From 7465fda7856859ec15c603e8c1ccc22b73719491 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 14 May 2026 23:01:15 +0000
Subject: [PATCH 01/82] release: v1.4.2-rc.2

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

diff --git a/package.json b/package.json
index 7e1366af82b..262e804eaa3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.2-rc.1",
+  "version": "1.4.2-rc.2",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From dcf5bf0dcee21f7e39f9e4b30632e71eb5cc2c43 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Thu, 14 May 2026 16:05:53 -0700
Subject: [PATCH 02/82] Clarify conflict details refresh state (#1875)

Co-authored-by: Orca <help@stably.ai>
---
 .../src/components/GitHubItemDialog.tsx       |  2 +-
 .../components/right-sidebar/ChecksPanel.tsx  | 22 ++++++--
 .../right-sidebar/SourceControl.tsx           |  2 +-
 .../checks-panel-content.test.tsx             | 54 +++++++++++++++++++
 ...s-helpers.tsx => checks-panel-content.tsx} | 14 ++++-
 5 files changed, 87 insertions(+), 7 deletions(-)
 create mode 100644 src/renderer/src/components/right-sidebar/checks-panel-content.test.tsx
 rename src/renderer/src/components/right-sidebar/{checks-helpers.tsx => checks-panel-content.tsx} (98%)

diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index 6f449118a9f..b8cd117d62e 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -50,7 +50,7 @@ import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
 import { detectLanguage } from '@/lib/language-detect'
 import { cn } from '@/lib/utils'
 import { buildDiffTree, type DiffTreeNode } from '@/components/pr-diff-tree'
-import { CHECK_COLOR, CHECK_ICON } from '@/components/right-sidebar/checks-helpers'
+import { CHECK_COLOR, CHECK_ICON } from '@/components/right-sidebar/checks-panel-content'
 import {
   filterPRCommentsByAudience,
   getPRCommentAudienceCounts,
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index 1e644af9a83..b401307d286 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -14,7 +14,7 @@ import {
   MergeConflictNotice,
   ChecksList,
   PRCommentsList
-} from './checks-helpers'
+} from './checks-panel-content'
 import { ENTRY_REFRESH_GRACE_MS, shouldEntryRefresh } from './checks-entry-refresh'
 import type { PRInfo, PRCheckDetail, PRComment } from '../../../../shared/types'
 
@@ -43,6 +43,7 @@ export default function ChecksPanel(): React.JSX.Element {
   const [commentsLoading, setCommentsLoading] = useState(false)
   const [emptyRefreshing, setEmptyRefreshing] = useState(false)
   const [isRefreshing, setIsRefreshing] = useState(false)
+  const [conflictDetailsRefreshing, setConflictDetailsRefreshing] = useState(false)
   const [editingTitle, setEditingTitle] = useState(false)
   const [titleDraft, setTitleDraft] = useState('')
   const [titleSaving, setTitleSaving] = useState(false)
@@ -67,6 +68,7 @@ export default function ChecksPanel(): React.JSX.Element {
     setTitleSaving(false)
     setIsRefreshing(false)
     setEmptyRefreshing(false)
+    setConflictDetailsRefreshing(false)
     conflictSummaryRefreshKeyRef.current = null
   }
 
@@ -108,6 +110,7 @@ export default function ChecksPanel(): React.JSX.Element {
   useEffect(() => {
     if (!repo || isFolder || !branch || !pr || pr.mergeable !== 'CONFLICTING') {
       conflictSummaryRefreshKeyRef.current = null
+      setConflictDetailsRefreshing(false)
       return
     }
 
@@ -121,7 +124,17 @@ export default function ChecksPanel(): React.JSX.Element {
     // them so we don't keep rendering cached branch summaries or empty file
     // lists from an older payload.
     conflictSummaryRefreshKeyRef.current = refreshKey
-    void fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR })
+    setConflictDetailsRefreshing(true)
+    void fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR }).finally(
+      () => {
+        // Why: fetchPRForBranch updates the PR cache before resolving, which
+        // can rerun this effect. Only the current refresh key may clear the
+        // spinner so stale requests don't race newer worktrees/branches.
+        if (conflictSummaryRefreshKeyRef.current === refreshKey) {
+          setConflictDetailsRefreshing(false)
+        }
+      }
+    )
   }, [repo, isFolder, branch, pr, linkedPR, fetchPRForBranch])
 
   // Fetch checks via cached store method
@@ -580,7 +593,10 @@ export default function ChecksPanel(): React.JSX.Element {
       </div>
 
       <ConflictingFilesSection pr={pr} />
-      <MergeConflictNotice pr={pr} />
+      <MergeConflictNotice
+        pr={pr}
+        isRefreshingConflictDetails={isRefreshing || conflictDetailsRefreshing}
+      />
       {/* Why: when the PR has merge conflicts and no checks have been fetched,
           showing "No checks configured" is misleading — checks may exist but
           simply cannot run until conflicts are resolved. Hide the empty state. */}
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index 0af146ae5dc..7047bf1e8d4 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -92,7 +92,7 @@ import {
   requestEditorSaveQuiesce
 } from '@/components/editor/editor-autosave'
 import { getConnectionId } from '@/lib/connection-context'
-import { PullRequestIcon } from './checks-helpers'
+import { PullRequestIcon } from './checks-panel-content'
 import type {
   DiffComment,
   GitBranchChangeEntry,
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
new file mode 100644
index 00000000000..1d8017fbf7e
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/checks-panel-content.test.tsx
@@ -0,0 +1,54 @@
+import React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+import type { PRInfo } from '../../../../shared/types'
+import { MergeConflictNotice } from './checks-panel-content'
+
+function makePR(overrides: Partial<PRInfo> = {}): PRInfo {
+  return {
+    number: 42,
+    title: 'Conflicting PR',
+    state: 'open',
+    url: 'https://github.com/acme/widgets/pull/42',
+    checksStatus: 'pending',
+    updatedAt: '2026-05-14T00:00:00Z',
+    mergeable: 'CONFLICTING',
+    ...overrides
+  }
+}
+
+function renderNotice(pr: PRInfo, isRefreshingConflictDetails = false): string {
+  return renderToStaticMarkup(
+    React.createElement(MergeConflictNotice, { pr, isRefreshingConflictDetails })
+  )
+}
+
+describe('MergeConflictNotice', () => {
+  it('does not claim conflict details are refreshing after the refresh has settled', () => {
+    const markup = renderNotice(makePR())
+
+    expect(markup).toContain('Conflict file details are unavailable')
+    expect(markup).not.toContain('Refreshing conflict details')
+  })
+
+  it('shows refreshing copy while conflict details are actively refreshing', () => {
+    const markup = renderNotice(makePR(), true)
+
+    expect(markup).toContain('Refreshing conflict details')
+  })
+
+  it('hides when the conflicting file list is available', () => {
+    const markup = renderNotice(
+      makePR({
+        conflictSummary: {
+          baseRef: 'main',
+          baseCommit: 'abc1234',
+          commitsBehind: 2,
+          files: ['src/conflict.ts']
+        }
+      })
+    )
+
+    expect(markup).toBe('')
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/checks-helpers.tsx b/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
similarity index 98%
rename from src/renderer/src/components/right-sidebar/checks-helpers.tsx
rename to src/renderer/src/components/right-sidebar/checks-panel-content.tsx
index b907dd7dff7..8dce022608d 100644
--- a/src/renderer/src/components/right-sidebar/checks-helpers.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
@@ -101,7 +101,13 @@ export function ConflictingFilesSection({ pr }: { pr: PRInfo }): React.JSX.Eleme
 }
 
 /** Fallback shown when GitHub reports merge conflicts but no file list is available yet. */
-export function MergeConflictNotice({ pr }: { pr: PRInfo }): React.JSX.Element | null {
+export function MergeConflictNotice({
+  pr,
+  isRefreshingConflictDetails
+}: {
+  pr: PRInfo
+  isRefreshingConflictDetails: boolean
+}): React.JSX.Element | null {
   if (pr.mergeable !== 'CONFLICTING' || (pr.conflictSummary?.files.length ?? 0) > 0) {
     return null
   }
@@ -111,7 +117,11 @@ export function MergeConflictNotice({ pr }: { pr: PRInfo }): React.JSX.Element |
       <div className="text-[11px] font-medium text-foreground">
         This branch has conflicts that must be resolved
       </div>
-      <div className="mt-1 text-[11px] text-muted-foreground">Refreshing conflict details…</div>
+      <div className="mt-1 text-[11px] text-muted-foreground">
+        {isRefreshingConflictDetails
+          ? 'Refreshing conflict details…'
+          : 'Conflict file details are unavailable'}
+      </div>
     </div>
   )
 }

From 2cadcbc4e1ffbda3f04dd0c6fbc02cd816f55ac2 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Thu, 14 May 2026 16:06:23 -0700
Subject: [PATCH 03/82] Support agent status hooks over SSH (#1865)

Co-authored-by: Orca <help@stably.ai>
---
 config/tsconfig.relay.json                    |   6 +-
 .../installer-utils-remote.test.ts            | 269 ++++++++++++
 .../agent-hooks/installer-utils-remote.ts     | 385 ++++++++++++++++++
 .../remote-hook-service-installers.test.ts    | 224 ++++++++++
 src/main/agent-hooks/server.ts                |  22 +-
 src/main/claude/hook-service.test.ts          | 166 ++++++++
 src/main/claude/hook-service.ts               |  87 +++-
 src/main/codex/config-toml-trust.ts           |  18 +-
 src/main/codex/hook-service.ts                | 106 ++++-
 src/main/cursor/hook-service.ts               |  77 +++-
 src/main/gemini/hook-service.ts               |  69 +++-
 src/main/ipc/pty.test.ts                      |   4 +
 src/main/pty/overlay-mirror.ts                |  12 +-
 src/main/pty/shell-startup-env.test.ts        |  19 +-
 src/main/pty/shell-startup-env.ts             |  90 ++--
 src/main/ssh/ssh-relay-session.test.ts        |  67 ++-
 src/main/ssh/ssh-relay-session.ts             |  80 +++-
 src/relay/agent-hook-server.ts                |  12 +-
 src/relay/plugin-overlay-env.test.ts          |  81 ++++
 src/relay/plugin-overlay-env.ts               |  35 ++
 src/relay/plugin-overlay.test.ts              | 186 +++++++++
 src/relay/plugin-overlay.ts                   | 276 +++++++++++++
 src/relay/plugin-source-limit.test.ts         |  24 ++
 src/relay/plugin-source-limit.ts              |  12 +
 src/relay/pty-handler.test.ts                 | 147 ++++++-
 src/relay/pty-handler.ts                      | 109 +++--
 src/relay/pty-shell-launch.test.ts            |  58 +++
 src/relay/pty-shell-launch.ts                 | 165 ++++++++
 src/relay/relay.ts                            | 110 ++++-
 src/shared/agent-hook-listener.ts             |   4 +-
 tests/e2e/ssh-localhost.spec.ts               |  67 ++-
 31 files changed, 2829 insertions(+), 158 deletions(-)
 create mode 100644 src/main/agent-hooks/installer-utils-remote.test.ts
 create mode 100644 src/main/agent-hooks/installer-utils-remote.ts
 create mode 100644 src/main/agent-hooks/remote-hook-service-installers.test.ts
 create mode 100644 src/main/claude/hook-service.test.ts
 create mode 100644 src/relay/plugin-overlay-env.test.ts
 create mode 100644 src/relay/plugin-overlay-env.ts
 create mode 100644 src/relay/plugin-overlay.test.ts
 create mode 100644 src/relay/plugin-overlay.ts
 create mode 100644 src/relay/plugin-source-limit.test.ts
 create mode 100644 src/relay/plugin-source-limit.ts
 create mode 100644 src/relay/pty-shell-launch.test.ts
 create mode 100644 src/relay/pty-shell-launch.ts

diff --git a/config/tsconfig.relay.json b/config/tsconfig.relay.json
index 247b9ac7476..242069f761c 100644
--- a/config/tsconfig.relay.json
+++ b/config/tsconfig.relay.json
@@ -1,6 +1,10 @@
 {
   "extends": "@electron-toolkit/tsconfig/tsconfig.node.json",
-  "include": ["../src/relay/**/*"],
+  "include": [
+    "../src/relay/**/*",
+    "../src/main/pty/overlay-mirror.ts",
+    "../src/main/pty/shell-startup-env.ts"
+  ],
   "exclude": ["../src/relay/integration.test.ts"],
   "compilerOptions": {
     "composite": true,
diff --git a/src/main/agent-hooks/installer-utils-remote.test.ts b/src/main/agent-hooks/installer-utils-remote.test.ts
new file mode 100644
index 00000000000..304ef4484ea
--- /dev/null
+++ b/src/main/agent-hooks/installer-utils-remote.test.ts
@@ -0,0 +1,269 @@
+import { describe, expect, it } from 'vitest'
+import type { SFTPWrapper } from 'ssh2'
+
+import {
+  readHooksJsonRemote,
+  writeHooksJsonRemote,
+  writeManagedScriptRemote,
+  writeTextFileRemoteAtomic
+} from './installer-utils-remote'
+
+type FakeFs = {
+  files: Map<string, string>
+  dirs: Set<string>
+  modes: Map<string, number>
+  openSshRenameCount: number
+}
+
+function createFakeSftp(
+  opts: {
+    plainRenameOverwrites?: boolean
+    openSshRename?: boolean
+    failDotFileWrites?: boolean
+  } = {}
+): {
+  sftp: SFTPWrapper
+  fs: FakeFs
+} {
+  const plainRenameOverwrites = opts.plainRenameOverwrites ?? true
+  const fs: FakeFs = {
+    files: new Map(),
+    dirs: new Set(['/']),
+    modes: new Map(),
+    openSshRenameCount: 0
+  }
+  const noEntryError = (path: string): { code: number; message: string } => ({
+    code: 2,
+    message: `ENOENT ${path}`
+  })
+  const fakeStats = (mode: number): { mode: number } => ({ mode })
+
+  const sftp = {
+    readFile: (path: string, _enc: string, cb: (err: unknown, data?: string) => void): void => {
+      const v = fs.files.get(path)
+      if (v === undefined) {
+        cb(noEntryError(path))
+        return
+      }
+      cb(null, v)
+    },
+    writeFile: (
+      path: string,
+      content: string,
+      options: string | { mode?: number },
+      cb: (err: unknown) => void
+    ): void => {
+      if (opts.failDotFileWrites && path.includes('/.')) {
+        cb({ code: 4, message: `write failed ${path}` })
+        return
+      }
+      fs.files.set(path, content)
+      if (typeof options !== 'string' && options.mode !== undefined) {
+        fs.modes.set(path, options.mode)
+      }
+      cb(null)
+    },
+    rename: (src: string, dst: string, cb: (err: unknown) => void): void => {
+      const v = fs.files.get(src)
+      if (v === undefined) {
+        cb(noEntryError(src))
+        return
+      }
+      if (!plainRenameOverwrites && fs.files.has(dst)) {
+        cb({ code: 4, message: `SSH_FX_FAILURE destination exists ${dst}` })
+        return
+      }
+      fs.files.set(dst, v)
+      fs.files.delete(src)
+      const mode = fs.modes.get(src)
+      if (mode !== undefined) {
+        fs.modes.set(dst, mode)
+        fs.modes.delete(src)
+      }
+      cb(null)
+    },
+    unlink: (path: string, cb: (err: unknown) => void): void => {
+      if (!fs.files.has(path)) {
+        cb(noEntryError(path))
+        return
+      }
+      fs.files.delete(path)
+      fs.modes.delete(path)
+      cb(null)
+    },
+    chmod: (path: string, mode: number, cb: (err: unknown) => void): void => {
+      fs.modes.set(path, mode)
+      cb(null)
+    },
+    stat: (path: string, cb: (err: unknown, stats?: { mode: number }) => void): void => {
+      if (!fs.files.has(path)) {
+        cb(noEntryError(path))
+        return
+      }
+      cb(null, fakeStats(fs.modes.get(path) ?? 0o100644))
+    },
+    readdir: (path: string, cb: (err: unknown, list?: { filename: string }[]) => void): void => {
+      if (fs.dirs.has(path)) {
+        cb(null, [])
+        return
+      }
+      cb(noEntryError(path))
+    },
+    mkdir: (path: string, cb: (err: unknown) => void): void => {
+      fs.dirs.add(path)
+      cb(null)
+    },
+    ...(opts.openSshRename
+      ? {
+          ext_openssh_rename: (src: string, dst: string, cb: (err: unknown) => void): void => {
+            fs.openSshRenameCount += 1
+            const v = fs.files.get(src)
+            if (v === undefined) {
+              cb(noEntryError(src))
+              return
+            }
+            fs.files.set(dst, v)
+            fs.files.delete(src)
+            const mode = fs.modes.get(src)
+            if (mode !== undefined) {
+              fs.modes.set(dst, mode)
+              fs.modes.delete(src)
+            }
+            cb(null)
+          }
+        }
+      : {})
+  } as unknown as SFTPWrapper
+  return { sftp, fs }
+}
+
+describe('installer-utils-remote', () => {
+  it('returns {} when settings.json does not exist on the remote', async () => {
+    const { sftp } = createFakeSftp()
+    const result = await readHooksJsonRemote(sftp, '/home/u/.claude/settings.json')
+    expect(result).toEqual({})
+  })
+
+  it('returns null when settings.json is malformed JSON', async () => {
+    const { sftp, fs } = createFakeSftp()
+    fs.files.set('/home/u/.claude/settings.json', 'not json {{')
+    const result = await readHooksJsonRemote(sftp, '/home/u/.claude/settings.json')
+    expect(result).toBeNull()
+  })
+
+  it('rethrows non-ENOENT read errors so callers can distinguish I/O failures from parse failures', async () => {
+    const sftp = {
+      readFile: (_path: string, _enc: string, cb: (err: unknown) => void): void => {
+        // Why: SSH_FX_PERMISSION_DENIED (3) is a real I/O failure that should
+        // not collapse into the same null result the parse-error path uses.
+        cb({ code: 3, message: 'permission denied' })
+      }
+    } as unknown as SFTPWrapper
+    await expect(readHooksJsonRemote(sftp, '/home/u/.claude/settings.json')).rejects.toMatchObject({
+      code: 3
+    })
+  })
+
+  it('atomically writes settings.json via tmp + rename', async () => {
+    const { sftp, fs } = createFakeSftp()
+    await writeHooksJsonRemote(sftp, '/home/u/.claude/settings.json', {
+      hooks: { Stop: [{ hooks: [{ type: 'command', command: 'foo' }] }] }
+    })
+    expect(fs.files.has('/home/u/.claude/settings.json')).toBe(true)
+    expect(fs.dirs.has('/home/u/.claude')).toBe(true)
+    const contents = fs.files.get('/home/u/.claude/settings.json')!
+    const parsed = JSON.parse(contents)
+    expect(parsed.hooks.Stop[0].hooks[0].command).toBe('foo')
+    // Tmp must be cleaned up.
+    const tmp = Array.from(fs.files.keys()).find((k) => k.includes('.tmp'))
+    expect(tmp).toBeUndefined()
+    expect(fs.modes.get('/home/u/.claude/settings.json')).toBe(0o600)
+  })
+
+  it('preserves existing config file mode across atomic replacement', async () => {
+    const { sftp, fs } = createFakeSftp()
+    const path = '/home/u/.codex/config.toml'
+    fs.files.set(path, 'old')
+    fs.modes.set(path, 0o640)
+
+    await writeTextFileRemoteAtomic(sftp, path, 'new')
+
+    expect(fs.modes.get(path)).toBe(0o640)
+  })
+
+  it('uses OpenSSH overwrite rename when an atomic write updates an existing file', async () => {
+    const { sftp, fs } = createFakeSftp({
+      plainRenameOverwrites: false,
+      openSshRename: true
+    })
+    const path = '/home/u/.claude/settings.json'
+    fs.files.set(path, JSON.stringify({ hooks: {} }))
+
+    await writeHooksJsonRemote(sftp, path, {
+      hooks: { Stop: [{ hooks: [{ type: 'command', command: 'new' }] }] }
+    })
+
+    expect(fs.openSshRenameCount).toBe(1)
+    expect(JSON.parse(fs.files.get(path)!).hooks.Stop[0].hooks[0].command).toBe('new')
+  })
+
+  it('leaves existing files intact when overwrite rename is unavailable', async () => {
+    const { sftp, fs } = createFakeSftp({ plainRenameOverwrites: false })
+    const path = '/home/u/.claude/settings.json'
+    fs.files.set(path, JSON.stringify({ hooks: { Stop: [] } }))
+
+    await expect(
+      writeHooksJsonRemote(sftp, path, {
+        hooks: { Stop: [{ hooks: [{ type: 'command', command: 'fallback' }] }] }
+      })
+    ).rejects.toMatchObject({ code: 4 })
+
+    expect(JSON.parse(fs.files.get(path)!).hooks.Stop).toEqual([])
+    expect(Array.from(fs.files.keys()).some((key) => key.includes('.tmp'))).toBe(false)
+  })
+
+  it('writes the managed script and chmods 0o755', async () => {
+    const { sftp, fs } = createFakeSftp()
+    await writeManagedScriptRemote(sftp, '/home/u/.orca/agent-hooks/claude-hook.sh', '#!/bin/sh\n')
+    expect(fs.files.get('/home/u/.orca/agent-hooks/claude-hook.sh')).toBe('#!/bin/sh\n')
+    expect(fs.modes.get('/home/u/.orca/agent-hooks/claude-hook.sh')).toBe(0o755)
+  })
+
+  it('replaces an existing managed script atomically via temp file rename', async () => {
+    const { sftp, fs } = createFakeSftp({
+      plainRenameOverwrites: false,
+      openSshRename: true
+    })
+    const path = '/home/u/.orca/agent-hooks/claude-hook.sh'
+    fs.files.set(path, 'old script')
+
+    await writeManagedScriptRemote(sftp, path, 'new script')
+
+    expect(fs.files.get(path)).toBe('new script')
+    expect(fs.modes.get(path)).toBe(0o755)
+    expect(Array.from(fs.files.keys()).some((key) => key.includes('.orca-backup-'))).toBe(false)
+  })
+
+  it('leaves the existing managed script intact when temp write fails', async () => {
+    const { sftp, fs } = createFakeSftp({ failDotFileWrites: true })
+    const path = '/home/u/.orca/agent-hooks/claude-hook.sh'
+    fs.files.set(path, 'old script')
+
+    await expect(writeManagedScriptRemote(sftp, path, 'new script')).rejects.toMatchObject({
+      code: 4
+    })
+    expect(fs.files.get(path)).toBe('old script')
+  })
+
+  it('skips a no-op write when contents already match', async () => {
+    const { sftp, fs } = createFakeSftp()
+    const path = '/home/u/.claude/settings.json'
+    await writeHooksJsonRemote(sftp, path, { hooks: {} })
+    const beforeKey = fs.files.get(path)
+    // Re-writing the same payload should produce the same content; there is
+    // no rename/tmp cycle visible to a downstream observer beyond the
+    // identical file body.
+    await writeHooksJsonRemote(sftp, path, { hooks: {} })
+    expect(fs.files.get(path)).toBe(beforeKey)
+  })
+})
diff --git a/src/main/agent-hooks/installer-utils-remote.ts b/src/main/agent-hooks/installer-utils-remote.ts
new file mode 100644
index 00000000000..63e10b45d5f
--- /dev/null
+++ b/src/main/agent-hooks/installer-utils-remote.ts
@@ -0,0 +1,385 @@
+// Why: SFTP-backed equivalents of `installer-utils.ts` for the remote-install
+// flow. Each function takes an `sftp` handle plus paths the agent CLI expects
+// on the remote (e.g. `~/.claude/settings.json`). Lives in `agent-hooks/`
+// because it shares the contract with the local installer (script body,
+// hook-event shape, atomic-rename semantics) and any drift between them is
+// exactly the bug we want to avoid.
+//
+// We deliberately keep the JSON merge logic in the existing
+// `installer-utils.ts` and only swap fs primitives — the JSON shape and
+// managed-command matching must stay identical to the local install.
+//
+// See docs/design/agent-status-over-ssh.md §8 (commit #8).
+
+import { randomUUID } from 'crypto'
+import type { SFTPWrapper, FileEntryWithStats } from 'ssh2'
+
+import { isPlainObject, type HooksConfig } from './installer-utils'
+
+const DEFAULT_REMOTE_CONFIG_MODE = 0o600
+
+/** Read+JSON-parse a remote file. Returns `null` on parse failure (caller
+ *  surfaces "could not parse" status to the UI), `{}` on missing file
+ *  (matches local behavior — first-install case). Rethrows on other I/O
+ *  failures (permission denied, EIO, channel closed) so the caller can
+ *  distinguish transient SFTP errors from a malformed-JSON case rather
+ *  than collapsing both into a misleading "could not parse" diagnostic. */
+export async function readHooksJsonRemote(
+  sftp: SFTPWrapper,
+  remotePath: string
+): Promise<HooksConfig | null> {
+  let body: string
+  try {
+    body = await readFile(sftp, remotePath)
+  } catch (err) {
+    if (isNoEntryError(err)) {
+      return {}
+    }
+    throw err
+  }
+  try {
+    const parsed = JSON.parse(body)
+    return isPlainObject(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** Atomically write a JSON config to the remote — write to a tmp path then
+ *  rename, mirroring the local writeHooksJson contract. The .bak rotation is
+ *  intentionally NOT carried over: the remote file is the user's, and a
+ *  per-target backup convention belongs alongside the remote installer UI
+ *  (out of scope for this commit). */
+export async function writeHooksJsonRemote(
+  sftp: SFTPWrapper,
+  remotePath: string,
+  config: HooksConfig
+): Promise<void> {
+  const dir = dirnamePosix(remotePath)
+  await mkdirpRemote(sftp, dir)
+  const serialized = `${JSON.stringify(config, null, 2)}\n`
+  // Why: skip the write when on-disk content is identical so repeated
+  // install() calls do not bump the file's mtime / inode unnecessarily.
+  try {
+    const existing = await readFile(sftp, remotePath)
+    if (existing === serialized) {
+      return
+    }
+  } catch {
+    // ENOENT or read error — fall through to the write below.
+  }
+  // Why: tmp + rename so a partial network drop mid-write does not leave a
+  // truncated settings.json that the agent CLI would refuse to load.
+  const tmp = `${dir}/.${Date.now()}-${randomUUID()}.tmp`
+  try {
+    const mode = await getRemoteFileModeOrDefault(sftp, remotePath, DEFAULT_REMOTE_CONFIG_MODE)
+    await writeFile(sftp, tmp, serialized, mode)
+    await chmod(sftp, tmp, mode)
+    await rename(sftp, tmp, remotePath)
+  } finally {
+    // Best-effort cleanup if rename failed.
+    try {
+      await unlink(sftp, tmp)
+    } catch {
+      // already gone or never created
+    }
+  }
+}
+
+/** Write the managed hook script to the remote and chmod 0o755. POSIX-only —
+ *  the relay deliberately does not support Windows-remote in v1 (see design
+ *  doc §3 + §6). */
+export async function writeManagedScriptRemote(
+  sftp: SFTPWrapper,
+  remotePath: string,
+  content: string
+): Promise<void> {
+  const dir = dirnamePosix(remotePath)
+  await mkdirpRemote(sftp, dir)
+  try {
+    const existing = await readFile(sftp, remotePath)
+    if (existing === content) {
+      await chmod(sftp, remotePath, 0o755)
+      return
+    }
+  } catch {
+    // ENOENT or read error — fall through to the atomic write below.
+  }
+
+  // Why: existing configs may already invoke this script. Write/chmod a temp
+  // file first, then rename it into place so interrupted reinstalls do not
+  // leave the configured hook path truncated or non-executable.
+  const tmp = `${dir}/.${Date.now()}-${randomUUID()}.tmp`
+  try {
+    await writeFile(sftp, tmp, content, 0o755)
+    await chmod(sftp, tmp, 0o755)
+    await rename(sftp, tmp, remotePath)
+  } finally {
+    try {
+      await unlink(sftp, tmp)
+    } catch {
+      // already gone or never created
+    }
+  }
+}
+
+export async function readTextFileRemote(
+  sftp: SFTPWrapper,
+  remotePath: string
+): Promise<string | null> {
+  try {
+    return await readFile(sftp, remotePath)
+  } catch (err) {
+    if (isNoEntryError(err)) {
+      return null
+    }
+    throw err
+  }
+}
+
+export async function writeTextFileRemoteAtomic(
+  sftp: SFTPWrapper,
+  remotePath: string,
+  content: string
+): Promise<void> {
+  const dir = dirnamePosix(remotePath)
+  await mkdirpRemote(sftp, dir)
+  try {
+    const existing = await readFile(sftp, remotePath)
+    if (existing === content) {
+      return
+    }
+  } catch {
+    // ENOENT or read error — fall through to the atomic write below.
+  }
+
+  const tmp = `${dir}/.${Date.now()}-${randomUUID()}.tmp`
+  try {
+    const mode = await getRemoteFileModeOrDefault(sftp, remotePath, DEFAULT_REMOTE_CONFIG_MODE)
+    await writeFile(sftp, tmp, content, mode)
+    await chmod(sftp, tmp, mode)
+    await rename(sftp, tmp, remotePath)
+  } finally {
+    try {
+      await unlink(sftp, tmp)
+    } catch {
+      // already gone or never created
+    }
+  }
+}
+
+// ─── Private SFTP primitives ────────────────────────────────────────
+
+async function readFile(sftp: SFTPWrapper, remotePath: string): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    sftp.readFile(remotePath, 'utf8', (err, data) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve(typeof data === 'string' ? data : data.toString('utf8'))
+    })
+  })
+}
+
+async function writeFile(
+  sftp: SFTPWrapper,
+  remotePath: string,
+  content: string,
+  mode?: number
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const options =
+      mode === undefined ? { encoding: 'utf8' as const } : { encoding: 'utf8' as const, mode }
+    sftp.writeFile(remotePath, content, options, (err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+}
+
+async function statMode(sftp: SFTPWrapper, remotePath: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    sftp.stat(remotePath, (err, stats) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve(stats.mode & 0o7777)
+    })
+  })
+}
+
+async function getRemoteFileModeOrDefault(
+  sftp: SFTPWrapper,
+  remotePath: string,
+  defaultMode: number
+): Promise<number> {
+  try {
+    return await statMode(sftp, remotePath)
+  } catch (err) {
+    if (isNoEntryError(err)) {
+      return defaultMode
+    }
+    throw err
+  }
+}
+
+async function rename(sftp: SFTPWrapper, src: string, dst: string): Promise<void> {
+  if (typeof sftp.ext_openssh_rename === 'function') {
+    try {
+      await renameOpenSsh(sftp, src, dst)
+      return
+    } catch (err) {
+      if (!isUnsupportedExtensionError(err)) {
+        throw err
+      }
+    }
+  }
+
+  // Why: servers without OpenSSH overwrite-rename cannot safely replace an
+  // existing live config path. Renaming dst aside would leave settings.json
+  // missing if the SFTP channel dies before src is moved into place, so fail
+  // closed and keep the existing file intact.
+  await renamePlain(sftp, src, dst)
+}
+
+async function renamePlain(sftp: SFTPWrapper, src: string, dst: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.rename(src, dst, (err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+}
+
+async function renameOpenSsh(sftp: SFTPWrapper, src: string, dst: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.ext_openssh_rename(src, dst, (err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+}
+
+async function unlink(sftp: SFTPWrapper, remotePath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.unlink(remotePath, (err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+}
+
+async function chmod(sftp: SFTPWrapper, remotePath: string, mode: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.chmod(remotePath, mode, (err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+}
+
+async function readdir(sftp: SFTPWrapper, remotePath: string): Promise<FileEntryWithStats[]> {
+  return new Promise((resolve, reject) => {
+    sftp.readdir(remotePath, (err, list) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve(list)
+    })
+  })
+}
+
+async function mkdir(sftp: SFTPWrapper, remotePath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.mkdir(remotePath, (err) => {
+      if (err) {
+        // SSH_FX_FAILURE (4) often means "already exists" on OpenSSH; we
+        // probe with stat afterwards rather than parse the error code.
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+}
+
+async function mkdirpRemote(sftp: SFTPWrapper, remotePath: string): Promise<void> {
+  if (remotePath === '/' || remotePath === '' || remotePath === '.') {
+    return
+  }
+  // Why: walk the path top-down rather than bottom-up so an existing parent
+  // chain doesn't cost a full readdir per segment. POSIX-only — Windows-
+  // remote is out of scope for v1.
+  const segments = remotePath.split('/').filter((s) => s.length > 0)
+  let current = remotePath.startsWith('/') ? '' : '.'
+  for (const seg of segments) {
+    current = current === '' ? `/${seg}` : current === '.' ? seg : `${current}/${seg}`
+    try {
+      await readdir(sftp, current)
+    } catch {
+      try {
+        await mkdir(sftp, current)
+      } catch (err) {
+        // Why: re-raise only when the dir really isn't there. SSH_FX_FAILURE
+        // on a concurrent mkdir from another client is harmless — readdir on
+        // the next iteration will succeed.
+        if (!isAlreadyExistsError(err)) {
+          throw err
+        }
+      }
+    }
+  }
+}
+
+function dirnamePosix(p: string): string {
+  const idx = p.lastIndexOf('/')
+  if (idx <= 0) {
+    return idx === 0 ? '/' : '.'
+  }
+  return p.slice(0, idx)
+}
+
+function isNoEntryError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') {
+    return false
+  }
+  // ssh2 surfaces SFTP errors with `code === 2` (SSH_FX_NO_SUCH_FILE).
+  return (err as { code?: unknown }).code === 2
+}
+
+function isAlreadyExistsError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') {
+    return false
+  }
+  // SSH_FX_FAILURE (4) is OpenSSH's catch-all for "exists" alongside other
+  // mkdir failures; we accept the ambiguity and let the next readdir prove
+  // success.
+  return (err as { code?: unknown }).code === 4
+}
+
+function isUnsupportedExtensionError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') {
+    return false
+  }
+  const code = (err as { code?: unknown }).code
+  const message = (err as { message?: unknown }).message
+  return code === 8 || (typeof message === 'string' && /unsupported/i.test(message))
+}
diff --git a/src/main/agent-hooks/remote-hook-service-installers.test.ts b/src/main/agent-hooks/remote-hook-service-installers.test.ts
new file mode 100644
index 00000000000..95db6b6ba95
--- /dev/null
+++ b/src/main/agent-hooks/remote-hook-service-installers.test.ts
@@ -0,0 +1,224 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { SFTPWrapper } from 'ssh2'
+
+vi.mock('electron', () => ({
+  app: {
+    getPath: () => '/tmp/orca-user-data'
+  }
+}))
+
+import { CodexHookService } from '../codex/hook-service'
+import { CursorHookService } from '../cursor/hook-service'
+import { GeminiHookService } from '../gemini/hook-service'
+import { ClaudeHookService } from '../claude/hook-service'
+
+type FakeFs = {
+  files: Map<string, string>
+  dirs: Set<string>
+  modes: Map<string, number>
+  failRenameTo: Set<string>
+}
+
+function createFakeSftp(): { sftp: SFTPWrapper; fs: FakeFs } {
+  const fs: FakeFs = {
+    files: new Map(),
+    dirs: new Set(['/']),
+    modes: new Map(),
+    failRenameTo: new Set()
+  }
+  const noEntryError = (path: string): { code: number; message: string } => ({
+    code: 2,
+    message: `ENOENT ${path}`
+  })
+  const fakeStats = (mode: number): { mode: number } => ({ mode })
+
+  const sftp = {
+    readFile: (path: string, _enc: string, cb: (err: unknown, data?: string) => void): void => {
+      const v = fs.files.get(path)
+      if (v === undefined) {
+        cb(noEntryError(path))
+        return
+      }
+      cb(null, v)
+    },
+    writeFile: (
+      path: string,
+      content: string,
+      options: string | { mode?: number },
+      cb: (err: unknown) => void
+    ): void => {
+      fs.files.set(path, content)
+      if (typeof options !== 'string' && options.mode !== undefined) {
+        fs.modes.set(path, options.mode)
+      }
+      cb(null)
+    },
+    rename: (src: string, dst: string, cb: (err: unknown) => void): void => {
+      if (fs.failRenameTo.has(dst)) {
+        cb({ code: 4, message: `rename failed ${dst}` })
+        return
+      }
+      const v = fs.files.get(src)
+      if (v === undefined) {
+        cb(noEntryError(src))
+        return
+      }
+      fs.files.set(dst, v)
+      fs.files.delete(src)
+      const mode = fs.modes.get(src)
+      if (mode !== undefined) {
+        fs.modes.set(dst, mode)
+        fs.modes.delete(src)
+      }
+      cb(null)
+    },
+    unlink: (path: string, cb: (err: unknown) => void): void => {
+      fs.files.delete(path)
+      fs.modes.delete(path)
+      cb(null)
+    },
+    chmod: (path: string, mode: number, cb: (err: unknown) => void): void => {
+      fs.modes.set(path, mode)
+      cb(null)
+    },
+    stat: (path: string, cb: (err: unknown, stats?: { mode: number }) => void): void => {
+      if (!fs.files.has(path)) {
+        cb(noEntryError(path))
+        return
+      }
+      cb(null, fakeStats(fs.modes.get(path) ?? 0o100644))
+    },
+    readdir: (path: string, cb: (err: unknown, list?: { filename: string }[]) => void): void => {
+      if (fs.dirs.has(path)) {
+        cb(null, [])
+        return
+      }
+      cb(noEntryError(path))
+    },
+    mkdir: (path: string, cb: (err: unknown) => void): void => {
+      fs.dirs.add(path)
+      cb(null)
+    }
+  } as unknown as SFTPWrapper
+  return { sftp, fs }
+}
+
+describe('remote hook service installers', () => {
+  it('always writes POSIX scripts for SSH remotes even from a Windows host', async () => {
+    const originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform')
+    Object.defineProperty(process, 'platform', { value: 'win32' })
+    try {
+      const installers = [
+        {
+          path: '/home/dev/.orca/agent-hooks/claude-hook.sh',
+          install: (sftp: SFTPWrapper) => new ClaudeHookService().installRemote(sftp, '/home/dev')
+        },
+        {
+          path: '/home/dev/.orca/agent-hooks/codex-hook.sh',
+          install: (sftp: SFTPWrapper) => new CodexHookService().installRemote(sftp, '/home/dev')
+        },
+        {
+          path: '/home/dev/.orca/agent-hooks/gemini-hook.sh',
+          install: (sftp: SFTPWrapper) => new GeminiHookService().installRemote(sftp, '/home/dev')
+        },
+        {
+          path: '/home/dev/.orca/agent-hooks/cursor-hook.sh',
+          install: (sftp: SFTPWrapper) => new CursorHookService().installRemote(sftp, '/home/dev')
+        }
+      ]
+
+      for (const { install, path } of installers) {
+        const { sftp, fs } = createFakeSftp()
+        const status = await install(sftp)
+        expect(status.state).toBe('installed')
+        const script = fs.files.get(path)
+        expect(script).toMatch(/^#!\/bin\/sh\n/)
+        expect(script).not.toContain('@echo off')
+        expect(script).not.toContain('powershell -NoProfile')
+      }
+    } finally {
+      if (originalPlatform) {
+        Object.defineProperty(process, 'platform', originalPlatform)
+      }
+    }
+  })
+
+  it('installs remote Codex hooks with matching trust entries', async () => {
+    const { sftp, fs } = createFakeSftp()
+
+    const status = await new CodexHookService().installRemote(sftp, '/home/dev/')
+
+    expect(status.state).toBe('installed')
+    expect(status.configPath).toBe('/home/dev/.codex/hooks.json')
+    const hooks = JSON.parse(fs.files.get('/home/dev/.codex/hooks.json')!) as {
+      hooks: Record<string, { hooks: { command: string }[] }[]>
+    }
+    for (const eventName of [
+      'SessionStart',
+      'UserPromptSubmit',
+      'PreToolUse',
+      'PermissionRequest',
+      'PostToolUse',
+      'Stop'
+    ]) {
+      const command = hooks.hooks[eventName]?.[0]?.hooks?.[0]?.command
+      expect(command).toContain('/home/dev/.orca/agent-hooks/codex-hook.sh')
+      expect(command).toMatch(/^if \[ -x /)
+    }
+    expect(fs.files.get('/home/dev/.orca/agent-hooks/codex-hook.sh')).toContain('#!/bin/sh')
+    expect(fs.modes.get('/home/dev/.orca/agent-hooks/codex-hook.sh')).toBe(0o755)
+    const toml = fs.files.get('/home/dev/.codex/config.toml')
+    expect(toml).toContain('/home/dev/.codex/hooks.json:permission_request:0:0')
+    expect(toml).toContain('trusted_hash = "sha256:')
+  })
+
+  it('reports Codex trust-write failures without rolling back installed hooks', async () => {
+    const { sftp, fs } = createFakeSftp()
+    fs.failRenameTo.add('/home/dev/.codex/config.toml')
+
+    const status = await new CodexHookService().installRemote(sftp, '/home/dev')
+
+    expect(status.state).toBe('error')
+    expect(status.managedHooksPresent).toBe(true)
+    expect(status.detail).toContain('trust entries could not be written')
+    expect(fs.files.get('/home/dev/.codex/hooks.json')).toContain('codex-hook.sh')
+    expect(fs.files.get('/home/dev/.orca/agent-hooks/codex-hook.sh')).toContain('#!/bin/sh')
+  })
+
+  it('installs remote Gemini and Cursor configs using their CLI-specific schemas', async () => {
+    const gemini = createFakeSftp()
+    const cursor = createFakeSftp()
+
+    await new GeminiHookService().installRemote(gemini.sftp, '/home/dev')
+    await new CursorHookService().installRemote(cursor.sftp, '/home/dev')
+
+    const geminiConfig = JSON.parse(gemini.fs.files.get('/home/dev/.gemini/settings.json')!) as {
+      hooks: Record<string, { hooks: { command: string }[] }[]>
+    }
+    for (const eventName of ['BeforeAgent', 'AfterAgent', 'AfterTool', 'PreToolUse']) {
+      const command = geminiConfig.hooks[eventName]?.[0]?.hooks?.[0]?.command
+      expect(command).toContain('/home/dev/.orca/agent-hooks/gemini-hook.sh')
+      expect(command).toMatch(/^if \[ -x /)
+    }
+
+    const cursorConfig = JSON.parse(cursor.fs.files.get('/home/dev/.cursor/hooks.json')!) as {
+      version: number
+      hooks: Record<string, { command?: string; hooks?: unknown[] }[]>
+    }
+    expect(cursorConfig.version).toBe(1)
+    for (const eventName of [
+      'beforeSubmitPrompt',
+      'stop',
+      'preToolUse',
+      'postToolUse',
+      'postToolUseFailure',
+      'beforeShellExecution',
+      'beforeMCPExecution',
+      'afterAgentResponse'
+    ]) {
+      const definition = cursorConfig.hooks[eventName]?.[0]
+      expect(definition?.command).toContain('/home/dev/.orca/agent-hooks/cursor-hook.sh')
+      expect(definition?.hooks).toBeUndefined()
+    }
+  })
+})
diff --git a/src/main/agent-hooks/server.ts b/src/main/agent-hooks/server.ts
index 241a0b2e8b1..cd715bcc598 100644
--- a/src/main/agent-hooks/server.ts
+++ b/src/main/agent-hooks/server.ts
@@ -709,6 +709,14 @@ export class AgentHookServer {
       }
     }
   }
+
+  /** Test-only accessor for the per-instance listener state. The `_internals`
+   *  shim needs to reach this without exposing `state` on the public surface
+   *  to renderer/main callers. AGENTS.md disallows `as unknown as X` escapes,
+   *  so we expose a narrow getter rather than casting the private field. */
+  _getStateForTests(): HookListenerState {
+    return this.state
+  }
 }
 
 export const agentHookServer = new AgentHookServer()
@@ -722,19 +730,9 @@ export const _internals = {
     body: unknown,
     expectedEnv: string
   ): AgentHookEventPayload | null =>
-    normalizeHookPayload(_singletonState(), source, body, expectedEnv),
+    normalizeHookPayload(agentHookServer._getStateForTests(), source, body, expectedEnv),
   parseFormEncodedBody,
   resetCachesForTests: (): void => {
-    clearAllListenerCaches(_singletonState())
+    clearAllListenerCaches(agentHookServer._getStateForTests())
   }
 }
-
-// Why: ergonomic accessor so the `_internals` shim can reach the singleton's
-// per-instance state without exposing `state` on the public class surface.
-function _singletonState(): HookListenerState {
-  // The runtime field is private, but tests access this module exclusively
-  // through `_internals`, which only fires after the module-level
-  // `agentHookServer` is constructed. The cast keeps the compile-time
-  // private invariant intact.
-  return (agentHookServer as unknown as { state: HookListenerState }).state
-}
diff --git a/src/main/claude/hook-service.test.ts b/src/main/claude/hook-service.test.ts
new file mode 100644
index 00000000000..00bfdc5cbe1
--- /dev/null
+++ b/src/main/claude/hook-service.test.ts
@@ -0,0 +1,166 @@
+// Why: locks in the remote-install contract so a refactor cannot silently
+// drift the produced settings.json shape, the wrapper-quoted command path,
+// or the script body that lands on the remote box. Local install behavior
+// is exercised through `installer-utils.test.ts` and the per-CLI status
+// audit; this file covers ONLY the SFTP-backed path added in commit #8.
+import { vi, describe, expect, it } from 'vitest'
+
+vi.mock('electron', () => ({
+  app: {
+    getPath: () => '/tmp/userData'
+  }
+}))
+
+import type { SFTPWrapper } from 'ssh2'
+import { ClaudeHookService } from './hook-service'
+
+type FakeFs = {
+  files: Map<string, string>
+  dirs: Set<string>
+  modes: Map<string, number>
+}
+
+function createFakeSftp(): { sftp: SFTPWrapper; fs: FakeFs } {
+  const fs: FakeFs = {
+    files: new Map(),
+    dirs: new Set(['/']),
+    modes: new Map()
+  }
+  const noEntryError = (path: string): { code: number; message: string } => ({
+    code: 2,
+    message: `ENOENT ${path}`
+  })
+  const fakeStats = (mode: number): { mode: number } => ({ mode })
+  const sftp = {
+    readFile: (path: string, _enc: string, cb: (err: unknown, data?: string) => void): void => {
+      const v = fs.files.get(path)
+      if (v === undefined) {
+        cb(noEntryError(path))
+        return
+      }
+      cb(null, v)
+    },
+    writeFile: (
+      path: string,
+      content: string,
+      options: string | { mode?: number },
+      cb: (err: unknown) => void
+    ): void => {
+      fs.files.set(path, content)
+      if (typeof options !== 'string' && options.mode !== undefined) {
+        fs.modes.set(path, options.mode)
+      }
+      cb(null)
+    },
+    rename: (src: string, dst: string, cb: (err: unknown) => void): void => {
+      const v = fs.files.get(src)
+      if (v === undefined) {
+        cb(noEntryError(src))
+        return
+      }
+      fs.files.set(dst, v)
+      fs.files.delete(src)
+      const mode = fs.modes.get(src)
+      if (mode !== undefined) {
+        fs.modes.set(dst, mode)
+        fs.modes.delete(src)
+      }
+      cb(null)
+    },
+    unlink: (path: string, cb: (err: unknown) => void): void => {
+      fs.files.delete(path)
+      fs.modes.delete(path)
+      cb(null)
+    },
+    chmod: (path: string, mode: number, cb: (err: unknown) => void): void => {
+      fs.modes.set(path, mode)
+      cb(null)
+    },
+    stat: (path: string, cb: (err: unknown, stats?: { mode: number }) => void): void => {
+      if (!fs.files.has(path)) {
+        cb(noEntryError(path))
+        return
+      }
+      cb(null, fakeStats(fs.modes.get(path) ?? 0o100644))
+    },
+    readdir: (path: string, cb: (err: unknown, list?: { filename: string }[]) => void): void => {
+      if (fs.dirs.has(path)) {
+        cb(null, [])
+        return
+      }
+      cb(noEntryError(path))
+    },
+    mkdir: (path: string, cb: (err: unknown) => void): void => {
+      fs.dirs.add(path)
+      cb(null)
+    }
+  } as unknown as SFTPWrapper
+  return { sftp, fs }
+}
+
+describe('ClaudeHookService.installRemote', () => {
+  it('writes settings.json + managed script under the remote $HOME', async () => {
+    const svc = new ClaudeHookService()
+    const { sftp, fs } = createFakeSftp()
+    const status = await svc.installRemote(sftp, '/home/dev')
+    expect(status.state).toBe('installed')
+    expect(status.configPath).toBe('/home/dev/.claude/settings.json')
+    const settings = fs.files.get('/home/dev/.claude/settings.json')
+    expect(settings).toBeTruthy()
+    const parsed = JSON.parse(settings!)
+    // Why: every load-bearing event must be present and point at the
+    // remote-shaped script path with the `if [ -x ... ]; then ... fi`
+    // wrapper applied. Drift in any of these is a real bug — Claude
+    // Code rejects unknown shapes silently and the agent-hooks pipeline
+    // goes dark.
+    for (const event of [
+      'UserPromptSubmit',
+      'Stop',
+      'PreToolUse',
+      'PostToolUse',
+      'PostToolUseFailure',
+      'PermissionRequest'
+    ]) {
+      expect(parsed.hooks[event]).toBeTruthy()
+      const cmd = parsed.hooks[event][0].hooks[0].command as string
+      expect(cmd).toContain('/home/dev/.orca/agent-hooks/claude-hook.sh')
+      expect(cmd).toMatch(/^if \[ -x /)
+    }
+    // Managed script body
+    expect(fs.files.get('/home/dev/.orca/agent-hooks/claude-hook.sh')).toContain('#!/bin/sh')
+    expect(fs.modes.get('/home/dev/.orca/agent-hooks/claude-hook.sh')).toBe(0o755)
+  })
+
+  it('reports parse error when remote settings.json is malformed', async () => {
+    const svc = new ClaudeHookService()
+    const { sftp, fs } = createFakeSftp()
+    fs.files.set('/home/dev/.claude/settings.json', 'not json')
+    const status = await svc.installRemote(sftp, '/home/dev')
+    expect(status.state).toBe('error')
+    expect(status.detail).toContain('Could not parse')
+  })
+
+  it('preserves user-authored hook entries on a fresh install', async () => {
+    const svc = new ClaudeHookService()
+    const { sftp, fs } = createFakeSftp()
+    fs.files.set(
+      '/home/dev/.claude/settings.json',
+      JSON.stringify({
+        hooks: {
+          Stop: [
+            {
+              hooks: [{ type: 'command', command: '/usr/local/bin/my-user-hook' }]
+            }
+          ]
+        }
+      })
+    )
+    await svc.installRemote(sftp, '/home/dev')
+    const parsed = JSON.parse(fs.files.get('/home/dev/.claude/settings.json')!)
+    // Original user-authored entry survives alongside the new managed entry.
+    const stopDefs = parsed.hooks.Stop as { hooks: { command: string }[] }[]
+    const userCmds = stopDefs.flatMap((d) => d.hooks.map((h) => h.command))
+    expect(userCmds).toContain('/usr/local/bin/my-user-hook')
+    expect(userCmds.some((c) => c.includes('claude-hook.sh'))).toBe(true)
+  })
+})
diff --git a/src/main/claude/hook-service.ts b/src/main/claude/hook-service.ts
index f2caf488104..d1d31db4438 100644
--- a/src/main/claude/hook-service.ts
+++ b/src/main/claude/hook-service.ts
@@ -1,5 +1,6 @@
 import { homedir } from 'os'
 import { join } from 'path'
+import type { SFTPWrapper } from 'ssh2'
 import type { AgentHookInstallState, AgentHookInstallStatus } from '../../shared/agent-hook-types'
 import {
   createManagedCommandMatcher,
@@ -11,6 +12,11 @@ import {
   writeManagedScript,
   type HookDefinition
 } from '../agent-hooks/installer-utils'
+import {
+  readHooksJsonRemote,
+  writeHooksJsonRemote,
+  writeManagedScriptRemote
+} from '../agent-hooks/installer-utils-remote'
 
 const CLAUDE_EVENTS = [
   { eventName: 'UserPromptSubmit', definition: { hooks: [{ type: 'command', command: '' }] } },
@@ -61,8 +67,8 @@ function getManagedCommand(scriptPath: string): string {
   return wrapPosixHookCommand(scriptPath)
 }
 
-function getManagedScript(): string {
-  if (process.platform === 'win32') {
+function getManagedScript(target: 'local' | 'posix' = 'local'): string {
+  if (target === 'local' && process.platform === 'win32') {
     return [
       '@echo off',
       'setlocal',
@@ -215,6 +221,83 @@ export class ClaudeHookService {
     return this.getStatus()
   }
 
+  // Why: install Orca's managed Claude hooks on the remote box rather than
+  // the local Mac/Linux machine. Caller passes the user's SFTP handle from
+  // the SshConnection plus the resolved remote `$HOME` (used to compute
+  // ~/.claude/settings.json on the target). POSIX-only by design — see
+  // docs/design/agent-status-over-ssh.md §3 / §6 (Windows-remote deferred).
+  async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
+    // Why: remote-Windows is out of scope for v1 — we ship POSIX-shaped paths
+    // (`~/.claude/settings.json`) and a `.sh` managed script body. The remote
+    // platform is gated by the relay's capability RPC at a higher layer; we
+    // cannot detect it from `process.platform` here (that's the local box).
+    const remoteConfigPath = `${remoteHome.replace(/\/$/, '')}/.claude/settings.json`
+    const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/claude-hook.sh`
+    // Why: SFTP reads/writes fail far more often than local fs (network drops,
+    // EACCES on remote dirs, disk full, channel closed). Wrap the entire
+    // install flow in try/catch so a transient I/O failure surfaces as a
+    // structured `state: 'error'` result for the UI, not an unstructured
+    // rejection the caller has to remember to handle. A `null` config
+    // specifically means "file present but unparseable" — keep that branch
+    // distinct so the user sees an actionable message.
+    try {
+      const config = await readHooksJsonRemote(sftp, remoteConfigPath)
+      if (!config) {
+        return {
+          agent: 'claude',
+          state: 'error',
+          configPath: remoteConfigPath,
+          managedHooksPresent: false,
+          detail: 'Could not parse remote Claude settings.json'
+        }
+      }
+
+      // Why: the POSIX wrapper is identical regardless of where the script
+      // lands; only the path differs. Reuse the same wrapper helper.
+      const command = wrapPosixHookCommand(remoteScriptPath)
+      const nextHooks = { ...config.hooks }
+      const isManagedCommand = createManagedCommandMatcher('claude-hook.sh')
+
+      for (const event of CLAUDE_EVENTS) {
+        const current = Array.isArray(nextHooks[event.eventName]) ? nextHooks[event.eventName] : []
+        const cleaned = removeManagedCommands(current, isManagedCommand)
+        const definition: HookDefinition = {
+          ...event.definition,
+          hooks: [{ type: 'command', command }]
+        }
+        nextHooks[event.eventName] = [...cleaned, definition]
+      }
+      config.hooks = nextHooks
+
+      // Why: write the script first, then the settings — settings.json
+      // referencing a missing script body would fire `command not found` on
+      // every tool call until the user re-runs install. Doing it in this
+      // order means a partial-failure mid-install at worst leaves the user
+      // with a working script no settings.json points at (a no-op), instead
+      // of broken settings.json.
+      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
+      // running on Windows; never derive remote script syntax from local OS.
+      await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
+      await writeHooksJsonRemote(sftp, remoteConfigPath, config)
+
+      return {
+        agent: 'claude',
+        state: 'installed',
+        configPath: remoteConfigPath,
+        managedHooksPresent: true,
+        detail: null
+      }
+    } catch (err) {
+      return {
+        agent: 'claude',
+        state: 'error',
+        configPath: remoteConfigPath,
+        managedHooksPresent: false,
+        detail: err instanceof Error ? err.message : String(err)
+      }
+    }
+  }
+
   remove(): AgentHookInstallStatus {
     const configPath = getConfigPath()
     const config = readHooksJson(configPath)
diff --git a/src/main/codex/config-toml-trust.ts b/src/main/codex/config-toml-trust.ts
index 1bd8594e8c9..179ce2572a0 100644
--- a/src/main/codex/config-toml-trust.ts
+++ b/src/main/codex/config-toml-trust.ts
@@ -190,16 +190,26 @@ export function upsertHookTrustEntries(
   entries: readonly CodexTrustEntry[]
 ): void {
   const existing = existsSync(configPath) ? readTomlFile(configPath) : ''
-  let updated = existing
-  for (const entry of entries) {
-    updated = upsertTrustBlock(updated, computeTrustKey(entry), computeTrustedHash(entry))
-  }
+  const updated = upsertHookTrustEntriesInContent(existing, entries)
   if (updated === existing) {
     return
   }
   writeConfigAtomically(configPath, updated)
 }
 
+export function upsertHookTrustEntriesInContent(
+  existingContent: string,
+  entries: readonly CodexTrustEntry[]
+): string {
+  const existing =
+    existingContent.charCodeAt(0) === 0xfeff ? existingContent.slice(1) : existingContent
+  let updated = existing
+  for (const entry of entries) {
+    updated = upsertTrustBlock(updated, computeTrustKey(entry), computeTrustedHash(entry))
+  }
+  return updated
+}
+
 // Why: build the canonical block we own. The two field names mirror what
 // Codex itself writes when the user approves via /hooks (HookStateToml
 // fields). `enabled` is plumbed through so an existing user-set
diff --git a/src/main/codex/hook-service.ts b/src/main/codex/hook-service.ts
index 6d54ff655c8..f7cada61a68 100644
--- a/src/main/codex/hook-service.ts
+++ b/src/main/codex/hook-service.ts
@@ -1,6 +1,7 @@
 /* eslint-disable max-lines -- Why: getStatus + install + remove all share the managed-command and trust-key derivation. Splitting would hide that the three operations must agree on group index, event label, and command bytes. */
 import { homedir } from 'os'
 import { join } from 'path'
+import type { SFTPWrapper } from 'ssh2'
 import type { AgentHookInstallState, AgentHookInstallStatus } from '../../shared/agent-hook-types'
 import {
   createManagedCommandMatcher,
@@ -12,12 +13,20 @@ import {
   writeManagedScript,
   type HookDefinition
 } from '../agent-hooks/installer-utils'
+import {
+  readHooksJsonRemote,
+  readTextFileRemote,
+  writeHooksJsonRemote,
+  writeManagedScriptRemote,
+  writeTextFileRemoteAtomic
+} from '../agent-hooks/installer-utils-remote'
 import {
   computeTrustKey,
   computeTrustedHash,
   parseTrustKey,
   readHookTrustEntries,
   removeHookTrustEntries,
+  upsertHookTrustEntriesInContent,
   upsertHookTrustEntries,
   type CodexEventLabel,
   type CodexHookTrustState,
@@ -71,8 +80,8 @@ function getManagedCommand(scriptPath: string): string {
   return process.platform === 'win32' ? scriptPath : wrapPosixHookCommand(scriptPath)
 }
 
-function getManagedScript(): string {
-  if (process.platform === 'win32') {
+function getManagedScript(target: 'local' | 'posix' = 'local'): string {
+  if (target === 'local' && process.platform === 'win32') {
     return [
       '@echo off',
       'setlocal',
@@ -329,6 +338,99 @@ export class CodexHookService {
     return this.getStatus()
   }
 
+  async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
+    const remoteConfigPath = `${remoteHome.replace(/\/$/, '')}/.codex/hooks.json`
+    const remoteTomlPath = `${remoteHome.replace(/\/$/, '')}/.codex/config.toml`
+    const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/codex-hook.sh`
+    try {
+      const config = await readHooksJsonRemote(sftp, remoteConfigPath)
+      if (!config) {
+        return {
+          agent: 'codex',
+          state: 'error',
+          configPath: remoteConfigPath,
+          managedHooksPresent: false,
+          detail: 'Could not parse remote Codex hooks.json'
+        }
+      }
+
+      const command = wrapPosixHookCommand(remoteScriptPath)
+      const nextHooks = { ...config.hooks }
+      const managedEvents = new Set<string>(CODEX_EVENTS)
+      const isManagedCommand = createManagedCommandMatcher('codex-hook.sh')
+
+      for (const [eventName, definitions] of Object.entries(nextHooks)) {
+        if (managedEvents.has(eventName) || !Array.isArray(definitions)) {
+          continue
+        }
+        const cleaned = removeManagedCommands(definitions, isManagedCommand)
+        if (cleaned.length === 0) {
+          delete nextHooks[eventName]
+        } else {
+          nextHooks[eventName] = cleaned
+        }
+      }
+
+      const trustEntries: CodexTrustEntry[] = []
+      for (const eventName of CODEX_EVENTS) {
+        const current = Array.isArray(nextHooks[eventName]) ? nextHooks[eventName] : []
+        const cleaned = removeManagedCommands(current, isManagedCommand)
+        const definition: HookDefinition = {
+          hooks: [{ type: 'command', command }]
+        }
+        nextHooks[eventName] = [...cleaned, definition]
+        trustEntries.push({
+          sourcePath: remoteConfigPath,
+          eventLabel: CODEX_EVENT_LABEL[eventName],
+          groupIndex: cleaned.length,
+          handlerIndex: 0,
+          command
+        })
+      }
+
+      config.hooks = nextHooks
+      // Why: script/settings first, trust TOML last. A partial trust write
+      // leaves Codex asking for approval rather than executing a missing script.
+      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
+      // running on Windows; never derive remote script syntax from local OS.
+      await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
+      await writeHooksJsonRemote(sftp, remoteConfigPath, config)
+      try {
+        const existingToml = (await readTextFileRemote(sftp, remoteTomlPath)) ?? ''
+        const updatedToml = upsertHookTrustEntriesInContent(existingToml, trustEntries)
+        if (updatedToml !== existingToml) {
+          await writeTextFileRemoteAtomic(sftp, remoteTomlPath, updatedToml)
+        }
+      } catch (error) {
+        return {
+          agent: 'codex',
+          state: 'error',
+          configPath: remoteConfigPath,
+          managedHooksPresent: true,
+          detail: `Hooks installed but trust entries could not be written: ${
+            error instanceof Error ? error.message : String(error)
+          }. Run /hooks in Codex on the remote host to approve.`
+        }
+      }
+
+      return {
+        agent: 'codex',
+        state: 'installed',
+        configPath: remoteConfigPath,
+        managedHooksPresent: true,
+        detail: null
+      }
+    } catch (err) {
+      return {
+        agent: 'codex',
+        state: 'error',
+        configPath: remoteConfigPath,
+        managedHooksPresent: false,
+        detail: err instanceof Error ? err.message : String(err)
+      }
+    }
+  }
+
   remove(): AgentHookInstallStatus {
     const configPath = getConfigPath()
     const config = readHooksJson(configPath)
diff --git a/src/main/cursor/hook-service.ts b/src/main/cursor/hook-service.ts
index 805a8d905db..ed7f7f3bd0a 100644
--- a/src/main/cursor/hook-service.ts
+++ b/src/main/cursor/hook-service.ts
@@ -1,5 +1,6 @@
 import { homedir } from 'os'
 import { join } from 'path'
+import type { SFTPWrapper } from 'ssh2'
 import type { AgentHookInstallState, AgentHookInstallStatus } from '../../shared/agent-hook-types'
 import {
   createManagedCommandMatcher,
@@ -11,6 +12,11 @@ import {
   writeManagedScript,
   type HookDefinition
 } from '../agent-hooks/installer-utils'
+import {
+  readHooksJsonRemote,
+  writeHooksJsonRemote,
+  writeManagedScriptRemote
+} from '../agent-hooks/installer-utils-remote'
 
 // Why: cursor-agent exposes a declarative hooks.json surface at
 // ~/.cursor/hooks.json (https://cursor.com/docs/hooks) with camelCase event
@@ -55,8 +61,8 @@ function getManagedCommand(scriptPath: string): string {
   return process.platform === 'win32' ? scriptPath : wrapPosixHookCommand(scriptPath)
 }
 
-function getManagedScript(): string {
-  if (process.platform === 'win32') {
+function getManagedScript(target: 'local' | 'posix' = 'local'): string {
+  if (target === 'local' && process.platform === 'win32') {
     return [
       '@echo off',
       'setlocal',
@@ -235,6 +241,73 @@ export class CursorHookService {
     return this.getStatus()
   }
 
+  // Why: install Orca's managed Cursor hooks on the remote box. Mirrors
+  // ClaudeHookService.installRemote — POSIX-only, uses the same SFTP-backed
+  // primitives, and emits Cursor's documented schema (top-level `command`
+  // on each definition + top-level `version: 1`) so cursor-agent on the
+  // remote actually invokes the script. See docs/design/agent-status-over-ssh.md
+  // §8.
+  async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
+    const remoteConfigPath = `${remoteHome.replace(/\/$/, '')}/.cursor/hooks.json`
+    const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/cursor-hook.sh`
+    try {
+      const config = await readHooksJsonRemote(sftp, remoteConfigPath)
+      if (!config) {
+        return {
+          agent: 'cursor',
+          state: 'error',
+          configPath: remoteConfigPath,
+          managedHooksPresent: false,
+          detail: 'Could not parse remote Cursor hooks.json'
+        }
+      }
+
+      const command = wrapPosixHookCommand(remoteScriptPath)
+      const nextHooks = { ...config.hooks }
+      const isManagedCommand = createManagedCommandMatcher('cursor-hook.sh')
+
+      for (const eventName of CURSOR_EVENTS) {
+        const current = Array.isArray(nextHooks[eventName]) ? nextHooks[eventName] : []
+        // Why: same dual-shape sweep as the local install — repeated
+        // installs converge on a single managed entry.
+        const cleaned = removeManagedCommands(current, isManagedCommand).filter(
+          (definition) => !isManagedCommand(definition.command as string | undefined)
+        )
+        const definition: HookDefinition = { command }
+        nextHooks[eventName] = [...cleaned, definition]
+      }
+
+      const nextConfig: Record<string, unknown> = { ...config, hooks: nextHooks }
+      if (nextConfig.version === undefined) {
+        nextConfig.version = 1
+      }
+
+      // Why: script-then-config order so a partial-failure mid-install at
+      // worst leaves a working script no settings.json points at — see
+      // ClaudeHookService.installRemote.
+      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
+      // running on Windows; never derive remote script syntax from local OS.
+      await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
+      await writeHooksJsonRemote(sftp, remoteConfigPath, nextConfig)
+
+      return {
+        agent: 'cursor',
+        state: 'installed',
+        configPath: remoteConfigPath,
+        managedHooksPresent: true,
+        detail: null
+      }
+    } catch (err) {
+      return {
+        agent: 'cursor',
+        state: 'error',
+        configPath: remoteConfigPath,
+        managedHooksPresent: false,
+        detail: err instanceof Error ? err.message : String(err)
+      }
+    }
+  }
+
   remove(): AgentHookInstallStatus {
     const configPath = getConfigPath()
     const config = readHooksJson(configPath)
diff --git a/src/main/gemini/hook-service.ts b/src/main/gemini/hook-service.ts
index 4cd0e401ab3..7b0d418ee71 100644
--- a/src/main/gemini/hook-service.ts
+++ b/src/main/gemini/hook-service.ts
@@ -1,5 +1,6 @@
 import { homedir } from 'os'
 import { join } from 'path'
+import type { SFTPWrapper } from 'ssh2'
 import type { AgentHookInstallState, AgentHookInstallStatus } from '../../shared/agent-hook-types'
 import {
   createManagedCommandMatcher,
@@ -11,6 +12,11 @@ import {
   writeManagedScript,
   type HookDefinition
 } from '../agent-hooks/installer-utils'
+import {
+  readHooksJsonRemote,
+  writeHooksJsonRemote,
+  writeManagedScriptRemote
+} from '../agent-hooks/installer-utils-remote'
 
 // Why: Gemini CLI fires `BeforeAgent` when a turn starts and `AfterAgent` when
 // it completes. `AfterTool` marks the resumption of model work after a tool
@@ -41,8 +47,8 @@ function getManagedCommand(scriptPath: string): string {
   return process.platform === 'win32' ? scriptPath : wrapPosixHookCommand(scriptPath)
 }
 
-function getManagedScript(): string {
-  if (process.platform === 'win32') {
+function getManagedScript(target: 'local' | 'posix' = 'local'): string {
+  if (target === 'local' && process.platform === 'win32') {
     return [
       '@echo off',
       'setlocal',
@@ -183,6 +189,65 @@ export class GeminiHookService {
     return this.getStatus()
   }
 
+  // Why: install Orca's managed Gemini hooks on the remote box. Mirrors
+  // ClaudeHookService.installRemote — POSIX-only, uses the same SFTP-backed
+  // primitives, and lays down the same script body the local install
+  // generates so a remote-side Gemini CLI behaves identically. See
+  // docs/design/agent-status-over-ssh.md §8.
+  async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
+    const remoteConfigPath = `${remoteHome.replace(/\/$/, '')}/.gemini/settings.json`
+    const remoteScriptPath = `${remoteHome.replace(/\/$/, '')}/.orca/agent-hooks/gemini-hook.sh`
+    try {
+      const config = await readHooksJsonRemote(sftp, remoteConfigPath)
+      if (!config) {
+        return {
+          agent: 'gemini',
+          state: 'error',
+          configPath: remoteConfigPath,
+          managedHooksPresent: false,
+          detail: 'Could not parse remote Gemini settings.json'
+        }
+      }
+
+      const command = wrapPosixHookCommand(remoteScriptPath)
+      const nextHooks = { ...config.hooks }
+      const isManagedCommand = createManagedCommandMatcher('gemini-hook.sh')
+
+      for (const eventName of GEMINI_EVENTS) {
+        const current = Array.isArray(nextHooks[eventName]) ? nextHooks[eventName] : []
+        const cleaned = removeManagedCommands(current, isManagedCommand)
+        const definition: HookDefinition = {
+          hooks: [{ type: 'command', command }]
+        }
+        nextHooks[eventName] = [...cleaned, definition]
+      }
+      config.hooks = nextHooks
+
+      // Why: write the script first so an interrupted install never leaves
+      // settings.json pointing at a missing script. See ClaudeHookService.
+      // Why: SSH remotes use POSIX `.sh` hook paths even when Orca itself is
+      // running on Windows; never derive remote script syntax from local OS.
+      await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
+      await writeHooksJsonRemote(sftp, remoteConfigPath, config)
+
+      return {
+        agent: 'gemini',
+        state: 'installed',
+        configPath: remoteConfigPath,
+        managedHooksPresent: true,
+        detail: null
+      }
+    } catch (err) {
+      return {
+        agent: 'gemini',
+        state: 'error',
+        configPath: remoteConfigPath,
+        managedHooksPresent: false,
+        detail: err instanceof Error ? err.message : String(err)
+      }
+    }
+  }
+
   remove(): AgentHookInstallStatus {
     const configPath = getConfigPath()
     const config = readHooksJson(configPath)
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 195685c90f2..1c5deb8d3cc 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -1277,6 +1277,9 @@ describe('registerPtyHandlers', () => {
           expect(env.ORCA_TAB_ID).toBeUndefined()
           expect(env.ORCA_WORKTREE_ID).toBeUndefined()
           expect(env.ORCA_AGENT_HOOK_TOKEN).toBeUndefined()
+          // Why: the local hook server's userData-relative endpoint file path
+          // is meaningless on the remote box; assert it does not leak.
+          expect(env.ORCA_AGENT_HOOK_ENDPOINT).toBeUndefined()
         } finally {
           if (prevFlag === undefined) {
             delete process.env.ORCA_FEATURE_REMOTE_AGENT_HOOKS
@@ -1336,6 +1339,7 @@ describe('registerPtyHandlers', () => {
           // relay is the source of truth for those.
           expect(env.ORCA_AGENT_HOOK_TOKEN).toBeUndefined()
           expect(env.ORCA_AGENT_HOOK_PORT).toBeUndefined()
+          expect(env.ORCA_AGENT_HOOK_ENDPOINT).toBeUndefined()
         } finally {
           if (prevFlag === undefined) {
             delete process.env.ORCA_FEATURE_REMOTE_AGENT_HOOKS
diff --git a/src/main/pty/overlay-mirror.ts b/src/main/pty/overlay-mirror.ts
index d529ac139b2..94e69071473 100644
--- a/src/main/pty/overlay-mirror.ts
+++ b/src/main/pty/overlay-mirror.ts
@@ -1,8 +1,8 @@
 // Why: Pi (PI_CODING_AGENT_DIR) and OpenCode (OPENCODE_CONFIG_DIR) both inject
 // Orca-owned files into per-PTY overlay directories that mirror a user-owned
-// source dir via symlinks/junctions. The safety guarantees here — never
+// source dir via symlinks/junctions. The safety guarantees here -- never
 // descend into a symlink/junction during teardown, refuse to operate outside
-// the overlay root, lstat-not-stat to avoid following links — are the result
+// the overlay root, lstat-not-stat to avoid following links -- are the result
 // of debugging issue #1083 (Windows directory junctions causing fs.rmSync to
 // delete the user's real Pi state). Shared in one module so a new overlay
 // consumer cannot accidentally diverge from the audited cleanup behavior.
@@ -42,7 +42,7 @@ export function mirrorEntry(sourcePath: string, targetPath: string): void {
 // Exported for tests. A "descend candidate" is an entry whose children we
 // should recurse into when tearing down the overlay. Anything that is a
 // symlink (including a Windows directory junction) must NOT be a candidate
-// even if it also reports isDirectory() — following it would walk into the
+// even if it also reports isDirectory() -- following it would walk into the
 // link target and delete user data, which is the bug in #1083.
 export function isSafeDescendCandidate(stats: {
   isSymbolicLink(): boolean
@@ -56,7 +56,7 @@ export function isSafeDescendCandidate(stats: {
 
 // Why: the overlay tree contains symlinks/junctions that point back into the
 // user's real state dir. fs.rmSync with { recursive: true } has repeatedly
-// regressed on Windows when walking NTFS junctions — it can follow them and
+// regressed on Windows when walking NTFS junctions -- it can follow them and
 // delete the *target*, destroying the user's data. Never descend into a
 // symlink/junction here: for any non-real-directory entry we unlink the link
 // itself; only entries that are truly directories on disk are recursed into.
@@ -70,7 +70,7 @@ export function safeRemoveTree(path: string): void {
 
   // On Windows, lstat on a directory junction can report BOTH
   // isSymbolicLink() === true AND isDirectory() === true, so we MUST check
-  // isSymbolicLink first — otherwise a junction enters the recursive branch
+  // isSymbolicLink first -- otherwise a junction enters the recursive branch
   // and readdirSync enumerates the link's target, the exact bug in #1083.
   if (!isSafeDescendCandidate(stat)) {
     try {
@@ -98,7 +98,7 @@ export function safeRemoveTree(path: string): void {
     try {
       unlinkSync(child)
     } catch {
-      // best-effort, see above
+      // Best-effort, see above.
     }
   }
 
diff --git a/src/main/pty/shell-startup-env.test.ts b/src/main/pty/shell-startup-env.test.ts
index 91418fd0809..d41e6c7fdcb 100644
--- a/src/main/pty/shell-startup-env.test.ts
+++ b/src/main/pty/shell-startup-env.test.ts
@@ -34,13 +34,17 @@ describe('readShellStartupEnvVar', () => {
   })
 
   function mockStartupFiles(files: Record<string, string>) {
+    const hasAbsoluteKeys = Object.keys(files).some((path) => path.startsWith('/'))
     existsSyncMock.mockImplementation((p: string) => {
       const file = p.split('/').pop() ?? ''
-      return file in files
+      return p in files || (!hasAbsoluteKeys && file in files)
     })
     readFileSyncMock.mockImplementation((p: string) => {
       const file = p.split('/').pop() ?? ''
-      if (file in files) {
+      if (p in files) {
+        return files[p]
+      }
+      if (!hasAbsoluteKeys && file in files) {
         return files[file]
       }
       throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' })
@@ -96,6 +100,17 @@ describe('readShellStartupEnvVar', () => {
     expect(readShellStartupEnvVar('OPENCODE_CONFIG_DIR', '/home/alice')).toBe('/newest/zlogin')
   })
 
+  it('uses ZDOTDIR exported from .zshenv for later zsh startup files', () => {
+    mockStartupFiles({
+      '/home/alice/.zshenv': 'export ZDOTDIR="$HOME/.config/zsh"\n',
+      '/home/alice/.config/zsh/.zshrc': 'export OPENCODE_CONFIG_DIR="$HOME/company/opencode"\n'
+    })
+
+    expect(readShellStartupEnvVar('OPENCODE_CONFIG_DIR', '/home/alice', '/bin/zsh')).toBe(
+      '/home/alice/company/opencode'
+    )
+  })
+
   it('handles double-quoted values', () => {
     mockStartupFiles({ '.zshrc': 'export OPENCODE_CONFIG_DIR="/quoted/path"\n' })
     expect(readShellStartupEnvVar('OPENCODE_CONFIG_DIR', '/home/alice')).toBe('/quoted/path')
diff --git a/src/main/pty/shell-startup-env.ts b/src/main/pty/shell-startup-env.ts
index fea07dd0f7f..96ba85aae6d 100644
--- a/src/main/pty/shell-startup-env.ts
+++ b/src/main/pty/shell-startup-env.ts
@@ -4,25 +4,62 @@ import { basename, join } from 'path'
 // Why: only files the user's actual shell would source. Mixing zsh and bash
 // files breaks the "last assignment wins matches the live shell" guarantee —
 // a stale .bash_profile on a zsh user would clobber the real .zshrc value.
-const ZSH_FILES = ['.zshenv', '.zprofile', '.zshrc', '.zlogin']
+const ZSH_ENV_FILE = '.zshenv'
+const ZSH_AFTER_ENV_FILES = ['.zprofile', '.zshrc', '.zlogin']
 // Why: Orca launches bash as a login shell (see local-pty-shell-ready.ts
 // getBashShellReadyRcfileContent and daemon/shell-ready.ts) which sources
 // .bash_profile / .bash_login / .profile but intentionally does NOT force
 // .bashrc. Scanning .bashrc would mirror values the live Orca bash never sees.
 const BASH_LOGIN_FILES = ['.bash_profile', '.bash_login', '.profile']
 
-function shellStartupFiles(shell: string | undefined): readonly string[] {
+function parseExportedValue(content: string, name: string, home: string): string | undefined {
+  const assignment = new RegExp(`^export\\s+${name}=(.+)$`)
+  let lastMatch: string | undefined
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    const match = assignment.exec(line)
+    if (!match?.[1]) {
+      continue
+    }
+    // Why: strip trailing unquoted `# comment` first so quoted values like
+    // `"$HOME/.opencode" # note` survive intact for unquoteShellValue.
+    const decommented = stripTrailingComment(match[1])
+    const { text, quoted } = unquoteShellValue(decommented)
+    // Why: $HOME / ${HOME} / ~ expansion mimics what the live shell would
+    // do for double-quoted and unquoted values; single-quoted is literal.
+    const expanded = quoted === "'" ? text : expandHome(text, home)
+    if (expanded.length > 0) {
+      lastMatch = expanded
+    }
+  }
+
+  return lastMatch
+}
+
+function readStartupFile(path: string): string | null {
+  if (!existsSync(path)) {
+    return null
+  }
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+function shellStartupFilePaths(home: string, shell: string | undefined): readonly string[] {
   if (!shell) {
     // Why: Orca's POSIX default shell is /bin/zsh when $SHELL is unset.
-    return ZSH_FILES
+    return zshStartupFilePaths(home)
   }
 
   const name = basename(shell).toLowerCase()
   if (name === 'zsh') {
-    return ZSH_FILES
+    return zshStartupFilePaths(home)
   }
   if (name === 'bash') {
-    return BASH_LOGIN_FILES
+    return BASH_LOGIN_FILES.map((file) => join(home, file))
   }
   // Why: unsupported explicit shells (fish, nushell, custom wrappers) do not
   // use Orca's zsh/bash shell-ready startup files, so scanning those files
@@ -30,6 +67,16 @@ function shellStartupFiles(shell: string | undefined): readonly string[] {
   return []
 }
 
+function zshStartupFilePaths(home: string): readonly string[] {
+  const zshEnvPath = join(home, ZSH_ENV_FILE)
+  const zshEnv = readStartupFile(zshEnvPath)
+  // Why: zsh sources ~/.zshenv first, then uses any ZDOTDIR exported there
+  // for .zprofile/.zshrc/.zlogin. Mirror that enough for static env discovery
+  // so users who keep zsh config in ~/.config/zsh do not lose overlay sources.
+  const zshDir = zshEnv ? (parseExportedValue(zshEnv, 'ZDOTDIR', home) ?? home) : home
+  return [zshEnvPath, ...ZSH_AFTER_ENV_FILES.map((file) => join(zshDir, file))]
+}
+
 function unquoteShellValue(value: string): { text: string; quoted: '"' | "'" | null } {
   const trimmed = value.trim()
   if (trimmed.length >= 2) {
@@ -118,38 +165,17 @@ export function readShellStartupEnvVar(
     return cache.get(cacheKey)
   }
 
-  const assignment = new RegExp(`^export\\s+${name}=(.+)$`)
   let lastMatch: string | undefined
 
-  for (const file of shellStartupFiles(shell)) {
-    const path = join(home, file)
-    if (!existsSync(path)) {
+  for (const path of shellStartupFilePaths(home, shell)) {
+    const content = readStartupFile(path)
+    if (content === null) {
       continue
     }
 
-    let content
-    try {
-      content = readFileSync(path, 'utf8')
-    } catch {
-      continue
-    }
-
-    for (const rawLine of content.split(/\r?\n/)) {
-      const line = rawLine.trim()
-      const match = assignment.exec(line)
-      if (!match?.[1]) {
-        continue
-      }
-      // Why: strip trailing unquoted `# comment` first so quoted values like
-      // `"$HOME/.opencode" # note` survive intact for unquoteShellValue.
-      const decommented = stripTrailingComment(match[1])
-      const { text, quoted } = unquoteShellValue(decommented)
-      // Why: $HOME / ${HOME} / ~ expansion mimics what the live shell would
-      // do for double-quoted and unquoted values; single-quoted is literal.
-      const expanded = quoted === "'" ? text : expandHome(text, home)
-      if (expanded.length > 0) {
-        lastMatch = expanded
-      }
+    const match = parseExportedValue(content, name, home)
+    if (match !== undefined) {
+      lastMatch = match
     }
   }
 
diff --git a/src/main/ssh/ssh-relay-session.test.ts b/src/main/ssh/ssh-relay-session.test.ts
index 48c248480e3..52660c51955 100644
--- a/src/main/ssh/ssh-relay-session.test.ts
+++ b/src/main/ssh/ssh-relay-session.test.ts
@@ -6,6 +6,11 @@ import { SshRelaySession } from './ssh-relay-session'
 import type { SshConnection } from './ssh-connection'
 import type { Store } from '../persistence'
 import type { SshPortForwardManager } from './ssh-port-forward'
+import { AGENT_HOOK_INSTALL_PLUGINS_METHOD } from '../../shared/agent-hook-relay'
+
+const { muxRequestMock } = vi.hoisted(() => ({
+  muxRequestMock: vi.fn()
+}))
 
 vi.mock('./ssh-relay-deploy', () => ({
   deployAndLaunchRelay: vi.fn()
@@ -15,7 +20,7 @@ vi.mock('./ssh-channel-multiplexer', () => {
   return {
     SshChannelMultiplexer: class MockSshChannelMultiplexer {
       notify = vi.fn()
-      request = vi.fn().mockResolvedValue([])
+      request = muxRequestMock
       onNotification = vi.fn().mockReturnValue(() => {})
       onDispose = vi.fn().mockReturnValue(() => {})
       dispose = vi.fn()
@@ -119,6 +124,9 @@ function mockDeploySuccess() {
 describe('SshRelaySession', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    delete process.env.ORCA_FEATURE_REMOTE_AGENT_HOOKS
+    muxRequestMock.mockReset()
+    muxRequestMock.mockResolvedValue([])
     mockDeploySuccess()
     vi.mocked(getPtyIdsForConnection).mockReturnValue([])
   })
@@ -143,6 +151,63 @@ describe('SshRelaySession', () => {
     expect(registerSshGitProvider).toHaveBeenCalledWith('target-1', expect.anything())
   })
 
+  it('syncs relay-owned plugin assets before registering the SSH PTY provider', async () => {
+    process.env.ORCA_FEATURE_REMOTE_AGENT_HOOKS = '1'
+    muxRequestMock.mockResolvedValue({ ok: true })
+    const sftp = { end: vi.fn() }
+    const { mockStore, mockPortForward, getMainWindow } = createMockDeps()
+    const mockConn = {
+      sftp: vi.fn().mockResolvedValue(sftp)
+    } as unknown as SshConnection
+    const session = new SshRelaySession('target-1', getMainWindow, mockStore, mockPortForward)
+
+    await session.establish(mockConn)
+
+    const installPluginsCallIndex = muxRequestMock.mock.calls.findIndex(
+      ([method]) => method === AGENT_HOOK_INSTALL_PLUGINS_METHOD
+    )
+    expect(installPluginsCallIndex).toBeGreaterThanOrEqual(0)
+    expect(muxRequestMock.mock.invocationCallOrder[installPluginsCallIndex]).toBeLessThan(
+      vi.mocked(registerSshPtyProvider).mock.invocationCallOrder[0]
+    )
+    // Why: connecting to SSH may upload relay-owned plugin source, but must
+    // not mutate user-owned agent config files. Remote managed-hook install
+    // belongs behind an explicit per-host user action.
+    expect(mockConn.sftp).not.toHaveBeenCalled()
+    expect(sftp.end).not.toHaveBeenCalled()
+  })
+
+  it('does not register providers if dispose wins during initial plugin sync', async () => {
+    process.env.ORCA_FEATURE_REMOTE_AGENT_HOOKS = '1'
+    let resolvePluginInstall!: () => void
+    muxRequestMock.mockImplementation(async (method: string) => {
+      if (method === AGENT_HOOK_INSTALL_PLUGINS_METHOD) {
+        return new Promise((resolve) => {
+          resolvePluginInstall = () => resolve({ ok: true })
+        })
+      }
+      return { ok: true }
+    })
+    const { mockStore, mockPortForward, getMainWindow } = createMockDeps()
+    const mockConn = {} as SshConnection
+    const session = new SshRelaySession('target-1', getMainWindow, mockStore, mockPortForward)
+
+    const establish = session.establish(mockConn)
+    await vi.waitFor(() =>
+      expect(muxRequestMock).toHaveBeenCalledWith(
+        AGENT_HOOK_INSTALL_PLUGINS_METHOD,
+        expect.anything()
+      )
+    )
+    session.dispose()
+    resolvePluginInstall()
+
+    await expect(establish).rejects.toThrow('Session disposed during establish')
+    expect(registerSshPtyProvider).not.toHaveBeenCalled()
+    expect(registerSshFilesystemProvider).not.toHaveBeenCalled()
+    expect(registerSshGitProvider).not.toHaveBeenCalled()
+  })
+
   it('rejects establish when not idle', async () => {
     const { mockConn, mockStore, mockPortForward, getMainWindow } = createMockDeps()
     const session = new SshRelaySession('target-1', getMainWindow, mockStore, mockPortForward)
diff --git a/src/main/ssh/ssh-relay-session.ts b/src/main/ssh/ssh-relay-session.ts
index 61074ed65ea..d75807f86ce 100644
--- a/src/main/ssh/ssh-relay-session.ts
+++ b/src/main/ssh/ssh-relay-session.ts
@@ -18,10 +18,13 @@ import { SshFilesystemProvider } from '../providers/ssh-filesystem-provider'
 import { SshGitProvider } from '../providers/ssh-git-provider'
 import { agentHookServer } from '../agent-hooks/server'
 import {
+  AGENT_HOOK_INSTALL_PLUGINS_METHOD,
   AGENT_HOOK_NOTIFICATION_METHOD,
   AGENT_HOOK_REQUEST_REPLAY_METHOD,
   isRemoteAgentHooksEnabled
 } from '../../shared/agent-hook-relay'
+import { _internals as openCodeInternals } from '../opencode/hook-service'
+import { getPiAgentStatusExtensionSource } from '../pi/agent-status-extension-source'
 import {
   registerSshPtyProvider,
   unregisterSshPtyProvider,
@@ -52,6 +55,11 @@ export class SshRelaySession {
   private mux: SshChannelMultiplexer | null = null
   private abortController: AbortController | null = null
   private muxDisposeCleanup: (() => void) | null = null
+  // Why: store the notification-handler disposer so teardownProviders can
+  // release it on reconnect/shutdown. Symmetric with muxDisposeCleanup; while
+  // the old mux's handler array is GC'd along with the mux today, holding the
+  // disposer is cheap insurance against future code that retains the old mux.
+  private muxNotificationCleanup: (() => void) | null = null
   // Why: when the relay exec channel closes but the SSH connection stays
   // up, the onStateChange reconnect path never fires. This callback lets
   // ssh.ts wire up relay-level reconnect from outside the session.
@@ -152,7 +160,13 @@ export class SshRelaySession {
       // here fails fast so doConnect() can report the real error.
       await mux.request('session.resolveHome', { path: '~' })
 
-      await this.registerProviders(mux)
+      const registered = await this.registerProviders(mux, ownsAttempt)
+      if (!registered) {
+        if (!mux.isDisposed()) {
+          mux.dispose()
+        }
+        throw new Error('Session disposed during establish')
+      }
 
       // Why: the mux's transport can close during registerProviders (e.g.
       // the --connect bridge exits). registerRelayRoots swallows mux errors
@@ -405,6 +419,11 @@ export class SshRelaySession {
       return false
     }
 
+    await this.installPluginsOnRelay(mux)
+    if (shouldContinue && !shouldContinue()) {
+      return false
+    }
+
     const ptyProvider = new SshPtyProvider(this.targetId, mux)
     registerSshPtyProvider(this.targetId, ptyProvider)
 
@@ -419,6 +438,47 @@ export class SshRelaySession {
     return true
   }
 
+  // Why: ship the OpenCode plugin / Pi extension source bodies to the relay
+  // so it can materialize per-PTY overlay dirs and inject OPENCODE_CONFIG_DIR
+  // / PI_CODING_AGENT_DIR into spawn env. The strings change as we add agent
+  // events (recent additions: cursor, pi); pinning them to the relay binary
+  // would force a relay redeploy on every Orca update. See
+  // docs/design/agent-status-over-ssh.md §4 + §8 (commit #7).
+  //
+  // Best-effort: a -32601 from an older relay (no handler installed) is
+  // swallowed; the user just doesn't get OpenCode/Pi status reporting until
+  // they upgrade. Hook-script-based agents use a separate explicit remote
+  // installer flow because that mutates user-owned agent config files.
+  private async installPluginsOnRelay(mux: SshChannelMultiplexer): Promise<void> {
+    if (!isRemoteAgentHooksEnabled()) {
+      return
+    }
+    try {
+      await mux.request(AGENT_HOOK_INSTALL_PLUGINS_METHOD, {
+        opencodePluginSource: openCodeInternals.getOpenCodePluginSource(),
+        piExtensionSource: getPiAgentStatusExtensionSource()
+      })
+    } catch (err) {
+      // Why: -32601 = older relay without the handler (treat as soft skip).
+      // CONNECTION_LOST / DISPOSED come from the multiplexer when it tears
+      // down mid-flight (routine on session shutdown / reconnect race) — not
+      // a real failure to surface; suppress to avoid log spam on every clean
+      // disconnect.
+      const code = (err as { code?: unknown })?.code
+      if (code === -32601 || code === 'CONNECTION_LOST' || code === 'DISPOSED') {
+        return
+      }
+      if (mux.isDisposed()) {
+        return
+      }
+      console.warn(
+        `[ssh-relay-session] agent_hook.installPlugins failed for ${this.targetId}: ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      )
+    }
+  }
+
   // Why: route the relay's `agent.hook` JSON-RPC notification into Orca's
   // shared `agentHookServer` via `ingestRemote`. The wire envelope carries
   // `connectionId: null` (the relay does not know Orca's local handle); we
@@ -433,7 +493,13 @@ export class SshRelaySession {
     if (!isRemoteAgentHooksEnabled()) {
       return
     }
-    mux.onNotification((method, params) => {
+    // Why: capture the disposer so teardownProviders can release the
+    // notification handler symmetrically with muxDisposeCleanup. Even though
+    // the disposed mux's handler array is GC'd along with it today, retaining
+    // the disposer makes "registerProviders called twice on the same mux"
+    // safe by future-proofing against duplicate handler registration.
+    this.muxNotificationCleanup?.()
+    this.muxNotificationCleanup = mux.onNotification((method, params) => {
       if (method !== AGENT_HOOK_NOTIFICATION_METHOD) {
         return
       }
@@ -470,10 +536,14 @@ export class SshRelaySession {
     // *after* the handler is wired so the request-driven replay shape
     // strictly trails our subscription on the dispatcher's single write
     // callback. Best-effort: a relay that does not know the method
-    // (e.g. older relay binary) returns -32601, which we swallow.
+    // (e.g. older relay binary) returns -32601; CONNECTION_LOST / DISPOSED
+    // arise from mux teardown mid-flight on routine reconnect/shutdown.
     void mux.request(AGENT_HOOK_REQUEST_REPLAY_METHOD).catch((err) => {
       const code = (err as { code?: unknown })?.code
-      if (code === -32601) {
+      if (code === -32601 || code === 'CONNECTION_LOST' || code === 'DISPOSED') {
+        return
+      }
+      if (mux.isDisposed()) {
         return
       }
       // Why: a normal disconnect/teardown rejects the in-flight request with
@@ -493,6 +563,8 @@ export class SshRelaySession {
   private teardownProviders(reason: 'shutdown' | 'connection_lost'): void {
     this.muxDisposeCleanup?.()
     this.muxDisposeCleanup = null
+    this.muxNotificationCleanup?.()
+    this.muxNotificationCleanup = null
     if (this.mux && !this.mux.isDisposed()) {
       this.mux.dispose(reason)
     }
diff --git a/src/relay/agent-hook-server.ts b/src/relay/agent-hook-server.ts
index 7865d018b54..f2fc8e5d267 100644
--- a/src/relay/agent-hook-server.ts
+++ b/src/relay/agent-hook-server.ts
@@ -106,6 +106,11 @@ export class RelayAgentHookServer {
     await new Promise<void>((resolve, reject) => {
       const onStartupError = (err: Error): void => {
         this.server?.off('listening', onListening)
+        // Why: null the server reference on bind failure so a subsequent
+        // start() can retry. Without this, a failed bind (e.g. EMFILE) leaves
+        // this.server populated and the early-return at the top of start()
+        // wedges the relay into a permanently broken state until stop() runs.
+        this.server = null
         reject(err)
       }
       const onListening = (): void => {
@@ -234,9 +239,14 @@ export class RelayAgentHookServer {
       }
       res.writeHead(204)
       res.end()
-    } catch {
+    } catch (err) {
       // Why: agent hooks must fail open — return success on parse / size /
       // timeout errors so a buggy agent script never blocks the agent run.
+      // Log the swallowed error to stderr so future programmer bugs are not
+      // invisible (the 204 response would otherwise mask them entirely).
+      process.stderr.write(
+        `[relay-hook-server] hook request failed: ${err instanceof Error ? err.message : String(err)}\n`
+      )
       res.writeHead(204)
       res.end()
     }
diff --git a/src/relay/plugin-overlay-env.test.ts b/src/relay/plugin-overlay-env.test.ts
new file mode 100644
index 00000000000..d23a767692b
--- /dev/null
+++ b/src/relay/plugin-overlay-env.test.ts
@@ -0,0 +1,81 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { __resetShellStartupEnvCache } from '../main/pty/shell-startup-env'
+import { resolveOpenCodeSourceConfigDir, resolvePiSourceAgentDir } from './plugin-overlay-env'
+
+describe('plugin overlay env source resolution', () => {
+  let homeDir: string
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), 'relay-plugin-overlay-env-'))
+    __resetShellStartupEnvCache()
+  })
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true })
+    __resetShellStartupEnvCache()
+  })
+
+  it.skipIf(process.platform === 'win32')(
+    'uses zsh startup exports before inherited public overlay env',
+    () => {
+      mkdirSync(join(homeDir, 'company-opencode'), { recursive: true })
+      mkdirSync(join(homeDir, 'company-pi'), { recursive: true })
+      writeFileSync(
+        join(homeDir, '.zshrc'),
+        [
+          'export OPENCODE_CONFIG_DIR="$HOME/company-opencode"',
+          'export PI_CODING_AGENT_DIR="$HOME/company-pi"'
+        ].join('\n')
+      )
+
+      const env = {
+        HOME: homeDir,
+        OPENCODE_CONFIG_DIR: '/tmp/inherited-opencode-overlay',
+        PI_CODING_AGENT_DIR: '/tmp/inherited-pi-overlay'
+      }
+
+      expect(resolveOpenCodeSourceConfigDir(env, '/bin/zsh')).toBe(
+        join(homeDir, 'company-opencode')
+      )
+      expect(resolvePiSourceAgentDir(env, '/bin/zsh')).toBe(join(homeDir, 'company-pi'))
+    }
+  )
+
+  it.skipIf(process.platform === 'win32')(
+    'discovers overlay sources from a custom zsh ZDOTDIR',
+    () => {
+      const zshDir = join(homeDir, '.config', 'zsh')
+      mkdirSync(zshDir, { recursive: true })
+      writeFileSync(join(homeDir, '.zshenv'), 'export ZDOTDIR="$HOME/.config/zsh"\n')
+      writeFileSync(join(zshDir, '.zshrc'), 'export OPENCODE_CONFIG_DIR="$HOME/opencode-src"\n')
+
+      expect(
+        resolveOpenCodeSourceConfigDir(
+          {
+            HOME: homeDir,
+            OPENCODE_CONFIG_DIR: '/tmp/inherited-opencode-overlay'
+          },
+          '/bin/zsh'
+        )
+      ).toBe(join(homeDir, 'opencode-src'))
+    }
+  )
+
+  it('keeps explicit original-source env ahead of startup hints', () => {
+    writeFileSync(join(homeDir, '.zshrc'), 'export OPENCODE_CONFIG_DIR="$HOME/company-opencode"\n')
+
+    expect(
+      resolveOpenCodeSourceConfigDir(
+        {
+          HOME: homeDir,
+          ORCA_OPENCODE_SOURCE_CONFIG_DIR: '/remote/original-opencode',
+          OPENCODE_CONFIG_DIR: '/tmp/inherited-opencode-overlay'
+        },
+        '/bin/zsh'
+      )
+    ).toBe('/remote/original-opencode')
+  })
+})
diff --git a/src/relay/plugin-overlay-env.ts b/src/relay/plugin-overlay-env.ts
new file mode 100644
index 00000000000..431a49430f1
--- /dev/null
+++ b/src/relay/plugin-overlay-env.ts
@@ -0,0 +1,35 @@
+import { readShellStartupEnvVar } from '../main/pty/shell-startup-env'
+
+function firstNonEmpty(...values: (string | undefined)[]): string | undefined {
+  return values.find((value) => typeof value === 'string' && value.length > 0)
+}
+
+function readStartupEnv(
+  name: string,
+  env: Record<string, string>,
+  shell: string | undefined
+): string | undefined {
+  return readShellStartupEnvVar(name, env.HOME ?? process.env.HOME, shell ?? env.SHELL)
+}
+
+export function resolveOpenCodeSourceConfigDir(
+  env: Record<string, string>,
+  shell: string | undefined
+): string | undefined {
+  return firstNonEmpty(
+    env.ORCA_OPENCODE_SOURCE_CONFIG_DIR,
+    readStartupEnv('OPENCODE_CONFIG_DIR', env, shell),
+    env.OPENCODE_CONFIG_DIR
+  )
+}
+
+export function resolvePiSourceAgentDir(
+  env: Record<string, string>,
+  shell: string | undefined
+): string | undefined {
+  return firstNonEmpty(
+    env.ORCA_PI_SOURCE_AGENT_DIR,
+    readStartupEnv('PI_CODING_AGENT_DIR', env, shell),
+    env.PI_CODING_AGENT_DIR
+  )
+}
diff --git a/src/relay/plugin-overlay.test.ts b/src/relay/plugin-overlay.test.ts
new file mode 100644
index 00000000000..5d7a7f03c33
--- /dev/null
+++ b/src/relay/plugin-overlay.test.ts
@@ -0,0 +1,186 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from 'fs'
+import { tmpdir } from 'os'
+import { basename, join } from 'path'
+import { PluginOverlayManager } from './plugin-overlay'
+
+describe('PluginOverlayManager', () => {
+  let homeDir: string
+  let manager: PluginOverlayManager
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), 'plugin-overlay-'))
+    manager = new PluginOverlayManager({ homeDir })
+  })
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true })
+  })
+
+  it('reports no source until install runs', () => {
+    expect(manager.hasOpenCodeSource()).toBe(false)
+    expect(manager.hasPiSource()).toBe(false)
+    expect(manager.materializeOpenCode('tab-1:0')).toBeNull()
+    expect(manager.materializePi('tab-1:0')).toBeNull()
+  })
+
+  it('materializes OpenCode plugin into <overlay>/plugins/<file>', () => {
+    manager.setSources({ opencodePluginSource: 'export const X = 1' })
+    const dir = manager.materializeOpenCode('tab-1:0')
+    expect(dir).not.toBeNull()
+    const expected = join(dir!, 'plugins', 'orca-opencode-status.js')
+    expect(existsSync(expected)).toBe(true)
+    expect(readFileSync(expected, 'utf8')).toBe('export const X = 1')
+  })
+
+  it('mirrors a preexisting remote OpenCode config dir before adding Orca plugin', () => {
+    const userConfigDir = join(homeDir, 'company-opencode')
+    mkdirSync(join(userConfigDir, 'plugins'), { recursive: true })
+    writeFileSync(join(userConfigDir, 'opencode.json'), '{"provider":"custom"}')
+    writeFileSync(join(userConfigDir, 'plugins', 'user-plugin.js'), 'user plugin')
+    writeFileSync(join(userConfigDir, 'plugins', 'orca-opencode-status.js'), 'user same-name')
+
+    manager.setSources({ opencodePluginSource: 'orca plugin' })
+    const dir = manager.materializeOpenCode('tab-opencode:0', userConfigDir)
+
+    expect(dir).not.toBeNull()
+    expect(readFileSync(join(dir!, 'opencode.json'), 'utf8')).toBe('{"provider":"custom"}')
+    expect(readFileSync(join(dir!, 'plugins', 'user-plugin.js'), 'utf8')).toBe('user plugin')
+    expect(readFileSync(join(dir!, 'plugins', 'orca-opencode-status.js'), 'utf8')).toBe(
+      'orca plugin'
+    )
+    expect(readFileSync(join(userConfigDir, 'plugins', 'orca-opencode-status.js'), 'utf8')).toBe(
+      'user same-name'
+    )
+  })
+
+  it('does not override a missing preexisting OpenCode config dir', () => {
+    manager.setSources({ opencodePluginSource: 'orca plugin' })
+
+    expect(manager.materializeOpenCode('tab-missing:0', join(homeDir, 'missing'))).toBeNull()
+  })
+
+  it('materializes Pi extension into <overlay>/extensions/<file>', () => {
+    manager.setSources({ piExtensionSource: '// pi extension' })
+    const dir = manager.materializePi('tab-2:0')
+    expect(dir).not.toBeNull()
+    const file = join(dir!, 'extensions', 'orca-agent-status.ts')
+    expect(existsSync(file)).toBe(true)
+  })
+
+  it('mirrors the remote default Pi agent dir before adding Orca status extension', () => {
+    const piAgentDir = join(homeDir, '.pi', 'agent')
+    mkdirSync(join(piAgentDir, 'skills', 'my-skill'), { recursive: true })
+    mkdirSync(join(piAgentDir, 'extensions', 'user-ext'), { recursive: true })
+    writeFileSync(join(piAgentDir, 'auth.json'), 'secret token')
+    writeFileSync(join(piAgentDir, 'skills', 'my-skill', 'SKILL.md'), 'critical user skill')
+    writeFileSync(join(piAgentDir, 'extensions', 'user-ext', 'ext.ts'), 'user extension')
+
+    manager.setSources({ piExtensionSource: '// pi extension' })
+    const dir = manager.materializePi('tab-pi:0')
+
+    expect(dir).not.toBeNull()
+    expect(readFileSync(join(dir!, 'auth.json'), 'utf8')).toBe('secret token')
+    expect(readFileSync(join(dir!, 'skills', 'my-skill', 'SKILL.md'), 'utf8')).toBe(
+      'critical user skill'
+    )
+    expect(readFileSync(join(dir!, 'extensions', 'user-ext', 'ext.ts'), 'utf8')).toBe(
+      'user extension'
+    )
+    expect(readdirSync(join(dir!, 'extensions')).sort()).toEqual([
+      'orca-agent-status.ts',
+      'user-ext'
+    ])
+  })
+
+  it('mirrors a preexisting remote Pi agent dir instead of the default', () => {
+    const defaultAgentDir = join(homeDir, '.pi', 'agent')
+    const customAgentDir = join(homeDir, 'custom-pi-agent')
+    mkdirSync(defaultAgentDir, { recursive: true })
+    mkdirSync(join(customAgentDir, 'extensions'), { recursive: true })
+    writeFileSync(join(defaultAgentDir, 'auth.json'), 'default token')
+    writeFileSync(join(customAgentDir, 'auth.json'), 'custom token')
+    writeFileSync(join(customAgentDir, 'extensions', 'custom.ts'), 'custom extension')
+
+    manager.setSources({ piExtensionSource: '// pi extension' })
+    const dir = manager.materializePi('tab-custom-pi:0', customAgentDir)
+
+    expect(dir).not.toBeNull()
+    expect(readFileSync(join(dir!, 'auth.json'), 'utf8')).toBe('custom token')
+    expect(readFileSync(join(dir!, 'extensions', 'custom.ts'), 'utf8')).toBe('custom extension')
+    expect(readFileSync(join(dir!, 'extensions', 'orca-agent-status.ts'), 'utf8')).toBe(
+      '// pi extension'
+    )
+  })
+
+  it('does not override a missing preexisting Pi agent dir', () => {
+    manager.setSources({ piExtensionSource: '// pi extension' })
+
+    expect(manager.materializePi('tab-missing-pi:0', join(homeDir, 'missing-pi'))).toBeNull()
+  })
+
+  it('clearOverlay removes both overlay roots for an id', () => {
+    manager.setSources({
+      opencodePluginSource: 'opencode',
+      piExtensionSource: 'pi'
+    })
+    const opencodeDir = manager.materializeOpenCode('tab-3:0')!
+    const piRoot = manager.materializePi('tab-3:0')!
+    expect(existsSync(opencodeDir)).toBe(true)
+    expect(existsSync(piRoot)).toBe(true)
+
+    manager.clearOverlay('tab-3:0')
+
+    expect(existsSync(opencodeDir)).toBe(false)
+    expect(existsSync(piRoot)).toBe(false)
+  })
+
+  it.skipIf(process.platform === 'win32')(
+    'clearOverlay removes OpenCode overlay symlinks without deleting their targets',
+    () => {
+      const userConfigDir = join(homeDir, 'company-opencode')
+      const linkedTarget = join(homeDir, 'linked-plugin-target')
+      mkdirSync(join(userConfigDir, 'plugins'), { recursive: true })
+      mkdirSync(linkedTarget, { recursive: true })
+      writeFileSync(join(linkedTarget, 'keep.js'), 'do not delete')
+      symlinkSync(linkedTarget, join(userConfigDir, 'plugins', 'linked-plugin'), 'dir')
+
+      manager.setSources({ opencodePluginSource: 'orca plugin' })
+      const dir = manager.materializeOpenCode('tab-opencode-symlink:0', userConfigDir)!
+      expect(existsSync(join(dir, 'plugins', 'linked-plugin'))).toBe(true)
+
+      manager.clearOverlay('tab-opencode-symlink:0')
+
+      expect(existsSync(dir)).toBe(false)
+      expect(readFileSync(join(linkedTarget, 'keep.js'), 'utf8')).toBe('do not delete')
+    }
+  )
+
+  it('produces stable overlay dirs for a given id (idempotent re-materialization)', () => {
+    manager.setSources({ opencodePluginSource: 'first' })
+    const dirA = manager.materializeOpenCode('tab-stable:0')!
+    manager.setSources({ opencodePluginSource: 'second' })
+    const dirB = manager.materializeOpenCode('tab-stable:0')!
+    expect(dirA).toBe(dirB)
+    expect(readFileSync(join(dirA, 'plugins', 'orca-opencode-status.js'), 'utf8')).toBe('second')
+  })
+
+  it('hashes unsafe pane ids into portable overlay directory names', () => {
+    manager.setSources({ opencodePluginSource: 'plugin' })
+    const dir = manager.materializeOpenCode('tab/with\\unsafe:chars\n0')
+
+    expect(dir).not.toBeNull()
+    expect(basename(dir!)).toMatch(/^[a-f0-9]{32}$/)
+    expect(dir).not.toContain('tab/with')
+    expect(existsSync(join(dir!, 'plugins', 'orca-opencode-status.js'))).toBe(true)
+  })
+})
diff --git a/src/relay/plugin-overlay.ts b/src/relay/plugin-overlay.ts
new file mode 100644
index 00000000000..905d4b5f3f1
--- /dev/null
+++ b/src/relay/plugin-overlay.ts
@@ -0,0 +1,276 @@
+// Why: relay-side equivalent of Orca's userData-backed plugin overlay system.
+// Orca's local OpenCodeHookService and PiTitlebarExtensionService each
+// materialize a per-PTY overlay and inject OPENCODE_CONFIG_DIR /
+// PI_CODING_AGENT_DIR pointing at it. Those paths describe the local
+// filesystem and would resolve to nothing on a remote box, so when a PTY runs
+// on the relay, the relay must do the same materialization on its own disk.
+//
+// Plugin source strings ship over the JSON-RPC channel at session-ready
+// (commit #7) — they are NOT bundled with the relay binary because the
+// relay is versioned independently from Orca and the plugin source changes
+// frequently as new agent events get added (see docs/design/agent-status-
+// over-ssh.md §4 "Why ship the plugin source over the wire").
+//
+// We deliberately do not reuse OpenCodeHookService / PiTitlebarExtensionService
+// directly: those modules import `electron` and ride on Orca's userData
+// path. The relay's electron-free constraint forces a thin parallel
+// implementation rooted at $HOME/.orca-relay/.
+
+import { createHash } from 'crypto'
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from 'fs'
+import { homedir } from 'os'
+import { basename, join } from 'path'
+import { mirrorEntry, safeRemoveOverlay } from '../main/pty/overlay-mirror'
+
+const RELAY_HOOKS_DIR = '.orca-relay'
+const OPENCODE_OVERLAY_SUBDIR = 'opencode-overlays'
+const PI_OVERLAY_SUBDIR = 'pi-overlays'
+const OPENCODE_PLUGIN_FILE = 'orca-opencode-status.js'
+const PI_EXTENSION_FILE = 'orca-agent-status.ts'
+const PI_AGENT_DIR_NAME = '.pi'
+const PI_AGENT_SUBDIR = 'agent'
+
+function safeDirName(input: string): string {
+  // Why: paneKey embeds tabId:paneId where tabId may itself contain
+  // filesystem-unsafe characters in some Orca builds. Hash to a fixed-width
+  // hex name so any input produces a portable directory name.
+  return createHash('sha256').update(input).digest('hex').slice(0, 32)
+}
+
+function isUsableId(id: string): boolean {
+  return typeof id === 'string' && id.length > 0 && id.length <= 1024
+}
+
+export type PluginSources = {
+  /** Source body of `orca-opencode-status.js` to drop into <overlay>/plugins/. */
+  opencodePluginSource?: string
+  /** Source body of `orca-agent-status.ts` to drop into <overlay>/extensions/. */
+  piExtensionSource?: string
+}
+
+export class PluginOverlayManager {
+  private opencodePluginSource: string | null = null
+  private piExtensionSource: string | null = null
+  private homeDir: string
+  private opencodeRoot: string
+  private piRoot: string
+
+  constructor(opts?: { homeDir?: string }) {
+    const home = opts?.homeDir ?? homedir()
+    this.homeDir = home
+    this.opencodeRoot = join(home, RELAY_HOOKS_DIR, OPENCODE_OVERLAY_SUBDIR)
+    this.piRoot = join(home, RELAY_HOOKS_DIR, PI_OVERLAY_SUBDIR)
+  }
+
+  /** Replace the cached source bodies. Called from relay.ts when Orca sends
+   *  `agent_hook.installPlugins`. The first install enables the augmenter
+   *  output; subsequent installs (e.g. Orca version upgrade in flight) refresh
+   *  the cached source so future spawns see the new strings.
+   *  Note: existing per-PTY overlays already on disk keep the previous source
+   *  until that PTY exits — a long-running PTY does NOT pick up the new
+   *  source, matching the local-Orca behavior where the plugin file is
+   *  written once at spawn time. */
+  setSources(sources: PluginSources): void {
+    if (typeof sources.opencodePluginSource === 'string') {
+      this.opencodePluginSource = sources.opencodePluginSource
+    }
+    if (typeof sources.piExtensionSource === 'string') {
+      this.piExtensionSource = sources.piExtensionSource
+    }
+  }
+
+  hasOpenCodeSource(): boolean {
+    return this.opencodePluginSource !== null
+  }
+
+  hasPiSource(): boolean {
+    return this.piExtensionSource !== null
+  }
+
+  private mirrorOpenCodeConfig(sourceDir: string, overlayDir: string): void {
+    for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+      const sourcePath = join(sourceDir, entry.name)
+
+      if (entry.name === 'plugins') {
+        const isSymlink = entry.isSymbolicLink()
+        let isLinkPointingToDir = false
+        if (isSymlink) {
+          try {
+            isLinkPointingToDir = statSync(sourcePath).isDirectory()
+          } catch {
+            isLinkPointingToDir = false
+          }
+        }
+
+        if ((!isSymlink && entry.isDirectory()) || isLinkPointingToDir) {
+          const resolvedSource = isLinkPointingToDir ? realpathSync(sourcePath) : sourcePath
+          const overlayPluginsDir = join(overlayDir, 'plugins')
+          mkdirSync(overlayPluginsDir, { recursive: true })
+          for (const pluginEntry of readdirSync(resolvedSource, { withFileTypes: true })) {
+            if (pluginEntry.name === OPENCODE_PLUGIN_FILE) {
+              continue
+            }
+            mirrorEntry(
+              join(resolvedSource, pluginEntry.name),
+              join(overlayPluginsDir, pluginEntry.name)
+            )
+          }
+          continue
+        }
+      }
+
+      mirrorEntry(sourcePath, join(overlayDir, entry.name))
+    }
+  }
+
+  private writeOpenCodePlugin(overlayDir: string): void {
+    const pluginsDir = join(overlayDir, 'plugins')
+    mkdirSync(pluginsDir, { recursive: true })
+    const pluginPath = join(pluginsDir, OPENCODE_PLUGIN_FILE)
+    try {
+      unlinkSync(pluginPath)
+    } catch {
+      // Fresh overlay or no same-named stale symlink.
+    }
+    writeFileSync(pluginPath, this.opencodePluginSource!)
+  }
+
+  /** Materialize the OpenCode plugin overlay for `id` (typically the
+   *  renderer-supplied paneKey or, fallback, the relay-internal pty-id) and
+   *  return the directory path. Returns null when no source is cached or
+   *  the overlay write fails — caller falls back to no plugin (the agent
+   *  CLI runs without status reporting), which is the existing fail-open
+   *  behavior on the local side. */
+  materializeOpenCode(id: string, existingConfigDir?: string): string | null {
+    if (!this.opencodePluginSource || !isUsableId(id)) {
+      return null
+    }
+    const dir = join(this.opencodeRoot, safeDirName(id))
+    try {
+      safeRemoveOverlay(dir, this.opencodeRoot)
+      mkdirSync(dir, { recursive: true })
+      if (existingConfigDir) {
+        if (!existsSync(existingConfigDir)) {
+          return null
+        }
+        // Why: OPENCODE_CONFIG_DIR is a single config root. Mirror the user's
+        // remote root into the overlay before adding Orca's plugin so status
+        // reporting does not hide their auth, models, keybinds, or plugins.
+        this.mirrorOpenCodeConfig(existingConfigDir, dir)
+      }
+      this.writeOpenCodePlugin(dir)
+      return dir
+    } catch (err) {
+      process.stderr.write(
+        `[plugin-overlay] failed to materialize OpenCode overlay: ${err instanceof Error ? err.message : String(err)}\n`
+      )
+      return null
+    }
+  }
+
+  private getDefaultPiAgentDir(): string {
+    return join(this.homeDir, PI_AGENT_DIR_NAME, PI_AGENT_SUBDIR)
+  }
+
+  private mirrorPiAgentDir(sourceAgentDir: string, overlayDir: string): void {
+    if (!existsSync(sourceAgentDir)) {
+      return
+    }
+
+    for (const entry of readdirSync(sourceAgentDir, { withFileTypes: true })) {
+      const sourcePath = join(sourceAgentDir, entry.name)
+
+      if (entry.name === 'extensions') {
+        const isSymlink = entry.isSymbolicLink()
+        let isLinkPointingToDir = false
+        if (isSymlink) {
+          try {
+            isLinkPointingToDir = statSync(sourcePath).isDirectory()
+          } catch {
+            isLinkPointingToDir = false
+          }
+        }
+
+        if ((!isSymlink && entry.isDirectory()) || isLinkPointingToDir) {
+          const resolvedSource = isLinkPointingToDir ? realpathSync(sourcePath) : sourcePath
+          const overlayExtensionsDir = join(overlayDir, 'extensions')
+          mkdirSync(overlayExtensionsDir, { recursive: true })
+          for (const extensionEntry of readdirSync(resolvedSource, { withFileTypes: true })) {
+            if (extensionEntry.name === PI_EXTENSION_FILE) {
+              continue
+            }
+            mirrorEntry(
+              join(resolvedSource, extensionEntry.name),
+              join(overlayExtensionsDir, extensionEntry.name)
+            )
+          }
+          continue
+        }
+      }
+
+      mirrorEntry(sourcePath, join(overlayDir, basename(sourcePath)))
+    }
+  }
+
+  /** Materialize the Pi extension overlay for `id` and return the directory
+   *  path that should be assigned to PI_CODING_AGENT_DIR. */
+  materializePi(id: string, existingAgentDir?: string): string | null {
+    if (!this.piExtensionSource || !isUsableId(id)) {
+      return null
+    }
+    const dir = join(this.piRoot, safeDirName(id))
+    try {
+      // Why: PI_CODING_AGENT_DIR is Pi's whole state root. Mirror the remote
+      // user's default agent dir so Orca's status extension does not hide auth,
+      // sessions, skills, prompts, themes, or user extensions inside SSH panes.
+      safeRemoveOverlay(dir, this.piRoot)
+      mkdirSync(dir, { recursive: true })
+      const sourceAgentDir = existingAgentDir ?? this.getDefaultPiAgentDir()
+      if (existingAgentDir && !existsSync(existingAgentDir)) {
+        return null
+      }
+      this.mirrorPiAgentDir(sourceAgentDir, dir)
+      const extensionsDir = join(dir, 'extensions')
+      mkdirSync(extensionsDir, { recursive: true })
+      writeFileSync(join(extensionsDir, PI_EXTENSION_FILE), this.piExtensionSource)
+      return dir
+    } catch (err) {
+      process.stderr.write(
+        `[plugin-overlay] failed to materialize Pi overlay: ${err instanceof Error ? err.message : String(err)}\n`
+      )
+      return null
+    }
+  }
+
+  /** Drop a paneKey's overlay dirs on PTY exit. Best-effort; cleanup over a
+   *  recursive tree may fail on exotic filesystems but the worst-case
+   *  outcome is unbounded growth on a long-lived relay, which the per-pane
+   *  caches alone do not bound. */
+  clearOverlay(id: string): void {
+    if (!isUsableId(id)) {
+      return
+    }
+    const safe = safeDirName(id)
+    for (const root of [this.opencodeRoot, this.piRoot]) {
+      try {
+        safeRemoveOverlay(join(root, safe), root)
+      } catch (err) {
+        // Why: log the failed cleanup so a permission/IO error is observable.
+        // The leak is the failure mode the per-pane cache eviction exists to
+        // prevent — silent swallows would let it accumulate invisibly on
+        // long-running relays.
+        process.stderr.write(
+          `[plugin-overlay] failed to remove overlay dir ${join(root, safe)}: ${err instanceof Error ? err.message : String(err)}\n`
+        )
+      }
+    }
+  }
+}
diff --git a/src/relay/plugin-source-limit.test.ts b/src/relay/plugin-source-limit.test.ts
new file mode 100644
index 00000000000..87068802215
--- /dev/null
+++ b/src/relay/plugin-source-limit.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { assertPluginSourceUnderByteCap, PLUGIN_SOURCE_MAX_BYTES } from './plugin-source-limit'
+
+describe('plugin source byte limit', () => {
+  it('allows non-string values because installPlugins treats them as absent sources', () => {
+    expect(() => assertPluginSourceUnderByteCap('piExtensionSource', undefined)).not.toThrow()
+  })
+
+  it('allows sources at the byte cap', () => {
+    const source = 'a'.repeat(PLUGIN_SOURCE_MAX_BYTES)
+
+    expect(() => assertPluginSourceUnderByteCap('opencodePluginSource', source)).not.toThrow()
+  })
+
+  it('rejects sources over the byte cap using utf8 byte length, not string length', () => {
+    const source = 'é'.repeat(Math.floor(PLUGIN_SOURCE_MAX_BYTES / 2) + 1)
+
+    expect(source.length).toBeLessThanOrEqual(PLUGIN_SOURCE_MAX_BYTES)
+    expect(Buffer.byteLength(source, 'utf8')).toBeGreaterThan(PLUGIN_SOURCE_MAX_BYTES)
+    expect(() => assertPluginSourceUnderByteCap('piExtensionSource', source)).toThrow(
+      `piExtensionSource exceeds ${PLUGIN_SOURCE_MAX_BYTES} byte cap`
+    )
+  })
+})
diff --git a/src/relay/plugin-source-limit.ts b/src/relay/plugin-source-limit.ts
new file mode 100644
index 00000000000..d06c24248a0
--- /dev/null
+++ b/src/relay/plugin-source-limit.ts
@@ -0,0 +1,12 @@
+export const PLUGIN_SOURCE_MAX_BYTES = 256 * 1024
+
+export function assertPluginSourceUnderByteCap(fieldName: string, value: unknown): void {
+  if (typeof value !== 'string') {
+    return
+  }
+  // Why: the relay receives JSON strings over the wire; cap actual UTF-8
+  // bytes instead of UTF-16 code units so non-ASCII source cannot bypass it.
+  if (Buffer.byteLength(value, 'utf8') > PLUGIN_SOURCE_MAX_BYTES) {
+    throw new Error(`${fieldName} exceeds ${PLUGIN_SOURCE_MAX_BYTES} byte cap`)
+  }
+}
diff --git a/src/relay/pty-handler.test.ts b/src/relay/pty-handler.test.ts
index ec34881e9a2..e806237a429 100644
--- a/src/relay/pty-handler.test.ts
+++ b/src/relay/pty-handler.test.ts
@@ -1,5 +1,8 @@
 /* oxlint-disable max-lines */
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
 
 const { mockPtySpawn, mockPtyInstance } = vi.hoisted(() => ({
   mockPtySpawn: vi.fn(),
@@ -435,6 +438,113 @@ describe('PtyHandler', () => {
     expect(callArgs.env.ORCA_TAB_ID).toBe('tab-1')
   })
 
+  it('passes the PTY id and renderer paneKey to env augmenters', async () => {
+    const seenContexts: { id: string; paneKey?: string; env: Record<string, string> }[] = []
+    handler.addEnvAugmenter((ctx) => {
+      seenContexts.push(ctx)
+      return {
+        OVERLAY_ID: ctx.paneKey ?? ctx.id
+      }
+    })
+
+    await dispatcher.callRequest('pty.spawn', {
+      env: { ORCA_PANE_KEY: 'tab-context:0' }
+    })
+    await dispatcher.callRequest('pty.spawn', {})
+
+    const firstEnv = mockPtySpawn.mock.calls[0][2] as { env: Record<string, string> }
+    const secondEnv = mockPtySpawn.mock.calls[1][2] as { env: Record<string, string> }
+    expect(seenContexts[0]).toMatchObject({
+      id: 'pty-1',
+      paneKey: 'tab-context:0',
+      env: { ORCA_PANE_KEY: 'tab-context:0' }
+    })
+    expect(seenContexts[1]).toMatchObject({ id: 'pty-2', paneKey: undefined })
+    expect(firstEnv.env.OVERLAY_ID).toBe('tab-context:0')
+    expect(secondEnv.env.OVERLAY_ID).toBe('pty-2')
+  })
+
+  it('passes process and renderer env to env augmenters before augmenter overrides are applied', async () => {
+    const oldProcessValue = process.env.OPENCODE_CONFIG_DIR
+    process.env.OPENCODE_CONFIG_DIR = '/remote/default-opencode'
+    try {
+      handler.addEnvAugmenter((ctx) => ({
+        SEEN_OPENCODE_CONFIG_DIR: ctx.env.OPENCODE_CONFIG_DIR,
+        SEEN_PI_CODING_AGENT_DIR: ctx.env.PI_CODING_AGENT_DIR
+      }))
+
+      await dispatcher.callRequest('pty.spawn', {
+        env: {
+          OPENCODE_CONFIG_DIR: '/remote/renderer-opencode',
+          PI_CODING_AGENT_DIR: '/remote/pi'
+        }
+      })
+    } finally {
+      if (oldProcessValue === undefined) {
+        delete process.env.OPENCODE_CONFIG_DIR
+      } else {
+        process.env.OPENCODE_CONFIG_DIR = oldProcessValue
+      }
+    }
+
+    const spawnEnv = mockPtySpawn.mock.calls[0][2] as { env: Record<string, string> }
+    expect(spawnEnv.env.SEEN_OPENCODE_CONFIG_DIR).toBe('/remote/renderer-opencode')
+    expect(spawnEnv.env.SEEN_PI_CODING_AGENT_DIR).toBe('/remote/pi')
+  })
+
+  it.skipIf(process.platform === 'win32')(
+    'wraps bash spawns to restore overlay env after remote startup files',
+    async () => {
+      const oldShell = process.env.SHELL
+      const oldHome = process.env.HOME
+      const homeDir = mkdtempSync(join(tmpdir(), 'relay-pty-shell-launch-'))
+
+      process.env.SHELL = '/bin/bash'
+      process.env.HOME = homeDir
+      try {
+        if (!existsSync('/bin/bash')) {
+          return
+        }
+
+        handler.addEnvAugmenter(() => ({
+          OPENCODE_CONFIG_DIR: '/remote/overlay/opencode',
+          ORCA_OPENCODE_CONFIG_DIR: '/remote/overlay/opencode',
+          PI_CODING_AGENT_DIR: '/remote/overlay/pi',
+          ORCA_PI_CODING_AGENT_DIR: '/remote/overlay/pi'
+        }))
+
+        await dispatcher.callRequest('pty.spawn', { env: { HOME: homeDir } })
+      } finally {
+        if (oldShell === undefined) {
+          delete process.env.SHELL
+        } else {
+          process.env.SHELL = oldShell
+        }
+        if (oldHome === undefined) {
+          delete process.env.HOME
+        } else {
+          process.env.HOME = oldHome
+        }
+      }
+
+      const shellArgs = mockPtySpawn.mock.calls[0][1]
+      const spawnOptions = mockPtySpawn.mock.calls[0][2] as { env: Record<string, string> }
+      const rcfile = join(homeDir, '.orca-relay', 'shell-ready', 'bash', 'rcfile')
+
+      expect(shellArgs).toEqual(['--rcfile', rcfile])
+      expect(spawnOptions.env.ORCA_OPENCODE_CONFIG_DIR).toBe('/remote/overlay/opencode')
+      expect(spawnOptions.env.ORCA_PI_CODING_AGENT_DIR).toBe('/remote/overlay/pi')
+      expect(readFileSync(rcfile, 'utf8')).toContain(
+        'export OPENCODE_CONFIG_DIR="${ORCA_OPENCODE_CONFIG_DIR}"'
+      )
+      expect(readFileSync(rcfile, 'utf8')).toContain(
+        'export PI_CODING_AGENT_DIR="${ORCA_PI_CODING_AGENT_DIR}"'
+      )
+
+      rmSync(homeDir, { recursive: true, force: true })
+    }
+  )
+
   it('revive restores pane identity env alongside hook-server coordinates', async () => {
     await dispatcher.callRequest('pty.spawn', {
       cols: 90,
@@ -494,7 +604,32 @@ describe('PtyHandler', () => {
     expect(exits).toEqual([{ id: 'pty-1', paneKey: 'tab-2:1' }])
   })
 
-  it('dispose kills all PTYs with SIGKILL', async () => {
+  it('immediate shutdown invokes the exit listener once even if onExit arrives later', async () => {
+    let onExitCb: ((evt: { exitCode: number }) => void) | undefined
+    const mockKill = vi.fn()
+    mockPtySpawn.mockReturnValue({
+      ...mockPtyInstance,
+      kill: mockKill,
+      onData: vi.fn(),
+      onExit: vi.fn((cb: (evt: { exitCode: number }) => void) => {
+        onExitCb = cb
+      })
+    })
+    const exits: { id: string; paneKey?: string }[] = []
+    handler.setExitListener((evt) => exits.push(evt))
+
+    await dispatcher.callRequest('pty.spawn', {
+      env: { ORCA_PANE_KEY: 'tab-shutdown:0' }
+    })
+    await dispatcher.callRequest('pty.shutdown', { id: 'pty-1', immediate: true })
+    onExitCb!({ exitCode: 0 })
+
+    expect(mockKill).toHaveBeenCalledWith('SIGKILL')
+    expect(exits).toEqual([{ id: 'pty-1', paneKey: 'tab-shutdown:0' }])
+    expect(handler.activePtyCount).toBe(0)
+  })
+
+  it('dispose kills all PTYs with SIGKILL and invokes exit listeners', async () => {
     const mockKill = vi.fn()
     mockPtySpawn.mockReturnValue({
       ...mockPtyInstance,
@@ -502,9 +637,11 @@ describe('PtyHandler', () => {
       onData: vi.fn(),
       onExit: vi.fn()
     })
+    const exits: { id: string; paneKey?: string }[] = []
+    handler.setExitListener((evt) => exits.push(evt))
 
-    await dispatcher.callRequest('pty.spawn', {})
-    await dispatcher.callRequest('pty.spawn', {})
+    await dispatcher.callRequest('pty.spawn', { env: { ORCA_PANE_KEY: 'tab-dispose:0' } })
+    await dispatcher.callRequest('pty.spawn', { env: { ORCA_PANE_KEY: 'tab-dispose:1' } })
     expect(handler.activePtyCount).toBe(2)
 
     handler.dispose()
@@ -513,6 +650,10 @@ describe('PtyHandler', () => {
     // wedged process, uninterruptible sleep) would survive SIGTERM + immediate
     // destroy() as an orphan on the remote host. SIGKILL is not ignorable.
     expect(mockKill).toHaveBeenCalledWith('SIGKILL')
+    expect(exits).toEqual([
+      { id: 'pty-1', paneKey: 'tab-dispose:0' },
+      { id: 'pty-2', paneKey: 'tab-dispose:1' }
+    ])
     expect(handler.activePtyCount).toBe(0)
   })
 })
diff --git a/src/relay/pty-handler.ts b/src/relay/pty-handler.ts
index b36b7b43180..b1b540cb867 100644
--- a/src/relay/pty-handler.ts
+++ b/src/relay/pty-handler.ts
@@ -9,6 +9,7 @@ import {
   getForegroundProcessName,
   listShellProfiles
 } from './pty-shell-utils'
+import { getRelayShellLaunchConfig } from './pty-shell-launch'
 
 // Why: node-pty is a native addon that may not be installed on the remote.
 // Dynamic import keeps the require() lazy so loadPty() returns null gracefully
@@ -39,6 +40,10 @@ type ManagedPty = {
    *  entry-point calls into a clean "not found" error instead of a silent no-op
    *  (POSIX proc.kill is neutralized inside disposeManagedPty). */
   disposed?: boolean
+  /** True once external cleanup observers have been notified. Forced cleanup
+   *  paths can run before node-pty emits onExit; this prevents duplicate
+   *  overlay/cache cleanup if onExit arrives later. */
+  exitListenerNotified?: boolean
   /** Renderer-supplied paneKey from spawn env (ORCA_PANE_KEY). Captured so
    *  external observers (the relay-hook-server cache) can evict per-pane
    *  state when this PTY exits. Symmetric with Orca's local pty.ts. */
@@ -102,7 +107,16 @@ type SerializedPtyEntry = {
 }
 
 export type PtyExitListener = (event: { id: string; paneKey?: string }) => void
-export type PtyEnvAugmenter = () => Record<string, string>
+/** Returns env to merge into the PTY's spawn env. Receives spawn context so
+ *  augmenters that need a per-PTY identity (e.g. OPENCODE_CONFIG_DIR overlay
+ *  paths derived from the renderer's paneKey) can compute it without pulling
+ *  the renderer's env in twice. */
+export type PtyEnvAugmenter = (ctx: {
+  id: string
+  paneKey?: string
+  shell: string
+  env: Record<string, string>
+}) => Record<string, string>
 
 export class PtyHandler {
   private ptys = new Map<string, ManagedPty>()
@@ -110,11 +124,13 @@ export class PtyHandler {
   private dispatcher: RelayDispatcher
   private graceTimeMs: number
   private graceTimer: ReturnType<typeof setTimeout> | null = null
-  // Why: external observers (the relay's hook-server cache) need to drop
-  // per-pane state when a PTY exits. Multiple listeners is unnecessary today
-  // — the hook server is the only consumer — so a single optional callback
-  // keeps the surface tight. A throw inside the listener is swallowed so it
-  // can never block disposeManagedPty / map cleanup.
+  // Why: external observers need to drop per-pane state when a PTY exits.
+  // Today the relay composes multiple consumers (hook-server cache eviction
+  // and plugin-overlay dir cleanup) into a single callback at the call site
+  // (see relay.ts setExitListener). A single optional slot is intentional —
+  // callers compose externally rather than us maintaining a listener list.
+  // A throw inside the listener is swallowed so it can never block
+  // disposeManagedPty / map cleanup.
   private exitListener: PtyExitListener | null = null
   // Why: env augmenters injected at relay boot (currently the relay-hook
   // server's ORCA_AGENT_HOOK_* coords). Run on every spawn so every PTY
@@ -156,18 +172,22 @@ export class PtyHandler {
    *  drift between the two paths — revived shells after a relay restart must
    *  see the fresh ORCA_AGENT_HOOK_* coords just like freshly-spawned ones,
    *  otherwise agent-status over SSH silently breaks on every revive. */
-  private buildSpawnEnv(rendererEnv?: Record<string, string>): Record<string, string> {
+  private buildSpawnEnv(
+    rendererEnv: Record<string, string> | undefined,
+    ctx: { id: string; paneKey?: string; shell: string }
+  ): Record<string, string> {
+    const baseEnv = { ...process.env, ...rendererEnv } as Record<string, string>
     const augmented: Record<string, string> = {}
     for (const augmenter of this.envAugmenters) {
       try {
-        Object.assign(augmented, augmenter())
+        Object.assign(augmented, augmenter({ ...ctx, env: baseEnv }))
       } catch (err) {
         process.stderr.write(
           `[pty-handler] env augmenter threw: ${err instanceof Error ? err.message : String(err)}\n`
         )
       }
     }
-    return { ...process.env, ...rendererEnv, ...augmented } as Record<string, string>
+    return { ...baseEnv, ...augmented }
   }
 
   /** Wire onData/onExit listeners for a managed PTY and store it. */
@@ -181,6 +201,9 @@ export class PtyHandler {
       this.dispatcher.notify('pty.data', { id: managed.id, data })
     })
     managed.pty.onExit(({ exitCode }: { exitCode: number }) => {
+      if (managed.disposed) {
+        return
+      }
       // Why: neutralize managed.pty.kill synchronously BEFORE anything else
       // in this callback. node-pty's UnixTerminal has
       // `_socket.once('close', () => this.kill('SIGHUP'))` wired at destroy
@@ -199,19 +222,7 @@ export class PtyHandler {
         managed.killTimer = undefined
       }
       this.dispatcher.notify('pty.exit', { id: managed.id, code: exitCode })
-      // Why: notify external observers BEFORE deleting the map entry so a
-      // listener that needs to read paneKey from the managed entry still
-      // can. Wrap in try/catch so a throwing listener cannot block fd
-      // release or map cleanup.
-      if (this.exitListener) {
-        try {
-          this.exitListener({ id: managed.id, paneKey: managed.paneKey })
-        } catch (err) {
-          process.stderr.write(
-            `[pty-handler] onExit listener threw: ${err instanceof Error ? err.message : String(err)}\n`
-          )
-        }
-      }
+      this.notifyExitListener(managed)
       this.ptys.delete(managed.id)
       // Why: release the ptmx fd on the natural-exit path. Without this the
       // node-pty wrapper's _socket stays alive until GC and the master fd
@@ -220,6 +231,26 @@ export class PtyHandler {
     })
   }
 
+  private notifyExitListener(managed: ManagedPty): void {
+    if (managed.exitListenerNotified) {
+      return
+    }
+    managed.exitListenerNotified = true
+    // Why: external observers own relay-hook cache eviction and plugin-overlay
+    // cleanup. Natural exits, immediate shutdown, SIGKILL fallback, and relay
+    // process disposal all need the same cleanup even when node-pty never
+    // delivers onExit.
+    if (this.exitListener) {
+      try {
+        this.exitListener({ id: managed.id, paneKey: managed.paneKey })
+      } catch (err) {
+        process.stderr.write(
+          `[pty-handler] exit listener threw: ${err instanceof Error ? err.message : String(err)}\n`
+        )
+      }
+    }
+  }
+
   private registerHandlers(): void {
     this.dispatcher.onRequest('pty.spawn', (p, context) => this.spawn(p, context))
     this.dispatcher.onRequest('pty.attach', (p) => this.attach(p))
@@ -262,28 +293,31 @@ export class PtyHandler {
     const shell = resolveDefaultShell()
     const id = `pty-${this.nextId++}`
 
-    // Why: server-side augmenter values (ORCA_AGENT_HOOK_*) override any
-    // renderer-supplied env so the live hook-server coords always reach the
-    // agent CLI — they come from the relay, not the renderer. See
-    // buildSpawnEnv for the precedence contract.
-    const spawnEnv = this.buildSpawnEnv(env)
+    // Why: server-side augmenter values (ORCA_AGENT_HOOK_* and plugin overlay
+    // dirs) override renderer-supplied env so live remote paths and hook coords
+    // win over local userData paths. The context lets overlay augmenters derive
+    // per-PTY OpenCode/Pi directories from the stable paneKey when present.
+    const paneKey = typeof env?.ORCA_PANE_KEY === 'string' ? env.ORCA_PANE_KEY : undefined
+    const spawnEnv = this.buildSpawnEnv(env, { id, paneKey, shell })
+    const shellLaunch = getRelayShellLaunchConfig(shell, spawnEnv)
 
     // Why: SSH exec channels give the relay a minimal environment without
     // .zprofile/.bash_profile sourced. Spawning a login shell ensures PATH
     // includes Homebrew, nvm, and user-installed CLIs (claude, codex, gh).
-    const term = pty.spawn(shell, ['-l'], {
+    // When overlays are injected, the launch wrapper keeps those paths after
+    // user startup files re-export their defaults.
+    const term = pty.spawn(shell, shellLaunch.args, {
       name: 'xterm-256color',
       cols,
       rows,
       cwd,
-      env: spawnEnv
+      env: { ...spawnEnv, ...shellLaunch.env }
     })
 
     // Why: capture the renderer-supplied paneKey on the managed entry so the
     // exit listener can evict per-pane caches without the relay needing a
     // separate ptyId→paneKey map. ORCA_PANE_KEY is shaped `${tabId}:${paneId}`
     // and is bounded by the renderer; the relay treats it as opaque.
-    const paneKey = typeof env?.ORCA_PANE_KEY === 'string' ? env.ORCA_PANE_KEY : undefined
     const tabId = typeof env?.ORCA_TAB_ID === 'string' ? env.ORCA_TAB_ID : undefined
     const worktreeId = typeof env?.ORCA_WORKTREE_ID === 'string' ? env.ORCA_WORKTREE_ID : undefined
     const managed: ManagedPty = {
@@ -309,6 +343,7 @@ export class PtyHandler {
           // SIGKILL's onExit is missed (kernel edge case, uninterruptible
           // sleep), the managed entry + ptmx fd would leak forever. Dispose
           // synchronously so the entry is gone regardless of onExit timing.
+          this.notifyExitListener(still)
           disposeManagedPty(still)
           this.ptys.delete(id)
         }
@@ -391,6 +426,7 @@ export class PtyHandler {
       // here makes the map hygiene a hard guarantee, not "hopefully onExit
       // runs". If onExit DOES fire later, its own `this.ptys.delete(id)` is
       // a no-op.
+      this.notifyExitListener(managed)
       this.ptys.delete(id)
     } else {
       managed.pty.kill('SIGTERM')
@@ -414,6 +450,7 @@ export class PtyHandler {
           // graceful-shutdown's SIGKILL fallback is a hard guarantee, not
           // "hopefully onExit will run". The disposed guard inside
           // disposeManagedPty makes a later onExit's dispose a no-op.
+          this.notifyExitListener(still)
           disposeManagedPty(still)
           this.ptys.delete(id)
         }
@@ -545,12 +582,19 @@ export class PtyHandler {
       if (entry.worktreeId) {
         revivedEnv.ORCA_WORKTREE_ID = entry.worktreeId
       }
-      const term = ptyMod.spawn(resolveDefaultShell(), ['-l'], {
+      const shell = resolveDefaultShell()
+      const spawnEnv = this.buildSpawnEnv(revivedEnv, {
+        id: entry.id,
+        paneKey: entry.paneKey,
+        shell
+      })
+      const shellLaunch = getRelayShellLaunchConfig(shell, spawnEnv)
+      const term = ptyMod.spawn(shell, shellLaunch.args, {
         name: 'xterm-256color',
         cols: entry.cols,
         rows: entry.rows,
         cwd: entry.cwd,
-        env: this.buildSpawnEnv(revivedEnv)
+        env: { ...spawnEnv, ...shellLaunch.env }
       })
       this.wireAndStore({
         id: entry.id,
@@ -612,6 +656,7 @@ export class PtyHandler {
       } catch {
         /* child may already be dead */
       }
+      this.notifyExitListener(managed)
       disposeManagedPty(managed)
     }
     this.ptys.clear()
diff --git a/src/relay/pty-shell-launch.test.ts b/src/relay/pty-shell-launch.test.ts
new file mode 100644
index 00000000000..9307f22f865
--- /dev/null
+++ b/src/relay/pty-shell-launch.test.ts
@@ -0,0 +1,58 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { getRelayShellLaunchConfig } from './pty-shell-launch'
+
+describe('getRelayShellLaunchConfig', () => {
+  let homeDir: string
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), 'relay-shell-launch-'))
+  })
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true })
+  })
+
+  it.skipIf(process.platform === 'win32')(
+    'preserves a user ZDOTDIR exported from .zshenv for later startup files',
+    () => {
+      const config = getRelayShellLaunchConfig('/bin/zsh', {
+        HOME: homeDir,
+        ORCA_OPENCODE_CONFIG_DIR: '/tmp/orca-opencode-overlay'
+      })
+      const zshRoot = join(homeDir, '.orca-relay', 'shell-ready', 'zsh')
+
+      expect(config.args).toEqual(['-l'])
+      expect(config.env.ZDOTDIR).toBe(zshRoot)
+      expect(readFileSync(join(zshRoot, '.zshenv'), 'utf8')).toContain(
+        'export ORCA_USER_ZDOTDIR="${ZDOTDIR:-${ORCA_ORIG_ZDOTDIR:-$HOME}}"'
+      )
+      expect(readFileSync(join(zshRoot, '.zprofile'), 'utf8')).toContain(
+        '_orca_home="${ORCA_USER_ZDOTDIR:-${ORCA_ORIG_ZDOTDIR:-$HOME}}"'
+      )
+      expect(readFileSync(join(zshRoot, '.zshrc'), 'utf8')).toContain(
+        '_orca_home="${ORCA_USER_ZDOTDIR:-${ORCA_ORIG_ZDOTDIR:-$HOME}}"'
+      )
+      expect(readFileSync(join(zshRoot, '.zlogin'), 'utf8')).toContain(
+        '_orca_home="${ORCA_USER_ZDOTDIR:-${ORCA_ORIG_ZDOTDIR:-$HOME}}"'
+      )
+    }
+  )
+
+  it.skipIf(process.platform === 'win32')('rewrites stale persistent wrapper files', () => {
+    const zshRoot = join(homeDir, '.orca-relay', 'shell-ready', 'zsh')
+    mkdirSync(zshRoot, { recursive: true })
+    writeFileSync(join(zshRoot, '.zshenv'), '# stale relay wrapper\n')
+
+    getRelayShellLaunchConfig('/bin/zsh', {
+      HOME: homeDir,
+      ORCA_OPENCODE_CONFIG_DIR: '/tmp/orca-opencode-overlay'
+    })
+
+    expect(readFileSync(join(zshRoot, '.zshenv'), 'utf8')).toContain(
+      'export ORCA_USER_ZDOTDIR="${ZDOTDIR:-${ORCA_ORIG_ZDOTDIR:-$HOME}}"'
+    )
+  })
+})
diff --git a/src/relay/pty-shell-launch.ts b/src/relay/pty-shell-launch.ts
new file mode 100644
index 00000000000..f2f3f739bd9
--- /dev/null
+++ b/src/relay/pty-shell-launch.ts
@@ -0,0 +1,165 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { basename, dirname, join } from 'path'
+
+const RELAY_SHELL_READY_DIR = '.orca-relay/shell-ready'
+const POSIX_LOGIN_ARGS = ['-l']
+
+export type RelayShellLaunchConfig = {
+  args: string[]
+  env: Record<string, string>
+}
+
+function quotePosixSingle(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+function hasOverlayRestoreEnv(env: Record<string, string>): boolean {
+  return Boolean(env.ORCA_OPENCODE_CONFIG_DIR || env.ORCA_PI_CODING_AGENT_DIR)
+}
+
+function getWrapperRoot(env: Record<string, string>): string {
+  return join(env.HOME || process.env.HOME || homedir(), RELAY_SHELL_READY_DIR)
+}
+
+function normalizeOriginalZdotdirCandidate(value: string | undefined): string | null {
+  if (!value) {
+    return null
+  }
+  const normalized = value.replace(/\/+$/, '')
+  if (!normalized || normalized.endsWith('/shell-ready/zsh')) {
+    return null
+  }
+  return value
+}
+
+function resolveOriginalZdotdir(env: Record<string, string>): string {
+  return (
+    normalizeOriginalZdotdirCandidate(env.ZDOTDIR) ||
+    normalizeOriginalZdotdirCandidate(env.ORCA_ORIG_ZDOTDIR) ||
+    env.HOME ||
+    process.env.HOME ||
+    ''
+  )
+}
+
+function ensureOverlayRestoreWrappers(root: string): void {
+  const zshDir = join(root, 'zsh')
+  const bashDir = join(root, 'bash')
+
+  const zshEnv = `# Orca relay zsh overlay wrapper
+export ORCA_ORIG_ZDOTDIR="\${ORCA_ORIG_ZDOTDIR:-$HOME}"
+case "\${ORCA_ORIG_ZDOTDIR%/}" in
+  */shell-ready/zsh) export ORCA_ORIG_ZDOTDIR="$HOME" ;;
+esac
+[[ -f "$ORCA_ORIG_ZDOTDIR/.zshenv" ]] && source "$ORCA_ORIG_ZDOTDIR/.zshenv"
+export ORCA_USER_ZDOTDIR="\${ZDOTDIR:-\${ORCA_ORIG_ZDOTDIR:-$HOME}}"
+case "\${ORCA_USER_ZDOTDIR%/}" in
+  */shell-ready/zsh) export ORCA_USER_ZDOTDIR="$HOME" ;;
+esac
+export ZDOTDIR=${quotePosixSingle(zshDir)}
+`
+  const zshProfile = `# Orca relay zsh overlay wrapper
+_orca_home="\${ORCA_USER_ZDOTDIR:-\${ORCA_ORIG_ZDOTDIR:-$HOME}}"
+case "\${_orca_home%/}" in
+  */shell-ready/zsh) _orca_home="$HOME" ;;
+esac
+[[ -f "$_orca_home/.zprofile" ]] && source "$_orca_home/.zprofile"
+`
+  const zshRc = `# Orca relay zsh overlay wrapper
+_orca_home="\${ORCA_USER_ZDOTDIR:-\${ORCA_ORIG_ZDOTDIR:-$HOME}}"
+case "\${_orca_home%/}" in
+  */shell-ready/zsh) _orca_home="$HOME" ;;
+esac
+if [[ -o interactive && -f "$_orca_home/.zshrc" ]]; then
+  source "$_orca_home/.zshrc"
+fi
+if [[ ! -o login ]]; then
+  # Why: remote startup files can re-export user defaults after relay spawn.
+  [[ -n "\${ORCA_OPENCODE_CONFIG_DIR:-}" ]] && export OPENCODE_CONFIG_DIR="\${ORCA_OPENCODE_CONFIG_DIR}"
+  [[ -n "\${ORCA_PI_CODING_AGENT_DIR:-}" ]] && export PI_CODING_AGENT_DIR="\${ORCA_PI_CODING_AGENT_DIR}"
+fi
+`
+  const zshLogin = `# Orca relay zsh overlay wrapper
+_orca_home="\${ORCA_USER_ZDOTDIR:-\${ORCA_ORIG_ZDOTDIR:-$HOME}}"
+case "\${_orca_home%/}" in
+  */shell-ready/zsh) _orca_home="$HOME" ;;
+esac
+if [[ -o interactive && -f "$_orca_home/.zlogin" ]]; then
+  source "$_orca_home/.zlogin"
+fi
+# Why: .zlogin is the final zsh login startup file before the prompt.
+[[ -n "\${ORCA_OPENCODE_CONFIG_DIR:-}" ]] && export OPENCODE_CONFIG_DIR="\${ORCA_OPENCODE_CONFIG_DIR}"
+[[ -n "\${ORCA_PI_CODING_AGENT_DIR:-}" ]] && export PI_CODING_AGENT_DIR="\${ORCA_PI_CODING_AGENT_DIR}"
+`
+  const bashRc = `# Orca relay bash overlay wrapper
+[[ -f /etc/profile ]] && source /etc/profile
+if [[ -f "$HOME/.bash_profile" ]]; then
+  source "$HOME/.bash_profile"
+elif [[ -f "$HOME/.bash_login" ]]; then
+  source "$HOME/.bash_login"
+elif [[ -f "$HOME/.profile" ]]; then
+  source "$HOME/.profile"
+fi
+# Why: remote startup files can re-export user defaults after relay spawn.
+[[ -n "\${ORCA_OPENCODE_CONFIG_DIR:-}" ]] && export OPENCODE_CONFIG_DIR="\${ORCA_OPENCODE_CONFIG_DIR}"
+[[ -n "\${ORCA_PI_CODING_AGENT_DIR:-}" ]] && export PI_CODING_AGENT_DIR="\${ORCA_PI_CODING_AGENT_DIR}"
+`
+
+  const files = [
+    [join(zshDir, '.zshenv'), zshEnv],
+    [join(zshDir, '.zprofile'), zshProfile],
+    [join(zshDir, '.zshrc'), zshRc],
+    [join(zshDir, '.zlogin'), zshLogin],
+    [join(bashDir, 'rcfile'), bashRc]
+  ] as const
+
+  for (const [path, content] of files) {
+    mkdirSync(dirname(path), { recursive: true })
+    let existing: string | null = null
+    try {
+      existing = readFileSync(path, 'utf8')
+    } catch {
+      existing = null
+    }
+    // Why: relay wrapper files persist under ~/.orca-relay across app
+    // upgrades. Existence alone is not enough; stale wrappers would miss
+    // later fixes such as preserving post-.zshenv ZDOTDIR.
+    if (existing !== content) {
+      writeFileSync(path, content, 'utf8')
+    }
+    chmodSync(path, 0o644)
+  }
+}
+
+export function getRelayShellLaunchConfig(
+  shellPath: string,
+  env: Record<string, string>
+): RelayShellLaunchConfig {
+  if (!hasOverlayRestoreEnv(env) || process.platform === 'win32') {
+    return { args: POSIX_LOGIN_ARGS, env: {} }
+  }
+
+  const shellName = basename(shellPath).toLowerCase()
+  if (shellName !== 'zsh' && shellName !== 'bash') {
+    return { args: POSIX_LOGIN_ARGS, env: {} }
+  }
+
+  const root = getWrapperRoot(env)
+  ensureOverlayRestoreWrappers(root)
+
+  if (shellName === 'zsh') {
+    return {
+      args: POSIX_LOGIN_ARGS,
+      env: {
+        ORCA_ORIG_ZDOTDIR: resolveOriginalZdotdir(env),
+        ZDOTDIR: join(root, 'zsh')
+      }
+    }
+  }
+
+  return {
+    args: ['--rcfile', join(root, 'bash', 'rcfile')],
+    env: {}
+  }
+}
diff --git a/src/relay/relay.ts b/src/relay/relay.ts
index df6e075adb7..b1bc2df32a5 100644
--- a/src/relay/relay.ts
+++ b/src/relay/relay.ts
@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+/* oxlint-disable max-lines -- Why: the relay entry point centralizes process
+   lifecycle (stdio, --connect bridge, grace timer, signal handlers, socket
+   server) and handler registration in one file so the boot sequence stays in
+   topological order. Splitting by line count would scatter ordered side-
+   effects across modules and obscure the lifecycle. */
 
 // Orca Relay — lightweight daemon deployed to remote hosts.
 // Communicates over stdin/stdout using the framed JSON-RPC protocol.
@@ -24,11 +29,14 @@ import { GitHandler } from './git-handler'
 import { PreflightHandler } from './preflight-handler'
 import { PortScanHandler } from './port-scan-handler'
 import { endpointDirForRelaySocket, RelayAgentHookServer } from './agent-hook-server'
+import { PluginOverlayManager } from './plugin-overlay'
 import {
   AGENT_HOOK_INSTALL_PLUGINS_METHOD,
   AGENT_HOOK_NOTIFICATION_METHOD,
   AGENT_HOOK_REQUEST_REPLAY_METHOD
 } from '../shared/agent-hook-relay'
+import { assertPluginSourceUnderByteCap } from './plugin-source-limit'
+import { resolveOpenCodeSourceConfigDir, resolvePiSourceAgentDir } from './plugin-overlay-env'
 
 const DEFAULT_GRACE_MS = 5 * 60 * 1000
 const SOCK_NAME = 'relay.sock'
@@ -247,26 +255,77 @@ async function main(): Promise<void> {
       )
     }
   })
-  // Why: wait for hook-server startup before the readiness sentinel. A PTY
-  // spawned before the augmenter exists can never receive ORCA_AGENT_HOOK_*
-  // later, so success registers the augmenter first; failure is the deliberate
-  // fail-open path where agent status is disabled for this relay process.
+  // Why: await the hook-server bind before announcing readiness so the very
+  // first PTY spawn (which can land within milliseconds of the sentinel)
+  // already sees populated ORCA_AGENT_HOOK_* env. The bind is a local-loopback
+  // listen — measured in ms — so the latency cost is trivial and removes a
+  // class of "first agent invocation has no status" races. Bind failure is
+  // treated as soft: log and continue, the augmenter returns {} and agent
+  // status simply does not flow.
   try {
     await hookServer.start()
-    ptyHandler.addEnvAugmenter(() => hookServer.buildPtyEnv())
   } catch (err) {
     process.stderr.write(
       `[relay] agent-hook server failed to start: ${err instanceof Error ? err.message : String(err)}\n`
     )
   }
 
-  // Why: evict the per-pane last-status cache when the backing PTY exits so
-  // a terminated pane's last working/done payload cannot resurface as a
-  // ghost event after a later reconnect — see §5 Path 3.
-  ptyHandler.setExitListener(({ paneKey }) => {
+  // Why: every relay-spawned PTY needs the live ORCA_AGENT_HOOK_* coords. The
+  // augmenter is read on every spawn so a hook-server bind that succeeded
+  // late (or after a stop/start) lands in the next PTY's env without a
+  // restart.
+  ptyHandler.addEnvAugmenter(() => hookServer.buildPtyEnv())
+
+  // Why: per-PTY plugin overlays for OpenCode and Pi. `OPENCODE_CONFIG_DIR`
+  // and `PI_CODING_AGENT_DIR` only make sense on the relay's own filesystem
+  // — paths the renderer would synthesize for the Orca host's userData are
+  // meaningless on the remote. The overlay manager materializes a per-PTY
+  // dir on the remote (rooted at $HOME/.orca-relay/) so the agent CLI inside
+  // the relay-spawned PTY loads the bundled status plugin and posts to the
+  // relay's hook server. Source bodies arrive over JSON-RPC (see
+  // `agent_hook.installPlugins` below) — not bundled with the relay binary.
+  const pluginOverlay = new PluginOverlayManager()
+  ptyHandler.addEnvAugmenter((ctx) => {
+    const env: Record<string, string> = {}
+    // Why: prefer paneKey for overlay identity so a renderer-side remount
+    // that reuses the paneKey lands in the same overlay dir. Falls back to
+    // the relay-internal pty-id when paneKey is absent (e.g. CLI-launched
+    // PTYs that don't go through the renderer).
+    const overlayId = ctx.paneKey ?? ctx.id
+    if (pluginOverlay.hasOpenCodeSource()) {
+      const sourceDir = resolveOpenCodeSourceConfigDir(ctx.env, ctx.shell)
+      const dir = pluginOverlay.materializeOpenCode(overlayId, sourceDir)
+      if (dir) {
+        env.OPENCODE_CONFIG_DIR = dir
+        env.ORCA_OPENCODE_CONFIG_DIR = dir
+        if (sourceDir) {
+          env.ORCA_OPENCODE_SOURCE_CONFIG_DIR = sourceDir
+        }
+      }
+    }
+    if (pluginOverlay.hasPiSource()) {
+      const sourceDir = resolvePiSourceAgentDir(ctx.env, ctx.shell)
+      const dir = pluginOverlay.materializePi(overlayId, sourceDir)
+      if (dir) {
+        env.PI_CODING_AGENT_DIR = dir
+        env.ORCA_PI_CODING_AGENT_DIR = dir
+        if (sourceDir) {
+          env.ORCA_PI_SOURCE_AGENT_DIR = sourceDir
+        }
+      }
+    }
+    return env
+  })
+
+  // Why: evict the per-pane last-status cache AND any plugin overlay dirs
+  // when the backing PTY exits so terminated panes do not (a) resurface as
+  // ghost events after a later reconnect (§5 Path 3) or (b) leak overlay
+  // dirs on a long-lived relay.
+  ptyHandler.setExitListener(({ paneKey, id }) => {
     if (paneKey) {
       hookServer.clearPaneState(paneKey)
     }
+    pluginOverlay.clearOverlay(paneKey ?? id)
   })
 
   // Why: request-driven replay. Orca issues this *after* it re-wires the
@@ -280,12 +339,31 @@ async function main(): Promise<void> {
     return { replayed }
   })
 
-  // Why: stub for the plugin-source sync handler used by OpenCode/Pi. The
-  // real implementation is wired in commit #7 (deferred to keep this commit
-  // tight). Stubbed out here as a method-found handler so a probing client
-  // can detect support without -32601 noise on first connect.
-  dispatcher.onRequest(AGENT_HOOK_INSTALL_PLUGINS_METHOD, async () => {
-    return { installed: false }
+  // Why: Orca ships the OpenCode plugin / Pi extension source bodies over
+  // the wire at session-ready (the renderer's bundled hook-service strings
+  // change as new agent events are added — pinning them to the relay binary
+  // would force a relay redeploy on every Orca update). Cache them so each
+  // subsequent PTY spawn can materialize a per-PTY overlay rooted under
+  // $HOME/.orca-relay/. See docs/design/agent-status-over-ssh.md §4.
+  // Why: bound the per-source size so a buggy/hostile Orca can't OOM the
+  // relay by pushing a giant string. The HTTP path has HOOK_REQUEST_MAX_BYTES
+  // = 1 MB; the JSON-RPC path needs an equivalent ceiling. Real plugin sources
+  // are <50 KB today; 256 KB leaves generous headroom.
+  dispatcher.onRequest(AGENT_HOOK_INSTALL_PLUGINS_METHOD, async (params) => {
+    const opencode = params.opencodePluginSource
+    const pi = params.piExtensionSource
+    assertPluginSourceUnderByteCap('opencodePluginSource', opencode)
+    assertPluginSourceUnderByteCap('piExtensionSource', pi)
+    pluginOverlay.setSources({
+      opencodePluginSource: typeof opencode === 'string' ? opencode : undefined,
+      piExtensionSource: typeof pi === 'string' ? pi : undefined
+    })
+    return {
+      installed: {
+        opencode: pluginOverlay.hasOpenCodeSource(),
+        pi: pluginOverlay.hasPiSource()
+      }
+    }
   })
 
   // ── Socket server for reconnection ──────────────────────────────────
@@ -488,7 +566,7 @@ function cleanupSocket(sockPath: string): void {
 
 void main().catch((err) => {
   process.stderr.write(
-    `[relay] Fatal startup error: ${err instanceof Error ? err.message : String(err)}\n`
+    `[relay] Fatal startup error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`
   )
   process.exit(1)
 })
diff --git a/src/shared/agent-hook-listener.ts b/src/shared/agent-hook-listener.ts
index f8469ee723d..f2887b30846 100644
--- a/src/shared/agent-hook-listener.ts
+++ b/src/shared/agent-hook-listener.ts
@@ -42,7 +42,9 @@ const MAX_WARNED_KEYS = 32
 export const HOOK_REQUEST_SLOWLORIS_MS = 5_000
 
 /** Bound paneKey size — `${tabId}:${paneId}` is well under 200 chars in
- *  practice; cap defends per-pane caches against pathological input. */
+ *  practice; cap defends per-pane caches against pathological input.
+ *  Exported so non-HTTP ingest paths (e.g. Orca's `ingestRemote`) can apply
+ *  the same cap as defense-in-depth. */
 export const MAX_PANE_KEY_LEN = 200
 
 /** Per-listener-instance state that holds caches needing per-PTY teardown
diff --git a/tests/e2e/ssh-localhost.spec.ts b/tests/e2e/ssh-localhost.spec.ts
index 14747355cc0..75aae779999 100644
--- a/tests/e2e/ssh-localhost.spec.ts
+++ b/tests/e2e/ssh-localhost.spec.ts
@@ -1,5 +1,4 @@
 import os from 'os'
-import path from 'path'
 
 import { test, expect } from './helpers/orca-app'
 import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
@@ -204,27 +203,6 @@ test.describe('Localhost SSH', () => {
     await execInTerminal(orcaPage, ptyId, emitMarkerCommand(terminalMarker))
     await waitForTerminalOutput(orcaPage, terminalMarker, 20_000)
 
-    // Why: managed hook scripts intentionally ignore Electron userData so
-    // dev/prod Orca instances converge on the same installed command.
-    const codexHookPath = path.join(os.homedir(), '.orca', 'agent-hooks', 'codex-hook.sh')
-    const quotedCodexHookPath = shellQuote(codexHookPath)
-    const codexHookStatus = await orcaPage.evaluate(() => window.api.agentHooks.codexStatus())
-    expect(codexHookStatus.state).toBe('installed')
-    const installMarker = marker('CODEX_HOOK_INSTALLED')
-    const installFailedMarker = marker('CODEX_HOOK_INSTALL_FAILED')
-    await execInTerminal(
-      orcaPage,
-      ptyId,
-      [
-        `if [ -x ${quotedCodexHookPath} ] && grep -F ${quotedCodexHookPath} "$HOME/.codex/hooks.json" >/dev/null 2>&1; then`,
-        `  ${emitMarkerCommand(installMarker)}`,
-        'else',
-        `  ${emitMarkerCommand(installFailedMarker)}`,
-        'fi'
-      ].join('\n')
-    )
-    await waitForTerminalOutput(orcaPage, installMarker, 20_000)
-
     const envMarker = marker('AGENT_HOOK_ENV_OK')
     const envFailedMarker = marker('AGENT_HOOK_ENV_BAD')
     await execInTerminal(
@@ -241,25 +219,44 @@ test.describe('Localhost SSH', () => {
     )
     await waitForTerminalOutput(orcaPage, envMarker, 20_000)
 
-    const prompt = `orca ssh e2e prompt ${Date.now()}`
-    const hookPostedMarker = marker('AGENT_HOOK_POSTED')
-    const hookPayloadFile = `/tmp/orca-e2e-hook-payload-${Date.now()}.json`
+    const pluginOverlayMarker = marker('AGENT_PLUGIN_OVERLAYS_OK')
+    const pluginOverlayFailedMarker = marker('AGENT_PLUGIN_OVERLAYS_BAD')
     await execInTerminal(
       orcaPage,
       ptyId,
       [
-        `if [ ! -x ${quotedCodexHookPath} ]; then`,
-        '  echo __ORCA_CODEX_HOOK_SCRIPT_MISSING__',
-        'elif [ -z "$ORCA_AGENT_HOOK_PORT" ] || [ -z "$ORCA_AGENT_HOOK_TOKEN" ] || [ -z "$ORCA_PANE_KEY" ]; then',
+        'opencode_status_file="$OPENCODE_CONFIG_DIR/plugins/orca-opencode-status.js"',
+        'pi_status_file="$PI_CODING_AGENT_DIR/extensions/orca-agent-status.ts"',
+        'if [ -n "$OPENCODE_CONFIG_DIR" ] && [ -f "$opencode_status_file" ] && [ -n "$PI_CODING_AGENT_DIR" ] && [ -f "$pi_status_file" ]; then',
+        `  ${emitMarkerCommand(pluginOverlayMarker)}`,
+        'else',
+        `  printf '%s opencode=%s opencode_file=%s pi=%s pi_file=%s\\n' ${shellQuote(pluginOverlayFailedMarker)} "$OPENCODE_CONFIG_DIR" "$opencode_status_file" "$PI_CODING_AGENT_DIR" "$pi_status_file"`,
+        'fi'
+      ].join('\n')
+    )
+    await waitForTerminalOutput(orcaPage, pluginOverlayMarker, 20_000)
+
+    const prompt = `orca ssh e2e prompt ${Date.now()}`
+    const hookPostedMarker = marker('AGENT_HOOK_POSTED')
+    await execInTerminal(
+      orcaPage,
+      ptyId,
+      [
+        'if [ -z "$ORCA_AGENT_HOOK_PORT" ] || [ -z "$ORCA_AGENT_HOOK_TOKEN" ] || [ -z "$ORCA_PANE_KEY" ]; then',
         '  echo __ORCA_AGENT_HOOK_ENV_MISSING__',
         'else',
-        `  printf '%s' ${shellQuote(
-          JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt })
-        )} > ${shellQuote(hookPayloadFile)}`,
-        `  /bin/sh ${quotedCodexHookPath} < ${shellQuote(hookPayloadFile)}`,
-        '  hook_status=$?',
-        `  rm -f ${shellQuote(hookPayloadFile)}`,
-        `  if [ "$hook_status" -eq 0 ]; then ${emitMarkerCommand(hookPostedMarker)}; fi`,
+        `  hook_payload=${shellQuote(JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt }))}`,
+        '  if curl -sS -X POST "http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/codex" \\',
+        '    -H "Content-Type: application/x-www-form-urlencoded" \\',
+        '    -H "X-Orca-Agent-Hook-Token: ${ORCA_AGENT_HOOK_TOKEN}" \\',
+        '    --data-urlencode "paneKey=${ORCA_PANE_KEY}" \\',
+        '    --data-urlencode "tabId=${ORCA_TAB_ID}" \\',
+        '    --data-urlencode "worktreeId=${ORCA_WORKTREE_ID}" \\',
+        '    --data-urlencode "env=${ORCA_AGENT_HOOK_ENV}" \\',
+        '    --data-urlencode "version=${ORCA_AGENT_HOOK_VERSION}" \\',
+        '    --data-urlencode "payload=${hook_payload}" >/dev/null; then',
+        `    ${emitMarkerCommand(hookPostedMarker)}`,
+        '  fi',
         'fi'
       ].join('\n')
     )

From cb58b109e0df43aa590fed44f9d1f430e3fe5c1b Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 14 May 2026 17:29:58 -0700
Subject: [PATCH 04/82] feat: add workspace space analyzer (#1877)

---
 .gitignore                                    |   3 +
 .../macos-computer-use-permissions.test.ts    |  27 +
 .../macos-computer-use-permissions.ts         |  45 +-
 src/main/ipc/register-core-handlers.test.ts   |  12 +-
 src/main/ipc/register-core-handlers.ts        |   2 +
 src/main/ipc/workspace-space.test.ts          |  69 ++
 src/main/ipc/workspace-space.ts               |  19 +
 src/main/workspace-space-analysis.test.ts     | 239 ++++++
 src/main/workspace-space-analysis.ts          | 689 ++++++++++++++++++
 src/preload/api-types.ts                      |   4 +
 src/preload/index.ts                          |   5 +
 src/renderer/src/App.tsx                      |  27 +-
 .../onboarding-feature-setup.test.ts          |   4 +
 .../components/settings/AppearancePane.tsx    |  20 +-
 .../components/settings/ComputerUsePane.tsx   |  27 +-
 .../sidebar/DeleteWorktreeDialog.tsx          |  20 +-
 .../sidebar/delete-worktree-flow.test.ts      |  31 +-
 .../sidebar/delete-worktree-flow.ts           |  53 +-
 src/renderer/src/components/sidebar/index.tsx |   2 -
 .../status-bar/ResourceUsageStatusSegment.tsx |  24 +-
 .../src/components/status-bar/StatusBar.tsx   |   2 +-
 .../status-bar/WorkspaceSpaceCompactPanel.tsx |  92 +++
 .../status-bar/WorkspaceSpaceManagerPanel.tsx | 685 +++++++++++++++++
 .../status-bar/mergeSnapshotAndSessions.ts    |   2 +-
 .../status-bar/workspace-space-format.test.ts |  21 +
 .../status-bar/workspace-space-format.ts      |  59 ++
 .../status-bar/workspace-space-layout.test.ts |  24 +
 .../status-bar/workspace-space-layout.ts      | 124 ++++
 .../workspace-space-presentation.test.ts      |  79 ++
 .../workspace-space-presentation.ts           |  78 ++
 .../workspace-space/WorkspaceSpacePage.tsx    |  59 ++
 src/renderer/src/hooks/resolve-zoom-target.ts |   2 +-
 src/renderer/src/store/index.ts               |   2 +
 .../src/store/slices/diffComments.test.ts     |   2 +
 src/renderer/src/store/slices/memory.ts       |   2 +-
 .../slices/store-session-cascades.test.ts     |   2 +
 .../src/store/slices/store-test-helpers.ts    |   2 +
 src/renderer/src/store/slices/tabs.test.ts    |   2 +
 src/renderer/src/store/slices/ui.test.ts      |  30 +
 src/renderer/src/store/slices/ui.ts           |  24 +-
 .../src/store/slices/workspace-space.ts       |  96 +++
 src/renderer/src/store/types.ts               |   2 +
 src/shared/computer-use-permissions-types.ts  |   2 +
 src/shared/workspace-space-types.ts           |  63 ++
 44 files changed, 2682 insertions(+), 96 deletions(-)
 create mode 100644 src/main/ipc/workspace-space.test.ts
 create mode 100644 src/main/ipc/workspace-space.ts
 create mode 100644 src/main/workspace-space-analysis.test.ts
 create mode 100644 src/main/workspace-space-analysis.ts
 create mode 100644 src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx
 create mode 100644 src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
 create mode 100644 src/renderer/src/components/status-bar/workspace-space-format.test.ts
 create mode 100644 src/renderer/src/components/status-bar/workspace-space-format.ts
 create mode 100644 src/renderer/src/components/status-bar/workspace-space-layout.test.ts
 create mode 100644 src/renderer/src/components/status-bar/workspace-space-layout.ts
 create mode 100644 src/renderer/src/components/status-bar/workspace-space-presentation.test.ts
 create mode 100644 src/renderer/src/components/status-bar/workspace-space-presentation.ts
 create mode 100644 src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx
 create mode 100644 src/renderer/src/store/slices/workspace-space.ts
 create mode 100644 src/shared/workspace-space-types.ts

diff --git a/.gitignore b/.gitignore
index 28e3868ff1c..2afd28d2a43 100644
--- a/.gitignore
+++ b/.gitignore
@@ -87,3 +87,6 @@ playwright-report/
 /.claude/skills/
 /.agents/skills/
 /skills-lock.json
+
+# Agent hook runtime endpoints (machine-local secrets)
+/agent-hooks/
diff --git a/src/main/computer/macos-computer-use-permissions.test.ts b/src/main/computer/macos-computer-use-permissions.test.ts
index 8345965c056..2f78b3cab23 100644
--- a/src/main/computer/macos-computer-use-permissions.test.ts
+++ b/src/main/computer/macos-computer-use-permissions.test.ts
@@ -135,6 +135,15 @@ describe('openComputerUsePermissions', () => {
     expect(() => openComputerUsePermissions()).toThrow('Orca Computer Use.app was not found')
   })
 
+  it('throws when the helper executable is missing during setup', () => {
+    resolveHelperAppPathMock.mockReturnValue('/Applications/Orca Computer Use.app')
+    resolveHelperExecutablePathMock.mockReturnValue(null)
+
+    expect(() => openComputerUsePermissions('accessibility')).toThrow(
+      '/Applications/Orca Computer Use.app/Contents/MacOS/orca-computer-use-macos was not found'
+    )
+  })
+
   it('reads permission status through the helper app executable', async () => {
     const { getComputerUsePermissionStatus } = await import('./macos-computer-use-permissions')
     resolveHelperAppPathMock.mockReturnValue('/Applications/Orca Computer Use.app')
@@ -142,6 +151,8 @@ describe('openComputerUsePermissions', () => {
 
     expect(getComputerUsePermissionStatus()).toEqual({
       platform: 'darwin',
+      helperAppPath: '/Applications/Orca Computer Use.app',
+      helperUnavailableReason: null,
       permissions: [
         { id: 'accessibility', status: 'granted' },
         { id: 'screenshots', status: 'not-granted' }
@@ -153,6 +164,22 @@ describe('openComputerUsePermissions', () => {
       { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
     )
   })
+
+  it('returns unavailable permission status when the helper app is missing on macOS', async () => {
+    const { getComputerUsePermissionStatus } = await import('./macos-computer-use-permissions')
+    resolveHelperAppPathMock.mockReturnValue(null)
+
+    expect(getComputerUsePermissionStatus()).toEqual({
+      platform: 'darwin',
+      helperAppPath: null,
+      helperUnavailableReason: 'Orca Computer Use.app was not found',
+      permissions: [
+        { id: 'accessibility', status: 'not-granted' },
+        { id: 'screenshots', status: 'not-granted' }
+      ]
+    })
+    expect(execFileSync).not.toHaveBeenCalled()
+  })
 })
 
 function mockPermissionStatus(json: string): void {
diff --git a/src/main/computer/macos-computer-use-permissions.ts b/src/main/computer/macos-computer-use-permissions.ts
index 3de460eb29b..9ec40ef2d7d 100644
--- a/src/main/computer/macos-computer-use-permissions.ts
+++ b/src/main/computer/macos-computer-use-permissions.ts
@@ -34,6 +34,9 @@ export function openComputerUsePermissions(
     throw new RuntimeClientError('accessibility_error', 'Orca Computer Use.app was not found')
   }
   const status = getComputerUsePermissionStatus()
+  if (status.helperUnavailableReason) {
+    throw new RuntimeClientError('accessibility_error', status.helperUnavailableReason)
+  }
   const nextStep = nextPermissionStep(status.permissions)
 
   if (!permissionId && !nextStep) {
@@ -80,6 +83,8 @@ export function getComputerUsePermissionStatus(): ComputerUsePermissionStatusRes
   if (process.platform !== 'darwin') {
     return {
       platform: process.platform,
+      helperAppPath: null,
+      helperUnavailableReason: null,
       permissions: [
         { id: 'accessibility', status: 'unsupported' },
         { id: 'screenshots', status: 'unsupported' }
@@ -89,13 +94,23 @@ export function getComputerUsePermissionStatus(): ComputerUsePermissionStatusRes
 
   const helperAppPath = resolveMacOSComputerUseAppPath()
   if (!helperAppPath) {
-    throw new RuntimeClientError('accessibility_error', 'Orca Computer Use.app was not found')
+    return createUnavailablePermissionStatus('Orca Computer Use.app was not found', null)
   }
 
-  const raw = readPermissionStatusFromHelperApp(helperAppPath)
+  const executablePath = resolveMacOSComputerUseExecutablePath()
+  if (!executablePath) {
+    return createUnavailablePermissionStatus(
+      `${helperAppPath}/Contents/MacOS/orca-computer-use-macos was not found`,
+      helperAppPath
+    )
+  }
+
+  const raw = readPermissionStatusFromHelperExecutable(executablePath)
 
   return {
     platform: process.platform,
+    helperAppPath,
+    helperUnavailableReason: null,
     permissions: [
       { id: 'accessibility', status: raw.accessibility ?? 'not-granted' },
       { id: 'screenshots', status: raw.screenshots ?? 'not-granted' }
@@ -103,16 +118,24 @@ export function getComputerUsePermissionStatus(): ComputerUsePermissionStatusRes
   }
 }
 
-function readPermissionStatusFromHelperApp(
-  helperAppPath: string
-): Partial<Record<ComputerUsePermissionId, ComputerUsePermissionStatus>> {
-  const executablePath = resolveMacOSComputerUseExecutablePath()
-  if (!executablePath) {
-    throw new RuntimeClientError(
-      'accessibility_error',
-      `${helperAppPath}/Contents/MacOS/orca-computer-use-macos was not found`
-    )
+function createUnavailablePermissionStatus(
+  reason: string,
+  helperAppPath: string | null
+): ComputerUsePermissionStatusResult {
+  return {
+    platform: process.platform,
+    helperAppPath,
+    helperUnavailableReason: reason,
+    permissions: [
+      { id: 'accessibility', status: 'not-granted' },
+      { id: 'screenshots', status: 'not-granted' }
+    ]
   }
+}
+
+function readPermissionStatusFromHelperExecutable(
+  executablePath: string
+): Partial<Record<ComputerUsePermissionId, ComputerUsePermissionStatus>> {
   // Why: launching the nested helper via LaunchServices can make TCC evaluate
   // Orca.app as responsible; the signed helper executable owns this grant.
   const output = execFileSync(executablePath, ['--permission-status'], {
diff --git a/src/main/ipc/register-core-handlers.test.ts b/src/main/ipc/register-core-handlers.test.ts
index 94897ad71dd..eb6fdd43d6a 100644
--- a/src/main/ipc/register-core-handlers.test.ts
+++ b/src/main/ipc/register-core-handlers.test.ts
@@ -41,7 +41,8 @@ const {
   registerHostedReviewHandlersMock,
   registerExportHandlersMock,
   registerOnboardingHandlersMock,
-  registerSpeechHandlersMock
+  registerSpeechHandlersMock,
+  registerWorkspaceSpaceHandlersMock
 } = vi.hoisted(() => ({
   registerCliHandlersMock: vi.fn(),
   registerPreflightHandlersMock: vi.fn(),
@@ -81,7 +82,8 @@ const {
   registerHostedReviewHandlersMock: vi.fn(),
   registerExportHandlersMock: vi.fn(),
   registerOnboardingHandlersMock: vi.fn(),
-  registerSpeechHandlersMock: vi.fn()
+  registerSpeechHandlersMock: vi.fn(),
+  registerWorkspaceSpaceHandlersMock: vi.fn()
 }))
 
 vi.mock('./onboarding', () => ({
@@ -152,6 +154,10 @@ vi.mock('./settings', () => ({
   registerSettingsHandlers: registerSettingsHandlersMock
 }))
 
+vi.mock('./workspace-space', () => ({
+  registerWorkspaceSpaceHandlers: registerWorkspaceSpaceHandlersMock
+}))
+
 vi.mock('./telemetry', () => ({
   registerTelemetryHandlers: registerTelemetryHandlersMock
 }))
@@ -273,6 +279,7 @@ describe('registerCoreHandlers', () => {
     registerHostedReviewHandlersMock.mockReset()
     registerExportHandlersMock.mockReset()
     registerSpeechHandlersMock.mockReset()
+    registerWorkspaceSpaceHandlersMock.mockReset()
   })
 
   it('passes the store through to handler registrars that need it', () => {
@@ -315,6 +322,7 @@ describe('registerCoreHandlers', () => {
     expect(registerDeveloperPermissionHandlersMock).toHaveBeenCalled()
     expect(registerComputerUsePermissionHandlersMock).toHaveBeenCalled()
     expect(registerSettingsHandlersMock).toHaveBeenCalledWith(store)
+    expect(registerWorkspaceSpaceHandlersMock).toHaveBeenCalledWith(store)
     expect(registerTelemetryHandlersMock).toHaveBeenCalledWith(store)
     expect(registerSessionHandlersMock).toHaveBeenCalledWith(store)
     expect(registerUIHandlersMock).toHaveBeenCalledWith(store)
diff --git a/src/main/ipc/register-core-handlers.ts b/src/main/ipc/register-core-handlers.ts
index ca013544ad9..e445a8e659f 100644
--- a/src/main/ipc/register-core-handlers.ts
+++ b/src/main/ipc/register-core-handlers.ts
@@ -27,6 +27,7 @@ import { registerComputerUsePermissionHandlers } from './computer-use-permission
 import { setTrustedBrowserRendererWebContentsId, setAgentBrowserBridgeRef } from './browser'
 import { registerSessionHandlers } from './session'
 import { registerSettingsHandlers } from './settings'
+import { registerWorkspaceSpaceHandlers } from './workspace-space'
 import { registerAutomationHandlers } from './automations'
 import { registerTelemetryHandlers } from './telemetry'
 import { registerBrowserHandlers } from './browser'
@@ -115,6 +116,7 @@ export function registerCoreHandlers(
   registerPetHandlers()
   registerSessionHandlers(store)
   registerUIHandlers(store)
+  registerWorkspaceSpaceHandlers(store)
   registerFilesystemHandlers(store)
   registerFilesystemWatcherHandlers()
   registerRuntimeHandlers(runtime)
diff --git a/src/main/ipc/workspace-space.test.ts b/src/main/ipc/workspace-space.test.ts
new file mode 100644
index 00000000000..24f590786d8
--- /dev/null
+++ b/src/main/ipc/workspace-space.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { WorkspaceSpaceAnalysis } from '../../shared/workspace-space-types'
+import type { Store } from '../persistence'
+
+const { handlers, analyzeWorkspaceSpaceMock, removeHandlerMock, handleMock } = vi.hoisted(() => ({
+  handlers: new Map<string, () => Promise<WorkspaceSpaceAnalysis>>(),
+  analyzeWorkspaceSpaceMock: vi.fn(),
+  removeHandlerMock: vi.fn(),
+  handleMock: vi.fn((channel: string, handler: () => Promise<WorkspaceSpaceAnalysis>) => {
+    handlers.set(channel, handler)
+  })
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    removeHandler: removeHandlerMock,
+    handle: handleMock
+  }
+}))
+
+vi.mock('../workspace-space-analysis', () => ({
+  analyzeWorkspaceSpace: analyzeWorkspaceSpaceMock
+}))
+
+import { registerWorkspaceSpaceHandlers } from './workspace-space'
+
+function createAnalysis(scannedAt: number): WorkspaceSpaceAnalysis {
+  return {
+    scannedAt,
+    totalSizeBytes: 0,
+    reclaimableBytes: 0,
+    worktreeCount: 0,
+    scannedWorktreeCount: 0,
+    unavailableWorktreeCount: 0,
+    repos: [],
+    worktrees: []
+  }
+}
+
+describe('registerWorkspaceSpaceHandlers', () => {
+  it('shares an in-flight analysis request', async () => {
+    const store = {} as Store
+    let resolveFirstScan: (analysis: WorkspaceSpaceAnalysis) => void = () => {}
+    const firstScan = new Promise<WorkspaceSpaceAnalysis>((resolve) => {
+      resolveFirstScan = resolve
+    })
+    const secondScan = Promise.resolve(createAnalysis(2))
+    analyzeWorkspaceSpaceMock.mockReturnValueOnce(firstScan).mockReturnValueOnce(secondScan)
+
+    registerWorkspaceSpaceHandlers(store)
+    expect(removeHandlerMock).toHaveBeenCalledWith('workspaceSpace:analyze')
+
+    const handler = handlers.get('workspaceSpace:analyze')
+    expect(handler).toBeDefined()
+
+    const first = handler!()
+    const duplicate = handler!()
+    expect(analyzeWorkspaceSpaceMock).toHaveBeenCalledTimes(1)
+    expect(analyzeWorkspaceSpaceMock).toHaveBeenCalledWith(store)
+
+    const firstResult = createAnalysis(1)
+    resolveFirstScan(firstResult)
+    await expect(first).resolves.toBe(firstResult)
+    await expect(duplicate).resolves.toBe(firstResult)
+
+    await expect(handler!()).resolves.toEqual(createAnalysis(2))
+    expect(analyzeWorkspaceSpaceMock).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/src/main/ipc/workspace-space.ts b/src/main/ipc/workspace-space.ts
new file mode 100644
index 00000000000..8302503bdf8
--- /dev/null
+++ b/src/main/ipc/workspace-space.ts
@@ -0,0 +1,19 @@
+import { ipcMain } from 'electron'
+import type { Store } from '../persistence'
+import type { WorkspaceSpaceAnalysis } from '../../shared/workspace-space-types'
+import { analyzeWorkspaceSpace } from '../workspace-space-analysis'
+
+export function registerWorkspaceSpaceHandlers(store: Store): void {
+  let inFlightScan: Promise<WorkspaceSpaceAnalysis> | null = null
+  ipcMain.removeHandler('workspaceSpace:analyze')
+  ipcMain.handle('workspaceSpace:analyze', async (): Promise<WorkspaceSpaceAnalysis> => {
+    if (!inFlightScan) {
+      // Why: large worktree fleets require real disk traversal; duplicate
+      // requests should share that IO instead of starting competing scans.
+      inFlightScan = analyzeWorkspaceSpace(store).finally(() => {
+        inFlightScan = null
+      })
+    }
+    return inFlightScan
+  })
+}
diff --git a/src/main/workspace-space-analysis.test.ts b/src/main/workspace-space-analysis.test.ts
new file mode 100644
index 00000000000..041219501c8
--- /dev/null
+++ b/src/main/workspace-space-analysis.test.ts
@@ -0,0 +1,239 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Repo } from '../shared/types'
+import type { Store } from './persistence'
+
+const { listRepoWorktreesMock, getSshFilesystemProviderMock, getSshGitProviderMock } = vi.hoisted(
+  () => ({
+    listRepoWorktreesMock: vi.fn(),
+    getSshFilesystemProviderMock: vi.fn(),
+    getSshGitProviderMock: vi.fn()
+  })
+)
+
+vi.mock('./repo-worktrees', () => ({
+  createFolderWorktree: (repo: Repo) => ({
+    path: repo.path,
+    head: '',
+    branch: '',
+    isBare: false,
+    isMainWorktree: true
+  }),
+  listRepoWorktrees: listRepoWorktreesMock
+}))
+
+vi.mock('./providers/ssh-filesystem-dispatch', () => ({
+  getSshFilesystemProvider: getSshFilesystemProviderMock
+}))
+
+vi.mock('./providers/ssh-git-dispatch', () => ({
+  getSshGitProvider: getSshGitProviderMock
+}))
+
+import { analyzeWorkspaceSpace } from './workspace-space-analysis'
+
+function createStore(repos: Repo[]): Store {
+  return {
+    getRepos: () => repos,
+    getWorktreeMeta: (worktreeId: string) => {
+      if (worktreeId.endsWith('feature')) {
+        return { displayName: 'Feature Workspace', lastActivityAt: 200 }
+      }
+      return undefined
+    }
+  } as Store
+}
+
+async function writeSizedFile(filePath: string, size: number): Promise<void> {
+  await writeFile(filePath, Buffer.alloc(size, 1))
+}
+
+describe('analyzeWorkspaceSpace', () => {
+  let tempDir: string | null = null
+
+  beforeEach(async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-05-14T12:00:00Z'))
+    tempDir = await mkdtemp(join(tmpdir(), 'orca-space-'))
+    listRepoWorktreesMock.mockReset()
+    getSshFilesystemProviderMock.mockReset()
+    getSshGitProviderMock.mockReset()
+  })
+
+  afterEach(async () => {
+    vi.useRealTimers()
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true })
+      tempDir = null
+    }
+  })
+
+  it('scans local worktrees and counts only linked worktrees as reclaimable', async () => {
+    const root = tempDir!
+    const mainPath = join(root, 'repo')
+    const featurePath = join(root, 'feature')
+    await mkdir(join(mainPath, 'src'), { recursive: true })
+    await mkdir(join(featurePath, 'node_modules'), { recursive: true })
+    await mkdir(join(featurePath, 'src'), { recursive: true })
+    await writeSizedFile(join(mainPath, 'src', 'main.ts'), 256)
+    await writeSizedFile(join(featurePath, 'node_modules', 'pkg.js'), 2048)
+    await writeSizedFile(join(featurePath, 'src', 'feature.ts'), 512)
+
+    const repo: Repo = {
+      id: 'repo-1',
+      path: mainPath,
+      displayName: 'orca',
+      badgeColor: '#000',
+      addedAt: 0
+    }
+    listRepoWorktreesMock.mockResolvedValue([
+      {
+        path: mainPath,
+        head: 'a',
+        branch: 'refs/heads/main',
+        isBare: false,
+        isMainWorktree: true
+      },
+      {
+        path: featurePath,
+        head: 'b',
+        branch: 'refs/heads/feature',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+
+    const result = await analyzeWorkspaceSpace(createStore([repo]))
+    const main = result.worktrees.find((row) => row.path === mainPath)
+    const feature = result.worktrees.find((row) => row.path === featurePath)
+
+    expect(result.scannedAt).toBe(Date.parse('2026-05-14T12:00:00Z'))
+    expect(result.worktreeCount).toBe(2)
+    expect(main?.status).toBe('ok')
+    expect(main?.canDelete).toBe(false)
+    expect(main?.reclaimableBytes).toBe(0)
+    expect(feature?.status).toBe('ok')
+    expect(feature?.displayName).toBe('Feature Workspace')
+    expect(feature?.canDelete).toBe(true)
+    expect(feature?.sizeBytes).toBeGreaterThanOrEqual(2048 + 512)
+    expect(feature?.reclaimableBytes).toBe(feature?.sizeBytes)
+    expect(feature?.topLevelItems[0]?.name).toBe('node_modules')
+    expect(result.reclaimableBytes).toBe(feature?.sizeBytes)
+  })
+
+  it('isolates missing worktrees as row-level scan failures', async () => {
+    const root = tempDir!
+    const repoPath = join(root, 'repo')
+    const missingPath = join(root, 'missing')
+    await mkdir(repoPath, { recursive: true })
+
+    const repo: Repo = {
+      id: 'repo-1',
+      path: repoPath,
+      displayName: 'orca',
+      badgeColor: '#000',
+      addedAt: 0
+    }
+    listRepoWorktreesMock.mockResolvedValue([
+      {
+        path: missingPath,
+        head: 'b',
+        branch: 'refs/heads/feature',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+
+    const result = await analyzeWorkspaceSpace(createStore([repo]))
+
+    expect(result.worktreeCount).toBe(1)
+    expect(result.scannedWorktreeCount).toBe(0)
+    expect(result.unavailableWorktreeCount).toBe(1)
+    expect(result.worktrees[0]?.status).toBe('missing')
+    expect(result.worktrees[0]?.sizeBytes).toBe(0)
+  })
+
+  it('scans SSH worktrees through the remote filesystem provider without following symlinks', async () => {
+    const repo: Repo = {
+      id: 'repo-remote',
+      path: '/remote/repo',
+      displayName: 'remote',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'ssh-1'
+    }
+    getSshGitProviderMock.mockReturnValue({
+      listWorktrees: vi.fn().mockResolvedValue([
+        {
+          path: '/remote/feature',
+          head: 'c',
+          branch: 'refs/heads/feature',
+          isBare: false,
+          isMainWorktree: false
+        }
+      ])
+    })
+
+    const statByPath = new Map([
+      ['/remote/feature', { size: 10, type: 'directory' as const, mtime: 0 }],
+      ['/remote/feature/node_modules', { size: 5, type: 'directory' as const, mtime: 0 }],
+      ['/remote/feature/node_modules/pkg.js', { size: 1000, type: 'file' as const, mtime: 0 }],
+      ['/remote/feature/file.log', { size: 200, type: 'file' as const, mtime: 0 }]
+    ])
+    const readDirMock = vi.fn(async (dirPath: string) => {
+      if (dirPath === '/remote/feature') {
+        return [
+          { name: 'node_modules', isDirectory: true, isSymlink: false },
+          { name: 'linked-cache', isDirectory: true, isSymlink: true },
+          { name: 'file.log', isDirectory: false, isSymlink: false }
+        ]
+      }
+      if (dirPath === '/remote/feature/node_modules') {
+        return [{ name: 'pkg.js', isDirectory: false, isSymlink: false }]
+      }
+      return []
+    })
+    const statMock = vi.fn(async (filePath: string) => {
+      const stat = statByPath.get(filePath)
+      if (!stat) {
+        throw Object.assign(new Error(`missing ${filePath}`), { code: 'ENOENT' })
+      }
+      return stat
+    })
+    getSshFilesystemProviderMock.mockReturnValue({
+      readDir: readDirMock,
+      stat: statMock
+    })
+
+    const result = await analyzeWorkspaceSpace(createStore([repo]))
+
+    expect(result.worktrees[0]?.status).toBe('ok')
+    expect(result.worktrees[0]?.sizeBytes).toBe(1215)
+    expect(result.worktrees[0]?.topLevelItems.map((item) => item.name)).toEqual([
+      'node_modules',
+      'file.log',
+      'linked-cache'
+    ])
+    expect(statMock).not.toHaveBeenCalledWith('/remote/feature/linked-cache')
+  })
+
+  it('reports disconnected SSH repos without failing the whole analysis', async () => {
+    const repo: Repo = {
+      id: 'repo-remote',
+      path: '/remote/repo',
+      displayName: 'remote',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'ssh-1'
+    }
+    getSshGitProviderMock.mockReturnValue(undefined)
+
+    const result = await analyzeWorkspaceSpace(createStore([repo]))
+
+    expect(result.worktrees).toEqual([])
+    expect(result.repos[0]?.error).toContain('not connected')
+    expect(result.unavailableWorktreeCount).toBe(1)
+  })
+})
diff --git a/src/main/workspace-space-analysis.ts b/src/main/workspace-space-analysis.ts
new file mode 100644
index 00000000000..950f05c78bb
--- /dev/null
+++ b/src/main/workspace-space-analysis.ts
@@ -0,0 +1,689 @@
+/* eslint-disable max-lines -- Why: this module keeps local and SSH directory-walk
+   semantics paired so reclaimable-byte, symlink, and partial-failure behavior cannot drift. */
+import { lstat, readdir } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { basename, posix, win32 } from 'node:path'
+import { platform } from 'node:process'
+import { promisify } from 'node:util'
+import type { Dirent } from 'node:fs'
+import type { Store } from './persistence'
+import { isFolderRepo } from '../shared/repo-kind'
+import type { GitWorktreeInfo, Repo, Worktree } from '../shared/types'
+import type {
+  WorkspaceSpaceAnalysis,
+  WorkspaceSpaceItem,
+  WorkspaceSpaceItemKind,
+  WorkspaceSpaceRepoSummary,
+  WorkspaceSpaceScanStatus,
+  WorkspaceSpaceWorktree
+} from '../shared/workspace-space-types'
+import type { IFilesystemProvider } from './providers/types'
+import { getSshFilesystemProvider } from './providers/ssh-filesystem-dispatch'
+import { getSshGitProvider } from './providers/ssh-git-dispatch'
+import { createFolderWorktree, listRepoWorktrees } from './repo-worktrees'
+import { mergeWorktree } from './ipc/worktree-logic'
+
+const MAX_TOP_LEVEL_ITEMS = 48
+const WORKTREE_SCAN_CONCURRENCY = 3
+const LOCAL_FS_CONCURRENCY = 48
+const REMOTE_FS_CONCURRENCY = 10
+const DU_TIMEOUT_MS = 120_000
+const DU_MAX_BUFFER_BYTES = 16 * 1024 * 1024
+const execFileAsync = promisify(execFile)
+
+type AsyncLimiter = <T>(task: () => Promise<T>) => Promise<T>
+
+type ScanStats = {
+  name: string
+  path: string
+  kind: WorkspaceSpaceItemKind
+  sizeBytes: number
+  skippedEntryCount: number
+  children?: ScanStats[]
+}
+
+type WorktreeListResult =
+  | { ok: true; worktrees: GitWorktreeInfo[] }
+  | { ok: false; status: Exclude<WorkspaceSpaceScanStatus, 'ok'>; error: string }
+
+type RepoScanResult = {
+  summary: WorkspaceSpaceRepoSummary
+  worktrees: WorkspaceSpaceWorktree[]
+}
+
+function createAsyncLimiter(maxConcurrent: number): AsyncLimiter {
+  let active = 0
+  const queue: (() => void)[] = []
+
+  const acquire = async (): Promise<void> => {
+    if (active < maxConcurrent) {
+      active += 1
+      return
+    }
+    await new Promise<void>((resolve) => queue.push(resolve))
+    active += 1
+  }
+
+  return async <T>(task: () => Promise<T>): Promise<T> => {
+    await acquire()
+    try {
+      return await task()
+    } finally {
+      active -= 1
+      const next = queue.shift()
+      if (next) {
+        next()
+      }
+    }
+  }
+}
+
+async function mapLimit<T, R>(
+  items: readonly T[],
+  maxConcurrent: number,
+  mapper: (item: T) => Promise<R>
+): Promise<R[]> {
+  const limit = createAsyncLimiter(maxConcurrent)
+  return Promise.all(items.map((item) => limit(() => mapper(item))))
+}
+
+function looksLikeWindowsPath(pathValue: string): boolean {
+  return /^[A-Za-z]:[\\/]/.test(pathValue) || pathValue.startsWith('\\\\')
+}
+
+function joinFilesystemPath(parent: string, child: string): string {
+  return looksLikeWindowsPath(parent) ? win32.join(parent, child) : posix.join(parent, child)
+}
+
+function normalizeLocalDuPath(pathValue: string): string {
+  const trimmed = pathValue.replace(/[\\/]+$/, '')
+  return trimmed.length > 0 ? trimmed : pathValue
+}
+
+function parseDuDepthOneOutput(stdout: string): Map<string, number> {
+  const sizes = new Map<string, number>()
+  for (const line of stdout.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) {
+      continue
+    }
+    const match = /^(\d+)\s+(.+)$/.exec(trimmed)
+    if (!match) {
+      continue
+    }
+    sizes.set(normalizeLocalDuPath(match[2]), Number(match[1]) * 1024)
+  }
+  return sizes
+}
+
+async function readLocalDuDepthOne(rootPath: string): Promise<Map<string, number>> {
+  const { stdout } = await execFileAsync('du', ['-k', '-d', '1', rootPath], {
+    encoding: 'utf8',
+    maxBuffer: DU_MAX_BUFFER_BYTES,
+    timeout: DU_TIMEOUT_MS
+  })
+  return parseDuDepthOneOutput(stdout)
+}
+
+function classifyError(error: unknown): {
+  status: Exclude<WorkspaceSpaceScanStatus, 'ok'>
+  message: string
+} {
+  const code =
+    error && typeof error === 'object' && 'code' in error
+      ? String((error as { code?: unknown }).code)
+      : ''
+  const message = error instanceof Error ? error.message : String(error)
+
+  if (code === 'ENOENT' || code === 'ENOTDIR') {
+    return { status: 'missing', message }
+  }
+  if (code === 'EACCES' || code === 'EPERM') {
+    return { status: 'permission-denied', message }
+  }
+  return { status: 'error', message }
+}
+
+function toWorkspaceSpaceItem(stats: ScanStats): WorkspaceSpaceItem {
+  return {
+    name: stats.name,
+    path: stats.path,
+    kind: stats.kind,
+    sizeBytes: stats.sizeBytes
+  }
+}
+
+function compactTopLevelItems(items: WorkspaceSpaceItem[]): {
+  topLevelItems: WorkspaceSpaceItem[]
+  omittedTopLevelItemCount: number
+  omittedTopLevelSizeBytes: number
+} {
+  const sorted = [...items].sort(
+    (a, b) => b.sizeBytes - a.sizeBytes || a.name.localeCompare(b.name)
+  )
+  if (sorted.length <= MAX_TOP_LEVEL_ITEMS) {
+    return {
+      topLevelItems: sorted,
+      omittedTopLevelItemCount: 0,
+      omittedTopLevelSizeBytes: 0
+    }
+  }
+
+  const visible = sorted.slice(0, MAX_TOP_LEVEL_ITEMS - 1)
+  const omitted = sorted.slice(MAX_TOP_LEVEL_ITEMS - 1)
+  const other = omitted.reduce<WorkspaceSpaceItem>(
+    (acc, item) => ({
+      ...acc,
+      sizeBytes: acc.sizeBytes + item.sizeBytes
+    }),
+    {
+      name: 'Other',
+      path: '',
+      kind: 'other',
+      sizeBytes: 0
+    }
+  )
+
+  return {
+    topLevelItems: [...visible, other],
+    omittedTopLevelItemCount: omitted.length,
+    omittedTopLevelSizeBytes: other.sizeBytes
+  }
+}
+
+function createBaseWorktreeRow(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number
+): Omit<
+  WorkspaceSpaceWorktree,
+  | 'status'
+  | 'error'
+  | 'sizeBytes'
+  | 'reclaimableBytes'
+  | 'skippedEntryCount'
+  | 'topLevelItems'
+  | 'omittedTopLevelItemCount'
+  | 'omittedTopLevelSizeBytes'
+> {
+  const canDelete = !worktree.isMainWorktree
+  return {
+    worktreeId: worktree.id,
+    repoId: repo.id,
+    repoDisplayName: repo.displayName,
+    repoPath: repo.path,
+    displayName: worktree.displayName,
+    path: worktree.path,
+    branch: worktree.branch,
+    isMainWorktree: worktree.isMainWorktree,
+    isRemote: Boolean(repo.connectionId),
+    isSparse: worktree.isSparse === true,
+    canDelete,
+    lastActivityAt: worktree.lastActivityAt,
+    scannedAt
+  }
+}
+
+function createUnavailableWorktreeRow(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number,
+  status: Exclude<WorkspaceSpaceScanStatus, 'ok'>,
+  error: string
+): WorkspaceSpaceWorktree {
+  return {
+    ...createBaseWorktreeRow(repo, worktree, scannedAt),
+    status,
+    error,
+    sizeBytes: 0,
+    reclaimableBytes: 0,
+    skippedEntryCount: 0,
+    topLevelItems: [],
+    omittedTopLevelItemCount: 0,
+    omittedTopLevelSizeBytes: 0
+  }
+}
+
+async function scanLocalEntry(
+  entryPath: string,
+  name: string,
+  limit: AsyncLimiter
+): Promise<ScanStats> {
+  const stats = await limit(() => lstat(entryPath))
+
+  if (stats.isSymbolicLink()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'symlink',
+      // Why: symlink targets may be shared outside the worktree. Counting the
+      // link itself reflects what deleting this worktree can actually reclaim.
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  if (!stats.isDirectory()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'file',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  let entries: Dirent[]
+  try {
+    entries = await limit(() => readdir(entryPath, { withFileTypes: true }))
+  } catch {
+    return {
+      name,
+      path: entryPath,
+      kind: 'directory',
+      sizeBytes: stats.size,
+      skippedEntryCount: 1
+    }
+  }
+
+  const childStats = await Promise.all(
+    entries.map(async (entry): Promise<ScanStats | null> => {
+      try {
+        return await scanLocalEntry(joinFilesystemPath(entryPath, entry.name), entry.name, limit)
+      } catch {
+        return null
+      }
+    })
+  )
+
+  let sizeBytes = stats.size
+  let skippedEntryCount = 0
+  for (const child of childStats) {
+    if (!child) {
+      skippedEntryCount += 1
+      continue
+    }
+    sizeBytes += child.sizeBytes
+    skippedEntryCount += child.skippedEntryCount
+  }
+
+  return {
+    name,
+    path: entryPath,
+    kind: 'directory',
+    sizeBytes,
+    skippedEntryCount,
+    children: childStats.filter((child): child is ScanStats => child !== null)
+  }
+}
+
+async function scanRemoteEntry(
+  entryPath: string,
+  name: string,
+  provider: IFilesystemProvider,
+  limit: AsyncLimiter,
+  knownSymlink = false
+): Promise<ScanStats> {
+  if (knownSymlink) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'symlink',
+      sizeBytes: 0,
+      skippedEntryCount: 0
+    }
+  }
+
+  const stats = await limit(() => provider.stat(entryPath))
+  if (stats.type === 'symlink') {
+    return {
+      name,
+      path: entryPath,
+      kind: 'symlink',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  if (stats.type !== 'directory') {
+    return {
+      name,
+      path: entryPath,
+      kind: 'file',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  let entries
+  try {
+    entries = await limit(() => provider.readDir(entryPath))
+  } catch {
+    return {
+      name,
+      path: entryPath,
+      kind: 'directory',
+      sizeBytes: stats.size,
+      skippedEntryCount: 1
+    }
+  }
+
+  const childStats = await Promise.all(
+    entries.map(async (entry): Promise<ScanStats | null> => {
+      try {
+        return await scanRemoteEntry(
+          joinFilesystemPath(entryPath, entry.name),
+          entry.name,
+          provider,
+          limit,
+          entry.isSymlink
+        )
+      } catch {
+        return null
+      }
+    })
+  )
+
+  let sizeBytes = stats.size
+  let skippedEntryCount = 0
+  for (const child of childStats) {
+    if (!child) {
+      skippedEntryCount += 1
+      continue
+    }
+    sizeBytes += child.sizeBytes
+    skippedEntryCount += child.skippedEntryCount
+  }
+
+  return {
+    name,
+    path: entryPath,
+    kind: 'directory',
+    sizeBytes,
+    skippedEntryCount,
+    children: childStats.filter((child): child is ScanStats => child !== null)
+  }
+}
+
+async function scanLocalTopLevelEntry(
+  entryPath: string,
+  name: string,
+  duSizes: Map<string, number>,
+  limit: AsyncLimiter
+): Promise<ScanStats> {
+  const stats = await limit(() => lstat(entryPath))
+
+  if (stats.isSymbolicLink()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'symlink',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  if (!stats.isDirectory()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'file',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  return {
+    name,
+    path: entryPath,
+    kind: 'directory',
+    sizeBytes: duSizes.get(normalizeLocalDuPath(entryPath)) ?? stats.size,
+    skippedEntryCount: 0
+  }
+}
+
+async function scanLocalWorktreeWithDu(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number
+): Promise<WorkspaceSpaceWorktree> {
+  const rootStats = await lstat(worktree.path)
+  if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+    const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY)
+    const root = await scanLocalEntry(worktree.path, basename(worktree.path), limit)
+    const compact = compactTopLevelItems((root.children ?? []).map(toWorkspaceSpaceItem))
+    return {
+      ...createBaseWorktreeRow(repo, worktree, scannedAt),
+      status: 'ok',
+      error: null,
+      sizeBytes: root.sizeBytes,
+      reclaimableBytes: worktree.isMainWorktree ? 0 : root.sizeBytes,
+      skippedEntryCount: root.skippedEntryCount,
+      ...compact
+    }
+  }
+
+  const [entries, duSizes] = await Promise.all([
+    readdir(worktree.path, { withFileTypes: true }),
+    readLocalDuDepthOne(worktree.path)
+  ])
+  const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY)
+  const childStats = await Promise.all(
+    entries.map(async (entry): Promise<ScanStats | null> => {
+      try {
+        return await scanLocalTopLevelEntry(
+          joinFilesystemPath(worktree.path, entry.name),
+          entry.name,
+          duSizes,
+          limit
+        )
+      } catch {
+        return null
+      }
+    })
+  )
+  const children = childStats.filter((child): child is ScanStats => child !== null)
+  const skippedEntryCount = childStats.length - children.length
+  const rootSize =
+    duSizes.get(normalizeLocalDuPath(worktree.path)) ??
+    rootStats.size + children.reduce((sum, child) => sum + child.sizeBytes, 0)
+  const compact = compactTopLevelItems(children.map(toWorkspaceSpaceItem))
+
+  return {
+    ...createBaseWorktreeRow(repo, worktree, scannedAt),
+    status: 'ok',
+    error: null,
+    sizeBytes: rootSize,
+    reclaimableBytes: worktree.isMainWorktree ? 0 : rootSize,
+    skippedEntryCount,
+    ...compact
+  }
+}
+
+async function scanLocalWorktreeWithNode(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number
+): Promise<WorkspaceSpaceWorktree> {
+  try {
+    const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY)
+    const root = await scanLocalEntry(worktree.path, basename(worktree.path), limit)
+    const compact = compactTopLevelItems((root.children ?? []).map(toWorkspaceSpaceItem))
+    return {
+      ...createBaseWorktreeRow(repo, worktree, scannedAt),
+      status: 'ok',
+      error: null,
+      sizeBytes: root.sizeBytes,
+      reclaimableBytes: worktree.isMainWorktree ? 0 : root.sizeBytes,
+      skippedEntryCount: root.skippedEntryCount,
+      ...compact
+    }
+  } catch (error) {
+    const classified = classifyError(error)
+    return createUnavailableWorktreeRow(
+      repo,
+      worktree,
+      scannedAt,
+      classified.status,
+      classified.message
+    )
+  }
+}
+
+async function scanLocalWorktree(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number
+): Promise<WorkspaceSpaceWorktree> {
+  if (platform !== 'win32') {
+    try {
+      // Why: JS per-file stats are too slow for large local workspace fleets;
+      // POSIX du gives bounded top-level sizing without following symlinks.
+      return await scanLocalWorktreeWithDu(repo, worktree, scannedAt)
+    } catch {
+      // Fall through to the portable scanner so unsupported du variants or
+      // permission edge cases still produce partial rows instead of failing.
+    }
+  }
+  return scanLocalWorktreeWithNode(repo, worktree, scannedAt)
+}
+
+async function scanRemoteWorktree(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number,
+  provider: IFilesystemProvider
+): Promise<WorkspaceSpaceWorktree> {
+  try {
+    const limit = createAsyncLimiter(REMOTE_FS_CONCURRENCY)
+    const root = await scanRemoteEntry(worktree.path, basename(worktree.path), provider, limit)
+    const compact = compactTopLevelItems((root.children ?? []).map(toWorkspaceSpaceItem))
+    return {
+      ...createBaseWorktreeRow(repo, worktree, scannedAt),
+      status: 'ok',
+      error: null,
+      sizeBytes: root.sizeBytes,
+      reclaimableBytes: worktree.isMainWorktree ? 0 : root.sizeBytes,
+      skippedEntryCount: root.skippedEntryCount,
+      ...compact
+    }
+  } catch (error) {
+    const classified = classifyError(error)
+    return createUnavailableWorktreeRow(
+      repo,
+      worktree,
+      scannedAt,
+      classified.status,
+      classified.message
+    )
+  }
+}
+
+async function listWorktreesForSpaceScan(repo: Repo): Promise<WorktreeListResult> {
+  try {
+    if (isFolderRepo(repo)) {
+      return { ok: true, worktrees: [createFolderWorktree(repo)] }
+    }
+    if (repo.connectionId) {
+      const provider = getSshGitProvider(repo.connectionId)
+      if (!provider) {
+        return {
+          ok: false,
+          status: 'unavailable',
+          error: `SSH connection "${repo.connectionId}" is not connected.`
+        }
+      }
+      return { ok: true, worktrees: await provider.listWorktrees(repo.path) }
+    }
+    return { ok: true, worktrees: await listRepoWorktrees(repo) }
+  } catch (error) {
+    const classified = classifyError(error)
+    return { ok: false, status: classified.status, error: classified.message }
+  }
+}
+
+function mergeForSpaceScan(repo: Repo, gitWorktree: GitWorktreeInfo, store: Store): Worktree {
+  const worktreeId = `${repo.id}::${gitWorktree.path}`
+  return mergeWorktree(repo.id, gitWorktree, store.getWorktreeMeta(worktreeId), repo.displayName)
+}
+
+async function scanRepo(repo: Repo, scannedAt: number, store: Store): Promise<RepoScanResult> {
+  const listed = await listWorktreesForSpaceScan(repo)
+  if (!listed.ok) {
+    return {
+      worktrees: [],
+      summary: {
+        repoId: repo.id,
+        displayName: repo.displayName,
+        path: repo.path,
+        isRemote: Boolean(repo.connectionId),
+        worktreeCount: 0,
+        scannedWorktreeCount: 0,
+        unavailableWorktreeCount: 1,
+        totalSizeBytes: 0,
+        reclaimableBytes: 0,
+        error: listed.error
+      }
+    }
+  }
+
+  const worktrees = listed.worktrees.map((gitWorktree) =>
+    mergeForSpaceScan(repo, gitWorktree, store)
+  )
+  const remoteProvider = repo.connectionId ? getSshFilesystemProvider(repo.connectionId) : undefined
+  const rows = await mapLimit(worktrees, WORKTREE_SCAN_CONCURRENCY, async (worktree) => {
+    if (repo.connectionId) {
+      if (!remoteProvider) {
+        return createUnavailableWorktreeRow(
+          repo,
+          worktree,
+          scannedAt,
+          'unavailable',
+          `SSH filesystem for "${repo.connectionId}" is not connected.`
+        )
+      }
+      return scanRemoteWorktree(repo, worktree, scannedAt, remoteProvider)
+    }
+    return scanLocalWorktree(repo, worktree, scannedAt)
+  })
+
+  return {
+    worktrees: rows,
+    summary: {
+      repoId: repo.id,
+      displayName: repo.displayName,
+      path: repo.path,
+      isRemote: Boolean(repo.connectionId),
+      worktreeCount: rows.length,
+      scannedWorktreeCount: rows.filter((row) => row.status === 'ok').length,
+      unavailableWorktreeCount: rows.filter((row) => row.status !== 'ok').length,
+      totalSizeBytes: rows.reduce((sum, row) => sum + row.sizeBytes, 0),
+      reclaimableBytes: rows.reduce((sum, row) => sum + row.reclaimableBytes, 0),
+      error: null
+    }
+  }
+}
+
+export async function analyzeWorkspaceSpace(store: Store): Promise<WorkspaceSpaceAnalysis> {
+  const scannedAt = Date.now()
+  const repoResults = await mapLimit(store.getRepos(), 2, (repo) =>
+    scanRepo(repo, scannedAt, store)
+  )
+  const repos = repoResults.map((result) => result.summary)
+  const worktrees = repoResults
+    .flatMap((result) => result.worktrees)
+    .sort((a, b) => b.sizeBytes - a.sizeBytes || a.displayName.localeCompare(b.displayName))
+
+  return {
+    scannedAt,
+    totalSizeBytes: worktrees.reduce((sum, row) => sum + row.sizeBytes, 0),
+    reclaimableBytes: worktrees.reduce((sum, row) => sum + row.reclaimableBytes, 0),
+    worktreeCount: worktrees.length,
+    scannedWorktreeCount: worktrees.filter((row) => row.status === 'ok').length,
+    unavailableWorktreeCount:
+      worktrees.filter((row) => row.status !== 'ok').length +
+      repos.filter((repo) => repo.error !== null).length,
+    repos,
+    worktrees
+  }
+}
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index c988c5561af..f46f7e977ce 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -165,6 +165,7 @@ import type {
 } from '../shared/claude-usage-types'
 import type { RateLimitState } from '../shared/rate-limit-types'
 import type { SpeechModelManifest, SpeechModelState } from '../shared/speech-types'
+import type { WorkspaceSpaceAnalysis } from '../shared/workspace-space-types'
 import type { GhAuthDiagnostic } from '../shared/github-auth-types'
 import type {
   SshConnectionState,
@@ -526,6 +527,9 @@ export type PreloadApi = {
       callback: (data: WorktreeRemoteBranchConflictEvent) => void
     ) => () => void
   }
+  workspaceSpace: {
+    analyze: () => Promise<WorkspaceSpaceAnalysis>
+  }
   pty: {
     spawn: (opts: {
       cols: number
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 88bdf910a7c..c744b23d047 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -38,6 +38,7 @@ import type {
   RuntimeMobileMarkdownResponse
 } from '../shared/mobile-markdown-document'
 import type { RateLimitState } from '../shared/rate-limit-types'
+import type { WorkspaceSpaceAnalysis } from '../shared/workspace-space-types'
 import type { GhAuthDiagnostic } from '../shared/github-auth-types'
 import type {
   AddIssueCommentBySlugArgs,
@@ -489,6 +490,10 @@ const api = {
     }
   },
 
+  workspaceSpace: {
+    analyze: (): Promise<WorkspaceSpaceAnalysis> => ipcRenderer.invoke('workspaceSpace:analyze')
+  },
+
   pty: {
     spawn: (opts: {
       cols: number
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 68a809ddd05..b70bbbd11c0 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -49,6 +49,7 @@ import { TelemetryFirstLaunchSurface } from './components/TelemetryFirstLaunchSu
 import { ZoomOverlay } from './components/ZoomOverlay'
 import { shouldShowOnboarding } from './components/onboarding/should-show-onboarding'
 import { SshPassphraseDialog } from './components/settings/SshPassphraseDialog'
+import DeleteWorktreeDialog from './components/sidebar/DeleteWorktreeDialog'
 import {
   FloatingTerminalPanel,
   FloatingTerminalToggleButton
@@ -159,6 +160,7 @@ const TaskPage = lazy(() => import('./components/TaskPage'))
 const AutomationsPage = lazy(() => import('./components/automations/AutomationsPage'))
 const ActivityPrototypePage = lazy(() => import('./components/activity/ActivityPrototypePage'))
 const Settings = lazy(() => import('./components/settings/Settings'))
+const WorkspaceSpacePage = lazy(() => import('./components/workspace-space/WorkspaceSpacePage'))
 const QuickOpen = lazy(() => import('./components/QuickOpen'))
 const WorktreeJumpPalette = lazy(() => import('./components/WorktreeJumpPalette'))
 const NewWorkspaceComposerModal = lazy(() => import('./components/NewWorkspaceComposerModal'))
@@ -802,10 +804,10 @@ function App(): React.JSX.Element {
     activeWorktreeId !== null &&
     !hasTabBar &&
     effectiveActiveTabExpanded
-  // Why: Activity is a full-page navigation surface — same treatment as
-  // Settings — so the worktree sidebar is removed for that view, letting the
-  // thread list + agent terminal span edge-to-edge.
-  const showSidebar = activeView !== 'settings' && activeView !== 'activity'
+  // Why: Activity and Space are full-page navigation surfaces — same
+  // treatment as Settings — so the worktree sidebar is removed for those views.
+  const showSidebar =
+    activeView !== 'settings' && activeView !== 'activity' && activeView !== 'space'
   // Why: only the terminal workspace replaces the full-width titlebar with
   // split-column chrome. Full-page navigation views keep the draggable app
   // titlebar so their page-level controls can live in that window strip.
@@ -816,7 +818,8 @@ function App(): React.JSX.Element {
     activeView !== 'settings' &&
     activeView !== 'tasks' &&
     activeView !== 'activity' &&
-    activeView !== 'automations'
+    activeView !== 'automations' &&
+    activeView !== 'space'
 
   const handleToggleExpand = (): void => {
     if (!effectiveActiveTabId) {
@@ -903,7 +906,12 @@ function App(): React.JSX.Element {
 
       // Why: full-page navigation surfaces should not reveal the right sidebar;
       // they are designed as distraction-free content areas.
-      if (activeView === 'tasks' || activeView === 'activity' || activeView === 'automations') {
+      if (
+        activeView === 'tasks' ||
+        activeView === 'activity' ||
+        activeView === 'automations' ||
+        activeView === 'space'
+      ) {
         return
       }
 
@@ -1137,7 +1145,10 @@ function App(): React.JSX.Element {
 
   useEffect(() => {
     if (
-      (activeView === 'tasks' || activeView === 'activity' || activeView === 'automations') &&
+      (activeView === 'tasks' ||
+        activeView === 'activity' ||
+        activeView === 'automations' ||
+        activeView === 'space') &&
       rightSidebarOpen
     ) {
       // Why: hide the right sidebar immediately when entering full-page
@@ -1307,6 +1318,7 @@ function App(): React.JSX.Element {
                     {activeView === 'tasks' ? <TaskPage /> : null}
                     {activeView === 'automations' ? <AutomationsPage /> : null}
                     {activeView === 'activity' ? <ActivityPrototypePage /> : null}
+                    {activeView === 'space' ? <WorkspaceSpacePage /> : null}
                     {activeView === 'terminal' && !activeWorktreeId ? <Landing /> : null}
                   </Suspense>
                 </div>
@@ -1370,6 +1382,7 @@ function App(): React.JSX.Element {
       <TelemetryFirstLaunchSurface />
       <ZoomOverlay />
       <SshPassphraseDialog />
+      <DeleteWorktreeDialog />
       {onboarding && shouldShowOnboarding(onboarding) ? (
         <Suspense fallback={null}>
           <OnboardingFlow onboarding={onboarding} onOnboardingChange={setOnboarding} />
diff --git a/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts b/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts
index 7fc319534ca..29c6a2fa58d 100644
--- a/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts
+++ b/src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts
@@ -52,6 +52,8 @@ const INSTALLED_CLI_STATUS: CliInstallStatus = {
 
 const GRANTED_COMPUTER_USE_STATUS: ComputerUsePermissionStatusResult = {
   platform: 'darwin',
+  helperAppPath: '/Applications/Orca Computer Use.app',
+  helperUnavailableReason: null,
   permissions: [
     { id: 'accessibility', status: 'granted' },
     { id: 'screenshots', status: 'granted' }
@@ -157,6 +159,8 @@ describe('onboarding feature setup runner', () => {
       getComputerUsePermissionStatus: vi.fn(
         async (): Promise<ComputerUsePermissionStatusResult> => ({
           platform: 'darwin',
+          helperAppPath: '/Applications/Orca Computer Use.app',
+          helperUnavailableReason: null,
           permissions: [
             { id: 'accessibility', status: 'not-granted' },
             { id: 'screenshots', status: 'granted' }
diff --git a/src/renderer/src/components/settings/AppearancePane.tsx b/src/renderer/src/components/settings/AppearancePane.tsx
index ad34aa40038..ee1d6567d75 100644
--- a/src/renderer/src/components/settings/AppearancePane.tsx
+++ b/src/renderer/src/components/settings/AppearancePane.tsx
@@ -61,23 +61,11 @@ const STATUS_BAR_TOGGLES: readonly {
   },
   {
     id: 'resource-usage',
-    title: 'Resource Usage',
-    description: 'Show CPU, memory, and terminal session indicators in the status bar.',
-    keywords: [
-      'status bar',
-      'resource',
-      'usage',
-      'memory',
-      'ram',
-      'cpu',
-      'terminal',
-      'sessions',
-      'pty',
-      'monitoring',
-      'performance'
-    ],
+    title: 'Resource Manager',
+    description: 'Show CPU, memory, terminal sessions, and workspace disk usage in the status bar.',
+    keywords: ['status bar', 'resource', 'manager', 'memory', 'cpu', 'terminal', 'disk', 'space'],
     toggleDescription:
-      'Show CPU, memory, and terminal session counts. Click it for a per-workspace breakdown and daemon controls.'
+      'Show the Resource Manager. Click it for CPU, memory, sessions, daemon controls, and workspace disk scans.'
   }
 ]
 
diff --git a/src/renderer/src/components/settings/ComputerUsePane.tsx b/src/renderer/src/components/settings/ComputerUsePane.tsx
index 79bd613b37e..bf31a526a4b 100644
--- a/src/renderer/src/components/settings/ComputerUsePane.tsx
+++ b/src/renderer/src/components/settings/ComputerUsePane.tsx
@@ -67,20 +67,12 @@ function statusClass(status: ComputerUsePermissionStatus | undefined): string {
   return 'border-border bg-muted text-muted-foreground'
 }
 
-function isExpectedDevMissingHelperError(error: unknown): boolean {
-  return (
-    import.meta.env.DEV &&
-    error instanceof Error &&
-    error.message.includes('Orca Computer Use.app was not found')
-  )
-}
-
 export function ComputerUsePane(): React.JSX.Element {
   const [platform, setPlatform] = useState<NodeJS.Platform | null>(null)
   const [states, setStates] = useState<ComputerUsePermissionState[]>([])
   const [loading, setLoading] = useState(true)
   const [pendingId, setPendingId] = useState<ComputerUsePermissionId | null>(null)
-  const [helperUnavailableInDev, setHelperUnavailableInDev] = useState(false)
+  const [helperUnavailableReason, setHelperUnavailableReason] = useState<string | null>(null)
 
   const stateById = useMemo(
     () => new Map(states.map((state) => [state.id, state.status] as const)),
@@ -93,14 +85,8 @@ export function ComputerUsePane(): React.JSX.Element {
       const result = await window.api.computerUsePermissions.getStatus()
       setPlatform(result.platform)
       setStates(result.permissions)
-      setHelperUnavailableInDev(false)
+      setHelperUnavailableReason(result.helperUnavailableReason)
     } catch (error) {
-      if (isExpectedDevMissingHelperError(error)) {
-        setPlatform('darwin')
-        setStates(PERMISSIONS.map((permission) => ({ id: permission.id, status: 'not-granted' })))
-        setHelperUnavailableInDev(true)
-        return
-      }
       toast.error(
         error instanceof Error ? error.message : 'Could not load Computer Use permissions'
       )
@@ -166,10 +152,9 @@ export function ComputerUsePane(): React.JSX.Element {
                 Computer Use needs macOS privacy permissions before agents can inspect and operate
                 app windows.
               </p>
-              {helperUnavailableInDev ? (
+              {helperUnavailableReason ? (
                 <p className="text-xs text-muted-foreground">
-                  Computer Use permissions are unavailable in this dev build because the helper app
-                  has not been built.
+                  Computer Use permissions are unavailable because {helperUnavailableReason}.
                 </p>
               ) : null}
             </div>
@@ -208,7 +193,9 @@ export function ComputerUsePane(): React.JSX.Element {
                   <Button
                     variant="outline"
                     size="sm"
-                    disabled={pending || status === 'unsupported' || helperUnavailableInDev}
+                    disabled={
+                      pending || status === 'unsupported' || helperUnavailableReason !== null
+                    }
                     onClick={() => void openPermission(permission.id)}
                     className="shrink-0 gap-1.5"
                   >
diff --git a/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx b/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx
index 10c01efc75a..335a7f5b2c2 100644
--- a/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx
+++ b/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx
@@ -35,6 +35,10 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
           : [],
     [modalData.worktreeIds, worktreeId]
   )
+  const onDeleted =
+    typeof modalData.onDeleted === 'function'
+      ? (modalData.onDeleted as (worktreeIds: string[]) => void)
+      : null
   const worktree = useMemo(
     () => (worktreeId ? (allWorktrees().find((item) => item.id === worktreeId) ?? null) : null),
     [allWorktrees, worktreeId]
@@ -146,7 +150,9 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
               toast.error('Force delete failed', {
                 description: result.error
               })
+              return
             }
+            onDeleted?.([worktreeId])
           })
           .catch((err: unknown) => {
             toast.error('Failed to delete worktree', {
@@ -154,15 +160,23 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
             })
           })
       } else {
-        for (const target of worktrees) {
-          runWorktreeDeleteWithToast(target.id, target.displayName)
-        }
+        void Promise.all(
+          worktrees.map((target) => runWorktreeDeleteWithToast(target.id, target.displayName))
+        ).then((results) => {
+          const deletedIds = worktrees
+            .filter((_, index) => results[index])
+            .map((target) => target.id)
+          if (deletedIds.length > 0) {
+            onDeleted?.(deletedIds)
+          }
+        })
       }
       closeModal()
     },
     [
       closeModal,
       dontAskAgain,
+      onDeleted,
       persistDontAskAgainPreference,
       removeWorktree,
       worktreeIds.length,
diff --git a/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts b/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts
index 35577dfca79..c562a9008b1 100644
--- a/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts
+++ b/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts
@@ -33,6 +33,7 @@ vi.mock('sonner', () => ({
   }
 }))
 
+import { toast } from 'sonner'
 import { runWorktreeBatchDelete } from './delete-worktree-flow'
 
 function setWorktrees(
@@ -57,14 +58,17 @@ describe('runWorktreeBatchDelete', () => {
     mocks.state.openModal.mockClear()
     mocks.state.removeWorktree.mockClear().mockResolvedValue({ ok: true })
     mocks.state.deleteStateByWorktreeId = {}
+    vi.mocked(toast.error).mockClear()
+    vi.mocked(toast.info).mockClear()
     setWorktrees([])
   })
 
   it('filters main worktrees and opens a batch confirmation for eligible targets', () => {
     setWorktrees([{ id: 'main', isMainWorktree: true }, { id: 'wt-1' }, { id: 'wt-2' }])
 
-    runWorktreeBatchDelete(['main', 'wt-1', 'wt-2'])
+    const started = runWorktreeBatchDelete(['main', 'wt-1', 'wt-2'])
 
+    expect(started).toBe(true)
     expect(mocks.state.clearWorktreeDeleteState).toHaveBeenCalledWith('wt-1')
     expect(mocks.state.clearWorktreeDeleteState).toHaveBeenCalledWith('wt-2')
     expect(mocks.state.clearWorktreeDeleteState).not.toHaveBeenCalledWith('main')
@@ -76,22 +80,41 @@ describe('runWorktreeBatchDelete', () => {
   it('opens the single-delete confirmation when only one target is eligible', () => {
     setWorktrees([{ id: 'main', isMainWorktree: true }, { id: 'wt-1' }])
 
-    runWorktreeBatchDelete(['main', 'wt-1'])
+    const started = runWorktreeBatchDelete(['main', 'wt-1'])
 
+    expect(started).toBe(true)
     expect(mocks.state.openModal).toHaveBeenCalledWith('delete-worktree', { worktreeId: 'wt-1' })
   })
 
-  it('runs every eligible delete immediately when confirmation is skipped', () => {
+  it('runs every eligible delete immediately when confirmation is skipped', async () => {
     mocks.state.settings = { skipDeleteWorktreeConfirm: true }
     setWorktrees([
       { id: 'wt-1', displayName: 'one' },
       { id: 'wt-2', displayName: 'two' }
     ])
+    const onDeleted = vi.fn()
 
-    runWorktreeBatchDelete(['wt-1', 'wt-2'])
+    const started = runWorktreeBatchDelete(['wt-1', 'wt-2'], { onDeleted })
 
+    expect(started).toBe(true)
     expect(mocks.state.openModal).not.toHaveBeenCalled()
     expect(mocks.state.removeWorktree).toHaveBeenCalledWith('wt-1', false)
     expect(mocks.state.removeWorktree).toHaveBeenCalledWith('wt-2', false)
+    await vi.waitFor(() => {
+      expect(onDeleted).toHaveBeenCalledWith(['wt-1', 'wt-2'])
+    })
+  })
+
+  it('reports when no selected worktrees are eligible', () => {
+    setWorktrees([{ id: 'main', isMainWorktree: true }])
+
+    const started = runWorktreeBatchDelete(['main', 'missing'])
+
+    expect(started).toBe(false)
+    expect(mocks.state.clearWorktreeDeleteState).not.toHaveBeenCalled()
+    expect(mocks.state.openModal).not.toHaveBeenCalled()
+    expect(toast.info).toHaveBeenCalledWith('No deletable workspaces selected', {
+      description: 'Refresh Space and try again if the workspace list looks stale.'
+    })
   })
 })
diff --git a/src/renderer/src/components/sidebar/delete-worktree-flow.ts b/src/renderer/src/components/sidebar/delete-worktree-flow.ts
index d64d8a3fab7..e09200650cc 100644
--- a/src/renderer/src/components/sidebar/delete-worktree-flow.ts
+++ b/src/renderer/src/components/sidebar/delete-worktree-flow.ts
@@ -5,6 +5,10 @@ import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { getDeleteWorktreeToastCopy } from './delete-worktree-toast'
 import type { Worktree } from '../../../../shared/types'
 
+type WorktreeBatchDeleteOptions = {
+  onDeleted?: (worktreeIds: string[]) => void
+}
+
 // Why: a failed delete almost always means the worktree still has changes
 // that need attention (uncommitted work, unpushed commits, conflicts). The
 // "View" affordance should surface those changes directly, not just bring
@@ -30,13 +34,16 @@ function viewWorktreeDiff(worktreeId: string): void {
  * concerns into the store slice while still preventing the two delete
  * entry points from drifting apart.
  */
-export function runWorktreeDeleteWithToast(worktreeId: string, worktreeName: string): void {
+export function runWorktreeDeleteWithToast(
+  worktreeId: string,
+  worktreeName: string
+): Promise<boolean> {
   const removeWorktree = useAppStore.getState().removeWorktree
 
-  removeWorktree(worktreeId, false)
+  return removeWorktree(worktreeId, false)
     .then((result) => {
       if (result.ok) {
-        return
+        return true
       }
       const state = useAppStore.getState().deleteStateByWorktreeId[worktreeId]
       const canForceDelete = state?.canForceDelete ?? false
@@ -80,11 +87,13 @@ export function runWorktreeDeleteWithToast(worktreeId: string, worktreeName: str
             }
           : undefined
       })
+      return false
     })
     .catch((err: unknown) => {
       toast.error('Failed to delete worktree', {
         description: err instanceof Error ? err.message : String(err)
       })
+      return false
     })
 }
 
@@ -122,13 +131,16 @@ export function runWorktreeDelete(worktreeId: string): void {
   state.clearWorktreeDeleteState(worktreeId)
   const skipConfirm = state.settings?.skipDeleteWorktreeConfirm ?? false
   if (skipConfirm) {
-    runWorktreeDeleteWithToast(worktreeId, target.displayName)
+    void runWorktreeDeleteWithToast(worktreeId, target.displayName)
     return
   }
   state.openModal('delete-worktree', { worktreeId })
 }
 
-export function runWorktreeBatchDelete(worktreeIds: readonly string[]): void {
+export function runWorktreeBatchDelete(
+  worktreeIds: readonly string[],
+  options: WorktreeBatchDeleteOptions = {}
+): boolean {
   const state = useAppStore.getState()
   const worktreeMap = getWorktreeMapFromState(state)
   const targets = worktreeIds
@@ -136,7 +148,10 @@ export function runWorktreeBatchDelete(worktreeIds: readonly string[]): void {
     .filter((worktree): worktree is Worktree => worktree != null && !worktree.isMainWorktree)
 
   if (targets.length === 0) {
-    return
+    toast.info('No deletable workspaces selected', {
+      description: 'Refresh Space and try again if the workspace list looks stale.'
+    })
+    return false
   }
 
   for (const target of targets) {
@@ -145,16 +160,28 @@ export function runWorktreeBatchDelete(worktreeIds: readonly string[]): void {
 
   const skipConfirm = state.settings?.skipDeleteWorktreeConfirm ?? false
   if (skipConfirm) {
-    for (const target of targets) {
-      runWorktreeDeleteWithToast(target.id, target.displayName)
-    }
-    return
+    void Promise.all(
+      targets.map((target) => runWorktreeDeleteWithToast(target.id, target.displayName))
+    ).then((results) => {
+      const deletedIds = targets.filter((_, index) => results[index]).map((target) => target.id)
+      if (deletedIds.length > 0) {
+        options.onDeleted?.(deletedIds)
+      }
+    })
+    return true
   }
 
   if (targets.length === 1) {
-    state.openModal('delete-worktree', { worktreeId: targets[0].id })
-    return
+    state.openModal('delete-worktree', {
+      worktreeId: targets[0].id,
+      ...(options.onDeleted ? { onDeleted: options.onDeleted } : {})
+    })
+    return true
   }
 
-  state.openModal('delete-worktree', { worktreeIds: targets.map((target) => target.id) })
+  state.openModal('delete-worktree', {
+    worktreeIds: targets.map((target) => target.id),
+    ...(options.onDeleted ? { onDeleted: options.onDeleted } : {})
+  })
+  return true
 }
diff --git a/src/renderer/src/components/sidebar/index.tsx b/src/renderer/src/components/sidebar/index.tsx
index 51f9979a2f8..e06c40087fb 100644
--- a/src/renderer/src/components/sidebar/index.tsx
+++ b/src/renderer/src/components/sidebar/index.tsx
@@ -7,7 +7,6 @@ import SidebarNav from './SidebarNav'
 import WorktreeList from './WorktreeList'
 import SidebarToolbar from './SidebarToolbar'
 import WorktreeMetaDialog from './WorktreeMetaDialog'
-import DeleteWorktreeDialog from './DeleteWorktreeDialog'
 import NonGitFolderDialog from './NonGitFolderDialog'
 import RemoveFolderDialog from './RemoveFolderDialog'
 import AddRepoDialog from './AddRepoDialog'
@@ -64,7 +63,6 @@ function Sidebar(): React.JSX.Element {
 
       {/* Dialog (rendered outside sidebar to avoid clipping) */}
       <WorktreeMetaDialog />
-      <DeleteWorktreeDialog />
       <NonGitFolderDialog />
       <RemoveFolderDialog />
       <AddRepoDialog />
diff --git a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
index 2908994204b..8a09b74d6df 100644
--- a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
@@ -47,6 +47,7 @@ import {
   type UnifiedSessionRow,
   type UnifiedWorktreeRow
 } from './mergeSnapshotAndSessions'
+import { WorkspaceSpaceCompactPanel } from './WorkspaceSpaceCompactPanel'
 
 const POLL_MS = 2_000
 const SESSIONS_POLL_MS = 10_000
@@ -654,6 +655,7 @@ export function ResourceUsageStatusSegment({
   const tabsByWorktree = useAppStore((s) => s.tabsByWorktree)
   const runtimePaneTitlesByTabId = useAppStore((s) => s.runtimePaneTitlesByTabId)
   const setActiveView = useAppStore((s) => s.setActiveView)
+  const openSpacePage = useAppStore((s) => s.openSpacePage)
   const repos = useAppStore((s) => s.repos)
 
   const [open, setOpen] = useState(false)
@@ -985,6 +987,11 @@ export function ResourceUsageStatusSegment({
     }
   }, [killConfirm, refreshSessions])
 
+  const openSpaceResults = useCallback((): void => {
+    setOpen(false)
+    openSpacePage()
+  }, [openSpacePage])
+
   return (
     <Popover open={open} onOpenChange={setOpen}>
       <Tooltip delayDuration={150}>
@@ -993,7 +1000,7 @@ export function ResourceUsageStatusSegment({
             <button
               type="button"
               className="inline-flex items-center gap-1.5 cursor-pointer rounded px-1 py-0.5 hover:bg-accent/70"
-              aria-label="Resource usage"
+              aria-label="Resource manager"
             >
               <MemoryStick className="size-3 text-muted-foreground" />
               {!iconOnly && (
@@ -1023,7 +1030,7 @@ export function ResourceUsageStatusSegment({
           </PopoverTrigger>
         </TooltipTrigger>
         <TooltipContent side="top" sideOffset={6}>
-          Resource usage — {memBadgeLabel} · {sessions.length} session
+          Resource Manager — {memBadgeLabel} · {sessions.length} session
           {sessions.length === 1 ? '' : 's'}
         </TooltipContent>
       </Tooltip>
@@ -1032,7 +1039,7 @@ export function ResourceUsageStatusSegment({
         side="top"
         align="end"
         sideOffset={8}
-        className="w-[26rem] p-0"
+        className="w-[26rem] max-w-[calc(100vw-2rem)] p-0"
         onOpenAutoFocus={(event) => event.preventDefault()}
         // Why: clicking a terminal row activates a tab, which causes xterm
         // to programmatically focus the terminal DOM node. Radix would
@@ -1041,13 +1048,10 @@ export function ResourceUsageStatusSegment({
         // outside-click (onPointerDownOutside default) and Escape.
         onFocusOutside={(event) => event.preventDefault()}
       >
-        {/* Why: header strip — title on the left, daemon-control icons on
-            the right. The tab switcher was removed because a single unified
-            list now covers what the two tabs used to show. */}
         <div className="flex items-center justify-between gap-2 border-b border-border px-3 py-1.5">
-          <div className="flex items-center gap-1.5 text-[11px] font-medium text-foreground">
-            <MemoryStick className="size-3 text-muted-foreground" />
-            <span>Resource Usage</span>
+          <div className="flex min-w-0 items-center gap-1.5 text-[11px] font-medium text-foreground">
+            <MemoryStick className="size-3 shrink-0 text-muted-foreground" />
+            <span className="truncate">Resource Manager</span>
           </div>
 
           <div className="flex items-center gap-0.5">
@@ -1280,6 +1284,8 @@ export function ResourceUsageStatusSegment({
             </button>
           </div>
         )}
+
+        <WorkspaceSpaceCompactPanel onOpenFullPage={openSpaceResults} />
       </PopoverContent>
       {/* Why: Radix Dialog must not be a descendant of PopoverContent — when
           the popover unmounts (e.g. clicking outside, focus moving to the
diff --git a/src/renderer/src/components/status-bar/StatusBar.tsx b/src/renderer/src/components/status-bar/StatusBar.tsx
index d33152a00ec..e5b935f5e02 100644
--- a/src/renderer/src/components/status-bar/StatusBar.tsx
+++ b/src/renderer/src/components/status-bar/StatusBar.tsx
@@ -985,7 +985,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
             onCheckedChange={() => toggleStatusBarItem('resource-usage')}
           >
             <Activity className="size-3.5" />
-            Resource Usage
+            Resource Manager
           </DropdownMenuCheckboxItem>
         </DropdownMenuContent>
       </DropdownMenu>
diff --git a/src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx b/src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx
new file mode 100644
index 00000000000..217816d5491
--- /dev/null
+++ b/src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx
@@ -0,0 +1,92 @@
+import { useCallback } from 'react'
+import { AlertTriangle, HardDrive, Loader2, RefreshCw } from 'lucide-react'
+import { useAppStore } from '../../store'
+import { Badge } from '../ui/badge'
+import { Button } from '../ui/button'
+import { formatBytes, getWorkspaceSpaceScanTimeLabel } from './workspace-space-format'
+
+export function WorkspaceSpaceCompactPanel({
+  onOpenFullPage
+}: {
+  onOpenFullPage: () => void
+}): React.JSX.Element {
+  const analysis = useAppStore((state) => state.workspaceSpaceAnalysis)
+  const scanError = useAppStore((state) => state.workspaceSpaceScanError)
+  const isScanning = useAppStore((state) => state.workspaceSpaceScanning)
+  const refreshWorkspaceSpace = useAppStore((state) => state.refreshWorkspaceSpace)
+
+  const scan = useCallback((): void => {
+    void refreshWorkspaceSpace().catch(() => {
+      /* scanError is stored by the slice */
+    })
+  }, [refreshWorkspaceSpace])
+
+  return (
+    <div className="border-t border-border/50 bg-muted/15 px-3 py-2">
+      <div className="flex items-center justify-between gap-2">
+        <div className="flex min-w-0 items-center gap-2">
+          <HardDrive className="size-3.5 shrink-0 text-muted-foreground" />
+          <div className="min-w-0">
+            <div className="flex min-w-0 items-center gap-1.5 text-[11px] font-medium text-foreground">
+              <span className="truncate">Space</span>
+              <Badge variant="secondary" className="px-1.5 py-0 text-[9px]">
+                Beta
+              </Badge>
+            </div>
+            <div className="truncate text-[11px] text-muted-foreground">
+              {analysis
+                ? `${formatBytes(analysis.reclaimableBytes)} reclaimable · ${analysis.scannedWorktreeCount} workspaces`
+                : isScanning
+                  ? 'Scanning workspace sizes.'
+                  : 'Workspace disk usage is not scanned.'}
+            </div>
+          </div>
+        </div>
+
+        <div className="flex shrink-0 items-center gap-1">
+          <Button variant="outline" size="xs" onClick={scan} disabled={isScanning}>
+            {isScanning ? (
+              <Loader2 className="size-3 animate-spin" />
+            ) : (
+              <RefreshCw className="size-3" />
+            )}
+            {isScanning ? 'Scanning' : analysis ? 'Refresh' : 'Scan'}
+          </Button>
+          <Button variant="ghost" size="xs" onClick={onOpenFullPage}>
+            Open
+          </Button>
+        </div>
+      </div>
+
+      {analysis ? (
+        <div className="mt-2 grid grid-cols-3 gap-1 text-[10px] tabular-nums">
+          <div className="rounded border border-border/60 bg-background/40 px-2 py-1">
+            <div className="text-muted-foreground">Scanned</div>
+            <div className="truncate font-medium text-foreground">
+              {formatBytes(analysis.totalSizeBytes)}
+            </div>
+          </div>
+          <div className="rounded border border-border/60 bg-background/40 px-2 py-1">
+            <div className="text-muted-foreground">Freeable</div>
+            <div className="truncate font-medium text-foreground">
+              {formatBytes(analysis.reclaimableBytes)}
+            </div>
+          </div>
+          <div className="rounded border border-border/60 bg-background/40 px-2 py-1">
+            <div className="text-muted-foreground">Updated</div>
+            <div className="truncate font-medium text-foreground">
+              {getWorkspaceSpaceScanTimeLabel(analysis.scannedAt)}
+            </div>
+          </div>
+        </div>
+      ) : null}
+
+      {scanError ? (
+        <div className="mt-1.5 flex items-start gap-1.5 text-[11px] text-destructive">
+          <AlertTriangle className="mt-0.5 size-3 shrink-0" />
+          <span className="min-w-0 truncate">{scanError}</span>
+        </div>
+      ) : null}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
new file mode 100644
index 00000000000..9c8452003da
--- /dev/null
+++ b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
@@ -0,0 +1,685 @@
+/* eslint-disable max-lines -- Why: the analyzer's private treemap, selection,
+   breakdown, and table pieces share one scan state and should evolve as one resource-manager surface. */
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import {
+  AlertTriangle,
+  ArrowDown,
+  ArrowUp,
+  Check,
+  Circle,
+  GitBranch,
+  HardDrive,
+  Loader2,
+  RefreshCw,
+  Search,
+  Server,
+  Trash2
+} from 'lucide-react'
+import type {
+  WorkspaceSpaceItem,
+  WorkspaceSpaceWorktree
+} from '../../../../shared/workspace-space-types'
+import { cn } from '@/lib/utils'
+import { toast } from 'sonner'
+import { useAppStore } from '../../store'
+import { runWorktreeBatchDelete } from '../sidebar/delete-worktree-flow'
+import { Badge } from '../ui/badge'
+import { Button } from '../ui/button'
+import { Input } from '../ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+import {
+  formatBytes,
+  formatCompactCount,
+  getWorkspaceSpaceBranchLabel,
+  getWorkspaceSpaceScanTimeLabel,
+  getWorkspaceSpaceStatusLabel
+} from './workspace-space-format'
+import { buildTreemapLayout, type TreemapRect } from './workspace-space-layout'
+import {
+  filterWorkspaceSpaceRows,
+  getSelectedDeletableWorkspaceIds,
+  sortWorkspaceSpaceRows,
+  type WorkspaceSpaceSortDirection,
+  type WorkspaceSpaceSortKey
+} from './workspace-space-presentation'
+
+const TREEMAP_FILLS = [
+  'color-mix(in srgb, var(--chart-2) 34%, var(--card))',
+  'color-mix(in srgb, var(--foreground) 20%, var(--card))',
+  'color-mix(in srgb, var(--chart-4) 28%, var(--card))',
+  'color-mix(in srgb, var(--primary) 24%, var(--card))',
+  'color-mix(in srgb, var(--chart-1) 38%, var(--card))'
+]
+
+function getTreemapFill(rect: TreemapRect, selected: boolean): string {
+  if (selected) {
+    return 'color-mix(in srgb, var(--ring) 40%, var(--card))'
+  }
+  return TREEMAP_FILLS[rect.index % TREEMAP_FILLS.length]
+}
+
+function Metric({ label, value }: { label: string; value: string }): React.JSX.Element {
+  return (
+    <div className="min-w-0 px-4 py-3">
+      <div className="truncate text-[11px] font-medium uppercase tracking-[0.14em] text-muted-foreground">
+        {label}
+      </div>
+      <div className="mt-1 truncate text-lg font-semibold tabular-nums">{value}</div>
+    </div>
+  )
+}
+
+function CheckButton({
+  checked,
+  disabled,
+  label,
+  onClick
+}: {
+  checked: boolean
+  disabled?: boolean
+  label: string
+  onClick: () => void
+}): React.JSX.Element {
+  return (
+    <button
+      type="button"
+      role="checkbox"
+      aria-checked={checked}
+      aria-label={label}
+      disabled={disabled}
+      onClick={(event) => {
+        event.stopPropagation()
+        onClick()
+      }}
+      className={cn(
+        'flex size-4 shrink-0 items-center justify-center rounded-sm border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        checked
+          ? 'border-foreground bg-foreground text-background'
+          : 'border-muted-foreground/50 bg-background/40 text-transparent',
+        disabled && 'cursor-default opacity-35'
+      )}
+    >
+      {checked ? <Check className="size-3" strokeWidth={3} /> : null}
+    </button>
+  )
+}
+
+function SortIndicator({
+  sortKey,
+  activeKey,
+  direction
+}: {
+  sortKey: WorkspaceSpaceSortKey
+  activeKey: WorkspaceSpaceSortKey
+  direction: WorkspaceSpaceSortDirection
+}): React.JSX.Element {
+  if (sortKey !== activeKey) {
+    return <Circle className="size-3 opacity-0" />
+  }
+  return direction === 'asc' ? <ArrowUp className="size-3" /> : <ArrowDown className="size-3" />
+}
+
+function StatusBadge({ worktree }: { worktree: WorkspaceSpaceWorktree }): React.JSX.Element {
+  if (worktree.status !== 'ok') {
+    return (
+      <Badge variant="outline" className="border-destructive/30 text-destructive">
+        {getWorkspaceSpaceStatusLabel(worktree.status)}
+      </Badge>
+    )
+  }
+  if (worktree.isMainWorktree) {
+    return <Badge variant="outline">Main</Badge>
+  }
+  return <Badge variant="secondary">Deletable</Badge>
+}
+
+function WorkspaceTreemap({
+  rows,
+  isScanning,
+  selectedWorktreeId,
+  onSelect
+}: {
+  rows: WorkspaceSpaceWorktree[]
+  isScanning: boolean
+  selectedWorktreeId: string | null
+  onSelect: (worktreeId: string) => void
+}): React.JSX.Element {
+  const rects = useMemo(
+    () =>
+      buildTreemapLayout(
+        rows
+          .filter((row) => row.status === 'ok' && row.sizeBytes > 0)
+          .map((row) => ({
+            id: row.worktreeId,
+            label: row.displayName,
+            sizeBytes: row.sizeBytes
+          }))
+      ),
+    [rows]
+  )
+
+  if (rects.length === 0) {
+    return (
+      <div className="flex h-72 items-center justify-center rounded-lg border border-dashed border-border/70 bg-muted/20 text-sm text-muted-foreground">
+        <span className="flex items-center gap-2">
+          {isScanning ? <Loader2 className="size-4 animate-spin" /> : null}
+          {isScanning
+            ? 'Scanning workspace sizes. You can leave this page.'
+            : 'No scanned workspace sizes yet.'}
+        </span>
+      </div>
+    )
+  }
+
+  return (
+    <div className="relative h-72 overflow-hidden rounded-lg border border-border/70 bg-muted/20">
+      {rects.map((rect) => {
+        const area = rect.width * rect.height
+        const selected = rect.id === selectedWorktreeId
+        return (
+          <button
+            key={rect.id}
+            type="button"
+            aria-label={`${rect.label}, ${formatBytes(rect.sizeBytes)}`}
+            title={`${rect.label} • ${formatBytes(rect.sizeBytes)}`}
+            onClick={() => onSelect(rect.id)}
+            className={cn(
+              'absolute overflow-hidden border border-background/80 p-2 text-left transition-[filter,outline] hover:brightness-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+              selected && 'ring-2 ring-ring ring-offset-1 ring-offset-background'
+            )}
+            style={{
+              left: `${rect.x}%`,
+              top: `${rect.y}%`,
+              width: `${rect.width}%`,
+              height: `${rect.height}%`,
+              background: getTreemapFill(rect, selected)
+            }}
+          >
+            {area >= 80 ? (
+              <span className="block min-w-0 text-[11px] font-medium leading-tight text-foreground">
+                <span className="block truncate">{rect.label}</span>
+                {area >= 180 ? (
+                  <span className="mt-0.5 block truncate text-muted-foreground">
+                    {formatBytes(rect.sizeBytes)}
+                  </span>
+                ) : null}
+              </span>
+            ) : null}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+function SizeBar({ value, max }: { value: number; max: number }): React.JSX.Element {
+  const pct = max > 0 ? Math.max(2, Math.min(100, (value / max) * 100)) : 0
+  return (
+    <div className="h-1.5 overflow-hidden rounded-full bg-muted">
+      <div className="h-full rounded-full bg-foreground/65" style={{ width: `${pct}%` }} />
+    </div>
+  )
+}
+
+function BreakdownList({
+  worktree,
+  isScanning
+}: {
+  worktree: WorkspaceSpaceWorktree | null
+  isScanning: boolean
+}): React.JSX.Element {
+  if (!worktree) {
+    return (
+      <div className="flex h-full min-h-72 items-center justify-center rounded-lg border border-dashed border-border/70 bg-muted/15 text-sm text-muted-foreground">
+        <span className="flex items-center gap-2">
+          {isScanning ? <Loader2 className="size-4 animate-spin" /> : null}
+          {isScanning
+            ? 'Scanning workspace sizes. You can leave this page.'
+            : 'Select a workspace to inspect.'}
+        </span>
+      </div>
+    )
+  }
+
+  const maxChildSize = Math.max(...worktree.topLevelItems.map((item) => item.sizeBytes), 0)
+  const topLevelItemCount = worktree.topLevelItems.length + worktree.omittedTopLevelItemCount
+  return (
+    <div className="min-h-72 rounded-lg border border-border/70 bg-background/35">
+      <div className="border-b border-border/60 px-4 py-3">
+        <div className="flex min-w-0 items-center justify-between gap-3">
+          <div className="min-w-0">
+            <div className="truncate text-sm font-semibold">{worktree.displayName}</div>
+            <div className="mt-0.5 truncate text-xs text-muted-foreground">
+              {worktree.repoDisplayName}
+            </div>
+          </div>
+          <div className="shrink-0 text-right">
+            <div className="text-sm font-semibold tabular-nums">
+              {formatBytes(worktree.sizeBytes)}
+            </div>
+            <div className="text-[11px] text-muted-foreground">
+              {formatCompactCount(topLevelItemCount)} top-level items
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {worktree.status !== 'ok' ? (
+        <div className="flex items-start gap-2 px-4 py-4 text-xs text-destructive">
+          <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
+          <span className="min-w-0 break-words">{worktree.error ?? 'Scan failed.'}</span>
+        </div>
+      ) : worktree.topLevelItems.length === 0 ? (
+        <div className="px-4 py-8 text-center text-sm text-muted-foreground">No files found.</div>
+      ) : (
+        <div className="max-h-72 overflow-y-auto scrollbar-sleek px-3 py-3">
+          <div className="space-y-2">
+            {worktree.topLevelItems.slice(0, 12).map((item) => (
+              <BreakdownRow key={`${item.path}:${item.name}`} item={item} maxSize={maxChildSize} />
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function BreakdownRow({
+  item,
+  maxSize
+}: {
+  item: WorkspaceSpaceItem
+  maxSize: number
+}): React.JSX.Element {
+  return (
+    <div className="space-y-1.5 rounded-md px-2 py-1.5 hover:bg-accent/50">
+      <div className="flex min-w-0 items-center justify-between gap-3 text-xs">
+        <span className="min-w-0 truncate font-medium">{item.name}</span>
+        <span className="shrink-0 tabular-nums text-muted-foreground">
+          {formatBytes(item.sizeBytes)}
+        </span>
+      </div>
+      <SizeBar value={item.sizeBytes} max={maxSize} />
+    </div>
+  )
+}
+
+function WorkspaceRow({
+  worktree,
+  maxSize,
+  selected,
+  inspected,
+  onToggleSelected,
+  onInspect
+}: {
+  worktree: WorkspaceSpaceWorktree
+  maxSize: number
+  selected: boolean
+  inspected: boolean
+  onToggleSelected: () => void
+  onInspect: () => void
+}): React.JSX.Element {
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      onClick={onInspect}
+      onKeyDown={(event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') {
+          return
+        }
+        event.preventDefault()
+        onInspect()
+      }}
+      className={cn(
+        'grid w-full cursor-pointer grid-cols-[1.75rem_minmax(0,1.35fr)_minmax(9rem,0.65fr)_8rem_6rem] items-center gap-3 border-b border-border/45 px-3 py-2.5 text-left text-sm transition-colors last:border-b-0 hover:bg-accent/45 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        inspected && 'bg-accent/55'
+      )}
+    >
+      <CheckButton
+        checked={selected}
+        disabled={!worktree.canDelete || worktree.status !== 'ok'}
+        label={`Select ${worktree.displayName}`}
+        onClick={onToggleSelected}
+      />
+
+      <div className="min-w-0">
+        <div className="flex min-w-0 items-center gap-2">
+          <span className="min-w-0 truncate font-medium">{worktree.displayName}</span>
+          {worktree.isRemote ? (
+            <Server className="size-3.5 shrink-0 text-muted-foreground" />
+          ) : null}
+          {worktree.isSparse ? <Badge variant="outline">Sparse</Badge> : null}
+        </div>
+        <div className="mt-1 flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground">
+          <GitBranch className="size-3 shrink-0" />
+          <span className="truncate">{getWorkspaceSpaceBranchLabel(worktree)}</span>
+        </div>
+        <div className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
+          {worktree.path}
+        </div>
+      </div>
+
+      <div className="min-w-0 text-xs">
+        <div className="truncate font-medium">{worktree.repoDisplayName}</div>
+        <div className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
+          {worktree.repoPath}
+        </div>
+      </div>
+
+      <div className="min-w-0 space-y-1.5">
+        <div className="text-right text-sm font-medium tabular-nums">
+          {worktree.status === 'ok' ? formatBytes(worktree.sizeBytes) : '—'}
+        </div>
+        <SizeBar value={worktree.sizeBytes} max={maxSize} />
+      </div>
+
+      <div className="flex justify-end">
+        <StatusBadge worktree={worktree} />
+      </div>
+    </div>
+  )
+}
+
+export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
+  const analysis = useAppStore((state) => state.workspaceSpaceAnalysis)
+  const scanError = useAppStore((state) => state.workspaceSpaceScanError)
+  const isScanning = useAppStore((state) => state.workspaceSpaceScanning)
+  const refreshWorkspaceSpace = useAppStore((state) => state.refreshWorkspaceSpace)
+  const removeWorkspaceSpaceWorktrees = useAppStore((state) => state.removeWorkspaceSpaceWorktrees)
+  const [query, setQuery] = useState('')
+  const [onlyDeletable, setOnlyDeletable] = useState(false)
+  const [sortKey, setSortKey] = useState<WorkspaceSpaceSortKey>('size')
+  const [sortDirection, setSortDirection] = useState<WorkspaceSpaceSortDirection>('desc')
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(() => new Set())
+  const [inspectedWorktreeId, setInspectedWorktreeId] = useState<string | null>(null)
+
+  const refresh = useCallback((): void => {
+    void refreshWorkspaceSpace().catch(() => {
+      /* scanError is stored by the slice */
+    })
+  }, [refreshWorkspaceSpace])
+
+  const sourceRows = useMemo(() => analysis?.worktrees ?? [], [analysis?.worktrees])
+
+  const rows = useMemo(
+    () =>
+      sortWorkspaceSpaceRows(
+        filterWorkspaceSpaceRows(sourceRows, query, onlyDeletable),
+        sortKey,
+        sortDirection
+      ),
+    [onlyDeletable, query, sortDirection, sortKey, sourceRows]
+  )
+
+  const inspectedWorktree =
+    rows.find((row) => row.worktreeId === inspectedWorktreeId) ??
+    rows.find((row) => row.status === 'ok') ??
+    null
+  const maxSize = Math.max(...rows.map((row) => row.sizeBytes), 0)
+  const selectedDeletableIds = getSelectedDeletableWorkspaceIds(rows, selectedIds)
+  const visibleDeletableIds = rows
+    .filter((row) => row.canDelete && row.status === 'ok')
+    .map((row) => row.worktreeId)
+  const allVisibleSelected =
+    visibleDeletableIds.length > 0 && visibleDeletableIds.every((id) => selectedIds.has(id))
+  const isInitialScan = isScanning && !analysis
+
+  useEffect(() => {
+    if (!analysis) {
+      setInspectedWorktreeId(null)
+      return
+    }
+    setInspectedWorktreeId((current) =>
+      current && analysis.worktrees.some((worktree) => worktree.worktreeId === current)
+        ? current
+        : (analysis.worktrees.find((worktree) => worktree.status === 'ok')?.worktreeId ?? null)
+    )
+  }, [analysis])
+
+  useEffect(() => {
+    setSelectedIds((current) => {
+      const valid = new Set(sourceRows.map((row) => row.worktreeId))
+      const next = new Set([...current].filter((id) => valid.has(id)))
+      return next.size === current.size ? current : next
+    })
+  }, [sourceRows])
+
+  const toggleSort = (key: WorkspaceSpaceSortKey): void => {
+    if (sortKey === key) {
+      setSortDirection((current) => (current === 'asc' ? 'desc' : 'asc'))
+      return
+    }
+    setSortKey(key)
+    setSortDirection(key === 'name' || key === 'repo' ? 'asc' : 'desc')
+  }
+
+  const toggleSelection = (worktreeId: string): void => {
+    setSelectedIds((current) => {
+      const next = new Set(current)
+      if (next.has(worktreeId)) {
+        next.delete(worktreeId)
+      } else {
+        next.add(worktreeId)
+      }
+      return next
+    })
+  }
+
+  const toggleVisibleSelection = (): void => {
+    setSelectedIds((current) => {
+      const next = new Set(current)
+      if (allVisibleSelected) {
+        for (const id of visibleDeletableIds) {
+          next.delete(id)
+        }
+      } else {
+        for (const id of visibleDeletableIds) {
+          next.add(id)
+        }
+      }
+      return next
+    })
+  }
+
+  const deleteSelected = (): void => {
+    if (selectedDeletableIds.length === 0) {
+      return
+    }
+    const started = runWorktreeBatchDelete(selectedDeletableIds, {
+      onDeleted: (deletedIds) => {
+        removeWorkspaceSpaceWorktrees(deletedIds)
+        setInspectedWorktreeId((current) =>
+          current && deletedIds.includes(current) ? null : current
+        )
+        toast.success(deletedIds.length === 1 ? 'Workspace deleted' : 'Workspaces deleted', {
+          description: `${deletedIds.length} ${deletedIds.length === 1 ? 'workspace' : 'workspaces'} removed from Space.`
+        })
+      }
+    })
+    if (started) {
+      setSelectedIds(new Set<string>())
+    }
+  }
+
+  return (
+    <div className="space-y-5">
+      <div className="grid overflow-hidden rounded-lg border border-border/65 bg-background/35 md:grid-cols-4 md:divide-x md:divide-border/60">
+        <Metric label="Scanned" value={analysis ? formatBytes(analysis.totalSizeBytes) : '—'} />
+        <Metric
+          label="Reclaimable"
+          value={analysis ? formatBytes(analysis.reclaimableBytes) : '—'}
+        />
+        <Metric label="Workspaces" value={analysis ? String(analysis.scannedWorktreeCount) : '—'} />
+        <Metric
+          label="Updated"
+          value={
+            analysis
+              ? getWorkspaceSpaceScanTimeLabel(analysis.scannedAt)
+              : isScanning
+                ? 'Scanning'
+                : '—'
+          }
+        />
+      </div>
+
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div className="flex min-w-0 items-center gap-2 text-xs text-muted-foreground">
+          <HardDrive className="size-4 shrink-0" />
+          <span className="truncate">
+            {analysis
+              ? `${formatBytes(analysis.reclaimableBytes)} can be reclaimed from linked worktrees.`
+              : isScanning
+                ? 'Scanning workspace sizes in the background. You can leave this page.'
+                : 'Run a scan to inspect workspace sizes.'}
+          </span>
+        </div>
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={refresh}
+          disabled={isScanning}
+          className="w-28 gap-1.5"
+        >
+          {isScanning ? (
+            <Loader2 className="size-3.5 animate-spin" />
+          ) : (
+            <RefreshCw className="size-3.5" />
+          )}
+          {isScanning ? 'Scanning' : analysis ? 'Refresh' : 'Scan'}
+        </Button>
+      </div>
+
+      {scanError ? (
+        <div className="flex items-start gap-2 rounded-md border border-destructive/35 bg-destructive/8 px-3 py-2 text-xs text-destructive">
+          <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
+          <span className="min-w-0 break-words">{scanError}</span>
+        </div>
+      ) : null}
+
+      <div className="grid gap-4 xl:grid-cols-[minmax(0,1.4fr)_minmax(20rem,0.6fr)]">
+        <WorkspaceTreemap
+          rows={sourceRows}
+          isScanning={isInitialScan}
+          selectedWorktreeId={inspectedWorktree?.worktreeId ?? null}
+          onSelect={setInspectedWorktreeId}
+        />
+        <BreakdownList worktree={inspectedWorktree} isScanning={isInitialScan} />
+      </div>
+
+      <div className="flex flex-wrap items-center gap-2">
+        <div className="relative min-w-[16rem] flex-1">
+          <Search className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            placeholder="Filter workspaces"
+            className="pl-9"
+          />
+        </div>
+
+        <Select
+          value={sortKey}
+          onValueChange={(value) => setSortKey(value as WorkspaceSpaceSortKey)}
+        >
+          <SelectTrigger className="w-36">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="size">Size</SelectItem>
+            <SelectItem value="name">Name</SelectItem>
+            <SelectItem value="repo">Repository</SelectItem>
+            <SelectItem value="activity">Activity</SelectItem>
+          </SelectContent>
+        </Select>
+
+        <Button
+          variant={onlyDeletable ? 'secondary' : 'outline'}
+          size="sm"
+          onClick={() => setOnlyDeletable((current) => !current)}
+          className="w-32"
+        >
+          {onlyDeletable ? 'Deletable' : 'All'}
+        </Button>
+
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={toggleVisibleSelection}
+          disabled={visibleDeletableIds.length === 0}
+          className="w-32 gap-1.5"
+        >
+          <Check className="size-3.5" />
+          {allVisibleSelected ? 'Clear' : 'Select'}
+        </Button>
+
+        <Button
+          variant="destructive"
+          size="sm"
+          onClick={deleteSelected}
+          disabled={selectedDeletableIds.length === 0}
+          className="w-32 gap-1.5"
+        >
+          <Trash2 className="size-3.5" />
+          {selectedDeletableIds.length > 0 ? `Delete ${selectedDeletableIds.length}` : 'Delete'}
+        </Button>
+      </div>
+
+      <div className="overflow-hidden rounded-lg border border-border/70 bg-background/30">
+        <div className="grid grid-cols-[1.75rem_minmax(0,1.35fr)_minmax(9rem,0.65fr)_8rem_6rem] gap-3 border-b border-border/60 px-3 py-2 text-[11px] font-medium uppercase tracking-[0.14em] text-muted-foreground">
+          <div />
+          <button
+            type="button"
+            onClick={() => toggleSort('name')}
+            className="flex items-center gap-1 text-left"
+          >
+            Workspace
+            <SortIndicator sortKey="name" activeKey={sortKey} direction={sortDirection} />
+          </button>
+          <button
+            type="button"
+            onClick={() => toggleSort('repo')}
+            className="flex items-center gap-1 text-left"
+          >
+            Repository
+            <SortIndicator sortKey="repo" activeKey={sortKey} direction={sortDirection} />
+          </button>
+          <button
+            type="button"
+            onClick={() => toggleSort('size')}
+            className="flex items-center justify-end gap-1 text-right"
+          >
+            Size
+            <SortIndicator sortKey="size" activeKey={sortKey} direction={sortDirection} />
+          </button>
+          <div className="text-right">State</div>
+        </div>
+
+        <div className="max-h-[28rem] overflow-y-auto scrollbar-sleek">
+          {isInitialScan ? (
+            <div className="flex items-center justify-center gap-2 px-4 py-10 text-center text-sm text-muted-foreground">
+              <Loader2 className="size-4 animate-spin" />
+              Scanning workspaces. You can leave this page.
+            </div>
+          ) : rows.length === 0 ? (
+            <div className="px-4 py-10 text-center text-sm text-muted-foreground">
+              No matching workspaces.
+            </div>
+          ) : (
+            rows.map((worktree) => (
+              <WorkspaceRow
+                key={worktree.worktreeId}
+                worktree={worktree}
+                maxSize={maxSize}
+                selected={selectedIds.has(worktree.worktreeId)}
+                inspected={inspectedWorktree?.worktreeId === worktree.worktreeId}
+                onToggleSelected={() => toggleSelection(worktree.worktreeId)}
+                onInspect={() => setInspectedWorktreeId(worktree.worktreeId)}
+              />
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
index 665b3b620db..8bf4c3e9e93 100644
--- a/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
+++ b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
@@ -4,7 +4,7 @@
    in ResourceUsageStatusSegment.tsx. Splitting would scatter logic that has
    exactly one consumer. See docs/resource-usage-merge-spec.md. */
 /**
- * Resource Usage popover merge helper.
+ * Resource Manager popover merge helper.
  *
  * Produces a single grouped list (repo → worktree → session) by unifying:
  *
diff --git a/src/renderer/src/components/status-bar/workspace-space-format.test.ts b/src/renderer/src/components/status-bar/workspace-space-format.test.ts
new file mode 100644
index 00000000000..9f239b0e075
--- /dev/null
+++ b/src/renderer/src/components/status-bar/workspace-space-format.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import {
+  formatBytes,
+  formatCompactCount,
+  getWorkspaceSpaceStatusLabel
+} from './workspace-space-format'
+
+describe('workspace space format helpers', () => {
+  it('formats byte values with stable units', () => {
+    expect(formatBytes(0)).toBe('0 B')
+    expect(formatBytes(512)).toBe('512 B')
+    expect(formatBytes(1536)).toBe('1.50 KB')
+    expect(formatBytes(5 * 1024 * 1024)).toBe('5.00 MB')
+  })
+
+  it('formats counts and statuses for dense table UI', () => {
+    expect(formatCompactCount(1530)).toBe('1.5k')
+    expect(formatCompactCount(25_000)).toBe('25k')
+    expect(getWorkspaceSpaceStatusLabel('permission-denied')).toBe('No access')
+  })
+})
diff --git a/src/renderer/src/components/status-bar/workspace-space-format.ts b/src/renderer/src/components/status-bar/workspace-space-format.ts
new file mode 100644
index 00000000000..9566e4e3911
--- /dev/null
+++ b/src/renderer/src/components/status-bar/workspace-space-format.ts
@@ -0,0 +1,59 @@
+import type {
+  WorkspaceSpaceScanStatus,
+  WorkspaceSpaceWorktree
+} from '../../../../shared/workspace-space-types'
+
+const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'] as const
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    return '0 B'
+  }
+
+  let value = bytes
+  let unitIndex = 0
+  while (value >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+    value /= 1024
+    unitIndex += 1
+  }
+
+  const precision = value >= 100 || unitIndex === 0 ? 0 : value >= 10 ? 1 : 2
+  return `${value.toFixed(precision)} ${BYTE_UNITS[unitIndex]}`
+}
+
+export function formatCompactCount(count: number): string {
+  if (!Number.isFinite(count) || count <= 0) {
+    return '0'
+  }
+  if (count < 1000) {
+    return String(count)
+  }
+  if (count < 1_000_000) {
+    return `${(count / 1000).toFixed(count >= 10_000 ? 0 : 1)}k`
+  }
+  return `${(count / 1_000_000).toFixed(count >= 10_000_000 ? 0 : 1)}m`
+}
+
+export function getWorkspaceSpaceScanTimeLabel(scannedAt: number): string {
+  return new Date(scannedAt).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+}
+
+export function getWorkspaceSpaceStatusLabel(status: WorkspaceSpaceScanStatus): string {
+  switch (status) {
+    case 'ok':
+      return 'Scanned'
+    case 'missing':
+      return 'Missing'
+    case 'permission-denied':
+      return 'No access'
+    case 'unavailable':
+      return 'Unavailable'
+    case 'error':
+      return 'Failed'
+  }
+}
+
+export function getWorkspaceSpaceBranchLabel(worktree: WorkspaceSpaceWorktree): string {
+  const branch = worktree.branch.replace(/^refs\/heads\//, '').trim()
+  return branch || (worktree.isMainWorktree ? 'main worktree' : 'detached')
+}
diff --git a/src/renderer/src/components/status-bar/workspace-space-layout.test.ts b/src/renderer/src/components/status-bar/workspace-space-layout.test.ts
new file mode 100644
index 00000000000..d1857a17e74
--- /dev/null
+++ b/src/renderer/src/components/status-bar/workspace-space-layout.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { buildTreemapLayout } from './workspace-space-layout'
+
+describe('buildTreemapLayout', () => {
+  it('lays out positive-size items inside a 100x100 treemap', () => {
+    const rects = buildTreemapLayout([
+      { id: 'a', label: 'A', sizeBytes: 60 },
+      { id: 'b', label: 'B', sizeBytes: 30 },
+      { id: 'c', label: 'C', sizeBytes: 10 },
+      { id: 'empty', label: 'Empty', sizeBytes: 0 }
+    ])
+
+    expect(rects.map((rect) => rect.id)).toEqual(['a', 'b', 'c'])
+    for (const rect of rects) {
+      expect(rect.x).toBeGreaterThanOrEqual(0)
+      expect(rect.y).toBeGreaterThanOrEqual(0)
+      expect(rect.x + rect.width).toBeLessThanOrEqual(100)
+      expect(rect.y + rect.height).toBeLessThanOrEqual(100)
+    }
+    const area = rects.reduce((sum, rect) => sum + rect.width * rect.height, 0)
+    expect(area).toBeCloseTo(10_000, 5)
+    expect(rects[0].width * rects[0].height).toBeGreaterThan(rects[1].width * rects[1].height)
+  })
+})
diff --git a/src/renderer/src/components/status-bar/workspace-space-layout.ts b/src/renderer/src/components/status-bar/workspace-space-layout.ts
new file mode 100644
index 00000000000..18f739ad99f
--- /dev/null
+++ b/src/renderer/src/components/status-bar/workspace-space-layout.ts
@@ -0,0 +1,124 @@
+export type TreemapInput = {
+  id: string
+  label: string
+  sizeBytes: number
+}
+
+export type TreemapRect = TreemapInput & {
+  x: number
+  y: number
+  width: number
+  height: number
+  depth: number
+  index: number
+}
+
+type Bounds = {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+function sumSizes(items: readonly TreemapInput[]): number {
+  return items.reduce((sum, item) => sum + Math.max(0, item.sizeBytes), 0)
+}
+
+function splitBalanced(items: readonly TreemapInput[]): {
+  first: TreemapInput[]
+  second: TreemapInput[]
+} {
+  const total = sumSizes(items)
+  if (items.length <= 1 || total <= 0) {
+    return { first: [...items], second: [] }
+  }
+
+  const target = total / 2
+  let running = 0
+  let splitIndex = 0
+  for (let index = 0; index < items.length; index += 1) {
+    const next = running + Math.max(0, items[index].sizeBytes)
+    if (index > 0 && Math.abs(target - running) < Math.abs(target - next)) {
+      break
+    }
+    running = next
+    splitIndex = index + 1
+  }
+
+  splitIndex = Math.min(items.length - 1, Math.max(1, splitIndex))
+  return {
+    first: items.slice(0, splitIndex),
+    second: items.slice(splitIndex)
+  }
+}
+
+function layoutTreemapRecursive(
+  items: readonly TreemapInput[],
+  bounds: Bounds,
+  depth: number,
+  output: TreemapRect[]
+): void {
+  if (items.length === 0 || bounds.width <= 0 || bounds.height <= 0) {
+    return
+  }
+
+  if (items.length === 1) {
+    const item = items[0]
+    output.push({
+      ...item,
+      ...bounds,
+      depth,
+      index: output.length
+    })
+    return
+  }
+
+  const total = sumSizes(items)
+  if (total <= 0) {
+    return
+  }
+
+  const { first, second } = splitBalanced(items)
+  const firstSize = sumSizes(first)
+  const ratio = firstSize / total
+
+  if (bounds.width >= bounds.height) {
+    const firstWidth = bounds.width * ratio
+    layoutTreemapRecursive(first, { ...bounds, width: firstWidth }, depth + 1, output)
+    layoutTreemapRecursive(
+      second,
+      {
+        x: bounds.x + firstWidth,
+        y: bounds.y,
+        width: bounds.width - firstWidth,
+        height: bounds.height
+      },
+      depth + 1,
+      output
+    )
+    return
+  }
+
+  const firstHeight = bounds.height * ratio
+  layoutTreemapRecursive(first, { ...bounds, height: firstHeight }, depth + 1, output)
+  layoutTreemapRecursive(
+    second,
+    {
+      x: bounds.x,
+      y: bounds.y + firstHeight,
+      width: bounds.width,
+      height: bounds.height - firstHeight
+    },
+    depth + 1,
+    output
+  )
+}
+
+export function buildTreemapLayout(items: readonly TreemapInput[]): TreemapRect[] {
+  const filtered = items
+    .filter((item) => item.sizeBytes > 0)
+    .sort((a, b) => b.sizeBytes - a.sizeBytes || a.label.localeCompare(b.label))
+  const output: TreemapRect[] = []
+  layoutTreemapRecursive(filtered, { x: 0, y: 0, width: 100, height: 100 }, 0, output)
+  return output
+}
diff --git a/src/renderer/src/components/status-bar/workspace-space-presentation.test.ts b/src/renderer/src/components/status-bar/workspace-space-presentation.test.ts
new file mode 100644
index 00000000000..7c386b07867
--- /dev/null
+++ b/src/renderer/src/components/status-bar/workspace-space-presentation.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import type { WorkspaceSpaceWorktree } from '../../../../shared/workspace-space-types'
+import {
+  filterWorkspaceSpaceRows,
+  getSelectedDeletableWorkspaceIds,
+  sortWorkspaceSpaceRows
+} from './workspace-space-presentation'
+
+function row(overrides: Partial<WorkspaceSpaceWorktree>): WorkspaceSpaceWorktree {
+  return {
+    worktreeId: 'wt',
+    repoId: 'repo',
+    repoDisplayName: 'repo',
+    repoPath: '/repo',
+    displayName: 'workspace',
+    path: '/workspace',
+    branch: 'refs/heads/main',
+    isMainWorktree: false,
+    isRemote: false,
+    isSparse: false,
+    canDelete: true,
+    lastActivityAt: 0,
+    status: 'ok',
+    error: null,
+    scannedAt: 0,
+    sizeBytes: 0,
+    reclaimableBytes: 0,
+    skippedEntryCount: 0,
+    topLevelItems: [],
+    omittedTopLevelItemCount: 0,
+    omittedTopLevelSizeBytes: 0,
+    ...overrides
+  }
+}
+
+describe('workspace space presentation helpers', () => {
+  it('sorts rows by the selected key and direction', () => {
+    const rows = [
+      row({ worktreeId: 'small', displayName: 'Small', sizeBytes: 10 }),
+      row({ worktreeId: 'large', displayName: 'Large', sizeBytes: 100 }),
+      row({ worktreeId: 'mid', displayName: 'Mid', sizeBytes: 50 })
+    ]
+
+    expect(sortWorkspaceSpaceRows(rows, 'size', 'desc').map((item) => item.worktreeId)).toEqual([
+      'large',
+      'mid',
+      'small'
+    ])
+    expect(sortWorkspaceSpaceRows(rows, 'name', 'asc').map((item) => item.worktreeId)).toEqual([
+      'large',
+      'mid',
+      'small'
+    ])
+  })
+
+  it('filters by search text and deletable status', () => {
+    const rows = [
+      row({ worktreeId: 'a', displayName: 'Frontend Cache', repoDisplayName: 'app' }),
+      row({ worktreeId: 'b', displayName: 'Main', repoDisplayName: 'api', canDelete: false })
+    ]
+
+    expect(filterWorkspaceSpaceRows(rows, 'cache', false).map((item) => item.worktreeId)).toEqual([
+      'a'
+    ])
+    expect(filterWorkspaceSpaceRows(rows, '', true).map((item) => item.worktreeId)).toEqual(['a'])
+  })
+
+  it('returns only selected worktrees that can be deleted', () => {
+    const rows = [
+      row({ worktreeId: 'ok', canDelete: true, status: 'ok' }),
+      row({ worktreeId: 'main', canDelete: false, status: 'ok' }),
+      row({ worktreeId: 'failed', canDelete: true, status: 'error' })
+    ]
+
+    expect(getSelectedDeletableWorkspaceIds(rows, new Set(['ok', 'main', 'failed']))).toEqual([
+      'ok'
+    ])
+  })
+})
diff --git a/src/renderer/src/components/status-bar/workspace-space-presentation.ts b/src/renderer/src/components/status-bar/workspace-space-presentation.ts
new file mode 100644
index 00000000000..4dd3c1d5059
--- /dev/null
+++ b/src/renderer/src/components/status-bar/workspace-space-presentation.ts
@@ -0,0 +1,78 @@
+import type { WorkspaceSpaceWorktree } from '../../../../shared/workspace-space-types'
+
+export type WorkspaceSpaceSortKey = 'size' | 'name' | 'repo' | 'activity'
+export type WorkspaceSpaceSortDirection = 'asc' | 'desc'
+
+export function getWorkspaceSpaceSearchText(worktree: WorkspaceSpaceWorktree): string {
+  return [
+    worktree.displayName,
+    worktree.repoDisplayName,
+    worktree.path,
+    worktree.branch,
+    worktree.status
+  ]
+    .join(' ')
+    .toLowerCase()
+}
+
+function compareRows(
+  left: WorkspaceSpaceWorktree,
+  right: WorkspaceSpaceWorktree,
+  sortKey: WorkspaceSpaceSortKey
+): number {
+  switch (sortKey) {
+    case 'size':
+      return left.sizeBytes - right.sizeBytes
+    case 'name':
+      return left.displayName.localeCompare(right.displayName)
+    case 'repo':
+      return (
+        left.repoDisplayName.localeCompare(right.repoDisplayName) ||
+        left.displayName.localeCompare(right.displayName)
+      )
+    case 'activity':
+      return left.lastActivityAt - right.lastActivityAt
+  }
+}
+
+export function sortWorkspaceSpaceRows(
+  rows: readonly WorkspaceSpaceWorktree[],
+  sortKey: WorkspaceSpaceSortKey,
+  direction: WorkspaceSpaceSortDirection
+): WorkspaceSpaceWorktree[] {
+  const multiplier = direction === 'asc' ? 1 : -1
+  return [...rows].sort((left, right) => {
+    const primary = compareRows(left, right, sortKey) * multiplier
+    return (
+      primary ||
+      right.sizeBytes - left.sizeBytes ||
+      left.displayName.localeCompare(right.displayName)
+    )
+  })
+}
+
+export function filterWorkspaceSpaceRows(
+  rows: readonly WorkspaceSpaceWorktree[],
+  query: string,
+  onlyDeletable: boolean
+): WorkspaceSpaceWorktree[] {
+  const normalizedQuery = query.trim().toLowerCase()
+  return rows.filter((row) => {
+    if (onlyDeletable && !row.canDelete) {
+      return false
+    }
+    if (!normalizedQuery) {
+      return true
+    }
+    return getWorkspaceSpaceSearchText(row).includes(normalizedQuery)
+  })
+}
+
+export function getSelectedDeletableWorkspaceIds(
+  rows: readonly WorkspaceSpaceWorktree[],
+  selectedIds: ReadonlySet<string>
+): string[] {
+  return rows
+    .filter((row) => row.canDelete && row.status === 'ok' && selectedIds.has(row.worktreeId))
+    .map((row) => row.worktreeId)
+}
diff --git a/src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx b/src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx
new file mode 100644
index 00000000000..0fed37c3afa
--- /dev/null
+++ b/src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx
@@ -0,0 +1,59 @@
+import { useEffect } from 'react'
+import { ArrowLeft, HardDrive } from 'lucide-react'
+import { Badge } from '../ui/badge'
+import { Button } from '../ui/button'
+import { WorkspaceSpaceManagerPanel } from '../status-bar/WorkspaceSpaceManagerPanel'
+import { useAppStore } from '../../store'
+
+export default function WorkspaceSpacePage(): React.JSX.Element {
+  const closeSpacePage = useAppStore((state) => state.closeSpacePage)
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent): void => {
+      if (event.key !== 'Escape' || event.defaultPrevented) {
+        return
+      }
+      // Why: confirmation dialogs own Escape first; page-level Escape should
+      // only leave the full Space surface when no modal is active.
+      if (document.querySelector('[role="dialog"]')) {
+        return
+      }
+      event.preventDefault()
+      closeSpacePage()
+    }
+
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [closeSpacePage])
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-background">
+      <div className="flex shrink-0 items-center gap-3 border-b border-border px-5 py-3">
+        <Button variant="outline" size="sm" onClick={closeSpacePage} className="shrink-0 gap-1.5">
+          <ArrowLeft className="size-3.5" />
+          Back
+        </Button>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="flex size-8 shrink-0 items-center justify-center rounded-md border border-border bg-muted/30">
+            <HardDrive className="size-4 text-muted-foreground" />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 items-center gap-2">
+              <h1 className="truncate text-base font-semibold text-foreground">Space</h1>
+              <Badge variant="secondary">Beta</Badge>
+            </div>
+            <p className="truncate text-xs text-muted-foreground">
+              Workspace disk usage and reclaimable worktree storage.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-5 scrollbar-sleek">
+        <div className="mx-auto max-w-7xl">
+          <WorkspaceSpaceManagerPanel />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/hooks/resolve-zoom-target.ts b/src/renderer/src/hooks/resolve-zoom-target.ts
index 255fbf386ce..f03b3786cd0 100644
--- a/src/renderer/src/hooks/resolve-zoom-target.ts
+++ b/src/renderer/src/hooks/resolve-zoom-target.ts
@@ -3,7 +3,7 @@
  * based on current view, tab type, and focused element.
  */
 export function resolveZoomTarget(args: {
-  activeView: 'terminal' | 'settings' | 'tasks' | 'activity' | 'automations'
+  activeView: 'terminal' | 'settings' | 'tasks' | 'activity' | 'automations' | 'space'
   activeTabType: 'terminal' | 'editor' | 'browser' | 'notes'
   activeElement: unknown
 }): 'terminal' | 'editor' | 'ui' {
diff --git a/src/renderer/src/store/index.ts b/src/renderer/src/store/index.ts
index d7e07344be9..76a8c91ed87 100644
--- a/src/renderer/src/store/index.ts
+++ b/src/renderer/src/store/index.ts
@@ -13,6 +13,7 @@ import { createLinearSlice } from './slices/linear'
 import { createEditorSlice } from './slices/editor'
 import { createStatsSlice } from './slices/stats'
 import { createMemorySlice } from './slices/memory'
+import { createWorkspaceSpaceSlice } from './slices/workspace-space'
 import { createClaudeUsageSlice } from './slices/claude-usage'
 import { createCodexUsageSlice } from './slices/codex-usage'
 import { createBrowserSlice } from './slices/browser'
@@ -40,6 +41,7 @@ export const useAppStore = create<AppState>()((...a) => ({
   ...createEditorSlice(...a),
   ...createStatsSlice(...a),
   ...createMemorySlice(...a),
+  ...createWorkspaceSpaceSlice(...a),
   ...createClaudeUsageSlice(...a),
   ...createCodexUsageSlice(...a),
   ...createBrowserSlice(...a),
diff --git a/src/renderer/src/store/slices/diffComments.test.ts b/src/renderer/src/store/slices/diffComments.test.ts
index b989a7667dd..827d9e3831e 100644
--- a/src/renderer/src/store/slices/diffComments.test.ts
+++ b/src/renderer/src/store/slices/diffComments.test.ts
@@ -85,6 +85,7 @@ import { createLinearSlice } from './linear'
 import { createEditorSlice } from './editor'
 import { createStatsSlice } from './stats'
 import { createMemorySlice } from './memory'
+import { createWorkspaceSpaceSlice } from './workspace-space'
 import { createClaudeUsageSlice } from './claude-usage'
 import { createCodexUsageSlice } from './codex-usage'
 import { createBrowserSlice } from './browser'
@@ -111,6 +112,7 @@ function createTestStore() {
     ...createEditorSlice(...a),
     ...createStatsSlice(...a),
     ...createMemorySlice(...a),
+    ...createWorkspaceSpaceSlice(...a),
     ...createClaudeUsageSlice(...a),
     ...createCodexUsageSlice(...a),
     ...createBrowserSlice(...a),
diff --git a/src/renderer/src/store/slices/memory.ts b/src/renderer/src/store/slices/memory.ts
index b24de6d0c89..a011adaf87c 100644
--- a/src/renderer/src/store/slices/memory.ts
+++ b/src/renderer/src/store/slices/memory.ts
@@ -17,7 +17,7 @@ export const createMemorySlice: StateCreator<AppState, [], [], MemorySlice> = (s
       const snapshot = await window.api.memory.getSnapshot()
       set({ memorySnapshot: snapshot, memorySnapshotError: null })
     } catch (err) {
-      // Why: the always-on Resource Usage status-bar segment needs to know when
+      // Why: the always-on Resource Manager status-bar segment needs to know when
       // the snapshot IPC is failing so it can surface a "daemon not responding"
       // banner with a Restart CTA. Prior code only console.error'd.
       console.error('Failed to fetch memory snapshot:', err)
diff --git a/src/renderer/src/store/slices/store-session-cascades.test.ts b/src/renderer/src/store/slices/store-session-cascades.test.ts
index 80495de0ceb..2e86742c240 100644
--- a/src/renderer/src/store/slices/store-session-cascades.test.ts
+++ b/src/renderer/src/store/slices/store-session-cascades.test.ts
@@ -102,6 +102,7 @@ import { createLinearSlice } from './linear'
 import { createEditorSlice } from './editor'
 import { createStatsSlice } from './stats'
 import { createMemorySlice } from './memory'
+import { createWorkspaceSpaceSlice } from './workspace-space'
 import { createClaudeUsageSlice } from './claude-usage'
 import { createCodexUsageSlice } from './codex-usage'
 import { createBrowserSlice } from './browser'
@@ -128,6 +129,7 @@ function createTestStore() {
     ...createEditorSlice(...a),
     ...createStatsSlice(...a),
     ...createMemorySlice(...a),
+    ...createWorkspaceSpaceSlice(...a),
     ...createClaudeUsageSlice(...a),
     ...createCodexUsageSlice(...a),
     ...createBrowserSlice(...a),
diff --git a/src/renderer/src/store/slices/store-test-helpers.ts b/src/renderer/src/store/slices/store-test-helpers.ts
index 21b9fff0da4..e4c43e4dfb8 100644
--- a/src/renderer/src/store/slices/store-test-helpers.ts
+++ b/src/renderer/src/store/slices/store-test-helpers.ts
@@ -21,6 +21,7 @@ import { createLinearSlice } from './linear'
 import { createEditorSlice } from './editor'
 import { createStatsSlice } from './stats'
 import { createMemorySlice } from './memory'
+import { createWorkspaceSpaceSlice } from './workspace-space'
 import { createClaudeUsageSlice } from './claude-usage'
 import { createCodexUsageSlice } from './codex-usage'
 import { createBrowserSlice } from './browser'
@@ -55,6 +56,7 @@ export function createTestStore() {
     ...createEditorSlice(...a),
     ...createStatsSlice(...a),
     ...createMemorySlice(...a),
+    ...createWorkspaceSpaceSlice(...a),
     ...createClaudeUsageSlice(...a),
     ...createCodexUsageSlice(...a),
     ...createBrowserSlice(...a),
diff --git a/src/renderer/src/store/slices/tabs.test.ts b/src/renderer/src/store/slices/tabs.test.ts
index 2af817e444e..3394284cf3e 100644
--- a/src/renderer/src/store/slices/tabs.test.ts
+++ b/src/renderer/src/store/slices/tabs.test.ts
@@ -97,6 +97,7 @@ import { createLinearSlice } from './linear'
 import { createEditorSlice } from './editor'
 import { createStatsSlice } from './stats'
 import { createMemorySlice } from './memory'
+import { createWorkspaceSpaceSlice } from './workspace-space'
 import { createClaudeUsageSlice } from './claude-usage'
 import { createCodexUsageSlice } from './codex-usage'
 import { createBrowserSlice } from './browser'
@@ -125,6 +126,7 @@ function createTestStore() {
     ...createEditorSlice(...a),
     ...createStatsSlice(...a),
     ...createMemorySlice(...a),
+    ...createWorkspaceSpaceSlice(...a),
     ...createClaudeUsageSlice(...a),
     ...createCodexUsageSlice(...a),
     ...createBrowserSlice(...a),
diff --git a/src/renderer/src/store/slices/ui.test.ts b/src/renderer/src/store/slices/ui.test.ts
index bc12e7e1007..ce28fbca880 100644
--- a/src/renderer/src/store/slices/ui.test.ts
+++ b/src/renderer/src/store/slices/ui.test.ts
@@ -446,3 +446,33 @@ describe('createUISlice feature tour nudge', () => {
     expect(store.getState().featureTourNudgeVisible).toBe(false)
   })
 })
+
+describe('createUISlice space navigation', () => {
+  it('returns to the tasks page after opening Space from an in-progress draft', () => {
+    const store = createUIStore()
+
+    store.getState().openTaskPage({ preselectedRepoId: 'repo-1' })
+    store.getState().openSpacePage()
+
+    expect(store.getState().activeView).toBe('space')
+    expect(store.getState().previousViewBeforeSpace).toBe('tasks')
+
+    store.getState().closeSpacePage()
+
+    expect(store.getState().activeView).toBe('tasks')
+  })
+
+  it('keeps the original return target when Space is reopened while already visible', () => {
+    const store = createUIStore()
+
+    store.getState().openTaskPage()
+    store.getState().openSpacePage()
+    store.getState().openSpacePage()
+
+    expect(store.getState().previousViewBeforeSpace).toBe('tasks')
+
+    store.getState().closeSpacePage()
+
+    expect(store.getState().activeView).toBe('tasks')
+  })
+})
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index 44acdabf574..8fce0f6cb15 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -194,11 +194,12 @@ export type UISlice = {
   acknowledgedAgentsByPaneKey: Record<string, number>
   acknowledgeAgents: (paneKeys: string[]) => void
   unacknowledgeAgents: (paneKeys: string[]) => void
-  activeView: 'terminal' | 'settings' | 'tasks' | 'activity' | 'automations'
-  previousViewBeforeTasks: 'terminal' | 'settings' | 'activity' | 'automations'
-  previousViewBeforeSettings: 'terminal' | 'tasks' | 'activity' | 'automations'
-  previousViewBeforeActivity: 'terminal' | 'settings' | 'tasks' | 'automations'
-  previousViewBeforeAutomations: 'terminal' | 'settings' | 'tasks' | 'activity'
+  activeView: 'terminal' | 'settings' | 'tasks' | 'activity' | 'automations' | 'space'
+  previousViewBeforeTasks: 'terminal' | 'settings' | 'activity' | 'automations' | 'space'
+  previousViewBeforeSettings: 'terminal' | 'tasks' | 'activity' | 'automations' | 'space'
+  previousViewBeforeActivity: 'terminal' | 'settings' | 'tasks' | 'automations' | 'space'
+  previousViewBeforeAutomations: 'terminal' | 'settings' | 'tasks' | 'activity' | 'space'
+  previousViewBeforeSpace: 'terminal' | 'settings' | 'tasks' | 'activity' | 'automations'
   setActiveView: (view: UISlice['activeView']) => void
   taskPageData: {
     preselectedRepoId?: string
@@ -238,6 +239,8 @@ export type UISlice = {
   setSelectedAutomationId: (id: string | null) => void
   openAutomationsPage: () => void
   closeAutomationsPage: () => void
+  openSpacePage: () => void
+  closeSpacePage: () => void
   setNewWorkspaceDraft: (draft: NonNullable<UISlice['newWorkspaceDraft']>) => void
   clearNewWorkspaceDraft: () => void
   openSettingsPage: () => void
@@ -423,6 +426,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   previousViewBeforeSettings: 'terminal',
   previousViewBeforeActivity: 'terminal',
   previousViewBeforeAutomations: 'terminal',
+  previousViewBeforeSpace: 'terminal',
   setActiveView: (view) => set({ activeView: view }),
   taskPageData: {},
   taskResumeState: undefined,
@@ -536,6 +540,16 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
     set((state) => ({
       activeView: state.previousViewBeforeAutomations
     })),
+  openSpacePage: () =>
+    set((state) => ({
+      activeView: 'space',
+      previousViewBeforeSpace:
+        state.activeView === 'space' ? state.previousViewBeforeSpace : state.activeView
+    })),
+  closeSpacePage: () =>
+    set((state) => ({
+      activeView: state.previousViewBeforeSpace
+    })),
   setNewWorkspaceDraft: (draft) => set({ newWorkspaceDraft: draft }),
   clearNewWorkspaceDraft: () => set({ newWorkspaceDraft: null }),
   openSettingsPage: () =>
diff --git a/src/renderer/src/store/slices/workspace-space.ts b/src/renderer/src/store/slices/workspace-space.ts
new file mode 100644
index 00000000000..2d1bc99c000
--- /dev/null
+++ b/src/renderer/src/store/slices/workspace-space.ts
@@ -0,0 +1,96 @@
+import type { StateCreator } from 'zustand'
+import type { WorkspaceSpaceAnalysis } from '../../../../shared/workspace-space-types'
+import type { AppState } from '../types'
+
+let inFlightScan: Promise<WorkspaceSpaceAnalysis> | null = null
+
+export type WorkspaceSpaceSlice = {
+  workspaceSpaceAnalysis: WorkspaceSpaceAnalysis | null
+  workspaceSpaceScanError: string | null
+  workspaceSpaceScanning: boolean
+  refreshWorkspaceSpace: () => Promise<WorkspaceSpaceAnalysis>
+  removeWorkspaceSpaceWorktrees: (worktreeIds: readonly string[]) => void
+}
+
+function removeDeletedWorktreesFromAnalysis(
+  analysis: WorkspaceSpaceAnalysis,
+  deletedWorktreeIds: readonly string[]
+): WorkspaceSpaceAnalysis {
+  const deletedSet = new Set(deletedWorktreeIds)
+  const worktrees = analysis.worktrees.filter((worktree) => !deletedSet.has(worktree.worktreeId))
+  const rowsByRepoId = new Map<string, typeof worktrees>()
+  for (const worktree of worktrees) {
+    const repoRows = rowsByRepoId.get(worktree.repoId) ?? []
+    repoRows.push(worktree)
+    rowsByRepoId.set(worktree.repoId, repoRows)
+  }
+  const repos = analysis.repos.map((repo) => {
+    const repoRows = rowsByRepoId.get(repo.repoId) ?? []
+    return {
+      ...repo,
+      worktreeCount: repoRows.length,
+      scannedWorktreeCount: repoRows.filter((row) => row.status === 'ok').length,
+      unavailableWorktreeCount: repoRows.filter((row) => row.status !== 'ok').length,
+      totalSizeBytes: repoRows.reduce((sum, row) => sum + row.sizeBytes, 0),
+      reclaimableBytes: repoRows.reduce((sum, row) => sum + row.reclaimableBytes, 0)
+    }
+  })
+
+  return {
+    ...analysis,
+    totalSizeBytes: worktrees.reduce((sum, row) => sum + row.sizeBytes, 0),
+    reclaimableBytes: worktrees.reduce((sum, row) => sum + row.reclaimableBytes, 0),
+    worktreeCount: worktrees.length,
+    scannedWorktreeCount: worktrees.filter((row) => row.status === 'ok').length,
+    unavailableWorktreeCount:
+      worktrees.filter((row) => row.status !== 'ok').length +
+      repos.filter((repo) => repo.error !== null).length,
+    repos,
+    worktrees
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export const createWorkspaceSpaceSlice: StateCreator<AppState, [], [], WorkspaceSpaceSlice> = (
+  set
+) => ({
+  workspaceSpaceAnalysis: null,
+  workspaceSpaceScanError: null,
+  workspaceSpaceScanning: false,
+  refreshWorkspaceSpace: async () => {
+    if (inFlightScan) {
+      return inFlightScan
+    }
+    set({ workspaceSpaceScanning: true, workspaceSpaceScanError: null })
+    // Why: the compact Resource Manager card and the full Space page share
+    // one manual scan result; duplicate button presses should join the same IO.
+    inFlightScan = window.api.workspaceSpace
+      .analyze()
+      .then((analysis) => {
+        set({ workspaceSpaceAnalysis: analysis, workspaceSpaceScanning: false })
+        return analysis
+      })
+      .catch((error: unknown) => {
+        set({ workspaceSpaceScanError: errorMessage(error), workspaceSpaceScanning: false })
+        throw error
+      })
+      .finally(() => {
+        inFlightScan = null
+      })
+    return inFlightScan
+  },
+  removeWorkspaceSpaceWorktrees: (worktreeIds) =>
+    set((state) =>
+      state.workspaceSpaceAnalysis
+        ? {
+            workspaceSpaceAnalysis: removeDeletedWorktreesFromAnalysis(
+              state.workspaceSpaceAnalysis,
+              worktreeIds
+            )
+          }
+        : state
+    )
+})
diff --git a/src/renderer/src/store/types.ts b/src/renderer/src/store/types.ts
index dce995c3fd9..4c8f148985f 100644
--- a/src/renderer/src/store/types.ts
+++ b/src/renderer/src/store/types.ts
@@ -11,6 +11,7 @@ import type { LinearSlice } from './slices/linear'
 import type { EditorSlice } from './slices/editor'
 import type { StatsSlice } from './slices/stats'
 import type { MemorySlice } from './slices/memory'
+import type { WorkspaceSpaceSlice } from './slices/workspace-space'
 import type { ClaudeUsageSlice } from './slices/claude-usage'
 import type { CodexUsageSlice } from './slices/codex-usage'
 import type { BrowserSlice } from './slices/browser'
@@ -35,6 +36,7 @@ export type AppState = RepoSlice &
   EditorSlice &
   StatsSlice &
   MemorySlice &
+  WorkspaceSpaceSlice &
   ClaudeUsageSlice &
   CodexUsageSlice &
   BrowserSlice &
diff --git a/src/shared/computer-use-permissions-types.ts b/src/shared/computer-use-permissions-types.ts
index 761dba95d42..d1f4c488fb0 100644
--- a/src/shared/computer-use-permissions-types.ts
+++ b/src/shared/computer-use-permissions-types.ts
@@ -9,6 +9,8 @@ export type ComputerUsePermissionState = {
 
 export type ComputerUsePermissionStatusResult = {
   platform: NodeJS.Platform
+  helperAppPath: string | null
+  helperUnavailableReason: string | null
   permissions: ComputerUsePermissionState[]
 }
 
diff --git a/src/shared/workspace-space-types.ts b/src/shared/workspace-space-types.ts
new file mode 100644
index 00000000000..9913ec87200
--- /dev/null
+++ b/src/shared/workspace-space-types.ts
@@ -0,0 +1,63 @@
+export type WorkspaceSpaceScanStatus =
+  | 'ok'
+  | 'missing'
+  | 'permission-denied'
+  | 'unavailable'
+  | 'error'
+
+export type WorkspaceSpaceItemKind = 'directory' | 'file' | 'symlink' | 'other'
+
+export type WorkspaceSpaceItem = {
+  name: string
+  path: string
+  kind: WorkspaceSpaceItemKind
+  sizeBytes: number
+}
+
+export type WorkspaceSpaceWorktree = {
+  worktreeId: string
+  repoId: string
+  repoDisplayName: string
+  repoPath: string
+  displayName: string
+  path: string
+  branch: string
+  isMainWorktree: boolean
+  isRemote: boolean
+  isSparse: boolean
+  canDelete: boolean
+  lastActivityAt: number
+  status: WorkspaceSpaceScanStatus
+  error: string | null
+  scannedAt: number
+  sizeBytes: number
+  reclaimableBytes: number
+  skippedEntryCount: number
+  topLevelItems: WorkspaceSpaceItem[]
+  omittedTopLevelItemCount: number
+  omittedTopLevelSizeBytes: number
+}
+
+export type WorkspaceSpaceRepoSummary = {
+  repoId: string
+  displayName: string
+  path: string
+  isRemote: boolean
+  worktreeCount: number
+  scannedWorktreeCount: number
+  unavailableWorktreeCount: number
+  totalSizeBytes: number
+  reclaimableBytes: number
+  error: string | null
+}
+
+export type WorkspaceSpaceAnalysis = {
+  scannedAt: number
+  totalSizeBytes: number
+  reclaimableBytes: number
+  worktreeCount: number
+  scannedWorktreeCount: number
+  unavailableWorktreeCount: number
+  repos: WorkspaceSpaceRepoSummary[]
+  worktrees: WorkspaceSpaceWorktree[]
+}

From 8a0b9b6bc56841185c695db9996569737d5d9da6 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 15 May 2026 00:45:31 +0000
Subject: [PATCH 05/82] release: v1.4.2-rc.3

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

diff --git a/package.json b/package.json
index 262e804eaa3..75544a91102 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.2-rc.2",
+  "version": "1.4.2-rc.3",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From 2d9cf720845e6e94829d0feebec1f87f1488e918 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 14 May 2026 19:02:37 -0700
Subject: [PATCH 06/82] fix: verify macOS entitlements before release

---
 .github/workflows/pr.yml                     |   3 +
 .github/workflows/release-cut.yml            |   6 +
 config/scripts/verify-macos-entitlements.mjs | 136 +++++++++++++++++++
 package.json                                 |   1 +
 resources/build/entitlements.mac.plist       |   2 -
 5 files changed, 146 insertions(+), 2 deletions(-)
 create mode 100644 config/scripts/verify-macos-entitlements.mjs

diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index b70a92d35dc..22b332c1a21 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -71,6 +71,9 @@ jobs:
       - name: Check feature wall asset budget
         run: pnpm check:feature-wall-assets
 
+      - name: Verify macOS entitlements
+        run: pnpm verify:macos-entitlements
+
       - name: Typecheck
         run: pnpm typecheck
 
diff --git a/.github/workflows/release-cut.yml b/.github/workflows/release-cut.yml
index 0f2dc8ba6c0..5128f74d079 100644
--- a/.github/workflows/release-cut.yml
+++ b/.github/workflows/release-cut.yml
@@ -634,6 +634,12 @@ jobs:
           APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
 
+      # Why: `plutil -lint` accepts duplicate plist keys, but `codesign`
+      # rejects duplicate entitlements after the expensive app build.
+      - name: Verify macOS entitlements
+        if: matrix.platform == 'mac'
+        run: pnpm verify:macos-entitlements
+
       # Why: telemetry's transport gate (`src/main/telemetry/client.ts:IS_OFFICIAL_BUILD`)
       # requires the build identity to be the literal string `stable` or `rc`,
       # substituted by electron-vite's `define` block at build time. Derive
diff --git a/config/scripts/verify-macos-entitlements.mjs b/config/scripts/verify-macos-entitlements.mjs
new file mode 100644
index 00000000000..20bb7230510
--- /dev/null
+++ b/config/scripts/verify-macos-entitlements.mjs
@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const repoRoot = resolve(__dirname, '../..')
+
+const defaultPlists = [
+  'resources/build/entitlements.mac.plist',
+  'resources/build/entitlements.computer-use.mac.plist'
+]
+
+const plistPaths = process.argv.slice(2)
+const pathsToCheck = plistPaths.length > 0 ? plistPaths : defaultPlists
+
+let failed = false
+
+for (const plistPath of pathsToCheck) {
+  const absolutePath = resolve(repoRoot, plistPath)
+  const xml = readFileSync(absolutePath, 'utf8')
+  const problems = findDuplicateDictKeys(xml)
+
+  if (problems.length === 0) {
+    console.log(`${plistPath}: OK`)
+    continue
+  }
+
+  failed = true
+  console.error(`${plistPath}: duplicate plist dict keys found`)
+  for (const problem of problems) {
+    console.error(
+      `- ${problem.key} first appears on line ${problem.firstLine}, duplicated on line ${problem.duplicateLine}`
+    )
+  }
+}
+
+if (failed) {
+  process.exit(1)
+}
+
+function findDuplicateDictKeys(xml) {
+  const problems = []
+  const lineStarts = buildLineStarts(xml)
+  const dictStack = []
+  // Why: `plutil -lint` accepts duplicate keys, but `codesign` rejects
+  // duplicate entitlements during release signing.
+  const tokenPattern =
+    /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<key\b[^>]*>([\s\S]*?)<\/key>|<(\/?)dict\b[^>]*>/g
+
+  for (const match of xml.matchAll(tokenPattern)) {
+    if (match[0].startsWith('<!--') || match[0].startsWith('<![CDATA[')) {
+      continue
+    }
+
+    if (match[0].startsWith('<key')) {
+      const currentDict = dictStack.at(-1)
+      if (!currentDict) {
+        continue
+      }
+
+      const key = decodeXmlEntities(match[1].trim())
+      const duplicateLine = lineNumberForIndex(lineStarts, match.index)
+      const firstLine = currentDict.keys.get(key)
+
+      if (firstLine) {
+        problems.push({ key, firstLine, duplicateLine })
+      } else {
+        currentDict.keys.set(key, duplicateLine)
+      }
+      continue
+    }
+
+    if (match[2] === '/') {
+      dictStack.pop()
+    } else {
+      dictStack.push({ keys: new Map() })
+    }
+  }
+
+  return problems
+}
+
+function buildLineStarts(text) {
+  const starts = [0]
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === '\n') {
+      starts.push(index + 1)
+    }
+  }
+  return starts
+}
+
+function lineNumberForIndex(lineStarts, targetIndex) {
+  let low = 0
+  let high = lineStarts.length - 1
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2)
+    if (lineStarts[mid] <= targetIndex) {
+      low = mid + 1
+    } else {
+      high = mid - 1
+    }
+  }
+
+  return high + 1
+}
+
+function decodeXmlEntities(value) {
+  return value.replace(/&(#x?[0-9a-fA-F]+|amp|lt|gt|apos|quot);/g, (entity, body) => {
+    if (body === 'amp') {
+      return '&'
+    }
+    if (body === 'lt') {
+      return '<'
+    }
+    if (body === 'gt') {
+      return '>'
+    }
+    if (body === 'apos') {
+      return "'"
+    }
+    if (body === 'quot') {
+      return '"'
+    }
+    if (body.startsWith('#x')) {
+      return String.fromCodePoint(Number.parseInt(body.slice(2), 16))
+    }
+    if (body.startsWith('#')) {
+      return String.fromCodePoint(Number.parseInt(body.slice(1), 10))
+    }
+    return entity
+  })
+}
diff --git a/package.json b/package.json
index 75544a91102..5cf6015d70a 100644
--- a/package.json
+++ b/package.json
@@ -15,6 +15,7 @@
     "prepare": "husky",
     "test": "vitest run --config config/vitest.config.ts",
     "check:feature-wall-assets": "node config/scripts/check-feature-wall-assets.mjs",
+    "verify:macos-entitlements": "node config/scripts/verify-macos-entitlements.mjs",
     "vendor:feature-wall-assets": "node config/scripts/vendor-feature-wall-assets.mjs",
     "tc:node": "tsgo --noEmit -p config/tsconfig.node.json",
     "tc:cli": "tsgo --noEmit -p config/tsconfig.tc.cli.json",
diff --git a/resources/build/entitlements.mac.plist b/resources/build/entitlements.mac.plist
index 0f1813fa81a..f43bcc2705d 100644
--- a/resources/build/entitlements.mac.plist
+++ b/resources/build/entitlements.mac.plist
@@ -20,7 +20,5 @@
 	<true/>
 	<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
 	<true/>
-	<key>com.apple.security.device.audio-input</key>
-	<true/>
 </dict>
 </plist>

From 4ad559e2b94ac31cead79b5c9045edbe44b41780 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 15 May 2026 02:03:17 +0000
Subject: [PATCH 07/82] release: v1.4.2-rc.4

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

diff --git a/package.json b/package.json
index 5cf6015d70a..974f99032fb 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.2-rc.3",
+  "version": "1.4.2-rc.4",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From a7d2a091882165e8fbaeef4738af4d70f1a83753 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Thu, 14 May 2026 19:12:10 -0700
Subject: [PATCH 08/82] docs: clarify mobile command directory (#1883)

---
 mobile/README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/mobile/README.md b/mobile/README.md
index ff03e6b91e1..576e1efe9be 100644
--- a/mobile/README.md
+++ b/mobile/README.md
@@ -7,6 +7,8 @@ Local development uses two processes:
 - Orca desktop/Electron from the repo root. This hosts the mobile WebSocket RPC server on port `6768`.
 - Expo Metro from `mobile/`. This serves the React Native app on port `8081`.
 
+Unless a command says otherwise, run mobile app commands from the `mobile/` directory.
+
 ## Prerequisites
 
 - Node.js 24+

From 322eab0f83b519199575547cf289f172e0d294c5 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 14 May 2026 19:36:57 -0700
Subject: [PATCH 09/82] fix: expect debian release artifact name

---
 config/scripts/verify-release-required-assets.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/config/scripts/verify-release-required-assets.mjs b/config/scripts/verify-release-required-assets.mjs
index 9d8fcf15ec0..12dbdb53b34 100644
--- a/config/scripts/verify-release-required-assets.mjs
+++ b/config/scripts/verify-release-required-assets.mjs
@@ -11,7 +11,7 @@ export function getRequiredReleaseAssetNames(tag) {
     'latest-mac.yml',
     'latest.yml',
     'orca-linux.AppImage',
-    `orca_${version}_amd64.deb`,
+    `orca-ide_${version}_amd64.deb`,
     'orca-windows-setup.exe',
     'orca-windows-setup.exe.blockmap',
     `Orca-${version}-mac.zip`,

From 31ab1560a7376e6e22ab2b8ff09f260f2915840a Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Thu, 14 May 2026 22:42:11 -0400
Subject: [PATCH 10/82] Fix WSL gh fallback for task lists (#1879)

---
 src/main/git/runner-wsl-gh-fallback.test.ts | 320 ++++++++++++++++++++
 src/main/git/runner.ts                      | 101 +++++-
 src/main/github/client.ts                   |  28 +-
 3 files changed, 428 insertions(+), 21 deletions(-)
 create mode 100644 src/main/git/runner-wsl-gh-fallback.test.ts

diff --git a/src/main/git/runner-wsl-gh-fallback.test.ts b/src/main/git/runner-wsl-gh-fallback.test.ts
new file mode 100644
index 00000000000..c1be9866094
--- /dev/null
+++ b/src/main/git/runner-wsl-gh-fallback.test.ts
@@ -0,0 +1,320 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { execFileMock, execFileSyncMock, spawnMock } = vi.hoisted(() => ({
+  execFileMock: vi.fn(),
+  execFileSyncMock: vi.fn(),
+  spawnMock: vi.fn()
+}))
+
+vi.mock('child_process', () => ({
+  execFile: execFileMock,
+  execFileSync: execFileSyncMock,
+  spawn: spawnMock
+}))
+
+import { ghExecFileAsync, glabExecFileAsync } from './runner'
+
+describe('ghExecFileAsync WSL fallback', () => {
+  const originalPlatform = process.platform
+
+  beforeEach(() => {
+    execFileMock.mockReset()
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'win32'
+    })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: originalPlatform
+    })
+  })
+
+  it('falls back to host gh for explicit-repo WSL calls when gh is missing in the distro', async () => {
+    execFileMock.mockImplementation((binary, _args, options, callback) => {
+      if (typeof options === 'function') {
+        callback = options
+      }
+      if (binary === 'wsl.exe') {
+        callback(
+          Object.assign(new Error('Command failed: wsl.exe'), {
+            stdout: '',
+            stderr: 'bash: line 1: gh: command not found\n'
+          })
+        )
+        return
+      }
+      callback(null, { stdout: '[]', stderr: '' })
+    })
+
+    await expect(
+      ghExecFileAsync(['issue', 'list', '--repo', 'stablyhq/noqa', '--json', 'number,title'], {
+        cwd: String.raw`\\wsl.localhost\Ubuntu\home\jinwoo\stably\noqa`
+      })
+    ).resolves.toEqual({ stdout: '[]', stderr: '' })
+
+    expect(execFileMock).toHaveBeenNthCalledWith(
+      1,
+      'wsl.exe',
+      [
+        '-d',
+        'Ubuntu',
+        '--',
+        'bash',
+        '-c',
+        "cd '/home/jinwoo/stably/noqa' && gh 'issue' 'list' '--repo' 'stablyhq/noqa' '--json' 'number,title'"
+      ],
+      expect.objectContaining({ cwd: undefined }),
+      expect.any(Function)
+    )
+    expect(execFileMock).toHaveBeenNthCalledWith(
+      2,
+      'gh',
+      ['issue', 'list', '--repo', 'stablyhq/noqa', '--json', 'number,title'],
+      expect.objectContaining({ cwd: undefined }),
+      expect.any(Function)
+    )
+  })
+
+  it('does not fall back for repo-context gh calls without explicit repo context', async () => {
+    execFileMock.mockImplementation((_binary, _args, _options, callback) => {
+      callback(
+        Object.assign(new Error('Command failed: wsl.exe'), {
+          stdout: '',
+          stderr: 'bash: line 1: gh: command not found\n'
+        })
+      )
+    })
+
+    await expect(
+      ghExecFileAsync(['issue', 'list'], {
+        cwd: String.raw`\\wsl.localhost\Ubuntu\home\jinwoo\stably\noqa`
+      })
+    ).rejects.toThrow('Command failed: wsl.exe')
+
+    expect(execFileMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('falls back for short-form explicit repo flags used by gh', async () => {
+    execFileMock.mockImplementation((binary, _args, options, callback) => {
+      if (typeof options === 'function') {
+        callback = options
+      }
+      if (binary === 'wsl.exe') {
+        callback(
+          Object.assign(new Error('Command failed: wsl.exe'), {
+            stdout: '',
+            stderr: 'bash: line 1: gh: command not found\n'
+          })
+        )
+        return
+      }
+      callback(null, { stdout: '[]', stderr: '' })
+    })
+
+    await expect(
+      ghExecFileAsync(['issue', 'list', '-R', 'stablyhq/noqa'], {
+        cwd: String.raw`\\wsl.localhost\Ubuntu\home\jinwoo\stably\noqa`
+      })
+    ).resolves.toEqual({ stdout: '[]', stderr: '' })
+
+    expect(execFileMock).toHaveBeenNthCalledWith(
+      2,
+      'gh',
+      ['issue', 'list', '-R', 'stablyhq/noqa'],
+      expect.objectContaining({ cwd: undefined }),
+      expect.any(Function)
+    )
+  })
+
+  it('falls back for compact short-form repo flags used by gh', async () => {
+    execFileMock.mockImplementation((binary, _args, options, callback) => {
+      if (typeof options === 'function') {
+        callback = options
+      }
+      if (binary === 'wsl.exe') {
+        callback(
+          Object.assign(new Error('Command failed: wsl.exe'), {
+            stdout: '',
+            stderr: 'bash: line 1: gh: command not found\n'
+          })
+        )
+        return
+      }
+      callback(null, { stdout: '[]', stderr: '' })
+    })
+
+    await expect(
+      ghExecFileAsync(['issue', 'list', '-Rstablyhq/noqa'], {
+        cwd: String.raw`\\wsl.localhost\Ubuntu\home\jinwoo\stably\noqa`
+      })
+    ).resolves.toEqual({ stdout: '[]', stderr: '' })
+
+    expect(execFileMock).toHaveBeenNthCalledWith(
+      2,
+      'gh',
+      ['issue', 'list', '-Rstablyhq/noqa'],
+      expect.objectContaining({ cwd: undefined }),
+      expect.any(Function)
+    )
+  })
+
+  it('does not fall back for gh api calls that depend on repo-context placeholders', async () => {
+    execFileMock.mockImplementation((_binary, _args, _options, callback) => {
+      callback(
+        Object.assign(new Error('Command failed: wsl.exe'), {
+          stdout: '',
+          stderr: 'bash: line 1: gh: command not found\n'
+        })
+      )
+    })
+
+    await expect(
+      ghExecFileAsync(['api', 'repos/stablyhq/noqa/branches/{branch}'], {
+        cwd: String.raw`\\wsl.localhost\Ubuntu\home\jinwoo\stably\noqa`
+      })
+    ).rejects.toThrow('Command failed: wsl.exe')
+
+    expect(execFileMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries idempotent gh GraphQL query transient failures', async () => {
+    execFileMock
+      .mockImplementationOnce((_binary, _args, _options, callback) => {
+        callback(
+          Object.assign(new Error('HTTP 502 Bad Gateway'), {
+            stdout: '',
+            stderr: 'HTTP 502 Bad Gateway'
+          })
+        )
+      })
+      .mockImplementationOnce((_binary, _args, _options, callback) => {
+        callback(null, { stdout: '{"data":{}}', stderr: '' })
+      })
+
+    await expect(
+      ghExecFileAsync(['api', 'graphql', '-f', 'query=query { viewer { login } }'])
+    ).resolves.toEqual({ stdout: '{"data":{}}', stderr: '' })
+
+    expect(execFileMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not retry non-idempotent gh API transient failures', async () => {
+    execFileMock.mockImplementation((_binary, _args, _options, callback) => {
+      callback(
+        Object.assign(new Error('HTTP 502 Bad Gateway'), {
+          stdout: '',
+          stderr: 'HTTP 502 Bad Gateway'
+        })
+      )
+    })
+
+    await expect(
+      ghExecFileAsync(['api', '-X', 'POST', 'repos/stablyai/orca/issues'])
+    ).rejects.toThrow('HTTP 502 Bad Gateway')
+
+    expect(execFileMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not retry gh GraphQL mutation transient failures', async () => {
+    execFileMock.mockImplementation((_binary, _args, _options, callback) => {
+      callback(
+        Object.assign(new Error('HTTP 502 Bad Gateway'), {
+          stdout: '',
+          stderr: 'HTTP 502 Bad Gateway'
+        })
+      )
+    })
+
+    await expect(
+      ghExecFileAsync([
+        'api',
+        'graphql',
+        '-f',
+        'query=mutation { addStar(input: {}) { starrable { id } } }'
+      ])
+    ).rejects.toThrow('HTTP 502 Bad Gateway')
+
+    expect(execFileMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not retry high-level gh edit transient failures', async () => {
+    execFileMock.mockImplementation((_binary, _args, _options, callback) => {
+      callback(
+        Object.assign(new Error('HTTP 502 Bad Gateway'), {
+          stdout: '',
+          stderr: 'HTTP 502 Bad Gateway'
+        })
+      )
+    })
+
+    await expect(
+      ghExecFileAsync(['issue', 'edit', '5', '--repo', 'stablyai/orca'])
+    ).rejects.toThrow('HTTP 502 Bad Gateway')
+
+    expect(execFileMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not retry non-idempotent glab transient failures', async () => {
+    execFileMock.mockImplementation((_binary, _args, _options, callback) => {
+      callback(
+        Object.assign(new Error('HTTP 502 Bad Gateway'), {
+          stdout: '',
+          stderr: 'HTTP 502 Bad Gateway'
+        })
+      )
+    })
+
+    await expect(
+      glabExecFileAsync(['api', '-X', 'POST', 'projects/stablyai%2Forca/issues/5/notes'], {
+        cwd: String.raw`C:\repo`
+      })
+    ).rejects.toThrow('HTTP 502 Bad Gateway')
+
+    expect(execFileMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not retry high-level glab update transient failures', async () => {
+    execFileMock.mockImplementation((_binary, _args, _options, callback) => {
+      callback(
+        Object.assign(new Error('HTTP 502 Bad Gateway'), {
+          stdout: '',
+          stderr: 'HTTP 502 Bad Gateway'
+        })
+      )
+    })
+
+    await expect(
+      glabExecFileAsync(['issue', 'update', '5', '-R', 'stablyai/orca'], {
+        cwd: String.raw`C:\repo`
+      })
+    ).rejects.toThrow('HTTP 502 Bad Gateway')
+
+    expect(execFileMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('still retries idempotent glab transient failures', async () => {
+    execFileMock
+      .mockImplementationOnce((_binary, _args, _options, callback) => {
+        callback(
+          Object.assign(new Error('HTTP 502 Bad Gateway'), {
+            stdout: '',
+            stderr: 'HTTP 502 Bad Gateway'
+          })
+        )
+      })
+      .mockImplementationOnce((_binary, _args, _options, callback) => {
+        callback(null, { stdout: '[]', stderr: '' })
+      })
+
+    await expect(
+      glabExecFileAsync(['api', 'projects/stablyai%2Forca/issues'], {
+        cwd: String.raw`C:\repo`
+      })
+    ).resolves.toEqual({ stdout: '[]', stderr: '' })
+
+    expect(execFileMock).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/src/main/git/runner.ts b/src/main/git/runner.ts
index c589b7b20a1..dffc475ec48 100644
--- a/src/main/git/runner.ts
+++ b/src/main/git/runner.ts
@@ -55,6 +55,72 @@ function translateArgsForWsl(args: string[]): string[] {
   })
 }
 
+function hasExplicitRepoArg(args: string[]): boolean {
+  for (let i = 0; i < args.length; i++) {
+    if (
+      (args[i] === '--repo' || args[i] === '-R') &&
+      typeof args[i + 1] === 'string' &&
+      args[i + 1].trim()
+    ) {
+      return true
+    }
+    if (args[i].startsWith('--repo=') || args[i].startsWith('-R=')) {
+      return args[i].slice(args[i].indexOf('=') + 1).trim().length > 0
+    }
+    if (args[i].startsWith('-R') && args[i].length > 2) {
+      return args[i].slice(2).trim().length > 0
+    }
+  }
+  return false
+}
+
+function argsUseGhApiPlaceholders(args: string[]): boolean {
+  return args.some(
+    (arg) => arg.includes('{owner}') || arg.includes('{repo}') || arg.includes('{branch}')
+  )
+}
+
+function canRunGitHubCliWithoutRepoCwd(args: string[]): boolean {
+  if (hasExplicitRepoArg(args)) {
+    return true
+  }
+  if (args[0] === 'api') {
+    return !argsUseGhApiPlaceholders(args)
+  }
+  return args[0] === 'auth'
+}
+
+function isMissingCommandInWsl(stderr: string, command: string): boolean {
+  const s = stderr.toLowerCase()
+  const c = command.toLowerCase()
+  return s.includes(`${c}: command not found`) || s.includes(`${c}: not found`)
+}
+
+function canFallBackToHostGitHubCli(
+  command: 'gh',
+  args: string[],
+  resolved: ResolvedCommand,
+  stderr: string
+): boolean {
+  return (
+    process.platform === 'win32' &&
+    resolved.wsl !== null &&
+    isMissingCommandInWsl(stderr, command) &&
+    canRunGitHubCliWithoutRepoCwd(args)
+  )
+}
+
+function resolveHostGitHubCli(command: 'gh', args: string[]): ResolvedCommand {
+  return {
+    binary: command,
+    args,
+    // Why: host gh cannot use a WSL UNC cwd reliably. We only fall back
+    // for commands with explicit repo/API context, so no repo cwd is required.
+    cwd: undefined,
+    wsl: null
+  }
+}
+
 /**
  * Given a command, its arguments, and a working directory, resolve whether
  * the invocation should be routed through wsl.exe.
@@ -227,6 +293,7 @@ const NON_IDEMPOTENT_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE'])
 const NON_IDEMPOTENT_GH_VERBS = new Set([
   'create',
   'edit',
+  'update',
   'delete',
   'close',
   'reopen',
@@ -245,6 +312,8 @@ const NON_IDEMPOTENT_GH_VERBS = new Set([
 function argsLookIdempotent(args: string[]): boolean {
   let explicitMethodSeen = false
   let hasApiBodyField = false
+  let hasGraphQlQuery = false
+  const isGraphQlApi = args[0] === 'api' && args[1] === 'graphql'
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '-X' || a === '--method') {
@@ -278,6 +347,7 @@ function argsLookIdempotent(args: string[]): boolean {
     // `gh api graphql -f query=mutation(...){ ... }` — detect mutation queries
     // so writes via the GraphQL endpoint also fail fast on transient errors.
     if (a.startsWith('query=')) {
+      hasGraphQlQuery = true
       const trimmed = a.slice('query='.length).trimStart().toLowerCase()
       if (trimmed.startsWith('mutation')) {
         return false
@@ -286,8 +356,14 @@ function argsLookIdempotent(args: string[]): boolean {
   }
   // `gh api ... -f foo=bar` with no explicit method: gh switches to POST.
   // Treat as non-idempotent so a transient 5xx after the server applied
-  // the write doesn't retry and duplicate it.
-  if (args[0] === 'api' && hasApiBodyField && !explicitMethodSeen) {
+  // the write doesn't retry and duplicate it. GraphQL reads are the exception:
+  // gh sends them as POST body fields, but a query operation is idempotent.
+  if (
+    args[0] === 'api' &&
+    hasApiBodyField &&
+    !explicitMethodSeen &&
+    !(isGraphQlApi && hasGraphQlQuery)
+  ) {
     return false
   }
   // `gh issue close`, `gh pr edit`, `gh pr merge`, etc. The first arg is the
@@ -423,8 +499,9 @@ export async function ghExecFileAsync(
   args: string[],
   options: GhExecOptions = {}
 ): Promise<{ stdout: string; stderr: string }> {
-  const resolved = resolveCommand('gh', args, options.cwd, options.wslDistro)
+  let resolved = resolveCommand('gh', args, options.cwd, options.wslDistro)
   let lastError: unknown
+  let attemptedHostFallback = false
   for (let attempt = 0; attempt <= GH_RETRY_DELAYS_MS.length; attempt++) {
     try {
       const { stdout, stderr } = await execFileAsync(resolved.binary, resolved.args, {
@@ -438,6 +515,12 @@ export async function ghExecFileAsync(
     } catch (err) {
       lastError = err
       const { stderr } = extractExecError(err)
+      if (!attemptedHostFallback && canFallBackToHostGitHubCli('gh', args, resolved, stderr)) {
+        resolved = resolveHostGitHubCli('gh', args)
+        attemptedHostFallback = true
+        attempt = -1
+        continue
+      }
       const isLastAttempt = attempt >= GH_RETRY_DELAYS_MS.length
       // Why: only retry idempotent calls. A 5xx/socket reset can arrive
       // after the server already applied a POST/PATCH/PUT/DELETE; retrying
@@ -479,7 +562,11 @@ export async function ghExecFileAsync(
 // helpers since HTTP-status- and TCP-error-based classification is
 // provider-agnostic.
 
-type GlabExecOptions = Omit<GitExecOptions, 'cwd'> & { cwd?: string; wslDistro?: string }
+type GlabExecOptions = Omit<GitExecOptions, 'cwd'> & {
+  cwd?: string
+  wslDistro?: string
+  idempotent?: boolean
+}
 
 /**
  * Async glab CLI execution. Drop-in replacement for
@@ -507,7 +594,11 @@ export async function glabExecFileAsync(
       lastError = err
       const { stderr } = extractExecError(err)
       const isLastAttempt = attempt >= GH_RETRY_DELAYS_MS.length
-      if (!isLastAttempt && isTransientGhError(stderr)) {
+      // Why: mirror gh's write-safety gate. A transient error after GitLab
+      // applies a POST/PATCH/PUT/DELETE must not create duplicate comments,
+      // issues, or merge actions through an automatic retry.
+      const idempotent = options.idempotent ?? argsLookIdempotent(args)
+      if (idempotent && !isLastAttempt && isTransientGhError(stderr)) {
         const retryAfterMs = parseRetryAfterMs(stderr)
         const delayMs =
           retryAfterMs !== null
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index cde6e71f3be..a34bd6ff012 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -1211,13 +1211,10 @@ export async function getPRComments(
       // Each source is parsed independently; failed sources contribute zero
       // comments instead of aborting the entire fetch.
       const [issueResult, threadsResult, reviewsResult] = await Promise.allSettled([
-        execFileAsync(
-          'gh',
-          ['api', ...cacheArgs, `${base}/issues/${prNumber}/comments?per_page=100`],
-          { cwd: repoPath, encoding: 'utf-8' }
-        ),
-        execFileAsync(
-          'gh',
+        ghExecFileAsync(['api', ...cacheArgs, `${base}/issues/${prNumber}/comments?per_page=100`], {
+          cwd: repoPath
+        }),
+        ghExecFileAsync(
           [
             'api',
             'graphql',
@@ -1230,17 +1227,15 @@ export async function getPRComments(
             '-F',
             `pr=${prNumber}`
           ],
-          { cwd: repoPath, encoding: 'utf-8' }
+          { cwd: repoPath }
         ),
         // Why: review summaries (approve, request changes, general comments) live
         // under pulls/{n}/reviews, not under issue comments or review threads.
         // Without this, a reviewer who submits "LGTM" without inline threads
         // would have their comment silently dropped from the panel.
-        execFileAsync(
-          'gh',
-          ['api', ...cacheArgs, `${base}/pulls/${prNumber}/reviews?per_page=100`],
-          { cwd: repoPath, encoding: 'utf-8' }
-        )
+        ghExecFileAsync(['api', ...cacheArgs, `${base}/pulls/${prNumber}/reviews?per_page=100`], {
+          cwd: repoPath
+        })
       ])
 
       // Parse issue comments (REST)
@@ -1387,10 +1382,11 @@ export async function getPRComments(
     }
 
     // Fallback: non-GitHub remote — use gh pr view (only returns issue-level comments)
-    const { stdout } = await execFileAsync(
-      'gh',
+    const { stdout } = await ghExecFileAsync(
       ['pr', 'view', String(prNumber), '--json', 'comments'],
-      { cwd: repoPath, encoding: 'utf-8' }
+      {
+        cwd: repoPath
+      }
     )
     const data = JSON.parse(stdout) as {
       comments: {

From 36a92f502a772a75df8f8f7be3a991f2f201edcd Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Thu, 14 May 2026 22:42:31 -0400
Subject: [PATCH 11/82] Fix Claude auth refresh clobbering live sessions
 (#1882)

---
 src/main/claude-accounts/live-pty-gate.ts     |  4 +
 .../runtime-auth-service.test.ts              | 74 +++++++++++++++
 .../claude-accounts/runtime-auth-service.ts   | 93 ++++++++++++++++++-
 src/main/ipc/pty.test.ts                      | 24 +++++
 4 files changed, 192 insertions(+), 3 deletions(-)

diff --git a/src/main/claude-accounts/live-pty-gate.ts b/src/main/claude-accounts/live-pty-gate.ts
index b87756a35dc..dbeeb03d618 100644
--- a/src/main/claude-accounts/live-pty-gate.ts
+++ b/src/main/claude-accounts/live-pty-gate.ts
@@ -9,6 +9,10 @@ export function markClaudePtyExited(ptyId: string): void {
   liveClaudePtyIds.delete(ptyId)
 }
 
+export function hasLiveClaudePtys(): boolean {
+  return liveClaudePtyIds.size > 0
+}
+
 export function beginClaudeAuthSwitch(): void {
   if (switchInProgress) {
     throw new Error('A Claude account switch is already in progress.')
diff --git a/src/main/claude-accounts/runtime-auth-service.test.ts b/src/main/claude-accounts/runtime-auth-service.test.ts
index 7e76ddb69ab..1f77f2a77a5 100644
--- a/src/main/claude-accounts/runtime-auth-service.test.ts
+++ b/src/main/claude-accounts/runtime-auth-service.test.ts
@@ -995,6 +995,80 @@ describe('ClaudeRuntimeAuthService', () => {
     expect(readFileSync(runtimeCredentialsPath, 'utf-8')).toBe(originalCredentials)
   })
 
+  it('preserves rejected runtime refreshes while a Claude terminal is live on Windows', async () => {
+    setPlatform('win32')
+    const runtimeCredentialsPath = join(testState.fakeHomeDir, '.claude', '.credentials.json')
+    const originalCredentials = createClaudeCredentialsJson('user@example.com', 'original', 'org-a')
+    const refreshedCredentials = createClaudeCredentialsWithoutEmail('refreshed', 'org-a')
+    const managedAuthPath = createManagedClaudeAuth(
+      testState.userDataDir,
+      'account-1',
+      originalCredentials
+    )
+    const settings = createSettings({
+      claudeManagedAccounts: [
+        createClaudeAccount('account-1', managedAuthPath, { organizationUuid: 'org-a' })
+      ],
+      activeClaudeManagedAccountId: 'account-1'
+    })
+    const store = createStore(settings)
+
+    const { ClaudeRuntimeAuthService } = await import('./runtime-auth-service')
+    const { markClaudePtyExited, markClaudePtySpawned } = await import('./live-pty-gate')
+    const service = new ClaudeRuntimeAuthService(store as never)
+    await service.syncForCurrentSelection()
+
+    markClaudePtySpawned('live-claude-pty')
+    try {
+      writeFileSync(runtimeCredentialsPath, refreshedCredentials, 'utf-8')
+      await service.syncForCurrentSelection()
+
+      expect(readManagedCredentialsForTest('account-1', managedAuthPath)).toBe(refreshedCredentials)
+      expect(readFileSync(runtimeCredentialsPath, 'utf-8')).toBe(refreshedCredentials)
+    } finally {
+      markClaudePtyExited('live-claude-pty')
+    }
+
+    await service.syncForCurrentSelection()
+
+    expect(readFileSync(runtimeCredentialsPath, 'utf-8')).toBe(refreshedCredentials)
+  })
+
+  it('does not persist live runtime refreshes with conflicting organization identity', async () => {
+    setPlatform('win32')
+    const runtimeCredentialsPath = join(testState.fakeHomeDir, '.claude', '.credentials.json')
+    const originalCredentials = createClaudeCredentialsJson('user@example.com', 'original', 'org-a')
+    const conflictingCredentials = createClaudeCredentialsWithoutEmail('refreshed', 'org-b')
+    const managedAuthPath = createManagedClaudeAuth(
+      testState.userDataDir,
+      'account-1',
+      originalCredentials
+    )
+    const settings = createSettings({
+      claudeManagedAccounts: [
+        createClaudeAccount('account-1', managedAuthPath, { organizationUuid: 'org-a' })
+      ],
+      activeClaudeManagedAccountId: 'account-1'
+    })
+    const store = createStore(settings)
+
+    const { ClaudeRuntimeAuthService } = await import('./runtime-auth-service')
+    const { markClaudePtyExited, markClaudePtySpawned } = await import('./live-pty-gate')
+    const service = new ClaudeRuntimeAuthService(store as never)
+    await service.syncForCurrentSelection()
+
+    markClaudePtySpawned('live-claude-pty')
+    try {
+      writeFileSync(runtimeCredentialsPath, conflictingCredentials, 'utf-8')
+      await service.syncForCurrentSelection()
+
+      expect(readManagedCredentialsForTest('account-1', managedAuthPath)).toBe(originalCredentials)
+      expect(readFileSync(runtimeCredentialsPath, 'utf-8')).toBe(conflictingCredentials)
+    } finally {
+      markClaudePtyExited('live-claude-pty')
+    }
+  })
+
   it('rejects unverifiable refreshed runtime credentials', async () => {
     const runtimeCredentialsPath = join(testState.fakeHomeDir, '.claude', '.credentials.json')
     const originalCredentials = createClaudeCredentialsWithoutEmail('original')
diff --git a/src/main/claude-accounts/runtime-auth-service.ts b/src/main/claude-accounts/runtime-auth-service.ts
index 75f6f5fa838..349bff0710a 100644
--- a/src/main/claude-accounts/runtime-auth-service.ts
+++ b/src/main/claude-accounts/runtime-auth-service.ts
@@ -13,6 +13,7 @@ import {
   resolveOwnedClaudeManagedAuthPath,
   writeClaudeManagedAuthFile
 } from './managed-auth-path'
+import { hasLiveClaudePtys } from './live-pty-gate'
 import { ClaudeRuntimePathResolver } from './runtime-paths'
 import {
   deleteActiveClaudeKeychainCredentialsStrict,
@@ -47,7 +48,9 @@ type ClaudeAuthIdentity = {
   organizationUuid: string | null
 }
 
-type ClaudeReadBackResult = { status: 'unchanged' | 'persisted' | 'rejected' }
+type ClaudeReadBackResult =
+  | { status: 'unchanged' | 'persisted' }
+  | { status: 'rejected'; runtimeCredentialsChanged: boolean; runtimeCredentialsJson?: string }
 type ClaudeReadBackMatch =
   | { kind: 'matched'; account: ClaudeManagedAccount; managedCredentialsJson: string }
   | { kind: 'none' | 'ambiguous' }
@@ -250,6 +253,34 @@ export class ClaudeRuntimeAuthService {
           if (updatedCredentialsJson && this.isValidCredentialsJsonObject(updatedCredentialsJson)) {
             credentialsJson = updatedCredentialsJson
           }
+        } else if (
+          readBackResult.status === 'rejected' &&
+          readBackResult.runtimeCredentialsChanged &&
+          hasLiveClaudePtys()
+        ) {
+          if (
+            readBackResult.runtimeCredentialsJson &&
+            this.liveRuntimeCredentialsCanUpdateActiveAccount(
+              readBackResult.runtimeCredentialsJson,
+              activeAccount,
+              credentialsJson,
+              this.readManagedOauthAccount(activeAccount)
+            )
+          ) {
+            // Why: this Claude process was launched under the active managed
+            // account, but persistence still needs positive account proof.
+            await this.writeManagedCredentials(activeAccount, readBackResult.runtimeCredentialsJson)
+            credentialsJson = readBackResult.runtimeCredentialsJson
+          } else {
+            // Why: while Claude is running, an unknown refresh can still belong
+            // to a live session. Rewriting stale managed auth logs that session out.
+            console.warn(
+              '[claude-runtime-auth] Preserving changed Claude runtime credentials while live Claude terminals are running'
+            )
+            this.lastSyncedAccountId = activeAccount.id
+            this.hasMaterializedRuntimeAuth = true
+            return
+          }
         }
       }
     }
@@ -319,6 +350,7 @@ export class ClaudeRuntimeAuthService {
         credentialsJson: string
         match: Extract<ClaudeReadBackMatch, { kind: 'matched' }>
       }[] = []
+      const ambiguousCandidates: string[] = []
       let sawAmbiguousCandidate = false
       for (const runtimeContents of changedCandidates) {
         if (!this.isValidCredentialsJsonObject(runtimeContents)) {
@@ -327,6 +359,7 @@ export class ClaudeRuntimeAuthService {
         const match = await this.findManagedAccountForRuntimeCredentials(runtimeContents)
         if (match.kind === 'ambiguous') {
           sawAmbiguousCandidate = true
+          ambiguousCandidates.push(runtimeContents)
           continue
         }
         if (match.kind !== 'matched') {
@@ -348,7 +381,12 @@ export class ClaudeRuntimeAuthService {
         if (sawAmbiguousCandidate) {
           console.warn('[claude-runtime-auth] Refusing ambiguous Claude auth read-back')
         }
-        return { status: 'rejected' }
+        return {
+          status: 'rejected',
+          runtimeCredentialsChanged: true,
+          runtimeCredentialsJson:
+            ambiguousCandidates.length === 1 ? ambiguousCandidates[0] : undefined
+        }
       }
       const { credentialsJson: runtimeContents, match } =
         this.chooseFreshestReadBackCandidate(acceptedCandidates)
@@ -368,7 +406,11 @@ export class ClaudeRuntimeAuthService {
       // forward sync path — the worst case is one more stale-token cycle, which
       // is strictly better than failing the entire sync.
       console.warn('[claude-runtime-auth] Failed to read back refreshed tokens:', error)
-      return { status: 'rejected' }
+      return {
+        status: 'rejected',
+        runtimeCredentialsChanged:
+          this.runtimeCredentialsChangedSinceLastWrite(baselineCredentialsJson)
+      }
     }
   }
 
@@ -498,6 +540,36 @@ export class ClaudeRuntimeAuthService {
     return 'match'
   }
 
+  private liveRuntimeCredentialsCanUpdateActiveAccount(
+    runtimeCredentialsJson: string,
+    account: ClaudeManagedAccount,
+    managedCredentialsJson: string,
+    managedOauthAccount: unknown
+  ): boolean {
+    const match = this.runtimeCredentialsMatchAccount(
+      runtimeCredentialsJson,
+      account,
+      managedCredentialsJson,
+      managedOauthAccount
+    )
+    if (match === 'match') {
+      return true
+    }
+    const identity = this.readIdentityFromCredentials(runtimeCredentialsJson)
+    const managedIdentity = this.readIdentityFromCredentials(managedCredentialsJson)
+    const managedOauthIdentity = this.readIdentityFromOauthAccount(managedOauthAccount)
+    const selectedOrganizationUuid = this.normalizeField(
+      account.organizationUuid ??
+        managedIdentity?.organizationUuid ??
+        managedOauthIdentity.organizationUuid
+    )
+    return (
+      match === 'unverifiable' &&
+      Boolean(selectedOrganizationUuid) &&
+      identity?.organizationUuid === selectedOrganizationUuid
+    )
+  }
+
   private readIdentityFromCredentials(credentialsJson: string): ClaudeAuthIdentity | null {
     let parsed: Record<string, unknown>
     try {
@@ -1014,6 +1086,21 @@ export class ClaudeRuntimeAuthService {
     return currentCredentialsJson === previouslyWrittenCredentialsJson
   }
 
+  private runtimeCredentialsChangedSinceLastWrite(baselineCredentialsJson: string): boolean {
+    const paths = this.pathResolver.getRuntimePaths()
+    try {
+      const currentCredentialsJson = existsSync(paths.credentialsPath)
+        ? readFileSync(paths.credentialsPath, 'utf-8')
+        : null
+      return (
+        currentCredentialsJson !== null &&
+        currentCredentialsJson !== (this.lastWrittenCredentialsJson ?? baselineCredentialsJson)
+      )
+    } catch {
+      return false
+    }
+  }
+
   private restoreRuntimeCredentials(credentialsJson: string | null): void {
     const paths = this.pathResolver.getRuntimePaths()
     if (credentialsJson !== null) {
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 1c5deb8d3cc..56426e7073d 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -122,6 +122,7 @@ import {
   setLocalPtyProvider,
   unregisterSshPtyProvider
 } from './pty'
+import { hasLiveClaudePtys } from '../claude-accounts/live-pty-gate'
 
 const POWERSHELL_PROFILE_COMMAND = expect.stringMatching(
   /\. \$PROFILE[\s\S]*ORCA_OPENCODE_CONFIG_DIR[\s\S]*ORCA_PI_CODING_AGENT_DIR[\s\S]*UTF8/
@@ -347,6 +348,29 @@ describe('registerPtyHandlers', () => {
   }
 
   describe('spawn environment', () => {
+    it('marks local Claude launches live until the PTY is killed', async () => {
+      const prepareClaudeAuth = vi.fn(async () => ({
+        configDir: '/tmp/claude',
+        envPatch: {},
+        stripAuthEnv: false,
+        provenance: 'managed:account-1'
+      }))
+      registerPtyHandlers(mainWindow as never, undefined, undefined, undefined, prepareClaudeAuth)
+
+      const spawnResult = (await handlers.get('pty:spawn')!(null, {
+        cols: 80,
+        rows: 24,
+        command: 'claude'
+      })) as { id: string }
+
+      expect(prepareClaudeAuth).toHaveBeenCalledTimes(1)
+      expect(hasLiveClaudePtys()).toBe(true)
+
+      await handlers.get('pty:kill')!(null, { id: spawnResult.id })
+
+      expect(hasLiveClaudePtys()).toBe(false)
+    })
+
     it('defaults LANG to en_US.UTF-8 when not inherited from process.env', async () => {
       const env = await spawnAndGetEnv(undefined, { LANG: undefined })
       expect(env.LANG).toBe('en_US.UTF-8')

From 09814150eab5ba1a132232517a7cb380929b0a09 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Thu, 14 May 2026 20:28:52 -0700
Subject: [PATCH 12/82] fix(dashboard): drop agent rows via foreground-process
 tracking, not title heuristic (#1167)

Co-authored-by: Orca <help@stably.ai>
---
 .../attribution/terminal-attribution.test.ts  | 126 +++++++++++-------
 src/main/daemon/pty-subprocess.test.ts        |  12 +-
 src/main/daemon/shell-ready.ts                |  89 +++++++++----
 src/main/daemon/types.ts                      |   8 +-
 src/main/ipc/pty.test.ts                      |  31 +++--
 src/main/powershell-osc133-bootstrap.test.ts  |  30 +++++
 src/main/powershell-osc133-bootstrap.ts       |  80 +++++++++++
 src/main/providers/local-pty-shell-ready.ts   | 107 ++++++++++-----
 src/main/providers/windows-shell-args.test.ts |  51 ++++---
 src/main/providers/windows-shell-args.ts      |  22 +--
 .../components/sidebar/WorktreeCard.test.ts   |  59 +++++++-
 .../sidebar/worktree-card-status.ts           | 121 +++++++++++++++++
 .../terminal-pane/pty-connection.test.ts      |  49 ++++++-
 .../terminal-pane/pty-connection.ts           |  31 +++--
 .../terminal-command-lifecycle.test.ts        |  74 ++++++++++
 .../terminal-command-lifecycle.ts             | 102 ++++++++++++++
 16 files changed, 815 insertions(+), 177 deletions(-)
 create mode 100644 src/main/powershell-osc133-bootstrap.test.ts
 create mode 100644 src/main/powershell-osc133-bootstrap.ts
 create mode 100644 src/renderer/src/components/sidebar/worktree-card-status.ts
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-command-lifecycle.test.ts
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-command-lifecycle.ts

diff --git a/src/main/attribution/terminal-attribution.test.ts b/src/main/attribution/terminal-attribution.test.ts
index 87fc1e1ea2c..ef99f3f2ba2 100644
--- a/src/main/attribution/terminal-attribution.test.ts
+++ b/src/main/attribution/terminal-attribution.test.ts
@@ -31,30 +31,36 @@ describe('applyTerminalAttributionEnv', () => {
     return tmpRoot
   }
 
+  function stripInheritedAttributionPath(pathValue: string): string {
+    const pathDelimiter = process.platform === 'win32' ? ';' : ':'
+    return pathValue
+      .split(pathDelimiter)
+      .filter((entry) => !entry.includes('orca-terminal-attribution'))
+      .join(pathDelimiter)
+  }
+
+  function cleanAttributionEnv(env?: Record<string, string>): Record<string, string> {
+    const base = { ...process.env }
+    delete base.ORCA_ENABLE_GIT_ATTRIBUTION
+    delete base.ORCA_GIT_COMMIT_TRAILER
+    delete base.ORCA_GH_PR_FOOTER
+    delete base.ORCA_GH_ISSUE_FOOTER
+    delete base.ORCA_ATTRIBUTION_SHIM_DIR
+    delete base.ORCA_REAL_GIT
+    delete base.ORCA_REAL_GH
+    base.PATH = stripInheritedAttributionPath(base.PATH ?? '')
+    const next = { ...base, ...env }
+    return next as Record<string, string>
+  }
+
   function runGit(repo: string, args: string[], env?: Record<string, string>): string {
     return execFileSync('git', args, {
       cwd: repo,
       encoding: 'utf8',
-      env: { ...getCleanProcessEnv(), ...env }
+      env: cleanAttributionEnv(env)
     })
   }
 
-  function getCleanProcessEnv(): NodeJS.ProcessEnv {
-    const env = { ...process.env }
-    delete env.ORCA_ENABLE_GIT_ATTRIBUTION
-    delete env.ORCA_GIT_COMMIT_TRAILER
-    delete env.ORCA_GH_PR_FOOTER
-    delete env.ORCA_GH_ISSUE_FOOTER
-    delete env.ORCA_ATTRIBUTION_SHIM_DIR
-    delete env.ORCA_REAL_GIT
-    delete env.ORCA_REAL_GH
-    env.PATH = (env.PATH ?? '')
-      .split(process.platform === 'win32' ? ';' : ':')
-      .filter((entry) => !entry.replace(/\\/g, '/').includes('/orca-terminal-attribution/'))
-      .join(process.platform === 'win32' ? ';' : ':')
-    return env
-  }
-
   it('does not amend HEAD when git commit --dry-run exits successfully', () => {
     const root = makeTmpRoot()
     const repo = join(root, 'repo')
@@ -66,7 +72,7 @@ describe('applyTerminalAttributionEnv', () => {
     runGit(repo, ['add', 'README.md'])
     runGit(repo, ['commit', '-m', 'initial'])
 
-    const attributionEnv = { PATH: process.env.PATH ?? '' }
+    const attributionEnv = { PATH: stripInheritedAttributionPath(process.env.PATH ?? '') }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -99,7 +105,7 @@ describe('applyTerminalAttributionEnv', () => {
     writeFileSync(join(repo, 'README.md'), 'initial\n')
     runGit(repo, ['add', 'README.md'])
 
-    const attributionEnv = { PATH: process.env.PATH ?? '' }
+    const attributionEnv = { PATH: stripInheritedAttributionPath(process.env.PATH ?? '') }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -124,7 +130,7 @@ describe('applyTerminalAttributionEnv', () => {
     runGit(repo, ['commit', '-m', 'initial'])
     writeFileSync(join(repo, 'README.md'), 'changed\n')
 
-    const attributionEnv = { PATH: process.env.PATH ?? '' }
+    const attributionEnv = { PATH: stripInheritedAttributionPath(process.env.PATH ?? '') }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -147,7 +153,7 @@ describe('applyTerminalAttributionEnv', () => {
     writeFileSync(join(repo, 'README.md'), 'initial\n')
     runGit(repo, ['add', 'README.md'])
 
-    const attributionEnv = { PATH: process.env.PATH ?? '' }
+    const attributionEnv = { PATH: stripInheritedAttributionPath(process.env.PATH ?? '') }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -172,7 +178,7 @@ describe('applyTerminalAttributionEnv', () => {
     writeFileSync(messagePath, 'initial from file\n')
     runGit(repo, ['add', 'README.md'])
 
-    const attributionEnv = { PATH: process.env.PATH ?? '' }
+    const attributionEnv = { PATH: stripInheritedAttributionPath(process.env.PATH ?? '') }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -205,7 +211,9 @@ exit 1
     )
     chmodSync(join(binDir, 'git'), 0o755)
 
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -214,7 +222,7 @@ exit 1
     expect(() =>
       execFileSync('git', ['commit', '-F', join(root, 'missing-message.txt')], {
         encoding: 'utf8',
-        env: { ...process.env, ...attributionEnv }
+        env: cleanAttributionEnv(attributionEnv)
       })
     ).toThrow()
 
@@ -242,7 +250,9 @@ exit 1
     )
     chmodSync(join(binDir, 'git'), 0o755)
 
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -250,15 +260,15 @@ exit 1
 
     execFileSync('git', ['commit', '-C', 'HEAD'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
     execFileSync('git', ['commit', '--fixup', 'HEAD'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
     execFileSync('git', ['commit', '-F', messagePath, '--fixup', 'HEAD'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(readFileSync(argsPath, 'utf8')).not.toContain('Co-authored-by: Orca')
@@ -290,7 +300,7 @@ grep -Fq 'Co-authored-by: Orca <help@stably.ai>' "$1"
     writeFileSync(join(repo, 'README.md'), 'initial\n')
     runGit(repo, ['add', 'README.md'])
 
-    const attributionEnv = { PATH: process.env.PATH ?? '' }
+    const attributionEnv = { PATH: stripInheritedAttributionPath(process.env.PATH ?? '') }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -334,7 +344,9 @@ exit 1
     )
     chmodSync(join(binDir, 'git'), 0o755)
 
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -342,7 +354,7 @@ exit 1
 
     execFileSync('git', ['commit', '-m', 'signed commit'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(existsSync(commitPath)).toBe(true)
@@ -369,7 +381,9 @@ exit 1
     )
     chmodSync(join(binDir, 'git'), 0o755)
 
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -377,7 +391,7 @@ exit 1
 
     execFileSync('git', ['commit'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(readFileSync(argsPath, 'utf8')).toBe('commit\n')
@@ -413,7 +427,9 @@ exit 1
       'utf8'
     )
     chmodSync(join(binDir, 'gh'), 0o755)
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -421,7 +437,7 @@ exit 1
 
     const output = execFileSync('gh', ['pr', 'create'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(output).toBe('interactive create complete\n')
@@ -469,7 +485,9 @@ exit 1
       'utf8'
     )
     chmodSync(join(binDir, 'gh'), 0o755)
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -478,13 +496,13 @@ exit 1
     expect(
       execFileSync('gh', ['pr', 'create', '--fill'], {
         encoding: 'utf8',
-        env: { ...process.env, ...attributionEnv }
+        env: cleanAttributionEnv(attributionEnv)
       })
     ).toBe('https://github.com/stablyai/orca/pull/123\n')
     expect(
       execFileSync('gh', ['issue', 'create', '--title', 'Issue', '--body', 'Body'], {
         encoding: 'utf8',
-        env: { ...process.env, ...attributionEnv }
+        env: cleanAttributionEnv(attributionEnv)
       })
     ).toBe('https://github.com/stablyai/orca/issues/456\n')
 
@@ -532,7 +550,9 @@ exit 1
       'utf8'
     )
     chmodSync(join(binDir, 'gh'), 0o755)
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -540,13 +560,13 @@ exit 1
 
     const output = execFileSync('gh', ['pr', 'create', '--help'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(output).toBe('pr help\n')
     const issueOutput = execFileSync('gh', ['issue', 'create', '--help'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(issueOutput).toBe('issue help\n')
@@ -579,7 +599,9 @@ exit 1
       'utf8'
     )
     chmodSync(join(binDir, 'gh'), 0o755)
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -587,7 +609,7 @@ exit 1
 
     const output = execFileSync('gh', ['issue', 'create'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(output).toBe('interactive issue create complete\n')
@@ -619,7 +641,9 @@ exit 1
       'utf8'
     )
     chmodSync(join(binDir, 'gh'), 0o755)
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -627,7 +651,7 @@ exit 1
 
     const output = execFileSync('gh', ['pr', 'create', '--fill'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(output).toBe('https://github.com/stablyai/orca/pull/123\n')
@@ -658,7 +682,9 @@ exit 1
       'utf8'
     )
     chmodSync(join(binDir, 'gh'), 0o755)
-    const attributionEnv = { PATH: `${binDir}:${process.env.PATH ?? ''}` }
+    const attributionEnv = {
+      PATH: `${binDir}:${stripInheritedAttributionPath(process.env.PATH ?? '')}`
+    }
     applyTerminalAttributionEnv(attributionEnv, {
       enabled: true,
       userDataPath: join(root, 'user-data')
@@ -666,7 +692,7 @@ exit 1
 
     const output = execFileSync('gh', ['pr', 'create', '--fill'], {
       encoding: 'utf8',
-      env: { ...process.env, ...attributionEnv }
+      env: cleanAttributionEnv(attributionEnv)
     })
 
     expect(output).toBe('https://github.com/stablyai/orca/pull/123\n')
@@ -689,7 +715,9 @@ exit 1
 
   it('does not duplicate shim directories when applied to an already-injected env', () => {
     const root = makeTmpRoot()
-    const baseEnv: Record<string, string> = { PATH: process.env.PATH ?? '' }
+    const baseEnv: Record<string, string> = {
+      PATH: stripInheritedAttributionPath(process.env.PATH ?? '')
+    }
     const options = { enabled: true, userDataPath: join(root, 'user-data') }
     const pathDelimiter = process.platform === 'win32' ? ';' : ':'
 
@@ -705,7 +733,7 @@ exit 1
   it('writes PowerShell wrappers without raw-template backslash escapes', () => {
     const root = makeTmpRoot()
     applyTerminalAttributionEnv(
-      { PATH: process.env.PATH ?? '' },
+      { PATH: stripInheritedAttributionPath(process.env.PATH ?? '') },
       { enabled: true, userDataPath: join(root, 'user-data') }
     )
 
diff --git a/src/main/daemon/pty-subprocess.test.ts b/src/main/daemon/pty-subprocess.test.ts
index 08b2ab70d3b..0f7b3181152 100644
--- a/src/main/daemon/pty-subprocess.test.ts
+++ b/src/main/daemon/pty-subprocess.test.ts
@@ -24,9 +24,7 @@ const ORCA_SHELL_WRAPPER_ENV = [
   'ORCA_OPENCODE_CONFIG_DIR',
   'ORCA_PI_CODING_AGENT_DIR'
 ] as const
-const POWERSHELL_PROFILE_COMMAND = expect.stringMatching(
-  /ORCA_OPENCODE_CONFIG_DIR[\s\S]*ORCA_PI_CODING_AGENT_DIR[\s\S]*UTF8/
-)
+const POWERSHELL_OSC133_COMMAND_ARGS = ['-NoLogo', '-NoExit', '-EncodedCommand', expect.any(String)]
 const ZSH_SHELL_READY_DIR = /shell-ready[\\/]zsh/
 
 function mockPtyProcess(pid = 12345) {
@@ -413,7 +411,7 @@ describe('createPtySubprocess', () => {
 
     expect(spawnMock).toHaveBeenCalledWith(
       'powershell.exe',
-      ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+      POWERSHELL_OSC133_COMMAND_ARGS,
       expect.any(Object)
     )
   })
@@ -442,7 +440,7 @@ describe('createPtySubprocess', () => {
 
     expect(spawnMock).toHaveBeenCalledWith(
       'pwsh.exe',
-      ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+      POWERSHELL_OSC133_COMMAND_ARGS,
       expect.any(Object)
     )
   })
@@ -471,7 +469,7 @@ describe('createPtySubprocess', () => {
 
     expect(spawnMock).toHaveBeenCalledWith(
       'powershell.exe',
-      ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+      POWERSHELL_OSC133_COMMAND_ARGS,
       expect.any(Object)
     )
   })
@@ -500,7 +498,7 @@ describe('createPtySubprocess', () => {
 
     expect(spawnMock).toHaveBeenCalledWith(
       'powershell.exe',
-      ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+      POWERSHELL_OSC133_COMMAND_ARGS,
       expect.any(Object)
     )
   })
diff --git a/src/main/daemon/shell-ready.ts b/src/main/daemon/shell-ready.ts
index 5ae1aa58d80..4a63443b9e2 100644
--- a/src/main/daemon/shell-ready.ts
+++ b/src/main/daemon/shell-ready.ts
@@ -1,6 +1,11 @@
 import { tmpdir } from 'os'
-import { basename, dirname, join } from 'path'
+import { basename, dirname, join, win32 as pathWin32 } from 'path'
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'fs'
+import {
+  encodePowerShellCommand,
+  getPowerShellOsc133Bootstrap,
+  isPowerShellExecutableName
+} from '../powershell-osc133-bootstrap'
 
 const ORCA_USER_DATA_PATH_ENV = 'ORCA_USER_DATA_PATH'
 const SHELL_READY_MARKER = '\\033]777;orca-shell-ready\\007'
@@ -69,6 +74,44 @@ function shellReadyWrappersExist(): boolean {
   return getRequiredShellReadyWrapperPaths().every((path) => existsSync(path))
 }
 
+export function getDaemonZshShellReadyRcfileContent(): string {
+  return `# Orca daemon zsh shell-ready wrapper
+_orca_home="\${ORCA_ORIG_ZDOTDIR:-$HOME}"
+if [[ "$_orca_home" != "$ZDOTDIR" && -o interactive && -f "$_orca_home/.zshrc" ]]; then
+  source "$_orca_home/.zshrc"
+fi
+__orca_restore_attribution_path() {
+  [[ -n "\${ORCA_ATTRIBUTION_SHIM_DIR:-}" ]] || return 0
+  case "$PATH" in
+    "\${ORCA_ATTRIBUTION_SHIM_DIR}"|"\${ORCA_ATTRIBUTION_SHIM_DIR}:"*) return 0 ;;
+  esac
+  export PATH="\${ORCA_ATTRIBUTION_SHIM_DIR}:$PATH"
+}
+[[ ! -o login ]] && __orca_restore_attribution_path
+if [[ ! -o login ]]; then
+  # Why: ~/.zshrc can export the user's default OpenCode config after spawn.
+  [[ -n "\${ORCA_OPENCODE_CONFIG_DIR:-}" ]] && export OPENCODE_CONFIG_DIR="\${ORCA_OPENCODE_CONFIG_DIR}"
+  # Why: PI_CODING_AGENT_DIR must keep the same PTY-scoped overlay after rc files.
+  [[ -n "\${ORCA_PI_CODING_AGENT_DIR:-}" ]] && export PI_CODING_AGENT_DIR="\${ORCA_PI_CODING_AGENT_DIR}"
+fi
+__orca_osc133_precmd() {
+  local exit_code=$?
+  if [[ -n "\${__orca_in_command:-}" ]]; then
+    printf "\\033]133;D;%s\\007" "$exit_code"
+    unset __orca_in_command
+  fi
+  printf "\\033]133;A\\007"
+}
+__orca_osc133_preexec() {
+  printf "\\033]133;C\\007"
+  __orca_in_command=1
+}
+# Why: prepend so Orca captures $? before user prompt hooks can overwrite it.
+precmd_functions=(__orca_osc133_precmd \${precmd_functions[@]})
+preexec_functions=(__orca_osc133_preexec \${preexec_functions[@]})
+`
+}
+
 function ensureShellReadyWrappers(): void {
   if (process.platform === 'win32') {
     return
@@ -97,29 +140,7 @@ case "\${_orca_home%/}" in
 esac
 [[ -f "$_orca_home/.zprofile" ]] && source "$_orca_home/.zprofile"
 `
-  const zshRc = `# Orca daemon zsh shell-ready wrapper
-_orca_home="\${ORCA_ORIG_ZDOTDIR:-$HOME}"
-case "\${_orca_home%/}" in
-  */shell-ready/zsh) _orca_home="$HOME" ;;
-esac
-if [[ -o interactive && -f "$_orca_home/.zshrc" ]]; then
-  source "$_orca_home/.zshrc"
-fi
-__orca_restore_attribution_path() {
-  [[ -n "\${ORCA_ATTRIBUTION_SHIM_DIR:-}" ]] || return 0
-  case "$PATH" in
-    "\${ORCA_ATTRIBUTION_SHIM_DIR}"|"\${ORCA_ATTRIBUTION_SHIM_DIR}:"*) return 0 ;;
-  esac
-  export PATH="\${ORCA_ATTRIBUTION_SHIM_DIR}:$PATH"
-}
-if [[ ! -o login ]]; then
-  __orca_restore_attribution_path
-  # Why: ~/.zshrc can export the user's default OpenCode config after spawn.
-  [[ -n "\${ORCA_OPENCODE_CONFIG_DIR:-}" ]] && export OPENCODE_CONFIG_DIR="\${ORCA_OPENCODE_CONFIG_DIR}"
-  # Why: PI_CODING_AGENT_DIR must keep the same PTY-scoped overlay after rc files.
-  [[ -n "\${ORCA_PI_CODING_AGENT_DIR:-}" ]] && export PI_CODING_AGENT_DIR="\${ORCA_PI_CODING_AGENT_DIR}"
-fi
-`
+  const zshRc = getDaemonZshShellReadyRcfileContent()
   const zshLogin = `# Orca daemon zsh shell-ready wrapper
 _orca_home="\${ORCA_ORIG_ZDOTDIR:-$HOME}"
 case "\${_orca_home%/}" in
@@ -206,7 +227,7 @@ fi
 
 export function resolvePtyShellPath(env: Record<string, string>): string {
   if (process.platform === 'win32') {
-    return env.COMSPEC || 'powershell.exe'
+    return env.ORCA_TERMINAL_WINDOWS_SHELL || 'powershell.exe'
   }
   return env.SHELL || process.env.SHELL || '/bin/zsh'
 }
@@ -215,7 +236,8 @@ export function supportsPtyStartupBarrier(env: Record<string, string>): boolean
   if (process.platform === 'win32') {
     return false
   }
-  const shellName = basename(resolvePtyShellPath(env)).toLowerCase()
+  const resolvedShell = resolvePtyShellPath(env)
+  const shellName = pathWin32.basename(basename(resolvedShell)).toLowerCase()
   return shellName === 'zsh' || shellName === 'bash'
 }
 
@@ -229,7 +251,7 @@ function getWrappedShellLaunchConfig(
   shellPath: string,
   options: { emitReadyMarker: boolean }
 ): ShellLaunchConfig {
-  const shellName = basename(shellPath).toLowerCase()
+  const shellName = pathWin32.basename(basename(shellPath)).toLowerCase()
 
   if (shellName === 'zsh') {
     ensureShellReadyWrappers()
@@ -257,6 +279,19 @@ function getWrappedShellLaunchConfig(
     }
   }
 
+  if (isPowerShellExecutableName(shellName)) {
+    return {
+      args: [
+        '-NoLogo',
+        '-NoExit',
+        '-EncodedCommand',
+        encodePowerShellCommand(getPowerShellOsc133Bootstrap())
+      ],
+      env: {},
+      supportsReadyMarker: false
+    }
+  }
+
   return {
     args: null,
     env: {},
diff --git a/src/main/daemon/types.ts b/src/main/daemon/types.ts
index 20fda41f02a..7808225393f 100644
--- a/src/main/daemon/types.ts
+++ b/src/main/daemon/types.ts
@@ -1,10 +1,10 @@
 // ─── Protocol Version ────────────────────────────────────────────────
 // Why: daemons can survive app updates. Bump for IPC wire-shape changes, or
 // when daemon-baked behavior cannot be delivered by on-disk wrapper refresh.
-// Why: bumped from 4 → 5 for OpenCode/Pi overlay restoration: a surviving v4
-// daemon keeps emitting stale shell-ready wrappers and stale PowerShell args.
-export const PROTOCOL_VERSION = 5
-export const PREVIOUS_DAEMON_PROTOCOL_VERSIONS = [1, 2, 3, 4] as const
+// Why: bumped from 5 -> 6 for OSC 133 shell wrapper changes layered on top of
+// OpenCode/Pi overlay restoration, both of which are baked into daemon spawns.
+export const PROTOCOL_VERSION = 6
+export const PREVIOUS_DAEMON_PROTOCOL_VERSIONS = [1, 2, 3, 4, 5] as const
 
 // ─── Session State Machine ──────────────────────────────────────────
 export type SessionState = 'created' | 'spawning' | 'running' | 'exiting' | 'exited'
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 56426e7073d..38ca92c39dd 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -123,10 +123,17 @@ import {
   unregisterSshPtyProvider
 } from './pty'
 import { hasLiveClaudePtys } from '../claude-accounts/live-pty-gate'
+import {
+  encodePowerShellCommand,
+  getPowerShellOsc133Bootstrap
+} from '../powershell-osc133-bootstrap'
 
-const POWERSHELL_PROFILE_COMMAND = expect.stringMatching(
-  /\. \$PROFILE[\s\S]*ORCA_OPENCODE_CONFIG_DIR[\s\S]*ORCA_PI_CODING_AGENT_DIR[\s\S]*UTF8/
-)
+const POWERSHELL_OSC133_ARGS = [
+  '-NoLogo',
+  '-NoExit',
+  '-EncodedCommand',
+  encodePowerShellCommand(getPowerShellOsc133Bootstrap())
+]
 
 function makeDisposable() {
   return { dispose: vi.fn() }
@@ -1721,7 +1728,7 @@ describe('registerPtyHandlers', () => {
 
       expect(spawnMock).toHaveBeenCalledWith(
         'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe',
-        ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+        POWERSHELL_OSC133_ARGS,
         expect.any(Object)
       )
     })
@@ -1734,7 +1741,7 @@ describe('registerPtyHandlers', () => {
 
       expect(spawnMock).toHaveBeenCalledWith(
         'C:\\Program Files\\PowerShell\\7\\pwsh.exe',
-        ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+        POWERSHELL_OSC133_ARGS,
         expect.any(Object)
       )
     })
@@ -1793,7 +1800,7 @@ describe('registerPtyHandlers', () => {
 
       expect(spawnMock).toHaveBeenCalledWith(
         'powershell.exe',
-        ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+        POWERSHELL_OSC133_ARGS,
         expect.any(Object)
       )
     })
@@ -1815,7 +1822,7 @@ describe('registerPtyHandlers', () => {
 
       expect(spawnMock).toHaveBeenCalledWith(
         'powershell.exe',
-        ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+        POWERSHELL_OSC133_ARGS,
         expect.any(Object)
       )
     })
@@ -1836,11 +1843,7 @@ describe('registerPtyHandlers', () => {
       )
       handlers.get('pty:spawn')!(null, { cols: 80, rows: 24 })
 
-      expect(spawnMock).toHaveBeenCalledWith(
-        'pwsh.exe',
-        ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
-        expect.any(Object)
-      )
+      expect(spawnMock).toHaveBeenCalledWith('pwsh.exe', POWERSHELL_OSC133_ARGS, expect.any(Object))
     })
 
     it('falls back to powershell.exe when PowerShell 7 is selected but unavailable', () => {
@@ -1861,7 +1864,7 @@ describe('registerPtyHandlers', () => {
 
       expect(spawnMock).toHaveBeenCalledWith(
         'powershell.exe',
-        ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+        POWERSHELL_OSC133_ARGS,
         expect.any(Object)
       )
     })
@@ -1884,7 +1887,7 @@ describe('registerPtyHandlers', () => {
 
       expect(spawnMock).toHaveBeenCalledWith(
         'powershell.exe',
-        ['-NoExit', '-Command', POWERSHELL_PROFILE_COMMAND],
+        POWERSHELL_OSC133_ARGS,
         expect.any(Object)
       )
     })
diff --git a/src/main/powershell-osc133-bootstrap.test.ts b/src/main/powershell-osc133-bootstrap.test.ts
new file mode 100644
index 00000000000..a7219b84500
--- /dev/null
+++ b/src/main/powershell-osc133-bootstrap.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import {
+  encodePowerShellCommand,
+  getPowerShellOsc133Bootstrap
+} from './powershell-osc133-bootstrap'
+
+describe('PowerShell OSC 133 bootstrap', () => {
+  it('wraps prompt/readline without bypassing profiles or execution policy', () => {
+    const script = getPowerShellOsc133Bootstrap()
+
+    expect(script).toContain('[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()')
+    expect(script).toContain('ORCA_OPENCODE_CONFIG_DIR')
+    expect(script).toContain('ORCA_PI_CODING_AGENT_DIR')
+    expect(script).toContain('function Global:prompt')
+    expect(script).toContain('function Global:PSConsoleHostReadLine')
+    expect(script).toContain('`e]133;D;$fakeExitCode`a')
+    expect(script).toContain('`e]133;A`a')
+    expect(script).toContain('`e]133;B`a')
+    expect(script).toContain('`e]133;C`a')
+    expect(script).not.toContain('$PROFILE')
+    expect(script).not.toContain('ExecutionPolicy')
+    expect(script).not.toContain('NoProfile')
+  })
+
+  it('encodes commands as UTF-16LE base64 for PowerShell -EncodedCommand', () => {
+    expect(encodePowerShellCommand('Write-Output ok')).toBe(
+      Buffer.from('Write-Output ok', 'utf16le').toString('base64')
+    )
+  })
+})
diff --git a/src/main/powershell-osc133-bootstrap.ts b/src/main/powershell-osc133-bootstrap.ts
new file mode 100644
index 00000000000..1784020c468
--- /dev/null
+++ b/src/main/powershell-osc133-bootstrap.ts
@@ -0,0 +1,80 @@
+const POWERSHELL_OSC133_BOOTSTRAP = `# Orca OSC 133 shell integration for PowerShell.
+if ((Test-Path variable:global:__OrcaOsc133State) -and
+    $null -ne $Global:__OrcaOsc133State.OriginalPrompt) {
+    return
+}
+
+if ($ExecutionContext.SessionState.LanguageMode -ne "FullLanguage") {
+    return
+}
+
+# Profiles have already loaded normally by the time -EncodedCommand runs.
+# Wrap the user's final prompt/readline state; do not source profiles here.
+
+# Preserve Windows CJK output by keeping ConPTY on UTF-8 without bypassing
+# profile loading or execution-policy checks.
+try {
+    [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+    [Console]::InputEncoding = [System.Text.UTF8Encoding]::new()
+    $OutputEncoding = [Console]::OutputEncoding
+} catch { Write-Error $_ -ErrorAction Continue }
+
+# Profiles can re-export user defaults after Orca's spawn env is set.
+if ($env:ORCA_OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = $env:ORCA_OPENCODE_CONFIG_DIR }
+if ($env:ORCA_PI_CODING_AGENT_DIR) { $env:PI_CODING_AGENT_DIR = $env:ORCA_PI_CODING_AGENT_DIR }
+
+$Global:__OrcaOsc133State = @{
+    OriginalPrompt = $function:prompt
+    OriginalReadLine = $function:PSConsoleHostReadLine
+    HasSeenPrompt = $false
+    HasPSReadLine = $null -ne (Get-Module -Name PSReadLine)
+}
+
+function Global:prompt {
+    # Capture FIRST; any other expression can clobber PowerShell's success bit.
+    $fakeExitCode = [int](!$global:?)
+    Set-StrictMode -Off
+    $result = ""
+
+    # Emit D from prompt, not readline state. Some profile setups bypass
+    # PSConsoleHostReadLine; the consumer only needs completion.
+    if ($Global:__OrcaOsc133State.HasSeenPrompt) {
+        $result += "\`e]133;D;$fakeExitCode\`a"
+    }
+    $Global:__OrcaOsc133State.HasSeenPrompt = $true
+
+    $result += "\`e]133;A\`a"
+    # Preserve the previous success/failure value for prompts that inspect it.
+    if ($fakeExitCode -ne 0) { Write-Error "failure" -ea ignore }
+    $result += $Global:__OrcaOsc133State.OriginalPrompt.Invoke()
+    $result += "\`e]133;B\`a"
+    $result
+}
+
+if ($Global:__OrcaOsc133State.HasPSReadLine -and
+    $null -ne $Global:__OrcaOsc133State.OriginalReadLine) {
+    function Global:PSConsoleHostReadLine {
+        $commandLine = $Global:__OrcaOsc133State.OriginalReadLine.Invoke()
+        [Console]::Write("\`e]133;C\`a")
+        return $commandLine
+    }
+}
+`
+
+export function getPowerShellOsc133Bootstrap(): string {
+  return POWERSHELL_OSC133_BOOTSTRAP
+}
+
+export function encodePowerShellCommand(command: string): string {
+  return Buffer.from(command, 'utf16le').toString('base64')
+}
+
+export function isPowerShellExecutableName(shellName: string): boolean {
+  const normalized = shellName.toLowerCase()
+  return (
+    normalized === 'pwsh' ||
+    normalized === 'pwsh.exe' ||
+    normalized === 'powershell' ||
+    normalized === 'powershell.exe'
+  )
+}
diff --git a/src/main/providers/local-pty-shell-ready.ts b/src/main/providers/local-pty-shell-ready.ts
index 85ce95c284c..1b0a4d57040 100644
--- a/src/main/providers/local-pty-shell-ready.ts
+++ b/src/main/providers/local-pty-shell-ready.ts
@@ -6,14 +6,20 @@
  *
  * Why: when Orca needs to inject a startup command (e.g. issue command runner),
  * it must wait until the shell has fully initialized before writing. This module
- * provides shell wrapper rcfiles that emit an OSC 133;A marker after startup,
+ * provides shell wrapper rcfiles that emit an OSC 777 marker after startup,
  * and a data scanner that detects that marker so the command can be written at
  * the right time.
  */
-import { basename } from 'path'
+import { tmpdir } from 'os'
+import { basename, win32 as pathWin32 } from 'path'
 import { mkdirSync, writeFileSync, chmodSync } from 'fs'
 import { app } from 'electron'
 import type * as pty from 'node-pty'
+import {
+  encodePowerShellCommand,
+  getPowerShellOsc133Bootstrap,
+  isPowerShellExecutableName
+} from '../powershell-osc133-bootstrap'
 
 let didEnsureShellReadyWrappers = false
 
@@ -22,9 +28,10 @@ function quotePosixSingle(value: string): string {
 }
 
 const STARTUP_COMMAND_READY_MAX_WAIT_MS = 1500
-const OSC_133_A = '\x1b]133;A'
+const SHELL_READY_MARKER = '\x1b]777;orca-shell-ready'
+const SHELL_READY_MARKER_ESCAPED = '\\033]777;orca-shell-ready\\007'
 
-// ── OSC 133;A scanner ───────────────────────────────────────────────
+// ── OSC 777 shell-ready scanner ─────────────────────────────────────
 
 export type ShellReadyScanState = {
   matchPos: number
@@ -43,15 +50,15 @@ export function scanForShellReady(
 
   for (let i = 0; i < data.length; i += 1) {
     const ch = data[i] as string
-    if (state.matchPos < OSC_133_A.length) {
-      if (ch === OSC_133_A[state.matchPos]) {
+    if (state.matchPos < SHELL_READY_MARKER.length) {
+      if (ch === SHELL_READY_MARKER[state.matchPos]) {
         state.heldBytes += ch
         state.matchPos += 1
       } else {
         output += state.heldBytes
         state.heldBytes = ''
         state.matchPos = 0
-        if (ch === OSC_133_A[0]) {
+        if (ch === SHELL_READY_MARKER[0]) {
           state.heldBytes = ch
           state.matchPos = 1
         } else {
@@ -74,7 +81,8 @@ export function scanForShellReady(
 // ── Shell wrapper files ─────────────────────────────────────────────
 
 function getShellReadyWrapperRoot(): string {
-  return `${app.getPath('userData')}/shell-ready`
+  const userDataPath = app?.getPath?.('userData') ?? process.env.ORCA_USER_DATA_PATH ?? tmpdir()
+  return `${userDataPath}/shell-ready`
 }
 
 // Why: if our own process inherited ZDOTDIR from a parent shell that was
@@ -144,7 +152,7 @@ __orca_restore_attribution_path
 # startup files have rebuilt the prompt, without re-running user rc files.
 if [[ "\${ORCA_SHELL_READY_MARKER:-0}" == "1" ]]; then
   __orca_prompt_mark() {
-    printf "\\033]133;A\\007"
+    printf "${SHELL_READY_MARKER_ESCAPED}"
   }
   if [[ "$(declare -p PROMPT_COMMAND 2>/dev/null)" == "declare -a"* ]]; then
     PROMPT_COMMAND=("\${PROMPT_COMMAND[@]}" "__orca_prompt_mark")
@@ -160,6 +168,44 @@ fi
 `
 }
 
+export function getZshShellReadyRcfileContent(): string {
+  return `# Orca zsh shell-ready wrapper
+_orca_home="\${ORCA_ORIG_ZDOTDIR:-$HOME}"
+if [[ "$_orca_home" != "$ZDOTDIR" && -o interactive && -f "$_orca_home/.zshrc" ]]; then
+  source "$_orca_home/.zshrc"
+fi
+__orca_restore_attribution_path() {
+  [[ -n "\${ORCA_ATTRIBUTION_SHIM_DIR:-}" ]] || return 0
+  case "$PATH" in
+    "\${ORCA_ATTRIBUTION_SHIM_DIR}"|"\${ORCA_ATTRIBUTION_SHIM_DIR}:"*) return 0 ;;
+  esac
+  export PATH="\${ORCA_ATTRIBUTION_SHIM_DIR}:$PATH"
+}
+[[ ! -o login ]] && __orca_restore_attribution_path
+if [[ ! -o login ]]; then
+  # Why: ~/.zshrc can export the user's default OpenCode config after spawn.
+  [[ -n "\${ORCA_OPENCODE_CONFIG_DIR:-}" ]] && export OPENCODE_CONFIG_DIR="\${ORCA_OPENCODE_CONFIG_DIR}"
+  # Why: PI_CODING_AGENT_DIR must keep the same PTY-scoped overlay after rc files.
+  [[ -n "\${ORCA_PI_CODING_AGENT_DIR:-}" ]] && export PI_CODING_AGENT_DIR="\${ORCA_PI_CODING_AGENT_DIR}"
+fi
+__orca_osc133_precmd() {
+  local exit_code=$?
+  if [[ -n "\${__orca_in_command:-}" ]]; then
+    printf "\\033]133;D;%s\\007" "$exit_code"
+    unset __orca_in_command
+  fi
+  printf "\\033]133;A\\007"
+}
+__orca_osc133_preexec() {
+  printf "\\033]133;C\\007"
+  __orca_in_command=1
+}
+# Why: prepend so Orca captures $? before user prompt hooks can overwrite it.
+precmd_functions=(__orca_osc133_precmd \${precmd_functions[@]})
+preexec_functions=(__orca_osc133_preexec \${preexec_functions[@]})
+`
+}
+
 function ensureShellReadyWrappers(): void {
   if (didEnsureShellReadyWrappers || process.platform === 'win32') {
     return
@@ -185,29 +231,7 @@ case "\${_orca_home%/}" in
 esac
 [[ -f "$_orca_home/.zprofile" ]] && source "$_orca_home/.zprofile"
 `
-  const zshRc = `# Orca zsh shell-ready wrapper
-_orca_home="\${ORCA_ORIG_ZDOTDIR:-$HOME}"
-case "\${_orca_home%/}" in
-  */shell-ready/zsh) _orca_home="$HOME" ;;
-esac
-if [[ -o interactive && -f "$_orca_home/.zshrc" ]]; then
-  source "$_orca_home/.zshrc"
-fi
-__orca_restore_attribution_path() {
-  [[ -n "\${ORCA_ATTRIBUTION_SHIM_DIR:-}" ]] || return 0
-  case "$PATH" in
-    "\${ORCA_ATTRIBUTION_SHIM_DIR}"|"\${ORCA_ATTRIBUTION_SHIM_DIR}:"*) return 0 ;;
-  esac
-  export PATH="\${ORCA_ATTRIBUTION_SHIM_DIR}:$PATH"
-}
-if [[ ! -o login ]]; then
-  __orca_restore_attribution_path
-  # Why: ~/.zshrc can export the user's default OpenCode config after spawn.
-  [[ -n "\${ORCA_OPENCODE_CONFIG_DIR:-}" ]] && export OPENCODE_CONFIG_DIR="\${ORCA_OPENCODE_CONFIG_DIR}"
-  # Why: PI_CODING_AGENT_DIR must keep the same PTY-scoped overlay after rc files.
-  [[ -n "\${ORCA_PI_CODING_AGENT_DIR:-}" ]] && export PI_CODING_AGENT_DIR="\${ORCA_PI_CODING_AGENT_DIR}"
-fi
-`
+  const zshRc = getZshShellReadyRcfileContent()
   const zshLogin = `# Orca zsh shell-ready wrapper
 _orca_home="\${ORCA_ORIG_ZDOTDIR:-$HOME}"
 case "\${_orca_home%/}" in
@@ -231,7 +255,7 @@ __orca_restore_attribution_path
 # which can double-echo startup commands. line-init fires when zle is ready.
 if [[ "\${ORCA_SHELL_READY_MARKER:-0}" == "1" ]]; then
   __orca_prompt_mark() {
-    printf "\\033]133;A\\007"
+    printf "${SHELL_READY_MARKER_ESCAPED}"
   }
   autoload -Uz add-zle-hook-widget
   zle -N __orca_prompt_mark
@@ -268,7 +292,7 @@ function getWrappedShellLaunchConfig(
   shellPath: string,
   options: { emitReadyMarker: boolean }
 ): ShellReadyLaunchConfig {
-  const shellName = basename(shellPath).toLowerCase()
+  const shellName = pathWin32.basename(basename(shellPath)).toLowerCase()
 
   if (shellName === 'zsh') {
     ensureShellReadyWrappers()
@@ -294,6 +318,19 @@ function getWrappedShellLaunchConfig(
     }
   }
 
+  if (isPowerShellExecutableName(shellName)) {
+    return {
+      args: [
+        '-NoLogo',
+        '-NoExit',
+        '-EncodedCommand',
+        encodePowerShellCommand(getPowerShellOsc133Bootstrap())
+      ],
+      env: {},
+      supportsReadyMarker: false
+    }
+  }
+
   return {
     args: null,
     env: {},
@@ -365,7 +402,7 @@ export function writeStartupCommandWhenShellReady(
     if (sent) {
       return
     }
-    // Why: the shell-ready marker (OSC 133;A) fires from precmd/PROMPT_COMMAND,
+    // Why: the shell-ready marker fires from precmd/PROMPT_COMMAND,
     // before the prompt is drawn and before zle/readline switches the PTY into
     // raw mode. Writing the command while the kernel still has ECHO enabled
     // causes the characters to be echoed once by the kernel and then redisplayed
diff --git a/src/main/providers/windows-shell-args.test.ts b/src/main/providers/windows-shell-args.test.ts
index bc0cf9feb34..0c18d639340 100644
--- a/src/main/providers/windows-shell-args.test.ts
+++ b/src/main/providers/windows-shell-args.test.ts
@@ -1,4 +1,8 @@
 import { describe, expect, it } from 'vitest'
+import {
+  encodePowerShellCommand,
+  getPowerShellOsc133Bootstrap
+} from '../powershell-osc133-bootstrap'
 import { resolveWindowsShellLaunchArgs } from './windows-shell-args'
 
 describe('resolveWindowsShellLaunchArgs', () => {
@@ -9,38 +13,46 @@ describe('resolveWindowsShellLaunchArgs', () => {
     expect(result.validationCwd).toBe('C:\\Users\\alice')
   })
 
-  it('returns PowerShell args that dot-source $PROFILE and force UTF-8 I/O', () => {
+  it('returns PowerShell args that install OSC 133 bootstrap after normal profile loading', () => {
     const result = resolveWindowsShellLaunchArgs(
       'powershell.exe',
       'C:\\Users\\alice',
       'C:\\Users\\alice'
     )
-    expect(result.shellArgs[0]).toBe('-NoExit')
-    expect(result.shellArgs[1]).toBe('-Command')
-    // The actual command must dot-source $PROFILE before setting encodings,
-    // otherwise oh-my-posh / starship / PSReadLine never load.
-    const command = result.shellArgs[2] ?? ''
-    const profileIndex = command.indexOf('. $PROFILE')
+    expect(result.shellArgs).toEqual([
+      '-NoLogo',
+      '-NoExit',
+      '-EncodedCommand',
+      encodePowerShellCommand(getPowerShellOsc133Bootstrap())
+    ])
+
+    const command = Buffer.from(result.shellArgs[3] ?? '', 'base64').toString('utf16le')
+    const outputEncodingIndex = command.indexOf('[Console]::OutputEncoding')
     const opencodeRestoreIndex = command.indexOf(
       '$env:OPENCODE_CONFIG_DIR = $env:ORCA_OPENCODE_CONFIG_DIR'
     )
     const piRestoreIndex = command.indexOf(
       '$env:PI_CODING_AGENT_DIR = $env:ORCA_PI_CODING_AGENT_DIR'
     )
-    const outputEncodingIndex = command.indexOf('[Console]::OutputEncoding')
-    const inputEncodingIndex = command.indexOf('[Console]::InputEncoding')
+    const promptIndex = command.indexOf('function Global:prompt')
 
-    expect(profileIndex).toBeGreaterThanOrEqual(0)
-    expect(opencodeRestoreIndex).toBeGreaterThan(profileIndex)
-    expect(piRestoreIndex).toBeGreaterThan(profileIndex)
-    expect(outputEncodingIndex).toBeGreaterThan(opencodeRestoreIndex)
-    expect(outputEncodingIndex).toBeGreaterThan(piRestoreIndex)
-    expect(inputEncodingIndex).toBeGreaterThan(outputEncodingIndex)
+    expect(command).not.toContain('$PROFILE')
+    expect(outputEncodingIndex).toBeGreaterThanOrEqual(0)
+    expect(opencodeRestoreIndex).toBeGreaterThan(outputEncodingIndex)
+    expect(piRestoreIndex).toBeGreaterThan(outputEncodingIndex)
+    expect(promptIndex).toBeGreaterThan(piRestoreIndex)
+    expect(command).toContain('`e]133;D;$fakeExitCode`a')
+    expect(command).toContain('`e]133;C`a')
   })
 
   it('handles pwsh.exe (PowerShell Core) the same as Windows PowerShell', () => {
     const result = resolveWindowsShellLaunchArgs('pwsh.exe', 'C:\\', 'C:\\Users\\alice')
-    expect(result.shellArgs[0]).toBe('-NoExit')
+    expect(result.shellArgs).toEqual([
+      '-NoLogo',
+      '-NoExit',
+      '-EncodedCommand',
+      encodePowerShellCommand(getPowerShellOsc133Bootstrap())
+    ])
   })
 
   it('translates Windows cwd to /mnt/<drive>/... for wsl.exe', () => {
@@ -117,6 +129,11 @@ describe('resolveWindowsShellLaunchArgs', () => {
 
   it('is case-insensitive on the shell basename', () => {
     const result = resolveWindowsShellLaunchArgs('PowerShell.EXE', 'C:\\', 'C:\\')
-    expect(result.shellArgs[0]).toBe('-NoExit')
+    expect(result.shellArgs).toEqual([
+      '-NoLogo',
+      '-NoExit',
+      '-EncodedCommand',
+      encodePowerShellCommand(getPowerShellOsc133Bootstrap())
+    ])
   })
 })
diff --git a/src/main/providers/windows-shell-args.ts b/src/main/providers/windows-shell-args.ts
index e9f58d22664..abce6a37be3 100644
--- a/src/main/providers/windows-shell-args.ts
+++ b/src/main/providers/windows-shell-args.ts
@@ -1,5 +1,9 @@
 import { win32 as pathWin32 } from 'path'
 import { parseWslPath, toLinuxPath } from '../wsl'
+import {
+  encodePowerShellCommand,
+  getPowerShellOsc133Bootstrap
+} from '../powershell-osc133-bootstrap'
 
 /** Result of resolving a Windows shell to its launch args + effective cwd.
  *
@@ -46,17 +50,15 @@ export function resolveWindowsShellLaunchArgs(
   }
 
   if (shellBasename === 'powershell.exe' || shellBasename === 'pwsh.exe') {
-    // Why: PowerShell profiles run after the spawn env is set and may re-export
-    // user defaults; restore Orca's PTY-scoped overlays after the profile.
-    const command = [
-      'try { . $PROFILE } catch {}',
-      'if ($env:ORCA_OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = $env:ORCA_OPENCODE_CONFIG_DIR }',
-      'if ($env:ORCA_PI_CODING_AGENT_DIR) { $env:PI_CODING_AGENT_DIR = $env:ORCA_PI_CODING_AGENT_DIR }',
-      '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
-      '[Console]::InputEncoding = [System.Text.Encoding]::UTF8'
-    ].join('; ')
+    // Why: foreground-process status on Windows depends on OSC 133 C/D, and
+    // PowerShell needs a prompt/readline bootstrap after profiles finish.
     return {
-      shellArgs: ['-NoExit', '-Command', command],
+      shellArgs: [
+        '-NoLogo',
+        '-NoExit',
+        '-EncodedCommand',
+        encodePowerShellCommand(getPowerShellOsc133Bootstrap())
+      ],
       effectiveCwd: cwd,
       validationCwd: cwd
     }
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.test.ts b/src/renderer/src/components/sidebar/WorktreeCard.test.ts
index 24aa69d6315..17f28248c1c 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.test.ts
+++ b/src/renderer/src/components/sidebar/WorktreeCard.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
+import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
 import type { TerminalTab } from '../../../../shared/types'
 
 vi.mock('@/lib/agent-status', () => ({
@@ -10,10 +11,15 @@ vi.mock('@/lib/agent-status', () => ({
       return 'working'
     }
     return null
-  })
+  }),
+  isExplicitAgentStatusFresh: vi.fn(
+    (entry: AgentStatusEntry, now: number, staleAfterMs: number) =>
+      now - entry.updatedAt <= staleAfterMs
+  )
 }))
 
 import { getWorktreeStatus } from '@/lib/worktree-status'
+import { deriveWorktreeCardStatus } from './worktree-card-status'
 
 function makeTerminalTab(title: string): TerminalTab {
   return {
@@ -28,6 +34,22 @@ function makeTerminalTab(title: string): TerminalTab {
   }
 }
 
+function makeAgentStatusEntry(args: {
+  paneKey: string
+  state: AgentStatusEntry['state']
+  updatedAt?: number
+}): AgentStatusEntry {
+  const updatedAt = args.updatedAt ?? 1_000
+  return {
+    paneKey: args.paneKey,
+    state: args.state,
+    prompt: '',
+    updatedAt,
+    stateStartedAt: updatedAt,
+    stateHistory: []
+  }
+}
+
 describe('getWorktreeStatus', () => {
   it('treats browser-only worktrees as active', () => {
     expect(getWorktreeStatus([], [{ id: 'browser-1' }], {})).toBe('active')
@@ -45,3 +67,38 @@ describe('getWorktreeStatus', () => {
     ).toBe('working')
   })
 })
+
+describe('deriveWorktreeCardStatus', () => {
+  it('keeps split-pane heuristics for panes without fresh explicit status', () => {
+    const status = deriveWorktreeCardStatus({
+      tabs: [makeTerminalTab('claude [done]')],
+      browserTabs: [],
+      worktreeAgentEntries: [makeAgentStatusEntry({ paneKey: 'tab-1:1', state: 'done' })],
+      runtimePaneTitlesByTabId: {
+        'tab-1': {
+          1: 'claude [done]',
+          2: 'codex [working]'
+        }
+      },
+      now: 1_000
+    })
+
+    expect(status).toBe('working')
+  })
+
+  it('lets fresh explicit status win over the matching pane title heuristic', () => {
+    const status = deriveWorktreeCardStatus({
+      tabs: [makeTerminalTab('codex [working]')],
+      browserTabs: [],
+      worktreeAgentEntries: [makeAgentStatusEntry({ paneKey: 'tab-1:2', state: 'done' })],
+      runtimePaneTitlesByTabId: {
+        'tab-1': {
+          2: 'codex [working]'
+        }
+      },
+      now: 1_000
+    })
+
+    expect(status).toBe('done')
+  })
+})
diff --git a/src/renderer/src/components/sidebar/worktree-card-status.ts b/src/renderer/src/components/sidebar/worktree-card-status.ts
new file mode 100644
index 00000000000..61daeb74c9a
--- /dev/null
+++ b/src/renderer/src/components/sidebar/worktree-card-status.ts
@@ -0,0 +1,121 @@
+import { detectAgentStatusFromTitle, isExplicitAgentStatusFresh } from '@/lib/agent-status'
+import type { WorktreeStatus } from '@/lib/worktree-status'
+import {
+  AGENT_STATUS_STALE_AFTER_MS,
+  type AgentStatusEntry
+} from '../../../../shared/agent-status-types'
+import type { TerminalTab } from '../../../../shared/types'
+
+type WorktreeCardStatusInput = {
+  tabs: Pick<TerminalTab, 'id' | 'ptyId' | 'title'>[]
+  browserTabs: { id: string }[]
+  worktreeAgentEntries: AgentStatusEntry[]
+  runtimePaneTitlesByTabId: Record<string, Record<number, string>>
+  now?: number
+}
+
+export function deriveWorktreeCardStatus({
+  tabs,
+  browserTabs,
+  worktreeAgentEntries,
+  runtimePaneTitlesByTabId,
+  now = Date.now()
+}: WorktreeCardStatusInput): WorktreeStatus {
+  const liveTabs = tabs.filter((tab) => tab.ptyId)
+  // Why: browser-only worktrees are still active from the user's point of
+  // view even when they have no PTY-backed terminal. The sidebar filter
+  // already treats them as active, so every navigation surface must reuse
+  // that rule instead of showing a misleading inactive dot.
+  const hasTerminals = liveTabs.length > 0 || browserTabs.length > 0
+  if (!hasTerminals) {
+    return 'inactive'
+  }
+
+  const freshByTabId = new Map<string, AgentStatusEntry[]>()
+  const explicitPaneIdsByTabId = new Map<string, Set<string>>()
+  for (const entry of worktreeAgentEntries) {
+    if (!isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)) {
+      continue
+    }
+    const colonIdx = entry.paneKey.indexOf(':')
+    // Why: paneKey must be `${tabId}:${paneId}`. Skip malformed entries (no
+    // colon or leading colon) rather than bucketing under "".
+    if (colonIdx <= 0) {
+      continue
+    }
+    const tabId = entry.paneKey.slice(0, colonIdx)
+    const paneId = entry.paneKey.slice(colonIdx + 1)
+    const bucket = freshByTabId.get(tabId)
+    if (bucket) {
+      bucket.push(entry)
+    } else {
+      freshByTabId.set(tabId, [entry])
+    }
+    const explicitPaneIds = explicitPaneIdsByTabId.get(tabId) ?? new Set<string>()
+    explicitPaneIds.add(paneId)
+    explicitPaneIdsByTabId.set(tabId, explicitPaneIds)
+  }
+
+  let hasPermission = false
+  let hasWorking = false
+  let hasDone = false
+  for (const tab of liveTabs) {
+    const fresh = freshByTabId.get(tab.id)
+    if (fresh && fresh.length > 0) {
+      if (fresh.some((e) => e.state === 'blocked' || e.state === 'waiting')) {
+        hasPermission = true
+      } else if (fresh.some((e) => e.state === 'working')) {
+        hasWorking = true
+      } else if (fresh.some((e) => e.state === 'done')) {
+        hasDone = true
+      }
+    }
+
+    const explicitPaneIds = explicitPaneIdsByTabId.get(tab.id)
+    const paneTitles = runtimePaneTitlesByTabId[tab.id]
+    if (paneTitles && Object.keys(paneTitles).length > 0) {
+      for (const [paneId, title] of Object.entries(paneTitles)) {
+        // Why: explicit hook status only supersedes the matching pane. Other
+        // split panes still need the title heuristic when hooks are absent.
+        if (explicitPaneIds?.has(paneId)) {
+          continue
+        }
+        const heuristic = detectAgentStatusFromTitle(title)
+        if (heuristic === 'permission') {
+          hasPermission = true
+          break
+        }
+        if (heuristic === 'working') {
+          hasWorking = true
+        }
+      }
+      continue
+    }
+
+    if (fresh && fresh.length > 0) {
+      continue
+    }
+
+    const heuristic = detectAgentStatusFromTitle(tab.title)
+    if (heuristic === 'permission') {
+      hasPermission = true
+    } else if (heuristic === 'working') {
+      hasWorking = true
+    }
+  }
+
+  if (hasPermission) {
+    return 'permission'
+  }
+  if (hasWorking) {
+    return 'working'
+  }
+  // Why: surface 'done' as its own status so the sidebar dot turns blue
+  // (sky-500/80) — matching the dashboard's done color. A completed agent
+  // still has a live terminal, so 'inactive' would be misleading; calling
+  // it 'done' keeps the two surfaces in agreement on what the agent is.
+  if (hasDone) {
+    return 'done'
+  }
+  return 'active'
+}
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index f907807c632..518964f6274 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -35,6 +35,9 @@ type StoreState = {
   removeDeferredSshSessionId: ReturnType<typeof vi.fn>
   consumePendingColdRestore: ReturnType<typeof vi.fn>
   consumePendingSnapshot: ReturnType<typeof vi.fn>
+  agentStatusByPaneKey: Record<string, unknown>
+  removeAgentStatus: ReturnType<typeof vi.fn>
+  dropAgentStatus: ReturnType<typeof vi.fn>
 }
 
 type ConnectCallbacks = {
@@ -163,7 +166,10 @@ function createPane(paneId: number) {
       write: vi.fn(),
       onData: vi.fn(() => ({ dispose: vi.fn() })),
       onResize: vi.fn(() => ({ dispose: vi.fn() })),
-      onTitleChange: vi.fn(() => ({ dispose: vi.fn() }))
+      onTitleChange: vi.fn(() => ({ dispose: vi.fn() })),
+      parser: {
+        registerOscHandler: vi.fn(() => ({ dispose: vi.fn() }))
+      }
     },
     container: { dataset: {} },
     fitAddon: {
@@ -253,7 +259,9 @@ describe('connectPanePty', () => {
       removeDeferredSshSessionId: vi.fn(),
       consumePendingColdRestore: vi.fn(() => null),
       consumePendingSnapshot: vi.fn(() => null),
-      removeAgentStatus: vi.fn()
+      agentStatusByPaneKey: {},
+      removeAgentStatus: vi.fn(),
+      dropAgentStatus: vi.fn()
     } as StoreState
     ;(globalThis as unknown as { window: unknown }).window = {
       api: {
@@ -555,6 +563,43 @@ describe('connectPanePty', () => {
     }
   })
 
+  it('drops agent status without retaining when OSC 133 reports the command finished', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+
+    const capturedDataCallback: { current: ((data: string) => void) | null } = { current: null }
+    const transport = createMockTransport()
+    transport.connect.mockImplementation(async ({ callbacks }: { callbacks: ConnectCallbacks }) => {
+      capturedDataCallback.current = callbacks.onData ?? null
+      return 'pty-local-1'
+    })
+    transportFactoryQueue.push(transport)
+    mockStoreState = {
+      ...mockStoreState,
+      agentStatusByPaneKey: {
+        'tab-1:1': {
+          paneKey: 'tab-1:1',
+          state: 'done',
+          prompt: 'hi',
+          updatedAt: 1000,
+          stateStartedAt: 1000,
+          agentType: 'codex',
+          stateHistory: []
+        }
+      }
+    }
+
+    const pane = createPane(1)
+    const manager = createManager(1)
+    const deps = createDeps({ isVisibleRef: { current: false } })
+
+    connectPanePty(pane as never, manager as never, deps as never)
+
+    capturedDataCallback.current?.('\x1b]133;D;130\x07thebr ~/repo $ ')
+
+    expect(mockStoreState.dropAgentStatus).toHaveBeenCalledWith('tab-1:1')
+    expect(mockStoreState.removeAgentStatus).not.toHaveBeenCalled()
+  })
+
   it('reattaches a remounted split pane to its restored leaf PTY instead of the tab-level PTY', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const transport = createMockTransport()
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index 821888a3ac3..eac55170eba 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -26,6 +26,7 @@ import {
   waitForTerminalOutputParsed,
   writeTerminalOutput
 } from '@/lib/pane-manager/pane-terminal-output-scheduler'
+import { createTerminalCommandLifecycle } from './terminal-command-lifecycle'
 
 const pendingSpawnByPaneKey = new Map<string, Promise<string | null>>()
 const SSH_SESSION_EXPIRED_ERROR = 'SSH_SESSION_EXPIRED'
@@ -149,6 +150,19 @@ export function connectPanePty(
   // can track each Claude session independently without overwriting each other.
   const cacheKey = `${deps.tabId}:${pane.id}`
   const pendingSpawnKey = `${deps.tabId}:${paneLeafId(pane.id)}`
+  const commandLifecycle = createTerminalCommandLifecycle({
+    onCommandFinished: () => {
+      const state = useAppStore.getState()
+      const entry = state.agentStatusByPaneKey[cacheKey]
+      // Why: OSC 133 D marks the foreground shell command exiting. Remove the
+      // row without retaining a done snapshot; this section represents a live
+      // agent process, and the shell prompt means that process is gone.
+      if (entry) {
+        state.dropAgentStatus(cacheKey)
+      }
+    }
+  })
+  commandLifecycle.attachXtermConsumer(pane.terminal)
 
   const onExit = (ptyId: string): void => {
     deps.syncPanePtyLayoutBinding(pane.id, null)
@@ -299,17 +313,10 @@ export function connectPanePty(
     // the agent has exited. Clear any running cache timer so the sidebar doesn't
     // show a stale countdown for a tab that no longer has an active Claude session.
     deps.setCacheTimerStartedAt(cacheKey, null)
-    // Why: the agent process is gone, so its explicit status is no longer meaningful.
-    // Remove the entry so the hover UI does not show stale "working" for a dead agent.
-    //
-    // TODO(#1167): this path only fires on idle→shell title transitions, which
-    // means Ctrl+C'd `working` rows (Codex, Gemini, OpenCode — agents with no
-    // interrupt hook) linger until the 30-min AGENT_STATUS_STALE_AFTER_MS TTL
-    // decays them to idle or the pane/tab is closed. PR #1167 replaces this
-    // heuristic with authoritative foreground-process tracking in main so the
-    // row drops within 2s of the CLI process exiting. See branch
-    // brennanb2025/foreground-process-agent-exit.
-    useAppStore.getState().removeAgentStatus(cacheKey)
+    // Why: do not let terminal-title reversion own agent-status lifecycle.
+    // Explicit hooks and OSC 133 command-finished marks are the reliable
+    // signals; title changes can race normal "done" states and make agents
+    // look like they vanished as soon as they finished responding.
   }
   // Why: inject ORCA_PANE_KEY so global Claude/Codex hooks can attribute their
   // callbacks to the correct Orca pane without resolving worktrees from cwd.
@@ -641,6 +648,7 @@ export function connectPanePty(
     }
 
     const dataCallback = (data: string): void => {
+      commandLifecycle.handlePtyData(data)
       if (terminalOutputPrefersDomRenderer(data)) {
         manager.markPaneHasComplexScriptOutput(pane.id)
       }
@@ -1253,6 +1261,7 @@ export function connectPanePty(
         cancelAnimationFrame(pendingGeometryReportRaf)
         pendingGeometryReportRaf = null
       }
+      commandLifecycle.dispose()
     }
   }
 }
diff --git a/src/renderer/src/components/terminal-pane/terminal-command-lifecycle.test.ts b/src/renderer/src/components/terminal-pane/terminal-command-lifecycle.test.ts
new file mode 100644
index 00000000000..cf703930e61
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-command-lifecycle.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createTerminalCommandLifecycle } from './terminal-command-lifecycle'
+
+describe('createTerminalCommandLifecycle', () => {
+  it('emits commandFinished for OSC 133 D with best-effort exit codes', () => {
+    const onCommandFinished = vi.fn()
+    const lifecycle = createTerminalCommandLifecycle({ onCommandFinished })
+
+    lifecycle.handlePtyData('before\x1b]133;A\x07prompt\x1b]133;B\x07')
+    lifecycle.handlePtyData('\x1b]133;C\x07running\x1b]133;D;0\x07')
+    lifecycle.handlePtyData('\x1b]133;D;130\x07')
+    lifecycle.handlePtyData('\x1b]133;D;not-a-number\x07')
+    lifecycle.handlePtyData('\x1b]133;D\x07')
+
+    expect(onCommandFinished).toHaveBeenCalledTimes(4)
+    expect(onCommandFinished).toHaveBeenNthCalledWith(1, 0)
+    expect(onCommandFinished).toHaveBeenNthCalledWith(2, 130)
+    expect(onCommandFinished).toHaveBeenNthCalledWith(3, null)
+    expect(onCommandFinished).toHaveBeenNthCalledWith(4, null)
+  })
+
+  it('detects OSC 133 sequences split across PTY chunks', () => {
+    const onCommandFinished = vi.fn()
+    const lifecycle = createTerminalCommandLifecycle({ onCommandFinished })
+
+    lifecycle.handlePtyData('chunk\x1b]133')
+    lifecycle.handlePtyData(';D;42')
+    lifecycle.handlePtyData('\x07next')
+
+    expect(onCommandFinished).toHaveBeenCalledOnce()
+    expect(onCommandFinished).toHaveBeenCalledWith(42)
+  })
+
+  it('carries partial OSC 133 prefixes after normal output', () => {
+    const onCommandFinished = vi.fn()
+    const lifecycle = createTerminalCommandLifecycle({ onCommandFinished })
+
+    lifecycle.handlePtyData('output\x1b]')
+    lifecycle.handlePtyData('133;D;0\x07')
+
+    expect(onCommandFinished).toHaveBeenCalledOnce()
+    expect(onCommandFinished).toHaveBeenCalledWith(0)
+  })
+
+  it('supports ESC backslash string terminators', () => {
+    const onCommandFinished = vi.fn()
+    const lifecycle = createTerminalCommandLifecycle({ onCommandFinished })
+
+    lifecycle.handlePtyData('\x1b]133;D;7\x1b\\')
+
+    expect(onCommandFinished).toHaveBeenCalledWith(7)
+  })
+
+  it('registers an xterm OSC consumer without emitting lifecycle events', () => {
+    const onCommandFinished = vi.fn()
+    const dispose = vi.fn()
+    const registerOscHandler = vi.fn((_code: number, _handler: (payload: string) => boolean) => ({
+      dispose
+    }))
+    const lifecycle = createTerminalCommandLifecycle({ onCommandFinished })
+
+    const disposable = lifecycle.attachXtermConsumer({
+      parser: { registerOscHandler }
+    } as never)
+
+    expect(registerOscHandler).toHaveBeenCalledWith(133, expect.any(Function))
+    const handler = registerOscHandler.mock.calls[0][1]
+    expect(handler('D;0')).toBe(true)
+    expect(onCommandFinished).not.toHaveBeenCalled()
+
+    disposable.dispose()
+    expect(dispose).toHaveBeenCalledOnce()
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-command-lifecycle.ts b/src/renderer/src/components/terminal-pane/terminal-command-lifecycle.ts
new file mode 100644
index 00000000000..3fb103efeac
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-command-lifecycle.ts
@@ -0,0 +1,102 @@
+import type { Terminal, IDisposable } from '@xterm/xterm'
+
+type TerminalCommandLifecycleOptions = {
+  onCommandFinished: (bestEffortExitCode: number | null) => void
+}
+
+type OscTerminator = {
+  index: number
+  length: number
+}
+
+const OSC_133_PREFIX = '\x1b]133;'
+const MAX_OSC_CARRY_LENGTH = 4096
+
+function findOscTerminator(data: string, startIndex: number): OscTerminator | null {
+  const bel = data.indexOf('\x07', startIndex)
+  const st = data.indexOf('\x1b\\', startIndex)
+
+  if (bel === -1 && st === -1) {
+    return null
+  }
+  if (bel !== -1 && (st === -1 || bel < st)) {
+    return { index: bel, length: 1 }
+  }
+  return { index: st, length: 2 }
+}
+
+function parseBestEffortExitCode(value: string | undefined): number | null {
+  if (!value) {
+    return null
+  }
+  const parsed = Number.parseInt(value, 10)
+  return Number.isNaN(parsed) ? null : parsed
+}
+
+function findPrefixCarry(data: string): string {
+  const maxCarryLength = Math.min(data.length, OSC_133_PREFIX.length - 1)
+  for (let length = maxCarryLength; length > 0; length -= 1) {
+    const suffix = data.slice(data.length - length)
+    if (OSC_133_PREFIX.startsWith(suffix)) {
+      return suffix
+    }
+  }
+  return ''
+}
+
+export function createTerminalCommandLifecycle(options: TerminalCommandLifecycleOptions): {
+  handlePtyData: (data: string) => void
+  attachXtermConsumer: (terminal: Terminal) => IDisposable
+  dispose: () => void
+} {
+  let carry = ''
+  const disposables: IDisposable[] = []
+
+  const handleOsc133 = (payload: string): void => {
+    const [sequence, exitCode] = payload.split(';')
+    if (sequence === 'D') {
+      options.onCommandFinished(parseBestEffortExitCode(exitCode))
+    }
+  }
+
+  const handlePtyData = (data: string): void => {
+    let combined = carry + data
+    carry = ''
+
+    while (combined.length > 0) {
+      const start = combined.indexOf(OSC_133_PREFIX)
+      if (start === -1) {
+        carry = findPrefixCarry(combined)
+        return
+      }
+
+      const payloadStart = start + OSC_133_PREFIX.length
+      const terminator = findOscTerminator(combined, payloadStart)
+      if (!terminator) {
+        carry = combined.slice(start)
+        if (carry.length > MAX_OSC_CARRY_LENGTH) {
+          carry = carry.slice(carry.length - MAX_OSC_CARRY_LENGTH)
+        }
+        return
+      }
+
+      handleOsc133(combined.slice(payloadStart, terminator.index))
+      combined = combined.slice(terminator.index + terminator.length)
+    }
+  }
+
+  return {
+    handlePtyData,
+    attachXtermConsumer(terminal) {
+      const disposable = terminal.parser.registerOscHandler(133, () => true)
+      disposables.push(disposable)
+      return disposable
+    },
+    dispose() {
+      carry = ''
+      for (const disposable of disposables.splice(0)) {
+        disposable.dispose()
+      }
+    }
+  }
+}

From f708e57c507867b7f0f8fa99bfb29afa1a773128 Mon Sep 17 00:00:00 2001
From: "buf0-bot[bot]" <252831055+buf0-bot[bot]@users.noreply.github.com>
Date: Thu, 14 May 2026 20:58:15 -0700
Subject: [PATCH 13/82] fix: pr-bug-scan validated finding from #1877 (#1891)

Co-authored-by: orca-bug-scan-bot <orca-bug-scan-bot@stably.ai>
---
 .../status-bar/WorkspaceSpaceManagerPanel.tsx     | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
index 9c8452003da..ce8ab9885e1 100644
--- a/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
+++ b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
@@ -486,20 +486,27 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
     if (selectedDeletableIds.length === 0) {
       return
     }
-    const started = runWorktreeBatchDelete(selectedDeletableIds, {
+    runWorktreeBatchDelete(selectedDeletableIds, {
       onDeleted: (deletedIds) => {
         removeWorkspaceSpaceWorktrees(deletedIds)
         setInspectedWorktreeId((current) =>
           current && deletedIds.includes(current) ? null : current
         )
+        setSelectedIds((current) => {
+          if (deletedIds.length === 0) {
+            return current
+          }
+          const next = new Set(current)
+          for (const id of deletedIds) {
+            next.delete(id)
+          }
+          return next
+        })
         toast.success(deletedIds.length === 1 ? 'Workspace deleted' : 'Workspaces deleted', {
           description: `${deletedIds.length} ${deletedIds.length === 1 ? 'workspace' : 'workspaces'} removed from Space.`
         })
       }
     })
-    if (started) {
-      setSelectedIds(new Set<string>())
-    }
   }
 
   return (

From 53150f6022bb0d146536a4ecb98653383b9e342a Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Thu, 14 May 2026 22:05:19 -0700
Subject: [PATCH 14/82] fix: address review findings (#1895)

---
 package.json                                  |   4 +
 pnpm-lock.yaml                                |  12 +
 src/renderer/src/assets/markdown-preview.css  | 118 ++++++++
 .../src/assets/rich-markdown-editor.css       |  12 +
 .../src/components/editor/EditorContent.tsx   |  12 +
 .../src/components/editor/EditorPanel.tsx     |  44 ++-
 .../components/editor/EditorViewToggle.tsx    |  78 +++---
 .../src/components/editor/MarkdownPreview.tsx | 254 ++++++++++--------
 .../editor/MarkdownTableOfContentsPanel.tsx   |  73 +++++
 .../components/editor/RichMarkdownEditor.tsx  | 175 +++++++-----
 .../editor/markdown-table-of-contents.test.ts | 101 +++++++
 .../editor/markdown-table-of-contents.ts      |  93 +++++++
 12 files changed, 761 insertions(+), 215 deletions(-)
 create mode 100644 src/renderer/src/components/editor/MarkdownTableOfContentsPanel.tsx
 create mode 100644 src/renderer/src/components/editor/markdown-table-of-contents.test.ts
 create mode 100644 src/renderer/src/components/editor/markdown-table-of-contents.ts

diff --git a/package.json b/package.json
index 974f99032fb..18e27bb409d 100644
--- a/package.json
+++ b/package.json
@@ -87,12 +87,14 @@
     "cmdk": "^1.1.1",
     "dompurify": "^3.4.2",
     "electron-updater": "^6.8.3",
+    "entities": "^6.0.1",
     "github-slugger": "^2.0.0",
     "hosted-git-info": "^9.0.3",
     "html-to-image": "^1.11.13",
     "katex": "^0.16.45",
     "lowlight": "^3.3.0",
     "lucide-react": "^0.577.0",
+    "mdast-util-to-string": "^4.0.0",
     "mermaid": "^11.15.0",
     "monaco-editor": "^0.55.1",
     "node-pty": "^1.1.0",
@@ -110,6 +112,7 @@
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
     "shadcn": "^4.7.0",
     "sherpa-onnx": "1.12.37",
     "simple-git": "^3.36.0",
@@ -118,6 +121,7 @@
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0",
     "tweetnacl": "^1.0.3",
+    "unified": "^11.0.5",
     "ws": "^8.20.0",
     "zod": "~4.4.3",
     "zustand": "^5.0.13"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8abdd97ee2f..d40d37323d0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -136,6 +136,9 @@ importers:
       electron-updater:
         specifier: ^6.8.3
         version: 6.8.3
+      entities:
+        specifier: ^6.0.1
+        version: 6.0.1
       github-slugger:
         specifier: ^2.0.0
         version: 2.0.0
@@ -154,6 +157,9 @@ importers:
       lucide-react:
         specifier: ^0.577.0
         version: 0.577.0(react@19.2.5)
+      mdast-util-to-string:
+        specifier: ^4.0.0
+        version: 4.0.0
       mermaid:
         specifier: ^11.15.0
         version: 11.15.0
@@ -205,6 +211,9 @@ importers:
       remark-math:
         specifier: ^6.0.0
         version: 6.0.0
+      remark-parse:
+        specifier: ^11.0.0
+        version: 11.0.0
       shadcn:
         specifier: ^4.7.0
         version: 4.7.0(@types/node@25.6.0)(typescript@5.9.3)
@@ -229,6 +238,9 @@ importers:
       tweetnacl:
         specifier: ^1.0.3
         version: 1.0.3
+      unified:
+        specifier: ^11.0.5
+        version: 11.0.5
       ws:
         specifier: ^8.20.0
         version: 8.20.0
diff --git a/src/renderer/src/assets/markdown-preview.css b/src/renderer/src/assets/markdown-preview.css
index df64ae4d542..1333e713e42 100644
--- a/src/renderer/src/assets/markdown-preview.css
+++ b/src/renderer/src/assets/markdown-preview.css
@@ -5,6 +5,17 @@
   padding: 24px 32px;
   font-size: inherit;
   line-height: 1.7;
+  min-width: 0;
+  flex: 1;
+}
+
+.markdown-preview-shell {
+  position: relative;
+  display: flex;
+  min-height: 0;
+  height: 100%;
+  min-width: 0;
+  container-type: inline-size;
 }
 
 .markdown-preview:focus-visible {
@@ -81,6 +92,113 @@
   color: var(--foreground);
 }
 
+.markdown-toc-panel {
+  display: flex;
+  width: 240px;
+  min-width: 200px;
+  max-width: 30%;
+  flex-shrink: 0;
+  flex-direction: column;
+  border-left: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+  background: color-mix(in srgb, var(--background) 88%, var(--editor-surface));
+}
+
+.markdown-toc-header {
+  display: flex;
+  min-height: 40px;
+  min-width: 0;
+  align-items: center;
+  gap: 8px;
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+  padding: 0 10px 0 12px;
+  color: var(--muted-foreground);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.markdown-toc-header > svg,
+.markdown-toc-header > button {
+  flex-shrink: 0;
+}
+
+.markdown-toc-header > span {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.markdown-toc-list {
+  min-height: 0;
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px;
+}
+
+.markdown-toc-row {
+  display: flex;
+  width: 100%;
+  min-width: 0;
+  align-items: center;
+  gap: 7px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  padding-top: 6px;
+  padding-right: 8px;
+  padding-bottom: 6px;
+  color: var(--foreground);
+  font-size: 12px;
+  line-height: 1.25;
+  text-align: left;
+}
+
+.markdown-toc-row:hover {
+  background: var(--accent);
+}
+
+.markdown-toc-level {
+  flex-shrink: 0;
+  color: var(--muted-foreground);
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+}
+
+.markdown-toc-title {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.markdown-toc-empty {
+  padding: 8px 6px;
+  color: var(--muted-foreground);
+  font-size: 12px;
+}
+
+@media (max-width: 900px) {
+  .markdown-toc-panel {
+    width: 200px;
+    max-width: 42%;
+  }
+}
+
+@container (max-width: 560px) {
+  .markdown-toc-panel {
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 30;
+    width: min(240px, 72cqw);
+    min-width: 0;
+    max-width: calc(100cqw - 44px);
+    box-shadow: -10px 0 24px rgb(0 0 0 / 0.14);
+  }
+}
+
 .markdown-preview-search-match {
   padding: 0;
   border-radius: 2px;
diff --git a/src/renderer/src/assets/rich-markdown-editor.css b/src/renderer/src/assets/rich-markdown-editor.css
index 3812a5dd17f..7f2b8fbe62c 100644
--- a/src/renderer/src/assets/rich-markdown-editor.css
+++ b/src/renderer/src/assets/rich-markdown-editor.css
@@ -5,10 +5,22 @@
   display: flex;
   min-height: 0;
   height: 100%;
+  min-width: 0;
+  flex: 1;
   flex-direction: column;
   background: var(--editor-surface);
 }
 
+.rich-markdown-editor-layout {
+  position: relative;
+  display: flex;
+  min-height: 0;
+  height: 100%;
+  min-width: 0;
+  background: var(--editor-surface);
+  container-type: inline-size;
+}
+
 .rich-markdown-editor-toolbar {
   display: flex;
   align-items: center;
diff --git a/src/renderer/src/components/editor/EditorContent.tsx b/src/renderer/src/components/editor/EditorContent.tsx
index c778ddcc215..57ddc16864f 100644
--- a/src/renderer/src/components/editor/EditorContent.tsx
+++ b/src/renderer/src/components/editor/EditorContent.tsx
@@ -83,6 +83,8 @@ export function EditorContent({
   mdViewMode,
   isChangesMode,
   sideBySide,
+  showMarkdownTableOfContents = false,
+  onCloseMarkdownTableOfContents = () => {},
   pendingEditorReveal,
   handleContentChange,
   handleDirtyStateHint,
@@ -103,6 +105,8 @@ export function EditorContent({
   mdViewMode: MarkdownViewMode
   isChangesMode: boolean
   sideBySide: boolean
+  showMarkdownTableOfContents?: boolean
+  onCloseMarkdownTableOfContents?: () => void
   pendingEditorReveal: {
     filePath?: string
     line?: number
@@ -239,6 +243,8 @@ export function EditorContent({
                 onSave={onSaveWithFm}
                 onOpenDocLink={md.onOpenDocLink}
                 markdownDocuments={md.markdownDocuments}
+                showTableOfContents={showMarkdownTableOfContents}
+                onCloseTableOfContents={onCloseMarkdownTableOfContents}
                 // Why: render the front-matter banner below the editor toolbar
                 // (inside the editor shell) so formatting controls remain at
                 // the top of the pane — the banner is read-only context, not
@@ -270,6 +276,8 @@ export function EditorContent({
               content={currentContent}
               filePath={activeFile.filePath}
               scrollCacheKey={`${editorViewStateKey}:preview`}
+              showTableOfContents={showMarkdownTableOfContents}
+              onCloseTableOfContents={onCloseMarkdownTableOfContents}
               {...md.previewProps}
             />
           </div>
@@ -357,6 +365,8 @@ export function EditorContent({
           filePath={activeFile.filePath}
           scrollCacheKey={markdownPreviewViewStateKey}
           initialAnchor={activeFile.markdownPreviewAnchor ?? null}
+          showTableOfContents={showMarkdownTableOfContents}
+          onCloseTableOfContents={onCloseMarkdownTableOfContents}
           {...md.previewProps}
         />
       </div>
@@ -498,6 +508,8 @@ export function EditorContent({
             content={modifiedDiffContent}
             filePath={activeFile.filePath}
             scrollCacheKey={`${diffViewStateKey}:preview`}
+            showTableOfContents={showMarkdownTableOfContents}
+            onCloseTableOfContents={onCloseMarkdownTableOfContents}
             {...md.previewProps}
           />
         </div>
diff --git a/src/renderer/src/components/editor/EditorPanel.tsx b/src/renderer/src/components/editor/EditorPanel.tsx
index 43af45fc945..f7067db3144 100644
--- a/src/renderer/src/components/editor/EditorPanel.tsx
+++ b/src/renderer/src/components/editor/EditorPanel.tsx
@@ -5,7 +5,16 @@ across multiple components. Autosave now lives in a smaller headless controller
 so hidden editor UI no longer participates in shutdown. */
 import React, { useCallback, useEffect, useRef, useState, Suspense } from 'react'
 import * as monaco from 'monaco-editor'
-import { Columns2, Copy, Eye, ExternalLink, FileText, MoreHorizontal, Rows2 } from 'lucide-react'
+import {
+  Columns2,
+  Copy,
+  Eye,
+  ExternalLink,
+  FileText,
+  ListTree,
+  MoreHorizontal,
+  Rows2
+} from 'lucide-react'
 import { useAppStore } from '@/store'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
 import { getConnectionId } from '@/lib/connection-context'
@@ -211,6 +220,7 @@ function EditorPanelInner({
   const [copiedPathToast, setCopiedPathToast] = useState<{ fileId: string; token: number } | null>(
     null
   )
+  const [showMarkdownTableOfContents, setShowMarkdownTableOfContents] = useState(false)
   const [renameDialogFileId, setRenameDialogFileId] = useState<string | null>(null)
   const renameDialogFile = renameDialogFileId
     ? openFiles.find((f) => f.id === renameDialogFileId)
@@ -1129,6 +1139,9 @@ function EditorPanelInner({
     : hasViewModeToggle
       ? mdViewMode
       : 'edit'
+  const isMarkdownTableOfContentsDisabled = hasViewModeToggle && mdViewMode === 'source'
+  const canShowMarkdownTableOfContents =
+    isMarkdown && (hasViewModeToggle || activeFile.mode === 'markdown-preview')
   const canShowMarkdownPreview = canOpenMarkdownPreview({
     language: resolvedLanguage,
     mode: activeFile.mode,
@@ -1312,6 +1325,33 @@ function EditorPanelInner({
               }
             />
           )}
+          {canShowMarkdownTableOfContents && (
+            <TooltipProvider delayDuration={300}>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <button
+                    type="button"
+                    className={`p-1 rounded hover:bg-accent hover:text-foreground transition-colors flex-shrink-0 disabled:opacity-50 disabled:hover:bg-transparent disabled:hover:text-muted-foreground ${
+                      showMarkdownTableOfContents && !isMarkdownTableOfContentsDisabled
+                        ? 'bg-accent text-foreground'
+                        : 'text-muted-foreground'
+                    }`}
+                    onClick={() => setShowMarkdownTableOfContents((shown) => !shown)}
+                    disabled={isMarkdownTableOfContentsDisabled}
+                    aria-label="Table of Contents"
+                    aria-pressed={showMarkdownTableOfContents}
+                  >
+                    <ListTree size={14} />
+                  </button>
+                </TooltipTrigger>
+                <TooltipContent side="bottom" sideOffset={4}>
+                  {isMarkdownTableOfContentsDisabled
+                    ? 'Table of Contents is available in rich or preview mode'
+                    : 'Table of Contents'}
+                </TooltipContent>
+              </Tooltip>
+            </TooltipProvider>
+          )}
           {hasViewModeToggle && isMarkdown && (
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
@@ -1366,6 +1406,8 @@ function EditorPanelInner({
           handleDirtyStateHint={handleDirtyStateHint}
           handleSave={handleSave}
           reloadFileContent={reloadFileContent}
+          showMarkdownTableOfContents={showMarkdownTableOfContents}
+          onCloseMarkdownTableOfContents={() => setShowMarkdownTableOfContents(false)}
         />
       </Suspense>
       <UntitledFileRenameDialog
diff --git a/src/renderer/src/components/editor/EditorViewToggle.tsx b/src/renderer/src/components/editor/EditorViewToggle.tsx
index d394f8baabd..c208b0cc3a1 100644
--- a/src/renderer/src/components/editor/EditorViewToggle.tsx
+++ b/src/renderer/src/components/editor/EditorViewToggle.tsx
@@ -10,6 +10,7 @@ import {
   type LucideIcon
 } from 'lucide-react'
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
 import type { MarkdownViewMode } from '@/store/slices/editor'
 
 // Why: 'changes' is not a MarkdownViewMode in the store — it lives on the
@@ -82,39 +83,48 @@ export default function EditorViewToggle({
   metadataOverride
 }: EditorViewToggleProps): React.JSX.Element {
   return (
-    <ToggleGroup
-      type="single"
-      size="sm"
-      className="h-6 [&_[data-slot=toggle-group-item]]:h-7 [&_[data-slot=toggle-group-item]]:min-w-5 [&_[data-slot=toggle-group-item]]:px-2.5"
-      variant="outline"
-      value={value}
-      onValueChange={(v) => {
-        if (v) {
-          onChange(v as EditorToggleValue)
-        }
-      }}
-    >
-      {modes.map((viewMode) => {
-        // Why: metadataOverride is keyed by MarkdownViewMode (source/rich/preview)
-        // because only those slots have language-specific presentation variants
-        // (e.g. CSV's "Table" label on the 'rich' slot). 'edit'/'changes' are
-        // orthogonal toggle values and always use the default metadata.
-        const override = (
-          metadataOverride as Partial<Record<EditorToggleValue, ViewModeMetadata>> | undefined
-        )?.[viewMode]
-        const metadata = override ?? DEFAULT_VIEW_MODE_METADATA[viewMode]
-        const Icon = metadata.icon
-        return (
-          <ToggleGroupItem
-            key={viewMode}
-            value={viewMode}
-            aria-label={metadata.label}
-            title={metadata.title ?? metadata.label}
-          >
-            <Icon className="h-3 w-3" />
-          </ToggleGroupItem>
-        )
-      })}
-    </ToggleGroup>
+    <TooltipProvider delayDuration={300}>
+      <ToggleGroup
+        type="single"
+        size="sm"
+        className="h-6 [&_[data-slot=toggle-group-item]]:h-7 [&_[data-slot=toggle-group-item]]:min-w-5 [&_[data-slot=toggle-group-item]]:px-2.5"
+        variant="outline"
+        value={value}
+        onValueChange={(v) => {
+          if (v) {
+            onChange(v as EditorToggleValue)
+          }
+        }}
+      >
+        {modes.map((viewMode) => {
+          // Why: metadataOverride is keyed by MarkdownViewMode (source/rich/preview)
+          // because only those slots have language-specific presentation variants
+          // (e.g. CSV's "Table" label on the 'rich' slot). 'edit'/'changes' are
+          // orthogonal toggle values and always use the default metadata.
+          const override = (
+            metadataOverride as Partial<Record<EditorToggleValue, ViewModeMetadata>> | undefined
+          )?.[viewMode]
+          const metadata = override ?? DEFAULT_VIEW_MODE_METADATA[viewMode]
+          const Icon = metadata.icon
+          const tooltipLabel = metadata.title ?? metadata.label
+          return (
+            <Tooltip key={viewMode}>
+              <TooltipTrigger asChild>
+                <ToggleGroupItem
+                  value={viewMode}
+                  aria-label={metadata.label}
+                  className="data-[state=on]:border-primary data-[state=on]:bg-primary data-[state=on]:text-primary-foreground data-[state=on]:shadow-xs data-[state=on]:hover:bg-primary/90 data-[state=on]:hover:text-primary-foreground"
+                >
+                  <Icon className="h-3 w-3" />
+                </ToggleGroupItem>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={4}>
+                {tooltipLabel}
+              </TooltipContent>
+            </Tooltip>
+          )
+        })}
+      </ToggleGroup>
+    </TooltipProvider>
   )
 }
diff --git a/src/renderer/src/components/editor/MarkdownPreview.tsx b/src/renderer/src/components/editor/MarkdownPreview.tsx
index d2d8b1638bc..bebadac8475 100644
--- a/src/renderer/src/components/editor/MarkdownPreview.tsx
+++ b/src/renderer/src/components/editor/MarkdownPreview.tsx
@@ -49,12 +49,16 @@ import {
 import { usePreserveSectionDuringExternalEdit } from './usePreserveSectionDuringExternalEdit'
 import { openHttpLink } from '@/lib/http-link-routing'
 import { markdownPreviewUrlTransform } from './markdown-preview-url-transform'
+import { buildMarkdownTableOfContents } from './markdown-table-of-contents'
+import { MarkdownTableOfContentsPanel } from './MarkdownTableOfContentsPanel'
 
 type MarkdownPreviewProps = {
   content: string
   filePath: string
   scrollCacheKey: string
   initialAnchor?: string | null
+  showTableOfContents?: boolean
+  onCloseTableOfContents?: () => void
   markdownDocuments?: MarkdownDocument[]
   onOpenDocument?: (document: MarkdownDocument) => void | Promise<void>
 }
@@ -163,6 +167,8 @@ export default function MarkdownPreview({
   filePath,
   scrollCacheKey,
   initialAnchor = null,
+  showTableOfContents = false,
+  onCloseTableOfContents,
   markdownDocuments = [],
   onOpenDocument
 }: MarkdownPreviewProps): React.JSX.Element {
@@ -194,6 +200,10 @@ export default function MarkdownPreview({
   const renderedContent = usePreserveSectionDuringExternalEdit(content, bodyRef)
 
   const frontMatter = useMemo(() => extractFrontMatter(renderedContent), [renderedContent])
+  const tableOfContentsItems = useMemo(
+    () => buildMarkdownTableOfContents(renderedContent),
+    [renderedContent]
+  )
   const markdownDocumentIndex = useMemo(
     () => createMarkdownDocumentIndex(markdownDocuments),
     [markdownDocuments]
@@ -335,6 +345,13 @@ export default function MarkdownPreview({
     return true
   }, [])
 
+  const navigateToTableOfContentsItem = useCallback(
+    (id: string): void => {
+      scrollToAnchor(id)
+    },
+    [scrollToAnchor]
+  )
+
   useEffect(() => {
     if (isSearchOpen) {
       inputRef.current?.focus()
@@ -748,125 +765,134 @@ export default function MarkdownPreview({
   ])
 
   return (
-    <div
-      ref={rootRef}
-      tabIndex={0}
-      style={{ fontSize: `${editorFontSize}px` }}
-      className={`markdown-preview h-full min-h-0 overflow-auto scrollbar-editor ${isDark ? 'markdown-dark' : 'markdown-light'}`}
-    >
-      {isSearchOpen ? (
-        <div className="markdown-preview-search" onKeyDown={(event) => event.stopPropagation()}>
-          <div className="markdown-preview-search-field">
-            <Input
-              ref={inputRef}
-              value={query}
-              onChange={(event) => setQuery(event.target.value)}
-              onKeyDown={(event) => {
-                if (event.key === 'Enter' && event.shiftKey) {
-                  event.preventDefault()
-                  moveToMatch(-1)
-                  return
-                }
-                if (event.key === 'Enter') {
-                  event.preventDefault()
-                  moveToMatch(1)
-                  return
-                }
-                if (event.key === 'Escape') {
-                  event.preventDefault()
-                  closeSearch()
-                  rootRef.current?.focus()
-                }
-              }}
-              placeholder="Find in preview"
-              className="markdown-preview-search-input h-7 !border-0 bg-transparent px-2 shadow-none focus-visible:!border-0 focus-visible:ring-0"
-              aria-label="Find in markdown preview"
-            />
+    <div className="markdown-preview-shell">
+      <div
+        ref={rootRef}
+        tabIndex={0}
+        style={{ fontSize: `${editorFontSize}px` }}
+        className={`markdown-preview h-full min-h-0 overflow-auto scrollbar-editor ${isDark ? 'markdown-dark' : 'markdown-light'}`}
+      >
+        {isSearchOpen ? (
+          <div className="markdown-preview-search" onKeyDown={(event) => event.stopPropagation()}>
+            <div className="markdown-preview-search-field">
+              <Input
+                ref={inputRef}
+                value={query}
+                onChange={(event) => setQuery(event.target.value)}
+                onKeyDown={(event) => {
+                  if (event.key === 'Enter' && event.shiftKey) {
+                    event.preventDefault()
+                    moveToMatch(-1)
+                    return
+                  }
+                  if (event.key === 'Enter') {
+                    event.preventDefault()
+                    moveToMatch(1)
+                    return
+                  }
+                  if (event.key === 'Escape') {
+                    event.preventDefault()
+                    closeSearch()
+                    rootRef.current?.focus()
+                  }
+                }}
+                placeholder="Find in preview"
+                className="markdown-preview-search-input h-7 !border-0 bg-transparent px-2 shadow-none focus-visible:!border-0 focus-visible:ring-0"
+                aria-label="Find in markdown preview"
+              />
+            </div>
+            <div className="markdown-preview-search-status">
+              {query && matchCount === 0
+                ? 'No results'
+                : `${matchCount === 0 ? 0 : activeMatchIndex + 1}/${matchCount}`}
+            </div>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-xs"
+              onClick={() => moveToMatch(-1)}
+              disabled={matchCount === 0}
+              title="Previous match"
+              aria-label="Previous match"
+              className="markdown-preview-search-button"
+            >
+              <ChevronUp size={14} />
+            </Button>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-xs"
+              onClick={() => moveToMatch(1)}
+              disabled={matchCount === 0}
+              title="Next match"
+              aria-label="Next match"
+              className="markdown-preview-search-button"
+            >
+              <ChevronDown size={14} />
+            </Button>
+            <div className="markdown-preview-search-divider" />
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-xs"
+              onClick={closeSearch}
+              title="Close search"
+              aria-label="Close search"
+              className="markdown-preview-search-button"
+            >
+              <X size={14} />
+            </Button>
           </div>
-          <div className="markdown-preview-search-status">
-            {query && matchCount === 0
-              ? 'No results'
-              : `${matchCount === 0 ? 0 : activeMatchIndex + 1}/${matchCount}`}
-          </div>
-          <Button
-            type="button"
-            variant="ghost"
-            size="icon-xs"
-            onClick={() => moveToMatch(-1)}
-            disabled={matchCount === 0}
-            title="Previous match"
-            aria-label="Previous match"
-            className="markdown-preview-search-button"
-          >
-            <ChevronUp size={14} />
-          </Button>
-          <Button
-            type="button"
-            variant="ghost"
-            size="icon-xs"
-            onClick={() => moveToMatch(1)}
-            disabled={matchCount === 0}
-            title="Next match"
-            aria-label="Next match"
-            className="markdown-preview-search-button"
-          >
-            <ChevronDown size={14} />
-          </Button>
-          <div className="markdown-preview-search-divider" />
-          <Button
-            type="button"
-            variant="ghost"
-            size="icon-xs"
-            onClick={closeSearch}
-            title="Close search"
-            aria-label="Close search"
-            className="markdown-preview-search-button"
-          >
-            <X size={14} />
-          </Button>
-        </div>
-      ) : null}
-      <div ref={bodyRef} className="markdown-body">
-        {/* Why: remarkFrontmatter silently strips front-matter from rendered
+        ) : null}
+        <div ref={bodyRef} className="markdown-body">
+          {/* Why: remarkFrontmatter silently strips front-matter from rendered
         output. We extract it ourselves and render it as a styled code block so
         the user can see the metadata in preview mode. */}
-        {frontMatter && (
-          <div className="mb-4 rounded border border-border/60 bg-muted/40 px-3 py-2">
-            <div className="mb-1 text-[10px] font-medium uppercase tracking-wider text-muted-foreground">
-              Front Matter
+          {frontMatter && (
+            <div className="mb-4 rounded border border-border/60 bg-muted/40 px-3 py-2">
+              <div className="mb-1 text-[10px] font-medium uppercase tracking-wider text-muted-foreground">
+                Front Matter
+              </div>
+              <pre className="max-h-48 overflow-auto whitespace-pre-wrap text-xs text-muted-foreground font-mono scrollbar-editor">
+                {frontMatterInner}
+              </pre>
             </div>
-            <pre className="max-h-48 overflow-auto whitespace-pre-wrap text-xs text-muted-foreground font-mono scrollbar-editor">
-              {frontMatterInner}
-            </pre>
-          </div>
-        )}
-        <Markdown
-          components={components}
-          // Why: react-markdown filters file:// after rehype-sanitize; preview
-          // click handlers need the target so they can authorize and open it.
-          urlTransform={markdownPreviewUrlTransform}
-          remarkPlugins={[
-            remarkGfm,
-            remarkBreaks,
-            remarkFrontmatter,
-            remarkMath,
-            remarkMarkdownDocLinks
-          ]}
-          // Why: raw HTML must be sanitized before any trusted renderer expands
-          // it into richer DOM. Running KaTeX and syntax highlighting after
-          // sanitize preserves VS Code-style math/code rendering without having
-          // to whitelist KaTeX's generated markup in the user-content schema.
-          rehypePlugins={[
-            rehypeRaw,
-            [rehypeSanitize, markdownPreviewSanitizeSchema],
-            rehypeSlug,
-            rehypeHighlight,
-            rehypeKatex
-          ]}
-        >
-          {renderedContent}
-        </Markdown>
+          )}
+          <Markdown
+            components={components}
+            // Why: react-markdown filters file:// after rehype-sanitize; preview
+            // click handlers need the target so they can authorize and open it.
+            urlTransform={markdownPreviewUrlTransform}
+            remarkPlugins={[
+              remarkGfm,
+              remarkBreaks,
+              remarkFrontmatter,
+              remarkMath,
+              remarkMarkdownDocLinks
+            ]}
+            // Why: raw HTML must be sanitized before any trusted renderer expands
+            // it into richer DOM. Running KaTeX and syntax highlighting after
+            // sanitize preserves VS Code-style math/code rendering without having
+            // to whitelist KaTeX's generated markup in the user-content schema.
+            rehypePlugins={[
+              rehypeRaw,
+              [rehypeSanitize, markdownPreviewSanitizeSchema],
+              rehypeSlug,
+              rehypeHighlight,
+              rehypeKatex
+            ]}
+          >
+            {renderedContent}
+          </Markdown>
+        </div>
       </div>
+      {showTableOfContents ? (
+        <MarkdownTableOfContentsPanel
+          items={tableOfContentsItems}
+          onClose={onCloseTableOfContents ?? (() => {})}
+          onNavigate={navigateToTableOfContentsItem}
+        />
+      ) : null}
     </div>
   )
 }
diff --git a/src/renderer/src/components/editor/MarkdownTableOfContentsPanel.tsx b/src/renderer/src/components/editor/MarkdownTableOfContentsPanel.tsx
new file mode 100644
index 00000000000..2f69ecec055
--- /dev/null
+++ b/src/renderer/src/components/editor/MarkdownTableOfContentsPanel.tsx
@@ -0,0 +1,73 @@
+import React from 'react'
+import { ListTree, X } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import type { MarkdownTocItem } from './markdown-table-of-contents'
+
+type MarkdownTableOfContentsPanelProps = {
+  items: MarkdownTocItem[]
+  onClose: () => void
+  onNavigate: (id: string) => void
+}
+
+function MarkdownTocRow({
+  depth,
+  item,
+  onNavigate
+}: {
+  depth: number
+  item: MarkdownTocItem
+  onNavigate: (id: string) => void
+}): React.JSX.Element {
+  return (
+    <>
+      <button
+        type="button"
+        className="markdown-toc-row"
+        style={{ paddingLeft: 12 + depth * 14 }}
+        title={item.title}
+        onClick={() => onNavigate(item.id)}
+      >
+        <span className="markdown-toc-level">H{item.level}</span>
+        <span className="markdown-toc-title">{item.title}</span>
+      </button>
+      {item.children.map((child) => (
+        <MarkdownTocRow key={child.id} depth={depth + 1} item={child} onNavigate={onNavigate} />
+      ))}
+    </>
+  )
+}
+
+export function MarkdownTableOfContentsPanel({
+  items,
+  onClose,
+  onNavigate
+}: MarkdownTableOfContentsPanelProps): React.JSX.Element {
+  return (
+    <aside className="markdown-toc-panel" aria-label="Table of contents">
+      <div className="markdown-toc-header">
+        <ListTree className="size-3.5 text-muted-foreground" />
+        <span>Table of Contents</span>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-xs"
+          className="ml-auto"
+          aria-label="Close table of contents"
+          title="Close table of contents"
+          onClick={onClose}
+        >
+          <X className="size-3.5" />
+        </Button>
+      </div>
+      <div className="markdown-toc-list">
+        {items.length > 0 ? (
+          items.map((item) => (
+            <MarkdownTocRow key={item.id} depth={0} item={item} onNavigate={onNavigate} />
+          ))
+        ) : (
+          <div className="markdown-toc-empty">No headings</div>
+        )}
+      </div>
+    </aside>
+  )
+}
diff --git a/src/renderer/src/components/editor/RichMarkdownEditor.tsx b/src/renderer/src/components/editor/RichMarkdownEditor.tsx
index 625dc47aac1..208daf48830 100644
--- a/src/renderer/src/components/editor/RichMarkdownEditor.tsx
+++ b/src/renderer/src/components/editor/RichMarkdownEditor.tsx
@@ -45,6 +45,8 @@ import type {
   RichMarkdownContextMenuCommand,
   RichMarkdownContextMenuCommandPayload
 } from '../../../../shared/rich-markdown-context-menu'
+import { buildMarkdownTableOfContents, type MarkdownTocItem } from './markdown-table-of-contents'
+import { MarkdownTableOfContentsPanel } from './MarkdownTableOfContentsPanel'
 
 type RichMarkdownEditorProps = {
   fileId: string
@@ -57,6 +59,8 @@ type RichMarkdownEditorProps = {
   onSave: (content: string) => void
   onOpenDocLink?: (target: string) => void
   markdownDocuments?: MarkdownDocument[]
+  showTableOfContents?: boolean
+  onCloseTableOfContents?: () => void
   // Why: front-matter is stripped from the rich editor's content but we still
   // want it visible to the user. It renders between the toolbar and the editor
   // surface so the formatting toolbar stays at the top of the pane.
@@ -154,6 +158,10 @@ function isRichMarkdownContextCommandTarget(
   )
 }
 
+function flattenMarkdownTocItems(items: MarkdownTocItem[]): MarkdownTocItem[] {
+  return items.flatMap((item) => [item, ...flattenMarkdownTocItems(item.children)])
+}
+
 export default function RichMarkdownEditor({
   fileId,
   content,
@@ -165,6 +173,8 @@ export default function RichMarkdownEditor({
   onSave,
   onOpenDocLink,
   markdownDocuments,
+  showTableOfContents = false,
+  onCloseTableOfContents,
   headerSlot
 }: RichMarkdownEditorProps): React.JSX.Element {
   const rootRef = useRef<HTMLDivElement | null>(null)
@@ -215,6 +225,11 @@ export default function RichMarkdownEditor({
   const [isEditingLink, setIsEditingLink] = useState(false)
   const isEditingLinkRef = useRef(false)
   const typedEmptyOrderedListMarkerRef = useRef(false)
+  const tableOfContentsItems = useMemo(() => buildMarkdownTableOfContents(content), [content])
+  const flatTableOfContentsItems = useMemo(
+    () => flattenMarkdownTocItems(tableOfContentsItems),
+    [tableOfContentsItems]
+  )
 
   // Why: assigning callback refs during render keeps them current before any
   // ProseMirror handler reads them, avoiding the one-render stale window that
@@ -566,6 +581,25 @@ export default function RichMarkdownEditor({
     openSearchRef.current = openSearch
   }, [openSearch])
 
+  const navigateToTableOfContentsItem = useCallback(
+    (id: string): void => {
+      const target = flatTableOfContentsItems.find((item) => item.id === id)
+      const container = scrollContainerRef.current
+      if (!target || !container) {
+        return
+      }
+      const sameTitleIndex = flatTableOfContentsItems
+        .filter((item) => item.title === target.title)
+        .findIndex((item) => item.id === target.id)
+      const matchingHeadings = Array.from(
+        container.querySelectorAll<HTMLElement>('h1, h2, h3')
+      ).filter((candidate) => candidate.textContent?.trim() === target.title)
+      const heading = matchingHeadings.at(Math.max(0, sameTitleIndex))
+      heading?.scrollIntoView({ block: 'center' })
+    },
+    [flatTableOfContentsItems]
+  )
+
   const filteredSlashCommands = useMemo(() => {
     const query = slashMenu?.query.trim().toLowerCase() ?? ''
     if (!query) {
@@ -712,75 +746,84 @@ export default function RichMarkdownEditor({
   }, [content, editor, fileId])
 
   return (
-    <div
-      ref={rootRef}
-      className="rich-markdown-editor-shell"
-      style={{ '--editor-font-zoom-level': editorFontZoomLevel } as React.CSSProperties}
-    >
-      <RichMarkdownToolbar
-        editor={editor}
-        onToggleLink={toggleLinkFromToolbar}
-        onImagePick={handleLocalImagePick}
-      />
-      {headerSlot}
-      {/* Why: wrap scroll area + search bar in a relative container so the
-          search bar overlays the content (Monaco-style) instead of occupying
-          layout space and shifting the document down when opened. */}
-      <div className="relative min-h-0 flex-1">
-        <div
-          ref={scrollContainerRef}
-          className="h-full overflow-auto scrollbar-editor"
-          onMouseDown={(event) => {
-            if (!shouldFocusEmptyEditorFromSurfaceClick(event, editorRef.current)) {
-              return
-            }
-            // Why: native contenteditable only places the caret on actual line
-            // boxes; an empty note should still focus when the user clicks any
-            // blank part of the document surface.
-            event.preventDefault()
-            editorRef.current?.commands.focus('start')
-          }}
-        >
-          <EditorContent editor={editor} />
-        </div>
-        <RichMarkdownSearchBar
-          activeMatchIndex={activeMatchIndex}
-          isOpen={isSearchOpen}
-          matchCount={matchCount}
-          onClose={closeSearch}
-          onMoveToMatch={moveToMatch}
-          onQueryChange={setSearchQuery}
-          query={searchQuery}
-          searchInputRef={searchInputRef}
-        />
-      </div>
-      {linkBubble ? (
-        <RichMarkdownLinkBubble
-          linkBubble={linkBubble}
-          isEditing={isEditingLink}
-          onSave={handleLinkSave}
-          onRemove={handleLinkRemove}
-          onEditStart={() => setIsEditingLink(true)}
-          onEditCancel={handleLinkEditCancel}
-          onOpen={handleLinkOpen}
-        />
-      ) : null}
-      {slashMenu && filteredSlashCommands.length > 0 ? (
-        <RichMarkdownSlashMenu
+    <div className="rich-markdown-editor-layout">
+      <div
+        ref={rootRef}
+        className="rich-markdown-editor-shell"
+        style={{ '--editor-font-zoom-level': editorFontZoomLevel } as React.CSSProperties}
+      >
+        <RichMarkdownToolbar
           editor={editor}
-          slashMenu={slashMenu}
-          filteredCommands={filteredSlashCommands}
-          selectedIndex={selectedCommandIndex}
+          onToggleLink={toggleLinkFromToolbar}
           onImagePick={handleLocalImagePick}
         />
-      ) : null}
-      {docLinkMenu ? (
-        <RichMarkdownDocLinkMenu
-          editor={editor}
-          menu={docLinkMenu}
-          rows={docLinkRows}
-          totalMatches={docLinkTotalMatches}
-          selectedIndex={selectedDocLinkIndex}
+        {headerSlot}
+        {/* Why: wrap scroll area + search bar in a relative container so the
+          search bar overlays the content (Monaco-style) instead of occupying
+          layout space and shifting the document down when opened. */}
+        <div className="relative min-h-0 flex-1">
+          <div
+            ref={scrollContainerRef}
+            className="h-full overflow-auto scrollbar-editor"
+            onMouseDown={(event) => {
+              if (!shouldFocusEmptyEditorFromSurfaceClick(event, editorRef.current)) {
+                return
+              }
+              // Why: native contenteditable only places the caret on actual line
+              // boxes; an empty note should still focus when the user clicks any
+              // blank part of the document surface.
+              event.preventDefault()
+              editorRef.current?.commands.focus('start')
+            }}
+          >
+            <EditorContent editor={editor} />
+          </div>
+          <RichMarkdownSearchBar
+            activeMatchIndex={activeMatchIndex}
+            isOpen={isSearchOpen}
+            matchCount={matchCount}
+            onClose={closeSearch}
+            onMoveToMatch={moveToMatch}
+            onQueryChange={setSearchQuery}
+            query={searchQuery}
+            searchInputRef={searchInputRef}
+          />
+        </div>
+        {linkBubble ? (
+          <RichMarkdownLinkBubble
+            linkBubble={linkBubble}
+            isEditing={isEditingLink}
+            onSave={handleLinkSave}
+            onRemove={handleLinkRemove}
+            onEditStart={() => setIsEditingLink(true)}
+            onEditCancel={handleLinkEditCancel}
+            onOpen={handleLinkOpen}
+          />
+        ) : null}
+        {slashMenu && filteredSlashCommands.length > 0 ? (
+          <RichMarkdownSlashMenu
+            editor={editor}
+            slashMenu={slashMenu}
+            filteredCommands={filteredSlashCommands}
+            selectedIndex={selectedCommandIndex}
+            onImagePick={handleLocalImagePick}
+          />
+        ) : null}
+        {docLinkMenu ? (
+          <RichMarkdownDocLinkMenu
+            editor={editor}
+            menu={docLinkMenu}
+            rows={docLinkRows}
+            totalMatches={docLinkTotalMatches}
+            selectedIndex={selectedDocLinkIndex}
+          />
+        ) : null}
+      </div>
+      {showTableOfContents ? (
+        <MarkdownTableOfContentsPanel
+          items={tableOfContentsItems}
+          onClose={onCloseTableOfContents ?? (() => {})}
+          onNavigate={navigateToTableOfContentsItem}
         />
       ) : null}
     </div>
diff --git a/src/renderer/src/components/editor/markdown-table-of-contents.test.ts b/src/renderer/src/components/editor/markdown-table-of-contents.test.ts
new file mode 100644
index 00000000000..fac94c85ce9
--- /dev/null
+++ b/src/renderer/src/components/editor/markdown-table-of-contents.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildMarkdownTableOfContents,
+  stripInlineMarkdownForToc
+} from './markdown-table-of-contents'
+
+describe('markdown table of contents', () => {
+  it('builds a nested h1-h3 outline', () => {
+    const toc = buildMarkdownTableOfContents('# Intro\n\n## Setup\n\n### Install\n\n## Usage')
+
+    expect(toc).toEqual([
+      {
+        id: 'intro',
+        level: 1,
+        title: 'Intro',
+        children: [
+          {
+            id: 'setup',
+            level: 2,
+            title: 'Setup',
+            children: [
+              {
+                id: 'install',
+                level: 3,
+                title: 'Install',
+                children: []
+              }
+            ]
+          },
+          {
+            id: 'usage',
+            level: 2,
+            title: 'Usage',
+            children: []
+          }
+        ]
+      }
+    ])
+  })
+
+  it('skips front matter and unsupported heading depths', () => {
+    const toc = buildMarkdownTableOfContents('---\ntitle: Doc\n---\n# Visible\n#### Hidden')
+
+    expect(toc.map((item) => item.title)).toEqual(['Visible'])
+  })
+
+  it('skips headings inside fenced code blocks', () => {
+    const toc = buildMarkdownTableOfContents('# Install\n\n```sh\n# not a heading\n```\n\n## Real')
+
+    expect(toc[0].children.map((item) => item.title)).toEqual(['Real'])
+  })
+
+  it('includes rendered markdown heading forms', () => {
+    const toc = buildMarkdownTableOfContents(
+      '# Intro\n\n  ## Indented\n\nSetext *Title*\n---\n\n### https://example.com'
+    )
+
+    expect(toc[0].children).toEqual([
+      {
+        id: 'indented',
+        level: 2,
+        title: 'Indented',
+        children: []
+      },
+      {
+        id: 'setext-title',
+        level: 2,
+        title: 'Setext Title',
+        children: [
+          {
+            id: 'httpsexamplecom',
+            level: 3,
+            title: 'https://example.com',
+            children: []
+          }
+        ]
+      }
+    ])
+  })
+
+  it('uses GitHub-compatible duplicate slugs', () => {
+    const toc = buildMarkdownTableOfContents('# Repeat\n# Repeat')
+
+    expect(toc.map((item) => item.id)).toEqual(['repeat', 'repeat-1'])
+  })
+
+  it('decodes HTML entities before slugging headings', () => {
+    const toc = buildMarkdownTableOfContents('# A &amp; B')
+
+    expect(toc[0]).toMatchObject({
+      id: 'a--b',
+      title: 'A & B'
+    })
+  })
+
+  it('strips inline markdown from labels', () => {
+    expect(stripInlineMarkdownForToc('Use **bold** [links](./x) and [[docs|Docs]]')).toBe(
+      'Use bold links and Docs'
+    )
+  })
+})
diff --git a/src/renderer/src/components/editor/markdown-table-of-contents.ts b/src/renderer/src/components/editor/markdown-table-of-contents.ts
new file mode 100644
index 00000000000..2d40cb4b962
--- /dev/null
+++ b/src/renderer/src/components/editor/markdown-table-of-contents.ts
@@ -0,0 +1,93 @@
+import GithubSlugger from 'github-slugger'
+import { decodeHTML } from 'entities'
+import { toString } from 'mdast-util-to-string'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import { unified } from 'unified'
+
+export type MarkdownTocLevel = 1 | 2 | 3
+
+export type MarkdownTocItem = {
+  children: MarkdownTocItem[]
+  id: string
+  level: MarkdownTocLevel
+  title: string
+}
+
+function isMarkdownTocLevel(value: number): value is MarkdownTocLevel {
+  return value === 1 || value === 2 || value === 3
+}
+
+export function stripInlineMarkdownForToc(text: string): string {
+  return decodeHTML(text)
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/\[\[[^|\]]+\|([^\]]+)\]\]/g, '$1')
+    .replace(/\[\[([^\]]+)\]\]/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .replace(/[*_`~]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function nearestParent(stack: MarkdownTocItem[], level: MarkdownTocLevel): MarkdownTocItem {
+  for (let index = stack.length - 1; index >= 0; index -= 1) {
+    const item = stack.at(index)
+    if (item && item.level < level) {
+      return item
+    }
+  }
+  return stack[0]
+}
+
+function appendTocItem(stack: MarkdownTocItem[], item: MarkdownTocItem): void {
+  nearestParent(stack, item.level).children.push(item)
+  Reflect.set(stack, item.level, item)
+  stack.length = item.level + 1
+}
+
+type MarkdownAstNode = {
+  children?: MarkdownAstNode[]
+  depth?: number
+  type?: string
+}
+
+export function buildMarkdownTableOfContents(markdown: string): MarkdownTocItem[] {
+  const slugger = new GithubSlugger()
+  const root: MarkdownTocItem = { id: 'toc-root', level: 1, title: '', children: [] }
+  const stack: MarkdownTocItem[] = [root]
+
+  // Why: the TOC must produce the same heading text/ids as react-markdown plus
+  // rehype-slug; parsing Markdown avoids drift on setext, GFM, and entities.
+  const tree = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkFrontmatter, ['yaml', 'toml'])
+    .parse(markdown) as MarkdownAstNode
+
+  function visit(node: MarkdownAstNode): void {
+    if (
+      node.type === 'heading' &&
+      typeof node.depth === 'number' &&
+      isMarkdownTocLevel(node.depth)
+    ) {
+      const title = toString(node).replace(/\s+/g, ' ').trim()
+      if (title) {
+        appendTocItem(stack, {
+          children: [],
+          id: slugger.slug(title),
+          level: node.depth,
+          title
+        })
+      }
+    }
+    for (const child of node.children ?? []) {
+      visit(child)
+    }
+  }
+
+  visit(tree)
+
+  return root.children
+}

From 1ba9cfc2e113f5e0b0fe63e24f50970b31ed3f9b Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Thu, 14 May 2026 22:11:50 -0700
Subject: [PATCH 15/82] Add rich markdown building block insertion (#1893)

- Add rich markdown building block insertion
---
 package.json                                  |   2 +
 pnpm-lock.yaml                                |  35 +++
 .../src/assets/rich-markdown-editor.css       |  86 ++++++-
 .../components/editor/RichMarkdownEditor.tsx  |  22 ++
 .../editor/RichMarkdownEmojiMenu.tsx          |  39 +++
 .../editor/RichMarkdownSlashMenu.tsx          |  53 ++--
 .../editor/rich-markdown-commands.test.ts     | 150 +++++++++++
 .../editor/rich-markdown-commands.tsx         | 241 ++++++++++++++----
 .../editor/rich-markdown-extensions.ts        |  12 +
 .../editor/rich-markdown-key-handler.test.ts  |  28 ++
 .../editor/rich-markdown-key-handler.ts       |  25 +-
 11 files changed, 611 insertions(+), 82 deletions(-)
 create mode 100644 src/renderer/src/components/editor/RichMarkdownEmojiMenu.tsx
 create mode 100644 src/renderer/src/components/editor/rich-markdown-commands.test.ts

diff --git a/package.json b/package.json
index 18e27bb409d..39e335bc753 100644
--- a/package.json
+++ b/package.json
@@ -60,6 +60,7 @@
     "@tiptap/extension-code-block-lowlight": "^3.22.5",
     "@tiptap/extension-image": "^3.22.5",
     "@tiptap/extension-link": "^3.22.5",
+    "@tiptap/extension-mathematics": "3.22.5",
     "@tiptap/extension-placeholder": "^3.22.5",
     "@tiptap/extension-table": "3.22.4",
     "@tiptap/extension-table-cell": "3.22.4",
@@ -88,6 +89,7 @@
     "dompurify": "^3.4.2",
     "electron-updater": "^6.8.3",
     "entities": "^6.0.1",
+    "emoji-picker-react": "^4.19.1",
     "github-slugger": "^2.0.0",
     "hosted-git-info": "^9.0.3",
     "html-to-image": "^1.11.13",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d40d37323d0..b42fb257529 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -55,6 +55,9 @@ importers:
       '@tiptap/extension-link':
         specifier: ^3.22.5
         version: 3.22.5(@tiptap/core@3.22.5(@tiptap/pm@3.22.5))(@tiptap/pm@3.22.5)
+      '@tiptap/extension-mathematics':
+        specifier: 3.22.5
+        version: 3.22.5(@tiptap/core@3.22.5(@tiptap/pm@3.22.5))(@tiptap/pm@3.22.5)(katex@0.16.45)
       '@tiptap/extension-placeholder':
         specifier: ^3.22.5
         version: 3.22.5(@tiptap/extensions@3.22.5(@tiptap/core@3.22.5(@tiptap/pm@3.22.5))(@tiptap/pm@3.22.5))
@@ -139,6 +142,9 @@ importers:
       entities:
         specifier: ^6.0.1
         version: 6.0.1
+      emoji-picker-react:
+        specifier: ^4.19.1
+        version: 4.19.1(react@19.2.5)
       github-slugger:
         specifier: ^2.0.0
         version: 2.0.0
@@ -2627,6 +2633,13 @@ packages:
       '@tiptap/core': 3.22.5
       '@tiptap/pm': 3.22.5
 
+  '@tiptap/extension-mathematics@3.22.5':
+    resolution: {integrity: sha512-ld2xoFHKyl4Qs+rgu3wn1UZBTsgDApEz2PD17E/XWlVXHO4KoiBOcLhrc5L9SL+aKOBXXmC/Ex1d+0hCptsBbg==}
+    peerDependencies:
+      '@tiptap/core': 3.22.5
+      '@tiptap/pm': 3.22.5
+      katex: ^0.16.4
+
   '@tiptap/extension-ordered-list@3.22.5':
     resolution: {integrity: sha512-OXdh4k4CNrukwiSdWdEQ49uvgnqvR0Z9aNSP4HI5/kZQ/Te1NtRtYCpUrzWyO/7CtjcCisXHti0o9C/TV8YMbQ==}
     peerDependencies:
@@ -3847,6 +3860,12 @@ packages:
     engines: {node: '>= 12.20.55'}
     hasBin: true
 
+  emoji-picker-react@4.19.1:
+    resolution: {integrity: sha512-BmDdqInKFVYJpv7qS9WI6L9656cDAC+FkDvUjJds56nKHbaVTBNeDmLwKBytRnzu37zWHs9Isg7gt5PT43y6xA==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      react: '>=16'
+
   emoji-regex@10.6.0:
     resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
 
@@ -4069,6 +4088,9 @@ packages:
     resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==}
     engines: {node: '>=8'}
 
+  flairup@1.0.0:
+    resolution: {integrity: sha512-IKlE+pNvL2R+kVL1kEhUYqRxVqeFnjiIvHWDMLFXNaqyUdFXQM2wte44EfMYJNHkW16X991t2Zg8apKkhv7OBA==}
+
   form-data@4.0.5:
     resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==}
     engines: {node: '>= 6'}
@@ -8436,6 +8458,12 @@ snapshots:
       '@tiptap/core': 3.22.5(@tiptap/pm@3.22.5)
       '@tiptap/pm': 3.22.5
 
+  '@tiptap/extension-mathematics@3.22.5(@tiptap/core@3.22.5(@tiptap/pm@3.22.5))(@tiptap/pm@3.22.5)(katex@0.16.45)':
+    dependencies:
+      '@tiptap/core': 3.22.5(@tiptap/pm@3.22.5)
+      '@tiptap/pm': 3.22.5
+      katex: 0.16.45
+
   '@tiptap/extension-ordered-list@3.22.5(@tiptap/extension-list@3.22.5(@tiptap/core@3.22.5(@tiptap/pm@3.22.5))(@tiptap/pm@3.22.5))':
     dependencies:
       '@tiptap/extension-list': 3.22.5(@tiptap/core@3.22.5(@tiptap/pm@3.22.5))(@tiptap/pm@3.22.5)
@@ -9814,6 +9842,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  emoji-picker-react@4.19.1(react@19.2.5):
+    dependencies:
+      flairup: 1.0.0
+      react: 19.2.5
+
   emoji-regex@10.6.0: {}
 
   emoji-regex@8.0.0: {}
@@ -10111,6 +10144,8 @@ snapshots:
       locate-path: 5.0.0
       path-exists: 4.0.0
 
+  flairup@1.0.0: {}
+
   form-data@4.0.5:
     dependencies:
       asynckit: 0.4.0
diff --git a/src/renderer/src/assets/rich-markdown-editor.css b/src/renderer/src/assets/rich-markdown-editor.css
index 7f2b8fbe62c..338f1293ab4 100644
--- a/src/renderer/src/assets/rich-markdown-editor.css
+++ b/src/renderer/src/assets/rich-markdown-editor.css
@@ -188,6 +188,26 @@
   margin: 0.75em 0;
 }
 
+.rich-markdown-editor .tiptap-mathematics-render {
+  border-radius: 4px;
+}
+
+.rich-markdown-editor .tiptap-mathematics-render[data-type='inline-math'] {
+  padding: 0 2px;
+}
+
+.rich-markdown-editor .tiptap-mathematics-render[data-type='block-math'] {
+  margin: 1em 0;
+  padding: 0.75em 1em;
+  overflow-x: auto;
+  border: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+  background: color-mix(in srgb, var(--muted) 42%, transparent);
+}
+
+.rich-markdown-editor .tiptap-mathematics-render--editable {
+  cursor: default;
+}
+
 .rich-markdown-editor ul,
 .rich-markdown-editor ol {
   padding-left: 1.5em;
@@ -562,23 +582,45 @@
   position: absolute;
   z-index: 30;
   display: flex;
-  width: min(320px, calc(100% - 24px));
-  max-height: 280px;
+  width: min(300px, calc(100% - 24px));
+  max-height: min(440px, calc(100vh - 120px));
   flex-direction: column;
   overflow-y: auto;
   border: 1px solid color-mix(in srgb, var(--border) 76%, transparent);
-  border-radius: 12px;
-  background: color-mix(in srgb, var(--background) 92%, transparent);
-  box-shadow: 0 18px 44px rgba(0, 0, 0, 0.2);
-  backdrop-filter: blur(16px);
+  border-radius: 6px;
+  background: var(--popover);
+  color: var(--popover-foreground);
+  box-shadow: 0 10px 24px rgba(0, 0, 0, 0.18);
+}
+
+.rich-markdown-slash-query {
+  display: flex;
+  min-height: 32px;
+  align-items: center;
+  gap: 1px;
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 64%, transparent);
+  padding: 5px 12px;
+  color: var(--popover-foreground);
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 20px;
+}
+
+.rich-markdown-slash-section {
+  padding: 9px 12px 4px;
+  color: var(--muted-foreground);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1;
 }
 
 .rich-markdown-slash-item {
   display: flex;
   align-items: center;
-  gap: 10px;
+  gap: 9px;
   width: 100%;
-  padding: 10px 12px;
+  min-height: 34px;
+  padding: 5px 12px;
   border: none;
   background: transparent;
   color: inherit;
@@ -594,14 +636,36 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 28px;
-  height: 28px;
+  width: 22px;
+  height: 22px;
   flex-shrink: 0;
-  border-radius: 8px;
+  border-radius: 5px;
   background: color-mix(in srgb, var(--foreground) 6%, transparent);
   color: var(--muted-foreground);
 }
 
+.rich-markdown-emoji-menu {
+  position: absolute;
+  z-index: 31;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, var(--border) 76%, transparent);
+  border-radius: 6px;
+  background: var(--popover);
+  color: var(--popover-foreground);
+  box-shadow: 0 10px 24px rgba(0, 0, 0, 0.18);
+}
+
+.rich-markdown-emoji-menu .EmojiPickerReact {
+  --epr-bg-color: var(--popover);
+  --epr-category-label-bg-color: var(--popover);
+  --epr-text-color: var(--popover-foreground);
+  --epr-search-input-bg-color: transparent;
+  --epr-search-input-border-color: var(--border);
+  --epr-hover-bg-color: var(--accent);
+  border: none;
+  font-family: Geist, sans-serif;
+}
+
 .rich-markdown-doc-link-menu {
   position: absolute;
   z-index: 30;
diff --git a/src/renderer/src/components/editor/RichMarkdownEditor.tsx b/src/renderer/src/components/editor/RichMarkdownEditor.tsx
index 208daf48830..096ed5062f7 100644
--- a/src/renderer/src/components/editor/RichMarkdownEditor.tsx
+++ b/src/renderer/src/components/editor/RichMarkdownEditor.tsx
@@ -5,6 +5,7 @@ import type { Editor } from '@tiptap/react'
 import type { MarkdownDocument } from '../../../../shared/types'
 import { RichMarkdownSlashMenu } from './RichMarkdownSlashMenu'
 import { RichMarkdownDocLinkMenu } from './RichMarkdownDocLinkMenu'
+import { RichMarkdownEmojiMenu } from './RichMarkdownEmojiMenu'
 import { useAppStore } from '@/store'
 import { RichMarkdownToolbar } from './RichMarkdownToolbar'
 import { encodeRawMarkdownHtmlForRichEditor } from './raw-markdown-html'
@@ -193,6 +194,7 @@ export default function RichMarkdownEditor({
   const [slashMenu, setSlashMenu] = useState<SlashMenuState | null>(null)
   const [selectedCommandIndex, setSelectedCommandIndex] = useState(0)
   const [docLinkMenu, setDocLinkMenu] = useState<DocLinkMenuState | null>(null)
+  const [emojiMenu, setEmojiMenu] = useState<{ left: number; top: number } | null>(null)
   const [selectedDocLinkIndex, setSelectedDocLinkIndex] = useState(0)
   const isMac = navigator.userAgent.includes('Mac')
   const lastCommittedMarkdownRef = useRef(content)
@@ -207,6 +209,7 @@ export default function RichMarkdownEditor({
   const onSaveRef = useRef(onSave)
   const onOpenDocLinkRef = useRef(onOpenDocLink)
   const handleLocalImagePickRef = useRef<() => void>(() => {})
+  const handleEmojiPickRef = useRef<(menu: SlashMenuState) => void>(() => {})
   const openSearchRef = useRef<() => void>(() => {})
   // Why: ProseMirror keeps the initial handleKeyDown closure, so `editor` stays
   // stuck at the first-render null value unless we read the live instance here.
@@ -305,6 +308,7 @@ export default function RichMarkdownEditor({
         filteredDocLinkRowsRef,
         selectedDocLinkIndexRef,
         handleLocalImagePickRef,
+        handleEmojiPickRef,
         typedEmptyOrderedListMarkerRef,
         flushPendingSerialization,
         openSearchRef,
@@ -600,6 +604,15 @@ export default function RichMarkdownEditor({
     [flatTableOfContentsItems]
   )
 
+  const openEmojiMenu = useCallback((menu: SlashMenuState): void => {
+    setSlashMenu(null)
+    setEmojiMenu({ left: menu.left, top: menu.top })
+  }, [])
+
+  useEffect(() => {
+    handleEmojiPickRef.current = openEmojiMenu
+  }, [openEmojiMenu])
+
   const filteredSlashCommands = useMemo(() => {
     const query = slashMenu?.query.trim().toLowerCase() ?? ''
     if (!query) {
@@ -807,6 +820,15 @@ export default function RichMarkdownEditor({
             filteredCommands={filteredSlashCommands}
             selectedIndex={selectedCommandIndex}
             onImagePick={handleLocalImagePick}
+            onEmojiPick={() => openEmojiMenu(slashMenu)}
+          />
+        ) : null}
+        {emojiMenu ? (
+          <RichMarkdownEmojiMenu
+            editor={editor}
+            left={emojiMenu.left}
+            top={emojiMenu.top}
+            onClose={() => setEmojiMenu(null)}
           />
         ) : null}
         {docLinkMenu ? (
diff --git a/src/renderer/src/components/editor/RichMarkdownEmojiMenu.tsx b/src/renderer/src/components/editor/RichMarkdownEmojiMenu.tsx
new file mode 100644
index 00000000000..6a5677b66bf
--- /dev/null
+++ b/src/renderer/src/components/editor/RichMarkdownEmojiMenu.tsx
@@ -0,0 +1,39 @@
+import React from 'react'
+import type { Editor } from '@tiptap/react'
+import EmojiPicker, { EmojiStyle, Theme, type EmojiClickData } from 'emoji-picker-react'
+
+type RichMarkdownEmojiMenuProps = {
+  editor: Editor | null
+  left: number
+  top: number
+  onClose: () => void
+}
+
+export function RichMarkdownEmojiMenu({
+  editor,
+  left,
+  top,
+  onClose
+}: RichMarkdownEmojiMenuProps): React.JSX.Element {
+  const insertEmoji = (emojiData: EmojiClickData): void => {
+    editor?.chain().focus().insertContent(emojiData.emoji).run()
+    onClose()
+  }
+
+  return (
+    <div className="rich-markdown-emoji-menu" style={{ left, top }} role="dialog">
+      <EmojiPicker
+        autoFocusSearch
+        emojiStyle={EmojiStyle.NATIVE}
+        height={360}
+        lazyLoadEmojis
+        onEmojiClick={insertEmoji}
+        previewConfig={{ showPreview: false }}
+        searchPlaceHolder="Search emoji"
+        skinTonesDisabled
+        theme={Theme.AUTO}
+        width={320}
+      />
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/editor/RichMarkdownSlashMenu.tsx b/src/renderer/src/components/editor/RichMarkdownSlashMenu.tsx
index 808591d359c..65df1ae8b82 100644
--- a/src/renderer/src/components/editor/RichMarkdownSlashMenu.tsx
+++ b/src/renderer/src/components/editor/RichMarkdownSlashMenu.tsx
@@ -10,6 +10,7 @@ type RichMarkdownSlashMenuProps = {
   filteredCommands: SlashCommand[]
   selectedIndex: number
   onImagePick: () => void
+  onEmojiPick: () => void
 }
 
 export function RichMarkdownSlashMenu({
@@ -17,33 +18,49 @@ export function RichMarkdownSlashMenu({
   slashMenu,
   filteredCommands,
   selectedIndex,
-  onImagePick
+  onImagePick,
+  onEmojiPick
 }: RichMarkdownSlashMenuProps): React.JSX.Element {
+  let currentGroup: SlashCommand['group'] | null = null
+
   return (
     <div
-      className="rich-markdown-slash-menu"
+      className="rich-markdown-slash-menu scrollbar-sleek"
       style={{ left: slashMenu.left, top: slashMenu.top }}
       role="listbox"
       aria-label="Slash commands"
     >
+      <div className="rich-markdown-slash-query" aria-hidden="true">
+        <span className="text-muted-foreground">/</span>
+        <span>{slashMenu.query}</span>
+      </div>
       {filteredCommands.map((command, index) => {
-        const Icon = command.icon
+        const showGroup = command.group !== currentGroup
+        currentGroup = command.group
         return (
-          <button
-            key={command.id}
-            type="button"
-            className={cn('rich-markdown-slash-item', index === selectedIndex && 'is-active')}
-            onMouseDown={(event) => event.preventDefault()}
-            onClick={() => editor && runSlashCommand(editor, slashMenu, command, onImagePick)}
-          >
-            <span className="rich-markdown-slash-icon">
-              <Icon className="size-3.5" />
-            </span>
-            <span className="flex min-w-0 flex-1 flex-col items-start">
-              <span className="truncate text-sm font-medium">{command.label}</span>
-              <span className="truncate text-xs text-muted-foreground">{command.description}</span>
-            </span>
-          </button>
+          <React.Fragment key={command.id}>
+            {showGroup ? <div className="rich-markdown-slash-section">{command.group}</div> : null}
+            <button
+              type="button"
+              title={command.description}
+              className={cn('rich-markdown-slash-item', index === selectedIndex && 'is-active')}
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={() =>
+                editor && runSlashCommand(editor, slashMenu, command, onImagePick, onEmojiPick)
+              }
+            >
+              <span className="rich-markdown-slash-icon">
+                {command.icon.kind === 'component' ? (
+                  <command.icon.component className="size-3.5" />
+                ) : (
+                  <span className="text-sm leading-none">{command.icon.value}</span>
+                )}
+              </span>
+              <span className="flex min-w-0 flex-1 flex-col items-start">
+                <span className="truncate text-[13px] font-medium leading-5">{command.label}</span>
+              </span>
+            </button>
+          </React.Fragment>
         )
       })}
     </div>
diff --git a/src/renderer/src/components/editor/rich-markdown-commands.test.ts b/src/renderer/src/components/editor/rich-markdown-commands.test.ts
new file mode 100644
index 00000000000..e23bec986bf
--- /dev/null
+++ b/src/renderer/src/components/editor/rich-markdown-commands.test.ts
@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import { createRichMarkdownExtensions } from './rich-markdown-extensions'
+import { runSlashCommand, slashCommands, type SlashCommandId } from './rich-markdown-commands'
+
+function createEditor(content = '/'): Editor {
+  return new Editor({
+    element: null,
+    extensions: createRichMarkdownExtensions(),
+    content,
+    contentType: 'markdown'
+  })
+}
+
+function getCommand(id: SlashCommandId) {
+  const command = slashCommands.find((candidate) => candidate.id === id)
+  if (!command) {
+    throw new Error(`Missing slash command ${id}`)
+  }
+  return command
+}
+
+function runCommand(id: SlashCommandId, content = '/'): Editor {
+  const editor = createEditor(content)
+  editor.commands.setTextSelection(content.length + 1)
+  runSlashCommand(editor, { from: 1, to: content.length + 1 }, getCommand(id))
+  return editor
+}
+
+describe('rich markdown slash commands', () => {
+  it('registers high-value markdown building blocks with searchable aliases', () => {
+    expect(getCommand('table').aliases).toContain('grid')
+    expect(getCommand('mermaid').aliases).toContain('diagram')
+    expect(getCommand('inline-math').aliases).toContain('latex')
+    expect(getCommand('math-block').aliases).toContain('equation block')
+    expect(getCommand('emoji').aliases).toContain('reaction')
+  })
+
+  it('orders commands under section headers', () => {
+    expect(slashCommands.map((command) => `${command.group}:${command.id}`)).toEqual([
+      'Headings:heading-1',
+      'Headings:heading-2',
+      'Headings:heading-3',
+      'Basic blocks:blockquote',
+      'Basic blocks:ordered-list',
+      'Basic blocks:bullet-list',
+      'Basic blocks:task-list',
+      'Basic blocks:text',
+      'Basic blocks:code-block',
+      'Basic blocks:divider',
+      'Advanced:table',
+      'Advanced:mermaid',
+      'Advanced:inline-math',
+      'Advanced:math-block',
+      'Media:image',
+      'Others:emoji'
+    ])
+  })
+
+  it('inserts a durable markdown table', () => {
+    const editor = runCommand('table')
+
+    try {
+      expect(editor.getMarkdown()).toContain('|     |     |     |')
+      expect(editor.getMarkdown()).toContain('| --- | --- | --- |')
+    } finally {
+      editor.destroy()
+    }
+  })
+
+  it('inserts a mermaid fenced code block', () => {
+    const editor = runCommand('mermaid')
+
+    try {
+      expect(editor.getMarkdown()).toBe('```mermaid\ngraph TD\n  A[Start] --> B[End]\n```')
+    } finally {
+      editor.destroy()
+    }
+  })
+
+  it('inserts inline math as a rendered rich editor node', () => {
+    const editor = runCommand('inline-math')
+
+    try {
+      expect(editor.getMarkdown()).toBe('$x$')
+      expect(editor.getJSON()).toMatchObject({
+        content: [
+          {
+            content: [
+              {
+                type: 'inlineMath',
+                attrs: { latex: 'x' }
+              }
+            ]
+          }
+        ]
+      })
+    } finally {
+      editor.destroy()
+    }
+  })
+
+  it('inserts display math as a rendered rich editor node', () => {
+    const editor = runCommand('math-block')
+
+    try {
+      expect(editor.getMarkdown()).toBe('$$\nx\n$$')
+      expect(editor.getJSON()).toMatchObject({
+        content: [
+          {
+            type: 'blockMath',
+            attrs: { latex: 'x' }
+          }
+        ]
+      })
+    } finally {
+      editor.destroy()
+    }
+  })
+
+  it('parses existing display math as a rendered rich editor node', () => {
+    const editor = createEditor('Before\n\n$$\nx + y\n$$\n\nAfter')
+
+    try {
+      expect(editor.getJSON()).toMatchObject({
+        content: [
+          { type: 'paragraph' },
+          {
+            type: 'blockMath',
+            attrs: { latex: 'x + y' }
+          },
+          { type: 'paragraph' }
+        ]
+      })
+      expect(editor.getMarkdown()).toBe('Before\n\n$$\nx + y\n$$\n\nAfter')
+    } finally {
+      editor.destroy()
+    }
+  })
+
+  it('inserts a plain unicode emoji', () => {
+    const editor = runCommand('emoji')
+
+    try {
+      expect(editor.getMarkdown()).toBe('🙂')
+    } finally {
+      editor.destroy()
+    }
+  })
+})
diff --git a/src/renderer/src/components/editor/rich-markdown-commands.tsx b/src/renderer/src/components/editor/rich-markdown-commands.tsx
index aee9405ce83..03da78f3920 100644
--- a/src/renderer/src/components/editor/rich-markdown-commands.tsx
+++ b/src/renderer/src/components/editor/rich-markdown-commands.tsx
@@ -1,6 +1,20 @@
+/* eslint-disable max-lines -- Why: slash commands and doc-link command helpers share trigger-range contracts used by the editor keyboard path. */
 import React from 'react'
 import type { Editor } from '@tiptap/react'
-import { Heading1, Heading2, Heading3, ImageIcon, List, ListOrdered, Quote } from 'lucide-react'
+import { TextSelection } from '@tiptap/pm/state'
+import type {} from '@tiptap/extension-mathematics'
+import {
+  Heading1,
+  Heading2,
+  Heading3,
+  ImageIcon,
+  List,
+  ListOrdered,
+  Quote,
+  Sigma,
+  Table2,
+  Workflow
+} from 'lucide-react'
 import type { MarkdownDocument } from '../../../../shared/types'
 import { stripMarkdownExtension } from './markdown-doc-links'
 
@@ -41,16 +55,72 @@ export type SlashCommandId =
   | 'code-block'
   | 'divider'
   | 'image'
+  | 'table'
+  | 'mermaid'
+  | 'inline-math'
+  | 'math-block'
+  | 'emoji'
+
+export type SlashCommandIcon =
+  | { kind: 'component'; component: React.ComponentType<{ className?: string }> }
+  | { kind: 'text'; value: string }
+
+export type SlashCommandGroup = 'Headings' | 'Basic blocks' | 'Advanced' | 'Media' | 'Others'
 
 export type SlashCommand = {
   id: SlashCommandId
   label: string
   aliases: string[]
-  icon: React.ComponentType<{ className?: string }>
+  icon: SlashCommandIcon
+  group: SlashCommandGroup
   description: string
   run: (editor: Editor) => void
 }
 
+function icon(component: React.ComponentType<{ className?: string }>): SlashCommandIcon {
+  return { kind: 'component', component }
+}
+
+function textIcon(value: string): SlashCommandIcon {
+  return { kind: 'text', value }
+}
+
+function insertTextWithSelection(
+  editor: Editor,
+  text: string,
+  selectionStartOffset?: number,
+  selectionEndOffset = selectionStartOffset
+): void {
+  editor.commands.command(({ state, dispatch }) => {
+    const from = state.selection.from
+    const tr = state.tr.insertText(text, from, state.selection.to)
+
+    if (selectionStartOffset !== undefined) {
+      const selectionFrom = from + selectionStartOffset
+      const selectionTo = from + (selectionEndOffset ?? selectionStartOffset)
+      tr.setSelection(TextSelection.create(tr.doc, selectionFrom, selectionTo))
+    }
+
+    dispatch?.(tr.scrollIntoView())
+    return true
+  })
+}
+
+function insertCodeBlock(editor: Editor, language: string, text: string): void {
+  editor.commands.command(({ state, dispatch }) => {
+    const codeBlockType = state.schema.nodes.codeBlock
+    if (!codeBlockType) {
+      return false
+    }
+    const node = codeBlockType.create({ language }, text ? state.schema.text(text) : undefined)
+    const tr = state.tr.replaceSelectionWith(node).scrollIntoView()
+    const cursor = tr.selection.from + 1
+    tr.setSelection(TextSelection.create(tr.doc, cursor, cursor))
+    dispatch?.(tr)
+    return true
+  })
+}
+
 /**
  * Executes a slash command by first deleting the typed slash text, then
  * delegating to the command's run method. Image is special-cased because
@@ -60,7 +130,8 @@ export function runSlashCommand(
   editor: Editor,
   slashMenu: { from: number; to: number },
   command: SlashCommand,
-  onImageCommand?: () => void
+  onImageCommand?: () => void,
+  onEmojiCommand?: () => void
 ): void {
   editor.chain().focus().deleteRange({ from: slashMenu.from, to: slashMenu.to }).run()
   // Why: image insertion cannot rely on window.prompt() in Electron, so this
@@ -69,25 +140,20 @@ export function runSlashCommand(
     onImageCommand()
     return
   }
+  if (command.id === 'emoji' && onEmojiCommand) {
+    onEmojiCommand()
+    return
+  }
   command.run(editor)
 }
 
 export const slashCommands: SlashCommand[] = [
-  {
-    id: 'text',
-    label: 'Text',
-    aliases: ['paragraph', 'plain'],
-    icon: List,
-    description: 'Start a normal paragraph.',
-    run: (editor) => {
-      editor.chain().focus().setParagraph().run()
-    }
-  },
   {
     id: 'heading-1',
     label: 'Heading 1',
     aliases: ['h1', 'title'],
-    icon: Heading1,
+    icon: icon(Heading1),
+    group: 'Headings',
     description: 'Large section heading.',
     run: (editor) => {
       // Use setHeading (not toggleHeading) so the slash command is idempotent —
@@ -99,7 +165,8 @@ export const slashCommands: SlashCommand[] = [
     id: 'heading-2',
     label: 'Heading 2',
     aliases: ['h2'],
-    icon: Heading2,
+    icon: icon(Heading2),
+    group: 'Headings',
     description: 'Medium section heading.',
     run: (editor) => {
       // Use setHeading (not toggleHeading) so the slash command is idempotent —
@@ -111,7 +178,8 @@ export const slashCommands: SlashCommand[] = [
     id: 'heading-3',
     label: 'Heading 3',
     aliases: ['h3'],
-    icon: Heading3,
+    icon: icon(Heading3),
+    group: 'Headings',
     description: 'Small section heading.',
     run: (editor) => {
       // Use setHeading (not toggleHeading) so the slash command is idempotent —
@@ -119,51 +187,67 @@ export const slashCommands: SlashCommand[] = [
       editor.chain().focus().setHeading({ level: 3 }).run()
     }
   },
-  {
-    id: 'task-list',
-    label: 'To-do List',
-    aliases: ['todo', 'task', 'checkbox'],
-    icon: List,
-    description: 'Create a checklist.',
-    run: (editor) => {
-      editor.chain().focus().toggleTaskList().run()
-    }
-  },
-  {
-    id: 'bullet-list',
-    label: 'Bullet List',
-    aliases: ['bullet', 'ul', 'list'],
-    icon: List,
-    description: 'Create an unordered list.',
-    run: (editor) => {
-      editor.chain().focus().toggleBulletList().run()
-    }
-  },
-  {
-    id: 'ordered-list',
-    label: 'Numbered List',
-    aliases: ['ordered', 'ol', 'numbered'],
-    icon: ListOrdered,
-    description: 'Create an ordered list.',
-    run: (editor) => {
-      editor.chain().focus().toggleOrderedList().run()
-    }
-  },
   {
     id: 'blockquote',
     label: 'Quote',
     aliases: ['quote', 'blockquote'],
-    icon: Quote,
+    icon: icon(Quote),
+    group: 'Basic blocks',
     description: 'Insert a blockquote.',
     run: (editor) => {
       editor.chain().focus().toggleBlockquote().run()
     }
   },
+  {
+    id: 'ordered-list',
+    label: 'Numbered List',
+    aliases: ['ordered', 'ol', 'numbered'],
+    icon: icon(ListOrdered),
+    group: 'Basic blocks',
+    description: 'Create an ordered list.',
+    run: (editor) => {
+      editor.chain().focus().toggleOrderedList().run()
+    }
+  },
+  {
+    id: 'bullet-list',
+    label: 'Bullet List',
+    aliases: ['bullet', 'ul', 'list'],
+    icon: icon(List),
+    group: 'Basic blocks',
+    description: 'Create an unordered list.',
+    run: (editor) => {
+      editor.chain().focus().toggleBulletList().run()
+    }
+  },
+  {
+    id: 'task-list',
+    label: 'Check List',
+    aliases: ['todo', 'task', 'checkbox'],
+    icon: icon(List),
+    group: 'Basic blocks',
+    description: 'Create a checklist.',
+    run: (editor) => {
+      editor.chain().focus().toggleTaskList().run()
+    }
+  },
+  {
+    id: 'text',
+    label: 'Paragraph',
+    aliases: ['paragraph', 'plain'],
+    icon: icon(List),
+    group: 'Basic blocks',
+    description: 'Start a normal paragraph.',
+    run: (editor) => {
+      editor.chain().focus().setParagraph().run()
+    }
+  },
   {
     id: 'code-block',
     label: 'Code Block',
     aliases: ['code', 'snippet'],
-    icon: List,
+    icon: icon(List),
+    group: 'Basic blocks',
     description: 'Insert a fenced code block.',
     run: (editor) => {
       editor.chain().focus().toggleCodeBlock().run()
@@ -173,23 +257,80 @@ export const slashCommands: SlashCommand[] = [
     id: 'divider',
     label: 'Divider',
     aliases: ['divider', 'rule', 'hr'],
-    icon: List,
+    icon: icon(List),
+    group: 'Basic blocks',
     description: 'Insert a horizontal rule.',
     run: (editor) => {
       editor.chain().focus().setHorizontalRule().run()
     }
   },
+  {
+    id: 'table',
+    label: 'Table',
+    aliases: ['grid', 'columns', 'rows'],
+    icon: icon(Table2),
+    group: 'Advanced',
+    description: 'Insert a 3x3 markdown table.',
+    run: (editor) => {
+      editor.chain().focus().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run()
+    }
+  },
+  {
+    id: 'mermaid',
+    label: 'Mermaid Diagram',
+    aliases: ['diagram', 'flowchart', 'chart', 'graph'],
+    icon: icon(Workflow),
+    group: 'Advanced',
+    description: 'Insert a Mermaid fenced block.',
+    run: (editor) => {
+      insertCodeBlock(editor, 'mermaid', 'graph TD\n  A[Start] --> B[End]')
+    }
+  },
+  {
+    id: 'inline-math',
+    label: 'Inline Math',
+    aliases: ['math', 'latex', 'equation', 'formula'],
+    icon: icon(Sigma),
+    group: 'Advanced',
+    description: 'Insert inline LaTeX math.',
+    run: (editor) => {
+      editor.commands.insertInlineMath({ latex: 'x' })
+    }
+  },
+  {
+    id: 'math-block',
+    label: 'Math Block',
+    aliases: ['display math', 'latex block', 'equation block'],
+    icon: icon(Sigma),
+    group: 'Advanced',
+    description: 'Insert display LaTeX math.',
+    run: (editor) => {
+      editor.commands.insertBlockMath({ latex: 'x' })
+    }
+  },
   {
     id: 'image',
     label: 'Image',
     aliases: ['image', 'img'],
-    icon: ImageIcon,
+    icon: icon(ImageIcon),
+    group: 'Media',
     description: 'Insert an image from your computer.',
     // Why: window.prompt() is not supported in Electron's renderer process,
     // so image URL input is handled by an inline input bar in RichMarkdownEditor.
     run: (editor) => {
       editor.chain().focus().run()
     }
+  },
+  {
+    id: 'emoji',
+    label: 'Emoji',
+    aliases: ['smile', 'reaction', 'icon'],
+    icon: textIcon('🙂'),
+    group: 'Others',
+    description: 'Insert a plain Unicode emoji.',
+    run: (editor) => {
+      insertTextWithSelection(editor, '🙂')
+    }
   }
 ]
 
diff --git a/src/renderer/src/components/editor/rich-markdown-extensions.ts b/src/renderer/src/components/editor/rich-markdown-extensions.ts
index 00479bfd89f..4cc560b2636 100644
--- a/src/renderer/src/components/editor/rich-markdown-extensions.ts
+++ b/src/renderer/src/components/editor/rich-markdown-extensions.ts
@@ -10,6 +10,7 @@ import { Table } from '@tiptap/extension-table'
 import { TableCell } from '@tiptap/extension-table-cell'
 import { TableHeader } from '@tiptap/extension-table-header'
 import { TableRow } from '@tiptap/extension-table-row'
+import { BlockMath, InlineMath } from '@tiptap/extension-mathematics'
 import { Markdown } from '@tiptap/markdown'
 import { createLowlight, common } from 'lowlight'
 import { loadLocalImageSrc, onImageCacheInvalidated } from './useLocalImageSrc'
@@ -132,6 +133,17 @@ export function createRichMarkdownExtensions({
     TableRow,
     TableHeader,
     TableCell,
+    InlineMath.configure({
+      katexOptions: {
+        throwOnError: false
+      }
+    }),
+    BlockMath.configure({
+      katexOptions: {
+        displayMode: true,
+        throwOnError: false
+      }
+    }),
     RawMarkdownHtmlInline,
     RawMarkdownHtmlBlock,
     MarkdownDocLink,
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 059c0a0448f..17bfb45df53 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
@@ -45,6 +45,7 @@ function createContext(editor: Editor, typedMarker: boolean): KeyHandlerContext
     filteredDocLinkRowsRef: { current: [] },
     selectedDocLinkIndexRef: { current: 0 },
     handleLocalImagePickRef: { current: vi.fn() },
+    handleEmojiPickRef: { current: vi.fn() },
     typedEmptyOrderedListMarkerRef: { current: typedMarker },
     flushPendingSerialization: vi.fn(),
     openSearchRef: { current: vi.fn() },
@@ -117,4 +118,31 @@ describe('rich markdown key handler', () => {
       editor.destroy()
     }
   })
+
+  it('keeps slash-menu filter input out of the document', () => {
+    const editor = createEditor({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: '/' }] }]
+    })
+
+    try {
+      editor.commands.setTextSelection(2)
+      let slashMenu = { query: '', from: 1, to: 2, left: 0, top: 0 }
+      const ctx = createContext(editor, false)
+      ctx.slashMenuRef.current = slashMenu
+      ctx.filteredSlashCommandsRef.current = [{ id: 'heading-1' } as never]
+      ctx.setSlashMenu = vi.fn((next) => {
+        slashMenu = typeof next === 'function' ? next(slashMenu) : next
+        ctx.slashMenuRef.current = slashMenu
+      })
+      const event = keyEvent('h')
+
+      expect(createRichMarkdownKeyHandler(ctx)(null, event)).toBe(true)
+      expect(event.preventDefault).toHaveBeenCalled()
+      expect(editor.getText()).toBe('/')
+      expect(ctx.slashMenuRef.current?.query).toBe('h')
+    } finally {
+      editor.destroy()
+    }
+  })
 })
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 70591cb00f9..c1bbd9851e1 100644
--- a/src/renderer/src/components/editor/rich-markdown-key-handler.ts
+++ b/src/renderer/src/components/editor/rich-markdown-key-handler.ts
@@ -31,6 +31,7 @@ export type KeyHandlerContext = {
   filteredDocLinkRowsRef: MutableRefObject<DocLinkMenuRow[]>
   selectedDocLinkIndexRef: MutableRefObject<number>
   handleLocalImagePickRef: MutableRefObject<() => void>
+  handleEmojiPickRef: MutableRefObject<(menu: SlashMenuState) => void>
   typedEmptyOrderedListMarkerRef: MutableRefObject<boolean>
   flushPendingSerialization: () => void
   openSearchRef: MutableRefObject<() => void>
@@ -38,7 +39,7 @@ export type KeyHandlerContext = {
   setLinkBubble: (bubble: LinkBubbleState | null) => void
   setSelectedCommandIndex: Dispatch<SetStateAction<number>>
   setSelectedDocLinkIndex: Dispatch<SetStateAction<number>>
-  setSlashMenu: (menu: SlashMenuState | null) => void
+  setSlashMenu: Dispatch<SetStateAction<SlashMenuState | null>>
   setDocLinkMenu: (menu: DocLinkMenuState | null) => void
 }
 
@@ -231,6 +232,20 @@ export function createRichMarkdownKeyHandler(
       return false
     }
 
+    if (!event.metaKey && !event.ctrlKey && !event.altKey && event.key.length === 1) {
+      event.preventDefault()
+      ctx.setSlashMenu((menu) => (menu ? { ...menu, query: `${menu.query}${event.key}` } : menu))
+      ctx.setSelectedCommandIndex(0)
+      return true
+    }
+
+    if (event.key === 'Backspace' && currentSlashMenu.query.length > 0) {
+      event.preventDefault()
+      ctx.setSlashMenu((menu) => (menu ? { ...menu, query: menu.query.slice(0, -1) } : menu))
+      ctx.setSelectedCommandIndex(0)
+      return true
+    }
+
     const currentFilteredSlashCommands = ctx.filteredSlashCommandsRef.current
     if (currentFilteredSlashCommands.length === 0) {
       return false
@@ -265,8 +280,12 @@ export function createRichMarkdownKeyHandler(
       // mirrors the latest highlighted slash-menu item for keyboard picks.
       const selectedCommand = currentFilteredSlashCommands[ctx.selectedCommandIndexRef.current]
       if (selectedCommand) {
-        runSlashCommand(activeEditor, currentSlashMenu, selectedCommand, () =>
-          ctx.handleLocalImagePickRef.current()
+        runSlashCommand(
+          activeEditor,
+          currentSlashMenu,
+          selectedCommand,
+          () => ctx.handleLocalImagePickRef.current(),
+          () => ctx.handleEmojiPickRef.current(currentSlashMenu)
         )
       }
       return true

From b7a00aaf0e65be033ec89c7428c4884dcbbef7bb Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Thu, 14 May 2026 22:15:44 -0700
Subject: [PATCH 16/82] fix: normalize empty markdown list items (#1897)

---
 .../editor/rich-markdown-normalize.test.ts    | 35 +++++++++++++++++
 .../editor/rich-markdown-normalize.ts         | 38 +++++++++++++++----
 2 files changed, 65 insertions(+), 8 deletions(-)
 create mode 100644 src/renderer/src/components/editor/rich-markdown-normalize.test.ts

diff --git a/src/renderer/src/components/editor/rich-markdown-normalize.test.ts b/src/renderer/src/components/editor/rich-markdown-normalize.test.ts
new file mode 100644
index 00000000000..7f81eb795c0
--- /dev/null
+++ b/src/renderer/src/components/editor/rich-markdown-normalize.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { Markdown } from '@tiptap/markdown'
+import { normalizeSoftBreaks } from './rich-markdown-normalize'
+
+const extensions = [StarterKit, Markdown.configure({ markedOptions: { gfm: true } })]
+
+function createEditor(content: string): Editor {
+  return new Editor({
+    element: null,
+    extensions,
+    content,
+    contentType: 'markdown'
+  })
+}
+
+describe('rich markdown normalization', () => {
+  it('normalizes empty ordered list items into caret targets', () => {
+    const editor = createEditor('1. Item 1\n2. Item 2\n3. \n\n## Next section\n')
+
+    try {
+      normalizeSoftBreaks(editor)
+
+      const list = editor.state.doc.child(0)
+      const emptyItem = list.child(2)
+      expect(emptyItem.type.name).toBe('listItem')
+      expect(emptyItem.childCount).toBe(1)
+      expect(emptyItem.child(0).type.name).toBe('paragraph')
+      expect(emptyItem.child(0).content.size).toBe(0)
+    } finally {
+      editor.destroy()
+    }
+  })
+})
diff --git a/src/renderer/src/components/editor/rich-markdown-normalize.ts b/src/renderer/src/components/editor/rich-markdown-normalize.ts
index a87aa972020..a3ead9a798b 100644
--- a/src/renderer/src/components/editor/rich-markdown-normalize.ts
+++ b/src/renderer/src/components/editor/rich-markdown-normalize.ts
@@ -10,8 +10,9 @@ import { Fragment, type Node as PmNode } from '@tiptap/pm/model'
  * of just one logical line.
  *
  * This function normalises the ProseMirror document by splitting any paragraph whose
- * text nodes contain `\n` into separate paragraph nodes — one per line.  Inline marks
- * (bold, italic, links, etc.) are preserved on each resulting paragraph.  This is
+ * text nodes contain `\n` into separate paragraph nodes — one per line — and by
+ * giving empty parsed list items a paragraph caret target. Inline marks (bold,
+ * italic, links, etc.) are preserved on each resulting paragraph. This is
  * structurally correct for the editing model: each visual line becomes its own block,
  * so the cut handler (and all other block-level operations) work on a per-line basis.
  */
@@ -30,9 +31,24 @@ export function normalizeSoftBreaks(editor: Editor): void {
   // Why: doc.forEach only iterates top-level children, so paragraphs nested inside
   // blockquotes, table cells, or other container nodes would be missed.
   // doc.descendants walks every node at every depth and provides absolute positions.
-  const replacements: { from: number; to: number; paragraphs: Fragment[] }[] = []
+  const replacements: (
+    | { from: number; to: number; kind: 'soft-break-paragraphs'; paragraphs: Fragment[] }
+    | { from: number; to: number; kind: 'empty-list-item'; node: PmNode }
+  )[] = []
 
   doc.descendants((node, pos) => {
+    if (node.type.name === 'listItem' && node.childCount === 0) {
+      // Why: marked parses `3. ` immediately before a heading as a list item
+      // with no paragraph. It renders a marker but has no editable caret target.
+      replacements.push({
+        from: pos,
+        to: pos + node.nodeSize,
+        kind: 'empty-list-item',
+        node: node.type.create(node.attrs, paragraphType.create(), node.marks)
+      })
+      return false
+    }
+
     if (node.type !== paragraphType) {
       return true // continue descending into container nodes
     }
@@ -77,6 +93,7 @@ export function normalizeSoftBreaks(editor: Editor): void {
     replacements.push({
       from: pos,
       to: pos + node.nodeSize,
+      kind: 'soft-break-paragraphs',
       paragraphs: lines
     })
 
@@ -90,11 +107,16 @@ export function normalizeSoftBreaks(editor: Editor): void {
   // Capture the transaction lazily — only after all replacements are collected.
   const tr = editor.view.state.tr
 
-  // Apply replacements in reverse order to preserve positions.
-  for (let i = replacements.length - 1; i >= 0; i--) {
-    const { from, to, paragraphs } = replacements[i]
-    const newNodes = paragraphs.map((content) => paragraphType.create(null, content))
-    tr.replaceWith(from, to, newNodes)
+  // Apply replacements in reverse document order to preserve positions.
+  replacements.sort((a, b) => b.from - a.from)
+  for (const replacement of replacements) {
+    if (replacement.kind === 'empty-list-item') {
+      tr.replaceWith(replacement.from, replacement.to, replacement.node)
+      continue
+    }
+
+    const newNodes = replacement.paragraphs.map((content) => paragraphType.create(null, content))
+    tr.replaceWith(replacement.from, replacement.to, newNodes)
   }
 
   // Why: this normalization is a structural housekeeping step, not a user edit.

From a9b47759fa88e1b0478dbddd3be8b6d710dbf7d8 Mon Sep 17 00:00:00 2001
From: "buf0-bot[bot]" <252831055+buf0-bot[bot]@users.noreply.github.com>
Date: Thu, 14 May 2026 22:34:22 -0700
Subject: [PATCH 17/82] fix: pr-bug-scan validated finding from #1857 (#1886)

* fix: address pr-bug-scan validated finding from #1857

Restored alt-buffer guards at both the double-rAF and 200ms phases of scheduleSplitScrollRestore so TUI panes skip restoreScrollState+refresh, blocking the #1298 cursor-drift regression.

* fix: preserve split scroll state around alternate buffers

---------

Co-authored-by: orca-bug-scan-bot <orca-bug-scan-bot@stably.ai>
Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
---
 .../pane-fit-resize-observer.test.ts          |   1 +
 .../lib/pane-manager/pane-manager-types.ts    |   1 +
 .../src/lib/pane-manager/pane-scroll.ts       |   3 +-
 .../pane-manager/pane-split-scroll.test.ts    | 180 ++++++++++++++++++
 .../src/lib/pane-manager/pane-split-scroll.ts |  83 +++++++-
 .../lib/pane-manager/pane-tree-ops.test.ts    |   1 +
 6 files changed, 260 insertions(+), 9 deletions(-)
 create mode 100644 src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts

diff --git a/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts b/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts
index c2cdb6e03a8..2085a3fa407 100644
--- a/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts
@@ -62,6 +62,7 @@ function createPane(): ManagedPaneInternal {
     compositionHandler: null,
     debugLabel: null,
     pendingSplitScrollState: {
+      bufferType: 'normal',
       wasAtBottom: true,
       firstVisibleLineContent: '',
       viewportY: 0,
diff --git a/src/renderer/src/lib/pane-manager/pane-manager-types.ts b/src/renderer/src/lib/pane-manager/pane-manager-types.ts
index 32041bd811f..08d1661f135 100644
--- a/src/renderer/src/lib/pane-manager/pane-manager-types.ts
+++ b/src/renderer/src/lib/pane-manager/pane-manager-types.ts
@@ -67,6 +67,7 @@ export type ManagedPane = {
 // ---------------------------------------------------------------------------
 
 export type ScrollState = {
+  bufferType: 'normal' | 'alternate'
   wasAtBottom: boolean
   firstVisibleLineContent: string
   viewportY: number
diff --git a/src/renderer/src/lib/pane-manager/pane-scroll.ts b/src/renderer/src/lib/pane-manager/pane-scroll.ts
index 6f430476246..ff895174c1e 100644
--- a/src/renderer/src/lib/pane-manager/pane-scroll.ts
+++ b/src/renderer/src/lib/pane-manager/pane-scroll.ts
@@ -51,11 +51,12 @@ export function findLineByContent(terminal: Terminal, content: string, hintRatio
 
 export function captureScrollState(terminal: Terminal): ScrollState {
   const buf = terminal.buffer.active
+  const bufferType = buf.type
   const viewportY = buf.viewportY
   const wasAtBottom = viewportY >= buf.baseY
   const firstVisibleLineContent = buf.getLine(viewportY)?.translateToString(true)?.trimEnd() ?? ''
   const totalLines = buf.baseY + terminal.rows
-  return { wasAtBottom, firstVisibleLineContent, viewportY, totalLines }
+  return { bufferType, wasAtBottom, firstVisibleLineContent, viewportY, totalLines }
 }
 
 export function restoreScrollState(terminal: Terminal, state: ScrollState): void {
diff --git a/src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts b/src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts
new file mode 100644
index 00000000000..4b059bb2991
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts
@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ManagedPaneInternal, ScrollState } from './pane-manager-types'
+
+const restoreScrollState = vi.hoisted(() => vi.fn())
+
+vi.mock('./pane-scroll', () => ({
+  restoreScrollState
+}))
+
+import { scheduleSplitScrollRestore } from './pane-split-scroll'
+
+const scrollState = {
+  bufferType: 'normal',
+  wasAtBottom: true,
+  firstVisibleLineContent: '',
+  viewportY: 0,
+  totalLines: 24
+} satisfies ScrollState
+
+const alternateScrollState = {
+  ...scrollState,
+  bufferType: 'alternate'
+} satisfies ScrollState
+
+function createPane(bufferType: 'normal' | 'alternate'): {
+  pane: ManagedPaneInternal
+  bufferChangeDisposable: { dispose: ReturnType<typeof vi.fn> }
+  triggerBufferChange: (bufferType: 'normal' | 'alternate') => void
+} {
+  let bufferChangeHandler: ((buffer: { type: 'normal' | 'alternate' }) => void) | null = null
+  const bufferChangeDisposable = { dispose: vi.fn() }
+  const pane: ManagedPaneInternal = {
+    id: 1,
+    terminal: {
+      rows: 24,
+      refresh: vi.fn(),
+      buffer: {
+        active: {
+          type: bufferType,
+          length: 24
+        },
+        onBufferChange: vi.fn((handler: (buffer: { type: 'normal' | 'alternate' }) => void) => {
+          bufferChangeHandler = handler
+          return bufferChangeDisposable
+        })
+      }
+    } as never,
+    container: {
+      querySelectorAll: vi.fn(() => [])
+    } as never,
+    xtermContainer: {} as never,
+    linkTooltip: {} as never,
+    terminalGpuAcceleration: 'auto',
+    gpuRenderingEnabled: true,
+    webglAttachmentDeferred: false,
+    webglDisabledAfterContextLoss: false,
+    hasComplexScriptOutput: false,
+    webglAddon: null,
+    ligaturesAddon: null,
+    fitResizeObserver: null,
+    pendingObservedFitRafId: null,
+    fitAddon: {} as never,
+    searchAddon: {} as never,
+    serializeAddon: {
+      serialize: vi.fn(() => '')
+    } as never,
+    unicode11Addon: {} as never,
+    webLinksAddon: {} as never,
+    compositionHandler: null,
+    pendingSplitScrollState: scrollState,
+    debugLabel: null
+  }
+  return {
+    pane,
+    bufferChangeDisposable,
+    triggerBufferChange: (bufferType) => bufferChangeHandler?.({ type: bufferType })
+  }
+}
+
+describe('scheduleSplitScrollRestore', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      callback(16)
+      return 1
+    })
+    restoreScrollState.mockClear()
+  })
+
+  afterEach(() => {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  it('restores and refreshes normal-screen panes after split reparenting settles', () => {
+    const { pane } = createPane('normal')
+    const reattachWebgl = vi.fn()
+
+    scheduleSplitScrollRestore(
+      () => pane,
+      pane.id,
+      scrollState,
+      () => false,
+      reattachWebgl
+    )
+
+    expect(restoreScrollState).toHaveBeenCalledTimes(1)
+    expect(pane.terminal.refresh).toHaveBeenCalledWith(0, 23)
+
+    vi.advanceTimersByTime(200)
+
+    expect(pane.pendingSplitScrollState).toBeNull()
+    expect(reattachWebgl).toHaveBeenCalledWith(pane)
+    expect(restoreScrollState).toHaveBeenCalledTimes(2)
+    expect(pane.terminal.refresh).toHaveBeenCalledTimes(2)
+  })
+
+  it('defers WebGL reattach and skips scroll restore for alternate-screen panes', () => {
+    const { pane, bufferChangeDisposable, triggerBufferChange } = createPane('alternate')
+    const reattachWebgl = vi.fn()
+
+    scheduleSplitScrollRestore(
+      () => pane,
+      pane.id,
+      alternateScrollState,
+      () => false,
+      reattachWebgl
+    )
+
+    expect(restoreScrollState).not.toHaveBeenCalled()
+    expect(pane.terminal.refresh).not.toHaveBeenCalled()
+    expect(pane.pendingSplitScrollState).toBe(scrollState)
+
+    vi.advanceTimersByTime(200)
+
+    expect(pane.pendingSplitScrollState).toBeNull()
+    expect(reattachWebgl).not.toHaveBeenCalled()
+    expect(restoreScrollState).not.toHaveBeenCalled()
+    expect(pane.terminal.refresh).not.toHaveBeenCalled()
+
+    triggerBufferChange('alternate')
+
+    expect(reattachWebgl).not.toHaveBeenCalled()
+    expect(bufferChangeDisposable.dispose).not.toHaveBeenCalled()
+
+    triggerBufferChange('normal')
+
+    expect(bufferChangeDisposable.dispose).toHaveBeenCalledTimes(1)
+    expect(reattachWebgl).toHaveBeenCalledWith(pane)
+    expect(restoreScrollState).not.toHaveBeenCalled()
+    expect(pane.terminal.refresh).not.toHaveBeenCalled()
+  })
+
+  it('defers normal-screen scroll restore until an active TUI exits alternate screen', () => {
+    const { pane, triggerBufferChange } = createPane('alternate')
+    const reattachWebgl = vi.fn()
+
+    scheduleSplitScrollRestore(
+      () => pane,
+      pane.id,
+      scrollState,
+      () => false,
+      reattachWebgl
+    )
+
+    vi.advanceTimersByTime(200)
+
+    expect(pane.pendingSplitScrollState).toBe(scrollState)
+    expect(restoreScrollState).not.toHaveBeenCalled()
+    expect(pane.terminal.refresh).not.toHaveBeenCalled()
+
+    triggerBufferChange('normal')
+
+    expect(pane.pendingSplitScrollState).toBeNull()
+    expect(reattachWebgl).toHaveBeenCalledWith(pane)
+    expect(restoreScrollState).toHaveBeenCalledWith(pane.terminal, scrollState)
+    expect(pane.terminal.refresh).toHaveBeenCalledWith(0, 23)
+  })
+})
diff --git a/src/renderer/src/lib/pane-manager/pane-split-scroll.ts b/src/renderer/src/lib/pane-manager/pane-split-scroll.ts
index ac102135d15..b8b00747cad 100644
--- a/src/renderer/src/lib/pane-manager/pane-split-scroll.ts
+++ b/src/renderer/src/lib/pane-manager/pane-split-scroll.ts
@@ -1,3 +1,4 @@
+import type { IBuffer, IDisposable } from '@xterm/xterm'
 import type { ManagedPaneInternal, ScrollState } from './pane-manager-types'
 import { restoreScrollState } from './pane-scroll'
 
@@ -9,6 +10,43 @@ function refreshAfterReparent(pane: ManagedPaneInternal): void {
   }
 }
 
+function runAfterNormalBuffer(
+  pane: ManagedPaneInternal,
+  getPaneById: (id: number) => ManagedPaneInternal | undefined,
+  paneId: number,
+  isDestroyed: () => boolean,
+  callback: (pane: ManagedPaneInternal) => void
+): void {
+  let disposable: IDisposable | null = null
+  disposable = pane.terminal.buffer.onBufferChange((buffer: IBuffer) => {
+    if (buffer.type === 'alternate') {
+      return
+    }
+    disposable?.dispose()
+    disposable = null
+    if (isDestroyed()) {
+      return
+    }
+    const live = getPaneById(paneId)
+    if (live) {
+      callback(live)
+    }
+  })
+}
+
+function restoreCapturedScrollState(
+  pane: ManagedPaneInternal,
+  scrollState: ScrollState,
+  reattachWebgl?: (pane: ManagedPaneInternal) => void
+): void {
+  pane.pendingSplitScrollState = null
+  if (reattachWebgl) {
+    reattachWebgl(pane)
+  }
+  restoreScrollState(pane.terminal, scrollState)
+  refreshAfterReparent(pane)
+}
+
 function logPaneHealth(pane: ManagedPaneInternal, phase: string): void {
   const canvases = pane.container.querySelectorAll('canvas')
   const canvasInfo = Array.from(canvases).map((c) => {
@@ -89,10 +127,19 @@ export function scheduleSplitScrollRestore(
         return
       }
       const live = getPaneById(paneId)
-      if (live?.pendingSplitScrollState) {
-        restoreScrollState(live.terminal, scrollState)
-        refreshAfterReparent(live)
+      if (!live?.pendingSplitScrollState) {
+        return
       }
+      // Why: see the 200ms timer below — the alt-screen buffer belongs to a
+      // TUI and restore-during-draw knocks its cursor one row off (#1298).
+      if (
+        scrollState.bufferType === 'alternate' ||
+        live.terminal.buffer.active.type === 'alternate'
+      ) {
+        return
+      }
+      restoreScrollState(live.terminal, scrollState)
+      refreshAfterReparent(live)
     })
   })
 
@@ -104,12 +151,32 @@ export function scheduleSplitScrollRestore(
     if (!live) {
       return
     }
-    live.pendingSplitScrollState = null
-    if (reattachWebgl) {
-      reattachWebgl(live)
+    // Why: the alt-screen buffer belongs to a full-screen TUI (Claude Code,
+    // vim, less) that owns its cursor position. Re-running scroll restore
+    // and a full refresh here clobbers an in-progress draw — refresh(0,
+    // rows-1) repaints rows from xterm's buffer, racing the TUI's next
+    // write and leaving its cursor one row off (#1298 regression).
+    // WebGL reattach also refreshes, so defer it until the TUI exits the
+    // alternate buffer. Alt-screen has no scrollback, so scroll restore has
+    // nothing legitimate to do.
+    if (scrollState.bufferType === 'alternate') {
+      live.pendingSplitScrollState = null
+      if (live.terminal.buffer.active.type === 'alternate' && reattachWebgl) {
+        runAfterNormalBuffer(live, getPaneById, paneId, isDestroyed, reattachWebgl)
+        return
+      }
+      if (reattachWebgl) {
+        reattachWebgl(live)
+      }
+      return
     }
-    restoreScrollState(live.terminal, scrollState)
-    refreshAfterReparent(live)
+    if (live.terminal.buffer.active.type === 'alternate') {
+      runAfterNormalBuffer(live, getPaneById, paneId, isDestroyed, (normalPane) => {
+        restoreCapturedScrollState(normalPane, scrollState, reattachWebgl)
+      })
+      return
+    }
+    restoreCapturedScrollState(live, scrollState, reattachWebgl)
   }, 200)
 
   setTimeout(() => {
diff --git a/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts b/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
index 695f3aaeb2d..f0c78cce205 100644
--- a/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
@@ -106,6 +106,7 @@ describe('safeFit', () => {
       terminalRows: 32
     })
     pane.pendingSplitScrollState = {
+      bufferType: 'normal',
       wasAtBottom: true,
       firstVisibleLineContent: '',
       viewportY: 0,

From 89827117e589b1b1ddc9adc42f8aa87efa261ac9 Mon Sep 17 00:00:00 2001
From: "buf0-bot[bot]" <252831055+buf0-bot[bot]@users.noreply.github.com>
Date: Thu, 14 May 2026 22:54:34 -0700
Subject: [PATCH 18/82] fix: pr-bug-scan validated finding from #1865 (#1888)

* fix: address pr-bug-scan validated finding from #1865

SIGKILL fallback in graceful pty.shutdown now emits pty.exit before notifyExitListener; renderer sees the exit even though onExit short-circuits on disposed.

* test: cover relay pty kill fallback exit

---------

Co-authored-by: orca-bug-scan-bot <orca-bug-scan-bot@stably.ai>
Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
---
 src/relay/pty-handler.test.ts | 26 ++++++++++++++++++++++++++
 src/relay/pty-handler.ts      |  5 +++++
 2 files changed, 31 insertions(+)

diff --git a/src/relay/pty-handler.test.ts b/src/relay/pty-handler.test.ts
index e806237a429..d52b5b1ea5b 100644
--- a/src/relay/pty-handler.test.ts
+++ b/src/relay/pty-handler.test.ts
@@ -284,6 +284,32 @@ describe('PtyHandler', () => {
     expect(mockKill).toHaveBeenCalledWith('SIGTERM')
   })
 
+  it('notifies pty.exit when graceful shutdown falls back to SIGKILL', async () => {
+    let onExitCb: ((evt: { exitCode: number }) => void) | undefined
+    const mockKill = vi.fn()
+    mockPtySpawn.mockReturnValue({
+      ...mockPtyInstance,
+      kill: mockKill,
+      onData: vi.fn(),
+      onExit: vi.fn((cb: (evt: { exitCode: number }) => void) => {
+        onExitCb = cb
+      })
+    })
+    const exits: { id: string; paneKey?: string }[] = []
+    handler.setExitListener((evt) => exits.push(evt))
+
+    await dispatcher.callRequest('pty.spawn', { env: { ORCA_PANE_KEY: 'tab-fallback:0' } })
+    await dispatcher.callRequest('pty.shutdown', { id: 'pty-1', immediate: false })
+    vi.advanceTimersByTime(5000)
+    onExitCb!({ exitCode: 137 })
+
+    expect(mockKill).toHaveBeenCalledWith('SIGTERM')
+    expect(mockKill).toHaveBeenCalledWith('SIGKILL')
+    expect(dispatcher.notify).toHaveBeenCalledWith('pty.exit', { id: 'pty-1', code: -1 })
+    expect(exits).toEqual([{ id: 'pty-1', paneKey: 'tab-fallback:0' }])
+    expect(handler.activePtyCount).toBe(0)
+  })
+
   it('kills PTY on shutdown with SIGKILL when immediate', async () => {
     const mockKill = vi.fn()
     mockPtySpawn.mockReturnValue({
diff --git a/src/relay/pty-handler.ts b/src/relay/pty-handler.ts
index b1b540cb867..deb6658b838 100644
--- a/src/relay/pty-handler.ts
+++ b/src/relay/pty-handler.ts
@@ -444,6 +444,11 @@ export class PtyHandler {
         const still = this.ptys.get(id)
         if (still && !still.disposed) {
           still.pty.kill('SIGKILL')
+          // Why: emit pty.exit BEFORE disposeManagedPty sets disposed=true.
+          // The natural onExit short-circuits on `managed.disposed`, so
+          // without this notify the renderer never learns the pane is dead
+          // when the SIGKILL fallback fires for a SIGTERM-ignoring child.
+          this.dispatcher.notify('pty.exit', { id, code: -1 })
           // Why: if SIGKILL's onExit never fires (kernel edge case,
           // uninterruptible sleep, child wedged on a bad NFS mount), the
           // fd and map entry would leak forever. Dispose synchronously so

From a22717bb35d50fcef57348039bbe0f4a7c4fa714 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 15 May 2026 02:13:37 -0400
Subject: [PATCH 19/82] Refactor runtime app architecture (#1878)

Co-authored-by: Orca <help@stably.ai>
---
 .gitignore                                    |    3 +
 config/electron-builder.config.cjs            |    4 +
 .../expo-two-way-audio/ios/AudioEngine.swift  |  116 +-
 mobile/scripts/test-subscribe.ts              |    9 +-
 mobile/src/transport/protocol-version.ts      |   10 +-
 package.json                                  |    2 +-
 src/cli/args.ts                               |    3 +-
 src/cli/dispatch.ts                           |    2 +
 src/cli/format.ts                             |   28 +
 src/cli/handlers/core.ts                      |   27 +
 src/cli/handlers/environment.ts               |   75 +
 src/cli/handlers/repo.ts                      |   31 +-
 src/cli/handlers/terminal.ts                  |    6 +
 src/cli/help.ts                               |   15 +
 src/cli/index.test.ts                         |  369 +-
 src/cli/index.ts                              |   14 +-
 src/cli/runtime-client.ts                     |    1 +
 src/cli/runtime/client.ts                     |  137 +-
 src/cli/runtime/envelope-schema.ts            |   67 +-
 src/cli/runtime/environments.test.ts          |   68 +
 src/cli/runtime/environments.ts               |   81 +
 src/cli/runtime/index.ts                      |    1 +
 src/cli/runtime/launch.test.ts                |   88 +
 src/cli/runtime/launch.ts                     |   89 +-
 src/cli/runtime/status.ts                     |    2 +-
 src/cli/runtime/transport.ts                  |    6 +-
 src/cli/runtime/types.ts                      |   33 +-
 src/cli/runtime/websocket-transport.test.ts   |  237 ++
 src/cli/runtime/websocket-transport.ts        |   22 +
 src/cli/selectors.ts                          |   29 +-
 src/cli/specs/core.ts                         |   18 +
 src/cli/specs/environment.ts                  |   30 +
 src/cli/specs/index.ts                        |    2 +
 src/main/cli/packaged-cli-assets.test.ts      |   19 +
 src/main/git/status.test.ts                   |   12 +-
 src/main/git/status.ts                        |   13 +-
 src/main/index.ts                             |  202 +-
 .../ipc/filesystem-import-ssh-ops.test.ts     |   11 +-
 src/main/ipc/filesystem-import-ssh.test.ts    |   49 +-
 src/main/ipc/filesystem-import-ssh.ts         |   10 +-
 src/main/ipc/filesystem-import.test.ts        |  290 +-
 src/main/ipc/filesystem-mutations.test.ts     |   46 +-
 src/main/ipc/filesystem-mutations.ts          |  350 +-
 src/main/ipc/filesystem-watcher.test.ts       |   31 +
 src/main/ipc/filesystem-watcher.ts            |   12 +-
 src/main/ipc/mobile.test.ts                   |   72 +
 src/main/ipc/mobile.ts                        |   41 +-
 src/main/ipc/pty.ts                           |   35 +
 src/main/ipc/register-core-handlers.test.ts   |    8 +
 src/main/ipc/register-core-handlers.ts        |    2 +
 .../ipc/runtime-environment-call-queue.ts     |   92 +
 ...runtime-environment-request-connections.ts |   46 +
 src/main/ipc/runtime-environments.test.ts     |  615 +++
 src/main/ipc/runtime-environments.ts          |  313 ++
 src/main/ipc/runtime.test.ts                  |   32 +-
 src/main/ipc/runtime.ts                       |   18 +
 src/main/ipc/worktree-remote.ts               |    4 +-
 src/main/powershell-osc133-bootstrap.test.ts  |   11 +-
 src/main/powershell-osc133-bootstrap.ts       |   10 +-
 .../providers/ssh-filesystem-provider.test.ts |  167 +
 src/main/providers/ssh-filesystem-provider.ts |   94 +-
 src/main/providers/types.ts                   |    3 +
 src/main/providers/windows-shell-args.test.ts |    7 +-
 src/main/repo-worktrees.ts                    |    8 +
 src/main/runtime/device-registry.ts           |   37 +-
 src/main/runtime/e2ee-keypair.ts              |    7 +-
 src/main/runtime/mobile-presence-lock.test.ts |   21 +
 src/main/runtime/orca-runtime-browser.ts      | 1455 +++++++
 src/main/runtime/orca-runtime-files.test.ts   |  112 +
 src/main/runtime/orca-runtime-files.ts        |  918 +++++
 src/main/runtime/orca-runtime-git.ts          |  308 ++
 src/main/runtime/orca-runtime.test.ts         |  554 ++-
 src/main/runtime/orca-runtime.ts              | 3586 +++++++++--------
 .../orchestration-cli-subprocess.test.ts}     |   14 +-
 ...ime-request-connection.integration.test.ts |   67 +
 src/main/runtime/rpc/core.ts                  |    8 +
 src/main/runtime/rpc/dispatcher.ts            |   14 +-
 src/main/runtime/rpc/e2ee-channel.test.ts     |   16 +-
 src/main/runtime/rpc/e2ee-channel.ts          |   13 +
 src/main/runtime/rpc/e2ee-crypto.ts           |   61 +-
 src/main/runtime/rpc/methods/browser-core.ts  |   16 +
 .../runtime/rpc/methods/browser-schemas.ts    |    6 +
 src/main/runtime/rpc/methods/browser.test.ts  |  144 +
 .../rpc/methods/file-watch-event-batcher.ts   |   65 +
 src/main/runtime/rpc/methods/files.test.ts    |  394 ++
 src/main/runtime/rpc/methods/files.ts         |  286 +-
 src/main/runtime/rpc/methods/git.test.ts      |  157 +
 src/main/runtime/rpc/methods/git.ts           |  175 +
 src/main/runtime/rpc/methods/github.test.ts   |  519 +++
 src/main/runtime/rpc/methods/github.ts        |  442 ++
 .../runtime/rpc/methods/hosted-review.test.ts |   48 +
 src/main/runtime/rpc/methods/hosted-review.ts |   26 +
 src/main/runtime/rpc/methods/index.ts         |    8 +
 src/main/runtime/rpc/methods/linear.test.ts   |  101 +
 src/main/runtime/rpc/methods/linear.ts        |  136 +
 src/main/runtime/rpc/methods/notes.test.ts    |  148 +
 src/main/runtime/rpc/methods/notes.ts         |   88 +-
 .../runtime/rpc/methods/orchestration.test.ts |   36 +
 src/main/runtime/rpc/methods/orchestration.ts |    6 +
 src/main/runtime/rpc/methods/repo.test.ts     |   96 +
 src/main/runtime/rpc/methods/repo.ts          |   94 +-
 src/main/runtime/rpc/methods/terminal.ts      |  642 ++-
 src/main/runtime/rpc/methods/worktree.test.ts |   64 +
 src/main/runtime/rpc/methods/worktree.ts      |  104 +-
 src/main/runtime/rpc/streaming.test.ts        |   55 +
 .../runtime/rpc/terminal-multiplex.test.ts    |  395 ++
 .../rpc/terminal-output-batching.test.ts      |  249 ++
 src/main/runtime/rpc/terminal-send.test.ts    |  104 +
 .../rpc/terminal-subscribe-buffer.test.ts     |  104 +
 src/main/runtime/rpc/ws-transport.test.ts     |  108 +-
 src/main/runtime/rpc/ws-transport.ts          |   84 +-
 src/main/runtime/runtime-metadata.test.ts     |   95 +-
 src/main/runtime/runtime-metadata.ts          |   97 +-
 src/main/runtime/runtime-relative-paths.ts    |   29 +
 src/main/runtime/runtime-rpc.test.ts          |  484 +++
 src/main/runtime/runtime-rpc.ts               |  245 +-
 src/main/ssh/sftp-upload.test.ts              |   63 +
 src/main/ssh/sftp-upload.ts                   |  114 +-
 src/main/ssh/ssh-relay-session.ts             |   16 +-
 src/preload/api-types.ts                      |   71 +
 src/preload/index.ts                          |   79 +
 .../runtime-environment-subscriptions.test.ts |  103 +
 .../runtime-environment-subscriptions.ts      |   99 +
 src/relay/fs-handler.test.ts                  |   64 +
 src/relay/fs-handler.ts                       |   30 +-
 src/renderer/src/App.tsx                      |    8 +-
 src/renderer/src/app-startup-routing.test.ts  |   20 +
 .../src/components/GitHubItemDialog.tsx       |  304 +-
 .../src/components/LinearItemDrawer.tsx       |   53 +-
 src/renderer/src/components/QuickOpen.tsx     |   20 +-
 src/renderer/src/components/TaskPage.tsx      |  107 +-
 .../TelemetryFirstLaunchSurface.tsx           |    5 +-
 src/renderer/src/components/Terminal.tsx      |    9 +-
 .../src/components/WorktreeJumpPalette.tsx    |   64 +-
 .../automations/CreateFromPicker.tsx          |   18 +-
 .../components/browser-pane/BrowserPane.tsx   |  524 ++-
 .../components/editor/CombinedDiffViewer.tsx  |   70 +-
 .../src/components/editor/EditorContent.tsx   |    1 +
 .../src/components/editor/EditorPanel.tsx     |  136 +-
 .../src/components/editor/MarkdownPreview.tsx |   61 +-
 .../editor/MonacoGutterContextMenu.tsx        |   16 +-
 .../components/editor/RichMarkdownEditor.tsx  |   58 +-
 .../editor/UntitledFileRenameDialog.tsx       |    7 +-
 .../editor/editor-autosave-controller.test.ts |   74 +
 .../editor/editor-autosave-controller.ts      |   24 +-
 .../editor/rich-markdown-extensions.ts        |    8 +-
 .../src/components/editor/useLinkBubble.ts    |    5 +-
 .../components/editor/useLocalImagePick.ts    |   62 +-
 .../editor/useLocalImageSrc.test.ts           |   25 +
 .../src/components/editor/useLocalImageSrc.ts |   72 +-
 .../components/editor/useMarkdownDocuments.ts |   48 +-
 .../FloatingTerminalPanel.tsx                 |    6 +-
 .../components/github-project/ProjectCell.tsx |  105 +-
 .../github-project/ProjectPicker.tsx          |   75 +-
 .../github-project/ProjectViewWrapper.tsx     |   36 +-
 .../slug-dialog/AssigneesEditor.tsx           |   51 +-
 .../github-project/slug-dialog/Comments.tsx   |   48 +-
 .../slug-dialog/LabelsEditor.tsx              |   41 +-
 .../components/github/GitHubRateLimitPill.tsx |   51 +-
 .../new-workspace/SmartWorkspaceNameField.tsx |  152 +-
 .../notes/ProjectNotesTabContent.tsx          |   42 +-
 .../components/onboarding/OnboardingFlow.tsx  |    6 +
 .../src/components/onboarding/RepoStep.tsx    |  120 +-
 .../onboarding/use-onboarding-flow.ts         |  119 +-
 .../components/right-sidebar/ChecksPanel.tsx  |   20 +-
 .../components/right-sidebar/FileExplorer.tsx |    2 +-
 .../right-sidebar/FileExplorerRow.tsx         |   22 +-
 .../components/right-sidebar/NotesPanel.tsx   |   18 +-
 .../components/right-sidebar/PRActions.tsx    |   22 +-
 .../src/components/right-sidebar/Search.tsx   |   36 +-
 .../right-sidebar/SourceControl.tsx           |  137 +-
 .../right-sidebar/git-status-refresh.ts       |    9 +-
 .../right-sidebar/useFileDeletion.ts          |   46 +-
 .../right-sidebar/useFileDuplicate.ts         |   18 +-
 .../right-sidebar/useFileExplorerDragDrop.ts  |   13 +-
 .../right-sidebar/useFileExplorerImport.ts    |   28 +-
 .../useFileExplorerInlineInput.ts             |   23 +-
 .../right-sidebar/useFileExplorerTree.ts      |   12 +-
 .../useFileExplorerWatch.test.ts              |   40 +
 .../right-sidebar/useFileExplorerWatch.ts     |  126 +-
 .../right-sidebar/useGitStatusPolling.test.ts |    8 +-
 .../right-sidebar/useGitStatusPolling.ts      |    6 +-
 .../src/components/settings/BaseRefPicker.tsx |   21 +-
 .../settings/ManageSessionsSection.tsx        |   36 +-
 .../settings/RepositoryHooksSection.tsx       |   14 +-
 .../settings/RuntimeEnvironmentsPane.tsx      |  413 ++
 .../src/components/settings/Settings.tsx      |   35 +-
 .../settings/WorktreeSymlinksSection.tsx      |    8 +-
 .../components/sidebar/AddRepoCreateStep.tsx  |   50 +-
 .../src/components/sidebar/AddRepoDialog.tsx  |  144 +-
 .../src/components/sidebar/AddRepoSteps.tsx   |    5 +-
 .../src/components/sidebar/WorktreeCard.tsx   |    5 +-
 .../sidebar/WorktreeContextMenu.tsx           |   11 +-
 .../src/components/sidebar/WorktreeList.tsx   |   11 +-
 .../status-bar/ResourceUsageStatusSegment.tsx |   83 +-
 .../src/components/tab-bar/EditorFileTab.tsx  |   16 +-
 .../src/components/tab-bar/TabBar.tsx         |    6 +-
 .../editor-tab-local-open-guard.test.ts       |   22 +
 .../tab-bar/editor-tab-local-open-guard.ts    |   13 +
 .../tab-group/useTabGroupWorkspaceModel.ts    |   26 +-
 .../components/terminal-pane/TerminalPane.tsx |   60 +-
 .../terminal-pane/pty-connection.test.ts      |   74 +-
 .../terminal-pane/pty-connection.ts           |   79 +-
 .../terminal-pane/pty-transport.test.ts       |  220 +
 .../components/terminal-pane/pty-transport.ts |  286 +-
 .../remote-runtime-pty-batching.ts            |   81 +
 .../remote-runtime-pty-binary-control.ts      |   47 +
 .../remote-runtime-pty-transport.test.ts      |  512 +++
 .../remote-runtime-pty-transport.ts           |  324 ++
 .../terminal-pane/resolve-split-cwd.test.ts   |   20 +-
 .../terminal-pane/resolve-split-cwd.ts        |    3 +-
 .../terminal-drop-handler.test.ts             |  166 +
 .../terminal-pane/terminal-drop-handler.ts    |  139 +-
 .../terminal-link-handlers.test.ts            |  150 +-
 .../terminal-pane/terminal-link-handlers.ts   |   70 +-
 .../use-terminal-pane-lifecycle.ts            |   20 +-
 src/renderer/src/hooks/useComposerState.ts    |  353 +-
 .../src/hooks/useEditorExternalWatch.test.ts  |  108 +-
 .../src/hooks/useEditorExternalWatch.ts       |  111 +-
 .../src/hooks/useGitHubSlugMetadata.ts        |   70 +-
 .../src/hooks/useGlobalFileDrop.test.ts       |   20 +
 src/renderer/src/hooks/useGlobalFileDrop.ts   |   82 +-
 src/renderer/src/hooks/useIpcEvents.ts        |   98 +-
 src/renderer/src/hooks/useIssueMetadata.ts    |  157 +-
 src/renderer/src/lib/agent-paste-draft.ts     |   28 +-
 src/renderer/src/lib/agent-ready-wait.ts      |    7 +-
 .../src/lib/codex-session-restart.test.ts     |   68 +-
 src/renderer/src/lib/codex-session-restart.ts |    7 +-
 .../src/lib/create-untitled-markdown.test.ts  |   89 +-
 .../src/lib/create-untitled-markdown.ts       |   17 +-
 .../src/lib/ensure-hooks-confirmed.ts         |    5 +-
 .../src/lib/http-link-routing.test.ts         |   14 +-
 src/renderer/src/lib/http-link-routing.ts     |    8 +-
 .../launch-agent-background-session.test.ts   |   73 +-
 .../lib/launch-agent-background-session.ts    |  101 +-
 .../src/lib/launch-work-item-direct.ts        |    3 +-
 .../src/lib/local-path-open-guard.test.ts     |   18 +
 src/renderer/src/lib/local-path-open-guard.ts |   15 +
 src/renderer/src/lib/new-workspace.ts         |   12 +-
 .../src/lib/open-project-notes-tab.ts         |    6 +-
 src/renderer/src/lib/rename-file.ts           |   13 +-
 src/renderer/src/lib/repo-slug-index.ts       |   65 +-
 src/renderer/src/lib/workspace-session.ts     |    3 +-
 .../src/runtime/mobile-markdown-bridge.ts     |    8 +-
 .../src/runtime/remote-file-client.ts         |   22 +
 .../remote-runtime-terminal-multiplexer.ts    |  379 ++
 .../runtime-compatibility-test-fixture.ts     |   37 +
 .../src/runtime/runtime-file-client.test.ts   | 1186 ++++++
 .../src/runtime/runtime-file-client.ts        |  860 ++++
 .../src/runtime/runtime-git-client.test.ts    |  144 +
 .../src/runtime/runtime-git-client.ts         |  340 ++
 .../src/runtime/runtime-hooks-client.test.ts  |   96 +
 .../src/runtime/runtime-hooks-client.ts       |   66 +
 .../src/runtime/runtime-linear-client.test.ts |  148 +
 .../src/runtime/runtime-linear-client.ts      |  222 +
 .../src/runtime/runtime-notes-client.test.ts  |  228 ++
 .../src/runtime/runtime-notes-client.ts       |  229 ++
 .../src/runtime/runtime-protocol-compat.ts    |   19 +
 .../src/runtime/runtime-repo-client.ts        |   42 +
 .../src/runtime/runtime-rpc-client.test.ts    |  155 +
 .../src/runtime/runtime-rpc-client.ts         |  108 +
 .../runtime-terminal-inspection.test.ts       |   72 +
 .../runtime/runtime-terminal-inspection.ts    |   62 +
 .../runtime/runtime-terminal-stream.test.ts   |  120 +
 .../src/runtime/runtime-terminal-stream.ts    |  163 +
 src/renderer/src/store/slices/browser.test.ts | 1144 ++----
 src/renderer/src/store/slices/browser.ts      |  280 +-
 .../src/store/slices/diffComments.test.ts     |   56 +
 src/renderer/src/store/slices/diffComments.ts |   27 +-
 src/renderer/src/store/slices/editor.test.ts  |  295 +-
 src/renderer/src/store/slices/editor.ts       |  149 +-
 src/renderer/src/store/slices/github.test.ts  |  130 +-
 src/renderer/src/store/slices/github.ts       |  251 +-
 .../src/store/slices/hosted-review.test.ts    |   51 +-
 .../src/store/slices/hosted-review.ts         |   34 +-
 src/renderer/src/store/slices/linear.ts       |   26 +-
 src/renderer/src/store/slices/repos.test.ts   |  256 ++
 src/renderer/src/store/slices/repos.ts        |  119 +-
 .../src/store/slices/settings.test.ts         |  246 ++
 src/renderer/src/store/slices/settings.ts     |  236 +-
 src/renderer/src/store/slices/terminals.ts    |   15 +-
 src/renderer/src/store/slices/ui.ts           |    1 +
 .../src/store/slices/worktrees.test.ts        |  169 +
 src/renderer/src/store/slices/worktrees.ts    |  116 +-
 src/shared/constants.ts                       |    3 +
 src/shared/cross-platform-path.test.ts        |   26 +
 src/shared/cross-platform-path.ts             |   57 +
 src/shared/e2ee-crypto.ts                     |   65 +
 src/shared/protocol-compat.test.ts            |   85 +-
 src/shared/protocol-compat.ts                 |   69 +-
 src/shared/protocol-version.ts                |   45 +-
 src/shared/remote-runtime-client.test.ts      |  140 +
 src/shared/remote-runtime-client.ts           |  552 +++
 ...e-runtime-request-connection-stale.test.ts |  115 +
 .../remote-runtime-request-connection.test.ts |  142 +
 .../remote-runtime-request-connection.ts      |  292 ++
 src/shared/remote-runtime-request-frames.ts   |   98 +
 .../remote-runtime-request-websocket.ts       |   96 +
 src/shared/runtime-environment-store.test.ts  |   47 +
 src/shared/runtime-environment-store.ts       |  166 +
 src/shared/runtime-environments.ts            |   99 +
 src/shared/runtime-rpc-envelope.ts            |   73 +
 src/shared/runtime-types.ts                   |   58 +-
 src/shared/secure-file.ts                     |  109 +
 src/shared/terminal-stream-protocol.test.ts   |   55 +
 src/shared/terminal-stream-protocol.ts        |   12 +-
 src/shared/types.ts                           |    4 +
 src/shared/workspace-session-schema.ts        |    3 +-
 308 files changed, 32140 insertions(+), 4464 deletions(-)
 create mode 100644 src/cli/handlers/environment.ts
 create mode 100644 src/cli/runtime/environments.test.ts
 create mode 100644 src/cli/runtime/environments.ts
 create mode 100644 src/cli/runtime/launch.test.ts
 create mode 100644 src/cli/runtime/websocket-transport.test.ts
 create mode 100644 src/cli/runtime/websocket-transport.ts
 create mode 100644 src/cli/specs/environment.ts
 create mode 100644 src/main/cli/packaged-cli-assets.test.ts
 create mode 100644 src/main/ipc/mobile.test.ts
 create mode 100644 src/main/ipc/runtime-environment-call-queue.ts
 create mode 100644 src/main/ipc/runtime-environment-request-connections.ts
 create mode 100644 src/main/ipc/runtime-environments.test.ts
 create mode 100644 src/main/ipc/runtime-environments.ts
 create mode 100644 src/main/runtime/orca-runtime-browser.ts
 create mode 100644 src/main/runtime/orca-runtime-files.test.ts
 create mode 100644 src/main/runtime/orca-runtime-files.ts
 create mode 100644 src/main/runtime/orca-runtime-git.ts
 rename src/{cli/orchestration.subprocess.test.ts => main/runtime/orchestration-cli-subprocess.test.ts} (93%)
 create mode 100644 src/main/runtime/remote-runtime-request-connection.integration.test.ts
 create mode 100644 src/main/runtime/rpc/methods/browser.test.ts
 create mode 100644 src/main/runtime/rpc/methods/file-watch-event-batcher.ts
 create mode 100644 src/main/runtime/rpc/methods/git.test.ts
 create mode 100644 src/main/runtime/rpc/methods/git.ts
 create mode 100644 src/main/runtime/rpc/methods/github.test.ts
 create mode 100644 src/main/runtime/rpc/methods/github.ts
 create mode 100644 src/main/runtime/rpc/methods/hosted-review.test.ts
 create mode 100644 src/main/runtime/rpc/methods/hosted-review.ts
 create mode 100644 src/main/runtime/rpc/methods/linear.test.ts
 create mode 100644 src/main/runtime/rpc/methods/linear.ts
 create mode 100644 src/main/runtime/rpc/methods/notes.test.ts
 create mode 100644 src/main/runtime/rpc/methods/repo.test.ts
 create mode 100644 src/main/runtime/rpc/methods/worktree.test.ts
 create mode 100644 src/main/runtime/rpc/terminal-multiplex.test.ts
 create mode 100644 src/main/runtime/rpc/terminal-output-batching.test.ts
 create mode 100644 src/main/runtime/rpc/terminal-send.test.ts
 create mode 100644 src/main/runtime/rpc/terminal-subscribe-buffer.test.ts
 create mode 100644 src/main/runtime/runtime-relative-paths.ts
 create mode 100644 src/main/ssh/sftp-upload.test.ts
 create mode 100644 src/preload/runtime-environment-subscriptions.test.ts
 create mode 100644 src/preload/runtime-environment-subscriptions.ts
 create mode 100644 src/renderer/src/app-startup-routing.test.ts
 create mode 100644 src/renderer/src/components/editor/useLocalImageSrc.test.ts
 create mode 100644 src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
 create mode 100644 src/renderer/src/components/tab-bar/editor-tab-local-open-guard.test.ts
 create mode 100644 src/renderer/src/components/tab-bar/editor-tab-local-open-guard.ts
 create mode 100644 src/renderer/src/components/terminal-pane/remote-runtime-pty-batching.ts
 create mode 100644 src/renderer/src/components/terminal-pane/remote-runtime-pty-binary-control.ts
 create mode 100644 src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.test.ts
 create mode 100644 src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-drop-handler.test.ts
 create mode 100644 src/renderer/src/hooks/useGlobalFileDrop.test.ts
 create mode 100644 src/renderer/src/lib/local-path-open-guard.test.ts
 create mode 100644 src/renderer/src/lib/local-path-open-guard.ts
 create mode 100644 src/renderer/src/runtime/remote-file-client.ts
 create mode 100644 src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
 create mode 100644 src/renderer/src/runtime/runtime-compatibility-test-fixture.ts
 create mode 100644 src/renderer/src/runtime/runtime-file-client.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-file-client.ts
 create mode 100644 src/renderer/src/runtime/runtime-git-client.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-git-client.ts
 create mode 100644 src/renderer/src/runtime/runtime-hooks-client.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-hooks-client.ts
 create mode 100644 src/renderer/src/runtime/runtime-linear-client.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-linear-client.ts
 create mode 100644 src/renderer/src/runtime/runtime-notes-client.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-notes-client.ts
 create mode 100644 src/renderer/src/runtime/runtime-protocol-compat.ts
 create mode 100644 src/renderer/src/runtime/runtime-repo-client.ts
 create mode 100644 src/renderer/src/runtime/runtime-rpc-client.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-rpc-client.ts
 create mode 100644 src/renderer/src/runtime/runtime-terminal-inspection.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-terminal-inspection.ts
 create mode 100644 src/renderer/src/runtime/runtime-terminal-stream.test.ts
 create mode 100644 src/renderer/src/runtime/runtime-terminal-stream.ts
 create mode 100644 src/renderer/src/store/slices/repos.test.ts
 create mode 100644 src/renderer/src/store/slices/settings.test.ts
 create mode 100644 src/shared/cross-platform-path.test.ts
 create mode 100644 src/shared/cross-platform-path.ts
 create mode 100644 src/shared/e2ee-crypto.ts
 create mode 100644 src/shared/remote-runtime-client.test.ts
 create mode 100644 src/shared/remote-runtime-client.ts
 create mode 100644 src/shared/remote-runtime-request-connection-stale.test.ts
 create mode 100644 src/shared/remote-runtime-request-connection.test.ts
 create mode 100644 src/shared/remote-runtime-request-connection.ts
 create mode 100644 src/shared/remote-runtime-request-frames.ts
 create mode 100644 src/shared/remote-runtime-request-websocket.ts
 create mode 100644 src/shared/runtime-environment-store.test.ts
 create mode 100644 src/shared/runtime-environment-store.ts
 create mode 100644 src/shared/runtime-environments.ts
 create mode 100644 src/shared/runtime-rpc-envelope.ts
 create mode 100644 src/shared/secure-file.ts

diff --git a/.gitignore b/.gitignore
index 2afd28d2a43..92b3d28c436 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,6 +67,9 @@ design-docs/
 .context/
 .atl/
 
+# Machine-local agent hook endpoint files may contain auth tokens.
+/agent-hooks/
+
 # Local-only design/planning docs (not checked in)
 docs/*.md
 !docs/README*.md
diff --git a/config/electron-builder.config.cjs b/config/electron-builder.config.cjs
index 30fc98ae895..e1a63218fe7 100644
--- a/config/electron-builder.config.cjs
+++ b/config/electron-builder.config.cjs
@@ -39,6 +39,8 @@ module.exports = {
   // integration — dependencies inside the asar archive are invisible to
   // require(). Unpack CLI runtime deps so they resolve from
   // app.asar.unpacked/node_modules/.
+  // Why: remote runtime connections use WebSocket + E2EE from the packaged CLI
+  // before the GUI process starts, so those deps need the same treatment.
   // Why: sherpa-onnx native bindings (platform-specific subpackages) must be
   // unpacked because they ship .node addons + .dylib/.so files that cannot be
   // dlopen()'d from inside the asar archive.
@@ -49,6 +51,8 @@ module.exports = {
     'out/main/computer-sidecar.js',
     'out/main/chunks/**',
     'resources/**',
+    'node_modules/ws/**',
+    'node_modules/tweetnacl/**',
     'node_modules/zod/**',
     'node_modules/sherpa-onnx*/**'
   ],
diff --git a/mobile/packages/expo-two-way-audio/ios/AudioEngine.swift b/mobile/packages/expo-two-way-audio/ios/AudioEngine.swift
index f079c89b7d3..ac259e3794c 100644
--- a/mobile/packages/expo-two-way-audio/ios/AudioEngine.swift
+++ b/mobile/packages/expo-two-way-audio/ios/AudioEngine.swift
@@ -7,41 +7,41 @@ class AudioEngine {
     private var engineConfigChangeObserver: Any?
     private var sessionInterruptionObserver: Any?
     private var mediaServicesResetObserver: Any?
-    
+
     public private(set) var voiceIOFormat: AVAudioFormat
     public private(set) var isRecording = false
     private var wasRecordingBeforeInterruption = false
-    
+
     public var onMicDataCallback: ((Data) -> Void)?
     public var onInputVolumeCallback: ((Float) -> Void)?
     public var onOutputVolumeCallback: ((Float) -> Void)?
     public var onAudioInterruptionCallback: ((String) -> Void)?
-    
+
     private var inputLevelTimer: Timer?
     private var outputLevelTimer: Timer?
-    
+
     private var inputBuffer = [Float](repeating: 0, count: 2048)
     private var outputBuffer = [Float](repeating: 0, count: 2048)
     private var inputBufferIndex = 0
     private var outputBufferIndex = 0
-    
+
     private var hasFirstInputBeenDiscarded = false
     private var discardRecording = false
     private var discardFirstInputMillis = 2000
-    
+
     enum AudioEngineError: Error {
         case audioFormatError
     }
-    
+
     init() throws {
         avAudioEngine.attach(speechPlayer)
-        
+
         guard let format = AVAudioFormat(standardFormatWithSampleRate: 16000, channels: 1) else {
             throw AudioEngineError.audioFormatError
         }
         voiceIOFormat = format
         print("Voice IO format: \(String(describing: voiceIOFormat))")
-        
+
         engineConfigChangeObserver = NotificationCenter.default.addObserver(
             forName: .AVAudioEngineConfigurationChange,
             object: avAudioEngine,
@@ -60,12 +60,12 @@ class AudioEngine {
             queue: .main) { [weak self] _ in
                 self?.handleMediaServicesWereReset()
             }
-        
+
         self.setupAudioSession()
         self.setup()
         self.start()
     }
-    
+
     deinit {
         if let observer = engineConfigChangeObserver {
             NotificationCenter.default.removeObserver(observer)
@@ -77,29 +77,29 @@ class AudioEngine {
             NotificationCenter.default.removeObserver(observer)
         }
     }
-    
+
     func setupAudioSession() {
         let session = AVAudioSession.sharedInstance()
-        
+
         do {
             try session.setCategory(.playAndRecord, mode: .voiceChat, options: [.defaultToSpeaker, .allowBluetooth, .allowBluetoothA2DP])
         } catch {
             print("Could not set the audio category: \(error.localizedDescription)")
         }
-        
+
         do {
             try session.setPreferredSampleRate(voiceIOFormat.sampleRate)
         } catch {
             print("Could not set the preferred sample rate: \(error.localizedDescription)")
         }
-        
+
         do {
             try session.setActive(true)
         } catch {
             print("Could not set the audio session as active")
         }
     }
-    
+
     func setup() {
         let input = avAudioEngine.inputNode
         do {
@@ -108,15 +108,15 @@ class AudioEngine {
             print("Could not enable voice processing \(error)")
             return
         }
-        
+
         avAudioEngine.inputNode.isVoiceProcessingInputMuted = !isRecording
-        
+
         let output = avAudioEngine.outputNode
         let mainMixer = avAudioEngine.mainMixerNode
-        
+
         avAudioEngine.connect(speechPlayer, to: mainMixer, format: voiceIOFormat)
         avAudioEngine.connect(mainMixer, to: output, format: voiceIOFormat)
-        
+
         input.installTap(onBus: 0, bufferSize: 2048, format: voiceIOFormat) { [weak self] buffer, when in
             // We don't do any input processing (no volume calculation or passing mic data to the callback) if discardRecording == true
             // See comment in the playPCMData function
@@ -125,48 +125,48 @@ class AudioEngine {
                 self?.updateInputVolume()
             }
         }
-        
+
         mainMixer.installTap(onBus: 0, bufferSize: 2048, format: voiceIOFormat) { [weak self] buffer, when in
             self?.processOutputBuffer(buffer)
             self?.updateOutputVolume()
         }
-        
+
         avAudioEngine.prepare()
     }
-    
+
     func processMicrophoneBuffer(_ buffer: AVAudioPCMBuffer) {
         guard let channelData = buffer.floatChannelData?[0] else {
             print("Error: Could not access channel data")
             return
         }
-        
+
         let frameCount = Int(buffer.frameLength)
         var int16Samples = [Int16](repeating: 0, count: frameCount)
-        
+
         // Convert float samples to Int16 and update input buffer for volume calculation
         for i in 0..<frameCount {
             let floatSample = max(-1.0, min(1.0, channelData[i]))
             int16Samples[i] = Int16(floatSample * Float(Int16.max))
-            
+
             inputBuffer[inputBufferIndex] = floatSample
             inputBufferIndex = (inputBufferIndex + 1) % inputBuffer.count
         }
-        
+
         // Create Data object from Int16 samples
         let data = Data(bytes: int16Samples, count: frameCount * MemoryLayout<Int16>.size)
-        
+
         // Send the data to the callback
         onMicDataCallback?(data)
     }
-    
+
     func processOutputBuffer(_ buffer: AVAudioPCMBuffer) {
         guard let channelData = buffer.floatChannelData?[0] else {
             print("Error: Could not access channel data")
             return
         }
-        
+
         let frameCount = Int(buffer.frameLength)
-        
+
         // Update output buffer for volume calculation
         for i in 0..<frameCount {
             let floatSample = max(-1.0, min(1.0, channelData[i]))
@@ -174,7 +174,7 @@ class AudioEngine {
             outputBufferIndex = (outputBufferIndex + 1) % outputBuffer.count
         }
     }
-    
+
     func start() {
         do {
             try avAudioEngine.start()
@@ -182,7 +182,7 @@ class AudioEngine {
             print("Could not start audio engine: \(error)")
         }
     }
-    
+
     func playPCMData(_ pcmData: Data) {
         // Looks like we don't get a proper AEC for the very first chunks of audio that we play.
         // To work around this, we will discard microphone input for the first few milliseconds.
@@ -196,33 +196,33 @@ class AudioEngine {
                 self.discardRecording = false
             }
         }
-        
+
         guard let buffer = createBuffer(from: pcmData) else {
             print("Failed to create audio buffer")
             return
         }
         speechPlayer.scheduleBuffer(buffer)
-        
+
         if !speechPlayer.isPlaying {
             speechPlayer.play()
         }
     }
 
-    
+
     private func createBuffer(from data: Data) -> AVAudioPCMBuffer? {
         let frameCount = UInt32(data.count) / 2 // 16-bit input = 2 bytes per frame
-        
+
         let format = AVAudioFormat(commonFormat: .pcmFormatFloat32,
                                    sampleRate: 16000,
                                    channels: 1,
                                    interleaved: false)!
-        
+
         guard let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: frameCount) else {
             return nil
         }
-        
+
         buffer.frameLength = frameCount
-        
+
         data.withUnsafeBytes { (rawBufferPointer: UnsafeRawBufferPointer) in
             if let sourcePtr = rawBufferPointer.baseAddress?.assumingMemoryBound(to: Int16.self),
                let destPtr = buffer.floatChannelData?[0] {
@@ -231,15 +231,15 @@ class AudioEngine {
                 }
             }
         }
-        
+
         return buffer
     }
-    
+
     func bypassVoiceProcessing(_ bypass: Bool) {
         let input = avAudioEngine.inputNode
         input.isVoiceProcessingBypassed = bypass
     }
-    
+
     func toggleRecording(_ val: Bool) -> Bool {
         isRecording = val
         if !isRecording {
@@ -251,10 +251,10 @@ class AudioEngine {
             avAudioEngine.inputNode.isVoiceProcessingInputMuted = false
         }
         print("Recording \(isRecording ? "started" : "stopped")")
-        
+
         return isRecording
     }
-    
+
     func stopRecordingAndPlayer(clearInterruptionResume: Bool = true){
         if clearInterruptionResume {
             wasRecordingBeforeInterruption = false
@@ -268,7 +268,7 @@ class AudioEngine {
         speechPlayer.stop()
         updateOutputVolume()
     }
-    
+
     func resumeRecordingAndPlayer(){
         do {
             try AVAudioSession.sharedInstance().setActive(true)
@@ -279,12 +279,12 @@ class AudioEngine {
         isRecording = toggleRecording(true)
         speechPlayer.play()
     }
-    
+
     func tearDown() {
         stopRecordingAndPlayer()
         avAudioEngine.stop()
     }
-    
+
     var isPlaying: Bool {
         return speechPlayer.isPlaying
     }
@@ -308,13 +308,13 @@ class AudioEngine {
             print("Playback resumed")
         }
     }
-    
+
     private func checkEngineIsRunning() {
         if !avAudioEngine.isRunning {
             start()
         }
     }
-    
+
     private func handleAudioSessionInterruption(_ notification: Notification) {
         guard let userInfo = notification.userInfo,
               let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt,
@@ -343,39 +343,39 @@ class AudioEngine {
             fatalError("Unknown type: \(type)")
         }
     }
-    
+
     private func handleMediaServicesWereReset() {
         self.avAudioEngine.stop()
         self.setup()
         self.start()
     }
-    
+
     private func updateInputVolume() {
         let volume = calculateRMSLevel(from: inputBuffer)
         onInputVolumeCallback?(volume)
     }
-    
+
     private func updateOutputVolume() {
         let volume = calculateRMSLevel(from: outputBuffer)
         onOutputVolumeCallback?(volume)
     }
-    
+
     private func calculateRMSLevel(from buffer: [Float]) -> Float {
         let epsilon: Float = 1e-5 // To avoid log(0)
         let rmsValue = sqrt(buffer.reduce(0) { $0 + $1 * $1 } / Float(buffer.count))
-        
+
         // Convert to decibels
         let dbValue = 20 * log10(max(rmsValue, epsilon))
-        
+
         // Normalize decibel value to 0-1 range
         // Assuming minimum audible is -60dB and maximum is 0dB
         let minDb: Float = -80.0
         let normalizedValue = max(0.0, min(1.0, (dbValue - minDb) / abs(minDb)))
-        
+
         // Optional: Apply exponential factor to push smaller values down
         let expFactor: Float = 2.0 // Adjust this value to change the curve
         let adjustedValue = pow(normalizedValue, expFactor)
-        
+
         return adjustedValue
     }
 }
diff --git a/mobile/scripts/test-subscribe.ts b/mobile/scripts/test-subscribe.ts
index 6fa8ffe4b42..a33ddd0c22b 100644
--- a/mobile/scripts/test-subscribe.ts
+++ b/mobile/scripts/test-subscribe.ts
@@ -267,7 +267,14 @@ ws.on('open', () => {
 })
 
 ws.on('message', (data) => {
-  const plaintext = decrypt(data.toString())
+  let plaintext: string | null = null
+  try {
+    plaintext = decrypt(data.toString())
+  } catch {
+    // Plaintext handshake/control frames such as e2ee_ready are handled by the
+    // connect flow above. The global listener only cares about encrypted RPC.
+    return
+  }
   if (!plaintext) return
   const response = JSON.parse(plaintext) as RpcResponse
   if (response._meta?.runtimeId) {
diff --git a/mobile/src/transport/protocol-version.ts b/mobile/src/transport/protocol-version.ts
index 3ba4ede3878..4c1cf137738 100644
--- a/mobile/src/transport/protocol-version.ts
+++ b/mobile/src/transport/protocol-version.ts
@@ -1,20 +1,20 @@
-// Why: declares the mobile's pairing protocol version and the minimum
-// desktop version it can talk to. Duplicates the desktop's
+// Why: declares the mobile client's runtime protocol version and the minimum
+// server protocol it can talk to. Duplicates the desktop's
 // `src/shared/protocol-version.ts` because Metro/Expo doesn't resolve
 // outside `mobile/`. Manual sync is acceptable — these constants are
 // expected to bump less than once a quarter.
 //
 // Bump MOBILE_PROTOCOL_VERSION when:
 //   - You change the meaning of an RPC mobile sends.
-//   - You stop relying on a desktop-side feature in a way old desktops
+//   - You stop relying on a server-side feature in a way old servers
 //     would notice.
 // Do NOT bump for:
 //   - Adding new optional fields to outbound requests.
 //   - Reading new optional fields on incoming responses.
 //
 // Bump MIN_COMPATIBLE_DESKTOP_VERSION when mobile starts relying on a
-// desktop feature added at a specific desktop protocol version. This
-// triggers a hard-block screen for users paired to older desktops.
+// server feature added at a specific runtime protocol version. This
+// triggers a hard-block screen for users paired to older servers.
 
 export const MOBILE_PROTOCOL_VERSION = 2
 export const MIN_COMPATIBLE_DESKTOP_VERSION = 2
diff --git a/package.json b/package.json
index 39e335bc753..5da12543545 100644
--- a/package.json
+++ b/package.json
@@ -88,8 +88,8 @@
     "cmdk": "^1.1.1",
     "dompurify": "^3.4.2",
     "electron-updater": "^6.8.3",
-    "entities": "^6.0.1",
     "emoji-picker-react": "^4.19.1",
+    "entities": "^6.0.1",
     "github-slugger": "^2.0.0",
     "hosted-git-info": "^9.0.3",
     "html-to-image": "^1.11.13",
diff --git a/src/cli/args.ts b/src/cli/args.ts
index ece4215d8f5..9af56d69065 100644
--- a/src/cli/args.ts
+++ b/src/cli/args.ts
@@ -14,7 +14,7 @@ export type CommandSpec = {
   notes?: string[]
 }
 
-export const GLOBAL_FLAGS = ['help', 'json']
+export const GLOBAL_FLAGS = ['help', 'json', 'pairing-code', 'environment']
 
 export function parseArgs(argv: string[]): ParsedArgs {
   const commandPath: string[] = []
@@ -93,6 +93,7 @@ export function isCommandGroup(commandPath: string[]): boolean {
         'storage',
         'orchestration',
         'computer',
+        'environment',
         'note'
       ].includes(commandPath[0])) ||
     (commandPath.length === 2 &&
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index 1937a4593ad..00896007067 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -14,6 +14,7 @@ import { BROWSER_ENV_HANDLERS } from './handlers/browser-env'
 import { BROWSER_STORAGE_HANDLERS } from './handlers/browser-storage'
 import { ORCHESTRATION_HANDLERS } from './handlers/orchestration'
 import { COMPUTER_HANDLERS } from './handlers/computer'
+import { ENVIRONMENT_HANDLERS } from './handlers/environment'
 import { NOTE_HANDLERS } from './handlers/note'
 
 export type HandlerContext = {
@@ -42,6 +43,7 @@ function buildHandlers(): Map<string, CommandHandler> {
     BROWSER_STORAGE_HANDLERS,
     ORCHESTRATION_HANDLERS,
     COMPUTER_HANDLERS,
+    ENVIRONMENT_HANDLERS,
     NOTE_HANDLERS
   ]
   for (const group of groups) {
diff --git a/src/cli/format.ts b/src/cli/format.ts
index b8cce4771af..0b99b8bcae4 100644
--- a/src/cli/format.ts
+++ b/src/cli/format.ts
@@ -33,6 +33,7 @@ import type {
   RuntimeWorktreePsResult,
   RuntimeWorktreeRecord
 } from '../shared/runtime-types'
+import type { PublicKnownRuntimeEnvironment } from '../shared/runtime-environments'
 import type { NoteListResult, NoteMutationResult, NoteShowResult } from '../shared/notes-types'
 import type { RuntimeRpcFailure, RuntimeRpcSuccess } from './runtime-client'
 import { RuntimeClientError, RuntimeRpcFailureError } from './runtime-client'
@@ -101,6 +102,33 @@ export function formatStatus(status: CliStatusResult): string {
   return formatCliStatus(status)
 }
 
+export function formatEnvironmentList(result: {
+  environments: PublicKnownRuntimeEnvironment[]
+}): string {
+  if (result.environments.length === 0) {
+    return 'No saved environments.'
+  }
+  return result.environments
+    .map(
+      (environment) =>
+        `${environment.id}  ${environment.name}  ${environment.endpoints[0]?.endpoint ?? 'no-endpoint'}`
+    )
+    .join('\n')
+}
+
+export function formatEnvironment(environment: PublicKnownRuntimeEnvironment): string {
+  return [
+    `id: ${environment.id}`,
+    `name: ${environment.name}`,
+    `runtimeId: ${environment.runtimeId ?? 'unknown'}`,
+    `lastUsedAt: ${environment.lastUsedAt ?? 'never'}`,
+    `preferredEndpointId: ${environment.preferredEndpointId}`,
+    ...environment.endpoints.map(
+      (endpoint) => `endpoint: ${endpoint.id} ${endpoint.kind} ${endpoint.endpoint}`
+    )
+  ].join('\n')
+}
+
 export function formatTerminalList(result: RuntimeTerminalListResult): string {
   if (result.terminals.length === 0) {
     return 'No live terminals.'
diff --git a/src/cli/handlers/core.ts b/src/cli/handlers/core.ts
index f96a941daf9..895aa7abca8 100644
--- a/src/cli/handlers/core.ts
+++ b/src/cli/handlers/core.ts
@@ -1,11 +1,38 @@
 import type { CommandHandler } from '../dispatch'
 import { formatCliStatus, formatStatus, printResult } from '../format'
+import { RuntimeClientError, serveOrcaApp } from '../runtime-client'
 
 export const CORE_HANDLERS: Record<string, CommandHandler> = {
   open: async ({ client, json }) => {
     const result = await client.openOrca()
     printResult(result, json, formatCliStatus)
   },
+  serve: async ({ flags, json }) => {
+    if (flags.get('no-pairing') === true && flags.get('mobile-pairing') === true) {
+      throw new RuntimeClientError(
+        'invalid_argument',
+        'Use either --mobile-pairing or --no-pairing, not both.'
+      )
+    }
+    const rawPort = flags.get('port')
+    if (typeof rawPort === 'string') {
+      const port = Number(rawPort)
+      if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new RuntimeClientError('invalid_argument', `Invalid --port value: ${rawPort}`)
+      }
+    }
+    const exitCode = await serveOrcaApp({
+      json,
+      port: typeof rawPort === 'string' ? rawPort : null,
+      pairingAddress:
+        typeof flags.get('pairing-address') === 'string'
+          ? (flags.get('pairing-address') as string)
+          : null,
+      noPairing: flags.get('no-pairing') === true,
+      mobilePairing: flags.get('mobile-pairing') === true
+    })
+    process.exitCode = exitCode
+  },
   status: async ({ client, json }) => {
     const result = await client.getCliStatus()
     if (!json && !result.result.runtime.reachable) {
diff --git a/src/cli/handlers/environment.ts b/src/cli/handlers/environment.ts
new file mode 100644
index 00000000000..08530ea29c3
--- /dev/null
+++ b/src/cli/handlers/environment.ts
@@ -0,0 +1,75 @@
+import type { CommandHandler } from '../dispatch'
+import { formatEnvironment, formatEnvironmentList, printResult } from '../format'
+import { getDefaultUserDataPath } from '../runtime-client'
+import type { RuntimeRpcSuccess } from '../runtime-client'
+import { RuntimeClientError } from '../runtime-client'
+import { redactRuntimeEnvironment } from '../../shared/runtime-environments'
+import {
+  addEnvironmentFromPairingCode,
+  listEnvironments,
+  removeEnvironment,
+  resolveEnvironment,
+  type EnvironmentAddResult,
+  type EnvironmentRemoveResult
+} from '../runtime/environments'
+
+export const ENVIRONMENT_HANDLERS: Record<string, CommandHandler> = {
+  'environment add': async ({ flags, json }) => {
+    const name = getRequiredStringFlag(flags, 'name')
+    const pairingCode = getRequiredStringFlag(flags, 'pairing-code')
+    const environment = redactRuntimeEnvironment(
+      addEnvironmentFromPairingCode(getDefaultUserDataPath(), {
+        name,
+        pairingCode
+      })
+    )
+    printResult(
+      localSuccess({ environment }),
+      json,
+      (result: EnvironmentAddResult) =>
+        `Saved environment ${result.environment.name} (${result.environment.id}).`
+    )
+  },
+  'environment list': async ({ json }) => {
+    const environments = listEnvironments(getDefaultUserDataPath()).map(redactRuntimeEnvironment)
+    printResult(localSuccess({ environments }), json, formatEnvironmentList)
+  },
+  'environment show': async ({ flags, json }) => {
+    const selector = getRequiredStringFlag(flags, 'environment')
+    const environment = redactRuntimeEnvironment(
+      resolveEnvironment(getDefaultUserDataPath(), selector)
+    )
+    printResult(localSuccess({ environment }), json, ({ environment: value }) =>
+      formatEnvironment(value)
+    )
+  },
+  'environment rm': async ({ flags, json }) => {
+    const selector = getRequiredStringFlag(flags, 'environment')
+    const removed = redactRuntimeEnvironment(removeEnvironment(getDefaultUserDataPath(), selector))
+    printResult(
+      localSuccess({ removed }),
+      json,
+      (result: EnvironmentRemoveResult) =>
+        `Removed environment ${result.removed.name} (${result.removed.id}).`
+    )
+  }
+}
+
+function getRequiredStringFlag(flags: Map<string, string | boolean>, name: string): string {
+  const value = flags.get(name)
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new RuntimeClientError('invalid_argument', `Missing required --${name}`)
+  }
+  return value
+}
+
+function localSuccess<TResult>(result: TResult): RuntimeRpcSuccess<TResult> {
+  return {
+    id: 'local',
+    ok: true,
+    result,
+    _meta: {
+      runtimeId: 'local'
+    }
+  }
+}
diff --git a/src/cli/handlers/repo.ts b/src/cli/handlers/repo.ts
index a1061ee271b..fc4c9f22809 100644
--- a/src/cli/handlers/repo.ts
+++ b/src/cli/handlers/repo.ts
@@ -1,16 +1,43 @@
+import { resolve as resolvePath } from 'path'
 import type { RuntimeRepoList, RuntimeRepoSearchRefs } from '../../shared/runtime-types'
 import type { CommandHandler } from '../dispatch'
 import { formatRepoList, formatRepoRefs, formatRepoShow, printResult } from '../format'
 import { getOptionalPositiveIntegerFlag, getRequiredStringFlag } from '../flags'
+import { RuntimeClientError } from '../runtime-client'
+
+function isAbsoluteServerPath(value: string): boolean {
+  return (
+    value.startsWith('/') ||
+    /^[A-Za-z]:[\\/]/.test(value) ||
+    value.startsWith('\\\\') ||
+    value.startsWith('//')
+  )
+}
+
+function resolveRepoAddPath(inputPath: string, cwd: string, isRemote: boolean): string {
+  if (!isRemote) {
+    return resolvePath(cwd, inputPath)
+  }
+  // Why: the local CLI cwd is unrelated to a paired runtime's filesystem.
+  // Relative remote paths would silently target the wrong machine.
+  if (!isAbsoluteServerPath(inputPath)) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Remote repo add requires --path to be an absolute path on the remote server.'
+    )
+  }
+  return inputPath
+}
 
 export const REPO_HANDLERS: Record<string, CommandHandler> = {
   'repo list': async ({ client, json }) => {
     const result = await client.call<RuntimeRepoList>('repo.list')
     printResult(result, json, formatRepoList)
   },
-  'repo add': async ({ flags, client, json }) => {
+  'repo add': async ({ flags, client, cwd, json }) => {
+    const repoPath = getRequiredStringFlag(flags, 'path')
     const result = await client.call<{ repo: Record<string, unknown> }>('repo.add', {
-      path: getRequiredStringFlag(flags, 'path')
+      path: resolveRepoAddPath(repoPath, cwd, client.isRemote)
     })
     printResult(result, json, formatRepoShow)
   },
diff --git a/src/cli/handlers/terminal.ts b/src/cli/handlers/terminal.ts
index e59ad46e712..831796a488f 100644
--- a/src/cli/handlers/terminal.ts
+++ b/src/cli/handlers/terminal.ts
@@ -116,6 +116,12 @@ export const TERMINAL_HANDLERS: Record<string, CommandHandler> = {
     printResult(result, json, formatTerminalRename)
   },
   'terminal create': async ({ flags, client, cwd, json }) => {
+    if (client.isRemote && !flags.has('worktree')) {
+      throw new RuntimeClientError(
+        'invalid_argument',
+        'Remote terminal create requires --worktree because the client cwd cannot identify a server worktree.'
+      )
+    }
     const result = await client.call<{ terminal: RuntimeTerminalCreate }>('terminal.create', {
       worktree: await getBrowserWorktreeSelector(flags, cwd, client),
       command: getOptionalStringFlag(flags, 'command'),
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 411ddd98715..b129306953f 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -8,8 +8,15 @@ Usage: orca <command> [options]
 
 Startup:
   open                      Launch Orca and wait for the runtime to be reachable
+  serve                     Start a headless Orca runtime server
   status                    Show app/runtime/graph readiness
 
+Environments:
+  environment add           Save a remote Orca runtime from a pairing code
+  environment list          List saved remote Orca runtimes
+  environment show          Show one saved remote Orca runtime
+  environment rm            Remove a saved remote Orca runtime
+
 Repos:
   repo list                 List repos registered in Orca
   repo add                  Add a project to Orca by filesystem path
@@ -138,7 +145,12 @@ Browser Automation:
 
 Common Commands:
   orca open [--json]
+  orca serve [--port <port>] [--pairing-address <host>] [--mobile-pairing] [--no-pairing] [--json]
   orca status [--json]
+  orca environment add --name <name> --pairing-code <code> [--json]
+  orca environment list [--json]
+  orca environment show --environment <selector> [--json]
+  orca environment rm --environment <selector> [--json]
   orca worktree list [--repo <selector>] [--limit <n>] [--json]
   orca worktree create --repo <selector> --name <name> [--base-branch <ref>] [--issue <number>] [--comment <text>] [--run-hooks] [--activate] [--json]
   orca worktree show --worktree <selector> [--json]
@@ -178,10 +190,13 @@ Wait Options:
 
 Output Options:
   --json                    Emit machine-readable JSON instead of human text
+  --pairing-code <code>      Connect to a remote Orca runtime using an orca://pair#... code
+  --environment <selector>   Connect using a saved environment id or name
   --help                    Show this help message
 
 Behavior:
   Most commands require a running Orca runtime. If Orca is not open yet, run \`orca open\` first.
+  Remote runtime access can also be supplied with ORCA_PAIRING_CODE or ORCA_ENVIRONMENT.
   Use selectors for discovery and handles for repeated live terminal operations.
 
 Browser Workflow:
diff --git a/src/cli/index.test.ts b/src/cli/index.test.ts
index 668354a2607..6758745bd0d 100644
--- a/src/cli/index.test.ts
+++ b/src/cli/index.test.ts
@@ -2,13 +2,47 @@
 import path from 'path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-const callMock = vi.fn()
+const {
+  callMock,
+  serveOrcaAppMock,
+  getDefaultUserDataPathMock,
+  addEnvironmentFromPairingCodeMock,
+  listEnvironmentsMock
+} = vi.hoisted(() => ({
+  callMock: vi.fn(),
+  serveOrcaAppMock: vi.fn(),
+  getDefaultUserDataPathMock: vi.fn(() => '/tmp/orca-user-data'),
+  addEnvironmentFromPairingCodeMock: vi.fn(),
+  listEnvironmentsMock: vi.fn()
+}))
 
 vi.mock('./runtime-client', () => {
   class RuntimeClient {
+    readonly isRemote: boolean
     call = callMock
     getCliStatus = vi.fn()
     openOrca = vi.fn()
+
+    constructor(
+      _userDataPath?: string,
+      _requestTimeoutMs?: number,
+      remotePairingCode?: string | null,
+      environmentSelector?: string | null
+    ) {
+      const effectivePairingCode =
+        remotePairingCode === undefined
+          ? (process.env.ORCA_PAIRING_CODE ?? process.env.ORCA_REMOTE_PAIRING)
+          : remotePairingCode
+      const effectiveEnvironment =
+        environmentSelector === undefined ? process.env.ORCA_ENVIRONMENT : environmentSelector
+      if (effectivePairingCode && effectiveEnvironment) {
+        throw new RuntimeClientError(
+          'invalid_argument',
+          'Use either --pairing-code or --environment, not both.'
+        )
+      }
+      this.isRemote = Boolean(effectivePairingCode || effectiveEnvironment)
+    }
   }
 
   class RuntimeClientError extends Error {
@@ -32,10 +66,19 @@ vi.mock('./runtime-client', () => {
   return {
     RuntimeClient,
     RuntimeClientError,
-    RuntimeRpcFailureError
+    RuntimeRpcFailureError,
+    serveOrcaApp: serveOrcaAppMock,
+    getDefaultUserDataPath: getDefaultUserDataPathMock
   }
 })
 
+vi.mock('./runtime/environments', () => ({
+  addEnvironmentFromPairingCode: addEnvironmentFromPairingCodeMock,
+  listEnvironments: listEnvironmentsMock,
+  removeEnvironment: vi.fn(),
+  resolveEnvironment: vi.fn()
+}))
+
 import {
   buildCurrentWorktreeSelector,
   COMMAND_SPECS,
@@ -58,9 +101,36 @@ describe('COMMAND_SPECS collision check', () => {
 describe('orca cli worktree awareness', () => {
   const originalTerminalHandle = process.env.ORCA_TERMINAL_HANDLE
   const originalUserDataPath = process.env.ORCA_USER_DATA_PATH
+  const originalPairingCode = process.env.ORCA_PAIRING_CODE
+  const originalRemotePairing = process.env.ORCA_REMOTE_PAIRING
+  const originalEnvironment = process.env.ORCA_ENVIRONMENT
 
   beforeEach(() => {
     callMock.mockReset()
+    serveOrcaAppMock.mockReset()
+    getDefaultUserDataPathMock.mockClear()
+    addEnvironmentFromPairingCodeMock.mockReset()
+    listEnvironmentsMock.mockReset()
+    addEnvironmentFromPairingCodeMock.mockReturnValue({
+      id: 'env-1',
+      name: 'desk',
+      createdAt: 100,
+      updatedAt: 100,
+      lastUsedAt: null,
+      runtimeId: null,
+      endpoints: [
+        {
+          id: 'ws-env-1',
+          kind: 'websocket',
+          label: 'WebSocket',
+          endpoint: 'ws://127.0.0.1:6768',
+          deviceToken: 'token',
+          publicKeyB64: 'pk'
+        }
+      ],
+      preferredEndpointId: 'ws-env-1'
+    })
+    listEnvironmentsMock.mockReturnValue([])
   })
 
   afterEach(() => {
@@ -75,6 +145,21 @@ describe('orca cli worktree awareness', () => {
     } else {
       process.env.ORCA_USER_DATA_PATH = originalUserDataPath
     }
+    if (originalPairingCode === undefined) {
+      delete process.env.ORCA_PAIRING_CODE
+    } else {
+      process.env.ORCA_PAIRING_CODE = originalPairingCode
+    }
+    if (originalRemotePairing === undefined) {
+      delete process.env.ORCA_REMOTE_PAIRING
+    } else {
+      process.env.ORCA_REMOTE_PAIRING = originalRemotePairing
+    }
+    if (originalEnvironment === undefined) {
+      delete process.env.ORCA_ENVIRONMENT
+    } else {
+      process.env.ORCA_ENVIRONMENT = originalEnvironment
+    }
   })
 
   it('builds the current worktree selector from cwd', () => {
@@ -115,6 +200,25 @@ describe('orca cli worktree awareness', () => {
     expect(logSpy).toHaveBeenCalledTimes(1)
   })
 
+  it('rejects remote `worktree current` without listing worktrees from client cwd', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const priorExitCode = process.exitCode
+
+    await main(
+      ['worktree', 'current', '--pairing-code', 'remote-runtime', '--json'],
+      '/tmp/repo/src'
+    )
+
+    expect(callMock).not.toHaveBeenCalled()
+    expect([...logSpy.mock.calls, ...errSpy.mock.calls].flat().join('\n')).toContain(
+      'current is a local cwd shortcut and cannot be resolved against a remote runtime.'
+    )
+    expect(process.exitCode).toBe(1)
+
+    process.exitCode = priorExitCode
+  })
+
   it('uses cwd when active is passed to worktree.set', async () => {
     queueFixtures(
       callMock,
@@ -171,6 +275,192 @@ describe('orca cli worktree awareness', () => {
     })
   })
 
+  it('starts a foreground headless server through `serve`', async () => {
+    serveOrcaAppMock.mockResolvedValue(0)
+    process.env.ORCA_ENVIRONMENT = 'stale-env'
+
+    await main(
+      ['serve', '--json', '--port', '6768', '--pairing-address', '100.64.1.20', '--no-pairing'],
+      '/tmp/repo'
+    )
+
+    expect(serveOrcaAppMock).toHaveBeenCalledWith({
+      json: true,
+      port: '6768',
+      pairingAddress: '100.64.1.20',
+      noPairing: true,
+      mobilePairing: false
+    })
+  })
+
+  it('starts a foreground headless server with mobile pairing enabled', async () => {
+    serveOrcaAppMock.mockResolvedValue(0)
+
+    await main(
+      ['serve', '--pairing-address', '100.64.1.20', '--mobile-pairing', '--json'],
+      '/tmp/repo'
+    )
+
+    expect(serveOrcaAppMock).toHaveBeenCalledWith({
+      json: true,
+      port: null,
+      pairingAddress: '100.64.1.20',
+      noPairing: false,
+      mobilePairing: true
+    })
+  })
+
+  it('rejects contradictory serve pairing flags', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const priorExitCode = process.exitCode
+
+    await main(['serve', '--mobile-pairing', '--no-pairing', '--json'], '/tmp/repo')
+
+    expect(serveOrcaAppMock).not.toHaveBeenCalled()
+    expect([...logSpy.mock.calls, ...errSpy.mock.calls].flat().join('\n')).toContain(
+      'Use either --mobile-pairing or --no-pairing, not both.'
+    )
+    expect(process.exitCode).toBe(1)
+
+    process.exitCode = priorExitCode
+  })
+
+  it('rejects invalid serve ports before launching the app', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const priorExitCode = process.exitCode
+
+    await main(['serve', '--port', 'not-a-port', '--json'], '/tmp/repo')
+
+    expect(serveOrcaAppMock).not.toHaveBeenCalled()
+    expect([...logSpy.mock.calls, ...errSpy.mock.calls].flat().join('\n')).toContain(
+      'Invalid --port value: not-a-port'
+    )
+    expect(process.exitCode).toBe(1)
+
+    process.exitCode = priorExitCode
+  })
+
+  it('lists saved environments even when ORCA_ENVIRONMENT is set', async () => {
+    process.env.ORCA_ENVIRONMENT = 'stale-env'
+    listEnvironmentsMock.mockReturnValue([addEnvironmentFromPairingCodeMock()])
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['environment', 'list', '--json'], '/tmp/repo')
+
+    expect(listEnvironmentsMock).toHaveBeenCalledWith('/tmp/orca-user-data')
+    expect(callMock).not.toHaveBeenCalled()
+    expect(logSpy.mock.calls[0]?.[0]).not.toContain('token')
+    expect(logSpy.mock.calls[0]?.[0]).not.toContain('publicKeyB64')
+  })
+
+  it('adds saved environments even when ORCA_ENVIRONMENT is set', async () => {
+    process.env.ORCA_ENVIRONMENT = 'stale-env'
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['environment', 'add', '--name', 'desk', '--pairing-code', 'orca://pair#abc', '--json'],
+      '/tmp/repo'
+    )
+
+    expect(addEnvironmentFromPairingCodeMock).toHaveBeenCalledWith('/tmp/orca-user-data', {
+      name: 'desk',
+      pairingCode: 'orca://pair#abc'
+    })
+    expect(callMock).not.toHaveBeenCalled()
+    expect(logSpy.mock.calls[0]?.[0]).not.toContain('token')
+    expect(logSpy.mock.calls[0]?.[0]).not.toContain('publicKeyB64')
+  })
+
+  it('resolves repo.add paths against the invoking cli cwd', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_repo_add', {
+        repo: {
+          id: 'repo-1',
+          path: path.resolve('/tmp/repo/apps/web'),
+          displayName: 'web'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['repo', 'add', '--path', './apps/web', '--json'], '/tmp/repo')
+
+    expect(callMock).toHaveBeenCalledWith('repo.add', {
+      path: path.resolve('/tmp/repo/apps/web')
+    })
+  })
+
+  it('rejects remote repo.add relative paths instead of resolving against client cwd', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const priorExitCode = process.exitCode
+
+    await main(
+      ['repo', 'add', '--path', './apps/web', '--pairing-code', 'remote-runtime', '--json'],
+      '/tmp/repo'
+    )
+
+    expect(callMock).not.toHaveBeenCalled()
+    expect([...logSpy.mock.calls, ...errSpy.mock.calls].flat().join('\n')).toContain(
+      'Remote repo add requires --path to be an absolute path on the remote server.'
+    )
+    expect(process.exitCode).toBe(1)
+
+    process.exitCode = priorExitCode
+  })
+
+  it('sends remote repo.add absolute paths unchanged', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_repo_add', {
+        repo: {
+          id: 'repo-1',
+          path: '/srv/orca/web',
+          displayName: 'web'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['repo', 'add', '--path', '/srv/orca/web', '--pairing-code', 'remote-runtime', '--json'],
+      '/tmp/repo'
+    )
+
+    expect(callMock).toHaveBeenCalledWith('repo.add', {
+      path: '/srv/orca/web'
+    })
+  })
+
+  it.each(['C:\\repo', 'C:/repo', '\\\\server\\share\\repo', '//server/share/repo'])(
+    'sends remote repo.add server absolute path %s unchanged',
+    async (serverPath) => {
+      queueFixtures(
+        callMock,
+        okFixture('req_repo_add', {
+          repo: {
+            id: 'repo-1',
+            path: serverPath,
+            displayName: 'web'
+          }
+        })
+      )
+      vi.spyOn(console, 'log').mockImplementation(() => {})
+
+      await main(
+        ['repo', 'add', '--path', serverPath, '--pairing-code', 'remote-runtime', '--json'],
+        '/tmp/repo'
+      )
+
+      expect(callMock).toHaveBeenCalledWith('repo.add', {
+        path: serverPath
+      })
+    }
+  )
+
   it('opts into setup and activation when worktree.create runs hooks', async () => {
     queueFixtures(
       callMock,
@@ -352,4 +642,79 @@ describe('orca cli worktree awareness', () => {
       limit: undefined
     })
   })
+
+  it('rejects implicit remote terminal create instead of resolving from client cwd', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const priorExitCode = process.exitCode
+
+    await main(
+      ['terminal', 'create', '--pairing-code', 'remote-runtime', '--json'],
+      '/tmp/client/repo/src'
+    )
+
+    expect(callMock).not.toHaveBeenCalled()
+    expect([...logSpy.mock.calls, ...errSpy.mock.calls].flat().join('\n')).toContain(
+      'Remote terminal create requires --worktree'
+    )
+    expect(process.exitCode).toBe(1)
+
+    process.exitCode = priorExitCode
+  })
+
+  it('sends explicit remote terminal create worktree selectors unchanged', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_terminal_create', {
+        terminal: {
+          handle: 'term_1',
+          worktreeId: 'repo-1::/srv/orca/feature',
+          title: 'Server terminal'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      [
+        'terminal',
+        'create',
+        '--worktree',
+        'id:repo-1::/srv/orca/feature',
+        '--pairing-code',
+        'remote-runtime',
+        '--json'
+      ],
+      '/tmp/client/repo/src'
+    )
+
+    expect(callMock).toHaveBeenCalledWith('terminal.create', {
+      worktree: 'id:repo-1::/srv/orca/feature',
+      command: undefined,
+      title: undefined,
+      focus: false
+    })
+  })
+
+  it('does not resolve implicit remote browser targets from client cwd', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_tab_current', {
+        tab: {
+          browserPageId: 'page-1',
+          index: 0,
+          url: 'https://example.com',
+          title: 'Example',
+          active: true,
+          worktreeId: 'repo-1::/srv/orca/feature'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['tab', 'current', '--pairing-code', 'remote-runtime', '--json'], '/tmp/client/src')
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabCurrent', { worktree: undefined })
+  })
 })
diff --git a/src/cli/index.ts b/src/cli/index.ts
index ed015d1185d..00a96e9043f 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -15,6 +15,10 @@ import { COMMAND_SPECS } from './specs'
 export { COMMAND_SPECS } from './specs'
 export { buildCurrentWorktreeSelector, normalizeWorktreeSelector } from './selectors'
 
+function shouldIgnoreRemoteSelection(commandPath: string[]): boolean {
+  return commandPath[0] === 'environment' || commandPath[0] === 'serve'
+}
+
 export async function main(argv = process.argv.slice(2), cwd = process.cwd()): Promise<void> {
   const parsed = parseArgs(argv)
   const helpPath = resolveHelpPath(parsed)
@@ -40,7 +44,15 @@ export async function main(argv = process.argv.slice(2), cwd = process.cwd()): P
     // lookup so users do not get misleading "Orca is not running" failures for
     // simple command typos or unsupported flags.
     validateCommandAndFlags(COMMAND_SPECS, parsed)
-    const client = new RuntimeClient()
+    const ignoreRemoteSelection = shouldIgnoreRemoteSelection(parsed.commandPath)
+    const pairingCode = ignoreRemoteSelection ? null : parsed.flags.get('pairing-code')
+    const environmentSelector = ignoreRemoteSelection ? null : parsed.flags.get('environment')
+    const client = new RuntimeClient(
+      undefined,
+      undefined,
+      typeof pairingCode === 'string' ? pairingCode : undefined,
+      typeof environmentSelector === 'string' ? environmentSelector : undefined
+    )
     await dispatch(parsed.commandPath, {
       flags: parsed.flags,
       client,
diff --git a/src/cli/runtime-client.ts b/src/cli/runtime-client.ts
index 480637847eb..f88b116981b 100644
--- a/src/cli/runtime-client.ts
+++ b/src/cli/runtime-client.ts
@@ -6,6 +6,7 @@ export {
   RuntimeClient,
   RuntimeClientError,
   RuntimeRpcFailureError,
+  serveOrcaApp,
   getDefaultUserDataPath,
   type RuntimeRpcFailure,
   type RuntimeRpcResponse,
diff --git a/src/cli/runtime/client.ts b/src/cli/runtime/client.ts
index ae65cd4f34c..ab082aa16ad 100644
--- a/src/cli/runtime/client.ts
+++ b/src/cli/runtime/client.ts
@@ -1,9 +1,17 @@
-import type { CliStatusResult } from '../../shared/runtime-types'
+import type { CliStatusResult, RuntimeStatus } from '../../shared/runtime-types'
+import { parsePairingCode, type PairingOffer } from '../../shared/pairing'
 import { launchOrcaApp } from './launch'
 import { getDefaultUserDataPath, readMetadata } from './metadata'
 import { getCliStatus } from './status'
 import { sendRequest } from './transport'
 import { RuntimeClientError, RuntimeRpcFailureError, type RuntimeRpcSuccess } from './types'
+import { sendWebSocketRequest } from './websocket-transport'
+import { markEnvironmentUsed, resolveEnvironmentPairingOffer } from './environments'
+import { describeRuntimeCompatBlock, evaluateRuntimeCompat } from '../../shared/protocol-compat'
+import {
+  MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from '../../shared/protocol-version'
 
 // Why: for `orchestration.check --wait` the caller's method-level
 // `params.timeoutMs` is the inner waiter budget; we extend the client-side
@@ -16,13 +24,27 @@ const LONG_POLL_CLIENT_GRACE_MS = 10_000
 export class RuntimeClient {
   private readonly userDataPath: string
   private readonly requestTimeoutMs: number
+  private readonly remotePairing: PairingOffer | null
+  private readonly environmentSelector: string | null
+  private remoteCompatChecked = false
 
   // Why: browser commands trigger first-time session init (agent-browser connect +
   // CDP proxy setup) which can take 15-30s. 60s accommodates cold start without
   // being so large that genuine hangs go unnoticed.
-  constructor(userDataPath = getDefaultUserDataPath(), requestTimeoutMs = 60_000) {
+  constructor(
+    userDataPath = getDefaultUserDataPath(),
+    requestTimeoutMs = 60_000,
+    remotePairingCode = process.env.ORCA_PAIRING_CODE ?? process.env.ORCA_REMOTE_PAIRING ?? null,
+    environmentSelector = process.env.ORCA_ENVIRONMENT ?? null
+  ) {
     this.userDataPath = userDataPath
     this.requestTimeoutMs = requestTimeoutMs
+    this.environmentSelector = environmentSelector
+    this.remotePairing = resolveRemotePairing(userDataPath, remotePairingCode, environmentSelector)
+  }
+
+  get isRemote(): boolean {
+    return this.remotePairing !== null
   }
 
   async call<TResult>(
@@ -32,10 +54,30 @@ export class RuntimeClient {
       timeoutMs?: number
     }
   ): Promise<RuntimeRpcSuccess<TResult>> {
-    const metadata = readMetadata(this.userDataPath)
     const effectiveTimeoutMs = options?.timeoutMs ?? this.resolveMethodTimeoutMs(method, params)
+    if (this.remotePairing) {
+      if (method !== 'status.get') {
+        await this.ensureRemoteRuntimeCompatible(effectiveTimeoutMs)
+      }
+      const response = await sendWebSocketRequest<TResult>(
+        this.remotePairing,
+        method,
+        params,
+        effectiveTimeoutMs
+      )
+      if (response.ok === false) {
+        throw new RuntimeRpcFailureError(response)
+      }
+      if (this.environmentSelector) {
+        markEnvironmentUsed(this.userDataPath, this.environmentSelector, {
+          runtimeId: response._meta.runtimeId
+        })
+      }
+      return response
+    }
+    const metadata = readMetadata(this.userDataPath)
     const response = await sendRequest<TResult>(metadata, method, params, effectiveTimeoutMs)
-    if (!response.ok) {
+    if (response.ok === false) {
       throw new RuntimeRpcFailureError(response)
     }
     return response
@@ -58,9 +100,69 @@ export class RuntimeClient {
   }
 
   async getCliStatus(): Promise<RuntimeRpcSuccess<CliStatusResult>> {
+    if (this.remotePairing) {
+      const response = await this.call<RuntimeStatus>('status.get')
+      this.assertRemoteRuntimeStatusCompatible(response.result)
+      this.remoteCompatChecked = true
+      const graphState = response.result.graphStatus
+      return {
+        id: response.id,
+        ok: true,
+        result: {
+          app: {
+            running: true,
+            pid: null
+          },
+          runtime: {
+            state: graphState === 'ready' ? 'ready' : 'graph_not_ready',
+            reachable: true,
+            runtimeId: response.result.runtimeId
+          },
+          graph: {
+            state: graphState
+          }
+        },
+        _meta: response._meta
+      }
+    }
     return getCliStatus(this.userDataPath)
   }
 
+  private async ensureRemoteRuntimeCompatible(timeoutMs: number): Promise<void> {
+    if (!this.remotePairing || this.remoteCompatChecked) {
+      return
+    }
+    const response = await sendWebSocketRequest<RuntimeStatus>(
+      this.remotePairing,
+      'status.get',
+      undefined,
+      timeoutMs
+    )
+    if (response.ok === false) {
+      throw new RuntimeRpcFailureError(response)
+    }
+    this.assertRemoteRuntimeStatusCompatible(response.result)
+    this.remoteCompatChecked = true
+    if (this.environmentSelector) {
+      markEnvironmentUsed(this.userDataPath, this.environmentSelector, {
+        runtimeId: response._meta.runtimeId
+      })
+    }
+  }
+
+  private assertRemoteRuntimeStatusCompatible(status: RuntimeStatus): void {
+    const verdict = evaluateRuntimeCompat({
+      clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleServerProtocolVersion: MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+      serverProtocolVersion: status.runtimeProtocolVersion ?? status.protocolVersion,
+      serverMinCompatibleClientProtocolVersion:
+        status.minCompatibleRuntimeClientVersion ?? status.minCompatibleMobileVersion
+    })
+    if (verdict.kind === 'blocked') {
+      throw new RuntimeClientError('incompatible_runtime', describeRuntimeCompatBlock(verdict))
+    }
+  }
+
   async openOrca(timeoutMs = 15_000): Promise<RuntimeRpcSuccess<CliStatusResult>> {
     const initial = await this.getCliStatus()
     if (initial.result.runtime.reachable) {
@@ -84,6 +186,33 @@ export class RuntimeClient {
   }
 }
 
+function resolveRemotePairing(
+  userDataPath: string,
+  pairingCode: string | null,
+  environmentSelector: string | null
+): PairingOffer | null {
+  if (pairingCode && environmentSelector) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Use either --pairing-code or --environment, not both.'
+    )
+  }
+  if (environmentSelector) {
+    return resolveEnvironmentPairingOffer(userDataPath, environmentSelector)
+  }
+  if (!pairingCode) {
+    return null
+  }
+  const pairing = parsePairingCode(pairingCode)
+  if (!pairing) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Invalid remote pairing code. Expected an orca://pair#... URL or bare pairing payload.'
+    )
+  }
+  return pairing
+}
+
 function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
diff --git a/src/cli/runtime/envelope-schema.ts b/src/cli/runtime/envelope-schema.ts
index f674aab11af..3447c007769 100644
--- a/src/cli/runtime/envelope-schema.ts
+++ b/src/cli/runtime/envelope-schema.ts
@@ -1,62 +1,5 @@
-// Why: the Orca runtime is a separate process and may drift in version from
-// the CLI (older CLI talking to newer app, or vice versa during dev HMR). A
-// Zod schema at the decode boundary means a malformed frame surfaces as a
-// single legible error instead of a silent mis-typed access downstream.
-//
-// The envelope shape mirrors src/main/runtime/rpc/core.ts. `result` is left
-// unknown here — method-level types are checked by the caller via generics —
-// so only the frame is validated, not the payload.
-import { z } from 'zod'
-
-const MetaSuccess = z.object({
-  runtimeId: z.string()
-})
-
-const MetaFailure = z
-  .object({
-    runtimeId: z.union([z.string(), z.null()])
-  })
-  .optional()
-
-const Success = z.object({
-  id: z.string(),
-  ok: z.literal(true),
-  result: z.unknown(),
-  _meta: MetaSuccess
-})
-
-const Failure = z.object({
-  id: z.string(),
-  ok: z.literal(false),
-  error: z.object({
-    code: z.string(),
-    message: z.string(),
-    data: z.unknown().optional()
-  }),
-  _meta: MetaFailure
-})
-
-// Why: transport-layer keepalive frame (server→client only). Not a terminal
-// frame — the client reads past it and keeps waiting for the real
-// success/failure. `id` and `_meta` are deliberately absent: keepalives carry
-// no method-level semantics and aren't tied to a particular request (one
-// connection handles one request today). See design doc §3.1.
-const Keepalive = z.object({
-  _keepalive: z.literal(true)
-})
-
-// Why: switched from z.discriminatedUnion('ok', …) to z.union because
-// keepalives have no `ok` field. Client code must branch on
-// `'_keepalive' in frame` before treating the frame as Success/Failure.
-export const RuntimeRpcEnvelopeSchema = z.union([Success, Failure, Keepalive])
-
-export type RuntimeRpcKeepaliveFrame = z.infer<typeof Keepalive>
-
-export function isKeepaliveFrame(frame: unknown): frame is RuntimeRpcKeepaliveFrame {
-  return (
-    typeof frame === 'object' &&
-    frame !== null &&
-    '_keepalive' in frame &&
-    (frame as { _keepalive: unknown })._keepalive === true
-  )
-}
+export {
+  isKeepaliveFrame,
+  RuntimeRpcEnvelopeSchema,
+  type RuntimeRpcKeepaliveFrame
+} from '../../shared/runtime-rpc-envelope'
diff --git a/src/cli/runtime/environments.test.ts b/src/cli/runtime/environments.test.ts
new file mode 100644
index 00000000000..8c27060cdba
--- /dev/null
+++ b/src/cli/runtime/environments.test.ts
@@ -0,0 +1,68 @@
+import { mkdtempSync, statSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { describe, expect, it } from 'vitest'
+import { encodePairingOffer } from '../../shared/pairing'
+import {
+  addEnvironmentFromPairingCode,
+  getEnvironmentStorePath,
+  listEnvironments,
+  removeEnvironment,
+  resolveEnvironmentPairingOffer
+} from './environments'
+
+function pairingCode(endpoint = 'ws://127.0.0.1:6768'): string {
+  return encodePairingOffer({
+    v: 2,
+    endpoint,
+    deviceToken: 'device-token',
+    publicKeyB64: Buffer.from(new Uint8Array(32).fill(1)).toString('base64')
+  })
+}
+
+describe('CLI runtime environments', () => {
+  it('saves, resolves, and removes a paired environment', () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-env-store-'))
+    const saved = addEnvironmentFromPairingCode(userDataPath, {
+      name: 'workstation',
+      pairingCode: pairingCode(),
+      now: 100
+    })
+
+    expect(listEnvironments(userDataPath)).toHaveLength(1)
+    expect(resolveEnvironmentPairingOffer(userDataPath, 'workstation')).toMatchObject({
+      endpoint: 'ws://127.0.0.1:6768',
+      deviceToken: 'device-token'
+    })
+    expect(resolveEnvironmentPairingOffer(userDataPath, saved.id)).toMatchObject({
+      endpoint: 'ws://127.0.0.1:6768'
+    })
+    expect((statSync(getEnvironmentStorePath(userDataPath)).mode & 0o777).toString(8)).toBe('600')
+
+    const removed = removeEnvironment(userDataPath, 'workstation')
+    expect(removed.id).toBe(saved.id)
+    expect(listEnvironments(userDataPath)).toEqual([])
+  })
+
+  it('rejects an environment with the same name', () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-env-store-'))
+    const first = addEnvironmentFromPairingCode(userDataPath, {
+      name: 'workstation',
+      pairingCode: pairingCode('ws://127.0.0.1:1111'),
+      now: 100
+    })
+
+    expect(() =>
+      addEnvironmentFromPairingCode(userDataPath, {
+        name: 'workstation',
+        pairingCode: pairingCode('ws://127.0.0.1:2222'),
+        now: 200
+      })
+    ).toThrow('A server named "workstation" already exists.')
+    expect(listEnvironments(userDataPath)).toHaveLength(1)
+    expect(resolveEnvironmentPairingOffer(userDataPath, 'workstation').endpoint).toBe(
+      'ws://127.0.0.1:1111'
+    )
+    expect(listEnvironments(userDataPath)[0]?.id).toBe(first.id)
+  })
+})
diff --git a/src/cli/runtime/environments.ts b/src/cli/runtime/environments.ts
new file mode 100644
index 00000000000..3009b11c9cb
--- /dev/null
+++ b/src/cli/runtime/environments.ts
@@ -0,0 +1,81 @@
+import {
+  addEnvironmentFromPairingCode as addEnvironmentFromPairingCodeInStore,
+  getEnvironmentStorePath,
+  listEnvironments,
+  markEnvironmentUsed as markEnvironmentUsedInStore,
+  removeEnvironment as removeEnvironmentFromStore,
+  resolveEnvironment as resolveEnvironmentFromStore,
+  resolveEnvironmentPairingOffer as resolveEnvironmentPairingOfferFromStore,
+  RuntimeEnvironmentStoreError,
+  type RuntimeEnvironmentStoreErrorCode
+} from '../../shared/runtime-environment-store'
+import type {
+  KnownRuntimeEnvironment,
+  PublicKnownRuntimeEnvironment
+} from '../../shared/runtime-environments'
+import type { PairingOffer } from '../../shared/pairing'
+import { RuntimeClientError } from './types'
+
+export type EnvironmentAddResult = {
+  environment: PublicKnownRuntimeEnvironment
+}
+
+export type EnvironmentListResult = {
+  environments: PublicKnownRuntimeEnvironment[]
+}
+
+export type EnvironmentRemoveResult = {
+  removed: PublicKnownRuntimeEnvironment
+}
+
+export { getEnvironmentStorePath, listEnvironments }
+
+export function addEnvironmentFromPairingCode(
+  userDataPath: string,
+  args: { name: string; pairingCode: string; now?: number }
+): KnownRuntimeEnvironment {
+  return translateStoreError(() => addEnvironmentFromPairingCodeInStore(userDataPath, args))
+}
+
+export function removeEnvironment(userDataPath: string, selector: string): KnownRuntimeEnvironment {
+  return translateStoreError(() => removeEnvironmentFromStore(userDataPath, selector))
+}
+
+export function resolveEnvironment(
+  userDataPath: string,
+  selector: string
+): KnownRuntimeEnvironment {
+  return translateStoreError(() => resolveEnvironmentFromStore(userDataPath, selector))
+}
+
+export function resolveEnvironmentPairingOffer(
+  userDataPath: string,
+  selector: string
+): PairingOffer {
+  return translateStoreError(() => resolveEnvironmentPairingOfferFromStore(userDataPath, selector))
+}
+
+export function markEnvironmentUsed(
+  userDataPath: string,
+  selector: string,
+  args: { runtimeId?: string | null; now?: number } = {}
+): void {
+  translateStoreError(() => markEnvironmentUsedInStore(userDataPath, selector, args))
+}
+
+function translateStoreError<TResult>(fn: () => TResult): TResult {
+  try {
+    return fn()
+  } catch (error) {
+    if (error instanceof RuntimeEnvironmentStoreError) {
+      throw new RuntimeClientError(toRuntimeClientErrorCode(error.code), error.message)
+    }
+    throw error
+  }
+}
+
+function toRuntimeClientErrorCode(
+  code: RuntimeEnvironmentStoreErrorCode
+): 'invalid_argument' | 'runtime_error' {
+  return code
+}
diff --git a/src/cli/runtime/index.ts b/src/cli/runtime/index.ts
index b061c042b21..81d9fdf16c6 100644
--- a/src/cli/runtime/index.ts
+++ b/src/cli/runtime/index.ts
@@ -1,4 +1,5 @@
 export { RuntimeClient } from './client'
+export { serveOrcaApp } from './launch'
 export { getDefaultUserDataPath } from './metadata'
 export {
   RuntimeClientError,
diff --git a/src/cli/runtime/launch.test.ts b/src/cli/runtime/launch.test.ts
new file mode 100644
index 00000000000..807df9dc721
--- /dev/null
+++ b/src/cli/runtime/launch.test.ts
@@ -0,0 +1,88 @@
+import { resolve } from 'path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { spawnMock } = vi.hoisted(() => ({
+  spawnMock: vi.fn()
+}))
+
+vi.mock('child_process', () => ({
+  spawn: spawnMock
+}))
+
+import { serveOrcaApp } from './launch'
+
+describe('serveOrcaApp', () => {
+  beforeEach(() => {
+    spawnMock.mockReset()
+    process.env.ORCA_APP_EXECUTABLE = '/Applications/Orca.app/Contents/MacOS/Orca'
+  })
+
+  afterEach(() => {
+    delete process.env.ORCA_APP_EXECUTABLE
+  })
+
+  it('pins the Electron child cwd to the app root instead of the caller cwd', async () => {
+    const child = {
+      kill: vi.fn(),
+      once: vi.fn(
+        (event: string, handler: (code: number | null, signal: string | null) => void) => {
+          if (event === 'exit') {
+            queueMicrotask(() => handler(0, null))
+          }
+          return child
+        }
+      )
+    }
+    spawnMock.mockReturnValue(child)
+
+    await expect(serveOrcaApp({ json: true })).resolves.toBe(0)
+
+    expect(spawnMock).toHaveBeenCalledWith(
+      '/Applications/Orca.app/Contents/MacOS/Orca',
+      ['--serve', '--serve-json'],
+      expect.objectContaining({
+        cwd: resolve(__dirname, '../../..')
+      })
+    )
+  })
+
+  it('passes mobile pairing through to the foreground server child', async () => {
+    const child = {
+      kill: vi.fn(),
+      once: vi.fn(
+        (event: string, handler: (code: number | null, signal: string | null) => void) => {
+          if (event === 'exit') {
+            queueMicrotask(() => handler(0, null))
+          }
+          return child
+        }
+      )
+    }
+    spawnMock.mockReturnValue(child)
+
+    await expect(
+      serveOrcaApp({
+        json: true,
+        port: '6768',
+        pairingAddress: '100.64.1.20',
+        mobilePairing: true
+      })
+    ).resolves.toBe(0)
+
+    expect(spawnMock).toHaveBeenCalledWith(
+      '/Applications/Orca.app/Contents/MacOS/Orca',
+      [
+        '--serve',
+        '--serve-json',
+        '--serve-port',
+        '6768',
+        '--serve-pairing-address',
+        '100.64.1.20',
+        '--serve-mobile-pairing'
+      ],
+      expect.objectContaining({
+        cwd: resolve(__dirname, '../../..')
+      })
+    )
+  })
+})
diff --git a/src/cli/runtime/launch.ts b/src/cli/runtime/launch.ts
index b86cfb9b4d1..71de311177b 100644
--- a/src/cli/runtime/launch.ts
+++ b/src/cli/runtime/launch.ts
@@ -1,5 +1,5 @@
 import { spawn as spawnProcess } from 'child_process'
-import { dirname } from 'path'
+import { dirname, resolve } from 'path'
 import { RuntimeClientError } from './types'
 
 export function launchOrcaApp(): void {
@@ -53,6 +53,93 @@ export function launchOrcaApp(): void {
   )
 }
 
+export function serveOrcaApp(
+  args: {
+    json?: boolean
+    port?: string | null
+    pairingAddress?: string | null
+    noPairing?: boolean
+    mobilePairing?: boolean
+  } = {}
+): Promise<number> {
+  const executable = resolveForegroundOrcaExecutable()
+  const childArgs = ['--serve']
+  if (args.json) {
+    childArgs.push('--serve-json')
+  }
+  if (args.port) {
+    childArgs.push('--serve-port', args.port)
+  }
+  if (args.pairingAddress) {
+    childArgs.push('--serve-pairing-address', args.pairingAddress)
+  }
+  if (args.noPairing) {
+    childArgs.push('--serve-no-pairing')
+  }
+  if (args.mobilePairing) {
+    childArgs.push('--serve-mobile-pairing')
+  }
+
+  const child = spawnProcess(executable, childArgs, {
+    cwd: resolveAppRoot(),
+    stdio: 'inherit',
+    env: stripElectronRunAsNode(process.env)
+  })
+
+  return new Promise((resolve, reject) => {
+    let forceKillTimer: ReturnType<typeof setTimeout> | null = null
+    const forwardSignal = (signal: NodeJS.Signals): void => {
+      child.kill(signal)
+      forceKillTimer ??= setTimeout(() => {
+        child.kill('SIGKILL')
+      }, 5000)
+    }
+    const cleanup = (): void => {
+      process.off('SIGINT', forwardSignal)
+      process.off('SIGTERM', forwardSignal)
+      if (forceKillTimer) {
+        clearTimeout(forceKillTimer)
+        forceKillTimer = null
+      }
+    }
+    process.on('SIGINT', forwardSignal)
+    process.on('SIGTERM', forwardSignal)
+    child.once('error', (error) => {
+      cleanup()
+      reject(error)
+    })
+    child.once('exit', (code, signal) => {
+      cleanup()
+      if (typeof code === 'number') {
+        resolve(code)
+        return
+      }
+      reject(new RuntimeClientError('runtime_serve_failed', `Orca serve exited via ${signal}`))
+    })
+  })
+}
+
+function resolveAppRoot(): string {
+  // Why: dev-mode resource resolution in the Electron child may consult
+  // process.cwd(). Pin it to the app root so `orca serve` behaves the same
+  // regardless of the shell directory it was launched from.
+  return resolve(__dirname, '../../..')
+}
+
+function resolveForegroundOrcaExecutable(): string {
+  const overrideExecutable = process.env.ORCA_APP_EXECUTABLE
+  if (typeof overrideExecutable === 'string' && overrideExecutable.trim().length > 0) {
+    return overrideExecutable
+  }
+  if (process.env.ELECTRON_RUN_AS_NODE === '1') {
+    return process.execPath
+  }
+  throw new RuntimeClientError(
+    'runtime_serve_failed',
+    'Could not determine how to start Orca server. Set ORCA_APP_EXECUTABLE to the Orca executable.'
+  )
+}
+
 function stripElectronRunAsNode(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   const next = { ...env }
   delete next.ELECTRON_RUN_AS_NODE
diff --git a/src/cli/runtime/status.ts b/src/cli/runtime/status.ts
index 3a0f445a40f..bbf5e7e272f 100644
--- a/src/cli/runtime/status.ts
+++ b/src/cli/runtime/status.ts
@@ -29,7 +29,7 @@ export async function getCliStatus(
 
   try {
     const response = await sendRequest<RuntimeStatus>(metadata, 'status.get', undefined, 1000)
-    if (!response.ok) {
+    if (response.ok === false) {
       throw new RuntimeRpcFailureError(response)
     }
     const graphState = response.result.graphStatus
diff --git a/src/cli/runtime/transport.ts b/src/cli/runtime/transport.ts
index ca8ca746274..ee80e484a6d 100644
--- a/src/cli/runtime/transport.ts
+++ b/src/cli/runtime/transport.ts
@@ -49,10 +49,10 @@ export async function sendRequest<TResult>(
       settled = true
       clearTimeout(timeout)
       socket.end()
-      if (result.ok) {
-        resolve(result.response)
-      } else {
+      if (result.ok === false) {
         reject(result.error)
+      } else {
+        resolve(result.response)
       }
     }
 
diff --git a/src/cli/runtime/types.ts b/src/cli/runtime/types.ts
index e427c87b5de..220d3e3aba5 100644
--- a/src/cli/runtime/types.ts
+++ b/src/cli/runtime/types.ts
@@ -1,31 +1,10 @@
-// Why: the RPC envelope shape is the contract the CLI shares with the main
-// runtime. Keeping the types and error classes in one leaf module lets every
-// other runtime module depend on them without pulling in transport or launch
-// code.
+import type { RuntimeRpcFailure } from '../../shared/runtime-rpc-envelope'
 
-export type RuntimeRpcSuccess<TResult> = {
-  id: string
-  ok: true
-  result: TResult
-  _meta: {
-    runtimeId: string
-  }
-}
-
-export type RuntimeRpcFailure = {
-  id: string
-  ok: false
-  error: {
-    code: string
-    message: string
-    data?: unknown
-  }
-  _meta?: {
-    runtimeId: string | null
-  }
-}
-
-export type RuntimeRpcResponse<TResult> = RuntimeRpcSuccess<TResult> | RuntimeRpcFailure
+export type {
+  RuntimeRpcFailure,
+  RuntimeRpcResponse,
+  RuntimeRpcSuccess
+} from '../../shared/runtime-rpc-envelope'
 
 export class RuntimeClientError extends Error {
   readonly code: string
diff --git a/src/cli/runtime/websocket-transport.test.ts b/src/cli/runtime/websocket-transport.test.ts
new file mode 100644
index 00000000000..38ccf06f956
--- /dev/null
+++ b/src/cli/runtime/websocket-transport.test.ts
@@ -0,0 +1,237 @@
+import { createServer, type Server } from 'http'
+import { mkdtempSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { WebSocketServer } from 'ws'
+import { encodePairingOffer, type PairingOffer } from '../../shared/pairing'
+import {
+  decrypt,
+  deriveSharedKey,
+  encrypt,
+  generateKeyPair,
+  publicKeyToBase64
+} from '../../shared/e2ee-crypto'
+import { RuntimeClient } from './client'
+import { addEnvironmentFromPairingCode } from './environments'
+import { RuntimeClientError } from './types'
+import {
+  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from '../../shared/protocol-version'
+
+type TestRuntime = {
+  endpoint: string
+  publicKeyB64: string
+  deviceToken: string
+  close: () => Promise<void>
+}
+
+describe('CLI remote WebSocket transport', () => {
+  const servers: TestRuntime[] = []
+
+  afterEach(async () => {
+    await Promise.all(servers.splice(0).map((server) => server.close()))
+  })
+
+  it('calls a remote runtime through a mobile pairing offer', async () => {
+    const runtime = await startTestRuntime('runtime-ws-1')
+    servers.push(runtime)
+
+    const pairingUrl = encodePairingOffer({
+      v: 2,
+      endpoint: runtime.endpoint,
+      deviceToken: runtime.deviceToken,
+      publicKeyB64: runtime.publicKeyB64
+    })
+    const client = new RuntimeClient('/tmp/unused', 5_000, pairingUrl)
+    const response = await client.call<{ runtimeId: string }>('status.get')
+
+    expect(response.ok).toBe(true)
+    expect(response.result.runtimeId).toBe('runtime-ws-1')
+  })
+
+  it('rejects malformed remote pairing codes before local runtime lookup', () => {
+    expect(() => new RuntimeClient('/tmp/unused', 5_000, 'not-a-pairing-code')).toThrow(
+      RuntimeClientError
+    )
+  })
+
+  it('accepts a bare pairing payload as well as the orca URL wrapper', async () => {
+    const runtime = await startTestRuntime('runtime-ws-2')
+    servers.push(runtime)
+    const offer: PairingOffer = {
+      v: 2,
+      endpoint: runtime.endpoint,
+      deviceToken: runtime.deviceToken,
+      publicKeyB64: runtime.publicKeyB64
+    }
+    const barePayload = encodePairingOffer(offer).split('#')[1]!
+
+    const client = new RuntimeClient('/tmp/unused', 5_000, barePayload)
+    const status = await client.getCliStatus()
+
+    expect(status.result.runtime.reachable).toBe(true)
+    expect(status.result.runtime.runtimeId).toBe('runtime-ws-2')
+  })
+
+  it('connects through a saved environment selector', async () => {
+    const runtime = await startTestRuntime('runtime-env-1')
+    servers.push(runtime)
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-cli-env-'))
+    addEnvironmentFromPairingCode(userDataPath, {
+      name: 'remote-dev',
+      pairingCode: encodePairingOffer({
+        v: 2,
+        endpoint: runtime.endpoint,
+        deviceToken: runtime.deviceToken,
+        publicKeyB64: runtime.publicKeyB64
+      })
+    })
+
+    const client = new RuntimeClient(userDataPath, 5_000, null, 'remote-dev')
+    const status = await client.getCliStatus()
+
+    expect(status.result.runtime.reachable).toBe(true)
+    expect(status.result.runtime.runtimeId).toBe('runtime-env-1')
+  })
+
+  it('blocks remote RPCs when the server protocol is too old', async () => {
+    const runtime = await startTestRuntime('runtime-old', { runtimeProtocolVersion: 1 })
+    servers.push(runtime)
+
+    const client = new RuntimeClient(
+      '/tmp/unused',
+      5_000,
+      encodePairingOffer({
+        v: 2,
+        endpoint: runtime.endpoint,
+        deviceToken: runtime.deviceToken,
+        publicKeyB64: runtime.publicKeyB64
+      })
+    )
+
+    await expect(client.call('repo.list')).rejects.toMatchObject({
+      code: 'incompatible_runtime',
+      message: expect.stringContaining('server is too old')
+    })
+  })
+})
+
+async function startTestRuntime(
+  runtimeId: string,
+  statusOverrides: {
+    runtimeProtocolVersion?: number
+    minCompatibleRuntimeClientVersion?: number
+  } = {}
+): Promise<TestRuntime> {
+  const serverKeyPair = generateKeyPair()
+  const deviceToken = `token-${runtimeId}`
+  const httpServer = createServer()
+  const wss = new WebSocketServer({ server: httpServer })
+
+  wss.on('connection', (ws) => {
+    let sharedKey: Uint8Array | null = null
+    let authenticated = false
+
+    ws.on('message', (data) => {
+      const frame = data.toString()
+      if (!sharedKey) {
+        const hello = JSON.parse(frame) as { type?: string; publicKeyB64?: string }
+        const clientPublicKey = Buffer.from(hello.publicKeyB64 ?? '', 'base64')
+        sharedKey = deriveSharedKey(serverKeyPair.secretKey, clientPublicKey)
+        ws.send(JSON.stringify({ type: 'e2ee_ready' }))
+        return
+      }
+
+      const plaintext = decrypt(frame, sharedKey)
+      if (!plaintext) {
+        ws.close(4003, 'decrypt failed')
+        return
+      }
+      if (!authenticated) {
+        const auth = JSON.parse(plaintext) as { type?: string; deviceToken?: string }
+        if (auth.type !== 'e2ee_auth' || auth.deviceToken !== deviceToken) {
+          ws.send(encrypt(JSON.stringify({ type: 'e2ee_error' }), sharedKey))
+          ws.close(4001, 'auth failed')
+          return
+        }
+        authenticated = true
+        ws.send(encrypt(JSON.stringify({ type: 'e2ee_authenticated' }), sharedKey))
+        return
+      }
+
+      const request = JSON.parse(plaintext) as { id: string; method: string }
+      const response =
+        request.method === 'status.get'
+          ? {
+              id: request.id,
+              ok: true,
+              result: {
+                runtimeId,
+                rendererGraphEpoch: 1,
+                graphStatus: 'ready',
+                authoritativeWindowId: null,
+                liveTabCount: 0,
+                liveLeafCount: 0,
+                runtimeProtocolVersion:
+                  statusOverrides.runtimeProtocolVersion ?? RUNTIME_PROTOCOL_VERSION,
+                minCompatibleRuntimeClientVersion:
+                  statusOverrides.minCompatibleRuntimeClientVersion ??
+                  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
+              },
+              _meta: { runtimeId }
+            }
+          : {
+              id: request.id,
+              ok: false,
+              error: { code: 'method_not_found', message: 'Unknown method' },
+              _meta: { runtimeId }
+            }
+      ws.send(encrypt(JSON.stringify(response), sharedKey))
+    })
+  })
+
+  await listen(httpServer)
+  const address = httpServer.address()
+  if (!address || typeof address === 'string') {
+    throw new Error('Expected TCP test server')
+  }
+
+  return {
+    endpoint: `ws://127.0.0.1:${address.port}`,
+    publicKeyB64: publicKeyToBase64(serverKeyPair.publicKey),
+    deviceToken,
+    close: async () => {
+      await new Promise<void>((resolve) => {
+        wss.close(() => resolve())
+        for (const client of wss.clients) {
+          client.close()
+        }
+      })
+      await closeHttpServer(httpServer)
+    }
+  }
+}
+
+async function listen(server: Server): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject)
+      resolve()
+    })
+  })
+}
+
+async function closeHttpServer(server: Server): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+      resolve()
+    })
+  })
+}
diff --git a/src/cli/runtime/websocket-transport.ts b/src/cli/runtime/websocket-transport.ts
new file mode 100644
index 00000000000..ac5fc677919
--- /dev/null
+++ b/src/cli/runtime/websocket-transport.ts
@@ -0,0 +1,22 @@
+import type { PairingOffer } from '../../shared/pairing'
+import {
+  RemoteRuntimeClientError,
+  sendRemoteRuntimeRequest
+} from '../../shared/remote-runtime-client'
+import { RuntimeClientError, type RuntimeRpcResponse } from './types'
+
+export async function sendWebSocketRequest<TResult>(
+  pairing: PairingOffer,
+  method: string,
+  params: unknown,
+  timeoutMs: number
+): Promise<RuntimeRpcResponse<TResult>> {
+  try {
+    return await sendRemoteRuntimeRequest<TResult>(pairing, method, params, timeoutMs)
+  } catch (error) {
+    if (error instanceof RemoteRuntimeClientError) {
+      throw new RuntimeClientError(error.code, error.message)
+    }
+    throw error
+  }
+}
diff --git a/src/cli/selectors.ts b/src/cli/selectors.ts
index 14420cebb69..c56d4f152e0 100644
--- a/src/cli/selectors.ts
+++ b/src/cli/selectors.ts
@@ -1,5 +1,6 @@
 import { isAbsolute, relative, resolve as resolvePath } from 'path'
 import type { ComputerAppQuery, RuntimeWorktreeListResult } from '../shared/runtime-types'
+import { isPathInsideOrEqual } from '../shared/cross-platform-path'
 import type { RuntimeClient } from './runtime-client'
 import { RuntimeClientError } from './runtime-client'
 import { getOptionalStringFlag, getRequiredStringFlag } from './flags'
@@ -26,7 +27,22 @@ export function normalizeWorktreeSelector(selector: string, cwd: string): string
   return selector
 }
 
+function assertLocalCwdWorktreeSelector(selector: string, client: RuntimeClient): void {
+  if (!client.isRemote) {
+    return
+  }
+  // Why: a paired CLI's cwd belongs to the client machine, not the runtime
+  // server, so cwd-derived worktree selectors are only valid locally.
+  throw new RuntimeClientError(
+    'invalid_argument',
+    `${selector} is a local cwd shortcut and cannot be resolved against a remote runtime. Pass an explicit server-side worktree selector such as id:<id>, branch:<branch>, issue:<number>, or path:<absolute-server-path>.`
+  )
+}
+
 function isWithinPath(parentPath: string, childPath: string): boolean {
+  if (isPathInsideOrEqual(parentPath, childPath)) {
+    return true
+  }
   const relativePath = relative(parentPath, childPath)
   return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath))
 }
@@ -35,6 +51,8 @@ export async function resolveCurrentWorktreeSelector(
   cwd: string,
   client: RuntimeClient
 ): Promise<string> {
+  assertLocalCwdWorktreeSelector('current', client)
+
   const currentPath = resolvePath(cwd)
   const worktrees = await client.call<RuntimeWorktreeListResult>('worktree.list', {
     limit: 10_000
@@ -68,6 +86,7 @@ export async function getOptionalWorktreeSelector(
     return undefined
   }
   if (value === 'active' || value === 'current') {
+    assertLocalCwdWorktreeSelector(value, client)
     return await resolveCurrentWorktreeSelector(cwd, client)
   }
   return normalizeWorktreeSelector(value, cwd)
@@ -81,13 +100,14 @@ export async function getRequiredWorktreeSelector(
 ): Promise<string> {
   const value = getRequiredStringFlag(flags, name)
   if (value === 'active' || value === 'current') {
+    assertLocalCwdWorktreeSelector(value, client)
     return await resolveCurrentWorktreeSelector(cwd, client)
   }
   return normalizeWorktreeSelector(value, cwd)
 }
 
-// Why: browser commands default to the current worktree (auto-resolve from cwd).
-// --worktree all bypasses filtering. Omitting --worktree auto-resolves.
+// Why: local browser commands default to the current worktree by auto-resolving
+// from cwd. Remote commands omit worktree so the runtime uses server-side focus.
 export async function getBrowserWorktreeSelector(
   flags: Map<string, string | boolean>,
   cwd: string,
@@ -99,10 +119,14 @@ export async function getBrowserWorktreeSelector(
   }
   if (value) {
     if (value === 'active' || value === 'current') {
+      assertLocalCwdWorktreeSelector(value, client)
       return await resolveCurrentWorktreeSelector(cwd, client)
     }
     return normalizeWorktreeSelector(value, cwd)
   }
+  if (client.isRemote) {
+    return undefined
+  }
   // Default: auto-resolve from cwd
   try {
     return await resolveCurrentWorktreeSelector(cwd, client)
@@ -146,6 +170,7 @@ export async function getBrowserCommandTarget(
     return { page }
   }
   if (explicitWorktree === 'active' || explicitWorktree === 'current') {
+    assertLocalCwdWorktreeSelector(explicitWorktree, client)
     return {
       page,
       worktree: await resolveCurrentWorktreeSelector(cwd, client)
diff --git a/src/cli/specs/core.ts b/src/cli/specs/core.ts
index b85424e8ac0..f8f6d8ffb00 100644
--- a/src/cli/specs/core.ts
+++ b/src/cli/specs/core.ts
@@ -9,6 +9,24 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [
     allowedFlags: [...GLOBAL_FLAGS],
     examples: ['orca open', 'orca open --json']
   },
+  {
+    path: ['serve'],
+    summary: 'Start an Orca runtime server without opening a desktop window',
+    usage:
+      'orca serve [--port <port>] [--pairing-address <host>] [--mobile-pairing] [--no-pairing] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'port', 'pairing-address', 'mobile-pairing', 'no-pairing'],
+    notes: [
+      'Runs in the foreground and prints the runtime endpoint. Stop it with Ctrl+C.',
+      'Use --pairing-address when clients should connect through a LAN, Tailscale, SSH-forward, or public tunnel address.',
+      'Use --mobile-pairing to print a mobile-scoped pairing QR/link instead of the default runtime-environment pairing link.'
+    ],
+    examples: [
+      'orca serve',
+      'orca serve --json',
+      'orca serve --port 6768 --pairing-address 100.64.1.20',
+      'orca serve --pairing-address 100.64.1.20 --mobile-pairing'
+    ]
+  },
   {
     path: ['status'],
     summary: 'Show app/runtime/graph readiness',
diff --git a/src/cli/specs/environment.ts b/src/cli/specs/environment.ts
new file mode 100644
index 00000000000..6bfe1940b65
--- /dev/null
+++ b/src/cli/specs/environment.ts
@@ -0,0 +1,30 @@
+import type { CommandSpec } from '../args'
+import { GLOBAL_FLAGS } from '../args'
+
+export const ENVIRONMENT_COMMAND_SPECS: CommandSpec[] = [
+  {
+    path: ['environment', 'add'],
+    summary: 'Save a remote Orca runtime environment from a pairing code',
+    usage: 'orca environment add --name <name> --pairing-code <code> [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'name'],
+    examples: ['orca environment add --name work-laptop --pairing-code orca://pair#...']
+  },
+  {
+    path: ['environment', 'list'],
+    summary: 'List saved Orca runtime environments',
+    usage: 'orca environment list [--json]',
+    allowedFlags: [...GLOBAL_FLAGS]
+  },
+  {
+    path: ['environment', 'show'],
+    summary: 'Show one saved Orca runtime environment',
+    usage: 'orca environment show --environment <selector> [--json]',
+    allowedFlags: [...GLOBAL_FLAGS]
+  },
+  {
+    path: ['environment', 'rm'],
+    summary: 'Remove one saved Orca runtime environment',
+    usage: 'orca environment rm --environment <selector> [--json]',
+    allowedFlags: [...GLOBAL_FLAGS]
+  }
+]
diff --git a/src/cli/specs/index.ts b/src/cli/specs/index.ts
index 0828ef9b557..ebcbb022fcd 100644
--- a/src/cli/specs/index.ts
+++ b/src/cli/specs/index.ts
@@ -4,6 +4,7 @@ import { BROWSER_BASIC_COMMAND_SPECS } from './browser-basic'
 import { CORE_COMMAND_SPECS } from './core'
 import { ORCHESTRATION_COMMAND_SPECS } from './orchestration'
 import { COMPUTER_COMMAND_SPECS } from './computer'
+import { ENVIRONMENT_COMMAND_SPECS } from './environment'
 import { NOTE_COMMAND_SPECS } from './note'
 
 export const COMMAND_SPECS: CommandSpec[] = [
@@ -12,5 +13,6 @@ export const COMMAND_SPECS: CommandSpec[] = [
   ...BROWSER_ADVANCED_COMMAND_SPECS,
   ...ORCHESTRATION_COMMAND_SPECS,
   ...COMPUTER_COMMAND_SPECS,
+  ...ENVIRONMENT_COMMAND_SPECS,
   ...NOTE_COMMAND_SPECS
 ]
diff --git a/src/main/cli/packaged-cli-assets.test.ts b/src/main/cli/packaged-cli-assets.test.ts
new file mode 100644
index 00000000000..615f382cf18
--- /dev/null
+++ b/src/main/cli/packaged-cli-assets.test.ts
@@ -0,0 +1,19 @@
+import { createRequire } from 'node:module'
+import { describe, expect, it } from 'vitest'
+
+const require = createRequire(import.meta.url)
+const builderConfig = require('../../../config/electron-builder.config.cjs') as {
+  asarUnpack?: string[]
+}
+
+describe('packaged CLI assets', () => {
+  it('unpacks runtime dependencies used before Electron asar integration is available', () => {
+    expect(builderConfig.asarUnpack).toEqual(
+      expect.arrayContaining([
+        'node_modules/ws/**',
+        'node_modules/tweetnacl/**',
+        'node_modules/zod/**'
+      ])
+    )
+  })
+})
diff --git a/src/main/git/status.test.ts b/src/main/git/status.test.ts
index c9fc0ecc357..3a815558c18 100644
--- a/src/main/git/status.test.ts
+++ b/src/main/git/status.test.ts
@@ -220,10 +220,14 @@ describe('getDiff', () => {
 
     const result = await getDiff('/repo', 'src/file.ts', false)
 
-    expect(gitExecFileAsyncBufferMock).toHaveBeenNthCalledWith(2, ['show', 'HEAD:src/file.ts'], {
-      cwd: '/repo',
-      maxBuffer: 10 * 1024 * 1024
-    })
+    expect(gitExecFileAsyncBufferMock).toHaveBeenNthCalledWith(
+      2,
+      ['show', '--end-of-options', 'HEAD:src/file.ts'],
+      {
+        cwd: '/repo',
+        maxBuffer: 10 * 1024 * 1024
+      }
+    )
     expect(result.originalContent).toBe('head-content\n')
     expect(result.modifiedContent).toBe('working-tree-content')
   })
diff --git a/src/main/git/status.ts b/src/main/git/status.ts
index 0934e6d1013..b24535d4454 100644
--- a/src/main/git/status.ts
+++ b/src/main/git/status.ts
@@ -551,7 +551,7 @@ async function resolveCompareRef(worktreePath: string): Promise<string> {
 }
 
 async function resolveRefOid(worktreePath: string, ref: string): Promise<string> {
-  const { stdout } = await gitExecFileAsync(['rev-parse', '--verify', ref], {
+  const { stdout } = await gitExecFileAsync(['rev-parse', '--verify', '--end-of-options', ref], {
     cwd: worktreePath
   })
   return stdout.trim()
@@ -613,10 +613,13 @@ async function readGitBlobAtOidPath(
   filePath: string
 ): Promise<GitBlobReadResult> {
   try {
-    const { stdout } = await gitExecFileAsyncBuffer(['show', `${oid}:${filePath}`], {
-      cwd: worktreePath,
-      maxBuffer: MAX_GIT_SHOW_BYTES
-    })
+    const { stdout } = await gitExecFileAsyncBuffer(
+      ['show', '--end-of-options', `${oid}:${filePath}`],
+      {
+        cwd: worktreePath,
+        maxBuffer: MAX_GIT_SHOW_BYTES
+      }
+    )
 
     return { ...bufferToBlob(stdout, filePath), exists: true }
   } catch {
diff --git a/src/main/index.ts b/src/main/index.ts
index 47de211cc30..19c20b07e10 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -5,6 +5,7 @@
 import { grantDirAcl } from './win32-utils'
 import { app, BrowserWindow, nativeImage, nativeTheme } from 'electron'
 import { electronApp, is } from '@electron-toolkit/utils'
+import * as QRCode from 'qrcode'
 import devIcon from '../../resources/icon-dev.png?asset'
 import { Store, initDataPath } from './persistence'
 import { StatsCollector, initStatsPath } from './stats/collector'
@@ -51,7 +52,12 @@ import { codexHookService } from './codex/hook-service'
 import { geminiHookService } from './gemini/hook-service'
 import { cursorHookService } from './cursor/hook-service'
 import { droidHookService } from './droid/hook-service'
-import { getPtyIdForPaneKey, registerPaneKeyTeardownListener, getLocalPtyProvider } from './ipc/pty'
+import {
+  getPtyIdForPaneKey,
+  registerPaneKeyTeardownListener,
+  getLocalPtyProvider,
+  registerHeadlessPtyRuntime
+} from './ipc/pty'
 import { AgentBrowserBridge } from './browser/agent-browser-bridge'
 import { browserManager } from './browser/browser-manager'
 import { setUnreadDockBadgeCount } from './dock/unread-badge'
@@ -79,6 +85,7 @@ let disposeFeatureWallFirstAgentTour: (() => void) | null = null
 let watcherShutdownPromise: Promise<void> | null = null
 let watcherShutdownDone = false
 let automations: AutomationService | null = null
+const isServeMode = process.argv.includes('--serve')
 
 installUncaughtPipeErrorGuard()
 // Why: propagate the Orca app version into `process.env` so PTY-env
@@ -141,7 +148,8 @@ function focusExistingWindow(): void {
 // agent work, so that routing ambiguity is acceptable. Packaged Orca keeps
 // the lock to protect against the corruption documented in PR #1326 /
 // issue #1312.
-const hasSingleInstanceLock = is.dev ? true : acquireSingleInstanceLock(app, focusExistingWindow)
+const hasSingleInstanceLock =
+  is.dev && !isServeMode ? true : acquireSingleInstanceLock(app, focusExistingWindow)
 if (!hasSingleInstanceLock) {
   if (is.dev) {
     // Why: packaged runs have no attached console, but dev runs do. Emit a
@@ -160,8 +168,12 @@ if (!hasSingleInstanceLock) {
 // below happen — those handlers only fire after whenReady, which app.quit()
 // prevents from ever dispatching.
 if (hasSingleInstanceLock) {
-  installDevParentDisconnectQuit(is.dev)
-  installDevParentWatchdog(is.dev)
+  // Why: dev parent shutdown coupling is only for electron-vite desktop runs.
+  // `orca serve` may be launched through a CLI shim or background shell whose
+  // parent lifetime is not the intended server lifetime.
+  const shouldCoupleToDevParent = is.dev && !isServeMode
+  installDevParentDisconnectQuit(shouldCoupleToDevParent)
+  installDevParentWatchdog(shouldCoupleToDevParent)
   // Why: must run after configureDevUserDataPath (which redirects userData to
   // orca-dev in dev mode) but before app.setName('Orca') inside whenReady
   // (which would change the resolved path on case-sensitive filesystems).
@@ -392,6 +404,108 @@ const syntheticTitleSpinnerByPaneKey = new Map<
   { timer: ReturnType<typeof setInterval>; frame: number; profile: SyntheticTitleProfile }
 >()
 
+type ServeOptions = {
+  json: boolean
+  wsPort?: number
+  pairingAddress: string | null
+  noPairing: boolean
+  mobilePairing: boolean
+}
+
+function getServeOptions(argv = process.argv): ServeOptions {
+  const valueAfter = (flag: string): string | null => {
+    const index = argv.indexOf(flag)
+    if (index === -1) {
+      return null
+    }
+    const value = argv[index + 1]
+    return value && !value.startsWith('--') ? value : null
+  }
+  const rawPort = valueAfter('--serve-port')
+  let wsPort: number | undefined
+  if (rawPort) {
+    const parsedPort = Number(rawPort)
+    if (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {
+      throw new Error(`Invalid --serve-port value: ${rawPort}`)
+    }
+    wsPort = parsedPort
+  }
+  return {
+    json: argv.includes('--serve-json'),
+    ...(wsPort !== undefined ? { wsPort } : {}),
+    pairingAddress: valueAfter('--serve-pairing-address'),
+    noPairing: argv.includes('--serve-no-pairing'),
+    mobilePairing: argv.includes('--serve-mobile-pairing')
+  }
+}
+
+async function renderTerminalPairingQr(pairingUrl: string): Promise<string | null> {
+  try {
+    return await QRCode.toString(pairingUrl, { type: 'terminal', small: true })
+  } catch {
+    try {
+      return await QRCode.toString(pairingUrl, { type: 'utf8' })
+    } catch {
+      return null
+    }
+  }
+}
+
+async function printServeReady(options: ServeOptions): Promise<void> {
+  if (!runtime || !runtimeRpc) {
+    throw new Error('Runtime server must be initialized before printing serve readiness')
+  }
+  const endpoint = runtimeRpc.getWebSocketEndpoint()
+  const pairing = options.noPairing
+    ? ({ available: false } as const)
+    : runtimeRpc.createPairingOffer({
+        address: options.pairingAddress,
+        name: `${options.mobilePairing ? 'Mobile' : 'CLI'} ${new Date().toLocaleDateString()}`,
+        scope: options.mobilePairing ? 'mobile' : 'runtime'
+      })
+  const pairingQr =
+    pairing.available && options.mobilePairing
+      ? await renderTerminalPairingQr(pairing.pairingUrl)
+      : null
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        type: 'orca_server_ready',
+        runtimeId: runtime.getRuntimeId(),
+        endpoint,
+        pairing: pairing.available
+          ? {
+              url: pairing.pairingUrl,
+              endpoint: pairing.endpoint,
+              deviceId: pairing.deviceId,
+              scope: options.mobilePairing ? 'mobile' : 'runtime',
+              qr: pairingQr
+            }
+          : null
+      })
+    )
+    return
+  }
+  console.log(`Orca server ready: ${endpoint ?? 'websocket unavailable'}`)
+  if (pairing.available) {
+    if (options.mobilePairing && pairingQr) {
+      console.log(`Mobile pairing QR:\n${pairingQr}`)
+    }
+    console.log(`Pairing URL: ${pairing.pairingUrl}`)
+  }
+}
+
+function installServeSignalHandlers(): void {
+  const quit = (): void => {
+    // Why: foreground `orca serve` is controlled by the parent CLI/terminal,
+    // so POSIX termination signals should follow Electron's normal quit path
+    // and flush runtime metadata, daemon checkpoints, and telemetry.
+    app.quit()
+  }
+  process.once('SIGINT', quit)
+  process.once('SIGTERM', quit)
+}
+
 // Why: on PTY teardown the paneKey→ptyId mapping is dropped, so the spinner
 // interval would keep firing but sendSyntheticTitle would no-op forever.
 // Stop the interval explicitly so the process doesn't carry a timer per dead
@@ -622,38 +736,70 @@ app.whenReady().then(async () => {
   // ws://127.0.0.1:6769 is stable; a second dev instance still falls back via
   // ws-transport's EADDRINUSE handler.
   const devWsPort = is.dev && !isE2E ? 6769 : undefined
+  let serveOptions: ServeOptions | null = null
+  try {
+    serveOptions = isServeMode ? getServeOptions() : null
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    app.exit(1)
+    return
+  }
   runtimeRpc = new OrcaRuntimeRpcServer({
     runtime,
     userDataPath: app.getPath('userData'),
     enableWebSocket: true,
     ...(isE2E ? { wsPort: 0 } : {}),
-    ...(devWsPort !== undefined ? { wsPort: devWsPort } : {})
+    ...(devWsPort !== undefined ? { wsPort: devWsPort } : {}),
+    ...(serveOptions?.wsPort !== undefined ? { wsPort: serveOptions.wsPort } : {})
   })
   registerMobileHandlers(runtimeRpc)
 
-  await startFirstWindowStartupServices({
-    // Why: the persistent-terminal daemon is always started. If it fails, the
-    // LocalPtyProvider remains as the implicit fallback — terminals work, just
-    // without cross-restart persistence.
-    startDaemonPtyProvider: () => initDaemonPtyProvider(),
-    // Why: PTY spawn env reads ORCA_AGENT_HOOK_* from the live server state,
-    // so the hook server must start before restored terminals can mount.
-    startAgentHookServer: () =>
-      agentHookServer.start({
-        env: app.isPackaged ? 'production' : 'development',
-        // Why: hooks source this endpoint file at invocation time, so old PTY
-        // env still reaches the current Orca process after an app restart.
-        userDataPath: app.getPath('userData')
-      }),
-    onDaemonError: (error) => {
-      console.error('[daemon] Failed to start daemon PTY provider, falling back to local:', error)
-    },
-    onAgentHookServerError: (error) => {
-      // Why: Claude/Codex/Gemini/OpenCode/Cursor hook callbacks are sidebar
-      // enrichment only. Orca must still boot if the loopback receiver fails.
-      console.error('[agent-hooks] Failed to start local hook server:', error)
-    }
-  })
+  if (!isServeMode) {
+    await startFirstWindowStartupServices({
+      // Why: the persistent-terminal daemon is desktop-only. Headless
+      // `orca serve` registers its PTY runtime below and must not spawn the
+      // desktop daemon or hook loopback listener.
+      startDaemonPtyProvider: () => initDaemonPtyProvider(),
+      // Why: PTY spawn env reads ORCA_AGENT_HOOK_* from the live server state,
+      // so the hook server must start before restored terminals can mount.
+      startAgentHookServer: () =>
+        agentHookServer.start({
+          env: app.isPackaged ? 'production' : 'development',
+          // Why: hooks source this endpoint file at invocation time, so old PTY
+          // env still reaches the current Orca process after an app restart.
+          userDataPath: app.getPath('userData')
+        }),
+      onDaemonError: (error) => {
+        console.error('[daemon] Failed to start daemon PTY provider, falling back to local:', error)
+      },
+      onAgentHookServerError: (error) => {
+        // Why: Claude/Codex/Gemini/OpenCode/Cursor hook callbacks are sidebar
+        // enrichment only. Orca must still boot if the loopback receiver fails.
+        console.error('[agent-hooks] Failed to start local hook server:', error)
+      }
+    })
+  }
+
+  if (serveOptions) {
+    registerHeadlessPtyRuntime(
+      runtime,
+      () => codexRuntimeHome!.prepareForCodexLaunch(),
+      () => store!.getSettings(),
+      () => claudeRuntimeAuth!.prepareForClaudeLaunch(),
+      store
+    )
+    // Why: headless servers have no renderer graph publisher. Publish an
+    // explicit empty graph so status clients see a ready server while
+    // renderer-only operations still fail at their own window boundary.
+    runtime.syncWindowGraph(0, { tabs: [], leaves: [] })
+    await runtimeRpc.start().catch((error) => {
+      console.error('[runtime] Failed to start headless RPC transport:', error)
+      throw error
+    })
+    installServeSignalHandlers()
+    await printServeReady(serveOptions)
+    return
+  }
 
   // Why: once the hook server is ready (or has already failed open), window
   // creation and runtime RPC startup are independent.
diff --git a/src/main/ipc/filesystem-import-ssh-ops.test.ts b/src/main/ipc/filesystem-import-ssh-ops.test.ts
index a67e6d8a787..376e867da43 100644
--- a/src/main/ipc/filesystem-import-ssh-ops.test.ts
+++ b/src/main/ipc/filesystem-import-ssh-ops.test.ts
@@ -179,7 +179,16 @@ describe('fs:importExternalPaths — SSH operations', () => {
       connectionId: connId
     })
     expect(results[0]).toMatchObject({ status: 'imported', kind: 'directory' })
-    expect(mkdirSftpMock).toHaveBeenCalledWith(mockSftp, `${destDir}/assets`)
+    expect(mkdirSftpMock).toHaveBeenCalledWith(mockSftp, `${destDir}/assets`, {
+      allowExisting: false
+    })
+    expect(uploadDirMock).toHaveBeenCalledWith(
+      mockSftp,
+      path.resolve('/tmp/dropped/assets'),
+      `${destDir}/assets`,
+      path.resolve('/tmp/dropped/assets'),
+      { exclusive: true }
+    )
   })
 
   it('reports per-item failure when deconfliction throws', async () => {
diff --git a/src/main/ipc/filesystem-import-ssh.test.ts b/src/main/ipc/filesystem-import-ssh.test.ts
index 210fbfe1105..e348f2f2979 100644
--- a/src/main/ipc/filesystem-import-ssh.test.ts
+++ b/src/main/ipc/filesystem-import-ssh.test.ts
@@ -1,4 +1,6 @@
 import path from 'path'
+import { constants } from 'fs'
+import { Readable, Writable } from 'stream'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const handlers = new Map<string, (_event: unknown, args: unknown) => Promise<unknown>>()
@@ -8,7 +10,9 @@ const {
   mkdirMock,
   realpathMock,
   copyFileMock,
+  openMock,
   readdirMock,
+  unlinkMock,
   sftpExistsMock,
   uploadFileMock,
   uploadDirMock,
@@ -20,7 +24,9 @@ const {
   mkdirMock: vi.fn(),
   realpathMock: vi.fn(),
   copyFileMock: vi.fn(),
+  openMock: vi.fn(),
   readdirMock: vi.fn(),
+  unlinkMock: vi.fn(),
   sftpExistsMock: vi.fn(),
   uploadFileMock: vi.fn(),
   uploadDirMock: vi.fn(),
@@ -36,7 +42,10 @@ vi.mock('fs/promises', () => ({
   writeFile: vi.fn(),
   realpath: realpathMock,
   copyFile: copyFileMock,
-  readdir: readdirMock
+  open: openMock,
+  readdir: readdirMock,
+  unlink: unlinkMock,
+  rm: vi.fn()
 }))
 vi.mock('../ssh/sftp-upload', () => ({
   sftpPathExists: sftpExistsMock,
@@ -92,7 +101,9 @@ describe('fs:importExternalPaths — SSH routing & connection', () => {
       mkdirMock,
       realpathMock,
       copyFileMock,
+      openMock,
       readdirMock,
+      unlinkMock,
       sftpExistsMock,
       uploadFileMock,
       uploadDirMock,
@@ -105,6 +116,30 @@ describe('fs:importExternalPaths — SSH routing & connection', () => {
     })
     realpathMock.mockImplementation(async (p: string) => p)
     lstatMock.mockRejectedValue(enoent())
+    openMock.mockImplementation(async (_p: string, flags: unknown) => {
+      if (flags === 'wx') {
+        return {
+          createWriteStream: () =>
+            new Writable({
+              write(_chunk, _encoding, callback) {
+                callback()
+              }
+            }),
+          close: vi.fn().mockResolvedValue(undefined)
+        }
+      }
+      return {
+        stat: vi.fn().mockResolvedValue({
+          size: 12,
+          ino: 1,
+          dev: 1,
+          isFile: () => true
+        }),
+        createReadStream: () => Readable.from([Buffer.from('file-content')]),
+        close: vi.fn().mockResolvedValue(undefined)
+      }
+    })
+    unlinkMock.mockResolvedValue(undefined)
     sftpExistsMock.mockResolvedValue(false)
     uploadFileMock.mockResolvedValue(undefined)
     uploadDirMock.mockResolvedValue(undefined)
@@ -121,7 +156,12 @@ describe('fs:importExternalPaths — SSH routing & connection', () => {
       connectionId: connId
     })
     expect(results[0]).toMatchObject({ status: 'imported', kind: 'file' })
-    expect(uploadFileMock).toHaveBeenCalled()
+    expect(uploadFileMock).toHaveBeenCalledWith(
+      mockSftp,
+      path.resolve('/tmp/dropped/file.txt'),
+      `${destDir}/file.txt`,
+      { exclusive: true }
+    )
     expect(copyFileMock).not.toHaveBeenCalled()
   })
 
@@ -132,7 +172,10 @@ describe('fs:importExternalPaths — SSH routing & connection', () => {
       destDir: path.resolve('/workspace/repo/src')
     })
     expect(results[0]).toMatchObject({ status: 'imported' })
-    expect(copyFileMock).toHaveBeenCalled()
+    expect(openMock).toHaveBeenCalledWith(
+      path.resolve('/tmp/dropped/file.txt'),
+      constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)
+    )
   })
 
   it('returns empty results without opening SFTP', async () => {
diff --git a/src/main/ipc/filesystem-import-ssh.ts b/src/main/ipc/filesystem-import-ssh.ts
index 8554b466547..c29dbd6ee04 100644
--- a/src/main/ipc/filesystem-import-ssh.ts
+++ b/src/main/ipc/filesystem-import-ssh.ts
@@ -1,4 +1,4 @@
-import { lstat, readdir } from 'fs/promises'
+import { lstat, readdir, realpath } from 'fs/promises'
 import { basename, join, posix, resolve } from 'path'
 import type { SFTPWrapper } from 'ssh2'
 import { authorizeExternalPath, isENOENT } from './filesystem-auth'
@@ -124,10 +124,12 @@ async function importOneSourceSsh(
     const renamed = finalName !== originalName
 
     if (isDir) {
-      await mkdirSftp(sftp, destPath)
-      await uploadDirectory(sftp, resolvedSource, destPath)
+      await mkdirSftp(sftp, destPath, { allowExisting: false })
+      await uploadDirectory(sftp, resolvedSource, destPath, await realpath(resolvedSource), {
+        exclusive: true
+      })
     } else {
-      await uploadFile(sftp, resolvedSource, destPath)
+      await uploadFile(sftp, resolvedSource, destPath, { exclusive: true })
     }
 
     return {
diff --git a/src/main/ipc/filesystem-import.test.ts b/src/main/ipc/filesystem-import.test.ts
index a6dc5df44b1..318e2d120fc 100644
--- a/src/main/ipc/filesystem-import.test.ts
+++ b/src/main/ipc/filesystem-import.test.ts
@@ -1,17 +1,34 @@
+/* eslint-disable max-lines -- Why: import tests cover local copy, SSH routing,
+symlink safety, and runtime-upload staging against one shared IPC fixture. */
 import path from 'path'
+import { constants } from 'fs'
+import { Readable, Writable } from 'stream'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const handlers = new Map<string, (_event: unknown, args: unknown) => Promise<unknown>>()
-const { handleMock, lstatMock, mkdirMock, realpathMock, copyFileMock, readdirMock } = vi.hoisted(
-  () => ({
-    handleMock: vi.fn(),
-    lstatMock: vi.fn(),
-    mkdirMock: vi.fn(),
-    realpathMock: vi.fn(),
-    copyFileMock: vi.fn(),
-    readdirMock: vi.fn()
-  })
-)
+const {
+  handleMock,
+  lstatMock,
+  mkdirMock,
+  realpathMock,
+  copyFileMock,
+  openMock,
+  readFileMock,
+  readdirMock,
+  rmMock,
+  unlinkMock
+} = vi.hoisted(() => ({
+  handleMock: vi.fn(),
+  lstatMock: vi.fn(),
+  mkdirMock: vi.fn(),
+  realpathMock: vi.fn(),
+  copyFileMock: vi.fn(),
+  openMock: vi.fn(),
+  readFileMock: vi.fn(),
+  readdirMock: vi.fn(),
+  rmMock: vi.fn(),
+  unlinkMock: vi.fn()
+}))
 
 vi.mock('electron', () => ({
   ipcMain: { handle: handleMock }
@@ -20,11 +37,15 @@ vi.mock('electron', () => ({
 vi.mock('fs/promises', () => ({
   lstat: lstatMock,
   mkdir: mkdirMock,
+  open: openMock,
   rename: vi.fn(),
   writeFile: vi.fn(),
   realpath: realpathMock,
   copyFile: copyFileMock,
-  readdir: readdirMock
+  readFile: readFileMock,
+  readdir: readdirMock,
+  rm: rmMock,
+  unlink: unlinkMock
 }))
 
 import { registerFilesystemMutationHandlers } from './filesystem-mutations'
@@ -50,7 +71,14 @@ describe('fs:importExternalPaths', () => {
     const resolvedPath = path.resolve(filePath)
     lstatMock.mockImplementation(async (p: string) => {
       if (p === resolvedPath) {
-        return { isFile: () => true, isDirectory: () => false, isSymbolicLink: () => false }
+        return {
+          size: 12,
+          ino: 1,
+          dev: 1,
+          isFile: () => true,
+          isDirectory: () => false,
+          isSymbolicLink: () => false
+        }
       }
       throw enoent()
     })
@@ -62,6 +90,17 @@ describe('fs:importExternalPaths', () => {
       if (p === resolvedDir) {
         return { isFile: () => false, isDirectory: () => true, isSymbolicLink: () => false }
       }
+      const entry = entries.find((e) => path.join(resolvedDir, e.name) === p)
+      if (entry) {
+        return {
+          size: entry.isDir ? 0 : 12,
+          ino: entry.isDir ? 2 : 3,
+          dev: 1,
+          isFile: () => !entry.isDir,
+          isDirectory: () => entry.isDir,
+          isSymbolicLink: () => false
+        }
+      }
       throw enoent()
     })
     readdirMock.mockImplementation(async () => {
@@ -84,6 +123,35 @@ describe('fs:importExternalPaths', () => {
     })
   }
 
+  function mockLocalCopyOpenSuccess(content = Buffer.from('file-content')): void {
+    openMock.mockImplementation(async (_p: string, flags: unknown) => {
+      if (flags === 'wx') {
+        const written: Buffer[] = []
+        return {
+          createWriteStream: () =>
+            new Writable({
+              write(chunk, _encoding, callback) {
+                written.push(Buffer.from(chunk))
+                callback()
+              }
+            }),
+          close: vi.fn().mockResolvedValue(undefined),
+          written
+        }
+      }
+      return {
+        stat: vi.fn().mockResolvedValue({
+          size: content.byteLength,
+          ino: 1,
+          dev: 1,
+          isFile: () => true
+        }),
+        createReadStream: () => Readable.from([content]),
+        close: vi.fn().mockResolvedValue(undefined)
+      }
+    })
+  }
+
   beforeEach(() => {
     handlers.clear()
     handleMock.mockReset()
@@ -91,7 +159,11 @@ describe('fs:importExternalPaths', () => {
     mkdirMock.mockReset()
     realpathMock.mockReset()
     copyFileMock.mockReset()
+    openMock.mockReset()
+    readFileMock.mockReset()
     readdirMock.mockReset()
+    rmMock.mockReset()
+    unlinkMock.mockReset()
 
     handleMock.mockImplementation((channel: string, handler: never) => {
       handlers.set(channel, handler)
@@ -101,7 +173,11 @@ describe('fs:importExternalPaths', () => {
     lstatMock.mockRejectedValue(enoent())
     mkdirMock.mockResolvedValue(undefined)
     copyFileMock.mockResolvedValue(undefined)
+    mockLocalCopyOpenSuccess()
+    readFileMock.mockResolvedValue(Buffer.from('file-content'))
     readdirMock.mockResolvedValue([])
+    rmMock.mockResolvedValue(undefined)
+    unlinkMock.mockResolvedValue(undefined)
 
     registerFilesystemMutationHandlers(store as never)
   })
@@ -122,10 +198,44 @@ describe('fs:importExternalPaths', () => {
       renamed: false,
       destPath: path.join(destDir, 'logo.png')
     })
-    expect(copyFileMock).toHaveBeenCalledWith(
+    expect(openMock).toHaveBeenCalledWith(
       path.resolve(sourcePath),
-      path.join(destDir, 'logo.png')
+      constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)
     )
+    expect(openMock).toHaveBeenCalledWith(path.join(destDir, 'logo.png'), 'wx')
+    expect(copyFileMock).not.toHaveBeenCalled()
+  })
+
+  it('fails local import instead of clobbering when the chosen destination appears late', async () => {
+    const sourcePath = '/tmp/dropped/logo.png'
+    mockSourceFile(sourcePath)
+    openMock.mockImplementation(async (_p: string, flags: unknown) => {
+      if (flags === 'wx') {
+        throw Object.assign(new Error('EEXIST'), { code: 'EEXIST' })
+      }
+      return {
+        stat: vi.fn().mockResolvedValue({
+          size: 12,
+          ino: 1,
+          dev: 1,
+          isFile: () => true
+        }),
+        createReadStream: () => Readable.from([Buffer.from('file-content')]),
+        close: vi.fn().mockResolvedValue(undefined)
+      }
+    })
+
+    const result = (await handlers.get('fs:importExternalPaths')!(null, {
+      sourcePaths: [sourcePath],
+      destDir
+    })) as { results: { status: string; reason?: string }[] }
+
+    expect(result.results[0]).toMatchObject({ status: 'failed', reason: 'EEXIST' })
+    expect(openMock).toHaveBeenCalledWith(
+      path.resolve(sourcePath),
+      constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)
+    )
+    expect(openMock).toHaveBeenCalledWith(path.join(destDir, 'logo.png'), 'wx')
   })
 
   it('imports multiple files in one batch', async () => {
@@ -276,6 +386,44 @@ describe('fs:importExternalPaths', () => {
     expect(copyFileMock).not.toHaveBeenCalled()
   })
 
+  it('fails and removes output if a local directory entry becomes a symlink after pre-scan', async () => {
+    const sourcePath = '/tmp/dropped/mixeddir'
+    const resolvedSource = path.resolve(sourcePath)
+    const childPath = path.join(resolvedSource, 'normal.txt')
+    lstatMock.mockImplementation(async (p: string) => {
+      if (p === resolvedSource) {
+        return { isFile: () => false, isDirectory: () => true, isSymbolicLink: () => false }
+      }
+      if (p === childPath) {
+        return { isFile: () => false, isDirectory: () => false, isSymbolicLink: () => true }
+      }
+      throw enoent()
+    })
+    readdirMock.mockResolvedValue([
+      {
+        name: 'normal.txt',
+        isDirectory: () => false,
+        isSymbolicLink: () => false,
+        isFile: () => true
+      }
+    ])
+
+    const result = (await handlers.get('fs:importExternalPaths')!(null, {
+      sourcePaths: [sourcePath],
+      destDir
+    })) as { results: { status: string; reason?: string }[] }
+
+    expect(result.results[0]).toMatchObject({
+      status: 'failed',
+      reason: "Symlink not allowed in 'normal.txt'"
+    })
+    expect(openMock).not.toHaveBeenCalledWith(childPath, expect.anything())
+    expect(rmMock).toHaveBeenCalledWith(path.join(destDir, 'mixeddir'), {
+      recursive: true,
+      force: true
+    })
+  })
+
   it('rejects unauthorized destinations', async () => {
     const sourcePath = '/tmp/dropped/file.txt'
     mockSourceFile(sourcePath)
@@ -328,4 +476,118 @@ describe('fs:importExternalPaths', () => {
       reason: 'missing'
     })
   })
+
+  it('stages external files for runtime upload without copying into the local worktree', async () => {
+    const sourcePath = '/tmp/dropped/logo.png'
+    const resolvedPath = path.resolve(sourcePath)
+    lstatMock.mockImplementation(async (p: string) => {
+      if (p === resolvedPath) {
+        return {
+          size: 4,
+          ino: 1,
+          dev: 1,
+          isFile: () => true,
+          isDirectory: () => false,
+          isSymbolicLink: () => false
+        }
+      }
+      throw enoent()
+    })
+    const closeMock = vi.fn().mockResolvedValue(undefined)
+    const readFileHandleMock = vi.fn().mockResolvedValue(Buffer.from('png'))
+    openMock.mockResolvedValue({
+      stat: vi.fn().mockResolvedValue({
+        size: 4,
+        ino: 1,
+        dev: 1,
+        isFile: () => true
+      }),
+      readFile: readFileHandleMock,
+      close: closeMock
+    })
+
+    const result = (await handlers.get('fs:stageExternalPathsForRuntimeUpload')!(null, {
+      sourcePaths: [sourcePath]
+    })) as { sources: unknown[] }
+
+    expect(result.sources).toEqual([
+      {
+        sourcePath,
+        status: 'staged',
+        name: 'logo.png',
+        kind: 'file',
+        entries: [{ relativePath: '', kind: 'file', contentBase64: 'cG5n' }]
+      }
+    ])
+    expect(copyFileMock).not.toHaveBeenCalled()
+    expect(readFileHandleMock).toHaveBeenCalled()
+    expect(closeMock).toHaveBeenCalled()
+  })
+
+  it('fails runtime upload staging when a file changes between lstat and open', async () => {
+    const sourcePath = '/tmp/dropped/logo.png'
+    const resolvedPath = path.resolve(sourcePath)
+    lstatMock.mockImplementation(async (p: string) => {
+      if (p === resolvedPath) {
+        return {
+          size: 4,
+          ino: 1,
+          dev: 1,
+          isFile: () => true,
+          isDirectory: () => false,
+          isSymbolicLink: () => false
+        }
+      }
+      throw enoent()
+    })
+    const readFileHandleMock = vi.fn().mockResolvedValue(Buffer.from('png'))
+    openMock.mockResolvedValue({
+      stat: vi.fn().mockResolvedValue({
+        size: 4,
+        ino: 2,
+        dev: 1,
+        isFile: () => true
+      }),
+      readFile: readFileHandleMock,
+      close: vi.fn().mockResolvedValue(undefined)
+    })
+
+    const result = (await handlers.get('fs:stageExternalPathsForRuntimeUpload')!(null, {
+      sourcePaths: [sourcePath]
+    })) as { sources: { status: string; reason?: string }[] }
+
+    expect(result.sources[0]).toMatchObject({
+      status: 'failed',
+      reason: "File changed during upload staging: ''"
+    })
+    expect(readFileHandleMock).not.toHaveBeenCalled()
+  })
+
+  it('fails runtime upload staging when a checked directory resolves outside the upload root', async () => {
+    const sourcePath = '/tmp/dropped/assets'
+    const resolvedPath = path.resolve(sourcePath)
+    lstatMock.mockImplementation(async (p: string) => {
+      if (p === resolvedPath) {
+        return {
+          isFile: () => false,
+          isDirectory: () => true,
+          isSymbolicLink: () => false
+        }
+      }
+      throw enoent()
+    })
+    readdirMock.mockResolvedValue([])
+    realpathMock
+      .mockResolvedValueOnce(resolvedPath)
+      .mockResolvedValueOnce(path.resolve('/private/assets'))
+
+    const result = (await handlers.get('fs:stageExternalPathsForRuntimeUpload')!(null, {
+      sourcePaths: [sourcePath]
+    })) as { sources: { status: string; reason?: string }[] }
+
+    expect(result.sources[0]).toMatchObject({
+      status: 'failed',
+      reason: "Path escaped upload root during staging: ''"
+    })
+  })
 })
diff --git a/src/main/ipc/filesystem-mutations.test.ts b/src/main/ipc/filesystem-mutations.test.ts
index 3865fc1ef37..13c4a648acc 100644
--- a/src/main/ipc/filesystem-mutations.test.ts
+++ b/src/main/ipc/filesystem-mutations.test.ts
@@ -2,16 +2,16 @@ import path from 'path'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const handlers = new Map<string, (_event: unknown, args: unknown) => Promise<unknown>>()
-const { handleMock, lstatMock, mkdirMock, renameMock, writeFileMock, realpathMock } = vi.hoisted(
-  () => ({
+const { handleMock, copyFileMock, lstatMock, mkdirMock, renameMock, writeFileMock, realpathMock } =
+  vi.hoisted(() => ({
     handleMock: vi.fn(),
+    copyFileMock: vi.fn(),
     lstatMock: vi.fn(),
     mkdirMock: vi.fn(),
     renameMock: vi.fn(),
     writeFileMock: vi.fn(),
     realpathMock: vi.fn()
-  })
-)
+  }))
 
 vi.mock('electron', () => ({
   ipcMain: { handle: handleMock }
@@ -23,11 +23,15 @@ vi.mock('fs/promises', () => ({
   rename: renameMock,
   writeFile: writeFileMock,
   realpath: realpathMock,
-  copyFile: vi.fn(),
+  copyFile: copyFileMock,
   readdir: vi.fn()
 }))
 
 import { registerFilesystemMutationHandlers } from './filesystem-mutations'
+import {
+  registerSshFilesystemProvider,
+  unregisterSshFilesystemProvider
+} from '../providers/ssh-filesystem-dispatch'
 
 // Why: paths are resolved via path.resolve() in production code, so test
 // data must use resolved paths to avoid Unix-vs-Windows mismatches.
@@ -58,6 +62,7 @@ describe('registerFilesystemMutationHandlers', () => {
   beforeEach(() => {
     handlers.clear()
     handleMock.mockReset()
+    copyFileMock.mockReset()
     lstatMock.mockReset()
     mkdirMock.mockReset()
     renameMock.mockReset()
@@ -74,6 +79,7 @@ describe('registerFilesystemMutationHandlers', () => {
     mkdirMock.mockResolvedValue(undefined)
     writeFileMock.mockResolvedValue(undefined)
     renameMock.mockResolvedValue(undefined)
+    copyFileMock.mockResolvedValue(undefined)
 
     registerFilesystemMutationHandlers(store as never)
   })
@@ -210,6 +216,36 @@ describe('registerFilesystemMutationHandlers', () => {
     expect(renameMock).toHaveBeenCalledWith(oldPath, newPath)
   })
 
+  // ── fs:copy ────────────────────────────────────────────────────
+
+  it('copies a file without overwriting an existing destination', async () => {
+    const sourcePath = path.resolve('/workspace/repo/source.ts')
+    const destinationPath = path.resolve('/workspace/repo/source copy.ts')
+
+    await handlers.get('fs:copy')!(null, { sourcePath, destinationPath })
+
+    expect(mkdirMock).toHaveBeenCalledWith(path.resolve('/workspace/repo'), { recursive: true })
+    expect(copyFileMock).toHaveBeenCalledWith(sourcePath, destinationPath, expect.any(Number))
+  })
+
+  it('routes copy through the SSH filesystem provider when a connection is present', async () => {
+    const copy = vi.fn().mockResolvedValue(undefined)
+    registerSshFilesystemProvider('ssh-1', { copy } as never)
+
+    try {
+      await handlers.get('fs:copy')!(null, {
+        sourcePath: '/home/me/repo/source.ts',
+        destinationPath: '/home/me/repo/source copy.ts',
+        connectionId: 'ssh-1'
+      })
+    } finally {
+      unregisterSshFilesystemProvider('ssh-1')
+    }
+
+    expect(copy).toHaveBeenCalledWith('/home/me/repo/source.ts', '/home/me/repo/source copy.ts')
+    expect(copyFileMock).not.toHaveBeenCalled()
+  })
+
   // ── Edge cases ─────────────────────────────────────────────────
 
   it('propagates non-ENOENT lstat errors in assertNotExists', async () => {
diff --git a/src/main/ipc/filesystem-mutations.ts b/src/main/ipc/filesystem-mutations.ts
index b9bcd91bedd..528baa1737c 100644
--- a/src/main/ipc/filesystem-mutations.ts
+++ b/src/main/ipc/filesystem-mutations.ts
@@ -1,6 +1,21 @@
+/* eslint-disable max-lines -- Why: filesystem mutation IPC handlers stay centralized so
+authorization, SSH routing, and external import behavior remain audited together. */
 import { ipcMain } from 'electron'
-import { copyFile, lstat, mkdir, readdir, rename, writeFile } from 'fs/promises'
-import { basename, dirname, join, resolve } from 'path'
+import { constants } from 'fs'
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  unlink,
+  writeFile
+} from 'fs/promises'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'path'
+import { pipeline } from 'stream/promises'
 import type { Store } from '../persistence'
 import { authorizeExternalPath, resolveAuthorizedPath, isENOENT } from './filesystem-auth'
 import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
@@ -117,14 +132,42 @@ export function registerFilesystemMutationHandlers(store: Store): void {
     }
   )
 
+  ipcMain.handle(
+    'fs:copy',
+    async (
+      _event,
+      args: { sourcePath: string; destinationPath: string; connectionId?: string }
+    ): Promise<void> => {
+      if (args.connectionId) {
+        const provider = getSshFilesystemProvider(args.connectionId)
+        if (!provider) {
+          throw new Error(`No filesystem provider for connection "${args.connectionId}"`)
+        }
+        return provider.copy(args.sourcePath, args.destinationPath)
+      }
+      const sourcePath = await resolveAuthorizedPath(args.sourcePath, store, {
+        preserveSymlink: true
+      })
+      const destinationPath = await resolveAuthorizedPath(args.destinationPath, store, {
+        preserveSymlink: true
+      })
+      await mkdir(dirname(destinationPath), { recursive: true })
+      // Why: duplicate/copy callers deconflict before copying. COPYFILE_EXCL
+      // keeps a late race from silently overwriting an existing file.
+      await copyFile(sourcePath, destinationPath, constants.COPYFILE_EXCL)
+    }
+  )
+
   ipcMain.handle(
     'fs:importExternalPaths',
     async (
       _event,
-      args: { sourcePaths: string[]; destDir: string; connectionId?: string }
+      args: { sourcePaths: string[]; destDir: string; connectionId?: string; ensureDir?: boolean }
     ): Promise<{ results: ImportItemResult[] }> => {
       if (args.connectionId) {
-        return importExternalPathsSsh(args.sourcePaths, args.destDir, args.connectionId)
+        return importExternalPathsSsh(args.sourcePaths, args.destDir, args.connectionId, {
+          ensureDir: args.ensureDir
+        })
       }
 
       // Why: destDir must be authorized before any copy work begins. If the
@@ -148,6 +191,20 @@ export function registerFilesystemMutationHandlers(store: Store): void {
     }
   )
 
+  ipcMain.handle(
+    'fs:stageExternalPathsForRuntimeUpload',
+    async (
+      _event,
+      args: { sourcePaths: string[] }
+    ): Promise<{ sources: StagedExternalImportSource[] }> => {
+      const sources: StagedExternalImportSource[] = []
+      for (const sourcePath of args.sourcePaths) {
+        sources.push(await stageOneSourceForRuntimeUpload(sourcePath))
+      }
+      return { sources }
+    }
+  )
+
   // Why: terminal drag-and-drop resolver. Local worktrees pass paths through
   // unchanged (reference-in-place; preserves zero-latency drop). SSH worktrees
   // upload each path into `${worktreePath}/.orca/drops/` and return remote
@@ -217,6 +274,32 @@ export type ImportItemResult =
       reason: string
     }
 
+export type StagedExternalImportSource =
+  | {
+      sourcePath: string
+      status: 'staged'
+      name: string
+      kind: 'file' | 'directory'
+      entries: StagedExternalImportEntry[]
+    }
+  | {
+      sourcePath: string
+      status: 'skipped'
+      reason: ImportSkipReason
+    }
+  | {
+      sourcePath: string
+      status: 'failed'
+      reason: string
+    }
+
+export type StagedExternalImportEntry =
+  | { relativePath: string; kind: 'directory' }
+  | { relativePath: string; kind: 'file'; contentBase64: string }
+
+const REMOTE_IMPORT_MAX_FILE_BYTES = 25 * 1024 * 1024
+const REMOTE_IMPORT_MAX_TOTAL_BYTES = 100 * 1024 * 1024
+
 // ─── External Import Implementation ─────────────────────────────────
 
 /**
@@ -288,8 +371,13 @@ async function importOneSource(
   const renamed = finalName !== originalName
 
   try {
-    await (isDir ? recursiveCopyDir(resolvedSource, destPath) : copyFile(resolvedSource, destPath))
+    await (isDir
+      ? recursiveCopyDir(resolvedSource, destPath)
+      : copyLocalFileNoFollow(resolvedSource, destPath))
   } catch (error) {
+    if (isDir) {
+      await rm(destPath, { recursive: true, force: true }).catch(() => {})
+    }
     return {
       sourcePath,
       status: 'failed',
@@ -306,6 +394,194 @@ async function importOneSource(
   }
 }
 
+async function stageOneSourceForRuntimeUpload(
+  sourcePath: string
+): Promise<StagedExternalImportSource> {
+  const resolvedSource = resolve(sourcePath)
+
+  // Why: runtime uploads read client-local paths in the client main process;
+  // authorize before lstat/readFile just like local copy imports.
+  authorizeExternalPath(resolvedSource)
+
+  let sourceStat: Awaited<ReturnType<typeof lstat>>
+  try {
+    sourceStat = await lstat(resolvedSource)
+  } catch (error) {
+    if (isENOENT(error)) {
+      return { sourcePath, status: 'skipped', reason: 'missing' }
+    }
+    if (
+      error instanceof Error &&
+      'code' in error &&
+      ((error as NodeJS.ErrnoException).code === 'EACCES' ||
+        (error as NodeJS.ErrnoException).code === 'EPERM')
+    ) {
+      return { sourcePath, status: 'skipped', reason: 'permission-denied' }
+    }
+    return {
+      sourcePath,
+      status: 'failed',
+      reason: error instanceof Error ? error.message : String(error)
+    }
+  }
+
+  if (sourceStat.isSymbolicLink()) {
+    return { sourcePath, status: 'skipped', reason: 'symlink' }
+  }
+  if (!sourceStat.isFile() && !sourceStat.isDirectory()) {
+    return { sourcePath, status: 'skipped', reason: 'unsupported' }
+  }
+  if (sourceStat.isDirectory() && (await preScanForSymlinks(resolvedSource))) {
+    return { sourcePath, status: 'skipped', reason: 'symlink' }
+  }
+
+  try {
+    const entries = sourceStat.isDirectory()
+      ? await stageDirectoryEntries(resolvedSource)
+      : [await stageFileEntry(resolvedSource, '')]
+    return {
+      sourcePath,
+      status: 'staged',
+      name: basename(resolvedSource),
+      kind: sourceStat.isDirectory() ? 'directory' : 'file',
+      entries
+    }
+  } catch (error) {
+    return {
+      sourcePath,
+      status: 'failed',
+      reason: error instanceof Error ? error.message : String(error)
+    }
+  }
+}
+
+async function stageDirectoryEntries(rootPath: string): Promise<StagedExternalImportEntry[]> {
+  const entries: StagedExternalImportEntry[] = [{ relativePath: '', kind: 'directory' }]
+  let totalBytes = 0
+  const rootRealPath = await realpath(rootPath)
+
+  async function visit(dirPath: string): Promise<void> {
+    const dirStat = await lstat(dirPath)
+    if (dirStat.isSymbolicLink()) {
+      throw new Error(
+        `Symlink not allowed in '${normalizeRelativeUploadPath(relative(rootPath, dirPath))}'`
+      )
+    }
+    if (!dirStat.isDirectory()) {
+      throw new Error(
+        `Unsupported file type in '${normalizeRelativeUploadPath(relative(rootPath, dirPath))}'`
+      )
+    }
+    await assertRealPathInsideRoot(
+      rootRealPath,
+      dirPath,
+      normalizeRelativeUploadPath(relative(rootPath, dirPath))
+    )
+    const dirEntries = await readdir(dirPath, { withFileTypes: true })
+    for (const entry of dirEntries) {
+      const childPath = join(dirPath, entry.name)
+      const childRelativePath = normalizeRelativeUploadPath(relative(rootPath, childPath))
+      if (entry.isDirectory()) {
+        const childStat = await lstat(childPath)
+        if (childStat.isSymbolicLink()) {
+          throw new Error(`Symlink not allowed in '${childRelativePath}'`)
+        }
+        if (!childStat.isDirectory()) {
+          throw new Error(`Unsupported file type in '${childRelativePath}'`)
+        }
+        entries.push({ relativePath: childRelativePath, kind: 'directory' })
+        await visit(childPath)
+        continue
+      }
+      if (!entry.isFile()) {
+        throw new Error(`Unsupported file type in '${childRelativePath}'`)
+      }
+      const statResult = await lstat(childPath)
+      totalBytes += statResult.size
+      assertRemoteUploadBudget(childRelativePath, statResult.size, totalBytes)
+      entries.push(await stageFileEntry(childPath, childRelativePath, rootRealPath))
+    }
+  }
+
+  await visit(rootPath)
+  return entries
+}
+
+async function stageFileEntry(
+  filePath: string,
+  relativePath: string,
+  rootRealPath?: string
+): Promise<StagedExternalImportEntry> {
+  const statResult = await lstat(filePath)
+  const displayPath = normalizeRelativeUploadPath(relativePath)
+  if (statResult.isSymbolicLink()) {
+    throw new Error(`Symlink not allowed in '${displayPath}'`)
+  }
+  if (!statResult.isFile()) {
+    throw new Error(`Unsupported file type in '${displayPath}'`)
+  }
+  if (rootRealPath) {
+    await assertRealPathInsideRoot(rootRealPath, filePath, displayPath)
+  }
+  assertRemoteUploadBudget(relativePath, statResult.size, statResult.size)
+  const fileHandle = await open(filePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+  try {
+    const openedStat = await fileHandle.stat()
+    if (!openedStat.isFile()) {
+      throw new Error(`Unsupported file type in '${displayPath}'`)
+    }
+    if (
+      openedStat.size !== statResult.size ||
+      (statResult.ino !== 0 && openedStat.ino !== 0 && openedStat.ino !== statResult.ino) ||
+      (statResult.dev !== 0 && openedStat.dev !== 0 && openedStat.dev !== statResult.dev)
+    ) {
+      throw new Error(`File changed during upload staging: '${displayPath}'`)
+    }
+    assertRemoteUploadBudget(relativePath, openedStat.size, openedStat.size)
+    const buffer = await fileHandle.readFile()
+    const afterReadStat = await fileHandle.stat()
+    if (afterReadStat.size !== openedStat.size) {
+      throw new Error(`File changed during upload staging: '${displayPath}'`)
+    }
+    return {
+      relativePath: displayPath,
+      kind: 'file',
+      contentBase64: buffer.toString('base64')
+    }
+  } finally {
+    await fileHandle.close()
+  }
+}
+
+async function assertRealPathInsideRoot(
+  rootRealPath: string,
+  candidatePath: string,
+  displayPath: string
+): Promise<void> {
+  const candidateRealPath = await realpath(candidatePath)
+  const relativeToRoot = relative(rootRealPath, candidateRealPath)
+  if (relativeToRoot !== '' && (relativeToRoot.startsWith('..') || isAbsolute(relativeToRoot))) {
+    throw new Error(`Path escaped upload root during staging: '${displayPath}'`)
+  }
+}
+
+function assertRemoteUploadBudget(
+  relativePath: string,
+  fileBytes: number,
+  totalBytes: number
+): void {
+  if (fileBytes > REMOTE_IMPORT_MAX_FILE_BYTES) {
+    throw new Error(`'${relativePath}' is too large for remote import`)
+  }
+  if (totalBytes > REMOTE_IMPORT_MAX_TOTAL_BYTES) {
+    throw new Error('Remote import is too large')
+  }
+}
+
+function normalizeRelativeUploadPath(path: string): string {
+  return path.replace(/[\\/]+/g, '/').replace(/^\/+/, '')
+}
+
 /**
  * Pre-scan a directory tree for symlinks. Returns true if any symlink
  * is found anywhere in the subtree.
@@ -332,12 +608,72 @@ async function preScanForSymlinks(dirPath: string): Promise<boolean> {
  * buffering entire files into memory.
  */
 async function recursiveCopyDir(srcDir: string, destDir: string): Promise<void> {
-  await mkdir(destDir, { recursive: true })
+  await mkdir(destDir, { recursive: false })
   const entries = await readdir(srcDir, { withFileTypes: true })
   for (const entry of entries) {
     const srcPath = join(srcDir, entry.name)
     const dstPath = join(destDir, entry.name)
-    await (entry.isDirectory() ? recursiveCopyDir(srcPath, dstPath) : copyFile(srcPath, dstPath))
+    const statResult = await lstat(srcPath)
+    if (statResult.isSymbolicLink()) {
+      throw new Error(`Symlink not allowed in '${entry.name}'`)
+    }
+    if (statResult.isDirectory()) {
+      await recursiveCopyDir(srcPath, dstPath)
+      continue
+    }
+    if (!statResult.isFile()) {
+      throw new Error(`Unsupported file type in '${entry.name}'`)
+    }
+    await copyLocalFileNoFollow(srcPath, dstPath, statResult)
+  }
+}
+
+async function copyLocalFileNoFollow(
+  srcPath: string,
+  dstPath: string,
+  statResult?: Awaited<ReturnType<typeof lstat>>
+): Promise<void> {
+  const beforeOpenStat = statResult ?? (await lstat(srcPath))
+  if (beforeOpenStat.isSymbolicLink()) {
+    throw new Error(`Symlink not allowed in '${basename(srcPath)}'`)
+  }
+  if (!beforeOpenStat.isFile()) {
+    throw new Error(`Unsupported file type in '${basename(srcPath)}'`)
+  }
+
+  let destinationCreated = false
+  const sourceHandle = await open(srcPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+  let destinationHandle: Awaited<ReturnType<typeof open>> | null = null
+  try {
+    const openedStat = await sourceHandle.stat()
+    if (
+      !openedStat.isFile() ||
+      (typeof beforeOpenStat.size === 'number' && openedStat.size !== beforeOpenStat.size) ||
+      (typeof beforeOpenStat.ino === 'number' &&
+        beforeOpenStat.ino !== 0 &&
+        openedStat.ino !== 0 &&
+        openedStat.ino !== beforeOpenStat.ino) ||
+      (typeof beforeOpenStat.dev === 'number' &&
+        beforeOpenStat.dev !== 0 &&
+        openedStat.dev !== 0 &&
+        openedStat.dev !== beforeOpenStat.dev)
+    ) {
+      throw new Error(`File changed during import: '${basename(srcPath)}'`)
+    }
+    // Why: copyFile(path, path) would follow a source symlink if the source is
+    // swapped after validation. Streaming from an O_NOFOLLOW handle keeps the
+    // authorized file identity pinned for the copy.
+    destinationHandle = await open(dstPath, 'wx')
+    destinationCreated = true
+    await pipeline(sourceHandle.createReadStream(), destinationHandle.createWriteStream())
+  } catch (error) {
+    if (destinationCreated) {
+      await unlink(dstPath).catch(() => {})
+    }
+    throw error
+  } finally {
+    await sourceHandle.close().catch(() => {})
+    await destinationHandle?.close().catch(() => {})
   }
 }
 
diff --git a/src/main/ipc/filesystem-watcher.test.ts b/src/main/ipc/filesystem-watcher.test.ts
index d1e3bafdebb..b6727bcf31f 100644
--- a/src/main/ipc/filesystem-watcher.test.ts
+++ b/src/main/ipc/filesystem-watcher.test.ts
@@ -28,16 +28,25 @@ vi.mock('../providers/ssh-filesystem-dispatch', () => ({
 }))
 
 import { closeAllWatchers, registerFilesystemWatcherHandlers } from './filesystem-watcher'
+import { stat } from 'fs/promises'
+import { subscribe as subscribeParcelWatcher } from '@parcel/watcher'
 
 type HandlerMap = Record<string, (_event: unknown, args: unknown) => Promise<unknown> | unknown>
 
 describe('registerFilesystemWatcherHandlers', () => {
   const handlers: HandlerMap = {}
+  const originalPlatform = process.platform
 
   beforeEach(() => {
     vi.useRealTimers()
     handleMock.mockReset()
     getSshFilesystemProviderMock.mockReset()
+    vi.mocked(stat).mockReset()
+    vi.mocked(subscribeParcelWatcher).mockReset()
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: originalPlatform
+    })
     for (const key of Object.keys(handlers)) {
       delete handlers[key]
     }
@@ -47,6 +56,28 @@ describe('registerFilesystemWatcherHandlers', () => {
     registerFilesystemWatcherHandlers()
   })
 
+  it('pins Parcel to the Windows backend for local Windows watches', async () => {
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'win32'
+    })
+    vi.mocked(stat).mockResolvedValue({ isDirectory: () => true } as never)
+    vi.mocked(subscribeParcelWatcher).mockResolvedValue({ unsubscribe: vi.fn() } as never)
+
+    await handlers['fs:watchWorktree'](
+      { sender: { isDestroyed: () => false, send: vi.fn(), once: vi.fn(), id: 1 } },
+      { worktreePath: 'C:\\repo' }
+    )
+
+    expect(subscribeParcelWatcher).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.any(Function),
+      expect.objectContaining({ backend: 'windows' })
+    )
+
+    await closeAllWatchers()
+  })
+
   it('quietly skips SSH worktree watches while the filesystem provider is unavailable', async () => {
     vi.useFakeTimers()
     const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
diff --git a/src/main/ipc/filesystem-watcher.ts b/src/main/ipc/filesystem-watcher.ts
index 7ffbf3ae778..d6064b4696d 100644
--- a/src/main/ipc/filesystem-watcher.ts
+++ b/src/main/ipc/filesystem-watcher.ts
@@ -239,6 +239,14 @@ async function createWatcher(rootKey: string, rootPath: string): Promise<Watched
     // therefore never unsubscribed), leaking a native file-watcher handle.
     let errorCleanedUp = false
 
+    const watcherOptions = {
+      ignore: WATCHER_IGNORE_DIRS,
+      // Why: Parcel checks Watchman before the native Windows backend by
+      // default, and Windows prints a shell-level "watchman not recognized"
+      // error for that probe. Pinning the backend keeps local watches quiet.
+      ...(process.platform === 'win32' ? { backend: 'windows' as const } : {})
+    }
+
     root.subscription = await watcher.subscribe(
       rootPath,
       (err, events) => {
@@ -280,9 +288,7 @@ async function createWatcher(rootKey: string, rootPath: string): Promise<Watched
         root.batch.events.push(...events)
         scheduleBatchFlush(rootKey, root)
       },
-      {
-        ignore: WATCHER_IGNORE_DIRS
-      }
+      watcherOptions
     )
 
     // Why: if the error callback already fired and cleaned up watchedRoots
diff --git a/src/main/ipc/mobile.test.ts b/src/main/ipc/mobile.test.ts
new file mode 100644
index 00000000000..5fb11e0b646
--- /dev/null
+++ b/src/main/ipc/mobile.test.ts
@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { handleMock } = vi.hoisted(() => ({
+  handleMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: { handle: handleMock }
+}))
+
+vi.mock('qrcode', () => ({
+  default: {
+    toDataURL: vi.fn().mockResolvedValue('data:image/png;base64,qr')
+  }
+}))
+
+import { registerMobileHandlers } from './mobile'
+
+describe('registerMobileHandlers', () => {
+  const handlers = new Map<string, (...args: unknown[]) => unknown>()
+
+  beforeEach(() => {
+    handlers.clear()
+    handleMock.mockReset()
+    handleMock.mockImplementation((channel: string, handler: (...args: unknown[]) => unknown) => {
+      handlers.set(channel, handler)
+    })
+  })
+
+  it('lists only paired mobile-scoped devices', () => {
+    const rpcServer = {
+      getDeviceRegistry: () => ({
+        listDevices: () => [
+          {
+            deviceId: 'mobile-1',
+            name: 'Phone',
+            scope: 'mobile',
+            pairedAt: 1,
+            lastSeenAt: 2
+          },
+          {
+            deviceId: 'runtime-1',
+            name: 'CLI',
+            scope: 'runtime',
+            pairedAt: 1,
+            lastSeenAt: 2
+          },
+          {
+            deviceId: 'pending-mobile',
+            name: 'Pending',
+            scope: 'mobile',
+            pairedAt: 1,
+            lastSeenAt: 0
+          }
+        ]
+      })
+    }
+
+    registerMobileHandlers(rpcServer as never)
+
+    expect(handlers.get('mobile:listDevices')?.()).toEqual({
+      devices: [
+        {
+          deviceId: 'mobile-1',
+          name: 'Phone',
+          pairedAt: 1,
+          lastSeenAt: 2
+        }
+      ]
+    })
+  })
+})
diff --git a/src/main/ipc/mobile.ts b/src/main/ipc/mobile.ts
index 9b1d8be3502..110f16d2699 100644
--- a/src/main/ipc/mobile.ts
+++ b/src/main/ipc/mobile.ts
@@ -2,7 +2,6 @@ import { ipcMain } from 'electron'
 import { networkInterfaces } from 'os'
 import QRCode from 'qrcode'
 import type { OrcaRuntimeRpcServer } from '../runtime/runtime-rpc'
-import { encodePairingOffer, PAIRING_OFFER_VERSION } from '../../shared/pairing'
 
 export type NetworkInterface = {
   name: string
@@ -46,12 +45,6 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
   ipcMain.handle(
     'mobile:getPairingQR',
     async (_event, args?: { address?: string; rotate?: boolean }) => {
-      const rawEndpoint = rpcServer.getWebSocketEndpoint()
-      const registry = rpcServer.getDeviceRegistry()
-      if (!rawEndpoint || !registry) {
-        return { available: false as const }
-      }
-
       // Why: allow the caller to specify which network interface address to
       // embed in the QR code. This supports overlay networks (Tailscale,
       // ZeroTier) where the default LAN IP isn't reachable from the phone.
@@ -59,7 +52,6 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
       if (!ip) {
         return { available: false as const }
       }
-      const endpoint = rawEndpoint.replace('0.0.0.0', ip)
 
       // Why: coalesce repeated QR regenerations onto a single never-scanned
       // pending token so the copy-button flow doesn't accumulate orphaned
@@ -68,24 +60,17 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
       // `rotate: true` (explicit "Regenerate" intent because the prior token
       // may have been exposed), we discard any pending token and mint a fresh
       // one so the new QR carries a different credential.
-      const name = `Mobile ${new Date().toLocaleDateString()}`
-      const device = args?.rotate
-        ? registry.rotatePendingDevice(name)
-        : registry.getOrCreatePendingDevice(name)
-
-      const publicKeyB64 = rpcServer.getE2EEPublicKey()
-      if (!publicKeyB64) {
+      const offer = rpcServer.createPairingOffer({
+        address: ip,
+        rotate: args?.rotate,
+        name: `Mobile ${new Date().toLocaleDateString()}`,
+        scope: 'mobile'
+      })
+      if (!offer.available) {
         return { available: false as const }
       }
 
-      const url = encodePairingOffer({
-        v: PAIRING_OFFER_VERSION,
-        endpoint,
-        deviceToken: device.token,
-        publicKeyB64
-      })
-
-      const qrDataUrl = await QRCode.toDataURL(url, {
+      const qrDataUrl = await QRCode.toDataURL(offer.pairingUrl, {
         errorCorrectionLevel: 'M',
         margin: 2,
         width: 256
@@ -94,9 +79,9 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
       return {
         available: true as const,
         qrDataUrl,
-        pairingUrl: url,
-        endpoint,
-        deviceId: device.deviceId
+        pairingUrl: offer.pairingUrl,
+        endpoint: offer.endpoint,
+        deviceId: offer.deviceId
       }
     }
   )
@@ -112,7 +97,7 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
     return {
       devices: registry
         .listDevices()
-        .filter((d) => d.lastSeenAt > 0)
+        .filter((d) => d.scope === 'mobile' && d.lastSeenAt > 0)
         .map((d) => ({
           deviceId: d.deviceId,
           name: d.name,
@@ -127,7 +112,7 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
     if (!registry) {
       return { revoked: false }
     }
-    return { revoked: registry.removeDevice(args.deviceId) }
+    return { revoked: rpcServer.revokeMobileDevice(args.deviceId) }
   })
 
   ipcMain.handle('mobile:isWebSocketReady', () => {
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index 7c483712e69..2b304baea2b 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -931,6 +931,13 @@ export function registerPtyHandlers(
         return null
       }
     },
+    hasChildProcesses: async (ptyId) => {
+      try {
+        return await getProviderForPty(ptyId).hasChildProcesses(ptyId)
+      } catch {
+        return false
+      }
+    },
     clearBuffer: async (ptyId) => {
       // Why: desktop xterm owns local scrollback, while daemon/SSH providers
       // own their own retained buffers. Clear both surfaces so mobile
@@ -1620,6 +1627,34 @@ export function registerPtyHandlers(
   )
 }
 
+export function registerHeadlessPtyRuntime(
+  runtime: OrcaRuntimeService,
+  getSelectedCodexHomePath?: () => string | null,
+  getSettings?: () => GlobalSettings,
+  prepareClaudeAuth?: () => Promise<ClaudeRuntimeAuthPreparation>,
+  store?: Store
+): void {
+  // Why: headless `orca serve` has no renderer window, but the runtime still
+  // needs the same PTY controller and provider listeners as desktop so remote
+  // clients can create, stream, inspect, and stop terminals.
+  const headlessWindow = {
+    isDestroyed: () => true,
+    webContents: {
+      send: () => {},
+      on: () => {},
+      removeListener: () => {}
+    }
+  } as unknown as BrowserWindow
+  registerPtyHandlers(
+    headlessWindow,
+    runtime,
+    getSelectedCodexHomePath,
+    getSettings,
+    prepareClaudeAuth,
+    store
+  )
+}
+
 /**
  * Kill all PTY processes. Call on app quit.
  */
diff --git a/src/main/ipc/register-core-handlers.test.ts b/src/main/ipc/register-core-handlers.test.ts
index eb6fdd43d6a..aab98e262f9 100644
--- a/src/main/ipc/register-core-handlers.test.ts
+++ b/src/main/ipc/register-core-handlers.test.ts
@@ -24,6 +24,7 @@ const {
   registerUIHandlersMock,
   registerFilesystemHandlersMock,
   registerRuntimeHandlersMock,
+  registerRuntimeEnvironmentHandlersMock,
   registerCodexAccountHandlersMock,
   registerAgentHookHandlersMock,
   registerAgentTrustHandlersMock,
@@ -65,6 +66,7 @@ const {
   registerUIHandlersMock: vi.fn(),
   registerFilesystemHandlersMock: vi.fn(),
   registerRuntimeHandlersMock: vi.fn(),
+  registerRuntimeEnvironmentHandlersMock: vi.fn(),
   registerCodexAccountHandlersMock: vi.fn(),
   registerAgentHookHandlersMock: vi.fn(),
   registerAgentTrustHandlersMock: vi.fn(),
@@ -194,6 +196,10 @@ vi.mock('./runtime', () => ({
   registerRuntimeHandlers: registerRuntimeHandlersMock
 }))
 
+vi.mock('./runtime-environments', () => ({
+  registerRuntimeEnvironmentHandlers: registerRuntimeEnvironmentHandlersMock
+}))
+
 vi.mock('./codex-accounts', () => ({
   registerCodexAccountHandlers: registerCodexAccountHandlersMock
 }))
@@ -262,6 +268,7 @@ describe('registerCoreHandlers', () => {
     registerUIHandlersMock.mockReset()
     registerFilesystemHandlersMock.mockReset()
     registerRuntimeHandlersMock.mockReset()
+    registerRuntimeEnvironmentHandlersMock.mockReset()
     registerCodexAccountHandlersMock.mockReset()
     registerAgentHookHandlersMock.mockReset()
     registerAgentTrustHandlersMock.mockReset()
@@ -328,6 +335,7 @@ describe('registerCoreHandlers', () => {
     expect(registerUIHandlersMock).toHaveBeenCalledWith(store)
     expect(registerFilesystemHandlersMock).toHaveBeenCalledWith(store)
     expect(registerRuntimeHandlersMock).toHaveBeenCalledWith(runtime)
+    expect(registerRuntimeEnvironmentHandlersMock).toHaveBeenCalled()
     expect(registerCliHandlersMock).toHaveBeenCalled()
     expect(registerPreflightHandlersMock).toHaveBeenCalled()
     expect(registerShellHandlersMock).toHaveBeenCalled()
diff --git a/src/main/ipc/register-core-handlers.ts b/src/main/ipc/register-core-handlers.ts
index e445a8e659f..74c08a40f69 100644
--- a/src/main/ipc/register-core-handlers.ts
+++ b/src/main/ipc/register-core-handlers.ts
@@ -18,6 +18,7 @@ import { registerStatsHandlers } from './stats'
 import { registerMemoryHandlers } from './memory'
 import { registerRateLimitHandlers } from './rate-limits'
 import { registerRuntimeHandlers } from './runtime'
+import { registerRuntimeEnvironmentHandlers } from './runtime-environments'
 import { registerNotesHandlers } from './notes'
 import { registerNotificationHandlers } from './notifications'
 import { registerNotebookHandlers } from './notebook'
@@ -120,6 +121,7 @@ export function registerCoreHandlers(
   registerFilesystemHandlers(store)
   registerFilesystemWatcherHandlers()
   registerRuntimeHandlers(runtime)
+  registerRuntimeEnvironmentHandlers()
   registerNotesHandlers(runtime)
   registerClipboardHandlers()
   registerUpdaterHandlers(store)
diff --git a/src/main/ipc/runtime-environment-call-queue.ts b/src/main/ipc/runtime-environment-call-queue.ts
new file mode 100644
index 00000000000..2a06416bb94
--- /dev/null
+++ b/src/main/ipc/runtime-environment-call-queue.ts
@@ -0,0 +1,92 @@
+const REMOTE_RUNTIME_CALL_CONCURRENCY = 8
+const REMOTE_RUNTIME_BACKGROUND_CALL_CONCURRENCY = 2
+
+type QueuedRuntimeCall<T> = {
+  background: boolean
+  run: () => Promise<T>
+  resolve: (value: T) => void
+  reject: (error: unknown) => void
+}
+
+type RuntimeCallQueue = {
+  active: number
+  backgroundActive: number
+  foreground: QueuedRuntimeCall<unknown>[]
+  background: QueuedRuntimeCall<unknown>[]
+}
+
+const runtimeCallQueues = new Map<string, RuntimeCallQueue>()
+
+function isBackgroundRuntimeMethod(method: string): boolean {
+  return (
+    method === 'hostedReview.forBranch' ||
+    method === 'github.listWorkItems' ||
+    method === 'github.countWorkItems' ||
+    method === 'git.status' ||
+    method === 'git.conflictOperation' ||
+    method === 'git.branchCompare' ||
+    method === 'git.upstreamStatus'
+  )
+}
+
+function getRuntimeCallQueue(selector: string): RuntimeCallQueue {
+  let queue = runtimeCallQueues.get(selector)
+  if (!queue) {
+    queue = { active: 0, backgroundActive: 0, foreground: [], background: [] }
+    runtimeCallQueues.set(selector, queue)
+  }
+  return queue
+}
+
+export function enqueueRuntimeCall<T>(
+  selector: string,
+  method: string,
+  run: () => Promise<T>
+): Promise<T> {
+  const queue = getRuntimeCallQueue(selector)
+  return new Promise<T>((resolve, reject) => {
+    const call: QueuedRuntimeCall<T> = {
+      background: isBackgroundRuntimeMethod(method),
+      run,
+      resolve,
+      reject
+    }
+    const targetQueue = call.background ? queue.background : queue.foreground
+    targetQueue.push(call as QueuedRuntimeCall<unknown>)
+    pumpRuntimeCallQueue(selector, queue)
+  })
+}
+
+function pumpRuntimeCallQueue(selector: string, queue: RuntimeCallQueue): void {
+  while (queue.active < REMOTE_RUNTIME_CALL_CONCURRENCY) {
+    let call = queue.foreground.shift()
+    if (!call && queue.backgroundActive < REMOTE_RUNTIME_BACKGROUND_CALL_CONCURRENCY) {
+      call = queue.background.shift()
+    }
+    if (!call) {
+      break
+    }
+
+    queue.active += 1
+    if (call.background) {
+      queue.backgroundActive += 1
+    }
+    // Why: remote WebSocket servers have a finite connection budget and each
+    // one-shot RPC currently opens its own encrypted socket. Background PR/task
+    // refreshes must not stampede the server and starve terminal/worktree calls.
+    void call
+      .run()
+      .then(call.resolve, call.reject)
+      .finally(() => {
+        queue.active = Math.max(0, queue.active - 1)
+        if (call.background) {
+          queue.backgroundActive = Math.max(0, queue.backgroundActive - 1)
+        }
+        if (queue.active === 0 && queue.foreground.length === 0 && queue.background.length === 0) {
+          runtimeCallQueues.delete(selector)
+          return
+        }
+        pumpRuntimeCallQueue(selector, queue)
+      })
+  }
+}
diff --git a/src/main/ipc/runtime-environment-request-connections.ts b/src/main/ipc/runtime-environment-request-connections.ts
new file mode 100644
index 00000000000..97cc0bf21ed
--- /dev/null
+++ b/src/main/ipc/runtime-environment-request-connections.ts
@@ -0,0 +1,46 @@
+import type { PairingOffer } from '../../shared/pairing'
+import type { RuntimeRpcResponse } from '../../shared/runtime-rpc-envelope'
+import { RemoteRuntimeRequestConnection } from '../../shared/remote-runtime-request-connection'
+
+type CachedRuntimeConnection = {
+  pairingKey: string
+  connection: RemoteRuntimeRequestConnection
+}
+
+const requestConnections = new Map<string, CachedRuntimeConnection>()
+
+export function sendRemoteRuntimeConnectionRequest<TResult>(
+  environmentId: string,
+  pairing: PairingOffer,
+  method: string,
+  params: unknown,
+  timeoutMs: number
+): Promise<RuntimeRpcResponse<TResult>> {
+  const pairingKey = getPairingKey(pairing)
+  let cached = requestConnections.get(environmentId)
+  if (!cached || cached.pairingKey !== pairingKey) {
+    cached?.connection.close()
+    cached = {
+      pairingKey,
+      connection: new RemoteRuntimeRequestConnection(pairing)
+    }
+    requestConnections.set(environmentId, cached)
+  }
+  return cached.connection.request(method, params, timeoutMs)
+}
+
+export function closeRemoteRuntimeRequestConnection(environmentId: string): void {
+  const cached = requestConnections.get(environmentId)
+  requestConnections.delete(environmentId)
+  cached?.connection.close()
+}
+
+export function closeAllRemoteRuntimeRequestConnections(): void {
+  for (const environmentId of Array.from(requestConnections.keys())) {
+    closeRemoteRuntimeRequestConnection(environmentId)
+  }
+}
+
+function getPairingKey(pairing: PairingOffer): string {
+  return [pairing.endpoint, pairing.deviceToken, pairing.publicKeyB64].join('\0')
+}
diff --git a/src/main/ipc/runtime-environments.test.ts b/src/main/ipc/runtime-environments.test.ts
new file mode 100644
index 00000000000..14d51953361
--- /dev/null
+++ b/src/main/ipc/runtime-environments.test.ts
@@ -0,0 +1,615 @@
+/* eslint-disable max-lines -- Why: this suite covers runtime environment
+   management, secret redaction, one-shot RPC, and streaming cleanup contracts. */
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { encodePairingOffer } from '../../shared/pairing'
+import * as environmentStore from '../../shared/runtime-environment-store'
+
+const {
+  handleMock,
+  onMock,
+  getPathMock,
+  sendRemoteRuntimeRequestMock,
+  subscribeRemoteRuntimeRequestMock,
+  sendRemoteRuntimeConnectionRequestMock,
+  closeRemoteRuntimeRequestConnectionMock
+} = vi.hoisted(() => ({
+  handleMock: vi.fn(),
+  onMock: vi.fn(),
+  getPathMock: vi.fn(),
+  sendRemoteRuntimeRequestMock: vi.fn(),
+  subscribeRemoteRuntimeRequestMock: vi.fn(),
+  sendRemoteRuntimeConnectionRequestMock: vi.fn(),
+  closeRemoteRuntimeRequestConnectionMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  app: { getPath: getPathMock },
+  ipcMain: { handle: handleMock, on: onMock }
+}))
+
+vi.mock('../../shared/remote-runtime-client', () => ({
+  sendRemoteRuntimeRequest: sendRemoteRuntimeRequestMock,
+  subscribeRemoteRuntimeRequest: subscribeRemoteRuntimeRequestMock
+}))
+
+vi.mock('./runtime-environment-request-connections', () => ({
+  sendRemoteRuntimeConnectionRequest: sendRemoteRuntimeConnectionRequestMock,
+  closeRemoteRuntimeRequestConnection: closeRemoteRuntimeRequestConnectionMock
+}))
+
+import { registerRuntimeEnvironmentHandlers } from './runtime-environments'
+
+function pairingCode(endpoint = 'ws://127.0.0.1:6768'): string {
+  return encodePairingOffer({
+    v: 2,
+    endpoint,
+    deviceToken: 'device-token',
+    publicKeyB64: Buffer.from(new Uint8Array(32).fill(1)).toString('base64')
+  })
+}
+
+function handler<TArgs, TResult>(
+  channel: string
+): (_event: unknown, args: TArgs) => TResult | Promise<TResult> {
+  const match = handleMock.mock.calls.find((call) => call[0] === channel)
+  expect(match).toBeTruthy()
+  return match![1] as (_event: unknown, args: TArgs) => TResult | Promise<TResult>
+}
+
+describe('registerRuntimeEnvironmentHandlers', () => {
+  let userDataPath: string
+
+  beforeEach(() => {
+    userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-env-ipc-'))
+    getPathMock.mockReset()
+    getPathMock.mockReturnValue(userDataPath)
+    handleMock.mockReset()
+    onMock.mockReset()
+    sendRemoteRuntimeRequestMock.mockReset()
+    subscribeRemoteRuntimeRequestMock.mockReset()
+    sendRemoteRuntimeConnectionRequestMock.mockReset()
+    closeRemoteRuntimeRequestConnectionMock.mockReset()
+  })
+
+  afterEach(() => {
+    rmSync(userDataPath, { recursive: true, force: true })
+  })
+
+  it('registers desktop runtime environment management handlers', () => {
+    registerRuntimeEnvironmentHandlers()
+
+    expect(handleMock.mock.calls.map((call) => call[0])).toEqual([
+      'runtimeEnvironments:list',
+      'runtimeEnvironments:addFromPairingCode',
+      'runtimeEnvironments:resolve',
+      'runtimeEnvironments:remove',
+      'runtimeEnvironments:getStatus',
+      'runtimeEnvironments:call',
+      'runtimeEnvironments:subscribe',
+      'runtimeEnvironments:unsubscribe'
+    ])
+    expect(onMock.mock.calls.map((call) => call[0])).toEqual([
+      'runtimeEnvironments:subscriptionBinary'
+    ])
+  })
+
+  it('stores, resolves, lists, and removes environments under Electron userData', async () => {
+    registerRuntimeEnvironmentHandlers()
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    const added = await add(null, { name: 'desk', pairingCode: pairingCode() })
+    expect(JSON.stringify(added)).not.toContain('device-token')
+    expect(JSON.stringify(added)).not.toContain('publicKeyB64')
+
+    const list = handler<undefined, { id: string; name: string }[]>('runtimeEnvironments:list')
+    expect(await list(null, undefined)).toMatchObject([{ id: added.environment.id, name: 'desk' }])
+    expect(JSON.stringify(await list(null, undefined))).not.toContain('device-token')
+
+    const resolve = handler<{ selector: string }, { id: string; name: string }>(
+      'runtimeEnvironments:resolve'
+    )
+    expect(await resolve(null, { selector: 'desk' })).toMatchObject({
+      id: added.environment.id,
+      name: 'desk'
+    })
+    expect(JSON.stringify(await resolve(null, { selector: 'desk' }))).not.toContain('device-token')
+
+    const remove = handler<{ selector: string }, { removed: { id: string; name: string } }>(
+      'runtimeEnvironments:remove'
+    )
+    const removed = await remove(null, { selector: added.environment.id })
+    expect(removed).toMatchObject({
+      removed: { id: added.environment.id, name: 'desk' }
+    })
+    expect(closeRemoteRuntimeRequestConnectionMock).toHaveBeenCalledWith(added.environment.id)
+    expect(JSON.stringify(removed)).not.toContain('device-token')
+    expect(await list(null, undefined)).toEqual([])
+  })
+
+  it('checks a saved remote runtime and records the runtime id on success', async () => {
+    registerRuntimeEnvironmentHandlers()
+    sendRemoteRuntimeRequestMock.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { runtimeId: 'runtime-remote', graphStatus: 'ready' },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    const added = await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    const getStatus = handler<
+      { selector: string; timeoutMs?: number },
+      { ok: true; result: { runtimeId: string } }
+    >('runtimeEnvironments:getStatus')
+    expect(await getStatus(null, { selector: 'desk', timeoutMs: 50 })).toMatchObject({
+      ok: true,
+      result: { runtimeId: 'runtime-remote' }
+    })
+    expect(sendRemoteRuntimeRequestMock).toHaveBeenCalledWith(
+      expect.objectContaining({ endpoint: 'ws://127.0.0.1:6768', deviceToken: 'device-token' }),
+      'status.get',
+      undefined,
+      50
+    )
+
+    const resolve = handler<{ selector: string }, { id: string; runtimeId: string | null }>(
+      'runtimeEnvironments:resolve'
+    )
+    expect(await resolve(null, { selector: added.environment.id })).toMatchObject({
+      id: added.environment.id,
+      runtimeId: 'runtime-remote'
+    })
+  })
+
+  it('proxies generic one-shot RPC calls to the saved remote runtime', async () => {
+    registerRuntimeEnvironmentHandlers()
+    sendRemoteRuntimeRequestMock.mockResolvedValue({
+      id: 'rpc-2',
+      ok: true,
+      result: { repos: [{ id: 'repo-1' }] },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    const call = handler<
+      { selector: string; method: string; params?: unknown; timeoutMs?: number },
+      { ok: true; result: unknown }
+    >('runtimeEnvironments:call')
+    expect(
+      await call(null, { selector: 'desk', method: 'repo.list', timeoutMs: 75 })
+    ).toMatchObject({
+      ok: true,
+      result: { repos: [{ id: 'repo-1' }] }
+    })
+    expect(sendRemoteRuntimeRequestMock).toHaveBeenCalledWith(
+      expect.objectContaining({ endpoint: 'ws://127.0.0.1:6768' }),
+      'repo.list',
+      undefined,
+      75
+    )
+    expect(sendRemoteRuntimeConnectionRequestMock).not.toHaveBeenCalled()
+  })
+
+  it('uses the cached request connection for terminal hot path RPCs', async () => {
+    registerRuntimeEnvironmentHandlers()
+    sendRemoteRuntimeConnectionRequestMock.mockResolvedValue({
+      id: 'rpc-terminal',
+      ok: true,
+      result: { send: { accepted: true } },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    const call = handler<
+      { selector: string; method: string; params?: unknown; timeoutMs?: number },
+      { ok: true; result: unknown }
+    >('runtimeEnvironments:call')
+    expect(
+      await call(null, {
+        selector: 'desk',
+        method: 'terminal.send',
+        params: { terminal: 't1', text: 'a' },
+        timeoutMs: 75
+      })
+    ).toMatchObject({
+      ok: true,
+      result: { send: { accepted: true } }
+    })
+    expect(sendRemoteRuntimeConnectionRequestMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ endpoint: 'ws://127.0.0.1:6768' }),
+      'terminal.send',
+      { terminal: 't1', text: 'a' },
+      75
+    )
+    expect(sendRemoteRuntimeRequestMock).not.toHaveBeenCalled()
+  })
+
+  it('limits background one-shot RPCs without blocking foreground runtime calls', async () => {
+    registerRuntimeEnvironmentHandlers()
+    const pendingBackground: ((value: unknown) => void)[] = []
+    sendRemoteRuntimeRequestMock.mockImplementation(async () => {
+      return await new Promise((resolve) => pendingBackground.push(resolve))
+    })
+    sendRemoteRuntimeConnectionRequestMock.mockResolvedValue({
+      id: 'terminal-send',
+      ok: true,
+      result: { send: { accepted: true } },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    const call = handler<
+      { selector: string; method: string; params?: unknown; timeoutMs?: number },
+      { ok: true; result: unknown }
+    >('runtimeEnvironments:call')
+    const bg1 = call(null, { selector: 'desk', method: 'hostedReview.forBranch' })
+    const bg2 = call(null, { selector: 'desk', method: 'github.listWorkItems' })
+    await vi.waitFor(() => expect(sendRemoteRuntimeRequestMock).toHaveBeenCalledTimes(2))
+
+    const bg3 = call(null, { selector: 'desk', method: 'git.status' })
+    const foreground = call(null, {
+      selector: 'desk',
+      method: 'terminal.send',
+      params: { terminal: 'term-1', text: 'a' }
+    })
+    await vi.waitFor(() =>
+      expect(sendRemoteRuntimeRequestMock.mock.calls.map((call) => call[1])).toEqual([
+        'hostedReview.forBranch',
+        'github.listWorkItems'
+      ])
+    )
+    expect(sendRemoteRuntimeConnectionRequestMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.any(Object),
+      'terminal.send',
+      { terminal: 'term-1', text: 'a' },
+      15_000
+    )
+
+    await expect(foreground).resolves.toMatchObject({
+      ok: true,
+      result: { send: { accepted: true } }
+    })
+    expect(pendingBackground).toHaveLength(2)
+
+    pendingBackground.shift()?.({
+      id: 'background-1',
+      ok: true,
+      result: null,
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    await vi.waitFor(() => expect(sendRemoteRuntimeRequestMock).toHaveBeenCalledTimes(3))
+    expect(sendRemoteRuntimeRequestMock.mock.calls.map((call) => call[1])).toEqual([
+      'hostedReview.forBranch',
+      'github.listWorkItems',
+      'git.status'
+    ])
+
+    pendingBackground.splice(0).forEach((resolve) =>
+      resolve({
+        id: 'background',
+        ok: true,
+        result: null,
+        _meta: { runtimeId: 'runtime-remote' }
+      })
+    )
+    await expect(bg1).resolves.toMatchObject({ ok: true })
+    await expect(bg2).resolves.toMatchObject({ ok: true })
+    await expect(bg3).resolves.toMatchObject({ ok: true })
+  })
+
+  it('starts and stops streaming subscriptions for a saved remote runtime', async () => {
+    registerRuntimeEnvironmentHandlers()
+    const close = vi.fn()
+    const sendBinary = vi.fn()
+    const markUsedSpy = vi.spyOn(environmentStore, 'markEnvironmentUsed')
+    subscribeRemoteRuntimeRequestMock.mockImplementation(
+      async (_pairing, _method, _params, _timeoutMs, callbacks) => {
+        callbacks.onResponse({
+          id: 'stream-1',
+          ok: true,
+          result: { type: 'subscribed' },
+          _meta: { runtimeId: 'runtime-remote' }
+        })
+        callbacks.onResponse({
+          id: 'stream-1',
+          ok: true,
+          result: { type: 'data', chunk: 'hello' },
+          _meta: { runtimeId: 'runtime-remote' }
+        })
+        callbacks.onBinary(new Uint8Array([1, 2, 3]))
+        return { requestId: 'stream-1', close, sendBinary }
+      }
+    )
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    const sent: unknown[] = []
+    const destroyedListenerRemoved = vi.fn()
+    const subscribe = handler<
+      {
+        selector: string
+        method: string
+        params?: unknown
+        timeoutMs?: number
+        subscriptionId?: string
+      },
+      { subscriptionId: string; requestId: string }
+    >('runtimeEnvironments:subscribe')
+    const result = await subscribe(
+      {
+        sender: {
+          id: 1,
+          isDestroyed: () => false,
+          send: (_channel: string, payload: unknown) => sent.push(payload),
+          once: vi.fn(),
+          removeListener: destroyedListenerRemoved
+        }
+      },
+      {
+        selector: 'desk',
+        method: 'terminal.subscribe',
+        params: { terminal: 't1' },
+        timeoutMs: 25,
+        subscriptionId: 'preload-sub-1'
+      }
+    )
+
+    expect(result.requestId).toBe('stream-1')
+    expect(result.subscriptionId).toBe('preload-sub-1')
+    expect(subscribeRemoteRuntimeRequestMock).toHaveBeenCalledWith(
+      expect.objectContaining({ endpoint: 'ws://127.0.0.1:6768' }),
+      'terminal.subscribe',
+      { terminal: 't1' },
+      25,
+      expect.any(Object)
+    )
+    expect(sent).toEqual([
+      expect.objectContaining({ subscriptionId: result.subscriptionId, type: 'response' }),
+      expect.objectContaining({ subscriptionId: result.subscriptionId, type: 'response' }),
+      expect.objectContaining({ subscriptionId: result.subscriptionId, type: 'binary' })
+    ])
+    expect(markUsedSpy).toHaveBeenCalledTimes(1)
+
+    const binaryListener = onMock.mock.calls.find(
+      (call) => call[0] === 'runtimeEnvironments:subscriptionBinary'
+    )?.[1] as (_event: unknown, args: unknown) => void
+    const bytes = new Uint8Array([9, 8, 7])
+    binaryListener({ sender: { id: 1 } }, { subscriptionId: result.subscriptionId, bytes })
+    expect(sendBinary).toHaveBeenCalledWith(bytes)
+
+    const unsubscribe = handler<{ subscriptionId: string }, { unsubscribed: boolean }>(
+      'runtimeEnvironments:unsubscribe'
+    )
+    expect(
+      await unsubscribe({ sender: { id: 1 } }, { subscriptionId: result.subscriptionId })
+    ).toEqual({
+      unsubscribed: true
+    })
+    expect(close).toHaveBeenCalled()
+    expect(destroyedListenerRemoved).toHaveBeenCalledWith('destroyed', expect.any(Function))
+    markUsedSpy.mockRestore()
+  })
+
+  it('rejects cross-window streaming subscription control', async () => {
+    registerRuntimeEnvironmentHandlers()
+    const close = vi.fn()
+    const sendBinary = vi.fn()
+    subscribeRemoteRuntimeRequestMock.mockResolvedValue({
+      requestId: 'stream-1',
+      close,
+      sendBinary
+    })
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    const subscribe = handler<
+      {
+        selector: string
+        method: string
+        params?: unknown
+        subscriptionId?: string
+      },
+      { subscriptionId: string; requestId: string }
+    >('runtimeEnvironments:subscribe')
+    const result = await subscribe(
+      {
+        sender: {
+          id: 1,
+          isDestroyed: () => false,
+          send: vi.fn(),
+          once: vi.fn(),
+          removeListener: vi.fn()
+        }
+      },
+      {
+        selector: 'desk',
+        method: 'terminal.subscribe',
+        params: { terminal: 't1' },
+        subscriptionId: 'owned-sub'
+      }
+    )
+
+    const binaryListener = onMock.mock.calls.find(
+      (call) => call[0] === 'runtimeEnvironments:subscriptionBinary'
+    )?.[1] as (_event: unknown, args: unknown) => void
+    binaryListener(
+      { sender: { id: 2 } },
+      { subscriptionId: result.subscriptionId, bytes: new Uint8Array([1]) }
+    )
+    expect(sendBinary).not.toHaveBeenCalled()
+
+    const unsubscribe = handler<{ subscriptionId: string }, { unsubscribed: boolean }>(
+      'runtimeEnvironments:unsubscribe'
+    )
+    expect(
+      await unsubscribe({ sender: { id: 2 } }, { subscriptionId: result.subscriptionId })
+    ).toEqual({
+      unsubscribed: false
+    })
+    expect(close).not.toHaveBeenCalled()
+
+    expect(
+      await unsubscribe({ sender: { id: 1 } }, { subscriptionId: result.subscriptionId })
+    ).toEqual({
+      unsubscribed: true
+    })
+    expect(close).toHaveBeenCalled()
+  })
+
+  it('closes a streaming subscription that resolves after the sender is destroyed', async () => {
+    registerRuntimeEnvironmentHandlers()
+    const close = vi.fn()
+    let resolveSubscribe: (value: {
+      requestId: string
+      close: () => void
+      sendBinary: (bytes: Uint8Array<ArrayBufferLike>) => boolean
+    }) => void = () => {}
+    subscribeRemoteRuntimeRequestMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveSubscribe = resolve
+        })
+    )
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    let destroyed = false
+    let destroyedHandler: unknown = null
+    const destroyedListenerRemoved = vi.fn()
+    const subscribe = handler<
+      {
+        selector: string
+        method: string
+        params?: unknown
+        subscriptionId?: string
+      },
+      { subscriptionId: string; requestId: string }
+    >('runtimeEnvironments:subscribe')
+    const resultPromise = subscribe(
+      {
+        sender: {
+          id: 1,
+          isDestroyed: () => destroyed,
+          send: vi.fn(),
+          once: vi.fn((_event: string, handler: () => void) => {
+            destroyedHandler = () => {
+              destroyed = true
+              handler()
+            }
+          }),
+          removeListener: destroyedListenerRemoved
+        }
+      },
+      {
+        selector: 'desk',
+        method: 'terminal.subscribe',
+        params: { terminal: 't1' },
+        subscriptionId: 'late-sub'
+      }
+    )
+
+    await vi.waitFor(() => {
+      expect(subscribeRemoteRuntimeRequestMock).toHaveBeenCalled()
+    })
+    expect(destroyedHandler).toBeTypeOf('function')
+    ;(destroyedHandler as () => void)()
+    resolveSubscribe({ requestId: 'stream-late', close, sendBinary: vi.fn() })
+
+    await expect(resultPromise).resolves.toEqual({
+      subscriptionId: 'late-sub',
+      requestId: 'stream-late'
+    })
+    expect(close).toHaveBeenCalledTimes(1)
+    expect(destroyedListenerRemoved).toHaveBeenCalledWith('destroyed', expect.any(Function))
+
+    const unsubscribe = handler<{ subscriptionId: string }, { unsubscribed: boolean }>(
+      'runtimeEnvironments:unsubscribe'
+    )
+    expect(await unsubscribe({ sender: { id: 1 } }, { subscriptionId: 'late-sub' })).toEqual({
+      unsubscribed: false
+    })
+  })
+
+  it('removes the destroyed listener when streaming subscription setup rejects', async () => {
+    registerRuntimeEnvironmentHandlers()
+    subscribeRemoteRuntimeRequestMock.mockRejectedValue(new Error('connect failed'))
+
+    const add = handler<
+      { name: string; pairingCode: string },
+      { environment: { id: string; name: string } }
+    >('runtimeEnvironments:addFromPairingCode')
+    await add(null, { name: 'desk', pairingCode: pairingCode() })
+
+    const destroyedListenerRemoved = vi.fn()
+    const subscribe = handler<
+      {
+        selector: string
+        method: string
+        params?: unknown
+        subscriptionId?: string
+      },
+      { subscriptionId: string; requestId: string }
+    >('runtimeEnvironments:subscribe')
+
+    await expect(
+      subscribe(
+        {
+          sender: {
+            id: 1,
+            isDestroyed: () => false,
+            send: vi.fn(),
+            once: vi.fn(),
+            removeListener: destroyedListenerRemoved
+          }
+        },
+        {
+          selector: 'desk',
+          method: 'terminal.subscribe',
+          params: { terminal: 't1' },
+          subscriptionId: 'failed-sub'
+        }
+      )
+    ).rejects.toThrow('connect failed')
+
+    expect(destroyedListenerRemoved).toHaveBeenCalledWith('destroyed', expect.any(Function))
+  })
+})
diff --git a/src/main/ipc/runtime-environments.ts b/src/main/ipc/runtime-environments.ts
new file mode 100644
index 00000000000..9b278ba63ba
--- /dev/null
+++ b/src/main/ipc/runtime-environments.ts
@@ -0,0 +1,313 @@
+/* eslint-disable max-lines -- Why: runtime environment IPC is the security boundary for saved server calls and subscriptions; keeping ownership checks, lifecycle cleanup, and binary forwarding together makes the bridge auditable. */
+import { app, ipcMain } from 'electron'
+import { randomUUID } from 'crypto'
+import {
+  addEnvironmentFromPairingCode,
+  listEnvironments,
+  markEnvironmentUsed,
+  removeEnvironment,
+  resolveEnvironment,
+  resolveEnvironmentPairingOffer
+} from '../../shared/runtime-environment-store'
+import {
+  redactRuntimeEnvironment,
+  getPreferredPairingOffer,
+  type PublicKnownRuntimeEnvironment
+} from '../../shared/runtime-environments'
+import type { RuntimeStatus } from '../../shared/runtime-types'
+import type { RuntimeRpcResponse } from '../../shared/runtime-rpc-envelope'
+import {
+  sendRemoteRuntimeRequest,
+  subscribeRemoteRuntimeRequest,
+  type RemoteRuntimeSubscription
+} from '../../shared/remote-runtime-client'
+import { enqueueRuntimeCall } from './runtime-environment-call-queue'
+import {
+  closeRemoteRuntimeRequestConnection,
+  sendRemoteRuntimeConnectionRequest
+} from './runtime-environment-request-connections'
+
+const DEFAULT_REMOTE_RUNTIME_TIMEOUT_MS = 15_000
+type RetainedRemoteRuntimeSubscription = RemoteRuntimeSubscription & {
+  ownerWebContentsId: number
+  removeDestroyedListener: () => void
+}
+const remoteRuntimeSubscriptions = new Map<string, RetainedRemoteRuntimeSubscription>()
+
+function getUserDataPath(): string {
+  return app.getPath('userData')
+}
+
+function shouldUseCachedRequestConnection(method: string): boolean {
+  return method === 'terminal.send' || method === 'terminal.updateViewport'
+}
+
+export function registerRuntimeEnvironmentHandlers(): void {
+  ipcMain.handle('runtimeEnvironments:list', (): PublicKnownRuntimeEnvironment[] =>
+    listEnvironments(getUserDataPath()).map(redactRuntimeEnvironment)
+  )
+  ipcMain.handle(
+    'runtimeEnvironments:addFromPairingCode',
+    (
+      _event,
+      args: { name: string; pairingCode: string }
+    ): { environment: PublicKnownRuntimeEnvironment } => ({
+      environment: redactRuntimeEnvironment(addEnvironmentFromPairingCode(getUserDataPath(), args))
+    })
+  )
+  ipcMain.handle(
+    'runtimeEnvironments:resolve',
+    (_event, args: { selector: string }): PublicKnownRuntimeEnvironment =>
+      redactRuntimeEnvironment(resolveEnvironment(getUserDataPath(), args.selector))
+  )
+  ipcMain.handle(
+    'runtimeEnvironments:remove',
+    (_event, args: { selector: string }): { removed: PublicKnownRuntimeEnvironment } => {
+      const removed = removeEnvironment(getUserDataPath(), args.selector)
+      closeRemoteRuntimeRequestConnection(removed.id)
+      if (args.selector !== removed.id) {
+        closeRemoteRuntimeRequestConnection(args.selector)
+      }
+      return { removed: redactRuntimeEnvironment(removed) }
+    }
+  )
+  ipcMain.handle(
+    'runtimeEnvironments:getStatus',
+    async (
+      _event,
+      args: { selector: string; timeoutMs?: number }
+    ): Promise<RuntimeRpcResponse<RuntimeStatus>> => {
+      const userDataPath = getUserDataPath()
+      const response = await sendRemoteRuntimeRequest<RuntimeStatus>(
+        resolveEnvironmentPairingOffer(userDataPath, args.selector),
+        'status.get',
+        undefined,
+        args.timeoutMs ?? DEFAULT_REMOTE_RUNTIME_TIMEOUT_MS
+      )
+      if (response.ok === true) {
+        markEnvironmentUsed(userDataPath, args.selector, { runtimeId: response._meta.runtimeId })
+      }
+      return response
+    }
+  )
+  ipcMain.handle(
+    'runtimeEnvironments:call',
+    async (
+      _event,
+      args: { selector: string; method: string; params?: unknown; timeoutMs?: number }
+    ): Promise<RuntimeRpcResponse<unknown>> => {
+      return callRuntimeEnvironment(args.selector, args.method, args.params, args.timeoutMs)
+    }
+  )
+  ipcMain.handle(
+    'runtimeEnvironments:subscribe',
+    async (
+      event,
+      args: {
+        selector: string
+        method: string
+        params?: unknown
+        timeoutMs?: number
+        subscriptionId?: string
+      }
+    ): Promise<{ subscriptionId: string; requestId: string }> => {
+      const subscriptionId =
+        typeof args.subscriptionId === 'string' && args.subscriptionId.length > 0
+          ? args.subscriptionId
+          : randomUUID()
+      if (remoteRuntimeSubscriptions.has(subscriptionId)) {
+        throw new Error('Runtime environment subscription id already exists')
+      }
+      const sender = event.sender
+      const ownerWebContentsId = sender.id
+      let senderDestroyed = sender.isDestroyed()
+      let subscription: RemoteRuntimeSubscription | null = null
+      let destroyedListenerAttached = false
+      const removeDestroyedListener = (): void => {
+        if (!destroyedListenerAttached) {
+          return
+        }
+        destroyedListenerAttached = false
+        sender.removeListener('destroyed', closeSubscription)
+      }
+      const closeSubscription = (): void => {
+        senderDestroyed = true
+        const retained = remoteRuntimeSubscriptions.get(subscriptionId) ?? null
+        remoteRuntimeSubscriptions.delete(subscriptionId)
+        if (retained) {
+          retained.close()
+          return
+        }
+        removeDestroyedListener()
+        subscription?.close()
+      }
+      sender.once('destroyed', closeSubscription)
+      destroyedListenerAttached = true
+      try {
+        subscription = await subscribeRuntimeEnvironment(
+          args.selector,
+          args.method,
+          args.params,
+          args.timeoutMs,
+          {
+            onEvent: (payload) => {
+              if (!sender.isDestroyed()) {
+                sender.send('runtimeEnvironments:subscriptionEvent', {
+                  subscriptionId,
+                  ...payload
+                })
+              }
+            },
+            onClose: () => {
+              const retained = remoteRuntimeSubscriptions.get(subscriptionId) ?? null
+              retained?.removeDestroyedListener()
+              remoteRuntimeSubscriptions.delete(subscriptionId)
+            }
+          }
+        )
+      } catch (error) {
+        removeDestroyedListener()
+        throw error
+      }
+      if (senderDestroyed || sender.isDestroyed()) {
+        removeDestroyedListener()
+        subscription.close()
+        return { subscriptionId, requestId: subscription.requestId }
+      }
+      remoteRuntimeSubscriptions.set(subscriptionId, {
+        requestId: subscription.requestId,
+        ownerWebContentsId,
+        removeDestroyedListener,
+        sendBinary: (bytes) => subscription?.sendBinary(bytes) ?? false,
+        close: () => {
+          removeDestroyedListener()
+          subscription?.close()
+        }
+      })
+      return { subscriptionId, requestId: subscription.requestId }
+    }
+  )
+  ipcMain.handle(
+    'runtimeEnvironments:unsubscribe',
+    (event, args: { subscriptionId: string }): { unsubscribed: boolean } => {
+      const subscription = remoteRuntimeSubscriptions.get(args.subscriptionId)
+      if (!subscription || subscription.ownerWebContentsId !== event.sender.id) {
+        return { unsubscribed: false }
+      }
+      remoteRuntimeSubscriptions.delete(args.subscriptionId)
+      subscription.close()
+      return { unsubscribed: true }
+    }
+  )
+  ipcMain.on(
+    'runtimeEnvironments:subscriptionBinary',
+    (event, args: { subscriptionId?: unknown; bytes?: unknown }) => {
+      if (typeof args.subscriptionId !== 'string') {
+        return
+      }
+      const bytes = toBinaryPayload(args.bytes)
+      if (!bytes) {
+        return
+      }
+      const subscription = remoteRuntimeSubscriptions.get(args.subscriptionId)
+      if (subscription?.ownerWebContentsId === event.sender.id) {
+        subscription.sendBinary(bytes)
+      }
+    }
+  )
+}
+
+function toBinaryPayload(value: unknown): Uint8Array<ArrayBufferLike> | null {
+  if (value instanceof Uint8Array) {
+    return value
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value)
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+  }
+  return null
+}
+
+async function callRuntimeEnvironment(
+  selector: string,
+  method: string,
+  params: unknown,
+  timeoutMs?: number
+): Promise<RuntimeRpcResponse<unknown>> {
+  const userDataPath = getUserDataPath()
+  const environment = resolveEnvironment(userDataPath, selector)
+  return enqueueRuntimeCall(environment.id, method, async () => {
+    const currentEnvironment = resolveEnvironment(userDataPath, environment.id)
+    const pairing = getPreferredPairingOffer(currentEnvironment)
+    const effectiveTimeoutMs = timeoutMs ?? DEFAULT_REMOTE_RUNTIME_TIMEOUT_MS
+    // Why: the cached request socket is only needed for terminal hot paths.
+    // Startup/control-plane RPCs use the proven one-shot path so repo hydration
+    // cannot be coupled to a stale terminal-control connection.
+    const response = shouldUseCachedRequestConnection(method)
+      ? await sendRemoteRuntimeConnectionRequest(
+          currentEnvironment.id,
+          pairing,
+          method,
+          params,
+          effectiveTimeoutMs
+        )
+      : await sendRemoteRuntimeRequest(pairing, method, params, effectiveTimeoutMs)
+    if (response.ok === true) {
+      markEnvironmentUsed(userDataPath, currentEnvironment.id, {
+        runtimeId: response._meta.runtimeId
+      })
+    }
+    return response
+  })
+}
+
+async function subscribeRuntimeEnvironment(
+  selector: string,
+  method: string,
+  params: unknown,
+  timeoutMs: number | undefined,
+  callbacks: {
+    onEvent: (
+      payload:
+        | { type: 'response'; response: RuntimeRpcResponse<unknown> }
+        | { type: 'binary'; bytes: Uint8Array<ArrayBufferLike> }
+        | { type: 'error'; code: string; message: string }
+        | { type: 'close' }
+    ) => void
+    onClose: () => void
+  }
+): Promise<RemoteRuntimeSubscription> {
+  const userDataPath = getUserDataPath()
+  let markedUsed = false
+  const markUsedOnce = (runtimeId: string): void => {
+    if (markedUsed) {
+      return
+    }
+    markedUsed = true
+    markEnvironmentUsed(userDataPath, selector, { runtimeId })
+  }
+  const subscription = await subscribeRemoteRuntimeRequest(
+    resolveEnvironmentPairingOffer(userDataPath, selector),
+    method,
+    params,
+    timeoutMs ?? DEFAULT_REMOTE_RUNTIME_TIMEOUT_MS,
+    {
+      onResponse: (response) => {
+        if (response.ok === true) {
+          markUsedOnce(response._meta.runtimeId)
+        }
+        callbacks.onEvent({ type: 'response', response })
+      },
+      onBinary: (bytes) => callbacks.onEvent({ type: 'binary', bytes }),
+      onError: (error) =>
+        callbacks.onEvent({ type: 'error', code: error.code, message: error.message }),
+      onClose: () => {
+        callbacks.onEvent({ type: 'close' })
+        callbacks.onClose()
+      }
+    }
+  )
+  return subscription
+}
diff --git a/src/main/ipc/runtime.test.ts b/src/main/ipc/runtime.test.ts
index 29c96559cd8..68a570e28cd 100644
--- a/src/main/ipc/runtime.test.ts
+++ b/src/main/ipc/runtime.test.ts
@@ -28,7 +28,8 @@ describe('registerRuntimeHandlers', () => {
   it('routes sync requests through the authoritative browser window id', () => {
     const runtime = {
       syncWindowGraph: vi.fn().mockReturnValue({ graphStatus: 'ready' }),
-      getStatus: vi.fn().mockReturnValue({ graphStatus: 'unavailable' })
+      getStatus: vi.fn().mockReturnValue({ graphStatus: 'unavailable' }),
+      getRuntimeId: vi.fn().mockReturnValue('runtime-1')
     }
 
     registerRuntimeHandlers(runtime as never)
@@ -46,4 +47,33 @@ describe('registerRuntimeHandlers', () => {
     expect(runtime.syncWindowGraph).toHaveBeenCalledWith(17, { tabs: [], leaves: [] })
     expect(result).toEqual({ graphStatus: 'ready' })
   })
+
+  it('routes generic local runtime RPC calls through the dispatcher', async () => {
+    const runtime = {
+      syncWindowGraph: vi.fn(),
+      getStatus: vi.fn().mockReturnValue({
+        runtimeId: 'runtime-1',
+        rendererGraphEpoch: 0,
+        graphStatus: 'ready',
+        authoritativeWindowId: null,
+        liveTabCount: 0,
+        liveLeafCount: 0
+      }),
+      getRuntimeId: vi.fn().mockReturnValue('runtime-1')
+    }
+
+    registerRuntimeHandlers(runtime as never)
+
+    const callRegistration = handleMock.mock.calls.find(([channel]) => channel === 'runtime:call')
+    expect(callRegistration).toBeTruthy()
+
+    const handler = callRegistration![1]
+    const result = await handler({ sender: {} }, { method: 'status.get' })
+
+    expect(result).toMatchObject({
+      ok: true,
+      result: { runtimeId: 'runtime-1', graphStatus: 'ready' },
+      _meta: { runtimeId: 'runtime-1' }
+    })
+  })
 })
diff --git a/src/main/ipc/runtime.ts b/src/main/ipc/runtime.ts
index 14a4de52ffb..d6c91e9e96e 100644
--- a/src/main/ipc/runtime.ts
+++ b/src/main/ipc/runtime.ts
@@ -1,10 +1,13 @@
 import { BrowserWindow, ipcMain } from 'electron'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
 import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../../shared/runtime-types'
+import type { RuntimeRpcResponse } from '../../shared/runtime-rpc-envelope'
+import { RpcDispatcher } from '../runtime/rpc/dispatcher'
 
 export function registerRuntimeHandlers(runtime: OrcaRuntimeService): void {
   ipcMain.removeHandler('runtime:syncWindowGraph')
   ipcMain.removeHandler('runtime:getStatus')
+  ipcMain.removeHandler('runtime:call')
 
   ipcMain.handle(
     'runtime:syncWindowGraph',
@@ -21,6 +24,21 @@ export function registerRuntimeHandlers(runtime: OrcaRuntimeService): void {
     return runtime.getStatus()
   })
 
+  ipcMain.handle(
+    'runtime:call',
+    async (
+      _event,
+      args: { method: string; params?: unknown }
+    ): Promise<RuntimeRpcResponse<unknown>> => {
+      return (await new RpcDispatcher({ runtime }).dispatch({
+        id: 'desktop-ipc',
+        authToken: 'desktop-ipc',
+        method: args.method,
+        params: args.params
+      })) as RuntimeRpcResponse<unknown>
+    }
+  )
+
   ipcMain.removeHandler('runtime:getTerminalFitOverrides')
   ipcMain.handle(
     'runtime:getTerminalFitOverrides',
diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index 948297d004b..066c39d981e 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -108,7 +108,7 @@ async function ensureUniqueRemoteName(repoPath: string, preferred: string): Prom
   throw new Error(`Could not find an available remote name for ${preferred}.`)
 }
 
-async function prepareWorktreePushTarget(
+export async function prepareWorktreePushTarget(
   repoPath: string,
   target: GitPushTarget
 ): Promise<GitPushTarget> {
@@ -138,7 +138,7 @@ async function prepareWorktreePushTarget(
   }
 }
 
-async function configureCreatedWorktreePushTarget(
+export async function configureCreatedWorktreePushTarget(
   worktreePath: string,
   branchName: string,
   target: GitPushTarget
diff --git a/src/main/powershell-osc133-bootstrap.test.ts b/src/main/powershell-osc133-bootstrap.test.ts
index a7219b84500..10d278088a8 100644
--- a/src/main/powershell-osc133-bootstrap.test.ts
+++ b/src/main/powershell-osc133-bootstrap.test.ts
@@ -13,10 +13,13 @@ describe('PowerShell OSC 133 bootstrap', () => {
     expect(script).toContain('ORCA_PI_CODING_AGENT_DIR')
     expect(script).toContain('function Global:prompt')
     expect(script).toContain('function Global:PSConsoleHostReadLine')
-    expect(script).toContain('`e]133;D;$fakeExitCode`a')
-    expect(script).toContain('`e]133;A`a')
-    expect(script).toContain('`e]133;B`a')
-    expect(script).toContain('`e]133;C`a')
+    expect(script).toContain('Esc = [char]27')
+    expect(script).toContain('Bel = [char]7')
+    expect(script).toContain(')]133;D;$fakeExitCode$(')
+    expect(script).toContain(')]133;A$(')
+    expect(script).toContain(')]133;B$(')
+    expect(script).toContain(')]133;C$(')
+    expect(script).not.toContain('`e]133')
     expect(script).not.toContain('$PROFILE')
     expect(script).not.toContain('ExecutionPolicy')
     expect(script).not.toContain('NoProfile')
diff --git a/src/main/powershell-osc133-bootstrap.ts b/src/main/powershell-osc133-bootstrap.ts
index 1784020c468..8f87ed21d2d 100644
--- a/src/main/powershell-osc133-bootstrap.ts
+++ b/src/main/powershell-osc133-bootstrap.ts
@@ -28,6 +28,8 @@ $Global:__OrcaOsc133State = @{
     OriginalReadLine = $function:PSConsoleHostReadLine
     HasSeenPrompt = $false
     HasPSReadLine = $null -ne (Get-Module -Name PSReadLine)
+    Esc = [char]27
+    Bel = [char]7
 }
 
 function Global:prompt {
@@ -39,15 +41,15 @@ function Global:prompt {
     # Emit D from prompt, not readline state. Some profile setups bypass
     # PSConsoleHostReadLine; the consumer only needs completion.
     if ($Global:__OrcaOsc133State.HasSeenPrompt) {
-        $result += "\`e]133;D;$fakeExitCode\`a"
+        $result += "$($Global:__OrcaOsc133State.Esc)]133;D;$fakeExitCode$($Global:__OrcaOsc133State.Bel)"
     }
     $Global:__OrcaOsc133State.HasSeenPrompt = $true
 
-    $result += "\`e]133;A\`a"
+    $result += "$($Global:__OrcaOsc133State.Esc)]133;A$($Global:__OrcaOsc133State.Bel)"
     # Preserve the previous success/failure value for prompts that inspect it.
     if ($fakeExitCode -ne 0) { Write-Error "failure" -ea ignore }
     $result += $Global:__OrcaOsc133State.OriginalPrompt.Invoke()
-    $result += "\`e]133;B\`a"
+    $result += "$($Global:__OrcaOsc133State.Esc)]133;B$($Global:__OrcaOsc133State.Bel)"
     $result
 }
 
@@ -55,7 +57,7 @@ if ($Global:__OrcaOsc133State.HasPSReadLine -and
     $null -ne $Global:__OrcaOsc133State.OriginalReadLine) {
     function Global:PSConsoleHostReadLine {
         $commandLine = $Global:__OrcaOsc133State.OriginalReadLine.Invoke()
-        [Console]::Write("\`e]133;C\`a")
+        [Console]::Write("$($Global:__OrcaOsc133State.Esc)]133;C$($Global:__OrcaOsc133State.Bel)")
         return $commandLine
     }
 }
diff --git a/src/main/providers/ssh-filesystem-provider.test.ts b/src/main/providers/ssh-filesystem-provider.test.ts
index dca8cf06bc9..8fbf9551c00 100644
--- a/src/main/providers/ssh-filesystem-provider.test.ts
+++ b/src/main/providers/ssh-filesystem-provider.test.ts
@@ -1,3 +1,6 @@
+/* eslint-disable max-lines -- Why: SSH filesystem provider coverage keeps relay fallback,
+SFTP binary writes, watch fan-out, and provider lifecycle tests together so
+transport parity regressions are visible in one suite. */
 import { describe, expect, it, vi, beforeEach } from 'vitest'
 import { SshFilesystemProvider } from './ssh-filesystem-provider'
 
@@ -90,6 +93,64 @@ describe('SshFilesystemProvider', () => {
     })
   })
 
+  describe('writeFileBase64', () => {
+    it('writes decoded bytes through SFTP', async () => {
+      const written: Buffer[] = []
+      const writeStream = {
+        on: vi.fn((_event: string, _handler: (...args: unknown[]) => void) => writeStream),
+        end: vi.fn((buffer: Buffer) => {
+          written.push(buffer)
+          const closeHandler = writeStream.on.mock.calls.find(([event]) => event === 'close')?.[1]
+          closeHandler?.()
+        }),
+        destroy: vi.fn()
+      }
+      const sftp = {
+        createWriteStream: vi.fn(() => writeStream),
+        end: vi.fn()
+      }
+      provider = new SshFilesystemProvider('conn-1', mux as never, async () => sftp as never)
+
+      await provider.writeFileBase64('/home/user/logo.png', 'cG5n')
+
+      expect(sftp.createWriteStream).toHaveBeenCalledWith('/home/user/logo.png', { flags: 'wx' })
+      expect(written).toEqual([Buffer.from('png')])
+      expect(sftp.end).toHaveBeenCalled()
+      expect(mux.request).not.toHaveBeenCalledWith('fs.writeFile', expect.anything())
+    })
+
+    it('can append decoded chunks through SFTP', async () => {
+      const writeStream = {
+        on: vi.fn((_event: string, _handler: (...args: unknown[]) => void) => writeStream),
+        end: vi.fn((_buffer: Buffer) => {
+          const closeHandler = writeStream.on.mock.calls.find(([event]) => event === 'close')?.[1]
+          closeHandler?.()
+        }),
+        destroy: vi.fn()
+      }
+      const sftp = {
+        createWriteStream: vi.fn(() => writeStream),
+        end: vi.fn()
+      }
+      provider = new SshFilesystemProvider('conn-1', mux as never, async () => sftp as never)
+
+      await provider.writeFileBase64Chunk('/home/user/logo.png', 'cG5n', true)
+
+      expect(sftp.createWriteStream).toHaveBeenCalledWith('/home/user/logo.png', { flags: 'a' })
+      expect(sftp.end).toHaveBeenCalled()
+    })
+  })
+
+  describe('createDirNoClobber', () => {
+    it('sends fs.createDirNoClobber request', async () => {
+      await provider.createDirNoClobber('/home/user/new-dir')
+
+      expect(mux.request).toHaveBeenCalledWith('fs.createDirNoClobber', {
+        dirPath: '/home/user/new-dir'
+      })
+    })
+  })
+
   describe('stat', () => {
     it('sends fs.stat request', async () => {
       const statResult = { size: 1024, type: 'file', mtime: 1234567890 }
@@ -196,6 +257,112 @@ describe('SshFilesystemProvider', () => {
       expect(callback).toHaveBeenCalledWith(events)
     })
 
+    it('fans out same-root watch events and unwatches only after the last subscriber', async () => {
+      const first = vi.fn()
+      const second = vi.fn()
+      const unsubFirst = await provider.watch('/home/user/project', first)
+      const unsubSecond = await provider.watch('/home/user/project', second)
+
+      expect(mux.request).toHaveBeenCalledTimes(1)
+      expect(mux.request).toHaveBeenCalledWith('fs.watch', { rootPath: '/home/user/project' })
+
+      const notifHandler = mux.onNotification.mock.calls[0][0]
+      const events = [{ kind: 'update', absolutePath: '/home/user/project/file.ts' }]
+      notifHandler('fs.changed', { events })
+      expect(first).toHaveBeenCalledWith(events)
+      expect(second).toHaveBeenCalledWith(events)
+
+      unsubFirst()
+      expect(mux.notify).not.toHaveBeenCalledWith('fs.unwatch', { rootPath: '/home/user/project' })
+      notifHandler('fs.changed', { events })
+      expect(second).toHaveBeenCalledTimes(2)
+
+      unsubSecond()
+      expect(mux.notify).toHaveBeenCalledWith('fs.unwatch', { rootPath: '/home/user/project' })
+    })
+
+    it('shares an in-flight same-root watch setup across concurrent subscribers', async () => {
+      let resolveWatch: () => void = () => {}
+      mux.request.mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveWatch = resolve
+          })
+      )
+      const first = vi.fn()
+      const second = vi.fn()
+
+      const firstWatch = provider.watch('/home/user/project', first)
+      const secondWatch = provider.watch('/home/user/project', second)
+
+      expect(mux.request).toHaveBeenCalledTimes(1)
+      resolveWatch()
+      const [unsubFirst, unsubSecond] = await Promise.all([firstWatch, secondWatch])
+
+      const notifHandler = mux.onNotification.mock.calls[0][0]
+      const events = [{ kind: 'update', absolutePath: '/home/user/project/file.ts' }]
+      notifHandler('fs.changed', { events })
+      expect(first).toHaveBeenCalledWith(events)
+      expect(second).toHaveBeenCalledWith(events)
+
+      unsubFirst()
+      expect(mux.notify).not.toHaveBeenCalledWith('fs.unwatch', { rootPath: '/home/user/project' })
+      unsubSecond()
+      expect(mux.notify).toHaveBeenCalledWith('fs.unwatch', { rootPath: '/home/user/project' })
+    })
+
+    it('does not retain a watch listener when fs.watch setup fails', async () => {
+      mux.request.mockRejectedValueOnce(new Error('watch unavailable'))
+      const first = vi.fn()
+      await expect(provider.watch('/home/user/project', first)).rejects.toThrow('watch unavailable')
+
+      const second = vi.fn()
+      await provider.watch('/home/user/project', second)
+
+      const notifHandler = mux.onNotification.mock.calls[0][0]
+      const events = [{ kind: 'update', absolutePath: '/home/user/project/file.ts' }]
+      notifHandler('fs.changed', { events })
+      expect(first).not.toHaveBeenCalled()
+      expect(second).toHaveBeenCalledWith(events)
+    })
+
+    it('does not forward sibling paths with matching prefixes', async () => {
+      const callback = vi.fn()
+      await provider.watch('/home/user/project', callback)
+
+      const notifHandler = mux.onNotification.mock.calls[0][0]
+      notifHandler('fs.changed', {
+        events: [
+          { kind: 'update', absolutePath: '/home/user/project-old/file.ts' },
+          { kind: 'update', absolutePath: '/home/user/project2/file.ts' }
+        ]
+      })
+
+      expect(callback).not.toHaveBeenCalled()
+    })
+
+    it('matches Windows and UNC watch roots case-insensitively', async () => {
+      const driveCallback = vi.fn()
+      const uncCallback = vi.fn()
+      await provider.watch('C:\\Repo', driveCallback)
+      await provider.watch('//Server/Share/Repo', uncCallback)
+
+      const notifHandler = mux.onNotification.mock.calls[0][0]
+      notifHandler('fs.changed', {
+        events: [
+          { kind: 'update', absolutePath: 'c:\\repo\\src\\file.ts' },
+          { kind: 'update', absolutePath: '//server/share/repo/docs/readme.md' }
+        ]
+      })
+
+      expect(driveCallback).toHaveBeenCalledWith([
+        { kind: 'update', absolutePath: 'c:\\repo\\src\\file.ts' }
+      ])
+      expect(uncCallback).toHaveBeenCalledWith([
+        { kind: 'update', absolutePath: '//server/share/repo/docs/readme.md' }
+      ])
+    })
+
     it('sends fs.unwatch when last listener unsubscribes', async () => {
       const callback = vi.fn()
       const unsub = await provider.watch('/home/user/project', callback)
diff --git a/src/main/providers/ssh-filesystem-provider.ts b/src/main/providers/ssh-filesystem-provider.ts
index d0c545d6881..b33c0dbe08b 100644
--- a/src/main/providers/ssh-filesystem-provider.ts
+++ b/src/main/providers/ssh-filesystem-provider.ts
@@ -1,7 +1,16 @@
 import type { SshChannelMultiplexer } from '../ssh/ssh-channel-multiplexer'
 import { isMethodNotFoundError, readFileViaStream } from '../ssh/ssh-filesystem-stream-reader'
+import { uploadBuffer } from '../ssh/sftp-upload'
 import type { IFilesystemProvider, FileStat, FileReadResult } from './types'
 import type { DirEntry, FsChangeEvent, SearchOptions, SearchResult } from '../../shared/types'
+import { isPathInsideOrEqual } from '../../shared/cross-platform-path'
+import type { SFTPWrapper } from 'ssh2'
+
+type SftpFactory = () => Promise<SFTPWrapper>
+type WatchRegistration = {
+  callbacks: Set<(events: FsChangeEvent[]) => void>
+  setupPromise: Promise<void>
+}
 
 export class SshFilesystemProvider implements IFilesystemProvider {
   private connectionId: string
@@ -9,7 +18,7 @@ export class SshFilesystemProvider implements IFilesystemProvider {
   // Why: each watch() call registers for a specific rootPath, but the relay
   // sends all fs.changed events on one notification channel. Keying by rootPath
   // prevents cross-pollination between different worktree watchers.
-  private watchListeners = new Map<string, (events: FsChangeEvent[]) => void>()
+  private watchListeners = new Map<string, WatchRegistration>()
   // Why: store the unsubscribe handle so dispose() can detach from the
   // multiplexer. Without this, notification callbacks keep firing after
   // the provider is torn down on disconnect, routing events to stale state.
@@ -19,17 +28,23 @@ export class SshFilesystemProvider implements IFilesystemProvider {
   // relays get diagnosed quickly without per-read log spam.
   private loggedStreamFallback = false
 
-  constructor(connectionId: string, mux: SshChannelMultiplexer) {
+  constructor(
+    connectionId: string,
+    mux: SshChannelMultiplexer,
+    private readonly createSftp?: SftpFactory
+  ) {
     this.connectionId = connectionId
     this.mux = mux
 
     this.unsubscribeNotifications = mux.onNotification((method, params) => {
       if (method === 'fs.changed') {
         const events = params.events as FsChangeEvent[]
-        for (const [rootPath, cb] of this.watchListeners) {
-          const matching = events.filter((e) => e.absolutePath.startsWith(rootPath))
+        for (const [rootPath, registration] of this.watchListeners) {
+          const matching = events.filter((e) => isPathInsideOrEqual(rootPath, e.absolutePath))
           if (matching.length > 0) {
-            cb(matching)
+            for (const cb of registration.callbacks) {
+              cb(matching)
+            }
           }
         }
       }
@@ -78,6 +93,31 @@ export class SshFilesystemProvider implements IFilesystemProvider {
     await this.mux.request('fs.writeFile', { filePath, content })
   }
 
+  async writeFileBase64(filePath: string, contentBase64: string): Promise<void> {
+    await this.writeFileBase64Chunk(filePath, contentBase64, false)
+  }
+
+  async writeFileBase64Chunk(
+    filePath: string,
+    contentBase64: string,
+    append: boolean
+  ): Promise<void> {
+    if (!this.createSftp) {
+      throw new Error('remote_binary_upload_unavailable')
+    }
+    const sftp = await this.createSftp()
+    try {
+      // Why: relay fs.writeFile is text-only. SFTP writes the decoded bytes
+      // directly so runtime uploads do not corrupt images, PDFs, or archives.
+      await uploadBuffer(sftp, Buffer.from(contentBase64, 'base64'), filePath, {
+        append,
+        exclusive: !append
+      })
+    } finally {
+      sftp.end()
+    }
+  }
+
   async stat(filePath: string): Promise<FileStat> {
     return (await this.mux.request('fs.stat', { filePath })) as FileStat
   }
@@ -94,6 +134,10 @@ export class SshFilesystemProvider implements IFilesystemProvider {
     await this.mux.request('fs.createDir', { dirPath })
   }
 
+  async createDirNoClobber(dirPath: string): Promise<void> {
+    await this.mux.request('fs.createDirNoClobber', { dirPath })
+  }
+
   async rename(oldPath: string, newPath: string): Promise<void> {
     await this.mux.request('fs.rename', { oldPath, newPath })
   }
@@ -122,15 +166,41 @@ export class SshFilesystemProvider implements IFilesystemProvider {
   }
 
   async watch(rootPath: string, callback: (events: FsChangeEvent[]) => void): Promise<() => void> {
-    this.watchListeners.set(rootPath, callback)
-    await this.mux.request('fs.watch', { rootPath })
+    let registration = this.watchListeners.get(rootPath)
+    if (registration) {
+      registration.callbacks.add(callback)
+      await registration.setupPromise
+      return this.createWatchUnsubscribe(rootPath, registration, callback)
+    }
 
+    const callbacks = new Set<(events: FsChangeEvent[]) => void>([callback])
+    const setupPromise = this.mux.request('fs.watch', { rootPath }).then(
+      () => undefined,
+      (error) => {
+        if (this.watchListeners.get(rootPath) === registration) {
+          this.watchListeners.delete(rootPath)
+        }
+        throw error
+      }
+    )
+    registration = { callbacks, setupPromise }
+    this.watchListeners.set(rootPath, registration)
+    await setupPromise
+
+    return this.createWatchUnsubscribe(rootPath, registration, callback)
+  }
+
+  private createWatchUnsubscribe(
+    rootPath: string,
+    registration: WatchRegistration,
+    callback: (events: FsChangeEvent[]) => void
+  ): () => void {
     return () => {
-      this.watchListeners.delete(rootPath)
-      // Why: each watch() starts a @parcel/watcher on the relay for this specific
-      // rootPath. We must always notify the relay to stop it, not only when all
-      // watchers are gone — otherwise the remote watcher leaks inotify descriptors.
-      this.mux.notify('fs.unwatch', { rootPath })
+      registration.callbacks.delete(callback)
+      if (registration.callbacks.size === 0 && this.watchListeners.get(rootPath) === registration) {
+        this.watchListeners.delete(rootPath)
+        this.mux.notify('fs.unwatch', { rootPath })
+      }
     }
   }
 }
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 024026115eb..998c22b3f73 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -118,10 +118,13 @@ export type IFilesystemProvider = {
   readDir(dirPath: string): Promise<DirEntry[]>
   readFile(filePath: string): Promise<FileReadResult>
   writeFile(filePath: string, content: string): Promise<void>
+  writeFileBase64(filePath: string, contentBase64: string): Promise<void>
+  writeFileBase64Chunk(filePath: string, contentBase64: string, append: boolean): Promise<void>
   stat(filePath: string): Promise<FileStat>
   deletePath(targetPath: string, recursive?: boolean): Promise<void>
   createFile(filePath: string): Promise<void>
   createDir(dirPath: string): Promise<void>
+  createDirNoClobber(dirPath: string): Promise<void>
   rename(oldPath: string, newPath: string): Promise<void>
   copy(source: string, destination: string): Promise<void>
   realpath(filePath: string): Promise<string>
diff --git a/src/main/providers/windows-shell-args.test.ts b/src/main/providers/windows-shell-args.test.ts
index 0c18d639340..e04fd6ca5b4 100644
--- a/src/main/providers/windows-shell-args.test.ts
+++ b/src/main/providers/windows-shell-args.test.ts
@@ -41,8 +41,11 @@ describe('resolveWindowsShellLaunchArgs', () => {
     expect(opencodeRestoreIndex).toBeGreaterThan(outputEncodingIndex)
     expect(piRestoreIndex).toBeGreaterThan(outputEncodingIndex)
     expect(promptIndex).toBeGreaterThan(piRestoreIndex)
-    expect(command).toContain('`e]133;D;$fakeExitCode`a')
-    expect(command).toContain('`e]133;C`a')
+    expect(command).toContain('Esc = [char]27')
+    expect(command).toContain('Bel = [char]7')
+    expect(command).toContain(')]133;D;$fakeExitCode$(')
+    expect(command).toContain(')]133;C$(')
+    expect(command).not.toContain('`e]133')
   })
 
   it('handles pwsh.exe (PowerShell Core) the same as Windows PowerShell', () => {
diff --git a/src/main/repo-worktrees.ts b/src/main/repo-worktrees.ts
index 5ccb91123ba..2469c4810df 100644
--- a/src/main/repo-worktrees.ts
+++ b/src/main/repo-worktrees.ts
@@ -1,6 +1,7 @@
 import type { GitWorktreeInfo, Repo } from '../shared/types'
 import { listWorktrees } from './git/worktree'
 import { isFolderRepo } from '../shared/repo-kind'
+import { getSshGitProvider } from './providers/ssh-git-dispatch'
 
 export function createFolderWorktree(repo: Repo): GitWorktreeInfo {
   return {
@@ -19,5 +20,12 @@ export async function listRepoWorktrees(repo: Repo): Promise<GitWorktreeInfo[]>
   if (isFolderRepo(repo)) {
     return [createFolderWorktree(repo)]
   }
+  if (repo.connectionId) {
+    const provider = getSshGitProvider(repo.connectionId)
+    // Why: runtime worktree resolution can run before SSH providers have
+    // reattached during startup. Return empty instead of falling back to
+    // local git against a server path.
+    return provider ? await provider.listWorktrees(repo.path) : []
+  }
   return await listWorktrees(repo.path)
 }
diff --git a/src/main/runtime/device-registry.ts b/src/main/runtime/device-registry.ts
index c925bce2b9c..5a03d05a1c1 100644
--- a/src/main/runtime/device-registry.ts
+++ b/src/main/runtime/device-registry.ts
@@ -3,15 +3,19 @@
 // compromising one device doesn't expose others. The registry is a simple
 // JSON file with hardened permissions matching the runtime metadata pattern.
 import { randomBytes, randomUUID } from 'crypto'
-import { existsSync, readFileSync, writeFileSync, chmodSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
+import { hardenExistingSecureFile, writeSecureJsonFile } from '../../shared/secure-file'
 
 const DEVICE_REGISTRY_FILENAME = 'orca-devices.json'
 
+export type DeviceScope = 'mobile' | 'runtime'
+
 export type DeviceEntry = {
   deviceId: string
   name: string
   token: string
+  scope: DeviceScope
   pairedAt: number
   lastSeenAt: number
 }
@@ -25,11 +29,12 @@ export class DeviceRegistry {
     this.load()
   }
 
-  addDevice(name: string): DeviceEntry {
+  addDevice(name: string, scope: DeviceScope = 'mobile'): DeviceEntry {
     const entry: DeviceEntry = {
       deviceId: randomUUID(),
       name,
       token: randomBytes(24).toString('hex'),
+      scope,
       pairedAt: Date.now(),
       lastSeenAt: 0
     }
@@ -44,12 +49,12 @@ export class DeviceRegistry {
   // copy-button flow that encourages regeneration) leaves an orphaned token
   // forever. Returns an existing never-scanned entry if present; otherwise
   // mints a new one and drops any stale pending entries.
-  getOrCreatePendingDevice(name: string): DeviceEntry {
-    const existing = this.devices.find((d) => d.lastSeenAt === 0)
+  getOrCreatePendingDevice(name: string, scope: DeviceScope = 'mobile'): DeviceEntry {
+    const existing = this.devices.find((d) => d.lastSeenAt === 0 && d.scope === scope)
     if (existing) {
       return existing
     }
-    return this.addDevice(name)
+    return this.addDevice(name, scope)
   }
 
   // Why: explicit rotation path for "Regenerate QR" — invalidates any
@@ -58,9 +63,9 @@ export class DeviceRegistry {
   // this, getOrCreatePendingDevice keeps returning the same token forever
   // until a phone actually pairs, so users have no way to revoke a leaked
   // pre-pairing token.
-  rotatePendingDevice(name: string): DeviceEntry {
-    this.devices = this.devices.filter((d) => d.lastSeenAt !== 0)
-    return this.addDevice(name)
+  rotatePendingDevice(name: string, scope: DeviceScope = 'mobile'): DeviceEntry {
+    this.devices = this.devices.filter((d) => d.lastSeenAt !== 0 || d.scope !== scope)
+    return this.addDevice(name, scope)
   }
 
   removeDevice(deviceId: string): boolean {
@@ -73,6 +78,10 @@ export class DeviceRegistry {
     return false
   }
 
+  getDevice(deviceId: string): DeviceEntry | null {
+    return this.devices.find((d) => d.deviceId === deviceId) ?? null
+  }
+
   listDevices(): readonly DeviceEntry[] {
     return this.devices
   }
@@ -95,14 +104,20 @@ export class DeviceRegistry {
       return
     }
     try {
-      this.devices = JSON.parse(readFileSync(this.registryPath, 'utf-8')) as DeviceEntry[]
+      hardenExistingSecureFile(this.registryPath)
+      const parsed = JSON.parse(readFileSync(this.registryPath, 'utf-8')) as DeviceEntry[]
+      this.devices = parsed.map((device) => ({
+        ...device,
+        // Why: older registries only existed for phone pairing. Treat missing
+        // scope as mobile so legacy device tokens do not gain new CLI powers.
+        scope: device.scope === 'runtime' ? 'runtime' : 'mobile'
+      }))
     } catch {
       this.devices = []
     }
   }
 
   private save(): void {
-    writeFileSync(this.registryPath, JSON.stringify(this.devices, null, 2), { mode: 0o600 })
-    chmodSync(this.registryPath, 0o600)
+    writeSecureJsonFile(this.registryPath, this.devices)
   }
 }
diff --git a/src/main/runtime/e2ee-keypair.ts b/src/main/runtime/e2ee-keypair.ts
index de0373ebafe..eee61363191 100644
--- a/src/main/runtime/e2ee-keypair.ts
+++ b/src/main/runtime/e2ee-keypair.ts
@@ -1,9 +1,10 @@
 // Why: the E2EE keypair enables application-layer encryption between mobile
 // and desktop over plain ws://. The public key is embedded in the QR pairing
 // offer so the mobile client can derive a shared secret via ECDH.
-import { existsSync, readFileSync, writeFileSync, chmodSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import nacl from 'tweetnacl'
+import { hardenExistingSecureFile, writeSecureJsonFile } from '../../shared/secure-file'
 
 const KEYPAIR_FILENAME = 'orca-e2ee-keypair.json'
 const KEYPAIR_VERSION = 1
@@ -25,6 +26,7 @@ export function loadOrCreateE2EEKeypair(userDataPath: string): E2EEKeypair {
 
   if (existsSync(filePath)) {
     try {
+      hardenExistingSecureFile(filePath)
       const raw: KeypairFile = JSON.parse(readFileSync(filePath, 'utf-8'))
       if (raw.v === KEYPAIR_VERSION && raw.publicKeyB64 && raw.secretKeyB64) {
         const publicKey = Uint8Array.from(Buffer.from(raw.publicKeyB64, 'base64'))
@@ -43,8 +45,7 @@ export function loadOrCreateE2EEKeypair(userDataPath: string): E2EEKeypair {
   const secretKeyB64 = Buffer.from(keypair.secretKey).toString('base64')
 
   const data: KeypairFile = { v: KEYPAIR_VERSION, publicKeyB64, secretKeyB64 }
-  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8')
-  chmodSync(filePath, 0o600)
+  writeSecureJsonFile(filePath, data)
 
   return { publicKey: keypair.publicKey, secretKey: keypair.secretKey, publicKeyB64 }
 }
diff --git a/src/main/runtime/mobile-presence-lock.test.ts b/src/main/runtime/mobile-presence-lock.test.ts
index d3a84349f2c..e25fbe22674 100644
--- a/src/main/runtime/mobile-presence-lock.test.ts
+++ b/src/main/runtime/mobile-presence-lock.test.ts
@@ -295,6 +295,27 @@ describe('mobile presence lock — multi-mobile semantics', () => {
     expect(driverEvents.slice(before).every((e) => e.driver.kind === 'mobile')).toBe(true)
   })
 
+  it('updateDesktopViewport resizes the source PTY and records desktop geometry', async () => {
+    const { runtime, ptySizes, resizes } = createRuntime()
+
+    expect(await runtime.updateDesktopViewport('pty-1', { cols: 132, rows: 44 })).toBe(true)
+
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 132, rows: 44 })
+    expect(resizes.at(-1)).toEqual({ ptyId: 'pty-1', cols: 132, rows: 44 })
+    expect(runtime.getLastRendererSize('pty-1')).toEqual({ cols: 132, rows: 44 })
+  })
+
+  it('updateDesktopViewport does not resize while mobile is driving', async () => {
+    const { runtime, ptySizes, resizes } = createRuntime()
+    await runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 49, rows: 20 })
+    resizes.length = 0
+
+    expect(await runtime.updateDesktopViewport('pty-1', { cols: 132, rows: 44 })).toBe(false)
+
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 49, rows: 20 })
+    expect(resizes).toEqual([])
+  })
+
   it('updateMobileViewport then disconnect restores PTY to original baseline', async () => {
     const { runtime, ptySizes } = createRuntime()
     await runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 49, rows: 38 })
diff --git a/src/main/runtime/orca-runtime-browser.ts b/src/main/runtime/orca-runtime-browser.ts
new file mode 100644
index 00000000000..ea66e39da40
--- /dev/null
+++ b/src/main/runtime/orca-runtime-browser.ts
@@ -0,0 +1,1455 @@
+/* eslint-disable max-lines -- Why: this file is a command adapter for one external surface, Agent Browser automation. It stays separate from OrcaRuntimeService so runtime state does not grow further while browser routing remains easy to scan in one place. */
+import { randomUUID } from 'crypto'
+import { ipcMain, type BrowserWindow } from 'electron'
+import { getRepoIdFromWorktreeId } from '../../shared/worktree-id'
+import type {
+  BrowserBackResult,
+  BrowserCaptureStartResult,
+  BrowserCheckResult,
+  BrowserCaptureStopResult,
+  BrowserClearResult,
+  BrowserClickResult,
+  BrowserConsoleResult,
+  BrowserCookieDeleteResult,
+  BrowserCookieGetResult,
+  BrowserCookieSetResult,
+  BrowserDetectProfilesResult,
+  BrowserDragResult,
+  BrowserEvalResult,
+  BrowserFillResult,
+  BrowserFocusResult,
+  BrowserGeolocationResult,
+  BrowserGotoResult,
+  BrowserHoverResult,
+  BrowserInterceptDisableResult,
+  BrowserInterceptEnableResult,
+  BrowserKeypressResult,
+  BrowserNetworkLogResult,
+  BrowserPdfResult,
+  BrowserProfileClearDefaultCookiesResult,
+  BrowserProfileCreateResult,
+  BrowserProfileDeleteResult,
+  BrowserProfileImportFromBrowserResult,
+  BrowserProfileListResult,
+  BrowserReloadResult,
+  BrowserScreenshotResult,
+  BrowserScrollResult,
+  BrowserSelectAllResult,
+  BrowserSelectResult,
+  BrowserSnapshotResult,
+  BrowserTabCurrentResult,
+  BrowserTabListResult,
+  BrowserTabProfileCloneResult,
+  BrowserTabProfileShowResult,
+  BrowserTabSetProfileResult,
+  BrowserTabShowResult,
+  BrowserTabSwitchResult,
+  BrowserTypeResult,
+  BrowserUploadResult,
+  BrowserViewportResult,
+  BrowserWaitResult
+} from '../../shared/runtime-types'
+import type { AgentBrowserBridge } from '../browser/agent-browser-bridge'
+import { browserManager } from '../browser/browser-manager'
+import { BrowserError } from '../browser/cdp-bridge'
+import { browserSessionRegistry } from '../browser/browser-session-registry'
+import {
+  detectInstalledBrowsers,
+  importCookiesFromBrowser,
+  selectBrowserProfile
+} from '../browser/browser-cookie-import'
+import { waitForTabRegistration } from '../ipc/browser'
+
+export type BrowserCommandTargetParams = {
+  worktree?: string
+  page?: string
+}
+
+type ResolvedBrowserCommandTarget = {
+  worktreeId?: string
+  browserPageId?: string
+}
+
+export type RuntimeBrowserCommandHost = {
+  getAgentBrowserBridge(): AgentBrowserBridge | null
+  resolveWorktreeSelector(selector: string): Promise<{ id: string }>
+  getAuthoritativeWindow(): BrowserWindow
+  getAvailableAuthoritativeWindow(): BrowserWindow | null
+}
+
+export class RuntimeBrowserCommands {
+  constructor(private readonly host: RuntimeBrowserCommandHost) {}
+
+  private requireAgentBrowserBridge(): AgentBrowserBridge {
+    const bridge = this.host.getAgentBrowserBridge()
+    if (!bridge) {
+      throw new BrowserError('browser_no_tab', 'No browser session is active')
+    }
+    return bridge
+  }
+
+  // Why: the CLI sends worktree selectors (e.g. "path:/Users/...") but the
+  // bridge stores worktreeIds in "repoId::path" format (from the renderer's
+  // Zustand store). This helper resolves the selector to the store-compatible
+  // ID so the bridge can filter tabs correctly.
+  private async resolveBrowserWorktreeId(selector?: string): Promise<string | undefined> {
+    if (!selector) {
+      // Why: after app restart, webviews only mount when the browser pane is visible.
+      // Without --worktree, we still need to activate the view so persisted tabs
+      // become operable via registerGuest.
+      const bridge = this.host.getAgentBrowserBridge()
+      if (bridge && bridge.getRegisteredTabs().size === 0) {
+        try {
+          const win = this.host.getAuthoritativeWindow()
+          win.webContents.send('browser:activateView', {})
+          await new Promise((resolve) => setTimeout(resolve, 500))
+        } catch {
+          // Window may not exist yet (e.g. during startup or in tests)
+        }
+      }
+      return undefined
+    }
+
+    const worktreeId = (await this.host.resolveWorktreeSelector(selector)).id
+    // Why: explicit worktree selectors are user intent, so resolution errors
+    // must surface instead of silently widening browser routing scope. Only the
+    // activation step remains best-effort because missing windows during tests
+    // or startup should not erase the validated worktree target itself.
+    const bridge = this.host.getAgentBrowserBridge()
+    if (bridge && bridge.getRegisteredTabs(worktreeId).size === 0) {
+      try {
+        await this.ensureBrowserWorktreeActive(worktreeId)
+      } catch {
+        // Fall through with the validated worktree id so downstream routing
+        // still stays scoped to the caller's explicit selector.
+      }
+    }
+    return worktreeId
+  }
+
+  private async resolveBrowserCommandTarget(
+    params: BrowserCommandTargetParams
+  ): Promise<ResolvedBrowserCommandTarget> {
+    const browserPageId =
+      typeof params.page === 'string' && params.page.length > 0 ? params.page : undefined
+    if (!browserPageId) {
+      return {
+        worktreeId: await this.resolveBrowserWorktreeId(params.worktree)
+      }
+    }
+
+    return {
+      // Why: explicit browserPageId is already a stable tab identity, so we do
+      // not auto-resolve cwd worktree scoping on top of it. Only honor an
+      // explicit --worktree when the caller asked for that extra validation.
+      worktreeId: params.worktree
+        ? await this.resolveBrowserWorktreeId(params.worktree)
+        : undefined,
+      browserPageId
+    }
+  }
+
+  // Why: browser tabs only mount (and become operable) when their worktree is
+  // the active worktree in the renderer AND activeTabType is 'browser'. If either
+  // condition is false, the webview stays in display:none and Electron won't start
+  // its guest process — dom-ready never fires, registerGuest never runs, and CLI
+  // browser commands fail with "CDP connection refused".
+  private async ensureBrowserWorktreeActive(worktreeId: string): Promise<void> {
+    const win = this.host.getAuthoritativeWindow()
+    const repoId = getRepoIdFromWorktreeId(worktreeId)
+    if (!repoId) {
+      return
+    }
+    win.webContents.send('ui:activateWorktree', { repoId, worktreeId })
+    // Why: switching worktree alone sets activeView='terminal'. Browser webviews
+    // won't mount until activeTabType is 'browser'. Send a second IPC to flip it.
+    win.webContents.send('browser:activateView', { worktreeId })
+    // Why: give the renderer time to mount the webview after switching worktrees.
+    // The webview needs to attach and fire dom-ready before registerGuest runs.
+    await new Promise((resolve) => setTimeout(resolve, 500))
+  }
+
+  // Why: agent-browser drives navigation via CDP, which bypasses Electron's
+  // webview event system. The renderer's did-navigate / page-title-updated
+  // listeners never fire, leaving the Zustand store (and thus the Orca UI's
+  // address bar and tab title) stale. Push updates from main → renderer after
+  // any navigation-causing command so the UI stays in sync.
+  private notifyRendererNavigation(browserPageId: string, url: string, title: string): void {
+    try {
+      const win = this.host.getAuthoritativeWindow()
+      win.webContents.send('browser:navigation-update', { browserPageId, url, title })
+    } catch {
+      // Window may not exist during shutdown
+    }
+  }
+
+  // Why: `tabSwitch` only flips the bridge's `activeWebContentsId` — it
+  // does not surface the browser pane in the renderer. Without --focus, the
+  // switch is invisible to the user. With --focus, we send a dedicated IPC
+  // so the renderer can update its per-worktree active-tab state.
+  //
+  // Why this IPC carries `worktreeId` instead of letting the renderer
+  // dispatch `setActiveWorktree`: multiple agents drive browsers in parallel
+  // worktrees. A global focus call from agent X would steal the user's
+  // screen from agent Y's worktree. The renderer-side handler
+  // (focusBrowserTabInWorktree) updates per-worktree state unconditionally
+  // and only flips globals when the user is already on the targeted
+  // worktree. Cross-worktree --focus calls pre-stage silently.
+  private notifyRendererBrowserPaneFocus(
+    worktreeId: string | undefined,
+    browserPageId: string
+  ): void {
+    try {
+      const win = this.host.getAuthoritativeWindow()
+      win.webContents.send('browser:pane-focus', {
+        worktreeId: worktreeId ?? null,
+        browserPageId
+      })
+    } catch {
+      // Window may not exist during shutdown
+    }
+  }
+
+  async browserSnapshot(params: BrowserCommandTargetParams): Promise<BrowserSnapshotResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().snapshot(target.worktreeId, target.browserPageId)
+  }
+
+  async browserClick(
+    params: { element: string } & BrowserCommandTargetParams
+  ): Promise<BrowserClickResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const bridge = this.requireAgentBrowserBridge()
+    const result = await bridge.click(params.element, target.worktreeId, target.browserPageId)
+    // Why: clicks can trigger navigation (e.g. submitting a form, clicking a link).
+    // Read the target tab's live URL/title after the click and push to the
+    // renderer so the UI updates even when automation targeted a non-active page.
+    const page = bridge.getPageInfo(target.worktreeId, target.browserPageId)
+    if (page) {
+      this.notifyRendererNavigation(page.browserPageId, page.url, page.title)
+    }
+    return result
+  }
+
+  async browserGoto(
+    params: { url: string } & BrowserCommandTargetParams
+  ): Promise<BrowserGotoResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const bridge = this.requireAgentBrowserBridge()
+    const result = await bridge.goto(params.url, target.worktreeId, target.browserPageId)
+    const pageId = bridge.getActivePageId(target.worktreeId, target.browserPageId)
+    if (pageId) {
+      this.notifyRendererNavigation(pageId, result.url, result.title)
+    }
+    return result
+  }
+
+  async browserFill(
+    params: {
+      element: string
+      value: string
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserFillResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().fill(
+      params.element,
+      params.value,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserType(
+    params: { input: string } & BrowserCommandTargetParams
+  ): Promise<BrowserTypeResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().type(
+      params.input,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserSelect(
+    params: {
+      element: string
+      value: string
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserSelectResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().select(
+      params.element,
+      params.value,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserScroll(
+    params: { direction: 'up' | 'down'; amount?: number } & BrowserCommandTargetParams
+  ): Promise<BrowserScrollResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().scroll(
+      params.direction,
+      params.amount,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserBack(params: BrowserCommandTargetParams): Promise<BrowserBackResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const bridge = this.requireAgentBrowserBridge()
+    const result = await bridge.back(target.worktreeId, target.browserPageId)
+    const pageId = bridge.getActivePageId(target.worktreeId, target.browserPageId)
+    if (pageId) {
+      this.notifyRendererNavigation(pageId, result.url, result.title)
+    }
+    return result
+  }
+
+  async browserReload(params: BrowserCommandTargetParams): Promise<BrowserReloadResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const bridge = this.requireAgentBrowserBridge()
+    const result = await bridge.reload(target.worktreeId, target.browserPageId)
+    const pageId = bridge.getActivePageId(target.worktreeId, target.browserPageId)
+    if (pageId) {
+      this.notifyRendererNavigation(pageId, result.url, result.title)
+    }
+    return result
+  }
+
+  async browserScreenshot(
+    params: {
+      format?: 'png' | 'jpeg'
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserScreenshotResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().screenshot(
+      params.format,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserEval(
+    params: { expression: string } & BrowserCommandTargetParams
+  ): Promise<BrowserEvalResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().evaluate(
+      params.expression,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserTabList(params: { worktree?: string }): Promise<BrowserTabListResult> {
+    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
+    const result = this.requireAgentBrowserBridge().tabList(worktreeId)
+    return {
+      tabs: result.tabs.map((tab) => this.enrichBrowserTabInfo(tab))
+    }
+  }
+
+  async browserTabShow(params: { page: string; worktree?: string }): Promise<BrowserTabShowResult> {
+    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
+    return { tab: this.describeBrowserTab(params.page, worktreeId) }
+  }
+
+  async browserTabCurrent(params: { worktree?: string }): Promise<BrowserTabCurrentResult> {
+    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
+    const browserPageId = this.requireAgentBrowserBridge().getActivePageId(worktreeId)
+    if (!browserPageId) {
+      throw new BrowserError('browser_no_tab', 'No browser tab open in this worktree')
+    }
+    return { tab: this.describeBrowserTab(browserPageId, worktreeId) }
+  }
+
+  async browserTabSwitch(
+    params: {
+      index?: number
+      focus?: boolean
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserTabSwitchResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const bridge = this.requireAgentBrowserBridge()
+    const result = await bridge.tabSwitch(params.index, target.worktreeId, target.browserPageId)
+    if (params.focus) {
+      // Why: prefer the explicit --worktree the caller passed; fall back to
+      // the bridge's owning-worktree map for the just-switched tab. The
+      // owning worktree is what the renderer needs to scope the focus to.
+      // The renderer NEVER yanks the user across worktrees on this signal
+      // (see focusBrowserTabInWorktree).
+      const worktreeId =
+        target.worktreeId ?? browserManager.getWorktreeIdForTab(result.browserPageId) ?? undefined
+      this.notifyRendererBrowserPaneFocus(worktreeId, result.browserPageId)
+    }
+    return result
+  }
+
+  async browserHover(
+    params: { element: string } & BrowserCommandTargetParams
+  ): Promise<BrowserHoverResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().hover(
+      params.element,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserDrag(
+    params: {
+      from: string
+      to: string
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserDragResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().drag(
+      params.from,
+      params.to,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserUpload(
+    params: { element: string; files: string[] } & BrowserCommandTargetParams
+  ): Promise<BrowserUploadResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().upload(
+      params.element,
+      params.files,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserWait(
+    params: {
+      selector?: string
+      timeout?: number
+      text?: string
+      url?: string
+      load?: string
+      fn?: string
+      state?: string
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserWaitResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const { worktree: _, page: __, ...options } = params
+    return this.requireAgentBrowserBridge().wait(options, target.worktreeId, target.browserPageId)
+  }
+
+  async browserCheck(
+    params: { element: string; checked: boolean } & BrowserCommandTargetParams
+  ): Promise<BrowserCheckResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().check(
+      params.element,
+      params.checked,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserFocus(
+    params: { element: string } & BrowserCommandTargetParams
+  ): Promise<BrowserFocusResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().focus(
+      params.element,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserClear(
+    params: { element: string } & BrowserCommandTargetParams
+  ): Promise<BrowserClearResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().clear(
+      params.element,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserSelectAll(
+    params: { element: string } & BrowserCommandTargetParams
+  ): Promise<BrowserSelectAllResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().selectAll(
+      params.element,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserKeypress(
+    params: { key: string } & BrowserCommandTargetParams
+  ): Promise<BrowserKeypressResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().keypress(
+      params.key,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserPdf(params: BrowserCommandTargetParams): Promise<BrowserPdfResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().pdf(target.worktreeId, target.browserPageId)
+  }
+
+  async browserFullScreenshot(
+    params: {
+      format?: 'png' | 'jpeg'
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserScreenshotResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().fullPageScreenshot(
+      params.format,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Cookie management ──
+
+  async browserCookieGet(
+    params: { url?: string } & BrowserCommandTargetParams
+  ): Promise<BrowserCookieGetResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().cookieGet(
+      params.url,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserCookieSet(
+    params: {
+      name: string
+      value: string
+      domain?: string
+      path?: string
+      secure?: boolean
+      httpOnly?: boolean
+      sameSite?: string
+      expires?: number
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserCookieSetResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().cookieSet(
+      params,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserCookieDelete(
+    params: {
+      name: string
+      domain?: string
+      url?: string
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserCookieDeleteResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().cookieDelete(
+      params.name,
+      params.domain,
+      params.url,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Viewport ──
+
+  async browserSetViewport(
+    params: {
+      width: number
+      height: number
+      deviceScaleFactor?: number
+      mobile?: boolean
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserViewportResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().setViewport(
+      params.width,
+      params.height,
+      params.deviceScaleFactor,
+      params.mobile,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Geolocation ──
+
+  async browserSetGeolocation(
+    params: {
+      latitude: number
+      longitude: number
+      accuracy?: number
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserGeolocationResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().setGeolocation(
+      params.latitude,
+      params.longitude,
+      params.accuracy,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Request interception ──
+
+  async browserInterceptEnable(
+    params: {
+      patterns?: string[]
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserInterceptEnableResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().interceptEnable(
+      params.patterns,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserInterceptDisable(
+    params: BrowserCommandTargetParams
+  ): Promise<BrowserInterceptDisableResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().interceptDisable(
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserInterceptList(params: BrowserCommandTargetParams): Promise<{ requests: unknown[] }> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().interceptList(target.worktreeId, target.browserPageId)
+  }
+
+  // ── Console/network capture ──
+
+  async browserCaptureStart(
+    params: BrowserCommandTargetParams
+  ): Promise<BrowserCaptureStartResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().captureStart(target.worktreeId, target.browserPageId)
+  }
+
+  async browserCaptureStop(params: BrowserCommandTargetParams): Promise<BrowserCaptureStopResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().captureStop(target.worktreeId, target.browserPageId)
+  }
+
+  async browserConsoleLog(
+    params: { limit?: number } & BrowserCommandTargetParams
+  ): Promise<BrowserConsoleResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().consoleLog(
+      params.limit,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserNetworkLog(
+    params: { limit?: number } & BrowserCommandTargetParams
+  ): Promise<BrowserNetworkLogResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().networkLog(
+      params.limit,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Additional core commands ──
+
+  async browserDblclick(
+    params: { element: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().dblclick(
+      params.element,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserForward(params: BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().forward(target.worktreeId, target.browserPageId)
+  }
+
+  async browserScrollIntoView(
+    params: { element: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().scrollIntoView(
+      params.element,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserGet(
+    params: {
+      what: string
+      selector?: string
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().get(
+      params.what,
+      params.selector,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserIs(
+    params: { what: string; selector: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().is(
+      params.what,
+      params.selector,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Keyboard insert text ──
+
+  async browserKeyboardInsertText(
+    params: { text: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().keyboardInsertText(
+      params.text,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Mouse commands ──
+
+  async browserMouseMove(
+    params: { x: number; y: number } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().mouseMove(
+      params.x,
+      params.y,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserMouseDown(
+    params: { button?: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().mouseDown(
+      params.button,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserMouseUp(params: { button?: string } & BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().mouseUp(
+      params.button,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserMouseWheel(
+    params: {
+      dy: number
+      dx?: number
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().mouseWheel(
+      params.dy,
+      params.dx,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Find (semantic locators) ──
+
+  async browserFind(
+    params: {
+      locator: string
+      value: string
+      action: string
+      text?: string
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().find(
+      params.locator,
+      params.value,
+      params.action,
+      params.text,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Set commands ──
+
+  async browserSetDevice(params: { name: string } & BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().setDevice(
+      params.name,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserSetOffline(
+    params: { state?: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().setOffline(
+      params.state,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserSetHeaders(
+    params: { headers: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().setHeaders(
+      params.headers,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserSetCredentials(
+    params: {
+      user: string
+      pass: string
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().setCredentials(
+      params.user,
+      params.pass,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserSetMedia(
+    params: {
+      colorScheme?: string
+      reducedMotion?: string
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().setMedia(
+      params.colorScheme,
+      params.reducedMotion,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Clipboard commands ──
+
+  async browserClipboardRead(params: BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().clipboardRead(target.worktreeId, target.browserPageId)
+  }
+
+  async browserClipboardWrite(
+    params: { text: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().clipboardWrite(
+      params.text,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Dialog commands ──
+
+  async browserDialogAccept(
+    params: { text?: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().dialogAccept(
+      params.text,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserDialogDismiss(params: BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().dialogDismiss(target.worktreeId, target.browserPageId)
+  }
+
+  // ── Storage commands ──
+
+  async browserStorageLocalGet(
+    params: { key: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().storageLocalGet(
+      params.key,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserStorageLocalSet(
+    params: {
+      key: string
+      value: string
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().storageLocalSet(
+      params.key,
+      params.value,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserStorageLocalClear(params: BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().storageLocalClear(
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserStorageSessionGet(
+    params: { key: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().storageSessionGet(
+      params.key,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserStorageSessionSet(
+    params: {
+      key: string
+      value: string
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().storageSessionSet(
+      params.key,
+      params.value,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserStorageSessionClear(params: BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().storageSessionClear(
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Download command ──
+
+  async browserDownload(
+    params: {
+      selector: string
+      path: string
+    } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().download(
+      params.selector,
+      params.path,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── Highlight command ──
+
+  async browserHighlight(
+    params: { selector: string } & BrowserCommandTargetParams
+  ): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().highlight(
+      params.selector,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  // ── New: exec passthrough + tab lifecycle ──
+
+  async browserExec(params: { command: string } & BrowserCommandTargetParams): Promise<unknown> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    return this.requireAgentBrowserBridge().exec(
+      params.command,
+      target.worktreeId,
+      target.browserPageId
+    )
+  }
+
+  async browserTabCreate(params: {
+    url?: string
+    worktree?: string
+    profileId?: string
+  }): Promise<{ browserPageId: string }> {
+    const url = params.url ?? 'about:blank'
+    const worktreeId = params.worktree
+      ? (await this.host.resolveWorktreeSelector(params.worktree)).id
+      : undefined
+    if (!this.host.getAvailableAuthoritativeWindow()) {
+      throw new BrowserError(
+        'browser_error',
+        'Browser tab creation requires a desktop renderer; headless orca serve does not support browser panes yet.'
+      )
+    }
+    const { browserPageId } = await this.createBrowserTabInRenderer(
+      url,
+      worktreeId,
+      params.profileId
+    )
+
+    // Why: the renderer creates the Zustand tab immediately, but the webview must
+    // mount and fire dom-ready before registerGuest runs. Waiting here ensures the
+    // tab is operable by subsequent CLI commands (snapshot, click, etc.).
+    // If registration doesn't complete within timeout, return the ID anyway — the
+    // tab exists in the UI but may not be ready for automation commands yet.
+    try {
+      await waitForTabRegistration(browserPageId)
+    } catch {
+      // Tab was created in the renderer but the webview hasn't finished mounting.
+      // Return success since the tab exists; subsequent commands will fail with a
+      // clear "tab not available" error if the webview never loads.
+    }
+
+    // Why: newly created tabs should be auto-activated so subsequent commands
+    // (snapshot, click, goto) target the new tab without requiring an explicit
+    // tab switch. Without this, the bridge's active tab still points at the
+    // previously active tab and the new tab shows active: false in tab list.
+    const bridge = this.requireAgentBrowserBridge()
+    const wcId = bridge.getRegisteredTabs(worktreeId).get(browserPageId)
+    if (wcId != null) {
+      bridge.setActiveTab(wcId, worktreeId)
+    }
+
+    // Why: the renderer sets webview.src=url on mount, but agent-browser connects
+    // via CDP after the webview loads about:blank. Without an explicit goto, the
+    // page stays blank from agent-browser's perspective. Navigate via the bridge
+    // so agent-browser's CDP session tracks the correct page state.
+    if (url && url !== 'about:blank') {
+      try {
+        const result = await bridge.goto(url, worktreeId, browserPageId)
+        this.notifyRendererNavigation(browserPageId, result.url, result.title)
+      } catch {
+        // Tab exists but navigation failed — caller can retry with explicit goto
+      }
+    }
+
+    return { browserPageId }
+  }
+
+  async browserTabSetProfile(
+    params: {
+      profileId: string
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserTabSetProfileResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const browserPageId =
+      target.browserPageId ?? this.requireAgentBrowserBridge().getActivePageId(target.worktreeId)
+    if (!browserPageId) {
+      throw new BrowserError('browser_no_tab', 'No browser tab open in this worktree')
+    }
+    // Why: 'default' is a synthetic id; fall back to the registry's default profile when not registered.
+    const profile =
+      browserSessionRegistry.getProfile(params.profileId) ??
+      (params.profileId === 'default' ? browserSessionRegistry.getDefaultProfile() : null)
+    if (!profile) {
+      throw new BrowserError(
+        'invalid_argument',
+        `Browser profile ${params.profileId} was not found`
+      )
+    }
+
+    // Why: short-circuit no-op switches so the renderer doesn't tear down and
+    // remount the webview when the tab is already on the requested profile.
+    const currentProfileId = browserManager.getSessionProfileIdForTab(browserPageId) ?? 'default'
+    if (currentProfileId === profile.id) {
+      return {
+        browserPageId,
+        profileId: profile.id,
+        profileLabel: profile.label
+      }
+    }
+
+    const win = this.host.getAuthoritativeWindow()
+    const requestId = randomUUID()
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        ipcMain.removeListener('browser:tabSetProfileReply', handler)
+        reject(new Error('Tab profile update timed out'))
+      }, 10_000)
+
+      const handler = (
+        _event: Electron.IpcMainEvent,
+        reply: { requestId: string; error?: string }
+      ): void => {
+        if (reply.requestId !== requestId) {
+          return
+        }
+        clearTimeout(timer)
+        ipcMain.removeListener('browser:tabSetProfileReply', handler)
+        if (reply.error) {
+          reject(new Error(reply.error))
+        } else {
+          resolve()
+        }
+      }
+      ipcMain.on('browser:tabSetProfileReply', handler)
+      win.webContents.send('browser:requestTabSetProfile', {
+        requestId,
+        browserPageId,
+        profileId: profile.id
+      })
+    })
+
+    // Why: the renderer destroys the old webview and remounts on the new
+    // partition. Wait for the re-register so a follow-up tab list
+    // --show-profile reads the updated sessionProfileId from BrowserManager
+    // instead of stale data, and so subsequent CLI ops (snapshot, click, etc.)
+    // hit a guest that's already attached.
+    try {
+      await waitForTabRegistration(browserPageId)
+    } catch {
+      // Best-effort: re-register won't fire if the worktree is hidden. The
+      // store already reflects the new profile; downstream commands retry
+      // once the pane re-mounts.
+    }
+
+    return {
+      browserPageId,
+      profileId: profile.id,
+      profileLabel: profile.label
+    }
+  }
+
+  async browserTabProfileShow(params: {
+    page: string
+    worktree?: string
+  }): Promise<BrowserTabProfileShowResult> {
+    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
+    const tab = this.describeBrowserTab(params.page, worktreeId)
+    return {
+      browserPageId: tab.browserPageId,
+      worktreeId: tab.worktreeId ?? null,
+      profileId: tab.profileId ?? null,
+      profileLabel: tab.profileLabel ?? null
+    }
+  }
+
+  async browserTabProfileClone(
+    params: {
+      profileId: string
+    } & BrowserCommandTargetParams
+  ): Promise<BrowserTabProfileCloneResult> {
+    const target = await this.resolveBrowserCommandTarget(params)
+    const sourceBrowserPageId =
+      target.browserPageId ?? this.requireAgentBrowserBridge().getActivePageId(target.worktreeId)
+    if (!sourceBrowserPageId) {
+      throw new BrowserError('browser_no_tab', 'No browser tab open in this worktree')
+    }
+    const sourceTab = this.describeBrowserTab(sourceBrowserPageId, target.worktreeId)
+    const profile = browserSessionRegistry.getProfile(params.profileId)
+    if (!profile) {
+      throw new BrowserError(
+        'invalid_argument',
+        `Browser profile ${params.profileId} was not found`
+      )
+    }
+    const created = await this.createBrowserTabInRenderer(
+      sourceTab.url,
+      sourceTab.worktreeId ?? target.worktreeId,
+      profile.id
+    )
+    // Why: parity with browserTabCreate. Wait for the cloned tab's webview to
+    // register so the returned browserPageId is operable by the next CLI call.
+    try {
+      await waitForTabRegistration(created.browserPageId)
+    } catch {
+      // Best-effort: registration may not fire if the worktree is hidden.
+    }
+    return {
+      browserPageId: created.browserPageId,
+      sourceBrowserPageId,
+      profileId: profile.id,
+      profileLabel: profile.label
+    }
+  }
+
+  async browserProfileList(): Promise<BrowserProfileListResult> {
+    return { profiles: browserSessionRegistry.listProfiles() }
+  }
+
+  async browserProfileCreate(params: {
+    label: string
+    scope: 'isolated' | 'imported'
+  }): Promise<BrowserProfileCreateResult> {
+    return {
+      profile: browserSessionRegistry.createProfile(params.scope, params.label)
+    }
+  }
+
+  async browserProfileDelete(params: { profileId: string }): Promise<BrowserProfileDeleteResult> {
+    return {
+      deleted: await browserSessionRegistry.deleteProfile(params.profileId),
+      profileId: params.profileId
+    }
+  }
+
+  async browserProfileDetectBrowsers(): Promise<BrowserDetectProfilesResult> {
+    return {
+      // Why: clients only need display metadata for the picker; filesystem
+      // paths and keychain identifiers stay on the runtime server.
+      browsers: detectInstalledBrowsers().map((browser) => ({
+        family: browser.family,
+        label: browser.label,
+        profiles: browser.profiles,
+        selectedProfile: browser.selectedProfile
+      }))
+    }
+  }
+
+  async browserProfileImportFromBrowser(params: {
+    profileId: string
+    browserFamily: string
+    browserProfile?: string
+  }): Promise<BrowserProfileImportFromBrowserResult> {
+    const profile = browserSessionRegistry.getProfile(params.profileId)
+    if (!profile) {
+      return { ok: false, reason: 'Session profile not found.' }
+    }
+    if (
+      params.browserProfile &&
+      (/[/\\]/.test(params.browserProfile) || params.browserProfile.includes('..'))
+    ) {
+      return { ok: false, reason: 'Invalid browser profile name.' }
+    }
+
+    const browsers = detectInstalledBrowsers()
+    let browser = browsers.find((candidate) => candidate.family === params.browserFamily)
+    if (!browser) {
+      return { ok: false, reason: 'Browser not found on this system.' }
+    }
+
+    if (params.browserProfile && params.browserProfile !== browser.selectedProfile) {
+      const reselected = selectBrowserProfile(browser, params.browserProfile)
+      if (!reselected) {
+        return {
+          ok: false,
+          reason: `No cookies database found for profile "${params.browserProfile}".`
+        }
+      }
+      browser = reselected
+    }
+
+    const result = await importCookiesFromBrowser(browser, profile.partition)
+    if (!result.ok) {
+      return result
+    }
+
+    const profileName =
+      browser.profiles.find((candidate) => candidate.directory === browser.selectedProfile)?.name ??
+      browser.selectedProfile
+    browserSessionRegistry.updateProfileSource(params.profileId, {
+      browserFamily: browser.family,
+      profileName,
+      importedAt: Date.now()
+    })
+    return { ...result, profileId: params.profileId }
+  }
+
+  async browserProfileClearDefaultCookies(): Promise<BrowserProfileClearDefaultCookiesResult> {
+    return { cleared: await browserSessionRegistry.clearDefaultSessionCookies() }
+  }
+
+  async browserTabClose(params: {
+    index?: number
+    page?: string
+    worktree?: string
+  }): Promise<{ closed: boolean }> {
+    const bridge = this.requireAgentBrowserBridge()
+    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
+
+    let tabId: string | null = null
+    if (typeof params.page === 'string' && params.page.length > 0) {
+      if (!bridge.getRegisteredTabs(worktreeId).has(params.page)) {
+        const scope = worktreeId ? ' in this worktree' : ''
+        throw new BrowserError(
+          'browser_tab_not_found',
+          `Browser page ${params.page} was not found${scope}`
+        )
+      }
+      tabId = params.page
+    } else if (params.index !== undefined) {
+      const tabs = bridge.getRegisteredTabs(worktreeId)
+      const entries = [...tabs.entries()]
+      if (params.index < 0 || params.index >= entries.length) {
+        throw new Error(`Tab index ${params.index} out of range (0-${entries.length - 1})`)
+      }
+      tabId = entries[params.index][0]
+    } else {
+      // Why: try the bridge first (registered tabs with webviews), then fall back
+      // to asking the renderer to close its active browser tab (handles cases where
+      // the webview hasn't mounted yet, e.g. tab was just created).
+      const tabs = bridge.getRegisteredTabs(worktreeId)
+      const entries = [...tabs.entries()]
+      const activeEntry = entries.find(([, wcId]) => wcId === bridge.getActiveWebContentsId())
+      if (activeEntry) {
+        tabId = activeEntry[0]
+      }
+    }
+
+    const win = this.host.getAuthoritativeWindow()
+    const requestId = randomUUID()
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        ipcMain.removeListener('browser:tabCloseReply', handler)
+        reject(new Error('Tab close timed out'))
+      }, 10_000)
+
+      const handler = (
+        _event: Electron.IpcMainEvent,
+        reply: { requestId: string; error?: string }
+      ): void => {
+        if (reply.requestId !== requestId) {
+          return
+        }
+        clearTimeout(timer)
+        ipcMain.removeListener('browser:tabCloseReply', handler)
+        if (reply.error) {
+          reject(new Error(reply.error))
+        } else {
+          resolve()
+        }
+      }
+      ipcMain.on('browser:tabCloseReply', handler)
+      // Why: when main cannot resolve a concrete tab id itself (for example if a
+      // browser workspace exists in the renderer before its guest mounts), the
+      // renderer still needs the intended worktree scope. Otherwise it falls
+      // back to the globally active browser tab and can close a tab in the
+      // wrong worktree.
+      win.webContents.send('browser:requestTabClose', { requestId, tabId, worktreeId })
+    })
+
+    return { closed: true }
+  }
+
+  private enrichBrowserTabInfo(
+    tab: BrowserTabListResult['tabs'][number]
+  ): BrowserTabListResult['tabs'][number] {
+    const rawProfileId = browserManager.getSessionProfileIdForTab(tab.browserPageId)
+    const profile =
+      browserSessionRegistry.getProfile(rawProfileId ?? 'default') ??
+      browserSessionRegistry.getDefaultProfile()
+    return {
+      ...tab,
+      worktreeId: browserManager.getWorktreeIdForTab(tab.browserPageId) ?? null,
+      profileId: profile.id,
+      profileLabel: profile.label
+    }
+  }
+
+  private describeBrowserTab(
+    browserPageId: string,
+    explicitWorktreeId?: string
+  ): BrowserTabListResult['tabs'][number] {
+    const worktreeId = explicitWorktreeId ?? browserManager.getWorktreeIdForTab(browserPageId)
+    const tab = this.requireAgentBrowserBridge()
+      .tabList(worktreeId)
+      .tabs.find((entry) => entry.browserPageId === browserPageId)
+    if (!tab) {
+      const scope = worktreeId ? ' in this worktree' : ''
+      throw new BrowserError(
+        'browser_tab_not_found',
+        `Browser page ${browserPageId} was not found${scope}`
+      )
+    }
+    return this.enrichBrowserTabInfo(tab)
+  }
+
+  private async createBrowserTabInRenderer(
+    url: string,
+    worktreeId?: string,
+    profileId?: string
+  ): Promise<{ browserPageId: string }> {
+    const win = this.host.getAuthoritativeWindow()
+    const requestId = randomUUID()
+
+    if (worktreeId) {
+      await this.ensureBrowserWorktreeActive(worktreeId)
+    }
+
+    const browserPageId = await new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        ipcMain.removeListener('browser:tabCreateReply', handler)
+        reject(new Error('Tab creation timed out'))
+      }, 10_000)
+
+      const handler = (
+        _event: Electron.IpcMainEvent,
+        reply: { requestId: string; browserPageId?: string; error?: string }
+      ): void => {
+        if (reply.requestId !== requestId) {
+          return
+        }
+        clearTimeout(timer)
+        ipcMain.removeListener('browser:tabCreateReply', handler)
+        if (reply.error) {
+          reject(new Error(reply.error))
+        } else {
+          resolve(reply.browserPageId!)
+        }
+      }
+      ipcMain.on('browser:tabCreateReply', handler)
+      win.webContents.send('browser:requestTabCreate', {
+        requestId,
+        url,
+        worktreeId,
+        sessionProfileId: profileId
+      })
+    })
+
+    return { browserPageId }
+  }
+}
diff --git a/src/main/runtime/orca-runtime-files.test.ts b/src/main/runtime/orca-runtime-files.test.ts
new file mode 100644
index 00000000000..e77943d1049
--- /dev/null
+++ b/src/main/runtime/orca-runtime-files.test.ts
@@ -0,0 +1,112 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type * as Fs from 'fs'
+import type * as FsPromises from 'fs/promises'
+import type * as FilesystemAuth from '../ipc/filesystem-auth'
+
+const { resolveAuthorizedPathMock, statMock, watchMock } = vi.hoisted(() => ({
+  resolveAuthorizedPathMock: vi.fn(),
+  statMock: vi.fn(),
+  watchMock: vi.fn()
+}))
+
+vi.mock('fs', async () => {
+  const actual = await vi.importActual<typeof Fs>('fs')
+  return {
+    ...actual,
+    watch: watchMock
+  }
+})
+
+vi.mock('fs/promises', async () => {
+  const actual = await vi.importActual<typeof FsPromises>('fs/promises')
+  return {
+    ...actual,
+    stat: statMock
+  }
+})
+
+vi.mock('../ipc/filesystem-auth', async () => {
+  const actual = await vi.importActual<typeof FilesystemAuth>('../ipc/filesystem-auth')
+  return {
+    ...actual,
+    resolveAuthorizedPath: resolveAuthorizedPathMock
+  }
+})
+
+vi.mock('../providers/ssh-filesystem-dispatch', () => ({
+  getSshFilesystemProvider: vi.fn()
+}))
+
+import { RuntimeFileCommands } from './orca-runtime-files'
+
+describe('RuntimeFileCommands', () => {
+  const originalPlatform = process.platform
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    resolveAuthorizedPathMock.mockReset()
+    statMock.mockReset()
+    watchMock.mockReset()
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: originalPlatform
+    })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: originalPlatform
+    })
+    vi.useRealTimers()
+  })
+
+  it('uses a conservative Node watcher for Windows runtime file watches', async () => {
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'win32'
+    })
+
+    const store = { getRepo: vi.fn(() => undefined) }
+    const close = vi.fn()
+    const on = vi.fn()
+    let listener: (() => void) | null = null
+    watchMock.mockImplementation((_rootPath, _options, callback) => {
+      listener = callback
+      return { close, on }
+    })
+    resolveAuthorizedPathMock.mockResolvedValue('C:\\repo')
+    statMock.mockResolvedValue({ isDirectory: () => true })
+
+    const commands = new RuntimeFileCommands({
+      getRuntimeId: () => 'runtime-1',
+      requireStore: () => store,
+      resolveWorktreeSelector: vi.fn(async () => ({
+        id: 'wt-1',
+        repoId: 'repo-1',
+        path: 'C:\\repo'
+      })),
+      resolveRuntimeGitTarget: vi.fn(),
+      openFile: vi.fn()
+    } as never)
+    const onEvents = vi.fn()
+
+    const unsubscribe = await commands.watchFileExplorer('id:wt-1', onEvents)
+
+    expect(watchMock).toHaveBeenCalledWith('C:\\repo', { recursive: true }, expect.any(Function))
+    const emit = listener as (() => void) | null
+    expect(emit).not.toBeNull()
+
+    emit?.()
+    emit?.()
+    await vi.advanceTimersByTimeAsync(149)
+    expect(onEvents).not.toHaveBeenCalled()
+
+    await vi.advanceTimersByTimeAsync(1)
+    expect(onEvents).toHaveBeenCalledTimes(1)
+    expect(onEvents).toHaveBeenCalledWith([{ kind: 'overflow', absolutePath: 'C:\\repo' }])
+
+    unsubscribe()
+    expect(close).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/main/runtime/orca-runtime-files.ts b/src/main/runtime/orca-runtime-files.ts
new file mode 100644
index 00000000000..ca326ae42ad
--- /dev/null
+++ b/src/main/runtime/orca-runtime-files.ts
@@ -0,0 +1,918 @@
+/* eslint-disable max-lines -- Why: filesystem, editor-file, and search commands share the same local/SSH path authorization rules. Keeping that IO adapter together prevents separate command paths from drifting on safety checks. */
+import type { ChildProcess } from 'child_process'
+import { watch as watchFs } from 'fs'
+import {
+  constants,
+  copyFile,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile
+} from 'fs/promises'
+import { basename, dirname, extname, join } from 'path'
+import type {
+  DirEntry,
+  FsChangeEvent,
+  GitWorktreeInfo,
+  MarkdownDocument,
+  SearchOptions,
+  SearchResult,
+  Worktree
+} from '../../shared/types'
+import type {
+  RuntimeFileListResult,
+  RuntimeFileOpenResult,
+  RuntimeFilePreviewResult,
+  RuntimeFileReadResult
+} from '../../shared/runtime-types'
+import { wslAwareSpawn } from '../git/runner'
+import { parseWslPath, toWindowsWslPath } from '../wsl'
+import { isENOENT, resolveAuthorizedPath } from '../ipc/filesystem-auth'
+import { listQuickOpenFiles } from '../ipc/filesystem-list-files'
+import { searchWithGitGrep } from '../ipc/filesystem-search-git'
+import { checkRgAvailable } from '../ipc/rg-availability'
+import {
+  listMarkdownDocuments,
+  markdownDocumentsFromRelativePaths
+} from '../ipc/markdown-documents'
+import {
+  buildRgArgs,
+  createAccumulator,
+  DEFAULT_SEARCH_MAX_RESULTS,
+  finalize,
+  ingestRgJsonLine,
+  SEARCH_TIMEOUT_MS
+} from '../../shared/text-search'
+import type { Store } from '../persistence'
+import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
+import { joinWorktreeRelativePath, normalizeRuntimeRelativePath } from './runtime-relative-paths'
+
+const MOBILE_FILE_LIST_LIMIT = 5000
+const MOBILE_FILE_READ_MAX_BYTES = 512 * 1024
+const RUNTIME_PREVIEWABLE_BINARY_MAX_BYTES = 10 * 1024 * 1024
+const WINDOWS_RUNTIME_FILE_WATCH_DEBOUNCE_MS = 150
+const MOBILE_BINARY_EXTENSIONS = new Set([
+  '.avif',
+  '.bmp',
+  '.gif',
+  '.heic',
+  '.ico',
+  '.jpeg',
+  '.jpg',
+  '.mov',
+  '.mp3',
+  '.mp4',
+  '.pdf',
+  '.png',
+  '.webp',
+  '.zip'
+])
+const RUNTIME_PREVIEWABLE_BINARY_MIME_TYPES: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon',
+  '.pdf': 'application/pdf'
+}
+
+export type ResolvedRuntimeFileWorktree = Worktree & { git: GitWorktreeInfo }
+
+export type RuntimeFileCommandHost = {
+  getRuntimeId(): string
+  requireStore(): Store
+  resolveWorktreeSelector(selector: string): Promise<ResolvedRuntimeFileWorktree>
+  resolveRuntimeGitTarget(
+    selector: string
+  ): Promise<{ worktree: ResolvedRuntimeFileWorktree; connectionId?: string }>
+  openFile(worktreeId: string, filePath: string, relativePath: string): void
+}
+
+export class RuntimeFileCommands {
+  private activeRuntimeTextSearches = new Map<string, ChildProcess>()
+
+  constructor(private readonly host: RuntimeFileCommandHost) {}
+
+  async listMobileFiles(worktreeSelector: string): Promise<RuntimeFileListResult> {
+    const store = this.host.requireStore()
+    const worktree = await this.host.resolveWorktreeSelector(worktreeSelector)
+    const repo = store.getRepo(worktree.repoId)
+    const connectionId = repo?.connectionId ?? undefined
+    const files = connectionId
+      ? await this.listRemoteMobileFiles(worktree.path, connectionId)
+      : await listQuickOpenFiles(worktree.path, store)
+    const entries = files
+      .filter((relativePath) => isSafeMobileRelativePath(relativePath))
+      .sort((a, b) => a.localeCompare(b))
+      .slice(0, MOBILE_FILE_LIST_LIMIT)
+      .map((relativePath) => ({
+        relativePath,
+        basename: basenameFromRelativePath(relativePath),
+        kind: isMobileBinaryPath(relativePath) ? ('binary' as const) : ('text' as const)
+      }))
+
+    return {
+      worktree: worktree.id,
+      rootPath: worktree.path,
+      files: entries,
+      totalCount: files.length,
+      truncated: files.length > MOBILE_FILE_LIST_LIMIT
+    }
+  }
+
+  async openMobileFile(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<RuntimeFileOpenResult> {
+    const worktree = await this.host.resolveWorktreeSelector(worktreeSelector)
+    if (!isSafeMobileRelativePath(relativePath)) {
+      throw new Error('invalid_relative_path')
+    }
+    const kind = isMobileBinaryPath(relativePath)
+      ? 'binary'
+      : isMobileMarkdownPath(relativePath)
+        ? 'markdown'
+        : 'text'
+    if (kind === 'binary') {
+      return { worktree: worktree.id, relativePath, kind, opened: false }
+    }
+    const filePath = joinWorktreeRelativePath(worktree.path, relativePath)
+    this.host.openFile(worktree.id, filePath, relativePath)
+    return { worktree: worktree.id, relativePath, kind, opened: true }
+  }
+
+  async readMobileFile(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<RuntimeFileReadResult> {
+    const store = this.host.requireStore()
+    const worktree = await this.host.resolveWorktreeSelector(worktreeSelector)
+    if (!isSafeMobileRelativePath(relativePath)) {
+      throw new Error('invalid_relative_path')
+    }
+    if (isMobileBinaryPath(relativePath)) {
+      throw new Error('binary_file')
+    }
+
+    const repo = store.getRepo(worktree.repoId)
+    const filePath = joinWorktreeRelativePath(worktree.path, relativePath)
+    const content = repo?.connectionId
+      ? await this.readRemoteMobileFile(filePath, repo.connectionId)
+      : await readLocalMobileFile(filePath, store)
+    const truncated = truncateMobileFilePreview(content)
+
+    return {
+      worktree: worktree.id,
+      relativePath,
+      content: truncated.content,
+      truncated: truncated.truncated,
+      byteLength: truncated.byteLength
+    }
+  }
+
+  async readFileExplorerDir(worktreeSelector: string, relativePath: string): Promise<DirEntry[]> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      return provider.readDir(target.path)
+    }
+
+    const dirPath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    const entries = await readdir(dirPath, { withFileTypes: true })
+    const mapped = await Promise.all(
+      entries.map(async (entry) => {
+        const entryPath = join(dirPath, entry.name)
+        return {
+          name: entry.name,
+          isDirectory: await isRuntimeDirectoryEntry(entryPath),
+          isSymlink: entry.isSymbolicLink()
+        }
+      })
+    )
+    return mapped.sort((a, b) => {
+      if (a.isDirectory !== b.isDirectory) {
+        return a.isDirectory ? -1 : 1
+      }
+      return a.name.localeCompare(b.name)
+    })
+  }
+
+  async watchFileExplorer(
+    worktreeSelector: string,
+    callback: (events: FsChangeEvent[]) => void
+  ): Promise<() => void> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, '')
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      return provider.watch(target.path, callback)
+    }
+
+    const rootPath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    const rootStats = await stat(rootPath)
+    if (!rootStats.isDirectory()) {
+      throw new Error('not_a_directory')
+    }
+    if (process.platform === 'win32') {
+      return watchWindowsRuntimeFileExplorer(rootPath, callback)
+    }
+    const watcher = await import('@parcel/watcher')
+    const subscription = await watcher.subscribe(
+      rootPath,
+      (err, events) => {
+        if (err) {
+          console.error('[runtime-files.watch] watcher error', { rootPath, err })
+          callback([{ kind: 'overflow', absolutePath: rootPath }])
+          return
+        }
+        void Promise.all(
+          events.map(async (event): Promise<FsChangeEvent> => {
+            let isDirectory = false
+            try {
+              isDirectory = (await stat(event.path)).isDirectory()
+            } catch {
+              isDirectory = false
+            }
+            return {
+              kind: event.type,
+              absolutePath: event.path,
+              isDirectory
+            }
+          })
+        ).then(callback)
+      },
+      {
+        ignore: [
+          '.git',
+          'node_modules',
+          'dist',
+          'build',
+          '.next',
+          '.cache',
+          '__pycache__',
+          'target',
+          '.venv'
+        ]
+      }
+    )
+    return () => {
+      void subscription.unsubscribe().catch((err: unknown) => {
+        console.error('[runtime-files.watch] unsubscribe error', { rootPath, err })
+      })
+    }
+  }
+
+  async readFileExplorerPreview(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<RuntimeFilePreviewResult> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      const fileStats = await provider.stat(target.path)
+      if (fileStats.size > RUNTIME_PREVIEWABLE_BINARY_MAX_BYTES) {
+        throw new Error('file_too_large')
+      }
+      const result = await provider.readFile(target.path)
+      return result
+    }
+
+    const filePath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    const fileStats = await stat(filePath)
+    const mimeType = RUNTIME_PREVIEWABLE_BINARY_MIME_TYPES[extname(filePath).toLowerCase()]
+    if (mimeType) {
+      if (fileStats.size > RUNTIME_PREVIEWABLE_BINARY_MAX_BYTES) {
+        throw new Error('file_too_large')
+      }
+      const buffer = await readFile(filePath)
+      return {
+        content: buffer.toString('base64'),
+        isBinary: true,
+        isImage: true,
+        mimeType
+      }
+    }
+
+    if (fileStats.size > MOBILE_FILE_READ_MAX_BYTES) {
+      throw new Error('file_too_large')
+    }
+    const buffer = await readFile(filePath)
+    if (isBinaryBuffer(buffer)) {
+      return { content: '', isBinary: true }
+    }
+    return { content: buffer.toString('utf-8'), isBinary: false }
+  }
+
+  async writeFileExplorerFile(
+    worktreeSelector: string,
+    relativePath: string,
+    content: string
+  ): Promise<{ ok: true }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.writeFile(target.path, content)
+      return { ok: true }
+    }
+
+    const filePath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    try {
+      const fileStats = await lstat(filePath)
+      if (fileStats.isDirectory()) {
+        throw new Error('Cannot write to a directory')
+      }
+    } catch (error) {
+      if (!isENOENT(error)) {
+        throw error
+      }
+    }
+    await writeFile(filePath, content, 'utf-8')
+    return { ok: true }
+  }
+
+  async writeFileExplorerFileBase64(
+    worktreeSelector: string,
+    relativePath: string,
+    contentBase64: string
+  ): Promise<{ ok: true }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    const content = Buffer.from(contentBase64, 'base64')
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.writeFileBase64(target.path, contentBase64)
+      return { ok: true }
+    }
+
+    const filePath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    await mkdir(dirname(filePath), { recursive: true })
+    await writeFile(filePath, content, { flag: 'wx' })
+    return { ok: true }
+  }
+
+  async writeFileExplorerFileBase64Chunk(
+    worktreeSelector: string,
+    relativePath: string,
+    contentBase64: string,
+    append: boolean
+  ): Promise<{ ok: true }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    const content = Buffer.from(contentBase64, 'base64')
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.writeFileBase64Chunk(target.path, contentBase64, append)
+      return { ok: true }
+    }
+
+    const filePath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    await mkdir(dirname(filePath), { recursive: true })
+    await writeFile(filePath, content, { flag: append ? 'a' : 'wx' })
+    return { ok: true }
+  }
+
+  async createFileExplorerFile(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<{ ok: true }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.createFile(target.path)
+      return { ok: true }
+    }
+
+    const filePath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    await mkdir(dirname(filePath), { recursive: true })
+    try {
+      await writeFile(filePath, '', { encoding: 'utf-8', flag: 'wx' })
+    } catch (error) {
+      rethrowRuntimeFileCreateError(error, filePath)
+    }
+    return { ok: true }
+  }
+
+  async createFileExplorerDir(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<{ ok: true }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.createDir(target.path)
+      return { ok: true }
+    }
+
+    const dirPath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    await assertRuntimePathDoesNotExist(dirPath)
+    await mkdir(dirPath, { recursive: false })
+    return { ok: true }
+  }
+
+  async createFileExplorerDirNoClobber(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<{ ok: true }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.createDirNoClobber(target.path)
+      return { ok: true }
+    }
+
+    const dirPath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    await mkdir(dirPath, { recursive: false })
+    return { ok: true }
+  }
+
+  async commitFileExplorerUpload(
+    worktreeSelector: string,
+    tempRelativePath: string,
+    finalRelativePath: string
+  ): Promise<{ ok: true }> {
+    const tempTarget = await this.resolveFileExplorerPath(worktreeSelector, tempRelativePath)
+    const finalTarget = await this.resolveFileExplorerPath(worktreeSelector, finalRelativePath)
+    const provider = tempTarget.connectionId
+      ? getSshFilesystemProvider(tempTarget.connectionId)
+      : null
+    if (tempTarget.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.copy(tempTarget.path, finalTarget.path)
+      await provider.deletePath(tempTarget.path, false).catch(() => {})
+      return { ok: true }
+    }
+
+    const store = this.host.requireStore()
+    const tempPath = await resolveAuthorizedPath(tempTarget.path, store)
+    const finalPath = await resolveAuthorizedPath(finalTarget.path, store)
+    await mkdir(dirname(finalPath), { recursive: true })
+    await copyFile(tempPath, finalPath, constants.COPYFILE_EXCL)
+    await rm(tempPath, { force: true })
+    return { ok: true }
+  }
+
+  async renameFileExplorerPath(
+    worktreeSelector: string,
+    oldRelativePath: string,
+    newRelativePath: string
+  ): Promise<{ ok: true }> {
+    const oldTarget = await this.resolveFileExplorerPath(worktreeSelector, oldRelativePath)
+    const newTarget = await this.resolveFileExplorerPath(worktreeSelector, newRelativePath)
+    const provider = oldTarget.connectionId
+      ? getSshFilesystemProvider(oldTarget.connectionId)
+      : null
+    if (oldTarget.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.rename(oldTarget.path, newTarget.path)
+      return { ok: true }
+    }
+
+    const store = this.host.requireStore()
+    const oldPath = await resolveAuthorizedPath(oldTarget.path, store, { preserveSymlink: true })
+    const newPath = await resolveAuthorizedPath(newTarget.path, store, { preserveSymlink: true })
+    await assertRuntimePathDoesNotExist(newPath)
+    await rename(oldPath, newPath)
+    return { ok: true }
+  }
+
+  async copyFileExplorerPath(
+    worktreeSelector: string,
+    sourceRelativePath: string,
+    destinationRelativePath: string
+  ): Promise<{ ok: true }> {
+    const sourceTarget = await this.resolveFileExplorerPath(worktreeSelector, sourceRelativePath)
+    const destinationTarget = await this.resolveFileExplorerPath(
+      worktreeSelector,
+      destinationRelativePath
+    )
+    const provider = sourceTarget.connectionId
+      ? getSshFilesystemProvider(sourceTarget.connectionId)
+      : null
+    if (sourceTarget.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.copy(sourceTarget.path, destinationTarget.path)
+      return { ok: true }
+    }
+
+    const store = this.host.requireStore()
+    const sourcePath = await resolveAuthorizedPath(sourceTarget.path, store, {
+      preserveSymlink: true
+    })
+    const destinationPath = await resolveAuthorizedPath(destinationTarget.path, store, {
+      preserveSymlink: true
+    })
+    await mkdir(dirname(destinationPath), { recursive: true })
+    // Why: duplicate/copy operations are deconflicted by the caller. COPYFILE_EXCL
+    // preserves the same no-clobber invariant as the local shell copy IPC.
+    await copyFile(sourcePath, destinationPath, constants.COPYFILE_EXCL)
+    return { ok: true }
+  }
+
+  async deleteFileExplorerPath(
+    worktreeSelector: string,
+    relativePath: string,
+    recursive?: boolean
+  ): Promise<{ ok: true }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      await provider.deletePath(target.path, recursive)
+      return { ok: true }
+    }
+
+    const targetPath = await resolveAuthorizedPath(target.path, this.host.requireStore(), {
+      preserveSymlink: true
+    })
+    // Why: a non-local runtime has no client OS Trash/Recycling Bin; server-side
+    // file mutations are permanent and the renderer confirms before calling this.
+    await rm(targetPath, { recursive: recursive === true, force: true })
+    return { ok: true }
+  }
+
+  async searchRuntimeFiles(
+    worktreeSelector: string,
+    options: Omit<SearchOptions, 'rootPath'>
+  ): Promise<SearchResult> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    const rootPath = target.worktree.path
+    const searchOptions = { ...options, rootPath }
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      return provider.search(searchOptions)
+    }
+    return this.searchLocalRuntimeFiles(rootPath, searchOptions)
+  }
+
+  async listRuntimeFiles(
+    worktreeSelector: string,
+    options: { excludePaths?: string[] } = {}
+  ): Promise<string[]> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        return []
+      }
+      return provider.listFiles(target.worktree.path, { excludePaths: options.excludePaths })
+    }
+    return listQuickOpenFiles(target.worktree.path, this.host.requireStore(), options.excludePaths)
+  }
+
+  async listRuntimeMarkdownDocuments(worktreeSelector: string): Promise<MarkdownDocument[]> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      const relativePaths = await provider.listFiles(target.worktree.path)
+      return markdownDocumentsFromRelativePaths(target.worktree.path, relativePaths)
+    }
+    return listMarkdownDocuments(target.worktree.path)
+  }
+
+  async statRuntimeFile(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<{ size: number; isDirectory: boolean; mtime: number }> {
+    const target = await this.resolveFileExplorerPath(worktreeSelector, relativePath)
+    const provider = target.connectionId ? getSshFilesystemProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_filesystem_unavailable')
+      }
+      const fileStat = await provider.stat(target.path)
+      return {
+        size: fileStat.size,
+        isDirectory: fileStat.type === 'directory',
+        mtime: fileStat.mtime
+      }
+    }
+    const filePath = await resolveAuthorizedPath(target.path, this.host.requireStore())
+    const stats = await stat(filePath)
+    return { size: stats.size, isDirectory: stats.isDirectory(), mtime: stats.mtimeMs }
+  }
+
+  private async searchLocalRuntimeFiles(
+    rootPath: string,
+    options: SearchOptions
+  ): Promise<SearchResult> {
+    const authorizedRootPath = await resolveAuthorizedPath(rootPath, this.host.requireStore())
+    const maxResults = Math.max(
+      1,
+      Math.min(options.maxResults ?? DEFAULT_SEARCH_MAX_RESULTS, DEFAULT_SEARCH_MAX_RESULTS)
+    )
+    const rgAvailable = await checkRgAvailable(authorizedRootPath)
+    if (!rgAvailable) {
+      return searchWithGitGrep(authorizedRootPath, options, maxResults)
+    }
+
+    return new Promise((resolvePromise) => {
+      const searchKey = `${this.host.getRuntimeId()}:${authorizedRootPath}`
+      const rgArgs = buildRgArgs(options.query, authorizedRootPath, options)
+      this.activeRuntimeTextSearches.get(searchKey)?.kill()
+
+      const acc = createAccumulator()
+      let stdoutBuffer = ''
+      let resolved = false
+      let child: ChildProcess | null = null
+      const wslInfo = parseWslPath(authorizedRootPath)
+      const transformAbsPath = wslInfo
+        ? (p: string): string => toWindowsWslPath(p, wslInfo.distro)
+        : undefined
+
+      const resolveOnce = (): void => {
+        if (resolved) {
+          return
+        }
+        resolved = true
+        if (this.activeRuntimeTextSearches.get(searchKey) === child) {
+          this.activeRuntimeTextSearches.delete(searchKey)
+        }
+        clearTimeout(killTimeout)
+        resolvePromise(finalize(acc))
+      }
+
+      const processLine = (line: string): void => {
+        const verdict = ingestRgJsonLine(
+          line,
+          authorizedRootPath,
+          acc,
+          maxResults,
+          transformAbsPath
+        )
+        if (verdict === 'stop') {
+          child?.kill()
+        }
+      }
+
+      const nextChild = wslAwareSpawn('rg', rgArgs, {
+        cwd: authorizedRootPath,
+        stdio: ['ignore', 'pipe', 'pipe']
+      })
+      child = nextChild
+      this.activeRuntimeTextSearches.set(searchKey, nextChild)
+
+      nextChild.stdout!.setEncoding('utf-8')
+      nextChild.stdout!.on('data', (chunk: string) => {
+        stdoutBuffer += chunk
+        const lines = stdoutBuffer.split('\n')
+        stdoutBuffer = lines.pop() ?? ''
+        for (const line of lines) {
+          processLine(line)
+        }
+      })
+      nextChild.stderr!.on('data', () => {
+        // Drain stderr so rg cannot block on a full pipe.
+      })
+      nextChild.once('error', () => resolveOnce())
+      nextChild.once('close', () => {
+        if (stdoutBuffer) {
+          processLine(stdoutBuffer)
+        }
+        resolveOnce()
+      })
+
+      const killTimeout = setTimeout(() => {
+        acc.truncated = true
+        child?.kill()
+      }, SEARCH_TIMEOUT_MS)
+    })
+  }
+
+  private async resolveFileExplorerPath(
+    worktreeSelector: string,
+    relativePath: string
+  ): Promise<{ worktree: ResolvedRuntimeFileWorktree; path: string; connectionId?: string }> {
+    const store = this.host.requireStore()
+    const worktree = await this.host.resolveWorktreeSelector(worktreeSelector)
+    const normalizedRelativePath = normalizeRuntimeRelativePath(relativePath)
+    const repo = store.getRepo(worktree.repoId)
+    return {
+      worktree,
+      path: joinWorktreeRelativePath(worktree.path, normalizedRelativePath),
+      connectionId: repo?.connectionId ?? undefined
+    }
+  }
+
+  private async listRemoteMobileFiles(rootPath: string, connectionId: string): Promise<string[]> {
+    const provider = getSshFilesystemProvider(connectionId)
+    if (!provider) {
+      return []
+    }
+    return provider.listFiles(rootPath)
+  }
+
+  private async readRemoteMobileFile(filePath: string, connectionId: string): Promise<string> {
+    const provider = getSshFilesystemProvider(connectionId)
+    if (!provider) {
+      throw new Error('remote_filesystem_unavailable')
+    }
+    const fileStat = await provider.stat(filePath)
+    // Why: the SSH filesystem API does not expose ranged reads here, so reject
+    // oversized remote previews instead of streaming a large file just to trim it.
+    if (fileStat.size > MOBILE_FILE_READ_MAX_BYTES) {
+      throw new Error('file_too_large')
+    }
+    const result = await provider.readFile(filePath)
+    if (result.isBinary) {
+      throw new Error('binary_file')
+    }
+    return result.content
+  }
+}
+
+function watchWindowsRuntimeFileExplorer(
+  rootPath: string,
+  callback: (events: FsChangeEvent[]) => void
+): () => void {
+  let disposed = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const emitOverflow = (): void => {
+    timer = null
+    if (disposed) {
+      return
+    }
+    callback([{ kind: 'overflow', absolutePath: rootPath }])
+  }
+
+  const scheduleOverflow = (): void => {
+    if (disposed) {
+      return
+    }
+    if (timer) {
+      clearTimeout(timer)
+    }
+    timer = setTimeout(emitOverflow, WINDOWS_RUNTIME_FILE_WATCH_DEBOUNCE_MS)
+  }
+
+  // Why: Parcel probes Watchman before the Windows backend and its native
+  // watcher can abort the headless server process. For remote Windows runtimes,
+  // a conservative overflow refresh is safer than a process-wide native crash.
+  const watcher = watchFs(rootPath, { recursive: true }, scheduleOverflow)
+  watcher.on('error', (err) => {
+    console.error('[runtime-files.watch] Windows watcher error', { rootPath, err })
+    scheduleOverflow()
+  })
+
+  return () => {
+    disposed = true
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+    try {
+      watcher.close()
+    } catch (err) {
+      console.error('[runtime-files.watch] Windows watcher close error', { rootPath, err })
+    }
+  }
+}
+
+export function isSafeMobileRelativePath(relativePath: string): boolean {
+  if (!relativePath || relativePath.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(relativePath)) {
+    return false
+  }
+  const parts = relativePath.replace(/\\/g, '/').split('/')
+  return parts.every((part) => part !== '' && part !== '.' && part !== '..')
+}
+
+function isMobileMarkdownPath(relativePath: string): boolean {
+  return /\.(md|mdx|markdown)$/i.test(relativePath)
+}
+
+function isMobileBinaryPath(relativePath: string): boolean {
+  const basename = basenameFromRelativePath(relativePath)
+  const dotIndex = basename.lastIndexOf('.')
+  if (dotIndex <= 0) {
+    return false
+  }
+  return MOBILE_BINARY_EXTENSIONS.has(basename.slice(dotIndex).toLowerCase())
+}
+
+function basenameFromRelativePath(relativePath: string): string {
+  const normalized = relativePath.replace(/\\/g, '/')
+  return normalized.slice(normalized.lastIndexOf('/') + 1)
+}
+
+async function isRuntimeDirectoryEntry(entryPath: string): Promise<boolean> {
+  try {
+    return (await stat(entryPath)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function isBinaryBuffer(buffer: Buffer): boolean {
+  const len = Math.min(buffer.length, 8192)
+  for (let i = 0; i < len; i += 1) {
+    if (buffer[i] === 0) {
+      return true
+    }
+  }
+  return false
+}
+
+async function assertRuntimePathDoesNotExist(targetPath: string): Promise<void> {
+  try {
+    await lstat(targetPath)
+    throw new Error(
+      `A file or folder named '${basename(targetPath)}' already exists in this location`
+    )
+  } catch (error) {
+    if (!isENOENT(error)) {
+      throw error
+    }
+  }
+}
+
+function rethrowRuntimeFileCreateError(error: unknown, targetPath: string): never {
+  const name = basename(targetPath)
+  if (error instanceof Error && 'code' in error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === 'EEXIST') {
+      throw new Error(`A file or folder named '${name}' already exists in this location`)
+    }
+    if (code === 'EACCES' || code === 'EPERM') {
+      throw new Error(`Permission denied: unable to create '${name}'`)
+    }
+  }
+  throw error
+}
+
+async function readLocalMobileFile(filePath: string, store: Store): Promise<string> {
+  const authorizedPath = await resolveAuthorizedPath(filePath, store)
+  const fileStat = await stat(authorizedPath)
+  // Why: mobile file previews are read-only convenience views; cap the read so
+  // opening a generated log or bundle cannot block the WebSocket like oversized scrollback.
+  const readLimit = Math.min(fileStat.size, MOBILE_FILE_READ_MAX_BYTES + 1)
+  const handle = await open(authorizedPath, 'r')
+  try {
+    const buffer = Buffer.alloc(readLimit)
+    const { bytesRead } = await handle.read(buffer, 0, readLimit, 0)
+    return buffer.subarray(0, bytesRead).toString('utf8')
+  } finally {
+    await handle.close()
+  }
+}
+
+function truncateMobileFilePreview(content: string): {
+  content: string
+  truncated: boolean
+  byteLength: number
+} {
+  const buffer = Buffer.from(content, 'utf8')
+  if (buffer.byteLength <= MOBILE_FILE_READ_MAX_BYTES) {
+    return { content, truncated: false, byteLength: buffer.byteLength }
+  }
+  return {
+    content: buffer.subarray(0, MOBILE_FILE_READ_MAX_BYTES).toString('utf8'),
+    truncated: true,
+    byteLength: buffer.byteLength
+  }
+}
diff --git a/src/main/runtime/orca-runtime-git.ts b/src/main/runtime/orca-runtime-git.ts
new file mode 100644
index 00000000000..9c405a04599
--- /dev/null
+++ b/src/main/runtime/orca-runtime-git.ts
@@ -0,0 +1,308 @@
+import type {
+  GitBranchCompareResult,
+  GitConflictOperation,
+  GitDiffResult,
+  GitPushTarget,
+  GitStatusResult,
+  GitUpstreamStatus,
+  GitWorktreeInfo,
+  Worktree
+} from '../../shared/types'
+import { getRemoteFileUrl } from '../git/repo'
+import {
+  bulkStageFiles,
+  bulkUnstageFiles,
+  commitChanges,
+  detectConflictOperation,
+  discardChanges,
+  getBranchCompare,
+  getBranchDiff,
+  getDiff,
+  getStatus as getGitStatus,
+  stageFile,
+  unstageFile
+} from '../git/status'
+import { getUpstreamStatus } from '../git/upstream'
+import { gitFetch, gitPull, gitPush } from '../git/remote'
+import { getSshGitProvider } from '../providers/ssh-git-dispatch'
+import { normalizeRuntimeRelativePath } from './runtime-relative-paths'
+
+export type ResolvedRuntimeGitWorktree = Worktree & { git: GitWorktreeInfo }
+
+export type RuntimeGitCommandHost = {
+  resolveRuntimeGitTarget(
+    selector: string
+  ): Promise<{ worktree: ResolvedRuntimeGitWorktree; connectionId?: string }>
+}
+
+export class RuntimeGitCommands {
+  constructor(private readonly host: RuntimeGitCommandHost) {}
+
+  async getRuntimeGitStatus(worktreeSelector: string): Promise<GitStatusResult> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      return provider.getStatus(target.worktree.path)
+    }
+    return getGitStatus(target.worktree.path)
+  }
+
+  async getRuntimeGitConflictOperation(worktreeSelector: string): Promise<GitConflictOperation> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      return provider.detectConflictOperation(target.worktree.path)
+    }
+    return detectConflictOperation(target.worktree.path)
+  }
+
+  async getRuntimeGitDiff(
+    worktreeSelector: string,
+    filePath: string,
+    staged: boolean,
+    compareAgainstHead?: boolean
+  ): Promise<GitDiffResult> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const relativePath = normalizeRuntimeRelativePath(filePath)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      return provider.getDiff(target.worktree.path, relativePath, staged, compareAgainstHead)
+    }
+    return getDiff(target.worktree.path, relativePath, staged, compareAgainstHead)
+  }
+
+  async getRuntimeGitBranchCompare(
+    worktreeSelector: string,
+    baseRef: string
+  ): Promise<GitBranchCompareResult> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      return provider.getBranchCompare(target.worktree.path, baseRef)
+    }
+    return getBranchCompare(target.worktree.path, baseRef)
+  }
+
+  async getRuntimeGitUpstreamStatus(worktreeSelector: string): Promise<GitUpstreamStatus> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      return provider.getUpstreamStatus(target.worktree.path)
+    }
+    return getUpstreamStatus(target.worktree.path)
+  }
+
+  async fetchRuntimeGit(worktreeSelector: string): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.fetchRemote(target.worktree.path)
+      return { ok: true }
+    }
+    await gitFetch(target.worktree.path)
+    return { ok: true }
+  }
+
+  async pullRuntimeGit(worktreeSelector: string): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.pullBranch(target.worktree.path)
+      return { ok: true }
+    }
+    await gitPull(target.worktree.path)
+    return { ok: true }
+  }
+
+  async pushRuntimeGit(
+    worktreeSelector: string,
+    publish?: boolean,
+    pushTarget?: GitPushTarget
+  ): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.pushBranch(target.worktree.path, publish === true, pushTarget)
+      return { ok: true }
+    }
+    await gitPush(target.worktree.path, publish === true, pushTarget)
+    return { ok: true }
+  }
+
+  async getRuntimeGitBranchDiff(
+    worktreeSelector: string,
+    compare: { mergeBase: string; headOid: string },
+    filePath: string,
+    oldPath?: string
+  ): Promise<GitDiffResult> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const relativePath = normalizeRuntimeRelativePath(filePath)
+    const oldRelativePath = oldPath ? normalizeRuntimeRelativePath(oldPath) : undefined
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      const results = await provider.getBranchDiff(target.worktree.path, compare.mergeBase, {
+        includePatch: true,
+        filePath: relativePath,
+        oldPath: oldRelativePath
+      })
+      return (
+        results[0] ?? {
+          kind: 'text',
+          originalContent: '',
+          modifiedContent: '',
+          originalIsBinary: false,
+          modifiedIsBinary: false
+        }
+      )
+    }
+    return getBranchDiff(target.worktree.path, {
+      mergeBase: compare.mergeBase,
+      headOid: compare.headOid,
+      filePath: relativePath,
+      oldPath: oldRelativePath
+    })
+  }
+
+  async commitRuntimeGit(
+    worktreeSelector: string,
+    message: string
+  ): Promise<{ success: boolean; error?: string }> {
+    if (message.trim().length === 0) {
+      throw new Error('Commit message is required')
+    }
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      return provider.commit(target.worktree.path, message)
+    }
+    return commitChanges(target.worktree.path, message)
+  }
+
+  async stageRuntimeGitPath(worktreeSelector: string, filePath: string): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const relativePath = normalizeRuntimeRelativePath(filePath)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.stageFile(target.worktree.path, relativePath)
+      return { ok: true }
+    }
+    await stageFile(target.worktree.path, relativePath)
+    return { ok: true }
+  }
+
+  async unstageRuntimeGitPath(worktreeSelector: string, filePath: string): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const relativePath = normalizeRuntimeRelativePath(filePath)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.unstageFile(target.worktree.path, relativePath)
+      return { ok: true }
+    }
+    await unstageFile(target.worktree.path, relativePath)
+    return { ok: true }
+  }
+
+  async bulkStageRuntimeGitPaths(
+    worktreeSelector: string,
+    filePaths: string[]
+  ): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const relativePaths = filePaths.map((path) => normalizeRuntimeRelativePath(path))
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.bulkStageFiles(target.worktree.path, relativePaths)
+      return { ok: true }
+    }
+    await bulkStageFiles(target.worktree.path, relativePaths)
+    return { ok: true }
+  }
+
+  async bulkUnstageRuntimeGitPaths(
+    worktreeSelector: string,
+    filePaths: string[]
+  ): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const relativePaths = filePaths.map((path) => normalizeRuntimeRelativePath(path))
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.bulkUnstageFiles(target.worktree.path, relativePaths)
+      return { ok: true }
+    }
+    await bulkUnstageFiles(target.worktree.path, relativePaths)
+    return { ok: true }
+  }
+
+  async discardRuntimeGitPath(worktreeSelector: string, filePath: string): Promise<{ ok: true }> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const relativePath = normalizeRuntimeRelativePath(filePath)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      await provider.discardChanges(target.worktree.path, relativePath)
+      return { ok: true }
+    }
+    await discardChanges(target.worktree.path, relativePath)
+    return { ok: true }
+  }
+
+  async getRuntimeGitRemoteFileUrl(
+    worktreeSelector: string,
+    relativePath: string,
+    line: number
+  ): Promise<string | null> {
+    const target = await this.host.resolveRuntimeGitTarget(worktreeSelector)
+    const normalizedRelativePath = normalizeRuntimeRelativePath(relativePath)
+    const provider = target.connectionId ? getSshGitProvider(target.connectionId) : null
+    if (target.connectionId) {
+      if (!provider) {
+        throw new Error('remote_git_unavailable')
+      }
+      return provider.getRemoteFileUrl(target.worktree.path, normalizedRelativePath, line)
+    }
+    return getRemoteFileUrl(target.worktree.path, normalizedRelativePath, line)
+  }
+}
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index cfba17c75c0..d1b3f1b2e54 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -5,11 +5,19 @@ import { addWorktree, listWorktrees, removeWorktree } from '../git/worktree'
 import {
   createSetupRunnerScript,
   getEffectiveHooks,
+  hasHooksFile,
+  parseOrcaYaml,
   runHook,
   shouldRunSetupForCreate
 } from '../hooks'
+import { getDefaultBaseRef } from '../git/repo'
 import { OrchestrationDb } from './orchestration/db'
 import { OrcaRuntimeService } from './orca-runtime'
+import {
+  registerSshFilesystemProvider,
+  unregisterSshFilesystemProvider
+} from '../providers/ssh-filesystem-dispatch'
+import { registerSshGitProvider, unregisterSshGitProvider } from '../providers/ssh-git-dispatch'
 
 vi.mock('electron', () => ({
   app: {
@@ -62,7 +70,8 @@ vi.mock('../hooks', () => ({
     .fn()
     .mockImplementation((_repo: never, decision: string) => decision === 'run'),
   getEffectiveSetupRunPolicy: vi.fn().mockReturnValue('auto'),
-  hasHooksFile: vi.fn().mockReturnValue(false)
+  hasHooksFile: vi.fn().mockReturnValue(false),
+  parseOrcaYaml: vi.fn().mockReturnValue(null)
 }))
 
 vi.mock('../ipc/worktree-logic', async (importOriginal) => {
@@ -99,10 +108,14 @@ afterEach(() => {
   vi.mocked(removeWorktree).mockReset()
   vi.mocked(createSetupRunnerScript).mockReset()
   vi.mocked(getEffectiveHooks).mockReset()
+  vi.mocked(hasHooksFile).mockReset()
+  vi.mocked(parseOrcaYaml).mockReset()
   vi.mocked(runHook).mockReset()
   vi.mocked(shouldRunSetupForCreate).mockReset()
   vi.mocked(shouldRunSetupForCreate).mockImplementation((_repo, decision) => decision === 'run')
   vi.mocked(getEffectiveHooks).mockReturnValue(null)
+  vi.mocked(hasHooksFile).mockReturnValue(false)
+  vi.mocked(parseOrcaYaml).mockReturnValue(null)
   computeWorktreePathMock.mockReset()
   ensurePathWithinWorkspaceMock.mockReset()
   invalidateAuthorizedRootsCacheMock.mockReset()
@@ -143,6 +156,20 @@ function createRuntime(): OrcaRuntimeService {
   return new OrcaRuntimeService(store)
 }
 
+function deferred<T>(): {
+  promise: Promise<T>
+  resolve: (value: T) => void
+  reject: (error: unknown) => void
+} {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
 const store = {
   getRepo: (id: string) => store.getRepos().find((repo) => repo.id === id),
   getRepos: () => [
@@ -224,10 +251,15 @@ describe('OrcaRuntimeService', () => {
     expect(runtime.getRuntimeId()).toBeTruthy()
   })
 
-  it('reports protocol version and minimum compatible mobile version on status', () => {
+  it('reports runtime protocol, capabilities, and mobile aliases on status', () => {
     const runtime = createRuntime()
 
     const status = runtime.getStatus()
+    expect(typeof status.runtimeProtocolVersion).toBe('number')
+    expect(typeof status.minCompatibleRuntimeClientVersion).toBe('number')
+    expect(status.runtimeProtocolVersion).toBe(status.protocolVersion)
+    expect(status.minCompatibleRuntimeClientVersion).toBe(status.minCompatibleMobileVersion)
+    expect(status.capabilities).toContain('terminal.binary-stream.v1')
     expect(typeof status.protocolVersion).toBe('number')
     expect(typeof status.minCompatibleMobileVersion).toBe('number')
     expect(status.protocolVersion).toBeGreaterThanOrEqual(1)
@@ -354,12 +386,481 @@ describe('OrcaRuntimeService', () => {
     })
   })
 
+  it('routes SSH-backed forward-slash UNC file and git paths without collapsing the root', async () => {
+    vi.mocked(listWorktrees).mockClear()
+    vi.mocked(listWorktrees).mockRejectedValue(new Error('local git should not run for SSH repos'))
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: '//Server/Share/Repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ],
+      getRepo: () => ({
+        id: TEST_REPO_ID,
+        path: '//Server/Share/Repo',
+        displayName: 'repo',
+        badgeColor: 'blue',
+        addedAt: 1,
+        connectionId: 'ssh-1'
+      })
+    }
+    const fsProvider = { readDir: vi.fn().mockResolvedValue([]) }
+    const gitProvider = {
+      listWorktrees: vi.fn().mockResolvedValue([
+        {
+          path: '//Server/Share/Repo',
+          head: 'abc',
+          branch: 'feature/foo',
+          isBare: false,
+          isMainWorktree: false
+        }
+      ]),
+      getStatus: vi.fn().mockResolvedValue({
+        branch: 'feature/foo',
+        files: [],
+        ahead: 0,
+        behind: 0,
+        hasConflicts: false
+      })
+    }
+    registerSshFilesystemProvider('ssh-1', fsProvider as never)
+    registerSshGitProvider('ssh-1', gitProvider as never)
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    try {
+      await runtime.readFileExplorerDir('path://server/share/repo', 'src')
+      await runtime.getRuntimeGitStatus('path://server/share/repo')
+      await expect(runtime.showRepo('path://server/share/repo')).resolves.toMatchObject({
+        path: '//Server/Share/Repo'
+      })
+    } finally {
+      unregisterSshFilesystemProvider('ssh-1')
+      unregisterSshGitProvider('ssh-1')
+    }
+
+    expect(listWorktrees).not.toHaveBeenCalled()
+    expect(gitProvider.listWorktrees).toHaveBeenCalledWith('//Server/Share/Repo')
+    expect(fsProvider.readDir).toHaveBeenCalledWith('\\\\Server\\Share\\Repo\\src')
+    expect(gitProvider.getStatus).toHaveBeenCalledWith('//Server/Share/Repo')
+  })
+
   it('does not interpret active as a runtime-global worktree selector', async () => {
     const runtime = new OrcaRuntimeService(store)
 
     await expect(runtime.showManagedWorktree('active')).rejects.toThrow('selector_not_found')
   })
 
+  it('does not reuse stale in-flight worktree scans after creating a worktree', async () => {
+    const runtime = new OrcaRuntimeService(store)
+    const staleScan = deferred<typeof MOCK_GIT_WORKTREES>()
+    const createdWorktree = {
+      path: '/tmp/workspaces/cache-race',
+      head: 'def',
+      branch: 'cache-race',
+      isBare: false,
+      isMainWorktree: false
+    }
+    computeWorktreePathMock.mockReturnValue(createdWorktree.path)
+    ensurePathWithinWorkspaceMock.mockReturnValue(createdWorktree.path)
+    vi.mocked(listWorktrees)
+      .mockImplementationOnce(() => staleScan.promise)
+      .mockResolvedValueOnce([createdWorktree])
+      .mockResolvedValueOnce([...MOCK_GIT_WORKTREES, createdWorktree])
+
+    const staleLookup = runtime.showManagedWorktree(TEST_WORKTREE_ID)
+    const result = await runtime.createManagedWorktree({
+      repoSelector: 'id:repo-1',
+      name: 'cache-race'
+    })
+    const freshLookup = runtime.showManagedWorktree(result.worktree.id)
+
+    staleScan.resolve(MOCK_GIT_WORKTREES)
+
+    await expect(staleLookup).resolves.toMatchObject({ id: TEST_WORKTREE_ID })
+    await expect(freshLookup).resolves.toMatchObject({
+      id: result.worktree.id,
+      path: createdWorktree.path
+    })
+  })
+
+  it('does not run local git when runtime worktree creation targets an SSH repo', async () => {
+    vi.mocked(listWorktrees).mockClear()
+    vi.mocked(addWorktree).mockClear()
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: '/remote/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ]
+    }
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    await expect(
+      runtime.createManagedWorktree({ repoSelector: TEST_REPO_ID, name: 'feature' })
+    ).rejects.toThrow('SSH-backed worktree creation is not supported through runtime RPC yet')
+
+    expect(addWorktree).not.toHaveBeenCalled()
+    expect(listWorktrees).not.toHaveBeenCalled()
+  })
+
+  it('removes SSH-backed runtime worktrees through the SSH git provider', async () => {
+    vi.mocked(listWorktrees).mockClear()
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: '/remote/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ],
+      getRepo: () => ({
+        id: TEST_REPO_ID,
+        path: '/remote/repo',
+        displayName: 'repo',
+        badgeColor: 'blue',
+        addedAt: 1,
+        connectionId: 'ssh-1'
+      })
+    }
+    const gitProvider = {
+      listWorktrees: vi.fn().mockResolvedValue([
+        {
+          path: '/remote/repo',
+          head: 'abc',
+          branch: 'feature/foo',
+          isBare: false,
+          isMainWorktree: true
+        }
+      ]),
+      removeWorktree: vi.fn().mockResolvedValue(undefined)
+    }
+    registerSshGitProvider('ssh-1', gitProvider as never)
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    try {
+      await runtime.removeManagedWorktree('path:/remote/repo', true)
+    } finally {
+      unregisterSshGitProvider('ssh-1')
+    }
+
+    expect(gitProvider.removeWorktree).toHaveBeenCalledWith('/remote/repo', true)
+    expect(removeWorktree).not.toHaveBeenCalled()
+    expect(listWorktrees).not.toHaveBeenCalled()
+  })
+
+  it('reads SSH repo hooks through the SSH filesystem provider', async () => {
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: 'C:/remote/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ]
+    }
+    const fsProvider = {
+      readFile: vi.fn().mockResolvedValue({
+        content: 'scripts:\n  setup: pnpm install\n',
+        isBinary: false
+      })
+    }
+    vi.mocked(parseOrcaYaml).mockReturnValue({ scripts: { setup: 'pnpm install' } })
+    registerSshFilesystemProvider('ssh-1', fsProvider as never)
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    try {
+      await expect(runtime.getRepoHooks('id:repo-1')).resolves.toMatchObject({
+        hasHooksFile: true,
+        hooks: { scripts: { setup: 'pnpm install' } },
+        source: 'orca.yaml'
+      })
+    } finally {
+      unregisterSshFilesystemProvider('ssh-1')
+    }
+
+    expect(fsProvider.readFile).toHaveBeenCalledWith('C:\\remote\\repo\\.orca.yaml')
+    expect(hasHooksFile).not.toHaveBeenCalled()
+    expect(getEffectiveHooks).not.toHaveBeenCalled()
+  })
+
+  it('uses remote path joins for SSH hook checks and issue-command files', async () => {
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: 'C:/remote/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ]
+    }
+    const fsProvider = {
+      readFile: vi.fn(async (filePath: string) => ({
+        content: filePath.includes('.orca.yaml')
+          ? 'scripts:\n  setup: pnpm install\n'
+          : filePath.endsWith('.gitignore')
+            ? 'node_modules\n'
+            : 'Fix it',
+        isBinary: false
+      })),
+      writeFile: vi.fn().mockResolvedValue(undefined),
+      createDir: vi.fn().mockResolvedValue(undefined),
+      deletePath: vi.fn().mockResolvedValue(undefined)
+    }
+    registerSshFilesystemProvider('ssh-1', fsProvider as never)
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    try {
+      await expect(runtime.checkRepoHooks('id:repo-1')).resolves.toMatchObject({
+        hasHooks: true,
+        mayNeedUpdate: false
+      })
+      await expect(runtime.readRepoIssueCommand('id:repo-1')).resolves.toMatchObject({
+        localContent: 'Fix it',
+        effectiveContent: 'Fix it',
+        localFilePath: 'C:\\remote\\repo\\.orca\\issue-command'
+      })
+      await expect(runtime.writeRepoIssueCommand('id:repo-1', 'Ship it')).resolves.toEqual({
+        ok: true
+      })
+    } finally {
+      unregisterSshFilesystemProvider('ssh-1')
+    }
+
+    expect(fsProvider.readFile).toHaveBeenCalledWith('C:\\remote\\repo\\.orca.yaml')
+    expect(fsProvider.readFile).toHaveBeenCalledWith('C:\\remote\\repo\\.orca\\issue-command')
+    expect(fsProvider.createDir).toHaveBeenCalledWith('C:\\remote\\repo\\.orca')
+    expect(fsProvider.writeFile).toHaveBeenCalledWith(
+      'C:\\remote\\repo\\.orca\\issue-command',
+      'Ship it\n'
+    )
+    expect(fsProvider.writeFile).toHaveBeenCalledWith(
+      'C:\\remote\\repo\\.gitignore',
+      'node_modules\n.orca\n'
+    )
+  })
+
+  it('resolves SSH issue commands from shared orca.yaml and deletes empty overrides', async () => {
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: '/remote/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ]
+    }
+    vi.mocked(parseOrcaYaml).mockReturnValue({
+      scripts: {},
+      issueCommand: 'claude -p "Fix #{{issue}}"'
+    })
+    const fsProvider = {
+      readFile: vi.fn(async (filePath: string) => {
+        if (filePath.endsWith('.orca/issue-command')) {
+          throw Object.assign(new Error('missing'), { code: 'ENOENT' })
+        }
+        if (filePath.endsWith('orca.yaml')) {
+          return { content: 'issueCommand: claude -p "Fix #{{issue}}"', isBinary: false }
+        }
+        return { content: '', isBinary: false }
+      }),
+      writeFile: vi.fn().mockResolvedValue(undefined),
+      createDir: vi.fn().mockResolvedValue(undefined),
+      deletePath: vi.fn().mockResolvedValue(undefined)
+    }
+    registerSshFilesystemProvider('ssh-1', fsProvider as never)
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    try {
+      await expect(runtime.readRepoIssueCommand('id:repo-1')).resolves.toMatchObject({
+        localContent: null,
+        sharedContent: 'claude -p "Fix #{{issue}}"',
+        effectiveContent: 'claude -p "Fix #{{issue}}"',
+        localFilePath: '/remote/repo/.orca/issue-command',
+        source: 'shared'
+      })
+      await expect(runtime.writeRepoIssueCommand('id:repo-1', '   ')).resolves.toEqual({
+        ok: true
+      })
+    } finally {
+      unregisterSshFilesystemProvider('ssh-1')
+    }
+
+    expect(fsProvider.readFile).toHaveBeenCalledWith('/remote/repo/orca.yaml')
+    expect(fsProvider.deletePath).toHaveBeenCalledWith('/remote/repo/.orca/issue-command', false)
+    expect(fsProvider.writeFile).not.toHaveBeenCalledWith(
+      '/remote/repo/.orca/issue-command',
+      expect.anything()
+    )
+  })
+
+  it('rejects host integration helpers for SSH repos instead of using remote paths locally', async () => {
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: '/remote/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ]
+    }
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    await expect(runtime.getRepoSlug('id:repo-1')).rejects.toThrow(
+      'repo_slug_unsupported_for_ssh_repo'
+    )
+    await expect(runtime.listRepoWorkItems('id:repo-1')).rejects.toThrow(
+      'repo_work_items_unsupported_for_ssh_repo'
+    )
+  })
+
+  it('treats SSH worktree drift as unknown without local git probes', async () => {
+    vi.mocked(listWorktrees).mockClear()
+    vi.mocked(getDefaultBaseRef).mockClear()
+    const remoteStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: TEST_REPO_ID,
+          path: '/remote/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          connectionId: 'ssh-1'
+        }
+      ],
+      getWorktreeMeta: () => null
+    }
+    const gitProvider = {
+      listWorktrees: vi.fn().mockResolvedValue([
+        {
+          path: '/remote/repo',
+          head: 'abc',
+          branch: 'feature/foo',
+          isBare: false,
+          isMainWorktree: true
+        }
+      ])
+    }
+    registerSshGitProvider('ssh-1', gitProvider as never)
+    const runtime = new OrcaRuntimeService(remoteStore as never)
+
+    try {
+      await expect(runtime.probeWorktreeDrift('path:/remote/repo')).resolves.toBeNull()
+    } finally {
+      unregisterSshGitProvider('ssh-1')
+    }
+
+    expect(gitProvider.listWorktrees).toHaveBeenCalledWith('/remote/repo')
+    expect(getDefaultBaseRef).not.toHaveBeenCalled()
+    expect(listWorktrees).not.toHaveBeenCalled()
+  })
+
+  it('deduplicates runtime repo paths with Windows/UNC comparison semantics', async () => {
+    const added: Record<string, unknown>[] = []
+    const uncStore = {
+      ...store,
+      getRepos: () => [
+        {
+          id: 'repo-unc',
+          path: '//Server/Share/Repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1,
+          kind: 'folder'
+        },
+        ...added
+      ],
+      addRepo: (repo: Record<string, unknown>) => {
+        added.push(repo)
+      },
+      getRepo: (id: string) => [...uncStore.getRepos()].find((repo) => repo.id === id) as never
+    }
+    const runtime = new OrcaRuntimeService(uncStore as never)
+
+    const repo = await runtime.addRepo('//server/share/repo', 'folder')
+
+    expect(repo).toMatchObject({ id: 'repo-unc', path: '//Server/Share/Repo' })
+    expect(added).toHaveLength(0)
+  })
+
+  it('associates controller PTYs with mixed-case Windows and UNC cwd paths', async () => {
+    vi.mocked(listWorktrees).mockResolvedValue([
+      {
+        path: 'C:\\Repo',
+        head: 'abc',
+        branch: 'feature/windows',
+        isBare: false,
+        isMainWorktree: true
+      },
+      {
+        path: '//Server/Share/Repo',
+        head: 'def',
+        branch: 'feature/unc',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+    const runtime = createRuntime()
+    runtime.setPtyController({
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null,
+      listProcesses: async () => [
+        { id: 'pty-windows', cwd: 'c:\\repo\\src', title: 'Windows shell' },
+        { id: 'pty-unc', cwd: '//server/share/repo/src', title: 'UNC shell' }
+      ]
+    })
+    runtime.attachWindow(1)
+    runtime.markGraphReady(1)
+
+    const terminals = await runtime.listTerminals()
+
+    expect(terminals.terminals).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          worktreeId: `${TEST_REPO_ID}::C:\\Repo`,
+          worktreePath: 'C:\\Repo'
+        }),
+        expect.objectContaining({
+          worktreeId: `${TEST_REPO_ID}:://Server/Share/Repo`,
+          worktreePath: '//Server/Share/Repo'
+        })
+      ])
+    )
+  })
+
   it('reads bounded terminal output and writes through the PTY controller', async () => {
     const writes: string[] = []
     const runtime = new OrcaRuntimeService(store)
@@ -1102,6 +1603,55 @@ describe('OrcaRuntimeService', () => {
     }
   })
 
+  it('creates mobile session terminals in a headless runtime server', async () => {
+    const spawn = vi.fn().mockResolvedValue({ id: 'pty-headless' })
+    const runtime = new OrcaRuntimeService(store)
+    runtime.setPtyController({
+      spawn,
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null
+    })
+    runtime.syncWindowGraph(0, { tabs: [], leaves: [] })
+
+    const result = await runtime.createMobileSessionTerminal(`id:${TEST_WORKTREE_ID}`)
+
+    expect(spawn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cwd: TEST_WORKTREE_PATH,
+        worktreeId: TEST_WORKTREE_ID,
+        preAllocatedHandle: expect.stringMatching(/^term_/)
+      })
+    )
+    expect(result.tab).toMatchObject({
+      type: 'terminal',
+      status: 'ready',
+      terminal: expect.stringMatching(/^term_/),
+      isActive: true
+    })
+
+    const listed = await runtime.listMobileSessionTabs(`id:${TEST_WORKTREE_ID}`)
+    expect(listed.tabs).toEqual([
+      expect.objectContaining({
+        id: result.tab.id,
+        status: 'ready',
+        terminal: result.tab.terminal
+      })
+    ])
+  })
+
+  it('reports browser tab creation as unsupported for headless runtime servers', async () => {
+    const runtime = new OrcaRuntimeService(store)
+    runtime.syncWindowGraph(0, { tabs: [], leaves: [] })
+
+    await expect(
+      runtime.browserTabCreate({ worktree: `id:${TEST_WORKTREE_ID}`, url: 'https://example.com' })
+    ).rejects.toMatchObject({
+      code: 'browser_error',
+      message: expect.stringContaining('headless orca serve')
+    })
+  })
+
   it('keeps already-idle status after tui-idle wait for immediate message delivery', async () => {
     const runtime = new OrcaRuntimeService(store)
     const db = new OrchestrationDb(':memory:')
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 2b053f310dc..38fa678ec92 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -1,4 +1,4 @@
-/* eslint-disable max-lines -- Why: the Orca runtime is the authoritative live control plane for the CLI, so handle validation, selector resolution, wait state, and summaries are kept together to avoid split-brain behavior. */
+/* eslint-disable max-lines -- Why: OrcaRuntimeService still owns the mutable live graph, PTY handles, waiters, mobile floor/layout state, and managed-worktree reconciliation. Stateless browser and file command adapters live beside it; the remaining split points need state-owner extraction before enforcing max-lines. */
 /* eslint-disable unicorn/no-useless-spread -- Why: waiter sets and handle keys are cloned intentionally before mutation so resolution and rejection can safely remove entries while iterating. */
 /* eslint-disable no-control-regex -- Why: terminal normalization must strip ANSI and OSC control sequences from PTY output before returning bounded text to agents. */
 import {
@@ -7,29 +7,40 @@ import {
   isShellProcess
 } from '../../shared/agent-detection'
 import type { AgentStatus } from '../../shared/agent-detection'
-import { gitExecFileAsync } from '../git/runner'
+import { gitExecFileAsync, wslAwareSpawn } from '../git/runner'
 import { isWslPath, parseWslPath, getWslHome } from '../wsl'
 import { createHash, randomUUID } from 'crypto'
-import { join, posix, win32 } from 'path'
-import { open, rm, stat } from 'fs/promises'
+import { basename, isAbsolute, join } from 'path'
+import { mkdir, readdir, rm, stat } from 'fs/promises'
 import { OrchestrationDb } from './orchestration/db'
 import { formatMessagesForInjection } from './orchestration/formatter'
 import type {
   CreateWorktreeResult,
+  GitPushTarget,
+  GitWorktreeInfo,
   GlobalSettings,
   Repo,
   StatsSummary,
+  Worktree,
+  WorktreeMeta,
   WorktreeBaseStatusEvent,
   WorktreeRemoteBranchConflictEvent,
-  WorktreeStartupLaunch
+  WorktreeStartupLaunch,
+  LinearIssueUpdate,
+  TuiAgent
 } from '../../shared/types'
-import { getRepoIdFromWorktreeId, splitWorktreeId } from '../../shared/worktree-id'
+import { splitWorktreeId } from '../../shared/worktree-id'
 import { isFolderRepo } from '../../shared/repo-kind'
 import { buildSetupRunnerCommand } from '../../shared/setup-runner-command'
 import { FIRST_PANE_ID } from '../../shared/pane-key'
 import {
-  DESKTOP_PROTOCOL_VERSION,
-  MIN_COMPATIBLE_MOBILE_VERSION
+  isPathInsideOrEqual,
+  normalizeRuntimePathForComparison
+} from '../../shared/cross-platform-path'
+import {
+  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+  RUNTIME_CAPABILITIES,
+  RUNTIME_PROTOCOL_VERSION
 } from '../../shared/protocol-version'
 import type {
   RuntimeGraphStatus,
@@ -57,87 +68,146 @@ import type {
   RuntimeMobileSessionCreateTerminalResult,
   RuntimeMobileSessionClientTab,
   RuntimeMobileSessionMarkdownTab,
+  RuntimeMobileSessionTerminalTab,
   RuntimeMobileSessionTabsRemovedResult,
   RuntimeMobileSessionTabsResult,
   RuntimeMobileSessionTabsSnapshot,
-  RuntimeFileListResult,
-  RuntimeFileOpenResult,
-  RuntimeFileReadResult,
   RuntimeSyncWindowGraph,
-  RuntimeWorktreeListResult,
-  BrowserSnapshotResult,
-  BrowserClickResult,
-  BrowserGotoResult,
-  BrowserFillResult,
-  BrowserTypeResult,
-  BrowserSelectResult,
-  BrowserScrollResult,
-  BrowserBackResult,
-  BrowserReloadResult,
-  BrowserProfileCreateResult,
-  BrowserProfileDeleteResult,
-  BrowserProfileListResult,
-  BrowserScreenshotResult,
-  BrowserEvalResult,
-  BrowserTabCurrentResult,
-  BrowserTabListResult,
-  BrowserTabProfileCloneResult,
-  BrowserTabProfileShowResult,
-  BrowserTabSetProfileResult,
-  BrowserTabShowResult,
-  BrowserTabSwitchResult,
-  BrowserHoverResult,
-  BrowserDragResult,
-  BrowserUploadResult,
-  BrowserWaitResult,
-  BrowserCheckResult,
-  BrowserFocusResult,
-  BrowserClearResult,
-  BrowserSelectAllResult,
-  BrowserKeypressResult,
-  BrowserPdfResult,
-  BrowserCookieGetResult,
-  BrowserCookieSetResult,
-  BrowserCookieDeleteResult,
-  BrowserViewportResult,
-  BrowserGeolocationResult,
-  BrowserInterceptEnableResult,
-  BrowserInterceptDisableResult,
-  BrowserCaptureStartResult,
-  BrowserCaptureStopResult,
-  BrowserConsoleResult,
-  BrowserNetworkLogResult
+  RuntimeWorktreeListResult
 } from '../../shared/runtime-types'
+import { RuntimeBrowserCommands } from './orca-runtime-browser'
+import { RuntimeFileCommands } from './orca-runtime-files'
+import { RuntimeGitCommands } from './orca-runtime-git'
+import { joinWorktreeRelativePath } from './runtime-relative-paths'
 import { app, BrowserWindow, ipcMain } from 'electron'
 import type { AgentBrowserBridge } from '../browser/agent-browser-bridge'
-import { browserManager } from '../browser/browser-manager'
-import { BrowserError } from '../browser/cdp-bridge'
-import { browserSessionRegistry } from '../browser/browser-session-registry'
-import { waitForTabRegistration } from '../ipc/browser'
-import { getPRForBranch } from '../github/client'
+import {
+  getPRForBranch,
+  getPullRequestPushTarget,
+  getRepoSlug,
+  getWorkItem,
+  listWorkItems,
+  countWorkItems,
+  getPRChecks,
+  getPRComments,
+  getIssue,
+  resolveReviewThread,
+  getWorkItemByOwnerRepo,
+  updatePRTitle,
+  mergePR,
+  createIssue,
+  updateIssue,
+  addIssueComment,
+  addPRReviewComment,
+  addPRReviewCommentReply,
+  listLabels,
+  listAssignableUsers
+} from '../github/client'
+import { getWorkItemDetails, getPRFileContents } from '../github/work-item-details'
+import { getRateLimit } from '../github/rate-limit'
+import type {
+  GitHubIssueUpdate,
+  GitHubPRFile,
+  GitHubPRReviewCommentInput
+} from '../../shared/types'
+import type { HostedReviewInfo } from '../../shared/hosted-review'
+import { getHostedReviewForBranch as getHostedReviewForBranchFromRepo } from '../source-control/hosted-review'
+import {
+  connect as connectLinear,
+  disconnect as disconnectLinear,
+  getStatus as getLinearStatus,
+  testConnection as testLinearConnection
+} from '../linear/client'
+import {
+  addIssueComment as addLinearIssueComment,
+  createIssue as createLinearIssue,
+  getIssue as getLinearIssue,
+  getIssueComments as getLinearIssueComments,
+  listIssues as listLinearIssues,
+  searchIssues as searchLinearIssues,
+  updateIssue as updateLinearIssue,
+  type LinearListFilter
+} from '../linear/issues'
+import {
+  getTeamLabels as getLinearTeamLabels,
+  getTeamMembers as getLinearTeamMembers,
+  getTeamStates as getLinearTeamStates,
+  listTeams as listLinearTeams
+} from '../linear/teams'
+import {
+  clearProjectItemFieldValue,
+  getProjectViewTable,
+  listAccessibleProjects,
+  listProjectViews,
+  resolveProjectRef,
+  addIssueCommentBySlug,
+  deleteIssueCommentBySlug,
+  listAssignableUsersBySlug,
+  listIssueTypesBySlug,
+  listLabelsBySlug,
+  updateIssueCommentBySlug,
+  updateIssueBySlug,
+  updateIssueTypeBySlug,
+  updateProjectItemFieldValue,
+  updatePullRequestBySlug
+} from '../github/project-view'
+import type {
+  ClearProjectItemFieldArgs,
+  GetProjectViewTableArgs,
+  ListAssignableUsersBySlugArgs,
+  ListIssueTypesBySlugArgs,
+  ListLabelsBySlugArgs,
+  ListProjectViewsArgs,
+  ResolveProjectRefArgs,
+  AddIssueCommentBySlugArgs,
+  DeleteIssueCommentBySlugArgs,
+  UpdateIssueBySlugArgs,
+  UpdateIssueCommentBySlugArgs,
+  UpdateIssueTypeBySlugArgs,
+  UpdateProjectItemFieldArgs,
+  UpdatePullRequestBySlugArgs
+} from '../../shared/github-project-types'
 import {
   getGitUsername,
+  getBaseRefDefault,
   getDefaultBaseRef,
+  getDefaultRemote,
   getBranchConflictKind,
   isGitRepo,
   getRepoName,
   searchBaseRefs,
+  getRemoteCount,
+  normalizeRefSearchQuery,
+  parseAndFilterSearchRefs,
+  parseRemoteCount,
+  resolveDefaultBaseRefViaExec,
+  buildSearchBaseRefsArgv,
   getRemoteDrift,
   getRecentDriftSubjects
 } from '../git/repo'
-import { listWorktrees, addWorktree, removeWorktree } from '../git/worktree'
-import { listQuickOpenFiles } from '../ipc/filesystem-list-files'
-import { resolveAuthorizedPath } from '../ipc/filesystem-auth'
+import { listWorktrees, addWorktree, addSparseWorktree, removeWorktree } from '../git/worktree'
+import { isENOENT } from '../ipc/filesystem-auth'
 import {
   createSetupRunnerScript,
   getEffectiveHooks,
   getEffectiveSetupRunPolicy,
+  hasUnrecognizedOrcaYamlKeys,
   hasHooksFile,
+  loadHooks,
+  parseOrcaYaml,
+  readIssueCommand,
   runHook,
-  shouldRunSetupForCreate
+  shouldRunSetupForCreate,
+  writeIssueCommand
 } from '../hooks'
 import { REPO_COLORS, getDefaultVoiceSettings } from '../../shared/constants'
 import { listRepoWorktrees } from '../repo-worktrees'
+import { createWorktreeSymlinks } from '../ipc/worktree-symlinks'
+import {
+  configureCreatedWorktreePushTarget,
+  prepareWorktreePushTarget
+} from '../ipc/worktree-remote'
+import { normalizeSparseDirectories } from '../ipc/sparse-checkout-directories'
 import type { Store } from '../persistence'
 import type { StatsCollector } from '../stats/collector'
 import { AgentDetector } from '../stats/agent-detector'
@@ -156,8 +226,9 @@ import { invalidateAuthorizedRootsCache } from '../ipc/filesystem-auth'
 import { HeadlessEmulator } from '../daemon/headless-emulator'
 import { killAllProcessesForWorktree } from './worktree-teardown'
 import { MOBILE_SUBSCRIBE_SCROLLBACK_ROWS } from './scrollback-limits'
-import type { IPtyProvider } from '../providers/types'
+import type { IFilesystemProvider, IPtyProvider } from '../providers/types'
 import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
+import { getSshGitProvider } from '../providers/ssh-git-dispatch'
 import type { ClaudeAccountService } from '../claude-accounts/service'
 import type { CodexAccountService } from '../codex-accounts/service'
 import type { RateLimitService } from '../rate-limits/service'
@@ -170,6 +241,8 @@ import type {
   NoteDeleteArgs,
   NoteDeleteResult,
   NoteLinkArgs,
+  NoteLink,
+  NoteLinkKind,
   NoteListArgs,
   NoteListResult,
   NoteMutationResult,
@@ -210,6 +283,8 @@ type RuntimeStore = {
   getRepo: Store['getRepo']
   addRepo: Store['addRepo']
   updateRepo: Store['updateRepo']
+  removeRepo?: Store['removeRepo']
+  reorderRepos?: Store['reorderRepos']
   getAllWorktreeMeta: Store['getAllWorktreeMeta']
   getWorktreeMeta: Store['getWorktreeMeta']
   setWorktreeMeta: Store['setWorktreeMeta']
@@ -222,6 +297,7 @@ type RuntimeStore = {
     refreshLocalBaseRefOnWorktreeCreate: boolean
     branchPrefix: string
     branchPrefixCustom: string
+    experimentalWorktreeSymlinks?: boolean
     mobileAutoRestoreFitMs?: number | null
     voice?: VoiceSettings
   }
@@ -290,6 +366,7 @@ type RuntimePtyController = {
   write(ptyId: string, data: string): boolean
   kill(ptyId: string): boolean
   getForegroundProcess(ptyId: string): Promise<string | null>
+  hasChildProcesses?(ptyId: string): Promise<boolean>
   clearBuffer?(ptyId: string): Promise<void>
   resize?(ptyId: string, cols: number, rows: number): boolean
   listProcesses?(): Promise<{ id: string; cwd: string; title: string }[]>
@@ -304,25 +381,6 @@ type RuntimePtyController = {
   getSize?(ptyId: string): { cols: number; rows: number } | null
 }
 
-const MOBILE_FILE_LIST_LIMIT = 5000
-const MOBILE_FILE_READ_MAX_BYTES = 512 * 1024
-const MOBILE_BINARY_EXTENSIONS = new Set([
-  '.avif',
-  '.bmp',
-  '.gif',
-  '.heic',
-  '.ico',
-  '.jpeg',
-  '.jpg',
-  '.mov',
-  '.mp3',
-  '.mp4',
-  '.pdf',
-  '.png',
-  '.webp',
-  '.zip'
-])
-
 type RuntimeNotifier = {
   worktreesChanged(repoId: string): void
   worktreeBaseStatus?(event: WorktreeBaseStatusEvent): void
@@ -403,38 +461,24 @@ type MessageWaiter = {
   timeout: NodeJS.Timeout | null
 }
 
-type ResolvedWorktree = {
-  id: string
-  repoId: string
-  path: string
-  branch: string
-  linkedIssue: number | null
-  git: {
-    path: string
-    head: string
-    branch: string
-    isBare: boolean
-    isMainWorktree: boolean
-  }
-  displayName: string
-  comment: string
+function omitUndefinedProperties<T extends Record<string, unknown>>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  ) as Partial<T>
 }
 
-type BrowserCommandTargetParams = {
-  worktree?: string
-  page?: string
-}
-
-type ResolvedBrowserCommandTarget = {
-  worktreeId?: string
-  browserPageId?: string
-}
+type ResolvedWorktree = Worktree & { git: GitWorktreeInfo }
 
 type ResolvedWorktreeCache = {
   expiresAt: number
   worktrees: ResolvedWorktree[]
 }
 
+type ResolvedWorktreeInFlight = {
+  generation: number
+  promise: Promise<ResolvedWorktree[]>
+}
+
 export type MobileNotificationEvent = {
   source: 'agent-task-complete' | 'terminal-bell' | 'test'
   title: string
@@ -510,7 +554,8 @@ export class OrcaRuntimeService {
   private notifier: RuntimeNotifier | null = null
   private agentBrowserBridge: AgentBrowserBridge | null = null
   private resolvedWorktreeCache: ResolvedWorktreeCache | null = null
-  private resolvedWorktreeInFlight: Promise<ResolvedWorktree[]> | null = null
+  private resolvedWorktreeInFlight: ResolvedWorktreeInFlight | null = null
+  private resolvedWorktreeGeneration = 0
   private agentDetector: AgentDetector | null = null
   private _orchestrationDb: OrchestrationDb | null = null
   private messageWaitersByHandle = new Map<string, Set<MessageWaiter>>()
@@ -525,6 +570,7 @@ export class OrcaRuntimeService {
     string,
     Set<(event: { mode: 'mobile-fit' | 'desktop-fit'; cols: number; rows: number }) => void>
   >()
+  private driverListeners = new Map<string, Set<(driver: DriverState) => void>>()
   private subscriptionCleanups = new Map<string, () => void>()
   // Why: index of subscriptionIds by per-WebSocket connectionId so the
   // server can sweep all subscriptions for a closing socket without
@@ -814,8 +860,11 @@ export class OrcaRuntimeService {
       authoritativeWindowId: this.authoritativeWindowId,
       liveTabCount: this.tabs.size,
       liveLeafCount: this.leaves.size,
-      protocolVersion: DESKTOP_PROTOCOL_VERSION,
-      minCompatibleMobileVersion: MIN_COMPATIBLE_MOBILE_VERSION
+      runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleRuntimeClientVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+      capabilities: [...RUNTIME_CAPABILITIES],
+      protocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleMobileVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
     }
   }
 
@@ -989,7 +1038,12 @@ export class OrcaRuntimeService {
       throw new Error('tab_not_found')
     }
     if (tab.type === 'terminal') {
-      this.notifier?.closeTerminal(tab.parentTabId)
+      const pty = this.findPtyForMobileTerminalTab(tab)
+      if (pty) {
+        this.ptyController?.kill(pty.ptyId)
+      } else {
+        this.notifier?.closeTerminal(tab.parentTabId)
+      }
     } else {
       this.notifier?.closeSessionTab?.(tab.id, worktreeId)
     }
@@ -1020,117 +1074,112 @@ export class OrcaRuntimeService {
     return await this.notifier.saveMobileMarkdownTab(worktreeId, tabId, baseVersion, content)
   }
 
-  async listMobileFiles(worktreeSelector: string): Promise<RuntimeFileListResult> {
-    if (!this.store) {
-      throw new Error('runtime_unavailable')
+  private readonly fileCommands = new RuntimeFileCommands({
+    getRuntimeId: () => this.runtimeId,
+    requireStore: () => this.requireStore(),
+    resolveWorktreeSelector: (selector) => this.resolveWorktreeSelector(selector),
+    resolveRuntimeGitTarget: (selector) => this.resolveRuntimeGitTarget(selector),
+    openFile: (worktreeId, filePath, relativePath) => {
+      if (!this.notifier?.openFile) {
+        throw new Error('renderer_unavailable')
+      }
+      this.notifier.openFile(worktreeId, filePath, relativePath)
     }
+  })
+
+  listMobileFiles: RuntimeFileCommands['listMobileFiles'] = this.fileCommands.listMobileFiles.bind(
+    this.fileCommands
+  )
+  openMobileFile: RuntimeFileCommands['openMobileFile'] = this.fileCommands.openMobileFile.bind(
+    this.fileCommands
+  )
+  readMobileFile: RuntimeFileCommands['readMobileFile'] = this.fileCommands.readMobileFile.bind(
+    this.fileCommands
+  )
+  readFileExplorerDir: RuntimeFileCommands['readFileExplorerDir'] =
+    this.fileCommands.readFileExplorerDir.bind(this.fileCommands)
+  watchFileExplorer: RuntimeFileCommands['watchFileExplorer'] =
+    this.fileCommands.watchFileExplorer.bind(this.fileCommands)
+  readFileExplorerPreview: RuntimeFileCommands['readFileExplorerPreview'] =
+    this.fileCommands.readFileExplorerPreview.bind(this.fileCommands)
+  writeFileExplorerFile: RuntimeFileCommands['writeFileExplorerFile'] =
+    this.fileCommands.writeFileExplorerFile.bind(this.fileCommands)
+  writeFileExplorerFileBase64: RuntimeFileCommands['writeFileExplorerFileBase64'] =
+    this.fileCommands.writeFileExplorerFileBase64.bind(this.fileCommands)
+  writeFileExplorerFileBase64Chunk: RuntimeFileCommands['writeFileExplorerFileBase64Chunk'] =
+    this.fileCommands.writeFileExplorerFileBase64Chunk.bind(this.fileCommands)
+  createFileExplorerFile: RuntimeFileCommands['createFileExplorerFile'] =
+    this.fileCommands.createFileExplorerFile.bind(this.fileCommands)
+  createFileExplorerDir: RuntimeFileCommands['createFileExplorerDir'] =
+    this.fileCommands.createFileExplorerDir.bind(this.fileCommands)
+  createFileExplorerDirNoClobber: RuntimeFileCommands['createFileExplorerDirNoClobber'] =
+    this.fileCommands.createFileExplorerDirNoClobber.bind(this.fileCommands)
+  commitFileExplorerUpload: RuntimeFileCommands['commitFileExplorerUpload'] =
+    this.fileCommands.commitFileExplorerUpload.bind(this.fileCommands)
+  renameFileExplorerPath: RuntimeFileCommands['renameFileExplorerPath'] =
+    this.fileCommands.renameFileExplorerPath.bind(this.fileCommands)
+  copyFileExplorerPath: RuntimeFileCommands['copyFileExplorerPath'] =
+    this.fileCommands.copyFileExplorerPath.bind(this.fileCommands)
+  deleteFileExplorerPath: RuntimeFileCommands['deleteFileExplorerPath'] =
+    this.fileCommands.deleteFileExplorerPath.bind(this.fileCommands)
+  searchRuntimeFiles: RuntimeFileCommands['searchRuntimeFiles'] =
+    this.fileCommands.searchRuntimeFiles.bind(this.fileCommands)
+  listRuntimeFiles: RuntimeFileCommands['listRuntimeFiles'] =
+    this.fileCommands.listRuntimeFiles.bind(this.fileCommands)
+  listRuntimeMarkdownDocuments: RuntimeFileCommands['listRuntimeMarkdownDocuments'] =
+    this.fileCommands.listRuntimeMarkdownDocuments.bind(this.fileCommands)
+  statRuntimeFile: RuntimeFileCommands['statRuntimeFile'] = this.fileCommands.statRuntimeFile.bind(
+    this.fileCommands
+  )
+
+  private readonly gitCommands = new RuntimeGitCommands({
+    resolveRuntimeGitTarget: (selector) => this.resolveRuntimeGitTarget(selector)
+  })
+
+  getRuntimeGitStatus: RuntimeGitCommands['getRuntimeGitStatus'] =
+    this.gitCommands.getRuntimeGitStatus.bind(this.gitCommands)
+  getRuntimeGitConflictOperation: RuntimeGitCommands['getRuntimeGitConflictOperation'] =
+    this.gitCommands.getRuntimeGitConflictOperation.bind(this.gitCommands)
+  getRuntimeGitDiff: RuntimeGitCommands['getRuntimeGitDiff'] =
+    this.gitCommands.getRuntimeGitDiff.bind(this.gitCommands)
+  getRuntimeGitBranchCompare: RuntimeGitCommands['getRuntimeGitBranchCompare'] =
+    this.gitCommands.getRuntimeGitBranchCompare.bind(this.gitCommands)
+  getRuntimeGitUpstreamStatus: RuntimeGitCommands['getRuntimeGitUpstreamStatus'] =
+    this.gitCommands.getRuntimeGitUpstreamStatus.bind(this.gitCommands)
+  fetchRuntimeGit: RuntimeGitCommands['fetchRuntimeGit'] = this.gitCommands.fetchRuntimeGit.bind(
+    this.gitCommands
+  )
+  pullRuntimeGit: RuntimeGitCommands['pullRuntimeGit'] = this.gitCommands.pullRuntimeGit.bind(
+    this.gitCommands
+  )
+  pushRuntimeGit: RuntimeGitCommands['pushRuntimeGit'] = this.gitCommands.pushRuntimeGit.bind(
+    this.gitCommands
+  )
+  getRuntimeGitBranchDiff: RuntimeGitCommands['getRuntimeGitBranchDiff'] =
+    this.gitCommands.getRuntimeGitBranchDiff.bind(this.gitCommands)
+  commitRuntimeGit: RuntimeGitCommands['commitRuntimeGit'] = this.gitCommands.commitRuntimeGit.bind(
+    this.gitCommands
+  )
+  stageRuntimeGitPath: RuntimeGitCommands['stageRuntimeGitPath'] =
+    this.gitCommands.stageRuntimeGitPath.bind(this.gitCommands)
+  unstageRuntimeGitPath: RuntimeGitCommands['unstageRuntimeGitPath'] =
+    this.gitCommands.unstageRuntimeGitPath.bind(this.gitCommands)
+  bulkStageRuntimeGitPaths: RuntimeGitCommands['bulkStageRuntimeGitPaths'] =
+    this.gitCommands.bulkStageRuntimeGitPaths.bind(this.gitCommands)
+  bulkUnstageRuntimeGitPaths: RuntimeGitCommands['bulkUnstageRuntimeGitPaths'] =
+    this.gitCommands.bulkUnstageRuntimeGitPaths.bind(this.gitCommands)
+  discardRuntimeGitPath: RuntimeGitCommands['discardRuntimeGitPath'] =
+    this.gitCommands.discardRuntimeGitPath.bind(this.gitCommands)
+  getRuntimeGitRemoteFileUrl: RuntimeGitCommands['getRuntimeGitRemoteFileUrl'] =
+    this.gitCommands.getRuntimeGitRemoteFileUrl.bind(this.gitCommands)
+
+  private async resolveRuntimeGitTarget(
+    worktreeSelector: string
+  ): Promise<{ worktree: ResolvedWorktree; connectionId?: string }> {
+    const store = this.requireStore()
     const worktree = await this.resolveWorktreeSelector(worktreeSelector)
-    const repo = this.store.getRepo(worktree.repoId)
-    const connectionId = repo?.connectionId ?? undefined
-    const files = connectionId
-      ? await this.listRemoteMobileFiles(worktree.path, connectionId)
-      : await listQuickOpenFiles(worktree.path, this.store as unknown as Store)
-    const entries = files
-      .filter((relativePath) => isSafeMobileRelativePath(relativePath))
-      .sort((a, b) => a.localeCompare(b))
-      .slice(0, MOBILE_FILE_LIST_LIMIT)
-      .map((relativePath) => ({
-        relativePath,
-        basename: basenameFromRelativePath(relativePath),
-        kind: isMobileBinaryPath(relativePath) ? ('binary' as const) : ('text' as const)
-      }))
-
-    return {
-      worktree: worktree.id,
-      rootPath: worktree.path,
-      files: entries,
-      totalCount: files.length,
-      truncated: files.length > MOBILE_FILE_LIST_LIMIT
-    }
-  }
-
-  async openMobileFile(
-    worktreeSelector: string,
-    relativePath: string
-  ): Promise<RuntimeFileOpenResult> {
-    if (!this.store) {
-      throw new Error('runtime_unavailable')
-    }
-    const worktree = await this.resolveWorktreeSelector(worktreeSelector)
-    if (!isSafeMobileRelativePath(relativePath)) {
-      throw new Error('invalid_relative_path')
-    }
-    const kind = isMobileBinaryPath(relativePath)
-      ? 'binary'
-      : isMobileMarkdownPath(relativePath)
-        ? 'markdown'
-        : 'text'
-    if (kind === 'binary') {
-      return { worktree: worktree.id, relativePath, kind, opened: false }
-    }
-    if (!this.notifier?.openFile) {
-      throw new Error('renderer_unavailable')
-    }
-    const filePath = joinWorktreeRelativePath(worktree.path, relativePath)
-    this.notifier.openFile(worktree.id, filePath, relativePath)
-    return { worktree: worktree.id, relativePath, kind, opened: true }
-  }
-
-  async readMobileFile(
-    worktreeSelector: string,
-    relativePath: string
-  ): Promise<RuntimeFileReadResult> {
-    if (!this.store) {
-      throw new Error('runtime_unavailable')
-    }
-    const worktree = await this.resolveWorktreeSelector(worktreeSelector)
-    if (!isSafeMobileRelativePath(relativePath)) {
-      throw new Error('invalid_relative_path')
-    }
-    if (isMobileBinaryPath(relativePath)) {
-      throw new Error('binary_file')
-    }
-
-    const repo = this.store.getRepo(worktree.repoId)
-    const filePath = joinWorktreeRelativePath(worktree.path, relativePath)
-    const content = repo?.connectionId
-      ? await this.readRemoteMobileFile(filePath, repo.connectionId)
-      : await readLocalMobileFile(filePath, this.store as unknown as Store)
-    const truncated = truncateMobileFilePreview(content)
-
-    return {
-      worktree: worktree.id,
-      relativePath,
-      content: truncated.content,
-      truncated: truncated.truncated,
-      byteLength: truncated.byteLength
-    }
-  }
-
-  private async listRemoteMobileFiles(rootPath: string, connectionId: string): Promise<string[]> {
-    const provider = getSshFilesystemProvider(connectionId)
-    if (!provider) {
-      return []
-    }
-    return provider.listFiles(rootPath)
-  }
-
-  private async readRemoteMobileFile(filePath: string, connectionId: string): Promise<string> {
-    const provider = getSshFilesystemProvider(connectionId)
-    if (!provider) {
-      throw new Error('remote_filesystem_unavailable')
-    }
-    const fileStat = await provider.stat(filePath)
-    // Why: the SSH filesystem API does not expose ranged reads here, so reject
-    // oversized remote previews instead of streaming a large file just to trim it.
-    if (fileStat.size > MOBILE_FILE_READ_MAX_BYTES) {
-      throw new Error('file_too_large')
-    }
-    const result = await provider.readFile(filePath)
-    if (result.isBinary) {
-      throw new Error('binary_file')
-    }
-    return result.content
+    const repo = store.getRepo(worktree.repoId)
+    return { worktree, connectionId: repo?.connectionId ?? undefined }
   }
 
   onMobileSessionTabsChanged(
@@ -1319,6 +1368,21 @@ export class OrcaRuntimeService {
     }
   }
 
+  subscribeToDriverChanges(ptyId: string, listener: (driver: DriverState) => void): () => void {
+    let listeners = this.driverListeners.get(ptyId)
+    if (!listeners) {
+      listeners = new Set()
+      this.driverListeners.set(ptyId, listeners)
+    }
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+      if (listeners.size === 0) {
+        this.driverListeners.delete(ptyId)
+      }
+    }
+  }
+
   private notifyFitOverrideListeners(
     ptyId: string,
     mode: 'mobile-fit' | 'desktop-fit',
@@ -1619,9 +1683,7 @@ export class OrcaRuntimeService {
     // listener leaks in dataListeners and duplicates every PTY data event.
     const existing = this.subscriptionCleanups.get(subscriptionId)
     if (existing) {
-      existing()
-      // Why: existing() already evicts itself from the per-connection index
-      // via cleanupSubscription, so no extra bookkeeping is needed here.
+      this.cleanupSubscription(subscriptionId)
     }
     this.subscriptionCleanups.set(subscriptionId, cleanup)
     if (connectionId) {
@@ -2318,6 +2380,12 @@ export class OrcaRuntimeService {
       this.currentDriver.set(ptyId, next)
     }
     this.notifier?.terminalDriverChanged(ptyId, next)
+    const listeners = this.driverListeners.get(ptyId)
+    if (listeners) {
+      for (const listener of listeners) {
+        listener(next)
+      }
+    }
   }
 
   // Why: invoked from mobile RPC method handlers (terminal.send / setDisplayMode /
@@ -2398,6 +2466,36 @@ export class OrcaRuntimeService {
     return true
   }
 
+  // Why: remote desktop clients do not have the local `pty:resize` IPC path.
+  // Their measured xterm size still has to resize the source PTY so TUIs
+  // reflow to the visible client dimensions.
+  async updateDesktopViewport(
+    ptyId: string,
+    viewport: { cols: number; rows: number }
+  ): Promise<boolean> {
+    if (
+      this.isResizeSuppressed() ||
+      this.getDriver(ptyId).kind === 'mobile' ||
+      this.terminalFitOverrides.has(ptyId)
+    ) {
+      return false
+    }
+    const cols = Math.max(20, Math.min(240, Math.round(viewport.cols)))
+    const rows = Math.max(8, Math.min(120, Math.round(viewport.rows)))
+    let resized = false
+    try {
+      resized = this.ptyController?.resize?.(ptyId, cols, rows) ?? false
+    } catch {
+      return false
+    }
+    if (!resized) {
+      return false
+    }
+    this.resizeHeadlessTerminal(ptyId, cols, rows)
+    this.onExternalPtyResize(ptyId, cols, rows)
+    return true
+  }
+
   // Why: invoked from `runtime:restoreTerminalFit` IPC (the desktop "Take
   // back" / "Restore" button). Forces the PTY back to desktop dims and
   // flips the driver to `desktop`, suppressing further mobile-driven dim
@@ -3867,11 +3965,16 @@ export class OrcaRuntimeService {
     if (!this.store) {
       throw new Error('runtime_unavailable')
     }
+    if (!isAbsolute(path)) {
+      // Why: remote clients may run in a different cwd than the server. Require
+      // server-side repo paths to be explicit so `orca serve` cwd is irrelevant.
+      throw new Error('Repo path must be an absolute path')
+    }
     if (kind === 'git' && !isGitRepo(path)) {
       throw new Error(`Not a valid git repository: ${path}`)
     }
 
-    const existing = this.store.getRepos().find((repo) => repo.path === path)
+    const existing = this.store.getRepos().find((repo) => runtimePathsEqual(repo.path, path))
     if (existing) {
       return existing
     }
@@ -3890,6 +3993,182 @@ export class OrcaRuntimeService {
     return this.store.getRepo(repo.id) ?? repo
   }
 
+  async createRepo(
+    parentPath: string,
+    name: string,
+    kind: 'git' | 'folder' = 'git'
+  ): Promise<{ repo: Repo } | { error: string }> {
+    if (!this.store) {
+      throw new Error('runtime_unavailable')
+    }
+    const trimmedName = name.trim()
+    const trimmedParentPath = parentPath.trim()
+    const repoKind: 'git' | 'folder' = kind === 'folder' ? 'folder' : 'git'
+    if (!trimmedName) {
+      return { error: 'Name cannot be empty' }
+    }
+    if (/[\\/]/.test(trimmedName) || trimmedName === '.' || trimmedName === '..') {
+      return { error: 'Name cannot contain slashes or be "." / ".."' }
+    }
+    if (!trimmedParentPath) {
+      return { error: 'Parent directory is required' }
+    }
+    if (!isAbsolute(trimmedParentPath)) {
+      return { error: 'Parent directory must be an absolute path' }
+    }
+
+    const targetPath = join(trimmedParentPath, trimmedName)
+    const existing = this.store.getRepos().find((repo) => runtimePathsEqual(repo.path, targetPath))
+    if (existing) {
+      return { repo: existing }
+    }
+
+    let createdDir = false
+    try {
+      const existingStat = await stat(targetPath).catch((error: unknown) => {
+        if (isENOENT(error)) {
+          return null
+        }
+        throw error
+      })
+      if (existingStat) {
+        if (!existingStat.isDirectory()) {
+          return { error: `"${trimmedName}" already exists at this location and is not a folder.` }
+        }
+        const entries = await readdir(targetPath)
+        if (entries.length > 0) {
+          return { error: `"${trimmedName}" already exists at this location and is not empty.` }
+        }
+      } else {
+        await mkdir(targetPath, { recursive: false })
+        createdDir = true
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return { error: `Failed to prepare directory: ${message}` }
+    }
+
+    if (repoKind === 'git') {
+      let step: 'init' | 'commit' = 'init'
+      try {
+        await gitExecFileAsync(['init'], { cwd: targetPath })
+        step = 'commit'
+        await gitExecFileAsync(['commit', '--allow-empty', '-m', 'Initial commit'], {
+          cwd: targetPath
+        })
+      } catch (error) {
+        if (createdDir) {
+          await rm(targetPath, { recursive: true, force: true }).catch(() => {})
+        } else if (step === 'commit') {
+          await rm(join(targetPath, '.git'), { recursive: true, force: true }).catch(() => {})
+        }
+        const message = error instanceof Error ? error.message : String(error)
+        if (
+          step === 'commit' &&
+          /Please tell me who you are|user\.name|user\.email/i.test(message)
+        ) {
+          return {
+            error:
+              'Git author identity is not configured. Run `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"`, then try again.'
+          }
+        }
+        const stepLabel =
+          step === 'init'
+            ? 'Failed to initialize git repository'
+            : 'Failed to create initial commit'
+        return { error: `${stepLabel}: ${message}` }
+      }
+    }
+
+    const raceWinner = this.store
+      .getRepos()
+      .find((repo) => runtimePathsEqual(repo.path, targetPath))
+    if (raceWinner) {
+      return { repo: raceWinner }
+    }
+
+    const repo: Repo = {
+      id: randomUUID(),
+      path: targetPath,
+      displayName: trimmedName,
+      badgeColor: REPO_COLORS[this.store.getRepos().length % REPO_COLORS.length],
+      addedAt: Date.now(),
+      kind: repoKind
+    }
+    this.store.addRepo(repo)
+    invalidateAuthorizedRootsCache()
+    this.invalidateResolvedWorktreeCache()
+    this.notifier?.reposChanged()
+    return { repo: this.store.getRepo(repo.id) ?? repo }
+  }
+
+  async cloneRepo(url: string, destination: string): Promise<Repo> {
+    if (!this.store) {
+      throw new Error('runtime_unavailable')
+    }
+    const trimmedUrl = url.trim()
+    const trimmedDestination = destination.trim()
+    const repoName = basename(trimmedUrl.replace(/\.git\/?$/, ''))
+    if (!repoName) {
+      throw new Error('Could not determine repository name from URL')
+    }
+    if (!trimmedDestination) {
+      throw new Error('Clone destination is required')
+    }
+    if (!isAbsolute(trimmedDestination)) {
+      throw new Error('Clone destination must be an absolute path')
+    }
+    await mkdir(trimmedDestination, { recursive: true })
+    const clonePath = join(trimmedDestination, repoName)
+    await new Promise<void>((resolve, reject) => {
+      const proc = wslAwareSpawn('git', ['clone', '--progress', '--', trimmedUrl, clonePath], {
+        cwd: trimmedDestination,
+        stdio: ['ignore', 'ignore', 'pipe']
+      })
+      let stderrTail = ''
+      proc.stderr?.on('data', (chunk: Buffer) => {
+        stderrTail = (stderrTail + chunk.toString()).slice(-4096)
+      })
+      proc.on('error', (error) => reject(new Error(`Clone failed: ${error.message}`)))
+      proc.on('close', (code, signal) => {
+        if (signal === 'SIGTERM') {
+          reject(new Error('Clone aborted'))
+        } else if (code === 0) {
+          resolve()
+        } else {
+          const lastLine = stderrTail.trim().split('\n').pop() ?? 'unknown error'
+          reject(new Error(`Clone failed: ${lastLine}`))
+        }
+      })
+    })
+
+    const existing = this.store.getRepos().find((repo) => runtimePathsEqual(repo.path, clonePath))
+    if (existing) {
+      if (isFolderRepo(existing)) {
+        const updated = this.store.updateRepo(existing.id, { kind: 'git' })
+        if (updated) {
+          this.notifier?.reposChanged()
+          return updated
+        }
+      }
+      return existing
+    }
+
+    const repo: Repo = {
+      id: randomUUID(),
+      path: clonePath,
+      displayName: getRepoName(clonePath),
+      badgeColor: REPO_COLORS[this.store.getRepos().length % REPO_COLORS.length],
+      addedAt: Date.now(),
+      kind: 'git'
+    }
+    this.store.addRepo(repo)
+    invalidateAuthorizedRootsCache()
+    this.invalidateResolvedWorktreeCache()
+    this.notifier?.reposChanged()
+    return this.store.getRepo(repo.id) ?? repo
+  }
+
   async showRepo(repoSelector: string): Promise<Repo> {
     return await this.resolveRepoSelector(repoSelector)
   }
@@ -3911,6 +4190,75 @@ export class OrcaRuntimeService {
     return updated
   }
 
+  async updateRepo(
+    repoSelector: string,
+    updates: Partial<
+      Pick<
+        Repo,
+        | 'displayName'
+        | 'badgeColor'
+        | 'hookSettings'
+        | 'worktreeBaseRef'
+        | 'kind'
+        | 'symlinkPaths'
+        | 'issueSourcePreference'
+      >
+    >
+  ): Promise<Repo> {
+    if (!this.store) {
+      throw new Error('runtime_unavailable')
+    }
+    const repo = await this.resolveRepoSelector(repoSelector)
+    const updated = this.store.updateRepo(repo.id, omitUndefinedProperties(updates))
+    if (!updated) {
+      throw new Error('repo_not_found')
+    }
+    this.invalidateResolvedWorktreeCache()
+    this.notifier?.reposChanged()
+    return updated
+  }
+
+  async removeRepo(repoSelector: string): Promise<{ removed: true }> {
+    if (!this.store?.removeRepo) {
+      throw new Error('runtime_unavailable')
+    }
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.store.removeRepo(repo.id)
+    this.invalidateResolvedWorktreeCache()
+    invalidateAuthorizedRootsCache()
+    this.notifier?.reposChanged()
+    return { removed: true }
+  }
+
+  async inspectTerminalProcess(
+    terminalSelector: string
+  ): Promise<{ foregroundProcess: string | null; hasChildProcesses: boolean }> {
+    const leaf = this.resolveLeafForHandle(terminalSelector)
+    if (!leaf?.ptyId || !this.ptyController) {
+      return { foregroundProcess: null, hasChildProcesses: false }
+    }
+    const foregroundProcess = await this.ptyController.getForegroundProcess(leaf.ptyId)
+    const hasChildProcesses =
+      (await this.ptyController.hasChildProcesses?.(leaf.ptyId).catch(() => false)) ?? false
+    return { foregroundProcess, hasChildProcesses }
+  }
+
+  reorderRepos(orderedIds: string[]): { status: 'applied' | 'rejected' } {
+    if (!this.store?.reorderRepos) {
+      throw new Error('runtime_unavailable')
+    }
+    // Why: remote clients can race repo add/remove on the server just like
+    // local drag-reorder can race another window. Let the store validate the
+    // full permutation and signal a resync-worthy rejection.
+    const applied = this.store.reorderRepos(orderedIds)
+    if (!applied) {
+      return { status: 'rejected' }
+    }
+    this.invalidateResolvedWorktreeCache()
+    this.notifier?.reposChanged()
+    return { status: 'applied' }
+  }
+
   async searchRepoRefs(
     repoSelector: string,
     query: string,
@@ -3926,15 +4274,462 @@ export class OrcaRuntimeService {
         truncated: false
       }
     }
-    const refs = await searchBaseRefs(repo.path, query, limit + 1)
+    const refs = repo.connectionId
+      ? await this.searchRemoteRepoRefs(repo, query, limit + 1)
+      : await searchBaseRefs(repo.path, query, limit + 1)
     return {
       refs: refs.slice(0, limit),
       truncated: refs.length > limit
     }
   }
 
+  async getRepoBaseRefDefault(
+    repoSelector: string
+  ): Promise<{ defaultBaseRef: string | null; remoteCount: number }> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    if (isFolderRepo(repo)) {
+      return { defaultBaseRef: null, remoteCount: 0 }
+    }
+    if (repo.connectionId) {
+      return this.getRemoteRepoBaseRefDefault(repo)
+    }
+    const [defaultBaseRef, remoteCount] = await Promise.all([
+      getBaseRefDefault(repo.path),
+      getRemoteCount(repo.path)
+    ])
+    return { defaultBaseRef, remoteCount }
+  }
+
+  private async getRemoteRepoBaseRefDefault(
+    repo: Repo
+  ): Promise<{ defaultBaseRef: string | null; remoteCount: number }> {
+    const provider = repo.connectionId ? getSshGitProvider(repo.connectionId) : null
+    if (!provider) {
+      return { defaultBaseRef: null, remoteCount: 0 }
+    }
+    const [defaultBaseRef, remoteCount] = await Promise.all([
+      resolveDefaultBaseRefViaExec(async (argv) => {
+        try {
+          return await provider.exec(argv, repo.path)
+        } catch (err) {
+          if (argv[0] === 'symbolic-ref') {
+            console.warn('[runtime:repo.baseRefDefault] SSH symbolic-ref failed', {
+              path: repo.path,
+              err
+            })
+          }
+          throw err
+        }
+      }),
+      provider
+        .exec(['remote'], repo.path)
+        .then((result) => parseRemoteCount(result.stdout))
+        .catch((err) => {
+          console.warn('[runtime:repo.baseRefDefault] SSH git remote count failed', {
+            path: repo.path,
+            err
+          })
+          return 0
+        })
+    ])
+    return { defaultBaseRef, remoteCount }
+  }
+
+  private async searchRemoteRepoRefs(repo: Repo, query: string, limit: number): Promise<string[]> {
+    const provider = repo.connectionId ? getSshGitProvider(repo.connectionId) : null
+    if (!provider) {
+      return []
+    }
+    const normalizedQuery = normalizeRefSearchQuery(query)
+    if (!normalizedQuery) {
+      return []
+    }
+    try {
+      const result = await provider.exec(buildSearchBaseRefsArgv(normalizedQuery), repo.path)
+      return parseAndFilterSearchRefs(result.stdout, limit)
+    } catch (err) {
+      console.warn('[runtime:repo.searchRefs] SSH for-each-ref failed', {
+        path: repo.path,
+        err
+      })
+      return []
+    }
+  }
+
+  private assertHostIntegrationRepoIsLocal(repo: Repo, operation: string): void {
+    if (repo.connectionId) {
+      throw new Error(`${operation}_unsupported_for_ssh_repo`)
+    }
+  }
+
+  async getRepoSlug(repoSelector: string): Promise<{ owner: string; repo: string } | null> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_slug')
+    return getRepoSlug(repo.path)
+  }
+
+  async listRepoWorkItems(
+    repoSelector: string,
+    limit?: number,
+    query?: string,
+    before?: string
+  ): Promise<Awaited<ReturnType<typeof listWorkItems>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_work_items')
+    return listWorkItems(repo.path, limit, query, before, repo.issueSourcePreference)
+  }
+
+  async getRepoWorkItem(
+    repoSelector: string,
+    number: number,
+    type?: 'issue' | 'pr'
+  ): Promise<Awaited<ReturnType<typeof getWorkItem>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_work_item')
+    return getWorkItem(repo.path, number, type)
+  }
+
+  async getRepoWorkItemByOwnerRepo(
+    repoSelector: string,
+    ownerRepo: { owner: string; repo: string },
+    number: number,
+    type: 'issue' | 'pr'
+  ): Promise<Awaited<ReturnType<typeof getWorkItemByOwnerRepo>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_work_item')
+    return getWorkItemByOwnerRepo(repo.path, ownerRepo, number, type)
+  }
+
+  async getRepoWorkItemDetails(
+    repoSelector: string,
+    number: number,
+    type?: 'issue' | 'pr'
+  ): Promise<Awaited<ReturnType<typeof getWorkItemDetails>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_work_item_details')
+    return getWorkItemDetails(repo.path, number, type)
+  }
+
+  async countRepoWorkItems(repoSelector: string, query?: string): Promise<number> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_work_items')
+    return countWorkItems(repo.path, query, repo.issueSourcePreference)
+  }
+
+  async listRepoLabels(repoSelector: string): Promise<Awaited<ReturnType<typeof listLabels>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_labels')
+    return listLabels(repo.path, repo.issueSourcePreference)
+  }
+
+  async listRepoAssignableUsers(
+    repoSelector: string
+  ): Promise<Awaited<ReturnType<typeof listAssignableUsers>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_assignable_users')
+    return listAssignableUsers(repo.path, repo.issueSourcePreference)
+  }
+
+  getGitHubRateLimit(options?: {
+    force?: boolean
+  }): Promise<Awaited<ReturnType<typeof getRateLimit>>> {
+    return getRateLimit(options)
+  }
+
+  async getRepoPRForBranch(
+    repoSelector: string,
+    branch: string,
+    linkedPRNumber?: number | null
+  ): Promise<Awaited<ReturnType<typeof getPRForBranch>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr')
+    return getPRForBranch(repo.path, branch, linkedPRNumber ?? null)
+  }
+
+  async getHostedReviewForBranch(args: {
+    repoSelector: string
+    branch: string
+    linkedGitHubPR?: number | null
+    linkedGitLabMR?: number | null
+    linkedBitbucketPR?: number | null
+  }): Promise<HostedReviewInfo | null> {
+    const repo = await this.resolveRepoSelector(args.repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'hosted_review')
+    const review = await getHostedReviewForBranchFromRepo({
+      repoPath: repo.path,
+      branch: args.branch,
+      linkedGitHubPR: args.linkedGitHubPR ?? null,
+      linkedGitLabMR: args.linkedGitLabMR ?? null,
+      linkedBitbucketPR: args.linkedBitbucketPR ?? null
+    })
+    if (review?.provider === 'github' && this.stats && !this.stats.hasCountedPR(review.url)) {
+      this.stats.record({
+        type: 'pr_created',
+        at: Date.now(),
+        repoId: repo.id,
+        meta: { prNumber: review.number, prUrl: review.url }
+      })
+    }
+    return review
+  }
+
+  async getRepoIssue(
+    repoSelector: string,
+    number: number
+  ): Promise<Awaited<ReturnType<typeof getIssue>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_issue')
+    return getIssue(repo.path, number)
+  }
+
+  async getRepoPRChecks(
+    repoSelector: string,
+    prNumber: number,
+    headSha?: string,
+    options?: { noCache?: boolean }
+  ): Promise<Awaited<ReturnType<typeof getPRChecks>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_checks')
+    return getPRChecks(repo.path, prNumber, headSha, options)
+  }
+
+  async getRepoPRComments(
+    repoSelector: string,
+    prNumber: number,
+    options?: { noCache?: boolean }
+  ): Promise<Awaited<ReturnType<typeof getPRComments>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_comments')
+    return getPRComments(repo.path, prNumber, options)
+  }
+
+  async getRepoPRFileContents(
+    repoSelector: string,
+    args: {
+      prNumber: number
+      path: string
+      oldPath?: string
+      status: GitHubPRFile['status']
+      headSha: string
+      baseSha: string
+    }
+  ): Promise<Awaited<ReturnType<typeof getPRFileContents>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_file_contents')
+    return getPRFileContents({ repoPath: repo.path, ...args })
+  }
+
+  async resolveRepoReviewThread(
+    repoSelector: string,
+    threadId: string,
+    resolve: boolean
+  ): Promise<Awaited<ReturnType<typeof resolveReviewThread>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_review_thread')
+    return resolveReviewThread(repo.path, threadId, resolve)
+  }
+
+  async updateRepoPRTitle(
+    repoSelector: string,
+    prNumber: number,
+    title: string
+  ): Promise<Awaited<ReturnType<typeof updatePRTitle>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_title')
+    return updatePRTitle(repo.path, prNumber, title)
+  }
+
+  async mergeRepoPR(
+    repoSelector: string,
+    prNumber: number,
+    method?: 'merge' | 'squash' | 'rebase'
+  ): Promise<Awaited<ReturnType<typeof mergePR>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_merge')
+    return mergePR(repo.path, prNumber, method)
+  }
+
+  async createRepoIssue(
+    repoSelector: string,
+    title: string,
+    body: string
+  ): Promise<Awaited<ReturnType<typeof createIssue>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_issue_create')
+    return createIssue(repo.path, title, body, repo.issueSourcePreference)
+  }
+
+  async updateRepoIssue(
+    repoSelector: string,
+    number: number,
+    updates: GitHubIssueUpdate
+  ): Promise<Awaited<ReturnType<typeof updateIssue>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_issue_update')
+    return updateIssue(repo.path, number, updates)
+  }
+
+  async addRepoIssueComment(
+    repoSelector: string,
+    number: number,
+    body: string
+  ): Promise<Awaited<ReturnType<typeof addIssueComment>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_issue_comment')
+    return addIssueComment(repo.path, number, body)
+  }
+
+  async addRepoPRReviewComment(
+    repoSelector: string,
+    args: Omit<GitHubPRReviewCommentInput, 'repoPath'>
+  ): Promise<Awaited<ReturnType<typeof addPRReviewComment>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_review_comment')
+    return addPRReviewComment({ repoPath: repo.path, ...args })
+  }
+
+  async addRepoPRReviewCommentReply(
+    repoSelector: string,
+    args: {
+      prNumber: number
+      commentId: number
+      body: string
+      threadId?: string
+      path?: string
+      line?: number
+    }
+  ): Promise<Awaited<ReturnType<typeof addPRReviewCommentReply>>> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'repo_pr_review_comment_reply')
+    return addPRReviewCommentReply(
+      repo.path,
+      args.prNumber,
+      args.commentId,
+      args.body,
+      args.threadId,
+      args.path,
+      args.line
+    )
+  }
+
+  async listGitHubProjects(): Promise<Awaited<ReturnType<typeof listAccessibleProjects>>> {
+    return listAccessibleProjects()
+  }
+
+  async listGitHubLabelsBySlug(
+    args: ListLabelsBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof listLabelsBySlug>>> {
+    return listLabelsBySlug(args)
+  }
+
+  async listGitHubAssignableUsersBySlug(
+    args: ListAssignableUsersBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof listAssignableUsersBySlug>>> {
+    return listAssignableUsersBySlug(args)
+  }
+
+  async listGitHubIssueTypesBySlug(
+    args: ListIssueTypesBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof listIssueTypesBySlug>>> {
+    return listIssueTypesBySlug(args)
+  }
+
+  async resolveGitHubProjectRef(
+    args: ResolveProjectRefArgs
+  ): Promise<Awaited<ReturnType<typeof resolveProjectRef>>> {
+    return resolveProjectRef(args)
+  }
+
+  async listGitHubProjectViews(
+    args: ListProjectViewsArgs
+  ): Promise<Awaited<ReturnType<typeof listProjectViews>>> {
+    return listProjectViews(args)
+  }
+
+  async getGitHubProjectViewTable(
+    args: GetProjectViewTableArgs
+  ): Promise<Awaited<ReturnType<typeof getProjectViewTable>>> {
+    return getProjectViewTable(args)
+  }
+
+  async updateGitHubProjectItemField(
+    args: UpdateProjectItemFieldArgs
+  ): Promise<Awaited<ReturnType<typeof updateProjectItemFieldValue>>> {
+    return updateProjectItemFieldValue(args)
+  }
+
+  async clearGitHubProjectItemField(
+    args: ClearProjectItemFieldArgs
+  ): Promise<Awaited<ReturnType<typeof clearProjectItemFieldValue>>> {
+    return clearProjectItemFieldValue(args)
+  }
+
+  async updateGitHubIssueBySlug(
+    args: UpdateIssueBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof updateIssueBySlug>>> {
+    return updateIssueBySlug(args)
+  }
+
+  async updateGitHubPullRequestBySlug(
+    args: UpdatePullRequestBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof updatePullRequestBySlug>>> {
+    return updatePullRequestBySlug(args)
+  }
+
+  async updateGitHubIssueTypeBySlug(
+    args: UpdateIssueTypeBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof updateIssueTypeBySlug>>> {
+    return updateIssueTypeBySlug(args)
+  }
+
+  async addGitHubIssueCommentBySlug(
+    args: AddIssueCommentBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof addIssueCommentBySlug>>> {
+    return addIssueCommentBySlug(args)
+  }
+
+  async updateGitHubIssueCommentBySlug(
+    args: UpdateIssueCommentBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof updateIssueCommentBySlug>>> {
+    return updateIssueCommentBySlug(args)
+  }
+
+  async deleteGitHubIssueCommentBySlug(
+    args: DeleteIssueCommentBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof deleteIssueCommentBySlug>>> {
+    return deleteIssueCommentBySlug(args)
+  }
+
   async getRepoHooks(repoSelector: string) {
     const repo = await this.resolveRepoSelector(repoSelector)
+    if (repo.connectionId) {
+      const fsProvider = getSshFilesystemProvider(repo.connectionId)
+      if (!fsProvider) {
+        return {
+          hasHooksFile: false,
+          hooks: null,
+          setupRunPolicy: getEffectiveSetupRunPolicy(repo),
+          source: null
+        }
+      }
+      try {
+        const result = await fsProvider.readFile(joinWorktreeRelativePath(repo.path, '.orca.yaml'))
+        const hooks = result.isBinary ? null : parseOrcaYaml(result.content)
+        return {
+          hasHooksFile: Boolean(hooks),
+          hooks,
+          setupRunPolicy: getEffectiveSetupRunPolicy(repo),
+          source: hooks ? 'orca.yaml' : null
+        }
+      } catch {
+        return {
+          hasHooksFile: false,
+          hooks: null,
+          setupRunPolicy: getEffectiveSetupRunPolicy(repo),
+          source: null
+        }
+      }
+    }
     const hasFile = hasHooksFile(repo.path)
     const hooks = getEffectiveHooks(repo)
     const setupRunPolicy = getEffectiveSetupRunPolicy(repo)
@@ -3946,6 +4741,164 @@ export class OrcaRuntimeService {
     }
   }
 
+  async checkRepoHooks(repoSelector: string) {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    if (isFolderRepo(repo)) {
+      return { hasHooks: false, hooks: null, mayNeedUpdate: false }
+    }
+
+    if (repo.connectionId) {
+      const fsProvider = getSshFilesystemProvider(repo.connectionId)
+      if (!fsProvider) {
+        return { hasHooks: false, hooks: null, mayNeedUpdate: false }
+      }
+      try {
+        const result = await fsProvider.readFile(joinWorktreeRelativePath(repo.path, '.orca.yaml'))
+        if (result.isBinary) {
+          return { hasHooks: false, hooks: null, mayNeedUpdate: false }
+        }
+        const { parse } = await import('yaml')
+        const parsed = parse(result.content)
+        return { hasHooks: true, hooks: parsed, mayNeedUpdate: false }
+      } catch {
+        return { hasHooks: false, hooks: null, mayNeedUpdate: false }
+      }
+    }
+
+    const has = hasHooksFile(repo.path)
+    const hooks = has ? loadHooks(repo.path) : null
+    return {
+      hasHooks: has,
+      hooks,
+      mayNeedUpdate: has && !hooks && hasUnrecognizedOrcaYamlKeys(repo.path)
+    }
+  }
+
+  async readRepoIssueCommand(repoSelector: string) {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    if (isFolderRepo(repo)) {
+      return {
+        localContent: null,
+        sharedContent: null,
+        effectiveContent: null,
+        localFilePath: '',
+        source: 'none' as const
+      }
+    }
+
+    if (repo.connectionId) {
+      const issueCommandPath = joinWorktreeRelativePath(repo.path, '.orca/issue-command')
+      const fsProvider = getSshFilesystemProvider(repo.connectionId)
+      if (!fsProvider) {
+        return {
+          localContent: null,
+          sharedContent: null,
+          effectiveContent: null,
+          localFilePath: issueCommandPath,
+          source: 'none' as const
+        }
+      }
+      const localContent = await this.readRemoteIssueCommandOverride(fsProvider, issueCommandPath)
+      const sharedContent = await this.readRemoteSharedIssueCommand(fsProvider, repo.path)
+      const effectiveContent = localContent ?? sharedContent
+      return {
+        localContent,
+        sharedContent,
+        effectiveContent,
+        localFilePath: issueCommandPath,
+        source: localContent
+          ? ('local' as const)
+          : sharedContent
+            ? ('shared' as const)
+            : ('none' as const)
+      }
+    }
+
+    return readIssueCommand(repo.path)
+  }
+
+  private async readRemoteIssueCommandOverride(
+    fsProvider: IFilesystemProvider,
+    issueCommandPath: string
+  ): Promise<string | null> {
+    try {
+      const result = await fsProvider.readFile(issueCommandPath)
+      if (result.isBinary) {
+        return null
+      }
+      return result.content.trim() || null
+    } catch {
+      return null
+    }
+  }
+
+  private async readRemoteSharedIssueCommand(
+    fsProvider: IFilesystemProvider,
+    repoPath: string
+  ): Promise<string | null> {
+    try {
+      const result = await fsProvider.readFile(joinWorktreeRelativePath(repoPath, 'orca.yaml'))
+      if (result.isBinary) {
+        return null
+      }
+      return parseOrcaYaml(result.content)?.issueCommand?.trim() || null
+    } catch {
+      return null
+    }
+  }
+
+  async writeRepoIssueCommand(repoSelector: string, content: string): Promise<{ ok: true }> {
+    const repo = await this.resolveRepoSelector(repoSelector)
+    if (isFolderRepo(repo)) {
+      return { ok: true }
+    }
+
+    if (repo.connectionId) {
+      const issueCommandPath = joinWorktreeRelativePath(repo.path, '.orca/issue-command')
+      const fsProvider = getSshFilesystemProvider(repo.connectionId)
+      if (!fsProvider) {
+        return { ok: true }
+      }
+      const trimmed = content.trim()
+      if (!trimmed) {
+        await fsProvider.deletePath(issueCommandPath, false).catch((error: unknown) => {
+          if (!isENOENT(error)) {
+            throw error
+          }
+        })
+        return { ok: true }
+      }
+      await fsProvider.createDir(joinWorktreeRelativePath(repo.path, '.orca'))
+      await this.ensureRemoteOrcaDirIgnored(fsProvider, repo.path)
+      await fsProvider.writeFile(issueCommandPath, `${trimmed}\n`)
+      return { ok: true }
+    }
+
+    writeIssueCommand(repo.path, content)
+    return { ok: true }
+  }
+
+  private async ensureRemoteOrcaDirIgnored(
+    fsProvider: IFilesystemProvider,
+    repoPath: string
+  ): Promise<void> {
+    const gitignorePath = joinWorktreeRelativePath(repoPath, '.gitignore')
+    try {
+      const result = await fsProvider.readFile(gitignorePath)
+      if (result.isBinary || /^\.orca\/?$/m.test(result.content)) {
+        return
+      }
+      const separator = result.content.endsWith('\n') ? '' : '\n'
+      await fsProvider.writeFile(gitignorePath, `${result.content}${separator}.orca\n`)
+    } catch {
+      try {
+        await fsProvider.writeFile(gitignorePath, '.orca\n')
+      } catch (error) {
+        console.warn('[runtime] Could not update remote .gitignore to exclude .orca', error)
+      }
+    }
+  }
+
   async listNotes(args: { worktreeSelector: string; limit?: number }): Promise<NoteListResult> {
     const scope = await this.resolveNotesScope(args.worktreeSelector)
     return await this.getNotesStore().list(this.getNotesScope(scope.projectId), {
@@ -3982,6 +4935,53 @@ export class OrcaRuntimeService {
     })
   }
 
+  async saveNote(args: {
+    worktreeSelector: string
+    note: string
+    title?: string
+    bodyMarkdown: string
+    revision?: number
+    makeActive?: boolean
+    updatedBySessionId?: string | null
+  }): Promise<NoteMutationResult> {
+    const scope = await this.resolveNotesScope(args.worktreeSelector)
+    return await this.getNotesStore().save(this.getNotesScope(scope.projectId), {
+      projectId: scope.projectId,
+      worktreeId: scope.worktreeId,
+      note: args.note,
+      title: args.title,
+      bodyMarkdown: args.bodyMarkdown,
+      revision: args.revision,
+      makeActive: args.makeActive,
+      updatedBySessionId: args.updatedBySessionId
+    })
+  }
+
+  async renameNote(args: {
+    worktreeSelector: string
+    note: string
+    title: string
+    updatedBySessionId?: string | null
+  }): Promise<NoteMutationResult> {
+    const scope = await this.resolveNotesScope(args.worktreeSelector)
+    return await this.getNotesStore().rename(this.getNotesScope(scope.projectId), {
+      projectId: scope.projectId,
+      worktreeId: scope.worktreeId,
+      note: args.note,
+      title: args.title,
+      updatedBySessionId: args.updatedBySessionId
+    })
+  }
+
+  async deleteNote(args: { worktreeSelector: string; note: string }): Promise<NoteDeleteResult> {
+    const scope = await this.resolveNotesScope(args.worktreeSelector)
+    return await this.getNotesStore().delete(this.getNotesScope(scope.projectId), {
+      projectId: scope.projectId,
+      worktreeId: scope.worktreeId,
+      note: args.note
+    })
+  }
+
   async appendNote(args: {
     worktreeSelector: string
     note: string
@@ -4014,6 +5014,30 @@ export class OrcaRuntimeService {
     })
   }
 
+  async linkNote(args: {
+    worktreeSelector: string
+    note: string
+    kind: NoteLinkKind
+  }): Promise<NoteLink> {
+    const scope = await this.resolveNotesScope(args.worktreeSelector)
+    return await this.getNotesStore().setLink(this.getNotesScope(scope.projectId), {
+      projectId: scope.projectId,
+      worktreeId: scope.worktreeId,
+      note: args.note,
+      kind: args.kind
+    })
+  }
+
+  async resolveNotesPanelOpenStateForWorktree(args: {
+    worktreeSelector: string
+  }): Promise<NotesPanelOpenState> {
+    const scope = await this.resolveNotesScope(args.worktreeSelector)
+    return await this.getNotesStore().resolvePanelOpenState(this.getNotesScope(scope.projectId), {
+      projectId: scope.projectId,
+      worktreeId: scope.worktreeId
+    })
+  }
+
   async listProjectNotes(args: NoteListArgs): Promise<NoteListResult> {
     this.assertKnownNotesProject(args.projectId)
     return await this.getNotesStore().list(this.getNotesScope(args.projectId), args)
@@ -4127,10 +5151,15 @@ export class OrcaRuntimeService {
     name: string
     baseBranch?: string
     linkedIssue?: number | null
+    linkedPR?: number | null
     comment?: string
+    displayName?: string
+    sparseCheckout?: { directories: string[]; presetId?: string }
+    pushTarget?: GitPushTarget
     runHooks?: boolean
     activate?: boolean
     setupDecision?: 'run' | 'skip' | 'inherit'
+    createdWithAgent?: TuiAgent
     startup?: WorktreeStartupLaunch
   }): Promise<CreateWorktreeResult> {
     if (!this.store) {
@@ -4141,8 +5170,15 @@ export class OrcaRuntimeService {
     if (isFolderRepo(repo)) {
       throw new Error('Folder mode does not support creating worktrees.')
     }
+    if (repo.connectionId) {
+      // Why: SSH-backed worktree creation still relies on the desktop SSH
+      // flow, which can prime relay roots and enforce its remote constraints.
+      // Runtime RPC must not fall through to local git against server paths.
+      throw new Error('SSH-backed worktree creation is not supported through runtime RPC yet.')
+    }
     const settings = this.store.getSettings()
     const requestedName = args.name
+    const requestedDisplayName = args.displayName?.trim() || undefined
     const sanitizedName = sanitizeWorktreeName(args.name)
     const username = getGitUsername(repo.path)
     const branchName = computeBranchName(sanitizedName, settings, username)
@@ -4200,13 +5236,47 @@ export class OrcaRuntimeService {
       // if future refactors change that contract.
     }
 
-    await addWorktree(
-      repo.path,
-      worktreePath,
-      branchName,
-      baseBranch,
-      settings.refreshLocalBaseRefOnWorktreeCreate
-    )
+    const sparseDirectories = args.sparseCheckout
+      ? normalizeSparseDirectories(args.sparseCheckout.directories)
+      : []
+    if (args.sparseCheckout && sparseDirectories.length === 0) {
+      throw new Error('Sparse checkout requires at least one repo-relative directory.')
+    }
+
+    let preparedPushTarget: GitPushTarget | undefined
+    if (args.pushTarget) {
+      // Why: fork-PR worktrees created through a remote runtime need the same
+      // upstream target setup as local desktop creates, or Push would publish
+      // to the wrong remote after the client/server split.
+      preparedPushTarget = await prepareWorktreePushTarget(repo.path, args.pushTarget)
+    }
+
+    await (sparseDirectories.length > 0
+      ? addSparseWorktree(
+          repo.path,
+          worktreePath,
+          branchName,
+          sparseDirectories,
+          baseBranch,
+          settings.refreshLocalBaseRefOnWorktreeCreate
+        )
+      : addWorktree(
+          repo.path,
+          worktreePath,
+          branchName,
+          baseBranch,
+          settings.refreshLocalBaseRefOnWorktreeCreate
+        ))
+
+    let configuredPushTarget: GitPushTarget | undefined
+    if (preparedPushTarget) {
+      configuredPushTarget = await configureCreatedWorktreePushTarget(
+        worktreePath,
+        branchName,
+        preparedPushTarget
+      )
+    }
+
     const gitWorktrees = await listWorktrees(repo.path)
     const created = gitWorktrees.find((gw) => areWorktreePathsEqual(gw.path, worktreePath))
     if (!created) {
@@ -4215,6 +5285,11 @@ export class OrcaRuntimeService {
 
     const worktreeId = `${repo.id}::${created.path}`
     const now = Date.now()
+    const displayNameMeta = requestedDisplayName
+      ? { displayName: requestedDisplayName }
+      : shouldSetDisplayName(requestedName, branchName, sanitizedName)
+        ? { displayName: requestedName }
+        : {}
     const meta = this.store.setWorktreeMeta(worktreeId, {
       lastActivityAt: now,
       // See createRemoteWorktree: createdAt grants the new worktree a grace
@@ -4222,15 +5297,31 @@ export class OrcaRuntimeService {
       // push it down before the user has had a chance to notice it. Smart-sort
       // uses max(lastActivityAt, createdAt + CREATE_GRACE_MS).
       createdAt: now,
-      ...(shouldSetDisplayName(requestedName, branchName, sanitizedName)
-        ? { displayName: requestedName }
-        : {}),
+      ...displayNameMeta,
       baseRef: baseBranch,
+      ...(configuredPushTarget ? { pushTarget: configuredPushTarget } : {}),
+      ...(sparseDirectories.length > 0
+        ? {
+            sparseDirectories,
+            sparseBaseRef: baseBranch,
+            sparsePresetId: args.sparseCheckout?.presetId
+          }
+        : {}),
       ...(args.linkedIssue !== undefined ? { linkedIssue: args.linkedIssue } : {}),
+      ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {}),
+      ...(args.createdWithAgent ? { createdWithAgent: args.createdWithAgent } : {}),
       ...(args.comment !== undefined ? { comment: args.comment } : {})
     })
     const worktree = mergeWorktree(repo.id, created, meta)
 
+    if (
+      settings.experimentalWorktreeSymlinks &&
+      repo.symlinkPaths &&
+      repo.symlinkPaths.length > 0
+    ) {
+      await createWorktreeSymlinks(repo.path, created.path, repo.symlinkPaths)
+    }
+
     let setup: CreateWorktreeResult['setup']
     let warning: string | undefined
     // Why: CLI-created worktrees do not have a renderer preview to mismatch
@@ -4277,6 +5368,7 @@ export class OrcaRuntimeService {
     // are not recognized and all git operations fail with "Access denied:
     // unknown repository or worktree path".
     invalidateAuthorizedRootsCache()
+
     this.notifier?.worktreesChanged(repo.id)
     const shouldActivate = args.activate === true || args.runHooks === true
     let didSpawnStartup = false
@@ -4669,6 +5761,12 @@ export class OrcaRuntimeService {
     if (!repo) {
       return null
     }
+    if (repo.connectionId) {
+      // Why: the drift probe uses local git helpers. Until the SSH provider
+      // exposes equivalent remote refs/log plumbing, fail closed to "unknown"
+      // instead of probing a server path on the desktop filesystem.
+      return null
+    }
     const meta = this.store.getWorktreeMeta(wt.id)
     const base =
       meta?.baseRef || meta?.sparseBaseRef || repo.worktreeBaseRef || getDefaultBaseRef(repo.path)
@@ -4694,25 +5792,12 @@ export class OrcaRuntimeService {
     return { base, behind: drift.behind, recentSubjects }
   }
 
-  async updateManagedWorktreeMeta(
-    worktreeSelector: string,
-    updates: {
-      displayName?: string
-      linkedIssue?: number | null
-      comment?: string
-      isPinned?: boolean
-    }
-  ) {
+  async updateManagedWorktreeMeta(worktreeSelector: string, updates: Partial<WorktreeMeta>) {
     if (!this.store) {
       throw new Error('runtime_unavailable')
     }
     const worktree = await this.resolveWorktreeSelector(worktreeSelector)
-    const meta = this.store.setWorktreeMeta(worktree.id, {
-      ...(updates.displayName !== undefined ? { displayName: updates.displayName } : {}),
-      ...(updates.linkedIssue !== undefined ? { linkedIssue: updates.linkedIssue } : {}),
-      ...(updates.comment !== undefined ? { comment: updates.comment } : {}),
-      ...(updates.isPinned !== undefined ? { isPinned: updates.isPinned } : {})
-    })
+    const meta = this.store.setWorktreeMeta(worktree.id, omitUndefinedProperties(updates))
     // Why: unlike renderer-initiated optimistic updates, CLI callers need an
     // explicit push so the editor refreshes metadata changed outside the UI.
     this.invalidateResolvedWorktreeCache()
@@ -4720,6 +5805,127 @@ export class OrcaRuntimeService {
     return mergeWorktree(worktree.repoId, worktree.git, meta)
   }
 
+  persistManagedWorktreeSortOrder(orderedIds: string[]): { updated: number } {
+    if (!this.store) {
+      throw new Error('runtime_unavailable')
+    }
+    const now = Date.now()
+    let updated = 0
+    for (let i = 0; i < orderedIds.length; i++) {
+      this.store.setWorktreeMeta(orderedIds[i], { sortOrder: now - i * 1000 })
+      updated++
+    }
+    this.invalidateResolvedWorktreeCache()
+    this.notifier?.reposChanged()
+    return { updated }
+  }
+
+  async resolveManagedPrBase(args: {
+    repoId: string
+    prNumber: number
+    headRefName?: string
+    isCrossRepository?: boolean
+  }): Promise<{ baseBranch: string; pushTarget?: GitPushTarget } | { error: string }> {
+    if (!this.store) {
+      throw new Error('runtime_unavailable')
+    }
+    const repo = this.store.getRepo(args.repoId)
+    if (!repo) {
+      return { error: 'Repo not found' }
+    }
+    if (repo.connectionId) {
+      return { error: 'PR start points are not supported for remote repos yet.' }
+    }
+    if (isFolderRepo(repo)) {
+      return { error: 'Folder mode does not support creating worktrees.' }
+    }
+
+    let headRefName = args.headRefName?.trim() ?? ''
+    let isCrossRepository = args.isCrossRepository === true
+    let pushTarget: GitPushTarget | undefined
+
+    if (!headRefName) {
+      const item = await getWorkItem(repo.path, args.prNumber, 'pr')
+      if (!item || item.type !== 'pr') {
+        return { error: `PR #${args.prNumber} not found.` }
+      }
+      headRefName = (item.branchName ?? '').trim()
+      if (!headRefName) {
+        return { error: `PR #${args.prNumber} has no head branch.` }
+      }
+      if (item.isCrossRepository === true) {
+        isCrossRepository = true
+      }
+    }
+
+    if (isCrossRepository) {
+      try {
+        pushTarget = (await getPullRequestPushTarget(repo.path, args.prNumber)) ?? undefined
+      } catch (error) {
+        return {
+          error:
+            error instanceof Error
+              ? error.message
+              : `Could not resolve PR #${args.prNumber} head push target.`
+        }
+      }
+      if (!pushTarget) {
+        return { error: `Could not resolve PR #${args.prNumber} head push target.` }
+      }
+    }
+
+    let remote: string
+    try {
+      remote = await getDefaultRemote(repo.path)
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : 'Could not resolve git remote.' }
+    }
+
+    if (isCrossRepository) {
+      const pullRef = `refs/pull/${args.prNumber}/head`
+      try {
+        await gitExecFileAsync(['fetch', remote, pullRef], { cwd: repo.path })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        return { error: `Failed to fetch ${pullRef}: ${message.split('\n')[0]}` }
+      }
+      try {
+        const { stdout } = await gitExecFileAsync(['rev-parse', '--verify', 'FETCH_HEAD'], {
+          cwd: repo.path
+        })
+        const sha = stdout.trim()
+        if (!sha) {
+          return { error: `Empty SHA resolving fork PR #${args.prNumber} head.` }
+        }
+        return { baseBranch: sha, ...(pushTarget ? { pushTarget } : {}) }
+      } catch {
+        return { error: `Could not resolve fork PR #${args.prNumber} head after fetch.` }
+      }
+    }
+
+    try {
+      await gitExecFileAsync(
+        ['fetch', remote, `+refs/heads/${headRefName}:refs/remotes/${remote}/${headRefName}`],
+        { cwd: repo.path }
+      )
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return { error: `Failed to fetch ${remote}/${headRefName}: ${message.split('\n')[0]}` }
+    }
+
+    const remoteRef = `${remote}/${headRefName}`
+    try {
+      await gitExecFileAsync(['rev-parse', '--verify', remoteRef], { cwd: repo.path })
+    } catch {
+      return { error: `Remote ref ${remoteRef} does not exist after fetch.` }
+    }
+
+    return {
+      baseBranch: remoteRef,
+      pushTarget: pushTarget ?? { remoteName: remote, branchName: headRefName }
+    }
+  }
+
   async removeManagedWorktree(
     worktreeSelector: string,
     force = false,
@@ -4736,6 +5942,19 @@ export class OrcaRuntimeService {
     if (isFolderRepo(repo)) {
       throw new Error('Folder mode does not support deleting worktrees.')
     }
+    if (repo.connectionId) {
+      const provider = getSshGitProvider(repo.connectionId)
+      if (!provider) {
+        throw new Error(`No git provider for connection "${repo.connectionId}"`)
+      }
+      await provider.removeWorktree(worktree.path, force)
+      this.clearOptimisticReconcileToken(worktree.id)
+      this.store.removeWorktreeMeta(worktree.id)
+      this.invalidateResolvedWorktreeCache()
+      invalidateAuthorizedRootsCache()
+      this.notifier?.worktreesChanged(repo.id)
+      return {}
+    }
 
     // Why: kill every PTY belonging to this worktree BEFORE the git-level
     // removal. Some shells keep the worktree directory busy, and `git worktree
@@ -4967,7 +6186,14 @@ export class OrcaRuntimeService {
       afterDesktopTabId = anchor.type === 'terminal' ? anchor.parentTabId : anchor.id
     }
 
-    const win = this.getAuthoritativeWindow()
+    const win = this.getAvailableAuthoritativeWindow()
+    if (!win) {
+      return await this.createHeadlessMobileSessionTerminal(
+        worktreeId,
+        opts.activate !== false,
+        opts.afterTabId
+      )
+    }
     const requestId = randomUUID()
     const reply = await new Promise<{ tabId: string; title: string }>((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -5004,6 +6230,64 @@ export class OrcaRuntimeService {
     return await this.waitForMobileTerminalSurface(worktreeId, reply.tabId)
   }
 
+  private async createHeadlessMobileSessionTerminal(
+    worktreeId: string,
+    activate: boolean,
+    afterTabId?: string
+  ): Promise<RuntimeMobileSessionCreateTerminalResult> {
+    const terminal = await this.createTerminal(`id:${worktreeId}`, { focus: false })
+    const livePty = this.getLivePtyForHandle(terminal.handle)
+    if (!livePty) {
+      throw new Error('terminal_handle_stale')
+    }
+    const parentTabId = livePty.pty.tabId ?? `pty:${livePty.pty.ptyId}`
+    const leafId = `pane:${FIRST_PANE_ID}`
+    const tab: RuntimeMobileSessionTerminalTab = {
+      type: 'terminal',
+      id: `${parentTabId}::${leafId}`,
+      parentTabId,
+      leafId,
+      title: terminal.title ?? livePty.pty.title ?? 'Terminal',
+      isActive: activate
+    }
+    const existing = this.mobileSessionTabsByWorktree.get(worktreeId)
+    const tabs = (existing?.tabs ?? [])
+      .filter((candidate) => candidate.id !== tab.id)
+      .map((candidate) => ({
+        ...candidate,
+        isActive: activate ? false : candidate.isActive
+      }))
+    const insertAfter = afterTabId ? tabs.findIndex((candidate) => candidate.id === afterTabId) : -1
+    if (insertAfter >= 0) {
+      tabs.splice(insertAfter + 1, 0, tab)
+    } else {
+      tabs.push(tab)
+    }
+    const next: RuntimeMobileSessionTabsSnapshot = {
+      worktree: worktreeId,
+      publicationEpoch: `headless:${Date.now().toString(36)}`,
+      snapshotVersion: (existing?.snapshotVersion ?? 0) + 1,
+      activeGroupId: existing?.activeGroupId ?? null,
+      activeTabId: activate ? tab.id : (existing?.activeTabId ?? null),
+      activeTabType: activate ? 'terminal' : (existing?.activeTabType ?? null),
+      tabs
+    }
+    this.mobileSessionTabsByWorktree.set(worktreeId, next)
+    const result = this.toMobileSessionTabsResult(next)
+    for (const listener of this.mobileSessionTabListeners) {
+      listener(result)
+    }
+    const created = result.tabs.find((candidate) => candidate.id === tab.id)
+    if (!created || created.type !== 'terminal') {
+      throw new Error('terminal_handle_stale')
+    }
+    return {
+      tab: created,
+      publicationEpoch: result.publicationEpoch,
+      snapshotVersion: result.snapshotVersion
+    }
+  }
+
   private waitForMobileTerminalSurface(
     worktreeId: string,
     parentTabId: string,
@@ -5392,7 +6676,9 @@ export class OrcaRuntimeService {
     if (selector.startsWith('id:')) {
       candidates = worktrees.filter((worktree) => worktree.id === selector.slice(3))
     } else if (selector.startsWith('path:')) {
-      candidates = worktrees.filter((worktree) => worktree.path === selector.slice(5))
+      candidates = worktrees.filter((worktree) =>
+        runtimePathsEqual(worktree.path, selector.slice(5))
+      )
     } else if (selector.startsWith('branch:')) {
       const branchSelector = selector.slice(7)
       candidates = worktrees.filter((worktree) =>
@@ -5407,7 +6693,7 @@ export class OrcaRuntimeService {
       candidates = worktrees.filter(
         (worktree) =>
           worktree.id === selector ||
-          worktree.path === selector ||
+          runtimePathsEqual(worktree.path, selector) ||
           branchSelectorMatches(worktree.branch, selector)
       )
     }
@@ -5467,12 +6753,15 @@ export class OrcaRuntimeService {
     if (selector.startsWith('id:')) {
       candidates = repos.filter((repo) => repo.id === selector.slice(3))
     } else if (selector.startsWith('path:')) {
-      candidates = repos.filter((repo) => repo.path === selector.slice(5))
+      candidates = repos.filter((repo) => runtimePathsEqual(repo.path, selector.slice(5)))
     } else if (selector.startsWith('name:')) {
       candidates = repos.filter((repo) => repo.displayName === selector.slice(5))
     } else {
       candidates = repos.filter(
-        (repo) => repo.id === selector || repo.path === selector || repo.displayName === selector
+        (repo) =>
+          repo.id === selector ||
+          runtimePathsEqual(repo.path, selector) ||
+          repo.displayName === selector
       )
     }
 
@@ -5485,6 +6774,13 @@ export class OrcaRuntimeService {
     throw new Error('repo_not_found')
   }
 
+  private requireStore(): Store {
+    if (!this.store) {
+      throw new Error('runtime_unavailable')
+    }
+    return this.store as unknown as Store
+  }
+
   private async listResolvedWorktrees(): Promise<ResolvedWorktree[]> {
     if (!this.store) {
       return []
@@ -5493,19 +6789,23 @@ export class OrcaRuntimeService {
     if (this.resolvedWorktreeCache && this.resolvedWorktreeCache.expiresAt > now) {
       return this.resolvedWorktreeCache.worktrees
     }
-    if (this.resolvedWorktreeInFlight) {
-      return this.resolvedWorktreeInFlight
+    const generation = this.resolvedWorktreeGeneration
+    if (this.resolvedWorktreeInFlight?.generation === generation) {
+      return this.resolvedWorktreeInFlight.promise
     }
 
-    this.resolvedWorktreeInFlight = this.computeResolvedWorktrees()
+    const promise = this.computeResolvedWorktrees(generation)
+    this.resolvedWorktreeInFlight = { generation, promise }
     try {
-      return await this.resolvedWorktreeInFlight
+      return await promise
     } finally {
-      this.resolvedWorktreeInFlight = null
+      if (this.resolvedWorktreeInFlight?.promise === promise) {
+        this.resolvedWorktreeInFlight = null
+      }
     }
   }
 
-  private async computeResolvedWorktrees(): Promise<ResolvedWorktree[]> {
+  private async computeResolvedWorktrees(generation: number): Promise<ResolvedWorktree[]> {
     if (!this.store) {
       return []
     }
@@ -5524,11 +6824,7 @@ export class OrcaRuntimeService {
           const worktreeId = `${repo.id}::${gitWorktree.path}`
           const merged = mergeWorktree(repo.id, gitWorktree, metaById[worktreeId], repo.displayName)
           return {
-            id: merged.id,
-            repoId: repo.id,
-            path: merged.path,
-            branch: merged.branch,
-            linkedIssue: metaById[worktreeId]?.linkedIssue ?? null,
+            ...merged,
             git: {
               path: gitWorktree.path,
               head: gitWorktree.head,
@@ -5546,9 +6842,11 @@ export class OrcaRuntimeService {
     // Why: terminal polling can be frequent, but git worktree state is still
     // allowed to change outside Orca. A short TTL avoids shelling out on every
     // read without pretending the cache is authoritative for long.
-    this.resolvedWorktreeCache = {
-      worktrees,
-      expiresAt: now + RESOLVED_WORKTREE_CACHE_TTL_MS
+    if (generation === this.resolvedWorktreeGeneration) {
+      this.resolvedWorktreeCache = {
+        worktrees,
+        expiresAt: now + RESOLVED_WORKTREE_CACHE_TTL_MS
+      }
     }
     return worktrees
   }
@@ -5558,6 +6856,7 @@ export class OrcaRuntimeService {
   }
 
   private invalidateResolvedWorktreeCache(): void {
+    this.resolvedWorktreeGeneration += 1
     this.resolvedWorktreeCache = null
   }
 
@@ -5800,16 +7099,19 @@ export class OrcaRuntimeService {
       }
       const syncedTab = this.tabs.get(tab.parentTabId)
       const leaf = this.leaves.get(this.getLeafKey(tab.parentTabId, tab.leafId)) ?? null
+      const pty = leaf ? null : this.findPtyForMobileTerminalTab(tab)
       tabs.push({
         type: 'terminal',
         id: tab.id,
         parentTabId: tab.parentTabId,
         leafId: tab.leafId,
-        title: leaf?.paneTitle ?? syncedTab?.title ?? tab.title,
+        title: leaf?.paneTitle ?? syncedTab?.title ?? pty?.title ?? tab.title,
         isActive: tab.isActive,
         ...(leaf
           ? { status: 'ready' as const, terminal: this.issueHandle(leaf) }
-          : { status: 'pending-handle' as const, terminal: null })
+          : pty
+            ? { status: 'ready' as const, terminal: this.issuePtyHandle(pty) }
+            : { status: 'pending-handle' as const, terminal: null })
       })
     }
     const active = tabs.find((tab) => tab.isActive) ?? null
@@ -5824,6 +7126,21 @@ export class OrcaRuntimeService {
     }
   }
 
+  private findPtyForMobileTerminalTab(
+    tab: RuntimeMobileSessionTerminalTab
+  ): RuntimePtyWorktreeRecord | null {
+    const paneKeys = new Set([`${tab.parentTabId}:${tab.leafId}`])
+    if (tab.leafId === `pane:${FIRST_PANE_ID}`) {
+      paneKeys.add(`${tab.parentTabId}:${FIRST_PANE_ID}`)
+    }
+    for (const pty of this.ptysById.values()) {
+      if (pty.tabId === tab.parentTabId && pty.paneKey && paneKeys.has(pty.paneKey)) {
+        return pty
+      }
+    }
+    return null
+  }
+
   // Why: group address resolution (Section 4.5) needs to query per-handle agent
   // status without throwing on stale handles, so this returns null on any error.
   getAgentStatusForHandle(handle: string): string | null {
@@ -6418,1318 +7735,355 @@ export class OrcaRuntimeService {
     return `${tabId}::${leafId}`
   }
 
+  // ── Linear integration ──
+
+  linearConnect(apiKey: string): ReturnType<typeof connectLinear> {
+    return connectLinear(apiKey)
+  }
+
+  linearDisconnect(): { ok: true } {
+    disconnectLinear()
+    return { ok: true }
+  }
+
+  linearStatus(): ReturnType<typeof getLinearStatus> {
+    return getLinearStatus()
+  }
+
+  linearTestConnection(): ReturnType<typeof testLinearConnection> {
+    return testLinearConnection()
+  }
+
+  linearSearchIssues(query: string, limit = 20): ReturnType<typeof searchLinearIssues> {
+    return searchLinearIssues(query, Math.min(Math.max(1, limit), 50))
+  }
+
+  linearListIssues(filter?: LinearListFilter, limit = 20): ReturnType<typeof listLinearIssues> {
+    return listLinearIssues(filter, Math.min(Math.max(1, limit), 50))
+  }
+
+  linearCreateIssue(
+    teamId: string,
+    title: string,
+    description?: string
+  ): ReturnType<typeof createLinearIssue> {
+    return createLinearIssue(teamId, title, description)
+  }
+
+  linearGetIssue(id: string): ReturnType<typeof getLinearIssue> {
+    return getLinearIssue(id)
+  }
+
+  linearUpdateIssue(id: string, updates: LinearIssueUpdate): ReturnType<typeof updateLinearIssue> {
+    return updateLinearIssue(id, updates)
+  }
+
+  linearAddIssueComment(issueId: string, body: string): ReturnType<typeof addLinearIssueComment> {
+    return addLinearIssueComment(issueId, body)
+  }
+
+  linearIssueComments(issueId: string): ReturnType<typeof getLinearIssueComments> {
+    return getLinearIssueComments(issueId)
+  }
+
+  linearListTeams(): ReturnType<typeof listLinearTeams> {
+    return listLinearTeams()
+  }
+
+  linearTeamStates(teamId: string): ReturnType<typeof getLinearTeamStates> {
+    return getLinearTeamStates(teamId)
+  }
+
+  linearTeamLabels(teamId: string): ReturnType<typeof getLinearTeamLabels> {
+    return getLinearTeamLabels(teamId)
+  }
+
+  linearTeamMembers(teamId: string): ReturnType<typeof getLinearTeamMembers> {
+    return getLinearTeamMembers(teamId)
+  }
+
   // ── Browser automation ──
 
-  private requireAgentBrowserBridge(): AgentBrowserBridge {
-    if (!this.agentBrowserBridge) {
-      throw new BrowserError('browser_no_tab', 'No browser session is active')
-    }
-    return this.agentBrowserBridge
-  }
-
-  // Why: the CLI sends worktree selectors (e.g. "path:/Users/...") but the
-  // bridge stores worktreeIds in "repoId::path" format (from the renderer's
-  // Zustand store). This helper resolves the selector to the store-compatible
-  // ID so the bridge can filter tabs correctly.
-  private async resolveBrowserWorktreeId(selector?: string): Promise<string | undefined> {
-    if (!selector) {
-      // Why: after app restart, webviews only mount when the browser pane is visible.
-      // Without --worktree, we still need to activate the view so persisted tabs
-      // become operable via registerGuest.
-      const bridge = this.agentBrowserBridge
-      if (bridge && bridge.getRegisteredTabs().size === 0) {
-        try {
-          const win = this.getAuthoritativeWindow()
-          win.webContents.send('browser:activateView', {})
-          await new Promise((resolve) => setTimeout(resolve, 500))
-        } catch {
-          // Window may not exist yet (e.g. during startup or in tests)
-        }
-      }
-      return undefined
-    }
-
-    const worktreeId = (await this.resolveWorktreeSelector(selector)).id
-    // Why: explicit worktree selectors are user intent, so resolution errors
-    // must surface instead of silently widening browser routing scope. Only the
-    // activation step remains best-effort because missing windows during tests
-    // or startup should not erase the validated worktree target itself.
-    const bridge = this.agentBrowserBridge
-    if (bridge && bridge.getRegisteredTabs(worktreeId).size === 0) {
-      try {
-        await this.ensureBrowserWorktreeActive(worktreeId)
-      } catch {
-        // Fall through with the validated worktree id so downstream routing
-        // still stays scoped to the caller's explicit selector.
-      }
-    }
-    return worktreeId
-  }
-
-  private async resolveBrowserCommandTarget(
-    params: BrowserCommandTargetParams
-  ): Promise<ResolvedBrowserCommandTarget> {
-    const browserPageId =
-      typeof params.page === 'string' && params.page.length > 0 ? params.page : undefined
-    if (!browserPageId) {
-      return {
-        worktreeId: await this.resolveBrowserWorktreeId(params.worktree)
-      }
-    }
-
-    return {
-      // Why: explicit browserPageId is already a stable tab identity, so we do
-      // not auto-resolve cwd worktree scoping on top of it. Only honor an
-      // explicit --worktree when the caller asked for that extra validation.
-      worktreeId: params.worktree
-        ? await this.resolveBrowserWorktreeId(params.worktree)
-        : undefined,
-      browserPageId
-    }
-  }
-
-  // Why: browser tabs only mount (and become operable) when their worktree is
-  // the active worktree in the renderer AND activeTabType is 'browser'. If either
-  // condition is false, the webview stays in display:none and Electron won't start
-  // its guest process — dom-ready never fires, registerGuest never runs, and CLI
-  // browser commands fail with "CDP connection refused".
-  private async ensureBrowserWorktreeActive(worktreeId: string): Promise<void> {
-    const win = this.getAuthoritativeWindow()
-    const repoId = getRepoIdFromWorktreeId(worktreeId)
-    if (!repoId) {
-      return
-    }
-    win.webContents.send('ui:activateWorktree', { repoId, worktreeId })
-    // Why: switching worktree alone sets activeView='terminal'. Browser webviews
-    // won't mount until activeTabType is 'browser'. Send a second IPC to flip it.
-    win.webContents.send('browser:activateView', { worktreeId })
-    // Why: give the renderer time to mount the webview after switching worktrees.
-    // The webview needs to attach and fire dom-ready before registerGuest runs.
-    await new Promise((resolve) => setTimeout(resolve, 500))
-  }
-
-  // Why: agent-browser drives navigation via CDP, which bypasses Electron's
-  // webview event system. The renderer's did-navigate / page-title-updated
-  // listeners never fire, leaving the Zustand store (and thus the Orca UI's
-  // address bar and tab title) stale. Push updates from main → renderer after
-  // any navigation-causing command so the UI stays in sync.
-  private notifyRendererNavigation(browserPageId: string, url: string, title: string): void {
-    try {
-      const win = this.getAuthoritativeWindow()
-      win.webContents.send('browser:navigation-update', { browserPageId, url, title })
-    } catch {
-      // Window may not exist during shutdown
-    }
-  }
-
-  // Why: `tabSwitch` only flips the bridge's `activeWebContentsId` — it
-  // does not surface the browser pane in the renderer. Without --focus, the
-  // switch is invisible to the user. With --focus, we send a dedicated IPC
-  // so the renderer can update its per-worktree active-tab state.
-  //
-  // Why this IPC carries `worktreeId` instead of letting the renderer
-  // dispatch `setActiveWorktree`: multiple agents drive browsers in parallel
-  // worktrees. A global focus call from agent X would steal the user's
-  // screen from agent Y's worktree. The renderer-side handler
-  // (focusBrowserTabInWorktree) updates per-worktree state unconditionally
-  // and only flips globals when the user is already on the targeted
-  // worktree. Cross-worktree --focus calls pre-stage silently.
-  private notifyRendererBrowserPaneFocus(
-    worktreeId: string | undefined,
-    browserPageId: string
-  ): void {
-    try {
-      const win = this.getAuthoritativeWindow()
-      win.webContents.send('browser:pane-focus', {
-        worktreeId: worktreeId ?? null,
-        browserPageId
-      })
-    } catch {
-      // Window may not exist during shutdown
-    }
-  }
-
-  async browserSnapshot(params: BrowserCommandTargetParams): Promise<BrowserSnapshotResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().snapshot(target.worktreeId, target.browserPageId)
-  }
-
-  async browserClick(
-    params: { element: string } & BrowserCommandTargetParams
-  ): Promise<BrowserClickResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const bridge = this.requireAgentBrowserBridge()
-    const result = await bridge.click(params.element, target.worktreeId, target.browserPageId)
-    // Why: clicks can trigger navigation (e.g. submitting a form, clicking a link).
-    // Read the target tab's live URL/title after the click and push to the
-    // renderer so the UI updates even when automation targeted a non-active page.
-    const page = bridge.getPageInfo(target.worktreeId, target.browserPageId)
-    if (page) {
-      this.notifyRendererNavigation(page.browserPageId, page.url, page.title)
-    }
-    return result
-  }
-
-  async browserGoto(
-    params: { url: string } & BrowserCommandTargetParams
-  ): Promise<BrowserGotoResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const bridge = this.requireAgentBrowserBridge()
-    const result = await bridge.goto(params.url, target.worktreeId, target.browserPageId)
-    const pageId = bridge.getActivePageId(target.worktreeId, target.browserPageId)
-    if (pageId) {
-      this.notifyRendererNavigation(pageId, result.url, result.title)
-    }
-    return result
-  }
-
-  async browserFill(
-    params: {
-      element: string
-      value: string
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserFillResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().fill(
-      params.element,
-      params.value,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserType(
-    params: { input: string } & BrowserCommandTargetParams
-  ): Promise<BrowserTypeResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().type(
-      params.input,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserSelect(
-    params: {
-      element: string
-      value: string
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserSelectResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().select(
-      params.element,
-      params.value,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserScroll(
-    params: { direction: 'up' | 'down'; amount?: number } & BrowserCommandTargetParams
-  ): Promise<BrowserScrollResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().scroll(
-      params.direction,
-      params.amount,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserBack(params: BrowserCommandTargetParams): Promise<BrowserBackResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const bridge = this.requireAgentBrowserBridge()
-    const result = await bridge.back(target.worktreeId, target.browserPageId)
-    const pageId = bridge.getActivePageId(target.worktreeId, target.browserPageId)
-    if (pageId) {
-      this.notifyRendererNavigation(pageId, result.url, result.title)
-    }
-    return result
-  }
-
-  async browserReload(params: BrowserCommandTargetParams): Promise<BrowserReloadResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const bridge = this.requireAgentBrowserBridge()
-    const result = await bridge.reload(target.worktreeId, target.browserPageId)
-    const pageId = bridge.getActivePageId(target.worktreeId, target.browserPageId)
-    if (pageId) {
-      this.notifyRendererNavigation(pageId, result.url, result.title)
-    }
-    return result
-  }
-
-  async browserScreenshot(
-    params: {
-      format?: 'png' | 'jpeg'
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserScreenshotResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().screenshot(
-      params.format,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserEval(
-    params: { expression: string } & BrowserCommandTargetParams
-  ): Promise<BrowserEvalResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().evaluate(
-      params.expression,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserTabList(params: { worktree?: string }): Promise<BrowserTabListResult> {
-    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
-    const result = this.requireAgentBrowserBridge().tabList(worktreeId)
-    return {
-      tabs: result.tabs.map((tab) => this.enrichBrowserTabInfo(tab))
-    }
-  }
-
-  async browserTabShow(params: { page: string; worktree?: string }): Promise<BrowserTabShowResult> {
-    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
-    return { tab: this.describeBrowserTab(params.page, worktreeId) }
-  }
-
-  async browserTabCurrent(params: { worktree?: string }): Promise<BrowserTabCurrentResult> {
-    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
-    const browserPageId = this.requireAgentBrowserBridge().getActivePageId(worktreeId)
-    if (!browserPageId) {
-      throw new BrowserError('browser_no_tab', 'No browser tab open in this worktree')
-    }
-    return { tab: this.describeBrowserTab(browserPageId, worktreeId) }
-  }
-
-  async browserTabSwitch(
-    params: {
-      index?: number
-      focus?: boolean
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserTabSwitchResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const bridge = this.requireAgentBrowserBridge()
-    const result = await bridge.tabSwitch(params.index, target.worktreeId, target.browserPageId)
-    if (params.focus) {
-      // Why: prefer the explicit --worktree the caller passed; fall back to
-      // the bridge's owning-worktree map for the just-switched tab. The
-      // owning worktree is what the renderer needs to scope the focus to.
-      // The renderer NEVER yanks the user across worktrees on this signal
-      // (see focusBrowserTabInWorktree).
-      const worktreeId =
-        target.worktreeId ?? browserManager.getWorktreeIdForTab(result.browserPageId) ?? undefined
-      this.notifyRendererBrowserPaneFocus(worktreeId, result.browserPageId)
-    }
-    return result
-  }
-
-  async browserHover(
-    params: { element: string } & BrowserCommandTargetParams
-  ): Promise<BrowserHoverResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().hover(
-      params.element,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserDrag(
-    params: {
-      from: string
-      to: string
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserDragResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().drag(
-      params.from,
-      params.to,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserUpload(
-    params: { element: string; files: string[] } & BrowserCommandTargetParams
-  ): Promise<BrowserUploadResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().upload(
-      params.element,
-      params.files,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserWait(
-    params: {
-      selector?: string
-      timeout?: number
-      text?: string
-      url?: string
-      load?: string
-      fn?: string
-      state?: string
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserWaitResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const { worktree: _, page: __, ...options } = params
-    return this.requireAgentBrowserBridge().wait(options, target.worktreeId, target.browserPageId)
-  }
-
-  async browserCheck(
-    params: { element: string; checked: boolean } & BrowserCommandTargetParams
-  ): Promise<BrowserCheckResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().check(
-      params.element,
-      params.checked,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserFocus(
-    params: { element: string } & BrowserCommandTargetParams
-  ): Promise<BrowserFocusResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().focus(
-      params.element,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserClear(
-    params: { element: string } & BrowserCommandTargetParams
-  ): Promise<BrowserClearResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().clear(
-      params.element,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserSelectAll(
-    params: { element: string } & BrowserCommandTargetParams
-  ): Promise<BrowserSelectAllResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().selectAll(
-      params.element,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserKeypress(
-    params: { key: string } & BrowserCommandTargetParams
-  ): Promise<BrowserKeypressResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().keypress(
-      params.key,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserPdf(params: BrowserCommandTargetParams): Promise<BrowserPdfResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().pdf(target.worktreeId, target.browserPageId)
-  }
-
-  async browserFullScreenshot(
-    params: {
-      format?: 'png' | 'jpeg'
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserScreenshotResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().fullPageScreenshot(
-      params.format,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Cookie management ──
-
-  async browserCookieGet(
-    params: { url?: string } & BrowserCommandTargetParams
-  ): Promise<BrowserCookieGetResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().cookieGet(
-      params.url,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserCookieSet(
-    params: {
-      name: string
-      value: string
-      domain?: string
-      path?: string
-      secure?: boolean
-      httpOnly?: boolean
-      sameSite?: string
-      expires?: number
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserCookieSetResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().cookieSet(
-      params,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserCookieDelete(
-    params: {
-      name: string
-      domain?: string
-      url?: string
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserCookieDeleteResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().cookieDelete(
-      params.name,
-      params.domain,
-      params.url,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Viewport ──
-
-  async browserSetViewport(
-    params: {
-      width: number
-      height: number
-      deviceScaleFactor?: number
-      mobile?: boolean
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserViewportResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().setViewport(
-      params.width,
-      params.height,
-      params.deviceScaleFactor,
-      params.mobile,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Geolocation ──
-
-  async browserSetGeolocation(
-    params: {
-      latitude: number
-      longitude: number
-      accuracy?: number
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserGeolocationResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().setGeolocation(
-      params.latitude,
-      params.longitude,
-      params.accuracy,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Request interception ──
-
-  async browserInterceptEnable(
-    params: {
-      patterns?: string[]
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserInterceptEnableResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().interceptEnable(
-      params.patterns,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserInterceptDisable(
-    params: BrowserCommandTargetParams
-  ): Promise<BrowserInterceptDisableResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().interceptDisable(
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserInterceptList(params: BrowserCommandTargetParams): Promise<{ requests: unknown[] }> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().interceptList(target.worktreeId, target.browserPageId)
-  }
-
-  // ── Console/network capture ──
-
-  async browserCaptureStart(
-    params: BrowserCommandTargetParams
-  ): Promise<BrowserCaptureStartResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().captureStart(target.worktreeId, target.browserPageId)
-  }
-
-  async browserCaptureStop(params: BrowserCommandTargetParams): Promise<BrowserCaptureStopResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().captureStop(target.worktreeId, target.browserPageId)
-  }
-
-  async browserConsoleLog(
-    params: { limit?: number } & BrowserCommandTargetParams
-  ): Promise<BrowserConsoleResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().consoleLog(
-      params.limit,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserNetworkLog(
-    params: { limit?: number } & BrowserCommandTargetParams
-  ): Promise<BrowserNetworkLogResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().networkLog(
-      params.limit,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Additional core commands ──
-
-  async browserDblclick(
-    params: { element: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().dblclick(
-      params.element,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserForward(params: BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().forward(target.worktreeId, target.browserPageId)
-  }
-
-  async browserScrollIntoView(
-    params: { element: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().scrollIntoView(
-      params.element,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserGet(
-    params: {
-      what: string
-      selector?: string
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().get(
-      params.what,
-      params.selector,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserIs(
-    params: { what: string; selector: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().is(
-      params.what,
-      params.selector,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Keyboard insert text ──
-
-  async browserKeyboardInsertText(
-    params: { text: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().keyboardInsertText(
-      params.text,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Mouse commands ──
-
-  async browserMouseMove(
-    params: { x: number; y: number } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().mouseMove(
-      params.x,
-      params.y,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserMouseDown(
-    params: { button?: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().mouseDown(
-      params.button,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserMouseUp(params: { button?: string } & BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().mouseUp(
-      params.button,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserMouseWheel(
-    params: {
-      dy: number
-      dx?: number
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().mouseWheel(
-      params.dy,
-      params.dx,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Find (semantic locators) ──
-
-  async browserFind(
-    params: {
-      locator: string
-      value: string
-      action: string
-      text?: string
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().find(
-      params.locator,
-      params.value,
-      params.action,
-      params.text,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Set commands ──
-
-  async browserSetDevice(params: { name: string } & BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().setDevice(
-      params.name,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserSetOffline(
-    params: { state?: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().setOffline(
-      params.state,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserSetHeaders(
-    params: { headers: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().setHeaders(
-      params.headers,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserSetCredentials(
-    params: {
-      user: string
-      pass: string
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().setCredentials(
-      params.user,
-      params.pass,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserSetMedia(
-    params: {
-      colorScheme?: string
-      reducedMotion?: string
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().setMedia(
-      params.colorScheme,
-      params.reducedMotion,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Clipboard commands ──
-
-  async browserClipboardRead(params: BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().clipboardRead(target.worktreeId, target.browserPageId)
-  }
-
-  async browserClipboardWrite(
-    params: { text: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().clipboardWrite(
-      params.text,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Dialog commands ──
-
-  async browserDialogAccept(
-    params: { text?: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().dialogAccept(
-      params.text,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserDialogDismiss(params: BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().dialogDismiss(target.worktreeId, target.browserPageId)
-  }
-
-  // ── Storage commands ──
-
-  async browserStorageLocalGet(
-    params: { key: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().storageLocalGet(
-      params.key,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserStorageLocalSet(
-    params: {
-      key: string
-      value: string
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().storageLocalSet(
-      params.key,
-      params.value,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserStorageLocalClear(params: BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().storageLocalClear(
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserStorageSessionGet(
-    params: { key: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().storageSessionGet(
-      params.key,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserStorageSessionSet(
-    params: {
-      key: string
-      value: string
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().storageSessionSet(
-      params.key,
-      params.value,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserStorageSessionClear(params: BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().storageSessionClear(
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Download command ──
-
-  async browserDownload(
-    params: {
-      selector: string
-      path: string
-    } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().download(
-      params.selector,
-      params.path,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── Highlight command ──
-
-  async browserHighlight(
-    params: { selector: string } & BrowserCommandTargetParams
-  ): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().highlight(
-      params.selector,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  // ── New: exec passthrough + tab lifecycle ──
-
-  async browserExec(params: { command: string } & BrowserCommandTargetParams): Promise<unknown> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    return this.requireAgentBrowserBridge().exec(
-      params.command,
-      target.worktreeId,
-      target.browserPageId
-    )
-  }
-
-  async browserTabCreate(params: {
-    url?: string
-    worktree?: string
-    profileId?: string
-  }): Promise<{ browserPageId: string }> {
-    const url = params.url ?? 'about:blank'
-    const worktreeId = params.worktree
-      ? (await this.resolveWorktreeSelector(params.worktree)).id
-      : undefined
-    const { browserPageId } = await this.createBrowserTabInRenderer(
-      url,
-      worktreeId,
-      params.profileId
-    )
-
-    // Why: the renderer creates the Zustand tab immediately, but the webview must
-    // mount and fire dom-ready before registerGuest runs. Waiting here ensures the
-    // tab is operable by subsequent CLI commands (snapshot, click, etc.).
-    // If registration doesn't complete within timeout, return the ID anyway — the
-    // tab exists in the UI but may not be ready for automation commands yet.
-    try {
-      await waitForTabRegistration(browserPageId)
-    } catch {
-      // Tab was created in the renderer but the webview hasn't finished mounting.
-      // Return success since the tab exists; subsequent commands will fail with a
-      // clear "tab not available" error if the webview never loads.
-    }
-
-    // Why: newly created tabs should be auto-activated so subsequent commands
-    // (snapshot, click, goto) target the new tab without requiring an explicit
-    // tab switch. Without this, the bridge's active tab still points at the
-    // previously active tab and the new tab shows active: false in tab list.
-    const bridge = this.requireAgentBrowserBridge()
-    const wcId = bridge.getRegisteredTabs(worktreeId).get(browserPageId)
-    if (wcId != null) {
-      bridge.setActiveTab(wcId, worktreeId)
-    }
-
-    // Why: the renderer sets webview.src=url on mount, but agent-browser connects
-    // via CDP after the webview loads about:blank. Without an explicit goto, the
-    // page stays blank from agent-browser's perspective. Navigate via the bridge
-    // so agent-browser's CDP session tracks the correct page state.
-    if (url && url !== 'about:blank') {
-      try {
-        const result = await bridge.goto(url, worktreeId, browserPageId)
-        this.notifyRendererNavigation(browserPageId, result.url, result.title)
-      } catch {
-        // Tab exists but navigation failed — caller can retry with explicit goto
-      }
-    }
-
-    return { browserPageId }
-  }
-
-  async browserTabSetProfile(
-    params: {
-      profileId: string
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserTabSetProfileResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const browserPageId =
-      target.browserPageId ?? this.requireAgentBrowserBridge().getActivePageId(target.worktreeId)
-    if (!browserPageId) {
-      throw new BrowserError('browser_no_tab', 'No browser tab open in this worktree')
-    }
-    // Why: 'default' is a synthetic id; fall back to the registry's default profile when not registered.
-    const profile =
-      browserSessionRegistry.getProfile(params.profileId) ??
-      (params.profileId === 'default' ? browserSessionRegistry.getDefaultProfile() : null)
-    if (!profile) {
-      throw new BrowserError(
-        'invalid_argument',
-        `Browser profile ${params.profileId} was not found`
-      )
-    }
-
-    // Why: short-circuit no-op switches so the renderer doesn't tear down and
-    // remount the webview when the tab is already on the requested profile.
-    const currentProfileId = browserManager.getSessionProfileIdForTab(browserPageId) ?? 'default'
-    if (currentProfileId === profile.id) {
-      return {
-        browserPageId,
-        profileId: profile.id,
-        profileLabel: profile.label
-      }
-    }
-
-    const win = this.getAuthoritativeWindow()
-    const requestId = randomUUID()
-    await new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        ipcMain.removeListener('browser:tabSetProfileReply', handler)
-        reject(new Error('Tab profile update timed out'))
-      }, 10_000)
-
-      const handler = (
-        _event: Electron.IpcMainEvent,
-        reply: { requestId: string; error?: string }
-      ): void => {
-        if (reply.requestId !== requestId) {
-          return
-        }
-        clearTimeout(timer)
-        ipcMain.removeListener('browser:tabSetProfileReply', handler)
-        if (reply.error) {
-          reject(new Error(reply.error))
-        } else {
-          resolve()
-        }
-      }
-      ipcMain.on('browser:tabSetProfileReply', handler)
-      win.webContents.send('browser:requestTabSetProfile', {
-        requestId,
-        browserPageId,
-        profileId: profile.id
-      })
-    })
-
-    // Why: the renderer destroys the old webview and remounts on the new
-    // partition. Wait for the re-register so a follow-up tab list
-    // --show-profile reads the updated sessionProfileId from BrowserManager
-    // instead of stale data, and so subsequent CLI ops (snapshot, click, etc.)
-    // hit a guest that's already attached.
-    try {
-      await waitForTabRegistration(browserPageId)
-    } catch {
-      // Best-effort: re-register won't fire if the worktree is hidden. The
-      // store already reflects the new profile; downstream commands retry
-      // once the pane re-mounts.
-    }
-
-    return {
-      browserPageId,
-      profileId: profile.id,
-      profileLabel: profile.label
-    }
-  }
-
-  async browserTabProfileShow(params: {
-    page: string
-    worktree?: string
-  }): Promise<BrowserTabProfileShowResult> {
-    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
-    const tab = this.describeBrowserTab(params.page, worktreeId)
-    return {
-      browserPageId: tab.browserPageId,
-      worktreeId: tab.worktreeId ?? null,
-      profileId: tab.profileId ?? null,
-      profileLabel: tab.profileLabel ?? null
-    }
-  }
-
-  async browserTabProfileClone(
-    params: {
-      profileId: string
-    } & BrowserCommandTargetParams
-  ): Promise<BrowserTabProfileCloneResult> {
-    const target = await this.resolveBrowserCommandTarget(params)
-    const sourceBrowserPageId =
-      target.browserPageId ?? this.requireAgentBrowserBridge().getActivePageId(target.worktreeId)
-    if (!sourceBrowserPageId) {
-      throw new BrowserError('browser_no_tab', 'No browser tab open in this worktree')
-    }
-    const sourceTab = this.describeBrowserTab(sourceBrowserPageId, target.worktreeId)
-    const profile = browserSessionRegistry.getProfile(params.profileId)
-    if (!profile) {
-      throw new BrowserError(
-        'invalid_argument',
-        `Browser profile ${params.profileId} was not found`
-      )
-    }
-    const created = await this.createBrowserTabInRenderer(
-      sourceTab.url,
-      sourceTab.worktreeId ?? target.worktreeId,
-      profile.id
-    )
-    // Why: parity with browserTabCreate. Wait for the cloned tab's webview to
-    // register so the returned browserPageId is operable by the next CLI call.
-    try {
-      await waitForTabRegistration(created.browserPageId)
-    } catch {
-      // Best-effort: registration may not fire if the worktree is hidden.
-    }
-    return {
-      browserPageId: created.browserPageId,
-      sourceBrowserPageId,
-      profileId: profile.id,
-      profileLabel: profile.label
-    }
-  }
-
-  async browserProfileList(): Promise<BrowserProfileListResult> {
-    return { profiles: browserSessionRegistry.listProfiles() }
-  }
-
-  async browserProfileCreate(params: {
-    label: string
-    scope: 'isolated' | 'imported'
-  }): Promise<BrowserProfileCreateResult> {
-    return {
-      profile: browserSessionRegistry.createProfile(params.scope, params.label)
-    }
-  }
-
-  async browserProfileDelete(params: { profileId: string }): Promise<BrowserProfileDeleteResult> {
-    return {
-      deleted: await browserSessionRegistry.deleteProfile(params.profileId),
-      profileId: params.profileId
-    }
-  }
-
-  async browserTabClose(params: {
-    index?: number
-    page?: string
-    worktree?: string
-  }): Promise<{ closed: boolean }> {
-    const bridge = this.requireAgentBrowserBridge()
-    const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
-
-    let tabId: string | null = null
-    if (typeof params.page === 'string' && params.page.length > 0) {
-      if (!bridge.getRegisteredTabs(worktreeId).has(params.page)) {
-        const scope = worktreeId ? ' in this worktree' : ''
-        throw new BrowserError(
-          'browser_tab_not_found',
-          `Browser page ${params.page} was not found${scope}`
-        )
-      }
-      tabId = params.page
-    } else if (params.index !== undefined) {
-      const tabs = bridge.getRegisteredTabs(worktreeId)
-      const entries = [...tabs.entries()]
-      if (params.index < 0 || params.index >= entries.length) {
-        throw new Error(`Tab index ${params.index} out of range (0-${entries.length - 1})`)
-      }
-      tabId = entries[params.index][0]
-    } else {
-      // Why: try the bridge first (registered tabs with webviews), then fall back
-      // to asking the renderer to close its active browser tab (handles cases where
-      // the webview hasn't mounted yet, e.g. tab was just created).
-      const tabs = bridge.getRegisteredTabs(worktreeId)
-      const entries = [...tabs.entries()]
-      const activeEntry = entries.find(([, wcId]) => wcId === bridge.getActiveWebContentsId())
-      if (activeEntry) {
-        tabId = activeEntry[0]
-      }
-    }
-
-    const win = this.getAuthoritativeWindow()
-    const requestId = randomUUID()
-    await new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        ipcMain.removeListener('browser:tabCloseReply', handler)
-        reject(new Error('Tab close timed out'))
-      }, 10_000)
-
-      const handler = (
-        _event: Electron.IpcMainEvent,
-        reply: { requestId: string; error?: string }
-      ): void => {
-        if (reply.requestId !== requestId) {
-          return
-        }
-        clearTimeout(timer)
-        ipcMain.removeListener('browser:tabCloseReply', handler)
-        if (reply.error) {
-          reject(new Error(reply.error))
-        } else {
-          resolve()
-        }
-      }
-      ipcMain.on('browser:tabCloseReply', handler)
-      // Why: when main cannot resolve a concrete tab id itself (for example if a
-      // browser workspace exists in the renderer before its guest mounts), the
-      // renderer still needs the intended worktree scope. Otherwise it falls
-      // back to the globally active browser tab and can close a tab in the
-      // wrong worktree.
-      win.webContents.send('browser:requestTabClose', { requestId, tabId, worktreeId })
-    })
-
-    return { closed: true }
-  }
-
-  private enrichBrowserTabInfo(
-    tab: BrowserTabListResult['tabs'][number]
-  ): BrowserTabListResult['tabs'][number] {
-    const rawProfileId = browserManager.getSessionProfileIdForTab(tab.browserPageId)
-    const profile =
-      browserSessionRegistry.getProfile(rawProfileId ?? 'default') ??
-      browserSessionRegistry.getDefaultProfile()
-    return {
-      ...tab,
-      worktreeId: browserManager.getWorktreeIdForTab(tab.browserPageId) ?? null,
-      profileId: profile.id,
-      profileLabel: profile.label
-    }
-  }
-
-  private describeBrowserTab(
-    browserPageId: string,
-    explicitWorktreeId?: string
-  ): BrowserTabListResult['tabs'][number] {
-    const worktreeId = explicitWorktreeId ?? browserManager.getWorktreeIdForTab(browserPageId)
-    const tab = this.requireAgentBrowserBridge()
-      .tabList(worktreeId)
-      .tabs.find((entry) => entry.browserPageId === browserPageId)
-    if (!tab) {
-      const scope = worktreeId ? ' in this worktree' : ''
-      throw new BrowserError(
-        'browser_tab_not_found',
-        `Browser page ${browserPageId} was not found${scope}`
-      )
-    }
-    return this.enrichBrowserTabInfo(tab)
-  }
-
-  private async createBrowserTabInRenderer(
-    url: string,
-    worktreeId?: string,
-    profileId?: string
-  ): Promise<{ browserPageId: string }> {
-    const win = this.getAuthoritativeWindow()
-    const requestId = randomUUID()
-
-    if (worktreeId) {
-      await this.ensureBrowserWorktreeActive(worktreeId)
-    }
-
-    const browserPageId = await new Promise<string>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        ipcMain.removeListener('browser:tabCreateReply', handler)
-        reject(new Error('Tab creation timed out'))
-      }, 10_000)
-
-      const handler = (
-        _event: Electron.IpcMainEvent,
-        reply: { requestId: string; browserPageId?: string; error?: string }
-      ): void => {
-        if (reply.requestId !== requestId) {
-          return
-        }
-        clearTimeout(timer)
-        ipcMain.removeListener('browser:tabCreateReply', handler)
-        if (reply.error) {
-          reject(new Error(reply.error))
-        } else {
-          resolve(reply.browserPageId!)
-        }
-      }
-      ipcMain.on('browser:tabCreateReply', handler)
-      win.webContents.send('browser:requestTabCreate', {
-        requestId,
-        url,
-        worktreeId,
-        sessionProfileId: profileId
-      })
-    })
-
-    return { browserPageId }
-  }
+  private readonly browserCommands = new RuntimeBrowserCommands({
+    getAgentBrowserBridge: () => this.agentBrowserBridge,
+    resolveWorktreeSelector: (selector) => this.resolveWorktreeSelector(selector),
+    getAuthoritativeWindow: () => this.getAuthoritativeWindow(),
+    getAvailableAuthoritativeWindow: () => this.getAvailableAuthoritativeWindow()
+  })
+
+  browserSnapshot: RuntimeBrowserCommands['browserSnapshot'] =
+    this.browserCommands.browserSnapshot.bind(this.browserCommands)
+
+  browserClick: RuntimeBrowserCommands['browserClick'] = this.browserCommands.browserClick.bind(
+    this.browserCommands
+  )
+
+  browserGoto: RuntimeBrowserCommands['browserGoto'] = this.browserCommands.browserGoto.bind(
+    this.browserCommands
+  )
+
+  browserFill: RuntimeBrowserCommands['browserFill'] = this.browserCommands.browserFill.bind(
+    this.browserCommands
+  )
+
+  browserType: RuntimeBrowserCommands['browserType'] = this.browserCommands.browserType.bind(
+    this.browserCommands
+  )
+
+  browserSelect: RuntimeBrowserCommands['browserSelect'] = this.browserCommands.browserSelect.bind(
+    this.browserCommands
+  )
+
+  browserScroll: RuntimeBrowserCommands['browserScroll'] = this.browserCommands.browserScroll.bind(
+    this.browserCommands
+  )
+
+  browserBack: RuntimeBrowserCommands['browserBack'] = this.browserCommands.browserBack.bind(
+    this.browserCommands
+  )
+
+  browserReload: RuntimeBrowserCommands['browserReload'] = this.browserCommands.browserReload.bind(
+    this.browserCommands
+  )
+
+  browserScreenshot: RuntimeBrowserCommands['browserScreenshot'] =
+    this.browserCommands.browserScreenshot.bind(this.browserCommands)
+
+  browserEval: RuntimeBrowserCommands['browserEval'] = this.browserCommands.browserEval.bind(
+    this.browserCommands
+  )
+
+  browserTabList: RuntimeBrowserCommands['browserTabList'] =
+    this.browserCommands.browserTabList.bind(this.browserCommands)
+
+  browserTabShow: RuntimeBrowserCommands['browserTabShow'] =
+    this.browserCommands.browserTabShow.bind(this.browserCommands)
+
+  browserTabCurrent: RuntimeBrowserCommands['browserTabCurrent'] =
+    this.browserCommands.browserTabCurrent.bind(this.browserCommands)
+
+  browserTabSwitch: RuntimeBrowserCommands['browserTabSwitch'] =
+    this.browserCommands.browserTabSwitch.bind(this.browserCommands)
+
+  browserHover: RuntimeBrowserCommands['browserHover'] = this.browserCommands.browserHover.bind(
+    this.browserCommands
+  )
+
+  browserDrag: RuntimeBrowserCommands['browserDrag'] = this.browserCommands.browserDrag.bind(
+    this.browserCommands
+  )
+
+  browserUpload: RuntimeBrowserCommands['browserUpload'] = this.browserCommands.browserUpload.bind(
+    this.browserCommands
+  )
+
+  browserWait: RuntimeBrowserCommands['browserWait'] = this.browserCommands.browserWait.bind(
+    this.browserCommands
+  )
+
+  browserCheck: RuntimeBrowserCommands['browserCheck'] = this.browserCommands.browserCheck.bind(
+    this.browserCommands
+  )
+
+  browserFocus: RuntimeBrowserCommands['browserFocus'] = this.browserCommands.browserFocus.bind(
+    this.browserCommands
+  )
+
+  browserClear: RuntimeBrowserCommands['browserClear'] = this.browserCommands.browserClear.bind(
+    this.browserCommands
+  )
+
+  browserSelectAll: RuntimeBrowserCommands['browserSelectAll'] =
+    this.browserCommands.browserSelectAll.bind(this.browserCommands)
+
+  browserKeypress: RuntimeBrowserCommands['browserKeypress'] =
+    this.browserCommands.browserKeypress.bind(this.browserCommands)
+
+  browserPdf: RuntimeBrowserCommands['browserPdf'] = this.browserCommands.browserPdf.bind(
+    this.browserCommands
+  )
+
+  browserFullScreenshot: RuntimeBrowserCommands['browserFullScreenshot'] =
+    this.browserCommands.browserFullScreenshot.bind(this.browserCommands)
+
+  browserCookieGet: RuntimeBrowserCommands['browserCookieGet'] =
+    this.browserCommands.browserCookieGet.bind(this.browserCommands)
+
+  browserCookieSet: RuntimeBrowserCommands['browserCookieSet'] =
+    this.browserCommands.browserCookieSet.bind(this.browserCommands)
+
+  browserCookieDelete: RuntimeBrowserCommands['browserCookieDelete'] =
+    this.browserCommands.browserCookieDelete.bind(this.browserCommands)
+
+  browserSetViewport: RuntimeBrowserCommands['browserSetViewport'] =
+    this.browserCommands.browserSetViewport.bind(this.browserCommands)
+
+  browserSetGeolocation: RuntimeBrowserCommands['browserSetGeolocation'] =
+    this.browserCommands.browserSetGeolocation.bind(this.browserCommands)
+
+  browserInterceptEnable: RuntimeBrowserCommands['browserInterceptEnable'] =
+    this.browserCommands.browserInterceptEnable.bind(this.browserCommands)
+
+  browserInterceptDisable: RuntimeBrowserCommands['browserInterceptDisable'] =
+    this.browserCommands.browserInterceptDisable.bind(this.browserCommands)
+
+  browserInterceptList: RuntimeBrowserCommands['browserInterceptList'] =
+    this.browserCommands.browserInterceptList.bind(this.browserCommands)
+
+  browserCaptureStart: RuntimeBrowserCommands['browserCaptureStart'] =
+    this.browserCommands.browserCaptureStart.bind(this.browserCommands)
+
+  browserCaptureStop: RuntimeBrowserCommands['browserCaptureStop'] =
+    this.browserCommands.browserCaptureStop.bind(this.browserCommands)
+
+  browserConsoleLog: RuntimeBrowserCommands['browserConsoleLog'] =
+    this.browserCommands.browserConsoleLog.bind(this.browserCommands)
+
+  browserNetworkLog: RuntimeBrowserCommands['browserNetworkLog'] =
+    this.browserCommands.browserNetworkLog.bind(this.browserCommands)
+
+  browserDblclick: RuntimeBrowserCommands['browserDblclick'] =
+    this.browserCommands.browserDblclick.bind(this.browserCommands)
+
+  browserForward: RuntimeBrowserCommands['browserForward'] =
+    this.browserCommands.browserForward.bind(this.browserCommands)
+
+  browserScrollIntoView: RuntimeBrowserCommands['browserScrollIntoView'] =
+    this.browserCommands.browserScrollIntoView.bind(this.browserCommands)
+
+  browserGet: RuntimeBrowserCommands['browserGet'] = this.browserCommands.browserGet.bind(
+    this.browserCommands
+  )
+
+  browserIs: RuntimeBrowserCommands['browserIs'] = this.browserCommands.browserIs.bind(
+    this.browserCommands
+  )
+
+  browserKeyboardInsertText: RuntimeBrowserCommands['browserKeyboardInsertText'] =
+    this.browserCommands.browserKeyboardInsertText.bind(this.browserCommands)
+
+  browserMouseMove: RuntimeBrowserCommands['browserMouseMove'] =
+    this.browserCommands.browserMouseMove.bind(this.browserCommands)
+
+  browserMouseDown: RuntimeBrowserCommands['browserMouseDown'] =
+    this.browserCommands.browserMouseDown.bind(this.browserCommands)
+
+  browserMouseUp: RuntimeBrowserCommands['browserMouseUp'] =
+    this.browserCommands.browserMouseUp.bind(this.browserCommands)
+
+  browserMouseWheel: RuntimeBrowserCommands['browserMouseWheel'] =
+    this.browserCommands.browserMouseWheel.bind(this.browserCommands)
+
+  browserFind: RuntimeBrowserCommands['browserFind'] = this.browserCommands.browserFind.bind(
+    this.browserCommands
+  )
+
+  browserSetDevice: RuntimeBrowserCommands['browserSetDevice'] =
+    this.browserCommands.browserSetDevice.bind(this.browserCommands)
+
+  browserSetOffline: RuntimeBrowserCommands['browserSetOffline'] =
+    this.browserCommands.browserSetOffline.bind(this.browserCommands)
+
+  browserSetHeaders: RuntimeBrowserCommands['browserSetHeaders'] =
+    this.browserCommands.browserSetHeaders.bind(this.browserCommands)
+
+  browserSetCredentials: RuntimeBrowserCommands['browserSetCredentials'] =
+    this.browserCommands.browserSetCredentials.bind(this.browserCommands)
+
+  browserSetMedia: RuntimeBrowserCommands['browserSetMedia'] =
+    this.browserCommands.browserSetMedia.bind(this.browserCommands)
+
+  browserClipboardRead: RuntimeBrowserCommands['browserClipboardRead'] =
+    this.browserCommands.browserClipboardRead.bind(this.browserCommands)
+
+  browserClipboardWrite: RuntimeBrowserCommands['browserClipboardWrite'] =
+    this.browserCommands.browserClipboardWrite.bind(this.browserCommands)
+
+  browserDialogAccept: RuntimeBrowserCommands['browserDialogAccept'] =
+    this.browserCommands.browserDialogAccept.bind(this.browserCommands)
+
+  browserDialogDismiss: RuntimeBrowserCommands['browserDialogDismiss'] =
+    this.browserCommands.browserDialogDismiss.bind(this.browserCommands)
+
+  browserStorageLocalGet: RuntimeBrowserCommands['browserStorageLocalGet'] =
+    this.browserCommands.browserStorageLocalGet.bind(this.browserCommands)
+
+  browserStorageLocalSet: RuntimeBrowserCommands['browserStorageLocalSet'] =
+    this.browserCommands.browserStorageLocalSet.bind(this.browserCommands)
+
+  browserStorageLocalClear: RuntimeBrowserCommands['browserStorageLocalClear'] =
+    this.browserCommands.browserStorageLocalClear.bind(this.browserCommands)
+
+  browserStorageSessionGet: RuntimeBrowserCommands['browserStorageSessionGet'] =
+    this.browserCommands.browserStorageSessionGet.bind(this.browserCommands)
+
+  browserStorageSessionSet: RuntimeBrowserCommands['browserStorageSessionSet'] =
+    this.browserCommands.browserStorageSessionSet.bind(this.browserCommands)
+
+  browserStorageSessionClear: RuntimeBrowserCommands['browserStorageSessionClear'] =
+    this.browserCommands.browserStorageSessionClear.bind(this.browserCommands)
+
+  browserDownload: RuntimeBrowserCommands['browserDownload'] =
+    this.browserCommands.browserDownload.bind(this.browserCommands)
+
+  browserHighlight: RuntimeBrowserCommands['browserHighlight'] =
+    this.browserCommands.browserHighlight.bind(this.browserCommands)
+
+  browserExec: RuntimeBrowserCommands['browserExec'] = this.browserCommands.browserExec.bind(
+    this.browserCommands
+  )
+
+  browserTabCreate: RuntimeBrowserCommands['browserTabCreate'] =
+    this.browserCommands.browserTabCreate.bind(this.browserCommands)
+
+  browserTabSetProfile: RuntimeBrowserCommands['browserTabSetProfile'] =
+    this.browserCommands.browserTabSetProfile.bind(this.browserCommands)
+
+  browserTabProfileShow: RuntimeBrowserCommands['browserTabProfileShow'] =
+    this.browserCommands.browserTabProfileShow.bind(this.browserCommands)
+
+  browserTabProfileClone: RuntimeBrowserCommands['browserTabProfileClone'] =
+    this.browserCommands.browserTabProfileClone.bind(this.browserCommands)
+
+  browserProfileList: RuntimeBrowserCommands['browserProfileList'] =
+    this.browserCommands.browserProfileList.bind(this.browserCommands)
+
+  browserProfileCreate: RuntimeBrowserCommands['browserProfileCreate'] =
+    this.browserCommands.browserProfileCreate.bind(this.browserCommands)
+
+  browserProfileDelete: RuntimeBrowserCommands['browserProfileDelete'] =
+    this.browserCommands.browserProfileDelete.bind(this.browserCommands)
+
+  browserProfileDetectBrowsers: RuntimeBrowserCommands['browserProfileDetectBrowsers'] =
+    this.browserCommands.browserProfileDetectBrowsers.bind(this.browserCommands)
+
+  browserProfileImportFromBrowser: RuntimeBrowserCommands['browserProfileImportFromBrowser'] =
+    this.browserCommands.browserProfileImportFromBrowser.bind(this.browserCommands)
+
+  browserProfileClearDefaultCookies: RuntimeBrowserCommands['browserProfileClearDefaultCookies'] =
+    this.browserCommands.browserProfileClearDefaultCookies.bind(this.browserCommands)
+
+  browserTabClose: RuntimeBrowserCommands['browserTabClose'] =
+    this.browserCommands.browserTabClose.bind(this.browserCommands)
 
   private getAuthoritativeWindow(): BrowserWindow {
-    if (this.authoritativeWindowId === null) {
-      throw new Error('No renderer window available')
-    }
-    const win = BrowserWindow.fromId(this.authoritativeWindowId)
+    const win = this.getAvailableAuthoritativeWindow()
     if (!win || win.isDestroyed()) {
       throw new Error('No renderer window available')
     }
     return win
   }
+
+  private getAvailableAuthoritativeWindow(): BrowserWindow | null {
+    if (this.authoritativeWindowId === null) {
+      return null
+    }
+    if (!BrowserWindow?.fromId) {
+      return null
+    }
+    const win = BrowserWindow.fromId(this.authoritativeWindowId)
+    return win && !win.isDestroyed() ? win : null
+  }
 }
 
 const MAX_TAIL_LINES = 120
@@ -7922,6 +8276,10 @@ function branchSelectorMatches(branch: string, selector: string): boolean {
   return normalizeBranchRef(branch) === normalizeBranchRef(selector)
 }
 
+function runtimePathsEqual(left: string, right: string): boolean {
+  return normalizeRuntimePathForComparison(left) === normalizeRuntimePathForComparison(right)
+}
+
 function normalizeBranchRef(branch: string): string {
   return branch.startsWith('refs/heads/') ? branch.slice('refs/heads/'.length) : branch
 }
@@ -7956,23 +8314,11 @@ function findResolvedWorktreeIdForPath(
     return null
   }
   const matches = resolvedWorktrees
-    .filter(
-      (worktree) =>
-        areWorktreePathsEqual(worktree.path, cwd) || isPathInsideWorktree(cwd, worktree.path)
-    )
+    .filter((worktree) => isPathInsideOrEqual(worktree.path, cwd))
     .sort((left, right) => right.path.length - left.path.length)
   return matches[0]?.id ?? null
 }
 
-function isPathInsideWorktree(candidatePath: string, worktreePath: string): boolean {
-  if (candidatePath === worktreePath) {
-    return true
-  }
-  const normalizedCandidate = candidatePath.replace(/\\/g, '/').replace(/\/+$/, '')
-  const normalizedWorktree = worktreePath.replace(/\\/g, '/').replace(/\/+$/, '')
-  return normalizedCandidate.startsWith(`${normalizedWorktree}/`)
-}
-
 function getLeafWorktreeStatus(
   leaf: RuntimeLeafRecord,
   tabTitle: string | null
@@ -8033,72 +8379,6 @@ function maxTimestamp(left: number | null, right: number | null): number | null
   return Math.max(left, right)
 }
 
-function isSafeMobileRelativePath(relativePath: string): boolean {
-  if (!relativePath || relativePath.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(relativePath)) {
-    return false
-  }
-  const parts = relativePath.replace(/\\/g, '/').split('/')
-  return parts.every((part) => part !== '' && part !== '.' && part !== '..')
-}
-
-function isMobileMarkdownPath(relativePath: string): boolean {
-  return /\.(md|mdx|markdown)$/i.test(relativePath)
-}
-
-function isMobileBinaryPath(relativePath: string): boolean {
-  const basename = basenameFromRelativePath(relativePath)
-  const dotIndex = basename.lastIndexOf('.')
-  if (dotIndex <= 0) {
-    return false
-  }
-  return MOBILE_BINARY_EXTENSIONS.has(basename.slice(dotIndex).toLowerCase())
-}
-
-function basenameFromRelativePath(relativePath: string): string {
-  const normalized = relativePath.replace(/\\/g, '/')
-  return normalized.slice(normalized.lastIndexOf('/') + 1)
-}
-
-function joinWorktreeRelativePath(rootPath: string, relativePath: string): string {
-  const normalizedRelativePath = relativePath.replace(/\\/g, '/')
-  if (/^[a-zA-Z]:[\\/]/.test(rootPath) || rootPath.startsWith('\\\\')) {
-    return win32.join(rootPath, ...normalizedRelativePath.split('/'))
-  }
-  return posix.join(rootPath, ...normalizedRelativePath.split('/'))
-}
-
-async function readLocalMobileFile(filePath: string, store: Store): Promise<string> {
-  const authorizedPath = await resolveAuthorizedPath(filePath, store)
-  const fileStat = await stat(authorizedPath)
-  // Why: mobile file previews are read-only convenience views; cap the read so
-  // opening a generated log or bundle cannot block the WebSocket like oversized scrollback.
-  const readLimit = Math.min(fileStat.size, MOBILE_FILE_READ_MAX_BYTES + 1)
-  const handle = await open(authorizedPath, 'r')
-  try {
-    const buffer = Buffer.alloc(readLimit)
-    const { bytesRead } = await handle.read(buffer, 0, readLimit, 0)
-    return buffer.subarray(0, bytesRead).toString('utf8')
-  } finally {
-    await handle.close()
-  }
-}
-
-function truncateMobileFilePreview(content: string): {
-  content: string
-  truncated: boolean
-  byteLength: number
-} {
-  const buffer = Buffer.from(content, 'utf8')
-  if (buffer.byteLength <= MOBILE_FILE_READ_MAX_BYTES) {
-    return { content, truncated: false, byteLength: buffer.byteLength }
-  }
-  return {
-    content: buffer.subarray(0, MOBILE_FILE_READ_MAX_BYTES).toString('utf8'),
-    truncated: true,
-    byteLength: buffer.byteLength
-  }
-}
-
 function compareWorktreePs(
   left: RuntimeWorktreePsSummary,
   right: RuntimeWorktreePsSummary
diff --git a/src/cli/orchestration.subprocess.test.ts b/src/main/runtime/orchestration-cli-subprocess.test.ts
similarity index 93%
rename from src/cli/orchestration.subprocess.test.ts
rename to src/main/runtime/orchestration-cli-subprocess.test.ts
index c8648ceafe6..054328a9653 100644
--- a/src/cli/orchestration.subprocess.test.ts
+++ b/src/main/runtime/orchestration-cli-subprocess.test.ts
@@ -20,9 +20,9 @@ import { existsSync, mkdtempSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { describe, expect, it } from 'vitest'
-import { OrcaRuntimeService } from '../main/runtime/orca-runtime'
-import { OrchestrationDb } from '../main/runtime/orchestration/db'
-import { OrcaRuntimeRpcServer } from '../main/runtime/runtime-rpc'
+import { OrcaRuntimeService } from './orca-runtime'
+import { OrchestrationDb } from './orchestration/db'
+import { OrcaRuntimeRpcServer } from './runtime-rpc'
 
 // Why: Vitest runs tests with `process.cwd()` pinned to the repo root, so
 // join against it to locate the compiled CLI regardless of where this test
@@ -108,12 +108,12 @@ describeIfBuilt('orca orchestration check --wait subprocess (§3.4)', () => {
       expect(heartbeatLines[0]).toHaveProperty('elapsedMs')
       expect(heartbeatLines[0]).toHaveProperty('deadlineMs', waitTimeoutMs)
 
-      // Why: first heartbeat must arrive within one interval + scheduler
-      // slack (300ms is generous); if the stream were fully buffered we'd
-      // see everything only after exit.
+      // Why: under full-suite load the child process startup may take longer
+      // than one heartbeat interval. The invariant that matters is that at
+      // least one heartbeat is observed before the terminal stdout payload.
       const firstHeartbeatChunk = stderrChunks.find((c) => c.data.includes('_heartbeat'))
       expect(firstHeartbeatChunk).toBeDefined()
-      expect(firstHeartbeatChunk!.at).toBeLessThan(heartbeatMs + 300)
+      expect(firstHeartbeatChunk!.at).toBeLessThan(stdoutChunks[0]?.at ?? Number.POSITIVE_INFINITY)
 
       // Why: line-flushing proof — the *first* heartbeat chunk must arrive
       // strictly before the exit chunk; i.e. we got at least two separate
diff --git a/src/main/runtime/remote-runtime-request-connection.integration.test.ts b/src/main/runtime/remote-runtime-request-connection.integration.test.ts
new file mode 100644
index 00000000000..540ad425b58
--- /dev/null
+++ b/src/main/runtime/remote-runtime-request-connection.integration.test.ts
@@ -0,0 +1,67 @@
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { describe, expect, it } from 'vitest'
+import { getDefaultRepoHookSettings } from '../../shared/constants'
+import type { Repo } from '../../shared/types'
+import { parsePairingCode } from '../../shared/pairing'
+import { RemoteRuntimeRequestConnection } from '../../shared/remote-runtime-request-connection'
+import type { OrcaRuntimeService } from './orca-runtime'
+import { OrcaRuntimeRpcServer } from './runtime-rpc'
+
+describe('remote runtime request connection integration', () => {
+  it('fetches repos through the real E2EE WebSocket runtime', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-request-'))
+    const repoPath = join(userDataPath, 'repo')
+    const repos: Repo[] = [
+      {
+        id: 'repo-1',
+        path: repoPath,
+        displayName: 'repo',
+        badgeColor: 'blue',
+        addedAt: 1,
+        hookSettings: getDefaultRepoHookSettings(),
+        worktreeBaseRef: 'main',
+        kind: 'git'
+      }
+    ]
+    const runtime = {
+      getRuntimeId: () => 'runtime-test',
+      getStartedAt: () => 1,
+      cleanupSubscriptionsForConnection: () => {},
+      cancelMobileDictationForConnection: () => {},
+      onClientDisconnected: () => {},
+      listRepos: () => repos
+    } as unknown as OrcaRuntimeService
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+
+    await server.start()
+    try {
+      const offer = server.createPairingOffer({ name: 'integration', scope: 'runtime' })
+      if (!offer.available) {
+        throw new Error('pairing unavailable')
+      }
+      const pairing = parsePairingCode(offer.pairingUrl)
+      if (!pairing) {
+        throw new Error('invalid pairing')
+      }
+      const connection = new RemoteRuntimeRequestConnection(pairing)
+      try {
+        await expect(connection.request('repo.list', undefined, 1000)).resolves.toMatchObject({
+          ok: true,
+          result: { repos }
+        })
+      } finally {
+        connection.close()
+      }
+    } finally {
+      await server.stop()
+      rmSync(userDataPath, { recursive: true, force: true })
+    }
+  })
+})
diff --git a/src/main/runtime/rpc/core.ts b/src/main/runtime/rpc/core.ts
index bdbc6e5b63b..4e51248c0b4 100644
--- a/src/main/runtime/rpc/core.ts
+++ b/src/main/runtime/rpc/core.ts
@@ -3,6 +3,7 @@
 // CLI-facing contract greppable and lets the dispatcher verify every payload
 // against the same shape the handler consumed during development.
 import { ZodError, type ZodType } from 'zod'
+import type { TerminalStreamFrame } from '../../../shared/terminal-stream-protocol'
 import type { OrcaRuntimeService } from '../orca-runtime'
 
 export type RpcEnvelopeMeta = {
@@ -59,6 +60,13 @@ export type RpcContext = {
   // responses after the binary terminal cutover. Undefined on Unix/socket
   // transports and non-E2EE WebSocket paths.
   sendBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+  // Why: binary terminal input/resize frames arrive outside JSON-RPC after a
+  // stream is established. The WebSocket transport owns the connection-scoped
+  // stream table; handlers register only the stream IDs they created.
+  registerBinaryStreamHandler?: (
+    streamId: number,
+    handler: (frame: TerminalStreamFrame) => void
+  ) => () => void
 }
 
 export type RpcHandler<TParams> = (params: TParams, ctx: RpcContext) => Promise<unknown> | unknown
diff --git a/src/main/runtime/rpc/dispatcher.ts b/src/main/runtime/rpc/dispatcher.ts
index edd247cd92e..aa693b5b1b1 100644
--- a/src/main/runtime/rpc/dispatcher.ts
+++ b/src/main/runtime/rpc/dispatcher.ts
@@ -13,6 +13,7 @@ import {
   type RpcRequest,
   type RpcResponse
 } from './core'
+import type { TerminalStreamFrame } from '../../../shared/terminal-stream-protocol'
 import { errorResponse, mapBrowserError, mapRuntimeError, successResponse } from './errors'
 import { ALL_RPC_METHODS } from './methods'
 import type { OrcaRuntimeService } from '../orca-runtime'
@@ -79,8 +80,13 @@ export class RpcDispatcher {
     reply: (response: string) => void,
     options?: {
       connectionId?: string
+      signal?: AbortSignal
       clientId?: string
       sendBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+      registerBinaryStreamHandler?: (
+        streamId: number,
+        handler: (frame: TerminalStreamFrame) => void
+      ) => () => void
     }
   ): Promise<void> {
     const meta = this.meta()
@@ -104,9 +110,11 @@ export class RpcDispatcher {
       try {
         const result = await method.handler(parsedParams.value, {
           runtime: this.runtime,
+          signal: options?.signal,
           connectionId: options?.connectionId,
           clientId: options?.clientId,
-          sendBinary: options?.sendBinary
+          sendBinary: options?.sendBinary,
+          registerBinaryStreamHandler: options?.registerBinaryStreamHandler
         })
         reply(JSON.stringify(successResponse(request.id, meta, result)))
       } catch (error) {
@@ -126,9 +134,11 @@ export class RpcDispatcher {
         parsedParams.value,
         {
           runtime: this.runtime,
+          signal: options?.signal,
           connectionId: options?.connectionId,
           clientId: options?.clientId,
-          sendBinary: options?.sendBinary
+          sendBinary: options?.sendBinary,
+          registerBinaryStreamHandler: options?.registerBinaryStreamHandler
         },
         emit
       )
diff --git a/src/main/runtime/rpc/e2ee-channel.test.ts b/src/main/runtime/rpc/e2ee-channel.test.ts
index 69b242c4ca8..a1daec13669 100644
--- a/src/main/runtime/rpc/e2ee-channel.test.ts
+++ b/src/main/runtime/rpc/e2ee-channel.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import type { WebSocket } from 'ws'
 import { E2EEChannel, type E2EEChannelOptions } from './e2ee-channel'
-import { generateKeyPair, deriveSharedKey, encrypt, decrypt } from './e2ee-crypto'
+import { generateKeyPair, deriveSharedKey, encrypt, decrypt, encryptBytes } from './e2ee-crypto'
 
 function publicKeyToBase64(key: Uint8Array): string {
   return Buffer.from(key).toString('base64')
@@ -182,6 +182,20 @@ describe('E2EEChannel', () => {
       expect(replyPlain).toBe('{"id":"rpc-1","ok":true}')
     })
 
+    it('decrypts and forwards binary messages after authentication', () => {
+      const ctx = setup()
+      const sharedKey = doHandshake(ctx)
+      const received: Uint8Array<ArrayBufferLike>[] = []
+
+      ctx.channel.onBinaryMessage((bytes) => {
+        received.push(bytes)
+      })
+
+      ctx.channel.handleRawMessage(encryptBytes(new Uint8Array([1, 2, 3]), sharedKey))
+
+      expect([...received[0]!]).toEqual([1, 2, 3])
+    })
+
     it('silently drops messages with wrong key', () => {
       const ctx = setup()
       doHandshake(ctx)
diff --git a/src/main/runtime/rpc/e2ee-channel.ts b/src/main/runtime/rpc/e2ee-channel.ts
index a105b882a0a..279da548310 100644
--- a/src/main/runtime/rpc/e2ee-channel.ts
+++ b/src/main/runtime/rpc/e2ee-channel.ts
@@ -46,6 +46,7 @@ export class E2EEChannel {
         encryptedBinaryReply: (response: Uint8Array<ArrayBufferLike>) => void
       ) => void)
     | null = null
+  private binaryMessageHandler: ((plaintext: Uint8Array<ArrayBufferLike>) => void) | null = null
 
   deviceToken: string | null = null
 
@@ -71,6 +72,10 @@ export class E2EEChannel {
     this.messageHandler = handler
   }
 
+  onBinaryMessage(handler: (plaintext: Uint8Array<ArrayBufferLike>) => void): void {
+    this.binaryMessageHandler = handler
+  }
+
   handleRawMessage(raw: string | Uint8Array<ArrayBufferLike>): void {
     if (this.state === 'awaiting_hello') {
       if (typeof raw !== 'string') {
@@ -89,7 +94,14 @@ export class E2EEChannel {
       const plaintextBytes = decryptBytes(raw, this.sharedKey)
       if (plaintextBytes === null) {
         this.trackDecryptFailure()
+        return
       }
+      this.consecutiveFailures = 0
+      if (this.state !== 'ready') {
+        this.onError(4001, 'Invalid binary message before authentication')
+        return
+      }
+      this.binaryMessageHandler?.(plaintextBytes)
       return
     }
 
@@ -211,5 +223,6 @@ export class E2EEChannel {
     }
     this.sharedKey = null
     this.messageHandler = null
+    this.binaryMessageHandler = null
   }
 }
diff --git a/src/main/runtime/rpc/e2ee-crypto.ts b/src/main/runtime/rpc/e2ee-crypto.ts
index 40818c424b5..f0f4f460d83 100644
--- a/src/main/runtime/rpc/e2ee-crypto.ts
+++ b/src/main/runtime/rpc/e2ee-crypto.ts
@@ -1,53 +1,8 @@
-// Why: shared E2EE primitives for the desktop side. Wraps tweetnacl to provide
-// encrypt/decrypt with the NaCl box format: [24-byte nonce][ciphertext]. JSON
-// RPC uses base64 text frames; terminal streams use the raw byte bundle.
-import nacl from 'tweetnacl'
-
-export function generateKeyPair(): nacl.BoxKeyPair {
-  return nacl.box.keyPair()
-}
-
-export function deriveSharedKey(ourSecretKey: Uint8Array, peerPublicKey: Uint8Array): Uint8Array {
-  return nacl.box.before(peerPublicKey, ourSecretKey)
-}
-
-export function encrypt(plaintext: string, sharedKey: Uint8Array): string {
-  const messageBytes = new TextEncoder().encode(plaintext)
-  return Buffer.from(encryptBytes(messageBytes, sharedKey)).toString('base64')
-}
-
-export function decrypt(encrypted: string, sharedKey: Uint8Array): string | null {
-  const bundle = Uint8Array.from(Buffer.from(encrypted, 'base64'))
-  const plaintext = decryptBytes(bundle, sharedKey)
-  return plaintext ? new TextDecoder().decode(plaintext) : null
-}
-
-export function encryptBytes(
-  plaintext: Uint8Array<ArrayBufferLike>,
-  sharedKey: Uint8Array
-): Uint8Array {
-  const nonce = nacl.randomBytes(nacl.box.nonceLength)
-  const ciphertext = nacl.box.after(plaintext, nonce, sharedKey)
-
-  const bundle = new Uint8Array(nonce.length + ciphertext.length)
-  bundle.set(nonce)
-  bundle.set(ciphertext, nonce.length)
-
-  return bundle
-}
-
-export function decryptBytes(bundle: Uint8Array, sharedKey: Uint8Array): Uint8Array | null {
-  if (bundle.length < nacl.box.nonceLength + nacl.box.overheadLength) {
-    return null
-  }
-
-  const nonce = bundle.slice(0, nacl.box.nonceLength)
-  const ciphertext = bundle.slice(nacl.box.nonceLength)
-  const plaintext = nacl.box.open.after(ciphertext, nonce, sharedKey)
-
-  if (!plaintext) {
-    return null
-  }
-
-  return plaintext
-}
+export {
+  decrypt,
+  decryptBytes,
+  deriveSharedKey,
+  encrypt,
+  encryptBytes,
+  generateKeyPair
+} from '../../../shared/e2ee-crypto'
diff --git a/src/main/runtime/rpc/methods/browser-core.ts b/src/main/runtime/rpc/methods/browser-core.ts
index b141c0b14a3..3736aaf5e74 100644
--- a/src/main/runtime/rpc/methods/browser-core.ts
+++ b/src/main/runtime/rpc/methods/browser-core.ts
@@ -18,6 +18,7 @@ import {
   LimitParam,
   ProfileCreate,
   ProfileDelete,
+  ProfileImportFromBrowser,
   Screenshot,
   Scroll,
   Select,
@@ -151,6 +152,21 @@ export const BROWSER_CORE_METHODS: RpcMethod[] = [
     params: ProfileDelete,
     handler: async (params, { runtime }) => runtime.browserProfileDelete(params)
   }),
+  defineMethod({
+    name: 'browser.profileDetectBrowsers',
+    params: null,
+    handler: async (_params, { runtime }) => runtime.browserProfileDetectBrowsers()
+  }),
+  defineMethod({
+    name: 'browser.profileImportFromBrowser',
+    params: ProfileImportFromBrowser,
+    handler: async (params, { runtime }) => runtime.browserProfileImportFromBrowser(params)
+  }),
+  defineMethod({
+    name: 'browser.profileClearDefaultCookies',
+    params: null,
+    handler: async (_params, { runtime }) => runtime.browserProfileClearDefaultCookies()
+  }),
   defineMethod({
     name: 'browser.hover',
     params: Element,
diff --git a/src/main/runtime/rpc/methods/browser-schemas.ts b/src/main/runtime/rpc/methods/browser-schemas.ts
index 0a216c1d9e0..1009429d625 100644
--- a/src/main/runtime/rpc/methods/browser-schemas.ts
+++ b/src/main/runtime/rpc/methods/browser-schemas.ts
@@ -143,6 +143,12 @@ export const ProfileDelete = z.object({
   profileId: requiredString('Missing required --profile')
 })
 
+export const ProfileImportFromBrowser = z.object({
+  profileId: requiredString('Missing required --profile'),
+  browserFamily: requiredString('Missing required --browser-family'),
+  browserProfile: OptionalString
+})
+
 export const Drag = BrowserTarget.extend({
   from: requiredString('Missing required --from and --to element refs'),
   to: requiredString('Missing required --from and --to element refs')
diff --git a/src/main/runtime/rpc/methods/browser.test.ts b/src/main/runtime/rpc/methods/browser.test.ts
new file mode 100644
index 00000000000..0312593e6b8
--- /dev/null
+++ b/src/main/runtime/rpc/methods/browser.test.ts
@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { BROWSER_CORE_METHODS } from './browser-core'
+import { BROWSER_EXTRA_METHODS } from './browser-extras'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('browser RPC methods', () => {
+  it('routes core browser automation commands to the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      browserSnapshot: vi.fn().mockResolvedValue({ elements: [] }),
+      browserGoto: vi.fn().mockResolvedValue({ url: 'https://example.com' }),
+      browserProfileDetectBrowsers: vi.fn().mockResolvedValue({ browsers: [] }),
+      browserProfileImportFromBrowser: vi.fn().mockResolvedValue({ ok: false, reason: 'empty' }),
+      browserTabCreate: vi.fn().mockResolvedValue({ browserPageId: 'page-1' }),
+      browserTabSwitch: vi.fn().mockResolvedValue({ browserPageId: 'page-1' })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: BROWSER_CORE_METHODS })
+
+    await dispatcher.dispatch(makeRequest('browser.snapshot', { worktree: 'id:wt-1' }))
+    await dispatcher.dispatch(
+      makeRequest('browser.goto', {
+        worktree: 'id:wt-1',
+        page: 'page-1',
+        url: 'https://example.com'
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('browser.tabCreate', {
+        worktree: 'id:wt-1',
+        url: 'https://example.com',
+        profileId: 'profile-1'
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('browser.tabSwitch', {
+        worktree: 'id:wt-1',
+        index: 0,
+        focus: true
+      })
+    )
+    await dispatcher.dispatch(makeRequest('browser.profileDetectBrowsers'))
+    await dispatcher.dispatch(
+      makeRequest('browser.profileImportFromBrowser', {
+        profileId: 'profile-1',
+        browserFamily: 'chrome',
+        browserProfile: 'Default'
+      })
+    )
+
+    expect(runtime.browserSnapshot).toHaveBeenCalledWith({ worktree: 'id:wt-1' })
+    expect(runtime.browserGoto).toHaveBeenCalledWith({
+      worktree: 'id:wt-1',
+      page: 'page-1',
+      url: 'https://example.com'
+    })
+    expect(runtime.browserTabCreate).toHaveBeenCalledWith({
+      worktree: 'id:wt-1',
+      url: 'https://example.com',
+      profileId: 'profile-1'
+    })
+    expect(runtime.browserTabSwitch).toHaveBeenCalledWith({
+      worktree: 'id:wt-1',
+      index: 0,
+      focus: true
+    })
+    expect(runtime.browserProfileDetectBrowsers).toHaveBeenCalled()
+    expect(runtime.browserProfileImportFromBrowser).toHaveBeenCalledWith({
+      profileId: 'profile-1',
+      browserFamily: 'chrome',
+      browserProfile: 'Default'
+    })
+  })
+
+  it('routes browser session and environment controls to the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      browserCookieGet: vi.fn().mockResolvedValue({ cookies: [] }),
+      browserSetViewport: vi.fn().mockResolvedValue({ ok: true }),
+      browserMouseWheel: vi.fn().mockResolvedValue({ ok: true }),
+      browserStorageLocalSet: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: BROWSER_EXTRA_METHODS })
+
+    await dispatcher.dispatch(
+      makeRequest('browser.cookie.get', {
+        worktree: 'id:wt-1',
+        page: 'page-1',
+        url: 'https://example.com'
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('browser.viewport', {
+        worktree: 'id:wt-1',
+        page: 'page-1',
+        width: 1024,
+        height: 768
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('browser.mouseWheel', {
+        worktree: 'id:wt-1',
+        page: 'page-1',
+        dy: 240
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('browser.storage.local.set', {
+        worktree: 'id:wt-1',
+        page: 'page-1',
+        key: 'orca',
+        value: 'enabled'
+      })
+    )
+
+    expect(runtime.browserCookieGet).toHaveBeenCalledWith({
+      worktree: 'id:wt-1',
+      page: 'page-1',
+      url: 'https://example.com'
+    })
+    expect(runtime.browserSetViewport).toHaveBeenCalledWith({
+      worktree: 'id:wt-1',
+      page: 'page-1',
+      width: 1024,
+      height: 768
+    })
+    expect(runtime.browserMouseWheel).toHaveBeenCalledWith({
+      worktree: 'id:wt-1',
+      page: 'page-1',
+      dy: 240
+    })
+    expect(runtime.browserStorageLocalSet).toHaveBeenCalledWith({
+      worktree: 'id:wt-1',
+      page: 'page-1',
+      key: 'orca',
+      value: 'enabled'
+    })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/file-watch-event-batcher.ts b/src/main/runtime/rpc/methods/file-watch-event-batcher.ts
new file mode 100644
index 00000000000..146ed251b0b
--- /dev/null
+++ b/src/main/runtime/rpc/methods/file-watch-event-batcher.ts
@@ -0,0 +1,65 @@
+import type { FsChangeEvent } from '../../../../shared/types'
+
+const FILE_WATCH_FLUSH_MS = 150
+const FILE_WATCH_MAX_WAIT_MS = 500
+
+export function createFileWatchEventBatcher(
+  worktree: string,
+  emit: (result: unknown) => void
+): {
+  push: (events: FsChangeEvent[]) => void
+  flush: () => void
+  dispose: () => void
+} {
+  let events: FsChangeEvent[] = []
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let firstEventAt = 0
+
+  const clearTimer = (): void => {
+    if (!timer) {
+      return
+    }
+    clearTimeout(timer)
+    timer = null
+  }
+
+  const flush = (): void => {
+    clearTimer()
+    const nextEvents = events.splice(0)
+    firstEventAt = 0
+    if (nextEvents.length === 0) {
+      return
+    }
+    emit({ type: 'changed', worktree, events: nextEvents })
+  }
+
+  return {
+    push(nextEvents: FsChangeEvent[]): void {
+      if (nextEvents.length === 0) {
+        return
+      }
+      events.push(...nextEvents)
+      const now = Date.now()
+      if (firstEventAt === 0) {
+        firstEventAt = now
+      }
+      if (now - firstEventAt >= FILE_WATCH_MAX_WAIT_MS) {
+        flush()
+        return
+      }
+      clearTimer()
+      // Why: remote file-watch events cross the runtime WebSocket before the
+      // renderer refreshes the tree. Match local watcher batching here.
+      timer = setTimeout(flush, FILE_WATCH_FLUSH_MS)
+      if (typeof timer.unref === 'function') {
+        timer.unref()
+      }
+    },
+    flush,
+    dispose(): void {
+      clearTimer()
+      events = []
+      firstEventAt = 0
+    }
+  }
+}
diff --git a/src/main/runtime/rpc/methods/files.test.ts b/src/main/runtime/rpc/methods/files.test.ts
index c05f252668e..708121e967b 100644
--- a/src/main/runtime/rpc/methods/files.test.ts
+++ b/src/main/runtime/rpc/methods/files.test.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: file RPC routing coverage stays together so
+the dispatcher contract for read, write, mutation, and watch methods is easy to audit. */
 import { describe, expect, it, vi } from 'vitest'
 import { RpcDispatcher } from '../dispatcher'
 import type { RpcRequest } from '../core'
@@ -54,6 +56,117 @@ describe('file RPC methods', () => {
     })
   })
 
+  it('streams file watch changes until the subscription is cleaned up', async () => {
+    vi.useFakeTimers()
+    try {
+      type WatchCallback = (
+        events: { kind: 'update'; absolutePath: string; isDirectory?: boolean }[]
+      ) => void
+      const watchFileExplorer = vi.fn(async (_worktree: string, _callback: WatchCallback) => {
+        return vi.fn()
+      })
+      const cleanups = new Map<string, () => void>()
+      const runtime = {
+        getRuntimeId: () => 'test-runtime',
+        watchFileExplorer,
+        registerSubscriptionCleanup: vi.fn().mockImplementation((id, cleanup) => {
+          cleanups.set(id, cleanup)
+        })
+      } as unknown as OrcaRuntimeService
+      const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+      const replies: unknown[] = []
+
+      const dispatch = dispatcher.dispatchStreaming(
+        makeRequest('files.watch', { worktree: 'id:wt-1' }),
+        (response) => replies.push(JSON.parse(response))
+      )
+
+      await vi.waitFor(() => {
+        expect(replies).toHaveLength(1)
+      })
+      expect(runtime.watchFileExplorer).toHaveBeenCalledWith('id:wt-1', expect.any(Function))
+      expect(replies[0]).toMatchObject({
+        ok: true,
+        streaming: true,
+        result: { type: 'ready', subscriptionId: expect.stringContaining('files-watch-') }
+      })
+
+      const emitWatchChange = watchFileExplorer.mock.calls[0]?.[1]
+      expect(emitWatchChange).toBeDefined()
+      emitWatchChange?.([{ kind: 'update', absolutePath: '/repo/readme.md', isDirectory: false }])
+      emitWatchChange?.([
+        { kind: 'update', absolutePath: '/repo/package.json', isDirectory: false }
+      ])
+      expect(replies).toHaveLength(1)
+
+      await vi.runOnlyPendingTimersAsync()
+
+      expect(replies[1]).toMatchObject({
+        ok: true,
+        streaming: true,
+        result: {
+          type: 'changed',
+          worktree: 'id:wt-1',
+          events: [
+            { kind: 'update', absolutePath: '/repo/readme.md', isDirectory: false },
+            { kind: 'update', absolutePath: '/repo/package.json', isDirectory: false }
+          ]
+        }
+      })
+
+      const ready = replies[0] as { result: { subscriptionId: string } }
+      cleanups.get(ready.result.subscriptionId)?.()
+      await dispatch
+
+      expect(replies[2]).toMatchObject({
+        ok: true,
+        streaming: true,
+        result: { type: 'end' }
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('tears down a file watch that resolves after the connection already closed', async () => {
+    type WatchCallback = (
+      events: { kind: 'update'; absolutePath: string; isDirectory?: boolean }[]
+    ) => void
+    const unwatch = vi.fn()
+    let resolveWatch: (value: () => void) => void = () => {}
+    const watchFileExplorer = vi.fn((_worktree: string, _callback: WatchCallback) => {
+      return new Promise<() => void>((resolve) => {
+        resolveWatch = resolve
+      })
+    })
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      watchFileExplorer,
+      registerSubscriptionCleanup: vi.fn()
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+    const abortController = new AbortController()
+    const replies: unknown[] = []
+
+    const dispatch = dispatcher.dispatchStreaming(
+      makeRequest('files.watch', { worktree: 'id:wt-1' }),
+      (response) => replies.push(JSON.parse(response)),
+      { connectionId: 'conn-1', signal: abortController.signal }
+    )
+    await vi.waitFor(() => {
+      expect(watchFileExplorer).toHaveBeenCalled()
+    })
+    abortController.abort()
+    await dispatch
+
+    resolveWatch(unwatch)
+    await vi.waitFor(() => {
+      expect(unwatch).toHaveBeenCalled()
+    })
+    expect(runtime.registerSubscriptionCleanup).not.toHaveBeenCalled()
+    expect(replies).toEqual([])
+  })
+
   it('reads a relative file path for a selected worktree', async () => {
     const runtime = {
       getRuntimeId: () => 'test-runtime',
@@ -77,4 +190,285 @@ describe('file RPC methods', () => {
       result: { content: 'export {}\\n', truncated: false }
     })
   })
+
+  it('reads a preview file for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      readFileExplorerPreview: vi.fn().mockResolvedValue({
+        content: 'base64',
+        isBinary: true,
+        isImage: true,
+        mimeType: 'image/png'
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.readPreview', { worktree: 'id:wt-1', relativePath: 'img/logo.png' })
+    )
+
+    expect(runtime.readFileExplorerPreview).toHaveBeenCalledWith('id:wt-1', 'img/logo.png')
+    expect(response).toMatchObject({
+      ok: true,
+      result: { content: 'base64', isBinary: true, mimeType: 'image/png' }
+    })
+  })
+
+  it('reads a file explorer directory for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      readFileExplorerDir: vi.fn().mockResolvedValue([{ name: 'src', isDirectory: true }])
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.readDir', { worktree: 'id:wt-1', relativePath: '' })
+    )
+
+    expect(runtime.readFileExplorerDir).toHaveBeenCalledWith('id:wt-1', '')
+    expect(response).toMatchObject({
+      ok: true,
+      result: [{ name: 'src', isDirectory: true }]
+    })
+  })
+
+  it('writes file explorer content for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      writeFileExplorerFile: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.write', {
+        worktree: 'id:wt-1',
+        relativePath: 'src/index.ts',
+        content: 'export {}'
+      })
+    )
+
+    expect(runtime.writeFileExplorerFile).toHaveBeenCalledWith(
+      'id:wt-1',
+      'src/index.ts',
+      'export {}'
+    )
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('writes base64 file explorer content for runtime uploads', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      writeFileExplorerFileBase64: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.writeBase64', {
+        worktree: 'id:wt-1',
+        relativePath: 'assets/logo.png',
+        contentBase64: 'cG5n'
+      })
+    )
+
+    expect(runtime.writeFileExplorerFileBase64).toHaveBeenCalledWith(
+      'id:wt-1',
+      'assets/logo.png',
+      'cG5n'
+    )
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('writes base64 file explorer content chunks for large runtime uploads', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      writeFileExplorerFileBase64Chunk: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.writeBase64Chunk', {
+        worktree: 'id:wt-1',
+        relativePath: 'assets/video.mov',
+        contentBase64: 'AAAA',
+        append: true
+      })
+    )
+
+    expect(runtime.writeFileExplorerFileBase64Chunk).toHaveBeenCalledWith(
+      'id:wt-1',
+      'assets/video.mov',
+      'AAAA',
+      true
+    )
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('commits staged runtime uploads without clobbering the final destination', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      commitFileExplorerUpload: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.commitUpload', {
+        worktree: 'id:wt-1',
+        tempRelativePath: 'assets/.logo.png.orca-upload-a',
+        finalRelativePath: 'assets/logo.png'
+      })
+    )
+
+    expect(runtime.commitFileExplorerUpload).toHaveBeenCalledWith(
+      'id:wt-1',
+      'assets/.logo.png.orca-upload-a',
+      'assets/logo.png'
+    )
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('renames file explorer paths for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      renameFileExplorerPath: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.rename', {
+        worktree: 'id:wt-1',
+        oldRelativePath: 'old.ts',
+        newRelativePath: 'new.ts'
+      })
+    )
+
+    expect(runtime.renameFileExplorerPath).toHaveBeenCalledWith('id:wt-1', 'old.ts', 'new.ts')
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('copies file explorer paths for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      copyFileExplorerPath: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.copy', {
+        worktree: 'id:wt-1',
+        sourceRelativePath: 'old.ts',
+        destinationRelativePath: 'old copy.ts'
+      })
+    )
+
+    expect(runtime.copyFileExplorerPath).toHaveBeenCalledWith('id:wt-1', 'old.ts', 'old copy.ts')
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('deletes file explorer paths for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      deleteFileExplorerPath: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.delete', {
+        worktree: 'id:wt-1',
+        relativePath: 'src',
+        recursive: true
+      })
+    )
+
+    expect(runtime.deleteFileExplorerPath).toHaveBeenCalledWith('id:wt-1', 'src', true)
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('searches files for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      searchRuntimeFiles: vi.fn().mockResolvedValue({
+        files: [],
+        totalMatches: 0,
+        truncated: false
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.search', {
+        worktree: 'id:wt-1',
+        query: 'needle',
+        caseSensitive: true,
+        maxResults: 50
+      })
+    )
+
+    expect(runtime.searchRuntimeFiles).toHaveBeenCalledWith('id:wt-1', {
+      query: 'needle',
+      caseSensitive: true,
+      wholeWord: undefined,
+      useRegex: undefined,
+      includePattern: undefined,
+      excludePattern: undefined,
+      maxResults: 50
+    })
+    expect(response).toMatchObject({ ok: true, result: { files: [], totalMatches: 0 } })
+  })
+
+  it('lists all quick-open files for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      listRuntimeFiles: vi.fn().mockResolvedValue(['src/index.ts'])
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.listAll', {
+        worktree: 'id:wt-1',
+        excludePaths: ['/repo/other-worktree']
+      })
+    )
+
+    expect(runtime.listRuntimeFiles).toHaveBeenCalledWith('id:wt-1', {
+      excludePaths: ['/repo/other-worktree']
+    })
+    expect(response).toMatchObject({ ok: true, result: ['src/index.ts'] })
+  })
+
+  it('lists markdown documents for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      listRuntimeMarkdownDocuments: vi.fn().mockResolvedValue([
+        {
+          filePath: '/repo/readme.md',
+          relativePath: 'readme.md',
+          basename: 'readme.md',
+          name: 'readme'
+        }
+      ])
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.listMarkdownDocuments', { worktree: 'id:wt-1' })
+    )
+
+    expect(runtime.listRuntimeMarkdownDocuments).toHaveBeenCalledWith('id:wt-1')
+    expect(response).toMatchObject({ ok: true, result: [{ relativePath: 'readme.md' }] })
+  })
+
+  it('stats a relative path for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      statRuntimeFile: vi.fn().mockResolvedValue({ size: 12, isDirectory: false, mtime: 1 })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: FILE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('files.stat', { worktree: 'id:wt-1', relativePath: 'readme.md' })
+    )
+
+    expect(runtime.statRuntimeFile).toHaveBeenCalledWith('id:wt-1', 'readme.md')
+    expect(response).toMatchObject({ ok: true, result: { isDirectory: false } })
+  })
 })
diff --git a/src/main/runtime/rpc/methods/files.ts b/src/main/runtime/rpc/methods/files.ts
index ceb8c00b13f..c97d211fec5 100644
--- a/src/main/runtime/rpc/methods/files.ts
+++ b/src/main/runtime/rpc/methods/files.ts
@@ -1,5 +1,8 @@
 import { z } from 'zod'
-import { defineMethod, type RpcMethod } from '../core'
+import { defineMethod, defineStreamingMethod, type RpcAnyMethod } from '../core'
+import { createFileWatchEventBatcher } from './file-watch-event-batcher'
+
+let filesWatchSubscriptionSeq = 0
 
 const WorktreeSelector = z.object({
   worktree: z
@@ -15,7 +18,93 @@ const FileOpen = WorktreeSelector.extend({
     .pipe(z.string().min(1, 'Missing relative path'))
 })
 
-export const FILE_METHODS: RpcMethod[] = [
+const FileTreePath = WorktreeSelector.extend({
+  relativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string())
+})
+
+const FileWrite = FileOpen.extend({
+  content: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string())
+})
+
+const FileWriteBase64 = FileOpen.extend({
+  contentBase64: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string())
+})
+
+const FileWriteBase64Chunk = FileWriteBase64.extend({
+  append: z.boolean().optional()
+})
+
+const FileRename = WorktreeSelector.extend({
+  oldRelativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing source path')),
+  newRelativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing destination path'))
+})
+
+const FileCopy = WorktreeSelector.extend({
+  sourceRelativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing source path')),
+  destinationRelativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing destination path'))
+})
+
+const FileCommitUpload = WorktreeSelector.extend({
+  tempRelativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing temporary path')),
+  finalRelativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing final path'))
+})
+
+const FileDelete = FileOpen.extend({
+  recursive: z.boolean().optional()
+})
+
+const FileSearch = WorktreeSelector.extend({
+  query: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing search query')),
+  caseSensitive: z.boolean().optional(),
+  wholeWord: z.boolean().optional(),
+  useRegex: z.boolean().optional(),
+  includePattern: z.string().optional(),
+  excludePattern: z.string().optional(),
+  maxResults: z.number().int().positive().optional()
+})
+
+const FileListAll = WorktreeSelector.extend({
+  excludePaths: z.array(z.string()).optional()
+})
+
+const FileUnwatch = z.object({
+  subscriptionId: z
+    .unknown()
+    .transform((value) => (typeof value === 'string' && value.length > 0 ? value : ''))
+    .pipe(z.string().min(1, 'Missing subscriptionId'))
+})
+
+export const FILE_METHODS: RpcAnyMethod[] = [
   defineMethod({
     name: 'files.list',
     params: WorktreeSelector,
@@ -32,5 +121,198 @@ export const FILE_METHODS: RpcMethod[] = [
     params: FileOpen,
     handler: async (params, { runtime }) =>
       runtime.readMobileFile(params.worktree, params.relativePath)
+  }),
+  defineMethod({
+    name: 'files.readPreview',
+    params: FileOpen,
+    handler: async (params, { runtime }) =>
+      runtime.readFileExplorerPreview(params.worktree, params.relativePath)
+  }),
+  defineMethod({
+    name: 'files.readDir',
+    params: FileTreePath,
+    handler: async (params, { runtime }) =>
+      runtime.readFileExplorerDir(params.worktree, params.relativePath)
+  }),
+  defineMethod({
+    name: 'files.write',
+    params: FileWrite,
+    handler: async (params, { runtime }) =>
+      runtime.writeFileExplorerFile(params.worktree, params.relativePath, params.content)
+  }),
+  defineMethod({
+    name: 'files.writeBase64',
+    params: FileWriteBase64,
+    handler: async (params, { runtime }) =>
+      runtime.writeFileExplorerFileBase64(
+        params.worktree,
+        params.relativePath,
+        params.contentBase64
+      )
+  }),
+  defineMethod({
+    name: 'files.writeBase64Chunk',
+    params: FileWriteBase64Chunk,
+    handler: async (params, { runtime }) =>
+      runtime.writeFileExplorerFileBase64Chunk(
+        params.worktree,
+        params.relativePath,
+        params.contentBase64,
+        params.append === true
+      )
+  }),
+  defineMethod({
+    name: 'files.createFile',
+    params: FileOpen,
+    handler: async (params, { runtime }) =>
+      runtime.createFileExplorerFile(params.worktree, params.relativePath)
+  }),
+  defineMethod({
+    name: 'files.createDir',
+    params: FileOpen,
+    handler: async (params, { runtime }) =>
+      runtime.createFileExplorerDir(params.worktree, params.relativePath)
+  }),
+  defineMethod({
+    name: 'files.createDirNoClobber',
+    params: FileOpen,
+    handler: async (params, { runtime }) =>
+      runtime.createFileExplorerDirNoClobber(params.worktree, params.relativePath)
+  }),
+  defineMethod({
+    name: 'files.commitUpload',
+    params: FileCommitUpload,
+    handler: async (params, { runtime }) =>
+      runtime.commitFileExplorerUpload(
+        params.worktree,
+        params.tempRelativePath,
+        params.finalRelativePath
+      )
+  }),
+  defineMethod({
+    name: 'files.rename',
+    params: FileRename,
+    handler: async (params, { runtime }) =>
+      runtime.renameFileExplorerPath(
+        params.worktree,
+        params.oldRelativePath,
+        params.newRelativePath
+      )
+  }),
+  defineMethod({
+    name: 'files.copy',
+    params: FileCopy,
+    handler: async (params, { runtime }) =>
+      runtime.copyFileExplorerPath(
+        params.worktree,
+        params.sourceRelativePath,
+        params.destinationRelativePath
+      )
+  }),
+  defineMethod({
+    name: 'files.delete',
+    params: FileDelete,
+    handler: async (params, { runtime }) =>
+      runtime.deleteFileExplorerPath(params.worktree, params.relativePath, params.recursive)
+  }),
+  defineMethod({
+    name: 'files.search',
+    params: FileSearch,
+    handler: async (params, { runtime }) =>
+      runtime.searchRuntimeFiles(params.worktree, {
+        query: params.query,
+        caseSensitive: params.caseSensitive,
+        wholeWord: params.wholeWord,
+        useRegex: params.useRegex,
+        includePattern: params.includePattern,
+        excludePattern: params.excludePattern,
+        maxResults: params.maxResults
+      })
+  }),
+  defineMethod({
+    name: 'files.listAll',
+    params: FileListAll,
+    handler: async (params, { runtime }) =>
+      runtime.listRuntimeFiles(params.worktree, { excludePaths: params.excludePaths })
+  }),
+  defineMethod({
+    name: 'files.listMarkdownDocuments',
+    params: WorktreeSelector,
+    handler: async (params, { runtime }) => runtime.listRuntimeMarkdownDocuments(params.worktree)
+  }),
+  defineMethod({
+    name: 'files.stat',
+    params: FileTreePath,
+    handler: async (params, { runtime }) =>
+      runtime.statRuntimeFile(params.worktree, params.relativePath)
+  }),
+  defineStreamingMethod({
+    name: 'files.watch',
+    params: WorktreeSelector,
+    handler: async (params, { runtime, connectionId, signal }, emit) => {
+      const seq = ++filesWatchSubscriptionSeq
+      const subscriptionId = `files-watch-${connectionId ?? 'inproc'}-${seq}`
+      if (signal?.aborted) {
+        return
+      }
+      await new Promise<void>((resolve, reject) => {
+        let settled = false
+        let unwatch: (() => void) | null = null
+        const eventBatcher = createFileWatchEventBatcher(params.worktree, emit)
+        const finish = (): void => {
+          if (settled) {
+            return
+          }
+          settled = true
+          signal?.removeEventListener('abort', handleAbort)
+          resolve()
+        }
+        const cleanup = (): void => {
+          eventBatcher.flush()
+          eventBatcher.dispose()
+          unwatch?.()
+          emit({ type: 'end' })
+          finish()
+        }
+        const handleAbort = (): void => {
+          if (unwatch) {
+            cleanup()
+          } else {
+            finish()
+          }
+        }
+        signal?.addEventListener('abort', handleAbort, { once: true })
+        void runtime
+          .watchFileExplorer(params.worktree, (events) => {
+            eventBatcher.push(events)
+          })
+          .then((nextUnwatch) => {
+            if (signal?.aborted || settled) {
+              // Why: the connection can close while watch setup is still
+              // resolving. Tear down the late watcher immediately instead of
+              // registering cleanup on a connection that was already reaped.
+              nextUnwatch()
+              return
+            }
+            unwatch = nextUnwatch
+            runtime.registerSubscriptionCleanup(subscriptionId, cleanup, connectionId)
+            emit({ type: 'ready', subscriptionId })
+          })
+          .catch((error) => {
+            if (!settled) {
+              signal?.removeEventListener('abort', handleAbort)
+              reject(error)
+            }
+          })
+      })
+    }
+  }),
+  defineMethod({
+    name: 'files.unwatch',
+    params: FileUnwatch,
+    handler: async (params, { runtime }) => {
+      runtime.cleanupSubscription(params.subscriptionId)
+      return { unsubscribed: true }
+    }
   })
 ]
diff --git a/src/main/runtime/rpc/methods/git.test.ts b/src/main/runtime/rpc/methods/git.test.ts
new file mode 100644
index 00000000000..0bd8a810710
--- /dev/null
+++ b/src/main/runtime/rpc/methods/git.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { GIT_METHODS } from './git'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('git RPC methods', () => {
+  it('returns status for a selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRuntimeGitStatus: vi.fn().mockResolvedValue({
+        entries: [],
+        conflictOperation: 'unknown',
+        branch: 'main',
+        head: 'abc'
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GIT_METHODS })
+
+    const response = await dispatcher.dispatch(makeRequest('git.status', { worktree: 'id:wt-1' }))
+
+    expect(runtime.getRuntimeGitStatus).toHaveBeenCalledWith('id:wt-1')
+    expect(response).toMatchObject({
+      ok: true,
+      result: { entries: [], branch: 'main' }
+    })
+  })
+
+  it('returns a worktree file diff', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRuntimeGitDiff: vi.fn().mockResolvedValue({
+        kind: 'text',
+        originalContent: '',
+        modifiedContent: 'hello',
+        originalIsBinary: false,
+        modifiedIsBinary: false
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GIT_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('git.diff', {
+        worktree: 'id:wt-1',
+        filePath: 'src/index.ts',
+        staged: false,
+        compareAgainstHead: true
+      })
+    )
+
+    expect(runtime.getRuntimeGitDiff).toHaveBeenCalledWith('id:wt-1', 'src/index.ts', false, true)
+    expect(response).toMatchObject({
+      ok: true,
+      result: { kind: 'text', modifiedContent: 'hello' }
+    })
+  })
+
+  it('routes common mutations to the runtime', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      stageRuntimeGitPath: vi.fn().mockResolvedValue({ ok: true }),
+      bulkUnstageRuntimeGitPaths: vi.fn().mockResolvedValue({ ok: true }),
+      discardRuntimeGitPath: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GIT_METHODS })
+
+    await dispatcher.dispatch(
+      makeRequest('git.stage', { worktree: 'id:wt-1', filePath: 'src/a.ts' })
+    )
+    await dispatcher.dispatch(
+      makeRequest('git.bulkUnstage', { worktree: 'id:wt-1', filePaths: ['src/a.ts', 'b.ts'] })
+    )
+    await dispatcher.dispatch(
+      makeRequest('git.discard', { worktree: 'id:wt-1', filePath: 'src/a.ts' })
+    )
+
+    expect(runtime.stageRuntimeGitPath).toHaveBeenCalledWith('id:wt-1', 'src/a.ts')
+    expect(runtime.bulkUnstageRuntimeGitPaths).toHaveBeenCalledWith('id:wt-1', ['src/a.ts', 'b.ts'])
+    expect(runtime.discardRuntimeGitPath).toHaveBeenCalledWith('id:wt-1', 'src/a.ts')
+  })
+
+  it('routes remote operations to the runtime', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      commitRuntimeGit: vi.fn().mockResolvedValue({ success: true }),
+      pushRuntimeGit: vi.fn().mockResolvedValue({ ok: true }),
+      getRuntimeGitRemoteFileUrl: vi.fn().mockResolvedValue('https://example.com/file#L3')
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GIT_METHODS })
+
+    await dispatcher.dispatch(
+      makeRequest('git.commit', { worktree: 'id:wt-1', message: 'feat: test' })
+    )
+    await dispatcher.dispatch(
+      makeRequest('git.push', {
+        worktree: 'id:wt-1',
+        publish: true,
+        pushTarget: { remote: 'origin' }
+      })
+    )
+    const response = await dispatcher.dispatch(
+      makeRequest('git.remoteFileUrl', {
+        worktree: 'id:wt-1',
+        relativePath: 'src/a.ts',
+        line: 3
+      })
+    )
+
+    expect(runtime.commitRuntimeGit).toHaveBeenCalledWith('id:wt-1', 'feat: test')
+    expect(runtime.pushRuntimeGit).toHaveBeenCalledWith('id:wt-1', true, { remote: 'origin' })
+    expect(response).toMatchObject({ ok: true, result: 'https://example.com/file#L3' })
+  })
+
+  it('rejects branch diff revisions that are not full object ids', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRuntimeGitBranchDiff: vi.fn()
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GIT_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('git.branchDiff', {
+        worktree: 'id:wt-1',
+        filePath: 'src/a.ts',
+        compare: {
+          headOid: '--output=/tmp/orca-test',
+          mergeBase: 'a'.repeat(40)
+        }
+      })
+    )
+
+    expect(response.ok).toBe(false)
+    expect(runtime.getRuntimeGitBranchDiff).not.toHaveBeenCalled()
+  })
+
+  it('rejects branch compare refs that look like git options', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRuntimeGitBranchCompare: vi.fn()
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GIT_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('git.branchCompare', {
+        worktree: 'id:wt-1',
+        baseRef: '--output=/tmp/orca-test'
+      })
+    )
+
+    expect(response.ok).toBe(false)
+    expect(runtime.getRuntimeGitBranchCompare).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/runtime/rpc/methods/git.ts b/src/main/runtime/rpc/methods/git.ts
new file mode 100644
index 00000000000..3d4e6274046
--- /dev/null
+++ b/src/main/runtime/rpc/methods/git.ts
@@ -0,0 +1,175 @@
+import { z } from 'zod'
+import { defineMethod, type RpcMethod } from '../core'
+
+const WorktreeSelector = z.object({
+  worktree: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing worktree selector'))
+})
+
+const GitFilePath = WorktreeSelector.extend({
+  filePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing file path'))
+})
+
+const GitDiff = GitFilePath.extend({
+  staged: z.boolean(),
+  compareAgainstHead: z.boolean().optional()
+})
+
+const GitBranchCompare = WorktreeSelector.extend({
+  baseRef: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(
+      z
+        .string()
+        .min(1, 'Missing base ref')
+        .refine((value) => !value.startsWith('-'), 'Base ref must not start with -')
+    )
+})
+
+const FullGitObjectId = z
+  .string()
+  .regex(/^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$/, 'Expected a full git object id')
+
+const GitBranchDiff = GitFilePath.extend({
+  compare: z.object({
+    baseRef: z.string().optional(),
+    baseOid: FullGitObjectId.optional(),
+    headOid: FullGitObjectId,
+    mergeBase: FullGitObjectId
+  }),
+  oldPath: z.string().optional()
+})
+
+const GitCommit = WorktreeSelector.extend({
+  message: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing commit message'))
+})
+
+const GitBulkPaths = WorktreeSelector.extend({
+  filePaths: z.array(z.string())
+})
+
+const GitPush = WorktreeSelector.extend({
+  publish: z.boolean().optional(),
+  pushTarget: z.unknown().optional()
+})
+
+const GitRemoteFileUrl = WorktreeSelector.extend({
+  relativePath: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing relative path')),
+  line: z.number().int().min(1)
+})
+
+export const GIT_METHODS: RpcMethod[] = [
+  defineMethod({
+    name: 'git.status',
+    params: WorktreeSelector,
+    handler: async (params, { runtime }) => runtime.getRuntimeGitStatus(params.worktree)
+  }),
+  defineMethod({
+    name: 'git.conflictOperation',
+    params: WorktreeSelector,
+    handler: async (params, { runtime }) => runtime.getRuntimeGitConflictOperation(params.worktree)
+  }),
+  defineMethod({
+    name: 'git.diff',
+    params: GitDiff,
+    handler: async (params, { runtime }) =>
+      runtime.getRuntimeGitDiff(
+        params.worktree,
+        params.filePath,
+        params.staged,
+        params.compareAgainstHead
+      )
+  }),
+  defineMethod({
+    name: 'git.branchCompare',
+    params: GitBranchCompare,
+    handler: async (params, { runtime }) =>
+      runtime.getRuntimeGitBranchCompare(params.worktree, params.baseRef)
+  }),
+  defineMethod({
+    name: 'git.upstreamStatus',
+    params: WorktreeSelector,
+    handler: async (params, { runtime }) => runtime.getRuntimeGitUpstreamStatus(params.worktree)
+  }),
+  defineMethod({
+    name: 'git.fetch',
+    params: WorktreeSelector,
+    handler: async (params, { runtime }) => runtime.fetchRuntimeGit(params.worktree)
+  }),
+  defineMethod({
+    name: 'git.pull',
+    params: WorktreeSelector,
+    handler: async (params, { runtime }) => runtime.pullRuntimeGit(params.worktree)
+  }),
+  defineMethod({
+    name: 'git.push',
+    params: GitPush,
+    handler: async (params, { runtime }) =>
+      runtime.pushRuntimeGit(params.worktree, params.publish, params.pushTarget as never)
+  }),
+  defineMethod({
+    name: 'git.branchDiff',
+    params: GitBranchDiff,
+    handler: async (params, { runtime }) =>
+      runtime.getRuntimeGitBranchDiff(
+        params.worktree,
+        params.compare,
+        params.filePath,
+        params.oldPath
+      )
+  }),
+  defineMethod({
+    name: 'git.commit',
+    params: GitCommit,
+    handler: async (params, { runtime }) =>
+      runtime.commitRuntimeGit(params.worktree, params.message)
+  }),
+  defineMethod({
+    name: 'git.stage',
+    params: GitFilePath,
+    handler: async (params, { runtime }) =>
+      runtime.stageRuntimeGitPath(params.worktree, params.filePath)
+  }),
+  defineMethod({
+    name: 'git.bulkStage',
+    params: GitBulkPaths,
+    handler: async (params, { runtime }) =>
+      runtime.bulkStageRuntimeGitPaths(params.worktree, params.filePaths)
+  }),
+  defineMethod({
+    name: 'git.unstage',
+    params: GitFilePath,
+    handler: async (params, { runtime }) =>
+      runtime.unstageRuntimeGitPath(params.worktree, params.filePath)
+  }),
+  defineMethod({
+    name: 'git.bulkUnstage',
+    params: GitBulkPaths,
+    handler: async (params, { runtime }) =>
+      runtime.bulkUnstageRuntimeGitPaths(params.worktree, params.filePaths)
+  }),
+  defineMethod({
+    name: 'git.discard',
+    params: GitFilePath,
+    handler: async (params, { runtime }) =>
+      runtime.discardRuntimeGitPath(params.worktree, params.filePath)
+  }),
+  defineMethod({
+    name: 'git.remoteFileUrl',
+    params: GitRemoteFileUrl,
+    handler: async (params, { runtime }) =>
+      runtime.getRuntimeGitRemoteFileUrl(params.worktree, params.relativePath, params.line)
+  })
+]
diff --git a/src/main/runtime/rpc/methods/github.test.ts b/src/main/runtime/rpc/methods/github.test.ts
new file mode 100644
index 00000000000..bcd32235050
--- /dev/null
+++ b/src/main/runtime/rpc/methods/github.test.ts
@@ -0,0 +1,519 @@
+/* eslint-disable max-lines -- Why: runtime GitHub RPC methods share one dispatcher suite so repo-scoped and Project-scoped contract coverage cannot drift. */
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { GITHUB_METHODS } from './github'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('github RPC methods', () => {
+  it('resolves the repo slug on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRepoSlug: vi.fn().mockResolvedValue({ owner: 'acme', repo: 'orca' })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(makeRequest('github.repoSlug', { repo: 'repo-1' }))
+
+    expect(runtime.getRepoSlug).toHaveBeenCalledWith('repo-1')
+    expect(response).toMatchObject({
+      ok: true,
+      result: { owner: 'acme', repo: 'orca' }
+    })
+  })
+
+  it('fetches GitHub rate limits on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getGitHubRateLimit: vi.fn().mockResolvedValue({ ok: true, snapshot: { core: {} } })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(makeRequest('github.rateLimit', { force: true }))
+
+    expect(runtime.getGitHubRateLimit).toHaveBeenCalledWith({ force: true })
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('lists work items on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      listRepoWorkItems: vi.fn().mockResolvedValue({ items: [] })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.listWorkItems', { repo: 'repo-1', limit: 10, query: 'is:pr' })
+    )
+
+    expect(runtime.listRepoWorkItems).toHaveBeenCalledWith('repo-1', 10, 'is:pr', undefined)
+    expect(response).toMatchObject({ ok: true, result: { items: [] } })
+  })
+
+  it('looks up a single work item on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRepoWorkItem: vi.fn().mockResolvedValue({ number: 12, type: 'pr' })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.workItem', { repo: 'repo-1', number: 12, type: 'pr' })
+    )
+
+    expect(runtime.getRepoWorkItem).toHaveBeenCalledWith('repo-1', 12, 'pr')
+    expect(response).toMatchObject({ ok: true, result: { number: 12, type: 'pr' } })
+  })
+
+  it('looks up a single work item by explicit owner/repo on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRepoWorkItemByOwnerRepo: vi.fn().mockResolvedValue({ number: 12, type: 'pr' })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.workItemByOwnerRepo', {
+        repo: 'repo-1',
+        owner: 'acme',
+        ownerRepo: 'orca',
+        number: 12,
+        type: 'pr'
+      })
+    )
+
+    expect(runtime.getRepoWorkItemByOwnerRepo).toHaveBeenCalledWith(
+      'repo-1',
+      { owner: 'acme', repo: 'orca' },
+      12,
+      'pr'
+    )
+    expect(response).toMatchObject({ ok: true, result: { number: 12, type: 'pr' } })
+  })
+
+  it('fetches work item details on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRepoWorkItemDetails: vi.fn().mockResolvedValue({ body: 'Details' })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.workItemDetails', { repo: 'repo-1', number: 12, type: 'issue' })
+    )
+
+    expect(runtime.getRepoWorkItemDetails).toHaveBeenCalledWith('repo-1', 12, 'issue')
+    expect(response).toMatchObject({ ok: true, result: { body: 'Details' } })
+  })
+
+  it('counts work items on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      countRepoWorkItems: vi.fn().mockResolvedValue(3)
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.countWorkItems', { repo: 'repo-1', query: 'is:open' })
+    )
+
+    expect(runtime.countRepoWorkItems).toHaveBeenCalledWith('repo-1', 'is:open')
+    expect(response).toMatchObject({ ok: true, result: 3 })
+  })
+
+  it('lists repo issue metadata on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      listRepoLabels: vi.fn().mockResolvedValue(['bug']),
+      listRepoAssignableUsers: vi.fn().mockResolvedValue([{ login: 'octo' }])
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const labels = await dispatcher.dispatch(makeRequest('github.listLabels', { repo: 'repo-1' }))
+    const users = await dispatcher.dispatch(
+      makeRequest('github.listAssignableUsers', { repo: 'repo-1' })
+    )
+
+    expect(runtime.listRepoLabels).toHaveBeenCalledWith('repo-1')
+    expect(runtime.listRepoAssignableUsers).toHaveBeenCalledWith('repo-1')
+    expect(labels).toMatchObject({ ok: true, result: ['bug'] })
+    expect(users).toMatchObject({ ok: true, result: [{ login: 'octo' }] })
+  })
+
+  it('fetches PR checks on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRepoPRChecks: vi.fn().mockResolvedValue([])
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.prChecks', {
+        repo: 'repo-1',
+        prNumber: 7,
+        headSha: 'abc123',
+        noCache: true
+      })
+    )
+
+    expect(runtime.getRepoPRChecks).toHaveBeenCalledWith('repo-1', 7, 'abc123', {
+      noCache: true
+    })
+    expect(response).toMatchObject({ ok: true, result: [] })
+  })
+
+  it('fetches PR file contents on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getRepoPRFileContents: vi.fn().mockResolvedValue({
+        original: '',
+        modified: 'new',
+        originalIsBinary: false,
+        modifiedIsBinary: false
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.prFileContents', {
+        repo: 'repo-1',
+        prNumber: 7,
+        path: 'src/app.ts',
+        status: 'modified',
+        headSha: 'head',
+        baseSha: 'base'
+      })
+    )
+
+    expect(runtime.getRepoPRFileContents).toHaveBeenCalledWith('repo-1', {
+      prNumber: 7,
+      path: 'src/app.ts',
+      oldPath: undefined,
+      status: 'modified',
+      headSha: 'head',
+      baseSha: 'base'
+    })
+    expect(response).toMatchObject({ ok: true, result: { modified: 'new' } })
+  })
+
+  it('resolves review threads on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      resolveRepoReviewThread: vi.fn().mockResolvedValue(true)
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.resolveReviewThread', {
+        repo: 'repo-1',
+        threadId: 'PRRT_1',
+        resolve: true
+      })
+    )
+
+    expect(runtime.resolveRepoReviewThread).toHaveBeenCalledWith('repo-1', 'PRRT_1', true)
+    expect(response).toMatchObject({ ok: true, result: true })
+  })
+
+  it('updates PR titles on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      updateRepoPRTitle: vi.fn().mockResolvedValue(true)
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.updatePRTitle', {
+        repo: 'repo-1',
+        prNumber: 7,
+        title: 'New title'
+      })
+    )
+
+    expect(runtime.updateRepoPRTitle).toHaveBeenCalledWith('repo-1', 7, 'New title')
+    expect(response).toMatchObject({ ok: true, result: true })
+  })
+
+  it('merges PRs on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      mergeRepoPR: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.mergePR', {
+        repo: 'repo-1',
+        prNumber: 7,
+        method: 'squash'
+      })
+    )
+
+    expect(runtime.mergeRepoPR).toHaveBeenCalledWith('repo-1', 7, 'squash')
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('creates issues on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      createRepoIssue: vi.fn().mockResolvedValue({ ok: true, number: 3, url: 'https://gh/3' })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.createIssue', {
+        repo: 'repo-1',
+        title: 'Bug',
+        body: 'Body'
+      })
+    )
+
+    expect(runtime.createRepoIssue).toHaveBeenCalledWith('repo-1', 'Bug', 'Body')
+    expect(response).toMatchObject({ ok: true, result: { ok: true, number: 3 } })
+  })
+
+  it('updates issues on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      updateRepoIssue: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.updateIssue', {
+        repo: 'repo-1',
+        number: 3,
+        updates: { state: 'closed', addLabels: ['bug'] }
+      })
+    )
+
+    expect(runtime.updateRepoIssue).toHaveBeenCalledWith('repo-1', 3, {
+      state: 'closed',
+      addLabels: ['bug']
+    })
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('adds issue comments on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      addRepoIssueComment: vi.fn().mockResolvedValue({ ok: true, comment: { id: 1 } })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.addIssueComment', {
+        repo: 'repo-1',
+        number: 3,
+        body: 'Looks good',
+        type: 'pr'
+      })
+    )
+
+    expect(runtime.addRepoIssueComment).toHaveBeenCalledWith('repo-1', 3, 'Looks good')
+    expect(response).toMatchObject({ ok: true, result: { ok: true, comment: { id: 1 } } })
+  })
+
+  it('adds PR review comments on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      addRepoPRReviewComment: vi.fn().mockResolvedValue({ ok: true, comment: { id: 2 } })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.addPRReviewComment', {
+        repo: 'repo-1',
+        prNumber: 7,
+        commitId: 'head',
+        path: 'src/app.ts',
+        line: 12,
+        startLine: 10,
+        body: 'Please tweak'
+      })
+    )
+
+    expect(runtime.addRepoPRReviewComment).toHaveBeenCalledWith('repo-1', {
+      prNumber: 7,
+      commitId: 'head',
+      path: 'src/app.ts',
+      line: 12,
+      startLine: 10,
+      body: 'Please tweak'
+    })
+    expect(response).toMatchObject({ ok: true, result: { ok: true, comment: { id: 2 } } })
+  })
+
+  it('adds PR review comment replies on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      addRepoPRReviewCommentReply: vi.fn().mockResolvedValue({ ok: true, comment: { id: 4 } })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.addPRReviewCommentReply', {
+        repo: 'repo-1',
+        prNumber: 7,
+        commentId: 2,
+        body: 'Done',
+        threadId: 'PRRT_1',
+        path: 'src/app.ts',
+        line: 12
+      })
+    )
+
+    expect(runtime.addRepoPRReviewCommentReply).toHaveBeenCalledWith('repo-1', {
+      prNumber: 7,
+      commentId: 2,
+      body: 'Done',
+      threadId: 'PRRT_1',
+      path: 'src/app.ts',
+      line: 12
+    })
+    expect(response).toMatchObject({ ok: true, result: { ok: true, comment: { id: 4 } } })
+  })
+
+  it('fetches GitHub project views on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      listGitHubProjectViews: vi.fn().mockResolvedValue({ ok: true, views: [] })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.project.listViews', {
+        owner: 'acme',
+        ownerType: 'organization',
+        projectNumber: 1
+      })
+    )
+
+    expect(runtime.listGitHubProjectViews).toHaveBeenCalledWith({
+      owner: 'acme',
+      ownerType: 'organization',
+      projectNumber: 1
+    })
+    expect(response).toMatchObject({ ok: true, result: { ok: true, views: [] } })
+  })
+
+  it('lists slug-addressed issue metadata on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      listGitHubLabelsBySlug: vi.fn().mockResolvedValue({ ok: true, labels: ['bug'] }),
+      listGitHubAssignableUsersBySlug: vi
+        .fn()
+        .mockResolvedValue({ ok: true, users: [{ login: 'octo' }] }),
+      listGitHubIssueTypesBySlug: vi.fn().mockResolvedValue({ ok: true, types: [{ id: 'it-1' }] })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const labels = await dispatcher.dispatch(
+      makeRequest('github.project.listLabelsBySlug', { owner: 'acme', repo: 'orca' })
+    )
+    const users = await dispatcher.dispatch(
+      makeRequest('github.project.listAssignableUsersBySlug', {
+        owner: 'acme',
+        repo: 'orca',
+        seedLogins: ['octo']
+      })
+    )
+    const issueTypes = await dispatcher.dispatch(
+      makeRequest('github.project.listIssueTypesBySlug', { owner: 'acme', repo: 'orca' })
+    )
+
+    expect(runtime.listGitHubLabelsBySlug).toHaveBeenCalledWith({ owner: 'acme', repo: 'orca' })
+    expect(runtime.listGitHubAssignableUsersBySlug).toHaveBeenCalledWith({
+      owner: 'acme',
+      repo: 'orca',
+      seedLogins: ['octo']
+    })
+    expect(runtime.listGitHubIssueTypesBySlug).toHaveBeenCalledWith({ owner: 'acme', repo: 'orca' })
+    expect(labels).toMatchObject({ ok: true, result: { ok: true, labels: ['bug'] } })
+    expect(users).toMatchObject({ ok: true, result: { ok: true, users: [{ login: 'octo' }] } })
+    expect(issueTypes).toMatchObject({ ok: true, result: { ok: true, types: [{ id: 'it-1' }] } })
+  })
+
+  it('fetches GitHub project tables on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getGitHubProjectViewTable: vi.fn().mockResolvedValue({ ok: true, data: { rows: [] } })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.project.viewTable', {
+        owner: 'acme',
+        ownerType: 'organization',
+        projectNumber: 1,
+        viewId: 'view-1',
+        queryOverride: 'is:open'
+      })
+    )
+
+    expect(runtime.getGitHubProjectViewTable).toHaveBeenCalledWith({
+      owner: 'acme',
+      ownerType: 'organization',
+      projectNumber: 1,
+      viewId: 'view-1',
+      viewNumber: undefined,
+      viewName: undefined,
+      queryOverride: 'is:open'
+    })
+    expect(response).toMatchObject({ ok: true, result: { ok: true, data: { rows: [] } } })
+  })
+
+  it('updates GitHub project item fields on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      updateGitHubProjectItemField: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.project.updateItemField', {
+        projectId: 'project-1',
+        itemId: 'item-1',
+        fieldId: 'field-1',
+        value: { kind: 'text', text: 'Now' }
+      })
+    )
+
+    expect(runtime.updateGitHubProjectItemField).toHaveBeenCalledWith({
+      projectId: 'project-1',
+      itemId: 'item-1',
+      fieldId: 'field-1',
+      value: { kind: 'text', text: 'Now' }
+    })
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+
+  it('updates GitHub project issue types on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      updateGitHubIssueTypeBySlug: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.project.updateIssueTypeBySlug', {
+        owner: 'acme',
+        repo: 'orca',
+        number: 9,
+        issueTypeId: null
+      })
+    )
+
+    expect(runtime.updateGitHubIssueTypeBySlug).toHaveBeenCalledWith({
+      owner: 'acme',
+      repo: 'orca',
+      number: 9,
+      issueTypeId: null
+    })
+    expect(response).toMatchObject({ ok: true, result: { ok: true } })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/github.ts b/src/main/runtime/rpc/methods/github.ts
new file mode 100644
index 00000000000..72b32e6cdd8
--- /dev/null
+++ b/src/main/runtime/rpc/methods/github.ts
@@ -0,0 +1,442 @@
+/* eslint-disable max-lines -- Why: GitHub runtime RPC keeps related repo, project, and mutation schemas beside their handlers so the method contract stays reviewable in one place. */
+import { z } from 'zod'
+import { defineMethod, type RpcMethod } from '../core'
+import { OptionalFiniteNumber, OptionalString, requiredString } from '../schemas'
+
+const RepoSelector = z.object({
+  repo: requiredString('Missing repo selector')
+})
+
+const WorkItemsList = RepoSelector.extend({
+  limit: OptionalFiniteNumber,
+  query: OptionalString,
+  before: OptionalString
+})
+
+const WorkItem = RepoSelector.extend({
+  number: z.number().int().positive(),
+  type: z.enum(['issue', 'pr']).optional()
+})
+
+const WorkItemByOwnerRepo = RepoSelector.extend({
+  owner: requiredString('Missing owner'),
+  ownerRepo: requiredString('Missing repo'),
+  number: z.number().int().positive(),
+  type: z.enum(['issue', 'pr'])
+})
+
+const WorkItemDetails = WorkItem
+
+const WorkItemsCount = RepoSelector.extend({
+  query: OptionalString
+})
+
+const RateLimit = z.object({
+  force: z.boolean().optional()
+})
+
+const SlugRepo = z.object({
+  owner: requiredString('Missing owner'),
+  repo: requiredString('Missing repo')
+})
+
+const SlugAssignableUsers = SlugRepo.extend({
+  seedLogins: z.array(z.string()).optional()
+})
+
+const PrForBranch = RepoSelector.extend({
+  branch: requiredString('Missing branch'),
+  linkedPRNumber: z.number().int().positive().nullable().optional()
+})
+
+const Issue = RepoSelector.extend({
+  number: z.number().int().positive()
+})
+
+const PullRequest = RepoSelector.extend({
+  prNumber: z.number().int().positive(),
+  noCache: z.boolean().optional()
+})
+
+const PullRequestChecks = PullRequest.extend({
+  headSha: OptionalString
+})
+
+const PullRequestFileContents = RepoSelector.extend({
+  prNumber: z.number().int().positive(),
+  path: requiredString('Missing file path'),
+  oldPath: OptionalString,
+  status: z.enum(['added', 'removed', 'modified', 'renamed', 'copied', 'changed', 'unchanged']),
+  headSha: requiredString('Missing head SHA'),
+  baseSha: requiredString('Missing base SHA')
+})
+
+const ReviewThread = RepoSelector.extend({
+  threadId: requiredString('Missing thread ID'),
+  resolve: z.boolean()
+})
+
+const UpdatePrTitle = RepoSelector.extend({
+  prNumber: z.number().int().positive(),
+  title: requiredString('Missing title')
+})
+
+const MergePr = RepoSelector.extend({
+  prNumber: z.number().int().positive(),
+  method: z.enum(['merge', 'squash', 'rebase']).optional()
+})
+
+const CreateIssue = RepoSelector.extend({
+  title: requiredString('Missing title'),
+  body: z.string()
+})
+
+const IssueUpdate = z.object({
+  state: z.enum(['open', 'closed']).optional(),
+  title: OptionalString,
+  body: OptionalString,
+  addLabels: z.array(z.string()).optional(),
+  removeLabels: z.array(z.string()).optional(),
+  addAssignees: z.array(z.string()).optional(),
+  removeAssignees: z.array(z.string()).optional()
+})
+
+const UpdateIssue = RepoSelector.extend({
+  number: z.number().int().positive(),
+  updates: IssueUpdate
+})
+
+const IssueComment = RepoSelector.extend({
+  number: z.number().int().positive(),
+  body: requiredString('Comment body required'),
+  type: z.enum(['issue', 'pr']).optional()
+})
+
+const PRReviewComment = RepoSelector.extend({
+  prNumber: z.number().int().positive(),
+  commitId: requiredString('Missing PR head SHA'),
+  path: requiredString('File path required'),
+  line: z.number().int().positive(),
+  startLine: z.number().int().positive().optional(),
+  body: requiredString('Comment body required')
+})
+
+const PRReviewCommentReply = RepoSelector.extend({
+  prNumber: z.number().int().positive(),
+  commentId: z.number().int().positive(),
+  body: requiredString('Comment body required'),
+  threadId: OptionalString,
+  path: OptionalString,
+  line: z.number().int().positive().optional()
+})
+
+const ProjectOwnerType = z.enum(['organization', 'user'])
+
+const ProjectViewTable = z.object({
+  owner: requiredString('Missing owner'),
+  ownerType: ProjectOwnerType,
+  projectNumber: z.number().int().positive(),
+  viewId: OptionalString,
+  viewNumber: z.number().int().positive().optional(),
+  viewName: OptionalString,
+  queryOverride: OptionalString
+})
+
+const ProjectRef = z.object({
+  input: requiredString('Missing project reference')
+})
+
+const ProjectViews = z.object({
+  owner: requiredString('Missing owner'),
+  ownerType: ProjectOwnerType,
+  projectNumber: z.number().int().positive()
+})
+
+const ProjectItemField = z.object({
+  projectId: requiredString('Missing project ID'),
+  itemId: requiredString('Missing item ID'),
+  fieldId: requiredString('Missing field ID'),
+  value: z.any()
+})
+
+const ClearProjectItemField = z.object({
+  projectId: requiredString('Missing project ID'),
+  itemId: requiredString('Missing item ID'),
+  fieldId: requiredString('Missing field ID')
+})
+
+const SlugIssueUpdate = z.object({
+  owner: requiredString('Missing owner'),
+  repo: requiredString('Missing repo'),
+  number: z.number().int().positive(),
+  updates: IssueUpdate
+})
+
+const SlugPullRequestUpdate = z.object({
+  owner: requiredString('Missing owner'),
+  repo: requiredString('Missing repo'),
+  number: z.number().int().positive(),
+  updates: z.object({
+    title: OptionalString,
+    body: OptionalString
+  })
+})
+
+const SlugIssueTypeUpdate = z.object({
+  owner: requiredString('Missing owner'),
+  repo: requiredString('Missing repo'),
+  number: z.number().int().positive(),
+  issueTypeId: z.string().nullable()
+})
+
+const SlugIssueComment = z.object({
+  owner: requiredString('Missing owner'),
+  repo: requiredString('Missing repo'),
+  number: z.number().int().positive(),
+  body: requiredString('Comment body required')
+})
+
+const SlugIssueCommentEdit = z.object({
+  owner: requiredString('Missing owner'),
+  repo: requiredString('Missing repo'),
+  commentId: z.number().int().positive(),
+  body: requiredString('Comment body required')
+})
+
+const SlugIssueCommentDelete = z.object({
+  owner: requiredString('Missing owner'),
+  repo: requiredString('Missing repo'),
+  commentId: z.number().int().positive()
+})
+
+export const GITHUB_METHODS: RpcMethod[] = [
+  defineMethod({
+    name: 'github.repoSlug',
+    params: RepoSelector,
+    handler: async (params, { runtime }) => runtime.getRepoSlug(params.repo)
+  }),
+  defineMethod({
+    name: 'github.rateLimit',
+    params: RateLimit,
+    handler: async (params, { runtime }) => runtime.getGitHubRateLimit(params)
+  }),
+  defineMethod({
+    name: 'github.listWorkItems',
+    params: WorkItemsList,
+    handler: async (params, { runtime }) =>
+      runtime.listRepoWorkItems(params.repo, params.limit, params.query, params.before)
+  }),
+  defineMethod({
+    name: 'github.countWorkItems',
+    params: WorkItemsCount,
+    handler: async (params, { runtime }) => runtime.countRepoWorkItems(params.repo, params.query)
+  }),
+  defineMethod({
+    name: 'github.listLabels',
+    params: RepoSelector,
+    handler: async (params, { runtime }) => runtime.listRepoLabels(params.repo)
+  }),
+  defineMethod({
+    name: 'github.listAssignableUsers',
+    params: RepoSelector,
+    handler: async (params, { runtime }) => runtime.listRepoAssignableUsers(params.repo)
+  }),
+  defineMethod({
+    name: 'github.workItem',
+    params: WorkItem,
+    handler: async (params, { runtime }) =>
+      runtime.getRepoWorkItem(params.repo, params.number, params.type)
+  }),
+  defineMethod({
+    name: 'github.workItemByOwnerRepo',
+    params: WorkItemByOwnerRepo,
+    handler: async (params, { runtime }) =>
+      runtime.getRepoWorkItemByOwnerRepo(
+        params.repo,
+        { owner: params.owner, repo: params.ownerRepo },
+        params.number,
+        params.type
+      )
+  }),
+  defineMethod({
+    name: 'github.workItemDetails',
+    params: WorkItemDetails,
+    handler: async (params, { runtime }) =>
+      runtime.getRepoWorkItemDetails(params.repo, params.number, params.type)
+  }),
+  defineMethod({
+    name: 'github.prForBranch',
+    params: PrForBranch,
+    handler: async (params, { runtime }) =>
+      runtime.getRepoPRForBranch(params.repo, params.branch, params.linkedPRNumber)
+  }),
+  defineMethod({
+    name: 'github.issue',
+    params: Issue,
+    handler: async (params, { runtime }) => runtime.getRepoIssue(params.repo, params.number)
+  }),
+  defineMethod({
+    name: 'github.prChecks',
+    params: PullRequestChecks,
+    handler: async (params, { runtime }) =>
+      runtime.getRepoPRChecks(params.repo, params.prNumber, params.headSha, {
+        noCache: params.noCache
+      })
+  }),
+  defineMethod({
+    name: 'github.prComments',
+    params: PullRequest,
+    handler: async (params, { runtime }) =>
+      runtime.getRepoPRComments(params.repo, params.prNumber, { noCache: params.noCache })
+  }),
+  defineMethod({
+    name: 'github.prFileContents',
+    params: PullRequestFileContents,
+    handler: async (params, { runtime }) =>
+      runtime.getRepoPRFileContents(params.repo, {
+        prNumber: params.prNumber,
+        path: params.path,
+        oldPath: params.oldPath,
+        status: params.status,
+        headSha: params.headSha,
+        baseSha: params.baseSha
+      })
+  }),
+  defineMethod({
+    name: 'github.resolveReviewThread',
+    params: ReviewThread,
+    handler: async (params, { runtime }) =>
+      runtime.resolveRepoReviewThread(params.repo, params.threadId, params.resolve)
+  }),
+  defineMethod({
+    name: 'github.updatePRTitle',
+    params: UpdatePrTitle,
+    handler: async (params, { runtime }) =>
+      runtime.updateRepoPRTitle(params.repo, params.prNumber, params.title)
+  }),
+  defineMethod({
+    name: 'github.mergePR',
+    params: MergePr,
+    handler: async (params, { runtime }) =>
+      runtime.mergeRepoPR(params.repo, params.prNumber, params.method)
+  }),
+  defineMethod({
+    name: 'github.createIssue',
+    params: CreateIssue,
+    handler: async (params, { runtime }) =>
+      runtime.createRepoIssue(params.repo, params.title, params.body)
+  }),
+  defineMethod({
+    name: 'github.updateIssue',
+    params: UpdateIssue,
+    handler: async (params, { runtime }) =>
+      runtime.updateRepoIssue(params.repo, params.number, params.updates)
+  }),
+  defineMethod({
+    name: 'github.addIssueComment',
+    params: IssueComment,
+    handler: async (params, { runtime }) =>
+      runtime.addRepoIssueComment(params.repo, params.number, params.body)
+  }),
+  defineMethod({
+    name: 'github.addPRReviewComment',
+    params: PRReviewComment,
+    handler: async (params, { runtime }) =>
+      runtime.addRepoPRReviewComment(params.repo, {
+        prNumber: params.prNumber,
+        commitId: params.commitId,
+        path: params.path,
+        line: params.line,
+        startLine: params.startLine,
+        body: params.body
+      })
+  }),
+  defineMethod({
+    name: 'github.addPRReviewCommentReply',
+    params: PRReviewCommentReply,
+    handler: async (params, { runtime }) =>
+      runtime.addRepoPRReviewCommentReply(params.repo, {
+        prNumber: params.prNumber,
+        commentId: params.commentId,
+        body: params.body,
+        threadId: params.threadId,
+        path: params.path,
+        line: params.line
+      })
+  }),
+  defineMethod({
+    name: 'github.project.listAccessible',
+    params: z.object({}),
+    handler: async (_params, { runtime }) => runtime.listGitHubProjects()
+  }),
+  defineMethod({
+    name: 'github.project.listLabelsBySlug',
+    params: SlugRepo,
+    handler: async (params, { runtime }) => runtime.listGitHubLabelsBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.listAssignableUsersBySlug',
+    params: SlugAssignableUsers,
+    handler: async (params, { runtime }) => runtime.listGitHubAssignableUsersBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.listIssueTypesBySlug',
+    params: SlugRepo,
+    handler: async (params, { runtime }) => runtime.listGitHubIssueTypesBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.resolveRef',
+    params: ProjectRef,
+    handler: async (params, { runtime }) => runtime.resolveGitHubProjectRef(params)
+  }),
+  defineMethod({
+    name: 'github.project.listViews',
+    params: ProjectViews,
+    handler: async (params, { runtime }) => runtime.listGitHubProjectViews(params)
+  }),
+  defineMethod({
+    name: 'github.project.viewTable',
+    params: ProjectViewTable,
+    handler: async (params, { runtime }) => runtime.getGitHubProjectViewTable(params)
+  }),
+  defineMethod({
+    name: 'github.project.updateItemField',
+    params: ProjectItemField,
+    handler: async (params, { runtime }) => runtime.updateGitHubProjectItemField(params)
+  }),
+  defineMethod({
+    name: 'github.project.clearItemField',
+    params: ClearProjectItemField,
+    handler: async (params, { runtime }) => runtime.clearGitHubProjectItemField(params)
+  }),
+  defineMethod({
+    name: 'github.project.updateIssueBySlug',
+    params: SlugIssueUpdate,
+    handler: async (params, { runtime }) => runtime.updateGitHubIssueBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.updatePullRequestBySlug',
+    params: SlugPullRequestUpdate,
+    handler: async (params, { runtime }) => runtime.updateGitHubPullRequestBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.updateIssueTypeBySlug',
+    params: SlugIssueTypeUpdate,
+    handler: async (params, { runtime }) => runtime.updateGitHubIssueTypeBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.addIssueCommentBySlug',
+    params: SlugIssueComment,
+    handler: async (params, { runtime }) => runtime.addGitHubIssueCommentBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.updateIssueCommentBySlug',
+    params: SlugIssueCommentEdit,
+    handler: async (params, { runtime }) => runtime.updateGitHubIssueCommentBySlug(params)
+  }),
+  defineMethod({
+    name: 'github.project.deleteIssueCommentBySlug',
+    params: SlugIssueCommentDelete,
+    handler: async (params, { runtime }) => runtime.deleteGitHubIssueCommentBySlug(params)
+  })
+]
diff --git a/src/main/runtime/rpc/methods/hosted-review.test.ts b/src/main/runtime/rpc/methods/hosted-review.test.ts
new file mode 100644
index 00000000000..df3ecc0f544
--- /dev/null
+++ b/src/main/runtime/rpc/methods/hosted-review.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { HOSTED_REVIEW_METHODS } from './hosted-review'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('hosted review RPC methods', () => {
+  it('fetches branch review status on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getHostedReviewForBranch: vi.fn().mockResolvedValue({
+        provider: 'github',
+        number: 12,
+        title: 'Feature',
+        state: 'open',
+        url: 'https://github.com/acme/orca/pull/12',
+        status: 'success',
+        updatedAt: '2026-05-10T00:00:00.000Z',
+        mergeable: 'MERGEABLE'
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: HOSTED_REVIEW_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('hostedReview.forBranch', {
+        repo: 'C:\\repo',
+        branch: 'feature/windows',
+        linkedGitHubPR: 12
+      })
+    )
+
+    expect(runtime.getHostedReviewForBranch).toHaveBeenCalledWith({
+      repoSelector: 'C:\\repo',
+      branch: 'feature/windows',
+      linkedGitHubPR: 12,
+      linkedGitLabMR: null,
+      linkedBitbucketPR: null
+    })
+    expect(response).toMatchObject({
+      ok: true,
+      result: { provider: 'github', number: 12 }
+    })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/hosted-review.ts b/src/main/runtime/rpc/methods/hosted-review.ts
new file mode 100644
index 00000000000..952f00f6be4
--- /dev/null
+++ b/src/main/runtime/rpc/methods/hosted-review.ts
@@ -0,0 +1,26 @@
+import { z } from 'zod'
+import { defineMethod, type RpcMethod } from '../core'
+import { requiredString } from '../schemas'
+
+const HostedReviewForBranch = z.object({
+  repo: requiredString('Missing repo selector'),
+  branch: requiredString('Missing branch'),
+  linkedGitHubPR: z.number().int().positive().nullable().optional(),
+  linkedGitLabMR: z.number().int().positive().nullable().optional(),
+  linkedBitbucketPR: z.number().int().positive().nullable().optional()
+})
+
+export const HOSTED_REVIEW_METHODS: RpcMethod[] = [
+  defineMethod({
+    name: 'hostedReview.forBranch',
+    params: HostedReviewForBranch,
+    handler: async (params, { runtime }) =>
+      runtime.getHostedReviewForBranch({
+        repoSelector: params.repo,
+        branch: params.branch,
+        linkedGitHubPR: params.linkedGitHubPR ?? null,
+        linkedGitLabMR: params.linkedGitLabMR ?? null,
+        linkedBitbucketPR: params.linkedBitbucketPR ?? null
+      })
+  })
+]
diff --git a/src/main/runtime/rpc/methods/index.ts b/src/main/runtime/rpc/methods/index.ts
index 69a4caccdf2..9cbc55d3435 100644
--- a/src/main/runtime/rpc/methods/index.ts
+++ b/src/main/runtime/rpc/methods/index.ts
@@ -12,6 +12,10 @@ import { ACCOUNT_METHODS } from './accounts'
 import { COMPUTER_METHODS } from './computer'
 import { SESSION_TAB_METHODS } from './session-tabs'
 import { FILE_METHODS } from './files'
+import { GIT_METHODS } from './git'
+import { GITHUB_METHODS } from './github'
+import { HOSTED_REVIEW_METHODS } from './hosted-review'
+import { LINEAR_METHODS } from './linear'
 import { NOTE_METHODS } from './notes'
 import { SPEECH_METHODS } from './speech'
 
@@ -32,6 +36,10 @@ export const ALL_RPC_METHODS: readonly RpcAnyMethod[] = [
   ...COMPUTER_METHODS,
   ...SESSION_TAB_METHODS,
   ...FILE_METHODS,
+  ...GIT_METHODS,
+  ...GITHUB_METHODS,
+  ...HOSTED_REVIEW_METHODS,
+  ...LINEAR_METHODS,
   ...NOTE_METHODS,
   ...SPEECH_METHODS
 ]
diff --git a/src/main/runtime/rpc/methods/linear.test.ts b/src/main/runtime/rpc/methods/linear.test.ts
new file mode 100644
index 00000000000..ec95e5525b2
--- /dev/null
+++ b/src/main/runtime/rpc/methods/linear.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { LINEAR_METHODS } from './linear'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('linear RPC methods', () => {
+  it('routes Linear account methods to the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      linearStatus: vi.fn().mockResolvedValue({ connected: true, viewer: null }),
+      linearTestConnection: vi.fn().mockResolvedValue({ ok: true, viewer: { displayName: 'Ada' } }),
+      linearConnect: vi.fn().mockResolvedValue({ ok: true, viewer: { displayName: 'Ada' } }),
+      linearDisconnect: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: LINEAR_METHODS })
+
+    await dispatcher.dispatch(makeRequest('linear.status'))
+    await dispatcher.dispatch(makeRequest('linear.testConnection'))
+    await dispatcher.dispatch(makeRequest('linear.connect', { apiKey: 'lin_api_key' }))
+    await dispatcher.dispatch(makeRequest('linear.disconnect'))
+
+    expect(runtime.linearStatus).toHaveBeenCalled()
+    expect(runtime.linearTestConnection).toHaveBeenCalled()
+    expect(runtime.linearConnect).toHaveBeenCalledWith('lin_api_key')
+    expect(runtime.linearDisconnect).toHaveBeenCalled()
+  })
+
+  it('routes Linear issue queries and mutations to the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      linearSearchIssues: vi.fn().mockResolvedValue([{ id: 'issue-1' }]),
+      linearListIssues: vi.fn().mockResolvedValue([{ id: 'issue-2' }]),
+      linearGetIssue: vi.fn().mockResolvedValue({ id: 'issue-3' }),
+      linearCreateIssue: vi.fn().mockResolvedValue({ ok: true, id: 'issue-4' }),
+      linearUpdateIssue: vi.fn().mockResolvedValue({ ok: true }),
+      linearAddIssueComment: vi.fn().mockResolvedValue({ ok: true, id: 'comment-1' }),
+      linearIssueComments: vi.fn().mockResolvedValue([{ id: 'comment-2' }])
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: LINEAR_METHODS })
+
+    await dispatcher.dispatch(makeRequest('linear.searchIssues', { query: 'bug', limit: 30 }))
+    await dispatcher.dispatch(makeRequest('linear.listIssues', { filter: 'assigned', limit: 20 }))
+    await dispatcher.dispatch(makeRequest('linear.getIssue', { id: 'issue-3' }))
+    await dispatcher.dispatch(
+      makeRequest('linear.createIssue', {
+        teamId: 'team-1',
+        title: 'Fix bug',
+        description: 'Details'
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('linear.updateIssue', {
+        id: 'issue-3',
+        updates: { stateId: 'state-1', assigneeId: null, priority: 2, labelIds: ['label-1'] }
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('linear.addIssueComment', { issueId: 'issue-3', body: 'Looks good' })
+    )
+    await dispatcher.dispatch(makeRequest('linear.issueComments', { issueId: 'issue-3' }))
+
+    expect(runtime.linearSearchIssues).toHaveBeenCalledWith('bug', 30)
+    expect(runtime.linearListIssues).toHaveBeenCalledWith('assigned', 20)
+    expect(runtime.linearGetIssue).toHaveBeenCalledWith('issue-3')
+    expect(runtime.linearCreateIssue).toHaveBeenCalledWith('team-1', 'Fix bug', 'Details')
+    expect(runtime.linearUpdateIssue).toHaveBeenCalledWith('issue-3', {
+      stateId: 'state-1',
+      assigneeId: null,
+      priority: 2,
+      labelIds: ['label-1']
+    })
+    expect(runtime.linearAddIssueComment).toHaveBeenCalledWith('issue-3', 'Looks good')
+    expect(runtime.linearIssueComments).toHaveBeenCalledWith('issue-3')
+  })
+
+  it('routes Linear metadata requests to the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      linearListTeams: vi.fn().mockResolvedValue([{ id: 'team-1' }]),
+      linearTeamStates: vi.fn().mockResolvedValue([{ id: 'state-1' }]),
+      linearTeamLabels: vi.fn().mockResolvedValue([{ id: 'label-1' }]),
+      linearTeamMembers: vi.fn().mockResolvedValue([{ id: 'member-1' }])
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: LINEAR_METHODS })
+
+    await dispatcher.dispatch(makeRequest('linear.listTeams'))
+    await dispatcher.dispatch(makeRequest('linear.teamStates', { teamId: 'team-1' }))
+    await dispatcher.dispatch(makeRequest('linear.teamLabels', { teamId: 'team-1' }))
+    await dispatcher.dispatch(makeRequest('linear.teamMembers', { teamId: 'team-1' }))
+
+    expect(runtime.linearListTeams).toHaveBeenCalled()
+    expect(runtime.linearTeamStates).toHaveBeenCalledWith('team-1')
+    expect(runtime.linearTeamLabels).toHaveBeenCalledWith('team-1')
+    expect(runtime.linearTeamMembers).toHaveBeenCalledWith('team-1')
+  })
+})
diff --git a/src/main/runtime/rpc/methods/linear.ts b/src/main/runtime/rpc/methods/linear.ts
new file mode 100644
index 00000000000..29bdcf488f8
--- /dev/null
+++ b/src/main/runtime/rpc/methods/linear.ts
@@ -0,0 +1,136 @@
+import { z } from 'zod'
+import { defineMethod, type RpcMethod } from '../core'
+import { OptionalFiniteNumber, OptionalString, requiredString } from '../schemas'
+
+const VALID_FILTERS = ['assigned', 'created', 'all', 'completed'] as const
+
+const Connect = z.object({
+  apiKey: requiredString('Invalid API key')
+})
+
+const SearchIssues = z.object({
+  query: requiredString('Missing query'),
+  limit: OptionalFiniteNumber
+})
+
+const ListIssues = z
+  .object({
+    filter: z.enum(VALID_FILTERS).optional(),
+    limit: OptionalFiniteNumber
+  })
+  .optional()
+
+const CreateIssue = z.object({
+  teamId: requiredString('Team ID is required'),
+  title: requiredString('Title is required'),
+  description: OptionalString
+})
+
+const IssueId = z.object({
+  id: requiredString('Issue ID is required')
+})
+
+const IssueComment = z.object({
+  issueId: requiredString('Issue ID is required'),
+  body: requiredString('Comment body is required')
+})
+
+const TeamId = z.object({
+  teamId: requiredString('Team ID is required')
+})
+
+const IssueUpdate = z.object({
+  id: requiredString('Issue ID is required'),
+  updates: z.object({
+    stateId: OptionalString,
+    title: OptionalString,
+    assigneeId: z.union([z.string(), z.null()]).optional(),
+    priority: z.number().int().min(0).max(4).optional(),
+    labelIds: z.array(z.string()).optional()
+  })
+})
+
+export const LINEAR_METHODS: RpcMethod[] = [
+  defineMethod({
+    name: 'linear.connect',
+    params: Connect,
+    handler: async (params, { runtime }) => runtime.linearConnect(params.apiKey.trim())
+  }),
+  defineMethod({
+    name: 'linear.disconnect',
+    params: null,
+    handler: async (_params, { runtime }) => runtime.linearDisconnect()
+  }),
+  defineMethod({
+    name: 'linear.status',
+    params: null,
+    handler: async (_params, { runtime }) => runtime.linearStatus()
+  }),
+  defineMethod({
+    name: 'linear.testConnection',
+    params: null,
+    handler: async (_params, { runtime }) => runtime.linearTestConnection()
+  }),
+  defineMethod({
+    name: 'linear.searchIssues',
+    params: SearchIssues,
+    handler: async (params, { runtime }) => runtime.linearSearchIssues(params.query, params.limit)
+  }),
+  defineMethod({
+    name: 'linear.listIssues',
+    params: ListIssues,
+    handler: async (params, { runtime }) => runtime.linearListIssues(params?.filter, params?.limit)
+  }),
+  defineMethod({
+    name: 'linear.createIssue',
+    params: CreateIssue,
+    handler: async (params, { runtime }) =>
+      runtime.linearCreateIssue(
+        params.teamId.trim(),
+        params.title.trim(),
+        params.description?.trim() || undefined
+      )
+  }),
+  defineMethod({
+    name: 'linear.getIssue',
+    params: IssueId,
+    handler: async (params, { runtime }) => runtime.linearGetIssue(params.id.trim())
+  }),
+  defineMethod({
+    name: 'linear.updateIssue',
+    params: IssueUpdate,
+    handler: async (params, { runtime }) =>
+      runtime.linearUpdateIssue(params.id.trim(), params.updates)
+  }),
+  defineMethod({
+    name: 'linear.addIssueComment',
+    params: IssueComment,
+    handler: async (params, { runtime }) =>
+      runtime.linearAddIssueComment(params.issueId.trim(), params.body.trim())
+  }),
+  defineMethod({
+    name: 'linear.issueComments',
+    params: z.object({ issueId: requiredString('Issue ID is required') }),
+    handler: async (params, { runtime }) => runtime.linearIssueComments(params.issueId.trim())
+  }),
+  defineMethod({
+    name: 'linear.listTeams',
+    params: null,
+    handler: async (_params, { runtime }) => runtime.linearListTeams()
+  }),
+  defineMethod({
+    name: 'linear.teamStates',
+    params: TeamId,
+    handler: async (params, { runtime }) => runtime.linearTeamStates(params.teamId.trim())
+  }),
+  defineMethod({
+    name: 'linear.teamLabels',
+    params: TeamId,
+    handler: async (params, { runtime }) => runtime.linearTeamLabels(params.teamId.trim())
+  }),
+  defineMethod({
+    name: 'linear.teamMembers',
+    params: TeamId,
+    handler: async (params, { runtime }) => runtime.linearTeamMembers(params.teamId.trim())
+  })
+]
diff --git a/src/main/runtime/rpc/methods/notes.test.ts b/src/main/runtime/rpc/methods/notes.test.ts
new file mode 100644
index 00000000000..35c56129f5e
--- /dev/null
+++ b/src/main/runtime/rpc/methods/notes.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import type { RpcRequest } from '../core'
+import { RpcDispatcher } from '../dispatcher'
+import { NOTE_METHODS } from './notes'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('notes RPC methods', () => {
+  it('routes note reads through the selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      listNotes: vi.fn().mockResolvedValue({ notes: [], totalCount: 0, truncated: false }),
+      showNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: null })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: NOTE_METHODS })
+
+    await dispatcher.dispatch(makeRequest('note.list', { worktree: 'id:wt-1', limit: 50 }))
+    await dispatcher.dispatch(makeRequest('note.show', { worktree: 'id:wt-1', note: 'note-1' }))
+
+    expect(runtime.listNotes).toHaveBeenCalledWith({ worktreeSelector: 'id:wt-1', limit: 50 })
+    expect(runtime.showNote).toHaveBeenCalledWith({
+      worktreeSelector: 'id:wt-1',
+      note: 'note-1'
+    })
+  })
+
+  it('routes note mutations through the selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      createNote: vi.fn().mockResolvedValue({ note: { id: 'created' }, linkKind: 'active' }),
+      saveNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: 'active' }),
+      renameNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: null }),
+      deleteNote: vi.fn().mockResolvedValue({ noteId: 'note-1', projectId: 'repo-1' }),
+      appendNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: null }),
+      linkNote: vi.fn().mockResolvedValue({
+        noteId: 'note-1',
+        projectId: 'repo-1',
+        worktreeId: 'wt-1',
+        kind: 'active',
+        createdAt: 'now'
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: NOTE_METHODS })
+
+    await dispatcher.dispatch(
+      makeRequest('note.create', {
+        worktree: 'id:wt-1',
+        title: 'Plan',
+        bodyMarkdown: 'body',
+        makeActive: true
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('note.save', {
+        worktree: 'id:wt-1',
+        note: 'note-1',
+        title: 'Plan v2',
+        bodyMarkdown: 'updated',
+        revision: 2,
+        makeActive: true
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('note.rename', { worktree: 'id:wt-1', note: 'note-1', title: 'Renamed' })
+    )
+    await dispatcher.dispatch(makeRequest('note.delete', { worktree: 'id:wt-1', note: 'note-1' }))
+    await dispatcher.dispatch(
+      makeRequest('note.append', {
+        worktree: 'id:wt-1',
+        note: 'note-1',
+        bodyMarkdown: 'more',
+        makeActive: true
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('note.link', { worktree: 'id:wt-1', note: 'note-1', kind: 'active' })
+    )
+
+    expect(runtime.createNote).toHaveBeenCalledWith(
+      expect.objectContaining({
+        worktreeSelector: 'id:wt-1',
+        title: 'Plan',
+        bodyMarkdown: 'body',
+        makeActive: true
+      })
+    )
+    expect(runtime.saveNote).toHaveBeenCalledWith(
+      expect.objectContaining({
+        worktreeSelector: 'id:wt-1',
+        note: 'note-1',
+        title: 'Plan v2',
+        bodyMarkdown: 'updated',
+        revision: 2,
+        makeActive: true
+      })
+    )
+    expect(runtime.renameNote).toHaveBeenCalledWith(
+      expect.objectContaining({
+        worktreeSelector: 'id:wt-1',
+        note: 'note-1',
+        title: 'Renamed'
+      })
+    )
+    expect(runtime.deleteNote).toHaveBeenCalledWith({
+      worktreeSelector: 'id:wt-1',
+      note: 'note-1'
+    })
+    expect(runtime.appendNote).toHaveBeenCalledWith(
+      expect.objectContaining({
+        worktreeSelector: 'id:wt-1',
+        note: 'note-1',
+        bodyMarkdown: 'more',
+        makeActive: true
+      })
+    )
+    expect(runtime.linkNote).toHaveBeenCalledWith({
+      worktreeSelector: 'id:wt-1',
+      note: 'note-1',
+      kind: 'active'
+    })
+  })
+
+  it('routes panel state and search through the selected worktree', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      searchNotes: vi.fn().mockResolvedValue({ notes: [], totalCount: 0, truncated: false }),
+      resolveNotesPanelOpenStateForWorktree: vi.fn().mockResolvedValue({ state: 'emptyDraft' })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: NOTE_METHODS })
+
+    await dispatcher.dispatch(
+      makeRequest('note.search', { worktree: 'id:wt-1', query: 'todo', limit: 20 })
+    )
+    await dispatcher.dispatch(makeRequest('note.panelState', { worktree: 'id:wt-1' }))
+
+    expect(runtime.searchNotes).toHaveBeenCalledWith({
+      worktreeSelector: 'id:wt-1',
+      query: 'todo',
+      limit: 20
+    })
+    expect(runtime.resolveNotesPanelOpenStateForWorktree).toHaveBeenCalledWith({
+      worktreeSelector: 'id:wt-1'
+    })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/notes.ts b/src/main/runtime/rpc/methods/notes.ts
index a4013f76671..fc0ea173871 100644
--- a/src/main/runtime/rpc/methods/notes.ts
+++ b/src/main/runtime/rpc/methods/notes.ts
@@ -17,13 +17,34 @@ const NoteShowParams = NoteScopedParams.extend({
 const NoteCreateParams = NoteScopedParams.extend({
   title: requiredString('Missing note title'),
   bodyMarkdown: OptionalString,
-  makeActive: z.boolean().optional()
+  makeActive: z.boolean().optional(),
+  createdBySessionId: z.string().nullable().optional()
+})
+
+const NoteSaveParams = NoteScopedParams.extend({
+  note: requiredString('Missing note selector'),
+  title: OptionalString,
+  bodyMarkdown: requiredString('Missing note body'),
+  revision: OptionalFiniteNumber,
+  makeActive: z.boolean().optional(),
+  updatedBySessionId: z.string().nullable().optional()
+})
+
+const NoteRenameParams = NoteScopedParams.extend({
+  note: requiredString('Missing note selector'),
+  title: requiredString('Missing note title'),
+  updatedBySessionId: z.string().nullable().optional()
+})
+
+const NoteDeleteParams = NoteScopedParams.extend({
+  note: requiredString('Missing note selector')
 })
 
 const NoteAppendParams = NoteScopedParams.extend({
   note: requiredString('Missing note selector'),
   bodyMarkdown: requiredString('Missing note body'),
-  makeActive: z.boolean().optional()
+  makeActive: z.boolean().optional(),
+  updatedBySessionId: z.string().nullable().optional()
 })
 
 const NoteSearchParams = NoteScopedParams.extend({
@@ -31,6 +52,11 @@ const NoteSearchParams = NoteScopedParams.extend({
   limit: OptionalFiniteNumber
 })
 
+const NoteLinkParams = NoteScopedParams.extend({
+  note: requiredString('Missing note selector'),
+  kind: z.enum(['active', 'referenced'])
+})
+
 export const NOTE_METHODS: readonly RpcAnyMethod[] = [
   defineMethod({
     name: 'note.list',
@@ -58,7 +84,42 @@ export const NOTE_METHODS: readonly RpcAnyMethod[] = [
         worktreeSelector: params.worktree,
         title: params.title,
         bodyMarkdown: params.bodyMarkdown,
-        makeActive: params.makeActive
+        makeActive: params.makeActive,
+        createdBySessionId: params.createdBySessionId
+      })
+  }),
+  defineMethod({
+    name: 'note.save',
+    params: NoteSaveParams,
+    handler: async (params, { runtime }) =>
+      await runtime.saveNote({
+        worktreeSelector: params.worktree,
+        note: params.note,
+        title: params.title,
+        bodyMarkdown: params.bodyMarkdown,
+        revision: params.revision,
+        makeActive: params.makeActive,
+        updatedBySessionId: params.updatedBySessionId
+      })
+  }),
+  defineMethod({
+    name: 'note.rename',
+    params: NoteRenameParams,
+    handler: async (params, { runtime }) =>
+      await runtime.renameNote({
+        worktreeSelector: params.worktree,
+        note: params.note,
+        title: params.title,
+        updatedBySessionId: params.updatedBySessionId
+      })
+  }),
+  defineMethod({
+    name: 'note.delete',
+    params: NoteDeleteParams,
+    handler: async (params, { runtime }) =>
+      await runtime.deleteNote({
+        worktreeSelector: params.worktree,
+        note: params.note
       })
   }),
   defineMethod({
@@ -69,7 +130,8 @@ export const NOTE_METHODS: readonly RpcAnyMethod[] = [
         worktreeSelector: params.worktree,
         note: params.note,
         bodyMarkdown: params.bodyMarkdown,
-        makeActive: params.makeActive
+        makeActive: params.makeActive,
+        updatedBySessionId: params.updatedBySessionId
       })
   }),
   defineMethod({
@@ -81,5 +143,23 @@ export const NOTE_METHODS: readonly RpcAnyMethod[] = [
         query: params.query,
         limit: params.limit
       })
+  }),
+  defineMethod({
+    name: 'note.link',
+    params: NoteLinkParams,
+    handler: async (params, { runtime }) =>
+      await runtime.linkNote({
+        worktreeSelector: params.worktree,
+        note: params.note,
+        kind: params.kind
+      })
+  }),
+  defineMethod({
+    name: 'note.panelState',
+    params: NoteScopedParams,
+    handler: async (params, { runtime }) =>
+      await runtime.resolveNotesPanelOpenStateForWorktree({
+        worktreeSelector: params.worktree
+      })
   })
 ]
diff --git a/src/main/runtime/rpc/methods/orchestration.test.ts b/src/main/runtime/rpc/methods/orchestration.test.ts
index 3ae1d213586..93856e98adb 100644
--- a/src/main/runtime/rpc/methods/orchestration.test.ts
+++ b/src/main/runtime/rpc/methods/orchestration.test.ts
@@ -349,6 +349,42 @@ describe('orchestration RPC methods', () => {
       // Must not have marked read
       expect(db.getUnreadMessages('b')).toHaveLength(1)
     })
+
+    it('does not mark messages read when a waiting check is aborted', async () => {
+      setup()
+      const abortController = new AbortController()
+      ctx = { runtime, signal: abortController.signal }
+      vi.spyOn(runtime, 'waitForMessage').mockImplementation(async () => {
+        db.insertMessage({ from: 'a', to: 'b', subject: 'arrived during close' })
+        abortController.abort()
+      })
+
+      const result = (await call('orchestration.check', {
+        terminal: 'b',
+        wait: true,
+        timeoutMs: 100
+      })) as { messages: unknown[]; count: number }
+
+      expect(result).toEqual({ messages: [], count: 0 })
+      expect(db.getUnreadMessages('b')).toHaveLength(1)
+    })
+
+    it('does not mark existing messages read when the check starts aborted', async () => {
+      setup()
+      const abortController = new AbortController()
+      abortController.abort()
+      ctx = { runtime, signal: abortController.signal }
+      db.insertMessage({ from: 'a', to: 'b', subject: 'already unread' })
+
+      const result = (await call('orchestration.check', {
+        terminal: 'b',
+        wait: true,
+        timeoutMs: 100
+      })) as { messages: unknown[]; count: number }
+
+      expect(result).toEqual({ messages: [], count: 0 })
+      expect(db.getUnreadMessages('b')).toHaveLength(1)
+    })
   })
 
   describe('orchestration.reply', () => {
diff --git a/src/main/runtime/rpc/methods/orchestration.ts b/src/main/runtime/rpc/methods/orchestration.ts
index e1a2d68b943..0fb5a6f8680 100644
--- a/src/main/runtime/rpc/methods/orchestration.ts
+++ b/src/main/runtime/rpc/methods/orchestration.ts
@@ -241,6 +241,9 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         return { messages, count: messages.length }
       }
 
+      if (signal?.aborted) {
+        return { messages: [], count: 0 }
+      }
       const result = readAndReturn()
       if (result.count > 0 || !params.wait) {
         return result
@@ -257,6 +260,9 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         timeoutMs: params.timeoutMs ?? undefined,
         signal
       })
+      if (signal?.aborted) {
+        return { messages: [], count: 0 }
+      }
       return readAndReturn()
     }
   }),
diff --git a/src/main/runtime/rpc/methods/repo.test.ts b/src/main/runtime/rpc/methods/repo.test.ts
new file mode 100644
index 00000000000..da7b9212215
--- /dev/null
+++ b/src/main/runtime/rpc/methods/repo.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { REPO_METHODS } from './repo'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('repo RPC methods', () => {
+  it('creates a repo on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      createRepo: vi.fn().mockResolvedValue({
+        repo: { id: 'repo-1', path: '/srv/projects/new-app', kind: 'git' }
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: REPO_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('repo.create', {
+        parentPath: '/srv/projects',
+        name: 'new-app',
+        kind: 'git'
+      })
+    )
+
+    expect(runtime.createRepo).toHaveBeenCalledWith('/srv/projects', 'new-app', 'git')
+    expect(response).toMatchObject({
+      ok: true,
+      result: { repo: { id: 'repo-1', path: '/srv/projects/new-app' } }
+    })
+  })
+
+  it('clones a repo on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      cloneRepo: vi.fn().mockResolvedValue({
+        id: 'repo-1',
+        path: '/srv/projects/orca',
+        kind: 'git'
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: REPO_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('repo.clone', {
+        url: 'https://github.com/example/orca.git',
+        destination: '/srv/projects'
+      })
+    )
+
+    expect(runtime.cloneRepo).toHaveBeenCalledWith(
+      'https://github.com/example/orca.git',
+      '/srv/projects'
+    )
+    expect(response).toMatchObject({
+      ok: true,
+      result: { repo: { id: 'repo-1', path: '/srv/projects/orca' } }
+    })
+  })
+
+  it('routes repository hook operations to the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      checkRepoHooks: vi.fn().mockResolvedValue({
+        hasHooks: true,
+        hooks: { scripts: { setup: 'pnpm install' } },
+        mayNeedUpdate: false
+      }),
+      readRepoIssueCommand: vi.fn().mockResolvedValue({
+        localContent: null,
+        sharedContent: 'Fix {{artifact_url}}',
+        effectiveContent: 'Fix {{artifact_url}}',
+        localFilePath: '/srv/repo/.orca/issue-command',
+        source: 'shared'
+      }),
+      writeRepoIssueCommand: vi.fn().mockResolvedValue({ ok: true })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: REPO_METHODS })
+
+    await dispatcher.dispatch(makeRequest('repo.hooksCheck', { repo: 'repo-1' }))
+    await dispatcher.dispatch(makeRequest('repo.issueCommandRead', { repo: 'repo-1' }))
+    await dispatcher.dispatch(
+      makeRequest('repo.issueCommandWrite', {
+        repo: 'repo-1',
+        content: 'Fix it'
+      })
+    )
+
+    expect(runtime.checkRepoHooks).toHaveBeenCalledWith('repo-1')
+    expect(runtime.readRepoIssueCommand).toHaveBeenCalledWith('repo-1')
+    expect(runtime.writeRepoIssueCommand).toHaveBeenCalledWith('repo-1', 'Fix it')
+  })
+})
diff --git a/src/main/runtime/rpc/methods/repo.ts b/src/main/runtime/rpc/methods/repo.ts
index 3af1133f836..9b466a2ce6a 100644
--- a/src/main/runtime/rpc/methods/repo.ts
+++ b/src/main/runtime/rpc/methods/repo.ts
@@ -1,13 +1,25 @@
 import { z } from 'zod'
 import { defineMethod, type RpcMethod } from '../core'
-import { OptionalFiniteNumber, requiredString } from '../schemas'
+import { OptionalFiniteNumber, OptionalString, requiredString } from '../schemas'
 
 const RepoSelector = z.object({
   repo: requiredString('Missing repo selector')
 })
 
 const RepoPath = z.object({
-  path: requiredString('Missing repo path')
+  path: requiredString('Missing repo path'),
+  kind: z.enum(['git', 'folder']).optional()
+})
+
+const RepoCreate = z.object({
+  parentPath: requiredString('Missing parent path'),
+  name: requiredString('Missing repo name'),
+  kind: z.enum(['git', 'folder']).optional()
+})
+
+const RepoClone = z.object({
+  url: requiredString('Missing clone URL'),
+  destination: requiredString('Missing clone destination')
 })
 
 const RepoSetBaseRef = z.object({
@@ -15,6 +27,18 @@ const RepoSetBaseRef = z.object({
   ref: requiredString('Missing base ref')
 })
 
+const RepoUpdate = RepoSelector.extend({
+  updates: z.object({
+    displayName: OptionalString,
+    badgeColor: OptionalString,
+    hookSettings: z.unknown().optional(),
+    worktreeBaseRef: OptionalString,
+    kind: z.enum(['git', 'folder']).optional(),
+    symlinkPaths: z.array(z.string()).optional(),
+    issueSourcePreference: z.enum(['auto', 'github', 'linear']).optional()
+  })
+})
+
 const RepoSearchRefs = z.object({
   repo: requiredString('Missing repo selector'),
   query: z
@@ -24,6 +48,14 @@ const RepoSearchRefs = z.object({
   limit: OptionalFiniteNumber
 })
 
+const RepoReorder = z.object({
+  orderedIds: z.array(z.string())
+})
+
+const RepoIssueCommandWrite = RepoSelector.extend({
+  content: z.string()
+})
+
 export const REPO_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'repo.list',
@@ -33,13 +65,48 @@ export const REPO_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'repo.add',
     params: RepoPath,
-    handler: async (params, { runtime }) => ({ repo: await runtime.addRepo(params.path) })
+    handler: async (params, { runtime }) => ({
+      repo: await runtime.addRepo(params.path, params.kind)
+    })
+  }),
+  defineMethod({
+    name: 'repo.create',
+    params: RepoCreate,
+    handler: async (params, { runtime }) =>
+      runtime.createRepo(params.parentPath, params.name, params.kind)
+  }),
+  defineMethod({
+    name: 'repo.clone',
+    params: RepoClone,
+    handler: async (params, { runtime }) => ({
+      repo: await runtime.cloneRepo(params.url, params.destination)
+    })
   }),
   defineMethod({
     name: 'repo.show',
     params: RepoSelector,
     handler: async (params, { runtime }) => ({ repo: await runtime.showRepo(params.repo) })
   }),
+  defineMethod({
+    name: 'repo.update',
+    params: RepoUpdate,
+    handler: async (params, { runtime }) => ({
+      repo: await runtime.updateRepo(
+        params.repo,
+        params.updates as Parameters<typeof runtime.updateRepo>[1]
+      )
+    })
+  }),
+  defineMethod({
+    name: 'repo.rm',
+    params: RepoSelector,
+    handler: async (params, { runtime }) => runtime.removeRepo(params.repo)
+  }),
+  defineMethod({
+    name: 'repo.reorder',
+    params: RepoReorder,
+    handler: async (params, { runtime }) => runtime.reorderRepos(params.orderedIds)
+  }),
   defineMethod({
     name: 'repo.setBaseRef',
     params: RepoSetBaseRef,
@@ -47,6 +114,11 @@ export const REPO_METHODS: RpcMethod[] = [
       repo: await runtime.setRepoBaseRef(params.repo, params.ref)
     })
   }),
+  defineMethod({
+    name: 'repo.baseRefDefault',
+    params: RepoSelector,
+    handler: async (params, { runtime }) => runtime.getRepoBaseRefDefault(params.repo)
+  }),
   defineMethod({
     name: 'repo.searchRefs',
     params: RepoSearchRefs,
@@ -57,5 +129,21 @@ export const REPO_METHODS: RpcMethod[] = [
     name: 'repo.hooks',
     params: RepoSelector,
     handler: async (params, { runtime }) => runtime.getRepoHooks(params.repo)
+  }),
+  defineMethod({
+    name: 'repo.hooksCheck',
+    params: RepoSelector,
+    handler: async (params, { runtime }) => runtime.checkRepoHooks(params.repo)
+  }),
+  defineMethod({
+    name: 'repo.issueCommandRead',
+    params: RepoSelector,
+    handler: async (params, { runtime }) => runtime.readRepoIssueCommand(params.repo)
+  }),
+  defineMethod({
+    name: 'repo.issueCommandWrite',
+    params: RepoIssueCommandWrite,
+    handler: async (params, { runtime }) =>
+      runtime.writeRepoIssueCommand(params.repo, params.content)
   })
 ]
diff --git a/src/main/runtime/rpc/methods/terminal.ts b/src/main/runtime/rpc/methods/terminal.ts
index fdf9350b99a..1fcbc4fae41 100644
--- a/src/main/runtime/rpc/methods/terminal.ts
+++ b/src/main/runtime/rpc/methods/terminal.ts
@@ -2,12 +2,15 @@
 import { z } from 'zod'
 import { defineMethod, defineStreamingMethod, type RpcAnyMethod } from '../core'
 import { OptionalFiniteNumber, OptionalString, requiredString } from '../schemas'
-import type { OrcaRuntimeService } from '../../orca-runtime'
+import type { DriverState, OrcaRuntimeService } from '../../orca-runtime'
 import {
   TerminalStreamOpcode,
+  decodeTerminalStreamJson,
+  decodeTerminalStreamText,
   encodeTerminalStreamFrame,
   encodeTerminalStreamJson,
-  encodeTerminalStreamText
+  encodeTerminalStreamText,
+  type TerminalStreamFrame
 } from '../../../../shared/terminal-stream-protocol'
 
 // Why: when a mobile client subscribes the server resizes the PTY to phone
@@ -19,6 +22,9 @@ import {
 const MOBILE_SUBSCRIBE_SCROLLBACK_ROWS = 1000
 const MOBILE_SNAPSHOT_BYTE_BUDGET = 512 * 1024
 const TERMINAL_STREAM_CHUNK_BYTES = 48 * 1024
+const TERMINAL_OUTPUT_FLUSH_MS = 5
+const TERMINAL_OUTPUT_BATCH_MAX_CHARS = 64 * 1024
+const TERMINAL_MULTIPLEX_PENDING_MAX_CHARS = 256 * 1024
 let nextTerminalStreamId = 1
 
 type SnapshotFrameOptions = {
@@ -41,6 +47,126 @@ type SerializedSnapshot = {
   truncatedByByteBudget: boolean
 } | null
 
+type TerminalViewportClient = {
+  id: string
+  type?: 'mobile' | 'desktop'
+}
+
+type TerminalMultiplexStream = {
+  streamId: number
+  terminal: string
+  ptyId: string
+  client: TerminalViewportClient | undefined
+  isMobile: boolean
+  buffering: boolean
+  pendingOutput: string[]
+  pendingOutputChars: number
+  outputBatcher: ReturnType<typeof createTerminalOutputBatcher>
+  unsubscribeData: () => void
+  unsubscribeResize: () => void
+  unsubscribeFit: () => void
+  unsubscribeDriver: () => void
+  unregisterBinaryHandler: () => void
+}
+
+function createTerminalOutputBatcher(onFlush: (data: string) => void): {
+  push: (data: string) => void
+  flush: () => void
+  dispose: () => void
+} {
+  let chunks: string[] = []
+  let chars = 0
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const clearTimer = (): void => {
+    if (!timer) {
+      return
+    }
+    clearTimeout(timer)
+    timer = null
+  }
+
+  const flush = (): void => {
+    clearTimer()
+    if (chunks.length === 0) {
+      return
+    }
+    const data = chunks.length === 1 ? chunks[0]! : chunks.join('')
+    chunks = []
+    chars = 0
+    onFlush(data)
+  }
+
+  return {
+    push(data: string): void {
+      if (!data) {
+        return
+      }
+      chunks.push(data)
+      chars += data.length
+      if (chars >= TERMINAL_OUTPUT_BATCH_MAX_CHARS) {
+        flush()
+        return
+      }
+      if (!timer) {
+        // Why: Paseo coalesces terminal stream output before crossing the
+        // network. Desktop runtime subscribers need the same burst boundary.
+        timer = setTimeout(flush, TERMINAL_OUTPUT_FLUSH_MS)
+        if (typeof timer.unref === 'function') {
+          timer.unref()
+        }
+      }
+    },
+    flush,
+    dispose(): void {
+      clearTimer()
+      chunks = []
+      chars = 0
+    }
+  }
+}
+
+function isTerminalInputLockedForClient(
+  runtime: OrcaRuntimeService,
+  ptyId: string,
+  client: TerminalViewportClient | undefined
+): boolean {
+  if (client?.type === 'mobile') {
+    return false
+  }
+  // Why: pre-refactor mobile builds did not send client metadata. Desktop
+  // callers we control now identify as desktop, so keep legacy mobile input
+  // working without opening the new desktop path.
+  if (!client) {
+    return false
+  }
+  return runtime.getDriver(ptyId).kind === 'mobile'
+}
+
+function resolveMobileFloorClientId(
+  driver: DriverState | null,
+  client: TerminalViewportClient | undefined
+): string | null {
+  if (client?.type === 'mobile') {
+    return client.id
+  }
+  if (!client && driver?.kind === 'mobile') {
+    return driver.clientId
+  }
+  return null
+}
+
+function appendPendingMultiplexOutput(stream: TerminalMultiplexStream, data: string): void {
+  stream.pendingOutput.push(data)
+  stream.pendingOutputChars += data.length
+  while (
+    stream.pendingOutputChars > TERMINAL_MULTIPLEX_PENDING_MAX_CHARS &&
+    stream.pendingOutput.length > 0
+  ) {
+    stream.pendingOutputChars -= stream.pendingOutput.shift()?.length ?? 0
+  }
+}
+
 function sendSnapshotFrames(
   sendFrame: (opcode: TerminalStreamOpcode, payload?: Uint8Array<ArrayBufferLike>) => void,
   options: SnapshotFrameOptions
@@ -99,6 +225,20 @@ async function serializeBudgetedMobileSnapshot(
   return null
 }
 
+async function updateViewportForClient(
+  runtime: OrcaRuntimeService,
+  ptyId: string,
+  client: TerminalViewportClient,
+  viewport: { cols: number; rows: number },
+  defaultType: 'mobile' | 'desktop'
+): Promise<boolean> {
+  const type = client.type ?? defaultType
+  if (type === 'mobile') {
+    return runtime.updateMobileViewport(ptyId, client.id, viewport)
+  }
+  return runtime.updateDesktopViewport(ptyId, viewport)
+}
+
 const TerminalHandle = z.object({
   terminal: requiredString('Missing terminal handle')
 })
@@ -161,6 +301,11 @@ const TerminalSend = TerminalHandle.extend({
     .optional()
 })
 
+const TerminalViewport = z.object({
+  cols: z.number().int().min(1).max(1000),
+  rows: z.number().int().min(1).max(500)
+})
+
 const TerminalWait = TerminalHandle.extend({
   for: z.custom<'exit' | 'tui-idle'>((value) => value === 'exit' || value === 'tui-idle', {
     message: 'Invalid --for value. Supported: exit, tui-idle'
@@ -171,6 +316,7 @@ const TerminalWait = TerminalHandle.extend({
 const TerminalCreateParams = z.object({
   worktree: OptionalString,
   command: OptionalString,
+  env: z.record(z.string(), z.string()).optional(),
   title: OptionalString,
   focus: z.unknown().optional()
 })
@@ -210,12 +356,7 @@ const TerminalSubscribe = TerminalHandle.extend({
       type: z.enum(['mobile', 'desktop']).default('desktop')
     })
     .optional(),
-  viewport: z
-    .object({
-      cols: z.number().int().min(20).max(240),
-      rows: z.number().int().min(8).max(120)
-    })
-    .optional(),
+  viewport: TerminalViewport.optional(),
   capabilities: z
     .object({
       terminalBinaryStream: z.literal(1).optional()
@@ -223,6 +364,19 @@ const TerminalSubscribe = TerminalHandle.extend({
     .optional()
 })
 
+const TerminalMultiplex = z.object({})
+
+const TerminalMultiplexSubscribeFrame = TerminalHandle.extend({
+  streamId: z.number().int().min(1),
+  client: z
+    .object({
+      id: requiredString('Missing client ID'),
+      type: z.enum(['mobile', 'desktop']).default('desktop')
+    })
+    .optional(),
+  viewport: TerminalViewport.optional()
+})
+
 const TerminalSetDisplayMode = TerminalHandle.extend({
   // Why: 'phone' was previously a "stay at phone dims after unsubscribe"
   // mode that the toggle UI never produced and nothing in product
@@ -317,6 +471,13 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       terminal: await runtime.readTerminal(params.terminal, { cursor: params.cursor })
     })
   }),
+  defineMethod({
+    name: 'terminal.inspectProcess',
+    params: TerminalHandle,
+    handler: async (params, { runtime }) => ({
+      process: await runtime.inspectTerminalProcess(params.terminal)
+    })
+  }),
   defineMethod({
     name: 'terminal.rename',
     params: TerminalRename,
@@ -335,6 +496,17 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     name: 'terminal.send',
     params: TerminalSend,
     handler: async (params, { runtime }) => {
+      const leaf = runtime.resolveLeafForHandle(params.terminal)
+      const driver = leaf?.ptyId ? runtime.getDriver(leaf.ptyId) : null
+      if (leaf?.ptyId && isTerminalInputLockedForClient(runtime, leaf.ptyId, params.client)) {
+        return {
+          send: {
+            handle: params.terminal,
+            accepted: false,
+            bytesWritten: 0
+          }
+        }
+      }
       const result = await runtime.sendTerminal(params.terminal, {
         text: params.text,
         enter: params.enter === true,
@@ -343,12 +515,11 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       // Why: deliberate mobile input is a take-floor action. Drives the
       // `* → mobile{clientId}` driver transition so the desktop banner
       // remounts (if previously reclaimed) and active phone-fit dims follow
-      // the most recent actor. Only mobile-typed callers take the floor.
-      if (params.client && params.client.type === 'mobile') {
-        const leaf = runtime.resolveLeafForHandle(params.terminal)
-        if (leaf?.ptyId) {
-          await runtime.mobileTookFloor(leaf.ptyId, params.client.id)
-        }
+      // the most recent actor. Clientless sends are old mobile builds, so use
+      // the current mobile driver as their compatibility identity.
+      const mobileFloorClientId = resolveMobileFloorClientId(driver, params.client)
+      if (leaf?.ptyId && mobileFloorClientId) {
+        await runtime.mobileTookFloor(leaf.ptyId, mobileFloorClientId)
       }
       return { send: result }
     }
@@ -369,6 +540,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     handler: async (params, { runtime }) => ({
       terminal: await runtime.createTerminal(params.worktree, {
         command: params.command,
+        env: params.env,
         title: params.title,
         focus: params.focus === true
       })
@@ -452,6 +624,17 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       return { mode: params.mode, seq: runtime.getLayout(leaf.ptyId)?.seq }
     }
   }),
+  defineMethod({
+    name: 'terminal.restoreFit',
+    params: TerminalHandle,
+    handler: async (params, { runtime }) => {
+      const leaf = runtime.resolveLeafForHandle(params.terminal)
+      if (!leaf?.ptyId) {
+        throw new Error('no_connected_pty')
+      }
+      return { restored: await runtime.reclaimTerminalForDesktop(leaf.ptyId) }
+    }
+  }),
   defineMethod({
     name: 'terminal.getDisplayMode',
     params: TerminalHandle,
@@ -470,24 +653,336 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       if (!leaf?.ptyId) {
         throw new Error('no_connected_pty')
       }
-      const updated = await runtime.updateMobileViewport(
+      const updated = await updateViewportForClient(
+        runtime,
         leaf.ptyId,
-        params.client.id,
-        params.viewport
+        params.client,
+        params.viewport,
+        'mobile'
       )
       return { updated, seq: runtime.getLayout(leaf.ptyId)?.seq }
     }
   }),
+  // Why: desktop remote sessions can have dozens of panes. One streaming RPC
+  // owns the binary socket and routes terminal slots by streamId, mirroring
+  // Paseo's slot-based terminal data plane while keeping legacy subscribe as
+  // the compatibility fallback.
+  defineStreamingMethod({
+    name: 'terminal.multiplex',
+    params: TerminalMultiplex,
+    handler: async (
+      _params,
+      { runtime, connectionId, sendBinary, registerBinaryStreamHandler },
+      emit
+    ) => {
+      if (!sendBinary || !registerBinaryStreamHandler || !connectionId) {
+        throw new Error('binary_terminal_stream_required')
+      }
+
+      let closed = false
+      let cursor = 0
+      const streams = new Map<number, TerminalMultiplexStream>()
+      let resolveMultiplex = (): void => {}
+      const multiplexClosed = new Promise<void>((resolve) => {
+        resolveMultiplex = resolve
+      })
+      const sendFrame = (
+        streamId: number,
+        opcode: TerminalStreamOpcode,
+        payload: Uint8Array<ArrayBufferLike> = new Uint8Array()
+      ): void => {
+        if (closed) {
+          return
+        }
+        sendBinary(encodeTerminalStreamFrame({ opcode, streamId, seq: cursor++, payload }))
+      }
+      const sendStreamError = (streamId: number, message: string): void => {
+        sendFrame(streamId, TerminalStreamOpcode.Error, encodeTerminalStreamText(message))
+        emit({ type: 'error', streamId, message })
+      }
+      const detachStream = (streamId: number, emitEnd: boolean): void => {
+        const stream = streams.get(streamId)
+        if (!stream) {
+          return
+        }
+        stream.outputBatcher.flush()
+        stream.outputBatcher.dispose()
+        stream.unsubscribeData()
+        stream.unsubscribeResize()
+        stream.unsubscribeFit()
+        stream.unsubscribeDriver()
+        stream.unregisterBinaryHandler()
+        streams.delete(streamId)
+        if (stream.isMobile && stream.client?.id) {
+          runtime.handleMobileUnsubscribe(stream.ptyId, stream.client.id)
+        }
+        if (emitEnd) {
+          emit({ type: 'end', streamId })
+        }
+      }
+      const closeMultiplex = (): void => {
+        if (closed) {
+          return
+        }
+        closed = true
+        for (const streamId of Array.from(streams.keys())) {
+          detachStream(streamId, false)
+        }
+        unregisterControlHandler()
+        resolveMultiplex()
+      }
+      const handleSlotFrame = (
+        stream: TerminalMultiplexStream,
+        frame: TerminalStreamFrame
+      ): void => {
+        if (closed || streams.get(stream.streamId) !== stream) {
+          return
+        }
+        if (frame.opcode === TerminalStreamOpcode.Unsubscribe) {
+          detachStream(stream.streamId, false)
+          return
+        }
+        if (frame.opcode === TerminalStreamOpcode.Input) {
+          const text = decodeTerminalStreamText(frame.payload)
+          if (!text) {
+            return
+          }
+          if (isTerminalInputLockedForClient(runtime, stream.ptyId, stream.client)) {
+            return
+          }
+          void runtime
+            .sendTerminal(stream.terminal, { text, enter: false, interrupt: false })
+            .then(async () => {
+              if (stream.isMobile && stream.client?.id) {
+                await runtime.mobileTookFloor(stream.ptyId, stream.client.id)
+              }
+            })
+            .catch(() => {})
+          return
+        }
+        if (frame.opcode === TerminalStreamOpcode.Resize && stream.client) {
+          const viewport = decodeTerminalStreamJson<{ cols?: unknown; rows?: unknown }>(
+            frame.payload
+          )
+          if (!viewport || typeof viewport.cols !== 'number' || typeof viewport.rows !== 'number') {
+            return
+          }
+          void updateViewportForClient(
+            runtime,
+            stream.ptyId,
+            stream.client,
+            { cols: viewport.cols, rows: viewport.rows },
+            stream.isMobile ? 'mobile' : 'desktop'
+          ).catch(() => {})
+        }
+      }
+      const handleSubscribeFrame = async (payload: Uint8Array<ArrayBufferLike>): Promise<void> => {
+        const raw = decodeTerminalStreamJson<unknown>(payload)
+        const parsed = TerminalMultiplexSubscribeFrame.safeParse(raw)
+        if (!parsed.success) {
+          return
+        }
+        const request = parsed.data
+        detachStream(request.streamId, false)
+
+        let leaf = runtime.resolveLeafForHandle(request.terminal)
+        const isMobile = request.client?.type === 'mobile'
+        if (!leaf?.ptyId && isMobile) {
+          try {
+            const ptyId = await runtime.waitForLeafPtyId(request.terminal)
+            leaf = { ptyId }
+          } catch {
+            // Fall through to the explicit no_connected_pty error below.
+          }
+        }
+        if (!leaf?.ptyId) {
+          sendStreamError(request.streamId, 'no_connected_pty')
+          emit({ type: 'end', streamId: request.streamId })
+          return
+        }
+
+        const ptyId = leaf.ptyId
+        const stream: TerminalMultiplexStream = {
+          streamId: request.streamId,
+          terminal: request.terminal,
+          ptyId,
+          client: request.client,
+          isMobile,
+          buffering: true,
+          pendingOutput: [],
+          pendingOutputChars: 0,
+          outputBatcher: createTerminalOutputBatcher((data) => {
+            sendFrame(request.streamId, TerminalStreamOpcode.Output, encodeTerminalStreamText(data))
+          }),
+          unsubscribeData: () => {},
+          unsubscribeResize: () => {},
+          unsubscribeFit: () => {},
+          unsubscribeDriver: () => {},
+          unregisterBinaryHandler: () => {}
+        }
+        streams.set(request.streamId, stream)
+        stream.unregisterBinaryHandler = registerBinaryStreamHandler(request.streamId, (frame) =>
+          handleSlotFrame(stream, frame)
+        )
+
+        try {
+          stream.unsubscribeData = runtime.subscribeToTerminalData(ptyId, (data) => {
+            if (closed || streams.get(request.streamId) !== stream) {
+              return
+            }
+            if (stream.buffering) {
+              appendPendingMultiplexOutput(stream, data)
+              return
+            }
+            stream.outputBatcher.push(data)
+          })
+
+          if (isMobile && request.client?.id) {
+            await runtime.handleMobileSubscribe(ptyId, request.client.id, request.viewport)
+          } else if (request.viewport && request.client) {
+            await updateViewportForClient(
+              runtime,
+              ptyId,
+              request.client,
+              request.viewport,
+              'desktop'
+            )
+          }
+          if (closed || streams.get(request.streamId) !== stream) {
+            return
+          }
+
+          if (!isMobile) {
+            stream.unsubscribeFit = runtime.subscribeToFitOverrideChanges(ptyId, (event) => {
+              emit({
+                type: 'fit-override-changed',
+                streamId: request.streamId,
+                mode: event.mode,
+                cols: event.cols,
+                rows: event.rows
+              })
+            })
+            stream.unsubscribeDriver = runtime.subscribeToDriverChanges(ptyId, (driver) => {
+              emit({
+                type: 'driver-changed',
+                streamId: request.streamId,
+                driver
+              })
+            })
+          }
+
+          const read = await runtime.readTerminal(request.terminal)
+          const serialized = await serializeBudgetedMobileSnapshot(runtime, ptyId, isMobile)
+          if (closed || streams.get(request.streamId) !== stream) {
+            return
+          }
+          const size = runtime.getTerminalSize(ptyId)
+          const displayMode = runtime.getMobileDisplayMode(ptyId)
+          const seq = runtime.getLayout(ptyId)?.seq
+          if (!isMobile) {
+            const fitOverride = runtime.getTerminalFitOverride(ptyId)
+            emit({
+              type: 'fit-override-changed',
+              streamId: request.streamId,
+              mode: fitOverride?.mode ?? 'desktop-fit',
+              cols: fitOverride?.cols ?? size?.cols ?? 0,
+              rows: fitOverride?.rows ?? size?.rows ?? 0
+            })
+            emit({
+              type: 'driver-changed',
+              streamId: request.streamId,
+              driver: runtime.getDriver(ptyId)
+            })
+          }
+          emit({
+            type: 'subscribed',
+            streamId: request.streamId,
+            terminal: request.terminal,
+            cols: serialized?.cols ?? size?.cols,
+            rows: serialized?.rows ?? size?.rows,
+            displayMode,
+            seq,
+            truncated: read.truncated
+          })
+          sendSnapshotFrames((opcode, payload) => sendFrame(request.streamId, opcode, payload), {
+            kind: 'scrollback',
+            cols: serialized?.cols ?? size?.cols ?? 80,
+            rows: serialized?.rows ?? size?.rows ?? 24,
+            displayMode,
+            seq,
+            truncated: read.truncated,
+            truncatedByByteBudget: serialized?.truncatedByByteBudget,
+            data: serialized?.data ?? (read.tail.length > 0 ? `${read.tail.join('\r\n')}\r\n` : '')
+          })
+          stream.buffering = false
+          for (const data of stream.pendingOutput.splice(0)) {
+            stream.outputBatcher.push(data)
+          }
+          stream.pendingOutputChars = 0
+          stream.outputBatcher.flush()
+
+          stream.unsubscribeResize = runtime.subscribeToTerminalResize(ptyId, (event) => {
+            stream.outputBatcher.flush()
+            sendFrame(
+              request.streamId,
+              TerminalStreamOpcode.Resized,
+              encodeTerminalStreamJson({
+                cols: event.cols,
+                rows: event.rows,
+                displayMode: event.displayMode,
+                reason: event.reason,
+                seq: event.seq
+              })
+            )
+          })
+          void runtime
+            .waitForTerminal(request.terminal, { condition: 'exit' })
+            .then(() => {
+              if (streams.get(request.streamId) === stream) {
+                detachStream(request.streamId, true)
+              }
+            })
+            .catch(() => {
+              if (streams.get(request.streamId) === stream) {
+                detachStream(request.streamId, true)
+              }
+            })
+        } catch (error) {
+          detachStream(request.streamId, false)
+          sendStreamError(request.streamId, error instanceof Error ? error.message : String(error))
+          emit({ type: 'end', streamId: request.streamId })
+        }
+      }
+      const unregisterControlHandler = registerBinaryStreamHandler(0, (frame) => {
+        if (frame.opcode !== TerminalStreamOpcode.Subscribe) {
+          return
+        }
+        void handleSubscribeFrame(frame.payload)
+      })
+
+      runtime.registerSubscriptionCleanup(
+        `terminal-multiplex:${connectionId}`,
+        closeMultiplex,
+        connectionId
+      )
+      emit({ type: 'ready' })
+      await multiplexClosed
+    }
+  }),
   // Why: terminal.subscribe streams live terminal output over WebSocket.
   // It sends initial scrollback, then live data chunks as they arrive.
   // Mobile clients pass client+viewport params for server-side auto-fit.
   defineStreamingMethod({
     name: 'terminal.subscribe',
     params: TerminalSubscribe,
-    handler: async (params, { runtime, connectionId, sendBinary }, emit) => {
+    handler: async (
+      params,
+      { runtime, connectionId, sendBinary, registerBinaryStreamHandler },
+      emit
+    ) => {
       let leaf = runtime.resolveLeafForHandle(params.terminal)
       const isMobile = params.client?.type === 'mobile'
-      const useBinaryStream = isMobile && params.capabilities?.terminalBinaryStream === 1
+      const useBinaryStream = params.capabilities?.terminalBinaryStream === 1 && Boolean(sendBinary)
 
       // Why: the left pane's PTY spawns asynchronously after the tab is created.
       // Mobile clients that subscribe before the PTY is ready would get a bare
@@ -515,7 +1010,7 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
 
       const ptyId = leaf.ptyId
       const clientId = params.client?.id
-      if (!isMobile) {
+      if (!useBinaryStream) {
         const read = await runtime.readTerminal(params.terminal)
         const serialized = await serializeBudgetedMobileSnapshot(runtime, ptyId, false)
         const size = runtime.getTerminalSize(ptyId)
@@ -532,11 +1027,19 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           seq
         })
 
+        // Why: desktop can have both a hidden automation watcher and a visible
+        // pane subscribed to the same terminal. Key by client when provided so
+        // one stream cannot evict the other.
+        const subscriptionId = clientId ? `${params.terminal}:${clientId}` : params.terminal
         await new Promise<void>((resolve) => {
+          const outputBatcher = createTerminalOutputBatcher((chunk) => {
+            emit({ type: 'data', chunk })
+          })
           const unsubscribeData = runtime.subscribeToTerminalData(ptyId, (data) => {
-            emit({ type: 'data', chunk: data })
+            outputBatcher.push(data)
           })
           const unsubscribeFit = runtime.subscribeToFitOverrideChanges(ptyId, (event) => {
+            outputBatcher.flush()
             emit({
               type: 'fit-override-changed',
               mode: event.mode,
@@ -545,8 +1048,10 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             })
           })
           runtime.registerSubscriptionCleanup(
-            params.terminal,
+            subscriptionId,
             () => {
+              outputBatcher.flush()
+              outputBatcher.dispose()
               unsubscribeData()
               unsubscribeFit()
               emit({ type: 'end' })
@@ -554,6 +1059,10 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             },
             connectionId
           )
+          void runtime
+            .waitForTerminal(params.terminal, { condition: 'exit' })
+            .then(() => runtime.cleanupSubscription(subscriptionId))
+            .catch(() => runtime.cleanupSubscription(subscriptionId))
         })
         return
       }
@@ -563,23 +1072,30 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       let closed = false
       let buffering = true
       const pendingOutput: string[] = []
+      let pendingOutputChars = 0
       let unsubscribeData = (): void => {}
       let unsubscribeResize = (): void => {}
       let unsubscribeFit = (): void => {}
+      let unregisterBinaryHandler = (): void => {}
+      let outputBatcher: ReturnType<typeof createTerminalOutputBatcher> | null = null
       let resolveStream = (): void => {}
       const streamClosed = new Promise<void>((resolve) => {
         resolveStream = resolve
       })
       // Why: register cleanup before any mobile-fit or snapshot await. A phone
-      // can disconnect mid-subscribe; cleanup must still remove mobile presence.
+      // can disconnect mid-subscribe; cleanup must still remove mobile
+      // presence. Client-scoped ids also allow parallel desktop subscribers.
       const subscriptionId = clientId ? `${params.terminal}:${clientId}` : params.terminal
       runtime.registerSubscriptionCleanup(
         subscriptionId,
         () => {
+          outputBatcher?.flush()
+          outputBatcher?.dispose()
           closed = true
           unsubscribeData()
           unsubscribeResize()
           unsubscribeFit()
+          unregisterBinaryHandler()
           if (isMobile && clientId) {
             runtime.handleMobileUnsubscribe(ptyId, clientId)
           }
@@ -588,6 +1104,10 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         },
         connectionId
       )
+      void runtime
+        .waitForTerminal(params.terminal, { condition: 'exit' })
+        .then(() => runtime.cleanupSubscription(subscriptionId))
+        .catch(() => runtime.cleanupSubscription(subscriptionId))
       const sendFrame = (
         opcode: TerminalStreamOpcode,
         payload: Uint8Array<ArrayBufferLike> = new Uint8Array()
@@ -597,6 +1117,52 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         }
         sendBinary(encodeTerminalStreamFrame({ opcode, streamId, seq: cursor++, payload }))
       }
+      outputBatcher = createTerminalOutputBatcher((data) => {
+        sendFrame(TerminalStreamOpcode.Output, encodeTerminalStreamText(data))
+      })
+      unregisterBinaryHandler =
+        registerBinaryStreamHandler?.(streamId, (frame) => {
+          if (closed) {
+            return
+          }
+          if (frame.opcode === TerminalStreamOpcode.Input) {
+            const text = decodeTerminalStreamText(frame.payload)
+            if (!text) {
+              return
+            }
+            if (isTerminalInputLockedForClient(runtime, ptyId, params.client)) {
+              return
+            }
+            void runtime
+              .sendTerminal(params.terminal, { text, enter: false, interrupt: false })
+              .then(async () => {
+                if (isMobile && clientId) {
+                  await runtime.mobileTookFloor(ptyId, clientId)
+                }
+              })
+              .catch(() => {})
+            return
+          }
+          if (frame.opcode === TerminalStreamOpcode.Resize && params.client) {
+            const viewport = decodeTerminalStreamJson<{ cols?: unknown; rows?: unknown }>(
+              frame.payload
+            )
+            if (
+              !viewport ||
+              typeof viewport.cols !== 'number' ||
+              typeof viewport.rows !== 'number'
+            ) {
+              return
+            }
+            void updateViewportForClient(
+              runtime,
+              ptyId,
+              params.client,
+              { cols: viewport.cols, rows: viewport.rows },
+              'desktop'
+            ).catch(() => {})
+          }
+        }) ?? (() => {})
       // Server-side auto-fit: resize PTY to phone dims before serializing scrollback
       try {
         if (isMobile && clientId) {
@@ -612,20 +1178,20 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
           }
           if (buffering) {
             pendingOutput.push(data)
+            pendingOutputChars += data.length
+            while (
+              pendingOutputChars > TERMINAL_MULTIPLEX_PENDING_MAX_CHARS &&
+              pendingOutput.length > 0
+            ) {
+              pendingOutputChars -= pendingOutput.shift()?.length ?? 0
+            }
             return
           }
-          sendBinary!(
-            encodeTerminalStreamFrame({
-              opcode: TerminalStreamOpcode.Output,
-              streamId,
-              seq: cursor++,
-              payload: encodeTerminalStreamText(data)
-            })
-          )
+          outputBatcher?.push(data)
         })
 
         const read = await runtime.readTerminal(params.terminal)
-        const serialized = await serializeBudgetedMobileSnapshot(runtime, ptyId, true)
+        const serialized = await serializeBudgetedMobileSnapshot(runtime, ptyId, isMobile)
         if (closed) {
           return
         }
@@ -667,20 +1233,16 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         })
         buffering = false
         for (const item of pendingOutput.splice(0)) {
-          sendBinary!(
-            encodeTerminalStreamFrame({
-              opcode: TerminalStreamOpcode.Output,
-              streamId,
-              seq: cursor++,
-              payload: encodeTerminalStreamText(item)
-            })
-          )
+          outputBatcher.push(item)
         }
+        pendingOutputChars = 0
+        outputBatcher.flush()
 
         unsubscribeResize = runtime.subscribeToTerminalResize(ptyId, (event) => {
           // Why: true PTY geometry changes should be followed by the TUI's
           // redraw output, not a full scrollback replay. The client resizes
           // xterm geometry and consumes subsequent live output on this stream.
+          outputBatcher?.flush()
           sendFrame(
             TerminalStreamOpcode.Resized,
             encodeTerminalStreamJson({
diff --git a/src/main/runtime/rpc/methods/worktree.test.ts b/src/main/runtime/rpc/methods/worktree.test.ts
new file mode 100644
index 00000000000..e0da750b5c4
--- /dev/null
+++ b/src/main/runtime/rpc/methods/worktree.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { WORKTREE_METHODS } from './worktree'
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('worktree RPC methods', () => {
+  it('routes create options to the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      createManagedWorktree: vi.fn().mockResolvedValue({ worktree: { id: 'wt-1' } })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: WORKTREE_METHODS })
+
+    await dispatcher.dispatch(
+      makeRequest('worktree.create', {
+        repo: 'repo-1',
+        name: 'feature',
+        baseBranch: 'origin/main',
+        setupDecision: 'skip',
+        displayName: 'Feature title',
+        linkedIssue: 123,
+        linkedPR: 456,
+        sparseCheckout: { directories: ['src'], presetId: 'preset-1' },
+        pushTarget: { remoteName: 'fork', branchName: 'feature' }
+      })
+    )
+
+    expect(runtime.createManagedWorktree).toHaveBeenCalledWith({
+      repoSelector: 'repo-1',
+      name: 'feature',
+      baseBranch: 'origin/main',
+      linkedIssue: 123,
+      linkedPR: 456,
+      comment: undefined,
+      displayName: 'Feature title',
+      sparseCheckout: { directories: ['src'], presetId: 'preset-1' },
+      pushTarget: { remoteName: 'fork', branchName: 'feature' },
+      runHooks: false,
+      activate: false,
+      setupDecision: 'skip',
+      startup: undefined
+    })
+  })
+
+  it('persists smart sort order on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      persistManagedWorktreeSortOrder: vi.fn().mockReturnValue({ updated: 2 })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: WORKTREE_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('worktree.persistSortOrder', { orderedIds: ['wt-1', 'wt-2'] })
+    )
+
+    expect(runtime.persistManagedWorktreeSortOrder).toHaveBeenCalledWith(['wt-1', 'wt-2'])
+    expect(response).toMatchObject({ ok: true, result: { updated: 2 } })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/worktree.ts b/src/main/runtime/rpc/methods/worktree.ts
index e3358fa731b..0dd7c5384ba 100644
--- a/src/main/runtime/rpc/methods/worktree.ts
+++ b/src/main/runtime/rpc/methods/worktree.ts
@@ -3,9 +3,11 @@ import { defineMethod, type RpcMethod } from '../core'
 import {
   OptionalBoolean,
   OptionalFiniteNumber,
+  OptionalPlainString,
   OptionalString,
   TriStateLinkedIssue
 } from '../schemas'
+import { isTuiAgent } from '../../../../shared/tui-agent-config'
 
 const WorktreeListParams = z.object({
   repo: OptionalString,
@@ -16,6 +18,10 @@ const WorktreePsParams = z.object({
   limit: OptionalFiniteNumber
 })
 
+const WorktreeSortOrder = z.object({
+  orderedIds: z.array(z.string())
+})
+
 const WorktreeSelector = z.object({
   worktree: z
     .unknown()
@@ -31,7 +37,22 @@ const WorktreeCreate = z.object({
   name: OptionalString,
   baseBranch: OptionalString,
   linkedIssue: TriStateLinkedIssue,
+  linkedPR: TriStateLinkedIssue,
   comment: OptionalString,
+  displayName: OptionalString,
+  sparseCheckout: z
+    .object({
+      directories: z.array(z.string()),
+      presetId: OptionalString
+    })
+    .optional(),
+  pushTarget: z
+    .object({
+      remoteName: z.string(),
+      branchName: z.string(),
+      remoteUrl: OptionalString
+    })
+    .optional(),
   runHooks: OptionalBoolean,
   activate: OptionalBoolean,
   setupDecision: z
@@ -43,14 +64,39 @@ const WorktreeCreate = z.object({
     .optional(),
   // Why: mobile clients pass a startup command (e.g. 'claude') so the first
   // terminal pane launches the selected agent instead of an idle shell.
-  startupCommand: OptionalString
+  startupCommand: OptionalString,
+  createdWithAgent: z
+    .unknown()
+    .transform((value) => (isTuiAgent(value) ? value : undefined))
+    .optional()
 })
 
 const WorktreeSet = WorktreeSelector.extend({
   displayName: OptionalString,
+  // Why: empty comments are meaningful metadata updates, so use the plain
+  // string parser instead of OptionalString's empty-as-undefined behavior.
+  comment: OptionalPlainString,
   linkedIssue: TriStateLinkedIssue,
-  comment: OptionalString,
-  isPinned: OptionalBoolean
+  linkedPR: TriStateLinkedIssue,
+  linkedLinearIssue: z.union([z.string(), z.null()]).optional(),
+  isArchived: OptionalBoolean,
+  isUnread: OptionalBoolean,
+  isPinned: OptionalBoolean,
+  sortOrder: OptionalFiniteNumber,
+  lastActivityAt: OptionalFiniteNumber,
+  createdAt: OptionalFiniteNumber,
+  sparseDirectories: z.array(z.string()).optional(),
+  sparseBaseRef: OptionalString,
+  sparsePresetId: OptionalString,
+  baseRef: OptionalString,
+  pushTarget: z
+    .object({
+      remoteName: z.string(),
+      branchName: z.string(),
+      remoteUrl: OptionalString
+    })
+    .optional(),
+  diffComments: z.array(z.unknown()).optional()
 })
 
 const WorktreeRemove = WorktreeSelector.extend({
@@ -58,6 +104,19 @@ const WorktreeRemove = WorktreeSelector.extend({
   runHooks: OptionalBoolean
 })
 
+const WorktreeResolvePrBase = z.object({
+  repo: z
+    .unknown()
+    .transform((v) => (typeof v === 'string' ? v : ''))
+    .pipe(z.string().min(1, 'Missing repo selector')),
+  prNumber: z
+    .unknown()
+    .transform((v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0))
+    .pipe(z.number().int().positive('Missing PR number')),
+  headRefName: OptionalString,
+  isCrossRepository: OptionalBoolean
+})
+
 export const WORKTREE_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'worktree.ps',
@@ -95,10 +154,15 @@ export const WORKTREE_METHODS: RpcMethod[] = [
         name: params.name ?? '',
         baseBranch: params.baseBranch,
         linkedIssue: params.linkedIssue,
+        linkedPR: params.linkedPR,
         comment: params.comment,
+        displayName: params.displayName,
+        sparseCheckout: params.sparseCheckout,
+        pushTarget: params.pushTarget,
         runHooks: params.runHooks === true,
         activate: params.activate === true,
         setupDecision: params.setupDecision,
+        createdWithAgent: params.createdWithAgent,
         startup: params.startupCommand ? { command: params.startupCommand } : undefined
       })
   }),
@@ -109,11 +173,41 @@ export const WORKTREE_METHODS: RpcMethod[] = [
       worktree: await runtime.updateManagedWorktreeMeta(params.worktree, {
         displayName: params.displayName,
         linkedIssue: params.linkedIssue,
+        linkedPR: params.linkedPR,
+        linkedLinearIssue: params.linkedLinearIssue,
         comment: params.comment,
-        isPinned: params.isPinned
-      })
+        isArchived: params.isArchived,
+        isUnread: params.isUnread,
+        isPinned: params.isPinned,
+        sortOrder: params.sortOrder,
+        lastActivityAt: params.lastActivityAt,
+        createdAt: params.createdAt,
+        sparseDirectories: params.sparseDirectories,
+        sparseBaseRef: params.sparseBaseRef,
+        sparsePresetId: params.sparsePresetId,
+        baseRef: params.baseRef,
+        pushTarget: params.pushTarget,
+        diffComments: params.diffComments
+      } as Parameters<typeof runtime.updateManagedWorktreeMeta>[1])
     })
   }),
+  defineMethod({
+    name: 'worktree.persistSortOrder',
+    params: WorktreeSortOrder,
+    handler: async (params, { runtime }) =>
+      runtime.persistManagedWorktreeSortOrder(params.orderedIds)
+  }),
+  defineMethod({
+    name: 'worktree.resolvePrBase',
+    params: WorktreeResolvePrBase,
+    handler: async (params, { runtime }) =>
+      runtime.resolveManagedPrBase({
+        repoId: params.repo,
+        prNumber: params.prNumber,
+        headRefName: params.headRefName,
+        isCrossRepository: params.isCrossRepository
+      })
+  }),
   defineMethod({
     name: 'worktree.rm',
     params: WorktreeRemove,
diff --git a/src/main/runtime/rpc/streaming.test.ts b/src/main/runtime/rpc/streaming.test.ts
index 7afa5ae7553..abc9ab20372 100644
--- a/src/main/runtime/rpc/streaming.test.ts
+++ b/src/main/runtime/rpc/streaming.test.ts
@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { RpcDispatcher } from './dispatcher'
 import { defineMethod, defineStreamingMethod, type RpcRequest } from './core'
 import type { OrcaRuntimeService } from '../orca-runtime'
+import { TERMINAL_METHODS } from './methods/terminal'
+import type { RuntimeTerminalWait } from '../../../shared/runtime-types'
 
 function stubRuntime(overrides: Partial<OrcaRuntimeService> = {}): OrcaRuntimeService {
   return {
@@ -263,4 +265,57 @@ describe('RpcDispatcher streaming', () => {
       error: { code: 'runtime_error' }
     })
   })
+
+  it('ends terminal.subscribe when the backing terminal exits', async () => {
+    const messages: string[] = []
+    let resolveExit!: () => void
+    const cleanups = new Map<string, () => void>()
+    const runtime = stubRuntime({
+      resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+      readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+      serializeTerminalBuffer: vi.fn().mockResolvedValue(null),
+      getTerminalSize: vi.fn().mockReturnValue({ cols: 80, rows: 24 }),
+      getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+      getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+      subscribeToTerminalData: vi.fn().mockReturnValue(vi.fn()),
+      subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+      registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+        cleanups.set(id, cleanup)
+      }),
+      cleanupSubscription: vi.fn((id: string) => {
+        const cleanup = cleanups.get(id)
+        cleanups.delete(id)
+        cleanup?.()
+      }),
+      waitForTerminal: vi.fn(
+        () =>
+          new Promise<RuntimeTerminalWait>((resolve) => {
+            resolveExit = () =>
+              resolve({
+                handle: 'terminal-1',
+                condition: 'exit',
+                satisfied: true,
+                status: 'exited',
+                exitCode: 0
+              })
+          })
+      )
+    })
+    const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+    const dispatchPromise = dispatcher.dispatchStreaming(
+      makeRequest('terminal.subscribe', {
+        terminal: 'terminal-1',
+        client: { id: 'desktop-1', type: 'desktop' }
+      }),
+      (msg) => messages.push(msg)
+    )
+
+    await vi.waitFor(() => expect(cleanups.has('terminal-1:desktop-1')).toBe(true))
+    resolveExit()
+    await dispatchPromise
+
+    expect(messages.some((msg) => JSON.parse(msg).result?.type === 'end')).toBe(true)
+    expect(runtime.cleanupSubscription).toHaveBeenCalledWith('terminal-1:desktop-1')
+  })
 })
diff --git a/src/main/runtime/rpc/terminal-multiplex.test.ts b/src/main/runtime/rpc/terminal-multiplex.test.ts
new file mode 100644
index 00000000000..1f066cca372
--- /dev/null
+++ b/src/main/runtime/rpc/terminal-multiplex.test.ts
@@ -0,0 +1,395 @@
+/* oxlint-disable max-lines -- Why: multiplex transport tests share a live dispatcher harness; splitting it would duplicate stream setup and weaken race coverage. */
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from './dispatcher'
+import type { RpcRequest } from './core'
+import type { OrcaRuntimeService } from '../orca-runtime'
+import { TERMINAL_METHODS } from './methods/terminal'
+import type { RuntimeTerminalWait } from '../../../shared/runtime-types'
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamJson,
+  decodeTerminalStreamText,
+  encodeTerminalStreamFrame,
+  encodeTerminalStreamJson,
+  encodeTerminalStreamText
+} from '../../../shared/terminal-stream-protocol'
+
+function stubRuntime(overrides: Partial<OrcaRuntimeService> = {}): OrcaRuntimeService {
+  return {
+    getRuntimeId: () => 'test-runtime',
+    ...overrides
+  } as OrcaRuntimeService
+}
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('terminal multiplex RPC', () => {
+  it('multiplexes terminal streams and routes desktop resize to the source PTY', async () => {
+    vi.useFakeTimers()
+    try {
+      const messages: string[] = []
+      const binaryFrames: Uint8Array<ArrayBufferLike>[] = []
+      const handlers = new Map<
+        number,
+        (frame: NonNullable<ReturnType<typeof decodeTerminalStreamFrame>>) => void
+      >()
+      const cleanups = new Map<string, () => void>()
+      const dataListenerRef: { current?: (data: string) => void } = {}
+      const runtime = stubRuntime({
+        resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+        readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+        serializeTerminalBuffer: vi.fn().mockResolvedValue({
+          data: 'snapshot',
+          cols: 120,
+          rows: 40
+        }),
+        getTerminalSize: vi.fn().mockReturnValue({ cols: 120, rows: 40 }),
+        getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+        getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+        subscribeToTerminalData: vi.fn((_: string, listener: (data: string) => void) => {
+          dataListenerRef.current = listener
+          return vi.fn()
+        }),
+        subscribeToTerminalResize: vi.fn().mockReturnValue(vi.fn()),
+        subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+        subscribeToDriverChanges: vi.fn().mockReturnValue(vi.fn()),
+        getTerminalFitOverride: vi.fn().mockReturnValue(null),
+        getDriver: vi.fn().mockReturnValue({ kind: 'idle' }),
+        registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+          cleanups.set(id, cleanup)
+        }),
+        cleanupSubscription: vi.fn((id: string) => {
+          const cleanup = cleanups.get(id)
+          cleanups.delete(id)
+          cleanup?.()
+        }),
+        waitForTerminal: vi.fn(() => new Promise<RuntimeTerminalWait>(() => {})),
+        sendTerminal: vi.fn().mockResolvedValue({ accepted: true }),
+        updateDesktopViewport: vi.fn().mockResolvedValue(true)
+      })
+      const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+      const dispatchPromise = dispatcher.dispatchStreaming(
+        makeRequest('terminal.multiplex', {}),
+        (msg) => messages.push(msg),
+        {
+          connectionId: 'conn-1',
+          sendBinary: (bytes) => binaryFrames.push(bytes),
+          registerBinaryStreamHandler: (streamId, handler) => {
+            handlers.set(streamId, handler)
+            return () => handlers.delete(streamId)
+          }
+        }
+      )
+
+      await vi.waitFor(() =>
+        expect(messages.some((msg) => JSON.parse(msg).result?.type === 'ready')).toBe(true)
+      )
+      expect(handlers.has(0)).toBe(true)
+
+      handlers.get(0)?.(
+        decodeTerminalStreamFrame(
+          encodeTerminalStreamFrame({
+            opcode: TerminalStreamOpcode.Subscribe,
+            streamId: 0,
+            seq: 1,
+            payload: encodeTerminalStreamJson({
+              streamId: 5,
+              terminal: 'terminal-1',
+              client: { id: 'desktop-1', type: 'desktop' },
+              viewport: { cols: 300, rows: 150 }
+            })
+          })
+        )!
+      )
+
+      await vi.waitFor(() =>
+        expect(messages.some((msg) => JSON.parse(msg).result?.type === 'subscribed')).toBe(true)
+      )
+      expect(messages.map((msg) => JSON.parse(msg).result)).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: 'fit-override-changed',
+            streamId: 5,
+            mode: 'desktop-fit'
+          }),
+          expect.objectContaining({
+            type: 'driver-changed',
+            streamId: 5,
+            driver: { kind: 'idle' }
+          })
+        ])
+      )
+      expect(runtime.updateDesktopViewport).toHaveBeenCalledWith('pty-1', {
+        cols: 300,
+        rows: 150
+      })
+      expect(handlers.has(5)).toBe(true)
+
+      dataListenerRef.current?.('a')
+      dataListenerRef.current?.('b')
+      await vi.runOnlyPendingTimersAsync()
+
+      const outputFrames = binaryFrames
+        .map((frame) => decodeTerminalStreamFrame(frame))
+        .filter((frame) => frame?.opcode === TerminalStreamOpcode.Output)
+      expect(outputFrames).toHaveLength(1)
+      expect(outputFrames[0]?.streamId).toBe(5)
+      expect(outputFrames[0] ? decodeTerminalStreamText(outputFrames[0].payload) : '').toBe('ab')
+
+      handlers.get(5)?.(
+        decodeTerminalStreamFrame(
+          encodeTerminalStreamFrame({
+            opcode: TerminalStreamOpcode.Input,
+            streamId: 5,
+            seq: 2,
+            payload: encodeTerminalStreamText('ls\r')
+          })
+        )!
+      )
+      await vi.waitFor(() =>
+        expect(runtime.sendTerminal).toHaveBeenCalledWith('terminal-1', {
+          text: 'ls\r',
+          enter: false,
+          interrupt: false
+        })
+      )
+
+      handlers.get(5)?.(
+        decodeTerminalStreamFrame(
+          encodeTerminalStreamFrame({
+            opcode: TerminalStreamOpcode.Resize,
+            streamId: 5,
+            seq: 3,
+            payload: encodeTerminalStreamJson({ cols: 100, rows: 30 })
+          })
+        )!
+      )
+      await vi.waitFor(() =>
+        expect(runtime.updateDesktopViewport).toHaveBeenLastCalledWith('pty-1', {
+          cols: 100,
+          rows: 30
+        })
+      )
+
+      const snapshotStartFrame = binaryFrames
+        .map((frame) => decodeTerminalStreamFrame(frame))
+        .find((frame) => frame?.opcode === TerminalStreamOpcode.SnapshotStart)
+      expect(
+        snapshotStartFrame && decodeTerminalStreamJson(snapshotStartFrame.payload)
+      ).toMatchObject({
+        cols: 120,
+        rows: 40
+      })
+
+      runtime.cleanupSubscription('terminal-multiplex:conn-1')
+      await dispatchPromise
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('drops desktop multiplex input while a mobile client owns the terminal floor', async () => {
+    const messages: string[] = []
+    const handlers = new Map<
+      number,
+      (frame: NonNullable<ReturnType<typeof decodeTerminalStreamFrame>>) => void
+    >()
+    const cleanups = new Map<string, () => void>()
+    const runtime = stubRuntime({
+      resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+      readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+      serializeTerminalBuffer: vi.fn().mockResolvedValue(null),
+      getTerminalSize: vi.fn().mockReturnValue({ cols: 120, rows: 40 }),
+      getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+      getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+      subscribeToTerminalData: vi.fn().mockReturnValue(vi.fn()),
+      subscribeToTerminalResize: vi.fn().mockReturnValue(vi.fn()),
+      subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+      subscribeToDriverChanges: vi.fn().mockReturnValue(vi.fn()),
+      getTerminalFitOverride: vi.fn().mockReturnValue({
+        mode: 'mobile-fit',
+        cols: 49,
+        rows: 20
+      }),
+      getDriver: vi.fn().mockReturnValue({ kind: 'mobile', clientId: 'phone-1' }),
+      registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+        cleanups.set(id, cleanup)
+      }),
+      waitForTerminal: vi.fn(() => new Promise<RuntimeTerminalWait>(() => {})),
+      sendTerminal: vi.fn().mockResolvedValue({ accepted: true }),
+      updateDesktopViewport: vi.fn().mockResolvedValue(true)
+    })
+    const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+    const dispatchPromise = dispatcher.dispatchStreaming(
+      makeRequest('terminal.multiplex', {}),
+      (msg) => messages.push(msg),
+      {
+        connectionId: 'conn-locked',
+        sendBinary: vi.fn(),
+        registerBinaryStreamHandler: (streamId, handler) => {
+          handlers.set(streamId, handler)
+          return () => handlers.delete(streamId)
+        }
+      }
+    )
+
+    await vi.waitFor(() =>
+      expect(messages.some((msg) => JSON.parse(msg).result?.type === 'ready')).toBe(true)
+    )
+    handlers.get(0)?.(
+      decodeTerminalStreamFrame(
+        encodeTerminalStreamFrame({
+          opcode: TerminalStreamOpcode.Subscribe,
+          streamId: 0,
+          seq: 1,
+          payload: encodeTerminalStreamJson({
+            streamId: 7,
+            terminal: 'terminal-1',
+            client: { id: 'desktop-1', type: 'desktop' },
+            viewport: { cols: 120, rows: 40 }
+          })
+        })
+      )!
+    )
+    await vi.waitFor(() => expect(handlers.has(7)).toBe(true))
+    await vi.waitFor(() =>
+      expect(messages.map((msg) => JSON.parse(msg).result)).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: 'fit-override-changed',
+            streamId: 7,
+            mode: 'mobile-fit',
+            cols: 49,
+            rows: 20
+          }),
+          expect.objectContaining({
+            type: 'driver-changed',
+            streamId: 7,
+            driver: { kind: 'mobile', clientId: 'phone-1' }
+          })
+        ])
+      )
+    )
+
+    handlers.get(7)?.(
+      decodeTerminalStreamFrame(
+        encodeTerminalStreamFrame({
+          opcode: TerminalStreamOpcode.Input,
+          streamId: 7,
+          seq: 2,
+          payload: encodeTerminalStreamText('typed while locked')
+        })
+      )!
+    )
+
+    expect(runtime.sendTerminal).not.toHaveBeenCalled()
+    cleanups.get('terminal-multiplex:conn-locked')?.()
+    await dispatchPromise
+  })
+
+  it('bounds live output queued while a multiplex snapshot is loading', async () => {
+    vi.useFakeTimers()
+    try {
+      const messages: string[] = []
+      const binaryFrames: Uint8Array<ArrayBufferLike>[] = []
+      const handlers = new Map<
+        number,
+        (frame: NonNullable<ReturnType<typeof decodeTerminalStreamFrame>>) => void
+      >()
+      const cleanups = new Map<string, () => void>()
+      const dataListenerRef: { current?: (data: string) => void } = {}
+      let resolveSnapshot: (value: { data: string; cols: number; rows: number }) => void = () => {}
+      const runtime = stubRuntime({
+        resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+        readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+        serializeTerminalBuffer: vi.fn(
+          () =>
+            new Promise<{ data: string; cols: number; rows: number }>((resolve) => {
+              resolveSnapshot = resolve
+            })
+        ),
+        getTerminalSize: vi.fn().mockReturnValue({ cols: 120, rows: 40 }),
+        getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+        getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+        subscribeToTerminalData: vi.fn((_: string, listener: (data: string) => void) => {
+          dataListenerRef.current = listener
+          return vi.fn()
+        }),
+        subscribeToTerminalResize: vi.fn().mockReturnValue(vi.fn()),
+        subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+        subscribeToDriverChanges: vi.fn().mockReturnValue(vi.fn()),
+        getTerminalFitOverride: vi.fn().mockReturnValue(null),
+        getDriver: vi.fn().mockReturnValue({ kind: 'idle' }),
+        registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+          cleanups.set(id, cleanup)
+        }),
+        waitForTerminal: vi.fn(() => new Promise<RuntimeTerminalWait>(() => {})),
+        sendTerminal: vi.fn().mockResolvedValue({ accepted: true }),
+        updateDesktopViewport: vi.fn().mockResolvedValue(true)
+      })
+      const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+      const dispatchPromise = dispatcher.dispatchStreaming(
+        makeRequest('terminal.multiplex', {}),
+        (msg) => messages.push(msg),
+        {
+          connectionId: 'conn-buffered',
+          sendBinary: (bytes) => binaryFrames.push(bytes),
+          registerBinaryStreamHandler: (streamId, handler) => {
+            handlers.set(streamId, handler)
+            return () => handlers.delete(streamId)
+          }
+        }
+      )
+
+      await vi.waitFor(() =>
+        expect(messages.some((msg) => JSON.parse(msg).result?.type === 'ready')).toBe(true)
+      )
+      handlers.get(0)?.(
+        decodeTerminalStreamFrame(
+          encodeTerminalStreamFrame({
+            opcode: TerminalStreamOpcode.Subscribe,
+            streamId: 0,
+            seq: 1,
+            payload: encodeTerminalStreamJson({
+              streamId: 9,
+              terminal: 'terminal-1',
+              client: { id: 'desktop-1', type: 'desktop' },
+              viewport: { cols: 120, rows: 40 }
+            })
+          })
+        )!
+      )
+      await vi.waitFor(() => expect(dataListenerRef.current).toBeDefined())
+
+      for (let index = 0; index < 400; index += 1) {
+        dataListenerRef.current?.(`${String(index).padStart(3, '0')}${'x'.repeat(1021)}`)
+      }
+      await vi.waitFor(() => expect(runtime.serializeTerminalBuffer).toHaveBeenCalled())
+      resolveSnapshot({ data: '', cols: 120, rows: 40 })
+      await vi.waitFor(() =>
+        expect(messages.some((msg) => JSON.parse(msg).result?.type === 'subscribed')).toBe(true)
+      )
+      await vi.runOnlyPendingTimersAsync()
+
+      const output = binaryFrames
+        .map((frame) => decodeTerminalStreamFrame(frame))
+        .filter((frame) => frame?.opcode === TerminalStreamOpcode.Output)
+        .map((frame) => (frame ? decodeTerminalStreamText(frame.payload) : ''))
+        .join('')
+      expect(output.length).toBeLessThanOrEqual(256 * 1024)
+      expect(output).not.toContain('000')
+      expect(output).toContain('399')
+
+      cleanups.get('terminal-multiplex:conn-buffered')?.()
+      await dispatchPromise
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
diff --git a/src/main/runtime/rpc/terminal-output-batching.test.ts b/src/main/runtime/rpc/terminal-output-batching.test.ts
new file mode 100644
index 00000000000..11e2b7476c8
--- /dev/null
+++ b/src/main/runtime/rpc/terminal-output-batching.test.ts
@@ -0,0 +1,249 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from './dispatcher'
+import type { RpcRequest } from './core'
+import type { OrcaRuntimeService } from '../orca-runtime'
+import { TERMINAL_METHODS } from './methods/terminal'
+import type { RuntimeTerminalWait } from '../../../shared/runtime-types'
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamText,
+  encodeTerminalStreamFrame,
+  encodeTerminalStreamText
+} from '../../../shared/terminal-stream-protocol'
+
+function stubRuntime(overrides: Partial<OrcaRuntimeService> = {}): OrcaRuntimeService {
+  return {
+    getRuntimeId: () => 'test-runtime',
+    ...overrides
+  } as OrcaRuntimeService
+}
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('terminal output batching', () => {
+  it('coalesces desktop terminal output bursts before emitting stream data', async () => {
+    vi.useFakeTimers()
+    try {
+      const messages: string[] = []
+      const cleanups = new Map<string, () => void>()
+      const dataListenerRef: { current?: (data: string) => void } = {}
+      const runtime = stubRuntime({
+        resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+        readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+        serializeTerminalBuffer: vi.fn().mockResolvedValue(null),
+        getTerminalSize: vi.fn().mockReturnValue({ cols: 80, rows: 24 }),
+        getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+        getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+        subscribeToTerminalData: vi.fn((_: string, listener: (data: string) => void) => {
+          dataListenerRef.current = listener
+          return vi.fn()
+        }),
+        subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+        registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+          cleanups.set(id, cleanup)
+        }),
+        cleanupSubscription: vi.fn((id: string) => {
+          const cleanup = cleanups.get(id)
+          cleanups.delete(id)
+          cleanup?.()
+        }),
+        waitForTerminal: vi.fn(() => new Promise<RuntimeTerminalWait>(() => {}))
+      })
+      const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+      const dispatchPromise = dispatcher.dispatchStreaming(
+        makeRequest('terminal.subscribe', {
+          terminal: 'terminal-1',
+          client: { id: 'desktop-1', type: 'desktop' }
+        }),
+        (msg) => messages.push(msg)
+      )
+
+      await vi.waitFor(() => expect(dataListenerRef.current).toBeDefined())
+      const emitData = dataListenerRef.current
+      if (!emitData) {
+        throw new Error('missing terminal data listener')
+      }
+      emitData('a')
+      emitData('b')
+
+      expect(messages.map((msg) => JSON.parse(msg).result?.type)).not.toContain('data')
+
+      await vi.runOnlyPendingTimersAsync()
+
+      const dataMessages = messages
+        .map((msg) => JSON.parse(msg))
+        .filter((message) => message.result?.type === 'data')
+      expect(dataMessages).toHaveLength(1)
+      expect(dataMessages[0]).toMatchObject({ result: { type: 'data', chunk: 'ab' } })
+
+      runtime.cleanupSubscription('terminal-1:desktop-1')
+      await dispatchPromise
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('streams desktop terminal output as coalesced binary frames when requested', async () => {
+    vi.useFakeTimers()
+    try {
+      const messages: string[] = []
+      const binaryFrames: Uint8Array<ArrayBufferLike>[] = []
+      const cleanups = new Map<string, () => void>()
+      const dataListenerRef: { current?: (data: string) => void } = {}
+      const runtime = stubRuntime({
+        resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+        readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+        serializeTerminalBuffer: vi.fn().mockResolvedValue({
+          data: 'snapshot',
+          cols: 80,
+          rows: 24
+        }),
+        getTerminalSize: vi.fn().mockReturnValue({ cols: 80, rows: 24 }),
+        getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+        getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+        subscribeToTerminalData: vi.fn((_: string, listener: (data: string) => void) => {
+          dataListenerRef.current = listener
+          return vi.fn()
+        }),
+        subscribeToTerminalResize: vi.fn().mockReturnValue(vi.fn()),
+        subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+        registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+          cleanups.set(id, cleanup)
+        }),
+        cleanupSubscription: vi.fn((id: string) => {
+          const cleanup = cleanups.get(id)
+          cleanups.delete(id)
+          cleanup?.()
+        }),
+        waitForTerminal: vi.fn(() => new Promise<RuntimeTerminalWait>(() => {})),
+        sendTerminal: vi.fn().mockResolvedValue({ accepted: true }),
+        updateMobileViewport: vi.fn().mockResolvedValue(false)
+      })
+      const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+      const dispatchPromise = dispatcher.dispatchStreaming(
+        makeRequest('terminal.subscribe', {
+          terminal: 'terminal-1',
+          client: { id: 'desktop-1', type: 'desktop' },
+          capabilities: { terminalBinaryStream: 1 }
+        }),
+        (msg) => messages.push(msg),
+        {
+          connectionId: 'conn-1',
+          sendBinary: (bytes) => binaryFrames.push(bytes)
+        }
+      )
+
+      await vi.waitFor(() =>
+        expect(messages.some((msg) => JSON.parse(msg).result?.type === 'subscribed')).toBe(true)
+      )
+      const subscribed = messages
+        .map((msg) => JSON.parse(msg))
+        .find((msg) => msg.result?.type === 'subscribed')
+      expect(subscribed?.result).toMatchObject({ type: 'subscribed', streamId: expect.any(Number) })
+      await vi.waitFor(() => expect(dataListenerRef.current).toBeDefined())
+
+      const emitData = dataListenerRef.current
+      if (!emitData) {
+        throw new Error('missing terminal data listener')
+      }
+      emitData('a')
+      emitData('b')
+
+      expect(messages.map((msg) => JSON.parse(msg).result?.type)).not.toContain('data')
+
+      await vi.runOnlyPendingTimersAsync()
+
+      const outputFrames = binaryFrames
+        .map((frame) => decodeTerminalStreamFrame(frame))
+        .filter((frame) => frame?.opcode === TerminalStreamOpcode.Output)
+      expect(outputFrames).toHaveLength(1)
+      expect(outputFrames[0] ? decodeTerminalStreamText(outputFrames[0].payload) : '').toBe('ab')
+
+      runtime.cleanupSubscription('terminal-1:desktop-1')
+      await dispatchPromise
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('routes binary terminal input frames back to the subscribed PTY', async () => {
+    const handlers = new Map<
+      number,
+      (frame: NonNullable<ReturnType<typeof decodeTerminalStreamFrame>>) => void
+    >()
+    const cleanups = new Map<string, () => void>()
+    const runtime = stubRuntime({
+      resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+      readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+      serializeTerminalBuffer: vi.fn().mockResolvedValue(null),
+      getTerminalSize: vi.fn().mockReturnValue({ cols: 80, rows: 24 }),
+      getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+      getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+      subscribeToTerminalData: vi.fn().mockReturnValue(vi.fn()),
+      subscribeToTerminalResize: vi.fn().mockReturnValue(vi.fn()),
+      subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+      getDriver: vi.fn().mockReturnValue({ kind: 'idle' }),
+      registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+        cleanups.set(id, cleanup)
+      }),
+      cleanupSubscription: vi.fn((id: string) => {
+        cleanups.get(id)?.()
+        cleanups.delete(id)
+      }),
+      waitForTerminal: vi.fn(() => new Promise<RuntimeTerminalWait>(() => {})),
+      sendTerminal: vi.fn().mockResolvedValue({ accepted: true }),
+      updateMobileViewport: vi.fn().mockResolvedValue(false)
+    })
+    const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+    const messages: string[] = []
+
+    const dispatchPromise = dispatcher.dispatchStreaming(
+      makeRequest('terminal.subscribe', {
+        terminal: 'terminal-1',
+        client: { id: 'desktop-1', type: 'desktop' },
+        capabilities: { terminalBinaryStream: 1 }
+      }),
+      (msg) => messages.push(msg),
+      {
+        connectionId: 'conn-1',
+        sendBinary: vi.fn(),
+        registerBinaryStreamHandler: (streamId, handler) => {
+          handlers.set(streamId, handler)
+          return () => handlers.delete(streamId)
+        }
+      }
+    )
+
+    await vi.waitFor(() => {
+      expect(messages.some((msg) => JSON.parse(msg).result?.streamId)).toBe(true)
+    })
+    const streamId = JSON.parse(messages.find((msg) => JSON.parse(msg).result?.streamId)!).result
+      .streamId as number
+    handlers.get(streamId)?.(
+      decodeTerminalStreamFrame(
+        encodeTerminalStreamFrame({
+          opcode: TerminalStreamOpcode.Input,
+          streamId,
+          seq: 1,
+          payload: encodeTerminalStreamText('ls\r')
+        })
+      )!
+    )
+
+    await vi.waitFor(() =>
+      expect(runtime.sendTerminal).toHaveBeenCalledWith('terminal-1', {
+        text: 'ls\r',
+        enter: false,
+        interrupt: false
+      })
+    )
+
+    runtime.cleanupSubscription('terminal-1:desktop-1')
+    await dispatchPromise
+  })
+})
diff --git a/src/main/runtime/rpc/terminal-send.test.ts b/src/main/runtime/rpc/terminal-send.test.ts
new file mode 100644
index 00000000000..37e4c503135
--- /dev/null
+++ b/src/main/runtime/rpc/terminal-send.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from './dispatcher'
+import type { RpcRequest } from './core'
+import type { OrcaRuntimeService } from '../orca-runtime'
+import { TERMINAL_METHODS } from './methods/terminal'
+
+function stubRuntime(overrides: Partial<OrcaRuntimeService> = {}): OrcaRuntimeService {
+  return {
+    getRuntimeId: () => 'test-runtime',
+    ...overrides
+  } as OrcaRuntimeService
+}
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('terminal send RPC', () => {
+  it('drops desktop input while a mobile client owns the terminal floor', async () => {
+    const runtime = stubRuntime({
+      resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+      getDriver: vi.fn().mockReturnValue({ kind: 'mobile', clientId: 'mobile-1' }),
+      sendTerminal: vi.fn(),
+      mobileTookFloor: vi.fn()
+    })
+    const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('terminal.send', {
+        terminal: 'terminal-1',
+        text: 'x',
+        client: { id: 'desktop-1', type: 'desktop' }
+      })
+    )
+
+    expect(response.ok).toBe(true)
+    if (!response.ok) {
+      throw new Error(response.error.message)
+    }
+    expect(response.result).toEqual({
+      send: {
+        handle: 'terminal-1',
+        accepted: false,
+        bytesWritten: 0
+      }
+    })
+    expect(runtime.sendTerminal).not.toHaveBeenCalled()
+    expect(runtime.mobileTookFloor).not.toHaveBeenCalled()
+  })
+
+  it('accepts legacy clientless mobile input when the current driver is mobile', async () => {
+    const runtime = stubRuntime({
+      resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+      getDriver: vi.fn().mockReturnValue({ kind: 'mobile', clientId: 'mobile-1' }),
+      sendTerminal: vi.fn().mockResolvedValue({
+        handle: 'terminal-1',
+        accepted: true,
+        bytesWritten: 1
+      }),
+      mobileTookFloor: vi.fn().mockResolvedValue(undefined)
+    })
+    const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('terminal.send', {
+        terminal: 'terminal-1',
+        text: 'x'
+      })
+    )
+
+    expect(response.ok).toBe(true)
+    if (!response.ok) {
+      throw new Error(response.error.message)
+    }
+    expect(response.result).toMatchObject({ send: { accepted: true, bytesWritten: 1 } })
+    expect(runtime.sendTerminal).toHaveBeenCalledWith('terminal-1', {
+      text: 'x',
+      enter: false,
+      interrupt: false
+    })
+    expect(runtime.mobileTookFloor).toHaveBeenCalledWith('pty-1', 'mobile-1')
+  })
+
+  it('routes terminal restore fit through the runtime driver state machine', async () => {
+    const runtime = stubRuntime({
+      resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+      reclaimTerminalForDesktop: vi.fn().mockResolvedValue(true)
+    })
+    const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('terminal.restoreFit', {
+        terminal: 'terminal-1'
+      })
+    )
+
+    expect(response.ok).toBe(true)
+    if (!response.ok) {
+      throw new Error(response.error.message)
+    }
+    expect(response.result).toEqual({ restored: true })
+    expect(runtime.reclaimTerminalForDesktop).toHaveBeenCalledWith('pty-1')
+  })
+})
diff --git a/src/main/runtime/rpc/terminal-subscribe-buffer.test.ts b/src/main/runtime/rpc/terminal-subscribe-buffer.test.ts
new file mode 100644
index 00000000000..8c1a0b77c5d
--- /dev/null
+++ b/src/main/runtime/rpc/terminal-subscribe-buffer.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from './dispatcher'
+import type { RpcRequest } from './core'
+import type { OrcaRuntimeService } from '../orca-runtime'
+import { TERMINAL_METHODS } from './methods/terminal'
+import type { RuntimeTerminalWait } from '../../../shared/runtime-types'
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamText
+} from '../../../shared/terminal-stream-protocol'
+
+function stubRuntime(overrides: Partial<OrcaRuntimeService> = {}): OrcaRuntimeService {
+  return {
+    getRuntimeId: () => 'test-runtime',
+    ...overrides
+  } as OrcaRuntimeService
+}
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('terminal subscribe buffering', () => {
+  it('bounds legacy binary output queued while the initial snapshot is serializing', async () => {
+    vi.useFakeTimers()
+    try {
+      const messages: string[] = []
+      const binaryFrames: Uint8Array<ArrayBufferLike>[] = []
+      const cleanups = new Map<string, () => void>()
+      const dataListenerRef: { current?: (data: string) => void } = {}
+      let resolveSnapshot: (value: { data: string; cols: number; rows: number }) => void = () => {}
+      const runtime = stubRuntime({
+        resolveLeafForHandle: vi.fn().mockReturnValue({ ptyId: 'pty-1' }),
+        readTerminal: vi.fn().mockResolvedValue({ tail: [], truncated: false }),
+        serializeTerminalBuffer: vi.fn(
+          () =>
+            new Promise<{ data: string; cols: number; rows: number }>((resolve) => {
+              resolveSnapshot = resolve
+            })
+        ),
+        getTerminalSize: vi.fn().mockReturnValue({ cols: 120, rows: 40 }),
+        getMobileDisplayMode: vi.fn().mockReturnValue('auto'),
+        getLayout: vi.fn().mockReturnValue({ seq: 1 }),
+        subscribeToTerminalData: vi.fn((_: string, listener: (data: string) => void) => {
+          dataListenerRef.current = listener
+          return vi.fn()
+        }),
+        subscribeToTerminalResize: vi.fn().mockReturnValue(vi.fn()),
+        subscribeToFitOverrideChanges: vi.fn().mockReturnValue(vi.fn()),
+        registerSubscriptionCleanup: vi.fn((id: string, cleanup: () => void) => {
+          cleanups.set(id, cleanup)
+        }),
+        cleanupSubscription: vi.fn((id: string) => {
+          const cleanup = cleanups.get(id)
+          cleanups.delete(id)
+          cleanup?.()
+        }),
+        waitForTerminal: vi.fn(() => new Promise<RuntimeTerminalWait>(() => {})),
+        sendTerminal: vi.fn().mockResolvedValue({ accepted: true }),
+        updateMobileViewport: vi.fn().mockResolvedValue(false)
+      })
+      const dispatcher = new RpcDispatcher({ runtime, methods: TERMINAL_METHODS })
+
+      const dispatchPromise = dispatcher.dispatchStreaming(
+        makeRequest('terminal.subscribe', {
+          terminal: 'terminal-1',
+          client: { id: 'desktop-1', type: 'desktop' },
+          capabilities: { terminalBinaryStream: 1 }
+        }),
+        (msg) => messages.push(msg),
+        {
+          connectionId: 'conn-buffered',
+          sendBinary: (bytes) => binaryFrames.push(bytes)
+        }
+      )
+
+      await vi.waitFor(() => expect(dataListenerRef.current).toBeDefined())
+      for (let index = 0; index < 400; index += 1) {
+        dataListenerRef.current?.(`${String(index).padStart(3, '0')}${'x'.repeat(1021)}`)
+      }
+      await vi.waitFor(() => expect(runtime.serializeTerminalBuffer).toHaveBeenCalled())
+      resolveSnapshot({ data: '', cols: 120, rows: 40 })
+      await vi.waitFor(() =>
+        expect(messages.some((msg) => JSON.parse(msg).result?.type === 'subscribed')).toBe(true)
+      )
+      await vi.runOnlyPendingTimersAsync()
+
+      const output = binaryFrames
+        .map((frame) => decodeTerminalStreamFrame(frame))
+        .filter((frame) => frame?.opcode === TerminalStreamOpcode.Output)
+        .map((frame) => (frame ? decodeTerminalStreamText(frame.payload) : ''))
+        .join('')
+      expect(output.length).toBeLessThanOrEqual(256 * 1024)
+      expect(output).not.toContain('000')
+      expect(output).toContain('399')
+
+      runtime.cleanupSubscription('terminal-1:desktop-1')
+      await dispatchPromise
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
diff --git a/src/main/runtime/rpc/ws-transport.test.ts b/src/main/runtime/rpc/ws-transport.test.ts
index 29db2b3b88b..2f3bcf6bdb6 100644
--- a/src/main/runtime/rpc/ws-transport.test.ts
+++ b/src/main/runtime/rpc/ws-transport.test.ts
@@ -23,7 +23,8 @@ describe('WebSocketTransport', () => {
   })
 
   async function createTransport(
-    handler?: (msg: string, reply: (response: string) => void) => void
+    handler?: (msg: string, reply: (response: string) => void) => void,
+    options: { preAuthTimeoutMs?: number } = {}
   ) {
     const tls = makeTls()
     const transport = new WebSocketTransport({
@@ -32,7 +33,8 @@ describe('WebSocketTransport', () => {
       // Port 0 lets the OS reserve an available port atomically.
       port: 0,
       tlsCert: tls.cert,
-      tlsKey: tls.key
+      tlsKey: tls.key,
+      preAuthTimeoutMs: options.preAuthTimeoutMs
     })
     if (handler) {
       transport.onMessage(handler)
@@ -41,7 +43,8 @@ describe('WebSocketTransport', () => {
     return { transport, tls }
   }
 
-  function connectWs(port: number): Promise<WebSocket> {
+  function connectWs(target: number | WebSocketTransport): Promise<WebSocket> {
+    const port = typeof target === 'number' ? target : target.resolvedPort
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(`wss://127.0.0.1:${port}`, {
         rejectUnauthorized: false
@@ -75,7 +78,7 @@ describe('WebSocketTransport', () => {
 
     await transport.start()
 
-    const ws = await connectWs(transport.resolvedPort)
+    const ws = await connectWs(transport)
     const response = await sendAndReceive(
       ws,
       JSON.stringify({ id: 'req-1', method: 'test', deviceToken: 'tok' })
@@ -99,9 +102,9 @@ describe('WebSocketTransport', () => {
     await transport.start()
 
     const clients = await Promise.all([
-      connectWs(transport.resolvedPort),
-      connectWs(transport.resolvedPort),
-      connectWs(transport.resolvedPort)
+      connectWs(transport),
+      connectWs(transport),
+      connectWs(transport)
     ])
 
     const responses = await Promise.all(
@@ -125,7 +128,7 @@ describe('WebSocketTransport', () => {
 
     await transport.start()
 
-    const ws = await connectWs(transport.resolvedPort)
+    const ws = await connectWs(transport)
 
     const r1 = sendAndReceive(ws, JSON.stringify({ id: 'a', method: 'first' }))
     const resp1 = JSON.parse(await r1)
@@ -148,7 +151,7 @@ describe('WebSocketTransport', () => {
 
     await transport.start()
 
-    const ws = await connectWs(transport.resolvedPort)
+    const ws = await connectWs(transport)
     const messages: string[] = []
 
     await new Promise<void>((resolve) => {
@@ -173,7 +176,7 @@ describe('WebSocketTransport', () => {
 
     await transport.start()
 
-    const ws = await connectWs(transport.resolvedPort)
+    const ws = await connectWs(transport)
 
     // Why: ws maxPayload is 1MB — sending >1MB should trigger close.
     const oversized = 'x'.repeat(1024 * 1024 + 100)
@@ -193,7 +196,7 @@ describe('WebSocketTransport', () => {
 
     await transport.start()
 
-    const ws = await connectWs(transport.resolvedPort)
+    const ws = await connectWs(transport)
     ws.send(JSON.stringify({ id: 'req-1', method: 'test' }))
 
     // Why: wait for the handler to capture the reply function.
@@ -215,6 +218,87 @@ describe('WebSocketTransport', () => {
     expect(() => capturedReply!(JSON.stringify({ id: 'req-1', ok: true }))).not.toThrow()
   })
 
+  it('runs connection cleanup for sockets that close before auth', async () => {
+    const { transport } = await createTransport()
+    const calls: { clientId: string | null; hasOtherConnections: boolean }[] = []
+    transport.onConnectionClose((clientId, _ws, hasOtherConnections) => {
+      calls.push({ clientId, hasOtherConnections })
+    })
+
+    await transport.start()
+
+    const ws = await connectWs(transport)
+    ws.close()
+
+    const start = Date.now()
+    while (calls.length === 0 && Date.now() - start < 2_000) {
+      await new Promise((resolve) => setTimeout(resolve, 20))
+    }
+
+    expect(calls).toEqual([{ clientId: null, hasOtherConnections: false }])
+  })
+
+  it('terminates every active connection for a revoked client id', async () => {
+    const { transport } = await createTransport()
+    const closedClientIds: (string | null)[] = []
+    transport.onConnectionClose((clientId) => {
+      closedClientIds.push(clientId)
+    })
+
+    await transport.start()
+
+    const clients = await Promise.all([connectWs(transport), connectWs(transport)])
+    const wss = (transport as unknown as { wss: { clients: Set<WebSocket> } }).wss
+    for (const client of wss.clients) {
+      transport.setClientId(client, 'device-token')
+    }
+
+    expect(transport.terminateClientConnections('device-token')).toBe(2)
+
+    await Promise.all(
+      clients.map(
+        (client) =>
+          new Promise<void>((resolve) => {
+            if (client.readyState === client.CLOSED) {
+              resolve()
+              return
+            }
+            client.once('close', () => resolve())
+          })
+      )
+    )
+
+    const start = Date.now()
+    while (closedClientIds.length < 2 && Date.now() - start < 2_000) {
+      await new Promise((resolve) => setTimeout(resolve, 20))
+    }
+
+    expect(closedClientIds).toEqual(['device-token', 'device-token'])
+  })
+
+  it('reaps silent pre-auth sockets so they cannot hold the connection cap', async () => {
+    const { transport } = await createTransport(undefined, { preAuthTimeoutMs: 50 })
+    await transport.start()
+
+    const clients = await Promise.all(Array.from({ length: 32 }, () => connectWs(transport)))
+    await Promise.all(
+      clients.map(
+        (client) =>
+          new Promise<void>((resolve) => {
+            if (client.readyState === client.CLOSED) {
+              resolve()
+              return
+            }
+            client.once('close', () => resolve())
+          })
+      )
+    )
+
+    const liveClient = await connectWs(transport)
+    expect(liveClient.readyState).toBe(liveClient.OPEN)
+    liveClient.close()
+  })
+
   it('is idempotent on double start', async () => {
     const { transport } = await createTransport()
 
@@ -282,7 +366,7 @@ describe('WebSocketTransport', () => {
     // start so we can stamp every accepted ws with a token.
     await transport.start()
 
-    const ws = await connectWs(transport.resolvedPort)
+    const ws = await connectWs(transport)
     // Why: pausing the underlying TCP socket halts both read (ping in)
     // and write (pong out) at the kernel level, so the `ws` library's
     // auto-pong can't actually be flushed back. From the server's
diff --git a/src/main/runtime/rpc/ws-transport.ts b/src/main/runtime/rpc/ws-transport.ts
index b6f34c71113..028c3f379ce 100644
--- a/src/main/runtime/rpc/ws-transport.ts
+++ b/src/main/runtime/rpc/ws-transport.ts
@@ -10,6 +10,7 @@ import type { RpcTransport } from './transport'
 
 const MAX_WS_MESSAGE_BYTES = 1024 * 1024
 const MAX_WS_CONNECTIONS = 32
+const PRE_AUTH_TIMEOUT_MS = 10_000
 type WebSocketMessagePayload = string | Uint8Array<ArrayBufferLike>
 type WebSocketMessageHandler = {
   bivarianceHack(
@@ -38,6 +39,8 @@ export type WebSocketTransportOptions = {
   tlsKey?: string
   // Why: test-only override. Production uses HEARTBEAT_INTERVAL_MS.
   heartbeatIntervalMs?: number
+  // Why: test-only override. Production uses PRE_AUTH_TIMEOUT_MS.
+  preAuthTimeoutMs?: number
 }
 
 export class WebSocketTransport implements RpcTransport {
@@ -46,6 +49,7 @@ export class WebSocketTransport implements RpcTransport {
   private readonly tlsCert: string | undefined
   private readonly tlsKey: string | undefined
   private readonly heartbeatIntervalMs: number
+  private readonly preAuthTimeoutMs: number
   private httpServer: HttpsServer | HttpServer | null = null
   private wss: WebSocketServer | null = null
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null
@@ -55,18 +59,27 @@ export class WebSocketTransport implements RpcTransport {
   private wsAlive = new WeakSet<WebSocket>()
   private messageHandler: WebSocketMessageHandler | null = null
   private connectionCloseHandler:
-    | ((clientId: string, ws: WebSocket, hasOtherConnections: boolean) => void)
+    | ((clientId: string | null, ws: WebSocket, hasOtherConnections: boolean) => void)
     | null = null
   // Why: maps each WebSocket to the clientId (deviceToken) that authenticated it,
   // so ws.on('close') can notify the runtime which mobile client disconnected.
   private wsClientIds = new Map<WebSocket, string>()
+  private preAuthTimers = new WeakMap<WebSocket, ReturnType<typeof setTimeout>>()
 
-  constructor({ host, port, tlsCert, tlsKey, heartbeatIntervalMs }: WebSocketTransportOptions) {
+  constructor({
+    host,
+    port,
+    tlsCert,
+    tlsKey,
+    heartbeatIntervalMs,
+    preAuthTimeoutMs
+  }: WebSocketTransportOptions) {
     this.host = host
     this.port = port
     this.tlsCert = tlsCert
     this.tlsKey = tlsKey
     this.heartbeatIntervalMs = heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS
+    this.preAuthTimeoutMs = preAuthTimeoutMs ?? PRE_AUTH_TIMEOUT_MS
   }
 
   onMessage(handler: WebSocketMessageHandler): void {
@@ -80,13 +93,26 @@ export class WebSocketTransport implements RpcTransport {
   // so client-scoped teardown (mobile-fit overrides, etc.) only fires on the
   // last disconnect.
   onConnectionClose(
-    handler: (clientId: string, ws: WebSocket, hasOtherConnections: boolean) => void
+    handler: (clientId: string | null, ws: WebSocket, hasOtherConnections: boolean) => void
   ): void {
     this.connectionCloseHandler = handler
   }
 
   setClientId(ws: WebSocket, clientId: string): void {
     this.wsClientIds.set(ws, clientId)
+    this.clearPreAuthTimer(ws)
+  }
+
+  terminateClientConnections(clientId: string): number {
+    const sockets = Array.from(this.wsClientIds.entries())
+      .filter(([, candidateClientId]) => candidateClientId === clientId)
+      .map(([ws]) => ws)
+    for (const ws of sockets) {
+      // Why: revocation is a security boundary; terminate skips the close
+      // handshake so a revoked mobile stream stops immediately.
+      ws.terminate()
+    }
+    return sockets.length
   }
 
   // Why: when port 0 is passed the OS assigns a random available port. The
@@ -235,6 +261,33 @@ export class WebSocketTransport implements RpcTransport {
   // connection via the RPC `id` field. The transport delegates all auth
   // and dispatch logic to the message handler set by OrcaRuntimeRpcServer.
   private handleConnection(ws: WebSocket): void {
+    let finalized = false
+    const finalizeConnection = (): void => {
+      if (finalized) {
+        return
+      }
+      finalized = true
+      this.clearPreAuthTimer(ws)
+      const clientId = this.wsClientIds.get(ws) ?? null
+      this.wsClientIds.delete(ws)
+      const hasOtherConnections =
+        clientId !== null && Array.from(this.wsClientIds.values()).includes(clientId)
+      this.connectionCloseHandler?.(clientId, ws, hasOtherConnections)
+    }
+
+    const preAuthTimer = setTimeout(() => {
+      if (!this.wsClientIds.has(ws)) {
+        // Why: a silent client that only auto-pongs can otherwise occupy one
+        // of the finite mobile WebSocket slots forever without ever starting
+        // the E2EE handshake.
+        ws.terminate()
+      }
+    }, this.preAuthTimeoutMs)
+    if (typeof preAuthTimer.unref === 'function') {
+      preAuthTimer.unref()
+    }
+    this.preAuthTimers.set(ws, preAuthTimer)
+
     // Why: seed alive=true so the first heartbeat tick after connect doesn't
     // treat a fresh socket as dead. Subsequent pongs (or any inbound traffic)
     // re-arm it.
@@ -272,24 +325,23 @@ export class WebSocketTransport implements RpcTransport {
     // Why: mobile clients disconnect when the phone locks, loses wifi, or
     // backgrounds the app. The runtime must clean up connection-scoped state
     // (e.g., mobile-fit overrides) to prevent orphaned phone-fit on desktop.
-    ws.on('close', () => {
-      const clientId = this.wsClientIds.get(ws)
-      this.wsClientIds.delete(ws)
-      if (clientId) {
-        // Why: a paired device may have multiple concurrent sockets open
-        // (e.g. one per app screen). Per-client teardown must only fire when
-        // the last socket for this token closes — otherwise closing the
-        // accounts-screen socket would clobber the host-screen socket's
-        // state and strand it in a non-functional state until re-paired.
-        const hasOtherConnections = Array.from(this.wsClientIds.values()).includes(clientId)
-        this.connectionCloseHandler?.(clientId, ws, hasOtherConnections)
-      }
-    })
+    ws.on('close', finalizeConnection)
 
     ws.on('error', () => {
+      // Why: close is not guaranteed after every ws error path; finalize here
+      // too so pre-auth E2EE channels and connection ids cannot leak.
+      finalizeConnection()
       ws.close()
     })
   }
+
+  private clearPreAuthTimer(ws: WebSocket): void {
+    const timer = this.preAuthTimers.get(ws)
+    if (timer) {
+      clearTimeout(timer)
+      this.preAuthTimers.delete(ws)
+    }
+  }
 }
 
 function isEAddressInUse(error: unknown): boolean {
diff --git a/src/main/runtime/runtime-metadata.test.ts b/src/main/runtime/runtime-metadata.test.ts
index 4e93e909dd6..da369b01d40 100644
--- a/src/main/runtime/runtime-metadata.test.ts
+++ b/src/main/runtime/runtime-metadata.test.ts
@@ -1,8 +1,16 @@
-import { mkdtempSync, statSync } from 'fs'
+import { chmodSync, mkdtempSync, readdirSync, statSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { getRuntimeMetadataPath } from '../../shared/runtime-bootstrap'
+import { encodePairingOffer } from '../../shared/pairing'
+import {
+  addEnvironmentFromPairingCode,
+  getEnvironmentStorePath,
+  listEnvironments
+} from '../../shared/runtime-environment-store'
+import { DeviceRegistry } from './device-registry'
+import { loadOrCreateE2EEKeypair } from './e2ee-keypair'
 import {
   clearRuntimeMetadata,
   clearRuntimeMetadataIfOwned,
@@ -161,4 +169,89 @@ describe('runtime metadata', () => {
       expect(directoryMode).toBe(0o700)
     }
   )
+
+  it.runIf(process.platform !== 'win32')(
+    'uses hardened atomic writes for runtime credential stores on Unix',
+    () => {
+      const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-secure-files-'))
+      tempDirs.push(userDataPath)
+
+      new DeviceRegistry(userDataPath).addDevice('phone')
+      loadOrCreateE2EEKeypair(userDataPath)
+      addEnvironmentFromPairingCode(userDataPath, {
+        name: 'desk',
+        pairingCode: encodePairingOffer({
+          v: 2,
+          endpoint: 'ws://127.0.0.1:6768',
+          deviceToken: 'device-token',
+          publicKeyB64: Buffer.from(new Uint8Array(32).fill(1)).toString('base64')
+        })
+      })
+
+      for (const path of [
+        join(userDataPath, 'orca-devices.json'),
+        join(userDataPath, 'orca-e2ee-keypair.json'),
+        getEnvironmentStorePath(userDataPath)
+      ]) {
+        expect(statSync(path).mode & 0o777).toBe(0o600)
+      }
+      expect(statSync(userDataPath).mode & 0o777).toBe(0o700)
+      expect(readdirSync(userDataPath).some((entry) => entry.endsWith('.tmp'))).toBe(false)
+    }
+  )
+
+  it.runIf(process.platform !== 'win32')(
+    'hardens existing runtime credential stores before reading them on Unix',
+    () => {
+      const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-existing-secure-files-'))
+      tempDirs.push(userDataPath)
+      const keyMaterial = Buffer.from(new Uint8Array(32).fill(1)).toString('base64')
+      const pairingCode = encodePairingOffer({
+        v: 2,
+        endpoint: 'ws://127.0.0.1:6768',
+        deviceToken: 'device-token',
+        publicKeyB64: keyMaterial
+      })
+      const environment = addEnvironmentFromPairingCode(userDataPath, {
+        name: 'desk',
+        pairingCode
+      })
+
+      const devicesPath = join(userDataPath, 'orca-devices.json')
+      const keypairPath = join(userDataPath, 'orca-e2ee-keypair.json')
+      const environmentsPath = getEnvironmentStorePath(userDataPath)
+      writeFileSync(
+        devicesPath,
+        JSON.stringify([
+          {
+            deviceId: 'device-1',
+            name: 'phone',
+            token: 'token',
+            pairedAt: 1,
+            lastSeenAt: 0
+          }
+        ])
+      )
+      writeFileSync(
+        keypairPath,
+        JSON.stringify({ v: 1, publicKeyB64: keyMaterial, secretKeyB64: keyMaterial })
+      )
+      for (const path of [devicesPath, keypairPath, environmentsPath]) {
+        chmodSync(path, 0o644)
+      }
+      chmodSync(userDataPath, 0o755)
+
+      expect(new DeviceRegistry(userDataPath).getDevice('device-1')).toMatchObject({
+        token: 'token',
+        scope: 'mobile'
+      })
+      expect(loadOrCreateE2EEKeypair(userDataPath).publicKeyB64).toBe(keyMaterial)
+      expect(listEnvironments(userDataPath)[0]?.id).toBe(environment.id)
+
+      for (const path of [devicesPath, keypairPath, environmentsPath]) {
+        expect(statSync(path).mode & 0o777).toBe(0o600)
+      }
+      expect(statSync(userDataPath).mode & 0o777).toBe(0o700)
+    }
+  )
 })
diff --git a/src/main/runtime/runtime-metadata.ts b/src/main/runtime/runtime-metadata.ts
index 95a7f707c0f..ec46035d7c2 100644
--- a/src/main/runtime/runtime-metadata.ts
+++ b/src/main/runtime/runtime-metadata.ts
@@ -1,17 +1,6 @@
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  writeFileSync
-} from 'fs'
-import { execFileSync } from 'child_process'
-import { dirname } from 'path'
+import { existsSync, readFileSync, rmSync } from 'fs'
 import { getRuntimeMetadataPath, type RuntimeMetadata } from '../../shared/runtime-bootstrap'
-
-let cachedWindowsUserSid: string | null | undefined
+import { writeSecureJsonFile } from '../../shared/secure-file'
 
 export function writeRuntimeMetadata(userDataPath: string, metadata: RuntimeMetadata): void {
   const metadataPath = getRuntimeMetadataPath(userDataPath)
@@ -63,85 +52,5 @@ export function clearRuntimeMetadataIfOwned(
 }
 
 function writeMetadataFile(path: string, metadata: RuntimeMetadata): void {
-  const dir = dirname(path)
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true, mode: 0o700 })
-  }
-  hardenRuntimePath(dir, { isDirectory: true, platform: process.platform })
-  const tmpFile = `${path}.tmp`
-  writeFileSync(tmpFile, JSON.stringify(metadata, null, 2), {
-    encoding: 'utf-8',
-    mode: 0o600
-  })
-  hardenRuntimePath(tmpFile, { isDirectory: false, platform: process.platform })
-  renameSync(tmpFile, path)
-  // Why: runtime bootstrap files carry auth material that lets the local CLI
-  // attach to a live Orca runtime. The published file must stay scoped to
-  // the current user.
-  hardenRuntimePath(path, { isDirectory: false, platform: process.platform })
-}
-
-function hardenRuntimePath(
-  targetPath: string,
-  options: {
-    isDirectory: boolean
-    platform: NodeJS.Platform
-  }
-): void {
-  if (options.platform === 'win32') {
-    bestEffortRestrictWindowsPath(targetPath)
-    return
-  }
-  chmodSync(targetPath, options.isDirectory ? 0o700 : 0o600)
-}
-
-function bestEffortRestrictWindowsPath(targetPath: string): void {
-  const currentUserSid = getCurrentWindowsUserSid()
-  if (!currentUserSid) {
-    return
-  }
-  try {
-    execFileSync(
-      'icacls',
-      [
-        targetPath,
-        '/inheritance:r',
-        '/grant:r',
-        `*${currentUserSid}:(F)`,
-        '*S-1-5-18:(F)',
-        '*S-1-5-32-544:(F)'
-      ],
-      {
-        stdio: 'ignore',
-        windowsHide: true,
-        timeout: 5000
-      }
-    )
-  } catch {
-    // Why: runtime metadata hardening should not prevent Orca from starting on
-    // Windows machines where icacls is unavailable or locked down differently.
-  }
-}
-
-function getCurrentWindowsUserSid(): string | null {
-  if (cachedWindowsUserSid !== undefined) {
-    return cachedWindowsUserSid
-  }
-  try {
-    const output = execFileSync('whoami', ['/user', '/fo', 'csv', '/nh'], {
-      encoding: 'utf-8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      windowsHide: true,
-      timeout: 5000
-    }).trim()
-    const columns = parseCsvLine(output)
-    cachedWindowsUserSid = columns[1] ?? null
-  } catch {
-    cachedWindowsUserSid = null
-  }
-  return cachedWindowsUserSid
-}
-
-function parseCsvLine(line: string): string[] {
-  return line.split(/","/).map((part) => part.replace(/^"/, '').replace(/"$/, ''))
+  writeSecureJsonFile(path, metadata)
 }
diff --git a/src/main/runtime/runtime-relative-paths.ts b/src/main/runtime/runtime-relative-paths.ts
new file mode 100644
index 00000000000..c74d965c0c9
--- /dev/null
+++ b/src/main/runtime/runtime-relative-paths.ts
@@ -0,0 +1,29 @@
+import { posix, win32 } from 'path'
+import { isWindowsAbsolutePathLike } from '../../shared/cross-platform-path'
+
+export function joinWorktreeRelativePath(rootPath: string, relativePath: string): string {
+  const normalizedRelativePath = relativePath.replace(/\\/g, '/')
+  if (isWindowsAbsolutePathLike(rootPath)) {
+    return win32.join(rootPath.replace(/\//g, '\\'), ...normalizedRelativePath.split('/'))
+  }
+  return posix.join(rootPath, ...normalizedRelativePath.split('/'))
+}
+
+export function normalizeRuntimeRelativePath(relativePath: string): string {
+  const normalized = relativePath.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (normalized === '') {
+    return ''
+  }
+  if (!isSafeRuntimeRelativePath(normalized)) {
+    throw new Error('invalid_relative_path')
+  }
+  return normalized
+}
+
+function isSafeRuntimeRelativePath(relativePath: string): boolean {
+  if (relativePath.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(relativePath)) {
+    return false
+  }
+  const parts = relativePath.split('/')
+  return parts.every((part) => part !== '' && part !== '.' && part !== '..')
+}
diff --git a/src/main/runtime/runtime-rpc.test.ts b/src/main/runtime/runtime-rpc.test.ts
index d07fc93b01b..acbbcdaa979 100644
--- a/src/main/runtime/runtime-rpc.test.ts
+++ b/src/main/runtime/runtime-rpc.test.ts
@@ -3,13 +3,18 @@ import { existsSync, mkdtempSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { createConnection, type Socket } from 'net'
+import { EventEmitter } from 'events'
 import { describe, expect, it, vi } from 'vitest'
 import Database from 'better-sqlite3'
+import WebSocket from 'ws'
 import { OrcaRuntimeService } from './orca-runtime'
 import { OrchestrationDb } from './orchestration/db'
 import * as runtimeMetadataModule from './runtime-metadata'
 import { readRuntimeMetadata } from './runtime-metadata'
 import { createRuntimeTransportMetadata, OrcaRuntimeRpcServer } from './runtime-rpc'
+import { parsePairingCode } from '../../shared/pairing'
+import { decrypt, deriveSharedKey, encrypt, generateKeyPair } from './rpc/e2ee-crypto'
+import { DeviceRegistry } from './device-registry'
 
 vi.mock('../git/worktree', () => ({
   listWorktrees: vi.fn().mockResolvedValue([
@@ -104,6 +109,73 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+async function waitFor(predicate: () => boolean, timeoutMs = 2_000): Promise<void> {
+  const start = Date.now()
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error('timed out waiting for condition')
+    }
+    await sleep(20)
+  }
+}
+
+function connectWs(endpoint: string): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(endpoint)
+    ws.once('open', () => resolve(ws))
+    ws.once('error', reject)
+  })
+}
+
+function nextWsMessage(ws: WebSocket): Promise<string> {
+  return new Promise((resolve) => {
+    ws.once('message', (data) => {
+      resolve(typeof data === 'string' ? data : data.toString('utf-8'))
+    })
+  })
+}
+
+function waitForWsClose(ws: WebSocket): Promise<void> {
+  return new Promise((resolve) => {
+    if (ws.readyState === ws.CLOSED) {
+      resolve()
+      return
+    }
+    ws.once('close', () => resolve())
+  })
+}
+
+async function authenticateMobileWs(pairingUrl: string): Promise<WebSocket> {
+  const parsed = parsePairingCode(pairingUrl)
+  expect(parsed).toBeTruthy()
+  const ws = await connectWs(parsed!.endpoint)
+  const mobileKeys = generateKeyPair()
+  const serverPublicKey = Uint8Array.from(Buffer.from(parsed!.publicKeyB64, 'base64'))
+  const sharedKey = deriveSharedKey(mobileKeys.secretKey, serverPublicKey)
+
+  ws.send(
+    JSON.stringify({
+      type: 'e2ee_hello',
+      publicKeyB64: Buffer.from(mobileKeys.publicKey).toString('base64')
+    })
+  )
+  expect(JSON.parse(await nextWsMessage(ws))).toEqual({ type: 'e2ee_ready' })
+
+  ws.send(
+    encrypt(JSON.stringify({ type: 'e2ee_auth', deviceToken: parsed!.deviceToken }), sharedKey)
+  )
+  expect(JSON.parse(decrypt(await nextWsMessage(ws), sharedKey)!)).toEqual({
+    type: 'e2ee_authenticated'
+  })
+
+  return ws
+}
+
+class FakeWebSocket extends EventEmitter {
+  readonly OPEN = 1
+  readyState = this.OPEN
+}
+
 describe('OrcaRuntimeRpcServer', () => {
   const makeStore = (overrides?: { isUnread?: boolean }) => ({
     getRepo: (id: string) =>
@@ -176,6 +248,418 @@ describe('OrcaRuntimeRpcServer', () => {
     })
   })
 
+  it('creates a pairing offer for the active WebSocket transport', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+
+    await server.start()
+
+    const offer = server.createPairingOffer({ address: '100.64.1.20', name: 'CLI test' })
+    expect(offer.available).toBe(true)
+    if (offer.available) {
+      expect(offer.endpoint).toContain('100.64.1.20')
+      const parsed = parsePairingCode(offer.pairingUrl)
+      expect(parsed?.endpoint).toBe(offer.endpoint)
+      expect(parsed?.deviceToken).toBeTruthy()
+      expect(parsed?.publicKeyB64).toBeTruthy()
+      expect(server.getDeviceRegistry()?.getDevice(offer.deviceId)?.scope).toBe('runtime')
+    }
+
+    await server.stop()
+  })
+
+  it('formats pairing-address overrides for IPv6 and host-port tunnel endpoints', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+
+    await server.start()
+
+    try {
+      const ipv6 = server.createPairingOffer({ address: '::1', name: 'IPv6 test' })
+      expect(ipv6.available).toBe(true)
+      if (ipv6.available) {
+        expect(ipv6.endpoint).toMatch(/^ws:\/\/\[::1\]:\d+$/)
+        expect(parsePairingCode(ipv6.pairingUrl)?.endpoint).toBe(ipv6.endpoint)
+      }
+
+      const tunnel = server.createPairingOffer({
+        address: 'tunnel.example.com:443',
+        name: 'Tunnel test'
+      })
+      expect(tunnel.available).toBe(true)
+      if (tunnel.available) {
+        expect(tunnel.endpoint).toBe('ws://tunnel.example.com:443')
+      }
+
+      const fullUrl = server.createPairingOffer({
+        address: 'wss://runtime.example.com/orca',
+        name: 'Full URL test'
+      })
+      expect(fullUrl.available).toBe(true)
+      if (fullUrl.available) {
+        expect(fullUrl.endpoint).toBe('wss://runtime.example.com/orca')
+      }
+    } finally {
+      await server.stop()
+    }
+  })
+
+  it('creates mobile-scoped pairing offers for headless mobile pairing', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+
+    await server.start()
+
+    try {
+      const offer = server.createPairingOffer({
+        address: '100.64.1.20',
+        name: 'Mobile test',
+        scope: 'mobile'
+      })
+      expect(offer.available).toBe(true)
+      if (!offer.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+
+      expect(server.getDeviceRegistry()?.getDevice(offer.deviceId)?.scope).toBe('mobile')
+      const parsed = parsePairingCode(offer.pairingUrl)
+      expect(parsed?.endpoint).toBe(offer.endpoint)
+      expect(parsed?.endpoint).toContain('100.64.1.20')
+    } finally {
+      await server.stop()
+    }
+  })
+
+  it('cleans up pre-auth E2EE WebSocket state when the socket closes', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+
+    await server.start()
+
+    try {
+      const offer = server.createPairingOffer({
+        address: '127.0.0.1',
+        name: 'mobile-test',
+        scope: 'mobile'
+      })
+      expect(offer.available).toBe(true)
+      if (!offer.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+      const parsed = parsePairingCode(offer.pairingUrl)!
+      const ws = await connectWs(parsed.endpoint)
+      const mobileKeys = generateKeyPair()
+      ws.send(
+        JSON.stringify({
+          type: 'e2ee_hello',
+          publicKeyB64: Buffer.from(mobileKeys.publicKey).toString('base64')
+        })
+      )
+      expect(JSON.parse(await nextWsMessage(ws))).toEqual({ type: 'e2ee_ready' })
+      expect(server['e2eeChannels'].size).toBe(1)
+      expect(server['wsConnectionIds'].size).toBe(1)
+
+      ws.close()
+      await waitForWsClose(ws)
+      await waitFor(() => server['e2eeChannels'].size === 0 && server['wsConnectionIds'].size === 0)
+    } finally {
+      await server.stop()
+    }
+  })
+
+  it('terminates active WebSockets for a revoked mobile device', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+    const disconnectSpy = vi.spyOn(runtime, 'onClientDisconnected')
+
+    await server.start()
+
+    try {
+      const offer = server.createPairingOffer({
+        address: '127.0.0.1',
+        name: 'mobile-test',
+        scope: 'mobile'
+      })
+      expect(offer.available).toBe(true)
+      if (!offer.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+      const first = await authenticateMobileWs(offer.pairingUrl)
+      const second = await authenticateMobileWs(offer.pairingUrl)
+
+      expect(server.revokeMobileDevice(offer.deviceId)).toBe(true)
+      await Promise.all([waitForWsClose(first), waitForWsClose(second)])
+      await waitFor(() => server['e2eeChannels'].size === 0 && server['wsConnectionIds'].size === 0)
+
+      expect(disconnectSpy).toHaveBeenCalledTimes(1)
+    } finally {
+      disconnectSpy.mockRestore()
+      await server.stop()
+    }
+  })
+
+  it('does not revoke runtime-scoped devices through mobile revocation', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0
+    })
+
+    await server.start()
+
+    try {
+      const offer = server.createPairingOffer({
+        address: '127.0.0.1',
+        name: 'runtime-test',
+        scope: 'runtime'
+      })
+      expect(offer.available).toBe(true)
+      if (!offer.available) {
+        throw new Error('WebSocket pairing unavailable')
+      }
+
+      expect(server.revokeMobileDevice(offer.deviceId)).toBe(false)
+      expect(server.getDeviceRegistry()?.getDevice(offer.deviceId)?.scope).toBe('runtime')
+    } finally {
+      await server.stop()
+    }
+  })
+
+  it('caps WebSocket long-polls and aborts them when the socket closes', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const db = new OrchestrationDb(':memory:')
+    runtime.setOrchestrationDb(db)
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: false,
+      longPollCap: 1
+    })
+    const device = server['deviceRegistry'] ?? null
+    expect(device).toBeNull()
+    server['deviceRegistry'] = new DeviceRegistry(userDataPath)
+    const entry = server['deviceRegistry']!.addDevice('runtime-test', 'runtime')
+    const ws = new FakeWebSocket()
+    server['wsConnectionIds'].set(ws as unknown as WebSocket, 'conn-test')
+    const replies: Record<string, unknown>[] = []
+
+    try {
+      const first = server['handleWebSocketMessage'](
+        JSON.stringify({
+          id: 'req_wait',
+          method: 'orchestration.check',
+          deviceToken: entry.token,
+          params: { terminal: 'term_wait', wait: true, timeoutMs: 10_000 }
+        }),
+        (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+        () => {},
+        undefined,
+        ws as unknown as WebSocket
+      )
+
+      await waitFor(() => server['activeLongPolls'] === 1)
+
+      await server['handleWebSocketMessage'](
+        JSON.stringify({
+          id: 'req_busy',
+          method: 'orchestration.check',
+          deviceToken: entry.token,
+          params: { terminal: 'term_busy', wait: true, timeoutMs: 10_000 }
+        }),
+        (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+        () => {},
+        undefined,
+        ws as unknown as WebSocket
+      )
+
+      expect(replies).toContainEqual(
+        expect.objectContaining({
+          id: 'req_busy',
+          ok: false,
+          error: expect.objectContaining({ code: 'runtime_busy' })
+        })
+      )
+      expect(server['activeLongPolls']).toBe(1)
+
+      ws.readyState = 3
+      ws.emit('close')
+      await first
+
+      expect(server['activeLongPolls']).toBe(0)
+      expect(replies).toContainEqual(expect.objectContaining({ id: 'req_wait', ok: true }))
+    } finally {
+      db.close()
+      await server.stop()
+    }
+  })
+
+  it('limits mobile-scoped WebSocket tokens to the mobile RPC surface', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const pushRuntimeGit = vi.fn().mockResolvedValue({ ok: true })
+    const selectClaudeAccount = vi.fn().mockResolvedValue({ ok: true })
+    const selectCodexAccount = vi.fn().mockResolvedValue({ ok: true })
+    const removeClaudeAccount = vi.fn().mockResolvedValue({ ok: true })
+    const readTerminal = vi.fn().mockResolvedValue({ tail: ['ok'] })
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getStatus: vi.fn().mockResolvedValue({ graphStatus: 'ok' }),
+      pushRuntimeGit,
+      selectClaudeAccount,
+      selectCodexAccount,
+      removeClaudeAccount,
+      readTerminal
+    } as unknown as OrcaRuntimeService
+    const server = new OrcaRuntimeRpcServer({ runtime, userDataPath, enableWebSocket: false })
+    server['deviceRegistry'] = new DeviceRegistry(userDataPath)
+    const mobile = server['deviceRegistry']!.addDevice('phone', 'mobile')
+    const replies: Record<string, unknown>[] = []
+
+    await server['handleWebSocketMessage'](
+      JSON.stringify({
+        id: 'req_forbidden',
+        method: 'git.push',
+        deviceToken: mobile.token,
+        params: { worktree: 'id:wt-1' }
+      }),
+      (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+      () => {}
+    )
+    await server['handleWebSocketMessage'](
+      JSON.stringify({
+        id: 'req_allowed',
+        method: 'status.get',
+        deviceToken: mobile.token
+      }),
+      (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+      () => {}
+    )
+    await server['handleWebSocketMessage'](
+      JSON.stringify({
+        id: 'req_select_claude',
+        method: 'accounts.selectClaude',
+        deviceToken: mobile.token,
+        params: { accountId: 'claude-account' }
+      }),
+      (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+      () => {}
+    )
+    await server['handleWebSocketMessage'](
+      JSON.stringify({
+        id: 'req_select_codex',
+        method: 'accounts.selectCodex',
+        deviceToken: mobile.token,
+        params: { accountId: null }
+      }),
+      (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+      () => {}
+    )
+    await server['handleWebSocketMessage'](
+      JSON.stringify({
+        id: 'req_remove_claude',
+        method: 'accounts.removeClaude',
+        deviceToken: mobile.token,
+        params: { accountId: 'claude-account' }
+      }),
+      (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+      () => {}
+    )
+    await server['handleWebSocketMessage'](
+      JSON.stringify({
+        id: 'req_terminal_read',
+        method: 'terminal.read',
+        deviceToken: mobile.token,
+        params: { terminal: 'term-1' }
+      }),
+      (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+      () => {}
+    )
+
+    expect(replies).toContainEqual(
+      expect.objectContaining({
+        id: 'req_forbidden',
+        ok: false,
+        error: expect.objectContaining({ code: 'forbidden' })
+      })
+    )
+    expect(replies).toContainEqual(expect.objectContaining({ id: 'req_allowed', ok: true }))
+    expect(replies).toContainEqual(expect.objectContaining({ id: 'req_select_claude', ok: true }))
+    expect(replies).toContainEqual(expect.objectContaining({ id: 'req_select_codex', ok: true }))
+    expect(replies).toContainEqual(expect.objectContaining({ id: 'req_terminal_read', ok: true }))
+    expect(replies).toContainEqual(
+      expect.objectContaining({
+        id: 'req_remove_claude',
+        ok: false,
+        error: expect.objectContaining({ code: 'forbidden' })
+      })
+    )
+    expect(selectClaudeAccount).toHaveBeenCalledWith('claude-account')
+    expect(selectCodexAccount).toHaveBeenCalledWith(null)
+    expect(readTerminal).toHaveBeenCalledWith('term-1', { cursor: undefined })
+    expect(removeClaudeAccount).not.toHaveBeenCalled()
+    expect(pushRuntimeGit).not.toHaveBeenCalled()
+  })
+
+  it('allows runtime-scoped WebSocket tokens to use the full RPC surface', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const pushRuntimeGit = vi.fn().mockResolvedValue({ ok: true })
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      pushRuntimeGit
+    } as unknown as OrcaRuntimeService
+    const server = new OrcaRuntimeRpcServer({ runtime, userDataPath, enableWebSocket: false })
+    server['deviceRegistry'] = new DeviceRegistry(userDataPath)
+    const runtimeDevice = server['deviceRegistry']!.addDevice('cli', 'runtime')
+    const replies: Record<string, unknown>[] = []
+
+    await server['handleWebSocketMessage'](
+      JSON.stringify({
+        id: 'req_push',
+        method: 'git.push',
+        deviceToken: runtimeDevice.token,
+        params: { worktree: 'id:wt-1' }
+      }),
+      (response) => replies.push(JSON.parse(response) as Record<string, unknown>),
+      () => {}
+    )
+
+    expect(replies).toContainEqual(expect.objectContaining({ id: 'req_push', ok: true }))
+    expect(pushRuntimeGit).toHaveBeenCalledWith('id:wt-1', undefined, undefined)
+  })
+
   it('leaves the last published metadata in place when a runtime stops', async () => {
     const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
     const runtime = new OrcaRuntimeService()
diff --git a/src/main/runtime/runtime-rpc.ts b/src/main/runtime/runtime-rpc.ts
index 19f80642b0d..da555f98833 100644
--- a/src/main/runtime/runtime-rpc.ts
+++ b/src/main/runtime/runtime-rpc.ts
@@ -17,9 +17,14 @@ import type { RpcMessageContext, RpcTransport } from './rpc/transport'
 import { UnixSocketTransport } from './rpc/unix-socket-transport'
 import { WebSocketTransport } from './rpc/ws-transport'
 import type { WebSocket } from 'ws'
-import { DeviceRegistry } from './device-registry'
+import { DeviceRegistry, type DeviceScope } from './device-registry'
 import { loadOrCreateE2EEKeypair, type E2EEKeypair } from './e2ee-keypair'
 import { E2EEChannel } from './rpc/e2ee-channel'
+import { encodePairingOffer, PAIRING_OFFER_VERSION } from '../../shared/pairing'
+import {
+  decodeTerminalStreamFrame,
+  type TerminalStreamFrame
+} from '../../shared/terminal-stream-protocol'
 
 const DEFAULT_WS_PORT = 6768
 
@@ -56,6 +61,89 @@ const KEEPALIVE_INTERVAL_MS = 10_000
 // queuing. See design doc §3.1 + §7 risk #2.
 const LONG_POLL_CAP = 16
 
+function resolvePairingEndpoint(rawEndpoint: string, address: string | null | undefined): string {
+  const endpoint = new URL(rawEndpoint)
+  const override = address?.trim()
+  if (!override) {
+    endpoint.hostname = '127.0.0.1'
+    return formatWebSocketUrl(endpoint)
+  }
+  if (/^wss?:\/\//i.test(override)) {
+    return formatWebSocketUrl(new URL(override))
+  }
+  const parsed = parsePairingAddressOverride(override)
+  endpoint.hostname = parsed.host.includes(':')
+    ? `[${parsed.host.replace(/^\[|\]$/g, '')}]`
+    : parsed.host
+  if (parsed.port) {
+    endpoint.port = parsed.port
+  }
+  return formatWebSocketUrl(endpoint)
+}
+
+function parsePairingAddressOverride(address: string): { host: string; port: string | null } {
+  if (address.startsWith('[') || address.split(':').length === 2) {
+    try {
+      const parsed = new URL(`ws://${address}`)
+      return { host: parsed.hostname.replace(/^\[|\]$/g, ''), port: parsed.port || null }
+    } catch {
+      return { host: address, port: null }
+    }
+  }
+  return { host: address, port: null }
+}
+
+function formatWebSocketUrl(url: URL): string {
+  const formatted = url.toString()
+  return url.pathname === '/' && !url.search && !url.hash ? formatted.replace(/\/$/, '') : formatted
+}
+
+const MOBILE_RPC_METHOD_ALLOWLIST = new Set([
+  'accounts.list',
+  'accounts.selectClaude',
+  'accounts.selectCodex',
+  'accounts.subscribe',
+  'accounts.unsubscribe',
+  'files.list',
+  'files.open',
+  'files.read',
+  'markdown.readTab',
+  'markdown.saveTab',
+  'notifications.subscribe',
+  'notifications.unsubscribe',
+  'repo.hooks',
+  'repo.list',
+  'session.tabs.activate',
+  'session.tabs.close',
+  'session.tabs.createTerminal',
+  'session.tabs.list',
+  'session.tabs.subscribe',
+  'session.tabs.unsubscribe',
+  'stats.summary',
+  'status.get',
+  'terminal.clearBuffer',
+  'terminal.close',
+  'terminal.create',
+  'terminal.focus',
+  'terminal.getAutoRestoreFit',
+  'terminal.list',
+  'terminal.multiplex',
+  'terminal.read',
+  'terminal.rename',
+  'terminal.send',
+  'terminal.setAutoRestoreFit',
+  'terminal.setDisplayMode',
+  'terminal.subscribe',
+  'terminal.unsubscribe',
+  'terminal.updateViewport',
+  'worktree.activate',
+  'worktree.create',
+  'worktree.ps',
+  'worktree.rm',
+  'worktree.set',
+  'worktree.sleep'
+])
+
 // Why: a long-poll request is one whose handler blocks for an unbounded
 // amount of time waiting for an external event (today, only
 // `orchestration.check` with `wait === true`). This function is the single
@@ -83,6 +171,7 @@ export class OrcaRuntimeRpcServer {
   private deviceRegistry: DeviceRegistry | null = null
   private e2eeKeypair: E2EEKeypair | null = null
   private tlsFingerprint: string | null = null
+  private wsTransport: WebSocketTransport | null = null
   private activeTransports: RpcTransport[] = []
   private transports: RuntimeTransportMetadata[] = []
   // Why: each WebSocket connection has its own E2EE channel that manages the
@@ -92,6 +181,10 @@ export class OrcaRuntimeRpcServer {
   // subscriptions, so the server can reap a closing socket's subscriptions
   // without affecting other live sockets that share the same deviceToken.
   private wsConnectionIds = new Map<WebSocket, string>()
+  private readonly binaryStreamHandlers = new Map<
+    string,
+    Map<number, (frame: TerminalStreamFrame) => void>
+  >()
   // Why: separate from Node's server.maxConnections because we need to count
   // only long-running dispatches, not every in-flight short RPC. See §3.1 +
   // §7 risk #2.
@@ -134,11 +227,87 @@ export class OrcaRuntimeRpcServer {
     return this.e2eeKeypair
   }
 
+  revokeMobileDevice(deviceId: string): boolean {
+    const device = this.deviceRegistry?.getDevice(deviceId)
+    if (device?.scope !== 'mobile' || !this.deviceRegistry?.removeDevice(deviceId)) {
+      return false
+    }
+    this.wsTransport?.terminateClientConnections(device.token)
+    return true
+  }
+
   getWebSocketEndpoint(): string | null {
     const ws = this.transports.find((t) => t.kind === 'websocket')
     return ws?.endpoint ?? null
   }
 
+  createPairingOffer(args: {
+    address?: string | null
+    name?: string
+    rotate?: boolean
+    scope?: DeviceScope
+  }):
+    | { available: false }
+    | { available: true; pairingUrl: string; endpoint: string; deviceId: string } {
+    const rawEndpoint = this.getWebSocketEndpoint()
+    const publicKeyB64 = this.getE2EEPublicKey()
+    if (!rawEndpoint || !this.deviceRegistry || !publicKeyB64) {
+      return { available: false }
+    }
+
+    const endpoint = resolvePairingEndpoint(rawEndpoint, args.address)
+    const deviceName = args.name ?? `CLI ${new Date().toLocaleDateString()}`
+    const scope = args.scope ?? 'runtime'
+    const device = args.rotate
+      ? this.deviceRegistry.rotatePendingDevice(deviceName, scope)
+      : this.deviceRegistry.getOrCreatePendingDevice(deviceName, scope)
+    const pairingUrl = encodePairingOffer({
+      v: PAIRING_OFFER_VERSION,
+      endpoint,
+      deviceToken: device.token,
+      publicKeyB64
+    })
+    return { available: true, pairingUrl, endpoint, deviceId: device.deviceId }
+  }
+
+  private registerBinaryStreamHandler(
+    connectionId: string | undefined,
+    streamId: number,
+    handler: (frame: TerminalStreamFrame) => void
+  ): () => void {
+    if (!connectionId || !Number.isInteger(streamId) || streamId < 0) {
+      return () => {}
+    }
+    let handlers = this.binaryStreamHandlers.get(connectionId)
+    if (!handlers) {
+      handlers = new Map()
+      this.binaryStreamHandlers.set(connectionId, handlers)
+    }
+    handlers.set(streamId, handler)
+    return () => {
+      const current = this.binaryStreamHandlers.get(connectionId)
+      if (!current || current.get(streamId) !== handler) {
+        return
+      }
+      current.delete(streamId)
+      if (current.size === 0) {
+        this.binaryStreamHandlers.delete(connectionId)
+      }
+    }
+  }
+
+  private handleWebSocketBinaryMessage(bytes: Uint8Array<ArrayBufferLike>, ws: WebSocket): void {
+    const connectionId = this.wsConnectionIds.get(ws)
+    if (!connectionId) {
+      return
+    }
+    const frame = decodeTerminalStreamFrame(bytes)
+    if (!frame) {
+      return
+    }
+    this.binaryStreamHandlers.get(connectionId)?.get(frame.streamId)?.(frame)
+  }
+
   async start(): Promise<void> {
     if (this.activeTransports.length > 0) {
       return
@@ -217,6 +386,7 @@ export class OrcaRuntimeRpcServer {
           host: '0.0.0.0',
           port: this.wsPort
         })
+        this.wsTransport = wsTransport
 
         // Why: each WebSocket connection gets an E2EE channel that handles the
         // handshake before any RPC messages are processed. The channel decrypts
@@ -259,6 +429,7 @@ export class OrcaRuntimeRpcServer {
                 ws
               )
             })
+            channel.onBinaryMessage((bytes) => this.handleWebSocketBinaryMessage(bytes, ws))
             this.e2eeChannels.set(ws, channel)
           }
           channel.handleRawMessage(msg)
@@ -279,6 +450,7 @@ export class OrcaRuntimeRpcServer {
           if (connectionId) {
             this.runtime.cleanupSubscriptionsForConnection(connectionId)
             this.runtime.cancelMobileDictationForConnection(connectionId)
+            this.binaryStreamHandlers.delete(connectionId)
             this.wsConnectionIds.delete(ws)
           }
           const channel = this.e2eeChannels.get(ws)
@@ -286,7 +458,7 @@ export class OrcaRuntimeRpcServer {
             channel.destroy()
             this.e2eeChannels.delete(ws)
           }
-          if (!hasOtherConnections) {
+          if (clientId && !hasOtherConnections) {
             this.runtime.onClientDisconnected(clientId)
           }
         })
@@ -302,6 +474,7 @@ export class OrcaRuntimeRpcServer {
         // function if it fails to start (e.g., port in use). Log and continue
         // with Unix socket only.
         console.error('[runtime] Failed to start WebSocket transport:', error)
+        this.wsTransport = null
       }
     }
 
@@ -328,6 +501,7 @@ export class OrcaRuntimeRpcServer {
     const transports = this.activeTransports
     this.activeTransports = []
     this.transports = []
+    this.wsTransport = null
     if (transports.length === 0) {
       return
     }
@@ -447,10 +621,23 @@ export class OrcaRuntimeRpcServer {
       reply(JSON.stringify(this.buildError(request.id, 'unauthorized', 'Missing device token')))
       return
     }
-    if (!this.deviceRegistry?.validateToken(token)) {
+    const device = this.deviceRegistry?.validateToken(token)
+    if (!device) {
       reply(JSON.stringify(this.buildError(request.id, 'unauthorized', 'Invalid device token')))
       return
     }
+    if (device.scope === 'mobile' && !MOBILE_RPC_METHOD_ALLOWLIST.has(request.method)) {
+      reply(
+        JSON.stringify(
+          this.buildError(
+            request.id,
+            'forbidden',
+            `Method '${request.method}' is not available to mobile clients`
+          )
+        )
+      )
+      return
+    }
 
     // Why: associate the deviceToken with this WebSocket so ws.on('close')
     // can notify the runtime which mobile client disconnected.
@@ -458,12 +645,54 @@ export class OrcaRuntimeRpcServer {
       wsTransport.setClientId(ws, token)
     }
 
+    const longPoll = isLongPollRequest(request)
+    if (longPoll && this.activeLongPolls >= this.longPollCap) {
+      reply(
+        JSON.stringify(
+          this.buildError(
+            request.id,
+            'runtime_busy',
+            'long-poll capacity reached; retry with backoff'
+          )
+        )
+      )
+      return
+    }
+
+    let abortController: AbortController | null = null
+    let abortOnClose: (() => void) | null = null
+    if (longPoll) {
+      this.activeLongPolls += 1
+      abortController = new AbortController()
+      if (ws) {
+        abortOnClose = () => abortController?.abort()
+        ws.once('close', abortOnClose)
+        ws.once('error', abortOnClose)
+        if (ws.readyState !== ws.OPEN) {
+          abortController.abort()
+        }
+      }
+    }
+
     const connectionId = ws ? this.wsConnectionIds.get(ws) : undefined
-    await this.dispatcher.dispatchStreaming(request, reply, {
-      connectionId,
-      clientId: token,
-      sendBinary
-    })
+    try {
+      await this.dispatcher.dispatchStreaming(request, reply, {
+        connectionId,
+        clientId: token,
+        signal: abortController?.signal,
+        sendBinary,
+        registerBinaryStreamHandler: (streamId, handler) =>
+          this.registerBinaryStreamHandler(connectionId, streamId, handler)
+      })
+    } finally {
+      if (abortOnClose && ws) {
+        ws.off('close', abortOnClose)
+        ws.off('error', abortOnClose)
+      }
+      if (longPoll) {
+        this.activeLongPolls = Math.max(0, this.activeLongPolls - 1)
+      }
+    }
   }
 
   private buildError(id: string, code: string, message: string): RpcResponse {
diff --git a/src/main/ssh/sftp-upload.test.ts b/src/main/ssh/sftp-upload.test.ts
new file mode 100644
index 00000000000..40676a34dc9
--- /dev/null
+++ b/src/main/ssh/sftp-upload.test.ts
@@ -0,0 +1,63 @@
+import { mkdtemp, mkdir, realpath, symlink, writeFile } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { Writable } from 'stream'
+import { describe, expect, it, vi } from 'vitest'
+import type { SFTPWrapper } from 'ssh2'
+import { uploadBuffer, uploadDirectory, uploadFile } from './sftp-upload'
+
+function createWritable(): Writable {
+  return new Writable({
+    write(_chunk, _encoding, callback) {
+      callback()
+    }
+  })
+}
+
+function createSftpMock(): SFTPWrapper {
+  return {
+    mkdir: vi.fn((_path: string, cb: (err?: Error | null) => void) => cb(null)),
+    createWriteStream: vi.fn(() => createWritable())
+  } as unknown as SFTPWrapper
+}
+
+describe('sftp-upload', () => {
+  it('can create the first binary upload chunk without clobbering an existing temp file', async () => {
+    const sftp = createSftpMock()
+
+    await uploadBuffer(sftp, Buffer.from('png'), '/remote/.logo.orca-upload', {
+      exclusive: true
+    })
+
+    expect(sftp.createWriteStream).toHaveBeenCalledWith('/remote/.logo.orca-upload', {
+      flags: 'wx'
+    })
+  })
+
+  it('uses no-clobber writes for nested files during exclusive directory upload', async () => {
+    const localDir = await mkdtemp(join(tmpdir(), 'orca-sftp-upload-'))
+    await mkdir(join(localDir, 'nested'))
+    await writeFile(join(localDir, 'nested', 'asset.txt'), 'asset')
+    const sftp = createSftpMock()
+
+    await uploadDirectory(sftp, localDir, '/remote/assets', await realpath(localDir), {
+      exclusive: true
+    })
+
+    expect(sftp.mkdir).toHaveBeenCalledWith('/remote/assets/nested', expect.any(Function))
+    expect(sftp.createWriteStream).toHaveBeenCalledWith('/remote/assets/nested/asset.txt', {
+      flags: 'wx'
+    })
+  })
+
+  it('does not create the remote file when the local source is a symlink', async () => {
+    const localDir = await mkdtemp(join(tmpdir(), 'orca-sftp-upload-'))
+    await writeFile(join(localDir, 'target.txt'), 'secret')
+    await symlink(join(localDir, 'target.txt'), join(localDir, 'link.txt'))
+    const sftp = createSftpMock()
+
+    await expect(uploadFile(sftp, join(localDir, 'link.txt'), '/remote/link.txt')).rejects.toThrow()
+
+    expect(sftp.createWriteStream).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/ssh/sftp-upload.ts b/src/main/ssh/sftp-upload.ts
index b7491542b64..b7dd3389590 100644
--- a/src/main/ssh/sftp-upload.ts
+++ b/src/main/ssh/sftp-upload.ts
@@ -1,16 +1,21 @@
-import { createReadStream } from 'fs'
-import { readdir } from 'fs/promises'
-import { join as pathJoin } from 'path'
+import { constants } from 'fs'
+import type { ReadStream } from 'fs'
+import { lstat, open, readdir, realpath } from 'fs/promises'
+import { isAbsolute, join as pathJoin, relative } from 'path'
 import type { SFTPWrapper } from 'ssh2'
 
-export function mkdirSftp(sftp: SFTPWrapper, path: string): Promise<void> {
+export function mkdirSftp(
+  sftp: SFTPWrapper,
+  path: string,
+  options?: { allowExisting?: boolean }
+): Promise<void> {
   return new Promise((resolve, reject) => {
     sftp.mkdir(path, (err) => {
       // Why: SFTP status code 4 (SSH_FX_FAILURE) is a generic code that
       // OpenSSH returns for "already exists," but could also cover other
       // failures (e.g. permission denied on parent). We accept this ambiguity
       // because the next operation (write/recurse) will surface the real error.
-      if (err && (err as { code?: number }).code !== 4) {
+      if (err && ((err as { code?: number }).code !== 4 || options?.allowExisting === false)) {
         reject(err)
       } else {
         resolve()
@@ -22,58 +27,131 @@ export function mkdirSftp(sftp: SFTPWrapper, path: string): Promise<void> {
 export function uploadFile(
   sftp: SFTPWrapper,
   localPath: string,
-  remotePath: string
+  remotePath: string,
+  options?: { exclusive?: boolean }
 ): Promise<void> {
   return new Promise((resolve, reject) => {
     let settled = false
-    const readStream = createReadStream(localPath)
-    const writeStream = sftp.createWriteStream(remotePath)
+    let readStream: ReadStream | null = null
+    let fileHandle: Awaited<ReturnType<typeof open>> | null = null
+    let writeStream: ReturnType<SFTPWrapper['createWriteStream']> | null = null
+
+    const settle = (fn: typeof resolve | typeof reject, val?: unknown): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      readStream?.destroy()
+      writeStream?.destroy()
+      void fileHandle?.close().catch(() => {})
+      fn(val as never)
+    }
+
+    void open(localPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+      .then(async (handle) => {
+        if (settled) {
+          void handle.close().catch(() => {})
+          return
+        }
+        fileHandle = handle
+        const statResult = await lstat(localPath)
+        if (statResult.isSymbolicLink() || !statResult.isFile()) {
+          throw new Error(`Unsupported upload source: ${localPath}`)
+        }
+        const openedStat = await handle.stat()
+        if (
+          !openedStat.isFile() ||
+          openedStat.size !== statResult.size ||
+          (statResult.ino !== 0 && openedStat.ino !== 0 && openedStat.ino !== statResult.ino) ||
+          (statResult.dev !== 0 && openedStat.dev !== 0 && openedStat.dev !== statResult.dev)
+        ) {
+          throw new Error(`File changed during upload: ${localPath}`)
+        }
+        // Why: validate the local source before creating the remote write
+        // target, so rejected sources do not leave empty files behind.
+        writeStream = sftp.createWriteStream(remotePath, {
+          flags: options?.exclusive ? 'wx' : 'w'
+        })
+        writeStream.on('close', () => settle(resolve))
+        writeStream.on('error', (err) => settle(reject, err))
+        readStream = handle.createReadStream()
+        readStream.on('error', (err) => settle(reject, err))
+        readStream.pipe(writeStream)
+      })
+      .catch((err: unknown) => settle(reject, err))
+  })
+}
+
+export function uploadBuffer(
+  sftp: SFTPWrapper,
+  buffer: Buffer,
+  remotePath: string,
+  options?: { append?: boolean; exclusive?: boolean }
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const writeStream = sftp.createWriteStream(remotePath, {
+      flags: options?.append ? 'a' : options?.exclusive ? 'wx' : 'w'
+    })
 
     const settle = (fn: typeof resolve | typeof reject, val?: unknown): void => {
       if (settled) {
         return
       }
       settled = true
-      readStream.destroy()
       writeStream.destroy()
       fn(val as never)
     }
 
     writeStream.on('close', () => settle(resolve))
     writeStream.on('error', (err) => settle(reject, err))
-    readStream.on('error', (err) => settle(reject, err))
-
-    readStream.pipe(writeStream)
+    writeStream.end(buffer)
   })
 }
 
 export async function uploadDirectory(
   sftp: SFTPWrapper,
   localDir: string,
-  remoteDir: string
+  remoteDir: string,
+  rootRealPath = localDir,
+  options?: { exclusive?: boolean }
 ): Promise<void> {
+  await assertLocalUploadPathInsideRoot(rootRealPath, localDir)
   const entries = await readdir(localDir, { withFileTypes: true })
   for (const entry of entries) {
     const localPath = pathJoin(localDir, entry.name)
     const remotePath = `${remoteDir}/${entry.name}`
+    await assertLocalUploadPathInsideRoot(rootRealPath, localPath)
+    const statResult = await lstat(localPath)
 
     // Why: skip symlinks and special files (sockets, FIFOs, devices) to
     // prevent following symlinks that could exfiltrate local files to the
     // remote. The caller's pre-scan catches symlinks up-front, but this
     // guard closes the TOCTOU gap if one is created between scan and upload.
-    if (entry.isSymbolicLink() || (!entry.isFile() && !entry.isDirectory())) {
+    if (statResult.isSymbolicLink() || (!statResult.isFile() && !statResult.isDirectory())) {
       continue
     }
 
-    if (entry.isDirectory()) {
-      await mkdirSftp(sftp, remotePath)
-      await uploadDirectory(sftp, localPath, remotePath)
+    if (statResult.isDirectory()) {
+      await mkdirSftp(sftp, remotePath, { allowExisting: !options?.exclusive })
+      await uploadDirectory(sftp, localPath, remotePath, rootRealPath, options)
     } else {
-      await uploadFile(sftp, localPath, remotePath)
+      await uploadFile(sftp, localPath, remotePath, { exclusive: options?.exclusive })
     }
   }
 }
 
+async function assertLocalUploadPathInsideRoot(
+  rootRealPath: string,
+  candidatePath: string
+): Promise<void> {
+  const candidateRealPath = await realpath(candidatePath)
+  const relativeToRoot = relative(rootRealPath, candidateRealPath)
+  if (relativeToRoot !== '' && (relativeToRoot.startsWith('..') || isAbsolute(relativeToRoot))) {
+    throw new Error(`Path escaped upload root: ${candidatePath}`)
+  }
+}
+
 /**
  * Check whether a path exists on the remote via SFTP lstat.
  * Returns true if the path exists (file, directory, or symlink).
diff --git a/src/main/ssh/ssh-relay-session.ts b/src/main/ssh/ssh-relay-session.ts
index d75807f86ce..cbccd4bb4ce 100644
--- a/src/main/ssh/ssh-relay-session.ts
+++ b/src/main/ssh/ssh-relay-session.ts
@@ -74,6 +74,7 @@ export class SshRelaySession {
     | null = null
   private _onReady: ((targetId: string) => void) | null = null
   private portScanner: PortScanner | null = null
+  private currentConnection: SshConnection | null = null
 
   constructor(
     readonly targetId: string,
@@ -113,6 +114,13 @@ export class SshRelaySession {
     return (this._state as RelaySessionState) === 'disposed'
   }
 
+  private requireReadyConnection(): SshConnection {
+    if (!this.currentConnection) {
+      throw new Error('SSH connection is not active')
+    }
+    return this.currentConnection
+  }
+
   getMux(): SshChannelMultiplexer | null {
     return this.mux
   }
@@ -129,6 +137,7 @@ export class SshRelaySession {
       throw new Error(`Cannot establish relay session in state: ${this._state}`)
     }
     this._state = 'deploying'
+    this.currentConnection = conn
 
     try {
       const { transport } = await deployAndLaunchRelay(
@@ -239,6 +248,7 @@ export class SshRelaySession {
     this.abortController = abortController
 
     this._state = 'reconnecting'
+    this.currentConnection = conn
 
     // Why: stop scanning before teardownProviders so the polling timer doesn't
     // fire against a disposed multiplexer.
@@ -371,6 +381,7 @@ export class SshRelaySession {
     this.broadcastEmptyLists()
     this.teardownProviders('shutdown')
     this.store.markSshRemotePtyLeases(this.targetId, 'terminated')
+    this.currentConnection = null
     this._state = 'disposed'
   }
 
@@ -386,6 +397,7 @@ export class SshRelaySession {
     // clearing PTY ownership needed for reattach.
     this.teardownProviders('connection_lost')
     this.store.markSshRemotePtyLeases(this.targetId, 'detached')
+    this.currentConnection = null
     this._state = 'disposed'
   }
 
@@ -427,7 +439,9 @@ export class SshRelaySession {
     const ptyProvider = new SshPtyProvider(this.targetId, mux)
     registerSshPtyProvider(this.targetId, ptyProvider)
 
-    const fsProvider = new SshFilesystemProvider(this.targetId, mux)
+    const fsProvider = new SshFilesystemProvider(this.targetId, mux, () =>
+      this.requireReadyConnection().sftp()
+    )
     registerSshFilesystemProvider(this.targetId, fsProvider)
 
     const gitProvider = new SshGitProvider(this.targetId, mux)
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index f46f7e977ce..533879c1fc7 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -85,6 +85,8 @@ import type {
   WorktreeStartupLaunch,
   WorkspaceSessionState
 } from '../shared/types'
+import type { PublicKnownRuntimeEnvironment } from '../shared/runtime-environments'
+import type { RuntimeRpcResponse } from '../shared/runtime-rpc-envelope'
 import type {
   AddIssueCommentBySlugArgs,
   ClearProjectItemFieldArgs,
@@ -139,6 +141,11 @@ import type { E2EConfig } from '../shared/e2e-config'
 import type { AgentHookInstallStatus } from '../shared/agent-hook-types'
 import type { AgentStatusIpcPayload } from '../shared/agent-status-types'
 import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../shared/runtime-types'
+
+type RuntimeEnvironmentSubscriptionHandle = {
+  unsubscribe: () => void
+  sendBinary: (bytes: Uint8Array<ArrayBufferLike>) => void
+}
 import type {
   RuntimeMobileMarkdownRequest,
   RuntimeMobileMarkdownResponse
@@ -1061,6 +1068,11 @@ export type PreloadApi = {
     createFile: (args: { filePath: string; connectionId?: string }) => Promise<void>
     createDir: (args: { dirPath: string; connectionId?: string }) => Promise<void>
     rename: (args: { oldPath: string; newPath: string; connectionId?: string }) => Promise<void>
+    copy: (args: {
+      sourcePath: string
+      destinationPath: string
+      connectionId?: string
+    }) => Promise<void>
     deletePath: (args: {
       targetPath: string
       connectionId?: string
@@ -1081,6 +1093,7 @@ export type PreloadApi = {
       sourcePaths: string[]
       destDir: string
       connectionId?: string
+      ensureDir?: boolean
     }) => Promise<{
       results: (
         | {
@@ -1102,6 +1115,30 @@ export type PreloadApi = {
           }
       )[]
     }>
+    stageExternalPathsForRuntimeUpload: (args: { sourcePaths: string[] }) => Promise<{
+      sources: (
+        | {
+            sourcePath: string
+            status: 'staged'
+            name: string
+            kind: 'file' | 'directory'
+            entries: (
+              | { relativePath: string; kind: 'directory' }
+              | { relativePath: string; kind: 'file'; contentBase64: string }
+            )[]
+          }
+        | {
+            sourcePath: string
+            status: 'skipped'
+            reason: 'missing' | 'symlink' | 'permission-denied' | 'unsupported'
+          }
+        | {
+            sourcePath: string
+            status: 'failed'
+            reason: string
+          }
+      )[]
+    }>
     resolveDroppedPathsForAgent: (args: {
       paths: string[]
       worktreePath: string
@@ -1357,6 +1394,7 @@ export type PreloadApi = {
   runtime: {
     syncWindowGraph: (graph: RuntimeSyncWindowGraph) => Promise<RuntimeStatus>
     getStatus: () => Promise<RuntimeStatus>
+    call: (args: { method: string; params?: unknown }) => Promise<RuntimeRpcResponse<unknown>>
     getTerminalFitOverrides: () => Promise<
       { ptyId: string; mode: 'mobile-fit'; cols: number; rows: number }[]
     >
@@ -1376,6 +1414,39 @@ export type PreloadApi = {
       }) => void
     ) => () => void
   }
+  runtimeEnvironments: {
+    list: () => Promise<PublicKnownRuntimeEnvironment[]>
+    addFromPairingCode: (args: {
+      name: string
+      pairingCode: string
+    }) => Promise<{ environment: PublicKnownRuntimeEnvironment }>
+    resolve: (args: { selector: string }) => Promise<PublicKnownRuntimeEnvironment>
+    remove: (args: { selector: string }) => Promise<{ removed: PublicKnownRuntimeEnvironment }>
+    getStatus: (args: {
+      selector: string
+      timeoutMs?: number
+    }) => Promise<RuntimeRpcResponse<RuntimeStatus>>
+    call: (args: {
+      selector: string
+      method: string
+      params?: unknown
+      timeoutMs?: number
+    }) => Promise<RuntimeRpcResponse<unknown>>
+    subscribe: (
+      args: {
+        selector: string
+        method: string
+        params?: unknown
+        timeoutMs?: number
+      },
+      callbacks: {
+        onResponse: (response: RuntimeRpcResponse<unknown>) => void
+        onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+        onError?: (error: { code: string; message: string }) => void
+        onClose?: () => void
+      }
+    ) => Promise<RuntimeEnvironmentSubscriptionHandle>
+  }
   rateLimits: {
     get: () => Promise<RateLimitState>
     refresh: () => Promise<RateLimitState>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index c744b23d047..b9b5d34d123 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -33,6 +33,8 @@ import type {
   WorktreeRemoteBranchConflictEvent
 } from '../shared/types'
 import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../shared/runtime-types'
+import type { RuntimeRpcResponse } from '../shared/runtime-rpc-envelope'
+import type { PublicKnownRuntimeEnvironment } from '../shared/runtime-environments'
 import type {
   RuntimeMobileMarkdownRequest,
   RuntimeMobileMarkdownResponse
@@ -98,6 +100,8 @@ import {
   ORCA_UPDATER_QUIT_AND_INSTALL_ABORTED_EVENT,
   ORCA_UPDATER_QUIT_AND_INSTALL_STARTED_EVENT
 } from '../shared/updater-renderer-events'
+import { subscribeRuntimeEnvironmentFromPreload } from './runtime-environment-subscriptions'
+import type { RuntimeEnvironmentSubscriptionHandle } from './runtime-environment-subscriptions'
 import type { HostedReviewForBranchArgs } from '../shared/hosted-review'
 
 type NativeDropResolution =
@@ -1631,6 +1635,11 @@ const api = {
       ipcRenderer.invoke('fs:createDir', args),
     rename: (args: { oldPath: string; newPath: string; connectionId?: string }): Promise<void> =>
       ipcRenderer.invoke('fs:rename', args),
+    copy: (args: {
+      sourcePath: string
+      destinationPath: string
+      connectionId?: string
+    }): Promise<void> => ipcRenderer.invoke('fs:copy', args),
     deletePath: (args: {
       targetPath: string
       connectionId?: string
@@ -1663,6 +1672,7 @@ const api = {
       sourcePaths: string[]
       destDir: string
       connectionId?: string
+      ensureDir?: boolean
     }): Promise<{
       results: (
         | {
@@ -1684,6 +1694,32 @@ const api = {
           }
       )[]
     }> => ipcRenderer.invoke('fs:importExternalPaths', args),
+    stageExternalPathsForRuntimeUpload: (args: {
+      sourcePaths: string[]
+    }): Promise<{
+      sources: (
+        | {
+            sourcePath: string
+            status: 'staged'
+            name: string
+            kind: 'file' | 'directory'
+            entries: (
+              | { relativePath: string; kind: 'directory' }
+              | { relativePath: string; kind: 'file'; contentBase64: string }
+            )[]
+          }
+        | {
+            sourcePath: string
+            status: 'skipped'
+            reason: 'missing' | 'symlink' | 'permission-denied' | 'unsupported'
+          }
+        | {
+            sourcePath: string
+            status: 'failed'
+            reason: string
+          }
+      )[]
+    }> => ipcRenderer.invoke('fs:stageExternalPathsForRuntimeUpload', args),
     resolveDroppedPathsForAgent: (args: {
       paths: string[]
       worktreePath: string
@@ -2277,6 +2313,8 @@ const api = {
     syncWindowGraph: (graph: RuntimeSyncWindowGraph): Promise<RuntimeStatus> =>
       ipcRenderer.invoke('runtime:syncWindowGraph', graph),
     getStatus: (): Promise<RuntimeStatus> => ipcRenderer.invoke('runtime:getStatus'),
+    call: (args: { method: string; params?: unknown }): Promise<RuntimeRpcResponse<unknown>> =>
+      ipcRenderer.invoke('runtime:call', args),
     getTerminalFitOverrides: (): Promise<
       { ptyId: string; mode: 'mobile-fit'; cols: number; rows: number }[]
     > => ipcRenderer.invoke('runtime:getTerminalFitOverrides'),
@@ -2315,6 +2353,47 @@ const api = {
     }
   },
 
+  runtimeEnvironments: {
+    list: (): Promise<PublicKnownRuntimeEnvironment[]> =>
+      ipcRenderer.invoke('runtimeEnvironments:list'),
+    addFromPairingCode: (args: {
+      name: string
+      pairingCode: string
+    }): Promise<{ environment: PublicKnownRuntimeEnvironment }> =>
+      ipcRenderer.invoke('runtimeEnvironments:addFromPairingCode', args),
+    resolve: (args: { selector: string }): Promise<PublicKnownRuntimeEnvironment> =>
+      ipcRenderer.invoke('runtimeEnvironments:resolve', args),
+    remove: (args: { selector: string }): Promise<{ removed: PublicKnownRuntimeEnvironment }> =>
+      ipcRenderer.invoke('runtimeEnvironments:remove', args),
+    getStatus: (args: {
+      selector: string
+      timeoutMs?: number
+    }): Promise<RuntimeRpcResponse<RuntimeStatus>> =>
+      ipcRenderer.invoke('runtimeEnvironments:getStatus', args),
+    call: (args: {
+      selector: string
+      method: string
+      params?: unknown
+      timeoutMs?: number
+    }): Promise<RuntimeRpcResponse<unknown>> =>
+      ipcRenderer.invoke('runtimeEnvironments:call', args),
+    subscribe: async (
+      args: {
+        selector: string
+        method: string
+        params?: unknown
+        timeoutMs?: number
+      },
+      callbacks: {
+        onResponse: (response: RuntimeRpcResponse<unknown>) => void
+        onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+        onError?: (error: { code: string; message: string }) => void
+        onClose?: () => void
+      }
+    ): Promise<RuntimeEnvironmentSubscriptionHandle> =>
+      subscribeRuntimeEnvironmentFromPreload(ipcRenderer, args, callbacks)
+  },
+
   rateLimits: {
     get: (): Promise<RateLimitState> => ipcRenderer.invoke('rateLimits:get'),
     refresh: (): Promise<RateLimitState> => ipcRenderer.invoke('rateLimits:refresh'),
diff --git a/src/preload/runtime-environment-subscriptions.test.ts b/src/preload/runtime-environment-subscriptions.test.ts
new file mode 100644
index 00000000000..31c4447e616
--- /dev/null
+++ b/src/preload/runtime-environment-subscriptions.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest'
+import { subscribeRuntimeEnvironmentFromPreload } from './runtime-environment-subscriptions'
+
+function deferred<T>(): {
+  promise: Promise<T>
+  resolve: (value: T) => void
+  reject: (error: unknown) => void
+} {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve
+    reject = promiseReject
+  })
+  return { promise, resolve, reject }
+}
+
+describe('subscribeRuntimeEnvironmentFromPreload', () => {
+  it('registers the subscription event listener before invoking main', async () => {
+    const subscription = deferred<{ subscriptionId: string; requestId: string }>()
+    const invoke = vi.fn(() => subscription.promise as Promise<unknown>)
+    const send = vi.fn()
+    const on = vi.fn()
+    const removeListener = vi.fn()
+    const onResponse = vi.fn()
+
+    const cleanupPromise = subscribeRuntimeEnvironmentFromPreload(
+      { invoke, send, on, removeListener },
+      { selector: 'desk', method: 'terminal.subscribe' },
+      { onResponse },
+      () => 'sub-1'
+    )
+
+    expect(on).toHaveBeenCalledWith('runtimeEnvironments:subscriptionEvent', expect.any(Function))
+    expect(invoke).toHaveBeenCalledWith('runtimeEnvironments:subscribe', {
+      selector: 'desk',
+      method: 'terminal.subscribe',
+      subscriptionId: 'sub-1'
+    })
+
+    const listener = on.mock.calls[0][1] as (
+      _event: unknown,
+      payload: {
+        subscriptionId: string
+        type: 'response'
+        response: { ok: true; id: string; result: unknown; _meta: { runtimeId: string } }
+      }
+    ) => void
+    listener(null, {
+      subscriptionId: 'sub-1',
+      type: 'response',
+      response: {
+        id: 'rpc-1',
+        ok: true,
+        result: { type: 'subscribed' },
+        _meta: { runtimeId: 'rt' }
+      }
+    })
+    expect(onResponse).toHaveBeenCalledWith({
+      id: 'rpc-1',
+      ok: true,
+      result: { type: 'subscribed' },
+      _meta: { runtimeId: 'rt' }
+    })
+
+    subscription.resolve({ subscriptionId: 'sub-1', requestId: 'rpc-1' })
+    const cleanup = await cleanupPromise
+    const bytes = new Uint8Array([1, 2, 3])
+    cleanup.sendBinary(bytes)
+    expect(send).toHaveBeenCalledWith('runtimeEnvironments:subscriptionBinary', {
+      subscriptionId: 'sub-1',
+      bytes
+    })
+    cleanup.unsubscribe()
+    expect(removeListener).toHaveBeenCalledWith('runtimeEnvironments:subscriptionEvent', listener)
+    expect(invoke).toHaveBeenCalledWith('runtimeEnvironments:unsubscribe', {
+      subscriptionId: 'sub-1'
+    })
+  })
+
+  it('removes the listener when main rejects the subscribe call', async () => {
+    const subscription = deferred<{ subscriptionId: string; requestId: string }>()
+    const invoke = vi.fn(() => subscription.promise as Promise<unknown>)
+    const send = vi.fn()
+    const on = vi.fn()
+    const removeListener = vi.fn()
+
+    const cleanupPromise = subscribeRuntimeEnvironmentFromPreload(
+      { invoke, send, on, removeListener },
+      { selector: 'desk', method: 'terminal.subscribe' },
+      { onResponse: vi.fn() },
+      () => 'sub-2'
+    )
+
+    const error = new Error('subscribe failed')
+    subscription.reject(error)
+    await expect(cleanupPromise).rejects.toThrow(error)
+    expect(removeListener).toHaveBeenCalledWith(
+      'runtimeEnvironments:subscriptionEvent',
+      on.mock.calls[0][1]
+    )
+  })
+})
diff --git a/src/preload/runtime-environment-subscriptions.ts b/src/preload/runtime-environment-subscriptions.ts
new file mode 100644
index 00000000000..d9c30325bd3
--- /dev/null
+++ b/src/preload/runtime-environment-subscriptions.ts
@@ -0,0 +1,99 @@
+import type { RuntimeRpcResponse } from '../shared/runtime-rpc-envelope'
+
+type RuntimeEnvironmentSubscribeArgs = {
+  selector: string
+  method: string
+  params?: unknown
+  timeoutMs?: number
+}
+
+type RuntimeEnvironmentSubscriptionCallbacks = {
+  onResponse: (response: RuntimeRpcResponse<unknown>) => void
+  onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+  onError?: (error: { code: string; message: string }) => void
+  onClose?: () => void
+}
+
+export type RuntimeEnvironmentSubscriptionHandle = {
+  unsubscribe: () => void
+  sendBinary: (bytes: Uint8Array<ArrayBufferLike>) => void
+}
+
+type RuntimeEnvironmentSubscriptionEvent =
+  | { subscriptionId: string; type: 'response'; response: RuntimeRpcResponse<unknown> }
+  | { subscriptionId: string; type: 'binary'; bytes: Uint8Array<ArrayBufferLike> }
+  | { subscriptionId: string; type: 'error'; code: string; message: string }
+  | { subscriptionId: string; type: 'close' }
+
+type RuntimeEnvironmentSubscriptionIpc = {
+  invoke: (channel: string, args: unknown) => Promise<unknown>
+  send: (channel: string, args: unknown) => void
+  on: (
+    channel: string,
+    listener: (event: unknown, payload: RuntimeEnvironmentSubscriptionEvent) => void
+  ) => void
+  removeListener: (
+    channel: string,
+    listener: (event: unknown, payload: RuntimeEnvironmentSubscriptionEvent) => void
+  ) => void
+}
+
+const SUBSCRIPTION_EVENT_CHANNEL = 'runtimeEnvironments:subscriptionEvent'
+
+function createRuntimeEnvironmentSubscriptionId(): string {
+  const randomUuid = globalThis.crypto?.randomUUID
+  if (typeof randomUuid === 'function') {
+    return randomUuid.call(globalThis.crypto)
+  }
+  return `sub-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+export async function subscribeRuntimeEnvironmentFromPreload(
+  ipc: RuntimeEnvironmentSubscriptionIpc,
+  args: RuntimeEnvironmentSubscribeArgs,
+  callbacks: RuntimeEnvironmentSubscriptionCallbacks,
+  createSubscriptionId = createRuntimeEnvironmentSubscriptionId
+): Promise<RuntimeEnvironmentSubscriptionHandle> {
+  const subscriptionId = createSubscriptionId()
+  const listener = (_event: unknown, event: RuntimeEnvironmentSubscriptionEvent): void => {
+    if (event.subscriptionId !== subscriptionId) {
+      return
+    }
+    if (event.type === 'response') {
+      callbacks.onResponse(event.response)
+    } else if (event.type === 'binary') {
+      callbacks.onBinary?.(event.bytes)
+    } else if (event.type === 'error') {
+      callbacks.onError?.({ code: event.code, message: event.message })
+    } else {
+      callbacks.onClose?.()
+    }
+  }
+
+  // Why: streaming RPCs can emit their first frame before ipcMain.handle()
+  // resolves, so preload must subscribe to the event channel before invoking.
+  ipc.on(SUBSCRIPTION_EVENT_CHANNEL, listener)
+  try {
+    const result = (await ipc.invoke('runtimeEnvironments:subscribe', {
+      ...args,
+      subscriptionId
+    })) as { subscriptionId: string; requestId: string }
+    if (result.subscriptionId !== subscriptionId) {
+      ipc.removeListener(SUBSCRIPTION_EVENT_CHANNEL, listener)
+      throw new Error('Runtime environment subscription id mismatch')
+    }
+  } catch (error) {
+    ipc.removeListener(SUBSCRIPTION_EVENT_CHANNEL, listener)
+    throw error
+  }
+
+  return {
+    unsubscribe: () => {
+      ipc.removeListener(SUBSCRIPTION_EVENT_CHANNEL, listener)
+      void ipc.invoke('runtimeEnvironments:unsubscribe', { subscriptionId })
+    },
+    sendBinary: (bytes) => {
+      ipc.send('runtimeEnvironments:subscriptionBinary', { subscriptionId, bytes })
+    }
+  }
+}
diff --git a/src/relay/fs-handler.test.ts b/src/relay/fs-handler.test.ts
index ed9120d54d6..590e9ea4665 100644
--- a/src/relay/fs-handler.test.ts
+++ b/src/relay/fs-handler.test.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: this suite covers relay filesystem RPCs,
+   file watcher lifecycle edges, and cross-platform path behavior together. */
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { FsHandler } from './fs-handler'
 import { RelayContext } from './context'
@@ -93,6 +95,7 @@ describe('FsHandler', () => {
     expect(methods).toContain('fs.deletePath')
     expect(methods).toContain('fs.createFile')
     expect(methods).toContain('fs.createDir')
+    expect(methods).toContain('fs.createDirNoClobber')
     expect(methods).toContain('fs.rename')
     expect(methods).toContain('fs.copy')
     expect(methods).toContain('fs.realpath')
@@ -268,6 +271,13 @@ describe('FsHandler', () => {
     expect(stats.isDirectory()).toBe(true)
   })
 
+  it('createDirNoClobber fails when the directory already exists', async () => {
+    const dirPath = path.join(tmpDir, 'existing')
+    mkdirSync(dirPath)
+
+    await expect(dispatcher.callRequest('fs.createDirNoClobber', { dirPath })).rejects.toThrow()
+  })
+
   it('rename moves files', async () => {
     const oldPath = path.join(tmpDir, 'old.txt')
     const newPath = path.join(tmpDir, 'new.txt')
@@ -291,6 +301,20 @@ describe('FsHandler', () => {
     expect(content).toBe('original')
   })
 
+  it('copy does not overwrite an existing destination', async () => {
+    const src = path.join(tmpDir, 'src.txt')
+    const dst = path.join(tmpDir, 'dst.txt')
+    writeFileSync(src, 'original')
+    writeFileSync(dst, 'existing')
+
+    await expect(
+      dispatcher.callRequest('fs.copy', { source: src, destination: dst })
+    ).rejects.toThrow('EEXIST')
+
+    const content = await fs.readFile(dst, 'utf-8')
+    expect(content).toBe('existing')
+  })
+
   it('realpath resolves symlinks', async () => {
     const realFile = path.join(tmpDir, 'real.txt')
     const linkPath = path.join(tmpDir, 'link.txt')
@@ -332,4 +356,44 @@ describe('FsHandler', () => {
     dispatcher.callNotification('fs.unwatch', { rootPath: tmpDir })
     expect(secondUnsubscribe).toHaveBeenCalled()
   })
+
+  it('unsubscribes an active stale watch before replacing it', async () => {
+    const firstUnsubscribe = vi.fn()
+    const secondUnsubscribe = vi.fn()
+    mockSubscribe
+      .mockResolvedValueOnce({ unsubscribe: firstUnsubscribe })
+      .mockResolvedValueOnce({ unsubscribe: secondUnsubscribe })
+
+    let stale = false
+    await dispatcher.callRequest('fs.watch', { rootPath: tmpDir }, { isStale: () => stale })
+    stale = true
+    await dispatcher.callRequest('fs.watch', { rootPath: tmpDir }, { isStale: () => false })
+
+    expect(firstUnsubscribe).toHaveBeenCalled()
+    expect(secondUnsubscribe).not.toHaveBeenCalled()
+    dispatcher.callNotification('fs.unwatch', { rootPath: tmpDir })
+    expect(secondUnsubscribe).toHaveBeenCalled()
+  })
+
+  it('replaces a stale watch for the same root before enforcing the watch cap', async () => {
+    const firstUnsubscribe = vi.fn()
+    const replacementUnsubscribe = vi.fn()
+    mockSubscribe
+      .mockResolvedValueOnce({ unsubscribe: firstUnsubscribe })
+      .mockResolvedValueOnce({ unsubscribe: replacementUnsubscribe })
+
+    let stale = false
+    await dispatcher.callRequest('fs.watch', { rootPath: tmpDir }, { isStale: () => stale })
+    for (let index = 0; index < 19; index++) {
+      await dispatcher.callRequest('fs.watch', {
+        rootPath: path.join(tmpDir, `watched-${index}`)
+      })
+    }
+
+    stale = true
+    await dispatcher.callRequest('fs.watch', { rootPath: tmpDir }, { isStale: () => false })
+
+    expect(firstUnsubscribe).toHaveBeenCalled()
+    expect(replacementUnsubscribe).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/relay/fs-handler.ts b/src/relay/fs-handler.ts
index 6f29861826c..3bedb3c856b 100644
--- a/src/relay/fs-handler.ts
+++ b/src/relay/fs-handler.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: relay filesystem request handling shares
+   path expansion, file IO, search, streaming reads, and watch lifecycle state. */
 import { readdir, writeFile, stat, lstat, mkdir, rename, cp, rm, realpath } from 'fs/promises'
 import { execFile } from 'child_process'
 import { join } from 'path'
@@ -64,6 +66,7 @@ export class FsHandler {
     this.dispatcher.onRequest('fs.deletePath', (p) => this.deletePath(p))
     this.dispatcher.onRequest('fs.createFile', (p) => this.createFile(p))
     this.dispatcher.onRequest('fs.createDir', (p) => this.createDir(p))
+    this.dispatcher.onRequest('fs.createDirNoClobber', (p) => this.createDirNoClobber(p))
     this.dispatcher.onRequest('fs.rename', (p) => this.rename(p))
     this.dispatcher.onRequest('fs.copy', (p) => this.copy(p))
     this.dispatcher.onRequest('fs.realpath', (p) => this.realpath(p))
@@ -175,6 +178,11 @@ export class FsHandler {
     await mkdir(dirPath, { recursive: true })
   }
 
+  private async createDirNoClobber(params: Record<string, unknown>) {
+    const dirPath = expandTilde(params.dirPath as string)
+    await mkdir(dirPath, { recursive: false })
+  }
+
   private async rename(params: Record<string, unknown>) {
     const oldPath = expandTilde(params.oldPath as string)
     const newPath = expandTilde(params.newPath as string)
@@ -184,7 +192,15 @@ export class FsHandler {
   private async copy(params: Record<string, unknown>) {
     const source = expandTilde(params.source as string)
     const destination = expandTilde(params.destination as string)
-    await cp(source, destination, { recursive: true })
+    try {
+      await cp(source, destination, { recursive: true, force: false, errorOnExist: true })
+    } catch (error) {
+      const code = error instanceof Error ? (error as NodeJS.ErrnoException).code : undefined
+      if (code === 'EEXIST' || code === 'ERR_FS_CP_EEXIST') {
+        throw new Error('EEXIST: destination already exists')
+      }
+      throw error
+    }
   }
 
   private async realpath(params: Record<string, unknown>) {
@@ -266,10 +282,6 @@ export class FsHandler {
   private async watch(params: Record<string, unknown>, context?: RequestContext) {
     const rootPath = expandTilde(params.rootPath as string)
 
-    if (this.watches.size >= 20) {
-      throw new Error('Maximum number of file watchers reached')
-    }
-
     const existing = this.watches.get(rootPath)
     if (existing && !existing.isStale()) {
       if (existing.setupPromise) {
@@ -277,6 +289,14 @@ export class FsHandler {
       }
       return
     }
+    if (existing?.isStale()) {
+      existing.unwatchFn?.()
+      this.watches.delete(rootPath)
+    }
+
+    if (this.watches.size >= 20) {
+      throw new Error('Maximum number of file watchers reached')
+    }
 
     const watchState: WatchState = {
       rootPath,
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index b70bbbd11c0..68642e47ec1 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -368,6 +368,10 @@ function App(): React.JSX.Element {
     let reconnectStarted = false
     void (async () => {
       try {
+        // Why: repo/worktree hydration routes through settings.activeRuntimeEnvironmentId.
+        // Load settings first so a persisted remote runtime does not boot against
+        // the local filesystem and then hydrate stale local workspace state.
+        await actions.fetchSettings()
         await actions.fetchRepos()
         await actions.fetchAllWorktrees()
         const persistedUI = await window.api.ui.get()
@@ -377,10 +381,6 @@ function App(): React.JSX.Element {
           hydratePersistedUI: actions.hydratePersistedUI
         })
         const session = await window.api.session.get()
-        // Why: settings must be loaded before hydrateWorkspaceSession so that
-        // hydration has access to user preferences. Without this, settings
-        // would still be null at hydration time.
-        await actions.fetchSettings()
         if (!cancelled) {
           actions.hydrateWorkspaceSession(session)
           actions.hydrateTabsSession(session)
diff --git a/src/renderer/src/app-startup-routing.test.ts b/src/renderer/src/app-startup-routing.test.ts
new file mode 100644
index 00000000000..67e92fca0a4
--- /dev/null
+++ b/src/renderer/src/app-startup-routing.test.ts
@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+describe('renderer startup runtime routing', () => {
+  it('loads settings before repo and worktree hydration', () => {
+    const source = readFileSync(join(process.cwd(), 'src/renderer/src/App.tsx'), 'utf8')
+    const startupBlockStart = source.indexOf('void (async () => {')
+    const startupBlockEnd = source.indexOf('const persistedUI = await window.api.ui.get()')
+    const startupBlock = source.slice(startupBlockStart, startupBlockEnd)
+
+    expect(startupBlock.indexOf('await actions.fetchSettings()')).toBeGreaterThanOrEqual(0)
+    expect(startupBlock.indexOf('await actions.fetchSettings()')).toBeLessThan(
+      startupBlock.indexOf('await actions.fetchRepos()')
+    )
+    expect(startupBlock.indexOf('await actions.fetchSettings()')).toBeLessThan(
+      startupBlock.indexOf('await actions.fetchAllWorktrees()')
+    )
+  })
+})
diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index b8cd117d62e..0e735654c76 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -70,6 +70,7 @@ import {
   type PRCommentGroup
 } from '@/lib/pr-comment-groups'
 import { useAppStore } from '@/store'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { useRepoLabels, useRepoAssignees, useImmediateMutation } from '@/hooks/useIssueMetadata'
 import { useRepoLabelsBySlug, useRepoAssigneesBySlug } from '@/hooks/useGitHubSlugMetadata'
 import IssueSourceIndicator, { sameGitHubOwnerRepo } from '@/components/github/IssueSourceIndicator'
@@ -371,6 +372,7 @@ function findNearestBraceBlock(
 
 type FileRowProps = {
   file: GitHubPRFile
+  repoId?: string
   repoPath: string
   prNumber: number
   headSha: string | undefined
@@ -384,6 +386,7 @@ type DiffViewMode = 'flat' | 'tree'
 type DiffTreeNodeProps = {
   node: DiffTreeNode
   depth: number
+  repoId?: string
   repoPath: string
   prNumber: number
   headSha: string | undefined
@@ -394,6 +397,7 @@ type DiffTreeNodeProps = {
 function PRDiffTreeNode({
   node,
   depth,
+  repoId,
   repoPath,
   prNumber,
   headSha,
@@ -406,6 +410,7 @@ function PRDiffTreeNode({
     return (
       <PRFileRow
         file={node.file}
+        repoId={repoId}
         repoPath={repoPath}
         prNumber={prNumber}
         headSha={headSha}
@@ -452,6 +457,7 @@ function PRDiffTreeNode({
               key={child.kind === 'file' ? child.file.path : child.path}
               node={child}
               depth={depth + 1}
+              repoId={repoId}
               repoPath={repoPath}
               prNumber={prNumber}
               headSha={headSha}
@@ -467,6 +473,7 @@ function PRDiffTreeNode({
 
 type PRDiffTreeViewProps = {
   files: GitHubPRFile[]
+  repoId?: string
   repoPath: string
   prNumber: number
   headSha: string | undefined
@@ -476,6 +483,7 @@ type PRDiffTreeViewProps = {
 
 function PRDiffTreeView({
   files,
+  repoId,
   repoPath,
   prNumber,
   headSha,
@@ -490,6 +498,7 @@ function PRDiffTreeView({
           key={node.kind === 'file' ? node.file.path : node.path}
           node={node}
           depth={0}
+          repoId={repoId}
           repoPath={repoPath}
           prNumber={prNumber}
           headSha={headSha}
@@ -536,6 +545,7 @@ function notifyWorkItemDetailsCache(): void {
 }
 
 function getWorkItemDetailsCacheKey(args: {
+  runtimeScope: string
   repoPath: string
   issueSourcePreference: string | undefined
   type: 'issue' | 'pr'
@@ -543,7 +553,13 @@ function getWorkItemDetailsCacheKey(args: {
 }): string {
   // Why: include all axes that change which (repo, item) the IPC resolves to.
   // `\0` separator avoids ambiguity between fields that may contain `:` or `/`.
-  return [args.repoPath, args.issueSourcePreference ?? 'auto', args.type, args.number].join('\0')
+  return [
+    args.runtimeScope,
+    args.repoPath,
+    args.issueSourcePreference ?? 'auto',
+    args.type,
+    args.number
+  ].join('\0')
 }
 
 function touchWorkItemDetailsCache(key: string, entry: WorkItemDetailsCacheEntry): void {
@@ -590,11 +606,10 @@ function invalidateWorkItemDetailsCacheByMatch(args: {
   number: number
 }): void {
   workItemDetailsCacheGeneration += 1
-  const suffix = `\0${args.type}\0${args.number}`
-  const prefix = `${args.repoPath}\0`
   let removed = false
   for (const key of Array.from(workItemDetailsCache.keys())) {
-    if (key.startsWith(prefix) && key.endsWith(suffix)) {
+    const [, repoPath, , type, number] = key.split('\0')
+    if (repoPath === args.repoPath && type === args.type && number === String(args.number)) {
       workItemDetailsCache.delete(key)
       removed = true
     }
@@ -648,6 +663,7 @@ function touchPRFileContentCache(
 }
 
 function getPRFileContentCacheKey(args: {
+  repoId?: string
   repoPath: string
   prNumber: number
   file: GitHubPRFile
@@ -655,6 +671,7 @@ function getPRFileContentCacheKey(args: {
   baseSha: string
 }): string {
   return [
+    args.repoId ?? '',
     args.repoPath,
     args.prNumber,
     args.file.path,
@@ -666,6 +683,7 @@ function getPRFileContentCacheKey(args: {
 }
 
 function loadPRFileContents(args: {
+  repoId?: string
   repoPath: string
   prNumber: number
   file: GitHubPRFile
@@ -678,16 +696,33 @@ function loadPRFileContents(args: {
     touchPRFileContentCache(cacheKey, cached)
     return Promise.resolve(cached)
   }
-  const request = window.api.gh
-    .prFileContents({
-      repoPath: args.repoPath,
-      prNumber: args.prNumber,
-      path: args.file.path,
-      oldPath: args.file.oldPath,
-      status: args.file.status,
-      headSha: args.headSha,
-      baseSha: args.baseSha
-    })
+  const target = getRuntimeTargetForRepoId(args.repoId)
+  const request = (
+    target
+      ? callRuntimeRpc<GitHubPRFileContents>(
+          target,
+          'github.prFileContents',
+          {
+            repo: args.repoId,
+            prNumber: args.prNumber,
+            path: args.file.path,
+            oldPath: args.file.oldPath,
+            status: args.file.status,
+            headSha: args.headSha,
+            baseSha: args.baseSha
+          },
+          { timeoutMs: 30_000 }
+        )
+      : window.api.gh.prFileContents({
+          repoPath: args.repoPath,
+          prNumber: args.prNumber,
+          path: args.file.path,
+          oldPath: args.file.oldPath,
+          status: args.file.status,
+          headSha: args.headSha,
+          baseSha: args.baseSha
+        })
+  )
     .then((contents) => {
       touchPRFileContentCache(cacheKey, contents)
       return contents
@@ -700,8 +735,143 @@ function loadPRFileContents(args: {
   return request
 }
 
+function getRuntimeTargetForRepoId(repoId: string | null | undefined) {
+  if (!repoId) {
+    return null
+  }
+  const state = useAppStore.getState()
+  const target = getActiveRuntimeTarget(state.settings)
+  if (target.kind !== 'environment') {
+    return null
+  }
+  return state.repos.some((repo) => repo.id === repoId) ? target : null
+}
+
+function addIssueCommentForRepo(args: {
+  repoId?: string
+  repoPath: string
+  number: number
+  body: string
+  type?: 'issue' | 'pr'
+}): Promise<Awaited<ReturnType<typeof window.api.gh.addIssueComment>>> {
+  const target = getRuntimeTargetForRepoId(args.repoId)
+  if (target) {
+    return callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.addIssueComment>>>(
+      target,
+      'github.addIssueComment',
+      { repo: args.repoId, number: args.number, body: args.body, type: args.type },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.addIssueComment({
+    repoPath: args.repoPath,
+    number: args.number,
+    body: args.body,
+    type: args.type
+  })
+}
+
+function addPRReviewCommentForRepo(args: {
+  repoId?: string
+  repoPath: string
+  prNumber: number
+  commitId: string
+  path: string
+  line: number
+  startLine?: number
+  body: string
+}): Promise<Awaited<ReturnType<typeof window.api.gh.addPRReviewComment>>> {
+  const target = getRuntimeTargetForRepoId(args.repoId)
+  if (target) {
+    return callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.addPRReviewComment>>>(
+      target,
+      'github.addPRReviewComment',
+      {
+        repo: args.repoId,
+        prNumber: args.prNumber,
+        commitId: args.commitId,
+        path: args.path,
+        line: args.line,
+        startLine: args.startLine,
+        body: args.body
+      },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.addPRReviewComment({
+    repoPath: args.repoPath,
+    prNumber: args.prNumber,
+    commitId: args.commitId,
+    path: args.path,
+    line: args.line,
+    startLine: args.startLine,
+    body: args.body
+  })
+}
+
+function addPRReviewCommentReplyForRepo(args: {
+  repoId?: string
+  repoPath: string
+  prNumber: number
+  commentId: number
+  body: string
+  threadId?: string
+  path?: string
+  line?: number
+}): Promise<Awaited<ReturnType<typeof window.api.gh.addPRReviewCommentReply>>> {
+  const target = getRuntimeTargetForRepoId(args.repoId)
+  if (target) {
+    return callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.addPRReviewCommentReply>>>(
+      target,
+      'github.addPRReviewCommentReply',
+      {
+        repo: args.repoId,
+        prNumber: args.prNumber,
+        commentId: args.commentId,
+        body: args.body,
+        threadId: args.threadId,
+        path: args.path,
+        line: args.line
+      },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.addPRReviewCommentReply({
+    repoPath: args.repoPath,
+    prNumber: args.prNumber,
+    commentId: args.commentId,
+    body: args.body,
+    threadId: args.threadId,
+    path: args.path,
+    line: args.line
+  })
+}
+
+function getWorkItemDetailsForRepo(args: {
+  repoId?: string
+  repoPath: string
+  number: number
+  type: 'issue' | 'pr'
+}): Promise<GitHubWorkItemDetails | null> {
+  const target = getRuntimeTargetForRepoId(args.repoId)
+  if (target) {
+    return callRuntimeRpc<GitHubWorkItemDetails | null>(
+      target,
+      'github.workItemDetails',
+      { repo: args.repoId, number: args.number, type: args.type },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.workItemDetails({
+    repoPath: args.repoPath,
+    number: args.number,
+    type: args.type
+  })
+}
+
 function PRFileRow({
   file,
+  repoId,
   repoPath,
   prNumber,
   headSha,
@@ -728,6 +898,7 @@ function PRFileRow({
         setLoading(true)
         setError(null)
         loadPRFileContents({
+          repoId,
           repoPath,
           prNumber,
           file,
@@ -746,7 +917,7 @@ function PRFileRow({
       }
       return next
     })
-  }, [baseSha, canLoadDiff, contents, file, headSha, loading, prNumber, repoPath])
+  }, [baseSha, canLoadDiff, contents, file, headSha, loading, prNumber, repoId, repoPath])
 
   const language = useMemo(() => detectLanguage(file.path), [file.path])
   const modelKey = `gh-dialog:pr:${prNumber}:${file.path}`
@@ -764,7 +935,8 @@ function PRFileRow({
         toast.error('Unable to comment without the PR head SHA.')
         return false
       }
-      const result = await window.api.gh.addPRReviewComment({
+      const result = await addPRReviewCommentForRepo({
+        repoId,
         repoPath,
         prNumber,
         commitId: headSha,
@@ -781,7 +953,7 @@ function PRFileRow({
       toast.success('Review comment added.')
       return true
     },
-    [file.path, headSha, onCommentAdded, prNumber, repoPath]
+    [file.path, headSha, onCommentAdded, prNumber, repoId, repoPath]
   )
 
   return (
@@ -1149,6 +1321,7 @@ function CommentCodeContext({
 
 function ConversationTab({
   item,
+  repoId,
   repoPath,
   body,
   comments,
@@ -1162,6 +1335,7 @@ function ConversationTab({
   onCommentAdded
 }: {
   item: GitHubWorkItem
+  repoId?: string
   repoPath: string | null
   body: string
   comments: PRComment[]
@@ -1174,10 +1348,11 @@ function ConversationTab({
   onUse: (item: GitHubWorkItem) => void
   onCommentAdded: (comment: PRComment) => void
 }): React.JSX.Element {
+  const settings = useAppStore((s) => s.settings)
   const authorLabel = item.author ?? 'unknown'
   const [replyingTo, setReplyingTo] = useState<number | null>(null)
   const [commentFilter, setCommentFilter] = useState<PRCommentAudienceFilter>('all')
-  const repoAssignees = useRepoAssignees(repoPath)
+  const repoAssignees = useRepoAssignees(repoPath, repoId, settings)
   const commentCounts = useMemo(() => getPRCommentAudienceCounts(comments), [comments])
   const visibleComments = useMemo(
     () => filterPRCommentsByAudience(comments, commentFilter),
@@ -1209,7 +1384,8 @@ function ConversationTab({
       }
       const result =
         comment.path && item.type === 'pr'
-          ? await window.api.gh.addPRReviewCommentReply({
+          ? await addPRReviewCommentReplyForRepo({
+              repoId,
               repoPath,
               prNumber: item.number,
               commentId: comment.id,
@@ -1218,7 +1394,8 @@ function ConversationTab({
               path: comment.path,
               line: comment.line
             })
-          : await window.api.gh.addIssueComment({
+          : await addIssueCommentForRepo({
+              repoId,
               repoPath,
               number: item.number,
               body: `@${comment.author} ${replyBody}`,
@@ -1234,7 +1411,7 @@ function ConversationTab({
       toast.success('Reply posted.')
       return true
     },
-    [item.number, item.type, onCommentAdded, repoPath]
+    [item.number, item.type, onCommentAdded, repoId, repoPath]
   )
 
   const startWorkspaceButton = (
@@ -1483,6 +1660,7 @@ function ConversationTab({
         {repoPath && (
           <GHCommentComposer
             className="mt-1"
+            repoId={repoId}
             repoPath={repoPath}
             issueNumber={item.number}
             itemType={item.type}
@@ -1798,18 +1976,29 @@ function MentionTextarea({
 // to a thrown rejection so the existing `useImmediateMutation` flow
 // (which expects throws on failure) continues to work unchanged.
 async function runIssueUpdate(args: {
+  repoId?: string
   repoPath: string | null
   projectOrigin: GitHubItemDialogProjectOrigin | undefined
   number: number
   updates: Parameters<typeof window.api.gh.updateIssue>[0]['updates']
 }): Promise<void> {
   if (args.projectOrigin) {
-    const res = await window.api.gh.updateIssueBySlug({
+    const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+    const updateArgs = {
       owner: args.projectOrigin.owner,
       repo: args.projectOrigin.repo,
       number: args.number,
       updates: args.updates
-    })
+    }
+    const res =
+      target.kind === 'environment'
+        ? await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.updateIssueBySlug>>>(
+            target,
+            'github.project.updateIssueBySlug',
+            updateArgs,
+            { timeoutMs: 30_000 }
+          )
+        : await window.api.gh.updateIssueBySlug(updateArgs)
     if (!res.ok) {
       throw new Error(res.error.message)
     }
@@ -1818,6 +2007,19 @@ async function runIssueUpdate(args: {
   if (!args.repoPath) {
     throw new Error('No repo context available for this edit.')
   }
+  const target = getRuntimeTargetForRepoId(args.repoId)
+  if (target) {
+    const res = await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.updateIssue>>>(
+      target,
+      'github.updateIssue',
+      { repo: args.repoId, number: args.number, updates: args.updates },
+      { timeoutMs: 30_000 }
+    )
+    if (!res.ok) {
+      throw new Error(res.error)
+    }
+    return
+  }
   await window.api.gh.updateIssue({
     repoPath: args.repoPath,
     number: args.number,
@@ -1858,6 +2060,7 @@ function GHEditSection({
   const patchWorkItem = useAppStore((s) => s.patchWorkItem)
   const patchProjectRowContent = useAppStore((s) => s.patchProjectRowContent)
   const { isPending, run } = useImmediateMutation()
+  const settings = useAppStore((s) => s.settings)
 
   // Why: when the dialog opens from a Project view, mutations route through
   // *BySlug IPCs and we must keep `projectViewCache` in sync alongside
@@ -1879,11 +2082,19 @@ function GHEditSection({
   // values from a different repo than the writes target.
   const slugOwner = projectOrigin?.owner ?? null
   const slugRepo = projectOrigin?.repo ?? null
-  const repoLabelsByPath = useRepoLabels(projectOrigin ? null : repoPath)
-  const repoLabelsBySlug = useRepoLabelsBySlug(slugOwner, slugRepo)
+  const repoLabelsByPath = useRepoLabels(
+    projectOrigin ? null : repoPath,
+    projectOrigin ? null : item.repoId,
+    settings
+  )
+  const repoLabelsBySlug = useRepoLabelsBySlug(slugOwner, slugRepo, settings)
   const repoLabels = projectOrigin ? repoLabelsBySlug : repoLabelsByPath
-  const repoAssigneesByPath = useRepoAssignees(projectOrigin ? null : repoPath)
-  const repoAssigneesBySlug = useRepoAssigneesBySlug(slugOwner, slugRepo, assignees)
+  const repoAssigneesByPath = useRepoAssignees(
+    projectOrigin ? null : repoPath,
+    projectOrigin ? null : item.repoId,
+    settings
+  )
+  const repoAssigneesBySlug = useRepoAssigneesBySlug(slugOwner, slugRepo, assignees, settings)
   const repoAssignees = projectOrigin ? repoAssigneesBySlug : repoAssigneesByPath
 
   // Why: sync local assignees when item changes or when the detail fetch
@@ -1910,6 +2121,7 @@ function GHEditSection({
       run('state', {
         mutate: () =>
           runIssueUpdate({
+            repoId: item.repoId,
             repoPath,
             projectOrigin,
             number: item.number,
@@ -1936,6 +2148,7 @@ function GHEditSection({
     [
       item.id,
       item.number,
+      item.repoId,
       localState,
       repoPath,
       projectOrigin,
@@ -1957,6 +2170,7 @@ function GHEditSection({
         run('labels', {
           mutate: () =>
             runIssueUpdate({
+              repoId: item.repoId,
               repoPath,
               projectOrigin,
               number: item.number,
@@ -1981,6 +2195,7 @@ function GHEditSection({
         run('labels', {
           mutate: () =>
             runIssueUpdate({
+              repoId: item.repoId,
               repoPath,
               projectOrigin,
               number: item.number,
@@ -2006,6 +2221,7 @@ function GHEditSection({
     [
       item.id,
       item.number,
+      item.repoId,
       localLabels,
       repoPath,
       projectOrigin,
@@ -2030,6 +2246,7 @@ function GHEditSection({
         run('assignees', {
           mutate: () =>
             runIssueUpdate({
+              repoId: item.repoId,
               repoPath,
               projectOrigin,
               number: item.number,
@@ -2052,6 +2269,7 @@ function GHEditSection({
         run('assignees', {
           mutate: () =>
             runIssueUpdate({
+              repoId: item.repoId,
               repoPath,
               projectOrigin,
               number: item.number,
@@ -2072,7 +2290,16 @@ function GHEditSection({
         })
       }
     },
-    [item.number, repoPath, projectOrigin, localAssignees, patchProjectRowIfNeeded, run, onMutated]
+    [
+      item.number,
+      item.repoId,
+      repoPath,
+      projectOrigin,
+      localAssignees,
+      patchProjectRowIfNeeded,
+      run,
+      onMutated
+    ]
   )
 
   if (item.type === 'pr') {
@@ -2267,6 +2494,7 @@ function GHEditSection({
 
 function GHCommentComposer({
   className,
+  repoId,
   repoPath,
   issueNumber,
   itemType,
@@ -2274,6 +2502,7 @@ function GHCommentComposer({
   onCommentAdded
 }: {
   className?: string
+  repoId?: string
   repoPath: string
   issueNumber: number
   itemType: 'issue' | 'pr'
@@ -2300,7 +2529,8 @@ function GHCommentComposer({
     }
     setSubmitting(true)
     try {
-      const result = await window.api.gh.addIssueComment({
+      const result = await addIssueCommentForRepo({
+        repoId,
         repoPath,
         number: issueNumber,
         body: trimmed,
@@ -2320,7 +2550,7 @@ function GHCommentComposer({
     } finally {
       setSubmitting(false)
     }
-  }, [autoGrow, body, repoPath, issueNumber, itemType, onCommentAdded])
+  }, [autoGrow, body, repoId, repoPath, issueNumber, itemType, onCommentAdded])
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -2453,17 +2683,23 @@ export default function GitHubItemDialog({
     }
     return s.repos.find((r) => r.path === repoPath)?.issueSourcePreference
   })
+  const runtimeScope = useAppStore((s) =>
+    s.settings?.activeRuntimeEnvironmentId
+      ? `runtime:${s.settings.activeRuntimeEnvironmentId}`
+      : 'local'
+  )
   const detailsCacheKey = useMemo(() => {
     if (!workItem || !repoPath) {
       return null
     }
     return getWorkItemDetailsCacheKey({
+      runtimeScope,
       repoPath,
       issueSourcePreference,
       type: workItem.type,
       number: workItem.number
     })
-  }, [repoPath, workItem, issueSourcePreference])
+  }, [runtimeScope, repoPath, workItem, issueSourcePreference])
 
   // Why: reset lifted edit state when the dialog switches items or when the
   // same item receives an optimistic cache patch from the surrounding table.
@@ -2605,7 +2841,8 @@ export default function GitHubItemDialog({
     // racing two `gh` subprocesses against each other.
     const inflight: Promise<GitHubWorkItemDetails | null> =
       cached?.pending ??
-      window.api.gh.workItemDetails({
+      getWorkItemDetailsForRepo({
+        repoId: workItem.repoId,
         repoPath,
         number: workItem.number,
         type: workItem.type
@@ -2859,6 +3096,7 @@ export default function GitHubItemDialog({
                     <TabsContent value="conversation" className="mt-0">
                       <ConversationTab
                         item={workItem}
+                        repoId={workItem.repoId}
                         repoPath={repoPath}
                         body={body}
                         comments={comments}
@@ -2937,6 +3175,7 @@ export default function GitHubItemDialog({
                                 <PRFileRow
                                   key={file.path}
                                   file={file}
+                                  repoId={workItem.repoId}
                                   repoPath={repoPath ?? ''}
                                   prNumber={workItem.number}
                                   headSha={details?.headSha}
@@ -2947,6 +3186,7 @@ export default function GitHubItemDialog({
                             ) : (
                               <PRDiffTreeView
                                 files={files}
+                                repoId={workItem.repoId}
                                 repoPath={repoPath ?? ''}
                                 prNumber={workItem.number}
                                 headSha={details?.headSha}
diff --git a/src/renderer/src/components/LinearItemDrawer.tsx b/src/renderer/src/components/LinearItemDrawer.tsx
index 1c903cea51a..d4aac63d8d8 100644
--- a/src/renderer/src/components/LinearItemDrawer.tsx
+++ b/src/renderer/src/components/LinearItemDrawer.tsx
@@ -18,6 +18,12 @@ import {
   useImmediateMutation
 } from '@/hooks/useIssueMetadata'
 import type { LinearIssue, LinearComment } from '../../../shared/types'
+import {
+  linearAddIssueComment,
+  linearGetIssue,
+  linearIssueComments,
+  linearUpdateIssue
+} from '@/runtime/runtime-linear-client'
 
 function LinearIcon({ className }: { className?: string }): React.JSX.Element {
   return (
@@ -87,6 +93,7 @@ type EditSectionProps = {
 function EditSection({ issue, editState, onEditStateChange }: EditSectionProps): React.JSX.Element {
   const [labelPopoverOpen, setLabelPopoverOpen] = useState(false)
   const patchLinearIssue = useAppStore((s) => s.patchLinearIssue)
+  const settings = useAppStore((s) => s.settings)
   const { isPending, run } = useImmediateMutation()
 
   const {
@@ -98,9 +105,9 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
   } = editState
 
   const teamId = issue.team?.id || null
-  const states = useTeamStates(teamId)
-  const labels = useTeamLabels(teamId)
-  const members = useTeamMembers(teamId)
+  const states = useTeamStates(teamId, settings)
+  const labels = useTeamLabels(teamId, settings)
+  const members = useTeamMembers(teamId, settings)
 
   const handleStateChange = useCallback(
     (stateId: string) => {
@@ -113,7 +120,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
       const stateValue = { name: newState.name, type: newState.type, color: newState.color }
 
       run('state', {
-        mutate: () => window.api.linear.updateIssue({ id: issue.id, updates: { stateId } }),
+        mutate: () => linearUpdateIssue(settings, issue.id, { stateId }),
         onOptimistic: () => {
           onEditStateChange({ state: stateValue })
           patchLinearIssue(issue.id, { state: stateValue })
@@ -125,7 +132,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         onError: (err) => toast.error(err)
       })
     },
-    [issue.id, localState, states.data, patchLinearIssue, run, onEditStateChange]
+    [issue.id, localState, settings, states.data, patchLinearIssue, run, onEditStateChange]
   )
 
   const handlePriorityChange = useCallback(
@@ -133,7 +140,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
       const priority = parseInt(value, 10)
       const prevPriority = localPriority
       run('priority', {
-        mutate: () => window.api.linear.updateIssue({ id: issue.id, updates: { priority } }),
+        mutate: () => linearUpdateIssue(settings, issue.id, { priority }),
         onOptimistic: () => {
           onEditStateChange({ priority })
           patchLinearIssue(issue.id, { priority })
@@ -145,7 +152,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         onError: (err) => toast.error(err)
       })
     },
-    [issue.id, localPriority, patchLinearIssue, run, onEditStateChange]
+    [issue.id, localPriority, settings, patchLinearIssue, run, onEditStateChange]
   )
 
   const handleAssigneeChange = useCallback(
@@ -157,7 +164,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         ? { id: member.id, displayName: member.displayName, avatarUrl: member.avatarUrl }
         : undefined
       run('assignee', {
-        mutate: () => window.api.linear.updateIssue({ id: issue.id, updates: { assigneeId } }),
+        mutate: () => linearUpdateIssue(settings, issue.id, { assigneeId }),
         onOptimistic: () => {
           onEditStateChange({ assignee: newAssignee })
           patchLinearIssue(issue.id, { assignee: newAssignee })
@@ -169,7 +176,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         onError: (err) => toast.error(err)
       })
     },
-    [issue.id, localAssignee, members.data, patchLinearIssue, run, onEditStateChange]
+    [issue.id, localAssignee, settings, members.data, patchLinearIssue, run, onEditStateChange]
   )
 
   const handleLabelToggle = useCallback(
@@ -185,8 +192,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         .filter((n): n is string => !!n)
 
       run('labels', {
-        mutate: () =>
-          window.api.linear.updateIssue({ id: issue.id, updates: { labelIds: newLabelIds } }),
+        mutate: () => linearUpdateIssue(settings, issue.id, { labelIds: newLabelIds }),
         onOptimistic: () => {
           onEditStateChange({ labelIds: newLabelIds, labels: newLabels })
           patchLinearIssue(issue.id, { labelIds: newLabelIds, labels: newLabels })
@@ -198,7 +204,16 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         onError: (err) => toast.error(err)
       })
     },
-    [issue.id, localLabelIds, localLabels, labels.data, patchLinearIssue, run, onEditStateChange]
+    [
+      issue.id,
+      localLabelIds,
+      localLabels,
+      settings,
+      labels.data,
+      patchLinearIssue,
+      run,
+      onEditStateChange
+    ]
   )
 
   const currentStateId = states.data.find(
@@ -406,6 +421,7 @@ function CommentFooter({
   issueId: string
   onCommentAdded: (comment: LocalComment) => void
 }): React.JSX.Element {
+  const settings = useAppStore((s) => s.settings)
   const [body, setBody] = useState('')
   const [submitting, setSubmitting] = useState(false)
   const textareaRef = useRef<HTMLTextAreaElement>(null)
@@ -426,7 +442,7 @@ function CommentFooter({
     }
     setSubmitting(true)
     try {
-      const result = await window.api.linear.addIssueComment({ issueId, body: trimmed })
+      const result = await linearAddIssueComment(settings, issueId, trimmed)
       const typed = result as { ok: boolean; id?: string; error?: string }
       if (typed.ok) {
         setBody('')
@@ -443,7 +459,7 @@ function CommentFooter({
     } finally {
       setSubmitting(false)
     }
-  }, [body, issueId, onCommentAdded])
+  }, [body, issueId, onCommentAdded, settings])
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -508,6 +524,7 @@ export default function LinearItemDrawer({
   const requestIdRef = useRef(0)
   const hasEditedRef = useRef(false)
   const optimisticCommentsRef = useRef<LinearComment[]>([])
+  const settings = useAppStore((s) => s.settings)
 
   const handleEditStateChange = useCallback((patch: Partial<LinearEditState>) => {
     hasEditedRef.current = true
@@ -535,8 +552,7 @@ export default function LinearItemDrawer({
 
     // Why: fetch issue and comments independently so a transient comments
     // failure doesn't discard the successfully-fetched issue data.
-    window.api.linear
-      .getIssue({ id: issue.id })
+    linearGetIssue(settings, issue.id)
       .then((issueResult) => {
         if (requestId !== requestIdRef.current) {
           return
@@ -553,8 +569,7 @@ export default function LinearItemDrawer({
       })
       .catch(() => {})
 
-    window.api.linear
-      .issueComments({ issueId: issue.id })
+    linearIssueComments(settings, issue.id)
       .then((commentsResult) => {
         if (requestId !== requestIdRef.current) {
           return
@@ -579,7 +594,7 @@ export default function LinearItemDrawer({
         }
       })
     // oxlint-disable-next-line react-hooks/exhaustive-deps
-  }, [issue?.id])
+  }, [issue?.id, settings])
 
   // Why: same pointer-events fix as GitHubItemDialog — Radix may leave
   // pointer-events: none on body when overlays transition.
diff --git a/src/renderer/src/components/QuickOpen.tsx b/src/renderer/src/components/QuickOpen.tsx
index f18a3203b59..53d0e646c36 100644
--- a/src/renderer/src/components/QuickOpen.tsx
+++ b/src/renderer/src/components/QuickOpen.tsx
@@ -6,6 +6,7 @@ import { useActiveWorktree, useWorktreesForRepo } from '@/store/selectors'
 import { detectLanguage } from '@/lib/language-detect'
 import { joinPath } from '@/lib/path'
 import { getConnectionId } from '@/lib/connection-context'
+import { listRuntimeFiles } from '@/runtime/runtime-file-client'
 import {
   CommandDialog,
   CommandInput,
@@ -254,15 +255,18 @@ export default function QuickOpen(): React.JSX.Element | null {
 
     const excludePaths = excludePathsKey ? excludePathsKey.split('\n') : undefined
 
-    void window.api.fs
-      // Why: quick-open shares the active worktree path model with file explorer
-      // and search, so remote worktrees must include connectionId. Without this,
-      // Windows resolves Linux roots (e.g. /home/*) as local C:\home\* paths.
-      .listFiles({
+    void listRuntimeFiles(
+      {
+        settings: useAppStore.getState().settings,
+        worktreeId: activeWorktreeId,
+        worktreePath,
+        connectionId
+      },
+      {
         rootPath: worktreePath,
-        connectionId,
         excludePaths
-      })
+      }
+    )
       .then((result) => {
         if (!cancelled) {
           setFiles(result)
@@ -289,7 +293,7 @@ export default function QuickOpen(): React.JSX.Element | null {
     return () => {
       cancelled = true
     }
-  }, [visible, worktreePath, connectionId, excludePathsKey, filesRequestKey])
+  }, [visible, activeWorktreeId, worktreePath, connectionId, excludePathsKey, filesRequestKey])
 
   // Filter files by fuzzy match
   const filtered = useMemo(() => {
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 7243620838b..3bbc8a03af0 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -26,6 +26,7 @@ import { toast } from 'sonner'
 
 import { useAppStore } from '@/store'
 import { useRepoMap } from '@/store/selectors'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import {
@@ -85,9 +86,16 @@ import type {
   GitLabTodo,
   GitLabWorkItem,
   LinearIssue,
+  Repo,
   TaskViewPresetId
 } from '../../../shared/types'
 import { shouldSuppressEnterSubmit } from '@/lib/new-workspace-enter-guard'
+import {
+  linearCreateIssue,
+  linearGetIssue,
+  linearListTeams,
+  linearUpdateIssue
+} from '@/runtime/runtime-linear-client'
 
 type TaskSource = 'github' | 'linear' | 'gitlab'
 
@@ -105,6 +113,18 @@ type TaskQueryPreset = {
   query: string
 }
 
+function getRuntimeTargetForRepoId(repoId: string | null | undefined) {
+  if (!repoId) {
+    return null
+  }
+  const state = useAppStore.getState()
+  const target = getActiveRuntimeTarget(state.settings)
+  if (target.kind !== 'environment') {
+    return null
+  }
+  return state.repos.some((repo) => repo.id === repoId) ? target : null
+}
+
 type SourceOption = {
   id: TaskSource
   label: string
@@ -219,10 +239,10 @@ const LINEAR_PRIORITY_LABELS: Record<number, string> = {
 
 function GHStatusCell({
   item,
-  repoPath
+  repo
 }: {
   item: GitHubWorkItem
-  repoPath: string | null
+  repo: Repo | null
 }): React.JSX.Element {
   const patchWorkItem = useAppStore((s) => s.patchWorkItem)
   const [localState, setLocalState] = useState(item.state)
@@ -235,15 +255,28 @@ function GHStatusCell({
 
   const handleStateChange = useCallback(
     (newState: 'open' | 'closed') => {
-      if (newState === localState || !repoPath || item.type !== 'issue') {
+      if (newState === localState || !repo || item.type !== 'issue') {
         return
       }
       reqRef.current += 1
       const reqId = reqRef.current
       setLocalState(newState)
       patchWorkItem(item.id, { state: newState })
-      window.api.gh
-        .updateIssue({ repoPath, number: item.number, updates: { state: newState } })
+      const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+      const updatePromise =
+        target.kind === 'environment'
+          ? callRuntimeRpc<{ ok?: boolean; error?: string }>(
+              target,
+              'github.updateIssue',
+              { repo: repo.id, number: item.number, updates: { state: newState } },
+              { timeoutMs: 30_000 }
+            )
+          : window.api.gh.updateIssue({
+              repoPath: repo.path,
+              number: item.number,
+              updates: { state: newState }
+            })
+      updatePromise
         .then((result) => {
           if (reqId !== reqRef.current) {
             return
@@ -264,10 +297,10 @@ function GHStatusCell({
           toast.error('Failed to update state')
         })
     },
-    [item.id, item.number, item.type, localState, repoPath, patchWorkItem]
+    [item.id, item.number, item.type, localState, repo, patchWorkItem]
   )
 
-  if (item.type !== 'issue' || !repoPath) {
+  if (item.type !== 'issue' || !repo) {
     return (
       <span
         className={cn(
@@ -334,6 +367,7 @@ function GHStatusCell({
 function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element {
   const patchLinearIssue = useAppStore((s) => s.patchLinearIssue)
   const fetchLinearIssue = useAppStore((s) => s.fetchLinearIssue)
+  const settings = useAppStore((s) => s.settings)
   const [localState, setLocalState] = useState(issue.state)
   const reqRef = useRef(0)
 
@@ -342,7 +376,7 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
   }, [issue.state])
 
   const teamId = issue.team?.id || null
-  const states = useTeamStates(teamId)
+  const states = useTeamStates(teamId, settings)
 
   const handleStateChange = useCallback(
     (stateId: string) => {
@@ -357,8 +391,7 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
 
       setLocalState(stateValue)
       patchLinearIssue(issue.id, { state: stateValue })
-      window.api.linear
-        .updateIssue({ id: issue.id, updates: { stateId } })
+      linearUpdateIssue(settings, issue.id, { stateId })
         .then((result) => {
           if (reqId !== reqRef.current) {
             return
@@ -381,7 +414,7 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
           toast.error('Failed to update status')
         })
     },
-    [issue.id, issue.state, states.data, patchLinearIssue, fetchLinearIssue]
+    [issue.id, issue.state, settings, states.data, patchLinearIssue, fetchLinearIssue]
   )
 
   const currentStateId = states.data.find(
@@ -442,6 +475,7 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
 function LinearPriorityCell({ issue }: { issue: LinearIssue }): React.JSX.Element {
   const patchLinearIssue = useAppStore((s) => s.patchLinearIssue)
   const fetchLinearIssue = useAppStore((s) => s.fetchLinearIssue)
+  const settings = useAppStore((s) => s.settings)
   const [localPriority, setLocalPriority] = useState(issue.priority)
   const [pending, setPending] = useState(false)
   const reqRef = useRef(0)
@@ -460,8 +494,7 @@ function LinearPriorityCell({ issue }: { issue: LinearIssue }): React.JSX.Elemen
       setLocalPriority(priority)
       patchLinearIssue(issue.id, { priority })
       setPending(true)
-      window.api.linear
-        .updateIssue({ id: issue.id, updates: { priority } })
+      linearUpdateIssue(settings, issue.id, { priority })
         .then((result) => {
           if (reqId !== reqRef.current) {
             return
@@ -490,7 +523,7 @@ function LinearPriorityCell({ issue }: { issue: LinearIssue }): React.JSX.Elemen
           setPending(false)
         })
     },
-    [issue.id, issue.priority, localPriority, patchLinearIssue, fetchLinearIssue]
+    [issue.id, issue.priority, localPriority, settings, patchLinearIssue, fetchLinearIssue]
   )
 
   const [open, setOpen] = useState(false)
@@ -1066,14 +1099,13 @@ export default function TaskPage(): React.JSX.Element {
     if (taskSource !== 'linear' || !linearStatus.connected) {
       return
     }
-    void window.api.linear
-      .listTeams()
+    void linearListTeams(settings)
       .then(setAvailableTeams)
       .catch(() => {
         console.warn('[TaskPage] Failed to fetch Linear teams')
       })
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [taskSource, linearStatus.connected, taskResumeApplied])
+  }, [settings, taskSource, linearStatus.connected, taskResumeApplied])
 
   // Why: stable key for `selectedRepos` so the GitLab fetch effect below
   // doesn't re-run on every parent re-render just because the array
@@ -1619,11 +1651,19 @@ export default function TaskPage(): React.JSX.Element {
     }
     setNewIssueSubmitting(true)
     try {
-      const result = await window.api.gh.createIssue({
-        repoPath: newIssueTargetRepo.path,
-        title,
-        body: newIssueBody
-      })
+      const target = getRuntimeTargetForRepoId(newIssueTargetRepo.id)
+      const result = target
+        ? await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.createIssue>>>(
+            target,
+            'github.createIssue',
+            { repo: newIssueTargetRepo.id, title, body: newIssueBody },
+            { timeoutMs: 30_000 }
+          )
+        : await window.api.gh.createIssue({
+            repoPath: newIssueTargetRepo.path,
+            title,
+            body: newIssueBody
+          })
       if (!result.ok) {
         toast.error(result.error || 'Failed to create issue.')
         return
@@ -1659,8 +1699,19 @@ export default function TaskPage(): React.JSX.Element {
       }
       setDialogWorkItem(stub)
       const stubRepoId = newIssueTargetRepo.id
-      void window.api.gh
-        .workItem({ repoPath: newIssueTargetRepo.path, number: result.number, type: 'issue' })
+      const fullIssuePromise = target
+        ? callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.workItem>>>(
+            target,
+            'github.workItem',
+            { repo: newIssueTargetRepo.id, number: result.number, type: 'issue' },
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh.workItem({
+            repoPath: newIssueTargetRepo.path,
+            number: result.number,
+            type: 'issue'
+          })
+      void fullIssuePromise
         .then((full) => {
           if (full) {
             // Why: `full` is `Omit<GitHubWorkItem, 'repoId'>` (IPC shape).
@@ -1687,7 +1738,7 @@ export default function TaskPage(): React.JSX.Element {
     }
     setNewLinearIssueSubmitting(true)
     try {
-      const result = await window.api.linear.createIssue({
+      const result = await linearCreateIssue(settings, {
         teamId: newLinearIssueTargetTeam.id,
         title,
         description: newLinearIssueBody || undefined
@@ -1711,8 +1762,7 @@ export default function TaskPage(): React.JSX.Element {
 
       // Why: auto-open the new issue in the side drawer so the user sees
       // exactly what was filed, mirroring the GitHub create-issue flow.
-      void window.api.linear
-        .getIssue({ id: result.id })
+      void linearGetIssue(settings, result.id)
         .then((full) => {
           if (full) {
             setDrawerLinearIssue(full)
@@ -1727,6 +1777,7 @@ export default function TaskPage(): React.JSX.Element {
     newLinearIssueSubmitting,
     newLinearIssueTargetTeam,
     newLinearIssueTitle,
+    settings,
     setDrawerLinearIssue
   ])
 
@@ -2693,7 +2744,7 @@ export default function TaskPage(): React.JSX.Element {
                         </div>
 
                         <div className="flex items-center">
-                          <GHStatusCell item={item} repoPath={itemRepo?.path ?? null} />
+                          <GHStatusCell item={item} repo={itemRepo ?? null} />
                         </div>
 
                         <Tooltip>
diff --git a/src/renderer/src/components/TelemetryFirstLaunchSurface.tsx b/src/renderer/src/components/TelemetryFirstLaunchSurface.tsx
index 50cedad4963..29c9cafd31d 100644
--- a/src/renderer/src/components/TelemetryFirstLaunchSurface.tsx
+++ b/src/renderer/src/components/TelemetryFirstLaunchSurface.tsx
@@ -1,6 +1,7 @@
 // Root-mounted gate for the existing-user first-launch notice. New users
-// get NO first-launch surface; see telemetry-plan.md §First-launch experience
-// for the rationale.
+// get NO first-launch surface — default-on with no first-run notice
+// matches the category norm for developer tooling; see telemetry-plan.md
+// §First-launch experience for the rationale.
 //
 // Cohort marker populated by the migration in `src/main/persistence.ts`:
 //
diff --git a/src/renderer/src/components/Terminal.tsx b/src/renderer/src/components/Terminal.tsx
index 4d5f987b116..d1b172000dd 100644
--- a/src/renderer/src/components/Terminal.tsx
+++ b/src/renderer/src/components/Terminal.tsx
@@ -62,6 +62,7 @@ import {
   useActivityTerminalPortals,
   type ActivityTerminalPortalTarget
 } from './activity/activity-terminal-portal'
+import { isRemoteRuntimePtyId } from '@/runtime/runtime-terminal-inspection'
 
 const EditorPanel = lazy(() => import('./editor/EditorPanel'))
 
@@ -215,7 +216,9 @@ function Terminal(): React.JSX.Element | null {
           if (connectionId !== null) {
             return []
           }
-          return worktreeTabs.flatMap((tab) => state.ptyIdsByTabId[tab.id] ?? [])
+          return worktreeTabs
+            .flatMap((tab) => state.ptyIdsByTabId[tab.id] ?? [])
+            .filter((ptyId) => !isRemoteRuntimePtyId(ptyId))
         }
       )
       if (localPtyIds.length > 0) {
@@ -640,10 +643,12 @@ function Terminal(): React.JSX.Element | null {
       // the ambient/default group and open the file in the wrong pane.
       const targetGroupId = useAppStore.getState().activeGroupIdByWorktree[activeWorktreeId]
       const connectionId = getConnectionId(activeWorktreeId) ?? undefined
+      const settings = useAppStore.getState().settings
       const fileInfo = await createUntitledMarkdownFile(
         worktree.path,
         activeWorktreeId,
-        connectionId
+        connectionId,
+        settings
       )
       openFile(fileInfo, { preview: false, targetGroupId })
     } catch (err) {
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index 1589c555332..7584be239bd 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -23,6 +23,7 @@ import { cn } from '@/lib/utils'
 import { getWorktreeStatus, getWorktreeStatusLabel } from '@/lib/worktree-status'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import {
   searchWorktrees,
   type MatchRange,
@@ -38,7 +39,13 @@ import {
   ORCA_BROWSER_FOCUS_REQUEST_EVENT,
   queueBrowserFocusRequest
 } from '@/components/browser-pane/browser-focus'
-import type { BrowserPage, BrowserWorkspace, Worktree } from '../../../shared/types'
+import type {
+  BrowserPage,
+  BrowserWorkspace,
+  GitHubWorkItem,
+  Repo,
+  Worktree
+} from '../../../shared/types'
 import { isGitRepoKind } from '../../../shared/repo-kind'
 
 type WorktreePaletteItem = {
@@ -76,6 +83,55 @@ type BrowserSelection = {
   page: BrowserPage
 }
 
+type GitHubWorkItemWithoutRepo = Omit<GitHubWorkItem, 'repoId'>
+
+function getRuntimeTargetForRepo(
+  repo: Repo
+): { kind: 'environment'; environmentId: string } | null {
+  const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+  if (target.kind !== 'environment') {
+    return null
+  }
+  return useAppStore.getState().repos.some((candidate) => candidate.id === repo.id) ? target : null
+}
+
+function getWorkItemForRepo(repo: Repo, number: number): Promise<GitHubWorkItemWithoutRepo | null> {
+  const target = getRuntimeTargetForRepo(repo)
+  if (target) {
+    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
+      target,
+      'github.workItem',
+      { repo: repo.id, number },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.workItem({ repoPath: repo.path, number })
+}
+
+function getWorkItemByOwnerRepoForRepo(
+  repo: Repo,
+  slug: { owner: string; repo: string },
+  number: number,
+  type: 'issue' | 'pr'
+): Promise<GitHubWorkItemWithoutRepo | null> {
+  const target = getRuntimeTargetForRepo(repo)
+  if (target) {
+    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
+      target,
+      'github.workItemByOwnerRepo',
+      { repo: repo.id, owner: slug.owner, ownerRepo: slug.repo, number, type },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.workItemByOwnerRepo({
+    repoPath: repo.path,
+    owner: slug.owner,
+    repo: slug.repo,
+    number,
+    type
+  })
+}
+
 function HighlightedText({
   text,
   matchRange
@@ -675,8 +731,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       // indefinitely on slow networks. Close immediately and populate the
       // composer once the lookup returns.
       closeModal()
-      void window.api.gh
-        .workItem({ repoPath: repoForLookup.path, number })
+      void getWorkItemByOwnerRepoForRepo(repoForLookup, slug, number, ghLink.type)
         .then((item) => {
           const data: Record<string, unknown> = { initialRepoId: repoForLookup.id }
           if (item) {
@@ -729,8 +784,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       }
 
       closeModal()
-      void window.api.gh
-        .workItem({ repoPath: repoForLookup.path, number: ghNumber })
+      void getWorkItemForRepo(repoForLookup, ghNumber)
         .then((item) => {
           const data: Record<string, unknown> = { initialRepoId: repoForLookup.id }
           if (item) {
diff --git a/src/renderer/src/components/automations/CreateFromPicker.tsx b/src/renderer/src/components/automations/CreateFromPicker.tsx
index e3f4bb7db23..300655e5f7b 100644
--- a/src/renderer/src/components/automations/CreateFromPicker.tsx
+++ b/src/renderer/src/components/automations/CreateFromPicker.tsx
@@ -11,6 +11,11 @@ import {
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { cn } from '@/lib/utils'
 import type { Repo, Worktree } from '../../../../shared/types'
+import { useAppStore } from '@/store'
+import {
+  getRuntimeRepoBaseRefDefault,
+  searchRuntimeRepoBaseRefs
+} from '@/runtime/runtime-repo-client'
 
 const DEFAULT_VALUE = '__project_default__'
 
@@ -31,6 +36,9 @@ export function CreateFromPicker({
   value: string
   onValueChange: (baseBranch: string) => void
 }): React.JSX.Element {
+  const activeRuntimeEnvironmentId = useAppStore(
+    (state) => state.settings?.activeRuntimeEnvironmentId ?? null
+  )
   const repo = repoMap.get(repoId)
   const [open, setOpen] = React.useState(false)
   const inputRef = React.useRef<HTMLInputElement | null>(null)
@@ -73,8 +81,7 @@ export function CreateFromPicker({
     }
     let stale = false
     setDefaultBaseRef(null)
-    void window.api.repos
-      .getBaseRefDefault({ repoId })
+    void getRuntimeRepoBaseRefDefault({ activeRuntimeEnvironmentId }, repoId)
       .then((result) => {
         if (!stale) {
           setDefaultBaseRef(result.defaultBaseRef)
@@ -88,7 +95,7 @@ export function CreateFromPicker({
     return () => {
       stale = true
     }
-  }, [repoId])
+  }, [activeRuntimeEnvironmentId, repoId])
 
   React.useEffect(() => {
     setQuery('')
@@ -107,8 +114,7 @@ export function CreateFromPicker({
     let stale = false
     setIsSearching(true)
     const timer = window.setTimeout(() => {
-      void window.api.repos
-        .searchBaseRefs({ repoId, query: trimmedQuery, limit: 30 })
+      void searchRuntimeRepoBaseRefs({ activeRuntimeEnvironmentId }, repoId, trimmedQuery, 30)
         .then((results) => {
           if (!stale) {
             setSearchResults(results)
@@ -130,7 +136,7 @@ export function CreateFromPicker({
       stale = true
       window.clearTimeout(timer)
     }
-  }, [open, query, repoId])
+  }, [activeRuntimeEnvironmentId, open, query, repoId])
 
   return (
     <div className="space-y-2">
diff --git a/src/renderer/src/components/browser-pane/BrowserPane.tsx b/src/renderer/src/components/browser-pane/BrowserPane.tsx
index d05187fc95f..da03b76a964 100644
--- a/src/renderer/src/components/browser-pane/BrowserPane.tsx
+++ b/src/renderer/src/components/browser-pane/BrowserPane.tsx
@@ -79,6 +79,19 @@ import {
   ORCA_BROWSER_FOCUS_REQUEST_EVENT,
   type BrowserFocusRequestDetail
 } from './browser-focus'
+import {
+  isRemoteRuntimeFileOperation,
+  statRuntimePath,
+  type RuntimeFileOperationArgs
+} from '@/runtime/runtime-file-client'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import type {
+  BrowserBackResult,
+  BrowserGotoResult,
+  BrowserReloadResult,
+  BrowserScreenshotResult,
+  BrowserTabInfo
+} from '../../../../shared/runtime-types'
 import {
   formatByteCount,
   formatDownloadFinishedNotice,
@@ -158,6 +171,31 @@ function getNotebookPathFromBrowserUrl(url: string): string | null {
   return filePath?.toLowerCase().endsWith('.ipynb') ? filePath : null
 }
 
+function getRemoteBrowserKeypressKey(event: React.KeyboardEvent): string | null {
+  if (event.key.length === 1) {
+    return null
+  }
+  if (event.metaKey || event.ctrlKey || event.altKey) {
+    return null
+  }
+  const supported = new Set([
+    'Enter',
+    'Backspace',
+    'Delete',
+    'Tab',
+    'Escape',
+    'ArrowUp',
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'Home',
+    'End',
+    'PageUp',
+    'PageDown'
+  ])
+  return supported.has(event.key) ? event.key : null
+}
+
 function getLoadErrorMetadata(loadError: BrowserLoadError | null): {
   displayUrl: string
   host: string | null
@@ -278,12 +316,39 @@ export default function BrowserPane({
   browserTab: BrowserWorkspaceState
   isActive: boolean
 }): React.JSX.Element {
+  const activeRuntimeEnvironmentId = useAppStore(
+    (s) => s.settings?.activeRuntimeEnvironmentId ?? null
+  )
   const browserPagesByWorkspace = useAppStore((s) => s.browserPagesByWorkspace)
   const browserPages = browserPagesByWorkspace[browserTab.id] ?? EMPTY_BROWSER_PAGES
   const activeBrowserPage =
     browserPages.find((page) => page.id === browserTab.activePageId) ?? browserPages[0] ?? null
   const updateBrowserPageState = useAppStore((s) => s.updateBrowserPageState)
   const setBrowserPageUrl = useAppStore((s) => s.setBrowserPageUrl)
+  const runtimeEnvironmentActive = Boolean(activeRuntimeEnvironmentId?.trim())
+
+  useEffect(() => {
+    if (!runtimeEnvironmentActive) {
+      return
+    }
+    for (const page of browserPages) {
+      destroyPersistentWebview(page.id)
+    }
+  }, [browserPages, runtimeEnvironmentActive])
+
+  if (runtimeEnvironmentActive) {
+    return activeBrowserPage ? (
+      <RemoteBrowserPagePane
+        browserTab={activeBrowserPage}
+        worktreeId={browserTab.worktreeId}
+        isActive={isActive}
+        onUpdatePageState={updateBrowserPageState}
+        onSetUrl={setBrowserPageUrl}
+      />
+    ) : (
+      <div className="flex h-full min-h-0 flex-1 bg-background" />
+    )
+  }
 
   return (
     <div className="relative flex h-full min-h-0 flex-1 flex-col">
@@ -304,6 +369,451 @@ export default function BrowserPane({
   )
 }
 
+function RemoteBrowserPagePane({
+  browserTab,
+  worktreeId,
+  isActive,
+  onUpdatePageState,
+  onSetUrl
+}: {
+  browserTab: BrowserPageState
+  worktreeId: string
+  isActive: boolean
+  onUpdatePageState: (tabId: string, updates: BrowserTabPageState) => void
+  onSetUrl: (tabId: string, url: string) => void
+}): React.JSX.Element {
+  const settings = useAppStore((s) => s.settings)
+  const addressBarInputRef = useRef<HTMLInputElement | null>(null)
+  const imageRef = useRef<HTMLImageElement | null>(null)
+  const [addressBarValue, setAddressBarValue] = useState(toDisplayUrl(browserTab.url))
+  const [screenshotUrl, setScreenshotUrl] = useState<string | null>(null)
+  const [remoteError, setRemoteError] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+  const remotePageIdRef = useRef<string | null>(null)
+  const activeRuntimeEnvironmentId = settings?.activeRuntimeEnvironmentId?.trim() ?? null
+  const setRemoteBrowserPageHandle = useAppStore((s) => s.setRemoteBrowserPageHandle)
+
+  useEffect(() => {
+    if (document.activeElement === addressBarInputRef.current) {
+      return
+    }
+    setAddressBarValue(toDisplayUrl(browserTab.url))
+  }, [browserTab.url])
+
+  const runtimeTarget = useCallback(() => {
+    const target = getActiveRuntimeTarget(settings)
+    return target.kind === 'environment' ? target : null
+  }, [settings])
+
+  useEffect(() => {
+    if (!activeRuntimeEnvironmentId) {
+      return
+    }
+    return () => {
+      const remotePageId = remotePageIdRef.current
+      if (!remotePageId) {
+        return
+      }
+      const state = useAppStore.getState()
+      const currentEnvironmentId = state.settings?.activeRuntimeEnvironmentId?.trim() ?? null
+      const pageStillExists = Object.values(state.browserPagesByWorkspace).some((pages) =>
+        pages.some((page) => page.id === browserTab.id)
+      )
+      if (currentEnvironmentId === activeRuntimeEnvironmentId && pageStillExists) {
+        return
+      }
+      const removedHandle = state.removeRemoteBrowserPageHandle(browserTab.id, remotePageId)
+      remotePageIdRef.current = null
+      if (!removedHandle) {
+        return
+      }
+      // Why: remote browser tabs outlive React components on the daemon. Close
+      // only when the local page is gone or its owning runtime environment is.
+      void callRuntimeRpc(
+        { kind: 'environment', environmentId: removedHandle.environmentId },
+        'browser.tabClose',
+        { worktree: `id:${worktreeId}`, page: removedHandle.remotePageId },
+        { timeoutMs: 15_000 }
+      ).catch(() => {})
+    }
+  }, [activeRuntimeEnvironmentId, browserTab.id, worktreeId])
+
+  const applyRemoteTabInfo = useCallback(
+    (tab: Pick<BrowserTabInfo, 'url' | 'title'>): void => {
+      const safeUrl = redactKagiSessionToken(tab.url || 'about:blank')
+      onSetUrl(browserTab.id, safeUrl)
+      onUpdatePageState(browserTab.id, {
+        title: getBrowserDisplayTitle(tab.title, safeUrl),
+        loading: false,
+        loadError: null
+      })
+      setAddressBarValue(toDisplayUrl(safeUrl))
+    },
+    [browserTab.id, onSetUrl, onUpdatePageState]
+  )
+
+  const captureRemoteScreenshot = useCallback(
+    async (pageId: string): Promise<void> => {
+      const target = runtimeTarget()
+      if (!target) {
+        return
+      }
+      const screenshot = await callRuntimeRpc<BrowserScreenshotResult>(
+        target,
+        'browser.screenshot',
+        { worktree: `id:${worktreeId}`, page: pageId, format: 'png' },
+        { timeoutMs: 30_000 }
+      )
+      setScreenshotUrl(`data:image/${screenshot.format};base64,${screenshot.data}`)
+    },
+    [runtimeTarget, worktreeId]
+  )
+
+  const ensureRemotePage = useCallback(async (): Promise<string | null> => {
+    const target = runtimeTarget()
+    if (!target) {
+      return null
+    }
+    const existingHandle = useAppStore.getState().remoteBrowserPageHandlesByPageId[browserTab.id]
+    if (existingHandle?.environmentId === target.environmentId) {
+      remotePageIdRef.current = existingHandle.remotePageId
+      return existingHandle.remotePageId
+    }
+    const initialUrl =
+      browserTab.url === ORCA_BROWSER_BLANK_URL ? 'about:blank' : browserTab.url || 'about:blank'
+    const created = await callRuntimeRpc<{ browserPageId: string }>(
+      target,
+      'browser.tabCreate',
+      { worktree: `id:${worktreeId}`, url: initialUrl },
+      { timeoutMs: 30_000 }
+    )
+    remotePageIdRef.current = created.browserPageId
+    setRemoteBrowserPageHandle(browserTab.id, {
+      environmentId: target.environmentId,
+      remotePageId: created.browserPageId
+    })
+    return created.browserPageId
+  }, [browserTab.id, browserTab.url, runtimeTarget, setRemoteBrowserPageHandle, worktreeId])
+
+  const refreshRemoteView = useCallback(
+    async (pageId?: string): Promise<void> => {
+      const target = runtimeTarget()
+      const targetPageId = pageId ?? remotePageIdRef.current
+      if (!target || !targetPageId) {
+        return
+      }
+      const shown = await callRuntimeRpc<{ tab: BrowserTabInfo }>(
+        target,
+        'browser.tabShow',
+        { worktree: `id:${worktreeId}`, page: targetPageId },
+        { timeoutMs: 15_000 }
+      )
+      applyRemoteTabInfo(shown.tab)
+      await captureRemoteScreenshot(targetPageId)
+    },
+    [applyRemoteTabInfo, captureRemoteScreenshot, runtimeTarget, worktreeId]
+  )
+
+  useEffect(() => {
+    if (!isActive) {
+      return
+    }
+    let cancelled = false
+    setBusy(true)
+    setRemoteError(null)
+    void ensureRemotePage()
+      .then(async (pageId) => {
+        if (!pageId || cancelled) {
+          return
+        }
+        await refreshRemoteView(pageId)
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setRemoteError(error instanceof Error ? error.message : 'Failed to open remote browser.')
+        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setBusy(false)
+        }
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [ensureRemotePage, isActive, refreshRemoteView])
+
+  useEffect(() => {
+    if (!isActive) {
+      return
+    }
+    return window.api.ui.onFocusBrowserAddressBar(() => {
+      addressBarInputRef.current?.focus()
+      addressBarInputRef.current?.select()
+    })
+  }, [isActive])
+
+  const runRemoteNavigation = useCallback(
+    async (
+      method: 'browser.goto' | 'browser.back' | 'browser.forward' | 'browser.reload',
+      url?: string
+    ) => {
+      const target = runtimeTarget()
+      if (!target) {
+        return
+      }
+      const pageId = await ensureRemotePage()
+      if (!pageId) {
+        return
+      }
+      setBusy(true)
+      setRemoteError(null)
+      onUpdatePageState(browserTab.id, { loading: true, loadError: null })
+      try {
+        const params =
+          method === 'browser.goto'
+            ? { worktree: `id:${worktreeId}`, page: pageId, url: url ?? 'about:blank' }
+            : { worktree: `id:${worktreeId}`, page: pageId }
+        const result = await callRuntimeRpc<
+          BrowserGotoResult | BrowserBackResult | BrowserReloadResult
+        >(target, method, params, { timeoutMs: 30_000 })
+        applyRemoteTabInfo(result)
+        await captureRemoteScreenshot(pageId)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Remote browser command failed.'
+        setRemoteError(message)
+        onUpdatePageState(browserTab.id, {
+          loading: false,
+          loadError: { code: 0, description: message, validatedUrl: url ?? browserTab.url }
+        })
+      } finally {
+        setBusy(false)
+      }
+    },
+    [
+      applyRemoteTabInfo,
+      browserTab.id,
+      browserTab.url,
+      captureRemoteScreenshot,
+      ensureRemotePage,
+      onUpdatePageState,
+      runtimeTarget,
+      worktreeId
+    ]
+  )
+
+  const navigateToUrl = useCallback(
+    (url: string): void => {
+      void runRemoteNavigation('browser.goto', url)
+    },
+    [runRemoteNavigation]
+  )
+
+  const submitAddressBar = (): void => {
+    const searchEngine = useAppStore.getState().browserDefaultSearchEngine
+    const kagiSessionLink = useAppStore.getState().browserKagiSessionLink
+    const nextUrl = normalizeBrowserNavigationUrl(addressBarValue, searchEngine, {
+      kagiSessionLink
+    })
+    if (!nextUrl) {
+      const message = 'Enter a valid http(s) or localhost URL.'
+      setRemoteError(message)
+      onUpdatePageState(browserTab.id, {
+        loadError: {
+          code: 0,
+          description: message,
+          validatedUrl: redactKagiSessionToken(addressBarValue.trim()) || 'about:blank'
+        }
+      })
+      return
+    }
+    navigateToUrl(nextUrl)
+  }
+
+  const clickRemoteScreenshot = (event: React.MouseEvent<HTMLImageElement>): void => {
+    const target = runtimeTarget()
+    const pageId = remotePageIdRef.current
+    const image = imageRef.current
+    if (!target || !pageId || !image) {
+      return
+    }
+    const rect = image.getBoundingClientRect()
+    image.focus()
+    const scaleX = image.naturalWidth / rect.width
+    const scaleY = image.naturalHeight / rect.height
+    const x = Math.round((event.clientX - rect.left) * scaleX)
+    const y = Math.round((event.clientY - rect.top) * scaleY)
+    setBusy(true)
+    setRemoteError(null)
+    void (async () => {
+      try {
+        const params = { worktree: `id:${worktreeId}`, page: pageId }
+        await callRuntimeRpc(
+          target,
+          'browser.mouseMove',
+          { ...params, x, y },
+          { timeoutMs: 15_000 }
+        )
+        await callRuntimeRpc(target, 'browser.mouseDown', params, { timeoutMs: 15_000 })
+        await callRuntimeRpc(target, 'browser.mouseUp', params, { timeoutMs: 15_000 })
+        await new Promise((resolve) => window.setTimeout(resolve, 300))
+        await refreshRemoteView(pageId)
+      } catch (error) {
+        setRemoteError(error instanceof Error ? error.message : 'Remote click failed.')
+      } finally {
+        setBusy(false)
+      }
+    })()
+  }
+
+  const handleRemoteScreenshotKeyDown = (event: React.KeyboardEvent<HTMLImageElement>): void => {
+    if (isEditableKeyboardTarget(event.target)) {
+      return
+    }
+    const target = runtimeTarget()
+    const pageId = remotePageIdRef.current
+    if (!target || !pageId) {
+      return
+    }
+    const params = { worktree: `id:${worktreeId}`, page: pageId }
+    const text =
+      event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey ? event.key : null
+    const key = text ? null : getRemoteBrowserKeypressKey(event)
+    if (!text && !key) {
+      return
+    }
+    event.preventDefault()
+    setRemoteError(null)
+    void (async () => {
+      try {
+        if (text) {
+          await callRuntimeRpc(
+            target,
+            'browser.keyboardInsertText',
+            { ...params, text },
+            { timeoutMs: 15_000 }
+          )
+        } else if (key) {
+          await callRuntimeRpc(
+            target,
+            'browser.keypress',
+            { ...params, key },
+            { timeoutMs: 15_000 }
+          )
+        }
+        await new Promise((resolve) => window.setTimeout(resolve, 100))
+        await refreshRemoteView(pageId)
+      } catch (error) {
+        setRemoteError(error instanceof Error ? error.message : 'Remote keyboard input failed.')
+      }
+    })()
+  }
+
+  const handleRemoteScreenshotWheel = (event: React.WheelEvent<HTMLImageElement>): void => {
+    const target = runtimeTarget()
+    const pageId = remotePageIdRef.current
+    if (!target || !pageId) {
+      return
+    }
+    event.preventDefault()
+    setRemoteError(null)
+    void callRuntimeRpc(
+      target,
+      'browser.mouseWheel',
+      {
+        worktree: `id:${worktreeId}`,
+        page: pageId,
+        dx: Math.round(event.deltaX),
+        dy: Math.round(event.deltaY)
+      },
+      { timeoutMs: 15_000 }
+    )
+      .then(async () => {
+        await new Promise((resolve) => window.setTimeout(resolve, 100))
+        await refreshRemoteView(pageId)
+      })
+      .catch((error: unknown) => {
+        setRemoteError(error instanceof Error ? error.message : 'Remote scroll failed.')
+      })
+  }
+
+  return (
+    <div className="relative flex h-full min-h-0 flex-1 flex-col bg-background">
+      <div className="relative z-10 flex items-center gap-2 border-b border-border/70 bg-background/95 px-3 py-1.5">
+        <Button
+          size="icon"
+          variant="ghost"
+          className="h-7 w-7"
+          onClick={() => void runRemoteNavigation('browser.back')}
+        >
+          <ArrowLeft className="size-4" />
+        </Button>
+        <Button
+          size="icon"
+          variant="ghost"
+          className="h-7 w-7"
+          onClick={() => void runRemoteNavigation('browser.forward')}
+        >
+          <ArrowRight className="size-4" />
+        </Button>
+        <Button
+          size="icon"
+          variant="ghost"
+          className="h-7 w-7"
+          onClick={() => void runRemoteNavigation('browser.reload')}
+        >
+          {busy || browserTab.loading ? (
+            <Loader2 className="size-4 animate-spin" />
+          ) : (
+            <RefreshCw className="size-4" />
+          )}
+        </Button>
+        <BrowserAddressBar
+          value={addressBarValue}
+          onChange={setAddressBarValue}
+          onSubmit={submitAddressBar}
+          onNavigate={navigateToUrl}
+          inputRef={addressBarInputRef}
+        />
+      </div>
+      <div className="relative flex min-h-0 flex-1 items-center justify-center overflow-auto bg-muted/20">
+        {screenshotUrl ? (
+          <img
+            ref={imageRef}
+            src={screenshotUrl}
+            alt=""
+            tabIndex={0}
+            className="max-h-full max-w-full cursor-crosshair bg-white object-contain"
+            onClick={clickRemoteScreenshot}
+            onKeyDown={handleRemoteScreenshotKeyDown}
+            onWheel={handleRemoteScreenshotWheel}
+            draggable={false}
+          />
+        ) : (
+          <div className="flex max-w-sm flex-col items-center gap-2 px-6 text-center">
+            {busy ? (
+              <Loader2 className="size-5 animate-spin text-muted-foreground" />
+            ) : (
+              <Globe className="size-5 text-muted-foreground" />
+            )}
+            <div className="text-sm font-medium text-foreground">
+              {busy ? 'Opening remote browser' : 'Remote browser'}
+            </div>
+            <div className="text-xs leading-5 text-muted-foreground">
+              This pane is rendered from the active runtime server.
+            </div>
+          </div>
+        )}
+        {remoteError ? (
+          <div className="absolute bottom-4 left-1/2 max-w-md -translate-x-1/2 rounded-md border border-border bg-popover px-3 py-2 text-xs text-popover-foreground shadow-md">
+            {remoteError}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
 function BrowserPagePane({
   browserTab,
   workspaceId,
@@ -1563,14 +2073,22 @@ function BrowserPagePane({
           }
 
           try {
-            await window.api.fs.authorizeExternalPath({ targetPath: notebookPath })
-            const stat = await window.api.fs.stat({ filePath: notebookPath })
+            const activeWorktree = store.allWorktrees().find((w) => w.id === worktreeId)
+            const fileContext: RuntimeFileOperationArgs = {
+              settings: store.settings,
+              worktreeId,
+              worktreePath: activeWorktree?.path,
+              connectionId: undefined
+            }
+            if (!isRemoteRuntimeFileOperation(fileContext, notebookPath)) {
+              await window.api.fs.authorizeExternalPath({ targetPath: notebookPath })
+            }
+            const stat = await statRuntimePath(fileContext, notebookPath)
             if (stat.isDirectory) {
               navigateBrowserUrl(url)
               return
             }
 
-            const activeWorktree = store.allWorktrees().find((w) => w.id === worktreeId)
             let relativePath = notebookPath
             if (activeWorktree?.path && isPathInsideWorktree(notebookPath, activeWorktree.path)) {
               relativePath =
diff --git a/src/renderer/src/components/editor/CombinedDiffViewer.tsx b/src/renderer/src/components/editor/CombinedDiffViewer.tsx
index 83d4b6181ea..b444d713d54 100644
--- a/src/renderer/src/components/editor/CombinedDiffViewer.tsx
+++ b/src/renderer/src/components/editor/CombinedDiffViewer.tsx
@@ -9,6 +9,10 @@ import { useAppStore } from '@/store'
 import { joinPath } from '@/lib/path'
 import { setWithLRU } from '@/lib/scroll-cache'
 import { getConnectionId } from '@/lib/connection-context'
+import { findWorktreeById } from '@/store/slices/worktree-helpers'
+import { writeRuntimeFile } from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+import { getRuntimeGitBranchDiff, getRuntimeGitDiff } from '@/runtime/runtime-git-client'
 import '@/lib/monaco-setup'
 import { Button } from '@/components/ui/button'
 import type { OpenFile } from '@/store/slices/editor'
@@ -207,26 +211,40 @@ export default function CombinedDiffViewer({
       let result: GitDiffResult
       try {
         const connectionId = getConnectionId(file.worktreeId) ?? undefined
+        const state = useAppStore.getState()
+        const fileSettings = settingsForRuntimeOwner(state.settings, file.runtimeEnvironmentId)
         result =
           isBranchMode && branchCompare
-            ? ((await window.api.git.branchDiff({
-                worktreePath: file.filePath,
-                compare: {
-                  baseRef: branchCompare.baseRef,
-                  baseOid: branchCompare.baseOid!,
-                  headOid: branchCompare.headOid!,
-                  mergeBase: branchCompare.mergeBase!
+            ? ((await getRuntimeGitBranchDiff(
+                {
+                  settings: fileSettings,
+                  worktreeId: file.worktreeId,
+                  worktreePath: file.filePath,
+                  connectionId
                 },
-                filePath: entry.path,
-                oldPath: entry.oldPath,
-                connectionId
-              })) as GitDiffResult)
-            : ((await window.api.git.diff({
-                worktreePath: file.filePath,
-                filePath: entry.path,
-                staged: 'area' in entry && entry.area === 'staged',
-                connectionId
-              })) as GitDiffResult)
+                {
+                  compare: {
+                    baseRef: branchCompare.baseRef,
+                    baseOid: branchCompare.baseOid!,
+                    headOid: branchCompare.headOid!,
+                    mergeBase: branchCompare.mergeBase!
+                  },
+                  filePath: entry.path,
+                  oldPath: entry.oldPath
+                }
+              )) as GitDiffResult)
+            : ((await getRuntimeGitDiff(
+                {
+                  settings: fileSettings,
+                  worktreeId: file.worktreeId,
+                  worktreePath: file.filePath,
+                  connectionId
+                },
+                {
+                  filePath: entry.path,
+                  staged: 'area' in entry && entry.area === 'staged'
+                }
+              )) as GitDiffResult)
       } catch {
         result = {
           kind: 'text',
@@ -261,6 +279,7 @@ export default function CombinedDiffViewer({
       branchCompare?.mergeBase,
       branchEntries,
       file.filePath,
+      file.runtimeEnvironmentId,
       isBranchMode,
       uncommittedEntries
     ]
@@ -287,7 +306,20 @@ export default function CombinedDiffViewer({
       const absolutePath = joinPath(file.filePath, section.path)
       try {
         const connectionId = getConnectionId(file.worktreeId) ?? undefined
-        await window.api.fs.writeFile({ filePath: absolutePath, content, connectionId })
+        const state = useAppStore.getState()
+        const worktree = file.worktreeId
+          ? findWorktreeById(state.worktreesByRepo, file.worktreeId)
+          : null
+        await writeRuntimeFile(
+          {
+            settings: settingsForRuntimeOwner(state.settings, file.runtimeEnvironmentId),
+            worktreeId: file.worktreeId,
+            worktreePath: worktree?.path ?? null,
+            connectionId
+          },
+          absolutePath,
+          content
+        )
         setSections((prev) =>
           prev.map((s, i) => (i === index ? { ...s, modifiedContent: content, dirty: false } : s))
         )
@@ -295,7 +327,7 @@ export default function CombinedDiffViewer({
         console.error('Save failed:', err)
       }
     },
-    [file.filePath, file.worktreeId, sections]
+    [file.filePath, file.runtimeEnvironmentId, file.worktreeId, sections]
   )
 
   const handleSectionSaveRef = useRef(handleSectionSave)
diff --git a/src/renderer/src/components/editor/EditorContent.tsx b/src/renderer/src/components/editor/EditorContent.tsx
index 57ddc16864f..872e43e1766 100644
--- a/src/renderer/src/components/editor/EditorContent.tsx
+++ b/src/renderer/src/components/editor/EditorContent.tsx
@@ -237,6 +237,7 @@ export function EditorContent({
                 content={editorContent}
                 filePath={activeFile.filePath}
                 worktreeId={activeFile.worktreeId}
+                runtimeEnvironmentId={activeFile.runtimeEnvironmentId}
                 scrollCacheKey={`${editorViewStateKey}:rich`}
                 onContentChange={onContentChangeWithFm}
                 onDirtyStateHint={handleDirtyStateHint}
diff --git a/src/renderer/src/components/editor/EditorPanel.tsx b/src/renderer/src/components/editor/EditorPanel.tsx
index f7067db3144..3be4b61f5aa 100644
--- a/src/renderer/src/components/editor/EditorPanel.tsx
+++ b/src/renderer/src/components/editor/EditorPanel.tsx
@@ -38,6 +38,7 @@ import EditorViewToggle, {
 } from './EditorViewToggle'
 import { EditorContent } from './EditorContent'
 import { scrollTopCache, cursorPositionCache, diffViewStateCache } from '@/lib/scroll-cache'
+import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
 import type { GitDiffResult } from '../../../../shared/types'
 import {
   getOpenFilesForExternalFileChange,
@@ -60,6 +61,19 @@ import {
   isMarkdownPreviewShortcut
 } from './markdown-preview-controls'
 import type { EditorToggleValue } from './EditorViewToggle'
+import {
+  createRuntimePath,
+  getRuntimeFileReadScope,
+  readRuntimeFileContent,
+  renameRuntimePath,
+  runtimePathExists
+} from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+import {
+  getRuntimeGitBranchDiff,
+  getRuntimeGitDiff,
+  getRuntimeGitScope
+} from '@/runtime/runtime-git-client'
 
 const isMac = navigator.userAgent.includes('Mac')
 const isLinux = navigator.userAgent.includes('Linux')
@@ -199,6 +213,7 @@ function EditorPanelInner({
   const activeFileWorktreeId = activeFile?.worktreeId ?? null
   const activeFileMode = activeFile?.mode ?? null
   const activeFileDiffSource = activeFile?.diffSource
+  const activeFileRuntimeEnvironmentId = activeFile?.runtimeEnvironmentId
   const activeViewStateId = activeViewStateIdProp ?? activeFileId
   const [fileContents, setFileContents] = useState<Record<string, FileContent>>({})
   const [diffContents, setDiffContents] = useState<Record<string, DiffContent>>({})
@@ -389,18 +404,26 @@ function EditorPanelInner({
       try {
         const connectionId = getConnectionId(worktreeId ?? null) ?? undefined
         const restoredOpenFile = openFilesRef.current.find((file) => file.id === id)
-        if (
-          !connectionId &&
-          restoredOpenFile?.filePath === filePath &&
-          restoredOpenFile.relativePath === filePath
-        ) {
+        const activeSettings = useAppStore.getState().settings
+        const readSettings = settingsForRuntimeOwner(
+          activeSettings,
+          restoredOpenFile?.runtimeEnvironmentId
+        )
+        if (restoredOpenFile?.filePath === filePath && restoredOpenFile.relativePath === filePath) {
+          if (readSettings?.activeRuntimeEnvironmentId?.trim() || connectionId) {
+            // Why: restored external-file tabs contain client-local absolute
+            // paths. Remote runtime and SSH workspaces cannot read those paths
+            // without an explicit upload/import flow.
+            throw new Error('External local files are not available for remote workspaces.')
+          }
           // Why: external files selected through OS/browser/drop flows are
           // authorized in the main process, but that grant is in-memory. On
           // session restore, re-authorize only tabs that were stored with an
           // absolute relativePath because they came from outside a worktree.
           await window.api.fs.authorizeExternalPath({ targetPath: filePath })
         }
-        const key = inFlightReadKey(connectionId, filePath)
+        const readScope = getRuntimeFileReadScope(readSettings, connectionId)
+        const key = inFlightReadKey(readScope, filePath)
         // Why: share the IPC round-trip across split-pane EditorPanels viewing
         // the same file. The first caller starts the read and registers the
         // promise; concurrent callers (triggered by the same external-change
@@ -408,7 +431,13 @@ function EditorPanelInner({
         // downstream setContent transactions.
         let pending = inFlightFileReads.get(key)
         if (!pending) {
-          pending = window.api.fs.readFile({ filePath, connectionId }) as Promise<FileContent>
+          pending = readRuntimeFileContent({
+            settings: readSettings,
+            filePath,
+            relativePath: restoredOpenFile?.relativePath,
+            worktreeId,
+            connectionId
+          }) as Promise<FileContent>
           inFlightFileReads.set(key, pending)
           // Why: limit deduplication to synchronous callers (like N split panes
           // responding to the exact same event loop dispatch). Caching the promise
@@ -468,6 +497,9 @@ function EditorPanelInner({
           ? file.branchCompare
           : null
       const connectionId = getConnectionId(file.worktreeId) ?? undefined
+      const activeSettings = useAppStore.getState().settings
+      const fileSettings = settingsForRuntimeOwner(activeSettings, file.runtimeEnvironmentId)
+      const gitScope = getRuntimeGitScope(fileSettings, connectionId)
       // Why: Changes view mode runs on top of an edit-mode tab and asks git
       // for an unstaged diff against HEAD for that file. Use the 'unstaged'
       // diff-source key so multiple Changes tabs across split panes share one
@@ -479,7 +511,7 @@ function EditorPanelInner({
       const compareAgainstHead = file.mode === 'edit'
       const key = inFlightDiffKey(
         { ...file, diffSource: effectiveDiffSource },
-        connectionId,
+        gitScope,
         compareAgainstHead
       )
       // Why: same rationale as inFlightFileReads above — a single external
@@ -490,25 +522,37 @@ function EditorPanelInner({
       if (!pending) {
         pending = (
           effectiveDiffSource === 'branch' && branchCompare
-            ? window.api.git.branchDiff({
-                worktreePath,
-                compare: {
-                  baseRef: branchCompare.baseRef,
-                  baseOid: branchCompare.baseOid!,
-                  headOid: branchCompare.headOid!,
-                  mergeBase: branchCompare.mergeBase!
+            ? getRuntimeGitBranchDiff(
+                {
+                  settings: fileSettings,
+                  worktreeId: file.worktreeId,
+                  worktreePath,
+                  connectionId
                 },
-                filePath: file.relativePath,
-                oldPath: file.branchOldPath,
-                connectionId
-              })
-            : window.api.git.diff({
-                worktreePath,
-                filePath: file.relativePath,
-                staged: effectiveDiffSource === 'staged',
-                compareAgainstHead,
-                connectionId
-              })
+                {
+                  compare: {
+                    baseRef: branchCompare.baseRef,
+                    baseOid: branchCompare.baseOid!,
+                    headOid: branchCompare.headOid!,
+                    mergeBase: branchCompare.mergeBase!
+                  },
+                  filePath: file.relativePath,
+                  oldPath: file.branchOldPath
+                }
+              )
+            : getRuntimeGitDiff(
+                {
+                  settings: fileSettings,
+                  worktreeId: file.worktreeId,
+                  worktreePath,
+                  connectionId
+                },
+                {
+                  filePath: file.relativePath,
+                  staged: effectiveDiffSource === 'staged',
+                  compareAgainstHead
+                }
+              )
         ) as Promise<DiffContent>
         inFlightDiffReads.set(key, pending)
         queueMicrotask(() => {
@@ -885,10 +929,20 @@ function EditorPanelInner({
         oldPath.length - renameDialogFile.relativePath.length - 1
       )
       const newPath = `${worktreeRoot}/${newRelPath}`
+      const connectionId = getConnectionId(renameDialogFile.worktreeId) ?? undefined
+      const fileContext = {
+        settings: settingsForRuntimeOwner(
+          useAppStore.getState().settings,
+          renameDialogFile.runtimeEnvironmentId
+        ),
+        worktreeId: renameDialogFile.worktreeId,
+        worktreePath: worktreeRoot,
+        connectionId
+      }
 
       // Prevent silently overwriting an existing file (but allow keeping
       // the current name — the file's own path is not a conflict).
-      if (newPath !== oldPath && (await window.api.shell.pathExists(newPath))) {
+      if (newPath !== oldPath && (await runtimePathExists(fileContext, newPath))) {
         setRenameError('A file with that name already exists')
         return
       }
@@ -925,12 +979,12 @@ function EditorPanelInner({
       // if the directory already exists (assertNotExists guard), so only call
       // it when the directory is not yet on disk.
       const newDir = newPath.slice(0, newPath.lastIndexOf('/'))
-      if (newDir !== worktreeRoot && !(await window.api.shell.pathExists(newDir))) {
-        await window.api.fs.createDir({ dirPath: newDir })
+      if (newDir !== worktreeRoot && !(await runtimePathExists(fileContext, newDir))) {
+        await createRuntimePath(fileContext, newDir, 'directory')
       }
 
       try {
-        await window.api.fs.rename({ oldPath, newPath })
+        await renameRuntimePath(fileContext, oldPath, newPath)
       } catch (err) {
         setRenameError(err instanceof Error ? err.message : 'Failed to rename file')
         return
@@ -941,6 +995,7 @@ function EditorPanelInner({
         filePath: newPath,
         relativePath: newRelPath,
         worktreeId: renameDialogFile.worktreeId,
+        runtimeEnvironmentId: renameDialogFile.runtimeEnvironmentId,
         language: detectLanguage(newRelPath),
         mode: 'edit'
       })
@@ -1008,6 +1063,7 @@ function EditorPanelInner({
         filePath: activeFilePath,
         relativePath: activeFileRelativePath,
         worktreeId: activeFileWorktreeId,
+        runtimeEnvironmentId: activeFileRuntimeEnvironmentId,
         language: shortcutLanguage
       })
     }
@@ -1019,6 +1075,7 @@ function EditorPanelInner({
     activeFileMode,
     activeFilePath,
     activeFileRelativePath,
+    activeFileRuntimeEnvironmentId,
     activeFileWorktreeId,
     openMarkdownPreview
   ])
@@ -1230,6 +1287,7 @@ function EditorPanelInner({
                         filePath: activeFile.filePath,
                         relativePath: activeFile.relativePath,
                         worktreeId: activeFile.worktreeId,
+                        runtimeEnvironmentId: activeFile.runtimeEnvironmentId,
                         language: resolvedLanguage
                       })
                     }
@@ -1242,6 +1300,17 @@ function EditorPanelInner({
                 {canShowMarkdownPreview && <DropdownMenuSeparator />}
                 <DropdownMenuItem
                   onSelect={() => {
+                    if (
+                      isLocalPathOpenBlocked(
+                        settingsForRuntimeOwner(settings, activeFile.runtimeEnvironmentId),
+                        {
+                          connectionId: getConnectionId(activeFile.worktreeId)
+                        }
+                      )
+                    ) {
+                      showLocalPathOpenBlockedToast()
+                      return
+                    }
                     window.api.shell.openPath(activeFile.filePath)
                   }}
                 >
@@ -1419,6 +1488,13 @@ function EditorPanelInner({
                 ?.path ?? '')
             : ''
         }
+        disableBrowse={Boolean(
+          settingsForRuntimeOwner(
+            settings,
+            renameDialogFile?.runtimeEnvironmentId
+          )?.activeRuntimeEnvironmentId?.trim() ||
+          (renameDialogFile ? getConnectionId(renameDialogFile.worktreeId) : null)
+        )}
         externalError={renameError}
         onClose={() => {
           setRenameDialogFileId(null)
diff --git a/src/renderer/src/components/editor/MarkdownPreview.tsx b/src/renderer/src/components/editor/MarkdownPreview.tsx
index bebadac8475..05ab3574c0e 100644
--- a/src/renderer/src/components/editor/MarkdownPreview.tsx
+++ b/src/renderer/src/components/editor/MarkdownPreview.tsx
@@ -21,6 +21,7 @@ import { Input } from '@/components/ui/input'
 import { useAppStore } from '@/store'
 import { toast } from 'sonner'
 import { computeEditorFontSize } from '@/lib/editor-font-zoom'
+import { getConnectionId } from '@/lib/connection-context'
 import { scrollTopCache, setWithLRU } from '@/lib/scroll-cache'
 import { detectLanguage } from '@/lib/language-detect'
 import type { MarkdownDocument, Worktree } from '../../../../shared/types'
@@ -48,7 +49,9 @@ import {
 } from './markdown-preview-search'
 import { usePreserveSectionDuringExternalEdit } from './usePreserveSectionDuringExternalEdit'
 import { openHttpLink } from '@/lib/http-link-routing'
+import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
 import { markdownPreviewUrlTransform } from './markdown-preview-url-transform'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 import { buildMarkdownTableOfContents } from './markdown-table-of-contents'
 import { MarkdownTableOfContentsPanel } from './MarkdownTableOfContentsPanel'
 
@@ -188,9 +191,25 @@ export default function MarkdownPreview({
   const setMarkdownViewMode = useAppStore((s) => s.setMarkdownViewMode)
   const setPendingEditorReveal = useAppStore((s) => s.setPendingEditorReveal)
   const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
+  const sourceRuntimeEnvironmentId = useAppStore(
+    (s) => s.openFiles.find((file) => file.filePath === filePath)?.runtimeEnvironmentId
+  )
   const sourceWorktree = findWorktreeForMarkdownPreviewPath(worktreesByRepo, filePath)
+  const sourceConnectionId = sourceWorktree ? getConnectionId(sourceWorktree.id) : null
   const worktreeRoot = sourceWorktree?.path ?? null
   const settings = useAppStore((s) => s.settings)
+  const imageRuntimeContext = useMemo(
+    () =>
+      sourceWorktree
+        ? {
+            settings: settingsForRuntimeOwner(settings, sourceRuntimeEnvironmentId),
+            worktreeId: sourceWorktree.id,
+            worktreePath: sourceWorktree.path,
+            connectionId: sourceConnectionId
+          }
+        : undefined,
+    [settings, sourceConnectionId, sourceRuntimeEnvironmentId, sourceWorktree]
+  )
   const editorFontZoomLevel = useAppStore((s) => s.editorFontZoomLevel)
   const editorFontSize = computeEditorFontSize(14, editorFontZoomLevel)
   const isDark =
@@ -516,6 +535,20 @@ export default function MarkdownPreview({
               return
             }
             if (parsed.protocol === 'file:') {
+              if (
+                isLocalPathOpenBlocked(
+                  settingsForRuntimeOwner(
+                    useAppStore.getState().settings,
+                    sourceRuntimeEnvironmentId
+                  ),
+                  { connectionId: sourceConnectionId }
+                )
+              ) {
+                // Why: modifier-open delegates to the client OS. Server-local
+                // file:// targets from remote runtime/SSH worktrees cannot be opened locally.
+                showLocalPathOpenBlockedToast()
+                return
+              }
               const classified = resolveMarkdownLinkTarget(href, filePath, worktreeRoot)
               if (classified?.kind === 'markdown') {
                 // Why: use the classifier's stripped absolutePath (no `:line:col`
@@ -565,10 +598,25 @@ export default function MarkdownPreview({
               void activateMarkdownLink(href, {
                 sourceFilePath: filePath,
                 worktreeId: sourceWorktree.id,
-                worktreeRoot: sourceWorktree.path
+                worktreeRoot: sourceWorktree.path,
+                runtimeEnvironmentId: sourceRuntimeEnvironmentId
               })
               return
             }
+            if (
+              isLocalPathOpenBlocked(
+                settingsForRuntimeOwner(
+                  useAppStore.getState().settings,
+                  sourceRuntimeEnvironmentId
+                ),
+                { connectionId: sourceConnectionId }
+              )
+            ) {
+              // Why: without a workspace match, opening a file URI delegates to
+              // the client OS. Remote runtime/SSH paths are not local files.
+              showLocalPathOpenBlockedToast()
+              return
+            }
             void window.api.shell.openFileUri(target.toString())
             return
           }
@@ -587,6 +635,7 @@ export default function MarkdownPreview({
               filePath: absolutePath,
               relativePath,
               worktreeId: targetWorktree.id,
+              runtimeEnvironmentId: sourceRuntimeEnvironmentId,
               language,
               mode: 'edit'
             })
@@ -610,6 +659,7 @@ export default function MarkdownPreview({
                 filePath: absolutePath,
                 relativePath,
                 worktreeId: targetWorktree.id,
+                runtimeEnvironmentId: sourceRuntimeEnvironmentId,
                 language
               },
               { anchor: target.hash ? target.hash.slice(1) : null }
@@ -621,6 +671,7 @@ export default function MarkdownPreview({
             filePath: absolutePath,
             relativePath,
             worktreeId: targetWorktree.id,
+            runtimeEnvironmentId: sourceRuntimeEnvironmentId,
             language,
             mode: 'edit'
           })
@@ -642,7 +693,7 @@ export default function MarkdownPreview({
         // eslint-disable-next-line react-hooks/rules-of-hooks -- react-markdown
         // instantiates component overrides as regular React components, so hooks
         // are valid here despite the lowercase function name.
-        const resolvedSrc = useLocalImageSrc(src, filePath)
+        const resolvedSrc = useLocalImageSrc(src, filePath, undefined, imageRuntimeContext)
         const handleImageClick = (event: React.MouseEvent<HTMLImageElement>): void => {
           if (!isMarkdownPreviewOpenModifier(event, isMac)) {
             return
@@ -657,7 +708,8 @@ export default function MarkdownPreview({
           void activateMarkdownLink(src, {
             sourceFilePath: filePath,
             worktreeId: sourceWorktree.id,
-            worktreeRoot: sourceWorktree.path
+            worktreeRoot: sourceWorktree.path,
+            runtimeEnvironmentId: sourceRuntimeEnvironmentId
           })
         }
 
@@ -752,6 +804,7 @@ export default function MarkdownPreview({
     activateMarkdownLink,
     isDark,
     isMac,
+    imageRuntimeContext,
     markdownDocumentIndex,
     onOpenDocument,
     openFile,
@@ -759,6 +812,8 @@ export default function MarkdownPreview({
     scrollToAnchor,
     setMarkdownViewMode,
     setPendingEditorReveal,
+    sourceConnectionId,
+    sourceRuntimeEnvironmentId,
     sourceWorktree,
     worktreeRoot,
     worktreesByRepo
diff --git a/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx b/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx
index 3d9def2b593..a702e9d6d5b 100644
--- a/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx
+++ b/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx
@@ -9,6 +9,7 @@ import {
 import { useAppStore } from '@/store'
 import { getConnectionId } from '@/lib/connection-context'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
+import { getRuntimeGitRemoteFileUrl } from '@/runtime/runtime-git-client'
 
 type MonacoGutterContextMenuProps = {
   open: boolean
@@ -60,12 +61,15 @@ export function MonacoGutterContextMenu({
               return
             }
             const connectionId = getConnectionId(activeFile?.worktreeId ?? null) ?? undefined
-            const url = await window.api.git.remoteFileUrl({
-              worktreePath: worktree.path,
-              relativePath,
-              line,
-              connectionId
-            })
+            const url = await getRuntimeGitRemoteFileUrl(
+              {
+                settings: state.settings,
+                worktreeId: activeFile.worktreeId,
+                worktreePath: worktree.path,
+                connectionId
+              },
+              { relativePath, line }
+            )
             if (url) {
               window.api.ui.writeClipboardText(url)
             }
diff --git a/src/renderer/src/components/editor/RichMarkdownEditor.tsx b/src/renderer/src/components/editor/RichMarkdownEditor.tsx
index 096ed5062f7..163b31c8bef 100644
--- a/src/renderer/src/components/editor/RichMarkdownEditor.tsx
+++ b/src/renderer/src/components/editor/RichMarkdownEditor.tsx
@@ -11,6 +11,7 @@ import { RichMarkdownToolbar } from './RichMarkdownToolbar'
 import { encodeRawMarkdownHtmlForRichEditor } from './raw-markdown-html'
 import { useLocalImagePick } from './useLocalImagePick'
 import { createRichMarkdownExtensions } from './rich-markdown-extensions'
+import { getConnectionId } from '@/lib/connection-context'
 import { slashCommands, syncDocLinkMenu, syncSlashMenu } from './rich-markdown-commands'
 import type {
   DocLinkMenuRow,
@@ -35,7 +36,9 @@ import { normalizeSoftBreaks } from './rich-markdown-normalize'
 import { autoFocusRichEditor } from './rich-markdown-auto-focus'
 import { handleRichMarkdownCut } from './rich-markdown-cut-handler'
 import { openHttpLink } from '@/lib/http-link-routing'
+import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
 import { toast } from 'sonner'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 import { isSingleEmptyTopLevelOrderedList } from './rich-markdown-list-continuation'
 import {
   absolutePathToFileUri as toFileUrlForOsEscape,
@@ -54,6 +57,7 @@ type RichMarkdownEditorProps = {
   content: string
   filePath: string
   worktreeId: string
+  runtimeEnvironmentId?: string | null
   scrollCacheKey: string
   onContentChange: (content: string) => void
   onDirtyStateHint: (dirty: boolean) => void
@@ -168,6 +172,7 @@ export default function RichMarkdownEditor({
   content,
   filePath,
   worktreeId,
+  runtimeEnvironmentId,
   scrollCacheKey,
   onContentChange,
   onDirtyStateHint,
@@ -179,6 +184,7 @@ export default function RichMarkdownEditor({
   headerSlot
 }: RichMarkdownEditorProps): React.JSX.Element {
   const rootRef = useRef<HTMLDivElement | null>(null)
+  const settings = useAppStore((s) => s.settings)
   const editorFontZoomLevel = useAppStore((s) => s.editorFontZoomLevel)
   const activateMarkdownLink = useAppStore((s) => s.activateMarkdownLink)
   const worktreeRoot = useAppStore((s) => {
@@ -341,7 +347,12 @@ export default function RichMarkdownEditor({
           if (!src) {
             return false
           }
-          void activateMarkdownLink(src, { sourceFilePath: filePath, worktreeId, worktreeRoot })
+          void activateMarkdownLink(src, {
+            sourceFilePath: filePath,
+            worktreeId,
+            worktreeRoot,
+            runtimeEnvironmentId
+          })
           return true
         }
         if (clickedNode?.type.name === 'markdownDocLink') {
@@ -370,7 +381,20 @@ export default function RichMarkdownEditor({
           }
           if (classified.kind === 'external') {
             openHttpLink(classified.url, { forceSystemBrowser: true })
-          } else if (classified.kind === 'markdown') {
+            return true
+          }
+          if (
+            isLocalPathOpenBlocked(
+              settingsForRuntimeOwner(useAppStore.getState().settings, runtimeEnvironmentId),
+              { connectionId: getConnectionId(worktreeId) }
+            )
+          ) {
+            // Why: Shift-click opens through the client OS. Server-local paths
+            // from remote runtime/SSH worktrees are not meaningful on this client.
+            showLocalPathOpenBlockedToast()
+            return true
+          }
+          if (classified.kind === 'markdown') {
             void window.api.shell.pathExists(classified.absolutePath).then((exists) => {
               if (!exists) {
                 toast.error(`File not found: ${classified.relativePath}`)
@@ -383,7 +407,12 @@ export default function RichMarkdownEditor({
           }
           return true
         }
-        void activateMarkdownLink(href, { sourceFilePath: filePath, worktreeId, worktreeRoot })
+        void activateMarkdownLink(href, {
+          sourceFilePath: filePath,
+          worktreeId,
+          worktreeRoot,
+          runtimeEnvironmentId
+        })
         return true
       }
     },
@@ -497,22 +526,30 @@ export default function RichMarkdownEditor({
 
   useModifierHeldClass(rootRef, isMac)
 
-  // Why: the custom Image extension reads filePath from editor.storage to resolve
-  // relative image src values to file:// URLs for display. After updating the
-  // stored path we dispatch a no-op transaction so ProseMirror re-renders image
-  // nodes with the new resolved src (renderHTML reads storage at render time).
+  // Why: the custom Image extension reads filePath/runtimeContext from storage
+  // to resolve relative image src values. After updating storage we dispatch a
+  // no-op transaction so ProseMirror re-renders image nodes with the new source.
   useEffect(() => {
     if (editor) {
       isApplyingProgrammaticUpdateRef.current = true
       try {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ;(editor.storage as any).image.filePath = filePath
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ;(editor.storage as any).image.runtimeContext = worktreeRoot
+          ? {
+              settings: settingsForRuntimeOwner(settings, runtimeEnvironmentId),
+              worktreeId,
+              worktreePath: worktreeRoot,
+              connectionId: getConnectionId(worktreeId)
+            }
+          : undefined
         editor.view.dispatch(editor.state.tr)
       } finally {
         isApplyingProgrammaticUpdateRef.current = false
       }
     }
-  }, [editor, filePath])
+  }, [editor, filePath, runtimeEnvironmentId, settings, worktreeId, worktreeRoot])
 
   // Why: the doc link NodeView reads the document list from storage to style
   // resolved vs. missing links. The no-op transaction with meta flag triggers
@@ -531,7 +568,7 @@ export default function RichMarkdownEditor({
     }
   }, [editor, markdownDocuments])
 
-  const handleLocalImagePick = useLocalImagePick(editor, filePath)
+  const handleLocalImagePick = useLocalImagePick(editor, filePath, worktreeId, runtimeEnvironmentId)
 
   useEffect(() => {
     handleLocalImagePickRef.current = handleLocalImagePick
@@ -546,7 +583,8 @@ export default function RichMarkdownEditor({
   } = useLinkBubble(editor, rootRef, linkBubble, setLinkBubble, setIsEditingLink, {
     sourceFilePath: filePath,
     worktreeId,
-    worktreeRoot
+    worktreeRoot,
+    runtimeEnvironmentId
   })
 
   useEffect(() => {
diff --git a/src/renderer/src/components/editor/UntitledFileRenameDialog.tsx b/src/renderer/src/components/editor/UntitledFileRenameDialog.tsx
index a015a011b39..de63bfdb4dd 100644
--- a/src/renderer/src/components/editor/UntitledFileRenameDialog.tsx
+++ b/src/renderer/src/components/editor/UntitledFileRenameDialog.tsx
@@ -16,6 +16,7 @@ type UntitledFileRenameDialogProps = {
   currentName: string
   worktreePath: string
   externalError?: string | null
+  disableBrowse?: boolean
   onClose: () => void
   onConfirm: (newRelativePath: string) => void
 }
@@ -25,6 +26,7 @@ export function UntitledFileRenameDialog({
   currentName,
   worktreePath,
   externalError,
+  disableBrowse = false,
   onClose,
   onConfirm
 }: UntitledFileRenameDialogProps): React.JSX.Element {
@@ -143,8 +145,11 @@ export function UntitledFileRenameDialog({
                 variant="outline"
                 size="icon"
                 className="h-8 w-8 shrink-0"
+                disabled={disableBrowse}
                 onClick={() => void handleBrowse()}
-                title="Browse folders"
+                title={
+                  disableBrowse ? 'Folder picker unavailable for remote files' : 'Browse folders'
+                }
               >
                 <FolderOpen className="size-3.5" />
               </Button>
diff --git a/src/renderer/src/components/editor/editor-autosave-controller.test.ts b/src/renderer/src/components/editor/editor-autosave-controller.test.ts
index b36b5b472e9..6edf848c54e 100644
--- a/src/renderer/src/components/editor/editor-autosave-controller.test.ts
+++ b/src/renderer/src/components/editor/editor-autosave-controller.test.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: autosave behavior depends on event wiring,
+   dirty drafts, remote routing, quiesce, and failure cleanup in one harness. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createStore, type StoreApi } from 'zustand/vanilla'
 import { createEditorSlice } from '@/store/slices/editor'
@@ -7,6 +9,11 @@ import { requestEditorFileSave, requestEditorSaveQuiesce } from './editor-autosa
 import { attachEditorAutosaveController } from './editor-autosave-controller'
 import { registerPendingEditorFlush } from './editor-pending-flush'
 import { __clearSelfWriteRegistryForTests, hasRecentSelfWrite } from './editor-self-write-registry'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '@/runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '@/runtime/runtime-rpc-client'
 
 type WindowStub = {
   addEventListener: Window['addEventListener']
@@ -18,6 +25,9 @@ type WindowStub = {
     fs: {
       writeFile: ReturnType<typeof vi.fn>
     }
+    runtimeEnvironments?: {
+      call: ReturnType<typeof vi.fn>
+    }
   }
 }
 
@@ -107,6 +117,70 @@ describe('attachEditorAutosaveController', () => {
     }
   })
 
+  it('saves remote files through the owning runtime environment', async () => {
+    clearRuntimeCompatibilityCacheForTests()
+    const writeFile = vi.fn().mockResolvedValue(undefined)
+    const runtimeCall = vi.fn().mockResolvedValue({
+      ok: true,
+      result: {},
+      _meta: { runtimeId: 'runtime-env-1' }
+    })
+    const runtimeTransportCall = vi.fn((args: RuntimeEnvironmentCallRequest) => {
+      return (
+        createCompatibleRuntimeStatusResponseIfNeeded(args, 'runtime-env-1') ?? runtimeCall(args)
+      )
+    })
+    const eventTarget = new EventTarget()
+    vi.stubGlobal('window', {
+      addEventListener: eventTarget.addEventListener.bind(eventTarget),
+      removeEventListener: eventTarget.removeEventListener.bind(eventTarget),
+      dispatchEvent: eventTarget.dispatchEvent.bind(eventTarget),
+      setTimeout: globalThis.setTimeout.bind(globalThis),
+      clearTimeout: globalThis.clearTimeout.bind(globalThis),
+      api: {
+        fs: { writeFile },
+        runtimeEnvironments: { call: runtimeTransportCall }
+      }
+    } satisfies WindowStub)
+
+    const store = createEditorStore()
+    store.setState({
+      settings: {
+        editorAutoSave: true,
+        editorAutoSaveDelayMs: 1000,
+        activeRuntimeEnvironmentId: 'env-2'
+      } as never,
+      worktreesByRepo: {
+        'repo-1': [{ id: 'wt-1', repoId: 'repo-1', path: '/remote/repo' }] as never
+      }
+    })
+    store.getState().openFile({
+      filePath: '/remote/repo/file.ts',
+      relativePath: 'file.ts',
+      worktreeId: 'wt-1',
+      runtimeEnvironmentId: 'env-1',
+      language: 'typescript',
+      mode: 'edit'
+    })
+    store.getState().setEditorDraft('/remote/repo/file.ts', 'edited')
+    store.getState().markFileDirty('/remote/repo/file.ts', true)
+
+    const cleanup = attachEditorAutosaveController(store)
+    try {
+      await requestDirtyFileSave()
+
+      expect(runtimeCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.write',
+        params: { worktree: 'wt-1', relativePath: 'file.ts', content: 'edited' },
+        timeoutMs: 15_000
+      })
+      expect(writeFile).not.toHaveBeenCalled()
+    } finally {
+      cleanup()
+    }
+  })
+
   it('flushes mounted rich-editor changes before restart-driven dirty-file saves', async () => {
     const writeFile = vi.fn().mockResolvedValue(undefined)
     const eventTarget = new EventTarget()
diff --git a/src/renderer/src/components/editor/editor-autosave-controller.ts b/src/renderer/src/components/editor/editor-autosave-controller.ts
index 1d94c6955ed..73c2817d7ca 100644
--- a/src/renderer/src/components/editor/editor-autosave-controller.ts
+++ b/src/renderer/src/components/editor/editor-autosave-controller.ts
@@ -1,7 +1,13 @@
+/* eslint-disable max-lines -- Why: autosave owns the save queue, quiesce
+coordination, and dirty-file shutdown hooks; keeping those lifecycles together
+avoids split-brain saves across visible and hidden editors. */
 import type { StoreApi } from 'zustand'
 import type { AppState } from '@/store'
 import type { OpenFile } from '@/store/slices/editor'
 import { getConnectionId } from '@/lib/connection-context'
+import { findWorktreeById } from '@/store/slices/worktree-helpers'
+import { writeRuntimeFile } from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 import {
   canAutoSaveOpenFile,
   getOpenFilesForExternalFileChange,
@@ -69,6 +75,9 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
 
         const contentToSave = state.editorDrafts[file.id] ?? fallbackContent
         const connectionId = getConnectionId(liveFile.worktreeId) ?? undefined
+        const worktree = liveFile.worktreeId
+          ? findWorktreeById(state.worktreesByRepo ?? {}, liveFile.worktreeId)
+          : null
         // Why: stamp before the write so the fs:changed event that our own
         // write produces is ignored by useEditorExternalWatch instead of
         // round-tripping back into a setContent that jumps the cursor to the
@@ -76,11 +85,16 @@ export function attachEditorAutosaveController(store: AppStoreApi): () => void {
         // debounce window). See editor-self-write-registry.
         recordSelfWrite(liveFile.filePath)
         try {
-          await window.api.fs.writeFile({
-            filePath: liveFile.filePath,
-            content: contentToSave,
-            connectionId
-          })
+          await writeRuntimeFile(
+            {
+              settings: settingsForRuntimeOwner(state.settings, liveFile.runtimeEnvironmentId),
+              worktreeId: liveFile.worktreeId,
+              worktreePath: worktree?.path ?? null,
+              connectionId
+            },
+            liveFile.filePath,
+            contentToSave
+          )
         } catch (error) {
           // Why: the self-write stamp is only valid if a disk write actually
           // happened. Clearing it on failure keeps the external watcher from
diff --git a/src/renderer/src/components/editor/rich-markdown-extensions.ts b/src/renderer/src/components/editor/rich-markdown-extensions.ts
index 4cc560b2636..89e8478d134 100644
--- a/src/renderer/src/components/editor/rich-markdown-extensions.ts
+++ b/src/renderer/src/components/editor/rich-markdown-extensions.ts
@@ -14,6 +14,7 @@ import { BlockMath, InlineMath } from '@tiptap/extension-mathematics'
 import { Markdown } from '@tiptap/markdown'
 import { createLowlight, common } from 'lowlight'
 import { loadLocalImageSrc, onImageCacheInvalidated } from './useLocalImageSrc'
+import type { RuntimeFileOperationArgs } from '@/runtime/runtime-file-client'
 import { RawMarkdownHtmlBlock, RawMarkdownHtmlInline } from './raw-markdown-html'
 import { MarkdownDocLink } from './rich-markdown-doc-link'
 import { RichMarkdownCodeBlock } from './RichMarkdownCodeBlock'
@@ -56,7 +57,7 @@ export function createRichMarkdownExtensions({
     // and works identically in dev and production modes.
     Image.extend({
       addStorage() {
-        return { filePath: '' }
+        return { filePath: '', runtimeContext: undefined as RuntimeFileOperationArgs | undefined }
       },
       addNodeView() {
         return ({ node, HTMLAttributes }) => {
@@ -80,11 +81,14 @@ export function createRichMarkdownExtensions({
 
           const loadImage = (src: string | undefined): void => {
             const fp = this.storage.filePath as string
+            const runtimeContext = this.storage.runtimeContext as
+              | RuntimeFileOperationArgs
+              | undefined
             if (src && fp) {
               // Why: when IPC resolution fails (e.g. unsupported format),
               // the ternary falls back to the raw src so the browser can
               // attempt its own loading rather than leaving a broken image.
-              void loadLocalImageSrc(src, fp).then((resolved) => {
+              void loadLocalImageSrc(src, fp, undefined, runtimeContext).then((resolved) => {
                 img.src = resolved ? resolved : src
               })
             } else if (src) {
diff --git a/src/renderer/src/components/editor/useLinkBubble.ts b/src/renderer/src/components/editor/useLinkBubble.ts
index a91b199b110..76941e0dc43 100644
--- a/src/renderer/src/components/editor/useLinkBubble.ts
+++ b/src/renderer/src/components/editor/useLinkBubble.ts
@@ -20,6 +20,7 @@ export function useLinkBubble(
     sourceFilePath: string
     worktreeId: string
     worktreeRoot: string | null
+    runtimeEnvironmentId?: string | null
   }
 ): {
   handleLinkSave: (href: string) => void
@@ -108,7 +109,8 @@ export function useLinkBubble(
     void activateMarkdownLink(linkBubble.href, {
       sourceFilePath: linkContext.sourceFilePath,
       worktreeId: linkContext.worktreeId,
-      worktreeRoot: linkContext.worktreeRoot
+      worktreeRoot: linkContext.worktreeRoot,
+      runtimeEnvironmentId: linkContext.runtimeEnvironmentId
     })
   }, [
     activateMarkdownLink,
@@ -116,6 +118,7 @@ export function useLinkBubble(
     linkContext.sourceFilePath,
     linkContext.worktreeId,
     linkContext.worktreeRoot,
+    linkContext.runtimeEnvironmentId,
     rootRef
   ])
 
diff --git a/src/renderer/src/components/editor/useLocalImagePick.ts b/src/renderer/src/components/editor/useLocalImagePick.ts
index 8c1446ac236..444a849ca1d 100644
--- a/src/renderer/src/components/editor/useLocalImagePick.ts
+++ b/src/renderer/src/components/editor/useLocalImagePick.ts
@@ -2,8 +2,18 @@ import { useCallback } from 'react'
 import { toast } from 'sonner'
 import type { Editor } from '@tiptap/react'
 import { extractIpcErrorMessage, getImageCopyDestination } from './rich-markdown-image-utils'
+import { useAppStore } from '@/store'
+import { getConnectionId } from '@/lib/connection-context'
+import { basename, dirname } from '@/lib/path'
+import { importExternalPathsToRuntime } from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 
-export function useLocalImagePick(editor: Editor | null, filePath: string): () => Promise<void> {
+export function useLocalImagePick(
+  editor: Editor | null,
+  filePath: string,
+  worktreeId: string | null,
+  runtimeEnvironmentId?: string | null
+): () => Promise<void> {
   return useCallback(async () => {
     if (!editor) {
       return
@@ -18,6 +28,45 @@ export function useLocalImagePick(editor: Editor | null, filePath: string): () =
       if (!srcPath) {
         return
       }
+      const connectionId = getConnectionId(worktreeId) ?? undefined
+      const settings = settingsForRuntimeOwner(
+        useAppStore.getState().settings,
+        runtimeEnvironmentId
+      )
+      if (settings?.activeRuntimeEnvironmentId?.trim() || connectionId) {
+        const worktreePath = getWorktreePath(worktreeId)
+        if (settings?.activeRuntimeEnvironmentId?.trim() && !worktreePath) {
+          toast.error('Worktree path not available.')
+          return
+        }
+        // Why: picked images are client-local files while remote markdown lives
+        // on the server. Upload beside the markdown file before inserting the
+        // relative image path so preview/save works from any client.
+        const { results } = await importExternalPathsToRuntime(
+          {
+            settings,
+            worktreeId,
+            worktreePath,
+            connectionId
+          },
+          [srcPath],
+          dirname(filePath)
+        )
+        const imported = results.find((result) => result.status === 'imported')
+        if (!imported) {
+          toast.error('Failed to insert image.')
+          return
+        }
+        editor
+          .chain()
+          .focus()
+          .insertContentAt(insertPos, {
+            type: 'image',
+            attrs: { src: basename(imported.destPath) }
+          })
+          .run()
+        return
+      }
       // Why: copy the image next to the markdown file and insert a relative path
       // so the markdown stays portable and doesn't bloat with base64 data.
       const { imageName, destPath } = await getImageCopyDestination(filePath, srcPath)
@@ -35,5 +84,14 @@ export function useLocalImagePick(editor: Editor | null, filePath: string): () =
     } catch (err) {
       toast.error(extractIpcErrorMessage(err, 'Failed to insert image.'))
     }
-  }, [editor, filePath])
+  }, [editor, filePath, runtimeEnvironmentId, worktreeId])
+}
+
+function getWorktreePath(worktreeId: string | null): string | null {
+  if (!worktreeId) {
+    return null
+  }
+  const state = useAppStore.getState()
+  const worktrees = Object.values(state.worktreesByRepo ?? {}).flat()
+  return worktrees.find((worktree) => worktree.id === worktreeId)?.path ?? null
 }
diff --git a/src/renderer/src/components/editor/useLocalImageSrc.test.ts b/src/renderer/src/components/editor/useLocalImageSrc.test.ts
new file mode 100644
index 00000000000..736be5a7672
--- /dev/null
+++ b/src/renderer/src/components/editor/useLocalImageSrc.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { getLocalImageCacheKey } from './useLocalImageSrc'
+
+describe('getLocalImageCacheKey', () => {
+  it('scopes local markdown image cache entries by runtime owner', () => {
+    const localKey = getLocalImageCacheKey('/repo/docs/logo.png', null, {
+      settings: { activeRuntimeEnvironmentId: null },
+      worktreeId: 'wt-1',
+      worktreePath: '/repo'
+    })
+    const remoteKey = getLocalImageCacheKey('/repo/docs/logo.png', null, {
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      worktreeId: 'wt-1',
+      worktreePath: '/repo'
+    })
+    const otherRemoteKey = getLocalImageCacheKey('/repo/docs/logo.png', null, {
+      settings: { activeRuntimeEnvironmentId: 'env-2' },
+      worktreeId: 'wt-1',
+      worktreePath: '/repo'
+    })
+
+    expect(localKey).not.toBe(remoteKey)
+    expect(remoteKey).not.toBe(otherRemoteKey)
+  })
+})
diff --git a/src/renderer/src/components/editor/useLocalImageSrc.ts b/src/renderer/src/components/editor/useLocalImageSrc.ts
index 3206e99b353..1f55756fba7 100644
--- a/src/renderer/src/components/editor/useLocalImageSrc.ts
+++ b/src/renderer/src/components/editor/useLocalImageSrc.ts
@@ -1,5 +1,7 @@
 import { useEffect, useState } from 'react'
 import { resolveImageAbsolutePath } from './markdown-preview-links'
+import type { RuntimeFileOperationArgs } from '@/runtime/runtime-file-client'
+import { readRuntimeFilePreview } from '@/runtime/runtime-file-client'
 
 // Why: the renderer is served from http://localhost in dev mode, so file://
 // URLs in <img> tags are blocked by cross-origin restrictions. Loading images
@@ -9,6 +11,21 @@ import { resolveImageAbsolutePath } from './markdown-preview-links'
 const BLOB_URL_CACHE_MAX_SIZE = 100
 const blobUrlCache = new Map<string, string>()
 
+export function getLocalImageCacheKey(
+  absolutePath: string,
+  connectionId?: string | null,
+  runtimeContext?: Omit<RuntimeFileOperationArgs, 'connectionId'> & { connectionId?: string | null }
+): string {
+  const runtimeEnvironmentId =
+    runtimeContext?.settings?.activeRuntimeEnvironmentId?.trim() ?? 'client'
+  return [
+    runtimeEnvironmentId,
+    runtimeContext?.connectionId ?? connectionId ?? 'local',
+    runtimeContext?.worktreeId ?? 'unknown-worktree',
+    absolutePath
+  ].join('\0')
+}
+
 // Why: blob URLs hold references to in-memory Blob objects; without eviction
 // the cache grows without bound and leaks memory. We evict the oldest entry
 // (Map iteration order is insertion order) and revoke its blob URL so the
@@ -97,7 +114,8 @@ function isExternalUrl(src: string): boolean {
 export function useLocalImageSrc(
   rawSrc: string | undefined,
   filePath: string,
-  connectionId?: string | null
+  connectionId?: string | null,
+  runtimeContext?: Omit<RuntimeFileOperationArgs, 'connectionId'> & { connectionId?: string | null }
 ): string | undefined {
   const [generation, setGeneration] = useState(cacheGeneration)
 
@@ -113,8 +131,11 @@ export function useLocalImageSrc(
       return rawSrc
     }
     const absolutePath = resolveImageAbsolutePath(rawSrc, filePath)
-    if (absolutePath && blobUrlCache.has(absolutePath)) {
-      return blobUrlCache.get(absolutePath)
+    if (absolutePath) {
+      const cacheKey = getLocalImageCacheKey(absolutePath, connectionId, runtimeContext)
+      if (blobUrlCache.has(cacheKey)) {
+        return blobUrlCache.get(cacheKey)
+      }
     }
     return undefined
   })
@@ -136,21 +157,21 @@ export function useLocalImageSrc(
       return
     }
 
-    if (blobUrlCache.has(absolutePath)) {
-      setDisplaySrc(blobUrlCache.get(absolutePath))
+    const cacheKey = getLocalImageCacheKey(absolutePath, connectionId, runtimeContext)
+    if (blobUrlCache.has(cacheKey)) {
+      setDisplaySrc(blobUrlCache.get(cacheKey))
       return
     }
 
     let cancelled = false
-    window.api.fs
-      .readFile({ filePath: absolutePath, connectionId: connectionId ?? undefined })
+    readImagePreview(absolutePath, connectionId, runtimeContext)
       .then((result) => {
         if (cancelled) {
           return
         }
         if (result.isBinary && result.content) {
           const url = base64ToBlobUrl(result.content, result.mimeType ?? 'image/png')
-          cacheBlobUrl(absolutePath, url)
+          cacheBlobUrl(cacheKey, url)
           setDisplaySrc(url)
         } else {
           // Why: if the file exists but is not binary (e.g. an SVG stored as
@@ -168,7 +189,7 @@ export function useLocalImageSrc(
     return () => {
       cancelled = true
     }
-  }, [rawSrc, filePath, generation, connectionId])
+  }, [rawSrc, filePath, generation, connectionId, runtimeContext])
 
   return displaySrc
 }
@@ -181,7 +202,8 @@ export function useLocalImageSrc(
 export async function loadLocalImageSrc(
   rawSrc: string,
   filePath: string,
-  connectionId?: string | null
+  connectionId?: string | null,
+  runtimeContext?: Omit<RuntimeFileOperationArgs, 'connectionId'> & { connectionId?: string | null }
 ): Promise<string | null> {
   if (
     rawSrc.startsWith('http://') ||
@@ -197,19 +219,17 @@ export async function loadLocalImageSrc(
     return null
   }
 
-  const cached = blobUrlCache.get(absolutePath)
+  const cacheKey = getLocalImageCacheKey(absolutePath, connectionId, runtimeContext)
+  const cached = blobUrlCache.get(cacheKey)
   if (cached) {
     return cached
   }
 
   try {
-    const result = await window.api.fs.readFile({
-      filePath: absolutePath,
-      connectionId: connectionId ?? undefined
-    })
+    const result = await readImagePreview(absolutePath, connectionId, runtimeContext)
     if (result.isBinary && result.content) {
       const url = base64ToBlobUrl(result.content, result.mimeType ?? 'image/png')
-      cacheBlobUrl(absolutePath, url)
+      cacheBlobUrl(cacheKey, url)
       return url
     }
     // Why: if the file is not binary (e.g. an SVG stored as text) or content
@@ -222,3 +242,23 @@ export async function loadLocalImageSrc(
 
   return null
 }
+
+function readImagePreview(
+  absolutePath: string,
+  connectionId?: string | null,
+  runtimeContext?: Omit<RuntimeFileOperationArgs, 'connectionId'> & { connectionId?: string | null }
+) {
+  if (!runtimeContext) {
+    return window.api.fs.readFile({
+      filePath: absolutePath,
+      connectionId: connectionId ?? undefined
+    })
+  }
+  return readRuntimeFilePreview(
+    {
+      ...runtimeContext,
+      connectionId: runtimeContext.connectionId ?? connectionId ?? undefined
+    },
+    absolutePath
+  )
+}
diff --git a/src/renderer/src/components/editor/useMarkdownDocuments.ts b/src/renderer/src/components/editor/useMarkdownDocuments.ts
index f0fdb092c7d..96a0c3ec682 100644
--- a/src/renderer/src/components/editor/useMarkdownDocuments.ts
+++ b/src/renderer/src/components/editor/useMarkdownDocuments.ts
@@ -3,6 +3,8 @@ import type { MarkdownDocument } from '../../../../shared/types'
 import { useAppStore } from '@/store'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
 import { getConnectionId } from '@/lib/connection-context'
+import { listRuntimeMarkdownDocuments, statRuntimePath } from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 import type { MarkdownViewMode, OpenFile } from '@/store/slices/editor'
 import { createMarkdownDocumentIndex, resolveMarkdownDocLink } from './markdown-doc-links'
 
@@ -48,10 +50,18 @@ export function useMarkdownDocuments(
     const requestId = requestRef.current + 1
     requestRef.current = requestId
     try {
-      const documents = await window.api.fs.listMarkdownDocuments({
-        rootPath: worktreePath,
-        connectionId: connectionId ?? undefined
-      })
+      const documents = await listRuntimeMarkdownDocuments(
+        {
+          settings: settingsForRuntimeOwner(
+            useAppStore.getState().settings,
+            activeFile.runtimeEnvironmentId
+          ),
+          worktreeId,
+          worktreePath,
+          connectionId: connectionId ?? undefined
+        },
+        worktreePath
+      )
       if (requestRef.current !== requestId) {
         return
       }
@@ -68,18 +78,26 @@ export function useMarkdownDocuments(
         }))
       }
     }
-  }, [connectionId, worktreeId, worktreePath])
+  }, [activeFile.runtimeEnvironmentId, connectionId, worktreeId, worktreePath])
 
   const openMarkdownDocument = useCallback(
     async (document: MarkdownDocument): Promise<void> => {
-      if (!worktreeId) {
+      if (!worktreeId || !worktreePath) {
         return
       }
       try {
-        const stats = await window.api.fs.stat({
-          filePath: document.filePath,
-          connectionId: connectionId ?? undefined
-        })
+        const stats = await statRuntimePath(
+          {
+            settings: settingsForRuntimeOwner(
+              useAppStore.getState().settings,
+              activeFile.runtimeEnvironmentId
+            ),
+            worktreeId,
+            worktreePath,
+            connectionId: connectionId ?? undefined
+          },
+          document.filePath
+        )
         if (stats.isDirectory) {
           await refreshMarkdownDocuments()
           return
@@ -94,10 +112,18 @@ export function useMarkdownDocuments(
         relativePath: document.relativePath,
         worktreeId,
         language: 'markdown',
+        runtimeEnvironmentId: activeFile.runtimeEnvironmentId,
         mode: 'edit'
       })
     },
-    [connectionId, openFile, refreshMarkdownDocuments, worktreeId]
+    [
+      activeFile.runtimeEnvironmentId,
+      connectionId,
+      openFile,
+      refreshMarkdownDocuments,
+      worktreeId,
+      worktreePath
+    ]
   )
 
   useEffect(() => {
diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
index b16d06ffaf6..a83df7ae613 100644
--- a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
@@ -15,6 +15,7 @@ import {
 } from '@/lib/orchestration-setup-state'
 import { notifyProjectNotesSelectionChanged } from '@/lib/open-project-notes-tab'
 import { requestProjectNotesTabClose } from '@/lib/project-notes-close-request'
+import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
 import { useAppStore } from '@/store'
 import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../../shared/constants'
 import type { TerminalTab } from '../../../../shared/types'
@@ -213,10 +214,11 @@ export function FloatingTerminalPanel({
         .find((candidate) => candidate.id === activeWorktreeId)
       const projectId =
         state.repos.find((candidate) => candidate.id === worktree?.repoId)?.id ?? worktree?.repoId
+      const settings = state.settings
       let label = 'Project Notes'
       if (noteId && projectId) {
         try {
-          const result = await window.api.notes.show({
+          const result = await showRuntimeProjectNote(settings, {
             projectId,
             worktreeId: activeWorktreeId,
             note: noteId
@@ -226,7 +228,7 @@ export function FloatingTerminalPanel({
           label = 'Project Notes'
         }
         if (projectId) {
-          await window.api.notes.link({
+          await linkRuntimeProjectNote(settings, {
             projectId,
             worktreeId: activeWorktreeId,
             note: noteId,
diff --git a/src/renderer/src/components/github-project/ProjectCell.tsx b/src/renderer/src/components/github-project/ProjectCell.tsx
index 4182e068d92..59ccf7ea2d2 100644
--- a/src/renderer/src/components/github-project/ProjectCell.tsx
+++ b/src/renderer/src/components/github-project/ProjectCell.tsx
@@ -9,14 +9,17 @@ import { TYPE_FIELD_DATA_TYPE } from './columns'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { Input } from '@/components/ui/input'
 import { cn } from '@/lib/utils'
-import type { GitHubAssignableUser } from '../../../../shared/types'
+import { useRepoAssigneesBySlug, useRepoLabelsBySlug } from '@/hooks/useGitHubSlugMetadata'
+import { useAppStore } from '@/store'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import type {
   GitHubIssueType,
   GitHubProjectField,
   GitHubProjectFieldMutationValue,
   GitHubProjectLabel,
   GitHubProjectRow,
-  GitHubProjectUser
+  GitHubProjectUser,
+  ListIssueTypesBySlugResult
 } from '../../../../shared/github-project-types'
 
 type Props = {
@@ -264,6 +267,7 @@ function IssueTypeCell({
   const [open, setOpen] = useState(false)
   const [options, setOptions] = useState<GitHubIssueType[]>([])
   const [loading, setLoading] = useState(false)
+  const settings = useAppStore((s) => s.settings)
   const [owner, repo] = (row.content.repository ?? '').split('/')
 
   React.useEffect(() => {
@@ -272,8 +276,17 @@ function IssueTypeCell({
     }
     let cancelled = false
     setLoading(true)
-    window.api.gh
-      .listIssueTypesBySlug({ owner, repo })
+    const target = getActiveRuntimeTarget(settings)
+    const request =
+      target.kind === 'environment'
+        ? callRuntimeRpc<ListIssueTypesBySlugResult>(
+            target,
+            'github.project.listIssueTypesBySlug',
+            { owner, repo },
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh.listIssueTypesBySlug({ owner, repo })
+    request
       .then((res) => {
         if (cancelled) {
           return
@@ -290,7 +303,7 @@ function IssueTypeCell({
     return () => {
       cancelled = true
     }
-  }, [open, owner, repo])
+  }, [open, owner, repo, settings])
 
   const trigger = (
     <span className="inline-flex items-center gap-1 text-xs">
@@ -713,8 +726,7 @@ function AssigneesCell({
 }): React.JSX.Element {
   const assignees = row.content.assignees
   const [open, setOpen] = useState(false)
-  const [options, setOptions] = useState<GitHubAssignableUser[]>([])
-  const [loading, setLoading] = useState(false)
+  const settings = useAppStore((s) => s.settings)
 
   const [owner, repo] = (row.content.repository ?? '').split('/')
 
@@ -732,37 +744,12 @@ function AssigneesCell({
     [assignees]
   )
 
-  // Why: only hit the slug-addressed user list when the popover actually
-  // opens — the assignable-users query can be expensive for large repos.
-  React.useEffect(() => {
-    if (!open || !owner || !repo) {
-      return
-    }
-    let cancelled = false
-    setLoading(true)
-    window.api.gh
-      .listAssignableUsersBySlug({
-        owner,
-        repo,
-        seedLogins: seedKey ? seedKey.split(',') : []
-      })
-      .then((res) => {
-        if (cancelled) {
-          return
-        }
-        if (res.ok) {
-          setOptions(res.users)
-        }
-      })
-      .finally(() => {
-        if (!cancelled) {
-          setLoading(false)
-        }
-      })
-    return () => {
-      cancelled = true
-    }
-  }, [open, owner, repo, seedKey])
+  const metadata = useRepoAssigneesBySlug(
+    open ? owner : null,
+    open ? repo : null,
+    seedKey ? seedKey.split(',') : [],
+    settings
+  )
 
   const labelContent =
     assignees.length === 0 ? null : assignees.map((u) => <UserChip key={u.login} user={u} />)
@@ -791,10 +778,10 @@ function AssigneesCell({
       <PopoverContent className="w-64 p-1">
         {!owner || !repo ? (
           <div className="px-2 py-1 text-xs text-muted-foreground">Row has no repo slug.</div>
-        ) : loading ? (
+        ) : metadata.loading ? (
           <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
         ) : (
-          options.map((u) => {
+          metadata.data.map((u) => {
             const isOn = assignees.some((a) => a.login === u.login)
             return (
               <button
@@ -839,38 +826,10 @@ function LabelsCell({
 }): React.JSX.Element {
   const labels = row.content.labels
   const [open, setOpen] = useState(false)
-  const [options, setOptions] = useState<string[]>([])
-  const [loading, setLoading] = useState(false)
+  const settings = useAppStore((s) => s.settings)
 
   const [owner, repo] = (row.content.repository ?? '').split('/')
-
-  // Why: only fetch the slug-addressed labels list when the popover actually
-  // opens — listing labels is cheap but still a network round-trip per row.
-  React.useEffect(() => {
-    if (!open || !owner || !repo) {
-      return
-    }
-    let cancelled = false
-    setLoading(true)
-    window.api.gh
-      .listLabelsBySlug({ owner, repo })
-      .then((res) => {
-        if (cancelled) {
-          return
-        }
-        if (res.ok) {
-          setOptions(res.labels)
-        }
-      })
-      .finally(() => {
-        if (!cancelled) {
-          setLoading(false)
-        }
-      })
-    return () => {
-      cancelled = true
-    }
-  }, [open, owner, repo])
+  const metadata = useRepoLabelsBySlug(open ? owner : null, open ? repo : null, settings)
 
   const labelContent =
     labels.length === 0 ? null : labels.map((l) => <LabelChip key={l.name} label={l} />)
@@ -893,12 +852,12 @@ function LabelsCell({
       <PopoverContent className="w-64 p-1">
         {!owner || !repo ? (
           <div className="px-2 py-1 text-xs text-muted-foreground">Row has no repo slug.</div>
-        ) : loading ? (
+        ) : metadata.loading ? (
           <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
-        ) : options.length === 0 ? (
+        ) : metadata.data.length === 0 ? (
           <div className="px-2 py-1 text-xs text-muted-foreground">No labels in this repo.</div>
         ) : (
-          options.map((name) => {
+          metadata.data.map((name) => {
             const isOn = labels.some((l) => l.name === name)
             return (
               <button
diff --git a/src/renderer/src/components/github-project/ProjectPicker.tsx b/src/renderer/src/components/github-project/ProjectPicker.tsx
index 54ea8496d75..29f2d1cf3d8 100644
--- a/src/renderer/src/components/github-project/ProjectPicker.tsx
+++ b/src/renderer/src/components/github-project/ProjectPicker.tsx
@@ -11,13 +11,17 @@ import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { cn } from '@/lib/utils'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { useAppStore } from '@/store'
 import type {
   GitHubProjectOwnerType,
   GitHubProjectSettings,
   GitHubProjectSummary,
   GitHubProjectViewError,
-  GitHubProjectViewSummary
+  GitHubProjectViewSummary,
+  ListAccessibleProjectsResult,
+  ListProjectViewsResult,
+  ResolveProjectRefResult
 } from '../../../../shared/github-project-types'
 
 export type ResolvedProjectSelection = {
@@ -44,15 +48,60 @@ let browseCache: {
   partialFailures?: { owner: string; message: string }[]
 } | null = null
 
+async function listAccessibleProjectsForRuntime(
+  settings: Parameters<typeof getActiveRuntimeTarget>[0]
+): Promise<ListAccessibleProjectsResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<ListAccessibleProjectsResult>(
+        target,
+        'github.project.listAccessible',
+        {},
+        { timeoutMs: 60_000 }
+      )
+    : window.api.gh.listAccessibleProjects()
+}
+
+async function listProjectViewsForRuntime(
+  settings: Parameters<typeof getActiveRuntimeTarget>[0],
+  args: { owner: string; ownerType: GitHubProjectOwnerType; projectNumber: number }
+): Promise<ListProjectViewsResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<ListProjectViewsResult>(target, 'github.project.listViews', args, {
+        timeoutMs: 30_000
+      })
+    : window.api.gh.listProjectViews(args)
+}
+
+async function resolveProjectRefForRuntime(
+  settings: Parameters<typeof getActiveRuntimeTarget>[0],
+  input: string
+): Promise<ResolveProjectRefResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<ResolveProjectRefResult>(
+        target,
+        'github.project.resolveRef',
+        { input },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.gh.resolveProjectRef({ input })
+}
+
 export default function ProjectPicker({ activeProject, onSelect }: Props): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
   const updateSettings = useAppStore((s) => s.updateSettings)
-  const projectSettings: GitHubProjectSettings = settings?.githubProjects ?? {
-    pinned: [],
-    recent: [],
-    lastViewByProject: {},
-    activeProject: null
-  }
+  const projectSettings: GitHubProjectSettings = useMemo(
+    () =>
+      settings?.githubProjects ?? {
+        pinned: [],
+        recent: [],
+        lastViewByProject: {},
+        activeProject: null
+      },
+    [settings?.githubProjects]
+  )
 
   const [open, setOpen] = useState(false)
   const [query, setQuery] = useState('')
@@ -86,7 +135,7 @@ export default function ProjectPicker({ activeProject, onSelect }: Props): React
     setBrowseLoading(true)
     setBrowseError(null)
     try {
-      const res = await window.api.gh.listAccessibleProjects()
+      const res = await listAccessibleProjectsForRuntime(settings)
       if (res.ok) {
         browseCache = {
           fetchedAt: Date.now(),
@@ -106,7 +155,7 @@ export default function ProjectPicker({ activeProject, onSelect }: Props): React
     } finally {
       setBrowseLoading(false)
     }
-  }, [])
+  }, [settings])
 
   useEffect(() => {
     if (open && !viewPickFor) {
@@ -199,7 +248,7 @@ export default function ProjectPicker({ activeProject, onSelect }: Props): React
       })
       setViewLoading(true)
       try {
-        const res = await window.api.gh.listProjectViews({
+        const res = await listProjectViewsForRuntime(settings, {
           owner: selection.owner,
           ownerType: selection.ownerType,
           projectNumber: selection.number
@@ -240,7 +289,7 @@ export default function ProjectPicker({ activeProject, onSelect }: Props): React
         setViewLoading(false)
       }
     },
-    [commitSelection, projectSettings.lastViewByProject]
+    [commitSelection, projectSettings.lastViewByProject, settings]
   )
 
   const handlePaste = useCallback(async () => {
@@ -252,7 +301,7 @@ export default function ProjectPicker({ activeProject, onSelect }: Props): React
     setPasteError(null)
     setPasteBusy(true)
     try {
-      const res = await window.api.gh.resolveProjectRef({ input: pasteInput.trim() })
+      const res = await resolveProjectRefForRuntime(settings, pasteInput.trim())
       if (!res.ok) {
         setPasteError(res.error.message)
         return
@@ -270,7 +319,7 @@ export default function ProjectPicker({ activeProject, onSelect }: Props): React
     } finally {
       setPasteBusy(false)
     }
-  }, [handleChooseProject, pasteInput])
+  }, [handleChooseProject, pasteInput, settings])
 
   const filteredBrowse = useMemo(() => {
     const q = query.trim().toLowerCase()
diff --git a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
index 8a07793a3af..f670072fd6d 100644
--- a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
+++ b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
@@ -29,6 +29,7 @@ import { GhAuthErrorHelp } from '@/components/github-project/GhAuthErrorHelp'
 import { launchWorkItemDirect } from '@/lib/launch-work-item-direct'
 import { useRepoSlugIndex } from '@/lib/repo-slug-index'
 import { cn } from '@/lib/utils'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { useAppStore } from '@/store'
 import { projectViewCacheKey } from '@/store/slices/github'
 import type {
@@ -38,7 +39,8 @@ import type {
   GitHubProjectRow,
   GitHubProjectTable,
   GitHubProjectViewError,
-  GitHubProjectViewSummary
+  GitHubProjectViewSummary,
+  ListProjectViewsResult
 } from '../../../../shared/github-project-types'
 import type { GitHubWorkItem } from '../../../../shared/types'
 import ProjectPicker, { type ResolvedProjectSelection } from './ProjectPicker'
@@ -47,6 +49,18 @@ import ProjectItemSlugDialog from './ProjectItemSlugDialog'
 
 type Props = Record<string, never>
 
+function listProjectViewsForRuntime(
+  settings: Parameters<typeof getActiveRuntimeTarget>[0],
+  args: { owner: string; ownerType: 'organization' | 'user'; projectNumber: number }
+): Promise<ListProjectViewsResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<ListProjectViewsResult>(target, 'github.project.listViews', args, {
+        timeoutMs: 30_000
+      })
+    : window.api.gh.listProjectViews(args)
+}
+
 export default function ProjectViewWrapper(_props: Props = {} as Props): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
   const projectViewCache = useAppStore((s) => s.projectViewCache)
@@ -59,7 +73,10 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
   const lookupSlug = useRepoSlugIndex()
 
   const activeProject = settings?.githubProjects?.activeProject ?? null
-  const lastViewByProject = settings?.githubProjects?.lastViewByProject ?? {}
+  const lastViewByProject = useMemo(
+    () => settings?.githubProjects?.lastViewByProject ?? {},
+    [settings?.githubProjects?.lastViewByProject]
+  )
 
   const [loading, setLoading] = useState(false)
   const [error, setError] = useState<{
@@ -165,12 +182,11 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
       return
     }
     let cancelled = false
-    void window.api.gh
-      .listProjectViews({
-        owner: activeProject.owner,
-        ownerType: activeProject.ownerType,
-        projectNumber: activeProject.number
-      })
+    void listProjectViewsForRuntime(settings, {
+      owner: activeProject.owner,
+      ownerType: activeProject.ownerType,
+      projectNumber: activeProject.number
+    })
       .then((res) => {
         if (cancelled) {
           return
@@ -192,7 +208,7 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
     return () => {
       cancelled = true
     }
-  }, [activeProject, viewListByProject])
+  }, [activeProject, viewListByProject, settings])
 
   const handleSwitchView = useCallback(
     async (viewId: string) => {
@@ -232,7 +248,7 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
         viewId
       })
     },
-    [activeProject, doFetch, lastViewByProject, settings]
+    [activeProject, doFetch, lastViewByProject]
   )
 
   const currentProjectViewKey = useMemo(() => {
diff --git a/src/renderer/src/components/github-project/slug-dialog/AssigneesEditor.tsx b/src/renderer/src/components/github-project/slug-dialog/AssigneesEditor.tsx
index 6ccc3a2e05b..5378801dba5 100644
--- a/src/renderer/src/components/github-project/slug-dialog/AssigneesEditor.tsx
+++ b/src/renderer/src/components/github-project/slug-dialog/AssigneesEditor.tsx
@@ -1,7 +1,8 @@
-import React, { useEffect, useMemo, useState } from 'react'
+import React, { useMemo, useState } from 'react'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { cn } from '@/lib/utils'
-import type { GitHubAssignableUser } from '../../../../../shared/types'
+import { useRepoAssigneesBySlug } from '@/hooks/useGitHubSlugMetadata'
+import { useAppStore } from '@/store'
 
 export function AssigneesEditor({
   owner,
@@ -17,45 +18,17 @@ export function AssigneesEditor({
   onChange: (add: string[], remove: string[]) => void | Promise<void>
 }): React.JSX.Element {
   const [open, setOpen] = useState(false)
-  const [users, setUsers] = useState<GitHubAssignableUser[]>([])
-  const [loading, setLoading] = useState(false)
+  const settings = useAppStore((s) => s.settings)
   // Why: stabilize the assignee seed identity. `selected` is a fresh array on
   // every parent render — depending on it directly would refire the IPC for
   // every unrelated re-render while the popover is open.
   const seedKey = useMemo(() => selected.slice().sort().join(','), [selected])
-  useEffect(() => {
-    if (!open) {
-      return
-    }
-    // Why: guard against late responses overwriting newer state when
-    // owner/repo/seedKey change (or the popover toggles) before the IPC
-    // resolves. Mirrors the requestIdRef pattern used for the details fetch.
-    let cancelled = false
-    setLoading(true)
-    window.api.gh
-      .listAssignableUsersBySlug({
-        owner,
-        repo,
-        seedLogins: seedKey ? seedKey.split(',') : []
-      })
-      .then((res) => {
-        if (cancelled) {
-          return
-        }
-        if (res.ok) {
-          setUsers(res.users)
-        }
-      })
-      .finally(() => {
-        if (cancelled) {
-          return
-        }
-        setLoading(false)
-      })
-    return () => {
-      cancelled = true
-    }
-  }, [open, owner, repo, seedKey])
+  const metadata = useRepoAssigneesBySlug(
+    open ? owner : null,
+    open ? repo : null,
+    seedKey ? seedKey.split(',') : [],
+    settings
+  )
   return (
     <Popover open={open} onOpenChange={(o) => !disabled && setOpen(o)}>
       <PopoverTrigger asChild>
@@ -68,10 +41,10 @@ export function AssigneesEditor({
         </button>
       </PopoverTrigger>
       <PopoverContent className="w-64 p-1">
-        {loading ? (
+        {metadata.loading ? (
           <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
         ) : (
-          users.map((u) => {
+          metadata.data.map((u) => {
             const isOn = selected.includes(u.login)
             return (
               <button
diff --git a/src/renderer/src/components/github-project/slug-dialog/Comments.tsx b/src/renderer/src/components/github-project/slug-dialog/Comments.tsx
index 5f914224218..76c1d5d5ab6 100644
--- a/src/renderer/src/components/github-project/slug-dialog/Comments.tsx
+++ b/src/renderer/src/components/github-project/slug-dialog/Comments.tsx
@@ -3,7 +3,18 @@ import { Send } from 'lucide-react'
 import { toast } from 'sonner'
 import { Button } from '@/components/ui/button'
 import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import { useAppStore } from '@/store'
 import type { PRComment } from '../../../../../shared/types'
+import type {
+  GitHubProjectCommentMutationResult,
+  GitHubProjectMutationResult
+} from '../../../../../shared/github-project-types'
+
+function getRuntimeTarget() {
+  const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+  return target.kind === 'environment' ? target : null
+}
 
 export function CommentsList({
   owner,
@@ -28,11 +39,20 @@ export function CommentsList({
             repo={repo}
             comment={c}
             onDelete={async () => {
-              const res = await window.api.gh.deleteIssueCommentBySlug({
+              const target = getRuntimeTarget()
+              const args = {
                 owner,
                 repo,
                 commentId: c.id
-              })
+              }
+              const res = target
+                ? await callRuntimeRpc<GitHubProjectMutationResult>(
+                    target,
+                    'github.project.deleteIssueCommentBySlug',
+                    args,
+                    { timeoutMs: 30_000 }
+                  )
+                : await window.api.gh.deleteIssueCommentBySlug(args)
               if (!res.ok) {
                 toast.error(res.error.message)
                 return
@@ -40,12 +60,21 @@ export function CommentsList({
               onChange(comments.filter((x) => x.id !== c.id))
             }}
             onEdit={async (next) => {
-              const res = await window.api.gh.updateIssueCommentBySlug({
+              const target = getRuntimeTarget()
+              const args = {
                 owner,
                 repo,
                 commentId: c.id,
                 body: next
-              })
+              }
+              const res = target
+                ? await callRuntimeRpc<GitHubProjectMutationResult>(
+                    target,
+                    'github.project.updateIssueCommentBySlug',
+                    args,
+                    { timeoutMs: 30_000 }
+                  )
+                : await window.api.gh.updateIssueCommentBySlug(args)
               if (!res.ok) {
                 toast.error(res.error.message)
                 return
@@ -154,7 +183,16 @@ export function NewCommentForm({
             }
             setSubmitting(true)
             try {
-              const res = await window.api.gh.addIssueCommentBySlug({ owner, repo, number, body })
+              const target = getRuntimeTarget()
+              const args = { owner, repo, number, body }
+              const res = target
+                ? await callRuntimeRpc<GitHubProjectCommentMutationResult>(
+                    target,
+                    'github.project.addIssueCommentBySlug',
+                    args,
+                    { timeoutMs: 30_000 }
+                  )
+                : await window.api.gh.addIssueCommentBySlug(args)
               if (!res.ok) {
                 toast.error(res.error.message)
                 return
diff --git a/src/renderer/src/components/github-project/slug-dialog/LabelsEditor.tsx b/src/renderer/src/components/github-project/slug-dialog/LabelsEditor.tsx
index 6ac9eaed9a6..9f8962ad032 100644
--- a/src/renderer/src/components/github-project/slug-dialog/LabelsEditor.tsx
+++ b/src/renderer/src/components/github-project/slug-dialog/LabelsEditor.tsx
@@ -1,6 +1,8 @@
-import React, { useEffect, useState } from 'react'
+import React, { useState } from 'react'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { cn } from '@/lib/utils'
+import { useRepoLabelsBySlug } from '@/hooks/useGitHubSlugMetadata'
+import { useAppStore } from '@/store'
 
 export function LabelsEditor({
   owner,
@@ -16,37 +18,8 @@ export function LabelsEditor({
   onChange: (add: string[], remove: string[]) => void | Promise<void>
 }): React.JSX.Element {
   const [open, setOpen] = useState(false)
-  const [options, setOptions] = useState<string[]>([])
-  const [loading, setLoading] = useState(false)
-  useEffect(() => {
-    if (!open) {
-      return
-    }
-    // Why: guard against late responses overwriting newer state when the
-    // popover toggles owner/repo (or closes/reopens) while the IPC is still
-    // in flight. Mirrors the requestIdRef pattern used for the details fetch.
-    let cancelled = false
-    setLoading(true)
-    window.api.gh
-      .listLabelsBySlug({ owner, repo })
-      .then((res) => {
-        if (cancelled) {
-          return
-        }
-        if (res.ok) {
-          setOptions(res.labels)
-        }
-      })
-      .finally(() => {
-        if (cancelled) {
-          return
-        }
-        setLoading(false)
-      })
-    return () => {
-      cancelled = true
-    }
-  }, [open, owner, repo])
+  const settings = useAppStore((s) => s.settings)
+  const metadata = useRepoLabelsBySlug(open ? owner : null, open ? repo : null, settings)
   return (
     <Popover open={open} onOpenChange={(o) => !disabled && setOpen(o)}>
       <PopoverTrigger asChild>
@@ -59,10 +32,10 @@ export function LabelsEditor({
         </button>
       </PopoverTrigger>
       <PopoverContent className="w-64 p-1">
-        {loading ? (
+        {metadata.loading ? (
           <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
         ) : (
-          options.map((name) => {
+          metadata.data.map((name) => {
             const isOn = selected.includes(name)
             return (
               <button
diff --git a/src/renderer/src/components/github/GitHubRateLimitPill.tsx b/src/renderer/src/components/github/GitHubRateLimitPill.tsx
index d6c5481238a..714ad1510ba 100644
--- a/src/renderer/src/components/github/GitHubRateLimitPill.tsx
+++ b/src/renderer/src/components/github/GitHubRateLimitPill.tsx
@@ -22,6 +22,8 @@ import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { Gauge } from 'lucide-react'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { cn } from '@/lib/utils'
+import { useAppStore } from '@/store'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import type { GetRateLimitResult, GitHubRateLimitSnapshot } from '../../../../shared/types'
 
 // Why: 60s client-side cadence. Aligns with typical user action rhythm
@@ -100,34 +102,43 @@ function tightestBucket(snapshot: GitHubRateLimitSnapshot): BucketMeta {
 export default function GitHubRateLimitPill(): React.JSX.Element | null {
   const [snapshot, setSnapshot] = useState<GitHubRateLimitSnapshot | null>(null)
   const [hasError, setHasError] = useState(false)
+  const settings = useAppStore((s) => s.settings)
   // Why: StrictMode double-invokes effects in dev. Without this guard the
   // first mount fires two rate_limit IPCs back-to-back — benign (exempt
   // endpoint, cached) but noisy in logs. Tracks the latest in-flight token
   // so stale responses from an unmounted instance are dropped.
   const latestToken = useRef(0)
 
-  const fetchSnapshot = useCallback(async (force: boolean): Promise<void> => {
-    const token = ++latestToken.current
-    try {
-      const res = (await window.api.gh.rateLimit(force ? { force: true } : undefined)) as
-        | GetRateLimitResult
-        | undefined
-      if (token !== latestToken.current) {
-        return
-      }
-      if (res?.ok) {
-        setSnapshot(res.snapshot)
-        setHasError(false)
-      } else {
+  const fetchSnapshot = useCallback(
+    async (force: boolean): Promise<void> => {
+      const token = ++latestToken.current
+      try {
+        const target = getActiveRuntimeTarget(settings)
+        const params = force ? { force: true } : undefined
+        const res =
+          target.kind === 'environment'
+            ? await callRuntimeRpc<GetRateLimitResult>(target, 'github.rateLimit', params ?? {}, {
+                timeoutMs: 30_000
+              })
+            : ((await window.api.gh.rateLimit(params)) as GetRateLimitResult | undefined)
+        if (token !== latestToken.current) {
+          return
+        }
+        if (res?.ok) {
+          setSnapshot(res.snapshot)
+          setHasError(false)
+        } else {
+          setHasError(true)
+        }
+      } catch {
+        if (token !== latestToken.current) {
+          return
+        }
         setHasError(true)
       }
-    } catch {
-      if (token !== latestToken.current) {
-        return
-      }
-      setHasError(true)
-    }
-  }, [])
+    },
+    [settings]
+  )
 
   useEffect(() => {
     const fetchIfVisible = (): void => {
diff --git a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
index c6625cfbfb4..acc44e650c8 100644
--- a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
+++ b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
@@ -41,7 +41,13 @@ import {
 import { parseGitLabIssueOrMRLink } from '@/lib/gitlab-links'
 import { cn } from '@/lib/utils'
 import { LinearIcon } from '@/components/icons/LinearIcon'
-import type { GitHubWorkItem, GitLabWorkItem, LinearIssue } from '../../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import type {
+  GitHubWorkItem,
+  GitLabWorkItem,
+  GlobalSettings,
+  LinearIssue
+} from '../../../../shared/types'
 
 type SmartNameMode = 'smart' | 'github' | 'gitlab' | 'branches' | 'linear' | 'text'
 
@@ -57,6 +63,7 @@ const MR_STATE_FILTERS: { id: MrStateFilter; label: string }[] = [
 ]
 
 type RepoOption = ReturnType<typeof useAppStore.getState>['repos'][number]
+type GitHubWorkItemWithoutRepo = Omit<GitHubWorkItem, 'repoId'>
 
 type SmartWorkspaceNameFieldProps = {
   repos: RepoOption[]
@@ -159,6 +166,7 @@ export default function SmartWorkspaceNameField({
       searchLinearIssues: s.searchLinearIssues
     }))
   )
+  const settings = useAppStore((s) => s.settings)
 
   const selectedRepo = useMemo(
     () => repos.find((repo) => repo.id === repoId) ?? null,
@@ -237,20 +245,20 @@ export default function SmartWorkspaceNameField({
     const directLink = parsedGhLink
     if (directLink !== null && handledCrossRepoUrlRef.current !== debouncedQuery.trim()) {
       setGithubLoading(true)
-      void getRepoSlugCached(selectedRepo, repoSlugCacheRef.current)
+      void getRepoSlugCached(selectedRepo, repoSlugCacheRef.current, settings)
         .then(async (selectedSlug) => {
           if (stale) {
             return
           }
           if (!selectedSlug || sameSlug(selectedSlug, directLink.slug)) {
             handledCrossRepoUrlRef.current = debouncedQuery.trim()
-            const item = await window.api.gh.workItemByOwnerRepo({
-              repoPath: selectedRepo.path,
-              owner: directLink.slug.owner,
-              repo: directLink.slug.repo,
-              number: directLink.number,
-              type: directLink.type
-            })
+            const item = await getWorkItemByOwnerRepo(
+              selectedRepo,
+              directLink.slug,
+              directLink.number,
+              directLink.type,
+              settings
+            )
             if (!stale) {
               setGithubItems(item ? [{ ...item, repoId: selectedRepo.id } as GitHubWorkItem] : [])
             }
@@ -259,7 +267,8 @@ export default function SmartWorkspaceNameField({
           const matchingRepo = await findMatchingRepoForSlug(
             repos,
             directLink.slug,
-            repoSlugCacheRef.current
+            repoSlugCacheRef.current,
+            settings
           )
           if (!stale) {
             setGithubItems([])
@@ -280,14 +289,14 @@ export default function SmartWorkspaceNameField({
       setGithubLoading(true)
       const request =
         directLink !== null
-          ? window.api.gh.workItemByOwnerRepo({
-              repoPath: selectedRepo.path,
-              owner: directLink.slug.owner,
-              repo: directLink.slug.repo,
-              number: directLink.number,
-              type: directLink.type
-            })
-          : window.api.gh.workItem({ repoPath: selectedRepo.path, number: directNumber })
+          ? getWorkItemByOwnerRepo(
+              selectedRepo,
+              directLink.slug,
+              directLink.number,
+              directLink.type,
+              settings
+            )
+          : getWorkItem(selectedRepo, directNumber, undefined, settings)
       void request
         .then((item) => {
           if (!stale) {
@@ -345,6 +354,7 @@ export default function SmartWorkspaceNameField({
     parsedGhLink,
     repos,
     selectedRepo,
+    settings,
     shouldQueryGithub
   ])
 
@@ -705,13 +715,13 @@ export default function SmartWorkspaceNameField({
       handledCrossRepoUrlRef.current = debouncedQuery.trim()
       setGithubLoading(true)
       try {
-        const item = await window.api.gh.workItemByOwnerRepo({
-          repoPath: targetRepo.path,
-          owner: crossRepoPrompt.link.slug.owner,
-          repo: crossRepoPrompt.link.slug.repo,
-          number: crossRepoPrompt.link.number,
-          type: crossRepoPrompt.link.type
-        })
+        const item = await getWorkItemByOwnerRepo(
+          targetRepo,
+          crossRepoPrompt.link.slug,
+          crossRepoPrompt.link.number,
+          crossRepoPrompt.link.type,
+          settings
+        )
         if (!item) {
           return
         }
@@ -723,7 +733,7 @@ export default function SmartWorkspaceNameField({
         setGithubLoading(false)
       }
     },
-    [crossRepoPrompt, debouncedQuery, onGitHubItemSelect, onRepoChange]
+    [crossRepoPrompt, debouncedQuery, onGitHubItemSelect, onRepoChange, settings]
   )
 
   const handleUseCurrentRepo = useCallback(async (): Promise<void> => {
@@ -743,11 +753,11 @@ export default function SmartWorkspaceNameField({
       return
     }
     repoSlugCacheRef.current.delete(added.id)
-    const slug = await getRepoSlugCached(added, repoSlugCacheRef.current)
+    const slug = await getRepoSlugCached(added, repoSlugCacheRef.current, settings)
     if (slug && sameSlug(slug, crossRepoPrompt.link.slug)) {
       await acceptGitHubLink(added)
     }
-  }, [acceptGitHubLink, addRepo, crossRepoPrompt])
+  }, [acceptGitHubLink, addRepo, crossRepoPrompt, settings])
 
   const dismissCrossRepoPrompt = useCallback((): void => {
     handledCrossRepoUrlRef.current = debouncedQuery.trim()
@@ -1165,23 +1175,41 @@ function sameSlug(left: RepoSlug, right: RepoSlug): boolean {
   )
 }
 
+function runtimeSlugScope(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): string {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment' ? `runtime:${target.environmentId}` : 'local'
+}
+
 async function getRepoSlugCached(
   repo: RepoOption,
-  cache: Map<string, RepoSlug | null>
+  cache: Map<string, RepoSlug | null>,
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
 ): Promise<RepoSlug | null> {
-  if (cache.has(repo.id)) {
-    return cache.get(repo.id) ?? null
+  const cacheKey = `${runtimeSlugScope(settings)}:${repo.id}`
+  if (cache.has(cacheKey)) {
+    return cache.get(cacheKey) ?? null
   }
   if (repo.connectionId) {
-    cache.set(repo.id, null)
+    cache.set(cacheKey, null)
     return null
   }
   try {
-    const slug = await window.api.gh.repoSlug({ repoPath: repo.path })
-    cache.set(repo.id, slug)
+    const target = getActiveRuntimeTarget(settings)
+    const slug =
+      target.kind === 'environment'
+        ? await callRuntimeRpc<RepoSlug | null>(
+            target,
+            'github.repoSlug',
+            { repo: repo.id },
+            { timeoutMs: 30_000 }
+          )
+        : await window.api.gh.repoSlug({ repoPath: repo.path })
+    cache.set(cacheKey, slug)
     return slug
   } catch {
-    cache.set(repo.id, null)
+    cache.set(cacheKey, null)
     return null
   }
 }
@@ -1189,13 +1217,63 @@ async function getRepoSlugCached(
 async function findMatchingRepoForSlug(
   repos: RepoOption[],
   slug: RepoSlug,
-  cache: Map<string, RepoSlug | null>
+  cache: Map<string, RepoSlug | null>,
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
 ): Promise<RepoOption | null> {
   for (const repo of repos) {
-    const candidate = await getRepoSlugCached(repo, cache)
+    const candidate = await getRepoSlugCached(repo, cache, settings)
     if (candidate && sameSlug(candidate, slug)) {
       return repo
     }
   }
   return null
 }
+
+function getWorkItem(
+  repo: RepoOption,
+  number: number,
+  type: 'issue' | 'pr' | undefined,
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): Promise<GitHubWorkItemWithoutRepo | null> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind === 'environment') {
+    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
+      target,
+      'github.workItem',
+      { repo: repo.id, number, ...(type ? { type } : {}) },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.workItem({ repoPath: repo.path, number, ...(type ? { type } : {}) })
+}
+
+function getWorkItemByOwnerRepo(
+  repo: RepoOption,
+  slug: RepoSlug,
+  number: number,
+  type: 'issue' | 'pr',
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): Promise<GitHubWorkItemWithoutRepo | null> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind === 'environment') {
+    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
+      target,
+      'github.workItemByOwnerRepo',
+      {
+        repo: repo.id,
+        owner: slug.owner,
+        ownerRepo: slug.repo,
+        number,
+        type
+      },
+      { timeoutMs: 30_000 }
+    )
+  }
+  return window.api.gh.workItemByOwnerRepo({
+    repoPath: repo.path,
+    owner: slug.owner,
+    repo: slug.repo,
+    number,
+    type
+  })
+}
diff --git a/src/renderer/src/components/notes/ProjectNotesTabContent.tsx b/src/renderer/src/components/notes/ProjectNotesTabContent.tsx
index 4f511405a88..99a81458b1f 100644
--- a/src/renderer/src/components/notes/ProjectNotesTabContent.tsx
+++ b/src/renderer/src/components/notes/ProjectNotesTabContent.tsx
@@ -31,6 +31,14 @@ import {
   getProjectNotesEntityId,
   notifyProjectNotesSelectionChanged
 } from '@/lib/open-project-notes-tab'
+import {
+  createRuntimeProjectNote,
+  listRuntimeProjectNotes,
+  linkRuntimeProjectNote,
+  resolveRuntimeNotesPanelState,
+  saveRuntimeProjectNote,
+  showRuntimeProjectNote
+} from '@/runtime/runtime-notes-client'
 import {
   ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT,
   type ProjectNotesCloseRequestDetail
@@ -78,6 +86,7 @@ export default function ProjectNotesTabContent({
   const worktree = useWorktreeById(worktreeId)
   const repo = useRepoById(worktree?.repoId ?? null)
   const projectId = repo?.id ?? worktree?.repoId ?? null
+  const settings = useAppStore((s) => s.settings)
 
   const [panelState, setPanelState] = useState<NotesPanelOpenState>({ state: 'noProject' })
   const [notes, setNotes] = useState<NoteSummary[]>([])
@@ -101,15 +110,19 @@ export default function ProjectNotesTabContent({
       setNotes([])
       return
     }
-    const result = await window.api.notes.list({ projectId, worktreeId, limit: 100 })
+    const result = await listRuntimeProjectNotes(settings, { projectId, worktreeId, limit: 100 })
     setNotes(result.notes)
-  }, [projectId, worktreeId])
+  }, [projectId, settings, worktreeId])
 
   const loadPanelState = useCallback(async (): Promise<void> => {
     try {
       setError(null)
       if (selectedNoteId && projectId) {
-        const result = await window.api.notes.show({ projectId, worktreeId, note: selectedNoteId })
+        const result = await showRuntimeProjectNote(settings, {
+          projectId,
+          worktreeId,
+          note: selectedNoteId
+        })
         setPanelState({ state: 'active', projectId, worktreeId, note: result.note })
         setDraft({
           id: result.note.id,
@@ -134,7 +147,7 @@ export default function ProjectNotesTabContent({
         await refreshNotes()
         return
       }
-      const next = await window.api.notes.panelState({ projectId, worktreeId })
+      const next = await resolveRuntimeNotesPanelState(settings, { projectId, worktreeId })
       setPanelState(next)
       if (next.state === 'active') {
         setDraft({
@@ -164,7 +177,7 @@ export default function ProjectNotesTabContent({
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
     }
-  }, [forceNew, projectId, refreshNotes, selectedNoteId, tabId, worktreeId])
+  }, [forceNew, projectId, refreshNotes, selectedNoteId, settings, tabId, worktreeId])
 
   useEffect(() => {
     void loadPanelState()
@@ -213,8 +226,13 @@ export default function ProjectNotesTabContent({
       if (!projectId) {
         return
       }
-      const result = await window.api.notes.show({ projectId, worktreeId, note: noteId })
-      await window.api.notes.link({ projectId, worktreeId, note: noteId, kind: 'active' })
+      const result = await showRuntimeProjectNote(settings, { projectId, worktreeId, note: noteId })
+      await linkRuntimeProjectNote(settings, {
+        projectId,
+        worktreeId,
+        note: noteId,
+        kind: 'active'
+      })
       setSelectedNoteId(noteId)
       setDraft({
         id: result.note.id,
@@ -231,7 +249,7 @@ export default function ProjectNotesTabContent({
       setDirty(false)
       await refreshNotes()
     },
-    [projectId, refreshNotes, tabId, worktreeId]
+    [projectId, refreshNotes, settings, tabId, worktreeId]
   )
 
   const saveDraft = useCallback(
@@ -251,7 +269,7 @@ export default function ProjectNotesTabContent({
       }
       setSaving(true)
       try {
-        const result = await window.api.notes.save({
+        const result = await saveRuntimeProjectNote(settings, {
           projectId,
           worktreeId,
           note: draft.id,
@@ -284,7 +302,7 @@ export default function ProjectNotesTabContent({
         setSaving(false)
       }
     },
-    [canSave, draft, projectId, refreshNotes, tabId, worktreeId]
+    [canSave, draft, projectId, refreshNotes, settings, tabId, worktreeId]
   )
 
   useEffect(() => {
@@ -350,7 +368,7 @@ export default function ProjectNotesTabContent({
     }
     setSaving(true)
     try {
-      const result = await window.api.notes.create({
+      const result = await createRuntimeProjectNote(settings, {
         projectId,
         worktreeId,
         title,
@@ -385,7 +403,7 @@ export default function ProjectNotesTabContent({
     } finally {
       setSaving(false)
     }
-  }, [draft.bodyMarkdown, projectId, refreshNotes, saveAsTitle, tabId, worktreeId])
+  }, [draft.bodyMarkdown, projectId, refreshNotes, saveAsTitle, settings, tabId, worktreeId])
 
   const handleClosePromptSave = useCallback(async (): Promise<void> => {
     setClosePromptOpen(false)
diff --git a/src/renderer/src/components/onboarding/OnboardingFlow.tsx b/src/renderer/src/components/onboarding/OnboardingFlow.tsx
index 755afab67ca..dd23fa1d162 100644
--- a/src/renderer/src/components/onboarding/OnboardingFlow.tsx
+++ b/src/renderer/src/components/onboarding/OnboardingFlow.tsx
@@ -173,8 +173,14 @@ export default function OnboardingFlow({
               cloneUrl={flow.cloneUrl}
               onCloneUrlChange={flow.setCloneUrl}
               onOpenFolder={() => void flow.openFolder()}
+              onOpenServerFolder={(kind) => void flow.openFolder(kind)}
               onClone={() => void flow.clone()}
+              serverPath={flow.serverPath}
+              onServerPathChange={flow.setServerPath}
+              cloneDestination={flow.cloneDestination}
+              onCloneDestinationChange={flow.setCloneDestination}
               workspaceDir={flow.settings?.workspaceDir ?? ''}
+              runtimeActive={Boolean(flow.settings?.activeRuntimeEnvironmentId?.trim())}
               busyLabel={flow.busyLabel}
               error={flow.error}
             />
diff --git a/src/renderer/src/components/onboarding/RepoStep.tsx b/src/renderer/src/components/onboarding/RepoStep.tsx
index ddaada2bf07..36f5c86ebf5 100644
--- a/src/renderer/src/components/onboarding/RepoStep.tsx
+++ b/src/renderer/src/components/onboarding/RepoStep.tsx
@@ -4,8 +4,14 @@ type RepoStepProps = {
   cloneUrl: string
   onCloneUrlChange: (value: string) => void
   onOpenFolder: () => void
+  onOpenServerFolder: (kind: 'git' | 'folder') => void
   onClone: () => void
+  serverPath: string
+  onServerPathChange: (value: string) => void
+  cloneDestination: string
+  onCloneDestinationChange: (value: string) => void
   workspaceDir: string
+  runtimeActive: boolean
   busyLabel: string | null
   error: string | null
 }
@@ -14,36 +20,89 @@ export function RepoStep({
   cloneUrl,
   onCloneUrlChange,
   onOpenFolder,
+  onOpenServerFolder,
   onClone,
+  serverPath,
+  onServerPathChange,
+  cloneDestination,
+  onCloneDestinationChange,
   workspaceDir,
+  runtimeActive,
   busyLabel,
   error
 }: RepoStepProps) {
   const disabled = Boolean(busyLabel)
   return (
     <div className="space-y-3">
-      <button
-        type="button"
-        className="group flex w-full items-center gap-4 rounded-xl border border-border bg-muted/30 p-5 text-left transition hover:border-foreground/40 hover:bg-muted/60 disabled:opacity-60"
-        disabled={disabled}
-        onClick={onOpenFolder}
-      >
-        <div className="grid size-11 shrink-0 place-items-center rounded-lg bg-muted text-foreground">
-          <FolderOpen className="size-5" />
-        </div>
-        <div className="min-w-0 flex-1">
-          <div className="text-base font-semibold text-foreground">Open a folder</div>
-          <div className="mt-0.5 text-[13px] text-muted-foreground">
-            Choose any local directory, git repo or not.
+      {runtimeActive ? (
+        <form
+          className="rounded-lg border border-border bg-muted/30 p-5"
+          onSubmit={(event) => {
+            event.preventDefault()
+            onOpenServerFolder('git')
+          }}
+        >
+          <div className="flex items-center gap-4">
+            <div className="grid size-11 shrink-0 place-items-center rounded-lg bg-muted text-foreground">
+              <FolderOpen className="size-5" />
+            </div>
+            <div className="min-w-0 flex-1">
+              <div className="text-base font-semibold text-foreground">Open a server project</div>
+              <div className="mt-0.5 text-[13px] text-muted-foreground">
+                Enter a path that exists on the runtime server.
+              </div>
+            </div>
           </div>
-        </div>
-        <span className="shrink-0 rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground transition group-hover:border-foreground/40">
-          Browse…
-        </span>
-      </button>
+          <div className="mt-4 flex flex-col gap-2 sm:flex-row">
+            <input
+              className="min-w-0 flex-1 rounded-lg border border-border bg-background px-4 py-3 font-mono text-sm text-foreground outline-none transition focus:border-foreground/50 focus:ring-2 focus:ring-foreground/15"
+              placeholder="/home/user/project"
+              value={serverPath}
+              disabled={disabled}
+              spellCheck={false}
+              onChange={(event) => onServerPathChange(event.target.value)}
+            />
+            <button
+              type="submit"
+              className="shrink-0 rounded-lg bg-primary px-4 py-3 text-sm font-medium text-primary-foreground hover:bg-primary/90 disabled:opacity-40"
+              disabled={!serverPath.trim() || disabled}
+            >
+              Add Git Project
+            </button>
+            <button
+              type="button"
+              className="shrink-0 rounded-lg border border-border bg-background px-4 py-3 text-sm font-medium text-foreground hover:bg-muted/60 disabled:opacity-40"
+              disabled={!serverPath.trim() || disabled}
+              onClick={() => onOpenServerFolder('folder')}
+            >
+              Open as Folder
+            </button>
+          </div>
+        </form>
+      ) : (
+        <button
+          type="button"
+          className="group flex w-full items-center gap-4 rounded-xl border border-border bg-muted/30 p-5 text-left transition hover:border-foreground/40 hover:bg-muted/60 disabled:opacity-60"
+          disabled={disabled}
+          onClick={onOpenFolder}
+        >
+          <div className="grid size-11 shrink-0 place-items-center rounded-lg bg-muted text-foreground">
+            <FolderOpen className="size-5" />
+          </div>
+          <div className="min-w-0 flex-1">
+            <div className="text-base font-semibold text-foreground">Open a folder</div>
+            <div className="mt-0.5 text-[13px] text-muted-foreground">
+              Choose any local directory, git repo or not.
+            </div>
+          </div>
+          <span className="shrink-0 rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground transition group-hover:border-foreground/40">
+            Browse...
+          </span>
+        </button>
+      )}
 
       <form
-        className="rounded-xl border border-border bg-muted/30 p-5"
+        className="rounded-lg border border-border bg-muted/30 p-5"
         onSubmit={(e) => {
           e.preventDefault()
           onClone()
@@ -71,21 +130,38 @@ export function RepoStep({
           <button
             type="submit"
             className="shrink-0 rounded-lg bg-primary px-5 py-3 text-sm font-medium text-primary-foreground hover:bg-primary/90 disabled:opacity-40"
-            disabled={!cloneUrl.trim() || disabled}
+            disabled={!cloneUrl.trim() || (runtimeActive && !cloneDestination.trim()) || disabled}
           >
             Clone
           </button>
         </div>
+        {runtimeActive && (
+          <div className="mt-2 space-y-1">
+            <label className="text-[11px] font-medium text-muted-foreground">
+              Clone into server path
+            </label>
+            <input
+              className="w-full rounded-lg border border-border bg-background px-4 py-3 font-mono text-sm text-foreground outline-none transition focus:border-foreground/50 focus:ring-2 focus:ring-foreground/15"
+              placeholder="/home/user"
+              value={cloneDestination}
+              disabled={disabled}
+              spellCheck={false}
+              onChange={(event) => onCloneDestinationChange(event.target.value)}
+            />
+          </div>
+        )}
       </form>
 
       <div className="flex flex-wrap items-center justify-between gap-3 px-1 pt-1 text-xs text-muted-foreground">
         <div className="flex min-w-0 items-center gap-2">
           <span>Workspace</span>
-          <span className="truncate font-mono text-foreground">{workspaceDir}</span>
+          <span className="truncate font-mono text-foreground">
+            {runtimeActive ? 'Runtime server' : workspaceDir}
+          </span>
         </div>
         <div className="flex items-center gap-1.5">
           <Server className="size-3.5" />
-          <span>SSH? Set hosts up in Settings</span>
+          <span>{runtimeActive ? 'Server paths only' : 'SSH? Set hosts up in Settings'}</span>
         </div>
       </div>
 
diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow.ts b/src/renderer/src/components/onboarding/use-onboarding-flow.ts
index df477c1eb3a..dc0c0bbd405 100644
--- a/src/renderer/src/components/onboarding/use-onboarding-flow.ts
+++ b/src/renderer/src/components/onboarding/use-onboarding-flow.ts
@@ -8,7 +8,7 @@ import { applyDocumentTheme } from '@/lib/document-theme'
 import { track } from '@/lib/telemetry'
 import { buildAgentPickedPayload } from './agent-picked-payload'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
-import type { GlobalSettings, OnboardingState, TuiAgent } from '../../../../shared/types'
+import type { GlobalSettings, OnboardingState, Repo, TuiAgent } from '../../../../shared/types'
 import type { NotificationDraft } from './NotificationStep'
 import {
   DEFAULT_ONBOARDING_FEATURE_SETUP_SELECTION,
@@ -19,6 +19,7 @@ import {
 } from './onboarding-feature-setup'
 import { STEPS, type StepNumber } from './use-onboarding-flow-types'
 import { persistStep, useCloseWith, usePersistCurrentStep } from './use-onboarding-flow-persistence'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 export { STEPS } from './use-onboarding-flow-types'
 export type { StepId, StepNumber } from './use-onboarding-flow-types'
@@ -38,6 +39,7 @@ export function useOnboardingFlow(
   const pathFailureReason = useAppStore((s) => s.pathFailureReason)
   const fetchRepos = useAppStore((s) => s.fetchRepos)
   const fetchWorktrees = useAppStore((s) => s.fetchWorktrees)
+  const addRepoPath = useAppStore((s) => s.addRepoPath)
   const openModal = useAppStore((s) => s.openModal)
 
   const initialStep = Math.min(Math.max(onboarding.lastCompletedStep, 0), STEPS.length - 1)
@@ -69,6 +71,8 @@ export function useOnboardingFlow(
   const [featureSetupTerminalSelection, setFeatureSetupTerminalSelection] =
     useState<OnboardingFeatureSetupSelection | null>(null)
   const [cloneUrl, setCloneUrl] = useState('')
+  const [serverPath, setServerPath] = useState('')
+  const [cloneDestination, setCloneDestination] = useState('')
   const [busyLabel, setBusyLabel] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
 
@@ -394,35 +398,62 @@ export function useOnboardingFlow(
     ]
   )
 
-  const openFolder = useCallback(async () => {
-    // Why: re-entry guard — rapid Cmd+Enter must not launch duplicate pickers.
-    if (busyLabel !== null) {
-      return
-    }
-    setError(null)
-    track('onboarding_step4_path_clicked', { path: 'open_folder' })
-    const path = await window.api.repos.pickFolder()
-    if (!path) {
-      track('onboarding_step4_path_failed', { path: 'open_folder', reason: 'cancelled' })
-      return
-    }
-    setBusyLabel('Opening project…')
-    try {
-      let result = await window.api.repos.add({ path })
-      if ('error' in result && result.error.includes('Not a valid git repository')) {
-        result = await window.api.repos.add({ path, kind: 'folder' })
+  const openFolder = useCallback(
+    async (kind: 'git' | 'folder' = 'git') => {
+      // Why: re-entry guard — rapid Cmd+Enter must not launch duplicate pickers.
+      if (busyLabel !== null) {
+        return
       }
-      if ('error' in result) {
-        throw new Error(result.error)
+      setError(null)
+      if (settings?.activeRuntimeEnvironmentId?.trim()) {
+        const path = serverPath.trim()
+        if (!path) {
+          const message = 'Enter a server path.'
+          setError(message)
+          return
+        }
+        track('onboarding_step4_path_clicked', { path: 'open_folder' })
+        setBusyLabel(kind === 'git' ? 'Opening project…' : 'Opening folder…')
+        try {
+          const repo = await addRepoPath(path, kind)
+          if (!repo) {
+            track('onboarding_step4_path_failed', { path: 'open_folder', reason: 'invalid_path' })
+            return
+          }
+          await completeRepo(repo.id, isGitRepoKind(repo), 'open_folder')
+        } catch (err) {
+          setError(err instanceof Error ? err.message : String(err))
+          track('onboarding_step4_path_failed', { path: 'open_folder', reason: 'invalid_path' })
+        } finally {
+          setBusyLabel(null)
+        }
+        return
       }
-      await completeRepo(result.repo.id, isGitRepoKind(result.repo), 'open_folder')
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err))
-      track('onboarding_step4_path_failed', { path: 'open_folder', reason: 'invalid_path' })
-    } finally {
-      setBusyLabel(null)
-    }
-  }, [busyLabel, completeRepo])
+      track('onboarding_step4_path_clicked', { path: 'open_folder' })
+      const path = await window.api.repos.pickFolder()
+      if (!path) {
+        track('onboarding_step4_path_failed', { path: 'open_folder', reason: 'cancelled' })
+        return
+      }
+      setBusyLabel('Opening project…')
+      try {
+        let result = await window.api.repos.add({ path })
+        if ('error' in result && result.error.includes('Not a valid git repository')) {
+          result = await window.api.repos.add({ path, kind: 'folder' })
+        }
+        if ('error' in result) {
+          throw new Error(result.error)
+        }
+        await completeRepo(result.repo.id, isGitRepoKind(result.repo), 'open_folder')
+      } catch (err) {
+        setError(err instanceof Error ? err.message : String(err))
+        track('onboarding_step4_path_failed', { path: 'open_folder', reason: 'invalid_path' })
+      } finally {
+        setBusyLabel(null)
+      }
+    },
+    [addRepoPath, busyLabel, completeRepo, serverPath, settings?.activeRuntimeEnvironmentId]
+  )
 
   const clone = useCallback(async () => {
     // Why: re-entry guard — prevents Enter spamming from triggering duplicate clones.
@@ -435,12 +466,30 @@ export function useOnboardingFlow(
     }
     setError(null)
     track('onboarding_step4_path_clicked', { path: 'clone_url' })
+    const target = getActiveRuntimeTarget(settings)
+    const destination =
+      target.kind === 'environment' ? cloneDestination.trim() : settings.workspaceDir
+    if (!destination) {
+      const message = 'Enter a server path for the clone destination.'
+      setError(message)
+      return
+    }
     setBusyLabel('Cloning repo…')
     try {
-      const repo = await window.api.repos.clone({
-        url: trimmed,
-        destination: settings.workspaceDir
-      })
+      const repo =
+        target.kind === 'environment'
+          ? (
+              await callRuntimeRpc<{ repo: Repo }>(
+                target,
+                'repo.clone',
+                { url: trimmed, destination },
+                { timeoutMs: 10 * 60_000 }
+              )
+            ).repo
+          : await window.api.repos.clone({
+              url: trimmed,
+              destination
+            })
       await completeRepo(repo.id, true, 'clone_url')
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
@@ -451,7 +500,7 @@ export function useOnboardingFlow(
     } finally {
       setBusyLabel(null)
     }
-  }, [busyLabel, cloneUrl, completeRepo, settings])
+  }, [busyLabel, cloneDestination, cloneUrl, completeRepo, settings])
 
   const skip = useCallback(async () => {
     if (busyLabel) {
@@ -521,6 +570,10 @@ export function useOnboardingFlow(
     hasSelectedFeatureSetup,
     cloneUrl,
     setCloneUrl,
+    serverPath,
+    setServerPath,
+    cloneDestination,
+    setCloneDestination,
     busyLabel,
     error,
     detectedSet,
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index b401307d286..886af2ef3bc 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -17,6 +17,7 @@ import {
 } from './checks-panel-content'
 import { ENTRY_REFRESH_GRACE_MS, shouldEntryRefresh } from './checks-entry-refresh'
 import type { PRInfo, PRCheckDetail, PRComment } from '../../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 export default function ChecksPanel(): React.JSX.Element {
   const activeWorktree = useActiveWorktree()
@@ -377,11 +378,20 @@ export default function ChecksPanel(): React.JSX.Element {
     }
     setTitleSaving(true)
     try {
-      const ok = await window.api.gh.updatePRTitle({
-        repoPath: repo.path,
-        prNumber: pr.number,
-        title: titleDraft.trim()
-      })
+      const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+      const ok =
+        target.kind === 'environment'
+          ? await callRuntimeRpc<boolean>(
+              target,
+              'github.updatePRTitle',
+              { repo: repo.id, prNumber: pr.number, title: titleDraft.trim() },
+              { timeoutMs: 30_000 }
+            )
+          : await window.api.gh.updatePRTitle({
+              repoPath: repo.path,
+              prNumber: pr.number,
+              title: titleDraft.trim()
+            })
       if (ok) {
         // Re-fetch PR to get updated title
         await fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR })
diff --git a/src/renderer/src/components/right-sidebar/FileExplorer.tsx b/src/renderer/src/components/right-sidebar/FileExplorer.tsx
index 54a7e186f32..ecda45f3348 100644
--- a/src/renderer/src/components/right-sidebar/FileExplorer.tsx
+++ b/src/renderer/src/components/right-sidebar/FileExplorer.tsx
@@ -272,7 +272,7 @@ function FileExplorerInner(): React.JSX.Element {
     scrollRef
   })
 
-  const handleDuplicate = useFileDuplicate({ worktreePath, refreshDir })
+  const handleDuplicate = useFileDuplicate({ activeWorktreeId, worktreePath, refreshDir })
 
   if (!worktreePath) {
     return (
diff --git a/src/renderer/src/components/right-sidebar/FileExplorerRow.tsx b/src/renderer/src/components/right-sidebar/FileExplorerRow.tsx
index f0370bced7c..229ee3c070e 100644
--- a/src/renderer/src/components/right-sidebar/FileExplorerRow.tsx
+++ b/src/renderer/src/components/right-sidebar/FileExplorerRow.tsx
@@ -29,6 +29,7 @@ import type { GitFileStatus } from '../../../../shared/types'
 import { STATUS_LABELS } from './status-display'
 import type { TreeNode } from './file-explorer-types'
 import { useFileExplorerRowDrag } from './useFileExplorerRowDrag'
+import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
 
 const ORCA_PATH_MIME = 'text/x-orca-file-path'
 
@@ -372,7 +373,26 @@ export function FileExplorerRow({
             Open Markdown Preview
           </ContextMenuItem>
         )}
-        <ContextMenuItem onSelect={() => window.api.shell.openPath(node.path)}>
+        <ContextMenuItem
+          onSelect={() => {
+            const state = useAppStore.getState()
+            const activeWorktree = Object.values(state.worktreesByRepo)
+              .flat()
+              .find((worktree) => worktree.id === activeWorktreeId)
+            const activeRepo = activeWorktree
+              ? state.repos.find((repo) => repo.id === activeWorktree.repoId)
+              : null
+            if (
+              isLocalPathOpenBlocked(state.settings, {
+                connectionId: activeRepo?.connectionId ?? null
+              })
+            ) {
+              showLocalPathOpenBlockedToast()
+              return
+            }
+            window.api.shell.openPath(node.path)
+          }}
+        >
           <ExternalLink />
           {revealLabel}
         </ContextMenuItem>
diff --git a/src/renderer/src/components/right-sidebar/NotesPanel.tsx b/src/renderer/src/components/right-sidebar/NotesPanel.tsx
index 6b934f7d0bb..b54ffc4d125 100644
--- a/src/renderer/src/components/right-sidebar/NotesPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/NotesPanel.tsx
@@ -23,6 +23,11 @@ import { useActiveWorktree, useRepoById } from '@/store/selectors'
 import { cn } from '@/lib/utils'
 import { getProjectNotesEntityId, openProjectNotesTab } from '@/lib/open-project-notes-tab'
 import { NOTES_ACTIVE_CHANGED_EVENT } from '@/lib/notes-events'
+import {
+  deleteRuntimeProjectNote,
+  listRuntimeProjectNotes,
+  renameRuntimeProjectNote
+} from '@/runtime/runtime-notes-client'
 import type { NoteSummary } from '../../../../shared/notes-types'
 
 export default function NotesPanel(): React.JSX.Element {
@@ -30,6 +35,7 @@ export default function NotesPanel(): React.JSX.Element {
   const repo = useRepoById(activeWorktree?.repoId ?? null)
   const projectId = repo?.id ?? activeWorktree?.repoId ?? null
   const worktreeId = activeWorktree?.id ?? null
+  const settings = useAppStore((s) => s.settings)
 
   const [notes, setNotes] = useState<NoteSummary[]>([])
   const [loading, setLoading] = useState(false)
@@ -49,14 +55,14 @@ export default function NotesPanel(): React.JSX.Element {
     setLoading(true)
     setError(null)
     try {
-      const result = await window.api.notes.list({ projectId, worktreeId, limit: 100 })
+      const result = await listRuntimeProjectNotes(settings, { projectId, worktreeId, limit: 100 })
       setNotes(result.notes)
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
     } finally {
       setLoading(false)
     }
-  }, [projectId, worktreeId])
+  }, [projectId, settings, worktreeId])
 
   useEffect(() => {
     void refresh()
@@ -106,7 +112,7 @@ export default function NotesPanel(): React.JSX.Element {
         return
       }
       try {
-        const result = await window.api.notes.rename({
+        const result = await renameRuntimeProjectNote(settings, {
           projectId,
           worktreeId,
           note: note.id,
@@ -126,7 +132,7 @@ export default function NotesPanel(): React.JSX.Element {
         toast.error(err instanceof Error ? err.message : `Failed to rename '${note.title}'.`)
       }
     },
-    [projectId, refresh, renameValue, worktreeId]
+    [projectId, refresh, renameValue, settings, worktreeId]
   )
 
   const cancelRename = useCallback(() => {
@@ -140,7 +146,7 @@ export default function NotesPanel(): React.JSX.Element {
     }
     setDeleting(true)
     try {
-      await window.api.notes.delete({ projectId, worktreeId, note: deleteTarget.id })
+      await deleteRuntimeProjectNote(settings, { projectId, worktreeId, note: deleteTarget.id })
       const entityId = getProjectNotesEntityId(projectId, deleteTarget.id)
       const state = useAppStore.getState()
       const tabIdsToClose: string[] = []
@@ -162,7 +168,7 @@ export default function NotesPanel(): React.JSX.Element {
     } finally {
       setDeleting(false)
     }
-  }, [deleteTarget, deleting, projectId, refresh, worktreeId])
+  }, [deleteTarget, deleting, projectId, refresh, settings, worktreeId])
 
   const copyNotePath = useCallback(async (note: NoteSummary): Promise<void> => {
     await navigator.clipboard.writeText(note.relativePath)
diff --git a/src/renderer/src/components/right-sidebar/PRActions.tsx b/src/renderer/src/components/right-sidebar/PRActions.tsx
index bcb51d55324..bb913938c25 100644
--- a/src/renderer/src/components/right-sidebar/PRActions.tsx
+++ b/src/renderer/src/components/right-sidebar/PRActions.tsx
@@ -6,6 +6,7 @@ import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@/components/ui/tooltip'
 import type { PRInfo, Repo, Worktree } from '../../../../shared/types'
 import { runWorktreeDeleteWithToast } from '../sidebar/delete-worktree-flow'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 const MERGE_METHODS = ['squash', 'merge', 'rebase'] as const
 
@@ -39,11 +40,20 @@ export default function PRActions({
       setMergeError(null)
       setMergeMenuOpen(false)
       try {
-        const result = await window.api.gh.mergePR({
-          repoPath: repo.path,
-          prNumber: pr.number,
-          method
-        })
+        const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+        const result =
+          target.kind === 'environment'
+            ? await callRuntimeRpc<{ ok: true } | { ok: false; error: string }>(
+                target,
+                'github.mergePR',
+                { repo: repo.id, prNumber: pr.number, method },
+                { timeoutMs: 30_000 }
+              )
+            : await window.api.gh.mergePR({
+                repoPath: repo.path,
+                prNumber: pr.number,
+                method
+              })
         if (!result.ok) {
           setMergeError(result.error)
         } else {
@@ -55,7 +65,7 @@ export default function PRActions({
         setMerging(false)
       }
     },
-    [repo.path, pr.number, onRefreshPR]
+    [repo.id, repo.path, pr.number, onRefreshPR]
   )
 
   useEffect(() => {
diff --git a/src/renderer/src/components/right-sidebar/Search.tsx b/src/renderer/src/components/right-sidebar/Search.tsx
index d85c5228a8c..c5c535317d0 100644
--- a/src/renderer/src/components/right-sidebar/Search.tsx
+++ b/src/renderer/src/components/right-sidebar/Search.tsx
@@ -3,6 +3,7 @@ import { useVirtualizer } from '@tanstack/react-virtual'
 import { useAppStore } from '@/store'
 import { useActiveWorktree } from '@/store/selectors'
 import { getConnectionId } from '@/lib/connection-context'
+import { searchRuntimeFiles } from '@/runtime/runtime-file-client'
 import type { SearchFileResult, SearchMatch } from '../../../../shared/types'
 import { buildSearchRows } from './search-rows'
 import { cancelRevealFrame, openMatchResult } from './search-match-open'
@@ -173,20 +174,27 @@ export default function Search(): React.JSX.Element {
         try {
           const state = useAppStore.getState()
           const connectionId = getConnectionId(activeWorktreeId!) ?? undefined
-          const results = await window.api.fs.search({
-            query: query.trim(),
-            rootPath: worktreePath,
-            connectionId,
-            caseSensitive:
-              state.fileSearchStateByWorktree[activeWorktreeId!]?.caseSensitive ?? false,
-            wholeWord: state.fileSearchStateByWorktree[activeWorktreeId!]?.wholeWord ?? false,
-            useRegex: state.fileSearchStateByWorktree[activeWorktreeId!]?.useRegex ?? false,
-            includePattern:
-              state.fileSearchStateByWorktree[activeWorktreeId!]?.includePattern || undefined,
-            excludePattern:
-              state.fileSearchStateByWorktree[activeWorktreeId!]?.excludePattern || undefined,
-            maxResults: SEARCH_MAX_RESULTS
-          })
+          const results = await searchRuntimeFiles(
+            {
+              settings: state.settings,
+              worktreeId: activeWorktreeId,
+              worktreePath,
+              connectionId
+            },
+            {
+              query: query.trim(),
+              rootPath: worktreePath,
+              caseSensitive:
+                state.fileSearchStateByWorktree[activeWorktreeId!]?.caseSensitive ?? false,
+              wholeWord: state.fileSearchStateByWorktree[activeWorktreeId!]?.wholeWord ?? false,
+              useRegex: state.fileSearchStateByWorktree[activeWorktreeId!]?.useRegex ?? false,
+              includePattern:
+                state.fileSearchStateByWorktree[activeWorktreeId!]?.includePattern || undefined,
+              excludePattern:
+                state.fileSearchStateByWorktree[activeWorktreeId!]?.excludePattern || undefined,
+              maxResults: SEARCH_MAX_RESULTS
+            }
+          )
           if (latestSearchIdRef.current === searchId) {
             updateActiveSearchState({ results })
           }
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index 7047bf1e8d4..a3aeea40cce 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -30,6 +30,7 @@ import {
 } from 'lucide-react'
 import { useAppStore } from '@/store'
 import { useActiveWorktree, useRepoById, useWorktreeMap } from '@/store/selectors'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
 import { detectLanguage } from '@/lib/language-detect'
 import { basename, dirname, joinPath } from '@/lib/path'
 import { cn } from '@/lib/utils'
@@ -92,6 +93,16 @@ import {
   requestEditorSaveQuiesce
 } from '@/components/editor/editor-autosave'
 import { getConnectionId } from '@/lib/connection-context'
+import {
+  bulkStageRuntimeGitPaths,
+  bulkUnstageRuntimeGitPaths,
+  commitRuntimeGit,
+  discardRuntimeGitPath,
+  getRuntimeGitBranchCompare,
+  stageRuntimeGitPath,
+  unstageRuntimeGitPath
+} from '@/runtime/runtime-git-client'
+import { getRuntimeRepoBaseRefDefault } from '@/runtime/runtime-repo-client'
 import { PullRequestIcon } from './checks-panel-content'
 import type {
   DiffComment,
@@ -233,6 +244,7 @@ function SourceControlInner(): React.JSX.Element {
   const remoteStatusesByWorktree = useAppStore((s) => s.remoteStatusesByWorktree)
   const isRemoteOperationActive = useAppStore((s) => s.isRemoteOperationActive)
   const inFlightRemoteOpKind = useAppStore((s) => s.inFlightRemoteOpKind)
+  const settings = useAppStore((s) => s.settings)
   const hostedReviewCache = useAppStore((s) => s.hostedReviewCache)
   const fetchHostedReviewForBranch = useAppStore((s) => s.fetchHostedReviewForBranch)
   const updateRepo = useAppStore((s) => s.updateRepo)
@@ -366,6 +378,7 @@ function SourceControlInner(): React.JSX.Element {
     }
     const connectionId = getConnectionId(activeWorktreeId) ?? undefined
     await refreshGitStatusForWorktree({
+      settings: useAppStore.getState().settings,
       worktreeId: activeWorktreeId,
       worktreePath,
       connectionId,
@@ -407,8 +420,7 @@ function SourceControlInner(): React.JSX.Element {
     setDefaultBaseRef(null)
 
     let stale = false
-    void window.api.repos
-      .getBaseRefDefault({ repoId: activeRepo.id })
+    void getRuntimeRepoBaseRefDefault(useAppStore.getState().settings, activeRepo.id)
       .then((result) => {
         if (!stale) {
           // Why: IPC now returns a `{ defaultBaseRef, remoteCount }` envelope;
@@ -436,7 +448,8 @@ function SourceControlInner(): React.JSX.Element {
   const hasUncommittedEntries = entries.length > 0
 
   const branchName = activeWorktree?.branch.replace(/^refs\/heads\//, '') ?? 'HEAD'
-  const hostedReviewCacheKey = activeRepo && branchName ? `${activeRepo.path}::${branchName}` : null
+  const hostedReviewCacheKey =
+    activeRepo && branchName ? getHostedReviewCacheKey(activeRepo.path, branchName, settings) : null
   const hostedReview: HostedReviewInfo | null = hostedReviewCacheKey
     ? (hostedReviewCache[hostedReviewCacheKey]?.data ?? null)
     : null
@@ -612,11 +625,15 @@ function SourceControlInner(): React.JSX.Element {
     setCommitInFlightByWorktree((prev) => ({ ...prev, [activeWorktreeId]: true }))
     setCommitErrors((prev) => ({ ...prev, [activeWorktreeId]: null }))
     try {
-      const commitResult = await window.api.git.commit({
-        worktreePath,
-        message,
-        connectionId
-      })
+      const commitResult = await commitRuntimeGit(
+        {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        },
+        message
+      )
       if (!commitResult.success) {
         setCommitErrors((prev) => ({
           ...prev,
@@ -948,7 +965,15 @@ function SourceControlInner(): React.JSX.Element {
     setIsExecutingBulk(true)
     try {
       const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-      await window.api.git.bulkStage({ worktreePath, filePaths: bulkStagePaths, connectionId })
+      await bulkStageRuntimeGitPaths(
+        {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        },
+        bulkStagePaths
+      )
       await refreshActiveGitStatusAfterMutation()
       clearSelection()
     } finally {
@@ -969,7 +994,15 @@ function SourceControlInner(): React.JSX.Element {
     setIsExecutingBulk(true)
     try {
       const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-      await window.api.git.bulkUnstage({ worktreePath, filePaths: bulkUnstagePaths, connectionId })
+      await bulkUnstageRuntimeGitPaths(
+        {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        },
+        bulkUnstagePaths
+      )
       await refreshActiveGitStatusAfterMutation()
       clearSelection()
     } finally {
@@ -999,7 +1032,15 @@ function SourceControlInner(): React.JSX.Element {
       setIsExecutingBulk(true)
       try {
         const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-        await window.api.git.bulkStage({ worktreePath, filePaths: paths, connectionId })
+        await bulkStageRuntimeGitPaths(
+          {
+            settings: useAppStore.getState().settings,
+            worktreeId: activeWorktreeId,
+            worktreePath,
+            connectionId
+          },
+          paths
+        )
         await refreshActiveGitStatusAfterMutation()
         clearSelection()
       } finally {
@@ -1034,7 +1075,15 @@ function SourceControlInner(): React.JSX.Element {
     setIsExecutingBulk(true)
     try {
       const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-      await window.api.git.bulkStage({ worktreePath, filePaths, connectionId })
+      await bulkStageRuntimeGitPaths(
+        {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        },
+        filePaths
+      )
       await refreshActiveGitStatusAfterMutation()
       clearSelection()
     } finally {
@@ -1086,7 +1135,15 @@ function SourceControlInner(): React.JSX.Element {
     setIsExecutingBulk(true)
     try {
       const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-      await window.api.git.bulkUnstage({ worktreePath, filePaths: paths, connectionId })
+      await bulkUnstageRuntimeGitPaths(
+        {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        },
+        paths
+      )
       await refreshActiveGitStatusAfterMutation()
       clearSelection()
     } finally {
@@ -1132,11 +1189,15 @@ function SourceControlInner(): React.JSX.Element {
 
     try {
       const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-      const result = await window.api.git.branchCompare({
-        worktreePath,
-        baseRef: effectiveBaseRef,
-        connectionId
-      })
+      const result = await getRuntimeGitBranchCompare(
+        {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        },
+        effectiveBaseRef
+      )
       setGitBranchCompareResult(activeWorktreeId, requestKey, result)
     } catch (error) {
       setGitBranchCompareResult(activeWorktreeId, requestKey, {
@@ -1314,7 +1375,15 @@ function SourceControlInner(): React.JSX.Element {
       }
       try {
         const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-        await window.api.git.stage({ worktreePath, filePath, connectionId })
+        await stageRuntimeGitPath(
+          {
+            settings: useAppStore.getState().settings,
+            worktreeId: activeWorktreeId,
+            worktreePath,
+            connectionId
+          },
+          filePath
+        )
         await refreshActiveGitStatusAfterMutation()
       } catch {
         // git operation failed silently
@@ -1330,7 +1399,15 @@ function SourceControlInner(): React.JSX.Element {
       }
       try {
         const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-        await window.api.git.unstage({ worktreePath, filePath, connectionId })
+        await unstageRuntimeGitPath(
+          {
+            settings: useAppStore.getState().settings,
+            worktreeId: activeWorktreeId,
+            worktreePath,
+            connectionId
+          },
+          filePath
+        )
         await refreshActiveGitStatusAfterMutation()
       } catch {
         // git operation failed silently
@@ -1357,7 +1434,15 @@ function SourceControlInner(): React.JSX.Element {
         relativePath: filePath
       })
       const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-      await window.api.git.discard({ worktreePath, filePath, connectionId })
+      await discardRuntimeGitPath(
+        {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        },
+        filePath
+      )
       notifyEditorExternalFileChange({
         worktreeId: activeWorktreeId,
         worktreePath,
@@ -1438,7 +1523,15 @@ function SourceControlInner(): React.JSX.Element {
         const errors: unknown[] = []
         const result = await runDiscardAllForArea(area, paths, {
           bulkUnstage: (filePaths) =>
-            window.api.git.bulkUnstage({ worktreePath, filePaths, connectionId }),
+            bulkUnstageRuntimeGitPaths(
+              {
+                settings: useAppStore.getState().settings,
+                worktreeId: activeWorktreeId,
+                worktreePath,
+                connectionId
+              },
+              filePaths
+            ),
           discardMany,
           discardOne: discardSingle,
           onError: (error) => {
diff --git a/src/renderer/src/components/right-sidebar/git-status-refresh.ts b/src/renderer/src/components/right-sidebar/git-status-refresh.ts
index 3929c54065d..d7fafc21d8e 100644
--- a/src/renderer/src/components/right-sidebar/git-status-refresh.ts
+++ b/src/renderer/src/components/right-sidebar/git-status-refresh.ts
@@ -1,4 +1,5 @@
-import type { GitStatusResult, GitUpstreamStatus } from '../../../../shared/types'
+import { getRuntimeGitStatus } from '@/runtime/runtime-git-client'
+import type { GitStatusResult, GitUpstreamStatus, GlobalSettings } from '../../../../shared/types'
 
 export type GitStatusRefreshDeps = {
   setGitStatus: (worktreeId: string, status: GitStatusResult) => void
@@ -15,17 +16,21 @@ export type GitStatusRefreshDeps = {
 }
 
 export async function refreshGitStatusForWorktree({
+  settings,
   worktreeId,
   worktreePath,
   connectionId,
   deps
 }: {
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
   worktreeId: string
   worktreePath: string
   connectionId?: string
   deps: GitStatusRefreshDeps
 }): Promise<void> {
-  const status = (await window.api.git.status({
+  const status = (await getRuntimeGitStatus({
+    settings,
+    worktreeId,
     worktreePath,
     connectionId
   })) as GitStatusResult
diff --git a/src/renderer/src/components/right-sidebar/useFileDeletion.ts b/src/renderer/src/components/right-sidebar/useFileDeletion.ts
index 44996e80790..6aeb95dd24b 100644
--- a/src/renderer/src/components/right-sidebar/useFileDeletion.ts
+++ b/src/renderer/src/components/right-sidebar/useFileDeletion.ts
@@ -4,6 +4,7 @@ import { toast } from 'sonner'
 import { useAppStore } from '@/store'
 import { dirname } from '@/lib/path'
 import { getConnectionId } from '@/lib/connection-context'
+import { findWorktreeById } from '@/store/slices/worktree-helpers'
 import { isPathEqualOrDescendant } from './file-explorer-paths'
 import type { TreeNode } from './file-explorer-types'
 import {
@@ -11,6 +12,12 @@ import {
   requestEditorSaveQuiesce
 } from '@/components/editor/editor-autosave'
 import { commitFileExplorerOp } from './fileExplorerUndoRedo'
+import {
+  deleteRuntimePath,
+  isRemoteRuntimeFileOperation,
+  readRuntimeFileContent,
+  writeRuntimeFile
+} from '@/runtime/runtime-file-client'
 
 type UseFileDeletionParams = {
   activeWorktreeId: string | null
@@ -54,7 +61,18 @@ export function useFileDeletion({
       inFlightRef.current.add(node.path)
 
       const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-      const isRemote = connectionId !== undefined
+      const state = useAppStore.getState()
+      const worktree = activeWorktreeId
+        ? findWorktreeById(state.worktreesByRepo, activeWorktreeId)
+        : null
+      const fileContext = {
+        settings: state.settings,
+        worktreeId: activeWorktreeId,
+        worktreePath: worktree?.path ?? null,
+        connectionId
+      }
+      const isRemote =
+        connectionId !== undefined || isRemoteRuntimeFileOperation(fileContext, node.path)
 
       // Why: remote deletes go through `rm` on the relay — there is no OS-level
       // Trash/Recycle Bin, so the operation is permanent. Require an explicit
@@ -93,7 +111,13 @@ export function useFileDeletion({
         let undoContent: string | undefined
         if (!node.isDirectory) {
           try {
-            const rf = await window.api.fs.readFile({ filePath: node.path, connectionId })
+            const rf = await readRuntimeFileContent({
+              settings: fileContext.settings,
+              filePath: node.path,
+              relativePath: node.relativePath,
+              worktreeId: activeWorktreeId ?? undefined,
+              connectionId
+            })
             if (!rf.isBinary) {
               undoContent = rf.content
             }
@@ -103,28 +127,16 @@ export function useFileDeletion({
           }
         }
 
-        await window.api.fs.deletePath({
-          targetPath: node.path,
-          connectionId,
-          recursive: node.isDirectory
-        })
+        await deleteRuntimePath(fileContext, node.path, node.isDirectory)
 
         if (undoContent !== undefined) {
           commitFileExplorerOp({
             undo: async () => {
-              await window.api.fs.writeFile({
-                filePath: node.path,
-                content: undoContent,
-                connectionId
-              })
+              await writeRuntimeFile(fileContext, node.path, undoContent)
               await refreshDir(parentDir)
             },
             redo: async () => {
-              await window.api.fs.deletePath({
-                targetPath: node.path,
-                connectionId,
-                recursive: node.isDirectory
-              })
+              await deleteRuntimePath(fileContext, node.path, node.isDirectory)
               await refreshDir(parentDir)
             }
           })
diff --git a/src/renderer/src/components/right-sidebar/useFileDuplicate.ts b/src/renderer/src/components/right-sidebar/useFileDuplicate.ts
index 255b380ca5a..82ef96b1353 100644
--- a/src/renderer/src/components/right-sidebar/useFileDuplicate.ts
+++ b/src/renderer/src/components/right-sidebar/useFileDuplicate.ts
@@ -2,6 +2,9 @@ import { useCallback } from 'react'
 import { toast } from 'sonner'
 import { basename, dirname, joinPath } from '@/lib/path'
 import type { TreeNode } from './file-explorer-types'
+import { useAppStore } from '@/store'
+import { copyRuntimePath, runtimePathExists } from '@/runtime/runtime-file-client'
+import { getConnectionId } from '@/lib/connection-context'
 
 /**
  * Electron's ipcRenderer.invoke wraps errors as:
@@ -17,11 +20,13 @@ function extractIpcErrorMessage(err: unknown, fallback: string): string {
 }
 
 type UseFileDuplicateParams = {
+  activeWorktreeId: string | null
   worktreePath: string | null
   refreshDir: (dirPath: string) => Promise<void>
 }
 
 export function useFileDuplicate({
+  activeWorktreeId,
   worktreePath,
   refreshDir
 }: UseFileDuplicateParams): (node: TreeNode) => void {
@@ -37,12 +42,19 @@ export function useFileDuplicate({
       const ext = dotIndex > 0 ? name.slice(dotIndex) : ''
 
       const run = async (): Promise<void> => {
+        const settings = useAppStore.getState().settings
+        const context = {
+          settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId: getConnectionId(activeWorktreeId) ?? undefined
+        }
         // Why: generate a unique "stem copy.ext", "stem copy 2.ext", … name
         // so we never collide with an existing file. pathExists checks are
         // sequential to avoid TOCTOU races with COPYFILE_EXCL on the backend.
         let candidate = joinPath(dir, `${stem} copy${ext}`)
         let n = 2
-        while (await window.api.shell.pathExists(candidate)) {
+        while (await runtimePathExists(context, candidate)) {
           candidate = joinPath(dir, `${stem} copy ${n}${ext}`)
           n += 1
         }
@@ -58,7 +70,7 @@ export function useFileDuplicate({
         // eslint-disable-next-line no-constant-condition
         while (true) {
           try {
-            await window.api.shell.copyFile({ srcPath: node.path, destPath: candidate })
+            await copyRuntimePath(context, node.path, candidate)
             break
           } catch (err) {
             const isEexist =
@@ -87,6 +99,6 @@ export function useFileDuplicate({
       }
       void run()
     },
-    [worktreePath, refreshDir]
+    [activeWorktreeId, worktreePath, refreshDir]
   )
 }
diff --git a/src/renderer/src/components/right-sidebar/useFileExplorerDragDrop.ts b/src/renderer/src/components/right-sidebar/useFileExplorerDragDrop.ts
index 30c8f964881..32716165c12 100644
--- a/src/renderer/src/components/right-sidebar/useFileExplorerDragDrop.ts
+++ b/src/renderer/src/components/right-sidebar/useFileExplorerDragDrop.ts
@@ -10,6 +10,7 @@ import { detectLanguage } from '@/lib/language-detect'
 import { getConnectionId } from '@/lib/connection-context'
 import { requestEditorSaveQuiesce } from '@/components/editor/editor-autosave'
 import { commitFileExplorerOp } from './fileExplorerUndoRedo'
+import { renameRuntimePath } from '@/runtime/runtime-file-client'
 
 function extractIpcErrorMessage(err: unknown, fallback: string): string {
   if (!(err instanceof Error)) {
@@ -281,16 +282,22 @@ export function useFileExplorerDragDrop({
 
         try {
           const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-          await window.api.fs.rename({ oldPath: sourcePath, newPath, connectionId })
+          const fileContext = {
+            settings: useAppStore.getState().settings,
+            worktreeId: activeWorktreeId,
+            worktreePath,
+            connectionId
+          }
+          await renameRuntimePath(fileContext, sourcePath, newPath)
 
           commitFileExplorerOp({
             undo: async () => {
-              await window.api.fs.rename({ oldPath: newPath, newPath: sourcePath, connectionId })
+              await renameRuntimePath(fileContext, newPath, sourcePath)
               await Promise.all([refreshDir(destDir), refreshDir(sourceDir)])
               remapOpenTabsForMovedPath(newPath, sourcePath)
             },
             redo: async () => {
-              await window.api.fs.rename({ oldPath: sourcePath, newPath, connectionId })
+              await renameRuntimePath(fileContext, sourcePath, newPath)
               await Promise.all([refreshDir(sourceDir), refreshDir(destDir)])
               remapOpenTabsForMovedPath(sourcePath, newPath)
             }
diff --git a/src/renderer/src/components/right-sidebar/useFileExplorerImport.ts b/src/renderer/src/components/right-sidebar/useFileExplorerImport.ts
index b08ddb30532..9a253a476ab 100644
--- a/src/renderer/src/components/right-sidebar/useFileExplorerImport.ts
+++ b/src/renderer/src/components/right-sidebar/useFileExplorerImport.ts
@@ -3,6 +3,8 @@ import type { Dispatch, SetStateAction } from 'react'
 import { toast } from 'sonner'
 import { getConnectionId } from '@/lib/connection-context'
 import { extractIpcErrorMessage } from '@/lib/ipc-error'
+import { useAppStore } from '@/store'
+import { importExternalPathsToRuntime } from '@/runtime/runtime-file-client'
 
 type UseFileExplorerImportParams = {
   worktreePath: string | null
@@ -61,21 +63,26 @@ export function useFileExplorerImport({
 
       void (async () => {
         try {
-          const { results } = await window.api.fs.importExternalPaths({
-            sourcePaths: paths,
-            destDir: destinationDir,
-            connectionId
-          })
+          const settings = useAppStore.getState().settings
+          const { results } = await importExternalPathsToRuntime(
+            {
+              settings,
+              worktreeId: wtId,
+              worktreePath: worktreePathRef.current,
+              connectionId
+            },
+            paths,
+            destinationDir
+          )
 
           // Refresh the destination directory once per gesture
           await refreshDirRef.current(destinationDir)
 
           // Why: only select (highlight) the first imported file — don't trigger
-          // the full reveal machinery (scrollToIndex + flash) because the user
-          // already knows where they dropped the file. The reveal's aggressive
-          // scroll-to-center races with FS watcher refreshes and can snap the
-          // viewport back to the top of the tree.
+          // the full reveal machinery because watcher refreshes can otherwise
+          // snap the tree viewport away from the user's drop target.
           const imported = results.filter((r) => r.status === 'imported')
+          const skipped = results.filter((r) => r.status === 'skipped')
           const failed = results.filter((r) => r.status === 'failed')
 
           if (imported.length > 0) {
@@ -85,6 +92,9 @@ export function useFileExplorerImport({
           if (failed.length > 0) {
             const noun = failed.length === 1 ? 'file' : 'files'
             toast.error(`Failed to import ${failed.length} ${noun}.`)
+          } else if (skipped.length > 0 && imported.length === 0) {
+            const noun = skipped.length === 1 ? 'file' : 'files'
+            toast.error(`Skipped ${skipped.length} ${noun}.`)
           }
         } catch (err) {
           toast.error(extractIpcErrorMessage(err, 'Failed to import files.'))
diff --git a/src/renderer/src/components/right-sidebar/useFileExplorerInlineInput.ts b/src/renderer/src/components/right-sidebar/useFileExplorerInlineInput.ts
index 65d495437be..a4064115397 100644
--- a/src/renderer/src/components/right-sidebar/useFileExplorerInlineInput.ts
+++ b/src/renderer/src/components/right-sidebar/useFileExplorerInlineInput.ts
@@ -9,6 +9,7 @@ import { extractIpcErrorMessage, renameFileOnDisk } from '@/lib/rename-file'
 import type { InlineInput } from './FileExplorerRow'
 import type { TreeNode } from './file-explorer-types'
 import { commitFileExplorerOp } from './fileExplorerUndoRedo'
+import { createRuntimePath, deleteRuntimePath } from '@/runtime/runtime-file-client'
 
 type UseFileExplorerInlineInputParams = {
   activeWorktreeId: string | null
@@ -110,6 +111,12 @@ export function useFileExplorerInlineInput({
       }
       const run = async (): Promise<void> => {
         const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
+        const fileContext = {
+          settings: useAppStore.getState().settings,
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId
+        }
         if (inlineInput.type === 'rename' && inlineInput.existingPath) {
           await renameFileOnDisk({
             oldPath: inlineInput.existingPath,
@@ -121,29 +128,31 @@ export function useFileExplorerInlineInput({
         } else {
           const fullPath = joinPath(inlineInput.parentPath, name)
           try {
-            await (inlineInput.type === 'folder'
-              ? window.api.fs.createDir({ dirPath: fullPath, connectionId })
-              : window.api.fs.createFile({ filePath: fullPath, connectionId }))
+            await createRuntimePath(
+              fileContext,
+              fullPath,
+              inlineInput.type === 'folder' ? 'directory' : 'file'
+            )
             const parentForRefresh = inlineInput.parentPath
             if (inlineInput.type === 'folder') {
               commitFileExplorerOp({
                 undo: async () => {
-                  await window.api.fs.deletePath({ targetPath: fullPath, connectionId })
+                  await deleteRuntimePath(fileContext, fullPath, true)
                   await refreshDir(parentForRefresh)
                 },
                 redo: async () => {
-                  await window.api.fs.createDir({ dirPath: fullPath, connectionId })
+                  await createRuntimePath(fileContext, fullPath, 'directory')
                   await refreshDir(parentForRefresh)
                 }
               })
             } else {
               commitFileExplorerOp({
                 undo: async () => {
-                  await window.api.fs.deletePath({ targetPath: fullPath, connectionId })
+                  await deleteRuntimePath(fileContext, fullPath)
                   await refreshDir(parentForRefresh)
                 },
                 redo: async () => {
-                  await window.api.fs.createFile({ filePath: fullPath, connectionId })
+                  await createRuntimePath(fileContext, fullPath, 'file')
                   await refreshDir(parentForRefresh)
                 }
               })
diff --git a/src/renderer/src/components/right-sidebar/useFileExplorerTree.ts b/src/renderer/src/components/right-sidebar/useFileExplorerTree.ts
index a09c31b3333..7c52f0a756d 100644
--- a/src/renderer/src/components/right-sidebar/useFileExplorerTree.ts
+++ b/src/renderer/src/components/right-sidebar/useFileExplorerTree.ts
@@ -5,6 +5,8 @@ import { getConnectionId } from '@/lib/connection-context'
 import type { DirCache, TreeNode } from './file-explorer-types'
 import { splitPathSegments } from './path-tree'
 import { shouldIncludeFileExplorerEntry } from './file-explorer-entries'
+import { readRuntimeDirectory } from '@/runtime/runtime-file-client'
+import { useAppStore } from '@/store'
 
 type UseFileExplorerTreeResult = {
   dirCache: Record<string, DirCache>
@@ -48,7 +50,15 @@ export function useFileExplorerTree(
       }))
       try {
         const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-        const entries = await window.api.fs.readDir({ dirPath, connectionId })
+        const entries = await readRuntimeDirectory(
+          {
+            settings: useAppStore.getState().settings,
+            worktreeId: activeWorktreeId,
+            worktreePath,
+            connectionId
+          },
+          dirPath
+        )
         if (depth === -1) {
           setRootError(null)
         }
diff --git a/src/renderer/src/components/right-sidebar/useFileExplorerWatch.test.ts b/src/renderer/src/components/right-sidebar/useFileExplorerWatch.test.ts
index 2d0c9290074..6aae3550b35 100644
--- a/src/renderer/src/components/right-sidebar/useFileExplorerWatch.test.ts
+++ b/src/renderer/src/components/right-sidebar/useFileExplorerWatch.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import type { FsChangedPayload } from '../../../../shared/types'
 import {
+  canonicalizeFileExplorerWatchPath,
   getExternalFileChangeRelativePath,
   payloadRequiresDeferredTreeRefresh
 } from './useFileExplorerWatch'
@@ -32,6 +33,22 @@ describe('getExternalFileChangeRelativePath', () => {
     ).toBe('config/settings.json')
   })
 
+  it('matches Windows paths case-insensitively before deriving the relative path', () => {
+    expect(
+      getExternalFileChangeRelativePath('C:\\Repo', 'c:\\repo\\config\\settings.json', false)
+    ).toBe('config/settings.json')
+  })
+
+  it('preserves UNC roots when deriving the relative path', () => {
+    expect(
+      getExternalFileChangeRelativePath(
+        '//Server/Share/Repo',
+        '//server/share/repo/config/settings.json',
+        false
+      )
+    ).toBe('config/settings.json')
+  })
+
   it('ignores paths outside the active worktree', () => {
     expect(
       getExternalFileChangeRelativePath('/repo', '/other/config/settings.json', false)
@@ -62,6 +79,29 @@ describe('getExternalFileChangeRelativePath', () => {
   })
 })
 
+describe('canonicalizeFileExplorerWatchPath', () => {
+  it('returns event paths with the watched worktree casing for UNC cache lookups', () => {
+    expect(
+      canonicalizeFileExplorerWatchPath('//Server/Share/Repo', '//server/share/repo/src/index.ts')
+    ).toBe('//Server/Share/Repo/src/index.ts')
+  })
+
+  it('preserves the watched worktree separator style for Windows cache lookups', () => {
+    expect(canonicalizeFileExplorerWatchPath('C:\\Repo', 'c:\\repo\\src\\index.ts')).toBe(
+      'C:\\Repo\\src\\index.ts'
+    )
+  })
+
+  it('rejects sibling UNC shares whose path merely shares a prefix', () => {
+    expect(
+      canonicalizeFileExplorerWatchPath(
+        '//Server/Share/Repo',
+        '//server/share/repository/src/index.ts'
+      )
+    ).toBeNull()
+  })
+})
+
 describe('payloadRequiresDeferredTreeRefresh', () => {
   function payload(events: FsChangedPayload['events'], worktreePath = '/repo'): FsChangedPayload {
     return { worktreePath, events }
diff --git a/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts b/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts
index 22c9dbd0205..5f926604e81 100644
--- a/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts
+++ b/src/renderer/src/components/right-sidebar/useFileExplorerWatch.ts
@@ -3,14 +3,19 @@ import type { Dispatch, SetStateAction } from 'react'
 import type { FsChangedPayload } from '../../../../shared/types'
 import type { DirCache } from './file-explorer-types'
 import type { InlineInput } from './FileExplorerRow'
-import { normalizeRelativePath } from '@/lib/path'
-import { normalizeAbsolutePath } from './file-explorer-paths'
-import { dirname } from '@/lib/path'
+import { joinPath, normalizeRelativePath, dirname } from '@/lib/path'
+import {
+  isPathInsideOrEqual,
+  normalizeRuntimePathForComparison,
+  relativePathInsideRoot
+} from '../../../../shared/cross-platform-path'
 import {
   purgeDirCacheSubtree,
   purgeExpandedDirsSubtree,
   clearStalePendingReveal
 } from './file-explorer-watcher-reconcile'
+import { useAppStore } from '@/store'
+import { subscribeRuntimeFileChanges } from '@/runtime/runtime-file-client'
 
 type UseFileExplorerWatchParams = {
   worktreePath: string | null
@@ -35,17 +40,8 @@ export function getExternalFileChangeRelativePath(
     return null
   }
 
-  const normalizedWorktreePath = normalizeAbsolutePath(worktreePath)
-  const normalizedAbsolutePath = normalizeAbsolutePath(absolutePath)
-  // Why: `normalizeAbsolutePath` preserves the trailing slash for filesystem
-  // roots (`/` on POSIX, `C:/` on Windows drive roots) but strips it from all
-  // other paths. Blindly appending `/` would produce `//` or `C://`, so
-  // external edits under a root worktree would fail the prefix check and be
-  // silently dropped. Treat those roots as already-terminated prefixes.
-  const isFsRoot = normalizedWorktreePath === '/' || /^[A-Za-z]:\/$/.test(normalizedWorktreePath)
-  const worktreePrefix = isFsRoot ? normalizedWorktreePath : `${normalizedWorktreePath}/`
-
-  if (!normalizedAbsolutePath.startsWith(worktreePrefix)) {
+  const relativePath = relativePathInsideRoot(worktreePath, absolutePath)
+  if (relativePath === null || relativePath === '') {
     return null
   }
 
@@ -54,14 +50,37 @@ export function getExternalFileChangeRelativePath(
   // filesystem watcher reports absolute paths, so normalize them here before
   // the explorer refresh path returns; otherwise terminal edits refresh the
   // tree but leave the editor's cached file contents stale.
-  return normalizeRelativePath(normalizedAbsolutePath.slice(worktreePrefix.length))
+  return normalizeRelativePath(relativePath)
+}
+
+export function canonicalizeFileExplorerWatchPath(
+  worktreePath: string,
+  absolutePath: string
+): string | null {
+  const relativePath = relativePathInsideRoot(worktreePath, absolutePath)
+  if (relativePath === null) {
+    return null
+  }
+
+  const rootPath = normalizeExplorerAbsolutePath(worktreePath)
+  return relativePath === '' ? rootPath : joinPath(rootPath, relativePath)
+}
+
+function normalizeExplorerAbsolutePath(path: string): string {
+  if (path === '/' || /^[A-Za-z]:[\\/]$/.test(path)) {
+    return path
+  }
+  return path.replace(/[\\/]+$/, '')
 }
 
 export function payloadRequiresDeferredTreeRefresh(
   payload: FsChangedPayload,
   currentWorktreePath: string
 ): boolean {
-  if (normalizeAbsolutePath(payload.worktreePath) !== normalizeAbsolutePath(currentWorktreePath)) {
+  if (
+    normalizeRuntimePathForComparison(payload.worktreePath) !==
+    normalizeRuntimePathForComparison(currentWorktreePath)
+  ) {
     return false
   }
 
@@ -91,6 +110,8 @@ export function useFileExplorerWatch({
   dragSourcePath,
   isNativeDragOver
 }: UseFileExplorerWatchParams): void {
+  const activeRuntimeEnvironmentId = useAppStore((s) => s.settings?.activeRuntimeEnvironmentId)
+
   // Keep refs for values accessed inside the event handler to avoid
   // re-subscribing the IPC listener on every render.
   const dirCacheRef = useRef(dirCache)
@@ -151,7 +172,8 @@ export function useFileExplorerWatch({
       // the old worktree can arrive after the switch. Processing them against
       // the new worktree's tree state would corrupt dirCache (design §3).
       if (
-        normalizeAbsolutePath(payload.worktreePath) !== normalizeAbsolutePath(currentWorktreePath)
+        normalizeRuntimePathForComparison(payload.worktreePath) !==
+        normalizeRuntimePathForComparison(currentWorktreePath)
       ) {
         return
       }
@@ -169,13 +191,19 @@ export function useFileExplorerWatch({
       let needsFullRefresh = false
 
       for (const evt of payload.events) {
-        const normalizedPath = normalizeAbsolutePath(evt.absolutePath)
-
         if (evt.kind === 'overflow') {
           needsFullRefresh = true
           break
         }
 
+        const normalizedPath = canonicalizeFileExplorerWatchPath(
+          currentWorktreePath,
+          evt.absolutePath
+        )
+        if (!normalizedPath) {
+          continue
+        }
+
         if (evt.kind === 'delete') {
           // Why: for delete events, isDirectory is undefined from the watcher
           // (the path no longer exists). Infer from dirCache: if the deleted
@@ -193,27 +221,27 @@ export function useFileExplorerWatch({
 
           // Clear selectedPath if it points into the deleted subtree
           setSelectedPath((prev) => {
-            if (prev && normalizeAbsolutePath(prev) === normalizedPath) {
-              return null
-            }
             if (
               prev &&
-              wasDirectory &&
-              normalizeAbsolutePath(prev).startsWith(`${normalizedPath}/`)
+              normalizeRuntimePathForComparison(prev) ===
+                normalizeRuntimePathForComparison(normalizedPath)
             ) {
               return null
             }
+            if (prev && wasDirectory && isPathInsideOrEqual(normalizedPath, prev)) {
+              return null
+            }
             return prev
           })
 
           // Invalidate the parent directory
-          const parent = normalizeAbsolutePath(dirname(normalizedPath))
+          const parent = normalizeExplorerAbsolutePath(dirname(normalizedPath))
           if (parent in cache) {
             dirsToRefresh.add(parent)
           }
         } else if (evt.kind === 'create') {
           // Invalidate the parent directory
-          const parent = normalizeAbsolutePath(dirname(normalizedPath))
+          const parent = normalizeExplorerAbsolutePath(dirname(normalizedPath))
           if (parent in cache) {
             dirsToRefresh.add(parent)
           }
@@ -239,7 +267,7 @@ export function useFileExplorerWatch({
       for (const dirPath of dirsToRefresh) {
         // Check the dir is the root or an expanded directory or already in cache
         if (
-          dirPath === normalizeAbsolutePath(currentWorktreePath) ||
+          dirPath === normalizeExplorerAbsolutePath(currentWorktreePath) ||
           exp.has(dirPath) ||
           dirPath in dirCacheRef.current
         ) {
@@ -271,14 +299,52 @@ export function useFileExplorerWatch({
       processPayload(payload)
     }
 
-    const unsubscribeListener = window.api.fs.onFsChanged(handleFsChanged)
+    let disposed = false
+    let unsubscribeListener: (() => void) | null = null
+    if (activeRuntimeEnvironmentId?.trim() && activeWorktreeId) {
+      // Why: remote runtime watch events do not enter the local Electron
+      // fs:changed bus, so the Explorer subscribes directly while it is mounted.
+      void subscribeRuntimeFileChanges(
+        {
+          settings: { activeRuntimeEnvironmentId },
+          worktreeId: activeWorktreeId,
+          worktreePath,
+          connectionId: undefined
+        },
+        handleFsChanged,
+        (err) => {
+          console.warn('[filesystem-watch] failed to subscribe to runtime file changes', {
+            worktreeId: activeWorktreeId,
+            worktreePath,
+            error: err.message
+          })
+        }
+      )
+        .then((unsubscribe) => {
+          if (disposed) {
+            unsubscribe()
+            return
+          }
+          unsubscribeListener = unsubscribe
+        })
+        .catch((err) => {
+          console.warn('[filesystem-watch] failed to subscribe to runtime file changes', {
+            worktreeId: activeWorktreeId,
+            worktreePath,
+            error: err instanceof Error ? err.message : String(err)
+          })
+        })
+    } else {
+      unsubscribeListener = window.api.fs.onFsChanged(handleFsChanged)
+    }
 
     return () => {
-      unsubscribeListener()
+      disposed = true
+      unsubscribeListener?.()
       deferredRef.current = []
       processPayloadRef.current = null
     }
-  }, [worktreePath, activeWorktreeId, setDirCache, setSelectedPath])
+  }, [worktreePath, activeWorktreeId, activeRuntimeEnvironmentId, setDirCache, setSelectedPath])
 
   // ── Flush deferred events when interaction ends ────────────────────
   useEffect(() => {
diff --git a/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts b/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts
index 89121ff88bc..a871ca1a4e7 100644
--- a/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts
+++ b/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts
@@ -48,7 +48,9 @@ async function usePollingOnce(status: GitStatusResult): Promise<PollState> {
   })
 
   vi.doMock('@/store', () => ({
-    useAppStore: (selector: (s: PollState) => unknown) => selector(state)
+    useAppStore: Object.assign((selector: (s: PollState) => unknown) => selector(state), {
+      getState: () => ({ settings: null })
+    })
   }))
 
   vi.doMock('@/store/selectors', () => ({
@@ -78,7 +80,9 @@ async function usePollingOnce(status: GitStatusResult): Promise<PollState> {
 
   const { useGitStatusPolling: runPolling } = await import('./useGitStatusPolling')
   GitStatusPollingHarness({ runPolling })
-  await Promise.resolve()
+  await vi.waitFor(() => {
+    expect(state.setGitStatus).toHaveBeenCalled()
+  })
 
   return state
 }
diff --git a/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts b/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts
index 4ef3c3770e9..07874284dfe 100644
--- a/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts
+++ b/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts
@@ -4,6 +4,7 @@ import { useActiveWorktree, useAllWorktrees, useRepoById, useRepoMap } from '@/s
 import type { GitConflictOperation } from '../../../../shared/types'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import { getConnectionId } from '@/lib/connection-context'
+import { getRuntimeGitConflictOperation } from '@/runtime/runtime-git-client'
 import { refreshGitStatusForWorktree } from './git-status-refresh'
 
 const POLL_INTERVAL_MS = 3000
@@ -54,6 +55,7 @@ export function useGitStatusPolling(): void {
     try {
       const connectionId = getConnectionId(activeWorktreeId) ?? undefined
       await refreshGitStatusForWorktree({
+        settings: useAppStore.getState().settings,
         worktreeId: activeWorktreeId,
         worktreePath,
         connectionId,
@@ -109,7 +111,9 @@ export function useGitStatusPolling(): void {
     const pollStale = async (): Promise<void> => {
       for (const { id, path } of staleConflictWorktrees) {
         try {
-          const op = (await window.api.git.conflictOperation({
+          const op = (await getRuntimeGitConflictOperation({
+            settings: useAppStore.getState().settings,
+            worktreeId: id,
             worktreePath: path,
             connectionId: getConnectionId(id) ?? undefined
           })) as GitConflictOperation
diff --git a/src/renderer/src/components/settings/BaseRefPicker.tsx b/src/renderer/src/components/settings/BaseRefPicker.tsx
index b5e586f317e..e3c8ddd67d9 100644
--- a/src/renderer/src/components/settings/BaseRefPicker.tsx
+++ b/src/renderer/src/components/settings/BaseRefPicker.tsx
@@ -2,6 +2,11 @@ import { useEffect, useState } from 'react'
 import { ScrollArea } from '../ui/scroll-area'
 import { Button } from '../ui/button'
 import { Input } from '../ui/input'
+import { useAppStore } from '@/store'
+import {
+  getRuntimeRepoBaseRefDefault,
+  searchRuntimeRepoBaseRefs
+} from '@/runtime/runtime-repo-client'
 
 type BaseRefPickerProps = {
   repoId: string
@@ -16,6 +21,9 @@ export function BaseRefPicker({
   onSelect,
   onUsePrimary
 }: BaseRefPickerProps): React.JSX.Element {
+  const activeRuntimeEnvironmentId = useAppStore(
+    (state) => state.settings?.activeRuntimeEnvironmentId ?? null
+  )
   // Why: null until the IPC resolves (or when the repo has no default base ref
   // available). We avoid seeding with 'origin/main' because that would display
   // a fabricated default in repos that don't actually have origin/main.
@@ -34,7 +42,7 @@ export function BaseRefPicker({
 
     const loadDefaultBaseRef = async (): Promise<void> => {
       try {
-        const result = await window.api.repos.getBaseRefDefault({ repoId })
+        const result = await getRuntimeRepoBaseRefDefault({ activeRuntimeEnvironmentId }, repoId)
         if (!stale) {
           setDefaultBaseRef(result.defaultBaseRef)
           setRemoteCount(result.remoteCount)
@@ -60,7 +68,7 @@ export function BaseRefPicker({
     return () => {
       stale = true
     }
-  }, [repoId])
+  }, [activeRuntimeEnvironmentId, repoId])
 
   useEffect(() => {
     const trimmedQuery = baseRefQuery.trim()
@@ -74,12 +82,7 @@ export function BaseRefPicker({
     setIsSearchingBaseRefs(true)
 
     const timer = window.setTimeout(() => {
-      void window.api.repos
-        .searchBaseRefs({
-          repoId,
-          query: trimmedQuery,
-          limit: 20
-        })
+      void searchRuntimeRepoBaseRefs({ activeRuntimeEnvironmentId }, repoId, trimmedQuery, 20)
         .then((results) => {
           if (!stale) {
             setBaseRefResults(results)
@@ -102,7 +105,7 @@ export function BaseRefPicker({
       stale = true
       window.clearTimeout(timer)
     }
-  }, [baseRefQuery, repoId])
+  }, [activeRuntimeEnvironmentId, baseRefQuery, repoId])
 
   const effectiveBaseRef = currentBaseRef ?? defaultBaseRef
 
diff --git a/src/renderer/src/components/settings/ManageSessionsSection.tsx b/src/renderer/src/components/settings/ManageSessionsSection.tsx
index 92148821647..8efeafa903d 100644
--- a/src/renderer/src/components/settings/ManageSessionsSection.tsx
+++ b/src/renderer/src/components/settings/ManageSessionsSection.tsx
@@ -96,6 +96,9 @@ function getConfirmCopy(confirm: PendingConfirm): {
 }
 
 export function ManageSessionsSection(): React.JSX.Element {
+  const activeRuntimeEnvironmentId = useAppStore(
+    (s) => s.settings?.activeRuntimeEnvironmentId ?? null
+  )
   const [sessions, setSessions] = useState<PtyManagementSession[]>([])
   const [isRefreshing, setIsRefreshing] = useState(true)
   const [hasLoadedOnce, setHasLoadedOnce] = useState(false)
@@ -176,6 +179,14 @@ export function ManageSessionsSection(): React.JSX.Element {
   }, [])
 
   const refresh = useCallback(async (): Promise<PtyManagementSession[]> => {
+    if (activeRuntimeEnvironmentId?.trim()) {
+      if (isMounted.current) {
+        setSessions([])
+        setIsRefreshing(false)
+        setHasLoadedOnce(true)
+      }
+      return []
+    }
     setIsRefreshing(true)
     try {
       const result = await window.api.pty.management.listSessions()
@@ -198,7 +209,7 @@ export function ManageSessionsSection(): React.JSX.Element {
         setHasLoadedOnce(true)
       }
     }
-  }, [])
+  }, [activeRuntimeEnvironmentId])
 
   useEffect(() => {
     void refresh()
@@ -275,6 +286,29 @@ export function ManageSessionsSection(): React.JSX.Element {
   const copy = useMemo(() => getConfirmCopy(confirm), [confirm])
   const isBusy = busyKind !== null || daemonActions.isBusy
 
+  if (activeRuntimeEnvironmentId?.trim()) {
+    return (
+      <section className="space-y-4">
+        <div className="space-y-1">
+          <h3 className="text-sm font-semibold">Manage Sessions</h3>
+          <p className="text-xs text-muted-foreground">
+            Session management is unavailable while a remote runtime server is active.
+          </p>
+        </div>
+        <SearchableSetting
+          title={MANAGE_SESSIONS_SEARCH_ENTRIES[0].title}
+          description={MANAGE_SESSIONS_SEARCH_ENTRIES[0].description}
+          keywords={MANAGE_SESSIONS_SEARCH_ENTRIES[0].keywords}
+          className="space-y-3"
+        >
+          <div className="rounded-lg border border-border/60 px-3 py-3 text-xs text-muted-foreground">
+            Switch back to the local runtime to restart or kill local daemon sessions.
+          </div>
+        </SearchableSetting>
+      </section>
+    )
+  }
+
   return (
     <section className="space-y-4">
       <div className="space-y-1">
diff --git a/src/renderer/src/components/settings/RepositoryHooksSection.tsx b/src/renderer/src/components/settings/RepositoryHooksSection.tsx
index fc5b9505638..6e6cbf23fc9 100644
--- a/src/renderer/src/components/settings/RepositoryHooksSection.tsx
+++ b/src/renderer/src/components/settings/RepositoryHooksSection.tsx
@@ -5,6 +5,8 @@ import { AlertTriangle } from 'lucide-react'
 import { toast } from 'sonner'
 import { Button } from '../ui/button'
 import { SearchableSetting } from './SearchableSetting'
+import { useAppStore } from '@/store'
+import { readRuntimeIssueCommand, writeRuntimeIssueCommand } from '@/runtime/runtime-hooks-client'
 
 type RepositoryHooksSectionProps = {
   repo: Repo
@@ -154,6 +156,7 @@ export function RepositoryHooksSection({
   onClearLegacyHooks,
   onUpdateSetupRunPolicy
 }: RepositoryHooksSectionProps): React.JSX.Element {
+  const settings = useAppStore((s) => s.settings)
   // Why: distinguish "file has unrecognised top-level keys" from "file is
   // genuinely malformed" so users see a helpful update prompt instead of a
   // confusing parse-error when a newer Orca version adds keys to `orca.yaml`.
@@ -192,8 +195,7 @@ export function RepositoryHooksSection({
     // Why: settings only edit the local override, but we still need to know
     // whether `orca.yaml` defines a shared default so the helper copy can
     // explain what happens when the override is blank.
-    void window.api.hooks
-      .readIssueCommand({ repoId })
+    void readRuntimeIssueCommand(settings, repoId)
       .then((result) => {
         if (cancelled) {
           return
@@ -215,18 +217,18 @@ export function RepositoryHooksSection({
       cancelled = true
       const draft = issueCommandDraftRef.current.trim()
       if (draft !== lastCommittedIssueCommandRef.current) {
-        void window.api.hooks.writeIssueCommand({ repoId, content: draft }).catch((err) => {
+        void writeRuntimeIssueCommand(settings, repoId, draft).catch((err) => {
           console.error('[RepositoryHooksSection] Failed to save issue command on unmount:', err)
         })
       }
     }
-  }, [repo.id])
+  }, [repo.id, settings])
 
   const commitIssueCommand = useCallback(async (): Promise<void> => {
     const trimmed = issueCommandDraft.trim()
     setIssueCommandDraft(trimmed)
     try {
-      await window.api.hooks.writeIssueCommand({ repoId: repo.id, content: trimmed })
+      await writeRuntimeIssueCommand(settings, repo.id, trimmed)
       lastCommittedIssueCommandRef.current = trimmed
       setIssueCommandSaveError(null)
     } catch (err) {
@@ -235,7 +237,7 @@ export function RepositoryHooksSection({
       setIssueCommandSaveError(message)
       toast.error(message)
     }
-  }, [issueCommandDraft, repo.id])
+  }, [issueCommandDraft, repo.id, settings])
 
   return (
     <section className="space-y-6">
diff --git a/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx b/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
new file mode 100644
index 00000000000..b6254ba3226
--- /dev/null
+++ b/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
@@ -0,0 +1,413 @@
+import { Loader2, Plus, RefreshCw, Trash2 } from 'lucide-react'
+import { useEffect, useState } from 'react'
+import { toast } from 'sonner'
+import type { GlobalSettings } from '../../../../shared/types'
+import type { PublicKnownRuntimeEnvironment } from '../../../../shared/runtime-environments'
+import { Button } from '../ui/button'
+import { Input } from '../ui/input'
+import { Label } from '../ui/label'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+import { SearchableSetting } from './SearchableSetting'
+import type { SettingsSearchEntry } from './settings-search'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '../ui/dialog'
+
+const LOCAL_RUNTIME_VALUE = '__local__'
+
+export const RUNTIME_ENVIRONMENTS_SEARCH_ENTRY: SettingsSearchEntry = {
+  title: 'Active Server',
+  description: 'Choose local desktop or a saved remote Orca server.',
+  keywords: [
+    'runtime',
+    'environment',
+    'server',
+    'client',
+    'remote',
+    'pairing',
+    'cloud',
+    'vm',
+    'dev box'
+  ]
+}
+
+type RuntimeEnvironmentsPaneProps = {
+  settings: GlobalSettings
+  switchRuntimeEnvironment: (environmentId: string | null) => Promise<boolean>
+}
+
+export function RuntimeEnvironmentsPane({
+  settings,
+  switchRuntimeEnvironment
+}: RuntimeEnvironmentsPaneProps): React.JSX.Element {
+  const [environments, setEnvironments] = useState<PublicKnownRuntimeEnvironment[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+  const [isSaving, setIsSaving] = useState(false)
+  const [switchingValue, setSwitchingValue] = useState<string | null>(null)
+  const [removingId, setRemovingId] = useState<string | null>(null)
+  const [pendingSwitchValue, setPendingSwitchValue] = useState<string | null>(null)
+  const [pendingRemove, setPendingRemove] = useState<PublicKnownRuntimeEnvironment | null>(null)
+  const [switchError, setSwitchError] = useState<string | null>(null)
+  const [removeError, setRemoveError] = useState<string | null>(null)
+  const [name, setName] = useState('')
+  const [pairingCode, setPairingCode] = useState('')
+  const activeValue = settings.activeRuntimeEnvironmentId ?? LOCAL_RUNTIME_VALUE
+  const isBusy = isSaving || switchingValue !== null || removingId !== null
+  const removingActiveServer = pendingRemove?.id === settings.activeRuntimeEnvironmentId
+
+  const loadEnvironments = async (): Promise<void> => {
+    setIsLoading(true)
+    try {
+      setEnvironments(await window.api.runtimeEnvironments.list())
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Failed to load runtime environments.')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    void loadEnvironments()
+  }, [])
+
+  const addEnvironment = async (): Promise<void> => {
+    const trimmedName = name.trim()
+    const trimmedPairingCode = pairingCode.trim()
+    if (!trimmedName || !trimmedPairingCode) {
+      toast.error('Name and pairing code are required.')
+      return
+    }
+    const duplicate = environments.find(
+      (environment) => environment.name.trim().toLowerCase() === trimmedName.toLowerCase()
+    )
+    if (duplicate) {
+      toast.error(`A server named "${duplicate.name}" already exists.`)
+      return
+    }
+    setIsSaving(true)
+    try {
+      const result = await window.api.runtimeEnvironments.addFromPairingCode({
+        name: trimmedName,
+        pairingCode: trimmedPairingCode
+      })
+      setName('')
+      setPairingCode('')
+      await loadEnvironments()
+      toast.success(`Saved ${result.environment.name}. Use Active Server to switch when ready.`)
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Failed to save runtime environment.')
+    } finally {
+      setIsSaving(false)
+    }
+  }
+
+  const removeEnvironment = async (
+    environment: PublicKnownRuntimeEnvironment
+  ): Promise<boolean> => {
+    setRemovingId(environment.id)
+    setRemoveError(null)
+    try {
+      if (settings.activeRuntimeEnvironmentId === environment.id) {
+        const switched = await switchRuntimeEnvironment(null)
+        if (!switched) {
+          setRemoveError('Could not switch to Local desktop. Fix the issue and try again.')
+          return false
+        }
+      }
+      await window.api.runtimeEnvironments.remove({ selector: environment.id })
+      await loadEnvironments()
+      toast.success(`Removed ${environment.name}.`)
+      return true
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : 'Failed to remove runtime environment.'
+      setRemoveError(message)
+      toast.error(message)
+      return false
+    } finally {
+      setRemovingId(null)
+    }
+  }
+
+  const switchToValue = async (value: string): Promise<boolean> => {
+    setSwitchingValue(value)
+    setSwitchError(null)
+    try {
+      const switched = await switchRuntimeEnvironment(value === LOCAL_RUNTIME_VALUE ? null : value)
+      if (switched) {
+        toast.success(`Switched to ${getEnvironmentLabel(value)}.`)
+        return true
+      }
+      setSwitchError('Could not switch servers. Fix the issue and try again.')
+      return false
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to switch servers.'
+      setSwitchError(message)
+      toast.error(message)
+      return false
+    } finally {
+      setSwitchingValue(null)
+    }
+  }
+
+  const getEnvironmentLabel = (value: string): string => {
+    if (value === LOCAL_RUNTIME_VALUE) {
+      return 'Local desktop'
+    }
+    return environments.find((environment) => environment.id === value)?.name ?? 'remote server'
+  }
+
+  return (
+    <SearchableSetting
+      title={RUNTIME_ENVIRONMENTS_SEARCH_ENTRY.title}
+      description={RUNTIME_ENVIRONMENTS_SEARCH_ENTRY.description}
+      keywords={RUNTIME_ENVIRONMENTS_SEARCH_ENTRY.keywords}
+      className="space-y-4 px-1 py-2"
+    >
+      <div className="space-y-2">
+        <div className="space-y-1">
+          <Label id="runtime-active-server-label">Active Server</Label>
+          <p className="text-xs text-muted-foreground">
+            Local keeps today&apos;s desktop behavior. Saved servers route supported client calls
+            through the remote runtime.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-2">
+          <Select
+            value={activeValue}
+            onValueChange={(value) => {
+              if (value !== activeValue) {
+                setSwitchError(null)
+                setPendingSwitchValue(value)
+              }
+            }}
+            disabled={isBusy}
+          >
+            <SelectTrigger
+              size="sm"
+              className="min-w-[260px]"
+              aria-labelledby="runtime-active-server-label"
+            >
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value={LOCAL_RUNTIME_VALUE}>Local desktop</SelectItem>
+              {environments.map((environment) => (
+                <SelectItem key={environment.id} value={environment.id}>
+                  {environment.name}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="gap-1.5"
+            onClick={() => void loadEnvironments()}
+            disabled={isLoading || isBusy}
+          >
+            {isLoading ? <Loader2 className="animate-spin" /> : <RefreshCw />}
+            Refresh
+          </Button>
+        </div>
+      </div>
+
+      <div className="grid gap-2 sm:grid-cols-[minmax(0,180px)_minmax(0,1fr)_auto]">
+        <div className="space-y-1">
+          <Label htmlFor="runtime-server-name">Server name</Label>
+          <Input
+            id="runtime-server-name"
+            value={name}
+            onChange={(event) => setName(event.target.value)}
+            placeholder="Dev box"
+            className="h-8 text-xs"
+          />
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor="runtime-server-pairing-code">Pairing code</Label>
+          <Input
+            id="runtime-server-pairing-code"
+            aria-describedby="runtime-server-pairing-code-help"
+            value={pairingCode}
+            onChange={(event) => setPairingCode(event.target.value)}
+            placeholder="orca://pair#..."
+            className="h-8 min-w-0 font-mono text-xs"
+          />
+          <p id="runtime-server-pairing-code-help" className="text-xs text-muted-foreground">
+            Run <span className="font-mono">orca serve --pairing-address &lt;host&gt;</span> on the
+            server and paste the printed pairing URL.
+          </p>
+        </div>
+        <Button
+          type="button"
+          size="sm"
+          className="mt-5 gap-1.5"
+          onClick={() => void addEnvironment()}
+          disabled={isBusy || !name.trim() || !pairingCode.trim()}
+        >
+          {isSaving ? <Loader2 className="animate-spin" /> : <Plus />}
+          Add
+        </Button>
+      </div>
+
+      <div className="rounded-lg border border-border/50">
+        {environments.length === 0 ? (
+          <div className="px-3 py-4 text-sm text-muted-foreground">No saved servers.</div>
+        ) : (
+          <div className="divide-y divide-border/50">
+            {environments.map((environment) => (
+              <div
+                key={environment.id}
+                className="flex items-center justify-between gap-3 px-3 py-2"
+              >
+                <div className="min-w-0">
+                  <div className="truncate text-sm font-medium">{environment.name}</div>
+                  <div className="truncate font-mono text-xs text-muted-foreground">
+                    {environment.endpoints[0]?.endpoint ?? 'No endpoint'}
+                  </div>
+                </div>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-sm"
+                  onClick={() => {
+                    setRemoveError(null)
+                    setPendingRemove(environment)
+                  }}
+                  disabled={isBusy}
+                  aria-label={`Remove ${environment.name}`}
+                >
+                  <Trash2 />
+                </Button>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <Dialog
+        open={pendingSwitchValue !== null}
+        onOpenChange={(open) => {
+          if (!open && switchingValue === null) {
+            setSwitchError(null)
+            setPendingSwitchValue(null)
+          }
+        }}
+      >
+        <DialogContent className="max-w-sm sm:max-w-sm" showCloseButton={false}>
+          <DialogHeader>
+            <DialogTitle className="text-sm">Switch Server</DialogTitle>
+            <DialogDescription>
+              Orca will close remote terminals and browser tabs from the current server before
+              loading projects from the next server.
+            </DialogDescription>
+          </DialogHeader>
+          {pendingSwitchValue ? (
+            <div className="rounded-md border border-border/70 bg-muted/35 px-3 py-2 text-xs">
+              <div className="text-muted-foreground">Switch to</div>
+              <div className="mt-0.5 truncate font-medium">
+                {getEnvironmentLabel(pendingSwitchValue)}
+              </div>
+            </div>
+          ) : null}
+          {switchError ? <p className="text-sm text-destructive">{switchError}</p> : null}
+          <DialogFooter>
+            <Button
+              variant="outline"
+              onClick={() => {
+                setSwitchError(null)
+                setPendingSwitchValue(null)
+              }}
+              disabled={switchingValue !== null}
+            >
+              Cancel
+            </Button>
+            <Button
+              onClick={() => {
+                const value = pendingSwitchValue
+                if (!value) {
+                  return
+                }
+                void switchToValue(value).then((switched) => {
+                  if (switched) {
+                    setPendingSwitchValue(null)
+                  }
+                })
+              }}
+              disabled={switchingValue !== null}
+            >
+              {switchingValue !== null ? <Loader2 className="animate-spin" /> : null}
+              Switch
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog
+        open={pendingRemove !== null}
+        onOpenChange={(open) => {
+          if (!open && removingId === null) {
+            setRemoveError(null)
+            setPendingRemove(null)
+          }
+        }}
+      >
+        <DialogContent className="max-w-sm sm:max-w-sm" showCloseButton={false}>
+          <DialogHeader>
+            <DialogTitle className="text-sm">Remove Server</DialogTitle>
+            <DialogDescription>
+              {removingActiveServer
+                ? 'Removing the active server first switches Orca back to Local desktop and closes remote terminals and browser tabs for that server.'
+                : 'This removes the saved server from Orca. It does not change the active server.'}
+            </DialogDescription>
+          </DialogHeader>
+          {pendingRemove ? (
+            <div className="rounded-md border border-border/70 bg-muted/35 px-3 py-2 text-xs">
+              <div className="truncate font-medium">{pendingRemove.name}</div>
+              <div className="mt-0.5 truncate font-mono text-muted-foreground">
+                {pendingRemove.endpoints[0]?.endpoint ?? 'No endpoint'}
+              </div>
+            </div>
+          ) : null}
+          {removeError ? <p className="text-sm text-destructive">{removeError}</p> : null}
+          <DialogFooter>
+            <Button
+              variant="outline"
+              onClick={() => {
+                setRemoveError(null)
+                setPendingRemove(null)
+              }}
+              disabled={removingId !== null}
+            >
+              Cancel
+            </Button>
+            <Button
+              variant="destructive"
+              onClick={() => {
+                const environment = pendingRemove
+                if (!environment) {
+                  return
+                }
+                void removeEnvironment(environment).then((removed) => {
+                  if (removed) {
+                    setPendingRemove(null)
+                  }
+                })
+              }}
+              disabled={removingId !== null}
+            >
+              {removingId !== null ? <Loader2 className="animate-spin" /> : <Trash2 />}
+              Remove
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </SearchableSetting>
+  )
+}
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 4932313f9bf..9e0cc8cb531 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -4,6 +4,7 @@ import {
   BarChart3,
   Bell,
   Bot,
+  Cable,
   FlaskConical,
   GitBranch,
   Globe,
@@ -59,11 +60,16 @@ import {
 } from './DeveloperPermissionsPane'
 import { ComputerUsePane, COMPUTER_USE_PANE_SEARCH_ENTRIES } from './ComputerUsePane'
 import { MobileSettingsPane, MOBILE_SETTINGS_PANE_SEARCH_ENTRIES } from './MobileSettingsPane'
+import {
+  RuntimeEnvironmentsPane,
+  RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
+} from './RuntimeEnvironmentsPane'
 import { PrivacyPane } from './PrivacyPane'
 import { PRIVACY_PANE_SEARCH_ENTRIES } from './privacy-search'
 import { SettingsSidebar } from './SettingsSidebar'
 import { SettingsSection } from './SettingsSection'
 import { matchesSettingsSearch, type SettingsSearchEntry } from './settings-search'
+import { checkRuntimeHooks } from '@/runtime/runtime-hooks-client'
 
 type SettingsNavTarget =
   | 'general'
@@ -84,6 +90,7 @@ type SettingsNavTarget =
   | 'experimental'
   | 'agents'
   | 'orchestration'
+  | 'servers'
   | 'mobile'
   | 'repo'
 
@@ -173,6 +180,7 @@ function isEditableTarget(target: EventTarget | null): boolean {
 function Settings(): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
   const updateSettings = useAppStore((s) => s.updateSettings)
+  const switchRuntimeEnvironment = useAppStore((s) => s.switchRuntimeEnvironment)
   const fetchSettings = useAppStore((s) => s.fetchSettings)
   const closeSettingsPage = useAppStore((s) => s.closeSettingsPage)
   const repos = useAppStore((s) => s.repos)
@@ -355,7 +363,7 @@ function Settings(): React.JSX.Element {
             return [repo.id, { hasHooks: false, hooks: null, mayNeedUpdate: false }] as const
           }
           try {
-            const result = await window.api.hooks.check({ repoId: repo.id })
+            const result = await checkRuntimeHooks(settings, repo.id)
             return [repo.id, result] as const
           } catch {
             return [repo.id, { hasHooks: false, hooks: null, mayNeedUpdate: false }] as const
@@ -382,7 +390,7 @@ function Settings(): React.JSX.Element {
     return () => {
       stale = true
     }
-  }, [repos])
+  }, [repos, settings])
 
   const applyTheme = useCallback((theme: 'system' | 'dark' | 'light') => {
     applyDocumentTheme(theme)
@@ -455,6 +463,14 @@ function Settings(): React.JSX.Element {
         icon: Network,
         searchEntries: ORCHESTRATION_PANE_SEARCH_ENTRIES
       },
+      {
+        id: 'servers',
+        title: 'Servers',
+        description: 'Run this client locally or through a remote Orca server.',
+        icon: Server,
+        searchEntries: [RUNTIME_ENVIRONMENTS_SEARCH_ENTRY],
+        badge: 'Beta'
+      },
       {
         id: 'mobile',
         title: 'Mobile',
@@ -522,7 +538,7 @@ function Settings(): React.JSX.Element {
         id: 'ssh',
         title: 'SSH',
         description: 'Remote SSH connections.',
-        icon: Server,
+        icon: Cable,
         searchEntries: SSH_PANE_SEARCH_ENTRIES
       },
       {
@@ -826,6 +842,19 @@ function Settings(): React.JSX.Element {
                   <OrchestrationPane />
                 </SettingsSection>
 
+                <SettingsSection
+                  id="servers"
+                  title="Servers"
+                  badge="Beta"
+                  description="Run this desktop client locally or through a remote Orca server."
+                  searchEntries={[RUNTIME_ENVIRONMENTS_SEARCH_ENTRY]}
+                >
+                  <RuntimeEnvironmentsPane
+                    settings={settings}
+                    switchRuntimeEnvironment={switchRuntimeEnvironment}
+                  />
+                </SettingsSection>
+
                 <SettingsSection
                   id="mobile"
                   title="Mobile"
diff --git a/src/renderer/src/components/settings/WorktreeSymlinksSection.tsx b/src/renderer/src/components/settings/WorktreeSymlinksSection.tsx
index 59a7fcc620e..60dd9e42c79 100644
--- a/src/renderer/src/components/settings/WorktreeSymlinksSection.tsx
+++ b/src/renderer/src/components/settings/WorktreeSymlinksSection.tsx
@@ -6,6 +6,7 @@ import { Command, CommandEmpty, CommandInput, CommandItem, CommandList } from '.
 import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
 import { cn } from '@/lib/utils'
 import { SearchableSetting } from './SearchableSetting'
+import { useAppStore } from '@/store'
 
 type WorktreeSymlinksSectionProps = {
   repo: Repo
@@ -23,11 +24,16 @@ export function WorktreeSymlinksSection({
   const [open, setOpen] = useState(false)
   const [query, setQuery] = useState('')
   const [entries, setEntries] = useState<DirEntry[]>([])
+  const activeRuntimeEnvironmentId = useAppStore((s) => s.settings?.activeRuntimeEnvironmentId)
 
   const paths = repo.symlinkPaths ?? []
   const queryTrimmed = query.trim().replace(/^\/+/, '')
 
   useEffect(() => {
+    if (activeRuntimeEnvironmentId?.trim()) {
+      setEntries([])
+      return
+    }
     let cancelled = false
     void window.api.fs
       .readDir({ dirPath: repo.path, connectionId: repo.connectionId ?? undefined })
@@ -44,7 +50,7 @@ export function WorktreeSymlinksSection({
     return () => {
       cancelled = true
     }
-  }, [repo.path, repo.connectionId])
+  }, [activeRuntimeEnvironmentId, repo.path, repo.connectionId])
 
   const filtered = useMemo(() => {
     const q = queryTrimmed.toLowerCase()
diff --git a/src/renderer/src/components/sidebar/AddRepoCreateStep.tsx b/src/renderer/src/components/sidebar/AddRepoCreateStep.tsx
index 5678c9300a6..d24aeda7e0f 100644
--- a/src/renderer/src/components/sidebar/AddRepoCreateStep.tsx
+++ b/src/renderer/src/components/sidebar/AddRepoCreateStep.tsx
@@ -13,6 +13,7 @@ import { DialogHeader, DialogTitle, DialogDescription } from '@/components/ui/di
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import type { Repo } from '../../../../shared/types'
 
@@ -46,6 +47,12 @@ export function useCreateRepo(
   }, [])
 
   const handlePickParent = useCallback(async () => {
+    if (useAppStore.getState().settings?.activeRuntimeEnvironmentId?.trim()) {
+      // Why: the native folder picker returns a client-local path. Runtime
+      // project creation needs an explicit server parent path.
+      toast.error('Enter a server parent path.')
+      return
+    }
     const dir = await window.api.repos.pickDirectory()
     if (dir) {
       setCreateParent(dir)
@@ -63,11 +70,25 @@ export function useCreateRepo(
     setIsCreating(true)
     setCreateError(null)
     try {
-      const result = await window.api.repos.create({
-        parentPath,
-        name,
-        kind: createKind
-      })
+      const settings = useAppStore.getState().settings
+      const target = getActiveRuntimeTarget(settings)
+      const result =
+        target.kind === 'environment'
+          ? await callRuntimeRpc<{ repo: Repo } | { error: string }>(
+              target,
+              'repo.create',
+              {
+                parentPath,
+                name,
+                kind: createKind
+              },
+              { timeoutMs: 60_000 }
+            )
+          : await window.api.repos.create({
+              parentPath,
+              name,
+              kind: createKind
+            })
       // Why: if the user closed the dialog or clicked Back mid-create,
       // createGenRef was bumped by resetCreateState. Ignore stale results.
       if (gen !== createGenRef.current) {
@@ -147,6 +168,7 @@ export function useCreateRepo(
     createError,
     isCreating,
     setCreateName,
+    setCreateParent,
     setCreateKind,
     setCreateError,
     resetCreateState,
@@ -235,7 +257,9 @@ type CreateStepProps = {
   createKind: RepoKind
   createError: string | null
   isCreating: boolean
+  manualParentEntry?: boolean
   onNameChange: (value: string) => void
+  onParentChange: (value: string) => void
   onKindChange: (kind: RepoKind) => void
   onPickParent: () => void
   onCreate: () => void
@@ -247,7 +271,9 @@ export function CreateStep({
   createKind,
   createError,
   isCreating,
+  manualParentEntry = false,
   onNameChange,
+  onParentChange,
   onKindChange,
   onPickParent,
   onCreate
@@ -333,11 +359,21 @@ export function CreateStep({
           />
         </div>
 
-        {/* Location. The "Choose…" button morphs into a summary + Change once picked. */}
+        {/* Location. The local flow uses a folder picker; runtime servers need
+          manual server-path entry because the client cannot browse that filesystem yet. */}
         <div className="space-y-1">
           <span className="text-[11px] font-medium text-muted-foreground block">Location</span>
 
-          {createParent ? (
+          {manualParentEntry ? (
+            <Input
+              value={createParent}
+              onChange={(e) => onParentChange(e.target.value)}
+              placeholder="/home/user/projects"
+              className="h-11 text-sm font-mono"
+              disabled={isCreating}
+              spellCheck={false}
+            />
+          ) : createParent ? (
             <div className="group flex items-center gap-2.5 rounded-md border border-border bg-background/40 h-11 min-w-0 px-3 text-sm">
               <span className="shrink-0 inline-flex items-center justify-center size-7 rounded-md border border-border/70 bg-background/50 text-muted-foreground">
                 <Home className="size-3.5" />
diff --git a/src/renderer/src/components/sidebar/AddRepoDialog.tsx b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
index 7f207bf6224..1a83b4b45de 100644
--- a/src/renderer/src/components/sidebar/AddRepoDialog.tsx
+++ b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
@@ -11,12 +11,14 @@ import {
   DialogDescription
 } from '@/components/ui/dialog'
 import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { track } from '@/lib/telemetry'
 import { RemoteStep, CloneStep, useRemoteRepo } from './AddRepoSteps'
 import { CreateStep, useCreateRepo } from './AddRepoCreateStep'
 import { SetupStep } from './AddRepoSetupStep'
 import { getDefaultCloneParent } from './clone-defaults'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import type { Repo, Worktree } from '../../../../shared/types'
 
@@ -24,6 +26,7 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
   const activeModal = useAppStore((s) => s.activeModal)
   const closeModal = useAppStore((s) => s.closeModal)
   const addRepo = useAppStore((s) => s.addRepo)
+  const addRepoPath = useAppStore((s) => s.addRepoPath)
   const repos = useAppStore((s) => s.repos)
   const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
   const fetchWorktrees = useAppStore((s) => s.fetchWorktrees)
@@ -35,6 +38,8 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
   const [step, setStep] = useState<'add' | 'clone' | 'remote' | 'create' | 'setup'>('add')
   const [addedRepo, setAddedRepo] = useState<Repo | null>(null)
   const [isAdding, setIsAdding] = useState(false)
+  const [serverPath, setServerPath] = useState('')
+  const [isAddingServerPath, setIsAddingServerPath] = useState(false)
   const [cloneUrl, setCloneUrl] = useState('')
   const [cloneDestination, setCloneDestination] = useState('')
   const [isCloning, setIsCloning] = useState(false)
@@ -71,6 +76,7 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
     createError,
     isCreating,
     setCreateName,
+    setCreateParent,
     setCreateKind,
     setCreateError,
     resetCreateState,
@@ -95,15 +101,19 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
     if (cloneDestination) {
       return
     }
+    if (settings?.activeRuntimeEnvironmentId?.trim()) {
+      return
+    }
     if (!settings?.workspaceDir) {
       return
     }
     cloneStepAutoFilledRef.current = true
     setCloneDestination(getDefaultCloneParent(settings.workspaceDir))
-  }, [step, cloneDestination, settings?.workspaceDir])
+  }, [step, cloneDestination, settings?.activeRuntimeEnvironmentId, settings?.workspaceDir])
 
   const isOpen = activeModal === 'add-repo'
   const repoId = addedRepo?.id ?? ''
+  const isRuntimeEnvironmentActive = Boolean(settings?.activeRuntimeEnvironmentId?.trim())
 
   const worktrees = useMemo(() => {
     return worktreesByRepo[repoId] ?? []
@@ -127,6 +137,8 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
     setStep('add')
     setAddedRepo(null)
     setIsAdding(false)
+    setServerPath('')
+    setIsAddingServerPath(false)
     setCloneUrl('')
     setCloneDestination('')
     setIsCloning(false)
@@ -162,13 +174,42 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
     }
   }, [addRepo, fetchWorktrees, closeModal])
 
+  const handleAddServerPath = useCallback(
+    async (kind: 'git' | 'folder') => {
+      const path = serverPath.trim()
+      if (!path) {
+        return
+      }
+      setIsAddingServerPath(true)
+      try {
+        const repo = await addRepoPath(path, kind)
+        if (repo && isGitRepoKind(repo)) {
+          setAddedRepo(repo)
+          await fetchWorktrees(repo.id)
+          setStep('setup')
+        } else if (repo) {
+          closeModal()
+        }
+      } finally {
+        setIsAddingServerPath(false)
+      }
+    },
+    [addRepoPath, closeModal, fetchWorktrees, serverPath]
+  )
+
   const handlePickDestination = useCallback(async () => {
+    if (settings?.activeRuntimeEnvironmentId?.trim()) {
+      // Why: the native folder picker returns a client-local path. Runtime
+      // clone destinations must be typed as server paths.
+      toast.error('Enter a server path for the clone destination.')
+      return
+    }
     const dir = await window.api.repos.pickDirectory()
     if (dir) {
       setCloneDestination(dir)
       setCloneError(null)
     }
-  }, [])
+  }, [settings?.activeRuntimeEnvironmentId])
 
   const handleClone = useCallback(async () => {
     const trimmedUrl = cloneUrl.trim()
@@ -180,10 +221,24 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
     setCloneError(null)
     setCloneProgress(null)
     try {
-      const repo = (await window.api.repos.clone({
-        url: trimmedUrl,
-        destination: cloneDestination.trim()
-      })) as Repo
+      const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+      const repo =
+        target.kind === 'environment'
+          ? (
+              await callRuntimeRpc<{ repo: Repo }>(
+                target,
+                'repo.clone',
+                {
+                  url: trimmedUrl,
+                  destination: cloneDestination.trim()
+                },
+                { timeoutMs: 10 * 60_000 }
+              )
+            ).repo
+          : ((await window.api.repos.clone({
+              url: trimmedUrl,
+              destination: cloneDestination.trim()
+            })) as Repo)
       // Why: if the user closed the dialog or clicked Back during the clone,
       // cloneGenRef will have been bumped by resetState. Ignore this stale result.
       if (gen !== cloneGenRef.current) {
@@ -310,7 +365,76 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
           </div>
         </div>
 
-        {step === 'add' ? (
+        {step === 'add' && isRuntimeEnvironmentActive ? (
+          <>
+            <DialogHeader>
+              <DialogTitle>Add a server project</DialogTitle>
+              <DialogDescription>
+                Add a Git repository or folder that already exists on the selected runtime server.
+              </DialogDescription>
+            </DialogHeader>
+
+            <div className="space-y-3 pt-2">
+              <div className="space-y-1">
+                <label
+                  htmlFor="server-project-path"
+                  className="text-[11px] font-medium text-muted-foreground block"
+                >
+                  Server path
+                </label>
+                <Input
+                  id="server-project-path"
+                  value={serverPath}
+                  onChange={(event) => setServerPath(event.target.value)}
+                  placeholder="/home/user/project"
+                  className="h-11 text-sm font-mono"
+                  disabled={isAddingServerPath}
+                  autoFocus
+                  spellCheck={false}
+                />
+              </div>
+              <div className="grid grid-cols-2 gap-2">
+                <Button
+                  onClick={() => void handleAddServerPath('git')}
+                  disabled={!serverPath.trim() || isAddingServerPath}
+                  className="h-10"
+                >
+                  Add Git Project
+                </Button>
+                <Button
+                  onClick={() => void handleAddServerPath('folder')}
+                  disabled={!serverPath.trim() || isAddingServerPath}
+                  variant="outline"
+                  className="h-10"
+                >
+                  Open as Folder
+                </Button>
+              </div>
+              <div className="flex items-center justify-center gap-4 pt-1">
+                <button
+                  type="button"
+                  onClick={() => {
+                    setCloneError(null)
+                    setStep('clone')
+                  }}
+                  className="text-xs text-muted-foreground hover:text-foreground transition-colors cursor-pointer rounded focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
+                >
+                  Clone into server path
+                </button>
+                <button
+                  type="button"
+                  onClick={() => {
+                    setCreateError(null)
+                    setStep('create')
+                  }}
+                  className="text-xs text-muted-foreground hover:text-foreground transition-colors cursor-pointer rounded focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
+                >
+                  Create on server
+                </button>
+              </div>
+            </div>
+          </>
+        ) : step === 'add' ? (
           <>
             <DialogHeader>
               <DialogTitle>Add a project</DialogTitle>
@@ -411,6 +535,7 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
             cloneError={cloneError}
             cloneProgress={cloneProgress}
             isCloning={isCloning}
+            disableDestinationPicker={isRuntimeEnvironmentActive}
             onUrlChange={(value) => {
               setCloneUrl(value)
               setCloneError(null)
@@ -429,10 +554,15 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
             createKind={createKind}
             createError={createError}
             isCreating={isCreating}
+            manualParentEntry={isRuntimeEnvironmentActive}
             onNameChange={(value) => {
               setCreateName(value)
               setCreateError(null)
             }}
+            onParentChange={(value) => {
+              setCreateParent(value)
+              setCreateError(null)
+            }}
             onKindChange={(kind) => {
               setCreateKind(kind)
               setCreateError(null)
diff --git a/src/renderer/src/components/sidebar/AddRepoSteps.tsx b/src/renderer/src/components/sidebar/AddRepoSteps.tsx
index a40c23c1400..aaf6eb78aee 100644
--- a/src/renderer/src/components/sidebar/AddRepoSteps.tsx
+++ b/src/renderer/src/components/sidebar/AddRepoSteps.tsx
@@ -306,6 +306,7 @@ type CloneStepProps = {
   cloneError: string | null
   cloneProgress: { phase: string; percent: number } | null
   isCloning: boolean
+  disableDestinationPicker?: boolean
   onUrlChange: (value: string) => void
   onDestChange: (value: string) => void
   onPickDestination: () => void
@@ -318,6 +319,7 @@ export function CloneStep({
   cloneError,
   cloneProgress,
   isCloning,
+  disableDestinationPicker = false,
   onUrlChange,
   onDestChange,
   onPickDestination,
@@ -369,7 +371,8 @@ export function CloneStep({
               size="sm"
               className="h-8 px-2 shrink-0"
               onClick={onPickDestination}
-              disabled={isCloning}
+              disabled={isCloning || disableDestinationPicker}
+              title={disableDestinationPicker ? 'Enter a server path manually' : 'Choose folder'}
             >
               <Folder className="size-3.5" />
             </Button>
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.tsx b/src/renderer/src/components/sidebar/WorktreeCard.tsx
index e9f6a69d4f1..646506caf78 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.tsx
@@ -2,6 +2,7 @@
 import React, { useEffect, useMemo, useCallback, useState } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import { useAppStore } from '@/store'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
 import { Badge } from '@/components/ui/badge'
 import { Tooltip, TooltipTrigger, TooltipContent } from '@/components/ui/tooltip'
 import {
@@ -74,6 +75,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
   const openModal = useAppStore((s) => s.openModal)
   const updateWorktreeMeta = useAppStore((s) => s.updateWorktreeMeta)
   const fetchHostedReviewForBranch = useAppStore((s) => s.fetchHostedReviewForBranch)
+  const settings = useAppStore((s) => s.settings)
   const fetchIssue = useAppStore((s) => s.fetchIssue)
   const cardProps = useAppStore((s) => s.worktreeCardProperties)
   const handleEditIssue = useCallback(
@@ -175,7 +177,8 @@ const WorktreeCard = React.memo(function WorktreeCard({
 
   const branch = branchDisplayName(worktree.branch)
   const isFolder = repo ? isFolderRepo(repo) : false
-  const hostedReviewCacheKey = repo && branch ? `${repo.path}::${branch}` : ''
+  const hostedReviewCacheKey =
+    repo && branch ? getHostedReviewCacheKey(repo.path, branch, settings) : ''
   const issueCacheKey = repo && worktree.linkedIssue ? `${repo.path}::${worktree.linkedIssue}` : ''
 
   // Subscribe to ONLY the specific cache entry, not entire review/issue caches.
diff --git a/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx b/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
index 59ac54b5245..31b9f77245b 100644
--- a/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
@@ -27,6 +27,7 @@ import type { Worktree } from '../../../../shared/types'
 import { isFolderRepo } from '../../../../shared/repo-kind'
 import { runWorktreeBatchDelete, runWorktreeDelete } from './delete-worktree-flow'
 import { runSleepWorktrees } from './sleep-worktree-flow'
+import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
 
 type Props = {
   worktree: Worktree
@@ -100,8 +101,16 @@ const WorktreeContextMenu = React.memo(function WorktreeContextMenu({
   }, [])
 
   const handleOpenInFinder = useCallback(() => {
+    if (
+      isLocalPathOpenBlocked(useAppStore.getState().settings, {
+        connectionId: repo?.connectionId ?? null
+      })
+    ) {
+      showLocalPathOpenBlockedToast()
+      return
+    }
     window.api.shell.openPath(worktree.path)
-  }, [worktree.path])
+  }, [repo?.connectionId, worktree.path])
 
   const handleCopyPath = useCallback(() => {
     window.api.ui.writeClipboardText(worktree.path)
diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index a58b538d123..c423a029b69 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -45,6 +45,7 @@ import {
   pruneWorktreeSelection,
   updateWorktreeSelection
 } from './worktree-multi-selection'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 // How long to wait after a sortEpoch bump before actually re-sorting.
 // Prevents jarring position shifts when background events (AI starting work,
@@ -820,7 +821,15 @@ const WorktreeList = React.memo(function WorktreeList() {
     if (sortBy !== 'smart' || sortedIds.length === 0 || !sessionHasHadPty.current) {
       return
     }
-    void window.api.worktrees.persistSortOrder({ orderedIds: sortedIds })
+    const target = getActiveRuntimeTarget(useAppStore.getState().settings)
+    void (target.kind === 'environment'
+      ? callRuntimeRpc(
+          target,
+          'worktree.persistSortOrder',
+          { orderedIds: sortedIds },
+          { timeoutMs: 15_000 }
+        )
+      : window.api.worktrees.persistSortOrder({ orderedIds: sortedIds }))
   }, [sortedIds, sortBy])
 
   // Flatten, filter, and apply stable sort order via the shared utility so
diff --git a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
index 8a09b74d6df..bf6ae9c7993 100644
--- a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
@@ -657,6 +657,10 @@ export function ResourceUsageStatusSegment({
   const setActiveView = useAppStore((s) => s.setActiveView)
   const openSpacePage = useAppStore((s) => s.openSpacePage)
   const repos = useAppStore((s) => s.repos)
+  const activeRuntimeEnvironmentId = useAppStore(
+    (s) => s.settings?.activeRuntimeEnvironmentId ?? null
+  )
+  const runtimeEnvironmentActive = Boolean(activeRuntimeEnvironmentId?.trim())
 
   const [open, setOpen] = useState(false)
   const [sortOption, setSortOption] = useState<SortOption>('memory')
@@ -667,6 +671,10 @@ export function ResourceUsageStatusSegment({
   const [sessionsError, setSessionsError] = useState(false)
   const [killConfirm, setKillConfirm] = useState<UnifiedSessionRow | null>(null)
   const [killing, setKilling] = useState(false)
+  // Why: this segment only understands the local Electron PTY/resource daemon.
+  // While a runtime server is active, hiding local samples avoids showing or
+  // killing sessions from the wrong machine.
+  const resourceSnapshot = runtimeEnvironmentActive ? null : snapshot
 
   // Why: after a kill confirms and the session unmounts, focus would otherwise
   // fall to <body>. We park a ref on the popover body so we can restore focus
@@ -674,6 +682,11 @@ export function ResourceUsageStatusSegment({
   const popoverBodyRef = useRef<HTMLDivElement | null>(null)
 
   const refreshSessions = useCallback(async () => {
+    if (runtimeEnvironmentActive) {
+      setSessions([])
+      setSessionsError(false)
+      return
+    }
     try {
       const result = await window.api.pty.listSessions()
       setSessions(result)
@@ -681,7 +694,7 @@ export function ResourceUsageStatusSegment({
     } catch {
       setSessionsError(true)
     }
-  }, [])
+  }, [runtimeEnvironmentActive])
 
   const daemonActions = useDaemonActions({
     onRestartSettled: () => {
@@ -698,7 +711,7 @@ export function ResourceUsageStatusSegment({
   // background at a slower rate so the badge count stays reasonably fresh
   // without keeping the Memory IPC hot.
   useEffect(() => {
-    if (!open) {
+    if (!open || runtimeEnvironmentActive) {
       return
     }
     void fetchSnapshot()
@@ -713,9 +726,14 @@ export function ResourceUsageStatusSegment({
     return () => {
       window.clearInterval(memTimer)
     }
-  }, [open, fetchSnapshot, refreshSessions])
+  }, [open, runtimeEnvironmentActive, fetchSnapshot, refreshSessions])
 
   useEffect(() => {
+    if (runtimeEnvironmentActive) {
+      setSessions([])
+      setSessionsError(false)
+      return
+    }
     const refreshIfVisible = (): void => {
       if (document.visibilityState === 'visible' && document.hasFocus()) {
         void refreshSessions()
@@ -733,7 +751,7 @@ export function ResourceUsageStatusSegment({
       window.removeEventListener('focus', refreshIfVisible)
       document.removeEventListener('visibilitychange', refreshIfVisible)
     }
-  }, [refreshSessions])
+  }, [runtimeEnvironmentActive, refreshSessions])
 
   const repoDisplayNameById = useMemo(() => {
     const map = new Map<string, string>()
@@ -766,8 +784,8 @@ export function ResourceUsageStatusSegment({
   // feel laggy because the segment is always mounted in the status bar.
   const unifiedRepos = useMemo(
     () =>
-      open
-        ? mergeSnapshotAndSessions(snapshot, sessions, {
+      open && !runtimeEnvironmentActive
+        ? mergeSnapshotAndSessions(resourceSnapshot, sessions, {
             tabsByWorktree,
             ptyIdsByTabId,
             runtimePaneTitlesByTabId,
@@ -778,7 +796,8 @@ export function ResourceUsageStatusSegment({
         : [],
     [
       open,
-      snapshot,
+      runtimeEnvironmentActive,
+      resourceSnapshot,
       sessions,
       tabsByWorktree,
       ptyIdsByTabId,
@@ -794,7 +813,7 @@ export function ResourceUsageStatusSegment({
   // Build the bound set with a single flat walk instead of nested Object
   // iterations to keep this light on every store update.
   const orphanCount = useMemo(() => {
-    if (!workspaceSessionReady) {
+    if (!workspaceSessionReady || runtimeEnvironmentActive) {
       return 0
     }
     const bound = new Set<string>()
@@ -812,32 +831,36 @@ export function ResourceUsageStatusSegment({
       }
     }
     return n
-  }, [sessions, ptyIdsByTabId, workspaceSessionReady])
+  }, [sessions, ptyIdsByTabId, workspaceSessionReady, runtimeEnvironmentActive])
 
   const { totalMemory, totalCpu, hostShare, memBadgeLabel } = useMemo(() => {
-    const memory = snapshot?.totalMemory ?? 0
-    const cpu = snapshot?.totalCpu ?? 0
-    const hostTotal = snapshot?.host.totalMemory ?? 0
+    const memory = resourceSnapshot?.totalMemory ?? 0
+    const cpu = resourceSnapshot?.totalCpu ?? 0
+    const hostTotal = resourceSnapshot?.host.totalMemory ?? 0
     return {
       totalMemory: memory,
       totalCpu: cpu,
       hostShare: hostTotal > 0 ? (memory / hostTotal) * 100 : 0,
-      memBadgeLabel: snapshot ? formatMemory(memory) : '—'
+      memBadgeLabel: resourceSnapshot ? formatMemory(memory) : '—'
     }
-  }, [snapshot])
+  }, [resourceSnapshot])
 
   // Why: memorySnapshotError is null both for "last fetch succeeded" and
   // "never fetched". When the segment is mounted but the popover hasn't
   // been opened, fetchMemorySnapshot has never run, so a sessions IPC
   // failure on the always-on poll would otherwise be silent. Treat the
   // absence of any snapshot plus a sessions error as unreachable too.
-  const daemonUnreachable = sessionsError && (memorySnapshotError !== null || snapshot === null)
+  const daemonUnreachable =
+    !runtimeEnvironmentActive &&
+    sessionsError &&
+    (memorySnapshotError !== null || snapshot === null)
   // Why: a partial failure where the sessions IPC fails but the snapshot
   // IPC still works was silently invisible after the merge — the old
   // SessionsTabPanel surfaced it as "Terminal sessions unavailable". Show
   // a slim inline notice so the user understands why the session list is
   // empty/stale even though the resource numbers look fine.
-  const sessionsOnlyError = sessionsError && memorySnapshotError === null
+  const sessionsOnlyError =
+    !runtimeEnvironmentActive && sessionsError && memorySnapshotError === null
 
   const toggleRepo = useCallback((repoId: string): void => {
     setCollapsedRepos((prev) => {
@@ -1060,7 +1083,7 @@ export function ResourceUsageStatusSegment({
                 <button
                   type="button"
                   onClick={() => daemonActions.setPending('restart')}
-                  disabled={daemonActions.isBusy}
+                  disabled={daemonActions.isBusy || runtimeEnvironmentActive}
                   aria-label="Restart daemon"
                   className="inline-flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-40"
                 >
@@ -1068,7 +1091,7 @@ export function ResourceUsageStatusSegment({
                 </button>
               </TooltipTrigger>
               <TooltipContent side="top" sideOffset={6}>
-                Restart daemon
+                {runtimeEnvironmentActive ? 'Unavailable for runtime servers' : 'Restart daemon'}
               </TooltipContent>
             </Tooltip>
             <Tooltip delayDuration={200}>
@@ -1076,7 +1099,7 @@ export function ResourceUsageStatusSegment({
                 <button
                   type="button"
                   onClick={() => daemonActions.setPending('killAll')}
-                  disabled={daemonActions.isBusy}
+                  disabled={daemonActions.isBusy || runtimeEnvironmentActive}
                   aria-label="Kill all sessions"
                   className="inline-flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive disabled:opacity-40"
                 >
@@ -1084,7 +1107,7 @@ export function ResourceUsageStatusSegment({
                 </button>
               </TooltipTrigger>
               <TooltipContent side="top" sideOffset={6}>
-                Kill all sessions
+                {runtimeEnvironmentActive ? 'Unavailable for runtime servers' : 'Kill all sessions'}
               </TooltipContent>
             </Tooltip>
           </div>
@@ -1122,7 +1145,7 @@ export function ResourceUsageStatusSegment({
           </div>
         )}
 
-        {snapshot && (
+        {resourceSnapshot && (
           <div className="px-3 py-2 border-b border-border flex items-baseline justify-between gap-3 text-xs tabular-nums">
             <div className="flex items-baseline gap-3 min-w-0">
               <Tooltip delayDuration={200}>
@@ -1182,7 +1205,7 @@ export function ResourceUsageStatusSegment({
             inner tree owns its own scroll. The footer renders below this
             shell when orphan-bulk-kill is available. */}
         <div ref={popoverBodyRef} tabIndex={-1} className="flex h-[420px] flex-col outline-none">
-          {(unifiedRepos.length > 0 || snapshot) && (
+          {(unifiedRepos.length > 0 || resourceSnapshot) && (
             <div className="flex items-center justify-between px-3 py-1 bg-muted/30 border-b border-border/50 text-[10px] uppercase tracking-wide shrink-0">
               <button
                 type="button"
@@ -1253,22 +1276,26 @@ export function ResourceUsageStatusSegment({
               />
             )}
 
-            {unifiedRepos.length === 0 && snapshot && (
+            {unifiedRepos.length === 0 && resourceSnapshot && (
               <div className="px-3 py-4 text-center text-xs text-muted-foreground">
                 Nothing running right now
               </div>
             )}
 
-            {snapshot && (
+            {resourceSnapshot && (
               <AppSection
-                app={snapshot.app}
+                app={resourceSnapshot.app}
                 isCollapsed={appCollapsed}
                 onToggle={() => setAppCollapsed((v) => !v)}
               />
             )}
 
-            {!snapshot && !daemonUnreachable && (
-              <div className="px-3 py-4 text-center text-xs text-muted-foreground">Loading…</div>
+            {!resourceSnapshot && !daemonUnreachable && (
+              <div className="px-3 py-4 text-center text-xs text-muted-foreground">
+                {runtimeEnvironmentActive
+                  ? 'Local resource usage hidden for runtime servers.'
+                  : 'Loading…'}
+              </div>
             )}
           </div>
         </div>
@@ -1346,7 +1373,7 @@ export function ResourceUsageStatusSegment({
           </DialogFooter>
         </DialogContent>
       </Dialog>
-      <DaemonActionDialog api={daemonActions} />
+      {!runtimeEnvironmentActive && <DaemonActionDialog api={daemonActions} />}
     </Popover>
   )
 }
diff --git a/src/renderer/src/components/tab-bar/EditorFileTab.tsx b/src/renderer/src/components/tab-bar/EditorFileTab.tsx
index a33cc025318..1e24243f01b 100644
--- a/src/renderer/src/components/tab-bar/EditorFileTab.tsx
+++ b/src/renderer/src/components/tab-bar/EditorFileTab.tsx
@@ -22,7 +22,7 @@ import { basename, normalizeRelativePath } from '@/lib/path'
 import { getEditorDisplayLabel } from '@/components/editor/editor-labels'
 import { renameFileOnDisk } from '@/lib/rename-file'
 import { detectLanguage } from '@/lib/language-detect'
-import { useWorktreeById } from '@/store/selectors'
+import { useRepoById, useWorktreeById } from '@/store/selectors'
 import { useAppStore } from '@/store'
 import { STATUS_COLORS, STATUS_LABELS } from '../right-sidebar/status-display'
 import type { GitFileStatus } from '../../../../shared/types'
@@ -35,6 +35,8 @@ import {
   type DropIndicator
 } from './drop-indicator'
 import { canOpenMarkdownPreview } from '@/components/editor/markdown-preview-controls'
+import { showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
+import { shouldBlockEditorTabLocalOpen } from './editor-tab-local-open-guard'
 
 const isMac = navigator.userAgent.includes('Mac')
 const isLinux = navigator.userAgent.includes('Linux')
@@ -74,6 +76,7 @@ export default function EditorFileTab({
   dropIndicator?: DropIndicator
 }): React.JSX.Element {
   const worktree = useWorktreeById(file.worktreeId)
+  const repo = useRepoById(worktree?.repoId ?? null)
   // Why: no transform/transition/isDragging styling — the drag design is
   // that tabs stay visually anchored; only the blue insertion bar moves.
   const { attributes, listeners, setNodeRef } = useSortable({
@@ -379,6 +382,7 @@ export default function EditorFileTab({
                     filePath: file.filePath,
                     relativePath: file.relativePath,
                     worktreeId: file.worktreeId,
+                    runtimeEnvironmentId: file.runtimeEnvironmentId,
                     language: resolvedLanguage
                   })
                 }}
@@ -407,6 +411,16 @@ export default function EditorFileTab({
           <DropdownMenuSeparator />
           <DropdownMenuItem
             onSelect={() => {
+              if (
+                shouldBlockEditorTabLocalOpen(
+                  useAppStore.getState().settings,
+                  file.runtimeEnvironmentId,
+                  repo?.connectionId ?? null
+                )
+              ) {
+                showLocalPathOpenBlockedToast()
+                return
+              }
               window.api.shell.openPath(file.filePath)
             }}
           >
diff --git a/src/renderer/src/components/tab-bar/TabBar.tsx b/src/renderer/src/components/tab-bar/TabBar.tsx
index 7f15947cfc6..91eef724ba0 100644
--- a/src/renderer/src/components/tab-bar/TabBar.tsx
+++ b/src/renderer/src/components/tab-bar/TabBar.tsx
@@ -38,6 +38,7 @@ import {
   DropdownMenuSubTrigger,
   DropdownMenuTrigger
 } from '@/components/ui/dropdown-menu'
+import { listRuntimeProjectNotes } from '@/runtime/runtime-notes-client'
 import type { NoteSummary } from '../../../../shared/notes-types'
 
 const isMac = navigator.userAgent.includes('Mac')
@@ -173,6 +174,7 @@ function TabBarInner({
   const defaultWindowsPowerShellImplementation = useAppStore(
     (s) => s.settings?.terminalWindowsPowerShellImplementation ?? 'auto'
   )
+  const settings = useAppStore((s) => s.settings)
   const [pwshAvailable, setPwshAvailable] = useState(false)
   const [projectNotes, setProjectNotes] = useState<NoteSummary[]>([])
   const [projectNotesLoading, setProjectNotesLoading] = useState(false)
@@ -237,7 +239,7 @@ function TabBarInner({
       setProjectNotesLoading(true)
       setProjectNotesError(null)
       try {
-        const result = await window.api.notes.list({
+        const result = await listRuntimeProjectNotes(settings, {
           projectId: context.projectId,
           worktreeId: context.worktreeId,
           limit: 100
@@ -250,7 +252,7 @@ function TabBarInner({
       }
     }
     void refreshProjectNotes()
-  }, [newTabMenuOpen, onNewNotesTab, targetNotesWorktreeId])
+  }, [newTabMenuOpen, onNewNotesTab, settings, targetNotesWorktreeId])
 
   const terminalMap = useMemo(() => new Map(tabs.map((t) => [t.id, t])), [tabs])
   const editorMap = useMemo(
diff --git a/src/renderer/src/components/tab-bar/editor-tab-local-open-guard.test.ts b/src/renderer/src/components/tab-bar/editor-tab-local-open-guard.test.ts
new file mode 100644
index 00000000000..21b850b21fa
--- /dev/null
+++ b/src/renderer/src/components/tab-bar/editor-tab-local-open-guard.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { shouldBlockEditorTabLocalOpen } from './editor-tab-local-open-guard'
+
+describe('shouldBlockEditorTabLocalOpen', () => {
+  it('blocks remote-owned editor tabs even after the active runtime switches local', () => {
+    expect(shouldBlockEditorTabLocalOpen({ activeRuntimeEnvironmentId: null }, 'env-1', null)).toBe(
+      true
+    )
+  })
+
+  it('blocks SSH editor tabs without a runtime owner', () => {
+    expect(
+      shouldBlockEditorTabLocalOpen({ activeRuntimeEnvironmentId: null }, undefined, 'ssh-1')
+    ).toBe(true)
+  })
+
+  it('allows local editor tabs without runtime or SSH ownership', () => {
+    expect(
+      shouldBlockEditorTabLocalOpen({ activeRuntimeEnvironmentId: null }, undefined, null)
+    ).toBe(false)
+  })
+})
diff --git a/src/renderer/src/components/tab-bar/editor-tab-local-open-guard.ts b/src/renderer/src/components/tab-bar/editor-tab-local-open-guard.ts
new file mode 100644
index 00000000000..37302887f6d
--- /dev/null
+++ b/src/renderer/src/components/tab-bar/editor-tab-local-open-guard.ts
@@ -0,0 +1,13 @@
+import type { GlobalSettings } from '../../../../shared/types'
+import { isLocalPathOpenBlocked } from '@/lib/local-path-open-guard'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+
+export function shouldBlockEditorTabLocalOpen(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  fileRuntimeEnvironmentId: string | null | undefined,
+  connectionId: string | null | undefined
+): boolean {
+  return isLocalPathOpenBlocked(settingsForRuntimeOwner(settings, fileRuntimeEnvironmentId), {
+    connectionId
+  })
+}
diff --git a/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts b/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
index dabf845257f..593653ef4a2 100644
--- a/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
+++ b/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
@@ -16,6 +16,7 @@ import { requestEditorFileClose } from '../editor/editor-autosave'
 import { focusTerminalTabSurface } from '../../lib/focus-terminal-tab-surface'
 import { getProjectNotesEntityId } from '../../lib/open-project-notes-tab'
 import { requestProjectNotesTabClose } from '../../lib/project-notes-close-request'
+import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
 
 export type GroupEditorItem = OpenFile & { tabId: string }
 export type GroupBrowserItem = BrowserTabState & { tabId: string }
@@ -484,7 +485,8 @@ export function useTabGroupWorkspaceModel({
       closeToRight,
       createSplitGroup,
       newBrowserTab: () => {
-        const defaultUrl = useAppStore.getState().browserDefaultUrl ?? 'about:blank'
+        const state = useAppStore.getState()
+        const defaultUrl = state.browserDefaultUrl ?? 'about:blank'
         createBrowserTab(worktreeId, defaultUrl, {
           title: 'New Browser Tab',
           focusAddressBar: true
@@ -513,7 +515,13 @@ export function useTabGroupWorkspaceModel({
         }
         try {
           const connectionId = getConnectionId(worktreeId) ?? undefined
-          const fileInfo = await createUntitledMarkdownFile(path, worktreeId, connectionId)
+          const settings = useAppStore.getState().settings
+          const fileInfo = await createUntitledMarkdownFile(
+            path,
+            worktreeId,
+            connectionId,
+            settings
+          )
           openFile(fileInfo, { preview: false, targetGroupId: groupId })
         } catch (err) {
           toast.error(extractIpcErrorMessage(err, 'Failed to create untitled markdown file.'))
@@ -524,9 +532,19 @@ export function useTabGroupWorkspaceModel({
         let label = 'Project Notes'
         if (noteId) {
           try {
-            const result = await window.api.notes.show({ projectId, worktreeId, note: noteId })
+            const settings = useAppStore.getState().settings
+            const result = await showRuntimeProjectNote(settings, {
+              projectId,
+              worktreeId,
+              note: noteId
+            })
             label = result.note.title
-            await window.api.notes.link({ projectId, worktreeId, note: noteId, kind: 'active' })
+            await linkRuntimeProjectNote(settings, {
+              projectId,
+              worktreeId,
+              note: noteId,
+              kind: 'active'
+            })
           } catch {
             label = 'Project Notes'
           }
diff --git a/src/renderer/src/components/terminal-pane/TerminalPane.tsx b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
index 3a3469b471a..909d1f91977 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
@@ -14,6 +14,7 @@ import TerminalSearch from '@/components/TerminalSearch'
 import type { PtyTransport } from './pty-transport'
 import { fitPanes, isWindowsUserAgent, shellEscapePath } from './pane-helpers'
 import { getConnectionId } from '@/lib/connection-context'
+import { resolveTerminalDropTargetShell } from './terminal-drop-handler'
 import { EMPTY_LAYOUT, paneLeafId, serializeTerminalLayout } from './layout-serialization'
 import {
   applyExpandedLayoutTo,
@@ -42,6 +43,12 @@ import {
 import { getDriverForPty, onDriverChange } from '@/lib/pane-manager/mobile-driver-state'
 import { safeFit } from '@/lib/pane-manager/pane-tree-ops'
 import { captureTerminalShutdownLayout } from './terminal-shutdown-layout-capture'
+import { inspectRuntimeTerminalProcess } from '@/runtime/runtime-terminal-inspection'
+import { callRuntimeRpc } from '@/runtime/runtime-rpc-client'
+import {
+  getRemoteRuntimePtyEnvironmentId,
+  getRemoteRuntimeTerminalHandle
+} from '@/runtime/runtime-terminal-stream'
 
 // Why: registry lives in a leaf module so the store slice can import it
 // without re-entering the `slice → TerminalPane → store → slice` cycle
@@ -452,10 +459,10 @@ export default function TerminalPane({
         executeClosePane(paneId)
         return
       }
-      void window.api.pty
-        .hasChildProcesses(ptyId)
-        .then((hasChildren) => {
-          if (hasChildren) {
+      const settings = useAppStore.getState().settings
+      void inspectRuntimeTerminalProcess(settings, ptyId)
+        .then((process) => {
+          if (process.hasChildProcesses) {
             setCloseConfirmPaneId(paneId)
           } else {
             executeClosePane(paneId)
@@ -1081,20 +1088,21 @@ export default function TerminalPane({
           if (!transport) {
             return
           }
-          // Why: the explorer passes the worktree-absolute path via a DOM
-          // MIME, so for SSH worktrees this is a remote POSIX path destined
-          // for the remote shell. Quote for the target shell (remote = posix)
-          // rather than the client OS; otherwise a Windows client dropping
-          // onto an SSH-Linux worktree would emit Windows-style quoting.
-          // Why: `typeof === 'string'` (not `!== null`) so an unhydrated
-          // store (`undefined`) is treated as local and falls through to
-          // client-OS quoting, rather than being misclassified as remote.
-          const isRemote = typeof getConnectionId(worktreeId) === 'string'
-          const targetShell: 'posix' | 'windows' = isRemote
-            ? 'posix'
-            : isWindowsUserAgent()
-              ? 'windows'
-              : 'posix'
+          const state = useAppStore.getState()
+          const worktreePath =
+            Object.values(state.worktreesByRepo ?? {})
+              .flat()
+              .find((worktree) => worktree.id === worktreeId)?.path ??
+            cwd ??
+            filePath
+          const targetShell = resolveTerminalDropTargetShell({
+            activeRuntimeEnvironmentId: state.settings?.activeRuntimeEnvironmentId,
+            worktreePath,
+            // Why: internal Explorer drags paste a worktree-absolute path
+            // directly into the target shell. Runtime drops use the runtime
+            // worktree's path shape; legacy SSH drops remain POSIX.
+            connectionId: getConnectionId(worktreeId)
+          })
           transport.sendInput(shellEscapePath(filePath, targetShell))
           // Move focus to the terminal so the user can keep typing where the
           // dropped path just landed. Without this, focus stays on the file
@@ -1256,7 +1264,21 @@ export default function TerminalPane({
                   // active-mobile-subscriber path and the held-no-subscriber
                   // path (docs/mobile-fit-hold.md), so the banner unmounts
                   // and the PTY returns to desktop dims in either case.
-                  void window.api.runtime.restoreTerminalFit(ptyId)
+                  const remoteHandle = getRemoteRuntimeTerminalHandle(ptyId)
+                  const environmentId =
+                    getRemoteRuntimePtyEnvironmentId(ptyId) ??
+                    settingsRef.current?.activeRuntimeEnvironmentId ??
+                    null
+                  if (remoteHandle && environmentId) {
+                    void callRuntimeRpc(
+                      { kind: 'environment', environmentId },
+                      'terminal.restoreFit',
+                      { terminal: remoteHandle },
+                      { timeoutMs: 15_000 }
+                    ).catch(() => {})
+                  } else {
+                    void window.api.runtime.restoreTerminalFit(ptyId).catch(() => {})
+                  }
                 }
               }}
             >
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index 518964f6274..ffc8cf5c70d 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -24,7 +24,7 @@ type StoreState = {
   repos: { id: string; connectionId?: string | null }[]
   sshConnectionStates: Map<string, { status: string }>
   cacheTimerByKey: Record<string, number | null>
-  settings: { promptCacheTimerEnabled?: boolean } | null
+  settings: { promptCacheTimerEnabled?: boolean; activeRuntimeEnvironmentId?: string | null } | null
   codexRestartNoticeByPtyId: Record<
     string,
     { previousAccountLabel: string; nextAccountLabel: string }
@@ -138,6 +138,19 @@ vi.mock('./pty-transport', () => ({
   })
 }))
 
+vi.mock('./remote-runtime-pty-transport', () => ({
+  createRemoteRuntimePtyTransport: vi.fn(
+    (_environmentId: string, options: Record<string, unknown>) => {
+      createdTransportOptions.push(options)
+      const nextTransport = transportFactoryQueue.shift()
+      if (!nextTransport) {
+        throw new Error('No mock transport queued')
+      }
+      return nextTransport
+    }
+  )
+}))
+
 function createMockTransport(initialPtyId: string | null = null): MockTransport {
   let ptyId = initialPtyId
   return {
@@ -957,6 +970,65 @@ describe('connectPanePty', () => {
     expect(deps.syncPanePtyLayoutBinding).toHaveBeenCalledWith(2, 'pty-local-detached')
   })
 
+  it('attaches remote runtime PTY handles instead of creating a replacement terminal', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const transport = createMockTransport()
+    transportFactoryQueue.push(transport)
+
+    mockStoreState = {
+      ...mockStoreState,
+      tabsByWorktree: {
+        'wt-1': [{ id: 'tab-1', ptyId: 'remote:terminal-1' }]
+      },
+      settings: {
+        ...mockStoreState.settings,
+        activeRuntimeEnvironmentId: 'env-1'
+      }
+    } as StoreState
+
+    const pane = createPane(2)
+    const manager = createManager(2)
+    const deps = createDeps()
+
+    connectPanePty(pane as never, manager as never, deps as never)
+
+    expect(transport.connect).not.toHaveBeenCalled()
+    expect(transport.attach).toHaveBeenCalledWith(
+      expect.objectContaining({ existingPtyId: 'remote:terminal-1' })
+    )
+    expect(deps.syncPanePtyLayoutBinding).toHaveBeenCalledWith(2, 'remote:terminal-1')
+  })
+
+  it('constructs restored encoded remote PTYs with their owning runtime environment', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const transport = createMockTransport()
+    transportFactoryQueue.push(transport)
+
+    mockStoreState = {
+      ...mockStoreState,
+      tabsByWorktree: {
+        'wt-1': [{ id: 'tab-1', ptyId: 'remote:env-1@@terminal-1' }]
+      },
+      settings: {
+        ...mockStoreState.settings,
+        activeRuntimeEnvironmentId: 'env-2'
+      }
+    } as StoreState
+
+    const pane = createPane(2)
+    const manager = createManager(2)
+    const deps = createDeps()
+
+    connectPanePty(pane as never, manager as never, deps as never)
+
+    expect(createRemoteRuntimePtyTransport).toHaveBeenCalledWith('env-1', expect.any(Object))
+    expect(transport.attach).toHaveBeenCalledWith(
+      expect.objectContaining({ existingPtyId: 'remote:env-1@@terminal-1' })
+    )
+    expect(deps.syncPanePtyLayoutBinding).toHaveBeenCalledWith(2, 'remote:env-1@@terminal-1')
+  })
+
   it('persists a restarted pane PTY id and uses it on the next remount', async () => {
     const { connectPanePty } = await import('./pty-connection')
 
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index eac55170eba..544422456ca 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -6,6 +6,7 @@ import { scheduleRuntimeGraphSync } from '@/runtime/sync-runtime-graph'
 import { useAppStore } from '@/store'
 import type { PtyConnectResult } from './pty-transport'
 import { createIpcPtyTransport } from './pty-transport'
+import { createRemoteRuntimePtyTransport } from './remote-runtime-pty-transport'
 import { shouldSeedCacheTimerOnInitialTitle } from './cache-timer-seeding'
 import type { PtyConnectionDeps } from './pty-connection-types'
 import { safeFit } from '@/lib/pane-manager/pane-tree-ops'
@@ -20,6 +21,7 @@ import {
 } from './layout-serialization'
 import { warnTerminalLifecycleAnomaly } from './terminal-lifecycle-diagnostics'
 import { registerPtySerializer, registerPtyTitleSource } from './pty-buffer-serializer'
+import { getRemoteRuntimePtyEnvironmentId } from '@/runtime/runtime-terminal-stream'
 import {
   discardTerminalOutput,
   flushTerminalOutput,
@@ -30,6 +32,7 @@ import { createTerminalCommandLifecycle } from './terminal-command-lifecycle'
 
 const pendingSpawnByPaneKey = new Map<string, Promise<string | null>>()
 const SSH_SESSION_EXPIRED_ERROR = 'SSH_SESSION_EXPIRED'
+const REMOTE_PTY_ID_PREFIX = 'remote:'
 
 // Why: when multiple panes/tabs need the same deferred SSH connection,
 // the first one calls ssh.connect() and subsequent ones must wait for it
@@ -48,6 +51,10 @@ function formatSshSessionExpiredMessage(): string {
   return 'Previous SSH session expired. Start a new terminal to continue.'
 }
 
+function isRemoteRuntimePtyId(ptyId: string | null | undefined): boolean {
+  return typeof ptyId === 'string' && ptyId.startsWith(REMOTE_PTY_ID_PREFIX)
+}
+
 function sshPromptConnectOutcomeForStatus(
   status: string | undefined,
   sawNonDisconnected: boolean
@@ -340,7 +347,17 @@ export function connectPanePty(
   const tab = (state.tabsByWorktree[deps.worktreeId] ?? []).find((t) => t.id === deps.tabId)
   const shellOverride = tab?.shellOverride
 
-  const transport = createIpcPtyTransport({
+  const restoredPtyIdForTransport =
+    deps.restoredLeafId && deps.restoredPtyIdByLeafId
+      ? (deps.restoredPtyIdByLeafId[deps.restoredLeafId] ?? null)
+      : null
+  const remoteRuntimeOwnerForTransport =
+    (restoredPtyIdForTransport
+      ? getRemoteRuntimePtyEnvironmentId(restoredPtyIdForTransport)
+      : null) ?? (tab?.ptyId ? getRemoteRuntimePtyEnvironmentId(tab.ptyId) : null)
+  const activeRuntimeEnvironmentId = state.settings?.activeRuntimeEnvironmentId?.trim() || null
+  const runtimeEnvironmentId = remoteRuntimeOwnerForTransport ?? activeRuntimeEnvironmentId
+  const transportOptions = {
     cwd: deps.cwd,
     env: paneEnv,
     command: paneStartup?.command,
@@ -374,7 +391,10 @@ export function connectPanePty(
       const title = currentState.runtimePaneTitlesByTabId?.[deps.tabId]?.[pane.id]
       currentState.setAgentStatus(cacheKey, payload, title)
     }
-  })
+  }
+  const transport = runtimeEnvironmentId
+    ? createRemoteRuntimePtyTransport(runtimeEnvironmentId, transportOptions)
+    : createIpcPtyTransport(transportOptions)
   const hasExistingPaneTransport = deps.paneTransportsRef.current.size > 0
   deps.paneTransportsRef.current.set(pane.id, transport)
 
@@ -466,7 +486,9 @@ export function connectPanePty(
     if (!proposed || proposed.cols <= 0 || proposed.rows <= 0) {
       return
     }
-    window.api.pty.reportGeometry(currentPtyId, proposed.cols, proposed.rows)
+    if (!isRemoteRuntimePtyId(currentPtyId)) {
+      window.api.pty.reportGeometry(currentPtyId, proposed.cols, proposed.rows)
+    }
   }
   const geometryReportObserver =
     typeof ResizeObserver === 'undefined'
@@ -580,9 +602,9 @@ export function connectPanePty(
       // calls from the same renderer. The cooperation gate at pty:spawn time
       // sees pendingByPaneKey populated. Settle/clear later echoes the gen
       // token captured here. See docs/mobile-prefer-renderer-scrollback.md.
-      const preSignalPromise = window.api.pty
-        .declarePendingPaneSerializer(cacheKey)
-        .catch(() => null)
+      const preSignalPromise = runtimeEnvironmentId
+        ? Promise.resolve(null)
+        : window.api.pty.declarePendingPaneSerializer(cacheKey).catch(() => null)
 
       const spawnedRaw = transport.connect({
         url: '',
@@ -601,8 +623,10 @@ export function connectPanePty(
             typeof spawnedPtyId === 'string' ? spawnedPtyId : transport.getPtyId()
           const gen = await preSignalPromise
           if (typeof gen === 'number' && resolvedPtyId) {
-            registerPaneSerializerFor(resolvedPtyId)
-            void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+            if (!isRemoteRuntimePtyId(resolvedPtyId)) {
+              registerPaneSerializerFor(resolvedPtyId)
+              void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+            }
           } else if (typeof gen === 'number') {
             void window.api.pty.clearPendingPaneSerializer(cacheKey, gen).catch(() => {})
           }
@@ -742,7 +766,9 @@ export function connectPanePty(
         if (connectResult.coldRestore) {
           // Snapshot superseded the cold-restore payload — ack it so the
           // daemon does not redeliver it on the next reattach.
-          window.api.pty.ackColdRestore(ptyId)
+          if (!isRemoteRuntimePtyId(ptyId)) {
+            window.api.pty.ackColdRestore(ptyId)
+          }
         }
       } else if (connectResult?.replay) {
         // Relay replay holds the last 100 KB of raw output. The xterm may
@@ -753,7 +779,9 @@ export function connectPanePty(
         writeReplayData(connectResult.replay)
         writeReplayData(POST_REPLAY_FOCUS_REPORTING_RESET)
         if (connectResult.coldRestore) {
-          window.api.pty.ackColdRestore(ptyId)
+          if (!isRemoteRuntimePtyId(ptyId)) {
+            window.api.pty.ackColdRestore(ptyId)
+          }
         }
       } else if (connectResult?.coldRestore) {
         // restoreScrollbackBuffers() already wrote the saved xterm buffer
@@ -771,7 +799,9 @@ export function connectPanePty(
         // crashed TUI (e.g. Claude's \e[?1004h) left in the scrollback, so
         // reset them to match the fresh shell's expectations.
         writeReplayData(POST_REPLAY_MODE_RESET)
-        window.api.pty.ackColdRestore(ptyId)
+        if (!isRemoteRuntimePtyId(ptyId)) {
+          window.api.pty.ackColdRestore(ptyId)
+        }
       }
       // Why: when a mobile-fit override is active, skip sending desktop dims
       // to the PTY — the PTY is already at phone dimensions and must stay there.
@@ -782,7 +812,9 @@ export function connectPanePty(
       // Why: POSIX only delivers SIGWINCH when terminal dimensions actually
       // change. Sending it explicitly guarantees restored TUIs repaint at
       // the correct cursor position after snapshot replay.
-      window.api.pty.signal(ptyId, 'SIGWINCH')
+      if (!isRemoteRuntimePtyId(ptyId)) {
+        window.api.pty.signal(ptyId, 'SIGWINCH')
+      }
 
       scheduleRuntimeGraphSync()
     }
@@ -946,9 +978,10 @@ export function connectPanePty(
             // cooperation gate uniformly applies to remote sessions. Issue
             // declare and connect back-to-back; Electron preserves order. See
             // docs/mobile-prefer-renderer-scrollback.md.
-            const preSignalPromise = window.api.pty
-              .declarePendingPaneSerializer(cacheKey)
-              .catch(() => null)
+            const preSignalPromise =
+              runtimeEnvironmentId || isRemoteRuntimePtyId(pendingSessionId)
+                ? Promise.resolve(null)
+                : window.api.pty.declarePendingPaneSerializer(cacheKey).catch(() => null)
             let expiredReattachError = false
             const reattachPromise = transport.connect({
               url: '',
@@ -991,7 +1024,9 @@ export function connectPanePty(
                 handleReattachResult(result, pendingSessionId)
                 const gen = await preSignalPromise
                 if (typeof gen === 'number') {
-                  void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+                  if (!isRemoteRuntimePtyId(pendingSessionId)) {
+                    void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+                  }
                 }
               })
               .catch(async (err) => {
@@ -1051,6 +1086,7 @@ export function connectPanePty(
     // the reattach and spawn a fresh session instead.
     const deferredReattachSessionId =
       candidateReattachSessionId &&
+      !isRemoteRuntimePtyId(candidateReattachSessionId) &&
       isSessionOwnedByWorktree(candidateReattachSessionId, deps.worktreeId)
         ? candidateReattachSessionId
         : null
@@ -1074,9 +1110,10 @@ export function connectPanePty(
       // channel preserves order. See
       // docs/mobile-prefer-renderer-scrollback.md (Renderer-side prerequisite
       // requirement #4).
-      const preSignalPromise = window.api.pty
-        .declarePendingPaneSerializer(cacheKey)
-        .catch(() => null)
+      const preSignalPromise =
+        runtimeEnvironmentId || isRemoteRuntimePtyId(deferredReattachSessionId)
+          ? Promise.resolve(null)
+          : window.api.pty.declarePendingPaneSerializer(cacheKey).catch(() => null)
 
       let expiredReattachError = false
       const reattachPromise = transport.connect({
@@ -1112,7 +1149,9 @@ export function connectPanePty(
           handleReattachResult(result, deferredReattachSessionId)
           const gen = await preSignalPromise
           if (typeof gen === 'number') {
-            void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+            if (!isRemoteRuntimePtyId(deferredReattachSessionId)) {
+              void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+            }
           }
         })
         .catch(async (err) => {
diff --git a/src/renderer/src/components/terminal-pane/pty-transport.test.ts b/src/renderer/src/components/terminal-pane/pty-transport.test.ts
index dd6c0737429..252c2f018ba 100644
--- a/src/renderer/src/components/terminal-pane/pty-transport.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-transport.test.ts
@@ -1,5 +1,13 @@
 /* oxlint-disable max-lines */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamJson,
+  encodeTerminalStreamFrame,
+  encodeTerminalStreamJson,
+  encodeTerminalStreamText
+} from '../../../../shared/terminal-stream-protocol'
 
 describe('createIpcPtyTransport', () => {
   const originalWindow = (globalThis as { window?: typeof window }).window
@@ -553,3 +561,215 @@ describe('createIpcPtyTransport', () => {
     expect(transport.getPtyId()).toBeNull()
   })
 })
+
+describe('createRemoteRuntimePtyTransport', () => {
+  const originalWindow = (globalThis as { window?: typeof window }).window
+  const runtimeCall = vi.fn()
+  const runtimeSubscribe = vi.fn()
+  let subscriptionCallbacks: {
+    onResponse: (response: unknown) => void
+    onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+    onError?: (error: { code: string; message: string }) => void
+    onClose?: () => void
+  } | null = null
+  let unsubscribe: {
+    unsubscribe: () => void
+    sendBinary: (bytes: Uint8Array<ArrayBufferLike>) => void
+  } | null = null
+  let unsubscribeFn: ReturnType<typeof vi.fn<() => void>> | null = null
+
+  beforeEach(() => {
+    vi.resetModules()
+    runtimeCall.mockReset()
+    runtimeSubscribe.mockReset()
+    subscriptionCallbacks = null
+    unsubscribeFn = vi.fn<() => void>()
+    unsubscribe = {
+      unsubscribe: unsubscribeFn,
+      sendBinary: vi.fn()
+    }
+    runtimeCall.mockResolvedValue({
+      id: 'rpc-create',
+      ok: true,
+      result: {
+        terminal: {
+          handle: 'term-remote',
+          worktreeId: 'repo1::/remote/wt',
+          title: null,
+          surface: 'background'
+        }
+      },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    runtimeSubscribe.mockImplementation(
+      async (_args: unknown, callbacks: typeof subscriptionCallbacks) => {
+        subscriptionCallbacks = callbacks
+        queueMicrotask(() => {
+          subscriptionCallbacks?.onResponse({
+            id: 'rpc-multiplex',
+            ok: true,
+            result: { type: 'ready' },
+            _meta: { runtimeId: 'runtime-remote' }
+          })
+        })
+        return unsubscribe
+      }
+    )
+
+    ;(globalThis as { window: typeof window }).window = {
+      ...originalWindow,
+      api: {
+        ...originalWindow?.api,
+        runtimeEnvironments: {
+          ...originalWindow?.api?.runtimeEnvironments,
+          call: runtimeCall,
+          subscribe: runtimeSubscribe
+        }
+      }
+    } as unknown as typeof window
+  })
+
+  afterEach(() => {
+    if (originalWindow) {
+      ;(globalThis as { window: typeof window }).window = originalWindow
+    } else {
+      delete (globalThis as { window?: typeof window }).window
+    }
+  })
+
+  function latestRemoteSubscribePayload(): { streamId: number } {
+    const send = unsubscribe?.sendBinary as unknown as
+      | { mock: { calls: [Uint8Array<ArrayBufferLike>][] } }
+      | undefined
+    const frames =
+      send?.mock.calls
+        .map((call) => decodeTerminalStreamFrame(call[0]))
+        .filter((frame) => frame?.opcode === TerminalStreamOpcode.Subscribe) ?? []
+    const frame = frames.at(-1)
+    if (!frame) {
+      throw new Error('missing remote terminal subscribe frame')
+    }
+    const payload = decodeTerminalStreamJson<{ streamId: number }>(frame.payload)
+    if (!payload) {
+      throw new Error('invalid remote terminal subscribe frame')
+    }
+    return payload
+  }
+
+  it('creates and subscribes to a terminal on the active remote runtime', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const onReplayData = vi.fn()
+    const onData = vi.fn()
+    const onConnect = vi.fn()
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'repo1::/remote/wt',
+      command: 'claude',
+      env: { ORCA_TAB_ID: 'tab-1' },
+      tabId: 'tab-1',
+      leafId: 'pane:1'
+    })
+
+    const result = await transport.connect({
+      url: '',
+      callbacks: { onReplayData, onData, onConnect }
+    })
+
+    expect(result).toEqual({ id: 'remote:env-1@@term-remote', replay: '' })
+    expect(runtimeCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'terminal.create',
+      params: {
+        worktree: 'repo1::/remote/wt',
+        command: 'claude',
+        env: { ORCA_TAB_ID: 'tab-1' },
+        focus: false
+      },
+      timeoutMs: 15_000
+    })
+    expect(runtimeSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'terminal.multiplex',
+        params: {}
+      }),
+      expect.any(Object)
+    )
+    const { streamId } = latestRemoteSubscribePayload()
+
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.SnapshotStart,
+        streamId,
+        seq: 1,
+        payload: encodeTerminalStreamJson({ kind: 'scrollback' })
+      })
+    )
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.SnapshotChunk,
+        streamId,
+        seq: 2,
+        payload: encodeTerminalStreamText('hello')
+      })
+    )
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.SnapshotEnd,
+        streamId,
+        seq: 3,
+        payload: new Uint8Array()
+      })
+    )
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Output,
+        streamId,
+        seq: 4,
+        payload: encodeTerminalStreamText(' world')
+      })
+    )
+
+    expect(onReplayData).toHaveBeenCalledWith('hello')
+    expect(onConnect).toHaveBeenCalled()
+    expect(onData).toHaveBeenCalledWith(' world')
+  })
+
+  it('forwards input and cleanup through runtime RPC', async () => {
+    vi.useFakeTimers()
+    try {
+      const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+      const transport = createRemoteRuntimePtyTransport('env-1', {
+        worktreeId: 'repo1::/remote/wt',
+        tabId: 'tab-1',
+        leafId: 'pane:1'
+      })
+
+      await transport.connect({ url: '', callbacks: {} })
+      const { streamId } = latestRemoteSubscribePayload()
+      runtimeCall.mockClear()
+      const send = unsubscribe?.sendBinary as unknown as {
+        mockClear: () => void
+        mock: { calls: [Uint8Array<ArrayBufferLike>][] }
+      }
+      send.mockClear()
+
+      expect(transport.sendInput('ls\r')).toBe(true)
+      await vi.runOnlyPendingTimersAsync()
+      expect(runtimeCall).not.toHaveBeenCalled()
+      const inputFrame = decodeTerminalStreamFrame(send.mock.calls[0][0])
+      expect(inputFrame?.opcode).toBe(TerminalStreamOpcode.Input)
+      expect(inputFrame?.streamId).toBe(streamId)
+
+      transport.disconnect()
+      expect(unsubscribeFn).toHaveBeenCalled()
+      expect(runtimeCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'terminal.close',
+        params: { terminal: 'term-remote' },
+        timeoutMs: 15_000
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/pty-transport.ts b/src/renderer/src/components/terminal-pane/pty-transport.ts
index 98aeff0354c..8ccc6e8a300 100644
--- a/src/renderer/src/components/terminal-pane/pty-transport.ts
+++ b/src/renderer/src/components/terminal-pane/pty-transport.ts
@@ -38,10 +38,165 @@ export type {
 export { extractLastOscTitle } from '../../../../shared/agent-detection'
 
 const SSH_SESSION_EXPIRED_ERROR = 'SSH_SESSION_EXPIRED'
+const STALE_TITLE_TIMEOUT = 3000 // ms before stale working title is cleared
 
 // Why: onAgentStatus callback added to IpcPtyTransportOptions in pty-dispatcher
 // so the OSC 9999 status payloads can be forwarded to the store.
 
+type PtyOutputCallbacks = Parameters<PtyTransport['connect']>[0]['callbacks']
+
+type PtyOutputProcessorOptions = Pick<
+  IpcPtyTransportOptions,
+  | 'onTitleChange'
+  | 'onBell'
+  | 'onAgentBecameIdle'
+  | 'onAgentBecameWorking'
+  | 'onAgentExited'
+  | 'onAgentStatus'
+>
+
+type ProcessPtyOutputOptions = {
+  replayingBufferedData?: boolean
+  suppressAttentionEvents?: boolean
+}
+
+export function createPtyOutputProcessor({
+  onTitleChange,
+  onBell,
+  onAgentBecameIdle,
+  onAgentBecameWorking,
+  onAgentExited,
+  onAgentStatus
+}: PtyOutputProcessorOptions): {
+  processData: (
+    data: string,
+    callbacks: PtyOutputCallbacks,
+    options?: ProcessPtyOutputOptions
+  ) => void
+  clearAccumulatedState: () => void
+  clearStaleTitleTimer: () => void
+  resetBellDetector: () => void
+} {
+  const bellDetector = createBellDetector()
+  const processAgentStatusChunk = createAgentStatusOscProcessor()
+  let lastEmittedTitle: string | null = null
+  let staleTitleTimer: ReturnType<typeof setTimeout> | null = null
+  const agentTracker =
+    onAgentBecameIdle || onAgentBecameWorking || onAgentExited
+      ? createAgentStatusTracker(
+          (title) => {
+            onAgentBecameIdle?.(title)
+          },
+          onAgentBecameWorking,
+          onAgentExited
+        )
+      : null
+
+  function applyObservedTerminalTitle(title: string): void {
+    // Why: cursor-agent's native OSC title is the literal string "Cursor Agent"
+    // and it re-emits that title many times per turn (on every internal redraw)
+    // even while it's actively working. Orca drives the cursor spinner/unread
+    // path by injecting its own synthesized "⠋ Cursor Agent" and "Cursor ready"
+    // frames from the hook server (see src/main/index.ts). If we let cursor's
+    // bare title through, it lands in `runtimePaneTitlesByTabId` — where
+    // `getWorktreeStatus` reads from — and flips the sidebar dot back to solid
+    // within a second of the spinner appearing. Dropping the bare title before
+    // it reaches the store leaves the synthesized frame as the last-applied
+    // state until the next hook event overwrites it. Match is literal (trimmed,
+    // case-insensitive) so any task/chat title cursor auto-generates still
+    // passes through unchanged.
+    if (title.trim().toLowerCase() === 'cursor agent') {
+      return
+    }
+    lastEmittedTitle = normalizeTerminalTitle(title)
+    onTitleChange?.(lastEmittedTitle, title)
+    agentTracker?.handleTitle(title)
+  }
+
+  function clearStaleTitleTimer(): void {
+    if (staleTitleTimer) {
+      clearTimeout(staleTitleTimer)
+      staleTitleTimer = null
+    }
+  }
+
+  function processData(
+    data: string,
+    callbacks: PtyOutputCallbacks,
+    options: ProcessPtyOutputOptions = {}
+  ): void {
+    const suppressAttentionEvents = options.suppressAttentionEvents === true
+    // Why: OSC 9999 is a renderer-only control protocol. Parse it before
+    // xterm sees the bytes, and keep parser state across chunks so partial
+    // PTY reads do not drop valid status updates or print escape garbage.
+    const processed = processAgentStatusChunk(data)
+    data = processed.cleanData
+    // Why: mirror the onBell / onAgentBecameIdle guard below — during eager-buffer
+    // replay we must not surface stale agent-status payloads from a prior app
+    // session into the live store. The parser still consumes the bytes so they
+    // do not leak into xterm, we just suppress the callback.
+    if (onAgentStatus && !suppressAttentionEvents) {
+      for (const payload of processed.payloads) {
+        onAgentStatus(payload)
+      }
+    }
+    if (options.replayingBufferedData && callbacks.onReplayData) {
+      callbacks.onReplayData(data)
+    } else {
+      callbacks.onData?.(data)
+    }
+    if (onTitleChange) {
+      // Why: feed EVERY OSC title in the chunk through the observer, not just
+      // the last one. node-pty + the main-process 8ms batch window commonly
+      // coalesce multiple title updates into a single IPC payload — for Pi's
+      // 80ms spinner + agent_end idle cycle, the last title in the chunk is
+      // the idle one and the intermediate working frames were silently
+      // dropped, so the worktree card never observed the working state.
+      // Processing titles in order preserves the working→idle transition
+      // that detectAgentStatusFromTitle and agentTracker both key off.
+      const titles = extractAllOscTitles(data)
+      if (titles.length > 0) {
+        clearStaleTitleTimer()
+        for (const title of titles) {
+          applyObservedTerminalTitle(title)
+        }
+      } else if (lastEmittedTitle && detectAgentStatusFromTitle(lastEmittedTitle) === 'working') {
+        clearStaleTitleTimer()
+        staleTitleTimer = setTimeout(() => {
+          staleTitleTimer = null
+          if (lastEmittedTitle && detectAgentStatusFromTitle(lastEmittedTitle) === 'working') {
+            const cleared = clearWorkingIndicators(lastEmittedTitle)
+            lastEmittedTitle = cleared
+            onTitleChange(cleared, cleared)
+            agentTracker?.handleTitle(cleared)
+          }
+        }, STALE_TITLE_TIMEOUT)
+      }
+    }
+    // Why: BEL is the attention signal. The detector is stateful across
+    // chunks so a BEL sitting inside an OSC sequence (e.g. Claude's
+    // `\e]0;title\a`) is correctly ignored — only true terminal bells raise
+    // attention. suppressAttentionEvents gates this during eager-buffer replay
+    // so historical BELs do not produce fresh alerts on cold reattach.
+    if (onBell && bellDetector.chunkContainsBell(data) && !suppressAttentionEvents) {
+      onBell()
+    }
+  }
+
+  function clearAccumulatedState(): void {
+    clearStaleTitleTimer()
+    agentTracker?.reset()
+    bellDetector.reset()
+  }
+
+  return {
+    processData,
+    clearAccumulatedState,
+    clearStaleTitleTimer,
+    resetBellDetector: () => bellDetector.reset()
+  }
+}
+
 export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTransport {
   const {
     cwd,
@@ -65,30 +220,24 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
   let connected = false
   let destroyed = false
   let ptyId: string | null = null
-  const bellDetector = createBellDetector()
   // Why: eager PTY buffers contain output produced before the pane attached —
   // often from the previous app session. We still replay that data so titles
   // and scrollback restore correctly, but it must not produce fresh bells,
   // unread marks, or notifications for unrelated worktrees just because Orca
   // is reconnecting background terminals on launch.
   let suppressAttentionEvents = false
-  const processAgentStatusChunk = createAgentStatusOscProcessor()
-  let lastEmittedTitle: string | null = null
-  let staleTitleTimer: ReturnType<typeof setTimeout> | null = null
-  const agentTracker =
-    onAgentBecameIdle || onAgentBecameWorking || onAgentExited
-      ? createAgentStatusTracker(
-          (title) => {
-            if (!suppressAttentionEvents) {
-              onAgentBecameIdle?.(title)
-            }
-          },
-          onAgentBecameWorking,
-          onAgentExited
-        )
-      : null
-
-  const STALE_TITLE_TIMEOUT = 3000 // ms before stale working title is cleared
+  const outputProcessor = createPtyOutputProcessor({
+    onTitleChange,
+    onBell,
+    onAgentBecameIdle: (title) => {
+      if (!suppressAttentionEvents) {
+        onAgentBecameIdle?.(title)
+      }
+    },
+    onAgentBecameWorking,
+    onAgentExited,
+    onAgentStatus
+  })
   let storedCallbacks: Parameters<PtyTransport['connect']>[0]['callbacks'] = {}
 
   function unregisterPtyHandlers(id: string): void {
@@ -103,27 +252,6 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
     ptyReplayHandlers.delete(id)
   }
 
-  function applyObservedTerminalTitle(title: string): void {
-    // Why: cursor-agent's native OSC title is the literal string "Cursor Agent"
-    // and it re-emits that title many times per turn (on every internal redraw)
-    // even while it's actively working. Orca drives the cursor spinner/unread
-    // path by injecting its own synthesized "⠋ Cursor Agent" and "Cursor ready"
-    // frames from the hook server (see src/main/index.ts). If we let cursor's
-    // bare title through, it lands in `runtimePaneTitlesByTabId` — where
-    // `getWorktreeStatus` reads from — and flips the sidebar dot back to solid
-    // within a second of the spinner appearing. Dropping the bare title before
-    // it reaches the store leaves the synthesized frame as the last-applied
-    // state until the next hook event overwrites it. Match is literal (trimmed,
-    // case-insensitive) so any task/chat title cursor auto-generates still
-    // passes through unchanged.
-    if (title.trim().toLowerCase() === 'cursor agent') {
-      return
-    }
-    lastEmittedTitle = normalizeTerminalTitle(title)
-    onTitleChange?.(lastEmittedTitle, title)
-    agentTracker?.handleTitle(title)
-  }
-
   // Why: true while we're replaying buffered/attach-time bytes into the
   // terminal. Routes those bytes through onReplayData so the renderer can
   // engage the replay guard — otherwise xterm auto-replies to embedded
@@ -144,78 +272,15 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
       }
     })
     ptyDataHandlers.set(id, (data) => {
-      // Why: OSC 9999 is a renderer-only control protocol. Parse it before
-      // xterm sees the bytes, and keep parser state across chunks so partial
-      // PTY reads do not drop valid status updates or print escape garbage.
-      const processed = processAgentStatusChunk(data)
-      data = processed.cleanData
-      // Why: mirror the onBell / onAgentBecameIdle guard below — during eager-buffer
-      // replay we must not surface stale agent-status payloads from a prior app
-      // session into the live store. The parser still consumes the bytes so they
-      // do not leak into xterm, we just suppress the callback.
-      if (onAgentStatus && !suppressAttentionEvents) {
-        for (const payload of processed.payloads) {
-          onAgentStatus(payload)
-        }
-      }
-      if (replayingBufferedData && storedCallbacks.onReplayData) {
-        storedCallbacks.onReplayData(data)
-      } else {
-        storedCallbacks.onData?.(data)
-      }
-      if (onTitleChange) {
-        // Why: feed EVERY OSC title in the chunk through the observer, not just
-        // the last one. node-pty + the main-process 8ms batch window commonly
-        // coalesce multiple title updates into a single IPC payload — for Pi's
-        // 80ms spinner + agent_end idle cycle, the last title in the chunk is
-        // the idle one and the intermediate working frames were silently
-        // dropped, so the worktree card never observed the working state.
-        // Processing titles in order preserves the working→idle transition
-        // that detectAgentStatusFromTitle and agentTracker both key off.
-        const titles = extractAllOscTitles(data)
-        if (titles.length > 0) {
-          if (staleTitleTimer) {
-            clearTimeout(staleTitleTimer)
-            staleTitleTimer = null
-          }
-          for (const title of titles) {
-            applyObservedTerminalTitle(title)
-          }
-        } else if (lastEmittedTitle && detectAgentStatusFromTitle(lastEmittedTitle) === 'working') {
-          if (staleTitleTimer) {
-            clearTimeout(staleTitleTimer)
-          }
-          staleTitleTimer = setTimeout(() => {
-            staleTitleTimer = null
-            if (lastEmittedTitle && detectAgentStatusFromTitle(lastEmittedTitle) === 'working') {
-              const cleared = clearWorkingIndicators(lastEmittedTitle)
-              lastEmittedTitle = cleared
-              onTitleChange(cleared, cleared)
-              agentTracker?.handleTitle(cleared)
-            }
-          }, STALE_TITLE_TIMEOUT)
-        }
-      }
-      // Why: BEL is the attention signal. The detector is
-      // stateful across chunks so a BEL sitting inside an OSC sequence
-      // (e.g. Claude's `\e]0;title\a`) is correctly ignored — only true
-      // terminal bells raise attention. suppressAttentionEvents gates this
-      // during the synchronous eager-buffer replay so a historical BEL
-      // captured from the prior session does not produce a fresh alert on
-      // cold reattach.
-      if (onBell && bellDetector.chunkContainsBell(data) && !suppressAttentionEvents) {
-        onBell()
-      }
+      outputProcessor.processData(data, storedCallbacks, {
+        replayingBufferedData,
+        suppressAttentionEvents
+      })
     })
   }
 
   function clearAccumulatedState(): void {
-    if (staleTitleTimer) {
-      clearTimeout(staleTitleTimer)
-      staleTitleTimer = null
-    }
-    agentTracker?.reset()
-    bellDetector.reset()
+    outputProcessor.clearAccumulatedState()
   }
 
   function registerPtyExitHandler(id: string): void {
@@ -383,17 +448,14 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
             // working→idle transition (and phantom cache-timer write) for a session
             // that was never live in this app instance. Cancel it so the replay has
             // no lingering side effects.
-            if (staleTitleTimer) {
-              clearTimeout(staleTitleTimer)
-              staleTitleTimer = null
-            }
+            outputProcessor.clearStaleTitleTimer()
             // Why: eager-buffered bytes may end mid-OSC (truncated/partial session
             // data), leaving bellDetector with inOsc = true. Without resetting, the
             // next real BEL in live data would be silently classified as an OSC
             // terminator and dropped. BEL is the sole attention signal per the PR
             // design, so this reset guards the attention pipeline against a silent
             // regression driven by replay state leaking into the live stream.
-            bellDetector.reset()
+            outputProcessor.resetBellDetector()
           }
         }
         bufferHandle.dispose()
diff --git a/src/renderer/src/components/terminal-pane/remote-runtime-pty-batching.ts b/src/renderer/src/components/terminal-pane/remote-runtime-pty-batching.ts
new file mode 100644
index 00000000000..cc86cd5df80
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/remote-runtime-pty-batching.ts
@@ -0,0 +1,81 @@
+export type RemoteRuntimePtyBatcher = {
+  push: (data: string) => void
+  flush: () => void
+  clear: () => void
+}
+
+export type RemoteRuntimeViewportBatcher = {
+  queue: (cols: number, rows: number) => void
+  flush: () => void
+  clear: () => void
+}
+
+export function createRemoteRuntimePtyTextBatcher(
+  delayMs: number,
+  onFlush: (text: string) => void
+): RemoteRuntimePtyBatcher {
+  let pending = ''
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const clear = (): void => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+  }
+
+  const flush = (): void => {
+    const text = pending
+    pending = ''
+    clear()
+    if (text) {
+      onFlush(text)
+    }
+  }
+
+  return {
+    push(data: string): void {
+      pending += data
+      if (!timer) {
+        timer = setTimeout(flush, delayMs)
+      }
+    },
+    flush,
+    clear
+  }
+}
+
+export function createRemoteRuntimeViewportBatcher(
+  delayMs: number,
+  onFlush: (cols: number, rows: number) => void
+): RemoteRuntimeViewportBatcher {
+  let pending: { cols: number; rows: number } | null = null
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const clear = (): void => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+  }
+
+  const flush = (): void => {
+    const viewport = pending
+    pending = null
+    clear()
+    if (viewport) {
+      onFlush(viewport.cols, viewport.rows)
+    }
+  }
+
+  return {
+    queue(cols: number, rows: number): void {
+      pending = { cols, rows }
+      if (!timer) {
+        timer = setTimeout(flush, delayMs)
+      }
+    },
+    flush,
+    clear
+  }
+}
diff --git a/src/renderer/src/components/terminal-pane/remote-runtime-pty-binary-control.ts b/src/renderer/src/components/terminal-pane/remote-runtime-pty-binary-control.ts
new file mode 100644
index 00000000000..be400ee578f
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/remote-runtime-pty-binary-control.ts
@@ -0,0 +1,47 @@
+import {
+  TerminalStreamOpcode,
+  encodeTerminalStreamFrame,
+  encodeTerminalStreamJson,
+  encodeTerminalStreamText
+} from '../../../../shared/terminal-stream-protocol'
+
+export type RemoteRuntimeBinarySender = (bytes: Uint8Array<ArrayBufferLike>) => void
+
+export function sendRemoteRuntimeTerminalInputFrame(
+  sendBinary: RemoteRuntimeBinarySender | null,
+  streamId: number | null,
+  text: string
+): boolean {
+  if (!sendBinary || streamId === null) {
+    return false
+  }
+  sendBinary(
+    encodeTerminalStreamFrame({
+      opcode: TerminalStreamOpcode.Input,
+      streamId,
+      seq: 0,
+      payload: encodeTerminalStreamText(text)
+    })
+  )
+  return true
+}
+
+export function sendRemoteRuntimeTerminalResizeFrame(
+  sendBinary: RemoteRuntimeBinarySender | null,
+  streamId: number | null,
+  cols: number,
+  rows: number
+): boolean {
+  if (!sendBinary || streamId === null) {
+    return false
+  }
+  sendBinary(
+    encodeTerminalStreamFrame({
+      opcode: TerminalStreamOpcode.Resize,
+      streamId,
+      seq: 0,
+      payload: encodeTerminalStreamJson({ cols, rows })
+    })
+  )
+  return true
+}
diff --git a/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.test.ts b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.test.ts
new file mode 100644
index 00000000000..c880d2c7c78
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.test.ts
@@ -0,0 +1,512 @@
+/* eslint-disable max-lines -- Why: remote runtime PTY behavior spans JSON fallback, binary stream, lifecycle, and parser coverage; keeping the matrix together catches transport regressions. */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamJson,
+  decodeTerminalStreamText,
+  encodeTerminalStreamFrame,
+  encodeTerminalStreamJson,
+  encodeTerminalStreamText
+} from '../../../../shared/terminal-stream-protocol'
+
+describe('createRemoteRuntimePtyTransport', () => {
+  const runtimeCall = vi.fn()
+  const runtimeSubscribe = vi.fn()
+  const subscriptionSendBinary = vi.fn()
+  let subscriptionCallbacks: {
+    onResponse: (response: unknown) => void
+    onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+    onError?: (error: { code: string; message: string }) => void
+    onClose?: () => void
+  } | null = null
+
+  function emitMultiplexReady(): void {
+    subscriptionCallbacks?.onResponse({
+      ok: true,
+      result: { type: 'ready' }
+    })
+  }
+
+  function latestSubscribePayload(): {
+    streamId: number
+    terminal: string
+    client: { id: string; type: string }
+    viewport?: { cols: number; rows: number }
+  } {
+    const frames = subscriptionSendBinary.mock.calls
+      .map((call) => decodeTerminalStreamFrame(call[0]))
+      .filter((frame) => frame?.opcode === TerminalStreamOpcode.Subscribe)
+    const frame = frames.at(-1)
+    if (!frame) {
+      throw new Error('missing terminal subscribe frame')
+    }
+    const payload = decodeTerminalStreamJson<{
+      streamId: number
+      terminal: string
+      client: { id: string; type: string }
+      viewport?: { cols: number; rows: number }
+    }>(frame.payload)
+    if (!payload) {
+      throw new Error('invalid terminal subscribe payload')
+    }
+    return payload
+  }
+
+  function emitOutput(streamId: number, data: string): void {
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Output,
+        streamId,
+        seq: 1,
+        payload: encodeTerminalStreamText(data)
+      })
+    )
+  }
+
+  function emitSnapshot(streamId: number, data: string): void {
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.SnapshotStart,
+        streamId,
+        seq: 1,
+        payload: encodeTerminalStreamJson({ kind: 'scrollback' })
+      })
+    )
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.SnapshotChunk,
+        streamId,
+        seq: 2,
+        payload: encodeTerminalStreamText(data)
+      })
+    )
+    subscriptionCallbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.SnapshotEnd,
+        streamId,
+        seq: 3,
+        payload: new Uint8Array()
+      })
+    )
+  }
+
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+    subscriptionCallbacks = null
+    subscriptionSendBinary.mockReset()
+    runtimeCall.mockResolvedValue({ ok: true, result: { terminal: { handle: 'terminal-1' } } })
+    runtimeSubscribe.mockImplementation(
+      async (_args: unknown, callbacks: typeof subscriptionCallbacks) => {
+        subscriptionCallbacks = callbacks
+        queueMicrotask(emitMultiplexReady)
+        return { unsubscribe: vi.fn(), sendBinary: subscriptionSendBinary }
+      }
+    )
+    vi.stubGlobal('window', {
+      api: {
+        runtimeEnvironments: {
+          call: runtimeCall,
+          subscribe: runtimeSubscribe
+        }
+      }
+    })
+  })
+
+  it('attaches to an existing remote runtime terminal handle', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const onError = vi.fn()
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId: 'pane:1'
+    })
+
+    transport.attach({
+      existingPtyId: 'remote:terminal-1',
+      cols: 120,
+      rows: 40,
+      callbacks: { onError }
+    })
+
+    await vi.waitFor(() => {
+      expect(runtimeSubscribe).toHaveBeenCalled()
+    })
+
+    expect(onError).not.toHaveBeenCalled()
+    expect(transport.getPtyId()).toBe('remote:terminal-1')
+    expect(runtimeSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'terminal.multiplex',
+        params: {}
+      }),
+      expect.any(Object)
+    )
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    expect(latestSubscribePayload()).toMatchObject({
+      terminal: 'terminal-1',
+      client: { id: 'desktop:tab-1:pane:1', type: 'desktop' },
+      viewport: { cols: 120, rows: 40 }
+    })
+  })
+
+  it('routes encoded restored terminal ids to their owning runtime environment', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const transport = createRemoteRuntimePtyTransport('env-2', {
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId: 'pane:1'
+    })
+
+    transport.attach({
+      existingPtyId: 'remote:env-1@@terminal-1',
+      cols: 120,
+      rows: 40,
+      callbacks: {}
+    })
+
+    await vi.waitFor(() => {
+      expect(runtimeSubscribe).toHaveBeenCalled()
+    })
+
+    expect(runtimeSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'terminal.multiplex'
+      }),
+      expect.any(Object)
+    )
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    expect(latestSubscribePayload()).toMatchObject({
+      terminal: 'terminal-1',
+      viewport: { cols: 120, rows: 40 }
+    })
+  })
+
+  it('closes a remote terminal created after the pane was destroyed', async () => {
+    let resolveCreate: (value: unknown) => void = () => {}
+    runtimeCall.mockImplementation((args) => {
+      if (args.method === 'terminal.create') {
+        return new Promise((resolve) => {
+          resolveCreate = resolve
+        })
+      }
+      return Promise.resolve({ ok: true, result: {} })
+    })
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId: 'pane:1'
+    })
+
+    const connect = transport.connect({ url: '', callbacks: {} })
+    transport.destroy?.()
+    resolveCreate({ ok: true, result: { terminal: { handle: 'terminal-late' } } })
+    await connect
+
+    expect(runtimeCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'terminal.close',
+      params: { terminal: 'terminal-late' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('unsubscribes a remote terminal subscription that resolves after destroy', async () => {
+    let resolveSubscribe: (value: {
+      unsubscribe: () => void
+      sendBinary: typeof subscriptionSendBinary
+    }) => void = () => {}
+    const unsubscribe = vi.fn()
+    runtimeSubscribe.mockImplementation(
+      (_args: unknown, callbacks: typeof subscriptionCallbacks) => {
+        subscriptionCallbacks = callbacks
+        return new Promise<{ unsubscribe: () => void; sendBinary: typeof subscriptionSendBinary }>(
+          (resolve) => {
+            resolveSubscribe = (value) => {
+              resolve(value)
+              queueMicrotask(emitMultiplexReady)
+            }
+          }
+        )
+      }
+    )
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId: 'pane:1'
+    })
+
+    const connect = transport.connect({ url: '', callbacks: {} })
+    await vi.waitFor(() => {
+      expect(runtimeSubscribe).toHaveBeenCalled()
+    })
+    transport.destroy?.()
+    resolveSubscribe({ unsubscribe, sendBinary: subscriptionSendBinary })
+    await connect
+
+    expect(unsubscribe).toHaveBeenCalled()
+    expect(transport.getPtyId()).toBeNull()
+  })
+
+  it('processes remote data chunks through title, bell, and OSC 9999 handlers before onData', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const onData = vi.fn()
+    const onTitleChange = vi.fn()
+    const onBell = vi.fn()
+    const onAgentStatus = vi.fn()
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      onTitleChange,
+      onBell,
+      onAgentStatus
+    })
+
+    await transport.connect({ url: '', callbacks: { onData } })
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    const { streamId } = latestSubscribePayload()
+    emitOutput(
+      streamId,
+      'before\x1b]9999;{"state":"working","prompt":"ship it","agentType":"codex"}\x07after\x1b]0;. Claude working\x07\x07'
+    )
+
+    expect(onAgentStatus).toHaveBeenCalledWith({
+      state: 'working',
+      prompt: 'ship it',
+      agentType: 'codex'
+    })
+    expect(onData).toHaveBeenCalledWith('beforeafter\x1b]0;. Claude working\x07\x07')
+    expect(onTitleChange).toHaveBeenCalledWith('. Claude working', '. Claude working')
+    expect(onBell).toHaveBeenCalledTimes(1)
+  })
+
+  it('processes binary remote data chunks through the terminal parser', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const onData = vi.fn()
+    const onTitleChange = vi.fn()
+    const onBell = vi.fn()
+    const onAgentStatus = vi.fn()
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      onTitleChange,
+      onBell,
+      onAgentStatus
+    })
+
+    await transport.connect({ url: '', callbacks: { onData } })
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    const { streamId } = latestSubscribePayload()
+    emitOutput(
+      streamId,
+      'before\x1b]9999;{"state":"working","prompt":"ship it","agentType":"codex"}\x07after'
+    )
+
+    expect(onAgentStatus).toHaveBeenCalledWith({
+      state: 'working',
+      prompt: 'ship it',
+      agentType: 'codex'
+    })
+    expect(onData).toHaveBeenCalledWith('beforeafter')
+  })
+
+  it('does not report PTY exit when the remote runtime subscription closes', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const onExit = vi.fn()
+    const onDisconnect = vi.fn()
+    const onPtyExit = vi.fn()
+    const onError = vi.fn()
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId: 'pane:1',
+      onPtyExit
+    })
+
+    await transport.connect({ url: '', callbacks: { onExit, onDisconnect, onError } })
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    subscriptionCallbacks?.onClose?.()
+
+    expect(onExit).not.toHaveBeenCalled()
+    expect(onDisconnect).not.toHaveBeenCalled()
+    expect(onPtyExit).not.toHaveBeenCalled()
+    expect(onError).toHaveBeenCalledWith('Remote Orca runtime closed the connection.')
+    await vi.waitFor(() => expect(runtimeSubscribe).toHaveBeenCalledTimes(2))
+  })
+
+  it('resubscribes with the latest pane viewport after the remote stream closes', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId: 'pane:1'
+    })
+
+    await transport.connect({ url: '', cols: 80, rows: 24, callbacks: {} })
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    expect(latestSubscribePayload().viewport).toEqual({ cols: 80, rows: 24 })
+
+    expect(transport.resize(132, 43)).toBe(true)
+    subscriptionCallbacks?.onClose?.()
+
+    await vi.waitFor(() => expect(runtimeSubscribe).toHaveBeenCalledTimes(2))
+    await vi.waitFor(() => {
+      expect(latestSubscribePayload().viewport).toEqual({ cols: 132, rows: 43 })
+    })
+  })
+
+  it('coalesces rapid remote terminal input before sending it to the runtime', async () => {
+    vi.useFakeTimers()
+    try {
+      const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+      const transport = createRemoteRuntimePtyTransport('env-1', {
+        worktreeId: 'wt-1',
+        tabId: 'tab-1',
+        leafId: 'pane:1'
+      })
+
+      await transport.connect({ url: '', callbacks: {} })
+      const { streamId } = latestSubscribePayload()
+      runtimeCall.mockClear()
+      subscriptionSendBinary.mockClear()
+
+      expect(transport.sendInput('a')).toBe(true)
+      expect(transport.sendInput('b')).toBe(true)
+      expect(runtimeCall).not.toHaveBeenCalled()
+
+      await vi.runOnlyPendingTimersAsync()
+
+      expect(runtimeCall).not.toHaveBeenCalled()
+      expect(subscriptionSendBinary).toHaveBeenCalledTimes(1)
+      const frame = decodeTerminalStreamFrame(subscriptionSendBinary.mock.calls[0][0])
+      expect(frame?.opcode).toBe(TerminalStreamOpcode.Input)
+      expect(frame?.streamId).toBe(streamId)
+      expect(frame ? decodeTerminalStreamText(frame.payload) : '').toBe('ab')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('sends coalesced terminal input as binary frames once the stream is established', async () => {
+    vi.useFakeTimers()
+    try {
+      const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+      const transport = createRemoteRuntimePtyTransport('env-1', {
+        worktreeId: 'wt-1',
+        tabId: 'tab-1',
+        leafId: 'pane:1'
+      })
+
+      await transport.connect({ url: '', callbacks: {} })
+      const { streamId } = latestSubscribePayload()
+      runtimeCall.mockClear()
+      subscriptionSendBinary.mockClear()
+
+      expect(transport.sendInput('a')).toBe(true)
+      expect(transport.sendInput('b')).toBe(true)
+      await vi.runOnlyPendingTimersAsync()
+
+      expect(runtimeCall).not.toHaveBeenCalled()
+      expect(subscriptionSendBinary).toHaveBeenCalledTimes(1)
+      const frame = decodeTerminalStreamFrame(subscriptionSendBinary.mock.calls[0][0])
+      expect(frame?.opcode).toBe(TerminalStreamOpcode.Input)
+      expect(frame?.streamId).toBe(streamId)
+      expect(frame ? decodeTerminalStreamText(frame.payload) : '').toBe('ab')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('coalesces rapid remote viewport updates before sending the latest size', async () => {
+    vi.useFakeTimers()
+    try {
+      const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+      const transport = createRemoteRuntimePtyTransport('env-1', {
+        worktreeId: 'wt-1',
+        tabId: 'tab-1',
+        leafId: 'pane:1'
+      })
+
+      await transport.connect({ url: '', callbacks: {} })
+      const { streamId } = latestSubscribePayload()
+      runtimeCall.mockClear()
+      subscriptionSendBinary.mockClear()
+
+      expect(transport.resize(80, 24)).toBe(true)
+      expect(transport.resize(120, 40)).toBe(true)
+      expect(runtimeCall).not.toHaveBeenCalled()
+
+      await vi.runOnlyPendingTimersAsync()
+
+      expect(runtimeCall).not.toHaveBeenCalled()
+      expect(subscriptionSendBinary).toHaveBeenCalledTimes(1)
+      const frame = decodeTerminalStreamFrame(subscriptionSendBinary.mock.calls[0][0])
+      expect(frame?.opcode).toBe(TerminalStreamOpcode.Resize)
+      expect(frame?.streamId).toBe(streamId)
+      expect(frame ? decodeTerminalStreamJson(frame.payload) : null).toEqual({
+        cols: 120,
+        rows: 40
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('replays remote scrollback through the parser without firing stale attention events', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const onReplayData = vi.fn()
+    const onTitleChange = vi.fn()
+    const onBell = vi.fn()
+    const onAgentStatus = vi.fn()
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      onTitleChange,
+      onBell,
+      onAgentStatus
+    })
+
+    await transport.connect({ url: '', callbacks: { onReplayData } })
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    const { streamId } = latestSubscribePayload()
+    emitSnapshot(
+      streamId,
+      'before\x1b]9999;{"state":"working","prompt":"old","agentType":"codex"}\x07after\x1b]0;Remote title\x07\x07'
+    )
+
+    expect(onReplayData).toHaveBeenCalledWith('beforeafter\x1b]0;Remote title\x07\x07')
+    expect(onTitleChange).toHaveBeenCalledWith('Remote title', 'Remote title')
+    expect(onAgentStatus).not.toHaveBeenCalled()
+    expect(onBell).not.toHaveBeenCalled()
+  })
+
+  it('replays binary snapshot chunks without firing stale attention events', async () => {
+    const { createRemoteRuntimePtyTransport } = await import('./remote-runtime-pty-transport')
+    const onReplayData = vi.fn()
+    const onTitleChange = vi.fn()
+    const onBell = vi.fn()
+    const onAgentStatus = vi.fn()
+    const onConnect = vi.fn()
+    const transport = createRemoteRuntimePtyTransport('env-1', {
+      worktreeId: 'wt-1',
+      onTitleChange,
+      onBell,
+      onAgentStatus
+    })
+
+    await transport.connect({ url: '', callbacks: { onReplayData, onConnect } })
+    await vi.waitFor(() => expect(subscriptionSendBinary).toHaveBeenCalled())
+    const { streamId } = latestSubscribePayload()
+    emitSnapshot(
+      streamId,
+      'before\x1b]9999;{"state":"working","prompt":"old","agentType":"codex"}\x07after'
+    )
+
+    expect(onReplayData).toHaveBeenCalledWith('beforeafter')
+    expect(onAgentStatus).not.toHaveBeenCalled()
+    expect(onBell).not.toHaveBeenCalled()
+    expect(onConnect).toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
new file mode 100644
index 00000000000..5f2d890a206
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
@@ -0,0 +1,324 @@
+/* eslint-disable max-lines -- Why: remote PTY transport keeps lifecycle, JSON fallback, and binary stream wiring together so reconnect/destroy ordering stays testable as one behavior surface. */
+import type { RuntimeRpcResponse } from '../../../../shared/runtime-rpc-envelope'
+import type { RuntimeTerminalCreate } from '../../../../shared/runtime-types'
+import type { PtyConnectResult, PtyTransport, IpcPtyTransportOptions } from './pty-dispatcher'
+import { createPtyOutputProcessor } from './pty-transport'
+import { unwrapRuntimeRpcResult } from '../../runtime/runtime-rpc-client'
+import {
+  getRemoteRuntimePtyEnvironmentId,
+  getRemoteRuntimeTerminalHandle,
+  runtimeTerminalErrorMessage,
+  toRemoteRuntimePtyId
+} from '../../runtime/runtime-terminal-stream'
+import {
+  getRemoteRuntimeTerminalMultiplexer,
+  type RemoteRuntimeMultiplexedTerminal
+} from '../../runtime/remote-runtime-terminal-multiplexer'
+import {
+  createRemoteRuntimePtyTextBatcher,
+  createRemoteRuntimeViewportBatcher
+} from './remote-runtime-pty-batching'
+import { setFitOverride } from '@/lib/pane-manager/mobile-fit-overrides'
+import { setDriverForPty } from '@/lib/pane-manager/mobile-driver-state'
+
+const REMOTE_TERMINAL_INPUT_FLUSH_MS = 8
+const REMOTE_TERMINAL_VIEWPORT_FLUSH_MS = 33
+
+export function createRemoteRuntimePtyTransport(
+  runtimeEnvironmentId: string,
+  opts: IpcPtyTransportOptions = {}
+): PtyTransport {
+  const {
+    command,
+    env,
+    worktreeId,
+    tabId,
+    leafId,
+    onPtyExit,
+    onPtySpawn,
+    onTitleChange,
+    onBell,
+    onAgentBecameIdle,
+    onAgentBecameWorking,
+    onAgentExited,
+    onAgentStatus
+  } = opts
+  let connected = false
+  let destroyed = false
+  let handle: string | null = null
+  let remotePtyId: string | null = null
+  let currentRuntimeEnvironmentId = runtimeEnvironmentId
+  let multiplexedStream: RemoteRuntimeMultiplexedTerminal | null = null
+  let desiredViewport: { cols: number; rows: number } | null = null
+  let storedCallbacks: Parameters<PtyTransport['connect']>[0]['callbacks'] = {}
+  let resubscribing = false
+  const clientId = `desktop:${tabId ?? 'tab'}:${leafId ?? 'leaf'}`
+  const outputProcessor = createPtyOutputProcessor({
+    onTitleChange,
+    onBell,
+    onAgentBecameIdle,
+    onAgentBecameWorking,
+    onAgentExited,
+    onAgentStatus
+  })
+
+  async function callRuntime<TResult>(method: string, params?: unknown): Promise<TResult> {
+    const response = await window.api.runtimeEnvironments.call({
+      selector: currentRuntimeEnvironmentId,
+      method,
+      params,
+      timeoutMs: 15_000
+    })
+    return unwrapRuntimeRpcResult(response as RuntimeRpcResponse<TResult>)
+  }
+
+  async function closeRemoteTerminal(handleOverride?: string): Promise<void> {
+    const targetHandle = handleOverride ?? handle
+    if (!targetHandle) {
+      return
+    }
+    try {
+      await callRuntime('terminal.close', { terminal: targetHandle })
+    } catch {
+      // Best-effort parity with local disconnect/kill.
+    }
+  }
+
+  const inputBatcher = createRemoteRuntimePtyTextBatcher(REMOTE_TERMINAL_INPUT_FLUSH_MS, (text) => {
+    const targetHandle = handle
+    if (!connected || !targetHandle) {
+      return
+    }
+    if (multiplexedStream?.sendInput(text)) {
+      return
+    }
+    void callRuntime('terminal.send', {
+      terminal: targetHandle,
+      text,
+      client: { id: clientId, type: 'desktop' }
+    })
+  })
+
+  function sendViewportUpdate(cols: number, rows: number): void {
+    const targetHandle = handle
+    if (!connected || !targetHandle) {
+      return
+    }
+    if (multiplexedStream?.resize(cols, rows)) {
+      return
+    }
+    void callRuntime('terminal.updateViewport', {
+      terminal: targetHandle,
+      client: { id: clientId, type: 'desktop' },
+      viewport: { cols, rows }
+    }).catch(() => {})
+  }
+
+  const viewportBatcher = createRemoteRuntimeViewportBatcher(
+    REMOTE_TERMINAL_VIEWPORT_FLUSH_MS,
+    sendViewportUpdate
+  )
+
+  function rememberViewport(cols: number, rows: number): void {
+    desiredViewport = { cols, rows }
+  }
+
+  async function subscribeToHandle(): Promise<void> {
+    if (!handle) {
+      return
+    }
+    const subscribedHandle = handle
+    const nextStream = await getRemoteRuntimeTerminalMultiplexer(
+      currentRuntimeEnvironmentId
+    ).subscribeTerminal({
+      terminal: subscribedHandle,
+      client: { id: clientId, type: 'desktop' },
+      viewport: desiredViewport ?? undefined,
+      callbacks: {
+        onData: (data) => outputProcessor.processData(data, storedCallbacks),
+        onSnapshot: (data) => {
+          if (data) {
+            outputProcessor.processData(data, storedCallbacks, {
+              replayingBufferedData: true,
+              suppressAttentionEvents: true
+            })
+          }
+        },
+        onSubscribed: () => {
+          storedCallbacks.onConnect?.()
+          storedCallbacks.onStatus?.('shell')
+        },
+        onEnd: () => {
+          outputProcessor.clearAccumulatedState()
+          connected = false
+          storedCallbacks.onExit?.(0)
+          storedCallbacks.onDisconnect?.()
+          if (remotePtyId) {
+            onPtyExit?.(remotePtyId)
+          }
+        },
+        onError: (message) => storedCallbacks.onError?.(message),
+        onFitOverrideChanged: (event) => {
+          if (remotePtyId) {
+            setFitOverride(remotePtyId, event.mode, event.cols, event.rows)
+          }
+        },
+        onDriverChanged: (driver) => {
+          if (remotePtyId) {
+            setDriverForPty(remotePtyId, driver)
+          }
+        },
+        onTransportClose: () => {
+          multiplexedStream = null
+          if (destroyed || !connected || !handle || resubscribing) {
+            return
+          }
+          resubscribing = true
+          void subscribeToHandle()
+            .catch((error) => storedCallbacks.onError?.(runtimeTerminalErrorMessage(error)))
+            .finally(() => {
+              resubscribing = false
+            })
+        }
+      }
+    })
+    if (destroyed || !connected || handle !== subscribedHandle) {
+      nextStream.close()
+      return
+    }
+    multiplexedStream = nextStream
+  }
+
+  return {
+    async connect(options) {
+      storedCallbacks = options.callbacks
+      if (destroyed || !worktreeId) {
+        return
+      }
+
+      try {
+        const created = await callRuntime<{ terminal: RuntimeTerminalCreate }>('terminal.create', {
+          worktree: worktreeId,
+          command,
+          env,
+          focus: false
+        })
+        handle = created.terminal.handle
+        if (destroyed) {
+          await closeRemoteTerminal(created.terminal.handle)
+          return
+        }
+
+        remotePtyId = toRemoteRuntimePtyId(handle, currentRuntimeEnvironmentId)
+        connected = true
+        desiredViewport = {
+          cols: options.cols ?? 80,
+          rows: options.rows ?? 24
+        }
+        onPtySpawn?.(remotePtyId)
+
+        await subscribeToHandle()
+        if (destroyed || !connected || !remotePtyId) {
+          return
+        }
+
+        return {
+          id: remotePtyId,
+          replay: ''
+        } satisfies PtyConnectResult
+      } catch (error) {
+        storedCallbacks.onError?.(runtimeTerminalErrorMessage(error))
+        return undefined
+      }
+    },
+
+    attach(options) {
+      storedCallbacks = options.callbacks
+      currentRuntimeEnvironmentId =
+        getRemoteRuntimePtyEnvironmentId(options.existingPtyId) ?? runtimeEnvironmentId
+      handle = getRemoteRuntimeTerminalHandle(options.existingPtyId)
+      if (!handle) {
+        connected = false
+        remotePtyId = null
+        storedCallbacks.onError?.('Remote runtime terminal id is invalid.')
+        return
+      }
+      remotePtyId = options.existingPtyId
+      connected = true
+      desiredViewport = {
+        cols: options.cols ?? 80,
+        rows: options.rows ?? 24
+      }
+      void subscribeToHandle().catch((error) => {
+        connected = false
+        storedCallbacks.onError?.(runtimeTerminalErrorMessage(error))
+      })
+    },
+
+    disconnect() {
+      inputBatcher.flush()
+      viewportBatcher.flush()
+      outputProcessor.clearAccumulatedState()
+      if (!connected && !handle) {
+        return
+      }
+      connected = false
+      const id = remotePtyId
+      multiplexedStream?.close()
+      multiplexedStream = null
+      void closeRemoteTerminal()
+      handle = null
+      remotePtyId = null
+      storedCallbacks.onDisconnect?.()
+      if (id) {
+        onPtyExit?.(id)
+      }
+    },
+
+    detach() {
+      inputBatcher.flush()
+      viewportBatcher.flush()
+      outputProcessor.clearAccumulatedState()
+      connected = false
+      multiplexedStream?.close()
+      multiplexedStream = null
+      storedCallbacks = {}
+    },
+
+    sendInput(data: string): boolean {
+      if (!connected || !handle) {
+        return false
+      }
+      // Why: remote terminal input currently crosses the runtime RPC boundary;
+      // coalescing same-frame key bursts avoids a per-keystroke remote round-trip.
+      inputBatcher.push(data)
+      return true
+    },
+
+    resize(cols: number, rows: number): boolean {
+      if (!connected || !handle) {
+        return false
+      }
+      rememberViewport(cols, rows)
+      // Why: xterm fit can emit resize bursts while the user drags panes or
+      // restores layouts. Remote runtimes only need the last viewport in a frame.
+      viewportBatcher.queue(cols, rows)
+      return true
+    },
+
+    isConnected() {
+      return connected
+    },
+
+    getPtyId() {
+      return remotePtyId
+    },
+
+    destroy() {
+      destroyed = true
+      this.disconnect()
+      inputBatcher.clear()
+      viewportBatcher.clear()
+    }
+  }
+}
diff --git a/src/renderer/src/components/terminal-pane/resolve-split-cwd.test.ts b/src/renderer/src/components/terminal-pane/resolve-split-cwd.test.ts
index fe8f89c5f7c..3420f1806d1 100644
--- a/src/renderer/src/components/terminal-pane/resolve-split-cwd.test.ts
+++ b/src/renderer/src/components/terminal-pane/resolve-split-cwd.test.ts
@@ -3,7 +3,12 @@ import { resolveSplitCwd, type PaneCwdMap } from './resolve-split-cwd'
 
 function installGetCwd(fn: (id: string) => Promise<string>): void {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test-only shim for window.api.pty.getCwd
-  ;(globalThis as any).window = { api: { pty: { getCwd: fn } } }
+  ;(globalThis as any).window = {
+    api: {
+      pty: { getCwd: fn },
+      runtimeEnvironments: { call: vi.fn() }
+    }
+  }
 }
 
 describe('resolveSplitCwd', () => {
@@ -104,4 +109,17 @@ describe('resolveSplitCwd', () => {
     expect(result).toBe('/worktree')
     expect(getCwd).not.toHaveBeenCalled()
   })
+
+  it('skips local PTY IPC for remote runtime PTY ids', async () => {
+    const getCwd = vi.fn()
+    installGetCwd(getCwd as unknown as (id: string) => Promise<string>)
+    const result = await resolveSplitCwd({
+      paneCwdMap: new Map(),
+      sourcePaneId: 1,
+      sourcePtyId: 'remote:term-1',
+      fallbackCwd: '/remote/worktree'
+    })
+    expect(result).toBe('/remote/worktree')
+    expect(getCwd).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/components/terminal-pane/resolve-split-cwd.ts b/src/renderer/src/components/terminal-pane/resolve-split-cwd.ts
index ce06202350c..300543d4718 100644
--- a/src/renderer/src/components/terminal-pane/resolve-split-cwd.ts
+++ b/src/renderer/src/components/terminal-pane/resolve-split-cwd.ts
@@ -3,6 +3,7 @@
 // `/proc`-or-lsof-backed IPC fallback for shells that never emit OSC 7 (agent
 // TUIs, minimal sh). Both layers can legitimately come back empty, so the
 // helper always finishes by returning the caller's worktree-root fallback.
+import { isRemoteRuntimePtyId } from '@/runtime/runtime-terminal-inspection'
 
 export type PaneCwdEntry = { cwd: string; confirmed: boolean }
 
@@ -32,7 +33,7 @@ export async function resolveSplitCwd(args: {
 
   // 2) Ask the PTY provider (/proc or lsof). Enforce a soft timeout
   //    renderer-side so a slow SSH relay can't stall the split.
-  if (sourcePtyId) {
+  if (sourcePtyId && !isRemoteRuntimePtyId(sourcePtyId)) {
     try {
       const ipcCwd = await Promise.race<string | null>([
         window.api.pty.getCwd(sourcePtyId).catch(() => null),
diff --git a/src/renderer/src/components/terminal-pane/terminal-drop-handler.test.ts b/src/renderer/src/components/terminal-pane/terminal-drop-handler.test.ts
new file mode 100644
index 00000000000..2a4a29743c5
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-drop-handler.test.ts
@@ -0,0 +1,166 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  toastLoading: vi.fn(() => 'toast-1'),
+  toastDismiss: vi.fn(),
+  toastError: vi.fn(),
+  importExternalPathsToRuntime: vi.fn(),
+  storeState: {
+    settings: { activeRuntimeEnvironmentId: 'env-1' as string | null },
+    worktreesByRepo: {
+      repo1: [{ id: 'wt-1', path: '/remote/repo' }]
+    }
+  }
+}))
+
+vi.mock('sonner', () => ({
+  toast: {
+    loading: mocks.toastLoading,
+    dismiss: mocks.toastDismiss,
+    error: mocks.toastError,
+    message: vi.fn()
+  }
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: {
+    getState: () => mocks.storeState
+  }
+}))
+
+vi.mock('@/runtime/runtime-file-client', () => ({
+  importExternalPathsToRuntime: mocks.importExternalPathsToRuntime
+}))
+
+import { handleTerminalFileDrop, resolveTerminalDropTargetShell } from './terminal-drop-handler'
+
+describe('handleTerminalFileDrop', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.storeState.settings = { activeRuntimeEnvironmentId: 'env-1' }
+    mocks.storeState.worktreesByRepo = {
+      repo1: [{ id: 'wt-1', path: '/remote/repo' }]
+    }
+  })
+
+  it('uploads client-local drops into the active runtime before pasting paths', async () => {
+    mocks.importExternalPathsToRuntime.mockResolvedValue({
+      results: [
+        {
+          sourcePath: '/Users/me/logo.png',
+          status: 'imported',
+          destPath: '/remote/repo/.orca/drops/logo.png',
+          kind: 'file',
+          renamed: false
+        }
+      ]
+    })
+    const sendInput = vi.fn()
+    const focus = vi.fn()
+    const manager = {
+      getActivePane: () => ({ id: 1, terminal: { focus } }),
+      getPanes: () => []
+    }
+    const paneTransports = new Map([[1, { sendInput }]])
+
+    await handleTerminalFileDrop({
+      manager: manager as never,
+      paneTransports: paneTransports as never,
+      worktreeId: 'wt-1',
+      cwd: undefined,
+      data: { paths: ['/Users/me/logo.png'], target: 'terminal' }
+    })
+
+    expect(mocks.importExternalPathsToRuntime).toHaveBeenCalledWith(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '/remote/repo'
+      },
+      ['/Users/me/logo.png'],
+      '/remote/repo/.orca/drops'
+    )
+    expect(sendInput).toHaveBeenCalledWith('/remote/repo/.orca/drops/logo.png ')
+    expect(focus).toHaveBeenCalled()
+    expect(mocks.toastError).not.toHaveBeenCalled()
+    expect(mocks.toastDismiss).toHaveBeenCalledWith('toast-1')
+  })
+
+  it('uses Windows shell paths for forward-slash UNC runtime worktrees', async () => {
+    mocks.storeState.worktreesByRepo = {
+      repo1: [{ id: 'wt-1', path: '//server/share/repo' }]
+    }
+    mocks.importExternalPathsToRuntime.mockResolvedValue({
+      results: [
+        {
+          sourcePath: '/Users/me/logo.png',
+          status: 'imported',
+          destPath: '//server/share/repo\\.orca\\drops\\logo.png',
+          kind: 'file',
+          renamed: false
+        }
+      ]
+    })
+    const sendInput = vi.fn()
+    const focus = vi.fn()
+    const manager = {
+      getActivePane: () => ({ id: 1, terminal: { focus } }),
+      getPanes: () => []
+    }
+    const paneTransports = new Map([[1, { sendInput }]])
+
+    await handleTerminalFileDrop({
+      manager: manager as never,
+      paneTransports: paneTransports as never,
+      worktreeId: 'wt-1',
+      cwd: undefined,
+      data: { paths: ['/Users/me/logo.png'], target: 'terminal' }
+    })
+
+    expect(mocks.importExternalPathsToRuntime).toHaveBeenCalledWith(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '//server/share/repo'
+      },
+      ['/Users/me/logo.png'],
+      '\\\\server\\share\\repo\\.orca\\drops'
+    )
+    expect(sendInput).toHaveBeenCalledWith('\\\\server\\share\\repo\\.orca\\drops\\logo.png ')
+  })
+})
+
+describe('resolveTerminalDropTargetShell', () => {
+  it('uses runtime worktree path shape for active Windows runtimes', () => {
+    expect(
+      resolveTerminalDropTargetShell({
+        activeRuntimeEnvironmentId: 'env-1',
+        worktreePath: '//Server/Share/Repo',
+        connectionId: null,
+        userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)'
+      })
+    ).toBe('windows')
+  })
+
+  it('uses runtime worktree path shape for active POSIX runtimes', () => {
+    expect(
+      resolveTerminalDropTargetShell({
+        activeRuntimeEnvironmentId: 'env-1',
+        worktreePath: '/home/orca/repo',
+        connectionId: null,
+        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
+      })
+    ).toBe('posix')
+  })
+
+  it('keeps legacy SSH drops POSIX when no runtime environment is active', () => {
+    expect(
+      resolveTerminalDropTargetShell({
+        activeRuntimeEnvironmentId: null,
+        worktreePath: 'C:\\repo',
+        connectionId: 'ssh-1',
+        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
+      })
+    ).toBe('posix')
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-drop-handler.ts b/src/renderer/src/components/terminal-pane/terminal-drop-handler.ts
index 52220bf6af4..df4677e2719 100644
--- a/src/renderer/src/components/terminal-pane/terminal-drop-handler.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-drop-handler.ts
@@ -5,6 +5,8 @@ import type { PaneManager } from '@/lib/pane-manager/pane-manager'
 import { useAppStore } from '@/store'
 import { isWindowsUserAgent, shellEscapePath } from './pane-helpers'
 import type { PtyTransport } from './pty-transport'
+import { importExternalPathsToRuntime } from '@/runtime/runtime-file-client'
+import { isWindowsAbsolutePathLike } from '../../../../shared/cross-platform-path'
 
 type Args = {
   manager: PaneManager
@@ -14,6 +16,32 @@ type Args = {
   data: { paths: string[]; target: string; tabId?: string }
 }
 
+export type TerminalTargetShell = 'posix' | 'windows'
+
+export function getTerminalTargetShellForWorktreePath(worktreePath: string): TerminalTargetShell {
+  return isWindowsPathLike(worktreePath) ? 'windows' : 'posix'
+}
+
+export function resolveTerminalDropTargetShell({
+  activeRuntimeEnvironmentId,
+  worktreePath,
+  connectionId,
+  userAgent
+}: {
+  activeRuntimeEnvironmentId: string | null | undefined
+  worktreePath: string | null | undefined
+  connectionId: string | null | undefined
+  userAgent?: string
+}): TerminalTargetShell {
+  if (activeRuntimeEnvironmentId?.trim() && worktreePath) {
+    return getTerminalTargetShellForWorktreePath(worktreePath)
+  }
+  if (typeof connectionId === 'string') {
+    return 'posix'
+  }
+  return isWindowsUserAgent(userAgent) ? 'windows' : 'posix'
+}
+
 /**
  * Handle a native file drop targeted at a terminal pane.
  *
@@ -36,6 +64,51 @@ export async function handleTerminalFileDrop(args: Args): Promise<void> {
   if (!transport) {
     return
   }
+  const settings = useAppStore.getState().settings
+  const activeRuntimeEnvironmentId = settings?.activeRuntimeEnvironmentId?.trim()
+  const worktreePath = resolveWorktreePath(worktreeId, cwd)
+  if (!worktreePath) {
+    toast.error('Worktree path not available.')
+    return
+  }
+
+  if (activeRuntimeEnvironmentId) {
+    const targetShell = getTerminalTargetShellForWorktreePath(worktreePath)
+    const destinationDir = joinRuntimeDropDir(worktreePath)
+    const pending = toast.loading(
+      `Uploading ${data.paths.length} file${data.paths.length === 1 ? '' : 's'} to runtime…`
+    )
+    try {
+      const { results } = await importExternalPathsToRuntime(
+        {
+          settings,
+          worktreeId,
+          worktreePath
+        },
+        data.paths,
+        destinationDir
+      )
+      const imported = results.filter((result) => result.status === 'imported')
+      const skipped = results.filter((result) => result.status === 'skipped')
+      const failed = results.filter((result) => result.status === 'failed')
+      const liveTransport = paneTransports.get(paneId)
+      if (liveTransport) {
+        for (const result of imported) {
+          const shellPath = isWindowsPathLike(worktreePath)
+            ? result.destPath.replace(/\//g, '\\')
+            : result.destPath
+          liveTransport.sendInput(`${shellEscapePath(shellPath, targetShell)} `)
+        }
+        pane.terminal.focus()
+      }
+      reportUploadSkipsAndFailures(skipped, failed)
+    } catch (err) {
+      toast.error(extractIpcErrorMessage(err, 'Failed to upload files.'))
+    } finally {
+      toast.dismiss(pending)
+    }
+    return
+  }
 
   // Why: `getConnectionId` returns `string` (SSH), `null` (local repo found),
   // or `undefined` (store not hydrated / worktree not found). Treat
@@ -47,11 +120,11 @@ export async function handleTerminalFileDrop(args: Args): Promise<void> {
     return
   }
   const isRemote = connectionId !== null
-  const targetShell: 'posix' | 'windows' = isRemote
-    ? 'posix'
-    : isWindowsUserAgent()
-      ? 'windows'
-      : 'posix'
+  const targetShell = resolveTerminalDropTargetShell({
+    activeRuntimeEnvironmentId: null,
+    worktreePath,
+    connectionId
+  })
 
   // Why: local fast path — no IPC round-trip, no toast — preserves today's
   // zero-latency drop behavior. Trailing space separates multiple paths in
@@ -64,12 +137,6 @@ export async function handleTerminalFileDrop(args: Args): Promise<void> {
     return
   }
 
-  const worktreePath = resolveWorktreePath(worktreeId, cwd)
-  if (!worktreePath) {
-    toast.error('Worktree path not available.')
-    return
-  }
-
   const pending = toast.loading(
     `Uploading ${data.paths.length} file${data.paths.length === 1 ? '' : 's'} to remote…`
   )
@@ -90,22 +157,7 @@ export async function handleTerminalFileDrop(args: Args): Promise<void> {
       }
       pane.terminal.focus()
     }
-    if (skipped.length > 0) {
-      // Why: symlink rejection is policy, not error — show as neutral
-      // message. Mixed skips collapse to a single "items" count to avoid
-      // enumerating every reason.
-      const symlinkCount = skipped.filter((s) => s.reason === 'symlink').length
-      const noun = skipped.length === 1 ? 'item' : 'items'
-      toast.message(
-        symlinkCount === skipped.length
-          ? `Skipped ${skipped.length} symlink${skipped.length === 1 ? '' : 's'}.`
-          : `Skipped ${skipped.length} ${noun}.`
-      )
-    }
-    if (failed.length > 0) {
-      const noun = failed.length === 1 ? 'file' : 'files'
-      toast.error(`Failed to upload ${failed.length} ${noun}.`)
-    }
+    reportUploadSkipsAndFailures(skipped, failed)
   } catch (err) {
     toast.error(extractIpcErrorMessage(err, 'Failed to upload files.'))
   } finally {
@@ -113,9 +165,42 @@ export async function handleTerminalFileDrop(args: Args): Promise<void> {
   }
 }
 
+function reportUploadSkipsAndFailures(
+  skipped: { reason: string }[],
+  failed: { reason: string }[]
+): void {
+  if (skipped.length > 0) {
+    // Why: symlink rejection is policy, not error — show as neutral
+    // message. Mixed skips collapse to a single "items" count to avoid
+    // enumerating every reason.
+    const symlinkCount = skipped.filter((s) => s.reason === 'symlink').length
+    const noun = skipped.length === 1 ? 'item' : 'items'
+    toast.message(
+      symlinkCount === skipped.length
+        ? `Skipped ${skipped.length} symlink${skipped.length === 1 ? '' : 's'}.`
+        : `Skipped ${skipped.length} ${noun}.`
+    )
+  }
+  if (failed.length > 0) {
+    const noun = failed.length === 1 ? 'file' : 'files'
+    toast.error(`Failed to upload ${failed.length} ${noun}.`)
+  }
+}
+
 function resolveWorktreePath(worktreeId: string, fallbackCwd: string | undefined): string | null {
   const state = useAppStore.getState()
   const allWorktrees = Object.values(state.worktreesByRepo ?? {}).flat()
   const worktree = allWorktrees.find((w) => w.id === worktreeId)
   return worktree?.path ?? fallbackCwd ?? null
 }
+
+function joinRuntimeDropDir(worktreePath: string): string {
+  if (isWindowsPathLike(worktreePath)) {
+    return `${worktreePath.replace(/[\\/]+$/, '').replace(/\//g, '\\')}\\.orca\\drops`
+  }
+  return `${worktreePath.replace(/[\\/]+$/, '')}/.orca/drops`
+}
+
+function isWindowsPathLike(path: string): boolean {
+  return isWindowsAbsolutePathLike(path) || path.includes('\\')
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts b/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts
index d767824bf70..5aa8b5766e2 100644
--- a/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: terminal link routing has intertwined local,
+SSH, and runtime cases; keeping them in one suite prevents fixture drift. */
 import type { IDisposable, ILink } from '@xterm/xterm'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { PaneManager } from '@/lib/pane-manager/pane-manager'
@@ -9,18 +11,29 @@ import {
   openDetectedFilePath
 } from './terminal-link-handlers'
 import { registerHttpLinkStoreAccessor } from '@/lib/http-link-routing'
+import { getConnectionId } from '@/lib/connection-context'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '@/runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '@/runtime/runtime-rpc-client'
 
 const openUrlMock = vi.fn()
 const openFileUriMock = vi.fn()
+const openFilePathMock = vi.fn()
 const openFileMock = vi.fn()
 const authorizeExternalPathMock = vi.fn()
 const statMock = vi.fn().mockResolvedValue({ isDirectory: false })
+const runtimeEnvironmentCallMock = vi.fn()
+const runtimeEnvironmentTransportCallMock = vi.fn()
 const setActiveWorktreeMock = vi.fn()
 const createBrowserTabMock = vi.fn()
 
 const deps = { worktreeId: 'wt-1', worktreePath: '/tmp' }
 const storeState = {
-  settings: undefined as { openLinksInApp?: boolean } | undefined,
+  settings: undefined as
+    | { openLinksInApp?: boolean; activeRuntimeEnvironmentId?: string | null }
+    | undefined,
   setActiveWorktree: setActiveWorktreeMock,
   createBrowserTab: createBrowserTabMock,
   openFile: openFileMock
@@ -44,12 +57,22 @@ vi.mock('@/lib/worktree-activation', () => ({
   activateAndRevealWorktree: vi.fn()
 }))
 
+vi.mock('@/lib/connection-context', () => ({
+  getConnectionId: vi.fn(() => null)
+}))
+
 function setPlatform(userAgent: string): void {
   vi.stubGlobal('navigator', { userAgent })
 }
 
 beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
   vi.clearAllMocks()
+  runtimeEnvironmentTransportCallMock.mockReset()
+  runtimeEnvironmentTransportCallMock.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCallMock(args)
+  })
+  vi.mocked(getConnectionId).mockReturnValue(null)
   storeState.settings = undefined
   registerHttpLinkStoreAccessor(() => storeState)
   vi.stubGlobal('window', {
@@ -57,12 +80,14 @@ beforeEach(() => {
       shell: {
         openUrl: openUrlMock,
         openFileUri: openFileUriMock,
+        openFilePath: openFilePathMock,
         pathExists: vi.fn().mockResolvedValue(true)
       },
       fs: {
         authorizeExternalPath: authorizeExternalPathMock,
         stat: statMock
-      }
+      },
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCallMock }
     }
   })
 })
@@ -240,6 +265,127 @@ describe('handleOscLink', () => {
       })
     )
   })
+
+  it('stats remote-runtime file links through the active runtime environment', async () => {
+    setPlatform('Macintosh')
+    storeState.settings = { activeRuntimeEnvironmentId: 'env-1' }
+    runtimeEnvironmentCallMock.mockResolvedValueOnce({
+      id: 'rpc-1',
+      ok: true,
+      result: { size: 1, isDirectory: false, mtime: 1 },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    openDetectedFilePath('/tmp/src/main.ts', null, null, deps)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(authorizeExternalPathMock).not.toHaveBeenCalled()
+    expect(statMock).not.toHaveBeenCalled()
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.stat',
+        params: { worktree: 'wt-1', relativePath: 'src/main.ts' },
+        timeoutMs: 15_000
+      })
+    })
+    expect(openFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        filePath: '/tmp/src/main.ts',
+        relativePath: 'src/main.ts'
+      })
+    )
+  })
+
+  it('stats remote-runtime file links through the owning PTY runtime environment', async () => {
+    setPlatform('Macintosh')
+    storeState.settings = { activeRuntimeEnvironmentId: 'env-2' }
+    runtimeEnvironmentCallMock.mockResolvedValueOnce({
+      id: 'rpc-1',
+      ok: true,
+      result: { size: 1, isDirectory: false, mtime: 1 },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    openDetectedFilePath('/tmp/src/main.ts', null, null, {
+      ...deps,
+      runtimeEnvironmentId: 'env-1'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.stat',
+        params: { worktree: 'wt-1', relativePath: 'src/main.ts' },
+        timeoutMs: 15_000
+      })
+    })
+    expect(openFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        filePath: '/tmp/src/main.ts',
+        relativePath: 'src/main.ts',
+        runtimeEnvironmentId: 'env-1'
+      })
+    )
+  })
+
+  it('opens SSH file links through Orca without local authorization', async () => {
+    setPlatform('Macintosh')
+    vi.mocked(getConnectionId).mockReturnValue('ssh-1')
+
+    openDetectedFilePath('/home/me/repo/src/main.ts', null, null, {
+      worktreeId: 'wt-1',
+      worktreePath: '/home/me/repo'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(authorizeExternalPathMock).not.toHaveBeenCalled()
+    expect(statMock).toHaveBeenCalledWith({
+      filePath: '/home/me/repo/src/main.ts',
+      connectionId: 'ssh-1'
+    })
+    expect(openFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        filePath: '/home/me/repo/src/main.ts',
+        relativePath: 'src/main.ts'
+      })
+    )
+  })
+
+  it('does not open SSH html file links as client-local file browser tabs', async () => {
+    setPlatform('Macintosh')
+    vi.mocked(getConnectionId).mockReturnValue('ssh-1')
+
+    openDetectedFilePath('/home/me/repo/report.html', null, null, {
+      worktreeId: 'wt-1',
+      worktreePath: '/home/me/repo'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(createBrowserTabMock).not.toHaveBeenCalled()
+    expect(openFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        filePath: '/home/me/repo/report.html',
+        relativePath: 'report.html'
+      })
+    )
+  })
+
+  it('does not ask the client OS to open SSH directories', async () => {
+    setPlatform('Macintosh')
+    vi.mocked(getConnectionId).mockReturnValue('ssh-1')
+    statMock.mockResolvedValueOnce({ isDirectory: true })
+
+    openDetectedFilePath('/home/me/repo/src', null, null, {
+      worktreeId: 'wt-1',
+      worktreePath: '/home/me/repo'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(openFilePathMock).not.toHaveBeenCalled()
+    expect(openFileMock).not.toHaveBeenCalled()
+  })
 })
 
 describe('createFilePathLinkProvider range bounds', () => {
diff --git a/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts b/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
index 13af7f80be9..582fac1e131 100644
--- a/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
@@ -13,6 +13,13 @@ import { absolutePathToFileUri } from '@/components/editor/markdown-internal-lin
 import type { PaneManager } from '@/lib/pane-manager/pane-manager'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { openHttpLink } from '@/lib/http-link-routing'
+import {
+  isRemoteRuntimeFileOperation,
+  runtimePathExists,
+  statRuntimePath,
+  type RuntimeFileOperationArgs
+} from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 
 export type LinkHandlerDeps = {
   worktreeId: string
@@ -21,6 +28,8 @@ export type LinkHandlerDeps = {
   managerRef: React.RefObject<PaneManager | null>
   linkProviderDisposablesRef: React.RefObject<Map<number, IDisposable>>
   pathExistsCache: Map<string, boolean>
+  runtimeEnvironmentId?: string | null
+  getRuntimeEnvironmentIdForPane?: (paneId: number) => string | null
 }
 
 type TerminalLinkEvent = Pick<MouseEvent, 'metaKey' | 'ctrlKey'> &
@@ -64,28 +73,47 @@ function openHtmlFileInBrowser(filePath: string, worktreeId: string): void {
   store.createBrowserTab(worktreeId, fileUrl, { title, activate: true })
 }
 
+function getTerminalFileContext(
+  worktreeId: string,
+  worktreePath: string,
+  runtimeEnvironmentId?: string | null
+): RuntimeFileOperationArgs {
+  const settings = useAppStore.getState().settings
+  return {
+    settings: settingsForRuntimeOwner(settings, runtimeEnvironmentId),
+    worktreeId: worktreeId || null,
+    worktreePath,
+    connectionId: getConnectionId(worktreeId || null) ?? undefined
+  }
+}
+
 export function openDetectedFilePath(
   filePath: string,
   line: number | null,
   column: number | null,
-  deps: Pick<LinkHandlerDeps, 'worktreeId' | 'worktreePath'>
+  deps: Pick<LinkHandlerDeps, 'worktreeId' | 'worktreePath' | 'runtimeEnvironmentId'>
 ): void {
-  const { worktreeId, worktreePath } = deps
+  const { runtimeEnvironmentId, worktreeId, worktreePath } = deps
 
   void (async () => {
     let statResult
     try {
-      const connectionId = getConnectionId(deps.worktreeId ?? null) ?? undefined
-      // Why: remote paths don't need local auth — the relay is the security boundary.
-      if (!connectionId) {
+      const fileContext = getTerminalFileContext(worktreeId, worktreePath, runtimeEnvironmentId)
+      const isRemoteRuntimePath = isRemoteRuntimeFileOperation(fileContext, filePath)
+      // Why: remote paths don't need local auth — the relay/runtime is the security boundary.
+      if (!fileContext.connectionId && !isRemoteRuntimePath) {
         await window.api.fs.authorizeExternalPath({ targetPath: filePath })
       }
-      statResult = await window.api.fs.stat({ filePath, connectionId })
+      statResult = await statRuntimePath(fileContext, filePath)
     } catch {
       return
     }
 
     if (statResult.isDirectory) {
+      const fileContext = getTerminalFileContext(worktreeId, worktreePath, runtimeEnvironmentId)
+      if (fileContext.connectionId || isRemoteRuntimeFileOperation(fileContext, filePath)) {
+        return
+      }
       await window.api.shell.openFilePath(filePath)
       return
     }
@@ -94,7 +122,12 @@ export function openDetectedFilePath(
     // as source in Monaco — ⌘/Ctrl+click on an HTML path in the terminal should
     // feel like clicking an http link and render the page, not dump HTML source.
     // Mirrors the editor's "Open Preview to the Side" action.
-    if (isHtmlFilePath(filePath)) {
+    const fileContext = getTerminalFileContext(worktreeId, worktreePath, runtimeEnvironmentId)
+    if (
+      isHtmlFilePath(filePath) &&
+      !fileContext.connectionId &&
+      !isRemoteRuntimeFileOperation(fileContext, filePath)
+    ) {
       openHtmlFileInBrowser(filePath, worktreeId)
       return
     }
@@ -120,7 +153,8 @@ export function openDetectedFilePath(
       relativePath,
       worktreeId: worktreeId || '',
       language: detectLanguage(filePath),
-      mode: 'edit'
+      mode: 'edit',
+      runtimeEnvironmentId: runtimeEnvironmentId ?? undefined
     })
 
     if (line !== null) {
@@ -172,9 +206,18 @@ export function createFilePathLinkProvider(
             return null
           }
 
-          const cachedExists = pathExistsCache.get(resolved.absolutePath)
-          const exists = cachedExists ?? (await window.api.shell.pathExists(resolved.absolutePath))
-          pathExistsCache.set(resolved.absolutePath, exists)
+          const runtimeEnvironmentId =
+            deps.getRuntimeEnvironmentIdForPane?.(paneId) ?? deps.runtimeEnvironmentId ?? null
+          const cacheKey = `${runtimeEnvironmentId ?? 'active'}\0${resolved.absolutePath}`
+          const cachedExists = pathExistsCache.get(cacheKey)
+          const fileContext = getTerminalFileContext(worktreeId, worktreePath, runtimeEnvironmentId)
+          const exists =
+            cachedExists ??
+            (fileContext.connectionId ||
+            isRemoteRuntimeFileOperation(fileContext, resolved.absolutePath)
+              ? await runtimePathExists(fileContext, resolved.absolutePath)
+              : await window.api.shell.pathExists(resolved.absolutePath))
+          pathExistsCache.set(cacheKey, exists)
           if (!exists) {
             return null
           }
@@ -197,7 +240,8 @@ export function createFilePathLinkProvider(
               }
               openDetectedFilePath(resolved.absolutePath, resolved.line, resolved.column, {
                 worktreeId,
-                worktreePath
+                worktreePath,
+                runtimeEnvironmentId
               })
             },
             hover: () => {
@@ -235,7 +279,7 @@ export function handleOscLink(
   rawText: string,
   event: TerminalLinkEvent | undefined,
   deps: Pick<LinkHandlerDeps, 'worktreeId' | 'worktreePath'> &
-    Partial<Pick<LinkHandlerDeps, 'startupCwd'>>
+    Partial<Pick<LinkHandlerDeps, 'runtimeEnvironmentId' | 'startupCwd'>>
 ): void {
   if (!isTerminalLinkActivation(event)) {
     return
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
index 5823891ad7f..af06537c444 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
@@ -38,6 +38,7 @@ import type { EffectiveMacOptionAsAlt } from '@/lib/keyboard-layout/detect-optio
 import { resolveEffectiveTerminalAppearance } from '@/lib/terminal-theme'
 import { connectPanePty } from './pty-connection'
 import type { PtyTransport } from './pty-transport'
+import { getRemoteRuntimePtyEnvironmentId } from '@/runtime/runtime-terminal-stream'
 import { isPaneReplaying, type ReplayingPanesRef } from './replay-guard'
 import { fitAndFocusPanes, fitPanes } from './pane-helpers'
 import { registerRuntimeTerminalTab, scheduleRuntimeGraphSync } from '@/runtime/sync-runtime-graph'
@@ -296,7 +297,11 @@ export function useTerminalPaneLifecycle({
       startupCwd,
       managerRef,
       linkProviderDisposablesRef,
-      pathExistsCache
+      pathExistsCache,
+      getRuntimeEnvironmentIdForPane: (paneId) => {
+        const ptyId = paneTransportsRef.current.get(paneId)?.getPtyId()
+        return ptyId ? getRemoteRuntimePtyEnvironmentId(ptyId) : null
+      }
     }
     let resizeRaf: number | null = null
     const queueResizeAll = (focusActive: boolean): void => {
@@ -488,7 +493,10 @@ export function useTerminalPaneLifecycle({
         pane.terminal.options.linkHandler = {
           allowNonHttpProtocols: true,
           activate: (event, text) => {
-            handleOscLink(text, event as MouseEvent | undefined, linkDeps)
+            handleOscLink(text, event as MouseEvent | undefined, {
+              ...linkDeps,
+              runtimeEnvironmentId: linkDeps.getRuntimeEnvironmentIdForPane?.(pane.id) ?? null
+            })
             // Why: Cmd/Ctrl+clicking a link activates Orca handling (open file,
             // new browser tab, system browser) which can steal focus from the
             // terminal before the click's mouseup reaches ownerDocument. Without
@@ -685,7 +693,13 @@ export function useTerminalPaneLifecycle({
         if (!event) {
           return
         }
-        void handleOscLink(url, event, linkDeps)
+        const activePane = managerRef.current?.getActivePane()
+        void handleOscLink(url, event, {
+          ...linkDeps,
+          runtimeEnvironmentId: activePane
+            ? (linkDeps.getRuntimeEnvironmentIdForPane?.(activePane.id) ?? null)
+            : null
+        })
         // Why: Cmd/Ctrl+click on a plain-text URL (WebLinksAddon) takes focus
         // away from the terminal before the click's mouseup reaches
         // ownerDocument. That leaves xterm's SelectionService drag-select
diff --git a/src/renderer/src/hooks/useComposerState.ts b/src/renderer/src/hooks/useComposerState.ts
index 88c2e46b317..3acdc7f96b4 100644
--- a/src/renderer/src/hooks/useComposerState.ts
+++ b/src/renderer/src/hooks/useComposerState.ts
@@ -17,6 +17,7 @@ import { buildAgentDraftLaunchPlan, buildAgentStartupPlan } from '@/lib/tui-agen
 import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
 import { tuiAgentToAgentKind } from '@/lib/telemetry'
 import { isGitRepoKind } from '../../../shared/repo-kind'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import type {
   GitHubWorkItem,
   GitPushTarget,
@@ -49,6 +50,9 @@ import { getSuggestedCreatureName } from '@/components/sidebar/worktree-name-sug
 import type { SmartWorkspaceNameSelection } from '@/components/new-workspace/SmartWorkspaceNameField'
 import { ensureHooksConfirmed } from '@/lib/ensure-hooks-confirmed'
 import { normalizeSparseDirectoryLines, sparseDirectoriesMatch } from '@/lib/sparse-paths'
+import { joinPath } from '@/lib/path'
+import { importExternalPathsToRuntime } from '@/runtime/runtime-file-client'
+import { checkRuntimeHooks, readRuntimeIssueCommand } from '@/runtime/runtime-hooks-client'
 
 export type UseComposerStateOptions = {
   initialRepoId?: string
@@ -392,6 +396,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   // multi-instance routing).
   const agentPromptRef = useRef(agentPrompt)
   agentPromptRef.current = agentPrompt
+  const connectionIdRef = useRef(connectionId)
+  connectionIdRef.current = connectionId
 
   const selectedRepo = eligibleRepos.find((repo) => repo.id === repoId)
 
@@ -404,18 +410,30 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     null
   )
   const selectedRepoPath = selectedRepo?.path
+  const selectedRepoPathRef = useRef<string | undefined>(selectedRepoPath)
+  selectedRepoPathRef.current = selectedRepoPath
+  const settingsRef = useRef(settings)
+  settingsRef.current = settings
   useEffect(() => {
-    if (!selectedRepoPath) {
+    if (!selectedRepo || !selectedRepoPath) {
       setSelectedRepoSlug(null)
       return
     }
     let cancelled = false
-    void (
-      window.api.gh.repoSlug({ repoPath: selectedRepoPath }) as Promise<{
-        owner: string
-        repo: string
-      } | null>
-    )
+    const target = getActiveRuntimeTarget(settings)
+    const request =
+      target.kind === 'environment'
+        ? callRuntimeRpc<{ owner: string; repo: string } | null>(
+            target,
+            'github.repoSlug',
+            { repo: selectedRepo.id },
+            { timeoutMs: 30_000 }
+          )
+        : (window.api.gh.repoSlug({ repoPath: selectedRepoPath }) as Promise<{
+            owner: string
+            repo: string
+          } | null>)
+    void request
       .then((result) => {
         if (cancelled) {
           return
@@ -430,7 +448,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [selectedRepoPath])
+  }, [selectedRepo, selectedRepoPath, settings])
   const sparsePresetsForRepo = sparsePresetsByRepo[repoId]
   const sparsePresets = sparsePresetsForRepo ?? EMPTY_SPARSE_PRESETS
   const normalizedSparseDirectories = useMemo(
@@ -702,8 +720,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     setYamlHooks(null)
     setCheckedHooksRepoId(null)
 
-    void window.api.hooks
-      .check({ repoId })
+    void checkRuntimeHooks(settings, repoId)
       .then((result) => {
         if (!cancelled) {
           setYamlHooks(result.hooks)
@@ -717,8 +734,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         }
       })
 
-    void window.api.hooks
-      .readIssueCommand({ repoId })
+    void readRuntimeIssueCommand(settings, repoId)
       .then((result) => {
         if (!cancelled) {
           setIssueCommandTemplate(result.effectiveContent ?? '')
@@ -735,7 +751,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [repoId])
+  }, [repoId, settings])
 
   // Why: warm the Start-from picker's PR cache on composer mount and whenever
   // the selected repo changes so opening the picker paints instantly from
@@ -779,8 +795,17 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     setLinkItemsLoading(true)
 
     const lookupRepoId = selectedRepo.id
-    void window.api.gh
-      .listWorkItems({ repoPath: selectedRepo.path, limit: 100 })
+    const target = getActiveRuntimeTarget(settings)
+    const request =
+      target.kind === 'environment'
+        ? callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.listWorkItems>>>(
+            target,
+            'github.listWorkItems',
+            { repo: selectedRepo.id, limit: 100 },
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh.listWorkItems({ repoPath: selectedRepo.path, limit: 100 })
+    void request
       .then((envelope) => {
         if (!cancelled) {
           // Why: IPC payload omits repoId — stamp it here from the repo we
@@ -827,7 +852,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [linkPopoverOpen, selectedRepo])
+  }, [linkPopoverOpen, selectedRepo, settings])
 
   useEffect(() => {
     if (!linkPopoverOpen || !selectedRepo || normalizedLinkQuery.directNumber === null) {
@@ -843,8 +868,20 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     // resolving direct lookups against the selected repo instead of requiring a
     // text match in the recent-items list.
     const lookupRepoId = selectedRepo.id
-    void window.api.gh
-      .workItem({ repoPath: selectedRepo.path, number: normalizedLinkQuery.directNumber })
+    const target = getActiveRuntimeTarget(settings)
+    const request =
+      target.kind === 'environment'
+        ? callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.workItem>>>(
+            target,
+            'github.workItem',
+            { repo: selectedRepo.id, number: normalizedLinkQuery.directNumber },
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh.workItem({
+            repoPath: selectedRepo.path,
+            number: normalizedLinkQuery.directNumber
+          })
+    void request
       .then((item) => {
         if (!cancelled) {
           setLinkDirectItem(
@@ -866,7 +903,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [linkPopoverOpen, normalizedLinkQuery.directNumber, selectedRepo])
+  }, [linkPopoverOpen, normalizedLinkQuery.directNumber, selectedRepo, settings])
 
   const applyLinkedWorkItem = useCallback(
     (item: GitHubWorkItem): void => {
@@ -975,23 +1012,165 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     },
     [name]
   )
+
+  const addComposerAttachments = useCallback((paths: string[]): void => {
+    if (paths.length === 0) {
+      return
+    }
+    setAttachmentPaths((current) => {
+      const next = [...current]
+      for (const pathValue of paths) {
+        if (!next.includes(pathValue)) {
+          next.push(pathValue)
+        }
+      }
+      return next
+    })
+  }, [])
+
+  const insertComposerFolderPaths = useCallback((folderPaths: string[]): void => {
+    if (folderPaths.length === 0) {
+      return
+    }
+    // Why: de-dup within a single drop — the OS occasionally delivers the
+    // same folder twice when a user drags from a selection that includes both
+    // the item and its parent, and we don't want to insert it multiple times.
+    const uniqueFolderPaths = Array.from(new Set(folderPaths))
+    // Why: wrap paths containing shell metacharacters in double quotes (and
+    // escape embedded quotes) so inserted folder refs stay a single token if
+    // pasted into a terminal. Simple paths stay unadorned to match OS drops.
+    const formatPath = (p: string): string => {
+      if (/[\s"'$`\\()[\]{}*?!;&|<>#~]/.test(p)) {
+        return `"${p.replace(/(["\\$`])/g, '\\$1')}"`
+      }
+      return p
+    }
+    const insertion = uniqueFolderPaths.map(formatPath).join(' ')
+    const textarea = promptTextareaRef.current
+    // Why: compute selection, insertion, and caret target OUTSIDE the
+    // setAgentPrompt updater so the updater stays pure. React Strict Mode
+    // double-invokes updaters in dev, and batching can delay execution.
+    const current = agentPromptRef.current
+    const selStart = textarea?.selectionStart ?? current.length
+    const selEnd = textarea?.selectionEnd ?? current.length
+    const before = current.slice(0, selStart)
+    const after = current.slice(selEnd)
+    // Why: pad with single spaces when the caret sits directly against other
+    // text so the folder path doesn't merge into an adjacent word.
+    const needsLeadingSpace = before.length > 0 && !/\s$/.test(before)
+    const needsTrailingSpace = after.length > 0 && !/^\s/.test(after)
+    const padded = `${needsLeadingSpace ? ' ' : ''}${insertion}${needsTrailingSpace ? ' ' : ''}`
+    const caret = before.length + padded.length
+    if (textarea) {
+      requestAnimationFrame(() => {
+        textarea.focus()
+        textarea.setSelectionRange(caret, caret)
+      })
+    }
+    // Why: pass a plain value (not an updater) since `before`/`after` were
+    // already resolved from `agentPromptRef.current`; this keeps the state
+    // write side-effect-free under Strict-Mode double-render.
+    setAgentPrompt(before + padded + after)
+  }, [])
+
+  const uploadComposerPaths = useCallback(
+    async (
+      sourcePaths: string[],
+      targetSettings = settings,
+      targetConnectionId = connectionId,
+      targetRepoPath = selectedRepoPath
+    ): Promise<{ filePaths: string[]; folderPaths: string[] } | null> => {
+      if (!targetSettings?.activeRuntimeEnvironmentId?.trim() && !targetConnectionId) {
+        return null
+      }
+      if (!targetRepoPath) {
+        toast.error('No remote repository path is available for attachments.')
+        return { filePaths: [], folderPaths: [] }
+      }
+      const destinationDir = joinPath(targetRepoPath, '.orca/drops')
+      const { results } = await importExternalPathsToRuntime(
+        {
+          settings: targetSettings,
+          worktreeId: targetRepoPath,
+          worktreePath: targetRepoPath,
+          connectionId: targetConnectionId ?? undefined
+        },
+        sourcePaths,
+        destinationDir,
+        { ensureDestinationDir: true }
+      )
+      const filePaths: string[] = []
+      const folderPaths: string[] = []
+      let skippedOrFailed = 0
+      for (const result of results) {
+        if (result.status !== 'imported') {
+          skippedOrFailed += 1
+          continue
+        }
+        if (result.kind === 'directory') {
+          folderPaths.push(result.destPath)
+        } else {
+          filePaths.push(result.destPath)
+        }
+      }
+      if (skippedOrFailed > 0) {
+        toast.error('Some attachments could not be uploaded.')
+      }
+      return { filePaths, folderPaths }
+    },
+    [connectionId, selectedRepoPath, settings]
+  )
+
   const handleAddAttachment = useCallback(async (): Promise<void> => {
     try {
       const selectedPath = await window.api.shell.pickAttachment()
       if (!selectedPath) {
         return
       }
-      setAttachmentPaths((current) => {
-        if (current.includes(selectedPath)) {
-          return current
-        }
-        return [...current, selectedPath]
-      })
+      const uploaded = await uploadComposerPaths([selectedPath])
+      if (uploaded) {
+        addComposerAttachments(uploaded.filePaths)
+        insertComposerFolderPaths(uploaded.folderPaths)
+        return
+      }
+      addComposerAttachments([selectedPath])
     } catch (error) {
       const message = error instanceof Error ? error.message : 'Failed to add attachment.'
       toast.error(message)
     }
-  }, [])
+  }, [addComposerAttachments, insertComposerFolderPaths, uploadComposerPaths])
+
+  const applyLocalComposerDrop = useCallback(
+    async (paths: string[]): Promise<void> => {
+      const fileAttachments: string[] = []
+      const folderPaths: string[] = []
+      for (const filePath of paths) {
+        try {
+          await window.api.fs.authorizeExternalPath({ targetPath: filePath })
+          const stat = await window.api.fs.stat({ filePath })
+          if (stat.isDirectory) {
+            folderPaths.push(filePath)
+          } else {
+            fileAttachments.push(filePath)
+          }
+        } catch {
+          // Skip paths we cannot authorize or stat.
+        }
+      }
+
+      addComposerAttachments(fileAttachments)
+      insertComposerFolderPaths(folderPaths)
+    },
+    [addComposerAttachments, insertComposerFolderPaths]
+  )
+  const addComposerAttachmentsRef = useRef(addComposerAttachments)
+  addComposerAttachmentsRef.current = addComposerAttachments
+  const insertComposerFolderPathsRef = useRef(insertComposerFolderPaths)
+  insertComposerFolderPathsRef.current = insertComposerFolderPaths
+  const uploadComposerPathsRef = useRef(uploadComposerPaths)
+  uploadComposerPathsRef.current = uploadComposerPaths
+  const applyLocalComposerDropRef = useRef(applyLocalComposerDrop)
+  applyLocalComposerDropRef.current = applyLocalComposerDrop
 
   // Why: native OS file drops onto the composer are captured by the preload
   // bridge (see `data-native-file-drop-target="composer"` markers) and relayed
@@ -1015,82 +1194,18 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         return
       }
       void (async () => {
-        const fileAttachments: string[] = []
-        const folderPaths: string[] = []
-        for (const filePath of data.paths) {
-          try {
-            await window.api.fs.authorizeExternalPath({ targetPath: filePath })
-            const stat = await window.api.fs.stat({ filePath })
-            if (stat.isDirectory) {
-              folderPaths.push(filePath)
-            } else {
-              fileAttachments.push(filePath)
-            }
-          } catch {
-            // Skip paths we cannot authorize or stat.
-          }
-        }
-
-        if (fileAttachments.length > 0) {
-          setAttachmentPaths((current) => {
-            const next = [...current]
-            for (const p of fileAttachments) {
-              if (!next.includes(p)) {
-                next.push(p)
-              }
-            }
-            return next
-          })
-        }
-
-        if (folderPaths.length > 0) {
-          // Why: de-dup within a single drop — the OS occasionally delivers
-          // the same folder twice when a user drags from a selection that
-          // includes both the item and its parent, and we don't want to
-          // insert it multiple times.
-          const uniqueFolderPaths = Array.from(new Set(folderPaths))
-          // Why: wrap paths containing shell metacharacters in double quotes
-          // (and escape embedded quotes) so the inserted text reads as a
-          // single token if the user pastes it into a terminal. Simple paths
-          // stay unadorned to match how Finder/Explorer drops appear.
-          const formatPath = (p: string): string => {
-            if (/[\s"'$`\\()[\]{}*?!;&|<>#~]/.test(p)) {
-              return `"${p.replace(/(["\\$`])/g, '\\$1')}"`
-            }
-            return p
-          }
-          const insertion = uniqueFolderPaths.map(formatPath).join(' ')
-          const textarea = promptTextareaRef.current
-          // Why: compute selection, insertion, and caret target OUTSIDE the
-          // setAgentPrompt updater so the updater stays pure. React Strict
-          // Mode double-invokes updaters in dev, and batching can delay
-          // execution — reading `textarea.selectionStart` inside the updater
-          // risks seeing a shifted caret. Read `agentPromptRef.current` for
-          // the latest prompt because this effect subscribes once and the
-          // outer closure's `agentPrompt` would be stale.
-          const current = agentPromptRef.current
-          const selStart = textarea?.selectionStart ?? current.length
-          const selEnd = textarea?.selectionEnd ?? current.length
-          const before = current.slice(0, selStart)
-          const after = current.slice(selEnd)
-          // Why: pad with single spaces when the caret sits directly against
-          // other text so the folder path doesn't merge into an adjacent word.
-          const needsLeadingSpace = before.length > 0 && !/\s$/.test(before)
-          const needsTrailingSpace = after.length > 0 && !/^\s/.test(after)
-          const padded = `${needsLeadingSpace ? ' ' : ''}${insertion}${needsTrailingSpace ? ' ' : ''}`
-          const caret = before.length + padded.length
-          if (textarea) {
-            // Restore the caret to the end of the inserted text after React flushes.
-            requestAnimationFrame(() => {
-              textarea.focus()
-              textarea.setSelectionRange(caret, caret)
-            })
-          }
-          // Why: pass a plain value (not an updater) since `before`/`after`
-          // were already resolved from `agentPromptRef.current`; this keeps
-          // the state write side-effect-free under Strict-Mode double-render.
-          setAgentPrompt(before + padded + after)
+        const uploaded = await uploadComposerPathsRef.current(
+          data.paths,
+          settingsRef.current,
+          connectionIdRef.current,
+          selectedRepoPathRef.current
+        )
+        if (uploaded) {
+          addComposerAttachmentsRef.current(uploaded.filePaths)
+          insertComposerFolderPathsRef.current(uploaded.folderPaths)
+          return
         }
+        await applyLocalComposerDropRef.current(data.paths)
       })()
     })
     return () => {
@@ -1231,15 +1346,31 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         return
       }
       setPushTarget(undefined)
-      void window.api.worktrees
-        .resolvePrBase({
-          repoId: repoForItem.id,
-          prNumber: item.number,
-          ...(item.branchName ? { headRefName: item.branchName } : {}),
-          ...(item.isCrossRepository !== undefined
-            ? { isCrossRepository: item.isCrossRepository }
-            : {})
-        })
+      const target = getActiveRuntimeTarget(settings)
+      const resolvePrBase =
+        target.kind === 'local'
+          ? window.api.worktrees.resolvePrBase({
+              repoId: repoForItem.id,
+              prNumber: item.number,
+              ...(item.branchName ? { headRefName: item.branchName } : {}),
+              ...(item.isCrossRepository !== undefined
+                ? { isCrossRepository: item.isCrossRepository }
+                : {})
+            })
+          : callRuntimeRpc<{ baseBranch: string; pushTarget?: GitPushTarget } | { error: string }>(
+              target,
+              'worktree.resolvePrBase',
+              {
+                repo: repoForItem.id,
+                prNumber: item.number,
+                ...(item.branchName ? { headRefName: item.branchName } : {}),
+                ...(item.isCrossRepository !== undefined
+                  ? { isCrossRepository: item.isCrossRepository }
+                  : {})
+              },
+              { timeoutMs: 30_000 }
+            )
+      void resolvePrBase
         .then((result) => {
           if ('error' in result) {
             setBaseBranch(undefined)
@@ -1255,7 +1386,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
           toast.error(error instanceof Error ? error.message : 'Failed to resolve PR base.')
         })
     },
-    [applyLinkedWorkItem, eligibleRepos, handleBaseBranchPrSelect, selectedRepo]
+    [applyLinkedWorkItem, eligibleRepos, handleBaseBranchPrSelect, selectedRepo, settings]
   )
 
   // Why: GitLab parallel of handleSmartGitHubItemSelect. For a picked
diff --git a/src/renderer/src/hooks/useEditorExternalWatch.test.ts b/src/renderer/src/hooks/useEditorExternalWatch.test.ts
index f6f809ff472..1b0b823f6c7 100644
--- a/src/renderer/src/hooks/useEditorExternalWatch.test.ts
+++ b/src/renderer/src/hooks/useEditorExternalWatch.test.ts
@@ -20,6 +20,10 @@ import {
   getWatchedTargetKey
 } from './useEditorExternalWatch'
 import { useAppStore } from '@/store'
+import {
+  getOpenFilesForExternalFileChange,
+  notifyEditorExternalFileChange
+} from '@/components/editor/editor-autosave'
 
 describe('getWatchedTargetKey', () => {
   it('changes when a worktree gains an SSH connection id', () => {
@@ -27,13 +31,33 @@ describe('getWatchedTargetKey', () => {
       getWatchedTargetKey({
         worktreeId: 'wt-1',
         worktreePath: '/repo',
-        connectionId: undefined
+        connectionId: undefined,
+        runtimeEnvironmentId: undefined
       })
     ).not.toBe(
       getWatchedTargetKey({
         worktreeId: 'wt-1',
         worktreePath: '/repo',
-        connectionId: 'conn-1'
+        connectionId: 'conn-1',
+        runtimeEnvironmentId: undefined
+      })
+    )
+  })
+
+  it('changes when the active runtime environment changes', () => {
+    expect(
+      getWatchedTargetKey({
+        worktreeId: 'wt-1',
+        worktreePath: '/repo',
+        connectionId: undefined,
+        runtimeEnvironmentId: undefined
+      })
+    ).not.toBe(
+      getWatchedTargetKey({
+        worktreeId: 'wt-1',
+        worktreePath: '/repo',
+        connectionId: undefined,
+        runtimeEnvironmentId: 'env-1'
       })
     )
   })
@@ -104,10 +128,16 @@ describe('createExternalWatchEventHandler tombstone coalescing', () => {
         worktreeId: string
         worktreePath: string
         connectionId: string | undefined
+        runtimeEnvironmentId: string | undefined
       }
     | undefined =>
     worktreePath === '/repo'
-      ? { worktreeId: 'wt-1', worktreePath: '/repo', connectionId: undefined }
+      ? {
+          worktreeId: 'wt-1',
+          worktreePath: '/repo',
+          connectionId: undefined,
+          runtimeEnvironmentId: undefined
+        }
       : undefined
 
   const fileNotes = {
@@ -182,4 +212,76 @@ describe('createExternalWatchEventHandler tombstone coalescing', () => {
 
     dispose()
   })
+
+  it('reloads Windows editor tabs when watcher event casing differs', () => {
+    const file = {
+      id: 'file-win',
+      worktreeId: 'wt-win',
+      worktreePath: 'C:\\Repo',
+      filePath: 'C:\\Repo\\notes.md',
+      relativePath: 'notes.md',
+      mode: 'edit' as const,
+      isDirty: false
+    }
+    vi.mocked(useAppStore.getState).mockReturnValue({
+      openFiles: [file],
+      setExternalMutation
+    } as never)
+    vi.mocked(getOpenFilesForExternalFileChange).mockReturnValue([file] as never)
+    const { handleFsChanged, dispose } = createExternalWatchEventHandler(() => ({
+      worktreeId: 'wt-win',
+      worktreePath: 'C:\\Repo',
+      connectionId: undefined,
+      runtimeEnvironmentId: 'env-1'
+    }))
+
+    handleFsChanged({
+      worktreePath: 'c:\\repo',
+      events: [{ kind: 'update', absolutePath: 'c:\\repo\\notes.md', isDirectory: false }]
+    })
+    vi.advanceTimersByTime(100)
+
+    expect(notifyEditorExternalFileChange).toHaveBeenCalledWith({
+      worktreeId: 'wt-win',
+      worktreePath: 'C:\\Repo',
+      relativePath: 'notes.md'
+    })
+    dispose()
+  })
+
+  it('reloads UNC editor tabs without collapsing the share root', () => {
+    const file = {
+      id: 'file-unc',
+      worktreeId: 'wt-unc',
+      worktreePath: '//Server/Share/Repo',
+      filePath: '//Server/Share/Repo/notes.md',
+      relativePath: 'notes.md',
+      mode: 'edit' as const,
+      isDirty: false
+    }
+    vi.mocked(useAppStore.getState).mockReturnValue({
+      openFiles: [file],
+      setExternalMutation
+    } as never)
+    vi.mocked(getOpenFilesForExternalFileChange).mockReturnValue([file] as never)
+    const { handleFsChanged, dispose } = createExternalWatchEventHandler(() => ({
+      worktreeId: 'wt-unc',
+      worktreePath: '//Server/Share/Repo',
+      connectionId: undefined,
+      runtimeEnvironmentId: 'env-1'
+    }))
+
+    handleFsChanged({
+      worktreePath: '//server/share/repo',
+      events: [{ kind: 'update', absolutePath: '//server/share/repo/notes.md', isDirectory: false }]
+    })
+    vi.advanceTimersByTime(100)
+
+    expect(notifyEditorExternalFileChange).toHaveBeenCalledWith({
+      worktreeId: 'wt-unc',
+      worktreePath: '//Server/Share/Repo',
+      relativePath: 'notes.md'
+    })
+    dispose()
+  })
 })
diff --git a/src/renderer/src/hooks/useEditorExternalWatch.ts b/src/renderer/src/hooks/useEditorExternalWatch.ts
index 26e97953c1f..d6d1081837b 100644
--- a/src/renderer/src/hooks/useEditorExternalWatch.ts
+++ b/src/renderer/src/hooks/useEditorExternalWatch.ts
@@ -5,8 +5,8 @@
 import { useEffect, useMemo, useRef } from 'react'
 import { useAppStore } from '@/store'
 import { basename, joinPath } from '@/lib/path'
-import { normalizeAbsolutePath } from '@/components/right-sidebar/file-explorer-paths'
 import { getExternalFileChangeRelativePath } from '@/components/right-sidebar/useFileExplorerWatch'
+import { normalizeRuntimePathForComparison } from '../../../shared/cross-platform-path'
 import {
   getOpenFilesForExternalFileChange,
   notifyEditorExternalFileChange
@@ -15,6 +15,7 @@ import { hasRecentSelfWrite } from '@/components/editor/editor-self-write-regist
 import type { FsChangedPayload } from '../../../shared/types'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
 import type { OpenFile } from '@/store/slices/editor'
+import { subscribeRuntimeFileChanges } from '@/runtime/runtime-file-client'
 
 // Why: atomic-write patterns (Claude Code's Edit tool, editors like vim,
 // VSCode) land as a short burst of `update` events — or `delete + create` on
@@ -25,7 +26,7 @@ import type { OpenFile } from '@/store/slices/editor'
 // and black out the window (issue #826). Coalescing per (worktreeId + path)
 // on a short debounce collapses that burst into one reload notification.
 const EXTERNAL_RELOAD_DEBOUNCE_MS = 75
-const pendingExternalReloadTimers = new Map<string, number>()
+const pendingExternalReloadTimers = new Map<string, ReturnType<typeof setTimeout>>()
 
 function warnExternalWatchFailure(target: WatchedTarget, err: unknown): void {
   console.warn('[filesystem-watch] failed to watch worktree', {
@@ -44,9 +45,9 @@ function scheduleDebouncedExternalReload(notification: {
   const key = `${notification.worktreeId}::${notification.relativePath}`
   const existing = pendingExternalReloadTimers.get(key)
   if (existing !== undefined) {
-    window.clearTimeout(existing)
+    globalThis.clearTimeout(existing)
   }
-  const handle = window.setTimeout(() => {
+  const handle = globalThis.setTimeout(() => {
     pendingExternalReloadTimers.delete(key)
     notifyEditorExternalFileChange(notification)
   }, EXTERNAL_RELOAD_DEBOUNCE_MS)
@@ -57,6 +58,7 @@ type WatchedTarget = {
   worktreeId: string
   worktreePath: string
   connectionId: string | undefined
+  runtimeEnvironmentId: string | undefined
 }
 
 type ExternalWatchNotification = {
@@ -69,7 +71,7 @@ export function getWatchedTargetKey(target: WatchedTarget): string {
   // Why: SSH worktrees can exist in the store before their remote filesystem
   // provider is ready. Include connectionId so a local/unknown placeholder
   // watch is replaced by the real SSH watch when the repo metadata hydrates.
-  return `${target.worktreeId}::${target.worktreePath}::${target.connectionId ?? 'local'}`
+  return `${target.worktreeId}::${target.worktreePath}::${target.connectionId ?? 'local'}::${target.runtimeEnvironmentId ?? 'client'}`
 }
 
 // Why: macOS atomic writes (Claude Code Edit, vim :w, VSCode save) deliver a
@@ -106,6 +108,7 @@ export function useEditorExternalWatch(): void {
   const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
   const repos = useAppStore((s) => s.repos)
   const activeWorktreeId = useAppStore((s) => s.activeWorktreeId)
+  const runtimeEnvironmentId = useAppStore((s) => s.settings?.activeRuntimeEnvironmentId)
 
   // Why: unify the target computation and the dependency key into one memo so
   // there's a single source of truth. The derived string key drives the
@@ -134,17 +137,20 @@ export function useEditorExternalWatch(): void {
       const target = {
         worktreeId: id,
         worktreePath: wt.path,
-        connectionId: repo?.connectionId ?? undefined
+        connectionId: repo?.connectionId ?? undefined,
+        runtimeEnvironmentId: runtimeEnvironmentId?.trim() || undefined
       }
       nextTargets.push(target)
       parts.push(getWatchedTargetKey(target))
     }
     return { targets: nextTargets, targetsKey: parts.join('|') }
-  }, [openFiles, worktreesByRepo, repos, activeWorktreeId])
+  }, [openFiles, worktreesByRepo, repos, activeWorktreeId, runtimeEnvironmentId])
 
   const targetsRef = useRef<WatchedTarget[]>([])
   const latestTargetsRef = useRef<WatchedTarget[]>(targets)
   latestTargetsRef.current = targets
+  const remoteWatchUnsubsRef = useRef(new Map<string, () => void>())
+  const fsChangedHandlerRef = useRef<((payload: FsChangedPayload) => void) | null>(null)
 
   // Why: diff previous vs next targets so unchanged worktrees keep their
   // existing subscription. Tearing down every subscription on each targetsKey
@@ -159,12 +165,55 @@ export function useEditorExternalWatch(): void {
     const added = nextTargets.filter((t) => !prevKeys.has(getWatchedTargetKey(t)))
 
     for (const target of removed) {
-      void window.api.fs.unwatchWorktree({
-        worktreePath: target.worktreePath,
-        connectionId: target.connectionId
-      })
+      const key = getWatchedTargetKey(target)
+      const remoteUnsubscribe = remoteWatchUnsubsRef.current.get(key)
+      if (remoteUnsubscribe) {
+        remoteUnsubscribe()
+        remoteWatchUnsubsRef.current.delete(key)
+      } else {
+        void window.api.fs.unwatchWorktree({
+          worktreePath: target.worktreePath,
+          connectionId: target.connectionId
+        })
+      }
     }
     for (const target of added) {
+      if (target.runtimeEnvironmentId) {
+        const key = getWatchedTargetKey(target)
+        let cancelled = false
+        const pendingUnsubscribe = (): void => {
+          cancelled = true
+        }
+        remoteWatchUnsubsRef.current.set(key, pendingUnsubscribe)
+        void subscribeRuntimeFileChanges(
+          {
+            settings: { activeRuntimeEnvironmentId: target.runtimeEnvironmentId },
+            worktreeId: target.worktreeId,
+            worktreePath: target.worktreePath,
+            connectionId: target.connectionId
+          },
+          (payload) => fsChangedHandlerRef.current?.(payload),
+          (err) => warnExternalWatchFailure(target, err)
+        )
+          .then((unsubscribe) => {
+            if (cancelled) {
+              unsubscribe()
+              return
+            }
+            if (remoteWatchUnsubsRef.current.get(key) === pendingUnsubscribe) {
+              remoteWatchUnsubsRef.current.set(key, unsubscribe)
+            } else {
+              unsubscribe()
+            }
+          })
+          .catch((err) => {
+            if (remoteWatchUnsubsRef.current.get(key) === pendingUnsubscribe) {
+              remoteWatchUnsubsRef.current.delete(key)
+            }
+            warnExternalWatchFailure(target, err)
+          })
+        continue
+      }
       void window.api.fs
         .watchWorktree({
           worktreePath: target.worktreePath,
@@ -188,25 +237,37 @@ export function useEditorExternalWatch(): void {
   // single always-mounted effect avoids re-subscribing on every targetsKey
   // change (which would otherwise miss events fired during re-subscription).
   useEffect(() => {
+    const remoteWatchUnsubs = remoteWatchUnsubsRef.current
     const { handleFsChanged, dispose } = createExternalWatchEventHandler((worktreePath) =>
       targetsRef.current.find(
-        (t) => normalizeAbsolutePath(t.worktreePath) === normalizeAbsolutePath(worktreePath)
+        (t) =>
+          normalizeRuntimePathForComparison(t.worktreePath) ===
+          normalizeRuntimePathForComparison(worktreePath)
       )
     )
     const unsubscribe = window.api.fs.onFsChanged(handleFsChanged)
+    fsChangedHandlerRef.current = handleFsChanged
 
     return () => {
       unsubscribe()
       dispose()
+      fsChangedHandlerRef.current = null
       // Why: final unmount must tear down every outstanding subscription.
       // The differential watch effect above intentionally never unwatches on
       // cleanup, so this is the only place that clears them.
       for (const target of targetsRef.current) {
-        void window.api.fs.unwatchWorktree({
-          worktreePath: target.worktreePath,
-          connectionId: target.connectionId
-        })
+        const key = getWatchedTargetKey(target)
+        const remoteUnsubscribe = remoteWatchUnsubs.get(key)
+        if (remoteUnsubscribe) {
+          remoteUnsubscribe()
+        } else {
+          void window.api.fs.unwatchWorktree({
+            worktreePath: target.worktreePath,
+            connectionId: target.connectionId
+          })
+        }
       }
+      remoteWatchUnsubs.clear()
       targetsRef.current = []
       // Why: deliberately do NOT clear pendingExternalReloadTimers here.
       // The map is module-scoped, so in React StrictMode (dev) the first
@@ -253,7 +314,7 @@ export function createExternalWatchEventHandler(
         continue
       }
       if (evt.kind === 'create' || evt.kind === 'update') {
-        createOrUpdatePaths.add(normalizeAbsolutePath(evt.absolutePath))
+        createOrUpdatePaths.add(normalizeRuntimePathForComparison(evt.absolutePath))
       }
     }
     for (const createdPath of createOrUpdatePaths) {
@@ -346,7 +407,7 @@ export function createExternalWatchEventHandler(
           file.worktreeId === target.worktreeId &&
           (file.mode === 'edit' || file.mode === 'markdown-preview') &&
           file.externalMutation &&
-          createOrUpdatePaths.has(normalizeAbsolutePath(file.filePath))
+          createOrUpdatePaths.has(normalizeRuntimePathForComparison(file.filePath))
         ) {
           state.setExternalMutation(file.id, null)
         }
@@ -384,7 +445,7 @@ export function createExternalWatchEventHandler(
 
       const relativePath = getExternalFileChangeRelativePath(
         target.worktreePath,
-        normalizeAbsolutePath(evt.absolutePath),
+        evt.absolutePath,
         evt.isDirectory
       )
       if (relativePath) {
@@ -481,7 +542,7 @@ function buildDeletePathByFileId(
   const deletePaths = new Set<string>()
   for (const evt of payload.events) {
     if (evt.kind === 'delete') {
-      deletePaths.add(normalizeAbsolutePath(evt.absolutePath))
+      deletePaths.add(normalizeRuntimePathForComparison(evt.absolutePath))
     }
   }
   const result = new Map<string, string>()
@@ -493,7 +554,7 @@ function buildDeletePathByFileId(
     if (!deletedIdSet.has(file.id) || file.worktreeId !== worktreeId) {
       continue
     }
-    const normalized = normalizeAbsolutePath(file.filePath)
+    const normalized = normalizeRuntimePathForComparison(file.filePath)
     if (deletePaths.has(normalized)) {
       result.set(file.id, normalized)
     }
@@ -509,7 +570,7 @@ function collectDeletedOpenEditorIds(
   const deletePaths = new Set<string>()
   for (const evt of payload.events) {
     if (evt.kind === 'delete') {
-      deletePaths.add(normalizeAbsolutePath(evt.absolutePath))
+      deletePaths.add(normalizeRuntimePathForComparison(evt.absolutePath))
     }
   }
   if (deletePaths.size === 0) {
@@ -523,7 +584,7 @@ function collectDeletedOpenEditorIds(
     ) {
       continue
     }
-    if (deletePaths.has(normalizeAbsolutePath(file.filePath))) {
+    if (deletePaths.has(normalizeRuntimePathForComparison(file.filePath))) {
       result.push(file.id)
     }
   }
@@ -564,7 +625,7 @@ function hasRenameCorrelatedCreate(
     if (!deletedIdSet.has(file.id)) {
       continue
     }
-    deletedBasenames.add(basename(normalizeAbsolutePath(file.filePath)))
+    deletedBasenames.add(basename(file.filePath))
   }
   if (deletedBasenames.size === 0) {
     return false
@@ -573,7 +634,7 @@ function hasRenameCorrelatedCreate(
     if (evt.kind !== 'create' || evt.isDirectory === true) {
       continue
     }
-    if (deletedBasenames.has(basename(normalizeAbsolutePath(evt.absolutePath)))) {
+    if (deletedBasenames.has(basename(evt.absolutePath))) {
       return true
     }
   }
diff --git a/src/renderer/src/hooks/useGitHubSlugMetadata.ts b/src/renderer/src/hooks/useGitHubSlugMetadata.ts
index 06861899518..49decd64ec5 100644
--- a/src/renderer/src/hooks/useGitHubSlugMetadata.ts
+++ b/src/renderer/src/hooks/useGitHubSlugMetadata.ts
@@ -5,7 +5,12 @@
 // existing repoPath-keyed hooks stay focused on the local-workspace flow
 // and so this file remains under the lint line cap.
 import { useEffect, useRef, useState } from 'react'
-import type { GitHubAssignableUser } from '../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import type { GitHubAssignableUser, GlobalSettings } from '../../../shared/types'
+import type {
+  ListAssignableUsersBySlugResult,
+  ListLabelsBySlugResult
+} from '../../../shared/github-project-types'
 import {
   clearMetadataRequestStore,
   createMetadataRequestStore,
@@ -29,7 +34,8 @@ export function clearGitHubSlugMetadataCache(): void {
 
 export function useRepoLabelsBySlug(
   owner: string | null,
-  repo: string | null
+  repo: string | null,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
 ): MetadataState<string[]> {
   const [state, setState] = useState<MetadataState<string[]>>({
     data: [],
@@ -42,7 +48,11 @@ export function useRepoLabelsBySlug(
     if (!owner || !repo) {
       return
     }
-    const key = `${owner}/${repo}`
+    const target = getActiveRuntimeTarget(settings)
+    const key =
+      target.kind === 'environment'
+        ? `runtime:${target.environmentId}:${owner}/${repo}`
+        : `${owner}/${repo}`
 
     const cached = getFreshMetadata(slugLabelStore, key)
     if (cached) {
@@ -64,7 +74,15 @@ export function useRepoLabelsBySlug(
       error: null
     }))
     loadMetadata(slugLabelStore, key, () =>
-      window.api.gh.listLabelsBySlug({ owner, repo }).then((res) => {
+      (target.kind === 'environment'
+        ? callRuntimeRpc<ListLabelsBySlugResult>(
+            target,
+            'github.project.listLabelsBySlug',
+            { owner, repo },
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh.listLabelsBySlug({ owner, repo })
+      ).then((res) => {
         if (!res.ok) {
           throw new Error(res.error.message)
         }
@@ -88,7 +106,7 @@ export function useRepoLabelsBySlug(
           error: err instanceof Error ? err.message : 'Failed to load labels'
         }))
       })
-  }, [owner, repo])
+  }, [owner, repo, settings])
 
   return state
 }
@@ -96,7 +114,8 @@ export function useRepoLabelsBySlug(
 export function useRepoAssigneesBySlug(
   owner: string | null,
   repo: string | null,
-  seedLogins?: string[]
+  seedLogins?: string[],
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
 ): MetadataState<GitHubAssignableUser[]> {
   const [state, setState] = useState<MetadataState<GitHubAssignableUser[]>>({
     data: [],
@@ -113,7 +132,11 @@ export function useRepoAssigneesBySlug(
     if (!owner || !repo) {
       return
     }
-    const key = `${owner}/${repo}#${seedKey}`
+    const target = getActiveRuntimeTarget(settings)
+    const key =
+      target.kind === 'environment'
+        ? `runtime:${target.environmentId}:${owner}/${repo}#${seedKey}`
+        : `${owner}/${repo}#${seedKey}`
 
     const cached = getFreshMetadata(slugAssigneeStore, key)
     if (cached) {
@@ -133,19 +156,26 @@ export function useRepoAssigneesBySlug(
       loading: true,
       error: null
     }))
+    const args = {
+      owner,
+      repo,
+      ...(seedKey ? { seedLogins: seedKey.split(',') } : {})
+    }
     loadMetadata(slugAssigneeStore, key, () =>
-      window.api.gh
-        .listAssignableUsersBySlug({
-          owner,
-          repo,
-          ...(seedKey ? { seedLogins: seedKey.split(',') } : {})
-        })
-        .then((res) => {
-          if (!res.ok) {
-            throw new Error(res.error.message)
-          }
-          return res.users
-        })
+      (target.kind === 'environment'
+        ? callRuntimeRpc<ListAssignableUsersBySlugResult>(
+            target,
+            'github.project.listAssignableUsersBySlug',
+            args,
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh.listAssignableUsersBySlug(args)
+      ).then((res) => {
+        if (!res.ok) {
+          throw new Error(res.error.message)
+        }
+        return res.users
+      })
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -164,7 +194,7 @@ export function useRepoAssigneesBySlug(
           error: err instanceof Error ? err.message : 'Failed to load assignees'
         }))
       })
-  }, [owner, repo, seedKey])
+  }, [owner, repo, seedKey, settings])
 
   return state
 }
diff --git a/src/renderer/src/hooks/useGlobalFileDrop.test.ts b/src/renderer/src/hooks/useGlobalFileDrop.test.ts
new file mode 100644
index 00000000000..1439e401c69
--- /dev/null
+++ b/src/renderer/src/hooks/useGlobalFileDrop.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { shouldUploadRemoteEditorFileDrop } from './useGlobalFileDrop'
+
+describe('shouldUploadRemoteEditorFileDrop', () => {
+  it('does not upload editor drops for local workspaces', () => {
+    expect(shouldUploadRemoteEditorFileDrop({ activeRuntimeEnvironmentId: null }, null)).toBe(false)
+  })
+
+  it('uploads editor drops while a runtime environment is active', () => {
+    expect(shouldUploadRemoteEditorFileDrop({ activeRuntimeEnvironmentId: 'env-1' }, null)).toBe(
+      true
+    )
+  })
+
+  it('uploads editor drops for SSH workspaces', () => {
+    expect(shouldUploadRemoteEditorFileDrop({ activeRuntimeEnvironmentId: null }, 'ssh-1')).toBe(
+      true
+    )
+  })
+})
diff --git a/src/renderer/src/hooks/useGlobalFileDrop.ts b/src/renderer/src/hooks/useGlobalFileDrop.ts
index b5020e94271..4f0564fee00 100644
--- a/src/renderer/src/hooks/useGlobalFileDrop.ts
+++ b/src/renderer/src/hooks/useGlobalFileDrop.ts
@@ -1,8 +1,24 @@
 import { useEffect } from 'react'
+import { toast } from 'sonner'
 import { detectLanguage } from '@/lib/language-detect'
 import { isPathInsideWorktree, toWorktreeRelativePath } from '@/lib/terminal-links'
 import { useAppStore } from '@/store'
 import { getConnectionId } from '@/lib/connection-context'
+import { joinPath } from '@/lib/path'
+import {
+  importExternalPathsToRuntime,
+  isRemoteRuntimeFileOperation,
+  statRuntimePath,
+  type RuntimeFileOperationArgs
+} from '@/runtime/runtime-file-client'
+import type { GlobalSettings } from '../../../shared/types'
+
+export function shouldUploadRemoteEditorFileDrop(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  connectionId: string | null | undefined
+): boolean {
+  return Boolean(settings?.activeRuntimeEnvironmentId?.trim() || connectionId?.trim())
+}
 
 export function useGlobalFileDrop(): void {
   useEffect(() => {
@@ -19,6 +35,58 @@ export function useGlobalFileDrop(): void {
 
       const activeWorktree = store.allWorktrees().find((w) => w.id === activeWorktreeId)
       const worktreePath = activeWorktree?.path
+      const connectionId = getConnectionId(activeWorktreeId) ?? undefined
+      const dropSettings = store.settings
+      const runtimeEnvironmentId = dropSettings?.activeRuntimeEnvironmentId?.trim() || undefined
+      if (shouldUploadRemoteEditorFileDrop(dropSettings, connectionId)) {
+        if (!worktreePath) {
+          toast.error('No remote workspace path is available for dropped files.')
+          return
+        }
+        void (async () => {
+          try {
+            // Why: OS file drops provide client-local paths. Remote runtime and
+            // SSH editors must upload into the server worktree before opening.
+            const destinationDir = joinPath(worktreePath, '.orca/drops')
+            const { results } = await importExternalPathsToRuntime(
+              {
+                settings: dropSettings,
+                worktreeId: activeWorktreeId,
+                worktreePath,
+                connectionId
+              },
+              data.paths,
+              destinationDir,
+              { ensureDestinationDir: true }
+            )
+            const imported = results.filter((result) => result.status === 'imported')
+            for (const result of imported) {
+              if (result.kind === 'directory') {
+                continue
+              }
+              const maybeRelative = toWorktreeRelativePath(result.destPath, worktreePath)
+              store.setActiveTabType('editor')
+              store.openFile(
+                {
+                  filePath: result.destPath,
+                  relativePath: maybeRelative ?? result.destPath,
+                  worktreeId: activeWorktreeId,
+                  runtimeEnvironmentId,
+                  language: detectLanguage(result.destPath),
+                  mode: 'edit'
+                },
+                { suppressActiveRuntimeFallback: runtimeEnvironmentId === undefined }
+              )
+            }
+            if (results.some((result) => result.status !== 'imported')) {
+              toast.error('Some dropped files could not be uploaded.')
+            }
+          } catch {
+            toast.error('Failed to upload dropped files.')
+          }
+        })()
+        return
+      }
 
       // Why: the relay payload now sends all paths in one gesture-scoped event.
       // Loop over every dropped file so multi-file editor drops still open
@@ -26,12 +94,18 @@ export function useGlobalFileDrop(): void {
       for (const filePath of data.paths) {
         void (async () => {
           try {
-            const connectionId = getConnectionId(activeWorktreeId) ?? undefined
-            // Why: remote paths don't need local auth — the relay is the security boundary.
-            if (!connectionId) {
+            const fileContext: RuntimeFileOperationArgs = {
+              settings: store.settings,
+              worktreeId: activeWorktreeId,
+              worktreePath,
+              connectionId
+            }
+            const isRemoteRuntimePath = isRemoteRuntimeFileOperation(fileContext, filePath)
+            // Why: remote paths don't need local auth — the relay/runtime is the security boundary.
+            if (!connectionId && !isRemoteRuntimePath) {
               await window.api.fs.authorizeExternalPath({ targetPath: filePath })
             }
-            const stat = await window.api.fs.stat({ filePath, connectionId })
+            const stat = await statRuntimePath(fileContext, filePath)
             if (stat.isDirectory) {
               return
             }
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index 65ee868a261..ada47027c8e 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -40,6 +40,10 @@ export { resolveZoomTarget } from './resolve-zoom-target'
 
 const ZOOM_STEP = 0.5
 
+function isRuntimeEnvironmentActive(): boolean {
+  return Boolean(useAppStore.getState().settings?.activeRuntimeEnvironmentId?.trim())
+}
+
 export function useIpcEvents(): void {
   useEffect(() => {
     const unsubs: (() => void)[] = []
@@ -48,12 +52,23 @@ export function useIpcEvents(): void {
 
     unsubs.push(
       window.api.repos.onChanged(() => {
+        if (isRuntimeEnvironmentActive()) {
+          // Why: this event comes from the local Electron store. While a
+          // runtime server is selected, repo hydration must be driven by the
+          // selected server instead of local-disk changes.
+          return
+        }
         useAppStore.getState().fetchRepos()
       })
     )
 
     unsubs.push(
       window.api.worktrees.onChanged(async (data: { repoId: string }) => {
+        if (isRuntimeEnvironmentActive()) {
+          // Why: local worktree events carry local repo ids. Fetching the
+          // active runtime with those ids can purge or overwrite server state.
+          return
+        }
         // Why: diff before vs. after fetchWorktrees to detect server-side
         // deletions (CLI `orca worktree rm`, other window, out-of-band RPC)
         // and purge worktree-scoped state for removed ids. Without this,
@@ -83,12 +98,18 @@ export function useIpcEvents(): void {
 
     unsubs.push(
       window.api.worktrees.onBaseStatus((event) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         useAppStore.getState().updateWorktreeBaseStatus(event)
       })
     )
 
     unsubs.push(
       window.api.worktrees.onRemoteBranchConflict((event) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         useAppStore.getState().updateWorktreeRemoteBranchConflict(event)
       })
     )
@@ -230,6 +251,12 @@ export function useIpcEvents(): void {
     unsubs.push(
       window.api.ui.onActivateWorktree(({ repoId, worktreeId, setup, startup }) => {
         void (async () => {
+          if (isRuntimeEnvironmentActive()) {
+            // Why: local CLI-created worktree events carry local repo/worktree
+            // ids. Runtime server activation arrives through runtime state,
+            // not this local Electron event.
+            return
+          }
           // Why: fetch worktrees first so the activation helper can resolve
           // the CLI-created worktree via findWorktreeById — it arrived from
           // the main process and is not yet in the renderer state.
@@ -250,6 +277,15 @@ export function useIpcEvents(): void {
       window.api.ui.onCreateTerminal(
         ({ requestId, worktreeId, command, title, ptyId, activate, tabId }) => {
           try {
+            if (isRuntimeEnvironmentActive()) {
+              if (requestId) {
+                window.api.ui.replyTerminalCreate({
+                  requestId,
+                  error: 'Local terminal reveal is unavailable while a remote runtime is active'
+                })
+              }
+              return
+            }
             const store = useAppStore.getState()
             const shouldActivate = activate !== false
             if (shouldActivate) {
@@ -324,6 +360,13 @@ export function useIpcEvents(): void {
     unsubs.push(
       window.api.ui.onRequestTerminalCreate((data) => {
         try {
+          if (isRuntimeEnvironmentActive()) {
+            window.api.ui.replyTerminalCreate({
+              requestId: data.requestId,
+              error: 'Local terminal creation is unavailable while a remote runtime is active'
+            })
+            return
+          }
           const store = useAppStore.getState()
           const worktreeId = data.worktreeId ?? store.activeWorktreeId
           if (!worktreeId) {
@@ -510,6 +553,9 @@ export function useIpcEvents(): void {
 
     unsubs.push(
       window.api.browser.onGuestLoadFailed(({ browserPageId, loadError }) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         useAppStore.getState().updateBrowserPageState(browserPageId, {
           loading: false,
           loadError,
@@ -525,6 +571,9 @@ export function useIpcEvents(): void {
     // This IPC pushes the live URL/title from main after goto/click/back/reload.
     unsubs.push(
       window.api.browser.onNavigationUpdate(({ browserPageId, url, title }) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         const store = useAppStore.getState()
         store.setBrowserPageUrl(browserPageId, url)
         store.updateBrowserPageState(browserPageId, { title, loading: false })
@@ -537,6 +586,9 @@ export function useIpcEvents(): void {
     // before browser commands so the webview can start and registerGuest fires.
     unsubs.push(
       window.api.browser.onActivateView(() => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         useAppStore.getState().setActiveTabType('browser')
       })
     )
@@ -552,6 +604,9 @@ export function useIpcEvents(): void {
     // pre-staging for whenever the user next visits that worktree.
     unsubs.push(
       window.api.browser.onPaneFocus(({ worktreeId, browserPageId }) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         const store = useAppStore.getState()
         // Why: main sends `worktreeId: null` if the tab closed between the
         // bridge resolving tabSwitch and getWorktreeIdForTab running. Falling
@@ -568,6 +623,9 @@ export function useIpcEvents(): void {
 
     unsubs.push(
       window.api.browser.onOpenLinkInOrcaTab(({ browserPageId, url }) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         const store = useAppStore.getState()
         const sourcePage = Object.values(store.browserPagesByWorkspace)
           .flat()
@@ -587,6 +645,9 @@ export function useIpcEvents(): void {
     // capture keyboard focus and bypass the renderer's window-level keydown.
     unsubs.push(
       window.api.ui.onNewBrowserTab(() => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         const store = useAppStore.getState()
         const worktreeId = store.activeWorktreeId
         if (worktreeId) {
@@ -604,6 +665,15 @@ export function useIpcEvents(): void {
     unsubs.push(
       window.api.ui.onRequestTabCreate((data) => {
         try {
+          if (isRuntimeEnvironmentActive()) {
+            // Why: browser automation targets client-local Electron webviews.
+            // Runtime agents cannot see or control those surfaces.
+            window.api.ui.replyTabCreate({
+              requestId: data.requestId,
+              error: 'Browser tabs are unavailable while a remote runtime is active'
+            })
+            return
+          }
           const store = useAppStore.getState()
           const worktreeId = data.worktreeId ?? store.activeWorktreeId
           if (!worktreeId) {
@@ -643,6 +713,13 @@ export function useIpcEvents(): void {
     unsubs.push(
       window.api.ui.onRequestTabSetProfile((data) => {
         try {
+          if (isRuntimeEnvironmentActive()) {
+            window.api.ui.replyTabSetProfile({
+              requestId: data.requestId,
+              error: 'Browser profiles are unavailable while a remote runtime is active'
+            })
+            return
+          }
           const store = useAppStore.getState()
           const owningWorkspace = Object.values(store.browserTabsByWorktree)
             .flat()
@@ -684,6 +761,13 @@ export function useIpcEvents(): void {
     unsubs.push(
       window.api.ui.onRequestTabClose((data) => {
         try {
+          if (isRuntimeEnvironmentActive()) {
+            window.api.ui.replyTabClose({
+              requestId: data.requestId,
+              error: 'Browser tabs are unavailable while a remote runtime is active'
+            })
+            return
+          }
           const store = useAppStore.getState()
           const explicitTargetId = data.tabId ?? null
           let tabToClose =
@@ -1121,12 +1205,17 @@ export function useIpcEvents(): void {
 
     // Why: hydrate mobile-fit overrides before terminal panes run their first
     // attach/fit logic, so a renderer reload doesn't undo active mobile fits.
-    void window.api.runtime.getTerminalFitOverrides().then((overrides) => {
-      hydrateOverrides(overrides)
-    })
+    if (!isRuntimeEnvironmentActive()) {
+      void window.api.runtime.getTerminalFitOverrides().then((overrides) => {
+        hydrateOverrides(overrides)
+      })
+    }
 
     unsubs.push(
       window.api.runtime.onTerminalFitOverrideChanged((event) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         setFitOverride(event.ptyId, event.mode, event.cols, event.rows)
       })
     )
@@ -1137,6 +1226,9 @@ export function useIpcEvents(): void {
       // know which PTYs are currently driven by mobile. See
       // docs/mobile-presence-lock.md.
       window.api.runtime.onTerminalDriverChanged((event) => {
+        if (isRuntimeEnvironmentActive()) {
+          return
+        }
         setDriverForPty(event.ptyId, event.driver)
       })
     )
diff --git a/src/renderer/src/hooks/useIssueMetadata.ts b/src/renderer/src/hooks/useIssueMetadata.ts
index c715d6cb550..deec6cb6a9b 100644
--- a/src/renderer/src/hooks/useIssueMetadata.ts
+++ b/src/renderer/src/hooks/useIssueMetadata.ts
@@ -1,6 +1,15 @@
+/* eslint-disable max-lines -- Why: repo metadata hooks share TTL caches and
+Linear/GitHub cache invalidation entrypoints used by the issue dialog. */
 import { useEffect, useRef, useState } from 'react'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import {
+  linearTeamLabels,
+  linearTeamMembers,
+  linearTeamStates
+} from '@/runtime/runtime-linear-client'
 import type {
   GitHubAssignableUser,
+  GlobalSettings,
   LinearWorkflowState,
   LinearLabel,
   LinearMember
@@ -23,7 +32,11 @@ type MetadataState<T> = {
 const ghLabelStore = createMetadataRequestStore<string[]>()
 const ghAssigneeStore = createMetadataRequestStore<GitHubAssignableUser[]>()
 
-export function useRepoLabels(repoPath: string | null): MetadataState<string[]> {
+export function useRepoLabels(
+  repoPath: string | null,
+  repoId?: string | null,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+): MetadataState<string[]> {
   const [state, setState] = useState<MetadataState<string[]>>({
     data: [],
     loading: false,
@@ -32,29 +45,41 @@ export function useRepoLabels(repoPath: string | null): MetadataState<string[]>
   const activeKeyRef = useRef<string | null>(null)
 
   useEffect(() => {
-    if (!repoPath) {
+    const target = getActiveRuntimeTarget(settings)
+    if (!repoPath && !(target.kind === 'environment' && repoId)) {
       return
     }
+    const cacheKey =
+      target.kind === 'environment' ? `runtime:${target.environmentId}:${repoId}` : (repoPath ?? '')
 
-    const cached = getFreshMetadata(ghLabelStore, repoPath)
+    const cached = getFreshMetadata(ghLabelStore, cacheKey)
     if (cached) {
-      if (activeKeyRef.current !== repoPath) {
+      if (activeKeyRef.current !== cacheKey) {
         setState({ data: cached.data, loading: false, error: null })
-        activeKeyRef.current = repoPath
+        activeKeyRef.current = cacheKey
       }
       return
     }
 
-    activeKeyRef.current = repoPath
-    const requestKey = repoPath
+    activeKeyRef.current = cacheKey
+    const requestKey = cacheKey
     setState((s) => ({
       ...s,
       data: s.data.length ? ([] as typeof s.data) : s.data,
       loading: true,
       error: null
     }))
-    loadMetadata(ghLabelStore, repoPath, () =>
-      window.api.gh.listLabels({ repoPath }).then((labels) => labels as string[])
+    loadMetadata(ghLabelStore, cacheKey, () =>
+      target.kind === 'environment'
+        ? callRuntimeRpc<string[]>(
+            target,
+            'github.listLabels',
+            { repo: repoId ?? '' },
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh
+            .listLabels({ repoPath: repoPath ?? '' })
+            .then((labels) => labels as string[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -73,12 +98,16 @@ export function useRepoLabels(repoPath: string | null): MetadataState<string[]>
           error: err instanceof Error ? err.message : 'Failed to load labels'
         }))
       })
-  }, [repoPath])
+  }, [repoId, repoPath, settings])
 
   return state
 }
 
-export function useRepoAssignees(repoPath: string | null): MetadataState<GitHubAssignableUser[]> {
+export function useRepoAssignees(
+  repoPath: string | null,
+  repoId?: string | null,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+): MetadataState<GitHubAssignableUser[]> {
   const [state, setState] = useState<MetadataState<GitHubAssignableUser[]>>({
     data: [],
     loading: false,
@@ -87,31 +116,41 @@ export function useRepoAssignees(repoPath: string | null): MetadataState<GitHubA
   const activeKeyRef = useRef<string | null>(null)
 
   useEffect(() => {
-    if (!repoPath) {
+    const target = getActiveRuntimeTarget(settings)
+    if (!repoPath && !(target.kind === 'environment' && repoId)) {
       return
     }
+    const cacheKey =
+      target.kind === 'environment' ? `runtime:${target.environmentId}:${repoId}` : (repoPath ?? '')
 
-    const cached = getFreshMetadata(ghAssigneeStore, repoPath)
+    const cached = getFreshMetadata(ghAssigneeStore, cacheKey)
     if (cached) {
-      if (activeKeyRef.current !== repoPath) {
+      if (activeKeyRef.current !== cacheKey) {
         setState({ data: cached.data, loading: false, error: null })
-        activeKeyRef.current = repoPath
+        activeKeyRef.current = cacheKey
       }
       return
     }
 
-    activeKeyRef.current = repoPath
-    const requestKey = repoPath
+    activeKeyRef.current = cacheKey
+    const requestKey = cacheKey
     setState((s) => ({
       ...s,
       data: s.data.length ? ([] as typeof s.data) : s.data,
       loading: true,
       error: null
     }))
-    loadMetadata(ghAssigneeStore, repoPath, () =>
-      window.api.gh
-        .listAssignableUsers({ repoPath })
-        .then((users) => users as GitHubAssignableUser[])
+    loadMetadata(ghAssigneeStore, cacheKey, () =>
+      target.kind === 'environment'
+        ? callRuntimeRpc<GitHubAssignableUser[]>(
+            target,
+            'github.listAssignableUsers',
+            { repo: repoId ?? '' },
+            { timeoutMs: 30_000 }
+          )
+        : window.api.gh
+            .listAssignableUsers({ repoPath: repoPath ?? '' })
+            .then((users) => users as GitHubAssignableUser[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -130,7 +169,7 @@ export function useRepoAssignees(repoPath: string | null): MetadataState<GitHubA
           error: err instanceof Error ? err.message : 'Failed to load assignees'
         }))
       })
-  }, [repoPath])
+  }, [repoId, repoPath, settings])
 
   return state
 }
@@ -141,6 +180,14 @@ const linearStateStore = createMetadataRequestStore<LinearWorkflowState[]>()
 const linearLabelStore = createMetadataRequestStore<LinearLabel[]>()
 const linearMemberStore = createMetadataRequestStore<LinearMember[]>()
 
+function linearMetadataCacheKey(
+  teamId: string,
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): string {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment' ? `runtime:${target.environmentId}:${teamId}` : teamId
+}
+
 export function clearLinearMetadataCache(): void {
   clearMetadataRequestStore(linearStateStore)
   clearMetadataRequestStore(linearLabelStore)
@@ -152,7 +199,10 @@ export function clearGitHubMetadataCache(): void {
   clearMetadataRequestStore(ghAssigneeStore)
 }
 
-export function useTeamStates(teamId: string | null): MetadataState<LinearWorkflowState[]> {
+export function useTeamStates(
+  teamId: string | null,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+): MetadataState<LinearWorkflowState[]> {
   const [state, setState] = useState<MetadataState<LinearWorkflowState[]>>({
     data: [],
     loading: false,
@@ -165,25 +215,26 @@ export function useTeamStates(teamId: string | null): MetadataState<LinearWorkfl
       return
     }
 
-    const cached = getFreshMetadata(linearStateStore, teamId)
+    const cacheKey = linearMetadataCacheKey(teamId, settings)
+    const cached = getFreshMetadata(linearStateStore, cacheKey)
     if (cached) {
-      if (activeKeyRef.current !== teamId) {
+      if (activeKeyRef.current !== cacheKey) {
         setState({ data: cached.data, loading: false, error: null })
-        activeKeyRef.current = teamId
+        activeKeyRef.current = cacheKey
       }
       return
     }
 
-    activeKeyRef.current = teamId
-    const requestKey = teamId
+    activeKeyRef.current = cacheKey
+    const requestKey = cacheKey
     setState((s) => ({
       ...s,
       data: s.data.length ? ([] as typeof s.data) : s.data,
       loading: true,
       error: null
     }))
-    loadMetadata(linearStateStore, teamId, () =>
-      window.api.linear.teamStates({ teamId }).then((states) => states as LinearWorkflowState[])
+    loadMetadata(linearStateStore, cacheKey, () =>
+      linearTeamStates(settings, teamId).then((states) => states as LinearWorkflowState[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -202,12 +253,15 @@ export function useTeamStates(teamId: string | null): MetadataState<LinearWorkfl
           error: err instanceof Error ? err.message : 'Failed to load states'
         }))
       })
-  }, [teamId])
+  }, [settings, teamId])
 
   return state
 }
 
-export function useTeamLabels(teamId: string | null): MetadataState<LinearLabel[]> {
+export function useTeamLabels(
+  teamId: string | null,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+): MetadataState<LinearLabel[]> {
   const [state, setState] = useState<MetadataState<LinearLabel[]>>({
     data: [],
     loading: false,
@@ -220,25 +274,26 @@ export function useTeamLabels(teamId: string | null): MetadataState<LinearLabel[
       return
     }
 
-    const cached = getFreshMetadata(linearLabelStore, teamId)
+    const cacheKey = linearMetadataCacheKey(teamId, settings)
+    const cached = getFreshMetadata(linearLabelStore, cacheKey)
     if (cached) {
-      if (activeKeyRef.current !== teamId) {
+      if (activeKeyRef.current !== cacheKey) {
         setState({ data: cached.data, loading: false, error: null })
-        activeKeyRef.current = teamId
+        activeKeyRef.current = cacheKey
       }
       return
     }
 
-    activeKeyRef.current = teamId
-    const requestKey = teamId
+    activeKeyRef.current = cacheKey
+    const requestKey = cacheKey
     setState((s) => ({
       ...s,
       data: s.data.length ? ([] as typeof s.data) : s.data,
       loading: true,
       error: null
     }))
-    loadMetadata(linearLabelStore, teamId, () =>
-      window.api.linear.teamLabels({ teamId }).then((labels) => labels as LinearLabel[])
+    loadMetadata(linearLabelStore, cacheKey, () =>
+      linearTeamLabels(settings, teamId).then((labels) => labels as LinearLabel[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -257,12 +312,15 @@ export function useTeamLabels(teamId: string | null): MetadataState<LinearLabel[
           error: err instanceof Error ? err.message : 'Failed to load labels'
         }))
       })
-  }, [teamId])
+  }, [settings, teamId])
 
   return state
 }
 
-export function useTeamMembers(teamId: string | null): MetadataState<LinearMember[]> {
+export function useTeamMembers(
+  teamId: string | null,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+): MetadataState<LinearMember[]> {
   const [state, setState] = useState<MetadataState<LinearMember[]>>({
     data: [],
     loading: false,
@@ -275,25 +333,26 @@ export function useTeamMembers(teamId: string | null): MetadataState<LinearMembe
       return
     }
 
-    const cached = getFreshMetadata(linearMemberStore, teamId)
+    const cacheKey = linearMetadataCacheKey(teamId, settings)
+    const cached = getFreshMetadata(linearMemberStore, cacheKey)
     if (cached) {
-      if (activeKeyRef.current !== teamId) {
+      if (activeKeyRef.current !== cacheKey) {
         setState({ data: cached.data, loading: false, error: null })
-        activeKeyRef.current = teamId
+        activeKeyRef.current = cacheKey
       }
       return
     }
 
-    activeKeyRef.current = teamId
-    const requestKey = teamId
+    activeKeyRef.current = cacheKey
+    const requestKey = cacheKey
     setState((s) => ({
       ...s,
       data: s.data.length ? ([] as typeof s.data) : s.data,
       loading: true,
       error: null
     }))
-    loadMetadata(linearMemberStore, teamId, () =>
-      window.api.linear.teamMembers({ teamId }).then((members) => members as LinearMember[])
+    loadMetadata(linearMemberStore, cacheKey, () =>
+      linearTeamMembers(settings, teamId).then((members) => members as LinearMember[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -312,7 +371,7 @@ export function useTeamMembers(teamId: string | null): MetadataState<LinearMembe
           error: err instanceof Error ? err.message : 'Failed to load members'
         }))
       })
-  }, [teamId])
+  }, [settings, teamId])
 
   return state
 }
diff --git a/src/renderer/src/lib/agent-paste-draft.ts b/src/renderer/src/lib/agent-paste-draft.ts
index cdce83c8272..5dd27b91dc8 100644
--- a/src/renderer/src/lib/agent-paste-draft.ts
+++ b/src/renderer/src/lib/agent-paste-draft.ts
@@ -2,6 +2,8 @@ import type { TuiAgent } from '../../../shared/types'
 import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
 import { useAppStore } from '@/store'
 import { subscribeToPtyData } from '@/components/terminal-pane/pty-dispatcher'
+import { isRemoteRuntimePtyId, sendRuntimePtyInput } from '@/runtime/runtime-terminal-inspection'
+import { subscribeToRuntimeTerminalData } from '@/runtime/runtime-terminal-stream'
 
 // Why: bracketed paste markers let modern TUIs (Claude Code / Codex / Pi /
 // OpenCode / Gemini / cursor-agent / copilot) treat the inserted text as a
@@ -89,7 +91,8 @@ export async function pasteDraftWhenAgentReady(args: {
     return false
   }
 
-  window.api.pty.write(
+  sendRuntimePtyInput(
+    useAppStore.getState().settings,
     ptyId,
     `${BRACKETED_PASTE_BEGIN}${content}${BRACKETED_PASTE_END}${submit ? '\r' : ''}`
   )
@@ -136,7 +139,7 @@ function waitForInputBoxReady(ptyId: string, timeoutMs: number): Promise<boolean
       quietTimer = window.setTimeout(() => finish(true), BRACKETED_PASTE_QUIET_MS)
     }
 
-    unsubscribe = subscribeToPtyData(ptyId, (data) => {
+    const observeData = (data: string): void => {
       // Why: keep just enough recent bytes that an escape sequence split
       // across two IPC frames is still detectable. 64 bytes >> 8-byte
       // sequence; cheap and bounded.
@@ -151,7 +154,26 @@ function waitForInputBoxReady(ptyId: string, timeoutMs: number): Promise<boolean
         // mounted and bracketed paste lands in the input buffer.
         armQuietTimer()
       }
-    })
+    }
+
+    if (isRemoteRuntimePtyId(ptyId)) {
+      void subscribeToRuntimeTerminalData(
+        useAppStore.getState().settings,
+        ptyId,
+        `desktop:paste-ready:${ptyId}`,
+        observeData
+      )
+        .then((remoteUnsubscribe) => {
+          if (settled) {
+            remoteUnsubscribe()
+            return
+          }
+          unsubscribe = remoteUnsubscribe
+        })
+        .catch(() => finish(false))
+    } else {
+      unsubscribe = subscribeToPtyData(ptyId, observeData)
+    }
 
     const hardTimer = window.setTimeout(() => finish(false), timeoutMs)
   })
diff --git a/src/renderer/src/lib/agent-ready-wait.ts b/src/renderer/src/lib/agent-ready-wait.ts
index 70af9f83910..84b75c721f9 100644
--- a/src/renderer/src/lib/agent-ready-wait.ts
+++ b/src/renderer/src/lib/agent-ready-wait.ts
@@ -1,6 +1,7 @@
 import { detectAgentStatusFromTitle } from '../../../shared/agent-detection'
 import { isShellProcess } from '@/lib/tui-agent-startup'
 import { useAppStore } from '@/store'
+import { inspectRuntimeTerminalProcess } from '@/runtime/runtime-terminal-inspection'
 
 // Why: agent CLIs vary widely in how they signal readiness. Title-based
 // detection (OSC titles parsed by detectAgentStatusFromTitle) is the tightest
@@ -89,7 +90,8 @@ export async function waitForAgentReady(
     }
 
     try {
-      const foreground = (await window.api.pty.getForegroundProcess(ptyId))?.toLowerCase() ?? ''
+      const process = await inspectRuntimeTerminalProcess(useAppStore.getState().settings, ptyId)
+      const foreground = process.foregroundProcess?.toLowerCase() ?? ''
       if (
         foreground === expectedProcess ||
         foreground.startsWith(`${expectedProcess}.`) ||
@@ -103,8 +105,7 @@ export async function waitForAgentReady(
       // polls so the shell's own startup children don't spoof readiness on
       // cold-start. Never accept it while the foreground is still a shell.
       if (attempt >= 4 && !isShellProcess(foreground)) {
-        const hasChildProcesses = await window.api.pty.hasChildProcesses(ptyId)
-        if (hasChildProcesses) {
+        if (process.hasChildProcesses) {
           return { ready: true, reason: 'child-process' }
         }
       }
diff --git a/src/renderer/src/lib/codex-session-restart.test.ts b/src/renderer/src/lib/codex-session-restart.test.ts
index e32c733b54c..e3ec0811c8e 100644
--- a/src/renderer/src/lib/codex-session-restart.test.ts
+++ b/src/renderer/src/lib/codex-session-restart.test.ts
@@ -1,6 +1,11 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { useAppStore } from '@/store'
 import { markLiveCodexSessionsForRestart } from './codex-session-restart'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '@/runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '@/runtime/runtime-rpc-client'
 
 const ACCOUNT_A = 'account-a@example.com'
 const ACCOUNT_B = 'account-b@example.com'
@@ -8,8 +13,16 @@ const ACCOUNT_C = 'account-c@example.com'
 
 describe('markLiveCodexSessionsForRestart', () => {
   const originalWindow = (globalThis as { window?: typeof window }).window
+  const runtimeEnvironmentCall = vi.fn()
+  const runtimeEnvironmentTransportCall = vi.fn()
 
   beforeEach(() => {
+    clearRuntimeCompatibilityCacheForTests()
+    runtimeEnvironmentCall.mockReset()
+    runtimeEnvironmentTransportCall.mockReset()
+    runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+      return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+    })
     useAppStore.setState({
       tabsByWorktree: {
         wt1: [
@@ -39,7 +52,12 @@ describe('markLiveCodexSessionsForRestart', () => {
         ...originalWindow?.api,
         pty: {
           ...originalWindow?.api?.pty,
-          getForegroundProcess: vi.fn()
+          getForegroundProcess: vi.fn(),
+          hasChildProcesses: vi.fn().mockResolvedValue(false)
+        },
+        runtimeEnvironments: {
+          ...originalWindow?.api?.runtimeEnvironments,
+          call: runtimeEnvironmentTransportCall
         }
       }
     } as unknown as typeof window
@@ -143,4 +161,52 @@ describe('markLiveCodexSessionsForRestart', () => {
       nextAccountLabel: ACCOUNT_C
     })
   })
+
+  it('inspects remote runtime PTYs through the active runtime environment', async () => {
+    useAppStore.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab-1',
+            ptyId: 'remote:term-1',
+            worktreeId: 'wt1',
+            title: 'orca-1',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          }
+        ]
+      },
+      ptyIdsByTabId: {
+        'tab-1': ['remote:term-1']
+      }
+    })
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: {
+        process: { foregroundProcess: 'codex', hasChildProcesses: true }
+      },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await markLiveCodexSessionsForRestart({
+      previousAccountLabel: ACCOUNT_A,
+      nextAccountLabel: ACCOUNT_B
+    })
+
+    expect(window.api.pty.getForegroundProcess).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'terminal.inspectProcess',
+      params: { terminal: 'term-1' },
+      timeoutMs: 15_000
+    })
+    expect(useAppStore.getState().codexRestartNoticeByPtyId['remote:term-1']).toEqual({
+      previousAccountLabel: ACCOUNT_A,
+      nextAccountLabel: ACCOUNT_B
+    })
+  })
 })
diff --git a/src/renderer/src/lib/codex-session-restart.ts b/src/renderer/src/lib/codex-session-restart.ts
index a3a71f2d669..6e7a46bb156 100644
--- a/src/renderer/src/lib/codex-session-restart.ts
+++ b/src/renderer/src/lib/codex-session-restart.ts
@@ -1,5 +1,6 @@
 import type { AppState } from '@/store'
 import { useAppStore } from '@/store'
+import { inspectRuntimeTerminalProcess } from '@/runtime/runtime-terminal-inspection'
 
 function normalizeProcessName(processName: string | null): string | null {
   if (!processName) {
@@ -34,7 +35,11 @@ async function getLiveCodexSessionPtyIds(state: AppState): Promise<string[]> {
       // does not always do that. The foreground PTY process is the stable
       // source of truth for whether this live tab is actually running Codex.
       const foregroundProcesses = await Promise.all(
-        ptyIds.map((ptyId) => window.api.pty.getForegroundProcess(ptyId))
+        ptyIds.map((ptyId) =>
+          inspectRuntimeTerminalProcess(state.settings, ptyId).then(
+            (inspection) => inspection.foregroundProcess
+          )
+        )
       )
       return ptyIds.filter((_, index) => isCodexForegroundProcess(foregroundProcesses[index]))
     })
diff --git a/src/renderer/src/lib/create-untitled-markdown.test.ts b/src/renderer/src/lib/create-untitled-markdown.test.ts
index 0b43bfcea72..e5768ffede4 100644
--- a/src/renderer/src/lib/create-untitled-markdown.test.ts
+++ b/src/renderer/src/lib/create-untitled-markdown.test.ts
@@ -1,5 +1,10 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createUntitledMarkdownFile } from './create-untitled-markdown'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '@/runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '@/runtime/runtime-rpc-client'
 
 describe('createUntitledMarkdownFile', () => {
   afterEach(() => {
@@ -7,7 +12,13 @@ describe('createUntitledMarkdownFile', () => {
   })
 
   it('retries with the next untitled name when createFile loses the EEXIST race', async () => {
-    const pathExists = vi.fn(async (filePath: string) => filePath.endsWith('untitled.md'))
+    const pathExists = vi.fn()
+    const stat = vi.fn(async (args: { filePath: string }) => {
+      if (args.filePath.endsWith('untitled.md')) {
+        return { size: 0, isDirectory: false, mtime: 1 }
+      }
+      throw new Error('ENOENT: no such file')
+    })
     const createFile = vi
       .fn()
       .mockRejectedValueOnce(new Error('EEXIST: file already exists'))
@@ -16,7 +27,7 @@ describe('createUntitledMarkdownFile', () => {
     vi.stubGlobal('window', {
       api: {
         shell: { pathExists },
-        fs: { createFile }
+        fs: { createFile, stat }
       }
     })
 
@@ -31,16 +42,18 @@ describe('createUntitledMarkdownFile', () => {
 
     expect(createFile).toHaveBeenNthCalledWith(1, { filePath: '/repo/untitled-2.md' })
     expect(createFile).toHaveBeenNthCalledWith(2, { filePath: '/repo/untitled-3.md' })
+    expect(pathExists).not.toHaveBeenCalled()
   })
 
   it('throws a descriptive error when untitled names are exhausted', async () => {
     const pathExists = vi.fn(async () => true)
+    const stat = vi.fn().mockResolvedValue({ size: 0, isDirectory: false, mtime: 1 })
     const createFile = vi.fn()
 
     vi.stubGlobal('window', {
       api: {
         shell: { pathExists },
-        fs: { createFile }
+        fs: { createFile, stat }
       }
     })
 
@@ -49,16 +62,18 @@ describe('createUntitledMarkdownFile', () => {
     )
 
     expect(createFile).not.toHaveBeenCalled()
+    expect(pathExists).not.toHaveBeenCalled()
   })
 
-  it('passes connectionId to createFile and skips the local pathExists probe for SSH worktrees', async () => {
+  it('passes connectionId to stat and createFile for SSH worktrees', async () => {
     const pathExists = vi.fn(async () => false)
+    const stat = vi.fn().mockRejectedValue(new Error('ENOENT: no such file'))
     const createFile = vi.fn().mockResolvedValueOnce(undefined)
 
     vi.stubGlobal('window', {
       api: {
         shell: { pathExists },
-        fs: { createFile }
+        fs: { createFile, stat }
       }
     })
 
@@ -66,13 +81,71 @@ describe('createUntitledMarkdownFile', () => {
       filePath: '/repo/untitled.md'
     })
 
-    // Why: shell.pathExists is main-process local-only; probing it on SSH
-    // worktrees always reports "not found" or succeeds against the wrong
-    // filesystem, so the probe must be skipped when a connectionId is set.
+    // Why: shell.pathExists is main-process local-only; SSH worktrees must
+    // probe through the same filesystem API that receives the connectionId.
     expect(pathExists).not.toHaveBeenCalled()
+    expect(stat).toHaveBeenCalledWith({
+      filePath: '/repo/untitled.md',
+      connectionId: 'conn-1'
+    })
     expect(createFile).toHaveBeenCalledWith({
       filePath: '/repo/untitled.md',
       connectionId: 'conn-1'
     })
   })
+
+  it('creates untitled files through the selected runtime environment', async () => {
+    clearRuntimeCompatibilityCacheForTests()
+    const stat = vi.fn()
+    const createFile = vi.fn()
+    const runtimeEnvironmentCall = vi
+      .fn()
+      .mockResolvedValueOnce({
+        id: 'rpc-1',
+        ok: false,
+        error: { message: 'ENOENT: no such file' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'rpc-2',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+    const runtimeEnvironmentTransportCall = vi.fn((args: RuntimeEnvironmentCallRequest) => {
+      return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+    })
+
+    vi.stubGlobal('window', {
+      api: {
+        shell: { pathExists: vi.fn() },
+        fs: { createFile, stat },
+        runtimeEnvironments: { call: runtimeEnvironmentTransportCall }
+      }
+    })
+
+    await expect(
+      createUntitledMarkdownFile('/remote/repo', 'wt-1', undefined, {
+        activeRuntimeEnvironmentId: 'env-1'
+      })
+    ).resolves.toMatchObject({
+      filePath: '/remote/repo/untitled.md',
+      relativePath: 'untitled.md'
+    })
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'files.stat',
+      params: { worktree: 'wt-1', relativePath: 'untitled.md' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'files.createFile',
+      params: { worktree: 'wt-1', relativePath: 'untitled.md' },
+      timeoutMs: 15_000
+    })
+    expect(stat).not.toHaveBeenCalled()
+    expect(createFile).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/lib/create-untitled-markdown.ts b/src/renderer/src/lib/create-untitled-markdown.ts
index ee3023dd712..3d41674f160 100644
--- a/src/renderer/src/lib/create-untitled-markdown.ts
+++ b/src/renderer/src/lib/create-untitled-markdown.ts
@@ -1,3 +1,5 @@
+import type { GlobalSettings } from '../../../shared/types'
+import { createRuntimePath, runtimePathExists } from '../runtime/runtime-file-client'
 import { detectLanguage } from './language-detect'
 import { joinPath } from './path'
 
@@ -11,7 +13,8 @@ import { joinPath } from './path'
 export async function createUntitledMarkdownFile(
   worktreePath: string,
   worktreeId: string,
-  connectionId?: string
+  connectionId?: string,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
 ): Promise<{
   filePath: string
   relativePath: string
@@ -30,21 +33,19 @@ export async function createUntitledMarkdownFile(
   // nearly the same time. Retrying EEXIST keeps "New Markdown" advancing to
   // the next untitled-N name instead of surfacing a spurious error toast.
   //
-  // Why (SSH): window.api.shell.pathExists is a local-only main-process probe
-  // and cannot see files on a remote host. For SSH worktrees we skip the probe
-  // and rely solely on the EEXIST retry loop; otherwise every attempt reports
-  // "not found" locally, then fails in the main process when createFile tries
-  // to authorize the remote path against local allowed roots.
+  // Why: existence probing must go through the same runtime/SSH-aware file
+  // surface as creation; the shell probe only sees the client filesystem.
   for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
     const fileName = attempt === 1 ? `${baseName}${ext}` : `${baseName}-${attempt}${ext}`
     const filePath = joinPath(worktreePath, fileName)
+    const context = { settings, worktreeId, worktreePath, connectionId }
 
-    if (!connectionId && (await window.api.shell.pathExists(filePath))) {
+    if (await runtimePathExists(context, filePath)) {
       continue
     }
 
     try {
-      await window.api.fs.createFile({ filePath, connectionId })
+      await createRuntimePath(context, filePath, 'file')
 
       return {
         filePath,
diff --git a/src/renderer/src/lib/ensure-hooks-confirmed.ts b/src/renderer/src/lib/ensure-hooks-confirmed.ts
index 63f060b3ec6..eeb1f4a71a7 100644
--- a/src/renderer/src/lib/ensure-hooks-confirmed.ts
+++ b/src/renderer/src/lib/ensure-hooks-confirmed.ts
@@ -1,6 +1,7 @@
 import type { AppState } from '@/store/types'
 import type { OrcaHooks } from '../../../shared/types'
 import { hashOrcaHookScript, type OrcaHookScriptKind } from './orca-hook-trust'
+import { checkRuntimeHooks, readRuntimeIssueCommand } from '@/runtime/runtime-hooks-client'
 
 export type HookScriptKind = OrcaHookScriptKind
 
@@ -31,13 +32,13 @@ export async function ensureHooksConfirmed(
     try {
       if (scriptKind === 'issueCommand') {
         // Local overrides are user-owned; only shared orca.yaml commands need repo trust.
-        const result = await window.api.hooks.readIssueCommand({ repoId })
+        const result = await readRuntimeIssueCommand(state.settings, repoId)
         if (result.source !== 'shared') {
           return 'run'
         }
         scriptContent = (result.sharedContent ?? '').trim()
       } else {
-        const result = await window.api.hooks.check({ repoId })
+        const result = await checkRuntimeHooks(state.settings, repoId)
         const yamlHooks = (result.hooks as OrcaHooks | null) ?? null
         scriptContent = (yamlHooks?.scripts?.[scriptKind] ?? '').trim()
       }
diff --git a/src/renderer/src/lib/http-link-routing.test.ts b/src/renderer/src/lib/http-link-routing.test.ts
index f62994e49ad..bdafd7e9981 100644
--- a/src/renderer/src/lib/http-link-routing.test.ts
+++ b/src/renderer/src/lib/http-link-routing.test.ts
@@ -6,7 +6,9 @@ const setActiveWorktreeMock = vi.fn()
 const createBrowserTabMock = vi.fn()
 
 const storeState = {
-  settings: undefined as { openLinksInApp?: boolean } | undefined,
+  settings: undefined as
+    | { openLinksInApp?: boolean; activeRuntimeEnvironmentId?: string | null }
+    | undefined,
   setActiveWorktree: setActiveWorktreeMock,
   createBrowserTab: createBrowserTabMock
 }
@@ -59,6 +61,16 @@ describe('openHttpLink', () => {
     expect(createBrowserTabMock).not.toHaveBeenCalled()
   })
 
+  it('routes to the system browser when a remote runtime environment is active', () => {
+    storeState.settings = { openLinksInApp: true, activeRuntimeEnvironmentId: 'env-1' }
+
+    openHttpLink('https://example.com/', { worktreeId: 'wt-1' })
+
+    expect(openUrlMock).toHaveBeenCalledWith('https://example.com/')
+    expect(createBrowserTabMock).not.toHaveBeenCalled()
+    expect(setActiveWorktreeMock).not.toHaveBeenCalled()
+  })
+
   it('routes to the system browser when no worktree id is provided', () => {
     storeState.settings = { openLinksInApp: true }
 
diff --git a/src/renderer/src/lib/http-link-routing.ts b/src/renderer/src/lib/http-link-routing.ts
index 541106718d3..5204be0daec 100644
--- a/src/renderer/src/lib/http-link-routing.ts
+++ b/src/renderer/src/lib/http-link-routing.ts
@@ -4,7 +4,7 @@ export type OpenHttpLinkOptions = {
 }
 
 type StoreAccessor = () => {
-  settings?: { openLinksInApp?: boolean } | null
+  settings?: { openLinksInApp?: boolean; activeRuntimeEnvironmentId?: string | null } | null
   setActiveWorktree: (worktreeId: string) => void
   createBrowserTab: (worktreeId: string, url: string, opts: { activate: boolean }) => unknown
 }
@@ -28,8 +28,12 @@ export function registerHttpLinkStoreAccessor(fn: StoreAccessor): void {
 export function openHttpLink(url: string, opts: OpenHttpLinkOptions = {}): void {
   const { worktreeId, forceSystemBrowser } = opts
   const state = storeAccessor?.()
+  const remoteRuntimeActive = Boolean(state?.settings?.activeRuntimeEnvironmentId?.trim())
   const routeToOrca =
-    !forceSystemBrowser && Boolean(worktreeId) && state?.settings?.openLinksInApp !== false
+    !remoteRuntimeActive &&
+    !forceSystemBrowser &&
+    Boolean(worktreeId) &&
+    state?.settings?.openLinksInApp !== false
 
   if (routeToOrca && worktreeId && state) {
     // Why: http clicks from inside a worktree should not push a worktree-switch
diff --git a/src/renderer/src/lib/launch-agent-background-session.test.ts b/src/renderer/src/lib/launch-agent-background-session.test.ts
index aacf55857db..d8a13516bb2 100644
--- a/src/renderer/src/lib/launch-agent-background-session.test.ts
+++ b/src/renderer/src/lib/launch-agent-background-session.test.ts
@@ -1,6 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '@/runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '@/runtime/runtime-rpc-client'
 
 const mockSpawn = vi.fn()
+const mockRuntimeEnvironmentCall = vi.fn()
+const mockRuntimeEnvironmentTransportCall = vi.fn()
+const mockRuntimeEnvironmentSubscribe = vi.fn()
 const mockCreateTab = vi.fn()
 const mockSetTabCustomTitle = vi.fn()
 const mockUpdateTabPtyId = vi.fn()
@@ -11,7 +19,7 @@ const mockSubscribeToPtyExit = vi.fn()
 const mockPasteDraftWhenAgentReady = vi.fn()
 
 const state = {
-  settings: { agentCmdOverrides: {} },
+  settings: { agentCmdOverrides: {}, activeRuntimeEnvironmentId: null as string | null },
   repos: [{ id: 'repo-1', connectionId: null }],
   allWorktrees: vi.fn(() => [
     { id: 'wt-1', repoId: 'repo-1', path: '/repo/worktree', displayName: 'main' }
@@ -47,15 +55,39 @@ vi.mock('@/components/terminal-pane/pty-dispatcher', () => ({
 
 describe('launchAgentBackgroundSession', () => {
   beforeEach(() => {
+    clearRuntimeCompatibilityCacheForTests()
     vi.clearAllMocks()
+    mockRuntimeEnvironmentTransportCall.mockImplementation(
+      (args: RuntimeEnvironmentCallRequest) => {
+        return (
+          createCompatibleRuntimeStatusResponseIfNeeded(args) ?? mockRuntimeEnvironmentCall(args)
+        )
+      }
+    )
+    state.settings = { agentCmdOverrides: {}, activeRuntimeEnvironmentId: null }
     mockCreateTab.mockReturnValue({ id: 'tab-1', title: 'Terminal 1' })
     mockSpawn.mockResolvedValue({ id: 'pty-1' })
+    mockRuntimeEnvironmentCall.mockResolvedValue({
+      ok: true,
+      result: { terminal: { handle: 'terminal-1', worktreeId: 'wt-1', title: null } }
+    })
+    mockRuntimeEnvironmentSubscribe.mockImplementation(async (_args, callbacks) => {
+      queueMicrotask(() => callbacks.onResponse({ ok: true, result: { type: 'ready' } }))
+      return { unsubscribe: vi.fn(), sendBinary: vi.fn() }
+    })
     mockSubscribeToPtyData.mockReturnValue(vi.fn())
     mockSubscribeToPtyExit.mockReturnValue(vi.fn())
     vi.stubGlobal('window', {
       api: {
         pty: {
           spawn: mockSpawn
+        },
+        runtime: {
+          call: vi.fn()
+        },
+        runtimeEnvironments: {
+          call: mockRuntimeEnvironmentTransportCall,
+          subscribe: mockRuntimeEnvironmentSubscribe
         }
       }
     })
@@ -175,4 +207,43 @@ describe('launchAgentBackgroundSession', () => {
       })
     )
   })
+
+  it('creates background sessions on the active runtime environment', async () => {
+    state.settings = { agentCmdOverrides: {}, activeRuntimeEnvironmentId: 'env-1' }
+    const { launchAgentBackgroundSession } = await import('./launch-agent-background-session')
+
+    const result = await launchAgentBackgroundSession({
+      agent: 'claude',
+      worktreeId: 'wt-1',
+      prompt: 'run the automation'
+    })
+
+    expect(mockSpawn).not.toHaveBeenCalled()
+    expect(mockRuntimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'terminal.create',
+      params: expect.objectContaining({
+        worktree: 'wt-1',
+        command: "claude 'run the automation'",
+        env: expect.objectContaining({
+          ORCA_PANE_KEY: 'tab-1:1',
+          ORCA_TAB_ID: 'tab-1',
+          ORCA_WORKTREE_ID: 'wt-1'
+        }),
+        focus: false
+      }),
+      timeoutMs: 15_000
+    })
+    expect(mockUpdateTabPtyId).toHaveBeenCalledWith('tab-1', 'remote:env-1@@terminal-1')
+    expect(mockRegisterEagerPtyBuffer).not.toHaveBeenCalled()
+    expect(mockRuntimeEnvironmentSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'terminal.multiplex',
+        params: {}
+      }),
+      expect.any(Object)
+    )
+    expect(result).toMatchObject({ tabId: 'tab-1', ptyId: 'remote:env-1@@terminal-1' })
+  })
 })
diff --git a/src/renderer/src/lib/launch-agent-background-session.ts b/src/renderer/src/lib/launch-agent-background-session.ts
index d0ae944bb18..710a0b5779d 100644
--- a/src/renderer/src/lib/launch-agent-background-session.ts
+++ b/src/renderer/src/lib/launch-agent-background-session.ts
@@ -14,7 +14,14 @@ import {
   subscribeToPtyExit
 } from '@/components/terminal-pane/pty-dispatcher'
 import { createAgentStatusOscProcessor } from '@/components/terminal-pane/agent-status-osc'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import {
+  getRemoteRuntimeTerminalHandle,
+  subscribeToRuntimeTerminalData,
+  toRemoteRuntimePtyId
+} from '@/runtime/runtime-terminal-stream'
 import type { ParsedAgentStatusPayload } from '../../../shared/agent-status-types'
+import type { RuntimeTerminalCreate } from '../../../shared/runtime-types'
 
 export type LaunchAgentBackgroundSessionArgs = {
   agent: TuiAgent
@@ -86,29 +93,49 @@ export async function launchAgentBackgroundSession(
     ORCA_TAB_ID: tab.id,
     ORCA_WORKTREE_ID: worktreeId
   }
-  let result: Awaited<ReturnType<typeof window.api.pty.spawn>>
+  const runtimeTarget = getActiveRuntimeTarget(store.settings)
+  let ptyId: string
   try {
-    result = await window.api.pty.spawn({
-      cols: 120,
-      rows: 40,
-      cwd: worktree.path,
-      command: startupPlan.launchCommand,
-      env: paneEnv,
-      connectionId: repo?.connectionId ?? null,
-      worktreeId,
-      tabId: tab.id,
-      leafId: 'pane:1',
-      telemetry: {
-        agent_kind: tuiAgentToAgentKind(agent),
-        launch_source: launchSource ?? 'unknown',
-        request_kind: 'new'
-      }
-    })
+    if (runtimeTarget.kind === 'environment') {
+      // Why: runtime environments execute on the server; using local pty.spawn
+      // would silently run automation on the client for a remote workspace.
+      const created = await callRuntimeRpc<{ terminal: RuntimeTerminalCreate }>(
+        runtimeTarget,
+        'terminal.create',
+        {
+          worktree: worktreeId,
+          command: startupPlan.launchCommand,
+          env: paneEnv,
+          title,
+          focus: false
+        },
+        { timeoutMs: 15_000 }
+      )
+      ptyId = toRemoteRuntimePtyId(created.terminal.handle, runtimeTarget.environmentId)
+    } else {
+      const result = await window.api.pty.spawn({
+        cols: 120,
+        rows: 40,
+        cwd: worktree.path,
+        command: startupPlan.launchCommand,
+        env: paneEnv,
+        connectionId: repo?.connectionId ?? null,
+        worktreeId,
+        tabId: tab.id,
+        leafId: 'pane:1',
+        telemetry: {
+          agent_kind: tuiAgentToAgentKind(agent),
+          launch_source: launchSource ?? 'unknown',
+          request_kind: 'new'
+        }
+      })
+      ptyId = result.id
+    }
   } catch (error) {
     store.closeTab(tab.id)
     throw error
   }
-  store.updateTabPtyId(tab.id, result.id)
+  store.updateTabPtyId(tab.id, ptyId)
   let exitHandled = false
   let unsubscribeExit = (): void => {}
   let unsubscribeData = (): void => {}
@@ -122,19 +149,41 @@ export async function launchAgentBackgroundSession(
     useAppStore.getState().clearTabPtyId(tab.id, ptyId)
     onExit?.(ptyId, code)
   }
-  registerEagerPtyBuffer(result.id, handleExit)
   const processAgentStatus = createAgentStatusOscProcessor()
-  unsubscribeData = subscribeToPtyData(result.id, (data) => {
+  const handleData = (data: string): void => {
     const processed = processAgentStatus(data)
     for (const payload of processed.payloads) {
       useAppStore.getState().setAgentStatus(paneKey, payload, undefined)
       onAgentStatus?.(payload)
     }
-  })
-  // Why: opening the workspace attaches a real terminal transport and disposes
-  // the eager exit handler. This sidecar keeps automation completion tracking
-  // alive regardless of whether the tab is hidden or mounted.
-  unsubscribeExit = subscribeToPtyExit(result.id, (code) => handleExit(result.id, code))
+  }
+  if (runtimeTarget.kind === 'environment') {
+    unsubscribeData = await subscribeToRuntimeTerminalData(
+      store.settings,
+      ptyId,
+      `desktop:background:${tab.id}`,
+      handleData
+    )
+    const terminal = getRemoteRuntimeTerminalHandle(ptyId)
+    if (!terminal) {
+      throw new Error('Runtime terminal id is invalid.')
+    }
+    void callRuntimeRpc<{ wait: { exitCode?: number | null } }>(
+      runtimeTarget,
+      'terminal.wait',
+      { terminal, for: 'exit' },
+      { timeoutMs: 24 * 60 * 60 * 1000 }
+    )
+      .then((result) => handleExit(ptyId, result.wait.exitCode ?? 0))
+      .catch(() => {})
+  } else {
+    registerEagerPtyBuffer(ptyId, handleExit)
+    unsubscribeData = subscribeToPtyData(ptyId, handleData)
+    // Why: opening the workspace attaches a real terminal transport and disposes
+    // the eager exit handler. This sidecar keeps automation completion tracking
+    // alive regardless of whether the tab is hidden or mounted.
+    unsubscribeExit = subscribeToPtyExit(ptyId, (code) => handleExit(ptyId, code))
+  }
 
   if (pasteDraftAfterLaunch !== null) {
     void pasteDraftWhenAgentReady({
@@ -152,5 +201,5 @@ export async function launchAgentBackgroundSession(
     })
   }
 
-  return { tabId: tab.id, ptyId: result.id, startupPlan }
+  return { tabId: tab.id, ptyId, startupPlan }
 }
diff --git a/src/renderer/src/lib/launch-work-item-direct.ts b/src/renderer/src/lib/launch-work-item-direct.ts
index 6a0ec8b3a5a..a297e508653 100644
--- a/src/renderer/src/lib/launch-work-item-direct.ts
+++ b/src/renderer/src/lib/launch-work-item-direct.ts
@@ -12,6 +12,7 @@ import {
   getWorkspaceSeedName
 } from '@/lib/new-workspace'
 import { ensureHooksConfirmed } from '@/lib/ensure-hooks-confirmed'
+import { checkRuntimeHooks } from '@/runtime/runtime-hooks-client'
 import { track, tuiAgentToAgentKind } from '@/lib/telemetry'
 import type {
   OrcaHooks,
@@ -91,7 +92,7 @@ async function resolveSetupDecision(
 ): Promise<{ kind: 'decided'; decision: SetupDecision } | { kind: 'needs-modal' }> {
   let yamlHooks: OrcaHooks | null = null
   try {
-    const result = await window.api.hooks.check({ repoId })
+    const result = await checkRuntimeHooks(useAppStore.getState().settings, repoId)
     yamlHooks = (result.hooks as OrcaHooks | null) ?? null
   } catch {
     yamlHooks = null
diff --git a/src/renderer/src/lib/local-path-open-guard.test.ts b/src/renderer/src/lib/local-path-open-guard.test.ts
new file mode 100644
index 00000000000..011757af112
--- /dev/null
+++ b/src/renderer/src/lib/local-path-open-guard.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { isLocalPathOpenBlocked } from './local-path-open-guard'
+
+describe('isLocalPathOpenBlocked', () => {
+  it('allows local paths without a runtime or SSH connection', () => {
+    expect(isLocalPathOpenBlocked({ activeRuntimeEnvironmentId: null })).toBe(false)
+  })
+
+  it('blocks paths while a runtime environment is active', () => {
+    expect(isLocalPathOpenBlocked({ activeRuntimeEnvironmentId: 'env-1' })).toBe(true)
+  })
+
+  it('blocks SSH-backed paths', () => {
+    expect(
+      isLocalPathOpenBlocked({ activeRuntimeEnvironmentId: null }, { connectionId: 'ssh-1' })
+    ).toBe(true)
+  })
+})
diff --git a/src/renderer/src/lib/local-path-open-guard.ts b/src/renderer/src/lib/local-path-open-guard.ts
new file mode 100644
index 00000000000..3b34a7747f3
--- /dev/null
+++ b/src/renderer/src/lib/local-path-open-guard.ts
@@ -0,0 +1,15 @@
+import { toast } from 'sonner'
+import type { GlobalSettings } from '../../../shared/types'
+
+export function isLocalPathOpenBlocked(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  context?: { connectionId?: string | null }
+): boolean {
+  return Boolean(settings?.activeRuntimeEnvironmentId?.trim() || context?.connectionId?.trim())
+}
+
+export function showLocalPathOpenBlockedToast(): void {
+  // Why: local OS reveal/open actions receive client filesystem paths. Remote
+  // runtime and SSH paths belong to another machine, not this client.
+  toast.error('Opening remote paths in the local OS is not available.')
+}
diff --git a/src/renderer/src/lib/new-workspace.ts b/src/renderer/src/lib/new-workspace.ts
index 9327f240647..d15b28c05d6 100644
--- a/src/renderer/src/lib/new-workspace.ts
+++ b/src/renderer/src/lib/new-workspace.ts
@@ -1,5 +1,9 @@
 import { useAppStore } from '@/store'
 import { pasteDraftWhenAgentReady } from '@/lib/agent-paste-draft'
+import {
+  inspectRuntimeTerminalProcess,
+  sendRuntimePtyInput
+} from '@/runtime/runtime-terminal-inspection'
 import type { AgentStartupPlan } from '@/lib/tui-agent-startup'
 import { isShellProcess } from '@/lib/tui-agent-startup'
 import type { OrcaHooks, TaskViewPresetId } from '../../../shared/types'
@@ -242,7 +246,7 @@ export async function ensureAgentStartupInTerminal(args: {
   // session and submitted. Wait until the agent owns the PTY before writing.
   if (startup.followupPrompt) {
     await waitForAgentForeground(ptyId, startup.expectedProcess)
-    window.api.pty.write(ptyId, `${startup.followupPrompt}\r`)
+    sendRuntimePtyInput(useAppStore.getState().settings, ptyId, `${startup.followupPrompt}\r`)
   }
 
   // Why: draftPrompt uses bracketed-paste so the URL lands atomically in the
@@ -267,7 +271,8 @@ async function waitForAgentForeground(ptyId: string, expectedProcess: string): P
       await new Promise((resolve) => window.setTimeout(resolve, 150))
     }
     try {
-      const foreground = (await window.api.pty.getForegroundProcess(ptyId))?.toLowerCase() ?? ''
+      const process = await inspectRuntimeTerminalProcess(useAppStore.getState().settings, ptyId)
+      const foreground = process.foregroundProcess?.toLowerCase() ?? ''
       const owns =
         foreground === expectedProcess ||
         foreground.startsWith(`${expectedProcess}.`) ||
@@ -276,8 +281,7 @@ async function waitForAgentForeground(ptyId: string, expectedProcess: string): P
         return
       }
       if (attempt >= 4 && !isShellProcess(foreground)) {
-        const hasChildProcesses = await window.api.pty.hasChildProcesses(ptyId)
-        if (hasChildProcesses) {
+        if (process.hasChildProcesses) {
           return
         }
       }
diff --git a/src/renderer/src/lib/open-project-notes-tab.ts b/src/renderer/src/lib/open-project-notes-tab.ts
index f072ecd22ea..cda85c7e695 100644
--- a/src/renderer/src/lib/open-project-notes-tab.ts
+++ b/src/renderer/src/lib/open-project-notes-tab.ts
@@ -1,5 +1,6 @@
 import { useAppStore } from '@/store'
 import { NOTES_ACTIVE_CHANGED_EVENT } from '@/lib/notes-events'
+import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
 
 export function getProjectNotesEntityId(projectId: string, noteId?: string): string {
   if (noteId) {
@@ -27,15 +28,16 @@ export async function openProjectNotesTab(worktreeId: string, noteId?: string):
     .find((candidate) => candidate.id === worktreeId)
   const repo = state.repos.find((candidate) => candidate.id === worktree?.repoId)
   const projectId = repo?.id ?? worktree?.repoId ?? null
+  const settings = state.settings
 
   if (noteId && projectId) {
-    await window.api.notes.link({ projectId, worktreeId, note: noteId, kind: 'active' })
+    await linkRuntimeProjectNote(settings, { projectId, worktreeId, note: noteId, kind: 'active' })
   }
 
   let label = 'Project Notes'
   if (noteId && projectId) {
     try {
-      const result = await window.api.notes.show({ projectId, worktreeId, note: noteId })
+      const result = await showRuntimeProjectNote(settings, { projectId, worktreeId, note: noteId })
       label = result.note.title
     } catch {
       label = 'Project Notes'
diff --git a/src/renderer/src/lib/rename-file.ts b/src/renderer/src/lib/rename-file.ts
index eef158e65e1..cf666e9d95a 100644
--- a/src/renderer/src/lib/rename-file.ts
+++ b/src/renderer/src/lib/rename-file.ts
@@ -5,6 +5,7 @@ import { basename, dirname, joinPath } from '@/lib/path'
 import { getConnectionId } from '@/lib/connection-context'
 import { requestEditorSaveQuiesce } from '@/components/editor/editor-autosave'
 import { commitFileExplorerOp } from '@/components/right-sidebar/fileExplorerUndoRedo'
+import { renameRuntimePath } from '@/runtime/runtime-file-client'
 
 /**
  * Electron's ipcRenderer.invoke wraps errors as:
@@ -124,20 +125,26 @@ export async function renameFileOnDisk(args: RenameFileArgs): Promise<void> {
       file.filePath.startsWith(`${oldPath}\\`)
   )
   await Promise.all(filesToQuiesce.map((file) => requestEditorSaveQuiesce({ fileId: file.id })))
+  const fileContext = {
+    settings: state.settings,
+    worktreeId,
+    worktreePath,
+    connectionId
+  }
 
   try {
-    await window.api.fs.rename({ oldPath, newPath, connectionId })
+    await renameRuntimePath(fileContext, oldPath, newPath)
     remapOpenTabsForRenamedPath(oldPath, newPath, worktreePath)
     commitFileExplorerOp({
       undo: async () => {
-        await window.api.fs.rename({ oldPath: newPath, newPath: oldPath, connectionId })
+        await renameRuntimePath(fileContext, newPath, oldPath)
         if (refreshDir) {
           await refreshDir(parentDir)
         }
         remapOpenTabsForRenamedPath(newPath, oldPath, worktreePath)
       },
       redo: async () => {
-        await window.api.fs.rename({ oldPath, newPath, connectionId })
+        await renameRuntimePath(fileContext, oldPath, newPath)
         if (refreshDir) {
           await refreshDir(parentDir)
         }
diff --git a/src/renderer/src/lib/repo-slug-index.ts b/src/renderer/src/lib/repo-slug-index.ts
index 6c14526b093..09028c370b2 100644
--- a/src/renderer/src/lib/repo-slug-index.ts
+++ b/src/renderer/src/lib/repo-slug-index.ts
@@ -16,6 +16,8 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { useAppStore } from '@/store'
 import type { Repo } from '../../../shared/types'
+import type { GlobalSettings } from '../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 /** Lowercased `owner/repo` → Repo. Case folded because GitHub treats slugs
  *  case-insensitively but displays the canonical casing; the lookup side
@@ -23,17 +25,29 @@ import type { Repo } from '../../../shared/types'
  *  canonical casing depending on when the project item was indexed. */
 type SlugIndex = Map<string, Repo>
 
-/** Module-scope cache keyed by repo.id. A Repo that has already failed
+/** Module-scope cache keyed by runtime scope + repo.id. A Repo that has already failed
  *  resolution is not retried on re-mount; the value in the map is `null`
  *  to record the negative result so we don't keep poking `git remote` for
  *  repos that will never match. */
 const slugByRepoId = new Map<string, string | null>()
 
+function slugCacheKey(
+  repoId: string,
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): string {
+  const target = getActiveRuntimeTarget(settings)
+  return `${target.kind === 'environment' ? `runtime:${target.environmentId}` : 'local'}:${repoId}`
+}
+
 /** Drop a repo's cached slug result. Call when a repo is removed or its
  *  remote URL is known to have changed (e.g. after `git remote set-url`),
  *  so the next index build re-resolves rather than serving a stale entry. */
 export function clearRepoSlugCacheEntry(repoId: string): void {
-  slugByRepoId.delete(repoId)
+  for (const key of slugByRepoId.keys()) {
+    if (key.endsWith(`:${repoId}`)) {
+      slugByRepoId.delete(key)
+    }
+  }
 }
 
 /** Clear the entire slug cache. Useful for tests or full repo-list resets. */
@@ -41,41 +55,57 @@ export function clearRepoSlugCache(): void {
   slugByRepoId.clear()
 }
 
-async function resolveRepoSlug(repo: Repo): Promise<string | null> {
-  if (slugByRepoId.has(repo.id)) {
-    return slugByRepoId.get(repo.id) ?? null
+async function resolveRepoSlug(
+  repo: Repo,
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): Promise<string | null> {
+  const cacheKey = slugCacheKey(repo.id, settings)
+  if (slugByRepoId.has(cacheKey)) {
+    return slugByRepoId.get(cacheKey) ?? null
   }
   try {
-    const result = await window.api.gh.repoSlug({ repoPath: repo.path })
+    const target = getActiveRuntimeTarget(settings)
+    const result =
+      target.kind === 'environment'
+        ? await callRuntimeRpc<{ owner: string; repo: string } | null>(
+            target,
+            'github.repoSlug',
+            { repo: repo.id },
+            { timeoutMs: 30_000 }
+          )
+        : await window.api.gh.repoSlug({ repoPath: repo.path })
     if (!result) {
-      slugByRepoId.set(repo.id, null)
+      slugByRepoId.set(cacheKey, null)
       return null
     }
     const slug = `${result.owner}/${result.repo}`.toLowerCase()
-    slugByRepoId.set(repo.id, slug)
+    slugByRepoId.set(cacheKey, slug)
     return slug
   } catch {
     // Why: treat any IPC failure as "not resolvable" rather than propagating —
     // design doc §Row actions: "If gh:repoSlug fails for a repo, exclude it".
-    slugByRepoId.set(repo.id, null)
+    slugByRepoId.set(cacheKey, null)
     return null
   }
 }
 
-async function buildIndex(repos: Repo[]): Promise<SlugIndex> {
+async function buildIndex(
+  repos: Repo[],
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): Promise<SlugIndex> {
   // Why: evict cached entries for repos that no longer exist in state so
   // the cache cannot grow unbounded across long sessions where users add
   // and remove repos. Without this, every removed repo's id (and its
   // negative-cached null) lingers forever.
-  const liveIds = new Set(repos.map((r) => r.id))
-  for (const id of slugByRepoId.keys()) {
-    if (!liveIds.has(id)) {
-      slugByRepoId.delete(id)
+  const liveKeys = new Set(repos.map((r) => slugCacheKey(r.id, settings)))
+  for (const key of slugByRepoId.keys()) {
+    if (!liveKeys.has(key)) {
+      slugByRepoId.delete(key)
     }
   }
   const next: SlugIndex = new Map()
   const results = await Promise.all(
-    repos.map(async (r) => ({ repo: r, slug: await resolveRepoSlug(r) }))
+    repos.map(async (r) => ({ repo: r, slug: await resolveRepoSlug(r, settings) }))
   )
   for (const { repo, slug } of results) {
     if (slug) {
@@ -90,6 +120,7 @@ async function buildIndex(repos: Repo[]): Promise<SlugIndex> {
  *  treat it as referentially equal inside a single render cycle. */
 export function useRepoSlugIndex(): (slug: string | null | undefined) => Repo | null {
   const repos = useAppStore((s) => s.repos)
+  const settings = useAppStore((s) => s.settings)
   const [index, setIndex] = useState<SlugIndex>(() => new Map())
   // Why: track the current repos snapshot so the effect can ignore stale
   // resolutions when repos change mid-flight.
@@ -97,13 +128,13 @@ export function useRepoSlugIndex(): (slug: string | null | undefined) => Repo |
 
   useEffect(() => {
     const gen = ++generationRef.current
-    void buildIndex(repos).then((next) => {
+    void buildIndex(repos, settings).then((next) => {
       if (gen !== generationRef.current) {
         return
       }
       setIndex(next)
     })
-  }, [repos])
+  }, [repos, settings])
 
   return useMemo(
     () =>
diff --git a/src/renderer/src/lib/workspace-session.ts b/src/renderer/src/lib/workspace-session.ts
index bc563959b0b..8b31ebaccce 100644
--- a/src/renderer/src/lib/workspace-session.ts
+++ b/src/renderer/src/lib/workspace-session.ts
@@ -111,7 +111,8 @@ export function buildEditorSessionData(
       relativePath: f.relativePath,
       worktreeId: f.worktreeId,
       language: f.language,
-      isPreview: f.isPreview || undefined
+      isPreview: f.isPreview || undefined,
+      runtimeEnvironmentId: f.runtimeEnvironmentId
     })
     const ids =
       editFileIdsByWorktree[f.worktreeId] ?? (editFileIdsByWorktree[f.worktreeId] = new Set())
diff --git a/src/renderer/src/runtime/mobile-markdown-bridge.ts b/src/renderer/src/runtime/mobile-markdown-bridge.ts
index 58d11e303c5..7158c64ecc0 100644
--- a/src/renderer/src/runtime/mobile-markdown-bridge.ts
+++ b/src/renderer/src/runtime/mobile-markdown-bridge.ts
@@ -9,6 +9,8 @@ import { flushPendingEditorChange } from '@/components/editor/editor-pending-flu
 import { getConnectionId } from '@/lib/connection-context'
 import { useAppStore } from '@/store'
 import type { OpenFile } from '@/store/slices/editor'
+import { readRuntimeFileContent } from './runtime-file-client'
+import { settingsForRuntimeOwner } from './runtime-rpc-client'
 import {
   hashMarkdownContent,
   MOBILE_MARKDOWN_EDIT_MAX_BYTES,
@@ -238,8 +240,12 @@ async function readCurrentContent(
 
 async function readFileContent(file: OpenFile): Promise<string> {
   const connectionId = getConnectionId(file.worktreeId) ?? undefined
-  const result = (await window.api.fs.readFile({
+  const state = useAppStore.getState()
+  const result = (await readRuntimeFileContent({
+    settings: settingsForRuntimeOwner(state.settings, file.runtimeEnvironmentId),
     filePath: file.filePath,
+    relativePath: file.relativePath,
+    worktreeId: file.worktreeId,
     connectionId
   })) as FileContent
   if (result.isBinary) {
diff --git a/src/renderer/src/runtime/remote-file-client.ts b/src/renderer/src/runtime/remote-file-client.ts
new file mode 100644
index 00000000000..9958ac957d7
--- /dev/null
+++ b/src/renderer/src/runtime/remote-file-client.ts
@@ -0,0 +1,22 @@
+import type { GlobalSettings } from '../../../shared/types'
+import { readRuntimeFileContent, type RuntimeReadableFileContent } from './runtime-file-client'
+
+export type RemoteReadableFile = {
+  worktreeId: string
+  relativePath: string
+  filePath?: string
+}
+
+export type RemoteFileContent = RuntimeReadableFileContent
+
+export async function readFileFromActiveRuntime(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  file: RemoteReadableFile
+): Promise<RemoteFileContent> {
+  return readRuntimeFileContent({
+    settings,
+    filePath: file.filePath ?? file.relativePath,
+    relativePath: file.relativePath,
+    worktreeId: file.worktreeId
+  })
+}
diff --git a/src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts b/src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
new file mode 100644
index 00000000000..2bf32cccbd9
--- /dev/null
+++ b/src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
@@ -0,0 +1,379 @@
+/* eslint-disable max-lines -- Why: the remote terminal multiplexer owns one bridged subscription, stream lifecycle, binary frame parsing, and remote lock events as a single transport contract. */
+import type { RuntimeRpcResponse } from '../../../shared/runtime-rpc-envelope'
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamText,
+  encodeTerminalStreamFrame,
+  encodeTerminalStreamJson,
+  encodeTerminalStreamText
+} from '../../../shared/terminal-stream-protocol'
+import { unwrapRuntimeRpcResult } from './runtime-rpc-client'
+
+type RuntimeEnvironmentSubscriptionHandle = {
+  unsubscribe: () => void
+  sendBinary: (bytes: Uint8Array<ArrayBufferLike>) => void
+}
+
+type TerminalMultiplexEvent =
+  | { type: 'ready' }
+  | { type: 'subscribed'; streamId: number }
+  | { type: 'end'; streamId: number }
+  | { type: 'error'; streamId: number; message?: string }
+  | {
+      type: 'fit-override-changed'
+      streamId: number
+      mode: 'mobile-fit' | 'desktop-fit'
+      cols: number
+      rows: number
+    }
+  | {
+      type: 'driver-changed'
+      streamId: number
+      driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
+    }
+  | { type: string; streamId?: number; [key: string]: unknown }
+
+export type RemoteRuntimeMultiplexedTerminalCallbacks = {
+  onData: (data: string) => void
+  onSnapshot: (data: string) => void
+  onSubscribed?: () => void
+  onEnd?: () => void
+  onError?: (message: string) => void
+  onFitOverrideChanged?: (event: {
+    mode: 'mobile-fit' | 'desktop-fit'
+    cols: number
+    rows: number
+  }) => void
+  onDriverChanged?: (
+    driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
+  ) => void
+  onTransportClose?: () => void
+}
+
+export type RemoteRuntimeMultiplexedTerminal = {
+  streamId: number
+  sendInput: (text: string) => boolean
+  resize: (cols: number, rows: number) => boolean
+  close: () => void
+}
+
+type RemoteRuntimeMultiplexedTerminalState = {
+  streamId: number
+  terminal: string
+  callbacks: RemoteRuntimeMultiplexedTerminalCallbacks
+  snapshotChunks: Uint8Array<ArrayBufferLike>[]
+}
+
+const CONTROL_STREAM_ID = 0
+
+class RemoteRuntimeTerminalMultiplexer {
+  private readonly streams = new Map<number, RemoteRuntimeMultiplexedTerminalState>()
+  private subscription: RuntimeEnvironmentSubscriptionHandle | null = null
+  private connectPromise: Promise<void> | null = null
+  private readyResolver: (() => void) | null = null
+  private readyRejecter: ((error: Error) => void) | null = null
+  private ready = false
+  private nextStreamId = 1
+
+  constructor(private readonly environmentId: string) {}
+
+  async subscribeTerminal(args: {
+    terminal: string
+    client: { id: string; type: 'desktop' | 'mobile' }
+    viewport?: { cols: number; rows: number }
+    callbacks: RemoteRuntimeMultiplexedTerminalCallbacks
+  }): Promise<RemoteRuntimeMultiplexedTerminal> {
+    const streamId = this.allocateStreamId()
+    const state: RemoteRuntimeMultiplexedTerminalState = {
+      streamId,
+      terminal: args.terminal,
+      callbacks: args.callbacks,
+      snapshotChunks: []
+    }
+    this.streams.set(streamId, state)
+
+    const stream: RemoteRuntimeMultiplexedTerminal = {
+      streamId,
+      sendInput: (text) =>
+        this.sendFrame(streamId, TerminalStreamOpcode.Input, encodeTerminalStreamText(text)),
+      resize: (cols, rows) =>
+        this.sendFrame(
+          streamId,
+          TerminalStreamOpcode.Resize,
+          encodeTerminalStreamJson({ cols, rows })
+        ),
+      close: () => {
+        if (this.streams.get(streamId) === state) {
+          this.sendFrame(streamId, TerminalStreamOpcode.Unsubscribe)
+          this.streams.delete(streamId)
+          this.closeIfIdle()
+        }
+      }
+    }
+
+    try {
+      await this.ensureConnected()
+      if (this.streams.get(streamId) !== state) {
+        return stream
+      }
+      const sent = this.sendFrame(
+        CONTROL_STREAM_ID,
+        TerminalStreamOpcode.Subscribe,
+        encodeTerminalStreamJson({
+          streamId,
+          terminal: args.terminal,
+          client: args.client,
+          viewport: args.viewport
+        })
+      )
+      if (!sent) {
+        throw new Error('Remote terminal stream is not connected.')
+      }
+    } catch (error) {
+      const terminalError = error instanceof Error ? error : new Error(String(error))
+      if (this.streams.get(streamId) === state) {
+        this.streams.delete(streamId)
+        this.closeIfIdle()
+      }
+      throw terminalError
+    }
+
+    return stream
+  }
+
+  private allocateStreamId(): number {
+    const start = this.nextStreamId
+    do {
+      const candidate = this.nextStreamId
+      this.nextStreamId = this.nextStreamId >= 0x7fffffff ? 1 : this.nextStreamId + 1
+      if (!this.streams.has(candidate)) {
+        return candidate
+      }
+    } while (this.nextStreamId !== start)
+    throw new Error('No remote terminal stream ids available.')
+  }
+
+  private ensureConnected(): Promise<void> {
+    if (this.ready && this.subscription) {
+      return Promise.resolve()
+    }
+    if (this.connectPromise) {
+      return this.connectPromise
+    }
+    this.connectPromise = new Promise<void>((resolve, reject) => {
+      this.readyResolver = resolve
+      this.readyRejecter = reject
+      void window.api.runtimeEnvironments
+        .subscribe(
+          {
+            selector: this.environmentId,
+            method: 'terminal.multiplex',
+            params: {},
+            timeoutMs: 15_000
+          },
+          {
+            onResponse: (response) => this.handleResponse(response),
+            onBinary: (bytes) => this.handleBinary(bytes),
+            onError: (error) => this.failConnection(new Error(error.message)),
+            onClose: () => this.handleClose('Remote Orca runtime closed the connection.')
+          }
+        )
+        .then((subscription) => {
+          this.subscription = subscription
+          this.resolveReadyIfConnected()
+        })
+        .catch((error) => {
+          this.connectPromise = null
+          this.readyResolver = null
+          this.readyRejecter = null
+          reject(error instanceof Error ? error : new Error(String(error)))
+        })
+    })
+    return this.connectPromise
+  }
+
+  private handleResponse(response: RuntimeRpcResponse<unknown>): void {
+    let event: TerminalMultiplexEvent
+    try {
+      event = unwrapRuntimeRpcResult(response) as TerminalMultiplexEvent
+    } catch (error) {
+      this.failConnection(error instanceof Error ? error : new Error(String(error)))
+      return
+    }
+
+    if (event.type === 'ready') {
+      this.ready = true
+      this.resolveReadyIfConnected()
+      return
+    }
+
+    if (!('streamId' in event) || typeof event.streamId !== 'number') {
+      return
+    }
+    const stream = this.streams.get(event.streamId)
+    if (!stream) {
+      return
+    }
+    if (event.type === 'end') {
+      this.streams.delete(event.streamId)
+      stream.callbacks.onEnd?.()
+      this.closeIfIdle()
+    } else if (event.type === 'error') {
+      stream.callbacks.onError?.(
+        typeof event.message === 'string' ? event.message : 'Remote terminal stream failed.'
+      )
+    } else if (event.type === 'fit-override-changed') {
+      if (
+        (event.mode !== 'mobile-fit' && event.mode !== 'desktop-fit') ||
+        typeof event.cols !== 'number' ||
+        typeof event.rows !== 'number'
+      ) {
+        return
+      }
+      stream.callbacks.onFitOverrideChanged?.({
+        mode: event.mode,
+        cols: event.cols,
+        rows: event.rows
+      })
+    } else if (event.type === 'driver-changed') {
+      if (!isTerminalDriverState(event.driver)) {
+        return
+      }
+      stream.callbacks.onDriverChanged?.(event.driver)
+    }
+  }
+
+  private handleBinary(bytes: Uint8Array<ArrayBufferLike>): void {
+    const frame = decodeTerminalStreamFrame(bytes)
+    if (!frame) {
+      return
+    }
+    const stream = this.streams.get(frame.streamId)
+    if (!stream) {
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.Output) {
+      stream.callbacks.onData(decodeTerminalStreamText(frame.payload))
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.SnapshotStart) {
+      stream.snapshotChunks = []
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.SnapshotChunk) {
+      stream.snapshotChunks.push(frame.payload)
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.SnapshotEnd) {
+      stream.callbacks.onSnapshot(decodeTerminalStreamText(concatBytes(stream.snapshotChunks)))
+      stream.snapshotChunks = []
+      stream.callbacks.onSubscribed?.()
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.Error) {
+      stream.callbacks.onError?.(decodeTerminalStreamText(frame.payload))
+    }
+  }
+
+  private sendFrame(
+    streamId: number,
+    opcode: TerminalStreamOpcode,
+    payload: Uint8Array<ArrayBufferLike> = new Uint8Array()
+  ): boolean {
+    if (!this.ready || !this.subscription) {
+      return false
+    }
+    this.subscription.sendBinary(encodeTerminalStreamFrame({ opcode, streamId, seq: 0, payload }))
+    return true
+  }
+
+  private resolveReadyIfConnected(): void {
+    if (!this.ready || !this.subscription) {
+      return
+    }
+    this.readyResolver?.()
+    this.readyResolver = null
+    this.readyRejecter = null
+  }
+
+  private failConnection(error: Error): void {
+    this.readyRejecter?.(error)
+    this.readyResolver = null
+    this.readyRejecter = null
+    for (const stream of this.streams.values()) {
+      stream.callbacks.onError?.(error.message)
+    }
+    this.subscription?.unsubscribe()
+    this.handleClose()
+  }
+
+  private handleClose(message?: string): void {
+    const streams = Array.from(this.streams.values())
+    this.ready = false
+    this.connectPromise = null
+    this.readyRejecter?.(new Error(message ?? 'Remote runtime connection closed.'))
+    this.readyResolver = null
+    this.readyRejecter = null
+    this.subscription = null
+    this.streams.clear()
+    for (const stream of streams) {
+      stream.callbacks.onTransportClose?.()
+      if (message) {
+        stream.callbacks.onError?.(message)
+      }
+    }
+  }
+
+  private closeIfIdle(): void {
+    if (this.streams.size > 0) {
+      return
+    }
+    this.subscription?.unsubscribe()
+    this.subscription = null
+    this.connectPromise = null
+    this.ready = false
+  }
+}
+
+const multiplexers = new Map<string, RemoteRuntimeTerminalMultiplexer>()
+
+export function getRemoteRuntimeTerminalMultiplexer(
+  environmentId: string
+): RemoteRuntimeTerminalMultiplexer {
+  let multiplexer = multiplexers.get(environmentId)
+  if (!multiplexer) {
+    multiplexer = new RemoteRuntimeTerminalMultiplexer(environmentId)
+    multiplexers.set(environmentId, multiplexer)
+  }
+  return multiplexer
+}
+
+export function resetRemoteRuntimeTerminalMultiplexersForTests(): void {
+  multiplexers.clear()
+}
+
+function concatBytes(chunks: Uint8Array<ArrayBufferLike>[]): Uint8Array<ArrayBufferLike> {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0)
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+function isTerminalDriverState(
+  value: unknown
+): value is { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string } {
+  if (!value || typeof value !== 'object' || !('kind' in value)) {
+    return false
+  }
+  const driver = value as { kind?: unknown; clientId?: unknown }
+  return (
+    driver.kind === 'idle' ||
+    driver.kind === 'desktop' ||
+    (driver.kind === 'mobile' && typeof driver.clientId === 'string')
+  )
+}
diff --git a/src/renderer/src/runtime/runtime-compatibility-test-fixture.ts b/src/renderer/src/runtime/runtime-compatibility-test-fixture.ts
new file mode 100644
index 00000000000..eb1bff0c680
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-compatibility-test-fixture.ts
@@ -0,0 +1,37 @@
+import type { RuntimeRpcResponse } from '../../../shared/runtime-rpc-envelope'
+import type { RuntimeStatus } from '../../../shared/runtime-types'
+import {
+  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from '../../../shared/protocol-version'
+
+export type RuntimeEnvironmentCallRequest = {
+  method: string
+}
+
+export function createCompatibleRuntimeStatusResponse(
+  runtimeId = 'remote-runtime'
+): RuntimeRpcResponse<RuntimeStatus> {
+  return {
+    id: 'status',
+    ok: true,
+    result: {
+      runtimeId,
+      rendererGraphEpoch: 0,
+      graphStatus: 'ready',
+      authoritativeWindowId: null,
+      liveTabCount: 0,
+      liveLeafCount: 0,
+      runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleRuntimeClientVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
+    },
+    _meta: { runtimeId }
+  }
+}
+
+export function createCompatibleRuntimeStatusResponseIfNeeded(
+  args: RuntimeEnvironmentCallRequest,
+  runtimeId?: string
+): RuntimeRpcResponse<RuntimeStatus> | null {
+  return args.method === 'status.get' ? createCompatibleRuntimeStatusResponse(runtimeId) : null
+}
diff --git a/src/renderer/src/runtime/runtime-file-client.test.ts b/src/renderer/src/runtime/runtime-file-client.test.ts
new file mode 100644
index 00000000000..582d4af028b
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-file-client.test.ts
@@ -0,0 +1,1186 @@
+/* eslint-disable max-lines -- Why: the runtime file client mirrors the file
+preload API plus remote fallbacks; keeping route coverage together makes local
+versus environment behavior easy to audit. */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  copyRuntimePath,
+  createRuntimePath,
+  deleteRuntimePath,
+  getRuntimeFileReadScope,
+  importExternalPathsToRuntime,
+  listRuntimeFiles,
+  listRuntimeMarkdownDocuments,
+  readRuntimeDirectory,
+  readRuntimeFileContent,
+  readRuntimeFilePreview,
+  renameRuntimePath,
+  searchRuntimeFiles,
+  statRuntimePath,
+  subscribeRuntimeFileChanges,
+  type RuntimeReadableFileContent
+} from './runtime-file-client'
+import { clearRuntimeCompatibilityCacheForTests } from './runtime-rpc-client'
+import {
+  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from '../../../shared/protocol-version'
+
+const fsReadFile = vi.fn()
+const fsOnChanged = vi.fn()
+const fsCopy = vi.fn()
+const fsCreateDir = vi.fn()
+const fsCreateFile = vi.fn()
+const fsRename = vi.fn()
+const fsDeletePath = vi.fn()
+const fsStat = vi.fn()
+const fsImportExternalPaths = vi.fn()
+const fsStageExternalPathsForRuntimeUpload = vi.fn()
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+const runtimeEnvironmentSubscribe = vi.fn()
+const runtimeCall = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  fsReadFile.mockReset()
+  fsOnChanged.mockReset()
+  fsCopy.mockReset()
+  fsCreateDir.mockReset()
+  fsCreateFile.mockReset()
+  fsRename.mockReset()
+  fsDeletePath.mockReset()
+  fsStat.mockReset()
+  fsImportExternalPaths.mockReset()
+  fsStageExternalPathsForRuntimeUpload.mockReset()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  runtimeEnvironmentSubscribe.mockReset()
+  runtimeCall.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: { method: string }) => {
+    if (args.method === 'status.get') {
+      return Promise.resolve({
+        id: 'status',
+        ok: true,
+        result: {
+          runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+          minCompatibleRuntimeClientVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
+        },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+    }
+    return runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      fs: {
+        readFile: fsReadFile,
+        onFsChanged: fsOnChanged,
+        copy: fsCopy,
+        createDir: fsCreateDir,
+        createFile: fsCreateFile,
+        rename: fsRename,
+        deletePath: fsDeletePath,
+        stat: fsStat,
+        importExternalPaths: fsImportExternalPaths,
+        stageExternalPathsForRuntimeUpload: fsStageExternalPathsForRuntimeUpload
+      },
+      runtime: { call: runtimeCall },
+      runtimeEnvironments: {
+        call: runtimeEnvironmentTransportCall,
+        subscribe: runtimeEnvironmentSubscribe
+      }
+    }
+  })
+})
+
+describe('runtime file client', () => {
+  it('uses local filesystem reads when no remote runtime is active', async () => {
+    const localResult: RuntimeReadableFileContent = { content: 'hello', isBinary: false }
+    fsReadFile.mockResolvedValue(localResult)
+
+    await expect(
+      readRuntimeFileContent({
+        settings: { activeRuntimeEnvironmentId: null },
+        filePath: '/repo/readme.md',
+        relativePath: 'readme.md',
+        worktreeId: 'wt-1',
+        connectionId: 'ssh-1'
+      })
+    ).resolves.toBe(localResult)
+
+    expect(fsReadFile).toHaveBeenCalledWith({ filePath: '/repo/readme.md', connectionId: 'ssh-1' })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes worktree-relative text reads through the selected runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: {
+        worktree: 'wt-1',
+        relativePath: 'src/index.ts',
+        content: 'export {}\n',
+        truncated: false,
+        byteLength: 10
+      },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await expect(
+      readRuntimeFileContent({
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        filePath: '/remote/repo/src/index.ts',
+        relativePath: 'src/index.ts',
+        worktreeId: 'wt-1'
+      })
+    ).resolves.toEqual({ content: 'export {}\n', isBinary: false })
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.read',
+      params: { worktree: 'wt-1', relativePath: 'src/index.ts' },
+      timeoutMs: 15_000
+    })
+    expect(fsReadFile).not.toHaveBeenCalled()
+  })
+
+  it('keeps external absolute-path files on the local filesystem path', async () => {
+    const localResult: RuntimeReadableFileContent = { content: 'scratch', isBinary: false }
+    fsReadFile.mockResolvedValue(localResult)
+
+    await expect(
+      readRuntimeFileContent({
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        filePath: '/Users/me/scratch.md',
+        relativePath: '/Users/me/scratch.md'
+      })
+    ).resolves.toBe(localResult)
+
+    expect(fsReadFile).toHaveBeenCalledWith({
+      filePath: '/Users/me/scratch.md',
+      connectionId: undefined
+    })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('rejects remote-owned text reads that are not worktree-relative', async () => {
+    await expect(
+      readRuntimeFileContent({
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        filePath: '/tmp/scratch.md',
+        relativePath: '/tmp/scratch.md',
+        worktreeId: 'wt-1'
+      })
+    ).rejects.toThrow('Remote file is outside the owning runtime worktree')
+
+    await expect(
+      readRuntimeFileContent({
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        filePath: '/remote/repo/unknown.md',
+        worktreeId: 'wt-1'
+      })
+    ).rejects.toThrow('Remote file is outside the owning runtime worktree')
+    expect(fsReadFile).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('rejects truncated remote reads instead of returning partial editable content', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: {
+        worktree: 'wt-1',
+        relativePath: 'large.log',
+        content: 'partial',
+        truncated: true,
+        byteLength: 524_288
+      },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await expect(
+      readRuntimeFileContent({
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        filePath: '/remote/repo/large.log',
+        relativePath: 'large.log',
+        worktreeId: 'wt-1'
+      })
+    ).rejects.toThrow('Remote file is too large to open in the editor')
+  })
+
+  it('uses the active runtime id as the dedupe scope', () => {
+    expect(getRuntimeFileReadScope({ activeRuntimeEnvironmentId: 'env-1' }, 'ssh-1')).toBe(
+      'runtime:env-1'
+    )
+    expect(getRuntimeFileReadScope({ activeRuntimeEnvironmentId: null }, 'ssh-1')).toBe('ssh-1')
+  })
+
+  it('routes directory reads through the selected runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: [{ name: 'src', isDirectory: true }],
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await expect(
+      readRuntimeDirectory(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        '/remote/repo/src'
+      )
+    ).resolves.toEqual([{ name: 'src', isDirectory: true }])
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.readDir',
+      params: { worktree: 'wt-1', relativePath: 'src' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes Windows drive paths case-insensitively through the selected runtime', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: [],
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await readRuntimeDirectory(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: 'C:\\Repo'
+      },
+      'c:\\repo\\Src'
+    )
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.readDir',
+      params: { worktree: 'wt-1', relativePath: 'Src' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes forward-slash UNC paths through the selected runtime', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: [],
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await readRuntimeDirectory(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '//Server/Share/Repo'
+      },
+      '//server/share/repo/src'
+    )
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.readDir',
+      params: { worktree: 'wt-1', relativePath: 'src' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes preview reads through the selected runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { content: 'base64', isBinary: true, isImage: true, mimeType: 'image/png' },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await expect(
+      readRuntimeFilePreview(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        '/remote/repo/images/logo.png'
+      )
+    ).resolves.toEqual({
+      content: 'base64',
+      isBinary: true,
+      isImage: true,
+      mimeType: 'image/png'
+    })
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.readPreview',
+      params: { worktree: 'wt-1', relativePath: 'images/logo.png' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('does not fall back to client-local preview reads for remote-owned files outside the worktree', async () => {
+    await expect(
+      readRuntimeFilePreview(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        '/tmp/logo.png'
+      )
+    ).rejects.toThrow('outside the owning runtime worktree')
+
+    expect(fsReadFile).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes root directory reads with an empty relative path', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: [],
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await readRuntimeDirectory(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '/remote/repo'
+      },
+      '/remote/repo'
+    )
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.readDir',
+      params: { worktree: 'wt-1', relativePath: '' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('does not fall back to client-local directory reads for remote-owned paths outside the worktree', async () => {
+    await expect(
+      readRuntimeDirectory(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo',
+          connectionId: 'ssh-1'
+        },
+        '/tmp'
+      )
+    ).rejects.toThrow('outside the owning runtime worktree')
+
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes create, rename, copy, and delete mutations through the selected runtime', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { ok: true },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    const context = {
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      worktreeId: 'wt-1',
+      worktreePath: '/remote/repo'
+    }
+
+    await createRuntimePath(context, '/remote/repo/src/new.ts', 'file')
+    await renameRuntimePath(context, '/remote/repo/src/new.ts', '/remote/repo/src/renamed.ts')
+    await copyRuntimePath(
+      context,
+      '/remote/repo/src/renamed.ts',
+      '/remote/repo/src/renamed copy.ts'
+    )
+    await deleteRuntimePath(context, '/remote/repo/src/renamed.ts', false)
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'files.createFile',
+      params: { worktree: 'wt-1', relativePath: 'src/new.ts' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'files.rename',
+      params: {
+        worktree: 'wt-1',
+        oldRelativePath: 'src/new.ts',
+        newRelativePath: 'src/renamed.ts'
+      },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
+      selector: 'env-1',
+      method: 'files.copy',
+      params: {
+        worktree: 'wt-1',
+        sourceRelativePath: 'src/renamed.ts',
+        destinationRelativePath: 'src/renamed copy.ts'
+      },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(4, {
+      selector: 'env-1',
+      method: 'files.delete',
+      params: { worktree: 'wt-1', relativePath: 'src/renamed.ts', recursive: false },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('does not fall back to client-local mutations for remote-owned paths outside the worktree', async () => {
+    const context = {
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      worktreeId: 'wt-1',
+      worktreePath: '/remote/repo'
+    }
+
+    await expect(createRuntimePath(context, '/tmp/new.ts', 'file')).rejects.toThrow(
+      'outside the owning runtime worktree'
+    )
+    await expect(
+      renameRuntimePath(context, '/remote/repo/src/new.ts', '/tmp/renamed.ts')
+    ).rejects.toThrow('outside the owning runtime worktree')
+    await expect(
+      copyRuntimePath(context, '/remote/repo/src/new.ts', '/tmp/copied.ts')
+    ).rejects.toThrow('outside the owning runtime worktree')
+    await expect(deleteRuntimePath(context, '/tmp/new.ts')).rejects.toThrow(
+      'outside the owning runtime worktree'
+    )
+
+    expect(fsCreateFile).not.toHaveBeenCalled()
+    expect(fsRename).not.toHaveBeenCalled()
+    expect(fsCopy).not.toHaveBeenCalled()
+    expect(fsDeletePath).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('does not fall back to client-local mutations when a remote Windows path escapes the worktree', async () => {
+    const context = {
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      worktreeId: 'wt-1',
+      worktreePath: 'C:\\repo'
+    }
+
+    await expect(createRuntimePath(context, 'D:\\repo\\new.ts', 'file')).rejects.toThrow(
+      'outside the owning runtime worktree'
+    )
+    await expect(
+      createRuntimePath(context, '\\\\server\\share\\repo\\new.ts', 'file')
+    ).rejects.toThrow('outside the owning runtime worktree')
+
+    expect(fsCreateFile).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('keeps copy operations on local filesystem IPC when no runtime is active', async () => {
+    await copyRuntimePath(
+      {
+        settings: { activeRuntimeEnvironmentId: null },
+        worktreeId: 'wt-1',
+        worktreePath: '/repo'
+      },
+      '/repo/a.md',
+      '/repo/a copy.md'
+    )
+
+    expect(fsCopy).toHaveBeenCalledWith({
+      sourcePath: '/repo/a.md',
+      destinationPath: '/repo/a copy.md',
+      connectionId: undefined
+    })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('preserves the SSH connection for copy operations when no runtime is active', async () => {
+    await copyRuntimePath(
+      {
+        settings: { activeRuntimeEnvironmentId: null },
+        worktreeId: 'wt-1',
+        worktreePath: '/repo',
+        connectionId: 'ssh-1'
+      },
+      '/repo/a.md',
+      '/repo/a copy.md'
+    )
+
+    expect(fsCopy).toHaveBeenCalledWith({
+      sourcePath: '/repo/a.md',
+      destinationPath: '/repo/a copy.md',
+      connectionId: 'ssh-1'
+    })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('uploads staged local drops into the selected runtime environment', async () => {
+    fsStageExternalPathsForRuntimeUpload.mockResolvedValue({
+      sources: [
+        {
+          sourcePath: '/Users/me/assets',
+          status: 'staged',
+          name: 'assets',
+          kind: 'directory',
+          entries: [
+            { relativePath: '', kind: 'directory' },
+            { relativePath: 'logo.png', kind: 'file', contentBase64: 'cG5n' }
+          ]
+        }
+      ]
+    })
+    runtimeEnvironmentCall
+      .mockResolvedValueOnce({
+        id: 'stat-destination-miss',
+        ok: false,
+        error: { code: 'not_found', message: 'not found' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'create-destination-dir',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'stat-miss',
+        ok: false,
+        error: { code: 'not_found', message: 'not found' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'create-dir',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'write-file',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'commit-upload',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'delete-temp',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+
+    await expect(
+      importExternalPathsToRuntime(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        ['/Users/me/assets'],
+        '/remote/repo/uploads'
+      )
+    ).resolves.toEqual({
+      results: [
+        {
+          sourcePath: '/Users/me/assets',
+          status: 'imported',
+          destPath: '/remote/repo/uploads/assets',
+          kind: 'directory',
+          renamed: false
+        }
+      ]
+    })
+
+    expect(fsStageExternalPathsForRuntimeUpload).toHaveBeenCalledWith({
+      sourcePaths: ['/Users/me/assets']
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'files.stat',
+      params: { worktree: 'wt-1', relativePath: 'uploads' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'files.createDir',
+      params: { worktree: 'wt-1', relativePath: 'uploads' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
+      selector: 'env-1',
+      method: 'files.stat',
+      params: { worktree: 'wt-1', relativePath: 'uploads/assets' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(4, {
+      selector: 'env-1',
+      method: 'files.createDirNoClobber',
+      params: { worktree: 'wt-1', relativePath: 'uploads/assets' },
+      timeoutMs: 15_000
+    })
+    const smallWriteCall = runtimeEnvironmentCall.mock.calls[4]?.[0] as {
+      params: { relativePath: string }
+    }
+    expect(smallWriteCall.params.relativePath).toMatch(
+      /^uploads\/assets\/\.logo\.png\.orca-upload-/
+    )
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(5, {
+      selector: 'env-1',
+      method: 'files.writeBase64',
+      params: {
+        worktree: 'wt-1',
+        relativePath: smallWriteCall.params.relativePath,
+        contentBase64: 'cG5n'
+      },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(6, {
+      selector: 'env-1',
+      method: 'files.commitUpload',
+      params: {
+        worktree: 'wt-1',
+        tempRelativePath: smallWriteCall.params.relativePath,
+        finalRelativePath: 'uploads/assets/logo.png'
+      },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(7, {
+      selector: 'env-1',
+      method: 'files.delete',
+      params: {
+        worktree: 'wt-1',
+        relativePath: smallWriteCall.params.relativePath,
+        recursive: false
+      },
+      timeoutMs: 15_000
+    })
+    expect(fsImportExternalPaths).not.toHaveBeenCalled()
+  })
+
+  it('chunks large staged runtime uploads below the WebSocket frame budget', async () => {
+    const firstChunk = 'A'.repeat(512 * 1024)
+    const secondChunk = 'BBBBBBBB'
+    fsStageExternalPathsForRuntimeUpload.mockResolvedValue({
+      sources: [
+        {
+          sourcePath: '/Users/me/large.bin',
+          status: 'staged',
+          name: 'large.bin',
+          kind: 'file',
+          entries: [
+            { relativePath: '', kind: 'file', contentBase64: `${firstChunk}${secondChunk}` }
+          ]
+        }
+      ]
+    })
+    runtimeEnvironmentCall
+      .mockResolvedValueOnce({
+        id: 'stat-destination-miss',
+        ok: false,
+        error: { code: 'not_found', message: 'not found' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'create-destination-dir',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'stat-miss',
+        ok: false,
+        error: { code: 'not_found', message: 'not found' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'write-chunk-1',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'write-chunk-2',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'commit-upload',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'delete-temp',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+
+    await expect(
+      importExternalPathsToRuntime(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        ['/Users/me/large.bin'],
+        '/remote/repo/uploads'
+      )
+    ).resolves.toEqual({
+      results: [
+        {
+          sourcePath: '/Users/me/large.bin',
+          status: 'imported',
+          destPath: '/remote/repo/uploads/large.bin',
+          kind: 'file',
+          renamed: false
+        }
+      ]
+    })
+
+    const chunkWriteCall = runtimeEnvironmentCall.mock.calls[3]?.[0] as {
+      params: { relativePath: string }
+    }
+    expect(chunkWriteCall.params.relativePath).toMatch(/^uploads\/\.large\.bin\.orca-upload-/)
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(4, {
+      selector: 'env-1',
+      method: 'files.writeBase64Chunk',
+      params: {
+        worktree: 'wt-1',
+        relativePath: chunkWriteCall.params.relativePath,
+        contentBase64: firstChunk,
+        append: false
+      },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(5, {
+      selector: 'env-1',
+      method: 'files.writeBase64Chunk',
+      params: {
+        worktree: 'wt-1',
+        relativePath: chunkWriteCall.params.relativePath,
+        contentBase64: secondChunk,
+        append: true
+      },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(6, {
+      selector: 'env-1',
+      method: 'files.commitUpload',
+      params: {
+        worktree: 'wt-1',
+        tempRelativePath: chunkWriteCall.params.relativePath,
+        finalRelativePath: 'uploads/large.bin'
+      },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(7, {
+      selector: 'env-1',
+      method: 'files.delete',
+      params: {
+        worktree: 'wt-1',
+        relativePath: chunkWriteCall.params.relativePath,
+        recursive: false
+      },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalledWith(
+      expect.objectContaining({ method: 'files.writeBase64' })
+    )
+  })
+
+  it('cleans up staged runtime upload temp files when a later chunk fails', async () => {
+    const firstChunk = 'A'.repeat(512 * 1024)
+    const secondChunk = 'BBBBBBBB'
+    fsStageExternalPathsForRuntimeUpload.mockResolvedValue({
+      sources: [
+        {
+          sourcePath: '/Users/me/large.bin',
+          status: 'staged',
+          name: 'large.bin',
+          kind: 'file',
+          entries: [
+            { relativePath: '', kind: 'file', contentBase64: `${firstChunk}${secondChunk}` }
+          ]
+        }
+      ]
+    })
+    runtimeEnvironmentCall
+      .mockResolvedValueOnce({
+        id: 'stat-destination-miss',
+        ok: false,
+        error: { code: 'not_found', message: 'not found' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'create-destination-dir',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'stat-miss',
+        ok: false,
+        error: { code: 'not_found', message: 'not found' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'write-chunk-1',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'write-chunk-2',
+        ok: false,
+        error: { code: 'write_failed', message: 'disk full' },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+      .mockResolvedValueOnce({
+        id: 'delete-temp',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+
+    await expect(
+      importExternalPathsToRuntime(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        ['/Users/me/large.bin'],
+        '/remote/repo/uploads'
+      )
+    ).resolves.toMatchObject({
+      results: [{ status: 'failed', reason: 'disk full' }]
+    })
+
+    const chunkCall = runtimeEnvironmentCall.mock.calls[3]?.[0] as
+      | { params: { relativePath: string } }
+      | undefined
+    if (!chunkCall) {
+      throw new Error('missing first chunk call')
+    }
+    const tempRelativePath = chunkCall.params.relativePath
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalledWith(
+      expect.objectContaining({ method: 'files.commitUpload' })
+    )
+    expect(runtimeEnvironmentCall).toHaveBeenLastCalledWith({
+      selector: 'env-1',
+      method: 'files.delete',
+      params: { worktree: 'wt-1', relativePath: tempRelativePath, recursive: false },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('keeps local external imports on filesystem IPC when no runtime is active', async () => {
+    fsImportExternalPaths.mockResolvedValue({
+      results: [
+        {
+          sourcePath: '/Users/me/readme.md',
+          status: 'imported',
+          destPath: '/repo/readme.md',
+          kind: 'file',
+          renamed: false
+        }
+      ]
+    })
+
+    await importExternalPathsToRuntime(
+      {
+        settings: { activeRuntimeEnvironmentId: null },
+        worktreeId: 'wt-1',
+        worktreePath: '/repo',
+        connectionId: 'ssh-1'
+      },
+      ['/Users/me/readme.md'],
+      '/repo',
+      { ensureDestinationDir: true }
+    )
+
+    expect(fsImportExternalPaths).toHaveBeenCalledWith({
+      sourcePaths: ['/Users/me/readme.md'],
+      destDir: '/repo',
+      connectionId: 'ssh-1',
+      ensureDir: true
+    })
+    expect(fsStageExternalPathsForRuntimeUpload).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes text search through the selected runtime without sending client root paths', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { files: [], totalMatches: 0, truncated: false },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await expect(
+      searchRuntimeFiles(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        {
+          query: 'needle',
+          rootPath: '/remote/repo',
+          caseSensitive: true,
+          maxResults: 50
+        }
+      )
+    ).resolves.toEqual({ files: [], totalMatches: 0, truncated: false })
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.search',
+      params: { worktree: 'wt-1', query: 'needle', caseSensitive: true, maxResults: 50 },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes quick-open file listing through the selected runtime', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: ['src/index.ts'],
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await expect(
+      listRuntimeFiles(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        {
+          rootPath: '/remote/repo',
+          excludePaths: ['/remote/repo-other']
+        }
+      )
+    ).resolves.toEqual(['src/index.ts'])
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'files.listAll',
+      params: { worktree: 'wt-1', excludePaths: ['/remote/repo-other'] },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes markdown document listing and stat through the selected runtime', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: [{ relativePath: 'readme.md' }],
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    const context = {
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      worktreeId: 'wt-1',
+      worktreePath: '/remote/repo'
+    }
+
+    await listRuntimeMarkdownDocuments(context, '/remote/repo')
+    await statRuntimePath(context, '/remote/repo/readme.md')
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'files.listMarkdownDocuments',
+      params: { worktree: 'wt-1' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'files.stat',
+      params: { worktree: 'wt-1', relativePath: 'readme.md' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('does not fall back to client-local stat for remote-owned paths outside the worktree', async () => {
+    await expect(
+      statRuntimePath(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: '/remote/repo'
+        },
+        '/tmp/readme.md'
+      )
+    ).rejects.toThrow('outside the owning runtime worktree')
+
+    await expect(
+      statRuntimePath(
+        {
+          settings: { activeRuntimeEnvironmentId: 'env-1' },
+          worktreeId: 'wt-1',
+          worktreePath: 'C:\\repo'
+        },
+        '\\\\server\\share\\repo\\readme.md'
+      )
+    ).rejects.toThrow('outside the owning runtime worktree')
+
+    expect(fsStat).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('uses the local fs changed stream when no runtime environment is active', async () => {
+    const unsubscribe = vi.fn()
+    const onPayload = vi.fn()
+    fsOnChanged.mockReturnValue(unsubscribe)
+
+    await expect(
+      subscribeRuntimeFileChanges(
+        {
+          settings: { activeRuntimeEnvironmentId: null },
+          worktreeId: 'wt-1',
+          worktreePath: '/repo'
+        },
+        onPayload
+      )
+    ).resolves.toBe(unsubscribe)
+
+    expect(fsOnChanged).toHaveBeenCalledWith(onPayload)
+    expect(runtimeEnvironmentSubscribe).not.toHaveBeenCalled()
+  })
+
+  it('maps runtime file watch events back to fs changed payloads', async () => {
+    const onPayload = vi.fn()
+    const unsubscribe = vi.fn()
+    let onResponse: ((response: unknown) => void) | undefined
+    runtimeEnvironmentSubscribe.mockImplementation((_args, callbacks) => {
+      onResponse = callbacks.onResponse
+      return Promise.resolve({ unsubscribe, sendBinary: vi.fn() })
+    })
+
+    const stop = await subscribeRuntimeFileChanges(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '/remote/repo'
+      },
+      onPayload
+    )
+
+    expect(runtimeEnvironmentSubscribe).toHaveBeenCalledWith(
+      {
+        selector: 'env-1',
+        method: 'files.watch',
+        params: { worktree: 'wt-1' },
+        timeoutMs: 15_000
+      },
+      expect.any(Object)
+    )
+
+    onResponse?.({
+      id: 'rpc-1',
+      ok: true,
+      result: {
+        type: 'changed',
+        worktree: 'wt-1',
+        events: [{ kind: 'update', absolutePath: '/remote/repo/readme.md' }]
+      },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    expect(onPayload).toHaveBeenCalledWith({
+      worktreePath: '/remote/repo',
+      events: [{ kind: 'update', absolutePath: '/remote/repo/readme.md' }]
+    })
+
+    stop()
+    expect(unsubscribe).toHaveBeenCalled()
+  })
+
+  it('shares one remote file watch subscription across listeners for the same worktree', async () => {
+    const firstPayload = vi.fn()
+    const secondPayload = vi.fn()
+    const unsubscribe = vi.fn()
+    let onResponse: ((response: unknown) => void) | undefined
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'unwatch',
+      ok: true,
+      result: { unsubscribed: true },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    runtimeEnvironmentSubscribe.mockImplementation((_args, callbacks) => {
+      onResponse = callbacks.onResponse
+      return Promise.resolve({ unsubscribe, sendBinary: vi.fn() })
+    })
+
+    const firstStop = await subscribeRuntimeFileChanges(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '/remote/repo'
+      },
+      firstPayload
+    )
+    const secondStop = await subscribeRuntimeFileChanges(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '/remote/repo'
+      },
+      secondPayload
+    )
+
+    expect(runtimeEnvironmentSubscribe).toHaveBeenCalledTimes(1)
+    onResponse?.({
+      id: 'ready',
+      ok: true,
+      result: { type: 'ready', subscriptionId: 'files-watch-1' },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    onResponse?.({
+      id: 'changed',
+      ok: true,
+      result: {
+        type: 'changed',
+        worktree: 'wt-1',
+        events: [{ kind: 'update', absolutePath: '/remote/repo/readme.md' }]
+      },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    expect(firstPayload).toHaveBeenCalledWith({
+      worktreePath: '/remote/repo',
+      events: [{ kind: 'update', absolutePath: '/remote/repo/readme.md' }]
+    })
+    expect(secondPayload).toHaveBeenCalledWith({
+      worktreePath: '/remote/repo',
+      events: [{ kind: 'update', absolutePath: '/remote/repo/readme.md' }]
+    })
+
+    firstStop()
+    expect(unsubscribe).not.toHaveBeenCalled()
+
+    secondStop()
+    expect(unsubscribe).toHaveBeenCalledTimes(1)
+    await vi.waitFor(() =>
+      expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.unwatch',
+        params: { subscriptionId: 'files-watch-1' },
+        timeoutMs: 5_000
+      })
+    )
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-file-client.ts b/src/renderer/src/runtime/runtime-file-client.ts
new file mode 100644
index 00000000000..233f641c61b
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-file-client.ts
@@ -0,0 +1,860 @@
+/* eslint-disable max-lines -- Why: this client intentionally centralizes the
+file preload API plus remote runtime fallbacks so call sites cannot drift on
+local-vs-environment routing rules. */
+import type {
+  DirEntry,
+  FsChangedPayload,
+  GlobalSettings,
+  MarkdownDocument,
+  SearchOptions,
+  SearchResult
+} from '../../../shared/types'
+import type { RuntimeFilePreviewResult, RuntimeFileReadResult } from '../../../shared/runtime-types'
+import {
+  callRuntimeRpc,
+  getActiveRuntimeTarget,
+  unwrapRuntimeRpcResult
+} from './runtime-rpc-client'
+import type { RuntimeRpcResponse } from '../../../shared/runtime-rpc-envelope'
+import { basename, joinPath, normalizeRelativePath } from '@/lib/path'
+import {
+  isWindowsAbsolutePathLike,
+  relativePathInsideRoot
+} from '../../../shared/cross-platform-path'
+
+export type RuntimeReadableFileContent = {
+  content: string
+  isBinary: boolean
+  isImage?: boolean
+  mimeType?: string
+}
+
+export type RuntimeFileReadArgs = {
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+  filePath: string
+  relativePath?: string
+  worktreeId?: string
+  connectionId?: string
+}
+
+export type RuntimeFileOperationArgs = {
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+  worktreeId: string | null | undefined
+  worktreePath: string | null | undefined
+  connectionId?: string
+}
+
+type StagedRuntimeImportSource =
+  | {
+      sourcePath: string
+      status: 'staged'
+      name: string
+      kind: 'file' | 'directory'
+      entries: StagedRuntimeImportEntry[]
+    }
+  | {
+      sourcePath: string
+      status: 'skipped'
+      reason: 'missing' | 'symlink' | 'permission-denied' | 'unsupported'
+    }
+  | { sourcePath: string; status: 'failed'; reason: string }
+
+type StagedRuntimeImportEntry =
+  | { relativePath: string; kind: 'directory' }
+  | { relativePath: string; kind: 'file'; contentBase64: string }
+
+type RuntimeImportResult =
+  | {
+      sourcePath: string
+      status: 'imported'
+      destPath: string
+      kind: 'file' | 'directory'
+      renamed: boolean
+    }
+  | {
+      sourcePath: string
+      status: 'skipped'
+      reason: 'missing' | 'symlink' | 'permission-denied' | 'unsupported'
+    }
+  | {
+      sourcePath: string
+      status: 'failed'
+      reason: string
+    }
+
+type RuntimeFileWatchEvent =
+  | { type: 'ready'; subscriptionId: string }
+  | { type: 'changed'; worktree: string; events: FsChangedPayload['events'] }
+  | { type: 'end' }
+
+const REMOTE_UPLOAD_BASE64_CHUNK_CHARS = 512 * 1024
+
+type RuntimeFileWatchListener = {
+  onPayload: (payload: FsChangedPayload) => void
+  onError?: (error: Error) => void
+}
+
+type SharedRuntimeFileWatch = {
+  target: { kind: 'environment'; environmentId: string }
+  worktreeId: string
+  listeners: Set<RuntimeFileWatchListener>
+  start: Promise<void>
+  unsubscribe: (() => void) | null
+  remoteSubscriptionId: string | null
+  closed: boolean
+}
+
+const sharedRuntimeFileWatches = new Map<string, SharedRuntimeFileWatch>()
+
+function getSharedRuntimeFileWatchKey(
+  environmentId: string,
+  worktreeId: string,
+  worktreePath: string
+): string {
+  return `${environmentId}\0${worktreeId}\0${worktreePath}`
+}
+
+export function getRuntimeFileReadScope(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  connectionId: string | undefined
+): string | undefined {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment' ? `runtime:${target.environmentId}` : connectionId
+}
+
+export async function readRuntimeFileContent({
+  settings,
+  filePath,
+  relativePath,
+  worktreeId,
+  connectionId
+}: RuntimeFileReadArgs): Promise<RuntimeReadableFileContent> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind !== 'environment') {
+    return window.api.fs.readFile({ filePath, connectionId })
+  }
+  if (!worktreeId) {
+    return window.api.fs.readFile({ filePath, connectionId })
+  }
+  if (!canReadRelativeRuntimeFile(relativePath)) {
+    throw new Error('Remote file is outside the owning runtime worktree')
+  }
+
+  const result = await callRuntimeRpc<RuntimeFileReadResult>(
+    target,
+    'files.read',
+    { worktree: worktreeId, relativePath },
+    { timeoutMs: 15_000 }
+  )
+  if (result.truncated) {
+    // Why: the runtime file RPC is preview-sized today; treating a truncated
+    // payload as editable content would make saves overwrite the rest of the file.
+    throw new Error(`Remote file is too large to open in the editor (${result.byteLength} bytes)`)
+  }
+  return { content: result.content, isBinary: false }
+}
+
+export async function readRuntimeFilePreview(
+  context: RuntimeFileOperationArgs,
+  filePath: string
+): Promise<RuntimeFilePreviewResult> {
+  const remoteArgs = getRemoteFileArgs(context, filePath)
+  if (!remoteArgs) {
+    if (hasRemoteRuntimeOwner(context)) {
+      throw new Error('Remote file is outside the owning runtime worktree')
+    }
+    return window.api.fs.readFile({ filePath, connectionId: context.connectionId })
+  }
+  return callRuntimeRpc<RuntimeFilePreviewResult>(
+    remoteArgs.target,
+    'files.readPreview',
+    { worktree: remoteArgs.worktreeId, relativePath: remoteArgs.relativePath },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function readRuntimeDirectory(
+  context: RuntimeFileOperationArgs,
+  dirPath: string
+): Promise<DirEntry[]> {
+  const remoteArgs = getRemoteFileArgs(context, dirPath)
+  if (!remoteArgs) {
+    assertLocalFilesystemFallbackAllowed(context)
+    return window.api.fs.readDir({ dirPath, connectionId: context.connectionId })
+  }
+  return callRuntimeRpc<DirEntry[]>(
+    remoteArgs.target,
+    'files.readDir',
+    { worktree: remoteArgs.worktreeId, relativePath: remoteArgs.relativePath },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function writeRuntimeFile(
+  context: RuntimeFileOperationArgs,
+  filePath: string,
+  content: string
+): Promise<void> {
+  const remoteArgs = getRemoteFileArgs(context, filePath)
+  if (!remoteArgs) {
+    assertLocalFilesystemFallbackAllowed(context)
+    await window.api.fs.writeFile({ filePath, content, connectionId: context.connectionId })
+    return
+  }
+  await callRuntimeRpc(
+    remoteArgs.target,
+    'files.write',
+    { worktree: remoteArgs.worktreeId, relativePath: remoteArgs.relativePath, content },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function createRuntimePath(
+  context: RuntimeFileOperationArgs,
+  path: string,
+  kind: 'file' | 'directory'
+): Promise<void> {
+  const remoteArgs = getRemoteFileArgs(context, path)
+  if (!remoteArgs) {
+    assertLocalFilesystemFallbackAllowed(context)
+    await (kind === 'directory'
+      ? window.api.fs.createDir({ dirPath: path, connectionId: context.connectionId })
+      : window.api.fs.createFile({ filePath: path, connectionId: context.connectionId }))
+    return
+  }
+  await callRuntimeRpc(
+    remoteArgs.target,
+    kind === 'directory' ? 'files.createDir' : 'files.createFile',
+    { worktree: remoteArgs.worktreeId, relativePath: remoteArgs.relativePath },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function renameRuntimePath(
+  context: RuntimeFileOperationArgs,
+  oldPath: string,
+  newPath: string
+): Promise<void> {
+  const oldRemoteArgs = getRemoteFileArgs(context, oldPath)
+  const newRelativePath = getRelativePathInsideWorktree(context.worktreePath, newPath)
+  if (!oldRemoteArgs || newRelativePath === null) {
+    assertLocalFilesystemFallbackAllowed(context)
+    await window.api.fs.rename({ oldPath, newPath, connectionId: context.connectionId })
+    return
+  }
+  await callRuntimeRpc(
+    oldRemoteArgs.target,
+    'files.rename',
+    {
+      worktree: oldRemoteArgs.worktreeId,
+      oldRelativePath: oldRemoteArgs.relativePath,
+      newRelativePath
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function copyRuntimePath(
+  context: RuntimeFileOperationArgs,
+  sourcePath: string,
+  destinationPath: string
+): Promise<void> {
+  const sourceArgs = getRemoteFileArgs(context, sourcePath)
+  const destinationArgs = getRemoteFileArgs(context, destinationPath)
+  if (!sourceArgs || !destinationArgs) {
+    assertLocalFilesystemFallbackAllowed(context)
+    await window.api.fs.copy({
+      sourcePath,
+      destinationPath,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(
+    sourceArgs.target,
+    'files.copy',
+    {
+      worktree: sourceArgs.worktreeId,
+      sourceRelativePath: sourceArgs.relativePath,
+      destinationRelativePath: destinationArgs.relativePath
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function deleteRuntimePath(
+  context: RuntimeFileOperationArgs,
+  targetPath: string,
+  recursive?: boolean
+): Promise<void> {
+  const remoteArgs = getRemoteFileArgs(context, targetPath)
+  if (!remoteArgs) {
+    assertLocalFilesystemFallbackAllowed(context)
+    await window.api.fs.deletePath({
+      targetPath,
+      connectionId: context.connectionId,
+      recursive
+    })
+    return
+  }
+  await callRuntimeRpc(
+    remoteArgs.target,
+    'files.delete',
+    { worktree: remoteArgs.worktreeId, relativePath: remoteArgs.relativePath, recursive },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function deleteRuntimeRelativePath(
+  context: RuntimeFileOperationArgs,
+  relativePath: string,
+  recursive?: boolean
+): Promise<boolean> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (
+    target.kind !== 'environment' ||
+    !context.worktreeId ||
+    !canReadRelativeRuntimeFile(relativePath)
+  ) {
+    return false
+  }
+  await callRuntimeRpc(
+    target,
+    'files.delete',
+    { worktree: context.worktreeId, relativePath: normalizeRelativePath(relativePath), recursive },
+    { timeoutMs: 15_000 }
+  )
+  return true
+}
+
+export async function importExternalPathsToRuntime(
+  context: RuntimeFileOperationArgs,
+  sourcePaths: string[],
+  destinationDir: string,
+  options?: { ensureDestinationDir?: boolean }
+): Promise<{ results: RuntimeImportResult[] }> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind !== 'environment' || !context.worktreeId || !context.worktreePath) {
+    return window.api.fs.importExternalPaths({
+      sourcePaths,
+      destDir: destinationDir,
+      connectionId: context.connectionId,
+      ensureDir: options?.ensureDestinationDir
+    })
+  }
+
+  const destinationArgs = getRemoteFileArgs(context, destinationDir)
+  if (!destinationArgs) {
+    throw new Error('Destination is outside the active runtime worktree')
+  }
+
+  const staged = await window.api.fs.stageExternalPathsForRuntimeUpload({ sourcePaths })
+  const results: RuntimeImportResult[] = []
+  const reservedNames = new Set<string>()
+
+  await ensureRuntimeDirectory(context, destinationDir)
+
+  for (const source of staged.sources as StagedRuntimeImportSource[]) {
+    if (source.status !== 'staged') {
+      results.push(source)
+      continue
+    }
+    try {
+      const finalName = await deconflictRuntimeImportName(
+        context,
+        destinationDir,
+        source.name,
+        reservedNames
+      )
+      const destPath = joinPath(destinationDir, finalName)
+      const destRelativePath = joinRuntimeRelativePath(destinationArgs.relativePath, finalName)
+      for (const entry of source.entries) {
+        const entryRelativePath = joinRuntimeRelativePath(destRelativePath, entry.relativePath)
+        if (entry.kind === 'directory') {
+          await callRuntimeRpc(
+            target,
+            'files.createDirNoClobber',
+            { worktree: context.worktreeId, relativePath: entryRelativePath },
+            { timeoutMs: 15_000 }
+          )
+          continue
+        }
+        await uploadRuntimeFileWithoutClobber(
+          target,
+          context.worktreeId,
+          entryRelativePath,
+          entry.contentBase64
+        )
+      }
+      reservedNames.add(finalName)
+      results.push({
+        sourcePath: source.sourcePath,
+        status: 'imported',
+        destPath,
+        kind: source.kind,
+        renamed: finalName !== source.name
+      })
+    } catch (error) {
+      results.push({
+        sourcePath: source.sourcePath,
+        status: 'failed',
+        reason: error instanceof Error ? error.message : String(error)
+      })
+    }
+  }
+
+  return { results }
+}
+
+async function uploadRuntimeFileWithoutClobber(
+  target: { kind: 'environment'; environmentId: string },
+  worktreeId: string,
+  relativePath: string,
+  contentBase64: string
+): Promise<void> {
+  const tempRelativePath = makeRuntimeUploadTempPath(relativePath)
+  try {
+    await writeRuntimeBase64File(target, worktreeId, tempRelativePath, contentBase64)
+    await callRuntimeRpc(
+      target,
+      'files.commitUpload',
+      {
+        worktree: worktreeId,
+        tempRelativePath,
+        finalRelativePath: relativePath
+      },
+      { timeoutMs: 30_000 }
+    )
+  } finally {
+    await callRuntimeRpc(
+      target,
+      'files.delete',
+      { worktree: worktreeId, relativePath: tempRelativePath, recursive: false },
+      { timeoutMs: 15_000 }
+    ).catch(() => {})
+  }
+}
+
+async function writeRuntimeBase64File(
+  target: { kind: 'environment'; environmentId: string },
+  worktreeId: string,
+  relativePath: string,
+  contentBase64: string
+): Promise<void> {
+  if (contentBase64.length <= REMOTE_UPLOAD_BASE64_CHUNK_CHARS) {
+    await callRuntimeRpc(
+      target,
+      'files.writeBase64',
+      { worktree: worktreeId, relativePath, contentBase64 },
+      { timeoutMs: 30_000 }
+    )
+    return
+  }
+
+  for (let offset = 0; offset < contentBase64.length; offset += REMOTE_UPLOAD_BASE64_CHUNK_CHARS) {
+    await callRuntimeRpc(
+      target,
+      'files.writeBase64Chunk',
+      {
+        worktree: worktreeId,
+        relativePath,
+        contentBase64: contentBase64.slice(offset, offset + REMOTE_UPLOAD_BASE64_CHUNK_CHARS),
+        append: offset > 0
+      },
+      { timeoutMs: 30_000 }
+    )
+  }
+}
+
+function makeRuntimeUploadTempPath(relativePath: string): string {
+  const normalized = normalizeRelativePath(relativePath)
+  const slashIndex = normalized.lastIndexOf('/')
+  const dir = slashIndex === -1 ? '' : normalized.slice(0, slashIndex + 1)
+  const leaf = slashIndex === -1 ? normalized : normalized.slice(slashIndex + 1)
+  const nonce = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+  return `${dir}.${leaf}.orca-upload-${nonce}`
+}
+
+async function ensureRuntimeDirectory(
+  context: RuntimeFileOperationArgs,
+  destinationDir: string
+): Promise<void> {
+  const destinationArgs = getRemoteFileArgs(context, destinationDir)
+  if (!destinationArgs) {
+    return
+  }
+  const parts = normalizeRelativePath(destinationArgs.relativePath)
+    .split('/')
+    .filter((part) => part.length > 0)
+  let current = ''
+  for (const part of parts) {
+    current = joinRuntimeRelativePath(current, part)
+    const absolutePath = joinPath(context.worktreePath ?? '', current)
+    if (await runtimePathExists(context, absolutePath)) {
+      continue
+    }
+    await callRuntimeRpc(
+      destinationArgs.target,
+      'files.createDir',
+      { worktree: destinationArgs.worktreeId, relativePath: current },
+      { timeoutMs: 15_000 }
+    )
+  }
+}
+
+export async function searchRuntimeFiles(
+  context: RuntimeFileOperationArgs,
+  options: SearchOptions
+): Promise<SearchResult> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind !== 'environment' || !context.worktreeId) {
+    return window.api.fs.search({
+      ...options,
+      connectionId: context.connectionId
+    })
+  }
+  const { rootPath: _rootPath, ...runtimeOptions } = options
+  return callRuntimeRpc<SearchResult>(
+    target,
+    'files.search',
+    { worktree: context.worktreeId, ...runtimeOptions },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function listRuntimeFiles(
+  context: RuntimeFileOperationArgs,
+  args: { rootPath: string; excludePaths?: string[] }
+): Promise<string[]> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind !== 'environment' || !context.worktreeId) {
+    return window.api.fs.listFiles({
+      rootPath: args.rootPath,
+      connectionId: context.connectionId,
+      excludePaths: args.excludePaths
+    })
+  }
+  return callRuntimeRpc<string[]>(
+    target,
+    'files.listAll',
+    { worktree: context.worktreeId, excludePaths: args.excludePaths },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function listRuntimeMarkdownDocuments(
+  context: RuntimeFileOperationArgs,
+  rootPath: string
+): Promise<MarkdownDocument[]> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind !== 'environment' || !context.worktreeId) {
+    return window.api.fs.listMarkdownDocuments({
+      rootPath,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<MarkdownDocument[]>(
+    target,
+    'files.listMarkdownDocuments',
+    { worktree: context.worktreeId },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function statRuntimePath(
+  context: RuntimeFileOperationArgs,
+  absolutePath: string
+): Promise<{ size: number; isDirectory: boolean; mtime: number }> {
+  const remoteArgs = getRemoteFileArgs(context, absolutePath)
+  if (!remoteArgs) {
+    assertLocalFilesystemFallbackAllowed(context)
+    return window.api.fs.stat({
+      filePath: absolutePath,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<{ size: number; isDirectory: boolean; mtime: number }>(
+    remoteArgs.target,
+    'files.stat',
+    { worktree: remoteArgs.worktreeId, relativePath: remoteArgs.relativePath },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function subscribeRuntimeFileChanges(
+  context: RuntimeFileOperationArgs,
+  onPayload: (payload: FsChangedPayload) => void,
+  onError?: (error: Error) => void
+): Promise<() => void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind !== 'environment' || !context.worktreeId || !context.worktreePath) {
+    return window.api.fs.onFsChanged(onPayload)
+  }
+
+  const listener: RuntimeFileWatchListener = { onPayload, onError }
+  const key = getSharedRuntimeFileWatchKey(
+    target.environmentId,
+    context.worktreeId,
+    context.worktreePath
+  )
+  let shared = sharedRuntimeFileWatches.get(key)
+  if (!shared) {
+    shared = createSharedRuntimeFileWatch(key, target, context.worktreeId, context.worktreePath)
+    sharedRuntimeFileWatches.set(key, shared)
+  }
+  shared.listeners.add(listener)
+  try {
+    await shared.start
+  } catch (err) {
+    shared.listeners.delete(listener)
+    throw err
+  }
+
+  return () => {
+    const current = sharedRuntimeFileWatches.get(key)
+    if (!current) {
+      return
+    }
+    current.listeners.delete(listener)
+    if (current.listeners.size === 0) {
+      closeSharedRuntimeFileWatch(key, current)
+    }
+  }
+}
+
+function createSharedRuntimeFileWatch(
+  key: string,
+  target: { kind: 'environment'; environmentId: string },
+  worktreeId: string,
+  worktreePath: string
+): SharedRuntimeFileWatch {
+  const shared: SharedRuntimeFileWatch = {
+    target,
+    worktreeId,
+    listeners: new Set(),
+    start: Promise.resolve(),
+    unsubscribe: null,
+    remoteSubscriptionId: null,
+    closed: false
+  }
+  // Why: editor reloads and the Explorer can watch the same remote worktree.
+  // Keep one runtime WebSocket/server watcher and fan out events in renderer.
+  shared.start = window.api.runtimeEnvironments
+    .subscribe(
+      {
+        selector: target.environmentId,
+        method: 'files.watch',
+        params: { worktree: worktreeId },
+        timeoutMs: 15_000
+      },
+      {
+        onResponse: (response) => {
+          handleSharedRuntimeFileWatchResponse(shared, worktreePath, response)
+        },
+        onError: (error) => {
+          notifySharedRuntimeFileWatchError(shared, new Error(error.message))
+        },
+        onClose: () => {
+          if (sharedRuntimeFileWatches.get(key) === shared) {
+            sharedRuntimeFileWatches.delete(key)
+          }
+          shared.closed = true
+          shared.unsubscribe = null
+        }
+      }
+    )
+    .then((subscription) => {
+      if (shared.closed || sharedRuntimeFileWatches.get(key) !== shared) {
+        subscription.unsubscribe()
+        unwatchSharedRuntimeFileWatch(shared)
+        return
+      }
+      shared.unsubscribe = subscription.unsubscribe
+    })
+    .catch((err) => {
+      if (sharedRuntimeFileWatches.get(key) === shared) {
+        sharedRuntimeFileWatches.delete(key)
+      }
+      shared.closed = true
+      notifySharedRuntimeFileWatchError(shared, err instanceof Error ? err : new Error(String(err)))
+      throw err
+    })
+  return shared
+}
+
+function handleSharedRuntimeFileWatchResponse(
+  shared: SharedRuntimeFileWatch,
+  worktreePath: string,
+  response: unknown
+): void {
+  try {
+    const event = unwrapRuntimeRpcResult<RuntimeFileWatchEvent>(
+      response as RuntimeRpcResponse<RuntimeFileWatchEvent>
+    )
+    if (event.type === 'ready') {
+      shared.remoteSubscriptionId = event.subscriptionId
+    } else if (event.type === 'changed') {
+      for (const listener of Array.from(shared.listeners)) {
+        listener.onPayload({ worktreePath, events: event.events })
+      }
+    }
+  } catch (err) {
+    notifySharedRuntimeFileWatchError(shared, err instanceof Error ? err : new Error(String(err)))
+  }
+}
+
+function notifySharedRuntimeFileWatchError(shared: SharedRuntimeFileWatch, error: Error): void {
+  for (const listener of Array.from(shared.listeners)) {
+    listener.onError?.(error)
+  }
+}
+
+function closeSharedRuntimeFileWatch(key: string, shared: SharedRuntimeFileWatch): void {
+  if (shared.closed) {
+    return
+  }
+  shared.closed = true
+  sharedRuntimeFileWatches.delete(key)
+  shared.unsubscribe?.()
+  shared.unsubscribe = null
+  unwatchSharedRuntimeFileWatch(shared)
+}
+
+function unwatchSharedRuntimeFileWatch(shared: SharedRuntimeFileWatch): void {
+  if (!shared.remoteSubscriptionId) {
+    return
+  }
+  void callRuntimeRpc(
+    shared.target,
+    'files.unwatch',
+    { subscriptionId: shared.remoteSubscriptionId },
+    { timeoutMs: 5_000 }
+  ).catch(() => {})
+}
+
+export async function runtimePathExists(
+  context: RuntimeFileOperationArgs,
+  absolutePath: string
+): Promise<boolean> {
+  try {
+    await statRuntimePath(context, absolutePath)
+    return true
+  } catch (err) {
+    const message = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase()
+    if (
+      message.includes('enoent') ||
+      message.includes('not found') ||
+      message.includes('no such file')
+    ) {
+      return false
+    }
+    throw err
+  }
+}
+
+export function isRemoteRuntimeFileOperation(
+  context: RuntimeFileOperationArgs,
+  path: string
+): boolean {
+  return getRemoteFileArgs(context, path) !== null
+}
+
+function canReadRelativeRuntimeFile(relativePath: string | undefined): relativePath is string {
+  return Boolean(relativePath && relativePath.trim() && !isAbsolutePathLike(relativePath))
+}
+
+function isAbsolutePathLike(value: string): boolean {
+  return value.startsWith('/') || isWindowsAbsolutePathLike(value)
+}
+
+function getRemoteFileArgs(
+  context: RuntimeFileOperationArgs,
+  absolutePath: string
+): {
+  target: ReturnType<typeof getActiveRuntimeTarget> & { kind: 'environment' }
+  worktreeId: string
+  relativePath: string
+} | null {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind !== 'environment' || !context.worktreeId) {
+    return null
+  }
+  const relativePath = getRelativePathInsideWorktree(context.worktreePath, absolutePath)
+  if (relativePath === null) {
+    return null
+  }
+  return { target, worktreeId: context.worktreeId, relativePath }
+}
+
+function hasRemoteRuntimeOwner(context: RuntimeFileOperationArgs): boolean {
+  return (
+    getActiveRuntimeTarget(context.settings).kind === 'environment' && Boolean(context.worktreeId)
+  )
+}
+
+function assertLocalFilesystemFallbackAllowed(context: RuntimeFileOperationArgs): void {
+  if (hasRemoteRuntimeOwner(context)) {
+    throw new Error('Remote file is outside the owning runtime worktree')
+  }
+}
+
+function getRelativePathInsideWorktree(
+  worktreePath: string | null | undefined,
+  absolutePath: string
+): string | null {
+  if (!worktreePath) {
+    return null
+  }
+  return relativePathInsideRoot(worktreePath, absolutePath)
+}
+
+async function deconflictRuntimeImportName(
+  context: RuntimeFileOperationArgs,
+  destinationDir: string,
+  originalName: string,
+  reservedNames: Set<string>
+): Promise<string> {
+  if (
+    !(await runtimePathExists(context, joinPath(destinationDir, originalName))) &&
+    !reservedNames.has(originalName)
+  ) {
+    return originalName
+  }
+
+  const dotIndex = originalName.lastIndexOf('.')
+  const hasMeaningfulExt = dotIndex > 0
+  const stem = hasMeaningfulExt ? originalName.slice(0, dotIndex) : originalName
+  const ext = hasMeaningfulExt ? originalName.slice(dotIndex) : ''
+  let candidate = `${stem} copy${ext}`
+  if (
+    !(await runtimePathExists(context, joinPath(destinationDir, candidate))) &&
+    !reservedNames.has(candidate)
+  ) {
+    return candidate
+  }
+
+  let counter = 2
+  while (counter < 10000) {
+    candidate = `${stem} copy ${counter}${ext}`
+    if (
+      !(await runtimePathExists(context, joinPath(destinationDir, candidate))) &&
+      !reservedNames.has(candidate)
+    ) {
+      return candidate
+    }
+    counter += 1
+  }
+  throw new Error(`Could not generate a unique name for '${basename(originalName)}'`)
+}
+
+function joinRuntimeRelativePath(basePath: string, relativePath: string): string {
+  const normalizedBase = normalizeRelativePath(basePath)
+  const normalizedRelative = normalizeRelativePath(relativePath)
+  if (!normalizedBase) {
+    return normalizedRelative
+  }
+  if (!normalizedRelative) {
+    return normalizedBase
+  }
+  return `${normalizedBase}/${normalizedRelative}`
+}
diff --git a/src/renderer/src/runtime/runtime-git-client.test.ts b/src/renderer/src/runtime/runtime-git-client.test.ts
new file mode 100644
index 00000000000..19888c32ae8
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-git-client.test.ts
@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  bulkStageRuntimeGitPaths,
+  commitRuntimeGit,
+  getRuntimeGitDiff,
+  getRuntimeGitStatus,
+  pushRuntimeGit
+} from './runtime-git-client'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from './runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from './runtime-rpc-client'
+
+const gitStatus = vi.fn()
+const gitDiff = vi.fn()
+const gitBulkStage = vi.fn()
+const gitCommit = vi.fn()
+const gitPush = vi.fn()
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+const runtimeCall = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  gitStatus.mockReset()
+  gitDiff.mockReset()
+  gitBulkStage.mockReset()
+  gitCommit.mockReset()
+  gitPush.mockReset()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  runtimeCall.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      git: {
+        status: gitStatus,
+        diff: gitDiff,
+        bulkStage: gitBulkStage,
+        commit: gitCommit,
+        push: gitPush
+      },
+      runtime: { call: runtimeCall },
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCall }
+    }
+  })
+})
+
+describe('runtime git client', () => {
+  it('uses local git IPC when no remote runtime is active', async () => {
+    gitStatus.mockResolvedValue({ entries: [], conflictOperation: 'unknown' })
+
+    await getRuntimeGitStatus({
+      settings: { activeRuntimeEnvironmentId: null },
+      worktreeId: 'wt-1',
+      worktreePath: '/repo',
+      connectionId: 'ssh-1'
+    })
+
+    expect(gitStatus).toHaveBeenCalledWith({ worktreePath: '/repo', connectionId: 'ssh-1' })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes status and diffs through the active runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { entries: [], conflictOperation: 'unknown' },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await getRuntimeGitStatus({
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      worktreeId: 'wt-1',
+      worktreePath: '/repo'
+    })
+    await getRuntimeGitDiff(
+      {
+        settings: { activeRuntimeEnvironmentId: 'env-1' },
+        worktreeId: 'wt-1',
+        worktreePath: '/repo'
+      },
+      { filePath: 'src/a.ts', staged: false, compareAgainstHead: true }
+    )
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'git.status',
+      params: { worktree: 'wt-1' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'git.diff',
+      params: {
+        worktree: 'wt-1',
+        filePath: 'src/a.ts',
+        staged: false,
+        compareAgainstHead: true
+      },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes bulk stage and remote operations through the active runtime', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { success: true },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    const context = {
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      worktreeId: 'wt-1',
+      worktreePath: '/repo'
+    }
+
+    await bulkStageRuntimeGitPaths(context, ['a.ts', 'b.ts'])
+    await commitRuntimeGit(context, 'feat: test')
+    await pushRuntimeGit(context, { publish: true, pushTarget: { remote: 'origin' } as never })
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'git.bulkStage',
+      params: { worktree: 'wt-1', filePaths: ['a.ts', 'b.ts'] },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'git.commit',
+      params: { worktree: 'wt-1', message: 'feat: test' },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
+      selector: 'env-1',
+      method: 'git.push',
+      params: { worktree: 'wt-1', publish: true, pushTarget: { remote: 'origin' } },
+      timeoutMs: 30_000
+    })
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-git-client.ts b/src/renderer/src/runtime/runtime-git-client.ts
new file mode 100644
index 00000000000..759edbd624c
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-git-client.ts
@@ -0,0 +1,340 @@
+/* eslint-disable max-lines -- Why: this module mirrors the git preload API with
+runtime-aware routing so source-control callers have one typed boundary instead
+of reimplementing local-vs-environment branching per operation. */
+import type {
+  GitBranchCompareResult,
+  GitConflictOperation,
+  GitDiffResult,
+  GitPushTarget,
+  GitStatusResult,
+  GitUpstreamStatus,
+  GlobalSettings
+} from '../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
+
+export type RuntimeGitContext = {
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+  worktreeId: string | null | undefined
+  worktreePath: string
+  connectionId?: string
+}
+
+export function getRuntimeGitScope(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  connectionId: string | undefined
+): string | undefined {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment' ? `runtime:${target.environmentId}` : connectionId
+}
+
+export async function getRuntimeGitStatus(context: RuntimeGitContext): Promise<GitStatusResult> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.status({
+      worktreePath: context.worktreePath,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<GitStatusResult>(
+    target,
+    'git.status',
+    { worktree: context.worktreeId },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function getRuntimeGitConflictOperation(
+  context: RuntimeGitContext
+): Promise<GitConflictOperation> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.conflictOperation({
+      worktreePath: context.worktreePath,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<GitConflictOperation>(
+    target,
+    'git.conflictOperation',
+    { worktree: context.worktreeId },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function getRuntimeGitDiff(
+  context: RuntimeGitContext,
+  args: { filePath: string; staged: boolean; compareAgainstHead?: boolean }
+): Promise<GitDiffResult> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.diff({
+      worktreePath: context.worktreePath,
+      filePath: args.filePath,
+      staged: args.staged,
+      compareAgainstHead: args.compareAgainstHead,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<GitDiffResult>(
+    target,
+    'git.diff',
+    { worktree: context.worktreeId, ...args },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function getRuntimeGitBranchCompare(
+  context: RuntimeGitContext,
+  baseRef: string
+): Promise<GitBranchCompareResult> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.branchCompare({
+      worktreePath: context.worktreePath,
+      baseRef,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<GitBranchCompareResult>(
+    target,
+    'git.branchCompare',
+    { worktree: context.worktreeId, baseRef },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function getRuntimeGitUpstreamStatus(
+  context: RuntimeGitContext
+): Promise<GitUpstreamStatus> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.upstreamStatus({
+      worktreePath: context.worktreePath,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<GitUpstreamStatus>(
+    target,
+    'git.upstreamStatus',
+    { worktree: context.worktreeId },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function fetchRuntimeGit(context: RuntimeGitContext): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.fetch({
+      worktreePath: context.worktreePath,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(target, 'git.fetch', { worktree: context.worktreeId }, { timeoutMs: 30_000 })
+}
+
+export async function pullRuntimeGit(context: RuntimeGitContext): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.pull({
+      worktreePath: context.worktreePath,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(target, 'git.pull', { worktree: context.worktreeId }, { timeoutMs: 30_000 })
+}
+
+export async function pushRuntimeGit(
+  context: RuntimeGitContext,
+  args: { publish?: boolean; pushTarget?: GitPushTarget } = {}
+): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.push({
+      worktreePath: context.worktreePath,
+      publish: args.publish,
+      pushTarget: args.pushTarget,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'git.push',
+    { worktree: context.worktreeId, publish: args.publish, pushTarget: args.pushTarget },
+    { timeoutMs: 30_000 }
+  )
+}
+
+export async function getRuntimeGitBranchDiff(
+  context: RuntimeGitContext,
+  args: {
+    compare: { baseRef: string; baseOid: string; headOid: string; mergeBase: string }
+    filePath: string
+    oldPath?: string
+  }
+): Promise<GitDiffResult> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.branchDiff({
+      worktreePath: context.worktreePath,
+      compare: args.compare,
+      filePath: args.filePath,
+      oldPath: args.oldPath,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<GitDiffResult>(
+    target,
+    'git.branchDiff',
+    { worktree: context.worktreeId, ...args },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function commitRuntimeGit(
+  context: RuntimeGitContext,
+  message: string
+): Promise<{ success: boolean; error?: string }> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.commit({
+      worktreePath: context.worktreePath,
+      message,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<{ success: boolean; error?: string }>(
+    target,
+    'git.commit',
+    { worktree: context.worktreeId, message },
+    { timeoutMs: 30_000 }
+  )
+}
+
+export async function stageRuntimeGitPath(
+  context: RuntimeGitContext,
+  filePath: string
+): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.stage({
+      worktreePath: context.worktreePath,
+      filePath,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'git.stage',
+    { worktree: context.worktreeId, filePath },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function bulkStageRuntimeGitPaths(
+  context: RuntimeGitContext,
+  filePaths: string[]
+): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.bulkStage({
+      worktreePath: context.worktreePath,
+      filePaths,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'git.bulkStage',
+    { worktree: context.worktreeId, filePaths },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function unstageRuntimeGitPath(
+  context: RuntimeGitContext,
+  filePath: string
+): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.unstage({
+      worktreePath: context.worktreePath,
+      filePath,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'git.unstage',
+    { worktree: context.worktreeId, filePath },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function bulkUnstageRuntimeGitPaths(
+  context: RuntimeGitContext,
+  filePaths: string[]
+): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.bulkUnstage({
+      worktreePath: context.worktreePath,
+      filePaths,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'git.bulkUnstage',
+    { worktree: context.worktreeId, filePaths },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function discardRuntimeGitPath(
+  context: RuntimeGitContext,
+  filePath: string
+): Promise<void> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    await window.api.git.discard({
+      worktreePath: context.worktreePath,
+      filePath,
+      connectionId: context.connectionId
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'git.discard',
+    { worktree: context.worktreeId, filePath },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function getRuntimeGitRemoteFileUrl(
+  context: RuntimeGitContext,
+  args: { relativePath: string; line: number }
+): Promise<string | null> {
+  const target = getActiveRuntimeTarget(context.settings)
+  if (target.kind === 'local' || !context.worktreeId) {
+    return window.api.git.remoteFileUrl({
+      worktreePath: context.worktreePath,
+      relativePath: args.relativePath,
+      line: args.line,
+      connectionId: context.connectionId
+    })
+  }
+  return callRuntimeRpc<string | null>(
+    target,
+    'git.remoteFileUrl',
+    { worktree: context.worktreeId, relativePath: args.relativePath, line: args.line },
+    { timeoutMs: 15_000 }
+  )
+}
diff --git a/src/renderer/src/runtime/runtime-hooks-client.test.ts b/src/renderer/src/runtime/runtime-hooks-client.test.ts
new file mode 100644
index 00000000000..53c9d6891a1
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-hooks-client.test.ts
@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  checkRuntimeHooks,
+  readRuntimeIssueCommand,
+  writeRuntimeIssueCommand
+} from './runtime-hooks-client'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from './runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from './runtime-rpc-client'
+
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+const hooksCheck = vi.fn()
+const hooksReadIssueCommand = vi.fn()
+const hooksWriteIssueCommand = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  hooksCheck.mockReset()
+  hooksReadIssueCommand.mockReset()
+  hooksWriteIssueCommand.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCall },
+      hooks: {
+        check: hooksCheck,
+        readIssueCommand: hooksReadIssueCommand,
+        writeIssueCommand: hooksWriteIssueCommand
+      }
+    }
+  })
+})
+
+describe('runtime hooks client', () => {
+  it('uses local hook IPC when no runtime environment is active', async () => {
+    hooksCheck.mockResolvedValue({ hasHooks: false, hooks: null, mayNeedUpdate: false })
+    hooksReadIssueCommand.mockResolvedValue({
+      localContent: null,
+      sharedContent: null,
+      effectiveContent: null,
+      localFilePath: '',
+      source: 'none'
+    })
+
+    await checkRuntimeHooks({ activeRuntimeEnvironmentId: null }, 'repo-1')
+    await readRuntimeIssueCommand({ activeRuntimeEnvironmentId: null }, 'repo-1')
+    await writeRuntimeIssueCommand({ activeRuntimeEnvironmentId: null }, 'repo-1', 'Fix it')
+
+    expect(hooksCheck).toHaveBeenCalledWith({ repoId: 'repo-1' })
+    expect(hooksReadIssueCommand).toHaveBeenCalledWith({ repoId: 'repo-1' })
+    expect(hooksWriteIssueCommand).toHaveBeenCalledWith({ repoId: 'repo-1', content: 'Fix it' })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes hook operations through the active runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { ok: true },
+      _meta: { runtimeId: 'runtime-1' }
+    })
+
+    await checkRuntimeHooks({ activeRuntimeEnvironmentId: 'env-1' }, 'repo-1')
+    await readRuntimeIssueCommand({ activeRuntimeEnvironmentId: 'env-1' }, 'repo-1')
+    await writeRuntimeIssueCommand({ activeRuntimeEnvironmentId: 'env-1' }, 'repo-1', 'Fix it')
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'repo.hooksCheck',
+      params: { repo: 'repo-1' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'repo.issueCommandRead',
+      params: { repo: 'repo-1' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
+      selector: 'env-1',
+      method: 'repo.issueCommandWrite',
+      params: { repo: 'repo-1', content: 'Fix it' },
+      timeoutMs: 15_000
+    })
+    expect(hooksCheck).not.toHaveBeenCalled()
+    expect(hooksReadIssueCommand).not.toHaveBeenCalled()
+    expect(hooksWriteIssueCommand).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-hooks-client.ts b/src/renderer/src/runtime/runtime-hooks-client.ts
new file mode 100644
index 00000000000..3179de7eef0
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-hooks-client.ts
@@ -0,0 +1,66 @@
+import type { GlobalSettings, OrcaHooks } from '../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
+
+export type HookCheckResult = {
+  hasHooks: boolean
+  hooks: OrcaHooks | null
+  mayNeedUpdate: boolean
+}
+
+export type IssueCommandReadResult = {
+  localContent: string | null
+  sharedContent: string | null
+  effectiveContent: string | null
+  localFilePath: string
+  source: 'local' | 'shared' | 'none'
+}
+
+export async function checkRuntimeHooks(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  repoId: string
+): Promise<HookCheckResult> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind !== 'environment') {
+    return window.api.hooks.check({ repoId })
+  }
+  return callRuntimeRpc<HookCheckResult>(
+    target,
+    'repo.hooksCheck',
+    { repo: repoId },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function readRuntimeIssueCommand(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  repoId: string
+): Promise<IssueCommandReadResult> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind !== 'environment') {
+    return window.api.hooks.readIssueCommand({ repoId })
+  }
+  return callRuntimeRpc<IssueCommandReadResult>(
+    target,
+    'repo.issueCommandRead',
+    { repo: repoId },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function writeRuntimeIssueCommand(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  repoId: string,
+  content: string
+): Promise<void> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind !== 'environment') {
+    await window.api.hooks.writeIssueCommand({ repoId, content })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'repo.issueCommandWrite',
+    { repo: repoId, content },
+    { timeoutMs: 15_000 }
+  )
+}
diff --git a/src/renderer/src/runtime/runtime-linear-client.test.ts b/src/renderer/src/runtime/runtime-linear-client.test.ts
new file mode 100644
index 00000000000..a552db06e19
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-linear-client.test.ts
@@ -0,0 +1,148 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  linearCreateIssue,
+  linearListTeams,
+  linearSearchIssues,
+  linearStatus,
+  linearUpdateIssue
+} from './runtime-linear-client'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from './runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from './runtime-rpc-client'
+
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+const linearStatusLocal = vi.fn()
+const linearSearchIssuesLocal = vi.fn()
+const linearCreateIssueLocal = vi.fn()
+const linearUpdateIssueLocal = vi.fn()
+const linearListTeamsLocal = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  linearStatusLocal.mockReset()
+  linearSearchIssuesLocal.mockReset()
+  linearCreateIssueLocal.mockReset()
+  linearUpdateIssueLocal.mockReset()
+  linearListTeamsLocal.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCall },
+      linear: {
+        status: linearStatusLocal,
+        searchIssues: linearSearchIssuesLocal,
+        createIssue: linearCreateIssueLocal,
+        updateIssue: linearUpdateIssueLocal,
+        listTeams: linearListTeamsLocal
+      }
+    }
+  })
+})
+
+describe('runtime linear client', () => {
+  it('uses local Linear IPC when no runtime environment is active', async () => {
+    linearStatusLocal.mockResolvedValue({ connected: false, viewer: null })
+    linearSearchIssuesLocal.mockResolvedValue([{ id: 'issue-1' }])
+
+    await expect(linearStatus({ activeRuntimeEnvironmentId: null })).resolves.toEqual({
+      connected: false,
+      viewer: null
+    })
+    await expect(
+      linearSearchIssues({ activeRuntimeEnvironmentId: null }, 'bug', 10)
+    ).resolves.toEqual([{ id: 'issue-1' }])
+
+    expect(linearStatusLocal).toHaveBeenCalled()
+    expect(linearSearchIssuesLocal).toHaveBeenCalledWith({ query: 'bug', limit: 10 })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes Linear reads through the selected runtime environment', async () => {
+    runtimeEnvironmentCall
+      .mockResolvedValueOnce({
+        id: 'rpc-status',
+        ok: true,
+        result: { connected: true, viewer: null },
+        _meta: { runtimeId: 'runtime-1' }
+      })
+      .mockResolvedValueOnce({
+        id: 'rpc-search',
+        ok: true,
+        result: [{ id: 'issue-1' }],
+        _meta: { runtimeId: 'runtime-1' }
+      })
+
+    await linearStatus({ activeRuntimeEnvironmentId: 'env-1' })
+    await linearSearchIssues({ activeRuntimeEnvironmentId: 'env-1' }, 'bug', 10)
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'linear.status',
+      params: undefined,
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'linear.searchIssues',
+      params: { query: 'bug', limit: 10 },
+      timeoutMs: 30_000
+    })
+    expect(linearStatusLocal).not.toHaveBeenCalled()
+    expect(linearSearchIssuesLocal).not.toHaveBeenCalled()
+  })
+
+  it('routes Linear mutations and metadata through the selected runtime environment', async () => {
+    runtimeEnvironmentCall
+      .mockResolvedValueOnce({
+        id: 'rpc-create',
+        ok: true,
+        result: { ok: true, id: 'issue-1', identifier: 'ENG-1', url: 'https://linear.app/ENG-1' },
+        _meta: { runtimeId: 'runtime-1' }
+      })
+      .mockResolvedValueOnce({
+        id: 'rpc-update',
+        ok: true,
+        result: { ok: true },
+        _meta: { runtimeId: 'runtime-1' }
+      })
+      .mockResolvedValueOnce({
+        id: 'rpc-teams',
+        ok: true,
+        result: [{ id: 'team-1' }],
+        _meta: { runtimeId: 'runtime-1' }
+      })
+
+    await linearCreateIssue(
+      { activeRuntimeEnvironmentId: 'env-1' },
+      { teamId: 'team-1', title: 'Fix bug' }
+    )
+    await linearUpdateIssue({ activeRuntimeEnvironmentId: 'env-1' }, 'issue-1', { priority: 2 })
+    await linearListTeams({ activeRuntimeEnvironmentId: 'env-1' })
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'linear.createIssue',
+      params: { teamId: 'team-1', title: 'Fix bug' },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'linear.updateIssue',
+      params: { id: 'issue-1', updates: { priority: 2 } },
+      timeoutMs: 30_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
+      selector: 'env-1',
+      method: 'linear.listTeams',
+      params: undefined,
+      timeoutMs: 30_000
+    })
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-linear-client.ts b/src/renderer/src/runtime/runtime-linear-client.ts
new file mode 100644
index 00000000000..7821a46d8aa
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-linear-client.ts
@@ -0,0 +1,222 @@
+import type {
+  GlobalSettings,
+  LinearComment,
+  LinearConnectionStatus,
+  LinearIssue,
+  LinearIssueUpdate,
+  LinearLabel,
+  LinearMember,
+  LinearTeam,
+  LinearViewer,
+  LinearWorkflowState
+} from '../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
+
+export type RuntimeLinearSettings =
+  | Pick<GlobalSettings, 'activeRuntimeEnvironmentId'>
+  | null
+  | undefined
+
+export type LinearIssueFilter = 'assigned' | 'created' | 'all' | 'completed'
+export type LinearConnectResult = { ok: true; viewer: LinearViewer } | { ok: false; error: string }
+export type LinearCreateIssueResult =
+  | { ok: true; id: string; identifier: string; url: string }
+  | { ok: false; error: string }
+export type LinearMutationResult = { ok: true } | { ok: false; error: string }
+export type LinearCommentResult = { ok: true; id: string } | { ok: false; error: string }
+
+export async function linearStatus(
+  settings: RuntimeLinearSettings
+): Promise<LinearConnectionStatus> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearConnectionStatus>(target, 'linear.status', undefined, {
+        timeoutMs: 15_000
+      })
+    : window.api.linear.status()
+}
+
+export async function linearTestConnection(
+  settings: RuntimeLinearSettings
+): Promise<LinearConnectResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearConnectResult>(target, 'linear.testConnection', undefined, {
+        timeoutMs: 30_000
+      })
+    : window.api.linear.testConnection()
+}
+
+export async function linearConnect(
+  settings: RuntimeLinearSettings,
+  apiKey: string
+): Promise<LinearConnectResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearConnectResult>(
+        target,
+        'linear.connect',
+        { apiKey },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.connect({ apiKey })
+}
+
+export async function linearDisconnect(settings: RuntimeLinearSettings): Promise<void> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind === 'environment') {
+    await callRuntimeRpc<{ ok: true }>(target, 'linear.disconnect', undefined, {
+      timeoutMs: 15_000
+    })
+    return
+  }
+  await window.api.linear.disconnect()
+}
+
+export async function linearSearchIssues(
+  settings: RuntimeLinearSettings,
+  query: string,
+  limit?: number
+): Promise<LinearIssue[]> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearIssue[]>(
+        target,
+        'linear.searchIssues',
+        { query, limit },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.searchIssues({ query, limit })
+}
+
+export async function linearListIssues(
+  settings: RuntimeLinearSettings,
+  filter?: LinearIssueFilter,
+  limit?: number
+): Promise<LinearIssue[]> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearIssue[]>(
+        target,
+        'linear.listIssues',
+        { filter, limit },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.listIssues({ filter, limit })
+}
+
+export async function linearCreateIssue(
+  settings: RuntimeLinearSettings,
+  args: { teamId: string; title: string; description?: string }
+): Promise<LinearCreateIssueResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCreateIssueResult>(target, 'linear.createIssue', args, {
+        timeoutMs: 30_000
+      })
+    : window.api.linear.createIssue(args)
+}
+
+export async function linearGetIssue(
+  settings: RuntimeLinearSettings,
+  id: string
+): Promise<LinearIssue | null> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearIssue | null>(target, 'linear.getIssue', { id }, { timeoutMs: 30_000 })
+    : window.api.linear.getIssue({ id })
+}
+
+export async function linearUpdateIssue(
+  settings: RuntimeLinearSettings,
+  id: string,
+  updates: LinearIssueUpdate
+): Promise<LinearMutationResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearMutationResult>(
+        target,
+        'linear.updateIssue',
+        { id, updates },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.updateIssue({ id, updates })
+}
+
+export async function linearAddIssueComment(
+  settings: RuntimeLinearSettings,
+  issueId: string,
+  body: string
+): Promise<LinearCommentResult> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCommentResult>(
+        target,
+        'linear.addIssueComment',
+        { issueId, body },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.addIssueComment({ issueId, body })
+}
+
+export async function linearIssueComments(
+  settings: RuntimeLinearSettings,
+  issueId: string
+): Promise<LinearComment[]> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearComment[]>(
+        target,
+        'linear.issueComments',
+        { issueId },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.issueComments({ issueId })
+}
+
+export async function linearListTeams(settings: RuntimeLinearSettings): Promise<LinearTeam[]> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearTeam[]>(target, 'linear.listTeams', undefined, { timeoutMs: 30_000 })
+    : window.api.linear.listTeams()
+}
+
+export async function linearTeamStates(
+  settings: RuntimeLinearSettings,
+  teamId: string
+): Promise<LinearWorkflowState[]> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearWorkflowState[]>(
+        target,
+        'linear.teamStates',
+        { teamId },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.teamStates({ teamId })
+}
+
+export async function linearTeamLabels(
+  settings: RuntimeLinearSettings,
+  teamId: string
+): Promise<LinearLabel[]> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearLabel[]>(target, 'linear.teamLabels', { teamId }, { timeoutMs: 30_000 })
+    : window.api.linear.teamLabels({ teamId })
+}
+
+export async function linearTeamMembers(
+  settings: RuntimeLinearSettings,
+  teamId: string
+): Promise<LinearMember[]> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearMember[]>(
+        target,
+        'linear.teamMembers',
+        { teamId },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.teamMembers({ teamId })
+}
diff --git a/src/renderer/src/runtime/runtime-notes-client.test.ts b/src/renderer/src/runtime/runtime-notes-client.test.ts
new file mode 100644
index 00000000000..ee15a592106
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-notes-client.test.ts
@@ -0,0 +1,228 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  createRuntimeProjectNote,
+  deleteRuntimeProjectNote,
+  linkRuntimeProjectNote,
+  listRuntimeProjectNotes,
+  renameRuntimeProjectNote,
+  resolveRuntimeNotesPanelState,
+  saveRuntimeProjectNote,
+  showRuntimeProjectNote
+} from './runtime-notes-client'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from './runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from './runtime-rpc-client'
+
+const notesList = vi.fn()
+const notesShow = vi.fn()
+const notesCreate = vi.fn()
+const notesSave = vi.fn()
+const notesRename = vi.fn()
+const notesDelete = vi.fn()
+const notesAppend = vi.fn()
+const notesSearch = vi.fn()
+const notesLink = vi.fn()
+const notesPanelState = vi.fn()
+const runtimeCall = vi.fn()
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  notesList.mockReset()
+  notesShow.mockReset()
+  notesCreate.mockReset()
+  notesSave.mockReset()
+  notesRename.mockReset()
+  notesDelete.mockReset()
+  notesAppend.mockReset()
+  notesSearch.mockReset()
+  notesLink.mockReset()
+  notesPanelState.mockReset()
+  runtimeCall.mockReset()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      notes: {
+        list: notesList,
+        show: notesShow,
+        create: notesCreate,
+        save: notesSave,
+        rename: notesRename,
+        delete: notesDelete,
+        append: notesAppend,
+        search: notesSearch,
+        link: notesLink,
+        panelState: notesPanelState
+      },
+      runtime: { call: runtimeCall },
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCall }
+    }
+  })
+})
+
+describe('runtime notes client', () => {
+  it('uses local notes IPC when no remote runtime is active', async () => {
+    notesList.mockResolvedValue({ notes: [], totalCount: 0, truncated: false })
+
+    await listRuntimeProjectNotes(
+      { activeRuntimeEnvironmentId: null },
+      { projectId: 'repo-1', worktreeId: 'wt-1', limit: 100 }
+    )
+
+    expect(notesList).toHaveBeenCalledWith({
+      projectId: 'repo-1',
+      worktreeId: 'wt-1',
+      limit: 100
+    })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes note reads through the active runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { notes: [], totalCount: 0, truncated: false },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    const settings = { activeRuntimeEnvironmentId: 'env-1' }
+
+    await listRuntimeProjectNotes(settings, {
+      projectId: 'repo-1',
+      worktreeId: 'wt-1',
+      limit: 100
+    })
+    runtimeEnvironmentCall.mockResolvedValueOnce({
+      id: 'rpc-2',
+      ok: true,
+      result: { note: { id: 'note-1' }, linkKind: null },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    await showRuntimeProjectNote(settings, {
+      projectId: 'repo-1',
+      worktreeId: 'wt-1',
+      note: 'note-1'
+    })
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'note.list',
+      params: { worktree: 'wt-1', limit: 100 },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'note.show',
+      params: { worktree: 'wt-1', note: 'note-1' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes note mutations through the active runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { note: { id: 'note-1' }, linkKind: 'active' },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+    const settings = { activeRuntimeEnvironmentId: 'env-1' }
+    const base = { projectId: 'repo-1', worktreeId: 'wt-1' }
+
+    await createRuntimeProjectNote(settings, { ...base, title: 'Plan', bodyMarkdown: 'body' })
+    await saveRuntimeProjectNote(settings, {
+      ...base,
+      note: 'note-1',
+      title: 'Plan',
+      bodyMarkdown: 'updated',
+      revision: 3,
+      makeActive: true
+    })
+    await renameRuntimeProjectNote(settings, { ...base, note: 'note-1', title: 'Renamed' })
+    await deleteRuntimeProjectNote(settings, { ...base, note: 'note-1' })
+    await linkRuntimeProjectNote(settings, { ...base, note: 'note-1', kind: 'active' })
+
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
+      selector: 'env-1',
+      method: 'note.create',
+      params: {
+        worktree: 'wt-1',
+        title: 'Plan',
+        bodyMarkdown: 'body',
+        makeActive: undefined,
+        createdBySessionId: undefined
+      },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
+      selector: 'env-1',
+      method: 'note.save',
+      params: {
+        worktree: 'wt-1',
+        note: 'note-1',
+        title: 'Plan',
+        bodyMarkdown: 'updated',
+        revision: 3,
+        makeActive: true,
+        updatedBySessionId: undefined
+      },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
+      selector: 'env-1',
+      method: 'note.rename',
+      params: {
+        worktree: 'wt-1',
+        note: 'note-1',
+        title: 'Renamed',
+        updatedBySessionId: undefined
+      },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(4, {
+      selector: 'env-1',
+      method: 'note.delete',
+      params: { worktree: 'wt-1', note: 'note-1' },
+      timeoutMs: 15_000
+    })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(5, {
+      selector: 'env-1',
+      method: 'note.link',
+      params: { worktree: 'wt-1', note: 'note-1', kind: 'active' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('routes panel state through the active runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { state: 'emptyDraft', projectId: 'repo-1', worktreeId: 'wt-1' },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await resolveRuntimeNotesPanelState(
+      { activeRuntimeEnvironmentId: 'env-1' },
+      { projectId: 'repo-1', worktreeId: 'wt-1' }
+    )
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'note.panelState',
+      params: { worktree: 'wt-1' },
+      timeoutMs: 15_000
+    })
+  })
+
+  it('returns noProject for remote panel state without a project/worktree', async () => {
+    await expect(
+      resolveRuntimeNotesPanelState({ activeRuntimeEnvironmentId: 'env-1' }, {})
+    ).resolves.toEqual({ state: 'noProject' })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-notes-client.ts b/src/renderer/src/runtime/runtime-notes-client.ts
new file mode 100644
index 00000000000..669d9d8681c
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-notes-client.ts
@@ -0,0 +1,229 @@
+import type { GlobalSettings } from '../../../shared/types'
+import type {
+  NoteAppendArgs,
+  NoteCreateArgs,
+  NoteDeleteArgs,
+  NoteDeleteResult,
+  NoteLink,
+  NoteLinkArgs,
+  NoteListArgs,
+  NoteListResult,
+  NoteMutationResult,
+  NoteRenameArgs,
+  NoteSaveArgs,
+  NoteSearchArgs,
+  NoteShowArgs,
+  NoteShowResult,
+  NotesPanelOpenState,
+  NotesPanelStateArgs
+} from '../../../shared/notes-types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
+
+type RuntimeNotesSettings = Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+
+function requireWorktreeId(worktreeId: string | null | undefined): string {
+  if (!worktreeId?.trim()) {
+    throw new Error('Project notes require an active worktree on remote runtime servers.')
+  }
+  return worktreeId
+}
+
+function noteTarget(settings: RuntimeNotesSettings): ReturnType<typeof getActiveRuntimeTarget> {
+  return getActiveRuntimeTarget(settings)
+}
+
+export async function listRuntimeProjectNotes(
+  settings: RuntimeNotesSettings,
+  args: NoteListArgs
+): Promise<NoteListResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.list(args)
+  }
+  return callRuntimeRpc<NoteListResult>(
+    target,
+    'note.list',
+    { worktree: requireWorktreeId(args.worktreeId), limit: args.limit },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function showRuntimeProjectNote(
+  settings: RuntimeNotesSettings,
+  args: NoteShowArgs
+): Promise<NoteShowResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.show(args)
+  }
+  return callRuntimeRpc<NoteShowResult>(
+    target,
+    'note.show',
+    { worktree: requireWorktreeId(args.worktreeId), note: args.note },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function createRuntimeProjectNote(
+  settings: RuntimeNotesSettings,
+  args: NoteCreateArgs
+): Promise<NoteMutationResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.create(args)
+  }
+  return callRuntimeRpc<NoteMutationResult>(
+    target,
+    'note.create',
+    {
+      worktree: requireWorktreeId(args.worktreeId),
+      title: args.title,
+      bodyMarkdown: args.bodyMarkdown,
+      makeActive: args.makeActive,
+      createdBySessionId: args.createdBySessionId
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function saveRuntimeProjectNote(
+  settings: RuntimeNotesSettings,
+  args: NoteSaveArgs
+): Promise<NoteMutationResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.save(args)
+  }
+  return callRuntimeRpc<NoteMutationResult>(
+    target,
+    'note.save',
+    {
+      worktree: requireWorktreeId(args.worktreeId),
+      note: args.note,
+      title: args.title,
+      bodyMarkdown: args.bodyMarkdown,
+      revision: args.revision,
+      makeActive: args.makeActive,
+      updatedBySessionId: args.updatedBySessionId
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function renameRuntimeProjectNote(
+  settings: RuntimeNotesSettings,
+  args: NoteRenameArgs
+): Promise<NoteMutationResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.rename(args)
+  }
+  return callRuntimeRpc<NoteMutationResult>(
+    target,
+    'note.rename',
+    {
+      worktree: requireWorktreeId(args.worktreeId),
+      note: args.note,
+      title: args.title,
+      updatedBySessionId: args.updatedBySessionId
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function deleteRuntimeProjectNote(
+  settings: RuntimeNotesSettings,
+  args: NoteDeleteArgs
+): Promise<NoteDeleteResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.delete(args)
+  }
+  return callRuntimeRpc<NoteDeleteResult>(
+    target,
+    'note.delete',
+    { worktree: requireWorktreeId(args.worktreeId), note: args.note },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function appendRuntimeProjectNote(
+  settings: RuntimeNotesSettings,
+  args: NoteAppendArgs
+): Promise<NoteMutationResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.append(args)
+  }
+  return callRuntimeRpc<NoteMutationResult>(
+    target,
+    'note.append',
+    {
+      worktree: requireWorktreeId(args.worktreeId),
+      note: args.note,
+      bodyMarkdown: args.bodyMarkdown,
+      makeActive: args.makeActive,
+      updatedBySessionId: args.updatedBySessionId
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function searchRuntimeProjectNotes(
+  settings: RuntimeNotesSettings,
+  args: NoteSearchArgs
+): Promise<NoteListResult> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.search(args)
+  }
+  return callRuntimeRpc<NoteListResult>(
+    target,
+    'note.search',
+    {
+      worktree: requireWorktreeId(args.worktreeId),
+      query: args.query,
+      limit: args.limit
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function linkRuntimeProjectNote(
+  settings: RuntimeNotesSettings,
+  args: NoteLinkArgs
+): Promise<NoteLink> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.link(args)
+  }
+  return callRuntimeRpc<NoteLink>(
+    target,
+    'note.link',
+    {
+      worktree: requireWorktreeId(args.worktreeId),
+      note: args.note,
+      kind: args.kind
+    },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function resolveRuntimeNotesPanelState(
+  settings: RuntimeNotesSettings,
+  args: NotesPanelStateArgs
+): Promise<NotesPanelOpenState> {
+  const target = noteTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.notes.panelState(args)
+  }
+  if (!args.projectId && !args.worktreeId) {
+    return { state: 'noProject' }
+  }
+  return callRuntimeRpc<NotesPanelOpenState>(
+    target,
+    'note.panelState',
+    { worktree: requireWorktreeId(args.worktreeId) },
+    { timeoutMs: 15_000 }
+  )
+}
diff --git a/src/renderer/src/runtime/runtime-protocol-compat.ts b/src/renderer/src/runtime/runtime-protocol-compat.ts
new file mode 100644
index 00000000000..3459c01b834
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-protocol-compat.ts
@@ -0,0 +1,19 @@
+import { describeRuntimeCompatBlock, evaluateRuntimeCompat } from '../../../shared/protocol-compat'
+import {
+  MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from '../../../shared/protocol-version'
+import type { RuntimeStatus } from '../../../shared/runtime-types'
+
+export function assertRuntimeStatusCompatible(status: RuntimeStatus): void {
+  const verdict = evaluateRuntimeCompat({
+    clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+    minCompatibleServerProtocolVersion: MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+    serverProtocolVersion: status.runtimeProtocolVersion ?? status.protocolVersion,
+    serverMinCompatibleClientProtocolVersion:
+      status.minCompatibleRuntimeClientVersion ?? status.minCompatibleMobileVersion
+  })
+  if (verdict.kind === 'blocked') {
+    throw new Error(describeRuntimeCompatBlock(verdict))
+  }
+}
diff --git a/src/renderer/src/runtime/runtime-repo-client.ts b/src/renderer/src/runtime/runtime-repo-client.ts
new file mode 100644
index 00000000000..bdd596c5da7
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-repo-client.ts
@@ -0,0 +1,42 @@
+import type { GlobalSettings } from '../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
+
+export type RuntimeRepoBaseRefDefault = {
+  defaultBaseRef: string | null
+  remoteCount: number
+}
+
+export async function getRuntimeRepoBaseRefDefault(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  repoId: string
+): Promise<RuntimeRepoBaseRefDefault> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind !== 'environment') {
+    return window.api.repos.getBaseRefDefault({ repoId })
+  }
+  return callRuntimeRpc<RuntimeRepoBaseRefDefault>(
+    target,
+    'repo.baseRefDefault',
+    { repo: repoId },
+    { timeoutMs: 15_000 }
+  )
+}
+
+export async function searchRuntimeRepoBaseRefs(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  repoId: string,
+  query: string,
+  limit: number
+): Promise<string[]> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind !== 'environment') {
+    return window.api.repos.searchBaseRefs({ repoId, query, limit })
+  }
+  const result = await callRuntimeRpc<{ refs: string[]; truncated: boolean }>(
+    target,
+    'repo.searchRefs',
+    { repo: repoId, query, limit },
+    { timeoutMs: 15_000 }
+  )
+  return result.refs
+}
diff --git a/src/renderer/src/runtime/runtime-rpc-client.test.ts b/src/renderer/src/runtime/runtime-rpc-client.test.ts
new file mode 100644
index 00000000000..21eec50c6c0
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-rpc-client.test.ts
@@ -0,0 +1,155 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  callRuntimeRpc,
+  clearRuntimeCompatibilityCacheForTests,
+  getActiveRuntimeTarget,
+  RuntimeRpcCallError,
+  unwrapRuntimeRpcResult
+} from './runtime-rpc-client'
+import {
+  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from '../../../shared/protocol-version'
+
+const runtimeCall = vi.fn()
+const runtimeEnvironmentCall = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  runtimeCall.mockReset()
+  runtimeEnvironmentCall.mockReset()
+  vi.stubGlobal('window', {
+    api: {
+      runtime: { call: runtimeCall },
+      runtimeEnvironments: { call: runtimeEnvironmentCall }
+    }
+  })
+})
+
+describe('runtime RPC client routing', () => {
+  it('uses the local runtime when no active environment is selected', () => {
+    expect(getActiveRuntimeTarget(null)).toEqual({ kind: 'local' })
+    expect(getActiveRuntimeTarget({ activeRuntimeEnvironmentId: null })).toEqual({ kind: 'local' })
+    expect(getActiveRuntimeTarget({ activeRuntimeEnvironmentId: '   ' })).toEqual({ kind: 'local' })
+  })
+
+  it('uses the active saved environment when one is selected', () => {
+    expect(getActiveRuntimeTarget({ activeRuntimeEnvironmentId: 'env-1' })).toEqual({
+      kind: 'environment',
+      environmentId: 'env-1'
+    })
+  })
+
+  it('routes local runtime calls through window.api.runtime.call', async () => {
+    runtimeCall.mockResolvedValue({
+      id: 'local',
+      ok: true,
+      result: [{ id: 'repo-1' }],
+      _meta: { runtimeId: 'local-runtime' }
+    })
+
+    await expect(callRuntimeRpc({ kind: 'local' }, 'repo.list')).resolves.toEqual([
+      { id: 'repo-1' }
+    ])
+    expect(runtimeCall).toHaveBeenCalledWith({ method: 'repo.list', params: undefined })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('routes remote runtime calls through window.api.runtimeEnvironments.call', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'remote',
+      ok: true,
+      result: { graphStatus: 'ready' },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await expect(
+      callRuntimeRpc({ kind: 'environment', environmentId: 'env-1' }, 'status.get', undefined, {
+        timeoutMs: 50
+      })
+    ).resolves.toEqual({ graphStatus: 'ready' })
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'status.get',
+      params: undefined,
+      timeoutMs: 50
+    })
+    expect(runtimeCall).not.toHaveBeenCalled()
+  })
+
+  it('preflights remote runtime compatibility before non-status calls', async () => {
+    runtimeEnvironmentCall.mockImplementation(({ method }: { method: string }) => {
+      const result =
+        method === 'status.get'
+          ? {
+              runtimeId: 'remote-runtime',
+              graphStatus: 'ready',
+              runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+              minCompatibleRuntimeClientVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
+            }
+          : { repos: [{ id: 'repo-1' }] }
+      return Promise.resolve({
+        id: method,
+        ok: true,
+        result,
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+    })
+
+    await expect(
+      callRuntimeRpc({ kind: 'environment', environmentId: 'env-compat' }, 'repo.list')
+    ).resolves.toEqual({ repos: [{ id: 'repo-1' }] })
+
+    expect(runtimeEnvironmentCall.mock.calls.map((call) => call[0].method)).toEqual([
+      'status.get',
+      'repo.list'
+    ])
+  })
+
+  it('caches successful remote compatibility checks per environment', async () => {
+    runtimeEnvironmentCall.mockImplementation(({ method }: { method: string }) => {
+      const result =
+        method === 'status.get'
+          ? {
+              runtimeId: 'remote-runtime',
+              graphStatus: 'ready',
+              runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+              minCompatibleRuntimeClientVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
+            }
+          : { ok: true }
+      return Promise.resolve({
+        id: method,
+        ok: true,
+        result,
+        _meta: { runtimeId: 'remote-runtime' }
+      })
+    })
+
+    await callRuntimeRpc({ kind: 'environment', environmentId: 'env-cache' }, 'repo.list')
+    await callRuntimeRpc({ kind: 'environment', environmentId: 'env-cache' }, 'worktree.list')
+
+    expect(runtimeEnvironmentCall.mock.calls.map((call) => call[0].method)).toEqual([
+      'status.get',
+      'repo.list',
+      'worktree.list'
+    ])
+  })
+
+  it('throws structured runtime RPC failures', () => {
+    const failure = {
+      id: 'rpc-1',
+      ok: false as const,
+      error: { code: 'method_not_found', message: 'Unknown method: nope' },
+      _meta: { runtimeId: 'runtime-1' }
+    }
+
+    expect(() => unwrapRuntimeRpcResult(failure)).toThrow(RuntimeRpcCallError)
+    try {
+      unwrapRuntimeRpcResult(failure)
+    } catch (error) {
+      expect(error).toBeInstanceOf(RuntimeRpcCallError)
+      expect((error as RuntimeRpcCallError).code).toBe('method_not_found')
+      expect((error as RuntimeRpcCallError).response).toBe(failure)
+    }
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-rpc-client.ts b/src/renderer/src/runtime/runtime-rpc-client.ts
new file mode 100644
index 00000000000..38540f694a4
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-rpc-client.ts
@@ -0,0 +1,108 @@
+import type { GlobalSettings } from '../../../shared/types'
+import type { RuntimeRpcFailure, RuntimeRpcResponse } from '../../../shared/runtime-rpc-envelope'
+import type { RuntimeStatus } from '../../../shared/runtime-types'
+import { assertRuntimeStatusCompatible } from './runtime-protocol-compat'
+
+export type RuntimeClientTarget = { kind: 'local' } | { kind: 'environment'; environmentId: string }
+
+const compatibleRuntimeEnvironments = new Map<string, Promise<void>>()
+
+export class RuntimeRpcCallError extends Error {
+  readonly code: string
+  readonly response: RuntimeRpcFailure
+
+  constructor(response: RuntimeRpcFailure) {
+    super(response.error.message)
+    this.name = 'RuntimeRpcCallError'
+    this.code = response.error.code
+    this.response = response
+  }
+}
+
+export function getActiveRuntimeTarget(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+): RuntimeClientTarget {
+  const environmentId = settings?.activeRuntimeEnvironmentId?.trim()
+  if (!environmentId) {
+    return { kind: 'local' }
+  }
+  return { kind: 'environment', environmentId }
+}
+
+export function settingsForRuntimeOwner(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  runtimeEnvironmentId: string | null | undefined
+): Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined {
+  const ownerId = runtimeEnvironmentId?.trim()
+  return ownerId ? { activeRuntimeEnvironmentId: ownerId } : settings
+}
+
+export async function callRuntimeRpc<TResult>(
+  target: RuntimeClientTarget,
+  method: string,
+  params?: unknown,
+  options: { timeoutMs?: number } = {}
+): Promise<TResult> {
+  if (target.kind === 'environment' && method !== 'status.get') {
+    await ensureRuntimeEnvironmentCompatible(target.environmentId, options.timeoutMs)
+  }
+  const response =
+    target.kind === 'local'
+      ? await window.api.runtime.call({ method, params })
+      : await window.api.runtimeEnvironments.call({
+          selector: target.environmentId,
+          method,
+          params,
+          timeoutMs: options.timeoutMs
+        })
+  return unwrapRuntimeRpcResult<TResult>(response as RuntimeRpcResponse<TResult>)
+}
+
+async function ensureRuntimeEnvironmentCompatible(
+  environmentId: string,
+  timeoutMs?: number
+): Promise<void> {
+  const cached = compatibleRuntimeEnvironments.get(environmentId)
+  if (cached) {
+    await cached
+    return
+  }
+  const check = (async () => {
+    const response = await window.api.runtimeEnvironments.call({
+      selector: environmentId,
+      method: 'status.get',
+      timeoutMs
+    })
+    const status = unwrapRuntimeRpcResult<RuntimeStatus>(
+      response as RuntimeRpcResponse<RuntimeStatus>
+    )
+    assertRuntimeStatusCompatible(status)
+  })()
+  compatibleRuntimeEnvironments.set(environmentId, check)
+  try {
+    await check
+  } catch (error) {
+    compatibleRuntimeEnvironments.delete(environmentId)
+    throw error
+  }
+}
+
+export function clearRuntimeCompatibilityCache(environmentId?: string | null): void {
+  const trimmed = environmentId?.trim()
+  if (trimmed) {
+    compatibleRuntimeEnvironments.delete(trimmed)
+    return
+  }
+  compatibleRuntimeEnvironments.clear()
+}
+
+export function clearRuntimeCompatibilityCacheForTests(): void {
+  clearRuntimeCompatibilityCache()
+}
+
+export function unwrapRuntimeRpcResult<TResult>(response: RuntimeRpcResponse<TResult>): TResult {
+  if (response.ok === false) {
+    throw new RuntimeRpcCallError(response)
+  }
+  return response.result
+}
diff --git a/src/renderer/src/runtime/runtime-terminal-inspection.test.ts b/src/renderer/src/runtime/runtime-terminal-inspection.test.ts
new file mode 100644
index 00000000000..222cb9e308b
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-terminal-inspection.test.ts
@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { inspectRuntimeTerminalProcess, sendRuntimePtyInput } from './runtime-terminal-inspection'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from './runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from './runtime-rpc-client'
+
+describe('runtime terminal owner routing', () => {
+  const runtimeCall = vi.fn()
+  const runtimeTransportCall = vi.fn()
+  const localWrite = vi.fn()
+  const localForeground = vi.fn()
+  const localHasChildren = vi.fn()
+
+  beforeEach(() => {
+    clearRuntimeCompatibilityCacheForTests()
+    vi.clearAllMocks()
+    runtimeCall.mockResolvedValue({
+      ok: true,
+      result: { process: { foregroundProcess: 'bash', hasChildProcesses: true } },
+      _meta: { runtimeId: 'runtime-1' }
+    })
+    runtimeTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+      return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeCall(args)
+    })
+    vi.stubGlobal('window', {
+      api: {
+        runtimeEnvironments: { call: runtimeTransportCall },
+        pty: {
+          write: localWrite,
+          getForegroundProcess: localForeground,
+          hasChildProcesses: localHasChildren
+        }
+      }
+    })
+  })
+
+  it('sends input through the PTY owning environment instead of the active one', async () => {
+    expect(
+      sendRuntimePtyInput({ activeRuntimeEnvironmentId: 'env-2' }, 'remote:env-1@@terminal-1', 'x')
+    ).toBe(true)
+
+    await vi.waitFor(() => {
+      expect(runtimeCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'terminal.send',
+        params: { terminal: 'terminal-1', text: 'x' },
+        timeoutMs: 15_000
+      })
+    })
+    expect(localWrite).not.toHaveBeenCalled()
+  })
+
+  it('inspects the PTY owning environment instead of the active one', async () => {
+    await expect(
+      inspectRuntimeTerminalProcess(
+        { activeRuntimeEnvironmentId: 'env-2' },
+        'remote:env-1@@terminal-1'
+      )
+    ).resolves.toEqual({ foregroundProcess: 'bash', hasChildProcesses: true })
+
+    expect(runtimeCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'terminal.inspectProcess',
+      params: { terminal: 'terminal-1' },
+      timeoutMs: 15_000
+    })
+    expect(localForeground).not.toHaveBeenCalled()
+    expect(localHasChildren).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-terminal-inspection.ts b/src/renderer/src/runtime/runtime-terminal-inspection.ts
new file mode 100644
index 00000000000..9c5c1f2f73f
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-terminal-inspection.ts
@@ -0,0 +1,62 @@
+import type { GlobalSettings } from '../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
+import {
+  getRemoteRuntimePtyEnvironmentId,
+  getRemoteRuntimeTerminalHandle
+} from './runtime-terminal-stream'
+
+export type RuntimeTerminalProcessInspection = {
+  foregroundProcess: string | null
+  hasChildProcesses: boolean
+}
+
+const REMOTE_PTY_ID_PREFIX = 'remote:'
+
+export function isRemoteRuntimePtyId(ptyId: string): boolean {
+  return ptyId.startsWith(REMOTE_PTY_ID_PREFIX)
+}
+
+export async function inspectRuntimeTerminalProcess(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  ptyId: string
+): Promise<RuntimeTerminalProcessInspection> {
+  const ownerEnvironmentId = getRemoteRuntimePtyEnvironmentId(ptyId)
+  const target = ownerEnvironmentId
+    ? ({ kind: 'environment', environmentId: ownerEnvironmentId } as const)
+    : getActiveRuntimeTarget(settings)
+  const terminal = getRemoteRuntimeTerminalHandle(ptyId)
+  if (target.kind !== 'environment' || !terminal) {
+    const [foregroundProcess, hasChildProcesses] = await Promise.all([
+      window.api.pty.getForegroundProcess(ptyId),
+      window.api.pty.hasChildProcesses(ptyId)
+    ])
+    return { foregroundProcess, hasChildProcesses }
+  }
+
+  const result = await callRuntimeRpc<{ process: RuntimeTerminalProcessInspection }>(
+    target,
+    'terminal.inspectProcess',
+    { terminal },
+    { timeoutMs: 15_000 }
+  )
+  return result.process
+}
+
+export function sendRuntimePtyInput(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  ptyId: string,
+  data: string
+): boolean {
+  const ownerEnvironmentId = getRemoteRuntimePtyEnvironmentId(ptyId)
+  const target = ownerEnvironmentId
+    ? ({ kind: 'environment', environmentId: ownerEnvironmentId } as const)
+    : getActiveRuntimeTarget(settings)
+  const terminal = getRemoteRuntimeTerminalHandle(ptyId)
+  if (target.kind !== 'environment' || !terminal) {
+    window.api.pty.write(ptyId, data)
+    return true
+  }
+
+  void callRuntimeRpc(target, 'terminal.send', { terminal, text: data }, { timeoutMs: 15_000 })
+  return true
+}
diff --git a/src/renderer/src/runtime/runtime-terminal-stream.test.ts b/src/renderer/src/runtime/runtime-terminal-stream.test.ts
new file mode 100644
index 00000000000..d08b413af74
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-terminal-stream.test.ts
@@ -0,0 +1,120 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamJson,
+  encodeTerminalStreamFrame,
+  encodeTerminalStreamText
+} from '../../../shared/terminal-stream-protocol'
+import { resetRemoteRuntimeTerminalMultiplexersForTests } from './remote-runtime-terminal-multiplexer'
+import {
+  getRemoteRuntimePtyEnvironmentId,
+  getRemoteRuntimeTerminalHandle,
+  subscribeToRuntimeTerminalData,
+  toRemoteRuntimePtyId
+} from './runtime-terminal-stream'
+
+describe('remote runtime terminal ids', () => {
+  it('encodes and decodes the owning runtime environment', () => {
+    const ptyId = toRemoteRuntimePtyId('terminal:one', 'env-1')
+
+    expect(ptyId).toBe('remote:env-1@@terminal%3Aone')
+    expect(getRemoteRuntimePtyEnvironmentId(ptyId)).toBe('env-1')
+    expect(getRemoteRuntimeTerminalHandle(ptyId)).toBe('terminal:one')
+  })
+
+  it('keeps legacy remote ids readable', () => {
+    expect(getRemoteRuntimePtyEnvironmentId('remote:terminal-1')).toBeNull()
+    expect(getRemoteRuntimeTerminalHandle('remote:terminal-1')).toBe('terminal-1')
+  })
+})
+
+describe('remote runtime terminal data subscriptions', () => {
+  const runtimeSubscribe = vi.fn()
+  const sendBinary = vi.fn()
+  const unsubscribe = vi.fn()
+  let callbacks: {
+    onResponse: (response: unknown) => void
+    onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+  } | null = null
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetRemoteRuntimeTerminalMultiplexersForTests()
+    callbacks = null
+    runtimeSubscribe.mockImplementation(async (_args: unknown, nextCallbacks: typeof callbacks) => {
+      callbacks = nextCallbacks
+      queueMicrotask(() =>
+        callbacks?.onResponse({
+          ok: true,
+          result: { type: 'ready' }
+        })
+      )
+      return { unsubscribe, sendBinary }
+    })
+    vi.stubGlobal('window', {
+      api: {
+        runtimeEnvironments: {
+          subscribe: runtimeSubscribe
+        }
+      }
+    })
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('uses the shared terminal multiplexer for sidecar data watchers', async () => {
+    const watcher = vi.fn()
+
+    const dispose = await subscribeToRuntimeTerminalData(
+      { activeRuntimeEnvironmentId: 'env-fallback' },
+      'remote:env-1@@terminal-1',
+      'watcher-1',
+      watcher
+    )
+
+    expect(runtimeSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'terminal.multiplex'
+      }),
+      expect.any(Object)
+    )
+    await vi.waitFor(() => expect(sendBinary).toHaveBeenCalled())
+    const subscribeFrame = decodeTerminalStreamFrame(sendBinary.mock.calls[0][0])
+    expect(subscribeFrame?.opcode).toBe(TerminalStreamOpcode.Subscribe)
+    const subscribePayload =
+      subscribeFrame && decodeTerminalStreamJson<{ streamId: number }>(subscribeFrame.payload)
+    expect(subscribePayload?.streamId).toEqual(expect.any(Number))
+
+    callbacks?.onBinary?.(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Output,
+        streamId: subscribePayload!.streamId,
+        seq: 1,
+        payload: encodeTerminalStreamText('live')
+      })
+    )
+
+    expect(watcher).toHaveBeenCalledWith('live')
+    dispose()
+    expect(unsubscribe).toHaveBeenCalled()
+  })
+
+  it('rejects remote terminal subscriptions when the multiplex connection fails', async () => {
+    runtimeSubscribe.mockRejectedValueOnce(new Error('offline'))
+
+    await expect(
+      subscribeToRuntimeTerminalData(
+        { activeRuntimeEnvironmentId: 'env-fallback' },
+        'remote:env-1@@terminal-1',
+        'watcher-1',
+        vi.fn()
+      )
+    ).rejects.toThrow('offline')
+
+    expect(sendBinary).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/runtime/runtime-terminal-stream.ts b/src/renderer/src/runtime/runtime-terminal-stream.ts
new file mode 100644
index 00000000000..d5e747e3344
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-terminal-stream.ts
@@ -0,0 +1,163 @@
+import {
+  TerminalStreamOpcode,
+  decodeTerminalStreamFrame,
+  decodeTerminalStreamText
+} from '../../../shared/terminal-stream-protocol'
+import type { GlobalSettings } from '../../../shared/types'
+import { RuntimeRpcCallError, getActiveRuntimeTarget } from './runtime-rpc-client'
+import { getRemoteRuntimeTerminalMultiplexer } from './remote-runtime-terminal-multiplexer'
+
+const REMOTE_PTY_ID_PREFIX = 'remote:'
+const REMOTE_PTY_OWNER_SEPARATOR = '@@'
+
+export type RemoteRuntimePtyIdParts = {
+  environmentId: string | null
+  handle: string
+}
+
+export type RuntimeTerminalSubscribeEvent =
+  | {
+      type: 'scrollback' | 'subscribed'
+      streamId?: number | null
+      lines?: string[]
+      truncated?: boolean
+      serialized?: string
+      cols?: number
+      rows?: number
+    }
+  | { type: 'data'; chunk: string }
+  | { type: 'end' }
+  | { type: string; [key: string]: unknown }
+
+export function toRemoteRuntimePtyId(handle: string, environmentId?: string | null): string {
+  const owner = environmentId?.trim()
+  if (!owner) {
+    return `${REMOTE_PTY_ID_PREFIX}${handle}`
+  }
+  return `${REMOTE_PTY_ID_PREFIX}${encodeURIComponent(owner)}${REMOTE_PTY_OWNER_SEPARATOR}${encodeURIComponent(handle)}`
+}
+
+export function parseRemoteRuntimePtyId(ptyId: string): RemoteRuntimePtyIdParts | null {
+  if (!ptyId.startsWith(REMOTE_PTY_ID_PREFIX)) {
+    return null
+  }
+  const rest = ptyId.slice(REMOTE_PTY_ID_PREFIX.length)
+  const separatorIndex = rest.indexOf(REMOTE_PTY_OWNER_SEPARATOR)
+  if (separatorIndex === -1) {
+    return { environmentId: null, handle: rest }
+  }
+  return {
+    environmentId: decodeURIComponent(rest.slice(0, separatorIndex)),
+    handle: decodeURIComponent(rest.slice(separatorIndex + REMOTE_PTY_OWNER_SEPARATOR.length))
+  }
+}
+
+export function getRemoteRuntimeTerminalHandle(ptyId: string): string | null {
+  return parseRemoteRuntimePtyId(ptyId)?.handle ?? null
+}
+
+export function getRemoteRuntimePtyEnvironmentId(ptyId: string): string | null {
+  return parseRemoteRuntimePtyId(ptyId)?.environmentId ?? null
+}
+
+export function isRuntimeTerminalScrollbackEvent(
+  event: RuntimeTerminalSubscribeEvent
+): event is Extract<RuntimeTerminalSubscribeEvent, { type: 'scrollback' | 'subscribed' }> {
+  return event.type === 'scrollback' || event.type === 'subscribed'
+}
+
+export function isRuntimeTerminalDataEvent(
+  event: RuntimeTerminalSubscribeEvent
+): event is Extract<RuntimeTerminalSubscribeEvent, { type: 'data' }> {
+  return event.type === 'data' && typeof (event as { chunk?: unknown }).chunk === 'string'
+}
+
+export function runtimeTerminalErrorMessage(error: unknown): string {
+  if (error instanceof RuntimeRpcCallError) {
+    return error.message
+  }
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function readRuntimeTerminalScrollback(event: {
+  serialized?: string
+  lines?: string[]
+}): string | null {
+  if (event.serialized) {
+    return event.serialized
+  }
+  if (event.lines && event.lines.length > 0) {
+    return `${event.lines.join('\r\n')}\r\n`
+  }
+  return null
+}
+
+function concatBytes(chunks: Uint8Array<ArrayBufferLike>[]): Uint8Array<ArrayBufferLike> {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0)
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+export function createRuntimeTerminalBinaryReader(callbacks: {
+  onData: (data: string) => void
+  onSnapshot: (data: string) => void
+  onEnd?: () => void
+}): (bytes: Uint8Array<ArrayBufferLike>) => void {
+  let snapshotChunks: Uint8Array<ArrayBufferLike>[] = []
+
+  return (bytes) => {
+    const frame = decodeTerminalStreamFrame(bytes)
+    if (!frame) {
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.Output) {
+      callbacks.onData(decodeTerminalStreamText(frame.payload))
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.SnapshotStart) {
+      snapshotChunks = []
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.SnapshotChunk) {
+      snapshotChunks.push(frame.payload)
+      return
+    }
+    if (frame.opcode === TerminalStreamOpcode.SnapshotEnd) {
+      callbacks.onSnapshot(decodeTerminalStreamText(concatBytes(snapshotChunks)))
+      snapshotChunks = []
+      callbacks.onEnd?.()
+    }
+  }
+}
+
+export async function subscribeToRuntimeTerminalData(
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  ptyId: string,
+  clientId: string,
+  watcher: (data: string) => void
+): Promise<() => void> {
+  const terminal = getRemoteRuntimeTerminalHandle(ptyId)
+  const ownerEnvironmentId = getRemoteRuntimePtyEnvironmentId(ptyId)
+  const target = ownerEnvironmentId
+    ? ({ kind: 'environment', environmentId: ownerEnvironmentId } as const)
+    : getActiveRuntimeTarget(settings)
+  if (target.kind !== 'environment' || !terminal) {
+    return () => {}
+  }
+
+  const stream = await getRemoteRuntimeTerminalMultiplexer(target.environmentId).subscribeTerminal({
+    terminal,
+    client: { id: clientId, type: 'desktop' },
+    callbacks: {
+      onData: watcher,
+      onSnapshot: watcher
+    }
+  })
+
+  return () => stream.close()
+}
diff --git a/src/renderer/src/store/slices/browser.test.ts b/src/renderer/src/store/slices/browser.test.ts
index f29297d19a7..3b22bb062c7 100644
--- a/src/renderer/src/store/slices/browser.test.ts
+++ b/src/renderer/src/store/slices/browser.test.ts
@@ -1,867 +1,415 @@
-/* eslint-disable max-lines --
- * Why: this slice test keeps closely related browser-slice scenarios
- * (create/close, reopen, hydrate, shutdown) in one file so the shared
- * webview-registry mock setup stays consistent across behaviors.
- */
+/* eslint-disable max-lines -- Why: browser slice behavior shares one mocked store harness; splitting only the tests would duplicate more setup than it saves. */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { create } from 'zustand'
+import { createBrowserSlice } from './browser'
+import type { AppState } from '../types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
 
-vi.mock('../../components/browser-pane/webview-registry', () => ({
-  destroyPersistentWebview: vi.fn()
-}))
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
 
-import { createTestStore, makeTabGroup, makeWorktree, seedStore } from './store-test-helpers'
-import { destroyPersistentWebview } from '../../components/browser-pane/webview-registry'
+const mockApi = {
+  browser: {
+    sessionListProfiles: vi.fn().mockResolvedValue([]),
+    sessionCreateProfile: vi.fn().mockResolvedValue(null),
+    sessionDeleteProfile: vi.fn().mockResolvedValue(false),
+    sessionImportCookies: vi.fn().mockResolvedValue({ ok: false, reason: 'canceled' }),
+    sessionDetectBrowsers: vi.fn().mockResolvedValue([]),
+    sessionImportFromBrowser: vi.fn().mockResolvedValue({ ok: false, reason: 'canceled' }),
+    sessionClearDefaultCookies: vi.fn().mockResolvedValue(false),
+    notifyActiveTabChanged: vi.fn().mockResolvedValue(undefined)
+  },
+  runtimeEnvironments: {
+    call: runtimeEnvironmentTransportCall
+  }
+}
 
-describe('browser slice', () => {
-  it('places a new tab in the target group when targetGroupId is provided', () => {
-    const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'terminal',
-      worktreesByRepo: {
-        repo1: [makeWorktree({ id: worktreeId, repoId: 'repo1', path: '/tmp/wt-1' })]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [
-          makeTabGroup({ id: 'terminal-group', worktreeId, activeTabId: null, tabOrder: [] }),
-          makeTabGroup({ id: 'browser-group', worktreeId, activeTabId: null, tabOrder: [] })
-        ]
-      },
-      activeGroupIdByWorktree: { [worktreeId]: 'terminal-group' },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
+// @ts-expect-error test window mock
+globalThis.window = { api: mockApi }
 
-    const created = store.getState().createBrowserTab(worktreeId, 'https://example.com', {
-      title: 'Example',
-      targetGroupId: 'browser-group'
-    })
+function createTestStore() {
+  return create<AppState>()(
+    (...a) =>
+      ({
+        settings: { activeRuntimeEnvironmentId: null } as AppState['settings'],
+        unifiedTabsByWorktree: {},
+        tabBarOrderByWorktree: {},
+        tabsByWorktree: {},
+        openFiles: [],
+        activeTabType: 'terminal',
+        activeTabTypeByWorktree: {},
+        worktreesByRepo: {},
+        createUnifiedTab: vi.fn(),
+        closeUnifiedTab: vi.fn(),
+        activateTab: vi.fn(),
+        setTabLabel: vi.fn(),
+        ...createBrowserSlice(...a)
+      }) as unknown as AppState
+  )
+}
 
-    const unifiedTab = (store.getState().unifiedTabsByWorktree[worktreeId] ?? []).find(
-      (t) => t.contentType === 'browser' && t.entityId === created.id
-    )
-    expect(unifiedTab?.groupId).toBe('browser-group')
-  })
+function settingsWithRuntime(id: string): AppState['settings'] {
+  return { activeRuntimeEnvironmentId: id } as AppState['settings']
+}
 
-  it('falls back to active group when targetGroupId is not provided', () => {
-    const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'terminal',
-      worktreesByRepo: {
-        repo1: [makeWorktree({ id: worktreeId, repoId: 'repo1', path: '/tmp/wt-1' })]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [
-          makeTabGroup({ id: 'terminal-group', worktreeId, activeTabId: null, tabOrder: [] }),
-          makeTabGroup({ id: 'browser-group', worktreeId, activeTabId: null, tabOrder: [] })
-        ]
-      },
-      activeGroupIdByWorktree: { [worktreeId]: 'terminal-group' },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
-
-    const created = store.getState().createBrowserTab(worktreeId, 'https://example.com', {
-      title: 'Example'
-    })
-
-    const unifiedTab = (store.getState().unifiedTabsByWorktree[worktreeId] ?? []).find(
-      (t) => t.contentType === 'browser' && t.entityId === created.id
-    )
-    expect(unifiedTab?.groupId).toBe('terminal-group')
-  })
-
-  it('reopens the most recently closed browser tab in the same worktree', () => {
-    const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'browser',
-      worktreesByRepo: {
-        repo1: [
-          makeWorktree({
-            id: worktreeId,
-            repoId: 'repo1',
-            path: '/tmp/wt-1'
-          })
-        ]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [
-          makeTabGroup({
-            id: 'group-1',
-            worktreeId,
-            activeTabId: null,
-            tabOrder: []
-          })
-        ]
-      },
-      activeGroupIdByWorktree: {
-        [worktreeId]: 'group-1'
-      },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
-
-    const created = store.getState().createBrowserTab(worktreeId, 'https://example.com/docs', {
-      title: 'Docs'
-    })
-    store.getState().closeBrowserTab(created.id)
-
-    expect(store.getState().browserTabsByWorktree[worktreeId]).toBeUndefined()
-    expect(store.getState().recentlyClosedBrowserTabsByWorktree[worktreeId]).toHaveLength(1)
-
-    const reopened = store.getState().reopenClosedBrowserTab(worktreeId)
-
-    expect(reopened).not.toBeNull()
-    expect(reopened?.id).not.toBe(created.id)
-    expect(reopened?.url).toBe('https://example.com/docs')
-    expect(reopened?.title).toBe('Docs')
-    expect(store.getState().browserTabsByWorktree[worktreeId]).toHaveLength(1)
-    expect(store.getState().recentlyClosedBrowserTabsByWorktree[worktreeId]).toHaveLength(0)
-  })
-
-  it('reopens a multi-page workspace without duplicating the active URL (page order ≠ active first)', () => {
-    const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'browser',
-      worktreesByRepo: {
-        repo1: [
-          makeWorktree({
-            id: worktreeId,
-            repoId: 'repo1',
-            path: '/tmp/wt-1'
-          })
-        ]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [
-          makeTabGroup({
-            id: 'group-1',
-            worktreeId,
-            activeTabId: null,
-            tabOrder: []
-          })
-        ]
-      },
-      activeGroupIdByWorktree: {
-        [worktreeId]: 'group-1'
-      },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
-
-    const ws = store.getState().createBrowserTab(worktreeId, 'https://example.com/a', {
-      title: 'A'
-    })
-    store
-      .getState()
-      .createBrowserPage(ws.id, 'https://example.com/b', { title: 'B', activate: true })
-    const beforeClose = store.getState().browserPagesByWorkspace[ws.id] ?? []
-    expect(beforeClose).toHaveLength(2)
-    expect(store.getState().browserTabsByWorktree[worktreeId]?.[0]?.url).toBe(
-      'https://example.com/b'
-    )
-
-    store.getState().closeBrowserTab(ws.id)
-    const reopened = store.getState().reopenClosedBrowserTab(worktreeId)
-    expect(reopened).not.toBeNull()
-    const pages = store.getState().browserPagesByWorkspace[reopened!.id] ?? []
-    expect(pages).toHaveLength(2)
-    const urls = new Set(pages.map((p) => p.url))
-    expect(urls.has('https://example.com/a')).toBe(true)
-    expect(urls.has('https://example.com/b')).toBe(true)
-    expect(store.getState().browserTabsByWorktree[worktreeId]?.[0]?.url).toBe(
-      'https://example.com/b'
-    )
-  })
-
-  it('sets pending address-bar focus when focusAddressBar is true even for non-blank URLs', () => {
-    const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'terminal',
-      worktreesByRepo: {
-        repo1: [makeWorktree({ id: worktreeId, repoId: 'repo1', path: '/tmp/wt-1' })]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [makeTabGroup({ id: 'group-1', worktreeId, activeTabId: null, tabOrder: [] })]
-      },
-      activeGroupIdByWorktree: { [worktreeId]: 'group-1' },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
-
-    const created = store.getState().createBrowserTab(worktreeId, 'https://example.com/home', {
-      title: 'Home',
-      focusAddressBar: true
-    })
-
-    const pageId = store.getState().browserPagesByWorkspace[created.id]?.[0]?.id
-    expect(pageId).toBeDefined()
-    expect(store.getState().pendingAddressBarFocusByTabId[created.id]).toBe(true)
-    expect(store.getState().pendingAddressBarFocusByPageId[pageId!]).toBe(true)
-  })
-
-  it('does not set pending address-bar focus for non-blank URLs when focusAddressBar is not set', () => {
-    const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'terminal',
-      worktreesByRepo: {
-        repo1: [makeWorktree({ id: worktreeId, repoId: 'repo1', path: '/tmp/wt-1' })]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [makeTabGroup({ id: 'group-1', worktreeId, activeTabId: null, tabOrder: [] })]
-      },
-      activeGroupIdByWorktree: { [worktreeId]: 'group-1' },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
-
-    const created = store.getState().createBrowserTab(worktreeId, 'https://example.com/home', {
-      title: 'Home'
-    })
-
-    expect(store.getState().pendingAddressBarFocusByTabId[created.id]).toBeUndefined()
-  })
-})
-
-describe('hydrateBrowserSession', () => {
+describe('createBrowserSlice runtime guard', () => {
   beforeEach(() => {
-    vi.mocked(destroyPersistentWebview).mockClear()
+    vi.clearAllMocks()
+    clearRuntimeCompatibilityCacheForTests()
+    runtimeEnvironmentCall.mockReset()
+    runtimeEnvironmentTransportCall.mockReset()
+    runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+      return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+    })
+    runtimeEnvironmentCall.mockResolvedValue({ id: 'rpc-1', ok: true, result: {} })
   })
 
-  // Why: design §3. hydrateBrowserSession drops workspaces whose worktree no
-  // longer exists. Reducers are pure; destroy calls must bracket the set()
-  // to mirror closeBrowserTab's contract and keep future callers (that might
-  // run hydrate after webviews are live) safe without surgery.
-  it('destroys webviews for dropped workspaces before committing state', () => {
+  it('fetches browser profiles from the active runtime environment', async () => {
     const store = createTestStore()
-    const survivingWorktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      worktreesByRepo: {
-        repo1: [makeWorktree({ id: survivingWorktreeId, repoId: 'repo1', path: '/tmp/wt-1' })]
-      },
-      // Why: destroyWorkspaceWebviews reads pre-hydrate browserPagesByWorkspace
-      // to resolve page ids. If the store is empty at hydrate time, the helper
-      // falls back to the legacy workspace-id destroy (design §2 fallback). To
-      // prove the page-id branch runs when pages exist in-store, seed them
-      // first. Today's boot-only caller hits the fallback because hydrate is
-      // the first thing to populate the map — the assertion here covers a
-      // future re-hydrate after webviews are already live.
-      browserPagesByWorkspace: {
-        'workspace-drop': [
+    runtimeEnvironmentCall.mockResolvedValueOnce({
+      id: 'rpc-1',
+      ok: true,
+      result: {
+        profiles: [
           {
-            id: 'page-drop-a',
-            workspaceId: 'workspace-drop',
-            worktreeId: 'repo1::/tmp/wt-gone',
-            url: 'about:blank',
-            title: 'a',
-            loading: false,
-            faviconUrl: null,
-            canGoBack: false,
-            canGoForward: false,
-            loadError: null,
-            createdAt: 1
-          },
-          {
-            id: 'page-drop-b',
-            workspaceId: 'workspace-drop',
-            worktreeId: 'repo1::/tmp/wt-gone',
-            url: 'about:blank',
-            title: 'b',
-            loading: false,
-            faviconUrl: null,
-            canGoBack: false,
-            canGoForward: false,
-            loadError: null,
-            createdAt: 1
+            id: 'default',
+            scope: 'default',
+            partition: 'persist:orca-default',
+            label: 'Default',
+            source: null
           }
         ]
-      } as never
+      },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    store.setState({
+      settings: settingsWithRuntime('env-1'),
+      browserSessionProfiles: []
     })
 
-    store.getState().hydrateBrowserSession({
-      browserTabsByWorktree: {
-        [survivingWorktreeId]: [
-          {
-            id: 'workspace-keep',
-            worktreeId: survivingWorktreeId,
-            label: 'keep',
-            sessionProfileId: null,
-            pageIds: ['page-keep'],
-            activePageId: 'page-keep',
-            url: 'about:blank',
-            title: 'keep',
-            loading: false,
-            faviconUrl: null,
-            canGoBack: false,
-            canGoForward: false,
-            loadError: null,
-            createdAt: 1
-          }
-        ],
-        'repo1::/tmp/wt-gone': [
-          {
-            id: 'workspace-drop',
-            worktreeId: 'repo1::/tmp/wt-gone',
-            label: 'drop',
-            sessionProfileId: null,
-            pageIds: ['page-drop-a', 'page-drop-b'],
-            activePageId: 'page-drop-a',
-            url: 'about:blank',
-            title: 'drop',
-            loading: false,
-            faviconUrl: null,
-            canGoBack: false,
-            canGoForward: false,
-            loadError: null,
-            createdAt: 1
-          }
-        ]
-      },
-      browserPagesByWorkspace: {
-        'workspace-drop': [
-          {
-            id: 'page-drop-a',
-            workspaceId: 'workspace-drop',
-            worktreeId: 'repo1::/tmp/wt-gone',
-            url: 'about:blank',
-            title: 'a',
-            loading: false,
-            faviconUrl: null,
-            canGoBack: false,
-            canGoForward: false,
-            loadError: null,
-            createdAt: 1
-          },
-          {
-            id: 'page-drop-b',
-            workspaceId: 'workspace-drop',
-            worktreeId: 'repo1::/tmp/wt-gone',
-            url: 'about:blank',
-            title: 'b',
-            loading: false,
-            faviconUrl: null,
-            canGoBack: false,
-            canGoForward: false,
-            loadError: null,
-            createdAt: 1
-          }
-        ],
-        'workspace-keep': [
-          {
-            id: 'page-keep',
-            workspaceId: 'workspace-keep',
-            worktreeId: survivingWorktreeId,
-            url: 'about:blank',
-            title: 'keep',
-            loading: false,
-            faviconUrl: null,
-            canGoBack: false,
-            canGoForward: false,
-            loadError: null,
-            createdAt: 1
-          }
-        ]
-      }
-    } as never)
+    await store.getState().fetchBrowserSessionProfiles()
 
-    expect(destroyPersistentWebview).toHaveBeenCalledWith('page-drop-a')
-    expect(destroyPersistentWebview).toHaveBeenCalledWith('page-drop-b')
-    expect(destroyPersistentWebview).not.toHaveBeenCalledWith('page-keep')
-    expect(store.getState().browserTabsByWorktree['repo1::/tmp/wt-gone']).toBeUndefined()
-    expect(store.getState().browserPagesByWorkspace['workspace-drop']).toBeUndefined()
-    expect(store.getState().browserTabsByWorktree[survivingWorktreeId]).toHaveLength(1)
-  })
-
-  it('redacts Kagi session tokens from hydrated browser history', () => {
-    const store = createTestStore()
-
-    store.getState().hydrateBrowserSession({
-      browserUrlHistory: [
-        {
-          url: 'https://kagi.com/search?token=secret&q=hello+world',
-          normalizedUrl: 'https://kagi.com/search?token=secret&q=hello+world',
-          title: 'Kagi Search',
-          lastVisitedAt: 1,
-          visitCount: 1
-        }
-      ]
-    } as never)
-
-    expect(store.getState().browserUrlHistory).toEqual([
+    expect(mockApi.browser.sessionListProfiles).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'browser.profileList',
+      params: undefined,
+      timeoutMs: 15_000
+    })
+    expect(store.getState().browserSessionProfiles).toEqual([
       {
-        url: 'https://kagi.com/search?q=hello+world',
-        normalizedUrl: 'https://kagi.com/search?q=hello+world',
-        title: 'Kagi Search',
-        lastVisitedAt: 1,
-        visitCount: 1
+        id: 'default',
+        scope: 'default',
+        partition: 'persist:orca-default',
+        label: 'Default',
+        source: null
       }
     ])
   })
-})
 
-// Why: setBrowserPageUrl is the single sink for URL updates from did-navigate,
-// the agent-browser CDP nav-update IPC, and direct address-bar submits. Pin
-// redaction at this boundary so a Kagi bearer token cannot reach the
-// persisted BrowserPage.url field via any caller that forgot to redact.
-describe('setBrowserPageUrl redaction', () => {
-  it('redacts Kagi session tokens before storing the page URL', () => {
+  it('does not import local browser cookies while a runtime environment is active', async () => {
     const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'browser',
-      worktreesByRepo: {
-        repo1: [makeWorktree({ id: worktreeId, repoId: 'repo1', path: '/tmp/wt-1' })]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [makeTabGroup({ id: 'group-1', worktreeId, activeTabId: null, tabOrder: [] })]
-      },
-      activeGroupIdByWorktree: { [worktreeId]: 'group-1' },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
+    store.setState({ settings: settingsWithRuntime('env-1') })
+
+    const result = await store.getState().importCookiesToProfile('default')
+
+    expect(mockApi.browser.sessionImportCookies).not.toHaveBeenCalled()
+    expect(result.ok).toBe(false)
+    expect(store.getState().browserSessionImportState).toMatchObject({
+      profileId: 'default',
+      status: 'error'
     })
-
-    const ws = store.getState().createBrowserTab(worktreeId, 'about:blank', { title: 'New Tab' })
-    const pageId = store.getState().browserPagesByWorkspace[ws.id]?.[0]?.id
-    expect(pageId).toBeDefined()
-
-    store
-      .getState()
-      .setBrowserPageUrl(pageId!, 'https://kagi.com/search?token=secret&q=hello+world')
-
-    const page = store.getState().browserPagesByWorkspace[ws.id]?.[0]
-    expect(page?.url).toBe('https://kagi.com/search?q=hello+world')
-    expect(store.getState().browserTabsByWorktree[worktreeId]?.[0]?.url).toBe(
-      'https://kagi.com/search?q=hello+world'
-    )
-  })
-})
-
-// Why: the leak this PR fixes lives inside the thunk itself. removeWorktree
-// and runSleepWorktree tests stub this thunk, so destroy-call regressions in
-// its body would be invisible there. These tests pin the thunk directly.
-describe('shutdownWorktreeBrowsers', () => {
-  beforeEach(() => {
-    vi.mocked(destroyPersistentWebview).mockClear()
   })
 
-  function seedWorktree(store: ReturnType<typeof createTestStore>, worktreeId: string): void {
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: worktreeId,
-      activeTabType: 'browser',
-      worktreesByRepo: {
-        repo1: [makeWorktree({ id: worktreeId, repoId: 'repo1', path: '/tmp/wt-1' })]
-      },
-      groupsByWorktree: {
-        [worktreeId]: [makeTabGroup({ id: 'group-1', worktreeId, activeTabId: null, tabOrder: [] })]
-      },
-      activeGroupIdByWorktree: { [worktreeId]: 'group-1' },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
-  }
-
-  it('destroys every page in every workspace of the target worktree', async () => {
+  it('uses local browser IPC when no runtime environment is active', async () => {
     const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedWorktree(store, worktreeId)
+    mockApi.browser.sessionListProfiles.mockResolvedValueOnce([
+      {
+        id: 'default',
+        scope: 'default',
+        partition: 'persist:orca-default',
+        label: 'Default',
+        source: null
+      }
+    ])
 
-    const ws1 = store.getState().createBrowserTab(worktreeId, 'https://example.com/a', {
-      title: 'A'
-    })
-    const ws2 = store.getState().createBrowserTab(worktreeId, 'https://example.com/b', {
-      title: 'B'
-    })
-    const ws1PageIds = (store.getState().browserPagesByWorkspace[ws1.id] ?? []).map((p) => p.id)
-    const ws2PageIds = (store.getState().browserPagesByWorkspace[ws2.id] ?? []).map((p) => p.id)
-    expect(ws1PageIds).toHaveLength(1)
-    expect(ws2PageIds).toHaveLength(1)
+    await store.getState().fetchBrowserSessionProfiles()
 
-    await store.getState().shutdownWorktreeBrowsers(worktreeId)
-
-    // Why: this is the regression guard. If the thunk ever stops calling
-    // destroyWorkspaceWebviews (or reverts to the old workspace-id keying),
-    // this assertion fails loudly.
-    for (const pageId of [...ws1PageIds, ...ws2PageIds]) {
-      expect(destroyPersistentWebview).toHaveBeenCalledWith(pageId)
-    }
-    expect(store.getState().browserTabsByWorktree[worktreeId]).toBeUndefined()
-    expect(store.getState().browserPagesByWorkspace[ws1.id]).toBeUndefined()
-    expect(store.getState().browserPagesByWorkspace[ws2.id]).toBeUndefined()
+    expect(mockApi.browser.sessionListProfiles).toHaveBeenCalledTimes(1)
+    expect(store.getState().browserSessionProfiles).toEqual([
+      {
+        id: 'default',
+        scope: 'default',
+        partition: 'persist:orca-default',
+        label: 'Default',
+        source: null
+      }
+    ])
   })
 
-  it('destroys every page id of a multi-page workspace', async () => {
+  it('does not notify the local browser manager when selecting tabs under runtime', () => {
     const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedWorktree(store, worktreeId)
-
-    const ws = store.getState().createBrowserTab(worktreeId, 'https://example.com/a', {
-      title: 'A'
+    store.setState({
+      settings: settingsWithRuntime('env-1'),
+      unifiedTabsByWorktree: {},
+      browserTabsByWorktree: {
+        'wt-1': [
+          {
+            id: 'workspace-1',
+            worktreeId: 'wt-1',
+            sessionProfileId: null,
+            activePageId: 'page-1',
+            pageIds: ['page-1'],
+            url: 'about:blank',
+            title: 'New Tab',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
+        ]
+      }
     })
-    store
-      .getState()
-      .createBrowserPage(ws.id, 'https://example.com/b', { title: 'B', activate: false })
-    store
-      .getState()
-      .createBrowserPage(ws.id, 'https://example.com/c', { title: 'C', activate: false })
-    const pageIds = (store.getState().browserPagesByWorkspace[ws.id] ?? []).map((p) => p.id)
-    expect(pageIds).toHaveLength(3)
 
-    await store.getState().shutdownWorktreeBrowsers(worktreeId)
+    store.getState().setActiveBrowserTab('workspace-1')
 
-    for (const pageId of pageIds) {
-      expect(destroyPersistentWebview).toHaveBeenCalledWith(pageId)
-    }
+    expect(mockApi.browser.notifyActiveTabChanged).not.toHaveBeenCalled()
   })
 
-  it('leaves other worktrees untouched', async () => {
+  it('closes the mapped remote tab when closing a browser page in the active runtime', async () => {
     const store = createTestStore()
-    const targetWorktreeId = 'repo1::/tmp/wt-1'
-    const otherWorktreeId = 'repo1::/tmp/wt-2'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: targetWorktreeId,
-      activeTabType: 'browser',
-      worktreesByRepo: {
-        repo1: [
-          makeWorktree({ id: targetWorktreeId, repoId: 'repo1', path: '/tmp/wt-1' }),
-          makeWorktree({ id: otherWorktreeId, repoId: 'repo1', path: '/tmp/wt-2' })
+    store.setState({
+      settings: settingsWithRuntime('env-1'),
+      browserTabsByWorktree: {
+        'wt-1': [
+          {
+            id: 'workspace-1',
+            worktreeId: 'wt-1',
+            sessionProfileId: null,
+            activePageId: 'page-1',
+            pageIds: ['page-1'],
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
         ]
       },
-      groupsByWorktree: {
-        [targetWorktreeId]: [
-          makeTabGroup({
-            id: 'group-1',
-            worktreeId: targetWorktreeId,
-            activeTabId: null,
-            tabOrder: []
-          })
-        ],
-        [otherWorktreeId]: [
-          makeTabGroup({
-            id: 'group-2',
-            worktreeId: otherWorktreeId,
-            activeTabId: null,
-            tabOrder: []
-          })
+      browserPagesByWorkspace: {
+        'workspace-1': [
+          {
+            id: 'page-1',
+            workspaceId: 'workspace-1',
+            worktreeId: 'wt-1',
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
         ]
       },
-      activeGroupIdByWorktree: {
-        [targetWorktreeId]: 'group-1',
-        [otherWorktreeId]: 'group-2'
-      },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
+      remoteBrowserPageHandlesByPageId: {
+        'page-1': { environmentId: 'env-1', remotePageId: 'remote-page-1' }
+      }
     })
 
-    const targetWs = store.getState().createBrowserTab(targetWorktreeId, 'https://example.com/a', {
-      title: 'A'
-    })
-    const otherWs = store.getState().createBrowserTab(otherWorktreeId, 'https://example.com/b', {
-      title: 'B'
-    })
-    const otherPageIds = (store.getState().browserPagesByWorkspace[otherWs.id] ?? []).map(
-      (p) => p.id
-    )
+    store.getState().closeBrowserPage('page-1')
 
-    await store.getState().shutdownWorktreeBrowsers(targetWorktreeId)
-
-    expect(store.getState().browserTabsByWorktree[targetWorktreeId]).toBeUndefined()
-    expect(store.getState().browserPagesByWorkspace[targetWs.id]).toBeUndefined()
-    expect(store.getState().browserTabsByWorktree[otherWorktreeId]).toHaveLength(1)
-    expect(store.getState().browserPagesByWorkspace[otherWs.id]).toHaveLength(1)
-    for (const pageId of otherPageIds) {
-      expect(destroyPersistentWebview).not.toHaveBeenCalledWith(pageId)
-    }
-  })
-
-  it('clears activeBrowserTabId and activeTabType when the target is the active worktree', async () => {
-    const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedWorktree(store, worktreeId)
-
-    const ws = store.getState().createBrowserTab(worktreeId, 'https://example.com/a', {
-      title: 'A',
-      activate: true
-    })
-    expect(store.getState().activeBrowserTabId).toBe(ws.id)
-
-    await store.getState().shutdownWorktreeBrowsers(worktreeId)
-
-    expect(store.getState().activeBrowserTabId).toBeNull()
-    expect(store.getState().activeTabType).toBe('terminal')
-    expect(store.getState().activeBrowserTabIdByWorktree[worktreeId]).toBeUndefined()
-  })
-
-  it('leaves global active browser alone when shutting down a background worktree', async () => {
-    const store = createTestStore()
-    const activeWorktreeId = 'repo1::/tmp/wt-1'
-    const backgroundWorktreeId = 'repo1::/tmp/wt-2'
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId,
-      activeTabType: 'browser',
-      worktreesByRepo: {
-        repo1: [
-          makeWorktree({ id: activeWorktreeId, repoId: 'repo1', path: '/tmp/wt-1' }),
-          makeWorktree({ id: backgroundWorktreeId, repoId: 'repo1', path: '/tmp/wt-2' })
-        ]
-      },
-      groupsByWorktree: {
-        [activeWorktreeId]: [
-          makeTabGroup({
-            id: 'group-1',
-            worktreeId: activeWorktreeId,
-            activeTabId: null,
-            tabOrder: []
-          })
-        ],
-        [backgroundWorktreeId]: [
-          makeTabGroup({
-            id: 'group-2',
-            worktreeId: backgroundWorktreeId,
-            activeTabId: null,
-            tabOrder: []
-          })
-        ]
-      },
-      activeGroupIdByWorktree: {
-        [activeWorktreeId]: 'group-1',
-        [backgroundWorktreeId]: 'group-2'
-      },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
-    })
-
-    const activeWs = store
-      .getState()
-      .createBrowserTab(activeWorktreeId, 'https://example.com/active', {
-        title: 'Active',
-        activate: true
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'browser.tabClose',
+        params: { worktree: 'id:wt-1', page: 'remote-page-1' },
+        timeoutMs: 15_000
       })
-    store.getState().createBrowserTab(backgroundWorktreeId, 'https://example.com/bg', {
-      title: 'Background',
-      // Why: createBrowserTab defaults to activate=true which would replace
-      // activeBrowserTabId globally. This test needs the original active tab
-      // to stay active so we can prove shutdown of the background worktree
-      // doesn't disturb it.
-      activate: false
     })
-    expect(store.getState().activeBrowserTabId).toBe(activeWs.id)
-
-    await store.getState().shutdownWorktreeBrowsers(backgroundWorktreeId)
-
-    // Why: §1 shouldResetGlobalBrowser is gated on activeWorktreeId===target.
-    // Shutting down a background worktree must not disturb what the user is
-    // currently looking at.
-    expect(store.getState().activeBrowserTabId).toBe(activeWs.id)
-    expect(store.getState().activeTabType).toBe('browser')
+    expect(store.getState().remoteBrowserPageHandlesByPageId['page-1']).toBeUndefined()
   })
 
-  it('is a no-op when the worktree has no browser tabs', async () => {
+  it('closes mapped remote tabs when closing a browser workspace in the active runtime', async () => {
     const store = createTestStore()
-    const worktreeId = 'repo1::/tmp/wt-1'
-    seedWorktree(store, worktreeId)
-    // Override: this test needs activeTabType to start as terminal so we can
-    // prove shutdown doesn't flip it.
-    store.setState({ activeTabType: 'terminal' })
-
-    await store.getState().shutdownWorktreeBrowsers(worktreeId)
-
-    expect(destroyPersistentWebview).not.toHaveBeenCalled()
-    expect(store.getState().activeTabType).toBe('terminal')
-  })
-})
-
-// Why: focusBrowserTabInWorktree is the renderer side of `tab switch --focus`.
-// The defining invariant is no cross-worktree screen theft: when multiple
-// agents drive browsers in parallel worktrees, an agent focusing a tab in
-// worktree X must never yank the user's view away from worktree Y.
-describe('focusBrowserTabInWorktree', () => {
-  function seedTwoWorktrees(
-    store: ReturnType<typeof createTestStore>,
-    activeWt: string,
-    otherWt: string
-  ): void {
-    seedStore(store, {
-      activeRepoId: 'repo1',
-      activeWorktreeId: activeWt,
-      activeTabType: 'terminal',
-      worktreesByRepo: {
-        repo1: [
-          makeWorktree({ id: activeWt, repoId: 'repo1', path: '/tmp/wt-active' }),
-          makeWorktree({ id: otherWt, repoId: 'repo1', path: '/tmp/wt-other' })
+    store.setState({
+      settings: settingsWithRuntime('env-1'),
+      browserTabsByWorktree: {
+        'wt-1': [
+          {
+            id: 'workspace-1',
+            worktreeId: 'wt-1',
+            sessionProfileId: null,
+            activePageId: 'page-1',
+            pageIds: ['page-1'],
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
         ]
       },
-      groupsByWorktree: {
-        [activeWt]: [
-          makeTabGroup({ id: 'g-active', worktreeId: activeWt, activeTabId: null, tabOrder: [] })
-        ],
-        [otherWt]: [
-          makeTabGroup({ id: 'g-other', worktreeId: otherWt, activeTabId: null, tabOrder: [] })
+      activeBrowserTabId: 'workspace-1',
+      activeBrowserTabIdByWorktree: { 'wt-1': 'workspace-1' },
+      browserPagesByWorkspace: {
+        'workspace-1': [
+          {
+            id: 'page-1',
+            workspaceId: 'workspace-1',
+            worktreeId: 'wt-1',
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
         ]
       },
-      activeGroupIdByWorktree: { [activeWt]: 'g-active', [otherWt]: 'g-other' },
-      activeTabTypeByWorktree: { [activeWt]: 'terminal', [otherWt]: 'terminal' },
-      browserTabsByWorktree: {},
-      unifiedTabsByWorktree: {}
+      remoteBrowserPageHandlesByPageId: {
+        'page-1': { environmentId: 'env-1', remotePageId: 'remote-page-1' }
+      }
     })
-  }
 
-  it('does not yank activeWorktreeId when focusing a tab in a non-active worktree', () => {
-    const store = createTestStore()
-    const activeWt = 'repo1::/tmp/wt-active'
-    const otherWt = 'repo1::/tmp/wt-other'
-    seedTwoWorktrees(store, activeWt, otherWt)
+    store.getState().closeBrowserTab('workspace-1')
 
-    const ws = store.getState().createBrowserTab(otherWt, 'https://example.com/a', { title: 'A' })
-    const pageId = (store.getState().browserPagesByWorkspace[ws.id] ?? [])[0]?.id
-    expect(pageId).toBeDefined()
-    // createBrowserTab on a non-active worktree leaves activeWorktreeId alone;
-    // re-pin it here in case any future change to that path regresses it.
-    store.setState({ activeWorktreeId: activeWt, activeTabType: 'terminal' })
-
-    store.getState().focusBrowserTabInWorktree(otherWt, pageId!, { surfacePane: true })
-
-    expect(store.getState().activeWorktreeId).toBe(activeWt)
-    expect(store.getState().activeTabType).toBe('terminal')
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'browser.tabClose',
+        params: { worktree: 'id:wt-1', page: 'remote-page-1' },
+        timeoutMs: 15_000
+      })
+    })
+    expect(store.getState().remoteBrowserPageHandlesByPageId['page-1']).toBeUndefined()
   })
 
-  it('updates per-worktree active tab and tab type for the targeted worktree even when not active', () => {
+  it('closes mapped remote pages in their owning environment after switching local', async () => {
     const store = createTestStore()
-    const activeWt = 'repo1::/tmp/wt-active'
-    const otherWt = 'repo1::/tmp/wt-other'
-    seedTwoWorktrees(store, activeWt, otherWt)
+    store.setState({
+      browserTabsByWorktree: {
+        'wt-1': [
+          {
+            id: 'workspace-1',
+            worktreeId: 'wt-1',
+            sessionProfileId: null,
+            activePageId: 'page-1',
+            pageIds: ['page-1'],
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
+        ]
+      },
+      browserPagesByWorkspace: {
+        'workspace-1': [
+          {
+            id: 'page-1',
+            workspaceId: 'workspace-1',
+            worktreeId: 'wt-1',
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
+        ]
+      },
+      remoteBrowserPageHandlesByPageId: {
+        'page-1': { environmentId: 'env-1', remotePageId: 'remote-page-1' }
+      }
+    })
 
-    const ws = store.getState().createBrowserTab(otherWt, 'https://example.com/a', { title: 'A' })
-    const pageId = (store.getState().browserPagesByWorkspace[ws.id] ?? [])[0]?.id
-    store.setState({ activeWorktreeId: activeWt, activeTabType: 'terminal' })
+    store.getState().closeBrowserPage('page-1')
 
-    store.getState().focusBrowserTabInWorktree(otherWt, pageId!, { surfacePane: true })
-
-    // Per-worktree slots: pre-staged for whenever the user next visits otherWt.
-    expect(store.getState().activeBrowserTabIdByWorktree[otherWt]).toBe(ws.id)
-    expect(store.getState().activeTabTypeByWorktree[otherWt]).toBe('browser')
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'browser.tabClose',
+        params: { worktree: 'id:wt-1', page: 'remote-page-1' },
+        timeoutMs: 15_000
+      })
+    })
   })
 
-  it('flips global activeBrowserTabId and activeTabType when targeting the active worktree with surfacePane', () => {
+  it('closes mapped remote tabs in their owning environment after switching environments', async () => {
     const store = createTestStore()
-    const activeWt = 'repo1::/tmp/wt-active'
-    const otherWt = 'repo1::/tmp/wt-other'
-    seedTwoWorktrees(store, activeWt, otherWt)
+    store.setState({
+      settings: settingsWithRuntime('env-2'),
+      browserTabsByWorktree: {
+        'wt-1': [
+          {
+            id: 'workspace-1',
+            worktreeId: 'wt-1',
+            sessionProfileId: null,
+            activePageId: 'page-1',
+            pageIds: ['page-1'],
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
+        ]
+      },
+      browserPagesByWorkspace: {
+        'workspace-1': [
+          {
+            id: 'page-1',
+            workspaceId: 'workspace-1',
+            worktreeId: 'wt-1',
+            url: 'https://example.com',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1
+          }
+        ]
+      },
+      remoteBrowserPageHandlesByPageId: {
+        'page-1': { environmentId: 'env-1', remotePageId: 'remote-page-1' }
+      }
+    })
 
-    const ws = store.getState().createBrowserTab(activeWt, 'https://example.com/a', { title: 'A' })
-    const pageId = (store.getState().browserPagesByWorkspace[ws.id] ?? [])[0]?.id
-    // Reset to terminal so we can prove --focus surfaces the pane.
-    store.setState((s) => ({
-      activeTabType: 'terminal',
-      activeTabTypeByWorktree: { ...s.activeTabTypeByWorktree, [activeWt]: 'terminal' }
-    }))
+    store.getState().closeBrowserTab('workspace-1')
 
-    store.getState().focusBrowserTabInWorktree(activeWt, pageId!, { surfacePane: true })
-
-    expect(store.getState().activeBrowserTabId).toBe(ws.id)
-    expect(store.getState().activeTabType).toBe('browser')
-  })
-
-  it('without surfacePane, leaves activeTabType alone even on the active worktree', () => {
-    const store = createTestStore()
-    const activeWt = 'repo1::/tmp/wt-active'
-    const otherWt = 'repo1::/tmp/wt-other'
-    seedTwoWorktrees(store, activeWt, otherWt)
-
-    const ws = store.getState().createBrowserTab(activeWt, 'https://example.com/a', { title: 'A' })
-    const pageId = (store.getState().browserPagesByWorkspace[ws.id] ?? [])[0]?.id
-    // Reset both globals and per-worktree slot so we can prove surfacePane=false
-    // does NOT flip the user back into the browser pane (createBrowserTab
-    // itself flips both because it activates the new tab).
-    store.setState((s) => ({
-      activeTabType: 'terminal',
-      activeTabTypeByWorktree: { ...s.activeTabTypeByWorktree, [activeWt]: 'terminal' }
-    }))
-
-    store.getState().focusBrowserTabInWorktree(activeWt, pageId!, { surfacePane: false })
-
-    // Per-worktree active tab still pre-staged, but the user is still on terminal.
-    expect(store.getState().activeBrowserTabIdByWorktree[activeWt]).toBe(ws.id)
-    expect(store.getState().activeTabType).toBe('terminal')
-    expect(store.getState().activeTabTypeByWorktree[activeWt]).toBe('terminal')
-  })
-
-  it('finds the owning workspace via pageIds for multi-page workspaces', () => {
-    const store = createTestStore()
-    const activeWt = 'repo1::/tmp/wt-active'
-    const otherWt = 'repo1::/tmp/wt-other'
-    seedTwoWorktrees(store, activeWt, otherWt)
-
-    const ws = store.getState().createBrowserTab(otherWt, 'https://example.com/a', { title: 'A' })
-    const pageB = store
-      .getState()
-      .createBrowserPage(ws.id, 'https://example.com/b', { title: 'B', activate: false })
-    expect(pageB).not.toBeNull()
-
-    store.getState().focusBrowserTabInWorktree(otherWt, pageB!.id, { surfacePane: true })
-
-    // The workspace's activePageId must follow the focused page id, not its
-    // first page. Renderer otherwise shows the wrong tab on next visit.
-    const updatedWs = store.getState().browserTabsByWorktree[otherWt]?.find((t) => t.id === ws.id)
-    expect(updatedWs?.activePageId).toBe(pageB!.id)
-    expect(store.getState().activeBrowserTabIdByWorktree[otherWt]).toBe(ws.id)
-  })
-
-  it('is a no-op when the page id is not present in the targeted worktree', () => {
-    const store = createTestStore()
-    const activeWt = 'repo1::/tmp/wt-active'
-    const otherWt = 'repo1::/tmp/wt-other'
-    seedTwoWorktrees(store, activeWt, otherWt)
-
-    const before = store.getState()
-    before.focusBrowserTabInWorktree(otherWt, 'page-that-does-not-exist', { surfacePane: true })
-    const after = store.getState()
-
-    // Nothing globally or per-worktree should have moved. Best-effort: the
-    // page may have closed between the bridge switching and the IPC arriving.
-    expect(after.activeWorktreeId).toBe(before.activeWorktreeId)
-    expect(after.activeTabType).toBe(before.activeTabType)
-    expect(after.activeBrowserTabIdByWorktree[otherWt]).toBeUndefined()
-  })
-
-  it('surfaces the pane by default when no options are passed (active worktree)', () => {
-    const store = createTestStore()
-    const activeWt = 'repo1::/tmp/wt-active'
-    const otherWt = 'repo1::/tmp/wt-other'
-    seedTwoWorktrees(store, activeWt, otherWt)
-
-    const ws = store.getState().createBrowserTab(activeWt, 'https://example.com/a', { title: 'A' })
-    const pageId = (store.getState().browserPagesByWorkspace[ws.id] ?? [])[0]?.id
-    store.setState((s) => ({
-      activeTabType: 'terminal',
-      activeTabTypeByWorktree: { ...s.activeTabTypeByWorktree, [activeWt]: 'terminal' }
-    }))
-
-    store.getState().focusBrowserTabInWorktree(activeWt, pageId!)
-
-    expect(store.getState().activeBrowserTabId).toBe(ws.id)
-    expect(store.getState().activeTabType).toBe('browser')
-    expect(store.getState().activeTabTypeByWorktree[activeWt]).toBe('browser')
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'browser.tabClose',
+        params: { worktree: 'id:wt-1', page: 'remote-page-1' },
+        timeoutMs: 15_000
+      })
+    })
   })
 })
diff --git a/src/renderer/src/store/slices/browser.ts b/src/renderer/src/store/slices/browser.ts
index d20473c299b..e326b761568 100644
--- a/src/renderer/src/store/slices/browser.ts
+++ b/src/renderer/src/store/slices/browser.ts
@@ -21,6 +21,19 @@ import {
 } from '../../../../shared/workspace-session-browser-history'
 import { pickNeighbor } from './tab-group-state'
 import { destroyWorkspaceWebviews } from './browser-webview-cleanup'
+import {
+  callRuntimeRpc,
+  getActiveRuntimeTarget,
+  type RuntimeClientTarget
+} from '@/runtime/runtime-rpc-client'
+import type {
+  BrowserDetectProfilesResult,
+  BrowserProfileClearDefaultCookiesResult,
+  BrowserProfileCreateResult,
+  BrowserProfileDeleteResult,
+  BrowserProfileImportFromBrowserResult,
+  BrowserProfileListResult
+} from '../../../../shared/runtime-types'
 
 type CreateBrowserTabOptions = {
   activate?: boolean
@@ -57,9 +70,15 @@ type ClosedBrowserWorkspaceSnapshot = {
   pages: BrowserPage[]
 }
 
+export type RemoteBrowserPageHandle = {
+  environmentId: string
+  remotePageId: string
+}
+
 export type BrowserSlice = {
   browserTabsByWorktree: Record<string, BrowserWorkspace[]>
   browserPagesByWorkspace: Record<string, BrowserPage[]>
+  remoteBrowserPageHandlesByPageId: Record<string, RemoteBrowserPageHandle>
   activeBrowserTabId: string | null
   activeBrowserTabIdByWorktree: Record<string, string | null>
   recentlyClosedBrowserTabsByWorktree: Record<string, ClosedBrowserWorkspaceSnapshot[]>
@@ -101,6 +120,11 @@ export type BrowserSlice = {
   updateBrowserPageState: (pageId: string, updates: BrowserTabPageState) => void
   setBrowserTabUrl: (pageId: string, url: string) => void
   setBrowserPageUrl: (pageId: string, url: string) => void
+  setRemoteBrowserPageHandle: (pageId: string, handle: RemoteBrowserPageHandle) => void
+  removeRemoteBrowserPageHandle: (
+    pageId: string,
+    remotePageId?: string
+  ) => RemoteBrowserPageHandle | null
   setBrowserPageViewportPreset: (
     pageId: string,
     viewportPresetId: BrowserViewportPresetId | null
@@ -172,6 +196,23 @@ function normalizeBrowserTitle(title: string | null | undefined, url: string): s
   return title
 }
 
+function isRuntimeEnvironmentActive(state: AppState): boolean {
+  return Boolean(state.settings?.activeRuntimeEnvironmentId?.trim())
+}
+
+function closeRemoteBrowserPageInOwningEnvironment(
+  worktreeId: string,
+  handle: RemoteBrowserPageHandle
+): void {
+  const target: RuntimeClientTarget = { kind: 'environment', environmentId: handle.environmentId }
+  void callRuntimeRpc(
+    target,
+    'browser.tabClose',
+    { worktree: `id:${worktreeId}`, page: handle.remotePageId },
+    { timeoutMs: 15_000 }
+  ).catch(() => {})
+}
+
 function buildBrowserPage(
   workspaceId: string,
   worktreeId: string,
@@ -297,6 +338,7 @@ function findPage(
 export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> = (set, get) => ({
   browserTabsByWorktree: {},
   browserPagesByWorkspace: {},
+  remoteBrowserPageHandlesByPageId: {},
   activeBrowserTabId: null,
   activeBrowserTabIdByWorktree: {},
   recentlyClosedBrowserTabsByWorktree: {},
@@ -414,6 +456,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   closeBrowserTab: (tabId) => {
+    let remotePagesToClose: { worktreeId: string; handle: RemoteBrowserPageHandle }[] = []
     set((s) => {
       let owningWorktreeId: string | null = null
       let closedWorkspace: BrowserWorkspace | null = null
@@ -436,6 +479,16 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       const closedPages = s.browserPagesByWorkspace[tabId] ?? []
       const nextBrowserPagesByWorkspace = { ...s.browserPagesByWorkspace }
       delete nextBrowserPagesByWorkspace[tabId]
+      remotePagesToClose = closedPages.flatMap((page) => {
+        const handle = s.remoteBrowserPageHandlesByPageId[page.id]
+        return handle ? [{ worktreeId: page.worktreeId, handle }] : []
+      })
+      const nextRemoteBrowserPageHandlesByPageId = {
+        ...s.remoteBrowserPageHandlesByPageId
+      }
+      for (const page of closedPages) {
+        delete nextRemoteBrowserPageHandlesByPageId[page.id]
+      }
 
       const nextActiveBrowserTabIdByWorktree = { ...s.activeBrowserTabIdByWorktree }
       const remainingBrowserTabs = nextBrowserTabsByWorktree[owningWorktreeId] ?? []
@@ -506,10 +559,15 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         pendingAddressBarFocusByTabId: nextPendingAddressBarFocusByTabId,
         activeTabTypeByWorktree: nextActiveTabTypeByWorktree,
         recentlyClosedBrowserTabsByWorktree: nextRecentlyClosedBrowserTabsByWorktree,
-        recentlyClosedBrowserPagesByWorkspace: nextRecentlyClosedBrowserPagesByWorkspace
+        recentlyClosedBrowserPagesByWorkspace: nextRecentlyClosedBrowserPagesByWorkspace,
+        remoteBrowserPageHandlesByPageId: nextRemoteBrowserPageHandlesByPageId
       }
     })
 
+    for (const remotePage of remotePagesToClose) {
+      closeRemoteBrowserPageInOwningEnvironment(remotePage.worktreeId, remotePage.handle)
+    }
+
     for (const tabs of Object.values(get().unifiedTabsByWorktree)) {
       const workspaceItem = tabs.find(
         (entry) => entry.contentType === 'browser' && entry.entityId === tabId
@@ -643,7 +701,12 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
     // registerGuest uses page IDs (not workspace IDs), so we resolve the active
     // page within the workspace to find the correct browserPageId.
     const workspace = findWorkspace(get().browserTabsByWorktree, tabId)
-    if (workspace?.activePageId && typeof window !== 'undefined' && window.api?.browser) {
+    if (
+      workspace?.activePageId &&
+      !isRuntimeEnvironmentActive(get()) &&
+      typeof window !== 'undefined' &&
+      window.api?.browser
+    ) {
       window.api.browser
         .notifyActiveTabChanged({ browserPageId: workspace.activePageId })
         .catch(() => {})
@@ -723,6 +786,8 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   closeBrowserPage: (pageId) => {
+    let closedWorkspaceIdForLabel: string | null = null
+    const remotePagesToClose: { worktreeId: string; handle: RemoteBrowserPageHandle }[] = []
     set((s) => {
       const page = findPage(s.browserPagesByWorkspace, pageId)
       if (!page) {
@@ -732,6 +797,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       if (!workspace) {
         return s
       }
+      closedWorkspaceIdForLabel = page.workspaceId
       const currentPages = s.browserPagesByWorkspace[workspace.id] ?? []
       const nextPages = currentPages.filter((entry) => entry.id !== pageId)
       const closedIdx = currentPages.findIndex((entry) => entry.id === pageId)
@@ -747,6 +813,14 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         },
         nextPages
       )
+      const remoteHandle = s.remoteBrowserPageHandlesByPageId[pageId]
+      if (remoteHandle) {
+        remotePagesToClose.push({ worktreeId: page.worktreeId, handle: remoteHandle })
+      }
+      const nextRemoteBrowserPageHandlesByPageId = {
+        ...s.remoteBrowserPageHandlesByPageId
+      }
+      delete nextRemoteBrowserPageHandlesByPageId[pageId]
 
       return {
         browserPagesByWorkspace: {
@@ -777,18 +851,23 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
           Object.entries(s.pendingAddressBarFocusByTabId).filter(
             ([pendingPageId]) => pendingPageId !== pageId
           )
-        )
+        ),
+        remoteBrowserPageHandlesByPageId: nextRemoteBrowserPageHandlesByPageId
       }
     })
 
-    const page = findPage(get().browserPagesByWorkspace, pageId)
-    if (!page) {
+    for (const remotePage of remotePagesToClose) {
+      closeRemoteBrowserPageInOwningEnvironment(remotePage.worktreeId, remotePage.handle)
+    }
+
+    const closedWorkspaceId = closedWorkspaceIdForLabel
+    if (!closedWorkspaceId) {
       return
     }
-    const workspace = findWorkspace(get().browserTabsByWorktree, page.workspaceId)
+    const workspace = findWorkspace(get().browserTabsByWorktree, closedWorkspaceId)
     const item = Object.values(get().unifiedTabsByWorktree)
       .flat()
-      .find((entry) => entry.contentType === 'browser' && entry.entityId === page.workspaceId)
+      .find((entry) => entry.contentType === 'browser' && entry.entityId === closedWorkspaceId)
     if (item && workspace) {
       get().setTabLabel(item.id, workspace.title)
     }
@@ -852,7 +931,11 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
 
     // Why: switching the active page within a workspace changes which guest
     // webContents the CDP bridge should target for agent commands.
-    if (typeof window !== 'undefined' && window.api?.browser) {
+    if (
+      !isRuntimeEnvironmentActive(get()) &&
+      typeof window !== 'undefined' &&
+      window.api?.browser
+    ) {
       window.api.browser.notifyActiveTabChanged({ browserPageId: pageId }).catch(() => {})
     }
 
@@ -925,7 +1008,11 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
     // Why: notify the CDP bridge which guest webContents is now active so
     // subsequent agent commands target the correct page. Mirrors the
     // notifyActiveTabChanged calls in setActiveBrowserTab/setActiveBrowserPage.
-    if (typeof window !== 'undefined' && window.api?.browser) {
+    if (
+      !isRuntimeEnvironmentActive(get()) &&
+      typeof window !== 'undefined' &&
+      window.api?.browser
+    ) {
       window.api.browser.notifyActiveTabChanged({ browserPageId }).catch(() => {})
     }
 
@@ -1057,6 +1144,32 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       }
     }),
 
+  setRemoteBrowserPageHandle: (pageId, handle) => {
+    set((s) => ({
+      remoteBrowserPageHandlesByPageId: {
+        ...s.remoteBrowserPageHandlesByPageId,
+        [pageId]: handle
+      }
+    }))
+  },
+
+  removeRemoteBrowserPageHandle: (pageId, remotePageId) => {
+    let removedHandle: RemoteBrowserPageHandle | null = null
+    set((s) => {
+      const current = s.remoteBrowserPageHandlesByPageId[pageId]
+      if (!current || (remotePageId && current.remotePageId !== remotePageId)) {
+        return s
+      }
+      removedHandle = current
+      const nextRemoteBrowserPageHandlesByPageId = {
+        ...s.remoteBrowserPageHandlesByPageId
+      }
+      delete nextRemoteBrowserPageHandlesByPageId[pageId]
+      return { remoteBrowserPageHandlesByPageId: nextRemoteBrowserPageHandlesByPageId }
+    })
+    return removedHandle
+  },
+
   // viewportPresetId is a per-page setting on BrowserPage and is intentionally not
   // mirrored onto BrowserWorkspace: the outer tab strip doesn't surface the preset,
   // so there's no UI consumer at the workspace layer. Keeping it page-local avoids
@@ -1241,6 +1354,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         activeBrowserTabId,
         activeTabTypeByWorktree: nextActiveTabTypeByWorktree,
         activeTabType,
+        remoteBrowserPageHandlesByPageId: {},
         browserUrlHistory: normalizeBrowserHistoryEntries(session.browserUrlHistory ?? [])
       }
     })
@@ -1281,6 +1395,20 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   fetchBrowserSessionProfiles: async () => {
+    if (isRuntimeEnvironmentActive(get())) {
+      try {
+        const result = await callRuntimeRpc<BrowserProfileListResult>(
+          getActiveRuntimeTarget(get().settings),
+          'browser.profileList',
+          undefined,
+          { timeoutMs: 15_000 }
+        )
+        set({ browserSessionProfiles: result.profiles })
+      } catch {
+        set({ browserSessionProfiles: [] })
+      }
+      return
+    }
     try {
       const profiles = (await window.api.browser.sessionListProfiles()) as BrowserSessionProfile[]
       set({ browserSessionProfiles: profiles })
@@ -1290,6 +1418,25 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   createBrowserSessionProfile: async (scope, label) => {
+    if (isRuntimeEnvironmentActive(get())) {
+      try {
+        const result = await callRuntimeRpc<BrowserProfileCreateResult>(
+          getActiveRuntimeTarget(get().settings),
+          'browser.profileCreate',
+          { scope, label },
+          { timeoutMs: 15_000 }
+        )
+        const profile = result.profile
+        if (profile) {
+          set((s) => ({
+            browserSessionProfiles: [...s.browserSessionProfiles, profile]
+          }))
+        }
+        return profile
+      } catch {
+        return null
+      }
+    }
     try {
       const profile = (await window.api.browser.sessionCreateProfile({
         scope,
@@ -1307,6 +1454,27 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   deleteBrowserSessionProfile: async (profileId) => {
+    if (isRuntimeEnvironmentActive(get())) {
+      try {
+        const result = await callRuntimeRpc<BrowserProfileDeleteResult>(
+          getActiveRuntimeTarget(get().settings),
+          'browser.profileDelete',
+          { profileId },
+          { timeoutMs: 15_000 }
+        )
+        if (result.deleted) {
+          set((s) => ({
+            browserSessionProfiles: s.browserSessionProfiles.filter((p) => p.id !== profileId),
+            ...(s.defaultBrowserSessionProfileId === profileId
+              ? { defaultBrowserSessionProfileId: null }
+              : {})
+          }))
+        }
+        return result.deleted
+      } catch {
+        return false
+      }
+    }
     try {
       const ok = await window.api.browser.sessionDeleteProfile({ profileId })
       if (ok) {
@@ -1324,6 +1492,18 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   importCookiesToProfile: async (profileId) => {
+    if (isRuntimeEnvironmentActive(get())) {
+      const reason = 'Manual cookie file import is unavailable while a remote runtime is active.'
+      set({
+        browserSessionImportState: {
+          profileId,
+          status: 'error',
+          summary: null,
+          error: reason
+        }
+      })
+      return { ok: false as const, reason }
+    }
     set({
       browserSessionImportState: {
         profileId,
@@ -1381,6 +1561,20 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   detectedBrowsersLoaded: false,
 
   fetchDetectedBrowsers: async () => {
+    if (isRuntimeEnvironmentActive(get())) {
+      try {
+        const result = await callRuntimeRpc<BrowserDetectProfilesResult>(
+          getActiveRuntimeTarget(get().settings),
+          'browser.profileDetectBrowsers',
+          undefined,
+          { timeoutMs: 15_000 }
+        )
+        set({ detectedBrowsers: result.browsers, detectedBrowsersLoaded: true })
+      } catch {
+        set({ detectedBrowsers: [], detectedBrowsersLoaded: true })
+      }
+      return
+    }
     if (get().detectedBrowsersLoaded) {
       return
     }
@@ -1399,6 +1593,58 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   importCookiesFromBrowser: async (profileId, browserFamily, browserProfile?) => {
+    if (isRuntimeEnvironmentActive(get())) {
+      set({
+        browserSessionImportState: {
+          profileId,
+          status: 'importing',
+          summary: null,
+          error: null
+        }
+      })
+      try {
+        const result = await callRuntimeRpc<BrowserProfileImportFromBrowserResult>(
+          getActiveRuntimeTarget(get().settings),
+          'browser.profileImportFromBrowser',
+          { profileId, browserFamily, browserProfile },
+          { timeoutMs: 30_000 }
+        )
+        if (result.ok) {
+          set({
+            browserSessionImportState: {
+              profileId,
+              status: 'success',
+              summary: result.summary,
+              error: null
+            }
+          })
+          await get()
+            .fetchBrowserSessionProfiles()
+            .catch(() => {})
+        } else {
+          set({
+            browserSessionImportState: {
+              profileId,
+              status: 'error',
+              summary: null,
+              error: result.reason
+            }
+          })
+        }
+        return result
+      } catch (err) {
+        const reason = String((err as Error)?.message ?? err)
+        set({
+          browserSessionImportState: {
+            profileId,
+            status: 'error',
+            summary: null,
+            error: reason
+          }
+        })
+        return { ok: false as const, reason }
+      }
+    }
     set({
       browserSessionImportState: {
         profileId,
@@ -1451,6 +1697,22 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   clearDefaultSessionCookies: async () => {
+    if (isRuntimeEnvironmentActive(get())) {
+      try {
+        const result = await callRuntimeRpc<BrowserProfileClearDefaultCookiesResult>(
+          getActiveRuntimeTarget(get().settings),
+          'browser.profileClearDefaultCookies',
+          undefined,
+          { timeoutMs: 15_000 }
+        )
+        if (result.cleared) {
+          await get().fetchBrowserSessionProfiles()
+        }
+        return result.cleared
+      } catch {
+        return false
+      }
+    }
     try {
       const ok = await window.api.browser.sessionClearDefaultCookies()
       if (ok) {
diff --git a/src/renderer/src/store/slices/diffComments.test.ts b/src/renderer/src/store/slices/diffComments.test.ts
index 827d9e3831e..22ba47359e3 100644
--- a/src/renderer/src/store/slices/diffComments.test.ts
+++ b/src/renderer/src/store/slices/diffComments.test.ts
@@ -2,6 +2,11 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { create } from 'zustand'
 import type { AppState } from '../types'
 import type { DiffComment, Worktree } from '../../../../shared/types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
 
 // Mock sonner (imported transitively by other slices)
 vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }))
@@ -14,6 +19,13 @@ vi.mock('@/lib/agent-status', async (importOriginal) => {
 })
 
 const updateMeta = vi.fn().mockResolvedValue({})
+const runtimeEnvironmentCall = vi.fn().mockResolvedValue({
+  id: 'rpc-1',
+  ok: true,
+  result: { ok: true },
+  _meta: { runtimeId: 'remote-runtime' }
+})
+const runtimeEnvironmentTransportCall = vi.fn()
 const mockApi = {
   worktrees: {
     list: vi.fn().mockResolvedValue([]),
@@ -21,6 +33,7 @@ const mockApi = {
     remove: vi.fn().mockResolvedValue(undefined),
     updateMeta
   },
+  runtimeEnvironments: { call: runtimeEnvironmentTransportCall },
   repos: {
     list: vi.fn().mockResolvedValue([]),
     add: vi.fn().mockResolvedValue({}),
@@ -161,7 +174,18 @@ function seed(store: ReturnType<typeof createTestStore>, comments: DiffComment[]
 describe('updateDiffComment', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    clearRuntimeCompatibilityCacheForTests()
+    runtimeEnvironmentTransportCall.mockReset()
+    runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+      return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+    })
     updateMeta.mockResolvedValue({})
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { ok: true },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
   })
 
   it('updates the body, trims it, and persists', async () => {
@@ -189,6 +213,38 @@ describe('updateDiffComment', () => {
     expect(updateMeta).toHaveBeenCalledTimes(1)
   })
 
+  it('persists through the selected runtime environment', async () => {
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never
+    })
+    seed(store, [
+      {
+        id: 'c1',
+        worktreeId: WT,
+        filePath: 'src/foo.ts',
+        lineNumber: 10,
+        body: 'old body',
+        createdAt: 1000,
+        side: 'modified'
+      }
+    ])
+
+    const ok = await store.getState().updateDiffComment(WT, 'c1', 'remote body')
+
+    expect(ok).toBe(true)
+    expect(updateMeta).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'worktree.set',
+      params: {
+        worktree: WT,
+        diffComments: [expect.objectContaining({ id: 'c1', body: 'remote body' })]
+      },
+      timeoutMs: 15_000
+    })
+  })
+
   it('rejects an empty body without persisting', async () => {
     const store = createTestStore()
     seed(store, [
diff --git a/src/renderer/src/store/slices/diffComments.ts b/src/renderer/src/store/slices/diffComments.ts
index c9a8493cd90..7b776d2aa23 100644
--- a/src/renderer/src/store/slices/diffComments.ts
+++ b/src/renderer/src/store/slices/diffComments.ts
@@ -2,6 +2,7 @@ import type { StateCreator } from 'zustand'
 import type { AppState } from '../types'
 import type { DiffComment, Worktree } from '../../../../shared/types'
 import { findWorktreeById, getRepoIdFromWorktreeId } from './worktree-helpers'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '../../runtime/runtime-rpc-client'
 
 export type DiffCommentsSlice = {
   getDiffComments: (worktreeId: string | null | undefined) => DiffComment[]
@@ -22,11 +23,25 @@ function generateId(): string {
 // the sentinel from being corrupted globally.
 const EMPTY_COMMENTS: readonly DiffComment[] = Object.freeze([])
 
-async function persist(worktreeId: string, diffComments: DiffComment[]): Promise<void> {
-  await window.api.worktrees.updateMeta({
-    worktreeId,
-    updates: { diffComments }
-  })
+async function persist(
+  settings: AppState['settings'],
+  worktreeId: string,
+  diffComments: DiffComment[]
+): Promise<void> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind === 'local') {
+    await window.api.worktrees.updateMeta({
+      worktreeId,
+      updates: { diffComments }
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'worktree.set',
+    { worktree: worktreeId, diffComments },
+    { timeoutMs: 15_000 }
+  )
 }
 
 // Why: IPC writes from `persist` are not ordered with respect to each other.
@@ -55,7 +70,7 @@ function enqueuePersist(worktreeId: string, get: () => AppState): Promise<void>
     const repoList = get().worktreesByRepo[repoId]
     const target = repoList?.find((w) => w.id === worktreeId)
     const latest = target?.diffComments ?? []
-    await persist(worktreeId, latest)
+    await persist(get().settings, worktreeId, latest)
   }
   const next = prior.then(run, run)
   persistQueueByWorktree.set(worktreeId, next)
diff --git a/src/renderer/src/store/slices/editor.test.ts b/src/renderer/src/store/slices/editor.test.ts
index b7a3a50e6e1..875946f1d4a 100644
--- a/src/renderer/src/store/slices/editor.test.ts
+++ b/src/renderer/src/store/slices/editor.test.ts
@@ -4,6 +4,11 @@ import { createStore, type StoreApi } from 'zustand/vanilla'
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { createEditorSlice } from './editor'
 import type { AppState } from '../types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
 
 const { toastErrorMock } = vi.hoisted(() => ({
   toastErrorMock: vi.fn()
@@ -107,6 +112,203 @@ describe('createEditorSlice openDiff', () => {
   })
 })
 
+describe('createEditorSlice untitled cleanup routing', () => {
+  const runtimeEnvironmentCallMock = vi.fn()
+  const runtimeEnvironmentTransportCallMock = vi.fn()
+  const localDeletePathMock = vi.fn()
+
+  beforeEach(() => {
+    clearRuntimeCompatibilityCacheForTests()
+    runtimeEnvironmentCallMock.mockReset()
+    runtimeEnvironmentTransportCallMock.mockReset()
+    localDeletePathMock.mockReset()
+    runtimeEnvironmentCallMock.mockResolvedValue({ ok: true, result: { deleted: true } })
+    runtimeEnvironmentTransportCallMock.mockImplementation(
+      (args: RuntimeEnvironmentCallRequest) =>
+        createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCallMock(args)
+    )
+    vi.stubGlobal('window', {
+      api: {
+        runtimeEnvironments: { call: runtimeEnvironmentTransportCallMock },
+        fs: { deletePath: localDeletePathMock }
+      }
+    })
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  function seedRemoteWorktree(store: StoreApi<AppState>): void {
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      repos: [
+        {
+          id: 'repo1',
+          path: '/remote/repo',
+          displayName: 'Repo',
+          badgeColor: '#000',
+          addedAt: 0
+        }
+      ],
+      worktreesByRepo: {
+        repo1: [
+          {
+            id: 'wt-1',
+            repoId: 'repo1',
+            path: '/remote/wt',
+            branch: 'refs/heads/main',
+            head: 'abc',
+            isBare: false,
+            isMainWorktree: false,
+            displayName: 'main',
+            comment: '',
+            linkedIssue: null,
+            linkedPR: null,
+            linkedLinearIssue: null,
+            isArchived: false,
+            isUnread: false,
+            isPinned: false,
+            sortOrder: 0,
+            lastActivityAt: 0
+          }
+        ]
+      }
+    } as Partial<AppState>)
+  }
+
+  it('closeFile deletes untouched remote untitled files through runtime file RPC', async () => {
+    const store = createEditorStore()
+    seedRemoteWorktree(store)
+    store.getState().openFile({
+      filePath: '/remote/wt/untitled.md',
+      relativePath: 'untitled.md',
+      worktreeId: 'wt-1',
+      language: 'markdown',
+      isUntitled: true,
+      mode: 'edit'
+    })
+
+    store.getState().closeFile('/remote/wt/untitled.md')
+
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.delete',
+        params: { worktree: 'wt-1', relativePath: 'untitled.md', recursive: undefined },
+        timeoutMs: 15_000
+      })
+    })
+    expect(localDeletePathMock).not.toHaveBeenCalled()
+  })
+
+  it('closeAllFiles deletes untouched remote untitled files through runtime file RPC', async () => {
+    const store = createEditorStore()
+    seedRemoteWorktree(store)
+    store.getState().openFile({
+      filePath: '/remote/wt/untitled.md',
+      relativePath: 'untitled.md',
+      worktreeId: 'wt-1',
+      language: 'markdown',
+      isUntitled: true,
+      mode: 'edit'
+    })
+
+    store.getState().closeAllFiles()
+
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.delete',
+        params: { worktree: 'wt-1', relativePath: 'untitled.md', recursive: undefined },
+        timeoutMs: 15_000
+      })
+    })
+    expect(localDeletePathMock).not.toHaveBeenCalled()
+  })
+
+  it('closeFile uses relative remote delete when worktree metadata is missing', async () => {
+    const store = createEditorStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      repos: [],
+      worktreesByRepo: {}
+    } as Partial<AppState>)
+    store.getState().openFile({
+      filePath: '/remote/wt/untitled.md',
+      relativePath: 'untitled.md',
+      worktreeId: 'wt-1',
+      language: 'markdown',
+      isUntitled: true,
+      mode: 'edit'
+    })
+
+    store.getState().closeFile('/remote/wt/untitled.md')
+
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.delete',
+        params: { worktree: 'wt-1', relativePath: 'untitled.md', recursive: undefined },
+        timeoutMs: 15_000
+      })
+    })
+    expect(localDeletePathMock).not.toHaveBeenCalled()
+  })
+
+  it('closeFile deletes untouched remote untitled files in their owning runtime after switching local', async () => {
+    const store = createEditorStore()
+    seedRemoteWorktree(store)
+    store.getState().openFile({
+      filePath: '/remote/wt/untitled.md',
+      relativePath: 'untitled.md',
+      worktreeId: 'wt-1',
+      language: 'markdown',
+      isUntitled: true,
+      mode: 'edit'
+    })
+    store.setState({ settings: { activeRuntimeEnvironmentId: null } as never })
+
+    store.getState().closeFile('/remote/wt/untitled.md')
+
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.delete',
+        params: { worktree: 'wt-1', relativePath: 'untitled.md', recursive: undefined },
+        timeoutMs: 15_000
+      })
+    })
+    expect(localDeletePathMock).not.toHaveBeenCalled()
+  })
+
+  it('closeFile deletes untouched remote untitled files in their owning runtime after switching environments', async () => {
+    const store = createEditorStore()
+    seedRemoteWorktree(store)
+    store.getState().openFile({
+      filePath: '/remote/wt/untitled.md',
+      relativePath: 'untitled.md',
+      worktreeId: 'wt-1',
+      language: 'markdown',
+      isUntitled: true,
+      mode: 'edit'
+    })
+    store.setState({ settings: { activeRuntimeEnvironmentId: 'env-2' } as never })
+
+    store.getState().closeFile('/remote/wt/untitled.md')
+
+    await vi.waitFor(() => {
+      expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+        selector: 'env-1',
+        method: 'files.delete',
+        params: { worktree: 'wt-1', relativePath: 'untitled.md', recursive: undefined },
+        timeoutMs: 15_000
+      })
+    })
+    expect(localDeletePathMock).not.toHaveBeenCalled()
+  })
+})
+
 describe('createEditorSlice markdown view state', () => {
   it('updates stale language metadata when reopening an existing file', () => {
     const store = createEditorStore()
@@ -1047,13 +1249,30 @@ describe('createEditorSlice activateMarkdownLink', () => {
   const openFileUriMock = vi.fn()
   const pathExistsMock = vi.fn()
   const authorizeExternalPathMock = vi.fn()
+  const runtimeEnvironmentCallMock = vi.fn()
+  const runtimeEnvironmentTransportCallMock = vi.fn()
 
   beforeEach(() => {
+    clearRuntimeCompatibilityCacheForTests()
     toastErrorMock.mockReset()
     openUrlMock.mockReset()
     openFileUriMock.mockReset()
     pathExistsMock.mockReset()
+    pathExistsMock.mockResolvedValue(true)
     authorizeExternalPathMock.mockReset()
+    runtimeEnvironmentCallMock.mockReset()
+    runtimeEnvironmentTransportCallMock.mockReset()
+    runtimeEnvironmentCallMock.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { size: 1, isDirectory: false, mtime: 1 },
+      _meta: { runtimeId: 'runtime-source' }
+    })
+    runtimeEnvironmentTransportCallMock.mockImplementation(
+      (args: RuntimeEnvironmentCallRequest) =>
+        createCompatibleRuntimeStatusResponseIfNeeded(args, 'runtime-source') ??
+        runtimeEnvironmentCallMock(args)
+    )
     openHttpLinkMock.mockReset()
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ;(globalThis as any).window = (globalThis as any).window ?? {}
@@ -1065,7 +1284,17 @@ describe('createEditorSlice activateMarkdownLink', () => {
         pathExists: pathExistsMock
       },
       fs: {
-        authorizeExternalPath: authorizeExternalPathMock
+        authorizeExternalPath: authorizeExternalPathMock,
+        stat: vi.fn(async ({ filePath }: { filePath: string }) => {
+          const exists = await pathExistsMock(filePath)
+          if (!exists) {
+            throw new Error('File not found')
+          }
+          return { size: 1, isDirectory: false, mtime: 1 }
+        })
+      },
+      runtimeEnvironments: {
+        call: runtimeEnvironmentTransportCallMock
       }
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1100,6 +1329,70 @@ describe('createEditorSlice activateMarkdownLink', () => {
     expect(openUrlMock).not.toHaveBeenCalled()
   })
 
+  it('opens remote-owned markdown links through the source file runtime owner', async () => {
+    const store = createEditorStore()
+    pathExistsMock.mockResolvedValue(true)
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-active' } as AppState['settings']
+    })
+    store.getState().openFile({
+      filePath: '/repo/docs/note.md',
+      relativePath: 'docs/note.md',
+      worktreeId: 'wt-1',
+      runtimeEnvironmentId: 'env-source',
+      language: 'markdown',
+      mode: 'edit'
+    })
+
+    await store.getState().activateMarkdownLink('./guide.md', {
+      sourceFilePath: '/repo/docs/note.md',
+      worktreeId: 'wt-1',
+      worktreeRoot: '/repo'
+    })
+
+    expect(runtimeEnvironmentCallMock).toHaveBeenCalledWith({
+      selector: 'env-source',
+      method: 'files.stat',
+      params: { worktree: 'wt-1', relativePath: 'docs/guide.md' },
+      timeoutMs: 15_000
+    })
+    expect(store.getState().openFiles).toEqual([
+      expect.objectContaining({
+        filePath: '/repo/docs/note.md',
+        runtimeEnvironmentId: 'env-source'
+      }),
+      expect.objectContaining({
+        filePath: '/repo/docs/guide.md',
+        runtimeEnvironmentId: 'env-source',
+        mode: 'edit',
+        isPreview: true
+      })
+    ])
+  })
+
+  it('can open a file without adopting the currently active runtime owner', () => {
+    const store = createEditorStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-active' } as AppState['settings']
+    })
+
+    store.getState().openFile(
+      {
+        filePath: '/remote/.orca/drops/log.txt',
+        relativePath: '.orca/drops/log.txt',
+        worktreeId: 'wt-1',
+        language: 'text',
+        mode: 'edit'
+      },
+      { suppressActiveRuntimeFallback: true }
+    )
+
+    expect(store.getState().openFiles[0]).toMatchObject({
+      filePath: '/remote/.orca/drops/log.txt'
+    })
+    expect(store.getState().openFiles[0]?.runtimeEnvironmentId).toBeUndefined()
+  })
+
   it('toasts when the markdown target is missing', async () => {
     const store = createEditorStore()
     pathExistsMock.mockResolvedValue(false)
diff --git a/src/renderer/src/store/slices/editor.ts b/src/renderer/src/store/slices/editor.ts
index 04f77a127cc..4faba8b6fbc 100644
--- a/src/renderer/src/store/slices/editor.ts
+++ b/src/renderer/src/store/slices/editor.ts
@@ -23,6 +23,19 @@ import type {
 } from '../../../../shared/types'
 import { stripCredentialsFromMessage } from '../../../../shared/git-remote-error'
 import type { RemoteOpKind } from '@/components/right-sidebar/source-control-primary-action'
+import {
+  fetchRuntimeGit,
+  getRuntimeGitUpstreamStatus,
+  pullRuntimeGit,
+  pushRuntimeGit
+} from '@/runtime/runtime-git-client'
+import {
+  deleteRuntimePath,
+  deleteRuntimeRelativePath,
+  runtimePathExists
+} from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+import { findWorktreeById, getRepoIdFromWorktreeId } from './worktree-helpers'
 
 export type DiffSource =
   | 'unstaged'
@@ -91,6 +104,9 @@ export type OpenFile = {
   worktreeId: string
   language: string
   isDirty: boolean
+  // Why: remote untitled cleanup must target the environment that created the
+  // file, even if the user switches to Local or another runtime before closing.
+  runtimeEnvironmentId?: string
   /** Why: markdown preview tabs are separate editor tabs that mirror a source
    *  markdown file's live draft. Storing the source file ID lets the preview
    *  follow unsaved edits from the normal editor without becoming editable
@@ -199,7 +215,12 @@ export type EditorSlice = {
   setActiveTabType: (type: WorkspaceVisibleTabType) => void
   openFile: (
     file: Omit<OpenFile, 'id' | 'isDirty'>,
-    options?: { preview?: boolean; targetGroupId?: string; recordReplacedPreview?: boolean }
+    options?: {
+      preview?: boolean
+      targetGroupId?: string
+      recordReplacedPreview?: boolean
+      suppressActiveRuntimeFallback?: boolean
+    }
   ) => void
   // Why: dispatcher for markdown link activation. Lives on the slice because it
   // sequences openFile, setMarkdownViewMode, and setPendingEditorReveal around
@@ -207,10 +228,18 @@ export type EditorSlice = {
   // docs/markdown-internal-link-opening-design.md.
   activateMarkdownLink: (
     rawHref: string | undefined,
-    ctx: { sourceFilePath: string; worktreeId: string; worktreeRoot: string | null }
+    ctx: {
+      sourceFilePath: string
+      worktreeId: string
+      worktreeRoot: string | null
+      runtimeEnvironmentId?: string | null
+    }
   ) => Promise<void>
   openMarkdownPreview: (
-    file: Pick<OpenFile, 'filePath' | 'relativePath' | 'worktreeId' | 'language'>,
+    file: Pick<
+      OpenFile,
+      'filePath' | 'relativePath' | 'worktreeId' | 'language' | 'runtimeEnvironmentId'
+    >,
     options?: { anchor?: string | null; targetGroupId?: string }
   ) => void
   pinFile: (fileId: string, tabId?: string) => void
@@ -494,6 +523,31 @@ function resolveRemoteOperationErrorMessage(
   return error.message
 }
 
+function deleteUntouchedUntitledFile(state: AppState, file: OpenFile): void {
+  const worktree = findWorktreeById(state.worktreesByRepo, file.worktreeId)
+  const repoId = worktree?.repoId ?? getRepoIdFromWorktreeId(file.worktreeId)
+  const repo = state.repos.find((candidate) => candidate.id === repoId)
+  const owningRuntimeEnvironmentId = file.runtimeEnvironmentId?.trim()
+  // Why: untitled placeholders may live on a remote runtime or SSH target.
+  // Route through the runtime-aware client instead of assuming client-local FS.
+  const context = {
+    settings: owningRuntimeEnvironmentId
+      ? { activeRuntimeEnvironmentId: owningRuntimeEnvironmentId }
+      : state.settings,
+    worktreeId: file.worktreeId,
+    worktreePath: worktree?.path ?? null,
+    connectionId: repo?.connectionId ?? undefined
+  }
+  void deleteRuntimeRelativePath(context, file.relativePath)
+    .then((deletedRemotely) => {
+      if (!deletedRemotely && !owningRuntimeEnvironmentId) {
+        return deleteRuntimePath(context, file.filePath)
+      }
+      return undefined
+    })
+    .catch(() => {})
+}
+
 export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (set, get) => ({
   editorDrafts: {},
   setEditorDraft: (fileId, content) =>
@@ -606,6 +660,11 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       const id = file.filePath
       const existing = s.openFiles.find((f) => f.id === id)
       const worktreeId = file.worktreeId
+      const runtimeEnvironmentId =
+        file.runtimeEnvironmentId ??
+        (options?.suppressActiveRuntimeFallback
+          ? undefined
+          : (s.settings?.activeRuntimeEnvironmentId?.trim() ?? undefined))
       const isPreview = options?.preview ?? false
       const recordReplacedPreview = options?.recordReplacedPreview ?? false
       // Why: resolve the target group up-front so preview replacement can be
@@ -647,7 +706,8 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
           existing.isPreview !== updatedPreview ||
           existing.language !== file.language ||
           existing.relativePath !== file.relativePath ||
-          existing.worktreeId !== file.worktreeId
+          existing.worktreeId !== file.worktreeId ||
+          existing.runtimeEnvironmentId !== runtimeEnvironmentId
         if (!needsExistingUpdate) {
           return activeResult
         }
@@ -659,6 +719,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
                   relativePath: file.relativePath,
                   worktreeId: file.worktreeId,
                   language: file.language,
+                  runtimeEnvironmentId,
                   mode: file.mode,
                   diffSource: file.diffSource,
                   branchCompare: file.branchCompare,
@@ -729,7 +790,9 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
                 )
           // Replace in-place to preserve tab position
           newFiles = s.openFiles.map((f, i) =>
-            i === existingPreviewIdx ? { ...file, id, isDirty: false, isPreview: true } : f
+            i === existingPreviewIdx
+              ? { ...file, id, isDirty: false, isPreview: true, runtimeEnvironmentId }
+              : f
           )
           // Swap the old preview ID for the new one in the stored tab bar order
           const prevOrder = s.tabBarOrderByWorktree?.[worktreeId]
@@ -799,7 +862,13 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       return {
         openFiles: [
           ...newFiles,
-          { ...file, id, isDirty: false, isPreview: isPreview || undefined }
+          {
+            ...file,
+            id,
+            isDirty: false,
+            isPreview: isPreview || undefined,
+            runtimeEnvironmentId
+          }
         ],
         ...tabBarUpdate,
         ...activeResult
@@ -826,6 +895,8 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     set((s) => {
       const existing = s.openFiles.find((openFile) => openFile.id === id)
       const worktreeId = file.worktreeId
+      const runtimeEnvironmentId =
+        file.runtimeEnvironmentId ?? s.settings?.activeRuntimeEnvironmentId?.trim() ?? undefined
       const activeResult = {
         activeFileId: id,
         activeTabType: 'editor' as const,
@@ -851,6 +922,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
                       relativePath: file.relativePath,
                       worktreeId: file.worktreeId,
                       language: file.language,
+                      runtimeEnvironmentId,
                       markdownPreviewSourceFileId: file.filePath,
                       markdownPreviewAnchor: anchor,
                       mode: 'markdown-preview' as const
@@ -869,6 +941,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
         worktreeId: file.worktreeId,
         language: file.language,
         isDirty: false,
+        runtimeEnvironmentId,
         markdownPreviewSourceFileId: file.filePath,
         markdownPreviewAnchor: anchor,
         mode: 'markdown-preview'
@@ -1075,7 +1148,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     // tab without typing anything, the file is just clutter. Fire-and-forget
     // delete; failure (e.g. already removed externally) is harmless.
     if (shouldDeleteFromDisk && preClose && typeof window !== 'undefined') {
-      void window.api?.fs?.deletePath({ targetPath: preClose.filePath })?.catch(() => {})
+      deleteUntouchedUntitledFile(get(), preClose)
     }
 
     // Why: the unified tab model drives visual tab-bar order and next-active
@@ -1242,8 +1315,9 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       }
     })
     if (typeof window !== 'undefined') {
+      const postCloseState = get()
       for (const f of untitledToDelete) {
-        void window.api?.fs?.deletePath({ targetPath: f.filePath })?.catch(() => {})
+        deleteUntouchedUntitledFile(postCloseState, f)
       }
     }
     for (const itemId of closingItemIds) {
@@ -1904,7 +1978,9 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     }),
   fetchUpstreamStatus: async (worktreeId, worktreePath, connectionId) => {
     try {
-      const status = await window.api.git.upstreamStatus({
+      const status = await getRuntimeGitUpstreamStatus({
+        settings: get().settings,
+        worktreeId,
         worktreePath,
         connectionId
       })
@@ -1931,7 +2007,10 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     // store as soon as the IPC resolves.
     get().beginRemoteOperation(publish ? 'publish' : 'push')
     try {
-      await window.api.git.push({ worktreePath, publish, connectionId, pushTarget })
+      await pushRuntimeGit(
+        { settings: get().settings, worktreeId, worktreePath, connectionId },
+        { publish, pushTarget }
+      )
     } catch (error) {
       toast.error(resolveRemoteOperationErrorMessage(error, { publish, isPush: true }))
       throw error
@@ -1943,7 +2022,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
   pullBranch: async (worktreeId, worktreePath, connectionId) => {
     get().beginRemoteOperation('pull')
     try {
-      await window.api.git.pull({ worktreePath, connectionId })
+      await pullRuntimeGit({ settings: get().settings, worktreeId, worktreePath, connectionId })
     } catch (error) {
       toast.error(resolveRemoteOperationErrorMessage(error))
       throw error
@@ -1963,23 +2042,17 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     // outer catch must then skip toasting to avoid a double-toast.
     let pushStageToastShown = false
     try {
-      await window.api.git.fetch({ worktreePath, connectionId })
-      await window.api.git.pull({ worktreePath, connectionId })
+      const context = { settings: get().settings, worktreeId, worktreePath, connectionId }
+      await fetchRuntimeGit(context)
+      await pullRuntimeGit(context)
       // Why: push only if the pull left local commits that aren't on the
       // remote. After a merge pull the ahead count can be >0 (local commits +
       // the new merge commit) or 0 (pure fast-forward), and we avoid a
       // no-op push round-trip in the fast-forward case.
-      const upstreamStatus = await window.api.git.upstreamStatus({
-        worktreePath,
-        connectionId
-      })
+      const upstreamStatus = await getRuntimeGitUpstreamStatus(context)
       if (upstreamStatus.ahead > 0) {
         try {
-          await window.api.git.push({
-            worktreePath,
-            connectionId,
-            pushTarget
-          })
+          await pushRuntimeGit(context, { pushTarget })
         } catch (error) {
           // Why: format under the user-facing operation (sync) rather than
           // the inner step (push) — the user clicked Sync and shouldn't see
@@ -2010,7 +2083,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     // ahead/behind counts on the upstream-status payload.
     get().beginRemoteOperation('fetch')
     try {
-      await window.api.git.fetch({ worktreePath, connectionId })
+      await fetchRuntimeGit({ settings: get().settings, worktreeId, worktreePath, connectionId })
     } catch (error) {
       toast.error(resolveRemoteOperationErrorMessage(error))
       throw error
@@ -2142,6 +2215,11 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
   setPendingEditorReveal: (reveal) => set({ pendingEditorReveal: reveal }),
 
   activateMarkdownLink: async (rawHref, ctx) => {
+    const sourceRuntimeEnvironmentId =
+      ctx.runtimeEnvironmentId ??
+      get().openFiles.find((file) => file.filePath === ctx.sourceFilePath)?.runtimeEnvironmentId ??
+      null
+    const sourceSettings = settingsForRuntimeOwner(get().settings, sourceRuntimeEnvironmentId)
     const target = resolveMarkdownLinkTarget(rawHref, ctx.sourceFilePath, ctx.worktreeRoot)
     if (!target) {
       return
@@ -2155,6 +2233,13 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     }
     if (target.kind === 'file') {
       if (target.relativePath === undefined) {
+        if (sourceSettings?.activeRuntimeEnvironmentId?.trim()) {
+          // Why: a file:// link outside the worktree is a client-local escape
+          // hatch. Remote runtime editors must not authorize/open client paths
+          // as though the server could read them.
+          toast.error('External local file links are not available for remote runtime files yet.')
+          return
+        }
         // Why: terminal file links already authorize clicked external paths
         // before opening them in Orca. Markdown file:// links need the same
         // user-gesture authorization so /tmp screenshots can use ImageViewer.
@@ -2166,6 +2251,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
           filePath: target.absolutePath,
           relativePath: target.relativePath ?? target.absolutePath,
           worktreeId: ctx.worktreeId,
+          runtimeEnvironmentId: sourceRuntimeEnvironmentId ?? undefined,
           language: detectLanguage(target.absolutePath),
           mode: 'edit'
         },
@@ -2180,14 +2266,25 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
 
     // target.kind === 'markdown'
     const { absolutePath, relativePath, line, column } = target
-    const exists = await window.api.shell.pathExists(absolutePath)
+    const exists = await runtimePathExists(
+      {
+        settings: sourceSettings,
+        worktreeId: ctx.worktreeId,
+        worktreePath: ctx.worktreeRoot
+      },
+      absolutePath
+    )
     if (!exists) {
       toast.error(`File not found: ${relativePath}`)
       return
     }
 
     const state = get()
-    const existing = state.openFiles.find((f) => f.filePath === absolutePath)
+    const existing = state.openFiles.find(
+      (f) =>
+        f.filePath === absolutePath &&
+        (f.runtimeEnvironmentId ?? null) === sourceRuntimeEnvironmentId
+    )
     const fileId = existing?.id ?? absolutePath
 
     // Why: pendingEditorReveal is consumed by MonacoEditor on mount. If the
@@ -2205,6 +2302,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
           filePath: absolutePath,
           relativePath,
           worktreeId: ctx.worktreeId,
+          runtimeEnvironmentId: sourceRuntimeEnvironmentId ?? undefined,
           language: 'markdown',
           mode: 'edit'
         },
@@ -2272,6 +2370,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
             language: detectLanguage(pf.relativePath || pf.filePath),
             isDirty: false,
             isPreview: pf.isPreview,
+            runtimeEnvironmentId: pf.runtimeEnvironmentId,
             mode: 'edit'
           })
         }
diff --git a/src/renderer/src/store/slices/github.test.ts b/src/renderer/src/store/slices/github.test.ts
index 3229a588db2..6fbae94e642 100644
--- a/src/renderer/src/store/slices/github.test.ts
+++ b/src/renderer/src/store/slices/github.test.ts
@@ -6,13 +6,25 @@ import { create } from 'zustand'
 import { createGitHubSlice } from './github'
 import type { AppState } from '../types'
 import type { PRInfo } from '../../../../shared/types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
+
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
 
 const mockApi = {
   gh: {
     prForBranch: vi.fn().mockResolvedValue(null),
     issue: vi.fn().mockResolvedValue(null),
     prChecks: vi.fn().mockResolvedValue([]),
-    listWorkItems: vi.fn()
+    listWorkItems: vi.fn(),
+    getProjectViewTable: vi.fn()
+  },
+  runtimeEnvironments: {
+    call: runtimeEnvironmentTransportCall
   },
   cache: {
     getGitHub: vi.fn().mockResolvedValue(null),
@@ -23,6 +35,15 @@ const mockApi = {
 // @ts-expect-error test window mock
 globalThis.window = { api: mockApi }
 
+function resetRemoteRuntimeMocks() {
+  clearRuntimeCompatibilityCacheForTests()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+}
+
 function createTestStore() {
   return create<AppState>()(
     (...a) =>
@@ -49,6 +70,7 @@ function makePR(overrides: Partial<PRInfo> = {}): PRInfo {
 describe('createGitHubSlice.fetchPRChecks', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
     mockApi.gh.prChecks.mockResolvedValue([])
   })
 
@@ -230,6 +252,7 @@ describe('createGitHubSlice.fetchPRChecks', () => {
 describe('createGitHubSlice.fetchPRForBranch', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
     mockApi.gh.prForBranch.mockResolvedValue(null)
   })
 
@@ -265,6 +288,13 @@ describe('createGitHubSlice.fetchPRForBranch', () => {
 describe('createGitHubSlice.fetchWorkItems source/error envelope', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { items: [], sources: { issues: null, prs: null, upstreamCandidate: null } },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
   })
 
   it('stores resolved sources on the cache entry for the indicator to read', async () => {
@@ -342,6 +372,104 @@ describe('createGitHubSlice.fetchWorkItems source/error envelope', () => {
     const after = store.getState().getWorkItemsSourcesAndError('/repo', 24, '')
     expect(after.error).toBeNull()
   })
+
+  it('routes work item fetches through the active runtime environment', async () => {
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' },
+      repos: [
+        {
+          id: 'repo-id',
+          path: '/server/repo',
+          displayName: 'repo',
+          badgeColor: 'blue',
+          addedAt: 1
+        }
+      ]
+    } as Partial<AppState>)
+    runtimeEnvironmentCall.mockResolvedValueOnce({
+      id: 'rpc-1',
+      ok: true,
+      result: {
+        items: [{ type: 'issue', number: 7, title: 'Server issue', url: 'https://example.test/7' }],
+        sources: { issues: { owner: 'up', repo: 'r' }, prs: { owner: 'up', repo: 'r' } }
+      },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    await store.getState().fetchWorkItems('repo-id', '/server/repo', 24, '')
+
+    expect(mockApi.gh.listWorkItems).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'github.listWorkItems',
+      params: { repo: 'repo-id', limit: 24, query: undefined },
+      timeoutMs: 30_000
+    })
+    expect(store.getState().workItemsCache['/server/repo::24::'].data?.[0]).toMatchObject({
+      repoId: 'repo-id',
+      number: 7
+    })
+  })
+
+  it('routes project table fetches through the active runtime environment', async () => {
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' }
+    } as Partial<AppState>)
+    runtimeEnvironmentCall.mockResolvedValueOnce({
+      id: 'rpc-1',
+      ok: true,
+      result: {
+        ok: true,
+        data: {
+          project: {
+            id: 'project-1',
+            owner: 'acme',
+            ownerType: 'organization',
+            number: 1,
+            title: 'Roadmap',
+            url: 'https://github.com/orgs/acme/projects/1'
+          },
+          selectedView: {
+            id: 'view-1',
+            number: 1,
+            name: 'Table',
+            layout: 'TABLE_LAYOUT',
+            filter: '',
+            fields: [],
+            groupByFields: [],
+            sortByFields: []
+          },
+          rows: [],
+          totalCount: 0,
+          parentFieldDropped: false
+        }
+      },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+
+    const result = await store.getState().fetchProjectViewTable({
+      owner: 'acme',
+      ownerType: 'organization',
+      projectNumber: 1,
+      viewId: 'view-1'
+    })
+
+    expect(result.ok).toBe(true)
+    expect(mockApi.gh.getProjectViewTable).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'github.project.viewTable',
+      params: {
+        owner: 'acme',
+        ownerType: 'organization',
+        projectNumber: 1,
+        viewId: 'view-1'
+      },
+      timeoutMs: 60_000
+    })
+  })
 })
 
 describe('IssueSourceIndicator suppression', () => {
diff --git a/src/renderer/src/store/slices/github.ts b/src/renderer/src/store/slices/github.ts
index e77901aba9f..4f007e839f1 100644
--- a/src/renderer/src/store/slices/github.ts
+++ b/src/renderer/src/store/slices/github.ts
@@ -11,6 +11,7 @@ import type {
   IssueInfo,
   PRCheckDetail,
   PRComment,
+  Repo,
   Worktree,
   GitHubWorkItem
 } from '../../../../shared/types'
@@ -25,6 +26,7 @@ import type {
 } from '../../../../shared/github-project-types'
 import { sortWorkItemsByUpdatedAt, PER_REPO_FETCH_LIMIT } from '../../../../shared/work-items'
 import { syncPRChecksStatus } from './github-checks'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '../../runtime/runtime-rpc-client'
 
 // ─── ProjectV2 cache types ────────────────────────────────────────────
 // Why: declared separately from CacheEntry<T> (not a generified E parameter)
@@ -77,6 +79,18 @@ function queryOverrideKeyPart(queryOverride: string | undefined): string {
   return `:q=${queryOverride}`
 }
 
+function getRuntimeRepoTarget(
+  state: AppState,
+  repoPath: string
+): { target: { kind: 'environment'; environmentId: string }; repo: Repo } | null {
+  const target = getActiveRuntimeTarget(state.settings)
+  if (target.kind !== 'environment') {
+    return null
+  }
+  const repo = state.repos.find((candidate) => candidate.path === repoPath)
+  return repo ? { target, repo } : null
+}
+
 export function projectViewCacheKey(
   ownerType: GetProjectViewTableArgs['ownerType'],
   owner: string,
@@ -616,7 +630,16 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const request = (async (): Promise<GetProjectViewTableResult> => {
       await acquireWorkItemSlot()
       try {
-        const envelope = await window.api.gh.getProjectViewTable(args)
+        const target = getActiveRuntimeTarget(get().settings)
+        const envelope =
+          target.kind === 'environment'
+            ? await callRuntimeRpc<GetProjectViewTableResult>(
+                target,
+                'github.project.viewTable',
+                args,
+                { timeoutMs: 60_000 }
+              )
+            : await window.api.gh.getProjectViewTable(args)
         if (envelope.ok) {
           const table = envelope.data
           const key = projectViewCacheKey(
@@ -703,12 +726,26 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     }
     applyRowPatch(set, cacheKey, rowId, optimisticRow)
 
-    const result = await window.api.gh.updateProjectItemField({
-      projectId: table.project.id,
-      itemId: rowId,
-      fieldId,
-      value
-    })
+    const target = getActiveRuntimeTarget(get().settings)
+    const result =
+      target.kind === 'environment'
+        ? await callRuntimeRpc<GitHubProjectMutationResult>(
+            target,
+            'github.project.updateItemField',
+            {
+              projectId: table.project.id,
+              itemId: rowId,
+              fieldId,
+              value
+            },
+            { timeoutMs: 30_000 }
+          )
+        : await window.api.gh.updateProjectItemField({
+            projectId: table.project.id,
+            itemId: rowId,
+            fieldId,
+            value
+          })
     if (!result.ok) {
       rollbackRowIfPresent(set, get, cacheKey, rowId, previousRow)
     }
@@ -741,11 +778,24 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     }
     applyRowPatch(set, cacheKey, rowId, optimisticRow)
 
-    const result = await window.api.gh.clearProjectItemField({
-      projectId: table.project.id,
-      itemId: rowId,
-      fieldId
-    })
+    const target = getActiveRuntimeTarget(get().settings)
+    const result =
+      target.kind === 'environment'
+        ? await callRuntimeRpc<GitHubProjectMutationResult>(
+            target,
+            'github.project.clearItemField',
+            {
+              projectId: table.project.id,
+              itemId: rowId,
+              fieldId
+            },
+            { timeoutMs: 30_000 }
+          )
+        : await window.api.gh.clearProjectItemField({
+            projectId: table.project.id,
+            itemId: rowId,
+            fieldId
+          })
     if (!result.ok) {
       rollbackRowIfPresent(set, get, cacheKey, rowId, previousRow)
     }
@@ -820,11 +870,12 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     // PRs goes through updatePullRequestBySlug; for issues through
     // updateIssueBySlug. We dispatch both as needed.
     let envelope: GitHubProjectMutationResult = { ok: true }
+    const target = getActiveRuntimeTarget(get().settings)
     if (
       previousRow.itemType === 'PULL_REQUEST' &&
       (updates.title !== undefined || updates.body !== undefined)
     ) {
-      const prRes = await window.api.gh.updatePullRequestBySlug({
+      const args = {
         owner,
         repo,
         number,
@@ -832,7 +883,16 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           ...(updates.title !== undefined ? { title: updates.title } : {}),
           ...(updates.body !== undefined ? { body: updates.body } : {})
         }
-      })
+      }
+      const prRes =
+        target.kind === 'environment'
+          ? await callRuntimeRpc<GitHubProjectMutationResult>(
+              target,
+              'github.project.updatePullRequestBySlug',
+              args,
+              { timeoutMs: 30_000 }
+            )
+          : await window.api.gh.updatePullRequestBySlug(args)
       if (!prRes.ok) {
         envelope = prRes
       }
@@ -846,7 +906,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
         (previousRow.itemType === 'ISSUE' &&
           (updates.title !== undefined || updates.body !== undefined)))
     ) {
-      const issueRes = await window.api.gh.updateIssueBySlug({
+      const args = {
         owner,
         repo,
         number,
@@ -858,7 +918,16 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           ...(updates.addAssignees ? { addAssignees: updates.addAssignees } : {}),
           ...(updates.removeAssignees ? { removeAssignees: updates.removeAssignees } : {})
         }
-      })
+      }
+      const issueRes =
+        target.kind === 'environment'
+          ? await callRuntimeRpc<GitHubProjectMutationResult>(
+              target,
+              'github.project.updateIssueBySlug',
+              args,
+              { timeoutMs: 30_000 }
+            )
+          : await window.api.gh.updateIssueBySlug(args)
       if (!issueRes.ok) {
         envelope = issueRes
       }
@@ -899,12 +968,22 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       content: { ...previousRow.content, issueType }
     }
     applyRowPatch(set, cacheKey, rowId, optimistic)
-    const res = await window.api.gh.updateIssueTypeBySlug({
+    const target = getActiveRuntimeTarget(get().settings)
+    const args = {
       owner,
       repo,
       number,
       issueTypeId: issueType?.id ?? null
-    })
+    }
+    const res =
+      target.kind === 'environment'
+        ? await callRuntimeRpc<GitHubProjectMutationResult>(
+            target,
+            'github.project.updateIssueTypeBySlug',
+            args,
+            { timeoutMs: 30_000 }
+          )
+        : await window.api.gh.updateIssueTypeBySlug(args)
     if (!res.ok) {
       rollbackRowIfPresent(set, get, cacheKey, rowId, previousRow)
     }
@@ -1008,11 +1087,19 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const request = (async () => {
       await acquireWorkItemSlot()
       try {
-        const envelope = await window.api.gh.listWorkItems({
-          repoPath,
-          limit,
-          query: query || undefined
-        })
+        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
+        const envelope = runtimeRepo
+          ? await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.listWorkItems>>>(
+              runtimeRepo.target,
+              'github.listWorkItems',
+              { repo: runtimeRepo.repo.id, limit, query: query || undefined },
+              { timeoutMs: 30_000 }
+            )
+          : await window.api.gh.listWorkItems({
+              repoPath,
+              limit,
+              query: query || undefined
+            })
         // Why: stamp repoId at the renderer fetch boundary so every downstream
         // consumer (cross-repo merge, row rendering, drawer) can rely on the
         // field being present. Main doesn't know Orca's Repo.id.
@@ -1103,12 +1190,25 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       repos.map(async (r) => {
         await acquireWorkItemSlot()
         try {
-          const envelope = await window.api.gh.listWorkItems({
-            repoPath: r.path,
-            limit: perRepoLimit,
-            query: query || undefined,
-            before
-          })
+          const runtimeRepo = getRuntimeRepoTarget(get(), r.path)
+          const envelope = runtimeRepo
+            ? await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.listWorkItems>>>(
+                runtimeRepo.target,
+                'github.listWorkItems',
+                {
+                  repo: runtimeRepo.repo.id,
+                  limit: perRepoLimit,
+                  query: query || undefined,
+                  before
+                },
+                { timeoutMs: 30_000 }
+              )
+            : await window.api.gh.listWorkItems({
+                repoPath: r.path,
+                limit: perRepoLimit,
+                query: query || undefined,
+                before
+              })
           // Why: page-N partial failures don't participate in the cache's per-repo
           // error banner (which is keyed on the initial-fetch cache entry). Log the
           // classified issues-side error so pagination failures are at least
@@ -1140,10 +1240,18 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const counts = await Promise.all(
       repos.map(async (r) => {
         try {
-          return await window.api.gh.countWorkItems({
-            repoPath: r.path,
-            query: query || undefined
-          })
+          const runtimeRepo = getRuntimeRepoTarget(get(), r.path)
+          return runtimeRepo
+            ? await callRuntimeRpc<number>(
+                runtimeRepo.target,
+                'github.countWorkItems',
+                { repo: runtimeRepo.repo.id, query: query || undefined },
+                { timeoutMs: 30_000 }
+              )
+            : await window.api.gh.countWorkItems({
+                repoPath: r.path,
+                query: query || undefined
+              })
         } catch {
           return 0
         }
@@ -1201,7 +1309,15 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const linkedPRNumber = options?.linkedPRNumber ?? null
     const request = (async () => {
       try {
-        const pr = await window.api.gh.prForBranch({ repoPath, branch, linkedPRNumber })
+        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
+        const pr = runtimeRepo
+          ? await callRuntimeRpc<PRInfo | null>(
+              runtimeRepo.target,
+              'github.prForBranch',
+              { repo: runtimeRepo.repo.id, branch, linkedPRNumber },
+              { timeoutMs: 30_000 }
+            )
+          : await window.api.gh.prForBranch({ repoPath, branch, linkedPRNumber })
         if (prRequestGenerations.get(cacheKey) === generation) {
           set((s) => ({
             prCache: { ...s.prCache, [cacheKey]: { data: pr, fetchedAt: Date.now() } }
@@ -1248,7 +1364,15 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const request = (async () => {
       try {
-        const issue = await window.api.gh.issue({ repoPath, number })
+        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
+        const issue = runtimeRepo
+          ? await callRuntimeRpc<IssueInfo | null>(
+              runtimeRepo.target,
+              'github.issue',
+              { repo: runtimeRepo.repo.id, number },
+              { timeoutMs: 30_000 }
+            )
+          : await window.api.gh.issue({ repoPath, number })
         set((s) => ({
           issueCache: { ...s.issueCache, [cacheKey]: { data: issue, fetchedAt: Date.now() } }
         }))
@@ -1290,12 +1414,20 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const request = (async () => {
       try {
-        const checks = (await window.api.gh.prChecks({
-          repoPath,
-          prNumber,
-          headSha,
-          noCache: options?.force
-        })) as PRCheckDetail[]
+        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
+        const checks = runtimeRepo
+          ? await callRuntimeRpc<PRCheckDetail[]>(
+              runtimeRepo.target,
+              'github.prChecks',
+              { repo: runtimeRepo.repo.id, prNumber, headSha, noCache: options?.force },
+              { timeoutMs: 30_000 }
+            )
+          : ((await window.api.gh.prChecks({
+              repoPath,
+              prNumber,
+              headSha,
+              noCache: options?.force
+            })) as PRCheckDetail[])
         set((s) => {
           const nextState: Partial<AppState> = {
             checksCache: { ...s.checksCache, [cacheKey]: { data: checks, fetchedAt: Date.now() } }
@@ -1336,11 +1468,19 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const request = (async () => {
       try {
-        const comments = (await window.api.gh.prComments({
-          repoPath,
-          prNumber,
-          noCache: options?.force
-        })) as PRComment[]
+        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
+        const comments = runtimeRepo
+          ? await callRuntimeRpc<PRComment[]>(
+              runtimeRepo.target,
+              'github.prComments',
+              { repo: runtimeRepo.repo.id, prNumber, noCache: options?.force },
+              { timeoutMs: 30_000 }
+            )
+          : ((await window.api.gh.prComments({
+              repoPath,
+              prNumber,
+              noCache: options?.force
+            })) as PRComment[])
         set((s) => ({
           commentsCache: {
             ...s.commentsCache,
@@ -1378,7 +1518,15 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       }))
     }
 
-    const ok = await window.api.gh.resolveReviewThread({ repoPath, threadId, resolve })
+    const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
+    const ok = runtimeRepo
+      ? await callRuntimeRpc<boolean>(
+          runtimeRepo.target,
+          'github.resolveReviewThread',
+          { repo: runtimeRepo.repo.id, threadId, resolve },
+          { timeoutMs: 30_000 }
+        )
+      : await window.api.gh.resolveReviewThread({ repoPath, threadId, resolve })
     if (!ok && prev) {
       // Revert optimistic update on failure
       set((s) => ({
@@ -1529,10 +1677,11 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       // `repos:changed` broadcast → other windows re-fetch. The store layer
       // normalizes `'auto'` to `undefined` so the persisted record drops
       // the key entirely (see main/persistence.ts#updateRepo).
-      await window.api.repos.update({
-        repoId,
-        updates: { issueSourcePreference: preference === 'auto' ? undefined : preference }
-      })
+      const updates = { issueSourcePreference: preference === 'auto' ? undefined : preference }
+      const target = getActiveRuntimeTarget(get().settings)
+      await (target.kind === 'local'
+        ? window.api.repos.update({ repoId, updates })
+        : callRuntimeRpc(target, 'repo.update', { repo: repoId, updates }, { timeoutMs: 15_000 }))
     } catch (err) {
       console.error('Failed to persist issue-source preference:', err)
       // Why: surface the persist failure so the user understands why the
diff --git a/src/renderer/src/store/slices/hosted-review.test.ts b/src/renderer/src/store/slices/hosted-review.test.ts
index 08c217e3cba..3f90fb4bfbb 100644
--- a/src/renderer/src/store/slices/hosted-review.test.ts
+++ b/src/renderer/src/store/slices/hosted-review.test.ts
@@ -4,6 +4,20 @@ import type { AppState } from '../types'
 import { createHostedReviewSlice } from './hosted-review'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 
+const runtimeRpc = vi.hoisted(() => ({
+  callRuntimeRpc: vi.fn()
+}))
+
+vi.mock('@/runtime/runtime-rpc-client', () => ({
+  callRuntimeRpc: runtimeRpc.callRuntimeRpc,
+  getActiveRuntimeTarget: (
+    settings: { activeRuntimeEnvironmentId?: string | null } | null | undefined
+  ) => {
+    const environmentId = settings?.activeRuntimeEnvironmentId?.trim()
+    return environmentId ? { kind: 'environment', environmentId } : { kind: 'local' }
+  }
+}))
+
 const mockApi = {
   hostedReview: {
     forBranch: vi.fn()
@@ -12,9 +26,12 @@ const mockApi = {
 
 globalThis.window = { api: mockApi } as never
 
-function makeStore() {
-  return create<Pick<AppState, 'hostedReviewCache' | 'fetchHostedReviewForBranch'>>()((...args) =>
-    createHostedReviewSlice(...(args as Parameters<typeof createHostedReviewSlice>))
+function makeStore(settings: AppState['settings'] = null) {
+  return create<Pick<AppState, 'hostedReviewCache' | 'fetchHostedReviewForBranch' | 'settings'>>()(
+    (...args) => ({
+      settings,
+      ...createHostedReviewSlice(...(args as Parameters<typeof createHostedReviewSlice>))
+    })
   )
 }
 
@@ -32,6 +49,7 @@ const review: HostedReviewInfo = {
 describe('hosted review slice', () => {
   beforeEach(() => {
     mockApi.hostedReview.forBranch.mockReset()
+    runtimeRpc.callRuntimeRpc.mockReset()
   })
 
   it('fetches and caches branch review status through the common IPC surface', async () => {
@@ -56,4 +74,31 @@ describe('hosted review slice', () => {
       linkedBitbucketPR: null
     })
   })
+
+  it('routes active runtime review lookups through runtime RPC', async () => {
+    runtimeRpc.callRuntimeRpc.mockResolvedValueOnce(review)
+    const store = makeStore({
+      activeRuntimeEnvironmentId: 'env-win'
+    } as AppState['settings'])
+
+    await expect(
+      store.getState().fetchHostedReviewForBranch('C:\\repo', 'feature/windows', {
+        linkedGitHubPR: 12
+      })
+    ).resolves.toEqual(review)
+
+    expect(mockApi.hostedReview.forBranch).not.toHaveBeenCalled()
+    expect(runtimeRpc.callRuntimeRpc).toHaveBeenCalledWith(
+      { kind: 'environment', environmentId: 'env-win' },
+      'hostedReview.forBranch',
+      {
+        repo: 'C:\\repo',
+        branch: 'feature/windows',
+        linkedGitHubPR: 12,
+        linkedGitLabMR: null,
+        linkedBitbucketPR: null
+      },
+      { timeoutMs: 30_000 }
+    )
+  })
 })
diff --git a/src/renderer/src/store/slices/hosted-review.ts b/src/renderer/src/store/slices/hosted-review.ts
index 0abbc0733ac..39b545f62e2 100644
--- a/src/renderer/src/store/slices/hosted-review.ts
+++ b/src/renderer/src/store/slices/hosted-review.ts
@@ -1,5 +1,7 @@
 import type { StateCreator } from 'zustand'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
+import type { GlobalSettings } from '../../../../shared/types'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import type { AppState } from '../types'
 
 type CacheEntry<T> = { data: T | null; fetchedAt: number }
@@ -17,6 +19,16 @@ function isFresh<T>(entry: CacheEntry<T> | undefined): entry is CacheEntry<T> {
   return entry !== undefined && Date.now() - entry.fetchedAt < CACHE_TTL_MS
 }
 
+export function getHostedReviewCacheKey(
+  repoPath: string,
+  branch: string,
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+): string {
+  const target = getActiveRuntimeTarget(settings)
+  const scope = target.kind === 'environment' ? `runtime:${target.environmentId}` : 'local'
+  return `${scope}::${repoPath}::${branch}`
+}
+
 export type HostedReviewSlice = {
   hostedReviewCache: Record<string, CacheEntry<HostedReviewInfo>>
   fetchHostedReviewForBranch: (
@@ -41,7 +53,9 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
     branch,
     options
   ): Promise<HostedReviewInfo | null> => {
-    const cacheKey = `${repoPath}::${branch}`
+    const settings = get().settings
+    const target = getActiveRuntimeTarget(settings)
+    const cacheKey = getHostedReviewCacheKey(repoPath, branch, settings)
     const cached = get().hostedReviewCache[cacheKey]
     const linkedRefetch =
       cached?.data === null &&
@@ -62,13 +76,25 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
 
     const request = (async () => {
       try {
-        const review = await window.api.hostedReview.forBranch({
-          repoPath,
+        const args = {
           branch,
           linkedGitHubPR: options?.linkedGitHubPR ?? null,
           linkedGitLabMR: options?.linkedGitLabMR ?? null,
           linkedBitbucketPR: options?.linkedBitbucketPR ?? null
-        })
+        }
+        const review =
+          target.kind === 'environment'
+            ? await callRuntimeRpc<HostedReviewInfo | null>(
+                target,
+                'hostedReview.forBranch',
+                { repo: repoPath, ...args },
+                // Why: remote dev boxes can be slower at `git`/`gh` lookups
+                // than local desktop repos, especially on Windows filesystem
+                // paths. The main-process queue caps concurrency, so a longer
+                // timeout no longer risks a background socket stampede.
+                { timeoutMs: 30_000 }
+              )
+            : await window.api.hostedReview.forBranch({ repoPath, ...args })
         if (requestGenerations.get(cacheKey) === generation) {
           set((state) => ({
             hostedReviewCache: {
diff --git a/src/renderer/src/store/slices/linear.ts b/src/renderer/src/store/slices/linear.ts
index 34098ee337c..084c8e29cf9 100644
--- a/src/renderer/src/store/slices/linear.ts
+++ b/src/renderer/src/store/slices/linear.ts
@@ -3,6 +3,15 @@ import type { AppState } from '../types'
 import type { LinearViewer, LinearConnectionStatus, LinearIssue } from '../../../../shared/types'
 import type { CacheEntry } from './github'
 import { clearLinearMetadataCache } from '../../hooks/useIssueMetadata'
+import {
+  linearConnect,
+  linearDisconnect,
+  linearGetIssue,
+  linearListIssues,
+  linearSearchIssues,
+  linearStatus,
+  linearTestConnection
+} from '@/runtime/runtime-linear-client'
 
 const CACHE_TTL = 60_000 // 60s — same as GitHub work-items TTL
 const MAX_CACHE_ENTRIES = 500
@@ -67,7 +76,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
 
   checkLinearConnection: async () => {
     try {
-      const status = (await window.api.linear.status()) as LinearConnectionStatus
+      const status = (await linearStatus(get().settings)) as LinearConnectionStatus
       const prev = get().linearStatus
       if (prev.connected !== status.connected || prev.viewer?.email !== status.viewer?.email) {
         set({ linearStatus: status, linearStatusChecked: true })
@@ -85,7 +94,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
 
   testLinearConnection: async () => {
     try {
-      const result = (await window.api.linear.testConnection()) as
+      const result = (await linearTestConnection(get().settings)) as
         | { ok: true; viewer: LinearViewer }
         | { ok: false; error: string }
       if (result.ok) {
@@ -110,7 +119,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
 
   connectLinear: async (apiKey: string) => {
     try {
-      const result = await window.api.linear.connect({ apiKey })
+      const result = await linearConnect(get().settings, apiKey)
       if (result.ok) {
         set({
           linearStatus: {
@@ -127,7 +136,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
   },
 
   disconnectLinear: async () => {
-    await window.api.linear.disconnect()
+    await linearDisconnect(get().settings)
     inflightIssueRequests.clear()
     inflightSearchRequests.clear()
     inflightListRequests.clear()
@@ -150,8 +159,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
       return inflight
     }
 
-    const promise = window.api.linear
-      .getIssue({ id })
+    const promise = linearGetIssue(get().settings, id)
       .then((issue) => {
         const data = issue as LinearIssue | null
         set((s) => ({
@@ -189,8 +197,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
       return inflight
     }
 
-    const promise = window.api.linear
-      .searchIssues({ query, limit })
+    const promise = linearSearchIssues(get().settings, query, limit)
       .then((issues) => {
         const data = issues as LinearIssue[]
         set((s) => ({
@@ -228,8 +235,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
       return inflight
     }
 
-    const promise = window.api.linear
-      .listIssues({ filter, limit })
+    const promise = linearListIssues(get().settings, filter, limit)
       .then((issues) => {
         const data = issues as LinearIssue[]
         set((s) => ({
diff --git a/src/renderer/src/store/slices/repos.test.ts b/src/renderer/src/store/slices/repos.test.ts
new file mode 100644
index 00000000000..ea268eb5b0b
--- /dev/null
+++ b/src/renderer/src/store/slices/repos.test.ts
@@ -0,0 +1,256 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { createTestStore, makeWorktree } from './store-test-helpers'
+import type { Repo } from '../../../../shared/types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
+
+const localRepo: Repo = {
+  id: 'local-repo',
+  path: '/local',
+  displayName: 'Local',
+  badgeColor: '#000',
+  addedAt: 1
+}
+
+const remoteRepo: Repo = {
+  id: 'remote-repo',
+  path: '/remote',
+  displayName: 'Remote',
+  badgeColor: '#111',
+  addedAt: 2
+}
+
+const reposList = vi.fn()
+const reposAdd = vi.fn()
+const reposPickFolder = vi.fn()
+const reposRemove = vi.fn()
+const reposUpdate = vi.fn()
+const reposReorder = vi.fn()
+const ptyKill = vi.fn()
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  reposList.mockReset()
+  reposAdd.mockReset()
+  reposPickFolder.mockReset()
+  reposRemove.mockReset()
+  reposUpdate.mockReset()
+  reposReorder.mockReset()
+  ptyKill.mockReset()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      repos: {
+        list: reposList,
+        add: reposAdd,
+        pickFolder: reposPickFolder,
+        remove: reposRemove,
+        update: reposUpdate,
+        reorder: reposReorder
+      },
+      pty: { kill: ptyKill },
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCall }
+    }
+  })
+})
+
+describe('repo slice runtime routing', () => {
+  it('fetches repos from local IPC when no remote environment is active', async () => {
+    reposList.mockResolvedValue([localRepo])
+    const store = createTestStore()
+
+    await store.getState().fetchRepos()
+
+    expect(store.getState().repos).toEqual([localRepo])
+    expect(reposList).toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('fetches repos from the active remote runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { repos: [remoteRepo] },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      activeRepoId: 'stale-repo',
+      filterRepoIds: ['remote-repo', 'stale-repo']
+    })
+
+    await store.getState().fetchRepos()
+
+    expect(store.getState().repos).toEqual([remoteRepo])
+    expect(store.getState().activeRepoId).toBeNull()
+    expect(store.getState().filterRepoIds).toEqual(['remote-repo'])
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'repo.list',
+      params: undefined,
+      timeoutMs: 15_000
+    })
+    expect(reposList).not.toHaveBeenCalled()
+  })
+
+  it('updates repos through the active remote runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-2',
+      ok: true,
+      result: { repo: { ...remoteRepo, displayName: 'Renamed' } },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      repos: [remoteRepo]
+    })
+
+    await store.getState().updateRepo(remoteRepo.id, { displayName: 'Renamed' })
+
+    expect(store.getState().repos[0]?.displayName).toBe('Renamed')
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'repo.update',
+      params: { repo: remoteRepo.id, updates: { displayName: 'Renamed' } },
+      timeoutMs: 15_000
+    })
+    expect(reposUpdate).not.toHaveBeenCalled()
+  })
+
+  it('adds explicit server paths through the active remote runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-add',
+      ok: true,
+      result: { repo: remoteRepo },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never
+    })
+
+    await expect(store.getState().addRepoPath('/srv/project', 'folder')).resolves.toEqual(
+      remoteRepo
+    )
+
+    expect(store.getState().repos).toEqual([remoteRepo])
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'repo.add',
+      params: { path: '/srv/project', kind: 'folder' },
+      timeoutMs: 15_000
+    })
+    expect(reposAdd).not.toHaveBeenCalled()
+    expect(reposPickFolder).not.toHaveBeenCalled()
+  })
+
+  it('does not open the client folder picker when a remote runtime environment is active', async () => {
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never
+    })
+
+    await expect(store.getState().addRepo()).resolves.toBeNull()
+
+    expect(reposPickFolder).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+
+  it('removes repos through the active remote runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-3',
+      ok: true,
+      result: { removed: true },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      repos: [remoteRepo],
+      activeRepoId: remoteRepo.id
+    })
+
+    await store.getState().removeRepo(remoteRepo.id)
+
+    expect(store.getState().repos).toEqual([])
+    expect(store.getState().activeRepoId).toBeNull()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'repo.rm',
+      params: { repo: remoteRepo.id },
+      timeoutMs: 15_000
+    })
+    expect(reposRemove).not.toHaveBeenCalled()
+  })
+
+  it('stops remote runtime terminals instead of killing remote ids through local pty IPC', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-remote',
+      ok: true,
+      result: { ok: true },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    const store = createTestStore()
+    const worktreeId = `${remoteRepo.id}::/remote/wt`
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      repos: [remoteRepo],
+      worktreesByRepo: {
+        [remoteRepo.id]: [makeWorktree({ id: worktreeId, repoId: remoteRepo.id })]
+      },
+      tabsByWorktree: {
+        [worktreeId]: [{ id: 'tab-1', worktreeId } as never]
+      },
+      ptyIdsByTabId: {
+        'tab-1': ['remote:term-1', 'pty-local-stale']
+      }
+    })
+
+    await store.getState().removeRepo(remoteRepo.id)
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'terminal.stop',
+      params: { worktree: worktreeId },
+      timeoutMs: 15_000
+    })
+    expect(ptyKill).toHaveBeenCalledWith('pty-local-stale')
+    expect(ptyKill).not.toHaveBeenCalledWith('remote:term-1')
+  })
+
+  it('reorders repos through the active remote runtime environment', async () => {
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-4',
+      ok: true,
+      result: { status: 'applied' },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      repos: [localRepo, remoteRepo]
+    })
+
+    await store.getState().reorderRepos([remoteRepo.id, localRepo.id])
+
+    expect(store.getState().repos.map((repo) => repo.id)).toEqual([remoteRepo.id, localRepo.id])
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'repo.reorder',
+      params: { orderedIds: [remoteRepo.id, localRepo.id] },
+      timeoutMs: 15_000
+    })
+    expect(reposReorder).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/store/slices/repos.ts b/src/renderer/src/store/slices/repos.ts
index 78977a17b7d..0cc50b4bc84 100644
--- a/src/renderer/src/store/slices/repos.ts
+++ b/src/renderer/src/store/slices/repos.ts
@@ -1,9 +1,14 @@
+/* eslint-disable max-lines -- Why: repo slice owns local/runtime routing,
+add/remove/reorder side effects, and cross-slice teardown. Splitting it during
+the client-server refactor would obscure the invariants this file is currently
+auditing and preserving. */
 import type { StateCreator } from 'zustand'
 import { toast } from 'sonner'
 import type { AppState } from '../types'
 import type { Repo } from '../../../../shared/types'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import { getRepoIdFromWorktreeId } from './worktree-helpers'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '../../runtime/runtime-rpc-client'
 
 const ERROR_TOAST_DURATION = 60_000
 
@@ -12,6 +17,7 @@ export type RepoSlice = {
   activeRepoId: string | null
   fetchRepos: () => Promise<void>
   addRepo: () => Promise<Repo | null>
+  addRepoPath: (path: string, kind?: 'git' | 'folder') => Promise<Repo | null>
   addNonGitFolder: (path: string) => Promise<Repo | null>
   removeRepo: (repoId: string) => Promise<void>
   updateRepo: (
@@ -39,7 +45,21 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   fetchRepos: async () => {
     try {
-      const repos = await window.api.repos.list()
+      const target = getActiveRuntimeTarget(get().settings)
+      const repos =
+        target.kind === 'local'
+          ? ((await window.api.repos.list()) as Repo[])
+          : (
+              await callRuntimeRpc<{ repos: Repo[] }>(
+                target,
+                'repo.list',
+                undefined,
+                // Why: remote environment fetches cross the network; keep the
+                // boot-time repo hydration bounded instead of inheriting an
+                // unbounded renderer promise.
+                { timeoutMs: 15_000 }
+              )
+            ).repos
       set((s) => {
         const validRepoIds = new Set(repos.map((repo) => repo.id))
         return {
@@ -53,22 +73,30 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     }
   },
 
-  addRepo: async () => {
+  addRepoPath: async (path, kind = 'git') => {
     try {
-      const path = await window.api.repos.pickFolder()
-      if (!path) {
-        return null
-      }
+      const target = getActiveRuntimeTarget(get().settings)
       let repo: Repo
       try {
-        const result = await window.api.repos.add({ path })
-        if ('error' in result) {
-          throw new Error(result.error)
+        if (target.kind === 'local') {
+          const result = await window.api.repos.add({ path, kind })
+          if ('error' in result) {
+            throw new Error(result.error)
+          }
+          repo = result.repo
+        } else {
+          repo = (
+            await callRuntimeRpc<{ repo: Repo }>(
+              target,
+              'repo.add',
+              { path, kind },
+              { timeoutMs: 15_000 }
+            )
+          ).repo
         }
-        repo = result.repo
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
-        if (!message.includes('Not a valid git repository')) {
+        if (kind !== 'git' || !message.includes('Not a valid git repository')) {
           throw err
         }
         // Why: folder mode is a capability downgrade, not a silent fallback.
@@ -109,27 +137,26 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     }
   },
 
+  addRepo: async () => {
+    const target = getActiveRuntimeTarget(get().settings)
+    if (target.kind !== 'local') {
+      // Why: OS folder pickers return client-local paths. Remote environments
+      // need an explicit server path, which the Add Project dialog handles.
+      toast.error('Use a server path to add projects from a remote runtime.')
+      return null
+    }
+    const path = await window.api.repos.pickFolder()
+    if (!path) {
+      return null
+    }
+    return get().addRepoPath(path)
+  },
+
   addNonGitFolder: async (path) => {
     try {
-      const result = await window.api.repos.add({ path, kind: 'folder' })
-      if ('error' in result) {
-        throw new Error(result.error)
-      }
-      const repo = result.repo
-      const alreadyAdded = get().repos.some((r) => r.id === repo.id)
-      if (alreadyAdded) {
-        get().clearOrcaHookTrustForRepo(repo.id)
-      }
-      set((s) => {
-        if (s.repos.some((r) => r.id === repo.id)) {
-          return s
-        }
-        return { repos: [...s.repos, repo] }
-      })
-      if (alreadyAdded) {
-        toast.info('Project already added', { description: repo.displayName })
-      } else {
-        toast.success('Folder added', { description: repo.displayName })
+      const repo = await get().addRepoPath(path, 'folder')
+      if (!repo) {
+        return null
       }
       // Why: without focusing the new folder, the UI looks unchanged after
       // the dialog closes and users think nothing happened. Fetch the
@@ -154,7 +181,10 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   removeRepo: async (repoId) => {
     try {
-      await window.api.repos.remove({ repoId })
+      const target = getActiveRuntimeTarget(get().settings)
+      await (target.kind === 'local'
+        ? window.api.repos.remove({ repoId })
+        : callRuntimeRpc(target, 'repo.rm', { repo: repoId }, { timeoutMs: 15_000 }))
 
       get().clearOrcaHookTrustForRepo(repoId)
 
@@ -162,13 +192,22 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       const worktreeIds = (get().worktreesByRepo[repoId] ?? []).map((w) => w.id)
       const killedTabIds = new Set<string>()
       const killedPtyIds = new Set<string>()
+      if (target.kind === 'environment') {
+        await Promise.allSettled(
+          worktreeIds.map((worktreeId) =>
+            callRuntimeRpc(target, 'terminal.stop', { worktree: worktreeId }, { timeoutMs: 15_000 })
+          )
+        )
+      }
       for (const wId of worktreeIds) {
         const tabs = get().tabsByWorktree[wId] ?? []
         for (const tab of tabs) {
           killedTabIds.add(tab.id)
           for (const ptyId of get().ptyIdsByTabId[tab.id] ?? []) {
             killedPtyIds.add(ptyId)
-            window.api.pty.kill(ptyId)
+            if (!ptyId.startsWith('remote:')) {
+              window.api.pty.kill(ptyId)
+            }
           }
         }
       }
@@ -259,7 +298,10 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   updateRepo: async (repoId, updates) => {
     try {
-      await window.api.repos.update({ repoId, updates })
+      const target = getActiveRuntimeTarget(get().settings)
+      await (target.kind === 'local'
+        ? window.api.repos.update({ repoId, updates })
+        : callRuntimeRpc(target, 'repo.update', { repo: repoId, updates }, { timeoutMs: 15_000 }))
       set((s) => ({
         repos: s.repos.map((r) => (r.id === repoId ? { ...r, ...updates } : r))
       }))
@@ -288,7 +330,16 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     }
     set({ repos: next })
     try {
-      const result = await window.api.repos.reorder({ orderedIds })
+      const target = getActiveRuntimeTarget(get().settings)
+      const result =
+        target.kind === 'local'
+          ? await window.api.repos.reorder({ orderedIds })
+          : await callRuntimeRpc<{ status: 'applied' | 'rejected' }>(
+              target,
+              'repo.reorder',
+              { orderedIds },
+              { timeoutMs: 15_000 }
+            )
       if (result.status === 'rejected') {
         await get().fetchRepos()
       }
diff --git a/src/renderer/src/store/slices/settings.test.ts b/src/renderer/src/store/slices/settings.test.ts
new file mode 100644
index 00000000000..9d0bc5e5476
--- /dev/null
+++ b/src/renderer/src/store/slices/settings.test.ts
@@ -0,0 +1,246 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { createTestStore, makeWorktree } from './store-test-helpers'
+import type { AppState } from '../types'
+import { toast } from 'sonner'
+import {
+  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from '../../../../shared/protocol-version'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
+
+vi.mock('sonner', () => ({ toast: { error: vi.fn(), success: vi.fn(), info: vi.fn() } }))
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    detectAgentStatusFromTitle: vi.fn().mockReturnValue(null)
+  }
+})
+
+const runtimeEnvironmentCall = vi.fn()
+const settingsSet = vi.fn().mockResolvedValue(undefined)
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  vi.clearAllMocks()
+  runtimeEnvironmentCall.mockImplementation(({ method }: { method: string }) => {
+    const result =
+      method === 'status.get'
+        ? {
+            runtimeId: 'runtime-2',
+            graphStatus: 'ready',
+            runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+            minCompatibleRuntimeClientVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
+          }
+        : method === 'repo.list'
+          ? {
+              repos: [
+                {
+                  id: 'repo-env-2',
+                  path: '/env-2/repo',
+                  displayName: 'Env 2',
+                  badgeColor: 'blue',
+                  addedAt: 1
+                }
+              ]
+            }
+          : method === 'worktree.list'
+            ? {
+                worktrees: [
+                  makeWorktree({
+                    id: 'repo-env-2::/env-2/repo',
+                    repoId: 'repo-env-2',
+                    path: '/env-2/repo'
+                  })
+                ],
+                totalCount: 1,
+                truncated: false
+              }
+            : method === 'browser.profile.list'
+              ? { profiles: [] }
+              : {}
+    return Promise.resolve({ id: 'rpc-1', ok: true, result, _meta: { runtimeId: 'runtime-2' } })
+  })
+  vi.stubGlobal('window', {
+    api: {
+      settings: { set: settingsSet },
+      runtimeEnvironments: { call: runtimeEnvironmentCall }
+    }
+  })
+})
+
+describe('createSettingsSlice runtime switching', () => {
+  it('clears stale runtime-owned state before loading the selected environment', async () => {
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as AppState['settings'],
+      repos: [{ id: 'repo-env-1', path: '/env-1/repo', displayName: 'Env 1' } as never],
+      worktreesByRepo: {
+        'repo-env-1': [makeWorktree({ id: 'repo-env-1::/env-1/repo', repoId: 'repo-env-1' })]
+      },
+      activeWorktreeId: 'repo-env-1::/env-1/repo',
+      openFiles: [{ id: '/env-1/repo/a.md', worktreeId: 'repo-env-1::/env-1/repo' } as never],
+      ptyIdsByTabId: { tab1: ['remote:env-1@@terminal-a'] },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: null,
+          activeLeafId: null,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { 'pane:1': 'remote:legacy-terminal' }
+        }
+      },
+      browserTabsByWorktree: { 'repo-env-1::/env-1/repo': [{ id: 'browser-env-1' }] as never },
+      browserPagesByWorkspace: {
+        'browser-env-1': [{ id: 'page-env-1', worktreeId: 'repo-env-1::/env-1/repo' }] as never
+      },
+      remoteBrowserPageHandlesByPageId: {
+        'page-env-1': { environmentId: 'env-1', remotePageId: 'remote-page-1' }
+      },
+      editorDrafts: { '/env-1/repo/stale.md': 'stale' },
+      markdownViewMode: { '/env-1/repo/stale.md': 'rich' },
+      editorViewMode: { '/env-1/repo/stale.md': 'changes' },
+      editorCursorLine: { '/env-1/repo/stale.md': 4 },
+      prCache: { '/env-1/repo::main': { data: null, fetchedAt: Date.now() } },
+      linearIssueCache: { 'LIN-1': { data: { id: 'LIN-1' } as never, fetchedAt: Date.now() } }
+    })
+
+    await expect(store.getState().switchRuntimeEnvironment('env-2')).resolves.toBe(true)
+
+    expect(settingsSet).toHaveBeenCalledWith({ activeRuntimeEnvironmentId: 'env-2' })
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({ selector: 'env-2', method: 'status.get' })
+    )
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({ selector: 'env-2', method: 'repo.list' })
+    )
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'terminal.close',
+        params: { terminal: 'terminal-a' }
+      })
+    )
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'terminal.close',
+        params: { terminal: 'legacy-terminal' }
+      })
+    )
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'browser.tabClose',
+        params: { worktree: 'id:repo-env-1::/env-1/repo', page: 'remote-page-1' }
+      })
+    )
+    expect(store.getState().repos.map((repo) => repo.id)).toEqual(['repo-env-2'])
+    expect(store.getState().worktreesByRepo['repo-env-2']?.map((worktree) => worktree.id)).toEqual([
+      'repo-env-2::/env-2/repo'
+    ])
+    expect(store.getState().activeWorktreeId).toBeNull()
+    expect(store.getState().openFiles).toEqual([])
+    expect(store.getState().editorDrafts).toEqual({})
+    expect(store.getState().markdownViewMode).toEqual({})
+    expect(store.getState().editorViewMode).toEqual({})
+    expect(store.getState().editorCursorLine).toEqual({})
+    expect(store.getState().ptyIdsByTabId).toEqual({})
+    expect(store.getState().browserTabsByWorktree).toEqual({})
+    expect(store.getState().prCache).toEqual({})
+    expect(store.getState().linearIssueCache).toEqual({})
+  })
+
+  it('refuses to switch environments while editor tabs have unsaved state', async () => {
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as AppState['settings'],
+      openFiles: [
+        {
+          id: '/env-1/repo/dirty.md',
+          worktreeId: 'repo-env-1::/env-1/repo',
+          isDirty: true
+        } as never
+      ],
+      editorDrafts: { '/env-1/repo/dirty.md': 'draft' }
+    })
+
+    await expect(store.getState().switchRuntimeEnvironment('env-2')).resolves.toBe(false)
+
+    expect(settingsSet).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+    expect(store.getState().settings?.activeRuntimeEnvironmentId).toBe('env-1')
+    expect(store.getState().openFiles).toHaveLength(1)
+    expect(store.getState().editorDrafts).toEqual({ '/env-1/repo/dirty.md': 'draft' })
+    expect(toast.error).toHaveBeenCalledWith(
+      'Save or close unsaved editor tabs before switching servers.'
+    )
+  })
+
+  it('keeps the current environment when the selected remote server is unreachable', async () => {
+    runtimeEnvironmentCall.mockRejectedValueOnce(
+      new Error('Remote Orca runtime closed the connection.')
+    )
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as AppState['settings'],
+      repos: [{ id: 'repo-env-1', path: '/env-1/repo', displayName: 'Env 1' } as never],
+      openFiles: [],
+      ptyIdsByTabId: { tab1: ['remote:env-1@@terminal-a'] }
+    })
+
+    await expect(store.getState().switchRuntimeEnvironment('env-2')).resolves.toBe(false)
+
+    expect(settingsSet).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({ selector: 'env-2', method: 'status.get' })
+    )
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalledWith(
+      expect.objectContaining({ selector: 'env-1', method: 'terminal.close' })
+    )
+    expect(store.getState().settings?.activeRuntimeEnvironmentId).toBe('env-1')
+    expect(store.getState().repos.map((repo) => repo.id)).toEqual(['repo-env-1'])
+    expect(store.getState().ptyIdsByTabId).toEqual({ tab1: ['remote:env-1@@terminal-a'] })
+    expect(toast.error).toHaveBeenCalledWith('Failed to switch servers', {
+      description: 'Remote Orca runtime closed the connection.'
+    })
+  })
+
+  it('keeps the current environment when the selected server is protocol-incompatible', async () => {
+    runtimeEnvironmentCall.mockImplementation(({ method }: { method: string }) => {
+      const result =
+        method === 'status.get'
+          ? {
+              runtimeId: 'runtime-old',
+              graphStatus: 'ready',
+              runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION - 1,
+              minCompatibleRuntimeClientVersion: 0
+            }
+          : {}
+      return Promise.resolve({
+        id: 'rpc-1',
+        ok: true,
+        result,
+        _meta: { runtimeId: 'runtime-old' }
+      })
+    })
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as AppState['settings'],
+      repos: [{ id: 'repo-env-1', path: '/env-1/repo', displayName: 'Env 1' } as never],
+      openFiles: []
+    })
+
+    await expect(store.getState().switchRuntimeEnvironment('env-old')).resolves.toBe(false)
+
+    expect(settingsSet).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({ selector: 'env-old', method: 'status.get' })
+    )
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalledWith(
+      expect.objectContaining({ selector: 'env-old', method: 'repo.list' })
+    )
+    expect(toast.error).toHaveBeenCalledWith('Failed to switch servers', {
+      description: expect.stringContaining('server is too old')
+    })
+  })
+})
diff --git a/src/renderer/src/store/slices/settings.ts b/src/renderer/src/store/slices/settings.ts
index 8307e594667..eb11cbf64f6 100644
--- a/src/renderer/src/store/slices/settings.ts
+++ b/src/renderer/src/store/slices/settings.ts
@@ -1,6 +1,12 @@
 import type { StateCreator } from 'zustand'
 import type { AppState } from '../types'
 import type { GlobalSettings } from '../../../../shared/types'
+import { toast } from 'sonner'
+import { callRuntimeRpc, clearRuntimeCompatibilityCache } from '@/runtime/runtime-rpc-client'
+import {
+  getRemoteRuntimePtyEnvironmentId,
+  getRemoteRuntimeTerminalHandle
+} from '@/runtime/runtime-terminal-stream'
 import { normalizeTerminalQuickCommands } from '../../../../shared/terminal-quick-commands'
 
 export type SettingsSlice = {
@@ -9,9 +15,199 @@ export type SettingsSlice = {
   setSettingsSearchQuery: (q: string) => void
   fetchSettings: () => Promise<void>
   updateSettings: (updates: Partial<GlobalSettings>) => Promise<void>
+  switchRuntimeEnvironment: (environmentId: string | null) => Promise<boolean>
 }
 
-export const createSettingsSlice: StateCreator<AppState, [], [], SettingsSlice> = (set) => ({
+function normalizeRuntimeEnvironmentId(value: string | null | undefined): string | null {
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : null
+}
+
+function runtimeScopedStateReset(): Partial<AppState> {
+  return {
+    repos: [],
+    activeRepoId: null,
+    sparsePresetsByRepo: {},
+    sparsePresetsLoadingByRepo: {},
+    sparsePresetsLoadStatusByRepo: {},
+    sparsePresetsErrorByRepo: {},
+    worktreesByRepo: {},
+    activeWorktreeId: null,
+    deleteStateByWorktreeId: {},
+    baseStatusByWorktreeId: {},
+    remoteBranchConflictByWorktreeId: {},
+    sortEpoch: 0,
+    everActivatedWorktreeIds: new Set<string>(),
+    lastVisitedAtByWorktreeId: {},
+    hasHydratedWorktreePurge: false,
+    unifiedTabsByWorktree: {},
+    groupsByWorktree: {},
+    activeGroupIdByWorktree: {},
+    layoutByWorktree: {},
+    tabsByWorktree: {},
+    activeTabId: null,
+    activeTabIdByWorktree: {},
+    ptyIdsByTabId: {},
+    runtimePaneTitlesByTabId: {},
+    unreadTerminalTabs: {},
+    suppressedPtyExitIds: {},
+    pendingCodexPaneRestartIds: {},
+    codexRestartNoticeByPtyId: {},
+    expandedPaneByTabId: {},
+    canExpandPaneByTabId: {},
+    terminalLayoutsByTabId: {},
+    pendingStartupByTabId: {},
+    pendingSetupSplitByTabId: {},
+    pendingIssueCommandSplitByTabId: {},
+    tabBarOrderByWorktree: {},
+    pendingReconnectWorktreeIds: [],
+    pendingReconnectTabByWorktree: {},
+    pendingReconnectPtyIdByTabId: {},
+    lastKnownRelayPtyIdByTabId: {},
+    pendingSnapshotByPtyId: {},
+    pendingColdRestoreByPtyId: {},
+    deferredSshReconnectTargets: [],
+    deferredSshSessionIdsByTabId: {},
+    cacheTimerByKey: {},
+    expandedDirs: {},
+    pendingExplorerReveal: null,
+    openFiles: [],
+    editorDrafts: {},
+    markdownViewMode: {},
+    editorViewMode: {},
+    editorCursorLine: {},
+    activeFileId: null,
+    activeFileIdByWorktree: {},
+    activeTabTypeByWorktree: {},
+    activeTabType: 'terminal',
+    recentlyClosedEditorTabsByWorktree: {},
+    browserTabsByWorktree: {},
+    browserPagesByWorkspace: {},
+    remoteBrowserPageHandlesByPageId: {},
+    activeBrowserTabId: null,
+    activeBrowserTabIdByWorktree: {},
+    recentlyClosedBrowserTabsByWorktree: {},
+    recentlyClosedBrowserPagesByWorkspace: {},
+    pendingAddressBarFocusByTabId: {},
+    pendingAddressBarFocusByPageId: {},
+    browserSessionProfiles: [],
+    browserSessionImportState: null,
+    defaultBrowserSessionProfileId: null,
+    detectedBrowsers: [],
+    detectedBrowsersLoaded: false,
+    prCache: {},
+    issueCache: {},
+    checksCache: {},
+    commentsCache: {},
+    workItemsCache: {},
+    workItemsInvalidationNonce: 0,
+    projectViewCache: {},
+    linearStatus: { connected: false, viewer: null },
+    linearStatusChecked: false,
+    linearIssueCache: {},
+    linearSearchCache: {}
+  }
+}
+
+function hasUnsavedEditorState(state: AppState): boolean {
+  return state.openFiles.some((file) => file.isDirty || state.editorDrafts[file.id] !== undefined)
+}
+
+async function closeRemoteBrowserPagesBeforeRuntimeSwitch(state: AppState): Promise<void> {
+  const worktreeIdByPageId = new Map<string, string>()
+  for (const pages of Object.values(state.browserPagesByWorkspace)) {
+    for (const page of pages) {
+      worktreeIdByPageId.set(page.id, page.worktreeId)
+    }
+  }
+  await Promise.allSettled(
+    Object.entries(state.remoteBrowserPageHandlesByPageId).map(([pageId, handle]) => {
+      const worktreeId = worktreeIdByPageId.get(pageId)
+      if (!worktreeId) {
+        return Promise.resolve()
+      }
+      return callRuntimeRpc(
+        { kind: 'environment', environmentId: handle.environmentId },
+        'browser.tabClose',
+        { worktree: `id:${worktreeId}`, page: handle.remotePageId },
+        { timeoutMs: 15_000 }
+      )
+    })
+  )
+}
+
+function collectRemoteTerminalHandlesForRuntimeSwitch(
+  state: AppState,
+  fallbackEnvironmentId: string | null
+): Map<string, Set<string>> {
+  const handlesByEnvironmentId = new Map<string, Set<string>>()
+  const collect = (ptyId: string | null | undefined): void => {
+    if (!ptyId) {
+      return
+    }
+    const handle = getRemoteRuntimeTerminalHandle(ptyId)
+    if (!handle) {
+      return
+    }
+    const environmentId = getRemoteRuntimePtyEnvironmentId(ptyId) ?? fallbackEnvironmentId
+    if (!environmentId) {
+      return
+    }
+    const handles = handlesByEnvironmentId.get(environmentId) ?? new Set<string>()
+    handles.add(handle)
+    handlesByEnvironmentId.set(environmentId, handles)
+  }
+
+  for (const ptyIds of Object.values(state.ptyIdsByTabId)) {
+    for (const ptyId of ptyIds) {
+      collect(ptyId)
+    }
+  }
+  for (const tabs of Object.values(state.tabsByWorktree)) {
+    for (const tab of tabs) {
+      collect(tab.ptyId)
+    }
+  }
+  for (const layout of Object.values(state.terminalLayoutsByTabId)) {
+    for (const ptyId of Object.values(layout.ptyIdsByLeafId ?? {})) {
+      collect(ptyId)
+    }
+  }
+  return handlesByEnvironmentId
+}
+
+async function closeRemoteTerminalsBeforeRuntimeSwitch(
+  state: AppState,
+  fallbackEnvironmentId: string | null
+): Promise<void> {
+  const handlesByEnvironmentId = collectRemoteTerminalHandlesForRuntimeSwitch(
+    state,
+    fallbackEnvironmentId
+  )
+  await Promise.allSettled(
+    Array.from(handlesByEnvironmentId.entries()).flatMap(([environmentId, handles]) =>
+      Array.from(handles).map((terminal) =>
+        callRuntimeRpc(
+          { kind: 'environment', environmentId },
+          'terminal.close',
+          { terminal },
+          { timeoutMs: 15_000 }
+        )
+      )
+    )
+  )
+}
+
+async function verifyRuntimeEnvironmentReachable(environmentId: string | null): Promise<void> {
+  if (!environmentId) {
+    return
+  }
+  await callRuntimeRpc({ kind: 'environment', environmentId }, 'repo.list', undefined, {
+    timeoutMs: 15_000
+  })
+}
+
+export const createSettingsSlice: StateCreator<AppState, [], [], SettingsSlice> = (set, get) => ({
   settings: null,
   settingsSearchQuery: '',
   setSettingsSearchQuery: (q) => set({ settingsSearchQuery: q }),
@@ -72,5 +268,43 @@ export const createSettingsSlice: StateCreator<AppState, [], [], SettingsSlice>
     } catch (err) {
       console.error('Failed to update settings:', err)
     }
+  },
+
+  switchRuntimeEnvironment: async (environmentId) => {
+    const nextId = normalizeRuntimeEnvironmentId(environmentId)
+    const previousId = normalizeRuntimeEnvironmentId(get().settings?.activeRuntimeEnvironmentId)
+    if (previousId === nextId) {
+      return true
+    }
+    if (hasUnsavedEditorState(get())) {
+      toast.error('Save or close unsaved editor tabs before switching servers.')
+      return false
+    }
+    try {
+      clearRuntimeCompatibilityCache(nextId)
+      await verifyRuntimeEnvironmentReachable(nextId)
+      // Why: remote browser tabs live on their owning server. Close them before
+      // clearing browser maps so the old server does not retain orphan pages.
+      await closeRemoteTerminalsBeforeRuntimeSwitch(get(), previousId)
+      await closeRemoteBrowserPagesBeforeRuntimeSwitch(get())
+      await window.api.settings.set({ activeRuntimeEnvironmentId: nextId })
+      set((s) => ({
+        ...runtimeScopedStateReset(),
+        settings: s.settings ? { ...s.settings, activeRuntimeEnvironmentId: nextId } : null
+      }))
+      // Why: server-owned state is cleared before refetch so old worktree,
+      // terminal, browser, and issue IDs cannot be used against the new server
+      // while the new environment is loading.
+      await get().fetchRepos()
+      await get().fetchAllWorktrees()
+      await get().fetchBrowserSessionProfiles()
+      return true
+    } catch (err) {
+      console.error('Failed to switch runtime environment:', err)
+      toast.error('Failed to switch servers', {
+        description: err instanceof Error ? err.message : String(err)
+      })
+      return false
+    }
   }
 })
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index 662ed2e87ba..e526fd41885 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -28,6 +28,7 @@ import {
   unregisterPtyDataHandlers
 } from '@/components/terminal-pane/pty-transport'
 import { shutdownBufferCaptures } from '@/components/terminal-pane/shutdown-buffer-captures'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 function getNextTerminalOrdinal(tabs: TerminalTab[]): number {
   const usedOrdinals = new Set<number>()
@@ -1252,8 +1253,20 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       return
     }
 
+    const target = getActiveRuntimeTarget(get().settings)
+    if (target.kind === 'environment') {
+      await callRuntimeRpc(
+        target,
+        'terminal.stop',
+        { worktree: worktreeId },
+        { timeoutMs: 15_000 }
+      ).catch(() => null)
+    }
+
     await Promise.allSettled(
-      ptyIds.map((ptyId) => window.api.pty.kill(ptyId, { keepHistory: keepIdentifiers }))
+      ptyIds
+        .filter((ptyId) => !ptyId.startsWith('remote:'))
+        .map((ptyId) => window.api.pty.kill(ptyId, { keepHistory: keepIdentifiers }))
     )
   },
 
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index 8fce0f6cb15..f9de8d4140b 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -259,6 +259,7 @@ export type UISlice = {
       | 'accounts'
       | 'voice'
       | 'experimental'
+      | 'servers'
       | 'mobile'
       | 'ssh'
     repoId: string | null
diff --git a/src/renderer/src/store/slices/worktrees.test.ts b/src/renderer/src/store/slices/worktrees.test.ts
index d884ff07460..b5517e65649 100644
--- a/src/renderer/src/store/slices/worktrees.test.ts
+++ b/src/renderer/src/store/slices/worktrees.test.ts
@@ -6,6 +6,14 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { create } from 'zustand'
 import type { AppState } from '../types'
 import type { Worktree } from '../../../../shared/types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
+
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
 
 const mockApi = {
   worktrees: {
@@ -19,6 +27,9 @@ const mockApi = {
   },
   hooks: {
     check: vi.fn().mockResolvedValue({ hasHooks: false, hooks: null, mayNeedUpdate: false })
+  },
+  runtimeEnvironments: {
+    call: runtimeEnvironmentTransportCall
   }
 }
 
@@ -27,6 +38,15 @@ globalThis.window = { api: mockApi }
 
 import { createWorktreeSlice } from './worktrees'
 
+function resetRemoteRuntimeMocks() {
+  clearRuntimeCompatibilityCacheForTests()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+}
+
 function createTestStore() {
   return create<AppState>()(
     (...a) =>
@@ -98,6 +118,7 @@ function makeWorktree(overrides: Partial<Worktree> & { id: string; repoId: strin
 describe('fetchWorktrees', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
   })
 
   it('does not notify subscribers when the fetched payload is unchanged', async () => {
@@ -192,11 +213,40 @@ describe('fetchWorktrees', () => {
     expect(store.getState().worktreesByRepo.repo1).toEqual([])
     expect(store.getState().sortEpoch).toBe(8)
   })
+
+  it('fetches worktrees from the active remote runtime environment', async () => {
+    const store = createTestStore()
+    const remote = makeWorktree({
+      id: 'repo1::/remote/wt1',
+      repoId: 'repo1',
+      path: '/remote/wt1',
+      branch: 'refs/heads/remote'
+    })
+    store.setState({ settings: { activeRuntimeEnvironmentId: 'env-1' } as never })
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { worktrees: [remote], totalCount: 1, truncated: false },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    await store.getState().fetchWorktrees('repo1')
+
+    expect(store.getState().worktreesByRepo.repo1).toEqual([remote])
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'worktree.list',
+      params: { repo: 'repo1' },
+      timeoutMs: 15_000
+    })
+    expect(mockApi.worktrees.list).not.toHaveBeenCalled()
+  })
 })
 
 describe('updateWorktreeGitIdentity', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
   })
 
   it('updates branch identity from git status without fetching worktrees', () => {
@@ -228,6 +278,7 @@ describe('updateWorktreeGitIdentity', () => {
 describe('createWorktree base status merge', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
   })
 
   it('passes linked work item and creation agent metadata through the create IPC payload', async () => {
@@ -311,6 +362,7 @@ describe('createWorktree base status merge', () => {
 describe('removeWorktree state cleanup', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
   })
 
   it('cleans up editorDrafts for files in the removed worktree', async () => {
@@ -609,6 +661,120 @@ describe('removeWorktree state cleanup', () => {
   })
 })
 
+describe('worktree remote runtime mutations', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
+  })
+
+  it('creates worktrees through the active remote runtime environment', async () => {
+    const store = createTestStore()
+    const wt = makeWorktree({
+      id: 'repo1::/path/feature',
+      repoId: 'repo1',
+      path: '/path/feature'
+    })
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-create',
+      ok: true,
+      result: { worktree: wt },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      worktreesByRepo: { repo1: [] }
+    } as Partial<AppState>)
+
+    const result = await store
+      .getState()
+      .createWorktree(
+        'repo1',
+        'feature',
+        'origin/main',
+        'skip',
+        { directories: ['src'], presetId: 'preset-1' },
+        'sidebar',
+        'Feature title',
+        123,
+        456,
+        { remoteName: 'fork', branchName: 'feature' }
+      )
+
+    expect(result).toEqual({ worktree: wt })
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'worktree.create',
+      params: {
+        repo: 'repo1',
+        name: 'feature',
+        baseBranch: 'origin/main',
+        setupDecision: 'skip',
+        sparseCheckout: { directories: ['src'], presetId: 'preset-1' },
+        displayName: 'Feature title',
+        linkedIssue: 123,
+        linkedPR: 456,
+        pushTarget: { remoteName: 'fork', branchName: 'feature' }
+      },
+      timeoutMs: 10 * 60_000
+    })
+    expect(mockApi.worktrees.create).not.toHaveBeenCalled()
+    expect(store.getState().worktreesByRepo.repo1).toEqual([wt])
+  })
+
+  it('removes worktrees through the active remote runtime environment', async () => {
+    const store = createTestStore()
+    const wt = makeWorktree({ id: 'repo1::/path/wt1', repoId: 'repo1', path: '/path/wt1' })
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-rm',
+      ok: true,
+      result: { removed: true },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      worktreesByRepo: { repo1: [wt] }
+    } as Partial<AppState>)
+
+    const result = await store.getState().removeWorktree(wt.id)
+
+    expect(result).toEqual({ ok: true })
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'worktree.rm',
+      params: { worktree: wt.id, force: undefined, runHooks: true },
+      timeoutMs: 60_000
+    })
+    expect(mockApi.worktrees.remove).not.toHaveBeenCalled()
+    expect(store.getState().worktreesByRepo.repo1).toEqual([])
+  })
+
+  it('persists worktree metadata through the active remote runtime environment', async () => {
+    const store = createTestStore()
+    const wt = makeWorktree({ id: 'repo1::/path/wt1', repoId: 'repo1', path: '/path/wt1' })
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-set',
+      ok: true,
+      result: { worktree: { ...wt, comment: 'remote note' } },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      worktreesByRepo: { repo1: [wt] }
+    } as Partial<AppState>)
+
+    await store.getState().updateWorktreeMeta(wt.id, { comment: 'remote note' })
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'worktree.set',
+      params: expect.objectContaining({ worktree: wt.id, comment: 'remote note' }),
+      timeoutMs: 15_000
+    })
+    expect(mockApi.worktrees.updateMeta).not.toHaveBeenCalled()
+    expect(store.getState().worktreesByRepo.repo1[0]?.comment).toBe('remote note')
+  })
+})
+
 // Why: ghostty "show until interact" model — BEL must raise the sidebar dot
 // even on the active worktree, and only clearWorktreeUnread (called from the
 // terminal pane on keystroke / pointerdown) dismisses it. Pins both halves
@@ -616,6 +782,7 @@ describe('removeWorktree state cleanup', () => {
 describe('worktree unread (show-until-interact)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
   })
 
   it('markWorktreeUnread sets isUnread even when the worktree is active', async () => {
@@ -685,6 +852,7 @@ describe('worktree unread (show-until-interact)', () => {
 describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
   })
 
   const repoA = {
@@ -823,6 +991,7 @@ describe('fetchAllWorktrees hydration-time purge (design §4.4)', () => {
 describe('purgeWorktreeTerminalState direct (design §4.4)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
   })
 
   it('wipes tab-id-keyed maps (terminalLayoutsByTabId, ptyIdsByTabId) and clears actives', () => {
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index d804e49c475..9d738dea8c6 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -10,6 +10,7 @@ import {
 } from './worktree-helpers'
 import { ensureHooksConfirmed } from '@/lib/ensure-hooks-confirmed'
 import { tabHasLivePty } from '@/lib/tab-has-live-pty'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '../../runtime/runtime-rpc-client'
 export type { WorktreeSlice, WorktreeDeleteState } from './worktree-helpers'
 
 function arraysShallowEqual(a: string[] | undefined, b: string[] | undefined): boolean {
@@ -68,6 +69,43 @@ function toVisibleTabType(contentType: string): WorkspaceVisibleTabType {
         : 'editor'
 }
 
+async function listWorktreesForRepo(
+  settings: AppState['settings'],
+  repoId: string
+): Promise<Worktree[]> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind === 'local') {
+    return window.api.worktrees.list({ repoId })
+  }
+  const result = await callRuntimeRpc<{ worktrees: Worktree[] }>(
+    target,
+    'worktree.list',
+    { repo: repoId },
+    // Why: remote environment hydration crosses the network. Bound the call
+    // so startup can recover instead of leaving the renderer waiting forever.
+    { timeoutMs: 15_000 }
+  )
+  return result.worktrees
+}
+
+async function persistWorktreeMeta(
+  settings: AppState['settings'],
+  worktreeId: string,
+  updates: Partial<WorktreeMeta>
+): Promise<void> {
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind === 'local') {
+    await window.api.worktrees.updateMeta({ worktreeId, updates })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'worktree.set',
+    { worktree: worktreeId, ...updates },
+    { timeoutMs: 15_000 }
+  )
+}
+
 export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice> = (set, get) => ({
   worktreesByRepo: {},
   activeWorktreeId: null,
@@ -81,7 +119,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
 
   fetchWorktrees: async (repoId) => {
     try {
-      const worktrees = await window.api.worktrees.list({ repoId })
+      const worktrees = await listWorktreesForRepo(get().settings, repoId)
       const current = get().worktreesByRepo[repoId]
       if (areWorktreesEqual(current, worktrees)) {
         return
@@ -135,7 +173,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     const results = await Promise.all(
       repos.map(async (r) => {
         try {
-          const list = await window.api.worktrees.list({ repoId: r.id })
+          const list = await listWorktreesForRepo(get().settings, r.id)
           const current = get().worktreesByRepo[r.id]
           if (
             !areWorktreesEqual(current, list) &&
@@ -252,7 +290,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       for (let attempt = 0; attempt < 25; attempt += 1) {
         const candidateName = nextCandidateName(name, attempt)
         try {
-          const result = await window.api.worktrees.create({
+          const createArgs = {
             repoId,
             name: candidateName,
             baseBranch,
@@ -264,7 +302,28 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             ...(linkedPR !== undefined ? { linkedPR } : {}),
             ...(pushTarget ? { pushTarget } : {}),
             ...(createdWithAgent ? { createdWithAgent } : {})
-          })
+          }
+          const target = getActiveRuntimeTarget(get().settings)
+          const result =
+            target.kind === 'local'
+              ? await window.api.worktrees.create(createArgs)
+              : await callRuntimeRpc<Awaited<ReturnType<typeof window.api.worktrees.create>>>(
+                  target,
+                  'worktree.create',
+                  {
+                    repo: repoId,
+                    name: candidateName,
+                    baseBranch,
+                    setupDecision,
+                    sparseCheckout,
+                    ...(displayName ? { displayName } : {}),
+                    ...(linkedIssue !== undefined ? { linkedIssue } : {}),
+                    ...(linkedPR !== undefined ? { linkedPR } : {}),
+                    ...(pushTarget ? { pushTarget } : {}),
+                    ...(createdWithAgent ? { createdWithAgent } : {})
+                  },
+                  { timeoutMs: 10 * 60_000 }
+                )
           // Why: a file watcher (worktrees.onChanged) can fire between the
           // backend creating the worktree and this callback running, causing
           // fetchWorktrees to add the worktree first. Appending unconditionally
@@ -338,7 +397,15 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       // can intercept them.
       await get().shutdownWorktreeBrowsers(worktreeId)
       await get().shutdownWorktreeTerminals(worktreeId)
-      await window.api.worktrees.remove({ worktreeId, force, skipArchive })
+      const target = getActiveRuntimeTarget(get().settings)
+      await (target.kind === 'local'
+        ? window.api.worktrees.remove({ worktreeId, force, skipArchive })
+        : callRuntimeRpc(
+            target,
+            'worktree.rm',
+            { worktree: worktreeId, force, runHooks: !skipArchive },
+            { timeoutMs: 60_000 }
+          ))
       const tabs = get().tabsByWorktree[worktreeId] ?? []
       const tabIds = new Set(tabs.map((t) => t.id))
 
@@ -557,7 +624,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     })
 
     try {
-      await window.api.worktrees.updateMeta({ worktreeId, updates: enriched })
+      await persistWorktreeMeta(get().settings, worktreeId, enriched)
     } catch (err) {
       console.error('Failed to update worktree meta:', err)
       void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
@@ -591,12 +658,13 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       return
     }
 
-    void window.api.worktrees
-      .updateMeta({ worktreeId, updates: { isUnread: true, lastActivityAt: now } })
-      .catch((err) => {
-        console.error('Failed to persist unread worktree state:', err)
-        void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
-      })
+    void persistWorktreeMeta(get().settings, worktreeId, {
+      isUnread: true,
+      lastActivityAt: now
+    }).catch((err) => {
+      console.error('Failed to persist unread worktree state:', err)
+      void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
+    })
   },
 
   clearWorktreeUnread: (worktreeId) => {
@@ -622,12 +690,10 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       return
     }
 
-    void window.api.worktrees
-      .updateMeta({ worktreeId, updates: { isUnread: false } })
-      .catch((err) => {
-        console.error('Failed to persist cleared unread worktree state:', err)
-        void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
-      })
+    void persistWorktreeMeta(get().settings, worktreeId, { isUnread: false }).catch((err) => {
+      console.error('Failed to persist cleared unread worktree state:', err)
+      void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
+    })
   },
 
   bumpWorktreeActivity: (worktreeId) => {
@@ -655,12 +721,10 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       }
     })
 
-    void window.api.worktrees
-      .updateMeta({ worktreeId, updates: { lastActivityAt: now } })
-      .catch((err) => {
-        console.error('Failed to persist worktree activity timestamp:', err)
-        void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
-      })
+    void persistWorktreeMeta(get().settings, worktreeId, { lastActivityAt: now }).catch((err) => {
+      console.error('Failed to persist worktree activity timestamp:', err)
+      void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
+    })
   },
 
   markWorktreeVisited: (worktreeId, visitedAt) => {
@@ -947,11 +1011,11 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     }
 
     if (shouldClearUnread) {
-      const updates: Parameters<typeof window.api.worktrees.updateMeta>[0]['updates'] = {
+      const updates: Partial<WorktreeMeta> = {
         isUnread: false
       }
 
-      void window.api.worktrees.updateMeta({ worktreeId, updates }).catch((err) => {
+      void persistWorktreeMeta(get().settings, worktreeId, updates).catch((err) => {
         console.error('Failed to persist worktree activation state:', err)
         void get().fetchWorktrees(getRepoIdFromWorktreeId(worktreeId))
       })
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 68560894056..6f6f33fa764 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -251,6 +251,9 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     experimentalPet: false,
     experimentalActivity: true,
     experimentalWorktreeSymlinks: false,
+    // Why: local desktop remains the default server until the user explicitly
+    // selects a saved runtime environment.
+    activeRuntimeEnvironmentId: null,
     // Why: hydrate an empty default so the renderer's optional-chained reads
     // (`settings?.githubProjects?.activeProject`) land on a stable shape
     // instead of `undefined`. Upgraded profiles inherit this via the
diff --git a/src/shared/cross-platform-path.test.ts b/src/shared/cross-platform-path.test.ts
new file mode 100644
index 00000000000..ea805b7a788
--- /dev/null
+++ b/src/shared/cross-platform-path.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { isPathInsideOrEqual, relativePathInsideRoot } from './cross-platform-path'
+
+describe('cross-platform path containment', () => {
+  it('keeps POSIX sibling prefixes outside the root', () => {
+    expect(isPathInsideOrEqual('/repo/app', '/repo/app')).toBe(true)
+    expect(isPathInsideOrEqual('/repo/app', '/repo/app/src/index.ts')).toBe(true)
+    expect(isPathInsideOrEqual('/repo/app', '/repo/application/src/index.ts')).toBe(false)
+    expect(relativePathInsideRoot('/repo/app/', '/repo/app/src/index.ts')).toBe('src/index.ts')
+  })
+
+  it('handles Windows drive roots and sibling drives case-insensitively', () => {
+    expect(isPathInsideOrEqual('C:\\Repo', 'c:\\repo\\src\\index.ts')).toBe(true)
+    expect(relativePathInsideRoot('C:\\Repo', 'c:\\repo\\src\\index.ts')).toBe('src/index.ts')
+    expect(isPathInsideOrEqual('C:\\Repo', 'D:\\Repo\\src\\index.ts')).toBe(false)
+    expect(relativePathInsideRoot('C:\\', 'c:\\repo\\src\\index.ts')).toBe('repo/src/index.ts')
+  })
+
+  it('handles UNC roots, trailing slashes, mixed separators, and case', () => {
+    expect(isPathInsideOrEqual('\\\\Server\\Share\\Repo\\', '//server/share/repo/src')).toBe(true)
+    expect(relativePathInsideRoot('\\\\Server\\Share\\Repo\\', '//server/share/repo/src')).toBe(
+      'src'
+    )
+    expect(isPathInsideOrEqual('\\\\Server\\Share\\Repo', '\\\\server\\share\\repo2')).toBe(false)
+  })
+})
diff --git a/src/shared/cross-platform-path.ts b/src/shared/cross-platform-path.ts
new file mode 100644
index 00000000000..d2645a34239
--- /dev/null
+++ b/src/shared/cross-platform-path.ts
@@ -0,0 +1,57 @@
+export function isWindowsAbsolutePathLike(value: string): boolean {
+  return /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\') || value.startsWith('//')
+}
+
+export function normalizeRuntimePathSeparators(value: string): string {
+  const normalized = value.replace(/\\/g, '/').replace(/\/+/g, '/')
+  if (value.startsWith('\\\\') || value.startsWith('//')) {
+    return `//${normalized.replace(/^\/+/, '')}`
+  }
+  return normalized
+}
+
+export function normalizeRuntimePathForComparison(value: string): string {
+  const normalized = trimRuntimePathTrailingSlash(normalizeRuntimePathSeparators(value))
+  return isWindowsAbsolutePathLike(value) ? normalized.toLowerCase() : normalized
+}
+
+export function isPathInsideOrEqual(rootPath: string, candidatePath: string): boolean {
+  const root = normalizeRuntimePathForComparison(rootPath)
+  const candidate = normalizeRuntimePathForComparison(candidatePath)
+  if (candidate === root) {
+    return true
+  }
+  const rootWithBoundary =
+    root === '/' || /^[a-z]:\/$/i.test(root) ? root : `${root.replace(/\/+$/, '')}/`
+  return candidate.startsWith(rootWithBoundary)
+}
+
+export function relativePathInsideRoot(rootPath: string, candidatePath: string): string | null {
+  const normalizedRoot = trimRuntimePathTrailingSlash(normalizeRuntimePathSeparators(rootPath))
+  const normalizedCandidate = trimRuntimePathTrailingSlash(
+    normalizeRuntimePathSeparators(candidatePath)
+  )
+  const comparisonRoot = isWindowsAbsolutePathLike(rootPath)
+    ? normalizedRoot.toLowerCase()
+    : normalizedRoot
+  const comparisonCandidate = isWindowsAbsolutePathLike(rootPath)
+    ? normalizedCandidate.toLowerCase()
+    : normalizedCandidate
+
+  if (comparisonCandidate === comparisonRoot) {
+    return ''
+  }
+  const isRoot = comparisonRoot === '/' || /^[a-z]:\/$/i.test(comparisonRoot)
+  const comparisonPrefix = isRoot ? comparisonRoot : `${comparisonRoot}/`
+  if (!comparisonCandidate.startsWith(comparisonPrefix)) {
+    return null
+  }
+  return normalizedCandidate.slice(comparisonPrefix.length)
+}
+
+function trimRuntimePathTrailingSlash(value: string): string {
+  if (value === '/' || /^[A-Za-z]:\/$/.test(value)) {
+    return value
+  }
+  return value.replace(/\/+$/, '')
+}
diff --git a/src/shared/e2ee-crypto.ts b/src/shared/e2ee-crypto.ts
new file mode 100644
index 00000000000..3d5bcdb5317
--- /dev/null
+++ b/src/shared/e2ee-crypto.ts
@@ -0,0 +1,65 @@
+// Why: Orca's remote runtime transports share one NaCl box format across
+// desktop, CLI, and mobile pairing. Keeping the Node-compatible primitives in
+// shared code prevents the CLI from importing main-process modules.
+import nacl from 'tweetnacl'
+
+export function generateKeyPair(): nacl.BoxKeyPair {
+  return nacl.box.keyPair()
+}
+
+export function deriveSharedKey(ourSecretKey: Uint8Array, peerPublicKey: Uint8Array): Uint8Array {
+  return nacl.box.before(peerPublicKey, ourSecretKey)
+}
+
+export function publicKeyFromBase64(b64: string): Uint8Array {
+  const key = Uint8Array.from(Buffer.from(b64, 'base64'))
+  if (key.length !== 32) {
+    throw new Error(`Invalid public key: expected 32 bytes, got ${key.length}`)
+  }
+  return key
+}
+
+export function publicKeyToBase64(key: Uint8Array): string {
+  return Buffer.from(key).toString('base64')
+}
+
+export function encrypt(plaintext: string, sharedKey: Uint8Array): string {
+  const messageBytes = new TextEncoder().encode(plaintext)
+  return Buffer.from(encryptBytes(messageBytes, sharedKey)).toString('base64')
+}
+
+export function decrypt(encrypted: string, sharedKey: Uint8Array): string | null {
+  const bundle = Uint8Array.from(Buffer.from(encrypted, 'base64'))
+  const plaintext = decryptBytes(bundle, sharedKey)
+  return plaintext ? new TextDecoder().decode(plaintext) : null
+}
+
+export function encryptBytes(
+  plaintext: Uint8Array<ArrayBufferLike>,
+  sharedKey: Uint8Array
+): Uint8Array {
+  const nonce = nacl.randomBytes(nacl.box.nonceLength)
+  const ciphertext = nacl.box.after(plaintext, nonce, sharedKey)
+
+  const bundle = new Uint8Array(nonce.length + ciphertext.length)
+  bundle.set(nonce)
+  bundle.set(ciphertext, nonce.length)
+
+  return bundle
+}
+
+export function decryptBytes(bundle: Uint8Array, sharedKey: Uint8Array): Uint8Array | null {
+  if (bundle.length < nacl.box.nonceLength + nacl.box.overheadLength) {
+    return null
+  }
+
+  const nonce = bundle.slice(0, nacl.box.nonceLength)
+  const ciphertext = bundle.slice(nacl.box.nonceLength)
+  const plaintext = nacl.box.open.after(ciphertext, nonce, sharedKey)
+
+  if (!plaintext) {
+    return null
+  }
+
+  return plaintext
+}
diff --git a/src/shared/protocol-compat.test.ts b/src/shared/protocol-compat.test.ts
index 22d5d4f5fa2..79b70c2d09a 100644
--- a/src/shared/protocol-compat.test.ts
+++ b/src/shared/protocol-compat.test.ts
@@ -1,6 +1,16 @@
 import { describe, expect, it } from 'vitest'
-import { evaluateCompat } from './protocol-compat'
-import { DESKTOP_PROTOCOL_VERSION, MIN_COMPATIBLE_MOBILE_VERSION } from './protocol-version'
+import {
+  describeRuntimeCompatBlock,
+  evaluateCompat,
+  evaluateRuntimeCompat
+} from './protocol-compat'
+import {
+  DESKTOP_PROTOCOL_VERSION,
+  MIN_COMPATIBLE_MOBILE_VERSION,
+  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
+  MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+  RUNTIME_PROTOCOL_VERSION
+} from './protocol-version'
 
 const MOBILE_V = 1
 
@@ -122,3 +132,74 @@ describe('evaluateCompat', () => {
     })
   })
 })
+
+describe('evaluateRuntimeCompat', () => {
+  it('keeps the current client and current server self-compatible', () => {
+    const verdict = evaluateRuntimeCompat({
+      clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleServerProtocolVersion: MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+      serverProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      serverMinCompatibleClientProtocolVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
+    })
+
+    expect(verdict).toMatchObject({ kind: 'ok' })
+  })
+
+  it('allows client and server app versions to skew when protocol ranges overlap', () => {
+    const verdict = evaluateRuntimeCompat({
+      clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleServerProtocolVersion: MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+      serverProtocolVersion: RUNTIME_PROTOCOL_VERSION + 3,
+      serverMinCompatibleClientProtocolVersion: RUNTIME_PROTOCOL_VERSION - 1
+    })
+
+    expect(verdict).toMatchObject({ kind: 'ok' })
+  })
+
+  it('blocks when the server requires a newer client protocol', () => {
+    const verdict = evaluateRuntimeCompat({
+      clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleServerProtocolVersion: MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
+      serverProtocolVersion: RUNTIME_PROTOCOL_VERSION + 1,
+      serverMinCompatibleClientProtocolVersion: RUNTIME_PROTOCOL_VERSION + 1
+    })
+
+    expect(verdict).toMatchObject({
+      kind: 'blocked',
+      reason: 'client-too-old',
+      requiredClientProtocolVersion: RUNTIME_PROTOCOL_VERSION + 1
+    })
+    expect(describeRuntimeCompatBlock(verdict)).toContain('client is too old')
+  })
+
+  it('blocks when the server protocol is below the client minimum', () => {
+    const verdict = evaluateRuntimeCompat({
+      clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleServerProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      serverProtocolVersion: RUNTIME_PROTOCOL_VERSION - 1,
+      serverMinCompatibleClientProtocolVersion: 0
+    })
+
+    expect(verdict).toMatchObject({
+      kind: 'blocked',
+      reason: 'server-too-old',
+      requiredServerProtocolVersion: RUNTIME_PROTOCOL_VERSION
+    })
+    expect(describeRuntimeCompatBlock(verdict)).toContain('server is too old')
+  })
+
+  it('treats missing server fields as protocol 0', () => {
+    const verdict = evaluateRuntimeCompat({
+      clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
+      minCompatibleServerProtocolVersion: 1,
+      serverProtocolVersion: undefined,
+      serverMinCompatibleClientProtocolVersion: undefined
+    })
+
+    expect(verdict).toMatchObject({
+      kind: 'blocked',
+      reason: 'server-too-old',
+      serverProtocolVersion: 0
+    })
+  })
+})
diff --git a/src/shared/protocol-compat.ts b/src/shared/protocol-compat.ts
index 72477cfb482..82f9566a9a0 100644
--- a/src/shared/protocol-compat.ts
+++ b/src/shared/protocol-compat.ts
@@ -1,8 +1,67 @@
-// Why: pure compat evaluator shared between desktop tests and mobile
-// runtime. Mobile imports a thin wrapper (`mobile/src/transport/protocol-compat.ts`)
-// that injects the mobile-side constants; desktop tests import this
-// directly so the function is covered by the root vitest suite.
-// All four numbers are passed in to keep the function dependency-free.
+// Why: pure compat evaluators shared between desktop tests, renderer runtime
+// switching, and the mobile mirror. All version numbers are passed in to keep
+// the logic dependency-free and easy to duplicate in Expo.
+
+export type RuntimeCompatVerdict =
+  | {
+      kind: 'ok'
+      clientProtocolVersion: number
+      serverProtocolVersion: number
+    }
+  | {
+      kind: 'blocked'
+      reason: 'client-too-old' | 'server-too-old'
+      clientProtocolVersion: number
+      serverProtocolVersion: number
+      requiredClientProtocolVersion?: number
+      requiredServerProtocolVersion?: number
+    }
+
+export function evaluateRuntimeCompat(input: {
+  clientProtocolVersion: number
+  minCompatibleServerProtocolVersion: number
+  serverProtocolVersion: number | undefined
+  serverMinCompatibleClientProtocolVersion: number | undefined
+}): RuntimeCompatVerdict {
+  // Why: absent fields are protocol 0. New clients can give old servers a
+  // clear "update server" error instead of attempting partially-supported RPCs.
+  const serverProtocolVersion = input.serverProtocolVersion ?? 0
+  const requiredClientProtocolVersion = input.serverMinCompatibleClientProtocolVersion ?? 0
+
+  if (input.clientProtocolVersion < requiredClientProtocolVersion) {
+    return {
+      kind: 'blocked',
+      reason: 'client-too-old',
+      clientProtocolVersion: input.clientProtocolVersion,
+      serverProtocolVersion,
+      requiredClientProtocolVersion
+    }
+  }
+  if (serverProtocolVersion < input.minCompatibleServerProtocolVersion) {
+    return {
+      kind: 'blocked',
+      reason: 'server-too-old',
+      clientProtocolVersion: input.clientProtocolVersion,
+      serverProtocolVersion,
+      requiredServerProtocolVersion: input.minCompatibleServerProtocolVersion
+    }
+  }
+  return {
+    kind: 'ok',
+    clientProtocolVersion: input.clientProtocolVersion,
+    serverProtocolVersion
+  }
+}
+
+export function describeRuntimeCompatBlock(verdict: RuntimeCompatVerdict): string {
+  if (verdict.kind === 'ok') {
+    return 'Runtime client and server are compatible.'
+  }
+  if (verdict.reason === 'client-too-old') {
+    return `This Orca client is too old for the selected server. Update Orca on this machine. Client protocol ${verdict.clientProtocolVersion}, server requires client protocol ${verdict.requiredClientProtocolVersion}.`
+  }
+  return `The selected Orca server is too old for this client. Update Orca on the server. Server protocol ${verdict.serverProtocolVersion}, client requires server protocol ${verdict.requiredServerProtocolVersion}.`
+}
 
 export type CompatVerdict =
   | { kind: 'ok' }
diff --git a/src/shared/protocol-version.ts b/src/shared/protocol-version.ts
index 63aebbdc312..355c7e63666 100644
--- a/src/shared/protocol-version.ts
+++ b/src/shared/protocol-version.ts
@@ -1,23 +1,36 @@
-// Why: declares the desktop's mobile-pairing protocol version so mobile
-// builds can detect declared-incompatible combos and hard-block at pair
-// time. Today's values are wide-open (mobile=any, desktop=any), so
-// nothing actually blocks; the wire format is ready for the day we
-// ship a genuinely-breaking change.
+// Why: declares the Orca runtime RPC compatibility contract. Desktop,
+// headless server, CLI, and mobile builds may drift in app version, but
+// they must agree on this protocol range before runtime RPCs are allowed.
 //
-// Bump DESKTOP_PROTOCOL_VERSION when:
-//   - You remove an RPC method or required parameter that mobile uses.
+// Bump RUNTIME_PROTOCOL_VERSION when:
+//   - You remove an RPC method or required parameter that clients use.
 //   - You change the meaning (units, nullability) of an existing field
-//     mobile reads.
-//   - You change encryption, framing, or the auth handshake.
+//     clients read.
+//   - You change encrypted framing, terminal stream framing, or auth.
 // Do NOT bump for:
 //   - Adding new RPC methods.
 //   - Adding new optional fields on existing methods.
-//   - Adding new event types in `terminal.subscribe`.
+//   - Adding new ignorable event types.
 //
-// Bump MIN_COMPATIBLE_MOBILE_VERSION when desktop ships a change that
-// requires a minimum mobile version to function safely. This is the
-// "kill switch": desktop can refuse old mobile builds without needing
-// a desktop release of mobile.
+// Bump MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION when a runtime server must
+// refuse older clients. Bump MIN_COMPATIBLE_RUNTIME_SERVER_VERSION when
+// this client build requires a newer server. Exact app-version equality is
+// never required; these numbers define the supported compatibility window.
 
-export const DESKTOP_PROTOCOL_VERSION = 2
-export const MIN_COMPATIBLE_MOBILE_VERSION = 2
+export const RUNTIME_PROTOCOL_VERSION = 2
+export const MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION = 2
+export const MIN_COMPATIBLE_RUNTIME_SERVER_VERSION = 2
+
+export const RUNTIME_CAPABILITIES = [
+  'runtime.status.compat.v1',
+  'runtime.environments.v1',
+  'terminal.binary-stream.v1',
+  'terminal.multiplex.v1'
+] as const
+
+export type RuntimeCapability = (typeof RUNTIME_CAPABILITIES)[number] | (string & {})
+
+// COMPAT(mobileProtocolAliases): added 2026-05-15 for mobile builds that
+// still read desktop/mobile names; remove once mobile reads runtime names.
+export const DESKTOP_PROTOCOL_VERSION = RUNTIME_PROTOCOL_VERSION
+export const MIN_COMPATIBLE_MOBILE_VERSION = MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION
diff --git a/src/shared/remote-runtime-client.test.ts b/src/shared/remote-runtime-client.test.ts
new file mode 100644
index 00000000000..4d7e2e9526d
--- /dev/null
+++ b/src/shared/remote-runtime-client.test.ts
@@ -0,0 +1,140 @@
+import type { AddressInfo } from 'net'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { WebSocketServer, type WebSocket } from 'ws'
+import { encodePairingOffer, parsePairingCode, type PairingOffer } from './pairing'
+import {
+  decrypt,
+  decryptBytes,
+  deriveSharedKey,
+  encrypt,
+  generateKeyPair,
+  publicKeyFromBase64,
+  publicKeyToBase64
+} from './e2ee-crypto'
+import { subscribeRemoteRuntimeRequest } from './remote-runtime-client'
+
+const servers: WebSocketServer[] = []
+
+afterEach(async () => {
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          for (const client of server.clients) {
+            client.close()
+          }
+          server.close(() => resolve())
+        })
+    )
+  )
+})
+
+describe('subscribeRemoteRuntimeRequest', () => {
+  it('sends encrypted binary frames on an established subscription socket', async () => {
+    const server = await createSubscriptionServer()
+    const onResponse = vi.fn()
+    const onError = vi.fn()
+
+    const subscription = await subscribeRemoteRuntimeRequest(
+      server.pairing,
+      'terminal.subscribe',
+      { terminal: 't1' },
+      1000,
+      {
+        onResponse,
+        onError
+      }
+    )
+
+    await vi.waitFor(() =>
+      expect(onResponse).toHaveBeenCalledWith(
+        expect.objectContaining({ ok: true, result: { type: 'subscribed' } })
+      )
+    )
+    const bytes = new Uint8Array([1, 2, 3])
+    expect(subscription.sendBinary(bytes)).toBe(true)
+    await expect(server.nextBinary).resolves.toEqual(bytes)
+    expect(onError).not.toHaveBeenCalled()
+    subscription.close()
+  })
+})
+
+async function createSubscriptionServer(): Promise<{
+  pairing: PairingOffer
+  nextBinary: Promise<Uint8Array>
+}> {
+  const serverKeyPair = generateKeyPair()
+  let resolveBinary: (bytes: Uint8Array) => void = () => {}
+  const nextBinary = new Promise<Uint8Array>((resolve) => {
+    resolveBinary = resolve
+  })
+  const wss = new WebSocketServer({ port: 0 })
+  servers.push(wss)
+
+  wss.on('connection', (ws) => {
+    let sharedKey: Uint8Array | null = null
+    let authenticated = false
+
+    ws.on('message', (data, isBinary) => {
+      if (isBinary) {
+        if (!sharedKey) {
+          return
+        }
+        const plaintext = decryptBytes(new Uint8Array(data as Buffer), sharedKey)
+        if (plaintext) {
+          resolveBinary(plaintext)
+        }
+        return
+      }
+
+      const frame = data.toString()
+      if (!sharedKey) {
+        const hello = JSON.parse(frame) as { publicKeyB64: string }
+        sharedKey = deriveSharedKey(
+          serverKeyPair.secretKey,
+          publicKeyFromBase64(hello.publicKeyB64)
+        )
+        ws.send(JSON.stringify({ type: 'e2ee_ready' }))
+        return
+      }
+
+      const plaintext = decrypt(frame, sharedKey)
+      if (!plaintext) {
+        return
+      }
+      if (!authenticated) {
+        authenticated = true
+        sendEncrypted(ws, sharedKey, { type: 'e2ee_authenticated' })
+        return
+      }
+
+      const request = JSON.parse(plaintext) as { id: string }
+      sendEncrypted(ws, sharedKey, {
+        id: request.id,
+        ok: true,
+        streaming: true,
+        result: { type: 'subscribed' },
+        _meta: { runtimeId: 'runtime-test' }
+      })
+    })
+  })
+
+  await new Promise<void>((resolve) => wss.once('listening', resolve))
+  const address = wss.address() as AddressInfo
+  const pairing = parsePairingCode(
+    encodePairingOffer({
+      v: 2,
+      endpoint: `ws://127.0.0.1:${address.port}`,
+      deviceToken: 'device-token',
+      publicKeyB64: publicKeyToBase64(serverKeyPair.publicKey)
+    })
+  )
+  if (!pairing) {
+    throw new Error('Failed to create test pairing')
+  }
+  return { pairing, nextBinary }
+}
+
+function sendEncrypted(ws: WebSocket, sharedKey: Uint8Array, message: unknown): void {
+  ws.send(encrypt(JSON.stringify(message), sharedKey))
+}
diff --git a/src/shared/remote-runtime-client.ts b/src/shared/remote-runtime-client.ts
new file mode 100644
index 00000000000..23589deb894
--- /dev/null
+++ b/src/shared/remote-runtime-client.ts
@@ -0,0 +1,552 @@
+/* oxlint-disable max-lines -- Why: one-shot and streaming remote clients share the
+ * same E2EE handshake and response validation state; keep them together until
+ * the terminal transport is fully migrated and a stable shared connection
+ * abstraction emerges. */
+import { randomUUID } from 'crypto'
+import WebSocket from 'ws'
+import type { PairingOffer } from './pairing'
+import {
+  decrypt,
+  decryptBytes,
+  deriveSharedKey,
+  encrypt,
+  encryptBytes,
+  generateKeyPair,
+  publicKeyFromBase64,
+  publicKeyToBase64
+} from './e2ee-crypto'
+import { RuntimeRpcEnvelopeSchema, type RuntimeRpcResponse } from './runtime-rpc-envelope'
+
+type HandshakeState = 'awaiting_ready' | 'awaiting_authenticated' | 'ready'
+
+export class RemoteRuntimeClientError extends Error {
+  readonly code: string
+
+  constructor(code: string, message: string) {
+    super(message)
+    this.name = 'RemoteRuntimeClientError'
+    this.code = code
+  }
+}
+
+export type RemoteRuntimeSubscription = {
+  requestId: string
+  close: () => void
+  sendBinary: (bytes: Uint8Array<ArrayBufferLike>) => boolean
+}
+
+export type RemoteRuntimeSubscriptionCallbacks<TResult = unknown> = {
+  onResponse: (response: RuntimeRpcResponse<TResult>) => void
+  onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+  onError: (error: RemoteRuntimeClientError) => void
+  onClose?: () => void
+}
+
+export async function sendRemoteRuntimeRequest<TResult>(
+  pairing: PairingOffer,
+  method: string,
+  params: unknown,
+  timeoutMs: number
+): Promise<RuntimeRpcResponse<TResult>> {
+  return await new Promise((resolve, reject) => {
+    const requestId = randomUUID()
+    const keyPair = generateKeyPair()
+    const serverPublicKey = publicKeyFromBase64(pairing.publicKeyB64)
+    const sharedKey = deriveSharedKey(keyPair.secretKey, serverPublicKey)
+    let state: HandshakeState = 'awaiting_ready'
+    let settled = false
+    let ws: WebSocket | null = null
+
+    const timeout = setTimeout(() => {
+      finish({
+        ok: false,
+        error: new RemoteRuntimeClientError(
+          'runtime_timeout',
+          'Timed out waiting for the remote Orca runtime to respond.'
+        )
+      })
+    }, timeoutMs)
+
+    const finish = (
+      result: { ok: true; response: RuntimeRpcResponse<TResult> } | { ok: false; error: Error }
+    ): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      clearTimeout(timeout)
+      try {
+        ws?.close()
+      } catch {
+        // ignore best-effort close
+      }
+      if (result.ok === false) {
+        reject(result.error)
+      } else {
+        resolve(result.response)
+      }
+    }
+
+    try {
+      ws = new WebSocket(pairing.endpoint)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      finish({
+        ok: false,
+        error: new RemoteRuntimeClientError(
+          'invalid_argument',
+          `Invalid remote endpoint: ${message}`
+        )
+      })
+      return
+    }
+
+    ws.once('open', () => {
+      ws?.send(
+        JSON.stringify({
+          type: 'e2ee_hello',
+          publicKeyB64: publicKeyToBase64(keyPair.publicKey)
+        })
+      )
+    })
+
+    ws.once('error', () => {
+      finish({
+        ok: false,
+        error: new RemoteRuntimeClientError(
+          'remote_runtime_unavailable',
+          'Could not connect to the remote Orca runtime.'
+        )
+      })
+    })
+
+    ws.on('close', () => {
+      if (!settled) {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'remote_runtime_unavailable',
+            'Remote Orca runtime closed the connection.'
+          )
+        })
+      }
+    })
+
+    ws.on('message', (data, isBinary) => {
+      if (settled) {
+        return
+      }
+      if (isBinary) {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an unexpected binary frame.'
+          )
+        })
+        return
+      }
+
+      const frame = data.toString()
+      if (state === 'awaiting_ready') {
+        handleReadyFrame(frame)
+        return
+      }
+
+      const plaintext = decrypt(frame, sharedKey)
+      if (plaintext === null) {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an undecryptable frame.'
+          )
+        })
+        return
+      }
+
+      if (state === 'awaiting_authenticated') {
+        handleAuthenticatedFrame(plaintext)
+        return
+      }
+
+      handleRpcFrame(plaintext)
+    })
+
+    function handleReadyFrame(frame: string): void {
+      let ready: unknown
+      try {
+        ready = JSON.parse(frame)
+      } catch {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an invalid E2EE handshake frame.'
+          )
+        })
+        return
+      }
+      if (
+        typeof ready !== 'object' ||
+        ready === null ||
+        (ready as { type?: unknown }).type !== 'e2ee_ready'
+      ) {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an unexpected E2EE handshake frame.'
+          )
+        })
+        return
+      }
+      state = 'awaiting_authenticated'
+      ws?.send(
+        encrypt(JSON.stringify({ type: 'e2ee_auth', deviceToken: pairing.deviceToken }), sharedKey)
+      )
+    }
+
+    function handleAuthenticatedFrame(plaintext: string): void {
+      let authenticated: unknown
+      try {
+        authenticated = JSON.parse(plaintext)
+      } catch {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an invalid E2EE auth frame.'
+          )
+        })
+        return
+      }
+      const type = (authenticated as { type?: unknown }).type
+      if (type !== 'e2ee_authenticated') {
+        const code =
+          typeof authenticated === 'object' &&
+          authenticated !== null &&
+          (authenticated as { error?: { code?: unknown } }).error?.code === 'unauthorized'
+            ? 'unauthorized'
+            : 'invalid_runtime_response'
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            code,
+            'Remote Orca runtime rejected the pairing token.'
+          )
+        })
+        return
+      }
+      state = 'ready'
+      ws?.send(
+        encrypt(
+          JSON.stringify({
+            id: requestId,
+            deviceToken: pairing.deviceToken,
+            method,
+            params
+          }),
+          sharedKey
+        )
+      )
+    }
+
+    function handleRpcFrame(plaintext: string): void {
+      let raw: unknown
+      try {
+        raw = JSON.parse(plaintext)
+      } catch {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an invalid response frame.'
+          )
+        })
+        return
+      }
+      const parsed = RuntimeRpcEnvelopeSchema.safeParse(raw)
+      if (!parsed.success || '_keepalive' in parsed.data) {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an invalid response frame.'
+          )
+        })
+        return
+      }
+      const response = parsed.data as RuntimeRpcResponse<TResult>
+      if (response.id !== requestId) {
+        finish({
+          ok: false,
+          error: new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned a mismatched response id.'
+          )
+        })
+        return
+      }
+      finish({ ok: true, response })
+    }
+  })
+}
+
+export async function subscribeRemoteRuntimeRequest<TResult>(
+  pairing: PairingOffer,
+  method: string,
+  params: unknown,
+  timeoutMs: number,
+  callbacks: RemoteRuntimeSubscriptionCallbacks<TResult>
+): Promise<RemoteRuntimeSubscription> {
+  return await new Promise((resolve, reject) => {
+    const requestId = randomUUID()
+    const keyPair = generateKeyPair()
+    const serverPublicKey = publicKeyFromBase64(pairing.publicKeyB64)
+    const sharedKey = deriveSharedKey(keyPair.secretKey, serverPublicKey)
+    let state: HandshakeState = 'awaiting_ready'
+    let settled = false
+    let ws: WebSocket | null = null
+
+    const timeout = setTimeout(() => {
+      fail(
+        new RemoteRuntimeClientError(
+          'runtime_timeout',
+          'Timed out waiting for the remote Orca runtime subscription to start.'
+        )
+      )
+    }, timeoutMs)
+
+    const close = (): void => {
+      try {
+        ws?.close()
+      } catch {
+        // ignore best-effort close
+      }
+    }
+
+    const sendBinary = (bytes: Uint8Array<ArrayBufferLike>): boolean => {
+      if (state !== 'ready' || !ws || ws.readyState !== WebSocket.OPEN) {
+        return false
+      }
+      ws.send(Buffer.from(encryptBytes(bytes, sharedKey)), { binary: true })
+      return true
+    }
+
+    const succeed = (): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      clearTimeout(timeout)
+      resolve({ requestId, close, sendBinary })
+    }
+
+    const fail = (error: RemoteRuntimeClientError): void => {
+      if (!settled) {
+        settled = true
+        clearTimeout(timeout)
+        close()
+        reject(error)
+        return
+      }
+      callbacks.onError(error)
+    }
+
+    try {
+      ws = new WebSocket(pairing.endpoint)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      fail(new RemoteRuntimeClientError('invalid_argument', `Invalid remote endpoint: ${message}`))
+      return
+    }
+
+    ws.once('open', () => {
+      ws?.send(
+        JSON.stringify({
+          type: 'e2ee_hello',
+          publicKeyB64: publicKeyToBase64(keyPair.publicKey)
+        })
+      )
+    })
+
+    ws.once('error', () => {
+      fail(
+        new RemoteRuntimeClientError(
+          'remote_runtime_unavailable',
+          'Could not connect to the remote Orca runtime.'
+        )
+      )
+    })
+
+    ws.on('close', () => {
+      clearTimeout(timeout)
+      if (!settled) {
+        reject(
+          new RemoteRuntimeClientError(
+            'remote_runtime_unavailable',
+            'Remote Orca runtime closed the connection.'
+          )
+        )
+        return
+      }
+      callbacks.onClose?.()
+    })
+
+    ws.on('message', (data, isBinary) => {
+      if (isBinary) {
+        handleBinaryFrame(new Uint8Array(data as Buffer))
+        return
+      }
+
+      const frame = data.toString()
+      if (state === 'awaiting_ready') {
+        handleReadyFrame(frame)
+        return
+      }
+
+      const plaintext = decrypt(frame, sharedKey)
+      if (plaintext === null) {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an undecryptable frame.'
+          )
+        )
+        return
+      }
+
+      if (state === 'awaiting_authenticated') {
+        handleAuthenticatedFrame(plaintext)
+        return
+      }
+
+      handleRpcFrame(plaintext)
+    })
+
+    function handleReadyFrame(frame: string): void {
+      let ready: unknown
+      try {
+        ready = JSON.parse(frame)
+      } catch {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an invalid E2EE handshake frame.'
+          )
+        )
+        return
+      }
+      if (
+        typeof ready !== 'object' ||
+        ready === null ||
+        (ready as { type?: unknown }).type !== 'e2ee_ready'
+      ) {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an unexpected E2EE handshake frame.'
+          )
+        )
+        return
+      }
+      state = 'awaiting_authenticated'
+      ws?.send(
+        encrypt(JSON.stringify({ type: 'e2ee_auth', deviceToken: pairing.deviceToken }), sharedKey)
+      )
+    }
+
+    function handleAuthenticatedFrame(plaintext: string): void {
+      let authenticated: unknown
+      try {
+        authenticated = JSON.parse(plaintext)
+      } catch {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an invalid E2EE auth frame.'
+          )
+        )
+        return
+      }
+      const type = (authenticated as { type?: unknown }).type
+      if (type !== 'e2ee_authenticated') {
+        const code =
+          typeof authenticated === 'object' &&
+          authenticated !== null &&
+          (authenticated as { error?: { code?: unknown } }).error?.code === 'unauthorized'
+            ? 'unauthorized'
+            : 'invalid_runtime_response'
+        fail(new RemoteRuntimeClientError(code, 'Remote Orca runtime rejected the pairing token.'))
+        return
+      }
+      state = 'ready'
+      ws?.send(
+        encrypt(
+          JSON.stringify({
+            id: requestId,
+            deviceToken: pairing.deviceToken,
+            method,
+            params
+          }),
+          sharedKey
+        )
+      )
+      succeed()
+    }
+
+    function handleRpcFrame(plaintext: string): void {
+      let raw: unknown
+      try {
+        raw = JSON.parse(plaintext)
+      } catch {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an invalid response frame.'
+          )
+        )
+        return
+      }
+      const parsed = RuntimeRpcEnvelopeSchema.safeParse(raw)
+      if (!parsed.success || '_keepalive' in parsed.data) {
+        return
+      }
+      const response = parsed.data as RuntimeRpcResponse<TResult>
+      if (response.id !== requestId) {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned a mismatched response id.'
+          )
+        )
+        return
+      }
+      callbacks.onResponse(response)
+    }
+
+    function handleBinaryFrame(frame: Uint8Array<ArrayBufferLike>): void {
+      if (state !== 'ready') {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned binary data before authentication.'
+          )
+        )
+        return
+      }
+      const plaintext = decryptBytes(frame, sharedKey)
+      if (plaintext === null) {
+        fail(
+          new RemoteRuntimeClientError(
+            'invalid_runtime_response',
+            'Remote Orca runtime returned an undecryptable binary frame.'
+          )
+        )
+        return
+      }
+      callbacks.onBinary?.(plaintext)
+    }
+  })
+}
diff --git a/src/shared/remote-runtime-request-connection-stale.test.ts b/src/shared/remote-runtime-request-connection-stale.test.ts
new file mode 100644
index 00000000000..39afac27b6e
--- /dev/null
+++ b/src/shared/remote-runtime-request-connection-stale.test.ts
@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import WebSocket from 'ws'
+import type { PairingOffer } from './pairing'
+import { decrypt, encrypt } from './e2ee-crypto'
+import type { RemoteRuntimeWebSocketCallbacks } from './remote-runtime-request-websocket'
+
+const opens: FakeOpenedSocket[] = []
+
+vi.mock('./remote-runtime-request-websocket', () => ({
+  openRemoteRuntimeWebSocket: (
+    _pairing: PairingOffer,
+    callbacks: RemoteRuntimeWebSocketCallbacks
+  ) => {
+    const socket = createFakeOpenedSocket(callbacks)
+    opens.push(socket)
+    return { ok: true, socket: { ws: socket.ws, sharedKey: socket.sharedKey } }
+  }
+}))
+
+type FakeOpenedSocket = {
+  ws: WebSocket
+  sharedKey: Uint8Array
+  sent: string[]
+  callbacks: RemoteRuntimeWebSocketCallbacks
+}
+
+function createFakeOpenedSocket(callbacks: RemoteRuntimeWebSocketCallbacks): FakeOpenedSocket {
+  const sent: string[] = []
+  const ws = {
+    readyState: WebSocket.OPEN,
+    send: (frame: string) => {
+      sent.push(frame)
+    },
+    close: vi.fn()
+  } as unknown as WebSocket
+  return {
+    ws,
+    sharedKey: new Uint8Array(32).fill(opens.length + 1),
+    sent,
+    callbacks
+  }
+}
+
+function authenticate(socket: FakeOpenedSocket): void {
+  socket.callbacks.onTextFrame(socket.ws, JSON.stringify({ type: 'e2ee_ready' }))
+  socket.callbacks.onTextFrame(
+    socket.ws,
+    encrypt(JSON.stringify({ type: 'e2ee_authenticated' }), socket.sharedKey)
+  )
+}
+
+function latestRequestId(socket: FakeOpenedSocket): string {
+  const plaintext = decrypt(socket.sent.at(-1) ?? '', socket.sharedKey)
+  if (plaintext === null) {
+    throw new Error('missing encrypted request')
+  }
+  return (JSON.parse(plaintext) as { id: string }).id
+}
+
+describe('RemoteRuntimeRequestConnection stale socket callbacks', () => {
+  beforeEach(() => {
+    opens.splice(0)
+  })
+
+  it('ignores stale socket errors and text frames after a replacement socket opens', async () => {
+    vi.useFakeTimers()
+    try {
+      const { RemoteRuntimeRequestConnection } =
+        await import('./remote-runtime-request-connection.js')
+      const connection = new RemoteRuntimeRequestConnection({
+        v: 2,
+        endpoint: 'ws://127.0.0.1:6768',
+        deviceToken: 'device-token',
+        publicKeyB64: Buffer.from(new Uint8Array(32).fill(9)).toString('base64')
+      })
+
+      const first = connection.request('slow.method', undefined, 10)
+      authenticate(opens[0]!)
+      const firstRejected = expect(first).rejects.toThrow('Timed out')
+      await vi.advanceTimersByTimeAsync(11)
+      await firstRejected
+
+      const second = connection.request('status.get', undefined, 1000)
+      authenticate(opens[1]!)
+      await vi.waitFor(() => expect(opens[1]!.sent.length).toBeGreaterThan(1))
+
+      opens[0]!.callbacks.onError(opens[0]!.ws, new Error('stale socket error') as never)
+      opens[0]!.callbacks.onTextFrame(
+        opens[0]!.ws,
+        encrypt(JSON.stringify({ id: 'stale', ok: true, result: {} }), opens[0]!.sharedKey)
+      )
+
+      const requestId = latestRequestId(opens[1]!)
+      opens[1]!.callbacks.onTextFrame(
+        opens[1]!.ws,
+        encrypt(
+          JSON.stringify({
+            id: requestId,
+            ok: true,
+            result: { state: 'ok' },
+            _meta: { runtimeId: 'runtime-2' }
+          }),
+          opens[1]!.sharedKey
+        )
+      )
+
+      await expect(second).resolves.toMatchObject({
+        ok: true,
+        result: { state: 'ok' }
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
diff --git a/src/shared/remote-runtime-request-connection.test.ts b/src/shared/remote-runtime-request-connection.test.ts
new file mode 100644
index 00000000000..3a9d7f1b191
--- /dev/null
+++ b/src/shared/remote-runtime-request-connection.test.ts
@@ -0,0 +1,142 @@
+import type { AddressInfo } from 'net'
+import { afterEach, describe, expect, it } from 'vitest'
+import { WebSocketServer, type WebSocket } from 'ws'
+import { encodePairingOffer, parsePairingCode, type PairingOffer } from './pairing'
+import {
+  decrypt,
+  deriveSharedKey,
+  encrypt,
+  generateKeyPair,
+  publicKeyFromBase64,
+  publicKeyToBase64
+} from './e2ee-crypto'
+import { RemoteRuntimeRequestConnection } from './remote-runtime-request-connection'
+
+type TestServer = {
+  wss: WebSocketServer
+  pairing: PairingOffer
+  requests: unknown[]
+  connectionCount: () => number
+}
+
+const servers: WebSocketServer[] = []
+
+afterEach(async () => {
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          for (const client of server.clients) {
+            client.close()
+          }
+          server.close(() => resolve())
+        })
+    )
+  )
+})
+
+describe('RemoteRuntimeRequestConnection', () => {
+  it('reuses one encrypted WebSocket for multiple one-shot RPCs', async () => {
+    const server = await createServer()
+    const connection = new RemoteRuntimeRequestConnection(server.pairing)
+
+    const first = await connection.request('status.get', undefined, 1000)
+    const second = await connection.request('terminal.send', { terminal: 't1', text: 'ab' }, 1000)
+
+    expect(first).toMatchObject({
+      ok: true,
+      result: { method: 'status.get' },
+      _meta: { runtimeId: 'runtime-test' }
+    })
+    expect(second).toMatchObject({
+      ok: true,
+      result: { method: 'terminal.send' },
+      _meta: { runtimeId: 'runtime-test' }
+    })
+    expect(server.connectionCount()).toBe(1)
+    expect(server.requests).toMatchObject([
+      { method: 'status.get' },
+      { method: 'terminal.send', params: { terminal: 't1', text: 'ab' } }
+    ])
+
+    connection.close()
+  })
+})
+
+async function createServer(): Promise<TestServer> {
+  const serverKeyPair = generateKeyPair()
+  const requests: unknown[] = []
+  let connectionCount = 0
+  const wss = new WebSocketServer({ port: 0 })
+  servers.push(wss)
+
+  wss.on('connection', (ws) => {
+    connectionCount += 1
+    let sharedKey: Uint8Array | null = null
+    let authenticated = false
+
+    ws.on('message', (data, isBinary) => {
+      if (isBinary) {
+        return
+      }
+      const frame = data.toString()
+      if (!sharedKey) {
+        const hello = JSON.parse(frame) as { type: string; publicKeyB64: string }
+        const clientPublicKey = publicKeyFromBase64(hello.publicKeyB64)
+        sharedKey = deriveSharedKey(serverKeyPair.secretKey, clientPublicKey)
+        ws.send(JSON.stringify({ type: 'e2ee_ready' }))
+        return
+      }
+
+      const plaintext = decrypt(frame, sharedKey)
+      if (plaintext === null) {
+        return
+      }
+      if (!authenticated) {
+        const auth = JSON.parse(plaintext) as { type: string; deviceToken: string }
+        expect(auth).toEqual({ type: 'e2ee_auth', deviceToken: 'device-token' })
+        authenticated = true
+        sendEncrypted(ws, sharedKey, { type: 'e2ee_authenticated' })
+        return
+      }
+
+      const request = JSON.parse(plaintext) as {
+        id: string
+        method: string
+        params?: unknown
+      }
+      requests.push(request)
+      sendEncrypted(ws, sharedKey, {
+        id: request.id,
+        ok: true,
+        result: { method: request.method },
+        _meta: { runtimeId: 'runtime-test' }
+      })
+    })
+  })
+
+  await new Promise<void>((resolve) => wss.once('listening', resolve))
+  const address = wss.address() as AddressInfo
+  const pairing = parsePairingCode(
+    encodePairingOffer({
+      v: 2,
+      endpoint: `ws://127.0.0.1:${address.port}`,
+      deviceToken: 'device-token',
+      publicKeyB64: publicKeyToBase64(serverKeyPair.publicKey)
+    })
+  )
+  if (!pairing) {
+    throw new Error('Failed to create test pairing')
+  }
+
+  return {
+    wss,
+    pairing,
+    requests,
+    connectionCount: () => connectionCount
+  }
+}
+
+function sendEncrypted(ws: WebSocket, sharedKey: Uint8Array, message: unknown): void {
+  ws.send(encrypt(JSON.stringify(message), sharedKey))
+}
diff --git a/src/shared/remote-runtime-request-connection.ts b/src/shared/remote-runtime-request-connection.ts
new file mode 100644
index 00000000000..17f6605ab87
--- /dev/null
+++ b/src/shared/remote-runtime-request-connection.ts
@@ -0,0 +1,292 @@
+import { randomUUID } from 'crypto'
+import WebSocket from 'ws'
+import type { PairingOffer } from './pairing'
+import { decrypt, encrypt } from './e2ee-crypto'
+import type { RuntimeRpcResponse } from './runtime-rpc-envelope'
+import { RemoteRuntimeClientError } from './remote-runtime-client'
+import {
+  invalidRemoteRuntimeResponseError,
+  parseAuthenticatedFrame,
+  parseReadyFrame,
+  parseRemoteRuntimeRpcFrame,
+  remoteRuntimeTimeoutError,
+  remoteRuntimeUnavailableError
+} from './remote-runtime-request-frames'
+import { openRemoteRuntimeWebSocket } from './remote-runtime-request-websocket'
+
+type ConnectionState = 'closed' | 'awaiting_ready' | 'awaiting_authenticated' | 'ready'
+
+type PendingRequest<TResult> = {
+  resolve: (response: RuntimeRpcResponse<TResult>) => void
+  reject: (error: Error) => void
+  timeout: ReturnType<typeof setTimeout>
+}
+
+type ReadyWaiter = {
+  resolve: () => void
+  reject: (error: Error) => void
+}
+
+const IDLE_CLOSE_MS = 60_000
+
+export class RemoteRuntimeRequestConnection {
+  private readonly pairing: PairingOffer
+  private state: ConnectionState = 'closed'
+  private ws: WebSocket | null = null
+  private sharedKey: Uint8Array | null = null
+  private readonly pendingRequests = new Map<string, PendingRequest<unknown>>()
+  private readonly readyWaiters: ReadyWaiter[] = []
+  private idleCloseTimer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(pairing: PairingOffer) {
+    this.pairing = pairing
+  }
+
+  request<TResult>(
+    method: string,
+    params: unknown,
+    timeoutMs: number
+  ): Promise<RuntimeRpcResponse<TResult>> {
+    this.clearIdleCloseTimer()
+    const requestId = randomUUID()
+    return new Promise<RuntimeRpcResponse<TResult>>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const pending = this.pendingRequests.get(requestId)
+        if (!pending) {
+          return
+        }
+        this.pendingRequests.delete(requestId)
+        const error = remoteRuntimeTimeoutError()
+        pending.reject(error)
+        this.close(error)
+      }, timeoutMs)
+      this.pendingRequests.set(requestId, {
+        resolve: resolve as (response: RuntimeRpcResponse<unknown>) => void,
+        reject,
+        timeout
+      })
+
+      void this.ensureReady().then(
+        () => this.sendRequest(requestId, method, params),
+        (error) => this.rejectPendingRequest(requestId, toClientError(error))
+      )
+    })
+  }
+
+  close(error?: Error): void {
+    const ws = this.ws
+    this.ws = null
+    this.sharedKey = null
+    this.state = 'closed'
+    this.clearIdleCloseTimer()
+
+    const closeError = error ?? remoteRuntimeUnavailableError()
+    this.rejectReadyWaiters(closeError)
+    for (const [requestId, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeout)
+      this.pendingRequests.delete(requestId)
+      pending.reject(closeError)
+    }
+
+    try {
+      ws?.close()
+    } catch {
+      // Best-effort shutdown for a cached remote control connection.
+    }
+  }
+
+  private ensureReady(): Promise<void> {
+    const ws = this.ws
+    if (this.state === 'ready' && ws?.readyState === WebSocket.OPEN && this.sharedKey) {
+      return Promise.resolve()
+    }
+
+    const promise = new Promise<void>((resolve, reject) => {
+      this.readyWaiters.push({ resolve, reject })
+    })
+
+    if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) {
+      this.open()
+    }
+
+    return promise
+  }
+
+  private open(): void {
+    const opened = openRemoteRuntimeWebSocket(this.pairing, {
+      onClose: (ws) => {
+        if (this.ws === ws) {
+          this.close()
+        }
+      },
+      onError: (ws, error) => {
+        if (this.ws === ws) {
+          this.close(error)
+        }
+      },
+      onTextFrame: (ws, frame) => {
+        if (this.ws === ws) {
+          this.handleTextFrame(frame)
+        }
+      }
+    })
+    if (!opened.ok) {
+      this.close(opened.error)
+      return
+    }
+    this.ws = opened.socket.ws
+    this.sharedKey = opened.socket.sharedKey
+    this.state = 'awaiting_ready'
+  }
+
+  private handleTextFrame(frame: string): void {
+    if (this.state === 'awaiting_ready') {
+      this.handleReadyFrame(frame)
+      return
+    }
+
+    const sharedKey = this.sharedKey
+    if (!sharedKey) {
+      return
+    }
+    const plaintext = decrypt(frame, sharedKey)
+    if (plaintext === null) {
+      this.close(
+        invalidRemoteRuntimeResponseError('Remote Orca runtime returned an undecryptable frame.')
+      )
+      return
+    }
+
+    if (this.state === 'awaiting_authenticated') {
+      this.handleAuthenticatedFrame(plaintext)
+      return
+    }
+
+    this.handleRpcFrame(plaintext)
+  }
+
+  private handleReadyFrame(frame: string): void {
+    const error = parseReadyFrame(frame)
+    if (error) {
+      this.close(error)
+      return
+    }
+    this.state = 'awaiting_authenticated'
+    const sharedKey = this.sharedKey
+    if (!sharedKey) {
+      return
+    }
+    this.ws?.send(
+      encrypt(
+        JSON.stringify({ type: 'e2ee_auth', deviceToken: this.pairing.deviceToken }),
+        sharedKey
+      )
+    )
+  }
+
+  private handleAuthenticatedFrame(plaintext: string): void {
+    const error = parseAuthenticatedFrame(plaintext)
+    if (error) {
+      this.close(error)
+      return
+    }
+    this.state = 'ready'
+    this.resolveReadyWaiters()
+    this.scheduleIdleCloseIfUnused()
+  }
+
+  private handleRpcFrame(plaintext: string): void {
+    const parsed = parseRemoteRuntimeRpcFrame(plaintext)
+    if (parsed.type === 'keepalive') {
+      return
+    }
+    if (parsed.type === 'error') {
+      this.close(parsed.error)
+      return
+    }
+
+    const response = parsed.response
+    const pending = this.pendingRequests.get(response.id)
+    if (!pending) {
+      return
+    }
+    this.pendingRequests.delete(response.id)
+    clearTimeout(pending.timeout)
+    pending.resolve(response)
+    this.scheduleIdleCloseIfUnused()
+  }
+
+  private sendRequest(requestId: string, method: string, params: unknown): void {
+    const pending = this.pendingRequests.get(requestId)
+    const ws = this.ws
+    const sharedKey = this.sharedKey
+    if (!pending) {
+      return
+    }
+    if (this.state !== 'ready' || !ws || ws.readyState !== WebSocket.OPEN || !sharedKey) {
+      this.rejectPendingRequest(requestId, remoteRuntimeUnavailableError())
+      return
+    }
+    ws.send(
+      encrypt(
+        JSON.stringify({
+          id: requestId,
+          deviceToken: this.pairing.deviceToken,
+          method,
+          params
+        }),
+        sharedKey
+      )
+    )
+  }
+
+  private rejectPendingRequest(requestId: string, error: Error): void {
+    const pending = this.pendingRequests.get(requestId)
+    if (!pending) {
+      return
+    }
+    this.pendingRequests.delete(requestId)
+    clearTimeout(pending.timeout)
+    pending.reject(error)
+    this.scheduleIdleCloseIfUnused()
+  }
+
+  private resolveReadyWaiters(): void {
+    const waiters = this.readyWaiters.splice(0)
+    for (const waiter of waiters) {
+      waiter.resolve()
+    }
+  }
+
+  private rejectReadyWaiters(error: Error): void {
+    const waiters = this.readyWaiters.splice(0)
+    for (const waiter of waiters) {
+      waiter.reject(error)
+    }
+  }
+
+  private scheduleIdleCloseIfUnused(): void {
+    if (this.pendingRequests.size > 0 || this.readyWaiters.length > 0 || this.state !== 'ready') {
+      return
+    }
+    this.clearIdleCloseTimer()
+    this.idleCloseTimer = setTimeout(() => this.close(), IDLE_CLOSE_MS)
+    if (typeof this.idleCloseTimer.unref === 'function') {
+      this.idleCloseTimer.unref()
+    }
+  }
+
+  private clearIdleCloseTimer(): void {
+    if (this.idleCloseTimer) {
+      clearTimeout(this.idleCloseTimer)
+      this.idleCloseTimer = null
+    }
+  }
+}
+
+function toClientError(error: unknown): Error {
+  if (error instanceof Error) {
+    return error
+  }
+  return new RemoteRuntimeClientError('runtime_error', String(error))
+}
diff --git a/src/shared/remote-runtime-request-frames.ts b/src/shared/remote-runtime-request-frames.ts
new file mode 100644
index 00000000000..b48212d0f5b
--- /dev/null
+++ b/src/shared/remote-runtime-request-frames.ts
@@ -0,0 +1,98 @@
+import {
+  RuntimeRpcEnvelopeSchema,
+  type RuntimeRpcResponse,
+  isKeepaliveFrame
+} from './runtime-rpc-envelope'
+import { RemoteRuntimeClientError } from './remote-runtime-client'
+
+export type ParsedRemoteRuntimeFrame =
+  | { type: 'keepalive' }
+  | { type: 'response'; response: RuntimeRpcResponse<unknown> }
+  | { type: 'error'; error: RemoteRuntimeClientError }
+
+export function remoteRuntimeUnavailableError(
+  message = 'Remote Orca runtime closed the connection.'
+): RemoteRuntimeClientError {
+  return new RemoteRuntimeClientError('remote_runtime_unavailable', message)
+}
+
+export function remoteRuntimeTimeoutError(): RemoteRuntimeClientError {
+  return new RemoteRuntimeClientError(
+    'runtime_timeout',
+    'Timed out waiting for the remote Orca runtime to respond.'
+  )
+}
+
+export function invalidRemoteRuntimeResponseError(message: string): RemoteRuntimeClientError {
+  return new RemoteRuntimeClientError('invalid_runtime_response', message)
+}
+
+export function parseReadyFrame(frame: string): RemoteRuntimeClientError | null {
+  let ready: unknown
+  try {
+    ready = JSON.parse(frame)
+  } catch {
+    return invalidRemoteRuntimeResponseError(
+      'Remote Orca runtime returned an invalid E2EE handshake frame.'
+    )
+  }
+  if (
+    typeof ready !== 'object' ||
+    ready === null ||
+    (ready as { type?: unknown }).type !== 'e2ee_ready'
+  ) {
+    return invalidRemoteRuntimeResponseError(
+      'Remote Orca runtime returned an unexpected E2EE handshake frame.'
+    )
+  }
+  return null
+}
+
+export function parseAuthenticatedFrame(plaintext: string): RemoteRuntimeClientError | null {
+  let authenticated: unknown
+  try {
+    authenticated = JSON.parse(plaintext)
+  } catch {
+    return invalidRemoteRuntimeResponseError(
+      'Remote Orca runtime returned an invalid E2EE auth frame.'
+    )
+  }
+  const type = (authenticated as { type?: unknown }).type
+  if (type === 'e2ee_authenticated') {
+    return null
+  }
+  const code =
+    typeof authenticated === 'object' &&
+    authenticated !== null &&
+    (authenticated as { error?: { code?: unknown } }).error?.code === 'unauthorized'
+      ? 'unauthorized'
+      : 'invalid_runtime_response'
+  return new RemoteRuntimeClientError(code, 'Remote Orca runtime rejected the pairing token.')
+}
+
+export function parseRemoteRuntimeRpcFrame(plaintext: string): ParsedRemoteRuntimeFrame {
+  let raw: unknown
+  try {
+    raw = JSON.parse(plaintext)
+  } catch {
+    return {
+      type: 'error',
+      error: invalidRemoteRuntimeResponseError(
+        'Remote Orca runtime returned an invalid response frame.'
+      )
+    }
+  }
+  if (isKeepaliveFrame(raw)) {
+    return { type: 'keepalive' }
+  }
+  const parsed = RuntimeRpcEnvelopeSchema.safeParse(raw)
+  if (!parsed.success || '_keepalive' in parsed.data) {
+    return {
+      type: 'error',
+      error: invalidRemoteRuntimeResponseError(
+        'Remote Orca runtime returned an invalid response frame.'
+      )
+    }
+  }
+  return { type: 'response', response: parsed.data as RuntimeRpcResponse<unknown> }
+}
diff --git a/src/shared/remote-runtime-request-websocket.ts b/src/shared/remote-runtime-request-websocket.ts
new file mode 100644
index 00000000000..569ef9e2759
--- /dev/null
+++ b/src/shared/remote-runtime-request-websocket.ts
@@ -0,0 +1,96 @@
+import WebSocket from 'ws'
+import type { PairingOffer } from './pairing'
+import {
+  deriveSharedKey,
+  generateKeyPair,
+  publicKeyFromBase64,
+  publicKeyToBase64
+} from './e2ee-crypto'
+import { RemoteRuntimeClientError } from './remote-runtime-client'
+import {
+  invalidRemoteRuntimeResponseError,
+  remoteRuntimeUnavailableError
+} from './remote-runtime-request-frames'
+
+export type RemoteRuntimeWebSocket = {
+  ws: WebSocket
+  sharedKey: Uint8Array
+}
+
+export type RemoteRuntimeWebSocketCallbacks = {
+  onClose: (ws: WebSocket) => void
+  onError: (ws: WebSocket, error: RemoteRuntimeClientError) => void
+  onTextFrame: (ws: WebSocket, frame: string) => void
+}
+
+export function openRemoteRuntimeWebSocket(
+  pairing: PairingOffer,
+  callbacks: RemoteRuntimeWebSocketCallbacks
+): { ok: true; socket: RemoteRuntimeWebSocket } | { ok: false; error: RemoteRuntimeClientError } {
+  const opened = createSocket(pairing)
+  if (!opened.ok) {
+    return opened
+  }
+  const { ws, keyPair } = opened
+  const serverPublicKey = publicKeyFromBase64(pairing.publicKeyB64)
+  const sharedKey = deriveSharedKey(keyPair.secretKey, serverPublicKey)
+
+  ws.once('open', () => {
+    ws.send(
+      JSON.stringify({
+        type: 'e2ee_hello',
+        publicKeyB64: publicKeyToBase64(keyPair.publicKey)
+      })
+    )
+  })
+  ws.on('error', () => {
+    callbacks.onError(
+      ws,
+      remoteRuntimeUnavailableError('Could not connect to the remote Orca runtime.')
+    )
+  })
+  ws.on('close', () => callbacks.onClose(ws))
+  ws.on('message', (data, isBinary) => {
+    if (isBinary) {
+      callbacks.onError(
+        ws,
+        invalidRemoteRuntimeResponseError(
+          'Remote Orca runtime returned an unexpected binary frame.'
+        )
+      )
+      return
+    }
+    callbacks.onTextFrame(ws, data.toString())
+  })
+  return { ok: true, socket: { ws, sharedKey } }
+}
+
+function createSocket(
+  pairing: PairingOffer
+):
+  | { ok: true; ws: WebSocket; keyPair: ReturnType<typeof generateKeyPair> }
+  | { ok: false; error: RemoteRuntimeClientError } {
+  let keyPair: ReturnType<typeof generateKeyPair>
+  try {
+    keyPair = generateKeyPair()
+    publicKeyFromBase64(pairing.publicKeyB64)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      ok: false,
+      error: new RemoteRuntimeClientError(
+        'invalid_argument',
+        `Invalid remote pairing key: ${message}`
+      )
+    }
+  }
+  try {
+    return { ok: true, ws: new WebSocket(pairing.endpoint), keyPair }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      ok: false,
+      error: new RemoteRuntimeClientError('invalid_argument', `Invalid remote endpoint: ${message}`)
+    }
+  }
+}
diff --git a/src/shared/runtime-environment-store.test.ts b/src/shared/runtime-environment-store.test.ts
new file mode 100644
index 00000000000..649775d11b7
--- /dev/null
+++ b/src/shared/runtime-environment-store.test.ts
@@ -0,0 +1,47 @@
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { encodePairingOffer } from './pairing'
+import {
+  RuntimeEnvironmentStoreError,
+  addEnvironmentFromPairingCode,
+  listEnvironments
+} from './runtime-environment-store'
+
+function pairingCode(endpoint = 'ws://127.0.0.1:6768'): string {
+  return encodePairingOffer({
+    v: 2,
+    endpoint,
+    deviceToken: 'device-token',
+    publicKeyB64: Buffer.from(new Uint8Array(32).fill(1)).toString('base64')
+  })
+}
+
+describe('runtime environment store', () => {
+  const tempDirs: string[] = []
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects duplicate server names instead of silently replacing the saved server', () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-env-store-'))
+    tempDirs.push(userDataPath)
+
+    const first = addEnvironmentFromPairingCode(userDataPath, {
+      name: 'dev box',
+      pairingCode: pairingCode('ws://127.0.0.1:6768')
+    })
+
+    expect(() =>
+      addEnvironmentFromPairingCode(userDataPath, {
+        name: 'dev box',
+        pairingCode: pairingCode('ws://192.0.2.10:6768')
+      })
+    ).toThrow(RuntimeEnvironmentStoreError)
+    expect(listEnvironments(userDataPath)).toEqual([first])
+  })
+})
diff --git a/src/shared/runtime-environment-store.ts b/src/shared/runtime-environment-store.ts
new file mode 100644
index 00000000000..2682ffb74dd
--- /dev/null
+++ b/src/shared/runtime-environment-store.ts
@@ -0,0 +1,166 @@
+import { randomUUID } from 'crypto'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { parsePairingCode, type PairingOffer } from './pairing'
+import { hardenExistingSecureFile, writeSecureJsonFile } from './secure-file'
+import {
+  createEnvironmentFromPairingOffer,
+  getPreferredPairingOffer,
+  KnownRuntimeEnvironmentSchema,
+  RuntimeEnvironmentStoreSchema,
+  type KnownRuntimeEnvironment,
+  type RuntimeEnvironmentStore
+} from './runtime-environments'
+
+const ENVIRONMENTS_FILE = 'orca-environments.json'
+
+export type RuntimeEnvironmentStoreErrorCode = 'invalid_argument' | 'runtime_error'
+
+export class RuntimeEnvironmentStoreError extends Error {
+  readonly code: RuntimeEnvironmentStoreErrorCode
+
+  constructor(code: RuntimeEnvironmentStoreErrorCode, message: string) {
+    super(message)
+    this.name = 'RuntimeEnvironmentStoreError'
+    this.code = code
+  }
+}
+
+export function getEnvironmentStorePath(userDataPath: string): string {
+  return join(userDataPath, ENVIRONMENTS_FILE)
+}
+
+export function listEnvironments(userDataPath: string): KnownRuntimeEnvironment[] {
+  return readEnvironmentStore(userDataPath).environments
+}
+
+export function addEnvironmentFromPairingCode(
+  userDataPath: string,
+  args: { name: string; pairingCode: string; now?: number }
+): KnownRuntimeEnvironment {
+  const offer = parsePairingCode(args.pairingCode)
+  if (!offer) {
+    throw new RuntimeEnvironmentStoreError(
+      'invalid_argument',
+      'Invalid pairing code. Expected an orca://pair#... URL or bare pairing payload.'
+    )
+  }
+  const store = readEnvironmentStore(userDataPath)
+  const now = args.now ?? Date.now()
+  const existing = store.environments.find((entry) => entry.name === args.name)
+  if (existing) {
+    throw new RuntimeEnvironmentStoreError(
+      'invalid_argument',
+      `A server named "${args.name}" already exists.`
+    )
+  }
+  const environment = createEnvironmentFromPairingOffer({
+    id: randomUUID(),
+    name: args.name,
+    now,
+    offer,
+    runtimeId: null
+  })
+  const next = {
+    version: 1 as const,
+    environments: [
+      ...store.environments.filter((entry) => entry.id !== environment.id),
+      environment
+    ].sort((a, b) => a.name.localeCompare(b.name))
+  }
+  writeEnvironmentStore(userDataPath, next)
+  return environment
+}
+
+export function removeEnvironment(userDataPath: string, selector: string): KnownRuntimeEnvironment {
+  const store = readEnvironmentStore(userDataPath)
+  const environment = resolveEnvironmentFromStore(store, selector)
+  writeEnvironmentStore(userDataPath, {
+    version: 1,
+    environments: store.environments.filter((entry) => entry.id !== environment.id)
+  })
+  return environment
+}
+
+export function resolveEnvironment(
+  userDataPath: string,
+  selector: string
+): KnownRuntimeEnvironment {
+  return resolveEnvironmentFromStore(readEnvironmentStore(userDataPath), selector)
+}
+
+export function resolveEnvironmentPairingOffer(
+  userDataPath: string,
+  selector: string
+): PairingOffer {
+  return getPreferredPairingOffer(resolveEnvironment(userDataPath, selector))
+}
+
+export function markEnvironmentUsed(
+  userDataPath: string,
+  selector: string,
+  args: { runtimeId?: string | null; now?: number } = {}
+): void {
+  const store = readEnvironmentStore(userDataPath)
+  const environment = resolveEnvironmentFromStore(store, selector)
+  const now = args.now ?? Date.now()
+  const next = store.environments.map((entry) =>
+    entry.id === environment.id
+      ? {
+          ...entry,
+          runtimeId: args.runtimeId ?? entry.runtimeId,
+          lastUsedAt: now,
+          updatedAt: now
+        }
+      : entry
+  )
+  writeEnvironmentStore(userDataPath, { version: 1, environments: next })
+}
+
+function resolveEnvironmentFromStore(
+  store: RuntimeEnvironmentStore,
+  selector: string
+): KnownRuntimeEnvironment {
+  const byId = store.environments.find((entry) => entry.id === selector)
+  if (byId) {
+    return byId
+  }
+  const matches = store.environments.filter((entry) => entry.name === selector)
+  if (matches.length === 1) {
+    return matches[0]!
+  }
+  if (matches.length > 1) {
+    throw new RuntimeEnvironmentStoreError(
+      'invalid_argument',
+      `Environment name "${selector}" is ambiguous; use the environment id.`
+    )
+  }
+  throw new RuntimeEnvironmentStoreError('invalid_argument', `Unknown environment: ${selector}`)
+}
+
+function readEnvironmentStore(userDataPath: string): RuntimeEnvironmentStore {
+  const path = getEnvironmentStorePath(userDataPath)
+  if (!existsSync(path)) {
+    return { version: 1, environments: [] }
+  }
+  try {
+    hardenExistingSecureFile(path)
+    const parsed = RuntimeEnvironmentStoreSchema.parse(JSON.parse(readFileSync(path, 'utf8')))
+    return {
+      version: 1,
+      environments: parsed.environments
+        .map((entry) => KnownRuntimeEnvironmentSchema.parse(entry))
+        .sort((a, b) => a.name.localeCompare(b.name))
+    }
+  } catch {
+    throw new RuntimeEnvironmentStoreError(
+      'runtime_error',
+      `Could not read Orca environments at ${path}; the file is invalid.`
+    )
+  }
+}
+
+function writeEnvironmentStore(userDataPath: string, store: RuntimeEnvironmentStore): void {
+  const path = getEnvironmentStorePath(userDataPath)
+  writeSecureJsonFile(path, RuntimeEnvironmentStoreSchema.parse(store))
+}
diff --git a/src/shared/runtime-environments.ts b/src/shared/runtime-environments.ts
new file mode 100644
index 00000000000..4f315b42dba
--- /dev/null
+++ b/src/shared/runtime-environments.ts
@@ -0,0 +1,99 @@
+import { z } from 'zod'
+import { PAIRING_OFFER_VERSION, type PairingOffer } from './pairing'
+
+export const RuntimeAccessEndpointSchema = z.object({
+  id: z.string().min(1),
+  kind: z.literal('websocket'),
+  label: z.string().min(1),
+  endpoint: z.string().min(1),
+  deviceToken: z.string().min(1),
+  publicKeyB64: z.string().min(1)
+})
+
+export type RuntimeAccessEndpoint = z.infer<typeof RuntimeAccessEndpointSchema>
+
+export const PublicRuntimeAccessEndpointSchema = RuntimeAccessEndpointSchema.omit({
+  deviceToken: true,
+  publicKeyB64: true
+})
+
+export type PublicRuntimeAccessEndpoint = z.infer<typeof PublicRuntimeAccessEndpointSchema>
+
+export const KnownRuntimeEnvironmentSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  createdAt: z.number().finite(),
+  updatedAt: z.number().finite(),
+  lastUsedAt: z.number().finite().nullable(),
+  runtimeId: z.string().min(1).nullable(),
+  endpoints: z.array(RuntimeAccessEndpointSchema).min(1),
+  preferredEndpointId: z.string().min(1)
+})
+
+export type KnownRuntimeEnvironment = z.infer<typeof KnownRuntimeEnvironmentSchema>
+
+export type PublicKnownRuntimeEnvironment = Omit<KnownRuntimeEnvironment, 'endpoints'> & {
+  endpoints: PublicRuntimeAccessEndpoint[]
+}
+
+export function redactRuntimeEnvironment(
+  environment: KnownRuntimeEnvironment
+): PublicKnownRuntimeEnvironment {
+  return {
+    ...environment,
+    endpoints: environment.endpoints.map(
+      ({ deviceToken: _deviceToken, publicKeyB64: _key, ...rest }) => rest
+    )
+  }
+}
+
+export const RuntimeEnvironmentStoreSchema = z.object({
+  version: z.literal(1),
+  environments: z.array(KnownRuntimeEnvironmentSchema)
+})
+
+export type RuntimeEnvironmentStore = z.infer<typeof RuntimeEnvironmentStoreSchema>
+
+export function createEnvironmentFromPairingOffer(args: {
+  id: string
+  name: string
+  now: number
+  offer: PairingOffer
+  runtimeId?: string | null
+}): KnownRuntimeEnvironment {
+  const endpointId = `ws-${args.id}`
+  return KnownRuntimeEnvironmentSchema.parse({
+    id: args.id,
+    name: args.name,
+    createdAt: args.now,
+    updatedAt: args.now,
+    lastUsedAt: null,
+    runtimeId: args.runtimeId ?? null,
+    endpoints: [
+      {
+        id: endpointId,
+        kind: 'websocket',
+        label: 'WebSocket',
+        endpoint: args.offer.endpoint,
+        deviceToken: args.offer.deviceToken,
+        publicKeyB64: args.offer.publicKeyB64
+      }
+    ],
+    preferredEndpointId: endpointId
+  })
+}
+
+export function getPreferredPairingOffer(environment: KnownRuntimeEnvironment): PairingOffer {
+  const endpoint =
+    environment.endpoints.find((entry) => entry.id === environment.preferredEndpointId) ??
+    environment.endpoints[0]
+  if (!endpoint) {
+    throw new Error(`Environment ${environment.name} has no access endpoints`)
+  }
+  return {
+    v: PAIRING_OFFER_VERSION,
+    endpoint: endpoint.endpoint,
+    deviceToken: endpoint.deviceToken,
+    publicKeyB64: endpoint.publicKeyB64
+  }
+}
diff --git a/src/shared/runtime-rpc-envelope.ts b/src/shared/runtime-rpc-envelope.ts
new file mode 100644
index 00000000000..c72811c18a3
--- /dev/null
+++ b/src/shared/runtime-rpc-envelope.ts
@@ -0,0 +1,73 @@
+// Why: runtime clients can be CLI, desktop, or future non-Electron shells.
+// Keeping the envelope contract here avoids making those clients import each
+// other just to validate the shared RPC frame shape.
+import { z } from 'zod'
+
+const MetaSuccess = z.object({
+  runtimeId: z.string()
+})
+
+const MetaFailure = z
+  .object({
+    runtimeId: z.union([z.string(), z.null()])
+  })
+  .optional()
+
+const Success = z.object({
+  id: z.string(),
+  ok: z.literal(true),
+  result: z.unknown(),
+  _meta: MetaSuccess
+})
+
+const Failure = z.object({
+  id: z.string(),
+  ok: z.literal(false),
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    data: z.unknown().optional()
+  }),
+  _meta: MetaFailure
+})
+
+const Keepalive = z.object({
+  _keepalive: z.literal(true)
+})
+
+export const RuntimeRpcEnvelopeSchema = z.union([Success, Failure, Keepalive])
+
+export type RuntimeRpcSuccess<TResult> = {
+  id: string
+  ok: true
+  result: TResult
+  _meta: {
+    runtimeId: string
+  }
+}
+
+export type RuntimeRpcFailure = {
+  id: string
+  ok: false
+  error: {
+    code: string
+    message: string
+    data?: unknown
+  }
+  _meta?: {
+    runtimeId: string | null
+  }
+}
+
+export type RuntimeRpcResponse<TResult> = RuntimeRpcSuccess<TResult> | RuntimeRpcFailure
+
+export type RuntimeRpcKeepaliveFrame = z.infer<typeof Keepalive>
+
+export function isKeepaliveFrame(frame: unknown): frame is RuntimeRpcKeepaliveFrame {
+  return (
+    typeof frame === 'object' &&
+    frame !== null &&
+    '_keepalive' in frame &&
+    (frame as { _keepalive: unknown })._keepalive === true
+  )
+}
diff --git a/src/shared/runtime-types.ts b/src/shared/runtime-types.ts
index 97070dfe649..586252341e3 100644
--- a/src/shared/runtime-types.ts
+++ b/src/shared/runtime-types.ts
@@ -1,10 +1,18 @@
 /* eslint-disable max-lines -- Why: shared type definitions for all runtime RPC methods live in one file for discoverability and import simplicity. */
 import type { TerminalPaneLayoutNode } from './types'
-import type { BrowserSessionProfile, GitWorktreeInfo, Repo } from './types'
+import type {
+  BrowserCookieImportResult,
+  BrowserSessionProfile,
+  BrowserSessionProfileSource,
+  GitWorktreeInfo,
+  Repo,
+  Worktree
+} from './types'
 import type {
   RuntimeMarkdownReadTabResult,
   RuntimeMarkdownSaveTabResult
 } from './mobile-markdown-document'
+import type { RuntimeCapability } from './protocol-version'
 
 export type { RuntimeMarkdownReadTabResult, RuntimeMarkdownSaveTabResult }
 
@@ -17,9 +25,13 @@ export type RuntimeStatus = {
   authoritativeWindowId: number | null
   liveTabCount: number
   liveLeafCount: number
-  // Why: optional so mobile builds can read both new and pre-PR desktops.
-  // Absence is treated as 0 by mobile's compat evaluator. See
-  // src/shared/protocol-version.ts for bump discipline.
+  // Why: optional so clients can read both new and pre-contract runtimes.
+  // Absence is treated as protocol 0 by the compat evaluator.
+  runtimeProtocolVersion?: number
+  minCompatibleRuntimeClientVersion?: number
+  capabilities?: RuntimeCapability[]
+  // COMPAT(runtimeStatusMobileAliases): added 2026-05-15 for mobile builds
+  // that still read these names; new desktop/CLI code uses the fields above.
   protocolVersion?: number
   minCompatibleMobileVersion?: number
 }
@@ -189,6 +201,13 @@ export type RuntimeFileReadResult = {
   byteLength: number
 }
 
+export type RuntimeFilePreviewResult = {
+  content: string
+  isBinary: boolean
+  isImage?: boolean
+  mimeType?: string
+}
+
 export type RuntimeTerminalSummary = {
   handle: string
   worktreeId: string
@@ -292,15 +311,8 @@ export type RuntimeWorktreePsSummary = {
 
 export type RuntimeWorktreeStatus = 'active' | 'working' | 'permission' | 'done' | 'inactive'
 
-export type RuntimeWorktreeRecord = {
-  id: string
-  repoId: string
-  path: string
-  branch: string
-  linkedIssue: number | null
+export type RuntimeWorktreeRecord = Worktree & {
   git: GitWorktreeInfo
-  displayName: string
-  comment: string
 }
 
 export type RuntimeWorktreePsResult = {
@@ -446,6 +458,28 @@ export type BrowserProfileDeleteResult = {
   profileId: string
 }
 
+export type BrowserDetectedProfileInfo = {
+  name: string
+  directory: string
+}
+
+export type BrowserDetectedInfo = {
+  family: BrowserSessionProfileSource['browserFamily']
+  label: string
+  profiles: BrowserDetectedProfileInfo[]
+  selectedProfile: string
+}
+
+export type BrowserDetectProfilesResult = {
+  browsers: BrowserDetectedInfo[]
+}
+
+export type BrowserProfileImportFromBrowserResult = BrowserCookieImportResult
+
+export type BrowserProfileClearDefaultCookiesResult = {
+  cleared: boolean
+}
+
 export type BrowserHoverResult = {
   hovered: string
 }
diff --git a/src/shared/secure-file.ts b/src/shared/secure-file.ts
new file mode 100644
index 00000000000..3d662a0806b
--- /dev/null
+++ b/src/shared/secure-file.ts
@@ -0,0 +1,109 @@
+import { execFileSync } from 'child_process'
+import { randomBytes } from 'crypto'
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'fs'
+import { dirname } from 'path'
+
+let cachedWindowsUserSid: string | null | undefined
+
+export function writeSecureJsonFile(targetPath: string, value: unknown): void {
+  writeSecureFile(targetPath, JSON.stringify(value, null, 2))
+}
+
+export function writeSecureFile(targetPath: string, contents: string): void {
+  const dir = dirname(targetPath)
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+  }
+  hardenSecurePath(dir, { isDirectory: true, platform: process.platform })
+
+  const tmpFile = `${targetPath}.${process.pid}.${Date.now()}.${randomBytes(4).toString('hex')}.tmp`
+  try {
+    writeFileSync(tmpFile, contents, {
+      encoding: 'utf-8',
+      mode: 0o600
+    })
+    hardenSecurePath(tmpFile, { isDirectory: false, platform: process.platform })
+    renameSync(tmpFile, targetPath)
+    // Why: these files carry runtime auth/device credentials; the published
+    // path must remain current-user only after the atomic rename.
+    hardenSecurePath(targetPath, { isDirectory: false, platform: process.platform })
+  } catch (error) {
+    rmSync(tmpFile, { force: true })
+    throw error
+  }
+}
+
+export function hardenExistingSecureFile(targetPath: string): void {
+  const dir = dirname(targetPath)
+  if (existsSync(dir)) {
+    hardenSecurePath(dir, { isDirectory: true, platform: process.platform })
+  }
+  if (existsSync(targetPath)) {
+    hardenSecurePath(targetPath, { isDirectory: false, platform: process.platform })
+  }
+}
+
+export function hardenSecurePath(
+  targetPath: string,
+  options: {
+    isDirectory: boolean
+    platform: NodeJS.Platform
+  }
+): void {
+  if (options.platform === 'win32') {
+    bestEffortRestrictWindowsPath(targetPath)
+    return
+  }
+  chmodSync(targetPath, options.isDirectory ? 0o700 : 0o600)
+}
+
+function bestEffortRestrictWindowsPath(targetPath: string): void {
+  const currentUserSid = getCurrentWindowsUserSid()
+  if (!currentUserSid) {
+    return
+  }
+  try {
+    execFileSync(
+      'icacls',
+      [
+        targetPath,
+        '/inheritance:r',
+        '/grant:r',
+        `*${currentUserSid}:(F)`,
+        '*S-1-5-18:(F)',
+        '*S-1-5-32-544:(F)'
+      ],
+      {
+        stdio: 'ignore',
+        windowsHide: true,
+        timeout: 5000
+      }
+    )
+  } catch {
+    // Why: credential-file hardening should not prevent Orca from starting on
+    // Windows machines where icacls is unavailable or locked down differently.
+  }
+}
+
+function getCurrentWindowsUserSid(): string | null {
+  if (cachedWindowsUserSid !== undefined) {
+    return cachedWindowsUserSid
+  }
+  try {
+    const output = execFileSync('whoami', ['/user', '/fo', 'csv', '/nh'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+      timeout: 5000
+    }).trim()
+    const columns = parseCsvLine(output)
+    cachedWindowsUserSid = columns[1] ?? null
+  } catch {
+    cachedWindowsUserSid = null
+  }
+  return cachedWindowsUserSid
+}
+
+function parseCsvLine(line: string): string[] {
+  return line.split(/","/).map((part) => part.replace(/^"/, '').replace(/"$/, ''))
+}
diff --git a/src/shared/terminal-stream-protocol.test.ts b/src/shared/terminal-stream-protocol.test.ts
index 5dec28c811e..eb82bbc3980 100644
--- a/src/shared/terminal-stream-protocol.test.ts
+++ b/src/shared/terminal-stream-protocol.test.ts
@@ -44,6 +44,61 @@ describe('terminal-stream-protocol', () => {
     })
   })
 
+  it('round-trips terminal input and resize frames', () => {
+    const input = decodeTerminalStreamFrame(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Input,
+        streamId: 11,
+        seq: 1,
+        payload: encodeTerminalStreamText('a')
+      })
+    )
+    const resize = decodeTerminalStreamFrame(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Resize,
+        streamId: 11,
+        seq: 2,
+        payload: encodeTerminalStreamJson({ cols: 120, rows: 40 })
+      })
+    )
+
+    expect(input?.opcode).toBe(TerminalStreamOpcode.Input)
+    expect(input ? decodeTerminalStreamText(input.payload) : '').toBe('a')
+    expect(resize?.opcode).toBe(TerminalStreamOpcode.Resize)
+    expect(resize && decodeTerminalStreamJson(resize.payload)).toEqual({ cols: 120, rows: 40 })
+  })
+
+  it('round-trips multiplex subscribe and unsubscribe frames', () => {
+    const subscribe = decodeTerminalStreamFrame(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Subscribe,
+        streamId: 0,
+        seq: 1,
+        payload: encodeTerminalStreamJson({
+          streamId: 12,
+          terminal: 'terminal-1',
+          viewport: { cols: 120, rows: 40 }
+        })
+      })
+    )
+    const unsubscribe = decodeTerminalStreamFrame(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Unsubscribe,
+        streamId: 12,
+        seq: 2,
+        payload: new Uint8Array()
+      })
+    )
+
+    expect(subscribe?.opcode).toBe(TerminalStreamOpcode.Subscribe)
+    expect(subscribe && decodeTerminalStreamJson(subscribe.payload)).toMatchObject({
+      streamId: 12,
+      terminal: 'terminal-1'
+    })
+    expect(unsubscribe?.opcode).toBe(TerminalStreamOpcode.Unsubscribe)
+    expect(unsubscribe?.streamId).toBe(12)
+  })
+
   it('rejects unknown frame versions and opcodes', () => {
     const encoded = encodeTerminalStreamFrame({
       opcode: TerminalStreamOpcode.Output,
diff --git a/src/shared/terminal-stream-protocol.ts b/src/shared/terminal-stream-protocol.ts
index daa709f415b..1dab528f97e 100644
--- a/src/shared/terminal-stream-protocol.ts
+++ b/src/shared/terminal-stream-protocol.ts
@@ -8,7 +8,11 @@ export enum TerminalStreamOpcode {
   SnapshotChunk = 3,
   SnapshotEnd = 4,
   Resized = 5,
-  Error = 6
+  Error = 6,
+  Input = 7,
+  Resize = 8,
+  Subscribe = 9,
+  Unsubscribe = 10
 }
 
 export type TerminalStreamFrame = {
@@ -82,6 +86,10 @@ function isTerminalStreamOpcode(value: number): value is TerminalStreamOpcode {
     value === TerminalStreamOpcode.SnapshotChunk ||
     value === TerminalStreamOpcode.SnapshotEnd ||
     value === TerminalStreamOpcode.Resized ||
-    value === TerminalStreamOpcode.Error
+    value === TerminalStreamOpcode.Error ||
+    value === TerminalStreamOpcode.Input ||
+    value === TerminalStreamOpcode.Resize ||
+    value === TerminalStreamOpcode.Subscribe ||
+    value === TerminalStreamOpcode.Unsubscribe
   )
 }
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 7a8b1470a9e..0f9624a10c4 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -435,6 +435,7 @@ export type PersistedOpenFile = {
   worktreeId: string
   language: string
   isPreview?: boolean
+  runtimeEnvironmentId?: string
 }
 
 export type WorkspaceSessionState = {
@@ -1382,6 +1383,9 @@ export type GlobalSettings = {
    *  configuration surface and edge cases (conflicts with existing paths,
    *  cleanup on worktree delete) are still being worked out. */
   experimentalWorktreeSymlinks: boolean
+  /** Active non-local runtime environment for client-routed RPC. `null`
+   *  preserves the current local desktop behavior. */
+  activeRuntimeEnvironmentId?: string | null
   /** GitHub Project mode state — pinned/recent/active project, last selected
    *  view per project. Optional because profiles created before this feature
    *  landed won't have the key; `getDefaultSettings()` hydrates the empty
diff --git a/src/shared/workspace-session-schema.ts b/src/shared/workspace-session-schema.ts
index 40bb2345322..d008f625330 100644
--- a/src/shared/workspace-session-schema.ts
+++ b/src/shared/workspace-session-schema.ts
@@ -125,7 +125,8 @@ const persistedOpenFileSchema = z.object({
   relativePath: z.string(),
   worktreeId: z.string(),
   language: z.string(),
-  isPreview: z.boolean().optional()
+  isPreview: z.boolean().optional(),
+  runtimeEnvironmentId: z.string().optional()
 })
 
 // ─── Browser ────────────────────────────────────────────────────────

From 029c860add20a116649815e73a18dbaf6415e8cf Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 15 May 2026 02:23:18 -0400
Subject: [PATCH 20/82] Add MCP config inspector (#1901)

Co-authored-by: Orca <help@stably.ai>
---
 .../components/settings/McpConfigSection.tsx  | 375 ++++++++++++++++++
 .../components/settings/RepositoryPane.tsx    |  18 +
 src/shared/mcp-config.test.ts                 | 112 ++++++
 src/shared/mcp-config.ts                      | 203 ++++++++++
 4 files changed, 708 insertions(+)
 create mode 100644 src/renderer/src/components/settings/McpConfigSection.tsx
 create mode 100644 src/shared/mcp-config.test.ts
 create mode 100644 src/shared/mcp-config.ts

diff --git a/src/renderer/src/components/settings/McpConfigSection.tsx b/src/renderer/src/components/settings/McpConfigSection.tsx
new file mode 100644
index 00000000000..7c662c30126
--- /dev/null
+++ b/src/renderer/src/components/settings/McpConfigSection.tsx
@@ -0,0 +1,375 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { AlertCircle, CheckCircle2, FileCode2, LoaderCircle, Plus, RefreshCw } from 'lucide-react'
+import { toast } from 'sonner'
+import type { Repo, Worktree } from '../../../../shared/types'
+import { getRepoIdFromWorktreeId } from '../../../../shared/worktree-id'
+import {
+  inspectMcpConfigContent,
+  MCP_CONFIG_CANDIDATES,
+  MCP_STARTER_CONFIG,
+  type McpConfigInspection
+} from '../../../../shared/mcp-config'
+import { useAppStore } from '../../store'
+import { joinPath } from '../../lib/path'
+import { extractIpcErrorMessage } from '../../lib/ipc-error'
+import { Button } from '../ui/button'
+
+type LoadedInspection = McpConfigInspection & {
+  absolutePath: string
+  readError?: string
+}
+
+type McpConfigSectionProps = {
+  repo: Repo
+}
+
+const EMPTY_WORKTREES: Worktree[] = []
+
+function isMissingFileError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  return /ENOENT|no such file|not found/i.test(message)
+}
+
+function isNoFilesystemProviderMessage(message: string | undefined): boolean {
+  return message ? /no filesystem provider/i.test(message) : false
+}
+
+function countServers(configs: LoadedInspection[]): number {
+  return configs.reduce((sum, config) => sum + config.servers.length, 0)
+}
+
+function statusLabel(config: LoadedInspection): string {
+  if (config.readError) {
+    return 'Unreadable'
+  }
+  if (config.status === 'missing') {
+    return 'Not found'
+  }
+  if (config.status === 'invalid') {
+    return 'Invalid JSON'
+  }
+  if (config.servers.length === 0) {
+    return 'No servers'
+  }
+  return `${config.servers.length} server${config.servers.length === 1 ? '' : 's'}`
+}
+
+function statusClassName(config: LoadedInspection): string {
+  if (config.readError || config.status === 'invalid') {
+    return 'border-destructive/30 bg-destructive/10 text-destructive'
+  }
+  if (config.status === 'valid' && config.servers.length > 0) {
+    return 'border-border/60 bg-background text-foreground'
+  }
+  return 'border-border/60 bg-muted/60 text-muted-foreground'
+}
+
+function serverDetailLabel(server: LoadedInspection['servers'][number]): string {
+  if (server.transport === 'http') {
+    return server.url ?? 'HTTP server'
+  }
+  if (server.transport === 'stdio') {
+    return server.command ?? 'stdio server'
+  }
+  return server.issue ?? 'Invalid server'
+}
+
+export function McpConfigSection({ repo }: McpConfigSectionProps): React.JSX.Element {
+  const openFile = useAppStore((state) => state.openFile)
+  const setActiveView = useAppStore((state) => state.setActiveView)
+  const setActiveWorktree = useAppStore((state) => state.setActiveWorktree)
+  const ensureWorktreeRootGroup = useAppStore((state) => state.ensureWorktreeRootGroup)
+  const activeWorktreeId = useAppStore((state) => state.activeWorktreeId)
+  const worktreesForRepo = useAppStore((state) => state.worktreesByRepo[repo.id] ?? EMPTY_WORKTREES)
+  const [configs, setConfigs] = useState<LoadedInspection[]>([])
+  const [loading, setLoading] = useState(true)
+  const [createConfirm, setCreateConfirm] = useState(false)
+
+  const connectionId = repo.connectionId ?? undefined
+  const targetWorktree = useMemo(() => {
+    if (activeWorktreeId && getRepoIdFromWorktreeId(activeWorktreeId) === repo.id) {
+      return (
+        worktreesForRepo.find((worktree) => worktree.id === activeWorktreeId) ?? {
+          id: activeWorktreeId,
+          path: repo.path
+        }
+      )
+    }
+    return (
+      worktreesForRepo.find((worktree) => worktree.isMainWorktree) ??
+      worktreesForRepo.find((worktree) => worktree.path === repo.path) ??
+      worktreesForRepo[0] ?? { id: `${repo.id}::${repo.path}`, path: repo.path }
+    )
+  }, [activeWorktreeId, repo.id, repo.path, worktreesForRepo])
+  const targetWorktreeId = targetWorktree.id
+  const targetRootPath = targetWorktree.path
+  const detectedCount = useMemo(() => configs.filter((config) => config.exists).length, [configs])
+  const remoteFilesystemUnavailable = useMemo(
+    () =>
+      Boolean(connectionId) &&
+      configs.length > 0 &&
+      configs.every((config) => isNoFilesystemProviderMessage(config.readError)),
+    [configs, connectionId]
+  )
+  const visibleConfigs = useMemo(
+    () =>
+      remoteFilesystemUnavailable
+        ? []
+        : configs.filter(
+            (config) => config.exists || config.status === 'invalid' || config.readError
+          ),
+    [configs, remoteFilesystemUnavailable]
+  )
+  const missingConfigs = useMemo(
+    () =>
+      configs.filter(
+        (config) => !config.exists && config.status === 'missing' && !config.readError
+      ),
+    [configs]
+  )
+  const serverCount = useMemo(() => countServers(configs), [configs])
+  const canCreateStarter = detectedCount === 0 && !remoteFilesystemUnavailable
+
+  const loadConfigs = useCallback(async (): Promise<void> => {
+    setLoading(true)
+    const next = await Promise.all(
+      MCP_CONFIG_CANDIDATES.map(async (candidate): Promise<LoadedInspection> => {
+        const absolutePath = joinPath(targetRootPath, candidate.relativePath)
+        try {
+          const result = await window.api.fs.readFile({ filePath: absolutePath, connectionId })
+          const inspection = inspectMcpConfigContent(
+            candidate,
+            result.isBinary ? '' : result.content
+          )
+          return { ...inspection, absolutePath }
+        } catch (error) {
+          if (isMissingFileError(error)) {
+            return { ...inspectMcpConfigContent(candidate, null), absolutePath }
+          }
+          return {
+            ...inspectMcpConfigContent(candidate, null),
+            exists: false,
+            status: 'invalid',
+            absolutePath,
+            readError: extractIpcErrorMessage(error, 'Unable to read config file.')
+          }
+        }
+      })
+    )
+    setConfigs(next)
+    setLoading(false)
+  }, [connectionId, targetRootPath])
+
+  useEffect(() => {
+    void loadConfigs()
+  }, [loadConfigs])
+
+  const handleOpen = (config: LoadedInspection): void => {
+    setActiveWorktree(targetWorktreeId)
+    const targetGroupId = ensureWorktreeRootGroup(targetWorktreeId)
+    openFile(
+      {
+        filePath: config.absolutePath,
+        relativePath: config.candidate.relativePath,
+        worktreeId: targetWorktreeId,
+        language: 'json',
+        mode: 'edit'
+      },
+      { targetGroupId }
+    )
+    setActiveView('terminal')
+  }
+
+  const handleCreateStarter = async (): Promise<void> => {
+    if (!createConfirm) {
+      setCreateConfirm(true)
+      window.setTimeout(() => setCreateConfirm(false), 3000)
+      return
+    }
+
+    const target = joinPath(targetRootPath, '.mcp.json')
+    try {
+      // Why: v1 only creates the root workspace config so we do not need to
+      // guess per-agent directory layouts or mutate agent-specific files.
+      await window.api.fs.writeFile({ filePath: target, content: MCP_STARTER_CONFIG, connectionId })
+      setCreateConfirm(false)
+      await loadConfigs()
+      setActiveWorktree(targetWorktreeId)
+      const targetGroupId = ensureWorktreeRootGroup(targetWorktreeId)
+      openFile(
+        {
+          filePath: target,
+          relativePath: '.mcp.json',
+          worktreeId: targetWorktreeId,
+          language: 'json',
+          mode: 'edit'
+        },
+        { targetGroupId }
+      )
+      setActiveView('terminal')
+      toast.success('MCP config created', { description: '.mcp.json' })
+    } catch (error) {
+      toast.error(extractIpcErrorMessage(error, 'Failed to create MCP config.'))
+    }
+  }
+
+  return (
+    <section className="space-y-4">
+      <div className="flex items-start justify-between gap-4">
+        <div className="space-y-1">
+          <h3 className="text-sm font-semibold">MCP Configs</h3>
+          <p className="text-xs text-muted-foreground">
+            Inspect MCP server definitions that agents can use while working in this repo.
+          </p>
+          {repo.connectionId ? (
+            <p className="text-xs text-muted-foreground">
+              SSH repos are read through the remote filesystem. Starter creation is limited to the
+              workspace root config.
+            </p>
+          ) : null}
+        </div>
+        <div className="flex shrink-0 items-center gap-2">
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            onClick={() => void loadConfigs()}
+            aria-label="Refresh MCP configs"
+          >
+            {loading ? (
+              <LoaderCircle className="size-3.5 animate-spin" />
+            ) : (
+              <RefreshCw className="size-3.5" />
+            )}
+          </Button>
+          {canCreateStarter ? (
+            <Button
+              variant={createConfirm ? 'default' : 'outline'}
+              size="sm"
+              className="gap-1.5"
+              onClick={() => void handleCreateStarter()}
+            >
+              <Plus className="size-3.5" />
+              {createConfirm ? 'Create empty config' : 'Add MCP config'}
+            </Button>
+          ) : null}
+        </div>
+      </div>
+
+      <div className="rounded-md border border-border/50 bg-muted/20">
+        <div className="flex items-center justify-between border-b border-border/50 px-3 py-2 text-xs text-muted-foreground">
+          <span>
+            {detectedCount} detected · {serverCount} server{serverCount === 1 ? '' : 's'}
+          </span>
+          {loading ? <LoaderCircle className="size-3.5 animate-spin" /> : null}
+        </div>
+        <div>
+          {visibleConfigs.length === 0 ? (
+            <div className="flex items-start gap-2 px-3 py-2.5 text-xs text-muted-foreground">
+              {remoteFilesystemUnavailable ? (
+                <AlertCircle className="mt-0.5 size-3.5 shrink-0" />
+              ) : (
+                <FileCode2 className="mt-0.5 size-3.5 shrink-0" />
+              )}
+              {remoteFilesystemUnavailable ? (
+                <span>Connect this SSH repo to inspect or add MCP configs.</span>
+              ) : (
+                <span>
+                  No MCP config found. Add an empty workspace config when you want this repo to
+                  define its own MCP servers.
+                </span>
+              )}
+            </div>
+          ) : (
+            <div className="divide-y divide-border/50">
+              {visibleConfigs.map((config) => (
+                <div key={config.candidate.relativePath} className="space-y-2 px-3 py-2.5">
+                  <div className="flex items-center gap-2">
+                    {config.status === 'valid' && !config.readError ? (
+                      <CheckCircle2 className="size-3.5 shrink-0 text-muted-foreground" />
+                    ) : (
+                      <AlertCircle className="size-3.5 shrink-0 text-destructive" />
+                    )}
+                    <div className="min-w-0 flex-1">
+                      <div className="flex min-w-0 items-center gap-2">
+                        <p className="truncate text-sm font-medium">{config.candidate.label}</p>
+                        <p className="truncate font-mono text-[11px] text-muted-foreground">
+                          {config.candidate.relativePath}
+                        </p>
+                      </div>
+                    </div>
+                    <span
+                      className={`shrink-0 rounded-full border px-1.5 py-0.5 text-[10px] font-medium ${statusClassName(config)}`}
+                    >
+                      {statusLabel(config)}
+                    </span>
+                    {config.exists ? (
+                      <Button variant="outline" size="xs" onClick={() => handleOpen(config)}>
+                        Open
+                      </Button>
+                    ) : null}
+                  </div>
+
+                  {config.error || config.readError ? (
+                    <p className="pl-5 text-xs text-destructive">
+                      {config.readError ?? config.error}
+                    </p>
+                  ) : null}
+
+                  {config.servers.length > 0 ? (
+                    <div className="grid gap-1.5 pl-5">
+                      {config.servers.map((server) => (
+                        <div
+                          key={server.name}
+                          className="grid grid-cols-[minmax(0,1fr)_auto] gap-2 rounded-md border border-border/40 bg-background/50 px-2.5 py-1.5"
+                        >
+                          <div className="min-w-0">
+                            <div className="flex items-center gap-1.5">
+                              <span className="truncate text-xs font-medium">{server.name}</span>
+                              <span className="rounded-full bg-muted px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-wider text-muted-foreground">
+                                {server.transport}
+                              </span>
+                            </div>
+                            <p className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
+                              {serverDetailLabel(server)}
+                            </p>
+                            {server.env && Object.keys(server.env).length > 0 ? (
+                              <p className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
+                                env:{' '}
+                                {Object.entries(server.env)
+                                  .map(([key, value]) => `${key}=${value}`)
+                                  .join(', ')}
+                              </p>
+                            ) : null}
+                          </div>
+                          <span className="self-start text-[11px] text-muted-foreground">
+                            {server.status}
+                          </span>
+                        </div>
+                      ))}
+                    </div>
+                  ) : null}
+                </div>
+              ))}
+            </div>
+          )}
+
+          {missingConfigs.length > 0 && !remoteFilesystemUnavailable ? (
+            <div className="space-y-1.5 border-t border-border/50 px-3 py-2">
+              <p className="text-[11px] text-muted-foreground">Checked</p>
+              <div className="flex flex-wrap gap-1.5">
+                {missingConfigs.map((config) => (
+                  <span
+                    key={config.candidate.relativePath}
+                    className="rounded-md border border-border/50 bg-background/40 px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground"
+                  >
+                    {config.candidate.relativePath}
+                  </span>
+                ))}
+              </div>
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </section>
+  )
+}
diff --git a/src/renderer/src/components/settings/RepositoryPane.tsx b/src/renderer/src/components/settings/RepositoryPane.tsx
index 8f335364bb0..297963ced99 100644
--- a/src/renderer/src/components/settings/RepositoryPane.tsx
+++ b/src/renderer/src/components/settings/RepositoryPane.tsx
@@ -10,6 +10,7 @@ import { Trash2 } from 'lucide-react'
 import { DEFAULT_REPO_HOOK_SETTINGS } from './SettingsConstants'
 import { BaseRefPicker } from './BaseRefPicker'
 import { RepositoryHooksSection } from './RepositoryHooksSection'
+import { McpConfigSection } from './McpConfigSection'
 import { WorktreeSymlinksSection } from './WorktreeSymlinksSection'
 import { SparsePresetSettingsSection } from './SparsePresetSettingsSection'
 import { SearchableSetting } from './SearchableSetting'
@@ -83,6 +84,19 @@ export function getRepositoryPaneSearchEntries(repo: Repo): SettingsSearchEntry[
               'node_modules'
             ]
           },
+          {
+            title: 'MCP Configs',
+            description: 'Inspect repo-level MCP server config files.',
+            keywords: [
+              repo.displayName,
+              'mcp',
+              'model context protocol',
+              '.mcp.json',
+              '.cursor/mcp.json',
+              '.claude.json',
+              '.claude/mcp.json'
+            ]
+          },
           {
             title: 'orca.yaml hooks',
             description: 'Shared setup and archive hook commands for this repository.',
@@ -206,6 +220,7 @@ export function RepositoryPane({
       'Custom GitHub Issue Command'
     ].includes(entry.title)
   )
+  const mcpEntries = allEntries.filter((entry) => entry.title === 'MCP Configs')
   const symlinkEntries = allEntries.filter((entry) => entry.title === 'Worktree Symlinks')
 
   const visibleSections = [
@@ -313,6 +328,9 @@ export function RepositoryPane({
     !isFolder && matchesSettingsSearch(searchQuery, sparsePresetEntries) ? (
       <SparsePresetSettingsSection key="sparse-presets" repoId={repo.id} />
     ) : null,
+    !isFolder && matchesSettingsSearch(searchQuery, mcpEntries) ? (
+      <McpConfigSection key="mcp-configs" repo={repo} />
+    ) : null,
     !isFolder && matchesSettingsSearch(searchQuery, hooksEntries) ? (
       <RepositoryHooksSection
         key="hooks"
diff --git a/src/shared/mcp-config.test.ts b/src/shared/mcp-config.test.ts
new file mode 100644
index 00000000000..f12ba2df21b
--- /dev/null
+++ b/src/shared/mcp-config.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+import {
+  inspectMcpConfigContent,
+  maskMcpEnv,
+  MCP_CONFIG_CANDIDATES,
+  MCP_STARTER_CONFIG
+} from './mcp-config'
+
+describe('mcp-config', () => {
+  const workspaceCandidate = MCP_CONFIG_CANDIDATES[0]
+
+  it('reports missing configs', () => {
+    expect(inspectMcpConfigContent(workspaceCandidate, null)).toMatchObject({
+      exists: false,
+      status: 'missing',
+      servers: []
+    })
+  })
+
+  it('reports invalid JSON without exposing file contents', () => {
+    const result = inspectMcpConfigContent(workspaceCandidate, '{')
+    expect(result.status).toBe('invalid')
+    expect(result.error).toContain('JSON')
+    expect(result.servers).toEqual([])
+  })
+
+  it('summarizes stdio, http, disabled, and invalid servers', () => {
+    const result = inspectMcpConfigContent(
+      workspaceCandidate,
+      JSON.stringify({
+        mcpServers: {
+          filesystem: {
+            command: 'npx',
+            args: ['-y', '@modelcontextprotocol/server-filesystem'],
+            env: { NODE_ENV: 'production', API_TOKEN: 'secret-token' }
+          },
+          docs: { type: 'http', url: 'https://example.com/mcp' },
+          old: { command: 'node', enabled: false },
+          broken: { args: ['missing-command'] }
+        }
+      })
+    )
+
+    expect(result.status).toBe('valid')
+    expect(result.servers).toEqual([
+      {
+        name: 'filesystem',
+        transport: 'stdio',
+        status: 'enabled',
+        command: 'npx',
+        env: { NODE_ENV: 'production', API_TOKEN: '••••••••' }
+      },
+      {
+        name: 'docs',
+        transport: 'http',
+        status: 'enabled',
+        url: 'https://example.com/mcp'
+      },
+      {
+        name: 'old',
+        transport: 'stdio',
+        status: 'disabled',
+        command: 'node'
+      },
+      {
+        name: 'broken',
+        transport: 'unknown',
+        status: 'invalid',
+        issue: 'Missing command or URL.'
+      }
+    ])
+  })
+
+  it('supports agent-specific command and URL shapes from common adapters', () => {
+    const result = inspectMcpConfigContent(
+      workspaceCandidate,
+      JSON.stringify({
+        mcpServers: {
+          opencodeLocal: { type: 'local', command: ['uvx', 'server'] },
+          geminiRemote: { httpUrl: 'https://example.com/sse' }
+        }
+      })
+    )
+
+    expect(result.servers).toMatchObject([
+      { name: 'opencodeLocal', transport: 'stdio', command: 'uvx' },
+      { name: 'geminiRemote', transport: 'http', url: 'https://example.com/sse' }
+    ])
+  })
+
+  it('masks env values that look sensitive by key or value', () => {
+    expect(
+      maskMcpEnv({
+        NORMAL: 'visible',
+        PASSWORD: 'hunter2',
+        MAYBE: 'sk-abc123456789xyz'
+      })
+    ).toEqual({
+      NORMAL: 'visible',
+      PASSWORD: '••••••••',
+      MAYBE: '••••••••'
+    })
+  })
+
+  it('keeps starter config valid and empty', () => {
+    expect(inspectMcpConfigContent(workspaceCandidate, MCP_STARTER_CONFIG)).toMatchObject({
+      exists: true,
+      status: 'valid',
+      servers: []
+    })
+  })
+})
diff --git a/src/shared/mcp-config.ts b/src/shared/mcp-config.ts
new file mode 100644
index 00000000000..5a81ac2b267
--- /dev/null
+++ b/src/shared/mcp-config.ts
@@ -0,0 +1,203 @@
+export type McpConfigFormat = 'workspace' | 'cursor' | 'claude'
+
+export type McpConfigCandidate = {
+  format: McpConfigFormat
+  label: string
+  relativePath: string
+  serversPath: string[]
+}
+
+export type McpServerTransport = 'stdio' | 'http' | 'unknown'
+export type McpServerStatus = 'enabled' | 'disabled' | 'invalid'
+
+export type McpServerSummary = {
+  name: string
+  transport: McpServerTransport
+  status: McpServerStatus
+  command?: string
+  url?: string
+  env?: Record<string, string>
+  issue?: string
+}
+
+export type McpConfigInspection = {
+  candidate: McpConfigCandidate
+  exists: boolean
+  status: 'missing' | 'valid' | 'invalid'
+  servers: McpServerSummary[]
+  error?: string
+}
+
+export const MCP_CONFIG_CANDIDATES: McpConfigCandidate[] = [
+  {
+    format: 'workspace',
+    label: 'Workspace',
+    relativePath: '.mcp.json',
+    serversPath: ['mcpServers']
+  },
+  {
+    format: 'cursor',
+    label: 'Cursor',
+    relativePath: '.cursor/mcp.json',
+    serversPath: ['mcpServers']
+  },
+  {
+    format: 'claude',
+    label: 'Claude',
+    relativePath: '.claude.json',
+    serversPath: ['mcpServers']
+  },
+  {
+    format: 'claude',
+    label: 'Claude workspace',
+    relativePath: '.claude/mcp.json',
+    serversPath: ['mcpServers']
+  }
+]
+
+export const MCP_STARTER_CONFIG = `{
+  "mcpServers": {}
+}
+`
+
+const SENSITIVE_ENV_KEY_PATTERN =
+  /(api[_-]?key|auth|bearer|cookie|credential|password|private[_-]?key|secret|session|token)/i
+const SENSITIVE_ENV_VALUE_PATTERN =
+  /(sk-[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9_]{12,}|xox[baprs]-[A-Za-z0-9-]{12,})/
+
+export function inspectMcpConfigContent(
+  candidate: McpConfigCandidate,
+  content: string | null
+): McpConfigInspection {
+  if (content === null) {
+    return { candidate, exists: false, status: 'missing', servers: [] }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(content)
+  } catch (error) {
+    return {
+      candidate,
+      exists: true,
+      status: 'invalid',
+      servers: [],
+      error: error instanceof Error ? error.message : 'Invalid JSON'
+    }
+  }
+
+  const rawServers = extractObjectAtPath(parsed, candidate.serversPath)
+  if (!rawServers) {
+    return { candidate, exists: true, status: 'valid', servers: [] }
+  }
+
+  return {
+    candidate,
+    exists: true,
+    status: 'valid',
+    servers: Object.entries(rawServers).map(([name, entry]) => summarizeMcpServer(name, entry))
+  }
+}
+
+export function maskMcpEnv(env: unknown): Record<string, string> | undefined {
+  if (!env || typeof env !== 'object' || Array.isArray(env)) {
+    return undefined
+  }
+
+  const masked: Record<string, string> = {}
+  for (const [key, rawValue] of Object.entries(env)) {
+    const value = typeof rawValue === 'string' ? rawValue : String(rawValue)
+    masked[key] =
+      SENSITIVE_ENV_KEY_PATTERN.test(key) || SENSITIVE_ENV_VALUE_PATTERN.test(value)
+        ? '••••••••'
+        : value
+  }
+  return masked
+}
+
+function extractObjectAtPath(
+  value: unknown,
+  pathSegments: string[]
+): Record<string, unknown> | null {
+  let current = value
+  for (const segment of pathSegments) {
+    if (!current || typeof current !== 'object' || Array.isArray(current)) {
+      return null
+    }
+    current = (current as Record<string, unknown>)[segment]
+  }
+  return current && typeof current === 'object' && !Array.isArray(current)
+    ? (current as Record<string, unknown>)
+    : null
+}
+
+function summarizeMcpServer(name: string, entry: unknown): McpServerSummary {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return {
+      name,
+      transport: 'unknown',
+      status: 'invalid',
+      issue: 'Server entry must be an object.'
+    }
+  }
+
+  const raw = entry as Record<string, unknown>
+  const command = readCommand(raw)
+  const url = readUrl(raw)
+  const transport = resolveTransport(raw, command, url)
+  const enabled = raw.enabled !== false && raw.disabled !== true
+  const env = maskMcpEnv(raw.env)
+
+  if (transport === 'unknown') {
+    return {
+      name,
+      transport,
+      status: 'invalid',
+      env,
+      issue: 'Missing command or URL.'
+    }
+  }
+
+  return {
+    name,
+    transport,
+    status: enabled ? 'enabled' : 'disabled',
+    command,
+    url,
+    env
+  }
+}
+
+function readCommand(raw: Record<string, unknown>): string | undefined {
+  if (typeof raw.command === 'string') {
+    return raw.command
+  }
+  if (Array.isArray(raw.command) && typeof raw.command[0] === 'string') {
+    return raw.command[0]
+  }
+  return undefined
+}
+
+function readUrl(raw: Record<string, unknown>): string | undefined {
+  if (typeof raw.url === 'string') {
+    return raw.url
+  }
+  if (typeof raw.httpUrl === 'string') {
+    return raw.httpUrl
+  }
+  return undefined
+}
+
+function resolveTransport(
+  raw: Record<string, unknown>,
+  command: string | undefined,
+  url: string | undefined
+): McpServerTransport {
+  if (raw.type === 'http' || raw.type === 'remote' || url) {
+    return 'http'
+  }
+  if (raw.type === 'local' || command) {
+    return 'stdio'
+  }
+  return 'unknown'
+}

From dc83da70360e85d3554271ba8721170345d986de Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 14 May 2026 23:26:12 -0700
Subject: [PATCH 21/82] Add workspace status board (#1902)

* Add workspace status board

* Position workspace board beside sidebar

* Simplify workspace drag target highlighting

* Tune workspace board animation and opacity

* Add workspace status visual customization

* Improve workspace board interactions

* Polish compact workspace cards

* Fix workspace board drawer focus

* Limit workspace drop listeners

* Toggle workspace board from header

* Update worktree status merge test
---
 src/main/ipc/worktree-logic.test.ts           |   9 +-
 src/main/ipc/worktree-logic.ts                |   2 +
 src/main/persistence.ts                       |  39 +-
 src/renderer/src/assets/main.css              |  35 ++
 .../src/components/sidebar/SidebarHeader.tsx  | 258 ++++++-----
 .../sidebar/WorkspaceKanbanCard.tsx           | 145 ++++++
 .../sidebar/WorkspaceKanbanDrawer.tsx         | 430 ++++++++++++++++++
 .../sidebar/WorkspaceKanbanSettingsMenu.tsx   | 156 +++++++
 .../WorkspaceStatusAppearancePopover.tsx      | 106 +++++
 .../src/components/sidebar/WorktreeCard.tsx   | 164 +------
 .../sidebar/WorktreeContextMenu.tsx           |  56 +++
 .../src/components/sidebar/WorktreeList.tsx   | 219 ++++++++-
 .../sidebar/use-workspace-status-drop.ts      |  81 ++++
 .../sidebar/use-worktree-activity-status.ts   |  93 ++++
 .../components/sidebar/workspace-status.ts    | 232 ++++++++++
 .../sidebar/worktree-list-groups.test.ts      |  76 +++-
 .../sidebar/worktree-list-groups.ts           | 128 +++---
 src/renderer/src/components/ui/sheet.tsx      |   6 +-
 src/renderer/src/store/slices/ui.test.ts      |  18 +
 src/renderer/src/store/slices/ui.ts           |  37 ++
 src/renderer/src/store/slices/worktrees.ts    |   1 +
 src/shared/constants.ts                       |   4 +
 src/shared/types.ts                           |  15 +
 src/shared/workspace-statuses.ts              | 201 ++++++++
 24 files changed, 2160 insertions(+), 351 deletions(-)
 create mode 100644 src/renderer/src/components/sidebar/WorkspaceKanbanCard.tsx
 create mode 100644 src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx
 create mode 100644 src/renderer/src/components/sidebar/WorkspaceKanbanSettingsMenu.tsx
 create mode 100644 src/renderer/src/components/sidebar/WorkspaceStatusAppearancePopover.tsx
 create mode 100644 src/renderer/src/components/sidebar/use-workspace-status-drop.ts
 create mode 100644 src/renderer/src/components/sidebar/use-worktree-activity-status.ts
 create mode 100644 src/renderer/src/components/sidebar/workspace-status.ts
 create mode 100644 src/shared/workspace-statuses.ts

diff --git a/src/main/ipc/worktree-logic.test.ts b/src/main/ipc/worktree-logic.test.ts
index 36927838fca..77073c29544 100644
--- a/src/main/ipc/worktree-logic.test.ts
+++ b/src/main/ipc/worktree-logic.test.ts
@@ -221,7 +221,9 @@ describe('mergeWorktree', () => {
       isUnread: true,
       isPinned: true,
       sortOrder: 5,
-      lastActivityAt: 1000
+      lastActivityAt: 1000,
+      workspaceStatus: 'in-review',
+      diffComments: []
     }
     const result = mergeWorktree('repo1', baseGit, meta)
     expect(result).toEqual({
@@ -243,7 +245,9 @@ describe('mergeWorktree', () => {
       isUnread: true,
       isPinned: true,
       sortOrder: 5,
-      lastActivityAt: 1000
+      lastActivityAt: 1000,
+      workspaceStatus: 'in-review',
+      diffComments: []
     })
   })
 
@@ -258,6 +262,7 @@ describe('mergeWorktree', () => {
     expect(result.isPinned).toBe(false)
     expect(result.sortOrder).toBe(0)
     expect(result.lastActivityAt).toBe(0)
+    expect(result.workspaceStatus).toBe('in-progress')
   })
 
   it('strips refs/heads/ prefix from branch for display name', () => {
diff --git a/src/main/ipc/worktree-logic.ts b/src/main/ipc/worktree-logic.ts
index fe2c086fc61..266718fb96f 100644
--- a/src/main/ipc/worktree-logic.ts
+++ b/src/main/ipc/worktree-logic.ts
@@ -1,6 +1,7 @@
 import { basename, join, resolve, relative, isAbsolute, posix, win32 } from 'path'
 import type { GitWorktreeInfo, Worktree, WorktreeMeta } from '../../shared/types'
 import { splitWorktreeId } from '../../shared/worktree-id'
+import { DEFAULT_WORKSPACE_STATUS_ID } from '../../shared/workspace-statuses'
 import { getWslHome, parseWslPath } from '../wsl'
 
 /**
@@ -205,6 +206,7 @@ export function mergeWorktree(
       : {}),
     ...(meta?.baseRef !== undefined ? { baseRef: meta.baseRef } : {}),
     ...(meta?.pushTarget !== undefined ? { pushTarget: meta.pushTarget } : {}),
+    workspaceStatus: meta?.workspaceStatus ?? DEFAULT_WORKSPACE_STATUS_ID,
     // Why: diff comments are persisted on WorktreeMeta (see `WorktreeMeta` in
     // shared/types) and forwarded verbatim so the renderer store mirrors
     // on-disk state. `undefined` here means the worktree has no comments yet.
diff --git a/src/main/persistence.ts b/src/main/persistence.ts
index 2d09b3c9086..28e2804a31b 100644
--- a/src/main/persistence.ts
+++ b/src/main/persistence.ts
@@ -57,6 +57,12 @@ import { pruneLocalTerminalScrollbackBuffers } from '../shared/workspace-session
 import { pruneWorkspaceSessionBrowserHistory } from '../shared/workspace-session-browser-history'
 import { getRepoIdFromWorktreeId } from '../shared/worktree-id'
 import { normalizeTerminalQuickCommands } from '../shared/terminal-quick-commands'
+import {
+  DEFAULT_WORKSPACE_STATUS_ID,
+  clampWorkspaceBoardOpacity,
+  normalizeWorkspaceBoardCompact,
+  normalizeWorkspaceStatuses
+} from '../shared/workspace-statuses'
 
 function encrypt(plaintext: string): string {
   if (!plaintext || !safeStorage.isEncryptionAvailable()) {
@@ -132,6 +138,16 @@ function backupPath(dataFile: string, index: number): string {
   return `${dataFile}.bak.${index}`
 }
 
+function normalizeGroupBy(groupBy: unknown): PersistedState['ui']['groupBy'] {
+  if (groupBy === 'none' || groupBy === 'repo' || groupBy === 'pr-status') {
+    return groupBy
+  }
+  if (groupBy === 'workspace-status') {
+    return 'none'
+  }
+  return getDefaultUIState().groupBy
+}
+
 function normalizeSortBy(sortBy: unknown): 'name' | 'smart' | 'recent' | 'repo' {
   if (sortBy === 'smart' || sortBy === 'recent' || sortBy === 'repo' || sortBy === 'name') {
     return sortBy
@@ -1195,7 +1211,11 @@ export class Store {
     return {
       ...getDefaultUIState(),
       ...this.state.ui,
-      sortBy: normalizeSortBy(this.state.ui?.sortBy)
+      groupBy: normalizeGroupBy(this.state.ui?.groupBy),
+      sortBy: normalizeSortBy(this.state.ui?.sortBy),
+      workspaceStatuses: normalizeWorkspaceStatuses(this.state.ui?.workspaceStatuses),
+      workspaceBoardOpacity: clampWorkspaceBoardOpacity(this.state.ui?.workspaceBoardOpacity),
+      workspaceBoardCompact: normalizeWorkspaceBoardCompact(this.state.ui?.workspaceBoardCompact)
     }
   }
 
@@ -1203,9 +1223,21 @@ export class Store {
     this.state.ui = {
       ...this.state.ui,
       ...updates,
+      groupBy: updates.groupBy
+        ? normalizeGroupBy(updates.groupBy)
+        : normalizeGroupBy(this.state.ui?.groupBy),
       sortBy: updates.sortBy
         ? normalizeSortBy(updates.sortBy)
-        : normalizeSortBy(this.state.ui?.sortBy)
+        : normalizeSortBy(this.state.ui?.sortBy),
+      workspaceStatuses: normalizeWorkspaceStatuses(
+        updates.workspaceStatuses ?? this.state.ui?.workspaceStatuses
+      ),
+      workspaceBoardOpacity: clampWorkspaceBoardOpacity(
+        updates.workspaceBoardOpacity ?? this.state.ui?.workspaceBoardOpacity
+      ),
+      workspaceBoardCompact: normalizeWorkspaceBoardCompact(
+        updates.workspaceBoardCompact ?? this.state.ui?.workspaceBoardCompact
+      )
     }
     this.scheduleSave()
   }
@@ -1706,6 +1738,7 @@ function getDefaultWorktreeMeta(): WorktreeMeta {
     isUnread: false,
     isPinned: false,
     sortOrder: Date.now(),
-    lastActivityAt: 0
+    lastActivityAt: 0,
+    workspaceStatus: DEFAULT_WORKSPACE_STATUS_ID
   }
 }
diff --git a/src/renderer/src/assets/main.css b/src/renderer/src/assets/main.css
index 8504cdd746e..1e206c0f92c 100644
--- a/src/renderer/src/assets/main.css
+++ b/src/renderer/src/assets/main.css
@@ -728,6 +728,41 @@
   overflow: hidden;
 }
 
+/* Why: the workspace board is offset to the sidebar edge. The generic left
+   sheet translates by its full width, which makes an offset board fly in from
+   far offscreen; this reveals it from the sidebar boundary instead. */
+.workspace-kanban-sheet-content[data-state='open'] {
+  animation-name: workspace-kanban-sheet-in;
+  animation-duration: 300ms;
+  animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.workspace-kanban-sheet-content[data-state='closed'] {
+  animation-name: workspace-kanban-sheet-out;
+  animation-duration: 200ms;
+  animation-timing-function: cubic-bezier(0.7, 0, 0.84, 0);
+}
+
+@keyframes workspace-kanban-sheet-in {
+  from {
+    clip-path: inset(0 100% 0 0);
+  }
+
+  to {
+    clip-path: inset(0 0 0 0);
+  }
+}
+
+@keyframes workspace-kanban-sheet-out {
+  from {
+    clip-path: inset(0 0 0 0);
+  }
+
+  to {
+    clip-path: inset(0 100% 0 0);
+  }
+}
+
 .sidebar-header {
   padding: 12px 16px 8px;
   font-size: 11px;
diff --git a/src/renderer/src/components/sidebar/SidebarHeader.tsx b/src/renderer/src/components/sidebar/SidebarHeader.tsx
index e84bde04b85..8c1d4e7d320 100644
--- a/src/renderer/src/components/sidebar/SidebarHeader.tsx
+++ b/src/renderer/src/components/sidebar/SidebarHeader.tsx
@@ -1,5 +1,5 @@
-import React from 'react'
-import { Plus, SlidersHorizontal } from 'lucide-react'
+import React, { useState } from 'react'
+import { Kanban, Plus, SlidersHorizontal } from 'lucide-react'
 import { useAppStore } from '@/store'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipTrigger, TooltipContent } from '@/components/ui/tooltip'
@@ -17,10 +17,11 @@ import {
 } from '@/components/ui/dropdown-menu'
 import type { WorktreeCardProperty } from '../../../../shared/types'
 import SidebarFilter from './SidebarFilter'
+import WorkspaceKanbanDrawer from './WorkspaceKanbanDrawer'
 
 const GROUP_BY_OPTIONS = [
-  { id: 'none', label: 'All' },
-  { id: 'pr-status', label: 'PR Status' },
+  { id: 'none', label: 'Status' },
+  { id: 'pr-status', label: 'PR' },
   { id: 'repo', label: 'Repo' }
 ] as const
 
@@ -52,6 +53,7 @@ const isMac = navigator.userAgent.includes('Mac')
 const newWorktreeShortcutLabel = isMac ? '⌘N' : 'Ctrl+N'
 
 const SidebarHeader = React.memo(function SidebarHeader() {
+  const [workspaceBoardOpen, setWorkspaceBoardOpen] = useState(false)
   const openModal = useAppStore((s) => s.openModal)
   const repos = useAppStore((s) => s.repos)
   const canCreateWorktree = repos.some((repo) => isGitRepoKind(repo))
@@ -63,129 +65,151 @@ const SidebarHeader = React.memo(function SidebarHeader() {
   const groupBy = useAppStore((s) => s.groupBy)
   const setGroupBy = useAppStore((s) => s.setGroupBy)
   return (
-    <div className="flex h-8 items-center justify-between px-2 gap-2">
-      <span className="px-2 text-[10.5px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/80 select-none">
-        Workspaces
-      </span>
-      <div className="flex items-center gap-1.5 shrink-0">
-        <SidebarFilter />
-        <DropdownMenu>
+    <>
+      <div className="flex h-8 items-center justify-between px-2 gap-2">
+        <div className="flex min-w-0 items-center gap-1">
+          <span className="px-2 text-[10.5px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/80 select-none">
+            Workspaces
+          </span>
           <Tooltip>
             <TooltipTrigger asChild>
-              <DropdownMenuTrigger asChild>
-                <Button
-                  variant="ghost"
-                  size="icon-xs"
-                  className="text-muted-foreground"
-                  aria-label="View options"
-                >
-                  <SlidersHorizontal className="size-3.5" strokeWidth={2.25} />
-                </Button>
-              </DropdownMenuTrigger>
+              <Button
+                variant="ghost"
+                size="icon-xs"
+                className="text-muted-foreground"
+                aria-label="Workspace board"
+                aria-pressed={workspaceBoardOpen}
+                onClick={() => setWorkspaceBoardOpen((open) => !open)}
+              >
+                <Kanban className="size-3.5" strokeWidth={2.25} />
+              </Button>
             </TooltipTrigger>
             <TooltipContent side="bottom" sideOffset={6}>
-              View options
+              Workspace board
             </TooltipContent>
           </Tooltip>
-          <DropdownMenuContent side="right" align="start" sideOffset={8} className="w-56 pb-2">
-            <DropdownMenuLabel>Group by</DropdownMenuLabel>
-            <div className="px-2 pt-0.5 pb-1">
-              <ToggleGroup
-                type="single"
-                value={groupBy}
-                onValueChange={(v) => {
-                  if (v) {
-                    setGroupBy(v as typeof groupBy)
+        </div>
+        <div className="flex items-center gap-1.5 shrink-0">
+          <SidebarFilter />
+          <DropdownMenu>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <DropdownMenuTrigger asChild>
+                  <Button
+                    variant="ghost"
+                    size="icon-xs"
+                    className="text-muted-foreground"
+                    aria-label="View options"
+                  >
+                    <SlidersHorizontal className="size-3.5" strokeWidth={2.25} />
+                  </Button>
+                </DropdownMenuTrigger>
+              </TooltipTrigger>
+              <TooltipContent side="bottom" sideOffset={6}>
+                View options
+              </TooltipContent>
+            </Tooltip>
+            <DropdownMenuContent side="right" align="start" sideOffset={8} className="w-56 pb-2">
+              <DropdownMenuLabel>Group by</DropdownMenuLabel>
+              <div className="px-2 pt-0.5 pb-1">
+                <ToggleGroup
+                  type="single"
+                  value={groupBy}
+                  onValueChange={(v) => {
+                    if (v) {
+                      setGroupBy(v as typeof groupBy)
+                    }
+                  }}
+                  variant="outline"
+                  size="sm"
+                  className="h-6 w-full justify-start"
+                >
+                  {GROUP_BY_OPTIONS.map((opt) => (
+                    <ToggleGroupItem
+                      key={opt.id}
+                      value={opt.id}
+                      className="h-6 px-2 text-[10px] data-[state=on]:bg-foreground/10 data-[state=on]:font-semibold data-[state=on]:text-foreground"
+                    >
+                      {opt.label}
+                    </ToggleGroupItem>
+                  ))}
+                </ToggleGroup>
+              </div>
+
+              <DropdownMenuSeparator />
+              <DropdownMenuLabel>Sort by</DropdownMenuLabel>
+              <DropdownMenuRadioGroup
+                value={sortBy}
+                onValueChange={(v) => setSortBy(v as typeof sortBy)}
+              >
+                {SORT_OPTIONS.map((opt) => {
+                  const radioItem = (
+                    <DropdownMenuRadioItem
+                      key={opt.id}
+                      value={opt.id}
+                      // Keep the menu open so people can compare sort modes and
+                      // toggle card properties without reopening the same panel.
+                      onSelect={(e) => e.preventDefault()}
+                    >
+                      {opt.label}
+                    </DropdownMenuRadioItem>
+                  )
+                  if (!opt.description) {
+                    return radioItem
                   }
+                  return (
+                    <Tooltip key={opt.id}>
+                      <TooltipTrigger asChild>{radioItem}</TooltipTrigger>
+                      <TooltipContent side="right" sideOffset={6}>
+                        {opt.description}
+                      </TooltipContent>
+                    </Tooltip>
+                  )
+                })}
+              </DropdownMenuRadioGroup>
+
+              <DropdownMenuSeparator />
+              <DropdownMenuLabel>Show properties</DropdownMenuLabel>
+              {PROPERTY_OPTIONS.map((opt) => (
+                <DropdownMenuCheckboxItem
+                  key={opt.id}
+                  checked={worktreeCardProperties.includes(opt.id)}
+                  onCheckedChange={() => toggleWorktreeCardProperty(opt.id)}
+                  onSelect={(e) => e.preventDefault()}
+                >
+                  {opt.label}
+                </DropdownMenuCheckboxItem>
+              ))}
+            </DropdownMenuContent>
+          </DropdownMenu>
+
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="ghost"
+                size="icon-xs"
+                onClick={() => {
+                  if (!canCreateWorktree) {
+                    return
+                  }
+                  openModal('new-workspace-composer', { telemetrySource: 'sidebar' })
                 }}
-                variant="outline"
-                size="sm"
-                className="h-6 w-full justify-start"
+                aria-label="New workspace"
+                disabled={!canCreateWorktree}
               >
-                {GROUP_BY_OPTIONS.map((opt) => (
-                  <ToggleGroupItem
-                    key={opt.id}
-                    value={opt.id}
-                    className="h-6 px-2 text-[10px] data-[state=on]:bg-foreground/10 data-[state=on]:font-semibold data-[state=on]:text-foreground"
-                  >
-                    {opt.label}
-                  </ToggleGroupItem>
-                ))}
-              </ToggleGroup>
-            </div>
-
-            <DropdownMenuSeparator />
-            <DropdownMenuLabel>Sort by</DropdownMenuLabel>
-            <DropdownMenuRadioGroup
-              value={sortBy}
-              onValueChange={(v) => setSortBy(v as typeof sortBy)}
-            >
-              {SORT_OPTIONS.map((opt) => {
-                const radioItem = (
-                  <DropdownMenuRadioItem
-                    key={opt.id}
-                    value={opt.id}
-                    // Keep the menu open so people can compare sort modes and
-                    // toggle card properties without reopening the same panel.
-                    onSelect={(e) => e.preventDefault()}
-                  >
-                    {opt.label}
-                  </DropdownMenuRadioItem>
-                )
-                if (!opt.description) {
-                  return radioItem
-                }
-                return (
-                  <Tooltip key={opt.id}>
-                    <TooltipTrigger asChild>{radioItem}</TooltipTrigger>
-                    <TooltipContent side="right" sideOffset={6}>
-                      {opt.description}
-                    </TooltipContent>
-                  </Tooltip>
-                )
-              })}
-            </DropdownMenuRadioGroup>
-
-            <DropdownMenuSeparator />
-            <DropdownMenuLabel>Show properties</DropdownMenuLabel>
-            {PROPERTY_OPTIONS.map((opt) => (
-              <DropdownMenuCheckboxItem
-                key={opt.id}
-                checked={worktreeCardProperties.includes(opt.id)}
-                onCheckedChange={() => toggleWorktreeCardProperty(opt.id)}
-                onSelect={(e) => e.preventDefault()}
-              >
-                {opt.label}
-              </DropdownMenuCheckboxItem>
-            ))}
-          </DropdownMenuContent>
-        </DropdownMenu>
-
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <Button
-              variant="ghost"
-              size="icon-xs"
-              onClick={() => {
-                if (!canCreateWorktree) {
-                  return
-                }
-                openModal('new-workspace-composer', { telemetrySource: 'sidebar' })
-              }}
-              aria-label="New workspace"
-              disabled={!canCreateWorktree}
-            >
-              <Plus className="size-3.5" strokeWidth={2.25} />
-            </Button>
-          </TooltipTrigger>
-          <TooltipContent side="right" sideOffset={6}>
-            {canCreateWorktree
-              ? `New workspace (${newWorktreeShortcutLabel})`
-              : 'Add a Git project to create worktrees'}
-          </TooltipContent>
-        </Tooltip>
+                <Plus className="size-3.5" strokeWidth={2.25} />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="right" sideOffset={6}>
+              {canCreateWorktree
+                ? `New workspace (${newWorktreeShortcutLabel})`
+                : 'Add a Git project to create worktrees'}
+            </TooltipContent>
+          </Tooltip>
+        </div>
       </div>
-    </div>
+      <WorkspaceKanbanDrawer open={workspaceBoardOpen} onOpenChange={setWorkspaceBoardOpen} />
+    </>
   )
 })
 
diff --git a/src/renderer/src/components/sidebar/WorkspaceKanbanCard.tsx b/src/renderer/src/components/sidebar/WorkspaceKanbanCard.tsx
new file mode 100644
index 00000000000..adde53c34c6
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorkspaceKanbanCard.tsx
@@ -0,0 +1,145 @@
+import React, { useCallback } from 'react'
+import { Pin } from 'lucide-react'
+import { useAppStore } from '@/store'
+import { Badge } from '@/components/ui/badge'
+import { HoverCard, HoverCardContent, HoverCardTrigger } from '@/components/ui/hover-card'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import { getWorktreeStatusLabel } from '@/lib/worktree-status'
+import { cn } from '@/lib/utils'
+import type { Repo, Worktree } from '../../../../shared/types'
+import StatusIndicator from './StatusIndicator'
+import WorktreeCard from './WorktreeCard'
+import WorktreeContextMenu from './WorktreeContextMenu'
+import { useWorktreeActivityStatus } from './use-worktree-activity-status'
+import { writeWorkspaceDragData } from './workspace-status'
+
+type WorkspaceKanbanCardProps = {
+  worktree: Worktree
+  repo: Repo | undefined
+  isActive: boolean
+  compact: boolean
+  onActivate: () => void
+}
+
+export default function WorkspaceKanbanCard({
+  worktree,
+  repo,
+  isActive,
+  compact,
+  onActivate
+}: WorkspaceKanbanCardProps): React.JSX.Element {
+  if (compact) {
+    return (
+      <WorkspaceKanbanCompactCard
+        worktree={worktree}
+        repo={repo}
+        isActive={isActive}
+        onActivate={onActivate}
+      />
+    )
+  }
+
+  return (
+    <div className="relative" data-workspace-board-card-mode="detailed">
+      {worktree.isPinned ? (
+        <Badge
+          variant="outline"
+          className="pointer-events-none absolute right-2 top-1.5 z-10 h-4 gap-1 rounded-full bg-background/90 px-1.5 text-[9px] leading-none text-muted-foreground"
+        >
+          <Pin className="size-2.5" />
+          Pinned
+        </Badge>
+      ) : null}
+      <WorktreeCard worktree={worktree} repo={repo} isActive={isActive} onActivate={onActivate} />
+    </div>
+  )
+}
+
+function WorkspaceKanbanCompactCard({
+  worktree,
+  repo,
+  isActive,
+  onActivate
+}: Omit<WorkspaceKanbanCardProps, 'compact'>): React.JSX.Element {
+  const deleteState = useAppStore((s) => s.deleteStateByWorktreeId[worktree.id])
+  const isDeleting = deleteState?.isDeleting ?? false
+  const status = useWorktreeActivityStatus(worktree.id)
+
+  const handleActivate = useCallback(() => {
+    if (isDeleting) {
+      return
+    }
+    activateAndRevealWorktree(worktree.id)
+    onActivate()
+  }, [isDeleting, onActivate, worktree.id])
+
+  const handleDragStart = useCallback(
+    (event: React.DragEvent<HTMLButtonElement>) => {
+      if (isDeleting) {
+        event.preventDefault()
+        return
+      }
+      writeWorkspaceDragData(event.dataTransfer, worktree.id)
+    },
+    [isDeleting, worktree.id]
+  )
+
+  return (
+    <WorktreeContextMenu worktree={worktree}>
+      <HoverCard openDelay={450} closeDelay={100}>
+        <HoverCardTrigger asChild>
+          <button
+            type="button"
+            draggable={!isDeleting}
+            onDragStart={handleDragStart}
+            onClick={handleActivate}
+            className={cn(
+              'flex h-8 w-full min-w-0 cursor-pointer items-center rounded-md border px-2 text-left text-[12px] outline-none transition-colors',
+              isActive
+                ? 'border-sidebar-ring bg-sidebar-accent text-sidebar-accent-foreground'
+                : 'border-transparent text-foreground hover:bg-sidebar-accent/60 focus-visible:border-sidebar-ring',
+              isDeleting && 'cursor-not-allowed opacity-50 grayscale'
+            )}
+            data-workspace-board-card-mode="compact"
+            aria-label={`Open ${worktree.displayName}`}
+            aria-busy={isDeleting}
+          >
+            <StatusIndicator status={status} aria-hidden="true" className="mr-1" />
+            <span className="sr-only">{getWorktreeStatusLabel(status)}</span>
+            <span className="min-w-0 flex-1 truncate">{worktree.displayName}</span>
+            {repo ? (
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <span
+                    className="ml-2 flex max-w-[25%] shrink-0 items-center gap-1 rounded-[4px] border border-border bg-accent px-1.5 py-0.5 leading-none dark:border-border/60 dark:bg-accent/50"
+                    data-workspace-board-repo-badge=""
+                  >
+                    <span
+                      className="size-1.5 shrink-0 rounded-full"
+                      style={{ backgroundColor: repo.badgeColor }}
+                    />
+                    <span className="min-w-0 truncate text-[10px] font-semibold lowercase text-foreground">
+                      {repo.displayName}
+                    </span>
+                  </span>
+                </TooltipTrigger>
+                <TooltipContent side="top" sideOffset={4}>
+                  {repo.displayName}
+                </TooltipContent>
+              </Tooltip>
+            ) : null}
+          </button>
+        </HoverCardTrigger>
+        <HoverCardContent side="right" align="start" sideOffset={8} className="w-72 p-1.5">
+          <WorktreeCard
+            worktree={worktree}
+            repo={repo}
+            isActive={isActive}
+            onActivate={onActivate}
+          />
+        </HoverCardContent>
+      </HoverCard>
+    </WorktreeContextMenu>
+  )
+}
diff --git a/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx b/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx
new file mode 100644
index 00000000000..51bab89d488
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx
@@ -0,0 +1,430 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useAppStore } from '@/store'
+import { useAllWorktrees, useRepoMap } from '@/store/selectors'
+import { cn } from '@/lib/utils'
+import {
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle
+} from '@/components/ui/sheet'
+import { Button } from '@/components/ui/button'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { LayoutList, Pin, Rows3, X } from 'lucide-react'
+import WorkspaceKanbanCard from './WorkspaceKanbanCard'
+import WorkspaceKanbanSettingsMenu from './WorkspaceKanbanSettingsMenu'
+import {
+  getWorkspaceStatus,
+  hasWorkspaceDragData,
+  readWorkspaceDragData,
+  getWorkspaceStatusVisualMeta
+} from './workspace-status'
+import { useWorkspaceStatusDocumentDrop } from './use-workspace-status-drop'
+import type { WorkspaceStatus, Worktree } from '../../../../shared/types'
+import { makeWorkspaceStatusId } from '../../../../shared/workspace-statuses'
+
+type WorkspaceKanbanDrawerProps = {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}
+
+function sortBoardWorktrees(a: Worktree, b: Worktree): number {
+  return b.lastActivityAt - a.lastActivityAt || a.displayName.localeCompare(b.displayName)
+}
+
+export default function WorkspaceKanbanDrawer({
+  open,
+  onOpenChange
+}: WorkspaceKanbanDrawerProps): React.JSX.Element {
+  const allWorktrees = useAllWorktrees()
+  const repoMap = useRepoMap()
+  const activeWorktreeId = useAppStore((s) => s.activeWorktreeId)
+  const updateWorktreeMeta = useAppStore((s) => s.updateWorktreeMeta)
+  const workspaceStatuses = useAppStore((s) => s.workspaceStatuses)
+  const setWorkspaceStatuses = useAppStore((s) => s.setWorkspaceStatuses)
+  const workspaceBoardOpacity = useAppStore((s) => s.workspaceBoardOpacity)
+  const setWorkspaceBoardOpacity = useAppStore((s) => s.setWorkspaceBoardOpacity)
+  const workspaceBoardCompact = useAppStore((s) => s.workspaceBoardCompact)
+  const setWorkspaceBoardCompact = useAppStore((s) => s.setWorkspaceBoardCompact)
+  const sidebarOpen = useAppStore((s) => s.sidebarOpen)
+  const sidebarWidth = useAppStore((s) => s.sidebarWidth)
+  const boardRef = useRef<HTMLDivElement>(null)
+  const [dragOverStatus, setDragOverStatus] = useState<WorkspaceStatus | null>(null)
+  const [pinDragOver, setPinDragOver] = useState(false)
+
+  const worktreesByStatus = useMemo(() => {
+    const grouped = new Map<WorkspaceStatus, Worktree[]>(
+      workspaceStatuses.map((status) => [status.id, []])
+    )
+    for (const worktree of allWorktrees) {
+      if (worktree.isArchived) {
+        continue
+      }
+      grouped.get(getWorkspaceStatus(worktree, workspaceStatuses))!.push(worktree)
+    }
+    for (const items of grouped.values()) {
+      items.sort((a, b) => Number(b.isPinned) - Number(a.isPinned) || sortBoardWorktrees(a, b))
+    }
+    return grouped
+  }, [allWorktrees, workspaceStatuses])
+
+  const moveWorktreeToStatus = useCallback(
+    (worktreeId: string, status: WorkspaceStatus) => {
+      const current = allWorktrees.find((worktree) => worktree.id === worktreeId)
+      if (!current || getWorkspaceStatus(current, workspaceStatuses) === status) {
+        return
+      }
+      void updateWorktreeMeta(worktreeId, { workspaceStatus: status })
+    },
+    [allWorktrees, updateWorktreeMeta, workspaceStatuses]
+  )
+
+  const pinWorktree = useCallback(
+    (worktreeId: string) => {
+      const current = allWorktrees.find((worktree) => worktree.id === worktreeId)
+      if (!current || current.isPinned) {
+        return
+      }
+      void updateWorktreeMeta(worktreeId, { isPinned: true })
+    },
+    [allWorktrees, updateWorktreeMeta]
+  )
+
+  const handleDragOver = useCallback((event: React.DragEvent, status: WorkspaceStatus) => {
+    if (!hasWorkspaceDragData(event.dataTransfer)) {
+      return
+    }
+    event.preventDefault()
+    event.dataTransfer.dropEffect = 'move'
+    setDragOverStatus(status)
+  }, [])
+
+  const handleDragLeave = useCallback((event: React.DragEvent) => {
+    const relatedTarget = event.relatedTarget
+    if (relatedTarget instanceof Node && event.currentTarget.contains(relatedTarget)) {
+      return
+    }
+    setDragOverStatus(null)
+  }, [])
+
+  const handlePinDragOver = useCallback((event: React.DragEvent) => {
+    if (!hasWorkspaceDragData(event.dataTransfer)) {
+      return
+    }
+    event.preventDefault()
+    event.dataTransfer.dropEffect = 'move'
+    setPinDragOver(true)
+  }, [])
+
+  const handlePinDragLeave = useCallback((event: React.DragEvent) => {
+    const relatedTarget = event.relatedTarget
+    if (relatedTarget instanceof Node && event.currentTarget.contains(relatedTarget)) {
+      return
+    }
+    setPinDragOver(false)
+  }, [])
+
+  const handleDragFinish = useCallback(() => {
+    setDragOverStatus(null)
+    setPinDragOver(false)
+  }, [])
+
+  const handleDrop = useCallback(
+    (event: React.DragEvent, status: WorkspaceStatus) => {
+      const worktreeId = readWorkspaceDragData(event.dataTransfer)
+      if (!worktreeId) {
+        return
+      }
+      event.preventDefault()
+      setDragOverStatus(null)
+      moveWorktreeToStatus(worktreeId, status)
+    },
+    [moveWorktreeToStatus]
+  )
+
+  const handleWorktreeActivate = useCallback(() => {
+    onOpenChange(false)
+  }, [onOpenChange])
+
+  const handleOpacityChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      setWorkspaceBoardOpacity(Number(event.target.value) / 100)
+    },
+    [setWorkspaceBoardOpacity]
+  )
+
+  const handleRenameStatus = useCallback(
+    (statusId: string, label: string) => {
+      const trimmed = label.trim()
+      if (!trimmed) {
+        return
+      }
+      setWorkspaceStatuses(
+        workspaceStatuses.map((status) =>
+          status.id === statusId ? { ...status, label: trimmed } : status
+        )
+      )
+    },
+    [setWorkspaceStatuses, workspaceStatuses]
+  )
+
+  const handleChangeStatusColor = useCallback(
+    (statusId: string, color: string) => {
+      setWorkspaceStatuses(
+        workspaceStatuses.map((status) => (status.id === statusId ? { ...status, color } : status))
+      )
+    },
+    [setWorkspaceStatuses, workspaceStatuses]
+  )
+
+  const handleChangeStatusIcon = useCallback(
+    (statusId: string, icon: string) => {
+      setWorkspaceStatuses(
+        workspaceStatuses.map((status) => (status.id === statusId ? { ...status, icon } : status))
+      )
+    },
+    [setWorkspaceStatuses, workspaceStatuses]
+  )
+
+  const handleMoveStatus = useCallback(
+    (statusId: string, direction: -1 | 1) => {
+      const index = workspaceStatuses.findIndex((status) => status.id === statusId)
+      const nextIndex = index + direction
+      if (index === -1 || nextIndex < 0 || nextIndex >= workspaceStatuses.length) {
+        return
+      }
+      const next = [...workspaceStatuses]
+      const [moved] = next.splice(index, 1)
+      next.splice(nextIndex, 0, moved)
+      setWorkspaceStatuses(next)
+    },
+    [setWorkspaceStatuses, workspaceStatuses]
+  )
+
+  const handleAddStatus = useCallback(() => {
+    const label = `Status ${workspaceStatuses.length + 1}`
+    setWorkspaceStatuses([
+      ...workspaceStatuses,
+      { id: makeWorkspaceStatusId(label, workspaceStatuses), label }
+    ])
+  }, [setWorkspaceStatuses, workspaceStatuses])
+
+  const handleRemoveStatus = useCallback(
+    (statusId: string) => {
+      if (workspaceStatuses.length <= 1) {
+        return
+      }
+      const index = workspaceStatuses.findIndex((status) => status.id === statusId)
+      if (index === -1) {
+        return
+      }
+      const next = workspaceStatuses.filter((status) => status.id !== statusId)
+      const fallbackStatus = next[Math.min(index, next.length - 1)]?.id ?? next[0]!.id
+      setWorkspaceStatuses(next)
+      for (const worktree of allWorktrees) {
+        if (getWorkspaceStatus(worktree, workspaceStatuses) === statusId) {
+          void updateWorktreeMeta(worktree.id, { workspaceStatus: fallbackStatus })
+        }
+      }
+    },
+    [allWorktrees, setWorkspaceStatuses, updateWorktreeMeta, workspaceStatuses]
+  )
+
+  useWorkspaceStatusDocumentDrop(
+    boardRef,
+    moveWorktreeToStatus,
+    pinWorktree,
+    handleDragFinish,
+    open
+  )
+
+  useEffect(() => {
+    if (!open) {
+      return
+    }
+
+    const handlePointerDown = (event: PointerEvent): void => {
+      const content = boardRef.current?.closest<HTMLElement>('[data-slot="sheet-content"]')
+      if (!content) {
+        return
+      }
+      const target = event.target
+      if (target instanceof Node && content.contains(target)) {
+        return
+      }
+      const rect = content.getBoundingClientRect()
+      if (event.clientX > rect.right && event.clientY >= rect.top && event.clientY <= rect.bottom) {
+        onOpenChange(false)
+      }
+    }
+
+    document.addEventListener('pointerdown', handlePointerDown, true)
+    return () => document.removeEventListener('pointerdown', handlePointerDown, true)
+  }, [onOpenChange, open])
+
+  const opacityPercent = Math.round(workspaceBoardOpacity * 100)
+  const drawerLeft = sidebarOpen ? sidebarWidth : 0
+  const BoardModeIcon = workspaceBoardCompact ? Rows3 : LayoutList
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange} modal={false}>
+      <SheetContent
+        side="left"
+        showCloseButton={false}
+        className="workspace-kanban-sheet-content bg-sidebar p-0 sm:max-w-none"
+        overlayStyle={{ top: 36, left: drawerLeft, pointerEvents: 'none' }}
+        style={
+          {
+            // Why: the board is a companion to the workspace sidebar, so it
+            // expands from the sidebar edge instead of covering the sidebar.
+            left: drawerLeft,
+            top: 36,
+            height: 'calc(100% - 36px)',
+            width: `min(calc(100vw - ${drawerLeft}px), 1180px)`,
+            opacity: workspaceBoardOpacity
+          } as React.CSSProperties
+        }
+        data-workspace-board-compact={workspaceBoardCompact ? 'true' : 'false'}
+        onOpenAutoFocus={(event) => {
+          // Why: Radix focuses the first toolbar button on open, which opens
+          // its tooltip without hover and makes the drawer feel noisy.
+          event.preventDefault()
+        }}
+        onInteractOutside={(event) => {
+          const originalEvent = event.detail.originalEvent
+          if (originalEvent instanceof PointerEvent && originalEvent.clientX < drawerLeft) {
+            // Why: users need to scroll, click, and drag from the workspace
+            // sidebar while the companion board stays open.
+            event.preventDefault()
+          }
+        }}
+      >
+        <SheetHeader className="border-b border-sidebar-border px-4 py-3 pr-24">
+          <SheetTitle className="text-sm">Workspace board</SheetTitle>
+          <SheetDescription className="sr-only">
+            Organize workspaces by status and open workspace cards.
+          </SheetDescription>
+        </SheetHeader>
+
+        <div className="absolute right-3 top-2.5 flex items-center gap-1">
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                type="button"
+                variant={workspaceBoardCompact ? 'secondary' : 'ghost'}
+                size="icon-xs"
+                aria-pressed={workspaceBoardCompact}
+                aria-label={
+                  workspaceBoardCompact ? 'Compact workspace cards' : 'Detailed workspace cards'
+                }
+                onClick={() => setWorkspaceBoardCompact(!workspaceBoardCompact)}
+              >
+                <BoardModeIcon className="size-3.5" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="top" sideOffset={4}>
+              {workspaceBoardCompact ? 'Show detailed cards' : 'Show compact cards'}
+            </TooltipContent>
+          </Tooltip>
+          <WorkspaceKanbanSettingsMenu
+            opacityPercent={opacityPercent}
+            workspaceStatuses={workspaceStatuses}
+            onOpacityChange={handleOpacityChange}
+            onRenameStatus={handleRenameStatus}
+            onChangeStatusColor={handleChangeStatusColor}
+            onChangeStatusIcon={handleChangeStatusIcon}
+            onMoveStatus={handleMoveStatus}
+            onRemoveStatus={handleRemoveStatus}
+            onAddStatus={handleAddStatus}
+          />
+          <SheetClose asChild>
+            <Button variant="ghost" size="icon-xs" aria-label="Close">
+              <X className="size-3.5" />
+            </Button>
+          </SheetClose>
+        </div>
+
+        <div ref={boardRef} className="flex min-h-0 flex-1 flex-col overflow-hidden p-3">
+          <div
+            data-workspace-pin-drop-target=""
+            className={cn(
+              'mb-3 flex h-8 shrink-0 items-center gap-2 rounded-md border border-dashed border-sidebar-border bg-background/45 px-3 text-[12px] text-muted-foreground transition-colors',
+              pinDragOver && 'border-sidebar-ring bg-sidebar-accent text-foreground'
+            )}
+            onDragOver={handlePinDragOver}
+            onDragLeave={handlePinDragLeave}
+          >
+            <Pin className="size-3.5" />
+            <span className="font-medium">Pinned</span>
+            <span className="truncate">Drop here to pin without changing status.</span>
+          </div>
+
+          <div className="min-h-0 flex-1 overflow-x-auto overflow-y-hidden scrollbar-sleek">
+            <div
+              className="grid h-full min-h-0 min-w-full grid-rows-[minmax(0,1fr)] gap-3"
+              style={{
+                gridTemplateColumns: `repeat(${workspaceStatuses.length}, minmax(240px, 1fr))`
+              }}
+            >
+              {workspaceStatuses.map((status) => {
+                const meta = getWorkspaceStatusVisualMeta(status)
+                const items = worktreesByStatus.get(status.id) ?? []
+                const isDragTarget = dragOverStatus === status.id
+
+                return (
+                  <section
+                    key={status.id}
+                    data-workspace-status-drop-target=""
+                    data-workspace-status={status.id}
+                    className={cn(
+                      'flex h-full min-h-0 min-w-0 flex-col overflow-hidden rounded-md border border-t-2 border-sidebar-border transition-colors',
+                      meta.border,
+                      meta.laneTint,
+                      isDragTarget && 'border-sidebar-ring bg-sidebar-accent/70'
+                    )}
+                    onDragOver={(event) => handleDragOver(event, status.id)}
+                    onDragLeave={handleDragLeave}
+                    onDrop={(event) => handleDrop(event, status.id)}
+                  >
+                    <div className="flex h-9 shrink-0 items-center gap-2 border-b border-border/70 px-3">
+                      <meta.icon className={cn('size-3.5', meta.tone)} />
+                      <div className="min-w-0 flex-1 truncate text-[12px] font-semibold text-foreground">
+                        {status.label}
+                      </div>
+                      <div className="rounded-full bg-muted px-1.5 py-0.5 text-[9px] font-medium leading-none text-muted-foreground">
+                        {items.length}
+                      </div>
+                    </div>
+
+                    <div className="min-h-0 flex-1 overflow-y-auto overflow-x-hidden px-1.5 py-2 scrollbar-sleek">
+                      {items.length > 0 ? (
+                        <div className="space-y-2">
+                          {items.map((worktree) => (
+                            <WorkspaceKanbanCard
+                              key={worktree.id}
+                              worktree={worktree}
+                              repo={repoMap.get(worktree.repoId)}
+                              isActive={activeWorktreeId === worktree.id}
+                              compact={workspaceBoardCompact}
+                              onActivate={handleWorktreeActivate}
+                            />
+                          ))}
+                        </div>
+                      ) : (
+                        <div className="flex h-20 items-center justify-center rounded-md border border-dashed border-border/70 text-[11px] text-muted-foreground">
+                          Empty
+                        </div>
+                      )}
+                    </div>
+                  </section>
+                )
+              })}
+            </div>
+          </div>
+        </div>
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/src/renderer/src/components/sidebar/WorkspaceKanbanSettingsMenu.tsx b/src/renderer/src/components/sidebar/WorkspaceKanbanSettingsMenu.tsx
new file mode 100644
index 00000000000..dfc85908acc
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorkspaceKanbanSettingsMenu.tsx
@@ -0,0 +1,156 @@
+import React from 'react'
+import { ArrowDown, ArrowUp, Plus, Settings2, Trash2 } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { cn } from '@/lib/utils'
+import type { WorkspaceStatusDefinition } from '../../../../shared/types'
+import { getWorkspaceStatusVisualMeta } from './workspace-status'
+import WorkspaceStatusAppearancePopover from './WorkspaceStatusAppearancePopover'
+
+type WorkspaceKanbanSettingsMenuProps = {
+  opacityPercent: number
+  workspaceStatuses: readonly WorkspaceStatusDefinition[]
+  onOpacityChange: (event: React.ChangeEvent<HTMLInputElement>) => void
+  onRenameStatus: (statusId: string, label: string) => void
+  onChangeStatusColor: (statusId: string, color: string) => void
+  onChangeStatusIcon: (statusId: string, icon: string) => void
+  onMoveStatus: (statusId: string, direction: -1 | 1) => void
+  onRemoveStatus: (statusId: string) => void
+  onAddStatus: () => void
+}
+
+export default function WorkspaceKanbanSettingsMenu({
+  opacityPercent,
+  workspaceStatuses,
+  onOpacityChange,
+  onRenameStatus,
+  onChangeStatusColor,
+  onChangeStatusIcon,
+  onMoveStatus,
+  onRemoveStatus,
+  onAddStatus
+}: WorkspaceKanbanSettingsMenuProps): React.JSX.Element {
+  return (
+    <DropdownMenu modal={false}>
+      <DropdownMenuTrigger asChild>
+        <Button variant="ghost" size="icon-xs" aria-label="Workspace board settings">
+          <Settings2 className="size-3.5" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        align="end"
+        sideOffset={8}
+        className="max-h-[min(80vh,720px)] w-80 overflow-y-auto p-2 scrollbar-sleek"
+        onInteractOutside={(event) => {
+          const target = event.target
+          if (
+            target instanceof Element &&
+            target.closest('[data-workspace-status-appearance-popover]')
+          ) {
+            event.preventDefault()
+          }
+        }}
+      >
+        <DropdownMenuLabel>Board opacity</DropdownMenuLabel>
+        <div className="px-2 pb-2">
+          <div className="mb-1 flex items-center justify-between text-[11px] text-muted-foreground">
+            <span>Pane opacity</span>
+            <span>{opacityPercent}%</span>
+          </div>
+          <input
+            type="range"
+            min={20}
+            max={100}
+            value={opacityPercent}
+            onChange={onOpacityChange}
+            className="h-5 w-full accent-foreground"
+            aria-label="Workspace board opacity"
+          />
+        </div>
+        <DropdownMenuSeparator />
+        <DropdownMenuLabel>Statuses</DropdownMenuLabel>
+        <div className="space-y-2 px-1 pb-1">
+          {workspaceStatuses.map((status, index) => {
+            const meta = getWorkspaceStatusVisualMeta(status)
+            return (
+              <div
+                key={status.id}
+                className="rounded-md border border-border/70 bg-background/40 p-1.5"
+              >
+                <div className="flex items-center gap-1">
+                  <meta.icon className={cn('size-3.5 shrink-0', meta.tone)} />
+                  <input
+                    defaultValue={status.label}
+                    onBlur={(event) => onRenameStatus(status.id, event.target.value)}
+                    onKeyDown={(event) => {
+                      event.stopPropagation()
+                      if (event.key === 'Enter') {
+                        event.currentTarget.blur()
+                      }
+                    }}
+                    className="h-7 min-w-0 flex-1 rounded-md border border-input bg-background px-2 text-[12px] text-foreground outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                    aria-label={`Rename ${status.label}`}
+                  />
+                  <WorkspaceStatusAppearancePopover
+                    status={status}
+                    onChangeColor={onChangeStatusColor}
+                    onChangeIcon={onChangeStatusIcon}
+                  />
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    className="size-7"
+                    disabled={index === 0}
+                    onClick={() => onMoveStatus(status.id, -1)}
+                    aria-label={`Move ${status.label} left`}
+                  >
+                    <ArrowUp className="size-3.5" />
+                  </Button>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    className="size-7"
+                    disabled={index === workspaceStatuses.length - 1}
+                    onClick={() => onMoveStatus(status.id, 1)}
+                    aria-label={`Move ${status.label} right`}
+                  >
+                    <ArrowDown className="size-3.5" />
+                  </Button>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    className="size-7 text-muted-foreground hover:text-destructive"
+                    disabled={workspaceStatuses.length <= 1}
+                    onClick={() => onRemoveStatus(status.id)}
+                    aria-label={`Remove ${status.label}`}
+                  >
+                    <Trash2 className="size-3.5" />
+                  </Button>
+                </div>
+              </div>
+            )
+          })}
+          <Button
+            type="button"
+            variant="ghost"
+            size="xs"
+            className="mt-1 h-7 w-full justify-start text-[12px]"
+            onClick={onAddStatus}
+          >
+            <Plus className="size-3.5" />
+            Add status
+          </Button>
+        </div>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/src/renderer/src/components/sidebar/WorkspaceStatusAppearancePopover.tsx b/src/renderer/src/components/sidebar/WorkspaceStatusAppearancePopover.tsx
new file mode 100644
index 00000000000..cce501faf84
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorkspaceStatusAppearancePopover.tsx
@@ -0,0 +1,106 @@
+import React from 'react'
+import { Button } from '@/components/ui/button'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { cn } from '@/lib/utils'
+import type { WorkspaceStatusDefinition } from '../../../../shared/types'
+import {
+  WORKSPACE_STATUS_COLOR_OPTIONS,
+  WORKSPACE_STATUS_ICON_OPTIONS,
+  getWorkspaceStatusVisualMeta
+} from './workspace-status'
+
+type WorkspaceStatusAppearancePopoverProps = {
+  status: WorkspaceStatusDefinition
+  onChangeColor: (statusId: string, color: string) => void
+  onChangeIcon: (statusId: string, icon: string) => void
+}
+
+export default function WorkspaceStatusAppearancePopover({
+  status,
+  onChangeColor,
+  onChangeIcon
+}: WorkspaceStatusAppearancePopoverProps): React.JSX.Element {
+  const meta = getWorkspaceStatusVisualMeta(status)
+
+  return (
+    <Popover modal={false}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <PopoverTrigger asChild>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-xs"
+              className="relative size-7"
+              aria-label={`Customize ${status.label} appearance`}
+            >
+              <span className={cn('absolute size-4 rounded-full opacity-20', meta.swatch)} />
+              <meta.icon className={cn('relative size-3.5', meta.tone)} />
+            </Button>
+          </PopoverTrigger>
+        </TooltipTrigger>
+        <TooltipContent side="top" sideOffset={4}>
+          Appearance
+        </TooltipContent>
+      </Tooltip>
+
+      <PopoverContent
+        align="end"
+        side="left"
+        sideOffset={8}
+        className="w-72 p-2"
+        data-workspace-status-appearance-popover=""
+        onOpenAutoFocus={(event) => event.preventDefault()}
+      >
+        <div className="px-1 py-1 text-[11px] font-semibold text-muted-foreground">Color</div>
+        <div className="grid grid-cols-4 gap-1">
+          {WORKSPACE_STATUS_COLOR_OPTIONS.map((color) => (
+            <Tooltip key={color.id}>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  className={cn(
+                    'flex h-8 items-center gap-1.5 rounded-md border border-transparent px-2 text-[11px] text-foreground outline-none transition-colors hover:bg-accent focus-visible:ring-1 focus-visible:ring-ring',
+                    status.color === color.id && 'border-ring bg-accent'
+                  )}
+                  onClick={() => onChangeColor(status.id, color.id)}
+                  aria-label={`Set ${status.label} color to ${color.label}`}
+                >
+                  <span className={cn('size-3 rounded-full', color.swatch)} />
+                  <span className="min-w-0 truncate">{color.label}</span>
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={4}>
+                {color.label}
+              </TooltipContent>
+            </Tooltip>
+          ))}
+        </div>
+
+        <div className="mt-2 px-1 py-1 text-[11px] font-semibold text-muted-foreground">Icon</div>
+        <div className="grid grid-cols-6 gap-1">
+          {WORKSPACE_STATUS_ICON_OPTIONS.map((icon) => (
+            <Tooltip key={icon.id}>
+              <TooltipTrigger asChild>
+                <Button
+                  type="button"
+                  variant={status.icon === icon.id ? 'secondary' : 'ghost'}
+                  size="icon-xs"
+                  className="size-8"
+                  onClick={() => onChangeIcon(status.id, icon.id)}
+                  aria-label={`Set ${status.label} icon to ${icon.label}`}
+                >
+                  <icon.icon className="size-3.5" />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={4}>
+                {icon.label}
+              </TooltipContent>
+            </Tooltip>
+          ))}
+        </div>
+      </PopoverContent>
+    </Popover>
+  )
+}
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.tsx b/src/renderer/src/components/sidebar/WorktreeCard.tsx
index 646506caf78..a444bf39e19 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.tsx
@@ -1,6 +1,5 @@
 /* eslint-disable max-lines -- Why: the worktree card centralizes sidebar card state (selection, drag, agent status, git info, context menu) in one cohesive component so sidebar rendering doesn't fan out across files. */
-import React, { useEffect, useMemo, useCallback, useState } from 'react'
-import { useShallow } from 'zustand/react/shallow'
+import React, { useEffect, useCallback, useState } from 'react'
 import { useAppStore } from '@/store'
 import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
 import { Badge } from '@/components/ui/badge'
@@ -22,13 +21,7 @@ import { SshDisconnectedDialog } from './SshDisconnectedDialog'
 import WorktreeCardAgents from './WorktreeCardAgents'
 import { cn } from '@/lib/utils'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
-import {
-  getWorktreeStatusLabel,
-  resolveWorktreeStatus,
-  type WorktreeStatus
-} from '@/lib/worktree-status'
-import { isExplicitAgentStatusFresh } from '@/lib/agent-status'
-import { AGENT_STATUS_STALE_AFTER_MS } from '../../../../shared/agent-status-types'
+import { getWorktreeStatusLabel } from '@/lib/worktree-status'
 import { getRepoKindLabel, isFolderRepo } from '../../../../shared/repo-kind'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 import type { Worktree, Repo, IssueInfo } from '../../../../shared/types'
@@ -36,15 +29,11 @@ import {
   branchDisplayName,
   checksLabel,
   CONFLICT_OPERATION_LABELS,
-  EMPTY_TABS,
-  EMPTY_BROWSER_TABS,
   FilledBellIcon
 } from './WorktreeCardHelpers'
 import { IssueSection, ReviewSection, CommentSection } from './WorktreeCardMeta'
-import {
-  selectLivePtyIdsForWorktree,
-  selectRuntimePaneTitlesForWorktree
-} from './worktree-card-status-inputs'
+import { writeWorkspaceDragData } from './workspace-status'
+import { useWorktreeActivityStatus } from './use-worktree-activity-status'
 
 type WorktreeCardProps = {
   worktree: Worktree
@@ -53,6 +42,7 @@ type WorktreeCardProps = {
   isMultiSelected?: boolean
   selectedWorktrees?: readonly Worktree[]
   hideRepoBadge?: boolean
+  onActivate?: () => void
   onSelectionGesture?: (event: React.MouseEvent<HTMLDivElement>, worktreeId: string) => boolean
   onContextMenuSelect?: (event: React.MouseEvent<HTMLDivElement>) => readonly Worktree[]
 }
@@ -68,6 +58,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
   isActive,
   isMultiSelected = false,
   selectedWorktrees,
+  onActivate,
   onSelectionGesture,
   onContextMenuSelect,
   hideRepoBadge
@@ -152,29 +143,6 @@ const WorktreeCard = React.memo(function WorktreeCard({
     repo?.connectionId ? (s.sshTargetLabels.get(repo.connectionId) ?? '') : ''
   )
 
-  // ── GRANULAR selectors: only subscribe to THIS worktree's data ──
-  const tabs = useAppStore((s) => s.tabsByWorktree[worktree.id] ?? EMPTY_TABS)
-  const browserTabs = useAppStore((s) => s.browserTabsByWorktree[worktree.id] ?? EMPTY_BROWSER_TABS)
-  const hasNotesSurface = useAppStore((s) =>
-    (s.unifiedTabsByWorktree[worktree.id] ?? []).some((tab) => tab.contentType === 'notes')
-  )
-  // Why: keep these as separate shallow selectors. Combining them into one
-  // returned object nests freshly-created maps under fresh keys, so Zustand's
-  // shallow memoization sees every unrelated store write as a change and
-  // re-renders every mounted card.
-  // tab.ptyId is the wake-hint sessionId preserved across sleep, not a
-  // liveness signal; sleep-then-card-render would lie the dot green if we
-  // read tab.ptyId; ptyIdsByTabId is the source of truth.
-  // tab.title is the focused-pane title (onActivePaneChange overwrites it),
-  // so the per-pane title map is needed to keep the sidebar spinner
-  // reflecting *any* working pane, not just the focused one.
-  const runtimePaneTitlesForWorktree = useAppStore(
-    useShallow((s) => selectRuntimePaneTitlesForWorktree(s, worktree.id))
-  )
-  const ptyIdsForWorktree = useAppStore(
-    useShallow((s) => selectLivePtyIdsForWorktree(s, worktree.id))
-  )
-
   const branch = branchDisplayName(worktree.branch)
   const isFolder = repo ? isFolderRepo(repo) : false
   const hostedReviewCacheKey =
@@ -207,109 +175,7 @@ const WorktreeCard = React.memo(function WorktreeCard({
       : null)
   const isDeleting = deleteState?.isDeleting ?? false
 
-  // Why: the sidebar dot overlays the *stable* hook-reported states (blocked,
-  // waiting, done) onto the title-heuristic base. `working` remains on the
-  // heuristic because hook pings flip on/off mid-turn and users complained
-  // that the spinner flickered; the blocked/waiting/done states don't have
-  // that problem — they're terminal (done) or attention-needed (blocked/
-  // waiting) and persist until the user acts. Retained "done" snapshots are
-  // consulted too so the done dot keeps glowing after the agent process exits,
-  // matching the dashboard's retention behavior.
-  //
-  // Priority (highest first): permission (blocked/waiting) > heuristic
-  // 'working' > done > other heuristic ('active'/'inactive').
-  // permission wins over everything because a newer blocked agent in the same
-  // worktree means the user needs to act now, not admire a previous
-  // completion.
-  // heuristic 'working' wins over done because a spinner means the user has
-  // already re-prompted the agent after it reported done — the newer "work
-  // in progress" signal is more informative than a retained completion dot.
-  // Only the 'working' heuristic earns this precedence; 'active'/'inactive'
-  // mean "quiet terminal", which shouldn't drown out a recent done.
-  // Why: collapse live hook entries to booleans inside the selector so the
-  // snapshot is a stable scalar (useShallow compares element identity — an
-  // array of freshly-constructed {state,updatedAt} objects would never hit
-  // the cache and trip React's "getSnapshot should be cached" infinite-loop
-  // guard). Staleness is applied here too so the selector already reflects
-  // the 30-min TTL; agentStatusEpoch pulls in the tick that fires when a
-  // fresh entry crosses the stale boundary. The same useShallow wrapper
-  // covers hasPermission, hasLiveDone, *and* hasRetainedDone — merging the
-  // retained scan into the same selector avoids a second full-map iteration
-  // per card on every retention write (with N sidebar cards on screen a
-  // standalone retained selector scans Object.values(...) N times per tick).
-  const { hasPermission, hasLiveDone, hasRetainedDone } = useAppStore(
-    useShallow((s) => {
-      // Touch the epoch so this selector re-runs when the freshness scheduler
-      // ticks — otherwise a stale transition wouldn't flip the booleans until
-      // some unrelated store write happened to rerun us.
-      void s.agentStatusEpoch
-      const wtTabs = s.tabsByWorktree[worktree.id] ?? EMPTY_TABS
-      let perm = false
-      let live = false
-      if (wtTabs.length > 0) {
-        const tabIds = new Set(wtTabs.map((t) => t.id))
-        const now = Date.now()
-        for (const [paneKey, entry] of Object.entries(s.agentStatusByPaneKey)) {
-          const sepIdx = paneKey.indexOf(':')
-          if (sepIdx <= 0) {
-            continue
-          }
-          const tabId = paneKey.slice(0, sepIdx)
-          if (!tabIds.has(tabId)) {
-            continue
-          }
-          if (!isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)) {
-            continue
-          }
-          if (entry.state === 'blocked' || entry.state === 'waiting') {
-            perm = true
-          } else if (entry.state === 'done') {
-            live = true
-          }
-        }
-      }
-      // Retained scan — one pass in the same selector avoids a second
-      // Object.values(...) per store tick (one per sidebar card).
-      let retained = false
-      for (const ra of Object.values(s.retainedAgentsByPaneKey)) {
-        if (ra.worktreeId === worktree.id) {
-          retained = true
-          break
-        }
-      }
-      return { hasPermission: perm, hasLiveDone: live, hasRetainedDone: retained }
-    })
-  )
-
-  // Why: resolveWorktreeStatus enforces the runtime-liveness precondition —
-  // when no tab in this worktree has a live PTY (and no browser tab exists)
-  // it short-circuits to 'inactive' before consulting hook-reported state or
-  // retained-done snapshots. That keeps the dot honest across sleep, crash,
-  // and slept-with-retained-done while preserving the row data used by the
-  // inline agents list (retained 'done' rows still render inside the card).
-  const status: WorktreeStatus = useMemo(
-    () =>
-      resolveWorktreeStatus({
-        tabs,
-        browserTabs,
-        ptyIdsByTabId: ptyIdsForWorktree,
-        runtimePaneTitlesByTabId: runtimePaneTitlesForWorktree,
-        hasNotesSurface,
-        hasPermission,
-        hasLiveDone,
-        hasRetainedDone
-      }),
-    [
-      tabs,
-      browserTabs,
-      ptyIdsForWorktree,
-      runtimePaneTitlesForWorktree,
-      hasNotesSurface,
-      hasPermission,
-      hasLiveDone,
-      hasRetainedDone
-    ]
-  )
+  const status = useWorktreeActivityStatus(worktree.id)
 
   const showPR = cardProps.includes('pr')
   const showCI = cardProps.includes('ci')
@@ -399,8 +265,9 @@ const WorktreeCard = React.memo(function WorktreeCard({
       if (isSshDisconnected) {
         setShowDisconnectedDialog(true)
       }
+      onActivate?.()
     },
-    [worktree.id, isSshDisconnected, onSelectionGesture]
+    [worktree.id, isSshDisconnected, onActivate, onSelectionGesture]
   )
 
   const handleDoubleClick = useCallback(() => {
@@ -431,6 +298,17 @@ const WorktreeCard = React.memo(function WorktreeCard({
 
   const unreadTooltip = worktree.isUnread ? 'Mark read' : 'Mark unread'
 
+  const handleDragStart = useCallback(
+    (event: React.DragEvent<HTMLDivElement>) => {
+      if (isDeleting) {
+        event.preventDefault()
+        return
+      }
+      writeWorkspaceDragData(event.dataTransfer, worktree.id)
+    },
+    [isDeleting, worktree.id]
+  )
+
   // Why: the 'unread' card property is the user's opt-out. When off, we render
   // as if the workspace is read so bold emphasis never appears. The persisted
   // `worktree.isUnread` flag is unchanged; only the rendering changes.
@@ -452,6 +330,8 @@ const WorktreeCard = React.memo(function WorktreeCard({
       )}
       onClick={handleClick}
       onDoubleClick={handleDoubleClick}
+      draggable={!isDeleting}
+      onDragStart={handleDragStart}
       aria-busy={isDeleting}
     >
       {isDeleting && (
diff --git a/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx b/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
index 31b9f77245b..dd522a58a08 100644
--- a/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
@@ -3,7 +3,12 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
   DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
   DropdownMenuTrigger
 } from '@/components/ui/dropdown-menu'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
@@ -18,6 +23,7 @@ import {
   Pencil,
   Pin,
   PinOff,
+  Kanban,
   Trash2
 } from 'lucide-react'
 import { useAppStore } from '@/store'
@@ -28,6 +34,7 @@ import { isFolderRepo } from '../../../../shared/repo-kind'
 import { runWorktreeBatchDelete, runWorktreeDelete } from './delete-worktree-flow'
 import { runSleepWorktrees } from './sleep-worktree-flow'
 import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
+import { getWorkspaceStatus, getWorkspaceStatusVisualMeta } from './workspace-status'
 
 type Props = {
   worktree: Worktree
@@ -48,6 +55,7 @@ const WorktreeContextMenu = React.memo(function WorktreeContextMenu({
   onContextMenuSelect
 }: Props) {
   const updateWorktreeMeta = useAppStore((s) => s.updateWorktreeMeta)
+  const workspaceStatuses = useAppStore((s) => s.workspaceStatuses)
   const openModal = useAppStore((s) => s.openModal)
   const repo = useRepoById(worktree.repoId)
   const deleteState = useAppStore((s) => s.deleteStateByWorktreeId[worktree.id])
@@ -77,6 +85,16 @@ const WorktreeContextMenu = React.memo(function WorktreeContextMenu({
     () => activeContextWorktrees.some((item) => deleteStateByWorktreeId[item.id]?.isDeleting),
     [activeContextWorktrees, deleteStateByWorktreeId]
   )
+  const contextWorkspaceStatus = useMemo(() => {
+    const [first, ...rest] = activeContextWorktrees
+    if (!first) {
+      return ''
+    }
+    const status = getWorkspaceStatus(first, workspaceStatuses)
+    return rest.every((item) => getWorkspaceStatus(item, workspaceStatuses) === status)
+      ? status
+      : ''
+  }, [activeContextWorktrees, workspaceStatuses])
   const batchDeleteWorktrees = useMemo(
     () =>
       activeContextWorktrees.filter((item) => {
@@ -124,6 +142,20 @@ const WorktreeContextMenu = React.memo(function WorktreeContextMenu({
     updateWorktreeMeta(worktree.id, { isPinned: !worktree.isPinned })
   }, [worktree.id, worktree.isPinned, updateWorktreeMeta])
 
+  const handleAssignWorkspaceStatus = useCallback(
+    (status: string) => {
+      setMenuOpen(false)
+      void Promise.all(
+        activeContextWorktrees.map((item) =>
+          getWorkspaceStatus(item, workspaceStatuses) === status
+            ? Promise.resolve()
+            : updateWorktreeMeta(item.id, { workspaceStatus: status })
+        )
+      )
+    },
+    [activeContextWorktrees, updateWorktreeMeta, workspaceStatuses]
+  )
+
   const handleRename = useCallback(() => {
     openModal('edit-meta', {
       worktreeId: worktree.id,
@@ -286,6 +318,30 @@ const WorktreeContextMenu = React.memo(function WorktreeContextMenu({
               <DropdownMenuSeparator />
             </>
           )}
+          <DropdownMenuSub>
+            <DropdownMenuSubTrigger disabled={deletingContext}>
+              <Kanban className="size-3.5" />
+              {isMultiContext ? 'Move Selected to Status' : 'Move to Status'}
+            </DropdownMenuSubTrigger>
+            <DropdownMenuSubContent className="w-44">
+              <DropdownMenuRadioGroup value={contextWorkspaceStatus}>
+                {workspaceStatuses.map((status) => {
+                  const meta = getWorkspaceStatusVisualMeta(status)
+                  return (
+                    <DropdownMenuRadioItem
+                      key={status.id}
+                      value={status.id}
+                      onSelect={() => handleAssignWorkspaceStatus(status.id)}
+                    >
+                      <meta.icon className={cn('size-3.5', meta.tone)} />
+                      {status.label}
+                    </DropdownMenuRadioItem>
+                  )
+                })}
+              </DropdownMenuRadioGroup>
+            </DropdownMenuSubContent>
+          </DropdownMenuSub>
+          <DropdownMenuSeparator />
           <Tooltip>
             <TooltipTrigger asChild>
               <DropdownMenuItem
diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index c423a029b69..bdc5171e686 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -13,7 +13,12 @@ import WorktreeCard from './WorktreeCard'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { cn } from '@/lib/utils'
-import type { Worktree, Repo } from '../../../../shared/types'
+import type {
+  Worktree,
+  Repo,
+  WorkspaceStatus,
+  WorkspaceStatusDefinition
+} from '../../../../shared/types'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import { buildWorktreeComparator } from './smart-sort'
 import {
@@ -26,11 +31,18 @@ import { tabHasLivePty } from '@/lib/tab-has-live-pty'
 import {
   type GroupHeaderRow,
   type Row,
-  ALL_GROUP_KEY,
+  type WorktreeGroupBy,
   PINNED_GROUP_KEY,
   buildRows,
   getGroupKeyForWorktree
 } from './worktree-list-groups'
+import {
+  getWorkspaceStatus,
+  getWorkspaceStatusFromGroupKey,
+  hasWorkspaceDragData,
+  readWorkspaceDragData
+} from './workspace-status'
+import { useWorkspaceStatusDocumentDrop } from './use-workspace-status-drop'
 import {
   computeClearFilterActions,
   computeVisibleWorktreeIds,
@@ -80,7 +92,7 @@ function getWorktreeOptionId(worktreeId: string): string {
 type VirtualizedWorktreeViewportProps = {
   rows: Row[]
   activeWorktreeId: string | null
-  groupBy: 'none' | 'repo' | 'pr-status'
+  groupBy: WorktreeGroupBy
   toggleGroup: (key: string) => void
   collapsedGroups: Set<string>
   handleCreateForRepo: (repoId: string) => void
@@ -104,6 +116,9 @@ type VirtualizedWorktreeViewportProps = {
   allRepoIds: string[]
   reorderRepos: (orderedIds: string[]) => void
   prCache: Record<string, unknown> | null
+  workspaceStatuses: readonly WorkspaceStatusDefinition[]
+  onMoveWorktreeToStatus: (worktreeId: string, status: WorkspaceStatus) => void
+  onPinWorktree: (worktreeId: string) => void
   // Why: the viewport remounts when the row structure changes (see
   // viewportResetKey) so the virtualizer's measurementsCache cannot hold
   // heights tied to shifted indices. A fresh virtualizer would otherwise
@@ -133,9 +148,14 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
   allRepoIds,
   reorderRepos,
   prCache,
+  workspaceStatuses,
+  onMoveWorktreeToStatus,
+  onPinWorktree,
   scrollOffsetRef
 }: VirtualizedWorktreeViewportProps) {
   const scrollRef = useRef<HTMLDivElement>(null)
+  const [dragOverStatus, setDragOverStatus] = useState<WorkspaceStatus | null>(null)
+  const [pinDragOver, setPinDragOver] = useState(false)
 
   // Drag is only meaningful when the user is grouping by repo. When inert
   // (groupBy !== 'repo'), the controller is still constructed for hook order
@@ -231,19 +251,17 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         if (collapsedGroups.has(PINNED_GROUP_KEY)) {
           toggleGroup(PINNED_GROUP_KEY)
         }
-      } else if (targetWorktree && groupBy !== 'none') {
-        const groupKey = getGroupKeyForWorktree(groupBy, targetWorktree, repoMap, prCache)
+      } else if (targetWorktree) {
+        const groupKey = getGroupKeyForWorktree(
+          groupBy,
+          targetWorktree,
+          repoMap,
+          prCache,
+          workspaceStatuses
+        )
         if (groupKey && collapsedGroups.has(groupKey)) {
           toggleGroup(groupKey)
         }
-      } else if (targetWorktree && groupBy === 'none') {
-        // Why: when any worktree is pinned, buildRows emits a sibling "All"
-        // header for the unpinned block (see worktree-list-groups.ts). If that
-        // header is collapsed, revealing an unpinned target would otherwise
-        // leave it hidden — uncollapse it so the card is actually visible.
-        if (collapsedGroups.has(ALL_GROUP_KEY)) {
-          toggleGroup(ALL_GROUP_KEY)
-        }
       }
     }
 
@@ -272,7 +290,8 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
     virtualizer,
     clearPendingRevealWorktreeId,
     toggleGroup,
-    collapsedGroups
+    collapsedGroups,
+    workspaceStatuses
   ])
 
   const prCacheLen = useAppStore((s) => Object.keys(s.prCache).length)
@@ -301,7 +320,8 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         repoMap,
         prCache,
         new Set<string>(),
-        repoOrder
+        repoOrder,
+        workspaceStatuses
       ).filter((r): r is Extract<Row, { type: 'item' }> => r.type === 'item')
       if (worktreeRows.length === 0) {
         return
@@ -334,7 +354,17 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         virtualizer.scrollToIndex(rowIndex, { align: 'auto' })
       }
     },
-    [rows, activeWorktreeId, virtualizer, groupBy, worktrees, repoMap, prCache, repoOrder]
+    [
+      rows,
+      activeWorktreeId,
+      virtualizer,
+      groupBy,
+      worktrees,
+      repoMap,
+      prCache,
+      repoOrder,
+      workspaceStatuses
+    ]
   )
 
   useEffect(() => {
@@ -393,6 +423,76 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       ? getWorktreeOptionId(activeWorktreeId)
       : undefined
 
+  const hasWorkspaceDropTargets = useMemo(
+    () =>
+      groupBy === 'none' ||
+      rows.some((row) => row.type === 'header' && row.key === PINNED_GROUP_KEY),
+    [groupBy, rows]
+  )
+
+  const handleWorkspaceStatusDragOver = useCallback(
+    (event: React.DragEvent, status: WorkspaceStatus) => {
+      if (!hasWorkspaceDragData(event.dataTransfer)) {
+        return
+      }
+      event.preventDefault()
+      event.dataTransfer.dropEffect = 'move'
+      setDragOverStatus(status)
+    },
+    []
+  )
+
+  const handleWorkspaceStatusDragLeave = useCallback((event: React.DragEvent) => {
+    const relatedTarget = event.relatedTarget
+    if (relatedTarget instanceof Node && event.currentTarget.contains(relatedTarget)) {
+      return
+    }
+    setDragOverStatus(null)
+  }, [])
+
+  const handleWorkspacePinDragOver = useCallback((event: React.DragEvent) => {
+    if (!hasWorkspaceDragData(event.dataTransfer)) {
+      return
+    }
+    event.preventDefault()
+    event.dataTransfer.dropEffect = 'move'
+    setPinDragOver(true)
+  }, [])
+
+  const handleWorkspacePinDragLeave = useCallback((event: React.DragEvent) => {
+    const relatedTarget = event.relatedTarget
+    if (relatedTarget instanceof Node && event.currentTarget.contains(relatedTarget)) {
+      return
+    }
+    setPinDragOver(false)
+  }, [])
+
+  const handleWorkspaceStatusDragFinish = useCallback(() => {
+    setDragOverStatus(null)
+    setPinDragOver(false)
+  }, [])
+
+  const handleWorkspaceStatusDrop = useCallback(
+    (event: React.DragEvent, status: WorkspaceStatus) => {
+      const worktreeId = readWorkspaceDragData(event.dataTransfer)
+      if (!worktreeId) {
+        return
+      }
+      event.preventDefault()
+      setDragOverStatus(null)
+      onMoveWorktreeToStatus(worktreeId, status)
+    },
+    [onMoveWorktreeToStatus]
+  )
+
+  useWorkspaceStatusDocumentDrop(
+    scrollRef,
+    onMoveWorktreeToStatus,
+    onPinWorktree,
+    handleWorkspaceStatusDragFinish,
+    hasWorkspaceDropTargets
+  )
+
   return (
     <div
       ref={scrollRef}
@@ -427,6 +527,9 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
             const isDraggingThis =
               repoDrag.state.draggingRepoId !== null &&
               repoDrag.state.draggingRepoId === repoIdForHeader
+            const headerWorkspaceStatus =
+              groupBy === 'none' ? getWorkspaceStatusFromGroupKey(row.key, workspaceStatuses) : null
+            const isPinnedHeader = row.key === PINNED_GROUP_KEY
             return (
               <div
                 key={vItem.key}
@@ -440,16 +543,44 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                   role="button"
                   tabIndex={0}
                   data-repo-header-id={repoIdForHeader}
+                  data-workspace-status-drop-target={headerWorkspaceStatus ? '' : undefined}
+                  data-workspace-status={headerWorkspaceStatus ?? undefined}
+                  data-workspace-pin-drop-target={isPinnedHeader ? '' : undefined}
                   className={cn(
                     'group flex h-7 w-full items-center gap-1.5 pl-3 pr-1 text-left transition-all',
                     'cursor-pointer',
                     isDraggingThis &&
                       'bg-accent/80 ring-1 ring-ring/40 shadow-md rounded-md scale-[1.01]',
+                    headerWorkspaceStatus &&
+                      dragOverStatus === headerWorkspaceStatus &&
+                      'rounded-md bg-sidebar-accent ring-1 ring-sidebar-ring/40',
+                    isPinnedHeader &&
+                      pinDragOver &&
+                      'rounded-md bg-sidebar-accent ring-1 ring-sidebar-ring/40',
                     // First header sits directly under SidebarHeader, which already
                     // supplies its own spacing — only offset secondary group headers.
                     vItem.index !== firstHeaderIndex && 'mt-2',
                     row.repo ? 'overflow-hidden' : row.tone
                   )}
+                  onDragOver={
+                    isPinnedHeader
+                      ? handleWorkspacePinDragOver
+                      : headerWorkspaceStatus
+                        ? (event) => handleWorkspaceStatusDragOver(event, headerWorkspaceStatus)
+                        : undefined
+                  }
+                  onDragLeave={
+                    isPinnedHeader
+                      ? handleWorkspacePinDragLeave
+                      : headerWorkspaceStatus
+                        ? handleWorkspaceStatusDragLeave
+                        : undefined
+                  }
+                  onDrop={
+                    headerWorkspaceStatus
+                      ? (event) => handleWorkspaceStatusDrop(event, headerWorkspaceStatus)
+                      : undefined
+                  }
                   onClick={() => toggleGroup(row.key)}
                   onKeyDown={(e) => {
                     if (e.key === 'Enter' || e.key === ' ') {
@@ -527,6 +658,9 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
             )
           }
 
+          const itemWorkspaceStatus =
+            groupBy === 'none' ? getWorkspaceStatus(row.worktree, workspaceStatuses) : null
+
           return (
             <div
               key={vItem.key}
@@ -536,8 +670,21 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
               aria-current={activeWorktreeId === row.worktree.id ? 'page' : undefined}
               data-index={vItem.index}
               ref={virtualizer.measureElement}
+              data-workspace-status-drop-target={itemWorkspaceStatus ? '' : undefined}
+              data-workspace-status={itemWorkspaceStatus ?? undefined}
               className="absolute left-0 right-0"
               style={{ transform: `translateY(${vItem.start}px)` }}
+              onDragOver={
+                itemWorkspaceStatus
+                  ? (event) => handleWorkspaceStatusDragOver(event, itemWorkspaceStatus)
+                  : undefined
+              }
+              onDragLeave={itemWorkspaceStatus ? handleWorkspaceStatusDragLeave : undefined}
+              onDrop={
+                itemWorkspaceStatus
+                  ? (event) => handleWorkspaceStatusDrop(event, itemWorkspaceStatus)
+                  : undefined
+              }
             >
               <WorktreeCard
                 worktree={row.worktree}
@@ -568,11 +715,13 @@ const WorktreeList = React.memo(function WorktreeList() {
   const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
   const activeWorktreeId = useAppStore((s) => s.activeWorktreeId)
   const groupBy = useAppStore((s) => s.groupBy)
+  const workspaceStatuses = useAppStore((s) => s.workspaceStatuses)
   const sortBy = useAppStore((s) => s.sortBy)
   const showActiveOnly = useAppStore((s) => s.showActiveOnly)
   const hideDefaultBranchWorkspace = useAppStore((s) => s.hideDefaultBranchWorkspace)
   const filterRepoIds = useAppStore((s) => s.filterRepoIds)
   const openModal = useAppStore((s) => s.openModal)
+  const updateWorktreeMeta = useAppStore((s) => s.updateWorktreeMeta)
   const activeView = useAppStore((s) => s.activeView)
   const activeModal = useAppStore((s) => s.activeModal)
   const pendingRevealWorktreeId = useAppStore((s) => s.pendingRevealWorktreeId)
@@ -881,8 +1030,17 @@ const WorktreeList = React.memo(function WorktreeList() {
 
   // Build flat row list for rendering
   const rows: Row[] = useMemo(
-    () => buildRows(groupBy, worktrees, repoMap, prCache, collapsedGroups, repoOrder),
-    [groupBy, worktrees, repoMap, prCache, collapsedGroups, repoOrder]
+    () =>
+      buildRows(
+        groupBy,
+        worktrees,
+        repoMap,
+        prCache,
+        collapsedGroups,
+        repoOrder,
+        workspaceStatuses
+      ),
+    [groupBy, worktrees, repoMap, prCache, collapsedGroups, repoOrder, workspaceStatuses]
   )
   // Why: rows.length alone can stay the same when items migrate between
   // groups (e.g., PR cache loads on restart and a collapsed group absorbs
@@ -1011,6 +1169,28 @@ const WorktreeList = React.memo(function WorktreeList() {
     [openModal]
   )
 
+  const moveWorktreeToStatus = useCallback(
+    (worktreeId: string, status: WorkspaceStatus) => {
+      const current = worktreeMap.get(worktreeId)
+      if (!current || getWorkspaceStatus(current, workspaceStatuses) === status) {
+        return
+      }
+      void updateWorktreeMeta(worktreeId, { workspaceStatus: status })
+    },
+    [updateWorktreeMeta, worktreeMap, workspaceStatuses]
+  )
+
+  const pinWorktree = useCallback(
+    (worktreeId: string) => {
+      const current = worktreeMap.get(worktreeId)
+      if (!current || current.isPinned) {
+        return
+      }
+      void updateWorktreeMeta(worktreeId, { isPinned: true })
+    },
+    [updateWorktreeMeta, worktreeMap]
+  )
+
   // Why: hideDefaultBranchWorkspace is counted as a filter here so the
   // empty-sidebar escape hatch (Clear Filters button below) is reachable when
   // it's the only reason the list is empty — otherwise a user whose only
@@ -1081,6 +1261,9 @@ const WorktreeList = React.memo(function WorktreeList() {
         void reorderReposAction(orderedIds)
       }}
       prCache={prCache}
+      workspaceStatuses={workspaceStatuses}
+      onMoveWorktreeToStatus={moveWorktreeToStatus}
+      onPinWorktree={pinWorktree}
       scrollOffsetRef={sidebarScrollOffsetRef}
     />
   )
diff --git a/src/renderer/src/components/sidebar/use-workspace-status-drop.ts b/src/renderer/src/components/sidebar/use-workspace-status-drop.ts
new file mode 100644
index 00000000000..2dcb4c706dd
--- /dev/null
+++ b/src/renderer/src/components/sidebar/use-workspace-status-drop.ts
@@ -0,0 +1,81 @@
+import { useEffect } from 'react'
+import type React from 'react'
+import type { WorkspaceStatus } from '../../../../shared/types'
+import { hasWorkspaceDragData, readWorkspaceDragData } from './workspace-status'
+
+const WORKSPACE_STATUS_DROP_TARGET = '[data-workspace-status-drop-target]'
+const WORKSPACE_PIN_DROP_TARGET = '[data-workspace-pin-drop-target]'
+
+type MoveWorktreeToStatus = (worktreeId: string, status: WorkspaceStatus) => void
+type PinWorktree = (worktreeId: string) => void
+
+export function useWorkspaceStatusDocumentDrop<T extends HTMLElement>(
+  containerRef: React.RefObject<T | null>,
+  onMoveWorktreeToStatus: MoveWorktreeToStatus,
+  onPinWorktree: PinWorktree,
+  onDragFinish: () => void,
+  enabled = true
+): void {
+  useEffect(() => {
+    if (!enabled) {
+      return
+    }
+
+    const handleDrop = (event: DragEvent): void => {
+      const dataTransfer = event.dataTransfer
+      if (!dataTransfer || !hasWorkspaceDragData(dataTransfer)) {
+        return
+      }
+
+      onDragFinish()
+
+      const container = containerRef.current
+      const target = event.target
+      if (!container || !(target instanceof Element) || !container.contains(target)) {
+        return
+      }
+
+      const pinTarget = target.closest<HTMLElement>(WORKSPACE_PIN_DROP_TARGET)
+      const statusTarget = target.closest<HTMLElement>(WORKSPACE_STATUS_DROP_TARGET)
+      const dropTarget =
+        pinTarget && container.contains(pinTarget)
+          ? pinTarget
+          : statusTarget && container.contains(statusTarget)
+            ? statusTarget
+            : null
+      if (!dropTarget) {
+        return
+      }
+
+      const worktreeId = readWorkspaceDragData(dataTransfer)
+      if (!worktreeId) {
+        return
+      }
+
+      // Why: Electron's preload bridge stops native drops before React sees
+      // them, so board drops commit from this scoped capture listener.
+      event.preventDefault()
+      event.stopPropagation()
+      if (dropTarget === pinTarget) {
+        onPinWorktree(worktreeId)
+        return
+      }
+
+      const status = dropTarget.dataset.workspaceStatus
+      if (status) {
+        onMoveWorktreeToStatus(worktreeId, status)
+      }
+    }
+
+    const handleDragFinish = (): void => {
+      onDragFinish()
+    }
+
+    document.addEventListener('drop', handleDrop, true)
+    document.addEventListener('dragend', handleDragFinish, true)
+    return () => {
+      document.removeEventListener('drop', handleDrop, true)
+      document.removeEventListener('dragend', handleDragFinish, true)
+    }
+  }, [containerRef, enabled, onDragFinish, onMoveWorktreeToStatus, onPinWorktree])
+}
diff --git a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
new file mode 100644
index 00000000000..7dc2e2dacae
--- /dev/null
+++ b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
@@ -0,0 +1,93 @@
+import { useMemo } from 'react'
+import { useShallow } from 'zustand/react/shallow'
+import { useAppStore } from '@/store'
+import { isExplicitAgentStatusFresh } from '@/lib/agent-status'
+import { resolveWorktreeStatus, type WorktreeStatus } from '@/lib/worktree-status'
+import { AGENT_STATUS_STALE_AFTER_MS } from '../../../../shared/agent-status-types'
+import { EMPTY_BROWSER_TABS, EMPTY_TABS } from './WorktreeCardHelpers'
+import {
+  selectLivePtyIdsForWorktree,
+  selectRuntimePaneTitlesForWorktree
+} from './worktree-card-status-inputs'
+
+export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
+  const tabs = useAppStore((s) => s.tabsByWorktree[worktreeId] ?? EMPTY_TABS)
+  const browserTabs = useAppStore((s) => s.browserTabsByWorktree[worktreeId] ?? EMPTY_BROWSER_TABS)
+  const hasNotesSurface = useAppStore((s) =>
+    (s.unifiedTabsByWorktree[worktreeId] ?? []).some((tab) => tab.contentType === 'notes')
+  )
+  const runtimePaneTitlesForWorktree = useAppStore(
+    useShallow((s) => selectRuntimePaneTitlesForWorktree(s, worktreeId))
+  )
+  const ptyIdsForWorktree = useAppStore(
+    useShallow((s) => selectLivePtyIdsForWorktree(s, worktreeId))
+  )
+  const { hasPermission, hasLiveDone, hasRetainedDone } = useAppStore(
+    useShallow((s) => {
+      // Touch the epoch so this selector re-runs when a fresh hook entry
+      // crosses the stale boundary.
+      void s.agentStatusEpoch
+      const wtTabs = s.tabsByWorktree[worktreeId] ?? EMPTY_TABS
+      let perm = false
+      let live = false
+      if (wtTabs.length > 0) {
+        const tabIds = new Set(wtTabs.map((tab) => tab.id))
+        const now = Date.now()
+        for (const [paneKey, entry] of Object.entries(s.agentStatusByPaneKey)) {
+          const sepIdx = paneKey.indexOf(':')
+          if (sepIdx <= 0) {
+            continue
+          }
+          const tabId = paneKey.slice(0, sepIdx)
+          if (!tabIds.has(tabId)) {
+            continue
+          }
+          if (!isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)) {
+            continue
+          }
+          if (entry.state === 'blocked' || entry.state === 'waiting') {
+            perm = true
+          } else if (entry.state === 'done') {
+            live = true
+          }
+        }
+      }
+
+      let retained = false
+      for (const agent of Object.values(s.retainedAgentsByPaneKey)) {
+        if (agent.worktreeId === worktreeId) {
+          retained = true
+          break
+        }
+      }
+      return { hasPermission: perm, hasLiveDone: live, hasRetainedDone: retained }
+    })
+  )
+
+  // Why: compact and detailed cards need the same status-dot semantics:
+  // runtime liveness gates title-derived states, then explicit agent rows can
+  // promote permission/done so the dot matches visible agent state.
+  return useMemo(
+    () =>
+      resolveWorktreeStatus({
+        tabs,
+        browserTabs,
+        ptyIdsByTabId: ptyIdsForWorktree,
+        runtimePaneTitlesByTabId: runtimePaneTitlesForWorktree,
+        hasNotesSurface,
+        hasPermission,
+        hasLiveDone,
+        hasRetainedDone
+      }),
+    [
+      tabs,
+      browserTabs,
+      ptyIdsForWorktree,
+      runtimePaneTitlesForWorktree,
+      hasNotesSurface,
+      hasPermission,
+      hasLiveDone,
+      hasRetainedDone
+    ]
+  )
+}
diff --git a/src/renderer/src/components/sidebar/workspace-status.ts b/src/renderer/src/components/sidebar/workspace-status.ts
new file mode 100644
index 00000000000..79f91afc69a
--- /dev/null
+++ b/src/renderer/src/components/sidebar/workspace-status.ts
@@ -0,0 +1,232 @@
+import type React from 'react'
+import {
+  Ban,
+  Circle,
+  CircleAlert,
+  CircleCheckBig,
+  CircleDashed,
+  CircleDot,
+  CircleEllipsis,
+  CirclePause,
+  CirclePlay,
+  Flag,
+  GitPullRequest,
+  Timer
+} from 'lucide-react'
+import type { WorkspaceStatus, WorkspaceStatusDefinition } from '../../../../shared/types'
+import {
+  DEFAULT_WORKSPACE_STATUS_COLOR_ID,
+  DEFAULT_WORKSPACE_STATUS_ICON_ID,
+  DEFAULT_WORKSPACE_STATUS_ID,
+  DEFAULT_WORKSPACE_STATUSES,
+  WORKSPACE_STATUS_COLOR_IDS,
+  WORKSPACE_STATUS_ICON_IDS,
+  getWorkspaceStatus,
+  getWorkspaceStatusFromGroupKey,
+  getWorkspaceStatusGroupKey,
+  isWorkspaceStatusId
+} from '../../../../shared/workspace-statuses'
+
+export {
+  DEFAULT_WORKSPACE_STATUS_COLOR_ID,
+  DEFAULT_WORKSPACE_STATUS_ICON_ID,
+  DEFAULT_WORKSPACE_STATUS_ID,
+  DEFAULT_WORKSPACE_STATUSES,
+  WORKSPACE_STATUS_COLOR_IDS,
+  WORKSPACE_STATUS_ICON_IDS,
+  getWorkspaceStatus,
+  getWorkspaceStatusFromGroupKey,
+  getWorkspaceStatusGroupKey,
+  isWorkspaceStatusId
+}
+
+export const WORKSPACE_STATUS_DRAG_TYPE = 'application/x-orca-worktree-id'
+
+type WorkspaceStatusColorOption = {
+  id: string
+  label: string
+  tone: string
+  swatch: string
+  border: string
+  laneTint: string
+}
+
+type WorkspaceStatusIconOption = {
+  id: string
+  label: string
+  icon: React.ComponentType<{ className?: string }>
+}
+
+export const WORKSPACE_STATUS_COLOR_OPTIONS: WorkspaceStatusColorOption[] = [
+  {
+    id: 'neutral',
+    label: 'Neutral',
+    tone: 'text-muted-foreground',
+    swatch: 'bg-muted-foreground',
+    border: 'border-t-muted-foreground/45',
+    laneTint: 'bg-background/55'
+  },
+  {
+    id: 'blue',
+    label: 'Blue',
+    tone: 'text-blue-600 dark:text-blue-300',
+    swatch: 'bg-blue-500',
+    border: 'border-t-blue-500/70',
+    laneTint: 'bg-blue-500/[0.04]'
+  },
+  {
+    id: 'sky',
+    label: 'Sky',
+    tone: 'text-sky-600 dark:text-sky-300',
+    swatch: 'bg-sky-500',
+    border: 'border-t-sky-500/70',
+    laneTint: 'bg-sky-500/[0.04]'
+  },
+  {
+    id: 'violet',
+    label: 'Violet',
+    tone: 'text-violet-600 dark:text-violet-300',
+    swatch: 'bg-violet-500',
+    border: 'border-t-violet-500/70',
+    laneTint: 'bg-violet-500/[0.04]'
+  },
+  {
+    id: 'amber',
+    label: 'Amber',
+    tone: 'text-amber-700 dark:text-amber-200',
+    swatch: 'bg-amber-500',
+    border: 'border-t-amber-500/70',
+    laneTint: 'bg-amber-500/[0.04]'
+  },
+  {
+    id: 'emerald',
+    label: 'Emerald',
+    tone: 'text-emerald-700 dark:text-emerald-200',
+    swatch: 'bg-emerald-500',
+    border: 'border-t-emerald-500/70',
+    laneTint: 'bg-emerald-500/[0.04]'
+  },
+  {
+    id: 'rose',
+    label: 'Rose',
+    tone: 'text-rose-600 dark:text-rose-300',
+    swatch: 'bg-rose-500',
+    border: 'border-t-rose-500/70',
+    laneTint: 'bg-rose-500/[0.04]'
+  },
+  {
+    id: 'zinc',
+    label: 'Zinc',
+    tone: 'text-zinc-600 dark:text-zinc-300',
+    swatch: 'bg-zinc-500',
+    border: 'border-t-zinc-500/70',
+    laneTint: 'bg-zinc-500/[0.04]'
+  }
+]
+
+export const WORKSPACE_STATUS_ICON_OPTIONS: WorkspaceStatusIconOption[] = [
+  { id: 'circle', label: 'Circle', icon: Circle },
+  { id: 'circle-dot', label: 'Dot', icon: CircleDot },
+  { id: 'circle-dashed', label: 'Dashed', icon: CircleDashed },
+  { id: 'circle-ellipsis', label: 'Waiting', icon: CircleEllipsis },
+  { id: 'git-pull-request', label: 'Review', icon: GitPullRequest },
+  { id: 'timer', label: 'Timer', icon: Timer },
+  { id: 'flag', label: 'Flag', icon: Flag },
+  { id: 'circle-alert', label: 'Alert', icon: CircleAlert },
+  { id: 'circle-pause', label: 'Paused', icon: CirclePause },
+  { id: 'circle-play', label: 'Play', icon: CirclePlay },
+  { id: 'circle-check', label: 'Done', icon: CircleCheckBig },
+  { id: 'ban', label: 'Blocked', icon: Ban }
+]
+
+const FALLBACK_COLOR_OPTION: WorkspaceStatusColorOption = WORKSPACE_STATUS_COLOR_OPTIONS[0] ?? {
+  id: DEFAULT_WORKSPACE_STATUS_COLOR_ID,
+  label: 'Neutral',
+  tone: 'text-muted-foreground',
+  swatch: 'bg-muted-foreground',
+  border: 'border-t-muted-foreground/45',
+  laneTint: 'bg-background/55'
+}
+
+const FALLBACK_ICON_OPTION: WorkspaceStatusIconOption = WORKSPACE_STATUS_ICON_OPTIONS[1] ?? {
+  id: DEFAULT_WORKSPACE_STATUS_ICON_ID,
+  label: 'Dot',
+  icon: CircleDot
+}
+
+const DEFAULT_STATUS_VISUALS: Record<
+  string,
+  {
+    color: string
+    icon: string
+  }
+> = {
+  todo: {
+    color: 'neutral',
+    icon: 'circle'
+  },
+  'in-progress': {
+    color: 'blue',
+    icon: 'circle-dot'
+  },
+  'in-review': {
+    color: 'violet',
+    icon: 'git-pull-request'
+  },
+  completed: {
+    color: 'emerald',
+    icon: 'circle-check'
+  }
+}
+
+export function getWorkspaceStatusVisualMeta(status: WorkspaceStatus | WorkspaceStatusDefinition): {
+  tone: string
+  swatch: string
+  border: string
+  laneTint: string
+  icon: React.ComponentType<{ className?: string }>
+} {
+  const statusId = typeof status === 'string' ? status : status.id
+  const visual = typeof status === 'string' ? DEFAULT_STATUS_VISUALS[status] : status
+  const colorId = visual?.color ?? DEFAULT_STATUS_VISUALS[statusId]?.color
+  const iconId = visual?.icon ?? DEFAULT_STATUS_VISUALS[statusId]?.icon
+  const color =
+    WORKSPACE_STATUS_COLOR_OPTIONS.find((option) => option.id === colorId) ??
+    WORKSPACE_STATUS_COLOR_OPTIONS.find(
+      (option) => option.id === DEFAULT_WORKSPACE_STATUS_COLOR_ID
+    ) ??
+    FALLBACK_COLOR_OPTION
+  const icon =
+    WORKSPACE_STATUS_ICON_OPTIONS.find((option) => option.id === iconId) ??
+    WORKSPACE_STATUS_ICON_OPTIONS.find(
+      (option) => option.id === DEFAULT_WORKSPACE_STATUS_ICON_ID
+    ) ??
+    FALLBACK_ICON_OPTION
+
+  return {
+    tone: color.tone,
+    swatch: color.swatch,
+    border: color.border,
+    laneTint: color.laneTint,
+    icon: icon.icon
+  }
+}
+
+export function writeWorkspaceDragData(dataTransfer: DataTransfer, worktreeId: string): void {
+  dataTransfer.effectAllowed = 'move'
+  dataTransfer.setData(WORKSPACE_STATUS_DRAG_TYPE, worktreeId)
+  dataTransfer.setData('text/plain', worktreeId)
+}
+
+export function readWorkspaceDragData(dataTransfer: DataTransfer): string | null {
+  const typed = dataTransfer.getData(WORKSPACE_STATUS_DRAG_TYPE)
+  if (typed) {
+    return typed
+  }
+  return dataTransfer.getData('text/plain') || null
+}
+
+export function hasWorkspaceDragData(dataTransfer: DataTransfer): boolean {
+  const types = Array.from(dataTransfer.types)
+  return types.includes(WORKSPACE_STATUS_DRAG_TYPE) || types.includes('text/plain')
+}
diff --git a/src/renderer/src/components/sidebar/worktree-list-groups.test.ts b/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
index 39d8a3d5b84..2f2c576520e 100644
--- a/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
+++ b/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
@@ -57,9 +57,14 @@ describe('buildRows with pinned worktrees', () => {
     expect(rows[1]).toMatchObject({ type: 'item', worktree: { id: 'wt-pinned' } })
   })
 
-  it('emits an All header between pinned and unpinned in groupBy none', () => {
+  it('emits status headers for unpinned worktrees in groupBy none', () => {
     const rows = buildRows('none', [unpinned1, pinned, unpinned2], repoMap, null, new Set())
-    expect(rows[2]).toMatchObject({ type: 'header', key: 'all', label: 'All', count: 2 })
+    expect(rows[2]).toMatchObject({
+      type: 'header',
+      key: 'workspace-status:in-progress',
+      label: 'In progress',
+      count: 2
+    })
     expect(rows[3]).toMatchObject({ type: 'item', worktree: { id: 'wt-1' } })
     expect(rows[4]).toMatchObject({ type: 'item', worktree: { id: 'wt-2' } })
   })
@@ -76,22 +81,36 @@ describe('buildRows with pinned worktrees', () => {
     }
   })
 
-  it('does not emit pinned section when no worktrees are pinned', () => {
+  it('keeps an empty pinned drop section above statuses in groupBy none', () => {
     const rows = buildRows('none', [unpinned1, unpinned2], repoMap, null, new Set())
-    expect(rows.every((r) => r.type === 'item')).toBe(true)
+    expect(rows[0]).toMatchObject({
+      type: 'header',
+      key: 'pinned',
+      label: 'Pinned',
+      count: 0
+    })
+    expect(rows[1]).toMatchObject({
+      type: 'header',
+      key: 'workspace-status:in-progress',
+      label: 'In progress',
+      count: 2
+    })
+    expect(rows[2]).toMatchObject({ type: 'item', worktree: { id: 'wt-1' } })
+    expect(rows[3]).toMatchObject({ type: 'item', worktree: { id: 'wt-2' } })
   })
 
   it('collapses pinned group when in collapsedGroups', () => {
     const rows = buildRows('none', [pinned, unpinned1], repoMap, null, new Set(['pinned']))
     expect(rows[0]).toMatchObject({ type: 'header', key: 'pinned' })
-    expect(rows[1]).toMatchObject({ type: 'header', key: 'all' })
+    expect(rows[1]).toMatchObject({ type: 'header', key: 'workspace-status:in-progress' })
     expect(rows[2]).toMatchObject({ type: 'item', worktree: { id: 'wt-1' } })
   })
 
-  it('does not emit All header when all worktrees are pinned', () => {
+  it('does not emit empty status sections when all worktrees are pinned', () => {
     const allPinned = { ...unpinned1, isPinned: true }
     const rows = buildRows('none', [pinned, allPinned], repoMap, null, new Set())
-    expect(rows.some((r) => r.type === 'header' && r.key === 'all')).toBe(false)
+    expect(rows.filter((r) => r.type === 'header')).toHaveLength(1)
+    expect(rows[0]).toMatchObject({ type: 'header', key: 'pinned', count: 2 })
   })
 
   it('preserves repo display casing in group labels', () => {
@@ -135,6 +154,49 @@ describe('buildRows with pinned worktrees', () => {
     })
     expect(rows[1]).toMatchObject({ type: 'item', worktree: { id: folderWorktree.id } })
   })
+
+  it('emits assigned workspace statuses as sections in groupBy none', () => {
+    const review = { ...worktree, id: 'wt-review', workspaceStatus: 'in-review' as const }
+    const rows = buildRows('none', [review], repoMap, null, new Set())
+
+    expect(
+      rows
+        .filter((r) => r.type === 'header')
+        .map((r) => ({ key: r.key, label: r.label, count: r.count }))
+    ).toEqual([
+      { key: 'pinned', label: 'Pinned', count: 0 },
+      { key: 'workspace-status:in-review', label: 'In review', count: 1 }
+    ])
+  })
+
+  it('uses customized workspace status labels and order', () => {
+    const customStatuses = [
+      { id: 'blocked', label: 'Blocked' },
+      { id: 'todo', label: 'Ready' },
+      { id: 'in-progress', label: 'Doing' }
+    ]
+    const blocked = { ...worktree, id: 'wt-blocked', workspaceStatus: 'blocked' }
+    const doing = { ...worktree, id: 'wt-doing', workspaceStatus: 'in-progress' }
+    const rows = buildRows(
+      'none',
+      [doing, blocked],
+      repoMap,
+      null,
+      new Set(),
+      undefined,
+      customStatuses
+    )
+
+    expect(
+      rows
+        .filter((r) => r.type === 'header')
+        .map((r) => ({ key: r.key, label: r.label, count: r.count }))
+    ).toEqual([
+      { key: 'pinned', label: 'Pinned', count: 0 },
+      { key: 'workspace-status:blocked', label: 'Blocked', count: 1 },
+      { key: 'workspace-status:in-progress', label: 'Doing', count: 1 }
+    ])
+  })
 })
 
 describe('buildRows repo grouping order', () => {
diff --git a/src/renderer/src/components/sidebar/worktree-list-groups.ts b/src/renderer/src/components/sidebar/worktree-list-groups.ts
index 088624082df..50e2d645719 100644
--- a/src/renderer/src/components/sidebar/worktree-list-groups.ts
+++ b/src/renderer/src/components/sidebar/worktree-list-groups.ts
@@ -1,18 +1,19 @@
-import {
-  CircleCheckBig,
-  CircleDot,
-  CircleX,
-  Folder,
-  GitPullRequest,
-  LayoutList,
-  Pin
-} from 'lucide-react'
+import { CircleCheckBig, CircleDot, CircleX, Folder, GitPullRequest, Pin } from 'lucide-react'
 import type React from 'react'
-import type { Repo, Worktree } from '../../../../shared/types'
+import type { Repo, Worktree, WorkspaceStatusDefinition } from '../../../../shared/types'
 import { branchName } from '@/lib/git-utils'
+import {
+  getWorkspaceStatus,
+  getWorkspaceStatusFromGroupKey,
+  getWorkspaceStatusGroupKey,
+  getWorkspaceStatusVisualMeta
+} from './workspace-status'
+import { cloneDefaultWorkspaceStatuses } from '../../../../shared/workspace-statuses'
 
 export { branchName }
 
+export type WorktreeGroupBy = 'none' | 'repo' | 'pr-status'
+
 export type GroupHeaderRow = {
   type: 'header'
   key: string
@@ -73,14 +74,6 @@ export const PINNED_GROUP_META = {
   icon: Pin
 } as const
 
-export const ALL_GROUP_KEY = 'all'
-
-export const ALL_GROUP_META = {
-  label: 'All',
-  tone: 'text-foreground',
-  icon: LayoutList
-} as const
-
 export function getPRGroupKey(
   worktree: Worktree,
   repoMap: Map<string, Repo>,
@@ -118,10 +111,11 @@ function emitPinnedGroup(
   worktrees: Worktree[],
   repoMap: Map<string, Repo>,
   collapsedGroups: Set<string>,
-  result: Row[]
+  result: Row[],
+  force = false
 ): Set<string> {
   const pinned = worktrees.filter((w) => w.isPinned)
-  if (pinned.length === 0) {
+  if (pinned.length === 0 && !force) {
     return new Set()
   }
 
@@ -146,41 +140,19 @@ function emitPinnedGroup(
  * Extracted here to keep WorktreeList.tsx under the line-count lint limit.
  */
 export function buildRows(
-  groupBy: 'none' | 'repo' | 'pr-status',
+  groupBy: WorktreeGroupBy,
   worktrees: Worktree[],
   repoMap: Map<string, Repo>,
   prCache: Record<string, unknown> | null,
   collapsedGroups: Set<string>,
-  repoOrder?: Map<string, number>
+  repoOrder?: Map<string, number>,
+  workspaceStatuses: readonly WorkspaceStatusDefinition[] = cloneDefaultWorkspaceStatuses()
 ): Row[] {
   const result: Row[] = []
 
-  const pinnedIds = emitPinnedGroup(worktrees, repoMap, collapsedGroups, result)
+  const pinnedIds = emitPinnedGroup(worktrees, repoMap, collapsedGroups, result, groupBy === 'none')
   const unpinned = pinnedIds.size > 0 ? worktrees.filter((w) => !pinnedIds.has(w.id)) : worktrees
 
-  if (groupBy === 'none') {
-    // Without an "All" header, the unpinned block is visually indistinguishable
-    // from a continuation of the Pinned section — so when pinned items exist,
-    // mark the boundary with a sibling header that mirrors the Pinned one.
-    if (pinnedIds.size > 0 && unpinned.length > 0) {
-      result.push({
-        type: 'header',
-        key: ALL_GROUP_KEY,
-        label: ALL_GROUP_META.label,
-        count: unpinned.length,
-        tone: ALL_GROUP_META.tone,
-        icon: ALL_GROUP_META.icon
-      })
-      if (collapsedGroups.has(ALL_GROUP_KEY)) {
-        return result
-      }
-    }
-    for (const w of unpinned) {
-      result.push({ type: 'item', worktree: w, repo: repoMap.get(w.repoId) })
-    }
-    return result
-  }
-
   const grouped = new Map<string, { label: string; items: Worktree[]; repo?: Repo }>()
   for (const w of unpinned) {
     let key: string
@@ -190,6 +162,11 @@ export function buildRows(
       repo = repoMap.get(w.repoId)
       key = `repo:${w.repoId}`
       label = repo?.displayName ?? 'Unknown'
+    } else if (groupBy === 'none') {
+      const workspaceStatus = getWorkspaceStatus(w, workspaceStatuses)
+      key = getWorkspaceStatusGroupKey(workspaceStatus)
+      label =
+        workspaceStatuses.find((status) => status.id === workspaceStatus)?.label ?? workspaceStatus
     } else {
       const prGroup = getPRGroupKey(w, repoMap, prCache)
       key = `pr:${prGroup}`
@@ -210,6 +187,17 @@ export function buildRows(
         orderedGroups.push([key, group])
       }
     }
+  } else if (groupBy === 'none') {
+    // Why: the old "All" grouping now organizes workspaces by user status.
+    // Keep the sidebar compact by rendering only sections that contain cards;
+    // the board drawer is the wider all-lanes drag target.
+    for (const status of workspaceStatuses) {
+      const key = getWorkspaceStatusGroupKey(status.id)
+      const group = grouped.get(key)
+      if (group) {
+        orderedGroups.push([key, group])
+      }
+    }
   } else {
     // Why: header order must follow the canonical state.repos array order, not
     // first-encounter from the smart-sorted worktree stream — otherwise sorting
@@ -249,18 +237,35 @@ export function buildRows(
             icon: REPO_GROUP_META.icon,
             repo
           }
-        : (() => {
-            const prGroup = key.replace(/^pr:/, '') as PRGroupKey
-            const meta = PR_GROUP_META[prGroup]
-            return {
-              type: 'header' as const,
-              key,
-              label: meta.label,
-              count: group.items.length,
-              tone: meta.tone,
-              icon: meta.icon
-            }
-          })()
+        : groupBy === 'none'
+          ? (() => {
+              const workspaceStatus =
+                getWorkspaceStatusFromGroupKey(key, workspaceStatuses) ??
+                workspaceStatuses[0]?.id ??
+                'in-progress'
+              const definition = workspaceStatuses.find((status) => status.id === workspaceStatus)
+              const meta = getWorkspaceStatusVisualMeta(definition ?? workspaceStatus)
+              return {
+                type: 'header' as const,
+                key,
+                label: definition?.label ?? workspaceStatus,
+                count: group.items.length,
+                tone: meta.tone,
+                icon: meta.icon
+              }
+            })()
+          : (() => {
+              const prGroup = key.replace(/^pr:/, '') as PRGroupKey
+              const meta = PR_GROUP_META[prGroup]
+              return {
+                type: 'header' as const,
+                key,
+                label: meta.label,
+                count: group.items.length,
+                tone: meta.tone,
+                icon: meta.icon
+              }
+            })()
 
     result.push(header)
     if (!isCollapsed) {
@@ -274,13 +279,14 @@ export function buildRows(
 }
 
 export function getGroupKeyForWorktree(
-  groupBy: 'none' | 'repo' | 'pr-status',
+  groupBy: WorktreeGroupBy,
   worktree: Worktree,
   repoMap: Map<string, Repo>,
-  prCache: Record<string, unknown> | null
+  prCache: Record<string, unknown> | null,
+  workspaceStatuses: readonly WorkspaceStatusDefinition[] = cloneDefaultWorkspaceStatuses()
 ): string | null {
   if (groupBy === 'none') {
-    return null
+    return getWorkspaceStatusGroupKey(getWorkspaceStatus(worktree, workspaceStatuses))
   }
   if (groupBy === 'repo') {
     return `repo:${worktree.repoId}`
diff --git a/src/renderer/src/components/ui/sheet.tsx b/src/renderer/src/components/ui/sheet.tsx
index 1d26d4ac3ce..3e734b9294c 100644
--- a/src/renderer/src/components/ui/sheet.tsx
+++ b/src/renderer/src/components/ui/sheet.tsx
@@ -68,15 +68,19 @@ function SheetContent({
   children,
   side = 'right',
   showCloseButton = true,
+  overlayClassName,
+  overlayStyle,
   style,
   ...props
 }: React.ComponentProps<typeof SheetPrimitive.Content> &
   VariantProps<typeof sheetContentVariants> & {
     showCloseButton?: boolean
+    overlayClassName?: string
+    overlayStyle?: React.CSSProperties
   }) {
   return (
     <SheetPortal>
-      <SheetOverlay />
+      <SheetOverlay className={overlayClassName} style={overlayStyle} />
       <SheetPrimitive.Content
         data-slot="sheet-content"
         className={cn(sheetContentVariants({ side }), className)}
diff --git a/src/renderer/src/store/slices/ui.test.ts b/src/renderer/src/store/slices/ui.test.ts
index ce28fbca880..ac0bbef2148 100644
--- a/src/renderer/src/store/slices/ui.test.ts
+++ b/src/renderer/src/store/slices/ui.test.ts
@@ -116,6 +116,24 @@ describe('createUISlice hydratePersistedUI', () => {
     expect(store.getState().hideDefaultBranchWorkspace).toBe(true)
   })
 
+  it('restores compact workspace board mode only from an explicit true', () => {
+    const store = createUIStore()
+
+    store.getState().hydratePersistedUI(
+      makePersistedUI({
+        workspaceBoardCompact: true
+      })
+    )
+    expect(store.getState().workspaceBoardCompact).toBe(true)
+
+    store.getState().hydratePersistedUI(
+      makePersistedUI({
+        workspaceBoardCompact: 'yes' as unknown as boolean
+      })
+    )
+    expect(store.getState().workspaceBoardCompact).toBe(false)
+  })
+
   it('hydrates a valid Kagi session link', () => {
     const store = createUIStore()
 
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index f9de8d4140b..e807ec3a67a 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -12,6 +12,7 @@ import type {
   TaskViewPresetId,
   TuiAgent,
   UpdateStatus,
+  WorkspaceStatusDefinition,
   WorktreeCardProperty
 } from '../../../../shared/types'
 import { PET_SIZE_DEFAULT, PET_SIZE_MAX, PET_SIZE_MIN } from '../../../../shared/types'
@@ -20,6 +21,12 @@ import {
   DEFAULT_STATUS_BAR_ITEMS,
   DEFAULT_WORKTREE_CARD_PROPERTIES
 } from '../../../../shared/constants'
+import {
+  clampWorkspaceBoardOpacity,
+  cloneDefaultWorkspaceStatuses,
+  normalizeWorkspaceBoardCompact,
+  normalizeWorkspaceStatuses
+} from '../../../../shared/workspace-statuses'
 import { normalizeKagiSessionLink } from '../../../../shared/browser-url'
 import type { OrcaHookScriptKind } from '../../lib/orca-hook-trust'
 import { DEFAULT_PET_ID, isBundledPetId } from '../../components/pet/pet-models'
@@ -308,6 +315,12 @@ export type UISlice = {
   toggleCollapsedGroup: (key: string) => void
   worktreeCardProperties: WorktreeCardProperty[]
   toggleWorktreeCardProperty: (prop: WorktreeCardProperty) => void
+  workspaceStatuses: WorkspaceStatusDefinition[]
+  setWorkspaceStatuses: (statuses: WorkspaceStatusDefinition[]) => void
+  workspaceBoardOpacity: number
+  setWorkspaceBoardOpacity: (opacity: number) => void
+  workspaceBoardCompact: boolean
+  setWorkspaceBoardCompact: (compact: boolean) => void
   statusBarItems: StatusBarItem[]
   toggleStatusBarItem: (item: StatusBarItem) => void
   statusBarVisible: boolean
@@ -676,6 +689,27 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
       return { worktreeCardProperties: updated }
     }),
 
+  workspaceStatuses: cloneDefaultWorkspaceStatuses(),
+  setWorkspaceStatuses: (statuses) => {
+    const normalized = normalizeWorkspaceStatuses(statuses)
+    window.api.ui.set({ workspaceStatuses: normalized }).catch(console.error)
+    set({ workspaceStatuses: normalized })
+  },
+
+  workspaceBoardOpacity: 1,
+  setWorkspaceBoardOpacity: (opacity) => {
+    const clamped = clampWorkspaceBoardOpacity(opacity)
+    window.api.ui.set({ workspaceBoardOpacity: clamped }).catch(console.error)
+    set({ workspaceBoardOpacity: clamped })
+  },
+
+  workspaceBoardCompact: false,
+  setWorkspaceBoardCompact: (compact) => {
+    const normalized = normalizeWorkspaceBoardCompact(compact)
+    window.api.ui.set({ workspaceBoardCompact: normalized }).catch(console.error)
+    set({ workspaceBoardCompact: normalized })
+  },
+
   statusBarItems: [...DEFAULT_STATUS_BAR_ITEMS],
   toggleStatusBarItem: (item) =>
     set((s) => {
@@ -815,6 +849,9 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         uiZoomLevel: ui.uiZoomLevel ?? 0,
         editorFontZoomLevel: ui.editorFontZoomLevel ?? 0,
         worktreeCardProperties: ui.worktreeCardProperties ?? [...DEFAULT_WORKTREE_CARD_PROPERTIES],
+        workspaceStatuses: normalizeWorkspaceStatuses(ui.workspaceStatuses),
+        workspaceBoardOpacity: clampWorkspaceBoardOpacity(ui.workspaceBoardOpacity),
+        workspaceBoardCompact: normalizeWorkspaceBoardCompact(ui.workspaceBoardCompact),
         statusBarItems: migrateStatusBarItems(ui.statusBarItems),
         statusBarVisible: ui.statusBarVisible ?? true,
         // Why: absent → true so existing users see the pet the first time
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 9d738dea8c6..32b2606864f 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -48,6 +48,7 @@ function areWorktreesEqual(current: Worktree[] | undefined, next: Worktree[]): b
       worktree.isPinned === candidate.isPinned &&
       worktree.sortOrder === candidate.sortOrder &&
       worktree.lastActivityAt === candidate.lastActivityAt &&
+      worktree.workspaceStatus === candidate.workspaceStatus &&
       worktree.createdWithAgent === candidate.createdWithAgent &&
       worktree.baseRef === candidate.baseRef &&
       worktree.pushTarget?.remoteName === candidate.pushTarget?.remoteName &&
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 6f6f33fa764..1c2de304c7a 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -13,6 +13,7 @@ import type {
 import { DEFAULT_TERMINAL_FONT_WEIGHT } from './terminal-fonts'
 import { getDefaultTerminalQuickCommands } from './terminal-quick-commands'
 import type { VoiceSettings } from './speech-types'
+import { cloneDefaultWorkspaceStatuses } from './workspace-statuses'
 
 export const SCHEMA_VERSION = 1
 export const DEFAULT_APP_FONT_FAMILY = 'Geist'
@@ -324,6 +325,9 @@ export function getDefaultUIState(): PersistedUIState {
     uiZoomLevel: 0,
     editorFontZoomLevel: 0,
     worktreeCardProperties: [...DEFAULT_WORKTREE_CARD_PROPERTIES],
+    workspaceStatuses: cloneDefaultWorkspaceStatuses(),
+    workspaceBoardOpacity: 1,
+    workspaceBoardCompact: false,
     statusBarItems: [...DEFAULT_STATUS_BAR_ITEMS],
     statusBarVisible: true,
     dismissedUpdateVersion: null,
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 0f9624a10c4..7430e34428e 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -106,6 +106,15 @@ export type GitWorktreeInfo = {
 }
 
 // ─── Worktree (app-level, enriched) ──────────────────────────────────
+export type WorkspaceStatus = string
+
+export type WorkspaceStatusDefinition = {
+  id: WorkspaceStatus
+  label: string
+  color?: string
+  icon?: string
+}
+
 export type Worktree = {
   id: string // `${repoId}::${path}`
   repoId: string
@@ -147,6 +156,7 @@ export type Worktree = {
   baseRef?: string
   /** Remote/branch Orca should publish review commits to when it created this worktree. */
   pushTarget?: GitPushTarget
+  workspaceStatus?: WorkspaceStatus
   diffComments?: DiffComment[]
 } & GitWorktreeInfo
 
@@ -183,6 +193,8 @@ export type WorktreeMeta = {
   baseRef?: string
   /** See {@link Worktree.pushTarget}. Persisted so refreshed worktree lists keep the target. */
   pushTarget?: GitPushTarget
+  /** User-assigned workspace board status for manual sidebar organization. */
+  workspaceStatus?: WorkspaceStatus
   diffComments?: DiffComment[]
 }
 
@@ -1571,6 +1583,9 @@ export type PersistedUIState = {
   uiZoomLevel: number
   editorFontZoomLevel: number
   worktreeCardProperties: WorktreeCardProperty[]
+  workspaceStatuses?: WorkspaceStatusDefinition[]
+  workspaceBoardOpacity?: number
+  workspaceBoardCompact?: boolean
   statusBarItems: StatusBarItem[]
   statusBarVisible: boolean
   dismissedUpdateVersion: string | null
diff --git a/src/shared/workspace-statuses.ts b/src/shared/workspace-statuses.ts
new file mode 100644
index 00000000000..7163d661a5c
--- /dev/null
+++ b/src/shared/workspace-statuses.ts
@@ -0,0 +1,201 @@
+import type { Worktree, WorkspaceStatus, WorkspaceStatusDefinition } from './types'
+
+const WORKSPACE_STATUS_GROUP_PREFIX = 'workspace-status:'
+const MAX_STATUS_LABEL_LENGTH = 32
+const MAX_WORKSPACE_STATUSES = 12
+
+export const DEFAULT_WORKSPACE_STATUS_ID: WorkspaceStatus = 'in-progress'
+export const DEFAULT_WORKSPACE_STATUS_COLOR_ID = 'neutral'
+export const DEFAULT_WORKSPACE_STATUS_ICON_ID = 'circle-dot'
+
+export const WORKSPACE_STATUS_COLOR_IDS = [
+  'neutral',
+  'blue',
+  'sky',
+  'violet',
+  'amber',
+  'emerald',
+  'rose',
+  'zinc'
+] as const
+
+export const WORKSPACE_STATUS_ICON_IDS = [
+  'circle',
+  'circle-dot',
+  'circle-dashed',
+  'circle-ellipsis',
+  'git-pull-request',
+  'timer',
+  'flag',
+  'circle-alert',
+  'circle-pause',
+  'circle-play',
+  'circle-check',
+  'ban'
+] as const
+
+const DEFAULT_STATUS_VISUALS: Record<string, { color: string; icon: string }> = {
+  todo: { color: 'neutral', icon: 'circle' },
+  'in-progress': { color: 'blue', icon: 'circle-dot' },
+  'in-review': { color: 'violet', icon: 'git-pull-request' },
+  completed: { color: 'emerald', icon: 'circle-check' }
+}
+
+export const DEFAULT_WORKSPACE_STATUSES = [
+  { id: 'todo', label: 'Todo', color: 'neutral', icon: 'circle' },
+  { id: 'in-progress', label: 'In progress', color: 'blue', icon: 'circle-dot' },
+  { id: 'in-review', label: 'In review', color: 'violet', icon: 'git-pull-request' },
+  { id: 'completed', label: 'Completed', color: 'emerald', icon: 'circle-check' }
+] as const satisfies readonly WorkspaceStatusDefinition[]
+
+export function cloneDefaultWorkspaceStatuses(): WorkspaceStatusDefinition[] {
+  return DEFAULT_WORKSPACE_STATUSES.map((status) => ({ ...status }))
+}
+
+function sanitizeWorkspaceStatusLabel(value: unknown, fallback: string): string {
+  if (typeof value !== 'string') {
+    return fallback
+  }
+  const trimmed = value.trim().replace(/\s+/g, ' ')
+  return trimmed ? trimmed.slice(0, MAX_STATUS_LABEL_LENGTH) : fallback
+}
+
+function slugWorkspaceStatusLabel(label: string): string {
+  const slug = label
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug || 'status'
+}
+
+function sanitizeWorkspaceStatusId(value: unknown, fallbackLabel: string): WorkspaceStatus {
+  if (typeof value !== 'string') {
+    return slugWorkspaceStatusLabel(fallbackLabel)
+  }
+  const trimmed = value.trim().toLowerCase()
+  if (!trimmed) {
+    return slugWorkspaceStatusLabel(fallbackLabel)
+  }
+  return trimmed.replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'status'
+}
+
+function sanitizeWorkspaceStatusColor(value: unknown, statusId: string, index: number): string {
+  if (typeof value === 'string' && WORKSPACE_STATUS_COLOR_IDS.some((id) => id === value)) {
+    return value
+  }
+  const defaultVisual = DEFAULT_STATUS_VISUALS[statusId]
+  if (defaultVisual) {
+    return defaultVisual.color
+  }
+  return WORKSPACE_STATUS_COLOR_IDS[index % WORKSPACE_STATUS_COLOR_IDS.length]
+}
+
+function sanitizeWorkspaceStatusIcon(value: unknown, statusId: string): string {
+  if (typeof value === 'string' && WORKSPACE_STATUS_ICON_IDS.some((id) => id === value)) {
+    return value
+  }
+  return DEFAULT_STATUS_VISUALS[statusId]?.icon ?? DEFAULT_WORKSPACE_STATUS_ICON_ID
+}
+
+export function makeWorkspaceStatusId(
+  label: string,
+  existingStatuses: readonly WorkspaceStatusDefinition[]
+): WorkspaceStatus {
+  const base = slugWorkspaceStatusLabel(label)
+  const existingIds = new Set(existingStatuses.map((status) => status.id))
+  if (!existingIds.has(base)) {
+    return base
+  }
+  for (let index = 2; index < 100; index += 1) {
+    const candidate = `${base}-${index}`
+    if (!existingIds.has(candidate)) {
+      return candidate
+    }
+  }
+  return `status-${Date.now().toString(36)}`
+}
+
+export function normalizeWorkspaceStatuses(value: unknown): WorkspaceStatusDefinition[] {
+  if (!Array.isArray(value)) {
+    return cloneDefaultWorkspaceStatuses()
+  }
+
+  const statuses: WorkspaceStatusDefinition[] = []
+  const usedIds = new Set<string>()
+  for (const rawStatus of value.slice(0, MAX_WORKSPACE_STATUSES)) {
+    if (!rawStatus || typeof rawStatus !== 'object' || Array.isArray(rawStatus)) {
+      continue
+    }
+    const raw = rawStatus as Record<string, unknown>
+    const fallbackLabel = `Status ${statuses.length + 1}`
+    const label = sanitizeWorkspaceStatusLabel(raw.label, fallbackLabel)
+    let id = sanitizeWorkspaceStatusId(raw.id, label)
+    if (usedIds.has(id)) {
+      id = makeWorkspaceStatusId(label, statuses)
+    }
+    usedIds.add(id)
+    statuses.push({
+      id,
+      label,
+      color: sanitizeWorkspaceStatusColor(raw.color, id, statuses.length),
+      icon: sanitizeWorkspaceStatusIcon(raw.icon, id)
+    })
+  }
+
+  return statuses.length > 0 ? statuses : cloneDefaultWorkspaceStatuses()
+}
+
+export function clampWorkspaceBoardOpacity(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return 1
+  }
+  return Math.min(1, Math.max(0.2, Math.round(value * 100) / 100))
+}
+
+export function normalizeWorkspaceBoardCompact(value: unknown): boolean {
+  return value === true
+}
+
+export function isWorkspaceStatusId(
+  value: string,
+  statuses: readonly WorkspaceStatusDefinition[]
+): value is WorkspaceStatus {
+  return statuses.some((status) => status.id === value)
+}
+
+export function getDefaultWorkspaceStatusId(
+  statuses: readonly WorkspaceStatusDefinition[]
+): WorkspaceStatus {
+  return statuses.some((status) => status.id === DEFAULT_WORKSPACE_STATUS_ID)
+    ? DEFAULT_WORKSPACE_STATUS_ID
+    : (statuses[0]?.id ?? DEFAULT_WORKSPACE_STATUS_ID)
+}
+
+export function getWorkspaceStatus(
+  worktree: Pick<Worktree, 'workspaceStatus'>,
+  statuses: readonly WorkspaceStatusDefinition[]
+): WorkspaceStatus {
+  return worktree.workspaceStatus && isWorkspaceStatusId(worktree.workspaceStatus, statuses)
+    ? worktree.workspaceStatus
+    : getDefaultWorkspaceStatusId(statuses)
+}
+
+export function getWorkspaceStatusGroupKey(status: WorkspaceStatus): string {
+  return `${WORKSPACE_STATUS_GROUP_PREFIX}${encodeURIComponent(status)}`
+}
+
+export function getWorkspaceStatusFromGroupKey(
+  groupKey: string,
+  statuses: readonly WorkspaceStatusDefinition[]
+): WorkspaceStatus | null {
+  if (!groupKey.startsWith(WORKSPACE_STATUS_GROUP_PREFIX)) {
+    return null
+  }
+  try {
+    const status = decodeURIComponent(groupKey.slice(WORKSPACE_STATUS_GROUP_PREFIX.length))
+    return isWorkspaceStatusId(status, statuses) ? status : null
+  } catch {
+    return null
+  }
+}

From 2d44ee83b4b933f99d758e77df260a43528ea009 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 14 May 2026 23:30:22 -0700
Subject: [PATCH 22/82] Add Space manager V2 safeguards

---
 src/main/ipc/workspace-space.test.ts          | 125 +++-
 src/main/ipc/workspace-space.ts               | 102 ++-
 src/main/ipc/worktrees.test.ts                |  61 +-
 src/main/ipc/worktrees.ts                     |  51 +-
 .../providers/ssh-filesystem-provider.test.ts |  21 +
 src/main/providers/ssh-filesystem-provider.ts |  14 +
 src/main/providers/ssh-git-provider.test.ts   |   9 +-
 src/main/providers/ssh-git-provider.ts        |  15 +-
 src/main/providers/types.ts                   |   7 +-
 src/main/runtime/orca-runtime.ts              |   9 +-
 src/main/ssh/ssh-channel-multiplexer.test.ts  |  28 +
 src/main/ssh/ssh-channel-multiplexer.ts       |  58 +-
 src/main/workspace-space-analysis.test.ts     | 116 ++-
 src/main/workspace-space-analysis.ts          | 427 ++++++++---
 src/main/worktree-removal-safety.ts           |  79 ++
 src/preload/api-types.ts                      |   9 +-
 src/preload/index.ts                          |  17 +-
 src/relay/dispatcher.test.ts                  |  22 +
 src/relay/dispatcher.ts                       |  28 +-
 src/relay/fs-handler.test.ts                  |  22 +-
 src/relay/fs-handler.ts                       |   9 +-
 src/relay/workspace-space-scan.ts             | 375 ++++++++++
 .../sidebar/DeleteWorktreeDialog.tsx          |  15 +-
 .../sidebar/delete-worktree-flow.test.ts      |  40 +-
 .../sidebar/delete-worktree-flow.ts           |  30 +-
 .../status-bar/WorkspaceSpaceCompactPanel.tsx |  47 +-
 .../status-bar/WorkspaceSpaceManagerPanel.tsx | 694 +++++++++++++-----
 .../status-bar/workspace-space-format.test.ts |  13 +
 .../status-bar/workspace-space-format.ts      |  47 +-
 .../workspace-space/WorkspaceSpacePage.tsx    |  36 +-
 src/renderer/src/hooks/useIpcEvents.ts        |  10 +
 .../src/store/slices/workspace-space.ts       |  70 +-
 src/renderer/src/store/slices/worktrees.ts    |   5 +-
 src/shared/workspace-space-compaction.ts      |  41 ++
 src/shared/workspace-space-types.ts           |  25 +
 35 files changed, 2276 insertions(+), 401 deletions(-)
 create mode 100644 src/main/worktree-removal-safety.ts
 create mode 100644 src/relay/workspace-space-scan.ts
 create mode 100644 src/shared/workspace-space-compaction.ts

diff --git a/src/main/ipc/workspace-space.test.ts b/src/main/ipc/workspace-space.test.ts
index 24f590786d8..437dd1c0cb0 100644
--- a/src/main/ipc/workspace-space.test.ts
+++ b/src/main/ipc/workspace-space.test.ts
@@ -1,15 +1,29 @@
 import { describe, expect, it, vi } from 'vitest'
-import type { WorkspaceSpaceAnalysis } from '../../shared/workspace-space-types'
+import type {
+  WorkspaceSpaceAnalysis,
+  WorkspaceSpaceAnalyzeResult,
+  WorkspaceSpaceScanProgress
+} from '../../shared/workspace-space-types'
 import type { Store } from '../persistence'
 
-const { handlers, analyzeWorkspaceSpaceMock, removeHandlerMock, handleMock } = vi.hoisted(() => ({
-  handlers: new Map<string, () => Promise<WorkspaceSpaceAnalysis>>(),
-  analyzeWorkspaceSpaceMock: vi.fn(),
-  removeHandlerMock: vi.fn(),
-  handleMock: vi.fn((channel: string, handler: () => Promise<WorkspaceSpaceAnalysis>) => {
-    handlers.set(channel, handler)
-  })
-}))
+const {
+  handlers,
+  analyzeWorkspaceSpaceMock,
+  removeHandlerMock,
+  handleMock,
+  WorkspaceSpaceScanCancelledErrorMock
+} = vi.hoisted(() => {
+  const handlers = new Map<string, (...args: unknown[]) => Promise<unknown>>()
+  return {
+    handlers,
+    analyzeWorkspaceSpaceMock: vi.fn(),
+    removeHandlerMock: vi.fn(),
+    handleMock: vi.fn((channel: string, handler: (...args: unknown[]) => Promise<unknown>) => {
+      handlers.set(channel, handler)
+    }),
+    WorkspaceSpaceScanCancelledErrorMock: class WorkspaceSpaceScanCancelledError extends Error {}
+  }
+})
 
 vi.mock('electron', () => ({
   ipcMain: {
@@ -19,6 +33,7 @@ vi.mock('electron', () => ({
 }))
 
 vi.mock('../workspace-space-analysis', () => ({
+  WorkspaceSpaceScanCancelledError: WorkspaceSpaceScanCancelledErrorMock,
   analyzeWorkspaceSpace: analyzeWorkspaceSpaceMock
 }))
 
@@ -37,6 +52,19 @@ function createAnalysis(scannedAt: number): WorkspaceSpaceAnalysis {
   }
 }
 
+function createAnalyzeResult(scannedAt: number): WorkspaceSpaceAnalyzeResult {
+  return { ok: true, analysis: createAnalysis(scannedAt) }
+}
+
+function createEvent() {
+  return {
+    sender: {
+      isDestroyed: vi.fn(() => false),
+      send: vi.fn()
+    }
+  }
+}
+
 describe('registerWorkspaceSpaceHandlers', () => {
   it('shares an in-flight analysis request', async () => {
     const store = {} as Store
@@ -53,17 +81,84 @@ describe('registerWorkspaceSpaceHandlers', () => {
     const handler = handlers.get('workspaceSpace:analyze')
     expect(handler).toBeDefined()
 
-    const first = handler!()
-    const duplicate = handler!()
+    const firstEvent = createEvent()
+    const secondEvent = createEvent()
+    const first = handler!(firstEvent)
+    const duplicate = handler!(secondEvent)
     expect(analyzeWorkspaceSpaceMock).toHaveBeenCalledTimes(1)
-    expect(analyzeWorkspaceSpaceMock).toHaveBeenCalledWith(store)
+    expect(analyzeWorkspaceSpaceMock).toHaveBeenCalledWith(
+      store,
+      expect.objectContaining({
+        scanId: expect.any(String),
+        signal: expect.any(AbortSignal),
+        onProgress: expect.any(Function)
+      })
+    )
 
     const firstResult = createAnalysis(1)
     resolveFirstScan(firstResult)
-    await expect(first).resolves.toBe(firstResult)
-    await expect(duplicate).resolves.toBe(firstResult)
+    await expect(first).resolves.toEqual({ ok: true, analysis: firstResult })
+    await expect(duplicate).resolves.toEqual({ ok: true, analysis: firstResult })
 
-    await expect(handler!()).resolves.toEqual(createAnalysis(2))
+    await expect(handler!(createEvent())).resolves.toEqual(createAnalyzeResult(2))
     expect(analyzeWorkspaceSpaceMock).toHaveBeenCalledTimes(2)
   })
+
+  it('forwards scan progress to the requesting renderer', async () => {
+    const store = {} as Store
+    let onProgress: ((progress: WorkspaceSpaceScanProgress) => void) | undefined
+    analyzeWorkspaceSpaceMock.mockImplementationOnce((_store, options) => {
+      onProgress = options.onProgress
+      return Promise.resolve(createAnalysis(1))
+    })
+
+    registerWorkspaceSpaceHandlers(store)
+    const event = createEvent()
+    const handler = handlers.get('workspaceSpace:analyze')
+    const promise = handler!(event)
+    const progress: WorkspaceSpaceScanProgress = {
+      scanId: 'scan-1',
+      state: 'running',
+      startedAt: 1,
+      updatedAt: 1,
+      totalRepoCount: 1,
+      scannedRepoCount: 0,
+      totalWorktreeCount: 2,
+      scannedWorktreeCount: 1,
+      currentRepoDisplayName: 'orca',
+      currentWorktreeDisplayName: 'feature'
+    }
+    onProgress?.(progress)
+    await promise
+
+    expect(event.sender.send).toHaveBeenCalledWith('workspaceSpace:progress', progress)
+  })
+
+  it('cancels the in-flight scan', async () => {
+    const store = {} as Store
+    let signal: AbortSignal | undefined
+    analyzeWorkspaceSpaceMock.mockImplementationOnce((_store, options) => {
+      signal = options.signal
+      return new Promise<WorkspaceSpaceAnalysis>(() => {})
+    })
+
+    registerWorkspaceSpaceHandlers(store)
+    const analyzeHandler = handlers.get('workspaceSpace:analyze')
+    const cancelHandler = handlers.get('workspaceSpace:cancel')
+    void analyzeHandler!(createEvent())
+
+    await expect(cancelHandler!()).resolves.toBe(true)
+    expect(signal?.aborted).toBe(true)
+    await expect(cancelHandler!()).resolves.toBe(false)
+  })
+
+  it('returns a normal cancelled result instead of rejecting expected cancellation', async () => {
+    const store = {} as Store
+    analyzeWorkspaceSpaceMock.mockRejectedValueOnce(new WorkspaceSpaceScanCancelledErrorMock())
+
+    registerWorkspaceSpaceHandlers(store)
+    const analyzeHandler = handlers.get('workspaceSpace:analyze')
+
+    await expect(analyzeHandler!(createEvent())).resolves.toEqual({ ok: false, cancelled: true })
+  })
 })
diff --git a/src/main/ipc/workspace-space.ts b/src/main/ipc/workspace-space.ts
index 8302503bdf8..d4449f3db52 100644
--- a/src/main/ipc/workspace-space.ts
+++ b/src/main/ipc/workspace-space.ts
@@ -1,19 +1,107 @@
 import { ipcMain } from 'electron'
 import type { Store } from '../persistence'
-import type { WorkspaceSpaceAnalysis } from '../../shared/workspace-space-types'
-import { analyzeWorkspaceSpace } from '../workspace-space-analysis'
+import type {
+  WorkspaceSpaceAnalyzeResult,
+  WorkspaceSpaceScanProgress
+} from '../../shared/workspace-space-types'
+import {
+  analyzeWorkspaceSpace,
+  WorkspaceSpaceScanCancelledError
+} from '../workspace-space-analysis'
+
+const PROGRESS_EMIT_INTERVAL_MS = 100
+
+type InFlightWorkspaceSpaceScan = {
+  scanId: string
+  controller: AbortController
+  progress: WorkspaceSpaceScanProgress
+  promise: Promise<WorkspaceSpaceAnalyzeResult>
+}
 
 export function registerWorkspaceSpaceHandlers(store: Store): void {
-  let inFlightScan: Promise<WorkspaceSpaceAnalysis> | null = null
+  let inFlightScan: InFlightWorkspaceSpaceScan | null = null
+  ipcMain.removeHandler('workspaceSpace:cancel')
   ipcMain.removeHandler('workspaceSpace:analyze')
-  ipcMain.handle('workspaceSpace:analyze', async (): Promise<WorkspaceSpaceAnalysis> => {
+  ipcMain.handle('workspaceSpace:analyze', async (event): Promise<WorkspaceSpaceAnalyzeResult> => {
     if (!inFlightScan) {
+      const controller = new AbortController()
+      const scanId = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      let latestProgress: WorkspaceSpaceScanProgress = {
+        scanId,
+        state: 'running',
+        startedAt: Date.now(),
+        updatedAt: Date.now(),
+        totalRepoCount: 0,
+        scannedRepoCount: 0,
+        totalWorktreeCount: 0,
+        scannedWorktreeCount: 0,
+        currentRepoDisplayName: null,
+        currentWorktreeDisplayName: null
+      }
+      let lastProgressSentAt = 0
+      const sendProgress = (progress: WorkspaceSpaceScanProgress): void => {
+        // Why: large fleets can report one progress event per worktree; keep
+        // the UI responsive without repainting the full Space page for each row.
+        const now = Date.now()
+        const isFirstProgress = lastProgressSentAt === 0
+        const isTerminalProgress =
+          progress.state !== 'running' ||
+          (progress.totalWorktreeCount > 0 &&
+            progress.scannedWorktreeCount >= progress.totalWorktreeCount)
+        if (
+          !isFirstProgress &&
+          !isTerminalProgress &&
+          now - lastProgressSentAt < PROGRESS_EMIT_INTERVAL_MS
+        ) {
+          return
+        }
+        lastProgressSentAt = now
+        if (!event.sender.isDestroyed()) {
+          event.sender.send('workspaceSpace:progress', progress)
+        }
+      }
       // Why: large worktree fleets require real disk traversal; duplicate
       // requests should share that IO instead of starting competing scans.
-      inFlightScan = analyzeWorkspaceSpace(store).finally(() => {
-        inFlightScan = null
+      const scan: InFlightWorkspaceSpaceScan = {
+        scanId,
+        controller,
+        progress: latestProgress,
+        promise: Promise.resolve(null as never)
+      }
+      inFlightScan = scan
+      scan.promise = analyzeWorkspaceSpace(store, {
+        scanId,
+        signal: controller.signal,
+        onProgress: (progress) => {
+          latestProgress = progress
+          scan.progress = progress
+          sendProgress(progress)
+        }
       })
+        .then((analysis): WorkspaceSpaceAnalyzeResult => ({ ok: true, analysis }))
+        .catch((error: unknown): WorkspaceSpaceAnalyzeResult => {
+          if (error instanceof WorkspaceSpaceScanCancelledError) {
+            return { ok: false, cancelled: true }
+          }
+          throw error
+        })
+        .finally(() => {
+          inFlightScan = null
+        })
     }
-    return inFlightScan
+    return inFlightScan.promise
+  })
+
+  ipcMain.handle('workspaceSpace:cancel', async (): Promise<boolean> => {
+    if (!inFlightScan || inFlightScan.controller.signal.aborted) {
+      return false
+    }
+    inFlightScan.controller.abort()
+    inFlightScan.progress = {
+      ...inFlightScan.progress,
+      state: 'cancelling',
+      updatedAt: Date.now()
+    }
+    return true
   })
 }
diff --git a/src/main/ipc/worktrees.test.ts b/src/main/ipc/worktrees.test.ts
index 25ff76c4dba..4a0de9b6e97 100644
--- a/src/main/ipc/worktrees.test.ts
+++ b/src/main/ipc/worktrees.test.ts
@@ -308,6 +308,25 @@ describe('registerWorktreeHandlers', () => {
     registerWorktreeHandlers(mainWindow as never, store as never, runtimeStub as never)
   })
 
+  function mockKnownFeatureWorktree(path = '/workspace/feature-wt'): void {
+    listWorktreesMock.mockResolvedValue([
+      {
+        path: '/workspace/repo',
+        head: 'main',
+        branch: 'main',
+        isBare: false,
+        isMainWorktree: true
+      },
+      {
+        path,
+        head: 'feature',
+        branch: 'feature',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+  }
+
   it('auto-suffixes the branch name when the first choice collides with a remote branch', async () => {
     // Why: new-workspace flow should silently try improve-dashboard-2, -3, ...
     // rather than failing and forcing the user back to the name picker.
@@ -1218,6 +1237,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('prunes git worktree tracking when removing an orphaned worktree', async () => {
+    mockKnownFeatureWorktree()
     const orphanError = Object.assign(new Error('git worktree remove failed'), {
       stderr: "fatal: '/workspace/feature-wt' is not a working tree"
     })
@@ -1241,7 +1261,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('runs the archive hook on remove when skipArchive is not set', async () => {
-    listWorktreesMock.mockResolvedValue([])
+    mockKnownFeatureWorktree()
     removeWorktreeMock.mockResolvedValue(undefined)
     getEffectiveHooksMock.mockReturnValue({
       scripts: {
@@ -1267,7 +1287,7 @@ describe('registerWorktreeHandlers', () => {
   })
 
   it('skips the archive hook on remove when skipArchive is true', async () => {
-    listWorktreesMock.mockResolvedValue([])
+    mockKnownFeatureWorktree()
     removeWorktreeMock.mockResolvedValue(undefined)
     getEffectiveHooksMock.mockReturnValue({
       scripts: {
@@ -1289,8 +1309,43 @@ describe('registerWorktreeHandlers', () => {
     )
   })
 
+  it('rejects unregistered delete paths before teardown, hooks, or git removal', async () => {
+    mockKnownFeatureWorktree('/workspace/real-feature')
+    getEffectiveHooksMock.mockReturnValue({
+      scripts: {
+        archive: 'echo archived'
+      }
+    })
+
+    await expect(
+      handlers['worktrees:remove'](null, {
+        worktreeId: 'repo-1::/workspace/not-a-worktree'
+      })
+    ).rejects.toThrow('Refusing to delete unregistered worktree path')
+
+    expect(killAllProcessesForWorktreeMock).not.toHaveBeenCalled()
+    expect(runHookMock).not.toHaveBeenCalled()
+    expect(removeWorktreeMock).not.toHaveBeenCalled()
+    expect(store.removeWorktreeMeta).not.toHaveBeenCalled()
+  })
+
+  it('rejects the main worktree before teardown, hooks, or git removal', async () => {
+    mockKnownFeatureWorktree()
+
+    await expect(
+      handlers['worktrees:remove'](null, {
+        worktreeId: 'repo-1::/workspace/repo'
+      })
+    ).rejects.toThrow('Refusing to delete protected worktree path')
+
+    expect(killAllProcessesForWorktreeMock).not.toHaveBeenCalled()
+    expect(runHookMock).not.toHaveBeenCalled()
+    expect(removeWorktreeMock).not.toHaveBeenCalled()
+    expect(store.removeWorktreeMeta).not.toHaveBeenCalled()
+  })
+
   it('IPC-initiated delete kills PTYs BEFORE git-level removal (design §4.3)', async () => {
-    listWorktreesMock.mockResolvedValue([])
+    mockKnownFeatureWorktree()
     getEffectiveHooksMock.mockReturnValue(null)
     const callOrder: string[] = []
     killAllProcessesForWorktreeMock.mockImplementation(async () => {
diff --git a/src/main/ipc/worktrees.ts b/src/main/ipc/worktrees.ts
index eef52f3d289..8bb2b01494a 100644
--- a/src/main/ipc/worktrees.ts
+++ b/src/main/ipc/worktrees.ts
@@ -13,7 +13,7 @@ import type {
   Repo,
   WorktreeMeta
 } from '../../shared/types'
-import { removeWorktree } from '../git/worktree'
+import { listWorktrees as listGitWorktrees, removeWorktree } from '../git/worktree'
 import { gitExecFileAsync } from '../git/runner'
 import { getDefaultRemote } from '../git/repo'
 import { getPullRequestPushTarget, getWorkItem } from '../github/client'
@@ -51,6 +51,10 @@ import { track } from '../telemetry/client'
 import { getCohortAtEmit } from '../telemetry/cohort-classifier'
 import { workspaceSourceSchema, type WorkspaceSource } from '../../shared/telemetry-events'
 import { classifyWorkspaceCreateError } from './workspace-create-error-classifier'
+import {
+  canSafelyRemoveOrphanedWorktreeDirectory,
+  getRegisteredDeletableWorktree
+} from '../worktree-removal-safety'
 
 // Why: worktrees discovered on disk (not created via Orca's UI) have no
 // persisted WorktreeMeta, so mergeWorktree falls back to `lastActivityAt: 0`.
@@ -517,6 +521,21 @@ export function registerWorktreeHandlers(
         throw new Error('Folder mode does not support deleting worktrees.')
       }
 
+      // Why: the renderer-supplied worktreeId contains a filesystem path.
+      // Re-derive the canonical path from git before any destructive action.
+      const provider = repo.connectionId ? getSshGitProvider(repo.connectionId) : null
+      if (repo.connectionId && !provider) {
+        throw new Error(`No git provider for connection "${repo.connectionId}"`)
+      }
+      const registeredWorktrees = repo.connectionId
+        ? await provider!.listWorktrees(repo.path)
+        : await listGitWorktrees(repo.path)
+      const canonicalWorktreePath = getRegisteredDeletableWorktree(
+        repo.path,
+        worktreePath,
+        registeredWorktrees
+      ).path
+
       // Why: kill every PTY belonging to this worktree BEFORE git-level
       // removal. The renderer pre-kills via shutdownWorktreeTerminals, but
       // defensive teardown here protects against: (a) a future renderer bug,
@@ -543,11 +562,7 @@ export function registerWorktreeHandlers(
       }
 
       if (repo.connectionId) {
-        const provider = getSshGitProvider(repo.connectionId)
-        if (!provider) {
-          throw new Error(`No git provider for connection "${repo.connectionId}"`)
-        }
-        await provider.removeWorktree(worktreePath, args.force)
+        await provider!.removeWorktree(canonicalWorktreePath, args.force)
         runtime.clearOptimisticReconcileToken(args.worktreeId)
         await runtime.unlinkNotesWorktree(repoId, args.worktreeId)
         store.removeWorktreeMeta(args.worktreeId)
@@ -559,9 +574,9 @@ export function registerWorktreeHandlers(
       // Run archive hook before removal
       const hooks = getEffectiveHooks(repo)
       if (hooks?.scripts.archive && !args.skipArchive) {
-        const result = await runHook('archive', worktreePath, repo)
+        const result = await runHook('archive', canonicalWorktreePath, repo)
         if (!result.success) {
-          console.error(`[hooks] archive hook failed for ${worktreePath}:`, result.output)
+          console.error(`[hooks] archive hook failed for ${canonicalWorktreePath}:`, result.output)
         }
       }
 
@@ -571,16 +586,24 @@ export function registerWorktreeHandlers(
       // first so the normal delete path keeps working — otherwise every
       // deletion would require the Force Delete toast once the feature is on.
       if (repo.symlinkPaths && repo.symlinkPaths.length > 0) {
-        await removeWorktreeSymlinks(worktreePath, repo.symlinkPaths)
+        await removeWorktreeSymlinks(canonicalWorktreePath, repo.symlinkPaths)
       }
 
       try {
-        await removeWorktree(repo.path, worktreePath, args.force ?? false)
+        await removeWorktree(repo.path, canonicalWorktreePath, args.force ?? false)
       } catch (error) {
         // If git no longer tracks this worktree, clean up the directory and metadata
         if (isOrphanedWorktreeError(error)) {
-          console.warn(`[worktrees] Orphaned worktree detected at ${worktreePath}, cleaning up`)
-          await rm(worktreePath, { recursive: true, force: true }).catch(() => {})
+          console.warn(
+            `[worktrees] Orphaned worktree detected at ${canonicalWorktreePath}, cleaning up`
+          )
+          if (await canSafelyRemoveOrphanedWorktreeDirectory(canonicalWorktreePath, repo.path)) {
+            await rm(canonicalWorktreePath, { recursive: true, force: true }).catch(() => {})
+          } else {
+            console.warn(
+              `[worktrees] Refusing recursive cleanup for unproven worktree directory: ${canonicalWorktreePath}`
+            )
+          }
           // Why: `git worktree remove` failed, so git's internal worktree tracking
           // (`.git/worktrees/<name>`) is still intact. Without pruning, `git worktree
           // list` continues to show the stale entry and the branch it had checked out
@@ -594,7 +617,9 @@ export function registerWorktreeHandlers(
           notifyWorktreesChanged(mainWindow, repoId)
           return
         }
-        throw new Error(formatWorktreeRemovalError(error, worktreePath, args.force ?? false))
+        throw new Error(
+          formatWorktreeRemovalError(error, canonicalWorktreePath, args.force ?? false)
+        )
       }
       runtime.clearOptimisticReconcileToken(args.worktreeId)
       await runtime.unlinkNotesWorktree(repoId, args.worktreeId)
diff --git a/src/main/providers/ssh-filesystem-provider.test.ts b/src/main/providers/ssh-filesystem-provider.test.ts
index 8fbf9551c00..037c7047756 100644
--- a/src/main/providers/ssh-filesystem-provider.test.ts
+++ b/src/main/providers/ssh-filesystem-provider.test.ts
@@ -162,6 +162,27 @@ describe('SshFilesystemProvider', () => {
     })
   })
 
+  it('scanWorkspaceSpace sends an abortable bulk scan request', async () => {
+    const result = {
+      sizeBytes: 1024,
+      skippedEntryCount: 0,
+      topLevelItems: [],
+      omittedTopLevelItemCount: 0,
+      omittedTopLevelSizeBytes: 0
+    }
+    const controller = new AbortController()
+    mux.request.mockResolvedValue(result)
+
+    await expect(
+      provider.scanWorkspaceSpace('/home/user/project', { signal: controller.signal })
+    ).resolves.toBe(result)
+    expect(mux.request).toHaveBeenCalledWith(
+      'fs.workspaceSpaceScan',
+      { rootPath: '/home/user/project' },
+      { signal: controller.signal, timeoutMs: 130000 }
+    )
+  })
+
   it('deletePath sends fs.deletePath request', async () => {
     await provider.deletePath('/home/user/file.txt')
     expect(mux.request).toHaveBeenCalledWith('fs.deletePath', { targetPath: '/home/user/file.txt' })
diff --git a/src/main/providers/ssh-filesystem-provider.ts b/src/main/providers/ssh-filesystem-provider.ts
index b33c0dbe08b..cc334a3cf83 100644
--- a/src/main/providers/ssh-filesystem-provider.ts
+++ b/src/main/providers/ssh-filesystem-provider.ts
@@ -4,6 +4,7 @@ import { uploadBuffer } from '../ssh/sftp-upload'
 import type { IFilesystemProvider, FileStat, FileReadResult } from './types'
 import type { DirEntry, FsChangeEvent, SearchOptions, SearchResult } from '../../shared/types'
 import { isPathInsideOrEqual } from '../../shared/cross-platform-path'
+import type { WorkspaceSpaceDirectoryScanResult } from '../../shared/workspace-space-types'
 import type { SFTPWrapper } from 'ssh2'
 
 type SftpFactory = () => Promise<SFTPWrapper>
@@ -12,6 +13,8 @@ type WatchRegistration = {
   setupPromise: Promise<void>
 }
 
+const WORKSPACE_SPACE_SCAN_TIMEOUT_MS = 130_000
+
 export class SshFilesystemProvider implements IFilesystemProvider {
   private connectionId: string
   private mux: SshChannelMultiplexer
@@ -122,6 +125,17 @@ export class SshFilesystemProvider implements IFilesystemProvider {
     return (await this.mux.request('fs.stat', { filePath })) as FileStat
   }
 
+  async scanWorkspaceSpace(
+    rootPath: string,
+    options?: { signal?: AbortSignal }
+  ): Promise<WorkspaceSpaceDirectoryScanResult> {
+    return (await this.mux.request(
+      'fs.workspaceSpaceScan',
+      { rootPath },
+      { signal: options?.signal, timeoutMs: WORKSPACE_SPACE_SCAN_TIMEOUT_MS }
+    )) as WorkspaceSpaceDirectoryScanResult
+  }
+
   async deletePath(targetPath: string, recursive?: boolean): Promise<void> {
     await this.mux.request('fs.deletePath', { targetPath, recursive })
   }
diff --git a/src/main/providers/ssh-git-provider.test.ts b/src/main/providers/ssh-git-provider.test.ts
index 68346c81e0f..5643c3c2d29 100644
--- a/src/main/providers/ssh-git-provider.test.ts
+++ b/src/main/providers/ssh-git-provider.test.ts
@@ -200,8 +200,13 @@ describe('SshGitProvider', () => {
     ]
     mux.request.mockResolvedValue(worktrees)
 
-    const result = await provider.listWorktrees('/home/user/repo')
-    expect(mux.request).toHaveBeenCalledWith('git.listWorktrees', { repoPath: '/home/user/repo' })
+    const controller = new AbortController()
+    const result = await provider.listWorktrees('/home/user/repo', { signal: controller.signal })
+    expect(mux.request).toHaveBeenCalledWith(
+      'git.listWorktrees',
+      { repoPath: '/home/user/repo' },
+      { signal: controller.signal }
+    )
     expect(result).toEqual(worktrees)
   })
 
diff --git a/src/main/providers/ssh-git-provider.ts b/src/main/providers/ssh-git-provider.ts
index e93ad886adf..45dec93c79b 100644
--- a/src/main/providers/ssh-git-provider.ts
+++ b/src/main/providers/ssh-git-provider.ts
@@ -123,10 +123,17 @@ export class SshGitProvider implements IGitProvider {
     })) as GitDiffResult[]
   }
 
-  async listWorktrees(repoPath: string): Promise<GitWorktreeInfo[]> {
-    return (await this.mux.request('git.listWorktrees', {
-      repoPath
-    })) as GitWorktreeInfo[]
+  async listWorktrees(
+    repoPath: string,
+    options?: { signal?: AbortSignal }
+  ): Promise<GitWorktreeInfo[]> {
+    return (await this.mux.request(
+      'git.listWorktrees',
+      {
+        repoPath
+      },
+      { signal: options?.signal }
+    )) as GitWorktreeInfo[]
   }
 
   async addWorktree(
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 998c22b3f73..3e091ea1f76 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -11,6 +11,7 @@ import type {
   SearchOptions,
   SearchResult
 } from '../../shared/types'
+import type { WorkspaceSpaceDirectoryScanResult } from '../../shared/workspace-space-types'
 
 // ─── PTY Provider ───────────────────────────────────────────────────
 
@@ -130,6 +131,10 @@ export type IFilesystemProvider = {
   realpath(filePath: string): Promise<string>
   search(opts: SearchOptions): Promise<SearchResult>
   listFiles(rootPath: string, options?: { excludePaths?: string[] }): Promise<string[]>
+  scanWorkspaceSpace?(
+    rootPath: string,
+    options?: { signal?: AbortSignal }
+  ): Promise<WorkspaceSpaceDirectoryScanResult>
   watch(rootPath: string, callback: (events: FsChangeEvent[]) => void): Promise<() => void>
 }
 
@@ -161,7 +166,7 @@ export type IGitProvider = {
     baseRef: string,
     options?: { includePatch?: boolean; filePath?: string; oldPath?: string }
   ): Promise<GitDiffResult[]>
-  listWorktrees(repoPath: string): Promise<GitWorktreeInfo[]>
+  listWorktrees(repoPath: string, options?: { signal?: AbortSignal }): Promise<GitWorktreeInfo[]>
   addWorktree(
     repoPath: string,
     branchName: string,
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 38fa678ec92..3ee8b60e261 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -222,6 +222,7 @@ import {
   shouldSetDisplayName,
   areWorktreePathsEqual
 } from '../ipc/worktree-logic'
+import { canSafelyRemoveOrphanedWorktreeDirectory } from '../worktree-removal-safety'
 import { invalidateAuthorizedRootsCache } from '../ipc/filesystem-auth'
 import { HeadlessEmulator } from '../daemon/headless-emulator'
 import { killAllProcessesForWorktree } from './worktree-teardown'
@@ -6004,7 +6005,13 @@ export class OrcaRuntimeService {
       await removeWorktree(repo.path, worktree.path, force)
     } catch (error) {
       if (isOrphanedWorktreeError(error)) {
-        await rm(worktree.path, { recursive: true, force: true }).catch(() => {})
+        if (await canSafelyRemoveOrphanedWorktreeDirectory(worktree.path, repo.path)) {
+          await rm(worktree.path, { recursive: true, force: true }).catch(() => {})
+        } else {
+          console.warn(
+            `[worktrees] Refusing recursive cleanup for unproven worktree directory: ${worktree.path}`
+          )
+        }
         // Why: `git worktree remove` failed, so git's internal worktree tracking
         // (`.git/worktrees/<name>`) is still intact. Without pruning, `git worktree
         // list` continues to show the stale entry and the branch it had checked out
diff --git a/src/main/ssh/ssh-channel-multiplexer.test.ts b/src/main/ssh/ssh-channel-multiplexer.test.ts
index f8ba76209b2..7df48286090 100644
--- a/src/main/ssh/ssh-channel-multiplexer.test.ts
+++ b/src/main/ssh/ssh-channel-multiplexer.test.ts
@@ -123,6 +123,34 @@ describe('SshChannelMultiplexer', () => {
       vi.advanceTimersByTime(1_000)
 
       await expect(promise).rejects.toThrow('timed out')
+      const cancelPayload = JSON.parse(
+        transport.written
+          .at(-1)!
+          .subarray(HEADER_LENGTH, HEADER_LENGTH + transport.written.at(-1)!.readUInt32BE(9))
+          .toString()
+      )
+      expect(cancelPayload).toMatchObject({
+        method: 'rpc.cancel',
+        params: { id: 1 }
+      })
+    })
+
+    it('uses per-request timeout overrides', async () => {
+      const promise = mux.request('fs.workspaceSpaceScan', {}, { timeoutMs: 60_000 })
+
+      for (let i = 0; i < 6; i++) {
+        vi.advanceTimersByTime(5_000)
+        transport.dataCallbacks[0](encodeKeepAliveFrame(i + 1, 0))
+      }
+      await Promise.resolve()
+      const requestWrites = transport.written.filter((frame) => frame[0] === MessageType.Regular)
+      expect(requestWrites).toHaveLength(1)
+
+      for (let i = 6; i < 12; i++) {
+        vi.advanceTimersByTime(5_000)
+        transport.dataCallbacks[0](encodeKeepAliveFrame(i + 1, 0))
+      }
+      await expect(promise).rejects.toThrow('timed out after 60000ms')
     })
 
     it('assigns unique request IDs', async () => {
diff --git a/src/main/ssh/ssh-channel-multiplexer.ts b/src/main/ssh/ssh-channel-multiplexer.ts
index 11a18bebe82..9d95bbd05b8 100644
--- a/src/main/ssh/ssh-channel-multiplexer.ts
+++ b/src/main/ssh/ssh-channel-multiplexer.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: the SSH relay protocol state machine keeps
+   request, notification, keepalive, and cancellation semantics paired. */
 import {
   FrameDecoder,
   MessageType,
@@ -24,6 +26,7 @@ type PendingRequest = {
   resolve: (result: unknown) => void
   reject: (error: Error) => void
   timer: ReturnType<typeof setTimeout>
+  cleanup: () => void
 }
 
 export type NotificationHandler = (method: string, params: Record<string, unknown>) => void
@@ -127,10 +130,19 @@ export class SshChannelMultiplexer {
   /**
    * Send a JSON-RPC request and wait for the response.
    */
-  async request(method: string, params?: Record<string, unknown>): Promise<unknown> {
+  async request(
+    method: string,
+    params?: Record<string, unknown>,
+    options?: { signal?: AbortSignal; timeoutMs?: number }
+  ): Promise<unknown> {
     if (this.disposed) {
       throw new Error('Multiplexer disposed')
     }
+    if (options?.signal?.aborted) {
+      const error = new Error(`Request "${method}" was cancelled`) as Error & { name: string }
+      error.name = 'AbortError'
+      throw error
+    }
 
     const id = this.nextRequestId++
     const msg: JsonRpcRequest = {
@@ -139,14 +151,46 @@ export class SshChannelMultiplexer {
       method,
       ...(params !== undefined ? { params } : {})
     }
+    const timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS
 
     return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
+      let timer: ReturnType<typeof setTimeout>
+      const cleanup = (): void => {
+        clearTimeout(timer)
+        if (options?.signal) {
+          options.signal.removeEventListener('abort', onAbort)
+        }
+      }
+      const onAbort = (): void => {
+        const pending = this.pendingRequests.get(id)
+        if (!pending) {
+          return
+        }
+        pending.cleanup()
         this.pendingRequests.delete(id)
-        reject(new Error(`Request "${method}" timed out after ${REQUEST_TIMEOUT_MS}ms`))
-      }, REQUEST_TIMEOUT_MS)
+        // Why: Space scans can run long on SSH hosts. Let the relay stop its
+        // local filesystem work instead of only dropping the client promise.
+        this.notify('rpc.cancel', { id })
+        const error = new Error(`Request "${method}" was cancelled`) as Error & { name: string }
+        error.name = 'AbortError'
+        pending.reject(error)
+      }
+      timer = setTimeout(() => {
+        const pending = this.pendingRequests.get(id)
+        if (pending) {
+          pending.cleanup()
+          // Why: request timeouts should stop relay-side long-running work,
+          // not just detach the client from the eventual response.
+          this.notify('rpc.cancel', { id })
+        }
+        this.pendingRequests.delete(id)
+        reject(new Error(`Request "${method}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
 
-      this.pendingRequests.set(id, { resolve, reject, timer })
+      if (options?.signal) {
+        options.signal.addEventListener('abort', onAbort, { once: true })
+      }
+      this.pendingRequests.set(id, { resolve, reject, timer, cleanup })
       this.sendMessage(msg)
     })
   }
@@ -194,7 +238,7 @@ export class SshChannelMultiplexer {
     const errorCode = reason === 'connection_lost' ? 'CONNECTION_LOST' : 'DISPOSED'
 
     for (const [id, pending] of this.pendingRequests) {
-      clearTimeout(pending.timer)
+      pending.cleanup()
       const err = new Error(errorMessage) as Error & { code: string }
       err.code = errorCode
       pending.reject(err)
@@ -295,7 +339,7 @@ export class SshChannelMultiplexer {
       return
     }
 
-    clearTimeout(pending.timer)
+    pending.cleanup()
     this.pendingRequests.delete(msg.id)
 
     if (msg.error) {
diff --git a/src/main/workspace-space-analysis.test.ts b/src/main/workspace-space-analysis.test.ts
index 041219501c8..f2ab549b915 100644
--- a/src/main/workspace-space-analysis.test.ts
+++ b/src/main/workspace-space-analysis.test.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- Why: scan, cancellation, SSH fallback, and compaction tests share temp-repo fixtures. */
 import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -32,7 +33,7 @@ vi.mock('./providers/ssh-git-dispatch', () => ({
   getSshGitProvider: getSshGitProviderMock
 }))
 
-import { analyzeWorkspaceSpace } from './workspace-space-analysis'
+import { analyzeWorkspaceSpace, WorkspaceSpaceScanCancelledError } from './workspace-space-analysis'
 
 function createStore(repos: Repo[]): Store {
   return {
@@ -123,6 +124,70 @@ describe('analyzeWorkspaceSpace', () => {
     expect(result.reclaimableBytes).toBe(feature?.sizeBytes)
   })
 
+  it('reports scan progress as repos and worktrees are scanned', async () => {
+    const root = tempDir!
+    const repoPath = join(root, 'repo')
+    await mkdir(repoPath, { recursive: true })
+    await writeSizedFile(join(repoPath, 'file.txt'), 128)
+    const repo: Repo = {
+      id: 'repo-1',
+      path: repoPath,
+      displayName: 'orca',
+      badgeColor: '#000',
+      addedAt: 0
+    }
+    listRepoWorktreesMock.mockResolvedValue([
+      {
+        path: repoPath,
+        head: 'a',
+        branch: 'refs/heads/main',
+        isBare: false,
+        isMainWorktree: true
+      }
+    ])
+    const progress: unknown[] = []
+
+    await analyzeWorkspaceSpace(createStore([repo]), {
+      scanId: 'scan-1',
+      onProgress: (event) => progress.push(event)
+    })
+
+    expect(progress[0]).toMatchObject({
+      scanId: 'scan-1',
+      totalRepoCount: 1,
+      scannedRepoCount: 0,
+      totalWorktreeCount: 0,
+      scannedWorktreeCount: 0
+    })
+    expect(progress).toContainEqual(
+      expect.objectContaining({
+        totalWorktreeCount: 1,
+        currentRepoDisplayName: 'orca'
+      })
+    )
+    expect(progress.at(-1)).toMatchObject({
+      scannedRepoCount: 1,
+      scannedWorktreeCount: 1
+    })
+  })
+
+  it('rejects when a scan is cancelled before it starts', async () => {
+    const repo: Repo = {
+      id: 'repo-1',
+      path: tempDir!,
+      displayName: 'orca',
+      badgeColor: '#000',
+      addedAt: 0
+    }
+    const controller = new AbortController()
+    controller.abort()
+
+    await expect(
+      analyzeWorkspaceSpace(createStore([repo]), { signal: controller.signal })
+    ).rejects.toBeInstanceOf(WorkspaceSpaceScanCancelledError)
+    expect(listRepoWorktreesMock).not.toHaveBeenCalled()
+  })
+
   it('isolates missing worktrees as row-level scan failures', async () => {
     const root = tempDir!
     const repoPath = join(root, 'repo')
@@ -219,6 +284,55 @@ describe('analyzeWorkspaceSpace', () => {
     expect(statMock).not.toHaveBeenCalledWith('/remote/feature/linked-cache')
   })
 
+  it('uses the SSH bulk Space scan provider when available', async () => {
+    const repo: Repo = {
+      id: 'repo-remote',
+      path: '/remote/repo',
+      displayName: 'remote',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'ssh-1'
+    }
+    getSshGitProviderMock.mockReturnValue({
+      listWorktrees: vi.fn().mockResolvedValue([
+        {
+          path: '/remote/feature',
+          head: 'c',
+          branch: 'refs/heads/feature',
+          isBare: false,
+          isMainWorktree: false
+        }
+      ])
+    })
+    const scanWorkspaceSpace = vi.fn().mockResolvedValue({
+      sizeBytes: 4096,
+      skippedEntryCount: 0,
+      topLevelItems: [
+        {
+          name: 'node_modules',
+          path: '/remote/feature/node_modules',
+          kind: 'directory',
+          sizeBytes: 4096
+        }
+      ],
+      omittedTopLevelItemCount: 0,
+      omittedTopLevelSizeBytes: 0
+    })
+    const readDir = vi.fn()
+    const stat = vi.fn()
+    getSshFilesystemProviderMock.mockReturnValue({ scanWorkspaceSpace, readDir, stat })
+
+    const result = await analyzeWorkspaceSpace(createStore([repo]))
+
+    expect(scanWorkspaceSpace).toHaveBeenCalledWith(
+      '/remote/feature',
+      expect.objectContaining({ signal: undefined })
+    )
+    expect(readDir).not.toHaveBeenCalled()
+    expect(stat).not.toHaveBeenCalled()
+    expect(result.worktrees[0]?.sizeBytes).toBe(4096)
+  })
+
   it('reports disconnected SSH repos without failing the whole analysis', async () => {
     const repo: Repo = {
       id: 'repo-remote',
diff --git a/src/main/workspace-space-analysis.ts b/src/main/workspace-space-analysis.ts
index 950f05c78bb..fd23f12b65b 100644
--- a/src/main/workspace-space-analysis.ts
+++ b/src/main/workspace-space-analysis.ts
@@ -2,7 +2,7 @@
    semantics paired so reclaimable-byte, symlink, and partial-failure behavior cannot drift. */
 import { lstat, readdir } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
-import { basename, posix, win32 } from 'node:path'
+import { posix, win32 } from 'node:path'
 import { platform } from 'node:process'
 import { promisify } from 'node:util'
 import type { Dirent } from 'node:fs'
@@ -11,19 +11,21 @@ import { isFolderRepo } from '../shared/repo-kind'
 import type { GitWorktreeInfo, Repo, Worktree } from '../shared/types'
 import type {
   WorkspaceSpaceAnalysis,
+  WorkspaceSpaceDirectoryScanResult,
   WorkspaceSpaceItem,
   WorkspaceSpaceItemKind,
   WorkspaceSpaceRepoSummary,
+  WorkspaceSpaceScanProgress,
   WorkspaceSpaceScanStatus,
   WorkspaceSpaceWorktree
 } from '../shared/workspace-space-types'
+import { compactWorkspaceSpaceItems } from '../shared/workspace-space-compaction'
 import type { IFilesystemProvider } from './providers/types'
 import { getSshFilesystemProvider } from './providers/ssh-filesystem-dispatch'
 import { getSshGitProvider } from './providers/ssh-git-dispatch'
 import { createFolderWorktree, listRepoWorktrees } from './repo-worktrees'
 import { mergeWorktree } from './ipc/worktree-logic'
 
-const MAX_TOP_LEVEL_ITEMS = 48
 const WORKTREE_SCAN_CONCURRENCY = 3
 const LOCAL_FS_CONCURRENCY = 48
 const REMOTE_FS_CONCURRENCY = 10
@@ -51,16 +53,78 @@ type RepoScanResult = {
   worktrees: WorkspaceSpaceWorktree[]
 }
 
-function createAsyncLimiter(maxConcurrent: number): AsyncLimiter {
+type WorkspaceSpaceAnalyzeOptions = {
+  signal?: AbortSignal
+  scanId?: string
+  onProgress?: (progress: WorkspaceSpaceScanProgress) => void
+}
+
+type WorkspaceSpaceProgressState = WorkspaceSpaceScanProgress
+
+export class WorkspaceSpaceScanCancelledError extends Error {
+  constructor() {
+    super('Workspace space scan cancelled')
+    this.name = 'WorkspaceSpaceScanCancelledError'
+  }
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new WorkspaceSpaceScanCancelledError()
+  }
+}
+
+function isAbortError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false
+  }
+  return (error as { name?: unknown }).name === 'AbortError'
+}
+
+function isRelayMethodNotFoundError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false
+  }
+  return (error as { code?: unknown }).code === -32601
+}
+
+function createAsyncLimiter(maxConcurrent: number, signal?: AbortSignal): AsyncLimiter {
   let active = 0
-  const queue: (() => void)[] = []
+  const queue: { resolve: () => void; reject: (error: Error) => void }[] = []
 
   const acquire = async (): Promise<void> => {
+    throwIfAborted(signal)
     if (active < maxConcurrent) {
       active += 1
       return
     }
-    await new Promise<void>((resolve) => queue.push(resolve))
+    await new Promise<void>((resolve, reject) => {
+      let onAbort: (() => void) | null = null
+      const waiter = {
+        resolve: () => {
+          if (onAbort) {
+            signal?.removeEventListener('abort', onAbort)
+          }
+          resolve()
+        },
+        reject
+      }
+      onAbort = () => {
+        const index = queue.indexOf(waiter)
+        if (index !== -1) {
+          queue.splice(index, 1)
+        }
+        reject(new WorkspaceSpaceScanCancelledError())
+      }
+      queue.push(waiter)
+      if (signal) {
+        signal.addEventListener('abort', onAbort, { once: true })
+        if (signal.aborted) {
+          onAbort()
+        }
+      }
+    })
+    throwIfAborted(signal)
     active += 1
   }
 
@@ -71,9 +135,7 @@ function createAsyncLimiter(maxConcurrent: number): AsyncLimiter {
     } finally {
       active -= 1
       const next = queue.shift()
-      if (next) {
-        next()
-      }
+      next?.resolve()
     }
   }
 }
@@ -91,23 +153,32 @@ function looksLikeWindowsPath(pathValue: string): boolean {
   return /^[A-Za-z]:[\\/]/.test(pathValue) || pathValue.startsWith('\\\\')
 }
 
+function basenameFilesystemPath(pathValue: string): string {
+  return looksLikeWindowsPath(pathValue) ? win32.basename(pathValue) : posix.basename(pathValue)
+}
+
 function joinFilesystemPath(parent: string, child: string): string {
   return looksLikeWindowsPath(parent) ? win32.join(parent, child) : posix.join(parent, child)
 }
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 function normalizeLocalDuPath(pathValue: string): string {
-  const trimmed = pathValue.replace(/[\\/]+$/, '')
+  const separator = platform === 'win32' ? '\\' : '/'
+  const trimmed = pathValue.replace(new RegExp(`${escapeRegExp(separator)}+$`), '')
   return trimmed.length > 0 ? trimmed : pathValue
 }
 
 function parseDuDepthOneOutput(stdout: string): Map<string, number> {
   const sizes = new Map<string, number>()
   for (const line of stdout.split('\n')) {
-    const trimmed = line.trim()
-    if (!trimmed) {
+    const normalizedLine = line.endsWith('\r') ? line.slice(0, -1) : line
+    if (!normalizedLine) {
       continue
     }
-    const match = /^(\d+)\s+(.+)$/.exec(trimmed)
+    const match = /^(\d+)\s+(.+)$/.exec(normalizedLine)
     if (!match) {
       continue
     }
@@ -116,10 +187,14 @@ function parseDuDepthOneOutput(stdout: string): Map<string, number> {
   return sizes
 }
 
-async function readLocalDuDepthOne(rootPath: string): Promise<Map<string, number>> {
+async function readLocalDuDepthOne(
+  rootPath: string,
+  signal?: AbortSignal
+): Promise<Map<string, number>> {
   const { stdout } = await execFileAsync('du', ['-k', '-d', '1', rootPath], {
     encoding: 'utf8',
     maxBuffer: DU_MAX_BUFFER_BYTES,
+    signal,
     timeout: DU_TIMEOUT_MS
   })
   return parseDuDepthOneOutput(stdout)
@@ -153,44 +228,6 @@ function toWorkspaceSpaceItem(stats: ScanStats): WorkspaceSpaceItem {
   }
 }
 
-function compactTopLevelItems(items: WorkspaceSpaceItem[]): {
-  topLevelItems: WorkspaceSpaceItem[]
-  omittedTopLevelItemCount: number
-  omittedTopLevelSizeBytes: number
-} {
-  const sorted = [...items].sort(
-    (a, b) => b.sizeBytes - a.sizeBytes || a.name.localeCompare(b.name)
-  )
-  if (sorted.length <= MAX_TOP_LEVEL_ITEMS) {
-    return {
-      topLevelItems: sorted,
-      omittedTopLevelItemCount: 0,
-      omittedTopLevelSizeBytes: 0
-    }
-  }
-
-  const visible = sorted.slice(0, MAX_TOP_LEVEL_ITEMS - 1)
-  const omitted = sorted.slice(MAX_TOP_LEVEL_ITEMS - 1)
-  const other = omitted.reduce<WorkspaceSpaceItem>(
-    (acc, item) => ({
-      ...acc,
-      sizeBytes: acc.sizeBytes + item.sizeBytes
-    }),
-    {
-      name: 'Other',
-      path: '',
-      kind: 'other',
-      sizeBytes: 0
-    }
-  )
-
-  return {
-    topLevelItems: [...visible, other],
-    omittedTopLevelItemCount: omitted.length,
-    omittedTopLevelSizeBytes: other.sizeBytes
-  }
-}
-
 function createBaseWorktreeRow(
   repo: Repo,
   worktree: Worktree,
@@ -244,12 +281,34 @@ function createUnavailableWorktreeRow(
   }
 }
 
+function createScannedWorktreeRow(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number,
+  scan: WorkspaceSpaceDirectoryScanResult
+): WorkspaceSpaceWorktree {
+  return {
+    ...createBaseWorktreeRow(repo, worktree, scannedAt),
+    status: 'ok',
+    error: null,
+    sizeBytes: scan.sizeBytes,
+    reclaimableBytes: worktree.isMainWorktree ? 0 : scan.sizeBytes,
+    skippedEntryCount: scan.skippedEntryCount,
+    topLevelItems: scan.topLevelItems,
+    omittedTopLevelItemCount: scan.omittedTopLevelItemCount,
+    omittedTopLevelSizeBytes: scan.omittedTopLevelSizeBytes
+  }
+}
+
 async function scanLocalEntry(
   entryPath: string,
   name: string,
-  limit: AsyncLimiter
+  limit: AsyncLimiter,
+  signal?: AbortSignal
 ): Promise<ScanStats> {
+  throwIfAborted(signal)
   const stats = await limit(() => lstat(entryPath))
+  throwIfAborted(signal)
 
   if (stats.isSymbolicLink()) {
     return {
@@ -289,8 +348,16 @@ async function scanLocalEntry(
   const childStats = await Promise.all(
     entries.map(async (entry): Promise<ScanStats | null> => {
       try {
-        return await scanLocalEntry(joinFilesystemPath(entryPath, entry.name), entry.name, limit)
-      } catch {
+        return await scanLocalEntry(
+          joinFilesystemPath(entryPath, entry.name),
+          entry.name,
+          limit,
+          signal
+        )
+      } catch (error) {
+        if (error instanceof WorkspaceSpaceScanCancelledError) {
+          throw error
+        }
         return null
       }
     })
@@ -322,8 +389,10 @@ async function scanRemoteEntry(
   name: string,
   provider: IFilesystemProvider,
   limit: AsyncLimiter,
+  signal?: AbortSignal,
   knownSymlink = false
 ): Promise<ScanStats> {
+  throwIfAborted(signal)
   if (knownSymlink) {
     return {
       name,
@@ -335,6 +404,7 @@ async function scanRemoteEntry(
   }
 
   const stats = await limit(() => provider.stat(entryPath))
+  throwIfAborted(signal)
   if (stats.type === 'symlink') {
     return {
       name,
@@ -358,7 +428,11 @@ async function scanRemoteEntry(
   let entries
   try {
     entries = await limit(() => provider.readDir(entryPath))
-  } catch {
+    throwIfAborted(signal)
+  } catch (error) {
+    if (error instanceof WorkspaceSpaceScanCancelledError) {
+      throw error
+    }
     return {
       name,
       path: entryPath,
@@ -376,9 +450,13 @@ async function scanRemoteEntry(
           entry.name,
           provider,
           limit,
+          signal,
           entry.isSymlink
         )
-      } catch {
+      } catch (error) {
+        if (error instanceof WorkspaceSpaceScanCancelledError) {
+          throw error
+        }
         return null
       }
     })
@@ -409,9 +487,12 @@ async function scanLocalTopLevelEntry(
   entryPath: string,
   name: string,
   duSizes: Map<string, number>,
-  limit: AsyncLimiter
+  limit: AsyncLimiter,
+  signal?: AbortSignal
 ): Promise<ScanStats> {
+  throwIfAborted(signal)
   const stats = await limit(() => lstat(entryPath))
+  throwIfAborted(signal)
 
   if (stats.isSymbolicLink()) {
     return {
@@ -445,13 +526,20 @@ async function scanLocalTopLevelEntry(
 async function scanLocalWorktreeWithDu(
   repo: Repo,
   worktree: Worktree,
-  scannedAt: number
+  scannedAt: number,
+  signal?: AbortSignal
 ): Promise<WorkspaceSpaceWorktree> {
+  throwIfAborted(signal)
   const rootStats = await lstat(worktree.path)
   if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
-    const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY)
-    const root = await scanLocalEntry(worktree.path, basename(worktree.path), limit)
-    const compact = compactTopLevelItems((root.children ?? []).map(toWorkspaceSpaceItem))
+    const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY, signal)
+    const root = await scanLocalEntry(
+      worktree.path,
+      basenameFilesystemPath(worktree.path),
+      limit,
+      signal
+    )
+    const compact = compactWorkspaceSpaceItems((root.children ?? []).map(toWorkspaceSpaceItem))
     return {
       ...createBaseWorktreeRow(repo, worktree, scannedAt),
       status: 'ok',
@@ -465,9 +553,10 @@ async function scanLocalWorktreeWithDu(
 
   const [entries, duSizes] = await Promise.all([
     readdir(worktree.path, { withFileTypes: true }),
-    readLocalDuDepthOne(worktree.path)
+    readLocalDuDepthOne(worktree.path, signal)
   ])
-  const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY)
+  throwIfAborted(signal)
+  const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY, signal)
   const childStats = await Promise.all(
     entries.map(async (entry): Promise<ScanStats | null> => {
       try {
@@ -475,9 +564,13 @@ async function scanLocalWorktreeWithDu(
           joinFilesystemPath(worktree.path, entry.name),
           entry.name,
           duSizes,
-          limit
+          limit,
+          signal
         )
-      } catch {
+      } catch (error) {
+        if (error instanceof WorkspaceSpaceScanCancelledError) {
+          throw error
+        }
         return null
       }
     })
@@ -487,7 +580,7 @@ async function scanLocalWorktreeWithDu(
   const rootSize =
     duSizes.get(normalizeLocalDuPath(worktree.path)) ??
     rootStats.size + children.reduce((sum, child) => sum + child.sizeBytes, 0)
-  const compact = compactTopLevelItems(children.map(toWorkspaceSpaceItem))
+  const compact = compactWorkspaceSpaceItems(children.map(toWorkspaceSpaceItem))
 
   return {
     ...createBaseWorktreeRow(repo, worktree, scannedAt),
@@ -503,12 +596,18 @@ async function scanLocalWorktreeWithDu(
 async function scanLocalWorktreeWithNode(
   repo: Repo,
   worktree: Worktree,
-  scannedAt: number
+  scannedAt: number,
+  signal?: AbortSignal
 ): Promise<WorkspaceSpaceWorktree> {
   try {
-    const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY)
-    const root = await scanLocalEntry(worktree.path, basename(worktree.path), limit)
-    const compact = compactTopLevelItems((root.children ?? []).map(toWorkspaceSpaceItem))
+    const limit = createAsyncLimiter(LOCAL_FS_CONCURRENCY, signal)
+    const root = await scanLocalEntry(
+      worktree.path,
+      basenameFilesystemPath(worktree.path),
+      limit,
+      signal
+    )
+    const compact = compactWorkspaceSpaceItems((root.children ?? []).map(toWorkspaceSpaceItem))
     return {
       ...createBaseWorktreeRow(repo, worktree, scannedAt),
       status: 'ok',
@@ -519,6 +618,9 @@ async function scanLocalWorktreeWithNode(
       ...compact
     }
   } catch (error) {
+    if (error instanceof WorkspaceSpaceScanCancelledError) {
+      throw error
+    }
     const classified = classifyError(error)
     return createUnavailableWorktreeRow(
       repo,
@@ -533,41 +635,70 @@ async function scanLocalWorktreeWithNode(
 async function scanLocalWorktree(
   repo: Repo,
   worktree: Worktree,
-  scannedAt: number
+  scannedAt: number,
+  signal?: AbortSignal
 ): Promise<WorkspaceSpaceWorktree> {
+  throwIfAborted(signal)
   if (platform !== 'win32') {
     try {
       // Why: JS per-file stats are too slow for large local workspace fleets;
       // POSIX du gives bounded top-level sizing without following symlinks.
-      return await scanLocalWorktreeWithDu(repo, worktree, scannedAt)
-    } catch {
+      return await scanLocalWorktreeWithDu(repo, worktree, scannedAt, signal)
+    } catch (error) {
+      throwIfAborted(signal)
+      if (error instanceof WorkspaceSpaceScanCancelledError) {
+        throw error
+      }
       // Fall through to the portable scanner so unsupported du variants or
       // permission edge cases still produce partial rows instead of failing.
     }
   }
-  return scanLocalWorktreeWithNode(repo, worktree, scannedAt)
+  return scanLocalWorktreeWithNode(repo, worktree, scannedAt, signal)
 }
 
 async function scanRemoteWorktree(
   repo: Repo,
   worktree: Worktree,
   scannedAt: number,
-  provider: IFilesystemProvider
+  provider: IFilesystemProvider,
+  signal?: AbortSignal
 ): Promise<WorkspaceSpaceWorktree> {
   try {
-    const limit = createAsyncLimiter(REMOTE_FS_CONCURRENCY)
-    const root = await scanRemoteEntry(worktree.path, basename(worktree.path), provider, limit)
-    const compact = compactTopLevelItems((root.children ?? []).map(toWorkspaceSpaceItem))
-    return {
-      ...createBaseWorktreeRow(repo, worktree, scannedAt),
-      status: 'ok',
-      error: null,
+    if (provider.scanWorkspaceSpace) {
+      try {
+        const scan = await provider.scanWorkspaceSpace(worktree.path, { signal })
+        return createScannedWorktreeRow(repo, worktree, scannedAt, scan)
+      } catch (error) {
+        if (isAbortError(error)) {
+          throw new WorkspaceSpaceScanCancelledError()
+        }
+        if (!isRelayMethodNotFoundError(error)) {
+          throw error
+        }
+        // Why: old SSH relays do not know the bulk Space scan method. Fall
+        // back to the request-by-request walker instead of marking SSH rows
+        // unavailable after an app upgrade.
+      }
+    }
+
+    const limit = createAsyncLimiter(REMOTE_FS_CONCURRENCY, signal)
+    const root = await scanRemoteEntry(
+      worktree.path,
+      basenameFilesystemPath(worktree.path),
+      provider,
+      limit,
+      signal
+    )
+    const compact = compactWorkspaceSpaceItems((root.children ?? []).map(toWorkspaceSpaceItem))
+    return createScannedWorktreeRow(repo, worktree, scannedAt, {
       sizeBytes: root.sizeBytes,
-      reclaimableBytes: worktree.isMainWorktree ? 0 : root.sizeBytes,
       skippedEntryCount: root.skippedEntryCount,
       ...compact
-    }
+    })
   } catch (error) {
+    if (error instanceof WorkspaceSpaceScanCancelledError) {
+      throw error
+    }
     const classified = classifyError(error)
     return createUnavailableWorktreeRow(
       repo,
@@ -579,8 +710,12 @@ async function scanRemoteWorktree(
   }
 }
 
-async function listWorktreesForSpaceScan(repo: Repo): Promise<WorktreeListResult> {
+async function listWorktreesForSpaceScan(
+  repo: Repo,
+  signal?: AbortSignal
+): Promise<WorktreeListResult> {
   try {
+    throwIfAborted(signal)
     if (isFolderRepo(repo)) {
       return { ok: true, worktrees: [createFolderWorktree(repo)] }
     }
@@ -593,10 +728,17 @@ async function listWorktreesForSpaceScan(repo: Repo): Promise<WorktreeListResult
           error: `SSH connection "${repo.connectionId}" is not connected.`
         }
       }
-      return { ok: true, worktrees: await provider.listWorktrees(repo.path) }
+      const worktrees = await provider.listWorktrees(repo.path, { signal })
+      throwIfAborted(signal)
+      return { ok: true, worktrees }
     }
-    return { ok: true, worktrees: await listRepoWorktrees(repo) }
+    const worktrees = await listRepoWorktrees(repo)
+    throwIfAborted(signal)
+    return { ok: true, worktrees }
   } catch (error) {
+    if (error instanceof WorkspaceSpaceScanCancelledError) {
+      throw error
+    }
     const classified = classifyError(error)
     return { ok: false, status: classified.status, error: classified.message }
   }
@@ -607,9 +749,38 @@ function mergeForSpaceScan(repo: Repo, gitWorktree: GitWorktreeInfo, store: Stor
   return mergeWorktree(repo.id, gitWorktree, store.getWorktreeMeta(worktreeId), repo.displayName)
 }
 
-async function scanRepo(repo: Repo, scannedAt: number, store: Store): Promise<RepoScanResult> {
-  const listed = await listWorktreesForSpaceScan(repo)
+function reportProgress(
+  progress: WorkspaceSpaceProgressState,
+  updates: Partial<WorkspaceSpaceProgressState>,
+  onProgress: WorkspaceSpaceAnalyzeOptions['onProgress']
+): void {
+  Object.assign(progress, updates, { updatedAt: Date.now() })
+  onProgress?.({ ...progress })
+}
+
+async function scanRepo(
+  repo: Repo,
+  scannedAt: number,
+  store: Store,
+  progress: WorkspaceSpaceProgressState,
+  options: WorkspaceSpaceAnalyzeOptions
+): Promise<RepoScanResult> {
+  throwIfAborted(options.signal)
+  reportProgress(
+    progress,
+    {
+      currentRepoDisplayName: repo.displayName,
+      currentWorktreeDisplayName: null
+    },
+    options.onProgress
+  )
+  const listed = await listWorktreesForSpaceScan(repo, options.signal)
   if (!listed.ok) {
+    reportProgress(
+      progress,
+      { scannedRepoCount: progress.scannedRepoCount + 1 },
+      options.onProgress
+    )
     return {
       worktrees: [],
       summary: {
@@ -630,22 +801,49 @@ async function scanRepo(repo: Repo, scannedAt: number, store: Store): Promise<Re
   const worktrees = listed.worktrees.map((gitWorktree) =>
     mergeForSpaceScan(repo, gitWorktree, store)
   )
+  reportProgress(
+    progress,
+    { totalWorktreeCount: progress.totalWorktreeCount + worktrees.length },
+    options.onProgress
+  )
   const remoteProvider = repo.connectionId ? getSshFilesystemProvider(repo.connectionId) : undefined
   const rows = await mapLimit(worktrees, WORKTREE_SCAN_CONCURRENCY, async (worktree) => {
-    if (repo.connectionId) {
-      if (!remoteProvider) {
-        return createUnavailableWorktreeRow(
-          repo,
-          worktree,
-          scannedAt,
-          'unavailable',
-          `SSH filesystem for "${repo.connectionId}" is not connected.`
-        )
-      }
-      return scanRemoteWorktree(repo, worktree, scannedAt, remoteProvider)
-    }
-    return scanLocalWorktree(repo, worktree, scannedAt)
+    throwIfAborted(options.signal)
+    reportProgress(
+      progress,
+      {
+        currentRepoDisplayName: repo.displayName,
+        currentWorktreeDisplayName: worktree.displayName
+      },
+      options.onProgress
+    )
+    const row: WorkspaceSpaceWorktree = repo.connectionId
+      ? remoteProvider
+        ? await scanRemoteWorktree(repo, worktree, scannedAt, remoteProvider, options.signal)
+        : createUnavailableWorktreeRow(
+            repo,
+            worktree,
+            scannedAt,
+            'unavailable',
+            `SSH filesystem for "${repo.connectionId}" is not connected.`
+          )
+      : await scanLocalWorktree(repo, worktree, scannedAt, options.signal)
+    reportProgress(
+      progress,
+      { scannedWorktreeCount: progress.scannedWorktreeCount + 1 },
+      options.onProgress
+    )
+    return row
   })
+  reportProgress(
+    progress,
+    {
+      scannedRepoCount: progress.scannedRepoCount + 1,
+      currentRepoDisplayName: repo.displayName,
+      currentWorktreeDisplayName: null
+    },
+    options.onProgress
+  )
 
   return {
     worktrees: rows,
@@ -664,11 +862,30 @@ async function scanRepo(repo: Repo, scannedAt: number, store: Store): Promise<Re
   }
 }
 
-export async function analyzeWorkspaceSpace(store: Store): Promise<WorkspaceSpaceAnalysis> {
+export async function analyzeWorkspaceSpace(
+  store: Store,
+  options: WorkspaceSpaceAnalyzeOptions = {}
+): Promise<WorkspaceSpaceAnalysis> {
+  throwIfAborted(options.signal)
   const scannedAt = Date.now()
-  const repoResults = await mapLimit(store.getRepos(), 2, (repo) =>
-    scanRepo(repo, scannedAt, store)
+  const reposToScan = store.getRepos()
+  const progress: WorkspaceSpaceProgressState = {
+    scanId: options.scanId ?? String(scannedAt),
+    state: 'running',
+    startedAt: scannedAt,
+    updatedAt: scannedAt,
+    totalRepoCount: reposToScan.length,
+    scannedRepoCount: 0,
+    totalWorktreeCount: 0,
+    scannedWorktreeCount: 0,
+    currentRepoDisplayName: null,
+    currentWorktreeDisplayName: null
+  }
+  options.onProgress?.({ ...progress })
+  const repoResults = await mapLimit(reposToScan, 2, (repo) =>
+    scanRepo(repo, scannedAt, store, progress, options)
   )
+  throwIfAborted(options.signal)
   const repos = repoResults.map((result) => result.summary)
   const worktrees = repoResults
     .flatMap((result) => result.worktrees)
diff --git a/src/main/worktree-removal-safety.ts b/src/main/worktree-removal-safety.ts
new file mode 100644
index 00000000000..dcd465c5863
--- /dev/null
+++ b/src/main/worktree-removal-safety.ts
@@ -0,0 +1,79 @@
+import { lstat } from 'fs/promises'
+import { homedir } from 'os'
+import { posix, win32 } from 'path'
+import type { GitWorktreeInfo } from '../shared/types'
+import { areWorktreePathsEqual } from './ipc/worktree-logic'
+
+type PathOps = typeof posix
+
+function looksLikeWindowsPath(pathValue: string): boolean {
+  return /^[A-Za-z]:[\\/]/.test(pathValue) || pathValue.startsWith('\\\\')
+}
+
+function getPathOps(...paths: string[]): PathOps {
+  return paths.some(looksLikeWindowsPath) ? win32 : posix
+}
+
+function containsPath(parentPath: string, childPath: string, pathOps: PathOps): boolean {
+  const relativePath = pathOps.relative(parentPath, childPath)
+  return (
+    relativePath === '' ||
+    (!!relativePath && !relativePath.startsWith('..') && !pathOps.isAbsolute(relativePath))
+  )
+}
+
+export function isDangerousWorktreeRemovalPath(worktreePath: string, repoPath: string): boolean {
+  if (!worktreePath.trim()) {
+    return true
+  }
+
+  if (areWorktreePathsEqual(worktreePath, repoPath)) {
+    return true
+  }
+
+  const pathOps = getPathOps(worktreePath, repoPath)
+  const resolvedWorktreePath = pathOps.resolve(worktreePath)
+  const rootPath = pathOps.parse(resolvedWorktreePath).root
+  if (resolvedWorktreePath === rootPath) {
+    return true
+  }
+
+  const resolvedRepoPath = pathOps.resolve(repoPath)
+  if (containsPath(resolvedWorktreePath, resolvedRepoPath, pathOps)) {
+    return true
+  }
+
+  const homePath = homedir()
+  return !!homePath && containsPath(resolvedWorktreePath, pathOps.resolve(homePath), pathOps)
+}
+
+export function getRegisteredDeletableWorktree(
+  repoPath: string,
+  requestedWorktreePath: string,
+  worktrees: readonly GitWorktreeInfo[]
+): GitWorktreeInfo {
+  const worktree = worktrees.find((item) => areWorktreePathsEqual(item.path, requestedWorktreePath))
+  if (!worktree) {
+    throw new Error(`Refusing to delete unregistered worktree path: ${requestedWorktreePath}`)
+  }
+  if (worktree.isMainWorktree || isDangerousWorktreeRemovalPath(worktree.path, repoPath)) {
+    throw new Error(`Refusing to delete protected worktree path: ${worktree.path}`)
+  }
+  return worktree
+}
+
+export async function canSafelyRemoveOrphanedWorktreeDirectory(
+  worktreePath: string,
+  repoPath: string
+): Promise<boolean> {
+  if (isDangerousWorktreeRemovalPath(worktreePath, repoPath)) {
+    return false
+  }
+
+  try {
+    const gitEntry = await lstat(getPathOps(worktreePath).join(worktreePath, '.git'))
+    return gitEntry.isFile() || gitEntry.isDirectory() || gitEntry.isSymbolicLink()
+  } catch {
+    return false
+  }
+}
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 533879c1fc7..9140e0e3133 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -172,7 +172,10 @@ import type {
 } from '../shared/claude-usage-types'
 import type { RateLimitState } from '../shared/rate-limit-types'
 import type { SpeechModelManifest, SpeechModelState } from '../shared/speech-types'
-import type { WorkspaceSpaceAnalysis } from '../shared/workspace-space-types'
+import type {
+  WorkspaceSpaceAnalyzeResult,
+  WorkspaceSpaceScanProgress
+} from '../shared/workspace-space-types'
 import type { GhAuthDiagnostic } from '../shared/github-auth-types'
 import type {
   SshConnectionState,
@@ -535,7 +538,9 @@ export type PreloadApi = {
     ) => () => void
   }
   workspaceSpace: {
-    analyze: () => Promise<WorkspaceSpaceAnalysis>
+    analyze: () => Promise<WorkspaceSpaceAnalyzeResult>
+    cancel: () => Promise<boolean>
+    onProgress: (callback: (progress: WorkspaceSpaceScanProgress) => void) => () => void
   }
   pty: {
     spawn: (opts: {
diff --git a/src/preload/index.ts b/src/preload/index.ts
index b9b5d34d123..6a203c2f204 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -40,7 +40,10 @@ import type {
   RuntimeMobileMarkdownResponse
 } from '../shared/mobile-markdown-document'
 import type { RateLimitState } from '../shared/rate-limit-types'
-import type { WorkspaceSpaceAnalysis } from '../shared/workspace-space-types'
+import type {
+  WorkspaceSpaceAnalyzeResult,
+  WorkspaceSpaceScanProgress
+} from '../shared/workspace-space-types'
 import type { GhAuthDiagnostic } from '../shared/github-auth-types'
 import type {
   AddIssueCommentBySlugArgs,
@@ -495,7 +498,17 @@ const api = {
   },
 
   workspaceSpace: {
-    analyze: (): Promise<WorkspaceSpaceAnalysis> => ipcRenderer.invoke('workspaceSpace:analyze')
+    analyze: (): Promise<WorkspaceSpaceAnalyzeResult> =>
+      ipcRenderer.invoke('workspaceSpace:analyze'),
+    cancel: (): Promise<boolean> => ipcRenderer.invoke('workspaceSpace:cancel'),
+    onProgress: (callback: (progress: WorkspaceSpaceScanProgress) => void): (() => void) => {
+      const listener = (
+        _event: Electron.IpcRendererEvent,
+        progress: WorkspaceSpaceScanProgress
+      ): void => callback(progress)
+      ipcRenderer.on('workspaceSpace:progress', listener)
+      return () => ipcRenderer.removeListener('workspaceSpace:progress', listener)
+    }
   },
 
   pty: {
diff --git a/src/relay/dispatcher.test.ts b/src/relay/dispatcher.test.ts
index e5bf73f6d48..53733dcabd2 100644
--- a/src/relay/dispatcher.test.ts
+++ b/src/relay/dispatcher.test.ts
@@ -247,4 +247,26 @@ describe('RelayDispatcher', () => {
     })
     expect(responses).toHaveLength(0)
   })
+
+  it('aborts in-flight request contexts after client invalidation', async () => {
+    let observedSignal: AbortSignal | undefined
+    let resolveHandler!: () => void
+    dispatcher.onRequest(
+      'slow.method',
+      (_params, context) =>
+        new Promise((resolve) => {
+          observedSignal = context.signal
+          resolveHandler = () => resolve(null)
+        })
+    )
+
+    const req: JsonRpcRequest = { jsonrpc: '2.0', id: 100, method: 'slow.method' }
+    dispatcher.feed(encodeJsonRpcFrame(req, 1, 0))
+    await vi.advanceTimersByTimeAsync(0)
+    dispatcher.invalidateClient()
+
+    expect(observedSignal?.aborted).toBe(true)
+    resolveHandler()
+    await vi.advanceTimersByTimeAsync(0)
+  })
 })
diff --git a/src/relay/dispatcher.ts b/src/relay/dispatcher.ts
index b827195ba4b..1cd2cce034b 100644
--- a/src/relay/dispatcher.ts
+++ b/src/relay/dispatcher.ts
@@ -13,6 +13,7 @@ import {
 
 export type RequestContext = {
   isStale: () => boolean
+  signal?: AbortSignal
 }
 
 export type MethodHandler = (
@@ -27,6 +28,7 @@ export class RelayDispatcher {
   private write: (data: Buffer) => void
   private requestHandlers = new Map<string, MethodHandler>()
   private notificationHandlers = new Map<string, NotificationHandler>()
+  private requestAbortControllers = new Map<number, AbortController>()
   private nextOutgoingSeq = 1
   private highestReceivedSeq = 0
   private keepaliveTimer: ReturnType<typeof setInterval> | null = null
@@ -54,6 +56,7 @@ export class RelayDispatcher {
   // up — causing the client's unacked-timeout checker to accumulate stale
   // timestamps that could eventually fire a false connection-dead signal.
   setWrite(write: (data: Buffer) => void): void {
+    this.abortActiveRequests()
     this.write = write
     this.nextOutgoingSeq = 1
     this.highestReceivedSeq = 0
@@ -65,6 +68,7 @@ export class RelayDispatcher {
   // disconnects even if no replacement has connected yet. Otherwise a late
   // pty.spawn/fs.watch completion can create remote state nobody can own.
   invalidateClient(): void {
+    this.abortActiveRequests()
     this.generation++
   }
 
@@ -76,6 +80,13 @@ export class RelayDispatcher {
     this.notificationHandlers.set(method, handler)
   }
 
+  private abortActiveRequests(): void {
+    for (const controller of this.requestAbortControllers.values()) {
+      controller.abort()
+    }
+    this.requestAbortControllers.clear()
+  }
+
   feed(data: Buffer): void {
     if (this.disposed) {
       return
@@ -157,26 +168,37 @@ export class RelayDispatcher {
     // space. Sending it would misroute — the new client may have issued
     // its own request with the same JSON-RPC id.
     const gen = this.generation
+    const abortController = new AbortController()
+    this.requestAbortControllers.set(req.id, abortController)
     const context: RequestContext = {
-      isStale: () => this.generation !== gen
+      isStale: () => this.generation !== gen || abortController.signal.aborted,
+      signal: abortController.signal
     }
     try {
       const result = await handler(req.params ?? {}, context)
-      if (this.generation !== gen) {
+      if (this.generation !== gen || abortController.signal.aborted) {
         return
       }
       this.sendResponse(req.id, result)
     } catch (err) {
-      if (this.generation !== gen) {
+      if (this.generation !== gen || abortController.signal.aborted) {
         return
       }
       const message = err instanceof Error ? err.message : String(err)
       const code = (err as { code?: number }).code ?? -32000
       this.sendResponse(req.id, undefined, { code, message })
+    } finally {
+      this.requestAbortControllers.delete(req.id)
     }
   }
 
   private handleNotification(notif: JsonRpcNotification): void {
+    if (notif.method === 'rpc.cancel') {
+      const id = Number((notif.params ?? {}).id)
+      const controller = this.requestAbortControllers.get(id)
+      controller?.abort()
+      return
+    }
     const handler = this.notificationHandlers.get(notif.method)
     if (handler) {
       handler(notif.params ?? {})
diff --git a/src/relay/fs-handler.test.ts b/src/relay/fs-handler.test.ts
index 590e9ea4665..d17df8c44a6 100644
--- a/src/relay/fs-handler.test.ts
+++ b/src/relay/fs-handler.test.ts
@@ -1,5 +1,5 @@
 /* eslint-disable max-lines -- Why: this suite covers relay filesystem RPCs,
-   file watcher lifecycle edges, and cross-platform path behavior together. */
+   Space scans, file watcher lifecycle edges, and cross-platform path behavior together. */
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { FsHandler } from './fs-handler'
 import { RelayContext } from './context'
@@ -101,6 +101,7 @@ describe('FsHandler', () => {
     expect(methods).toContain('fs.realpath')
     expect(methods).toContain('fs.search')
     expect(methods).toContain('fs.listFiles')
+    expect(methods).toContain('fs.workspaceSpaceScan')
     expect(methods).toContain('fs.watch')
 
     const notifMethods = Array.from(dispatcher._notificationHandlers.keys())
@@ -247,6 +248,25 @@ describe('FsHandler', () => {
     expect(result.type).toBe('directory')
   })
 
+  it('workspaceSpaceScan returns bounded top-level size details', async () => {
+    mkdirSync(path.join(tmpDir, 'node_modules'))
+    writeFileSync(path.join(tmpDir, 'node_modules', 'pkg.js'), Buffer.alloc(512))
+    writeFileSync(path.join(tmpDir, 'file.log'), Buffer.alloc(128))
+
+    const result = (await dispatcher.callRequest(
+      'fs.workspaceSpaceScan',
+      { rootPath: tmpDir },
+      { isStale: () => false }
+    )) as {
+      sizeBytes: number
+      topLevelItems: { name: string; sizeBytes: number }[]
+    }
+
+    expect(result.sizeBytes).toBeGreaterThanOrEqual(640)
+    expect(result.topLevelItems.map((item) => item.name)).toContain('node_modules')
+    expect(result.topLevelItems.map((item) => item.name)).toContain('file.log')
+  })
+
   it('deletePath removes files', async () => {
     const filePath = path.join(tmpDir, 'to-delete.txt')
     writeFileSync(filePath, 'bye')
diff --git a/src/relay/fs-handler.ts b/src/relay/fs-handler.ts
index 3bedb3c856b..a2d6f2aa2a3 100644
--- a/src/relay/fs-handler.ts
+++ b/src/relay/fs-handler.ts
@@ -1,5 +1,5 @@
 /* eslint-disable max-lines -- Why: relay filesystem request handling shares
-   path expansion, file IO, search, streaming reads, and watch lifecycle state. */
+   path expansion, file IO, search, streaming reads, Space scans, and watch lifecycle state. */
 import { readdir, writeFile, stat, lstat, mkdir, rename, cp, rm, realpath } from 'fs/promises'
 import { execFile } from 'child_process'
 import { join } from 'path'
@@ -20,6 +20,7 @@ import { buildExcludePathPrefixes } from '../shared/quick-open-filter'
 import { buildInstallRgMessage } from './fs-handler-install-rg'
 import { readRelayFileContent, readRelayFileStreamMetadata } from './fs-handler-file-read'
 import { RelayStreamRegistry } from './fs-stream-registry'
+import { scanWorkspaceSpaceDirectory } from './workspace-space-scan'
 
 type WatchState = {
   rootPath: string
@@ -72,6 +73,7 @@ export class FsHandler {
     this.dispatcher.onRequest('fs.realpath', (p) => this.realpath(p))
     this.dispatcher.onRequest('fs.search', (p) => this.search(p))
     this.dispatcher.onRequest('fs.listFiles', (p) => this.listFiles(p))
+    this.dispatcher.onRequest('fs.workspaceSpaceScan', (p, c) => this.workspaceSpaceScan(p, c))
     this.dispatcher.onRequest('fs.watch', (p, context) => this.watch(p, context))
     this.dispatcher.onNotification('fs.unwatch', (p) => this.unwatch(p))
     this.dispatcher.onNotification('fs.cancelStream', (p) => this.cancelStream(p))
@@ -279,6 +281,11 @@ export class FsHandler {
     }
   }
 
+  private async workspaceSpaceScan(params: Record<string, unknown>, context: RequestContext) {
+    const rootPath = expandTilde(params.rootPath as string)
+    return scanWorkspaceSpaceDirectory(rootPath, context)
+  }
+
   private async watch(params: Record<string, unknown>, context?: RequestContext) {
     const rootPath = expandTilde(params.rootPath as string)
 
diff --git a/src/relay/workspace-space-scan.ts b/src/relay/workspace-space-scan.ts
new file mode 100644
index 00000000000..cc823457142
--- /dev/null
+++ b/src/relay/workspace-space-scan.ts
@@ -0,0 +1,375 @@
+/* eslint-disable max-lines -- Why: local and relay Space scans share the same
+   cancellation, symlink, and top-level compaction semantics in one scanner. */
+import { execFile } from 'node:child_process'
+import type { Dirent } from 'node:fs'
+import { lstat, readdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { platform } from 'node:process'
+import { promisify } from 'node:util'
+import type {
+  WorkspaceSpaceDirectoryScanResult,
+  WorkspaceSpaceItem,
+  WorkspaceSpaceItemKind
+} from '../shared/workspace-space-types'
+import { compactWorkspaceSpaceItems } from '../shared/workspace-space-compaction'
+import type { RequestContext } from './dispatcher'
+
+const RELAY_FS_CONCURRENCY = 48
+const DU_TIMEOUT_MS = 120_000
+const DU_MAX_BUFFER_BYTES = 16 * 1024 * 1024
+const execFileAsync = promisify(execFile)
+
+type AsyncLimiter = <T>(task: () => Promise<T>) => Promise<T>
+
+type ScanStats = {
+  name: string
+  path: string
+  kind: WorkspaceSpaceItemKind
+  sizeBytes: number
+  skippedEntryCount: number
+}
+
+class RelayWorkspaceSpaceScanCancelledError extends Error {
+  constructor() {
+    super('Workspace space scan cancelled')
+    this.name = 'RelayWorkspaceSpaceScanCancelledError'
+  }
+}
+
+function throwIfCancelled(context: RequestContext): void {
+  if (context.isStale() || context.signal?.aborted) {
+    throw new RelayWorkspaceSpaceScanCancelledError()
+  }
+}
+
+function createAsyncLimiter(maxConcurrent: number, context: RequestContext): AsyncLimiter {
+  let active = 0
+  const queue: { resolve: () => void }[] = []
+
+  const acquire = async (): Promise<void> => {
+    throwIfCancelled(context)
+    if (active < maxConcurrent) {
+      active += 1
+      return
+    }
+    await new Promise<void>((resolve, reject) => {
+      let onAbort: (() => void) | null = null
+      const waiter = {
+        resolve: () => {
+          if (onAbort) {
+            context.signal?.removeEventListener('abort', onAbort)
+          }
+          resolve()
+        }
+      }
+      onAbort = () => {
+        const index = queue.indexOf(waiter)
+        if (index !== -1) {
+          queue.splice(index, 1)
+        }
+        reject(new RelayWorkspaceSpaceScanCancelledError())
+      }
+      queue.push(waiter)
+      if (context.signal) {
+        context.signal.addEventListener('abort', onAbort, { once: true })
+        if (context.signal.aborted) {
+          onAbort()
+        }
+      }
+    })
+    throwIfCancelled(context)
+    active += 1
+  }
+
+  return async <T>(task: () => Promise<T>): Promise<T> => {
+    await acquire()
+    try {
+      return await task()
+    } finally {
+      active -= 1
+      const next = queue.shift()
+      next?.resolve()
+    }
+  }
+}
+
+function normalizeDuPath(pathValue: string): string {
+  const trimmed = pathValue.replace(/\/+$/, '')
+  return trimmed.length > 0 ? trimmed : pathValue
+}
+
+function parseDuDepthOneOutput(stdout: string): Map<string, number> {
+  const sizes = new Map<string, number>()
+  for (const line of stdout.split('\n')) {
+    const normalizedLine = line.endsWith('\r') ? line.slice(0, -1) : line
+    if (!normalizedLine) {
+      continue
+    }
+    const match = /^(\d+)\s+(.+)$/.exec(normalizedLine)
+    if (!match) {
+      continue
+    }
+    sizes.set(normalizeDuPath(match[2]), Number(match[1]) * 1024)
+  }
+  return sizes
+}
+
+async function readDuDepthOne(
+  rootPath: string,
+  context: RequestContext
+): Promise<Map<string, number>> {
+  throwIfCancelled(context)
+  const { stdout } = await execFileAsync('du', ['-k', '-d', '1', rootPath], {
+    encoding: 'utf8',
+    maxBuffer: DU_MAX_BUFFER_BYTES,
+    signal: context.signal,
+    timeout: DU_TIMEOUT_MS
+  })
+  throwIfCancelled(context)
+  return parseDuDepthOneOutput(stdout)
+}
+
+function toWorkspaceSpaceItem(stats: ScanStats): WorkspaceSpaceItem {
+  return {
+    name: stats.name,
+    path: stats.path,
+    kind: stats.kind,
+    sizeBytes: stats.sizeBytes
+  }
+}
+
+async function scanTopLevelEntryWithDu(
+  entryPath: string,
+  name: string,
+  duSizes: Map<string, number>,
+  limit: AsyncLimiter,
+  context: RequestContext
+): Promise<ScanStats> {
+  throwIfCancelled(context)
+  const stats = await limit(() => lstat(entryPath))
+  throwIfCancelled(context)
+
+  if (stats.isSymbolicLink()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'symlink',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  if (!stats.isDirectory()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'file',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  return {
+    name,
+    path: entryPath,
+    kind: 'directory',
+    sizeBytes: duSizes.get(normalizeDuPath(entryPath)) ?? stats.size,
+    skippedEntryCount: 0
+  }
+}
+
+async function scanEntryAggregate(
+  entryPath: string,
+  name: string,
+  limit: AsyncLimiter,
+  context: RequestContext
+): Promise<ScanStats> {
+  throwIfCancelled(context)
+  const stats = await limit(() => lstat(entryPath))
+  throwIfCancelled(context)
+
+  if (stats.isSymbolicLink()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'symlink',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  if (!stats.isDirectory()) {
+    return {
+      name,
+      path: entryPath,
+      kind: 'file',
+      sizeBytes: stats.size,
+      skippedEntryCount: 0
+    }
+  }
+
+  let entries: Dirent[]
+  try {
+    entries = await limit(() => readdir(entryPath, { withFileTypes: true }))
+  } catch {
+    return {
+      name,
+      path: entryPath,
+      kind: 'directory',
+      sizeBytes: stats.size,
+      skippedEntryCount: 1
+    }
+  }
+
+  const childStats = await Promise.all(
+    entries.map(async (entry): Promise<ScanStats | null> => {
+      try {
+        return await scanEntryAggregate(join(entryPath, entry.name), entry.name, limit, context)
+      } catch (error) {
+        if (error instanceof RelayWorkspaceSpaceScanCancelledError) {
+          throw error
+        }
+        return null
+      }
+    })
+  )
+
+  let sizeBytes = stats.size
+  let skippedEntryCount = 0
+  for (const child of childStats) {
+    if (!child) {
+      skippedEntryCount += 1
+      continue
+    }
+    sizeBytes += child.sizeBytes
+    skippedEntryCount += child.skippedEntryCount
+  }
+
+  return {
+    name,
+    path: entryPath,
+    kind: 'directory',
+    sizeBytes,
+    skippedEntryCount
+  }
+}
+
+async function scanDirectoryWithDu(
+  rootPath: string,
+  context: RequestContext
+): Promise<WorkspaceSpaceDirectoryScanResult> {
+  throwIfCancelled(context)
+  const rootStats = await lstat(rootPath)
+  throwIfCancelled(context)
+  if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+    return scanDirectoryWithNode(rootPath, context)
+  }
+
+  const [entries, duSizes] = await Promise.all([
+    readdir(rootPath, { withFileTypes: true }),
+    readDuDepthOne(rootPath, context)
+  ])
+  throwIfCancelled(context)
+  const limit = createAsyncLimiter(RELAY_FS_CONCURRENCY, context)
+  const childStats = await Promise.all(
+    entries.map(async (entry): Promise<ScanStats | null> => {
+      try {
+        return await scanTopLevelEntryWithDu(
+          join(rootPath, entry.name),
+          entry.name,
+          duSizes,
+          limit,
+          context
+        )
+      } catch (error) {
+        if (error instanceof RelayWorkspaceSpaceScanCancelledError) {
+          throw error
+        }
+        return null
+      }
+    })
+  )
+  const children = childStats.filter((child): child is ScanStats => child !== null)
+  const compact = compactWorkspaceSpaceItems(children.map(toWorkspaceSpaceItem))
+
+  return {
+    sizeBytes:
+      duSizes.get(normalizeDuPath(rootPath)) ??
+      rootStats.size + children.reduce((sum, child) => sum + child.sizeBytes, 0),
+    skippedEntryCount: childStats.length - children.length,
+    ...compact
+  }
+}
+
+async function scanDirectoryWithNode(
+  rootPath: string,
+  context: RequestContext
+): Promise<WorkspaceSpaceDirectoryScanResult> {
+  throwIfCancelled(context)
+  const limit = createAsyncLimiter(RELAY_FS_CONCURRENCY, context)
+  const rootStats = await lstat(rootPath)
+  throwIfCancelled(context)
+  if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+    const root = await scanEntryAggregate(rootPath, basename(rootPath), limit, context)
+    return {
+      sizeBytes: root.sizeBytes,
+      skippedEntryCount: root.skippedEntryCount,
+      topLevelItems: [],
+      omittedTopLevelItemCount: 0,
+      omittedTopLevelSizeBytes: 0
+    }
+  }
+
+  let entries: Dirent[]
+  try {
+    entries = await readdir(rootPath, { withFileTypes: true })
+  } catch {
+    return {
+      sizeBytes: rootStats.size,
+      skippedEntryCount: 1,
+      topLevelItems: [],
+      omittedTopLevelItemCount: 0,
+      omittedTopLevelSizeBytes: 0
+    }
+  }
+
+  const childStats = await Promise.all(
+    entries.map(async (entry): Promise<ScanStats | null> => {
+      try {
+        return await scanEntryAggregate(join(rootPath, entry.name), entry.name, limit, context)
+      } catch (error) {
+        if (error instanceof RelayWorkspaceSpaceScanCancelledError) {
+          throw error
+        }
+        return null
+      }
+    })
+  )
+  const children = childStats.filter((child): child is ScanStats => child !== null)
+  const compact = compactWorkspaceSpaceItems(children.map(toWorkspaceSpaceItem))
+
+  return {
+    sizeBytes: rootStats.size + children.reduce((sum, child) => sum + child.sizeBytes, 0),
+    skippedEntryCount:
+      children.reduce((sum, child) => sum + child.skippedEntryCount, 0) +
+      childStats.length -
+      children.length,
+    ...compact
+  }
+}
+
+export async function scanWorkspaceSpaceDirectory(
+  rootPath: string,
+  context: RequestContext
+): Promise<WorkspaceSpaceDirectoryScanResult> {
+  if (platform !== 'win32') {
+    try {
+      return await scanDirectoryWithDu(rootPath, context)
+    } catch (error) {
+      if (error instanceof RelayWorkspaceSpaceScanCancelledError) {
+        throw error
+      }
+    }
+  }
+  return scanDirectoryWithNode(rootPath, context)
+}
diff --git a/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx b/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx
index 335a7f5b2c2..2854673162a 100644
--- a/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx
+++ b/src/renderer/src/components/sidebar/DeleteWorktreeDialog.tsx
@@ -11,7 +11,7 @@ import { Button } from '@/components/ui/button'
 import { AlertTriangle, Check, LoaderCircle, Trash2 } from 'lucide-react'
 import { useAppStore } from '@/store'
 import { toast } from 'sonner'
-import { runWorktreeDeleteWithToast } from './delete-worktree-flow'
+import { runWorktreeDeletesSequentially } from './delete-worktree-flow'
 
 const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
   const activeModal = useAppStore((s) => s.activeModal)
@@ -58,6 +58,7 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
   const canForceDelete = deleteState?.canForceDelete ?? false
   const confirmButtonRef = useRef<HTMLButtonElement>(null)
   const isBatchDelete = worktreeIds.length > 1
+  const allowSkipConfirm = !isBatchDelete && modalData.allowSkipConfirm !== false
   // Why: the main worktree is the repo's original clone directory — `git worktree remove`
   // always rejects it. We block the delete button upfront so the user doesn't have to
   // discover this limitation via a confusing force-delete dead-end.
@@ -136,7 +137,7 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
       // Saving "don't ask again" from that state would conflate the recovery
       // action with a broader preference. Only persist the preference on the
       // primary (non-force) confirmation so users intentionally opt in.
-      if (dontAskAgain && !force) {
+      if (dontAskAgain && allowSkipConfirm && !force) {
         persistDontAskAgainPreference()
       }
       if (force) {
@@ -160,12 +161,7 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
             })
           })
       } else {
-        void Promise.all(
-          worktrees.map((target) => runWorktreeDeleteWithToast(target.id, target.displayName))
-        ).then((results) => {
-          const deletedIds = worktrees
-            .filter((_, index) => results[index])
-            .map((target) => target.id)
+        void runWorktreeDeletesSequentially(worktrees).then((deletedIds) => {
           if (deletedIds.length > 0) {
             onDeleted?.(deletedIds)
           }
@@ -176,6 +172,7 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
     [
       closeModal,
       dontAskAgain,
+      allowSkipConfirm,
       onDeleted,
       persistDontAskAgainPreference,
       removeWorktree,
@@ -262,7 +259,7 @@ const DeleteWorktreeDialog = React.memo(function DeleteWorktreeDialog() {
           </div>
         )}
 
-        {!isMainWorktree && !canForceDelete && (
+        {!isMainWorktree && allowSkipConfirm && !canForceDelete && (
           // Why: only show "Don't ask again" for the primary confirmation. The
           // force-delete variant is a recovery path that shouldn't double as a
           // preference checkpoint; see handleDelete for the matching guard.
diff --git a/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts b/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts
index c562a9008b1..2c1556833a5 100644
--- a/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts
+++ b/src/renderer/src/components/sidebar/delete-worktree-flow.test.ts
@@ -73,7 +73,8 @@ describe('runWorktreeBatchDelete', () => {
     expect(mocks.state.clearWorktreeDeleteState).toHaveBeenCalledWith('wt-2')
     expect(mocks.state.clearWorktreeDeleteState).not.toHaveBeenCalledWith('main')
     expect(mocks.state.openModal).toHaveBeenCalledWith('delete-worktree', {
-      worktreeIds: ['wt-1', 'wt-2']
+      worktreeIds: ['wt-1', 'wt-2'],
+      allowSkipConfirm: false
     })
   })
 
@@ -86,7 +87,7 @@ describe('runWorktreeBatchDelete', () => {
     expect(mocks.state.openModal).toHaveBeenCalledWith('delete-worktree', { worktreeId: 'wt-1' })
   })
 
-  it('runs every eligible delete immediately when confirmation is skipped', async () => {
+  it('keeps batch deletes behind confirmation when confirmation is skipped', () => {
     mocks.state.settings = { skipDeleteWorktreeConfirm: true }
     setWorktrees([
       { id: 'wt-1', displayName: 'one' },
@@ -96,12 +97,43 @@ describe('runWorktreeBatchDelete', () => {
 
     const started = runWorktreeBatchDelete(['wt-1', 'wt-2'], { onDeleted })
 
+    expect(started).toBe(true)
+    expect(mocks.state.removeWorktree).not.toHaveBeenCalled()
+    expect(mocks.state.openModal).toHaveBeenCalledWith('delete-worktree', {
+      worktreeIds: ['wt-1', 'wt-2'],
+      allowSkipConfirm: false,
+      onDeleted
+    })
+  })
+
+  it('runs a single eligible delete immediately when confirmation is skipped', async () => {
+    mocks.state.settings = { skipDeleteWorktreeConfirm: true }
+    setWorktrees([{ id: 'wt-1', displayName: 'one' }])
+    const onDeleted = vi.fn()
+
+    const started = runWorktreeBatchDelete(['wt-1'], { onDeleted })
+
     expect(started).toBe(true)
     expect(mocks.state.openModal).not.toHaveBeenCalled()
     expect(mocks.state.removeWorktree).toHaveBeenCalledWith('wt-1', false)
-    expect(mocks.state.removeWorktree).toHaveBeenCalledWith('wt-2', false)
     await vi.waitFor(() => {
-      expect(onDeleted).toHaveBeenCalledWith(['wt-1', 'wt-2'])
+      expect(onDeleted).toHaveBeenCalledWith(['wt-1'])
+    })
+  })
+
+  it('can force confirmation for a single eligible delete', () => {
+    mocks.state.settings = { skipDeleteWorktreeConfirm: true }
+    setWorktrees([{ id: 'wt-1', displayName: 'one' }])
+    const onDeleted = vi.fn()
+
+    const started = runWorktreeBatchDelete(['wt-1'], { forceConfirm: true, onDeleted })
+
+    expect(started).toBe(true)
+    expect(mocks.state.removeWorktree).not.toHaveBeenCalled()
+    expect(mocks.state.openModal).toHaveBeenCalledWith('delete-worktree', {
+      worktreeId: 'wt-1',
+      allowSkipConfirm: false,
+      onDeleted
     })
   })
 
diff --git a/src/renderer/src/components/sidebar/delete-worktree-flow.ts b/src/renderer/src/components/sidebar/delete-worktree-flow.ts
index e09200650cc..f915b13f98a 100644
--- a/src/renderer/src/components/sidebar/delete-worktree-flow.ts
+++ b/src/renderer/src/components/sidebar/delete-worktree-flow.ts
@@ -6,6 +6,7 @@ import { getDeleteWorktreeToastCopy } from './delete-worktree-toast'
 import type { Worktree } from '../../../../shared/types'
 
 type WorktreeBatchDeleteOptions = {
+  forceConfirm?: boolean
   onDeleted?: (worktreeIds: string[]) => void
 }
 
@@ -21,6 +22,21 @@ function viewWorktreeDiff(worktreeId: string): void {
   state.setRightSidebarOpen(true)
 }
 
+export async function runWorktreeDeletesSequentially(
+  targets: readonly Pick<Worktree, 'id' | 'displayName'>[]
+): Promise<string[]> {
+  const deletedIds: string[] = []
+  for (const target of targets) {
+    // Why: git worktree removals for one repo contend on git lock files.
+    // Running the user-selected batch sequentially avoids partial lock races.
+    const deleted = await runWorktreeDeleteWithToast(target.id, target.displayName)
+    if (deleted) {
+      deletedIds.push(target.id)
+    }
+  }
+  return deletedIds
+}
+
 /**
  * Shared delete-with-toast flow used by both DeleteWorktreeDialog (confirm
  * path) and WorktreeContextMenu (skip-confirm path). Centralizes the error
@@ -158,12 +174,14 @@ export function runWorktreeBatchDelete(
     state.clearWorktreeDeleteState(target.id)
   }
 
-  const skipConfirm = state.settings?.skipDeleteWorktreeConfirm ?? false
+  // Why: bulk cleanup can destroy many directories at once, so batch deletes
+  // and Space-triggered deletes must keep an explicit confirmation step.
+  const skipConfirm =
+    !options.forceConfirm &&
+    targets.length === 1 &&
+    (state.settings?.skipDeleteWorktreeConfirm ?? false)
   if (skipConfirm) {
-    void Promise.all(
-      targets.map((target) => runWorktreeDeleteWithToast(target.id, target.displayName))
-    ).then((results) => {
-      const deletedIds = targets.filter((_, index) => results[index]).map((target) => target.id)
+    void runWorktreeDeletesSequentially(targets).then((deletedIds) => {
       if (deletedIds.length > 0) {
         options.onDeleted?.(deletedIds)
       }
@@ -174,6 +192,7 @@ export function runWorktreeBatchDelete(
   if (targets.length === 1) {
     state.openModal('delete-worktree', {
       worktreeId: targets[0].id,
+      ...(options.forceConfirm ? { allowSkipConfirm: false } : {}),
       ...(options.onDeleted ? { onDeleted: options.onDeleted } : {})
     })
     return true
@@ -181,6 +200,7 @@ export function runWorktreeBatchDelete(
 
   state.openModal('delete-worktree', {
     worktreeIds: targets.map((target) => target.id),
+    allowSkipConfirm: false,
     ...(options.onDeleted ? { onDeleted: options.onDeleted } : {})
   })
   return true
diff --git a/src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx b/src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx
index 217816d5491..a324d94fdb4 100644
--- a/src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx
+++ b/src/renderer/src/components/status-bar/WorkspaceSpaceCompactPanel.tsx
@@ -1,9 +1,13 @@
 import { useCallback } from 'react'
-import { AlertTriangle, HardDrive, Loader2, RefreshCw } from 'lucide-react'
+import { AlertTriangle, HardDrive, Loader2, RefreshCw, X } from 'lucide-react'
 import { useAppStore } from '../../store'
 import { Badge } from '../ui/badge'
 import { Button } from '../ui/button'
-import { formatBytes, getWorkspaceSpaceScanTimeLabel } from './workspace-space-format'
+import {
+  formatBytes,
+  getWorkspaceSpaceProgressLabel,
+  getWorkspaceSpaceScanTimeLabel
+} from './workspace-space-format'
 
 export function WorkspaceSpaceCompactPanel({
   onOpenFullPage
@@ -11,9 +15,12 @@ export function WorkspaceSpaceCompactPanel({
   onOpenFullPage: () => void
 }): React.JSX.Element {
   const analysis = useAppStore((state) => state.workspaceSpaceAnalysis)
+  const progress = useAppStore((state) => state.workspaceSpaceScanProgress)
   const scanError = useAppStore((state) => state.workspaceSpaceScanError)
   const isScanning = useAppStore((state) => state.workspaceSpaceScanning)
   const refreshWorkspaceSpace = useAppStore((state) => state.refreshWorkspaceSpace)
+  const cancelWorkspaceSpaceScan = useAppStore((state) => state.cancelWorkspaceSpaceScan)
+  const progressLabel = getWorkspaceSpaceProgressLabel(progress)
 
   const scan = useCallback((): void => {
     void refreshWorkspaceSpace().catch(() => {
@@ -21,6 +28,10 @@ export function WorkspaceSpaceCompactPanel({
     })
   }, [refreshWorkspaceSpace])
 
+  const cancelScan = useCallback((): void => {
+    void cancelWorkspaceSpaceScan()
+  }, [cancelWorkspaceSpaceScan])
+
   return (
     <div className="border-t border-border/50 bg-muted/15 px-3 py-2">
       <div className="flex items-center justify-between gap-2">
@@ -35,25 +46,45 @@ export function WorkspaceSpaceCompactPanel({
             </div>
             <div className="truncate text-[11px] text-muted-foreground">
               {analysis
-                ? `${formatBytes(analysis.reclaimableBytes)} reclaimable · ${analysis.scannedWorktreeCount} workspaces`
+                ? isScanning
+                  ? `${progressLabel ?? 'Scanning workspace sizes'} · last result kept`
+                  : analysis.unavailableWorktreeCount > 0
+                    ? `${formatBytes(analysis.reclaimableBytes)} reclaimable · ${analysis.unavailableWorktreeCount} unavailable`
+                    : `${formatBytes(analysis.reclaimableBytes)} reclaimable · ${analysis.scannedWorktreeCount} workspaces`
                 : isScanning
-                  ? 'Scanning workspace sizes.'
+                  ? (progressLabel ?? 'Scanning workspace sizes.')
                   : 'Workspace disk usage is not scanned.'}
             </div>
           </div>
         </div>
 
         <div className="flex shrink-0 items-center gap-1">
-          <Button variant="outline" size="xs" onClick={scan} disabled={isScanning}>
+          <Button
+            variant="outline"
+            size="xs"
+            onClick={isScanning ? cancelScan : scan}
+            disabled={progress?.state === 'cancelling'}
+            className="w-24"
+          >
             {isScanning ? (
-              <Loader2 className="size-3 animate-spin" />
+              progress?.state === 'cancelling' ? (
+                <Loader2 className="size-3 animate-spin" />
+              ) : (
+                <X className="size-3" />
+              )
             ) : (
               <RefreshCw className="size-3" />
             )}
-            {isScanning ? 'Scanning' : analysis ? 'Refresh' : 'Scan'}
+            {isScanning
+              ? progress?.state === 'cancelling'
+                ? 'Stopping'
+                : 'Cancel'
+              : analysis
+                ? 'Refresh'
+                : 'Scan'}
           </Button>
           <Button variant="ghost" size="xs" onClick={onOpenFullPage}>
-            Open
+            Review
           </Button>
         </div>
       </div>
diff --git a/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
index ce8ab9885e1..f7679049360 100644
--- a/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
+++ b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
@@ -10,10 +10,14 @@ import {
   GitBranch,
   HardDrive,
   Loader2,
+  Minus,
   RefreshCw,
   Search,
   Server,
-  Trash2
+  Trash2,
+  ZoomIn,
+  ZoomOut,
+  X
 } from 'lucide-react'
 import type {
   WorkspaceSpaceItem,
@@ -25,12 +29,20 @@ import { useAppStore } from '../../store'
 import { runWorktreeBatchDelete } from '../sidebar/delete-worktree-flow'
 import { Badge } from '../ui/badge'
 import { Button } from '../ui/button'
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuTrigger
+} from '../ui/context-menu'
 import { Input } from '../ui/input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
 import {
   formatBytes,
   formatCompactCount,
   getWorkspaceSpaceBranchLabel,
+  getWorkspaceSpaceProgressLabel,
+  getWorkspaceSpaceScanDateTimeLabel,
   getWorkspaceSpaceScanTimeLabel,
   getWorkspaceSpaceStatusLabel
 } from './workspace-space-format'
@@ -58,28 +70,73 @@ function getTreemapFill(rect: TreemapRect, selected: boolean): string {
   return TREEMAP_FILLS[rect.index % TREEMAP_FILLS.length]
 }
 
-function Metric({ label, value }: { label: string; value: string }): React.JSX.Element {
+function Metric({
+  label,
+  value,
+  title
+}: {
+  label: string
+  value: string
+  title?: string
+}): React.JSX.Element {
   return (
     <div className="min-w-0 px-4 py-3">
       <div className="truncate text-[11px] font-medium uppercase tracking-[0.14em] text-muted-foreground">
         {label}
       </div>
-      <div className="mt-1 truncate text-lg font-semibold tabular-nums">{value}</div>
+      <div className="mt-1 truncate text-lg font-semibold tabular-nums" title={title}>
+        {value}
+      </div>
     </div>
   )
 }
 
+function UpdatedMetric({
+  scannedAt,
+  isScanning
+}: {
+  scannedAt: number | null
+  isScanning: boolean
+}): React.JSX.Element {
+  const [now, setNow] = useState(() => Date.now())
+
+  useEffect(() => {
+    if (scannedAt === null) {
+      return
+    }
+    setNow(Date.now())
+    const timer = window.setInterval(() => setNow(Date.now()), 60_000)
+    return () => window.clearInterval(timer)
+  }, [scannedAt])
+
+  return (
+    <Metric
+      label="Updated"
+      title={scannedAt === null ? undefined : getWorkspaceSpaceScanDateTimeLabel(scannedAt)}
+      value={
+        scannedAt === null
+          ? isScanning
+            ? 'Scanning'
+            : '—'
+          : getWorkspaceSpaceScanTimeLabel(scannedAt, now)
+      }
+    />
+  )
+}
+
 function CheckButton({
   checked,
   disabled,
   label,
   onClick
 }: {
-  checked: boolean
+  checked: boolean | 'mixed'
   disabled?: boolean
   label: string
   onClick: () => void
 }): React.JSX.Element {
+  const isChecked = checked === true
+  const isMixed = checked === 'mixed'
   return (
     <button
       type="button"
@@ -87,19 +144,28 @@ function CheckButton({
       aria-checked={checked}
       aria-label={label}
       disabled={disabled}
+      onPointerDown={(event) => event.stopPropagation()}
+      onKeyDown={(event) => event.stopPropagation()}
       onClick={(event) => {
         event.stopPropagation()
         onClick()
       }}
       className={cn(
-        'flex size-4 shrink-0 items-center justify-center rounded-sm border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-        checked
-          ? 'border-foreground bg-foreground text-background'
-          : 'border-muted-foreground/50 bg-background/40 text-transparent',
+        'flex size-6 shrink-0 items-center justify-center rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
         disabled && 'cursor-default opacity-35'
       )}
     >
-      {checked ? <Check className="size-3" strokeWidth={3} /> : null}
+      <span
+        className={cn(
+          'flex size-4 items-center justify-center rounded-sm border transition-colors',
+          isChecked || isMixed
+            ? 'border-foreground bg-foreground text-background'
+            : 'border-muted-foreground/50 bg-background/40 text-transparent'
+        )}
+      >
+        {isChecked ? <Check className="size-3" strokeWidth={3} /> : null}
+        {isMixed ? <Minus className="size-3" strokeWidth={3} /> : null}
+      </span>
     </button>
   )
 }
@@ -137,35 +203,66 @@ function WorkspaceTreemap({
   rows,
   isScanning,
   selectedWorktreeId,
-  onSelect
+  zoomedWorktree,
+  onSelect,
+  onZoomChange
 }: {
   rows: WorkspaceSpaceWorktree[]
   isScanning: boolean
   selectedWorktreeId: string | null
+  zoomedWorktree: WorkspaceSpaceWorktree | null
   onSelect: (worktreeId: string) => void
+  onZoomChange: (worktreeId: string | null) => void
 }): React.JSX.Element {
+  const selectedWorktree = rows.find((row) => row.worktreeId === selectedWorktreeId) ?? null
+  const canZoomSelected =
+    !!selectedWorktree &&
+    selectedWorktree.status === 'ok' &&
+    selectedWorktree.topLevelItems.length > 0
+  const isZoomed = !!zoomedWorktree
   const rects = useMemo(
     () =>
       buildTreemapLayout(
-        rows
-          .filter((row) => row.status === 'ok' && row.sizeBytes > 0)
-          .map((row) => ({
-            id: row.worktreeId,
-            label: row.displayName,
-            sizeBytes: row.sizeBytes
-          }))
+        zoomedWorktree
+          ? zoomedWorktree.topLevelItems
+              .filter((item) => item.sizeBytes > 0)
+              .map((item) => ({
+                id: item.path,
+                label: item.name,
+                sizeBytes: item.sizeBytes
+              }))
+          : rows
+              .filter((row) => row.status === 'ok' && row.sizeBytes > 0)
+              .map((row) => ({
+                id: row.worktreeId,
+                label: row.displayName,
+                sizeBytes: row.sizeBytes
+              }))
       ),
-    [rows]
+    [rows, zoomedWorktree]
   )
 
   if (rects.length === 0) {
     return (
-      <div className="flex h-72 items-center justify-center rounded-lg border border-dashed border-border/70 bg-muted/20 text-sm text-muted-foreground">
+      <div className="relative flex h-72 items-center justify-center rounded-lg border border-dashed border-border/70 bg-muted/20 text-sm text-muted-foreground">
+        {zoomedWorktree ? (
+          <Button
+            variant="outline"
+            size="xs"
+            onClick={() => onZoomChange(null)}
+            className="absolute right-2 top-2 gap-1.5 bg-background/90 px-2.5 backdrop-blur"
+          >
+            <ZoomOut className="size-3" />
+            All
+          </Button>
+        ) : null}
         <span className="flex items-center gap-2">
           {isScanning ? <Loader2 className="size-4 animate-spin" /> : null}
           {isScanning
             ? 'Scanning workspace sizes. You can leave this page.'
-            : 'No scanned workspace sizes yet.'}
+            : isZoomed
+              ? 'No top-level items to show.'
+              : 'No scanned workspace sizes yet.'}
         </span>
       </div>
     )
@@ -173,9 +270,69 @@ function WorkspaceTreemap({
 
   return (
     <div className="relative h-72 overflow-hidden rounded-lg border border-border/70 bg-muted/20">
+      <div className="absolute right-2 top-2 z-10 flex max-w-[calc(100%-1rem)] items-center gap-2">
+        {zoomedWorktree ? (
+          <>
+            <div className="max-w-56 truncate rounded-md border border-border/70 bg-background/90 px-2 py-1 text-[11px] font-medium shadow-xs backdrop-blur">
+              {zoomedWorktree.displayName}
+            </div>
+            <Button
+              variant="outline"
+              size="xs"
+              onClick={() => onZoomChange(null)}
+              className="gap-1.5 bg-background/90 px-2.5 backdrop-blur"
+            >
+              <ZoomOut className="size-3" />
+              All
+            </Button>
+          </>
+        ) : canZoomSelected ? (
+          <Button
+            variant="outline"
+            size="xs"
+            onClick={() => onZoomChange(selectedWorktree.worktreeId)}
+            className="gap-1.5 bg-background/90 px-2.5 backdrop-blur"
+          >
+            <ZoomIn className="size-3" />
+            Zoom
+          </Button>
+        ) : null}
+      </div>
       {rects.map((rect) => {
         const area = rect.width * rect.height
-        const selected = rect.id === selectedWorktreeId
+        const selected = !isZoomed && rect.id === selectedWorktreeId
+        const rectStyle = {
+          left: `${rect.x}%`,
+          top: `${rect.y}%`,
+          width: `${rect.width}%`,
+          height: `${rect.height}%`,
+          background: getTreemapFill(rect, selected)
+        }
+        const rectContent =
+          area >= 80 ? (
+            <span className="block min-w-0 text-[11px] font-medium leading-tight text-foreground">
+              <span className="block truncate">{rect.label}</span>
+              {area >= 180 ? (
+                <span className="mt-0.5 block truncate text-muted-foreground">
+                  {formatBytes(rect.sizeBytes)}
+                </span>
+              ) : null}
+            </span>
+          ) : null
+
+        if (isZoomed) {
+          return (
+            <div
+              key={rect.id}
+              title={`${rect.label} • ${formatBytes(rect.sizeBytes)}`}
+              className="absolute overflow-hidden border border-background/80 p-2 text-left"
+              style={rectStyle}
+            >
+              {rectContent}
+            </div>
+          )
+        }
+
         return (
           <button
             key={rect.id}
@@ -187,24 +344,9 @@ function WorkspaceTreemap({
               'absolute overflow-hidden border border-background/80 p-2 text-left transition-[filter,outline] hover:brightness-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
               selected && 'ring-2 ring-ring ring-offset-1 ring-offset-background'
             )}
-            style={{
-              left: `${rect.x}%`,
-              top: `${rect.y}%`,
-              width: `${rect.width}%`,
-              height: `${rect.height}%`,
-              background: getTreemapFill(rect, selected)
-            }}
+            style={rectStyle}
           >
-            {area >= 80 ? (
-              <span className="block min-w-0 text-[11px] font-medium leading-tight text-foreground">
-                <span className="block truncate">{rect.label}</span>
-                {area >= 180 ? (
-                  <span className="mt-0.5 block truncate text-muted-foreground">
-                    {formatBytes(rect.sizeBytes)}
-                  </span>
-                ) : null}
-              </span>
-            ) : null}
+            {rectContent}
           </button>
         )
       })}
@@ -310,7 +452,8 @@ function WorkspaceRow({
   selected,
   inspected,
   onToggleSelected,
-  onInspect
+  onInspect,
+  onDelete
 }: {
   worktree: WorkspaceSpaceWorktree
   maxSize: number
@@ -318,8 +461,10 @@ function WorkspaceRow({
   inspected: boolean
   onToggleSelected: () => void
   onInspect: () => void
+  onDelete: () => void
 }): React.JSX.Element {
-  return (
+  const canDelete = worktree.canDelete && worktree.status === 'ok'
+  const row = (
     <div
       role="button"
       tabIndex={0}
@@ -338,7 +483,7 @@ function WorkspaceRow({
     >
       <CheckButton
         checked={selected}
-        disabled={!worktree.canDelete || worktree.status !== 'ok'}
+        disabled={!canDelete}
         label={`Select ${worktree.displayName}`}
         onClick={onToggleSelected}
       />
@@ -379,13 +524,31 @@ function WorkspaceRow({
       </div>
     </div>
   )
+
+  if (!canDelete) {
+    return row
+  }
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>{row}</ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuItem variant="destructive" onSelect={onDelete}>
+          <Trash2 className="size-3.5" />
+          Delete workspace
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  )
 }
 
 export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
   const analysis = useAppStore((state) => state.workspaceSpaceAnalysis)
+  const progress = useAppStore((state) => state.workspaceSpaceScanProgress)
   const scanError = useAppStore((state) => state.workspaceSpaceScanError)
   const isScanning = useAppStore((state) => state.workspaceSpaceScanning)
   const refreshWorkspaceSpace = useAppStore((state) => state.refreshWorkspaceSpace)
+  const cancelWorkspaceSpaceScan = useAppStore((state) => state.cancelWorkspaceSpaceScan)
   const removeWorkspaceSpaceWorktrees = useAppStore((state) => state.removeWorkspaceSpaceWorktrees)
   const [query, setQuery] = useState('')
   const [onlyDeletable, setOnlyDeletable] = useState(false)
@@ -393,6 +556,7 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
   const [sortDirection, setSortDirection] = useState<WorkspaceSpaceSortDirection>('desc')
   const [selectedIds, setSelectedIds] = useState<Set<string>>(() => new Set())
   const [inspectedWorktreeId, setInspectedWorktreeId] = useState<string | null>(null)
+  const [treemapZoomWorktreeId, setTreemapZoomWorktreeId] = useState<string | null>(null)
 
   const refresh = useCallback((): void => {
     void refreshWorkspaceSpace().catch(() => {
@@ -400,6 +564,10 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
     })
   }, [refreshWorkspaceSpace])
 
+  const cancelScan = useCallback((): void => {
+    void cancelWorkspaceSpaceScan()
+  }, [cancelWorkspaceSpaceScan])
+
   const sourceRows = useMemo(() => analysis?.worktrees ?? [], [analysis?.worktrees])
 
   const rows = useMemo(
@@ -416,14 +584,37 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
     rows.find((row) => row.worktreeId === inspectedWorktreeId) ??
     rows.find((row) => row.status === 'ok') ??
     null
+  const zoomedWorktree =
+    sourceRows.find((row) => row.worktreeId === treemapZoomWorktreeId && row.status === 'ok') ??
+    null
   const maxSize = Math.max(...rows.map((row) => row.sizeBytes), 0)
-  const selectedDeletableIds = getSelectedDeletableWorkspaceIds(rows, selectedIds)
-  const visibleDeletableIds = rows
-    .filter((row) => row.canDelete && row.status === 'ok')
-    .map((row) => row.worktreeId)
+  const selectedDeletableIds = useMemo(
+    () => getSelectedDeletableWorkspaceIds(rows, selectedIds),
+    [rows, selectedIds]
+  )
+  const selectedDeletableIdSet = useMemo(
+    () => new Set(selectedDeletableIds),
+    [selectedDeletableIds]
+  )
+  const visibleDeletableIds = useMemo(
+    () => rows.filter((row) => row.canDelete && row.status === 'ok').map((row) => row.worktreeId),
+    [rows]
+  )
   const allVisibleSelected =
     visibleDeletableIds.length > 0 && visibleDeletableIds.every((id) => selectedIds.has(id))
+  const someVisibleSelected = visibleDeletableIds.some((id) => selectedIds.has(id))
+  const visibleSelectionState = allVisibleSelected ? true : someVisibleSelected ? 'mixed' : false
   const isInitialScan = isScanning && !analysis
+  const hasRows = sourceRows.length > 0
+  const progressLabel = getWorkspaceSpaceProgressLabel(progress)
+  const repoErrors = analysis?.repos.filter((repo) => repo.error !== null) ?? []
+  const selectedReclaimableBytes = useMemo(
+    () =>
+      rows
+        .filter((row) => selectedDeletableIdSet.has(row.worktreeId))
+        .reduce((sum, row) => sum + row.reclaimableBytes, 0),
+    [rows, selectedDeletableIdSet]
+  )
 
   useEffect(() => {
     if (!analysis) {
@@ -445,6 +636,14 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
     })
   }, [sourceRows])
 
+  useEffect(() => {
+    setTreemapZoomWorktreeId((current) =>
+      current && sourceRows.some((row) => row.worktreeId === current && row.status === 'ok')
+        ? current
+        : null
+    )
+  }, [sourceRows])
+
   const toggleSort = (key: WorkspaceSpaceSortKey): void => {
     if (sortKey === key) {
       setSortDirection((current) => (current === 'asc' ? 'desc' : 'asc'))
@@ -454,6 +653,11 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
     setSortDirection(key === 'name' || key === 'repo' ? 'asc' : 'desc')
   }
 
+  const selectSortKey = (key: WorkspaceSpaceSortKey): void => {
+    setSortKey(key)
+    setSortDirection(key === 'name' || key === 'repo' ? 'asc' : 'desc')
+  }
+
   const toggleSelection = (worktreeId: string): void => {
     setSelectedIds((current) => {
       const next = new Set(current)
@@ -482,31 +686,45 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
     })
   }
 
+  const deleteWorktrees = useCallback(
+    (worktreeIds: readonly string[]): void => {
+      if (worktreeIds.length === 0) {
+        return
+      }
+      runWorktreeBatchDelete(worktreeIds, {
+        forceConfirm: true,
+        onDeleted: (deletedIds) => {
+          removeWorkspaceSpaceWorktrees(deletedIds)
+          setInspectedWorktreeId((current) =>
+            current && deletedIds.includes(current) ? null : current
+          )
+          setTreemapZoomWorktreeId((current) =>
+            current && deletedIds.includes(current) ? null : current
+          )
+          setSelectedIds((current) => {
+            if (deletedIds.length === 0) {
+              return current
+            }
+            const next = new Set(current)
+            for (const id of deletedIds) {
+              next.delete(id)
+            }
+            return next
+          })
+          toast.success(deletedIds.length === 1 ? 'Workspace deleted' : 'Workspaces deleted', {
+            description: `${deletedIds.length} ${deletedIds.length === 1 ? 'workspace' : 'workspaces'} removed from Space.`
+          })
+        }
+      })
+    },
+    [removeWorkspaceSpaceWorktrees]
+  )
+
   const deleteSelected = (): void => {
     if (selectedDeletableIds.length === 0) {
       return
     }
-    runWorktreeBatchDelete(selectedDeletableIds, {
-      onDeleted: (deletedIds) => {
-        removeWorkspaceSpaceWorktrees(deletedIds)
-        setInspectedWorktreeId((current) =>
-          current && deletedIds.includes(current) ? null : current
-        )
-        setSelectedIds((current) => {
-          if (deletedIds.length === 0) {
-            return current
-          }
-          const next = new Set(current)
-          for (const id of deletedIds) {
-            next.delete(id)
-          }
-          return next
-        })
-        toast.success(deletedIds.length === 1 ? 'Workspace deleted' : 'Workspaces deleted', {
-          description: `${deletedIds.length} ${deletedIds.length === 1 ? 'workspace' : 'workspaces'} removed from Space.`
-        })
-      }
-    })
+    deleteWorktrees(selectedDeletableIds)
   }
 
   return (
@@ -517,176 +735,264 @@ export function WorkspaceSpaceManagerPanel(): React.JSX.Element {
           label="Reclaimable"
           value={analysis ? formatBytes(analysis.reclaimableBytes) : '—'}
         />
-        <Metric label="Workspaces" value={analysis ? String(analysis.scannedWorktreeCount) : '—'} />
         <Metric
-          label="Updated"
+          label="Workspaces"
           value={
             analysis
-              ? getWorkspaceSpaceScanTimeLabel(analysis.scannedAt)
-              : isScanning
-                ? 'Scanning'
-                : '—'
+              ? analysis.unavailableWorktreeCount > 0
+                ? `${analysis.scannedWorktreeCount}/${analysis.worktreeCount}`
+                : String(analysis.scannedWorktreeCount)
+              : '—'
           }
         />
+        <UpdatedMetric scannedAt={analysis?.scannedAt ?? null} isScanning={isScanning} />
       </div>
 
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div className="flex min-w-0 items-center gap-2 text-xs text-muted-foreground">
-          <HardDrive className="size-4 shrink-0" />
+          {isScanning ? (
+            <Loader2 className="size-4 shrink-0 animate-spin" />
+          ) : (
+            <HardDrive className="size-4 shrink-0" />
+          )}
           <span className="truncate">
             {analysis
-              ? `${formatBytes(analysis.reclaimableBytes)} can be reclaimed from linked worktrees.`
+              ? isScanning
+                ? `${progressLabel ?? 'Scanning workspace sizes'}. You can leave this page; the last result stays visible.`
+                : `${formatBytes(analysis.reclaimableBytes)} can be reclaimed from linked worktrees.`
               : isScanning
-                ? 'Scanning workspace sizes in the background. You can leave this page.'
+                ? `${progressLabel ?? 'Scanning workspace sizes'}. You can leave this page.`
                 : 'Run a scan to inspect workspace sizes.'}
           </span>
         </div>
         <Button
           variant="outline"
           size="sm"
-          onClick={refresh}
-          disabled={isScanning}
+          onClick={isScanning ? cancelScan : refresh}
+          disabled={progress?.state === 'cancelling'}
           className="w-28 gap-1.5"
         >
           {isScanning ? (
-            <Loader2 className="size-3.5 animate-spin" />
+            progress?.state === 'cancelling' ? (
+              <Loader2 className="size-3.5 animate-spin" />
+            ) : (
+              <X className="size-3.5" />
+            )
           ) : (
             <RefreshCw className="size-3.5" />
           )}
-          {isScanning ? 'Scanning' : analysis ? 'Refresh' : 'Scan'}
+          {isScanning
+            ? progress?.state === 'cancelling'
+              ? 'Stopping'
+              : 'Cancel'
+            : analysis
+              ? 'Refresh'
+              : 'Scan'}
         </Button>
       </div>
 
       {scanError ? (
         <div className="flex items-start gap-2 rounded-md border border-destructive/35 bg-destructive/8 px-3 py-2 text-xs text-destructive">
           <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
-          <span className="min-w-0 break-words">{scanError}</span>
+          <span className="min-w-0 break-words">
+            {scanError}
+            {analysis ? ' Last successful results remain visible.' : ''}
+          </span>
         </div>
       ) : null}
 
-      <div className="grid gap-4 xl:grid-cols-[minmax(0,1.4fr)_minmax(20rem,0.6fr)]">
-        <WorkspaceTreemap
-          rows={sourceRows}
-          isScanning={isInitialScan}
-          selectedWorktreeId={inspectedWorktree?.worktreeId ?? null}
-          onSelect={setInspectedWorktreeId}
-        />
-        <BreakdownList worktree={inspectedWorktree} isScanning={isInitialScan} />
-      </div>
+      {repoErrors.length > 0 ? (
+        <div className="space-y-1.5 rounded-md border border-border/70 bg-muted/20 px-3 py-2 text-xs text-muted-foreground">
+          {repoErrors.map((repo) => (
+            <div key={repo.repoId} className="flex items-start gap-2">
+              <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
+              <span className="min-w-0 break-words">
+                {repo.displayName}: {repo.error}
+              </span>
+            </div>
+          ))}
+        </div>
+      ) : null}
 
-      <div className="flex flex-wrap items-center gap-2">
-        <div className="relative min-w-[16rem] flex-1">
-          <Search className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
-          <Input
-            value={query}
-            onChange={(event) => setQuery(event.target.value)}
-            placeholder="Filter workspaces"
-            className="pl-9"
+      {hasRows || isInitialScan ? (
+        <div className="grid gap-4 xl:grid-cols-[minmax(0,1.4fr)_minmax(20rem,0.6fr)]">
+          <WorkspaceTreemap
+            rows={sourceRows}
+            isScanning={isInitialScan}
+            selectedWorktreeId={inspectedWorktree?.worktreeId ?? null}
+            zoomedWorktree={zoomedWorktree}
+            onSelect={setInspectedWorktreeId}
+            onZoomChange={setTreemapZoomWorktreeId}
           />
+          <BreakdownList worktree={inspectedWorktree} isScanning={isInitialScan} />
         </div>
+      ) : null}
 
-        <Select
-          value={sortKey}
-          onValueChange={(value) => setSortKey(value as WorkspaceSpaceSortKey)}
-        >
-          <SelectTrigger className="w-36">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="size">Size</SelectItem>
-            <SelectItem value="name">Name</SelectItem>
-            <SelectItem value="repo">Repository</SelectItem>
-            <SelectItem value="activity">Activity</SelectItem>
-          </SelectContent>
-        </Select>
-
-        <Button
-          variant={onlyDeletable ? 'secondary' : 'outline'}
-          size="sm"
-          onClick={() => setOnlyDeletable((current) => !current)}
-          className="w-32"
-        >
-          {onlyDeletable ? 'Deletable' : 'All'}
-        </Button>
-
-        <Button
-          variant="outline"
-          size="sm"
-          onClick={toggleVisibleSelection}
-          disabled={visibleDeletableIds.length === 0}
-          className="w-32 gap-1.5"
-        >
-          <Check className="size-3.5" />
-          {allVisibleSelected ? 'Clear' : 'Select'}
-        </Button>
-
-        <Button
-          variant="destructive"
-          size="sm"
-          onClick={deleteSelected}
-          disabled={selectedDeletableIds.length === 0}
-          className="w-32 gap-1.5"
-        >
-          <Trash2 className="size-3.5" />
-          {selectedDeletableIds.length > 0 ? `Delete ${selectedDeletableIds.length}` : 'Delete'}
-        </Button>
-      </div>
-
-      <div className="overflow-hidden rounded-lg border border-border/70 bg-background/30">
-        <div className="grid grid-cols-[1.75rem_minmax(0,1.35fr)_minmax(9rem,0.65fr)_8rem_6rem] gap-3 border-b border-border/60 px-3 py-2 text-[11px] font-medium uppercase tracking-[0.14em] text-muted-foreground">
-          <div />
-          <button
-            type="button"
-            onClick={() => toggleSort('name')}
-            className="flex items-center gap-1 text-left"
-          >
-            Workspace
-            <SortIndicator sortKey="name" activeKey={sortKey} direction={sortDirection} />
-          </button>
-          <button
-            type="button"
-            onClick={() => toggleSort('repo')}
-            className="flex items-center gap-1 text-left"
-          >
-            Repository
-            <SortIndicator sortKey="repo" activeKey={sortKey} direction={sortDirection} />
-          </button>
-          <button
-            type="button"
-            onClick={() => toggleSort('size')}
-            className="flex items-center justify-end gap-1 text-right"
-          >
-            Size
-            <SortIndicator sortKey="size" activeKey={sortKey} direction={sortDirection} />
-          </button>
-          <div className="text-right">State</div>
+      {hasRows ? (
+        <div className="sticky top-0 z-10 -mx-1 flex flex-wrap items-center justify-between gap-2 rounded-md border border-border/70 bg-background/95 px-3 py-2 shadow-xs backdrop-blur">
+          <div className="min-w-0 text-xs text-muted-foreground">
+            <span className="font-medium text-foreground">
+              {selectedDeletableIds.length} selected
+            </span>
+            <span className="mx-1.5">·</span>
+            <span>{formatBytes(selectedReclaimableBytes)} reclaimable</span>
+          </div>
+          <div className="flex shrink-0 items-center gap-2">
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => setSelectedIds(new Set<string>())}
+              disabled={selectedDeletableIds.length === 0}
+              className="!px-3"
+            >
+              Clear
+            </Button>
+            <Button
+              variant="destructive"
+              size="sm"
+              onClick={deleteSelected}
+              disabled={selectedDeletableIds.length === 0}
+              className="min-w-[9.5rem] gap-1.5 !px-3.5"
+            >
+              <Trash2 className="size-3.5" />
+              Delete selected
+            </Button>
+          </div>
         </div>
+      ) : null}
 
-        <div className="max-h-[28rem] overflow-y-auto scrollbar-sleek">
-          {isInitialScan ? (
-            <div className="flex items-center justify-center gap-2 px-4 py-10 text-center text-sm text-muted-foreground">
-              <Loader2 className="size-4 animate-spin" />
-              Scanning workspaces. You can leave this page.
+      {hasRows ? (
+        <div className="flex flex-wrap items-center gap-2">
+          <div className="relative min-w-[16rem] flex-1">
+            <Search className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+            <Input
+              value={query}
+              onChange={(event) => setQuery(event.target.value)}
+              placeholder="Filter workspaces"
+              className="pl-9"
+            />
+          </div>
+
+          <Select
+            value={sortKey}
+            onValueChange={(value) => selectSortKey(value as WorkspaceSpaceSortKey)}
+          >
+            <SelectTrigger className="w-36">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="size">Size</SelectItem>
+              <SelectItem value="name">Name</SelectItem>
+              <SelectItem value="repo">Repository</SelectItem>
+              <SelectItem value="activity">Activity</SelectItem>
+            </SelectContent>
+          </Select>
+
+          <Button
+            variant={onlyDeletable ? 'secondary' : 'outline'}
+            size="sm"
+            onClick={() => setOnlyDeletable((current) => !current)}
+            className="w-32"
+            aria-label="Show only deletable workspaces"
+          >
+            {onlyDeletable ? 'Deletable' : 'All'}
+          </Button>
+
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={toggleVisibleSelection}
+            disabled={visibleDeletableIds.length === 0}
+            className="w-32 gap-1.5"
+            aria-label={
+              allVisibleSelected ? 'Clear visible selection' : 'Select visible deletable workspaces'
+            }
+          >
+            <Check className="size-3.5" />
+            {allVisibleSelected ? 'Clear' : 'Select'}
+          </Button>
+        </div>
+      ) : null}
+
+      {hasRows || isInitialScan ? (
+        <div className="overflow-x-auto rounded-lg border border-border/70 bg-background/30">
+          <div className="min-w-[46rem]">
+            <div className="grid grid-cols-[1.75rem_minmax(0,1.35fr)_minmax(9rem,0.65fr)_8rem_6rem] gap-3 border-b border-border/60 px-3 py-2 text-[11px] font-medium uppercase tracking-[0.14em] text-muted-foreground">
+              <div className="flex items-center">
+                <CheckButton
+                  checked={visibleSelectionState}
+                  disabled={visibleDeletableIds.length === 0}
+                  label={
+                    allVisibleSelected
+                      ? 'Clear visible selection'
+                      : 'Select visible deletable workspaces'
+                  }
+                  onClick={toggleVisibleSelection}
+                />
+              </div>
+              <button
+                type="button"
+                onClick={() => toggleSort('name')}
+                className="flex items-center gap-1 text-left"
+              >
+                Workspace
+                <SortIndicator sortKey="name" activeKey={sortKey} direction={sortDirection} />
+              </button>
+              <button
+                type="button"
+                onClick={() => toggleSort('repo')}
+                className="flex items-center gap-1 text-left"
+              >
+                Repository
+                <SortIndicator sortKey="repo" activeKey={sortKey} direction={sortDirection} />
+              </button>
+              <button
+                type="button"
+                onClick={() => toggleSort('size')}
+                className="flex items-center justify-end gap-1 text-right"
+              >
+                Size
+                <SortIndicator sortKey="size" activeKey={sortKey} direction={sortDirection} />
+              </button>
+              <div className="text-right">State</div>
             </div>
-          ) : rows.length === 0 ? (
-            <div className="px-4 py-10 text-center text-sm text-muted-foreground">
-              No matching workspaces.
+
+            <div className="max-h-[28rem] overflow-y-auto scrollbar-sleek">
+              {isInitialScan ? (
+                <div className="flex items-center justify-center gap-2 px-4 py-10 text-center text-sm text-muted-foreground">
+                  <Loader2 className="size-4 animate-spin" />
+                  Scanning workspaces. You can leave this page.
+                </div>
+              ) : rows.length === 0 ? (
+                <div className="px-4 py-10 text-center text-sm text-muted-foreground">
+                  No matching workspaces.
+                </div>
+              ) : (
+                rows.map((worktree) => (
+                  <WorkspaceRow
+                    key={worktree.worktreeId}
+                    worktree={worktree}
+                    maxSize={maxSize}
+                    selected={selectedIds.has(worktree.worktreeId)}
+                    inspected={inspectedWorktree?.worktreeId === worktree.worktreeId}
+                    onToggleSelected={() => toggleSelection(worktree.worktreeId)}
+                    onInspect={() => setInspectedWorktreeId(worktree.worktreeId)}
+                    onDelete={() => deleteWorktrees([worktree.worktreeId])}
+                  />
+                ))
+              )}
             </div>
-          ) : (
-            rows.map((worktree) => (
-              <WorkspaceRow
-                key={worktree.worktreeId}
-                worktree={worktree}
-                maxSize={maxSize}
-                selected={selectedIds.has(worktree.worktreeId)}
-                inspected={inspectedWorktree?.worktreeId === worktree.worktreeId}
-                onToggleSelected={() => toggleSelection(worktree.worktreeId)}
-                onInspect={() => setInspectedWorktreeId(worktree.worktreeId)}
-              />
-            ))
-          )}
+          </div>
         </div>
-      </div>
+      ) : (
+        <div className="rounded-lg border border-border/70 bg-background/30 px-4 py-10 text-center text-sm text-muted-foreground">
+          {scanError
+            ? 'Scan failed before any workspace sizes were collected.'
+            : analysis
+              ? 'No workspace rows were available from the scan.'
+              : 'Run a scan to inspect workspace sizes.'}
+        </div>
+      )}
     </div>
   )
 }
diff --git a/src/renderer/src/components/status-bar/workspace-space-format.test.ts b/src/renderer/src/components/status-bar/workspace-space-format.test.ts
index 9f239b0e075..6c43b22136c 100644
--- a/src/renderer/src/components/status-bar/workspace-space-format.test.ts
+++ b/src/renderer/src/components/status-bar/workspace-space-format.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import {
   formatBytes,
   formatCompactCount,
+  getWorkspaceSpaceScanTimeLabel,
   getWorkspaceSpaceStatusLabel
 } from './workspace-space-format'
 
@@ -18,4 +19,16 @@ describe('workspace space format helpers', () => {
     expect(formatCompactCount(25_000)).toBe('25k')
     expect(getWorkspaceSpaceStatusLabel('permission-denied')).toBe('No access')
   })
+
+  it('formats scan times as relative age labels', () => {
+    const now = new Date('2026-05-14T22:15:00Z').getTime()
+    const formatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' })
+
+    expect(getWorkspaceSpaceScanTimeLabel(now - 2 * 60_000, now)).toBe(
+      formatter.format(-2, 'minute')
+    )
+    expect(getWorkspaceSpaceScanTimeLabel(now - 3 * 60 * 60_000, now)).toBe(
+      formatter.format(-3, 'hour')
+    )
+  })
 })
diff --git a/src/renderer/src/components/status-bar/workspace-space-format.ts b/src/renderer/src/components/status-bar/workspace-space-format.ts
index 9566e4e3911..ab056ea68e4 100644
--- a/src/renderer/src/components/status-bar/workspace-space-format.ts
+++ b/src/renderer/src/components/status-bar/workspace-space-format.ts
@@ -1,9 +1,15 @@
 import type {
+  WorkspaceSpaceScanProgress,
   WorkspaceSpaceScanStatus,
   WorkspaceSpaceWorktree
 } from '../../../../shared/workspace-space-types'
 
 const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'] as const
+const relativeTimeFormatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' })
+const fullDateTimeFormatter = new Intl.DateTimeFormat(undefined, {
+  dateStyle: 'medium',
+  timeStyle: 'short'
+})
 
 export function formatBytes(bytes: number): string {
   if (!Number.isFinite(bytes) || bytes <= 0) {
@@ -34,8 +40,45 @@ export function formatCompactCount(count: number): string {
   return `${(count / 1_000_000).toFixed(count >= 10_000_000 ? 0 : 1)}m`
 }
 
-export function getWorkspaceSpaceScanTimeLabel(scannedAt: number): string {
-  return new Date(scannedAt).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+export function getWorkspaceSpaceScanTimeLabel(scannedAt: number, now = Date.now()): string {
+  const diffMs = scannedAt - now
+  const diffMinutes = Math.round(diffMs / 60_000)
+  if (Math.abs(diffMinutes) < 60) {
+    return relativeTimeFormatter.format(diffMinutes, 'minute')
+  }
+
+  const diffHours = Math.round(diffMinutes / 60)
+  if (Math.abs(diffHours) < 24) {
+    return relativeTimeFormatter.format(diffHours, 'hour')
+  }
+
+  const diffDays = Math.round(diffHours / 24)
+  return relativeTimeFormatter.format(diffDays, 'day')
+}
+
+export function getWorkspaceSpaceScanDateTimeLabel(scannedAt: number): string {
+  return fullDateTimeFormatter.format(new Date(scannedAt))
+}
+
+export function getWorkspaceSpaceProgressLabel(
+  progress: WorkspaceSpaceScanProgress | null
+): string | null {
+  if (!progress) {
+    return null
+  }
+  if (progress.state === 'cancelling') {
+    return 'Cancelling scan'
+  }
+
+  const current =
+    progress.currentWorktreeDisplayName ?? progress.currentRepoDisplayName ?? 'workspaces'
+  if (progress.totalWorktreeCount > 0) {
+    return `Scanning ${progress.scannedWorktreeCount} of ${progress.totalWorktreeCount} · ${current}`
+  }
+  if (progress.totalRepoCount > 0) {
+    return `Scanning ${progress.scannedRepoCount} of ${progress.totalRepoCount} repos · ${current}`
+  }
+  return 'Scanning workspace sizes'
 }
 
 export function getWorkspaceSpaceStatusLabel(status: WorkspaceSpaceScanStatus): string {
diff --git a/src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx b/src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx
index 0fed37c3afa..2060ce32724 100644
--- a/src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx
+++ b/src/renderer/src/components/workspace-space/WorkspaceSpacePage.tsx
@@ -9,21 +9,47 @@ export default function WorkspaceSpacePage(): React.JSX.Element {
   const closeSpacePage = useAppStore((state) => state.closeSpacePage)
 
   useEffect(() => {
+    const hasVisibleOverlay = (): boolean =>
+      Array.from(
+        document.querySelectorAll('[role="dialog"], [role="listbox"], [role="menu"]')
+      ).some((element) => {
+        if (!(element instanceof HTMLElement)) {
+          return false
+        }
+        if (element.closest('[aria-hidden="true"]')) {
+          return false
+        }
+        const style = window.getComputedStyle(element)
+        return (
+          style.display !== 'none' &&
+          style.visibility !== 'hidden' &&
+          element.getClientRects().length > 0
+        )
+      })
+
     const handleKeyDown = (event: KeyboardEvent): void => {
-      if (event.key !== 'Escape' || event.defaultPrevented) {
+      if (event.key !== 'Escape') {
         return
       }
       // Why: confirmation dialogs own Escape first; page-level Escape should
-      // only leave the full Space surface when no modal is active.
-      if (document.querySelector('[role="dialog"]')) {
+      // only leave the full Space surface when no modal or popover is active.
+      if (hasVisibleOverlay()) {
+        return
+      }
+      const target = event.target as HTMLElement | null
+      if (
+        target?.matches('input, textarea, select, [contenteditable="true"], [contenteditable=""]')
+      ) {
         return
       }
       event.preventDefault()
       closeSpacePage()
     }
 
-    window.addEventListener('keydown', handleKeyDown)
-    return () => window.removeEventListener('keydown', handleKeyDown)
+    // Why: tooltips can consume Escape before bubble listeners see it. Capture
+    // keeps the first Escape reliable while still deferring to real overlays.
+    window.addEventListener('keydown', handleKeyDown, { capture: true })
+    return () => window.removeEventListener('keydown', handleKeyDown, { capture: true })
   }, [closeSpacePage])
 
   return (
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index ada47027c8e..238c2b8cb3a 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -92,6 +92,7 @@ export function useIpcEvents(): void {
             removed
           )
           afterState.purgeWorktreeTerminalState(removed)
+          afterState.removeWorkspaceSpaceWorktrees(removed)
         }
       })
     )
@@ -891,6 +892,15 @@ export function useIpcEvents(): void {
       })
     )
 
+    const unsubscribeWorkspaceSpaceProgress = window.api.workspaceSpace?.onProgress?.(
+      (progress) => {
+        useAppStore.getState().applyWorkspaceSpaceProgress(progress)
+      }
+    )
+    if (unsubscribeWorkspaceSpaceProgress) {
+      unsubs.push(unsubscribeWorkspaceSpaceProgress)
+    }
+
     // Track SSH connection state changes so the renderer can show
     // disconnected indicators on remote worktrees.
     // Why: hydrate initial state for all known targets so worktree cards
diff --git a/src/renderer/src/store/slices/workspace-space.ts b/src/renderer/src/store/slices/workspace-space.ts
index 2d1bc99c000..f115156ed77 100644
--- a/src/renderer/src/store/slices/workspace-space.ts
+++ b/src/renderer/src/store/slices/workspace-space.ts
@@ -1,13 +1,19 @@
 import type { StateCreator } from 'zustand'
-import type { WorkspaceSpaceAnalysis } from '../../../../shared/workspace-space-types'
+import type {
+  WorkspaceSpaceAnalysis,
+  WorkspaceSpaceScanProgress
+} from '../../../../shared/workspace-space-types'
 import type { AppState } from '../types'
 
 let inFlightScan: Promise<WorkspaceSpaceAnalysis> | null = null
 
 export type WorkspaceSpaceSlice = {
   workspaceSpaceAnalysis: WorkspaceSpaceAnalysis | null
+  workspaceSpaceScanProgress: WorkspaceSpaceScanProgress | null
   workspaceSpaceScanError: string | null
   workspaceSpaceScanning: boolean
+  applyWorkspaceSpaceProgress: (progress: WorkspaceSpaceScanProgress) => void
+  cancelWorkspaceSpaceScan: () => Promise<boolean>
   refreshWorkspaceSpace: () => Promise<WorkspaceSpaceAnalysis>
   removeWorkspaceSpaceWorktrees: (worktreeIds: readonly string[]) => void
 }
@@ -54,27 +60,81 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+function isWorkspaceSpaceScanCancelled(error: unknown): boolean {
+  const message = errorMessage(error).toLowerCase()
+  return message.includes('workspace space scan cancelled') || message.includes('was cancelled')
+}
+
 export const createWorkspaceSpaceSlice: StateCreator<AppState, [], [], WorkspaceSpaceSlice> = (
   set
 ) => ({
   workspaceSpaceAnalysis: null,
+  workspaceSpaceScanProgress: null,
   workspaceSpaceScanError: null,
   workspaceSpaceScanning: false,
+  applyWorkspaceSpaceProgress: (progress) =>
+    set((state) => {
+      if (
+        state.workspaceSpaceScanProgress?.scanId !== progress.scanId &&
+        !state.workspaceSpaceScanning
+      ) {
+        return state
+      }
+      return {
+        workspaceSpaceScanProgress: progress,
+        workspaceSpaceScanning: true
+      }
+    }),
+  cancelWorkspaceSpaceScan: async () => {
+    const cancelled = await window.api.workspaceSpace.cancel()
+    if (cancelled) {
+      set((state) =>
+        state.workspaceSpaceScanProgress
+          ? {
+              workspaceSpaceScanProgress: {
+                ...state.workspaceSpaceScanProgress,
+                state: 'cancelling',
+                updatedAt: Date.now()
+              }
+            }
+          : state
+      )
+    }
+    return cancelled
+  },
   refreshWorkspaceSpace: async () => {
     if (inFlightScan) {
       return inFlightScan
     }
-    set({ workspaceSpaceScanning: true, workspaceSpaceScanError: null })
+    set({
+      workspaceSpaceScanning: true,
+      workspaceSpaceScanProgress: null,
+      workspaceSpaceScanError: null
+    })
     // Why: the compact Resource Manager card and the full Space page share
     // one manual scan result; duplicate button presses should join the same IO.
     inFlightScan = window.api.workspaceSpace
       .analyze()
-      .then((analysis) => {
-        set({ workspaceSpaceAnalysis: analysis, workspaceSpaceScanning: false })
+      .then((result) => {
+        if (!result.ok) {
+          throw new Error('Workspace space scan cancelled')
+        }
+        const analysis = result.analysis
+        set({
+          workspaceSpaceAnalysis: analysis,
+          workspaceSpaceScanning: false,
+          workspaceSpaceScanProgress: null
+        })
         return analysis
       })
       .catch((error: unknown) => {
-        set({ workspaceSpaceScanError: errorMessage(error), workspaceSpaceScanning: false })
+        set({
+          workspaceSpaceScanError: isWorkspaceSpaceScanCancelled(error)
+            ? null
+            : errorMessage(error),
+          workspaceSpaceScanning: false,
+          workspaceSpaceScanProgress: null
+        })
         throw error
       })
       .finally(() => {
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 32b2606864f..2493e78f45e 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -580,9 +580,12 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           sortEpoch: s.sortEpoch + 1
         }
       })
+      get().removeWorkspaceSpaceWorktrees?.([worktreeId])
       return { ok: true as const }
     } catch (err) {
-      console.error('Failed to remove worktree:', err)
+      // Why: git refusing a non-force delete for dirty/untracked files is a
+      // handled user decision point surfaced by the delete toast, not an app error.
+      console.warn('Failed to remove worktree:', err)
       const error = err instanceof Error ? err.message : String(err)
       set((s) => ({
         deleteStateByWorktreeId: {
diff --git a/src/shared/workspace-space-compaction.ts b/src/shared/workspace-space-compaction.ts
new file mode 100644
index 00000000000..9b3ab739e92
--- /dev/null
+++ b/src/shared/workspace-space-compaction.ts
@@ -0,0 +1,41 @@
+import type { WorkspaceSpaceItem } from './workspace-space-types'
+
+export const WORKSPACE_SPACE_MAX_TOP_LEVEL_ITEMS = 48
+
+export function compactWorkspaceSpaceItems(items: WorkspaceSpaceItem[]): {
+  topLevelItems: WorkspaceSpaceItem[]
+  omittedTopLevelItemCount: number
+  omittedTopLevelSizeBytes: number
+} {
+  const sorted = [...items].sort(
+    (a, b) => b.sizeBytes - a.sizeBytes || a.name.localeCompare(b.name)
+  )
+  if (sorted.length <= WORKSPACE_SPACE_MAX_TOP_LEVEL_ITEMS) {
+    return {
+      topLevelItems: sorted,
+      omittedTopLevelItemCount: 0,
+      omittedTopLevelSizeBytes: 0
+    }
+  }
+
+  const visible = sorted.slice(0, WORKSPACE_SPACE_MAX_TOP_LEVEL_ITEMS - 1)
+  const omitted = sorted.slice(WORKSPACE_SPACE_MAX_TOP_LEVEL_ITEMS - 1)
+  const other = omitted.reduce<WorkspaceSpaceItem>(
+    (acc, item) => ({
+      ...acc,
+      sizeBytes: acc.sizeBytes + item.sizeBytes
+    }),
+    {
+      name: 'Other',
+      path: '',
+      kind: 'other',
+      sizeBytes: 0
+    }
+  )
+
+  return {
+    topLevelItems: [...visible, other],
+    omittedTopLevelItemCount: omitted.length,
+    omittedTopLevelSizeBytes: other.sizeBytes
+  }
+}
diff --git a/src/shared/workspace-space-types.ts b/src/shared/workspace-space-types.ts
index 9913ec87200..bfd173db4eb 100644
--- a/src/shared/workspace-space-types.ts
+++ b/src/shared/workspace-space-types.ts
@@ -61,3 +61,28 @@ export type WorkspaceSpaceAnalysis = {
   repos: WorkspaceSpaceRepoSummary[]
   worktrees: WorkspaceSpaceWorktree[]
 }
+
+export type WorkspaceSpaceAnalyzeResult =
+  | { ok: true; analysis: WorkspaceSpaceAnalysis }
+  | { ok: false; cancelled: true }
+
+export type WorkspaceSpaceDirectoryScanResult = {
+  sizeBytes: number
+  skippedEntryCount: number
+  topLevelItems: WorkspaceSpaceItem[]
+  omittedTopLevelItemCount: number
+  omittedTopLevelSizeBytes: number
+}
+
+export type WorkspaceSpaceScanProgress = {
+  scanId: string
+  state: 'running' | 'cancelling'
+  startedAt: number
+  updatedAt: number
+  totalRepoCount: number
+  scannedRepoCount: number
+  totalWorktreeCount: number
+  scannedWorktreeCount: number
+  currentRepoDisplayName: string | null
+  currentWorktreeDisplayName: string | null
+}

From f4fcec5f598e8eabb1dbc5c5875747ae5bfa1ca4 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 15 May 2026 06:30:58 +0000
Subject: [PATCH 23/82] release: v1.4.2-rc.5

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

diff --git a/package.json b/package.json
index 5da12543545..9582a2632c7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.2-rc.4",
+  "version": "1.4.2-rc.5",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From 7d901f7809039920e0830a69cd2cacfc1887dc8d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 15 May 2026 06:32:56 +0000
Subject: [PATCH 24/82] release: v1.4.2-rc.6

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

diff --git a/package.json b/package.json
index 9582a2632c7..2a3b88d46c1 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.2-rc.5",
+  "version": "1.4.2-rc.6",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From f71397b1b75ea810f91ffe3db59b7d3fa0895661 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 00:05:42 -0700
Subject: [PATCH 25/82] perf(renderer): avoid runtime graph work on title ticks
 (#1903)

---
 src/renderer/src/App.tsx                      |  11 +-
 .../src/components/tab-bar/group-tab-order.ts |  26 ++-
 .../sync-runtime-graph-key-reuse.test.ts      | 135 ++++++++++++++
 .../src/runtime/sync-runtime-graph.ts         | 170 +++++++++++++-----
 4 files changed, 282 insertions(+), 60 deletions(-)
 create mode 100644 src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts

diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 68642e47ec1..13a8edf6bc9 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -617,11 +617,10 @@ function App(): React.JSX.Element {
   useEffect(() => {
     let previousKey = getRuntimeMobileSessionSyncKey(useAppStore.getState())
     return useAppStore.subscribe((state, previousState) => {
-      // Why: skip the key build entirely when no input field has changed by
-      // reference. Mirrors every field used by getRuntimeMobileSessionSyncKey
-      // so this gate covers every "could the key have changed?" case.
-      // — if any field's reference is unchanged, neither the projection
-      // serialized from it nor the reference-compared map can have changed.
+      // Why: skip the key build entirely when every input field is unchanged
+      // by reference. Mirrors every field used by
+      // getRuntimeMobileSessionSyncKey so this gate covers every "could the
+      // key have changed?" case.
       if (
         state.tabsByWorktree === previousState.tabsByWorktree &&
         state.groupsByWorktree === previousState.groupsByWorktree &&
@@ -638,7 +637,7 @@ function App(): React.JSX.Element {
       ) {
         return
       }
-      const nextKey = getRuntimeMobileSessionSyncKey(state)
+      const nextKey = getRuntimeMobileSessionSyncKey(state, previousState, previousKey)
       if (runtimeMobileSessionSyncKeysEqual(nextKey, previousKey)) {
         return
       }
diff --git a/src/renderer/src/components/tab-bar/group-tab-order.ts b/src/renderer/src/components/tab-bar/group-tab-order.ts
index 983e51d085c..b0d4fa2f1e6 100644
--- a/src/renderer/src/components/tab-bar/group-tab-order.ts
+++ b/src/renderer/src/components/tab-bar/group-tab-order.ts
@@ -8,6 +8,13 @@ export type VisibleTabRef = {
   tabId?: string
 }
 
+export type ActiveTabNavOrderIds = {
+  terminalIds?: string[]
+  editorIds?: string[]
+  browserIds?: string[]
+  notesIds?: string[]
+}
+
 /**
  * Compute the visible tab-strip order for a single group.
  *
@@ -116,14 +123,19 @@ export function getActiveTabNavOrder(
     | 'openFiles'
     | 'browserTabsByWorktree'
   >,
-  worktreeId: string
+  worktreeId: string,
+  ids: ActiveTabNavOrderIds = {}
 ): VisibleTabRef[] {
-  const terminalIds = (state.tabsByWorktree[worktreeId] ?? []).map((t) => t.id)
-  const editorIds = state.openFiles.filter((f) => f.worktreeId === worktreeId).map((f) => f.id)
-  const browserIds = (state.browserTabsByWorktree[worktreeId] ?? []).map((t) => t.id)
-  const notesIds = (state.unifiedTabsByWorktree[worktreeId] ?? [])
-    .filter((tab) => tab.contentType === 'notes')
-    .map((tab) => tab.id)
+  const terminalIds = ids.terminalIds ?? (state.tabsByWorktree[worktreeId] ?? []).map((t) => t.id)
+  const editorIds =
+    ids.editorIds ?? state.openFiles.filter((f) => f.worktreeId === worktreeId).map((f) => f.id)
+  const browserIds =
+    ids.browserIds ?? (state.browserTabsByWorktree?.[worktreeId] ?? []).map((t) => t.id)
+  const notesIds =
+    ids.notesIds ??
+    (state.unifiedTabsByWorktree?.[worktreeId] ?? [])
+      .filter((tab) => tab.contentType === 'notes')
+      .map((tab) => tab.id)
 
   const activeGroupId = state.activeGroupIdByWorktree[worktreeId]
   const group = activeGroupId
diff --git a/src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts b/src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts
new file mode 100644
index 00000000000..4a5294521fd
--- /dev/null
+++ b/src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts
@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  buildMobileSessionTabSnapshots,
+  getRuntimeMobileSessionSyncKey,
+  runtimeMobileSessionSyncKeysEqual
+} from './sync-runtime-graph'
+import type { AppState } from '../store/types'
+
+function makeState(overrides: Partial<AppState> = {}): AppState {
+  return {
+    tabsByWorktree: {},
+    terminalLayoutsByTabId: {} as AppState['terminalLayoutsByTabId'],
+    runtimePaneTitlesByTabId: {} as AppState['runtimePaneTitlesByTabId'],
+    groupsByWorktree: {},
+    activeGroupIdByWorktree: {},
+    unifiedTabsByWorktree: {},
+    tabBarOrderByWorktree: {},
+    activeFileId: null,
+    activeFileIdByWorktree: {},
+    openFiles: [],
+    editorDrafts: {},
+    activeTabId: null,
+    ...overrides
+  } as AppState
+}
+
+function makeOpenMarkdownFile(): AppState['openFiles'][number] {
+  return {
+    id: '/repo/README.md',
+    filePath: '/repo/README.md',
+    relativePath: 'README.md',
+    worktreeId: 'wt-1',
+    language: 'markdown',
+    mode: 'edit',
+    isDirty: false
+  }
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('runtime mobile session sync key projection reuse', () => {
+  it('reuses serialized projections when only runtime pane titles change', () => {
+    const base = makeState({
+      tabsByWorktree: {
+        'wt-1': [{ id: 'term-1', title: 'Codex working', customTitle: null }]
+      } as unknown as AppState['tabsByWorktree'],
+      runtimePaneTitlesByTabId: {
+        'term-1': { 1: 'Codex working' }
+      } as unknown as AppState['runtimePaneTitlesByTabId'],
+      openFiles: [makeOpenMarkdownFile()],
+      editorDrafts: { '/repo/README.md': '# draft' }
+    })
+    const baseKey = getRuntimeMobileSessionSyncKey(base)
+    const titleTick = makeState({
+      ...base,
+      runtimePaneTitlesByTabId: {
+        'term-1': { 1: 'Codex spinner frame' }
+      } as unknown as AppState['runtimePaneTitlesByTabId']
+    })
+
+    const stringifySpy = vi.spyOn(JSON, 'stringify')
+    stringifySpy.mockClear()
+    const titleTickKey = getRuntimeMobileSessionSyncKey(titleTick, base, baseKey)
+
+    expect(stringifySpy).not.toHaveBeenCalled()
+    expect(titleTickKey.tabsProjection).toBe(baseKey.tabsProjection)
+    expect(titleTickKey.openFilesProjection).toBe(baseKey.openFilesProjection)
+    expect(titleTickKey.editorDraftsProjection).toBe(baseKey.editorDraftsProjection)
+    expect(runtimeMobileSessionSyncKeysEqual(baseKey, titleTickKey)).toBe(false)
+  })
+
+  it('only rebuilds the tab projection when a terminal tab title changes', () => {
+    const base = makeState({
+      tabsByWorktree: {
+        'wt-1': [{ id: 'term-1', title: 'Codex working', customTitle: null }]
+      } as unknown as AppState['tabsByWorktree'],
+      openFiles: [makeOpenMarkdownFile()],
+      editorDrafts: { '/repo/README.md': '# draft' }
+    })
+    const baseKey = getRuntimeMobileSessionSyncKey(base)
+    const titleTick = makeState({
+      ...base,
+      tabsByWorktree: {
+        'wt-1': [{ id: 'term-1', title: 'Codex spinner frame', customTitle: null }]
+      } as unknown as AppState['tabsByWorktree']
+    })
+
+    const stringifySpy = vi.spyOn(JSON, 'stringify')
+    stringifySpy.mockClear()
+    const titleTickKey = getRuntimeMobileSessionSyncKey(titleTick, base, baseKey)
+
+    expect(stringifySpy).toHaveBeenCalledTimes(1)
+    expect(titleTickKey.tabsProjection).not.toBe(baseKey.tabsProjection)
+    expect(titleTickKey.openFilesProjection).toBe(baseKey.openFilesProjection)
+    expect(titleTickKey.editorDraftsProjection).toBe(baseKey.editorDraftsProjection)
+    expect(runtimeMobileSessionSyncKeysEqual(baseKey, titleTickKey)).toBe(false)
+  })
+})
+
+describe('mobile session snapshot reuse', () => {
+  it('reuses draft document versions when only runtime pane titles change', () => {
+    const draft = {
+      length: 1,
+      charCodeAt: vi.fn(() => 120)
+    } as unknown as string
+    const draftSpy = (draft as unknown as { charCodeAt: ReturnType<typeof vi.fn> }).charCodeAt
+    const base = makeState({
+      tabsByWorktree: {
+        'wt-1': [{ id: 'term-1', title: 'Codex working', customTitle: null }]
+      } as unknown as AppState['tabsByWorktree'],
+      tabBarOrderByWorktree: { 'wt-1': ['term-1', '/repo/README.md'] },
+      runtimePaneTitlesByTabId: {
+        'term-1': { 1: 'Codex working' }
+      } as unknown as AppState['runtimePaneTitlesByTabId'],
+      openFiles: [makeOpenMarkdownFile()],
+      editorDrafts: { '/repo/README.md': draft },
+      activeFileId: '/repo/README.md'
+    })
+
+    buildMobileSessionTabSnapshots(base)
+    expect(draftSpy).toHaveBeenCalled()
+    draftSpy.mockClear()
+
+    buildMobileSessionTabSnapshots({
+      ...base,
+      runtimePaneTitlesByTabId: {
+        'term-1': { 1: 'Codex spinner frame' }
+      } as unknown as AppState['runtimePaneTitlesByTabId']
+    })
+
+    expect(draftSpy).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/runtime/sync-runtime-graph.ts b/src/renderer/src/runtime/sync-runtime-graph.ts
index e6fc07c9162..7d8de532d0e 100644
--- a/src/renderer/src/runtime/sync-runtime-graph.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph.ts
@@ -25,6 +25,10 @@ type RegisteredTerminalTab = {
 }
 
 type OpenFileByWorktreeAndId = Map<string, Map<string, AppState['openFiles'][number]>>
+type OpenFileIndexes = {
+  byWorktreeAndId: OpenFileByWorktreeAndId
+  idsByWorktree: Map<string, string[]>
+}
 
 const registeredTabs = new Map<string, RegisteredTerminalTab>()
 // Why: track when each tab was registered so we can suppress the "no live
@@ -38,6 +42,10 @@ let syncScheduled = false
 let syncEnabled = false
 let getStoreState: (() => AppState) | null = null
 let mobileSessionSnapshotVersion = 0
+let cachedOpenFileIndexesSource: AppState['openFiles'] | null = null
+let cachedOpenFileIndexes: OpenFileIndexes | null = null
+let cachedEditorDraftsSource: AppState['editorDrafts'] | null = null
+let cachedEditorDraftVersionByFileId: Map<string, string> | null = null
 const mobileSessionPublicationEpoch =
   typeof crypto !== 'undefined' && 'randomUUID' in crypto
     ? crypto.randomUUID()
@@ -120,7 +128,13 @@ export type RuntimeMobileSessionSyncKey = {
   editorDraftsProjection: string
 }
 
-export function getRuntimeMobileSessionSyncKey(state: AppState): RuntimeMobileSessionSyncKey {
+export function getRuntimeMobileSessionSyncKey(
+  state: AppState,
+  previousState?: AppState,
+  previousKey?: RuntimeMobileSessionSyncKey
+): RuntimeMobileSessionSyncKey {
+  const canReusePrevious = previousState !== undefined && previousKey !== undefined
+
   return {
     terminalLayoutsByTabId: state.terminalLayoutsByTabId,
     runtimePaneTitlesByTabId: state.runtimePaneTitlesByTabId,
@@ -130,43 +144,66 @@ export function getRuntimeMobileSessionSyncKey(state: AppState): RuntimeMobileSe
     tabBarOrderByWorktree: state.tabBarOrderByWorktree,
     activeFileId: state.activeFileId,
     activeFileIdByWorktree: state.activeFileIdByWorktree,
-    tabsProjection: JSON.stringify(
-      Object.fromEntries(
-        Object.entries(state.tabsByWorktree).map(([worktreeId, tabs]) => [
-          worktreeId,
-          tabs.map((tab) => ({
-            id: tab.id,
-            title: tab.title,
-            customTitle: tab.customTitle,
-            active: state.activeTabId === tab.id
-          }))
-        ])
-      )
-    ),
-    openFilesProjection: JSON.stringify(
-      state.openFiles.map((file) => ({
-        id: file.id,
-        filePath: file.filePath,
-        relativePath: file.relativePath,
-        worktreeId: file.worktreeId,
-        language: file.language,
-        mode: file.mode,
-        isDirty: file.isDirty,
-        isUntitled: file.isUntitled,
-        markdownPreviewSourceFileId: file.markdownPreviewSourceFileId
-      }))
-    ),
-    editorDraftsProjection: JSON.stringify(
-      Object.fromEntries(
-        Object.entries(state.editorDrafts).map(([fileId, content]) => [
-          fileId,
-          stableHashString(content)
-        ])
-      )
-    )
+    // Why: background agent title ticks can change runtimePaneTitlesByTabId
+    // many times per second while the user types elsewhere. Reuse unchanged
+    // projections so those ticks do not rescan all tabs, files, and drafts.
+    tabsProjection:
+      canReusePrevious &&
+      state.tabsByWorktree === previousState.tabsByWorktree &&
+      state.activeTabId === previousState.activeTabId
+        ? previousKey.tabsProjection
+        : buildRuntimeMobileTabsProjection(state),
+    openFilesProjection:
+      canReusePrevious && state.openFiles === previousState.openFiles
+        ? previousKey.openFilesProjection
+        : buildRuntimeMobileOpenFilesProjection(state.openFiles),
+    editorDraftsProjection:
+      canReusePrevious && state.editorDrafts === previousState.editorDrafts
+        ? previousKey.editorDraftsProjection
+        : buildRuntimeMobileEditorDraftsProjection(state.editorDrafts)
   }
 }
 
+function buildRuntimeMobileTabsProjection(state: AppState): string {
+  return JSON.stringify(
+    Object.fromEntries(
+      Object.entries(state.tabsByWorktree).map(([worktreeId, tabs]) => [
+        worktreeId,
+        tabs.map((tab) => ({
+          id: tab.id,
+          title: tab.title,
+          customTitle: tab.customTitle,
+          active: state.activeTabId === tab.id
+        }))
+      ])
+    )
+  )
+}
+
+function buildRuntimeMobileOpenFilesProjection(openFiles: AppState['openFiles']): string {
+  return JSON.stringify(
+    openFiles.map((file) => ({
+      id: file.id,
+      filePath: file.filePath,
+      relativePath: file.relativePath,
+      worktreeId: file.worktreeId,
+      language: file.language,
+      mode: file.mode,
+      isDirty: file.isDirty,
+      isUntitled: file.isUntitled,
+      markdownPreviewSourceFileId: file.markdownPreviewSourceFileId
+    }))
+  )
+}
+
+function buildRuntimeMobileEditorDraftsProjection(editorDrafts: AppState['editorDrafts']): string {
+  return JSON.stringify(
+    Object.fromEntries(
+      Object.entries(editorDrafts).map(([fileId, content]) => [fileId, stableHashString(content)])
+    )
+  )
+}
+
 export function runtimeMobileSessionSyncKeysEqual(
   a: RuntimeMobileSessionSyncKey,
   b: RuntimeMobileSessionSyncKey
@@ -267,10 +304,11 @@ async function syncRuntimeGraph(): Promise<void> {
 export function buildMobileSessionTabSnapshots(
   state: AppState
 ): RuntimeMobileSessionTabsSnapshot[] {
-  // Why: mobile publication walks the tab order for every worktree. A single
-  // worktree-scoped file map keeps large editor sessions linear without
-  // collapsing SSH worktrees that expose the same absolute remote path.
-  const openFileByWorktreeAndId = indexOpenFilesByWorktreeAndId(state.openFiles)
+  // Why: mobile publication can run on high-frequency background agent title
+  // ticks. Cache open-file indexes and draft hashes by immutable store-slice
+  // reference so title-only syncs do not rescan or rehash editor state.
+  const openFileIndexes = getOpenFileIndexes(state.openFiles)
+  const editorDraftVersionByFileId = getEditorDraftVersionByFileId(state.editorDrafts)
   const worktreeIds = new Set<string>([
     ...Object.keys(state.tabsByWorktree),
     ...Object.keys(state.groupsByWorktree),
@@ -281,7 +319,9 @@ export function buildMobileSessionTabSnapshots(
   const snapshots: RuntimeMobileSessionTabsSnapshot[] = []
   for (const worktreeId of worktreeIds) {
     const activeGroupId = state.activeGroupIdByWorktree[worktreeId] ?? null
-    const order = getActiveTabNavOrder(state, worktreeId)
+    const order = getActiveTabNavOrder(state, worktreeId, {
+      editorIds: openFileIndexes.idsByWorktree.get(worktreeId) ?? []
+    })
     const terminalTabByIdForWorktree = new Map(
       (state.tabsByWorktree[worktreeId] ?? []).map((tab) => [tab.id, tab])
     )
@@ -295,11 +335,17 @@ export function buildMobileSessionTabSnapshots(
         }
         tabs.push(...buildMobileTerminalSurfaceTabs(state, terminal, worktreeId, item.tabId))
       } else if (item.type === 'editor') {
-        const file = openFileByWorktreeAndId.get(worktreeId)?.get(item.id)
+        const file = openFileIndexes.byWorktreeAndId.get(worktreeId)?.get(item.id)
         if (!file) {
           continue
         }
-        const markdown = buildMobileMarkdownTab(state, openFileByWorktreeAndId, file, item.tabId)
+        const markdown = buildMobileMarkdownTab(
+          state,
+          openFileIndexes.byWorktreeAndId,
+          editorDraftVersionByFileId,
+          file,
+          item.tabId
+        )
         if (markdown) {
           tabs.push(markdown)
         } else {
@@ -323,19 +369,49 @@ export function buildMobileSessionTabSnapshots(
   return snapshots
 }
 
-function indexOpenFilesByWorktreeAndId(openFiles: AppState['openFiles']): OpenFileByWorktreeAndId {
+function getOpenFileIndexes(openFiles: AppState['openFiles']): OpenFileIndexes {
+  if (cachedOpenFileIndexesSource === openFiles && cachedOpenFileIndexes) {
+    return cachedOpenFileIndexes
+  }
+
   const byWorktreeAndId: OpenFileByWorktreeAndId = new Map()
+  const idsByWorktree = new Map<string, string[]>()
   for (const file of openFiles) {
     let filesById = byWorktreeAndId.get(file.worktreeId)
     if (!filesById) {
       filesById = new Map()
       byWorktreeAndId.set(file.worktreeId, filesById)
     }
+    let ids = idsByWorktree.get(file.worktreeId)
+    if (!ids) {
+      ids = []
+      idsByWorktree.set(file.worktreeId, ids)
+    }
     if (!filesById.has(file.id)) {
       filesById.set(file.id, file)
+      ids.push(file.id)
     }
   }
-  return byWorktreeAndId
+
+  cachedOpenFileIndexesSource = openFiles
+  cachedOpenFileIndexes = { byWorktreeAndId, idsByWorktree }
+  return cachedOpenFileIndexes
+}
+
+function getEditorDraftVersionByFileId(
+  editorDrafts: AppState['editorDrafts']
+): Map<string, string> {
+  if (cachedEditorDraftsSource === editorDrafts && cachedEditorDraftVersionByFileId) {
+    return cachedEditorDraftVersionByFileId
+  }
+
+  const versions = new Map<string, string>()
+  for (const [fileId, content] of Object.entries(editorDrafts)) {
+    versions.set(fileId, stableHashString(content))
+  }
+  cachedEditorDraftsSource = editorDrafts
+  cachedEditorDraftVersionByFileId = versions
+  return versions
 }
 
 function mobileTerminalSurfaceId(parentTabId: string, leafId: string): string {
@@ -399,6 +475,7 @@ function buildMobileTerminalSurfaceTabs(
 function buildMobileMarkdownTab(
   state: AppState,
   openFileByWorktreeAndId: OpenFileByWorktreeAndId,
+  editorDraftVersionByFileId: ReadonlyMap<string, string>,
   file: AppState['openFiles'][number],
   unifiedTabId?: string
 ): RuntimeMobileSessionMarkdownTab | null {
@@ -414,7 +491,7 @@ function buildMobileMarkdownTab(
       ? (openFileByWorktreeAndId.get(file.worktreeId)?.get(file.markdownPreviewSourceFileId) ??
         file)
       : file
-  const draftContent = state.editorDrafts[sourceFile.id]
+  const draftVersion = editorDraftVersionByFileId.get(sourceFile.id)
   const title = file.relativePath.split(/[\\/]/).pop() || file.relativePath || 'Markdown'
 
   return {
@@ -434,8 +511,7 @@ function buildMobileMarkdownTab(
     sourceFileId: sourceFile.id,
     sourceFilePath: sourceFile.filePath,
     sourceRelativePath: sourceFile.relativePath,
-    documentVersion:
-      draftContent !== undefined ? stableHashString(draftContent) : `file:${sourceFile.id}`
+    documentVersion: draftVersion ?? `file:${sourceFile.id}`
   }
 }
 

From 39b8c5026af3b1bb9163abe14f83ec7c73c98943 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 00:20:13 -0700
Subject: [PATCH 26/82] docs: add Korean README (#1905)

---
 README.md            |   2 +-
 docs/README.es.md    |   2 +-
 docs/README.ja.md    |   2 +-
 docs/README.ko.md    | 146 +++++++++++++++++++++++++++++++++++++++++++
 docs/README.zh-CN.md |   2 +-
 5 files changed, 150 insertions(+), 4 deletions(-)
 create mode 100644 docs/README.ko.md

diff --git a/README.md b/README.md
index 18883b5f506..5dfd755e0c2 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="README.md">English</a> · <a href="docs/README.zh-CN.md">中文</a> · <a href="docs/README.ja.md">日本語</a> · <a href="docs/README.es.md">Español</a>
+  <a href="README.md">English</a> · <a href="docs/README.zh-CN.md">中文</a> · <a href="docs/README.ja.md">日本語</a> · <a href="docs/README.ko.md">한국어</a> · <a href="docs/README.es.md">Español</a>
 </p>
 
 <p align="center">
diff --git a/docs/README.es.md b/docs/README.es.md
index 4c202863d9c..1147e3b7bc8 100644
--- a/docs/README.es.md
+++ b/docs/README.es.md
@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a>
+  <a href="../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a>
 </p>
 
 <p align="center">
diff --git a/docs/README.ja.md b/docs/README.ja.md
index 22fa693960b..35f688e949b 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a>
+  <a href="../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a>
 </p>
 
 <p align="center">
diff --git a/docs/README.ko.md b/docs/README.ko.md
new file mode 100644
index 00000000000..42fabf357ed
--- /dev/null
+++ b/docs/README.ko.md
@@ -0,0 +1,146 @@
+<h1 align="center">
+  <a href="https://onOrca.dev"><img src="../resources/build/icon.png" alt="Orca" width="64" valign="middle" /></a> Orca
+</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Platform-macOS%20%7C%20Windows%20%7C%20Linux-blue?style=for-the-badge" alt="지원 플랫폼" />
+  <a href="https://discord.gg/fzjDKHxv8Q"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord" /></a>
+  <a href="https://x.com/orca_build"><img src="https://img.shields.io/badge/%E2%80%8E-Follow_@orca__build-000000?style=for-the-badge&logo=x&logoColor=white" alt="X에서 팔로우" /></a>
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a>
+</p>
+
+<p align="center">
+  <strong>100x 빌더를 위한 AI 오케스트레이터.</strong><br/>
+  Claude Code, Codex, OpenCode를 여러 리포지토리에서 나란히 실행하세요. 각 에이전트는 자체 worktree에서 실행되고 한곳에서 추적됩니다.<br/>
+  <strong>macOS, Windows, Linux</strong>에서 사용할 수 있습니다.
+</p>
+
+<p align="center">
+  <a href="#설치"><strong>다운로드 🐋</strong></a>
+</p>
+
+<p align="center">
+  <img src="assets/file-drag.gif" alt="Orca 스크린샷" width="800" />
+</p>
+
+## 지원 에이전트
+
+Orca는 모든 CLI 에이전트를 지원합니다(*아래 목록에만 한정되지 않습니다*).
+
+<p>
+  <a href="https://docs.anthropic.com/claude/docs/claude-code"><kbd><img src="assets/claude-logo.svg" width="16" valign="middle" /> Claude Code</kbd></a> &nbsp;
+  <a href="https://github.com/openai/codex"><kbd><img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" width="16" valign="middle" /> Codex</kbd></a> &nbsp;
+  <a href="https://github.com/google-gemini/gemini-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=gemini.google.com&sz=64" width="16" valign="middle" /> Gemini</kbd></a> &nbsp;
+  <a href="https://pi.dev"><kbd><img src="https://pi.dev/favicon.svg" width="16" valign="middle" /> Pi</kbd></a> &nbsp;
+  <a href="https://hermes-agent.nousresearch.com/docs/"><kbd><img src="https://www.google.com/s2/favicons?domain=nousresearch.com&sz=64" width="16" valign="middle" /> Hermes Agent</kbd></a> &nbsp;
+  <a href="https://opencode.ai/docs/cli/"><kbd><img src="https://www.google.com/s2/favicons?domain=opencode.ai&sz=64" width="16" valign="middle" /> OpenCode</kbd></a> &nbsp;
+  <a href="https://block.github.io/goose/docs/quickstart/"><kbd><img src="https://www.google.com/s2/favicons?domain=goose-docs.ai&sz=64" width="16" valign="middle" /> Goose</kbd></a> &nbsp;
+  <a href="https://ampcode.com/manual#install"><kbd><img src="https://www.google.com/s2/favicons?domain=ampcode.com&sz=64" width="16" valign="middle" /> Amp</kbd></a> &nbsp;
+  <a href="https://docs.augmentcode.com/cli/overview"><kbd><img src="https://www.google.com/s2/favicons?domain=augmentcode.com&sz=64" width="16" valign="middle" /> Auggie</kbd></a> &nbsp;
+  <a href="https://github.com/autohandai/code-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=autohand.ai&sz=64" width="16" valign="middle" /> Autohand Code</kbd></a> &nbsp;
+  <a href="https://github.com/charmbracelet/crush"><kbd><img src="https://www.google.com/s2/favicons?domain=charm.sh&sz=64" width="16" valign="middle" /> Charm</kbd></a> &nbsp;
+  <a href="https://docs.cline.bot/cline-cli/overview"><kbd><img src="https://www.google.com/s2/favicons?domain=cline.bot&sz=64" width="16" valign="middle" /> Cline</kbd></a> &nbsp;
+  <a href="https://www.codebuff.com/docs/help/quick-start"><kbd><img src="https://www.google.com/s2/favicons?domain=codebuff.com&sz=64" width="16" valign="middle" /> Codebuff</kbd></a> &nbsp;
+  <a href="https://docs.continue.dev/guides/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=continue.dev&sz=64" width="16" valign="middle" /> Continue</kbd></a> &nbsp;
+  <a href="https://cursor.com/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=cursor.com&sz=64" width="16" valign="middle" /> Cursor</kbd></a> &nbsp;
+  <a href="https://docs.factory.ai/cli/getting-started/quickstart"><kbd><img src="assets/droid-logo.svg" width="16" valign="middle" /> Droid</kbd></a> &nbsp;
+  <a href="https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=github.com&sz=64" width="16" valign="middle" /> GitHub Copilot</kbd></a> &nbsp;
+  <a href="https://kilo.ai/docs/cli"><kbd><img src="https://raw.githubusercontent.com/Kilo-Org/kilocode/main/packages/kilo-vscode/assets/icons/kilo-light.svg" width="16" valign="middle" /> Kilocode</kbd></a> &nbsp;
+  <a href="https://www.kimi.com/code/docs/en/kimi-code-cli/getting-started.html"><kbd><img src="https://www.google.com/s2/favicons?domain=moonshot.cn&sz=64" width="16" valign="middle" /> Kimi</kbd></a> &nbsp;
+  <a href="https://kiro.dev/docs/cli/"><kbd><img src="https://www.google.com/s2/favicons?domain=kiro.dev&sz=64" width="16" valign="middle" /> Kiro</kbd></a> &nbsp;
+  <a href="https://github.com/mistralai/mistral-vibe"><kbd><img src="https://www.google.com/s2/favicons?domain=mistral.ai&sz=64" width="16" valign="middle" /> Mistral Vibe</kbd></a> &nbsp;
+  <a href="https://github.com/QwenLM/qwen-code"><kbd><img src="https://www.google.com/s2/favicons?domain=qwenlm.github.io&sz=64" width="16" valign="middle" /> Qwen Code</kbd></a> &nbsp;
+  <a href="https://support.atlassian.com/rovo/docs/install-and-run-rovo-dev-cli-on-your-device/"><kbd><img src="https://www.google.com/s2/favicons?domain=atlassian.com&sz=64" width="16" valign="middle" /> Rovo Dev</kbd></a>
+</p>
+
+---
+
+## 기능
+
+- **로그인 불필요** — 보유한 Claude Code 또는 Codex 구독을 그대로 사용하세요.
+- **Worktree 네이티브** — 모든 기능은 자체 worktree를 가집니다. stash나 브랜치 전환에 얽매이지 않고 즉시 만들고 전환할 수 있습니다.
+- **멀티 에이전트 터미널** — 여러 AI 에이전트를 탭과 패널에서 나란히 실행하세요. 어떤 에이전트가 활성 상태인지 한눈에 볼 수 있습니다.
+- **내장 소스 관리** — AI가 생성한 diff를 검토하고, 빠르게 수정하고, Orca를 떠나지 않고 커밋할 수 있습니다.
+- **GitHub 통합** — PR, issue, Actions 체크가 각 worktree에 자동으로 연결됩니다.
+- **SSH 지원** — 원격 머신에 연결하고 Orca에서 직접 에이전트를 실행할 수 있습니다.
+- **알림** — 에이전트가 완료되거나 주의가 필요할 때 알려줍니다. 스레드를 읽지 않음으로 표시해 나중에 다시 볼 수 있습니다.
+
+---
+
+## 설치
+
+### Mac, Linux, Windows
+
+- **[onOrca.dev에서 다운로드](https://onOrca.dev)**
+- 또는 **[GitHub Releases 페이지](https://github.com/stablyai/orca/releases/latest)** 에서 받기
+
+*패키지 매니저로도 설치할 수 있습니다:*
+
+### macOS (Homebrew)
+
+```bash
+brew install --cask stablyai/orca/orca
+```
+
+### Arch Linux (AUR)
+
+```bash
+# 사전 컴파일된 바이너리
+yay -S stably-orca-bin
+
+# GitHub 소스에서 빌드
+yay -S stably-orca-git
+```
+
+---
+
+## 모바일 Companion 앱
+
+휴대폰에서 에이전트를 제어하세요.
+
+<p align="center">
+  <picture><source srcset="assets/feature-wall/mobile-companion-app-showcase.gif" type="image/gif"><img src="assets/feature-wall/mobile-companion-app-showcase.jpg" alt="Orca 데스크톱과 모바일 companion 앱" width="720" /></picture>
+</p>
+
+- **iOS:** [App Store에서 다운로드](https://apps.apple.com/us/app/orca-ide/id6766130217)
+- **Android:** [GH release에서 다운로드(최신 mobile 릴리스를 찾으세요)](https://github.com/stablyai/orca/releases)
+
+---
+
+## 기능 쇼케이스
+
+타일을 클릭해 각 워크플로를 살펴보세요.
+
+<p align="center">
+  <a href="https://www.onorca.dev/docs/model/worktrees"><kbd><strong>병렬 Worktree</strong><br/><br/><picture><source srcset="assets/feature-wall/parallel-worktrees.gif" type="image/gif"><img src="assets/feature-wall/parallel-worktrees.jpg" alt="병렬 worktree 오케스트레이션" width="390" /></picture><br/></kbd></a> &nbsp;&nbsp;
+  <a href="https://www.onorca.dev/docs/terminal"><kbd><strong>터미널 분할</strong><br/><br/><picture><source srcset="assets/feature-wall/terminal-splits.gif" type="image/gif"><img src="assets/feature-wall/terminal-splits.jpg" alt="Ghostty급 터미널 분할" width="390" /></picture><br/></kbd></a><br/><br/>
+  <a href="https://www.onorca.dev/docs/browser/design-mode"><kbd><strong>디자인 모드</strong><br/><br/><picture><source srcset="assets/feature-wall/design-mode.gif" type="image/gif"><img src="assets/feature-wall/design-mode.jpg" alt="내장 브라우저와 디자인 모드" width="390" /></picture><br/></kbd></a> &nbsp;&nbsp;
+  <a href="https://www.onorca.dev/docs/review/linear"><kbd><strong>GitHub 및 Linear 네이티브</strong><br/><br/><picture><source srcset="assets/feature-wall/github-linear.gif" type="image/gif"><img src="assets/feature-wall/github-linear.jpg" alt="Orca의 GitHub 및 Linear 워크플로" width="390" /></picture><br/></kbd></a><br/><br/>
+  <a href="https://www.onorca.dev/docs/agents/supported"><kbd><strong>모든 CLI 에이전트</strong><br/><br/><picture><source srcset="assets/feature-wall/cli-agents.gif" type="image/gif"><img src="assets/feature-wall/cli-agents.jpg" alt="모든 CLI 에이전트 지원" width="390" /></picture><br/></kbd></a> &nbsp;&nbsp;
+  <a href="https://www.onorca.dev/docs/ssh"><kbd><strong>SSH Worktree</strong><br/><br/><picture><source srcset="assets/feature-wall/ssh-worktrees.gif" type="image/gif"><img src="assets/feature-wall/ssh-worktrees.jpg" alt="SSH를 통한 원격 worktree" width="390" /></picture><br/></kbd></a><br/><br/>
+  <a href="https://www.onorca.dev/docs/editing/file-explorer"><kbd><strong>에이전트로 파일 드래그</strong><br/><br/><picture><source srcset="assets/feature-wall/file-drag.gif" type="image/gif"><img src="assets/feature-wall/file-drag.jpg" alt="파일과 이미지를 에이전트 프롬프트로 드래그" width="390" /></picture><br/></kbd></a> &nbsp;&nbsp;
+  <a href="https://www.onorca.dev/docs/review/annotate-ai-diff"><kbd><strong>AI Diff 주석</strong><br/><br/><picture><source srcset="assets/feature-wall/annotate-diff.gif" type="image/gif"><img src="assets/feature-wall/annotate-diff.jpg" alt="AI가 생성한 diff에 주석 달기" width="390" /></picture><br/></kbd></a><br/><br/>
+  <a href="https://www.onorca.dev/docs/cli/overview"><kbd><strong>Orca CLI</strong><br/><br/><picture><source srcset="assets/feature-wall/orca-cli.gif" type="image/gif"><img src="assets/feature-wall/orca-cli.jpg" alt="CLI에서 Orca 스크립팅" width="390" /></picture><br/></kbd></a> &nbsp;&nbsp;
+  <a href="https://www.onorca.dev/docs/settings"><kbd><strong>네이티브 검색</strong><br/><br/><picture><source srcset="assets/feature-wall/keyboard-native.gif" type="image/gif"><img src="assets/feature-wall/keyboard-native.jpg" alt="Orca 워크플로 전반의 네이티브 검색" width="390" /></picture><br/></kbd></a><br/><br/>
+  <a href="https://www.onorca.dev/docs/agents/usage-tracking"><kbd><strong>계정 전환 및 사용량 추적</strong><br/><br/><picture><source srcset="assets/feature-wall/codex-accounts.gif" type="image/gif"><img src="assets/feature-wall/codex-accounts.jpg" alt="계정 전환 및 사용량 추적" width="390" /></picture><br/></kbd></a> &nbsp;&nbsp;
+  <a href="https://www.onorca.dev/docs/editing/markdown"><kbd><strong>풍부한 리포지토리 미리보기</strong><br/><br/><picture><source srcset="assets/feature-wall/markdown-editor.gif" type="image/gif"><img src="assets/feature-wall/markdown-editor.jpg" alt="Markdown, 이미지, PDF, 리포지토리 문서 미리보기" width="390" /></picture><br/></kbd></a><br/><br/>
+  <a href="https://www.onorca.dev/docs/model/tabs-panes-splits"><kbd><strong>무엇이든 분할</strong><br/><br/><picture><source srcset="assets/feature-wall/split-screen.gif" type="image/gif"><img src="assets/feature-wall/split-screen.jpg" alt="에이전트, 터미널, 브라우저, 파일을 위한 분할 패널" width="390" /></picture><br/></kbd></a>
+</p>
+
+---
+
+## 커뮤니티와 지원
+
+- **Discord:** **[Discord](https://discord.gg/fzjDKHxv8Q)** 커뮤니티에 참여하세요.
+- **Twitter / X:** 업데이트와 공지는 **[@orca_build](https://x.com/orca_build)** 를 팔로우하세요.
+- **피드백과 아이디어:** 우리는 빠르게 출시합니다. 필요한 기능이 있나요? [새 기능을 요청](https://github.com/stablyai/orca/issues)하세요.
+- **응원하기:** 이 리포지토리에 star를 눌러 일일 릴리스를 따라와 주세요.
+
+---
+
+## 개발
+
+기여하거나 로컬에서 실행하고 싶으신가요? [CONTRIBUTING.md](../.github/CONTRIBUTING.md) 가이드를 확인하세요.
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 83431be966a..855471739c8 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a>
+  <a href="../README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a>
 </p>
 
 <p align="center">

From 4415bde1e5f54f610109934010d8644e90b88b82 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 00:25:13 -0700
Subject: [PATCH 27/82] Open workspace board on header hover (#1904)

---
 .../src/components/sidebar/SidebarHeader.tsx  | 132 +++++++++++++++---
 .../sidebar/WorkspaceKanbanDrawer.tsx         |   5 +-
 2 files changed, 115 insertions(+), 22 deletions(-)

diff --git a/src/renderer/src/components/sidebar/SidebarHeader.tsx b/src/renderer/src/components/sidebar/SidebarHeader.tsx
index 8c1d4e7d320..57ff07b7934 100644
--- a/src/renderer/src/components/sidebar/SidebarHeader.tsx
+++ b/src/renderer/src/components/sidebar/SidebarHeader.tsx
@@ -1,5 +1,5 @@
-import React, { useState } from 'react'
-import { Kanban, Plus, SlidersHorizontal } from 'lucide-react'
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { Plus, SlidersHorizontal } from 'lucide-react'
 import { useAppStore } from '@/store'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipTrigger, TooltipContent } from '@/components/ui/tooltip'
@@ -51,9 +51,18 @@ const SORT_OPTIONS = [
 
 const isMac = navigator.userAgent.includes('Mac')
 const newWorktreeShortcutLabel = isMac ? '⌘N' : 'Ctrl+N'
+const WORKSPACE_BOARD_HOVER_OPEN_DELAY_MS = 50
+// Why: gives the pointer room to travel from the header into the board before
+// the temporary hover preview collapses.
+const WORKSPACE_BOARD_HOVER_CLOSE_DELAY_MS = 220
 
 const SidebarHeader = React.memo(function SidebarHeader() {
   const [workspaceBoardOpen, setWorkspaceBoardOpen] = useState(false)
+  // Why: entering the board turns the hover preview into a persistent drawer
+  // until the user explicitly closes it or clicks outside.
+  const workspaceBoardPinnedOpenRef = useRef(false)
+  const workspaceBoardHoverOpenTimerRef = useRef<number | null>(null)
+  const workspaceBoardHoverCloseTimerRef = useRef<number | null>(null)
   const openModal = useAppStore((s) => s.openModal)
   const repos = useAppStore((s) => s.repos)
   const canCreateWorktree = repos.some((repo) => isGitRepoKind(repo))
@@ -64,30 +73,107 @@ const SidebarHeader = React.memo(function SidebarHeader() {
   const setSortBy = useAppStore((s) => s.setSortBy)
   const groupBy = useAppStore((s) => s.groupBy)
   const setGroupBy = useAppStore((s) => s.setGroupBy)
+
+  const clearWorkspaceBoardHoverClose = useCallback(() => {
+    if (workspaceBoardHoverCloseTimerRef.current === null) {
+      return
+    }
+    window.clearTimeout(workspaceBoardHoverCloseTimerRef.current)
+    workspaceBoardHoverCloseTimerRef.current = null
+  }, [])
+
+  const clearWorkspaceBoardHoverOpen = useCallback(() => {
+    if (workspaceBoardHoverOpenTimerRef.current === null) {
+      return
+    }
+    window.clearTimeout(workspaceBoardHoverOpenTimerRef.current)
+    workspaceBoardHoverOpenTimerRef.current = null
+  }, [])
+
+  useEffect(
+    () => () => {
+      clearWorkspaceBoardHoverOpen()
+      clearWorkspaceBoardHoverClose()
+    },
+    [clearWorkspaceBoardHoverClose, clearWorkspaceBoardHoverOpen]
+  )
+
+  const setWorkspaceBoardPinned = useCallback((pinned: boolean) => {
+    workspaceBoardPinnedOpenRef.current = pinned
+  }, [])
+
+  const handleWorkspaceBoardOpenChange = useCallback(
+    (open: boolean) => {
+      clearWorkspaceBoardHoverOpen()
+      clearWorkspaceBoardHoverClose()
+      setWorkspaceBoardOpen(open)
+      if (!open) {
+        setWorkspaceBoardPinned(false)
+      }
+    },
+    [clearWorkspaceBoardHoverClose, clearWorkspaceBoardHoverOpen, setWorkspaceBoardPinned]
+  )
+
+  const handleWorkspaceHeaderPointerEnter = useCallback(
+    (event: React.PointerEvent<HTMLDivElement>) => {
+      if (event.pointerType !== 'mouse') {
+        return
+      }
+      clearWorkspaceBoardHoverClose()
+      if (workspaceBoardOpen) {
+        return
+      }
+      clearWorkspaceBoardHoverOpen()
+      workspaceBoardHoverOpenTimerRef.current = window.setTimeout(() => {
+        workspaceBoardHoverOpenTimerRef.current = null
+        setWorkspaceBoardOpen(true)
+      }, WORKSPACE_BOARD_HOVER_OPEN_DELAY_MS)
+    },
+    [clearWorkspaceBoardHoverClose, clearWorkspaceBoardHoverOpen, workspaceBoardOpen]
+  )
+
+  const handleWorkspaceHeaderPointerLeave = useCallback(
+    (event: React.PointerEvent<HTMLDivElement>) => {
+      clearWorkspaceBoardHoverOpen()
+      if (event.pointerType !== 'mouse' || workspaceBoardPinnedOpenRef.current) {
+        return
+      }
+      clearWorkspaceBoardHoverClose()
+      workspaceBoardHoverCloseTimerRef.current = window.setTimeout(() => {
+        workspaceBoardHoverCloseTimerRef.current = null
+        if (workspaceBoardPinnedOpenRef.current) {
+          return
+        }
+        setWorkspaceBoardOpen(false)
+      }, WORKSPACE_BOARD_HOVER_CLOSE_DELAY_MS)
+    },
+    [clearWorkspaceBoardHoverClose, clearWorkspaceBoardHoverOpen]
+  )
+
+  const handleWorkspaceBoardPointerEnter = useCallback(
+    (event: React.PointerEvent<HTMLDivElement>) => {
+      if (event.pointerType !== 'mouse') {
+        return
+      }
+      clearWorkspaceBoardHoverOpen()
+      clearWorkspaceBoardHoverClose()
+      setWorkspaceBoardPinned(true)
+      setWorkspaceBoardOpen(true)
+    },
+    [clearWorkspaceBoardHoverClose, clearWorkspaceBoardHoverOpen, setWorkspaceBoardPinned]
+  )
+
   return (
     <>
-      <div className="flex h-8 items-center justify-between px-2 gap-2">
+      <div
+        className="flex h-8 items-center justify-between px-2 gap-2"
+        onPointerEnter={handleWorkspaceHeaderPointerEnter}
+        onPointerLeave={handleWorkspaceHeaderPointerLeave}
+      >
         <div className="flex min-w-0 items-center gap-1">
           <span className="px-2 text-[10.5px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/80 select-none">
             Workspaces
           </span>
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <Button
-                variant="ghost"
-                size="icon-xs"
-                className="text-muted-foreground"
-                aria-label="Workspace board"
-                aria-pressed={workspaceBoardOpen}
-                onClick={() => setWorkspaceBoardOpen((open) => !open)}
-              >
-                <Kanban className="size-3.5" strokeWidth={2.25} />
-              </Button>
-            </TooltipTrigger>
-            <TooltipContent side="bottom" sideOffset={6}>
-              Workspace board
-            </TooltipContent>
-          </Tooltip>
         </div>
         <div className="flex items-center gap-1.5 shrink-0">
           <SidebarFilter />
@@ -208,7 +294,11 @@ const SidebarHeader = React.memo(function SidebarHeader() {
           </Tooltip>
         </div>
       </div>
-      <WorkspaceKanbanDrawer open={workspaceBoardOpen} onOpenChange={setWorkspaceBoardOpen} />
+      <WorkspaceKanbanDrawer
+        open={workspaceBoardOpen}
+        onOpenChange={handleWorkspaceBoardOpenChange}
+        onPointerEnter={handleWorkspaceBoardPointerEnter}
+      />
     </>
   )
 })
diff --git a/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx b/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx
index 51bab89d488..9fb88777aa6 100644
--- a/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx
+++ b/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx
@@ -28,6 +28,7 @@ import { makeWorkspaceStatusId } from '../../../../shared/workspace-statuses'
 type WorkspaceKanbanDrawerProps = {
   open: boolean
   onOpenChange: (open: boolean) => void
+  onPointerEnter?: React.PointerEventHandler<HTMLDivElement>
 }
 
 function sortBoardWorktrees(a: Worktree, b: Worktree): number {
@@ -36,7 +37,8 @@ function sortBoardWorktrees(a: Worktree, b: Worktree): number {
 
 export default function WorkspaceKanbanDrawer({
   open,
-  onOpenChange
+  onOpenChange,
+  onPointerEnter
 }: WorkspaceKanbanDrawerProps): React.JSX.Element {
   const allWorktrees = useAllWorktrees()
   const repoMap = useRepoMap()
@@ -287,6 +289,7 @@ export default function WorkspaceKanbanDrawer({
           } as React.CSSProperties
         }
         data-workspace-board-compact={workspaceBoardCompact ? 'true' : 'false'}
+        onPointerEnter={onPointerEnter}
         onOpenAutoFocus={(event) => {
           // Why: Radix focuses the first toolbar button on open, which opens
           // its tooltip without hover and makes the drawer feel noisy.

From 5451f35af324d761e8cb2bfab709728012787691 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 15 May 2026 07:31:19 +0000
Subject: [PATCH 28/82] release: v1.4.2-rc.7

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

diff --git a/package.json b/package.json
index 2a3b88d46c1..2c9c6ea5fae 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.2-rc.6",
+  "version": "1.4.2-rc.7",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From bce9f50205a216a8cd26165972ab2be6367ab219 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 00:46:46 -0700
Subject: [PATCH 29/82] Implemented the skip-flow fix. (#1906)

Changed:

  - src/renderer/src/components/sidebar/AddRepoDialog.tsx: Skip now finalizes
    the imported repo/worktree list without opening an existing worktree or
    launching create-worktree.
  - src/renderer/src/components/sidebar/add-repo-skip-finalization.ts: added
    focused logic to make the imported worktrees visible by clearing sidebar
    filters that would hide them.
  - src/renderer/src/components/sidebar/add-repo-skip-finalization.test.ts:
    regression coverage for skipped imports.

Co-authored-by: Orca <help@stably.ai>
---
 .../src/components/sidebar/AddRepoDialog.tsx  |  21 +++-
 .../add-repo-skip-finalization.test.ts        | 102 ++++++++++++++++++
 .../sidebar/add-repo-skip-finalization.ts     |  42 ++++++++
 3 files changed, 162 insertions(+), 3 deletions(-)
 create mode 100644 src/renderer/src/components/sidebar/add-repo-skip-finalization.test.ts
 create mode 100644 src/renderer/src/components/sidebar/add-repo-skip-finalization.ts

diff --git a/src/renderer/src/components/sidebar/AddRepoDialog.tsx b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
index 1a83b4b45de..600c1f7225e 100644
--- a/src/renderer/src/components/sidebar/AddRepoDialog.tsx
+++ b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
@@ -21,6 +21,7 @@ import { getDefaultCloneParent } from './clone-defaults'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import type { Repo, Worktree } from '../../../../shared/types'
+import { finalizeImportedRepoAfterSkip } from './add-repo-skip-finalization'
 
 const AddRepoDialog = React.memo(function AddRepoDialog() {
   const activeModal = useAppStore((s) => s.activeModal)
@@ -299,14 +300,26 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
     openSettingsPage()
   }, [closeModal, openSettingsTarget, openSettingsPage, repoId])
 
+  const finishImportedRepoWithoutOpening = useCallback(async () => {
+    const importedRepoId = repoId
+    closeModal()
+    resetState()
+    if (!importedRepoId) {
+      return
+    }
+
+    await fetchWorktrees(importedRepoId)
+    const state = useAppStore.getState()
+    finalizeImportedRepoAfterSkip(state, importedRepoId)
+  }, [closeModal, fetchWorktrees, repoId, resetState])
+
   // Why: handleBack reuses resetState which already aborts clones and resets all fields.
   const handleBack = resetState
 
   const handleSkip = useCallback(() => {
     track('add_repo_setup_step_action', { action: 'skip' })
-    closeModal()
-    resetState()
-  }, [closeModal, resetState])
+    void finishImportedRepoWithoutOpening()
+  }, [finishImportedRepoWithoutOpening])
 
   // Why: only the Setup step's "Add another project" back arrow counts as a
   // funnel event — the in-flight Back arrows on clone/remote/create are not
@@ -328,6 +341,8 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
           // on the Setup step are funnel-equivalent to Skip.
           if (step === 'setup') {
             track('add_repo_setup_step_action', { action: 'skip' })
+            void finishImportedRepoWithoutOpening()
+            return
           }
           closeModal()
           resetState()
diff --git a/src/renderer/src/components/sidebar/add-repo-skip-finalization.test.ts b/src/renderer/src/components/sidebar/add-repo-skip-finalization.test.ts
new file mode 100644
index 00000000000..5654f6417ca
--- /dev/null
+++ b/src/renderer/src/components/sidebar/add-repo-skip-finalization.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { Worktree } from '../../../../shared/types'
+import {
+  finalizeImportedRepoAfterSkip,
+  type AddRepoSkipFinalizationState
+} from './add-repo-skip-finalization'
+
+function makeWorktree(overrides: Partial<Worktree> & { id: string; repoId: string }): Worktree {
+  return {
+    path: `/tmp/${overrides.id}`,
+    head: 'abc123',
+    branch: 'refs/heads/feature',
+    isBare: false,
+    isMainWorktree: false,
+    displayName: overrides.id,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    linkedGitLabMR: null,
+    linkedGitLabIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0,
+    ...overrides
+  }
+}
+
+function makeState(overrides: Partial<AddRepoSkipFinalizationState>): AddRepoSkipFinalizationState {
+  return {
+    activeRepoId: null,
+    filterRepoIds: [],
+    showActiveOnly: false,
+    hideDefaultBranchWorkspace: false,
+    worktreesByRepo: {},
+    setActiveRepo: vi.fn(),
+    setFilterRepoIds: vi.fn(),
+    setShowActiveOnly: vi.fn(),
+    setHideDefaultBranchWorkspace: vi.fn(),
+    ...overrides
+  }
+}
+
+describe('finalizeImportedRepoAfterSkip', () => {
+  it('keeps skipped imported worktrees visible without activating a worktree', () => {
+    const state = makeState({
+      activeRepoId: 'repo-old',
+      filterRepoIds: ['repo-old'],
+      showActiveOnly: true,
+      hideDefaultBranchWorkspace: false,
+      worktreesByRepo: {
+        'repo-new': [makeWorktree({ id: 'repo-new::/repo/feature', repoId: 'repo-new' })]
+      }
+    })
+
+    finalizeImportedRepoAfterSkip(state, 'repo-new')
+
+    expect(state.setActiveRepo).toHaveBeenCalledWith('repo-new')
+    expect(state.setFilterRepoIds).toHaveBeenCalledWith([])
+    expect(state.setShowActiveOnly).toHaveBeenCalledWith(false)
+    expect(state.setHideDefaultBranchWorkspace).not.toHaveBeenCalled()
+  })
+
+  it('clears default-branch hiding when it would hide every imported worktree', () => {
+    const state = makeState({
+      hideDefaultBranchWorkspace: true,
+      worktreesByRepo: {
+        'repo-new': [
+          makeWorktree({
+            id: 'repo-new::/repo/main',
+            repoId: 'repo-new',
+            isMainWorktree: true,
+            branch: 'refs/heads/main'
+          })
+        ]
+      }
+    })
+
+    finalizeImportedRepoAfterSkip(state, 'repo-new')
+
+    expect(state.setHideDefaultBranchWorkspace).toHaveBeenCalledWith(false)
+  })
+
+  it('does nothing when the imported repo has no discovered worktrees yet', () => {
+    const state = makeState({
+      activeRepoId: 'repo-old',
+      filterRepoIds: ['repo-old'],
+      showActiveOnly: true,
+      hideDefaultBranchWorkspace: true,
+      worktreesByRepo: { 'repo-new': [] }
+    })
+
+    finalizeImportedRepoAfterSkip(state, 'repo-new')
+
+    expect(state.setActiveRepo).not.toHaveBeenCalled()
+    expect(state.setFilterRepoIds).not.toHaveBeenCalled()
+    expect(state.setShowActiveOnly).not.toHaveBeenCalled()
+    expect(state.setHideDefaultBranchWorkspace).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/sidebar/add-repo-skip-finalization.ts b/src/renderer/src/components/sidebar/add-repo-skip-finalization.ts
new file mode 100644
index 00000000000..4185c3e6fbe
--- /dev/null
+++ b/src/renderer/src/components/sidebar/add-repo-skip-finalization.ts
@@ -0,0 +1,42 @@
+import type { Worktree } from '../../../../shared/types'
+import { isDefaultBranchWorkspace } from './visible-worktrees'
+
+export type AddRepoSkipFinalizationState = {
+  activeRepoId: string | null
+  filterRepoIds: string[]
+  showActiveOnly: boolean
+  hideDefaultBranchWorkspace: boolean
+  worktreesByRepo: Record<string, Worktree[]>
+  setActiveRepo: (repoId: string | null) => void
+  setFilterRepoIds: (repoIds: string[]) => void
+  setShowActiveOnly: (value: boolean) => void
+  setHideDefaultBranchWorkspace: (value: boolean) => void
+}
+
+export function finalizeImportedRepoAfterSkip(
+  state: AddRepoSkipFinalizationState,
+  importedRepoId: string
+): void {
+  const importedWorktrees = state.worktreesByRepo[importedRepoId] ?? []
+  if (importedWorktrees.length === 0) {
+    return
+  }
+
+  // Why: Skip means "do not open or create a worktree", not "hide the
+  // imported project behind sidebar filters so it looks like nothing landed."
+  if (state.activeRepoId !== importedRepoId) {
+    state.setActiveRepo(importedRepoId)
+  }
+  if (state.filterRepoIds.length > 0 && !state.filterRepoIds.includes(importedRepoId)) {
+    state.setFilterRepoIds([])
+  }
+  if (state.showActiveOnly) {
+    state.setShowActiveOnly(false)
+  }
+  if (
+    state.hideDefaultBranchWorkspace &&
+    importedWorktrees.every((worktree) => isDefaultBranchWorkspace(worktree))
+  ) {
+    state.setHideDefaultBranchWorkspace(false)
+  }
+}

From f81b3f219f15422f88dd5e9b37f2251ad15fb553 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 01:56:05 -0700
Subject: [PATCH 30/82] Add Gitea hosted review support

---
 src/main/gitea/client.test.ts                 | 159 +++++++++++
 src/main/gitea/client.ts                      | 253 ++++++++++++++++++
 src/main/gitea/pull-request-mappers.test.ts   |  76 ++++++
 src/main/gitea/pull-request-mappers.ts        | 129 +++++++++
 src/main/gitea/repository-ref.test.ts         |  86 ++++++
 src/main/gitea/repository-ref.ts              | 131 +++++++++
 src/main/ipc/hosted-review.ts                 |   3 +-
 src/main/ipc/preflight.test.ts                |  40 ++-
 src/main/ipc/preflight.ts                     |  16 +-
 src/main/runtime/orca-runtime.ts              |   4 +-
 .../runtime/rpc/methods/hosted-review.test.ts |   3 +-
 src/main/runtime/rpc/methods/hosted-review.ts |   6 +-
 .../hosted-review-gitea.integration.test.ts   | 113 ++++++++
 src/main/source-control/hosted-review.test.ts |  56 +++-
 src/main/source-control/hosted-review.ts      |  40 ++-
 src/preload/api-types.ts                      |   7 +
 src/preload/index.ts                          |   7 +
 .../components/settings/IntegrationsPane.tsx  | 129 ++++++++-
 .../components/sidebar/WorktreeCardMeta.tsx   |   3 +
 .../src/store/slices/hosted-review.test.ts    |   6 +-
 .../src/store/slices/hosted-review.ts         |   7 +-
 src/shared/hosted-review.ts                   |   3 +-
 22 files changed, 1247 insertions(+), 30 deletions(-)
 create mode 100644 src/main/gitea/client.test.ts
 create mode 100644 src/main/gitea/client.ts
 create mode 100644 src/main/gitea/pull-request-mappers.test.ts
 create mode 100644 src/main/gitea/pull-request-mappers.ts
 create mode 100644 src/main/gitea/repository-ref.test.ts
 create mode 100644 src/main/gitea/repository-ref.ts
 create mode 100644 src/main/source-control/hosted-review-gitea.integration.test.ts

diff --git a/src/main/gitea/client.test.ts b/src/main/gitea/client.test.ts
new file mode 100644
index 00000000000..620ab33225f
--- /dev/null
+++ b/src/main/gitea/client.test.ts
@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { gitExecFileAsyncMock } = vi.hoisted(() => ({
+  gitExecFileAsyncMock: vi.fn()
+}))
+
+vi.mock('../git/runner', () => ({
+  gitExecFileAsync: gitExecFileAsyncMock
+}))
+
+import {
+  getGiteaAuthStatus,
+  getGiteaPullRequestForBranch,
+  normalizeGiteaApiBaseUrl
+} from './client'
+import { _resetGiteaRepoRefCache } from './repository-ref'
+
+const OLD_ENV = process.env
+
+function giteaPr(index = 7, branch = 'feature/gitea') {
+  return {
+    number: index,
+    title: 'Add Gitea',
+    state: 'open',
+    html_url: `https://git.example.com/team/repo/pulls/${index}`,
+    updated_at: '2026-05-15T00:00:00Z',
+    mergeable: true,
+    head: {
+      ref: branch,
+      label: `team:${branch}`,
+      sha: 'abc123'
+    }
+  }
+}
+
+describe('Gitea client', () => {
+  beforeEach(() => {
+    process.env = { ...OLD_ENV }
+    process.env.ORCA_GITEA_TOKEN = 'gitea-token'
+    delete process.env.ORCA_GITEA_API_BASE_URL
+    gitExecFileAsyncMock.mockReset()
+    gitExecFileAsyncMock.mockResolvedValue({
+      stdout: 'https://git.example.com/team/repo.git\n',
+      stderr: ''
+    })
+    _resetGiteaRepoRefCache()
+    vi.unstubAllGlobals()
+  })
+
+  it('normalizes Gitea API base URLs', () => {
+    expect(normalizeGiteaApiBaseUrl('https://git.example.com')).toBe(
+      'https://git.example.com/api/v1'
+    )
+    expect(normalizeGiteaApiBaseUrl('https://git.example.com/api/v1/')).toBe(
+      'https://git.example.com/api/v1'
+    )
+  })
+
+  it('fetches a branch pull request and commit status', async () => {
+    const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
+      const parsed = new URL(url)
+      if (!init) {
+        throw new Error('expected request init')
+      }
+      expect((init.headers as Record<string, string>).Authorization).toBe('token gitea-token')
+      if (parsed.pathname.endsWith('/commits/abc123/status')) {
+        return Response.json({ state: 'success' })
+      }
+      return Response.json([giteaPr()])
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(
+      getGiteaPullRequestForBranch('/repo', 'refs/heads/feature/gitea')
+    ).resolves.toEqual({
+      number: 7,
+      title: 'Add Gitea',
+      state: 'open',
+      url: 'https://git.example.com/team/repo/pulls/7',
+      status: 'success',
+      updatedAt: '2026-05-15T00:00:00Z',
+      mergeable: 'MERGEABLE',
+      headSha: 'abc123'
+    })
+
+    const listUrl = new URL(String(fetchMock.mock.calls[0]?.[0]))
+    expect(listUrl.origin).toBe('https://git.example.com')
+    expect(listUrl.pathname).toBe('/api/v1/repos/team/repo/pulls')
+    expect(listUrl.searchParams.get('state')).toBe('all')
+    expect(listUrl.searchParams.get('sort')).toBe('recentupdate')
+    expect(listUrl.searchParams.get('page')).toBe('1')
+    expect(listUrl.searchParams.get('limit')).toBe('50')
+  })
+
+  it('uses an API base URL override for subpath or non-standard deployments', async () => {
+    process.env.ORCA_GITEA_API_BASE_URL = 'https://git.example.com/code'
+    const fetchMock = vi.fn(async (url: string | URL) => {
+      if (String(url).includes('/commits/abc123/status')) {
+        return Response.json({ state: 'pending' })
+      }
+      return Response.json([giteaPr()])
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(getGiteaPullRequestForBranch('/repo', 'feature/gitea')).resolves.toMatchObject({
+      number: 7,
+      status: 'pending'
+    })
+    expect(String(fetchMock.mock.calls[0]?.[0])).toContain(
+      'https://git.example.com/code/api/v1/repos/team/repo/pulls'
+    )
+  })
+
+  it('falls back to a linked PR number when branch lookup misses', async () => {
+    const fetchMock = vi.fn(async (url: string | URL) => {
+      const requestUrl = String(url)
+      if (requestUrl.includes('/commits/abc123/status')) {
+        return Response.json({ state: 'success' })
+      }
+      if (requestUrl.endsWith('/pulls/42')) {
+        return Response.json(giteaPr(42, 'renamed-local-branch'))
+      }
+      return Response.json([])
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(getGiteaPullRequestForBranch('/repo', 'local-name', 42)).resolves.toMatchObject({
+      number: 42,
+      status: 'success'
+    })
+  })
+
+  it('reports configured token auth without a global API base URL', async () => {
+    await expect(getGiteaAuthStatus()).resolves.toEqual({
+      configured: true,
+      authenticated: true,
+      account: null,
+      baseUrl: null,
+      tokenConfigured: true
+    })
+  })
+
+  it('verifies token auth when a global API base URL is configured', async () => {
+    process.env.ORCA_GITEA_API_BASE_URL = 'https://git.example.com'
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) =>
+      Response.json({ login: 'gitea-user' })
+    )
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(getGiteaAuthStatus()).resolves.toEqual({
+      configured: true,
+      authenticated: true,
+      account: 'gitea-user',
+      baseUrl: 'https://git.example.com/api/v1',
+      tokenConfigured: true
+    })
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('https://git.example.com/api/v1/user')
+  })
+})
diff --git a/src/main/gitea/client.ts b/src/main/gitea/client.ts
new file mode 100644
index 00000000000..c86dd89a9a4
--- /dev/null
+++ b/src/main/gitea/client.ts
@@ -0,0 +1,253 @@
+import {
+  deriveGiteaCommitStatus,
+  mapGiteaPullRequest,
+  type GiteaPullRequestInfo,
+  type RawGiteaCombinedStatus,
+  type RawGiteaPullRequest
+} from './pull-request-mappers'
+import { getGiteaRepoRef, type GiteaRepoRef } from './repository-ref'
+
+const REQUEST_TIMEOUT_MS = 5000
+const PULL_REQUEST_PAGE_LIMIT = 50
+const MAX_PULL_REQUEST_PAGES = 5
+
+type GiteaAuthConfig = {
+  apiBaseUrl: string | null
+  token: string | null
+}
+
+export type GiteaAuthStatus = {
+  configured: boolean
+  authenticated: boolean
+  account: string | null
+  baseUrl: string | null
+  tokenConfigured: boolean
+}
+
+type RequestOptions = {
+  searchParams?: Record<string, string | number>
+  timeoutMs?: number
+}
+
+function envValue(name: string): string | null {
+  const value = process.env[name]?.trim() ?? ''
+  return value.length > 0 ? value : null
+}
+
+export function normalizeGiteaApiBaseUrl(value: string): string {
+  const trimmed = value.trim().replace(/\/+$/, '')
+  return /\/api\/v1$/i.test(trimmed) ? trimmed : `${trimmed}/api/v1`
+}
+
+function getAuthConfig(): GiteaAuthConfig {
+  const apiBaseUrl = envValue('ORCA_GITEA_API_BASE_URL')
+  return {
+    apiBaseUrl: apiBaseUrl ? normalizeGiteaApiBaseUrl(apiBaseUrl) : null,
+    token: envValue('ORCA_GITEA_TOKEN')
+  }
+}
+
+function authHeaders(config: Pick<GiteaAuthConfig, 'token'>): Record<string, string> {
+  return config.token ? { Authorization: `token ${config.token}` } : {}
+}
+
+function configuredApiBaseUrl(repo: GiteaRepoRef): string {
+  return getAuthConfig().apiBaseUrl ?? repo.apiBaseUrl
+}
+
+function apiUrl(baseUrl: string, path: string, searchParams?: RequestOptions['searchParams']): URL {
+  const url = new URL(`${baseUrl.replace(/\/+$/, '')}${path}`)
+  if (searchParams) {
+    for (const [key, value] of Object.entries(searchParams)) {
+      url.searchParams.set(key, String(value))
+    }
+  }
+  return url
+}
+
+async function requestJsonAtBase<T>(
+  baseUrl: string,
+  path: string,
+  options: RequestOptions = {}
+): Promise<T | null> {
+  const config = getAuthConfig()
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? REQUEST_TIMEOUT_MS)
+  try {
+    const response = await fetch(apiUrl(baseUrl, path, options.searchParams), {
+      headers: {
+        Accept: 'application/json',
+        ...authHeaders(config)
+      },
+      signal: controller.signal
+    })
+    if (!response.ok) {
+      return null
+    }
+    return (await response.json()) as T
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+function requestJson<T>(
+  repo: GiteaRepoRef,
+  path: string,
+  options: RequestOptions = {}
+): Promise<T | null> {
+  return requestJsonAtBase(configuredApiBaseUrl(repo), path, options)
+}
+
+function encodedRepoPath(repo: GiteaRepoRef): string {
+  return `${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.repo)}`
+}
+
+async function getCommitStatus(
+  repo: GiteaRepoRef,
+  headSha: string | undefined
+): Promise<ReturnType<typeof deriveGiteaCommitStatus>> {
+  if (!headSha) {
+    return 'neutral'
+  }
+  const data = await requestJson<RawGiteaCombinedStatus>(
+    repo,
+    `/repos/${encodedRepoPath(repo)}/commits/${encodeURIComponent(headSha)}/status`
+  )
+  return deriveGiteaCommitStatus(data)
+}
+
+async function normalizePullRequest(
+  repo: GiteaRepoRef,
+  raw: RawGiteaPullRequest
+): Promise<GiteaPullRequestInfo | null> {
+  const status = await getCommitStatus(repo, raw.head?.sha?.trim())
+  return mapGiteaPullRequest(raw, status)
+}
+
+function matchesBranch(raw: RawGiteaPullRequest, branchName: string): boolean {
+  const ref = raw.head?.ref?.trim()
+  if (ref === branchName) {
+    return true
+  }
+  const label = raw.head?.label?.trim()
+  return label === branchName || label?.endsWith(`:${branchName}`) === true
+}
+
+export async function getGiteaAuthStatus(): Promise<GiteaAuthStatus> {
+  const config = getAuthConfig()
+  const tokenConfigured = config.token !== null
+  if (!config.apiBaseUrl && !tokenConfigured) {
+    return {
+      configured: false,
+      authenticated: false,
+      account: null,
+      baseUrl: null,
+      tokenConfigured: false
+    }
+  }
+  if (!config.apiBaseUrl) {
+    return {
+      configured: true,
+      authenticated: true,
+      account: null,
+      baseUrl: null,
+      tokenConfigured
+    }
+  }
+
+  if (!tokenConfigured) {
+    const version = await requestJsonAtBase<{ version?: string }>(config.apiBaseUrl, '/version', {
+      timeoutMs: 4000
+    })
+    return {
+      configured: version !== null,
+      authenticated: false,
+      account: null,
+      baseUrl: config.apiBaseUrl,
+      tokenConfigured
+    }
+  }
+
+  const user = await requestJsonAtBase<{
+    login?: string | null
+    username?: string | null
+    full_name?: string | null
+  }>(config.apiBaseUrl, '/user', { timeoutMs: 4000 })
+  return {
+    configured: true,
+    authenticated: user !== null,
+    account: user?.login ?? user?.username ?? user?.full_name ?? null,
+    baseUrl: config.apiBaseUrl,
+    tokenConfigured
+  }
+}
+
+export async function getGiteaPullRequest(
+  repoPath: string,
+  prNumber: number
+): Promise<GiteaPullRequestInfo | null> {
+  const repo = await getGiteaRepoRef(repoPath)
+  if (!repo) {
+    return null
+  }
+  const raw = await requestJson<RawGiteaPullRequest>(
+    repo,
+    `/repos/${encodedRepoPath(repo)}/pulls/${encodeURIComponent(String(prNumber))}`
+  )
+  return raw ? normalizePullRequest(repo, raw) : null
+}
+
+export async function getGiteaPullRequestForBranch(
+  repoPath: string,
+  branch: string,
+  linkedPRNumber?: number | null
+): Promise<GiteaPullRequestInfo | null> {
+  const branchName = branch.replace(/^refs\/heads\//, '')
+  if (!branchName && linkedPRNumber == null) {
+    return null
+  }
+
+  const repo = await getGiteaRepoRef(repoPath)
+  if (!repo) {
+    return null
+  }
+
+  if (branchName) {
+    for (let page = 1; page <= MAX_PULL_REQUEST_PAGES; page++) {
+      const list = await requestJson<RawGiteaPullRequest[]>(
+        repo,
+        `/repos/${encodedRepoPath(repo)}/pulls`,
+        {
+          searchParams: {
+            state: 'all',
+            sort: 'recentupdate',
+            page,
+            limit: PULL_REQUEST_PAGE_LIMIT
+          }
+        }
+      )
+      const raw = list?.find((item) => matchesBranch(item, branchName))
+      if (raw) {
+        return normalizePullRequest(repo, raw)
+      }
+      if (!list || list.length < PULL_REQUEST_PAGE_LIMIT) {
+        break
+      }
+    }
+  }
+
+  if (typeof linkedPRNumber !== 'number') {
+    return null
+  }
+  const raw = await requestJson<RawGiteaPullRequest>(
+    repo,
+    `/repos/${encodedRepoPath(repo)}/pulls/${encodeURIComponent(String(linkedPRNumber))}`
+  )
+  return raw ? normalizePullRequest(repo, raw) : null
+}
+
+export async function getGiteaRepoSlug(repoPath: string): Promise<GiteaRepoRef | null> {
+  return getGiteaRepoRef(repoPath)
+}
diff --git a/src/main/gitea/pull-request-mappers.test.ts b/src/main/gitea/pull-request-mappers.test.ts
new file mode 100644
index 00000000000..3b71a93ffdd
--- /dev/null
+++ b/src/main/gitea/pull-request-mappers.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import {
+  deriveGiteaCommitStatus,
+  mapGiteaMergeable,
+  mapGiteaPullRequest,
+  mapGiteaPullRequestState
+} from './pull-request-mappers'
+
+describe('Gitea pull request mappers', () => {
+  it('maps pull request states', () => {
+    expect(mapGiteaPullRequestState({ state: 'open' })).toBe('open')
+    expect(mapGiteaPullRequestState({ state: 'closed' })).toBe('closed')
+    expect(mapGiteaPullRequestState({ state: 'open', draft: true })).toBe('draft')
+    expect(mapGiteaPullRequestState({ state: 'closed', merged: true })).toBe('merged')
+  })
+
+  it('maps mergeability', () => {
+    expect(mapGiteaMergeable(true)).toBe('MERGEABLE')
+    expect(mapGiteaMergeable(false)).toBe('CONFLICTING')
+    expect(mapGiteaMergeable(undefined)).toBe('UNKNOWN')
+  })
+
+  it('derives commit status from the combined state', () => {
+    expect(deriveGiteaCommitStatus({ state: 'success' })).toBe('success')
+    expect(deriveGiteaCommitStatus({ state: 'failure' })).toBe('failure')
+    expect(deriveGiteaCommitStatus({ state: 'error' })).toBe('failure')
+    expect(deriveGiteaCommitStatus({ state: 'pending' })).toBe('pending')
+    expect(deriveGiteaCommitStatus({ state: 'skipped' })).toBe('neutral')
+  })
+
+  it('rolls up individual statuses when the combined state is neutral', () => {
+    expect(
+      deriveGiteaCommitStatus({
+        state: '',
+        statuses: [{ status: 'success' }, { status: 'failure' }]
+      })
+    ).toBe('failure')
+    expect(
+      deriveGiteaCommitStatus({
+        statuses: [{ status: 'success' }, { status: 'pending' }]
+      })
+    ).toBe('pending')
+    expect(deriveGiteaCommitStatus({ statuses: [{ status: 'success' }] })).toBe('success')
+    expect(deriveGiteaCommitStatus({ statuses: [] })).toBe('neutral')
+  })
+
+  it('maps a raw pull request to the hosted review shape', () => {
+    expect(
+      mapGiteaPullRequest(
+        {
+          number: 12,
+          title: 'Gitea branch',
+          state: 'open',
+          html_url: 'https://git.example.com/team/project/pulls/12',
+          updated_at: '2026-05-15T00:00:00Z',
+          mergeable: true,
+          head: { sha: 'abc123' }
+        },
+        'success'
+      )
+    ).toEqual({
+      number: 12,
+      title: 'Gitea branch',
+      state: 'open',
+      url: 'https://git.example.com/team/project/pulls/12',
+      status: 'success',
+      updatedAt: '2026-05-15T00:00:00Z',
+      mergeable: 'MERGEABLE',
+      headSha: 'abc123'
+    })
+  })
+
+  it('rejects incomplete pull request payloads', () => {
+    expect(mapGiteaPullRequest({ number: 1, title: 'missing url' }, 'neutral')).toBeNull()
+  })
+})
diff --git a/src/main/gitea/pull-request-mappers.ts b/src/main/gitea/pull-request-mappers.ts
new file mode 100644
index 00000000000..090e38bd39d
--- /dev/null
+++ b/src/main/gitea/pull-request-mappers.ts
@@ -0,0 +1,129 @@
+import type { CheckStatus, PRMergeableState } from '../../shared/types'
+
+export type RawGiteaPullRequest = {
+  number?: number
+  title?: string
+  state?: string | null
+  html_url?: string | null
+  updated_at?: string | null
+  merged?: boolean | null
+  draft?: boolean | null
+  mergeable?: boolean | null
+  head?: {
+    ref?: string | null
+    label?: string | null
+    sha?: string | null
+  } | null
+}
+
+export type GiteaPullRequestInfo = {
+  number: number
+  title: string
+  state: 'open' | 'closed' | 'merged' | 'draft'
+  url: string
+  status: CheckStatus
+  updatedAt: string
+  mergeable: PRMergeableState
+  headSha?: string
+}
+
+export type RawGiteaCombinedStatus = {
+  state?: string | null
+  statuses?: RawGiteaCommitStatus[] | null
+}
+
+export type RawGiteaCommitStatus = {
+  status?: string | null
+  state?: string | null
+}
+
+function classifyGiteaStatus(status: string | null | undefined): CheckStatus {
+  switch (status?.trim().toLowerCase()) {
+    case 'success':
+      return 'success'
+    case 'failure':
+    case 'error':
+    case 'warning':
+      return 'failure'
+    case 'pending':
+      return 'pending'
+    case 'skipped':
+    default:
+      return 'neutral'
+  }
+}
+
+export function deriveGiteaCommitStatus(rollup: RawGiteaCombinedStatus | null): CheckStatus {
+  if (!rollup) {
+    return 'neutral'
+  }
+  const combined = classifyGiteaStatus(rollup.state)
+  if (combined !== 'neutral') {
+    return combined
+  }
+  const statuses = rollup.statuses ?? []
+  if (statuses.length === 0) {
+    return 'neutral'
+  }
+
+  let hasPending = false
+  for (const status of statuses) {
+    const classified = classifyGiteaStatus(status.status ?? status.state)
+    if (classified === 'failure') {
+      return 'failure'
+    }
+    if (classified === 'pending') {
+      hasPending = true
+    }
+  }
+  if (hasPending) {
+    return 'pending'
+  }
+  return statuses.every(
+    (status) => classifyGiteaStatus(status.status ?? status.state) === 'success'
+  )
+    ? 'success'
+    : 'neutral'
+}
+
+export function mapGiteaPullRequestState(
+  raw: Pick<RawGiteaPullRequest, 'draft' | 'merged' | 'state'>
+): GiteaPullRequestInfo['state'] {
+  if (raw.merged) {
+    return 'merged'
+  }
+  if (raw.draft) {
+    return 'draft'
+  }
+  return raw.state?.trim().toLowerCase() === 'closed' ? 'closed' : 'open'
+}
+
+export function mapGiteaMergeable(value: boolean | null | undefined): PRMergeableState {
+  if (value === true) {
+    return 'MERGEABLE'
+  }
+  if (value === false) {
+    return 'CONFLICTING'
+  }
+  return 'UNKNOWN'
+}
+
+export function mapGiteaPullRequest(
+  raw: RawGiteaPullRequest,
+  status: CheckStatus
+): GiteaPullRequestInfo | null {
+  if (typeof raw.number !== 'number' || !raw.title || !raw.html_url) {
+    return null
+  }
+  const headSha = raw.head?.sha?.trim()
+  return {
+    number: raw.number,
+    title: raw.title,
+    state: mapGiteaPullRequestState(raw),
+    url: raw.html_url,
+    status,
+    updatedAt: raw.updated_at ?? '',
+    mergeable: mapGiteaMergeable(raw.mergeable),
+    ...(headSha ? { headSha } : {})
+  }
+}
diff --git a/src/main/gitea/repository-ref.test.ts b/src/main/gitea/repository-ref.test.ts
new file mode 100644
index 00000000000..4ff86d8b7ae
--- /dev/null
+++ b/src/main/gitea/repository-ref.test.ts
@@ -0,0 +1,86 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { gitExecFileAsyncMock } = vi.hoisted(() => ({
+  gitExecFileAsyncMock: vi.fn()
+}))
+
+vi.mock('../git/runner', () => ({
+  gitExecFileAsync: gitExecFileAsyncMock
+}))
+
+import { _resetGiteaRepoRefCache, getGiteaRepoRef, parseGiteaRepoRef } from './repository-ref'
+
+describe('Gitea repository ref parsing', () => {
+  beforeEach(() => {
+    gitExecFileAsyncMock.mockReset()
+    _resetGiteaRepoRefCache()
+  })
+
+  it('parses HTTPS remotes and derives the API base URL', () => {
+    expect(parseGiteaRepoRef('https://git.example.com/team/project.git')).toEqual({
+      host: 'git.example.com',
+      owner: 'team',
+      repo: 'project',
+      apiBaseUrl: 'https://git.example.com/api/v1',
+      webBaseUrl: 'https://git.example.com'
+    })
+  })
+
+  it('preserves an HTTP subpath when deriving the API base URL', () => {
+    expect(parseGiteaRepoRef('https://git.example.com/code/team/project.git')).toEqual({
+      host: 'git.example.com',
+      owner: 'team',
+      repo: 'project',
+      apiBaseUrl: 'https://git.example.com/code/api/v1',
+      webBaseUrl: 'https://git.example.com/code'
+    })
+  })
+
+  it('parses scp-like SSH remotes with an HTTPS web/API base', () => {
+    expect(parseGiteaRepoRef('git@gitea.example.test:team/project.git')).toEqual({
+      host: 'gitea.example.test',
+      owner: 'team',
+      repo: 'project',
+      apiBaseUrl: 'https://gitea.example.test/api/v1',
+      webBaseUrl: 'https://gitea.example.test'
+    })
+  })
+
+  it('parses ssh:// remotes without carrying the SSH port into web/API URLs', () => {
+    expect(parseGiteaRepoRef('ssh://git@gitea.example.test:2222/team/project.git')).toEqual({
+      host: 'gitea.example.test',
+      owner: 'team',
+      repo: 'project',
+      apiBaseUrl: 'https://gitea.example.test/api/v1',
+      webBaseUrl: 'https://gitea.example.test'
+    })
+  })
+
+  it('does not claim public hosts handled by more specific providers', () => {
+    expect(parseGiteaRepoRef('git@github.com:team/project.git')).toBeNull()
+    expect(parseGiteaRepoRef('https://gitlab.com/team/project.git')).toBeNull()
+    expect(parseGiteaRepoRef('https://bitbucket.org/team/project.git')).toBeNull()
+  })
+
+  it('reads and caches the origin remote', async () => {
+    gitExecFileAsyncMock.mockResolvedValueOnce({
+      stdout: 'https://git.example.com/team/project.git\n',
+      stderr: ''
+    })
+
+    await expect(getGiteaRepoRef('/repo')).resolves.toMatchObject({
+      host: 'git.example.com',
+      owner: 'team',
+      repo: 'project'
+    })
+    await expect(getGiteaRepoRef('/repo')).resolves.toMatchObject({
+      host: 'git.example.com',
+      owner: 'team',
+      repo: 'project'
+    })
+    expect(gitExecFileAsyncMock).toHaveBeenCalledTimes(1)
+    expect(gitExecFileAsyncMock).toHaveBeenCalledWith(['remote', 'get-url', 'origin'], {
+      cwd: '/repo'
+    })
+  })
+})
diff --git a/src/main/gitea/repository-ref.ts b/src/main/gitea/repository-ref.ts
new file mode 100644
index 00000000000..d6bc6b2cce4
--- /dev/null
+++ b/src/main/gitea/repository-ref.ts
@@ -0,0 +1,131 @@
+import { gitExecFileAsync } from '../git/runner'
+
+export type GiteaRepoRef = {
+  host: string
+  owner: string
+  repo: string
+  apiBaseUrl: string
+  webBaseUrl: string
+}
+
+const KNOWN_NON_GITEA_HOSTS = new Set(['github.com', 'gitlab.com', 'bitbucket.org'])
+const repoRefCache = new Map<string, GiteaRepoRef | null>()
+
+/** @internal - exposed for tests only */
+export function _resetGiteaRepoRefCache(): void {
+  repoRefCache.clear()
+}
+
+function decodeSegment(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+function parsePath(pathname: string): { owner: string; repo: string; basePath: string } | null {
+  const withoutSuffix = pathname.replace(/\.git$/i, '')
+  const parts = withoutSuffix
+    .split('/')
+    .map((part) => part.trim())
+    .filter(Boolean)
+  if (parts.length < 2) {
+    return null
+  }
+
+  const owner = decodeSegment(parts.at(-2) ?? '')
+  const repo = decodeSegment(parts.at(-1) ?? '')
+  if (!owner || !repo) {
+    return null
+  }
+
+  return {
+    owner,
+    repo,
+    basePath: parts.slice(0, -2).join('/')
+  }
+}
+
+function apiBaseUrlFromWebBase(webBaseUrl: string): string {
+  return `${webBaseUrl.replace(/\/+$/, '')}/api/v1`
+}
+
+function makeRepoRef(host: string, path: string, webBaseUrl: string): GiteaRepoRef | null {
+  const normalizedHost = host.toLowerCase()
+  if (!normalizedHost || KNOWN_NON_GITEA_HOSTS.has(normalizedHost)) {
+    return null
+  }
+
+  const parsed = parsePath(path)
+  if (!parsed) {
+    return null
+  }
+
+  return {
+    host: normalizedHost,
+    owner: parsed.owner,
+    repo: parsed.repo,
+    apiBaseUrl: apiBaseUrlFromWebBase(webBaseUrl),
+    webBaseUrl
+  }
+}
+
+export function parseGiteaRepoRef(remoteUrl: string): GiteaRepoRef | null {
+  const trimmed = remoteUrl.trim()
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    const scpLike = trimmed.match(/^(?:[^@/:]+@)?([^:\s/]+):([^\s]+?)(?:\.git)?$/)
+    if (scpLike) {
+      const host = scpLike[1]
+      const path = scpLike[2]
+      return makeRepoRef(host, path, `https://${host.toLowerCase()}`)
+    }
+  }
+
+  try {
+    const url = new URL(trimmed)
+    const protocol = url.protocol.toLowerCase()
+    if (!['http:', 'https:', 'ssh:', 'git+ssh:'].includes(protocol)) {
+      return null
+    }
+
+    const parsed = parsePath(url.pathname)
+    if (!parsed) {
+      return null
+    }
+
+    const webOrigin =
+      protocol === 'http:' || protocol === 'https:'
+        ? `${protocol}//${url.host}`
+        : `https://${url.hostname.toLowerCase()}`
+    const webBaseUrl = parsed.basePath ? `${webOrigin}/${parsed.basePath}` : webOrigin
+    return makeRepoRef(url.hostname, url.pathname, webBaseUrl)
+  } catch {
+    return null
+  }
+}
+
+export async function getGiteaRepoRefForRemote(
+  repoPath: string,
+  remoteName: string
+): Promise<GiteaRepoRef | null> {
+  const cacheKey = `${repoPath}\0${remoteName}`
+  if (repoRefCache.has(cacheKey)) {
+    return repoRefCache.get(cacheKey)!
+  }
+  try {
+    const { stdout } = await gitExecFileAsync(['remote', 'get-url', remoteName], {
+      cwd: repoPath
+    })
+    const result = parseGiteaRepoRef(stdout)
+    repoRefCache.set(cacheKey, result)
+    return result
+  } catch {
+    repoRefCache.set(cacheKey, null)
+    return null
+  }
+}
+
+export async function getGiteaRepoRef(repoPath: string): Promise<GiteaRepoRef | null> {
+  return getGiteaRepoRefForRemote(repoPath, 'origin')
+}
diff --git a/src/main/ipc/hosted-review.ts b/src/main/ipc/hosted-review.ts
index edd2fa2a5c8..acd89711356 100644
--- a/src/main/ipc/hosted-review.ts
+++ b/src/main/ipc/hosted-review.ts
@@ -23,7 +23,8 @@ export function registerHostedReviewHandlers(store: Store, stats: StatsCollector
       branch: args.branch,
       linkedGitHubPR: args.linkedGitHubPR ?? null,
       linkedGitLabMR: args.linkedGitLabMR ?? null,
-      linkedBitbucketPR: args.linkedBitbucketPR ?? null
+      linkedBitbucketPR: args.linkedBitbucketPR ?? null,
+      linkedGiteaPR: args.linkedGiteaPR ?? null
     })
     if (review?.provider === 'github' && !stats.hasCountedPR(review.url)) {
       stats.record({
diff --git a/src/main/ipc/preflight.test.ts b/src/main/ipc/preflight.test.ts
index d2d3327322f..fefc0d0ad3d 100644
--- a/src/main/ipc/preflight.test.ts
+++ b/src/main/ipc/preflight.test.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: preflight tests share expensive process/preload mocks across
+   install, auth, agent detection, and refresh branches. */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const {
@@ -6,14 +8,16 @@ const {
   execFileAsyncMock,
   hydrateShellPathMock,
   mergePathSegmentsMock,
-  getBitbucketAuthStatusMock
+  getBitbucketAuthStatusMock,
+  getGiteaAuthStatusMock
 } = vi.hoisted(() => ({
   handleMock: vi.fn(),
   execFileMock: vi.fn(),
   execFileAsyncMock: vi.fn(),
   hydrateShellPathMock: vi.fn(),
   mergePathSegmentsMock: vi.fn(),
-  getBitbucketAuthStatusMock: vi.fn()
+  getBitbucketAuthStatusMock: vi.fn(),
+  getGiteaAuthStatusMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -41,6 +45,10 @@ vi.mock('../bitbucket/client', () => ({
   getBitbucketAuthStatus: getBitbucketAuthStatusMock
 }))
 
+vi.mock('../gitea/client', () => ({
+  getGiteaAuthStatus: getGiteaAuthStatusMock
+}))
+
 import {
   _resetPreflightCache,
   detectInstalledAgents,
@@ -52,6 +60,14 @@ type HandlerMap = Record<string, (_event?: unknown, args?: { force?: boolean })
 
 describe('preflight', () => {
   const handlers: HandlerMap = {}
+  const defaultBitbucketStatus = { configured: false, authenticated: false, account: null }
+  const defaultGiteaStatus = {
+    configured: false,
+    authenticated: false,
+    account: null,
+    baseUrl: null,
+    tokenConfigured: false
+  }
 
   beforeEach(() => {
     handleMock.mockReset()
@@ -59,11 +75,9 @@ describe('preflight', () => {
     hydrateShellPathMock.mockReset()
     mergePathSegmentsMock.mockReset()
     getBitbucketAuthStatusMock.mockReset()
-    getBitbucketAuthStatusMock.mockResolvedValue({
-      configured: false,
-      authenticated: false,
-      account: null
-    })
+    getGiteaAuthStatusMock.mockReset()
+    getBitbucketAuthStatusMock.mockResolvedValue(defaultBitbucketStatus)
+    getGiteaAuthStatusMock.mockResolvedValue(defaultGiteaStatus)
     _resetPreflightCache()
 
     for (const key of Object.keys(handlers)) {
@@ -92,7 +106,8 @@ describe('preflight', () => {
       git: { installed: true },
       gh: { installed: true, authenticated: true },
       glab: { installed: true, authenticated: true },
-      bitbucket: { configured: false, authenticated: false, account: null }
+      bitbucket: defaultBitbucketStatus,
+      gitea: defaultGiteaStatus
     })
     expect(execFileAsyncMock).toHaveBeenNthCalledWith(4, 'gh', ['auth', 'status'], {
       encoding: 'utf-8'
@@ -193,7 +208,8 @@ describe('preflight', () => {
       git: { installed: true },
       gh: { installed: true, authenticated: true },
       glab: { installed: true, authenticated: true },
-      bitbucket: { configured: false, authenticated: false, account: null }
+      bitbucket: defaultBitbucketStatus,
+      gitea: defaultGiteaStatus
     })
   })
 
@@ -219,13 +235,15 @@ describe('preflight', () => {
       git: { installed: true },
       gh: { installed: true, authenticated: false },
       glab: { installed: true, authenticated: true },
-      bitbucket: { configured: false, authenticated: false, account: null }
+      bitbucket: defaultBitbucketStatus,
+      gitea: defaultGiteaStatus
     })
     expect(refreshedStatus).toEqual({
       git: { installed: true },
       gh: { installed: true, authenticated: true },
       glab: { installed: true, authenticated: true },
-      bitbucket: { configured: false, authenticated: false, account: null }
+      bitbucket: defaultBitbucketStatus,
+      gitea: defaultGiteaStatus
     })
   })
 
diff --git a/src/main/ipc/preflight.ts b/src/main/ipc/preflight.ts
index 31022751e41..865c6d33414 100644
--- a/src/main/ipc/preflight.ts
+++ b/src/main/ipc/preflight.ts
@@ -6,6 +6,7 @@ import { TUI_AGENT_CONFIG } from '../../shared/tui-agent-config'
 import type { PathSource, ShellHydrationFailureReason } from '../../shared/types'
 import { hydrateShellPath, mergePathSegments } from '../startup/hydrate-shell-path'
 import { getBitbucketAuthStatus } from '../bitbucket/client'
+import { getGiteaAuthStatus } from '../gitea/client'
 import { getActiveMultiplexer } from './ssh'
 
 const execFileAsync = promisify(execFile)
@@ -19,6 +20,13 @@ export type PreflightStatus = {
   // gate on `glab?.authenticated`.
   glab?: { installed: boolean; authenticated: boolean }
   bitbucket?: { configured: boolean; authenticated: boolean; account: string | null }
+  gitea?: {
+    configured: boolean
+    authenticated: boolean
+    account: string | null
+    baseUrl: string | null
+    tokenConfigured: boolean
+  }
 }
 
 // Why: cache the result so repeated Landing mounts don't re-spawn processes.
@@ -150,17 +158,19 @@ export async function runPreflightCheck(force = false): Promise<PreflightStatus>
     isCommandAvailable('glab')
   ])
 
-  const [ghAuthenticated, glabAuthenticated, bitbucket] = await Promise.all([
+  const [ghAuthenticated, glabAuthenticated, bitbucket, gitea] = await Promise.all([
     ghInstalled ? isGhAuthenticated() : Promise.resolve(false),
     glabInstalled ? isGlabAuthenticated() : Promise.resolve(false),
-    getBitbucketAuthStatus()
+    getBitbucketAuthStatus(),
+    getGiteaAuthStatus()
   ])
 
   cached = {
     git: { installed: gitInstalled },
     gh: { installed: ghInstalled, authenticated: ghAuthenticated },
     glab: { installed: glabInstalled, authenticated: glabAuthenticated },
-    bitbucket
+    bitbucket,
+    gitea
   }
 
   return cached
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 3ee8b60e261..00767acf3c8 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -4453,6 +4453,7 @@ export class OrcaRuntimeService {
     linkedGitHubPR?: number | null
     linkedGitLabMR?: number | null
     linkedBitbucketPR?: number | null
+    linkedGiteaPR?: number | null
   }): Promise<HostedReviewInfo | null> {
     const repo = await this.resolveRepoSelector(args.repoSelector)
     this.assertHostIntegrationRepoIsLocal(repo, 'hosted_review')
@@ -4461,7 +4462,8 @@ export class OrcaRuntimeService {
       branch: args.branch,
       linkedGitHubPR: args.linkedGitHubPR ?? null,
       linkedGitLabMR: args.linkedGitLabMR ?? null,
-      linkedBitbucketPR: args.linkedBitbucketPR ?? null
+      linkedBitbucketPR: args.linkedBitbucketPR ?? null,
+      linkedGiteaPR: args.linkedGiteaPR ?? null
     })
     if (review?.provider === 'github' && this.stats && !this.stats.hasCountedPR(review.url)) {
       this.stats.record({
diff --git a/src/main/runtime/rpc/methods/hosted-review.test.ts b/src/main/runtime/rpc/methods/hosted-review.test.ts
index df3ecc0f544..e7eaab3009f 100644
--- a/src/main/runtime/rpc/methods/hosted-review.test.ts
+++ b/src/main/runtime/rpc/methods/hosted-review.test.ts
@@ -38,7 +38,8 @@ describe('hosted review RPC methods', () => {
       branch: 'feature/windows',
       linkedGitHubPR: 12,
       linkedGitLabMR: null,
-      linkedBitbucketPR: null
+      linkedBitbucketPR: null,
+      linkedGiteaPR: null
     })
     expect(response).toMatchObject({
       ok: true,
diff --git a/src/main/runtime/rpc/methods/hosted-review.ts b/src/main/runtime/rpc/methods/hosted-review.ts
index 952f00f6be4..3d38f36604a 100644
--- a/src/main/runtime/rpc/methods/hosted-review.ts
+++ b/src/main/runtime/rpc/methods/hosted-review.ts
@@ -7,7 +7,8 @@ const HostedReviewForBranch = z.object({
   branch: requiredString('Missing branch'),
   linkedGitHubPR: z.number().int().positive().nullable().optional(),
   linkedGitLabMR: z.number().int().positive().nullable().optional(),
-  linkedBitbucketPR: z.number().int().positive().nullable().optional()
+  linkedBitbucketPR: z.number().int().positive().nullable().optional(),
+  linkedGiteaPR: z.number().int().positive().nullable().optional()
 })
 
 export const HOSTED_REVIEW_METHODS: RpcMethod[] = [
@@ -20,7 +21,8 @@ export const HOSTED_REVIEW_METHODS: RpcMethod[] = [
         branch: params.branch,
         linkedGitHubPR: params.linkedGitHubPR ?? null,
         linkedGitLabMR: params.linkedGitLabMR ?? null,
-        linkedBitbucketPR: params.linkedBitbucketPR ?? null
+        linkedBitbucketPR: params.linkedBitbucketPR ?? null,
+        linkedGiteaPR: params.linkedGiteaPR ?? null
       })
   })
 ]
diff --git a/src/main/source-control/hosted-review-gitea.integration.test.ts b/src/main/source-control/hosted-review-gitea.integration.test.ts
new file mode 100644
index 00000000000..a8bf4c40454
--- /dev/null
+++ b/src/main/source-control/hosted-review-gitea.integration.test.ts
@@ -0,0 +1,113 @@
+import { execFile } from 'child_process'
+import { mkdtemp, rm } from 'fs/promises'
+import { createServer, type IncomingMessage, type ServerResponse } from 'http'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { promisify } from 'util'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { _resetGiteaRepoRefCache } from '../gitea/repository-ref'
+import { getHostedReviewForBranch } from './hosted-review'
+
+const execFileAsync = promisify(execFile)
+const OLD_ENV = process.env
+
+type SeenRequest = {
+  pathname: string
+  search: string
+  authorization: string | undefined
+}
+
+function sendJson(res: ServerResponse, body: unknown): void {
+  res.writeHead(200, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify(body))
+}
+
+describe('Gitea hosted review integration', () => {
+  beforeEach(() => {
+    process.env = { ...OLD_ENV, ORCA_GITEA_TOKEN: 'local-token' }
+    delete process.env.ORCA_GITEA_API_BASE_URL
+    _resetGiteaRepoRefCache()
+  })
+
+  afterEach(() => {
+    process.env = OLD_ENV
+    _resetGiteaRepoRefCache()
+  })
+
+  it('resolves a Gitea PR through real git remote parsing and HTTP API calls', async () => {
+    const seen: SeenRequest[] = []
+    const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`)
+      seen.push({
+        pathname: url.pathname,
+        search: url.search,
+        authorization: req.headers.authorization
+      })
+
+      if (url.pathname === '/api/v1/repos/team/repo/pulls') {
+        sendJson(res, [
+          {
+            number: 9,
+            title: 'Local Gitea branch',
+            state: 'open',
+            html_url: 'http://127.0.0.1/team/repo/pulls/9',
+            updated_at: '2026-05-15T00:00:00Z',
+            mergeable: true,
+            head: { ref: 'feature/gitea', label: 'team:feature/gitea', sha: 'abc123' }
+          }
+        ])
+        return
+      }
+
+      if (url.pathname === '/api/v1/repos/team/repo/commits/abc123/status') {
+        sendJson(res, { state: 'success' })
+        return
+      }
+
+      res.writeHead(404, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ message: 'not found' }))
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+
+    const repoPath = await mkdtemp(join(tmpdir(), 'orca-gitea-review-'))
+    try {
+      const address = server.address()
+      if (!address || typeof address === 'string') {
+        throw new Error('expected TCP server address')
+      }
+
+      await execFileAsync('git', ['init'], { cwd: repoPath })
+      await execFileAsync(
+        'git',
+        ['remote', 'add', 'origin', `http://127.0.0.1:${address.port}/team/repo.git`],
+        { cwd: repoPath }
+      )
+
+      await expect(
+        getHostedReviewForBranch({ repoPath, branch: 'refs/heads/feature/gitea' })
+      ).resolves.toEqual({
+        provider: 'gitea',
+        number: 9,
+        title: 'Local Gitea branch',
+        state: 'open',
+        url: 'http://127.0.0.1/team/repo/pulls/9',
+        status: 'success',
+        updatedAt: '2026-05-15T00:00:00Z',
+        mergeable: 'MERGEABLE',
+        headSha: 'abc123'
+      })
+
+      expect(seen.map((request) => request.pathname)).toEqual([
+        '/api/v1/repos/team/repo/pulls',
+        '/api/v1/repos/team/repo/commits/abc123/status'
+      ])
+      expect(seen.every((request) => request.authorization === 'token local-token')).toBe(true)
+      expect(new URLSearchParams(seen[0].search).get('state')).toBe('all')
+    } finally {
+      await rm(repoPath, { recursive: true, force: true })
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()))
+      })
+    }
+  })
+})
diff --git a/src/main/source-control/hosted-review.test.ts b/src/main/source-control/hosted-review.test.ts
index ffd29cd1d9b..c45138b2663 100644
--- a/src/main/source-control/hosted-review.test.ts
+++ b/src/main/source-control/hosted-review.test.ts
@@ -6,14 +6,18 @@ const {
   getRepoSlugMock,
   getPRForBranchMock,
   getBitbucketRepoSlugMock,
-  getBitbucketPullRequestForBranchMock
+  getBitbucketPullRequestForBranchMock,
+  getGiteaRepoSlugMock,
+  getGiteaPullRequestForBranchMock
 } = vi.hoisted(() => ({
   getProjectSlugMock: vi.fn(),
   getMergeRequestForBranchMock: vi.fn(),
   getRepoSlugMock: vi.fn(),
   getPRForBranchMock: vi.fn(),
   getBitbucketRepoSlugMock: vi.fn(),
-  getBitbucketPullRequestForBranchMock: vi.fn()
+  getBitbucketPullRequestForBranchMock: vi.fn(),
+  getGiteaRepoSlugMock: vi.fn(),
+  getGiteaPullRequestForBranchMock: vi.fn()
 }))
 
 vi.mock('../gitlab/client', () => ({
@@ -33,6 +37,12 @@ vi.mock('../bitbucket/client', () => ({
   getBitbucketPullRequest: vi.fn()
 }))
 
+vi.mock('../gitea/client', () => ({
+  getGiteaRepoSlug: getGiteaRepoSlugMock,
+  getGiteaPullRequestForBranch: getGiteaPullRequestForBranchMock,
+  getGiteaPullRequest: vi.fn()
+}))
+
 import { getHostedReviewForBranch } from './hosted-review'
 
 describe('getHostedReviewForBranch', () => {
@@ -43,6 +53,8 @@ describe('getHostedReviewForBranch', () => {
     getPRForBranchMock.mockReset()
     getBitbucketRepoSlugMock.mockReset()
     getBitbucketPullRequestForBranchMock.mockReset()
+    getGiteaRepoSlugMock.mockReset()
+    getGiteaPullRequestForBranchMock.mockReset()
   })
 
   it('maps GitLab merge requests into the hosted review surface', async () => {
@@ -137,4 +149,44 @@ describe('getHostedReviewForBranch', () => {
       11
     )
   })
+
+  it('falls through to Gitea when origin is not another hosted provider', async () => {
+    getProjectSlugMock.mockResolvedValue(null)
+    getRepoSlugMock.mockResolvedValue(null)
+    getBitbucketRepoSlugMock.mockResolvedValue(null)
+    getGiteaRepoSlugMock.mockResolvedValue({
+      host: 'git.example.com',
+      owner: 'team',
+      repo: 'orca'
+    })
+    getGiteaPullRequestForBranchMock.mockResolvedValue({
+      number: 14,
+      title: 'Gitea branch',
+      state: 'open',
+      url: 'https://git.example.com/team/orca/pulls/14',
+      status: 'pending',
+      updatedAt: '2026-05-15T00:00:00.000Z',
+      mergeable: 'MERGEABLE',
+      headSha: 'def456'
+    })
+
+    await expect(
+      getHostedReviewForBranch({
+        repoPath: '/repo',
+        branch: 'feature/gitea',
+        linkedGiteaPR: 14
+      })
+    ).resolves.toEqual({
+      provider: 'gitea',
+      number: 14,
+      title: 'Gitea branch',
+      state: 'open',
+      url: 'https://git.example.com/team/orca/pulls/14',
+      status: 'pending',
+      updatedAt: '2026-05-15T00:00:00.000Z',
+      mergeable: 'MERGEABLE',
+      headSha: 'def456'
+    })
+    expect(getGiteaPullRequestForBranchMock).toHaveBeenCalledWith('/repo', 'feature/gitea', 14)
+  })
 })
diff --git a/src/main/source-control/hosted-review.ts b/src/main/source-control/hosted-review.ts
index a8f848d211e..1e3ce4e4b40 100644
--- a/src/main/source-control/hosted-review.ts
+++ b/src/main/source-control/hosted-review.ts
@@ -6,6 +6,12 @@ import {
   getBitbucketRepoSlug
 } from '../bitbucket/client'
 import type { BitbucketPullRequestInfo } from '../bitbucket/pull-request-mappers'
+import {
+  getGiteaPullRequest,
+  getGiteaPullRequestForBranch,
+  getGiteaRepoSlug
+} from '../gitea/client'
+import type { GiteaPullRequestInfo } from '../gitea/pull-request-mappers'
 import { getPRForBranch, getRepoSlug } from '../github/client'
 import { getMergeRequest, getMergeRequestForBranch, getProjectSlug } from '../gitlab/client'
 
@@ -60,19 +66,35 @@ function mapBitbucketReview(pr: BitbucketPullRequestInfo): HostedReviewInfo {
   }
 }
 
+function mapGiteaReview(pr: GiteaPullRequestInfo): HostedReviewInfo {
+  return {
+    provider: 'gitea',
+    number: pr.number,
+    title: pr.title,
+    state: pr.state,
+    url: pr.url,
+    status: pr.status,
+    updatedAt: pr.updatedAt,
+    mergeable: pr.mergeable,
+    ...(pr.headSha ? { headSha: pr.headSha } : {})
+  }
+}
+
 export async function getHostedReviewForBranch(input: {
   repoPath: string
   branch: string
   linkedGitHubPR?: number | null
   linkedGitLabMR?: number | null
   linkedBitbucketPR?: number | null
+  linkedGiteaPR?: number | null
 }): Promise<HostedReviewInfo | null> {
   const branchName = input.branch.replace(/^refs\/heads\//, '')
   if (
     !branchName &&
     input.linkedGitHubPR == null &&
     input.linkedGitLabMR == null &&
-    input.linkedBitbucketPR == null
+    input.linkedBitbucketPR == null &&
+    input.linkedGiteaPR == null
   ) {
     return null
   }
@@ -104,12 +126,22 @@ export async function getHostedReviewForBranch(input: {
     return pr ? mapBitbucketReview(pr) : null
   }
 
+  const giteaRepo = await getGiteaRepoSlug(input.repoPath)
+  if (giteaRepo) {
+    const pr = await getGiteaPullRequestForBranch(
+      input.repoPath,
+      branchName,
+      input.linkedGiteaPR ?? null
+    )
+    return pr ? mapGiteaReview(pr) : null
+  }
+
   return null
 }
 
 export async function getHostedReviewByNumber(input: {
   repoPath: string
-  provider: 'github' | 'gitlab' | 'bitbucket'
+  provider: 'github' | 'gitlab' | 'bitbucket' | 'gitea'
   number: number
 }): Promise<HostedReviewInfo | null> {
   if (input.provider === 'gitlab') {
@@ -120,6 +152,10 @@ export async function getHostedReviewByNumber(input: {
     const pr = await getBitbucketPullRequest(input.repoPath, input.number)
     return pr ? mapBitbucketReview(pr) : null
   }
+  if (input.provider === 'gitea') {
+    const pr = await getGiteaPullRequest(input.repoPath, input.number)
+    return pr ? mapGiteaReview(pr) : null
+  }
   const pr = await getPRForBranch(input.repoPath, '', input.number)
   return pr ? mapGitHubReview(pr) : null
 }
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 9140e0e3133..73322f995ab 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -312,6 +312,13 @@ export type PreflightStatus = {
    *  include it. Consumers gate on `glab?.installed` / `authenticated`. */
   glab?: { installed: boolean; authenticated: boolean }
   bitbucket?: { configured: boolean; authenticated: boolean; account: string | null }
+  gitea?: {
+    configured: boolean
+    authenticated: boolean
+    account: string | null
+    baseUrl: string | null
+    tokenConfigured: boolean
+  }
 }
 
 export type RefreshAgentsResult = {
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 6a203c2f204..5e987664eab 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -1068,6 +1068,13 @@ const api = {
       gh: { installed: boolean; authenticated: boolean }
       glab?: { installed: boolean; authenticated: boolean }
       bitbucket?: { configured: boolean; authenticated: boolean; account: string | null }
+      gitea?: {
+        configured: boolean
+        authenticated: boolean
+        account: string | null
+        baseUrl: string | null
+        tokenConfigured: boolean
+      }
       linear: { connected: boolean }
     }> => ipcRenderer.invoke('preflight:check', args),
     detectAgents: (): Promise<string[]> => ipcRenderer.invoke('preflight:detectAgents'),
diff --git a/src/renderer/src/components/settings/IntegrationsPane.tsx b/src/renderer/src/components/settings/IntegrationsPane.tsx
index a238bc78618..aa69b840b7b 100644
--- a/src/renderer/src/components/settings/IntegrationsPane.tsx
+++ b/src/renderer/src/components/settings/IntegrationsPane.tsx
@@ -1,5 +1,5 @@
-/* eslint-disable max-lines -- Why: this pane co-locates GitHub, GitLab,
-   and Linear integration cards so the preflight-check + status-badge +
+/* eslint-disable max-lines -- Why: this pane co-locates source-host and
+   Linear integration cards so the preflight-check + status-badge +
    install/auth-prompt scaffolding lives in one place rather than fanning
    out across per-integration files that would each repeat the same
    pattern. Splitting buys nothing while the surface stays this narrow. */
@@ -53,6 +53,11 @@ export const INTEGRATIONS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
     description: 'Bitbucket Cloud authentication via API token environment variables.',
     keywords: ['bitbucket', 'integration', 'pull request', 'api token']
   },
+  {
+    title: 'Gitea Integration',
+    description: 'Gitea authentication via API token environment variables.',
+    keywords: ['gitea', 'self-hosted', 'integration', 'pull request', 'api token']
+  },
   {
     title: 'Linear Integration',
     description: 'Connect Linear to browse and link issues.',
@@ -65,6 +70,25 @@ type GhStatus = 'checking' | 'connected' | 'not-installed' | 'not-authenticated'
 // modes (probe in-flight / installed-but-unauth / missing entirely).
 type GlabStatus = GhStatus
 type BitbucketStatus = 'checking' | 'connected' | 'not-configured' | 'not-authenticated'
+type GiteaStatus = 'checking' | 'configured' | 'not-configured' | 'not-authenticated'
+
+type GiteaPreflightStatus = {
+  configured: boolean
+  authenticated: boolean
+  account: string | null
+  baseUrl: string | null
+  tokenConfigured: boolean
+}
+
+function giteaStatusFromPreflight(status: GiteaPreflightStatus | undefined): GiteaStatus {
+  if (!status?.configured) {
+    return 'not-configured'
+  }
+  if (status.tokenConfigured && !status.authenticated) {
+    return 'not-authenticated'
+  }
+  return 'configured'
+}
 
 export function IntegrationsPane(): React.JSX.Element {
   const linearStatus = useAppStore((s) => s.linearStatus)
@@ -77,6 +101,9 @@ export function IntegrationsPane(): React.JSX.Element {
   const [glabStatus, setGlabStatus] = useState<GlabStatus>('checking')
   const [bitbucketStatus, setBitbucketStatus] = useState<BitbucketStatus>('checking')
   const [bitbucketAccount, setBitbucketAccount] = useState<string | null>(null)
+  const [giteaStatus, setGiteaStatus] = useState<GiteaStatus>('checking')
+  const [giteaAccount, setGiteaAccount] = useState<string | null>(null)
+  const [giteaBaseUrl, setGiteaBaseUrl] = useState<string | null>(null)
   const [linearDialogOpen, setLinearDialogOpen] = useState(false)
   const [linearApiKeyDraft, setLinearApiKeyDraft] = useState('')
   const [linearConnectState, setLinearConnectState] = useState<'idle' | 'connecting' | 'error'>(
@@ -118,6 +145,10 @@ export function IntegrationsPane(): React.JSX.Element {
       } else {
         setBitbucketStatus('connected')
       }
+      const gitea = status.gitea
+      setGiteaAccount(gitea?.account ?? null)
+      setGiteaBaseUrl(gitea?.baseUrl ?? null)
+      setGiteaStatus(giteaStatusFromPreflight(gitea))
     })
     // eslint-disable-next-line react-hooks/exhaustive-deps -- one-shot mount check
   }, [])
@@ -210,6 +241,16 @@ export function IntegrationsPane(): React.JSX.Element {
     })
   }
 
+  const handleRefreshGitea = (): void => {
+    setGiteaStatus('checking')
+    void window.api.preflight.check({ force: true }).then((status) => {
+      const gitea = status.gitea
+      setGiteaAccount(gitea?.account ?? null)
+      setGiteaBaseUrl(gitea?.baseUrl ?? null)
+      setGiteaStatus(giteaStatusFromPreflight(gitea))
+    })
+  }
+
   return (
     <div className="space-y-3">
       {/* GitHub */}
@@ -449,6 +490,90 @@ export function IntegrationsPane(): React.JSX.Element {
         )}
       </div>
 
+      {/* Gitea */}
+      <div className="rounded-md border border-border/50 bg-muted/30 px-4 py-3">
+        <div className="flex items-center gap-3">
+          <GitPullRequestArrow className="size-5 shrink-0 text-muted-foreground" />
+          <div className="min-w-0 flex-1 space-y-0.5">
+            <p className="text-sm font-medium">Gitea</p>
+            <p className="text-xs text-muted-foreground">
+              {giteaStatus === 'configured'
+                ? giteaAccount
+                  ? `${giteaAccount} · Pull requests and commit statuses`
+                  : giteaBaseUrl
+                    ? `${giteaBaseUrl} · Pull requests and commit statuses`
+                    : 'Pull requests and commit statuses for detected repositories'
+                : 'Pull requests and commit statuses via the Gitea REST API.'}
+            </p>
+          </div>
+          {giteaStatus === 'checking' ? (
+            <LoaderCircle className="size-4 shrink-0 animate-spin text-muted-foreground" />
+          ) : giteaStatus === 'configured' ? (
+            <span className="shrink-0 rounded-full border border-emerald-500/30 bg-emerald-500/10 px-2.5 py-1 text-[11px] font-medium text-emerald-700 dark:text-emerald-300">
+              {giteaAccount ? 'Connected' : 'Configured'}
+            </span>
+          ) : (
+            <span className="shrink-0 rounded-full border border-amber-500/30 bg-amber-500/10 px-2.5 py-1 text-[11px] font-medium text-amber-700 dark:text-amber-300">
+              {giteaStatus === 'not-configured' ? 'Optional setup' : 'Auth failed'}
+            </span>
+          )}
+        </div>
+
+        {giteaStatus !== 'checking' && giteaStatus !== 'configured' && (
+          <div className="mt-3 rounded-md border border-border/30 bg-background/50 px-3 py-2.5 space-y-2">
+            {giteaStatus === 'not-configured' ? (
+              <>
+                <p className="text-xs text-muted-foreground">
+                  Public repositories are detected from their git remote. Set{' '}
+                  <span className="font-mono text-[11px]">ORCA_GITEA_TOKEN</span> for private
+                  repositories, and set{' '}
+                  <span className="font-mono text-[11px]">ORCA_GITEA_API_BASE_URL</span> only when
+                  Orca cannot derive the API URL from the remote.
+                </p>
+                <div className="flex items-center gap-2">
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={() =>
+                      window.api.shell.openUrl('https://docs.gitea.com/next/development/api-usage')
+                    }
+                  >
+                    <ExternalLink className="size-3.5 mr-1.5" />
+                    Learn more
+                  </Button>
+                  <Button variant="ghost" size="sm" onClick={handleRefreshGitea}>
+                    Re-check
+                  </Button>
+                </div>
+              </>
+            ) : (
+              <>
+                <p className="text-xs text-muted-foreground">
+                  Gitea credentials are configured but could not authenticate. Check the token, API
+                  base URL, and repository permissions, then restart Orca if environment variables
+                  changed.
+                </p>
+                <div className="flex items-center gap-2">
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={() =>
+                      window.api.shell.openUrl('https://docs.gitea.com/next/development/api-usage')
+                    }
+                  >
+                    <ExternalLink className="size-3.5 mr-1.5" />
+                    Learn more
+                  </Button>
+                  <Button variant="ghost" size="sm" onClick={handleRefreshGitea}>
+                    Re-check
+                  </Button>
+                </div>
+              </>
+            )}
+          </div>
+        )}
+      </div>
+
       {/* Linear */}
       <div className="rounded-md border border-border/50 bg-muted/30 px-4 py-3">
         <div className="flex items-center gap-3">
diff --git a/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx b/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx
index 59ce508b06d..dc9ef9d5ae4 100644
--- a/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx
@@ -109,6 +109,9 @@ function getProviderName(review: HostedReviewInfo): string {
   if (review.provider === 'bitbucket') {
     return 'Bitbucket'
   }
+  if (review.provider === 'gitea') {
+    return 'Gitea'
+  }
   return 'GitHub'
 }
 
diff --git a/src/renderer/src/store/slices/hosted-review.test.ts b/src/renderer/src/store/slices/hosted-review.test.ts
index 3f90fb4bfbb..13466b0a19c 100644
--- a/src/renderer/src/store/slices/hosted-review.test.ts
+++ b/src/renderer/src/store/slices/hosted-review.test.ts
@@ -71,7 +71,8 @@ describe('hosted review slice', () => {
       branch: 'feature/gitlab',
       linkedGitHubPR: null,
       linkedGitLabMR: 5,
-      linkedBitbucketPR: null
+      linkedBitbucketPR: null,
+      linkedGiteaPR: null
     })
   })
 
@@ -96,7 +97,8 @@ describe('hosted review slice', () => {
         branch: 'feature/windows',
         linkedGitHubPR: 12,
         linkedGitLabMR: null,
-        linkedBitbucketPR: null
+        linkedBitbucketPR: null,
+        linkedGiteaPR: null
       },
       { timeoutMs: 30_000 }
     )
diff --git a/src/renderer/src/store/slices/hosted-review.ts b/src/renderer/src/store/slices/hosted-review.ts
index 39b545f62e2..1c86e9d1221 100644
--- a/src/renderer/src/store/slices/hosted-review.ts
+++ b/src/renderer/src/store/slices/hosted-review.ts
@@ -38,6 +38,7 @@ export type HostedReviewSlice = {
       linkedGitHubPR?: number | null
       linkedGitLabMR?: number | null
       linkedBitbucketPR?: number | null
+      linkedGiteaPR?: number | null
     }
   ) => Promise<HostedReviewInfo | null>
 }
@@ -61,7 +62,8 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
       cached?.data === null &&
       ((options?.linkedGitHubPR ?? null) !== null ||
         (options?.linkedGitLabMR ?? null) !== null ||
-        (options?.linkedBitbucketPR ?? null) !== null)
+        (options?.linkedBitbucketPR ?? null) !== null ||
+        (options?.linkedGiteaPR ?? null) !== null)
     if (!options?.force && !linkedRefetch && isFresh(cached)) {
       return cached.data
     }
@@ -80,7 +82,8 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
           branch,
           linkedGitHubPR: options?.linkedGitHubPR ?? null,
           linkedGitLabMR: options?.linkedGitLabMR ?? null,
-          linkedBitbucketPR: options?.linkedBitbucketPR ?? null
+          linkedBitbucketPR: options?.linkedBitbucketPR ?? null,
+          linkedGiteaPR: options?.linkedGiteaPR ?? null
         }
         const review =
           target.kind === 'environment'
diff --git a/src/shared/hosted-review.ts b/src/shared/hosted-review.ts
index 51697d30f02..a1dee49d5b2 100644
--- a/src/shared/hosted-review.ts
+++ b/src/shared/hosted-review.ts
@@ -1,6 +1,6 @@
 import type { CheckStatus, PRConflictSummary, PRMergeableState } from './types'
 
-export type HostedReviewProvider = 'github' | 'gitlab' | 'bitbucket'
+export type HostedReviewProvider = 'github' | 'gitlab' | 'bitbucket' | 'gitea'
 
 export type HostedReviewState = 'open' | 'closed' | 'merged' | 'draft'
 
@@ -23,4 +23,5 @@ export type HostedReviewForBranchArgs = {
   linkedGitHubPR?: number | null
   linkedGitLabMR?: number | null
   linkedBitbucketPR?: number | null
+  linkedGiteaPR?: number | null
 }

From d4cf116d3f6645ba1d9994007187726c8733c20c Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 02:01:19 -0700
Subject: [PATCH 31/82] Fix Windows CJK terminal WebGL rendering

---
 .../lib/pane-manager/terminal-complex-script.test.ts |  9 +++++++++
 .../src/lib/pane-manager/terminal-complex-script.ts  | 12 ++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/src/renderer/src/lib/pane-manager/terminal-complex-script.test.ts b/src/renderer/src/lib/pane-manager/terminal-complex-script.test.ts
index 20d131fbe7e..5c66dc0646e 100644
--- a/src/renderer/src/lib/pane-manager/terminal-complex-script.test.ts
+++ b/src/renderer/src/lib/pane-manager/terminal-complex-script.test.ts
@@ -10,6 +10,15 @@ describe('terminalOutputPrefersDomRenderer', () => {
     expect(terminalOutputPrefersDomRenderer('Hebrew: שלום')).toBe(true)
   })
 
+  it('detects East Asian wide and fullwidth terminal output', () => {
+    expect(
+      terminalOutputPrefersDomRenderer('直接接请求本地 /api/mcp，带同一个 Bearer token，成功')
+    ).toBe(true)
+    expect(terminalOutputPrefersDomRenderer('Japanese: ターミナル')).toBe(true)
+    expect(terminalOutputPrefersDomRenderer('Korean: 터미널')).toBe(true)
+    expect(terminalOutputPrefersDomRenderer('Fullwidth: ＡＢＣ１２３')).toBe(true)
+  })
+
   it('detects glyph classes common in agent terminal UIs', () => {
     expect(terminalOutputPrefersDomRenderer('⠋ Working')).toBe(true)
     expect(terminalOutputPrefersDomRenderer('├─ file.ts')).toBe(true)
diff --git a/src/renderer/src/lib/pane-manager/terminal-complex-script.ts b/src/renderer/src/lib/pane-manager/terminal-complex-script.ts
index 23f226319f5..beecca3cfc9 100644
--- a/src/renderer/src/lib/pane-manager/terminal-complex-script.ts
+++ b/src/renderer/src/lib/pane-manager/terminal-complex-script.ts
@@ -10,17 +10,29 @@ function isRendererRiskCodePoint(value: number): boolean {
   return (
     isInRange(value, 0x0590, 0x08ff) ||
     value === 0x200d ||
+    isInRange(value, 0x1100, 0x11ff) ||
     isInRange(value, 0x2500, 0x259f) ||
     isInRange(value, 0x25a0, 0x25ff) ||
     isInRange(value, 0x2800, 0x28ff) ||
+    // Why: xterm WebGL can leave stale atlas cells for East Asian wide glyphs
+    // on Windows; force browser text rendering before long CJK output paints.
+    isInRange(value, 0x2e80, 0x9fff) ||
+    isInRange(value, 0xa960, 0xa97f) ||
+    isInRange(value, 0xac00, 0xd7ff) ||
     isInRange(value, 0xd800, 0xdfff) ||
     isInRange(value, 0xe000, 0xf8ff) ||
+    isInRange(value, 0xf900, 0xfaff) ||
+    isInRange(value, 0xfe10, 0xfe1f) ||
+    isInRange(value, 0xfe30, 0xfe4f) ||
     isInRange(value, 0xfb1d, 0xfdff) ||
     isInRange(value, 0xfe00, 0xfe0f) ||
     isInRange(value, 0xfe70, 0xfeff) ||
+    isInRange(value, 0xff00, 0xffef) ||
     value === 0xfffd ||
     isInRange(value, 0x10ec0, 0x10eff) ||
     isInRange(value, 0x1e900, 0x1e95f) ||
+    isInRange(value, 0x20000, 0x2fa1f) ||
+    isInRange(value, 0x30000, 0x3134f) ||
     isInRange(value, 0xe0100, 0xe01ef)
   )
 }

From b030257c3b6fe98fc5d8b28daeaf5954e9d1ca69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Leynier=20Guti=C3=A9rrez=20Gonz=C3=A1lez?=
 <leynier41@gmail.com>
Date: Fri, 15 May 2026 03:18:46 -0600
Subject: [PATCH 32/82] feat(source-control): AI commit message generation
 (#1487)

Co-authored-by: Orca <help@stably.ai>
Co-authored-by: brennanb2025 <brennankbenson@gmail.com>
---
 src/main/attribution/terminal-attribution.ts  |   2 +-
 src/main/codex-cli/command.ts                 |   9 +-
 src/main/git/status.test.ts                   |  34 ++
 src/main/git/status.ts                        |  37 ++
 src/main/index.ts                             |  14 +-
 src/main/ipc/filesystem.test.ts               | 307 +++++++++++
 src/main/ipc/filesystem.ts                    | 151 +++++-
 src/main/ipc/register-core-handlers.ts        |  14 +-
 src/main/providers/ssh-git-dispatch.ts        |   8 +-
 src/main/providers/ssh-git-provider.test.ts   |  76 +++
 src/main/providers/ssh-git-provider.ts        |  55 ++
 src/main/providers/types.ts                   |   2 +
 .../commit-message-text-generation.test.ts    | 473 +++++++++++++++++
 .../commit-message-text-generation.ts         | 450 ++++++++++++++++
 src/main/win32-utils.test.ts                  |  14 +-
 src/main/win32-utils.ts                       |  31 +-
 src/preload/api-types.ts                      |  11 +
 src/preload/index.ts                          |   8 +
 src/relay/agent-exec-handler.test.ts          | 259 ++++++++++
 src/relay/agent-exec-handler.ts               | 254 +++++++++
 src/relay/git-exec-validator.test.ts          |  17 +
 src/relay/git-exec-validator.ts               |  22 +
 src/relay/relay.ts                            |   8 +
 .../CommitArea.chevron-spinner.test.tsx       |   8 +
 .../CommitArea.generate.test.tsx              | 213 ++++++++
 .../CommitArea.primary-icons.test.tsx         |   8 +
 .../right-sidebar/CommitArea.test.tsx         |  11 +
 .../right-sidebar/SourceControl.tsx           | 236 ++++++++-
 .../settings/CommitMessageAiPane.test.tsx     |  97 ++++
 .../settings/CommitMessageAiPane.tsx          | 480 ++++++++++++++++++
 .../src/components/settings/Settings.tsx      |  17 +-
 .../settings/commit-message-ai-search.ts      |  45 ++
 src/shared/commit-message-agent-spec.test.ts  | 165 ++++++
 src/shared/commit-message-agent-spec.ts       | 266 ++++++++++
 src/shared/commit-message-generation.test.ts  |  50 ++
 src/shared/commit-message-generation.ts       |  84 +++
 src/shared/commit-message-plan.test.ts        | 101 ++++
 src/shared/commit-message-plan.ts             | 127 +++++
 src/shared/commit-message-prompt.test.ts      | 203 ++++++++
 src/shared/commit-message-prompt.ts           | 231 +++++++++
 src/shared/constants.ts                       |  12 +
 src/shared/orca-attribution.ts                |   6 +
 src/shared/types.ts                           |  20 +
 .../source-control-commit-message-ai.spec.ts  | 132 +++++
 44 files changed, 4731 insertions(+), 37 deletions(-)
 create mode 100644 src/main/text-generation/commit-message-text-generation.test.ts
 create mode 100644 src/main/text-generation/commit-message-text-generation.ts
 create mode 100644 src/relay/agent-exec-handler.test.ts
 create mode 100644 src/relay/agent-exec-handler.ts
 create mode 100644 src/renderer/src/components/right-sidebar/CommitArea.generate.test.tsx
 create mode 100644 src/renderer/src/components/settings/CommitMessageAiPane.test.tsx
 create mode 100644 src/renderer/src/components/settings/CommitMessageAiPane.tsx
 create mode 100644 src/renderer/src/components/settings/commit-message-ai-search.ts
 create mode 100644 src/shared/commit-message-agent-spec.test.ts
 create mode 100644 src/shared/commit-message-agent-spec.ts
 create mode 100644 src/shared/commit-message-generation.test.ts
 create mode 100644 src/shared/commit-message-generation.ts
 create mode 100644 src/shared/commit-message-plan.test.ts
 create mode 100644 src/shared/commit-message-plan.ts
 create mode 100644 src/shared/commit-message-prompt.test.ts
 create mode 100644 src/shared/commit-message-prompt.ts
 create mode 100644 src/shared/orca-attribution.ts
 create mode 100644 tests/e2e/source-control-commit-message-ai.spec.ts

diff --git a/src/main/attribution/terminal-attribution.ts b/src/main/attribution/terminal-attribution.ts
index 22c7af94bd8..4162e15e33c 100644
--- a/src/main/attribution/terminal-attribution.ts
+++ b/src/main/attribution/terminal-attribution.ts
@@ -4,11 +4,11 @@ to the env injection code makes the attribution behavior auditable as one unit
 instead of scattering generated shell fragments across files. */
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
+import { ORCA_GIT_COMMIT_TRAILER } from '../../shared/orca-attribution'
 
 const ATTRIBUTION_ROOT_DIR = 'orca-terminal-attribution'
 const ATTRIBUTION_SHIM_VERSION = '6'
 const ORCA_PRODUCT_URL = 'https://github.com/stablyai/orca'
-const ORCA_GIT_COMMIT_TRAILER = 'Co-authored-by: Orca <help@stably.ai>'
 const ORCA_GH_FOOTER = `Made with [Orca](${ORCA_PRODUCT_URL}) 🐋`
 const SHELL_DOLLAR = '$'
 const POWERSHELL_TICK = '`'
diff --git a/src/main/codex-cli/command.ts b/src/main/codex-cli/command.ts
index ccdb7981ddd..2215583ac54 100644
--- a/src/main/codex-cli/command.ts
+++ b/src/main/codex-cli/command.ts
@@ -121,7 +121,10 @@ function getVersionManagerDirectories(
   return directories
 }
 
-function resolveCommand(commandName: string, options: ResolveCommandOptions = {}): string {
+export function resolveCliCommand(
+  commandName: string,
+  options: ResolveCommandOptions = {}
+): string {
   const platform = options.platform ?? process.platform
   const executableNames = getExecutableNames(platform, commandName)
   const pathEnv = options.pathEnv ?? process.env.PATH ?? process.env.Path ?? null
@@ -139,11 +142,11 @@ function resolveCommand(commandName: string, options: ResolveCommandOptions = {}
 }
 
 export function resolveCodexCommand(options: ResolveCommandOptions = {}): string {
-  return resolveCommand('codex', options)
+  return resolveCliCommand('codex', options)
 }
 
 export function resolveClaudeCommand(options: ResolveCommandOptions = {}): string {
-  return resolveCommand('claude', options)
+  return resolveCliCommand('claude', options)
 }
 
 // Why: GUI-launched Electron apps inherit a minimal PATH that excludes Node
diff --git a/src/main/git/status.test.ts b/src/main/git/status.test.ts
index 3a815558c18..24f2648d77d 100644
--- a/src/main/git/status.test.ts
+++ b/src/main/git/status.test.ts
@@ -33,6 +33,7 @@ import {
   discardChanges,
   getBranchCompare,
   getDiff,
+  getStagedCommitContext,
   getStatus,
   isWithinWorktree
 } from './status'
@@ -406,6 +407,39 @@ describe('getStatus', () => {
   })
 })
 
+describe('getStagedCommitContext', () => {
+  beforeEach(() => {
+    gitExecFileAsyncMock.mockReset()
+  })
+
+  it('uses explicit large buffers before prompt truncation', async () => {
+    gitExecFileAsyncMock
+      .mockResolvedValueOnce({ stdout: 'feature/ai\n' })
+      .mockResolvedValueOnce({ stdout: 'M\tREADME.md\n' })
+      .mockResolvedValueOnce({ stdout: 'diff --git a/README.md b/README.md\n+hello\n' })
+
+    const result = await getStagedCommitContext('/repo')
+
+    expect(result).toEqual({
+      branch: 'feature/ai',
+      stagedSummary: 'M\tREADME.md',
+      stagedPatch: 'diff --git a/README.md b/README.md\n+hello\n'
+    })
+    expect(gitExecFileAsyncMock).toHaveBeenNthCalledWith(2, ['diff', '--cached', '--name-status'], {
+      cwd: '/repo',
+      maxBuffer: 10 * 1024 * 1024
+    })
+    expect(gitExecFileAsyncMock).toHaveBeenNthCalledWith(
+      3,
+      ['diff', '--cached', '--patch', '--minimal', '--no-color', '--no-ext-diff'],
+      {
+        cwd: '/repo',
+        maxBuffer: 10 * 1024 * 1024
+      }
+    )
+  })
+})
+
 describe('detectConflictOperation', () => {
   beforeEach(() => {
     readFileMock.mockReset()
diff --git a/src/main/git/status.ts b/src/main/git/status.ts
index b24535d4454..1b74904fde7 100644
--- a/src/main/git/status.ts
+++ b/src/main/git/status.ts
@@ -14,9 +14,11 @@ import type {
   GitStatusEntry,
   GitStatusResult
 } from '../../shared/types'
+import type { CommitMessageDraftContext } from '../../shared/commit-message-generation'
 import { gitExecFileAsync, gitExecFileAsyncBuffer } from './runner'
 
 const MAX_GIT_SHOW_BYTES = 10 * 1024 * 1024
+const MAX_STAGED_COMMIT_CONTEXT_BYTES = MAX_GIT_SHOW_BYTES
 const BULK_CHUNK_SIZE = 100
 
 /**
@@ -728,6 +730,41 @@ export async function unstageFile(worktreePath: string, filePath: string): Promi
   await gitExecFileAsync(['restore', '--staged', '--', filePath], { cwd: worktreePath })
 }
 
+export async function getStagedCommitContext(
+  worktreePath: string
+): Promise<CommitMessageDraftContext | null> {
+  const branchPromise = gitExecFileAsync(['branch', '--show-current'], {
+    cwd: worktreePath
+  }).catch(() => ({ stdout: '' }))
+  const summaryPromise = gitExecFileAsync(['diff', '--cached', '--name-status'], {
+    cwd: worktreePath,
+    maxBuffer: MAX_STAGED_COMMIT_CONTEXT_BYTES
+  })
+
+  const [branchResult, summaryResult] = await Promise.all([branchPromise, summaryPromise])
+  const stagedSummary = summaryResult.stdout.trim()
+  if (!stagedSummary) {
+    return null
+  }
+
+  const { stdout: stagedPatch } = await gitExecFileAsync(
+    ['diff', '--cached', '--patch', '--minimal', '--no-color', '--no-ext-diff'],
+    {
+      cwd: worktreePath,
+      // Why: the prompt builder truncates large staged patches later. Give git
+      // enough buffer room to reach that truncation step instead of failing at
+      // Node's default execFile limit first.
+      maxBuffer: MAX_STAGED_COMMIT_CONTEXT_BYTES
+    }
+  )
+
+  return {
+    branch: branchResult.stdout.trim() || null,
+    stagedSummary,
+    stagedPatch
+  }
+}
+
 export async function commitChanges(
   worktreePath: string,
   message: string
diff --git a/src/main/index.ts b/src/main/index.ts
index 19c20b07e10..d16fdb2f141 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -269,7 +269,14 @@ function openMainWindow(): BrowserWindow {
     claudeAccounts,
     rateLimits,
     window.webContents.id,
-    automations
+    automations,
+    {
+      prepareForCodexLaunch: () =>
+        store!.getSettings().activeCodexManagedAccountId
+          ? codexRuntimeHome!.prepareForCodexLaunch()
+          : null,
+      prepareForClaudeLaunch: () => claudeRuntimeAuth!.prepareForClaudeLaunch()
+    }
   )
   automations.setWebContents(window.webContents)
   automations.start()
@@ -277,7 +284,10 @@ function openMainWindow(): BrowserWindow {
     window,
     store,
     runtime,
-    () => codexRuntimeHome!.prepareForCodexLaunch(),
+    () =>
+      store!.getSettings().activeCodexManagedAccountId
+        ? codexRuntimeHome!.prepareForCodexLaunch()
+        : null,
     () => claudeRuntimeAuth!.prepareForClaudeLaunch()
   )
   rateLimits.attach(window)
diff --git a/src/main/ipc/filesystem.test.ts b/src/main/ipc/filesystem.test.ts
index b0c267f624a..5196bdb475b 100644
--- a/src/main/ipc/filesystem.test.ts
+++ b/src/main/ipc/filesystem.test.ts
@@ -18,6 +18,7 @@ const {
   getDiffMock,
   getBranchCompareMock,
   getBranchDiffMock,
+  getStagedCommitContextMock,
   stageFileMock,
   bulkStageFilesMock,
   unstageFileMock,
@@ -25,6 +26,9 @@ const {
   bulkDiscardChangesMock,
   discardChangesMock,
   listWorktreesMock,
+  resolveCommitMessageSettingsMock,
+  generateCommitMessageFromContextMock,
+  cancelGenerateCommitMessageLocalMock,
   getSshFilesystemProviderMock,
   getSshGitProviderMock
 } = vi.hoisted(() => ({
@@ -42,6 +46,7 @@ const {
   getDiffMock: vi.fn(),
   getBranchCompareMock: vi.fn(),
   getBranchDiffMock: vi.fn(),
+  getStagedCommitContextMock: vi.fn(),
   stageFileMock: vi.fn(),
   bulkStageFilesMock: vi.fn(),
   unstageFileMock: vi.fn(),
@@ -49,6 +54,9 @@ const {
   bulkDiscardChangesMock: vi.fn(),
   discardChangesMock: vi.fn(),
   listWorktreesMock: vi.fn(),
+  resolveCommitMessageSettingsMock: vi.fn(),
+  generateCommitMessageFromContextMock: vi.fn(),
+  cancelGenerateCommitMessageLocalMock: vi.fn(),
   getSshFilesystemProviderMock: vi.fn(),
   getSshGitProviderMock: vi.fn()
 }))
@@ -78,6 +86,7 @@ vi.mock('../git/status', () => ({
   getDiff: getDiffMock,
   getBranchCompare: getBranchCompareMock,
   getBranchDiff: getBranchDiffMock,
+  getStagedCommitContext: getStagedCommitContextMock,
   stageFile: stageFileMock,
   bulkStageFiles: bulkStageFilesMock,
   unstageFile: unstageFileMock,
@@ -98,6 +107,12 @@ vi.mock('../providers/ssh-git-dispatch', () => ({
   getSshGitProvider: getSshGitProviderMock
 }))
 
+vi.mock('../text-generation/commit-message-text-generation', () => ({
+  resolveCommitMessageSettings: resolveCommitMessageSettingsMock,
+  generateCommitMessageFromContext: generateCommitMessageFromContextMock,
+  cancelGenerateCommitMessageLocal: cancelGenerateCommitMessageLocalMock
+}))
+
 import { registerFilesystemHandlers } from './filesystem'
 import { invalidateAuthorizedRootsCache, registerWorktreeRootsForRepo } from './filesystem-auth'
 
@@ -161,6 +176,7 @@ describe('registerFilesystemHandlers', () => {
       getDiffMock,
       getBranchCompareMock,
       getBranchDiffMock,
+      getStagedCommitContextMock,
       stageFileMock,
       bulkStageFilesMock,
       unstageFileMock,
@@ -168,6 +184,9 @@ describe('registerFilesystemHandlers', () => {
       bulkDiscardChangesMock,
       discardChangesMock,
       listWorktreesMock,
+      resolveCommitMessageSettingsMock,
+      generateCommitMessageFromContextMock,
+      cancelGenerateCommitMessageLocalMock,
       getSshFilesystemProviderMock,
       getSshGitProviderMock
     ]) {
@@ -720,6 +739,294 @@ describe('registerFilesystemHandlers', () => {
     ).resolves.toEqual({ success: false, error: 'hook failed' })
   })
 
+  it('generates a local commit message from main-process staged context', async () => {
+    const context = {
+      branch: 'feature/ai',
+      stagedSummary: 'M\tREADME.md',
+      stagedPatch: '+hello'
+    }
+    const params = { agentId: 'codex', model: 'gpt-5.4-mini', thinkingLevel: 'low' }
+    resolveCommitMessageSettingsMock.mockReturnValue({ ok: true, params })
+    getStagedCommitContextMock.mockResolvedValue(context)
+    generateCommitMessageFromContextMock.mockResolvedValue({
+      success: true,
+      message: 'Update README'
+    })
+
+    registerFilesystemHandlers(store as never)
+
+    await expect(
+      handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: WORKTREE_FEATURE_PATH
+      })
+    ).resolves.toEqual({ success: true, message: 'Update README' })
+
+    expect(getStagedCommitContextMock).toHaveBeenCalledWith(WORKTREE_FEATURE_PATH)
+    expect(generateCommitMessageFromContextMock).toHaveBeenCalledWith(context, params, {
+      kind: 'local',
+      cwd: WORKTREE_FEATURE_PATH
+    })
+  })
+
+  it('prepares the selected Codex account home before local generation', async () => {
+    const context = {
+      branch: 'feature/ai',
+      stagedSummary: 'M\tREADME.md',
+      stagedPatch: '+hello'
+    }
+    const params = { agentId: 'codex', model: 'gpt-5.4-mini', thinkingLevel: 'low' }
+    resolveCommitMessageSettingsMock.mockReturnValue({ ok: true, params })
+    getStagedCommitContextMock.mockResolvedValue(context)
+    generateCommitMessageFromContextMock.mockResolvedValue({
+      success: true,
+      message: 'Update README'
+    })
+
+    registerFilesystemHandlers(store as never, {
+      prepareForCodexLaunch: () => '/managed/codex-home'
+    })
+
+    await handlers.get('git:generateCommitMessage')!(null, {
+      worktreePath: WORKTREE_FEATURE_PATH
+    })
+
+    expect(generateCommitMessageFromContextMock).toHaveBeenCalledWith(
+      context,
+      params,
+      expect.objectContaining({
+        kind: 'local',
+        cwd: WORKTREE_FEATURE_PATH,
+        env: expect.objectContaining({ CODEX_HOME: '/managed/codex-home' })
+      })
+    )
+  })
+
+  it('preserves the inherited Codex environment when no managed account is selected', async () => {
+    const previousCodexHome = process.env.CODEX_HOME
+    process.env.CODEX_HOME = '/system/codex-home'
+    const context = {
+      branch: 'feature/ai',
+      stagedSummary: 'M\tREADME.md',
+      stagedPatch: '+hello'
+    }
+    const params = { agentId: 'codex', model: 'gpt-5.4-mini', thinkingLevel: 'low' }
+    resolveCommitMessageSettingsMock.mockReturnValue({ ok: true, params })
+    getStagedCommitContextMock.mockResolvedValue(context)
+    generateCommitMessageFromContextMock.mockResolvedValue({
+      success: true,
+      message: 'Update README'
+    })
+
+    try {
+      registerFilesystemHandlers(store as never, {
+        prepareForCodexLaunch: () => null
+      })
+
+      await handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: WORKTREE_FEATURE_PATH
+      })
+
+      expect(generateCommitMessageFromContextMock).toHaveBeenCalledWith(context, params, {
+        kind: 'local',
+        cwd: WORKTREE_FEATURE_PATH
+      })
+    } finally {
+      if (previousCodexHome === undefined) {
+        delete process.env.CODEX_HOME
+      } else {
+        process.env.CODEX_HOME = previousCodexHome
+      }
+    }
+  })
+
+  it('returns a sanitized error when local agent account preparation fails', async () => {
+    const context = {
+      branch: 'feature/ai',
+      stagedSummary: 'M\tREADME.md',
+      stagedPatch: '+hello'
+    }
+    const params = { agentId: 'codex', model: 'gpt-5.4-mini', thinkingLevel: 'low' }
+    resolveCommitMessageSettingsMock.mockReturnValue({ ok: true, params })
+    getStagedCommitContextMock.mockResolvedValue(context)
+
+    registerFilesystemHandlers(store as never, {
+      prepareForCodexLaunch: () => {
+        throw new Error('failed to read /Users/alice/.codex/auth.json')
+      }
+    })
+
+    await expect(
+      handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: WORKTREE_FEATURE_PATH
+      })
+    ).resolves.toEqual({
+      success: false,
+      error: 'Failed to prepare the selected agent account for commit message generation.'
+    })
+    expect(generateCommitMessageFromContextMock).not.toHaveBeenCalled()
+  })
+
+  it('prepares the selected Claude auth environment before local generation', async () => {
+    const previousAnthropicApiKey = process.env.ANTHROPIC_API_KEY
+    process.env.ANTHROPIC_API_KEY = 'do-not-leak-managed-auth-conflict'
+    const context = {
+      branch: 'feature/ai',
+      stagedSummary: 'M\tREADME.md',
+      stagedPatch: '+hello'
+    }
+    const params = { agentId: 'claude', model: 'claude-haiku-4-5' }
+    resolveCommitMessageSettingsMock.mockReturnValue({ ok: true, params })
+    getStagedCommitContextMock.mockResolvedValue(context)
+    generateCommitMessageFromContextMock.mockResolvedValue({
+      success: true,
+      message: 'Update README'
+    })
+
+    try {
+      registerFilesystemHandlers(store as never, {
+        prepareForClaudeLaunch: async () => ({
+          configDir: '/managed/claude',
+          envPatch: { CLAUDE_CONFIG_DIR: '/managed/claude' },
+          stripAuthEnv: true,
+          provenance: 'managed:account-1'
+        })
+      })
+
+      await handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: WORKTREE_FEATURE_PATH
+      })
+
+      const target = generateCommitMessageFromContextMock.mock.calls[0]?.[2] as
+        | { env?: NodeJS.ProcessEnv }
+        | undefined
+      expect(target?.env).toEqual(
+        expect.objectContaining({
+          CLAUDE_CONFIG_DIR: '/managed/claude'
+        })
+      )
+      expect(target?.env?.ANTHROPIC_API_KEY).toBeUndefined()
+    } finally {
+      if (previousAnthropicApiKey === undefined) {
+        delete process.env.ANTHROPIC_API_KEY
+      } else {
+        process.env.ANTHROPIC_API_KEY = previousAnthropicApiKey
+      }
+    }
+  })
+
+  it('generates an SSH commit message using remote staged context and relay execution', async () => {
+    const context = {
+      branch: 'main',
+      stagedSummary: 'A\tremote.txt',
+      stagedPatch: '+remote'
+    }
+    const params = { agentId: 'custom', model: '', customAgentCommand: 'agent' }
+    const executeCommitMessagePlan = vi.fn()
+    const prepareForCodexLaunch = vi.fn(() => '/managed/codex-home')
+    const prepareForClaudeLaunch = vi.fn()
+    resolveCommitMessageSettingsMock.mockReturnValue({ ok: true, params })
+    getSshGitProviderMock.mockReturnValue({
+      getStagedCommitContext: vi.fn().mockResolvedValue(context),
+      executeCommitMessagePlan
+    })
+    generateCommitMessageFromContextMock.mockResolvedValue({
+      success: true,
+      message: 'Add remote file'
+    })
+
+    registerFilesystemHandlers(store as never, {
+      prepareForCodexLaunch,
+      prepareForClaudeLaunch
+    })
+
+    await expect(
+      handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: '/remote/repo',
+        connectionId: 'conn-1'
+      })
+    ).resolves.toEqual({ success: true, message: 'Add remote file' })
+
+    expect(generateCommitMessageFromContextMock).toHaveBeenCalledWith(
+      context,
+      params,
+      expect.objectContaining({
+        kind: 'remote',
+        cwd: '/remote/repo',
+        missingBinaryLocation: 'remote PATH'
+      })
+    )
+    const target = generateCommitMessageFromContextMock.mock.calls[0]?.[2]
+    await target.execute(
+      { binary: 'agent', args: [], stdinPayload: null, label: 'agent' },
+      '/cwd',
+      1
+    )
+    expect(executeCommitMessagePlan).toHaveBeenCalledWith(
+      { binary: 'agent', args: [], stdinPayload: null, label: 'agent' },
+      '/cwd',
+      1
+    )
+    expect(prepareForCodexLaunch).not.toHaveBeenCalled()
+    expect(prepareForClaudeLaunch).not.toHaveBeenCalled()
+  })
+
+  it('does not call the generator when no staged changes exist', async () => {
+    resolveCommitMessageSettingsMock.mockReturnValue({
+      ok: true,
+      params: { agentId: 'codex', model: 'gpt-5.4-mini' }
+    })
+    getStagedCommitContextMock.mockResolvedValue(null)
+
+    registerFilesystemHandlers(store as never)
+
+    await expect(
+      handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: WORKTREE_FEATURE_PATH
+      })
+    ).resolves.toEqual({ success: false, error: 'No staged changes to summarize.' })
+
+    expect(generateCommitMessageFromContextMock).not.toHaveBeenCalled()
+  })
+
+  it('sanitizes local staged-context read failures before returning to the renderer', async () => {
+    resolveCommitMessageSettingsMock.mockReturnValue({
+      ok: true,
+      params: { agentId: 'codex', model: 'gpt-5.4-mini' }
+    })
+    getStagedCommitContextMock.mockRejectedValue(new Error('fatal: /secret/repo failed'))
+
+    registerFilesystemHandlers(store as never)
+
+    await expect(
+      handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: WORKTREE_FEATURE_PATH
+      })
+    ).resolves.toEqual({ success: false, error: 'Failed to read staged changes.' })
+
+    expect(generateCommitMessageFromContextMock).not.toHaveBeenCalled()
+  })
+
+  it('sanitizes SSH staged-context read failures before returning to the renderer', async () => {
+    resolveCommitMessageSettingsMock.mockReturnValue({
+      ok: true,
+      params: { agentId: 'codex', model: 'gpt-5.4-mini' }
+    })
+    getSshGitProviderMock.mockReturnValue({
+      getStagedCommitContext: vi.fn().mockRejectedValue(new Error('fatal: /remote/secret failed'))
+    })
+
+    registerFilesystemHandlers(store as never)
+
+    await expect(
+      handlers.get('git:generateCommitMessage')!(null, {
+        worktreePath: '/remote/repo',
+        connectionId: 'conn-1'
+      })
+    ).resolves.toEqual({ success: false, error: 'Failed to read staged changes.' })
+
+    expect(generateCommitMessageFromContextMock).not.toHaveBeenCalled()
+  })
+
   it('routes ssh git:commit through the SSH provider instead of local commitChanges', async () => {
     const sshCommitMock = vi.fn().mockResolvedValue({ success: true })
     getSshGitProviderMock.mockReturnValue({ commit: sshCommitMock })
diff --git a/src/main/ipc/filesystem.ts b/src/main/ipc/filesystem.ts
index 817668dec74..f35adbca549 100644
--- a/src/main/ipc/filesystem.ts
+++ b/src/main/ipc/filesystem.ts
@@ -37,9 +37,16 @@ import {
   bulkUnstageFiles,
   bulkDiscardChanges,
   discardChanges,
+  getStagedCommitContext,
   getBranchCompare,
   getBranchDiff
 } from '../git/status'
+import {
+  cancelGenerateCommitMessageLocal,
+  generateCommitMessageFromContext,
+  resolveCommitMessageSettings,
+  type GenerateCommitMessageResult
+} from '../text-generation/commit-message-text-generation'
 import { getUpstreamStatus } from '../git/upstream'
 import { gitFetch, gitPull, gitPush } from '../git/remote'
 import { assertGitPushTargetShape } from '../../shared/git-push-target-validation'
@@ -59,6 +66,8 @@ import { listMarkdownDocuments, markdownDocumentsFromRelativePaths } from './mar
 import { checkRgAvailable } from './rg-availability'
 import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
 import { getSshGitProvider } from '../providers/ssh-git-dispatch'
+import type { ClaudeRuntimeAuthPreparation } from '../claude-accounts/runtime-auth-service'
+import { applyClaudeEnvPatch } from '../claude-accounts/environment'
 
 // Why: Monaco has large-file optimizations like VS Code; blocking at 5MB makes
 // ordinary JSON/log files inaccessible before the editor can degrade features.
@@ -84,6 +93,56 @@ const PREVIEWABLE_BINARY_MIME_TYPES: Record<string, string> = {
   '.pdf': 'application/pdf'
 }
 
+export type CommitMessageAgentEnvironmentResolvers = {
+  prepareForCodexLaunch?: () => string | null
+  prepareForClaudeLaunch?: () => Promise<ClaudeRuntimeAuthPreparation>
+}
+
+function cloneProcessEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) {
+      env[key] = value
+    }
+  }
+  return env
+}
+
+async function prepareLocalCommitMessageAgentEnv(
+  agentId: string,
+  resolvers: CommitMessageAgentEnvironmentResolvers | undefined
+): Promise<{ ok: true; env?: NodeJS.ProcessEnv } | { ok: false; error: string }> {
+  if (!resolvers) {
+    return { ok: true }
+  }
+
+  try {
+    if (agentId === 'codex' && resolvers.prepareForCodexLaunch) {
+      const codexHomePath = resolvers.prepareForCodexLaunch()
+      return {
+        ok: true,
+        env: codexHomePath ? { ...cloneProcessEnv(), CODEX_HOME: codexHomePath } : undefined
+      }
+    }
+
+    if (agentId === 'claude' && resolvers.prepareForClaudeLaunch) {
+      const preparation = await resolvers.prepareForClaudeLaunch()
+      const env = applyClaudeEnvPatch(cloneProcessEnv(), preparation.envPatch, {
+        stripAuthEnv: preparation.stripAuthEnv
+      })
+      return { ok: true, env }
+    }
+  } catch (error) {
+    console.error('[filesystem] Failed to prepare commit message agent environment:', error)
+    return {
+      ok: false,
+      error: 'Failed to prepare the selected agent account for commit message generation.'
+    }
+  }
+
+  return { ok: true }
+}
+
 /**
  * Check if a buffer appears to be binary (contains null bytes in first 8KB).
  */
@@ -129,7 +188,10 @@ async function isDirectoryEntry(
   }
 }
 
-export function registerFilesystemHandlers(store: Store): void {
+export function registerFilesystemHandlers(
+  store: Store,
+  commitMessageAgentEnv?: CommitMessageAgentEnvironmentResolvers
+): void {
   const activeTextSearches = new Map<string, ChildProcess>()
 
   // ─── Filesystem ─────────────────────────────────────────
@@ -557,6 +619,93 @@ export function registerFilesystemHandlers(store: Store): void {
     }
   )
 
+  ipcMain.handle(
+    'git:generateCommitMessage',
+    async (
+      _event,
+      args: {
+        worktreePath: string
+        connectionId?: string
+      }
+    ): Promise<GenerateCommitMessageResult> => {
+      const resolvedSettings = resolveCommitMessageSettings(store.getSettings())
+      if (!resolvedSettings.ok) {
+        return { success: false, error: resolvedSettings.error }
+      }
+      if (args.connectionId) {
+        const provider = getSshGitProvider(args.connectionId)
+        if (!provider) {
+          return {
+            success: false,
+            error: `No git provider for connection "${args.connectionId}"`
+          }
+        }
+        let context
+        try {
+          context = await provider.getStagedCommitContext(args.worktreePath)
+        } catch (error) {
+          console.error('[filesystem] Failed to read remote staged commit context:', error)
+          return {
+            success: false,
+            error: 'Failed to read staged changes.'
+          }
+        }
+        if (!context) {
+          return { success: false, error: 'No staged changes to summarize.' }
+        }
+        return generateCommitMessageFromContext(context, resolvedSettings.params, {
+          kind: 'remote',
+          cwd: args.worktreePath,
+          execute: (plan, cwd, timeoutMs) =>
+            provider.executeCommitMessagePlan(plan, cwd, timeoutMs),
+          missingBinaryLocation: 'remote PATH'
+        })
+      }
+      const worktreePath = await resolveRegisteredWorktreePath(args.worktreePath, store)
+      let context
+      try {
+        context = await getStagedCommitContext(worktreePath)
+      } catch (error) {
+        console.error('[filesystem] Failed to read staged commit context:', error)
+        return {
+          success: false,
+          error: 'Failed to read staged changes.'
+        }
+      }
+      if (!context) {
+        return { success: false, error: 'No staged changes to summarize.' }
+      }
+      const localEnv = await prepareLocalCommitMessageAgentEnv(
+        resolvedSettings.params.agentId,
+        commitMessageAgentEnv
+      )
+      if (!localEnv.ok) {
+        return { success: false, error: localEnv.error }
+      }
+      return generateCommitMessageFromContext(context, resolvedSettings.params, {
+        kind: 'local',
+        cwd: worktreePath,
+        ...(localEnv.env ? { env: localEnv.env } : {})
+      })
+    }
+  )
+
+  ipcMain.handle(
+    'git:cancelGenerateCommitMessage',
+    async (_event, args: { worktreePath: string; connectionId?: string }): Promise<void> => {
+      if (args.connectionId) {
+        const provider = getSshGitProvider(args.connectionId)
+        if (!provider) {
+          return
+        }
+        await provider.cancelGenerateCommitMessage(args.worktreePath)
+        return
+      }
+      const worktreePath = await resolveRegisteredWorktreePath(args.worktreePath, store)
+      cancelGenerateCommitMessageLocal(worktreePath)
+    }
+  )
+
   ipcMain.handle(
     'git:branchCompare',
     async (
diff --git a/src/main/ipc/register-core-handlers.ts b/src/main/ipc/register-core-handlers.ts
index 74c08a40f69..2bfb4c71d86 100644
--- a/src/main/ipc/register-core-handlers.ts
+++ b/src/main/ipc/register-core-handlers.ts
@@ -4,7 +4,10 @@ import { registerPreflightHandlers } from './preflight'
 import type { Store } from '../persistence'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
 import type { StatsCollector } from '../stats/collector'
-import { registerFilesystemHandlers } from './filesystem'
+import {
+  registerFilesystemHandlers,
+  type CommitMessageAgentEnvironmentResolvers
+} from './filesystem'
 import { registerFilesystemWatcherHandlers } from './filesystem-watcher'
 import { registerClaudeUsageHandlers } from './claude-usage'
 import { registerCodexUsageHandlers } from './codex-usage'
@@ -65,7 +68,8 @@ export function registerCoreHandlers(
   claudeAccounts: ClaudeAccountService,
   rateLimits: RateLimitService,
   mainWindowWebContentsId: number | null = null,
-  automations?: AutomationService
+  automations?: AutomationService,
+  commitMessageAgentEnv?: CommitMessageAgentEnvironmentResolvers
 ): void {
   // Why: on macOS the app can stay alive after all windows close, then
   // openMainWindow() is called again on 'activate'. ipcMain.handle() throws
@@ -118,7 +122,11 @@ export function registerCoreHandlers(
   registerSessionHandlers(store)
   registerUIHandlers(store)
   registerWorkspaceSpaceHandlers(store)
-  registerFilesystemHandlers(store)
+  if (commitMessageAgentEnv) {
+    registerFilesystemHandlers(store, commitMessageAgentEnv)
+  } else {
+    registerFilesystemHandlers(store)
+  }
   registerFilesystemWatcherHandlers()
   registerRuntimeHandlers(runtime)
   registerRuntimeEnvironmentHandlers()
diff --git a/src/main/providers/ssh-git-dispatch.ts b/src/main/providers/ssh-git-dispatch.ts
index b4e462a3af1..74afe7700fc 100644
--- a/src/main/providers/ssh-git-dispatch.ts
+++ b/src/main/providers/ssh-git-dispatch.ts
@@ -1,8 +1,8 @@
-import type { IGitProvider } from './types'
+import type { SshGitProvider } from './ssh-git-provider'
 
-const sshProviders = new Map<string, IGitProvider>()
+const sshProviders = new Map<string, SshGitProvider>()
 
-export function registerSshGitProvider(connectionId: string, provider: IGitProvider): void {
+export function registerSshGitProvider(connectionId: string, provider: SshGitProvider): void {
   sshProviders.set(connectionId, provider)
 }
 
@@ -10,6 +10,6 @@ export function unregisterSshGitProvider(connectionId: string): void {
   sshProviders.delete(connectionId)
 }
 
-export function getSshGitProvider(connectionId: string): IGitProvider | undefined {
+export function getSshGitProvider(connectionId: string): SshGitProvider | undefined {
   return sshProviders.get(connectionId)
 }
diff --git a/src/main/providers/ssh-git-provider.test.ts b/src/main/providers/ssh-git-provider.test.ts
index 5643c3c2d29..636fa229d60 100644
--- a/src/main/providers/ssh-git-provider.test.ts
+++ b/src/main/providers/ssh-git-provider.test.ts
@@ -54,6 +54,82 @@ describe('SshGitProvider', () => {
     expect(result).toEqual(commitResult)
   })
 
+  it('getStagedCommitContext reads branch, staged summary, and staged patch remotely', async () => {
+    mux.request.mockImplementation(async (method, payload) => {
+      expect(method).toBe('git.exec')
+      if (payload.args[1] === '--show-current') {
+        return { stdout: 'feature/ai-commit\n' }
+      }
+      if (payload.args[2] === '--name-status') {
+        return { stdout: 'M\tREADME.md\n' }
+      }
+      if (payload.args[2] === '--patch') {
+        return { stdout: 'diff --git a/README.md b/README.md\n+hello' }
+      }
+      throw new Error(`unexpected args: ${payload.args.join(' ')}`)
+    })
+
+    const result = await provider.getStagedCommitContext('/home/user/repo')
+
+    expect(result).toEqual({
+      branch: 'feature/ai-commit',
+      stagedSummary: 'M\tREADME.md',
+      stagedPatch: 'diff --git a/README.md b/README.md\n+hello'
+    })
+    expect(mux.request).toHaveBeenCalledWith('git.exec', {
+      args: ['diff', '--cached', '--patch', '--minimal', '--no-color', '--no-ext-diff'],
+      cwd: '/home/user/repo'
+    })
+  })
+
+  it('getStagedCommitContext returns null when nothing is staged', async () => {
+    mux.request.mockImplementation(async (_method, payload) => {
+      if (payload.args[1] === '--show-current') {
+        return { stdout: 'main\n' }
+      }
+      return { stdout: '' }
+    })
+
+    await expect(provider.getStagedCommitContext('/home/user/repo')).resolves.toBeNull()
+    expect(mux.request).toHaveBeenCalledTimes(2)
+  })
+
+  it('executeCommitMessagePlan delegates the prepared plan to the relay', async () => {
+    const execResult = {
+      stdout: 'Update docs',
+      stderr: '',
+      exitCode: 0,
+      timedOut: false
+    }
+    mux.request.mockResolvedValue(execResult)
+
+    const result = await provider.executeCommitMessagePlan(
+      {
+        binary: 'codex',
+        args: ['exec', 'PROMPT'],
+        stdinPayload: null,
+        label: 'Codex'
+      },
+      '/home/user/repo',
+      60_000
+    )
+
+    expect(mux.request).toHaveBeenCalledWith('agent.execNonInteractive', {
+      binary: 'codex',
+      args: ['exec', 'PROMPT'],
+      cwd: '/home/user/repo',
+      stdin: null,
+      timeoutMs: 60_000
+    })
+    expect(result).toEqual(execResult)
+  })
+
+  it('cancelGenerateCommitMessage sends best-effort relay cancellation', async () => {
+    await provider.cancelGenerateCommitMessage('/home/user/repo')
+
+    expect(mux.request).toHaveBeenCalledWith('agent.cancelExec', { cwd: '/home/user/repo' })
+  })
+
   it('getDiff sends git.diff request', async () => {
     const diffResult = { kind: 'text', originalContent: '', modifiedContent: 'hello' }
     mux.request.mockResolvedValue(diffResult)
diff --git a/src/main/providers/ssh-git-provider.ts b/src/main/providers/ssh-git-provider.ts
index 45dec93c79b..e73e92f7658 100644
--- a/src/main/providers/ssh-git-provider.ts
+++ b/src/main/providers/ssh-git-provider.ts
@@ -1,3 +1,7 @@
+/* eslint-disable max-lines -- Why: this provider mirrors IGitProvider one
+   method per RPC call (~16 methods). Splitting it would only add
+   indirection — every method is a 1:1 forwarder to a relay RPC plus a
+   small amount of param plumbing. */
 import type { SshChannelMultiplexer } from '../ssh/ssh-channel-multiplexer'
 import type { IGitProvider } from './types'
 import hostedGitInfo from 'hosted-git-info'
@@ -10,6 +14,9 @@ import type {
   GitUpstreamStatus,
   GitWorktreeInfo
 } from '../../shared/types'
+import type { CommitMessageDraftContext } from '../../shared/commit-message-generation'
+import type { CommitMessagePlan } from '../../shared/commit-message-plan'
+import type { RemoteCommitMessageExecResult } from '../text-generation/commit-message-text-generation'
 
 export class SshGitProvider implements IGitProvider {
   private connectionId: string
@@ -38,6 +45,54 @@ export class SshGitProvider implements IGitProvider {
     })) as { success: boolean; error?: string }
   }
 
+  async getStagedCommitContext(worktreePath: string): Promise<CommitMessageDraftContext | null> {
+    const branchPromise = this.exec(['branch', '--show-current'], worktreePath).catch(() => ({
+      stdout: ''
+    }))
+    const [branchResult, summaryResult] = await Promise.all([
+      branchPromise,
+      this.exec(['diff', '--cached', '--name-status'], worktreePath)
+    ])
+    const stagedSummary = summaryResult.stdout.trim()
+    if (!stagedSummary) {
+      return null
+    }
+    const { stdout: stagedPatch } = await this.exec(
+      ['diff', '--cached', '--patch', '--minimal', '--no-color', '--no-ext-diff'],
+      worktreePath
+    )
+    return {
+      branch: branchResult.stdout.trim() || null,
+      stagedSummary,
+      stagedPatch
+    }
+  }
+
+  async executeCommitMessagePlan(
+    plan: CommitMessagePlan,
+    cwd: string,
+    timeoutMs: number
+  ): Promise<RemoteCommitMessageExecResult> {
+    return (await this.mux.request('agent.execNonInteractive', {
+      binary: plan.binary,
+      args: plan.args,
+      cwd,
+      stdin: plan.stdinPayload,
+      timeoutMs
+    })) as RemoteCommitMessageExecResult
+  }
+
+  async cancelGenerateCommitMessage(worktreePath: string): Promise<void> {
+    // Why: best-effort — the relay returns `{canceled: false}` when there is
+    // nothing in flight. Callers should not block UI updates on this.
+    try {
+      await this.mux.request('agent.cancelExec', { cwd: worktreePath })
+    } catch {
+      // Swallow: cancellation is a fire-and-forget user intent. The pending
+      // generateCommitMessage promise will still resolve with the kill result.
+    }
+  }
+
   async getDiff(
     worktreePath: string,
     filePath: string,
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index 3e091ea1f76..da8e8758ac6 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -11,6 +11,7 @@ import type {
   SearchOptions,
   SearchResult
 } from '../../shared/types'
+import type { CommitMessageDraftContext } from '../../shared/commit-message-generation'
 import type { WorkspaceSpaceDirectoryScanResult } from '../../shared/workspace-space-types'
 
 // ─── PTY Provider ───────────────────────────────────────────────────
@@ -143,6 +144,7 @@ export type IFilesystemProvider = {
 export type IGitProvider = {
   getStatus(worktreePath: string): Promise<GitStatusResult>
   commit(worktreePath: string, message: string): Promise<{ success: boolean; error?: string }>
+  getStagedCommitContext(worktreePath: string): Promise<CommitMessageDraftContext | null>
   getDiff(
     worktreePath: string,
     filePath: string,
diff --git a/src/main/text-generation/commit-message-text-generation.test.ts b/src/main/text-generation/commit-message-text-generation.test.ts
new file mode 100644
index 00000000000..77665b8991b
--- /dev/null
+++ b/src/main/text-generation/commit-message-text-generation.test.ts
@@ -0,0 +1,473 @@
+/* eslint-disable max-lines -- Why: local/remote generation, cancellation, and
+   env propagation share subprocess mocks; splitting would obscure the
+   cross-path invariants these tests protect. */
+import { spawn } from 'child_process'
+import type * as ChildProcess from 'child_process'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getDefaultSettings } from '../../shared/constants'
+import {
+  applyOrcaAttribution,
+  generateCommitMessageFromContext,
+  resolveCommitMessageSettings
+} from './commit-message-text-generation'
+
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof ChildProcess>()
+  return {
+    ...actual,
+    spawn: vi.fn(actual.spawn)
+  }
+})
+
+const spawnMock = vi.mocked(spawn)
+
+function withPlatform<T>(platform: NodeJS.Platform, fn: () => T): T {
+  const original = process.platform
+  Object.defineProperty(process, 'platform', { configurable: true, value: platform })
+  try {
+    return fn()
+  } finally {
+    Object.defineProperty(process, 'platform', { configurable: true, value: original })
+  }
+}
+
+beforeEach(() => {
+  spawnMock.mockClear()
+})
+
+describe('resolveCommitMessageSettings', () => {
+  it('falls back to the agent default model when a persisted model is stale', () => {
+    const settings = getDefaultSettings('/tmp')
+    settings.enableGitHubAttribution = true
+    settings.commitMessageAi = {
+      enabled: true,
+      agentId: 'codex',
+      selectedModelByAgent: { codex: 'retired-model' },
+      selectedThinkingByModel: {},
+      customPrompt: 'Use Conventional Commits.',
+      customAgentCommand: ''
+    }
+
+    const result = resolveCommitMessageSettings(settings)
+
+    expect(result).toEqual({
+      ok: true,
+      params: {
+        agentId: 'codex',
+        model: 'gpt-5.4-mini',
+        thinkingLevel: 'low',
+        customPrompt: 'Use Conventional Commits.',
+        attributionEnabled: true
+      }
+    })
+  })
+
+  it('falls back to the model default thinking level when a persisted level is stale', () => {
+    const settings = getDefaultSettings('/tmp')
+    settings.commitMessageAi = {
+      enabled: true,
+      agentId: 'codex',
+      selectedModelByAgent: { codex: 'gpt-5.5' },
+      selectedThinkingByModel: { 'gpt-5.5': 'turbo' },
+      customPrompt: '',
+      customAgentCommand: ''
+    }
+
+    const result = resolveCommitMessageSettings(settings)
+
+    expect(result).toMatchObject({
+      ok: true,
+      params: {
+        agentId: 'codex',
+        model: 'gpt-5.5',
+        thinkingLevel: 'low'
+      }
+    })
+  })
+
+  it('passes the per-agent command override into non-interactive planning', () => {
+    const settings = getDefaultSettings('/tmp')
+    settings.agentCmdOverrides.codex = 'npx codex'
+    settings.commitMessageAi = {
+      enabled: true,
+      agentId: 'codex',
+      selectedModelByAgent: { codex: 'gpt-5.4-mini' },
+      selectedThinkingByModel: {},
+      customPrompt: '',
+      customAgentCommand: ''
+    }
+
+    const result = resolveCommitMessageSettings(settings)
+
+    expect(result).toMatchObject({
+      ok: true,
+      params: {
+        agentId: 'codex',
+        agentCommandOverride: 'npx codex'
+      }
+    })
+  })
+
+  it('requires a non-empty custom command for custom agents', () => {
+    const settings = getDefaultSettings('/tmp')
+    settings.commitMessageAi = {
+      enabled: true,
+      agentId: 'custom',
+      selectedModelByAgent: {},
+      selectedThinkingByModel: {},
+      customPrompt: '',
+      customAgentCommand: '   '
+    }
+
+    expect(resolveCommitMessageSettings(settings)).toEqual({
+      ok: false,
+      error: 'Custom command is empty. Add one in Settings -> Git -> AI Commit Messages.'
+    })
+  })
+})
+
+describe('generateCommitMessageFromContext', () => {
+  it('uses a prepared remote execution plan instead of running git on the remote side', async () => {
+    const result = await generateCommitMessageFromContext(
+      {
+        branch: 'main',
+        stagedSummary: 'M\tREADME.md',
+        stagedPatch: '+hello'
+      },
+      {
+        agentId: 'custom',
+        model: '',
+        customAgentCommand: 'agent --message {prompt}'
+      },
+      {
+        kind: 'remote',
+        cwd: '/repo',
+        missingBinaryLocation: 'remote PATH',
+        execute: async (plan, cwd, timeoutMs) => {
+          expect(cwd).toBe('/repo')
+          expect(timeoutMs).toBe(60_000)
+          expect(plan.binary).toBe('agent')
+          expect(plan.args).toHaveLength(2)
+          expect(plan.args[0]).toBe('--message')
+          expect(plan.args[1]).toContain('Staged files:\nM\tREADME.md')
+          return {
+            stdout: 'Add README note.\n',
+            stderr: '',
+            exitCode: 0,
+            timedOut: false
+          }
+        }
+      }
+    )
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Add README note',
+      agentLabel: 'agent'
+    })
+  })
+
+  it('does not fall back to raw agent stdout or stderr on failures', async () => {
+    const result = await generateCommitMessageFromContext(
+      {
+        branch: 'main',
+        stagedSummary: 'M\tREADME.md',
+        stagedPatch: '+hello'
+      },
+      {
+        agentId: 'custom',
+        model: '',
+        customAgentCommand: 'agent'
+      },
+      {
+        kind: 'remote',
+        cwd: '/repo',
+        missingBinaryLocation: 'remote PATH',
+        execute: async () => ({
+          stdout: 'You are generating a single git commit message for /secret/repo',
+          stderr: 'raw failure output with /secret/repo',
+          exitCode: 1,
+          timedOut: false
+        })
+      }
+    )
+
+    expect(result).toEqual({
+      success: false,
+      error: 'agent failed. Check the agent CLI configuration and try again.'
+    })
+  })
+
+  it('does not expose extracted agent error details to the renderer', async () => {
+    const result = await generateCommitMessageFromContext(
+      {
+        branch: 'main',
+        stagedSummary: 'M\tREADME.md',
+        stagedPatch: '+hello'
+      },
+      {
+        agentId: 'custom',
+        model: '',
+        customAgentCommand: 'agent'
+      },
+      {
+        kind: 'remote',
+        cwd: '/repo',
+        missingBinaryLocation: 'remote PATH',
+        execute: async () => ({
+          stdout: 'ERROR: fatal: /secret/repo/config failed',
+          stderr: '',
+          exitCode: 1,
+          timedOut: false
+        })
+      }
+    )
+
+    expect(result).toEqual({
+      success: false,
+      error: 'agent failed. Check the agent CLI configuration and try again.'
+    })
+  })
+
+  it('preserves the structured subject and body when formatting the final response', async () => {
+    const result = await generateCommitMessageFromContext(
+      {
+        branch: 'main',
+        stagedSummary: 'M\tREADME.md',
+        stagedPatch: '+hello'
+      },
+      {
+        agentId: 'custom',
+        model: '',
+        customAgentCommand: 'agent',
+        attributionEnabled: true
+      },
+      {
+        kind: 'remote',
+        cwd: '/repo',
+        missingBinaryLocation: 'remote PATH',
+        execute: async () => ({
+          stdout: 'Update README.\n\n- Explain the generated commit-message flow\n',
+          stderr: '',
+          exitCode: 0,
+          timedOut: false
+        })
+      }
+    )
+
+    expect(result).toEqual({
+      success: true,
+      message:
+        'Update README\n\n- Explain the generated commit-message flow\n\nCo-authored-by: Orca <help@stably.ai>',
+      agentLabel: 'agent'
+    })
+  })
+
+  it('sanitizes remote execution transport failures', async () => {
+    const result = await generateCommitMessageFromContext(
+      {
+        branch: 'main',
+        stagedSummary: 'M\tREADME.md',
+        stagedPatch: '+hello'
+      },
+      {
+        agentId: 'custom',
+        model: '',
+        customAgentCommand: 'agent'
+      },
+      {
+        kind: 'remote',
+        cwd: '/repo',
+        missingBinaryLocation: 'remote PATH',
+        execute: async () => {
+          throw new Error('relay disconnected while reading /secret/repo')
+        }
+      }
+    )
+
+    expect(result).toEqual({
+      success: false,
+      error:
+        'agent could not be reached on the remote PATH. Try again after the SSH connection recovers.'
+    })
+  })
+
+  it('caps local agent output before buffering unbounded data', async () => {
+    const listeners = new Map<string, (value: unknown) => void>()
+    const child = {
+      pid: 123,
+      kill: vi.fn(),
+      stdout: { on: vi.fn((event, callback) => listeners.set(`stdout:${event}`, callback)) },
+      stderr: { on: vi.fn((event, callback) => listeners.set(`stderr:${event}`, callback)) },
+      stdin: { end: vi.fn() },
+      on: vi.fn((event, callback) => listeners.set(event, callback))
+    }
+    spawnMock.mockReturnValue(child as never)
+
+    const pending = generateCommitMessageFromContext(
+      {
+        branch: 'main',
+        stagedSummary: 'M\tREADME.md',
+        stagedPatch: '+hello'
+      },
+      {
+        agentId: 'custom',
+        model: '',
+        customAgentCommand: 'agent'
+      },
+      {
+        kind: 'local',
+        cwd: '/repo'
+      }
+    )
+
+    listeners.get('stdout:data')?.(Buffer.alloc(4 * 1024 * 1024 + 1))
+    listeners.get('close')?.(null)
+
+    await expect(pending).resolves.toEqual({
+      success: false,
+      error: 'agent failed. Check the agent CLI configuration and try again.'
+    })
+    expect(child.kill).toHaveBeenCalledWith('SIGKILL')
+  })
+
+  it('passes prepared provider environment to local agent subprocesses', async () => {
+    const listeners = new Map<string, (value: unknown) => void>()
+    const child = {
+      pid: 123,
+      kill: vi.fn(),
+      stdout: { on: vi.fn((event, callback) => listeners.set(`stdout:${event}`, callback)) },
+      stderr: { on: vi.fn((event, callback) => listeners.set(`stderr:${event}`, callback)) },
+      stdin: { end: vi.fn() },
+      on: vi.fn((event, callback) => listeners.set(event, callback))
+    }
+    spawnMock.mockReturnValue(child as never)
+
+    const pending = generateCommitMessageFromContext(
+      {
+        branch: 'main',
+        stagedSummary: 'M\tREADME.md',
+        stagedPatch: '+hello'
+      },
+      {
+        agentId: 'custom',
+        model: '',
+        customAgentCommand: 'orca-test-agent-nope'
+      },
+      {
+        kind: 'local',
+        cwd: '/repo',
+        env: { ...process.env, CODEX_HOME: '/managed/codex-home' }
+      }
+    )
+
+    listeners.get('stdout:data')?.(Buffer.from('Add README note\n'))
+    listeners.get('close')?.(0)
+
+    await expect(pending).resolves.toMatchObject({
+      success: true,
+      message: 'Add README note'
+    })
+    expect(spawnMock).toHaveBeenCalledWith(
+      'orca-test-agent-nope',
+      [],
+      expect.objectContaining({
+        env: expect.objectContaining({ CODEX_HOME: '/managed/codex-home' })
+      })
+    )
+  })
+
+  it('routes Windows batch-script agent commands through cmd.exe', async () => {
+    const originalComSpec = process.env.ComSpec
+    process.env.ComSpec = 'C:\\Windows\\System32\\cmd.exe'
+    try {
+      await withPlatform('win32', async () => {
+        const listeners = new Map<string, (value: unknown) => void>()
+        const child = {
+          pid: 123,
+          kill: vi.fn(),
+          stdout: { on: vi.fn((event, callback) => listeners.set(`stdout:${event}`, callback)) },
+          stderr: { on: vi.fn((event, callback) => listeners.set(`stderr:${event}`, callback)) },
+          stdin: { end: vi.fn() },
+          on: vi.fn((event, callback) => listeners.set(event, callback))
+        }
+        spawnMock.mockReturnValue(child as never)
+
+        const pending = generateCommitMessageFromContext(
+          {
+            branch: 'main',
+            stagedSummary: 'M\tREADME.md',
+            stagedPatch: '+hello'
+          },
+          {
+            agentId: 'custom',
+            model: '',
+            customAgentCommand: 'C:/tools/agent.cmd'
+          },
+          {
+            kind: 'local',
+            cwd: 'C:\\repo'
+          }
+        )
+
+        listeners.get('stdout:data')?.(Buffer.from('Update README\n'))
+        listeners.get('close')?.(0)
+
+        await expect(pending).resolves.toMatchObject({
+          success: true,
+          message: 'Update README'
+        })
+        expect(spawnMock).toHaveBeenCalledWith(
+          'C:\\Windows\\System32\\cmd.exe',
+          ['/d', '/s', '/c', '"C:/tools/agent.cmd"'],
+          expect.objectContaining({
+            cwd: 'C:\\repo',
+            windowsHide: true
+          })
+        )
+      })
+    } finally {
+      if (originalComSpec === undefined) {
+        delete process.env.ComSpec
+      } else {
+        process.env.ComSpec = originalComSpec
+      }
+    }
+  })
+
+  it('rejects unsafe argv prompts for Windows batch-script agent commands', async () => {
+    await withPlatform('win32', async () => {
+      const result = await generateCommitMessageFromContext(
+        {
+          branch: 'main',
+          stagedSummary: 'M\tREADME.md',
+          stagedPatch: '+hello & goodbye'
+        },
+        {
+          agentId: 'custom',
+          model: '',
+          customAgentCommand: 'C:/tools/agent.cmd {prompt}'
+        },
+        {
+          kind: 'local',
+          cwd: 'C:\\repo'
+        }
+      )
+
+      expect(result).toEqual({
+        success: false,
+        error:
+          'C:/tools/agent.cmd cannot be run as a Windows batch command with the prompt in argv. Remove {prompt} so Orca sends the prompt on stdin.'
+      })
+      expect(spawnMock).not.toHaveBeenCalled()
+    })
+  })
+})
+
+describe('applyOrcaAttribution', () => {
+  it('does not duplicate the Orca trailer', () => {
+    const message = applyOrcaAttribution('Update docs', true)
+
+    expect(applyOrcaAttribution(message, true)).toBe(message)
+  })
+})
diff --git a/src/main/text-generation/commit-message-text-generation.ts b/src/main/text-generation/commit-message-text-generation.ts
new file mode 100644
index 00000000000..e056270f8ca
--- /dev/null
+++ b/src/main/text-generation/commit-message-text-generation.ts
@@ -0,0 +1,450 @@
+/* eslint-disable max-lines -- Why: local and SSH generation share cancellation,
+   spawn failure handling, and output normalization; keeping them together
+   prevents those paths from drifting. */
+import { exec, spawn, type ChildProcess } from 'child_process'
+import type { GlobalSettings, TuiAgent } from '../../shared/types'
+import {
+  buildCommitMessagePrompt,
+  splitGeneratedCommitMessage,
+  type CommitMessageDraftContext,
+  type GeneratedCommitMessage
+} from '../../shared/commit-message-generation'
+import {
+  cleanGeneratedCommitMessage,
+  extractAgentErrorMessage
+} from '../../shared/commit-message-prompt'
+import {
+  CUSTOM_AGENT_ID,
+  DEFAULT_COMMIT_MESSAGE_AGENT_ID,
+  getCommitMessageAgentSpec,
+  getCommitMessageModel,
+  isCustomAgentId
+} from '../../shared/commit-message-agent-spec'
+import {
+  planCommitMessageGeneration,
+  type CommitMessagePlan
+} from '../../shared/commit-message-plan'
+import { ORCA_GIT_COMMIT_TRAILER } from '../../shared/orca-attribution'
+import { resolveCliCommand } from '../codex-cli/command'
+import {
+  getSpawnArgsForWindows,
+  UnsafeWindowsBatchArgumentsError,
+  WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR
+} from '../win32-utils'
+
+const GENERATION_TIMEOUT_MS = 60_000
+const MAX_AGENT_OUTPUT_BYTES = 4 * 1024 * 1024
+
+export type GenerateCommitMessageParams = {
+  agentId: TuiAgent | 'custom'
+  model: string
+  thinkingLevel?: string
+  customPrompt?: string
+  customAgentCommand?: string
+  agentCommandOverride?: string
+  /** When true, append `Co-authored-by: Orca ...` after the cleaned message. */
+  attributionEnabled?: boolean
+}
+
+export type GenerateCommitMessageResult =
+  | { success: true; message: string; agentLabel?: string }
+  | { success: false; error: string; canceled?: boolean }
+
+export type RemoteCommitMessageExecResult = {
+  stdout: string
+  stderr: string
+  exitCode: number | null
+  timedOut: boolean
+  canceled?: boolean
+  spawnError?: string
+}
+
+export type CommitMessageGenerationTarget =
+  | { kind: 'local'; cwd: string; env?: NodeJS.ProcessEnv }
+  | {
+      kind: 'remote'
+      cwd: string
+      execute: (
+        plan: CommitMessagePlan,
+        cwd: string,
+        timeoutMs: number
+      ) => Promise<RemoteCommitMessageExecResult>
+      missingBinaryLocation: string
+    }
+
+type ResolveCommitMessageSettingsResult =
+  | { ok: true; params: GenerateCommitMessageParams }
+  | { ok: false; error: string }
+
+type InternalCommitMessageGenerationResult =
+  | { success: true; commitMessage: GeneratedCommitMessage; agentLabel?: string }
+  | { success: false; error: string; canceled?: boolean }
+
+/** Appends the Orca trailer if the message does not already include it. */
+export function applyOrcaAttribution(message: string, enabled: boolean): string {
+  if (!enabled) {
+    // Why: trim trailing whitespace even on the no-attribution path so a
+    // stray "\n" from the agent's output never reaches the textarea as a
+    // visible blank line.
+    return message.replace(/\s+$/, '')
+  }
+  const stripped = message.replace(/\s+$/, '')
+  if (stripped.includes(ORCA_GIT_COMMIT_TRAILER)) {
+    return stripped
+  }
+  // Why: a blank line separates the trailer block from the body so `git
+  // interpret-trailers` and most parsers treat it as a real trailer instead
+  // of a paragraph continuation.
+  return `${stripped}\n\n${ORCA_GIT_COMMIT_TRAILER}`
+}
+
+export function resolveCommitMessageSettings(
+  settings: GlobalSettings
+): ResolveCommitMessageSettingsResult {
+  const config = settings.commitMessageAi
+  if (!config?.enabled || !config.agentId) {
+    return { ok: false, error: 'Enable AI commit messages and choose an agent in Settings -> Git.' }
+  }
+
+  if (isCustomAgentId(config.agentId)) {
+    const customAgentCommand = config.customAgentCommand.trim()
+    if (!customAgentCommand) {
+      return {
+        ok: false,
+        error: 'Custom command is empty. Add one in Settings -> Git -> AI Commit Messages.'
+      }
+    }
+    return {
+      ok: true,
+      params: {
+        agentId: CUSTOM_AGENT_ID,
+        model: '',
+        customPrompt: config.customPrompt,
+        customAgentCommand,
+        attributionEnabled: settings.enableGitHubAttribution === true
+      }
+    }
+  }
+
+  const agentId = config.agentId ?? DEFAULT_COMMIT_MESSAGE_AGENT_ID
+  const spec = getCommitMessageAgentSpec(agentId)
+  if (!spec) {
+    return { ok: false, error: `Agent "${agentId}" does not support AI commit messages.` }
+  }
+
+  const persistedModelId = config.selectedModelByAgent[agentId] ?? spec.defaultModelId
+  const model =
+    getCommitMessageModel(agentId, persistedModelId) ??
+    getCommitMessageModel(agentId, spec.defaultModelId)
+  if (!model) {
+    return { ok: false, error: `No model is available for ${spec.label}.` }
+  }
+
+  const persistedThinking = config.selectedThinkingByModel[model.id]
+  const thinkingLevel = model.thinkingLevels?.some((level) => level.id === persistedThinking)
+    ? persistedThinking
+    : model.defaultThinkingLevel
+
+  const agentCommandOverride = settings.agentCmdOverrides?.[agentId]?.trim()
+  return {
+    ok: true,
+    params: {
+      agentId,
+      model: model.id,
+      thinkingLevel,
+      customPrompt: config.customPrompt,
+      ...(agentCommandOverride ? { agentCommandOverride } : {}),
+      attributionEnabled: settings.enableGitHubAttribution === true
+    }
+  }
+}
+
+function sanitizeAgentFailureDetail(detail: string | null): string | null {
+  const trimmed = detail?.replace(/\p{Cc}+/gu, ' ').trim()
+  if (!trimmed) {
+    return null
+  }
+  return trimmed.length > 240 ? `${trimmed.slice(0, 240).trimEnd()}...` : trimmed
+}
+
+function userFacingAgentFailure(label: string): string {
+  return `${label} failed. Check the agent CLI configuration and try again.`
+}
+
+function userFacingUnsafeWindowsBatchArgs(label: string): string {
+  return `${label} cannot be run as a Windows batch command with the prompt in argv. Remove {prompt} so Orca sends the prompt on stdin.`
+}
+
+// Why: on Windows, npm-installed CLIs like `claude` and `codex` are usually
+// `.cmd` shims. We route those through cmd.exe so Node can launch them, and
+// `child.kill()` would only terminate the wrapper. `taskkill /T /F` walks the
+// process tree from the wrapper PID and force-kills every descendant, which is
+// what users expect when they hit "stop generating".
+function killProcessTree(child: ChildProcess): void {
+  const pid = child.pid
+  if (!pid) {
+    return
+  }
+  if (process.platform === 'win32') {
+    exec(`taskkill /pid ${pid} /T /F`, () => {
+      // Best-effort; the spawn's `close` listener fires once the tree exits.
+    })
+    return
+  }
+  try {
+    child.kill('SIGKILL')
+  } catch {
+    // The child may have already exited between the in-flight check and the
+    // kill - that race is benign and can be ignored.
+  }
+}
+
+// Keying by `local:${cwd}` keeps local cancellation independent from any SSH
+// worktree with the same remote path.
+const cancelTokensByLane = new Map<string, () => void>()
+
+function localLaneKey(cwd: string): string {
+  return `local:${cwd}`
+}
+
+export function cancelGenerateCommitMessageLocal(cwd: string): void {
+  cancelTokensByLane.get(localLaneKey(cwd))?.()
+}
+
+async function runLocalPlan(
+  plan: CommitMessagePlan,
+  cwd: string,
+  env: NodeJS.ProcessEnv | undefined
+): Promise<InternalCommitMessageGenerationResult> {
+  const { binary, args, stdinPayload, label } = plan
+  return new Promise((resolve) => {
+    let child: ChildProcess
+    try {
+      const spawnEnv = env ?? process.env
+      const resolvedBinary =
+        process.platform === 'win32'
+          ? resolveCliCommand(binary, { pathEnv: spawnEnv.PATH ?? spawnEnv.Path ?? null })
+          : binary
+      const { spawnCmd, spawnArgs } = getSpawnArgsForWindows(resolvedBinary, args)
+      child = spawn(spawnCmd, spawnArgs, {
+        cwd,
+        env: spawnEnv,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true
+      })
+    } catch (error) {
+      if (error instanceof UnsafeWindowsBatchArgumentsError) {
+        resolve({
+          success: false,
+          error: userFacingUnsafeWindowsBatchArgs(label)
+        })
+        return
+      }
+      console.error('[commit-message] Failed to spawn local generator:', error)
+      resolve({
+        success: false,
+        error: `${label} could not be started. Check the agent command in Settings and try again.`
+      })
+      return
+    }
+
+    let stdout = ''
+    let stderr = ''
+    let stdoutBytes = 0
+    let stderrBytes = 0
+    let outputLimitExceeded = false
+    let settled = false
+    let canceledByUser = false
+    const laneKey = localLaneKey(cwd)
+    const finalize = (result: InternalCommitMessageGenerationResult): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      cancelTokensByLane.delete(laneKey)
+      resolve(result)
+    }
+
+    cancelTokensByLane.set(laneKey, () => {
+      canceledByUser = true
+      killProcessTree(child)
+    })
+
+    const timer = setTimeout(() => {
+      killProcessTree(child)
+      finalize({
+        success: false,
+        error: `Generation timed out after ${GENERATION_TIMEOUT_MS / 1000}s.`
+      })
+    }, GENERATION_TIMEOUT_MS)
+
+    child.stdout?.on('data', (chunk: Buffer) => {
+      stdoutBytes += chunk.byteLength
+      if (stdoutBytes > MAX_AGENT_OUTPUT_BYTES) {
+        outputLimitExceeded = true
+        killProcessTree(child)
+        return
+      }
+      stdout += chunk.toString('utf-8')
+    })
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderrBytes += chunk.byteLength
+      if (stderrBytes > MAX_AGENT_OUTPUT_BYTES) {
+        outputLimitExceeded = true
+        killProcessTree(child)
+        return
+      }
+      stderr += chunk.toString('utf-8')
+    })
+    child.on('error', (error) => {
+      clearTimeout(timer)
+      const code = (error as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        finalize({
+          success: false,
+          error: `${binary} not found on PATH. Install ${label} to use AI commit messages.`
+        })
+        return
+      }
+      console.error('[commit-message] Local generator failed after spawn:', error)
+      finalize({
+        success: false,
+        error: `${label} failed to start. Check the agent command in Settings and try again.`
+      })
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      if (canceledByUser) {
+        finalize({ success: false, error: 'Generation canceled.', canceled: true })
+        return
+      }
+      if (outputLimitExceeded) {
+        finalize({ success: false, error: userFacingAgentFailure(label) })
+        return
+      }
+      finalizeFromAgentOutput({ code, stdout, stderr, label, finalize })
+    })
+
+    child.stdin?.end(stdinPayload ?? undefined)
+  })
+}
+
+function finalizeFromAgentOutput(args: {
+  code: number | null
+  stdout: string
+  stderr: string
+  label: string
+  finalize: (result: InternalCommitMessageGenerationResult) => void
+}): void {
+  const { code, stdout, stderr, label, finalize } = args
+  if (code !== 0) {
+    const safeDetail = sanitizeAgentFailureDetail(extractAgentErrorMessage(stdout, stderr))
+    console.error('[commit-message] Generator failed:', {
+      label,
+      exitCode: code,
+      safeDetail,
+      stdout,
+      stderr
+    })
+    finalize({ success: false, error: userFacingAgentFailure(label) })
+    return
+  }
+  const cleaned = cleanGeneratedCommitMessage(stdout)
+  if (!cleaned) {
+    finalize({ success: false, error: `${label} returned an empty message.` })
+    return
+  }
+  const commitMessage = splitGeneratedCommitMessage(cleaned)
+  finalize({
+    success: true,
+    commitMessage,
+    agentLabel: label
+  })
+}
+
+async function runRemotePlan(
+  plan: CommitMessagePlan,
+  target: Extract<CommitMessageGenerationTarget, { kind: 'remote' }>
+): Promise<InternalCommitMessageGenerationResult> {
+  const { binary, label } = plan
+  let result: RemoteCommitMessageExecResult
+  try {
+    result = await target.execute(plan, target.cwd, GENERATION_TIMEOUT_MS)
+  } catch (error) {
+    console.error('[commit-message] Remote generator request failed:', error)
+    return {
+      success: false,
+      error: `${label} could not be reached on the ${target.missingBinaryLocation}. Try again after the SSH connection recovers.`
+    }
+  }
+  if (result.spawnError) {
+    if (result.spawnError === WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR) {
+      return {
+        success: false,
+        error: userFacingUnsafeWindowsBatchArgs(label)
+      }
+    }
+    if (/ENOENT/i.test(result.spawnError)) {
+      return {
+        success: false,
+        error: `${binary} not found on the ${target.missingBinaryLocation}. Install ${label} there.`
+      }
+    }
+    console.error('[commit-message] Remote generator spawn failed:', result.spawnError)
+    return {
+      success: false,
+      error: `${label} could not be started on the ${target.missingBinaryLocation}. Check the agent command there and try again.`
+    }
+  }
+  if (result.canceled) {
+    return { success: false, error: 'Generation canceled.', canceled: true }
+  }
+  if (result.timedOut) {
+    return {
+      success: false,
+      error: `Generation timed out after ${GENERATION_TIMEOUT_MS / 1000}s.`
+    }
+  }
+
+  return new Promise((resolve) => {
+    finalizeFromAgentOutput({
+      code: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      label,
+      finalize: resolve
+    })
+  })
+}
+
+function formatCommitMessageGenerationResult(
+  result: InternalCommitMessageGenerationResult,
+  attributionEnabled: boolean
+): GenerateCommitMessageResult {
+  if (!result.success) {
+    return result
+  }
+  return {
+    success: true,
+    message: applyOrcaAttribution(result.commitMessage.message, attributionEnabled),
+    agentLabel: result.agentLabel
+  }
+}
+
+export async function generateCommitMessageFromContext(
+  context: CommitMessageDraftContext,
+  params: GenerateCommitMessageParams,
+  target: CommitMessageGenerationTarget
+): Promise<GenerateCommitMessageResult> {
+  const prompt = buildCommitMessagePrompt(context, params.customPrompt ?? '')
+  const planned = planCommitMessageGeneration(params, prompt)
+  if (!planned.ok) {
+    return { success: false, error: planned.error }
+  }
+
+  const internalResult =
+    target.kind === 'remote'
+      ? await runRemotePlan(planned.plan, target)
+      : await runLocalPlan(planned.plan, target.cwd, target.env)
+  return formatCommitMessageGenerationResult(internalResult, params.attributionEnabled === true)
+}
diff --git a/src/main/win32-utils.test.ts b/src/main/win32-utils.test.ts
index 621bfaaf7bb..cf4efb4cd52 100644
--- a/src/main/win32-utils.test.ts
+++ b/src/main/win32-utils.test.ts
@@ -44,9 +44,9 @@ describe('getSpawnArgsForWindows', () => {
           '--foo'
         ])
         expect(spawnCmd).toBe('C:\\Windows\\System32\\cmd.exe')
-        // Why: /d disables AutoRun; /c runs the given command and exits. Args
-        // follow the batch path literally without re-escaping.
-        expect(spawnArgs).toEqual(['/d', '/c', 'C:\\tools\\codex.cmd', 'login', '--foo'])
+        // Why: /d disables AutoRun; /s preserves quoted command-line parsing;
+        // /c runs the quoted batch command and exits.
+        expect(spawnArgs).toEqual(['/d', '/s', '/c', '"C:\\tools\\codex.cmd" "login" "--foo"'])
       })
     } finally {
       if (originalComSpec === undefined) {
@@ -72,6 +72,14 @@ describe('getSpawnArgsForWindows', () => {
       expect(spawnArgs).toEqual(['login'])
     })
   })
+
+  it('rejects unsafe args for .cmd scripts on win32', () => {
+    withPlatform('win32', () => {
+      expect(() => getSpawnArgsForWindows('C:\\tools\\agent.cmd', ['hello & goodbye'])).toThrow(
+        'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
+      )
+    })
+  })
 })
 
 describe('isPermissionError', () => {
diff --git a/src/main/win32-utils.ts b/src/main/win32-utils.ts
index 4465fa22349..edddf2eefd5 100644
--- a/src/main/win32-utils.ts
+++ b/src/main/win32-utils.ts
@@ -22,6 +22,26 @@ export function isWindowsBatchScript(commandPath: string): boolean {
   return process.platform === 'win32' && /\.(cmd|bat)$/i.test(commandPath)
 }
 
+export const WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR = 'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
+
+export class UnsafeWindowsBatchArgumentsError extends Error {
+  constructor() {
+    super(WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR)
+    this.name = 'UnsafeWindowsBatchArgumentsError'
+  }
+}
+
+function hasUnsafeWindowsBatchSyntax(value: string): boolean {
+  return /[&|<>^"%!\r\n]/.test(value)
+}
+
+function quoteWindowsBatchToken(value: string): string {
+  if (hasUnsafeWindowsBatchSyntax(value)) {
+    throw new UnsafeWindowsBatchArgumentsError()
+  }
+  return `"${value}"`
+}
+
 /** Check whether an error is a Windows permission error (EACCES or EPERM). */
 export function isPermissionError(error: unknown): boolean {
   return (
@@ -103,18 +123,17 @@ export function grantDirAcl(dirPath: string, options?: { recursive?: boolean }):
  * Why /d: disables per-machine/user AutoRun registry commands so a background
  * spawn cannot inherit surprising side effects from the user's shell config.
  *
- * SAFETY: when the .cmd/.bat branch is taken, cmd.exe re-parses the combined
- * command line, so callers MUST only pass trusted/literal args. An arg
- * containing `&`, `|`, `^`, `<`, `>`, or unbalanced `"` can escape the
- * intended command and execute arbitrary cmd.exe syntax. Do not feed
- * user-supplied strings through this helper without first validating them.
+ * SAFETY: when the .cmd/.bat branch is taken, cmd.exe re-parses the command
+ * line. Args with cmd metacharacters are rejected instead of escaped because
+ * the agent prompt may contain arbitrary staged diff text.
  */
 export function getSpawnArgsForWindows(
   command: string,
   args: string[]
 ): { spawnCmd: string; spawnArgs: string[] } {
   if (isWindowsBatchScript(command)) {
-    return { spawnCmd: getCmdExePath(), spawnArgs: ['/d', '/c', command, ...args] }
+    const commandLine = [command, ...args].map(quoteWindowsBatchToken).join(' ')
+    return { spawnCmd: getCmdExePath(), spawnArgs: ['/d', '/s', '/c', commandLine] }
   }
   return { spawnCmd: command, spawnArgs: args }
 }
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 73322f995ab..9eb7f202d3f 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -1214,6 +1214,17 @@ export type PreloadApi = {
       message: string
       connectionId?: string
     }) => Promise<{ success: boolean; error?: string }>
+    generateCommitMessage: (args: {
+      worktreePath: string
+      connectionId?: string
+    }) => Promise<
+      | { success: true; message: string; agentLabel?: string }
+      | { success: false; error: string; canceled?: boolean }
+    >
+    cancelGenerateCommitMessage: (args: {
+      worktreePath: string
+      connectionId?: string
+    }) => Promise<void>
     stage: (args: {
       worktreePath: string
       filePath: string
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 5e987664eab..d26874832be 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -1807,6 +1807,14 @@ const api = {
       message: string
       connectionId?: string
     }): Promise<{ success: boolean; error?: string }> => ipcRenderer.invoke('git:commit', args),
+    generateCommitMessage: (args: {
+      worktreePath: string
+      connectionId?: string
+    }): Promise<unknown> => ipcRenderer.invoke('git:generateCommitMessage', args),
+    cancelGenerateCommitMessage: (args: {
+      worktreePath: string
+      connectionId?: string
+    }): Promise<void> => ipcRenderer.invoke('git:cancelGenerateCommitMessage', args),
     stage: (args: {
       worktreePath: string
       filePath: string
diff --git a/src/relay/agent-exec-handler.test.ts b/src/relay/agent-exec-handler.test.ts
new file mode 100644
index 00000000000..18a9a5966c9
--- /dev/null
+++ b/src/relay/agent-exec-handler.test.ts
@@ -0,0 +1,259 @@
+import { EventEmitter } from 'events'
+import { exec, spawn } from 'child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type * as ChildProcess from 'child_process'
+import type { MethodHandler } from './dispatcher'
+import { AgentExecHandler } from './agent-exec-handler'
+
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof ChildProcess>()
+  return {
+    ...actual,
+    exec: vi.fn(),
+    spawn: vi.fn()
+  }
+})
+
+const spawnMock = vi.mocked(spawn)
+const execMock = vi.mocked(exec)
+
+function withPlatform<T>(platform: NodeJS.Platform, fn: () => T): T {
+  const original = process.platform
+  Object.defineProperty(process, 'platform', { configurable: true, value: platform })
+  try {
+    return fn()
+  } finally {
+    Object.defineProperty(process, 'platform', { configurable: true, value: original })
+  }
+}
+
+type FakeChild = EventEmitter & {
+  pid: number
+  kill: ReturnType<typeof vi.fn>
+  stdout: EventEmitter
+  stderr: EventEmitter
+  stdin: { end: ReturnType<typeof vi.fn> }
+}
+
+function createFakeChild(): FakeChild {
+  return Object.assign(new EventEmitter(), {
+    pid: 12345,
+    kill: vi.fn(),
+    stdout: new EventEmitter(),
+    stderr: new EventEmitter(),
+    stdin: { end: vi.fn() }
+  })
+}
+
+function createHandlers(): Map<string, MethodHandler> {
+  const handlers = new Map<string, MethodHandler>()
+  new AgentExecHandler({
+    onRequest: (method: string, handler: MethodHandler): void => {
+      handlers.set(method, handler)
+    }
+  } as never)
+  return handlers
+}
+
+describe('AgentExecHandler', () => {
+  beforeEach(() => {
+    spawnMock.mockReset()
+    execMock.mockReset()
+  })
+
+  it('executes a non-interactive command with captured output and stdin', async () => {
+    const child = createFakeChild()
+    spawnMock.mockReturnValue(child as never)
+    const handlers = createHandlers()
+
+    const pending = handlers.get('agent.execNonInteractive')!(
+      {
+        binary: 'agent',
+        args: ['--flag', 42],
+        cwd: '/repo',
+        stdin: 'PROMPT',
+        timeoutMs: 5_000
+      },
+      { isStale: () => false }
+    )
+
+    child.stdout.emit('data', Buffer.from('message'))
+    child.stderr.emit('data', Buffer.from('warning'))
+    child.emit('close', 0)
+
+    await expect(pending).resolves.toEqual({
+      stdout: 'message',
+      stderr: 'warning',
+      exitCode: 0,
+      timedOut: false,
+      canceled: false
+    })
+    expect(spawnMock).toHaveBeenCalledWith('agent', ['--flag', '42'], {
+      cwd: '/repo',
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true
+    })
+    expect(child.stdin.end).toHaveBeenCalledWith('PROMPT')
+  })
+
+  it('merges caller-supplied provider environment into the spawned command environment', async () => {
+    const child = createFakeChild()
+    spawnMock.mockReturnValue(child as never)
+    const handlers = createHandlers()
+
+    const pending = handlers.get('agent.execNonInteractive')!(
+      {
+        binary: 'codex',
+        args: ['exec'],
+        cwd: '/repo',
+        stdin: 'PROMPT',
+        timeoutMs: 5_000,
+        env: {
+          CODEX_HOME: '/managed/codex-home',
+          PATH: '/managed/bin'
+        }
+      },
+      { isStale: () => false }
+    )
+
+    child.emit('close', 0)
+
+    await expect(pending).resolves.toMatchObject({
+      exitCode: 0,
+      timedOut: false
+    })
+    expect(spawnMock).toHaveBeenCalledWith('codex', ['exec'], {
+      cwd: '/repo',
+      env: expect.objectContaining({
+        ...process.env,
+        CODEX_HOME: '/managed/codex-home',
+        PATH: '/managed/bin'
+      }),
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true
+    })
+  })
+
+  it('resolves bare Windows agent commands to batch shims before spawning', async () => {
+    const tempDir = mkdtempSync(join(tmpdir(), 'orca-agent-exec-'))
+    const originalComSpec = process.env.ComSpec
+    process.env.ComSpec = 'C:\\Windows\\System32\\cmd.exe'
+    try {
+      await withPlatform('win32', async () => {
+        const codexShim = join(tempDir, 'codex.cmd')
+        writeFileSync(codexShim, '@echo off\r\n')
+        const child = createFakeChild()
+        spawnMock.mockReturnValue(child as never)
+        const handlers = createHandlers()
+
+        const pending = handlers.get('agent.execNonInteractive')!(
+          {
+            binary: 'codex',
+            args: ['exec', '-s', 'read-only'],
+            cwd: 'C:\\repo',
+            stdin: 'PROMPT',
+            timeoutMs: 5_000,
+            env: { PATH: tempDir }
+          },
+          { isStale: () => false }
+        )
+
+        child.emit('close', 0)
+
+        await expect(pending).resolves.toMatchObject({
+          exitCode: 0,
+          timedOut: false
+        })
+        expect(spawnMock).toHaveBeenCalledWith(
+          'C:\\Windows\\System32\\cmd.exe',
+          ['/d', '/s', '/c', `"${codexShim}" "exec" "-s" "read-only"`],
+          {
+            cwd: 'C:\\repo',
+            env: expect.objectContaining({ PATH: tempDir }),
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true
+          }
+        )
+      })
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true })
+      if (originalComSpec === undefined) {
+        delete process.env.ComSpec
+      } else {
+        process.env.ComSpec = originalComSpec
+      }
+    }
+  })
+
+  it('rejects unsafe args when routing Windows batch shims through cmd.exe', async () => {
+    await withPlatform('win32', async () => {
+      const handlers = createHandlers()
+
+      const result = await handlers.get('agent.execNonInteractive')!(
+        {
+          binary: 'C:\\tools\\agent.cmd',
+          args: ['hello & goodbye'],
+          cwd: 'C:\\repo',
+          stdin: null,
+          timeoutMs: 5_000
+        },
+        { isStale: () => false }
+      )
+
+      expect(result).toEqual({
+        stdout: '',
+        stderr: '',
+        exitCode: null,
+        timedOut: false,
+        spawnError: 'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
+      })
+      expect(spawnMock).not.toHaveBeenCalled()
+    })
+  })
+
+  it('cancels the in-flight command for the requested cwd', async () => {
+    const child = createFakeChild()
+    spawnMock.mockReturnValue(child as never)
+    const handlers = createHandlers()
+
+    const pending = handlers.get('agent.execNonInteractive')!(
+      {
+        binary: 'agent',
+        args: [],
+        cwd: '/repo',
+        stdin: null,
+        timeoutMs: 5_000
+      },
+      { isStale: () => false }
+    )
+
+    await expect(
+      handlers.get('agent.cancelExec')!({ cwd: '/repo' }, { isStale: () => false })
+    ).resolves.toEqual({ canceled: true })
+
+    if (process.platform === 'win32') {
+      expect(execMock).toHaveBeenCalledWith('taskkill /pid 12345 /T /F', expect.any(Function))
+    } else {
+      expect(child.kill).toHaveBeenCalledWith('SIGKILL')
+    }
+
+    child.emit('close', null)
+    await expect(pending).resolves.toMatchObject({
+      exitCode: null,
+      timedOut: false,
+      canceled: true
+    })
+  })
+
+  it('reports when cancellation has no matching in-flight command', async () => {
+    const handlers = createHandlers()
+
+    await expect(
+      handlers.get('agent.cancelExec')!({ cwd: '/repo' }, { isStale: () => false })
+    ).resolves.toEqual({ canceled: false })
+  })
+})
diff --git a/src/relay/agent-exec-handler.ts b/src/relay/agent-exec-handler.ts
new file mode 100644
index 00000000000..38dc75601a4
--- /dev/null
+++ b/src/relay/agent-exec-handler.ts
@@ -0,0 +1,254 @@
+import { exec, spawn, type ChildProcess } from 'child_process'
+import { existsSync } from 'fs'
+import { delimiter, join } from 'path'
+import type { RelayDispatcher } from './dispatcher'
+
+const DEFAULT_TIMEOUT_MS = 60_000
+const MAX_TIMEOUT_MS = 5 * 60 * 1000
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024
+const WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR = 'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
+
+function getCmdExePath(): string {
+  return process.env.ComSpec || `${process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\cmd.exe`
+}
+
+function isWindowsBatchScript(commandPath: string): boolean {
+  return process.platform === 'win32' && /\.(cmd|bat)$/i.test(commandPath)
+}
+
+function hasUnsafeWindowsBatchSyntax(value: string): boolean {
+  return /[&|<>^"%!\r\n]/.test(value)
+}
+
+function quoteWindowsBatchToken(value: string): string {
+  if (hasUnsafeWindowsBatchSyntax(value)) {
+    throw new Error(WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR)
+  }
+  return `"${value}"`
+}
+
+function resolveWindowsCommand(binary: string, env: NodeJS.ProcessEnv): string {
+  if (process.platform !== 'win32') {
+    return binary
+  }
+  if (/[\\/]/.test(binary) || /\.[a-z0-9]+$/i.test(binary)) {
+    return binary
+  }
+
+  const pathEnv = env.PATH ?? env.Path
+  if (!pathEnv) {
+    return binary
+  }
+  const names = [`${binary}.cmd`, `${binary}.exe`, `${binary}.bat`, binary]
+  for (const directory of pathEnv.split(delimiter).filter(Boolean)) {
+    for (const name of names) {
+      const candidate = join(directory, name)
+      if (existsSync(candidate)) {
+        return candidate
+      }
+    }
+  }
+  return binary
+}
+
+function getWindowsSafeSpawn(
+  binary: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): { spawnCmd: string; spawnArgs: string[] } {
+  const resolvedBinary = resolveWindowsCommand(binary, env)
+  if (!isWindowsBatchScript(resolvedBinary)) {
+    return { spawnCmd: resolvedBinary, spawnArgs: args }
+  }
+  const commandLine = [resolvedBinary, ...args].map(quoteWindowsBatchToken).join(' ')
+  return { spawnCmd: getCmdExePath(), spawnArgs: ['/d', '/s', '/c', commandLine] }
+}
+
+// Why: mirrors src/main/text-generation/commit-message-text-generation.ts. On
+// Windows, npm-installed CLIs like `claude`/`codex` are usually `.cmd` shims.
+// We route those through cmd.exe so Node can launch them, and taskkill is
+// needed to terminate the whole wrapper + node.exe process tree. Kept
+// duplicated rather than imported because the relay ships to remote hosts.
+function killProcessTree(child: ChildProcess): void {
+  const pid = child.pid
+  if (!pid) {
+    return
+  }
+  if (process.platform === 'win32') {
+    exec(`taskkill /pid ${pid} /T /F`, () => {
+      // Best-effort; the spawn's `close` listener fires once the tree exits.
+    })
+    return
+  }
+  try {
+    child.kill('SIGKILL')
+  } catch {
+    // Child may already have exited between the kill request and now.
+  }
+}
+
+type ExecParams = {
+  binary: unknown
+  args: unknown
+  cwd: unknown
+  stdin: unknown
+  timeoutMs: unknown
+  env: unknown
+}
+
+type CancelParams = {
+  cwd: unknown
+}
+
+type ExecResult = {
+  stdout: string
+  stderr: string
+  exitCode: number | null
+  timedOut: boolean
+  /** Set when the user canceled the exec via `agent.cancelExec`. */
+  canceled?: boolean
+  /** Set when the binary could not be spawned (e.g. ENOENT). */
+  spawnError?: string
+}
+
+/**
+ * Non-interactive subprocess exec on the remote host. Used by the AI commit
+ * message generator to spawn agent CLIs (claude, codex, …) with the staged
+ * diff piped via stdin and the output captured to stdout. Distinct from
+ * `pty.spawn` because we want no terminal allocation, no escape sequences,
+ * and a clean exit code instead of an interactive session.
+ */
+export class AgentExecHandler {
+  // Why: a single in-flight exec per cwd is enough — the renderer prevents
+  // double-clicks. Keying by cwd lets `agent.cancelExec({cwd})` find the
+  // child without the client having to track relay-internal request ids.
+  private inFlightByCwd = new Map<string, { child: ChildProcess; markCanceled: () => void }>()
+
+  constructor(dispatcher: RelayDispatcher) {
+    dispatcher.onRequest('agent.execNonInteractive', (p) => this.exec(p as ExecParams))
+    dispatcher.onRequest('agent.cancelExec', (p) => this.cancel(p as CancelParams))
+  }
+
+  private async cancel(params: CancelParams): Promise<{ canceled: boolean }> {
+    const cwd = typeof params.cwd === 'string' ? params.cwd : ''
+    const entry = this.inFlightByCwd.get(cwd)
+    if (!entry) {
+      return { canceled: false }
+    }
+    entry.markCanceled()
+    killProcessTree(entry.child)
+    return { canceled: true }
+  }
+
+  private async exec(params: ExecParams): Promise<ExecResult> {
+    const binary = typeof params.binary === 'string' ? params.binary : ''
+    if (!binary) {
+      throw new Error('agent.execNonInteractive: binary is required')
+    }
+    const args = Array.isArray(params.args) ? params.args.map((a) => String(a)) : []
+    const cwd = typeof params.cwd === 'string' && params.cwd.length > 0 ? params.cwd : undefined
+    const stdinPayload = typeof params.stdin === 'string' ? params.stdin : null
+    const requestedTimeout =
+      typeof params.timeoutMs === 'number' ? params.timeoutMs : DEFAULT_TIMEOUT_MS
+    const timeoutMs = Math.max(1_000, Math.min(MAX_TIMEOUT_MS, requestedTimeout))
+    const extraEnv =
+      params.env && typeof params.env === 'object' && !Array.isArray(params.env)
+        ? (params.env as Record<string, string>)
+        : null
+    const spawnEnv = extraEnv ? { ...process.env, ...extraEnv } : process.env
+
+    return new Promise<ExecResult>((resolve) => {
+      let child
+      try {
+        const { spawnCmd, spawnArgs } = getWindowsSafeSpawn(binary, args, spawnEnv)
+        child = spawn(spawnCmd, spawnArgs, {
+          cwd,
+          env: spawnEnv,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          windowsHide: true
+        })
+      } catch (error) {
+        resolve({
+          stdout: '',
+          stderr: '',
+          exitCode: null,
+          timedOut: false,
+          spawnError: error instanceof Error ? error.message : String(error)
+        })
+        return
+      }
+
+      let stdout = ''
+      let stderr = ''
+      let stdoutBytes = 0
+      let stderrBytes = 0
+      let timedOut = false
+      let canceled = false
+      let settled = false
+      const laneKey = typeof cwd === 'string' ? cwd : ''
+      const finish = (result: ExecResult): void => {
+        if (settled) {
+          return
+        }
+        settled = true
+        if (laneKey) {
+          this.inFlightByCwd.delete(laneKey)
+        }
+        resolve(result)
+      }
+      if (laneKey) {
+        this.inFlightByCwd.set(laneKey, {
+          child,
+          markCanceled: () => {
+            canceled = true
+          }
+        })
+      }
+
+      const timer = setTimeout(() => {
+        timedOut = true
+        // Why: tree-kill because some CLIs trap SIGTERM and continue streaming;
+        // also Windows wraps `.cmd` shims in cmd.exe, so the immediate child
+        // is not the real node.exe process.
+        killProcessTree(child)
+      }, timeoutMs)
+
+      child.stdout?.on('data', (chunk: Buffer) => {
+        stdoutBytes += chunk.byteLength
+        if (stdoutBytes > MAX_OUTPUT_BYTES) {
+          killProcessTree(child)
+          return
+        }
+        stdout += chunk.toString('utf-8')
+      })
+      child.stderr?.on('data', (chunk: Buffer) => {
+        stderrBytes += chunk.byteLength
+        if (stderrBytes > MAX_OUTPUT_BYTES) {
+          killProcessTree(child)
+          return
+        }
+        stderr += chunk.toString('utf-8')
+      })
+      child.on('error', (error) => {
+        clearTimeout(timer)
+        finish({
+          stdout,
+          stderr,
+          exitCode: null,
+          timedOut,
+          spawnError: error.message
+        })
+      })
+      child.on('close', (code) => {
+        clearTimeout(timer)
+        finish({ stdout, stderr, exitCode: code, timedOut, canceled })
+      })
+
+      if (stdinPayload !== null) {
+        child.stdin?.end(stdinPayload)
+      } else {
+        child.stdin?.end()
+      }
+    })
+  }
+}
diff --git a/src/relay/git-exec-validator.test.ts b/src/relay/git-exec-validator.test.ts
index 54039ebd7cb..b808e692b8a 100644
--- a/src/relay/git-exec-validator.test.ts
+++ b/src/relay/git-exec-validator.test.ts
@@ -23,6 +23,8 @@ describe('validateGitExecArgs', () => {
       [['symbolic-ref', 'HEAD']],
       [['symbolic-ref', '--short', 'HEAD']],
       [['merge-base', 'main', 'HEAD']],
+      [['diff', '--cached', '--name-status']],
+      [['diff', '--cached', '--patch', '--minimal', '--no-color', '--no-ext-diff']],
       [['ls-files', '--error-unmatch', 'foo.txt']],
       [['config', '--get', 'user.name']],
       [['config', '--get-all', 'remote.origin.url']],
@@ -189,4 +191,19 @@ describe('validateGitExecArgs', () => {
       expectBlocked(['symbolic-ref', '--delete=HEAD'], 'git symbolic-ref write operations')
     })
   })
+
+  describe('git diff', () => {
+    it('rejects unstaged diff reads', () => {
+      expectBlocked(['diff', '--name-status'], 'restricted to staged changes')
+    })
+
+    it('rejects arbitrary refs and pathspecs', () => {
+      expectBlocked(['diff', '--cached', 'HEAD~1'], 'git diff flag not allowed')
+      expectBlocked(['diff', '--cached', '--', 'src/file.ts'], 'git diff flag not allowed')
+    })
+
+    it('rejects no-index reads', () => {
+      expectBlocked(['diff', '--cached', '--no-index', '/etc/passwd'], 'git diff flag not allowed')
+    })
+  })
 })
diff --git a/src/relay/git-exec-validator.ts b/src/relay/git-exec-validator.ts
index b881fbb6a26..0c8df69a4da 100644
--- a/src/relay/git-exec-validator.ts
+++ b/src/relay/git-exec-validator.ts
@@ -16,6 +16,7 @@ const ALLOWED_GIT_SUBCOMMANDS = new Set([
   'remote',
   'symbolic-ref',
   'merge-base',
+  'diff',
   'ls-files',
   'for-each-ref',
   'config'
@@ -69,6 +70,15 @@ const REMOTE_WRITE_SUBCOMMANDS = new Set([
   'update'
 ])
 const SYMBOLIC_REF_WRITE_FLAGS = new Set(['-d', '--delete', '-m'])
+const DIFF_ALLOWED_FLAGS = new Set([
+  '--cached',
+  '--staged',
+  '--name-status',
+  '--patch',
+  '--minimal',
+  '--no-color',
+  '--no-ext-diff'
+])
 
 // Why: git accepts --flag=value compound syntax (e.g. --file=/etc/passwd),
 // which bypasses exact-match Set.has() checks. This helper catches both forms.
@@ -133,4 +143,16 @@ export function validateGitExecArgs(args: string[]): void {
       throw new Error('git symbolic-ref write operations are not allowed via exec')
     }
   }
+  if (subcommand === 'diff') {
+    // Why: SSH commit-message generation only needs read-only staged diffs.
+    // Keep this narrow so `git.exec` cannot become a general file reader via
+    // arbitrary revisions, pathspecs, or --no-index.
+    if (!restArgs.some((a) => a === '--cached' || a === '--staged')) {
+      throw new Error('git diff via exec is restricted to staged changes')
+    }
+    const unsupportedArg = restArgs.find((a) => !DIFF_ALLOWED_FLAGS.has(a))
+    if (unsupportedArg) {
+      throw new Error(`git diff flag not allowed via exec: ${unsupportedArg}`)
+    }
+  }
 }
diff --git a/src/relay/relay.ts b/src/relay/relay.ts
index b1bc2df32a5..b221c712554 100644
--- a/src/relay/relay.ts
+++ b/src/relay/relay.ts
@@ -5,6 +5,10 @@
    topological order. Splitting by line count would scatter ordered side-
    effects across modules and obscure the lifecycle. */
 
+/* eslint-disable max-lines -- Why: the relay entrypoint owns process startup,
+   daemon reconnect, and handler registration. Splitting the orchestration
+   would hide the startup order, which is the important invariant here. */
+
 // Orca Relay — lightweight daemon deployed to remote hosts.
 // Communicates over stdin/stdout using the framed JSON-RPC protocol.
 // The Electron app (client) deploys this script via SCP and launches
@@ -28,6 +32,7 @@ import { FsHandler } from './fs-handler'
 import { GitHandler } from './git-handler'
 import { PreflightHandler } from './preflight-handler'
 import { PortScanHandler } from './port-scan-handler'
+import { AgentExecHandler } from './agent-exec-handler'
 import { endpointDirForRelaySocket, RelayAgentHookServer } from './agent-hook-server'
 import { PluginOverlayManager } from './plugin-overlay'
 import {
@@ -232,6 +237,9 @@ async function main(): Promise<void> {
   const _portScanHandler = new PortScanHandler(dispatcher)
   void _portScanHandler
 
+  const _agentExecHandler = new AgentExecHandler(dispatcher)
+  void _agentExecHandler
+
   // ── Agent-hook server ─────────────────────────────────────────────
   // Why: hosts a loopback HTTP receiver inside the relay process so agent
   // CLIs running in remote PTYs can post hook events without leaving the
diff --git a/src/renderer/src/components/right-sidebar/CommitArea.chevron-spinner.test.tsx b/src/renderer/src/components/right-sidebar/CommitArea.chevron-spinner.test.tsx
index 0d84e6517ce..bf85b036506 100644
--- a/src/renderer/src/components/right-sidebar/CommitArea.chevron-spinner.test.tsx
+++ b/src/renderer/src/components/right-sidebar/CommitArea.chevron-spinner.test.tsx
@@ -85,11 +85,19 @@ function baseProps(overrides: Partial<PrimaryActionInputs> = {}) {
     commitMessage: 'feat: add commit area',
     commitError: null as string | null,
     isCommitting: inputs.isCommitting,
+    aiEnabled: false,
+    aiAgentConfigured: false,
+    isGenerating: false,
+    generateError: null as string | null,
+    stagedCount: inputs.stagedCount,
+    hasUnresolvedConflicts: inputs.hasUnresolvedConflicts,
     isRemoteOperationActive: inputs.isRemoteOperationActive,
     inFlightRemoteOpKind: inputs.inFlightRemoteOpKind ?? null,
     primaryAction: resolvePrimaryAction(inputs),
     dropdownItems: resolveDropdownItems(inputs),
     onCommitMessageChange: vi.fn(),
+    onGenerate: vi.fn(),
+    onCancelGenerate: vi.fn(),
     onPrimaryAction: vi.fn(),
     onDropdownAction: vi.fn() as (kind: DropdownActionKind) => void
   }
diff --git a/src/renderer/src/components/right-sidebar/CommitArea.generate.test.tsx b/src/renderer/src/components/right-sidebar/CommitArea.generate.test.tsx
new file mode 100644
index 00000000000..cce1ecae339
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/CommitArea.generate.test.tsx
@@ -0,0 +1,213 @@
+import { describe, expect, it, vi } from 'vitest'
+import { CommitArea } from './SourceControl'
+import { Button } from '@/components/ui/button'
+import { resolvePrimaryAction, type PrimaryActionInputs } from './source-control-primary-action'
+import { resolveDropdownItems, type DropdownActionKind } from './source-control-dropdown-items'
+
+type ReactElementLike = {
+  type: unknown
+  props: Record<string, unknown>
+}
+
+function visit(node: unknown, cb: (node: ReactElementLike) => void): void {
+  if (node == null || typeof node === 'string' || typeof node === 'number') {
+    return
+  }
+  if (Array.isArray(node)) {
+    node.forEach((entry) => visit(entry, cb))
+    return
+  }
+  const element = node as ReactElementLike
+  cb(element)
+  if (element.props?.children) {
+    visit(element.props.children, cb)
+  }
+}
+
+function findNativeButtonByAriaLabel(node: unknown, ariaLabel: string): ReactElementLike {
+  let found: ReactElementLike | null = null
+  visit(node, (entry) => {
+    if (entry.type === 'button' && entry.props['aria-label'] === ariaLabel) {
+      found = entry
+    }
+  })
+  if (!found) {
+    throw new Error(`button not found: ${ariaLabel}`)
+  }
+  return found
+}
+
+function hasNativeButtonByAriaLabel(node: unknown, ariaLabel: string): boolean {
+  let found = false
+  visit(node, (entry) => {
+    if (entry.type === 'button' && entry.props['aria-label'] === ariaLabel) {
+      found = true
+    }
+  })
+  return found
+}
+
+function findTextarea(node: unknown): ReactElementLike {
+  let found: ReactElementLike | null = null
+  visit(node, (entry) => {
+    if (entry.type === 'textarea') {
+      found = entry
+    }
+  })
+  if (!found) {
+    throw new Error('textarea not found')
+  }
+  return found
+}
+
+function hasText(node: unknown, text: string): boolean {
+  let found = false
+  const walk = (value: unknown): void => {
+    if (typeof value === 'string') {
+      if (value.includes(text)) {
+        found = true
+      }
+      return
+    }
+    if (Array.isArray(value)) {
+      value.forEach(walk)
+      return
+    }
+    const element = value as ReactElementLike | null
+    if (element && typeof element === 'object' && 'props' in element) {
+      walk(element.props?.children)
+    }
+  }
+  visit(node, (entry) => {
+    walk(entry.props?.children)
+  })
+  return found
+}
+
+function buildInputs(overrides: Partial<PrimaryActionInputs> = {}): PrimaryActionInputs {
+  return {
+    stagedCount: 1,
+    hasUnstagedChanges: false,
+    hasMessage: true,
+    hasUnresolvedConflicts: false,
+    isCommitting: false,
+    isRemoteOperationActive: false,
+    upstreamStatus: { hasUpstream: true, ahead: 0, behind: 0 },
+    ...overrides
+  }
+}
+
+function baseProps(overrides: Partial<PrimaryActionInputs> = {}) {
+  const inputs = buildInputs(overrides)
+  return {
+    commitMessage: 'feat: add commit area',
+    commitError: null as string | null,
+    isCommitting: inputs.isCommitting,
+    aiEnabled: false,
+    aiAgentConfigured: false,
+    isGenerating: false,
+    generateError: null as string | null,
+    stagedCount: inputs.stagedCount,
+    hasUnresolvedConflicts: inputs.hasUnresolvedConflicts,
+    isRemoteOperationActive: inputs.isRemoteOperationActive,
+    inFlightRemoteOpKind: inputs.inFlightRemoteOpKind ?? null,
+    primaryAction: resolvePrimaryAction(inputs),
+    dropdownItems: resolveDropdownItems(inputs),
+    onCommitMessageChange: vi.fn(),
+    onGenerate: vi.fn(),
+    onCancelGenerate: vi.fn(),
+    onPrimaryAction: vi.fn(),
+    onDropdownAction: vi.fn() as (kind: DropdownActionKind) => void
+  }
+}
+
+describe('CommitArea AI generation', () => {
+  it('does not render the AI generate affordance when the feature is disabled', () => {
+    const element = CommitArea(baseProps())
+    expect(hasNativeButtonByAriaLabel(element, 'Generate commit message with AI')).toBe(false)
+  })
+
+  it('enables AI generation only when an agent is configured, changes are staged, and the message is empty', () => {
+    const onGenerate = vi.fn()
+    const props = baseProps({ hasMessage: false })
+    const element = CommitArea({
+      ...props,
+      commitMessage: '',
+      aiEnabled: true,
+      aiAgentConfigured: true,
+      onGenerate
+    })
+
+    const button = findNativeButtonByAriaLabel(element, 'Generate commit message with AI')
+    expect(button.props.disabled).toBe(false)
+    ;(button.props.onClick as () => void)()
+    expect(onGenerate).toHaveBeenCalledTimes(1)
+  })
+
+  it('disables AI generation when the textarea already has user text', () => {
+    const element = CommitArea({
+      ...baseProps(),
+      aiEnabled: true,
+      aiAgentConfigured: true
+    })
+
+    const button = findNativeButtonByAriaLabel(element, 'Generate commit message with AI')
+    expect(button.props.disabled).toBe(true)
+    expect(button.props.title).toBe('Clear the message to regenerate.')
+  })
+
+  it('disables AI generation until the configured agent can actually run', () => {
+    const props = baseProps({ hasMessage: false })
+    const element = CommitArea({
+      ...props,
+      commitMessage: '',
+      aiEnabled: true,
+      aiAgentConfigured: false
+    })
+
+    const button = findNativeButtonByAriaLabel(element, 'Generate commit message with AI')
+    expect(button.props.disabled).toBe(true)
+    expect(button.props.title).toBe('Pick an agent in Settings → AI Commit Messages.')
+  })
+
+  it('turns the generating icon into a stop affordance', () => {
+    const onCancelGenerate = vi.fn()
+    const props = baseProps({ hasMessage: false })
+    const element = CommitArea({
+      ...props,
+      commitMessage: '',
+      aiEnabled: true,
+      aiAgentConfigured: true,
+      isGenerating: true,
+      onCancelGenerate
+    })
+
+    const button = findNativeButtonByAriaLabel(element, 'Stop generating commit message')
+    expect(button.props.title).toBe('Stop generating')
+    ;(button.props.onClick as () => void)()
+    expect(onCancelGenerate).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows generation errors separately from commit errors and links them to the textarea', () => {
+    const element = CommitArea({
+      ...baseProps(),
+      commitError: null,
+      generateError: 'No staged changes to summarize.'
+    })
+
+    expect(hasText(element, 'No staged changes to summarize.')).toBe(true)
+    expect(findTextarea(element).props['aria-describedby']).toBe('commit-area-generate-error')
+  })
+
+  it('continues to render the split commit button alongside generation controls', () => {
+    const element = CommitArea({ ...baseProps(), aiEnabled: true, aiAgentConfigured: true })
+    let primaryFound = false
+    visit(element, (entry) => {
+      if (entry.type === Button) {
+        primaryFound = true
+      }
+    })
+
+    expect(primaryFound).toBe(true)
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/CommitArea.primary-icons.test.tsx b/src/renderer/src/components/right-sidebar/CommitArea.primary-icons.test.tsx
index 1ae4ef8fc95..4cf98fceffc 100644
--- a/src/renderer/src/components/right-sidebar/CommitArea.primary-icons.test.tsx
+++ b/src/renderer/src/components/right-sidebar/CommitArea.primary-icons.test.tsx
@@ -73,11 +73,19 @@ function baseProps(overrides: Partial<PrimaryActionInputs> = {}) {
     commitMessage: 'feat: add commit area',
     commitError: null as string | null,
     isCommitting: inputs.isCommitting,
+    aiEnabled: false,
+    aiAgentConfigured: false,
+    isGenerating: false,
+    generateError: null as string | null,
+    stagedCount: inputs.stagedCount,
+    hasUnresolvedConflicts: inputs.hasUnresolvedConflicts,
     isRemoteOperationActive: inputs.isRemoteOperationActive,
     inFlightRemoteOpKind: inputs.inFlightRemoteOpKind ?? null,
     primaryAction: resolvePrimaryAction(inputs),
     dropdownItems: resolveDropdownItems(inputs),
     onCommitMessageChange: vi.fn(),
+    onGenerate: vi.fn(),
+    onCancelGenerate: vi.fn(),
     onPrimaryAction: vi.fn(),
     onDropdownAction: vi.fn() as (kind: DropdownActionKind) => void
   }
diff --git a/src/renderer/src/components/right-sidebar/CommitArea.test.tsx b/src/renderer/src/components/right-sidebar/CommitArea.test.tsx
index cf4d95bcddd..cf37df70c2c 100644
--- a/src/renderer/src/components/right-sidebar/CommitArea.test.tsx
+++ b/src/renderer/src/components/right-sidebar/CommitArea.test.tsx
@@ -1,3 +1,6 @@
+/* eslint-disable max-lines -- Why: these CommitArea regression tests share
+   element-tree helpers that keep the assertions independent from a DOM test
+   harness; splitting the remaining cases would mostly duplicate setup. */
 import { describe, expect, it, vi } from 'vitest'
 import { Check, RefreshCw } from 'lucide-react'
 import { CommitArea } from './SourceControl'
@@ -123,11 +126,19 @@ function baseProps(overrides: Partial<PrimaryActionInputs> = {}) {
     commitMessage: 'feat: add commit area',
     commitError: null as string | null,
     isCommitting: inputs.isCommitting,
+    aiEnabled: false,
+    aiAgentConfigured: false,
+    isGenerating: false,
+    generateError: null as string | null,
+    stagedCount: inputs.stagedCount,
+    hasUnresolvedConflicts: inputs.hasUnresolvedConflicts,
     isRemoteOperationActive: inputs.isRemoteOperationActive,
     inFlightRemoteOpKind: inputs.inFlightRemoteOpKind ?? null,
     primaryAction: resolvePrimaryAction(inputs),
     dropdownItems: resolveDropdownItems(inputs),
     onCommitMessageChange: vi.fn(),
+    onGenerate: vi.fn(),
+    onCancelGenerate: vi.fn(),
     onPrimaryAction: vi.fn(),
     onDropdownAction: vi.fn() as (kind: DropdownActionKind) => void
   }
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index a3aeea40cce..296e13dd75f 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -9,6 +9,8 @@ import {
   Plus,
   RefreshCw,
   Settings2,
+  Sparkles,
+  Square,
   Undo2,
   FileEdit,
   FileMinus,
@@ -338,6 +340,16 @@ function SourceControlInner(): React.JSX.Element {
     {}
   )
   const isCommitting = commitInFlightByWorktree[activeWorktreeId ?? ''] ?? false
+  // Why: parallel state to commit. Same per-worktree shape so navigating between
+  // worktrees mid-generation never silently cancels the in-flight request.
+  const generateInFlightRef = useRef<Record<string, boolean>>({})
+  const [generateInFlightByWorktree, setGenerateInFlightByWorktree] = useState<
+    Record<string, boolean>
+  >({})
+  const [generateErrors, setGenerateErrors] = useState<Record<string, string | null>>({})
+  const isGenerating = generateInFlightByWorktree[activeWorktreeId ?? ''] ?? false
+  const generateError = generateErrors[activeWorktreeId ?? ''] ?? null
+  const commitMessageAi = useAppStore((s) => s.settings?.commitMessageAi)
   const filterInputRef = useRef<HTMLInputElement>(null)
   const commitMessage = readCommitDraftForWorktree(commitDrafts, activeWorktreeId)
   const commitError = commitErrors[activeWorktreeId ?? ''] ?? null
@@ -572,12 +584,19 @@ function SourceControlInner(): React.JSX.Element {
     setCommitDrafts((prev) => pruneRecord(prev))
     setCommitErrors((prev) => pruneRecord(prev))
     setCommitInFlightByWorktree((prev) => pruneRecord(prev))
+    setGenerateInFlightByWorktree((prev) => pruneRecord(prev))
+    setGenerateErrors((prev) => pruneRecord(prev))
     // Refs don't need setState — mutate in place to drop stale keys.
     for (const key of Object.keys(commitInFlightRef.current)) {
       if (!worktreeMap.has(key)) {
         delete commitInFlightRef.current[key]
       }
     }
+    for (const key of Object.keys(generateInFlightRef.current)) {
+      if (!worktreeMap.has(key)) {
+        delete generateInFlightRef.current[key]
+      }
+    }
   }, [worktreeMap])
 
   // Why: the sidebar no longer uses key={activeWorktreeId} to force a full
@@ -703,6 +722,92 @@ function SourceControlInner(): React.JSX.Element {
     worktreePath
   ])
 
+  const handleGenerate = useCallback(async (): Promise<void> => {
+    if (!activeWorktreeId || !worktreePath) {
+      return
+    }
+    if (generateInFlightRef.current[activeWorktreeId]) {
+      return
+    }
+    if (!commitMessageAi?.enabled || !commitMessageAi.agentId) {
+      return
+    }
+
+    if (commitMessageAi.agentId === 'custom') {
+      const command = commitMessageAi.customAgentCommand?.trim() ?? ''
+      if (!command) {
+        setGenerateErrors((prev) => ({
+          ...prev,
+          [activeWorktreeId]:
+            'Custom command is empty. Add one in Settings → Git → AI Commit Messages.'
+        }))
+        return
+      }
+    }
+
+    generateInFlightRef.current[activeWorktreeId] = true
+    const connectionId = getConnectionId(activeWorktreeId) ?? undefined
+    setGenerateInFlightByWorktree((prev) => ({ ...prev, [activeWorktreeId]: true }))
+    setGenerateErrors((prev) => ({ ...prev, [activeWorktreeId]: null }))
+    try {
+      const result = (await window.api.git.generateCommitMessage({
+        worktreePath,
+        connectionId
+      })) as
+        | { success: true; message: string; agentLabel?: string }
+        | { success: false; error: string; canceled?: boolean }
+
+      if (!result.success) {
+        // Why: cancellation is a deliberate user action, not a failure to
+        // surface. Clear any prior error and stay quiet.
+        if (result.canceled) {
+          setGenerateErrors((prev) => ({ ...prev, [activeWorktreeId]: null }))
+          return
+        }
+        setGenerateErrors((prev) => ({
+          ...prev,
+          [activeWorktreeId]: result.error
+        }))
+        return
+      }
+
+      // Why: race protection — the user may have started typing into the
+      // textarea while the agent was running. In that case we silently drop
+      // the generated message rather than overwrite their in-progress edits.
+      setCommitDrafts((prev) => {
+        const current = prev[activeWorktreeId]
+        if (current && current.length > 0) {
+          return prev
+        }
+        return writeCommitDraftForWorktree(prev, activeWorktreeId, result.message)
+      })
+      setGenerateErrors((prev) => ({ ...prev, [activeWorktreeId]: null }))
+    } catch (error) {
+      setGenerateErrors((prev) => ({
+        ...prev,
+        [activeWorktreeId]:
+          error instanceof Error ? error.message : 'Failed to generate commit message'
+      }))
+    } finally {
+      setGenerateInFlightByWorktree((prev) => ({ ...prev, [activeWorktreeId]: false }))
+      generateInFlightRef.current[activeWorktreeId] = false
+    }
+  }, [activeWorktreeId, commitMessageAi, worktreePath])
+
+  const handleCancelGenerate = useCallback((): void => {
+    if (!activeWorktreeId || !worktreePath) {
+      return
+    }
+    if (!generateInFlightRef.current[activeWorktreeId]) {
+      return
+    }
+    const connectionId = getConnectionId(activeWorktreeId) ?? undefined
+    // Why: fire-and-forget — the in-flight generateCommitMessage promise
+    // resolves with `{canceled: true}` once the kill propagates, which is
+    // where the spinner is cleared. Awaiting here would just delay UI feedback.
+    void window.api.git.cancelGenerateCommitMessage({ worktreePath, connectionId })
+  }, [activeWorktreeId, worktreePath])
+
   // Why: a single dispatcher for every remote-only action the split button or
   // chevron dropdown can trigger. Keeps the error-swallow pattern in one
   // place — store slices already surface actionable toasts, so additional
@@ -1873,6 +1978,20 @@ function SourceControlInner(): React.JSX.Element {
               commitMessage={commitMessage}
               commitError={commitError}
               isCommitting={isCommitting}
+              aiEnabled={commitMessageAi?.enabled === true}
+              aiAgentConfigured={
+                commitMessageAi?.enabled === true &&
+                commitMessageAi.agentId !== null &&
+                // Why: 'custom' is configured only once the user types a command.
+                // Without this guard, Generate would spawn an empty command and
+                // fail with a confusing error.
+                (commitMessageAi.agentId !== 'custom' ||
+                  (commitMessageAi.customAgentCommand ?? '').trim().length > 0)
+              }
+              isGenerating={isGenerating}
+              generateError={generateError}
+              stagedCount={grouped.staged.length}
+              hasUnresolvedConflicts={unresolvedConflicts.length > 0}
               isRemoteOperationActive={isRemoteOperationActive}
               inFlightRemoteOpKind={inFlightRemoteOpKind}
               primaryAction={primaryAction}
@@ -1885,6 +2004,10 @@ function SourceControlInner(): React.JSX.Element {
                   writeCommitDraftForWorktree(prev, activeWorktreeId, value)
                 )
               }}
+              onGenerate={() => {
+                void handleGenerate()
+              }}
+              onCancelGenerate={handleCancelGenerate}
               onPrimaryAction={handlePrimaryClick}
               onDropdownAction={handleActionInvoke}
             />
@@ -2184,11 +2307,19 @@ type CommitAreaProps = {
   commitMessage: string
   commitError: string | null
   isCommitting: boolean
+  aiEnabled: boolean
+  aiAgentConfigured: boolean
+  isGenerating: boolean
+  generateError: string | null
+  stagedCount: number
+  hasUnresolvedConflicts: boolean
   isRemoteOperationActive: boolean
   inFlightRemoteOpKind: RemoteOpKind | null
   primaryAction: PrimaryAction
   dropdownItems: DropdownEntry[]
   onCommitMessageChange: (message: string) => void
+  onGenerate: () => void
+  onCancelGenerate: () => void
   onPrimaryAction: () => void
   onDropdownAction: (kind: DropdownActionKind) => void
 }
@@ -2197,11 +2328,19 @@ export function CommitArea({
   commitMessage,
   commitError,
   isCommitting,
+  aiEnabled,
+  aiAgentConfigured,
+  isGenerating,
+  generateError,
+  stagedCount,
+  hasUnresolvedConflicts,
   isRemoteOperationActive,
   inFlightRemoteOpKind,
   primaryAction,
   dropdownItems,
   onCommitMessageChange,
+  onGenerate,
+  onCancelGenerate,
   onPrimaryAction,
   onDropdownAction
 }: CommitAreaProps): React.JSX.Element {
@@ -2239,23 +2378,90 @@ export function CommitArea({
   // title attribute carry the meaning for assistive tech.
   const PrimaryIcon = PRIMARY_ICONS[primaryAction.kind]
 
+  const hasMessage = commitMessage.trim().length > 0
+
+  // Why: only render the Generate button when the user has opted into the
+  // feature. Mounting a perma-disabled button would leak space and add noise
+  // for users who never plan to use AI commit messages.
+  const showGenerate = aiEnabled
+  let generateDisabledReason: string | undefined
+  if (isGenerating) {
+    generateDisabledReason = 'Generating commit message…'
+  } else if (isCommitting) {
+    generateDisabledReason = 'Commit in progress…'
+  } else if (!aiAgentConfigured) {
+    generateDisabledReason = 'Pick an agent in Settings → AI Commit Messages.'
+  } else if (stagedCount === 0) {
+    generateDisabledReason = 'Stage at least one file to generate a message.'
+  } else if (hasMessage) {
+    generateDisabledReason = 'Clear the message to regenerate.'
+  }
+  const isGenerateDisabled =
+    !aiAgentConfigured ||
+    isGenerating ||
+    isCommitting ||
+    stagedCount === 0 ||
+    hasMessage ||
+    hasUnresolvedConflicts
+
   return (
     <div className="px-3 pb-2">
-      <textarea
-        rows={rows}
-        value={commitMessage}
-        onChange={(e) => onCommitMessageChange(e.target.value)}
-        placeholder="Message"
-        aria-label="Commit message"
-        aria-describedby={commitError ? 'commit-area-error' : undefined}
-        className="mt-0.5 w-full resize-none rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-1 focus-visible:ring-ring"
-      />
+      <div className="relative">
+        <textarea
+          rows={rows}
+          value={commitMessage}
+          onChange={(e) => onCommitMessageChange(e.target.value)}
+          placeholder="Message"
+          aria-label="Commit message"
+          aria-describedby={
+            commitError
+              ? 'commit-area-error'
+              : generateError
+                ? 'commit-area-generate-error'
+                : undefined
+          }
+          // Why: reserve right padding so typed text does not slide under the
+          // absolute-positioned Generate icon in the top-right corner.
+          className={`mt-0.5 w-full resize-none rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-1 focus-visible:ring-ring ${
+            showGenerate ? 'pr-7' : ''
+          }`}
+        />
+        {showGenerate &&
+          (isGenerating ? (
+            // Why: while generating the icon doubles as the cancel affordance.
+            // Default state shows the spinning RefreshCw; on hover/focus we
+            // swap to a Square ("stop") with a destructive tint so the user
+            // sees that clicking will abort the run. Group/group-hover toggles
+            // keep this stateless on the React side.
+            <button
+              type="button"
+              onClick={() => onCancelGenerate()}
+              title="Stop generating"
+              aria-label="Stop generating commit message"
+              className="group absolute right-1.5 top-1.5 inline-flex size-5 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive focus-visible:bg-destructive/10 focus-visible:text-destructive focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-destructive/40"
+            >
+              <RefreshCw className="size-3.5 animate-spin group-hover:hidden group-focus-visible:hidden" />
+              <Square className="hidden size-3.5 fill-current group-hover:block group-focus-visible:block" />
+            </button>
+          ) : (
+            <button
+              type="button"
+              disabled={isGenerateDisabled}
+              onClick={() => onGenerate()}
+              title={generateDisabledReason ?? 'Generate commit message with AI'}
+              aria-label="Generate commit message with AI"
+              className="absolute right-1.5 top-1.5 inline-flex size-5 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent disabled:hover:text-muted-foreground"
+            >
+              <Sparkles className="size-3.5" />
+            </button>
+          ))}
+      </div>
       {/* Why: primary + chevron sit together as a visual split button so the
           edit → commit → push loop stays in a single vertical band. The
           chevron exposes the full action surface (fetch, pull, sync,
           publish, compound commits) without forcing morphing labels to
           carry every possible intent. */}
-      <div className="flex items-stretch">
+      <div className="mt-1 flex items-stretch">
         {/* Why: match the "Squash and merge" button in PRActions
             (size="xs", px-3 text-[11px]) so the sidebar has a consistent
             action-button shape across Source Control and Checks. The primary
@@ -2338,6 +2544,16 @@ export function CommitArea({
           {commitError}
         </p>
       )}
+      {generateError && (
+        <p
+          id="commit-area-generate-error"
+          role="alert"
+          aria-live="polite"
+          className="mt-1 text-[11px] text-destructive"
+        >
+          {generateError}
+        </p>
+      )}
     </div>
   )
 }
diff --git a/src/renderer/src/components/settings/CommitMessageAiPane.test.tsx b/src/renderer/src/components/settings/CommitMessageAiPane.test.tsx
new file mode 100644
index 00000000000..f9478fd1998
--- /dev/null
+++ b/src/renderer/src/components/settings/CommitMessageAiPane.test.tsx
@@ -0,0 +1,97 @@
+import React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { GlobalSettings } from '../../../../shared/types'
+import { useAppStore } from '../../store'
+import { CommitMessageAiPane } from './CommitMessageAiPane'
+import { COMMIT_MESSAGE_AI_PANE_SEARCH_ENTRIES } from './commit-message-ai-search'
+
+function renderPane(settings: GlobalSettings): string {
+  return renderToStaticMarkup(
+    React.createElement(CommitMessageAiPane, {
+      settings,
+      updateSettings: () => {}
+    })
+  )
+}
+
+function buildSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings {
+  return {
+    commitMessageAi: {
+      enabled: false,
+      agentId: null,
+      selectedModelByAgent: {},
+      selectedThinkingByModel: {},
+      customPrompt: '',
+      customAgentCommand: ''
+    },
+    ...overrides
+  } as GlobalSettings
+}
+
+describe('CommitMessageAiPane', () => {
+  beforeEach(() => {
+    useAppStore.setState({ settingsSearchQuery: '' })
+  })
+
+  it('renders only the opt-in control before the feature is enabled', () => {
+    const markup = renderPane(buildSettings())
+
+    expect(markup).toContain('AI Commit Messages')
+    expect(markup).toContain('Enable AI commit messages')
+    expect(markup).toContain('aria-checked="false"')
+    expect(markup).not.toContain('Which agent drafts your commit messages')
+    expect(markup).not.toContain('Thinking effort')
+  })
+
+  it('renders model, thinking, and prompt controls for enabled preset agents', () => {
+    const markup = renderPane(
+      buildSettings({
+        commitMessageAi: {
+          enabled: true,
+          agentId: 'codex',
+          selectedModelByAgent: { codex: 'gpt-5.5' },
+          selectedThinkingByModel: { 'gpt-5.5': 'medium' },
+          customPrompt: 'Use Conventional Commits.',
+          customAgentCommand: ''
+        }
+      })
+    )
+
+    expect(markup).toContain('aria-checked="true"')
+    expect(markup).toContain('Which agent drafts your commit messages')
+    expect(markup).toContain('Model')
+    expect(markup).toContain('Thinking effort')
+    expect(markup).toContain('Higher effort produces more careful messages')
+    expect(markup).toContain('Use Conventional Commits.')
+  })
+
+  it('renders custom command settings for custom agents', () => {
+    const markup = renderPane(
+      buildSettings({
+        commitMessageAi: {
+          enabled: true,
+          agentId: 'custom',
+          selectedModelByAgent: {},
+          selectedThinkingByModel: {},
+          customPrompt: '',
+          customAgentCommand: 'ollama run llama3.1 {prompt}'
+        }
+      })
+    )
+
+    expect(markup).toContain('AI Commit Messages')
+    expect(markup).toContain('Custom command')
+    expect(markup).toContain('ollama run llama3.1 {prompt}')
+  })
+
+  it('keeps custom command discoverable in settings search metadata', () => {
+    const customCommandEntry = COMMIT_MESSAGE_AI_PANE_SEARCH_ENTRIES.find(
+      (entry) => entry.title === 'Custom command'
+    )
+
+    expect(customCommandEntry?.keywords).toEqual(
+      expect.arrayContaining(['custom', 'command', 'ollama'])
+    )
+  })
+})
diff --git a/src/renderer/src/components/settings/CommitMessageAiPane.tsx b/src/renderer/src/components/settings/CommitMessageAiPane.tsx
new file mode 100644
index 00000000000..ff9000b4162
--- /dev/null
+++ b/src/renderer/src/components/settings/CommitMessageAiPane.tsx
@@ -0,0 +1,480 @@
+/* eslint-disable max-lines -- Why: each agent setting (toggle, agent dropdown,
+   model dropdown, thinking effort dropdown, custom command, custom prompt) is
+   a SearchableSetting block, and splitting the pane across files would scatter
+   the ~6 conditional render branches without making any of them clearer. */
+import { useMemo } from 'react'
+import { Terminal } from 'lucide-react'
+import type { CommitMessageAiSettings, GlobalSettings, TuiAgent } from '../../../../shared/types'
+import {
+  CUSTOM_AGENT_ID,
+  DEFAULT_COMMIT_MESSAGE_AGENT_ID,
+  getCommitMessageAgentCapability,
+  isCustomAgentId,
+  listCommitMessageAgentCapabilities,
+  type CommitMessageAgentChoice,
+  type CommitMessageAgentCapability,
+  type CommitMessageModelCapability
+} from '../../../../shared/commit-message-agent-spec'
+import { CUSTOM_PROMPT_PLACEHOLDER } from '../../../../shared/commit-message-prompt'
+import { AGENT_CATALOG, AgentIcon } from '@/lib/agent-catalog'
+import { Label } from '../ui/label'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+import { useAppStore } from '../../store'
+import { SearchableSetting } from './SearchableSetting'
+import { matchesSettingsSearch } from './settings-search'
+
+type CommitMessageAiPaneProps = {
+  settings: GlobalSettings
+  updateSettings: (updates: Partial<GlobalSettings>) => void
+}
+
+const EMPTY_SETTINGS: CommitMessageAiSettings = {
+  enabled: false,
+  agentId: null,
+  selectedModelByAgent: {},
+  selectedThinkingByModel: {},
+  customPrompt: '',
+  customAgentCommand: ''
+}
+
+function readSettings(settings: GlobalSettings): CommitMessageAiSettings {
+  return settings.commitMessageAi ?? EMPTY_SETTINGS
+}
+
+function agentLabel(agentId: TuiAgent, capability: CommitMessageAgentCapability): string {
+  return AGENT_CATALOG.find((a) => a.id === agentId)?.label ?? capability.label
+}
+
+function resolveSelectedModel(
+  config: CommitMessageAiSettings,
+  capability: CommitMessageAgentCapability
+): CommitMessageModelCapability {
+  const persisted = config.selectedModelByAgent[capability.id]
+  if (persisted) {
+    const found = capability.models.find((m) => m.id === persisted)
+    if (found) {
+      return found
+    }
+  }
+  // Why: defaultModelId is guaranteed to exist in provider capabilities by construction.
+  return capability.models.find((m) => m.id === capability.defaultModelId) ?? capability.models[0]
+}
+
+function resolveSelectedThinking(
+  config: CommitMessageAiSettings,
+  model: CommitMessageModelCapability
+): string | undefined {
+  if (!model.thinkingLevels) {
+    return undefined
+  }
+  const persisted = config.selectedThinkingByModel[model.id]
+  if (persisted && model.thinkingLevels.some((l) => l.id === persisted)) {
+    return persisted
+  }
+  return model.defaultThinkingLevel
+}
+
+export function CommitMessageAiPane({
+  settings,
+  updateSettings
+}: CommitMessageAiPaneProps): React.JSX.Element {
+  const searchQuery = useAppStore((s) => s.settingsSearchQuery)
+  const config = readSettings(settings)
+
+  const agentCapabilities = useMemo(listCommitMessageAgentCapabilities, [])
+  const activeAgentId: CommitMessageAgentChoice = config.agentId ?? DEFAULT_COMMIT_MESSAGE_AGENT_ID
+  const isCustom = isCustomAgentId(activeAgentId)
+  const activeCapability = isCustom ? undefined : getCommitMessageAgentCapability(activeAgentId)
+  const activeModel = activeCapability ? resolveSelectedModel(config, activeCapability) : null
+  const activeThinking = activeModel ? resolveSelectedThinking(config, activeModel) : undefined
+
+  const writeConfig = (patch: Partial<CommitMessageAiSettings>): void => {
+    updateSettings({ commitMessageAi: { ...config, ...patch } })
+  }
+
+  const onToggleEnabled = (): void => {
+    const next = !config.enabled
+    if (!next) {
+      writeConfig({ enabled: false })
+      return
+    }
+    // Why: when the user enables the feature for the first time, hydrate the
+    // agent / model / thinking choices from provider capabilities so the
+    // Generate button works immediately without forcing them to pick first.
+    // If the user previously persisted 'custom', we keep that and let them
+    // re-edit the command — no implicit reset to a preset.
+    const seedAgentId: TuiAgent | 'custom' = config.agentId ?? DEFAULT_COMMIT_MESSAGE_AGENT_ID
+    const seedCapability = isCustomAgentId(seedAgentId)
+      ? undefined
+      : getCommitMessageAgentCapability(seedAgentId)
+    const seedModel = seedCapability ? resolveSelectedModel(config, seedCapability) : null
+    const seedThinking = seedModel ? resolveSelectedThinking(config, seedModel) : undefined
+
+    const nextSelectedModelByAgent = { ...config.selectedModelByAgent }
+    if (seedCapability && !nextSelectedModelByAgent[seedCapability.id]) {
+      nextSelectedModelByAgent[seedCapability.id] = seedCapability.defaultModelId
+    }
+    const nextSelectedThinkingByModel = { ...config.selectedThinkingByModel }
+    if (seedModel && seedThinking && !nextSelectedThinkingByModel[seedModel.id]) {
+      nextSelectedThinkingByModel[seedModel.id] = seedThinking
+    }
+    writeConfig({
+      enabled: true,
+      agentId: seedAgentId,
+      selectedModelByAgent: nextSelectedModelByAgent,
+      selectedThinkingByModel: nextSelectedThinkingByModel
+    })
+  }
+
+  const onAgentChange = (newAgentId: string): void => {
+    if (isCustomAgentId(newAgentId)) {
+      writeConfig({ agentId: CUSTOM_AGENT_ID })
+      return
+    }
+    const capability = getCommitMessageAgentCapability(newAgentId as TuiAgent)
+    if (!capability) {
+      return
+    }
+    const nextSelectedModelByAgent = { ...config.selectedModelByAgent }
+    if (!nextSelectedModelByAgent[capability.id]) {
+      nextSelectedModelByAgent[capability.id] = capability.defaultModelId
+    }
+    const newModel = resolveSelectedModel({ ...config, agentId: capability.id }, capability)
+    const nextSelectedThinkingByModel = { ...config.selectedThinkingByModel }
+    if (
+      newModel.thinkingLevels &&
+      newModel.defaultThinkingLevel &&
+      !nextSelectedThinkingByModel[newModel.id]
+    ) {
+      nextSelectedThinkingByModel[newModel.id] = newModel.defaultThinkingLevel
+    }
+    writeConfig({
+      agentId: capability.id,
+      selectedModelByAgent: nextSelectedModelByAgent,
+      selectedThinkingByModel: nextSelectedThinkingByModel
+    })
+  }
+
+  const onCustomCommandChange = (value: string): void => {
+    writeConfig({ customAgentCommand: value })
+  }
+
+  const onModelChange = (newModelId: string): void => {
+    if (!activeCapability) {
+      return
+    }
+    const model = activeCapability.models.find((m) => m.id === newModelId)
+    if (!model) {
+      return
+    }
+    const nextSelectedModelByAgent = {
+      ...config.selectedModelByAgent,
+      [activeCapability.id]: model.id
+    }
+    const nextSelectedThinkingByModel = { ...config.selectedThinkingByModel }
+    if (
+      model.thinkingLevels &&
+      model.defaultThinkingLevel &&
+      !nextSelectedThinkingByModel[model.id]
+    ) {
+      nextSelectedThinkingByModel[model.id] = model.defaultThinkingLevel
+    }
+    writeConfig({
+      selectedModelByAgent: nextSelectedModelByAgent,
+      selectedThinkingByModel: nextSelectedThinkingByModel
+    })
+  }
+
+  const onThinkingChange = (newLevelId: string): void => {
+    if (!activeModel) {
+      return
+    }
+    writeConfig({
+      selectedThinkingByModel: {
+        ...config.selectedThinkingByModel,
+        [activeModel.id]: newLevelId
+      }
+    })
+  }
+
+  const onCustomPromptChange = (value: string): void => {
+    writeConfig({ customPrompt: value })
+  }
+
+  const sections: React.ReactNode[] = []
+
+  if (
+    matchesSettingsSearch(searchQuery, {
+      title: 'Enable AI commit messages',
+      description: 'Adds a Generate button to the Source Control panel.',
+      keywords: ['ai', 'commit', 'message', 'generate', 'agent', 'enabled']
+    })
+  ) {
+    sections.push(
+      <SearchableSetting
+        key="enabled"
+        title="Enable AI commit messages"
+        description="Adds a Generate button to the Source Control panel."
+        keywords={['ai', 'commit', 'message', 'generate', 'agent', 'enabled']}
+        className="flex items-center justify-between gap-4 px-1 py-2"
+      >
+        <div className="space-y-0.5">
+          <Label>Enable AI commit messages</Label>
+          <p className="text-xs text-muted-foreground">
+            Adds a Generate button to the Source Control panel that drafts a commit message from
+            your staged changes. Runs the agent CLI locally (or on the SSH host when working
+            remotely) and waits for the response.
+          </p>
+        </div>
+        <button
+          role="switch"
+          aria-checked={config.enabled}
+          onClick={onToggleEnabled}
+          className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-colors ${
+            config.enabled ? 'bg-foreground' : 'bg-muted-foreground/30'
+          }`}
+        >
+          <span
+            className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
+              config.enabled ? 'translate-x-4' : 'translate-x-0.5'
+            }`}
+          />
+        </button>
+      </SearchableSetting>
+    )
+  }
+
+  if (
+    config.enabled &&
+    matchesSettingsSearch(searchQuery, {
+      title: 'Agent',
+      description: 'Which agent to invoke when generating a commit message.',
+      keywords: ['agent', 'claude', 'codex']
+    })
+  ) {
+    sections.push(
+      <SearchableSetting
+        key="agent"
+        title="Agent"
+        description="Which agent to invoke when generating a commit message."
+        keywords={['agent', 'claude', 'codex']}
+        className="flex items-center justify-between gap-4 px-1 py-2"
+      >
+        <div className="space-y-0.5">
+          <Label>Agent</Label>
+          <p className="text-xs text-muted-foreground">
+            Which agent drafts your commit messages. Orca invokes its CLI in the background, so the
+            agent must be installed on the machine that hosts the worktree - your computer for local
+            worktrees, or the SSH host for remote ones.
+          </p>
+        </div>
+        <Select value={activeAgentId} onValueChange={onAgentChange}>
+          <SelectTrigger size="sm" className="h-8 text-xs w-[180px]">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {agentCapabilities.map((capability) => {
+              const id = capability.id
+              return (
+                <SelectItem key={id} value={id} className="cursor-pointer">
+                  <span className="flex items-center gap-2">
+                    <AgentIcon agent={id} size={14} />
+                    <span>{agentLabel(id, capability)}</span>
+                  </span>
+                </SelectItem>
+              )
+            })}
+            <SelectItem value={CUSTOM_AGENT_ID} className="cursor-pointer">
+              <span className="flex items-center gap-2">
+                <Terminal className="size-3.5" />
+                <span>Custom</span>
+              </span>
+            </SelectItem>
+          </SelectContent>
+        </Select>
+      </SearchableSetting>
+    )
+  }
+
+  if (
+    config.enabled &&
+    isCustom &&
+    matchesSettingsSearch(searchQuery, {
+      title: 'Custom command',
+      description: 'Command line Orca runs to generate the commit message.',
+      keywords: ['custom', 'command', 'cli', 'binary', 'prompt', 'placeholder']
+    })
+  ) {
+    sections.push(
+      <SearchableSetting
+        key="custom-command"
+        title="Custom command"
+        description="Command line Orca runs to generate the commit message."
+        keywords={['custom', 'command', 'cli', 'binary', 'prompt', 'placeholder']}
+        className="space-y-2 px-1 py-2"
+      >
+        <div className="space-y-0.5">
+          <Label htmlFor="commit-message-ai-custom-command">Custom command</Label>
+          <p className="text-xs text-muted-foreground">
+            Use{' '}
+            <code className="rounded bg-muted/60 px-1 py-0.5 text-[10px]">
+              {CUSTOM_PROMPT_PLACEHOLDER}
+            </code>{' '}
+            where the prompt should be substituted (passed as a single argument). Omit it and the
+            prompt is piped via stdin instead - useful for CLIs like{' '}
+            <code className="rounded bg-muted/60 px-1 py-0.5 text-[10px]">claude -p</code>. Quoting
+            is for grouping arguments only; we never invoke a shell, so{' '}
+            <code className="rounded bg-muted/60 px-1 py-0.5 text-[10px]">$VAR</code> and backticks
+            are not expanded.
+          </p>
+        </div>
+        <input
+          id="commit-message-ai-custom-command"
+          type="text"
+          spellCheck={false}
+          autoCorrect="off"
+          autoCapitalize="off"
+          value={config.customAgentCommand}
+          onChange={(e) => onCustomCommandChange(e.target.value)}
+          placeholder={`e.g. ollama run llama3.1 ${CUSTOM_PROMPT_PLACEHOLDER}`}
+          className="w-full rounded-md border border-border bg-background px-2 py-1.5 font-mono text-xs text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-1 focus-visible:ring-ring"
+        />
+      </SearchableSetting>
+    )
+  }
+
+  if (
+    config.enabled &&
+    activeCapability &&
+    activeModel &&
+    matchesSettingsSearch(searchQuery, {
+      title: 'Model',
+      description: 'Which model the selected agent uses to generate the message.',
+      keywords: ['model', 'haiku', 'sonnet', 'opus', 'gpt']
+    })
+  ) {
+    sections.push(
+      <SearchableSetting
+        key="model"
+        title="Model"
+        description="Which model the selected agent uses to generate the message."
+        keywords={['model', 'haiku', 'sonnet', 'opus', 'gpt']}
+        className="flex items-center justify-between gap-4 px-1 py-2"
+      >
+        <div className="space-y-0.5">
+          <Label>Model</Label>
+          <p className="text-xs text-muted-foreground">
+            Smaller models default to lower latency and cost. Pick a larger one if the diffs you
+            review tend to need more reasoning.
+          </p>
+        </div>
+        <Select value={activeModel.id} onValueChange={onModelChange}>
+          <SelectTrigger size="sm" className="h-8 text-xs w-[200px]">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {activeCapability.models.map((m) => (
+              <SelectItem key={m.id} value={m.id} className="cursor-pointer">
+                {m.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </SearchableSetting>
+    )
+  }
+
+  if (
+    config.enabled &&
+    activeModel?.thinkingLevels &&
+    activeThinking &&
+    matchesSettingsSearch(searchQuery, {
+      title: 'Thinking effort',
+      description: 'Reasoning effort level for the selected model. Higher levels are slower.',
+      keywords: ['thinking', 'effort', 'reasoning']
+    })
+  ) {
+    sections.push(
+      <SearchableSetting
+        key="thinking"
+        title="Thinking effort"
+        description="Reasoning effort level for the selected model. Higher levels are slower."
+        keywords={['thinking', 'effort', 'reasoning']}
+        className="flex items-center justify-between gap-4 px-1 py-2"
+      >
+        <div className="space-y-0.5">
+          <Label>Thinking effort</Label>
+          <p className="text-xs text-muted-foreground">
+            Higher effort produces more careful messages but takes longer and costs more tokens.
+          </p>
+        </div>
+        <Select value={activeThinking} onValueChange={onThinkingChange}>
+          <SelectTrigger size="sm" className="h-8 text-xs w-[160px]">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {activeModel.thinkingLevels.map((level) => (
+              <SelectItem key={level.id} value={level.id} className="cursor-pointer">
+                {level.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </SearchableSetting>
+    )
+  }
+
+  if (
+    config.enabled &&
+    matchesSettingsSearch(searchQuery, {
+      title: 'Custom prompt',
+      description:
+        'Optional instructions appended to the base prompt (e.g. Conventional Commits style).',
+      keywords: ['prompt', 'conventional commits', 'gitmoji', 'style']
+    })
+  ) {
+    sections.push(
+      <SearchableSetting
+        key="custom-prompt"
+        title="Custom prompt"
+        description="Optional instructions appended to the base prompt (e.g. Conventional Commits style)."
+        keywords={['prompt', 'conventional commits', 'gitmoji', 'style']}
+        className="space-y-2 px-1 py-2"
+      >
+        <div className="space-y-0.5">
+          <Label htmlFor="commit-message-ai-custom-prompt">Custom prompt</Label>
+          <p className="text-xs text-muted-foreground">
+            Appended verbatim to the base prompt. Use it to enforce Conventional Commits, gitmoji,
+            ticket prefixes, or any other style your team prefers.
+          </p>
+        </div>
+        <textarea
+          id="commit-message-ai-custom-prompt"
+          rows={4}
+          value={config.customPrompt}
+          onChange={(e) => onCustomPromptChange(e.target.value)}
+          placeholder="Use Conventional Commits format (feat:, fix:, ...). Reference the ticket key when present."
+          className="w-full resize-y rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-1 focus-visible:ring-ring"
+        />
+      </SearchableSetting>
+    )
+  }
+
+  if (sections.length === 0) {
+    return <div className="space-y-4" />
+  }
+  // Why: this pane lives nested inside the Git section, so we draw an explicit
+  // sub-heading + top border to keep its toggles visually distinct from the
+  // Branch Prefix / Refresh Local Base Ref / Orca Attribution rows above.
+  return (
+    <div className="space-y-4 border-t border-border/40 pt-4">
+      <div className="space-y-0.5">
+        <h3 className="text-sm font-semibold">AI Commit Messages</h3>
+        <p className="text-xs text-muted-foreground">
+          Generate commit messages from staged changes using a local agent CLI.
+        </p>
+      </div>
+      {sections}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 9e0cc8cb531..1af8e8a4979 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -43,6 +43,8 @@ import ghosttyIcon from '../../../../../resources/ghostty.svg'
 import { RepositoryPane, getRepositoryPaneSearchEntries } from './RepositoryPane'
 import { getTerminalPaneSearchEntries } from './terminal-search'
 import { GitPane, GIT_PANE_SEARCH_ENTRIES } from './GitPane'
+import { CommitMessageAiPane } from './CommitMessageAiPane'
+import { COMMIT_MESSAGE_AI_PANE_SEARCH_ENTRIES } from './commit-message-ai-search'
 import { NotificationsPane, NOTIFICATIONS_PANE_SEARCH_ENTRIES } from './NotificationsPane'
 import { VoicePane } from './VoicePane'
 import { VOICE_PANE_SEARCH_ENTRIES } from './voice-pane-search'
@@ -424,9 +426,12 @@ function Settings(): React.JSX.Element {
       {
         id: 'git',
         title: 'Git',
-        description: 'Branch naming and local ref behavior.',
+        description: 'Branch naming, local ref behavior, and AI commit messages.',
         icon: GitBranch,
-        searchEntries: GIT_PANE_SEARCH_ENTRIES
+        // Why: the AI commit messages pane is rendered inside the Git section,
+        // so its search entries belong to Git too — that way a query like
+        // "claude" or "thinking" still surfaces the section.
+        searchEntries: [...GIT_PANE_SEARCH_ENTRIES, ...COMMIT_MESSAGE_AI_PANE_SEARCH_ENTRIES]
       },
       {
         id: 'appearance',
@@ -759,14 +764,18 @@ function Settings(): React.JSX.Element {
                 <SettingsSection
                   id="git"
                   title="Git"
-                  description="Branch naming and local ref behavior."
-                  searchEntries={GIT_PANE_SEARCH_ENTRIES}
+                  description="Branch naming, local ref behavior, and AI commit messages."
+                  searchEntries={[
+                    ...GIT_PANE_SEARCH_ENTRIES,
+                    ...COMMIT_MESSAGE_AI_PANE_SEARCH_ENTRIES
+                  ]}
                 >
                   <GitPane
                     settings={settings}
                     updateSettings={updateSettings}
                     displayedGitUsername={displayedGitUsername}
                   />
+                  <CommitMessageAiPane settings={settings} updateSettings={updateSettings} />
                 </SettingsSection>
 
                 <SettingsSection
diff --git a/src/renderer/src/components/settings/commit-message-ai-search.ts b/src/renderer/src/components/settings/commit-message-ai-search.ts
new file mode 100644
index 00000000000..2dadc067471
--- /dev/null
+++ b/src/renderer/src/components/settings/commit-message-ai-search.ts
@@ -0,0 +1,45 @@
+import type { SettingsSearchEntry } from './settings-search'
+
+export const COMMIT_MESSAGE_AI_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
+  {
+    title: 'Enable AI commit messages',
+    description: 'Adds a Generate button to the Source Control panel.',
+    keywords: [
+      'ai',
+      'commit',
+      'message',
+      'generate',
+      'agent',
+      'claude',
+      'codex',
+      'source control',
+      'enabled'
+    ]
+  },
+  {
+    title: 'Agent',
+    description: 'Which agent to invoke when generating a commit message.',
+    keywords: ['agent', 'claude', 'codex']
+  },
+  {
+    title: 'Model',
+    description: 'Which model the selected agent uses to generate the message.',
+    keywords: ['model', 'haiku', 'sonnet', 'opus', 'gpt']
+  },
+  {
+    title: 'Thinking effort',
+    description: 'Reasoning effort level for the selected model. Higher levels are slower.',
+    keywords: ['thinking', 'effort', 'reasoning']
+  },
+  {
+    title: 'Custom prompt',
+    description:
+      'Optional instructions appended to the base prompt (e.g. Conventional Commits style).',
+    keywords: ['prompt', 'conventional commits', 'gitmoji', 'style']
+  },
+  {
+    title: 'Custom command',
+    description: 'Command line Orca runs to generate the commit message.',
+    keywords: ['custom', 'command', 'cli', 'binary', 'prompt', 'placeholder', 'ollama']
+  }
+]
diff --git a/src/shared/commit-message-agent-spec.test.ts b/src/shared/commit-message-agent-spec.test.ts
new file mode 100644
index 00000000000..d6f6ed158ad
--- /dev/null
+++ b/src/shared/commit-message-agent-spec.test.ts
@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest'
+import {
+  COMMIT_MESSAGE_AGENT_SPECS,
+  CUSTOM_AGENT_ID,
+  DEFAULT_COMMIT_MESSAGE_AGENT_ID,
+  getCommitMessageAgentCapability,
+  getCommitMessageAgentSpec,
+  getCommitMessageModelCapability,
+  getCommitMessageModel,
+  isCustomAgentId,
+  listCommitMessageAgentCapabilities,
+  listCommitMessageAgentIds
+} from './commit-message-agent-spec'
+
+describe('COMMIT_MESSAGE_AGENT_SPECS', () => {
+  it('exposes Claude and Codex as the v1 agents', () => {
+    const ids = listCommitMessageAgentIds().sort()
+    expect(ids).toEqual(['claude', 'codex'])
+  })
+
+  it('uses the smallest model as the default for each agent', () => {
+    expect(COMMIT_MESSAGE_AGENT_SPECS.claude?.defaultModelId).toBe('claude-haiku-4-5')
+    expect(COMMIT_MESSAGE_AGENT_SPECS.codex?.defaultModelId).toBe('gpt-5.4-mini')
+  })
+
+  it('defaults the agent picker to Claude', () => {
+    expect(DEFAULT_COMMIT_MESSAGE_AGENT_ID).toBe('claude')
+  })
+
+  it('defaults every model with thinking levels to "low"', () => {
+    for (const spec of Object.values(COMMIT_MESSAGE_AGENT_SPECS)) {
+      if (!spec) {
+        continue
+      }
+      for (const model of spec.models) {
+        if (model.thinkingLevels) {
+          expect(model.defaultThinkingLevel).toBe('low')
+          expect(model.thinkingLevels.some((l) => l.id === 'low')).toBe(true)
+        }
+      }
+    }
+  })
+
+  it('exposes thinking levels on the Spark variant (it accepts model_reasoning_effort)', () => {
+    const spark = getCommitMessageModel('codex', 'gpt-5.3-codex-spark')
+    expect(spark).toBeDefined()
+    expect(spark?.thinkingLevels?.map((l) => l.id)).toEqual(['low', 'medium', 'high', 'xhigh'])
+    expect(spark?.defaultThinkingLevel).toBe('low')
+  })
+
+  it('omits thinking levels on Claude Haiku 4.5 (non-reasoning model)', () => {
+    const haiku = getCommitMessageModel('claude', 'claude-haiku-4-5')
+    expect(haiku).toBeDefined()
+    expect(haiku?.thinkingLevels).toBeUndefined()
+    expect(haiku?.defaultThinkingLevel).toBeUndefined()
+  })
+
+  it('identifies the custom sentinel via isCustomAgentId', () => {
+    expect(isCustomAgentId(CUSTOM_AGENT_ID)).toBe(true)
+    expect(isCustomAgentId('claude')).toBe(false)
+    expect(isCustomAgentId('codex')).toBe(false)
+    expect(isCustomAgentId(null)).toBe(false)
+    expect(isCustomAgentId(undefined)).toBe(false)
+  })
+
+  it('does not list "custom" alongside preset agent ids', () => {
+    expect(listCommitMessageAgentIds()).not.toContain(CUSTOM_AGENT_ID)
+  })
+
+  it('orders Codex models by version descending to match the official picker', () => {
+    const ids = COMMIT_MESSAGE_AGENT_SPECS.codex?.models.map((m) => m.id)
+    expect(ids).toEqual([
+      'gpt-5.5',
+      'gpt-5.4',
+      'gpt-5.4-mini',
+      'gpt-5.3-codex',
+      'gpt-5.3-codex-spark',
+      'gpt-5.2'
+    ])
+  })
+
+  it('exposes UI capabilities without spawn details', () => {
+    const capabilities = listCommitMessageAgentCapabilities()
+    expect(capabilities.map((capability) => capability.id).sort()).toEqual(['claude', 'codex'])
+    const codex = getCommitMessageAgentCapability('codex')
+    expect(codex).toMatchObject({
+      id: 'codex',
+      label: 'Codex',
+      defaultModelId: 'gpt-5.4-mini'
+    })
+    expect(codex).not.toHaveProperty('binary')
+    expect(codex).not.toHaveProperty('buildArgs')
+    expect(getCommitMessageModelCapability('codex', 'gpt-5.4-mini')?.thinkingLevels).toBeDefined()
+  })
+})
+
+describe('buildArgs (Claude)', () => {
+  const spec = getCommitMessageAgentSpec('claude')!
+
+  it('passes -p, output format, and model on every call', () => {
+    const args = spec.buildArgs({ prompt: '', model: 'claude-haiku-4-5' })
+    expect(args).toEqual(['-p', '--output-format', 'text', '--model', 'claude-haiku-4-5'])
+  })
+
+  it('appends --effort when a thinking level is supplied', () => {
+    const args = spec.buildArgs({
+      prompt: '',
+      model: 'claude-sonnet-4-6',
+      thinkingLevel: 'high'
+    })
+    expect(args).toEqual([
+      '-p',
+      '--output-format',
+      'text',
+      '--model',
+      'claude-sonnet-4-6',
+      '--effort',
+      'high'
+    ])
+  })
+
+  it('omits --effort when thinkingLevel is not provided', () => {
+    const args = spec.buildArgs({ prompt: '', model: 'claude-opus-4-7' })
+    expect(args).not.toContain('--effort')
+  })
+})
+
+describe('buildArgs (Codex)', () => {
+  const spec = getCommitMessageAgentSpec('codex')!
+
+  it('runs `codex exec` without passing the prompt via argv', () => {
+    const args = spec.buildArgs({
+      prompt: 'PROMPT',
+      model: 'gpt-5.4-mini'
+    })
+    expect(args[0]).toBe('exec')
+    expect(args).toEqual([
+      'exec',
+      '--ephemeral',
+      '--skip-git-repo-check',
+      '-s',
+      'read-only',
+      '--model',
+      'gpt-5.4-mini'
+    ])
+    expect(args).toContain('--model')
+    expect(args).not.toContain('PROMPT')
+    expect(spec.promptDelivery).toBe('stdin')
+  })
+
+  it('emits -c model_reasoning_effort=<level> when thinking level is supplied', () => {
+    const args = spec.buildArgs({
+      prompt: 'PROMPT',
+      model: 'gpt-5.4',
+      thinkingLevel: 'medium'
+    })
+    expect(args).toContain('-c')
+    expect(args).toContain('model_reasoning_effort=medium')
+  })
+
+  it('omits the -c flag when no thinking level is supplied', () => {
+    const args = spec.buildArgs({ prompt: 'PROMPT', model: 'gpt-5.4-mini' })
+    expect(args).not.toContain('-c')
+  })
+})
diff --git a/src/shared/commit-message-agent-spec.ts b/src/shared/commit-message-agent-spec.ts
new file mode 100644
index 00000000000..af4f366cc77
--- /dev/null
+++ b/src/shared/commit-message-agent-spec.ts
@@ -0,0 +1,266 @@
+import type { TuiAgent } from './types'
+
+// Why: this file is the source of truth for non-interactive agent invocation
+// (commit-message generation). It is intentionally separate from
+// `tui-agent-config.ts`, which describes interactive PTY launching — mixing
+// the two confuses both code paths.
+
+export type ThinkingLevel = { id: string; label: string }
+
+export type CommitMessageModel = {
+  /** Value passed to the agent CLI's --model flag. */
+  id: string
+  /** Visible label in the model dropdown. */
+  label: string
+  /** Omit when the model does not expose an effort selector — the UI then hides the dropdown. */
+  thinkingLevels?: ThinkingLevel[]
+  /** Required when thinkingLevels is present. */
+  defaultThinkingLevel?: string
+}
+
+export type CommitMessageAgentSpec = {
+  id: TuiAgent
+  /** Visible label in the agent dropdown. */
+  label: string
+  /** Binary spawned in non-interactive mode. */
+  binary: string
+  /** Where the prompt is delivered. Large diffs go via stdin to avoid argv limits. */
+  promptDelivery: 'argv' | 'stdin'
+  buildArgs: (params: { prompt: string; model: string; thinkingLevel?: string }) => string[]
+  models: CommitMessageModel[]
+  defaultModelId: string
+}
+
+export type CommitMessageModelCapability = {
+  id: string
+  label: string
+  thinkingLevels?: ThinkingLevel[]
+  defaultThinkingLevel?: string
+}
+
+export type CommitMessageAgentCapability = {
+  id: TuiAgent
+  label: string
+  models: CommitMessageModelCapability[]
+  defaultModelId: string
+}
+
+export const COMMIT_MESSAGE_AGENT_SPECS: Partial<Record<TuiAgent, CommitMessageAgentSpec>> = {
+  claude: {
+    id: 'claude',
+    label: 'Claude',
+    binary: 'claude',
+    // Why: diffs can be large and `claude -p` reads from stdin natively when no
+    // positional prompt is provided.
+    promptDelivery: 'stdin',
+    buildArgs: ({ model, thinkingLevel }) => [
+      '-p',
+      '--output-format',
+      'text',
+      '--model',
+      model,
+      ...(thinkingLevel ? ['--effort', thinkingLevel] : [])
+    ],
+    models: [
+      {
+        // Why: Haiku 4.5 is a non-reasoning model — `claude --effort` rejects
+        // any value for it. Omit thinkingLevels so the UI hides the dropdown
+        // and the buildArgs path skips passing --effort entirely.
+        id: 'claude-haiku-4-5',
+        label: 'Haiku 4.5'
+      },
+      {
+        id: 'claude-sonnet-4-6',
+        label: 'Sonnet 4.6',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' },
+          { id: 'max', label: 'Max' }
+        ],
+        defaultThinkingLevel: 'low'
+      },
+      {
+        id: 'claude-opus-4-7',
+        label: 'Opus 4.7',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' },
+          { id: 'max', label: 'Max' }
+        ],
+        defaultThinkingLevel: 'low'
+      }
+    ],
+    defaultModelId: 'claude-haiku-4-5'
+  },
+  codex: {
+    id: 'codex',
+    label: 'Codex',
+    binary: 'codex',
+    // Why: `codex exec` reads stdin when no prompt arg is supplied. Commit
+    // prompts include large staged diffs, so argv would exceed Windows and
+    // some SSH/POSIX command-line limits.
+    promptDelivery: 'stdin',
+    buildArgs: ({ model, thinkingLevel }) => [
+      'exec',
+      // Why: commit-message generation needs text only, not a persisted agent
+      // session or workspace writes. Match T3 Code's safe git-text mode.
+      '--ephemeral',
+      '--skip-git-repo-check',
+      '-s',
+      'read-only',
+      '--model',
+      model,
+      ...(thinkingLevel ? ['-c', `model_reasoning_effort=${thinkingLevel}`] : [])
+    ],
+    // Why: ordered to match the official `codex` model picker — descending
+    // by version so the frontier model lands on top and legacy models trail.
+    // Default still resolves by id (`gpt-5.4-mini`), independent of order.
+    models: [
+      {
+        id: 'gpt-5.5',
+        label: 'GPT-5.5',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' }
+        ],
+        defaultThinkingLevel: 'low'
+      },
+      {
+        id: 'gpt-5.4',
+        label: 'GPT-5.4',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' }
+        ],
+        defaultThinkingLevel: 'low'
+      },
+      {
+        id: 'gpt-5.4-mini',
+        label: 'GPT-5.4 Mini',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' }
+        ],
+        defaultThinkingLevel: 'low'
+      },
+      {
+        id: 'gpt-5.3-codex',
+        label: 'GPT-5.3 Codex',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' }
+        ],
+        defaultThinkingLevel: 'low'
+      },
+      {
+        // Why: Codex's Spark variant accepts `model_reasoning_effort` (the
+        // CLI banner reports "reasoning effort: medium" by default); the
+        // gating that surfaces "model not supported" is on the account
+        // tier, not the effort flag.
+        id: 'gpt-5.3-codex-spark',
+        label: 'GPT-5.3 Codex Spark',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' }
+        ],
+        defaultThinkingLevel: 'low'
+      },
+      {
+        id: 'gpt-5.2',
+        label: 'GPT-5.2',
+        thinkingLevels: [
+          { id: 'low', label: 'Low' },
+          { id: 'medium', label: 'Medium' },
+          { id: 'high', label: 'High' },
+          { id: 'xhigh', label: 'Extra High' }
+        ],
+        defaultThinkingLevel: 'low'
+      }
+    ],
+    defaultModelId: 'gpt-5.4-mini'
+  }
+}
+
+export const DEFAULT_COMMIT_MESSAGE_AGENT_ID: TuiAgent = 'claude'
+
+// Why: the "custom" choice is not a TuiAgent — it lets the user point Orca
+// at any CLI by typing a command template (see customAgentCommand setting +
+// planCustomCommand in commit-message-prompt.ts). Keeping it as its own
+// sentinel avoids polluting TuiAgent (which is shared with PTY launch /
+// new-workspace flows that have nothing to do with this feature).
+export const CUSTOM_AGENT_ID = 'custom' as const
+export type CustomAgentId = typeof CUSTOM_AGENT_ID
+export type CommitMessageAgentChoice = TuiAgent | CustomAgentId
+
+export function isCustomAgentId(id: string | null | undefined): id is CustomAgentId {
+  return id === CUSTOM_AGENT_ID
+}
+
+export function getCommitMessageAgentSpec(agentId: TuiAgent): CommitMessageAgentSpec | undefined {
+  return COMMIT_MESSAGE_AGENT_SPECS[agentId]
+}
+
+export function getCommitMessageModel(
+  agentId: TuiAgent,
+  modelId: string
+): CommitMessageModel | undefined {
+  return getCommitMessageAgentSpec(agentId)?.models.find((m) => m.id === modelId)
+}
+
+function toCommitMessageAgentCapability(
+  spec: CommitMessageAgentSpec
+): CommitMessageAgentCapability {
+  return {
+    id: spec.id,
+    label: spec.label,
+    defaultModelId: spec.defaultModelId,
+    // Why: renderer/settings should consume provider capabilities, not the
+    // spawn contract. Copy the model metadata so future dynamic probes can
+    // swap this source without leaking binary/argv details into UI code.
+    models: spec.models.map((model) => ({
+      id: model.id,
+      label: model.label,
+      ...(model.thinkingLevels ? { thinkingLevels: [...model.thinkingLevels] } : {}),
+      ...(model.defaultThinkingLevel ? { defaultThinkingLevel: model.defaultThinkingLevel } : {})
+    }))
+  }
+}
+
+export function getCommitMessageAgentCapability(
+  agentId: TuiAgent
+): CommitMessageAgentCapability | undefined {
+  const spec = getCommitMessageAgentSpec(agentId)
+  return spec ? toCommitMessageAgentCapability(spec) : undefined
+}
+
+export function getCommitMessageModelCapability(
+  agentId: TuiAgent,
+  modelId: string
+): CommitMessageModelCapability | undefined {
+  return getCommitMessageAgentCapability(agentId)?.models.find((m) => m.id === modelId)
+}
+
+/** Ordered list of agents that have a non-interactive mode wired up. */
+export function listCommitMessageAgentIds(): TuiAgent[] {
+  return Object.keys(COMMIT_MESSAGE_AGENT_SPECS) as TuiAgent[]
+}
+
+export function listCommitMessageAgentCapabilities(): CommitMessageAgentCapability[] {
+  return listCommitMessageAgentIds()
+    .map((id) => getCommitMessageAgentCapability(id))
+    .filter((capability): capability is CommitMessageAgentCapability => Boolean(capability))
+}
diff --git a/src/shared/commit-message-generation.test.ts b/src/shared/commit-message-generation.test.ts
new file mode 100644
index 00000000000..4a0c7512285
--- /dev/null
+++ b/src/shared/commit-message-generation.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { buildCommitMessagePrompt, splitGeneratedCommitMessage } from './commit-message-generation'
+
+describe('buildCommitMessagePrompt', () => {
+  it('builds a prompt from staged context instead of asking the agent to inspect git', () => {
+    const prompt = buildCommitMessagePrompt(
+      {
+        branch: 'feature/commit-drafts',
+        stagedSummary: 'M\tsrc/main/ipc/filesystem.ts',
+        stagedPatch: 'diff --git a/src/main/ipc/filesystem.ts b/src/main/ipc/filesystem.ts\n+hello'
+      },
+      ''
+    )
+
+    expect(prompt).toContain('Branch: feature/commit-drafts')
+    expect(prompt).toContain('Staged files:\nM\tsrc/main/ipc/filesystem.ts')
+    expect(prompt).toContain('Staged patch:\n```diff')
+    expect(prompt).toContain('+hello')
+    expect(prompt).toContain('Use only the staged changes below as context.')
+    expect(prompt).not.toContain('Additional instructions from user:')
+  })
+
+  it('keeps custom instructions in a separate bounded section', () => {
+    const prompt = buildCommitMessagePrompt(
+      {
+        branch: null,
+        stagedSummary: 'A\tREADME.md',
+        stagedPatch: '+docs'
+      },
+      'Use Conventional Commits.'
+    )
+
+    expect(prompt).toContain('Branch: (detached)')
+    expect(prompt).toContain('Additional instructions from user:\nUse Conventional Commits.')
+  })
+})
+
+describe('splitGeneratedCommitMessage', () => {
+  it('normalizes subject and preserves body text', () => {
+    const result = splitGeneratedCommitMessage(
+      'Fix source control generation.\n\n- Move planning into main'
+    )
+
+    expect(result).toEqual({
+      subject: 'Fix source control generation',
+      body: '- Move planning into main',
+      message: 'Fix source control generation\n\n- Move planning into main'
+    })
+  })
+})
diff --git a/src/shared/commit-message-generation.ts b/src/shared/commit-message-generation.ts
new file mode 100644
index 00000000000..2c3eee8c1ab
--- /dev/null
+++ b/src/shared/commit-message-generation.ts
@@ -0,0 +1,84 @@
+import { cleanGeneratedCommitMessage, truncateDiffForPrompt } from './commit-message-prompt'
+import type { TuiAgent } from './types'
+
+export type CommitMessageDraftAgent = TuiAgent | 'custom'
+
+export type CommitMessageDraftContext = {
+  branch: string | null
+  stagedSummary: string
+  stagedPatch: string
+}
+
+export type CommitMessageDraftOptions = {
+  agentId: CommitMessageDraftAgent
+  model: string
+  thinkingLevel?: string
+  customPrompt?: string
+  customAgentCommand?: string
+}
+
+export type GeneratedCommitMessage = {
+  subject: string
+  body: string
+  message: string
+}
+
+function limitSection(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value
+  }
+  const omitted = value.length - maxChars
+  return `${value.slice(0, maxChars)}\n\n[truncated: ${omitted} characters omitted]`
+}
+
+export function buildCommitMessagePrompt(
+  context: CommitMessageDraftContext,
+  customInstructions: string
+): string {
+  const patch = truncateDiffForPrompt(context.stagedPatch)
+  const base = [
+    'You are generating a single git commit message.',
+    'Return only the commit message text. Do not include a preamble, quotes, or code fences.',
+    '',
+    'Rules:',
+    '- First line: imperative mood, <= 72 chars, no trailing period.',
+    '- Optional body: blank line, then short wrapped bullet points or prose explaining WHY.',
+    '- Capture the primary user-visible or developer-visible change.',
+    '- Use only the staged changes below as context.',
+    '- Do not include "Co-authored-by" trailers - Orca appends them after generation when configured.',
+    '',
+    `Branch: ${context.branch ?? '(detached)'}`,
+    '',
+    'Staged files:',
+    limitSection(context.stagedSummary, 6_000),
+    '',
+    'Staged patch:',
+    '```diff',
+    patch,
+    '```'
+  ].join('\n')
+
+  const trimmedInstructions = customInstructions.trim()
+  if (!trimmedInstructions) {
+    return base
+  }
+  return [
+    base,
+    '',
+    'Additional instructions from user:',
+    limitSection(trimmedInstructions, 4_000)
+  ].join('\n')
+}
+
+export function splitGeneratedCommitMessage(message: string): GeneratedCommitMessage {
+  const normalized = cleanGeneratedCommitMessage(message)
+  const [subjectLine = '', ...bodyLines] = normalized.split('\n')
+  const subject = subjectLine.trim().replace(/[.]+$/g, '').slice(0, 72).trimEnd()
+  const body = bodyLines.join('\n').trim()
+  const safeSubject = subject.length > 0 ? subject : 'Update project files'
+  return {
+    subject: safeSubject,
+    body,
+    message: body.length > 0 ? `${safeSubject}\n\n${body}` : safeSubject
+  }
+}
diff --git a/src/shared/commit-message-plan.test.ts b/src/shared/commit-message-plan.test.ts
new file mode 100644
index 00000000000..d8294278ea3
--- /dev/null
+++ b/src/shared/commit-message-plan.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import { planCommitMessageGeneration } from './commit-message-plan'
+
+describe('planCommitMessageGeneration', () => {
+  it('plans Claude non-interactive generation with the prompt on stdin only', () => {
+    const result = planCommitMessageGeneration(
+      {
+        agentId: 'claude',
+        model: 'claude-sonnet-4-6',
+        thinkingLevel: 'high'
+      },
+      'PROMPT'
+    )
+
+    expect(result).toEqual({
+      ok: true,
+      plan: {
+        binary: 'claude',
+        args: ['-p', '--output-format', 'text', '--model', 'claude-sonnet-4-6', '--effort', 'high'],
+        stdinPayload: 'PROMPT',
+        label: 'Claude'
+      }
+    })
+  })
+
+  it('plans Codex exec as non-interactive read-only generation with the prompt on stdin only', () => {
+    const result = planCommitMessageGeneration(
+      {
+        agentId: 'codex',
+        model: 'gpt-5.4-mini',
+        thinkingLevel: 'medium'
+      },
+      'PROMPT'
+    )
+
+    expect(result).toEqual({
+      ok: true,
+      plan: {
+        binary: 'codex',
+        args: [
+          'exec',
+          '--ephemeral',
+          '--skip-git-repo-check',
+          '-s',
+          'read-only',
+          '--model',
+          'gpt-5.4-mini',
+          '-c',
+          'model_reasoning_effort=medium'
+        ],
+        stdinPayload: 'PROMPT',
+        label: 'Codex'
+      }
+    })
+  })
+
+  it('uses preset agent command overrides as the spawn command prefix', () => {
+    const result = planCommitMessageGeneration(
+      {
+        agentId: 'codex',
+        model: 'gpt-5.4-mini',
+        agentCommandOverride: 'npx codex'
+      },
+      'PROMPT'
+    )
+
+    expect(result).toMatchObject({
+      ok: true,
+      plan: {
+        binary: 'npx',
+        args: [
+          'codex',
+          'exec',
+          '--ephemeral',
+          '--skip-git-repo-check',
+          '-s',
+          'read-only',
+          '--model',
+          'gpt-5.4-mini'
+        ],
+        stdinPayload: 'PROMPT'
+      }
+    })
+  })
+
+  it('rejects invalid preset agent command overrides before spawning', () => {
+    const result = planCommitMessageGeneration(
+      {
+        agentId: 'claude',
+        model: 'claude-haiku-4-5',
+        agentCommandOverride: 'claude "unterminated'
+      },
+      'PROMPT'
+    )
+
+    expect(result).toEqual({
+      ok: false,
+      error: 'Agent command override is invalid: Unclosed quote in command template.'
+    })
+  })
+})
diff --git a/src/shared/commit-message-plan.ts b/src/shared/commit-message-plan.ts
new file mode 100644
index 00000000000..7dd7ccf6107
--- /dev/null
+++ b/src/shared/commit-message-plan.ts
@@ -0,0 +1,127 @@
+import {
+  getCommitMessageAgentSpec,
+  getCommitMessageModel,
+  isCustomAgentId
+} from './commit-message-agent-spec'
+import { planCustomCommand, tokenizeCustomCommandTemplate } from './commit-message-prompt'
+import type { TuiAgent } from './types'
+
+// Why: planning is a pure transformation from "user request + prompt text"
+// into "spawn-ready binary + argv". Keeping it in shared lets both the local
+// generator (main process) and the SSH provider (which delegates to the
+// relay over JSON-RPC) reuse the exact same validation and arg-building
+// logic without duplicating the spec/model/thinking checks.
+
+export type CommitMessagePlanInput = {
+  agentId: TuiAgent | 'custom'
+  model: string
+  thinkingLevel?: string
+  customAgentCommand?: string
+  agentCommandOverride?: string
+}
+
+export type CommitMessagePlan = {
+  binary: string
+  args: string[]
+  /** Non-null when the prompt should be piped via stdin. */
+  stdinPayload: string | null
+  /** Human-readable label used in error prefixes (e.g. "Claude failed: ..."). */
+  label: string
+}
+
+export type CommitMessagePlanResult =
+  | { ok: true; plan: CommitMessagePlan }
+  | { ok: false; error: string }
+
+function planAgentBinary(
+  defaultBinary: string,
+  commandOverride: string | undefined
+): { ok: true; binary: string; prefixArgs: string[] } | { ok: false; error: string } {
+  const command = commandOverride?.trim()
+  if (!command) {
+    return { ok: true, binary: defaultBinary, prefixArgs: [] }
+  }
+
+  const tokenized = tokenizeCustomCommandTemplate(command)
+  if (!tokenized.ok) {
+    return { ok: false, error: `Agent command override is invalid: ${tokenized.error}` }
+  }
+  const [binary, ...prefixArgs] = tokenized.tokens
+  if (!binary) {
+    return { ok: false, error: 'Agent command override must start with a binary name.' }
+  }
+  return { ok: true, binary, prefixArgs }
+}
+
+export function planCommitMessageGeneration(
+  input: CommitMessagePlanInput,
+  prompt: string
+): CommitMessagePlanResult {
+  if (isCustomAgentId(input.agentId)) {
+    const command = input.customAgentCommand?.trim() ?? ''
+    if (!command) {
+      return {
+        ok: false,
+        error: 'Custom command is empty. Add one in Settings → Git → AI Commit Messages.'
+      }
+    }
+    const planned = planCustomCommand(command, prompt)
+    if (!planned.ok) {
+      return { ok: false, error: planned.error }
+    }
+    return {
+      ok: true,
+      plan: {
+        binary: planned.binary,
+        args: planned.args,
+        stdinPayload: planned.stdinPayload,
+        // Why: a custom command has no friendly name, so the binary doubles
+        // as the label in error prefixes ("ollama failed: ...").
+        label: planned.binary
+      }
+    }
+  }
+
+  const spec = getCommitMessageAgentSpec(input.agentId)
+  if (!spec) {
+    return { ok: false, error: `Agent "${input.agentId}" does not support AI commit messages.` }
+  }
+  const model = getCommitMessageModel(input.agentId, input.model)
+  if (!model) {
+    return { ok: false, error: `Model "${input.model}" is not available for ${spec.label}.` }
+  }
+  if (input.thinkingLevel) {
+    if (!model.thinkingLevels) {
+      return {
+        ok: false,
+        error: `Model "${model.label}" does not support a thinking effort level.`
+      }
+    }
+    if (!model.thinkingLevels.some((l) => l.id === input.thinkingLevel)) {
+      return {
+        ok: false,
+        error: `Thinking level "${input.thinkingLevel}" is not valid for ${model.label}.`
+      }
+    }
+  }
+
+  const argvPrompt = spec.promptDelivery === 'argv' ? prompt : ''
+  const args = spec.buildArgs({
+    prompt: argvPrompt,
+    model: input.model,
+    thinkingLevel: input.thinkingLevel
+  })
+  const command = planAgentBinary(spec.binary, input.agentCommandOverride)
+  if (!command.ok) {
+    return { ok: false, error: command.error }
+  }
+  return {
+    ok: true,
+    plan: {
+      binary: command.binary,
+      args: [...command.prefixArgs, ...args],
+      stdinPayload: spec.promptDelivery === 'stdin' ? prompt : null,
+      label: spec.label
+    }
+  }
+}
diff --git a/src/shared/commit-message-prompt.test.ts b/src/shared/commit-message-prompt.test.ts
new file mode 100644
index 00000000000..dfaa39fa1bb
--- /dev/null
+++ b/src/shared/commit-message-prompt.test.ts
@@ -0,0 +1,203 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildCommitPrompt,
+  cleanGeneratedCommitMessage,
+  extractAgentErrorMessage,
+  planCustomCommand,
+  STAGED_DIFF_BYTE_BUDGET,
+  tokenizeCustomCommandTemplate,
+  truncateDiffForPrompt
+} from './commit-message-prompt'
+
+describe('buildCommitPrompt', () => {
+  it('embeds the diff into the base prompt', () => {
+    const prompt = buildCommitPrompt('diff --git a/foo b/foo\n+hello', '')
+    expect(prompt).toContain('diff --git a/foo b/foo')
+    expect(prompt).toContain('+hello')
+    expect(prompt).toContain('First line: imperative mood')
+  })
+
+  it('appends a custom suffix when non-empty', () => {
+    const prompt = buildCommitPrompt('diff', 'Use Conventional Commits.')
+    expect(prompt).toContain('Additional instructions from user:')
+    expect(prompt.endsWith('Use Conventional Commits.')).toBe(true)
+  })
+
+  it('does not append the suffix block for whitespace-only suffixes', () => {
+    const prompt = buildCommitPrompt('diff', '   \n  ')
+    expect(prompt).not.toContain('Additional instructions from user:')
+  })
+})
+
+describe('truncateDiffForPrompt', () => {
+  it('returns the diff unchanged when within budget', () => {
+    const diff = 'line\n'.repeat(10)
+    expect(truncateDiffForPrompt(diff)).toBe(diff)
+  })
+
+  it('truncates and appends a marker when over budget', () => {
+    const oversized = 'A'.repeat(STAGED_DIFF_BYTE_BUDGET + 100)
+    const result = truncateDiffForPrompt(oversized)
+    expect(result.length).toBeLessThan(oversized.length)
+    expect(result).toMatch(/diff truncated, 100 bytes omitted/)
+  })
+
+  it('honors a custom budget', () => {
+    const result = truncateDiffForPrompt('abcdefghij', 5)
+    expect(result.startsWith('abcde')).toBe(true)
+    expect(result).toMatch(/diff truncated, 5 bytes omitted/)
+  })
+})
+
+describe('cleanGeneratedCommitMessage', () => {
+  it('trims whitespace', () => {
+    expect(cleanGeneratedCommitMessage('  feat: hello  \n')).toBe('feat: hello')
+  })
+
+  it('strips a single enclosing fenced code block', () => {
+    const raw = '```\nfeat: hello\n```'
+    expect(cleanGeneratedCommitMessage(raw)).toBe('feat: hello')
+  })
+
+  it('strips a fenced block with a language tag', () => {
+    const raw = '```text\nfix: bug\n```'
+    expect(cleanGeneratedCommitMessage(raw)).toBe('fix: bug')
+  })
+
+  it('drops a leading "Generating…" preamble line', () => {
+    const raw = 'Generating…\nfeat: hello world'
+    expect(cleanGeneratedCommitMessage(raw)).toBe('feat: hello world')
+  })
+
+  it('normalizes CRLF line endings', () => {
+    expect(cleanGeneratedCommitMessage('feat: a\r\nbody line\r\n')).toBe('feat: a\nbody line')
+  })
+
+  it('returns empty string when input is whitespace', () => {
+    expect(cleanGeneratedCommitMessage('   \n\t')).toBe('')
+  })
+})
+
+describe('extractAgentErrorMessage', () => {
+  it('returns the inner message from a Codex JSON error payload', () => {
+    const stderr = [
+      '--------',
+      'workdir: C:\\Storage\\Projects\\bagplanner',
+      'model: gpt-5.3-codex-spark',
+      'reasoning effort: medium',
+      '--------',
+      'user',
+      'You are generating a single git commit message...',
+      'hook: SessionStart',
+      'hook: SessionStart Completed',
+      'ERROR: {"type":"error","status":400,"error":{"type":"invalid_request_error","message":"The \'gpt-5.3-codex-spark\' model is not supported when using Codex with a ChatGPT account."}}'
+    ].join('\n')
+    expect(extractAgentErrorMessage('', stderr)).toBe(
+      "The 'gpt-5.3-codex-spark' model is not supported when using Codex with a ChatGPT account."
+    )
+  })
+
+  it('returns the payload for non-JSON error lines', () => {
+    const out = 'preamble line\nERROR: {bad json oops'
+    expect(extractAgentErrorMessage(out, '')).toBe('{bad json oops')
+  })
+
+  it('uses the last ERROR line when several are emitted', () => {
+    const out = ['ERROR: first failure', 'retry message', 'ERROR: second failure'].join('\n')
+    expect(extractAgentErrorMessage(out, '')).toBe('second failure')
+  })
+
+  it('matches an `Error:` line emitted on stdout', () => {
+    expect(extractAgentErrorMessage('Error: model unavailable\n', '')).toBe('model unavailable')
+  })
+
+  it('returns null when no ERROR line is present', () => {
+    expect(extractAgentErrorMessage('plain log\nmore log\n', '')).toBeNull()
+  })
+
+  it('returns the JSON payload `message` field when no nested error is set', () => {
+    const out = 'ERROR: {"message":"top-level only"}'
+    expect(extractAgentErrorMessage(out, '')).toBe('top-level only')
+  })
+})
+
+describe('tokenizeCustomCommandTemplate', () => {
+  it('splits on whitespace', () => {
+    const r = tokenizeCustomCommandTemplate('claude -p')
+    expect(r).toEqual({ ok: true, tokens: ['claude', '-p'] })
+  })
+
+  it('groups double-quoted segments with spaces', () => {
+    const r = tokenizeCustomCommandTemplate('claude --msg "hello world"')
+    expect(r).toEqual({ ok: true, tokens: ['claude', '--msg', 'hello world'] })
+  })
+
+  it('groups single-quoted segments verbatim', () => {
+    const r = tokenizeCustomCommandTemplate(`agent --json '{"k":"v"}'`)
+    expect(r).toEqual({ ok: true, tokens: ['agent', '--json', '{"k":"v"}'] })
+  })
+
+  it('honors backslash escapes inside double quotes', () => {
+    const r = tokenizeCustomCommandTemplate('claude --msg "she said \\"hi\\""')
+    expect(r).toEqual({ ok: true, tokens: ['claude', '--msg', 'she said "hi"'] })
+  })
+
+  it('keeps adjacent quoted/unquoted regions in one token (a"b"c → abc)', () => {
+    const r = tokenizeCustomCommandTemplate('foo a"b"c')
+    expect(r).toEqual({ ok: true, tokens: ['foo', 'abc'] })
+  })
+
+  it('returns an error for an unclosed quote', () => {
+    const r = tokenizeCustomCommandTemplate('claude --msg "no end')
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.error).toMatch(/unclosed/i)
+    }
+  })
+
+  it('returns an empty token list for whitespace-only input', () => {
+    const r = tokenizeCustomCommandTemplate('   \t  ')
+    expect(r).toEqual({ ok: true, tokens: [] })
+  })
+})
+
+describe('planCustomCommand', () => {
+  it('routes prompt via stdin when {prompt} is absent', () => {
+    const r = planCustomCommand('claude -p', 'COMMIT MSG')
+    expect(r).toEqual({ ok: true, binary: 'claude', args: ['-p'], stdinPayload: 'COMMIT MSG' })
+  })
+
+  it('substitutes {prompt} as a whole token via argv', () => {
+    const r = planCustomCommand('codex exec {prompt}', 'PROMPT')
+    expect(r).toEqual({ ok: true, binary: 'codex', args: ['exec', 'PROMPT'], stdinPayload: null })
+  })
+
+  it('treats "{prompt}" identically to bare {prompt} (no shell, no double-quoting)', () => {
+    const a = planCustomCommand('codex exec {prompt}', 'PROMPT')
+    const b = planCustomCommand('codex exec "{prompt}"', 'PROMPT')
+    expect(a).toEqual(b)
+  })
+
+  it('substitutes {prompt} embedded inside a token', () => {
+    const r = planCustomCommand('agent --msg={prompt}', 'PROMPT')
+    expect(r).toEqual({
+      ok: true,
+      binary: 'agent',
+      args: ['--msg=PROMPT'],
+      stdinPayload: null
+    })
+  })
+
+  it('errors on empty templates', () => {
+    const r = planCustomCommand('   ', 'PROMPT')
+    expect(r.ok).toBe(false)
+  })
+
+  it('propagates tokenizer errors', () => {
+    const r = planCustomCommand('agent "unclosed', 'PROMPT')
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.error).toMatch(/unclosed/i)
+    }
+  })
+})
diff --git a/src/shared/commit-message-prompt.ts b/src/shared/commit-message-prompt.ts
new file mode 100644
index 00000000000..cb12b5aeba2
--- /dev/null
+++ b/src/shared/commit-message-prompt.ts
@@ -0,0 +1,231 @@
+// Why: keeping the base prompt and assembly here (in shared) lets both the
+// renderer (preview/tests) and main (actual generation) reach the exact same
+// string without duplicating the wording.
+
+export const COMMIT_MESSAGE_BASE_PROMPT = `You are generating a single git commit message.
+Read the staged diff below and produce the message.
+
+Rules:
+- First line: imperative mood, <= 72 chars, no trailing period.
+- Optional body: blank line, then wrapped at 72 chars explaining WHY.
+- Output ONLY the commit message - no preamble, no code fences, no quotes.
+- Do not include "Co-authored-by" trailers - Orca appends them after generation when configured.
+
+Staged diff:
+\`\`\`diff
+{{DIFF}}
+\`\`\`
+`
+
+/** Builds the final prompt sent to the agent. The custom suffix is appended verbatim
+ *  when non-empty so the user can override style (Conventional Commits, gitmoji, …). */
+export function buildCommitPrompt(diff: string, customSuffix: string): string {
+  const base = COMMIT_MESSAGE_BASE_PROMPT.replace('{{DIFF}}', diff)
+  const trimmedSuffix = customSuffix.trim()
+  if (!trimmedSuffix) {
+    return base
+  }
+  return `${base}\n\nAdditional instructions from user:\n${trimmedSuffix}`
+}
+
+export const STAGED_DIFF_BYTE_BUDGET = 200_000
+
+/** Truncates a diff that exceeds the byte budget; appends a marker so the agent
+ *  knows the input was clipped. */
+export function truncateDiffForPrompt(
+  diff: string,
+  budget: number = STAGED_DIFF_BYTE_BUDGET
+): string {
+  if (diff.length <= budget) {
+    return diff
+  }
+  const omitted = diff.length - budget
+  return `${diff.slice(0, budget)}\n...(diff truncated, ${omitted} bytes omitted)`
+}
+
+/** Strips noise around the agent's output: surrounding whitespace, a single
+ *  enclosing fenced code block, and lone "Generating…" preamble lines some
+ *  CLIs print before the real answer. */
+export function cleanGeneratedCommitMessage(raw: string): string {
+  let text = raw.replace(/\r\n/g, '\n').trim()
+
+  // Why: real commit messages never start with an ellipsis or the word
+  // "Generating"/"Thinking" — those leak from CLIs that print a status line
+  // before the actual response.
+  const firstNewline = text.indexOf('\n')
+  if (firstNewline !== -1) {
+    const firstLine = text.slice(0, firstNewline)
+    if (/^(generating|thinking)\b/i.test(firstLine) || /^[.…]+$/.test(firstLine.trim())) {
+      text = text.slice(firstNewline + 1).trim()
+    }
+  }
+
+  const fence = /^```[a-zA-Z0-9_-]*\n([\s\S]*?)\n```$/
+  const fenced = text.match(fence)
+  if (fenced) {
+    text = fenced[1].trim()
+  }
+
+  return text
+}
+
+export const CUSTOM_PROMPT_PLACEHOLDER = '{prompt}'
+
+export type TokenizeCustomCommandResult =
+  | { ok: true; tokens: string[] }
+  | { ok: false; error: string }
+
+// Why: deliberately POSIX-shell-style only for *grouping* (single + double
+// quotes, backslash escapes inside double quotes). We do NOT expand `$VAR`,
+// command substitution, backticks, globs, or `~`. The user's intent is
+// "spawn this exact CLI" — adding shell semantics on top would create
+// surprising behavior across platforms (especially Windows) and a security
+// surface we don't need.
+export function tokenizeCustomCommandTemplate(template: string): TokenizeCustomCommandResult {
+  const tokens: string[] = []
+  let current = ''
+  let inToken = false
+  let quote: '"' | "'" | null = null
+  let i = 0
+
+  while (i < template.length) {
+    const ch = template[i]
+    if (quote) {
+      if (ch === '\\' && quote === '"' && i + 1 < template.length) {
+        current += template[i + 1]
+        i += 2
+        continue
+      }
+      if (ch === quote) {
+        quote = null
+        i++
+        // Why: leaving a quoted region still keeps the token open — `a"b"c`
+        // tokenizes as a single arg `abc`.
+        inToken = true
+        continue
+      }
+      current += ch
+      i++
+      continue
+    }
+
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      inToken = true
+      i++
+      continue
+    }
+
+    if (ch === '\\' && i + 1 < template.length) {
+      current += template[i + 1]
+      inToken = true
+      i += 2
+      continue
+    }
+
+    if (/\s/.test(ch)) {
+      if (inToken) {
+        tokens.push(current)
+        current = ''
+        inToken = false
+      }
+      i++
+      continue
+    }
+
+    current += ch
+    inToken = true
+    i++
+  }
+
+  if (quote) {
+    return { ok: false, error: 'Unclosed quote in command template.' }
+  }
+  if (inToken) {
+    tokens.push(current)
+  }
+  return { ok: true, tokens }
+}
+
+export type CustomCommandPlan =
+  | { ok: true; binary: string; args: string[]; stdinPayload: string | null }
+  | { ok: false; error: string }
+
+/**
+ * Parses a user-supplied command template into a spawn-ready binary + argv,
+ * substituting `{prompt}` with the agent prompt. When the template contains
+ * no `{prompt}`, the prompt is delivered via stdin (mirrors `claude -p`).
+ *
+ * Quoting is a tokenizer-level concern only — we use argv (no shell), so the
+ * substituted prompt is always passed as a single argument regardless of
+ * whether the template wrote `{prompt}` or `"{prompt}"`.
+ */
+export function planCustomCommand(template: string, prompt: string): CustomCommandPlan {
+  const tokenized = tokenizeCustomCommandTemplate(template)
+  if (!tokenized.ok) {
+    return { ok: false, error: tokenized.error }
+  }
+  if (tokenized.tokens.length === 0) {
+    return { ok: false, error: 'Custom command is empty.' }
+  }
+  const [binary, ...rest] = tokenized.tokens
+  if (!binary) {
+    return { ok: false, error: 'Custom command must start with a binary name.' }
+  }
+
+  const substitute = (token: string): string =>
+    token.includes(CUSTOM_PROMPT_PLACEHOLDER)
+      ? token.split(CUSTOM_PROMPT_PLACEHOLDER).join(prompt)
+      : token
+  const usesPlaceholder = tokenized.tokens.some((t) => t.includes(CUSTOM_PROMPT_PLACEHOLDER))
+  if (usesPlaceholder) {
+    return {
+      ok: true,
+      binary: substitute(binary),
+      args: rest.map(substitute),
+      stdinPayload: null
+    }
+  }
+  return { ok: true, binary, args: rest, stdinPayload: prompt }
+}
+
+// Why: agent CLIs (Codex, Claude) prefix their stdout/stderr with config
+// preamble, the echoed prompt, and hook lifecycle messages. When something
+// fails, the actionable error is buried far below all of that. This pulls
+// out the real message so the user sees something legible instead of a
+// dump of the agent's runtime state.
+export function extractAgentErrorMessage(stdout: string, stderr: string): string | null {
+  const combined = `${stdout}\n${stderr}`
+  const lines = combined.split(/\r?\n/)
+
+  // Pass 1: look for an `ERROR:`/`Error:` line carrying a JSON payload.
+  // Walk from the end so the most recent (and usually most meaningful)
+  // error wins when an agent prints multiple.
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    const match = /^\s*(?:ERROR|Error)\s*:\s*(.+)$/.exec(line)
+    if (!match) {
+      continue
+    }
+    const payload = match[1].trim()
+    if (payload.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(payload) as {
+          message?: string
+          error?: { message?: string }
+        }
+        const inner = parsed.error?.message ?? parsed.message
+        if (typeof inner === 'string' && inner.trim().length > 0) {
+          return inner.trim()
+        }
+      } catch {
+        // Fall through to using the raw payload below.
+      }
+    }
+    if (payload.length > 0) {
+      return payload
+    }
+  }
+
+  return null
+}
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 1c2de304c7a..b7e77955f2c 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -265,6 +265,18 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
       lastViewByProject: {},
       activeProject: null
     },
+    // Why: opt-in feature — `enabled: false` keeps the Generate button hidden
+    // for existing users until they discover and turn it on in Settings. The
+    // per-agent / per-model maps stay empty until the user activates the
+    // toggle, at which point the pane fills them with the spec defaults.
+    commitMessageAi: {
+      enabled: false,
+      agentId: null,
+      selectedModelByAgent: {},
+      selectedThinkingByModel: {},
+      customPrompt: '',
+      customAgentCommand: ''
+    },
     voice: getDefaultVoiceSettings()
   }
 }
diff --git a/src/shared/orca-attribution.ts b/src/shared/orca-attribution.ts
new file mode 100644
index 00000000000..ce81dcffb4e
--- /dev/null
+++ b/src/shared/orca-attribution.ts
@@ -0,0 +1,6 @@
+// Why: single source of truth for the commit trailer Orca appends when the
+// "Orca Attribution" toggle (`enableGitHubAttribution`) is on. Used by both
+// the terminal git/gh shim and the AI commit-message generator so the two
+// code paths agree on the exact string.
+
+export const ORCA_GIT_COMMIT_TRAILER = 'Co-authored-by: Orca <help@stably.ai>'
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 7430e34428e..3142a33f25c 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1403,6 +1403,10 @@ export type GlobalSettings = {
    *  landed won't have the key; `getDefaultSettings()` hydrates the empty
    *  default via the persistence merge. */
   githubProjects?: GitHubProjectSettings
+  /** AI-generated commit messages: agent + model + per-model thinking +
+   *  user-customizable prompt suffix. Optional so existing profiles do not
+   *  require a migration step before this feature lands. */
+  commitMessageAi?: CommitMessageAiSettings
   /** GitLab project preferences — pinned + recent project paths.
    *  Optional for backward compatibility with profiles saved before
    *  GitLab support; the persistence merge fills the empty default. */
@@ -1442,6 +1446,22 @@ export type GlobalSettings = {
   voice?: VoiceSettings
 }
 
+export type CommitMessageAiSettings = {
+  enabled: boolean
+  /** A TuiAgent id, the literal `'custom'` for a user-supplied command, or null. */
+  agentId: TuiAgent | 'custom' | null
+  /** Per-agent: switching agents preserves the previously-picked model. */
+  selectedModelByAgent: Partial<Record<TuiAgent, string>>
+  /** Per-model: thinking effort depends on the model, not the agent. Keyed by model id. */
+  selectedThinkingByModel: Record<string, string>
+  /** Optional user-provided suffix appended to the base prompt (style overrides, etc.). */
+  customPrompt: string
+  /** Command template used when `agentId === 'custom'`. Tokenized POSIX-style;
+   *  `{prompt}` is substituted with the diff prompt (argv delivery). When the
+   *  template has no `{prompt}`, the prompt is piped via stdin. */
+  customAgentCommand: string
+}
+
 export type GhosttyImportPreview = {
   found: boolean
   configPath?: string
diff --git a/tests/e2e/source-control-commit-message-ai.spec.ts b/tests/e2e/source-control-commit-message-ai.spec.ts
new file mode 100644
index 00000000000..fba38da8e9b
--- /dev/null
+++ b/tests/e2e/source-control-commit-message-ai.spec.ts
@@ -0,0 +1,132 @@
+import { execFileSync } from 'child_process'
+import { rmSync, writeFileSync } from 'fs'
+import os from 'os'
+import path from 'path'
+import { test, expect } from './helpers/orca-app'
+import { waitForSessionReady } from './helpers/store'
+
+function createWorktreeWithStagedChange(repoPath: string): {
+  branchName: string
+  worktreePath: string
+} {
+  const branchName = `e2e-ai-commit-${Date.now()}-${Math.random().toString(16).slice(2)}`
+  const worktreePath = path.join(os.tmpdir(), branchName)
+  execFileSync('git', ['worktree', 'add', worktreePath, '-b', branchName], {
+    cwd: repoPath,
+    stdio: 'pipe'
+  })
+  writeFileSync(
+    path.join(worktreePath, 'README.md'),
+    '# AI Commit Message E2E\n\nGenerated flow.\n'
+  )
+  execFileSync('git', ['add', 'README.md'], { cwd: worktreePath, stdio: 'pipe' })
+  return { branchName, worktreePath }
+}
+
+function cleanupWorktree(repoPath: string, worktreePath: string, branchName: string): void {
+  try {
+    execFileSync('git', ['worktree', 'remove', '--force', worktreePath], {
+      cwd: repoPath,
+      stdio: 'pipe'
+    })
+  } catch {
+    rmSync(worktreePath, { recursive: true, force: true })
+  }
+  try {
+    execFileSync('git', ['branch', '-D', branchName], { cwd: repoPath, stdio: 'pipe' })
+  } catch {
+    // The branch is already gone when git prunes it with the worktree.
+  }
+}
+
+test.describe('Source Control AI commit messages', () => {
+  test('generates a commit message from staged changes through the Source Control UI', async ({
+    orcaPage,
+    testRepoPath
+  }) => {
+    const { branchName, worktreePath } = createWorktreeWithStagedChange(testRepoPath)
+    const agentCommand =
+      'node -e "setTimeout(() => process.stdout.write(\'Add generated E2E message\'), 250)"'
+
+    try {
+      await waitForSessionReady(orcaPage)
+      await orcaPage.evaluate(
+        async ({ repoPath, worktreePath: targetWorktreePath, agentCommand: command }) => {
+          const store = window.__store
+          if (!store) {
+            throw new Error('window.__store is not available')
+          }
+          const state = store.getState()
+          await state.fetchRepos()
+          const repo = store.getState().repos.find((entry) => entry.path === repoPath)
+          if (!repo) {
+            throw new Error(`Seeded E2E repo was not registered: ${repoPath}`)
+          }
+          const listedWorktrees = await window.api.worktrees.list({ repoId: repo.id })
+          store.setState((current) => ({
+            worktreesByRepo: {
+              ...current.worktreesByRepo,
+              [repo.id]: listedWorktrees
+            }
+          }))
+          const normalizeMacTmpPath = (value: string): string =>
+            value.startsWith('/private/var/') ? value.slice('/private'.length) : value
+          const worktree = listedWorktrees.find(
+            (entry) => normalizeMacTmpPath(entry.path) === normalizeMacTmpPath(targetWorktreePath)
+          )
+          if (!worktree) {
+            throw new Error(
+              `E2E worktree was not loaded: ${targetWorktreePath}; listed=${listedWorktrees
+                .map((entry) => entry.path)
+                .join(', ')}`
+            )
+          }
+
+          store.getState().setActiveWorktree(worktree.id)
+          await store.getState().updateSettings({
+            commitMessageAi: {
+              enabled: true,
+              agentId: 'custom',
+              selectedModelByAgent: {},
+              selectedThinkingByModel: {},
+              customPrompt: '',
+              customAgentCommand: command
+            }
+          })
+          const status = await window.api.git.status({ worktreePath: worktree.path })
+          store.getState().setGitStatus(worktree.id, status)
+          store.getState().setRightSidebarTab('source-control')
+          store.getState().setRightSidebarOpen(true)
+        },
+        { repoPath: testRepoPath, worktreePath, agentCommand }
+      )
+
+      await expect
+        .poll(
+          async () =>
+            orcaPage.evaluate(() => {
+              const state = window.__store?.getState()
+              return Boolean(state?.rightSidebarOpen && state?.rightSidebarTab === 'source-control')
+            }),
+          { timeout: 5_000 }
+        )
+        .toBe(true)
+
+      const textarea = orcaPage.getByRole('textbox', { name: 'Commit message' })
+      await expect(textarea).toBeVisible({ timeout: 10_000 })
+      await expect(textarea).toHaveValue('')
+
+      const generate = orcaPage.getByRole('button', { name: 'Generate commit message with AI' })
+      await expect(generate).toBeVisible()
+      await expect(generate).toBeEnabled()
+      await generate.click()
+
+      await expect(
+        orcaPage.getByRole('button', { name: 'Stop generating commit message' })
+      ).toBeVisible()
+      await expect(textarea).toHaveValue('Add generated E2E message', { timeout: 10_000 })
+    } finally {
+      cleanupWorktree(testRepoPath, worktreePath, branchName)
+    }
+  })
+})

From 618f39d17913d958a72dfb11527d3f72bd371af0 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 15 May 2026 05:44:25 -0400
Subject: [PATCH 33/82] Add web runtime client support

---
 config/scripts/orca-dev                       |    8 +
 config/scripts/run-electron-vite-dev.mjs      |   31 +-
 config/scripts/verify-web-build.mjs           |   14 +
 package.json                                  |    6 +-
 src/cli/runtime/launch.test.ts                |   61 +
 src/cli/runtime/launch.ts                     |   16 +-
 src/cli/specs/core.ts                         |    3 +-
 src/main/index.ts                             |   14 +-
 src/main/ipc/mobile.test.ts                   |   33 +
 src/main/ipc/mobile.ts                        |   30 +
 src/main/ipc/preflight.ts                     |   20 +-
 src/main/runtime/orca-runtime.ts              |    8 +
 src/main/runtime/rpc/methods/github.test.ts   |   31 +
 src/main/runtime/rpc/methods/github.ts        |   10 +
 src/main/runtime/rpc/methods/index.ts         |    2 +
 .../runtime/rpc/methods/preflight.test.ts     |   84 ++
 src/main/runtime/rpc/methods/preflight.ts     |   38 +
 .../runtime/rpc/static-web-client-handler.ts  |  139 ++
 .../rpc/ws-transport-static-web.test.ts       |   91 ++
 src/main/runtime/rpc/ws-transport.test.ts     |    3 +
 src/main/runtime/rpc/ws-transport.ts          |   19 +-
 src/main/runtime/runtime-rpc.test.ts          |   67 +-
 src/main/runtime/runtime-rpc.ts               |   42 +-
 src/preload/api-types.ts                      |   10 +
 src/preload/index.ts                          |   14 +
 .../src/components/LinearItemDrawer.tsx       |    3 +-
 .../src/components/editor/ipynb-parse.ts      |    6 +-
 .../FloatingTerminalPanel.tsx                 |    3 +-
 .../src/components/settings/CliSection.tsx    |  105 +-
 .../settings/RuntimeEnvironmentsPane.tsx      |  322 ++--
 .../settings/RuntimePairingUrlGenerator.tsx   |  239 +++
 .../src/components/settings/Settings.tsx      |  308 ++--
 .../settings/TerminalQuickCommandsSection.tsx |    7 +-
 .../settings/runtime-environments-search.ts   |   25 +
 src/renderer/src/lib/browser-uuid.test.ts     |   29 +
 src/renderer/src/lib/browser-uuid.ts          |   28 +
 .../src/lib/open-project-notes-tab.ts         |    3 +-
 .../src/runtime/sync-runtime-graph.ts         |    6 +-
 src/renderer/src/store/slices/browser.ts      |    7 +-
 src/renderer/src/store/slices/diffComments.ts |    3 +-
 .../src/store/slices/tab-group-state.ts       |    3 +-
 .../src/store/slices/tabs-hydration.ts        |    3 +-
 src/renderer/src/store/slices/tabs.ts         |    9 +-
 src/renderer/src/store/slices/terminals.ts    |    3 +-
 src/renderer/src/web/WebConnect.tsx           |  143 ++
 src/renderer/src/web/main.tsx                 |   51 +
 src/renderer/src/web/web-e2ee.ts              |   80 +
 src/renderer/src/web/web-pairing.ts           |  107 ++
 src/renderer/src/web/web-preload-api.ts       | 1332 +++++++++++++++++
 .../src/web/web-runtime-client.test.ts        |   48 +
 src/renderer/src/web/web-runtime-client.ts    |  548 +++++++
 .../src/web/web-runtime-environment.ts        |  115 ++
 src/renderer/web-index.html                   |   15 +
 vite.web.config.ts                            |   28 +
 54 files changed, 4039 insertions(+), 334 deletions(-)
 create mode 100644 config/scripts/verify-web-build.mjs
 create mode 100644 src/main/runtime/rpc/methods/preflight.test.ts
 create mode 100644 src/main/runtime/rpc/methods/preflight.ts
 create mode 100644 src/main/runtime/rpc/static-web-client-handler.ts
 create mode 100644 src/main/runtime/rpc/ws-transport-static-web.test.ts
 create mode 100644 src/renderer/src/components/settings/RuntimePairingUrlGenerator.tsx
 create mode 100644 src/renderer/src/components/settings/runtime-environments-search.ts
 create mode 100644 src/renderer/src/lib/browser-uuid.test.ts
 create mode 100644 src/renderer/src/lib/browser-uuid.ts
 create mode 100644 src/renderer/src/web/WebConnect.tsx
 create mode 100644 src/renderer/src/web/main.tsx
 create mode 100644 src/renderer/src/web/web-e2ee.ts
 create mode 100644 src/renderer/src/web/web-pairing.ts
 create mode 100644 src/renderer/src/web/web-preload-api.ts
 create mode 100644 src/renderer/src/web/web-runtime-client.test.ts
 create mode 100644 src/renderer/src/web/web-runtime-client.ts
 create mode 100644 src/renderer/src/web/web-runtime-environment.ts
 create mode 100644 src/renderer/web-index.html
 create mode 100644 vite.web.config.ts

diff --git a/config/scripts/orca-dev b/config/scripts/orca-dev
index 47bdb1c5b56..10754fe4ca3 100755
--- a/config/scripts/orca-dev
+++ b/config/scripts/orca-dev
@@ -25,4 +25,12 @@ case "$(uname -s)" in
 esac
 
 export ORCA_USER_DATA_PATH="${ORCA_DEV_USER_DATA_PATH:-$default_data}"
+electron_executable="$REPO_ROOT/node_modules/.bin/electron"
+case "$(uname -s)" in
+  MINGW*|MSYS*) electron_executable="$REPO_ROOT/node_modules/electron/dist/electron.exe" ;;
+esac
+if [ -z "${ORCA_APP_EXECUTABLE:-}" ] && [ -x "$electron_executable" ]; then
+  export ORCA_APP_EXECUTABLE="$electron_executable"
+  export ORCA_APP_EXECUTABLE_NEEDS_APP_ROOT=1
+fi
 exec node "$CLI_ENTRY" "$@"
diff --git a/config/scripts/run-electron-vite-dev.mjs b/config/scripts/run-electron-vite-dev.mjs
index 408206b9838..c3ac1b049a5 100644
--- a/config/scripts/run-electron-vite-dev.mjs
+++ b/config/scripts/run-electron-vite-dev.mjs
@@ -23,9 +23,15 @@ function getDevUserDataPath() {
     return path.join(process.env.HOME ?? '', 'Library', 'Application Support', 'orca-dev')
   }
   if (process.platform === 'win32') {
-    return path.join(process.env.APPDATA ?? path.join(process.env.USERPROFILE ?? '', 'AppData', 'Roaming'), 'orca-dev')
+    return path.join(
+      process.env.APPDATA ?? path.join(process.env.USERPROFILE ?? '', 'AppData', 'Roaming'),
+      'orca-dev'
+    )
   }
-  return path.join(process.env.XDG_CONFIG_HOME ?? path.join(process.env.HOME ?? '', '.config'), 'orca-dev')
+  return path.join(
+    process.env.XDG_CONFIG_HOME ?? path.join(process.env.HOME ?? '', '.config'),
+    'orca-dev'
+  )
 }
 
 function prepareDevCliWrapper() {
@@ -33,18 +39,19 @@ function prepareDevCliWrapper() {
   mkdirSync(binDir, { recursive: true })
   const userDataPath = getDevUserDataPath()
   const cliPath = path.join(repoRoot, 'out', 'cli', 'index.js')
+  const electronBin = getElectronExecutable()
 
   if (process.platform === 'win32') {
     writeFileSync(
       path.join(binDir, 'orca-dev.cmd'),
-      `@echo off\r\nset "ORCA_USER_DATA_PATH=${userDataPath}"\r\nnode "${cliPath}" %*\r\n`,
+      `@echo off\r\nset "ORCA_USER_DATA_PATH=${userDataPath}"\r\nset "ORCA_APP_EXECUTABLE=${electronBin}"\r\nset "ORCA_APP_EXECUTABLE_NEEDS_APP_ROOT=1"\r\nnode "${cliPath}" %*\r\n`,
       'utf8'
     )
   } else {
     const wrapperPath = path.join(binDir, 'orca-dev')
     writeFileSync(
       wrapperPath,
-      `#!/usr/bin/env bash\nexport ORCA_USER_DATA_PATH=${JSON.stringify(userDataPath)}\nexec node ${JSON.stringify(cliPath)} "$@"\n`,
+      `#!/usr/bin/env bash\nexport ORCA_USER_DATA_PATH=${JSON.stringify(userDataPath)}\nexport ORCA_APP_EXECUTABLE=${JSON.stringify(electronBin)}\nexport ORCA_APP_EXECUTABLE_NEEDS_APP_ROOT=1\nexec node ${JSON.stringify(cliPath)} "$@"\n`,
       'utf8'
     )
     chmodSync(wrapperPath, 0o755)
@@ -54,6 +61,13 @@ function prepareDevCliWrapper() {
   console.log(`[orca-dev] Prepared wrapper in ${binDir}`)
 }
 
+function getElectronExecutable() {
+  if (process.platform === 'win32') {
+    return path.join(repoRoot, 'node_modules', 'electron', 'dist', 'electron.exe')
+  }
+  return path.join(repoRoot, 'node_modules', '.bin', 'electron')
+}
+
 if (process.env.ORCA_SKIP_DEV_CLI_PREPARE !== '1') {
   prepareDevCliWrapper()
 }
@@ -109,7 +123,10 @@ function parseDebugPortEnv(raw) {
 // space-separated form. `--remote-debugging-pipe` opts into pipe-based
 // debugging — don't fight the user's choice by injecting a port.
 const userPassedPort = forwardedRaw.some(
-  (a) => a === '--remote-debugging-port' || a.startsWith('--remote-debugging-port=') || a === '--remote-debugging-pipe'
+  (a) =>
+    a === '--remote-debugging-port' ||
+    a.startsWith('--remote-debugging-port=') ||
+    a === '--remote-debugging-pipe'
 )
 // Why: --help/--version exit immediately; binding a probe socket and printing
 // a debug-port line would be noise.
@@ -136,7 +153,9 @@ if (!userPassedPort && !isHelpOrVersion) {
     // resolve to ::1 on IPv6-first hosts).
     console.error(`[orca-dev] Remote debugging on http://127.0.0.1:${port}`)
   } else {
-    console.error('[orca-dev] No free debug port found in sweep; starting without --remote-debugging-port.')
+    console.error(
+      '[orca-dev] No free debug port found in sweep; starting without --remote-debugging-port.'
+    )
   }
 }
 const forwardedArgs = ['dev', ...forwardedRaw, ...forwardedExtras]
diff --git a/config/scripts/verify-web-build.mjs b/config/scripts/verify-web-build.mjs
new file mode 100644
index 00000000000..cf700129a91
--- /dev/null
+++ b/config/scripts/verify-web-build.mjs
@@ -0,0 +1,14 @@
+import { readFile } from 'fs/promises'
+import { resolve } from 'path'
+
+const indexPath = resolve('out/web/web-index.html')
+const html = await readFile(indexPath, 'utf8')
+
+const absoluteAssetReference = /\b(?:src|href)=["']\/assets\//.exec(html)
+
+if (absoluteAssetReference) {
+  console.error(
+    `Web build must use relative asset URLs for reverse-proxy pairing URLs; found ${absoluteAssetReference[0]} in ${indexPath}`
+  )
+  process.exit(1)
+}
diff --git a/package.json b/package.json
index 2c9c6ea5fae..18ce227e865 100644
--- a/package.json
+++ b/package.json
@@ -27,14 +27,16 @@
     "typecheck": "tsc --noEmit -p config/tsconfig.node.json --composite false && tsc --noEmit -p config/tsconfig.cli.json --composite false && tsc --noEmit -p config/tsconfig.web.json --composite false",
     "start": "electron-vite preview",
     "dev": "node config/scripts/run-electron-vite-dev.mjs",
+    "dev:web": "vite --config vite.web.config.ts --host 127.0.0.1",
     "build:relay": "node config/scripts/build-relay.mjs",
     "build:computer-macos": "node config/scripts/build-computer-macos.mjs",
     "smoke:computer": "node config/scripts/computer-use-smoke.mjs",
     "verify:computer-native": "node config/scripts/verify-computer-native.mjs",
     "build:cli": "tsc -p config/tsconfig.cli.json --outDir out --composite false --incremental false && node config/scripts/install-dev-cli.mjs",
     "build:electron-vite": "node config/scripts/run-electron-vite-build.mjs",
-    "build": "pnpm run typecheck && pnpm run build:relay && pnpm run build:computer-macos && pnpm run build:electron-vite && pnpm run build:cli",
-    "build:release": "pnpm run build:relay && pnpm run build:computer-macos && pnpm run verify:computer-native && pnpm run build:electron-vite && pnpm run build:cli",
+    "build:web": "vite build --config vite.web.config.ts && node config/scripts/verify-web-build.mjs",
+    "build": "pnpm run typecheck && pnpm run build:relay && pnpm run build:computer-macos && pnpm run build:electron-vite && pnpm run build:web && pnpm run build:cli",
+    "build:release": "pnpm run build:relay && pnpm run build:computer-macos && pnpm run verify:computer-native && pnpm run build:electron-vite && pnpm run build:web && pnpm run build:cli",
     "postinstall": "pnpm rebuild electron && node config/scripts/rebuild-native-deps.mjs",
     "rebuild:electron": "node config/scripts/rebuild-native-deps.mjs",
     "build:unpack": "pnpm run build && electron-builder --config config/electron-builder.config.cjs --dir",
diff --git a/src/cli/runtime/launch.test.ts b/src/cli/runtime/launch.test.ts
index 807df9dc721..c3cf5b3067b 100644
--- a/src/cli/runtime/launch.test.ts
+++ b/src/cli/runtime/launch.test.ts
@@ -19,6 +19,7 @@ describe('serveOrcaApp', () => {
 
   afterEach(() => {
     delete process.env.ORCA_APP_EXECUTABLE
+    delete process.env.ORCA_APP_EXECUTABLE_NEEDS_APP_ROOT
   })
 
   it('pins the Electron child cwd to the app root instead of the caller cwd', async () => {
@@ -85,4 +86,64 @@ describe('serveOrcaApp', () => {
       })
     )
   })
+
+  it('passes the app root before serve flags for dev Electron executables', async () => {
+    process.env.ORCA_APP_EXECUTABLE = '/repo/node_modules/.bin/electron'
+    process.env.ORCA_APP_EXECUTABLE_NEEDS_APP_ROOT = '1'
+    const child = {
+      kill: vi.fn(),
+      once: vi.fn(
+        (event: string, handler: (code: number | null, signal: string | null) => void) => {
+          if (event === 'exit') {
+            queueMicrotask(() => handler(0, null))
+          }
+          return child
+        }
+      )
+    }
+    spawnMock.mockReturnValue(child)
+
+    await expect(serveOrcaApp({ json: true, port: '6768' })).resolves.toBe(0)
+
+    expect(spawnMock).toHaveBeenCalledWith(
+      '/repo/node_modules/.bin/electron',
+      [resolve(__dirname, '../../..'), '--serve', '--serve-json', '--serve-port', '6768'],
+      expect.objectContaining({
+        cwd: resolve(__dirname, '../../..')
+      })
+    )
+  })
+
+  it('uses a shell when a Windows npm command shim is the Electron executable', async () => {
+    const platformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform')
+    Object.defineProperty(process, 'platform', { value: 'win32' })
+    process.env.ORCA_APP_EXECUTABLE = 'C:\\repo\\node_modules\\.bin\\electron.cmd'
+    const child = {
+      kill: vi.fn(),
+      once: vi.fn(
+        (event: string, handler: (code: number | null, signal: string | null) => void) => {
+          if (event === 'exit') {
+            queueMicrotask(() => handler(0, null))
+          }
+          return child
+        }
+      )
+    }
+    spawnMock.mockReturnValue(child)
+
+    try {
+      await expect(serveOrcaApp({ json: true })).resolves.toBe(0)
+      expect(spawnMock).toHaveBeenCalledWith(
+        'C:\\repo\\node_modules\\.bin\\electron.cmd',
+        ['--serve', '--serve-json'],
+        expect.objectContaining({
+          shell: true
+        })
+      )
+    } finally {
+      if (platformDescriptor) {
+        Object.defineProperty(process, 'platform', platformDescriptor)
+      }
+    }
+  })
 })
diff --git a/src/cli/runtime/launch.ts b/src/cli/runtime/launch.ts
index 71de311177b..6a7058c98fe 100644
--- a/src/cli/runtime/launch.ts
+++ b/src/cli/runtime/launch.ts
@@ -1,4 +1,4 @@
-import { spawn as spawnProcess } from 'child_process'
+import { spawn as spawnProcess, type SpawnOptions } from 'child_process'
 import { dirname, resolve } from 'path'
 import { RuntimeClientError } from './types'
 
@@ -15,9 +15,10 @@ export function launchOrcaApp(): void {
 
   const overrideExecutable = process.env.ORCA_APP_EXECUTABLE
   if (typeof overrideExecutable === 'string' && overrideExecutable.trim().length > 0) {
-    spawnProcess(overrideExecutable, [], {
+    spawnProcess(overrideExecutable, getExecutableAppArgs(), {
       detached: true,
       stdio: 'ignore',
+      ...getExecutableSpawnOptions(overrideExecutable),
       env: stripElectronRunAsNode(process.env)
     }).unref()
     return
@@ -63,7 +64,7 @@ export function serveOrcaApp(
   } = {}
 ): Promise<number> {
   const executable = resolveForegroundOrcaExecutable()
-  const childArgs = ['--serve']
+  const childArgs = [...getExecutableAppArgs(), '--serve']
   if (args.json) {
     childArgs.push('--serve-json')
   }
@@ -83,6 +84,7 @@ export function serveOrcaApp(
   const child = spawnProcess(executable, childArgs, {
     cwd: resolveAppRoot(),
     stdio: 'inherit',
+    ...getExecutableSpawnOptions(executable),
     env: stripElectronRunAsNode(process.env)
   })
 
@@ -119,6 +121,14 @@ export function serveOrcaApp(
   })
 }
 
+function getExecutableAppArgs(): string[] {
+  return process.env.ORCA_APP_EXECUTABLE_NEEDS_APP_ROOT === '1' ? [resolveAppRoot()] : []
+}
+
+function getExecutableSpawnOptions(executable: string): Pick<SpawnOptions, 'shell'> {
+  return process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(executable) ? { shell: true } : {}
+}
+
 function resolveAppRoot(): string {
   // Why: dev-mode resource resolution in the Electron child may consult
   // process.cwd(). Pin it to the app root so `orca serve` behaves the same
diff --git a/src/cli/specs/core.ts b/src/cli/specs/core.ts
index f8f6d8ffb00..afbb9dcd9ae 100644
--- a/src/cli/specs/core.ts
+++ b/src/cli/specs/core.ts
@@ -18,7 +18,8 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [
     notes: [
       'Runs in the foreground and prints the runtime endpoint. Stop it with Ctrl+C.',
       'Use --pairing-address when clients should connect through a LAN, Tailscale, SSH-forward, or public tunnel address.',
-      'Use --mobile-pairing to print a mobile-scoped pairing QR/link instead of the default runtime-environment pairing link.'
+      'Use --mobile-pairing to print a mobile-scoped pairing QR/link instead of the default runtime-environment pairing link.',
+      'When the web client bundle is available, the server also prints a browser URL with the pairing data embedded.'
     ],
     examples: [
       'orca serve',
diff --git a/src/main/index.ts b/src/main/index.ts
index d16fdb2f141..7da6e4fa722 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -3,6 +3,8 @@
    startup. Splitting by line count would fragment tightly coupled startup
    logic across files without a cleaner ownership seam. */
 import { grantDirAcl } from './win32-utils'
+import { existsSync } from 'fs'
+import { join } from 'path'
 import { app, BrowserWindow, nativeImage, nativeTheme } from 'electron'
 import { electronApp, is } from '@electron-toolkit/utils'
 import * as QRCode from 'qrcode'
@@ -449,6 +451,11 @@ function getServeOptions(argv = process.argv): ServeOptions {
   }
 }
 
+function getBundledWebClientRoot(): string | undefined {
+  const root = join(app.getAppPath(), 'out', 'web')
+  return existsSync(join(root, 'web-index.html')) ? root : undefined
+}
+
 async function renderTerminalPairingQr(pairingUrl: string): Promise<string | null> {
   try {
     return await QRCode.toString(pairingUrl, { type: 'terminal', small: true })
@@ -488,6 +495,7 @@ async function printServeReady(options: ServeOptions): Promise<void> {
               url: pairing.pairingUrl,
               endpoint: pairing.endpoint,
               deviceId: pairing.deviceId,
+              webClientUrl: pairing.webClientUrl,
               scope: options.mobilePairing ? 'mobile' : 'runtime',
               qr: pairingQr
             }
@@ -498,6 +506,9 @@ async function printServeReady(options: ServeOptions): Promise<void> {
   }
   console.log(`Orca server ready: ${endpoint ?? 'websocket unavailable'}`)
   if (pairing.available) {
+    if (pairing.webClientUrl) {
+      console.log(`Web client URL: ${pairing.webClientUrl}`)
+    }
     if (options.mobilePairing && pairingQr) {
       console.log(`Mobile pairing QR:\n${pairingQr}`)
     }
@@ -760,7 +771,8 @@ app.whenReady().then(async () => {
     enableWebSocket: true,
     ...(isE2E ? { wsPort: 0 } : {}),
     ...(devWsPort !== undefined ? { wsPort: devWsPort } : {}),
-    ...(serveOptions?.wsPort !== undefined ? { wsPort: serveOptions.wsPort } : {})
+    ...(serveOptions?.wsPort !== undefined ? { wsPort: serveOptions.wsPort } : {}),
+    webClientRoot: getBundledWebClientRoot()
   })
   registerMobileHandlers(runtimeRpc)
 
diff --git a/src/main/ipc/mobile.test.ts b/src/main/ipc/mobile.test.ts
index 5fb11e0b646..585b8aaf1fd 100644
--- a/src/main/ipc/mobile.test.ts
+++ b/src/main/ipc/mobile.test.ts
@@ -69,4 +69,37 @@ describe('registerMobileHandlers', () => {
       ]
     })
   })
+
+  it('generates runtime-scoped pairing urls for web and desktop clients', async () => {
+    const createPairingOffer = vi.fn().mockReturnValue({
+      available: true,
+      pairingUrl: 'orca://pair#runtime',
+      webClientUrl: 'http://100.64.1.20:6768/web-index.html?pairing=runtime',
+      endpoint: 'ws://100.64.1.20:6768',
+      deviceId: 'runtime-1'
+    })
+    const rpcServer = { createPairingOffer }
+
+    registerMobileHandlers(rpcServer as never)
+
+    await expect(
+      handlers.get('mobile:getRuntimePairingUrl')?.(null, {
+        address: '100.64.1.20',
+        rotate: true
+      })
+    ).resolves.toEqual({
+      available: true,
+      pairingUrl: 'orca://pair#runtime',
+      webClientUrl: 'http://100.64.1.20:6768/web-index.html?pairing=runtime',
+      endpoint: 'ws://100.64.1.20:6768',
+      deviceId: 'runtime-1'
+    })
+
+    expect(createPairingOffer).toHaveBeenCalledWith({
+      address: '100.64.1.20',
+      rotate: true,
+      name: expect.stringMatching(/^Runtime /),
+      scope: 'runtime'
+    })
+  })
 })
diff --git a/src/main/ipc/mobile.ts b/src/main/ipc/mobile.ts
index 110f16d2699..fc0315846eb 100644
--- a/src/main/ipc/mobile.ts
+++ b/src/main/ipc/mobile.ts
@@ -86,6 +86,36 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
     }
   )
 
+  ipcMain.handle(
+    'mobile:getRuntimePairingUrl',
+    async (_event, args?: { address?: string; rotate?: boolean }) => {
+      const ip = args?.address ?? getLanAddress()
+      if (!ip) {
+        return { available: false as const }
+      }
+
+      // Why: web/desktop runtime clients need full runtime access, not the
+      // mobile allowlist used by phone QR pairing.
+      const offer = rpcServer.createPairingOffer({
+        address: ip,
+        rotate: args?.rotate,
+        name: `Runtime ${new Date().toLocaleDateString()}`,
+        scope: 'runtime'
+      })
+      if (!offer.available) {
+        return { available: false as const }
+      }
+
+      return {
+        available: true as const,
+        pairingUrl: offer.pairingUrl,
+        webClientUrl: offer.webClientUrl,
+        endpoint: offer.endpoint,
+        deviceId: offer.deviceId
+      }
+    }
+  )
+
   ipcMain.handle('mobile:listDevices', () => {
     const registry = rpcServer.getDeviceRegistry()
     if (!registry) {
diff --git a/src/main/ipc/preflight.ts b/src/main/ipc/preflight.ts
index 865c6d33414..db3248091c3 100644
--- a/src/main/ipc/preflight.ts
+++ b/src/main/ipc/preflight.ts
@@ -114,6 +114,17 @@ export async function refreshShellPathAndDetectAgents(): Promise<RefreshAgentsRe
   }
 }
 
+export async function detectRemoteAgents(args: { connectionId: string }): Promise<string[]> {
+  const mux = getActiveMultiplexer(args.connectionId)
+  if (!mux || mux.isDisposed()) {
+    throw new Error(`No active SSH connection for "${args.connectionId}"`)
+  }
+  const result = (await mux.request('preflight.detectAgents', {
+    commands: KNOWN_AGENT_COMMANDS
+  })) as { agents: string[] }
+  return result.agents
+}
+
 async function isGhAuthenticated(): Promise<boolean> {
   try {
     await execFileAsync('gh', ['auth', 'status'], {
@@ -199,14 +210,7 @@ export function registerPreflightHandlers(): void {
   ipcMain.handle(
     'preflight:detectRemoteAgents',
     async (_event, args: { connectionId: string }): Promise<string[]> => {
-      const mux = getActiveMultiplexer(args.connectionId)
-      if (!mux || mux.isDisposed()) {
-        throw new Error(`No active SSH connection for "${args.connectionId}"`)
-      }
-      const result = (await mux.request('preflight.detectAgents', {
-        commands: KNOWN_AGENT_COMMANDS
-      })) as { agents: string[] }
-      return result.agents
+      return detectRemoteAgents(args)
     }
   )
 }
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 00767acf3c8..9f0277b35db 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -137,6 +137,7 @@ import {
 import {
   clearProjectItemFieldValue,
   getProjectViewTable,
+  getWorkItemDetailsBySlug,
   listAccessibleProjects,
   listProjectViews,
   resolveProjectRef,
@@ -158,6 +159,7 @@ import type {
   ListIssueTypesBySlugArgs,
   ListLabelsBySlugArgs,
   ListProjectViewsArgs,
+  ProjectWorkItemDetailsBySlugArgs,
   ResolveProjectRefArgs,
   AddIssueCommentBySlugArgs,
   DeleteIssueCommentBySlugArgs,
@@ -4655,6 +4657,12 @@ export class OrcaRuntimeService {
     return getProjectViewTable(args)
   }
 
+  async getGitHubProjectWorkItemDetailsBySlug(
+    args: ProjectWorkItemDetailsBySlugArgs
+  ): Promise<Awaited<ReturnType<typeof getWorkItemDetailsBySlug>>> {
+    return getWorkItemDetailsBySlug(args)
+  }
+
   async updateGitHubProjectItemField(
     args: UpdateProjectItemFieldArgs
   ): Promise<Awaited<ReturnType<typeof updateProjectItemFieldValue>>> {
diff --git a/src/main/runtime/rpc/methods/github.test.ts b/src/main/runtime/rpc/methods/github.test.ts
index bcd32235050..cff2852341b 100644
--- a/src/main/runtime/rpc/methods/github.test.ts
+++ b/src/main/runtime/rpc/methods/github.test.ts
@@ -467,6 +467,37 @@ describe('github RPC methods', () => {
     expect(response).toMatchObject({ ok: true, result: { ok: true, data: { rows: [] } } })
   })
 
+  it('fetches GitHub project work item details by slug on the runtime server', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getGitHubProjectWorkItemDetailsBySlug: vi.fn().mockResolvedValue({
+        ok: true,
+        item: { number: 9, title: 'Bug' }
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: GITHUB_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('github.project.workItemDetailsBySlug', {
+        owner: 'acme',
+        repo: 'orca',
+        number: 9,
+        type: 'issue'
+      })
+    )
+
+    expect(runtime.getGitHubProjectWorkItemDetailsBySlug).toHaveBeenCalledWith({
+      owner: 'acme',
+      repo: 'orca',
+      number: 9,
+      type: 'issue'
+    })
+    expect(response).toMatchObject({
+      ok: true,
+      result: { ok: true, item: { number: 9, title: 'Bug' } }
+    })
+  })
+
   it('updates GitHub project item fields on the runtime server', async () => {
     const runtime = {
       getRuntimeId: () => 'test-runtime',
diff --git a/src/main/runtime/rpc/methods/github.ts b/src/main/runtime/rpc/methods/github.ts
index 72b32e6cdd8..137a1d9f641 100644
--- a/src/main/runtime/rpc/methods/github.ts
+++ b/src/main/runtime/rpc/methods/github.ts
@@ -142,6 +142,11 @@ const ProjectViewTable = z.object({
   queryOverride: OptionalString
 })
 
+const ProjectWorkItemDetailsBySlug = SlugRepo.extend({
+  number: z.number().int().positive(),
+  type: z.enum(['issue', 'pr'])
+})
+
 const ProjectRef = z.object({
   input: requiredString('Missing project reference')
 })
@@ -399,6 +404,11 @@ export const GITHUB_METHODS: RpcMethod[] = [
     params: ProjectViewTable,
     handler: async (params, { runtime }) => runtime.getGitHubProjectViewTable(params)
   }),
+  defineMethod({
+    name: 'github.project.workItemDetailsBySlug',
+    params: ProjectWorkItemDetailsBySlug,
+    handler: async (params, { runtime }) => runtime.getGitHubProjectWorkItemDetailsBySlug(params)
+  }),
   defineMethod({
     name: 'github.project.updateItemField',
     params: ProjectItemField,
diff --git a/src/main/runtime/rpc/methods/index.ts b/src/main/runtime/rpc/methods/index.ts
index 9cbc55d3435..868a3b503aa 100644
--- a/src/main/runtime/rpc/methods/index.ts
+++ b/src/main/runtime/rpc/methods/index.ts
@@ -9,6 +9,7 @@ import { ORCHESTRATION_METHODS } from './orchestration'
 import { NOTIFICATION_METHODS } from './notifications'
 import { STATS_METHODS } from './stats'
 import { ACCOUNT_METHODS } from './accounts'
+import { PREFLIGHT_METHODS } from './preflight'
 import { COMPUTER_METHODS } from './computer'
 import { SESSION_TAB_METHODS } from './session-tabs'
 import { FILE_METHODS } from './files'
@@ -33,6 +34,7 @@ export const ALL_RPC_METHODS: readonly RpcAnyMethod[] = [
   ...NOTIFICATION_METHODS,
   ...STATS_METHODS,
   ...ACCOUNT_METHODS,
+  ...PREFLIGHT_METHODS,
   ...COMPUTER_METHODS,
   ...SESSION_TAB_METHODS,
   ...FILE_METHODS,
diff --git a/src/main/runtime/rpc/methods/preflight.test.ts b/src/main/runtime/rpc/methods/preflight.test.ts
new file mode 100644
index 00000000000..51a1231caa3
--- /dev/null
+++ b/src/main/runtime/rpc/methods/preflight.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RpcDispatcher } from '../dispatcher'
+import type { RpcRequest } from '../core'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+import { PREFLIGHT_METHODS } from './preflight'
+
+const {
+  detectInstalledAgentsMock,
+  detectRemoteAgentsMock,
+  refreshShellPathAndDetectAgentsMock,
+  runPreflightCheckMock
+} = vi.hoisted(() => ({
+  detectInstalledAgentsMock: vi.fn(),
+  detectRemoteAgentsMock: vi.fn(),
+  refreshShellPathAndDetectAgentsMock: vi.fn(),
+  runPreflightCheckMock: vi.fn()
+}))
+
+vi.mock('../../../ipc/preflight', () => ({
+  detectInstalledAgents: detectInstalledAgentsMock,
+  detectRemoteAgents: detectRemoteAgentsMock,
+  refreshShellPathAndDetectAgents: refreshShellPathAndDetectAgentsMock,
+  runPreflightCheck: runPreflightCheckMock
+}))
+
+function makeRequest(method: string, params?: unknown): RpcRequest {
+  return { id: 'req-1', authToken: 'tok', method, params }
+}
+
+describe('preflight RPC methods', () => {
+  it('runs the server-side preflight check through runtime RPC', async () => {
+    const status = {
+      git: { installed: true },
+      gh: { installed: true, authenticated: true },
+      glab: { installed: false, authenticated: false },
+      bitbucket: { configured: false, authenticated: false, account: null }
+    }
+    runPreflightCheckMock.mockResolvedValueOnce(status)
+    const runtime = { getRuntimeId: () => 'test-runtime' } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: PREFLIGHT_METHODS })
+
+    const response = await dispatcher.dispatch(makeRequest('preflight.check', { force: true }))
+
+    expect(runPreflightCheckMock).toHaveBeenCalledWith(true)
+    expect(response).toMatchObject({ ok: true, result: status })
+  })
+
+  it('detects agents and refreshes PATH on the server through runtime RPC', async () => {
+    detectInstalledAgentsMock.mockResolvedValueOnce(['codex'])
+    refreshShellPathAndDetectAgentsMock.mockResolvedValueOnce({
+      agents: ['codex', 'claude'],
+      addedPathSegments: ['/opt/bin'],
+      shellHydrationOk: true,
+      pathSource: 'shell_hydrate',
+      pathFailureReason: 'none'
+    })
+    const runtime = { getRuntimeId: () => 'test-runtime' } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: PREFLIGHT_METHODS })
+
+    const detected = await dispatcher.dispatch(makeRequest('preflight.detectAgents'))
+    const refreshed = await dispatcher.dispatch(makeRequest('preflight.refreshAgents'))
+
+    expect(detectInstalledAgentsMock).toHaveBeenCalled()
+    expect(refreshShellPathAndDetectAgentsMock).toHaveBeenCalled()
+    expect(detected).toMatchObject({ ok: true, result: ['codex'] })
+    expect(refreshed).toMatchObject({
+      ok: true,
+      result: { agents: ['codex', 'claude'], shellHydrationOk: true }
+    })
+  })
+
+  it('detects agents on remote SSH connections through runtime RPC', async () => {
+    detectRemoteAgentsMock.mockResolvedValueOnce(['claude'])
+    const runtime = { getRuntimeId: () => 'test-runtime' } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: PREFLIGHT_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('preflight.detectRemoteAgents', { connectionId: 'ssh-1' })
+    )
+
+    expect(detectRemoteAgentsMock).toHaveBeenCalledWith({ connectionId: 'ssh-1' })
+    expect(response).toMatchObject({ ok: true, result: ['claude'] })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/preflight.ts b/src/main/runtime/rpc/methods/preflight.ts
new file mode 100644
index 00000000000..720a823cc22
--- /dev/null
+++ b/src/main/runtime/rpc/methods/preflight.ts
@@ -0,0 +1,38 @@
+import { z } from 'zod'
+import { defineMethod, type RpcMethod } from '../core'
+import {
+  detectRemoteAgents,
+  detectInstalledAgents,
+  refreshShellPathAndDetectAgents,
+  runPreflightCheck
+} from '../../../ipc/preflight'
+
+const PreflightCheck = z.object({
+  force: z.boolean().optional()
+})
+const PreflightDetectRemoteAgents = z.object({
+  connectionId: z.string().min(1)
+})
+
+export const PREFLIGHT_METHODS: RpcMethod[] = [
+  defineMethod({
+    name: 'preflight.check',
+    params: PreflightCheck,
+    handler: async (params) => runPreflightCheck(params.force)
+  }),
+  defineMethod({
+    name: 'preflight.detectAgents',
+    params: null,
+    handler: async () => detectInstalledAgents()
+  }),
+  defineMethod({
+    name: 'preflight.detectRemoteAgents',
+    params: PreflightDetectRemoteAgents,
+    handler: async (params) => detectRemoteAgents(params)
+  }),
+  defineMethod({
+    name: 'preflight.refreshAgents',
+    params: null,
+    handler: async () => refreshShellPathAndDetectAgents()
+  })
+]
diff --git a/src/main/runtime/rpc/static-web-client-handler.ts b/src/main/runtime/rpc/static-web-client-handler.ts
new file mode 100644
index 00000000000..650df1be75b
--- /dev/null
+++ b/src/main/runtime/rpc/static-web-client-handler.ts
@@ -0,0 +1,139 @@
+import { createReadStream } from 'fs'
+import { stat } from 'fs/promises'
+import type { IncomingMessage, RequestListener, ServerResponse } from 'http'
+import { extname, isAbsolute, posix, relative, resolve } from 'path'
+
+const STATIC_WEB_ALLOWED_PATHS = new Set(['/web-index.html'])
+const STATIC_WEB_ALLOWED_PREFIXES = ['/assets/']
+const STATIC_WEB_CONTENT_TYPES = new Map([
+  ['.css', 'text/css; charset=utf-8'],
+  ['.html', 'text/html; charset=utf-8'],
+  ['.js', 'text/javascript; charset=utf-8'],
+  ['.json', 'application/json; charset=utf-8'],
+  ['.png', 'image/png'],
+  ['.svg', 'image/svg+xml; charset=utf-8'],
+  ['.wasm', 'application/wasm'],
+  ['.webp', 'image/webp'],
+  ['.woff2', 'font/woff2']
+])
+
+export function createStaticWebClientHandler(staticRoot: string): RequestListener {
+  const resolvedRoot = resolve(staticRoot)
+  return (request, response) => {
+    void handleStaticRequest(resolvedRoot, request, response)
+  }
+}
+
+async function handleStaticRequest(
+  staticRoot: string,
+  request: IncomingMessage,
+  response: ServerResponse
+): Promise<void> {
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    response.setHeader('Allow', 'GET, HEAD')
+    writeHttpStatus(response, 405)
+    return
+  }
+
+  const pathname = parseStaticPathname(request.url)
+  if (!pathname) {
+    writeHttpStatus(response, 400)
+    return
+  }
+  if (!isAllowedStaticWebPath(pathname)) {
+    writeHttpStatus(response, 404)
+    return
+  }
+
+  const absolutePath = resolve(staticRoot, pathname.slice(1))
+  const relativePath = relative(staticRoot, absolutePath)
+  if (relativePath === '' || relativePath.startsWith('..') || isAbsolute(relativePath)) {
+    writeHttpStatus(response, 404)
+    return
+  }
+
+  let fileStat
+  try {
+    fileStat = await stat(absolutePath)
+  } catch {
+    writeHttpStatus(response, 404)
+    return
+  }
+  if (!fileStat.isFile()) {
+    writeHttpStatus(response, 404)
+    return
+  }
+
+  response.statusCode = 200
+  response.setHeader(
+    'Content-Type',
+    STATIC_WEB_CONTENT_TYPES.get(extname(absolutePath)) ?? 'application/octet-stream'
+  )
+  response.setHeader('Content-Length', fileStat.size)
+  response.setHeader(
+    'Cache-Control',
+    pathname.startsWith('/assets/') ? 'public, max-age=31536000, immutable' : 'no-cache'
+  )
+  if (request.method === 'HEAD') {
+    response.end()
+    return
+  }
+
+  const stream = createReadStream(absolutePath)
+  stream.on('error', () => {
+    if (!response.headersSent) {
+      writeHttpStatus(response, 500)
+      return
+    }
+    response.destroy()
+  })
+  stream.pipe(response)
+}
+
+function parseStaticPathname(rawUrl: string | undefined): string | null {
+  if (!rawUrl) {
+    return '/web-index.html'
+  }
+  let pathname: string
+  try {
+    pathname = decodeURIComponent(new URL(rawUrl, 'http://127.0.0.1').pathname)
+  } catch {
+    return null
+  }
+  if (pathname === '/' || pathname === '/index.html') {
+    return '/web-index.html'
+  }
+  if (pathname.includes('\0') || pathname.includes('\\') || pathname.split('/').includes('..')) {
+    return null
+  }
+  if (posix.normalize(pathname) !== pathname) {
+    return null
+  }
+  return mapProxyPrefixedStaticPathname(pathname)
+}
+
+function mapProxyPrefixedStaticPathname(pathname: string): string {
+  if (pathname === '/web-index.html' || pathname.endsWith('/web-index.html')) {
+    return '/web-index.html'
+  }
+  const assetMarker = '/assets/'
+  const assetIndex = pathname.indexOf(assetMarker)
+  if (assetIndex !== -1) {
+    // Why: reverse proxies may forward the external path prefix through to
+    // Orca. Only the bundled /assets subtree is served after the prefix.
+    return pathname.slice(assetIndex)
+  }
+  return pathname
+}
+
+function isAllowedStaticWebPath(pathname: string): boolean {
+  return (
+    STATIC_WEB_ALLOWED_PATHS.has(pathname) ||
+    STATIC_WEB_ALLOWED_PREFIXES.some((prefix) => pathname.startsWith(prefix))
+  )
+}
+
+function writeHttpStatus(response: ServerResponse, statusCode: number): void {
+  response.statusCode = statusCode
+  response.end()
+}
diff --git a/src/main/runtime/rpc/ws-transport-static-web.test.ts b/src/main/runtime/rpc/ws-transport-static-web.test.ts
new file mode 100644
index 00000000000..ed321b5c0a1
--- /dev/null
+++ b/src/main/runtime/rpc/ws-transport-static-web.test.ts
@@ -0,0 +1,91 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { WebSocketTransport } from './ws-transport'
+
+describe('WebSocketTransport static web client', () => {
+  const transports: WebSocketTransport[] = []
+
+  afterEach(async () => {
+    await Promise.all(transports.map((t) => t.stop().catch(() => {})))
+    transports.length = 0
+  })
+
+  function createStaticTransport(staticRoot: string): WebSocketTransport {
+    const transport = new WebSocketTransport({
+      host: '127.0.0.1',
+      port: 0,
+      staticRoot
+    })
+    transports.push(transport)
+    return transport
+  }
+
+  it('serves the built web client from the same server', async () => {
+    const staticRoot = mkdtempSync(join(tmpdir(), 'ws-transport-static-'))
+    mkdirSync(join(staticRoot, 'assets'))
+    writeFileSync(join(staticRoot, 'web-index.html'), '<html>web</html>')
+    writeFileSync(join(staticRoot, 'assets', 'app.js'), 'console.log("web")')
+    const transport = createStaticTransport(staticRoot)
+
+    await transport.start()
+
+    const indexResponse = await fetch(`http://127.0.0.1:${transport.resolvedPort}/web-index.html`)
+    expect(indexResponse.status).toBe(200)
+    expect(indexResponse.headers.get('content-type')).toContain('text/html')
+    await expect(indexResponse.text()).resolves.toBe('<html>web</html>')
+
+    const assetResponse = await fetch(`http://127.0.0.1:${transport.resolvedPort}/assets/app.js`)
+    expect(assetResponse.status).toBe(200)
+    expect(assetResponse.headers.get('cache-control')).toContain('immutable')
+    await expect(assetResponse.text()).resolves.toBe('console.log("web")')
+  })
+
+  it('serves web assets when a reverse-proxy path prefix is forwarded', async () => {
+    const staticRoot = mkdtempSync(join(tmpdir(), 'ws-transport-static-'))
+    mkdirSync(join(staticRoot, 'assets'))
+    writeFileSync(join(staticRoot, 'web-index.html'), '<script src="./assets/app.js"></script>')
+    writeFileSync(join(staticRoot, 'assets', 'app.js'), 'console.log("prefixed")')
+    const transport = createStaticTransport(staticRoot)
+
+    await transport.start()
+
+    const indexResponse = await fetch(
+      `http://127.0.0.1:${transport.resolvedPort}/orca/web-index.html`
+    )
+    expect(indexResponse.status).toBe(200)
+    await expect(indexResponse.text()).resolves.toBe('<script src="./assets/app.js"></script>')
+
+    const assetResponse = await fetch(
+      `http://127.0.0.1:${transport.resolvedPort}/orca/assets/app.js`
+    )
+    expect(assetResponse.status).toBe(200)
+    await expect(assetResponse.text()).resolves.toBe('console.log("prefixed")')
+  })
+
+  it('does not expose arbitrary files from the static root', async () => {
+    const staticRoot = mkdtempSync(join(tmpdir(), 'ws-transport-static-'))
+    writeFileSync(join(staticRoot, 'package.json'), '{}')
+    const transport = createStaticTransport(staticRoot)
+
+    await transport.start()
+
+    const response = await fetch(`http://127.0.0.1:${transport.resolvedPort}/package.json`)
+    expect(response.status).toBe(404)
+  })
+
+  it('rejects encoded Windows separators in static paths', async () => {
+    const staticRoot = mkdtempSync(join(tmpdir(), 'ws-transport-static-'))
+    mkdirSync(join(staticRoot, 'assets'))
+    writeFileSync(join(staticRoot, 'package.json'), '{}')
+    const transport = createStaticTransport(staticRoot)
+
+    await transport.start()
+
+    const response = await fetch(
+      `http://127.0.0.1:${transport.resolvedPort}/assets/..%5Cpackage.json`
+    )
+    expect(response.status).toBe(400)
+  })
+})
diff --git a/src/main/runtime/rpc/ws-transport.test.ts b/src/main/runtime/rpc/ws-transport.test.ts
index 2f3bcf6bdb6..72af8f18590 100644
--- a/src/main/runtime/rpc/ws-transport.test.ts
+++ b/src/main/runtime/rpc/ws-transport.test.ts
@@ -1,3 +1,6 @@
+/* eslint-disable max-lines -- Why: these tests exercise one stateful transport
+   boundary across connection lifecycle, heartbeat, pre-auth timeout, and
+   shutdown behavior; splitting the setup would obscure the shared invariants. */
 import { mkdtempSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
diff --git a/src/main/runtime/rpc/ws-transport.ts b/src/main/runtime/rpc/ws-transport.ts
index 028c3f379ce..07ccc095265 100644
--- a/src/main/runtime/rpc/ws-transport.ts
+++ b/src/main/runtime/rpc/ws-transport.ts
@@ -1,3 +1,6 @@
+/* eslint-disable max-lines -- Why: the WebSocket transport owns connection
+   admission, heartbeat, pre-auth timeout, and client-id cleanup together; those
+   invariants are easier to audit in one transport boundary. */
 // Why: the WebSocket transport enables mobile clients to connect to the Orca
 // runtime over the local network. When TLS cert/key are provided it uses wss://
 // to prevent passive sniffing; otherwise it falls back to plain ws://. Per-device
@@ -7,6 +10,7 @@ import { createServer as createHttpsServer, type Server as HttpsServer } from 'h
 import { createServer as createHttpServer, type Server as HttpServer } from 'http'
 import { WebSocketServer, type WebSocket } from 'ws'
 import type { RpcTransport } from './transport'
+import { createStaticWebClientHandler } from './static-web-client-handler'
 
 const MAX_WS_MESSAGE_BYTES = 1024 * 1024
 const MAX_WS_CONNECTIONS = 32
@@ -41,6 +45,9 @@ export type WebSocketTransportOptions = {
   heartbeatIntervalMs?: number
   // Why: test-only override. Production uses PRE_AUTH_TIMEOUT_MS.
   preAuthTimeoutMs?: number
+  // Why: the pairing server can also serve the browser client, so users do
+  // not need a second dev/static server once the web bundle is built.
+  staticRoot?: string
 }
 
 export class WebSocketTransport implements RpcTransport {
@@ -50,6 +57,7 @@ export class WebSocketTransport implements RpcTransport {
   private readonly tlsKey: string | undefined
   private readonly heartbeatIntervalMs: number
   private readonly preAuthTimeoutMs: number
+  private readonly staticRoot: string | undefined
   private httpServer: HttpsServer | HttpServer | null = null
   private wss: WebSocketServer | null = null
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null
@@ -72,7 +80,8 @@ export class WebSocketTransport implements RpcTransport {
     tlsCert,
     tlsKey,
     heartbeatIntervalMs,
-    preAuthTimeoutMs
+    preAuthTimeoutMs,
+    staticRoot
   }: WebSocketTransportOptions) {
     this.host = host
     this.port = port
@@ -80,6 +89,7 @@ export class WebSocketTransport implements RpcTransport {
     this.tlsKey = tlsKey
     this.heartbeatIntervalMs = heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS
     this.preAuthTimeoutMs = preAuthTimeoutMs ?? PRE_AUTH_TIMEOUT_MS
+    this.staticRoot = staticRoot
   }
 
   onMessage(handler: WebSocketMessageHandler): void {
@@ -150,9 +160,12 @@ export class WebSocketTransport implements RpcTransport {
   }
 
   private createHttpServer(): HttpServer | HttpsServer {
+    const requestListener = this.staticRoot
+      ? createStaticWebClientHandler(this.staticRoot)
+      : undefined
     return this.tlsCert && this.tlsKey
-      ? createHttpsServer({ cert: this.tlsCert, key: this.tlsKey })
-      : createHttpServer()
+      ? createHttpsServer({ cert: this.tlsCert, key: this.tlsKey }, requestListener)
+      : createHttpServer(requestListener)
   }
 
   // Why: the WebSocketServer is attached only after listen succeeds. If we
diff --git a/src/main/runtime/runtime-rpc.test.ts b/src/main/runtime/runtime-rpc.test.ts
index acbbcdaa979..a67388bf142 100644
--- a/src/main/runtime/runtime-rpc.test.ts
+++ b/src/main/runtime/runtime-rpc.test.ts
@@ -255,7 +255,8 @@ describe('OrcaRuntimeRpcServer', () => {
       runtime,
       userDataPath,
       enableWebSocket: true,
-      wsPort: 0
+      wsPort: 0,
+      webClientRoot: userDataPath
     })
 
     await server.start()
@@ -274,6 +275,63 @@ describe('OrcaRuntimeRpcServer', () => {
     await server.stop()
   })
 
+  it('includes a web client URL when the web bundle is served by the runtime', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0,
+      webClientRoot: userDataPath
+    })
+
+    await server.start()
+
+    try {
+      const offer = server.createPairingOffer({ address: '100.64.1.20', name: 'Web test' })
+      expect(offer.available).toBe(true)
+      if (offer.available) {
+        expect(offer.webClientUrl).toBeTruthy()
+        const url = new URL(offer.webClientUrl!)
+        expect(url.protocol).toBe('http:')
+        expect(url.hostname).toBe('100.64.1.20')
+        expect(url.pathname).toBe('/web-index.html')
+        expect(url.search).toBe('')
+        expect(url.hash).toBe(`#pairing=${encodeURIComponent(offer.pairingUrl)}`)
+      }
+    } finally {
+      await server.stop()
+    }
+  })
+
+  it('preserves proxy path prefixes in web client URLs', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+    const runtime = new OrcaRuntimeService()
+    const server = new OrcaRuntimeRpcServer({
+      runtime,
+      userDataPath,
+      enableWebSocket: true,
+      wsPort: 0,
+      webClientRoot: userDataPath
+    })
+
+    await server.start()
+
+    try {
+      const offer = server.createPairingOffer({
+        address: 'wss://runtime.example.com/orca',
+        name: 'Proxy test'
+      })
+      expect(offer.available).toBe(true)
+      if (offer.available) {
+        expect(offer.webClientUrl).toContain('https://runtime.example.com/orca/web-index.html')
+      }
+    } finally {
+      await server.stop()
+    }
+  })
+
   it('formats pairing-address overrides for IPv6 and host-port tunnel endpoints', async () => {
     const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
     const runtime = new OrcaRuntimeService()
@@ -281,7 +339,8 @@ describe('OrcaRuntimeRpcServer', () => {
       runtime,
       userDataPath,
       enableWebSocket: true,
-      wsPort: 0
+      wsPort: 0,
+      webClientRoot: userDataPath
     })
 
     await server.start()
@@ -323,7 +382,8 @@ describe('OrcaRuntimeRpcServer', () => {
       runtime,
       userDataPath,
       enableWebSocket: true,
-      wsPort: 0
+      wsPort: 0,
+      webClientRoot: userDataPath
     })
 
     await server.start()
@@ -340,6 +400,7 @@ describe('OrcaRuntimeRpcServer', () => {
       }
 
       expect(server.getDeviceRegistry()?.getDevice(offer.deviceId)?.scope).toBe('mobile')
+      expect(offer.webClientUrl).toBeNull()
       const parsed = parsePairingCode(offer.pairingUrl)
       expect(parsed?.endpoint).toBe(offer.endpoint)
       expect(parsed?.endpoint).toContain('100.64.1.20')
diff --git a/src/main/runtime/runtime-rpc.ts b/src/main/runtime/runtime-rpc.ts
index da555f98833..f4687e2a9e4 100644
--- a/src/main/runtime/runtime-rpc.ts
+++ b/src/main/runtime/runtime-rpc.ts
@@ -35,6 +35,7 @@ type OrcaRuntimeRpcServerOptions = {
   platform?: NodeJS.Platform
   enableWebSocket?: boolean
   wsPort?: number
+  webClientRoot?: string
   // Why: test-only overrides for the two time-bound constants below.
   // Production callers must not pass these — defaults are set by the design
   // doc (§3.1) and changing them in production would weaken the admission
@@ -98,6 +99,24 @@ function formatWebSocketUrl(url: URL): string {
   return url.pathname === '/' && !url.search && !url.hash ? formatted.replace(/\/$/, '') : formatted
 }
 
+function createWebClientUrl(endpoint: string, pairingUrl: string): string {
+  const url = new URL(endpoint)
+  url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:'
+  url.pathname = webClientPathForEndpoint(url.pathname)
+  url.search = ''
+  // Why: pairing URLs include full runtime credentials. Keeping them in the
+  // fragment avoids proxy logs and Referer headers while the web app loads.
+  url.hash = `pairing=${encodeURIComponent(pairingUrl)}`
+  return url.toString()
+}
+
+function webClientPathForEndpoint(pathname: string): string {
+  if (!pathname || pathname === '/') {
+    return '/web-index.html'
+  }
+  return `${pathname.replace(/\/$/, '')}/web-index.html`
+}
+
 const MOBILE_RPC_METHOD_ALLOWLIST = new Set([
   'accounts.list',
   'accounts.selectClaude',
@@ -165,6 +184,7 @@ export class OrcaRuntimeRpcServer {
   private readonly platform: NodeJS.Platform
   private readonly enableWebSocket: boolean
   private readonly wsPort: number
+  private readonly webClientRoot: string | undefined
   private readonly authToken = randomBytes(24).toString('hex')
   private readonly keepaliveIntervalMs: number
   private readonly longPollCap: number
@@ -197,6 +217,7 @@ export class OrcaRuntimeRpcServer {
     platform = process.platform,
     enableWebSocket = false,
     wsPort = DEFAULT_WS_PORT,
+    webClientRoot,
     keepaliveIntervalMs = KEEPALIVE_INTERVAL_MS,
     longPollCap = LONG_POLL_CAP
   }: OrcaRuntimeRpcServerOptions) {
@@ -207,6 +228,7 @@ export class OrcaRuntimeRpcServer {
     this.platform = platform
     this.enableWebSocket = enableWebSocket
     this.wsPort = wsPort
+    this.webClientRoot = webClientRoot
     this.keepaliveIntervalMs = keepaliveIntervalMs
     this.longPollCap = longPollCap
   }
@@ -248,7 +270,13 @@ export class OrcaRuntimeRpcServer {
     scope?: DeviceScope
   }):
     | { available: false }
-    | { available: true; pairingUrl: string; endpoint: string; deviceId: string } {
+    | {
+        available: true
+        pairingUrl: string
+        endpoint: string
+        deviceId: string
+        webClientUrl: string | null
+      } {
     const rawEndpoint = this.getWebSocketEndpoint()
     const publicKeyB64 = this.getE2EEPublicKey()
     if (!rawEndpoint || !this.deviceRegistry || !publicKeyB64) {
@@ -267,7 +295,14 @@ export class OrcaRuntimeRpcServer {
       deviceToken: device.token,
       publicKeyB64
     })
-    return { available: true, pairingUrl, endpoint, deviceId: device.deviceId }
+    return {
+      available: true,
+      pairingUrl,
+      endpoint,
+      deviceId: device.deviceId,
+      webClientUrl:
+        this.webClientRoot && scope === 'runtime' ? createWebClientUrl(endpoint, pairingUrl) : null
+    }
   }
 
   private registerBinaryStreamHandler(
@@ -384,7 +419,8 @@ export class OrcaRuntimeRpcServer {
 
         const wsTransport = new WebSocketTransport({
           host: '0.0.0.0',
-          port: this.wsPort
+          port: this.wsPort,
+          staticRoot: this.webClientRoot
         })
         this.wsTransport = wsTransport
 
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 9eb7f202d3f..cecd0f29da4 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -1577,6 +1577,16 @@ export type PreloadApi = {
           deviceId: string
         }
     >
+    getRuntimePairingUrl: (args?: { address?: string; rotate?: boolean }) => Promise<
+      | { available: false }
+      | {
+          available: true
+          pairingUrl: string
+          webClientUrl: string | null
+          endpoint: string
+          deviceId: string
+        }
+    >
     listDevices: () => Promise<{
       devices: { deviceId: string; name: string; pairedAt: number; lastSeenAt: number }[]
     }>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index d26874832be..d87d80f2e36 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -2618,6 +2618,20 @@ const api = {
         }
     > => ipcRenderer.invoke('mobile:getPairingQR', args),
 
+    getRuntimePairingUrl: (args?: {
+      address?: string
+      rotate?: boolean
+    }): Promise<
+      | { available: false }
+      | {
+          available: true
+          pairingUrl: string
+          webClientUrl: string | null
+          endpoint: string
+          deviceId: string
+        }
+    > => ipcRenderer.invoke('mobile:getRuntimePairingUrl', args),
+
     listDevices: (): Promise<{
       devices: { deviceId: string; name: string; pairedAt: number; lastSeenAt: number }[]
     }> => ipcRenderer.invoke('mobile:listDevices'),
diff --git a/src/renderer/src/components/LinearItemDrawer.tsx b/src/renderer/src/components/LinearItemDrawer.tsx
index d4aac63d8d8..38fa892267c 100644
--- a/src/renderer/src/components/LinearItemDrawer.tsx
+++ b/src/renderer/src/components/LinearItemDrawer.tsx
@@ -11,6 +11,7 @@ import { VisuallyHidden } from 'radix-ui'
 import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
 import { cn } from '@/lib/utils'
 import { useAppStore } from '@/store'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 import {
   useTeamStates,
   useTeamLabels,
@@ -447,7 +448,7 @@ function CommentFooter({
       if (typed.ok) {
         setBody('')
         onCommentAdded({
-          id: typed.id ?? crypto.randomUUID(),
+          id: typed.id ?? createBrowserUuid(),
           body: trimmed,
           createdAt: new Date().toISOString()
         })
diff --git a/src/renderer/src/components/editor/ipynb-parse.ts b/src/renderer/src/components/editor/ipynb-parse.ts
index ffd2692b875..0415c417169 100644
--- a/src/renderer/src/components/editor/ipynb-parse.ts
+++ b/src/renderer/src/components/editor/ipynb-parse.ts
@@ -1,6 +1,8 @@
 /* eslint-disable max-lines -- Why: keeping notebook parse and mutation helpers
 in one module makes nbformat preservation easier to audit while the notebook
 editor model is still small. */
+import { createBrowserUuid } from '@/lib/browser-uuid'
+
 export type IpynbCellKind = 'code' | 'markdown' | 'raw'
 
 export type IpynbOutput =
@@ -288,7 +290,7 @@ export function insertIpynbCell(
   const cells = root.cells as unknown[]
   const nextCell: Record<string, unknown> = {
     cell_type: kind,
-    id: crypto.randomUUID?.() ?? `cell-${Date.now()}`,
+    id: createBrowserUuid(),
     metadata: {},
     source: []
   }
@@ -307,7 +309,7 @@ export function deleteIpynbCell(content: string, index: number): string {
   if (cells.length <= 1) {
     cells.splice(0, cells.length, {
       cell_type: 'code',
-      id: crypto.randomUUID?.() ?? `cell-${Date.now()}`,
+      id: createBrowserUuid(),
       metadata: {},
       execution_count: null,
       outputs: [],
diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
index a83df7ae613..fa472c63ed4 100644
--- a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
@@ -17,6 +17,7 @@ import { notifyProjectNotesSelectionChanged } from '@/lib/open-project-notes-tab
 import { requestProjectNotesTabClose } from '@/lib/project-notes-close-request'
 import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
 import { useAppStore } from '@/store'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../../shared/constants'
 import type { TerminalTab } from '../../../../shared/types'
 import { FloatingTerminalOrchestrationDialog } from './FloatingTerminalOrchestrationDialog'
@@ -237,7 +238,7 @@ export function FloatingTerminalPanel({
           notifyProjectNotesSelectionChanged()
         }
       }
-      const id = `floating-project-notes:${globalThis.crypto.randomUUID()}`
+      const id = `floating-project-notes:${createBrowserUuid()}`
       setNotesTabs((current) => [...current, { id, label, noteId: noteId ?? null, isDirty: false }])
       setActiveNotesTabId(id)
       setActiveSurface('notes')
diff --git a/src/renderer/src/components/settings/CliSection.tsx b/src/renderer/src/components/settings/CliSection.tsx
index 496f2bab6dd..b091665a715 100644
--- a/src/renderer/src/components/settings/CliSection.tsx
+++ b/src/renderer/src/components/settings/CliSection.tsx
@@ -65,6 +65,7 @@ export function CliSection({ currentPlatform }: CliSectionProps): React.JSX.Elem
 
   const isEnabled = status?.state === 'installed'
   const isSupported = status?.supported ?? false
+  const isBrowserManaged = status?.unsupportedReason === 'launch_mode_unavailable'
   const revealLabel = getRevealLabel(currentPlatform)
   const canRevealCommandPath =
     status?.commandPath != null && ['installed', 'stale', 'conflict'].includes(status.state)
@@ -145,21 +146,23 @@ export function CliSection({ currentPlatform }: CliSectionProps): React.JSX.Elem
                 </TooltipContent>
               </Tooltip>
             </TooltipProvider>
-            <button
-              role="switch"
-              aria-checked={isEnabled}
-              disabled={loading || !isSupported || busyAction !== null}
-              onClick={() => setDialogOpen(true)}
-              className={`relative inline-flex h-5 w-9 shrink-0 items-center rounded-full border border-transparent transition-colors ${
-                isEnabled ? 'bg-foreground' : 'bg-muted-foreground/30'
-              } ${loading || !isSupported || busyAction !== null ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'}`}
-            >
-              <span
-                className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
-                  isEnabled ? 'translate-x-4' : 'translate-x-0.5'
-                }`}
-              />
-            </button>
+            {!isBrowserManaged ? (
+              <button
+                role="switch"
+                aria-checked={isEnabled}
+                disabled={loading || !isSupported || busyAction !== null}
+                onClick={() => setDialogOpen(true)}
+                className={`relative inline-flex h-5 w-9 shrink-0 items-center rounded-full border border-transparent transition-colors ${
+                  isEnabled ? 'bg-foreground' : 'bg-muted-foreground/30'
+                } ${loading || !isSupported || busyAction !== null ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'}`}
+              >
+                <span
+                  className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
+                    isEnabled ? 'translate-x-4' : 'translate-x-0.5'
+                  }`}
+                />
+              </button>
+            ) : null}
           </div>
         </div>
 
@@ -182,7 +185,7 @@ export function CliSection({ currentPlatform }: CliSectionProps): React.JSX.Elem
           </p>
         ) : null}
 
-        {!loading && !isSupported && status?.detail ? (
+        {!loading && !isSupported && !isBrowserManaged && status?.detail ? (
           <p className="text-xs text-muted-foreground">{status.detail}</p>
         ) : null}
 
@@ -201,44 +204,46 @@ export function CliSection({ currentPlatform }: CliSectionProps): React.JSX.Elem
           ) : null}
         </div>
 
-        <div className="border-t border-border/60 pt-3">
-          <div className="space-y-0.5">
-            <Label>Agent skills</Label>
-            <p className="text-xs text-muted-foreground">
-              Install skills so agents know how to use Orca and report status.
-            </p>
-          </div>
+        {!isBrowserManaged ? (
+          <div className="border-t border-border/60 pt-3">
+            <div className="space-y-0.5">
+              <Label>Agent skills</Label>
+              <p className="text-xs text-muted-foreground">
+                Install skills so agents know how to use Orca and report status.
+              </p>
+            </div>
 
-          <div className="mt-3 space-y-3">
-            <div className="space-y-1">
-              <p className="text-xs text-muted-foreground">CLI skill</p>
-              <div className="inline-flex max-w-full items-center gap-2 rounded-lg border border-border/60 bg-background/60 px-3 py-2">
-                <code className="overflow-x-auto whitespace-nowrap text-[11px] text-muted-foreground">
-                  {ORCA_CLI_SKILL_INSTALL_COMMAND}
-                </code>
-                <TooltipProvider delayDuration={250}>
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <Button
-                        variant="ghost"
-                        size="icon-xs"
-                        onClick={() =>
-                          void handleCopySkillInstallCommand(ORCA_CLI_SKILL_INSTALL_COMMAND)
-                        }
-                        aria-label="Copy CLI skill install command"
-                      >
-                        <Copy className="size-3.5" />
-                      </Button>
-                    </TooltipTrigger>
-                    <TooltipContent side="bottom" sideOffset={6}>
-                      Copy
-                    </TooltipContent>
-                  </Tooltip>
-                </TooltipProvider>
+            <div className="mt-3 space-y-3">
+              <div className="space-y-1">
+                <p className="text-xs text-muted-foreground">CLI skill</p>
+                <div className="inline-flex max-w-full items-center gap-2 rounded-lg border border-border/60 bg-background/60 px-3 py-2">
+                  <code className="overflow-x-auto whitespace-nowrap text-[11px] text-muted-foreground">
+                    {ORCA_CLI_SKILL_INSTALL_COMMAND}
+                  </code>
+                  <TooltipProvider delayDuration={250}>
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <Button
+                          variant="ghost"
+                          size="icon-xs"
+                          onClick={() =>
+                            void handleCopySkillInstallCommand(ORCA_CLI_SKILL_INSTALL_COMMAND)
+                          }
+                          aria-label="Copy CLI skill install command"
+                        >
+                          <Copy className="size-3.5" />
+                        </Button>
+                      </TooltipTrigger>
+                      <TooltipContent side="bottom" sideOffset={6}>
+                        Copy
+                      </TooltipContent>
+                    </Tooltip>
+                  </TooltipProvider>
+                </div>
               </div>
             </div>
           </div>
-        </div>
+        ) : null}
       </div>
 
       <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
diff --git a/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx b/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
index b6254ba3226..bad28dccbf1 100644
--- a/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
+++ b/src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
@@ -1,4 +1,7 @@
-import { Loader2, Plus, RefreshCw, Trash2 } from 'lucide-react'
+/* eslint-disable max-lines -- Why: the server settings pane keeps active
+   server selection, saved server mutation, and confirmation dialogs together so
+   the state transitions stay auditable. */
+import { Loader2, Plus, RefreshCw, Share2, Trash2 } from 'lucide-react'
 import { useEffect, useState } from 'react'
 import { toast } from 'sonner'
 import type { GlobalSettings } from '../../../../shared/types'
@@ -8,7 +11,6 @@ import { Input } from '../ui/input'
 import { Label } from '../ui/label'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
 import { SearchableSetting } from './SearchableSetting'
-import type { SettingsSearchEntry } from './settings-search'
 import {
   Dialog,
   DialogContent,
@@ -17,33 +19,27 @@ import {
   DialogHeader,
   DialogTitle
 } from '../ui/dialog'
+import { RuntimePairingUrlGenerator } from './RuntimePairingUrlGenerator'
+import {
+  RUNTIME_ENVIRONMENTS_SEARCH_ENTRY,
+  WEB_RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
+} from './runtime-environments-search'
 
 const LOCAL_RUNTIME_VALUE = '__local__'
-
-export const RUNTIME_ENVIRONMENTS_SEARCH_ENTRY: SettingsSearchEntry = {
-  title: 'Active Server',
-  description: 'Choose local desktop or a saved remote Orca server.',
-  keywords: [
-    'runtime',
-    'environment',
-    'server',
-    'client',
-    'remote',
-    'pairing',
-    'cloud',
-    'vm',
-    'dev box'
-  ]
-}
+const NO_RUNTIME_VALUE = '__none__'
 
 type RuntimeEnvironmentsPaneProps = {
   settings: GlobalSettings
   switchRuntimeEnvironment: (environmentId: string | null) => Promise<boolean>
+  canGeneratePairingUrl?: boolean
+  allowLocalRuntime?: boolean
 }
 
 export function RuntimeEnvironmentsPane({
   settings,
-  switchRuntimeEnvironment
+  switchRuntimeEnvironment,
+  canGeneratePairingUrl = true,
+  allowLocalRuntime = true
 }: RuntimeEnvironmentsPaneProps): React.JSX.Element {
   const [environments, setEnvironments] = useState<PublicKnownRuntimeEnvironment[]>([])
   const [isLoading, setIsLoading] = useState(false)
@@ -52,13 +48,20 @@ export function RuntimeEnvironmentsPane({
   const [removingId, setRemovingId] = useState<string | null>(null)
   const [pendingSwitchValue, setPendingSwitchValue] = useState<string | null>(null)
   const [pendingRemove, setPendingRemove] = useState<PublicKnownRuntimeEnvironment | null>(null)
+  const [addServerFormOpen, setAddServerFormOpen] = useState(false)
+  const [shareServerFormOpen, setShareServerFormOpen] = useState(false)
   const [switchError, setSwitchError] = useState<string | null>(null)
   const [removeError, setRemoveError] = useState<string | null>(null)
   const [name, setName] = useState('')
   const [pairingCode, setPairingCode] = useState('')
-  const activeValue = settings.activeRuntimeEnvironmentId ?? LOCAL_RUNTIME_VALUE
+  const activeValue =
+    settings.activeRuntimeEnvironmentId ??
+    (allowLocalRuntime ? LOCAL_RUNTIME_VALUE : NO_RUNTIME_VALUE)
   const isBusy = isSaving || switchingValue !== null || removingId !== null
   const removingActiveServer = pendingRemove?.id === settings.activeRuntimeEnvironmentId
+  const searchEntry = canGeneratePairingUrl
+    ? RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
+    : WEB_RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
 
   const loadEnvironments = async (): Promise<void> => {
     setIsLoading(true)
@@ -75,6 +78,15 @@ export function RuntimeEnvironmentsPane({
     void loadEnvironments()
   }, [])
 
+  const closeAddServerForm = (): void => {
+    if (isSaving) {
+      return
+    }
+    setAddServerFormOpen(false)
+    setName('')
+    setPairingCode('')
+  }
+
   const addEnvironment = async (): Promise<void> => {
     const trimmedName = name.trim()
     const trimmedPairingCode = pairingCode.trim()
@@ -91,6 +103,12 @@ export function RuntimeEnvironmentsPane({
     }
     setIsSaving(true)
     try {
+      if (!allowLocalRuntime && settings.activeRuntimeEnvironmentId) {
+        const disconnected = await switchRuntimeEnvironment(null)
+        if (!disconnected) {
+          return
+        }
+      }
       const result = await window.api.runtimeEnvironments.addFromPairingCode({
         name: trimmedName,
         pairingCode: trimmedPairingCode
@@ -98,7 +116,18 @@ export function RuntimeEnvironmentsPane({
       setName('')
       setPairingCode('')
       await loadEnvironments()
-      toast.success(`Saved ${result.environment.name}. Use Active Server to switch when ready.`)
+      if (!allowLocalRuntime) {
+        const switched = await switchRuntimeEnvironment(result.environment.id)
+        if (!switched) {
+          await window.api.runtimeEnvironments.remove({ selector: result.environment.id })
+          await loadEnvironments()
+          return
+        }
+        toast.success(`Connected to ${result.environment.name}.`)
+      } else {
+        toast.success(`Saved ${result.environment.name}. Use Active Server to switch when ready.`)
+      }
+      setAddServerFormOpen(false)
     } catch (error) {
       toast.error(error instanceof Error ? error.message : 'Failed to save runtime environment.')
     } finally {
@@ -115,9 +144,18 @@ export function RuntimeEnvironmentsPane({
       if (settings.activeRuntimeEnvironmentId === environment.id) {
         const switched = await switchRuntimeEnvironment(null)
         if (!switched) {
-          setRemoveError('Could not switch to Local desktop. Fix the issue and try again.')
+          setRemoveError(
+            allowLocalRuntime
+              ? 'Could not switch to Local desktop. Fix the issue and try again.'
+              : 'Could not disconnect from this server. Fix the issue and try again.'
+          )
           return false
         }
+        if (!allowLocalRuntime) {
+          await loadEnvironments()
+          toast.success(`Removed ${environment.name}.`)
+          return true
+        }
       }
       await window.api.runtimeEnvironments.remove({ selector: environment.id })
       await loadEnvironments()
@@ -135,10 +173,15 @@ export function RuntimeEnvironmentsPane({
   }
 
   const switchToValue = async (value: string): Promise<boolean> => {
+    if (value === NO_RUNTIME_VALUE) {
+      return false
+    }
     setSwitchingValue(value)
     setSwitchError(null)
     try {
-      const switched = await switchRuntimeEnvironment(value === LOCAL_RUNTIME_VALUE ? null : value)
+      const switched = await switchRuntimeEnvironment(
+        allowLocalRuntime && value === LOCAL_RUNTIME_VALUE ? null : value
+      )
       if (switched) {
         toast.success(`Switched to ${getEnvironmentLabel(value)}.`)
         return true
@@ -159,22 +202,26 @@ export function RuntimeEnvironmentsPane({
     if (value === LOCAL_RUNTIME_VALUE) {
       return 'Local desktop'
     }
+    if (value === NO_RUNTIME_VALUE) {
+      return 'No server connected'
+    }
     return environments.find((environment) => environment.id === value)?.name ?? 'remote server'
   }
 
   return (
     <SearchableSetting
-      title={RUNTIME_ENVIRONMENTS_SEARCH_ENTRY.title}
-      description={RUNTIME_ENVIRONMENTS_SEARCH_ENTRY.description}
-      keywords={RUNTIME_ENVIRONMENTS_SEARCH_ENTRY.keywords}
+      title={searchEntry.title}
+      description={searchEntry.description}
+      keywords={searchEntry.keywords}
       className="space-y-4 px-1 py-2"
     >
       <div className="space-y-2">
         <div className="space-y-1">
           <Label id="runtime-active-server-label">Active Server</Label>
           <p className="text-xs text-muted-foreground">
-            Local keeps today&apos;s desktop behavior. Saved servers route supported client calls
-            through the remote runtime.
+            {allowLocalRuntime
+              ? "Local keeps today's desktop behavior. Saved servers route supported client calls through the remote runtime."
+              : 'Saved servers route this browser through a paired Orca runtime.'}
           </p>
         </div>
         <div className="flex flex-wrap items-center gap-2">
@@ -196,7 +243,13 @@ export function RuntimeEnvironmentsPane({
               <SelectValue />
             </SelectTrigger>
             <SelectContent>
-              <SelectItem value={LOCAL_RUNTIME_VALUE}>Local desktop</SelectItem>
+              {allowLocalRuntime ? (
+                <SelectItem value={LOCAL_RUNTIME_VALUE}>Local desktop</SelectItem>
+              ) : environments.length === 0 ? (
+                <SelectItem value={NO_RUNTIME_VALUE} disabled>
+                  No server connected
+                </SelectItem>
+              ) : null}
               {environments.map((environment) => (
                 <SelectItem key={environment.id} value={environment.id}>
                   {environment.name}
@@ -207,89 +260,156 @@ export function RuntimeEnvironmentsPane({
           <Button
             type="button"
             variant="outline"
-            size="sm"
-            className="gap-1.5"
+            size="icon-sm"
+            aria-label="Refresh servers"
+            title="Refresh servers"
             onClick={() => void loadEnvironments()}
             disabled={isLoading || isBusy}
           >
             {isLoading ? <Loader2 className="animate-spin" /> : <RefreshCw />}
-            Refresh
           </Button>
         </div>
       </div>
 
-      <div className="grid gap-2 sm:grid-cols-[minmax(0,180px)_minmax(0,1fr)_auto]">
-        <div className="space-y-1">
-          <Label htmlFor="runtime-server-name">Server name</Label>
-          <Input
-            id="runtime-server-name"
-            value={name}
-            onChange={(event) => setName(event.target.value)}
-            placeholder="Dev box"
-            className="h-8 text-xs"
-          />
+      <div className="space-y-3">
+        <div className="flex items-center justify-between gap-3">
+          <div className="text-sm font-medium">Saved Servers</div>
+          {addServerFormOpen ? null : (
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              className="gap-1.5"
+              onClick={() => setAddServerFormOpen(true)}
+              disabled={isBusy}
+            >
+              <Plus />
+              Add Server
+            </Button>
+          )}
         </div>
-        <div className="space-y-1">
-          <Label htmlFor="runtime-server-pairing-code">Pairing code</Label>
-          <Input
-            id="runtime-server-pairing-code"
-            aria-describedby="runtime-server-pairing-code-help"
-            value={pairingCode}
-            onChange={(event) => setPairingCode(event.target.value)}
-            placeholder="orca://pair#..."
-            className="h-8 min-w-0 font-mono text-xs"
-          />
-          <p id="runtime-server-pairing-code-help" className="text-xs text-muted-foreground">
-            Run <span className="font-mono">orca serve --pairing-address &lt;host&gt;</span> on the
-            server and paste the printed pairing URL.
-          </p>
+
+        {addServerFormOpen ? (
+          <form
+            className="space-y-3 rounded-lg border border-border/50 bg-muted/20 p-3"
+            onSubmit={(event) => {
+              event.preventDefault()
+              void addEnvironment()
+            }}
+          >
+            <div className="grid gap-3 sm:grid-cols-[minmax(0,180px)_minmax(0,1fr)]">
+              <div className="space-y-1">
+                <Label htmlFor="runtime-server-name">Server name</Label>
+                <Input
+                  id="runtime-server-name"
+                  value={name}
+                  onChange={(event) => setName(event.target.value)}
+                  placeholder="Dev box"
+                  className="h-8 text-xs"
+                  autoFocus
+                />
+              </div>
+              <div className="space-y-1">
+                <Label htmlFor="runtime-server-pairing-code">Pairing code</Label>
+                <Input
+                  id="runtime-server-pairing-code"
+                  aria-describedby="runtime-server-pairing-code-help"
+                  value={pairingCode}
+                  onChange={(event) => setPairingCode(event.target.value)}
+                  placeholder="orca://pair#..."
+                  className="h-8 min-w-0 font-mono text-xs"
+                />
+                <p id="runtime-server-pairing-code-help" className="text-xs text-muted-foreground">
+                  Run <span className="font-mono">orca serve --pairing-address &lt;host&gt;</span>{' '}
+                  on the server and paste the printed pairing URL.
+                </p>
+              </div>
+            </div>
+            <div className="flex justify-end gap-2">
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={closeAddServerForm}
+                disabled={isSaving}
+              >
+                Cancel
+              </Button>
+              <Button
+                type="submit"
+                size="sm"
+                disabled={isBusy || !name.trim() || !pairingCode.trim()}
+              >
+                {isSaving ? <Loader2 className="animate-spin" /> : <Plus />}
+                Add Server
+              </Button>
+            </div>
+          </form>
+        ) : null}
+
+        <div className="rounded-lg border border-border/50">
+          {environments.length === 0 ? (
+            <div className="px-3 py-4 text-sm text-muted-foreground">No saved servers.</div>
+          ) : (
+            <div className="divide-y divide-border/50">
+              {environments.map((environment) => (
+                <div
+                  key={environment.id}
+                  className="flex items-center justify-between gap-3 px-3 py-2"
+                >
+                  <div className="min-w-0">
+                    <div className="truncate text-sm font-medium">{environment.name}</div>
+                    <div className="truncate font-mono text-xs text-muted-foreground">
+                      {environment.endpoints[0]?.endpoint ?? 'No endpoint'}
+                    </div>
+                  </div>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-sm"
+                    onClick={() => {
+                      setRemoveError(null)
+                      setPendingRemove(environment)
+                    }}
+                    disabled={isBusy}
+                    aria-label={`Remove ${environment.name}`}
+                  >
+                    <Trash2 />
+                  </Button>
+                </div>
+              ))}
+            </div>
+          )}
         </div>
-        <Button
-          type="button"
-          size="sm"
-          className="mt-5 gap-1.5"
-          onClick={() => void addEnvironment()}
-          disabled={isBusy || !name.trim() || !pairingCode.trim()}
-        >
-          {isSaving ? <Loader2 className="animate-spin" /> : <Plus />}
-          Add
-        </Button>
       </div>
 
-      <div className="rounded-lg border border-border/50">
-        {environments.length === 0 ? (
-          <div className="px-3 py-4 text-sm text-muted-foreground">No saved servers.</div>
-        ) : (
-          <div className="divide-y divide-border/50">
-            {environments.map((environment) => (
-              <div
-                key={environment.id}
-                className="flex items-center justify-between gap-3 px-3 py-2"
-              >
-                <div className="min-w-0">
-                  <div className="truncate text-sm font-medium">{environment.name}</div>
-                  <div className="truncate font-mono text-xs text-muted-foreground">
-                    {environment.endpoints[0]?.endpoint ?? 'No endpoint'}
-                  </div>
-                </div>
-                <Button
-                  type="button"
-                  variant="ghost"
-                  size="icon-sm"
-                  onClick={() => {
-                    setRemoveError(null)
-                    setPendingRemove(environment)
-                  }}
-                  disabled={isBusy}
-                  aria-label={`Remove ${environment.name}`}
-                >
-                  <Trash2 />
-                </Button>
-              </div>
-            ))}
+      {canGeneratePairingUrl ? (
+        <div className="overflow-hidden rounded-lg border border-border/50">
+          <div className="flex flex-wrap items-center justify-between gap-3 px-3 py-2.5">
+            <div className="min-w-0 space-y-0.5">
+              <div className="text-sm font-medium">Share this desktop</div>
+              <p className="text-xs text-muted-foreground">
+                Generate a pairing URL for the web client or another Orca client.
+              </p>
+            </div>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              className="gap-1.5"
+              onClick={() => setShareServerFormOpen((open) => !open)}
+            >
+              <Share2 />
+              {shareServerFormOpen ? 'Hide' : 'Generate Link'}
+            </Button>
           </div>
-        )}
-      </div>
+          {shareServerFormOpen ? (
+            <div className="border-t border-border/40 px-3 py-3">
+              <RuntimePairingUrlGenerator framed={false} showHeader={false} />
+            </div>
+          ) : null}
+        </div>
+      ) : null}
 
       <Dialog
         open={pendingSwitchValue !== null}
@@ -363,7 +483,9 @@ export function RuntimeEnvironmentsPane({
             <DialogTitle className="text-sm">Remove Server</DialogTitle>
             <DialogDescription>
               {removingActiveServer
-                ? 'Removing the active server first switches Orca back to Local desktop and closes remote terminals and browser tabs for that server.'
+                ? allowLocalRuntime
+                  ? 'Removing the active server first switches Orca back to Local desktop and closes remote terminals and browser tabs for that server.'
+                  : 'Removing the active server disconnects this browser and closes remote terminals and browser tabs for that server.'
                 : 'This removes the saved server from Orca. It does not change the active server.'}
             </DialogDescription>
           </DialogHeader>
diff --git a/src/renderer/src/components/settings/RuntimePairingUrlGenerator.tsx b/src/renderer/src/components/settings/RuntimePairingUrlGenerator.tsx
new file mode 100644
index 00000000000..5b96398a938
--- /dev/null
+++ b/src/renderer/src/components/settings/RuntimePairingUrlGenerator.tsx
@@ -0,0 +1,239 @@
+import { Check, Copy, Loader2, RefreshCw } from 'lucide-react'
+import { useEffect, useState } from 'react'
+import { toast } from 'sonner'
+import { Button } from '../ui/button'
+import { Input } from '../ui/input'
+import { Label } from '../ui/label'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+
+const LOOPBACK_ADDRESS = '127.0.0.1'
+
+// Why: runtime pairing tokens stay valid in the main-process registry; keep the
+// last displayed URL across settings collapse/navigation without less-protected storage.
+const runtimePairingUrlCache: {
+  selectedAddress: string
+  customAddress: string
+  runtimePairingUrl: string | null
+  webClientUrl: string | null
+} = {
+  selectedAddress: LOOPBACK_ADDRESS,
+  customAddress: '',
+  runtimePairingUrl: null,
+  webClientUrl: null
+}
+
+function GeneratedUrlRow({
+  label,
+  value,
+  copied,
+  onCopy
+}: {
+  label: string
+  value: string
+  copied: boolean
+  onCopy: () => void
+}): React.JSX.Element {
+  return (
+    <div className="space-y-1">
+      <Label>{label}</Label>
+      <div className="flex min-w-0 items-center gap-2 rounded-md border border-border/60 bg-background/70 px-2 py-1.5">
+        <code className="min-w-0 flex-1 overflow-x-auto whitespace-nowrap text-[11px] text-muted-foreground">
+          {value}
+        </code>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-xs"
+          onClick={onCopy}
+          aria-label={`Copy ${label}`}
+        >
+          {copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+type RuntimePairingUrlGeneratorProps = {
+  framed?: boolean
+  showHeader?: boolean
+}
+
+export function RuntimePairingUrlGenerator({
+  framed = true,
+  showHeader = true
+}: RuntimePairingUrlGeneratorProps): React.JSX.Element {
+  const [networkInterfaces, setNetworkInterfaces] = useState<{ name: string; address: string }[]>(
+    []
+  )
+  const [selectedAddress, setSelectedAddress] = useState(runtimePairingUrlCache.selectedAddress)
+  const [customAddress, setCustomAddress] = useState(runtimePairingUrlCache.customAddress)
+  const [runtimePairingUrl, setRuntimePairingUrl] = useState<string | null>(
+    runtimePairingUrlCache.runtimePairingUrl
+  )
+  const [webClientUrl, setWebClientUrl] = useState<string | null>(
+    runtimePairingUrlCache.webClientUrl
+  )
+  const [copiedTarget, setCopiedTarget] = useState<'web' | 'pairing' | null>(null)
+  const [isGeneratingPairing, setIsGeneratingPairing] = useState(false)
+
+  useEffect(() => {
+    let stale = false
+
+    const loadNetworkInterfaces = async (): Promise<void> => {
+      try {
+        const result = await window.api.mobile.listNetworkInterfaces()
+        if (!stale) {
+          setNetworkInterfaces(result.interfaces)
+        }
+      } catch {
+        // Keep the loopback option available even if interface enumeration fails.
+      }
+    }
+
+    void loadNetworkInterfaces()
+
+    return () => {
+      stale = true
+    }
+  }, [])
+
+  const generateRuntimePairingUrl = async (): Promise<void> => {
+    setIsGeneratingPairing(true)
+    try {
+      const advertiseAddress = customAddress.trim() || selectedAddress
+      const result = await window.api.mobile.getRuntimePairingUrl({
+        address: advertiseAddress,
+        rotate: true
+      })
+      if (!result.available) {
+        runtimePairingUrlCache.runtimePairingUrl = null
+        runtimePairingUrlCache.webClientUrl = null
+        setRuntimePairingUrl(null)
+        setWebClientUrl(null)
+        toast.error('Runtime pairing is unavailable.')
+        return
+      }
+      runtimePairingUrlCache.runtimePairingUrl = result.pairingUrl
+      runtimePairingUrlCache.webClientUrl = result.webClientUrl
+      setRuntimePairingUrl(result.pairingUrl)
+      setWebClientUrl(result.webClientUrl)
+      toast.success(result.webClientUrl ? 'Generated web client URL.' : 'Generated pairing URL.')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Failed to generate pairing URL.')
+    } finally {
+      setIsGeneratingPairing(false)
+    }
+  }
+
+  const copyGeneratedUrl = async (target: 'web' | 'pairing', value: string): Promise<void> => {
+    try {
+      await window.api.ui.writeClipboardText(value)
+      setCopiedTarget(target)
+      toast.success(target === 'web' ? 'Copied web client URL.' : 'Copied pairing URL.')
+      window.setTimeout(() => {
+        setCopiedTarget((current) => (current === target ? null : current))
+      }, 1400)
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Failed to copy URL.')
+    }
+  }
+
+  const containerClassName = framed
+    ? 'space-y-3 rounded-lg border border-border/50 bg-muted/25 p-3'
+    : 'space-y-4'
+
+  const updateSelectedAddress = (address: string): void => {
+    runtimePairingUrlCache.selectedAddress = address
+    setSelectedAddress(address)
+  }
+
+  const updateCustomAddress = (address: string): void => {
+    runtimePairingUrlCache.customAddress = address
+    setCustomAddress(address)
+  }
+
+  return (
+    <div className={containerClassName}>
+      {showHeader ? (
+        <div className="space-y-1">
+          <Label id="runtime-share-server-label">Share this desktop</Label>
+          <p className="text-xs text-muted-foreground">
+            Generate a runtime pairing URL for the web client or another Orca client.
+          </p>
+        </div>
+      ) : null}
+      <div className="space-y-3">
+        <div className="grid gap-3 sm:grid-cols-[minmax(0,220px)_minmax(0,1fr)]">
+          <div className="space-y-1">
+            <Label id="runtime-pairing-address-label" htmlFor="runtime-pairing-address">
+              Advertise address
+            </Label>
+            <Select value={selectedAddress} onValueChange={updateSelectedAddress}>
+              <SelectTrigger
+                id="runtime-pairing-address"
+                size="sm"
+                className="min-w-[220px]"
+                aria-labelledby="runtime-pairing-address-label"
+              >
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value={LOOPBACK_ADDRESS}>This computer ({LOOPBACK_ADDRESS})</SelectItem>
+                {networkInterfaces.map((networkInterface, index) => (
+                  <SelectItem
+                    key={`${networkInterface.name}:${networkInterface.address}:${index}`}
+                    value={networkInterface.address}
+                  >
+                    {networkInterface.name} ({networkInterface.address})
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="min-w-0 space-y-1">
+            <Label htmlFor="runtime-pairing-custom-address">Custom address</Label>
+            <Input
+              id="runtime-pairing-custom-address"
+              value={customAddress}
+              onChange={(event) => updateCustomAddress(event.target.value)}
+              placeholder="host, host:port, or wss://host/path"
+              className="h-8 font-mono text-xs"
+            />
+          </div>
+        </div>
+        <div className="flex justify-end">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="gap-1.5"
+            onClick={() => void generateRuntimePairingUrl()}
+            disabled={isGeneratingPairing}
+          >
+            {isGeneratingPairing ? <Loader2 className="animate-spin" /> : <RefreshCw />}
+            Generate
+          </Button>
+        </div>
+      </div>
+
+      {webClientUrl ? (
+        <GeneratedUrlRow
+          label="Web client URL"
+          value={webClientUrl}
+          copied={copiedTarget === 'web'}
+          onCopy={() => void copyGeneratedUrl('web', webClientUrl)}
+        />
+      ) : null}
+
+      {runtimePairingUrl ? (
+        <GeneratedUrlRow
+          label="Pairing URL"
+          value={runtimePairingUrl}
+          copied={copiedTarget === 'pairing'}
+          onCopy={() => void copyGeneratedUrl('pairing', runtimePairingUrl)}
+        />
+      ) : null}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 1af8e8a4979..53cdf9f05ff 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -62,10 +62,11 @@ import {
 } from './DeveloperPermissionsPane'
 import { ComputerUsePane, COMPUTER_USE_PANE_SEARCH_ENTRIES } from './ComputerUsePane'
 import { MobileSettingsPane, MOBILE_SETTINGS_PANE_SEARCH_ENTRIES } from './MobileSettingsPane'
+import { RuntimeEnvironmentsPane } from './RuntimeEnvironmentsPane'
 import {
-  RuntimeEnvironmentsPane,
-  RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
-} from './RuntimeEnvironmentsPane'
+  RUNTIME_ENVIRONMENTS_SEARCH_ENTRY,
+  WEB_RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
+} from './runtime-environments-search'
 import { PrivacyPane } from './PrivacyPane'
 import { PRIVACY_PANE_SEARCH_ENTRIES } from './privacy-search'
 import { SettingsSidebar } from './SettingsSidebar'
@@ -179,6 +180,13 @@ function isEditableTarget(target: EventTarget | null): boolean {
   return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT'
 }
 
+function isWebClientLocation(): boolean {
+  return (
+    Boolean((window as unknown as { __ORCA_WEB_CLIENT__?: boolean }).__ORCA_WEB_CLIENT__) ||
+    window.location.pathname.endsWith('/web-index.html')
+  )
+}
+
 function Settings(): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
   const updateSettings = useAppStore((s) => s.updateSettings)
@@ -199,6 +207,8 @@ function Settings(): React.JSX.Element {
   const systemPrefersDark = useSystemPrefersDark()
   const isWindows = isWindowsUserAgent()
   const isMac = isMacUserAgent()
+  const isWebClient = isWebClientLocation()
+  const showDesktopOnlySettings = !isWebClient
   const showComputerUsePreviewTooltip = !isMac
   const computerUsePlatform = computerUsePlatformLabel({ isWindows, isMac })
   // Why: the Terminal settings section shares one search index with the
@@ -399,6 +409,9 @@ function Settings(): React.JSX.Element {
   }, [])
 
   const displayedGitUsername = repos[0]?.gitUsername ?? ''
+  const runtimeEnvironmentsSearchEntry = isWebClient
+    ? WEB_RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
+    : RUNTIME_ENVIRONMENTS_SEARCH_ENTRY
 
   const navSections = useMemo<SettingsNavSection[]>(
     () => [
@@ -447,20 +460,24 @@ function Settings(): React.JSX.Element {
         icon: SquareTerminal,
         searchEntries: terminalPaneSearchEntries
       },
-      {
-        id: 'browser',
-        title: 'Browser',
-        description: 'Home page, link routing, and session cookies.',
-        icon: Globe,
-        searchEntries: BROWSER_PANE_SEARCH_ENTRIES
-      },
-      {
-        id: 'notifications',
-        title: 'Notifications',
-        description: 'Native desktop notifications for agent and terminal events.',
-        icon: Bell,
-        searchEntries: NOTIFICATIONS_PANE_SEARCH_ENTRIES
-      },
+      ...(showDesktopOnlySettings
+        ? [
+            {
+              id: 'browser' as const,
+              title: 'Browser',
+              description: 'Home page, link routing, and session cookies.',
+              icon: Globe,
+              searchEntries: BROWSER_PANE_SEARCH_ENTRIES
+            },
+            {
+              id: 'notifications' as const,
+              title: 'Notifications',
+              description: 'Native desktop notifications for agent and terminal events.',
+              icon: Bell,
+              searchEntries: NOTIFICATIONS_PANE_SEARCH_ENTRIES
+            }
+          ]
+        : []),
       {
         id: 'orchestration',
         title: 'Orchestration',
@@ -471,36 +488,42 @@ function Settings(): React.JSX.Element {
       {
         id: 'servers',
         title: 'Servers',
-        description: 'Run this client locally or through a remote Orca server.',
+        description: isWebClient
+          ? 'Connect this browser to a saved Orca server.'
+          : 'Run this client locally or through a remote Orca server.',
         icon: Server,
-        searchEntries: [RUNTIME_ENVIRONMENTS_SEARCH_ENTRY],
+        searchEntries: [runtimeEnvironmentsSearchEntry],
         badge: 'Beta'
       },
-      {
-        id: 'mobile',
-        title: 'Mobile',
-        description: 'Control terminals and agents from your phone.',
-        icon: Smartphone,
-        searchEntries: MOBILE_SETTINGS_PANE_SEARCH_ENTRIES,
-        badge: 'Beta'
-      },
-      {
-        id: 'computer-use',
-        title: 'Computer Use',
-        description: 'Enable agents to control any app on your computer.',
-        icon: MousePointerClick,
-        searchEntries: COMPUTER_USE_PANE_SEARCH_ENTRIES,
-        badge: 'Beta'
-      },
-      {
-        id: 'voice',
-        title: 'Voice',
-        description: 'Local speech-to-text dictation with on-device models.',
-        icon: Mic,
-        searchEntries: VOICE_PANE_SEARCH_ENTRIES,
-        badge: 'Beta'
-      },
-      ...(isMac
+      ...(showDesktopOnlySettings
+        ? [
+            {
+              id: 'mobile' as const,
+              title: 'Mobile',
+              description: 'Control terminals and agents from your phone.',
+              icon: Smartphone,
+              searchEntries: MOBILE_SETTINGS_PANE_SEARCH_ENTRIES,
+              badge: 'Beta'
+            },
+            {
+              id: 'computer-use' as const,
+              title: 'Computer Use',
+              description: 'Enable agents to control any app on your computer.',
+              icon: MousePointerClick,
+              searchEntries: COMPUTER_USE_PANE_SEARCH_ENTRIES,
+              badge: 'Beta'
+            },
+            {
+              id: 'voice' as const,
+              title: 'Voice',
+              description: 'Local speech-to-text dictation with on-device models.',
+              icon: Mic,
+              searchEntries: VOICE_PANE_SEARCH_ENTRIES,
+              badge: 'Beta'
+            }
+          ]
+        : []),
+      ...(showDesktopOnlySettings && isMac
         ? [
             {
               id: 'developer-permissions' as const,
@@ -539,13 +562,17 @@ function Settings(): React.JSX.Element {
         icon: BarChart3,
         searchEntries: STATS_PANE_SEARCH_ENTRIES
       },
-      {
-        id: 'ssh',
-        title: 'SSH',
-        description: 'Remote SSH connections.',
-        icon: Cable,
-        searchEntries: SSH_PANE_SEARCH_ENTRIES
-      },
+      ...(showDesktopOnlySettings
+        ? [
+            {
+              id: 'ssh' as const,
+              title: 'SSH',
+              description: 'Remote SSH connections.',
+              icon: Cable,
+              searchEntries: SSH_PANE_SEARCH_ENTRIES
+            }
+          ]
+        : []),
       {
         id: 'experimental',
         title: 'Experimental',
@@ -561,7 +588,14 @@ function Settings(): React.JSX.Element {
         searchEntries: getRepositoryPaneSearchEntries(repo)
       }))
     ],
-    [isMac, repos, terminalPaneSearchEntries]
+    [
+      isMac,
+      isWebClient,
+      repos,
+      runtimeEnvironmentsSearchEntry,
+      showDesktopOnlySettings,
+      terminalPaneSearchEntries
+    ]
   )
 
   const visibleNavSections = useMemo(
@@ -824,23 +858,27 @@ function Settings(): React.JSX.Element {
                   />
                 </SettingsSection>
 
-                <SettingsSection
-                  id="browser"
-                  title="Browser"
-                  description="Home page, link routing, and session cookies."
-                  searchEntries={BROWSER_PANE_SEARCH_ENTRIES}
-                >
-                  <BrowserPane settings={settings} updateSettings={updateSettings} />
-                </SettingsSection>
+                {showDesktopOnlySettings ? (
+                  <>
+                    <SettingsSection
+                      id="browser"
+                      title="Browser"
+                      description="Home page, link routing, and session cookies."
+                      searchEntries={BROWSER_PANE_SEARCH_ENTRIES}
+                    >
+                      <BrowserPane settings={settings} updateSettings={updateSettings} />
+                    </SettingsSection>
 
-                <SettingsSection
-                  id="notifications"
-                  title="Notifications"
-                  description="Native desktop notifications for agent activity and terminal events."
-                  searchEntries={NOTIFICATIONS_PANE_SEARCH_ENTRIES}
-                >
-                  <NotificationsPane settings={settings} updateSettings={updateSettings} />
-                </SettingsSection>
+                    <SettingsSection
+                      id="notifications"
+                      title="Notifications"
+                      description="Native desktop notifications for agent activity and terminal events."
+                      searchEntries={NOTIFICATIONS_PANE_SEARCH_ENTRIES}
+                    >
+                      <NotificationsPane settings={settings} updateSettings={updateSettings} />
+                    </SettingsSection>
+                  </>
+                ) : null}
 
                 <SettingsSection
                   id="orchestration"
@@ -855,69 +893,79 @@ function Settings(): React.JSX.Element {
                   id="servers"
                   title="Servers"
                   badge="Beta"
-                  description="Run this desktop client locally or through a remote Orca server."
-                  searchEntries={[RUNTIME_ENVIRONMENTS_SEARCH_ENTRY]}
+                  description={
+                    isWebClient
+                      ? 'Connect this browser to a saved Orca server.'
+                      : 'Run this desktop client locally or through a remote Orca server.'
+                  }
+                  searchEntries={[runtimeEnvironmentsSearchEntry]}
                 >
                   <RuntimeEnvironmentsPane
                     settings={settings}
                     switchRuntimeEnvironment={switchRuntimeEnvironment}
+                    canGeneratePairingUrl={!isWebClient}
+                    allowLocalRuntime={!isWebClient}
                   />
                 </SettingsSection>
 
-                <SettingsSection
-                  id="mobile"
-                  title="Mobile"
-                  badge="Beta"
-                  description="Control terminals and agents from your phone."
-                  searchEntries={MOBILE_SETTINGS_PANE_SEARCH_ENTRIES}
-                >
-                  <MobileSettingsPane settings={settings} updateSettings={updateSettings} />
-                </SettingsSection>
+                {showDesktopOnlySettings ? (
+                  <>
+                    <SettingsSection
+                      id="mobile"
+                      title="Mobile"
+                      badge="Beta"
+                      description="Control terminals and agents from your phone."
+                      searchEntries={MOBILE_SETTINGS_PANE_SEARCH_ENTRIES}
+                    >
+                      <MobileSettingsPane settings={settings} updateSettings={updateSettings} />
+                    </SettingsSection>
 
-                <SettingsSection
-                  id="computer-use"
-                  title="Computer Use"
-                  badge="Beta"
-                  badgeAccessory={
-                    showComputerUsePreviewTooltip ? (
-                      <TooltipProvider delayDuration={250}>
-                        <Tooltip>
-                          <TooltipTrigger asChild>
-                            <button
-                              type="button"
-                              className="text-muted-foreground transition-colors hover:text-foreground"
-                              aria-label={`${computerUsePlatform} Computer Use preview details`}
-                            >
-                              <Info className="size-3.5" />
-                            </button>
-                          </TooltipTrigger>
-                          <TooltipContent side="top" sideOffset={6} className="max-w-72">
-                            <span>
-                              {computerUsePlatform} Computer Use is an early preview. Some apps and
-                              desktop environments may behave inconsistently.
-                            </span>
-                          </TooltipContent>
-                        </Tooltip>
-                      </TooltipProvider>
-                    ) : null
-                  }
-                  description="Enable agents to control any app on your computer."
-                  searchEntries={COMPUTER_USE_PANE_SEARCH_ENTRIES}
-                >
-                  <ComputerUsePane />
-                </SettingsSection>
+                    <SettingsSection
+                      id="computer-use"
+                      title="Computer Use"
+                      badge="Beta"
+                      badgeAccessory={
+                        showComputerUsePreviewTooltip ? (
+                          <TooltipProvider delayDuration={250}>
+                            <Tooltip>
+                              <TooltipTrigger asChild>
+                                <button
+                                  type="button"
+                                  className="text-muted-foreground transition-colors hover:text-foreground"
+                                  aria-label={`${computerUsePlatform} Computer Use preview details`}
+                                >
+                                  <Info className="size-3.5" />
+                                </button>
+                              </TooltipTrigger>
+                              <TooltipContent side="top" sideOffset={6} className="max-w-72">
+                                <span>
+                                  {computerUsePlatform} Computer Use is an early preview. Some apps
+                                  and desktop environments may behave inconsistently.
+                                </span>
+                              </TooltipContent>
+                            </Tooltip>
+                          </TooltipProvider>
+                        ) : null
+                      }
+                      description="Enable agents to control any app on your computer."
+                      searchEntries={COMPUTER_USE_PANE_SEARCH_ENTRIES}
+                    >
+                      <ComputerUsePane />
+                    </SettingsSection>
 
-                <SettingsSection
-                  id="voice"
-                  title="Voice"
-                  badge="Beta"
-                  description="Local speech-to-text dictation with on-device models."
-                  searchEntries={VOICE_PANE_SEARCH_ENTRIES}
-                >
-                  <VoicePane settings={settings} updateSettings={updateSettings} />
-                </SettingsSection>
+                    <SettingsSection
+                      id="voice"
+                      title="Voice"
+                      badge="Beta"
+                      description="Local speech-to-text dictation with on-device models."
+                      searchEntries={VOICE_PANE_SEARCH_ENTRIES}
+                    >
+                      <VoicePane settings={settings} updateSettings={updateSettings} />
+                    </SettingsSection>
+                  </>
+                ) : null}
 
-                {isMac ? (
+                {showDesktopOnlySettings && isMac ? (
                   <SettingsSection
                     id="developer-permissions"
                     title="Permissions"
@@ -955,14 +1003,16 @@ function Settings(): React.JSX.Element {
                   <StatsPane />
                 </SettingsSection>
 
-                <SettingsSection
-                  id="ssh"
-                  title="SSH"
-                  description="Manage remote SSH connections. Connect to remote servers to browse files, run terminals, and use git."
-                  searchEntries={SSH_PANE_SEARCH_ENTRIES}
-                >
-                  <SshPane />
-                </SettingsSection>
+                {showDesktopOnlySettings ? (
+                  <SettingsSection
+                    id="ssh"
+                    title="SSH"
+                    description="Manage remote SSH connections. Connect to remote servers to browse files, run terminals, and use git."
+                    searchEntries={SSH_PANE_SEARCH_ENTRIES}
+                  >
+                    <SshPane />
+                  </SettingsSection>
+                ) : null}
 
                 <SettingsSection
                   id="experimental"
diff --git a/src/renderer/src/components/settings/TerminalQuickCommandsSection.tsx b/src/renderer/src/components/settings/TerminalQuickCommandsSection.tsx
index 8136e90a274..a8e90a5c316 100644
--- a/src/renderer/src/components/settings/TerminalQuickCommandsSection.tsx
+++ b/src/renderer/src/components/settings/TerminalQuickCommandsSection.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import { Pencil, Plus, Trash2 } from 'lucide-react'
 import type { TerminalQuickCommand } from '../../../../shared/types'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 import { Button } from '../ui/button'
 import {
   Dialog,
@@ -30,12 +31,8 @@ type EditorState =
   | null
 
 function createQuickCommand(): TerminalQuickCommand {
-  const randomId =
-    typeof crypto !== 'undefined' && 'randomUUID' in crypto
-      ? crypto.randomUUID()
-      : `${Date.now()}-${Math.random().toString(16).slice(2)}`
   return {
-    id: `quick-command-${randomId}`,
+    id: `quick-command-${createBrowserUuid()}`,
     label: '',
     command: '',
     appendEnter: true
diff --git a/src/renderer/src/components/settings/runtime-environments-search.ts b/src/renderer/src/components/settings/runtime-environments-search.ts
new file mode 100644
index 00000000000..5da0eea6214
--- /dev/null
+++ b/src/renderer/src/components/settings/runtime-environments-search.ts
@@ -0,0 +1,25 @@
+import type { SettingsSearchEntry } from './settings-search'
+
+export const RUNTIME_ENVIRONMENTS_SEARCH_ENTRY: SettingsSearchEntry = {
+  title: 'Active Server',
+  description: 'Choose local desktop, add a saved remote Orca server, or generate a pairing URL.',
+  keywords: [
+    'runtime',
+    'environment',
+    'server',
+    'client',
+    'remote',
+    'pairing',
+    'pairing url',
+    'web client',
+    'cloud',
+    'vm',
+    'dev box'
+  ]
+}
+
+export const WEB_RUNTIME_ENVIRONMENTS_SEARCH_ENTRY: SettingsSearchEntry = {
+  title: 'Active Server',
+  description: 'Connect this browser to a saved Orca server.',
+  keywords: ['runtime', 'environment', 'server', 'client', 'remote', 'pairing code', 'cloud', 'vm']
+}
diff --git a/src/renderer/src/lib/browser-uuid.test.ts b/src/renderer/src/lib/browser-uuid.test.ts
new file mode 100644
index 00000000000..8ad0616200a
--- /dev/null
+++ b/src/renderer/src/lib/browser-uuid.test.ts
@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createBrowserUuid } from './browser-uuid'
+
+describe('createBrowserUuid', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('uses native randomUUID when it is available', () => {
+    vi.stubGlobal('crypto', {
+      randomUUID: () => 'native-id'
+    })
+
+    expect(createBrowserUuid()).toBe('native-id')
+  })
+
+  it('falls back to getRandomValues when randomUUID is unavailable', () => {
+    vi.stubGlobal('crypto', {
+      getRandomValues: (bytes: Uint8Array) => {
+        for (let index = 0; index < bytes.length; index += 1) {
+          bytes[index] = index
+        }
+        return bytes
+      }
+    })
+
+    expect(createBrowserUuid()).toBe('00010203-0405-4607-8809-0a0b0c0d0e0f')
+  })
+})
diff --git a/src/renderer/src/lib/browser-uuid.ts b/src/renderer/src/lib/browser-uuid.ts
new file mode 100644
index 00000000000..177d05f7ddb
--- /dev/null
+++ b/src/renderer/src/lib/browser-uuid.ts
@@ -0,0 +1,28 @@
+export function createBrowserUuid(): string {
+  const cryptoApi = globalThis.crypto
+  if (typeof cryptoApi?.randomUUID === 'function') {
+    return cryptoApi.randomUUID()
+  }
+
+  const bytes = new Uint8Array(16)
+  if (typeof cryptoApi?.getRandomValues === 'function') {
+    cryptoApi.getRandomValues(bytes)
+  } else {
+    // Why: LAN web clients can run in non-secure browser contexts where
+    // randomUUID is hidden. These are local UI IDs, not auth credentials.
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256)
+    }
+  }
+
+  bytes[6] = (bytes[6] & 0x0f) | 0x40
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+  return bytesToUuid(bytes)
+}
+
+function bytesToUuid(bytes: Uint8Array): string {
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0'))
+  return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex
+    .slice(6, 8)
+    .join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10, 16).join('')}`
+}
diff --git a/src/renderer/src/lib/open-project-notes-tab.ts b/src/renderer/src/lib/open-project-notes-tab.ts
index cda85c7e695..24c9fa6ca92 100644
--- a/src/renderer/src/lib/open-project-notes-tab.ts
+++ b/src/renderer/src/lib/open-project-notes-tab.ts
@@ -1,12 +1,13 @@
 import { useAppStore } from '@/store'
 import { NOTES_ACTIVE_CHANGED_EVENT } from '@/lib/notes-events'
 import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 
 export function getProjectNotesEntityId(projectId: string, noteId?: string): string {
   if (noteId) {
     return `notes:${projectId}:note:${noteId}`
   }
-  return `notes:${projectId}:new:${globalThis.crypto.randomUUID()}`
+  return `notes:${projectId}:new:${createBrowserUuid()}`
 }
 
 export function getProjectNoteIdFromEntityId(entityId: string): string | null {
diff --git a/src/renderer/src/runtime/sync-runtime-graph.ts b/src/renderer/src/runtime/sync-runtime-graph.ts
index 7d8de532d0e..557dd1052bc 100644
--- a/src/renderer/src/runtime/sync-runtime-graph.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph.ts
@@ -6,6 +6,7 @@ import {
 } from '@/components/terminal-pane/layout-serialization'
 import { warnTerminalLifecycleAnomaly } from '@/components/terminal-pane/terminal-lifecycle-diagnostics'
 import type { PaneManager } from '@/lib/pane-manager/pane-manager'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 import type { AppState } from '@/store/types'
 import type {
   RuntimeMobileSessionFileTab,
@@ -46,10 +47,7 @@ let cachedOpenFileIndexesSource: AppState['openFiles'] | null = null
 let cachedOpenFileIndexes: OpenFileIndexes | null = null
 let cachedEditorDraftsSource: AppState['editorDrafts'] | null = null
 let cachedEditorDraftVersionByFileId: Map<string, string> | null = null
-const mobileSessionPublicationEpoch =
-  typeof crypto !== 'undefined' && 'randomUUID' in crypto
-    ? crypto.randomUUID()
-    : `renderer:${Date.now().toString(36)}`
+const mobileSessionPublicationEpoch = `renderer:${createBrowserUuid()}`
 
 export function setRuntimeGraphStoreStateGetter(getter: (() => AppState) | null): void {
   getStoreState = getter
diff --git a/src/renderer/src/store/slices/browser.ts b/src/renderer/src/store/slices/browser.ts
index e326b761568..ab1fb6510f4 100644
--- a/src/renderer/src/store/slices/browser.ts
+++ b/src/renderer/src/store/slices/browser.ts
@@ -34,6 +34,7 @@ import type {
   BrowserProfileImportFromBrowserResult,
   BrowserProfileListResult
 } from '../../../../shared/runtime-types'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 
 type CreateBrowserTabOptions = {
   activate?: boolean
@@ -221,7 +222,7 @@ function buildBrowserPage(
 ): BrowserPage {
   const normalizedUrl = normalizeUrl(url)
   return {
-    id: globalThis.crypto.randomUUID(),
+    id: createBrowserUuid(),
     workspaceId,
     worktreeId,
     url: normalizedUrl,
@@ -355,7 +356,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   },
 
   createBrowserTab: (worktreeId, url, options) => {
-    const workspaceId = globalThis.crypto.randomUUID()
+    const workspaceId = createBrowserUuid()
     const page = buildBrowserPage(workspaceId, worktreeId, url, options?.title)
     // Why: when no explicit profile is passed, inherit the user's chosen default
     // profile. This lets users set a preferred profile in Settings that all new
@@ -1243,7 +1244,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         for (const tab of tabs) {
           const persistedPages = persistedPagesByWorkspace[tab.id] ?? [
             {
-              id: globalThis.crypto.randomUUID(),
+              id: createBrowserUuid(),
               workspaceId: tab.id,
               worktreeId,
               url: normalizeUrl(tab.url),
diff --git a/src/renderer/src/store/slices/diffComments.ts b/src/renderer/src/store/slices/diffComments.ts
index 7b776d2aa23..0a57741c8f4 100644
--- a/src/renderer/src/store/slices/diffComments.ts
+++ b/src/renderer/src/store/slices/diffComments.ts
@@ -3,6 +3,7 @@ import type { AppState } from '../types'
 import type { DiffComment, Worktree } from '../../../../shared/types'
 import { findWorktreeById, getRepoIdFromWorktreeId } from './worktree-helpers'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '../../runtime/runtime-rpc-client'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 
 export type DiffCommentsSlice = {
   getDiffComments: (worktreeId: string | null | undefined) => DiffComment[]
@@ -12,7 +13,7 @@ export type DiffCommentsSlice = {
 }
 
 function generateId(): string {
-  return globalThis.crypto.randomUUID()
+  return createBrowserUuid()
 }
 
 // Why: return a stable reference when no comments exist so selectors don't
diff --git a/src/renderer/src/store/slices/tab-group-state.ts b/src/renderer/src/store/slices/tab-group-state.ts
index 5bb4c730b16..b5d634cee61 100644
--- a/src/renderer/src/store/slices/tab-group-state.ts
+++ b/src/renderer/src/store/slices/tab-group-state.ts
@@ -1,4 +1,5 @@
 import type { Tab, TabContentType, TabGroup, WorkspaceSessionState } from '../../../../shared/types'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 
 export function findTabAndWorktree(
   tabsByWorktree: Record<string, Tab[]>,
@@ -69,7 +70,7 @@ export function ensureGroup(
   if (existing) {
     return { group: existing, groupsByWorktree, activeGroupIdByWorktree }
   }
-  const groupId = globalThis.crypto.randomUUID()
+  const groupId = createBrowserUuid()
   const group: TabGroup = { id: groupId, worktreeId, activeTabId: null, tabOrder: [] }
   return {
     group,
diff --git a/src/renderer/src/store/slices/tabs-hydration.ts b/src/renderer/src/store/slices/tabs-hydration.ts
index 886fecc0ba8..e01b50a3282 100644
--- a/src/renderer/src/store/slices/tabs-hydration.ts
+++ b/src/renderer/src/store/slices/tabs-hydration.ts
@@ -4,6 +4,7 @@ import type {
   TabGroupLayoutNode,
   WorkspaceSessionState
 } from '../../../../shared/types'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 import {
   dedupeTabOrder,
   getPersistedEditFileIdsByWorktree,
@@ -164,7 +165,7 @@ function hydrateLegacyFormat(
       continue
     }
 
-    const groupId = globalThis.crypto.randomUUID()
+    const groupId = createBrowserUuid()
     const tabs: Tab[] = []
     const tabOrder: string[] = []
 
diff --git a/src/renderer/src/store/slices/tabs.ts b/src/renderer/src/store/slices/tabs.ts
index 5882d970ced..42859580399 100644
--- a/src/renderer/src/store/slices/tabs.ts
+++ b/src/renderer/src/store/slices/tabs.ts
@@ -27,6 +27,7 @@ import {
 } from './tab-group-state'
 import { buildHydratedTabState } from './tabs-hydration'
 import { buildOrphanTerminalCleanupPatch, getOrphanTerminalIds } from './terminal-orphan-helpers'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 
 export type TabSplitDirection = 'left' | 'right' | 'up' | 'down'
 
@@ -402,7 +403,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
   layoutByWorktree: {},
 
   createUnifiedTab: (worktreeId, contentType, init) => {
-    const id = init?.id ?? globalThis.crypto.randomUUID()
+    const id = init?.id ?? createBrowserUuid()
     let created!: Tab
     set((state) => {
       const { group, groupsByWorktree, activeGroupIdByWorktree } = ensureGroup(
@@ -812,7 +813,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       return get().activeGroupIdByWorktree[worktreeId] ?? existingGroups[0].id
     }
 
-    const groupId = globalThis.crypto.randomUUID()
+    const groupId = createBrowserUuid()
     set((state) => ({
       // Why: a freshly selected worktree can legitimately have zero tabs, but
       // split-group affordances still need a canonical root group so new tabs
@@ -943,7 +944,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
   },
 
   createEmptySplitGroup: (worktreeId, sourceGroupId, direction) => {
-    const newGroupId = globalThis.crypto.randomUUID()
+    const newGroupId = createBrowserUuid()
     const newGroup: TabGroup = {
       id: newGroupId,
       worktreeId,
@@ -1091,7 +1092,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       let resolvedTargetGroupId = target.groupId
 
       if (target.splitDirection) {
-        const newGroupId = globalThis.crypto.randomUUID()
+        const newGroupId = createBrowserUuid()
         const newGroup: TabGroup = {
           id: newGroupId,
           worktreeId,
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index e526fd41885..949eb2049ed 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -29,6 +29,7 @@ import {
 } from '@/components/terminal-pane/pty-transport'
 import { shutdownBufferCaptures } from '@/components/terminal-pane/shutdown-buffer-captures'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import { createBrowserUuid } from '@/lib/browser-uuid'
 
 function getNextTerminalOrdinal(tabs: TerminalTab[]): number {
   const usedOrdinals = new Set<number>()
@@ -377,7 +378,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           `[createTab] tabId hint ${hintedId} already exists; minting a fresh id (hook attribution will degrade for this terminal)`
         )
       }
-      const id = hintedId !== undefined && !idCollides ? hintedId : globalThis.crypto.randomUUID()
+      const id = hintedId !== undefined && !idCollides ? hintedId : createBrowserUuid()
       const shouldActivate = options?.activate !== false
       const nextOrdinal = getNextTerminalOrdinal(existing)
       const defaultTitle = `Terminal ${nextOrdinal}`
diff --git a/src/renderer/src/web/WebConnect.tsx b/src/renderer/src/web/WebConnect.tsx
new file mode 100644
index 00000000000..a7b9c56a969
--- /dev/null
+++ b/src/renderer/src/web/WebConnect.tsx
@@ -0,0 +1,143 @@
+import { useMemo, useState } from 'react'
+import { Cable, Loader2, Server, Trash2 } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import {
+  clearStoredWebRuntimeEnvironment,
+  createStoredWebRuntimeEnvironment,
+  isMixedContentWebSocket,
+  readStoredWebRuntimeEnvironment,
+  saveStoredWebRuntimeEnvironment
+} from './web-runtime-environment'
+import { parseWebPairingInput } from './web-pairing'
+import { WebRuntimeClient } from './web-runtime-client'
+
+type WebConnectProps = {
+  initialPairingInput: string | null
+  onConnected: () => void
+}
+
+export default function WebConnect({
+  initialPairingInput,
+  onConnected
+}: WebConnectProps): React.JSX.Element {
+  const existingEnvironment = readStoredWebRuntimeEnvironment()
+  const [name, setName] = useState(existingEnvironment?.name ?? 'Orca Server')
+  const [pairingCode, setPairingCode] = useState(initialPairingInput ?? '')
+  const [error, setError] = useState<string | null>(null)
+  const [connecting, setConnecting] = useState(false)
+  const parsedOffer = useMemo(() => parseWebPairingInput(pairingCode), [pairingCode])
+
+  const connect = async (): Promise<void> => {
+    setError(null)
+    if (!parsedOffer) {
+      setError('Enter a valid Orca pairing URL or pairing code.')
+      return
+    }
+    if (isMixedContentWebSocket(parsedOffer.endpoint)) {
+      setError(
+        'This HTTPS page cannot connect to a plain ws:// Orca server. Open the web client over HTTP or pair with a wss:// endpoint.'
+      )
+      return
+    }
+    setConnecting(true)
+    const environment = createStoredWebRuntimeEnvironment({ name, offer: parsedOffer })
+    const client = new WebRuntimeClient(parsedOffer)
+    try {
+      const response = await client.call('status.get', undefined, { timeoutMs: 15_000 })
+      if (!response.ok) {
+        throw new Error(response.error.message)
+      }
+      saveStoredWebRuntimeEnvironment({
+        ...environment,
+        runtimeId: response._meta.runtimeId,
+        lastUsedAt: Date.now()
+      })
+      onConnected()
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      client.close()
+      setConnecting(false)
+    }
+  }
+
+  const clear = (): void => {
+    clearStoredWebRuntimeEnvironment()
+    setPairingCode('')
+    setError(null)
+  }
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background px-4 py-6 text-foreground">
+      <div className="flex w-full max-w-[520px] flex-col gap-5 rounded-lg border border-border bg-card p-5 shadow-sm">
+        <div className="flex items-start gap-3">
+          <div className="flex size-9 shrink-0 items-center justify-center rounded-md border border-border bg-muted">
+            <Server size={18} aria-hidden />
+          </div>
+          <div className="min-w-0">
+            <h1 className="text-base font-semibold leading-6">Connect to Orca</h1>
+            <p className="mt-1 text-sm leading-5 text-muted-foreground">
+              Paste a pairing URL from an Orca server that this browser can reach.
+            </p>
+          </div>
+        </div>
+
+        <div className="grid gap-2">
+          <Label htmlFor="web-runtime-name">Server name</Label>
+          <Input
+            id="web-runtime-name"
+            value={name}
+            onChange={(event) => setName(event.target.value)}
+            autoComplete="off"
+          />
+        </div>
+
+        <div className="grid gap-2">
+          <Label htmlFor="web-runtime-pairing-code">Pairing URL or code</Label>
+          <Input
+            id="web-runtime-pairing-code"
+            value={pairingCode}
+            onChange={(event) => setPairingCode(event.target.value)}
+            placeholder="orca://pair#..."
+            autoComplete="off"
+            spellCheck={false}
+          />
+        </div>
+
+        {parsedOffer && (
+          <div className="rounded-md border border-border bg-muted px-3 py-2 text-xs text-muted-foreground">
+            Endpoint: {parsedOffer.endpoint}
+          </div>
+        )}
+
+        {error && (
+          <div className="rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+            {error}
+          </div>
+        )}
+
+        <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-between">
+          <Button type="button" variant="outline" onClick={clear} className="gap-2">
+            <Trash2 size={15} aria-hidden />
+            Clear saved server
+          </Button>
+          <Button
+            type="button"
+            onClick={() => void connect()}
+            disabled={connecting || !parsedOffer}
+            className="gap-2"
+          >
+            {connecting ? (
+              <Loader2 size={15} className="animate-spin" aria-hidden />
+            ) : (
+              <Cable size={15} aria-hidden />
+            )}
+            Connect
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/web/main.tsx b/src/renderer/src/web/main.tsx
new file mode 100644
index 00000000000..6e39b36f6b8
--- /dev/null
+++ b/src/renderer/src/web/main.tsx
@@ -0,0 +1,51 @@
+import '../assets/main.css'
+
+import { lazy, Suspense, useMemo, useState } from 'react'
+import ReactDOM from 'react-dom/client'
+import WebConnect from './WebConnect'
+import {
+  clearPairingInputFromAddressBar,
+  parseWebPairingInput,
+  readPairingInputFromLocation
+} from './web-pairing'
+import {
+  createStoredWebRuntimeEnvironment,
+  readStoredWebRuntimeEnvironment,
+  saveStoredWebRuntimeEnvironment
+} from './web-runtime-environment'
+import { installWebPreloadApi } from './web-preload-api'
+
+const App = lazy(() => import('../App'))
+
+function WebRoot(): React.JSX.Element {
+  const initialPairingInput = useMemo(() => readPairingInputFromLocation(window.location), [])
+  const [hasEnvironment, setHasEnvironment] = useState(() => {
+    const offer = initialPairingInput ? parseWebPairingInput(initialPairingInput) : null
+    if (offer) {
+      saveStoredWebRuntimeEnvironment(
+        createStoredWebRuntimeEnvironment({ name: 'Orca Server', offer })
+      )
+      clearPairingInputFromAddressBar()
+      return true
+    }
+    return readStoredWebRuntimeEnvironment() !== null
+  })
+
+  if (!hasEnvironment) {
+    return (
+      <WebConnect
+        initialPairingInput={initialPairingInput}
+        onConnected={() => setHasEnvironment(true)}
+      />
+    )
+  }
+
+  installWebPreloadApi()
+  return (
+    <Suspense fallback={<div className="min-h-screen bg-background" />}>
+      <App />
+    </Suspense>
+  )
+}
+
+ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(<WebRoot />)
diff --git a/src/renderer/src/web/web-e2ee.ts b/src/renderer/src/web/web-e2ee.ts
new file mode 100644
index 00000000000..933a745ee17
--- /dev/null
+++ b/src/renderer/src/web/web-e2ee.ts
@@ -0,0 +1,80 @@
+import nacl from 'tweetnacl'
+
+if (globalThis.crypto?.getRandomValues) {
+  nacl.setPRNG((bytes, count) => {
+    globalThis.crypto.getRandomValues(bytes.subarray(0, count) as Uint8Array<ArrayBuffer>)
+  })
+}
+
+export function generateKeyPair(): nacl.BoxKeyPair {
+  return nacl.box.keyPair()
+}
+
+export function deriveSharedKey(ourSecretKey: Uint8Array, peerPublicKey: Uint8Array): Uint8Array {
+  return nacl.box.before(peerPublicKey, ourSecretKey)
+}
+
+export function publicKeyFromBase64(b64: string): Uint8Array {
+  const key = base64ToBytes(b64)
+  if (key.length !== 32) {
+    throw new Error(`Invalid public key: expected 32 bytes, got ${key.length}`)
+  }
+  return key
+}
+
+export function publicKeyToBase64(key: Uint8Array): string {
+  return bytesToBase64(key)
+}
+
+export function encrypt(plaintext: string, sharedKey: Uint8Array): string {
+  return bytesToBase64(encryptBytes(new TextEncoder().encode(plaintext), sharedKey))
+}
+
+export function decrypt(encrypted: string, sharedKey: Uint8Array): string | null {
+  const plaintext = decryptBytes(base64ToBytes(encrypted), sharedKey)
+  return plaintext ? new TextDecoder().decode(plaintext) : null
+}
+
+export function encryptBytes(
+  plaintext: Uint8Array<ArrayBufferLike>,
+  sharedKey: Uint8Array
+): Uint8Array<ArrayBuffer> {
+  const nonce = nacl.randomBytes(nacl.box.nonceLength)
+  const ciphertext = nacl.box.after(plaintext, nonce, sharedKey)
+  const bundle = new Uint8Array(nonce.length + ciphertext.length)
+  bundle.set(nonce)
+  bundle.set(ciphertext, nonce.length)
+  return bundle
+}
+
+export function decryptBytes(
+  bundle: Uint8Array<ArrayBufferLike>,
+  sharedKey: Uint8Array
+): Uint8Array<ArrayBuffer> | null {
+  if (bundle.length < nacl.box.nonceLength + nacl.box.overheadLength) {
+    return null
+  }
+  const nonce = bundle.slice(0, nacl.box.nonceLength)
+  const ciphertext = bundle.slice(nacl.box.nonceLength)
+  const plaintext = nacl.box.open.after(ciphertext, nonce, sharedKey)
+  return plaintext ? new Uint8Array(plaintext) : null
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = window.atob(value)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index)
+  }
+  return bytes
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  const chunkSize = 0x8000
+  let binary = ''
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    const chunk = bytes.subarray(offset, offset + chunkSize)
+    binary += String.fromCharCode(...chunk)
+  }
+  return window.btoa(binary)
+}
diff --git a/src/renderer/src/web/web-pairing.ts b/src/renderer/src/web/web-pairing.ts
new file mode 100644
index 00000000000..cc2fc747ab5
--- /dev/null
+++ b/src/renderer/src/web/web-pairing.ts
@@ -0,0 +1,107 @@
+const PAIRING_OFFER_VERSION = 2
+
+export type WebPairingOffer = {
+  v: typeof PAIRING_OFFER_VERSION
+  endpoint: string
+  deviceToken: string
+  publicKeyB64: string
+}
+
+export function parseWebPairingInput(input: string): WebPairingOffer | null {
+  const trimmed = input.trim()
+  if (!trimmed) {
+    return null
+  }
+
+  try {
+    if (trimmed.startsWith('orca://pair')) {
+      const hashIndex = trimmed.indexOf('#')
+      if (hashIndex === -1) {
+        return null
+      }
+      return decodePairingPayload(trimmed.slice(hashIndex + 1))
+    }
+    return decodePairingPayload(trimmed)
+  } catch {
+    return null
+  }
+}
+
+export function readPairingInputFromLocation(location: Location): string | null {
+  const search = new URLSearchParams(location.search)
+  for (const key of ['pairing', 'pair', 'code', 'token']) {
+    const value = search.get(key)
+    if (value?.trim()) {
+      return value.trim()
+    }
+  }
+
+  const hash = location.hash.replace(/^#/, '').trim()
+  if (!hash) {
+    return null
+  }
+  if (hash.startsWith('orca://pair')) {
+    return hash
+  }
+  const hashParams = new URLSearchParams(hash)
+  for (const key of ['pairing', 'pair', 'code', 'token']) {
+    const value = hashParams.get(key)
+    if (value?.trim()) {
+      return value.trim()
+    }
+  }
+  return hash
+}
+
+export function clearPairingInputFromAddressBar(): void {
+  if (!window.location.hash && !window.location.search) {
+    return
+  }
+  const cleanUrl = `${window.location.origin}${window.location.pathname}`
+  // Why: pairing payloads include the runtime auth token. Clear them after
+  // import so refresh/share/browser history no longer expose the secret.
+  window.history.replaceState(null, document.title, cleanUrl)
+}
+
+function decodePairingPayload(base64url: string): WebPairingOffer | null {
+  const json = new TextDecoder().decode(base64UrlToBytes(base64url))
+  const parsed = JSON.parse(json) as Partial<WebPairingOffer>
+  if (
+    parsed.v !== PAIRING_OFFER_VERSION ||
+    typeof parsed.endpoint !== 'string' ||
+    parsed.endpoint.length === 0 ||
+    typeof parsed.deviceToken !== 'string' ||
+    parsed.deviceToken.length === 0 ||
+    typeof parsed.publicKeyB64 !== 'string' ||
+    parsed.publicKeyB64.length === 0
+  ) {
+    return null
+  }
+  return {
+    v: PAIRING_OFFER_VERSION,
+    endpoint: normalizeWebSocketEndpoint(parsed.endpoint),
+    deviceToken: parsed.deviceToken,
+    publicKeyB64: parsed.publicKeyB64
+  }
+}
+
+function base64UrlToBytes(value: string): Uint8Array {
+  const base64 = value.replace(/-/g, '+').replace(/_/g, '/')
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=')
+  const binary = window.atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index)
+  }
+  return bytes
+}
+
+function normalizeWebSocketEndpoint(endpoint: string): string {
+  if (endpoint.startsWith('http://')) {
+    return `ws://${endpoint.slice('http://'.length)}`
+  }
+  if (endpoint.startsWith('https://')) {
+    return `wss://${endpoint.slice('https://'.length)}`
+  }
+  return endpoint
+}
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
new file mode 100644
index 00000000000..b8bb0242a4a
--- /dev/null
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -0,0 +1,1332 @@
+/* eslint-disable max-lines -- Why: the web preload adapter is the browser-side
+   replacement for Electron preload, so the compatibility surface is necessarily
+   centralized at this boundary. */
+import type { PreloadApi, PreflightStatus, RefreshAgentsResult } from '../../../preload/api-types'
+import type { RuntimeRpcResponse } from '../../../shared/runtime-rpc-envelope'
+import type {
+  DirEntry,
+  GlobalSettings,
+  MemorySnapshot,
+  OnboardingState,
+  Repo,
+  SearchResult,
+  StatsSummary,
+  Worktree
+} from '../../../shared/types'
+import {
+  getDefaultOnboardingState,
+  getDefaultSettings,
+  getDefaultUIState,
+  getDefaultWorkspaceSession
+} from '../../../shared/constants'
+import { createE2EConfig } from '../../../shared/e2e-config'
+import { relativePathInsideRoot } from '../../../shared/cross-platform-path'
+import type { RateLimitState } from '../../../shared/rate-limit-types'
+import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../../../shared/runtime-types'
+import {
+  clearStoredWebRuntimeEnvironment,
+  createStoredWebRuntimeEnvironment,
+  getPreferredWebPairingOffer,
+  readStoredWebRuntimeEnvironment,
+  redactStoredWebRuntimeEnvironment,
+  saveStoredWebRuntimeEnvironment,
+  updateStoredEnvironmentRuntimeId,
+  type StoredWebRuntimeEnvironment
+} from './web-runtime-environment'
+import { parseWebPairingInput } from './web-pairing'
+import { WebRuntimeClient } from './web-runtime-client'
+
+const SETTINGS_STORAGE_KEY = 'orca.web.settings.v1'
+const UI_STORAGE_KEY = 'orca.web.ui.v1'
+const SESSION_STORAGE_KEY = 'orca.web.workspaceSession.v1'
+const ONBOARDING_STORAGE_KEY = 'orca.web.onboarding.v1'
+const GITHUB_CACHE_STORAGE_KEY = 'orca.web.githubCache.v1'
+
+let activeEnvironment: StoredWebRuntimeEnvironment | null = readStoredWebRuntimeEnvironment()
+let activeClient: WebRuntimeClient | null = null
+let activeClientEnvironmentId: string | null = null
+let cachedWorktrees: { loadedAt: number; worktrees: Worktree[] } | null = null
+
+type WebSettingsApi = NonNullable<PreloadApi['settings']>
+
+export function installWebPreloadApi(): void {
+  activeEnvironment = readStoredWebRuntimeEnvironment()
+  const webWindow = window as unknown as { __ORCA_WEB_CLIENT__?: boolean }
+  webWindow.__ORCA_WEB_CLIENT__ = true
+  window.electron = createFallbackProxy(['electron']) as Window['electron']
+  window.api = withFallback(createWebPreloadApi(), []) as PreloadApi
+}
+
+function createWebPreloadApi(): Partial<PreloadApi> {
+  return {
+    app: {
+      getFeatureWallAssetBaseUrl: () => Promise.resolve('/'),
+      relaunch: () => Promise.resolve(window.location.reload()),
+      getKeyboardInputSourceId: () => Promise.resolve(null),
+      setUnreadDockBadgeCount: () => Promise.resolve(),
+      getFloatingTerminalCwd: () => Promise.resolve('~')
+    },
+    e2e: {
+      getConfig: () => createE2EConfig({})
+    },
+    settings: {
+      get: async () => getStoredSettings(),
+      set: async (updates) => {
+        if (updates.activeRuntimeEnvironmentId === null) {
+          disconnectActiveRuntimeEnvironment()
+        }
+        const next = mergeSettings(getStoredSettings(), updates)
+        writeJson(SETTINGS_STORAGE_KEY, next)
+        return next
+      },
+      listFonts: () => Promise.resolve([]),
+      onChanged: () => noopUnsubscribe
+    } satisfies Partial<WebSettingsApi> as unknown as WebSettingsApi,
+    ui: createWebUiApi(),
+    session: {
+      get: () => Promise.resolve(readJson(SESSION_STORAGE_KEY, getDefaultWorkspaceSession())),
+      set: async (session) => {
+        writeJson(SESSION_STORAGE_KEY, session)
+      },
+      setSync: (session) => {
+        writeJson(SESSION_STORAGE_KEY, session)
+      }
+    },
+    onboarding: {
+      get: () => Promise.resolve(getStoredOnboarding()),
+      update: async (updates) => {
+        const current = getStoredOnboarding()
+        const next: OnboardingState = {
+          ...current,
+          ...updates,
+          checklist: {
+            ...current.checklist,
+            ...updates.checklist
+          }
+        }
+        writeJson(ONBOARDING_STORAGE_KEY, next)
+        return next
+      }
+    },
+    cache: {
+      getGitHub: () =>
+        Promise.resolve(
+          readJson(GITHUB_CACHE_STORAGE_KEY, {
+            pr: {},
+            issue: {}
+          })
+        ),
+      setGitHub: async ({ cache }) => {
+        writeJson(GITHUB_CACHE_STORAGE_KEY, cache)
+      }
+    },
+    runtime: createRuntimeApi(),
+    runtimeEnvironments: createRuntimeEnvironmentsApi(),
+    repos: createReposApi(),
+    worktrees: createWorktreesApi(),
+    fs: createFileApi(),
+    git: createGitApi(),
+    browser: createBrowserApi(),
+    gh: createGitHubApi(),
+    linear: createRuntimeNamespaceApi('linear'),
+    notes: createNotesApi(),
+    hooks: createHooksApi(),
+    stats: {
+      getSummary: async () =>
+        callRuntimeResult<StatsSummary>('stats.summary').catch(() => ({
+          totalAgentsSpawned: 0,
+          totalPRsCreated: 0,
+          totalAgentTimeMs: 0,
+          firstEventAt: null
+        }))
+    },
+    memory: {
+      getSnapshot: () => Promise.resolve(createEmptyMemorySnapshot())
+    },
+    preflight: createPreflightApi(),
+    notifications: createNotificationsApi(),
+    rateLimits: createRateLimitsApi(),
+    codexAccounts: createAccountsApi(),
+    claudeAccounts: createAccountsApi(),
+    cli: createCliApi(),
+    agentHooks: createAgentHooksApi(),
+    developerPermissions: createDeveloperPermissionsApi(),
+    computerUsePermissions: createComputerUsePermissionsApi(),
+    updater: createUpdaterApi(),
+    shell: createShellApi(),
+    pty: createPtyApi(),
+    ssh: createSshApi(),
+    wsl: { isAvailable: () => Promise.resolve(false) },
+    pwsh: { isAvailable: () => Promise.resolve(false) },
+    agentStatus: {
+      onSet: () => noopUnsubscribe,
+      getSnapshot: () => Promise.resolve([]),
+      drop: () => {}
+    },
+    mobile: {
+      listNetworkInterfaces: () => Promise.resolve({ interfaces: [] }),
+      getPairingQR: () => Promise.resolve({ available: false }),
+      getRuntimePairingUrl: () => Promise.resolve({ available: false }),
+      listDevices: () => Promise.resolve({ devices: [] }),
+      revokeDevice: () => Promise.resolve({ revoked: false }),
+      isWebSocketReady: () => Promise.resolve({ ready: Boolean(activeEnvironment), endpoint: null })
+    },
+    telemetryTrack: () => Promise.resolve(),
+    telemetrySetOptIn: () => Promise.resolve(),
+    telemetryGetConsentState: () =>
+      Promise.resolve({ optedIn: false, source: 'default', blockedByEnv: false } as never),
+    telemetryAcknowledgeBanner: () => Promise.resolve()
+  }
+}
+
+function createRuntimeApi(): NonNullable<Partial<PreloadApi>['runtime']> {
+  return {
+    syncWindowGraph: async (_graph: RuntimeSyncWindowGraph) => getRemoteRuntimeStatus(),
+    getStatus: () => getRemoteRuntimeStatus(),
+    call: ({ method, params }) => callRuntimeEnvelope(method, params),
+    getTerminalFitOverrides: () => Promise.resolve([]),
+    restoreTerminalFit: () => Promise.resolve({ restored: false }),
+    onTerminalFitOverrideChanged: () => noopUnsubscribe,
+    onTerminalDriverChanged: () => noopUnsubscribe
+  }
+}
+
+function createRuntimeEnvironmentsApi(): NonNullable<Partial<PreloadApi>['runtimeEnvironments']> {
+  return {
+    list: async () => {
+      const environment = requireActiveEnvironmentOrNull()
+      return environment ? [redactStoredWebRuntimeEnvironment(environment)] : []
+    },
+    addFromPairingCode: async ({ name, pairingCode }) => {
+      const offer = parseWebPairingInput(pairingCode)
+      if (!offer) {
+        throw new Error('Invalid Orca pairing code.')
+      }
+      closeActiveRuntimeClients()
+      activeEnvironment = createStoredWebRuntimeEnvironment({ name, offer })
+      saveStoredWebRuntimeEnvironment(activeEnvironment)
+      return { environment: redactStoredWebRuntimeEnvironment(activeEnvironment) }
+    },
+    resolve: async ({ selector }) =>
+      redactStoredWebRuntimeEnvironment(resolveEnvironment(selector)),
+    remove: async ({ selector }) => {
+      const environment = resolveEnvironment(selector)
+      if (activeEnvironment?.id === environment.id) {
+        disconnectActiveRuntimeEnvironment()
+      }
+      return { removed: redactStoredWebRuntimeEnvironment(environment) }
+    },
+    getStatus: ({ selector, timeoutMs }) =>
+      callEnvironmentEnvelope<RuntimeStatus>(selector, 'status.get', undefined, timeoutMs),
+    call: ({ selector, method, params, timeoutMs }) =>
+      callEnvironmentEnvelope(selector, method, params, timeoutMs),
+    subscribe: async ({ selector, method, params, timeoutMs }, callbacks) => {
+      const environment = resolveEnvironment(selector)
+      const client = getClientForEnvironment(environment)
+      return client.subscribe(method, params, callbacks, { timeoutMs })
+    }
+  }
+}
+
+function createReposApi(): NonNullable<Partial<PreloadApi>['repos']> {
+  return {
+    list: async () => (await callRuntimeResult<{ repos: Repo[] }>('repo.list')).repos,
+    add: async ({ path, kind }) => callRuntimeResult('repo.add', { path, kind }),
+    remove: async ({ repoId }) => {
+      await callRuntimeResult('repo.rm', { repo: repoId })
+      cachedWorktrees = null
+    },
+    reorder: async ({ orderedIds }) => callRuntimeResult('repo.reorder', { orderedIds }),
+    update: async ({ repoId, updates }) =>
+      (await callRuntimeResult<{ repo: Repo }>('repo.update', { repo: repoId, updates })).repo,
+    pickFolder: () => Promise.resolve(null),
+    pickDirectory: () => Promise.resolve(null),
+    clone: async ({ url, destination }) =>
+      (await callRuntimeResult<{ repo: Repo }>('repo.clone', { url, destination }, 10 * 60_000))
+        .repo,
+    cloneAbort: () => Promise.resolve(),
+    addRemote: async ({ remotePath, displayName, kind }) => {
+      const result = await callRuntimeResult<{ repo: Repo }>('repo.add', {
+        path: remotePath,
+        kind
+      })
+      return displayName
+        ? {
+            repo: await createReposApi().update({
+              repoId: result.repo.id,
+              updates: { displayName }
+            })
+          }
+        : result
+    },
+    create: async ({ parentPath, name, kind }) =>
+      callRuntimeResult('repo.create', { parentPath, name, kind }),
+    onCloneProgress: () => noopUnsubscribe,
+    getGitUsername: () => Promise.resolve(''),
+    getBaseRefDefault: async ({ repoId }) =>
+      callRuntimeResult('repo.baseRefDefault', { repo: repoId }),
+    searchBaseRefs: async ({ repoId, query, limit }) =>
+      (
+        await callRuntimeResult<{ refs: string[] }>('repo.searchRefs', {
+          repo: repoId,
+          query,
+          limit
+        })
+      ).refs,
+    onChanged: () => noopUnsubscribe
+  }
+}
+
+function createWorktreesApi(): NonNullable<Partial<PreloadApi>['worktrees']> {
+  return {
+    list: async ({ repoId }) =>
+      (await callRuntimeResult<{ worktrees: Worktree[] }>('worktree.list', { repo: repoId }))
+        .worktrees,
+    listAll: () => listAllRuntimeWorktrees(),
+    create: async (args) => {
+      cachedWorktrees = null
+      return callRuntimeResult('worktree.create', {
+        repo: args.repoId,
+        name: args.name,
+        baseBranch: args.baseBranch,
+        linkedIssue: args.linkedIssue,
+        linkedPR: args.linkedPR,
+        displayName: args.displayName,
+        sparseCheckout: args.sparseCheckout,
+        pushTarget: args.pushTarget,
+        setupDecision: args.setupDecision,
+        createdWithAgent: args.createdWithAgent
+      })
+    },
+    resolvePrBase: async ({ repoId, prNumber, headRefName, isCrossRepository }) =>
+      callRuntimeResult('worktree.resolvePrBase', {
+        repo: repoId,
+        prNumber,
+        headRefName,
+        isCrossRepository
+      }),
+    resolveMrBase: async () => ({
+      error: 'GitLab merge request base resolution is unavailable on web.'
+    }),
+    remove: async ({ worktreeId, force }) => {
+      cachedWorktrees = null
+      await callRuntimeResult('worktree.rm', { worktree: worktreeId, force })
+    },
+    updateMeta: async ({ worktreeId, updates }) =>
+      (
+        await callRuntimeResult<{ worktree: Worktree }>('worktree.set', {
+          worktree: worktreeId,
+          ...updates
+        })
+      ).worktree,
+    persistSortOrder: async ({ orderedIds }) => {
+      await callRuntimeResult('worktree.persistSortOrder', { orderedIds })
+    },
+    onChanged: () => noopUnsubscribe,
+    onBaseStatus: () => noopUnsubscribe,
+    onRemoteBranchConflict: () => noopUnsubscribe
+  }
+}
+
+function createFileApi(): NonNullable<Partial<PreloadApi>['fs']> {
+  return {
+    readDir: async ({ dirPath }) => {
+      const file = await resolveRuntimeFilePath(dirPath)
+      return callRuntimeResult<DirEntry[]>('files.readDir', {
+        worktree: file.worktree.id,
+        relativePath: file.relativePath
+      })
+    },
+    readFile: async ({ filePath }) => {
+      const file = await resolveRuntimeFilePath(filePath)
+      return callRuntimeResult('files.readPreview', {
+        worktree: file.worktree.id,
+        relativePath: file.relativePath
+      })
+    },
+    listMarkdownDocuments: async ({ rootPath }) => {
+      const file = await resolveRuntimeFilePath(rootPath)
+      return callRuntimeResult('files.listMarkdownDocuments', { worktree: file.worktree.id })
+    },
+    writeFile: async ({ filePath, content }) => {
+      const file = await resolveRuntimeFilePath(filePath)
+      await callRuntimeResult('files.write', {
+        worktree: file.worktree.id,
+        relativePath: file.relativePath,
+        content
+      })
+    },
+    createFile: async ({ filePath }) => {
+      const file = await resolveRuntimeFilePath(filePath)
+      await callRuntimeResult('files.createFile', {
+        worktree: file.worktree.id,
+        relativePath: file.relativePath
+      })
+    },
+    createDir: async ({ dirPath }) => {
+      const file = await resolveRuntimeFilePath(dirPath)
+      await callRuntimeResult('files.createDir', {
+        worktree: file.worktree.id,
+        relativePath: file.relativePath
+      })
+    },
+    rename: async ({ oldPath, newPath }) => {
+      const oldFile = await resolveRuntimeFilePath(oldPath)
+      const newFile = await resolveRuntimeFilePath(newPath)
+      await callRuntimeResult('files.rename', {
+        worktree: oldFile.worktree.id,
+        oldRelativePath: oldFile.relativePath,
+        newRelativePath: newFile.relativePath
+      })
+    },
+    copy: async ({ sourcePath, destinationPath }) => {
+      const source = await resolveRuntimeFilePath(sourcePath)
+      const destination = await resolveRuntimeFilePath(destinationPath)
+      await callRuntimeResult('files.copy', {
+        worktree: source.worktree.id,
+        sourceRelativePath: source.relativePath,
+        destinationRelativePath: destination.relativePath
+      })
+    },
+    deletePath: async ({ targetPath, recursive }) => {
+      const file = await resolveRuntimeFilePath(targetPath)
+      await callRuntimeResult('files.delete', {
+        worktree: file.worktree.id,
+        relativePath: file.relativePath,
+        recursive
+      })
+    },
+    authorizeExternalPath: () => Promise.resolve(),
+    stat: async ({ filePath }) => {
+      const file = await resolveRuntimeFilePath(filePath)
+      return callRuntimeResult('files.stat', {
+        worktree: file.worktree.id,
+        relativePath: file.relativePath
+      })
+    },
+    listFiles: async ({ rootPath, excludePaths }) => {
+      const file = await resolveRuntimeFilePath(rootPath)
+      const result = await callRuntimeResult<{ files: { relativePath: string }[] }>(
+        'files.listAll',
+        {
+          worktree: file.worktree.id,
+          excludePaths
+        }
+      )
+      return result.files.map((entry) => entry.relativePath)
+    },
+    search: async (args) => {
+      const file = await resolveRuntimeFilePath(args.rootPath)
+      return callRuntimeResult<SearchResult>('files.search', {
+        worktree: file.worktree.id,
+        query: args.query,
+        caseSensitive: args.caseSensitive,
+        wholeWord: args.wholeWord,
+        useRegex: args.useRegex,
+        includePattern: args.includePattern,
+        excludePattern: args.excludePattern,
+        maxResults: args.maxResults
+      })
+    },
+    importExternalPaths: async () => ({ results: [] }),
+    stageExternalPathsForRuntimeUpload: async () => ({ sources: [] }),
+    resolveDroppedPathsForAgent: async () => ({ resolvedPaths: [], skipped: [], failed: [] }),
+    watchWorktree: () => Promise.resolve(),
+    unwatchWorktree: () => Promise.resolve(),
+    onFsChanged: () => noopUnsubscribe
+  }
+}
+
+function createGitApi(): NonNullable<Partial<PreloadApi>['git']> {
+  return {
+    status: async ({ worktreePath }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      return callRuntimeResult('git.status', { worktree: worktree.id })
+    },
+    conflictOperation: async ({ worktreePath }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      return callRuntimeResult('git.conflictOperation', { worktree: worktree.id })
+    },
+    diff: async ({ worktreePath, filePath, staged, compareAgainstHead }) => {
+      const file = await resolveRuntimeFilePath(filePath, worktreePath)
+      return callRuntimeResult('git.diff', {
+        worktree: file.worktree.id,
+        filePath: file.relativePath,
+        staged,
+        compareAgainstHead
+      })
+    },
+    branchCompare: async ({ worktreePath, baseRef }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      return callRuntimeResult('git.branchCompare', { worktree: worktree.id, baseRef })
+    },
+    upstreamStatus: async ({ worktreePath }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      return callRuntimeResult('git.upstreamStatus', { worktree: worktree.id })
+    },
+    fetch: async ({ worktreePath }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      await callRuntimeResult('git.fetch', { worktree: worktree.id })
+    },
+    push: async ({ worktreePath, publish, pushTarget }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      await callRuntimeResult('git.push', { worktree: worktree.id, publish, pushTarget })
+    },
+    pull: async ({ worktreePath }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      await callRuntimeResult('git.pull', { worktree: worktree.id })
+    },
+    branchDiff: async ({ worktreePath, filePath, compare, oldPath }) => {
+      const file = await resolveRuntimeFilePath(filePath, worktreePath)
+      return callRuntimeResult('git.branchDiff', {
+        worktree: file.worktree.id,
+        filePath: file.relativePath,
+        compare,
+        oldPath
+      })
+    },
+    commit: async ({ worktreePath, message }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      return callRuntimeResult('git.commit', { worktree: worktree.id, message })
+    },
+    generateCommitMessage: async () => ({
+      success: false,
+      error: 'Commit message generation is unavailable in the web client.'
+    }),
+    cancelGenerateCommitMessage: () => Promise.resolve(),
+    stage: async ({ worktreePath, filePath }) => mutateGitPath('git.stage', worktreePath, filePath),
+    bulkStage: async ({ worktreePath, filePaths }) =>
+      mutateGitPaths('git.bulkStage', worktreePath, filePaths),
+    unstage: async ({ worktreePath, filePath }) =>
+      mutateGitPath('git.unstage', worktreePath, filePath),
+    bulkUnstage: async ({ worktreePath, filePaths }) =>
+      mutateGitPaths('git.bulkUnstage', worktreePath, filePaths),
+    discard: async ({ worktreePath, filePath }) =>
+      mutateGitPath('git.discard', worktreePath, filePath),
+    bulkDiscard: async ({ worktreePath, filePaths }) => {
+      for (const filePath of filePaths) {
+        await mutateGitPath('git.discard', worktreePath, filePath)
+      }
+    },
+    remoteFileUrl: async ({ worktreePath, relativePath, line }) => {
+      const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+      return callRuntimeResult('git.remoteFileUrl', {
+        worktree: worktree.id,
+        relativePath,
+        line
+      })
+    }
+  }
+}
+
+function createBrowserApi(): NonNullable<Partial<PreloadApi>['browser']> {
+  return {
+    registerGuest: () => Promise.resolve(),
+    unregisterGuest: () => Promise.resolve(),
+    openDevTools: () => Promise.resolve(false),
+    setViewportOverride: () => Promise.resolve(false),
+    onGuestLoadFailed: () => noopUnsubscribe,
+    onPermissionDenied: () => noopUnsubscribe,
+    onPopup: () => noopUnsubscribe,
+    onDownloadRequested: () => noopUnsubscribe,
+    onDownloadProgress: () => noopUnsubscribe,
+    onDownloadFinished: () => noopUnsubscribe,
+    onContextMenuRequested: () => noopUnsubscribe,
+    onContextMenuDismissed: () => noopUnsubscribe,
+    onNavigationUpdate: () => noopUnsubscribe,
+    onActivateView: () => noopUnsubscribe,
+    onPaneFocus: () => noopUnsubscribe,
+    onOpenLinkInOrcaTab: () => noopUnsubscribe,
+    acceptDownload: () =>
+      Promise.resolve({ ok: false, reason: 'Downloads are handled by the server browser.' }),
+    cancelDownload: () => Promise.resolve(false),
+    setGrabMode: () =>
+      Promise.resolve({ ok: false, error: 'Grab mode is unavailable in the web client.' }),
+    awaitGrabSelection: () =>
+      Promise.resolve({ ok: false, error: 'Grab mode is unavailable in the web client.' }),
+    cancelGrab: () => Promise.resolve(false),
+    captureSelectionScreenshot: () =>
+      Promise.resolve({
+        ok: false,
+        error: 'Selection screenshots are unavailable in the web client.'
+      }),
+    extractHoverPayload: () =>
+      Promise.resolve({ ok: false, error: 'Hover extraction is unavailable in the web client.' }),
+    onGrabModeToggle: () => noopUnsubscribe,
+    onGrabActionShortcut: () => noopUnsubscribe,
+    sessionListProfiles: () => Promise.resolve([]),
+    sessionCreateProfile: () => Promise.resolve(null),
+    sessionDeleteProfile: () => Promise.resolve(false),
+    sessionImportCookies: () =>
+      Promise.resolve({
+        ok: false,
+        summary: null,
+        error: 'Cookie import is unavailable in the web client.'
+      }),
+    sessionResolvePartition: () => Promise.resolve(null),
+    sessionDetectBrowsers: () => Promise.resolve([]),
+    sessionImportFromBrowser: () =>
+      Promise.resolve({
+        ok: false,
+        summary: null,
+        error: 'Cookie import is unavailable in the web client.'
+      }),
+    sessionClearDefaultCookies: () => Promise.resolve(false),
+    notifyActiveTabChanged: () => Promise.resolve(false)
+  } as unknown as NonNullable<Partial<PreloadApi>['browser']>
+}
+
+function createGitHubApi(): NonNullable<Partial<PreloadApi>['gh']> {
+  const direct = (method: string) => (args?: unknown) =>
+    callRuntimeResult(method, mapRepoPathArg(args))
+  return {
+    viewer: () => Promise.resolve(null),
+    repoSlug: direct('github.repoSlug'),
+    prForBranch: direct('github.prForBranch'),
+    issue: direct('github.issue'),
+    workItem: direct('github.workItem'),
+    workItemByOwnerRepo: direct('github.workItemByOwnerRepo'),
+    workItemDetails: direct('github.workItemDetails'),
+    prFileContents: direct('github.prFileContents'),
+    listIssues: async () => [],
+    createIssue: direct('github.createIssue'),
+    countWorkItems: direct('github.countWorkItems'),
+    listWorkItems: direct('github.listWorkItems'),
+    prChecks: direct('github.prChecks'),
+    prComments: direct('github.prComments'),
+    resolveReviewThread: direct('github.resolveReviewThread'),
+    updatePRTitle: direct('github.updatePRTitle'),
+    mergePR: direct('github.mergePR'),
+    updateIssue: direct('github.updateIssue'),
+    addIssueComment: direct('github.addIssueComment'),
+    addPRReviewCommentReply: direct('github.addPRReviewCommentReply'),
+    addPRReviewComment: direct('github.addPRReviewComment'),
+    listLabels: direct('github.listLabels'),
+    listAssignableUsers: direct('github.listAssignableUsers'),
+    onWorkItemMutated: () => noopUnsubscribe,
+    checkOrcaStarred: () => Promise.resolve(null),
+    starOrca: () => Promise.resolve(false),
+    rateLimit: direct('github.rateLimit'),
+    diagnoseAuth: () =>
+      Promise.resolve({ ok: false, message: 'Unavailable in the web client.' } as never),
+    listAccessibleProjects: direct('github.project.listAccessible'),
+    resolveProjectRef: direct('github.project.resolveRef'),
+    listProjectViews: direct('github.project.listViews'),
+    getProjectViewTable: direct('github.project.viewTable'),
+    projectWorkItemDetailsBySlug: direct('github.project.workItemDetailsBySlug'),
+    updateProjectItemField: direct('github.project.updateItemField'),
+    clearProjectItemField: direct('github.project.clearItemField'),
+    updateIssueBySlug: direct('github.project.updateIssueBySlug'),
+    updatePullRequestBySlug: direct('github.project.updatePullRequestBySlug'),
+    addIssueCommentBySlug: direct('github.project.addIssueCommentBySlug'),
+    updateIssueCommentBySlug: direct('github.project.updateIssueCommentBySlug'),
+    deleteIssueCommentBySlug: direct('github.project.deleteIssueCommentBySlug'),
+    listLabelsBySlug: direct('github.project.listLabelsBySlug'),
+    listAssignableUsersBySlug: direct('github.project.listAssignableUsersBySlug'),
+    listIssueTypesBySlug: direct('github.project.listIssueTypesBySlug'),
+    updateIssueTypeBySlug: direct('github.project.updateIssueTypeBySlug')
+  } as NonNullable<Partial<PreloadApi>['gh']>
+}
+
+function createRuntimeNamespaceApi(prefix: string): never {
+  return createFallbackProxy([prefix], (path, args) => {
+    const method = `${prefix}.${path.at(-1) ?? ''}`
+    return callRuntimeResult(method, args[0])
+  }) as never
+}
+
+function createNotesApi(): NonNullable<Partial<PreloadApi>['notes']> {
+  const noteCall = (method: string) => (args: Record<string, unknown>) =>
+    callRuntimeResult(method, { ...args, worktree: args.worktreeId })
+  return {
+    list: noteCall('note.list'),
+    show: noteCall('note.show'),
+    create: noteCall('note.create'),
+    save: noteCall('note.save'),
+    rename: noteCall('note.rename'),
+    delete: noteCall('note.delete'),
+    append: noteCall('note.append'),
+    search: noteCall('note.search'),
+    link: noteCall('note.link'),
+    panelState: noteCall('note.panelState')
+  } as NonNullable<Partial<PreloadApi>['notes']>
+}
+
+function createHooksApi(): NonNullable<Partial<PreloadApi>['hooks']> {
+  return {
+    check: async ({ repoId }) => callRuntimeResult('repo.hooksCheck', { repo: repoId }),
+    createIssueCommandRunner: async () => ({ launched: false }) as never,
+    readIssueCommand: async ({ repoId }) =>
+      callRuntimeResult('repo.issueCommandRead', { repo: repoId }),
+    writeIssueCommand: async ({ repoId, content }) => {
+      await callRuntimeResult('repo.issueCommandWrite', { repo: repoId, content })
+    }
+  }
+}
+
+function createWebUiApi(): NonNullable<Partial<PreloadApi>['ui']> {
+  let zoomLevel = readJson(UI_STORAGE_KEY, getDefaultUIState()).uiZoomLevel
+  return {
+    get: () => Promise.resolve(readJson(UI_STORAGE_KEY, getDefaultUIState())),
+    set: async (updates) => {
+      const next = { ...readJson(UI_STORAGE_KEY, getDefaultUIState()), ...updates }
+      writeJson(UI_STORAGE_KEY, next)
+    },
+    readClipboardText: () => navigator.clipboard?.readText?.() ?? Promise.resolve(''),
+    saveClipboardImageAsTempFile: () => Promise.resolve(null),
+    writeClipboardText: (text) => navigator.clipboard?.writeText?.(text) ?? Promise.resolve(),
+    writeClipboardImage: () => Promise.resolve(),
+    getZoomLevel: () => zoomLevel,
+    setZoomLevel: (level) => {
+      zoomLevel = level
+    },
+    isMaximized: () => Promise.resolve(false),
+    onOpenSettings: () => noopUnsubscribe,
+    onOpenFeatureTour: () => noopUnsubscribe,
+    onShowFeatureTourNudge: () => noopUnsubscribe,
+    onToggleLeftSidebar: () => noopUnsubscribe,
+    onToggleRightSidebar: () => noopUnsubscribe,
+    onToggleWorktreePalette: () => noopUnsubscribe,
+    onToggleFloatingTerminal: () => noopUnsubscribe,
+    onOpenQuickOpen: () => noopUnsubscribe,
+    onOpenNewWorkspace: () => noopUnsubscribe,
+    onJumpToWorktreeIndex: () => noopUnsubscribe,
+    onWorktreeHistoryNavigate: () => noopUnsubscribe,
+    onNewBrowserTab: () => noopUnsubscribe,
+    onRequestTabCreate: () => noopUnsubscribe,
+    replyTabCreate: () => {},
+    onRequestTabSetProfile: () => noopUnsubscribe,
+    replyTabSetProfile: () => {},
+    onRequestTabClose: () => noopUnsubscribe,
+    replyTabClose: () => {},
+    onNewTerminalTab: () => noopUnsubscribe,
+    onFocusBrowserAddressBar: () => noopUnsubscribe,
+    onFindInBrowserPage: () => noopUnsubscribe,
+    onReloadBrowserPage: () => noopUnsubscribe,
+    onHardReloadBrowserPage: () => noopUnsubscribe,
+    onCloseActiveTab: () => noopUnsubscribe,
+    onSwitchTab: () => noopUnsubscribe,
+    onSwitchTabAcrossAllTypes: () => noopUnsubscribe,
+    onSwitchTerminalTab: () => noopUnsubscribe,
+    onToggleStatusBar: () => noopUnsubscribe,
+    onDictationKeyDown: () => noopUnsubscribe,
+    onExportPdfRequested: () => noopUnsubscribe,
+    onActivateWorktree: () => noopUnsubscribe,
+    onCreateTerminal: () => noopUnsubscribe,
+    onRequestTerminalCreate: () => noopUnsubscribe,
+    replyTerminalCreate: () => {},
+    onSplitTerminal: () => noopUnsubscribe,
+    onRenameTerminal: () => noopUnsubscribe,
+    onFocusTerminal: () => noopUnsubscribe,
+    onFocusEditorTab: () => noopUnsubscribe,
+    onCloseSessionTab: () => noopUnsubscribe,
+    onOpenFileFromMobile: () => noopUnsubscribe,
+    onMobileMarkdownRequest: () => noopUnsubscribe,
+    respondMobileMarkdownRequest: () => {},
+    onCloseTerminal: () => noopUnsubscribe,
+    onSleepWorktree: () => noopUnsubscribe,
+    onTerminalZoom: () => noopUnsubscribe,
+    onFileDrop: () => noopUnsubscribe,
+    syncTrafficLights: () => {},
+    setMarkdownEditorFocused: () => {},
+    onRichMarkdownContextCommand: () => noopUnsubscribe,
+    onFullscreenChanged: () => noopUnsubscribe,
+    minimize: () => {},
+    maximize: () => {},
+    onMaximizeChanged: () => noopUnsubscribe,
+    requestClose: () => {},
+    popupMenu: () => {},
+    onWindowCloseRequested: () => noopUnsubscribe,
+    confirmWindowClose: () => {}
+  }
+}
+
+function createPreflightApi(): NonNullable<Partial<PreloadApi>['preflight']> {
+  const fallbackStatus: PreflightStatus = {
+    git: { installed: false },
+    gh: { installed: false, authenticated: false },
+    glab: { installed: false, authenticated: false },
+    bitbucket: { configured: false, authenticated: false, account: null }
+  }
+  const fallbackRefreshAgents: RefreshAgentsResult = {
+    agents: [],
+    addedPathSegments: [],
+    shellHydrationOk: false,
+    pathSource: 'sync_seed_only',
+    pathFailureReason: 'spawn_error'
+  }
+  return {
+    check: async (args) => {
+      if (!requireActiveEnvironmentOrNull()) {
+        return fallbackStatus
+      }
+      return callRuntimeResult<PreflightStatus>('preflight.check', args)
+    },
+    detectAgents: async () => {
+      if (!requireActiveEnvironmentOrNull()) {
+        return []
+      }
+      return callRuntimeResult<string[]>('preflight.detectAgents').catch(() => [])
+    },
+    refreshAgents: () =>
+      requireActiveEnvironmentOrNull()
+        ? callRuntimeResult('preflight.refreshAgents')
+            .then((result) => result as RefreshAgentsResult)
+            .catch(() => fallbackRefreshAgents)
+        : Promise.resolve(fallbackRefreshAgents),
+    detectRemoteAgents: async (args) =>
+      requireActiveEnvironmentOrNull()
+        ? callRuntimeResult<string[]>('preflight.detectRemoteAgents', args).catch(() => [])
+        : []
+  }
+}
+
+function createCliApi(): NonNullable<Partial<PreloadApi>['cli']> {
+  const status = {
+    platform: getBrowserPlatform(),
+    commandName: 'orca',
+    commandPath: null,
+    pathDirectory: null,
+    pathConfigured: false,
+    launcherPath: null,
+    installMethod: null,
+    supported: false,
+    state: 'unsupported',
+    currentTarget: null,
+    unsupportedReason: 'launch_mode_unavailable',
+    detail: 'CLI registration is managed on the Orca server, not in the web browser.'
+  } as const
+  return {
+    getInstallStatus: () => Promise.resolve(status),
+    install: () => Promise.resolve(status),
+    remove: () => Promise.resolve(status)
+  } as NonNullable<Partial<PreloadApi>['cli']>
+}
+
+function createAgentHooksApi(): NonNullable<Partial<PreloadApi>['agentHooks']> {
+  const status = (agent: 'claude' | 'codex' | 'gemini' | 'cursor' | 'droid') =>
+    Promise.resolve({
+      agent,
+      state: 'not_installed',
+      configPath: '',
+      managedHooksPresent: false,
+      detail: 'Agent hook status is only available on the Orca server.'
+    } as const)
+  return {
+    claudeStatus: () => status('claude'),
+    codexStatus: () => status('codex'),
+    geminiStatus: () => status('gemini'),
+    cursorStatus: () => status('cursor'),
+    droidStatus: () => status('droid')
+  }
+}
+
+function createDeveloperPermissionsApi(): NonNullable<Partial<PreloadApi>['developerPermissions']> {
+  return {
+    getStatus: () => Promise.resolve([]),
+    request: ({ id }) =>
+      Promise.resolve({ id, status: 'unsupported', openedSystemSettings: false } as const),
+    openSettings: () => Promise.resolve()
+  }
+}
+
+function createComputerUsePermissionsApi(): NonNullable<
+  Partial<PreloadApi>['computerUsePermissions']
+> {
+  return {
+    getStatus: () =>
+      Promise.resolve({
+        platform: getBrowserPlatform(),
+        helperAppPath: null,
+        helperUnavailableReason: 'web_client',
+        permissions: []
+      }),
+    openSetup: () =>
+      Promise.resolve({
+        platform: getBrowserPlatform(),
+        helperAppPath: null,
+        openedSettings: false,
+        launchedHelper: false,
+        nextStep: 'Computer-use permissions are managed on the Orca server.'
+      })
+  }
+}
+
+function createNotificationsApi(): NonNullable<Partial<PreloadApi>['notifications']> {
+  return {
+    dispatch: () => Promise.resolve({ delivered: false, reason: 'not-supported' }),
+    openSystemSettings: () => Promise.resolve(),
+    getPermissionStatus: () =>
+      Promise.resolve({ supported: false, platform: getBrowserPlatform(), requested: false }),
+    requestPermission: () =>
+      Promise.resolve({ supported: false, platform: getBrowserPlatform(), requested: false }),
+    playSound: () => Promise.resolve({ played: false, reason: 'missing-path' })
+  }
+}
+
+function createRateLimitsApi(): NonNullable<Partial<PreloadApi>['rateLimits']> {
+  const empty: RateLimitState = {
+    claude: null,
+    codex: null,
+    gemini: null,
+    opencodeGo: null,
+    inactiveClaudeAccounts: [],
+    inactiveCodexAccounts: []
+  }
+  return {
+    get: () => Promise.resolve(empty),
+    refresh: () => Promise.resolve(empty),
+    setPollingInterval: () => Promise.resolve(),
+    fetchInactiveClaudeAccounts: () => Promise.resolve(),
+    fetchInactiveCodexAccounts: () => Promise.resolve(),
+    onUpdate: () => noopUnsubscribe
+  }
+}
+
+function createAccountsApi(): never {
+  const empty = { accounts: [], activeAccountId: null }
+  return {
+    list: () => Promise.resolve(empty),
+    add: () => Promise.resolve(empty),
+    reauthenticate: () => Promise.resolve(empty),
+    remove: () => Promise.resolve(empty),
+    select: () => Promise.resolve(empty)
+  } as never
+}
+
+function createUpdaterApi(): NonNullable<Partial<PreloadApi>['updater']> {
+  return {
+    getVersion: () => Promise.resolve('web'),
+    getStatus: () => Promise.resolve({ state: 'idle' } as never),
+    check: () => Promise.resolve(),
+    download: () => Promise.resolve(),
+    quitAndInstall: () => Promise.resolve(),
+    dismissNudge: () => Promise.resolve(),
+    onStatus: () => noopUnsubscribe,
+    onClearDismissal: () => noopUnsubscribe
+  }
+}
+
+function createShellApi(): NonNullable<Partial<PreloadApi>['shell']> {
+  return {
+    openPath: (path) =>
+      Promise.resolve(window.open(path, '_blank', 'noopener,noreferrer') as never),
+    openUrl: (url) => Promise.resolve(window.open(url, '_blank', 'noopener,noreferrer') as never),
+    openFilePath: () => Promise.resolve(),
+    openFileUri: (uri) =>
+      Promise.resolve(window.open(uri, '_blank', 'noopener,noreferrer') as never),
+    pathExists: async (path) => {
+      try {
+        await resolveRuntimeFilePath(path)
+        return true
+      } catch {
+        return false
+      }
+    },
+    pickAttachment: () => Promise.resolve(null),
+    pickImage: () => Promise.resolve(null),
+    pickAudio: () => Promise.resolve(null),
+    pickDirectory: () => Promise.resolve(null),
+    copyFile: () => Promise.resolve()
+  }
+}
+
+function createPtyApi(): NonNullable<Partial<PreloadApi>['pty']> {
+  return {
+    spawn: () => Promise.reject(new Error('Local PTYs are unavailable in the web client.')),
+    write: () => {},
+    resize: () => {},
+    reportGeometry: () => {},
+    signal: () => {},
+    kill: () => Promise.resolve(),
+    ackColdRestore: () => {},
+    hasChildProcesses: () => Promise.resolve(false),
+    getForegroundProcess: () => Promise.resolve(null),
+    getCwd: () => Promise.resolve('~'),
+    listSessions: () => Promise.resolve([]),
+    onData: () => noopUnsubscribe,
+    onReplay: () => noopUnsubscribe,
+    onExit: () => noopUnsubscribe,
+    onSerializeBufferRequest: () => noopUnsubscribe,
+    onClearBufferRequest: () => noopUnsubscribe,
+    sendSerializedBuffer: () => {},
+    declarePendingPaneSerializer: () => Promise.resolve(0),
+    settlePaneSerializer: () => Promise.resolve(),
+    clearPendingPaneSerializer: () => Promise.resolve(),
+    management: {
+      listSessions: () => Promise.resolve({ sessions: [] }),
+      killAll: () => Promise.resolve({ killedCount: 0, remainingCount: 0 }),
+      killOne: () => Promise.resolve({ success: false }),
+      restart: () => Promise.resolve({ success: false })
+    }
+  }
+}
+
+function createSshApi(): NonNullable<Partial<PreloadApi>['ssh']> {
+  return {
+    listTargets: () => Promise.resolve([]),
+    addTarget: () =>
+      Promise.reject(new Error('SSH target management is unavailable in the web client.')),
+    updateTarget: () =>
+      Promise.reject(new Error('SSH target management is unavailable in the web client.')),
+    removeTarget: () => Promise.resolve(),
+    importConfig: () => Promise.resolve([]),
+    connect: () => Promise.resolve(null),
+    disconnect: () => Promise.resolve(),
+    terminateSessions: () => Promise.resolve(),
+    getState: () => Promise.resolve(null),
+    needsPassphrasePrompt: () => Promise.resolve(false),
+    testConnection: () =>
+      Promise.resolve({ success: false, error: 'Unavailable in the web client.' }),
+    onStateChanged: () => noopUnsubscribe,
+    addPortForward: () =>
+      Promise.reject(new Error('SSH port forwarding is unavailable in the web client.')),
+    updatePortForward: () =>
+      Promise.reject(new Error('SSH port forwarding is unavailable in the web client.')),
+    removePortForward: () => Promise.resolve(null),
+    listPortForwards: () => Promise.resolve([]),
+    listDetectedPorts: () => Promise.resolve([]),
+    onPortForwardsChanged: () => noopUnsubscribe,
+    onDetectedPortsChanged: () => noopUnsubscribe,
+    browseDir: () => Promise.resolve({ entries: [], resolvedPath: '' }),
+    onCredentialRequest: () => noopUnsubscribe,
+    onCredentialResolved: () => noopUnsubscribe,
+    submitCredential: () => Promise.resolve()
+  }
+}
+
+async function callRuntimeEnvelope<TResult = unknown>(
+  method: string,
+  params?: unknown,
+  timeoutMs?: number
+): Promise<RuntimeRpcResponse<TResult>> {
+  const environment = requireActiveEnvironment()
+  const response = await getClientForEnvironment(environment).call(method, params, { timeoutMs })
+  updateEnvironmentFromResponse(environment, response)
+  return response as RuntimeRpcResponse<TResult>
+}
+
+async function callEnvironmentEnvelope<TResult = unknown>(
+  selector: string,
+  method: string,
+  params?: unknown,
+  timeoutMs?: number
+): Promise<RuntimeRpcResponse<TResult>> {
+  const environment = resolveEnvironment(selector)
+  const response = await getClientForEnvironment(environment).call(method, params, { timeoutMs })
+  updateEnvironmentFromResponse(environment, response)
+  return response as RuntimeRpcResponse<TResult>
+}
+
+async function callRuntimeResult<TResult>(
+  method: string,
+  params?: unknown,
+  timeoutMs?: number
+): Promise<TResult> {
+  const response = await callRuntimeEnvelope(method, params, timeoutMs)
+  if (!response.ok) {
+    throw new Error(response.error.message)
+  }
+  return response.result as TResult
+}
+
+async function getRemoteRuntimeStatus(): Promise<RuntimeStatus> {
+  return callRuntimeResult<RuntimeStatus>('status.get', undefined, 15_000)
+}
+
+function getClientForEnvironment(environment: StoredWebRuntimeEnvironment): WebRuntimeClient {
+  if (!activeClient || activeClientEnvironmentId !== environment.id) {
+    activeClient?.close()
+    activeClient = new WebRuntimeClient(getPreferredWebPairingOffer(environment))
+    activeClientEnvironmentId = environment.id
+  }
+  return activeClient
+}
+
+function closeActiveRuntimeClients(): void {
+  activeClient?.close()
+  activeClient = null
+  activeClientEnvironmentId = null
+  cachedWorktrees = null
+}
+
+function disconnectActiveRuntimeEnvironment(): void {
+  closeActiveRuntimeClients()
+  clearStoredWebRuntimeEnvironment()
+  activeEnvironment = null
+}
+
+function resolveEnvironment(selector: string): StoredWebRuntimeEnvironment {
+  const environment = requireActiveEnvironment()
+  if (selector === environment.id || selector === environment.name || selector === 'active') {
+    return environment
+  }
+  throw new Error(`Unknown Orca runtime environment: ${selector}`)
+}
+
+function requireActiveEnvironment(): StoredWebRuntimeEnvironment {
+  activeEnvironment = activeEnvironment ?? readStoredWebRuntimeEnvironment()
+  if (!activeEnvironment) {
+    throw new Error('Pair this web client with an Orca server first.')
+  }
+  return activeEnvironment
+}
+
+function requireActiveEnvironmentOrNull(): StoredWebRuntimeEnvironment | null {
+  activeEnvironment = activeEnvironment ?? readStoredWebRuntimeEnvironment()
+  return activeEnvironment
+}
+
+function updateEnvironmentFromResponse(
+  environment: StoredWebRuntimeEnvironment,
+  response: RuntimeRpcResponse<unknown>
+): void {
+  const runtimeId = response.ok ? response._meta.runtimeId : (response._meta?.runtimeId ?? null)
+  activeEnvironment = updateStoredEnvironmentRuntimeId(environment, runtimeId)
+}
+
+function getStoredSettings(): GlobalSettings {
+  const environment = (activeEnvironment = activeEnvironment ?? readStoredWebRuntimeEnvironment())
+  const defaults = getDefaultSettings('~')
+  const stored = readJson<Partial<GlobalSettings>>(SETTINGS_STORAGE_KEY, {})
+  return mergeSettings(
+    {
+      ...defaults,
+      floatingTerminalEnabled: false,
+      rightSidebarOpenByDefault: false,
+      activeRuntimeEnvironmentId: environment?.id ?? null
+    },
+    stored
+  )
+}
+
+function getStoredOnboarding(): OnboardingState {
+  const storedRaw = window.localStorage.getItem(ONBOARDING_STORAGE_KEY)
+  if (storedRaw) {
+    const stored = readJson(ONBOARDING_STORAGE_KEY, getDefaultOnboardingState())
+    if (stored.checklist.dismissed) {
+      return stored
+    }
+    const closed = closeWebOnboarding(stored)
+    writeJson(ONBOARDING_STORAGE_KEY, closed)
+    return closed
+  }
+  const closed = closeWebOnboarding(getDefaultOnboardingState())
+  // Why: pairing already means the user has an Orca server. Desktop first-run
+  // onboarding would incorrectly probe browser-local tools and block the client.
+  writeJson(ONBOARDING_STORAGE_KEY, closed)
+  return closed
+}
+
+function closeWebOnboarding(base: OnboardingState): OnboardingState {
+  return {
+    ...base,
+    closedAt: Date.now(),
+    outcome: 'dismissed',
+    checklist: {
+      ...base.checklist,
+      dismissed: true
+    }
+  }
+}
+
+function mergeSettings(base: GlobalSettings, updates: Partial<GlobalSettings>): GlobalSettings {
+  const defaults = getDefaultSettings('~')
+  return {
+    ...base,
+    ...updates,
+    notifications: {
+      ...base.notifications,
+      ...updates.notifications
+    },
+    githubProjects: {
+      ...(base.githubProjects ?? defaults.githubProjects),
+      ...updates.githubProjects
+    } as GlobalSettings['githubProjects'],
+    voice: {
+      ...(base.voice ?? defaults.voice),
+      ...updates.voice
+    } as NonNullable<GlobalSettings['voice']>,
+    activeRuntimeEnvironmentId: activeEnvironment?.id ?? updates.activeRuntimeEnvironmentId ?? null
+  }
+}
+
+async function listAllRuntimeWorktrees(): Promise<Worktree[]> {
+  if (cachedWorktrees && Date.now() - cachedWorktrees.loadedAt < 5_000) {
+    return cachedWorktrees.worktrees
+  }
+  const result = await callRuntimeResult<{ worktrees: Worktree[] }>('worktree.list', {})
+  cachedWorktrees = { loadedAt: Date.now(), worktrees: result.worktrees }
+  return result.worktrees
+}
+
+async function resolveRuntimeWorktreeByPath(worktreePath: string): Promise<Worktree> {
+  const worktrees = await listAllRuntimeWorktrees()
+  const match = worktrees
+    .map((worktree) => ({
+      worktree,
+      relativePath: relativePathInsideRoot(worktree.path, worktreePath)
+    }))
+    .filter((entry) => entry.relativePath !== null)
+    .sort((a, b) => b.worktree.path.length - a.worktree.path.length)[0]
+  if (!match) {
+    throw new Error(`No runtime worktree owns ${worktreePath}`)
+  }
+  return match.worktree
+}
+
+async function resolveRuntimeFilePath(
+  filePath: string,
+  preferredWorktreePath?: string
+): Promise<{ worktree: Worktree; relativePath: string }> {
+  const worktree = preferredWorktreePath
+    ? await resolveRuntimeWorktreeByPath(preferredWorktreePath)
+    : await resolveRuntimeWorktreeByPath(filePath)
+  const relativePath = relativePathInsideRoot(worktree.path, filePath)
+  if (relativePath === null) {
+    throw new Error(`File is outside runtime worktree: ${filePath}`)
+  }
+  return { worktree, relativePath }
+}
+
+async function mutateGitPath(
+  method: string,
+  worktreePath: string,
+  filePath: string
+): Promise<void> {
+  const file = await resolveRuntimeFilePath(filePath, worktreePath)
+  await callRuntimeResult(method, { worktree: file.worktree.id, filePath: file.relativePath })
+}
+
+async function mutateGitPaths(
+  method: string,
+  worktreePath: string,
+  filePaths: string[]
+): Promise<void> {
+  const worktree = await resolveRuntimeWorktreeByPath(worktreePath)
+  await callRuntimeResult(method, { worktree: worktree.id, filePaths })
+}
+
+function mapRepoPathArg(args: unknown): unknown {
+  if (!args || typeof args !== 'object' || !('repoPath' in args)) {
+    return args
+  }
+  const record = args as Record<string, unknown>
+  return {
+    ...record,
+    repo: record.repoPath
+  }
+}
+
+function createEmptyMemorySnapshot(): MemorySnapshot {
+  const emptyUsage = { cpu: 0, memory: 0 }
+  return {
+    app: { ...emptyUsage, main: emptyUsage, renderer: emptyUsage, other: emptyUsage, history: [] },
+    worktrees: [],
+    host: {
+      totalMemory: 0,
+      freeMemory: 0,
+      usedMemory: 0,
+      memoryUsagePercent: 0,
+      cpuCoreCount: navigator.hardwareConcurrency || 1,
+      loadAverage1m: 0
+    },
+    totalCpu: 0,
+    totalMemory: 0,
+    collectedAt: Date.now()
+  }
+}
+
+function getBrowserPlatform(): NodeJS.Platform {
+  if (navigator.userAgent.includes('Windows')) {
+    return 'win32'
+  }
+  if (navigator.userAgent.includes('Linux')) {
+    return 'linux'
+  }
+  return 'darwin'
+}
+
+function readJson<T>(key: string, fallback: T): T {
+  const raw = window.localStorage.getItem(key)
+  if (!raw) {
+    return cloneJson(fallback)
+  }
+  try {
+    return { ...cloneJson(fallback), ...JSON.parse(raw) } as T
+  } catch {
+    return cloneJson(fallback)
+  }
+}
+
+function writeJson<T>(key: string, value: T): void {
+  window.localStorage.setItem(key, JSON.stringify(value))
+}
+
+function cloneJson<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}
+
+function withFallback<T extends object>(target: T, path: string[]): T {
+  return new Proxy(target, {
+    get(current, property, receiver) {
+      if (property in current) {
+        const value = Reflect.get(current, property, receiver) as unknown
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+          return withFallback(value as object, [...path, String(property)])
+        }
+        return value
+      }
+      return createFallbackProxy([...path, String(property)])
+    }
+  })
+}
+
+function createFallbackProxy(
+  path: string[],
+  applyOverride?: (path: string[], args: unknown[]) => unknown
+): never {
+  const fn = () => undefined
+  return new Proxy(fn, {
+    get(_target, property) {
+      if (property === 'then') {
+        return undefined
+      }
+      return createFallbackProxy([...path, String(property)], applyOverride)
+    },
+    apply(_target, _thisArg, args) {
+      if (applyOverride) {
+        return applyOverride(path, args)
+      }
+      return getFallbackResult(path, args)
+    }
+  }) as never
+}
+
+function getFallbackResult(path: string[], args: unknown[]): unknown {
+  const name = path.at(-1) ?? ''
+  if (name.startsWith('on')) {
+    return noopUnsubscribe
+  }
+  if (name.startsWith('is') || name.startsWith('has') || name === 'pathExists') {
+    return Promise.resolve(false)
+  }
+  if (name.startsWith('list') || name.startsWith('detect')) {
+    return Promise.resolve([])
+  }
+  if (name.startsWith('preview')) {
+    return Promise.resolve({ found: false, diff: {}, unsupportedKeys: [] })
+  }
+  if (name.startsWith('get') && name.endsWith('Status')) {
+    return Promise.resolve([])
+  }
+  if (name === 'write' || name === 'resize' || name === 'reportGeometry') {
+    return undefined
+  }
+  if (args.length === 0 && (name === 'getZoomLevel' || name === 'declarePendingPaneSerializer')) {
+    return 0
+  }
+  return Promise.resolve(undefined)
+}
+
+function noopUnsubscribe(): void {}
diff --git a/src/renderer/src/web/web-runtime-client.test.ts b/src/renderer/src/web/web-runtime-client.test.ts
new file mode 100644
index 00000000000..58e1a2f3d60
--- /dev/null
+++ b/src/renderer/src/web/web-runtime-client.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from 'vitest'
+import { WebRuntimeClient } from './web-runtime-client'
+
+class FakeWebSocket {
+  static readonly CONNECTING = 0
+  static readonly OPEN = 1
+  readonly readyState = FakeWebSocket.CONNECTING
+  binaryType = 'arraybuffer'
+  close = vi.fn()
+  send = vi.fn()
+
+  constructor(readonly _url: string) {}
+}
+
+describe('WebRuntimeClient', () => {
+  beforeEach(() => {
+    vi.stubGlobal('window', {
+      setTimeout,
+      clearTimeout,
+      atob: (value: string) => Buffer.from(value, 'base64').toString('binary')
+    })
+    vi.stubGlobal('WebSocket', FakeWebSocket)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('closes child subscription clients when the owning client closes', () => {
+    const client = new WebRuntimeClient({
+      v: 2,
+      endpoint: 'ws://127.0.0.1:6768',
+      deviceToken: 'token',
+      publicKeyB64: Buffer.alloc(32).toString('base64')
+    })
+    const child = { close: vi.fn() }
+
+    ;(
+      client as unknown as {
+        childClients: Set<{ close: () => void }>
+      }
+    ).childClients.add(child)
+
+    client.close()
+
+    expect(child.close).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/renderer/src/web/web-runtime-client.ts b/src/renderer/src/web/web-runtime-client.ts
new file mode 100644
index 00000000000..93e48598fe0
--- /dev/null
+++ b/src/renderer/src/web/web-runtime-client.ts
@@ -0,0 +1,548 @@
+/* eslint-disable max-lines -- Why: this browser runtime client owns the E2EE
+   WebSocket state machine, JSON-RPC request routing, streaming callbacks, and
+   binary frame forwarding as one transport boundary. */
+import type { RuntimeRpcResponse } from '../../../shared/runtime-rpc-envelope'
+import { isKeepaliveFrame } from '../../../shared/runtime-rpc-envelope'
+import type { WebPairingOffer } from './web-pairing'
+import {
+  decrypt,
+  decryptBytes,
+  deriveSharedKey,
+  encrypt,
+  encryptBytes,
+  generateKeyPair,
+  publicKeyFromBase64,
+  publicKeyToBase64
+} from './web-e2ee'
+
+type WebRuntimeConnectionState =
+  | 'disconnected'
+  | 'connecting'
+  | 'handshaking'
+  | 'connected'
+  | 'auth-failed'
+
+type PendingRequest = {
+  method: string
+  resolve: (response: RuntimeRpcResponse<unknown>) => void
+  reject: (error: Error) => void
+  timeout: number
+}
+
+type SubscriptionCallbacks = {
+  onResponse: (response: RuntimeRpcResponse<unknown>) => void
+  onBinary?: (bytes: Uint8Array<ArrayBufferLike>) => void
+  onError?: (error: { code: string; message: string }) => void
+  onClose?: () => void
+}
+
+type RuntimeSubscription = {
+  method: string
+  params: unknown
+  callbacks: SubscriptionCallbacks
+}
+
+export type WebRuntimeSubscriptionHandle = {
+  unsubscribe: () => void
+  sendBinary: (bytes: Uint8Array<ArrayBufferLike>) => void
+}
+
+const REQUEST_TIMEOUT_MS = 30_000
+const CONNECT_TIMEOUT_MS = 12_000
+const HANDSHAKE_TIMEOUT_MS = 10_000
+const RECONNECT_DELAYS_MS = [500, 1000, 2000, 4000, 8000, 15_000]
+
+export class WebRuntimeClient {
+  private ws: WebSocket | null = null
+  private sharedKey: Uint8Array | null = null
+  private state: WebRuntimeConnectionState = 'disconnected'
+  private requestCounter = 0
+  private reconnectAttempt = 0
+  private intentionallyClosed = false
+  private connectTimer: number | null = null
+  private handshakeTimer: number | null = null
+  private reconnectTimer: number | null = null
+  private readonly pending = new Map<string, PendingRequest>()
+  private readonly subscriptions = new Map<string, RuntimeSubscription>()
+  private readonly childClients = new Set<WebRuntimeClient>()
+  private readonly waiters: { resolve: () => void; reject: (error: Error) => void }[] = []
+  private readonly serverPublicKey: Uint8Array
+
+  constructor(private readonly pairing: WebPairingOffer) {
+    this.serverPublicKey = publicKeyFromBase64(pairing.publicKeyB64)
+    this.openConnection()
+  }
+
+  async call(
+    method: string,
+    params?: unknown,
+    options?: { timeoutMs?: number }
+  ): Promise<RuntimeRpcResponse<unknown>> {
+    await this.waitForConnected(options?.timeoutMs)
+    return new Promise((resolve, reject) => {
+      const id = this.nextId()
+      const timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS
+      const timeout = window.setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`Request timed out: ${method}`))
+      }, timeoutMs)
+      this.pending.set(id, { method, resolve, reject, timeout })
+      if (!this.sendEncrypted({ id, deviceToken: this.pairing.deviceToken, method, params })) {
+        this.pending.delete(id)
+        window.clearTimeout(timeout)
+        reject(new Error('Remote Orca runtime is not connected.'))
+      }
+    })
+  }
+
+  async subscribe(
+    method: string,
+    params: unknown,
+    callbacks: SubscriptionCallbacks,
+    options?: { timeoutMs?: number }
+  ): Promise<WebRuntimeSubscriptionHandle> {
+    const client = new WebRuntimeClient(this.pairing)
+    this.childClients.add(client)
+    const closeChild = (): void => {
+      this.childClients.delete(client)
+      client.close()
+    }
+    try {
+      const wrappedCallbacks: SubscriptionCallbacks = {
+        ...callbacks,
+        onError: (error) => {
+          callbacks.onError?.(error)
+          closeChild()
+        },
+        onClose: () => {
+          callbacks.onClose?.()
+          closeChild()
+        }
+      }
+      const handle = await client.subscribeOnCurrentConnection(
+        method,
+        params,
+        wrappedCallbacks,
+        options
+      )
+      return {
+        unsubscribe: () => {
+          handle.unsubscribe()
+          closeChild()
+        },
+        sendBinary: (bytes) => handle.sendBinary(bytes)
+      }
+    } catch (error) {
+      closeChild()
+      throw error
+    }
+  }
+
+  private async subscribeOnCurrentConnection(
+    method: string,
+    params: unknown,
+    callbacks: SubscriptionCallbacks,
+    options?: { timeoutMs?: number }
+  ): Promise<WebRuntimeSubscriptionHandle> {
+    await this.waitForConnected(options?.timeoutMs)
+    const id = this.nextId()
+    this.subscriptions.set(id, { method, params, callbacks })
+    if (!this.sendEncrypted({ id, deviceToken: this.pairing.deviceToken, method, params })) {
+      this.subscriptions.delete(id)
+      throw new Error('Remote Orca runtime is not connected.')
+    }
+    return {
+      unsubscribe: () => {
+        this.subscriptions.delete(id)
+      },
+      sendBinary: (bytes) => {
+        this.sendEncryptedBinary(bytes)
+      }
+    }
+  }
+
+  close(): void {
+    this.intentionallyClosed = true
+    for (const child of Array.from(this.childClients)) {
+      child.close()
+    }
+    this.childClients.clear()
+    this.clearTimers()
+    this.rejectAllPending('Remote Orca runtime connection closed.')
+    this.notifySubscriptionsClosed()
+    if (this.ws) {
+      this.ws.close()
+      this.ws = null
+    }
+    this.sharedKey = null
+    this.setState('disconnected')
+  }
+
+  private openConnection(): void {
+    if (this.intentionallyClosed) {
+      return
+    }
+    let ws: WebSocket
+    try {
+      ws = new WebSocket(this.pairing.endpoint)
+    } catch (error) {
+      this.rejectAllPending(error instanceof Error ? error.message : String(error))
+      this.scheduleReconnect()
+      return
+    }
+
+    ws.binaryType = 'arraybuffer'
+    this.ws = ws
+    this.sharedKey = null
+    this.setState('connecting')
+
+    this.connectTimer = window.setTimeout(() => {
+      if (this.ws === ws && ws.readyState === WebSocket.CONNECTING) {
+        ws.close()
+        this.handleSocketClosed(ws)
+      }
+    }, CONNECT_TIMEOUT_MS)
+
+    ws.onopen = () => {
+      if (this.ws !== ws) {
+        return
+      }
+      this.clearConnectTimer()
+      this.setState('handshaking')
+      const keyPair = generateKeyPair()
+      this.sharedKey = deriveSharedKey(keyPair.secretKey, this.serverPublicKey)
+      ws.send(
+        JSON.stringify({
+          type: 'e2ee_hello',
+          publicKeyB64: publicKeyToBase64(keyPair.publicKey)
+        })
+      )
+      this.handshakeTimer = window.setTimeout(() => {
+        if (this.ws === ws && this.state === 'handshaking') {
+          ws.close()
+        }
+      }, HANDSHAKE_TIMEOUT_MS)
+    }
+
+    ws.onmessage = (event) => {
+      void this.handleSocketMessage(event.data)
+    }
+
+    ws.onclose = () => this.handleSocketClosed(ws)
+    ws.onerror = () => {
+      if (this.state === 'connecting') {
+        this.rejectAllWaiters(new Error('Could not connect to the remote Orca runtime.'))
+      }
+    }
+  }
+
+  private async handleSocketMessage(rawData: unknown): Promise<void> {
+    const raw = typeof rawData === 'string' ? rawData : null
+    if (this.state === 'handshaking') {
+      if (raw === null || !this.sharedKey) {
+        return
+      }
+      try {
+        const control = JSON.parse(raw) as { type?: unknown }
+        if (control.type === 'e2ee_ready') {
+          this.sendEncrypted({ type: 'e2ee_auth', deviceToken: this.pairing.deviceToken })
+          return
+        }
+      } catch {
+        // The authenticated control frame is encrypted, so non-JSON is normal here.
+      }
+
+      const plaintext = decrypt(raw, this.sharedKey)
+      if (plaintext === null) {
+        return
+      }
+      try {
+        const control = JSON.parse(plaintext) as {
+          type?: unknown
+          error?: { code?: string; message?: string }
+        }
+        if (control.type === 'e2ee_authenticated') {
+          this.clearHandshakeTimer()
+          this.reconnectAttempt = 0
+          this.setState('connected')
+        } else if (control.type === 'e2ee_error' || control.error?.code === 'unauthorized') {
+          this.intentionallyClosed = true
+          this.setState('auth-failed')
+          this.rejectAllPending('Unauthorized. Pair this web client again.')
+          this.notifySubscriptionsError('unauthorized', 'Unauthorized. Pair this web client again.')
+          this.ws?.close()
+        }
+      } catch {
+        // Ignore malformed handshake payloads; the server will close on timeout.
+      }
+      return
+    }
+
+    if (this.state !== 'connected' || !this.sharedKey) {
+      return
+    }
+
+    if (raw === null) {
+      const encrypted = await websocketPayloadToUint8(rawData)
+      if (!encrypted) {
+        return
+      }
+      const plaintext = decryptBytes(encrypted, this.sharedKey)
+      if (!plaintext) {
+        return
+      }
+      for (const subscription of this.subscriptions.values()) {
+        subscription.callbacks.onBinary?.(plaintext)
+      }
+      return
+    }
+
+    const plaintext = decrypt(raw, this.sharedKey)
+    if (plaintext === null) {
+      return
+    }
+
+    let response: RuntimeRpcResponse<unknown> | Record<string, unknown>
+    try {
+      response = JSON.parse(plaintext) as RuntimeRpcResponse<unknown> | Record<string, unknown>
+    } catch {
+      return
+    }
+    if (isKeepaliveFrame(response)) {
+      return
+    }
+    if (!('id' in response) || typeof response.id !== 'string') {
+      return
+    }
+    if (isRuntimeFailureResponse(response) && response.error.code === 'unauthorized') {
+      this.intentionallyClosed = true
+      this.setState('auth-failed')
+      this.rejectAllPending('Unauthorized. Pair this web client again.')
+      this.notifySubscriptionsError('unauthorized', 'Unauthorized. Pair this web client again.')
+      this.ws?.close()
+      return
+    }
+
+    const subscription = this.subscriptions.get(response.id)
+    if (subscription && isSubscriptionResponse(response)) {
+      subscription.callbacks.onResponse(response)
+      if (response.ok && isEndResult(response.result)) {
+        this.subscriptions.delete(response.id)
+        subscription.callbacks.onClose?.()
+      }
+      return
+    }
+
+    const pending = this.pending.get(response.id)
+    if (!pending) {
+      return
+    }
+    this.pending.delete(response.id)
+    window.clearTimeout(pending.timeout)
+    pending.resolve(response as RuntimeRpcResponse<unknown>)
+  }
+
+  private sendEncrypted(message: unknown): boolean {
+    const ws = this.ws
+    if (!ws || ws.readyState !== WebSocket.OPEN || !this.sharedKey) {
+      return false
+    }
+    ws.send(encrypt(JSON.stringify(message), this.sharedKey))
+    return true
+  }
+
+  private sendEncryptedBinary(bytes: Uint8Array<ArrayBufferLike>): boolean {
+    const ws = this.ws
+    if (!ws || ws.readyState !== WebSocket.OPEN || !this.sharedKey) {
+      return false
+    }
+    ws.send(encryptBytes(bytes, this.sharedKey))
+    return true
+  }
+
+  private waitForConnected(timeoutMs = REQUEST_TIMEOUT_MS): Promise<void> {
+    if (this.state === 'connected') {
+      return Promise.resolve()
+    }
+    if (this.state === 'auth-failed') {
+      return Promise.reject(new Error('Unauthorized. Pair this web client again.'))
+    }
+    if (this.intentionallyClosed) {
+      return Promise.reject(new Error('Remote Orca runtime connection closed.'))
+    }
+    return new Promise((resolve, reject) => {
+      const timeout = window.setTimeout(() => {
+        const index = this.waiters.findIndex((waiter) => waiter.resolve === resolve)
+        if (index !== -1) {
+          this.waiters.splice(index, 1)
+        }
+        reject(new Error('Timed out while connecting to the remote Orca runtime.'))
+      }, timeoutMs)
+      this.waiters.push({
+        resolve: () => {
+          window.clearTimeout(timeout)
+          resolve()
+        },
+        reject: (error) => {
+          window.clearTimeout(timeout)
+          reject(error)
+        }
+      })
+    })
+  }
+
+  private handleSocketClosed(closedWs: WebSocket): void {
+    if (this.ws !== closedWs) {
+      return
+    }
+    this.ws = null
+    this.sharedKey = null
+    this.clearConnectTimer()
+    this.clearHandshakeTimer()
+    this.rejectAllPending('Remote Orca runtime connection interrupted.')
+    this.notifySubscriptionsClosed()
+    if (this.intentionallyClosed || this.state === 'auth-failed') {
+      this.setState(this.state === 'auth-failed' ? 'auth-failed' : 'disconnected')
+      return
+    }
+    this.setState('disconnected')
+    this.scheduleReconnect()
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer || this.intentionallyClosed) {
+      return
+    }
+    const delay =
+      RECONNECT_DELAYS_MS[Math.min(this.reconnectAttempt, RECONNECT_DELAYS_MS.length - 1)]
+    this.reconnectAttempt += 1
+    this.reconnectTimer = window.setTimeout(() => {
+      this.reconnectTimer = null
+      this.openConnection()
+    }, delay)
+  }
+
+  private setState(next: WebRuntimeConnectionState): void {
+    this.state = next
+    if (next === 'connected') {
+      for (const waiter of this.waiters.splice(0)) {
+        waiter.resolve()
+      }
+    } else if (next === 'auth-failed') {
+      this.rejectAllWaiters(new Error('Unauthorized. Pair this web client again.'))
+    }
+  }
+
+  private nextId(): string {
+    this.requestCounter += 1
+    return `web-rpc-${this.requestCounter}-${Date.now()}`
+  }
+
+  private rejectAllPending(reason: string): void {
+    const error = new Error(reason)
+    for (const [id, pending] of this.pending) {
+      this.pending.delete(id)
+      window.clearTimeout(pending.timeout)
+      pending.reject(error)
+    }
+  }
+
+  private rejectAllWaiters(error: Error): void {
+    for (const waiter of this.waiters.splice(0)) {
+      waiter.reject(error)
+    }
+  }
+
+  private notifySubscriptionsClosed(): void {
+    const subscriptions = Array.from(this.subscriptions.values())
+    this.subscriptions.clear()
+    for (const subscription of subscriptions) {
+      subscription.callbacks.onClose?.()
+    }
+  }
+
+  private notifySubscriptionsError(code: string, message: string): void {
+    const subscriptions = Array.from(this.subscriptions.values())
+    this.subscriptions.clear()
+    for (const subscription of subscriptions) {
+      subscription.callbacks.onError?.({ code, message })
+    }
+  }
+
+  private clearTimers(): void {
+    this.clearConnectTimer()
+    this.clearHandshakeTimer()
+    if (this.reconnectTimer) {
+      window.clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+  }
+
+  private clearConnectTimer(): void {
+    if (this.connectTimer) {
+      window.clearTimeout(this.connectTimer)
+      this.connectTimer = null
+    }
+  }
+
+  private clearHandshakeTimer(): void {
+    if (this.handshakeTimer) {
+      window.clearTimeout(this.handshakeTimer)
+      this.handshakeTimer = null
+    }
+  }
+}
+
+function isSubscriptionResponse(
+  response: RuntimeRpcResponse<unknown> | Record<string, unknown>
+): response is RuntimeRpcResponse<unknown> {
+  if (!('ok' in response)) {
+    return false
+  }
+  if (response.ok === false) {
+    return true
+  }
+  if (response.ok === false) {
+    return true
+  }
+  const success = response as RuntimeRpcResponse<unknown> & { ok: true; streaming?: true }
+  return (
+    success.streaming === true || isEndResult(success.result) || isScrollbackResult(success.result)
+  )
+}
+
+function isRuntimeFailureResponse(
+  response: RuntimeRpcResponse<unknown> | Record<string, unknown>
+): response is RuntimeRpcResponse<unknown> & { ok: false } {
+  return (
+    'ok' in response &&
+    response.ok === false &&
+    'error' in response &&
+    !!response.error &&
+    typeof response.error === 'object' &&
+    'code' in response.error
+  )
+}
+
+function isEndResult(value: unknown): value is { type: 'end' } {
+  return !!value && typeof value === 'object' && (value as { type?: unknown }).type === 'end'
+}
+
+function isScrollbackResult(value: unknown): value is { type: 'scrollback' } {
+  return !!value && typeof value === 'object' && (value as { type?: unknown }).type === 'scrollback'
+}
+
+async function websocketPayloadToUint8(
+  value: unknown
+): Promise<Uint8Array<ArrayBufferLike> | null> {
+  if (value instanceof Uint8Array) {
+    return value
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value)
+  }
+  if (value instanceof Blob) {
+    return new Uint8Array(await value.arrayBuffer())
+  }
+  return null
+}
diff --git a/src/renderer/src/web/web-runtime-environment.ts b/src/renderer/src/web/web-runtime-environment.ts
new file mode 100644
index 00000000000..57769a1a623
--- /dev/null
+++ b/src/renderer/src/web/web-runtime-environment.ts
@@ -0,0 +1,115 @@
+import type { PublicKnownRuntimeEnvironment } from '../../../shared/runtime-environments'
+import type { WebPairingOffer } from './web-pairing'
+import { createBrowserUuid } from '@/lib/browser-uuid'
+
+export type StoredWebRuntimeEnvironment = Omit<PublicKnownRuntimeEnvironment, 'endpoints'> & {
+  endpoints: {
+    id: string
+    kind: 'websocket'
+    label: string
+    endpoint: string
+    deviceToken: string
+    publicKeyB64: string
+  }[]
+}
+
+const ENVIRONMENT_STORAGE_KEY = 'orca.web.runtimeEnvironment.v1'
+
+export function readStoredWebRuntimeEnvironment(): StoredWebRuntimeEnvironment | null {
+  const raw = window.localStorage.getItem(ENVIRONMENT_STORAGE_KEY)
+  if (!raw) {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(raw) as StoredWebRuntimeEnvironment
+    if (!parsed.id || !parsed.name || parsed.endpoints.length === 0) {
+      return null
+    }
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+export function saveStoredWebRuntimeEnvironment(environment: StoredWebRuntimeEnvironment): void {
+  window.localStorage.setItem(ENVIRONMENT_STORAGE_KEY, JSON.stringify(environment))
+}
+
+export function clearStoredWebRuntimeEnvironment(): void {
+  window.localStorage.removeItem(ENVIRONMENT_STORAGE_KEY)
+}
+
+export function createStoredWebRuntimeEnvironment(args: {
+  name: string
+  offer: WebPairingOffer
+}): StoredWebRuntimeEnvironment {
+  const id = `web-${createBrowserUuid()}`
+  const now = Date.now()
+  return {
+    id,
+    name: args.name.trim() || 'Orca Server',
+    createdAt: now,
+    updatedAt: now,
+    lastUsedAt: null,
+    runtimeId: null,
+    preferredEndpointId: `ws-${id}`,
+    endpoints: [
+      {
+        id: `ws-${id}`,
+        kind: 'websocket',
+        label: 'WebSocket',
+        endpoint: args.offer.endpoint,
+        deviceToken: args.offer.deviceToken,
+        publicKeyB64: args.offer.publicKeyB64
+      }
+    ]
+  }
+}
+
+export function redactStoredWebRuntimeEnvironment(
+  environment: StoredWebRuntimeEnvironment
+): PublicKnownRuntimeEnvironment {
+  return {
+    ...environment,
+    endpoints: environment.endpoints.map(
+      ({ deviceToken: _token, publicKeyB64: _key, ...rest }) => ({
+        ...rest
+      })
+    )
+  }
+}
+
+export function getPreferredWebPairingOffer(
+  environment: StoredWebRuntimeEnvironment
+): WebPairingOffer {
+  const endpoint =
+    environment.endpoints.find((entry) => entry.id === environment.preferredEndpointId) ??
+    environment.endpoints[0]
+  if (!endpoint) {
+    throw new Error('No runtime endpoint is stored for this web client.')
+  }
+  return {
+    v: 2,
+    endpoint: endpoint.endpoint,
+    deviceToken: endpoint.deviceToken,
+    publicKeyB64: endpoint.publicKeyB64
+  }
+}
+
+export function updateStoredEnvironmentRuntimeId(
+  environment: StoredWebRuntimeEnvironment,
+  runtimeId: string | null
+): StoredWebRuntimeEnvironment {
+  const next = {
+    ...environment,
+    runtimeId,
+    updatedAt: Date.now(),
+    lastUsedAt: Date.now()
+  }
+  saveStoredWebRuntimeEnvironment(next)
+  return next
+}
+
+export function isMixedContentWebSocket(endpoint: string): boolean {
+  return window.location.protocol === 'https:' && endpoint.startsWith('ws://')
+}
diff --git a/src/renderer/web-index.html b/src/renderer/web-index.html
new file mode 100644
index 00000000000..09fbbfa7682
--- /dev/null
+++ b/src/renderer/web-index.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
+    />
+    <title>Orca Web</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/web/main.tsx"></script>
+  </body>
+</html>
diff --git a/vite.web.config.ts b/vite.web.config.ts
new file mode 100644
index 00000000000..db107e10302
--- /dev/null
+++ b/vite.web.config.ts
@@ -0,0 +1,28 @@
+import { resolve } from 'path'
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  root: resolve('src/renderer'),
+  // Why: pairing URLs may live under a reverse-proxy path prefix like
+  // /orca/web-index.html, so built assets must resolve relative to the page.
+  base: './',
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@renderer': resolve('src/renderer/src'),
+      '@': resolve('src/renderer/src')
+    }
+  },
+  build: {
+    outDir: resolve('out/web'),
+    emptyOutDir: true,
+    rollupOptions: {
+      input: resolve('src/renderer/web-index.html')
+    }
+  },
+  worker: {
+    format: 'es'
+  }
+})

From 25102cb6d997487ecb69af7e7234663bfccb681e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 15 May 2026 10:51:57 +0000
Subject: [PATCH 34/82] release: v1.4.2-rc.8 [rc-slot:2026-05-15-03]

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

diff --git a/package.json b/package.json
index 18ce227e865..bd2cfa65bee 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.2-rc.7",
+  "version": "1.4.2-rc.8",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",

From 8cca091986dfd26316f40d4eb621516f4b3615d1 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 09:34:52 -0700
Subject: [PATCH 35/82] Refactor editor panel into focused modules (#1924)

* Squashed commits

- WIP: uncommitted changes before rebase

* fix: address review findings
---
 .../src/components/editor/EditorPanel.tsx     | 1468 ++---------------
 .../components/editor/EditorPanelHeader.tsx   |  312 ++++
 .../components/editor/EditorPanelShell.tsx    |  162 ++
 .../editor/editor-panel-content-types.ts      |   11 +
 .../editor-panel-export-pdf-listener.ts       |   23 +
 .../editor/editor-panel-file-mode.ts          |   14 +
 .../editor/editor-panel-render-model.ts       |  129 ++
 .../editor/useClosedEditorTabCleanup.ts       |   62 +
 .../editor/useEditorCmdSaveRequest.ts         |   50 +
 .../editor/useEditorPanelContentState.ts      |  289 ++++
 .../useEditorPanelExternalContentEvents.ts    |  132 ++
 .../editor/useEditorPanelFileLoadRetry.ts     |   80 +
 .../editor/useMarkdownPreviewShortcut.ts      |   80 +
 .../editor/useUntitledFileRename.ts           |  135 ++
 14 files changed, 1608 insertions(+), 1339 deletions(-)
 create mode 100644 src/renderer/src/components/editor/EditorPanelHeader.tsx
 create mode 100644 src/renderer/src/components/editor/EditorPanelShell.tsx
 create mode 100644 src/renderer/src/components/editor/editor-panel-content-types.ts
 create mode 100644 src/renderer/src/components/editor/editor-panel-export-pdf-listener.ts
 create mode 100644 src/renderer/src/components/editor/editor-panel-file-mode.ts
 create mode 100644 src/renderer/src/components/editor/editor-panel-render-model.ts
 create mode 100644 src/renderer/src/components/editor/useClosedEditorTabCleanup.ts
 create mode 100644 src/renderer/src/components/editor/useEditorCmdSaveRequest.ts
 create mode 100644 src/renderer/src/components/editor/useEditorPanelContentState.ts
 create mode 100644 src/renderer/src/components/editor/useEditorPanelExternalContentEvents.ts
 create mode 100644 src/renderer/src/components/editor/useEditorPanelFileLoadRetry.ts
 create mode 100644 src/renderer/src/components/editor/useMarkdownPreviewShortcut.ts
 create mode 100644 src/renderer/src/components/editor/useUntitledFileRename.ts

diff --git a/src/renderer/src/components/editor/EditorPanel.tsx b/src/renderer/src/components/editor/EditorPanel.tsx
index 3be4b61f5aa..86ad99428c2 100644
--- a/src/renderer/src/components/editor/EditorPanel.tsx
+++ b/src/renderer/src/components/editor/EditorPanel.tsx
@@ -1,185 +1,25 @@
-/* eslint-disable max-lines -- Why: EditorPanel still owns the visible editor
-save/load/render lifecycle for many modes (edit, diff, conflict review), and
-keeping that UI state together is easier to reason about than scattering it
-across multiple components. Autosave now lives in a smaller headless controller
-so hidden editor UI no longer participates in shutdown. */
-import React, { useCallback, useEffect, useRef, useState, Suspense } from 'react'
-import * as monaco from 'monaco-editor'
-import {
-  Columns2,
-  Copy,
-  Eye,
-  ExternalLink,
-  FileText,
-  ListTree,
-  MoreHorizontal,
-  Rows2
-} from 'lucide-react'
+import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { useAppStore } from '@/store'
-import { findWorktreeById } from '@/store/slices/worktree-helpers'
 import { getConnectionId } from '@/lib/connection-context'
 import { detectLanguage } from '@/lib/language-detect'
-import { canPreviewLanguage, openFilePreviewToSide } from '@/lib/file-preview'
-import { getEditorHeaderCopyState, getEditorHeaderOpenFileState } from './editor-header'
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuShortcut,
-  DropdownMenuTrigger
-} from '@/components/ui/dropdown-menu'
-import { CLOSE_ALL_CONTEXT_MENUS_EVENT } from '../tab-bar/SortableTab'
-import type { MarkdownViewMode, OpenFile } from '@/store/slices/editor'
-import EditorViewToggle, {
-  CSV_VIEW_MODE_METADATA,
-  NOTEBOOK_VIEW_MODE_METADATA
-} from './EditorViewToggle'
-import { EditorContent } from './EditorContent'
-import { scrollTopCache, cursorPositionCache, diffViewStateCache } from '@/lib/scroll-cache'
+import { openFilePreviewToSide } from '@/lib/file-preview'
+import { getEditorHeaderCopyState } from './editor-header'
 import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
-import type { GitDiffResult } from '../../../../shared/types'
-import {
-  getOpenFilesForExternalFileChange,
-  ORCA_EDITOR_FILE_SAVED_EVENT,
-  ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT,
-  requestEditorFileSave,
-  requestEditorSaveQuiesce,
-  ORCA_EDITOR_REQUEST_CMD_SAVE_EVENT,
-  type EditorFileSavedDetail,
-  type EditorPathMutationTarget
-} from './editor-autosave'
-import { UntitledFileRenameDialog } from './UntitledFileRenameDialog'
-import { exportActiveMarkdownToPdf } from './export-active-markdown'
-import {
-  canOpenMarkdownPreview,
-  getDefaultMarkdownViewMode,
-  getEditorToggleModes,
-  getMarkdownPreviewShortcutLabel,
-  getMarkdownViewModes,
-  isMarkdownPreviewShortcut
-} from './markdown-preview-controls'
-import type { EditorToggleValue } from './EditorViewToggle'
-import {
-  createRuntimePath,
-  getRuntimeFileReadScope,
-  readRuntimeFileContent,
-  renameRuntimePath,
-  runtimePathExists
-} from '@/runtime/runtime-file-client'
 import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
-import {
-  getRuntimeGitBranchDiff,
-  getRuntimeGitDiff,
-  getRuntimeGitScope
-} from '@/runtime/runtime-git-client'
+import { requestEditorFileSave } from './editor-autosave'
+import { exportActiveMarkdownToPdf } from './export-active-markdown'
+import type { EditorToggleValue } from './EditorViewToggle'
+import { EditorPanelShell } from './EditorPanelShell'
+import { acquireExportPdfListener } from './editor-panel-export-pdf-listener'
+import { canUseChangesModeForFile } from './editor-panel-file-mode'
+import { getEditorPanelRenderModel } from './editor-panel-render-model'
+import { useClosedEditorTabCleanup } from './useClosedEditorTabCleanup'
+import { useEditorCmdSaveRequest } from './useEditorCmdSaveRequest'
+import { useEditorPanelContentState } from './useEditorPanelContentState'
+import { useMarkdownPreviewShortcut } from './useMarkdownPreviewShortcut'
+import { useUntitledFileRename } from './useUntitledFileRename'
 
 const isMac = navigator.userAgent.includes('Mac')
-const isLinux = navigator.userAgent.includes('Linux')
-
-/** Platform-appropriate label: macOS → Finder, Windows → File Explorer, Linux → Files */
-const revealLabel = isMac
-  ? 'Reveal in Finder'
-  : isLinux
-    ? 'Open Containing Folder'
-    : 'Reveal in File Explorer'
-const markdownPreviewShortcutLabel = getMarkdownPreviewShortcutLabel(isMac)
-
-type FileContent = {
-  content: string
-  isBinary: boolean
-  isImage?: boolean
-  mimeType?: string
-  loadError?: string
-}
-
-type DiffContent = GitDiffResult
-const FILE_LOAD_RETRY_DELAYS_MS = [250, 1000, 2500]
-
-function shouldRetryFileLoadError(message: string): boolean {
-  const lower = message.toLowerCase()
-  return (
-    !lower.includes('access denied') &&
-    !lower.includes('enoent') &&
-    !lower.includes('no such file') &&
-    !lower.includes('file too large')
-  )
-}
-
-function isAbsolutePathLike(value: string): boolean {
-  return value.startsWith('/') || value.startsWith('\\\\') || /^[A-Za-z]:[\\/]/.test(value)
-}
-
-function canUseChangesModeForFile(file: OpenFile): boolean {
-  return (
-    file.mode === 'edit' &&
-    !file.isUntitled &&
-    file.relativePath !== file.filePath &&
-    !isAbsolutePathLike(file.relativePath)
-  )
-}
-
-// Why: split-pane layouts mount one EditorPanel per pane, and each panel
-// attaches its own listener to `ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT`.
-// Without coordination, a single external write fans out into N concurrent
-// `readFile` IPCs for the same path plus N independent `setContent`
-// transactions on the downstream rich editors — a meaningful contributor to
-// the black-window wedge reported in issue #826. Sharing a module-level
-// in-flight promise per (connectionId, filePath) collapses those N reads
-// into one round-trip while still letting each panel update its own local
-// state with the result.
-const inFlightFileReads = new Map<string, Promise<FileContent>>()
-const inFlightDiffReads = new Map<string, Promise<DiffContent>>()
-
-// Why: the "File → Export as PDF..." menu IPC fans out to every EditorPanel
-// instance, and split-pane layouts mount N panels concurrently. Without a
-// guard, a single menu click would spawn N concurrent exports — each racing
-// its own save dialog, toast, and printToPDF — producing duplicate output
-// files and confusing UX. This module-level ref-counted singleton installs
-// exactly one IPC subscription the first time any panel mounts, and tears
-// it down only when the last panel unmounts. A simple "first mounter wins"
-// counter would go dead if the first-mounting panel unmounted while others
-// were still mounted — survivors never re-subscribed and the menu silently
-// stopped working. The singleton pattern avoids that handoff bug entirely.
-let exportPdfListenerOwners = 0
-let exportPdfListenerUnsubscribe: (() => void) | null = null
-function acquireExportPdfListener(): () => void {
-  exportPdfListenerOwners += 1
-  if (exportPdfListenerOwners === 1) {
-    exportPdfListenerUnsubscribe = window.api.ui.onExportPdfRequested(() => {
-      void exportActiveMarkdownToPdf()
-    })
-  }
-  return () => {
-    exportPdfListenerOwners -= 1
-    if (exportPdfListenerOwners === 0 && exportPdfListenerUnsubscribe) {
-      exportPdfListenerUnsubscribe()
-      exportPdfListenerUnsubscribe = null
-    }
-  }
-}
-
-function inFlightReadKey(connectionId: string | undefined, filePath: string): string {
-  return `${connectionId ?? ''}::${filePath}`
-}
-
-function inFlightDiffKey(
-  file: OpenFile,
-  connectionId: string | undefined,
-  compareAgainstHead = false
-): string {
-  // Why: diff content depends on the file path AND which diff source is
-  // being rendered (unstaged/staged/branch). Branch diffs further depend
-  // on the base+head oids so switching compare points doesn't alias, and
-  // on branchOldPath so rename-detected diffs don't alias with the same
-  // post-rename path viewed without rename metadata.
-  const branch =
-    file.diffSource === 'branch' && file.branchCompare
-      ? `${file.branchCompare.baseOid ?? ''}..${file.branchCompare.headOid ?? ''}::${file.branchOldPath ?? ''}`
-      : ''
-  return `${connectionId ?? ''}::${file.diffSource ?? ''}::${compareAgainstHead ? 'head' : 'default'}::${file.filePath}::${branch}`
-}
 
 function EditorPanelInner({
   activeFileId: activeFileIdProp,
@@ -191,6 +31,8 @@ function EditorPanelInner({
   const openFiles = useAppStore((s) => s.openFiles)
   const globalActiveFileId = useAppStore((s) => s.activeFileId)
   const activeFileId = activeFileIdProp ?? globalActiveFileId
+  const activeViewStateId = activeViewStateIdProp ?? activeFileId
+  const activeFile = openFiles.find((f) => f.id === activeFileId) ?? null
   const markFileDirty = useAppStore((s) => s.markFileDirty)
   const pendingEditorReveal = useAppStore((s) => s.pendingEditorReveal)
   const gitStatusByWorktree = useAppStore((s) => s.gitStatusByWorktree)
@@ -206,57 +48,14 @@ function EditorPanelInner({
   const editorDrafts = useAppStore((s) => s.editorDrafts)
   const setEditorDraft = useAppStore((s) => s.setEditorDraft)
   const settings = useAppStore((s) => s.settings)
-
-  const activeFile = openFiles.find((f) => f.id === activeFileId) ?? null
-  const activeFilePath = activeFile?.filePath ?? null
-  const activeFileRelativePath = activeFile?.relativePath ?? null
-  const activeFileWorktreeId = activeFile?.worktreeId ?? null
-  const activeFileMode = activeFile?.mode ?? null
-  const activeFileDiffSource = activeFile?.diffSource
-  const activeFileRuntimeEnvironmentId = activeFile?.runtimeEnvironmentId
-  const activeViewStateId = activeViewStateIdProp ?? activeFileId
-  const [fileContents, setFileContents] = useState<Record<string, FileContent>>({})
-  const [diffContents, setDiffContents] = useState<Record<string, DiffContent>>({})
-  // Why: Changes view mode only applies on top of a regular edit-mode tab. It
-  // swaps the MonacoEditor for a DiffViewer (HEAD vs working tree incl. unsaved
-  // draft) without creating a new tab. Transient tabs (diff, conflict-review,
-  // markdown-preview) keep their own rendering pipeline.
-  // Binary content short-circuits to the binary placeholder in EditorContent
-  // before isChangesMode is consulted, so we must also exclude binary files
-  // here — otherwise the header toggle would still show Changes as selected
-  // and expose the inline/side-by-side toggle even though no diff is rendered.
-  const isChangesMode =
-    !!activeFile &&
-    activeFile.mode === 'edit' &&
-    canUseChangesModeForFile(activeFile) &&
-    editorViewMode[activeFile.id] === 'changes' &&
-    !fileContents[activeFile.id]?.isBinary &&
-    !fileContents[activeFile.id]?.loadError
+  const panelRef = useRef<HTMLDivElement>(null)
   const [copiedPathToast, setCopiedPathToast] = useState<{ fileId: string; token: number } | null>(
     null
   )
   const [showMarkdownTableOfContents, setShowMarkdownTableOfContents] = useState(false)
-  const [renameDialogFileId, setRenameDialogFileId] = useState<string | null>(null)
-  const renameDialogFile = renameDialogFileId
-    ? openFiles.find((f) => f.id === renameDialogFileId)
-    : null
   const [sideBySide, setSideBySide] = useState(settings?.diffDefaultView === 'side-by-side')
   const [prevDiffView, setPrevDiffView] = useState(settings?.diffDefaultView)
-  const [pathMenuOpen, setPathMenuOpen] = useState(false)
-  const [pathMenuPoint, setPathMenuPoint] = useState({ x: 0, y: 0 })
-  const panelRef = useRef<HTMLDivElement>(null)
-  const fileLoadRetryAttemptsRef = useRef<Record<string, number>>({})
 
-  const deleteCacheEntriesByPrefix = useCallback(<T,>(cache: Map<string, T>, prefix: string) => {
-    for (const key of cache.keys()) {
-      if (key.startsWith(prefix)) {
-        cache.delete(key)
-      }
-    }
-  }, [])
-
-  // Why: When the user changes their global diff-view preference in Settings,
-  // sync the local toggle to match during render (avoids flash of stale diff mode).
   if (settings?.diffDefaultView !== prevDiffView) {
     setPrevDiffView(settings?.diffDefaultView)
     if (settings?.diffDefaultView !== undefined) {
@@ -264,133 +63,34 @@ function EditorPanelInner({
     }
   }
 
-  const openFilesRef = useRef(openFiles)
-  openFilesRef.current = openFiles
+  const requestedChangesMode =
+    !!activeFile &&
+    activeFile.mode === 'edit' &&
+    canUseChangesModeForFile(activeFile) &&
+    editorViewMode[activeFile.id] === 'changes'
+  const { fileContents, diffContents, reloadFileContent } = useEditorPanelContentState({
+    activeFile,
+    isChangesMode: requestedChangesMode,
+    openFiles,
+    gitStatusByWorktree,
+    editorViewMode
+  })
+  const isChangesMode =
+    requestedChangesMode &&
+    !!activeFile &&
+    !fileContents[activeFile.id]?.isBinary &&
+    !fileContents[activeFile.id]?.loadError
+  const {
+    renameDialogFile,
+    renameError,
+    requestRenameForFile,
+    closeRenameDialog,
+    handleRenameConfirm
+  } = useUntitledFileRename({ openFiles, closeFile, openFile, clearUntitled })
 
-  // Why: the external-file-change handler below needs to consult the latest
-  // editorViewMode, but we do not want to re-register its window listener
-  // every time an unrelated editor-mode toggle flips. A ref lets the handler
-  // read the current value without adding editorViewMode to the effect deps.
-  const editorViewModeRef = useRef(editorViewMode)
-  editorViewModeRef.current = editorViewMode
-
-  useEffect(() => {
-    const closeMenu = (): void => setPathMenuOpen(false)
-    window.addEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
-    return () => window.removeEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
-  }, [])
-
-  // Why: the system "File → Export as PDF..." menu item sends a one-way IPC
-  // event that reaches whichever renderer has focus. The EditorPanel is the
-  // natural owner of the active markdown surface, so the listener lives here
-  // and delegates to the shared export helper. Both entry points (menu and
-  // overflow button) funnel through exportActiveMarkdownToPdf so toasts and
-  // no-op gating stay consistent.
-  // Why (guard): split-pane layouts mount multiple EditorPanelInner instances.
-  // We ref-count via `acquireExportPdfListener` so exactly one IPC subscription
-  // exists regardless of how many panels are mounted — and it survives panel
-  // churn as long as at least one panel is still mounted.
   useEffect(() => acquireExportPdfListener(), [])
-
-  // Why: keepCurrentModel / keepCurrent*Model retain Monaco models after unmount
-  // so undo history survives tab switches. When a tab is *closed*, the user has
-  // signalled they're done with the file — dispose the models to reclaim memory
-  // and delete cache entries so a reopened file starts fresh.
-  const prevOpenFilesRef = useRef<Map<string, OpenFile>>(new Map())
-
-  useEffect(() => {
-    const currentFilesById = new Map(openFiles.map((f) => [f.id, f]))
-    for (const [prevId, prevFile] of prevOpenFilesRef.current) {
-      if (!currentFilesById.has(prevId)) {
-        // Dispose only the kept-alive Monaco state that this tab mode owns.
-        // Why: edit and diff tabs use different retained-model keys, while the
-        // conflict-review surface does not create kept Monaco models today. An
-        // explicit switch makes that ownership boundary visible so future mode
-        // additions do not silently fall through without considering cleanup.
-        switch (prevFile.mode) {
-          case 'edit':
-            // Why: the edit model URI is constructed via monaco.Uri.parse(filePath)
-            // to match what @monaco-editor/react creates internally when the `path`
-            // prop is provided. This convention is version-dependent.
-            monaco.editor.getModel(monaco.Uri.parse(prevFile.filePath))?.dispose()
-            scrollTopCache.delete(prevFile.filePath)
-            deleteCacheEntriesByPrefix(scrollTopCache, `${prevFile.filePath}::`)
-            // Why: markdown edit tabs keep separate source/rich scroll caches,
-            // and older sessions may still have the legacy in-place preview key.
-            // Clear all of them so reopened files never inherit stale viewport
-            // state from a prior tab incarnation.
-            scrollTopCache.delete(`${prevFile.filePath}:rich`)
-            scrollTopCache.delete(`${prevFile.filePath}:preview`)
-            // Why: mermaid files use a mode-scoped cache key just like markdown.
-            // Without this, a reopened .mmd file would restore a stale scroll
-            // position from the previous session even if the content changed.
-            scrollTopCache.delete(`${prevFile.filePath}:mermaid-diagram`)
-            cursorPositionCache.delete(prevFile.filePath)
-            deleteCacheEntriesByPrefix(cursorPositionCache, `${prevFile.filePath}::`)
-            break
-          case 'markdown-preview':
-            // Why: preview tabs have no retained Monaco models, but they do
-            // own pane-scoped preview scroll cache entries that should be
-            // dropped on close so reopening the preview starts fresh.
-            scrollTopCache.delete(`${prevFile.id}:preview`)
-            deleteCacheEntriesByPrefix(scrollTopCache, `${prevFile.id}::`)
-            break
-          case 'diff':
-            // Why: kept diff models are keyed by tab id, not file path, because the
-            // same file can appear in multiple diff tabs with different contents.
-            monaco.editor.getModel(monaco.Uri.parse(`diff:original:${prevId}`))?.dispose()
-            monaco.editor.getModel(monaco.Uri.parse(`diff:modified:${prevId}`))?.dispose()
-            diffViewStateCache.delete(prevId)
-            deleteCacheEntriesByPrefix(diffViewStateCache, `${prevId}::`)
-            // Why: single-file markdown diffs now have a rendered preview mode
-            // whose scroll position is keyed off the diff tab identity rather
-            // than a Monaco view-state cache entry. Clear those mode-scoped
-            // keys alongside the diff models so reopened diff tabs start fresh.
-            scrollTopCache.delete(`${prevId}:preview`)
-            deleteCacheEntriesByPrefix(scrollTopCache, `${prevId}::`)
-            break
-          case 'conflict-review':
-            break
-        }
-      }
-    }
-    prevOpenFilesRef.current = currentFilesById
-  }, [deleteCacheEntriesByPrefix, openFiles])
-
-  // Load file content when active file changes
-  useEffect(() => {
-    if (!activeFile) {
-      return
-    }
-    if (activeFile.mode === 'conflict-review') {
-      return
-    }
-    if (activeFile.mode === 'edit' || activeFile.mode === 'markdown-preview') {
-      if (activeFile.conflict?.kind === 'conflict-placeholder') {
-        return
-      }
-      if (!fileContents[activeFile.id]) {
-        void loadFileContent(activeFile.filePath, activeFile.id, activeFile.worktreeId)
-      }
-      // Why: Changes view mode needs the HEAD-side blob as well as the
-      // working-tree content. Kick off the diff load alongside the normal
-      // file read so both are ready by the time DiffViewer mounts.
-      if (isChangesMode && !diffContents[activeFile.id]) {
-        void loadDiffContent(activeFile)
-      }
-    } else if (
-      activeFile.mode === 'diff' &&
-      activeFile.diffSource !== undefined &&
-      activeFile.diffSource !== 'combined-uncommitted' &&
-      activeFile.diffSource !== 'combined-branch'
-    ) {
-      if (diffContents[activeFile.id]) {
-        return
-      }
-      void loadDiffContent(activeFile)
-    }
-  }, [activeFile?.id, isChangesMode]) // eslint-disable-line react-hooks/exhaustive-deps
-
+  useClosedEditorTabCleanup(openFiles)
+  useMarkdownPreviewShortcut({ activeFile, panelRef, isMac, openMarkdownPreview })
   useEffect(() => {
     if (!copiedPathToast) {
       return
@@ -399,298 +99,35 @@ function EditorPanelInner({
     return () => window.clearTimeout(timeout)
   }, [copiedPathToast])
 
-  const loadFileContent = useCallback(
-    async (filePath: string, id: string, worktreeId?: string): Promise<void> => {
-      try {
-        const connectionId = getConnectionId(worktreeId ?? null) ?? undefined
-        const restoredOpenFile = openFilesRef.current.find((file) => file.id === id)
-        const activeSettings = useAppStore.getState().settings
-        const readSettings = settingsForRuntimeOwner(
-          activeSettings,
-          restoredOpenFile?.runtimeEnvironmentId
-        )
-        if (restoredOpenFile?.filePath === filePath && restoredOpenFile.relativePath === filePath) {
-          if (readSettings?.activeRuntimeEnvironmentId?.trim() || connectionId) {
-            // Why: restored external-file tabs contain client-local absolute
-            // paths. Remote runtime and SSH workspaces cannot read those paths
-            // without an explicit upload/import flow.
-            throw new Error('External local files are not available for remote workspaces.')
-          }
-          // Why: external files selected through OS/browser/drop flows are
-          // authorized in the main process, but that grant is in-memory. On
-          // session restore, re-authorize only tabs that were stored with an
-          // absolute relativePath because they came from outside a worktree.
-          await window.api.fs.authorizeExternalPath({ targetPath: filePath })
-        }
-        const readScope = getRuntimeFileReadScope(readSettings, connectionId)
-        const key = inFlightReadKey(readScope, filePath)
-        // Why: share the IPC round-trip across split-pane EditorPanels viewing
-        // the same file. The first caller starts the read and registers the
-        // promise; concurrent callers (triggered by the same external-change
-        // event) await it instead of firing duplicate reads and duplicate
-        // downstream setContent transactions.
-        let pending = inFlightFileReads.get(key)
-        if (!pending) {
-          pending = readRuntimeFileContent({
-            settings: readSettings,
-            filePath,
-            relativePath: restoredOpenFile?.relativePath,
-            worktreeId,
-            connectionId
-          }) as Promise<FileContent>
-          inFlightFileReads.set(key, pending)
-          // Why: limit deduplication to synchronous callers (like N split panes
-          // responding to the exact same event loop dispatch). Caching the promise
-          // across time (e.g. until the IPC returns) means a new change event that
-          // fires while the read is in-flight would receive stale content.
-          queueMicrotask(() => {
-            if (inFlightFileReads.get(key) === pending) {
-              inFlightFileReads.delete(key)
-            }
-          })
-        }
-        const result = await pending
-        delete fileLoadRetryAttemptsRef.current[id]
-        setFileContents((prev) => ({ ...prev, [id]: result }))
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err)
-        setFileContents((prev) => ({
-          ...prev,
-          [id]: { content: '', isBinary: false, loadError: message }
-        }))
-      }
-    },
-    []
-  )
-
-  const reloadFileContent = useCallback(
-    (file: OpenFile): void => {
-      delete fileLoadRetryAttemptsRef.current[file.id]
-      setFileContents((prev) => {
-        if (!prev[file.id]) {
-          return prev
-        }
-        const next = { ...prev }
-        delete next[file.id]
-        return next
-      })
-      void loadFileContent(file.filePath, file.id, file.worktreeId)
-    },
-    [loadFileContent]
-  )
-
-  const loadDiffContent = useCallback(async (file: OpenFile | null): Promise<void> => {
-    if (!file) {
-      return
-    }
-    try {
-      if (file.mode === 'edit' && !canUseChangesModeForFile(file)) {
-        return
-      }
-      // Extract worktree path from absolute file path and relative path
-      const worktreePath = file.filePath.slice(
-        0,
-        file.filePath.length - file.relativePath.length - 1
-      )
-      const branchCompare =
-        file.branchCompare?.baseOid && file.branchCompare.headOid && file.branchCompare.mergeBase
-          ? file.branchCompare
-          : null
-      const connectionId = getConnectionId(file.worktreeId) ?? undefined
-      const activeSettings = useAppStore.getState().settings
-      const fileSettings = settingsForRuntimeOwner(activeSettings, file.runtimeEnvironmentId)
-      const gitScope = getRuntimeGitScope(fileSettings, connectionId)
-      // Why: Changes view mode runs on top of an edit-mode tab and asks git
-      // for an unstaged diff against HEAD for that file. Use the 'unstaged'
-      // diff-source key so multiple Changes tabs across split panes share one
-      // IPC round-trip with any open unstaged diff-tab for the same path.
-      // Compute this once and reuse it for both the dedup key and the IPC
-      // branch selection so the two can never drift apart.
-      const effectiveDiffSource: typeof file.diffSource =
-        file.mode === 'edit' ? 'unstaged' : file.diffSource
-      const compareAgainstHead = file.mode === 'edit'
-      const key = inFlightDiffKey(
-        { ...file, diffSource: effectiveDiffSource },
-        gitScope,
-        compareAgainstHead
-      )
-      // Why: same rationale as inFlightFileReads above — a single external
-      // change fans out to every mounted EditorPanel, and two split panes
-      // showing the same diff tab should share one git.diff IPC instead of
-      // racing two identical calls through the same git repo lock.
-      let pending = inFlightDiffReads.get(key)
-      if (!pending) {
-        pending = (
-          effectiveDiffSource === 'branch' && branchCompare
-            ? getRuntimeGitBranchDiff(
-                {
-                  settings: fileSettings,
-                  worktreeId: file.worktreeId,
-                  worktreePath,
-                  connectionId
-                },
-                {
-                  compare: {
-                    baseRef: branchCompare.baseRef,
-                    baseOid: branchCompare.baseOid!,
-                    headOid: branchCompare.headOid!,
-                    mergeBase: branchCompare.mergeBase!
-                  },
-                  filePath: file.relativePath,
-                  oldPath: file.branchOldPath
-                }
-              )
-            : getRuntimeGitDiff(
-                {
-                  settings: fileSettings,
-                  worktreeId: file.worktreeId,
-                  worktreePath,
-                  connectionId
-                },
-                {
-                  filePath: file.relativePath,
-                  staged: effectiveDiffSource === 'staged',
-                  compareAgainstHead
-                }
-              )
-        ) as Promise<DiffContent>
-        inFlightDiffReads.set(key, pending)
-        queueMicrotask(() => {
-          if (inFlightDiffReads.get(key) === pending) {
-            inFlightDiffReads.delete(key)
-          }
-        })
-      }
-      const result = await pending
-      setDiffContents((prev) => ({ ...prev, [file.id]: result }))
-    } catch (err) {
-      setDiffContents((prev) => ({
-        ...prev,
-        [file.id]: {
-          kind: 'text',
-          originalContent: '',
-          modifiedContent: `Error loading diff: ${err}`,
-          originalIsBinary: false,
-          modifiedIsBinary: false
-        }
-      }))
-    }
-  }, [])
-
-  const activeFileLoadRetryId = activeFile?.id ?? null
-  const activeFileLoadError = activeFileLoadRetryId
-    ? fileContents[activeFileLoadRetryId]?.loadError
-    : undefined
-  useEffect(() => {
-    if (
-      !activeFileLoadRetryId ||
-      !activeFileLoadError ||
-      !shouldRetryFileLoadError(activeFileLoadError)
-    ) {
-      return
-    }
-    const retryCount = fileLoadRetryAttemptsRef.current[activeFileLoadRetryId] ?? 0
-    if (retryCount >= FILE_LOAD_RETRY_DELAYS_MS.length) {
-      return
-    }
-    const delayMs = FILE_LOAD_RETRY_DELAYS_MS[retryCount] ?? FILE_LOAD_RETRY_DELAYS_MS[0]
-    fileLoadRetryAttemptsRef.current[activeFileLoadRetryId] = retryCount + 1
-
-    // Why: restored tabs can race app/worktree startup and get a transient
-    // read failure. Retry briefly, but keep permanent filesystem errors quiet.
-    const timeoutId = window.setTimeout(() => {
-      const currentFile = openFilesRef.current.find((file) => file.id === activeFileLoadRetryId)
-      if (
-        !currentFile ||
-        (currentFile.mode !== 'edit' && currentFile.mode !== 'markdown-preview')
-      ) {
-        return
-      }
-      setFileContents((prev) => {
-        if (prev[currentFile.id]?.loadError !== activeFileLoadError) {
-          return prev
-        }
-        const next = { ...prev }
-        delete next[currentFile.id]
-        return next
-      })
-      void loadFileContent(currentFile.filePath, currentFile.id, currentFile.worktreeId)
-    }, delayMs)
-
-    return () => window.clearTimeout(timeoutId)
-  }, [activeFileLoadRetryId, activeFileLoadError, loadFileContent])
-
-  // Why: refetch the HEAD-side blob for Changes mode when the worktree's git
-  // status array identity changes. A commit, pull, or rebase updates the
-  // status poll result, which is the cheapest signal we have that HEAD moved
-  // — without this, users see a stale diff after committing from Changes mode.
-  // Subscribing to the status array keeps parity with the Changes sidebar.
-  const changesStatusEntries = activeFile?.worktreeId
-    ? gitStatusByWorktree[activeFile.worktreeId]
-    : undefined
-  // Why: depend on the primitive identifiers of the active file rather than
-  // the `activeFile` object. `openFiles` is rebuilt on any store update that
-  // touches an open file (dirty flips, saves, status polling), so the
-  // `activeFile` object reference changes on many unrelated renders. Each
-  // identity change would otherwise retrigger the effect and dispatch a
-  // spurious git.diff IPC that the in-flight dedup map cannot coalesce
-  // across time. Resolve the current file via `openFilesRef` inside the
-  // effect so we still pass a live OpenFile to loadDiffContent.
-  useEffect(() => {
-    if (!isChangesMode || !activeFile?.id) {
-      return
-    }
-    const current = openFilesRef.current.find((f) => f.id === activeFile.id)
-    if (!current) {
-      return
-    }
-    void loadDiffContent(current)
-  }, [
-    changesStatusEntries,
-    isChangesMode,
-    activeFile?.id,
-    activeFile?.worktreeId,
-    activeFile?.relativePath,
-    loadDiffContent
-  ])
-
   const handleContentChange = useCallback(
     (content: string) => {
       if (!activeFile) {
         return
       }
       setEditorDraft(activeFile.id, content)
-      // Why: TipTap's getMarkdown() always appends a trailing newline to the
-      // serialized output. If the file on disk lacks that newline the naive
-      // strict-equality check treats the file as dirty even though no user edit
-      // occurred. Normalising trailing whitespace for markdown files mirrors the
-      // same trimEnd() used in the round-trip checker (markdown-round-trip.ts).
-      const isMarkdown = activeFile.language === 'markdown'
-      const normalize = isMarkdown ? (s: string): string => s.trimEnd() : (s: string): string => s
+      const normalize =
+        activeFile.language === 'markdown'
+          ? (value: string): string => value.trimEnd()
+          : (value: string): string => value
       if (activeFile.mode === 'edit') {
-        const saved = fileContents[activeFile.id]?.content ?? ''
-        markFileDirty(activeFile.id, normalize(content) !== normalize(saved))
-      } else {
-        // Diff mode: compare against the original modified content from git
-        const dc = diffContents[activeFile.id]
-        const original = dc?.kind === 'text' ? dc.modifiedContent : ''
-        markFileDirty(activeFile.id, normalize(content) !== normalize(original))
+        markFileDirty(
+          activeFile.id,
+          normalize(content) !== normalize(fileContents[activeFile.id]?.content ?? '')
+        )
+        return
       }
+      const diffContent = diffContents[activeFile.id]
+      const original = diffContent?.kind === 'text' ? diffContent.modifiedContent : ''
+      markFileDirty(activeFile.id, normalize(content) !== normalize(original))
     },
     [activeFile, diffContents, fileContents, markFileDirty, setEditorDraft]
   )
 
   const handleDirtyStateHint = useCallback(
     (dirty: boolean) => {
-      if (!activeFile) {
-        return
+      if (activeFile) {
+        markFileDirty(activeFile.id, dirty)
       }
-
-      // Why: RichMarkdownEditor debounces markdown serialization to keep
-      // typing responsive on large documents. The store still needs an
-      // immediate dirty signal so close prompts and window-unload guards do
-      // not miss edits made in the last debounce window.
-      markFileDirty(activeFile.id, dirty)
     },
     [activeFile, markFileDirty]
   )
@@ -710,25 +147,18 @@ function EditorPanelInner({
       if (!saveTargetFile) {
         return
       }
-      // Why: for untitled files, Cmd+S should prompt for a name before
-      // writing anything. Saving first would make Cancel misleading since
-      // the write already happened. Show the dialog and let the confirm
-      // handler do the save + rename atomically.
       if (saveTargetFile.isUntitled) {
-        setRenameDialogFileId(saveTargetFile.id)
+        requestRenameForFile(saveTargetFile.id)
         return
       }
       try {
         await requestEditorFileSave({ fileId: saveTargetFile.id, fallbackContent: content })
       } catch {}
     },
-    [activeFile, openFiles]
+    [activeFile, openFiles, requestRenameForFile]
   )
+  useEditorCmdSaveRequest({ activeFile, openFiles, fileContents, handleSave })
 
-  // Why: hooks must run unconditionally, so this useCallback lives above the
-  // `if (!activeFile) return null` guard; the callback itself no-ops when
-  // no file is active. Memoised to match the other editor handlers in this
-  // file and avoid churning EditorViewToggle's onChange identity.
   const handleEditorToggleChange = useCallback(
     (next: EditorToggleValue): void => {
       const fileId = activeFile?.id
@@ -739,9 +169,6 @@ function EditorPanelInner({
         setEditorViewMode(fileId, 'changes')
         return
       }
-      // Why: selecting any non-Changes segment implicitly exits Changes mode.
-      // For markdown/mermaid files, also persist the chosen language sub-mode
-      // so that next time Changes is toggled off, the file returns to that view.
       setEditorViewMode(fileId, 'edit')
       if (next !== 'edit') {
         setMarkdownViewMode(fileId, next)
@@ -750,266 +177,6 @@ function EditorPanelInner({
     [activeFile?.id, setEditorViewMode, setMarkdownViewMode]
   )
 
-  // Why: global Cmd+S (from Terminal.tsx) dispatches this event when
-  // focus is outside the editor content area. Delegate to handleSave
-  // so untitled files still show the rename dialog.
-  useEffect(() => {
-    const handler = (): void => {
-      if (!activeFile) {
-        return
-      }
-      const saveTargetFile =
-        activeFile.mode === 'markdown-preview'
-          ? (openFilesRef.current.find(
-              (openFile) =>
-                openFile.id === activeFile.markdownPreviewSourceFileId && openFile.mode === 'edit'
-            ) ?? null)
-          : activeFile
-      if (!saveTargetFile) {
-        return
-      }
-      // Why: a markdown preview tab is read-only but still fronts the same
-      // underlying document. Cmd/Ctrl+S should save that source editor's draft
-      // instead of no-oping just because the preview tab currently has focus.
-      const state = useAppStore.getState()
-      const draft = state.editorDrafts[saveTargetFile.id]
-      if (!draft && !saveTargetFile.isUntitled && !saveTargetFile.isDirty) {
-        return
-      }
-      const fallbackContent =
-        draft ??
-        (activeFile.mode === 'markdown-preview' ? fileContents[activeFile.id]?.content : '')
-      void handleSave(fallbackContent ?? '')
-    }
-    window.addEventListener(ORCA_EDITOR_REQUEST_CMD_SAVE_EVENT, handler)
-    return () => window.removeEventListener(ORCA_EDITOR_REQUEST_CMD_SAVE_EVENT, handler)
-  }, [activeFile, fileContents, handleSave])
-
-  useEffect(() => {
-    const handler = (event: Event): void => {
-      const detail = (event as CustomEvent<EditorPathMutationTarget>).detail
-      if (!detail) {
-        return
-      }
-
-      const matchingFiles = getOpenFilesForExternalFileChange(openFilesRef.current, detail)
-      if (matchingFiles.length === 0) {
-        return
-      }
-      // Why: do NOT delete fileContents[file.id] here before the reload
-      // completes. Dropping the entry renders EditorContent's "Loading..."
-      // placeholder and unmounts MonacoEditor. On remount, @monaco-editor/react
-      // skips its value-sync effect on the first render, and `keepCurrentModel`
-      // retains the prior model — so the new content prop never reaches the
-      // editor and the user sees the pre-external-edit text linger.
-      // loadFileContent / loadDiffContent overwrite the entry atomically once
-      // the fresh read returns, which is what Monaco's value-sync can observe.
-      for (const file of matchingFiles) {
-        if (file.mode === 'edit' || file.mode === 'markdown-preview') {
-          void loadFileContent(file.filePath, file.id, file.worktreeId)
-          // Why: if this edit tab is currently in Changes view mode, the
-          // rendered DiffViewer also depends on the HEAD-side blob. An
-          // external write (e.g. a git checkout) can change both the working
-          // tree *and* shift the reference blob, so refetch the diff too.
-          // Read through a ref so the handler reflects the subscribed store
-          // value without forcing the listener to re-register on every mode
-          // toggle.
-          if (editorViewModeRef.current[file.id] === 'changes') {
-            void loadDiffContent(file)
-          }
-        } else if (
-          file.mode === 'diff' &&
-          file.diffSource !== 'combined-uncommitted' &&
-          file.diffSource !== 'combined-branch'
-        ) {
-          void loadDiffContent(file)
-        }
-      }
-    }
-
-    window.addEventListener(ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT, handler as EventListener)
-    return () =>
-      window.removeEventListener(ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT, handler as EventListener)
-  }, [loadDiffContent, loadFileContent])
-
-  useEffect(() => {
-    const openIds = new Set(openFiles.map((f) => f.id))
-    for (const fileId of Object.keys(fileLoadRetryAttemptsRef.current)) {
-      if (!openIds.has(fileId)) {
-        delete fileLoadRetryAttemptsRef.current[fileId]
-      }
-    }
-    setFileContents((prev) => {
-      const next: Record<string, FileContent> = {}
-      for (const [k, v] of Object.entries(prev)) {
-        if (openIds.has(k)) {
-          next[k] = v
-        }
-      }
-      return next
-    })
-    setDiffContents((prev) => {
-      const next: Record<string, DiffContent> = {}
-      for (const [k, v] of Object.entries(prev)) {
-        if (openIds.has(k)) {
-          next[k] = v
-        }
-      }
-      return next
-    })
-  }, [openFiles])
-
-  useEffect(() => {
-    const handler = (event: Event): void => {
-      const detail = (event as CustomEvent<EditorFileSavedDetail>).detail
-      if (!detail) {
-        return
-      }
-
-      const file = openFilesRef.current.find((openFile) => openFile.id === detail.fileId)
-      if (!file) {
-        return
-      }
-
-      if (file.mode === 'edit' || file.mode === 'markdown-preview') {
-        setFileContents((prev) => ({
-          ...prev,
-          [file.id]: { content: detail.content, isBinary: false }
-        }))
-      }
-
-      const previewTabs = openFilesRef.current.filter(
-        (openFile) =>
-          openFile.mode === 'markdown-preview' &&
-          openFile.markdownPreviewSourceFileId === detail.fileId
-      )
-      if (previewTabs.length > 0) {
-        setFileContents((prev) => {
-          const next = { ...prev }
-          for (const previewTab of previewTabs) {
-            next[previewTab.id] = { content: detail.content, isBinary: false }
-          }
-          return next
-        })
-      }
-
-      if (file.mode === 'edit' || file.mode === 'markdown-preview') {
-        return
-      }
-
-      setDiffContents((prev) => {
-        const existing = prev[file.id]
-        if (!existing || existing.kind !== 'text') {
-          return prev
-        }
-        return {
-          ...prev,
-          [file.id]: { ...existing, modifiedContent: detail.content }
-        }
-      })
-    }
-
-    window.addEventListener(ORCA_EDITOR_FILE_SAVED_EVENT, handler as EventListener)
-    return () => window.removeEventListener(ORCA_EDITOR_FILE_SAVED_EVENT, handler as EventListener)
-  }, [])
-
-  const [renameError, setRenameError] = useState<string | null>(null)
-
-  const handleRenameConfirm = useCallback(
-    async (newRelPath: string) => {
-      if (!renameDialogFile) {
-        return
-      }
-      const oldPath = renameDialogFile.filePath
-      // Why: worktree path is derived by stripping the old relativePath
-      // suffix, so subdirectory-relative names (e.g. "notes/ideas.md")
-      // resolve correctly against the worktree root.
-      const worktreeRoot = oldPath.slice(
-        0,
-        oldPath.length - renameDialogFile.relativePath.length - 1
-      )
-      const newPath = `${worktreeRoot}/${newRelPath}`
-      const connectionId = getConnectionId(renameDialogFile.worktreeId) ?? undefined
-      const fileContext = {
-        settings: settingsForRuntimeOwner(
-          useAppStore.getState().settings,
-          renameDialogFile.runtimeEnvironmentId
-        ),
-        worktreeId: renameDialogFile.worktreeId,
-        worktreePath: worktreeRoot,
-        connectionId
-      }
-
-      // Prevent silently overwriting an existing file (but allow keeping
-      // the current name — the file's own path is not a conflict).
-      if (newPath !== oldPath && (await runtimePathExists(fileContext, newPath))) {
-        setRenameError('A file with that name already exists')
-        return
-      }
-
-      // Why: Cmd+S no longer pre-saves for untitled files — it just opens
-      // this dialog. Flush any pending autosave, then save the current
-      // content so the file on disk is up-to-date before we rename it.
-      await requestEditorSaveQuiesce({ fileId: renameDialogFile.id })
-      // Why: only trigger a save if there's actually unsaved content.
-      // Passing an empty fallbackContent when the draft is absent would
-      // overwrite the file with nothing, wiping user content.
-      const draft = useAppStore.getState().editorDrafts[renameDialogFile.id]
-      if (draft !== undefined) {
-        try {
-          await requestEditorFileSave({ fileId: renameDialogFile.id, fallbackContent: draft })
-        } catch {
-          // Why: if the save fails (disk full, permissions, etc.), abort the
-          // rename to avoid moving a stale/empty file and losing content.
-          setRenameError('Failed to save file')
-          return
-        }
-      }
-
-      // User kept the same name — just save in place, no rename needed.
-      if (newPath === oldPath) {
-        clearUntitled(renameDialogFile.id)
-        setRenameDialogFileId(null)
-        setRenameError(null)
-        return
-      }
-
-      // Why: if the target path includes subdirectories (e.g. "notes/ideas.md"),
-      // ensure the parent directory exists before renaming. createDir throws
-      // if the directory already exists (assertNotExists guard), so only call
-      // it when the directory is not yet on disk.
-      const newDir = newPath.slice(0, newPath.lastIndexOf('/'))
-      if (newDir !== worktreeRoot && !(await runtimePathExists(fileContext, newDir))) {
-        await createRuntimePath(fileContext, newDir, 'directory')
-      }
-
-      try {
-        await renameRuntimePath(fileContext, oldPath, newPath)
-      } catch (err) {
-        setRenameError(err instanceof Error ? err.message : 'Failed to rename file')
-        return
-      }
-
-      closeFile(oldPath)
-      openFile({
-        filePath: newPath,
-        relativePath: newRelPath,
-        worktreeId: renameDialogFile.worktreeId,
-        runtimeEnvironmentId: renameDialogFile.runtimeEnvironmentId,
-        language: detectLanguage(newRelPath),
-        mode: 'edit'
-      })
-
-      // Why: Cmd+S already saved the content before the rename dialog opened,
-      // and quiesce flushed any remaining writes. The renamed file on disk
-      // matches the editor content, so the new tab should start clean.
-
-      setRenameDialogFileId(null)
-      setRenameError(null)
-    },
-    [renameDialogFile, closeFile, openFile, clearUntitled]
-  )
-
   const handleCopyPath = useCallback(async (): Promise<void> => {
     if (!activeFile) {
       return
@@ -1026,116 +193,19 @@ function EditorPanelInner({
     }
   }, [activeFile])
 
-  useEffect(() => {
-    if (!activeFilePath || !activeFileRelativePath || !activeFileWorktreeId || !activeFileMode) {
-      return
-    }
-
-    const shortcutLanguage =
-      activeFileMode === 'diff'
-        ? detectLanguage(activeFileRelativePath)
-        : detectLanguage(activeFilePath)
-    const canShowMarkdownPreview = canOpenMarkdownPreview({
-      language: shortcutLanguage,
-      mode: activeFileMode,
-      diffSource: activeFileDiffSource
-    })
-    if (!canShowMarkdownPreview) {
-      return
-    }
-
-    const handleKeyDown = (event: KeyboardEvent): void => {
-      if (event.defaultPrevented || !isMarkdownPreviewShortcut(event, isMac)) {
-        return
-      }
-      const root = panelRef.current
-      if (!root) {
-        return
-      }
-      const target = event.target
-      const targetInsidePanel = target instanceof Node && root.contains(target)
-      if (!targetInsidePanel) {
-        return
-      }
-      event.preventDefault()
-      event.stopPropagation()
-      openMarkdownPreview({
-        filePath: activeFilePath,
-        relativePath: activeFileRelativePath,
-        worktreeId: activeFileWorktreeId,
-        runtimeEnvironmentId: activeFileRuntimeEnvironmentId,
-        language: shortcutLanguage
-      })
-    }
-
-    window.addEventListener('keydown', handleKeyDown, { capture: true })
-    return () => window.removeEventListener('keydown', handleKeyDown, { capture: true })
-  }, [
-    activeFileDiffSource,
-    activeFileMode,
-    activeFilePath,
-    activeFileRelativePath,
-    activeFileRuntimeEnvironmentId,
-    activeFileWorktreeId,
-    openMarkdownPreview
-  ])
-
   if (!activeFile) {
     return null
   }
-
-  const isSingleDiff =
-    activeFile.mode === 'diff' &&
-    activeFile.diffSource !== undefined &&
-    activeFile.diffSource !== 'combined-uncommitted' &&
-    activeFile.diffSource !== 'combined-branch'
-  // Why: Changes view mode renders a DiffViewer, so expose the same inline /
-  // side-by-side toggle the diff-tab path already offers.
-  const isDiffSurface = isSingleDiff || isChangesMode
-  const isCombinedDiff =
-    activeFile.mode === 'diff' &&
-    (activeFile.diffSource === 'combined-uncommitted' ||
-      activeFile.diffSource === 'combined-branch')
-  const headerCopyState = getEditorHeaderCopyState(activeFile)
-  const worktreeEntries = gitStatusByWorktree[activeFile.worktreeId] ?? []
-  const branchEntries = gitBranchChangesByWorktree[activeFile.worktreeId] ?? []
-  const resolvedLanguage =
-    activeFile.mode === 'diff'
-      ? detectLanguage(activeFile.relativePath)
-      : detectLanguage(activeFile.filePath)
-  const matchingWorktreeEntry =
-    activeFile.mode === 'diff' && activeFile.diffSource !== 'branch'
-      ? (worktreeEntries.find(
-          (entry) =>
-            entry.path === activeFile.relativePath &&
-            (activeFile.diffSource === 'staged'
-              ? entry.area === 'staged'
-              : entry.area === 'unstaged')
-        ) ?? null)
-      : null
-  const matchingBranchEntry =
-    activeFile.mode === 'diff' && activeFile.diffSource === 'branch'
-      ? (branchEntries.find((entry) => entry.path === activeFile.relativePath) ?? null)
-      : null
-  const openFileState = getEditorHeaderOpenFileState(
+  const model = getEditorPanelRenderModel({
     activeFile,
-    matchingWorktreeEntry,
-    matchingBranchEntry
-  )
+    fileContents,
+    gitStatusByWorktree,
+    gitBranchChangesByWorktree,
+    markdownViewMode,
+    isChangesMode
+  })
 
-  const isMarkdown = resolvedLanguage === 'markdown'
-  const isMermaid = resolvedLanguage === 'mermaid'
-  const isCsv = resolvedLanguage === 'csv' || resolvedLanguage === 'tsv'
-  const isNotebook = resolvedLanguage === 'notebook'
-  // Why: "Open Preview to the Side" only applies to edit-mode tabs whose
-  // language has a registered renderer. Diff tabs already have their own
-  // toggle set and there is no clear semantic for previewing a diff.
-  const canOpenPreviewToSide = activeFile.mode === 'edit' && canPreviewLanguage(resolvedLanguage)
   const handleOpenPreviewToSide = (): void => {
-    // Split-pane layouts mount one EditorPanel per pane, each with its own
-    // activeViewStateId (the unified-tab id). Resolve the owning group from
-    // that tab so the preview lands beside *this* pane rather than whichever
-    // group happens to be the ambient active one.
     const state = useAppStore.getState()
     const sourceGroupId = activeViewStateId
       ? ((state.unifiedTabsByWorktree[activeFile.worktreeId] ?? []).find(
@@ -1143,366 +213,86 @@ function EditorPanelInner({
         )?.groupId ?? null)
       : null
     openFilePreviewToSide({
-      language: resolvedLanguage,
+      language: model.resolvedLanguage,
       filePath: activeFile.filePath,
       worktreeId: activeFile.worktreeId,
       sourceGroupId
     })
   }
-  const markdownViewModes = getMarkdownViewModes({
-    language: resolvedLanguage,
-    mode: activeFile.mode,
-    diffSource: activeFile.diffSource
-  })
-  const hasViewModeToggle = markdownViewModes.length > 0
-  const defaultMarkdownViewMode = getDefaultMarkdownViewMode({
-    language: resolvedLanguage,
-    mode: activeFile.mode,
-    diffSource: activeFile.diffSource
-  })
-  const storedMarkdownViewMode = markdownViewMode[activeFile.id]
-  const mdViewMode: MarkdownViewMode =
-    hasViewModeToggle &&
-    storedMarkdownViewMode !== undefined &&
-    markdownViewModes.includes(storedMarkdownViewMode)
-      ? storedMarkdownViewMode
-      : defaultMarkdownViewMode
-  // Why: the header toggle surfaces both the language-specific view mode
-  // (Source / Rich / Preview) and the orthogonal Changes view mode in one
-  // segmented control. Plain code files (no language-specific modes) still get
-  // an Edit | Changes toggle because Changes applies to every editable tab.
-  const editorToggleModes = getEditorToggleModes({
-    language: resolvedLanguage,
-    mode: activeFile.mode,
-    diffSource: activeFile.diffSource
-  })
-  const isBinaryEditSurface =
-    activeFile.mode === 'edit' && fileContents[activeFile.id]?.isBinary === true
-  const canUseChangesMode = canUseChangesModeForFile(activeFile)
-  // Why: edit-mode binary/image tabs already have their own dedicated renderers
-  // and external files have no repo-relative path for git diff. Hide Changes
-  // rather than offering a segment the renderer will immediately ignore.
-  const availableEditorToggleModes =
-    isBinaryEditSurface || !canUseChangesMode
-      ? editorToggleModes.filter((mode) => mode !== 'changes')
-      : editorToggleModes
-  // Why: a toggle with a single option is just a decorative pill with nothing
-  // to switch to. Binary plain-code tabs end up here after 'changes' is
-  // stripped — on main they had no header toggle at all, so requiring >1 mode
-  // preserves that behavior instead of leaving a lone "Edit" segment.
-  const hasEditorToggle = availableEditorToggleModes.length > 1
-  const effectiveToggleValue: EditorToggleValue = isChangesMode
-    ? 'changes'
-    : hasViewModeToggle
-      ? mdViewMode
-      : 'edit'
-  const isMarkdownTableOfContentsDisabled = hasViewModeToggle && mdViewMode === 'source'
-  const canShowMarkdownTableOfContents =
-    isMarkdown && (hasViewModeToggle || activeFile.mode === 'markdown-preview')
-  const canShowMarkdownPreview = canOpenMarkdownPreview({
-    language: resolvedLanguage,
-    mode: activeFile.mode,
-    diffSource: activeFile.diffSource
-  })
-
   const handleOpenDiffTargetFile = (): void => {
-    if (!openFileState.canOpen) {
+    if (!model.openFileState.canOpen) {
       return
     }
     openFile({
       filePath: activeFile.filePath,
       relativePath: activeFile.relativePath,
       worktreeId: activeFile.worktreeId,
+      runtimeEnvironmentId: activeFile.runtimeEnvironmentId,
       language: detectLanguage(activeFile.relativePath),
       mode: 'edit'
     })
   }
-
-  const loadingFallback = (
-    <div className="flex items-center justify-center h-full text-muted-foreground text-sm">
-      Loading editor...
-    </div>
+  const handleOpenMarkdownPreview = (): void => {
+    openMarkdownPreview({
+      filePath: activeFile.filePath,
+      relativePath: activeFile.relativePath,
+      worktreeId: activeFile.worktreeId,
+      runtimeEnvironmentId: activeFile.runtimeEnvironmentId,
+      language: model.resolvedLanguage
+    })
+  }
+  const handleOpenContainingFolder = (): void => {
+    if (
+      isLocalPathOpenBlocked(settingsForRuntimeOwner(settings, activeFile.runtimeEnvironmentId), {
+        connectionId: getConnectionId(activeFile.worktreeId)
+      })
+    ) {
+      showLocalPathOpenBlockedToast()
+      return
+    }
+    window.api.shell.openPath(activeFile.filePath)
+  }
+  const disableRenameBrowse = Boolean(
+    settingsForRuntimeOwner(
+      settings,
+      renameDialogFile?.runtimeEnvironmentId
+    )?.activeRuntimeEnvironmentId?.trim() ||
+      (renameDialogFile ? getConnectionId(renameDialogFile.worktreeId) : null)
   )
 
   return (
-    <div ref={panelRef} className="flex flex-col flex-1 min-w-0 min-h-0">
-      {!isCombinedDiff && (
-        <div className="editor-header">
-          <div className="editor-header-text">
-            <div
-              className="editor-header-path-row"
-              onContextMenuCapture={(event) => {
-                event.preventDefault()
-                window.dispatchEvent(new Event(CLOSE_ALL_CONTEXT_MENUS_EVENT))
-                setPathMenuPoint({ x: event.clientX, y: event.clientY })
-                setPathMenuOpen(true)
-              }}
-            >
-              <button
-                type="button"
-                className="editor-header-path"
-                onClick={() => void handleCopyPath()}
-                title={headerCopyState.pathTitle}
-              >
-                {headerCopyState.pathLabel}
-              </button>
-              <span
-                className={`editor-header-copy-toast${copiedPathToast?.fileId === activeFile.id ? ' is-visible' : ''}`}
-                aria-live="polite"
-              >
-                {headerCopyState.copyToastLabel}
-              </span>
-            </div>
-            <DropdownMenu open={pathMenuOpen} onOpenChange={setPathMenuOpen} modal={false}>
-              <DropdownMenuTrigger asChild>
-                <button
-                  aria-hidden
-                  tabIndex={-1}
-                  className="pointer-events-none fixed size-px opacity-0"
-                  style={{ left: pathMenuPoint.x, top: pathMenuPoint.y }}
-                />
-              </DropdownMenuTrigger>
-              <DropdownMenuContent className="w-56" sideOffset={0} align="start">
-                <DropdownMenuItem
-                  onSelect={() => {
-                    void window.api.ui.writeClipboardText(activeFile.filePath)
-                  }}
-                >
-                  <Copy className="w-3.5 h-3.5 mr-1.5" />
-                  Copy Path
-                </DropdownMenuItem>
-                <DropdownMenuItem
-                  onSelect={() => {
-                    void window.api.ui.writeClipboardText(activeFile.relativePath)
-                  }}
-                >
-                  <Copy className="w-3.5 h-3.5 mr-1.5" />
-                  Copy Relative Path
-                </DropdownMenuItem>
-                <DropdownMenuSeparator />
-                {canShowMarkdownPreview && (
-                  <DropdownMenuItem
-                    onSelect={() =>
-                      openMarkdownPreview({
-                        filePath: activeFile.filePath,
-                        relativePath: activeFile.relativePath,
-                        worktreeId: activeFile.worktreeId,
-                        runtimeEnvironmentId: activeFile.runtimeEnvironmentId,
-                        language: resolvedLanguage
-                      })
-                    }
-                  >
-                    <Eye className="w-3.5 h-3.5 mr-1.5" />
-                    Open Markdown Preview
-                    <DropdownMenuShortcut>{markdownPreviewShortcutLabel}</DropdownMenuShortcut>
-                  </DropdownMenuItem>
-                )}
-                {canShowMarkdownPreview && <DropdownMenuSeparator />}
-                <DropdownMenuItem
-                  onSelect={() => {
-                    if (
-                      isLocalPathOpenBlocked(
-                        settingsForRuntimeOwner(settings, activeFile.runtimeEnvironmentId),
-                        {
-                          connectionId: getConnectionId(activeFile.worktreeId)
-                        }
-                      )
-                    ) {
-                      showLocalPathOpenBlockedToast()
-                      return
-                    }
-                    window.api.shell.openPath(activeFile.filePath)
-                  }}
-                >
-                  <ExternalLink className="w-3.5 h-3.5 mr-1.5" />
-                  {revealLabel}
-                </DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          </div>
-          {isSingleDiff && (
-            <TooltipProvider delayDuration={300}>
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <button
-                    type="button"
-                    className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0 disabled:opacity-50 disabled:hover:bg-transparent disabled:hover:text-muted-foreground"
-                    onClick={handleOpenDiffTargetFile}
-                    aria-label="Open file"
-                    disabled={!openFileState.canOpen}
-                  >
-                    <FileText size={14} />
-                  </button>
-                </TooltipTrigger>
-                <TooltipContent side="bottom" sideOffset={4}>
-                  {openFileState.canOpen
-                    ? isMarkdown
-                      ? 'Open file tab to use rich markdown editing'
-                      : 'Open file tab'
-                    : 'This diff has no modified-side file to open'}
-                </TooltipContent>
-              </Tooltip>
-            </TooltipProvider>
-          )}
-          {canOpenPreviewToSide && (
-            <TooltipProvider delayDuration={300}>
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <button
-                    type="button"
-                    className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0"
-                    onClick={handleOpenPreviewToSide}
-                    aria-label="Open Preview to the Side"
-                  >
-                    <Eye size={14} />
-                  </button>
-                </TooltipTrigger>
-                <TooltipContent side="bottom" sideOffset={4}>
-                  Open Preview to the Side
-                </TooltipContent>
-              </Tooltip>
-            </TooltipProvider>
-          )}
-          {isDiffSurface && (
-            <TooltipProvider delayDuration={300}>
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <button
-                    className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0"
-                    onClick={() => setSideBySide((prev) => !prev)}
-                  >
-                    {sideBySide ? <Rows2 size={14} /> : <Columns2 size={14} />}
-                  </button>
-                </TooltipTrigger>
-                <TooltipContent side="bottom" sideOffset={4}>
-                  {sideBySide ? 'Switch to inline diff' : 'Switch to side-by-side diff'}
-                </TooltipContent>
-              </Tooltip>
-            </TooltipProvider>
-          )}
-          {hasEditorToggle && (
-            <EditorViewToggle
-              value={effectiveToggleValue}
-              modes={availableEditorToggleModes}
-              onChange={handleEditorToggleChange}
-              metadataOverride={
-                isCsv
-                  ? CSV_VIEW_MODE_METADATA
-                  : isNotebook
-                    ? NOTEBOOK_VIEW_MODE_METADATA
-                    : undefined
-              }
-            />
-          )}
-          {canShowMarkdownTableOfContents && (
-            <TooltipProvider delayDuration={300}>
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <button
-                    type="button"
-                    className={`p-1 rounded hover:bg-accent hover:text-foreground transition-colors flex-shrink-0 disabled:opacity-50 disabled:hover:bg-transparent disabled:hover:text-muted-foreground ${
-                      showMarkdownTableOfContents && !isMarkdownTableOfContentsDisabled
-                        ? 'bg-accent text-foreground'
-                        : 'text-muted-foreground'
-                    }`}
-                    onClick={() => setShowMarkdownTableOfContents((shown) => !shown)}
-                    disabled={isMarkdownTableOfContentsDisabled}
-                    aria-label="Table of Contents"
-                    aria-pressed={showMarkdownTableOfContents}
-                  >
-                    <ListTree size={14} />
-                  </button>
-                </TooltipTrigger>
-                <TooltipContent side="bottom" sideOffset={4}>
-                  {isMarkdownTableOfContentsDisabled
-                    ? 'Table of Contents is available in rich or preview mode'
-                    : 'Table of Contents'}
-                </TooltipContent>
-              </Tooltip>
-            </TooltipProvider>
-          )}
-          {hasViewModeToggle && isMarkdown && (
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <button
-                  type="button"
-                  className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0"
-                  aria-label="More actions"
-                  title="More actions"
-                >
-                  <MoreHorizontal size={14} />
-                </button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end" sideOffset={4}>
-                <DropdownMenuItem
-                  // Why: the item is disabled (not hidden) only in source/Monaco
-                  // mode, which has no document DOM to export. We intentionally
-                  // don't poll the DOM (canExportActiveMarkdown) at render time:
-                  // the Radix content renders in a Portal and the lookup can
-                  // race with the active surface's paint, producing a stuck
-                  // disabled state. exportActiveMarkdownToPdf is a safe no-op
-                  // when no subtree is found.
-                  disabled={mdViewMode === 'source'}
-                  onSelect={() => {
-                    void exportActiveMarkdownToPdf()
-                  }}
-                >
-                  Export as PDF
-                </DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          )}
-        </div>
-      )}
-      <Suspense fallback={loadingFallback}>
-        <EditorContent
-          activeFile={activeFile}
-          viewStateScopeId={activeViewStateId ?? activeFile.id}
-          fileContents={fileContents}
-          diffContents={diffContents}
-          editBuffers={editorDrafts}
-          worktreeEntries={worktreeEntries}
-          resolvedLanguage={resolvedLanguage}
-          isMarkdown={isMarkdown}
-          isMermaid={isMermaid}
-          isCsv={isCsv}
-          isNotebook={isNotebook}
-          mdViewMode={mdViewMode}
-          isChangesMode={isChangesMode}
-          sideBySide={sideBySide}
-          pendingEditorReveal={pendingEditorReveal}
-          handleContentChange={handleContentChange}
-          handleDirtyStateHint={handleDirtyStateHint}
-          handleSave={handleSave}
-          reloadFileContent={reloadFileContent}
-          showMarkdownTableOfContents={showMarkdownTableOfContents}
-          onCloseMarkdownTableOfContents={() => setShowMarkdownTableOfContents(false)}
-        />
-      </Suspense>
-      <UntitledFileRenameDialog
-        open={renameDialogFile !== undefined && renameDialogFile !== null}
-        currentName={renameDialogFile?.relativePath ?? ''}
-        worktreePath={
-          renameDialogFile
-            ? (findWorktreeById(useAppStore.getState().worktreesByRepo, renameDialogFile.worktreeId)
-                ?.path ?? '')
-            : ''
-        }
-        disableBrowse={Boolean(
-          settingsForRuntimeOwner(
-            settings,
-            renameDialogFile?.runtimeEnvironmentId
-          )?.activeRuntimeEnvironmentId?.trim() ||
-          (renameDialogFile ? getConnectionId(renameDialogFile.worktreeId) : null)
-        )}
-        externalError={renameError}
-        onClose={() => {
-          setRenameDialogFileId(null)
-          setRenameError(null)
-        }}
-        onConfirm={handleRenameConfirm}
-      />
-    </div>
+    <EditorPanelShell
+      panelRef={panelRef}
+      activeFile={activeFile}
+      activeViewStateId={activeViewStateId}
+      model={model}
+      copiedPathVisible={copiedPathToast?.fileId === activeFile.id}
+      showMarkdownTableOfContents={showMarkdownTableOfContents}
+      sideBySide={sideBySide}
+      fileContents={fileContents}
+      diffContents={diffContents}
+      editorDrafts={editorDrafts}
+      pendingEditorReveal={pendingEditorReveal}
+      renameDialogFile={renameDialogFile}
+      renameError={renameError}
+      disableRenameBrowse={disableRenameBrowse}
+      onCopyPath={() => void handleCopyPath()}
+      onOpenDiffTargetFile={handleOpenDiffTargetFile}
+      onOpenPreviewToSide={handleOpenPreviewToSide}
+      onOpenMarkdownPreview={handleOpenMarkdownPreview}
+      onOpenContainingFolder={handleOpenContainingFolder}
+      onToggleSideBySide={() => setSideBySide((prev) => !prev)}
+      onEditorToggleChange={handleEditorToggleChange}
+      onToggleMarkdownTableOfContents={() => setShowMarkdownTableOfContents((shown) => !shown)}
+      onExportMarkdownToPdf={() => void exportActiveMarkdownToPdf()}
+      onContentChange={handleContentChange}
+      onDirtyStateHint={handleDirtyStateHint}
+      onSave={handleSave}
+      onReloadFileContent={reloadFileContent}
+      onCloseMarkdownTableOfContents={() => setShowMarkdownTableOfContents(false)}
+      onCloseRenameDialog={closeRenameDialog}
+      onRenameConfirm={handleRenameConfirm}
+    />
   )
 }
 
diff --git a/src/renderer/src/components/editor/EditorPanelHeader.tsx b/src/renderer/src/components/editor/EditorPanelHeader.tsx
new file mode 100644
index 00000000000..e9e63339b4d
--- /dev/null
+++ b/src/renderer/src/components/editor/EditorPanelHeader.tsx
@@ -0,0 +1,312 @@
+import { useEffect, useState } from 'react'
+import {
+  Columns2,
+  Copy,
+  Eye,
+  ExternalLink,
+  FileText,
+  ListTree,
+  MoreHorizontal,
+  Rows2
+} from 'lucide-react'
+import type { MarkdownViewMode, OpenFile } from '@/store/slices/editor'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
+import { CLOSE_ALL_CONTEXT_MENUS_EVENT } from '../tab-bar/SortableTab'
+import EditorViewToggle, {
+  CSV_VIEW_MODE_METADATA,
+  NOTEBOOK_VIEW_MODE_METADATA
+} from './EditorViewToggle'
+import type { EditorToggleValue } from './EditorViewToggle'
+import type { EditorHeaderOpenFileState } from './editor-header'
+import { getEditorHeaderCopyState } from './editor-header'
+import { getMarkdownPreviewShortcutLabel } from './markdown-preview-controls'
+
+const isMac = navigator.userAgent.includes('Mac')
+const isLinux = navigator.userAgent.includes('Linux')
+
+/** Platform-appropriate label: macOS -> Finder, Windows -> File Explorer, Linux -> Files */
+const revealLabel = isMac
+  ? 'Reveal in Finder'
+  : isLinux
+    ? 'Open Containing Folder'
+    : 'Reveal in File Explorer'
+const markdownPreviewShortcutLabel = getMarkdownPreviewShortcutLabel(isMac)
+
+type EditorPanelHeaderProps = {
+  activeFile: OpenFile
+  copiedPathVisible: boolean
+  isSingleDiff: boolean
+  isDiffSurface: boolean
+  isMarkdown: boolean
+  isCsv: boolean
+  isNotebook: boolean
+  hasEditorToggle: boolean
+  availableEditorToggleModes: readonly EditorToggleValue[]
+  effectiveToggleValue: EditorToggleValue
+  mdViewMode: MarkdownViewMode
+  hasViewModeToggle: boolean
+  canOpenPreviewToSide: boolean
+  canShowMarkdownPreview: boolean
+  canShowMarkdownTableOfContents: boolean
+  isMarkdownTableOfContentsDisabled: boolean
+  showMarkdownTableOfContents: boolean
+  sideBySide: boolean
+  openFileState: EditorHeaderOpenFileState
+  onCopyPath: () => void
+  onOpenDiffTargetFile: () => void
+  onOpenPreviewToSide: () => void
+  onOpenMarkdownPreview: () => void
+  onOpenContainingFolder: () => void
+  onToggleSideBySide: () => void
+  onEditorToggleChange: (next: EditorToggleValue) => void
+  onToggleMarkdownTableOfContents: () => void
+  onExportMarkdownToPdf: () => void
+}
+
+export function EditorPanelHeader({
+  activeFile,
+  copiedPathVisible,
+  isSingleDiff,
+  isDiffSurface,
+  isMarkdown,
+  isCsv,
+  isNotebook,
+  hasEditorToggle,
+  availableEditorToggleModes,
+  effectiveToggleValue,
+  mdViewMode,
+  hasViewModeToggle,
+  canOpenPreviewToSide,
+  canShowMarkdownPreview,
+  canShowMarkdownTableOfContents,
+  isMarkdownTableOfContentsDisabled,
+  showMarkdownTableOfContents,
+  sideBySide,
+  openFileState,
+  onCopyPath,
+  onOpenDiffTargetFile,
+  onOpenPreviewToSide,
+  onOpenMarkdownPreview,
+  onOpenContainingFolder,
+  onToggleSideBySide,
+  onEditorToggleChange,
+  onToggleMarkdownTableOfContents,
+  onExportMarkdownToPdf
+}: EditorPanelHeaderProps): React.JSX.Element {
+  const [pathMenuOpen, setPathMenuOpen] = useState(false)
+  const [pathMenuPoint, setPathMenuPoint] = useState({ x: 0, y: 0 })
+  const headerCopyState = getEditorHeaderCopyState(activeFile)
+
+  useEffect(() => {
+    const closeMenu = (): void => setPathMenuOpen(false)
+    window.addEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
+    return () => window.removeEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
+  }, [])
+
+  return (
+    <div className="editor-header">
+      <div className="editor-header-text">
+        <div
+          className="editor-header-path-row"
+          onContextMenuCapture={(event) => {
+            event.preventDefault()
+            window.dispatchEvent(new Event(CLOSE_ALL_CONTEXT_MENUS_EVENT))
+            setPathMenuPoint({ x: event.clientX, y: event.clientY })
+            setPathMenuOpen(true)
+          }}
+        >
+          <button
+            type="button"
+            className="editor-header-path"
+            onClick={onCopyPath}
+            title={headerCopyState.pathTitle}
+          >
+            {headerCopyState.pathLabel}
+          </button>
+          <span
+            className={`editor-header-copy-toast${copiedPathVisible ? ' is-visible' : ''}`}
+            aria-live="polite"
+          >
+            {headerCopyState.copyToastLabel}
+          </span>
+        </div>
+        <DropdownMenu open={pathMenuOpen} onOpenChange={setPathMenuOpen} modal={false}>
+          <DropdownMenuTrigger asChild>
+            <button
+              aria-hidden
+              tabIndex={-1}
+              className="pointer-events-none fixed size-px opacity-0"
+              style={{ left: pathMenuPoint.x, top: pathMenuPoint.y }}
+            />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent className="w-56" sideOffset={0} align="start">
+            <DropdownMenuItem
+              onSelect={() => {
+                void window.api.ui.writeClipboardText(activeFile.filePath)
+              }}
+            >
+              <Copy className="w-3.5 h-3.5 mr-1.5" />
+              Copy Path
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              onSelect={() => {
+                void window.api.ui.writeClipboardText(activeFile.relativePath)
+              }}
+            >
+              <Copy className="w-3.5 h-3.5 mr-1.5" />
+              Copy Relative Path
+            </DropdownMenuItem>
+            <DropdownMenuSeparator />
+            {canShowMarkdownPreview && (
+              <DropdownMenuItem onSelect={onOpenMarkdownPreview}>
+                <Eye className="w-3.5 h-3.5 mr-1.5" />
+                Open Markdown Preview
+                <DropdownMenuShortcut>{markdownPreviewShortcutLabel}</DropdownMenuShortcut>
+              </DropdownMenuItem>
+            )}
+            {canShowMarkdownPreview && <DropdownMenuSeparator />}
+            <DropdownMenuItem onSelect={onOpenContainingFolder}>
+              <ExternalLink className="w-3.5 h-3.5 mr-1.5" />
+              {revealLabel}
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+      {isSingleDiff && (
+        <TooltipProvider delayDuration={300}>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0 disabled:opacity-50 disabled:hover:bg-transparent disabled:hover:text-muted-foreground"
+                onClick={onOpenDiffTargetFile}
+                aria-label="Open file"
+                disabled={!openFileState.canOpen}
+              >
+                <FileText size={14} />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={4}>
+              {openFileState.canOpen
+                ? isMarkdown
+                  ? 'Open file tab to use rich markdown editing'
+                  : 'Open file tab'
+                : 'This diff has no modified-side file to open'}
+            </TooltipContent>
+          </Tooltip>
+        </TooltipProvider>
+      )}
+      {canOpenPreviewToSide && (
+        <TooltipProvider delayDuration={300}>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0"
+                onClick={onOpenPreviewToSide}
+                aria-label="Open Preview to the Side"
+              >
+                <Eye size={14} />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={4}>
+              Open Preview to the Side
+            </TooltipContent>
+          </Tooltip>
+        </TooltipProvider>
+      )}
+      {isDiffSurface && (
+        <TooltipProvider delayDuration={300}>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0"
+                onClick={onToggleSideBySide}
+              >
+                {sideBySide ? <Rows2 size={14} /> : <Columns2 size={14} />}
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={4}>
+              {sideBySide ? 'Switch to inline diff' : 'Switch to side-by-side diff'}
+            </TooltipContent>
+          </Tooltip>
+        </TooltipProvider>
+      )}
+      {hasEditorToggle && (
+        <EditorViewToggle
+          value={effectiveToggleValue}
+          modes={availableEditorToggleModes}
+          onChange={onEditorToggleChange}
+          metadataOverride={
+            isCsv ? CSV_VIEW_MODE_METADATA : isNotebook ? NOTEBOOK_VIEW_MODE_METADATA : undefined
+          }
+        />
+      )}
+      {canShowMarkdownTableOfContents && (
+        <TooltipProvider delayDuration={300}>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                className={`p-1 rounded hover:bg-accent hover:text-foreground transition-colors flex-shrink-0 disabled:opacity-50 disabled:hover:bg-transparent disabled:hover:text-muted-foreground ${
+                  showMarkdownTableOfContents && !isMarkdownTableOfContentsDisabled
+                    ? 'bg-accent text-foreground'
+                    : 'text-muted-foreground'
+                }`}
+                onClick={onToggleMarkdownTableOfContents}
+                disabled={isMarkdownTableOfContentsDisabled}
+                aria-label="Table of Contents"
+                aria-pressed={showMarkdownTableOfContents}
+              >
+                <ListTree size={14} />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={4}>
+              {isMarkdownTableOfContentsDisabled
+                ? 'Table of Contents is available in rich or preview mode'
+                : 'Table of Contents'}
+            </TooltipContent>
+          </Tooltip>
+        </TooltipProvider>
+      )}
+      {hasViewModeToggle && isMarkdown && (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <button
+              type="button"
+              className="p-1 rounded hover:bg-accent text-muted-foreground hover:text-foreground transition-colors flex-shrink-0"
+              aria-label="More actions"
+              title="More actions"
+            >
+              <MoreHorizontal size={14} />
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" sideOffset={4}>
+            <DropdownMenuItem
+              // Why: the item is disabled (not hidden) only in source/Monaco
+              // mode, which has no document DOM to export. We intentionally
+              // don't poll the DOM (canExportActiveMarkdown) at render time:
+              // the Radix content renders in a Portal and the lookup can
+              // race with the active surface's paint, producing a stuck
+              // disabled state. exportActiveMarkdownToPdf is a safe no-op
+              // when no subtree is found.
+              disabled={mdViewMode === 'source'}
+              onSelect={onExportMarkdownToPdf}
+            >
+              Export as PDF
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/editor/EditorPanelShell.tsx b/src/renderer/src/components/editor/EditorPanelShell.tsx
new file mode 100644
index 00000000000..f48d22855d1
--- /dev/null
+++ b/src/renderer/src/components/editor/EditorPanelShell.tsx
@@ -0,0 +1,162 @@
+import { Suspense, type JSX, type RefObject } from 'react'
+import { useAppStore } from '@/store'
+import { findWorktreeById } from '@/store/slices/worktree-helpers'
+import type { OpenFile } from '@/store/slices/editor'
+import { EditorContent } from './EditorContent'
+import { EditorPanelHeader } from './EditorPanelHeader'
+import { UntitledFileRenameDialog } from './UntitledFileRenameDialog'
+import type { getEditorPanelRenderModel } from './editor-panel-render-model'
+import type { DiffContent, FileContent } from './editor-panel-content-types'
+import type { EditorToggleValue } from './EditorViewToggle'
+
+type EditorPanelRenderModel = ReturnType<typeof getEditorPanelRenderModel>
+
+type EditorPanelShellProps = {
+  panelRef: RefObject<HTMLDivElement | null>
+  activeFile: OpenFile
+  activeViewStateId: string | null | undefined
+  model: EditorPanelRenderModel
+  copiedPathVisible: boolean
+  showMarkdownTableOfContents: boolean
+  sideBySide: boolean
+  fileContents: Record<string, FileContent>
+  diffContents: Record<string, DiffContent>
+  editorDrafts: Record<string, string>
+  pendingEditorReveal: ReturnType<typeof useAppStore.getState>['pendingEditorReveal']
+  renameDialogFile: OpenFile | null
+  renameError: string | null
+  disableRenameBrowse: boolean
+  onCopyPath: () => void
+  onOpenDiffTargetFile: () => void
+  onOpenPreviewToSide: () => void
+  onOpenMarkdownPreview: () => void
+  onOpenContainingFolder: () => void
+  onToggleSideBySide: () => void
+  onEditorToggleChange: (next: EditorToggleValue) => void
+  onToggleMarkdownTableOfContents: () => void
+  onExportMarkdownToPdf: () => void
+  onContentChange: (content: string) => void
+  onDirtyStateHint: (dirty: boolean) => void
+  onSave: (content: string) => Promise<void>
+  onReloadFileContent: (file: OpenFile) => void
+  onCloseMarkdownTableOfContents: () => void
+  onCloseRenameDialog: () => void
+  onRenameConfirm: (newRelPath: string) => Promise<void>
+}
+
+export function EditorPanelShell({
+  panelRef,
+  activeFile,
+  activeViewStateId,
+  model,
+  copiedPathVisible,
+  showMarkdownTableOfContents,
+  sideBySide,
+  fileContents,
+  diffContents,
+  editorDrafts,
+  pendingEditorReveal,
+  renameDialogFile,
+  renameError,
+  disableRenameBrowse,
+  onCopyPath,
+  onOpenDiffTargetFile,
+  onOpenPreviewToSide,
+  onOpenMarkdownPreview,
+  onOpenContainingFolder,
+  onToggleSideBySide,
+  onEditorToggleChange,
+  onToggleMarkdownTableOfContents,
+  onExportMarkdownToPdf,
+  onContentChange,
+  onDirtyStateHint,
+  onSave,
+  onReloadFileContent,
+  onCloseMarkdownTableOfContents,
+  onCloseRenameDialog,
+  onRenameConfirm
+}: EditorPanelShellProps): JSX.Element {
+  return (
+    <div ref={panelRef} className="flex flex-col flex-1 min-w-0 min-h-0">
+      {!model.isCombinedDiff && (
+        <EditorPanelHeader
+          activeFile={activeFile}
+          copiedPathVisible={copiedPathVisible}
+          isSingleDiff={model.isSingleDiff}
+          isDiffSurface={model.isDiffSurface}
+          isMarkdown={model.isMarkdown}
+          isCsv={model.isCsv}
+          isNotebook={model.isNotebook}
+          hasEditorToggle={model.hasEditorToggle}
+          availableEditorToggleModes={model.availableEditorToggleModes}
+          effectiveToggleValue={model.effectiveToggleValue}
+          mdViewMode={model.mdViewMode}
+          hasViewModeToggle={model.hasViewModeToggle}
+          canOpenPreviewToSide={model.canOpenPreviewToSide}
+          canShowMarkdownPreview={model.canShowMarkdownPreview}
+          canShowMarkdownTableOfContents={model.canShowMarkdownTableOfContents}
+          isMarkdownTableOfContentsDisabled={model.isMarkdownTableOfContentsDisabled}
+          showMarkdownTableOfContents={showMarkdownTableOfContents}
+          sideBySide={sideBySide}
+          openFileState={model.openFileState}
+          onCopyPath={onCopyPath}
+          onOpenDiffTargetFile={onOpenDiffTargetFile}
+          onOpenPreviewToSide={onOpenPreviewToSide}
+          onOpenMarkdownPreview={onOpenMarkdownPreview}
+          onOpenContainingFolder={onOpenContainingFolder}
+          onToggleSideBySide={onToggleSideBySide}
+          onEditorToggleChange={onEditorToggleChange}
+          onToggleMarkdownTableOfContents={onToggleMarkdownTableOfContents}
+          onExportMarkdownToPdf={onExportMarkdownToPdf}
+        />
+      )}
+      <Suspense fallback={<EditorLoadingFallback />}>
+        <EditorContent
+          activeFile={activeFile}
+          viewStateScopeId={activeViewStateId ?? activeFile.id}
+          fileContents={fileContents}
+          diffContents={diffContents}
+          editBuffers={editorDrafts}
+          worktreeEntries={model.worktreeEntries}
+          resolvedLanguage={model.resolvedLanguage}
+          isMarkdown={model.isMarkdown}
+          isMermaid={model.isMermaid}
+          isCsv={model.isCsv}
+          isNotebook={model.isNotebook}
+          mdViewMode={model.mdViewMode}
+          isChangesMode={model.isDiffSurface && !model.isSingleDiff}
+          sideBySide={sideBySide}
+          pendingEditorReveal={pendingEditorReveal}
+          handleContentChange={onContentChange}
+          handleDirtyStateHint={onDirtyStateHint}
+          handleSave={onSave}
+          reloadFileContent={onReloadFileContent}
+          showMarkdownTableOfContents={showMarkdownTableOfContents}
+          onCloseMarkdownTableOfContents={onCloseMarkdownTableOfContents}
+        />
+      </Suspense>
+      <UntitledFileRenameDialog
+        open={renameDialogFile !== null}
+        currentName={renameDialogFile?.relativePath ?? ''}
+        worktreePath={
+          renameDialogFile
+            ? (findWorktreeById(useAppStore.getState().worktreesByRepo, renameDialogFile.worktreeId)
+                ?.path ?? '')
+            : ''
+        }
+        disableBrowse={disableRenameBrowse}
+        externalError={renameError}
+        onClose={onCloseRenameDialog}
+        onConfirm={onRenameConfirm}
+      />
+    </div>
+  )
+}
+
+function EditorLoadingFallback(): JSX.Element {
+  return (
+    <div className="flex items-center justify-center h-full text-muted-foreground text-sm">
+      Loading editor...
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/editor/editor-panel-content-types.ts b/src/renderer/src/components/editor/editor-panel-content-types.ts
new file mode 100644
index 00000000000..1267f4621cd
--- /dev/null
+++ b/src/renderer/src/components/editor/editor-panel-content-types.ts
@@ -0,0 +1,11 @@
+import type { GitDiffResult } from '../../../../shared/types'
+
+export type FileContent = {
+  content: string
+  isBinary: boolean
+  isImage?: boolean
+  mimeType?: string
+  loadError?: string
+}
+
+export type DiffContent = GitDiffResult
diff --git a/src/renderer/src/components/editor/editor-panel-export-pdf-listener.ts b/src/renderer/src/components/editor/editor-panel-export-pdf-listener.ts
new file mode 100644
index 00000000000..229da963140
--- /dev/null
+++ b/src/renderer/src/components/editor/editor-panel-export-pdf-listener.ts
@@ -0,0 +1,23 @@
+import { exportActiveMarkdownToPdf } from './export-active-markdown'
+
+// Why: the "File -> Export as PDF..." menu IPC fans out to every EditorPanel
+// instance, and split-pane layouts mount N panels concurrently. This ref-counted
+// singleton keeps exactly one renderer subscription alive while any panel exists.
+let exportPdfListenerOwners = 0
+let exportPdfListenerUnsubscribe: (() => void) | null = null
+
+export function acquireExportPdfListener(): () => void {
+  exportPdfListenerOwners += 1
+  if (exportPdfListenerOwners === 1) {
+    exportPdfListenerUnsubscribe = window.api.ui.onExportPdfRequested(() => {
+      void exportActiveMarkdownToPdf()
+    })
+  }
+  return () => {
+    exportPdfListenerOwners -= 1
+    if (exportPdfListenerOwners === 0 && exportPdfListenerUnsubscribe) {
+      exportPdfListenerUnsubscribe()
+      exportPdfListenerUnsubscribe = null
+    }
+  }
+}
diff --git a/src/renderer/src/components/editor/editor-panel-file-mode.ts b/src/renderer/src/components/editor/editor-panel-file-mode.ts
new file mode 100644
index 00000000000..cf24aaefdf9
--- /dev/null
+++ b/src/renderer/src/components/editor/editor-panel-file-mode.ts
@@ -0,0 +1,14 @@
+import type { OpenFile } from '@/store/slices/editor'
+
+export function isAbsolutePathLike(value: string): boolean {
+  return value.startsWith('/') || value.startsWith('\\\\') || /^[A-Za-z]:[\\/]/.test(value)
+}
+
+export function canUseChangesModeForFile(file: OpenFile): boolean {
+  return (
+    file.mode === 'edit' &&
+    !file.isUntitled &&
+    file.relativePath !== file.filePath &&
+    !isAbsolutePathLike(file.relativePath)
+  )
+}
diff --git a/src/renderer/src/components/editor/editor-panel-render-model.ts b/src/renderer/src/components/editor/editor-panel-render-model.ts
new file mode 100644
index 00000000000..7b588567f30
--- /dev/null
+++ b/src/renderer/src/components/editor/editor-panel-render-model.ts
@@ -0,0 +1,129 @@
+import { detectLanguage } from '@/lib/language-detect'
+import { canPreviewLanguage } from '@/lib/file-preview'
+import type { useAppStore } from '@/store'
+import type { MarkdownViewMode, OpenFile } from '@/store/slices/editor'
+import {
+  canOpenMarkdownPreview,
+  getDefaultMarkdownViewMode,
+  getEditorToggleModes,
+  getMarkdownViewModes
+} from './markdown-preview-controls'
+import { getEditorHeaderOpenFileState } from './editor-header'
+import type { EditorToggleValue } from './EditorViewToggle'
+import type { FileContent } from './editor-panel-content-types'
+import { canUseChangesModeForFile } from './editor-panel-file-mode'
+
+type StoreState = ReturnType<typeof useAppStore.getState>
+
+type EditorPanelRenderModelParams = {
+  activeFile: OpenFile
+  fileContents: Record<string, FileContent>
+  gitStatusByWorktree: StoreState['gitStatusByWorktree']
+  gitBranchChangesByWorktree: StoreState['gitBranchChangesByWorktree']
+  markdownViewMode: StoreState['markdownViewMode']
+  isChangesMode: boolean
+}
+
+export function getEditorPanelRenderModel({
+  activeFile,
+  fileContents,
+  gitStatusByWorktree,
+  gitBranchChangesByWorktree,
+  markdownViewMode,
+  isChangesMode
+}: EditorPanelRenderModelParams) {
+  const isSingleDiff =
+    activeFile.mode === 'diff' &&
+    activeFile.diffSource !== undefined &&
+    activeFile.diffSource !== 'combined-uncommitted' &&
+    activeFile.diffSource !== 'combined-branch'
+  const isCombinedDiff =
+    activeFile.mode === 'diff' &&
+    (activeFile.diffSource === 'combined-uncommitted' ||
+      activeFile.diffSource === 'combined-branch')
+  const resolvedLanguage =
+    activeFile.mode === 'diff'
+      ? detectLanguage(activeFile.relativePath)
+      : detectLanguage(activeFile.filePath)
+  const worktreeEntries = gitStatusByWorktree[activeFile.worktreeId] ?? []
+  const branchEntries = gitBranchChangesByWorktree[activeFile.worktreeId] ?? []
+  const matchingWorktreeEntry =
+    activeFile.mode === 'diff' && activeFile.diffSource !== 'branch'
+      ? (worktreeEntries.find(
+          (entry) =>
+            entry.path === activeFile.relativePath &&
+            (activeFile.diffSource === 'staged'
+              ? entry.area === 'staged'
+              : entry.area === 'unstaged')
+        ) ?? null)
+      : null
+  const matchingBranchEntry =
+    activeFile.mode === 'diff' && activeFile.diffSource === 'branch'
+      ? (branchEntries.find((entry) => entry.path === activeFile.relativePath) ?? null)
+      : null
+  const markdownViewModes = getMarkdownViewModes({
+    language: resolvedLanguage,
+    mode: activeFile.mode,
+    diffSource: activeFile.diffSource
+  })
+  const hasViewModeToggle = markdownViewModes.length > 0
+  const defaultMarkdownViewMode = getDefaultMarkdownViewMode({
+    language: resolvedLanguage,
+    mode: activeFile.mode,
+    diffSource: activeFile.diffSource
+  })
+  const storedMarkdownViewMode = markdownViewMode[activeFile.id]
+  const mdViewMode: MarkdownViewMode =
+    hasViewModeToggle &&
+    storedMarkdownViewMode !== undefined &&
+    markdownViewModes.includes(storedMarkdownViewMode)
+      ? storedMarkdownViewMode
+      : defaultMarkdownViewMode
+  const editorToggleModes = getEditorToggleModes({
+    language: resolvedLanguage,
+    mode: activeFile.mode,
+    diffSource: activeFile.diffSource
+  })
+  const isBinaryEditSurface =
+    activeFile.mode === 'edit' && fileContents[activeFile.id]?.isBinary === true
+  const availableEditorToggleModes =
+    isBinaryEditSurface || !canUseChangesModeForFile(activeFile)
+      ? editorToggleModes.filter((mode) => mode !== 'changes')
+      : editorToggleModes
+  const effectiveToggleValue: EditorToggleValue = isChangesMode
+    ? 'changes'
+    : hasViewModeToggle
+      ? mdViewMode
+      : 'edit'
+  return {
+    isSingleDiff,
+    isDiffSurface: isSingleDiff || isChangesMode,
+    isCombinedDiff,
+    worktreeEntries,
+    resolvedLanguage,
+    openFileState: getEditorHeaderOpenFileState(
+      activeFile,
+      matchingWorktreeEntry,
+      matchingBranchEntry
+    ),
+    isMarkdown: resolvedLanguage === 'markdown',
+    isMermaid: resolvedLanguage === 'mermaid',
+    isCsv: resolvedLanguage === 'csv' || resolvedLanguage === 'tsv',
+    isNotebook: resolvedLanguage === 'notebook',
+    canOpenPreviewToSide: activeFile.mode === 'edit' && canPreviewLanguage(resolvedLanguage),
+    mdViewMode,
+    hasViewModeToggle,
+    availableEditorToggleModes,
+    hasEditorToggle: availableEditorToggleModes.length > 1,
+    effectiveToggleValue,
+    isMarkdownTableOfContentsDisabled: hasViewModeToggle && mdViewMode === 'source',
+    canShowMarkdownTableOfContents:
+      resolvedLanguage === 'markdown' &&
+      (hasViewModeToggle || activeFile.mode === 'markdown-preview'),
+    canShowMarkdownPreview: canOpenMarkdownPreview({
+      language: resolvedLanguage,
+      mode: activeFile.mode,
+      diffSource: activeFile.diffSource
+    })
+  }
+}
diff --git a/src/renderer/src/components/editor/useClosedEditorTabCleanup.ts b/src/renderer/src/components/editor/useClosedEditorTabCleanup.ts
new file mode 100644
index 00000000000..99cd6e199c7
--- /dev/null
+++ b/src/renderer/src/components/editor/useClosedEditorTabCleanup.ts
@@ -0,0 +1,62 @@
+import { useEffect, useRef } from 'react'
+import * as monaco from 'monaco-editor'
+import type { OpenFile } from '@/store/slices/editor'
+import { cursorPositionCache, diffViewStateCache, scrollTopCache } from '@/lib/scroll-cache'
+
+function deleteCacheEntriesByPrefix<T>(cache: Map<string, T>, prefix: string): void {
+  for (const key of cache.keys()) {
+    if (key.startsWith(prefix)) {
+      cache.delete(key)
+    }
+  }
+}
+
+export function useClosedEditorTabCleanup(openFiles: OpenFile[]): void {
+  const prevOpenFilesRef = useRef<Map<string, OpenFile>>(new Map())
+
+  useEffect(() => {
+    const currentFilesById = new Map(openFiles.map((f) => [f.id, f]))
+    for (const [prevId, prevFile] of prevOpenFilesRef.current) {
+      if (!currentFilesById.has(prevId)) {
+        disposeClosedEditorTab(prevId, prevFile)
+      }
+    }
+    prevOpenFilesRef.current = currentFilesById
+  }, [openFiles])
+}
+
+function disposeClosedEditorTab(prevId: string, prevFile: OpenFile): void {
+  switch (prevFile.mode) {
+    case 'edit':
+      // Why: the edit model URI is constructed via monaco.Uri.parse(filePath)
+      // to match @monaco-editor/react's `path` prop convention.
+      monaco.editor.getModel(monaco.Uri.parse(prevFile.filePath))?.dispose()
+      scrollTopCache.delete(prevFile.filePath)
+      deleteCacheEntriesByPrefix(scrollTopCache, `${prevFile.filePath}::`)
+      // Why: markdown and mermaid surfaces keep mode-scoped scroll positions.
+      scrollTopCache.delete(`${prevFile.filePath}:rich`)
+      scrollTopCache.delete(`${prevFile.filePath}:preview`)
+      scrollTopCache.delete(`${prevFile.filePath}:mermaid-diagram`)
+      cursorPositionCache.delete(prevFile.filePath)
+      deleteCacheEntriesByPrefix(cursorPositionCache, `${prevFile.filePath}::`)
+      break
+    case 'markdown-preview':
+      // Why: preview tabs own pane-scoped preview scroll cache entries even
+      // though they do not retain Monaco models.
+      scrollTopCache.delete(`${prevFile.id}:preview`)
+      deleteCacheEntriesByPrefix(scrollTopCache, `${prevFile.id}::`)
+      break
+    case 'diff':
+      // Why: kept diff models are keyed by tab id because one file can appear
+      // in multiple diff tabs with different contents.
+      monaco.editor.getModel(monaco.Uri.parse(`diff:original:${prevId}`))?.dispose()
+      monaco.editor.getModel(monaco.Uri.parse(`diff:modified:${prevId}`))?.dispose()
+      diffViewStateCache.delete(prevId)
+      deleteCacheEntriesByPrefix(diffViewStateCache, `${prevId}::`)
+      scrollTopCache.delete(`${prevId}:preview`)
+      deleteCacheEntriesByPrefix(scrollTopCache, `${prevId}::`)
+      break
+    case 'conflict-review':
+      break
+  }
+}
diff --git a/src/renderer/src/components/editor/useEditorCmdSaveRequest.ts b/src/renderer/src/components/editor/useEditorCmdSaveRequest.ts
new file mode 100644
index 00000000000..f89a0ef24f8
--- /dev/null
+++ b/src/renderer/src/components/editor/useEditorCmdSaveRequest.ts
@@ -0,0 +1,50 @@
+import { useEffect } from 'react'
+import { useAppStore } from '@/store'
+import type { OpenFile } from '@/store/slices/editor'
+import { ORCA_EDITOR_REQUEST_CMD_SAVE_EVENT } from './editor-autosave'
+import type { FileContent } from './editor-panel-content-types'
+
+type UseEditorCmdSaveRequestParams = {
+  activeFile: OpenFile | null
+  openFiles: OpenFile[]
+  fileContents: Record<string, FileContent>
+  handleSave: (content: string) => Promise<void>
+}
+
+export function useEditorCmdSaveRequest({
+  activeFile,
+  openFiles,
+  fileContents,
+  handleSave
+}: UseEditorCmdSaveRequestParams): void {
+  useEffect(() => {
+    const handler = (): void => {
+      if (!activeFile) {
+        return
+      }
+      const saveTargetFile =
+        activeFile.mode === 'markdown-preview'
+          ? (openFiles.find(
+              (openFile) =>
+                openFile.id === activeFile.markdownPreviewSourceFileId && openFile.mode === 'edit'
+            ) ?? null)
+          : activeFile
+      if (!saveTargetFile) {
+        return
+      }
+      // Why: a markdown preview tab is read-only but fronts the same document,
+      // so Cmd/Ctrl+S should save the source editor's current draft.
+      const state = useAppStore.getState()
+      const draft = state.editorDrafts[saveTargetFile.id]
+      if (!draft && !saveTargetFile.isUntitled && !saveTargetFile.isDirty) {
+        return
+      }
+      const fallbackContent =
+        draft ??
+        (activeFile.mode === 'markdown-preview' ? fileContents[activeFile.id]?.content : '')
+      void handleSave(fallbackContent ?? '')
+    }
+    window.addEventListener(ORCA_EDITOR_REQUEST_CMD_SAVE_EVENT, handler)
+    return () => window.removeEventListener(ORCA_EDITOR_REQUEST_CMD_SAVE_EVENT, handler)
+  }, [activeFile, fileContents, handleSave, openFiles])
+}
diff --git a/src/renderer/src/components/editor/useEditorPanelContentState.ts b/src/renderer/src/components/editor/useEditorPanelContentState.ts
new file mode 100644
index 00000000000..f26154be5cd
--- /dev/null
+++ b/src/renderer/src/components/editor/useEditorPanelContentState.ts
@@ -0,0 +1,289 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { OpenFile } from '@/store/slices/editor'
+import { getConnectionId } from '@/lib/connection-context'
+import { useAppStore } from '@/store'
+import { getRuntimeFileReadScope, readRuntimeFileContent } from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+import {
+  getRuntimeGitBranchDiff,
+  getRuntimeGitDiff,
+  getRuntimeGitScope
+} from '@/runtime/runtime-git-client'
+import type { DiffContent, FileContent } from './editor-panel-content-types'
+import { canUseChangesModeForFile } from './editor-panel-file-mode'
+import {
+  useEditorPanelExternalContentEvents,
+  usePruneClosedEditorContent
+} from './useEditorPanelExternalContentEvents'
+import { useEditorPanelFileLoadRetry } from './useEditorPanelFileLoadRetry'
+
+const inFlightFileReads = new Map<string, Promise<FileContent>>()
+const inFlightDiffReads = new Map<string, Promise<DiffContent>>()
+
+type GitStatusByWorktree = ReturnType<typeof useAppStore.getState>['gitStatusByWorktree']
+type EditorViewModeByFile = ReturnType<typeof useAppStore.getState>['editorViewMode']
+
+type UseEditorPanelContentStateParams = {
+  activeFile: OpenFile | null
+  isChangesMode: boolean
+  openFiles: OpenFile[]
+  gitStatusByWorktree: GitStatusByWorktree
+  editorViewMode: EditorViewModeByFile
+}
+
+type UseEditorPanelContentStateResult = {
+  fileContents: Record<string, FileContent>
+  diffContents: Record<string, DiffContent>
+  reloadFileContent: (file: OpenFile) => void
+}
+
+function inFlightReadKey(connectionId: string | undefined, filePath: string): string {
+  return `${connectionId ?? ''}::${filePath}`
+}
+
+function inFlightDiffKey(
+  file: OpenFile,
+  connectionId: string | undefined,
+  compareAgainstHead = false
+): string {
+  const branch =
+    file.diffSource === 'branch' && file.branchCompare
+      ? `${file.branchCompare.baseOid ?? ''}..${file.branchCompare.headOid ?? ''}::${file.branchOldPath ?? ''}`
+      : ''
+  return `${connectionId ?? ''}::${file.diffSource ?? ''}::${compareAgainstHead ? 'head' : 'default'}::${file.filePath}::${branch}`
+}
+
+export function useEditorPanelContentState({
+  activeFile,
+  isChangesMode,
+  openFiles,
+  gitStatusByWorktree,
+  editorViewMode
+}: UseEditorPanelContentStateParams): UseEditorPanelContentStateResult {
+  const [fileContents, setFileContents] = useState<Record<string, FileContent>>({})
+  const [diffContents, setDiffContents] = useState<Record<string, DiffContent>>({})
+  const fileLoadRetryAttemptsRef = useRef<Record<string, number>>({})
+  const openFilesRef = useRef(openFiles)
+  openFilesRef.current = openFiles
+  const editorViewModeRef = useRef(editorViewMode)
+  editorViewModeRef.current = editorViewMode
+
+  const loadFileContent = useCallback(
+    async (filePath: string, id: string, worktreeId?: string): Promise<void> => {
+      try {
+        const connectionId = getConnectionId(worktreeId ?? null) ?? undefined
+        const restoredOpenFile = openFilesRef.current.find((file) => file.id === id)
+        const activeSettings = useAppStore.getState().settings
+        const readSettings = settingsForRuntimeOwner(
+          activeSettings,
+          restoredOpenFile?.runtimeEnvironmentId
+        )
+        if (restoredOpenFile?.filePath === filePath && restoredOpenFile.relativePath === filePath) {
+          if (readSettings?.activeRuntimeEnvironmentId?.trim() || connectionId) {
+            // Why: restored external-file tabs contain client-local absolute
+            // paths. Remote runtime and SSH workspaces cannot read those paths
+            // without an explicit upload/import flow.
+            throw new Error('External local files are not available for remote workspaces.')
+          }
+          // Why: restored external-file tabs need their main-process path grant
+          // refreshed because that authorization is only held in memory.
+          await window.api.fs.authorizeExternalPath({ targetPath: filePath })
+        }
+        const readScope = getRuntimeFileReadScope(readSettings, connectionId)
+        const key = inFlightReadKey(readScope, filePath)
+        let pending = inFlightFileReads.get(key)
+        if (!pending) {
+          pending = readRuntimeFileContent({
+            settings: readSettings,
+            filePath,
+            relativePath: restoredOpenFile?.relativePath,
+            worktreeId,
+            connectionId
+          }) as Promise<FileContent>
+          inFlightFileReads.set(key, pending)
+          queueMicrotask(() => {
+            if (inFlightFileReads.get(key) === pending) {
+              inFlightFileReads.delete(key)
+            }
+          })
+        }
+        const result = await pending
+        delete fileLoadRetryAttemptsRef.current[id]
+        setFileContents((prev) => ({ ...prev, [id]: result }))
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        setFileContents((prev) => ({
+          ...prev,
+          [id]: { content: '', isBinary: false, loadError: message }
+        }))
+      }
+    },
+    []
+  )
+
+  const loadDiffContent = useCallback(async (file: OpenFile | null): Promise<void> => {
+    if (!file || (file.mode === 'edit' && !canUseChangesModeForFile(file))) {
+      return
+    }
+    try {
+      const worktreePath = file.filePath.slice(
+        0,
+        file.filePath.length - file.relativePath.length - 1
+      )
+      const branchCompare =
+        file.branchCompare?.baseOid && file.branchCompare.headOid && file.branchCompare.mergeBase
+          ? file.branchCompare
+          : null
+      const connectionId = getConnectionId(file.worktreeId) ?? undefined
+      const activeSettings = useAppStore.getState().settings
+      const fileSettings = settingsForRuntimeOwner(activeSettings, file.runtimeEnvironmentId)
+      const gitScope = getRuntimeGitScope(fileSettings, connectionId)
+      const effectiveDiffSource: typeof file.diffSource =
+        file.mode === 'edit' ? 'unstaged' : file.diffSource
+      const compareAgainstHead = file.mode === 'edit'
+      const key = inFlightDiffKey(
+        { ...file, diffSource: effectiveDiffSource },
+        gitScope,
+        compareAgainstHead
+      )
+      let pending = inFlightDiffReads.get(key)
+      if (!pending) {
+        pending = (
+          effectiveDiffSource === 'branch' && branchCompare
+            ? getRuntimeGitBranchDiff(
+                {
+                  settings: fileSettings,
+                  worktreeId: file.worktreeId,
+                  worktreePath,
+                  connectionId
+                },
+                {
+                  compare: {
+                    baseRef: branchCompare.baseRef,
+                    baseOid: branchCompare.baseOid!,
+                    headOid: branchCompare.headOid!,
+                    mergeBase: branchCompare.mergeBase!
+                  },
+                  filePath: file.relativePath,
+                  oldPath: file.branchOldPath
+                }
+              )
+            : getRuntimeGitDiff(
+                {
+                  settings: fileSettings,
+                  worktreeId: file.worktreeId,
+                  worktreePath,
+                  connectionId
+                },
+                {
+                  filePath: file.relativePath,
+                  staged: effectiveDiffSource === 'staged',
+                  compareAgainstHead
+                }
+              )
+        ) as Promise<DiffContent>
+        inFlightDiffReads.set(key, pending)
+        queueMicrotask(() => {
+          if (inFlightDiffReads.get(key) === pending) {
+            inFlightDiffReads.delete(key)
+          }
+        })
+      }
+      const result = await pending
+      setDiffContents((prev) => ({ ...prev, [file.id]: result }))
+    } catch (err) {
+      setDiffContents((prev) => ({
+        ...prev,
+        [file.id]: {
+          kind: 'text',
+          originalContent: '',
+          modifiedContent: `Error loading diff: ${err}`,
+          originalIsBinary: false,
+          modifiedIsBinary: false
+        }
+      }))
+    }
+  }, [])
+
+  const reloadFileContent = useCallback(
+    (file: OpenFile): void => {
+      delete fileLoadRetryAttemptsRef.current[file.id]
+      setFileContents((prev) => {
+        if (!prev[file.id]) {
+          return prev
+        }
+        const next = { ...prev }
+        delete next[file.id]
+        return next
+      })
+      void loadFileContent(file.filePath, file.id, file.worktreeId)
+    },
+    [loadFileContent]
+  )
+
+  useEffect(() => {
+    if (!activeFile || activeFile.mode === 'conflict-review') {
+      return
+    }
+    if (activeFile.mode === 'edit' || activeFile.mode === 'markdown-preview') {
+      if (activeFile.conflict?.kind === 'conflict-placeholder') {
+        return
+      }
+      if (!fileContents[activeFile.id]) {
+        void loadFileContent(activeFile.filePath, activeFile.id, activeFile.worktreeId)
+      }
+      if (isChangesMode && !diffContents[activeFile.id]) {
+        void loadDiffContent(activeFile)
+      }
+    } else if (
+      activeFile.mode === 'diff' &&
+      activeFile.diffSource !== undefined &&
+      activeFile.diffSource !== 'combined-uncommitted' &&
+      activeFile.diffSource !== 'combined-branch' &&
+      !diffContents[activeFile.id]
+    ) {
+      void loadDiffContent(activeFile)
+    }
+  }, [activeFile?.id, isChangesMode]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEditorPanelFileLoadRetry({
+    activeFile,
+    fileContents,
+    fileLoadRetryAttemptsRef,
+    loadFileContent,
+    openFilesRef,
+    setFileContents
+  })
+
+  const changesStatusEntries = activeFile?.worktreeId
+    ? gitStatusByWorktree[activeFile.worktreeId]
+    : undefined
+  useEffect(() => {
+    if (!isChangesMode || !activeFile?.id) {
+      return
+    }
+    const current = openFilesRef.current.find((f) => f.id === activeFile.id)
+    if (current) {
+      void loadDiffContent(current)
+    }
+  }, [
+    changesStatusEntries,
+    isChangesMode,
+    activeFile?.id,
+    activeFile?.worktreeId,
+    activeFile?.relativePath,
+    loadDiffContent
+  ])
+
+  useEditorPanelExternalContentEvents({
+    loadDiffContent,
+    loadFileContent,
+    openFilesRef,
+    editorViewModeRef,
+    setFileContents,
+    setDiffContents
+  })
+  usePruneClosedEditorContent(openFiles, fileLoadRetryAttemptsRef, setFileContents, setDiffContents)
+
+  return { fileContents, diffContents, reloadFileContent }
+}
diff --git a/src/renderer/src/components/editor/useEditorPanelExternalContentEvents.ts b/src/renderer/src/components/editor/useEditorPanelExternalContentEvents.ts
new file mode 100644
index 00000000000..bf82c7bbc09
--- /dev/null
+++ b/src/renderer/src/components/editor/useEditorPanelExternalContentEvents.ts
@@ -0,0 +1,132 @@
+import { useEffect, type Dispatch, type MutableRefObject, type SetStateAction } from 'react'
+import type { useAppStore } from '@/store'
+import type { OpenFile } from '@/store/slices/editor'
+import {
+  getOpenFilesForExternalFileChange,
+  ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT,
+  ORCA_EDITOR_FILE_SAVED_EVENT,
+  type EditorFileSavedDetail,
+  type EditorPathMutationTarget
+} from './editor-autosave'
+import type { DiffContent, FileContent } from './editor-panel-content-types'
+
+type EditorViewModeByFile = ReturnType<typeof useAppStore.getState>['editorViewMode']
+
+type UseEditorPanelExternalContentEventsParams = {
+  loadDiffContent: (file: OpenFile | null) => Promise<void>
+  loadFileContent: (filePath: string, id: string, worktreeId?: string) => Promise<void>
+  openFilesRef: MutableRefObject<OpenFile[]>
+  editorViewModeRef: MutableRefObject<EditorViewModeByFile>
+  setFileContents: Dispatch<SetStateAction<Record<string, FileContent>>>
+  setDiffContents: Dispatch<SetStateAction<Record<string, DiffContent>>>
+}
+
+export function useEditorPanelExternalContentEvents({
+  loadDiffContent,
+  loadFileContent,
+  openFilesRef,
+  editorViewModeRef,
+  setFileContents,
+  setDiffContents
+}: UseEditorPanelExternalContentEventsParams): void {
+  useEffect(() => {
+    const handler = (event: Event): void => {
+      const detail = (event as CustomEvent<EditorPathMutationTarget>).detail
+      if (!detail) {
+        return
+      }
+      for (const file of getOpenFilesForExternalFileChange(openFilesRef.current, detail)) {
+        if (file.mode === 'edit' || file.mode === 'markdown-preview') {
+          void loadFileContent(file.filePath, file.id, file.worktreeId)
+          if (editorViewModeRef.current[file.id] === 'changes') {
+            void loadDiffContent(file)
+          }
+        } else if (
+          file.mode === 'diff' &&
+          file.diffSource !== 'combined-uncommitted' &&
+          file.diffSource !== 'combined-branch'
+        ) {
+          void loadDiffContent(file)
+        }
+      }
+    }
+    window.addEventListener(ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT, handler as EventListener)
+    return () =>
+      window.removeEventListener(ORCA_EDITOR_EXTERNAL_FILE_CHANGE_EVENT, handler as EventListener)
+  }, [editorViewModeRef, loadDiffContent, loadFileContent, openFilesRef])
+
+  useEffect(() => {
+    const handler = (event: Event): void => {
+      const detail = (event as CustomEvent<EditorFileSavedDetail>).detail
+      if (!detail) {
+        return
+      }
+      const file = openFilesRef.current.find((openFile) => openFile.id === detail.fileId)
+      if (!file) {
+        return
+      }
+      if (file.mode === 'edit' || file.mode === 'markdown-preview') {
+        setFileContents((prev) => ({
+          ...prev,
+          [file.id]: { content: detail.content, isBinary: false }
+        }))
+      }
+      updateSavedPreviewTabs(openFilesRef.current, detail, setFileContents)
+      if (file.mode === 'edit' || file.mode === 'markdown-preview') {
+        return
+      }
+      setDiffContents((prev) => {
+        const existing = prev[file.id]
+        if (!existing || existing.kind !== 'text') {
+          return prev
+        }
+        return { ...prev, [file.id]: { ...existing, modifiedContent: detail.content } }
+      })
+    }
+    window.addEventListener(ORCA_EDITOR_FILE_SAVED_EVENT, handler as EventListener)
+    return () => window.removeEventListener(ORCA_EDITOR_FILE_SAVED_EVENT, handler as EventListener)
+  }, [openFilesRef, setDiffContents, setFileContents])
+}
+
+function updateSavedPreviewTabs(
+  openFiles: OpenFile[],
+  detail: EditorFileSavedDetail,
+  setFileContents: Dispatch<SetStateAction<Record<string, FileContent>>>
+): void {
+  const previewTabs = openFiles.filter(
+    (openFile) =>
+      openFile.mode === 'markdown-preview' && openFile.markdownPreviewSourceFileId === detail.fileId
+  )
+  if (previewTabs.length === 0) {
+    return
+  }
+  setFileContents((prev) => {
+    const next = { ...prev }
+    for (const previewTab of previewTabs) {
+      next[previewTab.id] = { content: detail.content, isBinary: false }
+    }
+    return next
+  })
+}
+
+export function usePruneClosedEditorContent(
+  openFiles: OpenFile[],
+  fileLoadRetryAttemptsRef: MutableRefObject<Record<string, number>>,
+  setFileContents: Dispatch<SetStateAction<Record<string, FileContent>>>,
+  setDiffContents: Dispatch<SetStateAction<Record<string, DiffContent>>>
+): void {
+  useEffect(() => {
+    const openIds = new Set(openFiles.map((f) => f.id))
+    for (const fileId of Object.keys(fileLoadRetryAttemptsRef.current)) {
+      if (!openIds.has(fileId)) {
+        delete fileLoadRetryAttemptsRef.current[fileId]
+      }
+    }
+    setFileContents((prev) =>
+      Object.fromEntries(Object.entries(prev).filter(([key]) => openIds.has(key)))
+    )
+    setDiffContents((prev) =>
+      Object.fromEntries(Object.entries(prev).filter(([key]) => openIds.has(key)))
+    )
+  }, [fileLoadRetryAttemptsRef, openFiles, setDiffContents, setFileContents])
+}
diff --git a/src/renderer/src/components/editor/useEditorPanelFileLoadRetry.ts b/src/renderer/src/components/editor/useEditorPanelFileLoadRetry.ts
new file mode 100644
index 00000000000..0c9f7bff42c
--- /dev/null
+++ b/src/renderer/src/components/editor/useEditorPanelFileLoadRetry.ts
@@ -0,0 +1,80 @@
+import { useEffect, type Dispatch, type MutableRefObject, type SetStateAction } from 'react'
+import type { OpenFile } from '@/store/slices/editor'
+import type { FileContent } from './editor-panel-content-types'
+
+const FILE_LOAD_RETRY_DELAYS_MS = [250, 1000, 2500]
+
+type UseEditorPanelFileLoadRetryParams = {
+  activeFile: OpenFile | null
+  fileContents: Record<string, FileContent>
+  fileLoadRetryAttemptsRef: MutableRefObject<Record<string, number>>
+  loadFileContent: (filePath: string, id: string, worktreeId?: string) => Promise<void>
+  openFilesRef: MutableRefObject<OpenFile[]>
+  setFileContents: Dispatch<SetStateAction<Record<string, FileContent>>>
+}
+
+function shouldRetryFileLoadError(message: string): boolean {
+  const lower = message.toLowerCase()
+  return (
+    !lower.includes('access denied') &&
+    !lower.includes('enoent') &&
+    !lower.includes('no such file') &&
+    !lower.includes('file too large')
+  )
+}
+
+export function useEditorPanelFileLoadRetry({
+  activeFile,
+  fileContents,
+  fileLoadRetryAttemptsRef,
+  loadFileContent,
+  openFilesRef,
+  setFileContents
+}: UseEditorPanelFileLoadRetryParams): void {
+  const activeFileLoadRetryId = activeFile?.id ?? null
+  const activeFileLoadError = activeFileLoadRetryId
+    ? fileContents[activeFileLoadRetryId]?.loadError
+    : undefined
+
+  useEffect(() => {
+    if (
+      !activeFileLoadRetryId ||
+      !activeFileLoadError ||
+      !shouldRetryFileLoadError(activeFileLoadError)
+    ) {
+      return
+    }
+    const retryCount = fileLoadRetryAttemptsRef.current[activeFileLoadRetryId] ?? 0
+    if (retryCount >= FILE_LOAD_RETRY_DELAYS_MS.length) {
+      return
+    }
+    const delayMs = FILE_LOAD_RETRY_DELAYS_MS[retryCount] ?? FILE_LOAD_RETRY_DELAYS_MS[0]
+    fileLoadRetryAttemptsRef.current[activeFileLoadRetryId] = retryCount + 1
+    const timeoutId = window.setTimeout(() => {
+      const currentFile = openFilesRef.current.find((file) => file.id === activeFileLoadRetryId)
+      if (
+        !currentFile ||
+        (currentFile.mode !== 'edit' && currentFile.mode !== 'markdown-preview')
+      ) {
+        return
+      }
+      setFileContents((prev) => {
+        if (prev[currentFile.id]?.loadError !== activeFileLoadError) {
+          return prev
+        }
+        const next = { ...prev }
+        delete next[currentFile.id]
+        return next
+      })
+      void loadFileContent(currentFile.filePath, currentFile.id, currentFile.worktreeId)
+    }, delayMs)
+    return () => window.clearTimeout(timeoutId)
+  }, [
+    activeFileLoadRetryId,
+    activeFileLoadError,
+    fileLoadRetryAttemptsRef,
+    loadFileContent,
+    openFilesRef,
+    setFileContents
+  ])
+}
diff --git a/src/renderer/src/components/editor/useMarkdownPreviewShortcut.ts b/src/renderer/src/components/editor/useMarkdownPreviewShortcut.ts
new file mode 100644
index 00000000000..cc60f0e4089
--- /dev/null
+++ b/src/renderer/src/components/editor/useMarkdownPreviewShortcut.ts
@@ -0,0 +1,80 @@
+import { useEffect, type RefObject } from 'react'
+import { detectLanguage } from '@/lib/language-detect'
+import type { OpenFile } from '@/store/slices/editor'
+import { canOpenMarkdownPreview, isMarkdownPreviewShortcut } from './markdown-preview-controls'
+
+type UseMarkdownPreviewShortcutParams = {
+  activeFile: OpenFile | null
+  panelRef: RefObject<HTMLDivElement | null>
+  isMac: boolean
+  openMarkdownPreview: (file: {
+    filePath: string
+    relativePath: string
+    worktreeId: string
+    runtimeEnvironmentId?: string
+    language: string
+  }) => void
+}
+
+export function useMarkdownPreviewShortcut({
+  activeFile,
+  panelRef,
+  isMac,
+  openMarkdownPreview
+}: UseMarkdownPreviewShortcutParams): void {
+  const activeFilePath = activeFile?.filePath ?? null
+  const activeFileRelativePath = activeFile?.relativePath ?? null
+  const activeFileWorktreeId = activeFile?.worktreeId ?? null
+  const activeFileMode = activeFile?.mode ?? null
+  const activeFileDiffSource = activeFile?.diffSource
+  const activeFileRuntimeEnvironmentId = activeFile?.runtimeEnvironmentId
+
+  useEffect(() => {
+    if (!activeFilePath || !activeFileRelativePath || !activeFileWorktreeId || !activeFileMode) {
+      return
+    }
+    const shortcutLanguage =
+      activeFileMode === 'diff'
+        ? detectLanguage(activeFileRelativePath)
+        : detectLanguage(activeFilePath)
+    const canShowMarkdownPreview = canOpenMarkdownPreview({
+      language: shortcutLanguage,
+      mode: activeFileMode,
+      diffSource: activeFileDiffSource
+    })
+    if (!canShowMarkdownPreview) {
+      return
+    }
+    const handleKeyDown = (event: KeyboardEvent): void => {
+      if (event.defaultPrevented || !isMarkdownPreviewShortcut(event, isMac)) {
+        return
+      }
+      const root = panelRef.current
+      const target = event.target
+      if (!root || !(target instanceof Node) || !root.contains(target)) {
+        return
+      }
+      event.preventDefault()
+      event.stopPropagation()
+      openMarkdownPreview({
+        filePath: activeFilePath,
+        relativePath: activeFileRelativePath,
+        worktreeId: activeFileWorktreeId,
+        runtimeEnvironmentId: activeFileRuntimeEnvironmentId,
+        language: shortcutLanguage
+      })
+    }
+    window.addEventListener('keydown', handleKeyDown, { capture: true })
+    return () => window.removeEventListener('keydown', handleKeyDown, { capture: true })
+  }, [
+    activeFileDiffSource,
+    activeFileMode,
+    activeFilePath,
+    activeFileRelativePath,
+    activeFileRuntimeEnvironmentId,
+    activeFileWorktreeId,
+    isMac,
+    openMarkdownPreview,
+    panelRef
+  ])
+}
diff --git a/src/renderer/src/components/editor/useUntitledFileRename.ts b/src/renderer/src/components/editor/useUntitledFileRename.ts
new file mode 100644
index 00000000000..a301ce6811a
--- /dev/null
+++ b/src/renderer/src/components/editor/useUntitledFileRename.ts
@@ -0,0 +1,135 @@
+import { useCallback, useState } from 'react'
+import { getConnectionId } from '@/lib/connection-context'
+import { detectLanguage } from '@/lib/language-detect'
+import { dirname, joinPath } from '@/lib/path'
+import { useAppStore } from '@/store'
+import type { OpenFile } from '@/store/slices/editor'
+import {
+  createRuntimePath,
+  renameRuntimePath,
+  runtimePathExists
+} from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+import { requestEditorFileSave, requestEditorSaveQuiesce } from './editor-autosave'
+
+type UseUntitledFileRenameParams = {
+  openFiles: OpenFile[]
+  closeFile: (filePath: string) => void
+  openFile: (file: {
+    filePath: string
+    relativePath: string
+    worktreeId: string
+    runtimeEnvironmentId?: string
+    language: string
+    mode: 'edit'
+  }) => void
+  clearUntitled: (fileId: string) => void
+}
+
+type UseUntitledFileRenameResult = {
+  renameDialogFileId: string | null
+  renameDialogFile: OpenFile | null
+  renameError: string | null
+  requestRenameForFile: (fileId: string) => void
+  closeRenameDialog: () => void
+  handleRenameConfirm: (newRelPath: string) => Promise<void>
+}
+
+export function useUntitledFileRename({
+  openFiles,
+  closeFile,
+  openFile,
+  clearUntitled
+}: UseUntitledFileRenameParams): UseUntitledFileRenameResult {
+  const [renameDialogFileId, setRenameDialogFileId] = useState<string | null>(null)
+  const [renameError, setRenameError] = useState<string | null>(null)
+  const renameDialogFile = renameDialogFileId
+    ? (openFiles.find((f) => f.id === renameDialogFileId) ?? null)
+    : null
+
+  const closeRenameDialog = useCallback((): void => {
+    setRenameDialogFileId(null)
+    setRenameError(null)
+  }, [])
+
+  const handleRenameConfirm = useCallback(
+    async (newRelPath: string) => {
+      if (!renameDialogFile) {
+        return
+      }
+      const oldPath = renameDialogFile.filePath
+      // Why: derive the worktree root from the old relative path so nested
+      // untitled saves resolve relative to the worktree, not the current folder.
+      const worktreeRoot = oldPath.slice(
+        0,
+        oldPath.length - renameDialogFile.relativePath.length - 1
+      )
+      const newPath = joinPath(worktreeRoot, newRelPath)
+      const connectionId = getConnectionId(renameDialogFile.worktreeId) ?? undefined
+      const fileContext = {
+        settings: settingsForRuntimeOwner(
+          useAppStore.getState().settings,
+          renameDialogFile.runtimeEnvironmentId
+        ),
+        worktreeId: renameDialogFile.worktreeId,
+        worktreePath: worktreeRoot,
+        connectionId
+      }
+
+      if (newPath !== oldPath && (await runtimePathExists(fileContext, newPath))) {
+        setRenameError('A file with that name already exists')
+        return
+      }
+
+      await requestEditorSaveQuiesce({ fileId: renameDialogFile.id })
+      const draft = useAppStore.getState().editorDrafts[renameDialogFile.id]
+      if (draft !== undefined) {
+        try {
+          await requestEditorFileSave({ fileId: renameDialogFile.id, fallbackContent: draft })
+        } catch {
+          setRenameError('Failed to save file')
+          return
+        }
+      }
+
+      if (newPath === oldPath) {
+        clearUntitled(renameDialogFile.id)
+        closeRenameDialog()
+        return
+      }
+
+      const newDir = dirname(newPath)
+      if (newDir !== worktreeRoot && !(await runtimePathExists(fileContext, newDir))) {
+        await createRuntimePath(fileContext, newDir, 'directory')
+      }
+
+      try {
+        await renameRuntimePath(fileContext, oldPath, newPath)
+      } catch (err) {
+        setRenameError(err instanceof Error ? err.message : 'Failed to rename file')
+        return
+      }
+
+      closeFile(oldPath)
+      openFile({
+        filePath: newPath,
+        relativePath: newRelPath,
+        worktreeId: renameDialogFile.worktreeId,
+        runtimeEnvironmentId: renameDialogFile.runtimeEnvironmentId,
+        language: detectLanguage(newRelPath),
+        mode: 'edit'
+      })
+      closeRenameDialog()
+    },
+    [clearUntitled, closeFile, closeRenameDialog, openFile, renameDialogFile]
+  )
+
+  return {
+    renameDialogFileId,
+    renameDialogFile,
+    renameError,
+    requestRenameForFile: setRenameDialogFileId,
+    closeRenameDialog,
+    handleRenameConfirm
+  }
+}

From 60656e7a6ee367702e3ef91209007e0090dbf7fb Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 15 May 2026 10:50:22 -0700
Subject: [PATCH 36/82] Improve PTY exhaustion recovery messages (#1931)

Co-authored-by: Orca <help@stably.ai>
---
 src/main/daemon/node-pty-error-hints.test.ts | 52 +++++++++++++++---
 src/main/daemon/node-pty-error-hints.ts      | 55 ++++++++++++++++++--
 2 files changed, 96 insertions(+), 11 deletions(-)

diff --git a/src/main/daemon/node-pty-error-hints.test.ts b/src/main/daemon/node-pty-error-hints.test.ts
index 1b36eada05a..249cc167131 100644
--- a/src/main/daemon/node-pty-error-hints.test.ts
+++ b/src/main/daemon/node-pty-error-hints.test.ts
@@ -1,6 +1,22 @@
 import { describe, expect, it } from 'vitest'
 import { addNodePtyRecoveryHint, parseNodePtyDiagnostic } from './node-pty-error-hints'
 
+const PTY_ALLOCATION_HINT = [
+  'Your system cannot allocate any more pty devices.',
+  '',
+  'Orca requires a pty device to launch a new terminal. This error is usually due to having too many terminal windows or terminal sessions open, either in Orca or another program.',
+  '',
+  'Free up some pty devices and try again.'
+].join('\n')
+
+const TERMINAL_PROCESS_LIMIT_HINT = [
+  'Your system cannot start another terminal process.',
+  '',
+  'This is usually due to having too many terminal sessions or other processes running.',
+  '',
+  'Close unused terminals or quit unused processes and try again.'
+].join('\n')
+
 describe('node-pty diagnostic error hints', () => {
   it('parses the native step and errno without dropping the original message', () => {
     const message =
@@ -16,18 +32,42 @@ describe('node-pty diagnostic error hints', () => {
     const message =
       "node-pty: open_slave failed: EMFILE (errno 24, Too many open files) - slave='/dev/ttys003'"
 
-    expect(addNodePtyRecoveryHint(message)).toBe(
-      `Daemon hit the file-descriptor limit. Restart the daemon. ${message}`
-    )
+    expect(addNodePtyRecoveryHint(message)).toBe(`${PTY_ALLOCATION_HINT} ${message}`)
+  })
+
+  it('hints when the system cannot allocate a pty master', () => {
+    const message =
+      'node-pty: posix_openpt failed: ENFILE (errno 23, Too many open files in system)'
+
+    expect(addNodePtyRecoveryHint(message)).toBe(`${PTY_ALLOCATION_HINT} ${message}`)
+  })
+
+  it('hints local wrapped spawn errors from pty allocation failures', () => {
+    const message =
+      'Failed to spawn shell "/bin/zsh": node-pty: open_slave failed: EMFILE (errno 24, Too many open files) - slave=\'/dev/ttys003\' (shell: /bin/zsh, cwd: /tmp, arch: arm64, platform: darwin 25.0.0). If this persists, please file an issue.'
+
+    expect(addNodePtyRecoveryHint(message)).toBe(`${PTY_ALLOCATION_HINT} ${message}`)
+  })
+
+  it('hints unstructured openpty allocation failures', () => {
+    const message = 'Failed to spawn shell "/bin/bash": openpty(3) failed.'
+
+    expect(addNodePtyRecoveryHint(message)).toBe(`${PTY_ALLOCATION_HINT} ${message}`)
   })
 
   it('hints when posix_spawn reports the per-user process limit', () => {
     const message =
       "node-pty: posix_spawn failed: EAGAIN (errno 35, Resource temporarily unavailable) - helper='/tmp/node-pty/spawn-helper'"
 
-    expect(addNodePtyRecoveryHint(message)).toBe(
-      `Per-user process limit reached. Quit some agents and retry. ${message}`
-    )
+    expect(addNodePtyRecoveryHint(message)).toBe(`${TERMINAL_PROCESS_LIMIT_HINT} ${message}`)
+  })
+
+  it('does not duplicate an existing recovery hint', () => {
+    const message =
+      "node-pty: open_slave failed: EMFILE (errno 24, Too many open files) - slave='/dev/ttys003'"
+    const hinted = `${PTY_ALLOCATION_HINT} ${message}`
+
+    expect(addNodePtyRecoveryHint(hinted)).toBe(hinted)
   })
 
   it('leaves unrelated and unhinted node-pty diagnostics unchanged', () => {
diff --git a/src/main/daemon/node-pty-error-hints.ts b/src/main/daemon/node-pty-error-hints.ts
index 97c13baf5d9..a440a27639a 100644
--- a/src/main/daemon/node-pty-error-hints.ts
+++ b/src/main/daemon/node-pty-error-hints.ts
@@ -4,9 +4,45 @@ export type NodePtyDiagnostic = {
 }
 
 const NODE_PTY_DIAGNOSTIC_RE = /^node-pty: ([A-Za-z0-9_]+) failed: .*?\(errno (\d+)(?:, [^)]*)?\)/
+const NODE_PTY_DIAGNOSTIC_ANYWHERE_RE =
+  /node-pty: ([A-Za-z0-9_]+) failed: .*?\(errno (\d+)(?:, [^)]*)?\)/
+const GENERIC_PTY_ALLOCATION_RE = /\b(?:openpty|forkpty)\(3\) failed\b/i
+
+const PTY_ALLOCATION_STEPS = new Set([
+  'posix_openpt',
+  'grantpt',
+  'unlockpt',
+  'ioctl_TIOCPTYGNAME',
+  'open_slave'
+])
+
+const RESOURCE_EXHAUSTION_ERRNOS = new Set([
+  11, // EAGAIN on Linux
+  12, // ENOMEM
+  23, // ENFILE on macOS
+  24, // EMFILE on macOS/Linux
+  35 // EAGAIN on macOS
+])
+
+const PTY_ALLOCATION_HINT = [
+  'Your system cannot allocate any more pty devices.',
+  '',
+  'Orca requires a pty device to launch a new terminal. This error is usually due to having too many terminal windows or terminal sessions open, either in Orca or another program.',
+  '',
+  'Free up some pty devices and try again.'
+].join('\n')
+
+const TERMINAL_PROCESS_LIMIT_HINT = [
+  'Your system cannot start another terminal process.',
+  '',
+  'This is usually due to having too many terminal sessions or other processes running.',
+  '',
+  'Close unused terminals or quit unused processes and try again.'
+].join('\n')
 
 export function parseNodePtyDiagnostic(message: string): NodePtyDiagnostic | null {
-  const match = NODE_PTY_DIAGNOSTIC_RE.exec(message)
+  const match =
+    NODE_PTY_DIAGNOSTIC_RE.exec(message) ?? NODE_PTY_DIAGNOSTIC_ANYWHERE_RE.exec(message)
   if (!match) {
     return null
   }
@@ -21,11 +57,14 @@ export function getNodePtyRecoveryHint(diagnostic: NodePtyDiagnostic): string |
   if (diagnostic.step === 'posix_spawn' && diagnostic.errno === 2) {
     return "Daemon's node-pty install is gone (worktree deleted?). Restart Orca."
   }
-  if (diagnostic.step === 'open_slave' && diagnostic.errno === 24) {
-    return 'Daemon hit the file-descriptor limit. Restart the daemon.'
+  if (
+    PTY_ALLOCATION_STEPS.has(diagnostic.step) &&
+    RESOURCE_EXHAUSTION_ERRNOS.has(diagnostic.errno)
+  ) {
+    return PTY_ALLOCATION_HINT
   }
-  if (diagnostic.step === 'posix_spawn' && diagnostic.errno === 35) {
-    return 'Per-user process limit reached. Quit some agents and retry.'
+  if (diagnostic.step === 'posix_spawn' && RESOURCE_EXHAUSTION_ERRNOS.has(diagnostic.errno)) {
+    return TERMINAL_PROCESS_LIMIT_HINT
   }
   return null
 }
@@ -33,9 +72,15 @@ export function getNodePtyRecoveryHint(diagnostic: NodePtyDiagnostic): string |
 export function addNodePtyRecoveryHint(message: string): string {
   const diagnostic = parseNodePtyDiagnostic(message)
   if (!diagnostic) {
+    if (GENERIC_PTY_ALLOCATION_RE.test(message) && !message.startsWith(PTY_ALLOCATION_HINT)) {
+      return `${PTY_ALLOCATION_HINT} ${message}`
+    }
     return message
   }
 
   const hint = getNodePtyRecoveryHint(diagnostic)
+  if (hint && message.startsWith(hint)) {
+    return message
+  }
   return hint ? `${hint} ${message}` : message
 }

From 35e13a04b15dceb704f0529a6b0253fa35d1560d Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 11:05:21 -0700
Subject: [PATCH 37/82] Add worktree Open in editor button (#1929)

* Add worktree open-in editor button

Implements the Open in menu flow from docs/open-in-worktree-button.md, including shell IPC validation and sidebar menu integration.

* Move worktree open action into menu

Updates the design to remove the card button and show VS Code under a single Open in context-menu item.

* Shorten worktree file manager labels
---
 docs/open-in-worktree-button.md               | 132 +++++++++
 src/main/ipc/shell.test.ts                    | 260 +++++++++++++++++-
 src/main/ipc/shell.ts                         | 110 +++++++-
 src/preload/api-types.ts                      |   5 +
 src/preload/index.ts                          |   7 +
 .../src/components/sidebar/WorktreeCard.tsx   |  10 +-
 .../sidebar/WorktreeContextMenu.tsx           |  24 +-
 .../sidebar/WorktreeOpenInMenu.test.tsx       | 151 ++++++++++
 .../components/sidebar/WorktreeOpenInMenu.tsx | 145 ++++++++++
 src/renderer/src/web/web-preload-api.ts       |   3 +
 src/shared/shell-open-types.ts                |   5 +
 11 files changed, 813 insertions(+), 39 deletions(-)
 create mode 100644 docs/open-in-worktree-button.md
 create mode 100644 src/renderer/src/components/sidebar/WorktreeOpenInMenu.test.tsx
 create mode 100644 src/renderer/src/components/sidebar/WorktreeOpenInMenu.tsx
 create mode 100644 src/shared/shell-open-types.ts

diff --git a/docs/open-in-worktree-button.md b/docs/open-in-worktree-button.md
new file mode 100644
index 00000000000..4084bbee288
--- /dev/null
+++ b/docs/open-in-worktree-button.md
@@ -0,0 +1,132 @@
+# Open In Menu Item on Worktrees
+
+## Scope
+
+Add an `Open in` item to the worktree context menu for local worktree paths.
+
+Actions:
+
+- VS Code (directory target)
+- Open in OS file manager (directory reveal/open)
+
+Blocked:
+
+- Any SSH-backed worktree (`repo.connectionId` set)
+- Any non-local runtime context (`activeRuntimeEnvironmentId` set)
+
+Use `VS Code` as the visible editor label. Keep implementation identifiers generic so launcher behavior can evolve without renaming APIs.
+
+## Current State (Code-Verified)
+
+- `WorktreeContextMenu.tsx` has `Open in Finder` (macOS-specific label) and calls `window.api.shell.openPath(worktree.path)`.
+- `shell:openPath` in `src/main/ipc/shell.ts` calls `shell.showItemInFolder(path)` directly with no absolute-path validation, no existence check, and no structured return.
+- Preload contract exposes `openPath/openFilePath/openFileUri` as `Promise<void>`.
+- `isLocalPathOpenBlocked` exists and is tested (`local-path-open-guard.test.ts`), but enforcement is renderer-side only.
+- `shell.test.ts` currently does not test `shell:openPath`, `shell:openFilePath`, or `shell:openFileUri` behavior.
+
+## Required Design Changes
+
+### 1) IPC: split intent, return structured results
+
+Add explicit IPC handlers (main + preload + type contract):
+
+- `shell:openInFileManager(path)`
+- `shell:openInExternalEditor(path)`
+
+Return:
+
+- `{ ok: true }`
+- `{ ok: false, reason: 'not-absolute' | 'not-found' | 'launch-failed' }`
+
+Why: `Promise<void>` hides failures and forces renderer to assume success.
+
+### 2) Main-process validation must be authoritative
+
+For both new handlers:
+
+- Normalize path.
+- Require absolute path.
+- Check existence at call time (`stat`).
+- Map launcher failure to `launch-failed`.
+
+Renderer checks are UX only; security/correctness must not depend on renderer state.
+
+### 3) External editor launch must be feasible and generic
+
+Launch a generic editor CLI command constant with the normalized directory path as an argv entry.
+
+Important correction: do not claim this uses the OS default app for a directory. The launcher is platform-dependent and may fail per host config; failure must be surfaced via result union + toast.
+
+### 4) File manager action semantics
+
+Keep file-manager action separate from editor action.
+
+Platform-aware label in renderer:
+
+- macOS: `Finder`
+- Windows: `File Explorer`
+- Linux: `File Manager`
+
+If using reveal semantics, document that behavior explicitly and keep it consistent in the context menu.
+
+### 5) UI integration
+
+- Add a reusable sidebar open-in menu component used by `WorktreeContextMenu`.
+- The context menu should show a single `Open in` item with nested choices for VS Code and OS file manager.
+
+Interaction constraints:
+
+- Disable while deleting (`isDeleting`).
+- Preserve existing keyboard/focus behavior of menu primitives.
+
+### 6) Remote/SSH blocking policy
+
+Keep existing `isLocalPathOpenBlocked` gate in renderer for immediate UX and consistent toasts.
+
+Policy nuance:
+
+- Continue blocking by runtime/SSH context (existing behavior).
+- Main process still validates path existence/shape for all requests.
+- If later hardening is needed, add connection/runtime provenance in IPC args and enforce remote block in main too.
+
+## Edge Cases That Must Be Explicitly Handled
+
+- Worktree deleted/moved between render and click: return `not-found`.
+- Multi-window stale data: each click is independently validated in main.
+- Rapid repeated clicks: requests are independent; no Orca-side dedupe required.
+- External FS mutation races: normalized absolute path + existence recheck per call.
+- Host launcher missing/misconfigured: return `launch-failed`, show actionable toast.
+
+## Testing Requirements
+
+### `src/main/ipc/shell.test.ts`
+
+Add tests for both new handlers:
+
+- rejects relative path (`not-absolute`)
+- rejects missing path (`not-found`)
+- maps launcher error/failure (`launch-failed`)
+- success path invokes expected Electron shell call
+
+Also add coverage for existing `shell:openFilePath`/`shell:openFileUri` failure branches if retained.
+
+### Renderer tests
+
+Add/adjust tests near sidebar components for:
+
+- submenu disabled state while deleting
+- blocked-path toast path
+- platform label mapping
+
+## Rollout Order
+
+1. Add new main IPC handlers + result union types in preload contract.
+2. Add shared sidebar open-in menu component and wire into context menu.
+3. Replace direct `openPath` usage for worktree actions with new handlers.
+4. Add tests and run targeted test/typecheck.
+
+## Non-goals
+
+- Editor picker UI
+- Per-worktree app preference
+- Enabling local OS open for SSH/remote runtime worktrees
diff --git a/src/main/ipc/shell.test.ts b/src/main/ipc/shell.test.ts
index cd7ce56d893..5f034fb90b4 100644
--- a/src/main/ipc/shell.test.ts
+++ b/src/main/ipc/shell.test.ts
@@ -1,8 +1,25 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { normalize, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
-const { handleMock, showOpenDialogMock } = vi.hoisted(() => ({
+const {
+  getSpawnArgsForWindowsMock,
+  handleMock,
+  openPathMock,
+  resolveCliCommandMock,
+  showItemInFolderMock,
+  showOpenDialogMock,
+  spawnMock,
+  statMock
+} = vi.hoisted(() => ({
+  getSpawnArgsForWindowsMock: vi.fn(),
   handleMock: vi.fn(),
-  showOpenDialogMock: vi.fn()
+  openPathMock: vi.fn(),
+  resolveCliCommandMock: vi.fn(),
+  showItemInFolderMock: vi.fn(),
+  showOpenDialogMock: vi.fn(),
+  spawnMock: vi.fn(),
+  statMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -10,21 +27,71 @@ vi.mock('electron', () => ({
     handle: handleMock
   },
   shell: {
-    showItemInFolder: vi.fn(),
+    showItemInFolder: showItemInFolderMock,
     openExternal: vi.fn(),
-    openPath: vi.fn()
+    openPath: openPathMock
   },
   dialog: {
     showOpenDialog: showOpenDialogMock
   }
 }))
 
-import { registerShellHandlers } from './shell'
+vi.mock('node:fs/promises', () => ({
+  constants: { COPYFILE_EXCL: 1 },
+  copyFile: vi.fn(),
+  stat: statMock
+}))
+
+vi.mock('node:child_process', () => ({
+  spawn: spawnMock
+}))
+
+vi.mock('../codex-cli/command', () => ({
+  resolveCliCommand: resolveCliCommandMock
+}))
+
+vi.mock('../win32-utils', () => ({
+  getSpawnArgsForWindows: getSpawnArgsForWindowsMock
+}))
+
+import { EXTERNAL_EDITOR_CLI_COMMAND, registerShellHandlers } from './shell'
+
+function createSpawnedProcess(result: 'spawn' | 'error' = 'spawn'): {
+  once: ReturnType<typeof vi.fn>
+  unref: ReturnType<typeof vi.fn>
+} {
+  const child = {
+    once: vi.fn((eventName: string, callback: (error?: Error) => void) => {
+      if (eventName === result) {
+        queueMicrotask(() => {
+          callback(result === 'error' ? new Error('launcher unavailable') : undefined)
+        })
+      }
+      return child
+    }),
+    unref: vi.fn()
+  }
+  return child
+}
 
 describe('registerShellHandlers', () => {
   beforeEach(() => {
     handleMock.mockReset()
+    getSpawnArgsForWindowsMock.mockReset()
+    openPathMock.mockReset()
+    resolveCliCommandMock.mockReset()
+    showItemInFolderMock.mockReset()
     showOpenDialogMock.mockReset()
+    spawnMock.mockReset()
+    statMock.mockReset()
+    openPathMock.mockResolvedValue('')
+    resolveCliCommandMock.mockReturnValue('editor-cli')
+    getSpawnArgsForWindowsMock.mockImplementation((command: string, args: string[]) => ({
+      spawnCmd: command,
+      spawnArgs: args
+    }))
+    spawnMock.mockReturnValue(createSpawnedProcess())
+    statMock.mockResolvedValue({ isDirectory: () => true })
   })
 
   function getHandler(channel: string): (event: unknown, args?: unknown) => Promise<unknown> {
@@ -59,4 +126,187 @@ describe('registerShellHandlers', () => {
     const handler = getHandler('shell:pickAudio')
     await expect(handler({})).resolves.toBeNull()
   })
+
+  describe('shell:openInFileManager', () => {
+    it('rejects relative paths', async () => {
+      const handler = getHandler('shell:openInFileManager')
+
+      await expect(handler({}, 'relative/workspace')).resolves.toEqual({
+        ok: false,
+        reason: 'not-absolute'
+      })
+      expect(statMock).not.toHaveBeenCalled()
+      expect(showItemInFolderMock).not.toHaveBeenCalled()
+    })
+
+    it('rejects missing paths', async () => {
+      statMock.mockRejectedValueOnce(new Error('missing'))
+      const workspacePath = resolve('missing-workspace')
+      const handler = getHandler('shell:openInFileManager')
+
+      await expect(handler({}, workspacePath)).resolves.toEqual({
+        ok: false,
+        reason: 'not-found'
+      })
+      expect(statMock).toHaveBeenCalledWith(normalize(workspacePath))
+      expect(showItemInFolderMock).not.toHaveBeenCalled()
+    })
+
+    it('maps launcher errors to launch-failed', async () => {
+      showItemInFolderMock.mockImplementationOnce(() => {
+        throw new Error('launcher unavailable')
+      })
+      const workspacePath = resolve('workspace')
+      const handler = getHandler('shell:openInFileManager')
+
+      await expect(handler({}, workspacePath)).resolves.toEqual({
+        ok: false,
+        reason: 'launch-failed'
+      })
+      expect(showItemInFolderMock).toHaveBeenCalledWith(normalize(workspacePath))
+    })
+
+    it('opens existing absolute paths in the OS file manager', async () => {
+      const workspacePath = resolve('workspace')
+      const handler = getHandler('shell:openInFileManager')
+
+      await expect(handler({}, workspacePath)).resolves.toEqual({ ok: true })
+      expect(showItemInFolderMock).toHaveBeenCalledWith(normalize(workspacePath))
+    })
+  })
+
+  describe('shell:openInExternalEditor', () => {
+    it('rejects relative paths', async () => {
+      const handler = getHandler('shell:openInExternalEditor')
+
+      await expect(handler({}, 'relative/workspace')).resolves.toEqual({
+        ok: false,
+        reason: 'not-absolute'
+      })
+      expect(statMock).not.toHaveBeenCalled()
+      expect(openPathMock).not.toHaveBeenCalled()
+      expect(spawnMock).not.toHaveBeenCalled()
+    })
+
+    it('rejects missing paths', async () => {
+      statMock.mockRejectedValueOnce(new Error('missing'))
+      const workspacePath = resolve('missing-workspace')
+      const handler = getHandler('shell:openInExternalEditor')
+
+      await expect(handler({}, workspacePath)).resolves.toEqual({
+        ok: false,
+        reason: 'not-found'
+      })
+      expect(statMock).toHaveBeenCalledWith(normalize(workspacePath))
+      expect(openPathMock).not.toHaveBeenCalled()
+      expect(spawnMock).not.toHaveBeenCalled()
+    })
+
+    it('maps launcher failures to launch-failed', async () => {
+      spawnMock.mockReturnValueOnce(createSpawnedProcess('error'))
+      const workspacePath = resolve('workspace')
+      const handler = getHandler('shell:openInExternalEditor')
+
+      await expect(handler({}, workspacePath)).resolves.toEqual({
+        ok: false,
+        reason: 'launch-failed'
+      })
+      expect(resolveCliCommandMock).toHaveBeenCalledWith(EXTERNAL_EDITOR_CLI_COMMAND)
+      expect(getSpawnArgsForWindowsMock).toHaveBeenCalledWith('editor-cli', [
+        normalize(workspacePath)
+      ])
+      expect(spawnMock).toHaveBeenCalledWith('editor-cli', [normalize(workspacePath)], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true
+      })
+      expect(openPathMock).not.toHaveBeenCalled()
+    })
+
+    it('opens existing absolute paths with the editor launcher', async () => {
+      const workspacePath = resolve('workspace')
+      const handler = getHandler('shell:openInExternalEditor')
+
+      await expect(handler({}, workspacePath)).resolves.toEqual({ ok: true })
+      expect(resolveCliCommandMock).toHaveBeenCalledWith(EXTERNAL_EDITOR_CLI_COMMAND)
+      expect(getSpawnArgsForWindowsMock).toHaveBeenCalledWith('editor-cli', [
+        normalize(workspacePath)
+      ])
+      expect(spawnMock).toHaveBeenCalledWith('editor-cli', [normalize(workspacePath)], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true
+      })
+      expect(openPathMock).not.toHaveBeenCalled()
+    })
+
+    it('uses platform-safe launcher command arguments', async () => {
+      getSpawnArgsForWindowsMock.mockReturnValueOnce({
+        spawnCmd: 'platform-runner',
+        spawnArgs: ['platform-arg']
+      })
+      const workspacePath = resolve('workspace')
+      const handler = getHandler('shell:openInExternalEditor')
+
+      await expect(handler({}, workspacePath)).resolves.toEqual({ ok: true })
+      expect(getSpawnArgsForWindowsMock).toHaveBeenCalledWith('editor-cli', [
+        normalize(workspacePath)
+      ])
+      expect(spawnMock).toHaveBeenCalledWith('platform-runner', ['platform-arg'], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true
+      })
+      expect(openPathMock).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('legacy file open handlers', () => {
+    it('does not open relative file paths', async () => {
+      const handler = getHandler('shell:openFilePath')
+
+      await expect(handler({}, 'relative/file.md')).resolves.toBeUndefined()
+      expect(openPathMock).not.toHaveBeenCalled()
+    })
+
+    it('does not open missing file paths', async () => {
+      statMock.mockRejectedValueOnce(new Error('missing'))
+      const handler = getHandler('shell:openFilePath')
+
+      await expect(handler({}, resolve('missing.md'))).resolves.toBeUndefined()
+      expect(openPathMock).not.toHaveBeenCalled()
+    })
+
+    it('swallows host launcher failures for file paths', async () => {
+      openPathMock.mockRejectedValueOnce(new Error('launcher unavailable'))
+      const filePath = resolve('note.md')
+      const handler = getHandler('shell:openFilePath')
+
+      await expect(handler({}, filePath)).resolves.toBeUndefined()
+      expect(openPathMock).toHaveBeenCalledWith(normalize(filePath))
+    })
+
+    it('does not open non-file URIs', async () => {
+      const handler = getHandler('shell:openFileUri')
+
+      await expect(handler({}, 'https://example.com/file.md')).resolves.toBeUndefined()
+      expect(openPathMock).not.toHaveBeenCalled()
+    })
+
+    it('does not open remote file URIs', async () => {
+      const handler = getHandler('shell:openFileUri')
+
+      await expect(handler({}, 'file://server/share/file.md')).resolves.toBeUndefined()
+      expect(openPathMock).not.toHaveBeenCalled()
+    })
+
+    it('swallows host launcher failures for file URIs', async () => {
+      openPathMock.mockRejectedValueOnce(new Error('launcher unavailable'))
+      const filePath = resolve('note.md')
+      const handler = getHandler('shell:openFileUri')
+
+      await expect(handler({}, pathToFileURL(filePath).toString())).resolves.toBeUndefined()
+      expect(openPathMock).toHaveBeenCalledWith(normalize(filePath))
+    })
+  })
 })
diff --git a/src/main/ipc/shell.ts b/src/main/ipc/shell.ts
index 51dff5ae5b6..cb6fba2d9b5 100644
--- a/src/main/ipc/shell.ts
+++ b/src/main/ipc/shell.ts
@@ -1,7 +1,13 @@
 import { ipcMain, shell, dialog } from 'electron'
+import { spawn } from 'node:child_process'
 import { constants, copyFile, stat } from 'node:fs/promises'
 import { isAbsolute, normalize } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import type { ShellOpenLocalPathResult } from '../../shared/shell-open-types'
+import { resolveCliCommand } from '../codex-cli/command'
+import { getSpawnArgsForWindows } from '../win32-utils'
+
+export const EXTERNAL_EDITOR_CLI_COMMAND = 'code'
 
 async function pathExists(pathValue: string): Promise<boolean> {
   try {
@@ -12,11 +18,91 @@ async function pathExists(pathValue: string): Promise<boolean> {
   }
 }
 
+async function validateLocalPathTarget(
+  pathValue: string
+): Promise<{ ok: true; path: string } | { ok: false; reason: 'not-absolute' | 'not-found' }> {
+  const normalizedPath = normalize(pathValue)
+  if (!isAbsolute(normalizedPath)) {
+    return { ok: false, reason: 'not-absolute' }
+  }
+  if (!(await pathExists(normalizedPath))) {
+    return { ok: false, reason: 'not-found' }
+  }
+  return { ok: true, path: normalizedPath }
+}
+
+async function openInFileManager(pathValue: string): Promise<ShellOpenLocalPathResult> {
+  const target = await validateLocalPathTarget(pathValue)
+  if (!target.ok) {
+    return target
+  }
+  try {
+    // Why: the file-manager action uses reveal semantics, matching the
+    // previous sidebar behavior while still validating the path per click.
+    shell.showItemInFolder(target.path)
+    return { ok: true }
+  } catch {
+    return { ok: false, reason: 'launch-failed' }
+  }
+}
+
+async function launchExternalEditor(pathValue: string): Promise<void> {
+  const editorCommand = resolveCliCommand(EXTERNAL_EDITOR_CLI_COMMAND)
+  const { spawnCmd, spawnArgs } = getSpawnArgsForWindows(editorCommand, [pathValue])
+
+  await new Promise<void>((resolvePromise, rejectPromise) => {
+    const child = spawn(spawnCmd, spawnArgs, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true
+    })
+    let settled = false
+    const settle = (callback: () => void): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      callback()
+    }
+
+    child.once('error', (error) => {
+      settle(() => rejectPromise(error))
+    })
+    child.once('spawn', () => {
+      child.unref()
+      settle(resolvePromise)
+    })
+  })
+}
+
+async function openInExternalEditor(pathValue: string): Promise<ShellOpenLocalPathResult> {
+  const target = await validateLocalPathTarget(pathValue)
+  if (!target.ok) {
+    return target
+  }
+  try {
+    await launchExternalEditor(target.path)
+    return { ok: true }
+  } catch {
+    return { ok: false, reason: 'launch-failed' }
+  }
+}
+
 export function registerShellHandlers(): void {
   ipcMain.handle('shell:openPath', (_event, path: string) => {
     shell.showItemInFolder(path)
   })
 
+  ipcMain.handle(
+    'shell:openInFileManager',
+    (_event, path: string): Promise<ShellOpenLocalPathResult> => openInFileManager(path)
+  )
+
+  ipcMain.handle(
+    'shell:openInExternalEditor',
+    (_event, path: string): Promise<ShellOpenLocalPathResult> => openInExternalEditor(path)
+  )
+
   ipcMain.handle('shell:openUrl', (_event, rawUrl: string) => {
     let parsed: URL
     try {
@@ -33,14 +119,15 @@ export function registerShellHandlers(): void {
   })
 
   ipcMain.handle('shell:openFilePath', async (_event, filePath: string) => {
-    if (!isAbsolute(filePath)) {
+    const target = await validateLocalPathTarget(filePath)
+    if (!target.ok) {
       return
     }
-    const normalizedPath = normalize(filePath)
-    if (!(await pathExists(normalizedPath))) {
-      return
+    try {
+      await shell.openPath(target.path)
+    } catch {
+      // Why: legacy file-open IPC is best-effort; callers already treat failure as a no-op.
     }
-    await shell.openPath(normalizedPath)
   })
 
   ipcMain.handle('shell:openFileUri', async (_event, rawUri: string) => {
@@ -67,15 +154,16 @@ export function registerShellHandlers(): void {
       return
     }
 
-    const normalizedPath = normalize(filePath)
-    if (!isAbsolute(normalizedPath)) {
-      return
-    }
-    if (!(await pathExists(normalizedPath))) {
+    const target = await validateLocalPathTarget(filePath)
+    if (!target.ok) {
       return
     }
 
-    await shell.openPath(normalizedPath)
+    try {
+      await shell.openPath(target.path)
+    } catch {
+      // Why: legacy file-open IPC is best-effort; callers already treat failure as a no-op.
+    }
   })
 
   ipcMain.handle('shell:pathExists', async (_event, filePath: string): Promise<boolean> => {
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index cecd0f29da4..a874def4fca 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -141,6 +141,9 @@ import type { E2EConfig } from '../shared/e2e-config'
 import type { AgentHookInstallStatus } from '../shared/agent-hook-types'
 import type { AgentStatusIpcPayload } from '../shared/agent-status-types'
 import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../shared/runtime-types'
+import type { ShellOpenLocalPathResult } from '../shared/shell-open-types'
+
+export type { ShellOpenLocalPathResult } from '../shared/shell-open-types'
 
 type RuntimeEnvironmentSubscriptionHandle = {
   unsubscribe: () => void
@@ -992,6 +995,8 @@ export type PreloadApi = {
   }
   shell: {
     openPath: (path: string) => Promise<void>
+    openInFileManager: (path: string) => Promise<ShellOpenLocalPathResult>
+    openInExternalEditor: (path: string) => Promise<ShellOpenLocalPathResult>
     openUrl: (url: string) => Promise<void>
     openFilePath: (path: string) => Promise<void>
     openFileUri: (uri: string) => Promise<void>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index d87d80f2e36..014996c28de 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -32,6 +32,7 @@ import type {
   WorktreeBaseStatusEvent,
   WorktreeRemoteBranchConflictEvent
 } from '../shared/types'
+import type { ShellOpenLocalPathResult } from '../shared/shell-open-types'
 import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../shared/runtime-types'
 import type { RuntimeRpcResponse } from '../shared/runtime-rpc-envelope'
 import type { PublicKnownRuntimeEnvironment } from '../shared/runtime-environments'
@@ -1179,6 +1180,12 @@ const api = {
   shell: {
     openPath: (path: string): Promise<void> => ipcRenderer.invoke('shell:openPath', path),
 
+    openInFileManager: (path: string): Promise<ShellOpenLocalPathResult> =>
+      ipcRenderer.invoke('shell:openInFileManager', path),
+
+    openInExternalEditor: (path: string): Promise<ShellOpenLocalPathResult> =>
+      ipcRenderer.invoke('shell:openInExternalEditor', path),
+
     openUrl: (url: string): Promise<void> => ipcRenderer.invoke('shell:openUrl', url),
 
     openFilePath: (path: string): Promise<void> => ipcRenderer.invoke('shell:openFilePath', path),
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.tsx b/src/renderer/src/components/sidebar/WorktreeCard.tsx
index a444bf39e19..8690617c281 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.tsx
@@ -465,9 +465,9 @@ const WorktreeCard = React.memo(function WorktreeCard({
             )}
           </div>
 
-          {/* CI Checks & PR state on the right */}
-          {cardProps.includes('ci') && hostedReview && hostedReview.status !== 'neutral' && (
-            <div className="flex items-center gap-2 shrink-0">
+          <div className="flex items-center gap-1 shrink-0">
+            {/* CI Checks & PR state on the right */}
+            {cardProps.includes('ci') && hostedReview && hostedReview.status !== 'neutral' && (
               <Tooltip>
                 <TooltipTrigger asChild>
                   <span className="inline-flex items-center opacity-80 hover:opacity-100 transition-opacity">
@@ -486,8 +486,8 @@ const WorktreeCard = React.memo(function WorktreeCard({
                   <span>CI checks {checksLabel(hostedReview.status).toLowerCase()}</span>
                 </TooltipContent>
               </Tooltip>
-            </div>
-          )}
+            )}
+          </div>
         </div>
 
         {/* Subtitle row: Repo badge + Branch */}
diff --git a/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx b/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
index dd522a58a08..d8eccb5c8be 100644
--- a/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeContextMenu.tsx
@@ -13,7 +13,6 @@ import {
 } from '@/components/ui/dropdown-menu'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import {
-  FolderOpen,
   Copy,
   Bell,
   BellOff,
@@ -33,8 +32,8 @@ import type { Worktree } from '../../../../shared/types'
 import { isFolderRepo } from '../../../../shared/repo-kind'
 import { runWorktreeBatchDelete, runWorktreeDelete } from './delete-worktree-flow'
 import { runSleepWorktrees } from './sleep-worktree-flow'
-import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
 import { getWorkspaceStatus, getWorkspaceStatusVisualMeta } from './workspace-status'
+import { WorktreeOpenInSubMenu } from './WorktreeOpenInMenu'
 
 type Props = {
   worktree: Worktree
@@ -118,18 +117,6 @@ const WorktreeContextMenu = React.memo(function WorktreeContextMenu({
     return () => window.removeEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
   }, [])
 
-  const handleOpenInFinder = useCallback(() => {
-    if (
-      isLocalPathOpenBlocked(useAppStore.getState().settings, {
-        connectionId: repo?.connectionId ?? null
-      })
-    ) {
-      showLocalPathOpenBlockedToast()
-      return
-    }
-    window.api.shell.openPath(worktree.path)
-  }, [repo?.connectionId, worktree.path])
-
   const handleCopyPath = useCallback(() => {
     window.api.ui.writeClipboardText(worktree.path)
   }, [worktree.path])
@@ -282,10 +269,11 @@ const WorktreeContextMenu = React.memo(function WorktreeContextMenu({
         <DropdownMenuContent className={cn('w-52', contentClassName)} sideOffset={0} align="start">
           {!isMultiContext && (
             <>
-              <DropdownMenuItem onSelect={handleOpenInFinder} disabled={isDeleting}>
-                <FolderOpen className="size-3.5" />
-                Open in Finder
-              </DropdownMenuItem>
+              <WorktreeOpenInSubMenu
+                worktreePath={worktree.path}
+                connectionId={repo?.connectionId ?? null}
+                disabled={isDeleting}
+              />
               <DropdownMenuItem onSelect={handleCopyPath} disabled={isDeleting}>
                 <Copy className="size-3.5" />
                 Copy Path
diff --git a/src/renderer/src/components/sidebar/WorktreeOpenInMenu.test.tsx b/src/renderer/src/components/sidebar/WorktreeOpenInMenu.test.tsx
new file mode 100644
index 00000000000..691899bbd9a
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorktreeOpenInMenu.test.tsx
@@ -0,0 +1,151 @@
+import React from 'react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DropdownMenuSubContent, DropdownMenuSubTrigger } from '@/components/ui/dropdown-menu'
+import {
+  getLocalFileManagerLabel,
+  openWorktreePath,
+  WorktreeOpenInSubMenu
+} from './WorktreeOpenInMenu'
+
+type ReactElementLike = {
+  type: unknown
+  props: Record<string, unknown>
+}
+
+const { mockState, openInExternalEditorMock, openInFileManagerMock, toastErrorMock } = vi.hoisted(
+  () => ({
+    mockState: {
+      settings: { activeRuntimeEnvironmentId: null as string | null }
+    },
+    openInExternalEditorMock: vi.fn(),
+    openInFileManagerMock: vi.fn(),
+    toastErrorMock: vi.fn()
+  })
+)
+
+vi.mock('sonner', () => ({
+  toast: {
+    error: toastErrorMock
+  }
+}))
+
+vi.mock('@/store', () => {
+  const useAppStore = Object.assign(
+    (selector: (state: { settings: typeof mockState.settings }) => unknown) =>
+      selector({ settings: mockState.settings }),
+    {
+      getState: () => ({ settings: mockState.settings })
+    }
+  )
+  return { useAppStore }
+})
+
+function visit(node: unknown, cb: (node: ReactElementLike) => void): void {
+  if (node == null || typeof node === 'string' || typeof node === 'number') {
+    return
+  }
+  if (Array.isArray(node)) {
+    node.forEach((entry) => visit(entry, cb))
+    return
+  }
+  const element = node as ReactElementLike
+  cb(element)
+  if (element.props?.children) {
+    visit(element.props.children, cb)
+  }
+}
+
+function findByType(node: unknown, type: unknown): ReactElementLike {
+  let found: ReactElementLike | null = null
+  visit(node, (entry) => {
+    if (entry.type === type) {
+      found = entry
+    }
+  })
+  if (!found) {
+    throw new Error('element not found')
+  }
+  return found
+}
+
+describe('WorktreeOpenInMenu', () => {
+  beforeEach(() => {
+    mockState.settings = { activeRuntimeEnvironmentId: null }
+    toastErrorMock.mockReset()
+    openInFileManagerMock.mockReset()
+    openInExternalEditorMock.mockReset()
+    openInFileManagerMock.mockResolvedValue({ ok: true })
+    openInExternalEditorMock.mockResolvedValue({ ok: true })
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      value: {
+        api: {
+          shell: {
+            openInFileManager: openInFileManagerMock,
+            openInExternalEditor: openInExternalEditorMock
+          }
+        }
+      }
+    })
+  })
+
+  it('maps file manager labels by platform', () => {
+    expect(getLocalFileManagerLabel('Mozilla/5.0 Mac OS X')).toBe('Finder')
+    expect(getLocalFileManagerLabel('Mozilla/5.0 Windows NT 10.0')).toBe('File Explorer')
+    expect(getLocalFileManagerLabel('Mozilla/5.0 X11 Linux x86_64')).toBe('File Manager')
+  })
+
+  it('disables the Open in submenu while deleting', () => {
+    const tree = WorktreeOpenInSubMenu({
+      worktreePath: '/tmp/workspace',
+      connectionId: null,
+      disabled: true
+    })
+
+    expect(findByType(tree, DropdownMenuSubTrigger).props.disabled).toBe(true)
+  })
+
+  it('stops menu item click propagation', () => {
+    const tree = WorktreeOpenInSubMenu({
+      worktreePath: '/tmp/workspace',
+      connectionId: null
+    })
+    const menuContent = findByType(tree, DropdownMenuSubContent)
+
+    const stopPropagation = vi.fn()
+    const handler = menuContent.props.onClick as ((event: React.SyntheticEvent) => void) | null
+    handler?.({ stopPropagation } as unknown as React.SyntheticEvent)
+    expect(stopPropagation).toHaveBeenCalled()
+  })
+
+  it('uses the blocked-path toast without calling main IPC', async () => {
+    mockState.settings = { activeRuntimeEnvironmentId: 'runtime-1' }
+
+    await openWorktreePath({
+      target: 'file-manager',
+      worktreePath: '/tmp/workspace',
+      connectionId: null
+    })
+
+    expect(toastErrorMock).toHaveBeenCalledWith(
+      'Opening remote paths in the local OS is not available.'
+    )
+    expect(openInFileManagerMock).not.toHaveBeenCalled()
+    expect(openInExternalEditorMock).not.toHaveBeenCalled()
+  })
+
+  it('shows an actionable toast when the host launcher fails', async () => {
+    openInExternalEditorMock.mockResolvedValueOnce({ ok: false, reason: 'launch-failed' })
+
+    await openWorktreePath({
+      target: 'external-editor',
+      worktreePath: '/tmp/workspace',
+      connectionId: null
+    })
+
+    expect(openInExternalEditorMock).toHaveBeenCalledWith('/tmp/workspace')
+    expect(toastErrorMock).toHaveBeenCalledWith('Could not open workspace folder.', {
+      description: 'Check the editor command or file manager configuration on this machine.'
+    })
+  })
+})
diff --git a/src/renderer/src/components/sidebar/WorktreeOpenInMenu.tsx b/src/renderer/src/components/sidebar/WorktreeOpenInMenu.tsx
new file mode 100644
index 00000000000..5624984dc70
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorktreeOpenInMenu.tsx
@@ -0,0 +1,145 @@
+import React, { useCallback } from 'react'
+import { ExternalLink, FolderOpen } from 'lucide-react'
+import { toast } from 'sonner'
+import {
+  DropdownMenuItem,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger
+} from '@/components/ui/dropdown-menu'
+import { useAppStore } from '@/store'
+import { isLocalPathOpenBlocked, showLocalPathOpenBlockedToast } from '@/lib/local-path-open-guard'
+import type { ShellOpenLocalPathFailureReason } from '../../../../shared/shell-open-types'
+
+type WorktreeOpenInMenuItemsProps = {
+  worktreePath: string
+  connectionId?: string | null
+  disabled?: boolean
+}
+
+export function getLocalFileManagerLabel(userAgent?: string): string {
+  const resolvedUserAgent =
+    userAgent ?? (typeof navigator === 'undefined' ? '' : navigator.userAgent)
+  if (resolvedUserAgent.includes('Mac')) {
+    return 'Finder'
+  }
+  if (resolvedUserAgent.includes('Windows')) {
+    return 'File Explorer'
+  }
+  return 'File Manager'
+}
+
+function showOpenFailureToast(reason: ShellOpenLocalPathFailureReason): void {
+  if (reason === 'not-absolute') {
+    toast.error('Workspace path is not a valid local path.')
+    return
+  }
+  if (reason === 'not-found') {
+    toast.error('Workspace folder was not found.', {
+      description: 'It may have been moved or deleted. Refresh workspaces or remove it from Orca.'
+    })
+    return
+  }
+  toast.error('Could not open workspace folder.', {
+    description: 'Check the editor command or file manager configuration on this machine.'
+  })
+}
+
+function stopMenuPropagation(event: React.SyntheticEvent): void {
+  event.stopPropagation()
+}
+
+export async function openWorktreePath(args: {
+  target: 'file-manager' | 'external-editor'
+  worktreePath: string
+  connectionId?: string | null
+}): Promise<void> {
+  if (
+    isLocalPathOpenBlocked(useAppStore.getState().settings, {
+      connectionId: args.connectionId ?? null
+    })
+  ) {
+    showLocalPathOpenBlockedToast()
+    return
+  }
+
+  const result =
+    args.target === 'file-manager'
+      ? await window.api.shell.openInFileManager(args.worktreePath)
+      : await window.api.shell.openInExternalEditor(args.worktreePath)
+  if (!result.ok) {
+    showOpenFailureToast(result.reason)
+  }
+}
+
+function useOpenInWorktreePath({
+  worktreePath,
+  connectionId
+}: WorktreeOpenInMenuItemsProps): (target: 'file-manager' | 'external-editor') => Promise<void> {
+  return useCallback(
+    async (target) => {
+      await openWorktreePath({ target, worktreePath, connectionId })
+    },
+    [connectionId, worktreePath]
+  )
+}
+
+export function WorktreeOpenInMenuItems({
+  worktreePath,
+  connectionId,
+  disabled
+}: WorktreeOpenInMenuItemsProps): React.JSX.Element {
+  const openInWorktreePath = useOpenInWorktreePath({ worktreePath, connectionId })
+  const fileManagerLabel = getLocalFileManagerLabel()
+
+  return (
+    <>
+      <DropdownMenuItem
+        onClick={stopMenuPropagation}
+        onSelect={() => {
+          void openInWorktreePath('external-editor')
+        }}
+        disabled={disabled}
+      >
+        <ExternalLink className="size-3.5" />
+        VS Code
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        onClick={stopMenuPropagation}
+        onSelect={() => {
+          void openInWorktreePath('file-manager')
+        }}
+        disabled={disabled}
+      >
+        <FolderOpen className="size-3.5" />
+        {fileManagerLabel}
+      </DropdownMenuItem>
+    </>
+  )
+}
+
+export function WorktreeOpenInSubMenu({
+  worktreePath,
+  connectionId,
+  disabled
+}: WorktreeOpenInMenuItemsProps): React.JSX.Element {
+  return (
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger disabled={disabled}>
+        <FolderOpen className="size-3.5" />
+        Open in
+      </DropdownMenuSubTrigger>
+      <DropdownMenuSubContent
+        className="w-52"
+        onClick={stopMenuPropagation}
+        onPointerDown={stopMenuPropagation}
+      >
+        <WorktreeOpenInMenuItems
+          worktreePath={worktreePath}
+          connectionId={connectionId}
+          disabled={disabled}
+        />
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
+  )
+}
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index b8bb0242a4a..3d88e85d7ca 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -908,9 +908,12 @@ function createUpdaterApi(): NonNullable<Partial<PreloadApi>['updater']> {
 }
 
 function createShellApi(): NonNullable<Partial<PreloadApi>['shell']> {
+  const openResult = { ok: true } as const
   return {
     openPath: (path) =>
       Promise.resolve(window.open(path, '_blank', 'noopener,noreferrer') as never),
+    openInFileManager: () => Promise.resolve(openResult),
+    openInExternalEditor: () => Promise.resolve(openResult),
     openUrl: (url) => Promise.resolve(window.open(url, '_blank', 'noopener,noreferrer') as never),
     openFilePath: () => Promise.resolve(),
     openFileUri: (uri) =>
diff --git a/src/shared/shell-open-types.ts b/src/shared/shell-open-types.ts
new file mode 100644
index 00000000000..a2d477e9cc9
--- /dev/null
+++ b/src/shared/shell-open-types.ts
@@ -0,0 +1,5 @@
+export type ShellOpenLocalPathFailureReason = 'not-absolute' | 'not-found' | 'launch-failed'
+
+export type ShellOpenLocalPathResult =
+  | { ok: true }
+  | { ok: false; reason: ShellOpenLocalPathFailureReason }

From cc0272e5c414858800b86456b9b81d8989ff810a Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 11:11:13 -0700
Subject: [PATCH 38/82] chore: remove open editor design doc (#1938)

---
 docs/open-in-worktree-button.md | 132 --------------------------------
 1 file changed, 132 deletions(-)
 delete mode 100644 docs/open-in-worktree-button.md

diff --git a/docs/open-in-worktree-button.md b/docs/open-in-worktree-button.md
deleted file mode 100644
index 4084bbee288..00000000000
--- a/docs/open-in-worktree-button.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# Open In Menu Item on Worktrees
-
-## Scope
-
-Add an `Open in` item to the worktree context menu for local worktree paths.
-
-Actions:
-
-- VS Code (directory target)
-- Open in OS file manager (directory reveal/open)
-
-Blocked:
-
-- Any SSH-backed worktree (`repo.connectionId` set)
-- Any non-local runtime context (`activeRuntimeEnvironmentId` set)
-
-Use `VS Code` as the visible editor label. Keep implementation identifiers generic so launcher behavior can evolve without renaming APIs.
-
-## Current State (Code-Verified)
-
-- `WorktreeContextMenu.tsx` has `Open in Finder` (macOS-specific label) and calls `window.api.shell.openPath(worktree.path)`.
-- `shell:openPath` in `src/main/ipc/shell.ts` calls `shell.showItemInFolder(path)` directly with no absolute-path validation, no existence check, and no structured return.
-- Preload contract exposes `openPath/openFilePath/openFileUri` as `Promise<void>`.
-- `isLocalPathOpenBlocked` exists and is tested (`local-path-open-guard.test.ts`), but enforcement is renderer-side only.
-- `shell.test.ts` currently does not test `shell:openPath`, `shell:openFilePath`, or `shell:openFileUri` behavior.
-
-## Required Design Changes
-
-### 1) IPC: split intent, return structured results
-
-Add explicit IPC handlers (main + preload + type contract):
-
-- `shell:openInFileManager(path)`
-- `shell:openInExternalEditor(path)`
-
-Return:
-
-- `{ ok: true }`
-- `{ ok: false, reason: 'not-absolute' | 'not-found' | 'launch-failed' }`
-
-Why: `Promise<void>` hides failures and forces renderer to assume success.
-
-### 2) Main-process validation must be authoritative
-
-For both new handlers:
-
-- Normalize path.
-- Require absolute path.
-- Check existence at call time (`stat`).
-- Map launcher failure to `launch-failed`.
-
-Renderer checks are UX only; security/correctness must not depend on renderer state.
-
-### 3) External editor launch must be feasible and generic
-
-Launch a generic editor CLI command constant with the normalized directory path as an argv entry.
-
-Important correction: do not claim this uses the OS default app for a directory. The launcher is platform-dependent and may fail per host config; failure must be surfaced via result union + toast.
-
-### 4) File manager action semantics
-
-Keep file-manager action separate from editor action.
-
-Platform-aware label in renderer:
-
-- macOS: `Finder`
-- Windows: `File Explorer`
-- Linux: `File Manager`
-
-If using reveal semantics, document that behavior explicitly and keep it consistent in the context menu.
-
-### 5) UI integration
-
-- Add a reusable sidebar open-in menu component used by `WorktreeContextMenu`.
-- The context menu should show a single `Open in` item with nested choices for VS Code and OS file manager.
-
-Interaction constraints:
-
-- Disable while deleting (`isDeleting`).
-- Preserve existing keyboard/focus behavior of menu primitives.
-
-### 6) Remote/SSH blocking policy
-
-Keep existing `isLocalPathOpenBlocked` gate in renderer for immediate UX and consistent toasts.
-
-Policy nuance:
-
-- Continue blocking by runtime/SSH context (existing behavior).
-- Main process still validates path existence/shape for all requests.
-- If later hardening is needed, add connection/runtime provenance in IPC args and enforce remote block in main too.
-
-## Edge Cases That Must Be Explicitly Handled
-
-- Worktree deleted/moved between render and click: return `not-found`.
-- Multi-window stale data: each click is independently validated in main.
-- Rapid repeated clicks: requests are independent; no Orca-side dedupe required.
-- External FS mutation races: normalized absolute path + existence recheck per call.
-- Host launcher missing/misconfigured: return `launch-failed`, show actionable toast.
-
-## Testing Requirements
-
-### `src/main/ipc/shell.test.ts`
-
-Add tests for both new handlers:
-
-- rejects relative path (`not-absolute`)
-- rejects missing path (`not-found`)
-- maps launcher error/failure (`launch-failed`)
-- success path invokes expected Electron shell call
-
-Also add coverage for existing `shell:openFilePath`/`shell:openFileUri` failure branches if retained.
-
-### Renderer tests
-
-Add/adjust tests near sidebar components for:
-
-- submenu disabled state while deleting
-- blocked-path toast path
-- platform label mapping
-
-## Rollout Order
-
-1. Add new main IPC handlers + result union types in preload contract.
-2. Add shared sidebar open-in menu component and wire into context menu.
-3. Replace direct `openPath` usage for worktree actions with new handlers.
-4. Add tests and run targeted test/typecheck.
-
-## Non-goals
-
-- Editor picker UI
-- Per-worktree app preference
-- Enabling local OS open for SSH/remote runtime worktrees

From fd813e7639e444dfecde8b9f25a112d8905dc04b Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 15 May 2026 11:19:19 -0700
Subject: [PATCH 39/82] Keep computer awake while agents run (#1937)

Co-authored-by: Orca <help@stably.ai>
---
 src/main/agent-awake-service.test.ts          | 208 ++++++++++++++++++
 src/main/agent-awake-service.ts               | 206 +++++++++++++++++
 src/main/agent-hooks/server.test.ts           | 145 ++++++++++++
 src/main/agent-hooks/server.ts                |  55 +++++
 .../runtime-home-service.test.ts              |   1 +
 src/main/codex-accounts/service.test.ts       |   1 +
 src/main/index.ts                             |  19 +-
 src/main/ipc/register-core-handlers.test.ts   |   2 +-
 src/main/ipc/register-core-handlers.ts        |   6 +-
 src/main/ipc/settings.test.ts                 |  37 +++-
 src/main/ipc/settings.ts                      |   9 +-
 .../components/settings/AgentAwakeSetting.tsx |  51 +++++
 .../components/settings/AgentsPane.test.tsx   | 101 +++++++++
 .../src/components/settings/AgentsPane.tsx    |   3 +
 .../src/components/settings/agents-search.ts  |   6 +
 src/shared/constants.ts                       |   1 +
 src/shared/types.ts                           |   2 +
 tests/e2e/settings-agent-awake.spec.ts        |  54 +++++
 18 files changed, 901 insertions(+), 6 deletions(-)
 create mode 100644 src/main/agent-awake-service.test.ts
 create mode 100644 src/main/agent-awake-service.ts
 create mode 100644 src/renderer/src/components/settings/AgentAwakeSetting.tsx
 create mode 100644 src/renderer/src/components/settings/AgentsPane.test.tsx
 create mode 100644 tests/e2e/settings-agent-awake.spec.ts

diff --git a/src/main/agent-awake-service.test.ts b/src/main/agent-awake-service.test.ts
new file mode 100644
index 00000000000..d71b6c37b2c
--- /dev/null
+++ b/src/main/agent-awake-service.test.ts
@@ -0,0 +1,208 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { AgentAwakeService, AGENT_AWAKE_STATUS_STALE_AFTER_MS } from './agent-awake-service'
+import type { AgentAwakeStatus } from './agent-awake-service'
+
+vi.mock('electron', () => ({
+  powerSaveBlocker: {
+    start: vi.fn(),
+    stop: vi.fn(),
+    isStarted: vi.fn()
+  }
+}))
+
+function workingStatus(overrides: Partial<AgentAwakeStatus> = {}): AgentAwakeStatus {
+  return {
+    state: 'working',
+    receivedAt: 1_000,
+    observedInCurrentRuntime: true,
+    ...overrides
+  }
+}
+
+function createBlocker() {
+  const startedIds = new Set<number>()
+  let nextId = 1
+  return {
+    start: vi.fn(() => {
+      const id = nextId++
+      startedIds.add(id)
+      return id
+    }),
+    stop: vi.fn((id: number) => {
+      startedIds.delete(id)
+    }),
+    isStarted: vi.fn((id: number) => startedIds.has(id)),
+    startedIds
+  }
+}
+
+function createService(now: () => number, blocker = createBlocker()): AgentAwakeService {
+  return new AgentAwakeService({
+    blocker,
+    now,
+    logger: {
+      debug: vi.fn(),
+      warn: vi.fn()
+    }
+  })
+}
+
+describe('AgentAwakeService', () => {
+  beforeEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('does not start when disabled even with a running status', () => {
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setStatuses([workingStatus()])
+
+    expect(blocker.start).not.toHaveBeenCalled()
+  })
+
+  it('starts one prevent-app-suspension blocker when enabled with a fresh working status', () => {
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus()])
+
+    expect(blocker.start).toHaveBeenCalledTimes(1)
+    expect(blocker.start).toHaveBeenCalledWith('prevent-app-suspension')
+  })
+
+  it('starts and stops from settings flips around an already-running status', () => {
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setStatuses([workingStatus()])
+    service.setEnabled(true)
+    service.setEnabled(false)
+
+    expect(blocker.start).toHaveBeenCalledTimes(1)
+    expect(blocker.stop).toHaveBeenCalledWith(1)
+  })
+
+  it('ignores startup-hydrated working statuses that were not observed in this runtime', () => {
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus({ observedInCurrentRuntime: false })])
+
+    expect(blocker.start).not.toHaveBeenCalled()
+  })
+
+  it('does not start for blocked, waiting, or done statuses', () => {
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([
+      workingStatus({ state: 'blocked' }),
+      workingStatus({ state: 'waiting' }),
+      workingStatus({ state: 'done' })
+    ])
+
+    expect(blocker.start).not.toHaveBeenCalled()
+  })
+
+  it('does not start a second blocker when one working status replaces another', () => {
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus({ receivedAt: 1_000 })])
+    service.setStatuses([workingStatus({ receivedAt: 1_100 })])
+
+    expect(blocker.start).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops when the last running status is dropped', () => {
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus()])
+    service.setStatuses([])
+
+    expect(blocker.stop).toHaveBeenCalledWith(1)
+  })
+
+  it('does not start for a stale working status', () => {
+    const blocker = createBlocker()
+    const service = createService(() => AGENT_AWAKE_STATUS_STALE_AFTER_MS + 1_001, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus({ receivedAt: 1_000 })])
+
+    expect(blocker.start).not.toHaveBeenCalled()
+  })
+
+  it('stops when the only running status becomes stale without another event', () => {
+    vi.useFakeTimers()
+    let now = 1_000
+    const blocker = createBlocker()
+    const service = createService(() => now, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus({ receivedAt: 1_000 })])
+    now = 1_000 + AGENT_AWAKE_STATUS_STALE_AFTER_MS + 1
+    vi.advanceTimersByTime(AGENT_AWAKE_STATUS_STALE_AFTER_MS)
+
+    expect(blocker.stop).toHaveBeenCalledWith(1)
+    service.dispose()
+  })
+
+  it('reschedules stale expiry for a newer running status', () => {
+    vi.useFakeTimers()
+    let now = 1_000
+    const blocker = createBlocker()
+    const service = createService(() => now, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus({ receivedAt: 1_000 })])
+    now = 2_000
+    service.setStatuses([workingStatus({ receivedAt: 2_000 })])
+    now = 1_000 + AGENT_AWAKE_STATUS_STALE_AFTER_MS + 1
+    vi.advanceTimersByTime(AGENT_AWAKE_STATUS_STALE_AFTER_MS)
+
+    expect(blocker.stop).not.toHaveBeenCalled()
+    now = 2_000 + AGENT_AWAKE_STATUS_STALE_AFTER_MS + 1
+    vi.advanceTimersByTime(1_000)
+
+    expect(blocker.stop).toHaveBeenCalledWith(1)
+    service.dispose()
+  })
+
+  it('keeps the blocker id when stop fails and Electron reports it is still started', () => {
+    const blocker = createBlocker()
+    blocker.stop.mockImplementation(() => {
+      throw new Error('stop failed')
+    })
+    const service = createService(() => 1_000, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus()])
+    service.setStatuses([])
+    service.setStatuses([])
+
+    expect(blocker.stop).toHaveBeenCalledTimes(2)
+    expect(blocker.stop).toHaveBeenCalledWith(1)
+  })
+
+  it('disposes by clearing timers and stopping an active blocker once', () => {
+    vi.useFakeTimers()
+    const blocker = createBlocker()
+    const service = createService(() => 1_000, blocker)
+
+    service.setEnabled(true)
+    service.setStatuses([workingStatus()])
+    service.dispose()
+    vi.advanceTimersByTime(AGENT_AWAKE_STATUS_STALE_AFTER_MS)
+
+    expect(blocker.stop).toHaveBeenCalledTimes(1)
+    expect(blocker.stop).toHaveBeenCalledWith(1)
+  })
+})
diff --git a/src/main/agent-awake-service.ts b/src/main/agent-awake-service.ts
new file mode 100644
index 00000000000..ae1463f759d
--- /dev/null
+++ b/src/main/agent-awake-service.ts
@@ -0,0 +1,206 @@
+import { powerSaveBlocker } from 'electron'
+import type { AgentStatusState } from '../shared/agent-status-types'
+
+export const AGENT_AWAKE_STATUS_STALE_AFTER_MS = 2 * 60 * 60 * 1000
+
+export type AgentAwakeStatus = {
+  state: AgentStatusState
+  receivedAt: number
+  observedInCurrentRuntime: boolean
+}
+
+type PowerSaveBlocker = {
+  start: (type: 'prevent-app-suspension') => number
+  stop: (id: number) => void
+  isStarted: (id: number) => boolean
+}
+
+type Logger = Pick<Console, 'debug' | 'warn'>
+
+type AgentAwakeServiceOptions = {
+  blocker?: PowerSaveBlocker
+  logger?: Logger
+  now?: () => number
+}
+
+export class AgentAwakeService {
+  private enabled = false
+  private statuses: AgentAwakeStatus[] = []
+  private blockerId: number | null = null
+  private staleTimer: ReturnType<typeof setTimeout> | null = null
+  private readonly blocker: PowerSaveBlocker
+  private readonly logger: Logger
+  private readonly now: () => number
+
+  constructor(options: AgentAwakeServiceOptions = {}) {
+    this.blocker = options.blocker ?? powerSaveBlocker
+    this.logger = options.logger ?? console
+    this.now = options.now ?? Date.now
+  }
+
+  setEnabled(enabled: boolean): void {
+    if (this.enabled === enabled) {
+      return
+    }
+    this.enabled = enabled
+    this.refresh('settings-change')
+  }
+
+  setStatuses(statuses: AgentAwakeStatus[]): void {
+    this.statuses = statuses.map((status) => ({ ...status }))
+    this.refresh('status-change')
+  }
+
+  dispose(): void {
+    this.clearStaleTimer()
+    this.stopBlocker('dispose')
+  }
+
+  private refresh(reason: string): void {
+    this.scheduleStaleTimer()
+    const runningStatusCount = this.getEligibleRunningStatusCount()
+    const shouldBlock = this.enabled && runningStatusCount > 0
+    this.logger.debug('[agent-awake] refresh', {
+      reason,
+      enabled: this.enabled,
+      runningStatusCount,
+      shouldBlock,
+      blockerId: this.blockerId
+    })
+    if (shouldBlock) {
+      this.startBlocker(reason, runningStatusCount)
+    } else {
+      this.stopBlocker(reason, runningStatusCount)
+    }
+  }
+
+  private getEligibleRunningStatusCount(): number {
+    const now = this.now()
+    return this.statuses.filter((status) => this.isWakeEligible(status, now)).length
+  }
+
+  private isWakeEligible(status: AgentAwakeStatus, now: number): boolean {
+    return (
+      status.observedInCurrentRuntime &&
+      status.state === 'working' &&
+      Number.isFinite(status.receivedAt) &&
+      now - status.receivedAt <= AGENT_AWAKE_STATUS_STALE_AFTER_MS
+    )
+  }
+
+  private scheduleStaleTimer(): void {
+    this.clearStaleTimer()
+    const now = this.now()
+    let earliestExpiry: number | null = null
+    for (const status of this.statuses) {
+      if (
+        !status.observedInCurrentRuntime ||
+        status.state !== 'working' ||
+        !Number.isFinite(status.receivedAt)
+      ) {
+        continue
+      }
+      const expiry = status.receivedAt + AGENT_AWAKE_STATUS_STALE_AFTER_MS
+      if (expiry <= now) {
+        continue
+      }
+      earliestExpiry = earliestExpiry === null ? expiry : Math.min(earliestExpiry, expiry)
+    }
+    if (earliestExpiry === null) {
+      return
+    }
+    this.staleTimer = setTimeout(() => {
+      this.staleTimer = null
+      this.refresh('stale-expiry')
+    }, earliestExpiry - now)
+    if (typeof this.staleTimer.unref === 'function') {
+      this.staleTimer.unref()
+    }
+  }
+
+  private clearStaleTimer(): void {
+    if (!this.staleTimer) {
+      return
+    }
+    clearTimeout(this.staleTimer)
+    this.staleTimer = null
+  }
+
+  private startBlocker(reason: string, runningStatusCount: number): void {
+    if (this.blockerId !== null) {
+      if (this.reconcileBlocker('start-reconcile')) {
+        return
+      }
+    }
+    try {
+      const id = this.blocker.start('prevent-app-suspension')
+      this.blockerId = id
+      this.logger.debug('[agent-awake] started blocker', {
+        reason,
+        enabled: this.enabled,
+        runningStatusCount,
+        blockerId: id
+      })
+      this.reconcileBlocker('post-start')
+    } catch (err) {
+      this.logger.warn('[agent-awake] failed to start blocker', {
+        reason,
+        enabled: this.enabled,
+        runningStatusCount,
+        error: err
+      })
+    }
+  }
+
+  private stopBlocker(reason: string, runningStatusCount = 0): void {
+    if (this.blockerId === null) {
+      return
+    }
+    const id = this.blockerId
+    try {
+      this.blocker.stop(id)
+    } catch (err) {
+      this.logger.warn('[agent-awake] failed to stop blocker', {
+        reason,
+        enabled: this.enabled,
+        runningStatusCount,
+        blockerId: id,
+        error: err
+      })
+    }
+    if (!this.reconcileBlocker('post-stop')) {
+      this.logger.debug('[agent-awake] stopped blocker', {
+        reason,
+        enabled: this.enabled,
+        runningStatusCount,
+        blockerId: id
+      })
+    }
+  }
+
+  private reconcileBlocker(reason: string): boolean {
+    if (this.blockerId === null) {
+      return false
+    }
+    const id = this.blockerId
+    try {
+      const isStarted = this.blocker.isStarted(id)
+      this.logger.debug('[agent-awake] reconciled blocker', {
+        reason,
+        blockerId: id,
+        isStarted
+      })
+      if (!isStarted) {
+        this.blockerId = null
+      }
+      return isStarted
+    } catch (err) {
+      this.logger.warn('[agent-awake] failed to reconcile blocker', {
+        reason,
+        blockerId: id,
+        error: err
+      })
+      return true
+    }
+  }
+}
diff --git a/src/main/agent-hooks/server.test.ts b/src/main/agent-hooks/server.test.ts
index 724fc3a4a64..6033bf302d9 100644
--- a/src/main/agent-hooks/server.test.ts
+++ b/src/main/agent-hooks/server.test.ts
@@ -59,6 +59,151 @@ afterEach(() => {
 })
 
 describe('AgentHookServer listener replay', () => {
+  it('allows multiple status-change subscribers to observe the same update', () => {
+    const server = new AgentHookServer()
+    const first = vi.fn()
+    const second = vi.fn()
+    server.subscribeStatusChanges(first)
+    server.subscribeStatusChanges(second)
+
+    server.ingestRemote(
+      {
+        paneKey: PANE,
+        tabId: 'tab-1',
+        worktreeId: 'wt-1',
+        payload: { state: 'working', agentType: 'claude' }
+      },
+      'conn-1'
+    )
+
+    expect(first).toHaveBeenCalledWith([
+      expect.objectContaining({
+        state: 'working',
+        receivedAt: expect.any(Number),
+        observedInCurrentRuntime: true
+      })
+    ])
+    expect(second).toHaveBeenCalledWith([
+      expect.objectContaining({
+        state: 'working',
+        receivedAt: expect.any(Number),
+        observedInCurrentRuntime: true
+      })
+    ])
+  })
+
+  it('keeps status-change subscribers when renderer fanout listener is cleared', () => {
+    const server = new AgentHookServer()
+    const statusChangeListener = vi.fn()
+    const rendererListener = vi.fn()
+    server.subscribeStatusChanges(statusChangeListener)
+    server.setListener(rendererListener)
+    server.setListener(null)
+
+    server.ingestRemote(
+      {
+        paneKey: PANE,
+        tabId: 'tab-1',
+        worktreeId: 'wt-1',
+        payload: { state: 'working', agentType: 'claude' }
+      },
+      'conn-1'
+    )
+
+    expect(statusChangeListener).toHaveBeenCalledTimes(1)
+    expect(rendererListener).not.toHaveBeenCalled()
+  })
+
+  it('unsubscribes status-change listeners without removing the remaining listeners', () => {
+    const server = new AgentHookServer()
+    const removed = vi.fn()
+    const remaining = vi.fn()
+    const unsubscribe = server.subscribeStatusChanges(removed)
+    server.subscribeStatusChanges(remaining)
+
+    unsubscribe()
+    server.ingestRemote(
+      {
+        paneKey: PANE,
+        tabId: 'tab-1',
+        worktreeId: 'wt-1',
+        payload: { state: 'working', agentType: 'claude' }
+      },
+      'conn-1'
+    )
+
+    expect(removed).not.toHaveBeenCalled()
+    expect(remaining).toHaveBeenCalledWith([
+      expect.objectContaining({
+        state: 'working',
+        observedInCurrentRuntime: true
+      })
+    ])
+  })
+
+  it('notifies status-change subscribers when a working status is dropped or cleared', () => {
+    const server = new AgentHookServer()
+    const listener = vi.fn()
+    server.subscribeStatusChanges(listener)
+
+    server.ingestRemote(
+      {
+        paneKey: PANE,
+        tabId: 'tab-1',
+        worktreeId: 'wt-1',
+        payload: { state: 'working', agentType: 'claude' }
+      },
+      'conn-1'
+    )
+    server.dropStatusEntry(PANE)
+    server.ingestRemote(
+      {
+        paneKey: PANE,
+        tabId: 'tab-1',
+        worktreeId: 'wt-1',
+        payload: { state: 'working', agentType: 'claude' }
+      },
+      'conn-1'
+    )
+    server.clearPaneState(PANE)
+
+    expect(listener).toHaveBeenNthCalledWith(2, [])
+    expect(listener).toHaveBeenNthCalledWith(4, [])
+  })
+
+  it('hydrates cached statuses as not observed in the current runtime', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'orca-agent-hooks-'))
+    const firstServer = new AgentHookServer()
+    const secondServer = new AgentHookServer()
+    try {
+      await firstServer.start({ env: 'production', userDataPath: dir })
+      firstServer.ingestRemote(
+        {
+          paneKey: PANE,
+          tabId: 'tab-1',
+          worktreeId: 'wt-1',
+          payload: { state: 'working', agentType: 'claude' }
+        },
+        'conn-1'
+      )
+      firstServer.flushStatusPersistSync()
+      firstServer.stop()
+
+      await secondServer.start({ env: 'production', userDataPath: dir })
+
+      expect(secondServer.getStatusChangeSnapshot()).toEqual([
+        expect.objectContaining({
+          state: 'working',
+          observedInCurrentRuntime: false
+        })
+      ])
+    } finally {
+      firstServer.stop()
+      secondServer.stop()
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
   it('replays the latest retained pane status when a listener attaches after windowless events', async () => {
     const server = new AgentHookServer()
     await server.start({ env: 'production' })
diff --git a/src/main/agent-hooks/server.ts b/src/main/agent-hooks/server.ts
index cd715bcc598..9c3f736828d 100644
--- a/src/main/agent-hooks/server.ts
+++ b/src/main/agent-hooks/server.ts
@@ -36,6 +36,7 @@ import {
 import type { AgentHookSource } from '../../shared/agent-hook-relay'
 import {
   type AgentStatusIpcPayload,
+  type AgentStatusState,
   normalizeAgentStatusPayload
 } from '../../shared/agent-status-types'
 
@@ -54,6 +55,14 @@ type EnrichedAgentHookEventPayload = AgentHookEventPayload & {
   stateStartedAt: number
 }
 
+export type AgentHookStatusChangeEntry = {
+  state: AgentStatusState
+  receivedAt: number
+  observedInCurrentRuntime: boolean
+}
+
+type StatusChangeListener = (statuses: AgentHookStatusChangeEntry[]) => void
+
 // Why: name of the on-disk cache that survives Orca restart. Lives next to
 // the endpoint file in userData/agent-hooks/ so all hook-server-owned cross-
 // restart artifacts stay co-located.
@@ -199,6 +208,7 @@ export class AgentHookServer {
   // caller's knowledge of whether this is a packaged build.
   private env = 'production'
   private onAgentStatus: ((payload: EnrichedAgentHookEventPayload) => void) | null = null
+  private statusChangeListeners = new Set<StatusChangeListener>()
   // Why: directory that holds the on-disk endpoint file. Set via start()'s
   // `userDataPath` option so the class has no direct Electron dependency
   // (keeps it mockable in the vitest node environment).
@@ -209,6 +219,9 @@ export class AgentHookServer {
   // by paneKey). Held on the instance instead of as module-level Maps so
   // tests can spin up multiple servers without state cross-contamination.
   private state: HookListenerState = createHookListenerState()
+  // Why: hydrated last-status rows are useful UI continuity, but they are not
+  // evidence of live agent work in this main-process runtime.
+  private runtimeObservedStatusPaneKeys = new Set<string>()
   // Why: full path to the on-disk last-status cache. Set in start() from
   // userDataPath. Null when the server runs without a userDataPath (e.g.
   // tests that skip the userDataPath option) — in that case, persistence is
@@ -243,6 +256,13 @@ export class AgentHookServer {
     }
   }
 
+  subscribeStatusChanges(listener: StatusChangeListener): () => void {
+    this.statusChangeListeners.add(listener)
+    return () => {
+      this.statusChangeListeners.delete(listener)
+    }
+  }
+
   /** Snapshot of the current cached statuses, in the IPC-shaped form the
    *  renderer consumes. Used by the `agentStatus:getSnapshot` IPC after
    *  workspace tabs have hydrated, so the dashboard catches up on any
@@ -253,6 +273,31 @@ export class AgentHookServer {
     )
   }
 
+  getStatusChangeSnapshot(): AgentHookStatusChangeEntry[] {
+    return Array.from(this.state.lastStatusByPaneKey.entries(), ([paneKey, entry]) => {
+      const enriched = entry as EnrichedAgentHookEventPayload
+      return {
+        state: enriched.payload.state,
+        receivedAt: enriched.receivedAt,
+        observedInCurrentRuntime: this.runtimeObservedStatusPaneKeys.has(paneKey)
+      }
+    })
+  }
+
+  private notifyStatusChangeListeners(): void {
+    if (this.statusChangeListeners.size === 0) {
+      return
+    }
+    const snapshot = this.getStatusChangeSnapshot()
+    for (const listener of this.statusChangeListeners) {
+      try {
+        listener(snapshot)
+      } catch (err) {
+        console.error('[agent-hooks] status-change listener threw', err)
+      }
+    }
+  }
+
   private attachStatusTiming(payload: AgentHookEventPayload): EnrichedAgentHookEventPayload {
     const now = Date.now()
     const previous = this.state.lastStatusByPaneKey.get(payload.paneKey) as
@@ -354,8 +399,10 @@ export class AgentHookServer {
       payload: normalizedPayload
     }
     const enriched = this.attachStatusTiming(event)
+    this.runtimeObservedStatusPaneKeys.add(paneKey)
     this.state.lastStatusByPaneKey.set(paneKey, enriched)
     this.scheduleStatusPersist()
+    this.notifyStatusChangeListeners()
     this.onAgentStatus?.(enriched)
   }
 
@@ -416,8 +463,10 @@ export class AgentHookServer {
         const normalized = normalizeHookPayload(this.state, source, body, this.env)
         if (normalized) {
           const enriched = this.attachStatusTiming(normalized)
+          this.runtimeObservedStatusPaneKeys.add(enriched.paneKey)
           this.state.lastStatusByPaneKey.set(enriched.paneKey, enriched)
           this.scheduleStatusPersist()
+          this.notifyStatusChangeListeners()
           this.onAgentStatus?.(enriched)
         }
 
@@ -477,7 +526,9 @@ export class AgentHookServer {
     this.endpointFileWritten = false
     this.lastStatusFilePath = null
     this.lastWrittenJson = null
+    this.runtimeObservedStatusPaneKeys.clear()
     clearAllListenerCaches(this.state)
+    this.notifyStatusChangeListeners()
   }
 
   /** Why: invoked from the renderer-driven agentStatus:drop IPC when a user
@@ -492,7 +543,9 @@ export class AgentHookServer {
       return
     }
     this.state.lastStatusByPaneKey.delete(paneKey)
+    this.runtimeObservedStatusPaneKeys.delete(paneKey)
     this.scheduleStatusPersist()
+    this.notifyStatusChangeListeners()
   }
 
   clearPaneState(paneKey: string): void {
@@ -503,7 +556,9 @@ export class AgentHookServer {
     const hadStatus = this.state.lastStatusByPaneKey.has(paneKey)
     clearPaneCacheState(this.state, paneKey)
     if (hadStatus) {
+      this.runtimeObservedStatusPaneKeys.delete(paneKey)
       this.scheduleStatusPersist()
+      this.notifyStatusChangeListeners()
     }
   }
 
diff --git a/src/main/codex-accounts/runtime-home-service.test.ts b/src/main/codex-accounts/runtime-home-service.test.ts
index 35164220fca..d2d914e14ef 100644
--- a/src/main/codex-accounts/runtime-home-service.test.ts
+++ b/src/main/codex-accounts/runtime-home-service.test.ts
@@ -98,6 +98,7 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     opencodeWorkspaceId: '',
     geminiCliOAuthEnabled: false,
     agentCmdOverrides: {},
+    keepComputerAwakeWhileAgentsRun: false,
     terminalMacOptionAsAlt: 'false',
     terminalMacOptionAsAltMigrated: true,
     experimentalMobile: false,
diff --git a/src/main/codex-accounts/service.test.ts b/src/main/codex-accounts/service.test.ts
index 3a44b1bf7f6..89f82473d7d 100644
--- a/src/main/codex-accounts/service.test.ts
+++ b/src/main/codex-accounts/service.test.ts
@@ -91,6 +91,7 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     opencodeWorkspaceId: '',
     geminiCliOAuthEnabled: false,
     agentCmdOverrides: {},
+    keepComputerAwakeWhileAgentsRun: false,
     terminalMacOptionAsAlt: 'false',
     terminalMacOptionAsAltMigrated: true,
     experimentalMobile: false,
diff --git a/src/main/index.ts b/src/main/index.ts
index 7da6e4fa722..d034bac1ff6 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -65,6 +65,7 @@ import { browserManager } from './browser/browser-manager'
 import { setUnreadDockBadgeCount } from './dock/unread-badge'
 import { registerFeatureWallFirstAgentTour } from './feature-wall/first-agent-tour'
 import { AutomationService } from './automations/service'
+import { AgentAwakeService } from './agent-awake-service'
 
 let mainWindow: BrowserWindow | null = null
 /** Whether a manual app.quit() (Cmd+Q, etc.) is in progress. Shared with the
@@ -83,6 +84,8 @@ let runtime: OrcaRuntimeService | null = null
 let rateLimits: RateLimitService | null = null
 let runtimeRpc: OrcaRuntimeRpcServer | null = null
 let starNag: StarNagService | null = null
+let agentAwakeService: AgentAwakeService | null = null
+let unsubscribeAgentAwakeStatusChanges: (() => void) | null = null
 let disposeFeatureWallFirstAgentTour: (() => void) | null = null
 let watcherShutdownPromise: Promise<void> | null = null
 let watcherShutdownDone = false
@@ -278,7 +281,8 @@ function openMainWindow(): BrowserWindow {
           ? codexRuntimeHome!.prepareForCodexLaunch()
           : null,
       prepareForClaudeLaunch: () => claudeRuntimeAuth!.prepareForClaudeLaunch()
-    }
+    },
+    agentAwakeService ?? undefined
   )
   automations.setWebContents(window.webContents)
   automations.start()
@@ -618,6 +622,15 @@ app.whenReady().then(async () => {
   }
 
   store = new Store()
+  agentAwakeService = new AgentAwakeService()
+  agentAwakeService.setEnabled(store.getSettings().keepComputerAwakeWhileAgentsRun)
+  // Why: disk-hydrated status rows are UI continuity only. The service starts
+  // from an empty snapshot; only hook events observed in this runtime can keep
+  // the local computer awake.
+  agentAwakeService.setStatuses([])
+  unsubscribeAgentAwakeStatusChanges = agentHookServer.subscribeStatusChanges((statuses) => {
+    agentAwakeService?.setStatuses(statuses)
+  })
   // Why: telemetry must initialize before any IPC handler / renderer can
   // call `track()`. The client is a no-op in dev/contributor builds
   // (`IS_OFFICIAL_BUILD === false`) and a no-op while `TELEMETRY_ENABLED`
@@ -860,6 +873,10 @@ app.whenReady().then(async () => {
 
 app.on('before-quit', () => {
   isQuitting = true
+  unsubscribeAgentAwakeStatusChanges?.()
+  unsubscribeAgentAwakeStatusChanges = null
+  agentAwakeService?.dispose()
+  agentAwakeService = null
   disposeFeatureWallFirstAgentTour?.()
   disposeFeatureWallFirstAgentTour = null
   // Why: PTY cleanup is deferred to will-quit so the renderer has a chance to
diff --git a/src/main/ipc/register-core-handlers.test.ts b/src/main/ipc/register-core-handlers.test.ts
index aab98e262f9..7ff589620fc 100644
--- a/src/main/ipc/register-core-handlers.test.ts
+++ b/src/main/ipc/register-core-handlers.test.ts
@@ -328,7 +328,7 @@ describe('registerCoreHandlers', () => {
     expect(registerNotificationHandlersMock).toHaveBeenCalledWith(store, runtime)
     expect(registerDeveloperPermissionHandlersMock).toHaveBeenCalled()
     expect(registerComputerUsePermissionHandlersMock).toHaveBeenCalled()
-    expect(registerSettingsHandlersMock).toHaveBeenCalledWith(store)
+    expect(registerSettingsHandlersMock).toHaveBeenCalledWith(store, undefined)
     expect(registerWorkspaceSpaceHandlersMock).toHaveBeenCalledWith(store)
     expect(registerTelemetryHandlersMock).toHaveBeenCalledWith(store)
     expect(registerSessionHandlersMock).toHaveBeenCalledWith(store)
diff --git a/src/main/ipc/register-core-handlers.ts b/src/main/ipc/register-core-handlers.ts
index 2bfb4c71d86..b6d87da3947 100644
--- a/src/main/ipc/register-core-handlers.ts
+++ b/src/main/ipc/register-core-handlers.ts
@@ -55,6 +55,7 @@ import type { RateLimitService } from '../rate-limits/service'
 import type { CodexAccountService } from '../codex-accounts/service'
 import type { ClaudeAccountService } from '../claude-accounts/service'
 import type { AutomationService } from '../automations/service'
+import type { AgentAwakeService } from '../agent-awake-service'
 
 let registered = false
 
@@ -69,7 +70,8 @@ export function registerCoreHandlers(
   rateLimits: RateLimitService,
   mainWindowWebContentsId: number | null = null,
   automations?: AutomationService,
-  commitMessageAgentEnv?: CommitMessageAgentEnvironmentResolvers
+  commitMessageAgentEnv?: CommitMessageAgentEnvironmentResolvers,
+  agentAwakeService?: AgentAwakeService
 ): void {
   // Why: on macOS the app can stay alive after all windows close, then
   // openMainWindow() is called again on 'activate'. ipcMain.handle() throws
@@ -105,7 +107,7 @@ export function registerCoreHandlers(
   registerOnboardingHandlers(store)
   registerDeveloperPermissionHandlers()
   registerComputerUsePermissionHandlers()
-  registerSettingsHandlers(store)
+  registerSettingsHandlers(store, agentAwakeService)
   if (automations) {
     registerAutomationHandlers(store, automations)
   }
diff --git a/src/main/ipc/settings.test.ts b/src/main/ipc/settings.test.ts
index 75d66845bdd..7f50d8fa87e 100644
--- a/src/main/ipc/settings.test.ts
+++ b/src/main/ipc/settings.test.ts
@@ -6,7 +6,8 @@ const { handleMock, previewGhosttyImportMock } = vi.hoisted(() => ({
 }))
 
 vi.mock('electron', () => ({
-  ipcMain: { handle: handleMock }
+  ipcMain: { handle: handleMock },
+  nativeTheme: { themeSource: 'system' }
 }))
 
 vi.mock('../ghostty/index', () => ({
@@ -26,6 +27,8 @@ describe('registerSettingsHandlers', () => {
   beforeEach(() => {
     handleMock.mockClear()
     previewGhosttyImportMock.mockClear()
+    store.getSettings.mockReset()
+    store.updateSettings.mockReset()
   })
 
   it('registers settings:previewGhosttyImport handler', () => {
@@ -47,4 +50,36 @@ describe('registerSettingsHandlers', () => {
     expect(result).toEqual(expected)
     expect(previewGhosttyImportMock).toHaveBeenCalledWith(store)
   })
+
+  it('updates the agent awake service when the keep-awake setting changes', () => {
+    const agentAwakeService = { setEnabled: vi.fn() }
+    store.getSettings.mockReturnValue({ keepComputerAwakeWhileAgentsRun: false })
+    store.updateSettings.mockReturnValue({ keepComputerAwakeWhileAgentsRun: true })
+    registerSettingsHandlers(store as never, agentAwakeService as never)
+
+    const handler = handleMock.mock.calls.find((call) => call[0] === 'settings:set')?.[1] as (
+      _event: unknown,
+      args: unknown
+    ) => unknown
+
+    handler(null, { keepComputerAwakeWhileAgentsRun: true })
+
+    expect(agentAwakeService.setEnabled).toHaveBeenCalledWith(true)
+  })
+
+  it('does not notify the agent awake service for unrelated setting changes', () => {
+    const agentAwakeService = { setEnabled: vi.fn() }
+    store.getSettings.mockReturnValue({ keepComputerAwakeWhileAgentsRun: false })
+    store.updateSettings.mockReturnValue({ keepComputerAwakeWhileAgentsRun: false })
+    registerSettingsHandlers(store as never, agentAwakeService as never)
+
+    const handler = handleMock.mock.calls.find((call) => call[0] === 'settings:set')?.[1] as (
+      _event: unknown,
+      args: unknown
+    ) => unknown
+
+    handler(null, { defaultTuiAgent: 'codex' })
+
+    expect(agentAwakeService.setEnabled).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/main/ipc/settings.ts b/src/main/ipc/settings.ts
index 2029227ef12..9783340bfd0 100644
--- a/src/main/ipc/settings.ts
+++ b/src/main/ipc/settings.ts
@@ -6,6 +6,7 @@ import { previewGhosttyImport } from '../ghostty/index'
 import { rebuildAppMenu } from '../menu/register-app-menu'
 import { track } from '../telemetry/client'
 import { SETTINGS_CHANGED_WHITELIST, type SettingsChangedKey } from '../../shared/telemetry-events'
+import type { AgentAwakeService } from '../agent-awake-service'
 
 // Why: the whitelist is the source-of-truth for which keys we emit on. Casting
 // to a Set once at module load lets the IPC handler's per-key membership
@@ -21,7 +22,10 @@ const APPEARANCE_MENU_KEYS: readonly (keyof GlobalSettings)[] = [
   'showTitlebarAppName'
 ]
 
-export function registerSettingsHandlers(store: Store): void {
+export function registerSettingsHandlers(
+  store: Store,
+  agentAwakeService?: AgentAwakeService
+): void {
   ipcMain.handle('settings:get', () => {
     return store.getSettings()
   })
@@ -36,6 +40,9 @@ export function registerSettingsHandlers(store: Store): void {
     // no-op flip would inflate the experimental-feature-adoption signal.
     const before = store.getSettings()
     const result = store.updateSettings(args)
+    if ('keepComputerAwakeWhileAgentsRun' in args) {
+      agentAwakeService?.setEnabled(result.keepComputerAwakeWhileAgentsRun)
+    }
     if (APPEARANCE_MENU_KEYS.some((key) => key in args)) {
       rebuildAppMenu()
     }
diff --git a/src/renderer/src/components/settings/AgentAwakeSetting.tsx b/src/renderer/src/components/settings/AgentAwakeSetting.tsx
new file mode 100644
index 00000000000..375f849f5c9
--- /dev/null
+++ b/src/renderer/src/components/settings/AgentAwakeSetting.tsx
@@ -0,0 +1,51 @@
+import type { GlobalSettings } from '../../../../shared/types'
+import { Label } from '../ui/label'
+import { SearchableSetting } from './SearchableSetting'
+
+type AgentAwakeSettingProps = {
+  settings: GlobalSettings
+  updateSettings: (updates: Partial<GlobalSettings>) => void
+}
+
+export function AgentAwakeSetting({
+  settings,
+  updateSettings
+}: AgentAwakeSettingProps): React.JSX.Element {
+  return (
+    <section className="space-y-3">
+      <SearchableSetting
+        title="Keep computer awake when Orca sees agents running"
+        description="Prevents this computer from sleeping while Orca sees an agent working. The display can still turn off."
+        keywords={['awake', 'sleep', 'power', 'agent', 'running']}
+        className="flex items-start justify-between gap-4 px-1 py-2"
+      >
+        <div className="min-w-0 shrink space-y-0.5">
+          <Label>Keep computer awake when Orca sees agents running</Label>
+          <p className="text-xs text-muted-foreground">
+            Prevents this computer from sleeping while Orca sees an agent working. The display can
+            still turn off.
+          </p>
+        </div>
+        <button
+          role="switch"
+          aria-label="Keep computer awake when Orca sees agents running"
+          aria-checked={settings.keepComputerAwakeWhileAgentsRun}
+          onClick={() =>
+            updateSettings({
+              keepComputerAwakeWhileAgentsRun: !settings.keepComputerAwakeWhileAgentsRun
+            })
+          }
+          className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-colors ${
+            settings.keepComputerAwakeWhileAgentsRun ? 'bg-foreground' : 'bg-muted-foreground/30'
+          }`}
+        >
+          <span
+            className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
+              settings.keepComputerAwakeWhileAgentsRun ? 'translate-x-4' : 'translate-x-0.5'
+            }`}
+          />
+        </button>
+      </SearchableSetting>
+    </section>
+  )
+}
diff --git a/src/renderer/src/components/settings/AgentsPane.test.tsx b/src/renderer/src/components/settings/AgentsPane.test.tsx
new file mode 100644
index 00000000000..00a7059e101
--- /dev/null
+++ b/src/renderer/src/components/settings/AgentsPane.test.tsx
@@ -0,0 +1,101 @@
+import React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getDefaultSettings } from '../../../../shared/constants'
+import type { GlobalSettings } from '../../../../shared/types'
+import { useAppStore } from '../../store'
+import { AgentAwakeSetting } from './AgentAwakeSetting'
+import { AgentsPane, AGENTS_PANE_SEARCH_ENTRIES } from './AgentsPane'
+import { matchesSettingsSearch } from './settings-search'
+
+type ReactElementLike = {
+  type: unknown
+  props: Record<string, unknown>
+}
+
+function renderPane(settings: GlobalSettings): string {
+  return renderToStaticMarkup(
+    React.createElement(AgentsPane, {
+      settings,
+      updateSettings: vi.fn()
+    })
+  )
+}
+
+function visit(node: unknown, cb: (node: ReactElementLike) => void): void {
+  if (node == null || typeof node === 'string' || typeof node === 'number') {
+    return
+  }
+  if (Array.isArray(node)) {
+    node.forEach((entry) => visit(entry, cb))
+    return
+  }
+  const element = node as ReactElementLike
+  cb(element)
+  if (element.props?.children) {
+    visit(element.props.children, cb)
+  }
+}
+
+function findSwitch(node: unknown): ReactElementLike {
+  let found: ReactElementLike | null = null
+  visit(node, (entry) => {
+    if (entry.props.role === 'switch') {
+      found = entry
+    }
+  })
+  if (!found) {
+    throw new Error('switch not found')
+  }
+  return found
+}
+
+describe('AgentsPane', () => {
+  beforeEach(() => {
+    useAppStore.setState({
+      settingsSearchQuery: '',
+      detectedAgentIds: ['claude'],
+      isDetectingAgents: false,
+      isRefreshingAgents: false
+    })
+  })
+
+  it('renders the keep-awake toggle from settings', () => {
+    const markup = renderPane(getDefaultSettings('/tmp'))
+
+    expect(markup).toContain('Keep computer awake when Orca sees agents running')
+    expect(markup).toContain(
+      'Prevents this computer from sleeping while Orca sees an agent working. The display can still turn off.'
+    )
+    expect(markup).toContain('aria-checked="false"')
+  })
+
+  it('toggles the keep-awake setting with the next value', () => {
+    const updateSettings = vi.fn()
+    const element = AgentAwakeSetting({
+      settings: {
+        ...getDefaultSettings('/tmp'),
+        keepComputerAwakeWhileAgentsRun: false
+      },
+      updateSettings
+    })
+
+    const keepAwakeSwitch = findSwitch(element)
+    expect(keepAwakeSwitch.props['aria-label']).toBe(
+      'Keep computer awake when Orca sees agents running'
+    )
+    expect(keepAwakeSwitch.props['aria-checked']).toBe(false)
+
+    const onClick = keepAwakeSwitch.props.onClick as () => void
+    onClick()
+
+    expect(updateSettings).toHaveBeenCalledWith({
+      keepComputerAwakeWhileAgentsRun: true
+    })
+  })
+
+  it('includes awake and sleep search metadata for the setting', () => {
+    expect(matchesSettingsSearch('awake', AGENTS_PANE_SEARCH_ENTRIES)).toBe(true)
+    expect(matchesSettingsSearch('sleep', AGENTS_PANE_SEARCH_ENTRIES)).toBe(true)
+  })
+})
diff --git a/src/renderer/src/components/settings/AgentsPane.tsx b/src/renderer/src/components/settings/AgentsPane.tsx
index 5b55b96a549..01e1c4bcd70 100644
--- a/src/renderer/src/components/settings/AgentsPane.tsx
+++ b/src/renderer/src/components/settings/AgentsPane.tsx
@@ -6,6 +6,7 @@ import { useDetectedAgents } from '@/hooks/useDetectedAgents'
 import { Button } from '../ui/button'
 import { Input } from '../ui/input'
 import { cn } from '@/lib/utils'
+import { AgentAwakeSetting } from './AgentAwakeSetting'
 
 export { AGENTS_PANE_SEARCH_ENTRIES } from './agents-search'
 
@@ -336,6 +337,8 @@ export function AgentsPane({ settings, updateSettings }: AgentsPaneProps): React
         </div>
       </section>
 
+      <AgentAwakeSetting settings={settings} updateSettings={updateSettings} />
+
       {/* Detected agents */}
       {detectedAgents.length > 0 && (
         <section className="space-y-3">
diff --git a/src/renderer/src/components/settings/agents-search.ts b/src/renderer/src/components/settings/agents-search.ts
index 5be39975023..b82fe2e1d1c 100644
--- a/src/renderer/src/components/settings/agents-search.ts
+++ b/src/renderer/src/components/settings/agents-search.ts
@@ -37,5 +37,11 @@ export const AGENTS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
       'install',
       'detected'
     ]
+  },
+  {
+    title: 'Keep computer awake when Orca sees agents running',
+    description:
+      'Prevents this computer from sleeping while Orca sees an agent working. The display can still turn off.',
+    keywords: ['awake', 'sleep', 'power', 'agent', 'running']
   }
 ]
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index b7e77955f2c..9e602188d55 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -234,6 +234,7 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     opencodeWorkspaceId: '',
     geminiCliOAuthEnabled: false,
     agentCmdOverrides: {},
+    keepComputerAwakeWhileAgentsRun: false,
     // Why: 'auto' runs a layout-aware probe at boot (see
     // src/renderer/src/lib/keyboard-layout/*) that picks 'true' for US and
     // US-International and 'false' for every other layout. This mirrors
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 3142a33f25c..53ec7a17340 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1349,6 +1349,8 @@ export type GlobalSettings = {
   geminiCliOAuthEnabled: boolean
   /** Per-agent CLI command overrides. A missing key means use the catalog default binary name. */
   agentCmdOverrides: Partial<Record<TuiAgent, string>>
+  /** When true, Orca prevents local app suspension while hook-reported agents are working. */
+  keepComputerAwakeWhileAgentsRun: boolean
   /** Why: macOS terminals must choose between letting Option compose layout
    *  characters (@ on German, € on French) or treating Option as Meta/Esc for
    *  readline shortcuts. Mirrors Ghostty's macos-option-as-alt setting — and
diff --git a/tests/e2e/settings-agent-awake.spec.ts b/tests/e2e/settings-agent-awake.spec.ts
new file mode 100644
index 00000000000..8627ca1d1f4
--- /dev/null
+++ b/tests/e2e/settings-agent-awake.spec.ts
@@ -0,0 +1,54 @@
+import { test, expect } from './helpers/orca-app'
+import { waitForSessionReady } from './helpers/store'
+import type { GlobalSettings } from '../../src/shared/types'
+
+async function getSettings(
+  page: Parameters<typeof waitForSessionReady>[0]
+): Promise<GlobalSettings> {
+  return page.evaluate(() => window.api.settings.get())
+}
+
+async function openSettings(page: Parameters<typeof waitForSessionReady>[0]): Promise<void> {
+  await page.evaluate(() => {
+    window.__store!.getState().openSettingsPage()
+  })
+  await expect(page.getByPlaceholder('Search settings')).toBeVisible({ timeout: 10_000 })
+}
+
+test.describe('Agent awake setting', () => {
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+  })
+
+  test('can be toggled from Agents settings and persists through IPC', async ({ orcaPage }) => {
+    await openSettings(orcaPage)
+    await orcaPage.getByPlaceholder('Search settings').fill('awake')
+
+    await expect(
+      orcaPage.getByText('Keep computer awake when Orca sees agents running').first()
+    ).toBeVisible()
+
+    const keepAwakeSwitch = orcaPage.getByRole('switch', {
+      name: 'Keep computer awake when Orca sees agents running'
+    })
+
+    await expect(keepAwakeSwitch).toHaveAttribute('aria-checked', 'false')
+    await keepAwakeSwitch.click()
+    await expect(keepAwakeSwitch).toHaveAttribute('aria-checked', 'true')
+    await expect
+      .poll(async () => (await getSettings(orcaPage)).keepComputerAwakeWhileAgentsRun, {
+        timeout: 5_000,
+        message: 'keep-awake setting did not persist after enabling'
+      })
+      .toBe(true)
+
+    await keepAwakeSwitch.click()
+    await expect(keepAwakeSwitch).toHaveAttribute('aria-checked', 'false')
+    await expect
+      .poll(async () => (await getSettings(orcaPage)).keepComputerAwakeWhileAgentsRun, {
+        timeout: 5_000,
+        message: 'keep-awake setting did not persist after disabling'
+      })
+      .toBe(false)
+  })
+})

From da95082fd72dde292a4506c6a3ce72a502e1132d Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 15 May 2026 14:26:32 -0400
Subject: [PATCH 40/82] Fix MCP config inspection file probing (#1932)

Co-authored-by: Orca <help@stably.ai>
---
 .../components/settings/McpConfigFileRow.tsx  | 117 +++++++
 .../components/settings/McpConfigSection.tsx  | 297 +++++++++---------
 src/shared/mcp-config.test.ts                 |  42 ++-
 src/shared/mcp-config.ts                      |  52 +++
 4 files changed, 353 insertions(+), 155 deletions(-)
 create mode 100644 src/renderer/src/components/settings/McpConfigFileRow.tsx

diff --git a/src/renderer/src/components/settings/McpConfigFileRow.tsx b/src/renderer/src/components/settings/McpConfigFileRow.tsx
new file mode 100644
index 00000000000..7f640800eb1
--- /dev/null
+++ b/src/renderer/src/components/settings/McpConfigFileRow.tsx
@@ -0,0 +1,117 @@
+import { AlertCircle, CheckCircle2 } from 'lucide-react'
+import type { McpConfigInspection } from '../../../../shared/mcp-config'
+import { Button } from '../ui/button'
+
+export type LoadedMcpConfigInspection = McpConfigInspection & {
+  absolutePath: string
+  readError?: string
+}
+
+type McpConfigFileRowProps = {
+  config: LoadedMcpConfigInspection
+  onOpen: (config: LoadedMcpConfigInspection) => void
+}
+
+function statusLabel(config: LoadedMcpConfigInspection): string {
+  if (config.readError) {
+    return 'Unreadable'
+  }
+  if (config.status === 'missing') {
+    return 'Not found'
+  }
+  if (config.status === 'invalid') {
+    return 'Invalid JSON'
+  }
+  if (config.servers.length === 0) {
+    return 'No servers'
+  }
+  return `${config.servers.length} server${config.servers.length === 1 ? '' : 's'}`
+}
+
+function statusClassName(config: LoadedMcpConfigInspection): string {
+  if (config.readError || config.status === 'invalid') {
+    return 'border-destructive/30 bg-destructive/10 text-destructive'
+  }
+  if (config.status === 'valid' && config.servers.length > 0) {
+    return 'border-border/60 bg-background text-foreground'
+  }
+  return 'border-border/60 bg-muted/60 text-muted-foreground'
+}
+
+function serverDetailLabel(server: LoadedMcpConfigInspection['servers'][number]): string {
+  if (server.transport === 'http') {
+    return server.url ?? 'HTTP server'
+  }
+  if (server.transport === 'stdio') {
+    return server.command ?? 'stdio server'
+  }
+  return server.issue ?? 'Invalid server'
+}
+
+export function McpConfigFileRow({ config, onOpen }: McpConfigFileRowProps): React.JSX.Element {
+  return (
+    <div className="space-y-2 px-3 py-2.5">
+      <div className="flex items-center gap-2">
+        {config.status === 'valid' && !config.readError ? (
+          <CheckCircle2 className="size-3.5 shrink-0 text-muted-foreground" />
+        ) : (
+          <AlertCircle className="size-3.5 shrink-0 text-destructive" />
+        )}
+        <div className="min-w-0 flex-1">
+          <div className="flex min-w-0 items-center gap-2">
+            <p className="truncate text-sm font-medium">{config.candidate.label}</p>
+            <p className="truncate font-mono text-[11px] text-muted-foreground">
+              {config.candidate.relativePath}
+            </p>
+          </div>
+        </div>
+        <span
+          className={`shrink-0 rounded-full border px-1.5 py-0.5 text-[10px] font-medium ${statusClassName(config)}`}
+        >
+          {statusLabel(config)}
+        </span>
+        {config.exists ? (
+          <Button variant="outline" size="xs" onClick={() => onOpen(config)}>
+            Open
+          </Button>
+        ) : null}
+      </div>
+
+      {config.error || config.readError ? (
+        <p className="pl-5 text-xs text-destructive">{config.readError ?? config.error}</p>
+      ) : null}
+
+      {config.servers.length > 0 ? (
+        <div className="grid gap-1.5 pl-5">
+          {config.servers.map((server) => (
+            <div
+              key={server.name}
+              className="grid grid-cols-[minmax(0,1fr)_auto] gap-2 rounded-md border border-border/40 bg-background/50 px-2.5 py-1.5"
+            >
+              <div className="min-w-0">
+                <div className="flex items-center gap-1.5">
+                  <span className="truncate text-xs font-medium">{server.name}</span>
+                  <span className="rounded-full bg-muted px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-wider text-muted-foreground">
+                    {server.transport}
+                  </span>
+                </div>
+                <p className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
+                  {serverDetailLabel(server)}
+                </p>
+                {server.env && Object.keys(server.env).length > 0 ? (
+                  <p className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
+                    env:{' '}
+                    {Object.entries(server.env)
+                      .map(([key, value]) => `${key}=${value}`)
+                      .join(', ')}
+                  </p>
+                ) : null}
+              </div>
+              <span className="self-start text-[11px] text-muted-foreground">{server.status}</span>
+            </div>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/settings/McpConfigSection.tsx b/src/renderer/src/components/settings/McpConfigSection.tsx
index 7c662c30126..6506e332dff 100644
--- a/src/renderer/src/components/settings/McpConfigSection.tsx
+++ b/src/renderer/src/components/settings/McpConfigSection.tsx
@@ -1,23 +1,24 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
-import { AlertCircle, CheckCircle2, FileCode2, LoaderCircle, Plus, RefreshCw } from 'lucide-react'
+import { AlertCircle, FileCode2, LoaderCircle, Plus, RefreshCw } from 'lucide-react'
 import { toast } from 'sonner'
 import type { Repo, Worktree } from '../../../../shared/types'
 import { getRepoIdFromWorktreeId } from '../../../../shared/worktree-id'
 import {
+  canInspectLocalMcpConfigRoot,
+  getMcpConfigCandidateParentDir,
+  getMcpConfigParentDirs,
   inspectMcpConfigContent,
   MCP_CONFIG_CANDIDATES,
   MCP_STARTER_CONFIG,
-  type McpConfigInspection
+  selectExistingMcpConfigCandidates,
+  type McpConfigDirectoryEntry
 } from '../../../../shared/mcp-config'
 import { useAppStore } from '../../store'
 import { joinPath } from '../../lib/path'
 import { extractIpcErrorMessage } from '../../lib/ipc-error'
 import { Button } from '../ui/button'
-
-type LoadedInspection = McpConfigInspection & {
-  absolutePath: string
-  readError?: string
-}
+import { isWindowsUserAgent } from '../terminal-pane/pane-helpers'
+import { McpConfigFileRow, type LoadedMcpConfigInspection } from './McpConfigFileRow'
 
 type McpConfigSectionProps = {
   repo: Repo
@@ -30,50 +31,10 @@ function isMissingFileError(error: unknown): boolean {
   return /ENOENT|no such file|not found/i.test(message)
 }
 
-function isNoFilesystemProviderMessage(message: string | undefined): boolean {
-  return message ? /no filesystem provider/i.test(message) : false
-}
-
-function countServers(configs: LoadedInspection[]): number {
+function countServers(configs: LoadedMcpConfigInspection[]): number {
   return configs.reduce((sum, config) => sum + config.servers.length, 0)
 }
 
-function statusLabel(config: LoadedInspection): string {
-  if (config.readError) {
-    return 'Unreadable'
-  }
-  if (config.status === 'missing') {
-    return 'Not found'
-  }
-  if (config.status === 'invalid') {
-    return 'Invalid JSON'
-  }
-  if (config.servers.length === 0) {
-    return 'No servers'
-  }
-  return `${config.servers.length} server${config.servers.length === 1 ? '' : 's'}`
-}
-
-function statusClassName(config: LoadedInspection): string {
-  if (config.readError || config.status === 'invalid') {
-    return 'border-destructive/30 bg-destructive/10 text-destructive'
-  }
-  if (config.status === 'valid' && config.servers.length > 0) {
-    return 'border-border/60 bg-background text-foreground'
-  }
-  return 'border-border/60 bg-muted/60 text-muted-foreground'
-}
-
-function serverDetailLabel(server: LoadedInspection['servers'][number]): string {
-  if (server.transport === 'http') {
-    return server.url ?? 'HTTP server'
-  }
-  if (server.transport === 'stdio') {
-    return server.command ?? 'stdio server'
-  }
-  return server.issue ?? 'Invalid server'
-}
-
 export function McpConfigSection({ repo }: McpConfigSectionProps): React.JSX.Element {
   const openFile = useAppStore((state) => state.openFile)
   const setActiveView = useAppStore((state) => state.setActiveView)
@@ -81,11 +42,18 @@ export function McpConfigSection({ repo }: McpConfigSectionProps): React.JSX.Ele
   const ensureWorktreeRootGroup = useAppStore((state) => state.ensureWorktreeRootGroup)
   const activeWorktreeId = useAppStore((state) => state.activeWorktreeId)
   const worktreesForRepo = useAppStore((state) => state.worktreesByRepo[repo.id] ?? EMPTY_WORKTREES)
-  const [configs, setConfigs] = useState<LoadedInspection[]>([])
+  const sshConnectionStatus = useAppStore((state) =>
+    repo.connectionId ? state.sshConnectionStates.get(repo.connectionId)?.status : null
+  )
+  const [configs, setConfigs] = useState<LoadedMcpConfigInspection[]>([])
   const [loading, setLoading] = useState(true)
   const [createConfirm, setCreateConfirm] = useState(false)
+  const [inspectionUnavailableMessage, setInspectionUnavailableMessage] = useState<string | null>(
+    null
+  )
 
   const connectionId = repo.connectionId ?? undefined
+  const isWindows = isWindowsUserAgent()
   const targetWorktree = useMemo(() => {
     if (activeWorktreeId && getRepoIdFromWorktreeId(activeWorktreeId) === repo.id) {
       return (
@@ -104,21 +72,15 @@ export function McpConfigSection({ repo }: McpConfigSectionProps): React.JSX.Ele
   const targetWorktreeId = targetWorktree.id
   const targetRootPath = targetWorktree.path
   const detectedCount = useMemo(() => configs.filter((config) => config.exists).length, [configs])
-  const remoteFilesystemUnavailable = useMemo(
-    () =>
-      Boolean(connectionId) &&
-      configs.length > 0 &&
-      configs.every((config) => isNoFilesystemProviderMessage(config.readError)),
-    [configs, connectionId]
-  )
+  const inspectionUnavailable = inspectionUnavailableMessage !== null
   const visibleConfigs = useMemo(
     () =>
-      remoteFilesystemUnavailable
+      inspectionUnavailable
         ? []
         : configs.filter(
             (config) => config.exists || config.status === 'invalid' || config.readError
           ),
-    [configs, remoteFilesystemUnavailable]
+    [configs, inspectionUnavailable]
   )
   const missingConfigs = useMemo(
     () =>
@@ -127,44 +89,133 @@ export function McpConfigSection({ repo }: McpConfigSectionProps): React.JSX.Ele
       ),
     [configs]
   )
+  const missingInspections = useMemo(
+    () =>
+      MCP_CONFIG_CANDIDATES.map(
+        (candidate): LoadedMcpConfigInspection => ({
+          ...inspectMcpConfigContent(candidate, null),
+          absolutePath: joinPath(targetRootPath, candidate.relativePath)
+        })
+      ),
+    [targetRootPath]
+  )
   const serverCount = useMemo(() => countServers(configs), [configs])
-  const canCreateStarter = detectedCount === 0 && !remoteFilesystemUnavailable
+  const canCreateStarter = detectedCount === 0 && !inspectionUnavailable
 
   const loadConfigs = useCallback(async (): Promise<void> => {
     setLoading(true)
-    const next = await Promise.all(
-      MCP_CONFIG_CANDIDATES.map(async (candidate): Promise<LoadedInspection> => {
-        const absolutePath = joinPath(targetRootPath, candidate.relativePath)
-        try {
-          const result = await window.api.fs.readFile({ filePath: absolutePath, connectionId })
-          const inspection = inspectMcpConfigContent(
-            candidate,
-            result.isBinary ? '' : result.content
+    setInspectionUnavailableMessage(null)
+
+    try {
+      if (connectionId && sshConnectionStatus !== 'connected') {
+        setConfigs(missingInspections)
+        setInspectionUnavailableMessage('Connect this SSH repo to inspect or add MCP configs.')
+        return
+      }
+
+      if (!connectionId && !canInspectLocalMcpConfigRoot(targetRootPath, isWindows)) {
+        setConfigs(missingInspections)
+        setInspectionUnavailableMessage('This workspace path is not available from this host.')
+        return
+      }
+
+      if (!connectionId && !(await window.api.shell.pathExists(targetRootPath))) {
+        setConfigs(missingInspections)
+        setInspectionUnavailableMessage('This workspace path is not available on disk.')
+        return
+      }
+
+      const entriesByRelativeDir = new Map<string, readonly McpConfigDirectoryEntry[]>()
+      const rootEntries = await window.api.fs.readDir({ dirPath: targetRootPath, connectionId })
+      entriesByRelativeDir.set('', rootEntries)
+
+      const rootDirectoryNames = new Set(
+        rootEntries.filter((entry) => entry.isDirectory).map((entry) => entry.name)
+      )
+      const unreadableParentDirMessages = new Map<string, string>()
+      await Promise.all(
+        getMcpConfigParentDirs().map(async (relativeDir) => {
+          if (!rootDirectoryNames.has(relativeDir)) {
+            return
+          }
+          try {
+            const entries = await window.api.fs.readDir({
+              dirPath: joinPath(targetRootPath, relativeDir),
+              connectionId
+            })
+            entriesByRelativeDir.set(relativeDir, entries)
+          } catch (error) {
+            unreadableParentDirMessages.set(
+              relativeDir,
+              extractIpcErrorMessage(error, `Unable to inspect ${relativeDir}.`)
+            )
+          }
+        })
+      )
+
+      const existingRelativePaths = new Set(
+        selectExistingMcpConfigCandidates(entriesByRelativeDir).map(
+          (candidate) => candidate.relativePath
+        )
+      )
+
+      const next = await Promise.all(
+        MCP_CONFIG_CANDIDATES.map(async (candidate): Promise<LoadedMcpConfigInspection> => {
+          const absolutePath = joinPath(targetRootPath, candidate.relativePath)
+          const parentDirReadError = unreadableParentDirMessages.get(
+            getMcpConfigCandidateParentDir(candidate)
           )
-          return { ...inspection, absolutePath }
-        } catch (error) {
-          if (isMissingFileError(error)) {
+          if (parentDirReadError) {
+            return {
+              ...inspectMcpConfigContent(candidate, null),
+              exists: false,
+              status: 'invalid',
+              absolutePath,
+              readError: parentDirReadError
+            }
+          }
+
+          if (!existingRelativePaths.has(candidate.relativePath)) {
             return { ...inspectMcpConfigContent(candidate, null), absolutePath }
           }
-          return {
-            ...inspectMcpConfigContent(candidate, null),
-            exists: false,
-            status: 'invalid',
-            absolutePath,
-            readError: extractIpcErrorMessage(error, 'Unable to read config file.')
+
+          try {
+            const result = await window.api.fs.readFile({ filePath: absolutePath, connectionId })
+            const inspection = inspectMcpConfigContent(
+              candidate,
+              result.isBinary ? '' : result.content
+            )
+            return { ...inspection, absolutePath }
+          } catch (error) {
+            if (isMissingFileError(error)) {
+              return { ...inspectMcpConfigContent(candidate, null), absolutePath }
+            }
+            return {
+              ...inspectMcpConfigContent(candidate, null),
+              exists: false,
+              status: 'invalid',
+              absolutePath,
+              readError: extractIpcErrorMessage(error, 'Unable to read config file.')
+            }
           }
-        }
-      })
-    )
-    setConfigs(next)
-    setLoading(false)
-  }, [connectionId, targetRootPath])
+        })
+      )
+      setConfigs(next)
+    } catch (error) {
+      setConfigs(missingInspections)
+      setInspectionUnavailableMessage(
+        extractIpcErrorMessage(error, 'Unable to inspect MCP configs.')
+      )
+    } finally {
+      setLoading(false)
+    }
+  }, [connectionId, isWindows, missingInspections, sshConnectionStatus, targetRootPath])
 
   useEffect(() => {
     void loadConfigs()
   }, [loadConfigs])
 
-  const handleOpen = (config: LoadedInspection): void => {
+  const handleOpen = (config: LoadedMcpConfigInspection): void => {
     setActiveWorktree(targetWorktreeId)
     const targetGroupId = ensureWorktreeRootGroup(targetWorktreeId)
     openFile(
@@ -265,13 +316,13 @@ export function McpConfigSection({ repo }: McpConfigSectionProps): React.JSX.Ele
         <div>
           {visibleConfigs.length === 0 ? (
             <div className="flex items-start gap-2 px-3 py-2.5 text-xs text-muted-foreground">
-              {remoteFilesystemUnavailable ? (
+              {inspectionUnavailable ? (
                 <AlertCircle className="mt-0.5 size-3.5 shrink-0" />
               ) : (
                 <FileCode2 className="mt-0.5 size-3.5 shrink-0" />
               )}
-              {remoteFilesystemUnavailable ? (
-                <span>Connect this SSH repo to inspect or add MCP configs.</span>
+              {inspectionUnavailable ? (
+                <span>{inspectionUnavailableMessage}</span>
               ) : (
                 <span>
                   No MCP config found. Add an empty workspace config when you want this repo to
@@ -282,78 +333,16 @@ export function McpConfigSection({ repo }: McpConfigSectionProps): React.JSX.Ele
           ) : (
             <div className="divide-y divide-border/50">
               {visibleConfigs.map((config) => (
-                <div key={config.candidate.relativePath} className="space-y-2 px-3 py-2.5">
-                  <div className="flex items-center gap-2">
-                    {config.status === 'valid' && !config.readError ? (
-                      <CheckCircle2 className="size-3.5 shrink-0 text-muted-foreground" />
-                    ) : (
-                      <AlertCircle className="size-3.5 shrink-0 text-destructive" />
-                    )}
-                    <div className="min-w-0 flex-1">
-                      <div className="flex min-w-0 items-center gap-2">
-                        <p className="truncate text-sm font-medium">{config.candidate.label}</p>
-                        <p className="truncate font-mono text-[11px] text-muted-foreground">
-                          {config.candidate.relativePath}
-                        </p>
-                      </div>
-                    </div>
-                    <span
-                      className={`shrink-0 rounded-full border px-1.5 py-0.5 text-[10px] font-medium ${statusClassName(config)}`}
-                    >
-                      {statusLabel(config)}
-                    </span>
-                    {config.exists ? (
-                      <Button variant="outline" size="xs" onClick={() => handleOpen(config)}>
-                        Open
-                      </Button>
-                    ) : null}
-                  </div>
-
-                  {config.error || config.readError ? (
-                    <p className="pl-5 text-xs text-destructive">
-                      {config.readError ?? config.error}
-                    </p>
-                  ) : null}
-
-                  {config.servers.length > 0 ? (
-                    <div className="grid gap-1.5 pl-5">
-                      {config.servers.map((server) => (
-                        <div
-                          key={server.name}
-                          className="grid grid-cols-[minmax(0,1fr)_auto] gap-2 rounded-md border border-border/40 bg-background/50 px-2.5 py-1.5"
-                        >
-                          <div className="min-w-0">
-                            <div className="flex items-center gap-1.5">
-                              <span className="truncate text-xs font-medium">{server.name}</span>
-                              <span className="rounded-full bg-muted px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-wider text-muted-foreground">
-                                {server.transport}
-                              </span>
-                            </div>
-                            <p className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
-                              {serverDetailLabel(server)}
-                            </p>
-                            {server.env && Object.keys(server.env).length > 0 ? (
-                              <p className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">
-                                env:{' '}
-                                {Object.entries(server.env)
-                                  .map(([key, value]) => `${key}=${value}`)
-                                  .join(', ')}
-                              </p>
-                            ) : null}
-                          </div>
-                          <span className="self-start text-[11px] text-muted-foreground">
-                            {server.status}
-                          </span>
-                        </div>
-                      ))}
-                    </div>
-                  ) : null}
-                </div>
+                <McpConfigFileRow
+                  key={config.candidate.relativePath}
+                  config={config}
+                  onOpen={handleOpen}
+                />
               ))}
             </div>
           )}
 
-          {missingConfigs.length > 0 && !remoteFilesystemUnavailable ? (
+          {missingConfigs.length > 0 && !inspectionUnavailable ? (
             <div className="space-y-1.5 border-t border-border/50 px-3 py-2">
               <p className="text-[11px] text-muted-foreground">Checked</p>
               <div className="flex flex-wrap gap-1.5">
diff --git a/src/shared/mcp-config.test.ts b/src/shared/mcp-config.test.ts
index f12ba2df21b..a9f2b5412f3 100644
--- a/src/shared/mcp-config.test.ts
+++ b/src/shared/mcp-config.test.ts
@@ -1,9 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import {
+  canInspectLocalMcpConfigRoot,
+  getMcpConfigCandidateParentDir,
+  getMcpConfigParentDirs,
   inspectMcpConfigContent,
   maskMcpEnv,
   MCP_CONFIG_CANDIDATES,
-  MCP_STARTER_CONFIG
+  MCP_STARTER_CONFIG,
+  selectExistingMcpConfigCandidates
 } from './mcp-config'
 
 describe('mcp-config', () => {
@@ -109,4 +113,40 @@ describe('mcp-config', () => {
       servers: []
     })
   })
+
+  it('plans directory discovery before reading candidate files', () => {
+    expect(getMcpConfigParentDirs()).toEqual(['.cursor', '.claude'])
+    expect(
+      MCP_CONFIG_CANDIDATES.map((candidate) => getMcpConfigCandidateParentDir(candidate))
+    ).toEqual(['', '.cursor', '', '.claude'])
+
+    const entriesByRelativeDir = new Map([
+      [
+        '',
+        [
+          { name: '.mcp.json', isDirectory: false },
+          { name: '.cursor', isDirectory: true },
+          { name: '.claude', isDirectory: false }
+        ]
+      ],
+      ['.cursor', [{ name: 'mcp.json', isDirectory: false }]]
+    ])
+
+    expect(
+      selectExistingMcpConfigCandidates(entriesByRelativeDir).map((entry) => entry.label)
+    ).toEqual(['Workspace', 'Cursor'])
+  })
+
+  it('rejects Windows-only local roots on non-Windows hosts', () => {
+    expect(canInspectLocalMcpConfigRoot('C:\\repo', false)).toBe(false)
+    expect(canInspectLocalMcpConfigRoot('\\\\wsl.localhost\\Ubuntu\\home\\me\\repo', false)).toBe(
+      false
+    )
+    expect(canInspectLocalMcpConfigRoot('//wsl.localhost/Ubuntu/home/me/repo', false)).toBe(false)
+    expect(canInspectLocalMcpConfigRoot('/Users/me/repo', false)).toBe(true)
+    expect(canInspectLocalMcpConfigRoot('\\\\wsl.localhost\\Ubuntu\\home\\me\\repo', true)).toBe(
+      true
+    )
+    expect(canInspectLocalMcpConfigRoot('//wsl.localhost/Ubuntu/home/me/repo', true)).toBe(true)
+  })
 })
diff --git a/src/shared/mcp-config.ts b/src/shared/mcp-config.ts
index 5a81ac2b267..11ef0e66966 100644
--- a/src/shared/mcp-config.ts
+++ b/src/shared/mcp-config.ts
@@ -7,6 +7,11 @@ export type McpConfigCandidate = {
   serversPath: string[]
 }
 
+export type McpConfigDirectoryEntry = {
+  name: string
+  isDirectory: boolean
+}
+
 export type McpServerTransport = 'stdio' | 'http' | 'unknown'
 export type McpServerStatus = 'enabled' | 'disabled' | 'invalid'
 
@@ -60,6 +65,41 @@ export const MCP_STARTER_CONFIG = `{
 }
 `
 
+export function getMcpConfigParentDirs(
+  candidates: readonly McpConfigCandidate[] = MCP_CONFIG_CANDIDATES
+): string[] {
+  return Array.from(
+    new Set(
+      candidates
+        .map((candidate) => getRelativeParentDir(candidate.relativePath))
+        .filter((parentDir) => parentDir !== '')
+    )
+  )
+}
+
+export function getMcpConfigCandidateParentDir(candidate: McpConfigCandidate): string {
+  return getRelativeParentDir(candidate.relativePath)
+}
+
+export function selectExistingMcpConfigCandidates(
+  entriesByRelativeDir: ReadonlyMap<string, readonly McpConfigDirectoryEntry[]>,
+  candidates: readonly McpConfigCandidate[] = MCP_CONFIG_CANDIDATES
+): McpConfigCandidate[] {
+  return candidates.filter((candidate) => {
+    const parentDir = getRelativeParentDir(candidate.relativePath)
+    const basename = getRelativeBasename(candidate.relativePath)
+    const entries = entriesByRelativeDir.get(parentDir) ?? []
+    return entries.some((entry) => entry.name === basename && !entry.isDirectory)
+  })
+}
+
+export function canInspectLocalMcpConfigRoot(rootPath: string, isWindowsHost: boolean): boolean {
+  if (isWindowsHost) {
+    return true
+  }
+  return !/^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+)/.test(rootPath)
+}
+
 const SENSITIVE_ENV_KEY_PATTERN =
   /(api[_-]?key|auth|bearer|cookie|credential|password|private[_-]?key|secret|session|token)/i
 const SENSITIVE_ENV_VALUE_PATTERN =
@@ -115,6 +155,18 @@ export function maskMcpEnv(env: unknown): Record<string, string> | undefined {
   return masked
 }
 
+function getRelativeParentDir(relativePath: string): string {
+  const normalizedPath = relativePath.replace(/\\/g, '/')
+  const separatorIndex = normalizedPath.lastIndexOf('/')
+  return separatorIndex === -1 ? '' : normalizedPath.slice(0, separatorIndex)
+}
+
+function getRelativeBasename(relativePath: string): string {
+  const normalizedPath = relativePath.replace(/\\/g, '/')
+  const separatorIndex = normalizedPath.lastIndexOf('/')
+  return separatorIndex === -1 ? normalizedPath : normalizedPath.slice(separatorIndex + 1)
+}
+
 function extractObjectAtPath(
   value: unknown,
   pathSegments: string[]

From 7c384a36e3fd08c3c9469db256a263be817feaf4 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 11:29:33 -0700
Subject: [PATCH 41/82] Make floating terminal trigger more obvious (#1943)

---
 .../FloatingTerminalPanel.tsx                 |  51 +------
 .../FloatingTerminalToggleButton.tsx          |   2 +-
 .../FloatingTerminalWindowControls.tsx        | 144 ++++++++++++++++++
 .../src/components/status-bar/StatusBar.tsx   |   2 +-
 4 files changed, 153 insertions(+), 46 deletions(-)
 create mode 100644 src/renderer/src/components/floating-terminal/FloatingTerminalWindowControls.tsx

diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
index fa472c63ed4..94c89362086 100644
--- a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
@@ -1,10 +1,8 @@
 /* eslint-disable max-lines -- Why: the floating surface owns both terminal chrome and local notes tabs until the shared floating shell is extracted. */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Maximize2, Minimize2, Minus } from 'lucide-react'
 import TabBar from '@/components/tab-bar/TabBar'
 import TerminalPane from '@/components/terminal-pane/TerminalPane'
 import { Button } from '@/components/ui/button'
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
 import {
   ORCHESTRATION_SETUP_DISMISSED_STORAGE_KEY,
@@ -23,6 +21,7 @@ import type { TerminalTab } from '../../../../shared/types'
 import { FloatingTerminalOrchestrationDialog } from './FloatingTerminalOrchestrationDialog'
 import ProjectNotesTabContent from '@/components/notes/ProjectNotesTabContent'
 import { FloatingTerminalResizeHandles } from './FloatingTerminalResizeHandles'
+import { FloatingTerminalWindowControls } from './FloatingTerminalWindowControls'
 export { FloatingTerminalToggleButton } from './FloatingTerminalToggleButton'
 import {
   clampFloatingTerminalBounds,
@@ -361,7 +360,7 @@ export function FloatingTerminalPanel({
     >
       <div className="flex min-h-0 flex-1 flex-col">
         <div
-          className="flex h-9 shrink-0 items-center border-b border-border bg-[var(--bg-titlebar,var(--card))]"
+          className="flex h-9 shrink-0 cursor-grab items-center border-b border-border bg-[var(--bg-titlebar,var(--card))] active:cursor-grabbing"
           onPointerDown={handleDragStart}
           onPointerMove={handleDragMove}
           onPointerUp={handleDragEnd}
@@ -401,47 +400,11 @@ export function FloatingTerminalPanel({
               tabBarOrder={tabBarOrder}
             />
           </div>
-          <div className="flex items-center gap-1 px-2" data-floating-terminal-no-drag>
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <Button
-                  type="button"
-                  variant="ghost"
-                  size="icon-xs"
-                  aria-label={
-                    maximized ? 'Restore floating terminal' : 'Maximize floating terminal'
-                  }
-                  aria-pressed={maximized}
-                  onClick={toggleMaximized}
-                >
-                  {maximized ? (
-                    <Minimize2 className="size-3.5" />
-                  ) : (
-                    <Maximize2 className="size-3.5" />
-                  )}
-                </Button>
-              </TooltipTrigger>
-              <TooltipContent side="bottom" sideOffset={6}>
-                {maximized ? 'Restore' : 'Maximize'}
-              </TooltipContent>
-            </Tooltip>
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <Button
-                  type="button"
-                  variant="ghost"
-                  size="icon-xs"
-                  aria-label="Minimize floating terminal"
-                  onClick={() => onOpenChange(false)}
-                >
-                  <Minus className="size-3.5" />
-                </Button>
-              </TooltipTrigger>
-              <TooltipContent side="bottom" sideOffset={6}>
-                Minimize
-              </TooltipContent>
-            </Tooltip>
-          </div>
+          <FloatingTerminalWindowControls
+            maximized={maximized}
+            onToggleMaximized={toggleMaximized}
+            onMinimize={() => onOpenChange(false)}
+          />
         </div>
 
         <div className="relative min-h-0 flex-1 overflow-hidden bg-background">
diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalToggleButton.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalToggleButton.tsx
index 314f00efb6e..986f1612669 100644
--- a/src/renderer/src/components/floating-terminal/FloatingTerminalToggleButton.tsx
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalToggleButton.tsx
@@ -23,7 +23,7 @@ export function FloatingTerminalToggleButton({
             type="button"
             variant="outline"
             size="icon-sm"
-            className="bg-card/95 shadow-xs"
+            className="border-border bg-secondary text-secondary-foreground shadow-xs hover:bg-accent hover:text-accent-foreground"
             data-floating-terminal-toggle
             aria-label={open ? 'Minimize floating terminal' : 'Show floating terminal'}
             aria-pressed={open}
diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalWindowControls.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalWindowControls.tsx
new file mode 100644
index 00000000000..f09949cb510
--- /dev/null
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalWindowControls.tsx
@@ -0,0 +1,144 @@
+import { useCallback, useMemo } from 'react'
+import { Maximize2, Minimize2, Minus } from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { AGENT_CATALOG, AgentIcon } from '@/lib/agent-catalog'
+import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
+import { CLIENT_PLATFORM } from '@/lib/new-workspace'
+import { buildAgentStartupPlan } from '@/lib/tui-agent-startup'
+import { tuiAgentToAgentKind } from '@/lib/telemetry'
+import { useAppStore } from '@/store'
+import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../../shared/constants'
+
+type FloatingTerminalWindowControlsProps = {
+  maximized: boolean
+  onToggleMaximized: () => void
+  onMinimize: () => void
+}
+
+const controlButtonClassName =
+  'border-border bg-secondary text-secondary-foreground shadow-xs hover:bg-accent hover:text-accent-foreground'
+
+export function FloatingTerminalWindowControls({
+  maximized,
+  onToggleMaximized,
+  onMinimize
+}: FloatingTerminalWindowControlsProps): React.JSX.Element {
+  const defaultTuiAgent = useAppStore((s) => s.settings?.defaultTuiAgent ?? null)
+  const createTab = useAppStore((s) => s.createTab)
+  const setActiveTabForWorktree = useAppStore((s) => s.setActiveTabForWorktree)
+
+  const defaultAgent = defaultTuiAgent && defaultTuiAgent !== 'blank' ? defaultTuiAgent : null
+  const defaultAgentLabel = useMemo(
+    () =>
+      defaultAgent
+        ? (AGENT_CATALOG.find((agent) => agent.id === defaultAgent)?.label ?? defaultAgent)
+        : null,
+    [defaultAgent]
+  )
+
+  const launchDefaultAgent = useCallback(() => {
+    if (!defaultAgent) {
+      return
+    }
+    const state = useAppStore.getState()
+    const startupPlan = buildAgentStartupPlan({
+      agent: defaultAgent,
+      prompt: '',
+      cmdOverrides: state.settings?.agentCmdOverrides ?? {},
+      platform: CLIENT_PLATFORM,
+      allowEmptyPromptLaunch: true
+    })
+    if (!startupPlan) {
+      toast.error(`Could not build launch command for ${defaultAgentLabel ?? defaultAgent}.`)
+      return
+    }
+    const tab = createTab(FLOATING_TERMINAL_WORKTREE_ID, undefined, undefined, { activate: false })
+    state.queueTabStartupCommand(tab.id, {
+      command: startupPlan.launchCommand,
+      ...(startupPlan.env ? { env: startupPlan.env } : {}),
+      telemetry: {
+        agent_kind: tuiAgentToAgentKind(defaultAgent),
+        launch_source: 'shortcut',
+        request_kind: 'new'
+      }
+    })
+    setActiveTabForWorktree(FLOATING_TERMINAL_WORKTREE_ID, tab.id)
+    const fresh = useAppStore.getState()
+    const currentTabs = fresh.tabsByWorktree[FLOATING_TERMINAL_WORKTREE_ID] ?? []
+    const stored = fresh.tabBarOrderByWorktree[FLOATING_TERMINAL_WORKTREE_ID] ?? []
+    const validIds = new Set(currentTabs.map((entry) => entry.id))
+    const order = stored.filter((id) => validIds.has(id) && id !== tab.id)
+    for (const entry of currentTabs) {
+      if (entry.id !== tab.id && !order.includes(entry.id)) {
+        order.push(entry.id)
+      }
+    }
+    order.push(tab.id)
+    fresh.setTabBarOrder(FLOATING_TERMINAL_WORKTREE_ID, order)
+    focusTerminalTabSurface(tab.id)
+  }, [createTab, defaultAgent, defaultAgentLabel, setActiveTabForWorktree])
+
+  return (
+    <div className="flex items-center gap-1 px-2" data-floating-terminal-no-drag>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button
+            type="button"
+            variant="outline"
+            size="icon-xs"
+            className={controlButtonClassName}
+            aria-label={
+              defaultAgentLabel
+                ? `Open ${defaultAgentLabel} in floating terminal`
+                : 'No default agent configured'
+            }
+            disabled={!defaultAgent}
+            onClick={launchDefaultAgent}
+          >
+            <AgentIcon agent={defaultAgent} size={14} />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" sideOffset={6}>
+          {defaultAgentLabel ? `Open ${defaultAgentLabel}` : 'Choose a default agent first'}
+        </TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button
+            type="button"
+            variant="outline"
+            size="icon-xs"
+            className={controlButtonClassName}
+            aria-label={maximized ? 'Restore floating terminal' : 'Maximize floating terminal'}
+            aria-pressed={maximized}
+            onClick={onToggleMaximized}
+          >
+            {maximized ? <Minimize2 className="size-3.5" /> : <Maximize2 className="size-3.5" />}
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" sideOffset={6}>
+          {maximized ? 'Restore' : 'Maximize'}
+        </TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button
+            type="button"
+            variant="outline"
+            size="icon-xs"
+            className={controlButtonClassName}
+            aria-label="Minimize floating terminal"
+            onClick={onMinimize}
+          >
+            <Minus className="size-3.5" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" sideOffset={6}>
+          Minimize
+        </TooltipContent>
+      </Tooltip>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/status-bar/StatusBar.tsx b/src/renderer/src/components/status-bar/StatusBar.tsx
index e5b935f5e02..418292e0e93 100644
--- a/src/renderer/src/components/status-bar/StatusBar.tsx
+++ b/src/renderer/src/components/status-bar/StatusBar.tsx
@@ -908,7 +908,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
               <TooltipTrigger asChild>
                 <button
                   type="button"
-                  className="inline-flex size-5 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+                  className="inline-flex size-5 cursor-pointer items-center justify-center rounded border border-border bg-secondary text-secondary-foreground shadow-xs transition-colors hover:bg-accent hover:text-accent-foreground"
                   aria-label={floatingTerminalActionLabel}
                   onClick={() => {
                     window.dispatchEvent(new CustomEvent(TOGGLE_FLOATING_TERMINAL_EVENT))

From 96f0c683ebe04d56a43cbecda0a5cfdd4ec71243 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 11:32:46 -0700
Subject: [PATCH 42/82] Support multiple Linear workspaces (#1917)

---
 src/main/ipc/linear.ts                        | 145 +++--
 src/main/linear/client.test.ts                | 170 +++++
 src/main/linear/client.ts                     | 610 ++++++++++++++----
 src/main/linear/issues.ts                     | 294 ++++++---
 src/main/linear/teams.ts                      | 101 +--
 src/main/runtime/orca-runtime.ts              |  78 ++-
 src/main/runtime/rpc/methods/linear.test.ts   |  92 ++-
 src/main/runtime/rpc/methods/linear.ts        |  79 ++-
 src/preload/api-types.ts                      |  32 +-
 src/preload/index.ts                          |  36 +-
 .../src/components/LinearItemDrawer.tsx       |  59 +-
 src/renderer/src/components/TaskPage.tsx      | 158 +++--
 .../components/settings/IntegrationsPane.tsx  | 151 +++--
 src/renderer/src/hooks/useIssueMetadata.ts    |  37 +-
 .../src/runtime/runtime-linear-client.test.ts |  46 +-
 .../src/runtime/runtime-linear-client.ts      | 141 ++--
 src/renderer/src/store/slices/linear.ts       | 107 ++-
 src/shared/types.ts                           |  17 +
 18 files changed, 1735 insertions(+), 618 deletions(-)
 create mode 100644 src/main/linear/client.test.ts

diff --git a/src/main/ipc/linear.ts b/src/main/ipc/linear.ts
index d1a4c659393..96de78c74d5 100644
--- a/src/main/ipc/linear.ts
+++ b/src/main/ipc/linear.ts
@@ -1,5 +1,5 @@
 import { ipcMain } from 'electron'
-import { connect, disconnect, getStatus, testConnection } from '../linear/client'
+import { connect, disconnect, getStatus, selectWorkspace, testConnection } from '../linear/client'
 import { _resetPreflightCache } from './preflight'
 import {
   getIssue,
@@ -12,10 +12,19 @@ import {
 } from '../linear/issues'
 import { listTeams, getTeamStates, getTeamLabels, getTeamMembers } from '../linear/teams'
 import type { LinearListFilter } from '../linear/issues'
-import type { LinearIssueUpdate } from '../../shared/types'
+import type { LinearIssueUpdate, LinearWorkspaceSelection } from '../../shared/types'
 
 const VALID_FILTERS = new Set<LinearListFilter>(['assigned', 'created', 'all', 'completed'])
 
+function normalizeWorkspaceId(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function normalizeWorkspaceSelection(value: unknown): LinearWorkspaceSelection | undefined {
+  const workspaceId = normalizeWorkspaceId(value)
+  return workspaceId as LinearWorkspaceSelection | undefined
+}
+
 export function registerLinearHandlers(): void {
   ipcMain.handle('linear:connect', async (_event, args: { apiKey: string }) => {
     if (typeof args?.apiKey !== 'string' || !args.apiKey.trim()) {
@@ -28,41 +37,61 @@ export function registerLinearHandlers(): void {
     return result
   })
 
-  ipcMain.handle('linear:disconnect', async () => {
-    disconnect()
+  ipcMain.handle('linear:disconnect', async (_event, args?: { workspaceId?: string }) => {
+    disconnect(normalizeWorkspaceId(args?.workspaceId))
     _resetPreflightCache()
   })
 
+  ipcMain.handle('linear:selectWorkspace', async (_event, args: { workspaceId: string }) => {
+    const workspaceId = normalizeWorkspaceSelection(args?.workspaceId)
+    if (!workspaceId) {
+      return getStatus()
+    }
+    return selectWorkspace(workspaceId)
+  })
+
   ipcMain.handle('linear:status', async () => {
     return getStatus()
   })
 
-  ipcMain.handle('linear:testConnection', async () => {
-    return testConnection()
-  })
-
-  ipcMain.handle('linear:searchIssues', async (_event, args: { query: string; limit?: number }) => {
-    if (typeof args?.query !== 'string') {
-      return []
-    }
-    const limit = Math.min(Math.max(1, args.limit ?? 20), 50)
-    return searchIssues(args.query, limit)
+  ipcMain.handle('linear:testConnection', async (_event, args?: { workspaceId?: string }) => {
+    return testConnection(normalizeWorkspaceId(args?.workspaceId))
   })
 
+  ipcMain.handle(
+    'linear:searchIssues',
+    async (
+      _event,
+      args: { query: string; limit?: number; workspaceId?: LinearWorkspaceSelection }
+    ) => {
+      if (typeof args?.query !== 'string') {
+        return []
+      }
+      const limit = Math.min(Math.max(1, args.limit ?? 20), 50)
+      return searchIssues(args.query, limit, normalizeWorkspaceSelection(args.workspaceId))
+    }
+  )
+
   ipcMain.handle(
     'linear:listIssues',
-    async (_event, args?: { filter?: LinearListFilter; limit?: number }) => {
+    async (
+      _event,
+      args?: { filter?: LinearListFilter; limit?: number; workspaceId?: LinearWorkspaceSelection }
+    ) => {
       const filter = VALID_FILTERS.has(args?.filter as LinearListFilter)
         ? (args!.filter as LinearListFilter)
         : undefined
       const limit = Math.min(Math.max(1, args?.limit ?? 20), 50)
-      return listIssues(filter, limit)
+      return listIssues(filter, limit, normalizeWorkspaceSelection(args?.workspaceId))
     }
   )
 
   ipcMain.handle(
     'linear:createIssue',
-    async (_event, args: { teamId: string; title: string; description?: string }) => {
+    async (
+      _event,
+      args: { teamId: string; title: string; description?: string; workspaceId?: string }
+    ) => {
       if (typeof args?.teamId !== 'string' || !args.teamId.trim()) {
         return { ok: false, error: 'Team ID is required' }
       }
@@ -72,21 +101,22 @@ export function registerLinearHandlers(): void {
       return createIssue(
         args.teamId.trim(),
         args.title.trim(),
-        args.description?.trim() || undefined
+        args.description?.trim() || undefined,
+        normalizeWorkspaceId(args.workspaceId)
       )
     }
   )
 
-  ipcMain.handle('linear:getIssue', async (_event, args: { id: string }) => {
+  ipcMain.handle('linear:getIssue', async (_event, args: { id: string; workspaceId?: string }) => {
     if (typeof args?.id !== 'string' || !args.id.trim()) {
       return null
     }
-    return getIssue(args.id.trim())
+    return getIssue(args.id.trim(), normalizeWorkspaceId(args.workspaceId))
   })
 
   ipcMain.handle(
     'linear:updateIssue',
-    async (_event, args: { id: string; updates: LinearIssueUpdate }) => {
+    async (_event, args: { id: string; updates: LinearIssueUpdate; workspaceId?: string }) => {
       if (typeof args?.id !== 'string' || !args.id.trim()) {
         return { ok: false, error: 'Issue ID is required' }
       }
@@ -112,52 +142,71 @@ export function registerLinearHandlers(): void {
       ) {
         return { ok: false, error: 'Label IDs must be an array of strings' }
       }
-      return updateIssue(args.id.trim(), args.updates)
+      return updateIssue(args.id.trim(), args.updates, normalizeWorkspaceId(args.workspaceId))
     }
   )
 
   ipcMain.handle(
     'linear:addIssueComment',
-    async (_event, args: { issueId: string; body: string }) => {
+    async (_event, args: { issueId: string; body: string; workspaceId?: string }) => {
       if (typeof args?.issueId !== 'string' || !args.issueId.trim()) {
         return { ok: false, error: 'Issue ID is required' }
       }
       if (!args.body?.trim()) {
         return { ok: false, error: 'Comment body is required' }
       }
-      return addIssueComment(args.issueId.trim(), args.body.trim())
+      return addIssueComment(
+        args.issueId.trim(),
+        args.body.trim(),
+        normalizeWorkspaceId(args.workspaceId)
+      )
     }
   )
 
-  ipcMain.handle('linear:issueComments', async (_event, args: { issueId: string }) => {
-    if (typeof args?.issueId !== 'string' || !args.issueId.trim()) {
-      return []
+  ipcMain.handle(
+    'linear:issueComments',
+    async (_event, args: { issueId: string; workspaceId?: string }) => {
+      if (typeof args?.issueId !== 'string' || !args.issueId.trim()) {
+        return []
+      }
+      return getIssueComments(args.issueId.trim(), normalizeWorkspaceId(args.workspaceId))
     }
-    return getIssueComments(args.issueId.trim())
-  })
+  )
 
-  ipcMain.handle('linear:listTeams', async () => {
-    return listTeams()
-  })
-
-  ipcMain.handle('linear:teamStates', async (_event, args: { teamId: string }) => {
-    if (typeof args?.teamId !== 'string' || !args.teamId.trim()) {
-      return []
+  ipcMain.handle(
+    'linear:listTeams',
+    async (_event, args?: { workspaceId?: LinearWorkspaceSelection }) => {
+      return listTeams(normalizeWorkspaceSelection(args?.workspaceId))
     }
-    return getTeamStates(args.teamId.trim())
-  })
+  )
 
-  ipcMain.handle('linear:teamLabels', async (_event, args: { teamId: string }) => {
-    if (typeof args?.teamId !== 'string' || !args.teamId.trim()) {
-      return []
+  ipcMain.handle(
+    'linear:teamStates',
+    async (_event, args: { teamId: string; workspaceId?: string }) => {
+      if (typeof args?.teamId !== 'string' || !args.teamId.trim()) {
+        return []
+      }
+      return getTeamStates(args.teamId.trim(), normalizeWorkspaceId(args.workspaceId))
     }
-    return getTeamLabels(args.teamId.trim())
-  })
+  )
 
-  ipcMain.handle('linear:teamMembers', async (_event, args: { teamId: string }) => {
-    if (typeof args?.teamId !== 'string' || !args.teamId.trim()) {
-      return []
+  ipcMain.handle(
+    'linear:teamLabels',
+    async (_event, args: { teamId: string; workspaceId?: string }) => {
+      if (typeof args?.teamId !== 'string' || !args.teamId.trim()) {
+        return []
+      }
+      return getTeamLabels(args.teamId.trim(), normalizeWorkspaceId(args.workspaceId))
     }
-    return getTeamMembers(args.teamId.trim())
-  })
+  )
+
+  ipcMain.handle(
+    'linear:teamMembers',
+    async (_event, args: { teamId: string; workspaceId?: string }) => {
+      if (typeof args?.teamId !== 'string' || !args.teamId.trim()) {
+        return []
+      }
+      return getTeamMembers(args.teamId.trim(), normalizeWorkspaceId(args.workspaceId))
+    }
+  )
 }
diff --git a/src/main/linear/client.test.ts b/src/main/linear/client.test.ts
new file mode 100644
index 00000000000..30c049b3c80
--- /dev/null
+++ b/src/main/linear/client.test.ts
@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import type * as Os from 'os'
+import { join } from 'path'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+type ViewerFixture = {
+  displayName: string
+  email: string | null
+  organizationId: string
+  organizationName: string
+  organizationUrlKey: string
+}
+
+let tempHome = ''
+let fixtures = new Map<string, ViewerFixture>()
+let linearClientMock: ReturnType<typeof vi.fn>
+
+function writeLegacyLinearFiles(token: string, viewer: Record<string, unknown>): void {
+  const orcaDir = join(tempHome, '.orca')
+  mkdirSync(orcaDir, { recursive: true })
+  writeFileSync(join(orcaDir, 'linear-token.enc'), token, { encoding: 'utf-8' })
+  writeFileSync(join(orcaDir, 'linear-viewer.json'), JSON.stringify(viewer), {
+    encoding: 'utf-8'
+  })
+}
+
+async function loadClientModule() {
+  vi.resetModules()
+  linearClientMock = vi.fn(function LinearClient(
+    this: { viewer: Promise<unknown> },
+    { apiKey }: { apiKey: string }
+  ) {
+    const fixture = fixtures.get(apiKey)
+    if (!fixture) {
+      throw new Error('Invalid API key')
+    }
+    this.viewer = Promise.resolve({
+      displayName: fixture.displayName,
+      email: fixture.email,
+      organization: Promise.resolve({
+        id: fixture.organizationId,
+        name: fixture.organizationName,
+        urlKey: fixture.organizationUrlKey
+      })
+    })
+  })
+  vi.doMock('electron', () => ({
+    safeStorage: {
+      isEncryptionAvailable: () => false,
+      encryptString: (value: string) => Buffer.from(value),
+      decryptString: (value: Buffer) => value.toString('utf-8')
+    }
+  }))
+  vi.doMock('os', async () => {
+    const actual = await vi.importActual<typeof Os>('os')
+    return { ...actual, homedir: () => tempHome }
+  })
+  vi.doMock('@linear/sdk', () => ({
+    AuthenticationLinearError: class AuthenticationLinearError extends Error {},
+    LinearClient: linearClientMock
+  }))
+
+  return import('./client')
+}
+
+beforeEach(() => {
+  tempHome = mkdtempLike('orca-linear-client-')
+  fixtures = new Map([
+    [
+      'token-alpha',
+      {
+        displayName: 'Ada',
+        email: 'ada@example.com',
+        organizationId: 'org-alpha',
+        organizationName: 'Alpha',
+        organizationUrlKey: 'alpha'
+      }
+    ],
+    [
+      'token-beta',
+      {
+        displayName: 'Grace',
+        email: 'grace@example.com',
+        organizationId: 'org-beta',
+        organizationName: 'Beta',
+        organizationUrlKey: 'beta'
+      }
+    ]
+  ])
+  vi.restoreAllMocks()
+})
+
+function mkdtempLike(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), prefix))
+}
+
+describe('Linear client workspace storage', () => {
+  it('stores multiple workspaces and remembers the selected workspace', async () => {
+    const linear = await loadClientModule()
+
+    await expect(linear.connect('token-alpha')).resolves.toMatchObject({
+      ok: true,
+      workspace: { id: 'org-alpha', organizationName: 'Alpha' }
+    })
+    await expect(linear.connect('token-beta')).resolves.toMatchObject({
+      ok: true,
+      workspace: { id: 'org-beta', organizationName: 'Beta' }
+    })
+
+    expect(linear.getStatus()).toMatchObject({
+      connected: true,
+      selectedWorkspaceId: 'org-beta',
+      workspaces: [
+        { id: 'org-alpha', organizationName: 'Alpha' },
+        { id: 'org-beta', organizationName: 'Beta' }
+      ]
+    })
+
+    expect(linear.selectWorkspace('all')).toMatchObject({ selectedWorkspaceId: 'all' })
+
+    linear.disconnect('org-alpha')
+    expect(linear.getStatus()).toMatchObject({
+      connected: true,
+      workspaces: [{ id: 'org-beta', organizationName: 'Beta' }]
+    })
+  })
+
+  it('reports a legacy single-token workspace without constructing a Linear client', async () => {
+    writeLegacyLinearFiles('token-alpha', {
+      displayName: 'Ada',
+      email: 'ada@example.com',
+      organizationName: 'Alpha'
+    })
+    const linear = await loadClientModule()
+
+    expect(linear.getStatus()).toMatchObject({
+      connected: true,
+      selectedWorkspaceId: 'legacy',
+      workspaces: [{ id: 'legacy', organizationName: 'Alpha', isLegacy: true }]
+    })
+    expect(linearClientMock).not.toHaveBeenCalled()
+  })
+
+  it('migrates legacy token storage to a real workspace id when explicitly tested', async () => {
+    writeLegacyLinearFiles('token-alpha', {
+      displayName: 'Ada',
+      email: 'ada@example.com',
+      organizationName: 'Alpha'
+    })
+    const linear = await loadClientModule()
+
+    await expect(linear.testConnection('legacy')).resolves.toMatchObject({
+      ok: true,
+      workspace: { id: 'org-alpha', organizationName: 'Alpha' }
+    })
+
+    const status = linear.getStatus()
+    expect(status).toMatchObject({
+      connected: true,
+      selectedWorkspaceId: 'org-alpha',
+      workspaces: [{ id: 'org-alpha', organizationName: 'Alpha' }]
+    })
+    expect(status.workspaces?.some((workspace) => workspace.id === 'legacy')).toBe(false)
+    expect(existsSync(join(tempHome, '.orca', 'linear-token.enc'))).toBe(false)
+    expect(readFileSync(join(tempHome, '.orca', 'linear-workspaces.json'), 'utf-8')).toContain(
+      'org-alpha'
+    )
+  })
+})
diff --git a/src/main/linear/client.ts b/src/main/linear/client.ts
index 04854e3423f..e5924176e17 100644
--- a/src/main/linear/client.ts
+++ b/src/main/linear/client.ts
@@ -1,9 +1,17 @@
+/* eslint-disable max-lines -- Why: Linear credential storage and client
+   selection share one module so keychain-safe status reads and token mutation
+   stay in one consistency boundary. */
 import { safeStorage } from 'electron'
 import { LinearClient, AuthenticationLinearError } from '@linear/sdk'
-import { readFileSync, writeFileSync, unlinkSync, mkdirSync, existsSync } from 'fs'
-import { join } from 'path'
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
-import type { LinearViewer, LinearConnectionStatus } from '../../shared/types'
+import { join } from 'path'
+import type {
+  LinearConnectionStatus,
+  LinearViewer,
+  LinearWorkspace,
+  LinearWorkspaceSelection
+} from '../../shared/types'
 
 // ── Concurrency limiter — max 4 parallel Linear API calls ────────────
 const MAX_CONCURRENT = 4
@@ -31,28 +39,73 @@ export function release(): void {
   }
 }
 
-// ── Token + viewer storage ───────────────────────────────────────────
-// Why: the token is encrypted via safeStorage (OS keychain). The viewer
-// metadata is kept in a separate *plaintext* file so settings/status
-// checks can answer "are you connected, and as whom?" without ever
-// decrypting the token. Decrypting triggers a macOS Keychain permission
-// dialog after every app signature change (e.g. every update), so we only
-// touch the encrypted token when the user actually makes a Linear API
-// call or explicitly tests the connection.
-function getTokenPath(): string {
-  return join(homedir(), '.orca', 'linear-token.enc')
+// ── Token + workspace storage ────────────────────────────────────────
+// Why: tokens remain encrypted via safeStorage, while workspace metadata stays
+// plaintext so status checks can render connected accounts without decrypting
+// and triggering OS keychain prompts after app updates.
+const LEGACY_WORKSPACE_ID = 'legacy'
+
+type LinearWorkspaceFile = {
+  version: 1
+  activeWorkspaceId: string | null
+  selectedWorkspaceId: LinearWorkspaceSelection | null
+  workspaces: LinearWorkspace[]
 }
 
-function getViewerPath(): string {
-  return join(homedir(), '.orca', 'linear-viewer.json')
+export type LinearClientForWorkspace = {
+  workspace: LinearWorkspace
+  client: LinearClient
 }
 
-let cachedToken: string | null = null
-let cachedViewer: LinearViewer | null = null
-let viewerLoadedFromDisk = false
+let cachedTokens = new Map<string, string>()
+let cachedLegacyViewer: LinearViewer | null = null
+let legacyViewerLoadedFromDisk = false
+let cachedWorkspaceFile: LinearWorkspaceFile | null = null
+let workspaceFileLoadedFromDisk = false
 
-function readViewerFromDisk(): LinearViewer | null {
-  const path = getViewerPath()
+function getOrcaDir(): string {
+  return join(homedir(), '.orca')
+}
+
+function getLegacyTokenPath(): string {
+  return join(getOrcaDir(), 'linear-token.enc')
+}
+
+function getLegacyViewerPath(): string {
+  return join(getOrcaDir(), 'linear-viewer.json')
+}
+
+function getWorkspaceFilePath(): string {
+  return join(getOrcaDir(), 'linear-workspaces.json')
+}
+
+function getWorkspaceTokenDir(): string {
+  return join(getOrcaDir(), 'linear-tokens')
+}
+
+function getWorkspaceTokenPath(workspaceId: string): string {
+  if (workspaceId === LEGACY_WORKSPACE_ID) {
+    return getLegacyTokenPath()
+  }
+  return join(getWorkspaceTokenDir(), `${Buffer.from(workspaceId).toString('base64url')}.enc`)
+}
+
+function ensureOrcaDir(): void {
+  const dir = getOrcaDir()
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+function ensureWorkspaceTokenDir(): void {
+  const dir = getWorkspaceTokenDir()
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+function readLegacyViewerFromDisk(): LinearViewer | null {
+  const path = getLegacyViewerPath()
   if (!existsSync(path)) {
     return null
   }
@@ -65,111 +118,404 @@ function readViewerFromDisk(): LinearViewer | null {
     return {
       displayName: parsed.displayName,
       email: typeof parsed.email === 'string' ? parsed.email : null,
-      organizationName: parsed.organizationName
+      organizationId: typeof parsed.organizationId === 'string' ? parsed.organizationId : undefined,
+      organizationName: parsed.organizationName,
+      organizationUrlKey:
+        typeof parsed.organizationUrlKey === 'string' ? parsed.organizationUrlKey : undefined
     }
   } catch {
     return null
   }
 }
 
-function writeViewerToDisk(viewer: LinearViewer): void {
-  const dir = join(homedir(), '.orca')
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true })
+function getLegacyViewer(): LinearViewer | null {
+  if (!legacyViewerLoadedFromDisk) {
+    cachedLegacyViewer = readLegacyViewerFromDisk()
+    legacyViewerLoadedFromDisk = true
   }
-  writeFileSync(getViewerPath(), JSON.stringify(viewer), { encoding: 'utf-8', mode: 0o600 })
+  return cachedLegacyViewer
 }
 
-function clearViewerOnDisk(): void {
+function normalizeWorkspace(input: unknown): LinearWorkspace | null {
+  if (!input || typeof input !== 'object') {
+    return null
+  }
+  const record = input as Record<string, unknown>
+  if (typeof record.id !== 'string' || typeof record.organizationName !== 'string') {
+    return null
+  }
+  if (typeof record.displayName !== 'string') {
+    return null
+  }
+
+  const organizationId =
+    typeof record.organizationId === 'string' && record.organizationId
+      ? record.organizationId
+      : record.id
+
+  return {
+    id: record.id,
+    organizationId,
+    organizationName: record.organizationName,
+    organizationUrlKey:
+      typeof record.organizationUrlKey === 'string' ? record.organizationUrlKey : undefined,
+    displayName: record.displayName,
+    email: typeof record.email === 'string' ? record.email : null
+  }
+}
+
+function emptyWorkspaceFile(): LinearWorkspaceFile {
+  return {
+    version: 1,
+    activeWorkspaceId: null,
+    selectedWorkspaceId: null,
+    workspaces: []
+  }
+}
+
+function readWorkspaceFileFromDisk(): LinearWorkspaceFile {
+  const path = getWorkspaceFilePath()
+  if (!existsSync(path)) {
+    return emptyWorkspaceFile()
+  }
   try {
-    unlinkSync(getViewerPath())
+    const raw = readFileSync(path, { encoding: 'utf-8' })
+    const parsed = JSON.parse(raw) as Partial<LinearWorkspaceFile>
+    const workspaces = Array.isArray(parsed.workspaces)
+      ? parsed.workspaces
+          .map((workspace) => normalizeWorkspace(workspace))
+          .filter((workspace): workspace is LinearWorkspace => workspace !== null)
+          .filter((workspace) => hasStoredToken(workspace.id))
+      : []
+    const activeWorkspaceId =
+      typeof parsed.activeWorkspaceId === 'string' &&
+      workspaces.some((workspace) => workspace.id === parsed.activeWorkspaceId)
+        ? parsed.activeWorkspaceId
+        : (workspaces[0]?.id ?? null)
+    const selectedWorkspaceId =
+      parsed.selectedWorkspaceId === 'all' ||
+      (typeof parsed.selectedWorkspaceId === 'string' &&
+        workspaces.some((workspace) => workspace.id === parsed.selectedWorkspaceId))
+        ? parsed.selectedWorkspaceId
+        : activeWorkspaceId
+
+    return {
+      version: 1,
+      activeWorkspaceId,
+      selectedWorkspaceId,
+      workspaces
+    }
+  } catch {
+    return emptyWorkspaceFile()
+  }
+}
+
+function getWorkspaceFile(): LinearWorkspaceFile {
+  if (!workspaceFileLoadedFromDisk || !cachedWorkspaceFile) {
+    cachedWorkspaceFile = readWorkspaceFileFromDisk()
+    workspaceFileLoadedFromDisk = true
+  }
+  return cachedWorkspaceFile
+}
+
+function writeWorkspaceFile(file: LinearWorkspaceFile): void {
+  ensureOrcaDir()
+  const persistedWorkspaces = file.workspaces.filter(
+    (workspace) => workspace.id !== LEGACY_WORKSPACE_ID
+  )
+  const selectableIds = new Set(persistedWorkspaces.map((workspace) => workspace.id))
+  if (hasStoredToken(LEGACY_WORKSPACE_ID)) {
+    selectableIds.add(LEGACY_WORKSPACE_ID)
+  }
+  const activeWorkspaceId =
+    file.activeWorkspaceId && selectableIds.has(file.activeWorkspaceId)
+      ? file.activeWorkspaceId
+      : (persistedWorkspaces[0]?.id ??
+        (selectableIds.has(LEGACY_WORKSPACE_ID) ? LEGACY_WORKSPACE_ID : null))
+  const selectedWorkspaceId =
+    file.selectedWorkspaceId === 'all'
+      ? 'all'
+      : file.selectedWorkspaceId && selectableIds.has(file.selectedWorkspaceId)
+        ? file.selectedWorkspaceId
+        : activeWorkspaceId
+
+  cachedWorkspaceFile = {
+    version: 1,
+    activeWorkspaceId,
+    selectedWorkspaceId,
+    workspaces: persistedWorkspaces
+  }
+  workspaceFileLoadedFromDisk = true
+  writeFileSync(getWorkspaceFilePath(), JSON.stringify(cachedWorkspaceFile, null, 2), {
+    encoding: 'utf-8',
+    mode: 0o600
+  })
+}
+
+function getLegacyWorkspace(): LinearWorkspace | null {
+  if (!hasStoredToken(LEGACY_WORKSPACE_ID)) {
+    return null
+  }
+  const viewer = getLegacyViewer()
+  return {
+    id: LEGACY_WORKSPACE_ID,
+    organizationId: viewer?.organizationId ?? LEGACY_WORKSPACE_ID,
+    organizationName: viewer?.organizationName ?? 'Saved Linear workspace',
+    organizationUrlKey: viewer?.organizationUrlKey,
+    displayName: viewer?.displayName ?? 'Linear API key',
+    email: viewer?.email ?? null,
+    isLegacy: true
+  }
+}
+
+function getWorkspaceState(): LinearWorkspaceFile {
+  const file = getWorkspaceFile()
+  const legacyWorkspace = getLegacyWorkspace()
+  const workspaces = [
+    ...(legacyWorkspace ? [legacyWorkspace] : []),
+    ...file.workspaces.filter((workspace) => hasStoredToken(workspace.id))
+  ]
+  const activeWorkspaceId =
+    file.activeWorkspaceId &&
+    workspaces.some((workspace) => workspace.id === file.activeWorkspaceId)
+      ? file.activeWorkspaceId
+      : (workspaces[0]?.id ?? null)
+  const selectedWorkspaceId =
+    file.selectedWorkspaceId === 'all'
+      ? 'all'
+      : file.selectedWorkspaceId &&
+          workspaces.some((workspace) => workspace.id === file.selectedWorkspaceId)
+        ? file.selectedWorkspaceId
+        : activeWorkspaceId
+
+  return {
+    version: 1,
+    activeWorkspaceId,
+    selectedWorkspaceId,
+    workspaces
+  }
+}
+
+function clearLegacyViewerOnDisk(): void {
+  try {
+    unlinkSync(getLegacyViewerPath())
   } catch {
     // File may not exist — safe to ignore.
   }
 }
 
-export function saveToken(apiKey: string): void {
-  const dir = join(homedir(), '.orca')
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true })
-  }
-  const tokenPath = getTokenPath()
-  // Why: safeStorage uses the OS keychain (macOS Keychain, Windows DPAPI,
-  // Linux libsecret) to encrypt. If the keychain is unavailable (e.g. headless
-  // Linux without a keyring), fall back to plaintext with a warning — the user
-  // explicitly chose to store a personal API key on this machine.
+function writeEncryptedToken(path: string, apiKey: string): void {
   if (safeStorage.isEncryptionAvailable()) {
     const encrypted = safeStorage.encryptString(apiKey)
-    writeFileSync(tokenPath, encrypted, { mode: 0o600 })
-  } else {
-    console.warn('[linear] safeStorage encryption unavailable — storing token in plaintext')
-    writeFileSync(tokenPath, apiKey, { encoding: 'utf-8', mode: 0o600 })
+    writeFileSync(path, encrypted, { mode: 0o600 })
+    return
   }
-  cachedToken = apiKey
+
+  console.warn('[linear] safeStorage encryption unavailable — storing token in plaintext')
+  writeFileSync(path, apiKey, { encoding: 'utf-8', mode: 0o600 })
 }
 
-// Why: force=true is used when the caller wants a token and accepts the
-// keychain prompt (explicit "Test connection" or an actual API call). The
-// default call path is fine with returning null if we haven't decrypted yet
-// this session, so status checks don't trigger Keychain.
-export function loadToken(options: { force?: boolean } = {}): string | null {
-  if (cachedToken !== null) {
-    return cachedToken
+function saveWorkspaceToken(workspaceId: string, apiKey: string): void {
+  ensureOrcaDir()
+  if (workspaceId !== LEGACY_WORKSPACE_ID) {
+    ensureWorkspaceTokenDir()
+  }
+  const tokenPath = getWorkspaceTokenPath(workspaceId)
+  writeEncryptedToken(tokenPath, apiKey)
+  cachedTokens.set(workspaceId, apiKey)
+}
+
+// Backward-compatible export for the legacy single-workspace storage path.
+export function saveToken(apiKey: string): void {
+  saveWorkspaceToken(LEGACY_WORKSPACE_ID, apiKey)
+}
+
+export function loadToken(options: { force?: boolean; workspaceId?: string } = {}): string | null {
+  const workspaceId = options.workspaceId ?? resolveWorkspaceId()
+  if (!workspaceId) {
+    return null
+  }
+  const cached = cachedTokens.get(workspaceId)
+  if (cached !== undefined) {
+    return cached
   }
   if (!options.force) {
     return null
   }
-  const tokenPath = getTokenPath()
+  const tokenPath = getWorkspaceTokenPath(workspaceId)
   if (!existsSync(tokenPath)) {
     return null
   }
   try {
     const raw = readFileSync(tokenPath)
-    cachedToken = safeStorage.isEncryptionAvailable()
+    const token = safeStorage.isEncryptionAvailable()
       ? safeStorage.decryptString(raw)
       : raw.toString('utf-8')
-    return cachedToken
+    cachedTokens.set(workspaceId, token)
+    return token
   } catch {
     return null
   }
 }
 
-export function hasStoredToken(): boolean {
-  if (cachedToken !== null) {
+export function hasStoredToken(workspaceId?: string): boolean {
+  if (!workspaceId) {
+    return getWorkspaceState().workspaces.length > 0
+  }
+  if (cachedTokens.has(workspaceId)) {
     return true
   }
-  return existsSync(getTokenPath())
+  return existsSync(getWorkspaceTokenPath(workspaceId))
 }
 
-export function clearToken(): void {
-  cachedToken = null
-  cachedViewer = null
-  viewerLoadedFromDisk = false
-  const tokenPath = getTokenPath()
+function clearTokenFile(workspaceId: string): void {
+  cachedTokens.delete(workspaceId)
   try {
-    unlinkSync(tokenPath)
+    unlinkSync(getWorkspaceTokenPath(workspaceId))
   } catch {
     // File may not exist — safe to ignore.
   }
-  clearViewerOnDisk()
+}
+
+export function clearToken(workspaceId?: string): void {
+  if (!workspaceId) {
+    const state = getWorkspaceState()
+    for (const workspace of state.workspaces) {
+      clearTokenFile(workspace.id)
+    }
+    cachedTokens = new Map()
+    cachedLegacyViewer = null
+    legacyViewerLoadedFromDisk = false
+    cachedWorkspaceFile = emptyWorkspaceFile()
+    workspaceFileLoadedFromDisk = true
+    clearLegacyViewerOnDisk()
+    writeWorkspaceFile(emptyWorkspaceFile())
+    return
+  }
+
+  clearTokenFile(workspaceId)
+  if (workspaceId === LEGACY_WORKSPACE_ID) {
+    cachedLegacyViewer = null
+    legacyViewerLoadedFromDisk = false
+    clearLegacyViewerOnDisk()
+    return
+  }
+
+  const file = getWorkspaceFile()
+  const workspaces = file.workspaces.filter((workspace) => workspace.id !== workspaceId)
+  const activeWorkspaceId =
+    file.activeWorkspaceId === workspaceId ? (workspaces[0]?.id ?? null) : file.activeWorkspaceId
+  const selectedWorkspaceId =
+    file.selectedWorkspaceId === workspaceId ? activeWorkspaceId : file.selectedWorkspaceId
+  writeWorkspaceFile({
+    version: 1,
+    activeWorkspaceId,
+    selectedWorkspaceId,
+    workspaces
+  })
+}
+
+function workspaceFromLinearData(
+  me: { displayName: string; email?: string | null },
+  org: { id: string; name: string; urlKey?: string | null }
+): LinearWorkspace {
+  return {
+    id: org.id,
+    organizationId: org.id,
+    organizationName: org.name,
+    organizationUrlKey: org.urlKey ?? undefined,
+    displayName: me.displayName,
+    email: me.email ?? null
+  }
+}
+
+function upsertWorkspace(workspace: LinearWorkspace, options: { select?: boolean } = {}): void {
+  const file = getWorkspaceFile()
+  const withoutCurrent = file.workspaces.filter((entry) => entry.id !== workspace.id)
+  const workspaces = [...withoutCurrent, workspace].sort((a, b) =>
+    a.organizationName.localeCompare(b.organizationName)
+  )
+  const selectedWorkspaceId = options.select
+    ? workspace.id
+    : file.selectedWorkspaceId && file.selectedWorkspaceId !== LEGACY_WORKSPACE_ID
+      ? file.selectedWorkspaceId
+      : workspace.id
+  writeWorkspaceFile({
+    version: 1,
+    activeWorkspaceId: workspace.id,
+    selectedWorkspaceId,
+    workspaces
+  })
+}
+
+function replaceLegacyWorkspace(workspace: LinearWorkspace, token: string): void {
+  saveWorkspaceToken(workspace.id, token)
+  clearTokenFile(LEGACY_WORKSPACE_ID)
+  clearLegacyViewerOnDisk()
+  cachedLegacyViewer = null
+  legacyViewerLoadedFromDisk = true
+  upsertWorkspace(workspace, { select: true })
+}
+
+function resolveWorkspaceId(workspaceId?: string | null): string | null {
+  if (workspaceId && workspaceId !== 'all') {
+    return workspaceId
+  }
+  const state = getWorkspaceState()
+  if (
+    state.selectedWorkspaceId &&
+    state.selectedWorkspaceId !== 'all' &&
+    state.workspaces.some((workspace) => workspace.id === state.selectedWorkspaceId)
+  ) {
+    return state.selectedWorkspaceId
+  }
+  if (
+    state.activeWorkspaceId &&
+    state.workspaces.some((workspace) => workspace.id === state.activeWorkspaceId)
+  ) {
+    return state.activeWorkspaceId
+  }
+  return state.workspaces[0]?.id ?? null
 }
 
 // ── Client factory ───────────────────────────────────────────────────
-// Why: this is called by the issues/teams modules when the user actually
-// performs a Linear action — at that point decrypting the token (and
-// surfacing a Keychain prompt if needed) is expected.
-export function getClient(): LinearClient | null {
-  const token = loadToken({ force: true })
+// Why: issues/teams modules call this for real Linear actions — at that point
+// decrypting the token and surfacing a keychain prompt is expected.
+export function getClient(workspaceId?: string | null): LinearClient | null {
+  const token = loadToken({
+    force: true,
+    workspaceId: resolveWorkspaceId(workspaceId) ?? undefined
+  })
   if (!token) {
     return null
   }
   return new LinearClient({ apiKey: token })
 }
 
+export function getClients(
+  workspaceId?: LinearWorkspaceSelection | null
+): LinearClientForWorkspace[] {
+  const state = getWorkspaceState()
+  const selectedWorkspaces =
+    workspaceId === 'all'
+      ? state.workspaces
+      : state.workspaces.filter((workspace) => workspace.id === resolveWorkspaceId(workspaceId))
+
+  const clients: LinearClientForWorkspace[] = []
+  for (const workspace of selectedWorkspaces) {
+    const token = loadToken({ force: true, workspaceId: workspace.id })
+    if (!token) {
+      continue
+    }
+    clients.push({ workspace, client: new LinearClient({ apiKey: token }) })
+  }
+  return clients
+}
+
 // ── Auth error detection ─────────────────────────────────────────────
 // Why: 401 errors must trigger token clearing and a re-auth prompt in the
-// renderer (design §Error Propagation). All other errors are swallowed
-// with console.warn to match GitHub client's graceful degradation.
+// renderer. All other errors are swallowed with console.warn to match GitHub
+// client's graceful degradation.
 export function isAuthError(error: unknown): boolean {
   return error instanceof AuthenticationLinearError
 }
@@ -177,58 +523,89 @@ export function isAuthError(error: unknown): boolean {
 // ── Connect / disconnect / status ────────────────────────────────────
 export async function connect(
   apiKey: string
-): Promise<{ ok: true; viewer: LinearViewer } | { ok: false; error: string }> {
+): Promise<
+  { ok: true; viewer: LinearViewer; workspace: LinearWorkspace } | { ok: false; error: string }
+> {
   try {
     const client = new LinearClient({ apiKey })
     const me = await client.viewer
     const org = await me.organization
+    const workspace = workspaceFromLinearData(me, org)
 
-    const viewer: LinearViewer = {
-      displayName: me.displayName,
-      email: me.email ?? null,
-      organizationName: org.name
+    saveWorkspaceToken(workspace.id, apiKey)
+    const legacyWorkspace = getLegacyWorkspace()
+    if (
+      legacyWorkspace &&
+      legacyWorkspace.organizationName === workspace.organizationName &&
+      legacyWorkspace.email === workspace.email
+    ) {
+      clearTokenFile(LEGACY_WORKSPACE_ID)
+      clearLegacyViewerOnDisk()
+      cachedLegacyViewer = null
+      legacyViewerLoadedFromDisk = true
     }
-
-    saveToken(apiKey)
-    writeViewerToDisk(viewer)
-    cachedViewer = viewer
-    viewerLoadedFromDisk = true
-    return { ok: true, viewer }
+    upsertWorkspace(workspace, { select: true })
+    return { ok: true, viewer: workspace, workspace }
   } catch (error) {
     const message = error instanceof Error ? error.message : 'Failed to validate API key'
     return { ok: false, error: message }
   }
 }
 
-export function disconnect(): void {
-  clearToken()
+export function disconnect(workspaceId?: string): void {
+  clearToken(workspaceId)
+}
+
+export function selectWorkspace(workspaceId: LinearWorkspaceSelection): LinearConnectionStatus {
+  const state = getWorkspaceState()
+  if (
+    workspaceId !== 'all' &&
+    !state.workspaces.some((workspace) => workspace.id === workspaceId)
+  ) {
+    return getStatus()
+  }
+
+  const file = getWorkspaceFile()
+  writeWorkspaceFile({
+    version: 1,
+    activeWorkspaceId: workspaceId === 'all' ? file.activeWorkspaceId : workspaceId,
+    selectedWorkspaceId: workspaceId,
+    workspaces: file.workspaces
+  })
+  return getStatus()
 }
 
-// Why: getStatus must NEVER decrypt the token. It returns the cached
-// viewer (written at connect time) so the settings/landing UIs can show
-// "Connected as X" without triggering a Keychain permission dialog after
-// every app update. The encrypted token is only touched lazily on real
-// Linear API calls or when the user clicks "Test connection".
 export function getStatus(): LinearConnectionStatus {
-  if (!hasStoredToken()) {
-    return { connected: false, viewer: null }
-  }
+  const state = getWorkspaceState()
+  const selectedWorkspace =
+    state.selectedWorkspaceId && state.selectedWorkspaceId !== 'all'
+      ? state.workspaces.find((workspace) => workspace.id === state.selectedWorkspaceId)
+      : null
+  const activeWorkspace =
+    selectedWorkspace ??
+    state.workspaces.find((workspace) => workspace.id === state.activeWorkspaceId) ??
+    state.workspaces[0] ??
+    null
 
-  if (!cachedViewer && !viewerLoadedFromDisk) {
-    cachedViewer = readViewerFromDisk()
-    viewerLoadedFromDisk = true
+  return {
+    connected: state.workspaces.length > 0,
+    viewer: activeWorkspace,
+    workspaces: state.workspaces,
+    activeWorkspaceId: state.activeWorkspaceId,
+    selectedWorkspaceId: state.selectedWorkspaceId
   }
-
-  return { connected: true, viewer: cachedViewer }
 }
 
-// Why: explicit user-initiated check. Decrypts the token, pings the
-// Linear API to re-validate, and refreshes the cached viewer file. If the
-// token is rejected (401) it clears state just like a live API error.
-export async function testConnection(): Promise<
-  { ok: true; viewer: LinearViewer } | { ok: false; error: string }
+export async function testConnection(
+  workspaceId?: string
+): Promise<
+  { ok: true; viewer: LinearViewer; workspace: LinearWorkspace } | { ok: false; error: string }
 > {
-  const token = loadToken({ force: true })
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId)
+  if (!resolvedWorkspaceId) {
+    return { ok: false, error: 'No API key stored.' }
+  }
+  const token = loadToken({ force: true, workspaceId: resolvedWorkspaceId })
   if (!token) {
     return { ok: false, error: 'No API key stored.' }
   }
@@ -237,31 +614,26 @@ export async function testConnection(): Promise<
     const client = new LinearClient({ apiKey: token })
     const me = await client.viewer
     const org = await me.organization
-    const viewer: LinearViewer = {
-      displayName: me.displayName,
-      email: me.email ?? null,
-      organizationName: org.name
+    const workspace = workspaceFromLinearData(me, org)
+    if (resolvedWorkspaceId === LEGACY_WORKSPACE_ID) {
+      replaceLegacyWorkspace(workspace, token)
+    } else {
+      saveWorkspaceToken(workspace.id, token)
+      upsertWorkspace(workspace, { select: true })
     }
-    writeViewerToDisk(viewer)
-    cachedViewer = viewer
-    viewerLoadedFromDisk = true
-    return { ok: true, viewer }
+    return { ok: true, viewer: workspace, workspace }
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(resolvedWorkspaceId)
     }
     const message = error instanceof Error ? error.message : 'Test failed'
     return { ok: false, error: message }
   }
 }
 
-// Why: called at main-process startup. This used to eagerly decrypt the
-// token (which triggered a Keychain prompt on every launch after an app
-// update). We now only warm the plaintext viewer cache — the token stays
-// encrypted on disk until actually needed.
+// Why: called at main-process startup. We warm plaintext metadata only; tokens
+// stay encrypted on disk until a user performs an actual Linear action.
 export function initLinearToken(): void {
-  if (!viewerLoadedFromDisk) {
-    cachedViewer = readViewerFromDisk()
-    viewerLoadedFromDisk = true
-  }
+  getWorkspaceFile()
+  getLegacyViewer()
 }
diff --git a/src/main/linear/issues.ts b/src/main/linear/issues.ts
index 69bd579d249..afc59809973 100644
--- a/src/main/linear/issues.ts
+++ b/src/main/linear/issues.ts
@@ -1,49 +1,106 @@
-import type { LinearIssue, LinearIssueUpdate, LinearComment } from '../../shared/types'
-import { acquire, release, getClient, isAuthError, clearToken } from './client'
+/* eslint-disable max-lines -- Why: Linear issue reads and mutations share the
+   same workspace fan-out/error handling, so keeping them together avoids
+   drifting auth-clearing behavior between operations. */
+import type {
+  LinearIssue,
+  LinearIssueUpdate,
+  LinearComment,
+  LinearWorkspaceSelection
+} from '../../shared/types'
+import {
+  acquire,
+  release,
+  getClients,
+  isAuthError,
+  clearToken,
+  type LinearClientForWorkspace
+} from './client'
 import { mapLinearIssue } from './mappers'
 
-export async function getIssue(id: string): Promise<LinearIssue | null> {
-  const client = getClient()
-  if (!client) {
-    return null
-  }
-
-  await acquire()
-  try {
-    const issue = await client.issue(id)
-    return await mapLinearIssue(issue)
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken()
-      throw error
-    }
-    console.warn('[linear] getIssue failed:', error)
-    return null
-  } finally {
-    release()
+async function mapIssueForWorkspace(
+  entry: LinearClientForWorkspace,
+  issue: Parameters<typeof mapLinearIssue>[0]
+): Promise<LinearIssue> {
+  const mapped = await mapLinearIssue(issue)
+  return {
+    ...mapped,
+    workspaceId: entry.workspace.id,
+    workspaceName: entry.workspace.organizationName
   }
 }
 
-export async function searchIssues(query: string, limit = 20): Promise<LinearIssue[]> {
-  const client = getClient()
-  if (!client) {
+function sortAndLimitIssues(issues: LinearIssue[], limit: number): LinearIssue[] {
+  return issues
+    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
+    .slice(0, limit)
+}
+
+function shouldThrowAuthError(selection: LinearWorkspaceSelection | null | undefined): boolean {
+  return selection !== 'all'
+}
+
+export async function getIssue(
+  id: string,
+  workspaceId?: LinearWorkspaceSelection | null
+): Promise<LinearIssue | null> {
+  const entries = getClients(workspaceId)
+  if (entries.length === 0) {
+    return null
+  }
+
+  for (const entry of entries) {
+    await acquire()
+    try {
+      const issue = await entry.client.issue(id)
+      return await mapIssueForWorkspace(entry, issue)
+    } catch (error) {
+      if (isAuthError(error)) {
+        clearToken(entry.workspace.id)
+        if (shouldThrowAuthError(workspaceId)) {
+          throw error
+        }
+      } else {
+        console.warn('[linear] getIssue failed:', error)
+      }
+    } finally {
+      release()
+    }
+  }
+  return null
+}
+
+export async function searchIssues(
+  query: string,
+  limit = 20,
+  workspaceId?: LinearWorkspaceSelection | null
+): Promise<LinearIssue[]> {
+  const entries = getClients(workspaceId)
+  if (entries.length === 0) {
     return []
   }
 
-  await acquire()
-  try {
-    const result = await client.searchIssues(query, { first: limit })
-    return await Promise.all(result.nodes.map(mapLinearIssue))
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken()
-      throw error
-    }
-    console.warn('[linear] searchIssues failed:', error)
-    return []
-  } finally {
-    release()
-  }
+  const results = await Promise.all(
+    entries.map(async (entry) => {
+      await acquire()
+      try {
+        const result = await entry.client.searchIssues(query, { first: limit })
+        return await Promise.all(result.nodes.map((issue) => mapIssueForWorkspace(entry, issue)))
+      } catch (error) {
+        if (isAuthError(error)) {
+          clearToken(entry.workspace.id)
+          if (shouldThrowAuthError(workspaceId)) {
+            throw error
+          }
+        } else {
+          console.warn('[linear] searchIssues failed:', error)
+        }
+        return []
+      } finally {
+        release()
+      }
+    })
+  )
+  return sortAndLimitIssues(results.flat(), limit)
 }
 
 export type LinearListFilter = 'assigned' | 'created' | 'all' | 'completed'
@@ -53,81 +110,99 @@ const COMPLETED_STATE_FILTER = { state: { type: { in: ['completed', 'canceled']
 
 export async function listIssues(
   filter: LinearListFilter = 'assigned',
-  limit = 20
+  limit = 20,
+  workspaceId?: LinearWorkspaceSelection | null
 ): Promise<LinearIssue[]> {
-  const client = getClient()
-  if (!client) {
+  const entries = getClients(workspaceId)
+  if (entries.length === 0) {
     return []
   }
 
-  await acquire()
-  try {
-    const orderBy = 'updatedAt' as never
+  const results = await Promise.all(
+    entries.map(async (entry) => {
+      await acquire()
+      try {
+        const orderBy = 'updatedAt' as never
 
-    if (filter === 'assigned') {
-      const viewer = await client.viewer
-      const connection = await viewer.assignedIssues({
-        first: limit,
-        orderBy,
-        filter: ACTIVE_STATE_FILTER
-      })
-      return await Promise.all(connection.nodes.map(mapLinearIssue))
-    }
+        if (filter === 'assigned') {
+          const viewer = await entry.client.viewer
+          const connection = await viewer.assignedIssues({
+            first: limit,
+            orderBy,
+            filter: ACTIVE_STATE_FILTER
+          })
+          return await Promise.all(
+            connection.nodes.map((issue) => mapIssueForWorkspace(entry, issue))
+          )
+        }
 
-    if (filter === 'created') {
-      const viewer = await client.viewer
-      const connection = await viewer.createdIssues({
-        first: limit,
-        orderBy,
-        filter: ACTIVE_STATE_FILTER
-      })
-      return await Promise.all(connection.nodes.map(mapLinearIssue))
-    }
+        if (filter === 'created') {
+          const viewer = await entry.client.viewer
+          const connection = await viewer.createdIssues({
+            first: limit,
+            orderBy,
+            filter: ACTIVE_STATE_FILTER
+          })
+          return await Promise.all(
+            connection.nodes.map((issue) => mapIssueForWorkspace(entry, issue))
+          )
+        }
 
-    if (filter === 'completed') {
-      const viewer = await client.viewer
-      const connection = await viewer.assignedIssues({
-        first: limit,
-        orderBy,
-        filter: COMPLETED_STATE_FILTER
-      })
-      return await Promise.all(connection.nodes.map(mapLinearIssue))
-    }
+        if (filter === 'completed') {
+          const viewer = await entry.client.viewer
+          const connection = await viewer.assignedIssues({
+            first: limit,
+            orderBy,
+            filter: COMPLETED_STATE_FILTER
+          })
+          return await Promise.all(
+            connection.nodes.map((issue) => mapIssueForWorkspace(entry, issue))
+          )
+        }
 
-    // 'all' — all active issues across the workspace
-    const connection = await client.issues({
-      first: limit,
-      orderBy,
-      filter: ACTIVE_STATE_FILTER
+        // 'all' — all active issues across the workspace
+        const connection = await entry.client.issues({
+          first: limit,
+          orderBy,
+          filter: ACTIVE_STATE_FILTER
+        })
+        return await Promise.all(
+          connection.nodes.map((issue) => mapIssueForWorkspace(entry, issue))
+        )
+      } catch (error) {
+        if (isAuthError(error)) {
+          clearToken(entry.workspace.id)
+          if (shouldThrowAuthError(workspaceId)) {
+            throw error
+          }
+        } else {
+          console.warn('[linear] listIssues failed:', error)
+        }
+        return []
+      } finally {
+        release()
+      }
     })
-    return await Promise.all(connection.nodes.map(mapLinearIssue))
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken()
-      throw error
-    }
-    console.warn('[linear] listIssues failed:', error)
-    return []
-  } finally {
-    release()
-  }
+  )
+  return sortAndLimitIssues(results.flat(), limit)
 }
 
 export async function createIssue(
   teamId: string,
   title: string,
-  description?: string
+  description?: string,
+  workspaceId?: string | null
 ): Promise<
   { ok: true; id: string; identifier: string; url: string } | { ok: false; error: string }
 > {
-  const client = getClient()
-  if (!client) {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
     return { ok: false, error: 'Not connected to Linear' }
   }
 
   await acquire()
   try {
-    const result = await client.createIssue({
+    const result = await entry.client.createIssue({
       teamId,
       title,
       ...(description ? { description } : {})
@@ -142,7 +217,7 @@ export async function createIssue(
     return { ok: true, id: issue.id, identifier: issue.identifier, url: issue.url }
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(entry.workspace.id)
       throw error
     }
     const message = error instanceof Error ? error.message : String(error)
@@ -154,10 +229,11 @@ export async function createIssue(
 
 export async function updateIssue(
   id: string,
-  updates: LinearIssueUpdate
+  updates: LinearIssueUpdate,
+  workspaceId?: string | null
 ): Promise<{ ok: true } | { ok: false; error: string }> {
-  const client = getClient()
-  if (!client) {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
     return { ok: false, error: 'Not connected to Linear' }
   }
 
@@ -186,14 +262,14 @@ export async function updateIssue(
       payload.labelIds = resolvedLabelIds
     }
 
-    const result = await client.updateIssue(id, payload)
+    const result = await entry.client.updateIssue(id, payload)
     if (!result.success) {
       return { ok: false, error: 'Linear update failed' }
     }
     return { ok: true }
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(entry.workspace.id)
       throw error
     }
     const message = error instanceof Error ? error.message : String(error)
@@ -205,16 +281,17 @@ export async function updateIssue(
 
 export async function addIssueComment(
   issueId: string,
-  body: string
+  body: string,
+  workspaceId?: string | null
 ): Promise<{ ok: true; id: string } | { ok: false; error: string }> {
-  const client = getClient()
-  if (!client) {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
     return { ok: false, error: 'Not connected to Linear' }
   }
 
   await acquire()
   try {
-    const result = await client.createComment({ issueId, body })
+    const result = await entry.client.createComment({ issueId, body })
     if (!result.success) {
       return { ok: false, error: 'Failed to create comment' }
     }
@@ -222,7 +299,7 @@ export async function addIssueComment(
     return { ok: true, id: comment?.id ?? '' }
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(entry.workspace.id)
       throw error
     }
     const message = error instanceof Error ? error.message : String(error)
@@ -232,15 +309,18 @@ export async function addIssueComment(
   }
 }
 
-export async function getIssueComments(issueId: string): Promise<LinearComment[]> {
-  const client = getClient()
-  if (!client) {
+export async function getIssueComments(
+  issueId: string,
+  workspaceId?: string | null
+): Promise<LinearComment[]> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
     return []
   }
 
   await acquire()
   try {
-    const issue = await client.issue(issueId)
+    const issue = await entry.client.issue(issueId)
     const comments = await issue.comments()
     const results: LinearComment[] = []
     for (const c of comments.nodes) {
@@ -257,7 +337,7 @@ export async function getIssueComments(issueId: string): Promise<LinearComment[]
     return results
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(entry.workspace.id)
       throw error
     }
     console.warn('[linear] getIssueComments failed:', error)
diff --git a/src/main/linear/teams.ts b/src/main/linear/teams.ts
index 5e65dac6d79..4e0c7b012fd 100644
--- a/src/main/linear/teams.ts
+++ b/src/main/linear/teams.ts
@@ -1,39 +1,62 @@
-import type { LinearTeam, LinearWorkflowState, LinearLabel, LinearMember } from '../../shared/types'
-import { acquire, release, getClient, isAuthError, clearToken } from './client'
+import type {
+  LinearTeam,
+  LinearWorkflowState,
+  LinearLabel,
+  LinearMember,
+  LinearWorkspaceSelection
+} from '../../shared/types'
+import { acquire, release, getClients, isAuthError, clearToken } from './client'
 
-export async function listTeams(): Promise<LinearTeam[]> {
-  const client = getClient()
-  if (!client) {
+export async function listTeams(
+  workspaceId?: LinearWorkspaceSelection | null
+): Promise<LinearTeam[]> {
+  const entries = getClients(workspaceId)
+  if (entries.length === 0) {
     return []
   }
 
-  await acquire()
-  try {
-    const teams = await client.teams()
-    return teams.nodes
-      .map((t) => ({ id: t.id, name: t.name, key: t.key }))
-      .sort((a, b) => a.name.localeCompare(b.name))
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken()
-      throw error
-    }
-    console.warn('[linear] listTeams failed:', error)
-    return []
-  } finally {
-    release()
-  }
+  const results = await Promise.all(
+    entries.map(async (entry) => {
+      await acquire()
+      try {
+        const teams = await entry.client.teams()
+        return teams.nodes.map((t) => ({
+          id: t.id,
+          workspaceId: entry.workspace.id,
+          workspaceName: entry.workspace.organizationName,
+          name: t.name,
+          key: t.key
+        }))
+      } catch (error) {
+        if (isAuthError(error)) {
+          clearToken(entry.workspace.id)
+          if (workspaceId !== 'all') {
+            throw error
+          }
+        } else {
+          console.warn('[linear] listTeams failed:', error)
+        }
+        return []
+      } finally {
+        release()
+      }
+    })
+  )
+  return results.flat().sort((a, b) => a.name.localeCompare(b.name))
 }
 
-export async function getTeamStates(teamId: string): Promise<LinearWorkflowState[]> {
-  const client = getClient()
-  if (!client) {
+export async function getTeamStates(
+  teamId: string,
+  workspaceId?: string | null
+): Promise<LinearWorkflowState[]> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
     return []
   }
 
   await acquire()
   try {
-    const team = await client.team(teamId)
+    const team = await entry.client.team(teamId)
     const states = await team.states()
     return states.nodes
       .map((s) => ({
@@ -46,7 +69,7 @@ export async function getTeamStates(teamId: string): Promise<LinearWorkflowState
       .sort((a, b) => a.position - b.position)
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(entry.workspace.id)
       throw error
     }
     console.warn('[linear] getTeamStates failed:', error)
@@ -56,20 +79,23 @@ export async function getTeamStates(teamId: string): Promise<LinearWorkflowState
   }
 }
 
-export async function getTeamLabels(teamId: string): Promise<LinearLabel[]> {
-  const client = getClient()
-  if (!client) {
+export async function getTeamLabels(
+  teamId: string,
+  workspaceId?: string | null
+): Promise<LinearLabel[]> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
     return []
   }
 
   await acquire()
   try {
-    const team = await client.team(teamId)
+    const team = await entry.client.team(teamId)
     const labels = await team.labels()
     return labels.nodes.map((l) => ({ id: l.id, name: l.name, color: l.color }))
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(entry.workspace.id)
       throw error
     }
     console.warn('[linear] getTeamLabels failed:', error)
@@ -79,15 +105,18 @@ export async function getTeamLabels(teamId: string): Promise<LinearLabel[]> {
   }
 }
 
-export async function getTeamMembers(teamId: string): Promise<LinearMember[]> {
-  const client = getClient()
-  if (!client) {
+export async function getTeamMembers(
+  teamId: string,
+  workspaceId?: string | null
+): Promise<LinearMember[]> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
     return []
   }
 
   await acquire()
   try {
-    const team = await client.team(teamId)
+    const team = await entry.client.team(teamId)
     const members = await team.members()
     return members.nodes.map((m) => ({
       id: m.id,
@@ -96,7 +125,7 @@ export async function getTeamMembers(teamId: string): Promise<LinearMember[]> {
     }))
   } catch (error) {
     if (isAuthError(error)) {
-      clearToken()
+      clearToken(entry.workspace.id)
       throw error
     }
     console.warn('[linear] getTeamMembers failed:', error)
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 9f0277b35db..53a8e2ce6ef 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -27,6 +27,7 @@ import type {
   WorktreeRemoteBranchConflictEvent,
   WorktreeStartupLaunch,
   LinearIssueUpdate,
+  LinearWorkspaceSelection,
   TuiAgent
 } from '../../shared/types'
 import { splitWorktreeId } from '../../shared/worktree-id'
@@ -116,6 +117,7 @@ import {
   connect as connectLinear,
   disconnect as disconnectLinear,
   getStatus as getLinearStatus,
+  selectWorkspace as selectLinearWorkspace,
   testConnection as testLinearConnection
 } from '../linear/client'
 import {
@@ -7758,65 +7760,89 @@ export class OrcaRuntimeService {
     return connectLinear(apiKey)
   }
 
-  linearDisconnect(): { ok: true } {
-    disconnectLinear()
+  linearDisconnect(workspaceId?: string): { ok: true } {
+    disconnectLinear(workspaceId)
     return { ok: true }
   }
 
+  linearSelectWorkspace(workspaceId: LinearWorkspaceSelection): ReturnType<typeof getLinearStatus> {
+    return selectLinearWorkspace(workspaceId)
+  }
+
   linearStatus(): ReturnType<typeof getLinearStatus> {
     return getLinearStatus()
   }
 
-  linearTestConnection(): ReturnType<typeof testLinearConnection> {
-    return testLinearConnection()
+  linearTestConnection(workspaceId?: string): ReturnType<typeof testLinearConnection> {
+    return testLinearConnection(workspaceId)
   }
 
-  linearSearchIssues(query: string, limit = 20): ReturnType<typeof searchLinearIssues> {
-    return searchLinearIssues(query, Math.min(Math.max(1, limit), 50))
+  linearSearchIssues(
+    query: string,
+    limit = 20,
+    workspaceId?: LinearWorkspaceSelection
+  ): ReturnType<typeof searchLinearIssues> {
+    return searchLinearIssues(query, Math.min(Math.max(1, limit), 50), workspaceId)
   }
 
-  linearListIssues(filter?: LinearListFilter, limit = 20): ReturnType<typeof listLinearIssues> {
-    return listLinearIssues(filter, Math.min(Math.max(1, limit), 50))
+  linearListIssues(
+    filter?: LinearListFilter,
+    limit = 20,
+    workspaceId?: LinearWorkspaceSelection
+  ): ReturnType<typeof listLinearIssues> {
+    return listLinearIssues(filter, Math.min(Math.max(1, limit), 50), workspaceId)
   }
 
   linearCreateIssue(
     teamId: string,
     title: string,
-    description?: string
+    description?: string,
+    workspaceId?: string
   ): ReturnType<typeof createLinearIssue> {
-    return createLinearIssue(teamId, title, description)
+    return createLinearIssue(teamId, title, description, workspaceId)
   }
 
-  linearGetIssue(id: string): ReturnType<typeof getLinearIssue> {
-    return getLinearIssue(id)
+  linearGetIssue(id: string, workspaceId?: string): ReturnType<typeof getLinearIssue> {
+    return getLinearIssue(id, workspaceId)
   }
 
-  linearUpdateIssue(id: string, updates: LinearIssueUpdate): ReturnType<typeof updateLinearIssue> {
-    return updateLinearIssue(id, updates)
+  linearUpdateIssue(
+    id: string,
+    updates: LinearIssueUpdate,
+    workspaceId?: string
+  ): ReturnType<typeof updateLinearIssue> {
+    return updateLinearIssue(id, updates, workspaceId)
   }
 
-  linearAddIssueComment(issueId: string, body: string): ReturnType<typeof addLinearIssueComment> {
-    return addLinearIssueComment(issueId, body)
+  linearAddIssueComment(
+    issueId: string,
+    body: string,
+    workspaceId?: string
+  ): ReturnType<typeof addLinearIssueComment> {
+    return addLinearIssueComment(issueId, body, workspaceId)
   }
 
-  linearIssueComments(issueId: string): ReturnType<typeof getLinearIssueComments> {
-    return getLinearIssueComments(issueId)
+  linearIssueComments(
+    issueId: string,
+    workspaceId?: string
+  ): ReturnType<typeof getLinearIssueComments> {
+    return getLinearIssueComments(issueId, workspaceId)
   }
 
-  linearListTeams(): ReturnType<typeof listLinearTeams> {
-    return listLinearTeams()
+  linearListTeams(workspaceId?: LinearWorkspaceSelection): ReturnType<typeof listLinearTeams> {
+    return listLinearTeams(workspaceId)
   }
 
-  linearTeamStates(teamId: string): ReturnType<typeof getLinearTeamStates> {
-    return getLinearTeamStates(teamId)
+  linearTeamStates(teamId: string, workspaceId?: string): ReturnType<typeof getLinearTeamStates> {
+    return getLinearTeamStates(teamId, workspaceId)
   }
 
-  linearTeamLabels(teamId: string): ReturnType<typeof getLinearTeamLabels> {
-    return getLinearTeamLabels(teamId)
+  linearTeamLabels(teamId: string, workspaceId?: string): ReturnType<typeof getLinearTeamLabels> {
+    return getLinearTeamLabels(teamId, workspaceId)
   }
 
-  linearTeamMembers(teamId: string): ReturnType<typeof getLinearTeamMembers> {
-    return getLinearTeamMembers(teamId)
+  linearTeamMembers(teamId: string, workspaceId?: string): ReturnType<typeof getLinearTeamMembers> {
+    return getLinearTeamMembers(teamId, workspaceId)
   }
 
   // ── Browser automation ──
diff --git a/src/main/runtime/rpc/methods/linear.test.ts b/src/main/runtime/rpc/methods/linear.test.ts
index ec95e5525b2..85ec802fc53 100644
--- a/src/main/runtime/rpc/methods/linear.test.ts
+++ b/src/main/runtime/rpc/methods/linear.test.ts
@@ -15,6 +15,7 @@ describe('linear RPC methods', () => {
       linearStatus: vi.fn().mockResolvedValue({ connected: true, viewer: null }),
       linearTestConnection: vi.fn().mockResolvedValue({ ok: true, viewer: { displayName: 'Ada' } }),
       linearConnect: vi.fn().mockResolvedValue({ ok: true, viewer: { displayName: 'Ada' } }),
+      linearSelectWorkspace: vi.fn().mockResolvedValue({ connected: true, viewer: null }),
       linearDisconnect: vi.fn().mockResolvedValue({ ok: true })
     } as unknown as OrcaRuntimeService
     const dispatcher = new RpcDispatcher({ runtime, methods: LINEAR_METHODS })
@@ -22,11 +23,13 @@ describe('linear RPC methods', () => {
     await dispatcher.dispatch(makeRequest('linear.status'))
     await dispatcher.dispatch(makeRequest('linear.testConnection'))
     await dispatcher.dispatch(makeRequest('linear.connect', { apiKey: 'lin_api_key' }))
+    await dispatcher.dispatch(makeRequest('linear.selectWorkspace', { workspaceId: 'workspace-1' }))
     await dispatcher.dispatch(makeRequest('linear.disconnect'))
 
     expect(runtime.linearStatus).toHaveBeenCalled()
     expect(runtime.linearTestConnection).toHaveBeenCalled()
     expect(runtime.linearConnect).toHaveBeenCalledWith('lin_api_key')
+    expect(runtime.linearSelectWorkspace).toHaveBeenCalledWith('workspace-1')
     expect(runtime.linearDisconnect).toHaveBeenCalled()
   })
 
@@ -43,39 +46,70 @@ describe('linear RPC methods', () => {
     } as unknown as OrcaRuntimeService
     const dispatcher = new RpcDispatcher({ runtime, methods: LINEAR_METHODS })
 
-    await dispatcher.dispatch(makeRequest('linear.searchIssues', { query: 'bug', limit: 30 }))
-    await dispatcher.dispatch(makeRequest('linear.listIssues', { filter: 'assigned', limit: 20 }))
-    await dispatcher.dispatch(makeRequest('linear.getIssue', { id: 'issue-3' }))
+    await dispatcher.dispatch(
+      makeRequest('linear.searchIssues', { query: 'bug', limit: 30, workspaceId: 'all' })
+    )
+    await dispatcher.dispatch(
+      makeRequest('linear.listIssues', {
+        filter: 'assigned',
+        limit: 20,
+        workspaceId: 'workspace-1'
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('linear.getIssue', { id: 'issue-3', workspaceId: 'workspace-1' })
+    )
     await dispatcher.dispatch(
       makeRequest('linear.createIssue', {
         teamId: 'team-1',
         title: 'Fix bug',
-        description: 'Details'
+        description: 'Details',
+        workspaceId: 'workspace-1'
       })
     )
     await dispatcher.dispatch(
       makeRequest('linear.updateIssue', {
         id: 'issue-3',
+        workspaceId: 'workspace-1',
         updates: { stateId: 'state-1', assigneeId: null, priority: 2, labelIds: ['label-1'] }
       })
     )
     await dispatcher.dispatch(
-      makeRequest('linear.addIssueComment', { issueId: 'issue-3', body: 'Looks good' })
+      makeRequest('linear.addIssueComment', {
+        issueId: 'issue-3',
+        body: 'Looks good',
+        workspaceId: 'workspace-1'
+      })
+    )
+    await dispatcher.dispatch(
+      makeRequest('linear.issueComments', { issueId: 'issue-3', workspaceId: 'workspace-1' })
     )
-    await dispatcher.dispatch(makeRequest('linear.issueComments', { issueId: 'issue-3' }))
 
-    expect(runtime.linearSearchIssues).toHaveBeenCalledWith('bug', 30)
-    expect(runtime.linearListIssues).toHaveBeenCalledWith('assigned', 20)
-    expect(runtime.linearGetIssue).toHaveBeenCalledWith('issue-3')
-    expect(runtime.linearCreateIssue).toHaveBeenCalledWith('team-1', 'Fix bug', 'Details')
-    expect(runtime.linearUpdateIssue).toHaveBeenCalledWith('issue-3', {
-      stateId: 'state-1',
-      assigneeId: null,
-      priority: 2,
-      labelIds: ['label-1']
-    })
-    expect(runtime.linearAddIssueComment).toHaveBeenCalledWith('issue-3', 'Looks good')
-    expect(runtime.linearIssueComments).toHaveBeenCalledWith('issue-3')
+    expect(runtime.linearSearchIssues).toHaveBeenCalledWith('bug', 30, 'all')
+    expect(runtime.linearListIssues).toHaveBeenCalledWith('assigned', 20, 'workspace-1')
+    expect(runtime.linearGetIssue).toHaveBeenCalledWith('issue-3', 'workspace-1')
+    expect(runtime.linearCreateIssue).toHaveBeenCalledWith(
+      'team-1',
+      'Fix bug',
+      'Details',
+      'workspace-1'
+    )
+    expect(runtime.linearUpdateIssue).toHaveBeenCalledWith(
+      'issue-3',
+      {
+        stateId: 'state-1',
+        assigneeId: null,
+        priority: 2,
+        labelIds: ['label-1']
+      },
+      'workspace-1'
+    )
+    expect(runtime.linearAddIssueComment).toHaveBeenCalledWith(
+      'issue-3',
+      'Looks good',
+      'workspace-1'
+    )
+    expect(runtime.linearIssueComments).toHaveBeenCalledWith('issue-3', 'workspace-1')
   })
 
   it('routes Linear metadata requests to the runtime server', async () => {
@@ -88,14 +122,20 @@ describe('linear RPC methods', () => {
     } as unknown as OrcaRuntimeService
     const dispatcher = new RpcDispatcher({ runtime, methods: LINEAR_METHODS })
 
-    await dispatcher.dispatch(makeRequest('linear.listTeams'))
-    await dispatcher.dispatch(makeRequest('linear.teamStates', { teamId: 'team-1' }))
-    await dispatcher.dispatch(makeRequest('linear.teamLabels', { teamId: 'team-1' }))
-    await dispatcher.dispatch(makeRequest('linear.teamMembers', { teamId: 'team-1' }))
+    await dispatcher.dispatch(makeRequest('linear.listTeams', { workspaceId: 'all' }))
+    await dispatcher.dispatch(
+      makeRequest('linear.teamStates', { teamId: 'team-1', workspaceId: 'workspace-1' })
+    )
+    await dispatcher.dispatch(
+      makeRequest('linear.teamLabels', { teamId: 'team-1', workspaceId: 'workspace-1' })
+    )
+    await dispatcher.dispatch(
+      makeRequest('linear.teamMembers', { teamId: 'team-1', workspaceId: 'workspace-1' })
+    )
 
-    expect(runtime.linearListTeams).toHaveBeenCalled()
-    expect(runtime.linearTeamStates).toHaveBeenCalledWith('team-1')
-    expect(runtime.linearTeamLabels).toHaveBeenCalledWith('team-1')
-    expect(runtime.linearTeamMembers).toHaveBeenCalledWith('team-1')
+    expect(runtime.linearListTeams).toHaveBeenCalledWith('all')
+    expect(runtime.linearTeamStates).toHaveBeenCalledWith('team-1', 'workspace-1')
+    expect(runtime.linearTeamLabels).toHaveBeenCalledWith('team-1', 'workspace-1')
+    expect(runtime.linearTeamMembers).toHaveBeenCalledWith('team-1', 'workspace-1')
   })
 })
diff --git a/src/main/runtime/rpc/methods/linear.ts b/src/main/runtime/rpc/methods/linear.ts
index 29bdcf488f8..71c10ab3d02 100644
--- a/src/main/runtime/rpc/methods/linear.ts
+++ b/src/main/runtime/rpc/methods/linear.ts
@@ -8,39 +8,56 @@ const Connect = z.object({
   apiKey: requiredString('Invalid API key')
 })
 
+const WorkspaceSelection = z
+  .object({
+    workspaceId: OptionalString
+  })
+  .optional()
+
+const SelectWorkspace = z.object({
+  workspaceId: requiredString('Workspace ID is required')
+})
+
 const SearchIssues = z.object({
   query: requiredString('Missing query'),
-  limit: OptionalFiniteNumber
+  limit: OptionalFiniteNumber,
+  workspaceId: OptionalString
 })
 
 const ListIssues = z
   .object({
     filter: z.enum(VALID_FILTERS).optional(),
-    limit: OptionalFiniteNumber
+    limit: OptionalFiniteNumber,
+    workspaceId: OptionalString
   })
   .optional()
 
 const CreateIssue = z.object({
   teamId: requiredString('Team ID is required'),
   title: requiredString('Title is required'),
-  description: OptionalString
+  description: OptionalString,
+  workspaceId: OptionalString
 })
 
 const IssueId = z.object({
-  id: requiredString('Issue ID is required')
+  id: requiredString('Issue ID is required'),
+  workspaceId: OptionalString
 })
 
 const IssueComment = z.object({
   issueId: requiredString('Issue ID is required'),
-  body: requiredString('Comment body is required')
+  body: requiredString('Comment body is required'),
+  workspaceId: OptionalString
 })
 
 const TeamId = z.object({
-  teamId: requiredString('Team ID is required')
+  teamId: requiredString('Team ID is required'),
+  workspaceId: OptionalString
 })
 
 const IssueUpdate = z.object({
   id: requiredString('Issue ID is required'),
+  workspaceId: OptionalString,
   updates: z.object({
     stateId: OptionalString,
     title: OptionalString,
@@ -58,8 +75,13 @@ export const LINEAR_METHODS: RpcMethod[] = [
   }),
   defineMethod({
     name: 'linear.disconnect',
-    params: null,
-    handler: async (_params, { runtime }) => runtime.linearDisconnect()
+    params: WorkspaceSelection,
+    handler: async (params, { runtime }) => runtime.linearDisconnect(params?.workspaceId)
+  }),
+  defineMethod({
+    name: 'linear.selectWorkspace',
+    params: SelectWorkspace,
+    handler: async (params, { runtime }) => runtime.linearSelectWorkspace(params.workspaceId.trim())
   }),
   defineMethod({
     name: 'linear.status',
@@ -68,18 +90,20 @@ export const LINEAR_METHODS: RpcMethod[] = [
   }),
   defineMethod({
     name: 'linear.testConnection',
-    params: null,
-    handler: async (_params, { runtime }) => runtime.linearTestConnection()
+    params: WorkspaceSelection,
+    handler: async (params, { runtime }) => runtime.linearTestConnection(params?.workspaceId)
   }),
   defineMethod({
     name: 'linear.searchIssues',
     params: SearchIssues,
-    handler: async (params, { runtime }) => runtime.linearSearchIssues(params.query, params.limit)
+    handler: async (params, { runtime }) =>
+      runtime.linearSearchIssues(params.query, params.limit, params.workspaceId)
   }),
   defineMethod({
     name: 'linear.listIssues',
     params: ListIssues,
-    handler: async (params, { runtime }) => runtime.linearListIssues(params?.filter, params?.limit)
+    handler: async (params, { runtime }) =>
+      runtime.linearListIssues(params?.filter, params?.limit, params?.workspaceId)
   }),
   defineMethod({
     name: 'linear.createIssue',
@@ -88,49 +112,58 @@ export const LINEAR_METHODS: RpcMethod[] = [
       runtime.linearCreateIssue(
         params.teamId.trim(),
         params.title.trim(),
-        params.description?.trim() || undefined
+        params.description?.trim() || undefined,
+        params.workspaceId
       )
   }),
   defineMethod({
     name: 'linear.getIssue',
     params: IssueId,
-    handler: async (params, { runtime }) => runtime.linearGetIssue(params.id.trim())
+    handler: async (params, { runtime }) =>
+      runtime.linearGetIssue(params.id.trim(), params.workspaceId)
   }),
   defineMethod({
     name: 'linear.updateIssue',
     params: IssueUpdate,
     handler: async (params, { runtime }) =>
-      runtime.linearUpdateIssue(params.id.trim(), params.updates)
+      runtime.linearUpdateIssue(params.id.trim(), params.updates, params.workspaceId)
   }),
   defineMethod({
     name: 'linear.addIssueComment',
     params: IssueComment,
     handler: async (params, { runtime }) =>
-      runtime.linearAddIssueComment(params.issueId.trim(), params.body.trim())
+      runtime.linearAddIssueComment(params.issueId.trim(), params.body.trim(), params.workspaceId)
   }),
   defineMethod({
     name: 'linear.issueComments',
-    params: z.object({ issueId: requiredString('Issue ID is required') }),
-    handler: async (params, { runtime }) => runtime.linearIssueComments(params.issueId.trim())
+    params: z.object({
+      issueId: requiredString('Issue ID is required'),
+      workspaceId: OptionalString
+    }),
+    handler: async (params, { runtime }) =>
+      runtime.linearIssueComments(params.issueId.trim(), params.workspaceId)
   }),
   defineMethod({
     name: 'linear.listTeams',
-    params: null,
-    handler: async (_params, { runtime }) => runtime.linearListTeams()
+    params: WorkspaceSelection,
+    handler: async (params, { runtime }) => runtime.linearListTeams(params?.workspaceId)
   }),
   defineMethod({
     name: 'linear.teamStates',
     params: TeamId,
-    handler: async (params, { runtime }) => runtime.linearTeamStates(params.teamId.trim())
+    handler: async (params, { runtime }) =>
+      runtime.linearTeamStates(params.teamId.trim(), params.workspaceId)
   }),
   defineMethod({
     name: 'linear.teamLabels',
     params: TeamId,
-    handler: async (params, { runtime }) => runtime.linearTeamLabels(params.teamId.trim())
+    handler: async (params, { runtime }) =>
+      runtime.linearTeamLabels(params.teamId.trim(), params.workspaceId)
   }),
   defineMethod({
     name: 'linear.teamMembers',
     params: TeamId,
-    handler: async (params, { runtime }) => runtime.linearTeamMembers(params.teamId.trim())
+    handler: async (params, { runtime }) =>
+      runtime.linearTeamMembers(params.teamId.trim(), params.workspaceId)
   })
 ]
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index a874def4fca..5e21c47a89f 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -47,6 +47,7 @@ import type {
   IssueInfo,
   LinearViewer,
   LinearConnectionStatus,
+  LinearWorkspaceSelection,
   LinearIssue,
   LinearIssueUpdate,
   LinearComment,
@@ -867,35 +868,48 @@ export type PreloadApi = {
     connect: (args: {
       apiKey: string
     }) => Promise<{ ok: true; viewer: LinearViewer } | { ok: false; error: string }>
-    disconnect: () => Promise<void>
+    disconnect: (args?: { workspaceId?: string }) => Promise<void>
+    selectWorkspace: (args: {
+      workspaceId: LinearWorkspaceSelection
+    }) => Promise<LinearConnectionStatus>
     status: () => Promise<LinearConnectionStatus>
-    testConnection: () => Promise<{ ok: true; viewer: LinearViewer } | { ok: false; error: string }>
-    searchIssues: (args: { query: string; limit?: number }) => Promise<LinearIssue[]>
+    testConnection: (args?: {
+      workspaceId?: string
+    }) => Promise<{ ok: true; viewer: LinearViewer } | { ok: false; error: string }>
+    searchIssues: (args: {
+      query: string
+      limit?: number
+      workspaceId?: LinearWorkspaceSelection
+    }) => Promise<LinearIssue[]>
     listIssues: (args?: {
       filter?: 'assigned' | 'created' | 'all' | 'completed'
       limit?: number
+      workspaceId?: LinearWorkspaceSelection
     }) => Promise<LinearIssue[]>
     createIssue: (args: {
       teamId: string
       title: string
       description?: string
+      workspaceId?: string
     }) => Promise<
       { ok: true; id: string; identifier: string; url: string } | { ok: false; error: string }
     >
-    getIssue: (args: { id: string }) => Promise<LinearIssue | null>
+    getIssue: (args: { id: string; workspaceId?: string }) => Promise<LinearIssue | null>
     updateIssue: (args: {
       id: string
       updates: LinearIssueUpdate
+      workspaceId?: string
     }) => Promise<{ ok: true } | { ok: false; error: string }>
     addIssueComment: (args: {
       issueId: string
       body: string
+      workspaceId?: string
     }) => Promise<{ ok: true; id: string } | { ok: false; error: string }>
-    issueComments: (args: { issueId: string }) => Promise<LinearComment[]>
-    listTeams: () => Promise<LinearTeam[]>
-    teamStates: (args: { teamId: string }) => Promise<LinearWorkflowState[]>
-    teamLabels: (args: { teamId: string }) => Promise<LinearLabel[]>
-    teamMembers: (args: { teamId: string }) => Promise<LinearMember[]>
+    issueComments: (args: { issueId: string; workspaceId?: string }) => Promise<LinearComment[]>
+    listTeams: (args?: { workspaceId?: LinearWorkspaceSelection }) => Promise<LinearTeam[]>
+    teamStates: (args: { teamId: string; workspaceId?: string }) => Promise<LinearWorkflowState[]>
+    teamLabels: (args: { teamId: string; workspaceId?: string }) => Promise<LinearLabel[]>
+    teamMembers: (args: { teamId: string; workspaceId?: string }) => Promise<LinearMember[]>
   }
   starNag: {
     onShow: (callback: () => void) => () => void
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 014996c28de..764714f28cb 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -917,56 +917,70 @@ const api = {
     }): Promise<{ ok: true; viewer: unknown } | { ok: false; error: string }> =>
       ipcRenderer.invoke('linear:connect', args),
 
-    disconnect: (): Promise<void> => ipcRenderer.invoke('linear:disconnect'),
+    disconnect: (args?: { workspaceId?: string }): Promise<void> =>
+      ipcRenderer.invoke('linear:disconnect', args),
+
+    selectWorkspace: (args: { workspaceId: string }): Promise<unknown> =>
+      ipcRenderer.invoke('linear:selectWorkspace', args),
 
     status: (): Promise<unknown> => ipcRenderer.invoke('linear:status'),
 
-    testConnection: (): Promise<{ ok: true; viewer: unknown } | { ok: false; error: string }> =>
-      ipcRenderer.invoke('linear:testConnection'),
+    testConnection: (args?: {
+      workspaceId?: string
+    }): Promise<{ ok: true; viewer: unknown } | { ok: false; error: string }> =>
+      ipcRenderer.invoke('linear:testConnection', args),
 
-    searchIssues: (args: { query: string; limit?: number }): Promise<unknown[]> =>
-      ipcRenderer.invoke('linear:searchIssues', args),
+    searchIssues: (args: {
+      query: string
+      limit?: number
+      workspaceId?: string
+    }): Promise<unknown[]> => ipcRenderer.invoke('linear:searchIssues', args),
 
     listIssues: (args?: {
       filter?: 'assigned' | 'created' | 'all' | 'completed'
       limit?: number
+      workspaceId?: string
     }): Promise<unknown[]> => ipcRenderer.invoke('linear:listIssues', args),
 
     createIssue: (args: {
       teamId: string
       title: string
       description?: string
+      workspaceId?: string
     }): Promise<
       { ok: true; id: string; identifier: string; url: string } | { ok: false; error: string }
     > => ipcRenderer.invoke('linear:createIssue', args),
 
-    getIssue: (args: { id: string }): Promise<unknown> =>
+    getIssue: (args: { id: string; workspaceId?: string }): Promise<unknown> =>
       ipcRenderer.invoke('linear:getIssue', args),
 
     updateIssue: (args: {
       id: string
       updates: unknown
+      workspaceId?: string
     }): Promise<{ ok: true } | { ok: false; error: string }> =>
       ipcRenderer.invoke('linear:updateIssue', args),
 
     addIssueComment: (args: {
       issueId: string
       body: string
+      workspaceId?: string
     }): Promise<{ ok: true; id: string } | { ok: false; error: string }> =>
       ipcRenderer.invoke('linear:addIssueComment', args),
 
-    issueComments: (args: { issueId: string }): Promise<unknown[]> =>
+    issueComments: (args: { issueId: string; workspaceId?: string }): Promise<unknown[]> =>
       ipcRenderer.invoke('linear:issueComments', args),
 
-    listTeams: (): Promise<unknown[]> => ipcRenderer.invoke('linear:listTeams'),
+    listTeams: (args?: { workspaceId?: string }): Promise<unknown[]> =>
+      ipcRenderer.invoke('linear:listTeams', args),
 
-    teamStates: (args: { teamId: string }): Promise<unknown[]> =>
+    teamStates: (args: { teamId: string; workspaceId?: string }): Promise<unknown[]> =>
       ipcRenderer.invoke('linear:teamStates', args),
 
-    teamLabels: (args: { teamId: string }): Promise<unknown[]> =>
+    teamLabels: (args: { teamId: string; workspaceId?: string }): Promise<unknown[]> =>
       ipcRenderer.invoke('linear:teamLabels', args),
 
-    teamMembers: (args: { teamId: string }): Promise<unknown[]> =>
+    teamMembers: (args: { teamId: string; workspaceId?: string }): Promise<unknown[]> =>
       ipcRenderer.invoke('linear:teamMembers', args)
   },
 
diff --git a/src/renderer/src/components/LinearItemDrawer.tsx b/src/renderer/src/components/LinearItemDrawer.tsx
index 38fa892267c..7f55e78f572 100644
--- a/src/renderer/src/components/LinearItemDrawer.tsx
+++ b/src/renderer/src/components/LinearItemDrawer.tsx
@@ -106,9 +106,9 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
   } = editState
 
   const teamId = issue.team?.id || null
-  const states = useTeamStates(teamId, settings)
-  const labels = useTeamLabels(teamId, settings)
-  const members = useTeamMembers(teamId, settings)
+  const states = useTeamStates(teamId, settings, issue.workspaceId)
+  const labels = useTeamLabels(teamId, settings, issue.workspaceId)
+  const members = useTeamMembers(teamId, settings, issue.workspaceId)
 
   const handleStateChange = useCallback(
     (stateId: string) => {
@@ -121,7 +121,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
       const stateValue = { name: newState.name, type: newState.type, color: newState.color }
 
       run('state', {
-        mutate: () => linearUpdateIssue(settings, issue.id, { stateId }),
+        mutate: () => linearUpdateIssue(settings, issue.id, { stateId }, issue.workspaceId),
         onOptimistic: () => {
           onEditStateChange({ state: stateValue })
           patchLinearIssue(issue.id, { state: stateValue })
@@ -133,7 +133,16 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         onError: (err) => toast.error(err)
       })
     },
-    [issue.id, localState, settings, states.data, patchLinearIssue, run, onEditStateChange]
+    [
+      issue.id,
+      issue.workspaceId,
+      localState,
+      settings,
+      states.data,
+      patchLinearIssue,
+      run,
+      onEditStateChange
+    ]
   )
 
   const handlePriorityChange = useCallback(
@@ -141,7 +150,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
       const priority = parseInt(value, 10)
       const prevPriority = localPriority
       run('priority', {
-        mutate: () => linearUpdateIssue(settings, issue.id, { priority }),
+        mutate: () => linearUpdateIssue(settings, issue.id, { priority }, issue.workspaceId),
         onOptimistic: () => {
           onEditStateChange({ priority })
           patchLinearIssue(issue.id, { priority })
@@ -153,7 +162,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         onError: (err) => toast.error(err)
       })
     },
-    [issue.id, localPriority, settings, patchLinearIssue, run, onEditStateChange]
+    [issue.id, issue.workspaceId, localPriority, settings, patchLinearIssue, run, onEditStateChange]
   )
 
   const handleAssigneeChange = useCallback(
@@ -165,7 +174,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         ? { id: member.id, displayName: member.displayName, avatarUrl: member.avatarUrl }
         : undefined
       run('assignee', {
-        mutate: () => linearUpdateIssue(settings, issue.id, { assigneeId }),
+        mutate: () => linearUpdateIssue(settings, issue.id, { assigneeId }, issue.workspaceId),
         onOptimistic: () => {
           onEditStateChange({ assignee: newAssignee })
           patchLinearIssue(issue.id, { assignee: newAssignee })
@@ -177,7 +186,16 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         onError: (err) => toast.error(err)
       })
     },
-    [issue.id, localAssignee, settings, members.data, patchLinearIssue, run, onEditStateChange]
+    [
+      issue.id,
+      issue.workspaceId,
+      localAssignee,
+      settings,
+      members.data,
+      patchLinearIssue,
+      run,
+      onEditStateChange
+    ]
   )
 
   const handleLabelToggle = useCallback(
@@ -193,7 +211,8 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
         .filter((n): n is string => !!n)
 
       run('labels', {
-        mutate: () => linearUpdateIssue(settings, issue.id, { labelIds: newLabelIds }),
+        mutate: () =>
+          linearUpdateIssue(settings, issue.id, { labelIds: newLabelIds }, issue.workspaceId),
         onOptimistic: () => {
           onEditStateChange({ labelIds: newLabelIds, labels: newLabels })
           patchLinearIssue(issue.id, { labelIds: newLabelIds, labels: newLabels })
@@ -207,6 +226,7 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
     },
     [
       issue.id,
+      issue.workspaceId,
       localLabelIds,
       localLabels,
       settings,
@@ -417,9 +437,11 @@ type LocalComment = { id: string; body: string; createdAt: string }
 
 function CommentFooter({
   issueId,
+  workspaceId,
   onCommentAdded
 }: {
   issueId: string
+  workspaceId?: string | null
   onCommentAdded: (comment: LocalComment) => void
 }): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
@@ -443,7 +465,7 @@ function CommentFooter({
     }
     setSubmitting(true)
     try {
-      const result = await linearAddIssueComment(settings, issueId, trimmed)
+      const result = await linearAddIssueComment(settings, issueId, trimmed, workspaceId)
       const typed = result as { ok: boolean; id?: string; error?: string }
       if (typed.ok) {
         setBody('')
@@ -460,7 +482,7 @@ function CommentFooter({
     } finally {
       setSubmitting(false)
     }
-  }, [body, issueId, onCommentAdded, settings])
+  }, [body, issueId, onCommentAdded, settings, workspaceId])
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -553,7 +575,7 @@ export default function LinearItemDrawer({
 
     // Why: fetch issue and comments independently so a transient comments
     // failure doesn't discard the successfully-fetched issue data.
-    linearGetIssue(settings, issue.id)
+    linearGetIssue(settings, issue.id, issue.workspaceId)
       .then((issueResult) => {
         if (requestId !== requestIdRef.current) {
           return
@@ -570,7 +592,7 @@ export default function LinearItemDrawer({
       })
       .catch(() => {})
 
-    linearIssueComments(settings, issue.id)
+    linearIssueComments(settings, issue.id, issue.workspaceId)
       .then((commentsResult) => {
         if (requestId !== requestIdRef.current) {
           return
@@ -595,7 +617,7 @@ export default function LinearItemDrawer({
         }
       })
     // oxlint-disable-next-line react-hooks/exhaustive-deps
-  }, [issue?.id, settings])
+  }, [issue?.id, issue?.workspaceId, settings])
 
   // Why: same pointer-events fix as GitHubItemDialog — Radix may leave
   // pointer-events: none on body when overlays transition.
@@ -667,6 +689,7 @@ export default function LinearItemDrawer({
                     {displayed.title}
                   </h2>
                   <div className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-[11px] text-muted-foreground">
+                    {displayed.workspaceName && <span>{displayed.workspaceName}</span>}
                     {displayed.team?.name && <span>{displayed.team.name}</span>}
                     <span>· {formatRelativeTime(displayed.updatedAt)}</span>
                   </div>
@@ -779,7 +802,11 @@ export default function LinearItemDrawer({
             </div>
 
             {/* Comment footer + Start workspace */}
-            <CommentFooter issueId={displayed.id} onCommentAdded={handleCommentAdded} />
+            <CommentFooter
+              issueId={displayed.id}
+              workspaceId={displayed.workspaceId}
+              onCommentAdded={handleCommentAdded}
+            />
             <div className="flex-none border-t border-border/60 bg-background/40 px-4 py-3">
               <Button
                 onClick={() => onUse(displayed)}
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 3bbc8a03af0..7abc2f431ad 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -86,6 +86,7 @@ import type {
   GitLabTodo,
   GitLabWorkItem,
   LinearIssue,
+  LinearTeam,
   Repo,
   TaskViewPresetId
 } from '../../../shared/types'
@@ -376,7 +377,7 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
   }, [issue.state])
 
   const teamId = issue.team?.id || null
-  const states = useTeamStates(teamId, settings)
+  const states = useTeamStates(teamId, settings, issue.workspaceId)
 
   const handleStateChange = useCallback(
     (stateId: string) => {
@@ -391,7 +392,7 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
 
       setLocalState(stateValue)
       patchLinearIssue(issue.id, { state: stateValue })
-      linearUpdateIssue(settings, issue.id, { stateId })
+      linearUpdateIssue(settings, issue.id, { stateId }, issue.workspaceId)
         .then((result) => {
           if (reqId !== reqRef.current) {
             return
@@ -402,7 +403,7 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
             patchLinearIssue(issue.id, { state: issue.state })
             toast.error(typed.error ?? 'Failed to update status')
           } else {
-            fetchLinearIssue(issue.id)
+            fetchLinearIssue(issue.id, issue.workspaceId)
           }
         })
         .catch(() => {
@@ -414,7 +415,15 @@ function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element
           toast.error('Failed to update status')
         })
     },
-    [issue.id, issue.state, settings, states.data, patchLinearIssue, fetchLinearIssue]
+    [
+      issue.id,
+      issue.state,
+      issue.workspaceId,
+      settings,
+      states.data,
+      patchLinearIssue,
+      fetchLinearIssue
+    ]
   )
 
   const currentStateId = states.data.find(
@@ -494,7 +503,7 @@ function LinearPriorityCell({ issue }: { issue: LinearIssue }): React.JSX.Elemen
       setLocalPriority(priority)
       patchLinearIssue(issue.id, { priority })
       setPending(true)
-      linearUpdateIssue(settings, issue.id, { priority })
+      linearUpdateIssue(settings, issue.id, { priority }, issue.workspaceId)
         .then((result) => {
           if (reqId !== reqRef.current) {
             return
@@ -505,7 +514,7 @@ function LinearPriorityCell({ issue }: { issue: LinearIssue }): React.JSX.Elemen
             patchLinearIssue(issue.id, { priority: issue.priority })
             toast.error(typed.error ?? 'Failed to update priority')
           } else {
-            fetchLinearIssue(issue.id)
+            fetchLinearIssue(issue.id, issue.workspaceId)
           }
         })
         .catch(() => {
@@ -523,7 +532,15 @@ function LinearPriorityCell({ issue }: { issue: LinearIssue }): React.JSX.Elemen
           setPending(false)
         })
     },
-    [issue.id, issue.priority, localPriority, settings, patchLinearIssue, fetchLinearIssue]
+    [
+      issue.id,
+      issue.priority,
+      issue.workspaceId,
+      localPriority,
+      settings,
+      patchLinearIssue,
+      fetchLinearIssue
+    ]
   )
 
   const [open, setOpen] = useState(false)
@@ -717,6 +734,7 @@ export default function TaskPage(): React.JSX.Element {
   const linearStatus = useAppStore((s) => s.linearStatus)
   const linearStatusChecked = useAppStore((s) => s.linearStatusChecked)
   const connectLinear = useAppStore((s) => s.connectLinear)
+  const selectLinearWorkspace = useAppStore((s) => s.selectLinearWorkspace)
   const searchLinearIssues = useAppStore((s) => s.searchLinearIssues)
   const listLinearIssues = useAppStore((s) => s.listLinearIssues)
   const checkLinearConnection = useAppStore((s) => s.checkLinearConnection)
@@ -790,6 +808,12 @@ export default function TaskPage(): React.JSX.Element {
   // optimistic stub) need *a* repo. First selected is used as the default;
   // cross-repo dialogs still let the user override per-action.
   const primaryRepo = selectedRepos[0] ?? null
+  const linearWorkspaces = linearStatus.workspaces ?? []
+  const selectedLinearWorkspaceId =
+    linearStatus.selectedWorkspaceId ??
+    linearStatus.activeWorkspaceId ??
+    linearWorkspaces[0]?.id ??
+    null
 
   // Why: seed the preset + query from the user's saved default synchronously
   // so the first fetch effect issues exactly one request keyed to the final
@@ -1088,24 +1112,36 @@ export default function TaskPage(): React.JSX.Element {
   // Why: fetch the full team list from the Linear API so the selector shows
   // all teams the user belongs to, not just teams with issues in the current
   // fetch window. Fetched once when the Linear tab is active and connected.
-  const [availableTeams, setAvailableTeams] = useState<{ id: string; name: string; key: string }[]>(
-    []
-  )
+  const [availableTeams, setAvailableTeams] = useState<LinearTeam[]>([])
 
   useEffect(() => {
     if (!taskResumeApplied) {
       return
     }
     if (taskSource !== 'linear' || !linearStatus.connected) {
+      setAvailableTeams([])
       return
     }
-    void linearListTeams(settings)
-      .then(setAvailableTeams)
-      .catch(() => {
-        console.warn('[TaskPage] Failed to fetch Linear teams')
+    let cancelled = false
+    // Why: workspace switches must not leave the prior workspace's teams
+    // available for new-issue creation while the replacement fetch is pending.
+    setAvailableTeams([])
+    void linearListTeams(settings, selectedLinearWorkspaceId)
+      .then((teams) => {
+        if (!cancelled) {
+          setAvailableTeams(teams)
+        }
       })
+      .catch(() => {
+        if (!cancelled) {
+          console.warn('[TaskPage] Failed to fetch Linear teams')
+        }
+      })
+    return () => {
+      cancelled = true
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [settings, taskSource, linearStatus.connected, taskResumeApplied])
+  }, [settings, taskSource, linearStatus.connected, selectedLinearWorkspaceId, taskResumeApplied])
 
   // Why: stable key for `selectedRepos` so the GitLab fetch effect below
   // doesn't re-run on every parent re-render just because the array
@@ -1741,7 +1777,8 @@ export default function TaskPage(): React.JSX.Element {
       const result = await linearCreateIssue(settings, {
         teamId: newLinearIssueTargetTeam.id,
         title,
-        description: newLinearIssueBody || undefined
+        description: newLinearIssueBody || undefined,
+        workspaceId: newLinearIssueTargetTeam.workspaceId
       })
       if (!result.ok) {
         toast.error(result.error || 'Failed to create issue.')
@@ -1762,7 +1799,7 @@ export default function TaskPage(): React.JSX.Element {
 
       // Why: auto-open the new issue in the side drawer so the user sees
       // exactly what was filed, mirroring the GitHub create-issue flow.
-      void linearGetIssue(settings, result.id)
+      void linearGetIssue(settings, result.id, newLinearIssueTargetTeam.workspaceId)
         .then((full) => {
           if (full) {
             setDrawerLinearIssue(full)
@@ -1911,6 +1948,7 @@ export default function TaskPage(): React.JSX.Element {
   }, [
     taskSource,
     linearStatus.connected,
+    selectedLinearWorkspaceId,
     appliedLinearSearch,
     activeLinearPreset,
     linearRefreshNonce,
@@ -2041,27 +2079,55 @@ export default function TaskPage(): React.JSX.Element {
                       )
                     })}
                   </div>
-                  {taskSource === 'linear' && availableTeams.length > 0 ? (
-                    <div className="w-[200px]">
-                      <TeamMultiCombobox
-                        teams={availableTeams}
-                        selected={linearTeamSelection}
-                        onChange={(next) => {
-                          setLinearTeamSelection(next)
-                          void updateSettings({ defaultLinearTeamSelection: [...next] }).catch(
-                            () => {
-                              toast.error('Failed to save team selection.')
-                            }
-                          )
-                        }}
-                        onSelectAll={() => {
-                          setLinearTeamSelection(new Set(availableTeams.map((t) => t.id)))
-                          void updateSettings({ defaultLinearTeamSelection: null }).catch(() => {
-                            toast.error('Failed to save team selection.')
-                          })
-                        }}
-                        triggerClassName="h-8 w-full rounded-md border border-border/50 bg-muted/50 px-2 text-xs font-medium shadow-sm transition hover:bg-muted/50 focus:ring-2 focus:ring-ring/20 focus:outline-none"
-                      />
+                  {taskSource === 'linear' && linearStatus.connected ? (
+                    <div className="flex items-center gap-2">
+                      {linearWorkspaces.length > 1 ? (
+                        <Select
+                          value={selectedLinearWorkspaceId ?? undefined}
+                          onValueChange={(value) => {
+                            void selectLinearWorkspace(value).catch(() => {
+                              toast.error('Failed to switch Linear workspace.')
+                            })
+                          }}
+                        >
+                          <SelectTrigger className="h-8 w-[200px] rounded-md border-border/50 bg-muted/50 text-xs font-medium shadow-sm">
+                            <SelectValue />
+                          </SelectTrigger>
+                          <SelectContent>
+                            <SelectItem value="all">All workspaces</SelectItem>
+                            {linearWorkspaces.map((workspace) => (
+                              <SelectItem key={workspace.id} value={workspace.id}>
+                                {workspace.organizationName}
+                              </SelectItem>
+                            ))}
+                          </SelectContent>
+                        </Select>
+                      ) : null}
+                      {availableTeams.length > 0 ? (
+                        <div className="w-[200px]">
+                          <TeamMultiCombobox
+                            teams={availableTeams}
+                            selected={linearTeamSelection}
+                            onChange={(next) => {
+                              setLinearTeamSelection(next)
+                              void updateSettings({ defaultLinearTeamSelection: [...next] }).catch(
+                                () => {
+                                  toast.error('Failed to save team selection.')
+                                }
+                              )
+                            }}
+                            onSelectAll={() => {
+                              setLinearTeamSelection(new Set(availableTeams.map((t) => t.id)))
+                              void updateSettings({ defaultLinearTeamSelection: null }).catch(
+                                () => {
+                                  toast.error('Failed to save team selection.')
+                                }
+                              )
+                            }}
+                            triggerClassName="h-8 w-full rounded-md border border-border/50 bg-muted/50 px-2 text-xs font-medium shadow-sm transition hover:bg-muted/50 focus:ring-2 focus:ring-ring/20 focus:outline-none"
+                          />
+                        </div>
+                      ) : null}
                     </div>
                   ) : null}
                 </div>
@@ -3119,6 +3185,9 @@ export default function TaskPage(): React.JSX.Element {
                           {issue.title}
                         </h3>
                         <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
+                          {selectedLinearWorkspaceId === 'all' && issue.workspaceName ? (
+                            <span>{issue.workspaceName}</span>
+                          ) : null}
                           {issue.assignee ? <span>{issue.assignee.displayName}</span> : null}
                           {issue.labels.slice(0, 3).map((label) => (
                             <span
@@ -3384,7 +3453,11 @@ export default function TaskPage(): React.JSX.Element {
             <DialogDescription>
               {availableTeams.length > 1
                 ? 'Creates a new issue in the selected team.'
-                : `Creates a new issue in ${newLinearIssueTargetTeam?.name ?? 'your team'}.`}
+                : `Creates a new issue in ${
+                    newLinearIssueTargetTeam?.workspaceName
+                      ? `${newLinearIssueTargetTeam.workspaceName} / `
+                      : ''
+                  }${newLinearIssueTargetTeam?.name ?? 'your team'}.`}
             </DialogDescription>
           </DialogHeader>
           <div className="flex flex-col gap-3">
@@ -3402,6 +3475,9 @@ export default function TaskPage(): React.JSX.Element {
                   <SelectContent>
                     {availableTeams.map((t) => (
                       <SelectItem key={t.id} value={t.id}>
+                        {selectedLinearWorkspaceId === 'all' && t.workspaceName
+                          ? `${t.workspaceName} · `
+                          : ''}
                         {t.key} — {t.name}
                       </SelectItem>
                     ))}
@@ -3529,10 +3605,10 @@ export default function TaskPage(): React.JSX.Element {
           }}
         >
           <DialogHeader className="gap-3">
-            <DialogTitle className="leading-tight">Connect Linear</DialogTitle>
+            <DialogTitle className="leading-tight">Connect Linear workspace</DialogTitle>
             <DialogDescription>
               Paste a <strong className="font-semibold text-foreground">Personal API key</strong> to
-              browse your assigned issues.
+              browse issues from that workspace.
             </DialogDescription>
           </DialogHeader>
           <div className="flex flex-col gap-3">
diff --git a/src/renderer/src/components/settings/IntegrationsPane.tsx b/src/renderer/src/components/settings/IntegrationsPane.tsx
index aa69b840b7b..9847c21163a 100644
--- a/src/renderer/src/components/settings/IntegrationsPane.tsx
+++ b/src/renderer/src/components/settings/IntegrationsPane.tsx
@@ -94,8 +94,10 @@ export function IntegrationsPane(): React.JSX.Element {
   const linearStatus = useAppStore((s) => s.linearStatus)
   const connectLinear = useAppStore((s) => s.connectLinear)
   const disconnectLinear = useAppStore((s) => s.disconnectLinear)
+  const disconnectLinearWorkspace = useAppStore((s) => s.disconnectLinearWorkspace)
   const checkLinearConnection = useAppStore((s) => s.checkLinearConnection)
   const testLinearConnection = useAppStore((s) => s.testLinearConnection)
+  const linearWorkspaces = linearStatus.workspaces ?? []
 
   const [ghStatus, setGhStatus] = useState<GhStatus>('checking')
   const [glabStatus, setGlabStatus] = useState<GlabStatus>('checking')
@@ -110,10 +112,10 @@ export function IntegrationsPane(): React.JSX.Element {
     'idle'
   )
   const [linearConnectError, setLinearConnectError] = useState<string | null>(null)
-  const [linearTestState, setLinearTestState] = useState<'idle' | 'testing' | 'ok' | 'error'>(
-    'idle'
-  )
-  const [linearTestError, setLinearTestError] = useState<string | null>(null)
+  const [linearTestingWorkspaceId, setLinearTestingWorkspaceId] = useState<string | null>(null)
+  const [linearTestResultByWorkspace, setLinearTestResultByWorkspace] = useState<
+    Record<string, { state: 'ok' | 'error'; error?: string }>
+  >({})
 
   useEffect(() => {
     void checkLinearConnection()
@@ -165,6 +167,7 @@ export function IntegrationsPane(): React.JSX.Element {
         setLinearApiKeyDraft('')
         setLinearConnectState('idle')
         setLinearDialogOpen(false)
+        setLinearTestResultByWorkspace({})
       } else {
         setLinearConnectState('error')
         setLinearConnectError(result.error)
@@ -175,28 +178,37 @@ export function IntegrationsPane(): React.JSX.Element {
     }
   }
 
-  const handleLinearDisconnect = async (): Promise<void> => {
-    await disconnectLinear()
+  const handleLinearDisconnect = async (workspaceId?: string): Promise<void> => {
+    await (workspaceId ? disconnectLinearWorkspace(workspaceId) : disconnectLinear())
     setLinearConnectState('idle')
     setLinearConnectError(null)
-    setLinearTestState('idle')
-    setLinearTestError(null)
+    setLinearTestResultByWorkspace({})
   }
 
   // Why: explicit user-triggered verification. This is the *only* path in
   // settings that decrypts the stored API key, so the macOS Keychain prompt
   // (if the app signature has changed since the item was stored) only
   // appears when the user clicks Test — not just for opening Settings.
-  const handleLinearTest = async (): Promise<void> => {
-    setLinearTestState('testing')
-    setLinearTestError(null)
-    const result = await testLinearConnection()
+  const handleLinearTest = async (workspaceId: string): Promise<void> => {
+    setLinearTestingWorkspaceId(workspaceId)
+    setLinearTestResultByWorkspace((prev) => {
+      const next = { ...prev }
+      delete next[workspaceId]
+      return next
+    })
+    const result = await testLinearConnection(workspaceId)
     if (result.ok) {
-      setLinearTestState('ok')
+      setLinearTestResultByWorkspace((prev) => ({
+        ...prev,
+        [workspaceId]: { state: 'ok' }
+      }))
     } else {
-      setLinearTestState('error')
-      setLinearTestError(result.error)
+      setLinearTestResultByWorkspace((prev) => ({
+        ...prev,
+        [workspaceId]: { state: 'error', error: result.error }
+      }))
     }
+    setLinearTestingWorkspaceId(null)
   }
 
   const handleRefreshGlab = (): void => {
@@ -582,21 +594,15 @@ export function IntegrationsPane(): React.JSX.Element {
             <p className="text-sm font-medium">Linear</p>
             <p className="text-xs text-muted-foreground">
               {linearStatus.connected
-                ? linearStatus.viewer
-                  ? `${linearStatus.viewer.organizationName} · ${linearStatus.viewer.displayName}${linearStatus.viewer.email ? ` · ${linearStatus.viewer.email}` : ''}`
-                  : 'API key saved. Test to verify.'
+                ? `${linearWorkspaces.length} workspace${linearWorkspaces.length === 1 ? '' : 's'} connected`
                 : 'Browse and link issues to workspaces.'}
             </p>
           </div>
           {linearStatus.connected ? (
             <div className="flex shrink-0 items-center gap-1.5">
-              <button
-                onClick={handleLinearDisconnect}
-                aria-label="Disconnect Linear"
-                className="rounded-md p-1 text-muted-foreground/50 transition-colors hover:text-destructive"
-              >
-                <Unlink className="size-3.5" />
-              </button>
+              <Button variant="outline" size="sm" onClick={() => setLinearDialogOpen(true)}>
+                Add workspace
+              </Button>
               <span className="rounded-full border border-emerald-500/30 bg-emerald-500/10 px-2.5 py-1 text-[11px] font-medium text-emerald-700 dark:text-emerald-300">
                 Connected
               </span>
@@ -612,39 +618,64 @@ export function IntegrationsPane(): React.JSX.Element {
         </div>
 
         {linearStatus.connected && (
-          <div className="mt-2.5 flex items-center gap-2">
-            <Button
-              variant="outline"
-              size="sm"
-              onClick={() => void handleLinearTest()}
-              disabled={linearTestState === 'testing'}
-            >
-              {linearTestState === 'testing' ? (
-                <>
-                  <LoaderCircle className="size-3.5 mr-1.5 animate-spin" />
-                  Testing…
-                </>
-              ) : (
-                'Test connection'
-              )}
-            </Button>
-            {linearTestState === 'ok' && (
-              <span className="flex items-center gap-1 text-xs text-emerald-600 dark:text-emerald-400">
-                <CheckCircle2 className="size-3.5" />
-                Verified
-              </span>
-            )}
-            {linearTestState === 'error' && linearTestError && (
-              <span className="flex items-center gap-1 text-xs text-destructive">
-                <AlertCircle className="size-3.5" />
-                {linearTestError}
-              </span>
-            )}
-            {linearTestState === 'idle' && (
-              <span className="text-[11px] text-muted-foreground/70">
-                Verifies your API key against Linear.
-              </span>
-            )}
+          <div className="mt-3 space-y-2">
+            {linearWorkspaces.map((workspace) => {
+              const testResult = linearTestResultByWorkspace[workspace.id]
+              const testing = linearTestingWorkspaceId === workspace.id
+              return (
+                <div
+                  key={workspace.id}
+                  className="flex items-center gap-3 rounded-md border border-border/50 bg-background/60 px-3 py-2"
+                >
+                  <div className="min-w-0 flex-1">
+                    <p className="truncate text-sm font-medium text-foreground">
+                      {workspace.organizationName}
+                    </p>
+                    <p className="truncate text-xs text-muted-foreground">
+                      {workspace.displayName}
+                      {workspace.email ? ` · ${workspace.email}` : ''}
+                    </p>
+                  </div>
+                  {testResult?.state === 'ok' ? (
+                    <span className="flex shrink-0 items-center gap-1 text-xs text-emerald-600 dark:text-emerald-400">
+                      <CheckCircle2 className="size-3.5" />
+                      Verified
+                    </span>
+                  ) : null}
+                  {testResult?.state === 'error' ? (
+                    <span className="flex min-w-0 max-w-[220px] shrink items-center gap-1 truncate text-xs text-destructive">
+                      <AlertCircle className="size-3.5 shrink-0" />
+                      <span className="truncate">{testResult.error}</span>
+                    </span>
+                  ) : null}
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={() => void handleLinearTest(workspace.id)}
+                    disabled={testing}
+                  >
+                    {testing ? (
+                      <>
+                        <LoaderCircle className="size-3.5 mr-1.5 animate-spin" />
+                        Testing…
+                      </>
+                    ) : (
+                      'Test'
+                    )}
+                  </Button>
+                  <button
+                    onClick={() => void handleLinearDisconnect(workspace.id)}
+                    aria-label={`Disconnect ${workspace.organizationName}`}
+                    className="rounded-md p-1 text-muted-foreground/50 transition-colors hover:text-destructive"
+                  >
+                    <Unlink className="size-3.5" />
+                  </button>
+                </div>
+              )
+            })}
+            <p className="text-[11px] text-muted-foreground/70">
+              Each workspace uses its own locally stored API key.
+            </p>
           </div>
         )}
       </div>
@@ -672,10 +703,10 @@ export function IntegrationsPane(): React.JSX.Element {
           }}
         >
           <DialogHeader className="gap-3">
-            <DialogTitle className="leading-tight">Connect Linear</DialogTitle>
+            <DialogTitle className="leading-tight">Connect Linear workspace</DialogTitle>
             <DialogDescription>
               Paste a <strong className="font-semibold text-foreground">Personal API key</strong> to
-              browse your assigned issues.
+              add a workspace to Orca.
             </DialogDescription>
           </DialogHeader>
           <div className="flex flex-col gap-3">
diff --git a/src/renderer/src/hooks/useIssueMetadata.ts b/src/renderer/src/hooks/useIssueMetadata.ts
index deec6cb6a9b..93a1434a5f5 100644
--- a/src/renderer/src/hooks/useIssueMetadata.ts
+++ b/src/renderer/src/hooks/useIssueMetadata.ts
@@ -182,10 +182,14 @@ const linearMemberStore = createMetadataRequestStore<LinearMember[]>()
 
 function linearMetadataCacheKey(
   teamId: string,
-  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined,
+  workspaceId?: string | null
 ): string {
   const target = getActiveRuntimeTarget(settings)
-  return target.kind === 'environment' ? `runtime:${target.environmentId}:${teamId}` : teamId
+  const workspaceKey = workspaceId ?? 'selected'
+  return target.kind === 'environment'
+    ? `runtime:${target.environmentId}:${workspaceKey}:${teamId}`
+    : `${workspaceKey}:${teamId}`
 }
 
 export function clearLinearMetadataCache(): void {
@@ -201,7 +205,8 @@ export function clearGitHubMetadataCache(): void {
 
 export function useTeamStates(
   teamId: string | null,
-  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null,
+  workspaceId?: string | null
 ): MetadataState<LinearWorkflowState[]> {
   const [state, setState] = useState<MetadataState<LinearWorkflowState[]>>({
     data: [],
@@ -215,7 +220,7 @@ export function useTeamStates(
       return
     }
 
-    const cacheKey = linearMetadataCacheKey(teamId, settings)
+    const cacheKey = linearMetadataCacheKey(teamId, settings, workspaceId)
     const cached = getFreshMetadata(linearStateStore, cacheKey)
     if (cached) {
       if (activeKeyRef.current !== cacheKey) {
@@ -234,7 +239,9 @@ export function useTeamStates(
       error: null
     }))
     loadMetadata(linearStateStore, cacheKey, () =>
-      linearTeamStates(settings, teamId).then((states) => states as LinearWorkflowState[])
+      linearTeamStates(settings, teamId, workspaceId).then(
+        (states) => states as LinearWorkflowState[]
+      )
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -253,14 +260,15 @@ export function useTeamStates(
           error: err instanceof Error ? err.message : 'Failed to load states'
         }))
       })
-  }, [settings, teamId])
+  }, [settings, teamId, workspaceId])
 
   return state
 }
 
 export function useTeamLabels(
   teamId: string | null,
-  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null,
+  workspaceId?: string | null
 ): MetadataState<LinearLabel[]> {
   const [state, setState] = useState<MetadataState<LinearLabel[]>>({
     data: [],
@@ -274,7 +282,7 @@ export function useTeamLabels(
       return
     }
 
-    const cacheKey = linearMetadataCacheKey(teamId, settings)
+    const cacheKey = linearMetadataCacheKey(teamId, settings, workspaceId)
     const cached = getFreshMetadata(linearLabelStore, cacheKey)
     if (cached) {
       if (activeKeyRef.current !== cacheKey) {
@@ -293,7 +301,7 @@ export function useTeamLabels(
       error: null
     }))
     loadMetadata(linearLabelStore, cacheKey, () =>
-      linearTeamLabels(settings, teamId).then((labels) => labels as LinearLabel[])
+      linearTeamLabels(settings, teamId, workspaceId).then((labels) => labels as LinearLabel[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -312,14 +320,15 @@ export function useTeamLabels(
           error: err instanceof Error ? err.message : 'Failed to load labels'
         }))
       })
-  }, [settings, teamId])
+  }, [settings, teamId, workspaceId])
 
   return state
 }
 
 export function useTeamMembers(
   teamId: string | null,
-  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null,
+  workspaceId?: string | null
 ): MetadataState<LinearMember[]> {
   const [state, setState] = useState<MetadataState<LinearMember[]>>({
     data: [],
@@ -333,7 +342,7 @@ export function useTeamMembers(
       return
     }
 
-    const cacheKey = linearMetadataCacheKey(teamId, settings)
+    const cacheKey = linearMetadataCacheKey(teamId, settings, workspaceId)
     const cached = getFreshMetadata(linearMemberStore, cacheKey)
     if (cached) {
       if (activeKeyRef.current !== cacheKey) {
@@ -352,7 +361,7 @@ export function useTeamMembers(
       error: null
     }))
     loadMetadata(linearMemberStore, cacheKey, () =>
-      linearTeamMembers(settings, teamId).then((members) => members as LinearMember[])
+      linearTeamMembers(settings, teamId, workspaceId).then((members) => members as LinearMember[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -371,7 +380,7 @@ export function useTeamMembers(
           error: err instanceof Error ? err.message : 'Failed to load members'
         }))
       })
-  }, [settings, teamId])
+  }, [settings, teamId, workspaceId])
 
   return state
 }
diff --git a/src/renderer/src/runtime/runtime-linear-client.test.ts b/src/renderer/src/runtime/runtime-linear-client.test.ts
index a552db06e19..8f4755a98e3 100644
--- a/src/renderer/src/runtime/runtime-linear-client.test.ts
+++ b/src/renderer/src/runtime/runtime-linear-client.test.ts
@@ -3,6 +3,7 @@ import {
   linearCreateIssue,
   linearListTeams,
   linearSearchIssues,
+  linearSelectWorkspace,
   linearStatus,
   linearUpdateIssue
 } from './runtime-linear-client'
@@ -19,6 +20,7 @@ const linearSearchIssuesLocal = vi.fn()
 const linearCreateIssueLocal = vi.fn()
 const linearUpdateIssueLocal = vi.fn()
 const linearListTeamsLocal = vi.fn()
+const linearSelectWorkspaceLocal = vi.fn()
 
 beforeEach(() => {
   clearRuntimeCompatibilityCacheForTests()
@@ -29,6 +31,7 @@ beforeEach(() => {
   linearCreateIssueLocal.mockReset()
   linearUpdateIssueLocal.mockReset()
   linearListTeamsLocal.mockReset()
+  linearSelectWorkspaceLocal.mockReset()
   runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
     return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
   })
@@ -40,7 +43,8 @@ beforeEach(() => {
         searchIssues: linearSearchIssuesLocal,
         createIssue: linearCreateIssueLocal,
         updateIssue: linearUpdateIssueLocal,
-        listTeams: linearListTeamsLocal
+        listTeams: linearListTeamsLocal,
+        selectWorkspace: linearSelectWorkspaceLocal
       }
     }
   })
@@ -60,7 +64,11 @@ describe('runtime linear client', () => {
     ).resolves.toEqual([{ id: 'issue-1' }])
 
     expect(linearStatusLocal).toHaveBeenCalled()
-    expect(linearSearchIssuesLocal).toHaveBeenCalledWith({ query: 'bug', limit: 10 })
+    expect(linearSearchIssuesLocal).toHaveBeenCalledWith({
+      query: 'bug',
+      limit: 10,
+      workspaceId: undefined
+    })
     expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
   })
 
@@ -80,7 +88,7 @@ describe('runtime linear client', () => {
       })
 
     await linearStatus({ activeRuntimeEnvironmentId: 'env-1' })
-    await linearSearchIssues({ activeRuntimeEnvironmentId: 'env-1' }, 'bug', 10)
+    await linearSearchIssues({ activeRuntimeEnvironmentId: 'env-1' }, 'bug', 10, 'all')
 
     expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
       selector: 'env-1',
@@ -91,7 +99,7 @@ describe('runtime linear client', () => {
     expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
       selector: 'env-1',
       method: 'linear.searchIssues',
-      params: { query: 'bug', limit: 10 },
+      params: { query: 'bug', limit: 10, workspaceId: 'all' },
       timeoutMs: 30_000
     })
     expect(linearStatusLocal).not.toHaveBeenCalled()
@@ -118,31 +126,49 @@ describe('runtime linear client', () => {
         result: [{ id: 'team-1' }],
         _meta: { runtimeId: 'runtime-1' }
       })
+      .mockResolvedValueOnce({
+        id: 'rpc-select',
+        ok: true,
+        result: { connected: true, viewer: null },
+        _meta: { runtimeId: 'runtime-1' }
+      })
 
     await linearCreateIssue(
       { activeRuntimeEnvironmentId: 'env-1' },
-      { teamId: 'team-1', title: 'Fix bug' }
+      { teamId: 'team-1', title: 'Fix bug', workspaceId: 'workspace-1' }
     )
-    await linearUpdateIssue({ activeRuntimeEnvironmentId: 'env-1' }, 'issue-1', { priority: 2 })
-    await linearListTeams({ activeRuntimeEnvironmentId: 'env-1' })
+    await linearUpdateIssue(
+      { activeRuntimeEnvironmentId: 'env-1' },
+      'issue-1',
+      { priority: 2 },
+      'workspace-1'
+    )
+    await linearListTeams({ activeRuntimeEnvironmentId: 'env-1' }, 'all')
+    await linearSelectWorkspace({ activeRuntimeEnvironmentId: 'env-1' }, 'workspace-1')
 
     expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
       selector: 'env-1',
       method: 'linear.createIssue',
-      params: { teamId: 'team-1', title: 'Fix bug' },
+      params: { teamId: 'team-1', title: 'Fix bug', workspaceId: 'workspace-1' },
       timeoutMs: 30_000
     })
     expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
       selector: 'env-1',
       method: 'linear.updateIssue',
-      params: { id: 'issue-1', updates: { priority: 2 } },
+      params: { id: 'issue-1', updates: { priority: 2 }, workspaceId: 'workspace-1' },
       timeoutMs: 30_000
     })
     expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
       selector: 'env-1',
       method: 'linear.listTeams',
-      params: undefined,
+      params: { workspaceId: 'all' },
       timeoutMs: 30_000
     })
+    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(4, {
+      selector: 'env-1',
+      method: 'linear.selectWorkspace',
+      params: { workspaceId: 'workspace-1' },
+      timeoutMs: 15_000
+    })
   })
 })
diff --git a/src/renderer/src/runtime/runtime-linear-client.ts b/src/renderer/src/runtime/runtime-linear-client.ts
index 7821a46d8aa..9d1183f7923 100644
--- a/src/renderer/src/runtime/runtime-linear-client.ts
+++ b/src/renderer/src/runtime/runtime-linear-client.ts
@@ -8,6 +8,7 @@ import type {
   LinearMember,
   LinearTeam,
   LinearViewer,
+  LinearWorkspaceSelection,
   LinearWorkflowState
 } from '../../../shared/types'
 import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
@@ -37,14 +38,20 @@ export async function linearStatus(
 }
 
 export async function linearTestConnection(
-  settings: RuntimeLinearSettings
+  settings: RuntimeLinearSettings,
+  workspaceId?: string | null
 ): Promise<LinearConnectResult> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
-    ? callRuntimeRpc<LinearConnectResult>(target, 'linear.testConnection', undefined, {
-        timeoutMs: 30_000
-      })
-    : window.api.linear.testConnection()
+    ? callRuntimeRpc<LinearConnectResult>(
+        target,
+        'linear.testConnection',
+        workspaceId ? { workspaceId } : undefined,
+        {
+          timeoutMs: 30_000
+        }
+      )
+    : window.api.linear.testConnection(workspaceId ? { workspaceId } : undefined)
 }
 
 export async function linearConnect(
@@ -63,51 +70,80 @@ export async function linearConnect(
 }
 
 export async function linearDisconnect(settings: RuntimeLinearSettings): Promise<void> {
+  return linearDisconnectWorkspace(settings)
+}
+
+export async function linearDisconnectWorkspace(
+  settings: RuntimeLinearSettings,
+  workspaceId?: string | null
+): Promise<void> {
   const target = getActiveRuntimeTarget(settings)
   if (target.kind === 'environment') {
-    await callRuntimeRpc<{ ok: true }>(target, 'linear.disconnect', undefined, {
-      timeoutMs: 15_000
-    })
+    await callRuntimeRpc<{ ok: true }>(
+      target,
+      'linear.disconnect',
+      workspaceId ? { workspaceId } : undefined,
+      {
+        timeoutMs: 15_000
+      }
+    )
     return
   }
-  await window.api.linear.disconnect()
+  await window.api.linear.disconnect(workspaceId ? { workspaceId } : undefined)
+}
+
+export async function linearSelectWorkspace(
+  settings: RuntimeLinearSettings,
+  workspaceId: LinearWorkspaceSelection
+): Promise<LinearConnectionStatus> {
+  const target = getActiveRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearConnectionStatus>(
+        target,
+        'linear.selectWorkspace',
+        { workspaceId },
+        { timeoutMs: 15_000 }
+      )
+    : window.api.linear.selectWorkspace({ workspaceId })
 }
 
 export async function linearSearchIssues(
   settings: RuntimeLinearSettings,
   query: string,
-  limit?: number
+  limit?: number,
+  workspaceId?: LinearWorkspaceSelection | null
 ): Promise<LinearIssue[]> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
     ? callRuntimeRpc<LinearIssue[]>(
         target,
         'linear.searchIssues',
-        { query, limit },
+        { query, limit, workspaceId: workspaceId ?? undefined },
         { timeoutMs: 30_000 }
       )
-    : window.api.linear.searchIssues({ query, limit })
+    : window.api.linear.searchIssues({ query, limit, workspaceId: workspaceId ?? undefined })
 }
 
 export async function linearListIssues(
   settings: RuntimeLinearSettings,
   filter?: LinearIssueFilter,
-  limit?: number
+  limit?: number,
+  workspaceId?: LinearWorkspaceSelection | null
 ): Promise<LinearIssue[]> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
     ? callRuntimeRpc<LinearIssue[]>(
         target,
         'linear.listIssues',
-        { filter, limit },
+        { filter, limit, workspaceId: workspaceId ?? undefined },
         { timeoutMs: 30_000 }
       )
-    : window.api.linear.listIssues({ filter, limit })
+    : window.api.linear.listIssues({ filter, limit, workspaceId: workspaceId ?? undefined })
 }
 
 export async function linearCreateIssue(
   settings: RuntimeLinearSettings,
-  args: { teamId: string; title: string; description?: string }
+  args: { teamId: string; title: string; description?: string; workspaceId?: string }
 ): Promise<LinearCreateIssueResult> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
@@ -119,104 +155,129 @@ export async function linearCreateIssue(
 
 export async function linearGetIssue(
   settings: RuntimeLinearSettings,
-  id: string
+  id: string,
+  workspaceId?: string | null
 ): Promise<LinearIssue | null> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
-    ? callRuntimeRpc<LinearIssue | null>(target, 'linear.getIssue', { id }, { timeoutMs: 30_000 })
-    : window.api.linear.getIssue({ id })
+    ? callRuntimeRpc<LinearIssue | null>(
+        target,
+        'linear.getIssue',
+        { id, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.getIssue({ id, workspaceId: workspaceId ?? undefined })
 }
 
 export async function linearUpdateIssue(
   settings: RuntimeLinearSettings,
   id: string,
-  updates: LinearIssueUpdate
+  updates: LinearIssueUpdate,
+  workspaceId?: string | null
 ): Promise<LinearMutationResult> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
     ? callRuntimeRpc<LinearMutationResult>(
         target,
         'linear.updateIssue',
-        { id, updates },
+        { id, updates, workspaceId: workspaceId ?? undefined },
         { timeoutMs: 30_000 }
       )
-    : window.api.linear.updateIssue({ id, updates })
+    : window.api.linear.updateIssue({ id, updates, workspaceId: workspaceId ?? undefined })
 }
 
 export async function linearAddIssueComment(
   settings: RuntimeLinearSettings,
   issueId: string,
-  body: string
+  body: string,
+  workspaceId?: string | null
 ): Promise<LinearCommentResult> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
     ? callRuntimeRpc<LinearCommentResult>(
         target,
         'linear.addIssueComment',
-        { issueId, body },
+        { issueId, body, workspaceId: workspaceId ?? undefined },
         { timeoutMs: 30_000 }
       )
-    : window.api.linear.addIssueComment({ issueId, body })
+    : window.api.linear.addIssueComment({ issueId, body, workspaceId: workspaceId ?? undefined })
 }
 
 export async function linearIssueComments(
   settings: RuntimeLinearSettings,
-  issueId: string
+  issueId: string,
+  workspaceId?: string | null
 ): Promise<LinearComment[]> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
     ? callRuntimeRpc<LinearComment[]>(
         target,
         'linear.issueComments',
-        { issueId },
+        { issueId, workspaceId: workspaceId ?? undefined },
         { timeoutMs: 30_000 }
       )
-    : window.api.linear.issueComments({ issueId })
+    : window.api.linear.issueComments({ issueId, workspaceId: workspaceId ?? undefined })
 }
 
-export async function linearListTeams(settings: RuntimeLinearSettings): Promise<LinearTeam[]> {
+export async function linearListTeams(
+  settings: RuntimeLinearSettings,
+  workspaceId?: LinearWorkspaceSelection | null
+): Promise<LinearTeam[]> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
-    ? callRuntimeRpc<LinearTeam[]>(target, 'linear.listTeams', undefined, { timeoutMs: 30_000 })
-    : window.api.linear.listTeams()
+    ? callRuntimeRpc<LinearTeam[]>(
+        target,
+        'linear.listTeams',
+        workspaceId ? { workspaceId } : undefined,
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.listTeams(workspaceId ? { workspaceId } : undefined)
 }
 
 export async function linearTeamStates(
   settings: RuntimeLinearSettings,
-  teamId: string
+  teamId: string,
+  workspaceId?: string | null
 ): Promise<LinearWorkflowState[]> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
     ? callRuntimeRpc<LinearWorkflowState[]>(
         target,
         'linear.teamStates',
-        { teamId },
+        { teamId, workspaceId: workspaceId ?? undefined },
         { timeoutMs: 30_000 }
       )
-    : window.api.linear.teamStates({ teamId })
+    : window.api.linear.teamStates({ teamId, workspaceId: workspaceId ?? undefined })
 }
 
 export async function linearTeamLabels(
   settings: RuntimeLinearSettings,
-  teamId: string
+  teamId: string,
+  workspaceId?: string | null
 ): Promise<LinearLabel[]> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
-    ? callRuntimeRpc<LinearLabel[]>(target, 'linear.teamLabels', { teamId }, { timeoutMs: 30_000 })
-    : window.api.linear.teamLabels({ teamId })
+    ? callRuntimeRpc<LinearLabel[]>(
+        target,
+        'linear.teamLabels',
+        { teamId, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.teamLabels({ teamId, workspaceId: workspaceId ?? undefined })
 }
 
 export async function linearTeamMembers(
   settings: RuntimeLinearSettings,
-  teamId: string
+  teamId: string,
+  workspaceId?: string | null
 ): Promise<LinearMember[]> {
   const target = getActiveRuntimeTarget(settings)
   return target.kind === 'environment'
     ? callRuntimeRpc<LinearMember[]>(
         target,
         'linear.teamMembers',
-        { teamId },
+        { teamId, workspaceId: workspaceId ?? undefined },
         { timeoutMs: 30_000 }
       )
-    : window.api.linear.teamMembers({ teamId })
+    : window.api.linear.teamMembers({ teamId, workspaceId: workspaceId ?? undefined })
 }
diff --git a/src/renderer/src/store/slices/linear.ts b/src/renderer/src/store/slices/linear.ts
index 084c8e29cf9..618f7fe6520 100644
--- a/src/renderer/src/store/slices/linear.ts
+++ b/src/renderer/src/store/slices/linear.ts
@@ -1,14 +1,24 @@
+/* eslint-disable max-lines -- Why: the Linear slice owns status, workspace
+   selection, issue caches, and optimistic patch propagation as one store
+   boundary so cache invalidation stays coherent. */
 import type { StateCreator } from 'zustand'
 import type { AppState } from '../types'
-import type { LinearViewer, LinearConnectionStatus, LinearIssue } from '../../../../shared/types'
+import type {
+  LinearViewer,
+  LinearConnectionStatus,
+  LinearIssue,
+  LinearWorkspaceSelection
+} from '../../../../shared/types'
 import type { CacheEntry } from './github'
 import { clearLinearMetadataCache } from '../../hooks/useIssueMetadata'
 import {
   linearConnect,
   linearDisconnect,
+  linearDisconnectWorkspace,
   linearGetIssue,
   linearListIssues,
   linearSearchIssues,
+  linearSelectWorkspace,
   linearStatus,
   linearTestConnection
 } from '@/runtime/runtime-linear-client'
@@ -45,6 +55,10 @@ const inflightIssueRequests = new Map<string, Promise<LinearIssue | null>>()
 const inflightSearchRequests = new Map<string, Promise<LinearIssue[]>>()
 const inflightListRequests = new Map<string, Promise<LinearIssue[]>>()
 
+function getSelectedWorkspaceId(status: LinearConnectionStatus): LinearWorkspaceSelection | null {
+  return status.selectedWorkspaceId ?? status.activeWorkspaceId ?? null
+}
+
 export type LinearSlice = {
   linearStatus: LinearConnectionStatus
   linearStatusChecked: boolean
@@ -55,11 +69,13 @@ export type LinearSlice = {
   connectLinear: (
     apiKey: string
   ) => Promise<{ ok: true; viewer: LinearViewer } | { ok: false; error: string }>
-  testLinearConnection: () => Promise<
-    { ok: true; viewer: LinearViewer } | { ok: false; error: string }
-  >
+  testLinearConnection: (
+    workspaceId?: string | null
+  ) => Promise<{ ok: true; viewer: LinearViewer } | { ok: false; error: string }>
+  selectLinearWorkspace: (workspaceId: LinearWorkspaceSelection) => Promise<void>
   disconnectLinear: () => Promise<void>
-  fetchLinearIssue: (id: string) => Promise<LinearIssue | null>
+  disconnectLinearWorkspace: (workspaceId: string) => Promise<void>
+  fetchLinearIssue: (id: string, workspaceId?: string | null) => Promise<LinearIssue | null>
   searchLinearIssues: (query: string, limit?: number) => Promise<LinearIssue[]>
   listLinearIssues: (
     filter?: 'assigned' | 'created' | 'all' | 'completed',
@@ -78,7 +94,12 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
     try {
       const status = (await linearStatus(get().settings)) as LinearConnectionStatus
       const prev = get().linearStatus
-      if (prev.connected !== status.connected || prev.viewer?.email !== status.viewer?.email) {
+      if (
+        prev.connected !== status.connected ||
+        prev.viewer?.email !== status.viewer?.email ||
+        getSelectedWorkspaceId(prev) !== getSelectedWorkspaceId(status) ||
+        (prev.workspaces?.length ?? 0) !== (status.workspaces?.length ?? 0)
+      ) {
         set({ linearStatus: status, linearStatusChecked: true })
       } else if (!get().linearStatusChecked) {
         set({ linearStatusChecked: true })
@@ -92,24 +113,13 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
     }
   },
 
-  testLinearConnection: async () => {
+  testLinearConnection: async (workspaceId) => {
     try {
-      const result = (await linearTestConnection(get().settings)) as
+      const result = (await linearTestConnection(get().settings, workspaceId)) as
         | { ok: true; viewer: LinearViewer }
         | { ok: false; error: string }
-      if (result.ok) {
-        set({
-          linearStatus: { connected: true, viewer: result.viewer },
-          linearStatusChecked: true
-        })
-      } else {
-        // Why: testConnection clears the token on auth errors; reflect that
-        // locally so the UI drops back to the Connect state.
-        set({
-          linearStatus: { connected: false, viewer: null },
-          linearStatusChecked: true
-        })
-      }
+      const status = await linearStatus(get().settings)
+      set({ linearStatus: status, linearStatusChecked: true })
       return result
     } catch (error) {
       const message = error instanceof Error ? error.message : 'Test failed'
@@ -127,6 +137,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
             viewer: result.viewer as LinearViewer
           }
         })
+        void get().checkLinearConnection()
       }
       return result as { ok: true; viewer: LinearViewer } | { ok: false; error: string }
     } catch (error) {
@@ -135,6 +146,20 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
     }
   },
 
+  selectLinearWorkspace: async (workspaceId) => {
+    const status = await linearSelectWorkspace(get().settings, workspaceId)
+    inflightIssueRequests.clear()
+    inflightSearchRequests.clear()
+    inflightListRequests.clear()
+    clearLinearMetadataCache()
+    set({
+      linearStatus: status,
+      linearIssueCache: {},
+      linearSearchCache: {},
+      linearStatusChecked: true
+    })
+  },
+
   disconnectLinear: async () => {
     await linearDisconnect(get().settings)
     inflightIssueRequests.clear()
@@ -148,24 +173,40 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
     })
   },
 
-  fetchLinearIssue: async (id: string) => {
-    const cached = get().linearIssueCache[id]
+  disconnectLinearWorkspace: async (workspaceId) => {
+    await linearDisconnectWorkspace(get().settings, workspaceId)
+    inflightIssueRequests.clear()
+    inflightSearchRequests.clear()
+    inflightListRequests.clear()
+    clearLinearMetadataCache()
+    const status = await linearStatus(get().settings)
+    set({
+      linearStatus: status,
+      linearIssueCache: {},
+      linearSearchCache: {},
+      linearStatusChecked: true
+    })
+  },
+
+  fetchLinearIssue: async (id: string, workspaceId?: string | null) => {
+    const issueCacheKey = `${workspaceId ?? 'selected'}::${id}`
+    const cached = get().linearIssueCache[issueCacheKey] ?? get().linearIssueCache[id]
     if (isFresh(cached)) {
       return cached.data
     }
 
-    const inflight = inflightIssueRequests.get(id)
+    const inflight = inflightIssueRequests.get(issueCacheKey)
     if (inflight) {
       return inflight
     }
 
-    const promise = linearGetIssue(get().settings, id)
+    const promise = linearGetIssue(get().settings, id, workspaceId)
       .then((issue) => {
         const data = issue as LinearIssue | null
         set((s) => ({
           linearIssueCache: evictStaleEntries({
             ...s.linearIssueCache,
-            [id]: { data, fetchedAt: Date.now() }
+            [issueCacheKey]: { data, fetchedAt: Date.now() }
           })
         }))
         return data
@@ -178,15 +219,16 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
         return null
       })
       .finally(() => {
-        inflightIssueRequests.delete(id)
+        inflightIssueRequests.delete(issueCacheKey)
       })
 
-    inflightIssueRequests.set(id, promise)
+    inflightIssueRequests.set(issueCacheKey, promise)
     return promise
   },
 
   searchLinearIssues: async (query: string, limit = 20) => {
-    const cacheKey = `${query}::${limit}`
+    const workspaceId = getSelectedWorkspaceId(get().linearStatus)
+    const cacheKey = `${workspaceId ?? 'default'}::${query}::${limit}`
     const cached = get().linearSearchCache[cacheKey]
     if (isFresh(cached)) {
       return cached.data ?? []
@@ -197,7 +239,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
       return inflight
     }
 
-    const promise = linearSearchIssues(get().settings, query, limit)
+    const promise = linearSearchIssues(get().settings, query, limit, workspaceId)
       .then((issues) => {
         const data = issues as LinearIssue[]
         set((s) => ({
@@ -224,7 +266,8 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
   },
 
   listLinearIssues: async (filter = 'assigned', limit = 20) => {
-    const cacheKey = `list::${filter}::${limit}`
+    const workspaceId = getSelectedWorkspaceId(get().linearStatus)
+    const cacheKey = `${workspaceId ?? 'default'}::list::${filter}::${limit}`
     const cached = get().linearSearchCache[cacheKey]
     if (isFresh(cached)) {
       return cached.data ?? []
@@ -235,7 +278,7 @@ export const createLinearSlice: StateCreator<AppState, [], [], LinearSlice> = (s
       return inflight
     }
 
-    const promise = linearListIssues(get().settings, filter, limit)
+    const promise = linearListIssues(get().settings, filter, limit, workspaceId)
       .then((issues) => {
         const data = issues as LinearIssue[]
         set((s) => ({
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 53ec7a17340..448ce8b0091 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -680,16 +680,31 @@ export type GitHubWorkItemDetails = {
 export type LinearViewer = {
   displayName: string
   email: string | null
+  organizationId?: string
   organizationName: string
+  organizationUrlKey?: string
 }
 
+export type LinearWorkspace = LinearViewer & {
+  id: string
+  organizationId: string
+  isLegacy?: true
+}
+
+export type LinearWorkspaceSelection = string | 'all'
+
 export type LinearConnectionStatus = {
   connected: boolean
   viewer: LinearViewer | null
+  workspaces?: LinearWorkspace[]
+  activeWorkspaceId?: string | null
+  selectedWorkspaceId?: LinearWorkspaceSelection | null
 }
 
 export type LinearIssue = {
   id: string
+  workspaceId?: string
+  workspaceName?: string
   identifier: string
   title: string
   description?: string
@@ -885,6 +900,8 @@ export type LinearMember = {
 
 export type LinearTeam = {
   id: string
+  workspaceId?: string
+  workspaceName?: string
   name: string
   key: string
 }

From c0884f5f21e0825b2c95743fcf17ebbe7d1879d2 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 11:33:05 -0700
Subject: [PATCH 43/82] Fix release-cut draft RC recovery (#1942)

* fix: recover stuck draft RC releases

* fix: address release recovery lint
---
 .github/CONTRIBUTING.md                       |   2 +
 .github/workflows/release-cut.yml             | 114 +++++++++------
 .../publish-complete-draft-releases.mjs       | 133 +++++++++++++++++
 .../publish-complete-draft-releases.test.mjs  | 136 ++++++++++++++++++
 config/vitest.config.ts                       |   2 +-
 5 files changed, 345 insertions(+), 42 deletions(-)
 create mode 100644 config/scripts/publish-complete-draft-releases.mjs
 create mode 100644 config/scripts/publish-complete-draft-releases.test.mjs

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 9d2eddc7582..b54256d446a 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -95,6 +95,8 @@ All stable kinds (`patch`, `minor`, `major`) are computed off the latest *stable
 **Safety guarantees:**
 
 - Stable releases are refused if the new version isn't strictly greater than the latest published stable. This is the only rule `electron-updater` actually needs — it compares semver within the `latest` channel, so a regressing stable is the one thing that breaks auto-update for fresh installs.
+- Complete RC draft releases created by the release workflow are published before cutting a new tag, so a GitHub queue failure in the final publish job can be resumed safely.
+- If the latest RC tag exists but is still draft-only or missing its GitHub Release, the workflow resumes that tag before cutting the next RC. This keeps retries from leaving multiple unpublished draft releases behind.
 - Off-main releases (when `ref` is not the tip of `main`) only push the tag. `main` is never mutated from a non-main ref, so you can safely release an older commit without polluting history.
 - When `ref` is the tip of `main`, the version-bump commit is fast-forwarded onto `main` so local `package.json` stays in sync with what's shipped.
 
diff --git a/.github/workflows/release-cut.yml b/.github/workflows/release-cut.yml
index 5128f74d079..4851157bc4e 100644
--- a/.github/workflows/release-cut.yml
+++ b/.github/workflows/release-cut.yml
@@ -16,7 +16,7 @@ name: Cut Release
 #   5. Write package.json, commit (detached), tag, push tag.
 #   6. If ref was the tip of origin/main, fast-forward main to include the
 #      version-bump commit so developers see the right version locally.
-#   7. Invoke release.yml to build and publish artifacts.
+#   7. Build and publish artifacts from the tag.
 
 on:
   workflow_dispatch:
@@ -61,7 +61,7 @@ jobs:
     timeout-minutes: 15
     outputs:
       tag: ${{ steps.tag.outputs.tag || steps.version.outputs.recovered_tag }}
-      should_release: ${{ steps.window.outputs.allowed == 'true' && steps.existing.outputs.already_ran != 'true' && !(github.event_name == 'workflow_dispatch' && inputs.dry_run) }}
+      should_release: ${{ steps.tag.outputs.tag != '' || steps.version.outputs.recovered_tag != '' }}
     steps:
       - name: Checkout ref
         uses: actions/checkout@v4
@@ -174,9 +174,21 @@ jobs:
           echo "Already ran this slot: ${{ steps.existing.outputs.already_ran }}"
           echo "Reason: ${{ steps.existing.outputs.reason }}"
 
+      - name: Publish complete release-cut RC drafts from prior runs
+        id: publish_drafts
+        # Why: this must run even when the current slot already cut a tag; a
+        # later cron retry may be the first chance to unstick a complete RC draft.
+        if: steps.window.outputs.allowed == 'true' && !(github.event_name == 'workflow_dispatch' && inputs.dry_run)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node config/scripts/publish-complete-draft-releases.mjs
+
       - name: Compute next version
         id: version
-        if: steps.window.outputs.allowed == 'true' && steps.existing.outputs.already_ran != 'true' && !(github.event_name == 'workflow_dispatch' && inputs.dry_run)
+        # Why: if an RC run only had complete drafts to publish, stop there
+        # instead of immediately cutting another RC after the recovered one.
+        # Stable dispatches should still cut the requested stable release.
+        if: steps.window.outputs.allowed == 'true' && steps.existing.outputs.already_ran != 'true' && !(github.event_name == 'workflow_dispatch' && inputs.dry_run) && !((github.event_name == 'schedule' || inputs.kind == 'rc') && steps.publish_drafts.outputs.published_count != '0' && steps.publish_drafts.outputs.skipped_count == '0')
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           KIND: ${{ github.event_name == 'schedule' && 'rc' || inputs.kind }}
@@ -238,22 +250,50 @@ jobs:
             ' "$(strip_pre "$1")" "$2"
           }
 
-          next_rc_in_series() {
-            # Given a base version, find the highest existing -rc.N for it
-            # and return base-rc.(N+1). If none exists, base-rc.0.
+          highest_rc_for_base() {
             local base="$1"
-            local highest
-            highest="$(git tag --list "v${base}-rc.*" \
+            git tag --list "v${base}-rc.*" \
                 | sed -E "s/^v${base//./\\.}-rc\.//" \
                 | sort -n \
-                | tail -n 1 || true)"
-            if [[ -z "$highest" ]]; then
-              echo "${base}-rc.0"
+                | tail -n 1 || true
+          }
+
+          release_draft_state() {
+            # Prints: true, false, or missing.
+            local tag="$1"
+            local state_file="$RUNNER_TEMP/release-state-${tag//[^A-Za-z0-9_.-]/_}"
+            if gh release view "$tag" \
+                --repo "$GITHUB_REPOSITORY" \
+                --json isDraft \
+                --jq '.isDraft' >"$state_file" 2>/dev/null; then
+              cat "$state_file"
             else
-              echo "${base}-rc.$((highest + 1))"
+              echo "missing"
             fi
           }
 
+          recover_unpublished_tag() {
+            local tag="$1"
+            local reason="$2"
+            local release_state
+            release_state="$(release_draft_state "$tag")"
+            case "$release_state" in
+              missing|true)
+                echo "::warning::Tag $tag already exists but has no published release ($reason) - recovering by re-dispatching the release build against the existing tag."
+                echo "recovered_tag=$tag" >>"$GITHUB_OUTPUT"
+                echo "recovered=true" >>"$GITHUB_OUTPUT"
+                exit 0
+                ;;
+              false)
+                return 1
+                ;;
+              *)
+                echo "::error::Unexpected release state for $tag: $release_state" >&2
+                exit 1
+                ;;
+            esac
+          }
+
           # Fresh repo fallback so the math below never divides by zero.
           if [[ -z "$latest_stable" ]]; then
             latest_stable="0.0.0"
@@ -270,7 +310,18 @@ jobs:
               # that class of bug; minor/major RCs are cut by running
               # that stable kind first.
               base="$(bump "$latest_stable" patch)"
-              new="$(next_rc_in_series "$base")"
+              highest_rc="$(highest_rc_for_base "$base")"
+              if [[ -z "$highest_rc" ]]; then
+                new="${base}-rc.0"
+              else
+                existing_rc_tag="v${base}-rc.${highest_rc}"
+                # Why: a failed or GitHub-stuck run can leave the highest RC
+                # tag attached to a draft/missing release. Resume that tag so
+                # retries finish the intended release instead of piling up
+                # vX.Y.Z-rc.N+1 drafts.
+                recover_unpublished_tag "$existing_rc_tag" "latest RC in series" || true
+                new="${base}-rc.$((highest_rc + 1))"
+              fi
               ;;
             patch|minor|major)
               new="$(bump "$latest_stable" "$KIND")"
@@ -289,7 +340,7 @@ jobs:
           # Orphan-tag recovery.
           #
           # Why: if a previous cut pushed the tag but was cancelled (or the
-          # dependent release.yml job otherwise failed to start) before the
+          # dependent release build jobs otherwise failed to start) before the
           # GitHub Release was published, the tag now exists on the remote
           # but "latest stable" still points at the prior version. Every
           # subsequent patch cut then recomputes the same version and dies
@@ -301,7 +352,7 @@ jobs:
           # Recovery policy: if the tag exists AND no GitHub release has
           # been published for it (draft-or-absent both count as "not
           # shipped"), treat this as a resumable state: emit the existing
-          # tag as the job output so the downstream release.yml job runs
+          # tag as the job output so the downstream release build jobs run
           # against it and finishes what the earlier attempt started. The
           # bump/commit/push steps are skipped in that case — there is
           # nothing to bump; the tag is already on the remote.
@@ -310,32 +361,10 @@ jobs:
           # already exist — that's a real conflict (someone tagged manually
           # over a shipped version) and needs human attention.
           if git rev-parse "v$new" >/dev/null 2>&1; then
-            # Why: use the REST API, not `gh release view`. `gh api` returns
-            # `true`/`false` for a real release, while a 404 means the tag is
-            # orphaned and can be safely re-dispatched. Capture failures
-            # explicitly so the 404 payload never leaks into the state check.
-            release_state="missing"
-            if gh api \
-                "repos/$GITHUB_REPOSITORY/releases/tags/v$new" \
-                --jq '.draft' >"$RUNNER_TEMP/release-state" 2>/dev/null; then
-              release_state="$(cat "$RUNNER_TEMP/release-state")"
-            fi
-            case "$release_state" in
-              missing|true)
-                echo "::warning::Tag v$new already exists but no published release is attached — recovering by re-dispatching release.yml against the existing tag."
-                echo "recovered_tag=v$new" >>"$GITHUB_OUTPUT"
-                echo "recovered=true" >>"$GITHUB_OUTPUT"
-                exit 0
-                ;;
-              false)
-                echo "::error::Tag v$new already exists and has a published release. Refusing to re-cut over a shipped version." >&2
-                exit 1
-                ;;
-              *)
-                echo "::error::Unexpected release state for v$new: $release_state" >&2
-                exit 1
-                ;;
-            esac
+            recover_unpublished_tag "v$new" "tag collision" || {
+              echo "::error::Tag v$new already exists and has a published release. Refusing to re-cut over a shipped version." >&2
+              exit 1
+            }
           fi
 
           echo "version=$new" >>"$GITHUB_OUTPUT"
@@ -680,6 +709,9 @@ jobs:
       - name: Build app
         run: pnpm build:release
         env:
+          # Why: Vite's web build crossed Node's default old-space ceiling on
+          # the macOS release runner, leaving v1.4.2-rc.8 as an incomplete draft.
+          NODE_OPTIONS: --max-old-space-size=4096
           ORCA_BUILD_IDENTITY: ${{ steps.tag-classify.outputs.identity }}
           ORCA_POSTHOG_WRITE_KEY: ${{ secrets.ORCA_POSTHOG_WRITE_KEY }}
 
diff --git a/config/scripts/publish-complete-draft-releases.mjs b/config/scripts/publish-complete-draft-releases.mjs
new file mode 100644
index 00000000000..68af1d87c60
--- /dev/null
+++ b/config/scripts/publish-complete-draft-releases.mjs
@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import { appendFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { verifyRequiredReleaseAssets } from './verify-release-required-assets.mjs'
+
+const API_VERSION = '2022-11-28'
+const RELEASE_CUT_AUTHOR = 'github-actions[bot]'
+const DESKTOP_RC_TAG_PATTERN = /^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$/
+
+export function isReleaseCutDraft(release) {
+  return (
+    release?.draft === true &&
+    release?.author?.login === RELEASE_CUT_AUTHOR &&
+    typeof release?.tag_name === 'string' &&
+    DESKTOP_RC_TAG_PATTERN.test(release.tag_name)
+  )
+}
+
+function isRcTag(tag) {
+  return tag.includes('-rc.')
+}
+
+async function githubJson(fetchImpl, url, token, options = {}) {
+  const res = await fetchImpl(url, {
+    ...options,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${token}`,
+      'X-GitHub-Api-Version': API_VERSION,
+      ...options.headers
+    }
+  })
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    throw new Error(`GitHub request failed ${res.status} ${res.statusText}: ${body.slice(0, 300)}`)
+  }
+  return res.json()
+}
+
+async function fetchReleases(repo, token, fetchImpl) {
+  const releases = await githubJson(
+    fetchImpl,
+    `https://api.github.com/repos/${repo}/releases?per_page=100`,
+    token
+  )
+  if (!Array.isArray(releases)) {
+    throw new Error(`GitHub releases response for ${repo} was not an array`)
+  }
+  return releases
+}
+
+export async function publishCompleteDraftReleases({
+  repo,
+  token,
+  fetchImpl = fetch,
+  verifyReleaseAssets = verifyRequiredReleaseAssets,
+  log = console.log
+}) {
+  if (!repo) {
+    throw new Error('repo is required')
+  }
+  if (!token) {
+    throw new Error('token is required')
+  }
+
+  const releases = await fetchReleases(repo, token, fetchImpl)
+  const candidates = releases
+    .filter(isReleaseCutDraft)
+    .sort((a, b) => new Date(a.created_at ?? 0).getTime() - new Date(b.created_at ?? 0).getTime())
+
+  const published = []
+  const skipped = []
+
+  for (const release of candidates) {
+    const tag = release.tag_name
+    try {
+      await verifyReleaseAssets({ repo, tag, token })
+    } catch (error) {
+      const reason = error instanceof Error ? error.message.split('\n')[0] : String(error)
+      skipped.push({ tag, reason })
+      log(`Skipping incomplete RC draft release ${tag}: ${reason}`)
+      continue
+    }
+
+    // Why: only release-cut-authored RC drafts with a complete asset set are
+    // resumed here; incomplete drafts stay private for the normal rebuild path.
+    await githubJson(fetchImpl, `https://api.github.com/repos/${repo}/releases/${release.id}`, token, {
+      method: 'PATCH',
+      body: JSON.stringify({
+        draft: false,
+        prerelease: isRcTag(tag)
+      })
+    })
+    published.push(tag)
+    log(`Published complete RC draft release ${tag}`)
+  }
+
+  if (published.length === 0 && skipped.length === 0) {
+    log('No complete release-cut RC drafts to publish.')
+  }
+
+  return { published, skipped }
+}
+
+export function writeGithubOutputs({ published, skipped }, outputPath = process.env.GITHUB_OUTPUT) {
+  if (!outputPath) {
+    return
+  }
+  appendFileSync(
+    outputPath,
+    `${[
+      `published_count=${published.length}`,
+      `skipped_count=${skipped.length}`,
+      `published_tags=${published.join(',')}`,
+      `skipped_tags=${skipped.map((item) => item.tag).join(',')}`
+    ].join('\n')}\n`
+  )
+}
+
+async function main() {
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+  const repo = process.env.GITHUB_REPOSITORY || 'stablyai/orca'
+  const result = await publishCompleteDraftReleases({ repo, token })
+  writeGithubOutputs(result)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message)
+    process.exit(1)
+  })
+}
diff --git a/config/scripts/publish-complete-draft-releases.test.mjs b/config/scripts/publish-complete-draft-releases.test.mjs
new file mode 100644
index 00000000000..589f5475b50
--- /dev/null
+++ b/config/scripts/publish-complete-draft-releases.test.mjs
@@ -0,0 +1,136 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  isReleaseCutDraft,
+  publishCompleteDraftReleases,
+  writeGithubOutputs
+} from './publish-complete-draft-releases.mjs'
+
+function jsonResponse(body, init = {}) {
+  return {
+    ok: init.ok ?? true,
+    status: init.status ?? 200,
+    statusText: init.statusText ?? 'OK',
+    json: vi.fn(async () => body),
+    text: vi.fn(async () => (typeof body === 'string' ? body : JSON.stringify(body)))
+  }
+}
+
+describe('isReleaseCutDraft', () => {
+  it('only accepts bot-authored desktop draft releases', () => {
+    expect(
+      isReleaseCutDraft({
+        draft: true,
+        tag_name: 'v1.4.2-rc.7',
+        author: { login: 'github-actions[bot]' }
+      })
+    ).toBe(true)
+    expect(
+      isReleaseCutDraft({
+        draft: true,
+        tag_name: 'mobile-v0.0.7',
+        author: { login: 'github-actions[bot]' }
+      })
+    ).toBe(false)
+    expect(
+      isReleaseCutDraft({
+        draft: true,
+        tag_name: 'v1.4.2',
+        author: { login: 'github-actions[bot]' }
+      })
+    ).toBe(false)
+    expect(
+      isReleaseCutDraft({
+        draft: false,
+        tag_name: 'v1.4.2',
+        author: { login: 'github-actions[bot]' }
+      })
+    ).toBe(false)
+  })
+})
+
+describe('publishCompleteDraftReleases', () => {
+  it('publishes complete release-cut drafts and skips incomplete ones', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse([
+          {
+            id: 7,
+            draft: true,
+            tag_name: 'v1.4.2-rc.7',
+            created_at: '2026-05-15T07:31:19Z',
+            author: { login: 'github-actions[bot]' }
+          },
+          {
+            id: 8,
+            draft: true,
+            tag_name: 'v1.4.2-rc.8',
+            created_at: '2026-05-15T10:51:57Z',
+            author: { login: 'github-actions[bot]' }
+          }
+        ])
+      )
+      .mockResolvedValueOnce(jsonResponse({ tag_name: 'v1.4.2-rc.7', draft: false }))
+    const verifyReleaseAssets = vi.fn(async ({ tag }) => {
+      if (tag === 'v1.4.2-rc.8') {
+        throw new Error('Release v1.4.2-rc.8 is missing required assets.')
+      }
+    })
+    const log = vi.fn()
+
+    const result = await publishCompleteDraftReleases({
+      repo: 'stablyai/orca',
+      token: 'token',
+      fetchImpl,
+      verifyReleaseAssets,
+      log
+    })
+
+    expect(result).toEqual({
+      published: ['v1.4.2-rc.7'],
+      skipped: [
+        {
+          tag: 'v1.4.2-rc.8',
+          reason: 'Release v1.4.2-rc.8 is missing required assets.'
+        }
+      ]
+    })
+    expect(fetchImpl).toHaveBeenLastCalledWith(
+      'https://api.github.com/repos/stablyai/orca/releases/7',
+      expect.objectContaining({
+        method: 'PATCH',
+        body: JSON.stringify({ draft: false, prerelease: true })
+      })
+    )
+  })
+})
+
+describe('writeGithubOutputs', () => {
+  it('writes count outputs for workflow conditions', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'orca-release-outputs-'))
+    const outputPath = join(dir, 'output')
+    try {
+      writeGithubOutputs(
+        {
+          published: ['v1.4.2-rc.7'],
+          skipped: [{ tag: 'v1.4.2-rc.8', reason: 'missing assets' }]
+        },
+        outputPath
+      )
+
+      expect(readFileSync(outputPath, 'utf8')).toBe(
+        `${[
+          'published_count=1',
+          'skipped_count=1',
+          'published_tags=v1.4.2-rc.7',
+          'skipped_tags=v1.4.2-rc.8'
+        ].join('\n')}\n`
+      )
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
diff --git a/config/vitest.config.ts b/config/vitest.config.ts
index bee38dc32c9..13711cebd51 100644
--- a/config/vitest.config.ts
+++ b/config/vitest.config.ts
@@ -10,6 +10,6 @@ export default defineConfig({
   },
   test: {
     environment: 'node',
-    include: ['src/**/*.test.ts', 'src/**/*.test.tsx']
+    include: ['src/**/*.test.ts', 'src/**/*.test.tsx', 'config/scripts/**/*.test.mjs']
   }
 })

From e7833d8d17327ded50a630c163c55f7ca0822120 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 15 May 2026 11:34:01 -0700
Subject: [PATCH 44/82] Fix Droid native title completion notifications (#1944)

Co-authored-by: Orca <help@stably.ai>
---
 src/renderer/src/lib/agent-status.test.ts | 14 ++++
 src/shared/agent-detection.ts             | 19 ++++-
 tests/e2e/droid-notification.spec.ts      | 98 +++++++++++++++++++++++
 3 files changed, 128 insertions(+), 3 deletions(-)
 create mode 100644 tests/e2e/droid-notification.spec.ts

diff --git a/src/renderer/src/lib/agent-status.test.ts b/src/renderer/src/lib/agent-status.test.ts
index 2bf49ff71a6..770a6302cc1 100644
--- a/src/renderer/src/lib/agent-status.test.ts
+++ b/src/renderer/src/lib/agent-status.test.ts
@@ -200,6 +200,11 @@ describe('detectAgentStatusFromTitle', () => {
     expect(detectAgentStatusFromTitle('Droid working')).toBe('working')
   })
 
+  it('does not treat Factory Droid native needs-input titles as completion', () => {
+    expect(detectAgentStatusFromTitle('Factory Droid needs input')).toBeNull()
+    expect(detectAgentStatusFromTitle('Factory Droid needs your input')).toBeNull()
+  })
+
   // --- Case insensitivity ---
   it('is case-insensitive for agent names', () => {
     expect(detectAgentStatusFromTitle('CLAUDE')).toBe('idle')
@@ -488,6 +493,15 @@ describe('createAgentStatusTracker', () => {
     expect(onBecameIdle).toHaveBeenCalledTimes(1)
   })
 
+  it('does not fire when Factory Droid reports needs input during a working turn', () => {
+    const onBecameIdle = vi.fn()
+    const tracker = createAgentStatusTracker(onBecameIdle)
+
+    tracker.handleTitle('⠋ Droid')
+    tracker.handleTitle('Factory Droid needs input')
+    expect(onBecameIdle).not.toHaveBeenCalled()
+  })
+
   // --- Multiple cycles ---
   it('fires on each working → idle cycle', () => {
     const onBecameIdle = vi.fn()
diff --git a/src/shared/agent-detection.ts b/src/shared/agent-detection.ts
index 4fcf91b8a68..e4181e30468 100644
--- a/src/shared/agent-detection.ts
+++ b/src/shared/agent-detection.ts
@@ -151,9 +151,13 @@ function containsBrailleSpinner(title: string): boolean {
   return false
 }
 
-function containsAgentName(title: string): boolean {
+function containsLegacyAgentName(title: string): boolean {
   const lower = title.toLowerCase()
-  return AGENT_NAMES.some((name) => lower.includes(name)) || DROID_AGENT_NAME_RE.test(title)
+  return AGENT_NAMES.some((name) => lower.includes(name))
+}
+
+function containsAgentName(title: string): boolean {
+  return containsLegacyAgentName(title) || DROID_AGENT_NAME_RE.test(title)
 }
 
 function containsAny(title: string, words: readonly string[]): boolean {
@@ -413,7 +417,9 @@ export function detectAgentStatusFromTitle(title: string): AgentStatus | null {
     return 'working'
   }
 
-  if (containsAgentName(title)) {
+  const hasDroidAgentName = DROID_AGENT_NAME_RE.test(title)
+  const hasLegacyAgentName = containsLegacyAgentName(title)
+  if (hasLegacyAgentName || hasDroidAgentName) {
     if (containsAny(title, ['action required', 'permission', 'waiting'])) {
       return 'permission'
     }
@@ -443,6 +449,13 @@ export function detectAgentStatusFromTitle(title: string): AgentStatus | null {
       return 'idle'
     }
 
+    // Why: Factory Droid can publish native titles like "Factory Droid needs
+    // input" while an Execute tool is still sleeping. Droid's hook events are
+    // authoritative; don't turn a name-only native title into a completion.
+    if (hasDroidAgentName && !hasLegacyAgentName) {
+      return null
+    }
+
     return 'idle'
   }
 
diff --git a/tests/e2e/droid-notification.spec.ts b/tests/e2e/droid-notification.spec.ts
new file mode 100644
index 00000000000..b35ceae86d7
--- /dev/null
+++ b/tests/e2e/droid-notification.spec.ts
@@ -0,0 +1,98 @@
+import { test, expect } from './helpers/orca-app'
+import type { ElectronApplication } from '@stablyai/playwright-test'
+import {
+  sendToTerminal,
+  waitForActivePanePtyId,
+  waitForActiveTerminalManager,
+  waitForTerminalOutput
+} from './helpers/terminal'
+import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+
+type NotificationDispatch = {
+  source?: string
+  terminalTitle?: string
+}
+
+async function emitOscTitle(
+  page: Parameters<typeof sendToTerminal>[0],
+  ptyId: string,
+  title: string
+) {
+  await sendToTerminal(page, ptyId, `printf '\\033]0;${title}\\007'\r`)
+}
+
+async function installMainProcessNotificationDispatchSpy(app: ElectronApplication): Promise<void> {
+  await app.evaluate(({ ipcMain }) => {
+    const g = globalThis as unknown as {
+      __notificationDispatchLog?: NotificationDispatch[]
+      __notificationDispatchSpyInstalled?: boolean
+    }
+    if (g.__notificationDispatchSpyInstalled) {
+      return
+    }
+    g.__notificationDispatchLog = []
+    g.__notificationDispatchSpyInstalled = true
+    ipcMain.removeHandler('notifications:dispatch')
+    ipcMain.handle('notifications:dispatch', (_event: unknown, args: NotificationDispatch) => {
+      g.__notificationDispatchLog!.push(args)
+      return { delivered: true }
+    })
+  })
+}
+
+async function getNotificationDispatches(
+  app: ElectronApplication
+): Promise<NotificationDispatch[]> {
+  return app.evaluate(() => {
+    const g = globalThis as unknown as { __notificationDispatchLog?: NotificationDispatch[] }
+    return g.__notificationDispatchLog ?? []
+  })
+}
+
+test.describe('Droid notifications', () => {
+  test('Factory Droid needs-input native title does not dispatch a task-complete notification', async ({
+    orcaPage,
+    electronApp
+  }) => {
+    await waitForSessionReady(orcaPage)
+    await waitForActiveWorktree(orcaPage)
+    await ensureTerminalVisible(orcaPage)
+    await waitForActiveTerminalManager(orcaPage, 30_000)
+    // Why: contextBridge freezes window.api, so notification invokes must be
+    // observed in Electron's main process rather than monkey-patched renderer-side.
+    await installMainProcessNotificationDispatchSpy(electronApp)
+
+    const ptyId = await waitForActivePanePtyId(orcaPage)
+    const marker = `__DROID_NOTIFY_READY_${Date.now()}__`
+    await sendToTerminal(orcaPage, ptyId, `printf '${marker}\\n'\r`)
+    await waitForTerminalOutput(orcaPage, marker)
+
+    await emitOscTitle(orcaPage, ptyId, '⠋ Droid')
+    await emitOscTitle(orcaPage, ptyId, 'Factory Droid needs input')
+
+    await expect
+      .poll(
+        async () =>
+          orcaPage.evaluate(() => {
+            const store = window.__store
+            if (!store) {
+              return false
+            }
+            return Object.values(store.getState().tabsByWorktree ?? {})
+              .flat()
+              .some((tab) => tab.title === 'Factory Droid needs input')
+          }),
+        {
+          timeout: 10_000,
+          message: 'Factory Droid marker title did not land'
+        }
+      )
+      .toBe(true)
+
+    // Why: Factory Droid can show this title while Execute is still running
+    // (for example `sleep 180`); hook events own Droid status, not this title.
+    await orcaPage.waitForTimeout(500)
+    const dispatches = await getNotificationDispatches(electronApp)
+    expect(dispatches).toEqual([])
+  })
+})

From e64f8c5a76295e542dd34551289af804e0b7ec79 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 11:38:31 -0700
Subject: [PATCH 45/82] Block publishing merged pull request branches

---
 .../right-sidebar/SourceControl.tsx           | 13 ++-
 .../source-control-dropdown-items.test.ts     | 33 +++++++
 .../source-control-dropdown-items.ts          | 91 ++++++++++++++-----
 .../source-control-primary-action.test.ts     | 10 ++
 .../source-control-primary-action.ts          | 24 ++++-
 5 files changed, 144 insertions(+), 27 deletions(-)

diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index 296e13dd75f..98e9053fe8f 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -462,12 +462,15 @@ function SourceControlInner(): React.JSX.Element {
   const branchName = activeWorktree?.branch.replace(/^refs\/heads\//, '') ?? 'HEAD'
   const hostedReviewCacheKey =
     activeRepo && branchName ? getHostedReviewCacheKey(activeRepo.path, branchName, settings) : null
+  const hostedReviewEntry = hostedReviewCacheKey ? hostedReviewCache[hostedReviewCacheKey] : undefined
   const hostedReview: HostedReviewInfo | null = hostedReviewCacheKey
-    ? (hostedReviewCache[hostedReviewCacheKey]?.data ?? null)
+    ? (hostedReviewEntry?.data ?? null)
     : null
 
   const linkedGitHubPR = activeWorktree?.linkedPR ?? null
   const linkedGitLabMR = activeWorktree?.linkedGitLabMR ?? null
+  const isHostedReviewStateLoading =
+    (linkedGitHubPR !== null || linkedGitLabMR !== null) && hostedReviewEntry === undefined
   useEffect(() => {
     if (!isBranchVisible || !activeRepo || isFolder || !branchName || branchName === 'HEAD') {
       return
@@ -894,6 +897,8 @@ function SourceControlInner(): React.JSX.Element {
         isCommitting,
         isRemoteOperationActive,
         upstreamStatus: remoteStatus,
+        prState: hostedReview?.state ?? null,
+        isPRStateLoading: isHostedReviewStateLoading,
         inFlightRemoteOpKind
       }),
     [
@@ -903,6 +908,8 @@ function SourceControlInner(): React.JSX.Element {
       isCommitting,
       isRemoteOperationActive,
       inFlightRemoteOpKind,
+      isHostedReviewStateLoading,
+      hostedReview?.state,
       remoteStatus,
       unresolvedConflicts.length
     ]
@@ -918,6 +925,8 @@ function SourceControlInner(): React.JSX.Element {
         isCommitting,
         isRemoteOperationActive,
         upstreamStatus: remoteStatus,
+        prState: hostedReview?.state ?? null,
+        isPRStateLoading: isHostedReviewStateLoading,
         inFlightRemoteOpKind
       }),
     [
@@ -927,6 +936,8 @@ function SourceControlInner(): React.JSX.Element {
       isCommitting,
       isRemoteOperationActive,
       inFlightRemoteOpKind,
+      isHostedReviewStateLoading,
+      hostedReview?.state,
       remoteStatus,
       unresolvedConflicts.length
     ]
diff --git a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
index 9da3f7caf2d..8d9aa907db3 100644
--- a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
@@ -168,6 +168,39 @@ describe('resolveDropdownItems', () => {
     expect(byKind.publish.disabled).toBe(false)
   })
 
+  it('does not mention Publish Branch when the linked PR is already merged', () => {
+    const items = resolveDropdownItems(
+      inputs({
+        upstreamStatus: { hasUpstream: false, ahead: 0, behind: 0 },
+        prState: 'merged'
+      })
+    )
+    const byKind = Object.fromEntries(
+      items.filter((e) => e.kind !== 'separator').map((e) => [e.kind, e])
+    )
+    expect(byKind.push.title).toBe('PR is already merged')
+    expect(byKind.pull.title).toBe('PR is already merged')
+    expect(byKind.sync.title).toBe('PR is already merged')
+    expect(byKind.publish.label).toBe('PR Status')
+    expect(byKind.publish.title).toBe('PR is already merged')
+    expect(byKind.publish.disabled).toBe(true)
+  })
+
+  it('waits for linked PR state before showing a publish prompt', () => {
+    const items = resolveDropdownItems(
+      inputs({
+        upstreamStatus: { hasUpstream: false, ahead: 0, behind: 0 },
+        isPRStateLoading: true
+      })
+    )
+    const byKind = Object.fromEntries(
+      items.filter((e) => e.kind !== 'separator').map((e) => [e.kind, e])
+    )
+    expect(byKind.publish.label).toBe('PR Status')
+    expect(byKind.publish.title).toBe('Checking PR status…')
+    expect(byKind.publish.disabled).toBe(true)
+  })
+
   it('omits counts from compound commit labels even when ahead/behind are nonzero', () => {
     // Why: the commit itself changes ahead/behind, so pre-commit counts would
     // be stale the moment the action fires. Plain Push/Pull/Sync continue to
diff --git a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
index 78a9eac4d14..53656a8821a 100644
--- a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
@@ -58,7 +58,9 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
     hasUnresolvedConflicts,
     isCommitting,
     isRemoteOperationActive,
-    upstreamStatus
+    upstreamStatus,
+    prState,
+    isPRStateLoading
   } = inputs
 
   const hasStaged = stagedCount > 0
@@ -71,6 +73,8 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
   // button's stable-frame guarantee extends to the dropdown.
   const upstreamLoading = upstreamStatus === undefined
   const hasUpstream = upstreamStatus?.hasUpstream ?? false
+  const publishBlockedByMergedPR = !hasUpstream && prState === 'merged'
+  const publishBlockedByPRLoading = !hasUpstream && !!isPRStateLoading
   const ahead = upstreamStatus?.ahead ?? 0
   const behind = upstreamStatus?.behind ?? 0
 
@@ -108,20 +112,36 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
   // so the "publish first" instruction is consistent across the menu.
   const commitPushTitle = upstreamLoading
     ? 'Checking branch status…'
-    : !hasUpstream
-      ? 'Publish the branch first to push commits'
-      : (commitDisabledReason ?? 'Commit staged changes and push')
+    : publishBlockedByPRLoading
+      ? 'Checking PR status…'
+      : publishBlockedByMergedPR
+        ? 'PR is already merged'
+        : !hasUpstream
+          ? 'Publish the branch first to push commits'
+          : (commitDisabledReason ?? 'Commit staged changes and push')
   const commitPushItem: DropdownItem = {
     kind: 'commit_push',
     label: 'Commit & Push',
     title: commitPushTitle,
-    disabled: globalBusy || upstreamLoading || !hasUpstream || commitDisabledReason !== null
+    disabled:
+      globalBusy ||
+      upstreamLoading ||
+      !hasUpstream ||
+      publishBlockedByPRLoading ||
+      publishBlockedByMergedPR ||
+      commitDisabledReason !== null
   }
 
   const commitSyncTitle = (() => {
     if (upstreamLoading) {
       return 'Checking branch status…'
     }
+    if (publishBlockedByPRLoading) {
+      return 'Checking PR status…'
+    }
+    if (publishBlockedByMergedPR) {
+      return 'PR is already merged'
+    }
     if (!hasUpstream) {
       // Why: mirror pushItem/syncItem — direct the user to Publish Branch
       // (the primary action on an unpublished branch) rather than naming a
@@ -146,11 +166,15 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
     label: formatCountLabel('Push', ahead),
     title: upstreamLoading
       ? 'Checking branch status…'
-      : !hasUpstream
-        ? 'Publish the branch first to push commits'
-        : ahead === 0
-          ? 'Nothing to push'
-          : describePushCount(ahead),
+      : publishBlockedByPRLoading
+        ? 'Checking PR status…'
+        : publishBlockedByMergedPR
+          ? 'PR is already merged'
+          : !hasUpstream
+            ? 'Publish the branch first to push commits'
+            : ahead === 0
+              ? 'Nothing to push'
+              : describePushCount(ahead),
     disabled: globalBusy || upstreamLoading || !hasUpstream || ahead === 0
   }
 
@@ -159,11 +183,15 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
     label: formatCountLabel('Pull', behind),
     title: upstreamLoading
       ? 'Checking branch status…'
-      : !hasUpstream
-        ? 'Publish the branch first to pull commits'
-        : behind === 0
-          ? 'Nothing to pull'
-          : describePullCount(behind),
+      : publishBlockedByPRLoading
+        ? 'Checking PR status…'
+        : publishBlockedByMergedPR
+          ? 'PR is already merged'
+          : !hasUpstream
+            ? 'Publish the branch first to pull commits'
+            : behind === 0
+              ? 'Nothing to pull'
+              : describePullCount(behind),
     disabled: globalBusy || upstreamLoading || !hasUpstream || behind === 0
   }
 
@@ -172,11 +200,15 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
     label: formatSyncLabel('Sync', ahead, behind),
     title: upstreamLoading
       ? 'Checking branch status…'
-      : !hasUpstream
-        ? 'Publish the branch first to sync commits'
-        : ahead === 0 && behind === 0
-          ? 'Branch is up to date'
-          : describeSyncCounts(ahead, behind),
+      : publishBlockedByPRLoading
+        ? 'Checking PR status…'
+        : publishBlockedByMergedPR
+          ? 'PR is already merged'
+          : !hasUpstream
+            ? 'Publish the branch first to sync commits'
+            : ahead === 0 && behind === 0
+              ? 'Branch is up to date'
+              : describeSyncCounts(ahead, behind),
     disabled: globalBusy || upstreamLoading || !hasUpstream || (ahead === 0 && behind === 0)
   }
 
@@ -189,13 +221,22 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
 
   const publishItem: DropdownItem = {
     kind: 'publish',
-    label: 'Publish Branch',
+    label: publishBlockedByMergedPR || publishBlockedByPRLoading ? 'PR Status' : 'Publish Branch',
     title: upstreamLoading
       ? 'Checking branch status…'
-      : hasUpstream
-        ? 'Branch is already published'
-        : 'Publish this branch to origin',
-    disabled: globalBusy || upstreamLoading || hasUpstream
+      : publishBlockedByPRLoading
+        ? 'Checking PR status…'
+        : publishBlockedByMergedPR
+          ? 'PR is already merged'
+          : hasUpstream
+            ? 'Branch is already published'
+            : 'Publish this branch to origin',
+    disabled:
+      globalBusy ||
+      upstreamLoading ||
+      hasUpstream ||
+      publishBlockedByPRLoading ||
+      publishBlockedByMergedPR
   }
 
   return [
diff --git a/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts b/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
index c0655ca03a9..6838b2f7af7 100644
--- a/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
@@ -182,6 +182,16 @@ describe('resolvePrimaryAction', () => {
     })
   })
 
+  it.each([
+    [{ prState: 'merged' as const }, 'Nothing to commit. PR is already merged.'],
+    [{ isPRStateLoading: true }, 'Checking PR status…']
+  ])('does not offer Publish Branch when linked PR state blocks it', (overrides, title) => {
+    const result = resolvePrimaryAction(
+      inputs({ upstreamStatus: { hasUpstream: false, ahead: 0, behind: 0 }, ...overrides })
+    )
+    expect(result).toEqual({ kind: 'commit', label: 'Commit', title, disabled: true })
+  })
+
   it('returns Sync when clean + tracked + diverged both ways', () => {
     const result = resolvePrimaryAction(
       inputs({ upstreamStatus: { hasUpstream: true, ahead: 2, behind: 3 } })
diff --git a/src/renderer/src/components/right-sidebar/source-control-primary-action.ts b/src/renderer/src/components/right-sidebar/source-control-primary-action.ts
index 51a0f808ce5..04bfdf04542 100644
--- a/src/renderer/src/components/right-sidebar/source-control-primary-action.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-primary-action.ts
@@ -1,6 +1,6 @@
 // Why: split from the combined primary+dropdown module because the primary and dropdown are independent derivations with different priority ladders; together they exceed the max-lines budget and tangle unrelated concerns.
 
-import type { GitUpstreamStatus } from '../../../../shared/types'
+import type { GitUpstreamStatus, PRState } from '../../../../shared/types'
 
 // Why: this module owns the pure state-machine logic for the Source Control
 // primary action (split button). Keeping the logic outside the React component
@@ -39,6 +39,8 @@ export type PrimaryActionInputs = {
   isCommitting: boolean
   isRemoteOperationActive: boolean
   upstreamStatus: GitUpstreamStatus | undefined
+  prState?: PRState | null
+  isPRStateLoading?: boolean
   // Why: which remote op is currently running, when one is. null when no
   // remote op is in flight. Used by the in-flight branch below to mirror
   // the user-triggered action on the primary button instead of leaving a
@@ -93,6 +95,8 @@ export function resolvePrimaryAction(inputs: PrimaryActionInputs): PrimaryAction
     isCommitting,
     isRemoteOperationActive,
     upstreamStatus,
+    prState,
+    isPRStateLoading,
     inFlightRemoteOpKind
   } = inputs
 
@@ -214,6 +218,24 @@ export function resolvePrimaryAction(inputs: PrimaryActionInputs): PrimaryAction
   }
 
   if (!upstreamStatus.hasUpstream) {
+    if (isPRStateLoading) {
+      return {
+        kind: 'commit',
+        label: 'Commit',
+        title: 'Checking PR status…',
+        disabled: true
+      }
+    }
+
+    if (prState === 'merged') {
+      return {
+        kind: 'commit',
+        label: 'Commit',
+        title: 'Nothing to commit. PR is already merged.',
+        disabled: true
+      }
+    }
+
     return {
       kind: 'publish',
       label: 'Publish Branch',

From b8d669895052aff3fccefb67f72f1d2858332727 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 11:44:52 -0700
Subject: [PATCH 46/82] fix: make right sidebar header draggable (#1950)

---
 docs/right-sidebar-header-drag.md             | 54 +++++++++++++++++++
 src/renderer/src/assets/main.css              |  9 ++++
 .../src/components/right-sidebar/index.tsx    | 22 ++++----
 3 files changed, 75 insertions(+), 10 deletions(-)
 create mode 100644 docs/right-sidebar-header-drag.md

diff --git a/docs/right-sidebar-header-drag.md b/docs/right-sidebar-header-drag.md
new file mode 100644
index 00000000000..d1a525491c9
--- /dev/null
+++ b/docs/right-sidebar-header-drag.md
@@ -0,0 +1,54 @@
+# Right Sidebar Header Drag Region
+
+## Problem
+
+Right sidebar header blank space does not drag the window.
+
+- In top mode, the header row (`right-sidebar/index.tsx`, current line ~313) has no `-webkit-app-region: drag`.
+- In side mode, the title row (`right-sidebar/index.tsx`, current line ~332) has no `-webkit-app-region: drag`.
+- The app already uses draggable titlebar surfaces elsewhere (`.titlebar`, `.titlebar-left` in `main.css`), so this is an inconsistency.
+
+## Current Behavior (Verified)
+
+- `ActivityBarButton` renders plain `<button>` elements with no `no-drag` class.
+- Close button is already safe because `.sidebar-toggle` sets `-webkit-app-region: no-drag`.
+- Top-mode activity bar context menu is currently bound to the full header row via `ContextMenuTrigger`.
+- Side-mode activity bar context menu is bound to the side icon strip, not the side-mode title row.
+
+## Constraints That Matter
+
+- `-webkit-app-region: drag` is required for Electron window drag hit-testing.
+- Interactive descendants inside a drag region must be `-webkit-app-region: no-drag`, or click behavior becomes unreliable.
+- Do not depend on blank-space right-click inside a drag region for opening menus; attach context-menu trigger to a guaranteed `no-drag` target.
+- No visual/layout changes; keep existing Windows inset behavior (`right-sidebar-header-inset`, `right-sidebar-header-side-inset`, `side-activity-bar-windows-inset`).
+
+## Design
+
+1. Add utility classes in `src/renderer/src/assets/main.css`:
+   - `.right-sidebar-header-drag { -webkit-app-region: drag; user-select: none; }`
+   - `.right-sidebar-header-no-drag { -webkit-app-region: no-drag; }`
+2. Apply `.right-sidebar-header-drag` to both header wrappers:
+   - top activity-bar row
+   - side-mode title row
+3. Apply `.right-sidebar-header-no-drag` to all interactive header descendants:
+   - `ActivityBarButton` root button
+   - top-mode icon-row wrapper that owns context-menu trigger
+   - close button is already covered by `.sidebar-toggle` (keep as-is)
+4. Move top-mode `ContextMenuTrigger` from the whole header row to a `no-drag` target (icon-row wrapper). Do not bind it to the drag surface.
+5. Keep side-mode context-menu wiring on the side icon strip unchanged.
+
+## Validation
+
+- Top mode: blank area drags window.
+- Top mode: tab icons click reliably; close button click remains reliable.
+- Top mode: context menu opens from icon row (not blank drag area).
+- Side mode: title/blank area drags; close button remains clickable.
+- Left-edge resize handle remains usable (`z-10`, absolute overlay).
+- Windows: overlay controls do not cover close button/icons after insets.
+- Sidebar closed (`width: 0`, `overflow-hidden`): no leaked hit targets.
+
+## Concurrency / Consistency
+
+- Multi-window safe: renderer-local CSS/DOM only, no shared mutable state.
+- Store updates (`activityBarPosition`, `rightSidebarTab`, `rightSidebarOpen`) are safe: drag/no-drag is static class wiring on re-rendered elements.
+- No IPC or async cross-process dependency, so no invalidation races introduced.
diff --git a/src/renderer/src/assets/main.css b/src/renderer/src/assets/main.css
index 1e206c0f92c..08df8050141 100644
--- a/src/renderer/src/assets/main.css
+++ b/src/renderer/src/assets/main.css
@@ -470,6 +470,15 @@
   width: var(--window-controls-width, 0px);
 }
 
+.right-sidebar-header-drag {
+  -webkit-app-region: drag;
+  user-select: none;
+}
+
+.right-sidebar-header-no-drag {
+  -webkit-app-region: no-drag;
+}
+
 /* Why: the right sidebar header extends to the window's right edge. On Windows
    the fixed-position window-controls overlay sits on top of that edge, so we
    add matching padding-right so the header's close button (pr-1) isn't hidden
diff --git a/src/renderer/src/components/right-sidebar/index.tsx b/src/renderer/src/components/right-sidebar/index.tsx
index 66bcaa55682..fd1db766e59 100644
--- a/src/renderer/src/components/right-sidebar/index.tsx
+++ b/src/renderer/src/components/right-sidebar/index.tsx
@@ -309,14 +309,16 @@ function RightSidebarInner(): React.JSX.Element {
         {activityBarPosition === 'top' ? (
           /* ── Top activity bar: horizontal icon row ── */
           <ContextMenu>
-            <ContextMenuTrigger asChild>
-              <div className="flex items-center justify-between border-b border-border h-[36px] min-h-[36px] pl-2 pr-1 right-sidebar-header-inset">
-                <TooltipProvider delayDuration={400}>
-                  <div className="flex items-center">{activityBarIcons}</div>
-                  <div className="flex items-center">{closeButton}</div>
-                </TooltipProvider>
-              </div>
-            </ContextMenuTrigger>
+            <div className="flex items-center justify-between border-b border-border h-[36px] min-h-[36px] pl-2 pr-1 right-sidebar-header-inset right-sidebar-header-drag">
+              <TooltipProvider delayDuration={400}>
+                <ContextMenuTrigger asChild>
+                  <div className="flex items-center right-sidebar-header-no-drag">
+                    {activityBarIcons}
+                  </div>
+                </ContextMenuTrigger>
+                <div className="flex items-center">{closeButton}</div>
+              </TooltipProvider>
+            </div>
             <ActivityBarPositionMenu
               currentPosition={activityBarPosition}
               onChangePosition={setActivityBarPosition}
@@ -329,7 +331,7 @@ function RightSidebarInner(): React.JSX.Element {
              the panel header. right-sidebar-header-side-inset applies exactly
              that remainder (138-40=98px) as padding-right so the close button
              clears the minimize button without the full 138px gap. */
-          <div className="flex items-center justify-between h-[36px] min-h-[36px] px-3 border-b border-border right-sidebar-header-side-inset">
+          <div className="flex items-center justify-between h-[36px] min-h-[36px] px-3 border-b border-border right-sidebar-header-side-inset right-sidebar-header-drag">
             <span className="text-[11px] font-semibold uppercase tracking-wider text-foreground">
               {visibleItems.find((item) => item.id === effectiveTab)?.title ?? ''}
             </span>
@@ -423,7 +425,7 @@ function ActivityBarButton({
       <TooltipTrigger asChild>
         <button
           className={cn(
-            'relative flex items-center justify-center transition-colors',
+            'relative flex items-center justify-center transition-colors right-sidebar-header-no-drag',
             isTop ? 'h-[36px] w-9' : 'w-10 h-10',
             active ? 'text-foreground' : 'text-muted-foreground/60 hover:text-muted-foreground'
           )}

From 82214e86ee5c94cee906fa17bb9ff7000aac3b35 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 11:46:06 -0700
Subject: [PATCH 47/82] Revert "Add project notes (#1861)" (#1945)

This reverts commit c73fd2c90b30d4b5f19f80ca895d99c420df4b68.
---
 src/cli/args.ts                               |   3 +-
 src/cli/dispatch.ts                           |   4 +-
 src/cli/format.ts                             |  34 -
 src/cli/handlers/note.ts                      |  95 ---
 src/cli/specs/index.ts                        |   4 +-
 src/cli/specs/note.ts                         |  37 -
 src/main/ipc/notes.ts                         |  40 -
 src/main/ipc/register-core-handlers.test.ts   |   7 -
 src/main/ipc/register-core-handlers.ts        |   2 -
 src/main/ipc/worktrees.test.ts                |   4 +-
 src/main/ipc/worktrees.ts                     |   3 -
 src/main/notes/notes-markdown-store.test.ts   |  76 --
 src/main/notes/notes-markdown-store.ts        | 586 ---------------
 src/main/runtime/orca-runtime.test.ts         | 264 -------
 src/main/runtime/orca-runtime.ts              | 273 +------
 src/main/runtime/rpc/errors.ts                |   3 -
 src/main/runtime/rpc/methods/index.ts         |   2 -
 src/main/runtime/rpc/methods/notes.test.ts    | 148 ----
 src/main/runtime/rpc/methods/notes.ts         | 165 -----
 src/preload/api-types.ts                      |  30 -
 src/preload/index.ts                          |  13 -
 src/renderer/src/components/Terminal.tsx      |  20 -
 .../src/components/WorktreeJumpPalette.tsx    |   2 +-
 .../src/components/editor/EditorPanel.tsx     |   2 +-
 .../FloatingTerminalPanel.tsx                 | 153 +---
 .../notes/ProjectNotesTabContent.tsx          | 699 ------------------
 .../components/right-sidebar/NotesPanel.tsx   | 364 ---------
 .../src/components/right-sidebar/index.tsx    |  10 +-
 .../src/components/sidebar/WorktreeList.tsx   |   5 -
 .../sidebar/use-worktree-activity-status.ts   |   5 -
 .../sidebar/visible-worktrees.test.ts         |  33 +-
 .../components/sidebar/visible-worktrees.ts   |  14 +-
 .../components/tab-bar/ProjectNotesTab.tsx    | 131 ----
 .../tab-bar/TabBar.context-menu.test.ts       |  13 -
 .../src/components/tab-bar/TabBar.tsx         | 188 +----
 .../src/components/tab-bar/TabDragPreview.tsx |  10 +-
 .../src/components/tab-bar/group-tab-order.ts |  21 +-
 .../src/components/tab-bar/reconcile-order.ts |   7 +-
 .../components/tab-group/TabGroupPanel.tsx    |  58 +-
 .../components/tab-group/useTabDragSplit.ts   |   2 +-
 .../tab-group/useTabGroupWorkspaceModel.ts    |  80 --
 .../src/components/terminal/tab-type-cycle.ts |   2 +-
 .../src/components/ui/dropdown-menu.tsx       |   8 +-
 src/renderer/src/hooks/ipc-tab-switch.ts      |   3 -
 src/renderer/src/hooks/resolve-zoom-target.ts |   4 +-
 src/renderer/src/hooks/useIpcEvents.ts        |  10 -
 src/renderer/src/lib/notes-events.ts          |   1 -
 .../src/lib/open-project-notes-tab.ts         |  65 --
 .../lib/project-notes-close-request.test.ts   |  47 --
 .../src/lib/project-notes-close-request.ts    |  28 -
 src/renderer/src/lib/worktree-status.test.ts  |  24 -
 src/renderer/src/lib/worktree-status.ts       |   4 -
 .../src/runtime/runtime-notes-client.test.ts  | 228 ------
 .../src/runtime/runtime-notes-client.ts       | 229 ------
 src/renderer/src/store/slices/editor.ts       |   8 +-
 .../src/store/slices/tabs-hydration.ts        |   3 +-
 src/renderer/src/store/slices/tabs.test.ts    |  50 --
 src/renderer/src/store/slices/tabs.ts         |  25 +-
 src/renderer/src/store/slices/worktrees.ts    |   8 +-
 src/renderer/src/web/web-preload-api.ts       |  18 -
 src/shared/notes-types.ts                     | 130 ----
 src/shared/types.ts                           |  11 +-
 src/shared/workspace-session-schema.ts        |  14 +-
 63 files changed, 69 insertions(+), 4461 deletions(-)
 delete mode 100644 src/cli/handlers/note.ts
 delete mode 100644 src/cli/specs/note.ts
 delete mode 100644 src/main/ipc/notes.ts
 delete mode 100644 src/main/notes/notes-markdown-store.test.ts
 delete mode 100644 src/main/notes/notes-markdown-store.ts
 delete mode 100644 src/main/runtime/rpc/methods/notes.test.ts
 delete mode 100644 src/main/runtime/rpc/methods/notes.ts
 delete mode 100644 src/renderer/src/components/notes/ProjectNotesTabContent.tsx
 delete mode 100644 src/renderer/src/components/right-sidebar/NotesPanel.tsx
 delete mode 100644 src/renderer/src/components/tab-bar/ProjectNotesTab.tsx
 delete mode 100644 src/renderer/src/lib/notes-events.ts
 delete mode 100644 src/renderer/src/lib/open-project-notes-tab.ts
 delete mode 100644 src/renderer/src/lib/project-notes-close-request.test.ts
 delete mode 100644 src/renderer/src/lib/project-notes-close-request.ts
 delete mode 100644 src/renderer/src/runtime/runtime-notes-client.test.ts
 delete mode 100644 src/renderer/src/runtime/runtime-notes-client.ts
 delete mode 100644 src/shared/notes-types.ts

diff --git a/src/cli/args.ts b/src/cli/args.ts
index 9af56d69065..59472dcd258 100644
--- a/src/cli/args.ts
+++ b/src/cli/args.ts
@@ -93,8 +93,7 @@ export function isCommandGroup(commandPath: string[]): boolean {
         'storage',
         'orchestration',
         'computer',
-        'environment',
-        'note'
+        'environment'
       ].includes(commandPath[0])) ||
     (commandPath.length === 2 &&
       commandPath[0] === 'storage' &&
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index 00896007067..a9adbadf543 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -15,7 +15,6 @@ import { BROWSER_STORAGE_HANDLERS } from './handlers/browser-storage'
 import { ORCHESTRATION_HANDLERS } from './handlers/orchestration'
 import { COMPUTER_HANDLERS } from './handlers/computer'
 import { ENVIRONMENT_HANDLERS } from './handlers/environment'
-import { NOTE_HANDLERS } from './handlers/note'
 
 export type HandlerContext = {
   flags: Map<string, string | boolean>
@@ -43,8 +42,7 @@ function buildHandlers(): Map<string, CommandHandler> {
     BROWSER_STORAGE_HANDLERS,
     ORCHESTRATION_HANDLERS,
     COMPUTER_HANDLERS,
-    ENVIRONMENT_HANDLERS,
-    NOTE_HANDLERS
+    ENVIRONMENT_HANDLERS
   ]
   for (const group of groups) {
     for (const [key, handler] of Object.entries(group)) {
diff --git a/src/cli/format.ts b/src/cli/format.ts
index 0b99b8bcae4..f032bb1803f 100644
--- a/src/cli/format.ts
+++ b/src/cli/format.ts
@@ -34,7 +34,6 @@ import type {
   RuntimeWorktreeRecord
 } from '../shared/runtime-types'
 import type { PublicKnownRuntimeEnvironment } from '../shared/runtime-environments'
-import type { NoteListResult, NoteMutationResult, NoteShowResult } from '../shared/notes-types'
 import type { RuntimeRpcFailure, RuntimeRpcSuccess } from './runtime-client'
 import { RuntimeClientError, RuntimeRpcFailureError } from './runtime-client'
 
@@ -208,39 +207,6 @@ export function formatTerminalWait(result: { wait: RuntimeTerminalWait }): strin
   ].join('\n')
 }
 
-export function formatNoteList(result: NoteListResult): string {
-  if (result.notes.length === 0) {
-    return 'No notes.'
-  }
-  const body = result.notes
-    .map((note) => {
-      const link = note.linkKind ? `  ${note.linkKind}` : ''
-      const preview = note.preview ? `\n${note.preview}` : ''
-      return `${note.id}  ${note.title}${link}\npath: ${note.relativePath}\nupdated: ${note.updatedAt}${preview}`
-    })
-    .join('\n\n')
-  return result.truncated
-    ? `${body}\n\ntruncated: showing ${result.notes.length} of ${result.totalCount}`
-    : body
-}
-
-export function formatNoteShow(result: NoteShowResult): string {
-  const link = result.linkKind ? `link: ${result.linkKind}` : 'link: none'
-  return [
-    `id: ${result.note.id}`,
-    `path: ${result.note.relativePath}`,
-    `title: ${result.note.title}`,
-    `revision: ${result.note.revision}`,
-    link,
-    '',
-    result.note.bodyMarkdown
-  ].join('\n')
-}
-
-export function formatNoteMutation(result: NoteMutationResult): string {
-  return `Saved note ${result.note.id} (${result.note.title}) revision ${result.note.revision}.`
-}
-
 export function formatWorktreePs(result: RuntimeWorktreePsResult): string {
   if (result.worktrees.length === 0) {
     return 'No worktrees found.'
diff --git a/src/cli/handlers/note.ts b/src/cli/handlers/note.ts
deleted file mode 100644
index 12ac16d1058..00000000000
--- a/src/cli/handlers/note.ts
+++ /dev/null
@@ -1,95 +0,0 @@
-import { readFileSync } from 'fs'
-import type { NoteListResult, NoteMutationResult, NoteShowResult } from '../../shared/notes-types'
-import type { CommandHandler } from '../dispatch'
-import { formatNoteList, formatNoteMutation, formatNoteShow, printResult } from '../format'
-import {
-  getOptionalPositiveIntegerFlag,
-  getOptionalStringFlag,
-  getRequiredStringFlag
-} from '../flags'
-import { RuntimeClientError } from '../runtime-client'
-import { getBrowserWorktreeSelector } from '../selectors'
-
-async function getNoteWorktreeSelector(
-  flags: Map<string, string | boolean>,
-  cwd: string,
-  client: Parameters<CommandHandler>[0]['client']
-): Promise<string> {
-  const worktree = await getBrowserWorktreeSelector(flags, cwd, client)
-  if (!worktree) {
-    throw new RuntimeClientError(
-      'selector_not_found',
-      'No Orca-managed worktree contains the current directory. Pass --worktree.'
-    )
-  }
-  return worktree
-}
-
-function readBody(flags: Map<string, string | boolean>, required: boolean): string | undefined {
-  const body = getOptionalStringFlag(flags, 'body')
-  const bodyFile = getOptionalStringFlag(flags, 'body-file')
-  const bodyStdin = flags.get('body-stdin') === true
-  const specified = [body !== undefined, bodyFile !== undefined, bodyStdin].filter(Boolean).length
-  if (specified > 1) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      'Pass only one of --body, --body-file, or --body-stdin'
-    )
-  }
-  if (body !== undefined) {
-    return body
-  }
-  if (bodyFile) {
-    return readFileSync(bodyFile, 'utf8')
-  }
-  if (bodyStdin) {
-    return readFileSync(0, 'utf8')
-  }
-  if (required) {
-    throw new RuntimeClientError('invalid_argument', 'Missing note body')
-  }
-  return undefined
-}
-
-export const NOTE_HANDLERS: Record<string, CommandHandler> = {
-  'note list': async ({ flags, client, cwd, json }) => {
-    const result = await client.call<NoteListResult>('note.list', {
-      worktree: await getNoteWorktreeSelector(flags, cwd, client),
-      limit: getOptionalPositiveIntegerFlag(flags, 'limit')
-    })
-    printResult(result, json, formatNoteList)
-  },
-  'note show': async ({ flags, client, cwd, json }) => {
-    const result = await client.call<NoteShowResult>('note.show', {
-      worktree: await getNoteWorktreeSelector(flags, cwd, client),
-      note: getRequiredStringFlag(flags, 'note')
-    })
-    printResult(result, json, formatNoteShow)
-  },
-  'note create': async ({ flags, client, cwd, json }) => {
-    const result = await client.call<NoteMutationResult>('note.create', {
-      worktree: await getNoteWorktreeSelector(flags, cwd, client),
-      title: getRequiredStringFlag(flags, 'title'),
-      bodyMarkdown: readBody(flags, false),
-      makeActive: true
-    })
-    printResult(result, json, formatNoteMutation)
-  },
-  'note append': async ({ flags, client, cwd, json }) => {
-    const result = await client.call<NoteMutationResult>('note.append', {
-      worktree: await getNoteWorktreeSelector(flags, cwd, client),
-      note: getRequiredStringFlag(flags, 'note'),
-      bodyMarkdown: readBody(flags, true),
-      makeActive: true
-    })
-    printResult(result, json, formatNoteMutation)
-  },
-  'note search': async ({ flags, client, cwd, json }) => {
-    const result = await client.call<NoteListResult>('note.search', {
-      worktree: await getNoteWorktreeSelector(flags, cwd, client),
-      query: getRequiredStringFlag(flags, 'query'),
-      limit: getOptionalPositiveIntegerFlag(flags, 'limit')
-    })
-    printResult(result, json, formatNoteList)
-  }
-}
diff --git a/src/cli/specs/index.ts b/src/cli/specs/index.ts
index ebcbb022fcd..48c05a44142 100644
--- a/src/cli/specs/index.ts
+++ b/src/cli/specs/index.ts
@@ -5,7 +5,6 @@ import { CORE_COMMAND_SPECS } from './core'
 import { ORCHESTRATION_COMMAND_SPECS } from './orchestration'
 import { COMPUTER_COMMAND_SPECS } from './computer'
 import { ENVIRONMENT_COMMAND_SPECS } from './environment'
-import { NOTE_COMMAND_SPECS } from './note'
 
 export const COMMAND_SPECS: CommandSpec[] = [
   ...CORE_COMMAND_SPECS,
@@ -13,6 +12,5 @@ export const COMMAND_SPECS: CommandSpec[] = [
   ...BROWSER_ADVANCED_COMMAND_SPECS,
   ...ORCHESTRATION_COMMAND_SPECS,
   ...COMPUTER_COMMAND_SPECS,
-  ...ENVIRONMENT_COMMAND_SPECS,
-  ...NOTE_COMMAND_SPECS
+  ...ENVIRONMENT_COMMAND_SPECS
 ]
diff --git a/src/cli/specs/note.ts b/src/cli/specs/note.ts
deleted file mode 100644
index 6b4d6e4122c..00000000000
--- a/src/cli/specs/note.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import type { CommandSpec } from '../args'
-import { GLOBAL_FLAGS } from '../args'
-
-export const NOTE_COMMAND_SPECS: CommandSpec[] = [
-  {
-    path: ['note', 'list'],
-    summary: 'List project notes for the current Orca worktree',
-    usage: 'orca note list [--worktree <selector>] [--limit <n>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'worktree', 'limit']
-  },
-  {
-    path: ['note', 'show'],
-    summary: 'Show a project note',
-    usage: 'orca note show --note <selector> [--worktree <selector>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'note', 'worktree']
-  },
-  {
-    path: ['note', 'create'],
-    summary: 'Create a project note',
-    usage:
-      'orca note create --title <title> [--body <text>|--body-file <path>|--body-stdin] [--worktree <selector>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'title', 'body', 'body-file', 'body-stdin', 'worktree']
-  },
-  {
-    path: ['note', 'append'],
-    summary: 'Append Markdown to a project note',
-    usage:
-      'orca note append --note <selector> [--body <text>|--body-file <path>|--body-stdin] [--worktree <selector>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'note', 'body', 'body-file', 'body-stdin', 'worktree']
-  },
-  {
-    path: ['note', 'search'],
-    summary: 'Search project notes',
-    usage: 'orca note search --query <text> [--worktree <selector>] [--limit <n>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'query', 'worktree', 'limit']
-  }
-]
diff --git a/src/main/ipc/notes.ts b/src/main/ipc/notes.ts
deleted file mode 100644
index 88829ead892..00000000000
--- a/src/main/ipc/notes.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { ipcMain } from 'electron'
-import type { OrcaRuntimeService } from '../runtime/orca-runtime'
-import type {
-  NoteAppendArgs,
-  NoteCreateArgs,
-  NoteDeleteArgs,
-  NoteLinkArgs,
-  NoteListArgs,
-  NoteRenameArgs,
-  NoteSaveArgs,
-  NoteSearchArgs,
-  NoteShowArgs,
-  NotesPanelStateArgs
-} from '../../shared/notes-types'
-
-export function registerNotesHandlers(runtime: OrcaRuntimeService): void {
-  ipcMain.removeHandler('notes:list')
-  ipcMain.removeHandler('notes:show')
-  ipcMain.removeHandler('notes:create')
-  ipcMain.removeHandler('notes:save')
-  ipcMain.removeHandler('notes:rename')
-  ipcMain.removeHandler('notes:delete')
-  ipcMain.removeHandler('notes:append')
-  ipcMain.removeHandler('notes:search')
-  ipcMain.removeHandler('notes:link')
-  ipcMain.removeHandler('notes:panelState')
-
-  ipcMain.handle('notes:list', (_event, args: NoteListArgs) => runtime.listProjectNotes(args))
-  ipcMain.handle('notes:show', (_event, args: NoteShowArgs) => runtime.showProjectNote(args))
-  ipcMain.handle('notes:create', (_event, args: NoteCreateArgs) => runtime.createProjectNote(args))
-  ipcMain.handle('notes:save', (_event, args: NoteSaveArgs) => runtime.saveProjectNote(args))
-  ipcMain.handle('notes:rename', (_event, args: NoteRenameArgs) => runtime.renameProjectNote(args))
-  ipcMain.handle('notes:delete', (_event, args: NoteDeleteArgs) => runtime.deleteProjectNote(args))
-  ipcMain.handle('notes:append', (_event, args: NoteAppendArgs) => runtime.appendProjectNote(args))
-  ipcMain.handle('notes:search', (_event, args: NoteSearchArgs) => runtime.searchProjectNotes(args))
-  ipcMain.handle('notes:link', (_event, args: NoteLinkArgs) => runtime.linkProjectNote(args))
-  ipcMain.handle('notes:panelState', (_event, args: NotesPanelStateArgs) =>
-    runtime.resolveNotesPanelOpenState(args)
-  )
-}
diff --git a/src/main/ipc/register-core-handlers.test.ts b/src/main/ipc/register-core-handlers.test.ts
index 7ff589620fc..f81db6fddf8 100644
--- a/src/main/ipc/register-core-handlers.test.ts
+++ b/src/main/ipc/register-core-handlers.test.ts
@@ -12,7 +12,6 @@ const {
   registerStatsHandlersMock,
   registerMemoryHandlersMock,
   registerNotebookHandlersMock,
-  registerNotesHandlersMock,
   registerNotificationHandlersMock,
   registerDeveloperPermissionHandlersMock,
   registerComputerUsePermissionHandlersMock,
@@ -54,7 +53,6 @@ const {
   registerStatsHandlersMock: vi.fn(),
   registerMemoryHandlersMock: vi.fn(),
   registerNotebookHandlersMock: vi.fn(),
-  registerNotesHandlersMock: vi.fn(),
   registerNotificationHandlersMock: vi.fn(),
   registerDeveloperPermissionHandlersMock: vi.fn(),
   registerComputerUsePermissionHandlersMock: vi.fn(),
@@ -136,10 +134,6 @@ vi.mock('./notebook', () => ({
   registerNotebookHandlers: registerNotebookHandlersMock
 }))
 
-vi.mock('./notes', () => ({
-  registerNotesHandlers: registerNotesHandlersMock
-}))
-
 vi.mock('./notifications', () => ({
   registerNotificationHandlers: registerNotificationHandlersMock
 }))
@@ -256,7 +250,6 @@ describe('registerCoreHandlers', () => {
     registerStatsHandlersMock.mockReset()
     registerMemoryHandlersMock.mockReset()
     registerNotebookHandlersMock.mockReset()
-    registerNotesHandlersMock.mockReset()
     registerNotificationHandlersMock.mockReset()
     registerDeveloperPermissionHandlersMock.mockReset()
     registerComputerUsePermissionHandlersMock.mockReset()
diff --git a/src/main/ipc/register-core-handlers.ts b/src/main/ipc/register-core-handlers.ts
index b6d87da3947..f3e5bcce61a 100644
--- a/src/main/ipc/register-core-handlers.ts
+++ b/src/main/ipc/register-core-handlers.ts
@@ -22,7 +22,6 @@ import { registerMemoryHandlers } from './memory'
 import { registerRateLimitHandlers } from './rate-limits'
 import { registerRuntimeHandlers } from './runtime'
 import { registerRuntimeEnvironmentHandlers } from './runtime-environments'
-import { registerNotesHandlers } from './notes'
 import { registerNotificationHandlers } from './notifications'
 import { registerNotebookHandlers } from './notebook'
 import { registerOnboardingHandlers } from './onboarding'
@@ -132,7 +131,6 @@ export function registerCoreHandlers(
   registerFilesystemWatcherHandlers()
   registerRuntimeHandlers(runtime)
   registerRuntimeEnvironmentHandlers()
-  registerNotesHandlers(runtime)
   registerClipboardHandlers()
   registerUpdaterHandlers(store)
   registerSpeechHandlers(store)
diff --git a/src/main/ipc/worktrees.test.ts b/src/main/ipc/worktrees.test.ts
index 4a0de9b6e97..ab70a164fef 100644
--- a/src/main/ipc/worktrees.test.ts
+++ b/src/main/ipc/worktrees.test.ts
@@ -166,7 +166,6 @@ describe('registerWorktreeHandlers', () => {
     recordOptimisticReconcileToken: ReturnType<typeof vi.fn>
     reconcileWorktreeBaseStatus: ReturnType<typeof vi.fn>
     clearOptimisticReconcileToken: ReturnType<typeof vi.fn>
-    unlinkNotesWorktree: ReturnType<typeof vi.fn>
   }
 
   beforeEach(() => {
@@ -302,8 +301,7 @@ describe('registerWorktreeHandlers', () => {
       emitWorktreeBaseStatus: vi.fn(),
       recordOptimisticReconcileToken: vi.fn().mockReturnValue('token-1'),
       reconcileWorktreeBaseStatus: vi.fn(),
-      clearOptimisticReconcileToken: vi.fn(),
-      unlinkNotesWorktree: vi.fn().mockResolvedValue(undefined)
+      clearOptimisticReconcileToken: vi.fn()
     }
     registerWorktreeHandlers(mainWindow as never, store as never, runtimeStub as never)
   })
diff --git a/src/main/ipc/worktrees.ts b/src/main/ipc/worktrees.ts
index 8bb2b01494a..70b749c56e2 100644
--- a/src/main/ipc/worktrees.ts
+++ b/src/main/ipc/worktrees.ts
@@ -564,7 +564,6 @@ export function registerWorktreeHandlers(
       if (repo.connectionId) {
         await provider!.removeWorktree(canonicalWorktreePath, args.force)
         runtime.clearOptimisticReconcileToken(args.worktreeId)
-        await runtime.unlinkNotesWorktree(repoId, args.worktreeId)
         store.removeWorktreeMeta(args.worktreeId)
         deleteWorktreeHistoryDir(args.worktreeId)
         notifyWorktreesChanged(mainWindow, repoId)
@@ -610,7 +609,6 @@ export function registerWorktreeHandlers(
           // remains locked — other worktrees cannot check it out.
           await gitExecFileAsync(['worktree', 'prune'], { cwd: repo.path }).catch(() => {})
           runtime.clearOptimisticReconcileToken(args.worktreeId)
-          await runtime.unlinkNotesWorktree(repoId, args.worktreeId)
           store.removeWorktreeMeta(args.worktreeId)
           deleteWorktreeHistoryDir(args.worktreeId)
           invalidateAuthorizedRootsCache()
@@ -622,7 +620,6 @@ export function registerWorktreeHandlers(
         )
       }
       runtime.clearOptimisticReconcileToken(args.worktreeId)
-      await runtime.unlinkNotesWorktree(repoId, args.worktreeId)
       store.removeWorktreeMeta(args.worktreeId)
       deleteWorktreeHistoryDir(args.worktreeId)
       invalidateAuthorizedRootsCache()
diff --git a/src/main/notes/notes-markdown-store.test.ts b/src/main/notes/notes-markdown-store.test.ts
deleted file mode 100644
index 62793f2f4c1..00000000000
--- a/src/main/notes/notes-markdown-store.test.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import { mkdtemp, rm } from 'fs/promises'
-import { tmpdir } from 'os'
-import { join } from 'path'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { NotesMarkdownStore } from './notes-markdown-store'
-
-describe('NotesMarkdownStore mutations', () => {
-  let rootPath: string
-  let store: NotesMarkdownStore
-
-  beforeEach(async () => {
-    rootPath = await mkdtemp(join(tmpdir(), 'orca-notes-store-'))
-    store = new NotesMarkdownStore()
-  })
-
-  afterEach(async () => {
-    await rm(rootPath, { force: true, recursive: true })
-  })
-
-  it('renames the markdown file and keeps the note id stable', async () => {
-    const created = await store.create(
-      { projectId: 'repo-1', rootPath },
-      {
-        projectId: 'repo-1',
-        worktreeId: 'wt-1',
-        title: 'First note',
-        bodyMarkdown: 'body'
-      }
-    )
-
-    const renamed = await store.rename(
-      { projectId: 'repo-1', rootPath },
-      {
-        projectId: 'repo-1',
-        worktreeId: 'wt-1',
-        note: created.note.id,
-        title: 'Renamed note'
-      }
-    )
-
-    expect(renamed.note.id).toBe(created.note.id)
-    expect(renamed.note.title).toBe('Renamed note')
-    expect(renamed.note.relativePath).toContain('renamed-note')
-
-    const listed = await store.list(
-      { projectId: 'repo-1', rootPath },
-      { projectId: 'repo-1', worktreeId: 'wt-1' }
-    )
-    expect(listed.notes).toHaveLength(1)
-    expect(listed.notes[0].title).toBe('Renamed note')
-    expect(listed.notes[0].linkKind).toBe('active')
-  })
-
-  it('deletes the markdown file and clears worktree links', async () => {
-    const created = await store.create(
-      { projectId: 'repo-1', rootPath },
-      {
-        projectId: 'repo-1',
-        worktreeId: 'wt-1',
-        title: 'Delete me',
-        bodyMarkdown: 'body'
-      }
-    )
-
-    await store.delete(
-      { projectId: 'repo-1', rootPath },
-      { projectId: 'repo-1', worktreeId: 'wt-1', note: created.note.id }
-    )
-
-    const listed = await store.list(
-      { projectId: 'repo-1', rootPath },
-      { projectId: 'repo-1', worktreeId: 'wt-1' }
-    )
-    expect(listed.notes).toEqual([])
-  })
-})
diff --git a/src/main/notes/notes-markdown-store.ts b/src/main/notes/notes-markdown-store.ts
deleted file mode 100644
index 1cac4546c24..00000000000
--- a/src/main/notes/notes-markdown-store.ts
+++ /dev/null
@@ -1,586 +0,0 @@
-/* eslint-disable max-lines -- Why: note file serialization, index updates, and selector resolution need one persistence boundary so Markdown files stay user-owned without splitting active-link invariants across modules. */
-import { randomBytes } from 'crypto'
-import { mkdir, readFile, readdir, rename, rm, writeFile } from 'fs/promises'
-import { join, posix } from 'path'
-import type { IFilesystemProvider } from '../providers/types'
-import type {
-  NoteAppendArgs,
-  NoteCreateArgs,
-  NoteDeleteArgs,
-  NoteDeleteResult,
-  NoteLink,
-  NoteLinkArgs,
-  NoteLinkKind,
-  NoteListArgs,
-  NoteListResult,
-  NoteMutationResult,
-  NoteRecord,
-  NoteRenameArgs,
-  NoteSaveArgs,
-  NoteSearchArgs,
-  NoteShowArgs,
-  NoteShowResult,
-  NoteSummary,
-  NotesPanelOpenState,
-  NotesPanelStateArgs
-} from '../../shared/notes-types'
-
-type NotesMarkdownScope = {
-  projectId: string
-  rootPath: string
-  connectionId?: string | null
-  provider?: IFilesystemProvider
-}
-
-type NotesIndex = {
-  version: 1
-  activeByWorktree: Record<string, string>
-  referencedByWorktree: Record<string, string[]>
-}
-
-type NoteFrontMatter = {
-  id: string
-  title: string
-  createdAt: string
-  updatedAt: string
-  archivedAt: string | null
-  createdBySessionId: string | null
-  updatedBySessionId: string | null
-  revision: number
-}
-
-const NOTES_DIR = 'notes'
-const INDEX_FILE = 'index.json'
-const DEFAULT_LIMIT = 50
-const MAX_LIMIT = 200
-
-function nowIso(): string {
-  return new Date().toISOString()
-}
-
-function generateId(): string {
-  return `note_${randomBytes(8).toString('hex')}`
-}
-
-function clampLimit(limit: number | undefined): number {
-  if (!Number.isFinite(limit) || limit === undefined) {
-    return DEFAULT_LIMIT
-  }
-  return Math.max(1, Math.min(MAX_LIMIT, Math.floor(limit)))
-}
-
-function pathJoin(scope: NotesMarkdownScope, ...parts: string[]): string {
-  return scope.connectionId ? posix.join(scope.rootPath, ...parts) : join(scope.rootPath, ...parts)
-}
-
-function slugTitle(title: string): string {
-  const slug = title
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-  return slug || 'untitled-note'
-}
-
-function isMissingFile(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    'code' in error &&
-    ((error as NodeJS.ErrnoException).code === 'ENOENT' ||
-      (error as NodeJS.ErrnoException).code === 'ENOTDIR')
-  )
-}
-
-function emptyIndex(): NotesIndex {
-  return {
-    version: 1,
-    activeByWorktree: {},
-    referencedByWorktree: {}
-  }
-}
-
-function notePreview(bodyMarkdown: string): string {
-  return bodyMarkdown.replace(/\s+/g, ' ').trim().slice(0, 180)
-}
-
-function parseFrontMatterValue(raw: string): string | number | null {
-  const value = raw.trim()
-  if (value === 'null') {
-    return null
-  }
-  if (/^\d+$/.test(value)) {
-    return Number.parseInt(value, 10)
-  }
-  if (value.startsWith('"')) {
-    return JSON.parse(value) as string
-  }
-  return value
-}
-
-function parseNoteFile(
-  projectId: string,
-  filePath: string,
-  relativePath: string,
-  raw: string
-): NoteRecord {
-  if (!raw.startsWith('---\n')) {
-    throw new Error('invalid_note_file')
-  }
-  const end = raw.indexOf('\n---\n', 4)
-  if (end === -1) {
-    throw new Error('invalid_note_file')
-  }
-  const frontMatter = raw.slice(4, end)
-  const bodyMarkdown = raw.slice(end + 5)
-  const parsed: Partial<NoteFrontMatter> = {}
-  for (const line of frontMatter.split('\n')) {
-    const index = line.indexOf(':')
-    if (index === -1) {
-      continue
-    }
-    const key = line.slice(0, index).trim() as keyof NoteFrontMatter
-    const value = parseFrontMatterValue(line.slice(index + 1))
-    ;(parsed as Record<string, unknown>)[key] = value
-  }
-  if (!parsed.id || !parsed.title || !parsed.createdAt || !parsed.updatedAt) {
-    throw new Error('invalid_note_file')
-  }
-  return {
-    id: parsed.id,
-    projectId,
-    filePath,
-    relativePath,
-    title: parsed.title,
-    bodyMarkdown,
-    revision: typeof parsed.revision === 'number' ? parsed.revision : 1,
-    createdAt: parsed.createdAt,
-    updatedAt: parsed.updatedAt,
-    archivedAt: parsed.archivedAt ?? null,
-    createdBySessionId: parsed.createdBySessionId ?? null,
-    updatedBySessionId: parsed.updatedBySessionId ?? null
-  }
-}
-
-function serializeNote(note: NoteRecord): string {
-  const frontMatter: NoteFrontMatter = {
-    id: note.id,
-    title: note.title,
-    createdAt: note.createdAt,
-    updatedAt: note.updatedAt,
-    archivedAt: note.archivedAt,
-    createdBySessionId: note.createdBySessionId ?? null,
-    updatedBySessionId: note.updatedBySessionId ?? null,
-    revision: note.revision
-  }
-  const lines = Object.entries(frontMatter).map(([key, value]) => {
-    if (typeof value === 'string') {
-      return `${key}: ${JSON.stringify(value)}`
-    }
-    return `${key}: ${value === null ? 'null' : value}`
-  })
-  return `---\n${lines.join('\n')}\n---\n${note.bodyMarkdown}`
-}
-
-function linkKindForNote(
-  index: NotesIndex,
-  noteId: string,
-  worktreeId?: string | null
-): NoteLinkKind | null {
-  if (!worktreeId) {
-    return null
-  }
-  if (index.activeByWorktree[worktreeId] === noteId) {
-    return 'active'
-  }
-  if ((index.referencedByWorktree[worktreeId] ?? []).includes(noteId)) {
-    return 'referenced'
-  }
-  return null
-}
-
-function toSummary(note: NoteRecord, index: NotesIndex, worktreeId?: string | null): NoteSummary {
-  return {
-    ...note,
-    preview: notePreview(note.bodyMarkdown),
-    linkKind: linkKindForNote(index, note.id, worktreeId)
-  }
-}
-
-export class NotesMarkdownStore {
-  async list(scope: NotesMarkdownScope, args: NoteListArgs): Promise<NoteListResult> {
-    const limit = clampLimit(args.limit)
-    const [notes, index] = await Promise.all([this.readNotes(scope), this.readIndex(scope)])
-    const visible = notes
-      .filter((note) => note.archivedAt === null)
-      .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
-    const sorted = visible.sort((left, right) => {
-      const leftLink = linkKindForNote(index, left.id, args.worktreeId)
-      const rightLink = linkKindForNote(index, right.id, args.worktreeId)
-      const rank = (kind: NoteLinkKind | null): number =>
-        kind === 'active' ? 0 : kind === 'referenced' ? 1 : 2
-      return rank(leftLink) - rank(rightLink) || right.updatedAt.localeCompare(left.updatedAt)
-    })
-    return {
-      notes: sorted.slice(0, limit).map((note) => toSummary(note, index, args.worktreeId)),
-      totalCount: sorted.length,
-      truncated: sorted.length > limit
-    }
-  }
-
-  async show(scope: NotesMarkdownScope, args: NoteShowArgs): Promise<NoteShowResult> {
-    const [note, index] = await Promise.all([
-      this.resolveNote(scope, args.note),
-      this.readIndex(scope)
-    ])
-    return {
-      note,
-      linkKind: linkKindForNote(index, note.id, args.worktreeId)
-    }
-  }
-
-  async create(scope: NotesMarkdownScope, args: NoteCreateArgs): Promise<NoteMutationResult> {
-    const at = nowIso()
-    const id = generateId()
-    const title = args.title.trim() || 'Untitled note'
-    const note: NoteRecord = {
-      id,
-      projectId: scope.projectId,
-      filePath: this.notePath(scope, title, id),
-      relativePath: posix.join(NOTES_DIR, `${slugTitle(title)}-${id}.md`),
-      title,
-      bodyMarkdown: args.bodyMarkdown ?? '',
-      revision: 1,
-      createdAt: at,
-      updatedAt: at,
-      archivedAt: null,
-      createdBySessionId: args.createdBySessionId ?? null,
-      updatedBySessionId: args.createdBySessionId ?? null
-    }
-    await this.writeNote(scope, note)
-    if (args.makeActive !== false && args.worktreeId) {
-      await this.setLink(scope, {
-        projectId: args.projectId,
-        worktreeId: args.worktreeId,
-        note: note.id,
-        kind: 'active'
-      })
-    }
-    const index = await this.readIndex(scope)
-    return {
-      note,
-      linkKind: linkKindForNote(index, note.id, args.worktreeId)
-    }
-  }
-
-  async save(scope: NotesMarkdownScope, args: NoteSaveArgs): Promise<NoteMutationResult> {
-    const current = await this.resolveNote(scope, args.note)
-    if (args.revision !== undefined && args.revision !== current.revision) {
-      throw new Error('revision_conflict')
-    }
-    const next: NoteRecord = {
-      ...current,
-      title: args.title?.trim() || current.title,
-      bodyMarkdown: args.bodyMarkdown,
-      revision: current.revision + 1,
-      updatedAt: nowIso(),
-      updatedBySessionId: args.updatedBySessionId ?? null
-    }
-    await this.writeNote(scope, next)
-    if (args.makeActive === true && args.worktreeId) {
-      await this.setLink(scope, {
-        projectId: args.projectId,
-        worktreeId: args.worktreeId,
-        note: next.id,
-        kind: 'active'
-      })
-    }
-    const index = await this.readIndex(scope)
-    return {
-      note: next,
-      linkKind: linkKindForNote(index, next.id, args.worktreeId)
-    }
-  }
-
-  async rename(scope: NotesMarkdownScope, args: NoteRenameArgs): Promise<NoteMutationResult> {
-    const current = await this.resolveNote(scope, args.note)
-    const title = args.title.trim()
-    if (!title) {
-      throw new Error('invalid_note_title')
-    }
-    const nextPath = this.notePath(scope, title, current.id)
-    const nextRelativePath = posix.join(NOTES_DIR, `${slugTitle(title)}-${current.id}.md`)
-    const next: NoteRecord = {
-      ...current,
-      filePath: nextPath,
-      relativePath: nextRelativePath,
-      title,
-      revision: current.revision + 1,
-      updatedAt: nowIso(),
-      updatedBySessionId: args.updatedBySessionId ?? null
-    }
-    if (next.filePath !== current.filePath) {
-      await this.renamePath(scope, current.filePath, next.filePath)
-    }
-    await this.writeNote(scope, next)
-    const index = await this.readIndex(scope)
-    return {
-      note: next,
-      linkKind: linkKindForNote(index, next.id, args.worktreeId)
-    }
-  }
-
-  async delete(scope: NotesMarkdownScope, args: NoteDeleteArgs): Promise<NoteDeleteResult> {
-    const note = await this.resolveNote(scope, args.note)
-    await this.deletePath(scope, note.filePath)
-    const index = await this.readIndex(scope)
-    for (const [worktreeId, noteId] of Object.entries(index.activeByWorktree)) {
-      if (noteId === note.id) {
-        delete index.activeByWorktree[worktreeId]
-      }
-    }
-    for (const [worktreeId, noteIds] of Object.entries(index.referencedByWorktree)) {
-      const next = noteIds.filter((noteId) => noteId !== note.id)
-      if (next.length === 0) {
-        delete index.referencedByWorktree[worktreeId]
-      } else {
-        index.referencedByWorktree[worktreeId] = next
-      }
-    }
-    await this.writeIndex(scope, index)
-    return {
-      noteId: note.id,
-      projectId: scope.projectId
-    }
-  }
-
-  async append(scope: NotesMarkdownScope, args: NoteAppendArgs): Promise<NoteMutationResult> {
-    const current = await this.resolveNote(scope, args.note)
-    const separator = current.bodyMarkdown.trim().length > 0 ? '\n\n' : ''
-    return await this.save(scope, {
-      projectId: args.projectId,
-      worktreeId: args.worktreeId,
-      note: current.id,
-      title: current.title,
-      bodyMarkdown: `${current.bodyMarkdown}${separator}${args.bodyMarkdown}`,
-      makeActive: args.makeActive,
-      updatedBySessionId: args.updatedBySessionId
-    })
-  }
-
-  async search(scope: NotesMarkdownScope, args: NoteSearchArgs): Promise<NoteListResult> {
-    const limit = clampLimit(args.limit)
-    const query = args.query.trim().toLowerCase()
-    const [notes, index] = await Promise.all([this.readNotes(scope), this.readIndex(scope)])
-    const matches = notes
-      .filter(
-        (note) =>
-          note.archivedAt === null &&
-          (note.title.toLowerCase().includes(query) ||
-            note.bodyMarkdown.toLowerCase().includes(query))
-      )
-      .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
-    return {
-      notes: matches.slice(0, limit).map((note) => toSummary(note, index, args.worktreeId)),
-      totalCount: matches.length,
-      truncated: matches.length > limit
-    }
-  }
-
-  async setLink(scope: NotesMarkdownScope, args: NoteLinkArgs): Promise<NoteLink> {
-    const note = await this.resolveNote(scope, args.note)
-    const index = await this.readIndex(scope)
-    if (args.kind === 'active') {
-      index.activeByWorktree[args.worktreeId] = note.id
-    } else {
-      const existing = index.referencedByWorktree[args.worktreeId] ?? []
-      index.referencedByWorktree[args.worktreeId] = Array.from(new Set([...existing, note.id]))
-    }
-    await this.writeIndex(scope, index)
-    return {
-      noteId: note.id,
-      projectId: args.projectId,
-      worktreeId: args.worktreeId,
-      kind: args.kind,
-      createdAt: nowIso()
-    }
-  }
-
-  async unlinkWorktree(scope: NotesMarkdownScope, worktreeId: string): Promise<void> {
-    const index = await this.readIndex(scope)
-    delete index.activeByWorktree[worktreeId]
-    delete index.referencedByWorktree[worktreeId]
-    await this.writeIndex(scope, index)
-  }
-
-  async resolvePanelOpenState(
-    scope: NotesMarkdownScope | null,
-    args: NotesPanelStateArgs
-  ): Promise<NotesPanelOpenState> {
-    if (!scope || !args.projectId) {
-      return { state: 'noProject' }
-    }
-    const [notes, index] = await Promise.all([this.readNotes(scope), this.readIndex(scope)])
-    if (args.worktreeId) {
-      const activeId = index.activeByWorktree[args.worktreeId]
-      const active = notes.find((note) => note.id === activeId && note.archivedAt === null)
-      if (active) {
-        return {
-          state: 'active',
-          projectId: args.projectId,
-          worktreeId: args.worktreeId,
-          note: active
-        }
-      }
-    }
-    const summaries = notes
-      .filter((note) => note.archivedAt === null)
-      .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
-      .map((note) => toSummary(note, index, args.worktreeId))
-    if (summaries.length > 0) {
-      return {
-        state: 'pickerRequired',
-        projectId: args.projectId,
-        worktreeId: args.worktreeId ?? null,
-        notes: summaries
-      }
-    }
-    return {
-      state: 'emptyDraft',
-      projectId: args.projectId,
-      worktreeId: args.worktreeId ?? null
-    }
-  }
-
-  private notesDir(scope: NotesMarkdownScope): string {
-    return pathJoin(scope, NOTES_DIR)
-  }
-
-  private indexPath(scope: NotesMarkdownScope): string {
-    return pathJoin(scope, NOTES_DIR, INDEX_FILE)
-  }
-
-  private notePath(scope: NotesMarkdownScope, title: string, id: string): string {
-    return pathJoin(scope, NOTES_DIR, `${slugTitle(title)}-${id}.md`)
-  }
-
-  private async ensureNotesDir(scope: NotesMarkdownScope): Promise<void> {
-    if (scope.provider) {
-      await scope.provider.createDir(this.notesDir(scope))
-      return
-    }
-    await mkdir(this.notesDir(scope), { recursive: true })
-  }
-
-  private async readText(scope: NotesMarkdownScope, filePath: string): Promise<string> {
-    if (scope.provider) {
-      return (await scope.provider.readFile(filePath)).content
-    }
-    return await readFile(filePath, 'utf8')
-  }
-
-  private async writeText(
-    scope: NotesMarkdownScope,
-    filePath: string,
-    content: string
-  ): Promise<void> {
-    await this.ensureNotesDir(scope)
-    if (scope.provider) {
-      await scope.provider.writeFile(filePath, content)
-      return
-    }
-    await writeFile(filePath, content, 'utf8')
-  }
-
-  private async renamePath(
-    scope: NotesMarkdownScope,
-    oldPath: string,
-    newPath: string
-  ): Promise<void> {
-    await this.ensureNotesDir(scope)
-    if (scope.provider) {
-      await scope.provider.rename(oldPath, newPath)
-      return
-    }
-    await rename(oldPath, newPath)
-  }
-
-  private async deletePath(scope: NotesMarkdownScope, filePath: string): Promise<void> {
-    if (scope.provider) {
-      await scope.provider.deletePath(filePath)
-      return
-    }
-    await rm(filePath, { force: true })
-  }
-
-  private async readIndex(scope: NotesMarkdownScope): Promise<NotesIndex> {
-    try {
-      const raw = await this.readText(scope, this.indexPath(scope))
-      const parsed = JSON.parse(raw) as Partial<NotesIndex>
-      return {
-        version: 1,
-        activeByWorktree: parsed.activeByWorktree ?? {},
-        referencedByWorktree: parsed.referencedByWorktree ?? {}
-      }
-    } catch (error) {
-      if (isMissingFile(error)) {
-        return emptyIndex()
-      }
-      throw error
-    }
-  }
-
-  private async writeIndex(scope: NotesMarkdownScope, index: NotesIndex): Promise<void> {
-    await this.writeText(scope, this.indexPath(scope), `${JSON.stringify(index, null, 2)}\n`)
-  }
-
-  private async readNotes(scope: NotesMarkdownScope): Promise<NoteRecord[]> {
-    let names: string[]
-    try {
-      if (scope.provider) {
-        const entries = await scope.provider.readDir(this.notesDir(scope))
-        names = entries.filter((entry) => !entry.isDirectory).map((entry) => entry.name)
-      } else {
-        names = await readdir(this.notesDir(scope))
-      }
-    } catch (error) {
-      if (isMissingFile(error)) {
-        return []
-      }
-      throw error
-    }
-    const files = names.filter((name) => name.endsWith('.md'))
-    const notes = await Promise.all(
-      files.map(async (name) => {
-        const filePath = pathJoin(scope, NOTES_DIR, name)
-        const relativePath = posix.join(NOTES_DIR, name)
-        const raw = await this.readText(scope, filePath)
-        return parseNoteFile(scope.projectId, filePath, relativePath, raw)
-      })
-    )
-    return notes
-  }
-
-  private async writeNote(scope: NotesMarkdownScope, note: NoteRecord): Promise<void> {
-    await this.writeText(scope, note.filePath, serializeNote(note))
-  }
-
-  private async resolveNote(scope: NotesMarkdownScope, selector: string): Promise<NoteRecord> {
-    const normalized = selector.trim().toLowerCase()
-    const notes = await this.readNotes(scope)
-    const matches = notes.filter(
-      (note) =>
-        note.archivedAt === null &&
-        (note.id === selector ||
-          note.title.toLowerCase() === normalized ||
-          note.relativePath === selector ||
-          note.filePath === selector)
-    )
-    if (matches.length === 0) {
-      throw new Error('note_not_found')
-    }
-    if (matches.length > 1) {
-      throw new Error('note_ambiguous')
-    }
-    return matches[0]
-  }
-}
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index d1b3f1b2e54..d84f393531d 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -19,19 +19,6 @@ import {
 } from '../providers/ssh-filesystem-dispatch'
 import { registerSshGitProvider, unregisterSshGitProvider } from '../providers/ssh-git-dispatch'
 
-vi.mock('electron', () => ({
-  app: {
-    getPath: vi.fn(() => '/tmp/orca-user-data')
-  },
-  BrowserWindow: {
-    fromId: vi.fn(() => null)
-  },
-  ipcMain: {
-    on: vi.fn(),
-    removeListener: vi.fn()
-  }
-}))
-
 const {
   MOCK_GIT_WORKTREES,
   addWorktreeMock,
@@ -2172,120 +2159,6 @@ describe('OrcaRuntimeService', () => {
     expect(activateWorktree).toHaveBeenCalledWith('repo-1', expect.any(String), result.setup)
   })
 
-  it('spawns startup and setup in runtime before revealing activated worktrees', async () => {
-    const runtime = new OrcaRuntimeService(store)
-    const activateWorktree = vi.fn()
-    const revealTerminalSession = vi.fn().mockResolvedValue({ tabId: 'tab-visible-worktree' })
-    const spawn = vi
-      .fn()
-      .mockResolvedValueOnce({ id: 'pty-visible-startup' })
-      .mockResolvedValueOnce({ id: 'pty-visible-setup' })
-    runtime.setPtyController({
-      spawn,
-      write: () => true,
-      kill: () => true,
-      getForegroundProcess: async () => null
-    })
-    runtime.setNotifier({
-      worktreesChanged: vi.fn(),
-      reposChanged: vi.fn(),
-      activateWorktree,
-      createTerminal: vi.fn(),
-      revealTerminalSession,
-      splitTerminal: vi.fn(),
-      renameTerminal: vi.fn(),
-      focusTerminal: vi.fn(),
-      closeTerminal: vi.fn(),
-      sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn(),
-      terminalDriverChanged: vi.fn()
-    })
-    runtime.attachWindow(1)
-
-    computeWorktreePathMock.mockReturnValue('/tmp/workspaces/runtime-startup-setup')
-    ensurePathWithinWorkspaceMock.mockReturnValue('/tmp/workspaces/runtime-startup-setup')
-    vi.mocked(getEffectiveHooks).mockReturnValue({
-      scripts: {
-        setup: 'pnpm worktree:setup'
-      }
-    })
-    vi.mocked(createSetupRunnerScript).mockReturnValue({
-      runnerScriptPath: '/tmp/repo/.git/orca/setup-runner.sh',
-      envVars: {
-        ORCA_ROOT_PATH: '/tmp/repo',
-        ORCA_WORKTREE_PATH: '/tmp/workspaces/runtime-startup-setup'
-      }
-    })
-    vi.mocked(listWorktrees).mockResolvedValue([
-      {
-        path: '/tmp/workspaces/runtime-startup-setup',
-        head: 'def',
-        branch: 'runtime-startup-setup',
-        isBare: false,
-        isMainWorktree: false
-      }
-    ])
-
-    const result = await runtime.createManagedWorktree({
-      repoSelector: 'id:repo-1',
-      name: 'runtime-startup-setup',
-      runHooks: true,
-      startup: {
-        command: 'codex --prompt "setup"',
-        env: {
-          ORCA_STARTUP_SETUP: '1'
-        }
-      }
-    })
-
-    expect(spawn).toHaveBeenCalledTimes(2)
-    expect(spawn).toHaveBeenNthCalledWith(
-      1,
-      expect.objectContaining({
-        cwd: '/tmp/workspaces/runtime-startup-setup',
-        command: 'codex --prompt "setup"',
-        env: expect.objectContaining({
-          ORCA_STARTUP_SETUP: '1'
-        }),
-        worktreeId: result.worktree.id
-      })
-    )
-    expect(spawn).toHaveBeenNthCalledWith(
-      2,
-      expect.objectContaining({
-        cwd: '/tmp/workspaces/runtime-startup-setup',
-        command: 'bash /tmp/repo/.git/orca/setup-runner.sh',
-        env: expect.objectContaining({
-          ORCA_ROOT_PATH: '/tmp/repo',
-          ORCA_WORKTREE_PATH: '/tmp/workspaces/runtime-startup-setup'
-        }),
-        worktreeId: result.worktree.id
-      })
-    )
-    expect(revealTerminalSession).toHaveBeenNthCalledWith(
-      1,
-      result.worktree.id,
-      expect.objectContaining({
-        ptyId: 'pty-visible-startup',
-        title: null,
-        activate: false
-      })
-    )
-    expect(revealTerminalSession).toHaveBeenNthCalledWith(
-      2,
-      result.worktree.id,
-      expect.objectContaining({
-        ptyId: 'pty-visible-setup',
-        title: 'Setup',
-        activate: false
-      })
-    )
-    expect(activateWorktree).toHaveBeenCalledWith('repo-1', result.worktree.id, undefined)
-    expect(revealTerminalSession.mock.invocationCallOrder[1]).toBeLessThan(
-      activateWorktree.mock.invocationCallOrder[0]
-    )
-  })
-
   it('follows normal setup policy for CLI-created worktrees without activating them', async () => {
     const runtime = new OrcaRuntimeService(store)
     const activateWorktree = vi.fn()
@@ -2469,79 +2342,6 @@ describe('OrcaRuntimeService', () => {
     })
   })
 
-  it('runs startup commands through background PTYs when worktree activation was not requested', async () => {
-    const runtime = new OrcaRuntimeService(store)
-    const activateWorktree = vi.fn()
-    const revealTerminalSession = vi.fn().mockResolvedValue({ tabId: 'tab-startup-worktree' })
-    const spawn = vi.fn().mockResolvedValue({ id: 'pty-startup-worktree' })
-    runtime.setPtyController({
-      spawn,
-      write: () => true,
-      kill: () => true,
-      getForegroundProcess: async () => null
-    })
-    runtime.setNotifier({
-      worktreesChanged: vi.fn(),
-      reposChanged: vi.fn(),
-      activateWorktree,
-      createTerminal: vi.fn(),
-      revealTerminalSession,
-      splitTerminal: vi.fn(),
-      renameTerminal: vi.fn(),
-      focusTerminal: vi.fn(),
-      closeTerminal: vi.fn(),
-      sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn(),
-      terminalDriverChanged: vi.fn()
-    })
-    runtime.attachWindow(1)
-
-    computeWorktreePathMock.mockReturnValue('/tmp/workspaces/runtime-startup-terminal')
-    ensurePathWithinWorkspaceMock.mockReturnValue('/tmp/workspaces/runtime-startup-terminal')
-    vi.mocked(getEffectiveHooks).mockReturnValue(null)
-    vi.mocked(listWorktrees).mockResolvedValue([
-      {
-        path: '/tmp/workspaces/runtime-startup-terminal',
-        head: 'def',
-        branch: 'runtime-startup-terminal',
-        isBare: false,
-        isMainWorktree: false
-      }
-    ])
-
-    const result = await runtime.createManagedWorktree({
-      repoSelector: 'id:repo-1',
-      name: 'runtime-startup-terminal',
-      startup: {
-        command: 'codex --prompt "summarize"',
-        env: {
-          ORCA_TEST_MODE: '1'
-        }
-      }
-    })
-
-    expect(activateWorktree).not.toHaveBeenCalled()
-    expect(spawn).toHaveBeenCalledWith(
-      expect.objectContaining({
-        cwd: '/tmp/workspaces/runtime-startup-terminal',
-        command: 'codex --prompt "summarize"',
-        env: expect.objectContaining({
-          ORCA_TEST_MODE: '1'
-        }),
-        worktreeId: result.worktree.id,
-        preAllocatedHandle: expect.stringMatching(/^term_/)
-      })
-    )
-    expect(revealTerminalSession).toHaveBeenCalledWith(
-      result.worktree.id,
-      expect.objectContaining({
-        ptyId: 'pty-startup-worktree',
-        title: null,
-        activate: false
-      })
-    )
-  })
-
   it('keeps CLI-created worktrees successful when initial terminal creation fails', async () => {
     const runtime = new OrcaRuntimeService(store)
     const spawn = vi.fn().mockRejectedValue(new Error('pty unavailable'))
@@ -2642,70 +2442,6 @@ describe('OrcaRuntimeService', () => {
     expect(activateWorktree).toHaveBeenCalledWith('repo-1', expect.any(String), undefined)
   })
 
-  it('spawns startup commands in runtime before revealing explicitly activated worktrees', async () => {
-    const runtime = new OrcaRuntimeService(store)
-    const activateWorktree = vi.fn()
-    const spawn = vi.fn().mockResolvedValue({ id: 'pty-visible-startup' })
-    runtime.setPtyController({
-      spawn,
-      write: () => true,
-      kill: () => true,
-      getForegroundProcess: async () => null
-    })
-    runtime.setNotifier({
-      worktreesChanged: vi.fn(),
-      reposChanged: vi.fn(),
-      activateWorktree,
-      createTerminal: vi.fn(),
-      revealTerminalSession: vi.fn(),
-      splitTerminal: vi.fn(),
-      renameTerminal: vi.fn(),
-      focusTerminal: vi.fn(),
-      closeTerminal: vi.fn(),
-      sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn(),
-      terminalDriverChanged: vi.fn()
-    })
-    runtime.attachWindow(1)
-
-    computeWorktreePathMock.mockReturnValue('/tmp/workspaces/runtime-visible-startup')
-    ensurePathWithinWorkspaceMock.mockReturnValue('/tmp/workspaces/runtime-visible-startup')
-    vi.mocked(getEffectiveHooks).mockReturnValue(null)
-    vi.mocked(listWorktrees).mockResolvedValue([
-      {
-        path: '/tmp/workspaces/runtime-visible-startup',
-        head: 'def',
-        branch: 'runtime-visible-startup',
-        isBare: false,
-        isMainWorktree: false
-      }
-    ])
-
-    const result = await runtime.createManagedWorktree({
-      repoSelector: 'id:repo-1',
-      name: 'runtime-visible-startup',
-      activate: true,
-      startup: {
-        command: 'claude --dangerously-skip-permissions',
-        env: {
-          ORCA_VISIBLE_STARTUP: '1'
-        }
-      }
-    })
-
-    expect(spawn).toHaveBeenCalledWith(
-      expect.objectContaining({
-        cwd: '/tmp/workspaces/runtime-visible-startup',
-        command: 'claude --dangerously-skip-permissions',
-        env: expect.objectContaining({
-          ORCA_VISIBLE_STARTUP: '1'
-        }),
-        worktreeId: result.worktree.id
-      })
-    )
-    expect(activateWorktree).toHaveBeenCalledWith('repo-1', result.worktree.id, undefined)
-  })
-
   it('stamps createdAt alongside lastActivityAt so CLI-created worktrees get the Recent-sort grace window', async () => {
     // Why: parity with createLocalWorktree / createRemoteWorktree. Without
     // createdAt, ambient PTY bumps in OTHER worktrees during the few seconds
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 53a8e2ce6ef..8e6d46134de 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -9,7 +9,7 @@ import {
 import type { AgentStatus } from '../../shared/agent-detection'
 import { gitExecFileAsync, wslAwareSpawn } from '../git/runner'
 import { isWslPath, parseWslPath, getWslHome } from '../wsl'
-import { createHash, randomUUID } from 'crypto'
+import { randomUUID } from 'crypto'
 import { basename, isAbsolute, join } from 'path'
 import { mkdir, readdir, rm, stat } from 'fs/promises'
 import { OrchestrationDb } from './orchestration/db'
@@ -80,7 +80,7 @@ import { RuntimeBrowserCommands } from './orca-runtime-browser'
 import { RuntimeFileCommands } from './orca-runtime-files'
 import { RuntimeGitCommands } from './orca-runtime-git'
 import { joinWorktreeRelativePath } from './runtime-relative-paths'
-import { app, BrowserWindow, ipcMain } from 'electron'
+import { BrowserWindow, ipcMain } from 'electron'
 import type { AgentBrowserBridge } from '../browser/agent-browser-bridge'
 import {
   getPRForBranch,
@@ -239,26 +239,6 @@ import type { CodexAccountService } from '../codex-accounts/service'
 import type { RateLimitService } from '../rate-limits/service'
 import type { ClaudeRateLimitAccountsState, CodexRateLimitAccountsState } from '../../shared/types'
 import type { RateLimitState } from '../../shared/rate-limit-types'
-import { NotesMarkdownStore } from '../notes/notes-markdown-store'
-import type {
-  NoteAppendArgs,
-  NoteCreateArgs,
-  NoteDeleteArgs,
-  NoteDeleteResult,
-  NoteLinkArgs,
-  NoteLink,
-  NoteLinkKind,
-  NoteListArgs,
-  NoteListResult,
-  NoteMutationResult,
-  NoteRenameArgs,
-  NoteSaveArgs,
-  NoteSearchArgs,
-  NoteShowArgs,
-  NoteShowResult,
-  NotesPanelOpenState,
-  NotesPanelStateArgs
-} from '../../shared/notes-types'
 import type { VoiceSettings } from '../../shared/speech-types'
 import { getSpeechModelManager, getSpeechSttService } from '../speech/speech-runtime-service'
 
@@ -783,7 +763,6 @@ export class OrcaRuntimeService {
   private optimisticReconcileTokens = new Map<string, string>()
   private readonly getLocalProviderFn: (() => IPtyProvider) | null
   private accountServices: RuntimeAccountServices | null = null
-  private _notesStore: NotesMarkdownStore | null = null
   private mobileDictation: {
     id: string
     owner: string
@@ -838,17 +817,6 @@ export class OrcaRuntimeService {
     this._orchestrationDb = db
   }
 
-  getNotesStore(): NotesMarkdownStore {
-    if (!this._notesStore) {
-      this._notesStore = new NotesMarkdownStore()
-    }
-    return this._notesStore
-  }
-
-  setNotesStore(store: NotesMarkdownStore): void {
-    this._notesStore = store
-  }
-
   getRuntimeId(): string {
     return this.runtimeId
   }
@@ -4912,205 +4880,6 @@ export class OrcaRuntimeService {
     }
   }
 
-  async listNotes(args: { worktreeSelector: string; limit?: number }): Promise<NoteListResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().list(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      limit: args.limit
-    })
-  }
-
-  async showNote(args: { worktreeSelector: string; note: string }): Promise<NoteShowResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().show(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      note: args.note
-    })
-  }
-
-  async createNote(args: {
-    worktreeSelector: string
-    title: string
-    bodyMarkdown?: string
-    makeActive?: boolean
-    createdBySessionId?: string | null
-  }): Promise<NoteMutationResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().create(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      title: args.title,
-      bodyMarkdown: args.bodyMarkdown,
-      makeActive: args.makeActive,
-      createdBySessionId: args.createdBySessionId
-    })
-  }
-
-  async saveNote(args: {
-    worktreeSelector: string
-    note: string
-    title?: string
-    bodyMarkdown: string
-    revision?: number
-    makeActive?: boolean
-    updatedBySessionId?: string | null
-  }): Promise<NoteMutationResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().save(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      note: args.note,
-      title: args.title,
-      bodyMarkdown: args.bodyMarkdown,
-      revision: args.revision,
-      makeActive: args.makeActive,
-      updatedBySessionId: args.updatedBySessionId
-    })
-  }
-
-  async renameNote(args: {
-    worktreeSelector: string
-    note: string
-    title: string
-    updatedBySessionId?: string | null
-  }): Promise<NoteMutationResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().rename(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      note: args.note,
-      title: args.title,
-      updatedBySessionId: args.updatedBySessionId
-    })
-  }
-
-  async deleteNote(args: { worktreeSelector: string; note: string }): Promise<NoteDeleteResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().delete(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      note: args.note
-    })
-  }
-
-  async appendNote(args: {
-    worktreeSelector: string
-    note: string
-    bodyMarkdown: string
-    makeActive?: boolean
-    updatedBySessionId?: string | null
-  }): Promise<NoteMutationResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().append(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      note: args.note,
-      bodyMarkdown: args.bodyMarkdown,
-      makeActive: args.makeActive,
-      updatedBySessionId: args.updatedBySessionId
-    })
-  }
-
-  async searchNotes(args: {
-    worktreeSelector: string
-    query: string
-    limit?: number
-  }): Promise<NoteListResult> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().search(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      query: args.query,
-      limit: args.limit
-    })
-  }
-
-  async linkNote(args: {
-    worktreeSelector: string
-    note: string
-    kind: NoteLinkKind
-  }): Promise<NoteLink> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().setLink(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId,
-      note: args.note,
-      kind: args.kind
-    })
-  }
-
-  async resolveNotesPanelOpenStateForWorktree(args: {
-    worktreeSelector: string
-  }): Promise<NotesPanelOpenState> {
-    const scope = await this.resolveNotesScope(args.worktreeSelector)
-    return await this.getNotesStore().resolvePanelOpenState(this.getNotesScope(scope.projectId), {
-      projectId: scope.projectId,
-      worktreeId: scope.worktreeId
-    })
-  }
-
-  async listProjectNotes(args: NoteListArgs): Promise<NoteListResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().list(this.getNotesScope(args.projectId), args)
-  }
-
-  async showProjectNote(args: NoteShowArgs): Promise<NoteShowResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().show(this.getNotesScope(args.projectId), args)
-  }
-
-  async createProjectNote(args: NoteCreateArgs): Promise<NoteMutationResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().create(this.getNotesScope(args.projectId), args)
-  }
-
-  async saveProjectNote(args: NoteSaveArgs): Promise<NoteMutationResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().save(this.getNotesScope(args.projectId), args)
-  }
-
-  async renameProjectNote(args: NoteRenameArgs): Promise<NoteMutationResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().rename(this.getNotesScope(args.projectId), args)
-  }
-
-  async deleteProjectNote(args: NoteDeleteArgs): Promise<NoteDeleteResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().delete(this.getNotesScope(args.projectId), args)
-  }
-
-  async appendProjectNote(args: NoteAppendArgs): Promise<NoteMutationResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().append(this.getNotesScope(args.projectId), args)
-  }
-
-  async searchProjectNotes(args: NoteSearchArgs): Promise<NoteListResult> {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().search(this.getNotesScope(args.projectId), args)
-  }
-
-  async linkProjectNote(args: NoteLinkArgs) {
-    this.assertKnownNotesProject(args.projectId)
-    return await this.getNotesStore().setLink(this.getNotesScope(args.projectId), args)
-  }
-
-  async unlinkNotesWorktree(projectId: string, worktreeId: string): Promise<void> {
-    this.assertKnownNotesProject(projectId)
-    await this.getNotesStore().unlinkWorktree(this.getNotesScope(projectId), worktreeId)
-  }
-
-  async resolveNotesPanelOpenState(args: NotesPanelStateArgs): Promise<NotesPanelOpenState> {
-    if (args.projectId) {
-      this.assertKnownNotesProject(args.projectId)
-    }
-    return await this.getNotesStore().resolvePanelOpenState(
-      args.projectId ? this.getNotesScope(args.projectId) : null,
-      args
-    )
-  }
-
   async listManagedWorktrees(
     repoSelector?: string,
     limit = DEFAULT_WORKTREE_LIST_LIMIT
@@ -6030,7 +5799,6 @@ export class OrcaRuntimeService {
         // remains locked — other worktrees cannot check it out.
         await gitExecFileAsync(['worktree', 'prune'], { cwd: repo.path }).catch(() => {})
         this.clearOptimisticReconcileToken(worktree.id)
-        await this.getNotesStore().unlinkWorktree(this.getNotesScope(repo.id), worktree.id)
         this.store.removeWorktreeMeta(worktree.id)
         this.invalidateResolvedWorktreeCache()
         invalidateAuthorizedRootsCache()
@@ -6043,7 +5811,6 @@ export class OrcaRuntimeService {
     }
 
     this.clearOptimisticReconcileToken(worktree.id)
-    await this.getNotesStore().unlinkWorktree(this.getNotesScope(repo.id), worktree.id)
     this.store.removeWorktreeMeta(worktree.id)
     this.invalidateResolvedWorktreeCache()
     invalidateAuthorizedRootsCache()
@@ -6726,42 +6493,6 @@ export class OrcaRuntimeService {
     throw new Error('selector_not_found')
   }
 
-  private async resolveNotesScope(worktreeSelector: string): Promise<{
-    projectId: string
-    worktreeId: string
-  }> {
-    const worktree = await this.resolveWorktreeSelector(worktreeSelector)
-    return {
-      projectId: worktree.repoId,
-      worktreeId: worktree.id
-    }
-  }
-
-  private assertKnownNotesProject(projectId: string): void {
-    if (!this.store?.getRepo(projectId)) {
-      throw new Error('repo_not_found')
-    }
-  }
-
-  private getNotesScope(projectId: string): {
-    projectId: string
-    rootPath: string
-  } {
-    const repo = this.store?.getRepo(projectId)
-    if (!repo) {
-      throw new Error('repo_not_found')
-    }
-    const identity = `${repo.connectionId ?? 'local'}:${repo.path}`
-    const notesRoot = createHash('sha256').update(identity).digest('hex').slice(0, 24)
-    return {
-      projectId,
-      // Why: notes are Orca workspace memory, not repo source files. Keeping
-      // them in userData prevents accidental git commits while still sharing
-      // one notes folder across every Orca worktree for the same repo.
-      rootPath: join(app.getPath('userData'), 'project-notes', notesRoot)
-    }
-  }
-
   private async resolveRepoSelector(selector: string): Promise<Repo> {
     if (!this.store) {
       throw new Error('repo_not_found')
diff --git a/src/main/runtime/rpc/errors.ts b/src/main/runtime/rpc/errors.ts
index efb2044118d..da19f1cba1a 100644
--- a/src/main/runtime/rpc/errors.ts
+++ b/src/main/runtime/rpc/errors.ts
@@ -43,9 +43,6 @@ const RUNTIME_PASSTHROUGH_CODES: ReadonlySet<string> = new Set([
   'terminal_gone',
   'no_active_terminal',
   'repo_not_found',
-  'note_not_found',
-  'note_ambiguous',
-  'revision_conflict',
   'timeout',
   'invalid_limit'
 ])
diff --git a/src/main/runtime/rpc/methods/index.ts b/src/main/runtime/rpc/methods/index.ts
index 868a3b503aa..7f46810a99a 100644
--- a/src/main/runtime/rpc/methods/index.ts
+++ b/src/main/runtime/rpc/methods/index.ts
@@ -17,7 +17,6 @@ import { GIT_METHODS } from './git'
 import { GITHUB_METHODS } from './github'
 import { HOSTED_REVIEW_METHODS } from './hosted-review'
 import { LINEAR_METHODS } from './linear'
-import { NOTE_METHODS } from './notes'
 import { SPEECH_METHODS } from './speech'
 
 // Why: a flat manifest keeps registration order explicit and provides one
@@ -42,6 +41,5 @@ export const ALL_RPC_METHODS: readonly RpcAnyMethod[] = [
   ...GITHUB_METHODS,
   ...HOSTED_REVIEW_METHODS,
   ...LINEAR_METHODS,
-  ...NOTE_METHODS,
   ...SPEECH_METHODS
 ]
diff --git a/src/main/runtime/rpc/methods/notes.test.ts b/src/main/runtime/rpc/methods/notes.test.ts
deleted file mode 100644
index 35c56129f5e..00000000000
--- a/src/main/runtime/rpc/methods/notes.test.ts
+++ /dev/null
@@ -1,148 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import type { OrcaRuntimeService } from '../../orca-runtime'
-import type { RpcRequest } from '../core'
-import { RpcDispatcher } from '../dispatcher'
-import { NOTE_METHODS } from './notes'
-
-function makeRequest(method: string, params?: unknown): RpcRequest {
-  return { id: 'req-1', authToken: 'tok', method, params }
-}
-
-describe('notes RPC methods', () => {
-  it('routes note reads through the selected worktree', async () => {
-    const runtime = {
-      getRuntimeId: () => 'test-runtime',
-      listNotes: vi.fn().mockResolvedValue({ notes: [], totalCount: 0, truncated: false }),
-      showNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: null })
-    } as unknown as OrcaRuntimeService
-    const dispatcher = new RpcDispatcher({ runtime, methods: NOTE_METHODS })
-
-    await dispatcher.dispatch(makeRequest('note.list', { worktree: 'id:wt-1', limit: 50 }))
-    await dispatcher.dispatch(makeRequest('note.show', { worktree: 'id:wt-1', note: 'note-1' }))
-
-    expect(runtime.listNotes).toHaveBeenCalledWith({ worktreeSelector: 'id:wt-1', limit: 50 })
-    expect(runtime.showNote).toHaveBeenCalledWith({
-      worktreeSelector: 'id:wt-1',
-      note: 'note-1'
-    })
-  })
-
-  it('routes note mutations through the selected worktree', async () => {
-    const runtime = {
-      getRuntimeId: () => 'test-runtime',
-      createNote: vi.fn().mockResolvedValue({ note: { id: 'created' }, linkKind: 'active' }),
-      saveNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: 'active' }),
-      renameNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: null }),
-      deleteNote: vi.fn().mockResolvedValue({ noteId: 'note-1', projectId: 'repo-1' }),
-      appendNote: vi.fn().mockResolvedValue({ note: { id: 'note-1' }, linkKind: null }),
-      linkNote: vi.fn().mockResolvedValue({
-        noteId: 'note-1',
-        projectId: 'repo-1',
-        worktreeId: 'wt-1',
-        kind: 'active',
-        createdAt: 'now'
-      })
-    } as unknown as OrcaRuntimeService
-    const dispatcher = new RpcDispatcher({ runtime, methods: NOTE_METHODS })
-
-    await dispatcher.dispatch(
-      makeRequest('note.create', {
-        worktree: 'id:wt-1',
-        title: 'Plan',
-        bodyMarkdown: 'body',
-        makeActive: true
-      })
-    )
-    await dispatcher.dispatch(
-      makeRequest('note.save', {
-        worktree: 'id:wt-1',
-        note: 'note-1',
-        title: 'Plan v2',
-        bodyMarkdown: 'updated',
-        revision: 2,
-        makeActive: true
-      })
-    )
-    await dispatcher.dispatch(
-      makeRequest('note.rename', { worktree: 'id:wt-1', note: 'note-1', title: 'Renamed' })
-    )
-    await dispatcher.dispatch(makeRequest('note.delete', { worktree: 'id:wt-1', note: 'note-1' }))
-    await dispatcher.dispatch(
-      makeRequest('note.append', {
-        worktree: 'id:wt-1',
-        note: 'note-1',
-        bodyMarkdown: 'more',
-        makeActive: true
-      })
-    )
-    await dispatcher.dispatch(
-      makeRequest('note.link', { worktree: 'id:wt-1', note: 'note-1', kind: 'active' })
-    )
-
-    expect(runtime.createNote).toHaveBeenCalledWith(
-      expect.objectContaining({
-        worktreeSelector: 'id:wt-1',
-        title: 'Plan',
-        bodyMarkdown: 'body',
-        makeActive: true
-      })
-    )
-    expect(runtime.saveNote).toHaveBeenCalledWith(
-      expect.objectContaining({
-        worktreeSelector: 'id:wt-1',
-        note: 'note-1',
-        title: 'Plan v2',
-        bodyMarkdown: 'updated',
-        revision: 2,
-        makeActive: true
-      })
-    )
-    expect(runtime.renameNote).toHaveBeenCalledWith(
-      expect.objectContaining({
-        worktreeSelector: 'id:wt-1',
-        note: 'note-1',
-        title: 'Renamed'
-      })
-    )
-    expect(runtime.deleteNote).toHaveBeenCalledWith({
-      worktreeSelector: 'id:wt-1',
-      note: 'note-1'
-    })
-    expect(runtime.appendNote).toHaveBeenCalledWith(
-      expect.objectContaining({
-        worktreeSelector: 'id:wt-1',
-        note: 'note-1',
-        bodyMarkdown: 'more',
-        makeActive: true
-      })
-    )
-    expect(runtime.linkNote).toHaveBeenCalledWith({
-      worktreeSelector: 'id:wt-1',
-      note: 'note-1',
-      kind: 'active'
-    })
-  })
-
-  it('routes panel state and search through the selected worktree', async () => {
-    const runtime = {
-      getRuntimeId: () => 'test-runtime',
-      searchNotes: vi.fn().mockResolvedValue({ notes: [], totalCount: 0, truncated: false }),
-      resolveNotesPanelOpenStateForWorktree: vi.fn().mockResolvedValue({ state: 'emptyDraft' })
-    } as unknown as OrcaRuntimeService
-    const dispatcher = new RpcDispatcher({ runtime, methods: NOTE_METHODS })
-
-    await dispatcher.dispatch(
-      makeRequest('note.search', { worktree: 'id:wt-1', query: 'todo', limit: 20 })
-    )
-    await dispatcher.dispatch(makeRequest('note.panelState', { worktree: 'id:wt-1' }))
-
-    expect(runtime.searchNotes).toHaveBeenCalledWith({
-      worktreeSelector: 'id:wt-1',
-      query: 'todo',
-      limit: 20
-    })
-    expect(runtime.resolveNotesPanelOpenStateForWorktree).toHaveBeenCalledWith({
-      worktreeSelector: 'id:wt-1'
-    })
-  })
-})
diff --git a/src/main/runtime/rpc/methods/notes.ts b/src/main/runtime/rpc/methods/notes.ts
deleted file mode 100644
index fc0ea173871..00000000000
--- a/src/main/runtime/rpc/methods/notes.ts
+++ /dev/null
@@ -1,165 +0,0 @@
-import { z } from 'zod'
-import { defineMethod, type RpcAnyMethod } from '../core'
-import { OptionalFiniteNumber, OptionalString, requiredString } from '../schemas'
-
-const NoteScopedParams = z.object({
-  worktree: requiredString('Missing worktree selector')
-})
-
-const NoteListParams = NoteScopedParams.extend({
-  limit: OptionalFiniteNumber
-})
-
-const NoteShowParams = NoteScopedParams.extend({
-  note: requiredString('Missing note selector')
-})
-
-const NoteCreateParams = NoteScopedParams.extend({
-  title: requiredString('Missing note title'),
-  bodyMarkdown: OptionalString,
-  makeActive: z.boolean().optional(),
-  createdBySessionId: z.string().nullable().optional()
-})
-
-const NoteSaveParams = NoteScopedParams.extend({
-  note: requiredString('Missing note selector'),
-  title: OptionalString,
-  bodyMarkdown: requiredString('Missing note body'),
-  revision: OptionalFiniteNumber,
-  makeActive: z.boolean().optional(),
-  updatedBySessionId: z.string().nullable().optional()
-})
-
-const NoteRenameParams = NoteScopedParams.extend({
-  note: requiredString('Missing note selector'),
-  title: requiredString('Missing note title'),
-  updatedBySessionId: z.string().nullable().optional()
-})
-
-const NoteDeleteParams = NoteScopedParams.extend({
-  note: requiredString('Missing note selector')
-})
-
-const NoteAppendParams = NoteScopedParams.extend({
-  note: requiredString('Missing note selector'),
-  bodyMarkdown: requiredString('Missing note body'),
-  makeActive: z.boolean().optional(),
-  updatedBySessionId: z.string().nullable().optional()
-})
-
-const NoteSearchParams = NoteScopedParams.extend({
-  query: requiredString('Missing search query'),
-  limit: OptionalFiniteNumber
-})
-
-const NoteLinkParams = NoteScopedParams.extend({
-  note: requiredString('Missing note selector'),
-  kind: z.enum(['active', 'referenced'])
-})
-
-export const NOTE_METHODS: readonly RpcAnyMethod[] = [
-  defineMethod({
-    name: 'note.list',
-    params: NoteListParams,
-    handler: async (params, { runtime }) =>
-      await runtime.listNotes({
-        worktreeSelector: params.worktree,
-        limit: params.limit
-      })
-  }),
-  defineMethod({
-    name: 'note.show',
-    params: NoteShowParams,
-    handler: async (params, { runtime }) =>
-      await runtime.showNote({
-        worktreeSelector: params.worktree,
-        note: params.note
-      })
-  }),
-  defineMethod({
-    name: 'note.create',
-    params: NoteCreateParams,
-    handler: async (params, { runtime }) =>
-      await runtime.createNote({
-        worktreeSelector: params.worktree,
-        title: params.title,
-        bodyMarkdown: params.bodyMarkdown,
-        makeActive: params.makeActive,
-        createdBySessionId: params.createdBySessionId
-      })
-  }),
-  defineMethod({
-    name: 'note.save',
-    params: NoteSaveParams,
-    handler: async (params, { runtime }) =>
-      await runtime.saveNote({
-        worktreeSelector: params.worktree,
-        note: params.note,
-        title: params.title,
-        bodyMarkdown: params.bodyMarkdown,
-        revision: params.revision,
-        makeActive: params.makeActive,
-        updatedBySessionId: params.updatedBySessionId
-      })
-  }),
-  defineMethod({
-    name: 'note.rename',
-    params: NoteRenameParams,
-    handler: async (params, { runtime }) =>
-      await runtime.renameNote({
-        worktreeSelector: params.worktree,
-        note: params.note,
-        title: params.title,
-        updatedBySessionId: params.updatedBySessionId
-      })
-  }),
-  defineMethod({
-    name: 'note.delete',
-    params: NoteDeleteParams,
-    handler: async (params, { runtime }) =>
-      await runtime.deleteNote({
-        worktreeSelector: params.worktree,
-        note: params.note
-      })
-  }),
-  defineMethod({
-    name: 'note.append',
-    params: NoteAppendParams,
-    handler: async (params, { runtime }) =>
-      await runtime.appendNote({
-        worktreeSelector: params.worktree,
-        note: params.note,
-        bodyMarkdown: params.bodyMarkdown,
-        makeActive: params.makeActive,
-        updatedBySessionId: params.updatedBySessionId
-      })
-  }),
-  defineMethod({
-    name: 'note.search',
-    params: NoteSearchParams,
-    handler: async (params, { runtime }) =>
-      await runtime.searchNotes({
-        worktreeSelector: params.worktree,
-        query: params.query,
-        limit: params.limit
-      })
-  }),
-  defineMethod({
-    name: 'note.link',
-    params: NoteLinkParams,
-    handler: async (params, { runtime }) =>
-      await runtime.linkNote({
-        worktreeSelector: params.worktree,
-        note: params.note,
-        kind: params.kind
-      })
-  }),
-  defineMethod({
-    name: 'note.panelState',
-    params: NoteScopedParams,
-    handler: async (params, { runtime }) =>
-      await runtime.resolveNotesPanelOpenStateForWorktree({
-        worktreeSelector: params.worktree
-      })
-  })
-]
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 5e21c47a89f..666a8f3e412 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -207,24 +207,6 @@ import type {
   AutomationRun,
   AutomationUpdateInput
 } from '../shared/automations-types'
-import type {
-  NoteAppendArgs,
-  NoteCreateArgs,
-  NoteDeleteArgs,
-  NoteDeleteResult,
-  NoteLinkArgs,
-  NoteLink,
-  NoteListArgs,
-  NoteListResult,
-  NoteMutationResult,
-  NoteRenameArgs,
-  NoteSaveArgs,
-  NoteSearchArgs,
-  NoteShowArgs,
-  NoteShowResult,
-  NotesPanelOpenState,
-  NotesPanelStateArgs
-} from '../shared/notes-types'
 
 export type BrowserApi = {
   registerGuest: (args: {
@@ -1281,18 +1263,6 @@ export type PreloadApi = {
       connectionId?: string
     }) => Promise<string | null>
   }
-  notes: {
-    list: (args: NoteListArgs) => Promise<NoteListResult>
-    show: (args: NoteShowArgs) => Promise<NoteShowResult>
-    create: (args: NoteCreateArgs) => Promise<NoteMutationResult>
-    save: (args: NoteSaveArgs) => Promise<NoteMutationResult>
-    rename: (args: NoteRenameArgs) => Promise<NoteMutationResult>
-    delete: (args: NoteDeleteArgs) => Promise<NoteDeleteResult>
-    append: (args: NoteAppendArgs) => Promise<NoteMutationResult>
-    search: (args: NoteSearchArgs) => Promise<NoteListResult>
-    link: (args: NoteLinkArgs) => Promise<NoteLink>
-    panelState: (args: NotesPanelStateArgs) => Promise<NotesPanelOpenState>
-  }
   ui: {
     get: () => Promise<PersistedUIState>
     set: (args: Partial<PersistedUIState>) => Promise<void>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 764714f28cb..0ae09605a4b 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -338,19 +338,6 @@ const api = {
     isAvailable: (): Promise<boolean> => ipcRenderer.invoke('pwsh:isAvailable')
   },
 
-  notes: {
-    list: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:list', args),
-    show: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:show', args),
-    create: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:create', args),
-    save: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:save', args),
-    rename: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:rename', args),
-    delete: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:delete', args),
-    append: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:append', args),
-    search: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:search', args),
-    link: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:link', args),
-    panelState: (args: unknown): Promise<unknown> => ipcRenderer.invoke('notes:panelState', args)
-  },
-
   repos: {
     list: (): Promise<unknown[]> => ipcRenderer.invoke('repos:list'),
 
diff --git a/src/renderer/src/components/Terminal.tsx b/src/renderer/src/components/Terminal.tsx
index d1b172000dd..1169ea6dacc 100644
--- a/src/renderer/src/components/Terminal.tsx
+++ b/src/renderer/src/components/Terminal.tsx
@@ -29,7 +29,6 @@ import {
   type EditorRequestFileCloseDetail,
   requestEditorSaveQuiesce
 } from './editor/editor-autosave'
-import { requestProjectNotesTabClose } from '@/lib/project-notes-close-request'
 import { isUpdaterQuitAndInstallInProgress } from '@/lib/updater-beforeunload'
 import EditorAutosaveController from './editor/EditorAutosaveController'
 import type { TabGroupLayoutNode } from '../../../shared/types'
@@ -50,7 +49,6 @@ import TabGroupSplitLayout from './tab-group/TabGroupSplitLayout'
 import { shouldAutoCreateInitialTerminal } from './terminal/initial-terminal'
 import { shouldRepairActiveTerminalTab } from './terminal/active-terminal-repair'
 import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
-import { openProjectNotesTab } from '@/lib/open-project-notes-tab'
 import {
   getEffectiveLayoutForWorktree as getEffectiveLayout,
   anyMountedWorktreeHasLayout as computeAnyMountedWorktreeHasLayout
@@ -656,16 +654,6 @@ function Terminal(): React.JSX.Element | null {
     }
   }, [activeWorktreeId, openFile])
 
-  const handleNewNotesTab = useCallback(
-    (noteId?: string) => {
-      if (!activeWorktreeId) {
-        return
-      }
-      void openProjectNotesTab(activeWorktreeId, noteId)
-    },
-    [activeWorktreeId]
-  )
-
   const handleCloseTab = useCallback(
     (tabId: string) => {
       const state = useAppStore.getState()
@@ -986,13 +974,6 @@ function Terminal(): React.JSX.Element | null {
           handleCloseFile(state.activeFileId)
         } else if (state.activeTabType === 'browser' && state.activeBrowserTabId) {
           closeBrowserTab(state.activeBrowserTabId)
-        } else if (state.activeTabType === 'notes') {
-          const activeTab = activeWorktreeId ? state.getActiveTab(activeWorktreeId) : null
-          if (activeTab?.contentType === 'notes') {
-            requestProjectNotesTabClose(activeTab.id, () => {
-              state.closeUnifiedTab(activeTab.id)
-            })
-          }
         }
         return
       }
@@ -1211,7 +1192,6 @@ function Terminal(): React.JSX.Element | null {
             onNewTerminalWithShell={handleNewTab}
             onNewBrowserTab={handleNewBrowserTab}
             onNewFileTab={handleNewFile}
-            onNewNotesTab={handleNewNotesTab}
             wslAvailable={wslAvailable}
             onSetCustomTitle={setTabCustomTitle}
             onSetTabColor={setTabColor}
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index 7584be239bd..e21eb0ab923 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -228,7 +228,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   const deferredQuery = useDeferredValue(query)
   const [selectedItemId, setSelectedItemId] = useState('')
   const previousWorktreeIdRef = useRef<string | null>(null)
-  const previousActiveTabTypeRef = useRef<'browser' | 'editor' | 'terminal' | 'notes'>('terminal')
+  const previousActiveTabTypeRef = useRef<'browser' | 'editor' | 'terminal'>('terminal')
   const previousBrowserPageIdRef = useRef<string | null>(null)
   const previousBrowserFocusTargetRef = useRef<'webview' | 'address-bar'>('webview')
   const wasVisibleRef = useRef(false)
diff --git a/src/renderer/src/components/editor/EditorPanel.tsx b/src/renderer/src/components/editor/EditorPanel.tsx
index 86ad99428c2..c0835db1e23 100644
--- a/src/renderer/src/components/editor/EditorPanel.tsx
+++ b/src/renderer/src/components/editor/EditorPanel.tsx
@@ -257,7 +257,7 @@ function EditorPanelInner({
       settings,
       renameDialogFile?.runtimeEnvironmentId
     )?.activeRuntimeEnvironmentId?.trim() ||
-      (renameDialogFile ? getConnectionId(renameDialogFile.worktreeId) : null)
+    (renameDialogFile ? getConnectionId(renameDialogFile.worktreeId) : null)
   )
 
   return (
diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
index 94c89362086..0d0ffe18c89 100644
--- a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
@@ -1,4 +1,3 @@
-/* eslint-disable max-lines -- Why: the floating surface owns both terminal chrome and local notes tabs until the shared floating shell is extracted. */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import TabBar from '@/components/tab-bar/TabBar'
 import TerminalPane from '@/components/terminal-pane/TerminalPane'
@@ -11,15 +10,10 @@ import {
   isOrchestrationSetupDismissed,
   notifyOrchestrationSetupStateChanged
 } from '@/lib/orchestration-setup-state'
-import { notifyProjectNotesSelectionChanged } from '@/lib/open-project-notes-tab'
-import { requestProjectNotesTabClose } from '@/lib/project-notes-close-request'
-import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
 import { useAppStore } from '@/store'
-import { createBrowserUuid } from '@/lib/browser-uuid'
 import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../../shared/constants'
 import type { TerminalTab } from '../../../../shared/types'
 import { FloatingTerminalOrchestrationDialog } from './FloatingTerminalOrchestrationDialog'
-import ProjectNotesTabContent from '@/components/notes/ProjectNotesTabContent'
 import { FloatingTerminalResizeHandles } from './FloatingTerminalResizeHandles'
 import { FloatingTerminalWindowControls } from './FloatingTerminalWindowControls'
 export { FloatingTerminalToggleButton } from './FloatingTerminalToggleButton'
@@ -30,7 +24,6 @@ import {
   type FloatingTerminalPanelBounds
 } from './floating-terminal-panel-bounds'
 const EMPTY_TERMINAL_TABS: TerminalTab[] = []
-type FloatingNotesTab = { id: string; label: string; noteId: string | null; isDirty: boolean }
 
 type FloatingTerminalPanelProps = {
   open: boolean
@@ -53,7 +46,6 @@ export function FloatingTerminalPanel({
   const setTabPaneExpanded = useAppStore((s) => s.setTabPaneExpanded)
   const tabBarOrder = useAppStore((s) => s.tabBarOrderByWorktree[FLOATING_TERMINAL_WORKTREE_ID])
   const floatingTerminalCwd = useAppStore((s) => s.settings?.floatingTerminalCwd ?? '~')
-  const activeWorktreeId = useAppStore((s) => s.activeWorktreeId)
 
   const [cwd, setCwd] = useState<string | null>(null)
   const [bounds, setBounds] = useState(() => getDefaultFloatingTerminalBounds())
@@ -62,9 +54,6 @@ export function FloatingTerminalPanel({
   const [showOrchestrationSetup, setShowOrchestrationSetup] = useState(
     () => !hasOrchestrationSetupMarker() && !isOrchestrationSetupDismissed()
   )
-  const [notesTabs, setNotesTabs] = useState<FloatingNotesTab[]>([])
-  const [activeNotesTabId, setActiveNotesTabId] = useState<string | null>(null)
-  const [activeSurface, setActiveSurface] = useState<'terminal' | 'notes'>('terminal')
   const restoreBoundsRef = useRef<FloatingTerminalPanelBounds | null>(null)
   const normalizedInitialBoundsRef = useRef(false)
   const panelRef = useRef<HTMLDivElement>(null)
@@ -155,7 +144,6 @@ export function FloatingTerminalPanel({
   const createFloatingTab = useCallback(() => {
     const tab = createTab(FLOATING_TERMINAL_WORKTREE_ID, undefined, undefined, { activate: false })
     setActiveTabForWorktree(FLOATING_TERMINAL_WORKTREE_ID, tab.id)
-    setActiveSurface('terminal')
     const state = useAppStore.getState()
     const currentTabs = state.tabsByWorktree[FLOATING_TERMINAL_WORKTREE_ID] ?? []
     const stored = state.tabBarOrderByWorktree[FLOATING_TERMINAL_WORKTREE_ID] ?? []
@@ -174,7 +162,6 @@ export function FloatingTerminalPanel({
   const closeFloatingTab = useCallback(
     (tabId: string) => {
       closeTab(tabId)
-      setActiveSurface('terminal')
     },
     [closeTab]
   )
@@ -203,73 +190,6 @@ export function FloatingTerminalPanel({
     [closeTab, tabs]
   )
 
-  const openFloatingNotesTab = useCallback(
-    async (noteId?: string) => {
-      if (!activeWorktreeId) {
-        return
-      }
-      const state = useAppStore.getState()
-      const worktree = Object.values(state.worktreesByRepo)
-        .flat()
-        .find((candidate) => candidate.id === activeWorktreeId)
-      const projectId =
-        state.repos.find((candidate) => candidate.id === worktree?.repoId)?.id ?? worktree?.repoId
-      const settings = state.settings
-      let label = 'Project Notes'
-      if (noteId && projectId) {
-        try {
-          const result = await showRuntimeProjectNote(settings, {
-            projectId,
-            worktreeId: activeWorktreeId,
-            note: noteId
-          })
-          label = result.note.title
-        } catch {
-          label = 'Project Notes'
-        }
-        if (projectId) {
-          await linkRuntimeProjectNote(settings, {
-            projectId,
-            worktreeId: activeWorktreeId,
-            note: noteId,
-            kind: 'active'
-          })
-          notifyProjectNotesSelectionChanged()
-        }
-      }
-      const id = `floating-project-notes:${createBrowserUuid()}`
-      setNotesTabs((current) => [...current, { id, label, noteId: noteId ?? null, isDirty: false }])
-      setActiveNotesTabId(id)
-      setActiveSurface('notes')
-    },
-    [activeWorktreeId]
-  )
-
-  const closeFloatingNotesTab = useCallback((tabId: string) => {
-    requestProjectNotesTabClose(tabId, () => {
-      setNotesTabs((current) => current.filter((tab) => tab.id !== tabId))
-      setActiveNotesTabId((current) => (current === tabId ? null : current))
-      setActiveSurface('terminal')
-    })
-  }, [])
-
-  useEffect(() => {
-    if (!open || activeSurface !== 'notes' || !activeNotesTabId) {
-      return
-    }
-    const isMac = navigator.userAgent.includes('Mac')
-    const onKeyDown = (event: KeyboardEvent): void => {
-      const mod = isMac ? event.metaKey : event.ctrlKey
-      if (!mod || event.shiftKey || event.repeat || event.key.toLowerCase() !== 'w') {
-        return
-      }
-      event.preventDefault()
-      closeFloatingNotesTab(activeNotesTabId)
-    }
-    window.addEventListener('keydown', onKeyDown, { capture: true })
-    return () => window.removeEventListener('keydown', onKeyDown, { capture: true })
-  }, [activeNotesTabId, activeSurface, closeFloatingNotesTab, open])
-
   const toggleMaximized = useCallback(() => {
     setMaximized((current) => {
       if (current) {
@@ -372,31 +292,19 @@ export function FloatingTerminalPanel({
               activeTabId={activeTab?.id ?? null}
               worktreeId={FLOATING_TERMINAL_WORKTREE_ID}
               expandedPaneByTabId={expandedPaneByTabId}
-              onActivate={(tabId) => {
-                setActiveSurface('terminal')
-                setActiveTabForWorktree(FLOATING_TERMINAL_WORKTREE_ID, tabId)
-              }}
+              onActivate={(tabId) => setActiveTabForWorktree(FLOATING_TERMINAL_WORKTREE_ID, tabId)}
               onClose={closeFloatingTab}
               onCloseOthers={closeOthers}
               onCloseToRight={closeToRight}
               onNewTerminalTab={createFloatingTab}
               onNewBrowserTab={() => {}}
-              onNewNotesTab={activeWorktreeId ? openFloatingNotesTab : undefined}
-              notesWorktreeId={activeWorktreeId}
               terminalOnly
               onSetCustomTitle={setTabCustomTitle}
               onSetTabColor={setTabColor}
               onTogglePaneExpand={(tabId) =>
                 setTabPaneExpanded(tabId, expandedPaneByTabId[tabId] !== true)
               }
-              notesTabs={activeWorktreeId ? notesTabs : []}
-              activeNotesTabId={activeSurface === 'notes' ? activeNotesTabId : null}
-              onActivateNotesTab={(tabId) => {
-                setActiveNotesTabId(tabId)
-                setActiveSurface('notes')
-              }}
-              onCloseNotesTab={closeFloatingNotesTab}
-              activeTabType={activeSurface}
+              activeTabType="terminal"
               tabBarOrder={tabBarOrder}
             />
           </div>
@@ -408,42 +316,27 @@ export function FloatingTerminalPanel({
         </div>
 
         <div className="relative min-h-0 flex-1 overflow-hidden bg-background">
-          {activeSurface === 'notes' && activeWorktreeId && activeNotesTabId ? (
-            <ProjectNotesTabContent
-              key={activeNotesTabId}
-              worktreeId={activeWorktreeId}
-              tabId={activeNotesTabId}
-              noteId={notesTabs.find((tab) => tab.id === activeNotesTabId)?.noteId ?? null}
-              forceNew={notesTabs.find((tab) => tab.id === activeNotesTabId)?.noteId === null}
-              onDirtyChange={(dirty) => {
-                setNotesTabs((current) =>
-                  current.map((tab) =>
-                    tab.id === activeNotesTabId ? { ...tab, isDirty: dirty } : tab
-                  )
-                )
-              }}
-            />
-          ) : cwd ? (
-            tabs.map((tab) => (
-              <div
-                key={`${tab.id}-${tab.generation ?? 0}`}
-                className={
-                  tab.id === activeTab?.id ? 'absolute inset-0' : 'absolute inset-0 hidden'
-                }
-                aria-hidden={tab.id !== activeTab?.id}
-              >
-                <TerminalPane
-                  tabId={tab.id}
-                  worktreeId={FLOATING_TERMINAL_WORKTREE_ID}
-                  cwd={cwd}
-                  isActive={tab.id === activeTab?.id}
-                  isVisible={tab.id === activeTab?.id}
-                  onPtyExit={() => closeTab(tab.id)}
-                  onCloseTab={() => closeTab(tab.id)}
-                />
-              </div>
-            ))
-          ) : null}
+          {cwd
+            ? tabs.map((tab) => (
+                <div
+                  key={`${tab.id}-${tab.generation ?? 0}`}
+                  className={
+                    tab.id === activeTab?.id ? 'absolute inset-0' : 'absolute inset-0 hidden'
+                  }
+                  aria-hidden={tab.id !== activeTab?.id}
+                >
+                  <TerminalPane
+                    tabId={tab.id}
+                    worktreeId={FLOATING_TERMINAL_WORKTREE_ID}
+                    cwd={cwd}
+                    isActive={tab.id === activeTab?.id}
+                    isVisible={tab.id === activeTab?.id}
+                    onPtyExit={() => closeTab(tab.id)}
+                    onCloseTab={() => closeTab(tab.id)}
+                  />
+                </div>
+              ))
+            : null}
         </div>
       </div>
       {showOrchestrationSetup ? (
diff --git a/src/renderer/src/components/notes/ProjectNotesTabContent.tsx b/src/renderer/src/components/notes/ProjectNotesTabContent.tsx
deleted file mode 100644
index 99a81458b1f..00000000000
--- a/src/renderer/src/components/notes/ProjectNotesTabContent.tsx
+++ /dev/null
@@ -1,699 +0,0 @@
-/* eslint-disable max-lines -- Why: project notes keep picker, save-as, and
-   rich/source/preview markdown modes together so unsaved note creation and
-   active-note switching cannot drift across separate surfaces. */
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Copy, FileText, MoreHorizontal, Plus, Save } from 'lucide-react'
-import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger
-} from '@/components/ui/dropdown-menu'
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle
-} from '@/components/ui/dialog'
-import RichMarkdownEditor from '@/components/editor/RichMarkdownEditor'
-import MarkdownPreview from '@/components/editor/MarkdownPreview'
-import EditorViewToggle from '@/components/editor/EditorViewToggle'
-import { useAppStore } from '@/store'
-import { useRepoById, useWorktreeById } from '@/store/selectors'
-import { NOTES_ACTIVE_CHANGED_EVENT } from '@/lib/notes-events'
-import {
-  getProjectNotesEntityId,
-  notifyProjectNotesSelectionChanged
-} from '@/lib/open-project-notes-tab'
-import {
-  createRuntimeProjectNote,
-  listRuntimeProjectNotes,
-  linkRuntimeProjectNote,
-  resolveRuntimeNotesPanelState,
-  saveRuntimeProjectNote,
-  showRuntimeProjectNote
-} from '@/runtime/runtime-notes-client'
-import {
-  ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT,
-  type ProjectNotesCloseRequestDetail
-} from '@/lib/project-notes-close-request'
-import { toast } from 'sonner'
-import type { MarkdownDocument } from '../../../../shared/types'
-import type { NoteRecord, NoteSummary, NotesPanelOpenState } from '../../../../shared/notes-types'
-import type { MarkdownViewMode } from '@/store/slices/editor'
-
-const SAVE_DEBOUNCE_MS = 700
-
-type Draft = {
-  id: string | null
-  filePath: string | null
-  relativePath: string | null
-  title: string
-  bodyMarkdown: string
-  revision: number | null
-}
-
-function emptyDraft(): Draft {
-  return {
-    id: null,
-    filePath: null,
-    relativePath: null,
-    title: 'Untitled note',
-    bodyMarkdown: '',
-    revision: null
-  }
-}
-
-export default function ProjectNotesTabContent({
-  worktreeId,
-  tabId,
-  noteId = null,
-  forceNew = false,
-  onDirtyChange
-}: {
-  worktreeId: string
-  tabId: string
-  noteId?: string | null
-  forceNew?: boolean
-  onDirtyChange?: (dirty: boolean) => void
-}): React.JSX.Element {
-  const worktree = useWorktreeById(worktreeId)
-  const repo = useRepoById(worktree?.repoId ?? null)
-  const projectId = repo?.id ?? worktree?.repoId ?? null
-  const settings = useAppStore((s) => s.settings)
-
-  const [panelState, setPanelState] = useState<NotesPanelOpenState>({ state: 'noProject' })
-  const [notes, setNotes] = useState<NoteSummary[]>([])
-  const [draft, setDraft] = useState<Draft>(() => emptyDraft())
-  const [dirty, setDirty] = useState(false)
-  const [saving, setSaving] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-  const [viewMode, setViewMode] = useState<MarkdownViewMode>('rich')
-  const [saveAsOpen, setSaveAsOpen] = useState(false)
-  const [closePromptOpen, setClosePromptOpen] = useState(false)
-  const [saveAsTitle, setSaveAsTitle] = useState('Untitled note')
-  const [selectedNoteId, setSelectedNoteId] = useState<string | null>(noteId)
-  const saveAsInputRef = useRef<HTMLInputElement>(null)
-  const pendingCreateBodyRef = useRef<string | null>(null)
-  const pendingCloseRef = useRef<(() => void) | null>(null)
-
-  const canSave = projectId !== null && (draft.id === null || draft.title.trim().length > 0)
-
-  const refreshNotes = useCallback(async (): Promise<void> => {
-    if (!projectId) {
-      setNotes([])
-      return
-    }
-    const result = await listRuntimeProjectNotes(settings, { projectId, worktreeId, limit: 100 })
-    setNotes(result.notes)
-  }, [projectId, settings, worktreeId])
-
-  const loadPanelState = useCallback(async (): Promise<void> => {
-    try {
-      setError(null)
-      if (selectedNoteId && projectId) {
-        const result = await showRuntimeProjectNote(settings, {
-          projectId,
-          worktreeId,
-          note: selectedNoteId
-        })
-        setPanelState({ state: 'active', projectId, worktreeId, note: result.note })
-        setDraft({
-          id: result.note.id,
-          filePath: result.note.filePath,
-          relativePath: result.note.relativePath,
-          title: result.note.title,
-          bodyMarkdown: result.note.bodyMarkdown,
-          revision: result.note.revision
-        })
-        setDirty(false)
-        const state = useAppStore.getState()
-        state.setTabLabel(tabId, result.note.title)
-        state.setTabEntityId(tabId, getProjectNotesEntityId(projectId, result.note.id))
-        await refreshNotes()
-        return
-      }
-      if (forceNew && projectId) {
-        setPanelState({ state: 'emptyDraft', projectId, worktreeId })
-        setDraft(emptyDraft())
-        setDirty(false)
-        useAppStore.getState().setTabLabel(tabId, 'Project Notes')
-        await refreshNotes()
-        return
-      }
-      const next = await resolveRuntimeNotesPanelState(settings, { projectId, worktreeId })
-      setPanelState(next)
-      if (next.state === 'active') {
-        setDraft({
-          id: next.note.id,
-          filePath: next.note.filePath,
-          relativePath: next.note.relativePath,
-          title: next.note.title,
-          bodyMarkdown: next.note.bodyMarkdown,
-          revision: next.note.revision
-        })
-        const state = useAppStore.getState()
-        state.setTabLabel(tabId, next.note.title)
-        state.setTabEntityId(tabId, getProjectNotesEntityId(next.projectId, next.note.id))
-        setDirty(false)
-      } else {
-        setDraft(emptyDraft())
-        useAppStore
-          .getState()
-          .setTabEntityId(tabId, getProjectNotesEntityId(projectId ?? worktreeId))
-        setDirty(false)
-      }
-      if (next.state === 'pickerRequired') {
-        setNotes(next.notes)
-      } else {
-        await refreshNotes()
-      }
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err))
-    }
-  }, [forceNew, projectId, refreshNotes, selectedNoteId, settings, tabId, worktreeId])
-
-  useEffect(() => {
-    void loadPanelState()
-  }, [loadPanelState])
-
-  useEffect(() => {
-    setSelectedNoteId(noteId)
-  }, [noteId])
-
-  useEffect(() => {
-    useAppStore.getState().setTabDirty(tabId, dirty)
-    onDirtyChange?.(dirty)
-  }, [dirty, onDirtyChange, tabId])
-
-  useEffect(() => {
-    const listener = (): void => {
-      if (dirty) {
-        return
-      }
-      void loadPanelState()
-    }
-    window.addEventListener(NOTES_ACTIVE_CHANGED_EVENT, listener)
-    return () => window.removeEventListener(NOTES_ACTIVE_CHANGED_EVENT, listener)
-  }, [dirty, loadPanelState])
-
-  useEffect(() => {
-    const listener = (event: Event): void => {
-      const detail = (event as CustomEvent<ProjectNotesCloseRequestDetail>).detail
-      if (!detail || detail.tabId !== tabId) {
-        return
-      }
-      detail.claim()
-      if (!dirty) {
-        detail.close()
-        return
-      }
-      pendingCloseRef.current = detail.close
-      setClosePromptOpen(true)
-    }
-    window.addEventListener(ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT, listener)
-    return () => window.removeEventListener(ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT, listener)
-  }, [dirty, tabId])
-
-  const selectNote = useCallback(
-    async (noteId: string): Promise<void> => {
-      if (!projectId) {
-        return
-      }
-      const result = await showRuntimeProjectNote(settings, { projectId, worktreeId, note: noteId })
-      await linkRuntimeProjectNote(settings, {
-        projectId,
-        worktreeId,
-        note: noteId,
-        kind: 'active'
-      })
-      setSelectedNoteId(noteId)
-      setDraft({
-        id: result.note.id,
-        filePath: result.note.filePath,
-        relativePath: result.note.relativePath,
-        title: result.note.title,
-        bodyMarkdown: result.note.bodyMarkdown,
-        revision: result.note.revision
-      })
-      setPanelState({ state: 'active', projectId, worktreeId, note: result.note })
-      const state = useAppStore.getState()
-      state.setTabLabel(tabId, result.note.title)
-      state.setTabEntityId(tabId, getProjectNotesEntityId(projectId, result.note.id))
-      setDirty(false)
-      await refreshNotes()
-    },
-    [projectId, refreshNotes, settings, tabId, worktreeId]
-  )
-
-  const saveDraft = useCallback(
-    async (bodyOverride?: string): Promise<NoteRecord | null> => {
-      if (!canSave || !projectId) {
-        return null
-      }
-      const bodyMarkdown = bodyOverride ?? draft.bodyMarkdown
-      if (!draft.id) {
-        // Why: project notes are markdown files. Match untitled Markdown tabs
-        // by asking for the user-facing name before creating the file instead
-        // of silently persisting "Untitled note" from autosave.
-        pendingCreateBodyRef.current = bodyMarkdown
-        setSaveAsTitle(draft.title.trim() || 'Untitled note')
-        setSaveAsOpen(true)
-        return null
-      }
-      setSaving(true)
-      try {
-        const result = await saveRuntimeProjectNote(settings, {
-          projectId,
-          worktreeId,
-          note: draft.id,
-          title: draft.title,
-          bodyMarkdown,
-          revision: draft.revision ?? undefined,
-          makeActive: true
-        })
-        setDraft({
-          id: result.note.id,
-          filePath: result.note.filePath,
-          relativePath: result.note.relativePath,
-          title: result.note.title,
-          bodyMarkdown: result.note.bodyMarkdown,
-          revision: result.note.revision
-        })
-        setPanelState({ state: 'active', projectId, worktreeId, note: result.note })
-        setSelectedNoteId(result.note.id)
-        const state = useAppStore.getState()
-        state.setTabLabel(tabId, result.note.title)
-        state.setTabEntityId(tabId, getProjectNotesEntityId(projectId, result.note.id))
-        setDirty(false)
-        await refreshNotes()
-        notifyProjectNotesSelectionChanged()
-        return result.note
-      } catch (err) {
-        setError(err instanceof Error ? err.message : String(err))
-        return null
-      } finally {
-        setSaving(false)
-      }
-    },
-    [canSave, draft, projectId, refreshNotes, settings, tabId, worktreeId]
-  )
-
-  useEffect(() => {
-    if (!dirty || !canSave || !draft.id) {
-      return
-    }
-    const timer = window.setTimeout(() => {
-      void saveDraft()
-    }, SAVE_DEBOUNCE_MS)
-    return () => window.clearTimeout(timer)
-  }, [canSave, dirty, draft.id, saveDraft])
-
-  const createNewDraft = useCallback(() => {
-    setSelectedNoteId(null)
-    setDraft(emptyDraft())
-    const state = useAppStore.getState()
-    state.setTabLabel(tabId, 'Project Notes')
-    state.setTabEntityId(tabId, getProjectNotesEntityId(projectId ?? worktreeId))
-    setPanelState(
-      projectId ? { state: 'emptyDraft', projectId, worktreeId } : { state: 'noProject' }
-    )
-    setDirty(false)
-  }, [projectId, tabId, worktreeId])
-
-  const markdownDocuments = useMemo<MarkdownDocument[]>(
-    () =>
-      notes.map((note) => ({
-        filePath: note.filePath,
-        relativePath: note.relativePath,
-        basename: note.relativePath.split('/').pop() ?? note.title,
-        name: note.title
-      })),
-    [notes]
-  )
-
-  const editorFilePath =
-    draft.filePath ?? `orca://project-notes/${projectId ?? 'project'}/untitled.md`
-  const editorPathLabel = draft.filePath
-    ? (draft.relativePath ?? draft.title)
-    : `notes/${draft.title.trim() || 'untitled'}.md`
-
-  useEffect(() => {
-    if (error) {
-      toast.error(error)
-    }
-  }, [error])
-
-  useEffect(() => {
-    if (!saveAsOpen) {
-      return
-    }
-    requestAnimationFrame(() => saveAsInputRef.current?.select())
-  }, [saveAsOpen])
-
-  const confirmCreateNote = useCallback(async (): Promise<void> => {
-    if (!projectId) {
-      return
-    }
-    const title = saveAsTitle.trim().replace(/\.md$/i, '')
-    if (!title) {
-      setError('Name cannot be empty')
-      return
-    }
-    setSaving(true)
-    try {
-      const result = await createRuntimeProjectNote(settings, {
-        projectId,
-        worktreeId,
-        title,
-        bodyMarkdown: pendingCreateBodyRef.current ?? draft.bodyMarkdown,
-        makeActive: true
-      })
-      setDraft({
-        id: result.note.id,
-        filePath: result.note.filePath,
-        relativePath: result.note.relativePath,
-        title: result.note.title,
-        bodyMarkdown: result.note.bodyMarkdown,
-        revision: result.note.revision
-      })
-      setPanelState({ state: 'active', projectId, worktreeId, note: result.note })
-      setSelectedNoteId(result.note.id)
-      const state = useAppStore.getState()
-      state.setTabLabel(tabId, result.note.title)
-      state.setTabEntityId(tabId, getProjectNotesEntityId(projectId, result.note.id))
-      setDirty(false)
-      setSaveAsOpen(false)
-      pendingCreateBodyRef.current = null
-      await refreshNotes()
-      notifyProjectNotesSelectionChanged()
-      const pendingClose = pendingCloseRef.current
-      if (pendingClose) {
-        pendingCloseRef.current = null
-        pendingClose()
-      }
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err))
-    } finally {
-      setSaving(false)
-    }
-  }, [draft.bodyMarkdown, projectId, refreshNotes, saveAsTitle, settings, tabId, worktreeId])
-
-  const handleClosePromptSave = useCallback(async (): Promise<void> => {
-    setClosePromptOpen(false)
-    const saved = await saveDraft()
-    if (!saved) {
-      if (draft.id) {
-        setClosePromptOpen(true)
-      }
-      return
-    }
-    const pendingClose = pendingCloseRef.current
-    pendingCloseRef.current = null
-    pendingClose?.()
-  }, [draft.id, saveDraft])
-
-  const handleClosePromptDiscard = useCallback(() => {
-    setClosePromptOpen(false)
-    setDirty(false)
-    const pendingClose = pendingCloseRef.current
-    pendingCloseRef.current = null
-    pendingClose?.()
-  }, [])
-
-  const handleClosePromptCancel = useCallback(() => {
-    setClosePromptOpen(false)
-    pendingCloseRef.current = null
-  }, [])
-
-  const handleSaveAsCancel = useCallback(() => {
-    setSaveAsOpen(false)
-    pendingCreateBodyRef.current = null
-    pendingCloseRef.current = null
-  }, [])
-
-  return (
-    <div className="relative flex h-full min-h-0 min-w-0 flex-1 flex-col bg-background">
-      <div className="editor-header">
-        <div className="editor-header-text">
-          <div className="editor-header-path-row">
-            <button
-              type="button"
-              className="editor-header-path"
-              title={editorFilePath}
-              onClick={() => {
-                void window.api.ui.writeClipboardText(editorFilePath)
-              }}
-            >
-              {editorPathLabel}
-            </button>
-          </div>
-        </div>
-        <EditorViewToggle
-          value={viewMode}
-          modes={['source', 'rich', 'preview']}
-          onChange={(next) => setViewMode(next as MarkdownViewMode)}
-        />
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button
-              type="button"
-              variant="ghost"
-              size="icon-xs"
-              className="text-muted-foreground hover:text-foreground"
-              aria-label="More actions"
-              title="More actions"
-            >
-              <MoreHorizontal size={14} />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" className="w-64">
-            <DropdownMenuLabel>Current note</DropdownMenuLabel>
-            <div className="px-2 pb-2">
-              <Input
-                value={draft.title}
-                disabled={panelState.state === 'noProject'}
-                onChange={(event) => {
-                  setDraft((current) => ({ ...current, title: event.target.value }))
-                  setDirty(true)
-                }}
-                className="h-8 text-xs"
-                placeholder="Note title"
-              />
-            </div>
-            <DropdownMenuItem onSelect={createNewDraft}>
-              <Plus className="size-3.5" />
-              New note
-            </DropdownMenuItem>
-            <DropdownMenuItem
-              onSelect={() => {
-                void window.api.ui.writeClipboardText(draft.bodyMarkdown)
-              }}
-            >
-              <Copy className="size-3.5" />
-              Copy Markdown
-            </DropdownMenuItem>
-            <DropdownMenuItem disabled={!canSave || saving} onSelect={() => void saveDraft()}>
-              <Save className="size-3.5" />
-              Save now
-            </DropdownMenuItem>
-            {notes.length > 0 ? (
-              <>
-                <DropdownMenuSeparator />
-                <DropdownMenuLabel>Switch note</DropdownMenuLabel>
-                {notes.map((note) => (
-                  <DropdownMenuItem key={note.id} onSelect={() => void selectNote(note.id)}>
-                    <FileText className="size-3.5" />
-                    <span className="truncate">{note.title}</span>
-                  </DropdownMenuItem>
-                ))}
-              </>
-            ) : null}
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-
-      <div className="min-h-0 min-w-0 flex-1 overflow-hidden">
-        {panelState.state === 'noProject' ? (
-          <div className="flex h-full items-center justify-center px-4 text-sm text-muted-foreground">
-            Open a project worktree to use notes.
-          </div>
-        ) : panelState.state === 'pickerRequired' ? (
-          <div className="flex h-full flex-col overflow-y-auto px-8 py-6">
-            <div className="mb-4 flex items-center justify-between gap-3">
-              <div className="min-w-0">
-                <div className="text-sm font-medium text-foreground">Project Notes</div>
-                <div className="mt-1 text-xs text-muted-foreground">
-                  Choose a saved note or start a new one.
-                </div>
-              </div>
-              <Button type="button" size="sm" variant="outline" onClick={createNewDraft}>
-                <Plus className="size-3.5" />
-                New note
-              </Button>
-            </div>
-            <div className="space-y-1">
-              {notes.map((note) => (
-                <button
-                  key={note.id}
-                  type="button"
-                  className="flex w-full items-start gap-2 rounded-md px-2.5 py-2 text-left hover:bg-accent/45"
-                  onClick={() => void selectNote(note.id)}
-                >
-                  <FileText className="mt-0.5 size-3.5 shrink-0 text-muted-foreground" />
-                  <span className="min-w-0 flex-1">
-                    <span className="block truncate text-sm font-medium text-foreground">
-                      {note.title}
-                    </span>
-                    <span className="mt-0.5 line-clamp-2 block text-xs leading-5 text-muted-foreground">
-                      {note.preview || note.relativePath}
-                    </span>
-                  </span>
-                </button>
-              ))}
-            </div>
-          </div>
-        ) : viewMode === 'source' ? (
-          <textarea
-            className="h-full w-full resize-none bg-background px-8 py-6 font-mono text-[13px] leading-6 text-foreground outline-none scrollbar-editor"
-            value={draft.bodyMarkdown}
-            spellCheck={false}
-            onChange={(event) => {
-              setDraft((current) => ({ ...current, bodyMarkdown: event.target.value }))
-              setDirty(true)
-            }}
-            onKeyDown={(event) => {
-              const isMac = navigator.userAgent.includes('Mac')
-              const saveShortcut = isMac ? event.metaKey : event.ctrlKey
-              if (saveShortcut && event.key.toLowerCase() === 's') {
-                event.preventDefault()
-                void saveDraft()
-              }
-            }}
-          />
-        ) : viewMode === 'preview' ? (
-          <MarkdownPreview
-            content={draft.bodyMarkdown}
-            filePath={editorFilePath}
-            scrollCacheKey={`notes:${draft.id ?? 'new'}:preview`}
-            markdownDocuments={markdownDocuments}
-            onOpenDocument={(document) => {
-              const note = notes.find((candidate) => candidate.filePath === document.filePath)
-              if (note) {
-                void selectNote(note.id)
-              }
-            }}
-          />
-        ) : (
-          <RichMarkdownEditor
-            fileId={draft.id ?? 'new-note'}
-            content={draft.bodyMarkdown}
-            filePath={editorFilePath}
-            worktreeId={worktreeId}
-            scrollCacheKey={`notes:${draft.id ?? 'new'}`}
-            onContentChange={(content) => {
-              setDraft((current) => ({ ...current, bodyMarkdown: content }))
-              setDirty(true)
-            }}
-            onDirtyStateHint={(nextDirty) => {
-              if (nextDirty) {
-                setDirty(true)
-              }
-            }}
-            onSave={(content) => {
-              setDraft((current) => ({ ...current, bodyMarkdown: content }))
-              setDirty(true)
-              void saveDraft(content)
-            }}
-            markdownDocuments={markdownDocuments}
-          />
-        )}
-      </div>
-      <Dialog
-        open={saveAsOpen}
-        onOpenChange={(isOpen) => {
-          if (isOpen) {
-            return
-          }
-          handleSaveAsCancel()
-        }}
-      >
-        <DialogContent showCloseButton={false} className="max-w-[340px]">
-          <DialogHeader>
-            <DialogTitle className="text-sm">Save project note</DialogTitle>
-            <DialogDescription className="text-xs">
-              Name this markdown note before saving it in Orca project notes.
-            </DialogDescription>
-          </DialogHeader>
-          <div>
-            <label className="mb-1 block text-[11px] font-medium text-muted-foreground">Name</label>
-            <div className="flex items-center gap-1.5">
-              <Input
-                ref={saveAsInputRef}
-                value={saveAsTitle}
-                onChange={(event) => setSaveAsTitle(event.target.value)}
-                onKeyDown={(event) => {
-                  if (event.key === 'Enter') {
-                    event.preventDefault()
-                    void confirmCreateNote()
-                  }
-                }}
-                className="h-8 text-sm"
-                placeholder="note name"
-              />
-              <span className="shrink-0 text-xs text-muted-foreground">.md</span>
-            </div>
-          </div>
-          <DialogFooter className="mt-1">
-            <Button variant="outline" size="sm" onClick={handleSaveAsCancel}>
-              Cancel
-            </Button>
-            <Button size="sm" disabled={saving} onClick={() => void confirmCreateNote()}>
-              Save
-            </Button>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
-      <Dialog
-        open={closePromptOpen}
-        onOpenChange={(isOpen) => {
-          if (!isOpen) {
-            handleClosePromptCancel()
-          }
-        }}
-      >
-        <DialogContent className="max-w-sm">
-          <DialogHeader>
-            <DialogTitle className="text-sm">Unsaved Changes</DialogTitle>
-            <DialogDescription className="text-xs">
-              &quot;{draft.title.trim() || 'Project Notes'}&quot; has unsaved changes. Do you want
-              to save before closing?
-            </DialogDescription>
-          </DialogHeader>
-          <DialogFooter className="gap-2">
-            <Button type="button" variant="outline" size="sm" onClick={handleClosePromptCancel}>
-              Cancel
-            </Button>
-            <Button type="button" variant="outline" size="sm" onClick={handleClosePromptDiscard}>
-              Don&apos;t Save
-            </Button>
-            <Button
-              type="button"
-              size="sm"
-              disabled={saving}
-              onClick={() => void handleClosePromptSave()}
-            >
-              Save
-            </Button>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
-    </div>
-  )
-}
diff --git a/src/renderer/src/components/right-sidebar/NotesPanel.tsx b/src/renderer/src/components/right-sidebar/NotesPanel.tsx
deleted file mode 100644
index b54ffc4d125..00000000000
--- a/src/renderer/src/components/right-sidebar/NotesPanel.tsx
+++ /dev/null
@@ -1,364 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
-import { Copy, FileText, Pencil, Plus, RefreshCw, Trash2 } from 'lucide-react'
-import { toast } from 'sonner'
-import { Button } from '@/components/ui/button'
-import {
-  ContextMenu,
-  ContextMenuContent,
-  ContextMenuItem,
-  ContextMenuSeparator,
-  ContextMenuTrigger
-} from '@/components/ui/context-menu'
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle
-} from '@/components/ui/dialog'
-import { Input } from '@/components/ui/input'
-import { useAppStore } from '@/store'
-import { useActiveWorktree, useRepoById } from '@/store/selectors'
-import { cn } from '@/lib/utils'
-import { getProjectNotesEntityId, openProjectNotesTab } from '@/lib/open-project-notes-tab'
-import { NOTES_ACTIVE_CHANGED_EVENT } from '@/lib/notes-events'
-import {
-  deleteRuntimeProjectNote,
-  listRuntimeProjectNotes,
-  renameRuntimeProjectNote
-} from '@/runtime/runtime-notes-client'
-import type { NoteSummary } from '../../../../shared/notes-types'
-
-export default function NotesPanel(): React.JSX.Element {
-  const activeWorktree = useActiveWorktree()
-  const repo = useRepoById(activeWorktree?.repoId ?? null)
-  const projectId = repo?.id ?? activeWorktree?.repoId ?? null
-  const worktreeId = activeWorktree?.id ?? null
-  const settings = useAppStore((s) => s.settings)
-
-  const [notes, setNotes] = useState<NoteSummary[]>([])
-  const [loading, setLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-  const [renamingNoteId, setRenamingNoteId] = useState<string | null>(null)
-  const [renameValue, setRenameValue] = useState('')
-  const [deleteTarget, setDeleteTarget] = useState<NoteSummary | null>(null)
-  const [deleting, setDeleting] = useState(false)
-  const renameCommittedRef = useRef(false)
-  const deleteConfirmButtonRef = useRef<HTMLButtonElement>(null)
-
-  const refresh = useCallback(async (): Promise<void> => {
-    if (!projectId || !worktreeId) {
-      setNotes([])
-      return
-    }
-    setLoading(true)
-    setError(null)
-    try {
-      const result = await listRuntimeProjectNotes(settings, { projectId, worktreeId, limit: 100 })
-      setNotes(result.notes)
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err))
-    } finally {
-      setLoading(false)
-    }
-  }, [projectId, settings, worktreeId])
-
-  useEffect(() => {
-    void refresh()
-  }, [refresh])
-
-  useEffect(() => {
-    const listener = (): void => {
-      void refresh()
-    }
-    window.addEventListener(NOTES_ACTIVE_CHANGED_EVENT, listener)
-    return () => window.removeEventListener(NOTES_ACTIVE_CHANGED_EVENT, listener)
-  }, [refresh])
-
-  const openNotes = useCallback(() => {
-    if (!worktreeId) {
-      return
-    }
-    void openProjectNotesTab(worktreeId)
-  }, [worktreeId])
-
-  const selectNote = useCallback(
-    async (noteId: string): Promise<void> => {
-      if (!projectId || !worktreeId) {
-        return
-      }
-      await openProjectNotesTab(worktreeId, noteId)
-      await refresh()
-    },
-    [projectId, refresh, worktreeId]
-  )
-
-  const startRename = useCallback((note: NoteSummary) => {
-    renameCommittedRef.current = false
-    setRenamingNoteId(note.id)
-    setRenameValue(note.title)
-  }, [])
-
-  const commitRename = useCallback(
-    async (note: NoteSummary): Promise<void> => {
-      if (renameCommittedRef.current) {
-        return
-      }
-      renameCommittedRef.current = true
-      const title = renameValue.trim()
-      setRenamingNoteId(null)
-      if (!projectId || !worktreeId || !title || title === note.title) {
-        return
-      }
-      try {
-        const result = await renameRuntimeProjectNote(settings, {
-          projectId,
-          worktreeId,
-          note: note.id,
-          title
-        })
-        const entityId = getProjectNotesEntityId(projectId, note.id)
-        const state = useAppStore.getState()
-        for (const tabs of Object.values(state.unifiedTabsByWorktree)) {
-          for (const tab of tabs) {
-            if (tab.contentType === 'notes' && tab.entityId === entityId) {
-              state.setTabLabel(tab.id, result.note.title)
-            }
-          }
-        }
-        await refresh()
-      } catch (err) {
-        toast.error(err instanceof Error ? err.message : `Failed to rename '${note.title}'.`)
-      }
-    },
-    [projectId, refresh, renameValue, settings, worktreeId]
-  )
-
-  const cancelRename = useCallback(() => {
-    renameCommittedRef.current = true
-    setRenamingNoteId(null)
-  }, [])
-
-  const confirmDeleteNote = useCallback(async (): Promise<void> => {
-    if (!projectId || !worktreeId || !deleteTarget || deleting) {
-      return
-    }
-    setDeleting(true)
-    try {
-      await deleteRuntimeProjectNote(settings, { projectId, worktreeId, note: deleteTarget.id })
-      const entityId = getProjectNotesEntityId(projectId, deleteTarget.id)
-      const state = useAppStore.getState()
-      const tabIdsToClose: string[] = []
-      for (const tabs of Object.values(state.unifiedTabsByWorktree)) {
-        for (const tab of tabs) {
-          if (tab.contentType === 'notes' && tab.entityId === entityId) {
-            tabIdsToClose.push(tab.id)
-          }
-        }
-      }
-      for (const tabId of tabIdsToClose) {
-        useAppStore.getState().closeUnifiedTab(tabId)
-      }
-      await refresh()
-      toast.success(`'${deleteTarget.title}' deleted`)
-      setDeleteTarget(null)
-    } catch (err) {
-      toast.error(err instanceof Error ? err.message : `Failed to delete '${deleteTarget.title}'.`)
-    } finally {
-      setDeleting(false)
-    }
-  }, [deleteTarget, deleting, projectId, refresh, settings, worktreeId])
-
-  const copyNotePath = useCallback(async (note: NoteSummary): Promise<void> => {
-    await navigator.clipboard.writeText(note.relativePath)
-    toast.success('Note path copied')
-  }, [])
-
-  if (!projectId || !worktreeId) {
-    return (
-      <div className="flex h-full items-center justify-center px-4 text-center text-sm text-muted-foreground">
-        Open a project worktree to use notes.
-      </div>
-    )
-  }
-
-  return (
-    <div className="flex h-full min-h-0 flex-col">
-      <div className="flex shrink-0 items-center gap-2 border-b border-border px-3 py-2">
-        <div className="min-w-0 flex-1">
-          <div className="truncate text-xs font-medium text-foreground">Project Notes</div>
-          <div className="line-clamp-2 text-[11px] leading-4 text-muted-foreground">
-            Shared across all workspaces for {repo?.displayName ?? 'this repo'}
-          </div>
-        </div>
-        <Button
-          type="button"
-          variant="ghost"
-          size="icon-xs"
-          aria-label="Refresh notes"
-          onClick={() => void refresh()}
-        >
-          <RefreshCw className={cn('size-3.5', loading && 'animate-spin')} />
-        </Button>
-        <Button
-          type="button"
-          variant="ghost"
-          size="icon-xs"
-          aria-label="New project notes tab"
-          onClick={openNotes}
-        >
-          <Plus className="size-3.5" />
-        </Button>
-      </div>
-
-      {error ? (
-        <div className="border-b border-border px-3 py-2 text-xs text-destructive">{error}</div>
-      ) : null}
-
-      <div className="min-h-0 flex-1 overflow-y-auto py-1">
-        {notes.length === 0 ? (
-          <div className="px-3 py-4">
-            <div className="text-xs font-medium text-foreground">No project notes yet</div>
-            <div className="mt-1 text-[11px] leading-4 text-muted-foreground">
-              Create one to keep repo context available across every workspace.
-            </div>
-          </div>
-        ) : (
-          notes.map((note) => (
-            <ContextMenu key={note.id}>
-              <ContextMenuTrigger asChild>
-                <div
-                  role="button"
-                  tabIndex={0}
-                  className="mx-1.5 flex w-[calc(100%-0.75rem)] items-start gap-2 rounded-md px-2 py-2 text-left hover:bg-accent/45"
-                  onClick={() => {
-                    if (renamingNoteId !== note.id) {
-                      void selectNote(note.id)
-                    }
-                  }}
-                  onKeyDown={(event) => {
-                    if (event.key !== 'Enter' && event.key !== ' ') {
-                      return
-                    }
-                    event.preventDefault()
-                    if (renamingNoteId !== note.id) {
-                      void selectNote(note.id)
-                    }
-                  }}
-                >
-                  <FileText className="mt-0.5 size-3.5 shrink-0 text-muted-foreground" />
-                  <span className="min-w-0 flex-1">
-                    {renamingNoteId === note.id ? (
-                      <Input
-                        autoFocus
-                        value={renameValue}
-                        className="h-6 px-2 text-xs"
-                        onClick={(event) => event.stopPropagation()}
-                        onChange={(event) => setRenameValue(event.target.value)}
-                        onFocus={(event) => event.currentTarget.select()}
-                        onBlur={() => void commitRename(note)}
-                        onKeyDown={(event) => {
-                          if (event.key === 'Enter') {
-                            event.preventDefault()
-                            void commitRename(note)
-                          } else if (event.key === 'Escape') {
-                            event.preventDefault()
-                            cancelRename()
-                          }
-                        }}
-                      />
-                    ) : (
-                      <span className="block truncate text-xs font-medium text-foreground">
-                        {note.title}
-                      </span>
-                    )}
-                    <span className="mt-0.5 line-clamp-2 block text-[11px] leading-4 text-muted-foreground">
-                      {note.preview || note.relativePath}
-                    </span>
-                  </span>
-                </div>
-              </ContextMenuTrigger>
-              <ContextMenuContent>
-                <ContextMenuItem onSelect={() => void selectNote(note.id)}>
-                  <FileText className="size-3.5" />
-                  Open
-                </ContextMenuItem>
-                <ContextMenuItem onSelect={() => startRename(note)}>
-                  <Pencil className="size-3.5" />
-                  Rename
-                </ContextMenuItem>
-                <ContextMenuItem onSelect={() => void copyNotePath(note)}>
-                  <Copy className="size-3.5" />
-                  Copy Path
-                </ContextMenuItem>
-                <ContextMenuSeparator />
-                <ContextMenuItem variant="destructive" onSelect={() => setDeleteTarget(note)}>
-                  <Trash2 className="size-3.5" />
-                  Delete
-                </ContextMenuItem>
-              </ContextMenuContent>
-            </ContextMenu>
-          ))
-        )}
-      </div>
-
-      <Dialog
-        open={deleteTarget !== null}
-        onOpenChange={(open) => {
-          if (open) {
-            return
-          }
-          setDeleteTarget(null)
-          setDeleting(false)
-        }}
-      >
-        <DialogContent
-          className="max-w-md"
-          onOpenAutoFocus={(event) => {
-            event.preventDefault()
-            deleteConfirmButtonRef.current?.focus()
-          }}
-        >
-          <DialogHeader>
-            <DialogTitle className="text-sm">Delete Project Note</DialogTitle>
-            <DialogDescription className="text-xs">
-              Delete{' '}
-              <span className="break-all font-medium text-foreground">{deleteTarget?.title}</span>?
-              This cannot be undone.
-            </DialogDescription>
-          </DialogHeader>
-          {deleteTarget ? (
-            <div className="rounded-md border border-border/70 bg-muted/35 px-3 py-2 text-xs">
-              <div className="break-all font-medium text-foreground">{deleteTarget.title}</div>
-              <div className="mt-1 break-all text-muted-foreground">
-                {deleteTarget.relativePath}
-              </div>
-            </div>
-          ) : null}
-          <DialogFooter>
-            <Button
-              variant="outline"
-              disabled={deleting}
-              onClick={() => {
-                setDeleteTarget(null)
-                setDeleting(false)
-              }}
-            >
-              Cancel
-            </Button>
-            <Button
-              ref={deleteConfirmButtonRef}
-              variant="destructive"
-              disabled={deleting}
-              onClick={() => void confirmDeleteNote()}
-            >
-              <Trash2 className="size-4" />
-              {deleting ? 'Deleting...' : 'Delete'}
-            </Button>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
-    </div>
-  )
-}
diff --git a/src/renderer/src/components/right-sidebar/index.tsx b/src/renderer/src/components/right-sidebar/index.tsx
index fd1db766e59..a5a69821891 100644
--- a/src/renderer/src/components/right-sidebar/index.tsx
+++ b/src/renderer/src/components/right-sidebar/index.tsx
@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useState } from 'react'
-import { Files, Search, GitBranch, ListChecks, Cable, PanelRight, FileText } from 'lucide-react'
+import { Files, Search, GitBranch, ListChecks, Cable, PanelRight } from 'lucide-react'
 import { useAppStore } from '@/store'
 import { getRepoMapFromState, useActiveWorktree, useRepoById } from '@/store/selectors'
 import { cn } from '@/lib/utils'
@@ -22,7 +22,6 @@ import SourceControl from './SourceControl'
 import SearchPanel from './Search'
 import ChecksPanel from './ChecksPanel'
 import PortsPanel from './PortsPanel'
-import NotesPanel from './NotesPanel'
 
 const MIN_WIDTH = 220
 // Why: long file names (e.g. construction drawing sheets, multi-part document
@@ -88,12 +87,6 @@ const ACTIVITY_ITEMS: ActivityBarItem[] = [
     title: 'Search',
     shortcut: `${isMac ? '\u21E7' : 'Shift+'}${mod}F`
   },
-  {
-    id: 'notes',
-    icon: FileText,
-    title: 'Project Notes',
-    shortcut: ''
-  },
   {
     id: 'source-control',
     icon: GitBranch,
@@ -252,7 +245,6 @@ function RightSidebarInner(): React.JSX.Element {
         {effectiveTab === 'source-control' && <SourceControl />}
         {effectiveTab === 'checks' && <ChecksPanel />}
         {effectiveTab === 'ports' && <PortsPanel />}
-        {effectiveTab === 'notes' && <NotesPanel />}
       </div>
     </div>
   )
diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index bdc5171e686..5cdfb2b7b5b 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -731,9 +731,6 @@ const WorktreeList = React.memo(function WorktreeList() {
   const needsTabs = showActiveOnly || sortBy === 'smart'
   const tabsByWorktree = useAppStore((s) => (needsTabs ? s.tabsByWorktree : null))
   const ptyIdsByTabId = useAppStore((s) => (needsTabs ? s.ptyIdsByTabId : null))
-  const unifiedTabsByWorktree = useAppStore((s) =>
-    showActiveOnly ? s.unifiedTabsByWorktree : null
-  )
   const browserTabsByWorktree = useAppStore((s) =>
     showActiveOnly ? s.browserTabsByWorktree : null
   )
@@ -989,7 +986,6 @@ const WorktreeList = React.memo(function WorktreeList() {
       showActiveOnly,
       tabsByWorktree,
       ptyIdsByTabId,
-      unifiedTabsByWorktree,
       browserTabsByWorktree,
       activeWorktreeId,
       hideDefaultBranchWorkspace,
@@ -1004,7 +1000,6 @@ const WorktreeList = React.memo(function WorktreeList() {
     repoMap,
     tabsByWorktree,
     ptyIdsByTabId,
-    unifiedTabsByWorktree,
     browserTabsByWorktree,
     sortedIds,
     worktreeMap,
diff --git a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
index 7dc2e2dacae..47e5c0ec84f 100644
--- a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
@@ -13,9 +13,6 @@ import {
 export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
   const tabs = useAppStore((s) => s.tabsByWorktree[worktreeId] ?? EMPTY_TABS)
   const browserTabs = useAppStore((s) => s.browserTabsByWorktree[worktreeId] ?? EMPTY_BROWSER_TABS)
-  const hasNotesSurface = useAppStore((s) =>
-    (s.unifiedTabsByWorktree[worktreeId] ?? []).some((tab) => tab.contentType === 'notes')
-  )
   const runtimePaneTitlesForWorktree = useAppStore(
     useShallow((s) => selectRuntimePaneTitlesForWorktree(s, worktreeId))
   )
@@ -74,7 +71,6 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
         browserTabs,
         ptyIdsByTabId: ptyIdsForWorktree,
         runtimePaneTitlesByTabId: runtimePaneTitlesForWorktree,
-        hasNotesSurface,
         hasPermission,
         hasLiveDone,
         hasRetainedDone
@@ -84,7 +80,6 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
       browserTabs,
       ptyIdsForWorktree,
       runtimePaneTitlesForWorktree,
-      hasNotesSurface,
       hasPermission,
       hasLiveDone,
       hasRetainedDone
diff --git a/src/renderer/src/components/sidebar/visible-worktrees.test.ts b/src/renderer/src/components/sidebar/visible-worktrees.test.ts
index becd27e9d3f..d53d8095dab 100644
--- a/src/renderer/src/components/sidebar/visible-worktrees.test.ts
+++ b/src/renderer/src/components/sidebar/visible-worktrees.test.ts
@@ -6,7 +6,7 @@ import {
   isDefaultBranchWorkspace,
   sidebarHasActiveFilters
 } from './visible-worktrees'
-import type { Repo, Tab, TerminalTab, Worktree } from '../../../../shared/types'
+import type { Repo, TerminalTab, Worktree } from '../../../../shared/types'
 
 function makeTab(id: string, worktreeId: string, ptyId: string | null): TerminalTab {
   return {
@@ -21,21 +21,6 @@ function makeTab(id: string, worktreeId: string, ptyId: string | null): Terminal
   }
 }
 
-function makeNotesTab(id: string, worktreeId: string): Tab {
-  return {
-    id,
-    entityId: `notes:${worktreeId}:${id}`,
-    groupId: 'group-1',
-    worktreeId,
-    contentType: 'notes',
-    label: 'Project Notes',
-    customLabel: null,
-    color: null,
-    sortOrder: 0,
-    createdAt: 0
-  }
-}
-
 function makeWorktree(id: string, repoId = 'repo1'): Worktree {
   return {
     id,
@@ -110,22 +95,6 @@ describe('computeVisibleWorktreeIds', () => {
     expect(result).toEqual([wt.id])
   })
 
-  it('treats project-notes tabs as active for the active-only filter', () => {
-    const notesWt = makeWorktree('wt-notes')
-    const unrelatedWt = makeWorktree('wt-unrelated')
-
-    const result = computeVisibleWorktreeIds(
-      { repo1: [notesWt, unrelatedWt] },
-      [notesWt.id, unrelatedWt.id],
-      visibleOptions({
-        showActiveOnly: true,
-        unifiedTabsByWorktree: { [notesWt.id]: [makeNotesTab('notes-1', notesWt.id)] }
-      })
-    )
-
-    expect(result).toEqual([notesWt.id])
-  })
-
   it('keeps the currently active worktree visible even without PTYs', () => {
     const wt = makeWorktree('wt-active')
 
diff --git a/src/renderer/src/components/sidebar/visible-worktrees.ts b/src/renderer/src/components/sidebar/visible-worktrees.ts
index 78cccf01c3f..2f6a632b834 100644
--- a/src/renderer/src/components/sidebar/visible-worktrees.ts
+++ b/src/renderer/src/components/sidebar/visible-worktrees.ts
@@ -1,4 +1,4 @@
-import type { Worktree, Repo, Tab, TerminalTab } from '../../../../shared/types'
+import type { Worktree, Repo, TerminalTab } from '../../../../shared/types'
 import { buildWorktreeComparator, sortWorktreesSmart } from './smart-sort'
 import { tabHasLivePty } from '@/lib/tab-has-live-pty'
 import { useAppStore } from '@/store'
@@ -81,7 +81,6 @@ export function computeVisibleWorktreeIds(
     showActiveOnly: boolean
     tabsByWorktree: Record<string, TerminalTab[]> | null
     ptyIdsByTabId: Record<string, string[]> | null
-    unifiedTabsByWorktree?: Record<string, Tab[]> | null
     browserTabsByWorktree?: Record<string, { id: string }[]> | null
     activeWorktreeId?: string | null
     // Why required: every caller (WorktreeList, getVisibleWorktreeIds
@@ -115,15 +114,11 @@ export function computeVisibleWorktreeIds(
         opts.ptyIdsByTabId ? tabHasLivePty(opts.ptyIdsByTabId, tab.id) : false
       )
       const hasBrowserTabs = (opts.browserTabsByWorktree?.[w.id] ?? []).length > 0
-      const hasNotesTabs = (opts.unifiedTabsByWorktree?.[w.id] ?? []).some(
-        (tab) => tab.contentType === 'notes'
-      )
       // Why: "Active only" should reflect the surfaces Orca can actually
       // restore into, not just PTY-backed terminals. A browser-tab worktree is
-      // still active from the user's point of view even if it has no live PTY.
-      // Project notes follow the same rule because they are workspace tabs
-      // backed by the notes store, not PTY-backed terminal state.
-      return hasLiveTerminal || hasBrowserTabs || hasNotesTabs || opts.activeWorktreeId === w.id
+      // still active from the user's point of view even if it has no live PTY,
+      // and the currently selected worktree should never vanish from the list.
+      return hasLiveTerminal || hasBrowserTabs || opts.activeWorktreeId === w.id
     })
   }
 
@@ -207,7 +202,6 @@ export function getVisibleWorktreeIds(): string[] {
     showActiveOnly: state.showActiveOnly,
     tabsByWorktree: state.tabsByWorktree,
     ptyIdsByTabId: state.ptyIdsByTabId,
-    unifiedTabsByWorktree: state.unifiedTabsByWorktree,
     browserTabsByWorktree: state.browserTabsByWorktree,
     activeWorktreeId: state.activeWorktreeId,
     hideDefaultBranchWorkspace: state.hideDefaultBranchWorkspace,
diff --git a/src/renderer/src/components/tab-bar/ProjectNotesTab.tsx b/src/renderer/src/components/tab-bar/ProjectNotesTab.tsx
deleted file mode 100644
index 415bf6d85ad..00000000000
--- a/src/renderer/src/components/tab-bar/ProjectNotesTab.tsx
+++ /dev/null
@@ -1,131 +0,0 @@
-import { useEffect, useState } from 'react'
-import { useSortable } from '@dnd-kit/sortable'
-import { Columns2, FileText, Rows2, X } from 'lucide-react'
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger
-} from '@/components/ui/dropdown-menu'
-import { CLOSE_ALL_CONTEXT_MENUS_EVENT } from './SortableTab'
-import type { TabDragItemData } from '../tab-group/useTabDragSplit'
-import {
-  ACTIVE_TAB_INDICATOR_CLASSES,
-  getDropIndicatorClasses,
-  type DropIndicator
-} from './drop-indicator'
-
-export type ProjectNotesTabState = {
-  id: string
-  label: string
-  isDirty: boolean
-}
-
-export function ProjectNotesTab({
-  tab,
-  isActive,
-  hasTabsToRight,
-  onActivate,
-  onClose,
-  onCloseToRight,
-  onSplitGroup,
-  dragData,
-  dropIndicator
-}: {
-  tab: ProjectNotesTabState
-  isActive: boolean
-  hasTabsToRight: boolean
-  onActivate: () => void
-  onClose: () => void
-  onCloseToRight: () => void
-  onSplitGroup: (direction: 'left' | 'right' | 'up' | 'down', sourceVisibleTabId: string) => void
-  dragData: TabDragItemData
-  dropIndicator?: DropIndicator
-}): React.JSX.Element {
-  const { attributes, listeners, setNodeRef } = useSortable({
-    id: tab.id,
-    data: dragData
-  })
-  const [menuOpen, setMenuOpen] = useState(false)
-  const [menuPoint, setMenuPoint] = useState({ x: 0, y: 0 })
-
-  useEffect(() => {
-    const closeMenu = (): void => setMenuOpen(false)
-    window.addEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
-    return () => window.removeEventListener(CLOSE_ALL_CONTEXT_MENUS_EVENT, closeMenu)
-  }, [])
-
-  return (
-    <>
-      <div
-        ref={setNodeRef}
-        {...attributes}
-        {...listeners}
-        onClick={onActivate}
-        onContextMenuCapture={(event) => {
-          event.preventDefault()
-          window.dispatchEvent(new Event(CLOSE_ALL_CONTEXT_MENUS_EVENT))
-          setMenuPoint({ x: event.clientX, y: event.clientY })
-          setMenuOpen(true)
-        }}
-        className={`group relative flex h-full min-w-[120px] max-w-[220px] items-center gap-1.5 border-l border-border px-2 text-xs ${
-          hasTabsToRight ? 'border-r border-r-border/70' : ''
-        } ${isActive ? 'bg-background text-foreground' : 'bg-card text-muted-foreground hover:bg-muted/50 hover:text-foreground'}`}
-        role="tab"
-        aria-selected={isActive}
-      >
-        {dropIndicator ? <div className={getDropIndicatorClasses(dropIndicator)} /> : null}
-        <FileText className="size-3.5 shrink-0" />
-        <span className="min-w-0 flex-1 truncate">{tab.label}</span>
-        <div className="relative flex size-4 shrink-0 items-center justify-center">
-          {tab.isDirty ? (
-            <span className="absolute size-1.5 rounded-full bg-foreground/60 group-hover:hidden" />
-          ) : null}
-          <button
-            type="button"
-            className={`flex size-4 items-center justify-center rounded-sm ${
-              tab.isDirty
-                ? 'hidden text-muted-foreground hover:bg-muted hover:text-foreground group-hover:flex'
-                : isActive
-                  ? 'text-muted-foreground hover:bg-muted hover:text-foreground'
-                  : 'text-transparent hover:!bg-muted hover:!text-foreground group-hover:text-muted-foreground'
-            }`}
-            onClick={(event) => {
-              event.stopPropagation()
-              onClose()
-            }}
-            aria-label="Close Project Notes"
-          >
-            <X className="size-3" />
-          </button>
-        </div>
-        {isActive ? <div className={ACTIVE_TAB_INDICATOR_CLASSES} /> : null}
-      </div>
-      <DropdownMenu open={menuOpen} onOpenChange={setMenuOpen}>
-        <DropdownMenuTrigger asChild>
-          <span
-            className="fixed size-px"
-            style={{ left: menuPoint.x, top: menuPoint.y }}
-            aria-hidden
-          />
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="start">
-          <DropdownMenuItem onSelect={() => onSplitGroup('right', tab.id)}>
-            <Columns2 className="size-4" />
-            Split Right
-          </DropdownMenuItem>
-          <DropdownMenuItem onSelect={() => onSplitGroup('down', tab.id)}>
-            <Rows2 className="size-4" />
-            Split Down
-          </DropdownMenuItem>
-          <DropdownMenuSeparator />
-          <DropdownMenuItem onSelect={onCloseToRight}>Close Tabs to Right</DropdownMenuItem>
-          <DropdownMenuItem variant="destructive" onSelect={onClose}>
-            Close
-          </DropdownMenuItem>
-        </DropdownMenuContent>
-      </DropdownMenu>
-    </>
-  )
-}
diff --git a/src/renderer/src/components/tab-bar/TabBar.context-menu.test.ts b/src/renderer/src/components/tab-bar/TabBar.context-menu.test.ts
index e76a2c69ecc..1170506a349 100644
--- a/src/renderer/src/components/tab-bar/TabBar.context-menu.test.ts
+++ b/src/renderer/src/components/tab-bar/TabBar.context-menu.test.ts
@@ -26,7 +26,6 @@ vi.mock('react', async () => {
     memo: <T>(component: T) => component,
     useEffect: () => {},
     useLayoutEffect: () => {},
-    useCallback: <T>(callback: T) => callback,
     useMemo: <T>(factory: () => T) => factory(),
     useRef: <T>(current: T) => ({ current }),
     useState: <T>(initial: T) => [initial, vi.fn()] as const
@@ -37,9 +36,6 @@ vi.mock('lucide-react', () => ({
   FilePlus: function FilePlus() {
     return null
   },
-  FileText: function FileText() {
-    return null
-  },
   Globe: function Globe() {
     return null
   },
@@ -127,15 +123,6 @@ vi.mock('@/components/ui/dropdown-menu', () => ({
   DropdownMenuShortcut: function DropdownMenuShortcut(props: { children?: unknown }) {
     return { type: 'DropdownMenuShortcut', props }
   },
-  DropdownMenuSub: function DropdownMenuSub(props: { children?: unknown }) {
-    return { type: 'DropdownMenuSub', props }
-  },
-  DropdownMenuSubContent: function DropdownMenuSubContent(props: { children?: unknown }) {
-    return { type: 'DropdownMenuSubContent', props }
-  },
-  DropdownMenuSubTrigger: function DropdownMenuSubTrigger(props: { children?: unknown }) {
-    return { type: 'DropdownMenuSubTrigger', props }
-  },
   DropdownMenuTrigger: function DropdownMenuTrigger(props: { children?: unknown }) {
     return { type: 'DropdownMenuTrigger', props }
   }
diff --git a/src/renderer/src/components/tab-bar/TabBar.tsx b/src/renderer/src/components/tab-bar/TabBar.tsx
index 91eef724ba0..7d969a810b1 100644
--- a/src/renderer/src/components/tab-bar/TabBar.tsx
+++ b/src/renderer/src/components/tab-bar/TabBar.tsx
@@ -5,7 +5,7 @@
  * more clarity than the ~5 lines of bloat is worth. */
 import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { SortableContext } from '@dnd-kit/sortable'
-import { FilePlus, Globe, Plus, TerminalSquare, FileText } from 'lucide-react'
+import { FilePlus, Globe, Plus, TerminalSquare } from 'lucide-react'
 import type {
   BrowserTab as BrowserTabState,
   TerminalTab,
@@ -17,7 +17,6 @@ import type { OpenFile } from '../../store/slices/editor'
 import SortableTab from './SortableTab'
 import EditorFileTab from './EditorFileTab'
 import BrowserTab, { getBrowserTabLabel } from './BrowserTab'
-import { ProjectNotesTab, type ProjectNotesTabState } from './ProjectNotesTab'
 import { QuickLaunchAgentMenuItems } from './QuickLaunchButton'
 import type { DropIndicator } from './drop-indicator'
 import { reconcileTabOrder } from './reconcile-order'
@@ -33,13 +32,8 @@ import {
   DropdownMenuItem,
   DropdownMenuSeparator,
   DropdownMenuShortcut,
-  DropdownMenuSub,
-  DropdownMenuSubContent,
-  DropdownMenuSubTrigger,
   DropdownMenuTrigger
 } from '@/components/ui/dropdown-menu'
-import { listRuntimeProjectNotes } from '@/runtime/runtime-notes-client'
-import type { NoteSummary } from '../../../../shared/notes-types'
 
 const isMac = navigator.userAgent.includes('Mac')
 const isWindows = navigator.userAgent.includes('Windows')
@@ -64,8 +58,6 @@ type TabBarProps = {
   terminalOnly?: boolean
   showAgentLaunchItems?: boolean
   onNewFileTab?: () => void
-  onNewNotesTab?: (noteId?: string) => void
-  notesWorktreeId?: string | null
   /** Whether WSL is installed on this Windows machine. When true, the "+"
    *  dropdown shows a WSL option under the terminal submenu. */
   wslAvailable?: boolean
@@ -74,17 +66,13 @@ type TabBarProps = {
   onTogglePaneExpand: (tabId: string) => void
   editorFiles?: (OpenFile & { tabId?: string })[]
   browserTabs?: (BrowserTabState & { tabId?: string })[]
-  notesTabs?: ProjectNotesTabState[]
   activeFileId?: string | null
   activeBrowserTabId?: string | null
-  activeNotesTabId?: string | null
   activeTabType?: WorkspaceVisibleTabType
   onActivateFile?: (fileId: string) => void
   onCloseFile?: (fileId: string) => void
   onActivateBrowserTab?: (tabId: string) => void
   onCloseBrowserTab?: (tabId: string) => void
-  onActivateNotesTab?: (tabId: string) => void
-  onCloseNotesTab?: (tabId: string) => void
   onDuplicateBrowserTab?: (tabId: string) => void
   onCloseAllFiles?: () => void
   onPinFile?: (fileId: string, tabId?: string) => void
@@ -110,7 +98,6 @@ type TabItem =
       unifiedTabId: string
       data: BrowserTabState & { tabId?: string }
     }
-  | { type: 'notes'; id: string; unifiedTabId: string; data: ProjectNotesTabState }
 
 function getTabDragLabel(item: TabItem): string {
   if (item.type === 'terminal') {
@@ -119,9 +106,6 @@ function getTabDragLabel(item: TabItem): string {
   if (item.type === 'browser') {
     return getBrowserTabLabel(item.data)
   }
-  if (item.type === 'notes') {
-    return item.data.label
-  }
   return getEditorDisplayLabel(item.data)
 }
 
@@ -141,24 +125,18 @@ function TabBarInner({
   terminalOnly = false,
   showAgentLaunchItems = true,
   onNewFileTab,
-  onNewNotesTab,
-  notesWorktreeId,
   onSetCustomTitle,
   onSetTabColor,
   onTogglePaneExpand,
   editorFiles,
   browserTabs,
-  notesTabs,
   activeFileId,
   activeBrowserTabId,
-  activeNotesTabId,
   activeTabType,
   onActivateFile,
   onCloseFile,
   onActivateBrowserTab,
   onCloseBrowserTab,
-  onActivateNotesTab,
-  onCloseNotesTab,
   onDuplicateBrowserTab,
   onCloseAllFiles,
   onPinFile,
@@ -174,12 +152,7 @@ function TabBarInner({
   const defaultWindowsPowerShellImplementation = useAppStore(
     (s) => s.settings?.terminalWindowsPowerShellImplementation ?? 'auto'
   )
-  const settings = useAppStore((s) => s.settings)
   const [pwshAvailable, setPwshAvailable] = useState(false)
-  const [projectNotes, setProjectNotes] = useState<NoteSummary[]>([])
-  const [projectNotesLoading, setProjectNotesLoading] = useState(false)
-  const [projectNotesError, setProjectNotesError] = useState<string | null>(null)
-  const [projectNotesMenuOpen, setProjectNotesMenuOpen] = useState(false)
   useEffect(() => {
     if (!isWindows) {
       setPwshAvailable(false)
@@ -189,7 +162,6 @@ function TabBarInner({
     void window.api.pwsh.isAvailable().then(setPwshAvailable)
   }, [])
   const resolvedGroupId = groupId ?? worktreeId
-  const targetNotesWorktreeId = notesWorktreeId ?? worktreeId
 
   const statusByRelativePath = useMemo(
     () => buildStatusMap(gitStatusByWorktree[worktreeId] ?? []),
@@ -211,49 +183,6 @@ function TabBarInner({
     return () => window.removeEventListener('blur', dismiss)
   }, [newTabMenuOpen])
 
-  useEffect(() => {
-    if (!newTabMenuOpen) {
-      setProjectNotesMenuOpen(false)
-      return
-    }
-    const refreshProjectNotes = async (): Promise<void> => {
-      if (!onNewNotesTab) {
-        return
-      }
-      let context: { projectId: string; worktreeId: string } | null = null
-      if (targetNotesWorktreeId) {
-        const state = useAppStore.getState()
-        const worktree = Object.values(state.worktreesByRepo)
-          .flat()
-          .find((candidate) => candidate.id === targetNotesWorktreeId)
-        if (worktree) {
-          const repo = state.repos.find((candidate) => candidate.id === worktree.repoId)
-          context = { projectId: repo?.id ?? worktree.repoId, worktreeId: targetNotesWorktreeId }
-        }
-      }
-      if (!context) {
-        setProjectNotes([])
-        setProjectNotesError(null)
-        return
-      }
-      setProjectNotesLoading(true)
-      setProjectNotesError(null)
-      try {
-        const result = await listRuntimeProjectNotes(settings, {
-          projectId: context.projectId,
-          worktreeId: context.worktreeId,
-          limit: 100
-        })
-        setProjectNotes(result.notes)
-      } catch (err) {
-        setProjectNotesError(err instanceof Error ? err.message : String(err))
-      } finally {
-        setProjectNotesLoading(false)
-      }
-    }
-    void refreshProjectNotes()
-  }, [newTabMenuOpen, onNewNotesTab, settings, targetNotesWorktreeId])
-
   const terminalMap = useMemo(() => new Map(tabs.map((t) => [t.id, t])), [tabs])
   const editorMap = useMemo(
     () => new Map((editorFiles ?? []).map((f) => [f.tabId ?? f.id, f])),
@@ -263,22 +192,14 @@ function TabBarInner({
     () => new Map((browserTabs ?? []).map((t) => [t.id, t])),
     [browserTabs]
   )
-  const notesMap = useMemo(() => new Map((notesTabs ?? []).map((t) => [t.id, t])), [notesTabs])
 
   const terminalIds = useMemo(() => tabs.map((t) => t.id), [tabs])
   const editorFileIds = useMemo(() => editorFiles?.map((f) => f.tabId ?? f.id) ?? [], [editorFiles])
   const browserTabIds = useMemo(() => browserTabs?.map((tab) => tab.id) ?? [], [browserTabs])
-  const notesTabIds = useMemo(() => notesTabs?.map((tab) => tab.id) ?? [], [notesTabs])
 
   // Build the unified ordered list, reconciling stored order with current items
   const orderedItems = useMemo(() => {
-    const ids = reconcileTabOrder(
-      tabBarOrder,
-      terminalIds,
-      editorFileIds,
-      browserTabIds,
-      notesTabIds
-    )
+    const ids = reconcileTabOrder(tabBarOrder, terminalIds, editorFileIds, browserTabIds)
     const items: TabItem[] = []
     for (const id of ids) {
       const terminal = terminalMap.get(id)
@@ -306,23 +227,9 @@ function TabBarInner({
         })
         continue
       }
-      const notesTab = notesMap.get(id)
-      if (notesTab) {
-        items.push({ type: 'notes', id, unifiedTabId: notesTab.id, data: notesTab })
-      }
     }
     return items
-  }, [
-    tabBarOrder,
-    terminalIds,
-    editorFileIds,
-    browserTabIds,
-    notesTabIds,
-    terminalMap,
-    editorMap,
-    browserMap,
-    notesMap
-  ])
+  }, [tabBarOrder, terminalIds, editorFileIds, browserTabIds, terminalMap, editorMap, browserMap])
 
   const sortableIds = useMemo(() => orderedItems.map((item) => item.id), [orderedItems])
 
@@ -521,24 +428,6 @@ function TabBarInner({
                 />
               )
             }
-            if (item.type === 'notes') {
-              return (
-                <ProjectNotesTab
-                  key={item.id}
-                  tab={item.data}
-                  isActive={activeTabType === 'notes' && activeNotesTabId === item.id}
-                  hasTabsToRight={index < orderedItems.length - 1}
-                  onActivate={() => onActivateNotesTab?.(item.id)}
-                  onClose={() => onCloseNotesTab?.(item.id)}
-                  onCloseToRight={() => onCloseToRight(item.id)}
-                  onSplitGroup={(direction, sourceVisibleTabId) =>
-                    onCreateSplitGroup?.(direction, sourceVisibleTabId)
-                  }
-                  dragData={dragData}
-                  dropIndicator={dropIndicatorByVisibleId.get(item.id) ?? null}
-                />
-              )
-            }
             return (
               <EditorFileTab
                 key={item.id}
@@ -677,77 +566,6 @@ function TabBarInner({
               <DropdownMenuShortcut>{NEW_FILE_SHORTCUT}</DropdownMenuShortcut>
             </DropdownMenuItem>
           )}
-          {onNewNotesTab && (
-            <DropdownMenuSub open={projectNotesMenuOpen} onOpenChange={setProjectNotesMenuOpen}>
-              <DropdownMenuSubTrigger
-                className="gap-2 rounded-[7px] px-2 py-1.5 text-[12px] leading-5 font-medium"
-                onPointerEnter={() => setProjectNotesMenuOpen(true)}
-                onFocus={() => setProjectNotesMenuOpen(true)}
-                onClick={() => {
-                  // Why: this row looks like the other creation commands in
-                  // the + menu. Keep hover-to-pick-saved-note, but make a
-                  // direct click create a fresh note instead of only opening
-                  // the submenu.
-                  onNewNotesTab()
-                  setProjectNotesMenuOpen(false)
-                  setNewTabMenuOpen(false)
-                }}
-                onKeyDown={(event) => {
-                  if (event.key !== 'Enter' && event.key !== ' ') {
-                    return
-                  }
-                  event.preventDefault()
-                  onNewNotesTab()
-                  setProjectNotesMenuOpen(false)
-                  setNewTabMenuOpen(false)
-                }}
-              >
-                <FileText className="size-4 text-muted-foreground" />
-                Project Notes
-              </DropdownMenuSubTrigger>
-              <DropdownMenuSubContent className="w-64">
-                <DropdownMenuItem
-                  onSelect={() => onNewNotesTab()}
-                  className="gap-2 rounded-[7px] px-2 py-1.5 text-[12px] leading-5 font-medium"
-                >
-                  <FileText className="size-3.5 text-muted-foreground" />
-                  New Project Note
-                </DropdownMenuItem>
-                <DropdownMenuSeparator />
-                {projectNotesLoading ? (
-                  <DropdownMenuItem disabled className="text-muted-foreground">
-                    Loading notes...
-                  </DropdownMenuItem>
-                ) : projectNotesError ? (
-                  <DropdownMenuItem disabled className="text-destructive">
-                    Failed to load notes
-                  </DropdownMenuItem>
-                ) : projectNotes.length === 0 ? (
-                  <DropdownMenuItem disabled className="text-muted-foreground">
-                    No saved notes
-                  </DropdownMenuItem>
-                ) : (
-                  <div className="max-h-64 overflow-y-auto pr-0.5">
-                    {projectNotes.map((note) => (
-                      <DropdownMenuItem
-                        key={note.id}
-                        onSelect={() => onNewNotesTab(note.id)}
-                        className="items-start gap-2 rounded-[7px] px-2 py-1.5 text-[12px] leading-5"
-                      >
-                        <FileText className="mt-0.5 size-3.5 text-muted-foreground" />
-                        <span className="min-w-0 flex-1">
-                          <span className="block truncate font-medium">{note.title}</span>
-                          <span className="block truncate text-[11px] leading-4 text-muted-foreground">
-                            {note.preview || note.relativePath}
-                          </span>
-                        </span>
-                      </DropdownMenuItem>
-                    ))}
-                  </div>
-                )}
-              </DropdownMenuSubContent>
-            </DropdownMenuSub>
-          )}
           {showAgentLaunchItems ? (
             <>
               <DropdownMenuSeparator />
diff --git a/src/renderer/src/components/tab-bar/TabDragPreview.tsx b/src/renderer/src/components/tab-bar/TabDragPreview.tsx
index 314dad9859b..ad0e51591f1 100644
--- a/src/renderer/src/components/tab-bar/TabDragPreview.tsx
+++ b/src/renderer/src/components/tab-bar/TabDragPreview.tsx
@@ -1,4 +1,4 @@
-import { FileCode, Globe, Terminal as TerminalIcon, FileText } from 'lucide-react'
+import { FileCode, Globe, Terminal as TerminalIcon } from 'lucide-react'
 import type { TabDragItemData } from '../tab-group/useTabDragSplit'
 
 // Why: rendered inside dnd-kit's DragOverlay (a document-level portal), so
@@ -9,13 +9,7 @@ import type { TabDragItemData } from '../tab-group/useTabDragSplit'
 // the wrapper's top-left.
 export default function TabDragPreview({ drag }: { drag: TabDragItemData }): React.JSX.Element {
   const Icon =
-    drag.tabType === 'browser'
-      ? Globe
-      : drag.tabType === 'editor'
-        ? FileCode
-        : drag.tabType === 'notes'
-          ? FileText
-          : TerminalIcon
+    drag.tabType === 'browser' ? Globe : drag.tabType === 'editor' ? FileCode : TerminalIcon
   return (
     <div className="pointer-events-none flex h-full w-full items-center gap-1.5 rounded-sm border border-border bg-accent px-2 text-xs text-foreground shadow-md">
       <Icon className="h-3.5 w-3.5 shrink-0" />
diff --git a/src/renderer/src/components/tab-bar/group-tab-order.ts b/src/renderer/src/components/tab-bar/group-tab-order.ts
index b0d4fa2f1e6..5ca2dfa81a8 100644
--- a/src/renderer/src/components/tab-bar/group-tab-order.ts
+++ b/src/renderer/src/components/tab-bar/group-tab-order.ts
@@ -3,7 +3,7 @@ import type { AppState } from '../../store/types'
 import { reconcileTabOrder } from './reconcile-order'
 
 export type VisibleTabRef = {
-  type: 'terminal' | 'editor' | 'browser' | 'notes'
+  type: 'terminal' | 'editor' | 'browser'
   id: string
   tabId?: string
 }
@@ -12,7 +12,6 @@ export type ActiveTabNavOrderIds = {
   terminalIds?: string[]
   editorIds?: string[]
   browserIds?: string[]
-  notesIds?: string[]
 }
 
 /**
@@ -63,7 +62,6 @@ export function getGroupVisibleTabOrder(
   const seenTerminals = new Set<string>()
   const seenBrowsers = new Set<string>()
   const seenEditors = new Set<string>()
-  const seenNotes = new Set<string>()
   for (const unifiedId of group.tabOrder) {
     const tab = tabsById.get(unifiedId)
     if (!tab) {
@@ -81,12 +79,6 @@ export function getGroupVisibleTabOrder(
       }
       seenBrowsers.add(tab.entityId)
       result.push({ type: 'browser', id: tab.entityId, tabId: tab.id })
-    } else if (tab.contentType === 'notes') {
-      if (seenNotes.has(tab.id)) {
-        continue
-      }
-      seenNotes.add(tab.id)
-      result.push({ type: 'notes', id: tab.id, tabId: tab.id })
     } else {
       if (!editorEntityIds.has(tab.entityId) || seenEditors.has(tab.id)) {
         continue
@@ -131,11 +123,6 @@ export function getActiveTabNavOrder(
     ids.editorIds ?? state.openFiles.filter((f) => f.worktreeId === worktreeId).map((f) => f.id)
   const browserIds =
     ids.browserIds ?? (state.browserTabsByWorktree?.[worktreeId] ?? []).map((t) => t.id)
-  const notesIds =
-    ids.notesIds ??
-    (state.unifiedTabsByWorktree?.[worktreeId] ?? [])
-      .filter((tab) => tab.contentType === 'notes')
-      .map((tab) => tab.id)
 
   const activeGroupId = state.activeGroupIdByWorktree[worktreeId]
   const group = activeGroupId
@@ -160,13 +147,11 @@ export function getActiveTabNavOrder(
     state.tabBarOrderByWorktree[worktreeId],
     terminalIds,
     editorIds,
-    browserIds,
-    notesIds
+    browserIds
   )
   const terminalIdSet = new Set(terminalIds)
   const editorIdSet = new Set(editorIds)
   const browserIdSet = new Set(browserIds)
-  const notesIdSet = new Set(notesIds)
   const result: VisibleTabRef[] = []
   for (const id of visibleIds) {
     if (terminalIdSet.has(id)) {
@@ -175,8 +160,6 @@ export function getActiveTabNavOrder(
       result.push({ type: 'editor', id })
     } else if (browserIdSet.has(id)) {
       result.push({ type: 'browser', id })
-    } else if (notesIdSet.has(id)) {
-      result.push({ type: 'notes', id, tabId: id })
     }
   }
   return result
diff --git a/src/renderer/src/components/tab-bar/reconcile-order.ts b/src/renderer/src/components/tab-bar/reconcile-order.ts
index af2b4629ae3..6fce831d986 100644
--- a/src/renderer/src/components/tab-bar/reconcile-order.ts
+++ b/src/renderer/src/components/tab-bar/reconcile-order.ts
@@ -7,10 +7,9 @@ export function reconcileTabOrder(
   storedOrder: string[] | undefined,
   terminalIds: string[],
   editorIds: string[],
-  browserIds: string[] = [],
-  notesIds: string[] = []
+  browserIds: string[] = []
 ): string[] {
-  const validIds = new Set([...terminalIds, ...editorIds, ...browserIds, ...notesIds])
+  const validIds = new Set([...terminalIds, ...editorIds, ...browserIds])
   // Why: storedOrder is persisted group tab order and is mutated by many
   // codepaths (drop/move/reorder/hydrate). A stale or racey write can leave
   // the same tab id twice in the list, which surfaces as React's "two
@@ -25,7 +24,7 @@ export function reconcileTabOrder(
       inResult.add(id)
     }
   }
-  for (const id of [...terminalIds, ...editorIds, ...browserIds, ...notesIds]) {
+  for (const id of [...terminalIds, ...editorIds, ...browserIds]) {
     if (!inResult.has(id)) {
       result.push(id)
       inResult.add(id)
diff --git a/src/renderer/src/components/tab-group/TabGroupPanel.tsx b/src/renderer/src/components/tab-group/TabGroupPanel.tsx
index ec92e9748a2..bd86341ad33 100644
--- a/src/renderer/src/components/tab-group/TabGroupPanel.tsx
+++ b/src/renderer/src/components/tab-group/TabGroupPanel.tsx
@@ -1,4 +1,3 @@
-/* eslint-disable max-lines -- Why: this pane shell coordinates terminals, editor tabs, browser slots, and notes tabs so split-group routing stays in one place. */
 import { lazy, Suspense, useEffect, useMemo, useState } from 'react'
 import { useDroppable } from '@dnd-kit/core'
 import { Columns2, Ellipsis, Rows2, X } from 'lucide-react'
@@ -20,13 +19,8 @@ import {
   type TabDropZone
 } from './useTabDragSplit'
 import { tabGroupBodyAnchorName } from './tab-group-body-anchor'
-import {
-  getProjectNoteIdFromEntityId,
-  isNewProjectNoteEntityId
-} from '@/lib/open-project-notes-tab'
 
 const EditorPanel = lazy(() => import('../editor/EditorPanel'))
-const ProjectNotesTabContent = lazy(() => import('../notes/ProjectNotesTabContent'))
 
 export default function TabGroupPanel({
   groupId,
@@ -62,8 +56,7 @@ export default function TabGroupPanel({
   }, [])
 
   const model = useTabGroupWorkspaceModel({ groupId, worktreeId })
-  const { activeTab, browserItems, commands, editorItems, notesItems, tabBarOrder, terminalTabs } =
-    model
+  const { activeTab, browserItems, commands, editorItems, tabBarOrder, terminalTabs } = model
   const { setNodeRef: setBodyDropRef } = useDroppable({
     id: getTabPaneBodyDroppableId(groupId),
     data: {
@@ -126,30 +119,23 @@ export default function TabGroupPanel({
       wslAvailable={wslAvailable}
       onNewBrowserTab={commands.newBrowserTab}
       onNewFileTab={commands.newFileTab}
-      onNewNotesTab={commands.newNotesTab}
       onSetCustomTitle={commands.setTabCustomTitle}
       onSetTabColor={commands.setTabColor}
       onTogglePaneExpand={() => {}}
       editorFiles={editorItems}
       browserTabs={browserItems}
-      notesTabs={notesItems}
       activeFileId={
-        activeTab?.contentType === 'terminal' ||
-        activeTab?.contentType === 'browser' ||
-        activeTab?.contentType === 'notes'
+        activeTab?.contentType === 'terminal' || activeTab?.contentType === 'browser'
           ? null
           : activeTab?.id
       }
       activeBrowserTabId={activeTab?.contentType === 'browser' ? activeTab.entityId : null}
-      activeNotesTabId={activeTab?.contentType === 'notes' ? activeTab.id : null}
       activeTabType={
         activeTab?.contentType === 'terminal'
           ? 'terminal'
           : activeTab?.contentType === 'browser'
             ? 'browser'
-            : activeTab?.contentType === 'notes'
-              ? 'notes'
-              : 'editor'
+            : 'editor'
       }
       onActivateFile={commands.activateEditor}
       onCloseFile={commands.closeItem}
@@ -162,15 +148,6 @@ export default function TabGroupPanel({
           commands.closeItem(item.id)
         }
       }}
-      onActivateNotesTab={commands.activateNotes}
-      onCloseNotesTab={(notesTabId) => {
-        const item = model.groupTabs.find(
-          (candidate) => candidate.id === notesTabId && candidate.contentType === 'notes'
-        )
-        if (item) {
-          commands.closeItem(item.id)
-        }
-      }}
       onDuplicateBrowserTab={commands.duplicateBrowserTab}
       onCloseAllFiles={commands.closeAllEditorTabsInGroup}
       onPinFile={(_fileId, tabId) => {
@@ -361,36 +338,9 @@ export default function TabGroupPanel({
         style={bodyAnchorStyle}
       >
         {activeDropZone ? <TabGroupDropOverlay zone={activeDropZone} /> : null}
-        {model.groupTabs
-          .filter((tab) => tab.contentType === 'notes')
-          .map((notesTab) => (
-            <div
-              key={notesTab.id}
-              className={`absolute inset-0 min-h-0 min-w-0 ${
-                activeTab?.id === notesTab.id ? 'flex' : 'hidden'
-              }`}
-            >
-              <Suspense
-                fallback={
-                  <div className="flex flex-1 items-center justify-center text-sm text-muted-foreground">
-                    Loading notes...
-                  </div>
-                }
-              >
-                <ProjectNotesTabContent
-                  worktreeId={worktreeId}
-                  tabId={notesTab.id}
-                  noteId={getProjectNoteIdFromEntityId(notesTab.entityId)}
-                  forceNew={isNewProjectNoteEntityId(notesTab.entityId)}
-                />
-              </Suspense>
-            </div>
-          ))}
-
         {activeTab &&
           activeTab.contentType !== 'terminal' &&
-          activeTab.contentType !== 'browser' &&
-          activeTab.contentType !== 'notes' && (
+          activeTab.contentType !== 'browser' && (
             <div className="absolute inset-0 flex min-h-0 min-w-0">
               {/* Why: split groups render editor/browser content inside a
                   plain relative pane body instead of the legacy flex column in
diff --git a/src/renderer/src/components/tab-group/useTabDragSplit.ts b/src/renderer/src/components/tab-group/useTabDragSplit.ts
index 838e9deac94..22c7f5d4d99 100644
--- a/src/renderer/src/components/tab-group/useTabDragSplit.ts
+++ b/src/renderer/src/components/tab-group/useTabDragSplit.ts
@@ -34,7 +34,7 @@ export type TabDragItemData = {
   groupId: string
   unifiedTabId: string
   visibleTabId: string
-  tabType: 'terminal' | 'editor' | 'browser' | 'notes'
+  tabType: 'terminal' | 'editor' | 'browser'
   /** Rendered by the DragOverlay ghost that follows the cursor across
    *  groups. Source tab strips use overflow-hidden, so without the overlay
    *  the dragged tab would be invisible once the cursor leaves its own
diff --git a/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts b/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
index 593653ef4a2..6059902b579 100644
--- a/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
+++ b/src/renderer/src/components/tab-group/useTabGroupWorkspaceModel.ts
@@ -14,13 +14,9 @@ import { extractIpcErrorMessage } from '../../lib/ipc-error'
 import { destroyWorkspaceWebviews } from '../../store/slices/browser-webview-cleanup'
 import { requestEditorFileClose } from '../editor/editor-autosave'
 import { focusTerminalTabSurface } from '../../lib/focus-terminal-tab-surface'
-import { getProjectNotesEntityId } from '../../lib/open-project-notes-tab'
-import { requestProjectNotesTabClose } from '../../lib/project-notes-close-request'
-import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
 
 export type GroupEditorItem = OpenFile & { tabId: string }
 export type GroupBrowserItem = BrowserTabState & { tabId: string }
-export type GroupNotesItem = { id: string; label: string; entityId: string; isDirty: boolean }
 
 const EMPTY_GROUPS: readonly TabGroup[] = []
 const EMPTY_UNIFIED_TABS: readonly Tab[] = []
@@ -144,19 +140,6 @@ export function useTabGroupWorkspaceModel({
     [groupTabs, worktreeState.browserTabs]
   )
 
-  const notesItems = useMemo<GroupNotesItem[]>(
-    () =>
-      groupTabs
-        .filter((item) => item.contentType === 'notes')
-        .map((item) => ({
-          id: item.id,
-          label: item.label,
-          entityId: item.entityId,
-          isDirty: item.isDirty === true
-        })),
-    [groupTabs]
-  )
-
   const closeEditorIfUnreferenced = useCallback(
     (entityId: string, closingTabId: string) => {
       const otherReference = (useAppStore.getState().unifiedTabsByWorktree[worktreeId] ?? []).some(
@@ -210,14 +193,6 @@ export function useTabGroupWorkspaceModel({
       } else if (item.contentType === 'browser') {
         destroyWorkspaceWebviews(useAppStore.getState().browserPagesByWorkspace, item.entityId)
         closeBrowserTab(item.entityId)
-      } else if (item.contentType === 'notes') {
-        requestProjectNotesTabClose(item.id, () => {
-          closeUnifiedTab(item.id)
-          if (!opts?.skipEmptyCheck) {
-            leaveWorktreeIfEmpty()
-          }
-        })
-        return
       } else {
         const canCloseTab = closeEditorIfUnreferenced(item.entityId, item.id)
         if (!canCloseTab) {
@@ -251,10 +226,6 @@ export function useTabGroupWorkspaceModel({
         } else if (item.contentType === 'browser') {
           destroyWorkspaceWebviews(useAppStore.getState().browserPagesByWorkspace, item.entityId)
           closeBrowserTab(item.entityId)
-        } else if (item.contentType === 'notes') {
-          requestProjectNotesTabClose(item.id, () => {
-            closeUnifiedTab(item.id)
-          })
         } else {
           const canCloseTab = closeEditorIfUnreferenced(item.entityId, item.id)
           if (canCloseTab) {
@@ -312,21 +283,6 @@ export function useTabGroupWorkspaceModel({
     [activateTab, focusGroup, groupId, groupTabs, setActiveBrowserTab, setActiveTabType, worktreeId]
   )
 
-  const activateNotes = useCallback(
-    (tabId: string) => {
-      const item = groupTabs.find(
-        (candidate) => candidate.id === tabId && candidate.contentType === 'notes'
-      )
-      if (!item) {
-        return
-      }
-      focusGroup(worktreeId, groupId)
-      activateTab(item.id)
-      setActiveTabType('notes')
-    },
-    [activateTab, focusGroup, groupId, groupTabs, setActiveTabType, worktreeId]
-  )
-
   const createSplitGroup = useCallback(
     (direction: 'left' | 'right' | 'up' | 'down', sourceVisibleTabId?: string) => {
       const sourceTab =
@@ -465,7 +421,6 @@ export function useTabGroupWorkspaceModel({
     activeTab,
     browserItems,
     editorItems,
-    notesItems,
     terminalTabs,
     tabBarOrder,
     groupTabs,
@@ -476,7 +431,6 @@ export function useTabGroupWorkspaceModel({
       },
       activateBrowser,
       activateEditor,
-      activateNotes,
       activateTerminal,
       closeAllEditorTabsInGroup,
       closeGroup,
@@ -527,40 +481,6 @@ export function useTabGroupWorkspaceModel({
           toast.error(extractIpcErrorMessage(err, 'Failed to create untitled markdown file.'))
         }
       },
-      newNotesTab: async (noteId?: string) => {
-        const projectId = worktree?.repoId ?? worktreeId
-        let label = 'Project Notes'
-        if (noteId) {
-          try {
-            const settings = useAppStore.getState().settings
-            const result = await showRuntimeProjectNote(settings, {
-              projectId,
-              worktreeId,
-              note: noteId
-            })
-            label = result.note.title
-            await linkRuntimeProjectNote(settings, {
-              projectId,
-              worktreeId,
-              note: noteId,
-              kind: 'active'
-            })
-          } catch {
-            label = 'Project Notes'
-          }
-        }
-        const tab = useAppStore.getState().createUnifiedTab(worktreeId, 'notes', {
-          targetGroupId: groupId,
-          label,
-          // Why: each Project Notes tab is an editor surface, not the note
-          // identity itself. Give it a unique entity id so users can keep
-          // more than one notes tab open in the same pane.
-          entityId: getProjectNotesEntityId(projectId, noteId)
-        })
-        focusGroup(worktreeId, groupId)
-        activateTab(tab.id)
-        setActiveTabType('notes')
-      },
       newTerminalTab: () => {
         const terminal = createTab(worktreeId, groupId)
         setActiveTab(terminal.id)
diff --git a/src/renderer/src/components/terminal/tab-type-cycle.ts b/src/renderer/src/components/terminal/tab-type-cycle.ts
index 1fcd48d62f7..af86198f317 100644
--- a/src/renderer/src/components/terminal/tab-type-cycle.ts
+++ b/src/renderer/src/components/terminal/tab-type-cycle.ts
@@ -1,4 +1,4 @@
-export type TabCycleType = 'terminal' | 'editor' | 'browser' | 'notes'
+export type TabCycleType = 'terminal' | 'editor' | 'browser'
 
 export type TypeCyclableTab = {
   type: TabCycleType
diff --git a/src/renderer/src/components/ui/dropdown-menu.tsx b/src/renderer/src/components/ui/dropdown-menu.tsx
index cd3dad0ba98..0861a7d57f7 100644
--- a/src/renderer/src/components/ui/dropdown-menu.tsx
+++ b/src/renderer/src/components/ui/dropdown-menu.tsx
@@ -32,7 +32,7 @@ function DropdownMenuContent({
         data-slot="dropdown-menu-content"
         sideOffset={sideOffset}
         className={cn(
-          'relative z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[11rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-[11px] border border-black/14 bg-[rgba(255,255,255,0.82)] p-1 text-black dark:text-white shadow-[0_16px_36px_rgba(0,0,0,0.24),inset_0_1px_0_rgba(255,255,255,0.14)] backdrop-blur-2xl dark:border-white/14 dark:bg-[rgba(0,0,0,0.72)] dark:shadow-[0_20px_44px_rgba(0,0,0,0.42),inset_0_1px_0_rgba(255,255,255,0.04)] data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+          'z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[11rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-[11px] border border-black/14 bg-[rgba(255,255,255,0.82)] p-1 text-black dark:text-white shadow-[0_16px_36px_rgba(0,0,0,0.24),inset_0_1px_0_rgba(255,255,255,0.14)] backdrop-blur-2xl dark:border-white/14 dark:bg-[rgba(0,0,0,0.72)] dark:shadow-[0_20px_44px_rgba(0,0,0,0.42),inset_0_1px_0_rgba(255,255,255,0.04)] data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
           className
         )}
         // Why: Electron's -webkit-app-region: drag on the titlebar captures
@@ -209,11 +209,11 @@ function DropdownMenuSubContent({
       <DropdownMenuPrimitive.SubContent
         data-slot="dropdown-menu-sub-content"
         className={cn(
-          'relative z-50 min-w-[11rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-[11px] border border-black/14 bg-[rgba(255,255,255,0.82)] p-1 text-black dark:text-white shadow-[0_16px_36px_rgba(0,0,0,0.24),inset_0_1px_0_rgba(255,255,255,0.14)] backdrop-blur-2xl dark:border-white/14 dark:bg-[rgba(0,0,0,0.72)] dark:shadow-[0_20px_44px_rgba(0,0,0,0.42),inset_0_1px_0_rgba(255,255,255,0.04)] data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+          'z-50 min-w-[11rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-[11px] border border-black/14 bg-[rgba(255,255,255,0.82)] p-1 text-black dark:text-white shadow-[0_16px_36px_rgba(0,0,0,0.24),inset_0_1px_0_rgba(255,255,255,0.14)] backdrop-blur-2xl dark:border-white/14 dark:bg-[rgba(0,0,0,0.72)] dark:shadow-[0_20px_44px_rgba(0,0,0,0.42),inset_0_1px_0_rgba(255,255,255,0.04)] data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
           className
         )}
-        // Why: submenus must escape the parent menu's scroll clipping; the
-        // portal also needs no-drag for titlebar-overlapping menus in Electron.
+        // Why: same no-drag fix as DropdownMenuContent — titlebar drag region
+        // would otherwise capture clicks when submenu overlaps it.
         style={{ ...style, WebkitAppRegion: 'no-drag' } as React.CSSProperties}
         {...props}
       />
diff --git a/src/renderer/src/hooks/ipc-tab-switch.ts b/src/renderer/src/hooks/ipc-tab-switch.ts
index 88fac6dd73e..632d65e532d 100644
--- a/src/renderer/src/hooks/ipc-tab-switch.ts
+++ b/src/renderer/src/hooks/ipc-tab-switch.ts
@@ -67,9 +67,6 @@ function applyNextTab(store: AppStoreState, next: TypeCyclableTab): void {
       store.activateTab?.(next.tabId)
     }
     store.setActiveTabType('browser')
-  } else if (next.type === 'notes') {
-    store.activateTab?.(next.tabId ?? next.id)
-    store.setActiveTabType('notes')
   } else {
     // Why: `setActiveFile` targets the file entity (its implicit activateTab
     // picks the first matching tab in the active group); `activateTab(tabId)`
diff --git a/src/renderer/src/hooks/resolve-zoom-target.ts b/src/renderer/src/hooks/resolve-zoom-target.ts
index f03b3786cd0..bc70e777afa 100644
--- a/src/renderer/src/hooks/resolve-zoom-target.ts
+++ b/src/renderer/src/hooks/resolve-zoom-target.ts
@@ -4,7 +4,7 @@
  */
 export function resolveZoomTarget(args: {
   activeView: 'terminal' | 'settings' | 'tasks' | 'activity' | 'automations' | 'space'
-  activeTabType: 'terminal' | 'editor' | 'browser' | 'notes'
+  activeTabType: 'terminal' | 'editor' | 'browser'
   activeElement: unknown
 }): 'terminal' | 'editor' | 'ui' {
   const { activeView, activeTabType, activeElement } = args
@@ -35,7 +35,7 @@ export function resolveZoomTarget(args: {
   if (activeView !== 'terminal') {
     return 'ui'
   }
-  if (activeTabType === 'editor' || activeTabType === 'notes' || editorFocused) {
+  if (activeTabType === 'editor' || editorFocused) {
     return 'editor'
   }
   // Why: terminal tabs should keep using per-pane terminal font zoom even when
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index 238c2b8cb3a..863a69abb25 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -34,7 +34,6 @@ import { destroyPersistentWebview } from '@/components/browser-pane/webview-regi
 import { attachMobileMarkdownBridge } from '@/runtime/mobile-markdown-bridge'
 import { detectLanguage } from '@/lib/language-detect'
 import { track } from '@/lib/telemetry'
-import { requestProjectNotesTabClose } from '@/lib/project-notes-close-request'
 
 export { resolveZoomTarget } from './resolve-zoom-target'
 
@@ -864,15 +863,6 @@ export function useIpcEvents(): void {
         const store = useAppStore.getState()
         if (store.activeTabType === 'browser' && store.activeBrowserTabId) {
           store.closeBrowserTab(store.activeBrowserTabId)
-          return
-        }
-        if (store.activeTabType === 'notes' && store.activeWorktreeId) {
-          const activeTab = store.getActiveTab(store.activeWorktreeId)
-          if (activeTab?.contentType === 'notes') {
-            requestProjectNotesTabClose(activeTab.id, () => {
-              store.closeUnifiedTab(activeTab.id)
-            })
-          }
         }
       })
     )
diff --git a/src/renderer/src/lib/notes-events.ts b/src/renderer/src/lib/notes-events.ts
deleted file mode 100644
index ede0a9b9647..00000000000
--- a/src/renderer/src/lib/notes-events.ts
+++ /dev/null
@@ -1 +0,0 @@
-export const NOTES_ACTIVE_CHANGED_EVENT = 'orca:notes-active-changed'
diff --git a/src/renderer/src/lib/open-project-notes-tab.ts b/src/renderer/src/lib/open-project-notes-tab.ts
deleted file mode 100644
index 24c9fa6ca92..00000000000
--- a/src/renderer/src/lib/open-project-notes-tab.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { useAppStore } from '@/store'
-import { NOTES_ACTIVE_CHANGED_EVENT } from '@/lib/notes-events'
-import { linkRuntimeProjectNote, showRuntimeProjectNote } from '@/runtime/runtime-notes-client'
-import { createBrowserUuid } from '@/lib/browser-uuid'
-
-export function getProjectNotesEntityId(projectId: string, noteId?: string): string {
-  if (noteId) {
-    return `notes:${projectId}:note:${noteId}`
-  }
-  return `notes:${projectId}:new:${createBrowserUuid()}`
-}
-
-export function getProjectNoteIdFromEntityId(entityId: string): string | null {
-  const [, , kind, noteId] = entityId.split(':')
-  return kind === 'note' && noteId ? noteId : null
-}
-
-export function isNewProjectNoteEntityId(entityId: string): boolean {
-  const [, , kind] = entityId.split(':')
-  return kind === 'new'
-}
-
-export async function openProjectNotesTab(worktreeId: string, noteId?: string): Promise<void> {
-  const state = useAppStore.getState()
-  const targetGroupId =
-    state.activeGroupIdByWorktree[worktreeId] ?? (state.groupsByWorktree[worktreeId] ?? [])[0]?.id
-  const worktree = Object.values(state.worktreesByRepo)
-    .flat()
-    .find((candidate) => candidate.id === worktreeId)
-  const repo = state.repos.find((candidate) => candidate.id === worktree?.repoId)
-  const projectId = repo?.id ?? worktree?.repoId ?? null
-  const settings = state.settings
-
-  if (noteId && projectId) {
-    await linkRuntimeProjectNote(settings, { projectId, worktreeId, note: noteId, kind: 'active' })
-  }
-
-  let label = 'Project Notes'
-  if (noteId && projectId) {
-    try {
-      const result = await showRuntimeProjectNote(settings, { projectId, worktreeId, note: noteId })
-      label = result.note.title
-    } catch {
-      label = 'Project Notes'
-    }
-  }
-
-  state.setActiveView('terminal')
-
-  const tab = state.createUnifiedTab(worktreeId, 'notes', {
-    targetGroupId,
-    label,
-    entityId: getProjectNotesEntityId(projectId ?? worktree?.repoId ?? worktreeId, noteId)
-  })
-  state.focusGroup(worktreeId, tab.groupId)
-  state.activateTab(tab.id)
-  state.setActiveTabType('notes')
-  if (noteId) {
-    notifyProjectNotesSelectionChanged()
-  }
-}
-
-export function notifyProjectNotesSelectionChanged(): void {
-  window.dispatchEvent(new CustomEvent(NOTES_ACTIVE_CHANGED_EVENT))
-}
diff --git a/src/renderer/src/lib/project-notes-close-request.test.ts b/src/renderer/src/lib/project-notes-close-request.test.ts
deleted file mode 100644
index afdafb769fe..00000000000
--- a/src/renderer/src/lib/project-notes-close-request.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import {
-  ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT,
-  requestProjectNotesTabClose,
-  type ProjectNotesCloseRequestDetail
-} from './project-notes-close-request'
-
-type WindowEventStub = Pick<Window, 'addEventListener' | 'removeEventListener' | 'dispatchEvent'>
-
-beforeEach(() => {
-  const eventTarget = new EventTarget()
-  vi.stubGlobal('window', {
-    addEventListener: eventTarget.addEventListener.bind(eventTarget),
-    removeEventListener: eventTarget.removeEventListener.bind(eventTarget),
-    dispatchEvent: eventTarget.dispatchEvent.bind(eventTarget)
-  } satisfies WindowEventStub)
-})
-
-afterEach(() => {
-  vi.unstubAllGlobals()
-})
-
-describe('requestProjectNotesTabClose', () => {
-  it('dispatches a close request and lets a mounted notes tab claim it', () => {
-    const close = vi.fn()
-    const listener = vi.fn((event: Event) => {
-      const detail = (event as CustomEvent<ProjectNotesCloseRequestDetail>).detail
-      detail.claim()
-      expect(detail.tabId).toBe('tab-1')
-      expect(detail.close).toBe(close)
-    })
-    window.addEventListener(ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT, listener)
-    try {
-      requestProjectNotesTabClose('tab-1', close)
-      expect(listener).toHaveBeenCalledTimes(1)
-      expect(close).not.toHaveBeenCalled()
-    } finally {
-      window.removeEventListener(ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT, listener)
-    }
-  })
-
-  it('closes immediately when no notes tab claims the request', () => {
-    const close = vi.fn()
-    requestProjectNotesTabClose('tab-1', close)
-    expect(close).toHaveBeenCalledTimes(1)
-  })
-})
diff --git a/src/renderer/src/lib/project-notes-close-request.ts b/src/renderer/src/lib/project-notes-close-request.ts
deleted file mode 100644
index 3984d665d65..00000000000
--- a/src/renderer/src/lib/project-notes-close-request.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-export const ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT = 'orca:project-notes-request-close'
-
-export type ProjectNotesCloseRequestDetail = {
-  tabId: string
-  close: () => void
-  claim: () => void
-}
-
-export function requestProjectNotesTabClose(tabId: string, close: () => void): void {
-  let claimed = false
-  window.dispatchEvent(
-    new CustomEvent<ProjectNotesCloseRequestDetail>(ORCA_PROJECT_NOTES_REQUEST_CLOSE_EVENT, {
-      detail: {
-        tabId,
-        close,
-        claim: () => {
-          claimed = true
-        }
-      }
-    })
-  )
-  // Why: Project Notes tabs are normally mounted so dirty state can prompt on
-  // close, but close requests should still complete if a tab shell exists
-  // before its lazy content has attached a listener.
-  if (!claimed) {
-    close()
-  }
-}
diff --git a/src/renderer/src/lib/worktree-status.test.ts b/src/renderer/src/lib/worktree-status.test.ts
index 8b16fa295ea..681bc1e74cd 100644
--- a/src/renderer/src/lib/worktree-status.test.ts
+++ b/src/renderer/src/lib/worktree-status.test.ts
@@ -188,28 +188,4 @@ describe('resolveWorktreeStatus', () => {
 
     expect(status).toBe('active')
   })
-
-  it('treats a notes-only worktree as active without promoting unrelated worktrees', () => {
-    const notesWorktreeStatus = resolveWorktreeStatus({
-      tabs: [],
-      browserTabs: [],
-      ptyIdsByTabId: {},
-      hasNotesSurface: true,
-      hasPermission: false,
-      hasLiveDone: false,
-      hasRetainedDone: false
-    })
-    const unrelatedWorktreeStatus = resolveWorktreeStatus({
-      tabs: [],
-      browserTabs: [],
-      ptyIdsByTabId: {},
-      hasNotesSurface: false,
-      hasPermission: false,
-      hasLiveDone: false,
-      hasRetainedDone: false
-    })
-
-    expect(notesWorktreeStatus).toBe('active')
-    expect(unrelatedWorktreeStatus).toBe('inactive')
-  })
 })
diff --git a/src/renderer/src/lib/worktree-status.ts b/src/renderer/src/lib/worktree-status.ts
index afec4bd728f..1f2380d6807 100644
--- a/src/renderer/src/lib/worktree-status.ts
+++ b/src/renderer/src/lib/worktree-status.ts
@@ -98,7 +98,6 @@ export function resolveWorktreeStatus(args: {
   browserTabs: { id: string }[]
   ptyIdsByTabId: Record<string, string[]>
   runtimePaneTitlesByTabId?: Record<string, Record<number, string>>
-  hasNotesSurface?: boolean
   hasPermission: boolean
   hasLiveDone: boolean
   hasRetainedDone: boolean
@@ -126,8 +125,5 @@ export function resolveWorktreeStatus(args: {
   if (args.hasLiveDone || args.hasRetainedDone) {
     return 'done'
   }
-  if (heuristic === 'inactive' && args.hasNotesSurface) {
-    return 'active'
-  }
   return heuristic
 }
diff --git a/src/renderer/src/runtime/runtime-notes-client.test.ts b/src/renderer/src/runtime/runtime-notes-client.test.ts
deleted file mode 100644
index ee15a592106..00000000000
--- a/src/renderer/src/runtime/runtime-notes-client.test.ts
+++ /dev/null
@@ -1,228 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import {
-  createRuntimeProjectNote,
-  deleteRuntimeProjectNote,
-  linkRuntimeProjectNote,
-  listRuntimeProjectNotes,
-  renameRuntimeProjectNote,
-  resolveRuntimeNotesPanelState,
-  saveRuntimeProjectNote,
-  showRuntimeProjectNote
-} from './runtime-notes-client'
-import {
-  createCompatibleRuntimeStatusResponseIfNeeded,
-  type RuntimeEnvironmentCallRequest
-} from './runtime-compatibility-test-fixture'
-import { clearRuntimeCompatibilityCacheForTests } from './runtime-rpc-client'
-
-const notesList = vi.fn()
-const notesShow = vi.fn()
-const notesCreate = vi.fn()
-const notesSave = vi.fn()
-const notesRename = vi.fn()
-const notesDelete = vi.fn()
-const notesAppend = vi.fn()
-const notesSearch = vi.fn()
-const notesLink = vi.fn()
-const notesPanelState = vi.fn()
-const runtimeCall = vi.fn()
-const runtimeEnvironmentCall = vi.fn()
-const runtimeEnvironmentTransportCall = vi.fn()
-
-beforeEach(() => {
-  clearRuntimeCompatibilityCacheForTests()
-  notesList.mockReset()
-  notesShow.mockReset()
-  notesCreate.mockReset()
-  notesSave.mockReset()
-  notesRename.mockReset()
-  notesDelete.mockReset()
-  notesAppend.mockReset()
-  notesSearch.mockReset()
-  notesLink.mockReset()
-  notesPanelState.mockReset()
-  runtimeCall.mockReset()
-  runtimeEnvironmentCall.mockReset()
-  runtimeEnvironmentTransportCall.mockReset()
-  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
-    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
-  })
-  vi.stubGlobal('window', {
-    api: {
-      notes: {
-        list: notesList,
-        show: notesShow,
-        create: notesCreate,
-        save: notesSave,
-        rename: notesRename,
-        delete: notesDelete,
-        append: notesAppend,
-        search: notesSearch,
-        link: notesLink,
-        panelState: notesPanelState
-      },
-      runtime: { call: runtimeCall },
-      runtimeEnvironments: { call: runtimeEnvironmentTransportCall }
-    }
-  })
-})
-
-describe('runtime notes client', () => {
-  it('uses local notes IPC when no remote runtime is active', async () => {
-    notesList.mockResolvedValue({ notes: [], totalCount: 0, truncated: false })
-
-    await listRuntimeProjectNotes(
-      { activeRuntimeEnvironmentId: null },
-      { projectId: 'repo-1', worktreeId: 'wt-1', limit: 100 }
-    )
-
-    expect(notesList).toHaveBeenCalledWith({
-      projectId: 'repo-1',
-      worktreeId: 'wt-1',
-      limit: 100
-    })
-    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
-  })
-
-  it('routes note reads through the active runtime environment', async () => {
-    runtimeEnvironmentCall.mockResolvedValue({
-      id: 'rpc-1',
-      ok: true,
-      result: { notes: [], totalCount: 0, truncated: false },
-      _meta: { runtimeId: 'remote-runtime' }
-    })
-    const settings = { activeRuntimeEnvironmentId: 'env-1' }
-
-    await listRuntimeProjectNotes(settings, {
-      projectId: 'repo-1',
-      worktreeId: 'wt-1',
-      limit: 100
-    })
-    runtimeEnvironmentCall.mockResolvedValueOnce({
-      id: 'rpc-2',
-      ok: true,
-      result: { note: { id: 'note-1' }, linkKind: null },
-      _meta: { runtimeId: 'remote-runtime' }
-    })
-    await showRuntimeProjectNote(settings, {
-      projectId: 'repo-1',
-      worktreeId: 'wt-1',
-      note: 'note-1'
-    })
-
-    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
-      selector: 'env-1',
-      method: 'note.list',
-      params: { worktree: 'wt-1', limit: 100 },
-      timeoutMs: 15_000
-    })
-    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
-      selector: 'env-1',
-      method: 'note.show',
-      params: { worktree: 'wt-1', note: 'note-1' },
-      timeoutMs: 15_000
-    })
-  })
-
-  it('routes note mutations through the active runtime environment', async () => {
-    runtimeEnvironmentCall.mockResolvedValue({
-      id: 'rpc-1',
-      ok: true,
-      result: { note: { id: 'note-1' }, linkKind: 'active' },
-      _meta: { runtimeId: 'remote-runtime' }
-    })
-    const settings = { activeRuntimeEnvironmentId: 'env-1' }
-    const base = { projectId: 'repo-1', worktreeId: 'wt-1' }
-
-    await createRuntimeProjectNote(settings, { ...base, title: 'Plan', bodyMarkdown: 'body' })
-    await saveRuntimeProjectNote(settings, {
-      ...base,
-      note: 'note-1',
-      title: 'Plan',
-      bodyMarkdown: 'updated',
-      revision: 3,
-      makeActive: true
-    })
-    await renameRuntimeProjectNote(settings, { ...base, note: 'note-1', title: 'Renamed' })
-    await deleteRuntimeProjectNote(settings, { ...base, note: 'note-1' })
-    await linkRuntimeProjectNote(settings, { ...base, note: 'note-1', kind: 'active' })
-
-    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(1, {
-      selector: 'env-1',
-      method: 'note.create',
-      params: {
-        worktree: 'wt-1',
-        title: 'Plan',
-        bodyMarkdown: 'body',
-        makeActive: undefined,
-        createdBySessionId: undefined
-      },
-      timeoutMs: 15_000
-    })
-    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(2, {
-      selector: 'env-1',
-      method: 'note.save',
-      params: {
-        worktree: 'wt-1',
-        note: 'note-1',
-        title: 'Plan',
-        bodyMarkdown: 'updated',
-        revision: 3,
-        makeActive: true,
-        updatedBySessionId: undefined
-      },
-      timeoutMs: 15_000
-    })
-    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(3, {
-      selector: 'env-1',
-      method: 'note.rename',
-      params: {
-        worktree: 'wt-1',
-        note: 'note-1',
-        title: 'Renamed',
-        updatedBySessionId: undefined
-      },
-      timeoutMs: 15_000
-    })
-    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(4, {
-      selector: 'env-1',
-      method: 'note.delete',
-      params: { worktree: 'wt-1', note: 'note-1' },
-      timeoutMs: 15_000
-    })
-    expect(runtimeEnvironmentCall).toHaveBeenNthCalledWith(5, {
-      selector: 'env-1',
-      method: 'note.link',
-      params: { worktree: 'wt-1', note: 'note-1', kind: 'active' },
-      timeoutMs: 15_000
-    })
-  })
-
-  it('routes panel state through the active runtime environment', async () => {
-    runtimeEnvironmentCall.mockResolvedValue({
-      id: 'rpc-1',
-      ok: true,
-      result: { state: 'emptyDraft', projectId: 'repo-1', worktreeId: 'wt-1' },
-      _meta: { runtimeId: 'remote-runtime' }
-    })
-
-    await resolveRuntimeNotesPanelState(
-      { activeRuntimeEnvironmentId: 'env-1' },
-      { projectId: 'repo-1', worktreeId: 'wt-1' }
-    )
-
-    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
-      selector: 'env-1',
-      method: 'note.panelState',
-      params: { worktree: 'wt-1' },
-      timeoutMs: 15_000
-    })
-  })
-
-  it('returns noProject for remote panel state without a project/worktree', async () => {
-    await expect(
-      resolveRuntimeNotesPanelState({ activeRuntimeEnvironmentId: 'env-1' }, {})
-    ).resolves.toEqual({ state: 'noProject' })
-    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
-  })
-})
diff --git a/src/renderer/src/runtime/runtime-notes-client.ts b/src/renderer/src/runtime/runtime-notes-client.ts
deleted file mode 100644
index 669d9d8681c..00000000000
--- a/src/renderer/src/runtime/runtime-notes-client.ts
+++ /dev/null
@@ -1,229 +0,0 @@
-import type { GlobalSettings } from '../../../shared/types'
-import type {
-  NoteAppendArgs,
-  NoteCreateArgs,
-  NoteDeleteArgs,
-  NoteDeleteResult,
-  NoteLink,
-  NoteLinkArgs,
-  NoteListArgs,
-  NoteListResult,
-  NoteMutationResult,
-  NoteRenameArgs,
-  NoteSaveArgs,
-  NoteSearchArgs,
-  NoteShowArgs,
-  NoteShowResult,
-  NotesPanelOpenState,
-  NotesPanelStateArgs
-} from '../../../shared/notes-types'
-import { callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
-
-type RuntimeNotesSettings = Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
-
-function requireWorktreeId(worktreeId: string | null | undefined): string {
-  if (!worktreeId?.trim()) {
-    throw new Error('Project notes require an active worktree on remote runtime servers.')
-  }
-  return worktreeId
-}
-
-function noteTarget(settings: RuntimeNotesSettings): ReturnType<typeof getActiveRuntimeTarget> {
-  return getActiveRuntimeTarget(settings)
-}
-
-export async function listRuntimeProjectNotes(
-  settings: RuntimeNotesSettings,
-  args: NoteListArgs
-): Promise<NoteListResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.list(args)
-  }
-  return callRuntimeRpc<NoteListResult>(
-    target,
-    'note.list',
-    { worktree: requireWorktreeId(args.worktreeId), limit: args.limit },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function showRuntimeProjectNote(
-  settings: RuntimeNotesSettings,
-  args: NoteShowArgs
-): Promise<NoteShowResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.show(args)
-  }
-  return callRuntimeRpc<NoteShowResult>(
-    target,
-    'note.show',
-    { worktree: requireWorktreeId(args.worktreeId), note: args.note },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function createRuntimeProjectNote(
-  settings: RuntimeNotesSettings,
-  args: NoteCreateArgs
-): Promise<NoteMutationResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.create(args)
-  }
-  return callRuntimeRpc<NoteMutationResult>(
-    target,
-    'note.create',
-    {
-      worktree: requireWorktreeId(args.worktreeId),
-      title: args.title,
-      bodyMarkdown: args.bodyMarkdown,
-      makeActive: args.makeActive,
-      createdBySessionId: args.createdBySessionId
-    },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function saveRuntimeProjectNote(
-  settings: RuntimeNotesSettings,
-  args: NoteSaveArgs
-): Promise<NoteMutationResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.save(args)
-  }
-  return callRuntimeRpc<NoteMutationResult>(
-    target,
-    'note.save',
-    {
-      worktree: requireWorktreeId(args.worktreeId),
-      note: args.note,
-      title: args.title,
-      bodyMarkdown: args.bodyMarkdown,
-      revision: args.revision,
-      makeActive: args.makeActive,
-      updatedBySessionId: args.updatedBySessionId
-    },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function renameRuntimeProjectNote(
-  settings: RuntimeNotesSettings,
-  args: NoteRenameArgs
-): Promise<NoteMutationResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.rename(args)
-  }
-  return callRuntimeRpc<NoteMutationResult>(
-    target,
-    'note.rename',
-    {
-      worktree: requireWorktreeId(args.worktreeId),
-      note: args.note,
-      title: args.title,
-      updatedBySessionId: args.updatedBySessionId
-    },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function deleteRuntimeProjectNote(
-  settings: RuntimeNotesSettings,
-  args: NoteDeleteArgs
-): Promise<NoteDeleteResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.delete(args)
-  }
-  return callRuntimeRpc<NoteDeleteResult>(
-    target,
-    'note.delete',
-    { worktree: requireWorktreeId(args.worktreeId), note: args.note },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function appendRuntimeProjectNote(
-  settings: RuntimeNotesSettings,
-  args: NoteAppendArgs
-): Promise<NoteMutationResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.append(args)
-  }
-  return callRuntimeRpc<NoteMutationResult>(
-    target,
-    'note.append',
-    {
-      worktree: requireWorktreeId(args.worktreeId),
-      note: args.note,
-      bodyMarkdown: args.bodyMarkdown,
-      makeActive: args.makeActive,
-      updatedBySessionId: args.updatedBySessionId
-    },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function searchRuntimeProjectNotes(
-  settings: RuntimeNotesSettings,
-  args: NoteSearchArgs
-): Promise<NoteListResult> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.search(args)
-  }
-  return callRuntimeRpc<NoteListResult>(
-    target,
-    'note.search',
-    {
-      worktree: requireWorktreeId(args.worktreeId),
-      query: args.query,
-      limit: args.limit
-    },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function linkRuntimeProjectNote(
-  settings: RuntimeNotesSettings,
-  args: NoteLinkArgs
-): Promise<NoteLink> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.link(args)
-  }
-  return callRuntimeRpc<NoteLink>(
-    target,
-    'note.link',
-    {
-      worktree: requireWorktreeId(args.worktreeId),
-      note: args.note,
-      kind: args.kind
-    },
-    { timeoutMs: 15_000 }
-  )
-}
-
-export async function resolveRuntimeNotesPanelState(
-  settings: RuntimeNotesSettings,
-  args: NotesPanelStateArgs
-): Promise<NotesPanelOpenState> {
-  const target = noteTarget(settings)
-  if (target.kind === 'local') {
-    return window.api.notes.panelState(args)
-  }
-  if (!args.projectId && !args.worktreeId) {
-    return { state: 'noProject' }
-  }
-  return callRuntimeRpc<NotesPanelOpenState>(
-    target,
-    'note.panelState',
-    { worktree: requireWorktreeId(args.worktreeId) },
-    { timeoutMs: 15_000 }
-  )
-}
diff --git a/src/renderer/src/store/slices/editor.ts b/src/renderer/src/store/slices/editor.ts
index 4faba8b6fbc..74fe667f474 100644
--- a/src/renderer/src/store/slices/editor.ts
+++ b/src/renderer/src/store/slices/editor.ts
@@ -140,13 +140,7 @@ export type OpenFile = {
   mode: 'edit' | 'diff' | 'conflict-review' | 'markdown-preview'
 }
 
-export type RightSidebarTab =
-  | 'explorer'
-  | 'search'
-  | 'source-control'
-  | 'checks'
-  | 'ports'
-  | 'notes'
+export type RightSidebarTab = 'explorer' | 'search' | 'source-control' | 'checks' | 'ports'
 export type ActivityBarPosition = 'top' | 'side'
 
 export type MarkdownViewMode = 'source' | 'rich' | 'preview'
diff --git a/src/renderer/src/store/slices/tabs-hydration.ts b/src/renderer/src/store/slices/tabs-hydration.ts
index e01b50a3282..bca09f034ab 100644
--- a/src/renderer/src/store/slices/tabs-hydration.ts
+++ b/src/renderer/src/store/slices/tabs-hydration.ts
@@ -62,8 +62,7 @@ function hydrateUnifiedFormat(
     tabsByWorktree[worktreeId] = [...tabs]
       .map((tab) => ({
         ...tab,
-        entityId: tab.entityId ?? tab.id,
-        isDirty: false
+        entityId: tab.entityId ?? tab.id
       }))
       .filter((tab) => {
         if (!isTransientEditorContentType(tab.contentType)) {
diff --git a/src/renderer/src/store/slices/tabs.test.ts b/src/renderer/src/store/slices/tabs.test.ts
index 3394284cf3e..32e245f1d2e 100644
--- a/src/renderer/src/store/slices/tabs.test.ts
+++ b/src/renderer/src/store/slices/tabs.test.ts
@@ -968,14 +968,6 @@ describe('TabsSlice', () => {
       store.getState().setUnifiedTabColor(tab.id, '#ff0000')
       expect(store.getState().unifiedTabsByWorktree[WT][0].color).toBe('#ff0000')
     })
-
-    it('setTabDirty updates dirty state', () => {
-      const tab = store.getState().createUnifiedTab(WT, 'notes')
-      store.getState().setTabDirty(tab.id, true)
-      expect(store.getState().unifiedTabsByWorktree[WT][0].isDirty).toBe(true)
-      store.getState().setTabDirty(tab.id, false)
-      expect(store.getState().unifiedTabsByWorktree[WT][0].isDirty).toBe(false)
-    })
   })
 
   // ─── pinTab / unpinTab ────────────────────────────────────────────
@@ -1511,47 +1503,5 @@ describe('TabsSlice', () => {
         groupId: restoredGroup?.id
       })
     })
-
-    it('keeps project notes tabs even though they are not openFiles-backed editors', () => {
-      const groupId = 'g-1'
-      store.setState({
-        unifiedTabsByWorktree: {
-          [WT]: [
-            {
-              id: 'notes-tab-1',
-              entityId: 'notes:repo-1:note-1',
-              groupId,
-              worktreeId: WT,
-              contentType: 'notes',
-              label: 'Project Notes',
-              customLabel: null,
-              color: null,
-              sortOrder: 0,
-              createdAt: 1
-            }
-          ]
-        },
-        groupsByWorktree: {
-          [WT]: [
-            {
-              id: groupId,
-              worktreeId: WT,
-              activeTabId: 'notes-tab-1',
-              tabOrder: ['notes-tab-1']
-            }
-          ]
-        },
-        activeGroupIdByWorktree: { [WT]: groupId },
-        tabsByWorktree: { [WT]: [] },
-        openFiles: []
-      })
-
-      const result = store.getState().reconcileWorktreeTabModel(WT)
-
-      expect(result.renderableTabCount).toBe(1)
-      expect(result.activeRenderableTabId).toBe('notes-tab-1')
-      expect(store.getState().unifiedTabsByWorktree[WT]).toHaveLength(1)
-      expect(store.getState().groupsByWorktree[WT][0].activeTabId).toBe('notes-tab-1')
-    })
   })
 })
diff --git a/src/renderer/src/store/slices/tabs.ts b/src/renderer/src/store/slices/tabs.ts
index 42859580399..ca2a70eb32e 100644
--- a/src/renderer/src/store/slices/tabs.ts
+++ b/src/renderer/src/store/slices/tabs.ts
@@ -61,9 +61,7 @@ export type TabsSlice = {
     tabId: string
   ) => { closedTabId: string; wasLastTab: boolean; worktreeId: string } | null
   reorderUnifiedTabs: (groupId: string, tabIds: string[]) => void
-  setTabEntityId: (tabId: string, entityId: string) => void
   setTabLabel: (tabId: string, label: string) => void
-  setTabDirty: (tabId: string, isDirty: boolean) => void
   setTabCustomLabel: (tabId: string, label: string | null) => void
   setUnifiedTabColor: (tabId: string, color: string | null) => void
   pinTab: (tabId: string) => void
@@ -230,13 +228,7 @@ function collapseGroupLayout(
 }
 
 function toVisibleTabType(contentType: TabContentType): WorkspaceVisibleTabType {
-  return contentType === 'browser'
-    ? 'browser'
-    : contentType === 'terminal'
-      ? 'terminal'
-      : contentType === 'notes'
-        ? 'notes'
-        : 'editor'
+  return contentType === 'browser' ? 'browser' : contentType === 'terminal' ? 'terminal' : 'editor'
 }
 
 function deriveActiveSurfaceForWorktree(
@@ -439,8 +431,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
         sortOrder: nextOrder.length,
         createdAt: Date.now(),
         isPreview: init?.isPreview,
-        isPinned: init?.isPinned,
-        isDirty: false
+        isPinned: init?.isPinned
       }
 
       nextOrder = dedupeTabOrder([...nextOrder, created.id])
@@ -738,12 +729,6 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
   setTabLabel: (tabId, label) =>
     set((state) => patchTab(state.unifiedTabsByWorktree, tabId, { label }) ?? {}),
 
-  setTabEntityId: (tabId, entityId) =>
-    set((state) => patchTab(state.unifiedTabsByWorktree, tabId, { entityId }) ?? {}),
-
-  setTabDirty: (tabId, isDirty) =>
-    set((state) => patchTab(state.unifiedTabsByWorktree, tabId, { isDirty }) ?? {}),
-
   setTabCustomLabel: (tabId, label) =>
     set((state) => patchTab(state.unifiedTabsByWorktree, tabId, { customLabel: label }) ?? {}),
 
@@ -1375,12 +1360,6 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
       if (tab.contentType === 'browser') {
         return liveBrowserIds.has(tab.entityId)
       }
-      if (tab.contentType === 'notes') {
-        // Why: project notes are backed by the project notes store, not by
-        // openFiles. Treating them as editor-backed files makes reconcile
-        // prune valid notes tabs and can leave the workspace looking empty.
-        return true
-      }
       return liveEditorIds.has(tab.entityId)
     }
 
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 2493e78f45e..201f8570099 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -61,13 +61,7 @@ function areWorktreesEqual(current: Worktree[] | undefined, next: Worktree[]): b
 }
 
 function toVisibleTabType(contentType: string): WorkspaceVisibleTabType {
-  return contentType === 'browser'
-    ? 'browser'
-    : contentType === 'terminal'
-      ? 'terminal'
-      : contentType === 'notes'
-        ? 'notes'
-        : 'editor'
+  return contentType === 'browser' ? 'browser' : contentType === 'terminal' ? 'terminal' : 'editor'
 }
 
 async function listWorktreesForRepo(
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index 3d88e85d7ca..11f69041672 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -129,7 +129,6 @@ function createWebPreloadApi(): Partial<PreloadApi> {
     browser: createBrowserApi(),
     gh: createGitHubApi(),
     linear: createRuntimeNamespaceApi('linear'),
-    notes: createNotesApi(),
     hooks: createHooksApi(),
     stats: {
       getSummary: async () =>
@@ -635,23 +634,6 @@ function createRuntimeNamespaceApi(prefix: string): never {
   }) as never
 }
 
-function createNotesApi(): NonNullable<Partial<PreloadApi>['notes']> {
-  const noteCall = (method: string) => (args: Record<string, unknown>) =>
-    callRuntimeResult(method, { ...args, worktree: args.worktreeId })
-  return {
-    list: noteCall('note.list'),
-    show: noteCall('note.show'),
-    create: noteCall('note.create'),
-    save: noteCall('note.save'),
-    rename: noteCall('note.rename'),
-    delete: noteCall('note.delete'),
-    append: noteCall('note.append'),
-    search: noteCall('note.search'),
-    link: noteCall('note.link'),
-    panelState: noteCall('note.panelState')
-  } as NonNullable<Partial<PreloadApi>['notes']>
-}
-
 function createHooksApi(): NonNullable<Partial<PreloadApi>['hooks']> {
   return {
     check: async ({ repoId }) => callRuntimeResult('repo.hooksCheck', { repo: repoId }),
diff --git a/src/shared/notes-types.ts b/src/shared/notes-types.ts
deleted file mode 100644
index 447beae89cb..00000000000
--- a/src/shared/notes-types.ts
+++ /dev/null
@@ -1,130 +0,0 @@
-export type NoteLinkKind = 'active' | 'referenced'
-
-export type NoteRecord = {
-  id: string
-  projectId: string
-  filePath: string
-  relativePath: string
-  title: string
-  bodyMarkdown: string
-  revision: number
-  createdAt: string
-  updatedAt: string
-  archivedAt: string | null
-  createdBySessionId?: string | null
-  updatedBySessionId?: string | null
-}
-
-export type NoteLink = {
-  noteId: string
-  projectId: string
-  worktreeId: string
-  kind: NoteLinkKind
-  createdAt: string
-}
-
-export type NoteSummary = Omit<NoteRecord, 'bodyMarkdown'> & {
-  preview: string
-  linkKind: NoteLinkKind | null
-}
-
-export type NoteListResult = {
-  notes: NoteSummary[]
-  totalCount: number
-  truncated: boolean
-}
-
-export type NoteShowResult = {
-  note: NoteRecord
-  linkKind: NoteLinkKind | null
-}
-
-export type NoteMutationResult = {
-  note: NoteRecord
-  linkKind: NoteLinkKind | null
-}
-
-export type NotesPanelOpenState =
-  | { state: 'noProject' }
-  | { state: 'emptyDraft'; projectId: string; worktreeId: string | null }
-  | { state: 'pickerRequired'; projectId: string; worktreeId: string | null; notes: NoteSummary[] }
-  | { state: 'active'; projectId: string; worktreeId: string | null; note: NoteRecord }
-
-export type NoteListArgs = {
-  projectId: string
-  worktreeId?: string | null
-  limit?: number
-}
-
-export type NoteShowArgs = {
-  projectId: string
-  worktreeId?: string | null
-  note: string
-}
-
-export type NoteCreateArgs = {
-  projectId: string
-  worktreeId?: string | null
-  title: string
-  bodyMarkdown?: string
-  makeActive?: boolean
-  createdBySessionId?: string | null
-}
-
-export type NoteSaveArgs = {
-  projectId: string
-  worktreeId?: string | null
-  note: string
-  title?: string
-  bodyMarkdown: string
-  revision?: number
-  makeActive?: boolean
-  updatedBySessionId?: string | null
-}
-
-export type NoteRenameArgs = {
-  projectId: string
-  worktreeId?: string | null
-  note: string
-  title: string
-  updatedBySessionId?: string | null
-}
-
-export type NoteDeleteArgs = {
-  projectId: string
-  worktreeId?: string | null
-  note: string
-}
-
-export type NoteDeleteResult = {
-  noteId: string
-  projectId: string
-}
-
-export type NoteAppendArgs = {
-  projectId: string
-  worktreeId?: string | null
-  note: string
-  bodyMarkdown: string
-  makeActive?: boolean
-  updatedBySessionId?: string | null
-}
-
-export type NoteSearchArgs = {
-  projectId: string
-  worktreeId?: string | null
-  query: string
-  limit?: number
-}
-
-export type NoteLinkArgs = {
-  projectId: string
-  worktreeId: string
-  note: string
-  kind: NoteLinkKind
-}
-
-export type NotesPanelStateArgs = {
-  projectId?: string | null
-  worktreeId?: string | null
-}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 448ce8b0091..d2441f4e708 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -229,15 +229,9 @@ export type TabGroupLayoutNode =
     }
 
 // ─── Unified Tab ────────────────────────────────────────────────────
-export type TabContentType =
-  | 'terminal'
-  | 'editor'
-  | 'diff'
-  | 'conflict-review'
-  | 'browser'
-  | 'notes'
+export type TabContentType = 'terminal' | 'editor' | 'diff' | 'conflict-review' | 'browser'
 
-export type WorkspaceVisibleTabType = 'terminal' | 'editor' | 'browser' | 'notes'
+export type WorkspaceVisibleTabType = 'terminal' | 'editor' | 'browser'
 
 export type Tab = {
   id: string // UUID for terminals, filePath for editors (preserves current convention)
@@ -252,7 +246,6 @@ export type Tab = {
   createdAt: number
   isPreview?: boolean // preview tabs get replaced by next single-click open
   isPinned?: boolean // pinned tabs survive "close others"
-  isDirty?: boolean // unsaved tab-local content, currently used by Project Notes
 }
 
 export type TabGroup = {
diff --git a/src/shared/workspace-session-schema.ts b/src/shared/workspace-session-schema.ts
index d008f625330..2fd4eb3fa4b 100644
--- a/src/shared/workspace-session-schema.ts
+++ b/src/shared/workspace-session-schema.ts
@@ -65,16 +65,9 @@ const terminalTabSchema = z.object({
 
 // ─── Unified tab model ──────────────────────────────────────────────
 
-const tabContentTypeSchema = z.enum([
-  'terminal',
-  'editor',
-  'diff',
-  'conflict-review',
-  'browser',
-  'notes'
-])
+const tabContentTypeSchema = z.enum(['terminal', 'editor', 'diff', 'conflict-review', 'browser'])
 
-const workspaceVisibleTabTypeSchema = z.enum(['terminal', 'editor', 'browser', 'notes'])
+const workspaceVisibleTabTypeSchema = z.enum(['terminal', 'editor', 'browser'])
 
 const tabSchema = z.object({
   id: z.string(),
@@ -88,8 +81,7 @@ const tabSchema = z.object({
   sortOrder: z.number(),
   createdAt: z.number(),
   isPreview: z.boolean().optional(),
-  isPinned: z.boolean().optional(),
-  isDirty: z.boolean().optional()
+  isPinned: z.boolean().optional()
 })
 
 const tabGroupSchema = z.object({

From e42c78107c5fbb3803c6734d1930bbf7d0999f5d Mon Sep 17 00:00:00 2001
From: Prateek Rungta <prateek@users.noreply.github.com>
Date: Fri, 15 May 2026 14:47:13 -0400
Subject: [PATCH 48/82] Mobile: replace presence-lock banner with loud overlay
 + collapsible chip (#1899)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Orca <help@stably.ai>
Co-authored-by: Jinwoo-H <jinwoo0825@gmail.com>
---
 docs/mobile-presence-lock.md                  | 164 +++++-----
 src/main/ipc/runtime.ts                       |  15 +-
 src/main/runtime/orca-runtime.ts              |  10 +-
 src/preload/api-types.ts                      |  17 +-
 src/preload/index.ts                          |  19 +-
 .../terminal-pane/MobileDriverOverlay.tsx     | 210 +++++++++++++
 .../components/terminal-pane/TerminalPane.tsx | 134 ++++-----
 src/renderer/src/hooks/useIpcEvents.test.ts   |   8 +
 src/renderer/src/hooks/useIpcEvents.ts        |  68 ++++-
 .../pane-manager/mobile-driver-state.test.ts  |  47 +++
 .../lib/pane-manager/mobile-driver-state.ts   |  25 +-
 .../mobile-fit-overrides-hydration.test.ts    |  25 ++
 .../lib/pane-manager/mobile-fit-overrides.ts  |  27 ++
 src/renderer/src/web/web-preload-api.ts       |   1 +
 src/shared/runtime-types.ts                   |   7 +
 tests/e2e/mobile-banner.spec.ts               | 280 ++++++++++++++++++
 16 files changed, 871 insertions(+), 186 deletions(-)
 create mode 100644 src/renderer/src/components/terminal-pane/MobileDriverOverlay.tsx
 create mode 100644 src/renderer/src/lib/pane-manager/mobile-driver-state.test.ts
 create mode 100644 src/renderer/src/lib/pane-manager/mobile-fit-overrides-hydration.test.ts
 create mode 100644 tests/e2e/mobile-banner.spec.ts

diff --git a/docs/mobile-presence-lock.md b/docs/mobile-presence-lock.md
index 12584a51dab..d328befcaaf 100644
--- a/docs/mobile-presence-lock.md
+++ b/docs/mobile-presence-lock.md
@@ -46,7 +46,7 @@ watching.
 Repurpose the banner into a general presence-based lock with this single
 rule:
 
-> At any moment, each PTY has exactly one *driver* — desktop, a specific
+> At any moment, each PTY has exactly one _driver_ — desktop, a specific
 > mobile client, or nobody. While mobile drives, desktop input and resize
 > are dropped; the desktop banner explains why and offers **Take back** to
 > hand the floor over. While desktop drives, mobile keystrokes silently
@@ -69,10 +69,7 @@ exactly one driver per PTY at any moment, and transitions are atomic
 (updated and emitted together from the runtime).
 
 ```ts
-type DriverState =
-  | { kind: 'idle' }
-  | { kind: 'desktop' }
-  | { kind: 'mobile'; clientId: string }
+type DriverState = { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
 ```
 
 - `idle` — no mobile subscribers; desktop input and resize flow through
@@ -98,26 +95,26 @@ Invariants:
   that window passes the renderer guard and is dropped by the server
   guard.
 - Only one driver per PTY at any moment. Multiple mobile clients can
-  *subscribe* simultaneously (see "Multi-mobile subscriber model"), but
+  _subscribe_ simultaneously (see "Multi-mobile subscriber model"), but
   only the most recent mobile actor is the driver.
 
 ### Transitions
 
-| Current driver | Trigger | Next driver | Side effect |
-|---|---|---|---|
-| `idle` | mobile subscribes with `displayMode='auto'` (first client for this ptyId) | `mobile{clientId}` | banner mounts on desktop; PTY resizes to phone dims |
-| `idle` | mobile subscribes with `displayMode='desktop'` (first client for this ptyId) | `desktop` | inner subscriber map populated; **no** banner; PTY stays at desktop dims |
-| `idle` | desktop input or first PTY data after no subscribers | `idle` (no transition) | — |
-| `mobile{A}` | desktop clicks **Take back** | `desktop` | banner unmounts; PTY snaps to desktop dims if at phone dims |
-| `mobile{A}` | mobile A sends input/resize/setDisplayMode | `mobile{A}` (no transition) | — |
-| `mobile{A}` | mobile B sends input | `mobile{B}` | (no banner change; both are "mobile") |
-| `mobile{A}` | last mobile client unsubscribes | `idle` | banner unmounts |
-| `desktop` | any mobile client sends input/resize | `mobile{thatClient}` | banner mounts; PTY snaps to phone dims if that client's mode is auto |
-| `desktop` | mobile sets `displayMode` to `auto` or `phone` | `mobile{thatClient}` | banner mounts; PTY snaps to phone dims (deliberate "I want to drive" gesture) |
-| `desktop` | mobile sets `displayMode` to `desktop` | `desktop` (no transition) | — (already desktop-mode watching) |
-| `desktop` | mobile subscribes-fresh with `auto`/`phone` | `mobile{thatClient}` | banner mounts; PTY snaps to phone dims |
-| `desktop` | mobile subscribes-fresh with `desktop` | `desktop` (no transition) | inner map updated; no banner |
-| `desktop` | last mobile client unsubscribes | `idle` | (banner already unmounted) |
+| Current driver | Trigger                                                                      | Next driver                 | Side effect                                                                   |
+| -------------- | ---------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------- |
+| `idle`         | mobile subscribes with `displayMode='auto'` (first client for this ptyId)    | `mobile{clientId}`          | banner mounts on desktop; PTY resizes to phone dims                           |
+| `idle`         | mobile subscribes with `displayMode='desktop'` (first client for this ptyId) | `desktop`                   | inner subscriber map populated; **no** banner; PTY stays at desktop dims      |
+| `idle`         | desktop input or first PTY data after no subscribers                         | `idle` (no transition)      | —                                                                             |
+| `mobile{A}`    | desktop clicks **Take back**                                                 | `desktop`                   | banner unmounts; PTY snaps to desktop dims if at phone dims                   |
+| `mobile{A}`    | mobile A sends input/resize/setDisplayMode                                   | `mobile{A}` (no transition) | —                                                                             |
+| `mobile{A}`    | mobile B sends input                                                         | `mobile{B}`                 | (no banner change; both are "mobile")                                         |
+| `mobile{A}`    | last mobile client unsubscribes                                              | `idle`                      | banner unmounts                                                               |
+| `desktop`      | any mobile client sends input/resize                                         | `mobile{thatClient}`        | banner mounts; PTY snaps to phone dims if that client's mode is auto          |
+| `desktop`      | mobile sets `displayMode` to `auto` or `phone`                               | `mobile{thatClient}`        | banner mounts; PTY snaps to phone dims (deliberate "I want to drive" gesture) |
+| `desktop`      | mobile sets `displayMode` to `desktop`                                       | `desktop` (no transition)   | — (already desktop-mode watching)                                             |
+| `desktop`      | mobile subscribes-fresh with `auto`/`phone`                                  | `mobile{thatClient}`        | banner mounts; PTY snaps to phone dims                                        |
+| `desktop`      | mobile subscribes-fresh with `desktop`                                       | `desktop` (no transition)   | inner map updated; no banner                                                  |
+| `desktop`      | last mobile client unsubscribes                                              | `idle`                      | (banner already unmounted)                                                    |
 
 **Subscribe-in-desktop-mode rule.** A mobile client subscribing in
 `displayMode='desktop'` is treated as a passive watch, not a take-floor
@@ -125,13 +122,13 @@ gesture. The driver stays at `idle`/`desktop`, so the desktop user is not
 interrupted. The instant that client (or any peer) sends input, sets the
 display mode to `auto`/`phone`, or sends a resize, the runtime transitions
 to `mobile{thatClient}` and the banner appears. This matches the rest of
-the design: the lock engages on *interaction*, not on *presence*.
+the design: the lock engages on _interaction_, not on _presence_.
 
 The protocol is "first-mover wins until the other party acts." Desktop
 clicks Take back, mobile types, desktop types again — banner ping-pongs as
 each side acts. The `clientId` carried in `mobile{clientId}` is updated
 each time a mobile actor takes the floor; this is the wire channel by
-which the runtime knows *which* phone last drove (useful for the
+which the runtime knows _which_ phone last drove (useful for the
 forward-path coordinator described at the bottom of this doc, and for the
 multi-mobile semantics described below).
 
@@ -156,27 +153,29 @@ In the symmetric direction, mobile reclaim:
 
 ## End-user UX
 
-| Driver | Banner (desktop) | Desktop input | Desktop resize |
-|---|---|---|---|
-| `idle` | hidden | allowed | allowed |
-| `mobile{*}` | "🔒 Mobile is driving this terminal — your input is paused. Click **Take back** to resume." | blocked at xterm.onData (silent drop) | blocked in renderer + dropped in `pty:resize` IPC server-side |
-| `desktop` | hidden | allowed | allowed |
+| Driver      | Overlay (desktop)                                                                                 | Desktop input                         | Desktop resize                                                |
+| ----------- | ------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------- |
+| `idle`      | hidden                                                                                            | allowed                               | allowed                                                       |
+| `mobile{*}` | loud lock overlay with **Take back** and **Collapse**; collapsed chip keeps **Take back** visible | blocked at xterm.onData (silent drop) | blocked in renderer + dropped in `pty:resize` IPC server-side |
+| `desktop`   | hidden                                                                                            | allowed                               | allowed                                                       |
 
 Walkthroughs:
 
-**Phone connects while you're typing.** Banner pops in. PTY may resize to
+**Phone connects while you're typing.** Overlay appears. PTY may resize to
 phone dims (existing). Your next keystroke is dropped. Click Take back to
 unlock and (if needed) restore desktop dims.
 
-**You click Take back.** Banner gone. You type freely. Mobile stays
+**You click Take back.** Overlay gone. You type freely. Mobile stays
 connected; mobile sees the desktop-sized terminal because PTY snapped back
 (or stayed at desktop dims if mobile was in desktop mode).
 
-**Mobile types something while you're reclaimed.** Banner reappears. Your
+**Mobile types something while you're reclaimed.** Overlay reappears. Your
 next keystroke is blocked. PTY may snap back to phone dims (if mobile is in
 auto mode).
 
-**Mobile disconnects.** Banner gone permanently. Driver returns to `idle`.
+**Mobile disconnects.** The active-driver overlay is gone. If the PTY is
+still held at phone dimensions, the held-fit Restore overlay remains until
+desktop restores or the finite auto-restore timer fires.
 
 **Multiple panes.** Driver state is per-pane. Phone on pane A doesn't
 affect pane B.
@@ -184,7 +183,7 @@ affect pane B.
 **Text selection / scrollback / copy.** Always allowed. The lock is
 keystroke and resize only.
 
-**Output continues to render.** While the banner is mounted, terminal
+**Output continues to render.** While the overlay is mounted, terminal
 output streams to xterm normally — it is the mobile actor's bytes you
 are seeing. Only desktop-side keystrokes and resize are dropped. This
 matters because "your input is paused" can read ambiguously; output
@@ -216,7 +215,7 @@ This is asymmetric and we are accepting it deliberately:
   surface; a banner with no actionable control is closer to noise than
   signal.
 
-The flip side: a mobile user typing into a stale view *won't* be told
+The flip side: a mobile user typing into a stale view _won't_ be told
 "hold on, desktop is driving" before their keystroke lands. They just take
 the floor. We consider that acceptable because (a) they're explicitly
 acting, and (b) the desktop user gets the warning side of the tradeoff
@@ -268,7 +267,7 @@ other.
 
 ### Why a structured payload vs `locked: boolean`?
 
-The runtime needs to know *which* mobile client most recently drove (for
+The runtime needs to know _which_ mobile client most recently drove (for
 multi-mobile semantics today and for the future write coordinator). A
 structured `DriverState` payload makes that information first-class on
 the wire instead of smuggling it through a side channel. The cost is ~70
@@ -301,7 +300,7 @@ callsite:
   driver-change; peers still have the floor.
 - **`applyMobileDisplayMode(ptyId)`** — iterate the inner map. The
   restore-resize semantics need a single representative subscriber (the
-  desktop dims to restore *to* are stored on the subscriber record). Pick
+  desktop dims to restore _to_ are stored on the subscriber record). Pick
   the earliest by subscribe time so the restore target is stable as
   later phones come and go. The display mode itself is per-PTY runtime
   state, not per-client.
@@ -333,9 +332,9 @@ callsite:
     wasResizedToPhone: boolean
     previousCols: number | null
     previousRows: number | null
-    subscribedAt: number  // ms since epoch, set on insert
-    lastActedAt: number   // ms since epoch, init = subscribedAt;
-                          // updated on every mobileTookFloor for this client
+    subscribedAt: number // ms since epoch, set on insert
+    lastActedAt: number // ms since epoch, init = subscribedAt;
+    // updated on every mobileTookFloor for this client
   }
   ```
 
@@ -358,6 +357,7 @@ callsite:
   Both operations are O(n) over the inner map, which is bounded by
   the number of concurrently subscribed mobile clients (typically 1,
   rarely 2-3). No indexing needed.
+
 - **`isMobileSubscriberActive(ptyId)`** — returns `true` iff the inner map
   is non-empty.
 - **Driver state for the mobile side** stores the `clientId` of the most
@@ -384,7 +384,7 @@ Files touched:
    `applyMobileDisplayMode` / `isMobileSubscriberActive` per the
    multi-mobile model above. **Extend `onPtyExit` cleanup** to
    `currentDriver.delete(ptyId)` and emit `terminalDriverChanged(ptyId,
-   { kind: 'idle' })` so any banner mounted on the dead pane unmounts.
+{ kind: 'idle' })` so any banner mounted on the dead pane unmounts.
    Without this, a dead PTY's last driver state lingers and the
    renderer banner could persist on a dead pane until tab teardown.
 2. `src/main/runtime/orca-runtime.ts` interface `RuntimeNotifier` — add
@@ -410,16 +410,15 @@ Files touched:
 
    **Canonical identity shape.** Use the existing
    `terminal.subscribe` shape: `client: { id: string; type: 'mobile'
-   \| 'desktop' }` (with `type` optional). `TerminalResizeForClient`
+\| 'desktop' }` (with `type` optional). `TerminalResizeForClient`
    keeps its grandfathered top-level `clientId: string` field for
    backward compatibility — implementers may add an aliased nested
    `client.id` setter for consistency at the call site, but the wire
    shape is preserved.
 
    New fields on existing schemas:
-
    - `TerminalSend` gains `client: { id: string; type?: 'mobile' \|
-     'desktop' }` (optional for backward compatibility — falls back
+'desktop' }` (optional for backward compatibility — falls back
      to "the most recent mobile actor" when absent).
    - `TerminalSetDisplayMode` gains the same `client` field.
    - `TerminalUnsubscribe` gains `client: { id: string }` so the
@@ -439,13 +438,13 @@ Files touched:
 
    **Unsubscribe-side composite key.** The mobile RPC client today
    emits `terminal.unsubscribe` with `params: { subscriptionId:
-   stream.params.terminal }` — the bare handle. With the subscribe
+stream.params.terminal }` — the bare handle. With the subscribe
    side now keying by composite, a bare-handle unsubscribe will miss
    in `subscriptionCleanups.get(bareHandle)` and silently no-op,
    leaking the data listener and leaving `mobileSubscribers`
    populated forever (banner stuck, driver never returns to `idle`).
    Fix: the mobile RPC client emits `{ subscriptionId:
-   ${terminal}:${clientId}, client: { id: clientId } }`, and the
+${terminal}:${clientId}, client: { id: clientId } }`, and the
    server's `cleanupSubscription` uses whichever the caller sent —
    if both `subscriptionId` and `client.id` are present and the
    caller passed only `terminal` in `subscriptionId`, the server
@@ -461,12 +460,13 @@ Files touched:
    that direction is moot because the stale server has not adopted
    composite keys on subscribe either. No client newer than server,
    so this is safe.
+
 7. `src/main/ipc/pty.ts` — defense in depth: drop `pty:write` and
    `pty:resize` calls when
    `runtime.getDriver(id).kind === 'mobile'`. **Preserve the existing
    `runtime.isResizeSuppressed()` short-circuit at the top of the
-   `pty:resize` handler** — the new driver-state guard is *in
-   addition to*, not in place of, the suppression window. The two
+   `pty:resize` handler** — the new driver-state guard is _in
+   addition to_, not in place of, the suppression window. The two
    guards have different purposes: `isResizeSuppressed()` blocks the
    safeFit cascade after a take-back transition (preventing
    collateral resize corruption of background panes), while the
@@ -539,7 +539,7 @@ deliberate mobile actions, not to internal runtime calls.
 ```ts
 // pty-connection.ts onData
 if (currentPtyId && getDriverForPty(currentPtyId).kind === 'mobile') {
-  return  // Mobile is driving this PTY; banner explains.
+  return // Mobile is driving this PTY; banner explains.
 }
 // existing transport.sendInput(data)
 
@@ -551,28 +551,40 @@ if (currentPtyId && getDriverForPty(currentPtyId).kind === 'mobile') {
 // was added to prevent.
 if (
   currentPtyId &&
-  (getFitOverrideForPty(currentPtyId) ||
-    getDriverForPty(currentPtyId).kind === 'mobile')
+  (getFitOverrideForPty(currentPtyId) || getDriverForPty(currentPtyId).kind === 'mobile')
 ) {
   return
 }
 ```
 
-### Banner copy
+### Overlay copy
 
-```
-🔒 Mobile is driving this terminal — your input is paused. [ Take back ]
-```
+The lock UI is a full-pane overlay (not a thin banner) so users cannot
+miss it. The driving state can be collapsed to a corner chip while the
+session is being watched; the held-fit state stays loud because there is
+no live output to monitor (see `MobileDriverOverlay.tsx`).
 
-When PTY is at phone dims, append the dim suffix:
-```
-🔒 Mobile is driving this terminal (80×24) — your input is paused. [ Take back ]
-```
+Driving state, expanded:
 
-The phrasing makes Take back the discoverable resolution. There is no
-auto-unlock-on-WS-silence and no liveness probing; the banner stays up
-until the desktop user takes back, until mobile actor sends input (which
-keeps mobile as driver), or until the last mobile subscriber disconnects.
+- Eyebrow: `Mobile is driving this terminal`
+- Title: `Your keyboard is paused`
+- Body: `Output below is being typed from your phone. Take back to resume typing on the desktop, or collapse to keep watching.`
+- Buttons: `Collapse`, `Take back`
+
+Driving state, collapsed (corner chip): `● Mobile driving [ Take back ]`.
+Clicking the label re-expands.
+
+Held-at-phone-fit (no active mobile subscriber, PTY still at phone dims):
+
+- Eyebrow: `Held at phone size`
+- Title: `This terminal is sized for your mobile app`
+- Body: `The session is still being held at the dimensions your phone last reported. Restore to use it on your desktop.`
+- Button: `Restore desktop size`
+
+There is no auto-unlock-on-WS-silence and no liveness probing; the overlay
+stays up until the desktop user takes back / restores, until mobile actor
+sends input (which keeps mobile as driver), or until the last mobile
+subscriber disconnects.
 
 ## Edge cases
 
@@ -584,7 +596,7 @@ keeps mobile as driver), or until the last mobile subscriber disconnects.
   (`desktop → mobile{thatClient}`).
 - **Two phones on same PTY**. The inner map carries both subscribers.
   Driver state is `mobile{whicheverActedLast}`. Phone A unsubscribing
-  while phone B is still on does *not* drop the banner; only the last
+  while phone B is still on does _not_ drop the banner; only the last
   client leaving the inner map transitions to `idle`.
 - **Pre-locked input in flight**. `transport.sendInput` is
   fire-and-forget; there is no in-flight queue to drain. The first
@@ -600,18 +612,14 @@ keeps mobile as driver), or until the last mobile subscriber disconnects.
   `idle → mobile{thatClient}`) transition. A mobile reconnect takes back
   the floor from desktop — correct semantic since the user actively
   reopened the mobile view.
-- **Restore-debounce window on last-subscriber-leaves**. When the
-  last mobile subscriber unsubscribes, the driver transitions to
-  `idle` synchronously (banner unmounts immediately on desktop), but
-  the PTY-dim restore runs inside the existing 300ms
-  `pendingRestoreTimers` debounce. For up to 300ms after the banner
-  unmounts, the PTY remains at phone dims while desktop input flows
-  through. Desktop typing into a still-squished terminal is a brief
-  visual mismatch, not a correctness bug — the existing debounce is
-  there to absorb rapid tab switches without thrashing PTY size, and
-  emitting `idle` synchronously preserves that behavior. Do not
-  reorder these (driver-emit-first, then debounced restore) without
-  re-introducing thrash.
+- **Held-fit window on last-subscriber-leaves**. When the last mobile
+  subscriber unsubscribes, the driver transitions to `idle`
+  synchronously. The active-driver overlay swaps to the held-fit Restore
+  overlay while the phone-fit override remains. With the default
+  indefinite hold, that Restore overlay stays up until desktop restores;
+  with finite auto-restore, it stays up until the timer restores the PTY
+  back to desktop dims. This keeps the "why is my terminal phone-sized?"
+  explanation visible even after the mobile driver is gone.
 
 ## Tests
 
@@ -640,9 +648,9 @@ keeps mobile as driver), or until the last mobile subscriber disconnects.
   - `applyMobileDisplayMode` picks the **most-recent-actor's**
     viewport for active phone-fit dims and the
     **earliest-by-subscribe-time** desktop dims for restore.
-  - Mobile sets `displayMode` to `desktop` from `mobile{*}` does *not*
+  - Mobile sets `displayMode` to `desktop` from `mobile{*}` does _not_
     transition to `desktop` automatically (existing setDisplayMode
-    semantics stand) — but the runtime's *driver* transition rule for
+    semantics stand) — but the runtime's _driver_ transition rule for
     `desktop → desktop` (mode change to desktop while already in
     desktop driver) is a no-op.
 - `terminal.test.ts` (subscriptionId per-client keying):
@@ -658,7 +666,7 @@ keeps mobile as driver), or until the last mobile subscriber disconnects.
   - `onResize` is dropped while driver is `mobile`.
 - `pty.test.ts` (or new `pty-driver-state.test.ts`):
   - `pty:write` IPC is dropped when `runtime.getDriver(id).kind ===
-    'mobile'`.
+'mobile'`.
   - `pty:resize` IPC is dropped under the same predicate.
 
 ## Out of scope
diff --git a/src/main/ipc/runtime.ts b/src/main/ipc/runtime.ts
index d6c91e9e96e..a4f3b3ace4e 100644
--- a/src/main/ipc/runtime.ts
+++ b/src/main/ipc/runtime.ts
@@ -1,6 +1,10 @@
 import { BrowserWindow, ipcMain } from 'electron'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
-import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../../shared/runtime-types'
+import type {
+  RuntimeStatus,
+  RuntimeSyncWindowGraph,
+  RuntimeTerminalDriverState
+} from '../../shared/runtime-types'
 import type { RuntimeRpcResponse } from '../../shared/runtime-rpc-envelope'
 import { RpcDispatcher } from '../runtime/rpc/dispatcher'
 
@@ -51,6 +55,15 @@ export function registerRuntimeHandlers(runtime: OrcaRuntimeService): void {
     }
   )
 
+  ipcMain.removeHandler('runtime:getTerminalDrivers')
+  ipcMain.handle(
+    'runtime:getTerminalDrivers',
+    (): { ptyId: string; driver: RuntimeTerminalDriverState }[] => {
+      const drivers = runtime.getAllTerminalDrivers()
+      return Array.from(drivers.entries()).map(([ptyId, driver]) => ({ ptyId, driver }))
+    }
+  )
+
   // Why: the desktop "Restore" button sets the display mode to 'desktop' and
   // applies it, which restores the PTY to its original dimensions and emits
   // a 'resized' event to any active mobile subscriber. This uses the same
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 8e6d46134de..7eae9c84c16 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -73,6 +73,7 @@ import type {
   RuntimeMobileSessionTabsRemovedResult,
   RuntimeMobileSessionTabsResult,
   RuntimeMobileSessionTabsSnapshot,
+  RuntimeTerminalDriverState,
   RuntimeSyncWindowGraph,
   RuntimeWorktreeListResult
 } from '../../shared/runtime-types'
@@ -480,10 +481,7 @@ export type MobileNotificationEvent = {
 //   - `mobile{clientId}`: a mobile client is the active driver; desktop
 //      input/resize are dropped server-side and the lock banner is mounted.
 //      `clientId` is the most recent mobile actor for this PTY.
-export type DriverState =
-  | { kind: 'idle' }
-  | { kind: 'desktop' }
-  | { kind: 'mobile'; clientId: string }
+export type DriverState = RuntimeTerminalDriverState
 
 // Why: per-PTY layout target — what the PTY *should* be at right now.
 // `desktop` ⇒ runs at the desktop renderer's pane geometry; mobile passive
@@ -2123,6 +2121,10 @@ export class OrcaRuntimeService {
     return result
   }
 
+  getAllTerminalDrivers(): Map<string, DriverState> {
+    return new Map(this.currentDriver)
+  }
+
   onClientDisconnected(clientId: string): void {
     this.cancelMobileDictationForClient(clientId)
 
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 666a8f3e412..015b5d353c8 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -141,7 +141,11 @@ import type { CliInstallStatus } from '../shared/cli-install-types'
 import type { E2EConfig } from '../shared/e2e-config'
 import type { AgentHookInstallStatus } from '../shared/agent-hook-types'
 import type { AgentStatusIpcPayload } from '../shared/agent-status-types'
-import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../shared/runtime-types'
+import type {
+  RuntimeStatus,
+  RuntimeSyncWindowGraph,
+  RuntimeTerminalDriverState
+} from '../shared/runtime-types'
 import type { ShellOpenLocalPathResult } from '../shared/shell-open-types'
 
 export type { ShellOpenLocalPathResult } from '../shared/shell-open-types'
@@ -1410,6 +1414,12 @@ export type PreloadApi = {
     getTerminalFitOverrides: () => Promise<
       { ptyId: string; mode: 'mobile-fit'; cols: number; rows: number }[]
     >
+    getTerminalDrivers: () => Promise<
+      {
+        ptyId: string
+        driver: RuntimeTerminalDriverState
+      }[]
+    >
     restoreTerminalFit: (ptyId: string) => Promise<{ restored: boolean }>
     onTerminalFitOverrideChanged: (
       callback: (event: {
@@ -1420,10 +1430,7 @@ export type PreloadApi = {
       }) => void
     ) => () => void
     onTerminalDriverChanged: (
-      callback: (event: {
-        ptyId: string
-        driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
-      }) => void
+      callback: (event: { ptyId: string; driver: RuntimeTerminalDriverState }) => void
     ) => () => void
   }
   runtimeEnvironments: {
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 0ae09605a4b..d8cfa69234e 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -33,7 +33,11 @@ import type {
   WorktreeRemoteBranchConflictEvent
 } from '../shared/types'
 import type { ShellOpenLocalPathResult } from '../shared/shell-open-types'
-import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../shared/runtime-types'
+import type {
+  RuntimeStatus,
+  RuntimeSyncWindowGraph,
+  RuntimeTerminalDriverState
+} from '../shared/runtime-types'
 import type { RuntimeRpcResponse } from '../shared/runtime-rpc-envelope'
 import type { PublicKnownRuntimeEnvironment } from '../shared/runtime-environments'
 import type {
@@ -2354,6 +2358,12 @@ const api = {
     getTerminalFitOverrides: (): Promise<
       { ptyId: string; mode: 'mobile-fit'; cols: number; rows: number }[]
     > => ipcRenderer.invoke('runtime:getTerminalFitOverrides'),
+    getTerminalDrivers: (): Promise<
+      {
+        ptyId: string
+        driver: RuntimeTerminalDriverState
+      }[]
+    > => ipcRenderer.invoke('runtime:getTerminalDrivers'),
     restoreTerminalFit: (ptyId: string): Promise<{ restored: boolean }> =>
       ipcRenderer.invoke('runtime:restoreTerminalFit', { ptyId }),
     onTerminalFitOverrideChanged: (
@@ -2372,16 +2382,13 @@ const api = {
       return () => ipcRenderer.removeListener('runtime:terminalFitOverrideChanged', listener)
     },
     onTerminalDriverChanged: (
-      callback: (event: {
-        ptyId: string
-        driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
-      }) => void
+      callback: (event: { ptyId: string; driver: RuntimeTerminalDriverState }) => void
     ): (() => void) => {
       const listener = (
         _event: Electron.IpcRendererEvent,
         data: {
           ptyId: string
-          driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
+          driver: RuntimeTerminalDriverState
         }
       ) => callback(data)
       ipcRenderer.on('runtime:terminalDriverChanged', listener)
diff --git a/src/renderer/src/components/terminal-pane/MobileDriverOverlay.tsx b/src/renderer/src/components/terminal-pane/MobileDriverOverlay.tsx
new file mode 100644
index 00000000000..6b8c5e807e6
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/MobileDriverOverlay.tsx
@@ -0,0 +1,210 @@
+import { useEffect, useId, useRef, useState, type ReactElement } from 'react'
+import { Button } from '@/components/ui/button'
+import { cn } from '@/lib/utils'
+import type { DriverState } from '@/lib/pane-manager/mobile-driver-state'
+
+type Props = {
+  driver: DriverState
+  hasFitOverride: boolean
+  onAction: () => void | Promise<void>
+  /** Identifier class on the rendered root, used by e2e selectors. */
+  rootClassName?: string
+}
+
+// Why: see docs/mobile-presence-lock.md. Driving state preserves output streaming
+// so the chip mode lets users keep watching; held-fit state has no live output to
+// preserve, so it stays loud until Restore.
+export function MobileDriverOverlay({
+  driver,
+  hasFitOverride,
+  onAction,
+  rootClassName
+}: Props): ReactElement | null {
+  const isMobileDriving = driver.kind === 'mobile'
+  const isHeldAtPhoneFit = !isMobileDriving && hasFitOverride
+  const driverClientId = driver.kind === 'mobile' ? driver.clientId : null
+
+  const [collapsed, setCollapsed] = useState(false)
+  const [actionPending, setActionPending] = useState(false)
+  const mountedRef = useRef(true)
+
+  useEffect(
+    () => () => {
+      mountedRef.current = false
+    },
+    []
+  )
+
+  // Re-expand on driver flip so a new mobile actor is loud, not silent.
+  useEffect(() => {
+    if (!isMobileDriving) {
+      return
+    }
+    setCollapsed(false)
+  }, [isMobileDriving, driverClientId])
+
+  if (!isMobileDriving && !isHeldAtPhoneFit) {
+    return null
+  }
+
+  const handleAction = async (): Promise<void> => {
+    if (actionPending) {
+      return
+    }
+    setActionPending(true)
+    try {
+      await onAction()
+    } finally {
+      if (mountedRef.current) {
+        setActionPending(false)
+      }
+    }
+  }
+
+  if (isHeldAtPhoneFit) {
+    return (
+      <LoudOverlay
+        eyebrow="Held at phone size"
+        title="This terminal is sized for your mobile app"
+        body="The session is still being held at the dimensions your phone last reported. Restore to use it on your desktop."
+        actionLabel="Restore desktop size"
+        actionPending={actionPending}
+        onAction={handleAction}
+        tone="held"
+        rootClassName={rootClassName}
+      />
+    )
+  }
+
+  if (collapsed) {
+    return (
+      <LockChip
+        actionPending={actionPending}
+        onAction={handleAction}
+        onExpand={() => setCollapsed(false)}
+        rootClassName={rootClassName}
+      />
+    )
+  }
+
+  return (
+    <LoudOverlay
+      eyebrow="Mobile is driving this terminal"
+      title="Your keyboard is paused"
+      body="Output below is being typed from your phone. Take back to resume typing on the desktop, or collapse to keep watching."
+      actionLabel="Take back"
+      actionPending={actionPending}
+      onAction={handleAction}
+      onCollapse={() => setCollapsed(true)}
+      tone="driving"
+      rootClassName={rootClassName}
+    />
+  )
+}
+
+type LoudOverlayProps = {
+  eyebrow: string
+  title: string
+  body: string
+  actionLabel: string
+  actionPending: boolean
+  onAction: () => void | Promise<void>
+  onCollapse?: () => void
+  tone: 'driving' | 'held'
+  rootClassName?: string
+}
+
+function LoudOverlay({
+  eyebrow,
+  title,
+  body,
+  actionLabel,
+  actionPending,
+  onAction,
+  onCollapse,
+  tone,
+  rootClassName
+}: LoudOverlayProps): ReactElement {
+  const titleId = useId()
+  const bodyId = useId()
+  return (
+    <div
+      role="dialog"
+      aria-live="assertive"
+      aria-labelledby={titleId}
+      aria-describedby={bodyId}
+      className={cn(
+        'pointer-events-none absolute inset-0 z-50 flex items-center justify-center bg-background/80 p-6 backdrop-blur-sm',
+        rootClassName
+      )}
+    >
+      <div className="pointer-events-auto flex w-full max-w-[30rem] flex-col gap-3 rounded-lg border border-border bg-card p-6 pb-5 text-card-foreground shadow-xs">
+        <div
+          className={cn(
+            'flex items-center gap-1.5 text-xs font-medium',
+            tone === 'driving' ? 'text-foreground' : 'text-muted-foreground'
+          )}
+        >
+          <span aria-hidden="true">●</span>
+          <span>{eyebrow}</span>
+        </div>
+        <div id={titleId} className="text-base font-semibold leading-tight">
+          {title}
+        </div>
+        <div id={bodyId} className="text-sm leading-relaxed text-muted-foreground">
+          {body}
+        </div>
+        <div className="mt-1 flex justify-end gap-2">
+          {onCollapse && (
+            <Button type="button" variant="outline" size="sm" onClick={onCollapse}>
+              Collapse
+            </Button>
+          )}
+          {/* autoFocus lands keyboard users on the recovery action when the pane-local lock appears. */}
+          <Button
+            type="button"
+            variant="default"
+            size="sm"
+            onClick={onAction}
+            disabled={actionPending}
+            autoFocus
+          >
+            {actionLabel}
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+type ChipProps = {
+  actionPending: boolean
+  onAction: () => void | Promise<void>
+  onExpand: () => void
+  rootClassName?: string
+}
+
+function LockChip({ actionPending, onAction, onExpand, rootClassName }: ChipProps): ReactElement {
+  return (
+    <div
+      className={cn(
+        'absolute right-2 top-2 z-50 flex items-center gap-1.5 rounded-full border border-border bg-card px-2 py-1 text-xs font-medium text-card-foreground shadow-xs',
+        rootClassName
+      )}
+    >
+      <span aria-hidden="true" className="size-2 rounded-full bg-foreground" />
+      <Button
+        type="button"
+        variant="ghost"
+        size="xs"
+        className="px-1 font-medium"
+        onClick={onExpand}
+      >
+        Mobile driving
+      </Button>
+      <Button type="button" variant="default" size="xs" onClick={onAction} disabled={actionPending}>
+        Take back
+      </Button>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/terminal-pane/TerminalPane.tsx b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
index 909d1f91977..0dd84c77629 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
@@ -26,6 +26,7 @@ import type { MacOptionAsAlt } from './terminal-shortcut-policy'
 import { useEffectiveMacOptionAsAlt } from '@/lib/keyboard-layout/use-effective-mac-option-as-alt'
 import { useTerminalFontZoom } from './useTerminalFontZoom'
 import CloseTerminalDialog from './CloseTerminalDialog'
+import { MobileDriverOverlay } from './MobileDriverOverlay'
 import { TerminalErrorToast } from './TerminalErrorToast'
 import TerminalContextMenu from './TerminalContextMenu'
 import { useSystemPrefersDark } from './use-system-prefers-dark'
@@ -35,11 +36,7 @@ import { useTerminalPaneContextMenu } from './use-terminal-pane-context-menu'
 import { useNotificationDispatch } from './use-notification-dispatch'
 import { connectPanePty } from './pty-connection'
 import { shouldPreserveTerminalScrollbackBuffers } from '../../../../shared/workspace-session-terminal-buffers'
-import {
-  getFitOverrideForPty,
-  getPaneIdsForPty,
-  onOverrideChange
-} from '@/lib/pane-manager/mobile-fit-overrides'
+import { getFitOverrideForPty, onOverrideChange } from '@/lib/pane-manager/mobile-fit-overrides'
 import { getDriverForPty, onDriverChange } from '@/lib/pane-manager/mobile-driver-state'
 import { safeFit } from '@/lib/pane-manager/pane-tree-ops'
 import { captureTerminalShutdownLayout } from './terminal-shutdown-layout-capture'
@@ -144,11 +141,16 @@ export default function TerminalPane({
       onOverrideChange((event) => {
         setOverrideTick((n) => n + 1)
         if (event.mode === 'desktop-fit') {
-          const paneIds = getPaneIdsForPty(event.ptyId)
           const manager = managerRef.current
           if (!manager) {
             return
           }
+          // Why: pane IDs are per-tab, so resolve the affected PTY through this
+          // tab's live transport bindings instead of global numeric pane IDs.
+          const getAffectedPanes = (): ReturnType<typeof manager.getPanes> =>
+            manager
+              .getPanes()
+              .filter((pane) => paneTransportsRef.current.get(pane.id)?.getPtyId() === event.ptyId)
           // Why: fitAddon.fit() measures DOM dimensions, so it must run after
           // the browser has settled layout. Running synchronously inside the
           // IPC callback can produce stale measurements. rAF ensures the DOM
@@ -158,11 +160,8 @@ export default function TerminalPane({
           // dimensions from the runtime. This guarantees xterm exits mobile
           // dims even when the DOM-based fit path fails.
           const fitAffectedPanes = (): void => {
-            for (const paneId of paneIds) {
-              const pane = manager.getPanes().find((p) => p.id === paneId)
-              if (pane) {
-                safeFit(pane)
-              }
+            for (const pane of getAffectedPanes()) {
+              safeFit(pane)
             }
           }
           requestAnimationFrame(fitAffectedPanes)
@@ -179,11 +178,7 @@ export default function TerminalPane({
           // mobile-fit started, not the current pane geometry — applying
           // it would shrink the terminal back to e.g. half-width.
           setTimeout(() => {
-            for (const paneId of paneIds) {
-              const pane = manager.getPanes().find((p) => p.id === paneId)
-              if (!pane) {
-                continue
-              }
+            for (const pane of getAffectedPanes()) {
               // Why: skip the fallback for hidden/unmounted panes whose
               // container is 0×0. Force-resizing xterm to the server's
               // desktop dims while the DOM has no geometry leaves xterm
@@ -1211,80 +1206,57 @@ export default function TerminalPane({
         if (!ptyId) {
           return null
         }
-        // Why: two-state banner. (1) Driver is mobile → presence-lock,
-        // input paused (docs/mobile-presence-lock.md). (2) No mobile
-        // driver but a phone-fit override is still in place → indefinite
-        // hold (docs/mobile-fit-hold.md): the user left mobile, the PTY
-        // is held at phone dims, and the banner is the explicit
-        // return-to-desktop-size escape hatch.
+        // Why: two-state lock UI. (1) Driver is mobile → presence-lock,
+        // input paused (docs/mobile-presence-lock.md). (2) No mobile driver
+        // but a phone-fit override is still in place → indefinite hold
+        // (docs/mobile-fit-hold.md). MobileDriverOverlay owns the visual
+        // treatment and collapse-to-chip state; both branches share a
+        // single IPC route through restoreTerminalFit.
         const driver = getDriverForPty(ptyId)
         const isMobileDriving = driver.kind === 'mobile'
-        const isHeldAtPhoneFit = !isMobileDriving && getFitOverrideForPty(ptyId) !== null
-        if (!isMobileDriving && !isHeldAtPhoneFit) {
+        const hasFitOverride = getFitOverrideForPty(ptyId) !== null
+        if (!isMobileDriving && !hasFitOverride) {
           return null
         }
         return createPortal(
-          <div
-            key={`mobile-driver-${pane.id}`}
-            className="mobile-driver-banner"
-            style={{
-              position: 'absolute',
-              top: 0,
-              left: 0,
-              right: 0,
-              zIndex: 10,
-              padding: '4px 12px',
-              background: 'var(--orca-banner-bg, rgba(30, 30, 30, 0.75))',
-              color: 'var(--orca-banner-fg, #a0a0a0)',
-              fontSize: '12px',
-              display: 'flex',
-              alignItems: 'center',
-              justifyContent: 'space-between'
-            }}
-          >
-            <span>
-              {isMobileDriving
-                ? 'Mobile is driving this terminal — your input is paused. Click Take back to resume.'
-                : 'This terminal is held at phone size for the mobile app. Click Restore to return it to desktop size.'}
-            </span>
-            <button
-              style={{
-                background: 'transparent',
-                border: '1px solid currentColor',
-                borderRadius: '3px',
-                color: 'inherit',
-                padding: '1px 8px',
-                cursor: 'pointer',
-                fontSize: '11px'
-              }}
-              onClick={() => {
-                const ptyId = paneTransportsRef.current.get(pane.id)?.getPtyId()
-                if (ptyId) {
-                  // Why: same IPC route — handler resolves both the
-                  // active-mobile-subscriber path and the held-no-subscriber
-                  // path (docs/mobile-fit-hold.md), so the banner unmounts
-                  // and the PTY returns to desktop dims in either case.
-                  const remoteHandle = getRemoteRuntimeTerminalHandle(ptyId)
-                  const environmentId =
-                    getRemoteRuntimePtyEnvironmentId(ptyId) ??
-                    settingsRef.current?.activeRuntimeEnvironmentId ??
-                    null
-                  if (remoteHandle && environmentId) {
-                    void callRuntimeRpc(
+          <MobileDriverOverlay
+            key={`mobile-driver-${pane.id}-${ptyId}`}
+            driver={driver}
+            hasFitOverride={hasFitOverride}
+            rootClassName="mobile-driver-banner"
+            onAction={async () => {
+              // Why: same restore intent has two transports. Remote-runtime PTYs
+              // must call the environment RPC; local PTYs use the Electron IPC
+              // handler. Both resolve active-mobile and held-no-subscriber states.
+              const transport = paneTransportsRef.current.get(pane.id)
+              const id = transport?.getPtyId()
+              if (!id) {
+                return
+              }
+              const remoteHandle = getRemoteRuntimeTerminalHandle(id)
+              const environmentId =
+                getRemoteRuntimePtyEnvironmentId(id) ??
+                settingsRef.current?.activeRuntimeEnvironmentId ??
+                null
+              const result =
+                remoteHandle && environmentId
+                  ? await callRuntimeRpc<{ restored: boolean }>(
                       { kind: 'environment', environmentId },
                       'terminal.restoreFit',
                       { terminal: remoteHandle },
                       { timeoutMs: 15_000 }
-                    ).catch(() => {})
-                  } else {
-                    void window.api.runtime.restoreTerminalFit(ptyId).catch(() => {})
-                  }
-                }
-              }}
-            >
-              {isMobileDriving ? 'Take back' : 'Restore'}
-            </button>
-          </div>,
+                    ).catch(() => ({ restored: false }))
+                  : await window.api.runtime
+                      .restoreTerminalFit(id)
+                      .catch(() => ({ restored: false }))
+              if (result.restored) {
+                // Why: after the overlay unmounts, focus would otherwise stay on
+                // the removed button/body instead of the terminal the user just
+                // reclaimed.
+                pane.terminal.focus()
+              }
+            }}
+          />,
           pane.container,
           `mobile-driver-banner-${pane.id}`
         )
diff --git a/src/renderer/src/hooks/useIpcEvents.test.ts b/src/renderer/src/hooks/useIpcEvents.test.ts
index a91316e83c9..9e412a5cdf3 100644
--- a/src/renderer/src/hooks/useIpcEvents.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents.test.ts
@@ -217,6 +217,7 @@ describe('useIpcEvents updater integration', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
@@ -425,6 +426,7 @@ describe('useIpcEvents updater integration', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
@@ -657,6 +659,7 @@ describe('useIpcEvents updater integration', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
@@ -950,6 +953,7 @@ describe('useIpcEvents browser tab close routing', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
@@ -1156,6 +1160,7 @@ describe('useIpcEvents browser tab close routing', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
@@ -1357,6 +1362,7 @@ describe('useIpcEvents browser tab close routing', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
@@ -1567,6 +1573,7 @@ describe('useIpcEvents CLI-created worktree activation', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
@@ -1748,6 +1755,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
+          getTerminalDrivers: () => Promise.resolve([]),
           onTerminalFitOverrideChanged: () => () => {},
           onTerminalDriverChanged: () => () => {}
         },
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index 863a69abb25..53cf19d7327 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -12,6 +12,7 @@ import { nextEditorFontZoomLevel, computeEditorFontSize } from '@/lib/editor-fon
 import type { UpdateStatus } from '../../../shared/types'
 import type { RateLimitState } from '../../../shared/rate-limit-types'
 import type { SshConnectionState } from '../../../shared/ssh-types'
+import type { RuntimeTerminalDriverState } from '../../../shared/runtime-types'
 import { zoomLevelToPercent, ZOOM_MIN, ZOOM_MAX } from '@/components/settings/SettingsConstants'
 import { dispatchZoomLevelChanged } from '@/lib/zoom-events'
 import { resolveZoomTarget } from './resolve-zoom-target'
@@ -29,7 +30,7 @@ import { TOGGLE_FLOATING_TERMINAL_EVENT } from '@/lib/floating-terminal'
 import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
 import { focusRuntimeTerminalSurface } from '@/runtime/sync-runtime-graph'
 import { setFitOverride, hydrateOverrides } from '@/lib/pane-manager/mobile-fit-overrides'
-import { setDriverForPty } from '@/lib/pane-manager/mobile-driver-state'
+import { setDriverForPty, hydrateDrivers } from '@/lib/pane-manager/mobile-driver-state'
 import { destroyPersistentWebview } from '@/components/browser-pane/webview-registry'
 import { attachMobileMarkdownBridge } from '@/runtime/mobile-markdown-bridge'
 import { detectLanguage } from '@/lib/language-detect'
@@ -1203,12 +1204,36 @@ export function useIpcEvents(): void {
     requestAgentStatusSnapshotIfReady()
     unsubs.push(useAppStore.subscribe(() => requestAgentStatusSnapshotIfReady()))
 
-    // Why: hydrate mobile-fit overrides before terminal panes run their first
-    // attach/fit logic, so a renderer reload doesn't undo active mobile fits.
-    if (!isRuntimeEnvironmentActive()) {
-      void window.api.runtime.getTerminalFitOverrides().then((overrides) => {
-        hydrateOverrides(overrides)
-      })
+    let mobileStateHydrated = isRuntimeEnvironmentActive()
+    type PendingMobileStateEvent =
+      | {
+          kind: 'fit'
+          event: {
+            ptyId: string
+            mode: 'mobile-fit' | 'desktop-fit'
+            cols: number
+            rows: number
+          }
+        }
+      | {
+          kind: 'driver'
+          event: {
+            ptyId: string
+            driver: RuntimeTerminalDriverState
+          }
+        }
+    const pendingMobileStateEvents: PendingMobileStateEvent[] = []
+
+    const applyPendingMobileStateEvents = (): void => {
+      for (const pending of pendingMobileStateEvents) {
+        if (pending.kind === 'fit') {
+          const { ptyId, mode, cols, rows } = pending.event
+          setFitOverride(ptyId, mode, cols, rows)
+        } else {
+          setDriverForPty(pending.event.ptyId, pending.event.driver)
+        }
+      }
+      pendingMobileStateEvents.length = 0
     }
 
     unsubs.push(
@@ -1216,6 +1241,10 @@ export function useIpcEvents(): void {
         if (isRuntimeEnvironmentActive()) {
           return
         }
+        if (!mobileStateHydrated) {
+          pendingMobileStateEvents.push({ kind: 'fit', event })
+          return
+        }
         setFitOverride(event.ptyId, event.mode, event.cols, event.rows)
       })
     )
@@ -1229,10 +1258,35 @@ export function useIpcEvents(): void {
         if (isRuntimeEnvironmentActive()) {
           return
         }
+        if (!mobileStateHydrated) {
+          pendingMobileStateEvents.push({ kind: 'driver', event })
+          return
+        }
         setDriverForPty(event.ptyId, event.driver)
       })
     )
 
+    // Why: hydrate mobile-owned terminal state on renderer reload. Subscribe
+    // first and buffer live events during the snapshot round trip; otherwise an
+    // older snapshot could overwrite a newer live lock and hide the overlay.
+    if (!isRuntimeEnvironmentActive()) {
+      void Promise.all([
+        window.api.runtime.getTerminalFitOverrides(),
+        window.api.runtime.getTerminalDrivers()
+      ])
+        .then(([overrides, drivers]) => {
+          hydrateOverrides(overrides)
+          hydrateDrivers(drivers)
+          mobileStateHydrated = true
+          applyPendingMobileStateEvents()
+        })
+        .catch((error: unknown) => {
+          console.error('Failed to hydrate mobile terminal state:', error)
+          mobileStateHydrated = true
+          applyPendingMobileStateEvents()
+        })
+    }
+
     return () => unsubs.forEach((fn) => fn())
   }, [])
 }
diff --git a/src/renderer/src/lib/pane-manager/mobile-driver-state.test.ts b/src/renderer/src/lib/pane-manager/mobile-driver-state.test.ts
new file mode 100644
index 00000000000..94b6e15c98b
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/mobile-driver-state.test.ts
@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  getDriverForPty,
+  hydrateDrivers,
+  isPtyLocked,
+  onDriverChange,
+  setDriverForPty
+} from './mobile-driver-state'
+
+afterEach(() => {
+  hydrateDrivers([])
+})
+
+describe('mobile-driver-state', () => {
+  it('stores and clears driver state keyed by PTY id', () => {
+    setDriverForPty('pty-1', { kind: 'mobile', clientId: 'phone-1' })
+
+    expect(getDriverForPty('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-1' })
+    expect(isPtyLocked('pty-1')).toBe(true)
+
+    setDriverForPty('pty-1', { kind: 'idle' })
+
+    expect(getDriverForPty('pty-1')).toEqual({ kind: 'idle' })
+    expect(isPtyLocked('pty-1')).toBe(false)
+  })
+
+  it('hydrates driver snapshots and notifies affected listeners', () => {
+    setDriverForPty('pty-old', { kind: 'mobile', clientId: 'phone-old' })
+    const listener = vi.fn()
+    const unsub = onDriverChange(listener)
+
+    hydrateDrivers([{ ptyId: 'pty-new', driver: { kind: 'mobile', clientId: 'phone-new' } }])
+
+    expect(getDriverForPty('pty-old')).toEqual({ kind: 'idle' })
+    expect(getDriverForPty('pty-new')).toEqual({ kind: 'mobile', clientId: 'phone-new' })
+    expect(listener).toHaveBeenCalledWith({
+      ptyId: 'pty-old',
+      driver: { kind: 'idle' }
+    })
+    expect(listener).toHaveBeenCalledWith({
+      ptyId: 'pty-new',
+      driver: { kind: 'mobile', clientId: 'phone-new' }
+    })
+
+    unsub()
+  })
+})
diff --git a/src/renderer/src/lib/pane-manager/mobile-driver-state.ts b/src/renderer/src/lib/pane-manager/mobile-driver-state.ts
index f6e066dd040..3e97491e7ef 100644
--- a/src/renderer/src/lib/pane-manager/mobile-driver-state.ts
+++ b/src/renderer/src/lib/pane-manager/mobile-driver-state.ts
@@ -9,10 +9,9 @@
 //
 // See docs/mobile-presence-lock.md.
 
-export type DriverState =
-  | { kind: 'idle' }
-  | { kind: 'desktop' }
-  | { kind: 'mobile'; clientId: string }
+import type { RuntimeTerminalDriverState } from '../../../../shared/runtime-types'
+
+export type DriverState = RuntimeTerminalDriverState
 
 const driverByPtyId = new Map<string, DriverState>()
 
@@ -50,3 +49,21 @@ export function getDriverForPty(ptyId: string): DriverState {
 export function isPtyLocked(ptyId: string): boolean {
   return driverByPtyId.get(ptyId)?.kind === 'mobile'
 }
+
+export function hydrateDrivers(drivers: { ptyId: string; driver: DriverState }[]): void {
+  const affectedPtyIds = new Set(driverByPtyId.keys())
+  driverByPtyId.clear()
+
+  for (const { ptyId, driver } of drivers) {
+    affectedPtyIds.add(ptyId)
+    if (driver.kind !== 'idle') {
+      driverByPtyId.set(ptyId, driver)
+    }
+  }
+
+  // Why: startup hydration can arrive after TerminalPane has mounted. Notify
+  // all affected PTYs so the pane-local overlay cannot miss an active lock.
+  for (const ptyId of affectedPtyIds) {
+    notifyChange({ ptyId, driver: getDriverForPty(ptyId) })
+  }
+}
diff --git a/src/renderer/src/lib/pane-manager/mobile-fit-overrides-hydration.test.ts b/src/renderer/src/lib/pane-manager/mobile-fit-overrides-hydration.test.ts
new file mode 100644
index 00000000000..882d2b8ea15
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/mobile-fit-overrides-hydration.test.ts
@@ -0,0 +1,25 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { hydrateOverrides, onOverrideChange, setFitOverride } from './mobile-fit-overrides'
+
+afterEach(() => {
+  hydrateOverrides([])
+})
+
+describe('hydrateOverrides notifications', () => {
+  it('notifies listeners for hydrated and cleared overrides', () => {
+    setFitOverride('pty-old', 'mobile-fit', 49, 20)
+    const events: { ptyId: string; mode: string; priorCols: number | null }[] = []
+    const unsub = onOverrideChange((event) => {
+      events.push({ ptyId: event.ptyId, mode: event.mode, priorCols: event.priorCols })
+    })
+
+    hydrateOverrides([{ ptyId: 'pty-new', mode: 'mobile-fit', cols: 80, rows: 30 }])
+
+    expect(events).toEqual([
+      { ptyId: 'pty-new', mode: 'mobile-fit', priorCols: null },
+      { ptyId: 'pty-old', mode: 'desktop-fit', priorCols: 49 }
+    ])
+
+    unsub()
+  })
+})
diff --git a/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts b/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
index e489069624c..17b26a7805d 100644
--- a/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
+++ b/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
@@ -115,10 +115,37 @@ export function unbindPane(paneId: number, tabId?: string): void {
 export function hydrateOverrides(
   overrides: { ptyId: string; mode: 'mobile-fit'; cols: number; rows: number }[]
 ): void {
+  const previous = new Map(overridesByPtyId)
   overridesByPtyId.clear()
   for (const o of overrides) {
     overridesByPtyId.set(o.ptyId, { mode: o.mode, cols: o.cols, rows: o.rows })
   }
+
+  // Why: hydration can complete after terminal panes mount during reload. Notify
+  // readers so held phone-fit overlays appear even without a fresh IPC event.
+  for (const [ptyId, override] of overridesByPtyId) {
+    const prior = previous.get(ptyId) ?? null
+    notifyChange({
+      ptyId,
+      mode: 'mobile-fit',
+      cols: override.cols,
+      rows: override.rows,
+      priorCols: prior?.cols ?? null,
+      priorRows: prior?.rows ?? null
+    })
+    previous.delete(ptyId)
+  }
+
+  for (const [ptyId, prior] of previous) {
+    notifyChange({
+      ptyId,
+      mode: 'desktop-fit',
+      cols: 0,
+      rows: 0,
+      priorCols: prior.cols,
+      priorRows: prior.rows
+    })
+  }
 }
 
 export function getAllOverrides(): Map<string, FitOverride> {
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index 11f69041672..2541e15937c 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -184,6 +184,7 @@ function createRuntimeApi(): NonNullable<Partial<PreloadApi>['runtime']> {
     getStatus: () => getRemoteRuntimeStatus(),
     call: ({ method, params }) => callRuntimeEnvelope(method, params),
     getTerminalFitOverrides: () => Promise.resolve([]),
+    getTerminalDrivers: () => Promise.resolve([]),
     restoreTerminalFit: () => Promise.resolve({ restored: false }),
     onTerminalFitOverrideChanged: () => noopUnsubscribe,
     onTerminalDriverChanged: () => noopUnsubscribe
diff --git a/src/shared/runtime-types.ts b/src/shared/runtime-types.ts
index 586252341e3..6d89e8d79fb 100644
--- a/src/shared/runtime-types.ts
+++ b/src/shared/runtime-types.ts
@@ -18,6 +18,13 @@ export type { RuntimeMarkdownReadTabResult, RuntimeMarkdownSaveTabResult }
 
 export type RuntimeGraphStatus = 'ready' | 'reloading' | 'unavailable'
 
+// Why: presence-lock driver state crosses main/preload/renderer IPC. Keep one
+// checked source so future variants cannot drift silently across layers.
+export type RuntimeTerminalDriverState =
+  | { kind: 'idle' }
+  | { kind: 'desktop' }
+  | { kind: 'mobile'; clientId: string }
+
 export type RuntimeStatus = {
   runtimeId: string
   rendererGraphEpoch: number
diff --git a/tests/e2e/mobile-banner.spec.ts b/tests/e2e/mobile-banner.spec.ts
new file mode 100644
index 00000000000..3c8f2a3c3f7
--- /dev/null
+++ b/tests/e2e/mobile-banner.spec.ts
@@ -0,0 +1,280 @@
+import type { ElectronApplication, Page, TestInfo } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import { ensureTerminalVisible, waitForSessionReady, waitForActiveWorktree } from './helpers/store'
+import { waitForActivePanePtyId, waitForActiveTerminalManager } from './helpers/terminal'
+
+// Why: regression coverage for the mobile-presence-lock UX (PR #1532,
+// docs/mobile-presence-lock.md). The original bug was that the prior banner
+// mounted but was visually unobtrusive enough that users missed it. Strong DOM
+// assertions guard the "doesn't mount / doesn't dismiss" regression class;
+// screenshots ride in the playwright-traces artifact upload so reviewers can
+// eyeball the rendering on a failed run.
+//
+// Drives the renderer by sending the same IPC events main fires in production
+// (runtime:terminalFitOverrideChanged, runtime:terminalDriverChanged — wired in
+// useIpcEvents.ts). No production-code test backdoor; the spec exercises the
+// renderer-side IPC listener → state mirror → banner JSX chain.
+
+test.describe.configure({ mode: 'serial' })
+
+test('mobile subscribe mounts overlay; collapse → chip; Take back dismisses', async ({
+  orcaPage,
+  electronApp
+}, testInfo) => {
+  await waitForSessionReady(orcaPage)
+  await waitForActiveWorktree(orcaPage)
+  await ensureTerminalVisible(orcaPage)
+  await waitForActiveTerminalManager(orcaPage)
+  const ptyId = await waitForActivePanePtyId(orcaPage)
+  await installRestoreTerminalFitRecorder(electronApp)
+
+  const overlay = orcaPage.locator('.mobile-driver-banner')
+  await expect(overlay).toHaveCount(0)
+
+  // Fire the IPC events main emits when a mobile client subscribes in 'auto'
+  // mode (handleMobileSubscribe in src/main/runtime/orca-runtime.ts). The
+  // renderer's listener calls setFitOverride + setDriverForPty, the banner
+  // observes the change, and MobileDriverOverlay mounts in loud mode.
+  await sendMobileSubscribeIpc(electronApp, { ptyId, cols: 45, rows: 20 })
+
+  await expect(overlay).toBeVisible({ timeout: 15_000 })
+  await expect(overlay).toContainText(/mobile is driving this terminal/i)
+  await expect(overlay).toContainText(/your keyboard is paused/i)
+  await expectExpandedOverlayCoversPane(orcaPage, ptyId)
+
+  const takeBack = overlay.getByRole('button', { name: /take back/i })
+  const collapse = overlay.getByRole('button', { name: /^collapse$/i })
+  await expect(takeBack).toBeVisible()
+  await expect(collapse).toBeVisible()
+
+  await captureAttachment(orcaPage, testInfo, 'overlay-loud.png')
+
+  // Click Collapse → loud overlay swaps to the corner chip while the lock stays
+  // engaged. The user can keep watching live mobile output while the chip
+  // remains a one-click escape hatch back to desktop control.
+  await collapse.click()
+  await expect(overlay).toContainText(/mobile driving/i)
+  await expect(overlay.getByRole('button', { name: /take back/i })).toBeVisible()
+  await expect(overlay).not.toContainText(/your keyboard is paused/i)
+  await expectChipIsCompactInPane(orcaPage, ptyId)
+
+  await captureAttachment(orcaPage, testInfo, 'overlay-collapsed.png')
+
+  await overlay.getByRole('button', { name: /mobile driving/i }).click()
+  await expect(overlay).toContainText(/your keyboard is paused/i)
+  await expectExpandedOverlayCoversPane(orcaPage, ptyId)
+
+  await collapse.click()
+  await expect(overlay).not.toContainText(/your keyboard is paused/i)
+
+  // Take back from the chip dismisses the overlay. The button calls
+  // runtime.restoreTerminalFit via IPC; main responds with desktop-fit + idle
+  // driver events that we mirror here so the renderer state lands on the
+  // post-take-back terminal state.
+  await overlay.getByRole('button', { name: /take back/i }).click()
+  await expectRestoreTerminalFitCalls(electronApp, [ptyId])
+  await sendDesktopRestoreIpc(electronApp, { ptyId })
+  await expect(overlay).toBeHidden({ timeout: 15_000 })
+})
+
+test('held phone-fit state mounts restore overlay without collapse', async ({
+  orcaPage,
+  electronApp
+}, testInfo) => {
+  await waitForSessionReady(orcaPage)
+  await waitForActiveWorktree(orcaPage)
+  await ensureTerminalVisible(orcaPage)
+  await waitForActiveTerminalManager(orcaPage)
+  const ptyId = await waitForActivePanePtyId(orcaPage)
+  await installRestoreTerminalFitRecorder(electronApp)
+
+  const overlay = orcaPage.locator('.mobile-driver-banner')
+  await expect(overlay).toHaveCount(0)
+
+  // Held-fit is the post-mobile-disconnect state: the phone-fit override remains
+  // while the driver returns to idle. It should stay loud because there is no
+  // active mobile output to keep watching behind a collapsed chip.
+  await sendHeldPhoneFitIpc(electronApp, { ptyId, cols: 45, rows: 20 })
+
+  await expect(overlay).toBeVisible({ timeout: 15_000 })
+  await expect(overlay).toContainText(/held at phone size/i)
+  await expect(overlay).toContainText(/restore to use it on your desktop/i)
+  await expect(overlay.getByRole('button', { name: /restore desktop size/i })).toBeVisible()
+  await expect(overlay.getByRole('button', { name: /^collapse$/i })).toHaveCount(0)
+  await expect(overlay.getByRole('button', { name: /take back/i })).toHaveCount(0)
+  await expectExpandedOverlayCoversPane(orcaPage, ptyId)
+
+  await captureAttachment(orcaPage, testInfo, 'overlay-held-fit.png')
+
+  await overlay.getByRole('button', { name: /restore desktop size/i }).click()
+  await expectRestoreTerminalFitCalls(electronApp, [ptyId])
+  await sendDesktopRestoreIpc(electronApp, { ptyId })
+  await expect(overlay).toBeHidden({ timeout: 15_000 })
+})
+
+async function sendMobileSubscribeIpc(
+  electronApp: ElectronApplication,
+  args: { ptyId: string; cols: number; rows: number }
+): Promise<void> {
+  await electronApp.evaluate(({ BrowserWindow }, payload) => {
+    const wins = BrowserWindow.getAllWindows()
+    for (const win of wins) {
+      win.webContents.send('runtime:terminalFitOverrideChanged', {
+        ptyId: payload.ptyId,
+        mode: 'mobile-fit',
+        cols: payload.cols,
+        rows: payload.rows
+      })
+      win.webContents.send('runtime:terminalDriverChanged', {
+        ptyId: payload.ptyId,
+        driver: { kind: 'mobile', clientId: 'fake-phone-1' }
+      })
+    }
+  }, args)
+}
+
+async function sendHeldPhoneFitIpc(
+  electronApp: ElectronApplication,
+  args: { ptyId: string; cols: number; rows: number }
+): Promise<void> {
+  await electronApp.evaluate(({ BrowserWindow }, payload) => {
+    const wins = BrowserWindow.getAllWindows()
+    for (const win of wins) {
+      win.webContents.send('runtime:terminalFitOverrideChanged', {
+        ptyId: payload.ptyId,
+        mode: 'mobile-fit',
+        cols: payload.cols,
+        rows: payload.rows
+      })
+      win.webContents.send('runtime:terminalDriverChanged', {
+        ptyId: payload.ptyId,
+        driver: { kind: 'idle' }
+      })
+    }
+  }, args)
+}
+
+async function sendDesktopRestoreIpc(
+  electronApp: ElectronApplication,
+  args: { ptyId: string }
+): Promise<void> {
+  await electronApp.evaluate(({ BrowserWindow }, payload) => {
+    const wins = BrowserWindow.getAllWindows()
+    for (const win of wins) {
+      win.webContents.send('runtime:terminalFitOverrideChanged', {
+        ptyId: payload.ptyId,
+        mode: 'desktop-fit',
+        cols: 0,
+        rows: 0
+      })
+      win.webContents.send('runtime:terminalDriverChanged', {
+        ptyId: payload.ptyId,
+        driver: { kind: 'idle' }
+      })
+    }
+  }, args)
+}
+
+async function installRestoreTerminalFitRecorder(electronApp: ElectronApplication): Promise<void> {
+  await electronApp.evaluate(({ ipcMain }) => {
+    const testGlobal = globalThis as typeof globalThis & {
+      __mobileBannerRestoreCalls?: string[]
+    }
+    testGlobal.__mobileBannerRestoreCalls = []
+    // Why: the renderer state is driven by production IPC events in this spec,
+    // so the runtime has no real mobile subscriber to reclaim. Replace only the
+    // main-process handler inside the test process to prove the button invokes
+    // the production channel and payload before we mirror the resulting events.
+    ipcMain.removeHandler('runtime:restoreTerminalFit')
+    ipcMain.handle('runtime:restoreTerminalFit', (_event, args: { ptyId: string }) => {
+      testGlobal.__mobileBannerRestoreCalls?.push(args.ptyId)
+      return { restored: true }
+    })
+  })
+}
+
+async function expectRestoreTerminalFitCalls(
+  electronApp: ElectronApplication,
+  expected: string[]
+): Promise<void> {
+  await expect
+    .poll(
+      () =>
+        electronApp.evaluate(
+          () =>
+            (
+              globalThis as typeof globalThis & {
+                __mobileBannerRestoreCalls?: string[]
+              }
+            ).__mobileBannerRestoreCalls ?? []
+        ),
+      { message: 'restoreTerminalFit should be invoked through the production IPC channel' }
+    )
+    .toEqual(expected)
+}
+
+async function expectExpandedOverlayCoversPane(page: Page, ptyId: string): Promise<void> {
+  await expect
+    .poll(
+      () =>
+        page.evaluate((targetPtyId) => {
+          const pane = Array.from(document.querySelectorAll<HTMLElement>('[data-pty-id]')).find(
+            (node) => node.dataset.ptyId === targetPtyId
+          )
+          const overlay = document.querySelector<HTMLElement>('.mobile-driver-banner')
+          if (!pane || !overlay) {
+            return false
+          }
+          const paneBox = pane.getBoundingClientRect()
+          const overlayBox = overlay.getBoundingClientRect()
+          return (
+            Math.abs(overlayBox.left - paneBox.left) <= 2 &&
+            Math.abs(overlayBox.top - paneBox.top) <= 2 &&
+            overlayBox.width >= paneBox.width - 2 &&
+            overlayBox.height >= paneBox.height - 2
+          )
+        }, ptyId),
+      { message: 'expanded overlay should cover the terminal pane' }
+    )
+    .toBe(true)
+}
+
+async function expectChipIsCompactInPane(page: Page, ptyId: string): Promise<void> {
+  await expect
+    .poll(
+      () =>
+        page.evaluate((targetPtyId) => {
+          const pane = Array.from(document.querySelectorAll<HTMLElement>('[data-pty-id]')).find(
+            (node) => node.dataset.ptyId === targetPtyId
+          )
+          const chip = document.querySelector<HTMLElement>('.mobile-driver-banner')
+          if (!pane || !chip) {
+            return false
+          }
+          const paneBox = pane.getBoundingClientRect()
+          const chipBox = chip.getBoundingClientRect()
+          const rightInset = paneBox.right - chipBox.right
+          const topInset = chipBox.top - paneBox.top
+          return (
+            chipBox.width < paneBox.width * 0.6 &&
+            chipBox.height <= 40 &&
+            rightInset >= 6 &&
+            rightInset <= 16 &&
+            topInset >= 6 &&
+            topInset <= 16
+          )
+        }, ptyId),
+      { message: 'collapsed chip should stay compact in the terminal pane corner' }
+    )
+    .toBe(true)
+}
+
+// Why: writing the screenshot to testInfo.outputPath() lands the file in the
+// per-test output dir that ships in the playwright-traces artifact uploaded by
+// .github/workflows/e2e.yml on failure. The `body` form of testInfo.attach
+// didn't reliably persist for the `list` reporter; the path round-trip does.
+async function captureAttachment(page: Page, testInfo: TestInfo, fileName: string): Promise<void> {
+  const dest = testInfo.outputPath(fileName)
+  await page.screenshot({ path: dest, fullPage: true })
+  await testInfo.attach(fileName, { path: dest, contentType: 'image/png' })
+}

From 69700466e91156fcf44b6b2ef2b72ecfb9904c56 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 11:57:22 -0700
Subject: [PATCH 49/82] fix: constrain floating terminal to titlebar (#1955)

---
 .../floating-terminal-panel-bounds.test.ts    | 61 +++++++++++++++++++
 .../floating-terminal-panel-bounds.ts         | 15 ++---
 2 files changed, 69 insertions(+), 7 deletions(-)
 create mode 100644 src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.test.ts

diff --git a/src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.test.ts b/src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.test.ts
new file mode 100644
index 00000000000..8cce47e3f26
--- /dev/null
+++ b/src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.test.ts
@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  TITLEBAR_SAFE_TOP,
+  clampFloatingTerminalBounds,
+  getDefaultFloatingTerminalBounds,
+  getMaximizedFloatingTerminalBounds
+} from './floating-terminal-panel-bounds'
+
+function stubViewport(width: number, height: number, userAgent: string): void {
+  vi.stubGlobal('window', { innerWidth: width, innerHeight: height })
+  vi.stubGlobal('navigator', { userAgent })
+}
+
+describe('floating terminal panel bounds', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('lets dragged panels touch the macOS titlebar without going above it', () => {
+    stubViewport(1200, 800, 'Macintosh')
+
+    const bounds = clampFloatingTerminalBounds({
+      left: 32,
+      top: 8,
+      width: 640,
+      height: 360
+    })
+
+    expect(bounds.top).toBe(TITLEBAR_SAFE_TOP)
+  })
+
+  it('keeps dragged panels below the renderer titlebar on other platforms', () => {
+    stubViewport(1200, 800, 'Windows NT')
+
+    const bounds = clampFloatingTerminalBounds({
+      left: 32,
+      top: 8,
+      width: 640,
+      height: 360
+    })
+
+    expect(bounds.top).toBe(TITLEBAR_SAFE_TOP)
+  })
+
+  it('maximizes below the renderer titlebar on non-mac platforms', () => {
+    stubViewport(1200, 800, 'Windows NT')
+
+    expect(getMaximizedFloatingTerminalBounds()).toEqual(
+      expect.objectContaining({
+        top: TITLEBAR_SAFE_TOP,
+        height: 800 - TITLEBAR_SAFE_TOP - 36
+      })
+    )
+  })
+
+  it('defaults at or below the titlebar on compact macOS windows', () => {
+    stubViewport(760, 420, 'Macintosh')
+
+    expect(getDefaultFloatingTerminalBounds().top).toBeGreaterThanOrEqual(TITLEBAR_SAFE_TOP)
+  })
+})
diff --git a/src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.ts b/src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.ts
index c9892cba06f..f083abe8fee 100644
--- a/src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.ts
+++ b/src/renderer/src/components/floating-terminal/floating-terminal-panel-bounds.ts
@@ -4,7 +4,7 @@ export const MIN_PANEL_WIDTH = 420
 export const MIN_PANEL_HEIGHT = 280
 export const MAXIMIZED_MARGIN = 12
 export const MAXIMIZED_BOTTOM_GAP = 36
-export const MAC_TITLEBAR_SAFE_TOP = 44
+export const TITLEBAR_SAFE_TOP = 36
 const DEFAULT_RIGHT_GAP = 24
 const DEFAULT_BOTTOM_GAP = 84
 
@@ -18,11 +18,14 @@ export type FloatingTerminalPanelBounds = {
 export function getDefaultFloatingTerminalBounds(): FloatingTerminalPanelBounds {
   const viewportWidth = typeof window === 'undefined' ? 1200 : window.innerWidth
   const viewportHeight = typeof window === 'undefined' ? 800 : window.innerHeight
+  // Why: the floating panel may touch the renderer titlebar, but must not
+  // overlap it or the native window controls above it.
+  const safeTop = TITLEBAR_SAFE_TOP
   const width = Math.min(DEFAULT_PANEL_WIDTH, Math.max(MIN_PANEL_WIDTH, viewportWidth - 48))
   const height = Math.min(DEFAULT_PANEL_HEIGHT, Math.max(MIN_PANEL_HEIGHT, viewportHeight - 96))
   return {
     left: Math.max(16, viewportWidth - width - DEFAULT_RIGHT_GAP),
-    top: Math.max(40, viewportHeight - height - DEFAULT_BOTTOM_GAP),
+    top: Math.max(safeTop, viewportHeight - height - DEFAULT_BOTTOM_GAP),
     width,
     height
   }
@@ -35,20 +38,18 @@ export function clampFloatingTerminalBounds(
     typeof window === 'undefined' ? bounds.left + bounds.width : window.innerWidth
   const viewportHeight =
     typeof window === 'undefined' ? bounds.top + bounds.height : window.innerHeight
+  const safeTop = TITLEBAR_SAFE_TOP
   return {
     ...bounds,
     left: Math.min(Math.max(8, bounds.left), Math.max(8, viewportWidth - 80)),
-    top: Math.min(Math.max(8, bounds.top), Math.max(8, viewportHeight - 80))
+    top: Math.min(Math.max(safeTop, bounds.top), Math.max(safeTop, viewportHeight - 80))
   }
 }
 
 export function getMaximizedFloatingTerminalBounds(): FloatingTerminalPanelBounds {
   const viewportWidth = typeof window === 'undefined' ? 1200 : window.innerWidth
   const viewportHeight = typeof window === 'undefined' ? 800 : window.innerHeight
-  const top =
-    typeof navigator !== 'undefined' && navigator.userAgent.includes('Mac')
-      ? MAC_TITLEBAR_SAFE_TOP
-      : MAXIMIZED_MARGIN
+  const top = TITLEBAR_SAFE_TOP
   return {
     left: MAXIMIZED_MARGIN,
     top,

From d66d559471556b626de36c5dd32ea040f248fcce Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 11:59:28 -0700
Subject: [PATCH 50/82] Add copy button to GitHub item dialog (#1954)

---
 .../src/components/GitHubItemDialog.tsx       | 142 ++++++++++++++----
 1 file changed, 110 insertions(+), 32 deletions(-)

diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index 0e735654c76..86d4d378933 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -15,10 +15,12 @@ import {
   ArrowRight,
   ArrowUp,
   Braces,
+  Check,
   ChevronDown,
   ChevronRight,
   CircleDashed,
   CircleDot,
+  Copy,
   ExternalLink,
   FileText,
   Folder,
@@ -301,6 +303,26 @@ function getStateTone(item: GitHubWorkItem): string {
   return 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-300'
 }
 
+function WorkItemStateBadge({
+  item,
+  className
+}: {
+  item: GitHubWorkItem
+  className?: string
+}): React.JSX.Element {
+  return (
+    <span
+      className={cn(
+        'inline-flex h-5 items-center rounded-full border px-2 text-[11px] font-medium',
+        getStateTone(item),
+        className
+      )}
+    >
+      {getStateLabel(item)}
+    </span>
+  )
+}
+
 function fileStatusTone(status: GitHubPRFile['status']): string {
   switch (status) {
     case 'added':
@@ -1429,11 +1451,13 @@ function ConversationTab({
     item.type === 'pr' ? (
       <div className="flex h-fit flex-col gap-3 xl:sticky xl:top-4">
         {startWorkspaceButton}
-        <aside className="rounded-lg border border-border/50 bg-background/30">
+        <aside className="rounded-lg border border-border/50 bg-card/50 shadow-xs">
           <div className="flex h-10 items-center gap-2 border-b border-border/50 px-3">
             <CircleDashed className="size-3.5 text-muted-foreground" />
             <span className="text-[13px] font-medium text-foreground">Checks</span>
-            <span className="text-[12px] text-muted-foreground">{(checks ?? []).length}</span>
+            <span className="ml-auto rounded-full border border-border/50 bg-muted/30 px-1.5 py-0.5 text-[11px] tabular-nums text-muted-foreground">
+              {(checks ?? []).length}
+            </span>
           </div>
           <ChecksTab checks={checks} loading={loading} />
         </aside>
@@ -1444,7 +1468,7 @@ function ConversationTab({
     <div
       key={comment.id}
       className={cn(
-        'rounded-lg border border-border/40 bg-background/30',
+        'rounded-lg border border-border/40 bg-card/50 shadow-xs',
         isReply && 'ml-6',
         comment.isResolved && PR_COMMENT_RESOLVED_CONTAINER_CLASS
       )}
@@ -1570,7 +1594,7 @@ function ConversationTab({
       <Accordion key={getPRCommentGroupId(group)} type="single" collapsible>
         <AccordionItem
           value={getPRCommentGroupId(group)}
-          className="rounded-lg border border-border/40 bg-background/20"
+          className="rounded-lg border border-border/40 bg-card/40"
         >
           <AccordionTrigger className="px-3 py-2 text-[13px] text-muted-foreground hover:bg-accent/30">
             <span className="min-w-0 truncate">
@@ -1589,17 +1613,17 @@ function ConversationTab({
   return (
     <div
       className={cn(
-        'grid gap-4 px-4 py-4',
-        item.type === 'pr' && 'xl:grid-cols-[minmax(0,2fr)_minmax(280px,1fr)]'
+        'grid gap-5 px-4 py-4',
+        item.type === 'pr' && 'xl:grid-cols-[minmax(0,1fr)_280px]'
       )}
     >
       <div className="flex min-w-0 flex-col gap-4">
-        <div className="rounded-lg border border-border/50 bg-background/40">
+        <div className="rounded-lg border border-border/50 bg-card/50 shadow-xs">
           <div className="flex items-center gap-2 border-b border-border/50 px-3 py-2 text-[12px] text-muted-foreground">
             <span className="font-medium text-foreground">{authorLabel}</span>
-            <span>· {formatRelativeTime(item.updatedAt)}</span>
+            <span>updated {formatRelativeTime(item.updatedAt)}</span>
           </div>
-          <div className="px-3 py-3 text-[14px] leading-relaxed text-foreground">
+          <div className="px-4 py-4 text-[14px] leading-relaxed text-foreground">
             {body.trim() ? (
               <CommentMarkdown
                 content={body}
@@ -1616,7 +1640,9 @@ function ConversationTab({
           <MessageSquare className="size-4 text-muted-foreground" />
           <span className="text-[13px] font-medium text-foreground">Comments</span>
           {comments.length > 0 && (
-            <span className="text-[12px] text-muted-foreground">{comments.length}</span>
+            <span className="rounded-full border border-border/50 bg-muted/30 px-1.5 py-0.5 text-[11px] tabular-nums text-muted-foreground">
+              {comments.length}
+            </span>
           )}
         </div>
 
@@ -1644,15 +1670,17 @@ function ConversationTab({
         )}
 
         {loading && comments.length === 0 ? (
-          <div className="flex items-center justify-center py-6">
+          <div className="flex items-center justify-center rounded-lg border border-dashed border-border/50 py-8">
             <LoaderCircle className="size-4 animate-spin text-muted-foreground" />
           </div>
         ) : comments.length === 0 ? (
-          <p className="text-[13px] text-muted-foreground">No comments yet.</p>
+          <div className="rounded-lg border border-dashed border-border/50 px-3 py-6 text-center text-[13px] text-muted-foreground">
+            No comments yet.
+          </div>
         ) : visibleComments.length === 0 ? (
-          <p className="text-[13px] text-muted-foreground">
+          <div className="rounded-lg border border-dashed border-border/50 px-3 py-6 text-center text-[13px] text-muted-foreground">
             {getPRCommentAudienceEmptyLabel(commentFilter)}
-          </p>
+          </div>
         ) : (
           <div className="flex flex-col gap-3">{visibleCommentGroups.map(renderCommentGroup)}</div>
         )}
@@ -2668,6 +2696,7 @@ export default function GitHubItemDialog({
   const [localState, setLocalState] = useState<GitHubWorkItem['state']>(workItem?.state ?? 'open')
   const [localLabels, setLocalLabels] = useState<string[]>(workItem?.labels ?? [])
   const [diffViewMode, setDiffViewMode] = useState<DiffViewMode>('flat')
+  const [linkCopied, setLinkCopied] = useState(false)
   const workItemId = workItem?.id
   const workItemState = workItem?.state
   const workItemLabels = workItem?.labels
@@ -2912,6 +2941,33 @@ export default function GitHubItemDialog({
   const files = details?.files ?? []
   const checks = details?.checks ?? []
 
+  useEffect(() => {
+    setLinkCopied(false)
+  }, [workItemId])
+
+  useEffect(() => {
+    if (!linkCopied) {
+      return
+    }
+    const handle = window.setTimeout(() => setLinkCopied(false), 1500)
+    return () => window.clearTimeout(handle)
+  }, [linkCopied])
+
+  const handleCopyWorkItemLink = useCallback(async (): Promise<void> => {
+    if (!workItem) {
+      return
+    }
+    try {
+      // Why: Electron's clipboard IPC is reliable even when browser clipboard
+      // APIs lose focus/activation inside nested overlay surfaces.
+      await window.api.ui.writeClipboardText(workItem.url)
+      setLinkCopied(true)
+      toast.success('GitHub link copied')
+    } catch {
+      toast.error('Failed to copy GitHub link')
+    }
+  }, [workItem])
+
   const appendOptimisticComment = useCallback(
     (comment: PRComment) => {
       // Why: skip refreshDetails() — gh api --cache 60s returns stale data
@@ -2974,22 +3030,26 @@ export default function GitHubItemDialog({
 
         {workItem && (
           <div className="flex h-full min-h-0 flex-col">
-            <div className="flex-none border-b border-border/60 px-4 py-3">
-              <div className="flex items-start gap-2">
-                <div className="min-w-0 flex-1">
-                  <span className="font-mono text-[12px] text-muted-foreground">
-                    #{workItem.number}
-                  </span>
-                  <h2 className="mt-1 flex items-start gap-2 text-[15px] font-semibold leading-tight text-foreground">
-                    <Icon className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
-                    <span className="min-w-0">{workItem.title}</span>
+            <div className="flex-none border-b border-border/60 bg-card/80 px-4 py-3 shadow-xs backdrop-blur supports-[backdrop-filter]:bg-card/70">
+              <div className="flex items-start gap-3">
+                <div className="mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-md border border-border/60 bg-muted/40 text-muted-foreground">
+                  <Icon className="size-4" />
+                </div>
+                <div className="min-w-0 flex-1 space-y-1">
+                  <div className="flex flex-wrap items-center gap-2 text-[11px] text-muted-foreground">
+                    <WorkItemStateBadge item={{ ...workItem, state: localState }} />
+                    <span className="font-mono">#{workItem.number}</span>
+                    <span>{workItem.type === 'pr' ? 'Pull request' : 'Issue'}</span>
+                  </div>
+                  <h2 className="text-[15px] font-semibold leading-snug text-foreground">
+                    {workItem.title}
                   </h2>
-                  <div className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 pl-6 text-[11px] text-muted-foreground">
+                  <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-[11px] text-muted-foreground">
                     <span>{workItem.author ?? 'unknown'}</span>
-                    <span>· {formatRelativeTime(workItem.updatedAt)}</span>
+                    <span>updated {formatRelativeTime(workItem.updatedAt)}</span>
                     {workItem.branchName && (
-                      <span className="font-mono text-[10px] text-muted-foreground/80">
-                        · {workItem.branchName}
+                      <span className="max-w-full truncate rounded-md border border-border/50 bg-muted/40 px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground">
+                        {workItem.branchName}
                       </span>
                     )}
                   </div>
@@ -3001,9 +3061,28 @@ export default function GitHubItemDialog({
                   <Tooltip>
                     <TooltipTrigger asChild>
                       <Button
+                        type="button"
                         variant="ghost"
-                        size="icon"
-                        className="size-7"
+                        size="icon-sm"
+                        onClick={() => void handleCopyWorkItemLink()}
+                        aria-label="Copy GitHub link"
+                      >
+                        {linkCopied ? (
+                          <Check className="size-4 text-emerald-500" />
+                        ) : (
+                          <Copy className="size-4" />
+                        )}
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent side="bottom" sideOffset={6}>
+                      {linkCopied ? 'Copied' : 'Copy GitHub link'}
+                    </TooltipContent>
+                  </Tooltip>
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="icon-sm"
                         onClick={() => window.api.shell.openUrl(workItem.url)}
                         aria-label="Open on GitHub"
                       >
@@ -3018,8 +3097,7 @@ export default function GitHubItemDialog({
                     <TooltipTrigger asChild>
                       <Button
                         variant="ghost"
-                        size="icon"
-                        className="size-7"
+                        size="icon-sm"
                         onClick={onClose}
                         aria-label="Close preview"
                       >
@@ -3073,7 +3151,7 @@ export default function GitHubItemDialog({
                 >
                   <TabsList
                     variant="line"
-                    className="mx-4 mt-2 justify-start gap-3 border-b border-border/60"
+                    className="mx-4 mt-2 justify-start gap-3 border-b border-border/60 bg-transparent"
                   >
                     <TabsTrigger value="conversation" className="px-2">
                       <MessageSquare className="size-3.5" />

From 6d8c835dd4ce95094e12cb02dba40fd832b3212d Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 12:05:56 -0700
Subject: [PATCH 51/82] perf(renderer): cache runtime tab projections by
 worktree (#1956)

---
 .../sync-runtime-graph-key-reuse.test.ts      | 57 +++++++++++++++
 .../src/runtime/sync-runtime-graph.test.ts    | 11 +--
 .../src/runtime/sync-runtime-graph.ts         | 73 ++++++++++++++-----
 3 files changed, 116 insertions(+), 25 deletions(-)

diff --git a/src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts b/src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts
index 4a5294521fd..388ea40eab7 100644
--- a/src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph-key-reuse.test.ts
@@ -97,6 +97,63 @@ describe('runtime mobile session sync key projection reuse', () => {
     expect(titleTickKey.editorDraftsProjection).toBe(baseKey.editorDraftsProjection)
     expect(runtimeMobileSessionSyncKeysEqual(baseKey, titleTickKey)).toBe(false)
   })
+
+  it('does not rebuild serialized projections when only activeTabId changes', () => {
+    const base = makeState({
+      tabsByWorktree: {
+        'wt-1': [{ id: 'term-1', title: 'Codex working', customTitle: null }]
+      } as unknown as AppState['tabsByWorktree']
+    })
+    const baseKey = getRuntimeMobileSessionSyncKey(base)
+    const activated = makeState({
+      ...base,
+      activeTabId: 'term-1'
+    })
+
+    const stringifySpy = vi.spyOn(JSON, 'stringify')
+    stringifySpy.mockClear()
+    const activatedKey = getRuntimeMobileSessionSyncKey(activated, base, baseKey)
+
+    expect(stringifySpy).not.toHaveBeenCalled()
+    expect(activatedKey.tabsProjection).toBe(baseKey.tabsProjection)
+    expect(activatedKey.openFilesProjection).toBe(baseKey.openFilesProjection)
+    expect(activatedKey.editorDraftsProjection).toBe(baseKey.editorDraftsProjection)
+    expect(runtimeMobileSessionSyncKeysEqual(baseKey, activatedKey)).toBe(false)
+  })
+
+  it('reuses unchanged worktree tab projections when one worktree title changes', () => {
+    const unchangedTitle = vi.fn(() => 'Unchanged agent')
+    const unchangedTab = {
+      id: 'term-unchanged',
+      customTitle: null,
+      get title() {
+        return unchangedTitle()
+      }
+    }
+    const base = makeState({
+      tabsByWorktree: {
+        'wt-1': [{ id: 'term-1', title: 'Codex working', customTitle: null }],
+        'wt-2': [unchangedTab]
+      } as unknown as AppState['tabsByWorktree']
+    })
+    const baseKey = getRuntimeMobileSessionSyncKey(base)
+    expect(unchangedTitle).toHaveBeenCalled()
+    unchangedTitle.mockClear()
+
+    const titleTick = makeState({
+      ...base,
+      tabsByWorktree: {
+        ...base.tabsByWorktree,
+        'wt-1': [{ id: 'term-1', title: 'Codex spinner frame', customTitle: null }]
+      } as unknown as AppState['tabsByWorktree']
+    })
+
+    const titleTickKey = getRuntimeMobileSessionSyncKey(titleTick, base, baseKey)
+
+    expect(unchangedTitle).not.toHaveBeenCalled()
+    expect(titleTickKey.tabsProjection).not.toBe(baseKey.tabsProjection)
+    expect(runtimeMobileSessionSyncKeysEqual(baseKey, titleTickKey)).toBe(false)
+  })
 })
 
 describe('mobile session snapshot reuse', () => {
diff --git a/src/renderer/src/runtime/sync-runtime-graph.test.ts b/src/renderer/src/runtime/sync-runtime-graph.test.ts
index 8ed36dcb263..f7ad3303dc5 100644
--- a/src/renderer/src/runtime/sync-runtime-graph.test.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph.test.ts
@@ -25,11 +25,12 @@ function makeState(overrides: Partial<AppState> = {}): AppState {
 // Why: the comparator at `runtimeMobileSessionSyncKeysEqual` checks
 // `terminalLayoutsByTabId`, `runtimePaneTitlesByTabId`, `groupsByWorktree`,
 // `activeGroupIdByWorktree`, `unifiedTabsByWorktree`, `tabBarOrderByWorktree`,
-// and `activeFileIdByWorktree` by reference. `makeState`'s defaults allocate
-// fresh `{}` for each, so two unrelated `makeState({...})` calls trivially
-// diverge. Tests that want to isolate a single field must share every other
-// reference-checked map between the two states; this factory produces one
-// `Partial<AppState>` whose fields can be spread into both `makeState` calls.
+// and `activeFileIdByWorktree` by reference, and checks `activeTabId` by scalar
+// equality. `makeState`'s defaults allocate fresh `{}` for each map, so two
+// unrelated `makeState({...})` calls trivially diverge. Tests that want to
+// isolate a single field must share every other reference-checked map between
+// the two states; this factory produces one `Partial<AppState>` whose fields
+// can be spread into both `makeState` calls.
 function makeSharedOverrides(): Partial<AppState> {
   return {
     tabsByWorktree: {},
diff --git a/src/renderer/src/runtime/sync-runtime-graph.ts b/src/renderer/src/runtime/sync-runtime-graph.ts
index 557dd1052bc..47e83281e3a 100644
--- a/src/renderer/src/runtime/sync-runtime-graph.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph.ts
@@ -30,6 +30,16 @@ type OpenFileIndexes = {
   byWorktreeAndId: OpenFileByWorktreeAndId
   idsByWorktree: Map<string, string[]>
 }
+type TabsProjectionCacheEntry = {
+  tabs: NonNullable<AppState['tabsByWorktree'][string]>
+  worktreeIdJson: string
+  projection: string
+}
+type TabsProjectionCache = {
+  source: AppState['tabsByWorktree']
+  entries: Map<string, TabsProjectionCacheEntry>
+  projection: string
+}
 
 const registeredTabs = new Map<string, RegisteredTerminalTab>()
 // Why: track when each tab was registered so we can suppress the "no live
@@ -43,6 +53,7 @@ let syncScheduled = false
 let syncEnabled = false
 let getStoreState: (() => AppState) | null = null
 let mobileSessionSnapshotVersion = 0
+let cachedTabsProjection: TabsProjectionCache | null = null
 let cachedOpenFileIndexesSource: AppState['openFiles'] | null = null
 let cachedOpenFileIndexes: OpenFileIndexes | null = null
 let cachedEditorDraftsSource: AppState['editorDrafts'] | null = null
@@ -117,10 +128,11 @@ export type RuntimeMobileSessionSyncKey = {
   tabBarOrderByWorktree: AppState['tabBarOrderByWorktree']
   activeFileId: AppState['activeFileId']
   activeFileIdByWorktree: AppState['activeFileIdByWorktree']
+  activeTabId: AppState['activeTabId']
   // Why: these projections still need value-level inspection because the
   // underlying references churn even when the mobile-relevant shape is
-  // unchanged (`tabsByWorktree` reallocates on every OSC title frame; the
-  // active-tab marker depends on `activeTabId`). Pre-serialize them once.
+  // unchanged (`tabsByWorktree` reallocates on every OSC title frame).
+  // Pre-serialize them once.
   tabsProjection: string
   openFilesProjection: string
   editorDraftsProjection: string
@@ -142,15 +154,14 @@ export function getRuntimeMobileSessionSyncKey(
     tabBarOrderByWorktree: state.tabBarOrderByWorktree,
     activeFileId: state.activeFileId,
     activeFileIdByWorktree: state.activeFileIdByWorktree,
+    activeTabId: state.activeTabId,
     // Why: background agent title ticks can change runtimePaneTitlesByTabId
     // many times per second while the user types elsewhere. Reuse unchanged
     // projections so those ticks do not rescan all tabs, files, and drafts.
     tabsProjection:
-      canReusePrevious &&
-      state.tabsByWorktree === previousState.tabsByWorktree &&
-      state.activeTabId === previousState.activeTabId
+      canReusePrevious && state.tabsByWorktree === previousState.tabsByWorktree
         ? previousKey.tabsProjection
-        : buildRuntimeMobileTabsProjection(state),
+        : buildRuntimeMobileTabsProjection(state.tabsByWorktree),
     openFilesProjection:
       canReusePrevious && state.openFiles === previousState.openFiles
         ? previousKey.openFilesProjection
@@ -162,20 +173,41 @@ export function getRuntimeMobileSessionSyncKey(
   }
 }
 
-function buildRuntimeMobileTabsProjection(state: AppState): string {
-  return JSON.stringify(
-    Object.fromEntries(
-      Object.entries(state.tabsByWorktree).map(([worktreeId, tabs]) => [
-        worktreeId,
-        tabs.map((tab) => ({
-          id: tab.id,
-          title: tab.title,
-          customTitle: tab.customTitle,
-          active: state.activeTabId === tab.id
-        }))
-      ])
-    )
-  )
+function buildRuntimeMobileTabsProjection(tabsByWorktree: AppState['tabsByWorktree']): string {
+  if (cachedTabsProjection?.source === tabsByWorktree) {
+    return cachedTabsProjection.projection
+  }
+
+  const previousEntries = cachedTabsProjection?.entries
+  const entries = new Map<string, TabsProjectionCacheEntry>()
+  const parts: string[] = []
+
+  for (const [worktreeId, tabs] of Object.entries(tabsByWorktree)) {
+    const previous = previousEntries?.get(worktreeId)
+    const entry =
+      previous?.tabs === tabs
+        ? previous
+        : {
+            tabs,
+            worktreeIdJson: previous?.worktreeIdJson ?? JSON.stringify(worktreeId),
+            projection: JSON.stringify(
+              tabs.map((tab) => ({
+                id: tab.id,
+                title: tab.title,
+                customTitle: tab.customTitle
+              }))
+            )
+          }
+    entries.set(worktreeId, entry)
+    parts.push(`${entry.worktreeIdJson}:${entry.projection}`)
+  }
+
+  cachedTabsProjection = {
+    source: tabsByWorktree,
+    entries,
+    projection: `{${parts.join(',')}}`
+  }
+  return cachedTabsProjection.projection
 }
 
 function buildRuntimeMobileOpenFilesProjection(openFiles: AppState['openFiles']): string {
@@ -215,6 +247,7 @@ export function runtimeMobileSessionSyncKeysEqual(
     a.tabBarOrderByWorktree === b.tabBarOrderByWorktree &&
     a.activeFileId === b.activeFileId &&
     a.activeFileIdByWorktree === b.activeFileIdByWorktree &&
+    a.activeTabId === b.activeTabId &&
     a.tabsProjection === b.tabsProjection &&
     a.openFilesProjection === b.openFilesProjection &&
     a.editorDraftsProjection === b.editorDraftsProjection

From 4c475a1ce116e19f845bd35f692097915627123b Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 12:06:06 -0700
Subject: [PATCH 52/82] Add Computer Use promo to Browser settings

References docs/browser-computer-use-promo.md.
---
 docs/browser-computer-use-promo.md            | 64 +++++++++++++++++++
 .../src/components/settings/BrowserPane.tsx   | 14 +++-
 .../components/settings/BrowserUsePane.tsx    | 31 ++++++++-
 .../src/components/settings/Settings.tsx      | 27 +++++++-
 .../components/settings/browser-use-search.ts |  9 ++-
 5 files changed, 138 insertions(+), 7 deletions(-)
 create mode 100644 docs/browser-computer-use-promo.md

diff --git a/docs/browser-computer-use-promo.md b/docs/browser-computer-use-promo.md
new file mode 100644
index 00000000000..3d735efbcd3
--- /dev/null
+++ b/docs/browser-computer-use-promo.md
@@ -0,0 +1,64 @@
+# Browser Computer Use Promo
+
+## Problem
+Browser Use setup is in **Browser** settings, while **Computer Use** is a separate section. Users are not told that Computer Use can control already-authenticated desktop apps (including system browsers), which can be lower-friction than cookie import for some tasks.
+
+## Current constraints (code-verified)
+- `BrowserUseSetup` currently accepts only `onConfigureMoreBrowsers?: () => void` (`BrowserUsePane.tsx`).
+- `BrowserPane` is desktop-only because the entire Browser section is gated by `showDesktopOnlySettings` in `Settings.tsx`.
+- Browser Use toggle and “skill installed” are persisted in `localStorage` keys (`BROWSER_USE_ENABLED_STORAGE_KEY`, `BROWSER_USE_SKILL_INSTALLED_STORAGE_KEY`), but each window keeps its own React state copy after initial read (no `storage` event sync).
+- Computer Use section id is `computer-use` (`SettingsSection id`).
+- Settings search filters section mounting; filtered sections are absent from the DOM.
+- Canonical jump behavior already exists in `Settings.tsx` via `pendingNavSectionRef`, `pendingScrollTargetRef`, `scrollSectionIntoView`, and `flashSectionHighlight`.
+- `ComputerUsePane` always renders the skill install block; macOS permission controls render only when platform resolves to macOS.
+
+## Goal
+Add a compact promo inside expanded Browser Use that links to Computer Use and uses the existing Settings pending-nav jump path.
+
+## Non-goals
+- No Computer Use controls duplicated inside Browser.
+- No Browser Use step semantics changes.
+- No Computer Use backend/API changes.
+
+## Implementation
+1. Add `onOpenComputerUse?: () => void` to `BrowserUseSetupProps`.
+2. Thread that prop through `BrowserPaneProps` and pass it from `BrowserPane` to `BrowserUseSetup`.
+3. In `Settings.tsx`, pass `onOpenComputerUse` into `BrowserPane` that:
+- sets `pendingNavSectionRef.current = 'computer-use'`
+- sets `pendingScrollTargetRef.current = 'computer-use'`
+- clears search only if non-empty (`setSettingsSearchQuery('')`) so the section can mount
+4. Rely on existing `visibleNavSections` effect to execute scroll + flash and clear pending refs.
+5. Render promo only when Browser Use is enabled/expanded and callback exists.
+6. Place promo at top of expanded Browser Use card, before Step 1.
+7. Style with existing tokens/primitives only (`rounded-xl border border-border/60 bg-card/50`, existing `Button` variants, `MousePointerClick` icon).
+
+Do not implement ad-hoc local scroll logic in `BrowserUsePane` for this jump; keep section navigation centralized in `Settings.tsx`.
+
+## Copy constraints
+- State capability, not guarantee: Computer Use can control local apps and may use existing logged-in sessions where applicable.
+- State prerequisites: Computer Use skill install is required; macOS permissions are additionally required on macOS.
+- Position as an alternative path, not a replacement for Browser Use cookie import.
+
+## Edge cases to handle
+- Active search currently filters out `computer-use`.
+- Repeated CTA clicks before prior pending jump resolves (last click should remain idempotent).
+- Browser Use collapsed/disabled (no promo).
+- Multi-window state drift: localStorage-backed Browser Use UI state is not live-synced across open windows.
+- Non-mac platforms: CTA remains valid (skill flow still exists even without mac permission rows).
+- Web client: Browser section is absent, so promo path is unreachable by design.
+
+## Search indexing
+Update `BROWSER_USE_PANE_SEARCH_ENTRIES` to add intent terms for this promo while keeping existing terms:
+- `computer use`
+- `system browser`
+- `existing session`
+- `authenticated browser`
+- `chrome profile`
+- `edge profile`
+- `arc profile`
+
+## Acceptance criteria
+- Expanded Browser Use shows promo + CTA.
+- CTA lands on `computer-use`, flashes section highlight, and works when search filters are active.
+- No Browser Use step behavior changes.
+- No duplicated Computer Use controls in Browser.
diff --git a/src/renderer/src/components/settings/BrowserPane.tsx b/src/renderer/src/components/settings/BrowserPane.tsx
index 2d7d9ef7bd7..adb19168059 100644
--- a/src/renderer/src/components/settings/BrowserPane.tsx
+++ b/src/renderer/src/components/settings/BrowserPane.tsx
@@ -30,9 +30,14 @@ export const BROWSER_PANE_SEARCH_ENTRIES = [
 type BrowserPaneProps = {
   settings: GlobalSettings
   updateSettings: (updates: Partial<GlobalSettings>) => void
+  onOpenComputerUse?: () => void
 }
 
-export function BrowserPane({ settings, updateSettings }: BrowserPaneProps): React.JSX.Element {
+export function BrowserPane({
+  settings,
+  updateSettings,
+  onOpenComputerUse
+}: BrowserPaneProps): React.JSX.Element {
   const searchQuery = useAppStore((s) => s.settingsSearchQuery)
   const browserDefaultUrl = useAppStore((s) => s.browserDefaultUrl)
   const setBrowserDefaultUrl = useAppStore((s) => s.setBrowserDefaultUrl)
@@ -87,7 +92,12 @@ export function BrowserPane({ settings, updateSettings }: BrowserPaneProps): Rea
 
   return (
     <div className="space-y-6">
-      {showBrowserUse ? <BrowserUseSetup onConfigureMoreBrowsers={scrollToSessionCookies} /> : null}
+      {showBrowserUse ? (
+        <BrowserUseSetup
+          onConfigureMoreBrowsers={scrollToSessionCookies}
+          onOpenComputerUse={onOpenComputerUse}
+        />
+      ) : null}
 
       {showHomePage ? (
         <SearchableSetting
diff --git a/src/renderer/src/components/settings/BrowserUsePane.tsx b/src/renderer/src/components/settings/BrowserUsePane.tsx
index 86412cb88d9..056e7932aec 100644
--- a/src/renderer/src/components/settings/BrowserUsePane.tsx
+++ b/src/renderer/src/components/settings/BrowserUsePane.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import { Import, Loader2 } from 'lucide-react'
+import { Import, Loader2, MousePointerClick } from 'lucide-react'
 import { toast } from 'sonner'
 import type { CliInstallStatus } from '../../../../shared/cli-install-types'
 import { ORCA_CLI_SKILL_INSTALL_COMMAND } from '@/lib/agent-feature-install-commands'
@@ -31,10 +31,12 @@ import { BrowserUseSkillStep } from './BrowserUseSkillStep'
 
 type BrowserUseSetupProps = {
   onConfigureMoreBrowsers?: () => void
+  onOpenComputerUse?: () => void
 }
 
 export function BrowserUseSetup({
-  onConfigureMoreBrowsers
+  onConfigureMoreBrowsers,
+  onOpenComputerUse
 }: BrowserUseSetupProps = {}): React.JSX.Element {
   const searchQuery = useAppStore((s) => s.settingsSearchQuery)
   const browserSessionProfiles = useAppStore((s) => s.browserSessionProfiles)
@@ -222,6 +224,31 @@ export function BrowserUseSetup({
         </div>
       </div>
 
+      {onOpenComputerUse ? (
+        <div className="rounded-xl border border-border/60 bg-card/50 p-4">
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-start">
+            <div className="min-w-0 flex-1 space-y-1">
+              <p className="text-sm font-medium">Use an existing browser session</p>
+              <p className="text-xs text-muted-foreground">
+                If cookie import is not the right fit, Computer Use can control local apps and may
+                use existing logged-in browser sessions where applicable. Install the Computer Use
+                skill; macOS also requires privacy permissions.
+              </p>
+            </div>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={onOpenComputerUse}
+              className="shrink-0 gap-1.5 self-start"
+            >
+              <MousePointerClick className="size-3.5" />
+              Open Computer Use
+            </Button>
+          </div>
+        </div>
+      ) : null}
+
       {showStep1 ? (
         <SearchableSetting
           title="Enable Orca CLI"
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 53cdf9f05ff..d6eb79a6dbe 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -240,6 +240,7 @@ function Settings(): React.JSX.Element {
     Array.from(new Set([DEFAULT_APP_FONT_FAMILY, ...getFallbackTerminalFonts()]))
   )
   const [activeSectionId, setActiveSectionId] = useState('general')
+  const [pendingNavRequestTick, setPendingNavRequestTick] = useState(0)
   // Why: the hidden-experimental group is an unlock — Shift-clicking the
   // Experimental sidebar entry reveals it for the remainder of the session.
   // Not persisted on purpose: it's a power-user affordance we don't want to
@@ -628,7 +629,13 @@ function Settings(): React.JSX.Element {
     if (!visibleIds.has(activeSectionId) && visibleNavSections.length > 0) {
       setActiveSectionId(getFallbackVisibleSection(visibleNavSections)?.id ?? activeSectionId)
     }
-  }, [activeSectionId, setSettingsSearchQuery, settingsSearchQuery, visibleNavSections])
+  }, [
+    activeSectionId,
+    pendingNavRequestTick,
+    setSettingsSearchQuery,
+    settingsSearchQuery,
+    visibleNavSections
+  ])
 
   useEffect(() => {
     const container = contentScrollRef.current
@@ -720,6 +727,18 @@ function Settings(): React.JSX.Element {
     []
   )
 
+  const openComputerUseFromBrowser = useCallback(() => {
+    pendingNavSectionRef.current = 'computer-use'
+    pendingScrollTargetRef.current = 'computer-use'
+    if (settingsSearchQuery !== '') {
+      setSettingsSearchQuery('')
+      return
+    }
+    // Why: the pending section refs do not schedule a render by themselves.
+    // When search is already clear, this reruns the centralized jump effect.
+    setPendingNavRequestTick((tick) => tick + 1)
+  }, [setSettingsSearchQuery, settingsSearchQuery])
+
   if (!settings) {
     return (
       <div className="flex flex-1 items-center justify-center text-muted-foreground">
@@ -866,7 +885,11 @@ function Settings(): React.JSX.Element {
                       description="Home page, link routing, and session cookies."
                       searchEntries={BROWSER_PANE_SEARCH_ENTRIES}
                     >
-                      <BrowserPane settings={settings} updateSettings={updateSettings} />
+                      <BrowserPane
+                        settings={settings}
+                        updateSettings={updateSettings}
+                        onOpenComputerUse={openComputerUseFromBrowser}
+                      />
                     </SettingsSection>
 
                     <SettingsSection
diff --git a/src/renderer/src/components/settings/browser-use-search.ts b/src/renderer/src/components/settings/browser-use-search.ts
index 1574ae34178..08bd0d5ada6 100644
--- a/src/renderer/src/components/settings/browser-use-search.ts
+++ b/src/renderer/src/components/settings/browser-use-search.ts
@@ -33,7 +33,14 @@ export const BROWSER_USE_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
       'auth',
       'chrome',
       'edge',
-      'arc'
+      'arc',
+      'computer use',
+      'system browser',
+      'existing session',
+      'authenticated browser',
+      'chrome profile',
+      'edge profile',
+      'arc profile'
     ]
   }
 ]

From a92da4b1a2514fdfcc62dc5d5fdd2b6dd90c8e7f Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 12:07:14 -0700
Subject: [PATCH 53/82] feat: double click floating terminal titlebar (#1957)

---
 .../FloatingTerminalPanel.tsx                 | 23 ++++++++++++++-----
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
index 0d0ffe18c89..be9bfa9e2e2 100644
--- a/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
@@ -30,6 +30,13 @@ type FloatingTerminalPanelProps = {
   onOpenChange: (open: boolean) => void
 }
 
+const FLOATING_TERMINAL_NO_DRAG_SELECTOR =
+  'button,input,textarea,select,[role="menuitem"],[data-testid="sortable-tab"],[data-floating-terminal-no-drag]'
+
+function isFloatingTerminalDragTarget(target: EventTarget): boolean {
+  return !(target instanceof HTMLElement && target.closest(FLOATING_TERMINAL_NO_DRAG_SELECTOR))
+}
+
 export function FloatingTerminalPanel({
   open,
   onOpenChange
@@ -211,12 +218,7 @@ export function FloatingTerminalPanel({
       return
     }
     const target = event.target
-    if (
-      target instanceof HTMLElement &&
-      target.closest(
-        'button,input,textarea,select,[role="menuitem"],[data-testid="sortable-tab"],[data-floating-terminal-no-drag]'
-      )
-    ) {
+    if (!isFloatingTerminalDragTarget(target)) {
       return
     }
     dragRef.current = {
@@ -249,6 +251,14 @@ export function FloatingTerminalPanel({
     }
   }
 
+  const handleTitlebarDoubleClick = (event: React.MouseEvent<HTMLDivElement>): void => {
+    if (event.button !== 0 || !isFloatingTerminalDragTarget(event.target)) {
+      return
+    }
+    event.preventDefault()
+    toggleMaximized()
+  }
+
   const dismissOrchestrationSetup = useCallback(() => {
     localStorage.setItem(ORCHESTRATION_SETUP_DISMISSED_STORAGE_KEY, '1')
     setShowOrchestrationSetup(false)
@@ -285,6 +295,7 @@ export function FloatingTerminalPanel({
           onPointerMove={handleDragMove}
           onPointerUp={handleDragEnd}
           onPointerCancel={handleDragEnd}
+          onDoubleClick={handleTitlebarDoubleClick}
         >
           <div className="flex h-full min-w-0 flex-1">
             <TabBar

From 67c67cd6fa3203e7081a7acc7976d44dee21bbe2 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 12:07:33 -0700
Subject: [PATCH 54/82] Include disconnected SSH workspaces

---
 src/main/ipc/worktrees.test.ts | 298 +++++++++++++++++++++++++++++++++
 src/main/ipc/worktrees.ts      | 104 ++++++++++--
 2 files changed, 392 insertions(+), 10 deletions(-)

diff --git a/src/main/ipc/worktrees.test.ts b/src/main/ipc/worktrees.test.ts
index ab70a164fef..1b053b54004 100644
--- a/src/main/ipc/worktrees.test.ts
+++ b/src/main/ipc/worktrees.test.ts
@@ -153,6 +153,7 @@ describe('registerWorktreeHandlers', () => {
     getSparsePresets: vi.fn(),
     getSettings: vi.fn(),
     getWorktreeMeta: vi.fn(),
+    getAllWorktreeMeta: vi.fn(),
     setWorktreeMeta: vi.fn(),
     removeWorktreeMeta: vi.fn()
   }
@@ -201,6 +202,7 @@ describe('registerWorktreeHandlers', () => {
       store.getSparsePresets,
       store.getSettings,
       store.getWorktreeMeta,
+      store.getAllWorktreeMeta,
       store.setWorktreeMeta,
       store.removeWorktreeMeta,
       killAllProcessesForWorktreeMock,
@@ -240,6 +242,7 @@ describe('registerWorktreeHandlers', () => {
       workspaceDir: '/workspace'
     })
     store.getWorktreeMeta.mockReturnValue(undefined)
+    store.getAllWorktreeMeta.mockReturnValue({})
     store.setWorktreeMeta.mockReturnValue({})
     getGitUsernameMock.mockReturnValue('')
     getDefaultBaseRefMock.mockReturnValue('origin/main')
@@ -325,6 +328,22 @@ describe('registerWorktreeHandlers', () => {
     ])
   }
 
+  function makeWorktreeMeta(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+    return {
+      displayName: '',
+      comment: '',
+      linkedIssue: null,
+      linkedPR: null,
+      linkedLinearIssue: null,
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 0,
+      ...overrides
+    }
+  }
+
   it('auto-suffixes the branch name when the first choice collides with a remote branch', async () => {
     // Why: new-workspace flow should silently try improve-dashboard-2, -3, ...
     // rather than failing and forcing the user back to the name picker.
@@ -744,6 +763,285 @@ describe('registerWorktreeHandlers', () => {
     expect(listWorktreesMock).not.toHaveBeenCalled()
   })
 
+  it('returns reconstructed rows when an SSH provider is unavailable', async () => {
+    const repo = {
+      id: 'repo-ssh',
+      path: '/remote/repo',
+      displayName: 'SSH Repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    store.getRepo.mockReturnValue(repo)
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-ssh::/remote/feature-wt': makeWorktreeMeta({
+        displayName: 'Feature workspace',
+        comment: 'persisted comment',
+        linkedIssue: 123,
+        linkedPR: 456,
+        linkedLinearIssue: 'LIN-123',
+        isArchived: true,
+        isUnread: true,
+        isPinned: true,
+        sortOrder: 7,
+        lastActivityAt: 42,
+        workspaceStatus: 'blocked',
+        diffComments: [
+          {
+            id: 'comment-1',
+            worktreeId: 'repo-ssh::/remote/feature-wt',
+            filePath: 'src/app.ts',
+            lineNumber: 10,
+            body: 'check this',
+            createdAt: 1,
+            updatedAt: 1
+          }
+        ],
+        sparseDirectories: ['packages/web'],
+        sparseBaseRef: 'origin/main',
+        sparsePresetId: 'preset-1'
+      })
+    })
+
+    const listed = await handlers['worktrees:list'](null, { repoId: 'repo-ssh' })
+
+    expect(listed).toEqual([
+      expect.objectContaining({
+        id: 'repo-ssh::/remote/feature-wt',
+        repoId: 'repo-ssh',
+        path: '/remote/feature-wt',
+        head: '',
+        branch: '',
+        isBare: false,
+        isMainWorktree: false,
+        isSparse: true,
+        displayName: 'Feature workspace',
+        comment: 'persisted comment',
+        linkedIssue: 123,
+        linkedPR: 456,
+        linkedLinearIssue: 'LIN-123',
+        isArchived: true,
+        isUnread: true,
+        isPinned: true,
+        sortOrder: 7,
+        lastActivityAt: 42,
+        workspaceStatus: 'blocked',
+        sparseDirectories: ['packages/web'],
+        sparseBaseRef: 'origin/main',
+        sparsePresetId: 'preset-1',
+        diffComments: [
+          expect.objectContaining({
+            id: 'comment-1',
+            filePath: 'src/app.ts'
+          })
+        ]
+      })
+    ])
+    expect(store.getWorktreeMeta).not.toHaveBeenCalled()
+    expect(store.setWorktreeMeta).not.toHaveBeenCalled()
+  })
+
+  it('falls back to reconstructed SSH rows when provider listing throws', async () => {
+    const repo = {
+      id: 'repo-ssh',
+      path: '/remote/repo',
+      displayName: 'SSH Repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    const provider = {
+      listWorktrees: vi.fn().mockRejectedValue(new Error('connection lost'))
+    }
+    store.getRepo.mockReturnValue(repo)
+    getSshGitProviderMock.mockReturnValue(provider)
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-ssh::/remote/feature-wt': makeWorktreeMeta({
+        displayName: 'Feature workspace',
+        lastActivityAt: 42
+      })
+    })
+
+    const listed = await handlers['worktrees:list'](null, { repoId: 'repo-ssh' })
+
+    expect(provider.listWorktrees).toHaveBeenCalledWith('/remote/repo')
+    expect(listed).toEqual([
+      expect.objectContaining({
+        id: 'repo-ssh::/remote/feature-wt',
+        displayName: 'Feature workspace',
+        lastActivityAt: 42
+      })
+    ])
+  })
+
+  it('keeps local listing failure behavior as an empty list', async () => {
+    listWorktreesMock.mockRejectedValue(new Error('filesystem denied'))
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-1::/workspace/feature-wt': makeWorktreeMeta({
+        displayName: 'Should not appear'
+      })
+    })
+
+    const listed = await handlers['worktrees:list'](null, { repoId: 'repo-1' })
+
+    expect(listed).toEqual([])
+    expect(store.getAllWorktreeMeta).not.toHaveBeenCalled()
+  })
+
+  it('ignores malformed metadata keys during SSH fallback', async () => {
+    const repo = {
+      id: 'repo-ssh',
+      path: '/remote/repo',
+      displayName: 'SSH Repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    store.getRepo.mockReturnValue(repo)
+    store.getAllWorktreeMeta.mockReturnValue({
+      'not-a-worktree-id': makeWorktreeMeta({ displayName: 'Bad row' }),
+      'repo-ssh::/remote/feature-wt': makeWorktreeMeta({ displayName: 'Good row' })
+    })
+
+    const listed = await handlers['worktrees:list'](null, { repoId: 'repo-ssh' })
+
+    expect(listed).toEqual([
+      expect.objectContaining({
+        id: 'repo-ssh::/remote/feature-wt',
+        displayName: 'Good row'
+      })
+    ])
+  })
+
+  it('does not use the repo display name for sparse fallback rows with empty branches', async () => {
+    const repo = {
+      id: 'repo-ssh',
+      path: '/remote/repo',
+      displayName: 'SSH Repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    store.getRepo.mockReturnValue(repo)
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-ssh::/remote/custom-name': makeWorktreeMeta({
+        sparseDirectories: ['packages/web']
+      })
+    })
+
+    const listed = (await handlers['worktrees:list'](null, { repoId: 'repo-ssh' })) as {
+      displayName: string
+      isSparse?: boolean
+      sparseDirectories?: string[]
+    }[]
+
+    expect(listed[0]).toMatchObject({
+      displayName: 'custom-name',
+      isSparse: true,
+      sparseDirectories: ['packages/web']
+    })
+  })
+
+  it('uses path equivalence to mark the reconstructed SSH main worktree', async () => {
+    const repo = {
+      id: 'repo-ssh',
+      path: 'C:\\Remote\\Repo',
+      displayName: 'SSH Repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    store.getRepo.mockReturnValue(repo)
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-ssh::c:/remote/repo': makeWorktreeMeta()
+    })
+
+    const listed = (await handlers['worktrees:list'](null, { repoId: 'repo-ssh' })) as {
+      isMainWorktree: boolean
+    }[]
+
+    expect(listed[0].isMainWorktree).toBe(true)
+  })
+
+  it('includes SSH fallback rows in listAll alongside healthy local rows', async () => {
+    const sshRepo = {
+      id: 'repo-ssh',
+      path: '/remote/repo',
+      displayName: 'SSH Repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    const localRepo = {
+      id: 'repo-local',
+      path: '/workspace/local',
+      displayName: 'Local Repo',
+      badgeColor: '#111',
+      addedAt: 0
+    }
+    store.getRepos.mockReturnValue([sshRepo, localRepo])
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-ssh::/remote/feature-wt': makeWorktreeMeta({ displayName: 'Remote cached' })
+    })
+    listWorktreesMock.mockResolvedValue([
+      {
+        path: '/workspace/local',
+        head: 'abc123',
+        branch: 'refs/heads/main',
+        isBare: false,
+        isMainWorktree: true
+      }
+    ])
+
+    const listed = await handlers['worktrees:listAll'](null, undefined)
+
+    expect(store.getAllWorktreeMeta).toHaveBeenCalledTimes(1)
+    expect(listed).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: 'repo-ssh::/remote/feature-wt',
+          displayName: 'Remote cached'
+        }),
+        expect.objectContaining({
+          id: 'repo-local::/workspace/local',
+          branch: 'refs/heads/main'
+        })
+      ])
+    )
+  })
+
+  it('snapshots SSH fallback metadata once for listAll', async () => {
+    const sshRepoA = {
+      id: 'repo-ssh-a',
+      path: '/remote/a',
+      displayName: 'SSH A',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    const sshRepoB = {
+      id: 'repo-ssh-b',
+      path: '/remote/b',
+      displayName: 'SSH B',
+      badgeColor: '#111',
+      addedAt: 0,
+      connectionId: 'conn-2'
+    }
+    store.getRepos.mockReturnValue([sshRepoA, sshRepoB])
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-ssh-a::/remote/a/one': makeWorktreeMeta({ displayName: 'One' }),
+      'repo-ssh-b::/remote/b/two': makeWorktreeMeta({ displayName: 'Two' })
+    })
+
+    const listed = await handlers['worktrees:listAll'](null, undefined)
+
+    expect(store.getAllWorktreeMeta).toHaveBeenCalledTimes(1)
+    expect(listed).toEqual([
+      expect.objectContaining({ id: 'repo-ssh-a::/remote/a/one' }),
+      expect.objectContaining({ id: 'repo-ssh-b::/remote/b/two' })
+    ])
+  })
+
   it('stamps lastActivityAt on first discovery so newly-added worktrees sort to the top of Recent', async () => {
     // Why: a worktree that exists on disk but has no persisted WorktreeMeta
     // (e.g. a folder repo just added, or a pre-existing worktree in a
diff --git a/src/main/ipc/worktrees.ts b/src/main/ipc/worktrees.ts
index 70b749c56e2..91390b7c108 100644
--- a/src/main/ipc/worktrees.ts
+++ b/src/main/ipc/worktrees.ts
@@ -34,6 +34,7 @@ import {
 import {
   mergeWorktree,
   parseWorktreeId,
+  areWorktreePathsEqual,
   formatWorktreeRemovalError,
   isOrphanedWorktreeError
 } from './worktree-logic'
@@ -72,6 +73,7 @@ function resolveWorktreeMetaWithDiscoveryStamp(store: Store, worktreeId: string)
 
 const loggedUnavailableSshGitProviders = new Set<string>()
 const loggedWorktreeListFailures = new Set<string>()
+const loggedMalformedWorktreeMetaKeys = new Set<string>()
 
 function warnOnce(keySet: Set<string>, key: string, message: string, error?: unknown): void {
   if (keySet.has(key)) {
@@ -102,6 +104,68 @@ function rememberLocalWorktreeRoots(
   ])
 }
 
+type SshWorktreeMetaCandidate = {
+  path: string
+  meta: WorktreeMeta
+}
+
+type SshWorktreeMetaIndex = Map<string, SshWorktreeMetaCandidate[]>
+
+function createSshWorktreeMetaIndex(entries: [string, WorktreeMeta][]): SshWorktreeMetaIndex {
+  const index: SshWorktreeMetaIndex = new Map()
+  for (const [worktreeId, meta] of entries) {
+    let parsed: { repoId: string; worktreePath: string }
+    try {
+      parsed = parseWorktreeId(worktreeId)
+    } catch (err) {
+      warnOnce(
+        loggedMalformedWorktreeMetaKeys,
+        worktreeId,
+        `[worktrees] ignoring malformed persisted worktree metadata key "${worktreeId}"`,
+        err
+      )
+      continue
+    }
+
+    const candidates = index.get(parsed.repoId) ?? []
+    candidates.push({ path: parsed.worktreePath, meta })
+    index.set(parsed.repoId, candidates)
+  }
+  return index
+}
+
+function synthesizeSshGitWorktree(repo: Repo, path: string, meta: WorktreeMeta): GitWorktreeInfo {
+  return {
+    path,
+    head: '',
+    branch: '',
+    isBare: false,
+    isMainWorktree: areWorktreePathsEqual(path, repo.path),
+    ...(meta.sparseDirectories !== undefined ||
+    meta.sparseBaseRef !== undefined ||
+    meta.sparsePresetId !== undefined
+      ? { isSparse: true }
+      : {})
+  }
+}
+
+function listDisconnectedSshWorktrees(
+  repo: Repo,
+  metaIndex: SshWorktreeMetaIndex
+): ReturnType<typeof mergeWorktree>[] {
+  const byWorktreeId = new Map<string, ReturnType<typeof mergeWorktree>>()
+  for (const candidate of metaIndex.get(repo.id) ?? []) {
+    const worktree = mergeWorktree(
+      repo.id,
+      synthesizeSshGitWorktree(repo, candidate.path, candidate.meta),
+      candidate.meta
+    )
+    byWorktreeId.delete(worktree.id)
+    byWorktreeId.set(worktree.id, worktree)
+  }
+  return [...byWorktreeId.values()]
+}
+
 export function registerWorktreeHandlers(
   mainWindow: BrowserWindow,
   store: Store,
@@ -123,6 +187,9 @@ export function registerWorktreeHandlers(
 
   ipcMain.handle('worktrees:listAll', async () => {
     const repos = store.getRepos()
+    const sshWorktreeMetaIndex = repos.some((repo) => repo.connectionId)
+      ? createSshWorktreeMetaIndex(Object.entries(store.getAllWorktreeMeta()))
+      : new Map()
 
     // Why: repos are listed in parallel so total time = slowest repo, not
     // the sum of all repos. Each listRepoWorktrees spawns `git worktree list`.
@@ -140,10 +207,20 @@ export function registerWorktreeHandlers(
                 `${repo.connectionId}:${repo.id}`,
                 `[worktrees] SSH git provider unavailable; skipping worktree list for repo "${repo.displayName}" (${repo.id}) at ${repo.path} on connection ${repo.connectionId}`
               )
-              return []
+              return listDisconnectedSshWorktrees(repo, sshWorktreeMetaIndex)
             }
             loggedUnavailableSshGitProviders.delete(`${repo.connectionId}:${repo.id}`)
-            gitWorktrees = await provider.listWorktrees(repo.path)
+            try {
+              gitWorktrees = await provider.listWorktrees(repo.path)
+            } catch (err) {
+              warnOnce(
+                loggedWorktreeListFailures,
+                `${repo.id}:${repo.path}`,
+                `[worktrees] failed to list worktrees for repo "${repo.displayName}" (${repo.id}) at ${repo.path}`,
+                err
+              )
+              return listDisconnectedSshWorktrees(repo, sshWorktreeMetaIndex)
+            }
           } else {
             gitWorktrees = await listRepoWorktrees(repo)
           }
@@ -181,6 +258,9 @@ export function registerWorktreeHandlers(
     if (!repo) {
       return []
     }
+    const sshWorktreeMetaIndex = repo.connectionId
+      ? createSshWorktreeMetaIndex(Object.entries(store.getAllWorktreeMeta()))
+      : new Map()
 
     try {
       let gitWorktrees
@@ -188,22 +268,26 @@ export function registerWorktreeHandlers(
         gitWorktrees = [createFolderWorktree(repo)]
       } else if (repo.connectionId) {
         const provider = getSshGitProvider(repo.connectionId)
-        // Why: when SSH is disconnected the provider is null. Return [] so the
-        // renderer's fetchWorktrees guard (`worktrees.length === 0 && current.length > 0`)
-        // preserves its cached worktree list. This avoids a console error on every
-        // fetchAllWorktrees cycle while the connection is being (re-)established —
-        // worktrees will be properly populated when the SSH `connected` event fires
-        // and triggers a re-fetch.
         if (!provider) {
           warnOnce(
             loggedUnavailableSshGitProviders,
             `${repo.connectionId}:${repo.id}`,
             `[worktrees] SSH git provider unavailable; skipping worktree list for repo "${repo.displayName}" (${repo.id}) at ${repo.path} on connection ${repo.connectionId}`
           )
-          return []
+          return listDisconnectedSshWorktrees(repo, sshWorktreeMetaIndex)
         }
         loggedUnavailableSshGitProviders.delete(`${repo.connectionId}:${repo.id}`)
-        gitWorktrees = await provider.listWorktrees(repo.path)
+        try {
+          gitWorktrees = await provider.listWorktrees(repo.path)
+        } catch (err) {
+          warnOnce(
+            loggedWorktreeListFailures,
+            `${repo.id}:${repo.path}`,
+            `[worktrees] failed to list worktrees for repo "${repo.displayName}" (${repo.id}) at ${repo.path}`,
+            err
+          )
+          return listDisconnectedSshWorktrees(repo, sshWorktreeMetaIndex)
+        }
       } else {
         gitWorktrees = await listRepoWorktrees(repo)
       }

From 60fdd11114093ce0fc33095a0045cb60bd742480 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 15 May 2026 12:10:06 -0700
Subject: [PATCH 55/82] Migrate agent pane identity to stable leaf ids (#1909)

Co-authored-by: Orca <help@stably.ai>
---
 .../migration-unsupported-pty-state.ts        |  47 ++
 src/main/agent-hooks/server.test.ts           |  87 ++-
 src/main/agent-hooks/server.ts                |  30 +-
 src/main/daemon/daemon-pty-adapter.ts         |   9 +-
 src/main/index.ts                             |  14 +
 src/main/ipc/agent-hooks.test.ts              |  11 +-
 src/main/ipc/agent-hooks.ts                   |  15 +-
 src/main/ipc/pty.test.ts                      | 166 +++-
 src/main/ipc/pty.ts                           | 182 ++++-
 src/main/persistence.test.ts                  | 723 +++++++++++++++---
 src/main/persistence.ts                       | 707 ++++++++++++++++-
 src/main/runtime/orca-runtime.test.ts         | 163 +++-
 src/main/runtime/orca-runtime.ts              |  62 +-
 src/main/runtime/rpc/methods/terminal.ts      |   8 +-
 ...ay-session-agent-hooks.integration.test.ts |  18 +-
 .../window/attach-main-window-services.ts     |   5 +-
 src/preload/api-types.ts                      |  11 +-
 src/preload/index.ts                          |  22 +-
 src/relay/agent-hook-integration.test.ts      |  11 +-
 src/relay/agent-hook-server.test.ts           |  14 +-
 src/renderer/src/components/Terminal.tsx      |   5 +-
 .../src/components/WorktreeJumpPalette.tsx    |  18 +-
 .../activity/ActivityPrototypePage.test.ts    |  96 ++-
 .../activity/ActivityPrototypePage.tsx        | 273 +++++--
 .../activity/ActivityTitlebarControls.tsx     |   7 +
 .../activity/activity-terminal-portal.ts      |  42 +-
 .../components/dashboard/useDashboardData.ts  |  55 +-
 .../components/dashboard/useRetainedAgents.ts |   7 +-
 .../dashboard/useRetainedAgentsSync.test.ts   |  37 +-
 .../right-sidebar/SourceControl.tsx           |   4 +-
 .../src/components/sidebar/CacheTimer.tsx     |   2 +-
 .../src/components/sidebar/SidebarNav.tsx     |  10 +
 .../components/sidebar/WorktreeCardAgents.tsx |  34 +-
 .../src/components/sidebar/WorktreeList.tsx   |   4 +-
 .../sidebar/smart-attention.test.ts           |  51 +-
 .../src/components/sidebar/smart-attention.ts | 123 ++-
 .../src/components/sidebar/smart-sort.test.ts |  95 +--
 .../src/components/sidebar/smart-sort.ts      |  15 +-
 .../sidebar/use-worktree-activity-status.ts   |  20 +-
 .../sidebar/useWorktreeAgentRows.test.ts      |  21 +-
 .../sidebar/useWorktreeAgentRows.ts           |  29 +-
 .../components/sidebar/visible-worktrees.ts   |   4 +-
 .../status-bar/ResourceUsageStatusSegment.tsx |  16 +-
 .../status-bar/mergeSnapshotAndSessions.ts    |  20 +-
 .../components/terminal-pane/TerminalPane.tsx |  72 +-
 .../TerminalPaneOverlayLayer.tsx              |   9 +-
 .../focus-terminal-pane-event.ts              |  39 +
 .../layout-serialization.test.ts              | 141 +++-
 .../terminal-pane/layout-serialization.ts     |  96 +--
 .../terminal-pane/pty-connection.test.ts      |  62 +-
 .../terminal-pane/pty-connection.ts           |  32 +-
 .../terminal-pane/pty-transport.test.ts       |   4 +-
 .../remote-runtime-pty-transport.ts           |   2 +
 .../terminal-pane/stale-agent-row.ts          |  20 +
 .../terminal-pane/terminal-layout-leaf-ids.ts | 173 +++++
 .../terminal-shutdown-layout-capture.test.ts  |  31 +-
 .../terminal-shutdown-layout-capture.ts       |  21 +-
 .../use-terminal-pane-global-effects.ts       |  21 +-
 .../use-terminal-pane-lifecycle.ts            |  25 +-
 src/renderer/src/constants/terminal.ts        |   7 +-
 .../src/hooks/useAutoAckViewedAgent.test.ts   |  22 +-
 .../src/hooks/useAutoAckViewedAgent.ts        |  57 +-
 .../src/hooks/useAutomationDispatchEvents.ts  |  12 +-
 src/renderer/src/hooks/useIpcEvents.test.ts   | 126 ++-
 src/renderer/src/hooks/useIpcEvents.ts        |  83 +-
 .../src/lib/activate-tab-and-focus-pane.ts    |  15 +-
 .../src/lib/focus-terminal-tab-surface.ts     |  19 +-
 .../launch-agent-background-session.test.ts   |  52 +-
 .../lib/launch-agent-background-session.ts    |  12 +-
 .../lib/migration-unsupported-agent-entry.ts  |  27 +
 .../lib/pane-manager/mint-stable-pane-id.ts   |  25 +
 .../lib/pane-manager/mobile-fit-overrides.ts  |  22 +-
 .../pane-fit-resize-observer.test.ts          |   3 +
 .../pane-manager/pane-identity-registry.ts    |  79 ++
 .../pane-manager/pane-key-resolution.test.ts  |  77 ++
 .../lib/pane-manager/pane-key-resolution.ts   |  70 ++
 .../lib/pane-manager/pane-lifecycle.test.ts   |   6 +
 .../src/lib/pane-manager/pane-lifecycle.ts    |   5 +
 .../lib/pane-manager/pane-manager-types.ts    |  13 +-
 .../src/lib/pane-manager/pane-manager.ts      | 180 ++---
 .../src/lib/pane-manager/pane-public-view.ts  |   2 +
 .../src/lib/pane-manager/pane-split-close.ts  | 154 ++++
 .../pane-manager/pane-split-scroll.test.ts    |   5 +
 .../pane-terminal-gpu-acceleration.test.ts    |   3 +
 .../lib/pane-manager/pane-tree-ops.test.ts    |   3 +
 .../src/runtime/sync-runtime-graph.ts         |  48 +-
 src/renderer/src/store/slices/agent-status.ts | 138 +++-
 .../src/store/slices/store-cascades.test.ts   |   7 +-
 .../slices/store-session-cascades.test.ts     |  14 +-
 .../src/store/slices/terminal-helpers.ts      |  14 +
 src/renderer/src/store/slices/terminals.ts    |  21 +-
 src/renderer/src/web/web-preload-api.ts       |   3 +
 src/shared/agent-hook-listener.test.ts        |  14 +-
 src/shared/agent-hook-listener.ts             |   8 +-
 src/shared/agent-status-types.ts              |  14 +-
 src/shared/constants.ts                       |   1 +
 src/shared/pane-key.ts                        |   8 +-
 src/shared/stable-pane-id.test.ts             |  42 +
 src/shared/stable-pane-id.ts                  |  45 ++
 src/shared/types.ts                           |   4 +-
 src/shared/workspace-session-schema.ts        |  10 +-
 .../e2e/activity-agent-pane-isolation.spec.ts | 382 +++++++++
 tests/e2e/helpers/terminal.ts                 | 127 +++
 tests/e2e/ssh-localhost.spec.ts               |   5 +-
 tests/e2e/terminal-panes.spec.ts              | 193 +++++
 tests/e2e/worktree-smart-sort.spec.ts         |  70 +-
 106 files changed, 5229 insertions(+), 1059 deletions(-)
 create mode 100644 src/main/agent-hooks/migration-unsupported-pty-state.ts
 create mode 100644 src/renderer/src/components/terminal-pane/focus-terminal-pane-event.ts
 create mode 100644 src/renderer/src/components/terminal-pane/stale-agent-row.ts
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-layout-leaf-ids.ts
 create mode 100644 src/renderer/src/lib/migration-unsupported-agent-entry.ts
 create mode 100644 src/renderer/src/lib/pane-manager/mint-stable-pane-id.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-identity-registry.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-key-resolution.test.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-key-resolution.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-split-close.ts
 create mode 100644 src/shared/stable-pane-id.test.ts
 create mode 100644 src/shared/stable-pane-id.ts
 create mode 100644 tests/e2e/activity-agent-pane-isolation.spec.ts

diff --git a/src/main/agent-hooks/migration-unsupported-pty-state.ts b/src/main/agent-hooks/migration-unsupported-pty-state.ts
new file mode 100644
index 00000000000..4e214ee13b0
--- /dev/null
+++ b/src/main/agent-hooks/migration-unsupported-pty-state.ts
@@ -0,0 +1,47 @@
+import type { MigrationUnsupportedPtyEntry } from '../../shared/agent-status-types'
+
+type MigrationUnsupportedPtyEvent =
+  | { type: 'set'; entry: MigrationUnsupportedPtyEntry }
+  | { type: 'clear'; ptyId: string }
+
+const entriesByPtyId = new Map<string, MigrationUnsupportedPtyEntry>()
+let listener: ((event: MigrationUnsupportedPtyEvent) => void) | null = null
+let persistenceListener: ((entries: MigrationUnsupportedPtyEntry[]) => void) | null = null
+
+export function setMigrationUnsupportedPtyListener(
+  nextListener: ((event: MigrationUnsupportedPtyEvent) => void) | null
+): void {
+  listener = nextListener
+}
+
+export function getMigrationUnsupportedPtySnapshot(): MigrationUnsupportedPtyEntry[] {
+  return [...entriesByPtyId.values()]
+}
+
+export function setMigrationUnsupportedPtyPersistenceListener(
+  nextListener: ((entries: MigrationUnsupportedPtyEntry[]) => void) | null
+): void {
+  persistenceListener = nextListener
+}
+
+export function setMigrationUnsupportedPty(entry: MigrationUnsupportedPtyEntry): void {
+  entriesByPtyId.set(entry.ptyId, entry)
+  listener?.({ type: 'set', entry })
+  persistenceListener?.(getMigrationUnsupportedPtySnapshot())
+}
+
+export function clearMigrationUnsupportedPty(ptyId: string): void {
+  if (!entriesByPtyId.delete(ptyId)) {
+    return
+  }
+  listener?.({ type: 'clear', ptyId })
+  persistenceListener?.(getMigrationUnsupportedPtySnapshot())
+}
+
+export function clearMigrationUnsupportedPtysForPaneKey(paneKey: string): void {
+  for (const [ptyId, entry] of entriesByPtyId) {
+    if (entry.paneKey === paneKey) {
+      clearMigrationUnsupportedPty(ptyId)
+    }
+  }
+}
diff --git a/src/main/agent-hooks/server.test.ts b/src/main/agent-hooks/server.test.ts
index 6033bf302d9..dbeaa3e5520 100644
--- a/src/main/agent-hooks/server.test.ts
+++ b/src/main/agent-hooks/server.test.ts
@@ -18,6 +18,7 @@ import {
   AGENT_STATUS_MAX_FIELD_LENGTH,
   parseAgentStatusPayload
 } from '../../shared/agent-status-types'
+import { makePaneKey } from '../../shared/stable-pane-id'
 
 const { trackMock } = vi.hoisted(() => ({
   trackMock: vi.fn()
@@ -27,7 +28,16 @@ vi.mock('../telemetry/client', () => ({
   track: trackMock
 }))
 
-const PANE = 'tab-1:0'
+const LEAF_1 = '11111111-1111-4111-8111-111111111111'
+const LEAF_2 = '22222222-2222-4222-8222-222222222222'
+const LEAF_3 = '33333333-3333-4333-8333-333333333333'
+const LEAF_4 = '44444444-4444-4444-8444-444444444444'
+const LEAF_5 = '55555555-5555-4555-8555-555555555555'
+const PANE = makePaneKey('tab-1', LEAF_1)
+const GOOD_PANE = makePaneKey('tab-good', LEAF_2)
+const OLD_PANE = makePaneKey('tab-old', LEAF_3)
+const FRESH_PANE = makePaneKey('tab-fresh', LEAF_4)
+const TAB_A_PANE = makePaneKey('tab-A', LEAF_5)
 
 type Body = {
   paneKey: string
@@ -358,14 +368,15 @@ describe('AgentHookServer listener replay', () => {
       )
 
       const warnsAfterFirst = warn.mock.calls.length
+      const secondPane = makePaneKey('tab-2', LEAF_2)
       server.ingestRemote(
         {
-          paneKey: 'tab-2:0',
+          paneKey: secondPane,
           env: 'development',
           version: '999',
           payload: {
             state: 'working',
-            paneKey: 'tab-2:0',
+            paneKey: secondPane,
             updatedAt: Date.now(),
             agentType: 'claude'
           }
@@ -391,9 +402,10 @@ describe('AgentHookServer listener replay', () => {
       server.setListener(listener)
 
       const oversizedPrompt = 'x'.repeat(AGENT_STATUS_MAX_FIELD_LENGTH + 50)
+      const remotePane = makePaneKey('tab-3', LEAF_3)
       server.ingestRemote(
         {
-          paneKey: ' tab-3:0 ',
+          paneKey: ` ${remotePane} `,
           tabId: ' tab-3 ',
           worktreeId: ' wt-3 ',
           env: 'remote',
@@ -410,7 +422,7 @@ describe('AgentHookServer listener replay', () => {
       expect(listener).toHaveBeenCalledTimes(1)
       expect(listener).toHaveBeenCalledWith(
         expect.objectContaining({
-          paneKey: 'tab-3:0',
+          paneKey: remotePane,
           tabId: 'tab-3',
           worktreeId: 'wt-3',
           connectionId: 'conn-9',
@@ -1762,9 +1774,10 @@ describe('Endpoint file lifecycle', () => {
       })
     })
     try {
+      const remotePane = makePaneKey('tab-3', LEAF_3)
       server.ingestRemote(
         {
-          paneKey: 'tab-3:0',
+          paneKey: remotePane,
           tabId: 'tab-3',
           worktreeId: 'wt-3',
           payload: {
@@ -1776,7 +1789,7 @@ describe('Endpoint file lifecycle', () => {
         'conn-42'
       )
       expect(events).toHaveLength(1)
-      expect(events[0].paneKey).toBe('tab-3:0')
+      expect(events[0].paneKey).toBe(remotePane)
       expect(events[0].connectionId).toBe('conn-42')
       expect(events[0].payload).toMatchObject({
         state: 'working',
@@ -2036,14 +2049,14 @@ describe('Last-status persistence', () => {
           },
           // Embedded paneKey mismatch — drop.
           [PANE]: {
-            paneKey: 'tab-x:99',
+            paneKey: makePaneKey('tab-x', LEAF_2),
             receivedAt: 1_700_000_000_000,
             stateStartedAt: 1_699_999_999_000,
             payload: { state: 'done', prompt: 'mismatch', agentType: 'claude' }
           },
           // Valid.
-          'tab-good:0': {
-            paneKey: 'tab-good:0',
+          [GOOD_PANE]: {
+            paneKey: GOOD_PANE,
             tabId: 'tab-good',
             receivedAt: recentTs(),
             stateStartedAt: recentTs(-1000),
@@ -2064,7 +2077,7 @@ describe('Last-status persistence', () => {
       expect(listener).toHaveBeenCalledTimes(1)
       expect(listener).toHaveBeenCalledWith(
         expect.objectContaining({
-          paneKey: 'tab-good:0',
+          paneKey: GOOD_PANE,
           payload: expect.objectContaining({ prompt: 'survived' })
         })
       )
@@ -2082,16 +2095,16 @@ describe('Last-status persistence', () => {
         version: 2,
         entries: {
           // Stale — should be dropped.
-          'tab-old:0': {
-            paneKey: 'tab-old:0',
+          [OLD_PANE]: {
+            paneKey: OLD_PANE,
             tabId: 'tab-old',
             receivedAt: eightDaysAgoMs,
             stateStartedAt: eightDaysAgoMs - 1000,
             payload: { state: 'done', prompt: 'old', agentType: 'claude' }
           },
           // Recent — should survive.
-          'tab-fresh:0': {
-            paneKey: 'tab-fresh:0',
+          [FRESH_PANE]: {
+            paneKey: FRESH_PANE,
             tabId: 'tab-fresh',
             receivedAt: recentTs(),
             stateStartedAt: recentTs(-1000),
@@ -2108,7 +2121,7 @@ describe('Last-status persistence', () => {
     })
     try {
       const snapshot = server.getStatusSnapshot()
-      expect(snapshot.map((e) => e.paneKey)).toEqual(['tab-fresh:0'])
+      expect(snapshot.map((e) => e.paneKey)).toEqual([FRESH_PANE])
     } finally {
       server.stop()
     }
@@ -2121,8 +2134,8 @@ describe('Last-status persistence', () => {
       JSON.stringify({
         version: 2,
         entries: {
-          'tab-A:0': {
-            paneKey: 'tab-A:0',
+          [TAB_A_PANE]: {
+            paneKey: TAB_A_PANE,
             // Why: deliberately divergent — paneKey says tab-A, the entry
             // claims tab-B. Sanitizer must drop rather than hydrate this
             // inconsistent row.
@@ -2188,7 +2201,7 @@ describe('Last-status persistence', () => {
       // Why: a no-op clearPaneState on a paneKey not in the cache is a
       // mutation site that should NOT trigger a redundant write. (clear was
       // designed to bail when nothing was evicted.)
-      server.clearPaneState('non-existent:0')
+      server.clearPaneState(makePaneKey('non-existent', LEAF_5))
       server.flushStatusPersistSync()
       // Touch back to the same mtime would let the test pass spuriously, so
       // assert no rewrite happened by checking that mtime is unchanged after
@@ -2287,6 +2300,42 @@ describe('AgentHookServer ingestRemote', () => {
     expect(listener).not.toHaveBeenCalled()
   })
 
+  it('drops remote relay envelopes with legacy numeric paneKeys before cache mutation', () => {
+    const server = new AgentHookServer()
+    const payload = parseAgentStatusPayload(
+      JSON.stringify({ state: 'working', prompt: 'p', agentType: 'claude' })
+    )
+    if (!payload) {
+      throw new Error('parseAgentStatusPayload returned null for a known-good fixture')
+    }
+    const listener = vi.fn()
+    server.setListener(listener)
+    server.ingestRemote(
+      { paneKey: 'tab-1:0', tabId: 'tab-1', worktreeId: 'wt-1', payload },
+      'conn-1'
+    )
+    expect(listener).not.toHaveBeenCalled()
+    expect(server.getStatusSnapshot()).toEqual([])
+  })
+
+  it('drops remote relay envelopes whose tabId disagrees with the paneKey tab', () => {
+    const server = new AgentHookServer()
+    const payload = parseAgentStatusPayload(
+      JSON.stringify({ state: 'working', prompt: 'p', agentType: 'claude' })
+    )
+    if (!payload) {
+      throw new Error('parseAgentStatusPayload returned null for a known-good fixture')
+    }
+    const listener = vi.fn()
+    server.setListener(listener)
+    server.ingestRemote(
+      { paneKey: PANE, tabId: 'tab-other', worktreeId: 'wt-1', payload },
+      'conn-1'
+    )
+    expect(listener).not.toHaveBeenCalled()
+    expect(server.getStatusSnapshot()).toEqual([])
+  })
+
   it('rejects empty connectionId', () => {
     const server = new AgentHookServer()
     const payload = parseAgentStatusPayload(
diff --git a/src/main/agent-hooks/server.ts b/src/main/agent-hooks/server.ts
index 9c3f736828d..072874998e7 100644
--- a/src/main/agent-hooks/server.ts
+++ b/src/main/agent-hooks/server.ts
@@ -39,6 +39,7 @@ import {
   type AgentStatusState,
   normalizeAgentStatusPayload
 } from '../../shared/agent-status-types'
+import { parsePaneKey } from '../../shared/stable-pane-id'
 
 export type { AgentHookSource }
 
@@ -95,26 +96,18 @@ type LastStatusFile = {
   entries: Record<string, EnrichedAgentHookEventPayload>
 }
 
-// Why: paneKey is `${tabId}:${paneId}` — exactly one ':' with non-empty
-// segments on either side. Used both at write time (defensive) and at
-// hydrate time (drop on mismatch).
+// Why: paneKey is `${tabId}:${leafUuid}` — validate the durable leaf suffix
+// at write/hydrate time so legacy numeric rows fail closed.
 export function isValidPaneKey(value: unknown): value is string {
-  if (typeof value !== 'string' || value.length === 0) {
-    return false
-  }
-  const colon = value.indexOf(':')
-  if (colon <= 0 || colon === value.length - 1) {
-    return false
-  }
-  // Why: exactly one colon. Anything weirder is corruption.
-  return !value.includes(':', colon + 1)
+  return typeof value === 'string' && parsePaneKey(value) !== null
 }
 
 function sanitizeHydratedEntry(
   paneKey: string,
   rawEntry: unknown
 ): EnrichedAgentHookEventPayload | null {
-  if (!isValidPaneKey(paneKey)) {
+  const parsedPaneKey = parsePaneKey(paneKey)
+  if (!parsedPaneKey) {
     return null
   }
   if (typeof rawEntry !== 'object' || rawEntry === null) {
@@ -128,10 +121,10 @@ function sanitizeHydratedEntry(
   if (tabId !== undefined && (typeof tabId !== 'string' || tabId.length === 0)) {
     return null
   }
-  // Why: paneKey is `${tabId}:${paneId}`; a stored entry whose tabId field
+  // Why: paneKey is `${tabId}:${leafUuid}`; a stored entry whose tabId field
   // diverges from the key's tab segment is corruption (renamer bug, manual
   // edit, future shape drift). Drop instead of hydrating an inconsistent row.
-  if (typeof tabId === 'string' && tabId !== paneKey.slice(0, paneKey.indexOf(':'))) {
+  if (typeof tabId === 'string' && tabId !== parsedPaneKey.tabId) {
     return null
   }
   const worktreeId = record.worktreeId
@@ -349,6 +342,7 @@ export class AgentHookServer {
     // length-caps paneKey before caching, so the cache key here must follow
     // the same rule or remote-vs-local events for the same pane would diverge.
     const paneKey = envelope.paneKey.trim()
+    const parsedPaneKey = parsePaneKey(paneKey)
     if (paneKey.length === 0) {
       track('agent_hook_unattributed', { reason: 'empty_pane_key' })
       return
@@ -356,6 +350,9 @@ export class AgentHookServer {
     if (paneKey.length > MAX_PANE_KEY_LEN) {
       return
     }
+    if (!parsedPaneKey) {
+      return
+    }
     if (envelope.tabId !== undefined && typeof envelope.tabId !== 'string') {
       return
     }
@@ -369,6 +366,9 @@ export class AgentHookServer {
       envelope.tabId !== undefined && envelope.tabId.trim().length > 0
         ? envelope.tabId.trim()
         : undefined
+    if (tabId !== undefined && tabId !== parsedPaneKey.tabId) {
+      return
+    }
     const worktreeId =
       envelope.worktreeId !== undefined && envelope.worktreeId.trim().length > 0
         ? envelope.worktreeId.trim()
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 0570519c1fd..96ac6932ad2 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -142,7 +142,12 @@ export class DaemonPtyAdapter implements IPtyProvider {
     // but should still return the cached cold restore data.
     const cachedRestore = this.coldRestoreCache.get(sessionId)
     if (cachedRestore) {
-      return { id: sessionId, pid, coldRestore: cachedRestore }
+      return {
+        id: sessionId,
+        pid,
+        coldRestore: cachedRestore,
+        ...(!result.isNew ? { isReattach: true } : {})
+      }
     }
 
     this.activeSessionIds.add(sessionId)
@@ -197,7 +202,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
 
     const isReattach = !result.isNew
     if (!isReattach || !result.snapshot) {
-      return { id: sessionId, pid }
+      return { id: sessionId, pid, ...(isReattach ? { isReattach: true } : {}) }
     }
 
     const isAltScreen = result.snapshot.modes.alternateScreen
diff --git a/src/main/index.ts b/src/main/index.ts
index d034bac1ff6..e87525574d9 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -49,6 +49,7 @@ import { ClaudeAccountService } from './claude-accounts/service'
 import { ClaudeRuntimeAuthService } from './claude-accounts/runtime-auth-service'
 import { StarNagService } from './star-nag/service'
 import { agentHookServer } from './agent-hooks/server'
+import { setMigrationUnsupportedPtyListener } from './agent-hooks/migration-unsupported-pty-state'
 import { claudeHookService } from './claude/hook-service'
 import { codexHookService } from './codex/hook-service'
 import { geminiHookService } from './gemini/hook-service'
@@ -309,6 +310,7 @@ function openMainWindow(): BrowserWindow {
     // replay-loop through lastStatusByPaneKey runs only on deliberate
     // window recreations instead of stacking on top of stale listeners.
     agentHookServer.setListener(null)
+    setMigrationUnsupportedPtyListener(null)
     // Why: any running synthesized-title spinner intervals would fire into a
     // destroyed webContents; stop them all here instead of deferring to
     // per-pane teardown, which may never run for restored-but-never-torn-down
@@ -347,6 +349,18 @@ function openMainWindow(): BrowserWindow {
       }
     }
   )
+  setMigrationUnsupportedPtyListener((event) => {
+    if (mainWindow?.isDestroyed()) {
+      return
+    }
+    if (event.type === 'set') {
+      mainWindow?.webContents.send('agentStatus:migrationUnsupported', event.entry)
+    } else {
+      mainWindow?.webContents.send('agentStatus:migrationUnsupportedClear', {
+        ptyId: event.ptyId
+      })
+    }
+  })
   return window
 }
 
diff --git a/src/main/ipc/agent-hooks.test.ts b/src/main/ipc/agent-hooks.test.ts
index a87ea123a37..f82ade795e1 100644
--- a/src/main/ipc/agent-hooks.test.ts
+++ b/src/main/ipc/agent-hooks.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type * as AgentHookServerModule from '../agent-hooks/server'
+import { makePaneKey } from '../../shared/stable-pane-id'
 
 // Why: cover the agentStatus:drop IPC handler — it must propagate the
 // renderer dismissal to dropStatusEntry so the on-disk last-status file
@@ -12,6 +13,7 @@ const onHandlers = new Map<string, (event: unknown, ...args: unknown[]) => void>
 const handleHandlers = new Map<string, (event: unknown, ...args: unknown[]) => unknown>()
 const removeHandler = vi.fn()
 const removeAllListeners = vi.fn()
+const PANE_KEY = makePaneKey('tab-1', '11111111-1111-4111-8111-111111111111')
 
 vi.mock('electron', () => ({
   ipcMain: {
@@ -69,7 +71,7 @@ describe('agentStatus:getSnapshot IPC', () => {
   it('returns the hook cache snapshot', async () => {
     const snapshot = [
       {
-        paneKey: 'tab-1:0',
+        paneKey: PANE_KEY,
         state: 'done',
         prompt: 'p',
         agentType: 'claude',
@@ -94,8 +96,8 @@ describe('agentStatus:drop IPC', () => {
 
     const handler = onHandlers.get('agentStatus:drop')
     expect(handler).toBeDefined()
-    handler!({}, 'tab-1:0')
-    expect(dropStatusEntry).toHaveBeenCalledWith('tab-1:0')
+    handler!({}, PANE_KEY)
+    expect(dropStatusEntry).toHaveBeenCalledWith(PANE_KEY)
   })
 
   it('rejects non-string paneKey (defensive against a malformed renderer message)', async () => {
@@ -110,9 +112,10 @@ describe('agentStatus:drop IPC', () => {
       null,
       {},
       [],
+      'tab-1:0', // legacy numeric pane-key suffix
       'no-colon', // missing colon — rejected by isValidPaneKey
       ':leading', // empty tabId half
-      'trailing:', // empty paneId half
+      'trailing:', // empty leafId half
       'a:b:c' // multiple colons
     ]
     for (const value of bad) {
diff --git a/src/main/ipc/agent-hooks.ts b/src/main/ipc/agent-hooks.ts
index 2cf3929b36f..350c1c9200e 100644
--- a/src/main/ipc/agent-hooks.ts
+++ b/src/main/ipc/agent-hooks.ts
@@ -1,7 +1,14 @@
 import { ipcMain } from 'electron'
 import type { AgentHookInstallStatus } from '../../shared/agent-hook-types'
-import type { AgentStatusIpcPayload } from '../../shared/agent-status-types'
+import type {
+  AgentStatusIpcPayload,
+  MigrationUnsupportedPtyEntry
+} from '../../shared/agent-status-types'
 import { agentHookServer, isValidPaneKey } from '../agent-hooks/server'
+import {
+  clearMigrationUnsupportedPtysForPaneKey,
+  getMigrationUnsupportedPtySnapshot
+} from '../agent-hooks/migration-unsupported-pty-state'
 import { claudeHookService } from '../claude/hook-service'
 import { codexHookService } from '../codex/hook-service'
 import { geminiHookService } from '../gemini/hook-service'
@@ -25,6 +32,7 @@ export function registerAgentHookHandlers(): void {
   ipcMain.removeHandler('agentHooks:cursorStatus')
   ipcMain.removeHandler('agentHooks:droidStatus')
   ipcMain.removeHandler('agentStatus:getSnapshot')
+  ipcMain.removeHandler('agentStatus:getMigrationUnsupportedSnapshot')
   // Why: agentStatus:drop is sent fire-and-forget from the renderer via
   // ipcRenderer.send(); we listen with ipcMain.on (not handle) so we don't
   // round-trip a response. Removing first keeps re-registration safe even
@@ -40,6 +48,7 @@ export function registerAgentHookHandlers(): void {
       // wipe the per-pane prompt/tool caches, which the next hook event for that
       // (still-alive) pane needs to render a coherent row.
       agentHookServer.dropStatusEntry(paneKey)
+      clearMigrationUnsupportedPtysForPaneKey(paneKey)
     } catch (err) {
       console.warn('[agent-hooks] dropStatusEntry failed:', err)
     }
@@ -49,6 +58,10 @@ export function registerAgentHookHandlers(): void {
     // lose replayed statuses while its local store is still empty.
     return agentHookServer.getStatusSnapshot()
   })
+  ipcMain.handle(
+    'agentStatus:getMigrationUnsupportedSnapshot',
+    (): MigrationUnsupportedPtyEntry[] => getMigrationUnsupportedPtySnapshot()
+  )
 
   // Why: errors from getStatus() (fs permission denied, homedir resolution
   // failure, etc.) must be reported inline via state:'error' so the sidebar can
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 38ca92c39dd..2cd81d45df2 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -25,7 +25,12 @@ const {
   piClearPtyMock,
   isPwshAvailableMock,
   trackMock,
-  classifyErrorMock
+  classifyErrorMock,
+  registerPtyMock,
+  unregisterPtyMock,
+  setMigrationUnsupportedPtyMock,
+  clearMigrationUnsupportedPtyMock,
+  clearMigrationUnsupportedPtysForPaneKeyMock
 } = vi.hoisted(() => ({
   handleMock: vi.fn(),
   onMock: vi.fn(),
@@ -48,7 +53,12 @@ const {
   piBuildPtyEnvMock: vi.fn(),
   piClearPtyMock: vi.fn(),
   trackMock: vi.fn(),
-  classifyErrorMock: vi.fn()
+  classifyErrorMock: vi.fn(),
+  registerPtyMock: vi.fn(),
+  unregisterPtyMock: vi.fn(),
+  setMigrationUnsupportedPtyMock: vi.fn(),
+  clearMigrationUnsupportedPtyMock: vi.fn(),
+  clearMigrationUnsupportedPtysForPaneKeyMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -113,11 +123,25 @@ vi.mock('../telemetry/client', () => ({
 vi.mock('../telemetry/classify-error', () => ({
   classifyError: classifyErrorMock
 }))
+
+vi.mock('../memory/pty-registry', () => ({
+  registerPty: registerPtyMock,
+  unregisterPty: unregisterPtyMock
+}))
+
+vi.mock('../agent-hooks/migration-unsupported-pty-state', () => ({
+  setMigrationUnsupportedPty: setMigrationUnsupportedPtyMock,
+  clearMigrationUnsupportedPty: clearMigrationUnsupportedPtyMock,
+  clearMigrationUnsupportedPtysForPaneKey: clearMigrationUnsupportedPtysForPaneKeyMock
+}))
 import { LocalPtyProvider } from '../providers/local-pty-provider'
+import { makePaneKey } from '../../shared/stable-pane-id'
 import {
   registerPtyHandlers,
   registerSshPtyProvider,
+  clearProviderPtyState,
   deletePtyOwnership,
+  getPtyIdForPaneKey,
   setPtyOwnership,
   setLocalPtyProvider,
   unregisterSshPtyProvider
@@ -187,6 +211,11 @@ describe('registerPtyHandlers', () => {
     isPwshAvailableMock.mockReset()
     trackMock.mockReset()
     classifyErrorMock.mockReset()
+    registerPtyMock.mockReset()
+    unregisterPtyMock.mockReset()
+    setMigrationUnsupportedPtyMock.mockReset()
+    clearMigrationUnsupportedPtyMock.mockReset()
+    clearMigrationUnsupportedPtysForPaneKeyMock.mockReset()
     mainWindow.webContents.on.mockReset()
     mainWindow.webContents.send.mockReset()
 
@@ -960,14 +989,15 @@ describe('registerPtyHandlers', () => {
           undefined,
           store as never
         )
+        const leafId = '11111111-1111-4111-8111-111111111111'
         await handlers.get('pty:spawn')!(null, {
           cols: 80,
           rows: 24,
-          env: { FOO: 'bar' },
+          env: { FOO: 'bar', ORCA_PANE_KEY: makePaneKey('tab-1', leafId) },
           connectionId: 'ssh-1',
           worktreeId: 'wt-1',
           tabId: 'tab-1',
-          leafId: 'leaf-1'
+          leafId
         })
         const env = sshSpawn.mock.calls.at(-1)![0].env
         // Why: every host-local var must be absent over SSH — the hook
@@ -994,16 +1024,32 @@ describe('registerPtyHandlers', () => {
             ptyId: 'ssh-pty',
             worktreeId: 'wt-1',
             tabId: 'tab-1',
-            leafId: 'leaf-1',
+            leafId,
             state: 'attached'
           })
         )
         expect(store.persistPtyBinding).toHaveBeenCalledWith({
           worktreeId: 'wt-1',
           tabId: 'tab-1',
-          leafId: 'leaf-1',
+          leafId,
           ptyId: 'ssh-pty'
         })
+
+        store.upsertSshRemotePtyLease.mockClear()
+        store.persistPtyBinding.mockClear()
+        await handlers.get('pty:spawn')!(null, {
+          cols: 80,
+          rows: 24,
+          env: { ORCA_PANE_KEY: 'tab-1:pane:1' },
+          connectionId: 'ssh-1',
+          worktreeId: 'wt-1',
+          tabId: 'tab-1',
+          leafId: 'pane:1'
+        })
+        expect(store.upsertSshRemotePtyLease).toHaveBeenCalledTimes(1)
+        expect(sshSpawn.mock.calls.at(-1)?.[0].env.ORCA_PANE_KEY).toBeUndefined()
+        expect(store.upsertSshRemotePtyLease.mock.calls[0]?.[0]).not.toHaveProperty('leafId')
+        expect(store.persistPtyBinding).not.toHaveBeenCalled()
       })
 
       it('marks a caller-supplied SSH session expired when remote reattach is gone', async () => {
@@ -1351,19 +1397,23 @@ describe('registerPtyHandlers', () => {
         const prevFlag = process.env.ORCA_FEATURE_REMOTE_AGENT_HOOKS
         process.env.ORCA_FEATURE_REMOTE_AGENT_HOOKS = '1'
         try {
+          const leafId = '22222222-2222-4222-8222-222222222222'
+          const paneKey = makePaneKey('tab-2', leafId)
           await handlers.get('pty:spawn')!(null, {
             cols: 80,
             rows: 24,
             env: {
               FOO: 'bar',
-              ORCA_PANE_KEY: 'tab-2:0',
+              ORCA_PANE_KEY: paneKey,
               ORCA_TAB_ID: 'tab-2',
               ORCA_WORKTREE_ID: 'wt-2'
             },
-            connectionId: 'ssh-1'
+            connectionId: 'ssh-1',
+            tabId: 'tab-2',
+            leafId
           })
           const env = sshSpawn.mock.calls.at(-1)![0].env
-          expect(env.ORCA_PANE_KEY).toBe('tab-2:0')
+          expect(env.ORCA_PANE_KEY).toBe(paneKey)
           expect(env.ORCA_TAB_ID).toBe('tab-2')
           expect(env.ORCA_WORKTREE_ID).toBe('wt-2')
           // Local hook server coords still must NOT cross the wire — the
@@ -1641,7 +1691,7 @@ describe('registerPtyHandlers', () => {
     }
 
     registerPtyHandlers(mainWindow as never, runtime as never)
-    const paneKey = 'tab-cli:1'
+    const paneKey = makePaneKey('tab-cli', '11111111-1111-4111-8111-111111111111')
     const gen = (await handlers.get('pty:declarePendingPaneSerializer')!(null, {
       paneKey
     })) as number
@@ -2276,6 +2326,102 @@ describe('registerPtyHandlers', () => {
     }
   })
 
+  it('registers only validated stable pane keys in the local PTY memory registry', async () => {
+    registerPtyHandlers(mainWindow as never)
+    const leafId = '11111111-1111-4111-8111-111111111111'
+    await handlers.get('pty:spawn')!(null, {
+      cols: 80,
+      rows: 24,
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId,
+      env: { ORCA_PANE_KEY: 'tab-1:0' }
+    })
+
+    expect(registerPtyMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        paneKey: null
+      })
+    )
+    expect(setMigrationUnsupportedPtyMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ptyId: expect.any(String),
+        worktreeId: 'wt-1',
+        tabId: 'tab-1',
+        leafId,
+        paneKey: makePaneKey('tab-1', leafId),
+        reason: 'legacy-numeric-pane-key',
+        source: 'local'
+      })
+    )
+
+    const stablePaneKey = makePaneKey('tab-1', leafId)
+    await handlers.get('pty:spawn')!(null, {
+      cols: 80,
+      rows: 24,
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId,
+      env: { ORCA_PANE_KEY: stablePaneKey }
+    })
+
+    expect(registerPtyMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        paneKey: stablePaneKey
+      })
+    )
+    expect(clearMigrationUnsupportedPtysForPaneKeyMock).toHaveBeenCalledWith(stablePaneKey)
+
+    await handlers.get('pty:spawn')!(null, {
+      cols: 80,
+      rows: 24,
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId,
+      env: { ORCA_PANE_KEY: makePaneKey('tab-2', leafId) }
+    })
+
+    expect(registerPtyMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        paneKey: null
+      })
+    )
+  })
+
+  it('does not let an old PTY teardown clear a newer pane-key owner', async () => {
+    registerPtyHandlers(mainWindow as never)
+    const leafId = '11111111-1111-4111-8111-111111111111'
+    const stablePaneKey = makePaneKey('tab-1', leafId)
+
+    const first = (await handlers.get('pty:spawn')!(null, {
+      cols: 80,
+      rows: 24,
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId,
+      env: { ORCA_PANE_KEY: stablePaneKey }
+    })) as { id: string }
+    const second = (await handlers.get('pty:spawn')!(null, {
+      cols: 80,
+      rows: 24,
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId,
+      env: { ORCA_PANE_KEY: stablePaneKey }
+    })) as { id: string }
+
+    expect(getPtyIdForPaneKey(stablePaneKey)).toBe(second.id)
+    clearAgentHookPaneStateMock.mockClear()
+    clearProviderPtyState(first.id)
+
+    expect(getPtyIdForPaneKey(stablePaneKey)).toBe(second.id)
+    expect(clearAgentHookPaneStateMock).not.toHaveBeenCalledWith(stablePaneKey)
+
+    clearProviderPtyState(second.id)
+    expect(getPtyIdForPaneKey(stablePaneKey)).toBeUndefined()
+    expect(clearAgentHookPaneStateMock).toHaveBeenCalledWith(stablePaneKey)
+  })
+
   it('prefers args.env.SHELL and normalizes the child env after fallback', async () => {
     const originalShell = process.env.SHELL
     const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index 2b304baea2b..a0d4cc4c26e 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -38,6 +38,12 @@ import {
 } from '../../shared/telemetry-events'
 import { isRemoteAgentHooksEnabled } from '../../shared/agent-hook-relay'
 import { readShellStartupEnvVar } from '../pty/shell-startup-env'
+import { isTerminalLeafId, makePaneKey, parsePaneKey } from '../../shared/stable-pane-id'
+import {
+  clearMigrationUnsupportedPty,
+  clearMigrationUnsupportedPtysForPaneKey,
+  setMigrationUnsupportedPty
+} from '../agent-hooks/migration-unsupported-pty-state'
 
 // ─── Provider Registry ──────────────────────────────────────────────
 // Routes PTY operations by connectionId. null = local provider.
@@ -102,8 +108,37 @@ const ptyPendingGenByPtyId = new Map<string, number>()
 // and cleared on PTY teardown.
 const rendererSerializerByPtyId = new Set<string>()
 
+function parseValidPaneKey(paneKey: unknown): ReturnType<typeof parsePaneKey> {
+  if (typeof paneKey !== 'string' || paneKey.length > 256) {
+    return null
+  }
+  return parsePaneKey(paneKey)
+}
+
 function isValidPaneKey(paneKey: unknown): paneKey is string {
-  return typeof paneKey === 'string' && paneKey.length > 0 && paneKey.length <= 256
+  return parseValidPaneKey(paneKey) !== null
+}
+
+function parseLegacyNumericPaneKey(
+  paneKey: unknown
+): { tabId: string; numericPaneId: string } | null {
+  if (typeof paneKey !== 'string' || paneKey.length > 256) {
+    return null
+  }
+  const trimmed = paneKey.trim()
+  const delimiter = trimmed.indexOf(':')
+  if (
+    delimiter <= 0 ||
+    delimiter !== trimmed.lastIndexOf(':') ||
+    delimiter === trimmed.length - 1
+  ) {
+    return null
+  }
+  const numericPaneId = trimmed.slice(delimiter + 1)
+  if (!/^\d+$/.test(numericPaneId)) {
+    return null
+  }
+  return { tabId: trimmed.slice(0, delimiter), numericPaneId }
 }
 
 function rememberPaneKeyForPty(ptyId: string, paneKey: unknown): string | null {
@@ -431,6 +466,7 @@ export function clearProviderPtyState(id: string): void {
   // trying to resolve its (now-dead) pid on every snapshot. Safe no-op for
   // PTYs that were never registered (SSH-owned).
   unregisterPty(id)
+  clearMigrationUnsupportedPty(id)
   rendererSerializerByPtyId.delete(id)
   // Why: the hook server's per-paneKey caches (lastPrompt / lastTool) would
   // otherwise accumulate entries for dead panes over the process lifetime.
@@ -438,9 +474,12 @@ export function clearProviderPtyState(id: string): void {
   // correlate a ptyId back to its paneKey.
   const paneKey = ptyPaneKey.get(id)
   if (paneKey) {
-    agentHookServer.clearPaneState(paneKey)
+    const stillOwnsPaneKey = paneKeyPtyId.get(paneKey) === id
+    if (stillOwnsPaneKey) {
+      agentHookServer.clearPaneState(paneKey)
+      paneKeyPtyId.delete(paneKey)
+    }
     ptyPaneKey.delete(id)
-    paneKeyPtyId.delete(paneKey)
     // Why: drop the pre-signal pending entry only if it still belongs to THIS
     // PTY's spawn generation. If a remount for the same paneKey has already
     // pre-signaled a new gen, this teardown must NOT touch it — otherwise
@@ -452,14 +491,16 @@ export function clearProviderPtyState(id: string): void {
       settlePendingPaneSerializer(paneKey, ownedGen)
     }
     ptyPendingGenByPtyId.delete(id)
-    // Why: notify registered consumers AFTER we've dropped the paneKey↔ptyId
-    // entries so a listener that re-reads the map sees the post-teardown
-    // state. Wrap each call so one throwing listener cannot block the rest.
-    for (const listener of paneKeyTeardownListeners) {
-      try {
-        listener(paneKey)
-      } catch (err) {
-        console.error('[pty] paneKey teardown listener threw', err)
+    if (stillOwnsPaneKey) {
+      // Why: notify registered consumers AFTER we've dropped the paneKey↔ptyId
+      // entries so a listener that re-reads the map sees the post-teardown
+      // state. Wrap each call so one throwing listener cannot block the rest.
+      for (const listener of paneKeyTeardownListeners) {
+        try {
+          listener(paneKey)
+        } catch (err) {
+          console.error('[pty] paneKey teardown listener threw', err)
+        }
       }
     }
   }
@@ -1067,14 +1108,9 @@ export function registerPtyHandlers(
       const isMintedSessionId = args.sessionId === undefined && isDaemonHostSpawn
       const effectiveSessionId =
         args.sessionId ?? (isDaemonHostSpawn ? mintPtySessionId(args.worktreeId) : undefined)
-      // Why: the renderer unconditionally sets ORCA_PANE_KEY/TAB_ID/WORKTREE_ID
-      // on every spawn, including SSH ones (see pty-connection.ts). When the
-      // remote-agent-hook feature is OFF, the relay-side hook server is not
-      // wired up and forwarding these vars across the SSH wire would let a
-      // future relay build start posting hook events Orca cannot route. Strip
-      // them on the SSH path while the flag is off; flag ON keeps them so the
-      // relay's pty-handler sees the paneKey on spawn env. See
-      // docs/design/agent-status-over-ssh.md §8 (commit #6 gate location a).
+      // Why: the renderer sets pane env for SSH too. Only forward it to the
+      // remote when the relay hook path is enabled; otherwise a newer relay
+      // could emit statuses this Orca build is not prepared to route.
       let sshSourceEnv = args.env
       if (args.connectionId && !isRemoteAgentHooksEnabled()) {
         if (
@@ -1090,7 +1126,41 @@ export function registerPtyHandlers(
           sshSourceEnv = stripped
         }
       }
-      const baseEnv = claudeAuth ? { ...sshSourceEnv, ...claudeAuth.envPatch } : sshSourceEnv
+      const baseEnvWithAuth = claudeAuth
+        ? { ...sshSourceEnv, ...claudeAuth.envPatch }
+        : sshSourceEnv
+      const spawnPaneKey = baseEnvWithAuth?.ORCA_PANE_KEY
+      const parsedSpawnPaneKey = parseValidPaneKey(spawnPaneKey)
+      const verifiedPaneKey =
+        parsedSpawnPaneKey &&
+        typeof args.tabId === 'string' &&
+        args.tabId === parsedSpawnPaneKey.tabId &&
+        args.leafId === parsedSpawnPaneKey.leafId
+          ? makePaneKey(parsedSpawnPaneKey.tabId, parsedSpawnPaneKey.leafId)
+          : null
+      const verifiedLeafId =
+        verifiedPaneKey && parsedSpawnPaneKey ? parsedSpawnPaneKey.leafId : null
+      const metadataLeafId =
+        typeof args.leafId === 'string' && isTerminalLeafId(args.leafId) ? args.leafId : null
+      const legacySpawnPaneKey = verifiedPaneKey ? null : parseLegacyNumericPaneKey(spawnPaneKey)
+      const migrationUnsupportedPaneKey =
+        legacySpawnPaneKey &&
+        typeof args.tabId === 'string' &&
+        args.tabId === legacySpawnPaneKey.tabId &&
+        typeof args.leafId === 'string' &&
+        isTerminalLeafId(args.leafId)
+          ? makePaneKey(args.tabId, args.leafId)
+          : null
+      const baseEnv = baseEnvWithAuth
+        ? { ...baseEnvWithAuth, ...(verifiedPaneKey ? { ORCA_PANE_KEY: verifiedPaneKey } : {}) }
+        : undefined
+      if (baseEnv && !verifiedPaneKey) {
+        // Why: ORCA_PANE_KEY crosses into shells and hook registries. Only the
+        // key proven to match this spawn's tab+leaf may leave the IPC boundary.
+        delete baseEnv.ORCA_PANE_KEY
+      }
+      const validatedPaneKey = verifiedPaneKey
+      const validatedLeafId = verifiedLeafId ?? metadataLeafId
       let env: Record<string, string> | undefined = baseEnv
       const preAllocatedHandle =
         runtime && !(provider instanceof LocalPtyProvider)
@@ -1262,7 +1332,7 @@ export function registerPtyHandlers(
           ptyId: result.id,
           ...(typeof args.worktreeId === 'string' ? { worktreeId: args.worktreeId } : {}),
           ...(typeof args.tabId === 'string' ? { tabId: args.tabId } : {}),
-          ...(typeof args.leafId === 'string' ? { leafId: args.leafId } : {}),
+          ...(validatedLeafId ? { leafId: validatedLeafId } : {}),
           state: 'attached',
           lastAttachedAt: Date.now()
         })
@@ -1280,16 +1350,35 @@ export function registerPtyHandlers(
       if (
         (isDaemonHostSpawn || args.connectionId) &&
         store &&
-        args.worktreeId !== undefined &&
-        args.tabId !== undefined &&
-        args.leafId !== undefined
+        typeof args.worktreeId === 'string' &&
+        typeof args.tabId === 'string' &&
+        validatedLeafId !== null
       ) {
-        store.persistPtyBinding({
-          worktreeId: args.worktreeId,
-          tabId: args.tabId,
-          leafId: args.leafId,
-          ptyId: result.id
-        })
+        try {
+          store.persistPtyBinding({
+            worktreeId: args.worktreeId,
+            tabId: args.tabId,
+            leafId: validatedLeafId,
+            ptyId: result.id
+          })
+        } catch (err) {
+          console.error('[pty] failed to persist PTY binding after spawn:', err)
+          if (!result.isReattach) {
+            try {
+              await provider.shutdown(result.id, { immediate: true })
+            } catch (shutdownErr) {
+              console.warn('[pty] failed to clean up PTY after persistence failure:', shutdownErr)
+            }
+            clearProviderPtyState(result.id)
+            deletePtyOwnership(result.id)
+          }
+          if (!result.isReattach && args.connectionId && store) {
+            store.removeSshRemotePtyLease(args.connectionId, result.id)
+          }
+          throw new Error(
+            'Failed to save terminal session state. Check disk space and Orca data directory permissions, then try again.'
+          )
+        }
       }
       // Why: pre-signal cooperation gate — when the renderer has declared it
       // will own the serializer for this paneKey, suppress the daemon-snapshot
@@ -1297,16 +1386,13 @@ export function registerPtyHandlers(
       // is the sole authority. The pre-signal is keyed on paneKey because at
       // spawn time the renderer doesn't yet know the new ptyId. See
       // docs/mobile-prefer-renderer-scrollback.md.
-      const spawnPaneKey = args.env?.ORCA_PANE_KEY
-      const rendererPreSignaled = isValidPaneKey(spawnPaneKey)
-        ? pendingByPaneKey.has(spawnPaneKey)
-        : false
+      const rendererPreSignaled = validatedPaneKey ? pendingByPaneKey.has(validatedPaneKey) : false
       const rendererAlreadyRegistered = rendererSerializerByPtyId.has(result.id)
       // Why: capture the pending gen at spawn time so teardown for THIS PTY
       // only settles its own generation. A remount that replaces the entry
       // with a new gen must not be stomped by the old PTY's teardown.
-      if (isValidPaneKey(spawnPaneKey) && rendererPreSignaled) {
-        const gen = pendingByPaneKey.get(spawnPaneKey)
+      if (validatedPaneKey && rendererPreSignaled) {
+        const gen = pendingByPaneKey.get(validatedPaneKey)
         if (gen !== undefined) {
           ptyPendingGenByPtyId.set(result.id, gen)
         }
@@ -1356,8 +1442,28 @@ export function registerPtyHandlers(
       // Record<string, string> type is not actually enforced at the boundary.
       // Narrow to a bounded string so malformed or oversized values cannot
       // pollute ptyPaneKey or the downstream clearPaneState call.
-      const paneKey = args.env?.ORCA_PANE_KEY
-      const rememberedPaneKey = rememberPaneKeyForPty(result.id, paneKey)
+      const rememberedPaneKey = validatedPaneKey
+        ? rememberPaneKeyForPty(result.id, validatedPaneKey)
+        : null
+      if (validatedPaneKey) {
+        if (!result.isReattach) {
+          clearMigrationUnsupportedPtysForPaneKey(validatedPaneKey)
+        }
+      } else if (migrationUnsupportedPaneKey && legacySpawnPaneKey) {
+        // Why: old live PTYs can still carry `${tabId}:${numericPaneId}` in
+        // ORCA_PANE_KEY. Only surface a migration row when this spawn also
+        // proves the owning UUID leaf through the renderer IPC metadata.
+        setMigrationUnsupportedPty({
+          ptyId: result.id,
+          ...(typeof args.worktreeId === 'string' ? { worktreeId: args.worktreeId } : {}),
+          tabId: legacySpawnPaneKey.tabId,
+          leafId: args.leafId,
+          paneKey: migrationUnsupportedPaneKey,
+          reason: 'legacy-numeric-pane-key',
+          source: args.connectionId ? 'ssh' : 'local',
+          updatedAt: Date.now()
+        })
+      }
       // Why: register local PTYs (connectionId falsy) with the memory
       // collector so it can walk each PTY's process subtree and attribute
       // memory back to its worktree. SSH PTYs execute remotely and their
diff --git a/src/main/persistence.test.ts b/src/main/persistence.test.ts
index 89444699168..ec9aceee279 100644
--- a/src/main/persistence.test.ts
+++ b/src/main/persistence.test.ts
@@ -6,10 +6,15 @@ import { writeFileSync, readFileSync, rmSync, mkdtempSync, mkdirSync, existsSync
 import { join } from 'path'
 import { tmpdir } from 'os'
 import type { Repo, TerminalTab, WorkspaceSessionState } from '../shared/types'
+import { isTerminalLeafId } from '../shared/stable-pane-id'
 import { MAX_BROWSER_HISTORY_ENTRIES } from '../shared/workspace-session-browser-history'
 
 // Shared mutable state so the electron mock can reference a per-test directory
 const testState = { dir: '' }
+const TEST_LEAF_1 = '11111111-1111-4111-8111-111111111111'
+const TEST_LEAF_2 = '22222222-2222-4222-8222-222222222222'
+const TEST_LEAF_LIVE = '33333333-3333-4333-8333-333333333333'
+const TEST_LEAF_EXPIRED = '44444444-4444-4444-8444-444444444444'
 
 vi.mock('electron', () => ({
   app: {
@@ -97,18 +102,18 @@ function makeSessionWithTerminalBuffers(): WorkspaceSessionState {
     },
     terminalLayoutsByTabId: {
       'local-tab': {
-        root: { type: 'leaf', leafId: 'leaf-local' },
-        activeLeafId: 'leaf-local',
+        root: { type: 'leaf', leafId: TEST_LEAF_1 },
+        activeLeafId: TEST_LEAF_1,
         expandedLeafId: null,
-        buffersByLeafId: { 'leaf-local': 'local-scrollback' },
-        ptyIdsByLeafId: { 'leaf-local': 'local-pty' }
+        buffersByLeafId: { [TEST_LEAF_1]: 'local-scrollback' },
+        ptyIdsByLeafId: { [TEST_LEAF_1]: 'local-pty' }
       },
       'remote-tab': {
-        root: { type: 'leaf', leafId: 'leaf-remote' },
-        activeLeafId: 'leaf-remote',
+        root: { type: 'leaf', leafId: TEST_LEAF_2 },
+        activeLeafId: TEST_LEAF_2,
         expandedLeafId: null,
-        buffersByLeafId: { 'leaf-remote': 'remote-scrollback' },
-        ptyIdsByLeafId: { 'leaf-remote': 'remote-pty' }
+        buffersByLeafId: { [TEST_LEAF_2]: 'remote-scrollback' },
+        ptyIdsByLeafId: { [TEST_LEAF_2]: 'remote-pty' }
       }
     }
   }
@@ -197,6 +202,24 @@ describe('Store', () => {
     expect(repos[0].gitUsername).toBe('testuser')
   })
 
+  it('drops malformed migration-unsupported PTY entries on load', async () => {
+    const repo = makeRepo()
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [repo],
+      worktreeMeta: {},
+      settings: {},
+      ui: {},
+      githubCache: { pr: {}, issue: {} },
+      workspaceSession: {},
+      migrationUnsupportedPtyEntries: {}
+    })
+
+    const store = await createStore()
+
+    expect(store.getRepos()).toHaveLength(1)
+  })
+
   it('can clear an automation back to the project default branch', async () => {
     const store = await createStore()
     store.addRepo(makeRepo({ worktreeBaseRef: 'origin/main' }))
@@ -1048,10 +1071,10 @@ describe('Store', () => {
     const session = store.getWorkspaceSession()
     expect(session.terminalLayoutsByTabId['local-tab'].buffersByLeafId).toBeUndefined()
     expect(session.terminalLayoutsByTabId['local-tab'].ptyIdsByLeafId).toEqual({
-      'leaf-local': 'local-pty'
+      [TEST_LEAF_1]: 'local-pty'
     })
     expect(session.terminalLayoutsByTabId['remote-tab'].buffersByLeafId).toEqual({
-      'leaf-remote': 'remote-scrollback'
+      [TEST_LEAF_2]: 'remote-scrollback'
     })
   })
 
@@ -1087,10 +1110,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         'remote-tab': {
-          root: { type: 'leaf', leafId: 'leaf-remote' },
-          activeLeafId: 'leaf-remote',
+          root: { type: 'leaf', leafId: TEST_LEAF_2 },
+          activeLeafId: TEST_LEAF_2,
           expandedLeafId: null,
-          buffersByLeafId: { 'leaf-remote': 'maybe-remote-scrollback' }
+          buffersByLeafId: { [TEST_LEAF_2]: 'maybe-remote-scrollback' }
         }
       }
     })
@@ -1098,7 +1121,7 @@ describe('Store', () => {
     expect(
       store.getWorkspaceSession().terminalLayoutsByTabId['remote-tab'].buffersByLeafId
     ).toEqual({
-      'leaf-remote': 'maybe-remote-scrollback'
+      [TEST_LEAF_2]: 'maybe-remote-scrollback'
     })
   })
 
@@ -1120,7 +1143,7 @@ describe('Store', () => {
     const session = store.getWorkspaceSession()
     expect(session.terminalLayoutsByTabId['local-tab'].buffersByLeafId).toBeUndefined()
     expect(session.terminalLayoutsByTabId['remote-tab'].buffersByLeafId).toEqual({
-      'leaf-remote': 'remote-scrollback'
+      [TEST_LEAF_2]: 'remote-scrollback'
     })
   })
 
@@ -1141,16 +1164,121 @@ describe('Store', () => {
     expect(session.browserUrlHistory?.at(-1)?.url).toBe('https://example.com/199')
   })
 
-  it('does not restore cleared SSH bindings after a lease expired', async () => {
-    const store = await createStore()
-    store.upsertSshRemotePtyLease({
-      targetId: 'ssh-1',
-      ptyId: 'remote-pty',
-      worktreeId: 'wt1',
-      tabId: 'tab1',
-      leafId: 'leaf1',
-      state: 'expired'
+  it('remaps legacy SSH lease leaf ids when loading legacy workspace layouts', async () => {
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [],
+      worktreeMeta: {},
+      settings: {},
+      ui: {},
+      githubCache: { pr: {}, issue: {} },
+      workspaceSession: {
+        activeRepoId: 'r1',
+        activeWorktreeId: 'wt1',
+        activeTabId: 'tab1',
+        tabsByWorktree: {
+          wt1: [
+            {
+              id: 'tab1',
+              worktreeId: 'wt1',
+              title: 'Terminal',
+              customTitle: null,
+              color: null,
+              sortOrder: 0,
+              createdAt: 1,
+              ptyId: 'remote-pty'
+            }
+          ]
+        },
+        terminalLayoutsByTabId: {
+          tab1: {
+            root: { type: 'leaf', leafId: 'pane:1' },
+            activeLeafId: 'pane:1',
+            expandedLeafId: null,
+            ptyIdsByLeafId: { 'pane:1': 'remote-pty' }
+          }
+        }
+      },
+      sshRemotePtyLeases: [
+        {
+          targetId: 'ssh-1',
+          ptyId: 'remote-pty',
+          worktreeId: 'wt1',
+          tabId: 'tab1',
+          leafId: 'pane:1',
+          state: 'detached',
+          createdAt: 1,
+          updatedAt: 1
+        }
+      ]
     })
+
+    const store = await createStore()
+    const layout = store.getWorkspaceSession().terminalLayoutsByTabId.tab1
+    const leafId = layout.root?.type === 'leaf' ? layout.root.leafId : null
+    if (leafId === null) {
+      throw new Error('Expected remapped leaf id')
+    }
+    expect(isTerminalLeafId(leafId)).toBe(true)
+    expect(layout.ptyIdsByLeafId).toEqual({ [leafId]: 'remote-pty' })
+    expect(store.getSshRemotePtyLeases('ssh-1')[0].leafId).toBe(leafId)
+  })
+
+  it('remaps legacy SSH lease leaf ids by PTY when the layout is already normalized', async () => {
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [],
+      worktreeMeta: {},
+      settings: {},
+      ui: {},
+      githubCache: { pr: {}, issue: {} },
+      workspaceSession: {
+        activeRepoId: 'r1',
+        activeWorktreeId: 'wt1',
+        activeTabId: 'tab1',
+        tabsByWorktree: {
+          wt1: [
+            {
+              id: 'tab1',
+              worktreeId: 'wt1',
+              title: 'Terminal',
+              customTitle: null,
+              color: null,
+              sortOrder: 0,
+              createdAt: 1,
+              ptyId: 'remote-pty'
+            }
+          ]
+        },
+        terminalLayoutsByTabId: {
+          tab1: {
+            root: { type: 'leaf', leafId: TEST_LEAF_1 },
+            activeLeafId: TEST_LEAF_1,
+            expandedLeafId: null,
+            ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty' }
+          }
+        }
+      },
+      sshRemotePtyLeases: [
+        {
+          targetId: 'ssh-1',
+          ptyId: 'remote-pty',
+          worktreeId: 'wt1',
+          tabId: 'tab1',
+          leafId: 'pane:1',
+          state: 'detached',
+          createdAt: 1,
+          updatedAt: 1
+        }
+      ]
+    })
+
+    const store = await createStore()
+    expect(store.getSshRemotePtyLeases('ssh-1')[0].leafId).toBe(TEST_LEAF_1)
+  })
+
+  it('normalizes stale legacy session writes to prior UUID leaves before preserving bindings', async () => {
+    const store = await createStore()
     store.setWorkspaceSession({
       activeRepoId: 'r1',
       activeWorktreeId: 'wt1',
@@ -1171,10 +1299,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty' }
         }
       }
     })
@@ -1199,8 +1327,402 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: 'pane:1' },
+          activeLeafId: 'pane:1',
+          expandedLeafId: null,
+          ptyIdsByLeafId: {}
+        }
+      }
+    })
+
+    const session = store.getWorkspaceSession()
+    const layout = session.terminalLayoutsByTabId.tab1
+    expect(layout.root).toEqual({ type: 'leaf', leafId: TEST_LEAF_1 })
+    expect(layout.ptyIdsByLeafId).toEqual({ [TEST_LEAF_1]: 'remote-pty' })
+    expect(session.tabsByWorktree.wt1[0].ptyId).toBe('remote-pty')
+  })
+
+  it('promotes an empty tab layout to a durable UUID root when persisting the first PTY binding', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: null
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: null,
+          activeLeafId: null,
+          expandedLeafId: null
+        }
+      }
+    })
+
+    store.persistPtyBinding({
+      worktreeId: 'wt1',
+      tabId: 'tab1',
+      leafId: TEST_LEAF_1,
+      ptyId: 'daemon-pty'
+    })
+
+    const session = store.getWorkspaceSession()
+    expect(session.tabsByWorktree.wt1[0].ptyId).toBe('daemon-pty')
+    expect(session.terminalLayoutsByTabId.tab1).toEqual({
+      root: { type: 'leaf', leafId: TEST_LEAF_1 },
+      activeLeafId: TEST_LEAF_1,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [TEST_LEAF_1]: 'daemon-pty' }
+    })
+  })
+
+  it('adds a missing split leaf to the durable root when a new pane spawns before layout debounce', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: 'pty-1'
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'pty-1' }
+        }
+      }
+    })
+
+    store.persistPtyBinding({
+      worktreeId: 'wt1',
+      tabId: 'tab1',
+      leafId: TEST_LEAF_2,
+      ptyId: 'pty-2'
+    })
+
+    const layout = store.getWorkspaceSession().terminalLayoutsByTabId.tab1
+    expect(layout.root).toEqual({
+      type: 'split',
+      direction: 'vertical',
+      first: { type: 'leaf', leafId: TEST_LEAF_1 },
+      second: { type: 'leaf', leafId: TEST_LEAF_2 }
+    })
+    expect(layout.activeLeafId).toBe(TEST_LEAF_2)
+    expect(layout.ptyIdsByLeafId).toEqual({
+      [TEST_LEAF_1]: 'pty-1',
+      [TEST_LEAF_2]: 'pty-2'
+    })
+
+    const reloaded = await createStore()
+    expect(reloaded.getWorkspaceSession().terminalLayoutsByTabId.tab1.ptyIdsByLeafId).toEqual({
+      [TEST_LEAF_1]: 'pty-1',
+      [TEST_LEAF_2]: 'pty-2'
+    })
+  })
+
+  it('preserves a sync-persisted UUID root when a stale empty layout write arrives', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: null
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: null,
+          activeLeafId: null,
+          expandedLeafId: null
+        }
+      }
+    })
+
+    store.persistPtyBinding({
+      worktreeId: 'wt1',
+      tabId: 'tab1',
+      leafId: TEST_LEAF_1,
+      ptyId: 'daemon-pty'
+    })
+
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: null
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: null,
+          activeLeafId: null,
+          expandedLeafId: null,
+          ptyIdsByLeafId: {}
+        }
+      }
+    })
+
+    const session = store.getWorkspaceSession()
+    expect(session.tabsByWorktree.wt1[0].ptyId).toBe('daemon-pty')
+    expect(session.terminalLayoutsByTabId.tab1).toEqual({
+      root: { type: 'leaf', leafId: TEST_LEAF_1 },
+      activeLeafId: TEST_LEAF_1,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [TEST_LEAF_1]: 'daemon-pty' }
+    })
+  })
+
+  it('drops legacy leaf-keyed records from mixed-version writes before binding preservation', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: 'daemon-pty'
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'daemon-pty' },
+          buffersByLeafId: { [TEST_LEAF_1]: 'Current buffer' },
+          titlesByLeafId: { [TEST_LEAF_1]: 'Current' }
+        }
+      }
+    })
+
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: null
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: 'pane:1',
+          expandedLeafId: 'pane:1',
+          ptyIdsByLeafId: { 'pane:1': 'stale-pty' },
+          buffersByLeafId: { 'pane:1': 'Stale buffer' },
+          titlesByLeafId: { 'pane:1': 'Stale' }
+        }
+      }
+    })
+
+    const session = store.getWorkspaceSession()
+    const layout = session.terminalLayoutsByTabId.tab1
+    expect(layout.activeLeafId).toBe(TEST_LEAF_1)
+    expect(layout.expandedLeafId).toBeNull()
+    expect(layout.ptyIdsByLeafId).toEqual({ [TEST_LEAF_1]: 'daemon-pty' })
+    expect(layout.buffersByLeafId).toEqual({ [TEST_LEAF_1]: 'Current buffer' })
+    expect(layout.titlesByLeafId).toEqual({ [TEST_LEAF_1]: 'Current' })
+    expect(session.tabsByWorktree.wt1[0].ptyId).toBe('daemon-pty')
+  })
+
+  it('does not reuse prior UUID leaves by position when legacy leaf counts changed', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: null
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: {
+            type: 'split',
+            direction: 'horizontal',
+            first: { type: 'leaf', leafId: TEST_LEAF_1 },
+            second: { type: 'leaf', leafId: TEST_LEAF_2 },
+            ratio: 0.5
+          },
+          activeLeafId: TEST_LEAF_1,
+          expandedLeafId: null
+        }
+      }
+    })
+
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: null
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: { type: 'leaf', leafId: 'pane:1' },
+          activeLeafId: 'pane:1',
+          expandedLeafId: null
+        }
+      }
+    })
+
+    const root = store.getWorkspaceSession().terminalLayoutsByTabId.tab1.root
+    const leafId = root?.type === 'leaf' ? root.leafId : null
+    if (leafId === null) {
+      throw new Error('Expected normalized leaf')
+    }
+    expect(isTerminalLeafId(leafId)).toBe(true)
+    expect(leafId).not.toBe(TEST_LEAF_1)
+    expect(leafId).not.toBe(TEST_LEAF_2)
+  })
+
+  it('does not restore cleared SSH bindings after a lease expired', async () => {
+    const store = await createStore()
+    store.upsertSshRemotePtyLease({
+      targetId: 'ssh-1',
+      ptyId: 'remote-pty',
+      worktreeId: 'wt1',
+      tabId: 'tab1',
+      leafId: TEST_LEAF_1,
+      state: 'expired'
+    })
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: 'remote-pty'
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty' }
+        }
+      }
+    })
+
+    store.setWorkspaceSession({
+      activeRepoId: 'r1',
+      activeWorktreeId: 'wt1',
+      activeTabId: 'tab1',
+      tabsByWorktree: {
+        wt1: [
+          {
+            id: 'tab1',
+            worktreeId: 'wt1',
+            title: 'Terminal',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1,
+            ptyId: null
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        tab1: {
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
           ptyIdsByLeafId: {}
         }
@@ -1219,7 +1741,7 @@ describe('Store', () => {
       ptyId: 'remote-pty',
       worktreeId: 'wt1',
       tabId: 'tab-expired',
-      leafId: 'leaf-expired',
+      leafId: TEST_LEAF_EXPIRED,
       state: 'expired'
     })
     store.setWorkspaceSession({
@@ -1242,10 +1764,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         'tab-live': {
-          root: { type: 'leaf', leafId: 'leaf-live' },
-          activeLeafId: 'leaf-live',
+          root: { type: 'leaf', leafId: TEST_LEAF_LIVE },
+          activeLeafId: TEST_LEAF_LIVE,
           expandedLeafId: null,
-          ptyIdsByLeafId: { 'leaf-live': 'remote-pty' }
+          ptyIdsByLeafId: { [TEST_LEAF_LIVE]: 'remote-pty' }
         }
       }
     })
@@ -1270,8 +1792,8 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         'tab-live': {
-          root: { type: 'leaf', leafId: 'leaf-live' },
-          activeLeafId: 'leaf-live',
+          root: { type: 'leaf', leafId: TEST_LEAF_LIVE },
+          activeLeafId: TEST_LEAF_LIVE,
           expandedLeafId: null,
           ptyIdsByLeafId: {}
         }
@@ -1281,7 +1803,7 @@ describe('Store', () => {
     const session = store.getWorkspaceSession()
     expect(session.tabsByWorktree.wt1[0].ptyId).toBe('remote-pty')
     expect(session.terminalLayoutsByTabId['tab-live'].ptyIdsByLeafId).toEqual({
-      'leaf-live': 'remote-pty'
+      [TEST_LEAF_LIVE]: 'remote-pty'
     })
   })
 
@@ -1293,7 +1815,7 @@ describe('Store', () => {
       ptyId: 'remote-pty',
       worktreeId: 'repo-live::/wt',
       tabId: 'tab-live',
-      leafId: 'leaf-live',
+      leafId: TEST_LEAF_LIVE,
       state: 'expired'
     })
     store.upsertSshRemotePtyLease({
@@ -1301,7 +1823,7 @@ describe('Store', () => {
       ptyId: 'remote-pty',
       worktreeId: 'repo-live::/wt',
       tabId: 'tab-live',
-      leafId: 'leaf-live',
+      leafId: TEST_LEAF_LIVE,
       state: 'detached'
     })
     store.setWorkspaceSession({
@@ -1324,10 +1846,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         'tab-live': {
-          root: { type: 'leaf', leafId: 'leaf-live' },
-          activeLeafId: 'leaf-live',
+          root: { type: 'leaf', leafId: TEST_LEAF_LIVE },
+          activeLeafId: TEST_LEAF_LIVE,
           expandedLeafId: null,
-          ptyIdsByLeafId: { 'leaf-live': 'remote-pty' }
+          ptyIdsByLeafId: { [TEST_LEAF_LIVE]: 'remote-pty' }
         }
       }
     })
@@ -1352,8 +1874,8 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         'tab-live': {
-          root: { type: 'leaf', leafId: 'leaf-live' },
-          activeLeafId: 'leaf-live',
+          root: { type: 'leaf', leafId: TEST_LEAF_LIVE },
+          activeLeafId: TEST_LEAF_LIVE,
           expandedLeafId: null,
           ptyIdsByLeafId: {}
         }
@@ -1363,7 +1885,7 @@ describe('Store', () => {
     const session = store.getWorkspaceSession()
     expect(session.tabsByWorktree['repo-live::/wt'][0].ptyId).toBe('remote-pty')
     expect(session.terminalLayoutsByTabId['tab-live'].ptyIdsByLeafId).toEqual({
-      'leaf-live': 'remote-pty'
+      [TEST_LEAF_LIVE]: 'remote-pty'
     })
   })
 
@@ -1394,10 +1916,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty' }
         }
       }
     })
@@ -1422,8 +1944,8 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
           ptyIdsByLeafId: {}
         }
@@ -1432,7 +1954,9 @@ describe('Store', () => {
 
     const session = store.getWorkspaceSession()
     expect(session.tabsByWorktree.wt1[0].ptyId).toBe('remote-pty')
-    expect(session.terminalLayoutsByTabId.tab1.ptyIdsByLeafId).toEqual({ leaf1: 'remote-pty' })
+    expect(session.terminalLayoutsByTabId.tab1.ptyIdsByLeafId).toEqual({
+      [TEST_LEAF_1]: 'remote-pty'
+    })
   })
 
   it('does not treat layout-level leases missing worktree context as contextual matches', async () => {
@@ -1441,7 +1965,7 @@ describe('Store', () => {
       targetId: 'ssh-1',
       ptyId: 'remote-pty',
       tabId: 'tab1',
-      leafId: 'leaf1',
+      leafId: TEST_LEAF_1,
       state: 'expired'
     })
     store.setWorkspaceSession({
@@ -1464,10 +1988,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty' }
         }
       }
     })
@@ -1492,8 +2016,8 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
           ptyIdsByLeafId: {}
         }
@@ -1501,7 +2025,7 @@ describe('Store', () => {
     })
 
     expect(store.getWorkspaceSession().terminalLayoutsByTabId.tab1.ptyIdsByLeafId).toEqual({
-      leaf1: 'remote-pty'
+      [TEST_LEAF_1]: 'remote-pty'
     })
   })
 
@@ -1512,7 +2036,7 @@ describe('Store', () => {
       ptyId: 'remote-pty-1',
       worktreeId: 'wt1',
       tabId: 'tab1',
-      leafId: 'leaf1',
+      leafId: TEST_LEAF_1,
       state: 'detached'
     })
     store.upsertSshRemotePtyLease({
@@ -1520,7 +2044,7 @@ describe('Store', () => {
       ptyId: 'remote-pty-2',
       worktreeId: 'wt1',
       tabId: 'tab1',
-      leafId: 'leaf2',
+      leafId: TEST_LEAF_2,
       state: 'detached'
     })
     store.setWorkspaceSession({
@@ -1546,13 +2070,16 @@ describe('Store', () => {
           root: {
             type: 'split',
             direction: 'horizontal',
-            first: { type: 'leaf', leafId: 'leaf1' },
-            second: { type: 'leaf', leafId: 'leaf2' },
+            first: { type: 'leaf', leafId: TEST_LEAF_1 },
+            second: { type: 'leaf', leafId: TEST_LEAF_2 },
             ratio: 0.5
           },
-          activeLeafId: 'leaf2',
+          activeLeafId: TEST_LEAF_2,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty-1', leaf2: 'remote-pty-2' }
+          ptyIdsByLeafId: {
+            [TEST_LEAF_1]: 'remote-pty-1',
+            [TEST_LEAF_2]: 'remote-pty-2'
+          }
         }
       }
     })
@@ -1580,20 +2107,20 @@ describe('Store', () => {
           root: {
             type: 'split',
             direction: 'horizontal',
-            first: { type: 'leaf', leafId: 'leaf1' },
-            second: { type: 'leaf', leafId: 'leaf2' },
+            first: { type: 'leaf', leafId: TEST_LEAF_1 },
+            second: { type: 'leaf', leafId: TEST_LEAF_2 },
             ratio: 0.5
           },
-          activeLeafId: 'leaf1',
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty-1' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty-1' }
         }
       }
     })
 
     expect(store.getWorkspaceSession().terminalLayoutsByTabId.tab1.ptyIdsByLeafId).toEqual({
-      leaf1: 'remote-pty-1',
-      leaf2: 'remote-pty-2'
+      [TEST_LEAF_1]: 'remote-pty-1',
+      [TEST_LEAF_2]: 'remote-pty-2'
     })
   })
 
@@ -1603,14 +2130,14 @@ describe('Store', () => {
       targetId: 'ssh-1',
       ptyId: 'remote-pty-1',
       tabId: 'tab1',
-      leafId: 'leaf1',
+      leafId: TEST_LEAF_1,
       state: 'detached'
     })
     store.upsertSshRemotePtyLease({
       targetId: 'ssh-1',
       ptyId: 'remote-pty-2',
       tabId: 'tab1',
-      leafId: 'leaf2',
+      leafId: TEST_LEAF_2,
       state: 'detached'
     })
     store.setWorkspaceSession({
@@ -1636,13 +2163,16 @@ describe('Store', () => {
           root: {
             type: 'split',
             direction: 'horizontal',
-            first: { type: 'leaf', leafId: 'leaf1' },
-            second: { type: 'leaf', leafId: 'leaf2' },
+            first: { type: 'leaf', leafId: TEST_LEAF_1 },
+            second: { type: 'leaf', leafId: TEST_LEAF_2 },
             ratio: 0.5
           },
-          activeLeafId: 'leaf2',
+          activeLeafId: TEST_LEAF_2,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty-1', leaf2: 'remote-pty-2' }
+          ptyIdsByLeafId: {
+            [TEST_LEAF_1]: 'remote-pty-1',
+            [TEST_LEAF_2]: 'remote-pty-2'
+          }
         }
       }
     })
@@ -1667,16 +2197,16 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty-1' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty-1' }
         }
       }
     })
 
     expect(store.getWorkspaceSession().terminalLayoutsByTabId.tab1.ptyIdsByLeafId).toEqual({
-      leaf1: 'remote-pty-1'
+      [TEST_LEAF_1]: 'remote-pty-1'
     })
   })
 
@@ -1705,13 +2235,16 @@ describe('Store', () => {
           root: {
             type: 'split',
             direction: 'horizontal',
-            first: { type: 'leaf', leafId: 'leaf1' },
-            second: { type: 'leaf', leafId: 'leaf2' },
+            first: { type: 'leaf', leafId: TEST_LEAF_1 },
+            second: { type: 'leaf', leafId: TEST_LEAF_2 },
             ratio: 0.5
           },
-          activeLeafId: 'leaf2',
+          activeLeafId: TEST_LEAF_2,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'local-pty-1', leaf2: 'local-pty-2' }
+          ptyIdsByLeafId: {
+            [TEST_LEAF_1]: 'local-pty-1',
+            [TEST_LEAF_2]: 'local-pty-2'
+          }
         }
       }
     })
@@ -1739,19 +2272,19 @@ describe('Store', () => {
           root: {
             type: 'split',
             direction: 'horizontal',
-            first: { type: 'leaf', leafId: 'leaf1' },
-            second: { type: 'leaf', leafId: 'leaf2' },
+            first: { type: 'leaf', leafId: TEST_LEAF_1 },
+            second: { type: 'leaf', leafId: TEST_LEAF_2 },
             ratio: 0.5
           },
-          activeLeafId: 'leaf1',
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'local-pty-1' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'local-pty-1' }
         }
       }
     })
 
     expect(store.getWorkspaceSession().terminalLayoutsByTabId.tab1.ptyIdsByLeafId).toEqual({
-      leaf1: 'local-pty-1'
+      [TEST_LEAF_1]: 'local-pty-1'
     })
   })
 
@@ -1762,7 +2295,7 @@ describe('Store', () => {
       ptyId: 'remote-pty',
       worktreeId: 'wt1',
       tabId: 'tab1',
-      leafId: 'leaf1',
+      leafId: TEST_LEAF_1,
       state: 'detached'
     })
     store.setWorkspaceSession({
@@ -1785,10 +2318,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty' }
         }
       }
     })
@@ -1828,10 +2361,10 @@ describe('Store', () => {
       },
       terminalLayoutsByTabId: {
         tab1: {
-          root: { type: 'leaf', leafId: 'leaf1' },
-          activeLeafId: 'leaf1',
+          root: { type: 'leaf', leafId: TEST_LEAF_1 },
+          activeLeafId: TEST_LEAF_1,
           expandedLeafId: null,
-          ptyIdsByLeafId: { leaf1: 'remote-pty' }
+          ptyIdsByLeafId: { [TEST_LEAF_1]: 'remote-pty' }
         }
       }
     })
diff --git a/src/main/persistence.ts b/src/main/persistence.ts
index 28e2804a31b..00bb9bc4409 100644
--- a/src/main/persistence.ts
+++ b/src/main/persistence.ts
@@ -37,8 +37,12 @@ import type {
   OnboardingChecklistState,
   OnboardingOutcome,
   OnboardingState,
-  TerminalPaneLayoutNode
+  TerminalPaneLayoutNode,
+  TerminalLayoutSnapshot,
+  TerminalTab,
+  WorkspaceSessionState
 } from '../shared/types'
+import type { MigrationUnsupportedPtyEntry } from '../shared/agent-status-types'
 import type { SshRemotePtyLease, SshTarget } from '../shared/ssh-types'
 import { isFolderRepo } from '../shared/repo-kind'
 import { getGitUsername } from './git/repo'
@@ -53,6 +57,11 @@ import {
   ONBOARDING_FINAL_STEP
 } from '../shared/constants'
 import { parseWorkspaceSession } from '../shared/workspace-session-schema'
+import { isTerminalLeafId, makePaneKey } from '../shared/stable-pane-id'
+import {
+  setMigrationUnsupportedPty,
+  setMigrationUnsupportedPtyPersistenceListener
+} from './agent-hooks/migration-unsupported-pty-state'
 import { pruneLocalTerminalScrollbackBuffers } from '../shared/workspace-session-terminal-buffers'
 import { pruneWorkspaceSessionBrowserHistory } from '../shared/workspace-session-browser-history'
 import { getRepoIdFromWorktreeId } from '../shared/worktree-id'
@@ -261,7 +270,7 @@ function normalizeSshRemotePtyLease(value: unknown): SshRemotePtyLease | null {
     ptyId: raw.ptyId,
     ...(typeof raw.worktreeId === 'string' ? { worktreeId: raw.worktreeId } : {}),
     ...(typeof raw.tabId === 'string' ? { tabId: raw.tabId } : {}),
-    ...(typeof raw.leafId === 'string' ? { leafId: raw.leafId } : {}),
+    ...(typeof raw.leafId === 'string' && raw.leafId.length <= 256 ? { leafId: raw.leafId } : {}),
     state,
     createdAt: typeof raw.createdAt === 'number' ? raw.createdAt : now,
     updatedAt: typeof raw.updatedAt === 'number' ? raw.updatedAt : now,
@@ -270,6 +279,527 @@ function normalizeSshRemotePtyLease(value: unknown): SshRemotePtyLease | null {
   }
 }
 
+type LayoutLeafNormalization = {
+  snapshot: TerminalLayoutSnapshot
+  changed: boolean
+  leafIdByInputLeafId: Map<string, string>
+}
+
+function collectLayoutLeafCounts(
+  node: TerminalPaneLayoutNode,
+  counts: Map<string, number> = new Map()
+): Map<string, number> {
+  if (node.type === 'leaf') {
+    counts.set(node.leafId, (counts.get(node.leafId) ?? 0) + 1)
+    return counts
+  }
+  collectLayoutLeafCounts(node.first, counts)
+  collectLayoutLeafCounts(node.second, counts)
+  return counts
+}
+
+function collectLayoutLeafIdsInOrder(node: TerminalPaneLayoutNode | null | undefined): string[] {
+  if (!node) {
+    return []
+  }
+  if (node.type === 'leaf') {
+    return [node.leafId]
+  }
+  return [...collectLayoutLeafIdsInOrder(node.first), ...collectLayoutLeafIdsInOrder(node.second)]
+}
+
+function firstLayoutLeafId(node: TerminalPaneLayoutNode | null): string | null {
+  if (!node) {
+    return null
+  }
+  return node.type === 'leaf' ? node.leafId : firstLayoutLeafId(node.first)
+}
+
+function layoutContainsLeafId(node: TerminalPaneLayoutNode | null, leafId: string): boolean {
+  if (!node) {
+    return false
+  }
+  if (node.type === 'leaf') {
+    return node.leafId === leafId
+  }
+  return layoutContainsLeafId(node.first, leafId) || layoutContainsLeafId(node.second, leafId)
+}
+
+function cloneLayoutNode(node: TerminalPaneLayoutNode): TerminalPaneLayoutNode {
+  if (node.type === 'leaf') {
+    return { type: 'leaf', leafId: node.leafId }
+  }
+  return {
+    ...node,
+    first: cloneLayoutNode(node.first),
+    second: cloneLayoutNode(node.second)
+  }
+}
+
+function cloneLayoutWithLeafIds(
+  node: TerminalPaneLayoutNode,
+  leafIdByInputLeafId: Map<string, string>,
+  duplicatedInputLeafIds: Set<string>
+): TerminalPaneLayoutNode {
+  if (node.type === 'leaf') {
+    return {
+      type: 'leaf',
+      leafId: duplicatedInputLeafIds.has(node.leafId)
+        ? randomUUID()
+        : (leafIdByInputLeafId.get(node.leafId) ?? randomUUID())
+    }
+  }
+  return {
+    ...node,
+    first: cloneLayoutWithLeafIds(node.first, leafIdByInputLeafId, duplicatedInputLeafIds),
+    second: cloneLayoutWithLeafIds(node.second, leafIdByInputLeafId, duplicatedInputLeafIds)
+  }
+}
+
+function remapLeafRecordForPersistence(
+  source: Record<string, string> | undefined,
+  leafIdByInputLeafId: Map<string, string>,
+  duplicatedInputLeafIds: Set<string>
+): Record<string, string> | undefined {
+  if (!source) {
+    return undefined
+  }
+  const next: Record<string, string> = {}
+  for (const [leafId, value] of Object.entries(source)) {
+    if (duplicatedInputLeafIds.has(leafId)) {
+      continue
+    }
+    const nextLeafId = leafIdByInputLeafId.get(leafId)
+    if (nextLeafId) {
+      next[nextLeafId] = value
+    }
+  }
+  return Object.keys(next).length > 0 ? next : undefined
+}
+
+function leafRecordEquivalent(
+  left: Record<string, string> | undefined,
+  right: Record<string, string> | undefined
+): boolean {
+  const leftEntries = Object.entries(left ?? {})
+  const rightRecord = right ?? {}
+  if (leftEntries.length !== Object.keys(rightRecord).length) {
+    return false
+  }
+  return leftEntries.every(([key, value]) => rightRecord[key] === value)
+}
+
+function preserveMissingLeafRecordEntries(
+  priorRecord: Record<string, string> | undefined,
+  incomingRecord: Record<string, string> | undefined,
+  liveLeafIds: Set<string>
+): Record<string, string> | undefined {
+  const preserved = Object.fromEntries(
+    Object.entries(priorRecord ?? {}).filter(
+      ([leafId]) => liveLeafIds.has(leafId) && incomingRecord?.[leafId] === undefined
+    )
+  )
+  const next = { ...preserved, ...incomingRecord }
+  return Object.keys(next).length > 0 ? next : undefined
+}
+
+function findWorktreeIdForTab(session: WorkspaceSessionState, tabId: string): string | undefined {
+  for (const [worktreeId, tabs] of Object.entries(session.tabsByWorktree ?? {})) {
+    if (tabs.some((tab) => tab.id === tabId)) {
+      return worktreeId
+    }
+  }
+  return undefined
+}
+
+function collectMigrationUnsupportedPtyEntries(args: {
+  session: WorkspaceSessionState
+  tabId: string
+  inputLayout: TerminalLayoutSnapshot
+  normalizedLayout: TerminalLayoutSnapshot
+  leafIdByInputLeafId: Map<string, string>
+  sourceForPtyId: (ptyId: string) => 'local' | 'ssh'
+}): MigrationUnsupportedPtyEntry[] {
+  const entries: MigrationUnsupportedPtyEntry[] = []
+  const worktreeId = findWorktreeIdForTab(args.session, args.tabId)
+  const tab = worktreeId
+    ? args.session.tabsByWorktree?.[worktreeId]?.find((entry) => entry.id === args.tabId)
+    : undefined
+  const pushEntry = (ptyId: string, leafId: string): void => {
+    if (!isTerminalLeafId(leafId)) {
+      return
+    }
+    let paneKey: string
+    try {
+      paneKey = makePaneKey(args.tabId, leafId)
+    } catch {
+      return
+    }
+    entries.push({
+      ptyId,
+      ...(worktreeId ? { worktreeId } : {}),
+      tabId: args.tabId,
+      leafId,
+      paneKey,
+      reason: 'legacy-numeric-pane-key',
+      source: args.sourceForPtyId(ptyId),
+      updatedAt: Date.now()
+    })
+  }
+  for (const [inputLeafId, ptyId] of Object.entries(args.inputLayout.ptyIdsByLeafId ?? {})) {
+    if (isTerminalLeafId(inputLeafId)) {
+      continue
+    }
+    const leafId = args.leafIdByInputLeafId.get(inputLeafId)
+    if (leafId) {
+      pushEntry(ptyId, leafId)
+    }
+  }
+  if (
+    entries.length === 0 &&
+    tab?.ptyId &&
+    Object.keys(args.inputLayout.ptyIdsByLeafId ?? {}).length === 0
+  ) {
+    const fallbackLeafId =
+      args.normalizedLayout.activeLeafId ?? firstLayoutLeafId(args.normalizedLayout.root)
+    if (fallbackLeafId) {
+      // Why: older single-pane sessions can reattach from tab.ptyId only, with
+      // no leaf binding to migrate. Their live shell env can still hold the
+      // legacy pane key, so surface the restart-required row for that PTY.
+      pushEntry(tab.ptyId, fallbackLeafId)
+    }
+  }
+  return entries
+}
+
+function normalizeTerminalLayoutSnapshotForPersistence(
+  snapshot: TerminalLayoutSnapshot,
+  preferredLayout?: TerminalLayoutSnapshot
+): LayoutLeafNormalization {
+  let inputSnapshot = snapshot
+  let changed = false
+  if (!inputSnapshot.root) {
+    if (!preferredLayout?.root) {
+      return { snapshot, changed: false, leafIdByInputLeafId: new Map() }
+    }
+    const root = cloneLayoutNode(preferredLayout.root)
+    const rootLeafIds = new Set(collectLayoutLeafIdsInOrder(root))
+    const activeLeafId =
+      (inputSnapshot.activeLeafId && rootLeafIds.has(inputSnapshot.activeLeafId)
+        ? inputSnapshot.activeLeafId
+        : null) ??
+      (preferredLayout.activeLeafId && rootLeafIds.has(preferredLayout.activeLeafId)
+        ? preferredLayout.activeLeafId
+        : null) ??
+      firstLayoutLeafId(root)
+    const expandedLeafId =
+      (inputSnapshot.expandedLeafId && rootLeafIds.has(inputSnapshot.expandedLeafId)
+        ? inputSnapshot.expandedLeafId
+        : null) ??
+      (preferredLayout.expandedLeafId && rootLeafIds.has(preferredLayout.expandedLeafId)
+        ? preferredLayout.expandedLeafId
+        : null)
+    inputSnapshot = { ...inputSnapshot, root, activeLeafId, expandedLeafId }
+    // Why: a debounced renderer writer can still hold the createTab-era empty
+    // layout after persistPtyBinding has already sync-flushed the UUID root.
+    changed = true
+  }
+  const inputRoot = inputSnapshot.root
+  if (!inputRoot) {
+    return { snapshot, changed: false, leafIdByInputLeafId: new Map() }
+  }
+  const counts = collectLayoutLeafCounts(inputRoot)
+  const duplicatedInputLeafIds = new Set(
+    Array.from(counts.entries())
+      .filter(([, count]) => count > 1)
+      .map(([leafId]) => leafId)
+  )
+  const inputLeafIdsInOrder = collectLayoutLeafIdsInOrder(inputRoot)
+  const preferredLeafIdsInOrder = collectLayoutLeafIdsInOrder(preferredLayout?.root)
+  const usePreferredLeafIds = preferredLeafIdsInOrder.length === inputLeafIdsInOrder.length
+  const leafIdByInputLeafId = new Map<string, string>()
+  for (const [index, leafId] of inputLeafIdsInOrder.entries()) {
+    const count = counts.get(leafId) ?? 0
+    if (count !== 1 || leafIdByInputLeafId.has(leafId)) {
+      changed = true
+      continue
+    }
+    if (isTerminalLeafId(leafId)) {
+      leafIdByInputLeafId.set(leafId, leafId)
+      continue
+    }
+    changed = true
+    const preferredLeafId = usePreferredLeafIds ? preferredLeafIdsInOrder[index] : undefined
+    leafIdByInputLeafId.set(
+      leafId,
+      preferredLeafId && isTerminalLeafId(preferredLeafId) ? preferredLeafId : randomUUID()
+    )
+  }
+  const root = changed
+    ? cloneLayoutWithLeafIds(inputRoot, leafIdByInputLeafId, duplicatedInputLeafIds)
+    : inputRoot
+  const activeLeafId =
+    inputSnapshot.activeLeafId && !duplicatedInputLeafIds.has(inputSnapshot.activeLeafId)
+      ? (leafIdByInputLeafId.get(inputSnapshot.activeLeafId) ?? firstLayoutLeafId(root))
+      : inputSnapshot.activeLeafId === null
+        ? null
+        : firstLayoutLeafId(root)
+  const expandedLeafId =
+    inputSnapshot.expandedLeafId && !duplicatedInputLeafIds.has(inputSnapshot.expandedLeafId)
+      ? (leafIdByInputLeafId.get(inputSnapshot.expandedLeafId) ?? null)
+      : null
+  const ptyIdsByLeafId = remapLeafRecordForPersistence(
+    inputSnapshot.ptyIdsByLeafId,
+    leafIdByInputLeafId,
+    duplicatedInputLeafIds
+  )
+  const buffersByLeafId = remapLeafRecordForPersistence(
+    inputSnapshot.buffersByLeafId,
+    leafIdByInputLeafId,
+    duplicatedInputLeafIds
+  )
+  const titlesByLeafId = remapLeafRecordForPersistence(
+    inputSnapshot.titlesByLeafId,
+    leafIdByInputLeafId,
+    duplicatedInputLeafIds
+  )
+  const recordsChanged =
+    !leafRecordEquivalent(inputSnapshot.ptyIdsByLeafId, ptyIdsByLeafId) ||
+    !leafRecordEquivalent(inputSnapshot.buffersByLeafId, buffersByLeafId) ||
+    !leafRecordEquivalent(inputSnapshot.titlesByLeafId, titlesByLeafId)
+  const metadataChanged =
+    activeLeafId !== inputSnapshot.activeLeafId || expandedLeafId !== inputSnapshot.expandedLeafId
+  if (!changed && !recordsChanged && !metadataChanged) {
+    return { snapshot, changed: false, leafIdByInputLeafId }
+  }
+  const {
+    ptyIdsByLeafId: _oldPtyIdsByLeafId,
+    buffersByLeafId: _oldBuffersByLeafId,
+    titlesByLeafId: _oldTitlesByLeafId,
+    ...snapshotWithoutLeafRecords
+  } = inputSnapshot
+  return {
+    snapshot: {
+      ...snapshotWithoutLeafRecords,
+      root,
+      activeLeafId,
+      expandedLeafId,
+      ...(ptyIdsByLeafId ? { ptyIdsByLeafId } : {}),
+      ...(buffersByLeafId ? { buffersByLeafId } : {}),
+      ...(titlesByLeafId ? { titlesByLeafId } : {})
+    },
+    changed: true,
+    leafIdByInputLeafId
+  }
+}
+
+function normalizeWorkspaceSessionPaneIdentities(
+  session: WorkspaceSessionState,
+  priorLayoutsByTabId: Record<string, TerminalLayoutSnapshot> = {},
+  sourceForPtyId: (ptyId: string) => 'local' | 'ssh' = () => 'local'
+): {
+  session: WorkspaceSessionState
+  changed: boolean
+  leafIdByInputLeafIdByTabId: Map<string, Map<string, string>>
+  leafIdByPtyIdByTabId: Map<string, Map<string, string>>
+  migrationUnsupportedEntries: MigrationUnsupportedPtyEntry[]
+} {
+  let changed = false
+  const leafIdByInputLeafIdByTabId = new Map<string, Map<string, string>>()
+  const leafIdByPtyIdByTabId = new Map<string, Map<string, string>>()
+  const migrationUnsupportedEntries: MigrationUnsupportedPtyEntry[] = []
+  const terminalLayoutsByTabId: Record<string, TerminalLayoutSnapshot> = {}
+  for (const [tabId, layout] of Object.entries(session.terminalLayoutsByTabId ?? {})) {
+    const normalized = normalizeTerminalLayoutSnapshotForPersistence(
+      layout,
+      priorLayoutsByTabId[tabId]
+    )
+    terminalLayoutsByTabId[tabId] = normalized.snapshot
+    leafIdByInputLeafIdByTabId.set(tabId, normalized.leafIdByInputLeafId)
+    migrationUnsupportedEntries.push(
+      ...collectMigrationUnsupportedPtyEntries({
+        session,
+        tabId,
+        inputLayout: layout,
+        normalizedLayout: normalized.snapshot,
+        leafIdByInputLeafId: normalized.leafIdByInputLeafId,
+        sourceForPtyId
+      })
+    )
+    const leafIdByPtyId = new Map<string, string>()
+    const duplicatePtyIds = new Set<string>()
+    for (const [leafId, ptyId] of Object.entries(normalized.snapshot.ptyIdsByLeafId ?? {})) {
+      if (duplicatePtyIds.has(ptyId)) {
+        continue
+      }
+      if (leafIdByPtyId.has(ptyId)) {
+        leafIdByPtyId.delete(ptyId)
+        duplicatePtyIds.add(ptyId)
+        continue
+      }
+      leafIdByPtyId.set(ptyId, leafId)
+    }
+    leafIdByPtyIdByTabId.set(tabId, leafIdByPtyId)
+    changed ||= normalized.changed
+  }
+  return {
+    session: changed ? { ...session, terminalLayoutsByTabId } : session,
+    changed,
+    leafIdByInputLeafIdByTabId,
+    leafIdByPtyIdByTabId,
+    migrationUnsupportedEntries
+  }
+}
+
+function remapSshRemotePtyLeaseLeafIds(
+  leases: SshRemotePtyLease[],
+  leafIdByInputLeafIdByTabId: Map<string, Map<string, string>>,
+  leafIdByPtyIdByTabId: Map<string, Map<string, string>>
+): { leases: SshRemotePtyLease[]; changed: boolean } {
+  let changed = false
+  const nextLeases = leases.map((lease) => {
+    if (lease.leafId === undefined || isTerminalLeafId(lease.leafId)) {
+      return lease
+    }
+    const remappedLeafId = lease.tabId
+      ? leafIdByInputLeafIdByTabId.get(lease.tabId)?.get(lease.leafId)
+      : undefined
+    const leafIdForPty = lease.tabId
+      ? leafIdByPtyIdByTabId.get(lease.tabId)?.get(lease.ptyId)
+      : undefined
+    changed = true
+    const nextLeafId = remappedLeafId ?? leafIdForPty
+    if (nextLeafId) {
+      return { ...lease, leafId: nextLeafId }
+    }
+    const next = { ...lease }
+    // Why: unmatched legacy leaf ids are ambiguous after migration; do not
+    // re-persist them as durable pane identity.
+    delete next.leafId
+    return next
+  })
+  return { leases: nextLeases, changed }
+}
+
+function normalizePersistedPaneIdentityState(state: PersistedState): {
+  state: PersistedState
+  changed: boolean
+  migrationUnsupportedEntries: MigrationUnsupportedPtyEntry[]
+} {
+  const sshPtyIds = new Set((state.sshRemotePtyLeases ?? []).map((lease) => lease.ptyId))
+  const normalizedSession = normalizeWorkspaceSessionPaneIdentities(
+    state.workspaceSession,
+    {},
+    (ptyId) => (sshPtyIds.has(ptyId) ? 'ssh' : 'local')
+  )
+  const remappedLeases = remapSshRemotePtyLeaseLeafIds(
+    state.sshRemotePtyLeases ?? [],
+    normalizedSession.leafIdByInputLeafIdByTabId,
+    normalizedSession.leafIdByPtyIdByTabId
+  )
+  const mergedMigrationUnsupportedEntries = mergeMigrationUnsupportedPtyEntries([
+    ...(state.migrationUnsupportedPtyEntries ?? []),
+    ...normalizedSession.migrationUnsupportedEntries
+  ])
+  const migrationUnsupportedChanged = !migrationUnsupportedEntriesEqual(
+    state.migrationUnsupportedPtyEntries ?? [],
+    mergedMigrationUnsupportedEntries
+  )
+  if (!normalizedSession.changed && !remappedLeases.changed && !migrationUnsupportedChanged) {
+    return {
+      state,
+      changed: false,
+      migrationUnsupportedEntries: mergedMigrationUnsupportedEntries
+    }
+  }
+  return {
+    state: {
+      ...state,
+      workspaceSession: normalizedSession.session,
+      sshRemotePtyLeases: remappedLeases.leases,
+      migrationUnsupportedPtyEntries: mergedMigrationUnsupportedEntries
+    },
+    changed: true,
+    migrationUnsupportedEntries: mergedMigrationUnsupportedEntries
+  }
+}
+
+function mergeMigrationUnsupportedPtyEntries(
+  entries: MigrationUnsupportedPtyEntry[]
+): MigrationUnsupportedPtyEntry[] {
+  const byPtyId = new Map<string, MigrationUnsupportedPtyEntry>()
+  for (const entry of entries) {
+    const existing = byPtyId.get(entry.ptyId)
+    if (!existing || existing.updatedAt <= entry.updatedAt) {
+      byPtyId.set(entry.ptyId, entry)
+    }
+  }
+  return [...byPtyId.values()]
+}
+
+function normalizeMigrationUnsupportedPtyEntries(value: unknown): MigrationUnsupportedPtyEntry[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+  return value.filter((entry): entry is MigrationUnsupportedPtyEntry => {
+    if (!entry || typeof entry !== 'object') {
+      return false
+    }
+    const candidate = entry as Partial<MigrationUnsupportedPtyEntry>
+    return (
+      typeof candidate.ptyId === 'string' &&
+      candidate.ptyId.length > 0 &&
+      (candidate.worktreeId === undefined || typeof candidate.worktreeId === 'string') &&
+      (candidate.tabId === undefined || typeof candidate.tabId === 'string') &&
+      (candidate.leafId === undefined || isTerminalLeafId(candidate.leafId)) &&
+      (candidate.paneKey === undefined || typeof candidate.paneKey === 'string') &&
+      candidate.reason === 'legacy-numeric-pane-key' &&
+      (candidate.source === 'local' || candidate.source === 'ssh') &&
+      Number.isFinite(candidate.updatedAt)
+    )
+  })
+}
+
+function migrationUnsupportedEntriesEqual(
+  left: MigrationUnsupportedPtyEntry[],
+  right: MigrationUnsupportedPtyEntry[]
+): boolean {
+  if (left.length !== right.length) {
+    return false
+  }
+  const rightByPtyId = new Map(right.map((entry) => [entry.ptyId, entry]))
+  return left.every((entry) => {
+    const other = rightByPtyId.get(entry.ptyId)
+    return other ? JSON.stringify(entry) === JSON.stringify(other) : false
+  })
+}
+
+function createMinimalPersistedTerminalTab(args: {
+  worktreeId: string
+  tabId: string
+  ptyId: string
+  existingTabCount: number
+}): TerminalTab {
+  const ordinal = args.existingTabCount + 1
+  const defaultTitle = `Terminal ${ordinal}`
+  return {
+    id: args.tabId,
+    ptyId: args.ptyId,
+    worktreeId: args.worktreeId,
+    title: defaultTitle,
+    defaultTitle,
+    customTitle: null,
+    color: null,
+    sortOrder: args.existingTabCount,
+    createdAt: Date.now(),
+    pendingActivationSpawn: true
+  }
+}
+
+function cloneWorkspaceSessionState(session: WorkspaceSessionState): WorkspaceSessionState {
+  return structuredClone(session)
+}
+
 export class Store {
   private state: PersistedState
   private writeTimer: ReturnType<typeof setTimeout> | null = null
@@ -278,7 +808,21 @@ export class Store {
   private gitUsernameCache = new Map<string, string>()
 
   constructor() {
-    this.state = this.load()
+    const loaded = this.load()
+    const normalized = normalizePersistedPaneIdentityState(loaded)
+    this.state = normalized.state
+    for (const entry of normalized.migrationUnsupportedEntries) {
+      setMigrationUnsupportedPty(entry)
+    }
+    setMigrationUnsupportedPtyPersistenceListener((entries) => {
+      this.state.migrationUnsupportedPtyEntries = entries
+      this.scheduleSave()
+    })
+    if (normalized.changed) {
+      // Why: upgraded sessions may contain legacy pane:1 leaves. Rewrite them at
+      // the main persistence boundary so older renderer writes cannot revive them.
+      this.scheduleSave()
+    }
   }
 
   // Why (issue #1158): debounced writes fire as often as every 300ms during
@@ -547,6 +1091,9 @@ export class Store {
           sshRemotePtyLeases: (parsed.sshRemotePtyLeases ?? [])
             .map(normalizeSshRemotePtyLease)
             .filter((lease): lease is SshRemotePtyLease => lease !== null),
+          migrationUnsupportedPtyEntries: normalizeMigrationUnsupportedPtyEntries(
+            parsed.migrationUnsupportedPtyEntries
+          ),
           automations: Array.isArray(parsed.automations) ? parsed.automations : [],
           automationRuns: Array.isArray(parsed.automationRuns) ? parsed.automationRuns : [],
           onboarding: (() => {
@@ -809,6 +1356,18 @@ export class Store {
     }
   }
 
+  private flushOrThrow(): void {
+    if (this.writeTimer) {
+      clearTimeout(this.writeTimer)
+      this.writeTimer = null
+    }
+    // Why: bump writeGeneration so any in-flight async writeToDiskAsync skips
+    // its rename, preventing a stale snapshot from overwriting this sync write.
+    this.writeGeneration++
+    this.pendingWrite = null
+    this.writeToDiskSync()
+  }
+
   // ── Repos ──────────────────────────────────────────────────────────
 
   getRepos(): Repo[] {
@@ -1304,6 +1863,24 @@ export class Store {
     // the durable binding and re-open the orphan window. Merge in any
     // existing bindings whenever the incoming snapshot's binding is empty.
     const prior = this.state.workspaceSession
+    const sshPtyIds = new Set((this.state.sshRemotePtyLeases ?? []).map((lease) => lease.ptyId))
+    const normalized = normalizeWorkspaceSessionPaneIdentities(
+      session,
+      prior?.terminalLayoutsByTabId,
+      (ptyId) => (sshPtyIds.has(ptyId) ? 'ssh' : 'local')
+    )
+    for (const entry of normalized.migrationUnsupportedEntries) {
+      setMigrationUnsupportedPty(entry)
+    }
+    session = normalized.session
+    const remappedLeases = remapSshRemotePtyLeaseLeafIds(
+      this.state.sshRemotePtyLeases ?? [],
+      normalized.leafIdByInputLeafIdByTabId,
+      normalized.leafIdByPtyIdByTabId
+    )
+    if (remappedLeases.changed) {
+      this.state.sshRemotePtyLeases = remappedLeases.leases
+    }
     if (session && prior) {
       const priorTabs = prior.tabsByWorktree ?? {}
       const nextTabs = session.tabsByWorktree ?? {}
@@ -1368,6 +1945,24 @@ export class Store {
         )
         if (Object.keys(restorableBindings).length > 0) {
           layout.ptyIdsByLeafId = { ...restorableBindings, ...incoming }
+          // Why: the same stale session write that drops ptyIdsByLeafId can
+          // also be from an older renderer that lacks UUID-keyed metadata.
+          const buffersByLeafId = preserveMissingLeafRecordEntries(
+            priorLayout.buffersByLeafId,
+            layout.buffersByLeafId,
+            liveLeafIds
+          )
+          const titlesByLeafId = preserveMissingLeafRecordEntries(
+            priorLayout.titlesByLeafId,
+            layout.titlesByLeafId,
+            liveLeafIds
+          )
+          if (buffersByLeafId) {
+            layout.buffersByLeafId = buffersByLeafId
+          }
+          if (titlesByLeafId) {
+            layout.titlesByLeafId = titlesByLeafId
+          }
         }
       }
     }
@@ -1382,7 +1977,9 @@ export class Store {
         return
       }
       if (node.type === 'leaf') {
-        leafIds.add(node.leafId)
+        if (isTerminalLeafId(node.leafId)) {
+          leafIds.add(node.leafId)
+        }
         return
       }
       visit(node.first)
@@ -1497,13 +2094,67 @@ export class Store {
     if (!session) {
       return
     }
+    const sessionBeforeBinding = cloneWorkspaceSessionState(session)
     const tabs = session.tabsByWorktree?.[args.worktreeId]
     const tab = tabs?.find((t) => t.id === args.tabId)
     if (tab) {
       tab.ptyId = args.ptyId
+    } else {
+      // Why: pty:spawn can beat the debounced session writer for a newly
+      // created tab. Persist a minimal tab so hydration does not prune the
+      // crash-safe layout binding below as an orphaned tab id.
+      const nextTabs = [
+        ...(tabs ?? []),
+        createMinimalPersistedTerminalTab({
+          ...args,
+          existingTabCount: tabs?.length ?? 0
+        })
+      ]
+      session.tabsByWorktree = {
+        ...session.tabsByWorktree,
+        [args.worktreeId]: nextTabs
+      }
+      session.activeWorktreeId ??= args.worktreeId
+      session.activeTabId ??= args.tabId
+      session.activeTabIdByWorktree = {
+        ...session.activeTabIdByWorktree,
+        [args.worktreeId]: session.activeTabIdByWorktree?.[args.worktreeId] ?? args.tabId
+      }
+    }
+    if (!isTerminalLeafId(args.leafId)) {
+      // Why: legacy renderer-local pane ids may arrive from older callers; keep
+      // them out of durable leaf-keyed layout state after the UUID migration.
+      try {
+        this.flushOrThrow()
+      } catch (err) {
+        this.state.workspaceSession = sessionBeforeBinding
+        throw err
+      }
+      return
     }
     const layout = session.terminalLayoutsByTabId?.[args.tabId]
     if (layout) {
+      if (!layout.root) {
+        // Why: createTab can persist an empty layout before TerminalPane mounts.
+        // The sync spawn binding must still leave a durable UUID root behind.
+        layout.root = { type: 'leaf', leafId: args.leafId }
+        layout.activeLeafId = args.leafId
+        layout.expandedLeafId = null
+      } else if (!layoutContainsLeafId(layout.root, args.leafId)) {
+        // Why: splitPane publishes the new pane and starts pty:spawn before the
+        // debounced full layout snapshot reaches main. Add a minimal leaf so a
+        // crash in that window cannot make the new pane's binding unreachable.
+        layout.root = {
+          type: 'split',
+          direction: 'vertical',
+          first: cloneLayoutNode(layout.root),
+          second: { type: 'leaf', leafId: args.leafId }
+        }
+        layout.activeLeafId = args.leafId
+        if (layout.expandedLeafId && !layoutContainsLeafId(layout.root, layout.expandedLeafId)) {
+          layout.expandedLeafId = null
+        }
+      }
       layout.ptyIdsByLeafId = {
         ...layout.ptyIdsByLeafId,
         [args.leafId]: args.ptyId
@@ -1525,7 +2176,12 @@ export class Store {
         }
       }
     }
-    this.flush()
+    try {
+      this.flushOrThrow()
+    } catch (err) {
+      this.state.workspaceSession = sessionBeforeBinding
+      throw err
+    }
   }
 
   // ── SSH Targets ────────────────────────────────────────────────────
@@ -1575,16 +2231,21 @@ export class Store {
       Partial<Pick<SshRemotePtyLease, 'createdAt' | 'updatedAt'>>
   ): void {
     this.state.sshRemotePtyLeases ??= []
+    const normalizedLease = { ...lease }
+    if (normalizedLease.leafId !== undefined && !isTerminalLeafId(normalizedLease.leafId)) {
+      delete normalizedLease.leafId
+    }
     const now = Date.now()
     const existingIndex = this.state.sshRemotePtyLeases.findIndex(
-      (entry) => entry.targetId === lease.targetId && entry.ptyId === lease.ptyId
+      (entry) =>
+        entry.targetId === normalizedLease.targetId && entry.ptyId === normalizedLease.ptyId
     )
     const existing = existingIndex >= 0 ? this.state.sshRemotePtyLeases[existingIndex] : undefined
     const next: SshRemotePtyLease = {
       ...existing,
-      ...lease,
-      createdAt: existing?.createdAt ?? lease.createdAt ?? now,
-      updatedAt: lease.updatedAt ?? now
+      ...normalizedLease,
+      createdAt: existing?.createdAt ?? normalizedLease.createdAt ?? now,
+      updatedAt: normalizedLease.updatedAt ?? now
     }
     if (existingIndex >= 0) {
       this.state.sshRemotePtyLeases[existingIndex] = next
@@ -1637,6 +2298,20 @@ export class Store {
     this.flush()
   }
 
+  removeSshRemotePtyLease(targetId: string, ptyId: string): void {
+    const leases = (this.state.sshRemotePtyLeases ?? []).filter(
+      (lease) => lease.targetId === targetId && lease.ptyId === ptyId
+    )
+    const before = this.state.sshRemotePtyLeases?.length ?? 0
+    this.clearSshRemotePtyBindingsForLeases(targetId, leases)
+    this.state.sshRemotePtyLeases = (this.state.sshRemotePtyLeases ?? []).filter(
+      (lease) => lease.targetId !== targetId || lease.ptyId !== ptyId
+    )
+    if (this.state.sshRemotePtyLeases.length !== before) {
+      this.flush()
+    }
+  }
+
   removeSshRemotePtyLeases(targetId: string): void {
     this.state.sshRemotePtyLeases ??= []
     this.clearSshRemotePtyBindingsForTarget(targetId)
@@ -1651,6 +2326,10 @@ export class Store {
 
   private clearSshRemotePtyBindingsForTarget(targetId: string): void {
     const leases = this.state.sshRemotePtyLeases?.filter((lease) => lease.targetId === targetId)
+    this.clearSshRemotePtyBindingsForLeases(targetId, leases ?? [])
+  }
+
+  private clearSshRemotePtyBindingsForLeases(targetId: string, leases: SshRemotePtyLease[]): void {
     const session = this.state.workspaceSession
     if (!leases?.length || !session) {
       return
@@ -1709,16 +2388,8 @@ export class Store {
   // ── Flush (for shutdown) ───────────────────────────────────────────
 
   flush(): void {
-    if (this.writeTimer) {
-      clearTimeout(this.writeTimer)
-      this.writeTimer = null
-    }
-    // Why: bump writeGeneration so any in-flight async writeToDiskAsync skips
-    // its rename, preventing a stale snapshot from overwriting this sync write.
-    this.writeGeneration++
-    this.pendingWrite = null
     try {
-      this.writeToDiskSync()
+      this.flushOrThrow()
     } catch (err) {
       console.error('[persistence] Failed to flush state:', err)
     }
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index d84f393531d..0b89b417f0e 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -138,6 +138,15 @@ const TEST_REPO_ID = 'repo-1'
 const TEST_REPO_PATH = '/tmp/repo'
 const TEST_WORKTREE_PATH = '/tmp/worktree-a'
 const TEST_WORKTREE_ID = `${TEST_REPO_ID}::${TEST_WORKTREE_PATH}`
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+function expectStablePaneKeyEnv(env: Record<string, string>): string {
+  expect(env.ORCA_TAB_ID).toMatch(UUID_RE)
+  const leafId = env.ORCA_PANE_KEY?.slice(`${env.ORCA_TAB_ID}:`.length)
+  expect(leafId).toMatch(UUID_RE)
+  expect(env.ORCA_PANE_KEY).toBe(`${env.ORCA_TAB_ID}:${leafId}`)
+  return env.ORCA_PANE_KEY
+}
 
 function createRuntime(): OrcaRuntimeService {
   return new OrcaRuntimeService(store)
@@ -952,24 +961,52 @@ describe('OrcaRuntimeService', () => {
     })
     expect(result.handle).toMatch(/^term_/)
     expect(createTerminal).not.toHaveBeenCalled()
-    // Why: hook-based agent status keys off `${tabId}:${paneId}`, so main must
+    // Why: hook-based agent status keys off `${tabId}:${leafId}`, so main must
     // pre-allocate the tabId and stamp ORCA_PANE_KEY/TAB_ID/WORKTREE_ID into
     // the PTY env before spawn. The same tabId is then handed to the renderer
-    // via `revealTerminalSession` so adoption preserves attribution. See
-    // docs/cli-terminal-hook-pane-key.md.
+    // via `revealTerminalSession` so adoption preserves attribution.
     const spawnCall = spawn.mock.calls[0]?.[0] as { env?: Record<string, string> } | undefined
     const spawnedEnv = spawnCall?.env ?? {}
-    expect(spawnedEnv.ORCA_TAB_ID).toMatch(/^[0-9a-f-]+$/)
-    expect(spawnedEnv.ORCA_PANE_KEY).toBe(`${spawnedEnv.ORCA_TAB_ID}:1`)
+    expectStablePaneKeyEnv(spawnedEnv)
+    const spawnedLeafId = spawnedEnv.ORCA_PANE_KEY.slice(`${spawnedEnv.ORCA_TAB_ID}:`.length)
     expect(spawnedEnv.ORCA_WORKTREE_ID).toBe(TEST_WORKTREE_ID)
     expect(revealTerminalSession).toHaveBeenCalledWith(TEST_WORKTREE_ID, {
       ptyId: 'pty-bg',
       title: 'worker',
       activate: false,
-      tabId: spawnedEnv.ORCA_TAB_ID
+      tabId: spawnedEnv.ORCA_TAB_ID,
+      leafId: spawnedLeafId
     })
   })
 
+  it('adopts renderer pane identity for remote runtime terminal creates', async () => {
+    const spawn = vi.fn().mockResolvedValue({ id: 'pty-bg' })
+    const runtime = new OrcaRuntimeService(store)
+    const tabId = 'tab-remote-runtime'
+    const leafId = '11111111-1111-4111-8111-111111111111'
+    runtime.setPtyController({
+      spawn,
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null
+    })
+
+    await runtime.createTerminal(`path:${TEST_WORKTREE_PATH}`, {
+      focus: false,
+      tabId,
+      leafId,
+      env: {
+        ORCA_PANE_KEY: `${tabId}:${leafId}`,
+        ORCA_TAB_ID: tabId
+      }
+    })
+
+    const spawnedEnv =
+      (spawn.mock.calls[0]?.[0] as { env?: Record<string, string> } | undefined)?.env ?? {}
+    expect(spawnedEnv.ORCA_TAB_ID).toBe(tabId)
+    expect(spawnedEnv.ORCA_PANE_KEY).toBe(`${tabId}:${leafId}`)
+  })
+
   it('creates background terminal sessions while the renderer graph is unavailable', async () => {
     const spawn = vi.fn().mockResolvedValue({ id: 'pty-bg' })
     const runtime = new OrcaRuntimeService(store)
@@ -1025,13 +1062,14 @@ describe('OrcaRuntimeService', () => {
       })
       const spawnCall = spawn.mock.calls[0]?.[0] as { env?: Record<string, string> } | undefined
       const spawnedEnv = spawnCall?.env ?? {}
-      expect(spawnedEnv.ORCA_TAB_ID).toMatch(/^[0-9a-f-]+$/)
-      expect(spawnedEnv.ORCA_PANE_KEY).toBe(`${spawnedEnv.ORCA_TAB_ID}:1`)
+      expectStablePaneKeyEnv(spawnedEnv)
+      const spawnedLeafId = spawnedEnv.ORCA_PANE_KEY.slice(`${spawnedEnv.ORCA_TAB_ID}:`.length)
       expect(revealTerminalSession).toHaveBeenCalledWith(TEST_WORKTREE_ID, {
         ptyId: 'pty-bg',
         title: null,
         activate: false,
-        tabId: spawnedEnv.ORCA_TAB_ID
+        tabId: spawnedEnv.ORCA_TAB_ID,
+        leafId: spawnedLeafId
       })
       expect(warn).toHaveBeenCalledWith(
         expect.stringContaining('[terminal-create] failed to create inactive tab for pty-bg:'),
@@ -1127,7 +1165,8 @@ describe('OrcaRuntimeService', () => {
     expect(revealTerminalSession).toHaveBeenLastCalledWith(TEST_WORKTREE_ID, {
       ptyId: 'pty-bg',
       title: 'worker',
-      tabId: expect.stringMatching(/^[0-9a-f-]+$/)
+      tabId: expect.stringMatching(UUID_RE),
+      leafId: expect.stringMatching(UUID_RE)
     })
   })
 
@@ -1590,6 +1629,89 @@ describe('OrcaRuntimeService', () => {
     }
   })
 
+  it('closes the matching mobile terminal UUID leaf without closing the whole tab', async () => {
+    const closeTerminal = vi.fn()
+    const kill = vi.fn(() => true)
+    const runtime = new OrcaRuntimeService(store)
+    runtime.setPtyController({
+      spawn: vi.fn(),
+      write: () => true,
+      kill,
+      getForegroundProcess: async () => null
+    })
+    runtime.setNotifier({
+      worktreesChanged: vi.fn(),
+      reposChanged: vi.fn(),
+      activateWorktree: vi.fn(),
+      createTerminal: vi.fn(),
+      revealTerminalSession: vi.fn(),
+      splitTerminal: vi.fn(),
+      renameTerminal: vi.fn(),
+      focusTerminal: vi.fn(),
+      closeTerminal,
+      sleepWorktree: vi.fn(),
+      terminalFitOverrideChanged: vi.fn(),
+      terminalDriverChanged: vi.fn()
+    })
+    const leftLeafId = '11111111-1111-4111-8111-111111111111'
+    const rightLeafId = '22222222-2222-4222-8222-222222222222'
+    runtime.attachWindow(1)
+    runtime.syncWindowGraph(1, {
+      tabs: [
+        {
+          tabId: 'tab-1',
+          worktreeId: TEST_WORKTREE_ID,
+          title: 'Terminal 1',
+          activeLeafId: rightLeafId,
+          layout: null
+        }
+      ],
+      leaves: [
+        {
+          tabId: 'tab-1',
+          worktreeId: TEST_WORKTREE_ID,
+          leafId: leftLeafId,
+          paneRuntimeId: 1,
+          ptyId: 'pty-left',
+          paneTitle: 'left'
+        },
+        {
+          tabId: 'tab-1',
+          worktreeId: TEST_WORKTREE_ID,
+          leafId: rightLeafId,
+          paneRuntimeId: 2,
+          ptyId: 'pty-right',
+          paneTitle: 'right'
+        }
+      ],
+      mobileSessionTabs: [
+        {
+          worktree: TEST_WORKTREE_ID,
+          publicationEpoch: 'epoch-1',
+          snapshotVersion: 1,
+          activeGroupId: 'group-1',
+          activeTabId: `tab-1::${rightLeafId}`,
+          activeTabType: 'terminal',
+          tabs: [
+            {
+              type: 'terminal',
+              id: `tab-1::${rightLeafId}`,
+              parentTabId: 'tab-1',
+              leafId: rightLeafId,
+              title: 'right',
+              isActive: true
+            }
+          ]
+        }
+      ]
+    })
+
+    await runtime.closeMobileSessionTab(`id:${TEST_WORKTREE_ID}`, `tab-1::${rightLeafId}`)
+
+    expect(kill).toHaveBeenCalledWith('pty-right')
+    expect(closeTerminal).not.toHaveBeenCalled()
+  })
+
   it('creates mobile session terminals in a headless runtime server', async () => {
     const spawn = vi.fn().mockResolvedValue({ id: 'pty-headless' })
     const runtime = new OrcaRuntimeService(store)
@@ -2255,12 +2377,12 @@ describe('OrcaRuntimeService', () => {
         command: 'bash /tmp/repo/.git/orca/setup-runner.sh',
         // Why: createTerminal stamps ORCA_PANE_KEY/TAB_ID/WORKTREE_ID into the
         // PTY env on top of the caller-supplied env so hook-based agent status
-        // can attribute hook events to a pane. See docs/cli-terminal-hook-pane-key.md.
+        // can attribute hook events to a stable pane.
         env: expect.objectContaining({
           ORCA_ROOT_PATH: '/tmp/repo',
           ORCA_WORKTREE_PATH: '/tmp/workspaces/runtime-hook-skip',
-          ORCA_TAB_ID: expect.stringMatching(/^[0-9a-f-]+$/),
-          ORCA_PANE_KEY: expect.stringMatching(/^[0-9a-f-]+:1$/),
+          ORCA_TAB_ID: expect.stringMatching(UUID_RE),
+          ORCA_PANE_KEY: expect.any(String),
           ORCA_WORKTREE_ID: result.worktree.id
         }),
         worktreeId: result.worktree.id
@@ -2268,12 +2390,14 @@ describe('OrcaRuntimeService', () => {
     )
     const setupSpawnEnv =
       (spawn.mock.calls[1]?.[0] as { env?: Record<string, string> } | undefined)?.env ?? {}
-    expect(setupSpawnEnv.ORCA_PANE_KEY).toBe(`${setupSpawnEnv.ORCA_TAB_ID}:1`)
+    expectStablePaneKeyEnv(setupSpawnEnv)
+    const setupLeafId = setupSpawnEnv.ORCA_PANE_KEY.slice(`${setupSpawnEnv.ORCA_TAB_ID}:`.length)
     expect(revealTerminalSession).toHaveBeenLastCalledWith(result.worktree.id, {
       ptyId: 'pty-setup',
       title: 'Setup',
       activate: false,
-      tabId: setupSpawnEnv.ORCA_TAB_ID
+      tabId: setupSpawnEnv.ORCA_TAB_ID,
+      leafId: setupLeafId
     })
   })
 
@@ -2332,13 +2456,16 @@ describe('OrcaRuntimeService', () => {
     )
     const initialSpawnEnv =
       (spawn.mock.calls[0]?.[0] as { env?: Record<string, string> } | undefined)?.env ?? {}
-    expect(initialSpawnEnv.ORCA_TAB_ID).toMatch(/^[0-9a-f-]+$/)
-    expect(initialSpawnEnv.ORCA_PANE_KEY).toBe(`${initialSpawnEnv.ORCA_TAB_ID}:1`)
+    expectStablePaneKeyEnv(initialSpawnEnv)
+    const initialLeafId = initialSpawnEnv.ORCA_PANE_KEY.slice(
+      `${initialSpawnEnv.ORCA_TAB_ID}:`.length
+    )
     expect(revealTerminalSession).toHaveBeenCalledWith(result.worktree.id, {
       ptyId: 'pty-created-worktree',
       title: null,
       activate: false,
-      tabId: initialSpawnEnv.ORCA_TAB_ID
+      tabId: initialSpawnEnv.ORCA_TAB_ID,
+      leafId: initialLeafId
     })
   })
 
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 7eae9c84c16..3e3dfd25098 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -34,6 +34,7 @@ import { splitWorktreeId } from '../../shared/worktree-id'
 import { isFolderRepo } from '../../shared/repo-kind'
 import { buildSetupRunnerCommand } from '../../shared/setup-runner-command'
 import { FIRST_PANE_ID } from '../../shared/pane-key'
+import { isTerminalLeafId, makePaneKey, parsePaneKey } from '../../shared/stable-pane-id'
 import {
   isPathInsideOrEqual,
   normalizeRuntimePathForComparison
@@ -381,7 +382,13 @@ type RuntimeNotifier = {
   createTerminal(worktreeId: string, opts: { command?: string; title?: string }): void
   revealTerminalSession?(
     worktreeId: string,
-    opts: { ptyId: string; title?: string | null; activate?: boolean; tabId?: string }
+    opts: {
+      ptyId: string
+      title?: string | null
+      activate?: boolean
+      tabId?: string
+      leafId?: string
+    }
   ):
     | Promise<{ tabId: string; title?: string | null }>
     | { tabId: string; title?: string | null }
@@ -914,7 +921,7 @@ export class OrcaRuntimeService {
           lastOutputAt: existing?.ptyId === leaf.ptyId ? existing.lastOutputAt : null,
           preview: existing?.ptyId === leaf.ptyId ? existing.preview : '',
           tabId: leaf.tabId,
-          paneKey: `${leaf.tabId}:${leaf.paneRuntimeId}`
+          paneKey: this.makeRuntimePaneKey(leaf)
         })
       }
 
@@ -1257,7 +1264,7 @@ export class OrcaRuntimeService {
         lastOutputAt: pty?.lastOutputAt ?? at,
         preview: pty?.preview ?? leaf.preview,
         tabId: leaf.tabId,
-        paneKey: `${leaf.tabId}:${leaf.paneRuntimeId}`
+        paneKey: this.makeRuntimePaneKey(leaf)
       })
       leaf.connected = true
       leaf.writable = this.graphStatus === 'ready'
@@ -5842,7 +5849,14 @@ export class OrcaRuntimeService {
 
   async createTerminal(
     worktreeSelector?: string,
-    opts: { command?: string; env?: Record<string, string>; title?: string; focus?: boolean } = {}
+    opts: {
+      command?: string
+      env?: Record<string, string>
+      title?: string
+      focus?: boolean
+      tabId?: string
+      leafId?: string
+    } = {}
   ): Promise<RuntimeTerminalCreate> {
     if (opts.focus !== true) {
       if (!worktreeSelector) {
@@ -5856,13 +5870,20 @@ export class OrcaRuntimeService {
       const preAllocatedHandle = this.createPreAllocatedTerminalHandle()
       // Why: mint tabId in main before spawn so paneKey is known at PTY env
       // build time. Hook-based agent status (Claude/Codex/Cursor/Gemini) keys
-      // off `${tabId}:${paneId}` — without these vars set on the PTY, the
+      // off `${tabId}:${leafId}` — without these vars set on the PTY, the
       // hook payload arrives with an empty paneKey and the renderer cannot
-      // attribute the event. paneId is hard-coded to 1 because this path
-      // never splits and the renderer's nextPaneId starts at 1 for a fresh
-      // tab. See docs/cli-terminal-hook-pane-key.md.
-      const tabId = randomUUID()
-      const paneKey = `${tabId}:${FIRST_PANE_ID}`
+      // attribute the event. Use a stable UUID leaf because hooks reject the
+      // legacy numeric pane keys after the pane-id migration.
+      const hintedTabId = opts.tabId?.trim()
+      const canAdoptPaneIdentity =
+        hintedTabId !== undefined &&
+        hintedTabId.length > 0 &&
+        !hintedTabId.includes(':') &&
+        opts.leafId !== undefined &&
+        isTerminalLeafId(opts.leafId)
+      const tabId = canAdoptPaneIdentity ? (hintedTabId as string) : randomUUID()
+      const leafId = canAdoptPaneIdentity ? (opts.leafId as string) : randomUUID()
+      const paneKey = makePaneKey(tabId, leafId)
       const env = {
         ...opts.env,
         ORCA_PANE_KEY: paneKey,
@@ -5899,7 +5920,8 @@ export class OrcaRuntimeService {
             ptyId: result.id,
             title: opts.title ?? null,
             activate: false,
-            tabId
+            tabId,
+            leafId
           })
           surface = 'visible'
         } catch (err) {
@@ -6013,7 +6035,7 @@ export class OrcaRuntimeService {
     })
 
     if (opts.activate !== false) {
-      this.notifier?.focusTerminal(reply.tabId, worktreeId, 'pane:1')
+      this.notifier?.focusTerminal(reply.tabId, worktreeId, null)
     }
     return await this.waitForMobileTerminalSurface(worktreeId, reply.tabId)
   }
@@ -6029,7 +6051,7 @@ export class OrcaRuntimeService {
       throw new Error('terminal_handle_stale')
     }
     const parentTabId = livePty.pty.tabId ?? `pty:${livePty.pty.ptyId}`
-    const leafId = `pane:${FIRST_PANE_ID}`
+    const leafId = parsePaneKey(livePty.pty.paneKey ?? '')?.leafId ?? randomUUID()
     const tab: RuntimeMobileSessionTerminalTab = {
       type: 'terminal',
       id: `${parentTabId}::${leafId}`,
@@ -6245,10 +6267,12 @@ export class OrcaRuntimeService {
       if (!pty.pty.connected) {
         throw new Error('terminal_exited')
       }
+      const parsedPaneKey = parsePaneKey(pty.pty.paneKey ?? '')
       const revealed = await this.notifier?.revealTerminalSession?.(pty.pty.worktreeId, {
         ptyId: pty.pty.ptyId,
         title: pty.pty.title ?? pty.pty.lastOscTitle,
-        ...(pty.pty.tabId !== null ? { tabId: pty.pty.tabId } : {})
+        ...(pty.pty.tabId !== null ? { tabId: pty.pty.tabId } : {}),
+        ...(parsedPaneKey ? { leafId: parsedPaneKey.leafId } : {})
       })
       return {
         handle,
@@ -6257,7 +6281,7 @@ export class OrcaRuntimeService {
       }
     }
     const { leaf } = this.getLiveLeafForHandle(handle)
-    this.notifier?.focusTerminal(leaf.tabId, leaf.worktreeId)
+    this.notifier?.focusTerminal(leaf.tabId, leaf.worktreeId, leaf.leafId)
     return { handle, tabId: leaf.tabId, worktreeId: leaf.worktreeId }
   }
 
@@ -6661,6 +6685,14 @@ export class OrcaRuntimeService {
     return pty
   }
 
+  private makeRuntimePaneKey(
+    leaf: Pick<RuntimeSyncedLeaf, 'tabId' | 'leafId' | 'paneRuntimeId'>
+  ): string {
+    return isTerminalLeafId(leaf.leafId)
+      ? makePaneKey(leaf.tabId, leaf.leafId)
+      : `${leaf.tabId}:${leaf.paneRuntimeId}`
+  }
+
   private getOrCreatePtyWorktreeRecord(ptyId: string): RuntimePtyWorktreeRecord | null {
     const existing = this.ptysById.get(ptyId)
     if (existing) {
diff --git a/src/main/runtime/rpc/methods/terminal.ts b/src/main/runtime/rpc/methods/terminal.ts
index 1fcbc4fae41..81f59d22bb8 100644
--- a/src/main/runtime/rpc/methods/terminal.ts
+++ b/src/main/runtime/rpc/methods/terminal.ts
@@ -318,7 +318,9 @@ const TerminalCreateParams = z.object({
   command: OptionalString,
   env: z.record(z.string(), z.string()).optional(),
   title: OptionalString,
-  focus: z.unknown().optional()
+  focus: z.unknown().optional(),
+  tabId: OptionalString,
+  leafId: OptionalString
 })
 
 const TerminalSplit = TerminalHandle.extend({
@@ -542,7 +544,9 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         command: params.command,
         env: params.env,
         title: params.title,
-        focus: params.focus === true
+        focus: params.focus === true,
+        tabId: params.tabId,
+        leafId: params.leafId
       })
     })
   }),
diff --git a/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts b/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
index 2aa5347ec6f..b1b6154e0b2 100644
--- a/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
+++ b/src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
@@ -22,6 +22,10 @@ vi.mock('./ssh-relay-deploy', () => ({
 const { deployAndLaunchRelay } = await import('./ssh-relay-deploy')
 const { SshRelaySession } = await import('./ssh-relay-session')
 
+const SSH_LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const REPLAY_LEAF_ID = '22222222-2222-4222-8222-222222222222'
+const BAD_LEAF_ID = '33333333-3333-4333-8333-333333333333'
+
 type CapturedStatus = {
   paneKey: string
   tabId?: string
@@ -153,7 +157,7 @@ function captureAgentStatuses(events: CapturedStatus[]): void {
 function makeEnvelope(overrides: Partial<AgentHookRelayEnvelope> = {}): AgentHookRelayEnvelope {
   return {
     source: 'codex',
-    paneKey: 'tab-ssh:0',
+    paneKey: `tab-ssh:${SSH_LEAF_ID}`,
     tabId: 'tab-ssh',
     worktreeId: 'wt-ssh',
     connectionId: null,
@@ -217,7 +221,7 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
       rows: 40,
       cwd: '/home/orca/project',
       env: {
-        ORCA_PANE_KEY: 'tab-ssh:0',
+        ORCA_PANE_KEY: `tab-ssh:${SSH_LEAF_ID}`,
         ORCA_TAB_ID: 'tab-ssh',
         ORCA_WORKTREE_ID: 'wt-ssh'
       }
@@ -228,7 +232,7 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
     expect(relay.ptySpawnRequests[0]).toMatchObject({
       cwd: '/home/orca/project',
       env: {
-        ORCA_PANE_KEY: 'tab-ssh:0',
+        ORCA_PANE_KEY: `tab-ssh:${SSH_LEAF_ID}`,
         ORCA_TAB_ID: 'tab-ssh',
         ORCA_WORKTREE_ID: 'wt-ssh'
       }
@@ -238,7 +242,7 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
 
     await waitForStatusCount(events, 1)
     expect(events[0]).toEqual({
-      paneKey: 'tab-ssh:0',
+      paneKey: `tab-ssh:${SSH_LEAF_ID}`,
       tabId: 'tab-ssh',
       worktreeId: 'wt-ssh',
       connectionId: 'conn-fake',
@@ -255,7 +259,7 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
     relay = createFakeRelay()
     relay.replayEnvelopes.push(
       makeEnvelope({
-        paneKey: 'tab-replay:0',
+        paneKey: `tab-replay:${REPLAY_LEAF_ID}`,
         tabId: 'tab-replay',
         worktreeId: 'wt-replay',
         payload: {
@@ -278,7 +282,7 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
 
     await waitForStatusCount(events, 1)
     expect(events[0]).toMatchObject({
-      paneKey: 'tab-replay:0',
+      paneKey: `tab-replay:${REPLAY_LEAF_ID}`,
       tabId: 'tab-replay',
       worktreeId: 'wt-replay',
       connectionId: 'conn-replay',
@@ -305,7 +309,7 @@ describe('SshRelaySession agent hooks over a fake relay transport', () => {
 
     relay.notifyAgentHook({
       source: 'codex',
-      paneKey: 'tab-bad:0',
+      paneKey: `tab-bad:${BAD_LEAF_ID}`,
       connectionId: null,
       env: REMOTE_AGENT_HOOK_ENV,
       version: '1',
diff --git a/src/main/window/attach-main-window-services.ts b/src/main/window/attach-main-window-services.ts
index cbfd97df3fc..afd62e898e3 100644
--- a/src/main/window/attach-main-window-services.ts
+++ b/src/main/window/attach-main-window-services.ts
@@ -266,8 +266,9 @@ function registerRuntimeWindowLifecycle(
           activate: opts.activate !== false,
           // Why: pre-minted tabId from main keeps the renderer's tab id aligned
           // with the paneKey baked into the PTY env at spawn time, so hook
-          // events route to the right slot. See docs/cli-terminal-hook-pane-key.md.
-          ...(opts.tabId !== undefined ? { tabId: opts.tabId } : {})
+          // events route to the right slot.
+          ...(opts.tabId !== undefined ? { tabId: opts.tabId } : {}),
+          ...(opts.leafId !== undefined ? { leafId: opts.leafId } : {})
         })
       }),
     splitTerminal: (tabId, paneRuntimeId, opts) => {
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 015b5d353c8..8bcb4ce9467 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -140,7 +140,10 @@ import type { ElectronAPI } from '@electron-toolkit/preload'
 import type { CliInstallStatus } from '../shared/cli-install-types'
 import type { E2EConfig } from '../shared/e2e-config'
 import type { AgentHookInstallStatus } from '../shared/agent-hook-types'
-import type { AgentStatusIpcPayload } from '../shared/agent-status-types'
+import type {
+  AgentStatusIpcPayload,
+  MigrationUnsupportedPtyEntry
+} from '../shared/agent-status-types'
 import type {
   RuntimeStatus,
   RuntimeSyncWindowGraph,
@@ -1328,6 +1331,7 @@ export type PreloadApi = {
         ptyId?: string
         activate?: boolean
         tabId?: string
+        leafId?: string
       }) => void
     ) => () => void
     onRequestTerminalCreate: (
@@ -1555,6 +1559,11 @@ export type PreloadApi = {
     onSet: (callback: (data: AgentStatusIpcPayload) => void) => () => void
     /** Return the current main-process hook cache after renderer hydration. */
     getSnapshot: () => Promise<AgentStatusIpcPayload[]>
+    /** Listen for PTYs that still use a legacy numeric pane key but have
+     *  registry-backed UUID pane proof. */
+    onMigrationUnsupported: (callback: (entry: MigrationUnsupportedPtyEntry) => void) => () => void
+    onMigrationUnsupportedClear: (callback: (data: { ptyId: string }) => void) => () => void
+    getMigrationUnsupportedSnapshot: () => Promise<MigrationUnsupportedPtyEntry[]>
     /** Drop a paneKey from the main-process hook cache and the on-disk
      *  last-status file. Fire-and-forget. */
     drop: (paneKey: string) => void
diff --git a/src/preload/index.ts b/src/preload/index.ts
index d8cfa69234e..f007c51d429 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -87,7 +87,10 @@ import type {
   PortForwardEntry,
   DetectedPort
 } from '../shared/ssh-types'
-import type { AgentStatusIpcPayload } from '../shared/agent-status-types'
+import type {
+  AgentStatusIpcPayload,
+  MigrationUnsupportedPtyEntry
+} from '../shared/agent-status-types'
 import type { SpeechModelManifest, SpeechModelState } from '../shared/speech-types'
 import type { TelemetryConsentState } from '../shared/telemetry-consent-types'
 import type { RefreshAgentsResult } from './api-types'
@@ -2080,6 +2083,7 @@ const api = {
           ptyId?: string
           activate?: boolean
           tabId?: string
+          leafId?: string
         }
       ) => callback(data)
       ipcRenderer.on('ui:createTerminal', listener)
@@ -2671,6 +2675,22 @@ const api = {
      *  knows which tabs exist. */
     getSnapshot: (): Promise<AgentStatusIpcPayload[]> =>
       ipcRenderer.invoke('agentStatus:getSnapshot'),
+    onMigrationUnsupported: (
+      callback: (entry: MigrationUnsupportedPtyEntry) => void
+    ): (() => void) => {
+      const listener = (_event: Electron.IpcRendererEvent, entry: MigrationUnsupportedPtyEntry) =>
+        callback(entry)
+      ipcRenderer.on('agentStatus:migrationUnsupported', listener)
+      return () => ipcRenderer.removeListener('agentStatus:migrationUnsupported', listener)
+    },
+    onMigrationUnsupportedClear: (callback: (data: { ptyId: string }) => void): (() => void) => {
+      const listener = (_event: Electron.IpcRendererEvent, data: { ptyId: string }) =>
+        callback(data)
+      ipcRenderer.on('agentStatus:migrationUnsupportedClear', listener)
+      return () => ipcRenderer.removeListener('agentStatus:migrationUnsupportedClear', listener)
+    },
+    getMigrationUnsupportedSnapshot: (): Promise<MigrationUnsupportedPtyEntry[]> =>
+      ipcRenderer.invoke('agentStatus:getMigrationUnsupportedSnapshot'),
     /** Drop the cached hook status for a paneKey on both sides — main-process
      *  cache (lastStatusByPaneKey) and on-disk last-status file. Fired from
      *  the renderer when the user dismisses a retained row so a relaunch
diff --git a/src/relay/agent-hook-integration.test.ts b/src/relay/agent-hook-integration.test.ts
index 29466576c54..cfceac96c63 100644
--- a/src/relay/agent-hook-integration.test.ts
+++ b/src/relay/agent-hook-integration.test.ts
@@ -28,6 +28,9 @@ import {
 } from '../shared/agent-hook-relay'
 import { AgentHookServer } from '../main/agent-hooks/server'
 
+const LEAF_7 = '77777777-7777-4777-8777-777777777777'
+const LEAF_9 = '99999999-9999-4999-8999-999999999999'
+
 describe('Integration: relay hook server → mux → AgentHookServer.ingestRemote', () => {
   let tmpDir: string
   let mux: SshChannelMultiplexer
@@ -128,7 +131,7 @@ describe('Integration: relay hook server → mux → AgentHookServer.ingestRemot
         'X-Orca-Agent-Hook-Token': token
       },
       body: JSON.stringify({
-        paneKey: 'tab-7:0',
+        paneKey: `tab-7:${LEAF_7}`,
         tabId: 'tab-7',
         worktreeId: 'wt-7',
         env: 'remote',
@@ -146,7 +149,7 @@ describe('Integration: relay hook server → mux → AgentHookServer.ingestRemot
       await new Promise((r) => setImmediate(r))
     }
     expect(events).toHaveLength(1)
-    expect(events[0].paneKey).toBe('tab-7:0')
+    expect(events[0].paneKey).toBe(`tab-7:${LEAF_7}`)
     expect(events[0].connectionId).toBe('conn-test')
     const payload = events[0].payload as { state: string; prompt: string; agentType: string }
     expect(payload.state).toBe('working')
@@ -172,7 +175,7 @@ describe('Integration: relay hook server → mux → AgentHookServer.ingestRemot
         'X-Orca-Agent-Hook-Token': token
       },
       body: JSON.stringify({
-        paneKey: 'tab-9:0',
+        paneKey: `tab-9:${LEAF_9}`,
         payload: { hook_event_name: 'UserPromptSubmit', prompt: 'cached' }
       })
     })
@@ -198,6 +201,6 @@ describe('Integration: relay hook server → mux → AgentHookServer.ingestRemot
       await new Promise((r) => setImmediate(r))
     }
     expect(events).toHaveLength(2)
-    expect(events[1].paneKey).toBe('tab-9:0')
+    expect(events[1].paneKey).toBe(`tab-9:${LEAF_9}`)
   })
 })
diff --git a/src/relay/agent-hook-server.test.ts b/src/relay/agent-hook-server.test.ts
index 51fc046525b..e24182441be 100644
--- a/src/relay/agent-hook-server.test.ts
+++ b/src/relay/agent-hook-server.test.ts
@@ -4,6 +4,10 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import { endpointDirForRelaySocket, RelayAgentHookServer } from './agent-hook-server'
 import type { AgentHookRelayEnvelope } from '../shared/agent-hook-relay'
+import { makePaneKey } from '../shared/stable-pane-id'
+
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const PANE_KEY = makePaneKey('tab-1', LEAF_ID)
 
 describe('RelayAgentHookServer', () => {
   let dir: string
@@ -36,7 +40,7 @@ describe('RelayAgentHookServer', () => {
           'X-Orca-Agent-Hook-Token': token
         },
         body: JSON.stringify({
-          paneKey: 'tab-1:0',
+          paneKey: PANE_KEY,
           tabId: 'tab-1',
           worktreeId: 'wt-1',
           env: 'remote',
@@ -48,7 +52,7 @@ describe('RelayAgentHookServer', () => {
       expect(forward).toHaveBeenCalledTimes(1)
       const envelope = forward.mock.calls[0][0]
       expect(envelope.source).toBe('claude')
-      expect(envelope.paneKey).toBe('tab-1:0')
+      expect(envelope.paneKey).toBe(PANE_KEY)
       expect(envelope.tabId).toBe('tab-1')
       expect(envelope.connectionId).toBeNull()
       expect(envelope.payload.state).toBe('working')
@@ -96,7 +100,7 @@ describe('RelayAgentHookServer', () => {
           'X-Orca-Agent-Hook-Token': token
         },
         body: JSON.stringify({
-          paneKey: 'tab-1:0',
+          paneKey: PANE_KEY,
           tabId: 'tab-1',
           env: 'remote',
           version: '1',
@@ -131,11 +135,11 @@ describe('RelayAgentHookServer', () => {
           'X-Orca-Agent-Hook-Token': token
         },
         body: JSON.stringify({
-          paneKey: 'tab-1:0',
+          paneKey: PANE_KEY,
           payload: { hook_event_name: 'UserPromptSubmit', prompt: 'gone' }
         })
       })
-      server.clearPaneState('tab-1:0')
+      server.clearPaneState(PANE_KEY)
       forward.mockClear()
       const replayed = server.replayCachedPayloadsForPanes()
       expect(replayed).toBe(0)
diff --git a/src/renderer/src/components/Terminal.tsx b/src/renderer/src/components/Terminal.tsx
index 1169ea6dacc..55c287bb805 100644
--- a/src/renderer/src/components/Terminal.tsx
+++ b/src/renderer/src/components/Terminal.tsx
@@ -1304,8 +1304,7 @@ function Terminal(): React.JSX.Element | null {
                     {(tabsByWorktree[worktree.id] ?? []).map((tab) => {
                       const activityTerminalPortal = findActivityTerminalPortal(
                         activityTerminalPortals,
-                        worktree.id,
-                        tab.id
+                        { worktreeId: worktree.id, tabId: tab.id }
                       )
                       const isActivityPortalTab = activityTerminalPortal !== null
                       const isActiveTerminalTab =
@@ -1325,7 +1324,7 @@ function Terminal(): React.JSX.Element | null {
                           // Why: when portaled to Activity for a specific agent
                           // pane, isolate that leaf so split siblings stay
                           // hidden. Workspace renders pass null → no override.
-                          isolatedPaneId={activityTerminalPortal?.paneId ?? null}
+                          isolatedPaneKey={activityTerminalPortal?.paneKey ?? null}
                           onPtyExit={(ptyId) => handlePtyExit(tab.id, ptyId)}
                           onCloseTab={() => handleCloseTab(tab.id)}
                         />
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index e21eb0ab923..c575c0dd54f 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -212,9 +212,11 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   // tab.ptyId is a wake-hint sessionId, not a liveness signal) and the jump
   // palette dot would lie green even though the sidebar dot is correctly grey.
   const ptyIdsByTabId = useAppStore((s) => s.ptyIdsByTabId)
+  const terminalLayoutsByTabId = useAppStore((s) => s.terminalLayoutsByTabId)
   const prCache = useAppStore((s) => s.prCache)
   const issueCache = useAppStore((s) => s.issueCache)
   const agentStatusByPaneKey = useAppStore((s) => s.agentStatusByPaneKey)
+  const migrationUnsupportedByPtyId = useAppStore((s) => s.migrationUnsupportedByPtyId)
   const activeWorktreeId = useAppStore((s) => s.activeWorktreeId)
   const activeTabType = useAppStore((s) => s.activeTabType)
   const activeBrowserTabId = useAppStore((s) => s.activeBrowserTabId)
@@ -292,7 +294,9 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
             repoMap,
             agentStatusByPaneKey,
             runtimePaneTitlesByTabId,
-            ptyIdsByTabId
+            ptyIdsByTabId,
+            migrationUnsupportedByPtyId,
+            terminalLayoutsByTabId
           )
         : switchableWorktreesForRows,
     [
@@ -303,7 +307,9 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       repoMap,
       agentStatusByPaneKey,
       runtimePaneTitlesByTabId,
-      ptyIdsByTabId
+      ptyIdsByTabId,
+      migrationUnsupportedByPtyId,
+      terminalLayoutsByTabId
     ]
   )
 
@@ -320,7 +326,9 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       repoMap,
       agentStatusByPaneKey,
       runtimePaneTitlesByTabId,
-      ptyIdsByTabId
+      ptyIdsByTabId,
+      migrationUnsupportedByPtyId,
+      terminalLayoutsByTabId
     )
   }, [
     allWorktrees,
@@ -328,7 +336,9 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
     repoMap,
     agentStatusByPaneKey,
     runtimePaneTitlesByTabId,
-    ptyIdsByTabId
+    ptyIdsByTabId,
+    migrationUnsupportedByPtyId,
+    terminalLayoutsByTabId
   ])
 
   // Why: browser rows need worktree lookups for repo badge colors, and browser
diff --git a/src/renderer/src/components/activity/ActivityPrototypePage.test.ts b/src/renderer/src/components/activity/ActivityPrototypePage.test.ts
index cec15d11cbf..d56c546be6c 100644
--- a/src/renderer/src/components/activity/ActivityPrototypePage.test.ts
+++ b/src/renderer/src/components/activity/ActivityPrototypePage.test.ts
@@ -17,6 +17,22 @@ import {
   getActivityThreadGroup,
   groupActivityThreadsByStatus
 } from './ActivityPrototypePage'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
+
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const LEAF_ID_2 = '22222222-2222-4222-8222-222222222222'
+const LEAF_ID_3 = '33333333-3333-4333-8333-333333333333'
+const LEAF_ID_UNKNOWN = '44444444-4444-4444-8444-444444444444'
+const LEAF_ID_A1 = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1'
+const LEAF_ID_B1 = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbb1'
+const LEAF_ID_A2 = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa2'
+const PANE_KEY = makePaneKey('tab-1', LEAF_ID)
+const PANE_KEY_2 = makePaneKey('tab-2', LEAF_ID_2)
+const PANE_KEY_3 = makePaneKey('tab-3', LEAF_ID_3)
+const UNKNOWN_PANE_KEY = makePaneKey('tab-unknown', LEAF_ID_UNKNOWN)
+const PANE_KEY_A1 = makePaneKey('tab-a1', LEAF_ID_A1)
+const PANE_KEY_B1 = makePaneKey('tab-b1', LEAF_ID_B1)
+const PANE_KEY_A2 = makePaneKey('tab-a2', LEAF_ID_A2)
 
 function makeRepo(): Repo {
   return {
@@ -89,7 +105,7 @@ function makeWorkingEntryWithPriorDone(): AgentStatusEntry {
     prompt: 'Second prompt',
     updatedAt: 2_000,
     stateStartedAt: 2_000,
-    paneKey: 'tab-1:1',
+    paneKey: PANE_KEY,
     terminalTitle: 'Claude',
     stateHistory: [
       {
@@ -108,7 +124,7 @@ function makeWorkingEntryWithoutHistory(): AgentStatusEntry {
     prompt: 'New run',
     updatedAt: 3_000,
     stateStartedAt: 3_000,
-    paneKey: 'tab-1:1',
+    paneKey: PANE_KEY,
     terminalTitle: 'Claude',
     stateHistory: [],
     agentType: 'claude'
@@ -122,7 +138,7 @@ function makeRetainedDoneEntry(tab: TerminalTab): RetainedAgentEntry {
       prompt: 'Retained prior run',
       updatedAt: 1_000,
       stateStartedAt: 1_000,
-      paneKey: 'tab-1:1',
+      paneKey: PANE_KEY,
       terminalTitle: 'Claude',
       stateHistory: [],
       agentType: 'claude',
@@ -169,7 +185,7 @@ describe('buildActivityEvents', () => {
   it('keeps a prior done event after the same pane starts working again', () => {
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': makeWorkingEntryWithPriorDone()
+        [PANE_KEY]: makeWorkingEntryWithPriorDone()
       },
       now: 2_000
     })
@@ -180,8 +196,8 @@ describe('buildActivityEvents', () => {
       timestamp: 1_000
     })
     expect(result.events[0].entry.prompt).toBe('First prompt')
-    expect(result.liveAgentByPaneKey['tab-1:1'].state).toBe('working')
-    expect(result.liveAgentByPaneKey['tab-1:1'].entry.prompt).toBe('Second prompt')
+    expect(result.liveAgentByPaneKey[PANE_KEY].state).toBe('working')
+    expect(result.liveAgentByPaneKey[PANE_KEY].entry.prompt).toBe('Second prompt')
 
     const threads = makeThreads(result)
 
@@ -194,19 +210,19 @@ describe('buildActivityEvents', () => {
   it('does not keep showing a stale live agent as running', () => {
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': makeWorkingEntryWithPriorDone()
+        [PANE_KEY]: makeWorkingEntryWithPriorDone()
       },
       now: 2_000 + AGENT_STATUS_STALE_AFTER_MS + 1
     })
 
     expect(result.events).toHaveLength(1)
-    expect(result.liveAgentByPaneKey['tab-1:1']).toBeUndefined()
+    expect(result.liveAgentByPaneKey[PANE_KEY]).toBeUndefined()
   })
 
   it('creates a thread for a fresh running agent with no historical events', () => {
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': makeWorkingEntryWithoutHistory()
+        [PANE_KEY]: makeWorkingEntryWithoutHistory()
       }
     })
 
@@ -215,7 +231,7 @@ describe('buildActivityEvents', () => {
     expect(result.events).toHaveLength(0)
     expect(threads).toHaveLength(1)
     expect(threads[0]).toMatchObject({
-      paneKey: 'tab-1:1',
+      paneKey: PANE_KEY,
       paneTitle: 'New run',
       currentAgentState: 'working',
       latestTimestamp: 3_000,
@@ -233,7 +249,7 @@ describe('buildActivityEvents', () => {
 
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': entry
+        [PANE_KEY]: entry
       },
       tab
     })
@@ -257,7 +273,7 @@ describe('buildActivityEvents', () => {
 
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': entry
+        [PANE_KEY]: entry
       }
     })
 
@@ -281,7 +297,7 @@ describe('buildActivityEvents', () => {
 
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': entry
+        [PANE_KEY]: entry
       }
     })
 
@@ -315,7 +331,7 @@ describe('buildActivityEvents', () => {
 
     const result = makeActivityResult({
       retained: {
-        'tab-1:1': makeRetainedDoneEntry(tab)
+        [PANE_KEY]: makeRetainedDoneEntry(tab)
       },
       tab
     })
@@ -330,10 +346,10 @@ describe('buildActivityEvents', () => {
 
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': makeWorkingEntryWithoutHistory()
+        [PANE_KEY]: makeWorkingEntryWithoutHistory()
       },
       retained: {
-        'tab-1:1': makeRetainedDoneEntry(tab)
+        [PANE_KEY]: makeRetainedDoneEntry(tab)
       },
       tab
     })
@@ -344,7 +360,7 @@ describe('buildActivityEvents', () => {
       timestamp: 1_000
     })
     expect(result.events[0].entry.prompt).toBe('Retained prior run')
-    expect(result.liveAgentByPaneKey['tab-1:1'].state).toBe('working')
+    expect(result.liveAgentByPaneKey[PANE_KEY].state).toBe('working')
 
     const threads = makeThreads(result)
 
@@ -363,22 +379,22 @@ describe('buildActivityEvents', () => {
     const doneTab = { ...makeTab(), id: 'tab-3', ptyId: 'pty-3' }
     const result = buildActivityEvents({
       agentStatusByPaneKey: {
-        'tab-1:1': makeWorkingEntryWithoutHistory(),
-        'tab-2:1': {
+        [PANE_KEY]: makeWorkingEntryWithoutHistory(),
+        [PANE_KEY_2]: {
           ...makeWorkingEntryWithoutHistory(),
           state: 'blocked',
           prompt: 'Needs approval',
           updatedAt: 4_000,
           stateStartedAt: 4_000,
-          paneKey: 'tab-2:1'
+          paneKey: PANE_KEY_2
         },
-        'tab-3:1': {
+        [PANE_KEY_3]: {
           ...makeWorkingEntryWithoutHistory(),
           state: 'done',
           prompt: 'Finished work',
           updatedAt: 5_000,
           stateStartedAt: 5_000,
-          paneKey: 'tab-3:1'
+          paneKey: PANE_KEY_3
         }
       },
       retainedAgentsByPaneKey: {},
@@ -400,9 +416,9 @@ describe('buildActivityEvents', () => {
 
     expect(groups.map((group) => group.id)).toEqual(['working', 'blocked', 'done'])
     expect(groups.map((group) => group.threads.map((thread) => thread.paneKey))).toEqual([
-      ['tab-1:1'],
-      ['tab-2:1'],
-      ['tab-3:1']
+      [PANE_KEY],
+      [PANE_KEY_2],
+      [PANE_KEY_3]
     ])
   })
 })
@@ -425,16 +441,16 @@ describe('activity thread grouping', () => {
     }
     const { events, liveAgentByPaneKey } = buildActivityEvents({
       agentStatusByPaneKey: {
-        'tab-1:1': {
+        [PANE_KEY]: {
           ...sharedDone,
-          paneKey: 'tab-1:1',
+          paneKey: PANE_KEY,
           interrupted: true,
           updatedAt: 3_000,
           stateStartedAt: 3_000
         },
-        'tab-2:1': {
+        [PANE_KEY_2]: {
           ...sharedDone,
-          paneKey: 'tab-2:1',
+          paneKey: PANE_KEY_2,
           interrupted: false,
           updatedAt: 2_000,
           stateStartedAt: 2_000
@@ -462,12 +478,12 @@ describe('activity thread grouping', () => {
     const tab = makeTabWithIds('tab-unknown', worktree.id)
     const { events, liveAgentByPaneKey } = buildActivityEvents({
       agentStatusByPaneKey: {
-        'tab-unknown:1': {
+        [UNKNOWN_PANE_KEY]: {
           state: 'done',
           prompt: 'Prompt',
           updatedAt: 1_000,
           stateStartedAt: 1_000,
-          paneKey: 'tab-unknown:1',
+          paneKey: UNKNOWN_PANE_KEY,
           terminalTitle: 'Claude',
           stateHistory: [],
           agentType: 'claude'
@@ -489,7 +505,7 @@ describe('activity thread grouping', () => {
   it('worktree and agent grouping use expected keys and labels', () => {
     const result = makeActivityResult({
       entries: {
-        'tab-1:1': makeWorkingEntryWithoutHistory()
+        [PANE_KEY]: makeWorkingEntryWithoutHistory()
       }
     })
     const threads = makeThreads(result)
@@ -513,32 +529,32 @@ describe('activity thread grouping', () => {
     const tabA2 = makeTabWithIds('tab-a2', wtA.id)
     const { events, liveAgentByPaneKey } = buildActivityEvents({
       agentStatusByPaneKey: {
-        'tab-a1:1': {
+        [PANE_KEY_A1]: {
           state: 'done',
           prompt: 'A1',
           updatedAt: 3_000,
           stateStartedAt: 3_000,
-          paneKey: 'tab-a1:1',
+          paneKey: PANE_KEY_A1,
           terminalTitle: 'Claude',
           stateHistory: [],
           agentType: 'claude'
         },
-        'tab-b1:1': {
+        [PANE_KEY_B1]: {
           state: 'done',
           prompt: 'B1',
           updatedAt: 2_000,
           stateStartedAt: 2_000,
-          paneKey: 'tab-b1:1',
+          paneKey: PANE_KEY_B1,
           terminalTitle: 'Claude',
           stateHistory: [],
           agentType: 'claude'
         },
-        'tab-a2:1': {
+        [PANE_KEY_A2]: {
           state: 'done',
           prompt: 'A2',
           updatedAt: 1_000,
           stateStartedAt: 1_000,
-          paneKey: 'tab-a2:1',
+          paneKey: PANE_KEY_A2,
           terminalTitle: 'Claude',
           stateHistory: [],
           agentType: 'claude'
@@ -558,8 +574,8 @@ describe('activity thread grouping', () => {
     const groups = buildActivityThreadGroups(threads, 'worktree')
 
     expect(groups.map((group) => group.key)).toEqual(['worktree:wt-a', 'worktree:wt-b'])
-    expect(groups[0].threads.map((thread) => thread.paneKey)).toEqual(['tab-a1:1', 'tab-a2:1'])
-    expect(groups[1].threads.map((thread) => thread.paneKey)).toEqual(['tab-b1:1'])
+    expect(groups[0].threads.map((thread) => thread.paneKey)).toEqual([PANE_KEY_A1, PANE_KEY_A2])
+    expect(groups[1].threads.map((thread) => thread.paneKey)).toEqual([PANE_KEY_B1])
   })
 
   it('returns no groups for empty thread input', () => {
diff --git a/src/renderer/src/components/activity/ActivityPrototypePage.tsx b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
index 001fb45bff9..6188cadfbca 100644
--- a/src/renderer/src/components/activity/ActivityPrototypePage.tsx
+++ b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
@@ -58,8 +58,11 @@ import {
   type AgentStateHistoryEntry,
   type AgentStatusEntry,
   type AgentStatusState,
-  type AgentType
+  type AgentType,
+  type MigrationUnsupportedPtyEntry
 } from '../../../../shared/agent-status-types'
+import { parsePaneKey } from '../../../../shared/stable-pane-id'
+import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
 
 type ThreadReadFilter = 'all' | 'unread'
 type ActivityGroupBy = 'status' | 'project' | 'worktree' | 'agent'
@@ -77,6 +80,7 @@ type ActivityEvent = {
   tab: TerminalTab
   agentType: AgentType
   agentAlive: boolean
+  migrationUnsupportedPtyId?: string
   unread: boolean
 }
 
@@ -91,8 +95,8 @@ type ActivityLiveAgentSnapshot = {
 }
 
 // Why (per-pane thread): the activity feed is keyed on the agent pane (a
-// terminal tab + pane id) rather than on the workspace, so the left list
-// shows one entry per agent. paneKey is the stable identity (`${tabId}:${paneId}`).
+// terminal tab + stable leaf id) rather than on the workspace, so the left list
+// shows one entry per agent. paneKey is the durable identity (`${tabId}:${leafId}`).
 type AgentPaneThread = {
   paneKey: string
   paneTitle: string
@@ -106,6 +110,7 @@ type AgentPaneThread = {
   latestTimestamp: number
   latestEvent: ActivityEvent | null
   events: ActivityEvent[]
+  migrationUnsupportedPtyId?: string
   unread: boolean
 }
 
@@ -119,13 +124,14 @@ type ActivityThreadGroup = {
 
 type ActivityTerminalPortalReadiness = {
   target: HTMLElement | null
-  tabId: string | null
-  ready: boolean
+  paneKey: string | null
+  status: 'loading' | 'ready' | 'unavailable'
 }
 
 type ActivityTerminalPortalDomStatus = {
   hasSelectedRoot: boolean
   ready: boolean
+  unavailable: boolean
 }
 
 type ActivityTerminalPortalSlotId = 'primary' | 'secondary'
@@ -168,6 +174,43 @@ function formatRelativeTime(timestamp: number): string {
   return relativeTimeFormatter.format(diffDays, 'day')
 }
 
+function findActivityTerminalPane(
+  root: HTMLElement,
+  leafId: string
+): { foundAnyPane: boolean; pane: HTMLElement | null } {
+  let foundAnyPane = false
+  for (const candidate of root.querySelectorAll<HTMLElement>('[data-leaf-id]')) {
+    foundAnyPane = true
+    if (candidate.dataset.leafId === leafId) {
+      return { foundAnyPane, pane: candidate }
+    }
+  }
+  return { foundAnyPane, pane: null }
+}
+
+function hasInlineDisplayNoneBetween(element: HTMLElement, root: HTMLElement): boolean {
+  let current: HTMLElement | null = element
+  while (current) {
+    if (current.style.display === 'none') {
+      return true
+    }
+    if (current === root) {
+      return false
+    }
+    current = current.parentElement
+  }
+  return false
+}
+
+function hasUnhiddenSiblingPane(root: HTMLElement, selectedPane: HTMLElement): boolean {
+  for (const candidate of root.querySelectorAll<HTMLElement>('[data-leaf-id]')) {
+    if (candidate !== selectedPane && !hasInlineDisplayNoneBetween(candidate, root)) {
+      return true
+    }
+  }
+  return false
+}
+
 function truncatePreservingSurrogates(value: string, maxLength: number): string {
   if (value.length <= maxLength) {
     return value
@@ -195,50 +238,70 @@ export function activityThreadResponseRenderPreview({
   ).trimEnd()}...`
 }
 
-function paneIdFromPaneKey(paneKey: string): number | null {
-  const colon = paneKey.indexOf(':')
-  const tail = colon > 0 ? paneKey.slice(colon + 1) : ''
-  const parsed = /^\d+$/.test(tail) ? Number.parseInt(tail, 10) : NaN
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : null
-}
-
 function getSelectedActivityTerminalPortalStatus(
   target: HTMLElement,
-  tabId: string
+  paneKey: string
 ): ActivityTerminalPortalDomStatus {
+  const parsed = parsePaneKey(paneKey)
+  if (!parsed) {
+    return { hasSelectedRoot: false, ready: false, unavailable: true }
+  }
   let selectedRoot: HTMLElement | null = null
   for (const candidate of target.querySelectorAll<HTMLElement>('[data-terminal-tab-id]')) {
-    if (candidate.dataset.terminalTabId === tabId) {
+    if (candidate.dataset.terminalTabId === parsed.tabId) {
       selectedRoot = candidate
       break
     }
   }
   if (!selectedRoot) {
-    return { hasSelectedRoot: false, ready: false }
+    return { hasSelectedRoot: false, ready: false, unavailable: false }
   }
+
+  const { foundAnyPane, pane: selectedPane } = findActivityTerminalPane(selectedRoot, parsed.leafId)
+  if (!selectedPane) {
+    return { hasSelectedRoot: true, ready: false, unavailable: foundAnyPane }
+  }
+
+  const unavailable = hasInlineDisplayNoneBetween(selectedPane, selectedRoot)
+  const hasUnisolatedSibling = hasUnhiddenSiblingPane(selectedRoot, selectedPane)
+  const isVisibleRoot =
+    !unavailable && (selectedPane.offsetParent !== null || selectedPane.getClientRects().length > 0)
   const hasPtyBinding =
-    selectedRoot.hasAttribute('data-pty-id') ||
-    selectedRoot.querySelector<HTMLElement>('[data-pty-id]') !== null
-  const hasXtermScreen = selectedRoot.querySelector<HTMLElement>('.xterm-screen') !== null
-  return { hasSelectedRoot: true, ready: hasPtyBinding && hasXtermScreen }
+    selectedPane.hasAttribute('data-pty-id') ||
+    selectedPane.querySelector<HTMLElement>('[data-pty-id]') !== null
+  const hasXtermScreen = selectedPane.querySelector<HTMLElement>('.xterm-screen') !== null
+  return {
+    hasSelectedRoot: true,
+    ready: isVisibleRoot && !hasUnisolatedSibling && hasPtyBinding && hasXtermScreen,
+    unavailable
+  }
 }
 
-function useActivityTerminalPortalReadiness(
+function useActivityTerminalPortalStatus(
   target: HTMLElement | null,
-  tabId: string | null
-): boolean {
+  paneKey: string | null,
+  forceUnavailable = false
+): ActivityTerminalPortalReadiness['status'] {
   const [readiness, setReadiness] = useState<ActivityTerminalPortalReadiness>({
     target: null,
-    tabId: null,
-    ready: false
+    paneKey: null,
+    status: 'loading'
   })
 
   useLayoutEffect(() => {
-    if (!target || !tabId) {
+    if (!target || !paneKey) {
       setReadiness((prev) =>
-        prev.target === null && prev.tabId === null && !prev.ready
+        prev.target === null && prev.paneKey === null && prev.status === 'loading'
           ? prev
-          : { target: null, tabId: null, ready: false }
+          : { target: null, paneKey: null, status: 'loading' }
+      )
+      return
+    }
+    if (forceUnavailable) {
+      setReadiness((prev) =>
+        prev.target === target && prev.paneKey === paneKey && prev.status === 'unavailable'
+          ? prev
+          : { target, paneKey, status: 'unavailable' }
       )
       return
     }
@@ -247,11 +310,11 @@ function useActivityTerminalPortalReadiness(
     let readyFrame: number | null = null
     let sawUnreadySelectedRoot = false
 
-    const updateReadiness = (ready: boolean): void => {
+    const updateReadiness = (status: ActivityTerminalPortalReadiness['status']): void => {
       setReadiness((prev) =>
-        prev.target === target && prev.tabId === tabId && prev.ready === ready
+        prev.target === target && prev.paneKey === paneKey && prev.status === status
           ? prev
-          : { target, tabId, ready }
+          : { target, paneKey, status }
       )
     }
 
@@ -263,11 +326,16 @@ function useActivityTerminalPortalReadiness(
     }
 
     const checkReadiness = (): void => {
-      const status = getSelectedActivityTerminalPortalStatus(target, tabId)
+      const status = getSelectedActivityTerminalPortalStatus(target, paneKey)
+      if (status.unavailable) {
+        cancelReadyFrame()
+        updateReadiness('unavailable')
+        return
+      }
       if (status.ready) {
         if (!sawUnreadySelectedRoot) {
           cancelReadyFrame()
-          updateReadiness(true)
+          updateReadiness('ready')
           return
         }
         if (readyFrame !== null) {
@@ -278,8 +346,8 @@ function useActivityTerminalPortalReadiness(
         // frame without moving terminal lifecycle work into global layout effects.
         readyFrame = requestAnimationFrame(() => {
           readyFrame = null
-          if (!disposed && getSelectedActivityTerminalPortalStatus(target, tabId).ready) {
-            updateReadiness(true)
+          if (!disposed && getSelectedActivityTerminalPortalStatus(target, paneKey).ready) {
+            updateReadiness('ready')
           }
         })
         return
@@ -288,10 +356,10 @@ function useActivityTerminalPortalReadiness(
         sawUnreadySelectedRoot = true
       }
       cancelReadyFrame()
-      updateReadiness(false)
+      updateReadiness('loading')
     }
 
-    updateReadiness(false)
+    updateReadiness('loading')
     checkReadiness()
 
     const observer = new MutationObserver(checkReadiness)
@@ -299,7 +367,7 @@ function useActivityTerminalPortalReadiness(
       childList: true,
       subtree: true,
       attributes: true,
-      attributeFilter: ['data-terminal-tab-id', 'data-pty-id']
+      attributeFilter: ['data-terminal-tab-id', 'data-leaf-id', 'data-pty-id', 'style']
     })
 
     return () => {
@@ -307,9 +375,9 @@ function useActivityTerminalPortalReadiness(
       cancelReadyFrame()
       observer.disconnect()
     }
-  }, [target, tabId])
+  }, [target, paneKey, forceUnavailable])
 
-  return readiness.target === target && readiness.tabId === tabId && readiness.ready
+  return readiness.target === target && readiness.paneKey === paneKey ? readiness.status : 'loading'
 }
 
 function otherActivityTerminalSlot(
@@ -440,6 +508,7 @@ function appendActivityEvent(args: {
   agentType: AgentType
   agentAlive: boolean
   acknowledgedAt: number
+  migrationUnsupportedPtyId?: string
 }): void {
   const id = `agent:${args.entry.paneKey}:${args.state}:${args.timestamp}`
   if (args.seenEventIds.has(id)) {
@@ -456,6 +525,7 @@ function appendActivityEvent(args: {
     tab: args.tab,
     agentType: args.agentType,
     agentAlive: args.agentAlive,
+    migrationUnsupportedPtyId: args.migrationUnsupportedPtyId,
     unread: args.acknowledgedAt < args.timestamp
   })
 }
@@ -470,6 +540,7 @@ function appendActivityEventsForEntry(args: {
   agentType: AgentType
   agentAlive: boolean
   acknowledgedAt: number
+  migrationUnsupportedPtyId?: string
 }): void {
   // Why: Activity is an append-only history surface. When a user continues in
   // the same terminal pane, the live entry moves done→working; stateHistory is
@@ -498,6 +569,7 @@ function appendActivityEventsForEntry(args: {
 
 export function buildActivityEvents(args: {
   agentStatusByPaneKey: Record<string, AgentStatusEntry>
+  migrationUnsupportedByPtyId?: Record<string, MigrationUnsupportedPtyEntry>
   retainedAgentsByPaneKey: Record<string, RetainedAgentEntry>
   tabsByWorktree: Record<string, TerminalTab[]>
   worktreeMap: Map<string, Worktree>
@@ -521,12 +593,11 @@ export function buildActivityEvents(args: {
   }
 
   for (const [paneKey, entry] of Object.entries(args.agentStatusByPaneKey)) {
-    const separatorIndex = paneKey.indexOf(':')
-    if (separatorIndex <= 0) {
+    const parsed = parsePaneKey(paneKey)
+    if (!parsed) {
       continue
     }
-    const tabId = paneKey.slice(0, separatorIndex)
-    const context = tabContext.get(tabId)
+    const context = tabContext.get(parsed.tabId)
     if (!context) {
       continue
     }
@@ -559,7 +630,47 @@ export function buildActivityEvents(args: {
     })
   }
 
+  for (const unsupported of Object.values(args.migrationUnsupportedByPtyId ?? {})) {
+    const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
+    if (!entry) {
+      continue
+    }
+    const parsed = parsePaneKey(entry.paneKey)
+    if (!parsed) {
+      continue
+    }
+    const context = tabContext.get(parsed.tabId)
+    if (!context) {
+      continue
+    }
+    const ackAt = args.acknowledgedAgentsByPaneKey[entry.paneKey] ?? 0
+    liveAgentByPaneKey[entry.paneKey] = {
+      state: 'blocked',
+      timestamp: entry.stateStartedAt,
+      worktree: context.worktree,
+      repo: args.repoMap.get(context.worktree.repoId) ?? null,
+      entry,
+      tab: context.tab,
+      agentType: entry.agentType ?? 'unknown'
+    }
+    appendActivityEventsForEntry({
+      events,
+      seenEventIds,
+      worktree: context.worktree,
+      repo: args.repoMap.get(context.worktree.repoId) ?? null,
+      entry,
+      tab: context.tab,
+      agentType: entry.agentType ?? 'unknown',
+      agentAlive: false,
+      acknowledgedAt: ackAt,
+      migrationUnsupportedPtyId: unsupported.ptyId
+    })
+  }
+
   for (const [paneKey, retained] of Object.entries(args.retainedAgentsByPaneKey)) {
+    if (!parsePaneKey(paneKey)) {
+      continue
+    }
     const worktree = args.worktreeMap.get(retained.worktreeId)
     if (!worktree) {
       continue
@@ -618,12 +729,15 @@ export function buildAgentPaneThreads(args: {
         latestTimestamp: event.timestamp,
         latestEvent: event,
         events: [event],
+        migrationUnsupportedPtyId: event.migrationUnsupportedPtyId,
         unread: event.unread
       })
       continue
     }
     existing.events.push(event)
     existing.unread = existing.unread || event.unread
+    existing.migrationUnsupportedPtyId =
+      existing.migrationUnsupportedPtyId ?? event.migrationUnsupportedPtyId
     if (!existing.latestEvent || event.timestamp > existing.latestEvent.timestamp) {
       existing.latestEvent = event
       existing.paneTitle = paneTitleForEvent(event)
@@ -1090,6 +1204,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
   const storeData = useAppStore(
     useShallow((s) => ({
       agentStatusByPaneKey: s.agentStatusByPaneKey,
+      migrationUnsupportedByPtyId: s.migrationUnsupportedByPtyId,
       retainedAgentsByPaneKey: s.retainedAgentsByPaneKey,
       tabsByWorktree: s.tabsByWorktree,
       worktreeMap: getWorktreeMapFromState(s),
@@ -1108,6 +1223,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     () =>
       buildActivityEvents({
         agentStatusByPaneKey: storeData.agentStatusByPaneKey,
+        migrationUnsupportedByPtyId: storeData.migrationUnsupportedByPtyId,
         retainedAgentsByPaneKey: storeData.retainedAgentsByPaneKey,
         tabsByWorktree: storeData.tabsByWorktree,
         worktreeMap: storeData.worktreeMap,
@@ -1199,10 +1315,20 @@ export default function ActivityPrototypePage(): React.JSX.Element {
   } satisfies Record<ActivityTerminalPortalSlotId, HTMLElement | null>
   const activePortalTargetEl = portalTargetBySlot[activePortalSlotId]
   const inactivePortalTargetEl = portalTargetBySlot[inactivePortalSlotId]
-  const visibleTabId = visibleThread?.tab.id ?? null
-  const stagedTabId = stagedThread?.tab.id ?? null
-  const visiblePortalReady = useActivityTerminalPortalReadiness(activePortalTargetEl, visibleTabId)
-  const stagedPortalReady = useActivityTerminalPortalReadiness(inactivePortalTargetEl, stagedTabId)
+  const visiblePortalStatus = useActivityTerminalPortalStatus(
+    activePortalTargetEl,
+    visibleThread?.paneKey ?? null,
+    visibleThread?.migrationUnsupportedPtyId !== undefined
+  )
+  const stagedPortalStatus = useActivityTerminalPortalStatus(
+    inactivePortalTargetEl,
+    stagedThread?.paneKey ?? null,
+    stagedThread?.migrationUnsupportedPtyId !== undefined
+  )
+  const visiblePortalReady = visiblePortalStatus === 'ready'
+  const visiblePortalUnavailable = visiblePortalStatus === 'unavailable'
+  const stagedPortalReady = stagedPortalStatus === 'ready'
+  const stagedPortalUnavailable = stagedPortalStatus === 'unavailable'
   const showTerminalLoadingLabel = useActivityTerminalLoadingLabel(
     Boolean(visibleThread && !stagedThread && !visiblePortalReady)
   )
@@ -1232,20 +1358,24 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     if (visibleThread && activePortalTargetEl) {
       descriptors.push({
         slotId: activePortalSlotId,
+        requestToken: `${activePortalSlotId}:${visibleThread.paneKey}`,
         target: activePortalTargetEl,
         worktreeId: visibleThread.worktree.id,
         tabId: visibleThread.tab.id,
-        paneId: paneIdFromPaneKey(visibleThread.paneKey),
+        paneKey: visibleThread.paneKey,
+        forceUnavailable: visibleThread.migrationUnsupportedPtyId !== undefined,
         active: true
       })
     }
     if (stagedThread && inactivePortalTargetEl) {
       descriptors.push({
         slotId: inactivePortalSlotId,
+        requestToken: `${inactivePortalSlotId}:${stagedThread.paneKey}`,
         target: inactivePortalTargetEl,
         worktreeId: stagedThread.worktree.id,
         tabId: stagedThread.tab.id,
-        paneId: paneIdFromPaneKey(stagedThread.paneKey),
+        paneKey: stagedThread.paneKey,
+        forceUnavailable: stagedThread.migrationUnsupportedPtyId !== undefined,
         active: false
       })
     }
@@ -1264,7 +1394,9 @@ export default function ActivityPrototypePage(): React.JSX.Element {
       setDisplayedPaneKey(null)
       return
     }
-    if (stagedThread && stagedPortalReady) {
+    if (stagedThread && (stagedPortalReady || stagedPortalUnavailable)) {
+      // Why: a stale selected pane should replace the old terminal with the
+      // unavailable state, not leave the previous pane visible under the new row.
       setActivePortalSlotId(inactivePortalSlotId)
       setDisplayedPaneKey(stagedThread.paneKey)
       return
@@ -1276,6 +1408,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     inactivePortalSlotId,
     selectedHasLiveTab,
     selectedThread,
+    stagedPortalUnavailable,
     stagedPortalReady,
     stagedThread,
     visiblePortalReady,
@@ -1325,15 +1458,44 @@ export default function ActivityPrototypePage(): React.JSX.Element {
       state.setActiveWorktree(thread.worktree.id)
     }
     state.setActiveTabType('terminal')
-    activateTabAndFocusPane(thread.tab.id, paneIdFromPaneKey(thread.paneKey))
+    const parsed = parsePaneKey(thread.paneKey)
+    activateTabAndFocusPane(
+      thread.tab.id,
+      parsed && parsed.tabId === thread.tab.id ? parsed.leafId : null
+    )
   }
 
   const selectThread = (thread: AgentPaneThread): void => {
     setSelectedPaneKey(thread.paneKey)
-    markThreadRead(thread)
     activateThreadTerminal(thread)
   }
 
+  useEffect(() => {
+    if (
+      !selectedThread ||
+      !selectedThread.unread ||
+      stagedThread ||
+      selectedThread.paneKey !== selectedPaneKey
+    ) {
+      return
+    }
+    const selectedThreadHasDetailOnlyView =
+      !selectedHasLiveTab || selectedThread.migrationUnsupportedPtyId !== undefined
+    const selectedThreadIsVisibleTerminal =
+      visibleThread?.paneKey === selectedPaneKey && visiblePortalReady
+    if (selectedThreadHasDetailOnlyView || selectedThreadIsVisibleTerminal) {
+      storeData.acknowledgeAgents([selectedThread.paneKey])
+    }
+  }, [
+    selectedHasLiveTab,
+    selectedPaneKey,
+    selectedThread,
+    stagedThread,
+    storeData,
+    visiblePortalReady,
+    visibleThread
+  ])
+
   const jumpToWorkspace = (thread: AgentPaneThread): void => {
     markThreadRead(thread)
     activateAndRevealWorktree(thread.worktree.id)
@@ -1566,7 +1728,12 @@ export default function ActivityPrototypePage(): React.JSX.Element {
                         className="pointer-events-none absolute inset-0 z-20 bg-editor-surface"
                         aria-hidden="true"
                       >
-                        {showTerminalLoadingLabel ? (
+                        {visiblePortalUnavailable ? (
+                          <div className="ml-3 mt-3 inline-flex items-center gap-2 rounded-md border border-border bg-background/85 px-2 py-1 text-xs text-muted-foreground shadow-xs">
+                            <span className="h-3 w-1.5 rounded-sm bg-muted-foreground/70" />
+                            <span>Terminal unavailable</span>
+                          </div>
+                        ) : showTerminalLoadingLabel ? (
                           <div className="ml-3 mt-3 inline-flex items-center gap-2 rounded-md border border-border bg-background/85 px-2 py-1 text-xs text-muted-foreground shadow-xs">
                             <span className="h-3 w-1.5 animate-pulse rounded-sm bg-muted-foreground/70" />
                             <span>Connecting terminal...</span>
diff --git a/src/renderer/src/components/activity/ActivityTitlebarControls.tsx b/src/renderer/src/components/activity/ActivityTitlebarControls.tsx
index 6fd95fdec5e..42dafa48f7e 100644
--- a/src/renderer/src/components/activity/ActivityTitlebarControls.tsx
+++ b/src/renderer/src/components/activity/ActivityTitlebarControls.tsx
@@ -5,6 +5,7 @@ import { Badge } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import type { AgentStatusEntry, AgentStatusState } from '../../../../shared/agent-status-types'
+import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
 
 // Why: keep the unread accumulator local; "Mark all read" moved to the
 // thread-list overflow menu in ActivityPrototypePage so it lives next to
@@ -34,6 +35,12 @@ function useActivityUnreadCount(): number {
     for (const [paneKey, retained] of Object.entries(s.retainedAgentsByPaneKey)) {
       accumulate(retained.entry, s.acknowledgedAgentsByPaneKey[paneKey] ?? 0)
     }
+    for (const unsupported of Object.values(s.migrationUnsupportedByPtyId)) {
+      const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
+      if (entry) {
+        accumulate(entry, s.acknowledgedAgentsByPaneKey[entry.paneKey] ?? 0)
+      }
+    }
     return count
   })
 }
diff --git a/src/renderer/src/components/activity/activity-terminal-portal.ts b/src/renderer/src/components/activity/activity-terminal-portal.ts
index 5f7a342e4fa..c9c2203227b 100644
--- a/src/renderer/src/components/activity/activity-terminal-portal.ts
+++ b/src/renderer/src/components/activity/activity-terminal-portal.ts
@@ -2,14 +2,15 @@ import { useLayoutEffect, useState } from 'react'
 
 export type ActivityTerminalPortalTarget = {
   slotId: string
+  requestToken: string
   target: HTMLElement
   worktreeId: string
   tabId: string
-  // Why: each Activity thread is keyed on a single agent pane within a tab.
-  // Carrying paneId here lets TerminalPane isolate that pane visually
-  // (hiding split siblings) without touching the user-facing expanded-pane
-  // state or the persisted layout snapshot.
-  paneId: number | null
+  // Why: each Activity thread targets one stable terminal leaf inside a tab.
+  // Carry the durable paneKey across this boundary; TerminalPane resolves it
+  // to the current numeric PaneManager handle immediately before isolation.
+  paneKey: string
+  forceUnavailable?: boolean
   active: boolean
 }
 
@@ -56,10 +57,35 @@ export function useActivityTerminalPortals(enabled: boolean): ActivityTerminalPo
 
 export function findActivityTerminalPortal(
   targets: ActivityTerminalPortalTarget[],
-  worktreeId: string,
-  tabId: string
+  query: {
+    worktreeId: string
+    tabId: string
+    slotId?: string
+    paneKey?: string
+    requestToken?: string
+  }
 ): ActivityTerminalPortalTarget | null {
+  const matchingTab = targets.filter(
+    (target) => target.worktreeId === query.worktreeId && target.tabId === query.tabId
+  )
+  if (
+    query.slotId !== undefined ||
+    query.paneKey !== undefined ||
+    query.requestToken !== undefined
+  ) {
+    const exact = matchingTab.find(
+      (target) =>
+        (query.slotId === undefined || target.slotId === query.slotId) &&
+        (query.paneKey === undefined || target.paneKey === query.paneKey) &&
+        (query.requestToken === undefined || target.requestToken === query.requestToken)
+    )
+    if (exact) {
+      return exact
+    }
+  }
   return (
-    targets.find((target) => target.worktreeId === worktreeId && target.tabId === tabId) ?? null
+    matchingTab.find((target) => target.active) ??
+    (matchingTab.length === 1 ? matchingTab[0] : null) ??
+    null
   )
 }
diff --git a/src/renderer/src/components/dashboard/useDashboardData.ts b/src/renderer/src/components/dashboard/useDashboardData.ts
index 1385f8a9d05..634bfb98e59 100644
--- a/src/renderer/src/components/dashboard/useDashboardData.ts
+++ b/src/renderer/src/components/dashboard/useDashboardData.ts
@@ -5,9 +5,12 @@ import {
   AGENT_STATUS_STALE_AFTER_MS,
   type AgentStatusEntry,
   type AgentStatusState,
-  type AgentType
+  type AgentType,
+  type MigrationUnsupportedPtyEntry
 } from '../../../../shared/agent-status-types'
 import type { Repo, Worktree, TerminalTab } from '../../../../shared/types'
+import { parsePaneKey } from '../../../../shared/stable-pane-id'
+import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
 
 // ─── Shared data types ────────────────────────────────────────────────────────
 
@@ -96,25 +99,40 @@ function buildDashboardData(
   worktreesByRepo: Record<string, Worktree[]>,
   tabsByWorktree: Record<string, TerminalTab[]>,
   agentStatusByPaneKey: Record<string, AgentStatusEntry>,
+  migrationUnsupportedByPtyId: Record<string, MigrationUnsupportedPtyEntry>,
   now: number
 ): DashboardRepoGroup[] {
   // Why: build a tabId -> entries index once per computation instead of
   // re-scanning every agent status entry inside the per-tab loop. paneKey is
-  // formatted as `${tabId}:${paneId}`; splitting on the first ':' lets us
-  // bucket entries by tab in a single O(N) pass, turning the per-worktree
-  // build from O(tabs × statuses) into O(tabs).
+  // formatted as `${tabId}:${leafId}`; parsePaneKey also drops legacy numeric
+  // suffixes so stale rows do not remain routable after pane replay.
   const entriesByTabId = new Map<string, AgentStatusEntry[]>()
   for (const [paneKey, entry] of Object.entries(agentStatusByPaneKey)) {
-    const colonIndex = paneKey.indexOf(':')
-    if (colonIndex === -1) {
+    const parsed = parsePaneKey(paneKey)
+    if (!parsed) {
       continue
     }
-    const tabId = paneKey.slice(0, colonIndex)
-    const bucket = entriesByTabId.get(tabId)
+    const bucket = entriesByTabId.get(parsed.tabId)
     if (bucket) {
       bucket.push(entry)
     } else {
-      entriesByTabId.set(tabId, [entry])
+      entriesByTabId.set(parsed.tabId, [entry])
+    }
+  }
+  for (const unsupported of Object.values(migrationUnsupportedByPtyId)) {
+    const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
+    if (!entry) {
+      continue
+    }
+    const parsed = parsePaneKey(entry.paneKey)
+    if (!parsed) {
+      continue
+    }
+    const bucket = entriesByTabId.get(parsed.tabId)
+    if (bucket) {
+      bucket.push(entry)
+    } else {
+      entriesByTabId.set(parsed.tabId, [entry])
     }
   }
 
@@ -143,6 +161,7 @@ export function useDashboardData(): DashboardRepoGroup[] {
   const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
   const tabsByWorktree = useAppStore((s) => s.tabsByWorktree)
   const agentStatusByPaneKey = useAppStore((s) => s.agentStatusByPaneKey)
+  const migrationUnsupportedByPtyId = useAppStore((s) => s.migrationUnsupportedByPtyId)
   // Why: agentStatusEpoch is included in the dependency array (but not in the
   // computation itself) so the memo recomputes when freshness boundaries expire,
   // even if no new PTY data arrives.
@@ -154,8 +173,22 @@ export function useDashboardData(): DashboardRepoGroup[] {
     // freshness boundary crosses, driving re-evaluation without coupling to
     // wall-clock time directly.
     () =>
-      buildDashboardData(repos, worktreesByRepo, tabsByWorktree, agentStatusByPaneKey, Date.now()),
+      buildDashboardData(
+        repos,
+        worktreesByRepo,
+        tabsByWorktree,
+        agentStatusByPaneKey,
+        migrationUnsupportedByPtyId,
+        Date.now()
+      ),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [repos, worktreesByRepo, tabsByWorktree, agentStatusByPaneKey, agentStatusEpoch]
+    [
+      repos,
+      worktreesByRepo,
+      tabsByWorktree,
+      agentStatusByPaneKey,
+      migrationUnsupportedByPtyId,
+      agentStatusEpoch
+    ]
   )
 }
diff --git a/src/renderer/src/components/dashboard/useRetainedAgents.ts b/src/renderer/src/components/dashboard/useRetainedAgents.ts
index bb3d0f8271c..8a68b3638db 100644
--- a/src/renderer/src/components/dashboard/useRetainedAgents.ts
+++ b/src/renderer/src/components/dashboard/useRetainedAgents.ts
@@ -8,6 +8,7 @@ import {
   AGENT_STATUS_STALE_AFTER_MS,
   type AgentStatusEntry
 } from '../../../../shared/agent-status-types'
+import { parsePaneKey } from '../../../../shared/stable-pane-id'
 
 // Why: when an agent finishes or its terminal closes, the store cleans up the
 // explicit status entry and the agent vanishes from the live status set.
@@ -30,11 +31,7 @@ type RetainedAgentsSyncSnapshotInputs = RetainedAgentsSyncInputs & {
 }
 
 function paneKeyTabId(paneKey: string): string | null {
-  const colonIndex = paneKey.indexOf(':')
-  if (colonIndex <= 0) {
-    return null
-  }
-  return paneKey.slice(0, colonIndex)
+  return parsePaneKey(paneKey)?.tabId ?? null
 }
 
 function buildLiveTabIndex(args: {
diff --git a/src/renderer/src/components/dashboard/useRetainedAgentsSync.test.ts b/src/renderer/src/components/dashboard/useRetainedAgentsSync.test.ts
index beb25518362..c87c4612b18 100644
--- a/src/renderer/src/components/dashboard/useRetainedAgentsSync.test.ts
+++ b/src/renderer/src/components/dashboard/useRetainedAgentsSync.test.ts
@@ -5,11 +5,16 @@ import {
   type AgentStatusState
 } from '../../../../shared/agent-status-types'
 import type { Repo, TerminalTab, Worktree } from '../../../../shared/types'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
 import {
   buildRetainedAgentsSyncSignature,
   buildRetainedAgentsSyncSnapshot
 } from './useRetainedAgents'
 
+const PANE_KEY = makePaneKey('tab-1', '11111111-1111-4111-8111-111111111111')
+const ACTIVE_PANE_KEY = makePaneKey('tab-active', '22222222-2222-4222-8222-222222222222')
+const ARCHIVED_PANE_KEY = makePaneKey('tab-archived', '33333333-3333-4333-8333-333333333333')
+
 function makeRepo(): Repo {
   return {
     id: 'repo-1',
@@ -95,8 +100,8 @@ describe('buildRetainedAgentsSyncSignature', () => {
   it('ignores fresh same-state working ping details but changes on state transitions', () => {
     const first = buildRetainedAgentsSyncSignature(
       makeSyncInputs({
-        'tab-1:1': makeEntry({
-          paneKey: 'tab-1:1',
+        [PANE_KEY]: makeEntry({
+          paneKey: PANE_KEY,
           state: 'working',
           updatedAt: 1_000,
           stateStartedAt: 1_000,
@@ -107,8 +112,8 @@ describe('buildRetainedAgentsSyncSignature', () => {
     )
     const sameState = buildRetainedAgentsSyncSignature(
       makeSyncInputs({
-        'tab-1:1': makeEntry({
-          paneKey: 'tab-1:1',
+        [PANE_KEY]: makeEntry({
+          paneKey: PANE_KEY,
           state: 'working',
           updatedAt: 2_000,
           stateStartedAt: 1_000,
@@ -119,8 +124,8 @@ describe('buildRetainedAgentsSyncSignature', () => {
     )
     const done = buildRetainedAgentsSyncSignature(
       makeSyncInputs({
-        'tab-1:1': makeEntry({
-          paneKey: 'tab-1:1',
+        [PANE_KEY]: makeEntry({
+          paneKey: PANE_KEY,
           state: 'done',
           updatedAt: 3_000,
           stateStartedAt: 3_000,
@@ -136,8 +141,8 @@ describe('buildRetainedAgentsSyncSignature', () => {
   it('tracks same-state done updates so retention keeps the final snapshot', () => {
     const done = buildRetainedAgentsSyncSignature(
       makeSyncInputs({
-        'tab-1:1': makeEntry({
-          paneKey: 'tab-1:1',
+        [PANE_KEY]: makeEntry({
+          paneKey: PANE_KEY,
           state: 'done',
           updatedAt: 3_000,
           stateStartedAt: 3_000
@@ -146,8 +151,8 @@ describe('buildRetainedAgentsSyncSignature', () => {
     )
     const updatedDone = buildRetainedAgentsSyncSignature(
       makeSyncInputs({
-        'tab-1:1': makeEntry({
-          paneKey: 'tab-1:1',
+        [PANE_KEY]: makeEntry({
+          paneKey: PANE_KEY,
           state: 'done',
           updatedAt: 4_000,
           stateStartedAt: 3_000
@@ -175,14 +180,14 @@ describe('buildRetainedAgentsSyncSnapshot', () => {
         [archivedWorktree.id]: [archivedTab]
       },
       agentStatusByPaneKey: {
-        'tab-active:1': makeEntry({
-          paneKey: 'tab-active:1',
+        [ACTIVE_PANE_KEY]: makeEntry({
+          paneKey: ACTIVE_PANE_KEY,
           state: 'working',
           updatedAt: 10_000,
           stateStartedAt: 10_000
         }),
-        'tab-archived:1': makeEntry({
-          paneKey: 'tab-archived:1',
+        [ARCHIVED_PANE_KEY]: makeEntry({
+          paneKey: ARCHIVED_PANE_KEY,
           state: 'done',
           updatedAt: 20_000,
           stateStartedAt: 20_000
@@ -192,7 +197,7 @@ describe('buildRetainedAgentsSyncSnapshot', () => {
     })
 
     expect([...snapshot.existingWorktreeIds]).toEqual(['wt-active'])
-    expect(snapshot.currentAgents.get('tab-active:1')?.row.state).toBe('idle')
-    expect(snapshot.currentAgents.get('tab-archived:1')).toBeUndefined()
+    expect(snapshot.currentAgents.get(ACTIVE_PANE_KEY)?.row.state).toBe('idle')
+    expect(snapshot.currentAgents.get(ARCHIVED_PANE_KEY)).toBeUndefined()
   })
 })
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index 98e9053fe8f..71eaea8e1f4 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -462,7 +462,9 @@ function SourceControlInner(): React.JSX.Element {
   const branchName = activeWorktree?.branch.replace(/^refs\/heads\//, '') ?? 'HEAD'
   const hostedReviewCacheKey =
     activeRepo && branchName ? getHostedReviewCacheKey(activeRepo.path, branchName, settings) : null
-  const hostedReviewEntry = hostedReviewCacheKey ? hostedReviewCache[hostedReviewCacheKey] : undefined
+  const hostedReviewEntry = hostedReviewCacheKey
+    ? hostedReviewCache[hostedReviewCacheKey]
+    : undefined
   const hostedReview: HostedReviewInfo | null = hostedReviewCacheKey
     ? (hostedReviewEntry?.data ?? null)
     : null
diff --git a/src/renderer/src/components/sidebar/CacheTimer.tsx b/src/renderer/src/components/sidebar/CacheTimer.tsx
index 61f2f44763d..2f4ee986ee4 100644
--- a/src/renderer/src/components/sidebar/CacheTimer.tsx
+++ b/src/renderer/src/components/sidebar/CacheTimer.tsx
@@ -32,7 +32,7 @@ export default function CacheTimer({
     }
     let oldest: number | null = null
     for (const tab of tabs) {
-      // Why: cache timer keys are `${tabId}:${paneId}` composites, so we check
+      // Why: cache timer keys are `${tabId}:${leafId}` composites, so we check
       // all keys that belong to this tab's panes.
       for (const key of Object.keys(s.cacheTimerByKey)) {
         if (!key.startsWith(`${tab.id}:`)) {
diff --git a/src/renderer/src/components/sidebar/SidebarNav.tsx b/src/renderer/src/components/sidebar/SidebarNav.tsx
index bffed9d67ab..febf70e7aea 100644
--- a/src/renderer/src/components/sidebar/SidebarNav.tsx
+++ b/src/renderer/src/components/sidebar/SidebarNav.tsx
@@ -6,6 +6,7 @@ import { cn } from '@/lib/utils'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import { getTaskPresetQuery, PER_REPO_FETCH_LIMIT } from '@/lib/new-workspace'
 import { LinearIcon } from '@/components/icons/LinearIcon'
+import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
 
 const isMac = typeof navigator !== 'undefined' && navigator.userAgent.includes('Mac')
 
@@ -77,6 +78,15 @@ const SidebarNav = React.memo(function SidebarNav() {
         count += 1
       }
     }
+    for (const unsupported of Object.values(s.migrationUnsupportedByPtyId)) {
+      const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
+      if (!entry) {
+        continue
+      }
+      if ((s.acknowledgedAgentsByPaneKey[entry.paneKey] ?? 0) < entry.stateStartedAt) {
+        count += 1
+      }
+    }
     return count
   })
 
diff --git a/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx b/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
index 4d9c5f609de..8499ea1de4c 100644
--- a/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
@@ -7,6 +7,8 @@ import { useNow } from '@/components/dashboard/useNow'
 import { useWorktreeAgentRows } from './useWorktreeAgentRows'
 import { cn } from '@/lib/utils'
 import type { DashboardAgentRow as DashboardAgentRowData } from '@/components/dashboard/useDashboardData'
+import { parsePaneKey } from '../../../../shared/stable-pane-id'
+import { dismissStaleAgentRowByKey } from '../terminal-pane/stale-agent-row'
 
 type Props = {
   worktreeId: string
@@ -51,7 +53,6 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
 }: BodyProps) {
   const dropAgentStatus = useAppStore((s) => s.dropAgentStatus)
   const dismissRetainedAgent = useAppStore((s) => s.dismissRetainedAgent)
-  const acknowledgeAgents = useAppStore((s) => s.acknowledgeAgents)
 
   // Why: subscribe to the ack map reference (Object.is equality) and derive
   // per-agent unvisited flags locally. Keeps the inline list's bold/mute
@@ -79,18 +80,21 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
 
   const handleActivateAgentTab = useCallback(
     (tabId: string, paneKey: string) => {
-      acknowledgeAgents([paneKey])
-      const colon = paneKey.indexOf(':')
-      const tail = colon > 0 ? paneKey.slice(colon + 1) : ''
-      const parsed = /^\d+$/.test(tail) ? Number.parseInt(tail, 10) : NaN
-      let paneId: number | null = null
-      if (Number.isFinite(parsed) && parsed > 0) {
-        paneId = parsed
-      } else {
-        // Why: paneKey for sidebar agent rows is always ${tabId}:${paneId}
-        // with a positive integer paneId; anything else (empty, zero,
-        // non-numeric) means upstream row construction drifted.
+      const parsed = parsePaneKey(paneKey)
+      if (!parsed) {
+        // Why: malformed or legacy numeric keys cannot be resolved safely after
+        // pane replay/remount, so drop the stale row instead of guessing.
         console.warn('[WorktreeCardAgents] malformed paneKey, skipping pane focus', paneKey)
+        dismissStaleAgentRowByKey(paneKey)
+        return
+      }
+      if (parsed.tabId !== tabId) {
+        console.warn('[WorktreeCardAgents] paneKey tabId mismatch, dismissing row', {
+          tabId,
+          paneKey
+        })
+        dismissStaleAgentRowByKey(paneKey)
+        return
       }
       // Why: route through activateAndRevealWorktree so cross-repo clicks also
       // set activeRepoId, record a nav-history entry, clear sidebar filters,
@@ -102,10 +106,12 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
       activateAndRevealWorktree(worktreeId)
       const tabs = useAppStore.getState().tabsByWorktree[worktreeId] ?? []
       if (tabs.some((t) => t.id === tabId)) {
-        activateTabAndFocusPane(tabId, paneId)
+        activateTabAndFocusPane(tabId, parsed.leafId, { ackPaneKeyOnSuccess: paneKey })
+      } else {
+        dismissStaleAgentRowByKey(paneKey)
       }
     },
-    [worktreeId, acknowledgeAgents]
+    [worktreeId]
   )
 
   // Why: own one 30s tick per non-empty inline list. Cards with zero agents
diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index 5cdfb2b7b5b..be729c1a154 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -859,7 +859,9 @@ const WorktreeList = React.memo(function WorktreeList() {
             state.agentStatusByPaneKey,
             state.runtimePaneTitlesByTabId,
             state.ptyIdsByTabId,
-            now
+            now,
+            state.migrationUnsupportedByPtyId,
+            state.terminalLayoutsByTabId
           )
         : new Map<string, WorktreeAttention>()
     lastAttentionByWorktreeRef.current = sortBy === 'smart' ? attentionByWorktree : null
diff --git a/src/renderer/src/components/sidebar/smart-attention.test.ts b/src/renderer/src/components/sidebar/smart-attention.test.ts
index 05120eae905..c4fbd18ce73 100644
--- a/src/renderer/src/components/sidebar/smart-attention.test.ts
+++ b/src/renderer/src/components/sidebar/smart-attention.test.ts
@@ -12,7 +12,7 @@ import {
   resolveAttention,
   type PaneInput
 } from './smart-attention'
-import type { TerminalTab, Worktree } from '../../../../shared/types'
+import type { TerminalLayoutSnapshot, TerminalTab, Worktree } from '../../../../shared/types'
 
 function hookPane(entry: AgentStatusEntry): PaneInput {
   return { kind: 'hook', entry }
@@ -23,6 +23,31 @@ function hookPanes(entries: AgentStatusEntry[]): PaneInput[] {
 }
 
 const NOW = new Date('2026-03-27T12:00:00.000Z').getTime()
+const LEAF_1 = '11111111-1111-4111-8111-111111111111'
+const LEAF_2 = '22222222-2222-4222-8222-222222222222'
+
+function paneKey(tabId: string, leafId: string): string {
+  return `${tabId}:${leafId}`
+}
+
+function splitLayout(
+  tabId: string,
+  firstLeafId = LEAF_1,
+  secondLeafId = LEAF_2
+): Record<string, TerminalLayoutSnapshot> {
+  return {
+    [tabId]: {
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: firstLeafId },
+        second: { type: 'leaf', leafId: secondLeafId }
+      },
+      activeLeafId: firstLeafId,
+      expandedLeafId: null
+    }
+  }
+}
 
 function makeEntry(overrides: Partial<AgentStatusEntry> & { paneKey: string }): AgentStatusEntry {
   return {
@@ -382,14 +407,14 @@ describe('buildAttentionByWorktree', () => {
     const w = makeWorktree('wt-1')
     const tab = makeTab('tab-1', w.id)
     const entries: Record<string, AgentStatusEntry> = {
-      'tab-1:1': makeEntry({
-        paneKey: 'tab-1:1',
+      [paneKey(tab.id, LEAF_1)]: makeEntry({
+        paneKey: paneKey(tab.id, LEAF_1),
         state: 'working',
         stateStartedAt: NOW - 10_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-1:2': makeEntry({
-        paneKey: 'tab-1:2',
+      [paneKey(tab.id, LEAF_2)]: makeEntry({
+        paneKey: paneKey(tab.id, LEAF_2),
         state: 'blocked',
         stateStartedAt: NOW - 5_000,
         updatedAt: NOW - 1_000
@@ -460,8 +485,8 @@ describe('buildAttentionByWorktree', () => {
     const w = makeWorktree('wt-1')
     const tab = makeTab('tab-1', w.id)
     const entries: Record<string, AgentStatusEntry> = {
-      'tab-1:1': makeEntry({
-        paneKey: 'tab-1:1',
+      [paneKey(tab.id, LEAF_1)]: makeEntry({
+        paneKey: paneKey(tab.id, LEAF_1),
         state: 'done',
         stateStartedAt: NOW - 30_000,
         updatedAt: NOW - 1_000
@@ -474,7 +499,9 @@ describe('buildAttentionByWorktree', () => {
       // Same paneId 1 — must NOT double-promote into Class 3.
       { [tab.id]: { 1: '⠋ Claude' } },
       ptyMap([tab.id]),
-      NOW
+      NOW,
+      undefined,
+      splitLayout(tab.id)
     )
     expect(map.get(w.id)).toEqual({ cls: 2, attentionTimestamp: NOW - 30_000 })
   })
@@ -483,8 +510,8 @@ describe('buildAttentionByWorktree', () => {
     const w = makeWorktree('wt-1')
     const tab = makeTab('tab-1', w.id)
     const entries: Record<string, AgentStatusEntry> = {
-      'tab-1:1': makeEntry({
-        paneKey: 'tab-1:1',
+      [paneKey(tab.id, LEAF_1)]: makeEntry({
+        paneKey: paneKey(tab.id, LEAF_1),
         state: 'done',
         stateStartedAt: NOW - 30_000,
         updatedAt: NOW - 1_000
@@ -497,7 +524,9 @@ describe('buildAttentionByWorktree', () => {
       // Pane 2 has no hook — title fallback fires for it.
       { [tab.id]: { 1: 'something', 2: '✋ Gemini CLI' } },
       ptyMap([tab.id]),
-      NOW
+      NOW,
+      undefined,
+      splitLayout(tab.id)
     )
     expect(map.get(w.id)).toEqual({
       cls: 1,
diff --git a/src/renderer/src/components/sidebar/smart-attention.ts b/src/renderer/src/components/sidebar/smart-attention.ts
index 516ced3a16d..7a1ba82e4c2 100644
--- a/src/renderer/src/components/sidebar/smart-attention.ts
+++ b/src/renderer/src/components/sidebar/smart-attention.ts
@@ -1,12 +1,21 @@
 import { detectAgentStatusFromTitle, isExplicitAgentStatusFresh } from '@/lib/agent-status'
+import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
 import { tabHasLivePty } from '@/lib/tab-has-live-pty'
 import type { AgentStatus } from '../../../../shared/agent-detection'
-import type { TerminalTab, Worktree } from '../../../../shared/types'
+import type {
+  TerminalLayoutSnapshot,
+  TerminalPaneLayoutNode,
+  TerminalTab,
+  Worktree
+} from '../../../../shared/types'
 import {
   AGENT_STATUS_STALE_AFTER_MS,
   type AgentStateHistoryEntry,
-  type AgentStatusEntry
+  type AgentStatusEntry,
+  type MigrationUnsupportedPtyEntry
 } from '../../../../shared/agent-status-types'
+import { isTerminalLeafId, parsePaneKey } from '../../../../shared/stable-pane-id'
+import { FIRST_PANE_ID } from '../../../../shared/pane-key'
 
 /**
  * Ordinal class for the "Smart" sort. Lower number = more attention-demanding.
@@ -191,43 +200,90 @@ export function resolveAttention(panes: PaneInput[], now: number): WorktreeAtten
  * resolution pay O(T) lookups instead of scanning the full map.
  */
 export function buildExplicitEntriesByTabId(
-  agentStatusByPaneKey: Record<string, AgentStatusEntry> | undefined
+  agentStatusByPaneKey: Record<string, AgentStatusEntry> | undefined,
+  migrationUnsupportedByPtyId?: Record<string, MigrationUnsupportedPtyEntry>
 ): Map<string, AgentStatusEntry[]> {
   const byTab = new Map<string, AgentStatusEntry[]>()
-  if (!agentStatusByPaneKey) {
+  const entries = [
+    ...Object.values(agentStatusByPaneKey ?? {}),
+    ...Object.values(migrationUnsupportedByPtyId ?? {}).flatMap((entry) => {
+      const agentEntry = migrationUnsupportedToAgentStatusEntry(entry)
+      return agentEntry ? [agentEntry] : []
+    })
+  ]
+  if (entries.length === 0) {
     return byTab
   }
-  for (const entry of Object.values(agentStatusByPaneKey)) {
-    const colon = entry.paneKey.indexOf(':')
-    // Why: paneKey must be `${tabId}:${paneId}`. Skip malformed entries (no
-    // colon or leading colon) rather than bucketing them under an empty tabId.
-    if (colon <= 0) {
+  for (const entry of entries) {
+    const parsed = parsePaneKey(entry.paneKey)
+    // Why: paneKey must be `${tabId}:${leafUuid}`. Skip malformed or legacy
+    // numeric entries rather than bucketing unroutable rows under a tab.
+    if (!parsed) {
       continue
     }
-    const tabId = entry.paneKey.slice(0, colon)
-    const bucket = byTab.get(tabId)
+    const bucket = byTab.get(parsed.tabId)
     if (bucket) {
       bucket.push(entry)
     } else {
-      byTab.set(tabId, [entry])
+      byTab.set(parsed.tabId, [entry])
     }
   }
   return byTab
 }
 
 /**
- * Extract the paneId from a `${tabId}:${paneId}` paneKey, returning null for
- * malformed keys (no colon or non-numeric tail). Used for per-pane authority:
- * we need to know which paneIds already have a fresh hook entry so we don't
- * double-count them via the title fallback.
+ * Extract the stable leaf id from a `${tabId}:${leafId}` paneKey. Used for
+ * per-pane authority: we need to know which leaves already have a fresh hook
+ * entry so we don't double-count them via the title fallback.
  */
-function paneIdFromPaneKey(paneKey: string): number | null {
-  const colon = paneKey.indexOf(':')
-  if (colon <= 0) {
+function leafIdFromPaneKey(paneKey: string): string | null {
+  return parsePaneKey(paneKey)?.leafId ?? null
+}
+
+function getLeftmostLeafId(node: TerminalPaneLayoutNode): string {
+  return node.type === 'leaf' ? node.leafId : getLeftmostLeafId(node.first)
+}
+
+function collectReplayCreatedPaneLeafIds(
+  node: Extract<TerminalPaneLayoutNode, { type: 'split' }>,
+  leafIdsInReplayCreationOrder: string[]
+): void {
+  leafIdsInReplayCreationOrder.push(getLeftmostLeafId(node.second))
+
+  if (node.first.type === 'split') {
+    collectReplayCreatedPaneLeafIds(node.first, leafIdsInReplayCreationOrder)
+  }
+  if (node.second.type === 'split') {
+    collectReplayCreatedPaneLeafIds(node.second, leafIdsInReplayCreationOrder)
+  }
+}
+
+function collectLeafIdsInReplayCreationOrder(
+  node: TerminalPaneLayoutNode | null | undefined
+): string[] {
+  if (!node) {
+    return []
+  }
+  const leafIdsInReplayCreationOrder = [getLeftmostLeafId(node)]
+  if (node.type === 'split') {
+    collectReplayCreatedPaneLeafIds(node, leafIdsInReplayCreationOrder)
+  }
+  return leafIdsInReplayCreationOrder
+}
+
+function resolveRuntimePaneTitleLeafId(
+  tabLayout: TerminalLayoutSnapshot | undefined,
+  runtimePaneId: string
+): string | null {
+  if (isTerminalLeafId(runtimePaneId)) {
+    return runtimePaneId
+  }
+  const numericPaneId = Number(runtimePaneId)
+  if (!Number.isInteger(numericPaneId) || numericPaneId < FIRST_PANE_ID) {
     return null
   }
-  const id = Number(paneKey.slice(colon + 1))
-  return Number.isFinite(id) ? id : null
+  const leafIds = collectLeafIdsInReplayCreationOrder(tabLayout?.root)
+  return leafIds[numericPaneId - FIRST_PANE_ID] ?? null
 }
 
 /**
@@ -248,9 +304,11 @@ export function buildAttentionByWorktree(
   agentStatusByPaneKey: Record<string, AgentStatusEntry> | undefined,
   runtimePaneTitlesByTabId: Record<string, Record<number, string>>,
   ptyIdsByTabId: Record<string, string[]>,
-  now: number
+  now: number,
+  migrationUnsupportedByPtyId?: Record<string, MigrationUnsupportedPtyEntry>,
+  terminalLayoutsByTabId?: Record<string, TerminalLayoutSnapshot>
 ): Map<string, WorktreeAttention> {
-  const byTab = buildExplicitEntriesByTabId(agentStatusByPaneKey)
+  const byTab = buildExplicitEntriesByTabId(agentStatusByPaneKey, migrationUnsupportedByPtyId)
   const result = new Map<string, WorktreeAttention>()
 
   for (const worktree of worktrees) {
@@ -262,9 +320,9 @@ export function buildAttentionByWorktree(
     const panes: PaneInput[] = []
     for (const tab of tabs) {
       const hookEntries = byTab.get(tab.id)
-      // Why: paneIds covered by a hook entry skip the title fallback so we
+      // Why: leaf ids covered by a hook entry skip the title fallback so we
       // don't double-count them. Hook authority is per-pane.
-      const hookPaneIds = new Set<number>()
+      const hookLeafIds = new Set<string>()
       if (hookEntries) {
         for (const entry of hookEntries) {
           panes.push({ kind: 'hook', entry })
@@ -275,9 +333,9 @@ export function buildAttentionByWorktree(
           if (!isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)) {
             continue
           }
-          const paneId = paneIdFromPaneKey(entry.paneKey)
-          if (paneId !== null) {
-            hookPaneIds.add(paneId)
+          const leafId = leafIdFromPaneKey(entry.paneKey)
+          if (leafId !== null) {
+            hookLeafIds.add(leafId)
           }
         }
       }
@@ -293,9 +351,10 @@ export function buildAttentionByWorktree(
       if (paneTitles && Object.keys(paneTitles).length > 0) {
         // Why: split-pane tabs can host multiple agents; each pane reports
         // its own title. Mirrors the precedence used by getWorkingAgentsPerWorktree.
-        for (const [paneIdStr, title] of Object.entries(paneTitles)) {
-          const paneId = Number(paneIdStr)
-          if (hookPaneIds.has(paneId)) {
+        const tabLayout = terminalLayoutsByTabId?.[tab.id]
+        for (const [runtimePaneId, title] of Object.entries(paneTitles)) {
+          const leafId = resolveRuntimePaneTitleLeafId(tabLayout, runtimePaneId)
+          if (leafId !== null && hookLeafIds.has(leafId)) {
             continue
           }
           panes.push({
@@ -304,7 +363,7 @@ export function buildAttentionByWorktree(
             worktreeLastActivityAt: worktree.lastActivityAt
           })
         }
-      } else if (hookPaneIds.size === 0) {
+      } else if (hookLeafIds.size === 0) {
         // Why: tabs we have not mounted yet (restored-but-unvisited) only
         // expose the legacy tab title. Fall back to it only when no pane-level
         // titles or hook entries exist for this tab.
diff --git a/src/renderer/src/components/sidebar/smart-sort.test.ts b/src/renderer/src/components/sidebar/smart-sort.test.ts
index 6c4f9a0144b..a05536101ff 100644
--- a/src/renderer/src/components/sidebar/smart-sort.test.ts
+++ b/src/renderer/src/components/sidebar/smart-sort.test.ts
@@ -13,8 +13,15 @@ import {
   type AgentStateHistoryEntry,
   type AgentStatusEntry
 } from '../../../../shared/agent-status-types'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
 
 const NOW = new Date('2026-03-27T12:00:00.000Z').getTime()
+const LEAF_ID_1 = '11111111-1111-4111-8111-111111111111'
+const LEAF_ID_2 = '22222222-2222-4222-8222-222222222222'
+
+function paneKey(tabId: string, leaf: '1' | '2' = '1'): string {
+  return makePaneKey(tabId, leaf === '1' ? LEAF_ID_1 : LEAF_ID_2)
+}
 
 const repoMap = new Map<string, Repo>([
   [
@@ -126,15 +133,15 @@ describe('smart sort — class invariants', () => {
       [done.id]: [makeTab({ id: 'tab-done', worktreeId: done.id })]
     }
     const entries = {
-      'tab-blocked:1': makeEntry({
-        paneKey: 'tab-blocked:1',
+      [paneKey('tab-blocked', '1')]: makeEntry({
+        paneKey: paneKey('tab-blocked', '1'),
         state: 'blocked',
         // older than the done timestamp
         stateStartedAt: NOW - 5 * 60_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-done:1': makeEntry({
-        paneKey: 'tab-done:1',
+      [paneKey('tab-done', '1')]: makeEntry({
+        paneKey: paneKey('tab-done', '1'),
         state: 'done',
         // newer
         stateStartedAt: NOW - 10_000,
@@ -153,14 +160,14 @@ describe('smart sort — class invariants', () => {
       [working.id]: [makeTab({ id: 'tab-working', worktreeId: working.id })]
     }
     const entries = {
-      'tab-done:1': makeEntry({
-        paneKey: 'tab-done:1',
+      [paneKey('tab-done', '1')]: makeEntry({
+        paneKey: paneKey('tab-done', '1'),
         state: 'done',
         stateStartedAt: NOW - 10 * 60_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-working:1': makeEntry({
-        paneKey: 'tab-working:1',
+      [paneKey('tab-working', '1')]: makeEntry({
+        paneKey: paneKey('tab-working', '1'),
         state: 'working',
         // newer than the done — must still lose because class wins
         stateStartedAt: NOW - 1_000,
@@ -185,8 +192,8 @@ describe('smart sort — class invariants', () => {
       [idle.id]: [makeTab({ id: 'tab-idle', worktreeId: idle.id })]
     }
     const entries = {
-      'tab-working:1': makeEntry({
-        paneKey: 'tab-working:1',
+      [paneKey('tab-working', '1')]: makeEntry({
+        paneKey: paneKey('tab-working', '1'),
         state: 'working',
         stateStartedAt: NOW - 60_000,
         updatedAt: NOW - 1_000
@@ -206,14 +213,14 @@ describe('smart sort — within-class recency', () => {
       [newer.id]: [makeTab({ id: 'tab-newer', worktreeId: newer.id })]
     }
     const entries = {
-      'tab-older:1': makeEntry({
-        paneKey: 'tab-older:1',
+      [paneKey('tab-older', '1')]: makeEntry({
+        paneKey: paneKey('tab-older', '1'),
         state: 'blocked',
         stateStartedAt: NOW - 5 * 60_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-newer:1': makeEntry({
-        paneKey: 'tab-newer:1',
+      [paneKey('tab-newer', '1')]: makeEntry({
+        paneKey: paneKey('tab-newer', '1'),
         state: 'blocked',
         stateStartedAt: NOW - 30_000,
         updatedAt: NOW - 1_000
@@ -231,16 +238,16 @@ describe('smart sort — within-class recency', () => {
       [fresh.id]: [makeTab({ id: 'tab-fresh', worktreeId: fresh.id })]
     }
     const entries = {
-      'tab-with:1': makeEntry({
-        paneKey: 'tab-with:1',
+      [paneKey('tab-with', '1')]: makeEntry({
+        paneKey: paneKey('tab-with', '1'),
         state: 'working',
         stateStartedAt: NOW - 60_000,
         updatedAt: NOW - 1_000,
         // Prior done from earlier in the session bumps within-class recency.
         stateHistory: [makeHistory('done', NOW - 5_000)]
       }),
-      'tab-fresh:1': makeEntry({
-        paneKey: 'tab-fresh:1',
+      [paneKey('tab-fresh', '1')]: makeEntry({
+        paneKey: paneKey('tab-fresh', '1'),
         state: 'working',
         // Even newer current stateStartedAt — but with no history, falls back
         // to this timestamp (older than the prior done above).
@@ -263,15 +270,15 @@ describe('smart sort — within-class recency', () => {
       [fresh.id]: [makeTab({ id: 'tab-f', worktreeId: fresh.id })]
     }
     const entries = {
-      'tab-i:1': makeEntry({
-        paneKey: 'tab-i:1',
+      [paneKey('tab-i', '1')]: makeEntry({
+        paneKey: paneKey('tab-i', '1'),
         state: 'working',
         stateStartedAt: NOW - 60_000,
         updatedAt: NOW - 1_000,
         stateHistory: [makeHistory('done', NOW - 5_000, true)]
       }),
-      'tab-f:1': makeEntry({
-        paneKey: 'tab-f:1',
+      [paneKey('tab-f', '1')]: makeEntry({
+        paneKey: paneKey('tab-f', '1'),
         state: 'working',
         stateStartedAt: NOW - 30_000,
         updatedAt: NOW - 1_000
@@ -297,15 +304,15 @@ describe('smart sort — interrupted and stale handling', () => {
       [realDone.id]: [makeTab({ id: 'tab-d', worktreeId: realDone.id })]
     }
     const entries = {
-      'tab-i:1': makeEntry({
-        paneKey: 'tab-i:1',
+      [paneKey('tab-i', '1')]: makeEntry({
+        paneKey: paneKey('tab-i', '1'),
         state: 'done',
         interrupted: true,
         stateStartedAt: NOW - 1_000,
         updatedAt: NOW - 500
       }),
-      'tab-d:1': makeEntry({
-        paneKey: 'tab-d:1',
+      [paneKey('tab-d', '1')]: makeEntry({
+        paneKey: paneKey('tab-d', '1'),
         state: 'done',
         stateStartedAt: NOW - 5 * 60_000,
         updatedAt: NOW - 1_000
@@ -327,14 +334,14 @@ describe('smart sort — interrupted and stale handling', () => {
       [fresh.id]: [makeTab({ id: 'tab-f', worktreeId: fresh.id })]
     }
     const entries = {
-      'tab-s:1': makeEntry({
-        paneKey: 'tab-s:1',
+      [paneKey('tab-s', '1')]: makeEntry({
+        paneKey: paneKey('tab-s', '1'),
         state: 'blocked',
         stateStartedAt: NOW - AGENT_STATUS_STALE_AFTER_MS - 60_000,
         updatedAt: NOW - AGENT_STATUS_STALE_AFTER_MS - 60_000
       }),
-      'tab-f:1': makeEntry({
-        paneKey: 'tab-f:1',
+      [paneKey('tab-f', '1')]: makeEntry({
+        paneKey: paneKey('tab-f', '1'),
         state: 'done',
         stateStartedAt: NOW - 5 * 60_000,
         updatedAt: NOW - 1_000
@@ -417,20 +424,20 @@ describe('smart sort — multi-pane resolution', () => {
       [otherDone.id]: [makeTab({ id: 'tab-other', worktreeId: otherDone.id })]
     }
     const entries = {
-      'tab-split:1': makeEntry({
-        paneKey: 'tab-split:1',
+      [paneKey('tab-split', '1')]: makeEntry({
+        paneKey: paneKey('tab-split', '1'),
         state: 'working',
         stateStartedAt: NOW - 60_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-split:2': makeEntry({
-        paneKey: 'tab-split:2',
+      [paneKey('tab-split', '2')]: makeEntry({
+        paneKey: paneKey('tab-split', '2'),
         state: 'blocked',
         stateStartedAt: NOW - 30_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-other:1': makeEntry({
-        paneKey: 'tab-other:1',
+      [paneKey('tab-other', '1')]: makeEntry({
+        paneKey: paneKey('tab-other', '1'),
         state: 'done',
         stateStartedAt: NOW - 5_000,
         updatedAt: NOW - 1_000
@@ -473,14 +480,14 @@ describe('sortWorktreesSmart — cold start fallback', () => {
       [done.id]: [makeTab({ id: 'tab-done', worktreeId: done.id })]
     }
     const entries = {
-      'tab-blocked:1': makeEntry({
-        paneKey: 'tab-blocked:1',
+      [paneKey('tab-blocked', '1')]: makeEntry({
+        paneKey: paneKey('tab-blocked', '1'),
         state: 'blocked',
         stateStartedAt: NOW - 60_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-done:1': makeEntry({
-        paneKey: 'tab-done:1',
+      [paneKey('tab-done', '1')]: makeEntry({
+        paneKey: paneKey('tab-done', '1'),
         state: 'done',
         stateStartedAt: NOW - 30_000,
         updatedAt: NOW - 1_000
@@ -511,14 +518,14 @@ describe('sortWorktreesSmart — palette caller regression', () => {
       [working.id]: [makeTab({ id: 'tab-working', worktreeId: working.id })]
     }
     const agentStatusByPaneKey: Record<string, AgentStatusEntry> = {
-      'tab-blocked:1': makeEntry({
-        paneKey: 'tab-blocked:1',
+      [paneKey('tab-blocked', '1')]: makeEntry({
+        paneKey: paneKey('tab-blocked', '1'),
         state: 'blocked',
         stateStartedAt: NOW - 60_000,
         updatedAt: NOW - 1_000
       }),
-      'tab-working:1': makeEntry({
-        paneKey: 'tab-working:1',
+      [paneKey('tab-working', '1')]: makeEntry({
+        paneKey: paneKey('tab-working', '1'),
         state: 'working',
         // newer than the blocked one — would win on recency alone
         stateStartedAt: NOW - 1_000,
diff --git a/src/renderer/src/components/sidebar/smart-sort.ts b/src/renderer/src/components/sidebar/smart-sort.ts
index 3d539c2f3b9..96872ba9ff3 100644
--- a/src/renderer/src/components/sidebar/smart-sort.ts
+++ b/src/renderer/src/components/sidebar/smart-sort.ts
@@ -1,5 +1,8 @@
-import type { Worktree, Repo, TerminalTab } from '../../../../shared/types'
-import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
+import type { Worktree, Repo, TerminalLayoutSnapshot, TerminalTab } from '../../../../shared/types'
+import type {
+  AgentStatusEntry,
+  MigrationUnsupportedPtyEntry
+} from '../../../../shared/agent-status-types'
 import { tabHasLivePty } from '@/lib/tab-has-live-pty'
 import { IDLE, buildAttentionByWorktree, type WorktreeAttention } from './smart-attention'
 
@@ -121,7 +124,9 @@ export function sortWorktreesSmart(
   repoMap: Map<string, Repo>,
   agentStatusByPaneKey: Record<string, AgentStatusEntry>,
   runtimePaneTitlesByTabId: Record<string, Record<number, string>>,
-  ptyIdsByTabId: Record<string, string[]>
+  ptyIdsByTabId: Record<string, string[]>,
+  migrationUnsupportedByPtyId?: Record<string, MigrationUnsupportedPtyEntry>,
+  terminalLayoutsByTabId?: Record<string, TerminalLayoutSnapshot>
 ): Worktree[] {
   // Why: `tabHasLivePty` (over `ptyIdsByTabId`) is the source of truth for
   // liveness — slept terminals retain `tab.ptyId` as a wake hint, so reading
@@ -145,7 +150,9 @@ export function sortWorktreesSmart(
     agentStatusByPaneKey,
     runtimePaneTitlesByTabId,
     ptyIdsByTabId,
-    now
+    now,
+    migrationUnsupportedByPtyId,
+    terminalLayoutsByTabId
   )
 
   return [...worktrees].sort(buildWorktreeComparator('smart', repoMap, now, attentionByWorktree))
diff --git a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
index 47e5c0ec84f..af547f8e886 100644
--- a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
@@ -2,8 +2,10 @@ import { useMemo } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import { useAppStore } from '@/store'
 import { isExplicitAgentStatusFresh } from '@/lib/agent-status'
+import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
 import { resolveWorktreeStatus, type WorktreeStatus } from '@/lib/worktree-status'
 import { AGENT_STATUS_STALE_AFTER_MS } from '../../../../shared/agent-status-types'
+import { parsePaneKey } from '../../../../shared/stable-pane-id'
 import { EMPTY_BROWSER_TABS, EMPTY_TABS } from './WorktreeCardHelpers'
 import {
   selectLivePtyIdsForWorktree,
@@ -31,12 +33,8 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
         const tabIds = new Set(wtTabs.map((tab) => tab.id))
         const now = Date.now()
         for (const [paneKey, entry] of Object.entries(s.agentStatusByPaneKey)) {
-          const sepIdx = paneKey.indexOf(':')
-          if (sepIdx <= 0) {
-            continue
-          }
-          const tabId = paneKey.slice(0, sepIdx)
-          if (!tabIds.has(tabId)) {
+          const parsed = parsePaneKey(paneKey)
+          if (!parsed || !tabIds.has(parsed.tabId)) {
             continue
           }
           if (!isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS)) {
@@ -48,6 +46,16 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
             live = true
           }
         }
+        for (const unsupported of Object.values(s.migrationUnsupportedByPtyId)) {
+          const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
+          if (!entry) {
+            continue
+          }
+          const parsed = parsePaneKey(entry.paneKey)
+          if (parsed && tabIds.has(parsed.tabId)) {
+            perm = true
+          }
+        }
       }
 
       let retained = false
diff --git a/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts b/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts
index 1b010a43db2..986e96d1f1d 100644
--- a/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts
+++ b/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts
@@ -6,6 +6,11 @@ import {
 import type { TerminalTab } from '../../../../shared/types'
 import type { RetainedAgentEntry } from '@/store/slices/agent-status'
 import { buildWorktreeAgentRows } from './useWorktreeAgentRows'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
+
+const ORPHAN_PANE_KEY = makePaneKey('tab-orphan', '11111111-1111-4111-8111-111111111111')
+const PANE_KEY_1 = makePaneKey('tab-1', '22222222-2222-4222-8222-222222222222')
+const PANE_KEY_2 = makePaneKey('tab-2', '33333333-3333-4333-8333-333333333333')
 
 function makeTab(id: string): TerminalTab {
   return {
@@ -57,20 +62,20 @@ describe('buildWorktreeAgentRows', () => {
       // Why: useWorktreeAgentRows filters retained snapshots by worktreeId, not
       // current tab membership. This is the sidebar behavior that sleep cleanup
       // must counter by dropping worktree-scoped retained rows.
-      retained: [makeRetained('tab-orphan:0', 'wt-1', 1000)],
+      retained: [makeRetained(ORPHAN_PANE_KEY, 'wt-1', 1000)],
       now: 2000
     })
 
-    expect(rows.map((row) => row.paneKey)).toEqual(['tab-orphan:0'])
+    expect(rows.map((row) => row.paneKey)).toEqual([ORPHAN_PANE_KEY])
     expect(rows[0].state).toBe('done')
   })
 
   it('prefers a live row over a retained snapshot with the same paneKey', () => {
-    const liveEntry = makeEntry('tab-1:0', 2000)
+    const liveEntry = makeEntry(PANE_KEY_1, 2000)
     const rows = buildWorktreeAgentRows({
       tabs: [makeTab('tab-1')],
       entries: [liveEntry],
-      retained: [makeRetained('tab-1:0', 'wt-1', 1000)],
+      retained: [makeRetained(PANE_KEY_1, 'wt-1', 1000)],
       now: 3000
     })
 
@@ -90,15 +95,15 @@ describe('buildWorktreeAgentRows', () => {
     const rows = buildWorktreeAgentRows({
       tabs: [makeTab('tab-1'), makeTab('tab-2')],
       entries: [
-        makeEntry('tab-1:0', staleAt, { state: 'working', updatedAt: staleAt }),
-        makeEntry('tab-2:0', freshDoneAt, { state: 'done', updatedAt: freshDoneAt })
+        makeEntry(PANE_KEY_1, staleAt, { state: 'working', updatedAt: staleAt }),
+        makeEntry(PANE_KEY_2, freshDoneAt, { state: 'done', updatedAt: freshDoneAt })
       ],
       retained: [],
       now
     })
 
-    const working = rows.find((r) => r.paneKey === 'tab-1:0')
-    const done = rows.find((r) => r.paneKey === 'tab-2:0')
+    const working = rows.find((r) => r.paneKey === PANE_KEY_1)
+    const done = rows.find((r) => r.paneKey === PANE_KEY_2)
     expect(working?.state).toBe('idle')
     expect(done?.state).toBe('done')
   })
diff --git a/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts b/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
index c0330715a01..20d13af57db 100644
--- a/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
+++ b/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
@@ -9,6 +9,8 @@ import {
   AGENT_STATUS_STALE_AFTER_MS,
   type AgentStatusEntry
 } from '../../../../shared/agent-status-types'
+import { parsePaneKey } from '../../../../shared/stable-pane-id'
+import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
 
 // Why: stable empty-array references so narrow selectors return the same
 // reference when there's nothing for this worktree. Without stable empties,
@@ -29,16 +31,15 @@ export function buildWorktreeAgentRows(args: {
 
   const entriesByTabId = new Map<string, AgentStatusEntry[]>()
   for (const entry of args.entries) {
-    const colonIndex = entry.paneKey.indexOf(':')
-    if (colonIndex === -1) {
+    const parsed = parsePaneKey(entry.paneKey)
+    if (!parsed) {
       continue
     }
-    const tabId = entry.paneKey.slice(0, colonIndex)
-    const bucket = entriesByTabId.get(tabId)
+    const bucket = entriesByTabId.get(parsed.tabId)
     if (bucket) {
       bucket.push(entry)
     } else {
-      entriesByTabId.set(tabId, [entry])
+      entriesByTabId.set(parsed.tabId, [entry])
     }
   }
 
@@ -105,12 +106,22 @@ export function useWorktreeAgentRows(worktreeId: string): DashboardAgentRow[] {
       const tabIds = new Set(wtTabs.map((t) => t.id))
       const out: AgentStatusEntry[] = []
       for (const [paneKey, entry] of Object.entries(s.agentStatusByPaneKey)) {
-        const sepIdx = paneKey.indexOf(':')
-        if (sepIdx <= 0) {
+        const parsed = parsePaneKey(paneKey)
+        if (!parsed) {
           continue
         }
-        const tabId = paneKey.slice(0, sepIdx)
-        if (!tabIds.has(tabId)) {
+        if (!tabIds.has(parsed.tabId)) {
+          continue
+        }
+        out.push(entry)
+      }
+      for (const unsupported of Object.values(s.migrationUnsupportedByPtyId)) {
+        const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
+        if (!entry) {
+          continue
+        }
+        const parsed = parsePaneKey(entry.paneKey)
+        if (!parsed || !tabIds.has(parsed.tabId)) {
           continue
         }
         out.push(entry)
diff --git a/src/renderer/src/components/sidebar/visible-worktrees.ts b/src/renderer/src/components/sidebar/visible-worktrees.ts
index 2f6a632b834..d901b2c35d1 100644
--- a/src/renderer/src/components/sidebar/visible-worktrees.ts
+++ b/src/renderer/src/components/sidebar/visible-worktrees.ts
@@ -186,7 +186,9 @@ export function getVisibleWorktreeIds(): string[] {
       repoMap,
       state.agentStatusByPaneKey,
       state.runtimePaneTitlesByTabId,
-      state.ptyIdsByTabId
+      state.ptyIdsByTabId,
+      state.migrationUnsupportedByPtyId,
+      state.terminalLayoutsByTabId
     ).map((w) => w.id)
   } else {
     // Why empty map: non-smart branches don't read attentionByWorktree, but
diff --git a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
index bf6ae9c7993..213a0de60d9 100644
--- a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
@@ -38,6 +38,7 @@ import { runSleepWorktree } from '../sidebar/sleep-worktree-flow'
 import { useDaemonActions, DaemonActionDialog } from '../shared/useDaemonActions'
 import type { AppMemory, UsageValues, Worktree } from '../../../../shared/types'
 import { ORPHAN_WORKTREE_ID } from '../../../../shared/constants'
+import { parsePaneKey } from '../../../../shared/stable-pane-id'
 import {
   mergeSnapshotAndSessions,
   UNATTRIBUTED_REPO_ID,
@@ -908,17 +909,10 @@ export function ResourceUsageStatusSegment({
         }
       }
       setActiveView('terminal')
-      // Why: snapshot-derived rows carry a `${tabId}:${paneId}` paneKey from
-      // the main-process pty registry — parse the paneId tail so split-tab
-      // clicks land focus on the *clicked* pane rather than whichever pane
-      // was last active. Daemon-only rows have paneKey=null and degrade to
-      // tab-only activation.
-      const colon = paneKey ? paneKey.indexOf(':') : -1
-      const tail = colon > 0 && paneKey ? paneKey.slice(colon + 1) : ''
-      const parsed = /^\d+$/.test(tail) ? Number.parseInt(tail, 10) : NaN
-      const paneId =
-        Number.isFinite(parsed) && parsed > 0 && paneKey?.slice(0, colon) === tabId ? parsed : null
-      activateTabAndFocusPane(tabId, paneId)
+      // Why: paneKey suffixes are stable UUID leaf ids after replay/reload.
+      // Legacy numeric keys degrade to tab-only activation instead of guessing.
+      const parsed = paneKey ? parsePaneKey(paneKey) : null
+      activateTabAndFocusPane(tabId, parsed?.tabId === tabId ? parsed.leafId : null)
     },
     [tabsByWorktree, setActiveView]
   )
diff --git a/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
index 8bf4c3e9e93..bccc250fe81 100644
--- a/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
+++ b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
@@ -28,8 +28,9 @@ import type {
   TerminalTab,
   WorktreeMemory
 } from '../../../../shared/types'
-import { getRepoIdFromWorktreeId, splitWorktreeId } from '../../../../shared/worktree-id'
 import { parsePtySessionId } from '../../../../shared/pty-session-id-format'
+import { parsePaneKey as parseStablePaneKey } from '../../../../shared/stable-pane-id'
+import { getRepoIdFromWorktreeId, splitWorktreeId } from '../../../../shared/worktree-id'
 
 // ─── View-model types (renderer-local) ──────────────────────────────
 
@@ -131,19 +132,12 @@ function shortCwd(cwd: string): string {
   return parts.length > 2 ? parts.slice(-2).join(sep) : cwd
 }
 
-function parsePaneKey(paneKey: string | null): { tabId: string; paneRuntimeId: number } | null {
+function parsePaneKey(paneKey: string | null): { tabId: string; leafId: string } | null {
   if (!paneKey) {
     return null
   }
-  const sepIdx = paneKey.indexOf(':')
-  if (sepIdx <= 0) {
-    return null
-  }
-  const paneRuntimeId = Number(paneKey.slice(sepIdx + 1))
-  if (!Number.isFinite(paneRuntimeId)) {
-    return null
-  }
-  return { tabId: paneKey.slice(0, sepIdx), paneRuntimeId }
+  const parsed = parseStablePaneKey(paneKey)
+  return parsed ? { tabId: parsed.tabId, leafId: parsed.leafId } : null
 }
 
 function resolveSnapshotSessionLabel(
@@ -161,10 +155,6 @@ function resolveSnapshotSessionLabel(
       if (custom) {
         return custom
       }
-      const runtime = ctx.runtimePaneTitlesByTabId[parsed.tabId]?.[parsed.paneRuntimeId]?.trim()
-      if (runtime) {
-        return runtime
-      }
       return tab.defaultTitle?.trim() || tab.title?.trim() || `Terminal ${tabIndex + 1}`
     }
   }
diff --git a/src/renderer/src/components/terminal-pane/TerminalPane.tsx b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
index 0dd84c77629..f891f762d67 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
@@ -15,7 +15,8 @@ import type { PtyTransport } from './pty-transport'
 import { fitPanes, isWindowsUserAgent, shellEscapePath } from './pane-helpers'
 import { getConnectionId } from '@/lib/connection-context'
 import { resolveTerminalDropTargetShell } from './terminal-drop-handler'
-import { EMPTY_LAYOUT, paneLeafId, serializeTerminalLayout } from './layout-serialization'
+import { EMPTY_LAYOUT, serializeTerminalLayout } from './layout-serialization'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
 import {
   applyExpandedLayoutTo,
   createExpandCollapseActions,
@@ -38,6 +39,7 @@ import { connectPanePty } from './pty-connection'
 import { shouldPreserveTerminalScrollbackBuffers } from '../../../../shared/workspace-session-terminal-buffers'
 import { getFitOverrideForPty, onOverrideChange } from '@/lib/pane-manager/mobile-fit-overrides'
 import { getDriverForPty, onDriverChange } from '@/lib/pane-manager/mobile-driver-state'
+import { resolvePaneKeyForManager } from '@/lib/pane-manager/pane-key-resolution'
 import { safeFit } from '@/lib/pane-manager/pane-tree-ops'
 import { captureTerminalShutdownLayout } from './terminal-shutdown-layout-capture'
 import { inspectRuntimeTerminalProcess } from '@/runtime/runtime-terminal-inspection'
@@ -64,7 +66,7 @@ type TerminalPaneProps = {
   // override (separate snapshot ref) — does NOT touch expandedPaneId state
   // or persist to the layout snapshot, so returning to the workspace shows
   // the original split layout unchanged.
-  isolatedPaneId?: number | null
+  isolatedPaneKey?: string | null
   onPtyExit: (ptyId: string) => void
   onCloseTab: () => void
 }
@@ -75,7 +77,7 @@ export default function TerminalPane({
   cwd,
   isActive,
   isVisible = true,
-  isolatedPaneId = null,
+  isolatedPaneKey = null,
   onPtyExit,
   onCloseTab
 }: TerminalPaneProps): React.JSX.Element {
@@ -319,10 +321,16 @@ export default function TerminalPane({
       return
     }
     const activePaneId = manager.getActivePane()?.id ?? manager.getPanes()[0]?.id ?? null
-    const layout = serializeTerminalLayout(container, activePaneId, expandedPaneIdRef.current)
+    const leafIdByPaneId = manager.getLeafIdMap()
+    const layout = serializeTerminalLayout(
+      container,
+      activePaneId,
+      expandedPaneIdRef.current,
+      leafIdByPaneId
+    )
     const existing = useAppStore.getState().terminalLayoutsByTabId[tabId]
     const currentPanes = manager.getPanes()
-    const currentLeafIds = new Set(currentPanes.map((p) => paneLeafId(p.id)))
+    const currentLeafIds = new Set(currentPanes.map((p) => p.leafId))
     // Preserve existing buffersByLeafId so layout-only persists (resize, split,
     // reorder) don't clobber previously captured scrollback. Drop entries for
     // leaves that no longer exist.
@@ -341,10 +349,11 @@ export default function TerminalPane({
     // successive remount (tab moved again before the first rAF) would lose
     // the mappings and force fresh PTY spawns.
     const livePtyEntries = currentPanes
-      .map(
-        (p) => [paneLeafId(p.id), paneTransportsRef.current.get(p.id)?.getPtyId() ?? null] as const
+      .map((p) => [p.leafId, paneTransportsRef.current.get(p.id)?.getPtyId() ?? null] as const)
+      .filter(
+        (entry): entry is readonly [(typeof currentPanes)[number]['leafId'], string] =>
+          entry[1] !== null
       )
-      .filter((entry): entry is readonly [string, string] => entry[1] !== null)
     const mergedPtyIds = mergeCapturedLeafState({
       prior: existing?.ptyIdsByLeafId,
       fresh: Object.fromEntries(livePtyEntries),
@@ -359,7 +368,7 @@ export default function TerminalPane({
     const titles = paneTitlesRef.current
     const titleEntries = currentPanes
       .filter((p) => titles[p.id])
-      .map((p) => [paneLeafId(p.id), titles[p.id]] as const)
+      .map((p) => [p.leafId, titles[p.id]] as const)
     if (titleEntries.length > 0) {
       layout.titlesByLeafId = Object.fromEntries(titleEntries)
     }
@@ -372,7 +381,10 @@ export default function TerminalPane({
       const { ptyIdsByLeafId: _existingPtyIdsByLeafId, ...layoutWithoutPtyBindings } =
         existingLayout
       const existingBindings = existingLayout.ptyIdsByLeafId ?? {}
-      const leafId = paneLeafId(paneId)
+      const leafId = managerRef.current?.getLeafId(paneId)
+      if (!leafId) {
+        return
+      }
 
       if (ptyId) {
         setTabLayout(tabId, {
@@ -429,13 +441,12 @@ export default function TerminalPane({
         // so the sidebar doesn't show a stale countdown for a pane that no
         // longer exists. The closeTab path handles bulk cleanup, but closing
         // a single split pane doesn't go through closeTab.
-        useAppStore.getState().setCacheTimerStartedAt(`${tabId}:${paneId}`, null)
+        const leafId = manager.getLeafId(paneId)
+        if (leafId) {
+          useAppStore.getState().setCacheTimerStartedAt(makePaneKey(tabId, leafId), null)
+          useAppStore.getState().dropAgentStatus(makePaneKey(tabId, leafId))
+        }
         syncPanePtyLayoutBinding(paneId, null)
-        // Why: Cmd+W on a split pane is user-initiated teardown — drop (not
-        // remove) so any retained `done` snapshot for this pane is also cleared
-        // and a same-frame live→gone transition cannot re-snapshot it via the
-        // retention sync.
-        useAppStore.getState().dropAgentStatus(`${tabId}:${paneId}`)
         manager.closePane(paneId)
       }
     },
@@ -559,20 +570,33 @@ export default function TerminalPane({
           safeFit(pane)
         }
       })
-    if (isolatedPaneId === null) {
+    if (isolatedPaneKey === null) {
       restoreExpandedLayoutFrom(snapshots)
       const frame = scheduleRefit()
       return () => {
         cancelAnimationFrame(frame)
       }
     }
-    const applied = applyExpandedLayoutTo(isolatedPaneId, {
-      managerRef,
-      containerRef,
-      expandedStyleSnapshotRef: activityIsolationSnapshotRef
-    })
+    const manager = managerRef.current
+    const resolution = resolvePaneKeyForManager(tabId, isolatedPaneKey, manager)
+    const resolvedPaneId = resolution.status === 'resolved' ? resolution.numericPaneId : null
+    const applied =
+      resolvedPaneId !== null &&
+      ((manager?.getPanes().length ?? 0) <= 1 ||
+        applyExpandedLayoutTo(resolvedPaneId, {
+          managerRef,
+          containerRef,
+          expandedStyleSnapshotRef: activityIsolationSnapshotRef
+        }))
     if (!applied) {
       restoreExpandedLayoutFrom(snapshots)
+      const root = containerRef.current?.firstElementChild
+      if (root instanceof HTMLElement) {
+        // Why: Activity requested an exact pane. If it cannot be resolved, fail
+        // closed instead of showing the whole split terminal as a fallback.
+        snapshots.set(root, { display: root.style.display, flex: root.style.flex })
+        root.style.display = 'none'
+      }
       const frame = scheduleRefit()
       return () => {
         cancelAnimationFrame(frame)
@@ -582,7 +606,7 @@ export default function TerminalPane({
     return () => {
       cancelAnimationFrame(frame)
     }
-  }, [isolatedPaneId, paneCount])
+  }, [isolatedPaneKey, paneCount, tabId])
 
   // Why: belt-and-suspenders unmount cleanup. If the component unmounts
   // while isolation is active (e.g. tab closed mid-Activity-view), restore
@@ -621,7 +645,7 @@ export default function TerminalPane({
       syncPanePtyLayoutBinding(paneId, null)
       transport?.destroy?.()
       paneTransportsRef.current.delete(paneId)
-      setCacheTimerStartedAt(`${tabId}:${paneId}`, null)
+      setCacheTimerStartedAt(makePaneKey(tabId, pane.leafId), null)
       setTerminalError(null)
 
       const newPaneBinding = connectPanePty(pane, manager, {
diff --git a/src/renderer/src/components/terminal-pane/TerminalPaneOverlayLayer.tsx b/src/renderer/src/components/terminal-pane/TerminalPaneOverlayLayer.tsx
index b734b8b7e18..cf615132616 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPaneOverlayLayer.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPaneOverlayLayer.tsx
@@ -91,7 +91,7 @@ const TerminalOverlaySlot = memo(function TerminalOverlaySlot({
       // TerminalPane mounted here preserves alt-screen TUI state while this
       // flag still lets hidden tabs throttle rendering.
       isVisible={isVisible || activityTerminalPortal !== null}
-      isolatedPaneId={activityTerminalPortal?.paneId ?? null}
+      isolatedPaneKey={activityTerminalPortal?.paneKey ?? null}
       onPtyExit={(ptyId) => {
         if (consumeSuppressedPtyExit(ptyId)) {
           return
@@ -205,11 +205,10 @@ const TerminalPaneOverlayLayer = memo(function TerminalPaneOverlayLayer({
         const assignment = assignments.get(terminalTab.id)
         const isVisible = Boolean(isWorktreeActive && assignment && assignment.isActiveInGroup)
         const isActive = Boolean(isVisible && assignment && assignment.groupId === activeGroupId)
-        const activityTerminalPortal = findActivityTerminalPortal(
-          activityTerminalPortals,
+        const activityTerminalPortal = findActivityTerminalPortal(activityTerminalPortals, {
           worktreeId,
-          terminalTab.id
-        )
+          tabId: terminalTab.id
+        })
         return (
           <TerminalOverlaySlot
             key={terminalTab.id}
diff --git a/src/renderer/src/components/terminal-pane/focus-terminal-pane-event.ts b/src/renderer/src/components/terminal-pane/focus-terminal-pane-event.ts
new file mode 100644
index 00000000000..a55c40c12d9
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/focus-terminal-pane-event.ts
@@ -0,0 +1,39 @@
+import type { FocusTerminalPaneDetail } from '@/constants/terminal'
+import type { PaneManager } from '@/lib/pane-manager/pane-manager'
+import { resolveLeafIdForManager } from '@/lib/pane-manager/pane-key-resolution'
+
+type FocusTerminalPaneEventDeps = {
+  tabId: string
+  manager: Pick<PaneManager, 'getNumericIdForLeaf' | 'getPanes' | 'setActivePane'> | null
+  acknowledgeAgents: (paneKeys: string[]) => void
+  surfaceStaleAgentRow: (tabId: string, leafId: string) => void
+}
+
+export function handleFocusTerminalPaneDetail(
+  detail: FocusTerminalPaneDetail | undefined,
+  { tabId, manager, acknowledgeAgents, surfaceStaleAgentRow }: FocusTerminalPaneEventDeps
+): void {
+  if (!detail?.tabId || detail.tabId !== tabId) {
+    return
+  }
+  if (!manager || !detail.leafId) {
+    return
+  }
+  const resolution = resolveLeafIdForManager(
+    tabId,
+    detail.leafId,
+    manager,
+    detail.ackPaneKeyOnSuccess ?? null
+  )
+  if (resolution.status !== 'resolved') {
+    // Why: stale pane keys must fail closed instead of focusing a sibling pane.
+    if (resolution.leafId) {
+      surfaceStaleAgentRow(tabId, resolution.leafId)
+    }
+    return
+  }
+  manager.setActivePane(resolution.numericPaneId, { focus: true })
+  if (detail.ackPaneKeyOnSuccess) {
+    acknowledgeAgents([detail.ackPaneKeyOnSuccess])
+  }
+}
diff --git a/src/renderer/src/components/terminal-pane/layout-serialization.test.ts b/src/renderer/src/components/terminal-pane/layout-serialization.test.ts
index f4fe088ad73..d533f81e04a 100644
--- a/src/renderer/src/components/terminal-pane/layout-serialization.test.ts
+++ b/src/renderer/src/components/terminal-pane/layout-serialization.test.ts
@@ -1,3 +1,5 @@
+/* oxlint-disable max-lines -- Why: this test keeps split layout replay fixtures together so
+ * stable leaf-id migration regressions are visible in one focused suite. */
 import { describe, expect, it, beforeAll } from 'vitest'
 import type { TerminalPaneLayoutNode } from '../../../../shared/types'
 
@@ -33,7 +35,6 @@ beforeAll(() => {
 })
 
 import {
-  paneLeafId,
   buildFontFamily,
   serializePaneTree,
   serializeTerminalLayout,
@@ -55,22 +56,10 @@ function mockElement(opts: {
   return new MockHTMLElement(opts) as unknown as HTMLElement
 }
 
-// ---------------------------------------------------------------------------
-// paneLeafId
-// ---------------------------------------------------------------------------
-describe('paneLeafId', () => {
-  it('returns "pane:0" for paneId 0', () => {
-    expect(paneLeafId(0)).toBe('pane:0')
-  })
-
-  it('returns "pane:1" for paneId 1', () => {
-    expect(paneLeafId(1)).toBe('pane:1')
-  })
-
-  it('returns "pane:42" for paneId 42', () => {
-    expect(paneLeafId(42)).toBe('pane:42')
-  })
-})
+const LEAF_1 = '11111111-1111-4111-8111-111111111111'
+const LEAF_2 = '22222222-2222-4222-8222-222222222222'
+const LEAF_3 = '33333333-3333-4333-8333-333333333333'
+const LEAF_4 = '44444444-4444-4444-8444-444444444444'
 
 // ---------------------------------------------------------------------------
 // buildFontFamily
@@ -132,36 +121,53 @@ describe('serializePaneTree', () => {
   })
 
   it('returns a leaf node for a single pane', () => {
-    const pane = mockElement({ classList: ['pane'], dataset: { paneId: '1' } })
-    expect(serializePaneTree(pane)).toEqual({ type: 'leaf', leafId: 'pane:1' })
+    const pane = mockElement({ classList: ['pane'], dataset: { paneId: '1', leafId: LEAF_1 } })
+    expect(serializePaneTree(pane)).toEqual({ type: 'leaf', leafId: LEAF_1 })
   })
 
-  it('returns null for a pane with non-numeric paneId', () => {
+  it('returns null for a pane without a UUID leaf id', () => {
     const pane = mockElement({ classList: ['pane'], dataset: { paneId: 'abc' } })
     expect(serializePaneTree(pane)).toBeNull()
   })
 
+  it('returns null for a pane with a legacy leaf id', () => {
+    const pane = mockElement({ classList: ['pane'], dataset: { paneId: '1', leafId: 'pane:1' } })
+    expect(serializePaneTree(pane)).toBeNull()
+  })
+
   it('returns null for element that is neither pane nor pane-split', () => {
     const el = mockElement({ classList: ['random-class'] })
     expect(serializePaneTree(el)).toBeNull()
   })
 
   it('returns a vertical split node with two pane children', () => {
-    const first = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: '1' } })
-    const second = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: '2' } })
+    const first = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '1', leafId: LEAF_1 }
+    })
+    const second = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '2', leafId: LEAF_2 }
+    })
     const split = mockElement({ classList: ['pane-split'], children: [first, second] })
 
     expect(serializePaneTree(split)).toEqual({
       type: 'split',
       direction: 'vertical',
-      first: { type: 'leaf', leafId: 'pane:1' },
-      second: { type: 'leaf', leafId: 'pane:2' }
+      first: { type: 'leaf', leafId: LEAF_1 },
+      second: { type: 'leaf', leafId: LEAF_2 }
     })
   })
 
   it('returns horizontal direction when split has is-horizontal class', () => {
-    const first = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: '3' } })
-    const second = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: '4' } })
+    const first = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '3', leafId: LEAF_3 }
+    })
+    const second = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '4', leafId: LEAF_4 }
+    })
     const split = mockElement({
       classList: ['pane-split', 'is-horizontal'],
       children: [first, second]
@@ -170,20 +176,20 @@ describe('serializePaneTree', () => {
     expect(serializePaneTree(split)).toEqual({
       type: 'split',
       direction: 'horizontal',
-      first: { type: 'leaf', leafId: 'pane:3' },
-      second: { type: 'leaf', leafId: 'pane:4' }
+      first: { type: 'leaf', leafId: LEAF_3 },
+      second: { type: 'leaf', leafId: LEAF_4 }
     })
   })
 
   it('captures flex ratio when children have unequal flex', () => {
     const first = new MockHTMLElement({
       classList: ['pane'],
-      dataset: { paneId: '1' },
+      dataset: { paneId: '1', leafId: LEAF_1 },
       style: { flex: '3' }
     })
     const second = new MockHTMLElement({
       classList: ['pane'],
-      dataset: { paneId: '2' },
+      dataset: { paneId: '2', leafId: LEAF_2 },
       style: { flex: '1' }
     })
     const split = mockElement({ classList: ['pane-split'], children: [first, second] })
@@ -192,8 +198,8 @@ describe('serializePaneTree', () => {
     expect(result).toEqual({
       type: 'split',
       direction: 'vertical',
-      first: { type: 'leaf', leafId: 'pane:1' },
-      second: { type: 'leaf', leafId: 'pane:2' },
+      first: { type: 'leaf', leafId: LEAF_1 },
+      second: { type: 'leaf', leafId: LEAF_2 },
       ratio: 0.75
     })
   })
@@ -201,12 +207,12 @@ describe('serializePaneTree', () => {
   it('omits ratio when flex values are equal (both 1)', () => {
     const first = new MockHTMLElement({
       classList: ['pane'],
-      dataset: { paneId: '1' },
+      dataset: { paneId: '1', leafId: LEAF_1 },
       style: { flex: '1' }
     })
     const second = new MockHTMLElement({
       classList: ['pane'],
-      dataset: { paneId: '2' },
+      dataset: { paneId: '2', leafId: LEAF_2 },
       style: { flex: '1' }
     })
     const split = mockElement({ classList: ['pane-split'], children: [first, second] })
@@ -216,9 +222,18 @@ describe('serializePaneTree', () => {
   })
 
   it('handles nested splits recursively', () => {
-    const leaf1 = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: '1' } })
-    const leaf2 = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: '2' } })
-    const leaf3 = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: '3' } })
+    const leaf1 = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '1', leafId: LEAF_1 }
+    })
+    const leaf2 = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '2', leafId: LEAF_2 }
+    })
+    const leaf3 = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '3', leafId: LEAF_3 }
+    })
 
     const innerSplit = new MockHTMLElement({
       classList: ['pane-split', 'is-horizontal'],
@@ -232,12 +247,12 @@ describe('serializePaneTree', () => {
     expect(serializePaneTree(outerSplit)).toEqual({
       type: 'split',
       direction: 'vertical',
-      first: { type: 'leaf', leafId: 'pane:1' },
+      first: { type: 'leaf', leafId: LEAF_1 },
       second: {
         type: 'split',
         direction: 'horizontal',
-        first: { type: 'leaf', leafId: 'pane:2' },
-        second: { type: 'leaf', leafId: 'pane:3' }
+        first: { type: 'leaf', leafId: LEAF_2 },
+        second: { type: 'leaf', leafId: LEAF_3 }
       }
     })
   })
@@ -257,7 +272,51 @@ describe('serializeTerminalLayout', () => {
     const result = serializeTerminalLayout(root, 5, null)
     expect(result).toEqual({
       root: null,
-      activeLeafId: 'pane:5',
+      activeLeafId: null,
+      expandedLeafId: null
+    })
+  })
+
+  it('uses UUID leaf ids from the live pane map for active and expanded panes', () => {
+    const child = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '5', leafId: LEAF_1 }
+    })
+    const root = mockElement({ firstElementChild: child }) as unknown as HTMLDivElement
+    const result = serializeTerminalLayout(
+      root,
+      5,
+      6,
+      new Map([
+        [5, LEAF_1],
+        [6, LEAF_2]
+      ])
+    )
+    expect(result).toEqual({
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: LEAF_1,
+      expandedLeafId: LEAF_2
+    })
+  })
+
+  it('does not serialize legacy active pane ids when the live map is missing UUIDs', () => {
+    const child = new MockHTMLElement({
+      classList: ['pane'],
+      dataset: { paneId: '5', leafId: LEAF_1 }
+    })
+    const root = mockElement({ firstElementChild: child }) as unknown as HTMLDivElement
+    const result = serializeTerminalLayout(
+      root,
+      5,
+      6,
+      new Map([
+        [5, 'pane:5'],
+        [6, 'pane:6']
+      ])
+    )
+    expect(result).toEqual({
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: null,
       expandedLeafId: null
     })
   })
diff --git a/src/renderer/src/components/terminal-pane/layout-serialization.ts b/src/renderer/src/components/terminal-pane/layout-serialization.ts
index 6127da76526..7441256fa24 100644
--- a/src/renderer/src/components/terminal-pane/layout-serialization.ts
+++ b/src/renderer/src/components/terminal-pane/layout-serialization.ts
@@ -3,8 +3,16 @@ import type {
   TerminalPaneLayoutNode,
   TerminalPaneSplitDirection
 } from '../../../../shared/types'
+import { isTerminalLeafId } from '../../../../shared/stable-pane-id'
 import type { PaneManager } from '@/lib/pane-manager/pane-manager'
 import { replayIntoTerminal, type ReplayingPanesRef } from './replay-guard'
+import { getLeftmostLeafId, normalizeTerminalLayoutSnapshot } from './terminal-layout-leaf-ids'
+
+export {
+  collectLeafIdsInOrder,
+  collectLeafIdsInReplayCreationOrder,
+  normalizeTerminalLayoutSnapshot
+} from './terminal-layout-leaf-ids'
 
 export const EMPTY_LAYOUT: TerminalLayoutSnapshot = {
   root: null,
@@ -49,54 +57,6 @@ export const POST_REPLAY_MODE_RESET =
 //          as unbound key input).
 export const POST_REPLAY_FOCUS_REPORTING_RESET = '\x1b[?25h\x1b[?1004l'
 
-export function paneLeafId(paneId: number): string {
-  return `pane:${paneId}`
-}
-
-export function collectLeafIdsInOrder(node: TerminalPaneLayoutNode | null | undefined): string[] {
-  if (!node) {
-    return []
-  }
-  if (node.type === 'leaf') {
-    return [node.leafId]
-  }
-  return [...collectLeafIdsInOrder(node.first), ...collectLeafIdsInOrder(node.second)]
-}
-
-function getLeftmostLeafId(node: TerminalPaneLayoutNode): string {
-  return node.type === 'leaf' ? node.leafId : getLeftmostLeafId(node.first)
-}
-
-function collectReplayCreatedPaneLeafIds(
-  node: Extract<TerminalPaneLayoutNode, { type: 'split' }>,
-  leafIdsInReplayCreationOrder: string[]
-): void {
-  // Why: replayTerminalLayout() creates one new pane per split and assigns it
-  // to the split's second subtree before recursing, so the new pane maps to
-  // the leftmost leaf reachable within that second subtree.
-  leafIdsInReplayCreationOrder.push(getLeftmostLeafId(node.second))
-
-  if (node.first.type === 'split') {
-    collectReplayCreatedPaneLeafIds(node.first, leafIdsInReplayCreationOrder)
-  }
-  if (node.second.type === 'split') {
-    collectReplayCreatedPaneLeafIds(node.second, leafIdsInReplayCreationOrder)
-  }
-}
-
-export function collectLeafIdsInReplayCreationOrder(
-  node: TerminalPaneLayoutNode | null | undefined
-): string[] {
-  if (!node) {
-    return []
-  }
-  const leafIdsInReplayCreationOrder = [getLeftmostLeafId(node)]
-  if (node.type === 'split') {
-    collectReplayCreatedPaneLeafIds(node, leafIdsInReplayCreationOrder)
-  }
-  return leafIdsInReplayCreationOrder
-}
-
 // Cross-platform monospace fallback chain ensures the terminal always has a
 // usable font regardless of OS.  macOS-only fonts like SF Mono and Menlo are
 // harmless on other platforms (the browser skips them), while Cascadia Mono /
@@ -156,11 +116,11 @@ export function serializePaneTree(node: HTMLElement | null): TerminalPaneLayoutN
   }
 
   if (node.classList.contains('pane')) {
-    const paneId = Number(node.dataset.paneId ?? '')
-    if (!Number.isFinite(paneId)) {
+    const leafId = node.dataset.leafId
+    if (!leafId || !isTerminalLeafId(leafId)) {
       return null
     }
-    return { type: 'leaf', leafId: paneLeafId(paneId) }
+    return { type: 'leaf', leafId }
   }
 
   if (!node.classList.contains('pane-split')) {
@@ -201,31 +161,21 @@ export function serializePaneTree(node: HTMLElement | null): TerminalPaneLayoutN
 export function serializeTerminalLayout(
   root: HTMLDivElement | null,
   activePaneId: number | null,
-  expandedPaneId: number | null
+  expandedPaneId: number | null,
+  leafIdByPaneId?: ReadonlyMap<number, string>
 ): TerminalLayoutSnapshot {
   const rootNode = serializePaneTree(
     root?.firstElementChild instanceof HTMLElement ? root.firstElementChild : null
   )
+  const activeLeafId = activePaneId === null ? null : leafIdByPaneId?.get(activePaneId)
+  const expandedLeafId = expandedPaneId === null ? null : leafIdByPaneId?.get(expandedPaneId)
   return {
     root: rootNode,
-    activeLeafId: activePaneId === null ? null : paneLeafId(activePaneId),
-    expandedLeafId: expandedPaneId === null ? null : paneLeafId(expandedPaneId)
+    activeLeafId: activeLeafId && isTerminalLeafId(activeLeafId) ? activeLeafId : null,
+    expandedLeafId: expandedLeafId && isTerminalLeafId(expandedLeafId) ? expandedLeafId : null
   }
 }
 
-function collectLeafIds(
-  node: TerminalPaneLayoutNode,
-  paneByLeafId: Map<string, number>,
-  paneId: number
-): void {
-  if (node.type === 'leaf') {
-    paneByLeafId.set(node.leafId, paneId)
-    return
-  }
-  collectLeafIds(node.first, paneByLeafId, paneId)
-  collectLeafIds(node.second, paneByLeafId, paneId)
-}
-
 /**
  * Write saved scrollback buffers into the restored panes so the user sees
  * their previous terminal output after an app restart.  If a buffer was
@@ -289,9 +239,12 @@ export function replayTerminalLayout(
 ): Map<string, number> {
   const paneByLeafId = new Map<string, number>()
 
-  const initialPane = manager.createInitialPane({ focus: focusInitialPane })
+  const normalized = normalizeTerminalLayoutSnapshot(snapshot)
+  snapshot = normalized.snapshot
+  const initialLeafId = snapshot.root ? getLeftmostLeafId(snapshot.root) : undefined
+  const initialPane = manager.createInitialPane({ focus: focusInitialPane, leafId: initialLeafId })
   if (!snapshot?.root) {
-    paneByLeafId.set(paneLeafId(initialPane.id), initialPane.id)
+    paneByLeafId.set(initialPane.leafId, initialPane.id)
     return paneByLeafId
   }
 
@@ -302,10 +255,11 @@ export function replayTerminalLayout(
     }
 
     const createdPane = manager.splitPane(paneId, node.direction as TerminalPaneSplitDirection, {
-      ratio: node.ratio
+      ratio: node.ratio,
+      leafId: getLeftmostLeafId(node.second)
     })
     if (!createdPane) {
-      collectLeafIds(node, paneByLeafId, paneId)
+      restoreNode(node.first, paneId)
       return
     }
 
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.test.ts b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
index ffc8cf5c70d..b6752f8581d 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -3,6 +3,7 @@ import type * as React from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { POST_REPLAY_FOCUS_REPORTING_RESET, POST_REPLAY_MODE_RESET } from './layout-serialization'
 import type * as UseNotificationDispatchModule from './use-notification-dispatch'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
 
 // Why: the fresh-spawn and reattach paths now chain pre-signal → spawn →
 // register/settle through multiple microtasks. Tests that previously flushed
@@ -15,6 +16,12 @@ async function flushAsyncTicks(count = 6): Promise<void> {
 }
 
 const toastInfo = vi.fn()
+const LEAF_1 = '11111111-1111-4111-8111-111111111111' as const
+const LEAF_2 = '22222222-2222-4222-8222-222222222222' as const
+
+function leafIdForPane(paneId: number): string {
+  return paneId === 2 ? LEAF_2 : LEAF_1
+}
 
 type StoreState = {
   tabsByWorktree: Record<string, { id: string; ptyId: string | null; title?: string }[]>
@@ -171,8 +178,11 @@ function createMockTransport(initialPtyId: string | null = null): MockTransport
 }
 
 function createPane(paneId: number) {
+  const leafId = leafIdForPane(paneId)
   return {
     id: paneId,
+    leafId,
+    stablePaneId: leafId,
     terminal: {
       cols: 120,
       rows: 40,
@@ -195,7 +205,12 @@ function createManager(paneCount = 1) {
   return {
     setPaneGpuRendering: vi.fn(),
     markPaneHasComplexScriptOutput: vi.fn(),
-    getPanes: vi.fn(() => Array.from({ length: paneCount }, (_, index) => ({ id: index + 1 }))),
+    getPanes: vi.fn(() =>
+      Array.from({ length: paneCount }, (_, index) => ({
+        id: index + 1,
+        leafId: leafIdForPane(index + 1)
+      }))
+    ),
     closePane: vi.fn(),
     getActivePane: vi.fn<() => { id: number } | null>(() => null)
   }
@@ -586,11 +601,12 @@ describe('connectPanePty', () => {
       return 'pty-local-1'
     })
     transportFactoryQueue.push(transport)
+    const paneKey = makePaneKey('tab-1', LEAF_1)
     mockStoreState = {
       ...mockStoreState,
       agentStatusByPaneKey: {
-        'tab-1:1': {
-          paneKey: 'tab-1:1',
+        [paneKey]: {
+          paneKey,
           state: 'done',
           prompt: 'hi',
           updatedAt: 1000,
@@ -609,7 +625,7 @@ describe('connectPanePty', () => {
 
     capturedDataCallback.current?.('\x1b]133;D;130\x07thebr ~/repo $ ')
 
-    expect(mockStoreState.dropAgentStatus).toHaveBeenCalledWith('tab-1:1')
+    expect(mockStoreState.dropAgentStatus).toHaveBeenCalledWith(paneKey)
     expect(mockStoreState.removeAgentStatus).not.toHaveBeenCalled()
   })
 
@@ -626,8 +642,8 @@ describe('connectPanePty', () => {
     const pane = createPane(2)
     const manager = createManager(2)
     const deps = createDeps({
-      restoredLeafId: 'pane:2',
-      restoredPtyIdByLeafId: { 'pane:2': 'leaf-pty-2' }
+      restoredLeafId: LEAF_2,
+      restoredPtyIdByLeafId: { [LEAF_2]: 'leaf-pty-2' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -666,8 +682,8 @@ describe('connectPanePty', () => {
     const pane = createPane(2)
     const manager = createManager(2)
     const deps = createDeps({
-      restoredLeafId: 'pane:2',
-      restoredPtyIdByLeafId: { 'pane:2': 'stale-pty' }
+      restoredLeafId: LEAF_2,
+      restoredPtyIdByLeafId: { [LEAF_2]: 'stale-pty' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -705,8 +721,8 @@ describe('connectPanePty', () => {
     const pane = createPane(2)
     const manager = createManager(2)
     const deps = createDeps({
-      restoredLeafId: 'pane:2',
-      restoredPtyIdByLeafId: { 'pane:2': 'restored-session' }
+      restoredLeafId: LEAF_2,
+      restoredPtyIdByLeafId: { [LEAF_2]: 'restored-session' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -744,8 +760,8 @@ describe('connectPanePty', () => {
     const pane = createPane(1)
     const manager = createManager(1)
     const deps = createDeps({
-      restoredLeafId: 'pane:1',
-      restoredPtyIdByLeafId: { 'pane:1': 'tab-pty' }
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'tab-pty' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -795,8 +811,8 @@ describe('connectPanePty', () => {
     const pane = createPane(1)
     const manager = createManager(1)
     const deps = createDeps({
-      restoredLeafId: 'pane:1',
-      restoredPtyIdByLeafId: { 'pane:1': 'tab-pty' }
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'tab-pty' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -830,8 +846,8 @@ describe('connectPanePty', () => {
     const pane = createPane(1)
     const manager = createManager(1)
     const deps = createDeps({
-      restoredLeafId: 'pane:1',
-      restoredPtyIdByLeafId: { 'pane:1': 'tab-pty' }
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'tab-pty' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -1069,8 +1085,8 @@ describe('connectPanePty', () => {
     const remountPane = createPane(1)
     const remountManager = createManager(1)
     const remountDeps = createDeps({
-      restoredLeafId: 'pane:1',
-      restoredPtyIdByLeafId: { 'pane:1': 'pty-restarted' }
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'pty-restarted' }
     })
 
     connectPanePty(remountPane as never, remountManager as never, remountDeps as never)
@@ -1239,8 +1255,8 @@ describe('connectPanePty', () => {
     const pane = createPane(1)
     const manager = createManager(1)
     const deps = createDeps({
-      restoredLeafId: 'leaf-1',
-      restoredPtyIdByLeafId: { 'leaf-1': 'leaf-session' }
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'leaf-session' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -1343,8 +1359,8 @@ describe('connectPanePty', () => {
     const pane = createPane(1)
     const manager = createManager(1)
     const deps = createDeps({
-      restoredLeafId: 'leaf-1',
-      restoredPtyIdByLeafId: { 'leaf-1': 'leaf-session' }
+      restoredLeafId: LEAF_1,
+      restoredPtyIdByLeafId: { [LEAF_1]: 'leaf-session' }
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
@@ -1434,6 +1450,6 @@ describe('connectPanePty', () => {
 
     agentExitedHandler()
 
-    expect(deps.setCacheTimerStartedAt).toHaveBeenCalledWith('tab-1:1', null)
+    expect(deps.setCacheTimerStartedAt).toHaveBeenCalledWith(makePaneKey('tab-1', LEAF_1), null)
   })
 })
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index 544422456ca..221ad4aa796 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -14,11 +14,7 @@ import { getFitOverrideForPty, bindPanePtyId } from '@/lib/pane-manager/mobile-f
 import { isPtyLocked } from '@/lib/pane-manager/mobile-driver-state'
 import { isPaneReplaying, replayIntoTerminal } from './replay-guard'
 import { terminalOutputPrefersDomRenderer } from '@/lib/pane-manager/terminal-complex-script'
-import {
-  paneLeafId,
-  POST_REPLAY_MODE_RESET,
-  POST_REPLAY_FOCUS_REPORTING_RESET
-} from './layout-serialization'
+import { POST_REPLAY_MODE_RESET, POST_REPLAY_FOCUS_REPORTING_RESET } from './layout-serialization'
 import { warnTerminalLifecycleAnomaly } from './terminal-lifecycle-diagnostics'
 import { registerPtySerializer, registerPtyTitleSource } from './pty-buffer-serializer'
 import { getRemoteRuntimePtyEnvironmentId } from '@/runtime/runtime-terminal-stream'
@@ -28,6 +24,7 @@ import {
   waitForTerminalOutputParsed,
   writeTerminalOutput
 } from '@/lib/pane-manager/pane-terminal-output-scheduler'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
 import { createTerminalCommandLifecycle } from './terminal-command-lifecycle'
 
 const pendingSpawnByPaneKey = new Map<string, Promise<string | null>>()
@@ -153,10 +150,10 @@ export function connectPanePty(
   const paneStartup = deps.startup ?? null
   deps.startup = undefined
 
-  // Why: cache timer state is keyed per-pane (not per-tab) so split-pane tabs
-  // can track each Claude session independently without overwriting each other.
-  const cacheKey = `${deps.tabId}:${pane.id}`
-  const pendingSpawnKey = `${deps.tabId}:${paneLeafId(pane.id)}`
+  // Why: paneKey crosses PTY env, hook IPC, retained rows, and reload/replay.
+  // Use the stable layout leaf UUID, not the renderer-local numeric pane id.
+  const cacheKey = makePaneKey(deps.tabId, pane.leafId)
+  const pendingSpawnKey = cacheKey
   const commandLifecycle = createTerminalCommandLifecycle({
     onCommandFinished: () => {
       const state = useAppStore.getState()
@@ -327,9 +324,8 @@ export function connectPanePty(
   }
   // Why: inject ORCA_PANE_KEY so global Claude/Codex hooks can attribute their
   // callbacks to the correct Orca pane without resolving worktrees from cwd.
-  // The key matches the `${tabId}:${paneId}` composite used for cacheTimerByKey.
-  // ORCA_TAB_ID / ORCA_WORKTREE_ID are exposed separately so the receiver has
-  // routing context without having to split paneKey back into its parts.
+  // The key matches the `${tabId}:${leafId}` composite used for cacheTimerByKey
+  // and agentStatusByPaneKey. Treat it as opaque outside Orca.
   const paneEnv = {
     ...paneStartup?.env,
     ORCA_PANE_KEY: cacheKey,
@@ -368,7 +364,7 @@ export function connectPanePty(
     // pty:spawn returns. Daemon-host-only: SSH path leaves these undefined
     // and the main-side guard short-circuits.
     tabId: deps.tabId,
-    leafId: paneLeafId(pane.id),
+    leafId: pane.leafId,
     ...(shellOverride ? { shellOverride } : {}),
     ...(paneStartup?.telemetry ? { telemetry: paneStartup.telemetry } : {}),
     onPtyExit: onExit,
@@ -714,7 +710,7 @@ export function connectPanePty(
         warnTerminalLifecycleAnomaly('restored PTY reattach returned no PTY id', {
           tabId: deps.tabId,
           worktreeId: deps.worktreeId,
-          leafId: deps.restoredLeafId ?? paneLeafId(pane.id),
+          leafId: deps.restoredLeafId ?? pane.leafId,
           paneId: pane.id,
           ptyId: staleSessionId ?? null
         })
@@ -1163,7 +1159,7 @@ export function connectPanePty(
           warnTerminalLifecycleAnomaly('restored PTY reattach threw', {
             tabId: deps.tabId,
             worktreeId: deps.worktreeId,
-            leafId: deps.restoredLeafId ?? paneLeafId(pane.id),
+            leafId: deps.restoredLeafId ?? pane.leafId,
             paneId: pane.id,
             ptyId: deferredReattachSessionId,
             reason: message
@@ -1212,11 +1208,9 @@ export function connectPanePty(
       }
     } else {
       allowInitialIdleCacheSeed = false
-      const pendingSpawn = hasExistingPaneTransport
-        ? undefined
-        : pendingSpawnByPaneKey.get(pendingSpawnKey)
+      const pendingSpawn = pendingSpawnByPaneKey.get(pendingSpawnKey)
       if (pendingSpawn) {
-        console.log(`[pty-connect] pane=${pane.id} → PENDING SPAWN (waiting on sibling)`)
+        console.log(`[pty-connect] pane=${pane.id} → PENDING SPAWN (waiting on same leaf)`)
         ;((globalThis as Record<string, unknown>).__ptyConnectDiag as string[])?.push(
           `pane=${pane.id} → PENDING SPAWN`
         )
diff --git a/src/renderer/src/components/terminal-pane/pty-transport.test.ts b/src/renderer/src/components/terminal-pane/pty-transport.test.ts
index 252c2f018ba..1164b439282 100644
--- a/src/renderer/src/components/terminal-pane/pty-transport.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-transport.test.ts
@@ -666,7 +666,7 @@ describe('createRemoteRuntimePtyTransport', () => {
       command: 'claude',
       env: { ORCA_TAB_ID: 'tab-1' },
       tabId: 'tab-1',
-      leafId: 'pane:1'
+      leafId: '11111111-1111-4111-8111-111111111111'
     })
 
     const result = await transport.connect({
@@ -682,6 +682,8 @@ describe('createRemoteRuntimePtyTransport', () => {
         worktree: 'repo1::/remote/wt',
         command: 'claude',
         env: { ORCA_TAB_ID: 'tab-1' },
+        tabId: 'tab-1',
+        leafId: '11111111-1111-4111-8111-111111111111',
         focus: false
       },
       timeoutMs: 15_000
diff --git a/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
index 5f2d890a206..c42dd65dfca 100644
--- a/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
+++ b/src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
@@ -201,6 +201,8 @@ export function createRemoteRuntimePtyTransport(
           worktree: worktreeId,
           command,
           env,
+          tabId,
+          leafId,
           focus: false
         })
         handle = created.terminal.handle
diff --git a/src/renderer/src/components/terminal-pane/stale-agent-row.ts b/src/renderer/src/components/terminal-pane/stale-agent-row.ts
new file mode 100644
index 00000000000..e5cf1b20959
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/stale-agent-row.ts
@@ -0,0 +1,20 @@
+import { toast } from 'sonner'
+import { useAppStore } from '@/store'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
+
+export function dismissStaleAgentRowByKey(paneKey: string): void {
+  const store = useAppStore.getState()
+  const liveExisted = paneKey in store.agentStatusByPaneKey
+  const retainedExisted = paneKey in store.retainedAgentsByPaneKey
+  store.dropAgentStatus(paneKey)
+  store.dismissRetainedAgent(paneKey)
+  if (liveExisted || retainedExisted) {
+    toast.info("Agent's pane is no longer available.", {
+      id: `stale-agent-row-${paneKey}`
+    })
+  }
+}
+
+export function surfaceStaleAgentRow(tabId: string, leafId: string): void {
+  dismissStaleAgentRowByKey(makePaneKey(tabId, leafId))
+}
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
new file mode 100644
index 00000000000..b04b23db0d5
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-layout-leaf-ids.ts
@@ -0,0 +1,173 @@
+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'
+
+const EMPTY_TERMINAL_LAYOUT: TerminalLayoutSnapshot = {
+  root: null,
+  activeLeafId: null,
+  expandedLeafId: null
+}
+
+type LeafIdRewrite = {
+  nextLeafIdByInputLeafId: Map<string, TerminalLeafId>
+  duplicatedInputLeafIds: Set<string>
+}
+
+function cloneLayoutWithLeafRewrite(
+  node: TerminalPaneLayoutNode,
+  rewrite: LeafIdRewrite
+): TerminalPaneLayoutNode {
+  if (node.type === 'leaf') {
+    const replacement = rewrite.nextLeafIdByInputLeafId.get(node.leafId) ?? mintStablePaneId()
+    return { type: 'leaf', leafId: replacement }
+  }
+  return {
+    ...node,
+    first: cloneLayoutWithLeafRewrite(node.first, rewrite),
+    second: cloneLayoutWithLeafRewrite(node.second, rewrite)
+  }
+}
+
+function remapLeafRecord(
+  source: Record<string, string> | undefined,
+  rewrite: LeafIdRewrite
+): Record<string, string> | undefined {
+  if (!source) {
+    return undefined
+  }
+  const next: Record<string, string> = {}
+  for (const [leafId, value] of Object.entries(source)) {
+    if (rewrite.duplicatedInputLeafIds.has(leafId)) {
+      continue
+    }
+    const nextLeafId = rewrite.nextLeafIdByInputLeafId.get(leafId)
+    if (nextLeafId) {
+      next[nextLeafId] = value
+    }
+  }
+  return Object.keys(next).length > 0 ? next : undefined
+}
+
+function collectLeafCounts(
+  node: TerminalPaneLayoutNode,
+  counts: Map<string, number> = new Map()
+): Map<string, number> {
+  if (node.type === 'leaf') {
+    counts.set(node.leafId, (counts.get(node.leafId) ?? 0) + 1)
+    return counts
+  }
+  collectLeafCounts(node.first, counts)
+  collectLeafCounts(node.second, counts)
+  return counts
+}
+
+function firstLeafId(node: TerminalPaneLayoutNode | null): string | null {
+  if (!node) {
+    return null
+  }
+  return node.type === 'leaf' ? node.leafId : firstLeafId(node.first)
+}
+
+export function normalizeTerminalLayoutSnapshot(
+  snapshot: TerminalLayoutSnapshot | null | undefined
+): { snapshot: TerminalLayoutSnapshot; changed: boolean } {
+  if (!snapshot?.root) {
+    return { snapshot: snapshot ?? EMPTY_TERMINAL_LAYOUT, changed: false }
+  }
+  const counts = collectLeafCounts(snapshot.root)
+  const duplicatedInputLeafIds = new Set(
+    Array.from(counts.entries())
+      .filter(([, count]) => count > 1)
+      .map(([leafId]) => leafId)
+  )
+  const nextLeafIdByInputLeafId = new Map<string, TerminalLeafId>()
+  let changed = false
+  for (const [leafId, count] of counts) {
+    if (count === 1 && isTerminalLeafId(leafId)) {
+      nextLeafIdByInputLeafId.set(leafId, leafId)
+      continue
+    }
+    changed = true
+    if (count === 1) {
+      nextLeafIdByInputLeafId.set(leafId, mintStablePaneId())
+    }
+  }
+  if (!changed) {
+    return { snapshot, changed: false }
+  }
+  const rewrite: LeafIdRewrite = { nextLeafIdByInputLeafId, duplicatedInputLeafIds }
+  const root = cloneLayoutWithLeafRewrite(snapshot.root, rewrite)
+  const activeLeafId =
+    snapshot.activeLeafId && !duplicatedInputLeafIds.has(snapshot.activeLeafId)
+      ? (nextLeafIdByInputLeafId.get(snapshot.activeLeafId) ?? null)
+      : firstLeafId(root)
+  const expandedLeafId =
+    snapshot.expandedLeafId && !duplicatedInputLeafIds.has(snapshot.expandedLeafId)
+      ? (nextLeafIdByInputLeafId.get(snapshot.expandedLeafId) ?? null)
+      : null
+  const ptyIdsByLeafId = remapLeafRecord(snapshot.ptyIdsByLeafId, rewrite)
+  const buffersByLeafId = remapLeafRecord(snapshot.buffersByLeafId, rewrite)
+  const titlesByLeafId = remapLeafRecord(snapshot.titlesByLeafId, rewrite)
+  const {
+    ptyIdsByLeafId: _oldPtyIdsByLeafId,
+    buffersByLeafId: _oldBuffersByLeafId,
+    titlesByLeafId: _oldTitlesByLeafId,
+    ...snapshotWithoutLeafRecords
+  } = snapshot
+  return {
+    snapshot: {
+      ...snapshotWithoutLeafRecords,
+      root,
+      activeLeafId,
+      expandedLeafId,
+      ...(ptyIdsByLeafId ? { ptyIdsByLeafId } : {}),
+      ...(buffersByLeafId ? { buffersByLeafId } : {}),
+      ...(titlesByLeafId ? { titlesByLeafId } : {})
+    },
+    changed: true
+  }
+}
+
+export function collectLeafIdsInOrder(node: TerminalPaneLayoutNode | null | undefined): string[] {
+  if (!node) {
+    return []
+  }
+  if (node.type === 'leaf') {
+    return [node.leafId]
+  }
+  return [...collectLeafIdsInOrder(node.first), ...collectLeafIdsInOrder(node.second)]
+}
+
+export function getLeftmostLeafId(node: TerminalPaneLayoutNode): string {
+  return node.type === 'leaf' ? node.leafId : getLeftmostLeafId(node.first)
+}
+
+function collectReplayCreatedPaneLeafIds(
+  node: Extract<TerminalPaneLayoutNode, { type: 'split' }>,
+  leafIdsInReplayCreationOrder: string[]
+): void {
+  // Why: replayTerminalLayout() creates one new pane per split and assigns it
+  // to the split's second subtree before recursing, so the new pane maps to
+  // the leftmost leaf reachable within that second subtree.
+  leafIdsInReplayCreationOrder.push(getLeftmostLeafId(node.second))
+
+  if (node.first.type === 'split') {
+    collectReplayCreatedPaneLeafIds(node.first, leafIdsInReplayCreationOrder)
+  }
+  if (node.second.type === 'split') {
+    collectReplayCreatedPaneLeafIds(node.second, leafIdsInReplayCreationOrder)
+  }
+}
+
+export function collectLeafIdsInReplayCreationOrder(
+  node: TerminalPaneLayoutNode | null | undefined
+): string[] {
+  if (!node) {
+    return []
+  }
+  const leafIdsInReplayCreationOrder = [getLeftmostLeafId(node)]
+  if (node.type === 'split') {
+    collectReplayCreatedPaneLeafIds(node, leafIdsInReplayCreationOrder)
+  }
+  return leafIdsInReplayCreationOrder
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.test.ts b/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.test.ts
index 87a5a3ad394..e9608dcd120 100644
--- a/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.test.ts
@@ -1,6 +1,8 @@
 import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { TerminalLayoutSnapshot } from '../../../../shared/types'
 
+const LEAF_ID = '11111111-1111-4111-8111-111111111111' as const
+
 const mocks = vi.hoisted(() => ({
   flushTerminalOutput: vi.fn()
 }))
@@ -40,8 +42,11 @@ beforeEach(() => {
   mocks.flushTerminalOutput.mockReset()
 })
 
-function mockRootForPane(paneId: number): HTMLDivElement {
-  const pane = new MockHTMLElement({ classList: ['pane'], dataset: { paneId: String(paneId) } })
+function mockRootForPane(paneId: number, leafId: string = LEAF_ID): HTMLDivElement {
+  const pane = new MockHTMLElement({
+    classList: ['pane'],
+    dataset: { paneId: String(paneId), leafId }
+  })
   return new MockHTMLElement({ firstElementChild: pane }) as unknown as HTMLDivElement
 }
 
@@ -55,6 +60,8 @@ describe('captureTerminalShutdownLayout', () => {
     }
     const pane = {
       id: 1,
+      leafId: LEAF_ID,
+      stablePaneId: LEAF_ID,
       terminal,
       serializeAddon: {
         serialize: vi.fn(() => {
@@ -75,7 +82,7 @@ describe('captureTerminalShutdownLayout', () => {
 
     const layout = captureTerminalShutdownLayout({
       manager: manager as never,
-      container: mockRootForPane(1),
+      container: mockRootForPane(1, LEAF_ID),
       expandedPaneId: null,
       paneTransports: new Map([[1, { getPtyId: vi.fn(() => 'pty-1') }]]),
       paneTitlesByPaneId: { 1: 'build logs' },
@@ -84,12 +91,12 @@ describe('captureTerminalShutdownLayout', () => {
 
     expect(order).toEqual(['flush', 'serialize'])
     expect(layout).toMatchObject<TerminalLayoutSnapshot>({
-      root: { type: 'leaf', leafId: 'pane:1' },
-      activeLeafId: 'pane:1',
+      root: { type: 'leaf', leafId: LEAF_ID },
+      activeLeafId: LEAF_ID,
       expandedLeafId: null,
-      buffersByLeafId: { 'pane:1': 'snapshot:queued-before-quit' },
-      ptyIdsByLeafId: { 'pane:1': 'pty-1' },
-      titlesByLeafId: { 'pane:1': 'build logs' }
+      buffersByLeafId: { [LEAF_ID]: 'snapshot:queued-before-quit' },
+      ptyIdsByLeafId: { [LEAF_ID]: 'pty-1' },
+      titlesByLeafId: { [LEAF_ID]: 'build logs' }
     })
   })
 
@@ -97,6 +104,8 @@ describe('captureTerminalShutdownLayout', () => {
     const { captureTerminalShutdownLayout } = await import('./terminal-shutdown-layout-capture')
     const pane = {
       id: 1,
+      leafId: LEAF_ID,
+      stablePaneId: LEAF_ID,
       terminal: { options: { scrollback: 50_000 } },
       serializeAddon: {
         serialize: vi.fn(() => 'x'.repeat(512 * 1024))
@@ -117,7 +126,7 @@ describe('captureTerminalShutdownLayout', () => {
         root: null,
         activeLeafId: null,
         expandedLeafId: null,
-        buffersByLeafId: { 'pane:1': 'previous-local-scrollback' }
+        buffersByLeafId: { [LEAF_ID]: 'previous-local-scrollback' }
       },
       captureBuffers: false
     })
@@ -125,7 +134,7 @@ describe('captureTerminalShutdownLayout', () => {
     expect(mocks.flushTerminalOutput).not.toHaveBeenCalled()
     expect(pane.serializeAddon.serialize).not.toHaveBeenCalled()
     expect(layout.buffersByLeafId).toBeUndefined()
-    expect(layout.ptyIdsByLeafId).toEqual({ 'pane:1': 'pty-1' })
-    expect(layout.titlesByLeafId).toEqual({ 'pane:1': 'local shell' })
+    expect(layout.ptyIdsByLeafId).toEqual({ [LEAF_ID]: 'pty-1' })
+    expect(layout.titlesByLeafId).toEqual({ [LEAF_ID]: 'local shell' })
   })
 })
diff --git a/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.ts b/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.ts
index 67f9d9bb4c7..709af1fee8b 100644
--- a/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-shutdown-layout-capture.ts
@@ -2,12 +2,12 @@ import type { TerminalLayoutSnapshot } from '../../../../shared/types'
 import type { ManagedPane } from '@/lib/pane-manager/pane-manager'
 import type { PtyTransport } from './pty-transport'
 import { flushTerminalOutput } from '@/lib/pane-manager/pane-terminal-output-scheduler'
-import { paneLeafId, serializeTerminalLayout } from './layout-serialization'
+import { serializeTerminalLayout } from './layout-serialization'
 import { mergeCapturedLeafState } from './merge-captured-leaf-state'
 
 const MAX_BUFFER_BYTES = 512 * 1024
 
-type ShutdownPane = Pick<ManagedPane, 'id' | 'terminal' | 'serializeAddon'>
+type ShutdownPane = Pick<ManagedPane, 'id' | 'leafId' | 'terminal' | 'serializeAddon'>
 
 type ShutdownPaneManager = {
   getPanes(): ShutdownPane[]
@@ -42,7 +42,7 @@ export function captureTerminalShutdownLayout({
         // Why: non-focused panes may have renderer-throttled PTY bytes queued;
         // push them into xterm before taking the shutdown scrollback snapshot.
         flushTerminalOutput(pane.terminal)
-        const leafId = paneLeafId(pane.id)
+        const leafId = pane.leafId
         let scrollback = pane.terminal.options.scrollback ?? 10_000
         let serialized = pane.serializeAddon.serialize({ scrollback })
         // Cap at 512KB — binary search for largest scrollback that fits.
@@ -72,11 +72,16 @@ export function captureTerminalShutdownLayout({
   }
 
   const activePaneId = manager.getActivePane()?.id ?? panes[0]?.id ?? null
-  const layout = serializeTerminalLayout(container, activePaneId, expandedPaneId)
-  const currentLeafIds = new Set(panes.map((p) => paneLeafId(p.id)))
+  const layout = serializeTerminalLayout(
+    container,
+    activePaneId,
+    expandedPaneId,
+    new Map(panes.map((pane) => [pane.id, pane.leafId]))
+  )
+  const currentLeafIds = new Set(panes.map((p) => p.leafId))
   const ptyEntries = panes
-    .map((pane) => [paneLeafId(pane.id), paneTransports.get(pane.id)?.getPtyId() ?? null] as const)
-    .filter((entry): entry is readonly [string, string] => entry[1] !== null)
+    .map((pane) => [pane.leafId, paneTransports.get(pane.id)?.getPtyId() ?? null] as const)
+    .filter((entry): entry is readonly [ShutdownPane['leafId'], string] => entry[1] !== null)
 
   const mergedBuffers = captureBuffers
     ? mergeCapturedLeafState({
@@ -99,7 +104,7 @@ export function captureTerminalShutdownLayout({
 
   const titleEntries = panes
     .filter((p) => paneTitlesByPaneId[p.id])
-    .map((p) => [paneLeafId(p.id), paneTitlesByPaneId[p.id]] as const)
+    .map((p) => [p.leafId, paneTitlesByPaneId[p.id]] as const)
   if (titleEntries.length > 0) {
     layout.titlesByLeafId = Object.fromEntries(titleEntries)
   }
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.ts
index d739d472779..c2ecd12cef1 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.ts
@@ -12,6 +12,9 @@ import { fitAndFocusPanes, fitPanes } from './pane-helpers'
 import type { PtyTransport } from './pty-transport'
 import { handleTerminalFileDrop } from './terminal-drop-handler'
 import { flushTerminalOutput } from '@/lib/pane-manager/pane-terminal-output-scheduler'
+import { handleFocusTerminalPaneDetail } from './focus-terminal-pane-event'
+import { surfaceStaleAgentRow } from './stale-agent-row'
+import { useAppStore } from '@/store'
 
 type UseTerminalPaneGlobalEffectsArgs = {
   tabId: string
@@ -114,18 +117,12 @@ export function useTerminalPaneGlobalEffects({
   useEffect(() => {
     const onFocusPane = (event: Event): void => {
       const detail = (event as CustomEvent<FocusTerminalPaneDetail | undefined>).detail
-      if (!detail?.tabId || detail.tabId !== tabId) {
-        return
-      }
-      const manager = managerRef.current
-      if (!manager) {
-        return
-      }
-      const pane = manager.getPanes().find((candidate) => candidate.id === detail.paneId)
-      if (!pane) {
-        return
-      }
-      manager.setActivePane(pane.id, { focus: true })
+      handleFocusTerminalPaneDetail(detail, {
+        tabId,
+        manager: managerRef.current,
+        acknowledgeAgents: (paneKeys) => useAppStore.getState().acknowledgeAgents(paneKeys),
+        surfaceStaleAgentRow
+      })
     }
     window.addEventListener(FOCUS_TERMINAL_PANE_EVENT, onFocusPane)
     return () => window.removeEventListener(FOCUS_TERMINAL_PANE_EVENT, onFocusPane)
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
index af06537c444..20ab6b285b0 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
@@ -19,10 +19,11 @@ import type { EventProps } from '../../../../shared/telemetry-events'
 import { resolveTerminalFontWeights } from '../../../../shared/terminal-fonts'
 import {
   buildFontFamily,
-  collectLeafIdsInReplayCreationOrder,
+  normalizeTerminalLayoutSnapshot,
   replayTerminalLayout,
   restoreScrollbackBuffers
 } from './layout-serialization'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
 import { applyExpandedLayoutTo, restoreExpandedLayoutFrom } from './expand-collapse'
 import {
   applyTerminalAppearance,
@@ -335,11 +336,12 @@ export function useTerminalPaneLifecycle({
       setPaneCount(managerRef.current?.getPanes().length ?? 0)
     }
 
+    const normalizedInitialLayout = normalizeTerminalLayoutSnapshot(initialLayoutRef.current)
+    if (normalizedInitialLayout.changed) {
+      initialLayoutRef.current = normalizedInitialLayout.snapshot
+      useAppStore.getState().setTabLayout(tabId, normalizedInitialLayout.snapshot)
+    }
     let shouldPersistLayout = false
-    const restoredLeafIdsInCreationOrder = collectLeafIdsInReplayCreationOrder(
-      initialLayoutRef.current.root
-    )
-    let restoredPaneCreateIndex = 0
     const ptyDeps = {
       tabId,
       worktreeId,
@@ -519,15 +521,13 @@ export function useTerminalPaneLifecycle({
           }
         }
         applyAppearance(manager)
-        const restoredLeafId = restoredLeafIdsInCreationOrder[restoredPaneCreateIndex] ?? null
-        restoredPaneCreateIndex += 1
         const panePtyBinding = connectPanePty(pane, manager, {
           ...ptyDeps,
           // Why: spread order matters — spawnHints.cwd (inherited from the
           // source pane) must override the tab-level ptyDeps.cwd (worktree
           // root) so Cmd+D splits boot in the live cwd.
           ...(spawnHints?.cwd ? { cwd: spawnHints.cwd } : {}),
-          restoredLeafId
+          restoredLeafId: pane.leafId
         })
         // Why: connectPanePty receives a spread copy of ptyDeps, so the
         // `deps.startup = undefined` it performs internally only clears its
@@ -546,7 +546,7 @@ export function useTerminalPaneLifecycle({
         scheduleRuntimeGraphSync()
         queueResizeAll(true)
       },
-      onPaneClosed: (paneId) => {
+      onPaneClosed: (paneId, closedPane) => {
         const linkProviderDisposable = linkProviderDisposablesRef.current.get(paneId)
         if (linkProviderDisposable) {
           linkProviderDisposable.dispose()
@@ -600,7 +600,12 @@ export function useTerminalPaneLifecycle({
           // (not remove) so any retained `done` snapshot for this pane is also
           // cleared and a same-frame live→gone transition cannot re-snapshot
           // it via the retention sync.
-          useAppStore.getState().dropAgentStatus(`${tabId}:${paneId}`)
+          const leafId = closedPane?.leafId
+          if (leafId) {
+            const paneKey = makePaneKey(tabId, leafId)
+            useAppStore.getState().setCacheTimerStartedAt(paneKey, null)
+            useAppStore.getState().dropAgentStatus(paneKey)
+          }
           transport.destroy?.()
           paneTransportsRef.current.delete(paneId)
         }
diff --git a/src/renderer/src/constants/terminal.ts b/src/renderer/src/constants/terminal.ts
index bdfa382d176..570685d884e 100644
--- a/src/renderer/src/constants/terminal.ts
+++ b/src/renderer/src/constants/terminal.ts
@@ -24,7 +24,12 @@ export type ToggleTerminalPaneExpandDetail = {
 
 export type FocusTerminalPaneDetail = {
   tabId: string
-  paneId: number
+  /** Stable terminal layout leaf UUID. Numeric PaneManager ids are renderer-local
+   *  and can be reminted during replay/reload, so cross-component focus uses
+   *  the durable leaf identity and resolves it at the receiving TerminalPane. */
+  leafId: string | null
+  /** Optional paneKey to ack only after the target leaf resolves and focuses. */
+  ackPaneKeyOnSuccess?: string
 }
 
 export type PasteTerminalTextDetail = {
diff --git a/src/renderer/src/hooks/useAutoAckViewedAgent.test.ts b/src/renderer/src/hooks/useAutoAckViewedAgent.test.ts
index ee92d729a0f..52ebd4e8d63 100644
--- a/src/renderer/src/hooks/useAutoAckViewedAgent.test.ts
+++ b/src/renderer/src/hooks/useAutoAckViewedAgent.test.ts
@@ -2,6 +2,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { computeAutoAckTargets } from './useAutoAckViewedAgent'
 import { createTestStore, makeTab } from '../store/slices/store-test-helpers'
 import type { RetainedAgentEntry } from '../store/slices/agent-status'
+import { makePaneKey } from '../../../shared/stable-pane-id'
+
+const CODEX_LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const OTHER_LEAF_ID = '22222222-2222-4222-8222-222222222222'
 
 // Why: regression coverage for the codex inline-agent row that stayed bold
 // after returning from another workspace (docs/codex-agent-row-bold-stuck.md).
@@ -26,8 +30,8 @@ describe('computeAutoAckTargets — codex retain race regression', () => {
     vi.useFakeTimers()
     vi.setSystemTime(new Date('2026-05-05T12:00:00.000Z'))
     const store = createTestStore()
-    const paneKey = 'tab-codex:2'
     const activeTabId = 'tab-codex'
+    const paneKey = makePaneKey(activeTabId, CODEX_LEAF_ID)
 
     // 1. Codex starts working, user acks it (e.g. by clicking the row).
     store.getState().setAgentStatus(paneKey, {
@@ -72,7 +76,7 @@ describe('computeAutoAckTargets — codex retain race regression', () => {
 
     // 5. The user is back on the codex tab. computeAutoAckTargets must see
     //    the retained row and surface it for ack — pre-fix this returned [].
-    const targets = computeAutoAckTargets(store.getState(), activeTabId)
+    const targets = computeAutoAckTargets(store.getState(), activeTabId, CODEX_LEAF_ID)
     expect(targets).toEqual([paneKey])
   })
 
@@ -80,8 +84,8 @@ describe('computeAutoAckTargets — codex retain race regression', () => {
     vi.useFakeTimers()
     vi.setSystemTime(new Date('2026-05-05T12:00:00.000Z'))
     const store = createTestStore()
-    const paneKey = 'tab-codex:2'
     const activeTabId = 'tab-codex'
+    const paneKey = makePaneKey(activeTabId, CODEX_LEAF_ID)
 
     store.getState().setAgentStatus(paneKey, {
       state: 'done',
@@ -101,19 +105,19 @@ describe('computeAutoAckTargets — codex retain race regression', () => {
     store.getState().removeAgentStatus(paneKey)
 
     // First scan: the retained row is unvisited.
-    expect(computeAutoAckTargets(store.getState(), activeTabId)).toEqual([paneKey])
+    expect(computeAutoAckTargets(store.getState(), activeTabId, CODEX_LEAF_ID)).toEqual([paneKey])
 
     // Simulate the ack effect.
     vi.setSystemTime(new Date('2026-05-05T12:00:01.000Z'))
     store.getState().acknowledgeAgents([paneKey])
 
     // Second scan: idempotent — nothing to ack.
-    expect(computeAutoAckTargets(store.getState(), activeTabId)).toEqual([])
+    expect(computeAutoAckTargets(store.getState(), activeTabId, CODEX_LEAF_ID)).toEqual([])
   })
 
   it('skips retained rows whose paneKey is on a different tab', () => {
     const store = createTestStore()
-    const paneKey = 'tab-other:0'
+    const paneKey = makePaneKey('tab-other', OTHER_LEAF_ID)
     store.getState().setAgentStatus(paneKey, {
       state: 'done',
       prompt: 'p',
@@ -134,15 +138,15 @@ describe('computeAutoAckTargets — codex retain race regression', () => {
     // Active tab differs — the retained row must NOT be acked while the user
     // is looking at a different tab; the bold-until-viewed signal must
     // survive the tab switch.
-    expect(computeAutoAckTargets(store.getState(), 'tab-codex')).toEqual([])
+    expect(computeAutoAckTargets(store.getState(), 'tab-codex', CODEX_LEAF_ID)).toEqual([])
   })
 
   it('acks a paneKey present in BOTH live and retained without throwing', () => {
     vi.useFakeTimers()
     vi.setSystemTime(new Date('2026-05-05T12:00:00.000Z'))
     const store = createTestStore()
-    const paneKey = 'tab-codex:2'
     const activeTabId = 'tab-codex'
+    const paneKey = makePaneKey(activeTabId, CODEX_LEAF_ID)
 
     // Construct a (rare) state where retainedAgentsByPaneKey and
     // agentStatusByPaneKey both contain the same paneKey — e.g. the
@@ -165,7 +169,7 @@ describe('computeAutoAckTargets — codex retain race regression', () => {
       }
     ])
 
-    const targets = computeAutoAckTargets(store.getState(), activeTabId)
+    const targets = computeAutoAckTargets(store.getState(), activeTabId, CODEX_LEAF_ID)
     // Two pushes, same paneKey — duplicates are intentional and harmless;
     // acknowledgeAgents short-circuits per key.
     expect(targets.length).toBeLessThanOrEqual(2)
diff --git a/src/renderer/src/hooks/useAutoAckViewedAgent.ts b/src/renderer/src/hooks/useAutoAckViewedAgent.ts
index 2209c554040..25cb244a691 100644
--- a/src/renderer/src/hooks/useAutoAckViewedAgent.ts
+++ b/src/renderer/src/hooks/useAutoAckViewedAgent.ts
@@ -2,17 +2,26 @@ import { useEffect } from 'react'
 import { useAppStore } from '@/store'
 import type { AgentStatusEntry } from '../../../shared/agent-status-types'
 import type { RetainedAgentEntry } from '@/store/slices/agent-status'
+import type { TerminalLayoutSnapshot } from '../../../shared/types'
+import { isTerminalLeafId, makePaneKey } from '../../../shared/stable-pane-id'
+
+function resolveActiveLeafId(
+  state: { terminalLayoutsByTabId: Record<string, TerminalLayoutSnapshot> },
+  activeTabId: string
+): string | null {
+  const leafId = state.terminalLayoutsByTabId[activeTabId]?.activeLeafId ?? null
+  return leafId && isTerminalLeafId(leafId) ? leafId : null
+}
 
 /**
  * Pure helper used by the hook below — exported so the regression test for
  * the codex-row-stays-bold race (docs/codex-agent-row-bold-stuck.md) can
  * exercise the decision against a real test store without needing a DOM.
  *
- * Returns the list of paneKeys that should be acked given the active tab.
- * Walks BOTH the live agent map AND the retained snapshot map: the inline
- * agents list renders the union, so the ack scan must too. A paneKey may
- * appear in both maps simultaneously (paneKey reuse mid-frame); duplicate
- * pushes are harmless because acknowledgeAgents short-circuits per key.
+ * Returns the list of paneKeys that should be acked given the active tab and
+ * exact active leaf. Split tabs can host multiple agent panes, so equality on
+ * `${tabId}:${leafId}` is required; tab-prefix matching would mark siblings
+ * read without ever displaying them.
  */
 export function computeAutoAckTargets(
   state: {
@@ -20,29 +29,29 @@ export function computeAutoAckTargets(
     retainedAgentsByPaneKey: Record<string, RetainedAgentEntry>
     acknowledgedAgentsByPaneKey: Record<string, number>
   },
-  activeTabId: string
+  activeTabId: string,
+  activeLeafId: string | null
 ): string[] {
-  const prefix = `${activeTabId}:`
+  if (!activeLeafId || !isTerminalLeafId(activeLeafId)) {
+    return []
+  }
+  const targetKey = makePaneKey(activeTabId, activeLeafId)
   const targets: string[] = []
-  for (const [paneKey, entry] of Object.entries(state.agentStatusByPaneKey)) {
-    if (!paneKey.startsWith(prefix)) {
-      continue
-    }
-    const ackAt = state.acknowledgedAgentsByPaneKey[paneKey] ?? 0
+  const liveEntry = state.agentStatusByPaneKey[targetKey]
+  if (liveEntry) {
+    const ackAt = state.acknowledgedAgentsByPaneKey[targetKey] ?? 0
     // Why: use stateStartedAt (not updatedAt) so tool/prompt pings within the
     // same state don't re-trigger ack work — keeping the comparison aligned
     // with WorktreeCardAgents' is-unvisited rule.
-    if (ackAt < entry.stateStartedAt) {
-      targets.push(paneKey)
+    if (ackAt < liveEntry.stateStartedAt) {
+      targets.push(targetKey)
     }
   }
-  for (const [paneKey, retained] of Object.entries(state.retainedAgentsByPaneKey)) {
-    if (!paneKey.startsWith(prefix)) {
-      continue
-    }
-    const ackAt = state.acknowledgedAgentsByPaneKey[paneKey] ?? 0
+  const retained = state.retainedAgentsByPaneKey[targetKey]
+  if (retained) {
+    const ackAt = state.acknowledgedAgentsByPaneKey[targetKey] ?? 0
     if (ackAt < retained.entry.stateStartedAt) {
-      targets.push(paneKey)
+      targets.push(targetKey)
     }
   }
   return targets
@@ -102,6 +111,7 @@ export function useAutoAckViewedAgent(): void {
     let lastAgentStatus: unknown = undefined
     let lastRetained: unknown = undefined
     let lastAcknowledged: unknown = undefined
+    let lastLayouts: unknown = undefined
 
     const maybeAck = (): void => {
       const s = useAppStore.getState()
@@ -110,7 +120,8 @@ export function useAutoAckViewedAgent(): void {
         s.activeTabId === lastActiveTabId &&
         s.agentStatusByPaneKey === lastAgentStatus &&
         s.retainedAgentsByPaneKey === lastRetained &&
-        s.acknowledgedAgentsByPaneKey === lastAcknowledged
+        s.acknowledgedAgentsByPaneKey === lastAcknowledged &&
+        s.terminalLayoutsByTabId === lastLayouts
       ) {
         return
       }
@@ -136,6 +147,7 @@ export function useAutoAckViewedAgent(): void {
       if (!activeTabId) {
         return
       }
+      const activeLeafId = resolveActiveLeafId(s, activeTabId)
       // Why: advance the refs ONLY after all gates have passed — if the
       // visibility gate (window hidden/unfocused or no activeTabId) caused an
       // early return, leave the refs stale so the next call (e.g. triggered by
@@ -148,7 +160,8 @@ export function useAutoAckViewedAgent(): void {
       lastAgentStatus = s.agentStatusByPaneKey
       lastRetained = s.retainedAgentsByPaneKey
       lastAcknowledged = s.acknowledgedAgentsByPaneKey
-      const toAck = computeAutoAckTargets(s, activeTabId)
+      lastLayouts = s.terminalLayoutsByTabId
+      const toAck = computeAutoAckTargets(s, activeTabId, activeLeafId)
       if (toAck.length > 0) {
         s.acknowledgeAgents(toAck)
       }
diff --git a/src/renderer/src/hooks/useAutomationDispatchEvents.ts b/src/renderer/src/hooks/useAutomationDispatchEvents.ts
index e833e85369b..b6fdf1a6e1c 100644
--- a/src/renderer/src/hooks/useAutomationDispatchEvents.ts
+++ b/src/renderer/src/hooks/useAutomationDispatchEvents.ts
@@ -2,7 +2,7 @@ import { useEffect } from 'react'
 import { launchAgentBackgroundSession } from '@/lib/launch-agent-background-session'
 import { useAppStore } from '@/store'
 import type { AutomationDispatchResult } from '../../../shared/automations-types'
-import { FIRST_PANE_ID } from '../../../shared/pane-key'
+import { parsePaneKey } from '../../../shared/stable-pane-id'
 
 const AUTOMATIONS_CHANGED_EVENT = 'orca:automations-changed'
 
@@ -151,10 +151,14 @@ export function useAutomationDispatchEvents(): void {
           void markCompletionResult()
         }
         const observeAgentStatus = (tabId: string): void => {
-          const paneKey = `${tabId}:${FIRST_PANE_ID}`
           const checkCurrentStatus = (): void => {
-            if (useAppStore.getState().agentStatusByPaneKey[paneKey]?.state === 'done') {
-              handleAgentDone()
+            const { agentStatusByPaneKey } = useAppStore.getState()
+            for (const [paneKey, entry] of Object.entries(agentStatusByPaneKey)) {
+              const parsed = parsePaneKey(paneKey)
+              if (parsed?.tabId === tabId && entry.state === 'done') {
+                handleAgentDone()
+                return
+              }
             }
           }
           // Why: Codex/Claude completion normally arrives through the global
diff --git a/src/renderer/src/hooks/useIpcEvents.test.ts b/src/renderer/src/hooks/useIpcEvents.test.ts
index 9e412a5cdf3..f5d927fe68f 100644
--- a/src/renderer/src/hooks/useIpcEvents.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents.test.ts
@@ -2,6 +2,16 @@
 import type * as ReactModule from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { resolveZoomTarget } from './useIpcEvents'
+import { makePaneKey } from '../../../shared/stable-pane-id'
+
+const FUTURE_LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const STALE_LEAF_ID = '22222222-2222-4222-8222-222222222222'
+const ORPHAN_LEAF_ID = '33333333-3333-4333-8333-333333333333'
+const TAB_1_LEAF_ID = '44444444-4444-4444-8444-444444444444'
+const FUTURE_PANE_KEY = makePaneKey('tab-future', FUTURE_LEAF_ID)
+const STALE_PANE_KEY = makePaneKey('tab-future', STALE_LEAF_ID)
+const ORPHAN_PANE_KEY = makePaneKey('tab-orphan', ORPHAN_LEAF_ID)
+const TAB_1_PANE_KEY = makePaneKey('tab-1', TAB_1_LEAF_ID)
 
 function makeTarget(args: { hasXtermClass?: boolean; editorClosest?: boolean }): {
   classList: { contains: (token: string) => boolean }
@@ -1672,6 +1682,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
       removeSshCredentialRequest: vi.fn(),
       clearTabPtyId: vi.fn(),
       runtimePaneTitlesByTabId: {},
+      terminalLayoutsByTabId: {},
       repos: [],
       worktreesByRepo: {},
       tabsByWorktree: {},
@@ -1822,7 +1833,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     const getSnapshot = vi.fn(() =>
       Promise.resolve([
         {
-          paneKey: 'tab-future:0',
+          paneKey: FUTURE_PANE_KEY,
           state: 'working' as const,
           prompt: 'p',
           agentType: 'claude',
@@ -1877,7 +1888,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
 
     // Fire an event for an unknown paneKey while not ready — must NOT call setAgentStatus.
     onSetListenerRef.current({
-      paneKey: 'tab-future:0',
+      paneKey: FUTURE_PANE_KEY,
       state: 'working',
       prompt: 'p',
       agentType: 'claude',
@@ -1891,6 +1902,13 @@ describe('useIpcEvents agent status snapshot integration', () => {
     storeState.tabsByWorktree = {
       'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Future Tab' }]
     }
+    storeState.terminalLayoutsByTabId = {
+      'tab-future': {
+        root: { type: 'leaf', leafId: FUTURE_LEAF_ID },
+        activeLeafId: FUTURE_LEAF_ID,
+        expandedLeafId: null
+      }
+    }
     if (typeof subscribeListenerRef.current !== 'function') {
       throw new Error('Expected useAppStore.subscribe listener to be registered')
     }
@@ -1899,7 +1917,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
 
     expect(setAgentStatus).toHaveBeenCalledTimes(1)
     expect(setAgentStatus).toHaveBeenCalledWith(
-      'tab-future:0',
+      FUTURE_PANE_KEY,
       expect.objectContaining({ state: 'working', prompt: 'p', agentType: 'claude' }),
       'Future Tab',
       { updatedAt: 1_700_000_000_000, stateStartedAt: 1_699_999_999_000 }
@@ -2010,7 +2028,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     const getSnapshot = vi.fn(() =>
       Promise.resolve([
         {
-          paneKey: 'tab-orphan:0',
+          paneKey: ORPHAN_PANE_KEY,
           state: 'done' as const,
           prompt: 'p',
           agentType: 'claude',
@@ -2025,6 +2043,68 @@ describe('useIpcEvents agent status snapshot integration', () => {
       tabsByWorktree: {
         'wt-1': [{ id: 'tab-other', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Other' }]
       },
+      terminalLayoutsByTabId: {
+        'tab-orphan': {
+          root: { type: 'leaf', leafId: ORPHAN_LEAF_ID },
+          activeLeafId: ORPHAN_LEAF_ID,
+          expandedLeafId: null
+        }
+      },
+      workspaceSessionReady: true
+    })
+
+    stubReactSyncEffect()
+    vi.doMock('../store', () => ({
+      useAppStore: {
+        subscribe: vi.fn(() => () => {}),
+        getState: () => storeState
+      }
+    }))
+    stubAuxiliaryModules()
+    vi.stubGlobal(
+      'window',
+      buildWindowApi({
+        getSnapshot,
+        onSet: () => () => {}
+      })
+    )
+
+    const { useIpcEvents } = await import('./useIpcEvents')
+
+    useIpcEvents()
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(setAgentStatus).not.toHaveBeenCalled()
+  })
+
+  it('silently discards valid paneKeys whose leaf is not in the current layout', async () => {
+    const setAgentStatus = vi.fn()
+    const getSnapshot = vi.fn(() =>
+      Promise.resolve([
+        {
+          paneKey: STALE_PANE_KEY,
+          state: 'done' as const,
+          prompt: 'p',
+          agentType: 'claude',
+          receivedAt: 1_700_000_000_000,
+          stateStartedAt: 1_699_999_999_000
+        }
+      ])
+    )
+
+    const storeState: StoreLike = buildStoreState({
+      setAgentStatus,
+      tabsByWorktree: {
+        'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Future Tab' }]
+      },
+      terminalLayoutsByTabId: {
+        'tab-future': {
+          root: { type: 'leaf', leafId: FUTURE_LEAF_ID },
+          activeLeafId: FUTURE_LEAF_ID,
+          expandedLeafId: null
+        }
+      },
       workspaceSessionReady: true
     })
 
@@ -2067,6 +2147,13 @@ describe('useIpcEvents agent status snapshot integration', () => {
       },
       tabsByWorktree: {
         'wt-1': [{ id: 'tab-1', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Terminal 1' }]
+      },
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: TAB_1_LEAF_ID },
+          activeLeafId: TAB_1_LEAF_ID,
+          expandedLeafId: null
+        }
       }
     })
 
@@ -2090,7 +2177,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     await Promise.resolve()
 
     onSetListenerRef.current?.({
-      paneKey: 'tab-1:0',
+      paneKey: TAB_1_PANE_KEY,
       connectionId: 'conn-1',
       state: 'working',
       receivedAt: 1_700_000_000_100,
@@ -2098,7 +2185,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     })
 
     expect(setAgentStatus).toHaveBeenCalledWith(
-      'tab-1:0',
+      TAB_1_PANE_KEY,
       expect.objectContaining({ state: 'working' }),
       'Terminal 1',
       { updatedAt: 1_700_000_000_100, stateStartedAt: 1_699_999_999_100 }
@@ -2119,6 +2206,13 @@ describe('useIpcEvents agent status snapshot integration', () => {
       },
       tabsByWorktree: {
         'wt-1': [{ id: 'tab-1', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Terminal 1' }]
+      },
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: TAB_1_LEAF_ID },
+          activeLeafId: TAB_1_LEAF_ID,
+          expandedLeafId: null
+        }
       }
     })
 
@@ -2142,7 +2236,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     await Promise.resolve()
 
     onSetListenerRef.current?.({
-      paneKey: 'tab-1:0',
+      paneKey: TAB_1_PANE_KEY,
       connectionId: 'conn-stale',
       state: 'working',
       receivedAt: 1_700_000_000_100,
@@ -2164,6 +2258,13 @@ describe('useIpcEvents agent status snapshot integration', () => {
       worktreesByRepo: { 'repo-1': [] },
       tabsByWorktree: {
         'wt-1': [{ id: 'tab-1', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Terminal 1' }]
+      },
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: TAB_1_LEAF_ID },
+          activeLeafId: TAB_1_LEAF_ID,
+          expandedLeafId: null
+        }
       }
     })
 
@@ -2187,7 +2288,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     await Promise.resolve()
 
     onSetListenerRef.current?.({
-      paneKey: 'tab-1:0',
+      paneKey: TAB_1_PANE_KEY,
       connectionId: 'conn-other',
       state: 'working',
       receivedAt: 1_700_000_000_100,
@@ -2211,6 +2312,13 @@ describe('useIpcEvents agent status snapshot integration', () => {
       },
       tabsByWorktree: {
         'wt-1': [{ id: 'tab-1', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Terminal 1' }]
+      },
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: TAB_1_LEAF_ID },
+          activeLeafId: TAB_1_LEAF_ID,
+          expandedLeafId: null
+        }
       }
     })
 
@@ -2234,7 +2342,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     await Promise.resolve()
 
     onSetListenerRef.current?.({
-      paneKey: 'tab-1:0',
+      paneKey: TAB_1_PANE_KEY,
       state: 'working',
       receivedAt: 1_700_000_000_100,
       stateStartedAt: 1_699_999_999_100
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index 53cf19d7327..fdeedcf3608 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -34,7 +34,10 @@ import { setDriverForPty, hydrateDrivers } from '@/lib/pane-manager/mobile-drive
 import { destroyPersistentWebview } from '@/components/browser-pane/webview-registry'
 import { attachMobileMarkdownBridge } from '@/runtime/mobile-markdown-bridge'
 import { detectLanguage } from '@/lib/language-detect'
+import { parsePaneKey } from '../../../shared/stable-pane-id'
+import { collectLeafIdsInOrder } from '@/components/terminal-pane/layout-serialization'
 import { track } from '@/lib/telemetry'
+import { singlePaneLayoutSnapshot } from '@/store/slices/terminal-helpers'
 
 export { resolveZoomTarget } from './resolve-zoom-target'
 
@@ -276,7 +279,7 @@ export function useIpcEvents(): void {
 
     unsubs.push(
       window.api.ui.onCreateTerminal(
-        ({ requestId, worktreeId, command, title, ptyId, activate, tabId }) => {
+        ({ requestId, worktreeId, command, title, ptyId, activate, tabId, leafId }) => {
           try {
             if (isRuntimeEnvironmentActive()) {
               if (requestId) {
@@ -308,17 +311,15 @@ export function useIpcEvents(): void {
                   initialPtyId: ptyId,
                   activate: shouldActivate,
                   // Why: tabId hint comes from CLI-spawned PTYs whose env
-                  // already has paneKey=`${tabId}:1` baked in. Adopting the
-                  // tab under the same id keeps hook-event attribution working;
-                  // see docs/cli-terminal-hook-pane-key.md.
+                  // already has the pane key baked in. Adopting the tab under
+                  // the same id keeps hook-event attribution working.
                   ...(tabId !== undefined ? { id: tabId } : {})
                 }))
               : store.createTab(worktreeId)
             // Why: when an existing tab already owns this ptyId, we reuse it instead of
-            // minting a new one — but the PTY env already carries `paneKey=`${tabId}:1``
-            // from main. If the existing tab id doesn't match the hint, hook attribution
-            // will degrade for that PTY's lifetime. Warn so this is visible during
-            // development; in production this surfaces via `agent_hook_unattributed`.
+            // minting a new one — but the PTY env already carries a paneKey from main.
+            // If the existing tab id doesn't match the hint, hook attribution degrades
+            // for that PTY's lifetime. Warn so this is visible during development.
             if (tabId !== undefined && tab.id !== tabId) {
               console.warn(
                 `[onCreateTerminal] tabId hint ${tabId} ignored for ptyId ${ptyId}; existing tab ${tab.id} adopted instead (hook attribution will degrade for this terminal)`
@@ -332,6 +333,12 @@ export function useIpcEvents(): void {
             if (title) {
               store.setTabCustomTitle(tab.id, title)
             }
+            if (leafId && ptyId) {
+              // Why: CLI/runtime-spawned PTYs emit hook events before a hidden
+              // tab mounts TerminalPane, so the adopted UUID leaf must exist
+              // in layout state for paneKey validation to accept them.
+              store.setTabLayout(tab.id, singlePaneLayoutSnapshot(leafId, ptyId, title))
+            }
             if (command) {
               store.queueTabStartupCommand(tab.id, { command })
             }
@@ -455,7 +462,7 @@ export function useIpcEvents(): void {
         store.setActiveTab(tabId)
         store.revealWorktreeInSidebar(worktreeId)
         if (!focusRuntimeTerminalSurface(tabId, leafId)) {
-          focusTerminalTabSurface(tabId)
+          focusTerminalTabSurface(tabId, leafId)
         }
       })
     )
@@ -1178,6 +1185,22 @@ export function useIpcEvents(): void {
           for (const entry of entries) {
             applyAgentStatus(entry, { replay: true })
           }
+          const getMigrationUnsupportedSnapshot =
+            window.api.agentStatus.getMigrationUnsupportedSnapshot
+          if (typeof getMigrationUnsupportedSnapshot !== 'function') {
+            return
+          }
+          void getMigrationUnsupportedSnapshot().then((unsupportedEntries) => {
+            const unsupportedStore = useAppStore.getState()
+            if (!unsupportedStore.workspaceSessionReady) {
+              return
+            }
+            for (const entry of unsupportedEntries) {
+              if (entry.paneKey && resolvePaneKey(unsupportedStore, entry.paneKey).exists) {
+                unsupportedStore.setMigrationUnsupportedPty(entry)
+              }
+            }
+          })
         })
         .catch((err) => {
           // Why: keep snapshotRequestedForReadyWindow latched on failure. The
@@ -1196,6 +1219,27 @@ export function useIpcEvents(): void {
         applyAgentStatus(data)
       })
     )
+    const unsubscribeMigrationUnsupported = window.api.agentStatus.onMigrationUnsupported?.(
+      (entry) => {
+        const store = useAppStore.getState()
+        if (!store.workspaceSessionReady) {
+          return
+        }
+        if (entry.paneKey && resolvePaneKey(store, entry.paneKey).exists) {
+          store.setMigrationUnsupportedPty(entry)
+        }
+      }
+    )
+    if (unsubscribeMigrationUnsupported) {
+      unsubs.push(unsubscribeMigrationUnsupported)
+    }
+    const unsubscribeMigrationUnsupportedClear =
+      window.api.agentStatus.onMigrationUnsupportedClear?.(({ ptyId }) => {
+        useAppStore.getState().clearMigrationUnsupportedPty(ptyId)
+      })
+    if (unsubscribeMigrationUnsupportedClear) {
+      unsubs.push(unsubscribeMigrationUnsupportedClear)
+    }
 
     // Why: the main hook server is the durable source of truth. Pull a
     // snapshot only after workspace tabs are ready, so early startup pushes
@@ -1291,7 +1335,7 @@ export function useIpcEvents(): void {
   }, [])
 }
 
-/** Resolve a paneKey (tabId:paneId) to a liveness check, the current terminal
+/** Resolve a paneKey (tabId:leafId) to both a liveness check and the current
  *  title, and the connectionId of the repo that owns the pane's worktree.
  *  Walks tabsByWorktree to locate the tab, then resolves the owning worktree
  *  and repo via cached selector maps. Used for agent type inference when the
@@ -1306,16 +1350,19 @@ function resolvePaneKey(
   store: ReturnType<typeof useAppStore.getState>,
   paneKey: string
 ): { exists: boolean; title: string | undefined; repoConnectionId: string | null } {
-  const [tabId, paneIdRaw] = paneKey.split(':')
-  if (!tabId) {
+  const parsed = parsePaneKey(paneKey)
+  if (!parsed) {
     return { exists: false, title: undefined, repoConnectionId: null }
   }
-  // Why: split panes track per-pane titles in runtimePaneTitlesByTabId; prefer
-  // the pane's own title over the tab-level (last-winning) title so agent type
-  // inference attributes status to the correct pane.
-  const paneTitles = store.runtimePaneTitlesByTabId?.[tabId]
-  const paneIdNum = paneIdRaw !== undefined ? Number(paneIdRaw) : NaN
-  const rawPaneTitle = paneTitles && !Number.isNaN(paneIdNum) ? paneTitles[paneIdNum] : undefined
+  const { tabId, leafId } = parsed
+  const layout = store.terminalLayoutsByTabId?.[tabId]
+  const leafExists = collectLeafIdsInOrder(layout?.root).includes(leafId)
+  if (!leafExists) {
+    return { exists: false, title: undefined, repoConnectionId: null }
+  }
+  // Why: replay can remint numeric pane ids, so status title recovery must use
+  // persisted leaf-keyed titles when crossing from hook state into tab state.
+  const rawPaneTitle = layout?.titlesByLeafId?.[leafId]
   // Why: treat an empty-string paneTitle as "no title" so the tab-level
   // fallback still fires. `paneTitle ?? tabTitle` alone would short-circuit on
   // '' and also erase any previously-cached terminalTitle in the store
diff --git a/src/renderer/src/lib/activate-tab-and-focus-pane.ts b/src/renderer/src/lib/activate-tab-and-focus-pane.ts
index 864b62928a0..2a8ef07106a 100644
--- a/src/renderer/src/lib/activate-tab-and-focus-pane.ts
+++ b/src/renderer/src/lib/activate-tab-and-focus-pane.ts
@@ -1,17 +1,26 @@
 import { useAppStore } from '@/store'
 import { FOCUS_TERMINAL_PANE_EVENT, type FocusTerminalPaneDetail } from '@/constants/terminal'
 
-export function activateTabAndFocusPane(tabId: string, paneId: number | null): void {
+export function activateTabAndFocusPane(
+  tabId: string,
+  leafId: string | null,
+  opts?: { ackPaneKeyOnSuccess?: string }
+): void {
   useAppStore.getState().setActiveTab(tabId)
-  if (paneId === null) {
+  if (leafId === null) {
     return
   }
   // Why: defer one frame so the new TerminalPane has mounted its
   // FOCUS_TERMINAL_PANE_EVENT listener before we dispatch.
   requestAnimationFrame(() => {
+    const detail: FocusTerminalPaneDetail = {
+      tabId,
+      leafId,
+      ...(opts?.ackPaneKeyOnSuccess ? { ackPaneKeyOnSuccess: opts.ackPaneKeyOnSuccess } : {})
+    }
     window.dispatchEvent(
       new CustomEvent<FocusTerminalPaneDetail>(FOCUS_TERMINAL_PANE_EVENT, {
-        detail: { tabId, paneId }
+        detail
       })
     )
   })
diff --git a/src/renderer/src/lib/focus-terminal-tab-surface.ts b/src/renderer/src/lib/focus-terminal-tab-surface.ts
index ab7f9e70f2a..060bd8feff8 100644
--- a/src/renderer/src/lib/focus-terminal-tab-surface.ts
+++ b/src/renderer/src/lib/focus-terminal-tab-surface.ts
@@ -5,16 +5,27 @@
  * double-rAF waits for that commit so focus lands on the new tab instead of
  * whatever surface (menu trigger, body, previous tab) just relinquished it.
  */
-export function focusTerminalTabSurface(tabId: string): void {
+function cssAttributeString(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+export function focusTerminalTabSurface(tabId: string, leafId?: string | null): void {
   requestAnimationFrame(() => {
     requestAnimationFrame(() => {
-      const scoped = document.querySelector(
-        `[data-terminal-tab-id="${tabId}"] .xterm-helper-textarea`
-      ) as HTMLElement | null
+      const escapedTabId = cssAttributeString(tabId)
+      const scopedSelector = leafId
+        ? `[data-terminal-tab-id="${escapedTabId}"] [data-leaf-id="${cssAttributeString(leafId)}"] .xterm-helper-textarea`
+        : `[data-terminal-tab-id="${escapedTabId}"] .xterm-helper-textarea`
+      const scoped = document.querySelector(scopedSelector) as HTMLElement | null
       if (scoped) {
         scoped.focus()
         return
       }
+      if (leafId) {
+        // Why: exact mobile split-pane focus must not silently focus a sibling
+        // pane when the requested UUID leaf has not mounted yet.
+        return
+      }
       const fallback = document.querySelector('.xterm-helper-textarea') as HTMLElement | null
       fallback?.focus()
     })
diff --git a/src/renderer/src/lib/launch-agent-background-session.test.ts b/src/renderer/src/lib/launch-agent-background-session.test.ts
index d8a13516bb2..af5e113cf45 100644
--- a/src/renderer/src/lib/launch-agent-background-session.test.ts
+++ b/src/renderer/src/lib/launch-agent-background-session.test.ts
@@ -13,10 +13,23 @@ const mockCreateTab = vi.fn()
 const mockSetTabCustomTitle = vi.fn()
 const mockUpdateTabPtyId = vi.fn()
 const mockCloseTab = vi.fn()
+const mockSetTabLayout = vi.fn()
 const mockRegisterEagerPtyBuffer = vi.fn()
 const mockSubscribeToPtyData = vi.fn()
 const mockSubscribeToPtyExit = vi.fn()
 const mockPasteDraftWhenAgentReady = vi.fn()
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+function expectStablePaneSpawn(): string {
+  const spawnArgs = mockSpawn.mock.calls[0]?.[0]
+  const paneKey = spawnArgs?.env?.ORCA_PANE_KEY
+  const leafId = spawnArgs?.leafId
+  expect(typeof paneKey).toBe('string')
+  expect(typeof leafId).toBe('string')
+  expect(leafId).toMatch(UUID_RE)
+  expect(paneKey).toBe(`tab-1:${leafId}`)
+  return paneKey
+}
 
 const state = {
   settings: { agentCmdOverrides: {}, activeRuntimeEnvironmentId: null as string | null },
@@ -28,6 +41,7 @@ const state = {
   setTabCustomTitle: mockSetTabCustomTitle,
   updateTabPtyId: mockUpdateTabPtyId,
   closeTab: mockCloseTab,
+  setTabLayout: mockSetTabLayout,
   clearTabPtyId: vi.fn(),
   setAgentStatus: vi.fn()
 }
@@ -108,15 +122,24 @@ describe('launchAgentBackgroundSession', () => {
       expect.objectContaining({
         cwd: '/repo/worktree',
         command: "claude 'run the automation'",
-        env: {
-          ORCA_PANE_KEY: 'tab-1:1',
+        env: expect.objectContaining({
           ORCA_TAB_ID: 'tab-1',
           ORCA_WORKTREE_ID: 'wt-1'
-        },
+        }),
         connectionId: null,
         worktreeId: 'wt-1',
-        tabId: 'tab-1',
-        leafId: 'pane:1'
+        tabId: 'tab-1'
+      })
+    )
+    const paneKey = expectStablePaneSpawn()
+    const leafId = paneKey.slice('tab-1:'.length)
+    expect(mockSetTabLayout).toHaveBeenCalledWith(
+      'tab-1',
+      expect.objectContaining({
+        root: { type: 'leaf', leafId },
+        activeLeafId: leafId,
+        ptyIdsByLeafId: { [leafId]: 'pty-1' },
+        titlesByLeafId: { [leafId]: 'Nightly audit' }
       })
     )
     expect(mockSetTabCustomTitle).toHaveBeenCalledWith('tab-1', 'Nightly audit')
@@ -141,8 +164,9 @@ describe('launchAgentBackgroundSession', () => {
     const dataSidecar = mockSubscribeToPtyData.mock.calls[0]?.[1] as (data: string) => void
     dataSidecar('\x1b]9999;{"state":"done","prompt":"ok","agentType":"codex"}\x07')
 
+    const paneKey = expectStablePaneSpawn()
     expect(state.setAgentStatus).toHaveBeenCalledWith(
-      'tab-1:1',
+      paneKey,
       expect.objectContaining({ state: 'done', prompt: 'ok', agentType: 'codex' }),
       undefined
     )
@@ -219,6 +243,18 @@ describe('launchAgentBackgroundSession', () => {
     })
 
     expect(mockSpawn).not.toHaveBeenCalled()
+    const params = mockRuntimeEnvironmentCall.mock.calls[0]?.[0]?.params
+    const paneKey = params?.env?.ORCA_PANE_KEY
+    const leafId = typeof paneKey === 'string' ? paneKey.slice('tab-1:'.length) : ''
+    expect(leafId).toMatch(UUID_RE)
+    expect(mockSetTabLayout).toHaveBeenCalledWith(
+      'tab-1',
+      expect.objectContaining({
+        root: { type: 'leaf', leafId },
+        activeLeafId: leafId,
+        ptyIdsByLeafId: { [leafId]: 'remote:env-1@@terminal-1' }
+      })
+    )
     expect(mockRuntimeEnvironmentCall).toHaveBeenCalledWith({
       selector: 'env-1',
       method: 'terminal.create',
@@ -226,10 +262,12 @@ describe('launchAgentBackgroundSession', () => {
         worktree: 'wt-1',
         command: "claude 'run the automation'",
         env: expect.objectContaining({
-          ORCA_PANE_KEY: 'tab-1:1',
+          ORCA_PANE_KEY: `tab-1:${leafId}`,
           ORCA_TAB_ID: 'tab-1',
           ORCA_WORKTREE_ID: 'wt-1'
         }),
+        tabId: 'tab-1',
+        leafId,
         focus: false
       }),
       timeoutMs: 15_000
diff --git a/src/renderer/src/lib/launch-agent-background-session.ts b/src/renderer/src/lib/launch-agent-background-session.ts
index 710a0b5779d..6240ad8b19f 100644
--- a/src/renderer/src/lib/launch-agent-background-session.ts
+++ b/src/renderer/src/lib/launch-agent-background-session.ts
@@ -7,7 +7,7 @@ import { pasteDraftWhenAgentReady } from '@/lib/agent-paste-draft'
 import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
 import type { TuiAgent } from '../../../shared/types'
 import type { LaunchSource } from '../../../shared/telemetry-events'
-import { FIRST_PANE_ID } from '../../../shared/pane-key'
+import { makePaneKey } from '../../../shared/stable-pane-id'
 import {
   registerEagerPtyBuffer,
   subscribeToPtyData,
@@ -15,6 +15,7 @@ import {
 } from '@/components/terminal-pane/pty-dispatcher'
 import { createAgentStatusOscProcessor } from '@/components/terminal-pane/agent-status-osc'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import { singlePaneLayoutSnapshot } from '@/store/slices/terminal-helpers'
 import {
   getRemoteRuntimeTerminalHandle,
   subscribeToRuntimeTerminalData,
@@ -84,9 +85,11 @@ export async function launchAgentBackgroundSession(
   if (title) {
     store.setTabCustomTitle(tab.id, title)
   }
-  const paneKey = `${tab.id}:${FIRST_PANE_ID}`
   // Why: agent hook callbacks are keyed by pane, and background automation
   // tabs never mount a TerminalPane to inject this env for us.
+  const leafId = globalThis.crypto.randomUUID()
+  const paneKey = makePaneKey(tab.id, leafId)
+  store.setTabLayout(tab.id, singlePaneLayoutSnapshot(leafId, undefined, title))
   const paneEnv = {
     ...startupPlan.env,
     ORCA_PANE_KEY: paneKey,
@@ -107,6 +110,8 @@ export async function launchAgentBackgroundSession(
           command: startupPlan.launchCommand,
           env: paneEnv,
           title,
+          tabId: tab.id,
+          leafId,
           focus: false
         },
         { timeoutMs: 15_000 }
@@ -122,7 +127,7 @@ export async function launchAgentBackgroundSession(
         connectionId: repo?.connectionId ?? null,
         worktreeId,
         tabId: tab.id,
-        leafId: 'pane:1',
+        leafId,
         telemetry: {
           agent_kind: tuiAgentToAgentKind(agent),
           launch_source: launchSource ?? 'unknown',
@@ -136,6 +141,7 @@ export async function launchAgentBackgroundSession(
     throw error
   }
   store.updateTabPtyId(tab.id, ptyId)
+  store.setTabLayout(tab.id, singlePaneLayoutSnapshot(leafId, ptyId, title))
   let exitHandled = false
   let unsubscribeExit = (): void => {}
   let unsubscribeData = (): void => {}
diff --git a/src/renderer/src/lib/migration-unsupported-agent-entry.ts b/src/renderer/src/lib/migration-unsupported-agent-entry.ts
new file mode 100644
index 00000000000..5f3e83496c9
--- /dev/null
+++ b/src/renderer/src/lib/migration-unsupported-agent-entry.ts
@@ -0,0 +1,27 @@
+import type {
+  AgentStatusEntry,
+  MigrationUnsupportedPtyEntry
+} from '../../../shared/agent-status-types'
+
+export function migrationUnsupportedToAgentStatusEntry(
+  entry: MigrationUnsupportedPtyEntry
+): AgentStatusEntry | null {
+  if (!entry.paneKey) {
+    return null
+  }
+  const now = Date.now()
+  return {
+    state: 'blocked',
+    prompt: 'Agent unavailable after pane identity migration',
+    // Why: this is a persistent migration block, not a hook heartbeat. Keep it
+    // fresh while present so normal stale-status decay does not hide it.
+    updatedAt: Math.max(entry.updatedAt, now),
+    stateStartedAt: entry.updatedAt,
+    agentType: 'unknown',
+    paneKey: entry.paneKey,
+    terminalTitle: 'Migration unsupported',
+    stateHistory: [],
+    lastAssistantMessage:
+      'Restart this terminal so Orca can attach a stable UUID pane key to agent hooks.'
+  }
+}
diff --git a/src/renderer/src/lib/pane-manager/mint-stable-pane-id.ts b/src/renderer/src/lib/pane-manager/mint-stable-pane-id.ts
new file mode 100644
index 00000000000..10f332f49ac
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/mint-stable-pane-id.ts
@@ -0,0 +1,25 @@
+import type { TerminalLeafId } from '../../../../shared/stable-pane-id'
+
+// Why: Electron/test runtimes can lack crypto.randomUUID. The fallback still
+// produces a UUID-shaped v4 id so pane-key validation remains deterministic.
+export function mintStablePaneId(): TerminalLeafId {
+  const cryptoApi = globalThis.crypto as Crypto | undefined
+  if (cryptoApi?.randomUUID) {
+    return cryptoApi.randomUUID() as TerminalLeafId
+  }
+  const bytes = new Uint8Array(16)
+  if (cryptoApi?.getRandomValues) {
+    cryptoApi.getRandomValues(bytes)
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) {
+      bytes[i] = Math.floor(Math.random() * 256)
+    }
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x40
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(
+    16,
+    20
+  )}-${hex.slice(20)}` as TerminalLeafId
+}
diff --git a/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts b/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
index 17b26a7805d..3ab4937c4d2 100644
--- a/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
+++ b/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
@@ -10,9 +10,13 @@ type FitOverride = {
 }
 
 const overridesByPtyId = new Map<string, FitOverride>()
-// Why: keyed by 'tabId:paneId' composite to avoid collisions when different
-// tabs have panes with the same numeric ID (pane IDs are per-tab, not global).
-const ptyIdByPaneKey = new Map<string, string>()
+// Why: this is an in-memory renderer fit binding, not an agent paneKey.
+// Numeric pane ids are valid here because fit overrides never cross replay.
+const ptyIdByFitBindingKey = new Map<string, string>()
+
+function fitBindingKey(tabId: string, paneId: number): string {
+  return `${tabId}:${paneId}`
+}
 
 // Why: the override maps are plain JS — React components that read them
 // (e.g. the desktop mobile-fit banner) have no way to know when entries
@@ -69,7 +73,7 @@ export function setFitOverride(
 
 export function getPaneIdsForPty(ptyId: string): number[] {
   const result: number[] = []
-  for (const [key, boundPtyId] of ptyIdByPaneKey) {
+  for (const [key, boundPtyId] of ptyIdByFitBindingKey) {
     if (boundPtyId === ptyId) {
       const paneId = Number(key.split(':').pop())
       if (!Number.isNaN(paneId)) {
@@ -86,7 +90,7 @@ export function getFitOverrideForPty(ptyId: string): FitOverride | null {
 
 export function getFitOverrideForPane(paneId: number, tabId?: string): FitOverride | null {
   if (tabId) {
-    const ptyId = ptyIdByPaneKey.get(`${tabId}:${paneId}`)
+    const ptyId = ptyIdByFitBindingKey.get(fitBindingKey(tabId, paneId))
     if (!ptyId) {
       return null
     }
@@ -97,18 +101,18 @@ export function getFitOverrideForPane(paneId: number, tabId?: string): FitOverri
 
 export function bindPanePtyId(paneId: number, ptyId: string | null, tabId?: string): void {
   if (tabId) {
-    const key = `${tabId}:${paneId}`
+    const key = fitBindingKey(tabId, paneId)
     if (ptyId) {
-      ptyIdByPaneKey.set(key, ptyId)
+      ptyIdByFitBindingKey.set(key, ptyId)
     } else {
-      ptyIdByPaneKey.delete(key)
+      ptyIdByFitBindingKey.delete(key)
     }
   }
 }
 
 export function unbindPane(paneId: number, tabId?: string): void {
   if (tabId) {
-    ptyIdByPaneKey.delete(`${tabId}:${paneId}`)
+    ptyIdByFitBindingKey.delete(fitBindingKey(tabId, paneId))
   }
 }
 
diff --git a/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts b/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts
index 2085a3fa407..acd20726e5e 100644
--- a/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-fit-resize-observer.test.ts
@@ -33,8 +33,11 @@ function flushAnimationFrames(timestamp = 16): void {
 }
 
 function createPane(): ManagedPaneInternal {
+  const leafId = '11111111-1111-4111-8111-111111111111' as never
   return {
     id: 1,
+    leafId,
+    stablePaneId: leafId,
     terminal: {
       cols: 79,
       rows: 24
diff --git a/src/renderer/src/lib/pane-manager/pane-identity-registry.ts b/src/renderer/src/lib/pane-manager/pane-identity-registry.ts
new file mode 100644
index 00000000000..0c1951e979f
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-identity-registry.ts
@@ -0,0 +1,79 @@
+import { isTerminalLeafId, type TerminalLeafId } from '../../../../shared/stable-pane-id'
+import { mintStablePaneId } from './mint-stable-pane-id'
+import type { ManagedPaneInternal } from './pane-manager-types'
+
+export class PaneIdentityRegistry {
+  private leafIdByNumericId: Map<number, TerminalLeafId> = new Map()
+  private numericIdByLeafId: Map<TerminalLeafId, number> = new Map()
+  private publishedPaneIds: Set<number> = new Set()
+
+  claimLeafId(leafIdHint?: string): TerminalLeafId {
+    if (leafIdHint && isTerminalLeafId(leafIdHint) && !this.numericIdByLeafId.has(leafIdHint)) {
+      return leafIdHint
+    }
+    return this.mintUnclaimedLeafId()
+  }
+
+  register(numericPaneId: number, leafId: TerminalLeafId): void {
+    this.leafIdByNumericId.set(numericPaneId, leafId)
+    this.numericIdByLeafId.set(leafId, numericPaneId)
+  }
+
+  release(numericPaneId: number): void {
+    const leafId = this.leafIdByNumericId.get(numericPaneId)
+    if (leafId) {
+      this.numericIdByLeafId.delete(leafId)
+    }
+    this.leafIdByNumericId.delete(numericPaneId)
+    this.publishedPaneIds.delete(numericPaneId)
+  }
+
+  markPublished(numericPaneId: number): void {
+    this.publishedPaneIds.add(numericPaneId)
+  }
+
+  getLeafId(numericPaneId: number): TerminalLeafId | null {
+    return this.leafIdByNumericId.get(numericPaneId) ?? null
+  }
+
+  getNumericIdForLeaf(leafId: string): number | null {
+    if (!isTerminalLeafId(leafId)) {
+      return null
+    }
+    return this.numericIdByLeafId.get(leafId) ?? null
+  }
+
+  getLeafIdMap(): Map<number, TerminalLeafId> {
+    return new Map(this.leafIdByNumericId)
+  }
+
+  adoptPaneLeafId(numericPaneId: number, pane: ManagedPaneInternal, leafId: string): boolean {
+    if (!isTerminalLeafId(leafId) || this.publishedPaneIds.has(numericPaneId)) {
+      return false
+    }
+    const existingOwner = this.numericIdByLeafId.get(leafId)
+    if (existingOwner !== undefined && existingOwner !== numericPaneId) {
+      return false
+    }
+    this.numericIdByLeafId.delete(pane.leafId)
+    this.register(numericPaneId, leafId)
+    pane.leafId = leafId
+    pane.stablePaneId = leafId
+    pane.container.dataset.leafId = leafId
+    return true
+  }
+
+  clear(): void {
+    this.leafIdByNumericId.clear()
+    this.numericIdByLeafId.clear()
+    this.publishedPaneIds.clear()
+  }
+
+  private mintUnclaimedLeafId(): TerminalLeafId {
+    let leafId: TerminalLeafId
+    do {
+      leafId = mintStablePaneId()
+    } while (this.numericIdByLeafId.has(leafId))
+    return leafId
+  }
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-key-resolution.test.ts b/src/renderer/src/lib/pane-manager/pane-key-resolution.test.ts
new file mode 100644
index 00000000000..d75f89c9eb8
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-key-resolution.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
+import type { ManagedPane } from './pane-manager-types'
+import { resolveLeafIdForManager, resolvePaneKeyForManager } from './pane-key-resolution'
+
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const OTHER_LEAF_ID = '22222222-2222-4222-8222-222222222222'
+const PANE_KEY = makePaneKey('tab-1', LEAF_ID)
+
+function makeManager(args: {
+  numericPaneId: number | null
+  panes: Pick<ManagedPane, 'id' | 'leafId'>[]
+}) {
+  return {
+    getNumericIdForLeaf: () => args.numericPaneId,
+    getPanes: () => args.panes as ManagedPane[]
+  }
+}
+
+describe('pane-key resolution', () => {
+  it('resolves a stable pane key to the current numeric pane id', () => {
+    const manager = makeManager({
+      numericPaneId: 7,
+      panes: [{ id: 7, leafId: LEAF_ID as never }]
+    })
+
+    expect(resolvePaneKeyForManager('tab-1', PANE_KEY, manager)).toEqual({
+      status: 'resolved',
+      paneKey: PANE_KEY,
+      leafId: LEAF_ID,
+      numericPaneId: 7
+    })
+  })
+
+  it('rejects malformed, legacy numeric, and wrong-tab pane keys as invalid', () => {
+    const manager = makeManager({
+      numericPaneId: 1,
+      panes: [{ id: 1, leafId: LEAF_ID as never }]
+    })
+
+    expect(resolvePaneKeyForManager('tab-1', 'tab-1:1', manager)).toMatchObject({
+      status: 'unresolved',
+      reason: 'invalid'
+    })
+    expect(resolvePaneKeyForManager('tab-1', makePaneKey('tab-2', LEAF_ID), manager)).toMatchObject(
+      {
+        status: 'unresolved',
+        reason: 'invalid'
+      }
+    )
+  })
+
+  it('reports confirmed-missing when the committed leaf has no live pane', () => {
+    const manager = makeManager({ numericPaneId: null, panes: [] })
+
+    expect(resolvePaneKeyForManager('tab-1', PANE_KEY, manager)).toEqual({
+      status: 'unresolved',
+      paneKey: PANE_KEY,
+      leafId: LEAF_ID,
+      reason: 'confirmed-missing'
+    })
+  })
+
+  it('reports ownership-mismatch when the numeric pane handle now belongs to another leaf', () => {
+    const manager = makeManager({
+      numericPaneId: 7,
+      panes: [{ id: 7, leafId: OTHER_LEAF_ID as never }]
+    })
+
+    expect(resolveLeafIdForManager('tab-1', LEAF_ID, manager, PANE_KEY)).toEqual({
+      status: 'unresolved',
+      paneKey: PANE_KEY,
+      leafId: LEAF_ID,
+      reason: 'ownership-mismatch'
+    })
+  })
+})
diff --git a/src/renderer/src/lib/pane-manager/pane-key-resolution.ts b/src/renderer/src/lib/pane-manager/pane-key-resolution.ts
new file mode 100644
index 00000000000..a8ebe9094f0
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-key-resolution.ts
@@ -0,0 +1,70 @@
+import {
+  isTerminalLeafId,
+  parsePaneKey,
+  type TerminalLeafId
+} from '../../../../shared/stable-pane-id'
+import type { ManagedPane } from './pane-manager-types'
+
+export type PaneKeyUnresolvedReason = 'confirmed-missing' | 'ownership-mismatch' | 'invalid'
+
+export type PaneKeyResolution =
+  | {
+      status: 'resolved'
+      paneKey: string
+      leafId: TerminalLeafId
+      numericPaneId: number
+    }
+  | {
+      status: 'unresolved'
+      paneKey: string | null
+      leafId: TerminalLeafId | null
+      reason: PaneKeyUnresolvedReason
+    }
+
+export type PaneKeyResolutionManager = {
+  getNumericIdForLeaf(leafId: string): number | null
+  getPanes(): ManagedPane[]
+}
+
+export function resolvePaneKeyForManager(
+  tabId: string,
+  paneKey: string,
+  manager: PaneKeyResolutionManager | null
+): PaneKeyResolution {
+  const parsed = parsePaneKey(paneKey)
+  if (!parsed || parsed.tabId !== tabId) {
+    return { status: 'unresolved', paneKey, leafId: parsed?.leafId ?? null, reason: 'invalid' }
+  }
+  return resolveLeafIdForManager(tabId, parsed.leafId, manager, paneKey)
+}
+
+export function resolveLeafIdForManager(
+  tabId: string,
+  leafId: string,
+  manager: PaneKeyResolutionManager | null,
+  paneKey: string | null = null
+): PaneKeyResolution {
+  if (!isTerminalLeafId(leafId)) {
+    return { status: 'unresolved', paneKey, leafId: null, reason: 'invalid' }
+  }
+  if (!manager) {
+    return { status: 'unresolved', paneKey, leafId, reason: 'confirmed-missing' }
+  }
+
+  const numericPaneId = manager.getNumericIdForLeaf(leafId)
+  if (numericPaneId === null) {
+    return { status: 'unresolved', paneKey, leafId, reason: 'confirmed-missing' }
+  }
+
+  const pane = manager.getPanes().find((candidate) => candidate.id === numericPaneId)
+  if (!pane) {
+    return { status: 'unresolved', paneKey, leafId, reason: 'confirmed-missing' }
+  }
+  if (pane.leafId !== leafId) {
+    // Why: numeric pane ids can be reused after replay/teardown. The stable
+    // leaf must still match at the moment the caller needs a live handle.
+    return { status: 'unresolved', paneKey, leafId, reason: 'ownership-mismatch' }
+  }
+
+  return { status: 'resolved', paneKey: paneKey ?? `${tabId}:${leafId}`, leafId, numericPaneId }
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-lifecycle.test.ts b/src/renderer/src/lib/pane-manager/pane-lifecycle.test.ts
index ec9fcf177e9..aff38ce3e45 100644
--- a/src/renderer/src/lib/pane-manager/pane-lifecycle.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-lifecycle.test.ts
@@ -26,8 +26,11 @@ vi.mock('@xterm/addon-webgl', () => ({
 }))
 
 function createPane(): ManagedPaneInternal {
+  const leafId = '11111111-1111-4111-8111-111111111111' as never
   return {
     id: 1,
+    leafId,
+    stablePaneId: leafId,
     terminal: {
       loadAddon: vi.fn(),
       refresh: vi.fn(),
@@ -271,8 +274,11 @@ describe('openTerminal — Unicode 11 ordering', () => {
       buffer: { active: { cursorX: 0, cursorY: 0 } }
     } as unknown as ManagedPaneInternal['terminal']
 
+    const leafId = '22222222-2222-4222-8222-222222222222' as never
     const pane: ManagedPaneInternal = {
       id: 1,
+      leafId,
+      stablePaneId: leafId,
       terminal,
       container: fakeContainer,
       xtermContainer: fakeContainer,
diff --git a/src/renderer/src/lib/pane-manager/pane-lifecycle.ts b/src/renderer/src/lib/pane-manager/pane-lifecycle.ts
index f9673b3fa84..3f6eab46f58 100644
--- a/src/renderer/src/lib/pane-manager/pane-lifecycle.ts
+++ b/src/renderer/src/lib/pane-manager/pane-lifecycle.ts
@@ -13,6 +13,7 @@ import { WebLinksAddon } from '@xterm/addon-web-links'
 import { SerializeAddon } from '@xterm/addon-serialize'
 
 import type { PaneManagerOptions, ManagedPaneInternal } from './pane-manager-types'
+import type { TerminalLeafId } from '../../../../shared/stable-pane-id'
 import type { DragReorderState } from './pane-drag-reorder'
 import type { DragReorderCallbacks } from './pane-drag-reorder'
 import { attachPaneDrag } from './pane-drag-reorder'
@@ -36,6 +37,7 @@ function getTerminalUrlOpenHint(): string {
 
 export function createPaneDOM(
   id: number,
+  leafId: TerminalLeafId,
   options: PaneManagerOptions,
   dragState: DragReorderState,
   dragCallbacks: DragReorderCallbacks,
@@ -46,6 +48,7 @@ export function createPaneDOM(
   const container = document.createElement('div')
   container.className = 'pane'
   container.dataset.paneId = String(id)
+  container.dataset.leafId = leafId
 
   // Create .xterm-container — baseline layout (position, width, height, margin)
   // is CSS-driven (see main.css .xterm-container) so that the data-has-title
@@ -102,6 +105,8 @@ export function createPaneDOM(
 
   const pane: ManagedPaneInternal = {
     id,
+    leafId,
+    stablePaneId: leafId,
     terminal,
     container,
     xtermContainer,
diff --git a/src/renderer/src/lib/pane-manager/pane-manager-types.ts b/src/renderer/src/lib/pane-manager/pane-manager-types.ts
index 08d1661f135..f6c02c9e956 100644
--- a/src/renderer/src/lib/pane-manager/pane-manager-types.ts
+++ b/src/renderer/src/lib/pane-manager/pane-manager-types.ts
@@ -8,6 +8,7 @@ import type { WebLinksAddon } from '@xterm/addon-web-links'
 import type { WebglAddon } from '@xterm/addon-webgl'
 import type { SerializeAddon } from '@xterm/addon-serialize'
 import type { GlobalSettings } from '../../../../shared/types'
+import type { TerminalLeafId } from '../../../../shared/stable-pane-id'
 
 // ---------------------------------------------------------------------------
 // Public interfaces
@@ -21,9 +22,14 @@ export type PaneSpawnHints = {
   cwd?: string
 }
 
+export type ClosedPaneInfo = {
+  paneId: number
+  leafId: TerminalLeafId
+}
+
 export type PaneManagerOptions = {
   onPaneCreated?: (pane: ManagedPane, spawnHints?: PaneSpawnHints) => void | Promise<void>
-  onPaneClosed?: (paneId: number) => void
+  onPaneClosed?: (paneId: number, closedPane?: ClosedPaneInfo) => void
   onActivePaneChange?: (pane: ManagedPane) => void
   onLayoutChanged?: () => void
   terminalOptions?: (paneId: number) => Partial<ITerminalOptions>
@@ -54,6 +60,11 @@ export type PaneStyleOptions = {
 
 export type ManagedPane = {
   id: number
+  /** Durable terminal layout leaf UUID. Use this for paneKey/ORCA_PANE_KEY and
+   *  persisted leaf-keyed state; `id` is only the live renderer handle. */
+  leafId: TerminalLeafId
+  /** Compatibility alias while callers migrate from the older stablePaneId name. */
+  stablePaneId: TerminalLeafId
   terminal: Terminal
   container: HTMLElement // the .pane element
   linkTooltip: HTMLElement
diff --git a/src/renderer/src/lib/pane-manager/pane-manager.ts b/src/renderer/src/lib/pane-manager/pane-manager.ts
index 8e1526f79a2..5ead38cc96b 100644
--- a/src/renderer/src/lib/pane-manager/pane-manager.ts
+++ b/src/renderer/src/lib/pane-manager/pane-manager.ts
@@ -11,35 +11,21 @@ import {
   applyPaneOpacity,
   applyRootBackground
 } from './pane-divider'
-import {
-  createDragReorderState,
-  hideDropOverlay,
-  handlePaneDrop,
-  updateMultiPaneState
-} from './pane-drag-reorder'
+import { createDragReorderState, hideDropOverlay, handlePaneDrop } from './pane-drag-reorder'
 import { createPaneDOM, openTerminal, setLigaturesEnabled, disposePane } from './pane-lifecycle'
-import { disposeWebgl } from './pane-webgl-renderer'
 import { shouldFollowMouseFocus } from './focus-follows-mouse'
-import {
-  findPaneChildren,
-  removeDividers,
-  promoteSibling,
-  wrapInSplit,
-  safeFit,
-  fitAllPanesInternal,
-  captureScrollState,
-  refitPanesUnder
-} from './pane-tree-ops'
-import { scheduleSplitScrollRestore } from './pane-split-scroll'
+import { safeFit, fitAllPanesInternal, refitPanesUnder } from './pane-tree-ops'
 import { toPublicPane } from './pane-public-view'
 import { applyTerminalGpuAcceleration } from './pane-terminal-gpu-acceleration'
-import { reattachWebglIfNeeded } from './pane-webgl-reattach'
 import {
   markPaneComplexScriptOutput,
   resumePaneRendering,
   setPaneGpuRenderingState,
   suspendPaneRendering
 } from './pane-rendering-control'
+import type { TerminalLeafId } from '../../../../shared/stable-pane-id'
+import { PaneIdentityRegistry } from './pane-identity-registry'
+import { closeManagedPane, splitManagedPane } from './pane-split-close'
 import { FIRST_PANE_ID } from '../../../../shared/pane-key'
 
 export type { PaneManagerOptions, PaneStyleOptions, ManagedPane, DropZone }
@@ -53,6 +39,7 @@ export class PaneManager {
   private styleOptions: PaneStyleOptions = {}
   private destroyed = false
   private renderingSuspended: boolean
+  private identities = new PaneIdentityRegistry()
 
   // Drag-to-reorder state
   private dragState = createDragReorderState()
@@ -63,8 +50,8 @@ export class PaneManager {
     this.renderingSuspended = options.initialRenderingSuspended === true
   }
 
-  createInitialPane(opts?: { focus?: boolean }): ManagedPane {
-    const pane = this.createPaneInternal()
+  createInitialPane(opts?: { focus?: boolean; leafId?: string }): ManagedPane {
+    const pane = this.createPaneInternal(opts?.leafId)
     Object.assign(pane.container.style, {
       width: '100%',
       height: '100%',
@@ -80,99 +67,48 @@ export class PaneManager {
       pane.terminal.focus()
     }
 
-    void this.options.onPaneCreated?.(toPublicPane(pane))
+    this.publishPaneCreated(pane)
     return toPublicPane(pane)
   }
 
   splitPane(
     paneId: number,
     direction: 'vertical' | 'horizontal',
-    opts?: { ratio?: number; cwd?: string }
+    opts?: { ratio?: number; cwd?: string; leafId?: string }
   ): ManagedPane | null {
-    const existing = this.panes.get(paneId)
-    if (!existing) {
-      return null
-    }
-    const newPane = this.createPaneInternal()
-    const parent = existing.container.parentElement
-    if (!parent) {
-      return null
-    }
-
-    const isVertical = direction === 'vertical'
-    const divider = this.createDividerWrapped(isVertical)
-
-    // Why: wrapInSplit reparents the existing container, resetting scrollTop.
-    const scrollState = captureScrollState(existing.terminal)
-    // Why: lock prevents safeFit/fitAllPanes from restoring scroll during
-    // the async settle window — scheduleSplitScrollRestore owns the restore.
-    existing.pendingSplitScrollState = scrollState
-
-    // Why: DOM reparenting can silently invalidate a WebGL context without
-    // firing contextlost — Chromium reclaims the oldest context near its
-    // ~8–16 limit. Dispose before the move, reattach in the 200ms timer.
-    const hadWebgl = !!existing.webglAddon
-    disposeWebgl(existing)
-
-    wrapInSplit(existing.container, newPane.container, isVertical, divider, opts)
-
-    openTerminal(newPane)
-    this.activePaneId = newPane.id
-    applyPaneOpacity(this.panes.values(), this.activePaneId, this.styleOptions)
-    applyDividerStyles(this.root, this.styleOptions)
-    newPane.terminal?.focus()
-    updateMultiPaneState(this.getDragCallbacks())
-    // Why: forward cwd hint so the new PTY spawns in the source pane's cwd.
-    void this.options.onPaneCreated?.(
-      toPublicPane(newPane),
-      opts?.cwd ? { cwd: opts.cwd } : undefined
-    )
-    this.options.onLayoutChanged?.()
-
-    const reattach = hadWebgl ? reattachWebglIfNeeded : undefined
-    scheduleSplitScrollRestore(
-      (id) => this.panes.get(id),
-      existing.id,
-      scrollState,
-      () => this.destroyed,
-      reattach
-    )
-
-    return toPublicPane(newPane)
+    return splitManagedPane({
+      paneId,
+      direction,
+      opts,
+      panes: this.panes,
+      root: this.root,
+      styleOptions: this.styleOptions,
+      managerOptions: this.options,
+      createPaneInternal: (leafIdHint) => this.createPaneInternal(leafIdHint),
+      createDivider: (isVertical) => this.createDividerWrapped(isVertical),
+      publishPaneCreated: (pane, spawnHints) => this.publishPaneCreated(pane, spawnHints),
+      getDragCallbacks: () => this.getDragCallbacks(),
+      setActivePaneId: (id) => {
+        this.activePaneId = id
+      },
+      isDestroyed: () => this.destroyed
+    })
   }
 
   closePane(paneId: number): void {
-    const pane = this.panes.get(paneId)
-    if (!pane) {
-      return
-    }
-    const paneContainer = pane.container
-    const parent = paneContainer.parentElement
-    if (!parent) {
-      return
-    }
-    disposePane(pane, this.panes)
-    if (parent.classList.contains('pane-split')) {
-      const siblings = findPaneChildren(parent)
-      const sibling = siblings.find((c) => c !== paneContainer) ?? null
-      paneContainer.remove()
-      removeDividers(parent)
-      promoteSibling(sibling, parent, this.root)
-    } else {
-      paneContainer.remove()
-    }
-    if (this.activePaneId === paneId) {
-      const next = this.panes.values().next().value as ManagedPaneInternal | undefined
-      this.activePaneId = next?.id ?? null
-      next?.terminal.focus()
-    }
-    applyPaneOpacity(this.panes.values(), this.activePaneId, this.styleOptions)
-    for (const p of this.panes.values()) {
-      safeFit(p)
-    }
-    updateMultiPaneState(this.getDragCallbacks())
-    this.options.onPaneClosed?.(paneId)
-    this.options.onLayoutChanged?.()
+    closeManagedPane({
+      paneId,
+      activePaneId: this.activePaneId,
+      panes: this.panes,
+      root: this.root,
+      styleOptions: this.styleOptions,
+      managerOptions: this.options,
+      getDragCallbacks: () => this.getDragCallbacks(),
+      releasePaneIdentity: (numericPaneId) => this.identities.release(numericPaneId),
+      setActivePaneId: (id) => {
+        this.activePaneId = id
+      }
+    })
   }
 
   getPanes(): ManagedPane[] {
@@ -191,6 +127,26 @@ export class PaneManager {
     return pane ? toPublicPane(pane) : null
   }
 
+  getLeafId(numericPaneId: number): TerminalLeafId | null {
+    return this.identities.getLeafId(numericPaneId)
+  }
+
+  getNumericIdForLeaf(leafId: string): number | null {
+    return this.identities.getNumericIdForLeaf(leafId)
+  }
+
+  getLeafIdMap(): Map<number, TerminalLeafId> {
+    return this.identities.getLeafIdMap()
+  }
+
+  adoptLeafId(numericPaneId: number, leafId: string): boolean {
+    const pane = this.panes.get(numericPaneId)
+    if (!pane) {
+      return false
+    }
+    return this.identities.adoptPaneLeafId(numericPaneId, pane, leafId)
+  }
+
   setActivePane(paneId: number, opts?: { focus?: boolean }): void {
     const pane = this.panes.get(paneId)
     if (!pane) {
@@ -256,14 +212,17 @@ export class PaneManager {
     for (const pane of this.panes.values()) {
       disposePane(pane, this.panes)
     }
+    this.identities.clear()
     this.root.innerHTML = ''
     this.activePaneId = null
   }
 
-  private createPaneInternal(): ManagedPaneInternal {
+  private createPaneInternal(leafIdHint?: string): ManagedPaneInternal {
     const id = this.nextPaneId++
+    const leafId = this.identities.claimLeafId(leafIdHint)
     const pane = createPaneDOM(
       id,
+      leafId,
       this.options,
       this.dragState,
       this.getDragCallbacks(),
@@ -280,9 +239,20 @@ export class PaneManager {
     )
     pane.webglAttachmentDeferred = this.renderingSuspended
     this.panes.set(id, pane)
+    this.identities.register(id, leafId)
     return pane
   }
 
+  private publishPaneCreated(
+    pane: ManagedPaneInternal,
+    spawnHints?: Parameters<NonNullable<PaneManagerOptions['onPaneCreated']>>[1]
+  ): void {
+    // Why: onPaneCreated wires PTY/status identity synchronously. After this
+    // point, replacing the leaf id would fork ORCA_PANE_KEY from layout state.
+    this.identities.markPublished(pane.id)
+    void this.options.onPaneCreated?.(toPublicPane(pane), spawnHints)
+  }
+
   private handlePaneMouseEnter(paneId: number, event: MouseEvent): void {
     if (
       shouldFollowMouseFocus({
diff --git a/src/renderer/src/lib/pane-manager/pane-public-view.ts b/src/renderer/src/lib/pane-manager/pane-public-view.ts
index c0ae326b386..578f69a49fc 100644
--- a/src/renderer/src/lib/pane-manager/pane-public-view.ts
+++ b/src/renderer/src/lib/pane-manager/pane-public-view.ts
@@ -3,6 +3,8 @@ import type { ManagedPane, ManagedPaneInternal } from './pane-manager-types'
 export function toPublicPane(pane: ManagedPaneInternal): ManagedPane {
   return {
     id: pane.id,
+    leafId: pane.leafId,
+    stablePaneId: pane.stablePaneId,
     terminal: pane.terminal,
     container: pane.container,
     linkTooltip: pane.linkTooltip,
diff --git a/src/renderer/src/lib/pane-manager/pane-split-close.ts b/src/renderer/src/lib/pane-manager/pane-split-close.ts
new file mode 100644
index 00000000000..52a20f149a9
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-split-close.ts
@@ -0,0 +1,154 @@
+import type {
+  ManagedPane,
+  ManagedPaneInternal,
+  PaneManagerOptions,
+  PaneStyleOptions
+} from './pane-manager-types'
+import type { DragReorderCallbacks } from './pane-drag-reorder'
+import { updateMultiPaneState } from './pane-drag-reorder'
+import {
+  captureScrollState,
+  findPaneChildren,
+  promoteSibling,
+  removeDividers,
+  safeFit,
+  wrapInSplit
+} from './pane-tree-ops'
+import { applyDividerStyles, applyPaneOpacity } from './pane-divider'
+import { disposePane, openTerminal } from './pane-lifecycle'
+import { disposeWebgl } from './pane-webgl-renderer'
+import { scheduleSplitScrollRestore } from './pane-split-scroll'
+import { reattachWebglIfNeeded } from './pane-webgl-reattach'
+import { toPublicPane } from './pane-public-view'
+
+type SplitManagedPaneArgs = {
+  paneId: number
+  direction: 'vertical' | 'horizontal'
+  opts?: { ratio?: number; cwd?: string; leafId?: string }
+  panes: Map<number, ManagedPaneInternal>
+  root: HTMLElement
+  styleOptions: PaneStyleOptions
+  managerOptions: PaneManagerOptions
+  createPaneInternal: (leafIdHint?: string) => ManagedPaneInternal
+  createDivider: (isVertical: boolean) => HTMLElement
+  publishPaneCreated: (
+    pane: ManagedPaneInternal,
+    spawnHints?: Parameters<NonNullable<PaneManagerOptions['onPaneCreated']>>[1]
+  ) => void
+  getDragCallbacks: () => DragReorderCallbacks
+  setActivePaneId: (paneId: number | null) => void
+  isDestroyed: () => boolean
+}
+
+export function splitManagedPane(args: SplitManagedPaneArgs): ManagedPane | null {
+  const existing = args.panes.get(args.paneId)
+  if (!existing) {
+    return null
+  }
+  const parent = existing.container.parentElement
+  if (!parent) {
+    return null
+  }
+  const newPane = args.createPaneInternal(args.opts?.leafId)
+  const isVertical = args.direction === 'vertical'
+  const divider = args.createDivider(isVertical)
+
+  // Why: wrapInSplit reparents the existing container, resetting scrollTop.
+  const scrollState = captureScrollState(existing.terminal)
+  // Why: lock prevents safeFit/fitAllPanes from restoring scroll during the
+  // async settle window; scheduleSplitScrollRestore owns the restore.
+  existing.pendingSplitScrollState = scrollState
+
+  // Why: DOM reparenting can silently invalidate a WebGL context without
+  // firing contextlost, so dispose before the move and reattach after settle.
+  const hadWebgl = !!existing.webglAddon
+  disposeWebgl(existing)
+
+  wrapInSplit(existing.container, newPane.container, isVertical, divider, args.opts)
+  args.setActivePaneId(newPane.id)
+  openSplitPane(args, newPane, args.opts?.cwd)
+
+  scheduleSplitScrollRestore(
+    (id) => args.panes.get(id),
+    existing.id,
+    scrollState,
+    args.isDestroyed,
+    hadWebgl ? reattachWebglIfNeeded : undefined
+  )
+
+  return toPublicPane(newPane)
+}
+
+function openSplitPane(
+  args: SplitManagedPaneArgs,
+  newPane: ManagedPaneInternal,
+  cwd?: string
+): void {
+  openTerminal(newPane)
+  applyPaneOpacity(args.panes.values(), newPane.id, args.styleOptions)
+  applyDividerStyles(args.root, args.styleOptions)
+  newPane.terminal.focus()
+  updateMultiPaneState(args.getDragCallbacks())
+  // Why: forward cwd hint so the new PTY spawns in the source pane's cwd.
+  args.publishPaneCreated(newPane, cwd ? { cwd } : undefined)
+  args.managerOptions.onLayoutChanged?.()
+}
+
+type CloseManagedPaneArgs = {
+  paneId: number
+  activePaneId: number | null
+  panes: Map<number, ManagedPaneInternal>
+  root: HTMLElement
+  styleOptions: PaneStyleOptions
+  managerOptions: PaneManagerOptions
+  getDragCallbacks: () => DragReorderCallbacks
+  releasePaneIdentity: (numericPaneId: number) => void
+  setActivePaneId: (paneId: number | null) => void
+}
+
+export function closeManagedPane(args: CloseManagedPaneArgs): void {
+  const pane = args.panes.get(args.paneId)
+  if (!pane) {
+    return
+  }
+  const closedLeafId = pane.leafId
+  args.releasePaneIdentity(args.paneId)
+  removePaneContainer(args, pane)
+  const nextActivePaneId = activateReplacementPane(args)
+  applyPaneOpacity(args.panes.values(), nextActivePaneId, args.styleOptions)
+  for (const p of args.panes.values()) {
+    safeFit(p)
+  }
+  updateMultiPaneState(args.getDragCallbacks())
+  args.managerOptions.onPaneClosed?.(args.paneId, { paneId: args.paneId, leafId: closedLeafId })
+  args.managerOptions.onLayoutChanged?.()
+}
+
+function removePaneContainer(args: CloseManagedPaneArgs, pane: ManagedPaneInternal): void {
+  const paneContainer = pane.container
+  const parent = paneContainer.parentElement
+  disposePane(pane, args.panes)
+  if (!parent) {
+    return
+  }
+  if (parent.classList.contains('pane-split')) {
+    const siblings = findPaneChildren(parent)
+    const sibling = siblings.find((c) => c !== paneContainer) ?? null
+    paneContainer.remove()
+    removeDividers(parent)
+    promoteSibling(sibling, parent, args.root)
+  } else {
+    paneContainer.remove()
+  }
+}
+
+function activateReplacementPane(args: CloseManagedPaneArgs): number | null {
+  if (args.activePaneId !== args.paneId) {
+    return args.activePaneId
+  }
+  const next = args.panes.values().next().value as ManagedPaneInternal | undefined
+  const nextActivePaneId = next?.id ?? null
+  args.setActivePaneId(nextActivePaneId)
+  next?.terminal.focus()
+  return nextActivePaneId
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts b/src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts
index 4b059bb2991..4ff8c5eb811 100644
--- a/src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-split-scroll.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { ManagedPaneInternal, ScrollState } from './pane-manager-types'
+import type { TerminalLeafId } from '../../../../shared/stable-pane-id'
 
 const restoreScrollState = vi.hoisted(() => vi.fn())
 
@@ -22,6 +23,8 @@ const alternateScrollState = {
   bufferType: 'alternate'
 } satisfies ScrollState
 
+const TEST_LEAF_ID = '11111111-1111-4111-8111-111111111111' as TerminalLeafId
+
 function createPane(bufferType: 'normal' | 'alternate'): {
   pane: ManagedPaneInternal
   bufferChangeDisposable: { dispose: ReturnType<typeof vi.fn> }
@@ -31,6 +34,8 @@ function createPane(bufferType: 'normal' | 'alternate'): {
   const bufferChangeDisposable = { dispose: vi.fn() }
   const pane: ManagedPaneInternal = {
     id: 1,
+    leafId: TEST_LEAF_ID,
+    stablePaneId: TEST_LEAF_ID,
     terminal: {
       rows: 24,
       refresh: vi.fn(),
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-gpu-acceleration.test.ts b/src/renderer/src/lib/pane-manager/pane-terminal-gpu-acceleration.test.ts
index 509de81571a..c42b6d2af0b 100644
--- a/src/renderer/src/lib/pane-manager/pane-terminal-gpu-acceleration.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-gpu-acceleration.test.ts
@@ -3,8 +3,11 @@ import type { ManagedPaneInternal, PaneManagerOptions } from './pane-manager-typ
 import { applyTerminalGpuAcceleration } from './pane-terminal-gpu-acceleration'
 
 function createPane(): ManagedPaneInternal {
+  const leafId = '11111111-1111-4111-8111-111111111111' as never
   return {
     id: 1,
+    leafId,
+    stablePaneId: leafId,
     terminal: {
       cols: 80,
       rows: 24
diff --git a/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts b/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
index f0c78cce205..b163d4934f3 100644
--- a/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
@@ -20,6 +20,7 @@ function createPane({
   terminalRows: number
   paneId?: number
 }): ManagedPaneInternal {
+  const leafId = '11111111-1111-4111-8111-111111111111' as never
   const fit = vi.fn()
   const proposeDimensions = vi.fn(() => ({ cols: proposedCols, rows: proposedRows }))
   const terminal = {
@@ -44,6 +45,8 @@ function createPane({
 
   return {
     id: paneId,
+    leafId,
+    stablePaneId: leafId,
     terminal: terminal as never,
     container: { dataset: {} } as never,
     xtermContainer: {} as never,
diff --git a/src/renderer/src/runtime/sync-runtime-graph.ts b/src/renderer/src/runtime/sync-runtime-graph.ts
index 47e83281e3a..83cb03e2b8a 100644
--- a/src/renderer/src/runtime/sync-runtime-graph.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph.ts
@@ -1,12 +1,12 @@
 /* eslint-disable max-lines -- Why: runtime graph sync and mobile session-tab publication share the same injected renderer state and terminal registry. Keeping them together prevents a second store/registry reader from drifting. */
 import {
   collectLeafIdsInOrder,
-  paneLeafId,
   serializePaneTree
 } from '@/components/terminal-pane/layout-serialization'
 import { warnTerminalLifecycleAnomaly } from '@/components/terminal-pane/terminal-lifecycle-diagnostics'
-import type { PaneManager } from '@/lib/pane-manager/pane-manager'
 import { createBrowserUuid } from '@/lib/browser-uuid'
+import type { PaneManager } from '@/lib/pane-manager/pane-manager'
+import { resolveLeafIdForManager } from '@/lib/pane-manager/pane-key-resolution'
 import type { AppState } from '@/store/types'
 import type {
   RuntimeMobileSessionFileTab,
@@ -15,6 +15,7 @@ import type {
   RuntimeMobileSessionTabsSnapshot,
   RuntimeSyncWindowGraph
 } from '../../../shared/runtime-types'
+import { isTerminalLeafId } from '../../../shared/stable-pane-id'
 import { getActiveTabNavOrder } from '../components/tab-bar/group-tab-order'
 
 type RegisteredTerminalTab = {
@@ -85,11 +86,11 @@ export function focusRuntimeTerminalSurface(tabId: string, leafId?: string | nul
     manager.getActivePane()?.terminal.focus()
     return true
   }
-  const pane = manager.getPanes().find((candidate) => paneLeafId(candidate.id) === leafId)
-  if (!pane) {
+  const resolution = resolveLeafIdForManager(tabId, leafId, manager)
+  if (resolution.status !== 'resolved') {
     return false
   }
-  manager.setActivePane(pane.id, { focus: true })
+  manager.setActivePane(resolution.numericPaneId, { focus: true })
   scheduleRuntimeGraphSync()
   return true
 }
@@ -293,13 +294,13 @@ async function syncRuntimeGraph(): Promise<void> {
       tabId,
       worktreeId: registeredTab.worktreeId,
       title: tab.customTitle ?? tab.title,
-      activeLeafId: activePaneId === null ? null : paneLeafId(activePaneId),
+      activeLeafId: activePaneId === null ? null : (manager?.getLeafId(activePaneId) ?? null),
       layout: serializePaneTree(root)
     })
 
     const savedPtyIdsByLeafId = state.terminalLayoutsByTabId[tabId]?.ptyIdsByLeafId ?? {}
     for (const pane of manager?.getPanes() ?? []) {
-      const leafId = paneLeafId(pane.id)
+      const leafId = pane.leafId
       const ptyId = registeredTab.getPtyIdForPane(pane.id)
       const savedPtyId = savedPtyIdsByLeafId[leafId] ?? null
       const registeredTime = tabRegisteredAt.get(tabId) ?? 0
@@ -452,21 +453,21 @@ function mobileTerminalSurfaceId(parentTabId: string, leafId: string): string {
 function getRuntimeLeafIdsForTerminal(tabId: string, state: AppState): string[] {
   const registered = registeredTabs.get(tabId)
   const manager = registered?.getManager()
-  const liveLeafIds = manager?.getPanes().map((pane) => paneLeafId(pane.id)) ?? []
+  const liveLeafIds = manager?.getPanes().map((pane) => pane.leafId) ?? []
   if (liveLeafIds.length > 0) {
     return liveLeafIds
   }
 
   const layout = state.terminalLayoutsByTabId[tabId]
-  const persistedLeafIds = collectLeafIdsInOrder(layout?.root)
+  const persistedLeafIds = collectLeafIdsInOrder(layout?.root).filter(isTerminalLeafId)
   if (persistedLeafIds.length > 0) {
     return persistedLeafIds
   }
 
   // Why: a newly-created terminal tab can be in the store before TerminalPane
-  // mounts. Publish its deterministic first-pane surface so mobile does not
-  // fill the startup gap from terminal.list.
-  return [paneLeafId(1)]
+  // mounts. Without a live or persisted UUID leaf, there is no stable mobile
+  // surface to publish yet; fabricating pane:1 would become stale after mount.
+  return []
 }
 
 function buildMobileTerminalSurfaceTabs(
@@ -482,16 +483,23 @@ function buildMobileTerminalSurfaceTabs(
           group.activeTabId === unifiedTabId
       ) === true
     : state.activeTabId === terminal.id
-  const liveActiveLeafId =
-    registeredTabs.get(terminal.id)?.getManager()?.getActivePane()?.id ?? null
+  const manager = registeredTabs.get(terminal.id)?.getManager()
+  const liveActivePaneId = manager?.getActivePane()?.id ?? null
+  const leafIds = getRuntimeLeafIdsForTerminal(terminal.id, state)
   const activeLeafId =
-    liveActiveLeafId !== null
-      ? paneLeafId(liveActiveLeafId)
-      : (state.terminalLayoutsByTabId[terminal.id]?.activeLeafId ?? paneLeafId(1))
+    liveActivePaneId !== null
+      ? (manager?.getLeafId(liveActivePaneId) ?? null)
+      : (state.terminalLayoutsByTabId[terminal.id]?.activeLeafId ?? leafIds[0] ?? null)
   const paneTitles = state.runtimePaneTitlesByTabId[terminal.id] ?? {}
-  return getRuntimeLeafIdsForTerminal(terminal.id, state).map((leafId) => {
-    const paneId = /^pane:(\d+)$/.exec(leafId)?.[1]
-    const paneTitle = paneId ? paneTitles[Number(paneId)] : undefined
+  return leafIds.map((leafId) => {
+    const numericPaneId = manager?.getNumericIdForLeaf(leafId) ?? null
+    const legacyPaneId = numericPaneId === null ? /^pane:(\d+)$/.exec(leafId)?.[1] : null
+    const paneTitle =
+      numericPaneId !== null
+        ? paneTitles[numericPaneId]
+        : legacyPaneId
+          ? paneTitles[Number(legacyPaneId)]
+          : undefined
     return {
       type: 'terminal' as const,
       id: mobileTerminalSurfaceId(terminal.id, leafId),
diff --git a/src/renderer/src/store/slices/agent-status.ts b/src/renderer/src/store/slices/agent-status.ts
index 361db4a40f1..d61aa81cc3e 100644
--- a/src/renderer/src/store/slices/agent-status.ts
+++ b/src/renderer/src/store/slices/agent-status.ts
@@ -7,6 +7,7 @@ import {
   type AgentStateHistoryEntry,
   type AgentStatusEntry,
   type AgentType,
+  type MigrationUnsupportedPtyEntry,
   type ParsedAgentStatusPayload
 } from '../../../../shared/agent-status-types'
 import type { TerminalTab } from '../../../../shared/types'
@@ -30,9 +31,12 @@ export type RetainedAgentEntry = {
 }
 
 export type AgentStatusSlice = {
-  /** Explicit agent status entries keyed by `${tabId}:${paneId}` composite.
+  /** Explicit agent status entries keyed by `${tabId}:${leafId}` composite.
    *  Real-time only — lives in renderer memory, not persisted to disk. */
   agentStatusByPaneKey: Record<string, AgentStatusEntry>
+  /** PTYs that still report legacy numeric pane keys but have registry-backed
+   *  UUID pane proof. Stored separately from normal hook-reported status. */
+  migrationUnsupportedByPtyId: Record<string, MigrationUnsupportedPtyEntry>
   /** Monotonic tick that advances when agent-status freshness boundaries pass. */
   agentStatusEpoch: number
 
@@ -55,6 +59,9 @@ export type AgentStatusSlice = {
     timing?: { updatedAt?: number; stateStartedAt?: number }
   ) => void
 
+  setMigrationUnsupportedPty: (entry: MigrationUnsupportedPtyEntry) => void
+  clearMigrationUnsupportedPty: (ptyId: string) => void
+
   /** Remove a single entry (e.g., when a pane's terminal exits). */
   removeAgentStatus: (paneKey: string) => void
 
@@ -116,6 +123,22 @@ function paneKeyMatchesAnyTabPrefix(paneKey: string, tabPrefixes: string[]): boo
   return false
 }
 
+function pruneMigrationUnsupportedEntries(
+  entries: Record<string, MigrationUnsupportedPtyEntry>,
+  predicate: (entry: MigrationUnsupportedPtyEntry) => boolean
+): { next: Record<string, MigrationUnsupportedPtyEntry>; changed: boolean } {
+  let changed = false
+  const next: Record<string, MigrationUnsupportedPtyEntry> = {}
+  for (const [ptyId, entry] of Object.entries(entries)) {
+    if (predicate(entry)) {
+      changed = true
+      continue
+    }
+    next[ptyId] = entry
+  }
+  return { next: changed ? next : entries, changed }
+}
+
 export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusSlice> = (
   set,
   get
@@ -142,6 +165,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
 
   return {
     agentStatusByPaneKey: {},
+    migrationUnsupportedByPtyId: {},
     agentStatusEpoch: 0,
     retainedAgentsByPaneKey: {},
     retentionSuppressedPaneKeys: {},
@@ -265,11 +289,20 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           nextRetentionSuppressedPaneKeys = { ...s.retentionSuppressedPaneKeys }
           delete nextRetentionSuppressedPaneKeys[paneKey]
         }
+        const migrationUnsupported = pruneMigrationUnsupportedEntries(
+          s.migrationUnsupportedByPtyId,
+          (entry) => entry.paneKey === paneKey
+        )
         return {
           agentStatusByPaneKey: { ...s.agentStatusByPaneKey, [paneKey]: entry },
+          migrationUnsupportedByPtyId: migrationUnsupported.next,
           retentionSuppressedPaneKeys: nextRetentionSuppressedPaneKeys,
-          agentStatusEpoch: sortRelevantChange ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
-          sortEpoch: sortRelevantChange ? s.sortEpoch + 1 : s.sortEpoch
+          agentStatusEpoch:
+            sortRelevantChange || migrationUnsupported.changed
+              ? s.agentStatusEpoch + 1
+              : s.agentStatusEpoch,
+          sortEpoch:
+            sortRelevantChange || migrationUnsupported.changed ? s.sortEpoch + 1 : s.sortEpoch
         }
       })
       // Why: schedule after set completes so the timer reads the updated map.
@@ -277,13 +310,55 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
       queueMicrotask(() => freshness.schedule())
     },
 
-    removeAgentStatus: (paneKey) => {
-      if (!(paneKey in get().agentStatusByPaneKey)) {
+    setMigrationUnsupportedPty: (entry) => {
+      set((s) => {
+        const existing = s.migrationUnsupportedByPtyId[entry.ptyId]
+        if (existing && entry.updatedAt < existing.updatedAt) {
+          return s
+        }
+        return {
+          migrationUnsupportedByPtyId: {
+            ...s.migrationUnsupportedByPtyId,
+            [entry.ptyId]: entry
+          },
+          agentStatusEpoch: s.agentStatusEpoch + 1,
+          sortEpoch: s.sortEpoch + 1
+        }
+      })
+    },
+
+    clearMigrationUnsupportedPty: (ptyId) => {
+      if (!(ptyId in get().migrationUnsupportedByPtyId)) {
         return
       }
       set((s) => {
-        const next = { ...s.agentStatusByPaneKey }
-        delete next[paneKey]
+        const next = { ...s.migrationUnsupportedByPtyId }
+        delete next[ptyId]
+        return {
+          migrationUnsupportedByPtyId: next,
+          agentStatusEpoch: s.agentStatusEpoch + 1,
+          sortEpoch: s.sortEpoch + 1
+        }
+      })
+    },
+
+    removeAgentStatus: (paneKey) => {
+      if (
+        !(paneKey in get().agentStatusByPaneKey) &&
+        !Object.values(get().migrationUnsupportedByPtyId).some((entry) => entry.paneKey === paneKey)
+      ) {
+        return
+      }
+      set((s) => {
+        const hasLive = paneKey in s.agentStatusByPaneKey
+        const next = hasLive ? { ...s.agentStatusByPaneKey } : s.agentStatusByPaneKey
+        if (hasLive) {
+          delete next[paneKey]
+        }
+        const migrationUnsupported = pruneMigrationUnsupportedEntries(
+          s.migrationUnsupportedByPtyId,
+          (entry) => entry.paneKey === paneKey
+        )
         // Why: acknowledgedAgentsByPaneKey is written per user-ack but owned
         // lifecycle-wise by the pane — drop the ack entry in lockstep with the
         // live-map entry so closed panes don't leave stale ack timestamps that
@@ -299,6 +374,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         // as setAgentStatus.
         return {
           agentStatusByPaneKey: next,
+          migrationUnsupportedByPtyId: migrationUnsupported.next,
           ...(nextAck !== s.acknowledgedAgentsByPaneKey
             ? { acknowledgedAgentsByPaneKey: nextAck }
             : {}),
@@ -313,7 +389,10 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
       const prefix = `${tabIdPrefix}:`
       const currentKeys = Object.keys(get().agentStatusByPaneKey)
       const toRemove = currentKeys.filter((k) => k.startsWith(prefix))
-      if (toRemove.length === 0) {
+      const hasMigrationUnsupported = Object.values(get().migrationUnsupportedByPtyId).some(
+        (entry) => entry.paneKey?.startsWith(prefix)
+      )
+      if (toRemove.length === 0 && !hasMigrationUnsupported) {
         return
       }
       set((s) => {
@@ -321,6 +400,10 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         for (const key of toRemove) {
           delete next[key]
         }
+        const migrationUnsupported = pruneMigrationUnsupportedEntries(
+          s.migrationUnsupportedByPtyId,
+          (entry) => entry.paneKey?.startsWith(prefix) ?? false
+        )
         // See removeAgentStatus for rationale on ack cleanup.
         let nextAck = s.acknowledgedAgentsByPaneKey
         const ackKeys = Object.keys(nextAck).filter((k) => k.startsWith(prefix))
@@ -336,6 +419,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         // no keys matched the prefix.
         return {
           agentStatusByPaneKey: next,
+          migrationUnsupportedByPtyId: migrationUnsupported.next,
           ...(nextAck !== s.acknowledgedAgentsByPaneKey
             ? { acknowledgedAgentsByPaneKey: nextAck }
             : {}),
@@ -356,6 +440,10 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         const hasLive = paneKey in s.agentStatusByPaneKey
         liveExisted = hasLive
         const hasRetained = paneKey in s.retainedAgentsByPaneKey
+        const migrationUnsupported = pruneMigrationUnsupportedEntries(
+          s.migrationUnsupportedByPtyId,
+          (entry) => entry.paneKey === paneKey
+        )
         // See removeAgentStatus for rationale on ack cleanup. Apply this
         // regardless of live/retained presence — the ack entry is owned by
         // the pane lifecycle independently of live/retained state.
@@ -371,7 +459,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         // paneKey with no live and no retained entry truly has nothing to
         // change, so short-circuit here — but still flush a pending ack
         // cleanup if one is present.
-        if (!hasLive && !hasRetained) {
+        if (!hasLive && !hasRetained && !migrationUnsupported.changed) {
           if (nextAck !== s.acknowledgedAgentsByPaneKey) {
             return { acknowledgedAgentsByPaneKey: nextAck }
           }
@@ -423,6 +511,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         return {
           agentStatusByPaneKey: nextLive,
           retainedAgentsByPaneKey: nextRetained,
+          migrationUnsupportedByPtyId: migrationUnsupported.next,
           ...(nextAck !== s.acknowledgedAgentsByPaneKey
             ? { acknowledgedAgentsByPaneKey: nextAck }
             : {}),
@@ -434,13 +523,14 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
                 }
               }
             : {}),
-          agentStatusEpoch: hasLive ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
+          agentStatusEpoch:
+            hasLive || migrationUnsupported.changed ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
           // Why: mirrors removeAgentStatus — dropping a live working/blocked
           // agent changes its contribution to the worktree sort score, so the
           // sidebar smart-sort must recompute. Without this bump, a user-
           // initiated dismissal from the inline agents list would leave the
           // sidebar ordering stale until some unrelated event repaired it.
-          sortEpoch: hasLive ? s.sortEpoch + 1 : s.sortEpoch
+          sortEpoch: hasLive || migrationUnsupported.changed ? s.sortEpoch + 1 : s.sortEpoch
         }
       })
       // Why: freshness.schedule only matters when the live map changed —
@@ -470,6 +560,10 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         const retainedKeys = Object.keys(s.retainedAgentsByPaneKey).filter((k) =>
           k.startsWith(prefix)
         )
+        const migrationUnsupported = pruneMigrationUnsupportedEntries(
+          s.migrationUnsupportedByPtyId,
+          (entry) => entry.paneKey?.startsWith(prefix) ?? false
+        )
         // See removeAgentStatus for rationale on ack cleanup. Apply this
         // regardless of live/retained presence — ack entries are owned by
         // the pane lifecycle independently of live/retained state.
@@ -481,7 +575,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
             delete nextAck[k]
           }
         }
-        if (liveKeys.length === 0 && retainedKeys.length === 0) {
+        if (liveKeys.length === 0 && retainedKeys.length === 0 && !migrationUnsupported.changed) {
           if (nextAck !== s.acknowledgedAgentsByPaneKey) {
             return { acknowledgedAgentsByPaneKey: nextAck }
           }
@@ -527,6 +621,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         return {
           agentStatusByPaneKey: nextLive,
           retainedAgentsByPaneKey: nextRetained,
+          migrationUnsupportedByPtyId: migrationUnsupported.next,
           retentionSuppressedPaneKeys: nextRetentionSuppressedPaneKeys,
           ...(nextAck !== s.acknowledgedAgentsByPaneKey
             ? { acknowledgedAgentsByPaneKey: nextAck }
@@ -534,8 +629,9 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           // Why: mirrors removeAgentStatusByTabPrefix — only bump the live-map
           // epoch / sortEpoch when the live map actually changed. Retained-only
           // sweeps do not participate in smart-sort or freshness calculations.
-          agentStatusEpoch: hadLive ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
-          sortEpoch: hadLive ? s.sortEpoch + 1 : s.sortEpoch
+          agentStatusEpoch:
+            hadLive || migrationUnsupported.changed ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
+          sortEpoch: hadLive || migrationUnsupported.changed ? s.sortEpoch + 1 : s.sortEpoch
         }
       })
       if (hadLive) {
@@ -557,6 +653,12 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
           )
           .map(([paneKey]) => paneKey)
         const retainedKeySet = new Set(retainedKeys)
+        const migrationUnsupported = pruneMigrationUnsupportedEntries(
+          s.migrationUnsupportedByPtyId,
+          (entry) =>
+            entry.worktreeId === worktreeId ||
+            (entry.paneKey ? paneKeyMatchesAnyTabPrefix(entry.paneKey, tabPrefixes) : false)
+        )
         // See removeAgentStatus for rationale on ack cleanup. Current tabs are
         // swept by prefix; orphan retained rows are swept by their retained key.
         let nextAck = s.acknowledgedAgentsByPaneKey
@@ -573,7 +675,7 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         // changed, narrow the return to just the ack delta (or s) so we don't
         // emit a new top-level state object that re-renders full-state
         // subscribers for nothing.
-        if (liveKeys.length === 0 && retainedKeys.length === 0) {
+        if (liveKeys.length === 0 && retainedKeys.length === 0 && !migrationUnsupported.changed) {
           if (nextAck !== s.acknowledgedAgentsByPaneKey) {
             return { acknowledgedAgentsByPaneKey: nextAck }
           }
@@ -608,12 +710,14 @@ export const createAgentStatusSlice: StateCreator<AppState, [], [], AgentStatusS
         return {
           agentStatusByPaneKey: nextLive,
           retainedAgentsByPaneKey: nextRetained,
+          migrationUnsupportedByPtyId: migrationUnsupported.next,
           retentionSuppressedPaneKeys: nextRetentionSuppressedPaneKeys,
           ...(nextAck !== s.acknowledgedAgentsByPaneKey
             ? { acknowledgedAgentsByPaneKey: nextAck }
             : {}),
-          agentStatusEpoch: hadLive ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
-          sortEpoch: hadLive ? s.sortEpoch + 1 : s.sortEpoch
+          agentStatusEpoch:
+            hadLive || migrationUnsupported.changed ? s.agentStatusEpoch + 1 : s.agentStatusEpoch,
+          sortEpoch: hadLive || migrationUnsupported.changed ? s.sortEpoch + 1 : s.sortEpoch
         }
       })
       if (hadLive) {
diff --git a/src/renderer/src/store/slices/store-cascades.test.ts b/src/renderer/src/store/slices/store-cascades.test.ts
index a20b9768de3..98a73cfe811 100644
--- a/src/renderer/src/store/slices/store-cascades.test.ts
+++ b/src/renderer/src/store/slices/store-cascades.test.ts
@@ -1614,10 +1614,9 @@ describe('shutdownWorktreeTerminals (sleep) — agent status hygiene', () => {
   })
 })
 
-// Why: CLI-spawned background terminals stamp ORCA_PANE_KEY=`${tabId}:1` into
-// the PTY env at spawn time. The renderer must adopt the tab under the same
-// id so hook events route to the correct slot. See
-// docs/cli-terminal-hook-pane-key.md.
+// Why: CLI-spawned background terminals stamp ORCA_PANE_KEY into the PTY env
+// at spawn time. The renderer must adopt the tab under the same id so hook
+// events route to the correct slot.
 describe('createTab tabId hint', () => {
   it('uses the supplied id when no collision exists', () => {
     const store = createTestStore()
diff --git a/src/renderer/src/store/slices/store-session-cascades.test.ts b/src/renderer/src/store/slices/store-session-cascades.test.ts
index 2e86742c240..990a4f3fc01 100644
--- a/src/renderer/src/store/slices/store-session-cascades.test.ts
+++ b/src/renderer/src/store/slices/store-session-cascades.test.ts
@@ -9,6 +9,7 @@ import type {
   TerminalTab,
   Worktree
 } from '../../../../shared/types'
+import { isTerminalLeafId } from '../../../../shared/stable-pane-id'
 
 // Mock sonner (imported by repos.ts)
 vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }))
@@ -1305,12 +1306,15 @@ describe('reconnectPersistedTerminals', () => {
     // sees the tab as active (green dot) even before the terminal mounts.
     // connectPanePty reads ptyIdsByLeafId for per-leaf daemon sessions.
     expect(s.tabsByWorktree[wt1][0].ptyId).toBe('daemon-session-B')
-    // ptyIdsByLeafId preserved from hydration for connectPanePty to consume
+    // ptyIdsByLeafId preserved from hydration for connectPanePty to consume,
+    // but legacy pane:* leaves are reminted to durable UUID leaves at hydration.
     const layout = s.terminalLayoutsByTabId['tab1']
-    expect(layout.ptyIdsByLeafId).toEqual({
-      'pane:1': 'daemon-session-A',
-      'pane:3': 'daemon-session-B'
-    })
+    const bindings = layout.ptyIdsByLeafId ?? {}
+    expect(Object.keys(bindings)).toHaveLength(2)
+    expect(Object.keys(bindings).every(isTerminalLeafId)).toBe(true)
+    expect(Object.keys(bindings)).not.toContain('pane:1')
+    expect(Object.keys(bindings)).not.toContain('pane:3')
+    expect(Object.values(bindings).sort()).toEqual(['daemon-session-A', 'daemon-session-B'])
     expect(s.workspaceSessionReady).toBe(true)
   })
 })
diff --git a/src/renderer/src/store/slices/terminal-helpers.ts b/src/renderer/src/store/slices/terminal-helpers.ts
index 10e4595d2b8..3976605569c 100644
--- a/src/renderer/src/store/slices/terminal-helpers.ts
+++ b/src/renderer/src/store/slices/terminal-helpers.ts
@@ -9,6 +9,20 @@ export function emptyLayoutSnapshot(): TerminalLayoutSnapshot {
   }
 }
 
+export function singlePaneLayoutSnapshot(
+  leafId: string,
+  ptyId?: string,
+  title?: string | null
+): TerminalLayoutSnapshot {
+  return {
+    root: { type: 'leaf', leafId },
+    activeLeafId: leafId,
+    expandedLeafId: null,
+    ...(ptyId ? { ptyIdsByLeafId: { [leafId]: ptyId } } : {}),
+    ...(title ? { titlesByLeafId: { [leafId]: title } } : {})
+  }
+}
+
 export function clearTransientTerminalState(tab: TerminalTab, index: number): TerminalTab {
   return {
     ...tab,
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index 949eb2049ed..8e0f0aa9064 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -27,6 +27,7 @@ import {
   ensurePtyDispatcher,
   unregisterPtyDataHandlers
 } from '@/components/terminal-pane/pty-transport'
+import { normalizeTerminalLayoutSnapshot } from '@/components/terminal-pane/terminal-layout-leaf-ids'
 import { shutdownBufferCaptures } from '@/components/terminal-pane/shutdown-buffer-captures'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { createBrowserUuid } from '@/lib/browser-uuid'
@@ -154,8 +155,8 @@ export type TerminalSlice = {
       pendingActivationSpawn?: boolean
       initialPtyId?: string
       activate?: boolean
-      /** Pre-allocated tab id (e.g. minted by main for CLI-spawned terminals
-       *  whose PTY env already carries `paneKey=`${tabId}:1``). Falls back to
+      /** Pre-allocated tab id (e.g. minted by main for CLI/runtime-spawned
+       *  terminals whose PTY env already carries a pane key). Falls back to
        *  minting a fresh id when omitted or when the supplied id collides
        *  with an existing tab anywhere in the store (tabIds form the global
        *  paneKey namespace, so collisions are checked across all worktrees). */
@@ -226,7 +227,7 @@ export type TerminalSlice = {
     tabId: string
   ) => { command: string; env?: Record<string, string> } | null
   /** Per-pane timestamp (ms) when the prompt-cache countdown started (agent became idle).
-   *  Keys are `${tabId}:${paneId}` composites so split-pane tabs can track each pane
+   *  Keys are `${tabId}:${leafId}` composites so split-pane tabs can track each pane
    *  independently. null means no active timer for that pane. */
   cacheTimerByKey: Record<string, number | null>
   setCacheTimerStartedAt: (key: string, ts: number | null) => void
@@ -283,7 +284,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   setCacheTimerStartedAt: (key, ts) => {
     set((s) => {
       const next = { ...s.cacheTimerByKey, [key]: ts }
-      // Why: when a real pane transition writes a key like `${tabId}:${paneId}`,
+      // Why: when a real pane transition writes a key like `${tabId}:${leafId}`,
       // clean up any `${tabId}:seed` sentinel left by seedCacheTimersForIdleTabs.
       // This prevents phantom timers when the seeded key doesn't match the real
       // pane ID (e.g., idle Claude in pane 2 of a split tab).
@@ -367,7 +368,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       // boundary at useIpcEvents.ts spreads `id` whenever `tabId !== undefined`,
       // so a stray `''` or whitespace-only value from a future producer would
       // otherwise be persisted as a real tab id and break paneKey routing
-      // (`${tabId}:1` would shape as `:1` or `<spaces>:1`).
+      // (`${tabId}:${leafId}` would inherit the bad tab segment).
       const trimmedHint = typeof options?.id === 'string' ? options.id.trim() : ''
       const hintedId = trimmedHint.length > 0 ? trimmedHint : undefined
       const idCollides =
@@ -537,7 +538,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       const nextPendingIssueCommandSplitByTabId = { ...s.pendingIssueCommandSplitByTabId }
       delete nextPendingIssueCommandSplitByTabId[tabId]
       const nextCacheTimer = { ...s.cacheTimerByKey }
-      // Why: cache timer keys are `${tabId}:${paneId}` composites. Remove all
+      // Why: cache timer keys are `${tabId}:${leafId}` composites. Remove all
       // entries for the closing tab, regardless of how many panes it had.
       for (const key of Object.keys(nextCacheTimer)) {
         if (key.startsWith(`${tabId}:`)) {
@@ -1740,7 +1741,13 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         // reconnectPersistedTerminals can reattach each split-pane leaf
         // to its specific daemon session (not just the tab-level ptyId).
         terminalLayoutsByTabId: Object.fromEntries(
-          Object.entries(session.terminalLayoutsByTabId).filter(([tabId]) => validTabIds.has(tabId))
+          Object.entries(session.terminalLayoutsByTabId)
+            .filter(([tabId]) => validTabIds.has(tabId))
+            .map(([tabId, layout]) => {
+              // Why: old sessions can contain renderer-local pane:1-style leaf
+              // ids. Normalize during hydration before runtime/mobile surfaces read them.
+              return [tabId, normalizeTerminalLayoutSnapshot(layout).snapshot]
+            })
         )
       }
     })
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index 2541e15937c..378be8f8b9d 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -160,6 +160,9 @@ function createWebPreloadApi(): Partial<PreloadApi> {
     agentStatus: {
       onSet: () => noopUnsubscribe,
       getSnapshot: () => Promise.resolve([]),
+      onMigrationUnsupported: () => noopUnsubscribe,
+      onMigrationUnsupportedClear: () => noopUnsubscribe,
+      getMigrationUnsupportedSnapshot: () => Promise.resolve([]),
       drop: () => {}
     },
     mobile: {
diff --git a/src/shared/agent-hook-listener.test.ts b/src/shared/agent-hook-listener.test.ts
index e0fa65dc713..fa3c0e8acbf 100644
--- a/src/shared/agent-hook-listener.test.ts
+++ b/src/shared/agent-hook-listener.test.ts
@@ -12,6 +12,10 @@ import {
   writeEndpointFile,
   type HookListenerState
 } from './agent-hook-listener'
+import { makePaneKey } from './stable-pane-id'
+
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const PANE_KEY = makePaneKey('tab-1', LEAF_ID)
 
 describe('shared agent-hook-listener', () => {
   let state: HookListenerState
@@ -47,7 +51,7 @@ describe('shared agent-hook-listener', () => {
       state,
       'claude',
       {
-        paneKey: 'tab-1:0',
+        paneKey: PANE_KEY,
         tabId: 'tab-1',
         worktreeId: 'wt',
         env: 'production',
@@ -57,7 +61,7 @@ describe('shared agent-hook-listener', () => {
       'production'
     )
     expect(event).not.toBeNull()
-    expect(event!.paneKey).toBe('tab-1:0')
+    expect(event!.paneKey).toBe(PANE_KEY)
     expect(event!.connectionId).toBeNull()
     expect(event!.payload.state).toBe('working')
     expect(event!.payload.prompt).toBe('hello')
@@ -69,7 +73,7 @@ describe('shared agent-hook-listener', () => {
       state,
       'claude',
       {
-        paneKey: 'tab-1:0',
+        paneKey: PANE_KEY,
         payload: { hook_event_name: 'UserPromptSubmit', prompt: '   hi   ' }
       },
       'production'
@@ -97,7 +101,7 @@ describe('shared agent-hook-listener', () => {
     normalizeHookPayload(
       a,
       'claude',
-      { paneKey: 'p', payload: { hook_event_name: 'UserPromptSubmit', prompt: 'first' } },
+      { paneKey: PANE_KEY, payload: { hook_event_name: 'UserPromptSubmit', prompt: 'first' } },
       'production'
     )
     // The second listener has no cached prompt for this paneKey, so a tool
@@ -106,7 +110,7 @@ describe('shared agent-hook-listener', () => {
       b,
       'claude',
       {
-        paneKey: 'p',
+        paneKey: PANE_KEY,
         payload: {
           hook_event_name: 'PreToolUse',
           tool_name: 'Read',
diff --git a/src/shared/agent-hook-listener.ts b/src/shared/agent-hook-listener.ts
index f2887b30846..3b5e2c36bf6 100644
--- a/src/shared/agent-hook-listener.ts
+++ b/src/shared/agent-hook-listener.ts
@@ -29,6 +29,7 @@ import { join } from 'path'
 import { parseAgentStatusPayload, type ParsedAgentStatusPayload } from './agent-status-types'
 import { ORCA_HOOK_PROTOCOL_VERSION } from './agent-hook-types'
 import { REMOTE_AGENT_HOOK_ENV, type AgentHookSource } from './agent-hook-relay'
+import { parsePaneKey } from './stable-pane-id'
 
 /** Maximum request body size accepted by the listener (1 MB). */
 export const HOOK_REQUEST_MAX_BYTES = 1_000_000
@@ -41,7 +42,7 @@ const MAX_WARNED_KEYS = 32
 /** Slowloris cap: drop requests that have not finished sending after 5 s. */
 export const HOOK_REQUEST_SLOWLORIS_MS = 5_000
 
-/** Bound paneKey size — `${tabId}:${paneId}` is well under 200 chars in
+/** Bound paneKey size — `${tabId}:${leafUuid}` is well under 200 chars in
  *  practice; cap defends per-pane caches against pathological input.
  *  Exported so non-HTTP ingest paths (e.g. Orca's `ingestRemote`) can apply
  *  the same cap as defense-in-depth. */
@@ -1161,6 +1162,7 @@ export function normalizeHookPayload(
 
   const record = body as Record<string, unknown>
   const paneKey = typeof record.paneKey === 'string' ? record.paneKey.trim() : ''
+  const parsedPaneKey = parsePaneKey(paneKey)
   const rawPayload = record.payload
   const hookPayload =
     typeof rawPayload === 'string'
@@ -1175,6 +1177,7 @@ export function normalizeHookPayload(
   if (
     !paneKey ||
     paneKey.length > MAX_PANE_KEY_LEN ||
+    !parsedPaneKey ||
     typeof hookPayload !== 'object' ||
     hookPayload === null
   ) {
@@ -1188,6 +1191,9 @@ export function normalizeHookPayload(
   })
 
   const tabId = readStringField(record, 'tabId')
+  if (tabId && tabId !== parsedPaneKey.tabId) {
+    return null
+  }
   const worktreeId = readStringField(record, 'worktreeId')
 
   const eventName = (hookPayload as Record<string, unknown>).hook_event_name
diff --git a/src/shared/agent-status-types.ts b/src/shared/agent-status-types.ts
index 70fedb0cc31..402907d339b 100644
--- a/src/shared/agent-status-types.ts
+++ b/src/shared/agent-status-types.ts
@@ -61,7 +61,7 @@ export type AgentStatusEntry = {
    *  (tool/prompt pings reset updatedAt but not stateStartedAt). */
   stateStartedAt: number
   agentType?: AgentType
-  /** Composite key: `${tabId}:${paneId}` — matches the cacheTimerByKey convention. */
+  /** Composite key: `${tabId}:${leafId}` where leafId is a stable UUID layout leaf. */
   paneKey: string
   terminalTitle?: string
   /** Rolling log of previous states. Each entry records a state the agent was in
@@ -81,6 +81,18 @@ export type AgentStatusEntry = {
   interrupted?: boolean
 }
 
+export type MigrationUnsupportedPtyEntry = {
+  ptyId: string
+  worktreeId?: string
+  tabId?: string
+  leafId?: string
+  /** Registry-backed UUID pane proof, when available. */
+  paneKey?: string
+  reason: 'legacy-numeric-pane-key'
+  source: 'local' | 'ssh'
+  updatedAt: number
+}
+
 // ─── Agent status payload shape (what hook receivers send via IPC) ──────────
 // Hook integrations only need to provide normalized state fields. The
 // remaining AgentStatusEntry fields (updatedAt, paneKey, etc.) are populated
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 9e602188d55..f643e0b7e11 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -317,6 +317,7 @@ export function getDefaultPersistedState(homedir: string): PersistedState {
     workspaceSession: getDefaultWorkspaceSession(),
     sshTargets: [],
     sshRemotePtyLeases: [],
+    migrationUnsupportedPtyEntries: [],
     automations: [],
     automationRuns: [],
     onboarding: getDefaultOnboardingState()
diff --git a/src/shared/pane-key.ts b/src/shared/pane-key.ts
index c0bcc21b82a..ce7d10065a7 100644
--- a/src/shared/pane-key.ts
+++ b/src/shared/pane-key.ts
@@ -1,6 +1,4 @@
-/** Why: CLI-spawned terminals bake `paneKey = `${tabId}:${FIRST_PANE_ID}`` into
- *  the PTY env at spawn time, before any pane has actually been allocated.
- *  This constant must match the renderer's PaneManager.nextPaneId initial
- *  value so hook events route to the first pane. See
- *  docs/cli-terminal-hook-pane-key.md. */
+/** Why: live PaneManager ids are still 1-based numeric handles even though
+ *  durable pane keys use UUID leaf ids. Keep the first numeric id centralized
+ *  for runtime-title mapping and legacy migration fallbacks. */
 export const FIRST_PANE_ID = 1
diff --git a/src/shared/stable-pane-id.test.ts b/src/shared/stable-pane-id.test.ts
new file mode 100644
index 00000000000..a380cfacb27
--- /dev/null
+++ b/src/shared/stable-pane-id.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { isStablePaneId, isTerminalLeafId, makePaneKey, parsePaneKey } from './stable-pane-id'
+
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+
+describe('stable pane ids', () => {
+  it('recognizes UUID leaf ids as stable pane ids', () => {
+    expect(isStablePaneId(LEAF_ID)).toBe(true)
+    expect(isTerminalLeafId(LEAF_ID)).toBe(true)
+  })
+
+  it('rejects legacy numeric pane ids and malformed UUIDs', () => {
+    for (const value of ['1', 'pane:1', '11111111-1111-6111-8111-111111111111', '']) {
+      expect(isStablePaneId(value)).toBe(false)
+      expect(isTerminalLeafId(value)).toBe(false)
+    }
+  })
+
+  it('builds and parses pane keys using the tab id and UUID leaf id', () => {
+    const paneKey = makePaneKey('tab-1', LEAF_ID)
+
+    expect(paneKey).toBe(`tab-1:${LEAF_ID}`)
+    expect(parsePaneKey(paneKey)).toEqual({
+      tabId: 'tab-1',
+      leafId: LEAF_ID,
+      stablePaneId: LEAF_ID
+    })
+  })
+
+  it('rejects ambiguous tab ids and non-UUID leaf ids when building keys', () => {
+    expect(() => makePaneKey('', LEAF_ID)).toThrow(/tabId/)
+    expect(() => makePaneKey('tab:1', LEAF_ID)).toThrow(/tabId/)
+    expect(() => makePaneKey('tab-1', '1')).toThrow(/UUID/)
+  })
+
+  it('rejects ambiguous or legacy pane-key inputs when parsing', () => {
+    expect(parsePaneKey('tab-1:1')).toBeNull()
+    expect(parsePaneKey(`tab:1:${LEAF_ID}`)).toBeNull()
+    expect(parsePaneKey(`:${LEAF_ID}`)).toBeNull()
+    expect(parsePaneKey('tab-1:')).toBeNull()
+  })
+})
diff --git a/src/shared/stable-pane-id.ts b/src/shared/stable-pane-id.ts
new file mode 100644
index 00000000000..75da3a6a232
--- /dev/null
+++ b/src/shared/stable-pane-id.ts
@@ -0,0 +1,45 @@
+// Why: paneKey crosses renderer reloads, PTY env, hook IPC, and retained UI
+// rows, so it must use the durable terminal-layout leaf UUID instead of the
+// renderer-local numeric PaneManager id.
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+declare const stablePaneIdBrand: unique symbol
+declare const terminalLeafIdBrand: unique symbol
+declare const paneKeyBrand: unique symbol
+
+export type StablePaneId = string & { readonly [stablePaneIdBrand]: true }
+export type TerminalLeafId = StablePaneId & { readonly [terminalLeafIdBrand]: true }
+export type PaneKey = string & { readonly [paneKeyBrand]: true }
+
+export function isStablePaneId(value: string): value is StablePaneId {
+  return UUID_RE.test(value)
+}
+
+export function isTerminalLeafId(value: string): value is TerminalLeafId {
+  return isStablePaneId(value)
+}
+
+export function makePaneKey(tabId: string, stableLeafId: string): PaneKey {
+  if (!tabId || tabId.includes(':')) {
+    throw new Error('tabId must be non-empty and must not contain ":"')
+  }
+  if (!isTerminalLeafId(stableLeafId)) {
+    throw new Error('stableLeafId must be a UUID')
+  }
+  return `${tabId}:${stableLeafId}` as PaneKey
+}
+
+export function parsePaneKey(
+  paneKey: string
+): { tabId: string; leafId: TerminalLeafId; stablePaneId: StablePaneId } | null {
+  const first = paneKey.indexOf(':')
+  if (first <= 0 || first !== paneKey.lastIndexOf(':') || first === paneKey.length - 1) {
+    return null
+  }
+  const tabId = paneKey.slice(0, first)
+  const leafId = paneKey.slice(first + 1)
+  if (!isTerminalLeafId(leafId)) {
+    return null
+  }
+  return { tabId, leafId, stablePaneId: leafId }
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index d2441f4e708..04eb6588dcc 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -3,6 +3,7 @@ import type { SshRemotePtyLease, SshTarget } from './ssh-types'
 import type { Automation, AutomationRun } from './automations-types'
 import type { WorkspaceSource } from './telemetry-events'
 import type { GitHubProjectSettings } from './github-project-types'
+import type { MigrationUnsupportedPtyEntry } from './agent-status-types'
 import type { VoiceSettings } from './speech-types'
 import type { GitLabProjectSettings } from './gitlab-types'
 
@@ -426,7 +427,7 @@ export type TerminalLayoutSnapshot = {
   ptyIdsByLeafId?: Record<string, string>
   /** Serialized terminal buffers per leaf for scrollback restoration on restart. */
   buffersByLeafId?: Record<string, string>
-  /** User-assigned pane titles, keyed by leafId (e.g. "pane:3").
+  /** User-assigned pane titles, keyed by stable layout leaf UUID.
    *  Persisted alongside buffers via the existing session:set flow. */
   titlesByLeafId?: Record<string, string>
 }
@@ -1801,6 +1802,7 @@ export type PersistedState = {
   workspaceSession: WorkspaceSessionState
   sshTargets: SshTarget[]
   sshRemotePtyLeases: SshRemotePtyLease[]
+  migrationUnsupportedPtyEntries: MigrationUnsupportedPtyEntry[]
   automations: Automation[]
   automationRuns: AutomationRun[]
   onboarding: OnboardingState
diff --git a/src/shared/workspace-session-schema.ts b/src/shared/workspace-session-schema.ts
index 2fd4eb3fa4b..97d40e72ab5 100644
--- a/src/shared/workspace-session-schema.ts
+++ b/src/shared/workspace-session-schema.ts
@@ -20,6 +20,10 @@ import { normalizeBrowserHistoryEntries } from './workspace-session-browser-hist
 // ─── Terminal pane layout (recursive) ───────────────────────────────
 
 const terminalPaneSplitDirectionSchema = z.enum(['vertical', 'horizontal'])
+const terminalTabIdSchema = z
+  .string()
+  .min(1)
+  .refine((value) => !value.includes(':'), 'terminal tab id must not contain ":"')
 
 // Why: z.lazy + type annotation keeps the recursive inference working without
 // forcing zod to resolve the whole tree at definition time.
@@ -51,7 +55,7 @@ const terminalLayoutSnapshotSchema = z.object({
 // ─── Terminal tab (legacy) ──────────────────────────────────────────
 
 const terminalTabSchema = z.object({
-  id: z.string(),
+  id: terminalTabIdSchema,
   ptyId: z.string().nullable(),
   worktreeId: z.string(),
   title: z.string(),
@@ -195,7 +199,7 @@ export const workspaceSessionStateSchema: z.ZodType<WorkspaceSessionState> = z.o
   activeWorktreeId: z.string().nullable(),
   activeTabId: z.string().nullable(),
   tabsByWorktree: z.record(z.string(), z.array(terminalTabSchema)),
-  terminalLayoutsByTabId: z.record(z.string(), terminalLayoutSnapshotSchema),
+  terminalLayoutsByTabId: z.record(terminalTabIdSchema, terminalLayoutSnapshotSchema),
   activeWorktreeIdsOnShutdown: z.array(z.string()).optional(),
   openFilesByWorktree: z.record(z.string(), z.array(persistedOpenFileSchema)).optional(),
   activeFileIdByWorktree: z.record(z.string(), z.string().nullable()).optional(),
@@ -210,7 +214,7 @@ export const workspaceSessionStateSchema: z.ZodType<WorkspaceSessionState> = z.o
   tabGroupLayouts: z.record(z.string(), tabGroupLayoutNodeSchema).optional(),
   activeGroupIdByWorktree: z.record(z.string(), z.string()).optional(),
   activeConnectionIdsAtShutdown: z.array(z.string()).optional(),
-  remoteSessionIdsByTabId: z.record(z.string(), z.string()).optional(),
+  remoteSessionIdsByTabId: z.record(terminalTabIdSchema, z.string()).optional(),
   // Why: the sort comparator in order-empty-query-worktrees.ts would produce
   // NaN (undefined sort order) if a corrupted session file carried NaN or
   // Infinity here. Parse leniently: drop individual bad entries rather than
diff --git a/tests/e2e/activity-agent-pane-isolation.spec.ts b/tests/e2e/activity-agent-pane-isolation.spec.ts
new file mode 100644
index 00000000000..6272b9d0d6d
--- /dev/null
+++ b/tests/e2e/activity-agent-pane-isolation.spec.ts
@@ -0,0 +1,382 @@
+/* eslint-disable max-lines -- Activity E2E keeps the setup helpers beside the split-pane, split-group, and workspace-card routing assertions they support. */
+import type { Page } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import {
+  splitActiveTerminalPane,
+  waitForActiveTerminalManager,
+  waitForPaneCount,
+  waitForPaneIdentitySnapshot,
+  type PaneIdentitySnapshot
+} from './helpers/terminal'
+import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+
+type SeededActivityThread = {
+  paneKey: string
+  leafId: string
+  prompt: string
+}
+
+type ActivityPaneVisibility = {
+  slotId: string | null
+  allLeafIds: string[]
+  visibleLeafIds: string[]
+}
+
+type ActivePaneSelection = {
+  activeWorktreeId: string | null
+  activeGroupId: string | null
+  activeTabId: string | null
+  activeLeafId: string | null
+  activePaneId: number | null
+}
+
+type SplitGroupTerminal = {
+  sourceGroupId: string
+  groupId: string
+  tabId: string
+}
+
+async function seedActivityThread(
+  page: Page,
+  thread: SeededActivityThread,
+  title: string,
+  state: 'blocked' | 'done',
+  message: string,
+  startedAt: number
+): Promise<void> {
+  await page.evaluate(
+    ({ thread, title, state, message, startedAt }) => {
+      const store = window.__store
+      if (!store) {
+        throw new Error('window.__store is not available')
+      }
+
+      store.getState().setAgentStatus(
+        thread.paneKey,
+        {
+          state,
+          prompt: thread.prompt,
+          agentType: 'codex',
+          lastAssistantMessage: message
+        },
+        title,
+        { updatedAt: startedAt, stateStartedAt: startedAt }
+      )
+    },
+    { thread, title, state, message, startedAt }
+  )
+}
+
+async function seedActivityThreadsForSplitPanes(
+  page: Page,
+  snapshot: PaneIdentitySnapshot
+): Promise<[SeededActivityThread, SeededActivityThread]> {
+  const [firstPane, secondPane] = snapshot.panes
+  if (!firstPane || !secondPane) {
+    throw new Error('Activity pane isolation test needs two split panes')
+  }
+
+  const now = Date.now()
+  const first: SeededActivityThread = {
+    paneKey: `${snapshot.tabId}:${firstPane.leafId}`,
+    leafId: firstPane.leafId,
+    prompt: `ACTIVITY_UUID_LEFT_${now}`
+  }
+  const second: SeededActivityThread = {
+    paneKey: `${snapshot.tabId}:${secondPane.leafId}`,
+    leafId: secondPane.leafId,
+    prompt: `ACTIVITY_UUID_RIGHT_${now}`
+  }
+
+  await seedActivityThread(
+    page,
+    first,
+    'Codex left pane',
+    'blocked',
+    'Left pane is waiting for user input.',
+    now - 2_000
+  )
+  await seedActivityThread(
+    page,
+    second,
+    'Codex right pane',
+    'done',
+    'Right pane finished its turn.',
+    now - 1_000
+  )
+
+  return [first, second]
+}
+
+async function readActivityPaneVisibility(page: Page): Promise<ActivityPaneVisibility> {
+  return page.evaluate(() => {
+    const slot = document.querySelector<HTMLElement>(
+      '[data-activity-terminal-slot-id]:not([aria-hidden="true"])'
+    )
+    if (!slot) {
+      return { slotId: null, allLeafIds: [], visibleLeafIds: [] }
+    }
+
+    const hasInlineDisplayNoneBetween = (element: HTMLElement, root: HTMLElement): boolean => {
+      let current: HTMLElement | null = element
+      while (current) {
+        if (current.style.display === 'none') {
+          return true
+        }
+        if (current === root) {
+          return false
+        }
+        current = current.parentElement
+      }
+      return false
+    }
+
+    const panes = Array.from(slot.querySelectorAll<HTMLElement>('[data-leaf-id]'))
+    return {
+      slotId: slot.dataset.activityTerminalSlotId ?? null,
+      allLeafIds: panes.map((pane) => pane.dataset.leafId ?? ''),
+      visibleLeafIds: panes
+        .filter((pane) => !hasInlineDisplayNoneBetween(pane, slot))
+        .map((pane) => pane.dataset.leafId ?? '')
+    }
+  })
+}
+
+async function enableInlineAgentCards(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('window.__store is not available')
+    }
+
+    const state = store.getState()
+    if (!state.worktreeCardProperties.includes('inline-agents')) {
+      state.toggleWorktreeCardProperty('inline-agents')
+    }
+    state.closeActivityPage()
+  })
+}
+
+async function clickWorkspaceCardAgentRow(page: Page, prompt: string): Promise<void> {
+  const rowLabel = page
+    .getByRole('group', { name: 'Agents' })
+    .locator(`span[title="${prompt}"]`)
+    .first()
+  await expect(rowLabel).toBeVisible({ timeout: 10_000 })
+  await rowLabel.click()
+}
+
+async function readActivePaneSelection(page: Page): Promise<ActivePaneSelection> {
+  return page.evaluate(() => {
+    const store = window.__store
+    if (!store) {
+      return {
+        activeWorktreeId: null,
+        activeGroupId: null,
+        activeTabId: null,
+        activeLeafId: null,
+        activePaneId: null
+      }
+    }
+
+    const state = store.getState()
+    const activeWorktreeId = state.activeWorktreeId ?? null
+    const activeGroupId = activeWorktreeId
+      ? (state.activeGroupIdByWorktree[activeWorktreeId] ?? null)
+      : null
+    const activeTabId = state.activeTabId ?? null
+    const activePane = activeTabId
+      ? (window.__paneManagers?.get(activeTabId)?.getActivePane?.() ?? null)
+      : null
+
+    return {
+      activeWorktreeId,
+      activeGroupId,
+      activeTabId,
+      activeLeafId: activePane?.leafId ?? null,
+      activePaneId: activePane?.id ?? null
+    }
+  })
+}
+
+async function createTerminalInNewSplitGroup(page: Page): Promise<SplitGroupTerminal> {
+  return page.evaluate(() => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('window.__store is not available')
+    }
+    const state = store.getState()
+    const worktreeId = state.activeWorktreeId
+    if (!worktreeId) {
+      throw new Error('No active worktree for split-group terminal setup')
+    }
+    const sourceGroupId =
+      state.activeGroupIdByWorktree[worktreeId] ?? state.groupsByWorktree[worktreeId]?.[0]?.id
+    if (!sourceGroupId) {
+      throw new Error('No source group for split-group terminal setup')
+    }
+
+    const groupId = state.createEmptySplitGroup(worktreeId, sourceGroupId, 'right')
+    if (!groupId) {
+      throw new Error('Failed to create split group')
+    }
+
+    const tab = state.createTab(worktreeId, groupId, undefined, { activate: true })
+    state.focusGroup(worktreeId, groupId)
+    state.setActiveTab(tab.id)
+    state.setActiveTabType('terminal')
+    return { sourceGroupId, groupId, tabId: tab.id }
+  })
+}
+
+test.describe('Activity Agent Pane Isolation', () => {
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+    await waitForActiveWorktree(orcaPage)
+    await ensureTerminalVisible(orcaPage)
+    const hasPaneManager = await waitForActiveTerminalManager(orcaPage, 30_000)
+      .then(() => true)
+      .catch(() => false)
+    test.skip(
+      !hasPaneManager,
+      'Electron automation in this environment never mounts the live TerminalPane manager, so Activity pane isolation would only fail on harness setup.'
+    )
+    await waitForPaneCount(orcaPage, 1, 30_000)
+  })
+
+  test('selecting agent rows isolates the matching split pane by stable leaf id', async ({
+    orcaPage
+  }) => {
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, 2)
+    const snapshot = await waitForPaneIdentitySnapshot(orcaPage, 2)
+    const [first, second] = await seedActivityThreadsForSplitPanes(orcaPage, snapshot)
+
+    await orcaPage.getByRole('button', { name: /Agents/ }).click()
+    await expect(orcaPage.getByText(first.prompt)).toBeVisible()
+    await expect(orcaPage.getByText(second.prompt)).toBeVisible()
+
+    await orcaPage.getByRole('button').filter({ hasText: first.prompt }).first().click()
+    await expect
+      .poll(async () => readActivityPaneVisibility(orcaPage), {
+        timeout: 10_000,
+        message: 'Activity did not isolate the first selected split pane'
+      })
+      .toMatchObject({
+        allLeafIds: expect.arrayContaining([first.leafId, second.leafId]),
+        visibleLeafIds: [first.leafId]
+      })
+
+    await orcaPage.getByRole('button').filter({ hasText: second.prompt }).first().click()
+    await expect
+      .poll(async () => readActivityPaneVisibility(orcaPage), {
+        timeout: 10_000,
+        message: 'Activity did not switch isolation to the second selected split pane'
+      })
+      .toMatchObject({
+        allLeafIds: expect.arrayContaining([first.leafId, second.leafId]),
+        visibleLeafIds: [second.leafId]
+      })
+  })
+
+  test('workspace card agent rows focus the matching terminal split pane', async ({ orcaPage }) => {
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, 2)
+    const snapshot = await waitForPaneIdentitySnapshot(orcaPage, 2)
+    const [first, second] = await seedActivityThreadsForSplitPanes(orcaPage, snapshot)
+
+    await enableInlineAgentCards(orcaPage)
+
+    await clickWorkspaceCardAgentRow(orcaPage, first.prompt)
+    await expect
+      .poll(async () => readActivePaneSelection(orcaPage), {
+        timeout: 10_000,
+        message: 'Workspace-card row did not focus the first split pane'
+      })
+      .toMatchObject({
+        activeTabId: snapshot.tabId,
+        activeLeafId: first.leafId
+      })
+
+    await clickWorkspaceCardAgentRow(orcaPage, second.prompt)
+    await expect
+      .poll(async () => readActivePaneSelection(orcaPage), {
+        timeout: 10_000,
+        message: 'Workspace-card row did not focus the second split pane'
+      })
+      .toMatchObject({
+        activeTabId: snapshot.tabId,
+        activeLeafId: second.leafId
+      })
+  })
+
+  test('workspace card agent rows focus the matching split-group terminal pane', async ({
+    orcaPage
+  }) => {
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, 2)
+    const firstGroupSnapshot = await waitForPaneIdentitySnapshot(orcaPage, 2)
+    const [first, second] = await seedActivityThreadsForSplitPanes(orcaPage, firstGroupSnapshot)
+
+    const splitGroup = await createTerminalInNewSplitGroup(orcaPage)
+    await waitForActiveTerminalManager(orcaPage, 30_000)
+    await waitForPaneCount(orcaPage, 1, 30_000)
+    const secondGroupSnapshot = await waitForPaneIdentitySnapshot(orcaPage, 1)
+    const secondGroupPane = secondGroupSnapshot.panes[0]
+    if (!secondGroupPane) {
+      throw new Error('Split-group terminal did not mount a pane')
+    }
+    const now = Date.now()
+    const splitGroupThread: SeededActivityThread = {
+      paneKey: `${secondGroupSnapshot.tabId}:${secondGroupPane.leafId}`,
+      leafId: secondGroupPane.leafId,
+      prompt: `ACTIVITY_UUID_SPLIT_GROUP_${now}`
+    }
+    await seedActivityThread(
+      orcaPage,
+      splitGroupThread,
+      'Codex split group pane',
+      'blocked',
+      'Split group pane is waiting for user input.',
+      now
+    )
+
+    await enableInlineAgentCards(orcaPage)
+
+    await clickWorkspaceCardAgentRow(orcaPage, splitGroupThread.prompt)
+    await expect
+      .poll(async () => readActivePaneSelection(orcaPage), {
+        timeout: 10_000,
+        message: 'Workspace-card row did not focus the split-group terminal pane'
+      })
+      .toMatchObject({
+        activeGroupId: splitGroup.groupId,
+        activeTabId: secondGroupSnapshot.tabId,
+        activeLeafId: splitGroupThread.leafId
+      })
+
+    await clickWorkspaceCardAgentRow(orcaPage, first.prompt)
+    await expect
+      .poll(async () => readActivePaneSelection(orcaPage), {
+        timeout: 10_000,
+        message: 'Workspace-card row did not return to the first split group'
+      })
+      .toMatchObject({
+        activeGroupId: splitGroup.sourceGroupId,
+        activeTabId: firstGroupSnapshot.tabId,
+        activeLeafId: first.leafId
+      })
+
+    await clickWorkspaceCardAgentRow(orcaPage, second.prompt)
+    await expect
+      .poll(async () => readActivePaneSelection(orcaPage), {
+        timeout: 10_000,
+        message: 'Workspace-card row did not focus the sibling pane after group switch'
+      })
+      .toMatchObject({
+        activeGroupId: splitGroup.sourceGroupId,
+        activeTabId: firstGroupSnapshot.tabId,
+        activeLeafId: second.leafId
+      })
+  })
+})
diff --git a/tests/e2e/helpers/terminal.ts b/tests/e2e/helpers/terminal.ts
index 70c3576b2b3..6b075f67422 100644
--- a/tests/e2e/helpers/terminal.ts
+++ b/tests/e2e/helpers/terminal.ts
@@ -1,6 +1,22 @@
+/* eslint-disable max-lines -- Terminal E2E helpers share one PaneManager-backed path for PTY IO, split actions, and stable pane identity snapshots. */
 import type { Page } from '@stablyai/playwright-test'
 import { expect } from '@stablyai/playwright-test'
 
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+export type PaneIdentitySnapshot = {
+  tabId: string
+  activeLeafId: string | null
+  panes: {
+    numericPaneId: number
+    leafId: string
+    stablePaneId: string
+    datasetLeafId: string | null
+    ptyId: string | null
+  }[]
+  ptyIdsByLeafId: Record<string, string>
+}
+
 // Why: worktree restoration can render the terminal surface before the legacy
 // global activeTabId settles. Prefer the active worktree's saved terminal tab
 // pointer, then fall back to the first terminal tab.
@@ -175,6 +191,117 @@ export async function discoverActivePtyId(page: Page): Promise<string> {
   return foundPtyId
 }
 
+export async function readPaneIdentitySnapshot(page: Page): Promise<PaneIdentitySnapshot | null> {
+  const tabId = await resolveActiveTabId(page)
+  if (!tabId) {
+    return null
+  }
+
+  return page.evaluate((tabId) => {
+    const manager = window.__paneManagers?.get(tabId)
+    const store = window.__store
+    if (!manager || !store) {
+      return null
+    }
+
+    const activePane = manager.getActivePane?.() ?? null
+    return {
+      tabId,
+      activeLeafId: activePane?.leafId ?? null,
+      panes: manager.getPanes().map((pane) => ({
+        numericPaneId: pane.id,
+        leafId: pane.leafId,
+        stablePaneId: pane.stablePaneId,
+        datasetLeafId: pane.container.dataset.leafId ?? null,
+        ptyId: pane.container.dataset.ptyId ?? null
+      })),
+      ptyIdsByLeafId: store.getState().terminalLayoutsByTabId[tabId]?.ptyIdsByLeafId ?? {}
+    }
+  }, tabId)
+}
+
+export async function waitForPaneIdentitySnapshot(
+  page: Page,
+  paneCount: number
+): Promise<PaneIdentitySnapshot> {
+  await expect
+    .poll(
+      async () => {
+        const snapshot = await readPaneIdentitySnapshot(page)
+        return Boolean(
+          snapshot &&
+          snapshot.panes.length === paneCount &&
+          snapshot.panes.every(
+            (pane) =>
+              UUID_RE.test(pane.leafId) &&
+              pane.stablePaneId === pane.leafId &&
+              pane.datasetLeafId === pane.leafId &&
+              pane.ptyId !== null &&
+              snapshot.ptyIdsByLeafId[pane.leafId] === pane.ptyId
+          )
+        )
+      },
+      {
+        timeout: 15_000,
+        message: 'Split terminal panes did not settle with UUID leaf-keyed PTY bindings'
+      }
+    )
+    .toBe(true)
+
+  const snapshot = await readPaneIdentitySnapshot(page)
+  if (!snapshot) {
+    throw new Error('Pane identity snapshot disappeared after settling')
+  }
+  return snapshot
+}
+
+export async function readTerminalPaneDomLeafOrder(page: Page): Promise<string[]> {
+  const snapshot = await readPaneIdentitySnapshot(page)
+  if (!snapshot) {
+    return []
+  }
+
+  return page.evaluate((tabId) => {
+    const manager = window.__paneManagers?.get(tabId)
+    if (!manager) {
+      return []
+    }
+    const paneElements = new Set(manager.getPanes().map((pane) => pane.container))
+    return Array.from(document.querySelectorAll<HTMLElement>('.pane[data-leaf-id]'))
+      .filter((element) => paneElements.has(element))
+      .map((element) => element.dataset.leafId ?? '')
+      .filter((leafId) => leafId.length > 0)
+  }, snapshot.tabId)
+}
+
+export async function moveTerminalPaneByLeafId(
+  page: Page,
+  sourceLeafId: string,
+  targetLeafId: string,
+  zone: 'top' | 'bottom' | 'left' | 'right'
+): Promise<void> {
+  const snapshot = await readPaneIdentitySnapshot(page)
+  if (!snapshot) {
+    throw new Error('moveTerminalPaneByLeafId: no active terminal tab')
+  }
+
+  await page.evaluate(
+    ({ tabId, sourceLeafId, targetLeafId, zone }) => {
+      const manager = window.__paneManagers?.get(tabId)
+      if (!manager) {
+        throw new Error('moveTerminalPaneByLeafId: active pane manager not ready')
+      }
+      const sourcePaneId = manager.getNumericIdForLeaf(sourceLeafId)
+      const targetPaneId = manager.getNumericIdForLeaf(targetLeafId)
+      if (sourcePaneId == null || targetPaneId == null) {
+        throw new Error('moveTerminalPaneByLeafId: source or target leaf is not mounted')
+      }
+      manager.movePane(sourcePaneId, targetPaneId, zone)
+    },
+    { tabId: snapshot.tabId, sourceLeafId, targetLeafId, zone }
+  )
+}
+
 export async function sendToTerminal(page: Page, ptyId: string, text: string): Promise<void> {
   await page.evaluate(
     ({ ptyId, text }) => {
diff --git a/tests/e2e/ssh-localhost.spec.ts b/tests/e2e/ssh-localhost.spec.ts
index 75aae779999..4fca1bc759c 100644
--- a/tests/e2e/ssh-localhost.spec.ts
+++ b/tests/e2e/ssh-localhost.spec.ts
@@ -3,6 +3,7 @@ import os from 'os'
 import { test, expect } from './helpers/orca-app'
 import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
 import {
+  UUID_RE,
   execInTerminal,
   waitForActivePanePtyId,
   waitForActiveTerminalManager,
@@ -196,8 +197,10 @@ test.describe('Localhost SSH', () => {
       if (!pane) {
         throw new Error('No active terminal pane')
       }
-      return `${tabId}:${pane.id}`
+      return `${tabId}:${pane.leafId}`
     })
+    const paneKeyLeafId = paneKey.slice(paneKey.indexOf(':') + 1)
+    expect(paneKeyLeafId).toMatch(UUID_RE)
 
     const terminalMarker = marker('LOCALHOST_SSH')
     await execInTerminal(orcaPage, ptyId, emitMarkerCommand(terminalMarker))
diff --git a/tests/e2e/terminal-panes.spec.ts b/tests/e2e/terminal-panes.spec.ts
index 2df63557eb9..3fd38b14cad 100644
--- a/tests/e2e/terminal-panes.spec.ts
+++ b/tests/e2e/terminal-panes.spec.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- Terminal pane E2E is a serial coverage matrix for split, close, remake, move, resize, and retention flows. */
 /**
  * E2E tests for terminal pane splitting, state retention, resizing, and closing.
  *
@@ -10,12 +11,16 @@
 
 import { test, expect } from './helpers/orca-app'
 import {
+  UUID_RE,
   discoverActivePtyId,
   execInTerminal,
   closeActiveTerminalPane,
   countVisibleTerminalPanes,
   focusLastTerminalPane,
+  moveTerminalPaneByLeafId,
+  readTerminalPaneDomLeafOrder,
   splitActiveTerminalPane,
+  waitForPaneIdentitySnapshot,
   waitForActiveTerminalManager,
   waitForTerminalOutput,
   waitForPaneCount,
@@ -93,6 +98,148 @@ test.describe('Terminal Panes', () => {
     expect(paneCountAfter).toBe(paneCountBefore + 1)
   })
 
+  test('split panes persist PTY bindings by stable UUID leaf id', async ({ orcaPage }) => {
+    const paneCountBefore = await countVisibleTerminalPanes(orcaPage)
+
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, paneCountBefore + 1)
+
+    const snapshot = await waitForPaneIdentitySnapshot(orcaPage, paneCountBefore + 1)
+    const leafIds = snapshot.panes.map((pane) => pane.leafId)
+    const ptyIds = snapshot.panes.map((pane) => pane.ptyId)
+
+    expect(new Set(leafIds).size).toBe(leafIds.length)
+    expect(new Set(ptyIds).size).toBe(ptyIds.length)
+    expect(Object.keys(snapshot.ptyIdsByLeafId).sort()).toEqual([...leafIds].sort())
+    expect(Object.keys(snapshot.ptyIdsByLeafId).every((leafId) => UUID_RE.test(leafId))).toBe(true)
+    expect(
+      snapshot.panes.some(
+        (pane) =>
+          String(pane.numericPaneId) === pane.leafId || `pane:${pane.numericPaneId}` === pane.leafId
+      )
+    ).toBe(false)
+  })
+
+  test('terminal process receives ORCA_PANE_KEY with the active UUID leaf id', async ({
+    orcaPage
+  }) => {
+    const snapshot = await waitForPaneIdentitySnapshot(orcaPage, 1)
+    const activeLeafId = snapshot.activeLeafId ?? snapshot.panes[0]?.leafId
+    if (!activeLeafId) {
+      throw new Error('No active pane leaf id found')
+    }
+
+    const expectedPaneKey = `${snapshot.tabId}:${activeLeafId}`
+    const ptyId = await discoverActivePtyId(orcaPage)
+    const marker = `ORCA_PANE_KEY_E2E_${Date.now()}`
+
+    await execInTerminal(orcaPage, ptyId, `printf '${marker}=%s\\n' "$ORCA_PANE_KEY"`)
+    await waitForTerminalOutput(orcaPage, `${marker}=${expectedPaneKey}`)
+
+    expect(activeLeafId).toMatch(UUID_RE)
+  })
+
+  test('closing a split pane prunes its leaf-keyed PTY binding without remapping siblings', async ({
+    orcaPage
+  }) => {
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, 2)
+    await splitActiveTerminalPane(orcaPage, 'horizontal')
+    await waitForPaneCount(orcaPage, 3)
+
+    const beforeClose = await waitForPaneIdentitySnapshot(orcaPage, 3)
+    const closedLeafId = beforeClose.activeLeafId ?? beforeClose.panes.at(-1)?.leafId
+    if (!closedLeafId) {
+      throw new Error('No active split pane leaf id found before close')
+    }
+    const survivingLeafIds = beforeClose.panes
+      .map((pane) => pane.leafId)
+      .filter((leafId) => leafId !== closedLeafId)
+
+    await closeActiveTerminalPane(orcaPage)
+    await waitForPaneCount(orcaPage, 2)
+
+    const afterClose = await waitForPaneIdentitySnapshot(orcaPage, 2)
+    expect(afterClose.panes.map((pane) => pane.leafId).sort()).toEqual(survivingLeafIds.sort())
+    expect(Object.keys(afterClose.ptyIdsByLeafId).sort()).toEqual(survivingLeafIds.sort())
+    expect(afterClose.ptyIdsByLeafId[closedLeafId]).toBeUndefined()
+  })
+
+  test('closing and remaking right/down splits keeps surviving leaf-keyed bindings stable', async ({
+    orcaPage
+  }) => {
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, 2)
+    await splitActiveTerminalPane(orcaPage, 'horizontal')
+    await waitForPaneCount(orcaPage, 3)
+
+    const beforeClose = await waitForPaneIdentitySnapshot(orcaPage, 3)
+    const closedLeafId = beforeClose.activeLeafId ?? beforeClose.panes.at(-1)?.leafId
+    if (!closedLeafId) {
+      throw new Error('No active split pane leaf id found before close/remake')
+    }
+    const survivingBindings = Object.fromEntries(
+      beforeClose.panes
+        .filter((pane) => pane.leafId !== closedLeafId)
+        .map((pane) => [pane.leafId, pane.ptyId])
+    )
+
+    await closeActiveTerminalPane(orcaPage)
+    await waitForPaneCount(orcaPage, 2)
+
+    const afterClose = await waitForPaneIdentitySnapshot(orcaPage, 2)
+    expect(Object.keys(afterClose.ptyIdsByLeafId).sort()).toEqual(
+      Object.keys(survivingBindings).sort()
+    )
+    for (const [leafId, ptyId] of Object.entries(survivingBindings)) {
+      expect(afterClose.ptyIdsByLeafId[leafId]).toBe(ptyId)
+    }
+    expect(afterClose.ptyIdsByLeafId[closedLeafId]).toBeUndefined()
+
+    await splitActiveTerminalPane(orcaPage, 'horizontal')
+    await waitForPaneCount(orcaPage, 3)
+
+    const afterRemake = await waitForPaneIdentitySnapshot(orcaPage, 3)
+    const remadeLeafIds = afterRemake.panes.map((pane) => pane.leafId)
+    expect(remadeLeafIds).not.toContain(closedLeafId)
+    for (const [leafId, ptyId] of Object.entries(survivingBindings)) {
+      expect(afterRemake.ptyIdsByLeafId[leafId]).toBe(ptyId)
+    }
+    expect(new Set(remadeLeafIds).size).toBe(3)
+  })
+
+  test('moving panes through the drag-drop handler preserves leaf-keyed PTY bindings', async ({
+    orcaPage
+  }) => {
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, 2)
+    await splitActiveTerminalPane(orcaPage, 'horizontal')
+    await waitForPaneCount(orcaPage, 3)
+
+    const beforeMove = await waitForPaneIdentitySnapshot(orcaPage, 3)
+    const beforeOrder = await readTerminalPaneDomLeafOrder(orcaPage)
+    const source = beforeMove.panes.at(-1)
+    const target = beforeMove.panes[0]
+    if (!source || !target) {
+      throw new Error('Need source and target panes for move test')
+    }
+    const bindingsBefore = { ...beforeMove.ptyIdsByLeafId }
+
+    await moveTerminalPaneByLeafId(orcaPage, source.leafId, target.leafId, 'left')
+
+    await expect
+      .poll(async () => readTerminalPaneDomLeafOrder(orcaPage), {
+        timeout: 10_000,
+        message: 'Pane drag-drop move did not update DOM order'
+      })
+      .not.toEqual(beforeOrder)
+
+    const afterMove = await waitForPaneIdentitySnapshot(orcaPage, 3)
+    const afterLeafIds = afterMove.panes.map((pane) => pane.leafId).sort()
+    expect(afterLeafIds).toEqual(beforeMove.panes.map((pane) => pane.leafId).sort())
+    expect(afterMove.ptyIdsByLeafId).toEqual(bindingsBefore)
+  })
+
   /**
    * User Prompt:
    * - terminal panes retain state when switching tabs and when you make / close a pane / switch worktrees
@@ -280,6 +427,52 @@ test.describe('Terminal Panes', () => {
       .toBe(true)
   })
 
+  test('@headful dragging terminal panes around preserves leaf-keyed PTY bindings', async ({
+    orcaPage
+  }) => {
+    await splitActiveTerminalPane(orcaPage, 'vertical')
+    await waitForPaneCount(orcaPage, 2)
+    await splitActiveTerminalPane(orcaPage, 'horizontal')
+    await waitForPaneCount(orcaPage, 3)
+
+    const beforeDrag = await waitForPaneIdentitySnapshot(orcaPage, 3)
+    const beforeOrder = await readTerminalPaneDomLeafOrder(orcaPage)
+    const source = beforeDrag.panes.at(-1)
+    const target = beforeDrag.panes[0]
+    if (!source || !target) {
+      throw new Error('Need source and target panes for drag test')
+    }
+
+    const sourceHandle = orcaPage.locator(
+      `.pane[data-leaf-id="${source.leafId}"] .pane-drag-handle`
+    )
+    await expect(sourceHandle).toBeVisible({ timeout: 3_000 })
+    const sourceBox = await sourceHandle.boundingBox()
+    const targetBox = await orcaPage.locator(`.pane[data-leaf-id="${target.leafId}"]`).boundingBox()
+    expect(sourceBox).not.toBeNull()
+    expect(targetBox).not.toBeNull()
+
+    await orcaPage.mouse.move(sourceBox!.x + sourceBox!.width / 2, sourceBox!.y + 4)
+    await orcaPage.mouse.down()
+    await orcaPage.mouse.move(targetBox!.x + 8, targetBox!.y + targetBox!.height / 2, {
+      steps: 20
+    })
+    await orcaPage.mouse.up()
+
+    await expect
+      .poll(async () => readTerminalPaneDomLeafOrder(orcaPage), {
+        timeout: 10_000,
+        message: 'Real pane drag did not update DOM order'
+      })
+      .not.toEqual(beforeOrder)
+
+    const afterDrag = await waitForPaneIdentitySnapshot(orcaPage, 3)
+    expect(afterDrag.panes.map((pane) => pane.leafId).sort()).toEqual(
+      beforeDrag.panes.map((pane) => pane.leafId).sort()
+    )
+    expect(afterDrag.ptyIdsByLeafId).toEqual(beforeDrag.ptyIdsByLeafId)
+  })
+
   /**
    * User Prompt:
    * - closing panes works
diff --git a/tests/e2e/worktree-smart-sort.spec.ts b/tests/e2e/worktree-smart-sort.spec.ts
index 0430f5fa3c9..f68e949e58b 100644
--- a/tests/e2e/worktree-smart-sort.spec.ts
+++ b/tests/e2e/worktree-smart-sort.spec.ts
@@ -1,5 +1,6 @@
 import { test, expect } from './helpers/orca-app'
 import type { Page } from '@stablyai/playwright-test'
+import type { TerminalPaneLayoutNode } from '../../src/shared/types'
 import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
 
 type SmartSortScenario = {
@@ -85,31 +86,72 @@ async function seedSmartSortScenario(page: Page): Promise<SmartSortScenario> {
       throw new Error('Smart sort E2E failed to create terminal tabs')
     }
 
+    const blockedPtyId = stateWithTabs.ptyIdsByTabId[blockedTab.id]?.[0] ?? `e2e-${blockedTab.id}`
+    const donePtyId = stateWithTabs.ptyIdsByTabId[doneTab.id]?.[0] ?? `e2e-${doneTab.id}`
+    const firstLayoutLeafId = (node: TerminalPaneLayoutNode | null | undefined): string | null => {
+      if (!node) {
+        return null
+      }
+      return node.type === 'leaf'
+        ? node.leafId
+        : (firstLayoutLeafId(node.first) ?? firstLayoutLeafId(node.second))
+    }
+    let blockedLeafId = ''
+    let doneLeafId = ''
+
     // Why: WorktreeList intentionally holds cold-start ordering until a live
     // PTY exists. E2E hidden windows can create tabs before panes mount, so
-    // seed the live-PTY map explicitly and let agent-status writes drive the
-    // same sortEpoch path that hook events use in the app.
-    store.setState((current) => ({
-      ptyIdsByTabId: {
-        ...current.ptyIdsByTabId,
-        [blockedTab.id]: current.ptyIdsByTabId[blockedTab.id]?.length
-          ? current.ptyIdsByTabId[blockedTab.id]
-          : [`e2e-${blockedTab.id}`],
-        [doneTab.id]: current.ptyIdsByTabId[doneTab.id]?.length
-          ? current.ptyIdsByTabId[doneTab.id]
-          : [`e2e-${doneTab.id}`]
+    // seed the live-PTY and stable-layout maps explicitly and let agent-status
+    // writes drive the same sortEpoch path that hook events use in the app.
+    store.setState((current) => {
+      const blockedLayout = current.terminalLayoutsByTabId[blockedTab.id]
+      const doneLayout = current.terminalLayoutsByTabId[doneTab.id]
+      blockedLeafId = firstLayoutLeafId(blockedLayout?.root) ?? crypto.randomUUID()
+      doneLeafId = firstLayoutLeafId(doneLayout?.root) ?? crypto.randomUUID()
+
+      return {
+        ptyIdsByTabId: {
+          ...current.ptyIdsByTabId,
+          [blockedTab.id]: current.ptyIdsByTabId[blockedTab.id]?.length
+            ? current.ptyIdsByTabId[blockedTab.id]
+            : [blockedPtyId],
+          [doneTab.id]: current.ptyIdsByTabId[doneTab.id]?.length
+            ? current.ptyIdsByTabId[doneTab.id]
+            : [donePtyId]
+        },
+        terminalLayoutsByTabId: {
+          ...current.terminalLayoutsByTabId,
+          [blockedTab.id]: {
+            root: blockedLayout?.root ?? { type: 'leaf', leafId: blockedLeafId },
+            activeLeafId: blockedLayout?.activeLeafId ?? blockedLeafId,
+            expandedLeafId: blockedLayout?.expandedLeafId ?? null,
+            ptyIdsByLeafId: {
+              ...blockedLayout?.ptyIdsByLeafId,
+              [blockedLeafId]: blockedPtyId
+            }
+          },
+          [doneTab.id]: {
+            root: doneLayout?.root ?? { type: 'leaf', leafId: doneLeafId },
+            activeLeafId: doneLayout?.activeLeafId ?? doneLeafId,
+            expandedLeafId: doneLayout?.expandedLeafId ?? null,
+            ptyIdsByLeafId: {
+              ...doneLayout?.ptyIdsByLeafId,
+              [doneLeafId]: donePtyId
+            }
+          }
+        }
       }
-    }))
+    })
 
     const actions = store.getState()
     actions.setAgentStatus(
-      `${doneTab.id}:1`,
+      `${doneTab.id}:${doneLeafId}`,
       { state: 'done', prompt: 'Finished', agentType: 'codex' },
       'codex',
       { updatedAt: now, stateStartedAt: now - 1_000 }
     )
     actions.setAgentStatus(
-      `${blockedTab.id}:1`,
+      `${blockedTab.id}:${blockedLeafId}`,
       { state: 'blocked', prompt: 'Needs approval', agentType: 'codex' },
       'codex',
       { updatedAt: now, stateStartedAt: now - 60_000 }

From 6c4bcf7ea6a4c2bc434c0456177c1db611f55ef5 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 15 May 2026 15:32:07 -0400
Subject: [PATCH 56/82] feat(ssh): make remote workspaces first-class (#1876)

Co-authored-by: Orca <help@stably.ai>
---
 .github/workflows/computer-e2e.yml            |  14 +
 config/electron-builder.config.cjs            |  10 +
 docs/design/ssh-remote-workspace-sync-plan.md | 198 +++++++++
 src/main/github/client-issue-source.test.ts   |  38 +-
 src/main/github/client-pr-checks.test.ts      |   7 +-
 src/main/github/client-work-items.test.ts     |   5 +
 src/main/github/client.test.ts                |  20 +-
 src/main/github/client.ts                     | 260 ++++++++----
 src/main/github/gh-utils.test.ts              |  41 +-
 src/main/github/gh-utils.ts                   |  83 +++-
 src/main/github/issues.ts                     |  74 ++--
 src/main/github/work-item-details.test.ts     |  51 ++-
 src/main/github/work-item-details.ts          | 133 +++---
 src/main/ipc/filesystem-watcher.test.ts       |  47 ++-
 src/main/ipc/filesystem-watcher.ts            |  81 ++--
 src/main/ipc/github-work-item-args.test.ts    |  32 +-
 src/main/ipc/github-work-item-args.ts         |  16 +-
 src/main/ipc/github.test.ts                   |  34 +-
 src/main/ipc/github.ts                        | 169 +++++---
 src/main/ipc/hosted-review.ts                 |  12 +-
 src/main/ipc/remote-workspace-events.ts       |  24 ++
 src/main/ipc/remote-workspace-namespace.ts    |  12 +
 src/main/ipc/remote-workspace.test.ts         |  87 ++++
 src/main/ipc/remote-workspace.ts              | 385 ++++++++++++++++++
 src/main/ipc/ssh.ts                           |  15 +-
 src/main/ipc/worktree-remote.ts               | 127 +++++-
 src/main/ipc/worktrees.test.ts                |  18 +-
 src/main/ipc/worktrees.ts                     |  51 ++-
 src/main/runtime/orca-runtime.ts              |   4 +
 src/main/runtime/rpc/methods/worktree.ts      |   2 +
 src/main/source-control/hosted-review.test.ts |   2 +-
 src/main/source-control/hosted-review.ts      |  10 +-
 src/main/ssh/ssh-channel-multiplexer.ts       |  10 +-
 src/main/ssh/ssh-relay-deploy.ts              |  60 +--
 .../ssh/ssh-relay-native-deps-install.test.ts |   2 +-
 src/main/ssh/ssh-relay-session.ts             |   8 +
 .../window/attach-main-window-services.ts     |   2 +
 src/preload/api-types.ts                      |  77 +++-
 src/preload/index.ts                          |  65 ++-
 src/relay/agent-exec-handler.test.ts          |  20 +-
 src/relay/client-request-aborts.ts            |  33 ++
 src/relay/dispatcher.test.ts                  |  51 ++-
 src/relay/dispatcher.ts                       | 235 ++++++++---
 src/relay/fs-handler.test.ts                  | 158 ++++++-
 src/relay/fs-handler.ts                       |  68 +++-
 src/relay/pty-handler.ts                      |   3 +
 src/relay/relay.ts                            |  64 ++-
 src/relay/workspace-session-handler.test.ts   | 142 +++++++
 src/relay/workspace-session-handler.ts        | 187 +++++++++
 src/renderer/src/App.tsx                      |  60 ++-
 .../src/components/GitHubItemDialog.tsx       | 248 ++++-------
 src/renderer/src/components/TaskPage.tsx      |  13 +-
 .../src/components/WorktreeJumpPalette.tsx    |  65 +--
 .../github-project/ProjectViewWrapper.tsx     |  10 +-
 .../new-workspace/SmartWorkspaceNameField.tsx | 153 ++-----
 .../components/right-sidebar/ChecksPanel.tsx  |  87 ++--
 .../components/right-sidebar/PRActions.tsx    |  21 +-
 .../right-sidebar/SourceControl.tsx           |  18 +-
 .../right-sidebar/useGitStatusPolling.test.ts |  58 ++-
 .../right-sidebar/useGitStatusPolling.ts      |  22 +-
 .../src/components/settings/SshPane.tsx       |  28 +-
 .../src/components/settings/SshTargetForm.tsx |  47 ++-
 .../src/components/sidebar/WorktreeCard.tsx   |  18 +-
 .../status-bar/SshStatusSegment.tsx           | 120 +++++-
 src/renderer/src/hooks/useComposerState.ts    |  78 ++--
 src/renderer/src/hooks/useIpcEvents.test.ts   | 101 ++++-
 src/renderer/src/hooks/useIpcEvents.ts        | 346 +++++++++++++++-
 src/renderer/src/hooks/useIssueMetadata.ts    |  52 +--
 .../src/lib/launch-work-item-direct.ts        |  21 +-
 src/renderer/src/lib/new-workspace.ts         |   3 +
 src/renderer/src/lib/repo-slug-index.ts       |  20 +-
 .../src/lib/session-write-subscriber.test.ts  |  39 ++
 .../src/lib/session-write-subscriber.ts       |   9 +
 src/renderer/src/store/slices/github.test.ts  |  33 +-
 src/renderer/src/store/slices/github.ts       | 269 +++++-------
 .../src/store/slices/hosted-review.test.ts    |   1 +
 .../src/store/slices/hosted-review.ts         |  12 +-
 src/renderer/src/store/slices/ssh.ts          |  50 ++-
 .../src/store/slices/worktree-helpers.ts      |   3 +-
 .../src/store/slices/worktrees.test.ts        |  12 +-
 src/renderer/src/store/slices/worktrees.ts    |   9 +-
 src/shared/hosted-review.ts                   |   1 +
 ...emote-workspace-session-projection.test.ts | 120 ++++++
 .../remote-workspace-session-projection.ts    | 184 +++++++++
 src/shared/remote-workspace-types.ts          |  54 +++
 src/shared/ssh-types.ts                       |   6 +
 src/shared/types.ts                           |   1 +
 87 files changed, 4352 insertions(+), 1287 deletions(-)
 create mode 100644 docs/design/ssh-remote-workspace-sync-plan.md
 create mode 100644 src/main/ipc/remote-workspace-events.ts
 create mode 100644 src/main/ipc/remote-workspace-namespace.ts
 create mode 100644 src/main/ipc/remote-workspace.test.ts
 create mode 100644 src/main/ipc/remote-workspace.ts
 create mode 100644 src/relay/client-request-aborts.ts
 create mode 100644 src/relay/workspace-session-handler.test.ts
 create mode 100644 src/relay/workspace-session-handler.ts
 create mode 100644 src/shared/remote-workspace-session-projection.test.ts
 create mode 100644 src/shared/remote-workspace-session-projection.ts
 create mode 100644 src/shared/remote-workspace-types.ts

diff --git a/.github/workflows/computer-e2e.yml b/.github/workflows/computer-e2e.yml
index 6d68765f903..33645a3c253 100644
--- a/.github/workflows/computer-e2e.yml
+++ b/.github/workflows/computer-e2e.yml
@@ -40,6 +40,14 @@ jobs:
           run_install: false
       - if: runner.os == 'Linux'
         run: sudo apt-get update && sudo apt-get install -y python3 python3-gi gir1.2-atspi-2.0 at-spi2-core xclip xdotool
+      # Why: pnpm's bundled node-gyp can ship gyp_main.py without execute
+      # permission on Linux runners; node-pty's install fallback then fails
+      # before this smoke job can exercise the native package.
+      - name: Use external node-gyp to avoid pnpm's bundled copy (Linux only)
+        if: runner.os == 'Linux'
+        run: |
+          npm install -g node-gyp@11.5.0
+          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
       - run: pnpm install --frozen-lockfile
       - run: pnpm verify:computer-native
       - run: pnpm build:cli
@@ -80,6 +88,12 @@ jobs:
         with:
           run_install: false
       - run: sudo apt-get update && sudo apt-get install -y build-essential python3 python3-gi gir1.2-atspi-2.0 gedit at-spi2-core xvfb xclip xdotool
+      # Why: keep scheduled Linux e2e on the same native install path as PR
+      # smoke and pr.yml's verify job.
+      - name: Use external node-gyp to avoid pnpm's bundled copy (Linux only)
+        run: |
+          npm install -g node-gyp@11.5.0
+          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
       - run: pnpm install --frozen-lockfile
       - run: pnpm verify:computer-native
       - run: pnpm build:cli
diff --git a/config/electron-builder.config.cjs b/config/electron-builder.config.cjs
index e1a63218fe7..87e87a92fc1 100644
--- a/config/electron-builder.config.cjs
+++ b/config/electron-builder.config.cjs
@@ -7,6 +7,13 @@ const featureWallResources = {
   from: 'resources/onboarding/feature-wall',
   to: 'onboarding/feature-wall'
 }
+// Why: SSH relay deploy resolves bundles from process.resourcesPath in packaged
+// apps. Keeping relay assets as extraResources makes them real directories
+// instead of paths hidden inside app.asar.
+const relayExtraResource = {
+  from: 'out/relay',
+  to: 'relay'
+}
 
 /** @type {import('electron-builder').Configuration} */
 module.exports = {
@@ -85,6 +92,7 @@ module.exports = {
   win: {
     executableName: 'Orca',
     extraResources: [
+      relayExtraResource,
       {
         from: 'resources/win32/bin/orca.cmd',
         to: 'bin/orca.cmd'
@@ -138,6 +146,7 @@ module.exports = {
     hardenedRuntime: isMacRelease,
     notarize: isMacRelease,
     extraResources: [
+      relayExtraResource,
       {
         from: 'resources/darwin/bin/orca',
         to: 'bin/orca'
@@ -174,6 +183,7 @@ module.exports = {
     // The Linux installer should not claim those system package/file names.
     executableName: 'orca-ide',
     extraResources: [
+      relayExtraResource,
       {
         from: 'resources/linux/bin/orca',
         to: 'bin/orca'
diff --git a/docs/design/ssh-remote-workspace-sync-plan.md b/docs/design/ssh-remote-workspace-sync-plan.md
new file mode 100644
index 00000000000..7b3e9929453
--- /dev/null
+++ b/docs/design/ssh-remote-workspace-sync-plan.md
@@ -0,0 +1,198 @@
+# SSH Remote Workspace Sync Plan
+
+Planning note for refreshing PR #1690 against current `main`. This is not a merge plan for #1690; current `main` already owns same-client SSH PTY persistence through durable remote PTY leases, relay grace reconnect, explicit expired-session behavior, and provider cleanup semantics.
+
+## Product Boundary
+
+Orca should support an opt-in mode for an SSH target where terminal workspace chrome for that target is stored on the remote host and can be restored by another Orca client connecting to the same target.
+
+In scope:
+
+- Per-SSH-target remote workspace snapshots: terminal tabs, split layouts, active worktree/tab state, and remote PTY IDs needed to reattach live relay PTYs.
+- Device presence for clients currently connected to the same synced target.
+- Cross-client PTY reattach when the remote relay still owns the PTY.
+- Conflict-safe snapshot writes with revisions and stale-write handling.
+- Packaged app relay asset lookup and deployment reliability.
+
+Out of scope:
+
+- A general cloud sync service.
+- Syncing local repos, local PTYs, local browser runtime state, credentials, secrets, shell history, or local filesystem paths.
+- Guaranteed survival after the remote relay/host process exits.
+- Automatic agent recovery as core PTY persistence.
+
+Keep explicit/user-driven:
+
+- Enabling sync per SSH target.
+- Terminating remote sessions through an explicit destructive action. Normal disconnect detaches only.
+- Resuming expired Claude/Codex agent sessions. Show an affordance using stored metadata; do not auto-inject resume commands into a shell.
+- Resolving true conflicts that cannot be merged by target/worktree scope.
+
+## Gap Analysis
+
+Already covered on current `main`:
+
+- Same-client SSH PTY survival across close/quit/reconnect through `activeConnectionIdsAtShutdown`, `remoteSessionIdsByTabId`, durable `SshRemotePtyLease` records, relay grace reconnect, and renderer deferred reattach.
+- Explicit expired-session behavior: failed `pty.attach` marks leases expired and the renderer starts from the expired state rather than silently pretending the old process survived.
+- Provider absence and relay teardown semantics: disconnect detaches, terminate/remove is destructive, and provider registration/ownership are centralized in `SshRelaySession`/`pty.ts`.
+- Relay-side PTY buffering, attach, shutdown, and grace timers.
+
+#1690 adds beyond that:
+
+- Relay-side `workspace.*` RPCs and JSON snapshot storage on the remote host.
+- A target-scoped session filter and scoped merge so one target's snapshot does not overwrite unrelated local/remote workspaces.
+- Remote workspace IPC (`remoteWorkspace:*`) and preload API.
+- Renderer hydration of remote snapshots and event-driven application of `workspace.changed`.
+- Device presence polling and status UI.
+- Multi-client relay dispatcher/socket support so more than one Orca client can talk to the same relay daemon.
+- Resize ownership logic so background clients do not resize a shared remote PTY.
+- Packaged relay asset lookup through `process.resourcesPath`/`extraResources`.
+- Agent resume metadata tied to pane keys. This remains deferred for this implementation.
+
+Now redundant or risky from #1690:
+
+- Do not copy the renderer terminal restore changes wholesale. They overlap directly with recently stabilized `reconnectPersistedTerminals`, deferred SSH session IDs, split-leaf PTY mappings, and expired-session handling.
+- Do not replace same-client persistence with relay snapshots. Local workspace session remains the source of truth for classic SSH targets and for non-synced targets.
+- Do not default sync to on for existing or new targets until product decides retention/privacy behavior.
+- Do not use unlimited relay lifetime as an implicit consequence of sync without a visible setting and cleanup story.
+- Do not auto-run agent resume commands after an expired PTY.
+
+## Fresh Architecture
+
+Use two separate layers:
+
+1. **Local session persistence remains authoritative for this Orca install.** It continues to write normal workspace sessions and durable SSH PTY leases exactly as current `main` does.
+2. **Remote workspace sync is an opt-in target-level overlay.** When enabled and connected, Orca pushes only that target's scoped workspace slice to the relay and hydrates only that target's slice from the relay.
+
+Data ownership:
+
+- Main process owns target configuration, active SSH sessions, remote workspace IPC, snapshot revision checks, ID translation, and old-relay compatibility handling.
+- Relay owns synced snapshot storage under a per-user remote directory, keyed by a sanitized namespace derived from stable target identity.
+- Renderer owns local Zustand workspace state and applies remote snapshots only through a guarded hydration path.
+- PTY lifetime remains owned by the relay and current `SshRemotePtyLease`/PTY ownership maps. Remote snapshots store PTY IDs as references, not as process ownership.
+
+Remote snapshot shape:
+
+- `namespace`, `revision`, `updatedAt`, `schemaVersion`, `clientId`, and `session`.
+- `session` is an explicit v1 projection, not raw `WorkspaceSessionState`.
+- v1 includes only terminal/worktree state, keyed by stable remote worktree path. Import/export translates between remote worktree paths and local `repoId::path` IDs at the main/renderer boundary.
+- Editor/browser chrome, browser URL history, browser profile IDs, and global active connection IDs are excluded from v1 to avoid syncing local-install identifiers or privacy-sensitive local state.
+- Additive fields are okay; wrong-typed core fields must fall back safely.
+
+Sync flow:
+
+- On connect for sync-enabled target: register providers, fetch worktrees, fetch `workspace.get`, translate remote path IDs to local worktree IDs, scope-merge into local state, then let existing terminal reattach paths consume the resulting PTY IDs.
+- Local state remains authoritative immediately after startup. A remote snapshot is applied only if this target has no local dirty state newer than the last synced revision, or the user explicitly refreshes from remote.
+- On local session write: if workspace session is ready and the target was hydrated, export only that target's terminal/worktree slice using remote worktree paths and `workspace.patch` with the last known revision.
+- On stale revision: if both local and newer remote touched the same worktree since the base revision, set conflict state. Otherwise preserve out-of-scope/untouched remote state, merge local touched worktrees, and retry once.
+- On relay `workspace.changed`: ignore self-originated events, queue per target, apply only newer revisions, and avoid triggering a resize unless there is trusted local foreground intent.
+
+Failure semantics:
+
+- Old relay without `workspace.*`: keep classic SSH behavior, mark sync "unavailable until reconnect/update", and do not fail SSH connection.
+- Remote snapshot parse failure: ignore the remote snapshot, leave local session intact, and show sync error for that target.
+- Patch failure: keep local session as-is and retry on next session write or reconnect.
+- Expired PTY referenced by remote snapshot: use the current expired-session path; do not silently replace with a live shell unless the existing UI path already does that intentionally.
+- Explicit disconnect keeps remote PTYs according to current detach semantics. `Terminate remote sessions` kills PTYs. Target removal is destructive after confirmation and must clear or tombstone that target's synced PTY references.
+
+## Phased Implementation Plan
+
+1. **Relay packaging and compatibility PR**
+   - Add relay `extraResources` packaging and `getLocalRelayCandidates(platform)` lookup using `process.resourcesPath`.
+   - Keep current dev path and `ORCA_RELAY_PATH`.
+   - Add tests for packaged candidate order and missing package diagnostics.
+
+2. **Target setting and main IPC skeleton PR**
+   - Add `remoteWorkspaceSyncEnabled` and bounded `remoteWorkspaceSyncGracePeriodSeconds` to `SshTarget`.
+   - Default to false unless product explicitly chooses otherwise.
+   - Add preload/main `remoteWorkspace:*` IPC behind feature availability.
+   - No renderer hydration yet; verify old targets normalize cleanly.
+
+3. **Relay workspace snapshot RPC PR**
+   - Add relay `workspace.get`, `workspace.patch`, and `workspace.presence`.
+   - Store snapshots atomically under a user-private remote directory.
+   - Include namespace sanitization, revisions, schema version, and stale-revision responses.
+   - Wire old-relay method-not-found handling in main as "sync unavailable", not connection failure.
+
+4. **Projected session filtering/merge PR**
+   - Implement target-scoped session extraction in main using repo `connectionId`.
+   - Export/import terminal workspace state through a path-keyed projected schema.
+   - Implement merge that replaces only known in-scope worktrees and preserves out-of-scope remote state.
+   - Cover terminal tabs, split layouts, active IDs, `remoteSessionIdsByTabId`, and last-visited timestamps. Defer editor/browser chrome.
+
+5. **Renderer guarded hydrate/push PR**
+   - Fetch synced snapshots only after target worktrees are loaded.
+   - Apply snapshots through a remote-hydration guard and per-target queue.
+   - Push snapshots from the existing debounced session writer only for hydrated, connected, sync-enabled targets.
+   - Reuse existing `reconnectPersistedTerminals`; only feed it scoped remote session IDs.
+   - Do not enable live cross-client PTY attach unless the multi-client dispatcher and resize ownership from phase 6 are also present.
+
+6. **Multi-client relay + resize ownership PR**
+   - Extend relay dispatcher/socket bridge to support independent client frame state.
+   - Broadcast notifications to all clients, but keep request/response routing per client.
+   - Add foreground/local-intent resize ownership so background hydration or non-focused clients do not resize shared PTYs.
+   - Treat mobile fit locks and current PTY locks as higher priority than desktop resize.
+
+7. **Presence and status UI PR**
+   - Add lightweight presence polling and status display for sync-enabled connected targets.
+   - Show sync phase: idle, pulling, pushing, synced, conflict, error, unavailable/offline.
+   - Follow `docs/STYLEGUIDE.md` tokens and existing status bar patterns.
+
+8. **Agent resume metadata polish PR**
+   - Persist provider/session/cwd metadata as recovery hints only.
+   - Add an explicit "Resume Claude/Codex session" action when a synced PTY expired.
+   - Avoid auto-sending commands on mount or after snapshot hydration.
+
+## Test Plan
+
+Unit:
+
+- Target normalization preserves existing targets and defaults sync off.
+- Namespace derivation is stable and sanitization rejects path traversal/control chars.
+- Relay snapshot read/write handles missing, corrupt, stale, and atomic-write cases.
+- Target-scoped filter excludes local repos and other SSH targets.
+- Projected snapshot import/export translates stable remote worktree paths to local `repoId::path` IDs.
+- Scoped merge preserves out-of-scope remote worktrees and deletes in-scope records when the remote snapshot says they are gone.
+- Stale revision retry preserves edits from the newer remote snapshot.
+- Old relay `-32601` maps to sync unavailable.
+- Packaged relay candidate lookup searches `process.resourcesPath` and dev paths.
+- Resize ownership gates remote resize on focused/local user intent.
+
+Integration:
+
+- Current same-client persistence still passes: close/quit/reconnect restores SSH PTYs without remote workspace sync enabled.
+- Sync-enabled target push writes only that target's session slice.
+- Cross-device simulation with two mux clients: client A pushes, client B receives `workspace.changed`, hydrates, and attaches the same relay PTY.
+- Two clients patch concurrently: one stale response, one retry, no out-of-scope data loss.
+- Explicit disconnect detaches but preserves leases; terminate sessions kills remote PTYs and marks leases terminated.
+- Relay restart or expired grace marks PTY references expired and does not auto-resume agents.
+- Provider-registration wait, if still needed, waits only for restored SSH reattach and does not mask normal spawn failures.
+
+E2E/manual:
+
+- Packaged macOS/Linux/Windows app can deploy the relay from packaged resources.
+- Old running relay continues classic SSH behavior and shows sync unavailable until reconnected with a new relay.
+- Two Orca clients on different machines connect to the same target, open a shared remote workspace, and verify tab/layout sync.
+- Resize a focused terminal on one client while another client is backgrounded; full-screen TUI dimensions follow only the focused client.
+- Mobile/desktop mixed client does not fight PTY dimensions when mobile fit lock is active.
+- Passphrase-protected targets defer reconnect without losing remote session IDs.
+
+## Risks And Decisions
+
+Decisions before implementation:
+
+- Default: should remote workspace sync be opt-in off for all targets? Recommendation: yes.
+- Retention: is `0` unlimited relay lifetime acceptable, or should sync use a large bounded default with visible cleanup?
+- Namespace identity: include `configHost`, host, port, and username. Label changes do not affect namespace.
+- Snapshot scope: v1 is terminal + layout + active worktree/tab only. Editor/browser comes later with explicit allowlists and translation rules.
+- Conflict UX: retry once automatically, then surface "Refresh from remote" / "Overwrite remote" choices.
+- Agent resume UX: explicit action location in expired terminal state or status toast.
+
+Main risks:
+
+- Cross-device resize fights can corrupt TUI layout; ship ownership gates with the first cross-client PTY attach.
+- Snapshot merge bugs can delete unrelated local or remote workspace state; keep target filtering/merge isolated and heavily tested.
+- Unlimited remote relay lifetime can leave processes running unexpectedly; make retention visible and terminate explicit.
+- Old relays may live across app updates; every new RPC must fail open.
+- Renderer hydration can trigger existing session writers and feedback loops; use hydration guards and per-target revision tracking.
+- Remote snapshots contain path/workspace metadata on the SSH host; treat as local-to-remote-user data and document the storage path.
diff --git a/src/main/github/client-issue-source.test.ts b/src/main/github/client-issue-source.test.ts
index 051f9ffebc6..ddeeca3a0a0 100644
--- a/src/main/github/client-issue-source.test.ts
+++ b/src/main/github/client-issue-source.test.ts
@@ -128,6 +128,42 @@ describe('GitHub issue source split', () => {
     )
   })
 
+  it('lists SSH repo work items with explicit owner/repo and no local cwd', async () => {
+    resolveIssueSourceMock.mockResolvedValueOnce({
+      source: { owner: 'stablyai', repo: 'orca' },
+      fellBack: false
+    })
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'fork', repo: 'orca' })
+    ghExecFileAsyncMock.mockResolvedValueOnce({ stdout: '[]' }).mockResolvedValueOnce({
+      stdout: '[]'
+    })
+
+    await listWorkItems('/home/jinwoo/orca', 10, undefined, undefined, 'auto', 'openclaw-2')
+
+    expect(resolveIssueSourceMock).toHaveBeenCalledWith('/home/jinwoo/orca', 'auto', 'openclaw-2')
+    expect(getOwnerRepoMock).toHaveBeenCalledWith('/home/jinwoo/orca', 'openclaw-2')
+    expect(ghExecFileAsyncMock).toHaveBeenNthCalledWith(
+      1,
+      [
+        'api',
+        '--cache',
+        '120s',
+        'repos/stablyai/orca/issues?per_page=10&state=open&sort=updated&direction=desc'
+      ],
+      {}
+    )
+    expect(ghExecFileAsyncMock).toHaveBeenNthCalledWith(
+      2,
+      [
+        'api',
+        '--cache',
+        '120s',
+        'repos/fork/orca/pulls?per_page=10&state=open&sort=updated&direction=desc'
+      ],
+      {}
+    )
+  })
+
   it('uses upstream for issue-only queries and origin for PR-only queries', async () => {
     getIssueOwnerRepoMock.mockResolvedValueOnce({ owner: 'stablyai', repo: 'orca' })
     getOwnerRepoMock.mockResolvedValueOnce({ owner: 'fork', repo: 'orca' })
@@ -332,7 +368,7 @@ describe('GitHub issue source split', () => {
 
       const result = await listWorkItems('/repo-root', 10, undefined, undefined, 'auto')
 
-      expect(resolveIssueSourceMock).toHaveBeenCalledWith('/repo-root', 'auto')
+      expect(resolveIssueSourceMock).toHaveBeenCalledWith('/repo-root', 'auto', undefined)
       expect(ghExecFileAsyncMock).toHaveBeenNthCalledWith(
         1,
         [
diff --git a/src/main/github/client-pr-checks.test.ts b/src/main/github/client-pr-checks.test.ts
index 49064da51e3..1a3dadf957c 100644
--- a/src/main/github/client-pr-checks.test.ts
+++ b/src/main/github/client-pr-checks.test.ts
@@ -21,6 +21,11 @@ const {
 vi.mock('./gh-utils', () => ({
   execFileAsync: execFileAsyncMock,
   ghExecFileAsync: ghExecFileAsyncMock,
+  githubRepoContext: (repoPath: string, connectionId?: string | null) => ({
+    repoPath,
+    connectionId: connectionId ?? null
+  }),
+  ghRepoExecOptions: (context: { repoPath: string }) => ({ cwd: context.repoPath }),
   getOwnerRepo: getOwnerRepoMock,
   getIssueOwnerRepo: getIssueOwnerRepoMock,
   acquire: acquireMock,
@@ -91,7 +96,7 @@ describe('getPRChecks', () => {
 
     expect(ghExecFileAsyncMock).toHaveBeenNthCalledWith(
       2,
-      ['pr', 'checks', '42', '--json', 'name,state,link'],
+      ['pr', 'checks', '42', '--json', 'name,state,link', '--repo', 'acme/widgets'],
       { cwd: '/repo-root' }
     )
     expect(checks).toEqual([
diff --git a/src/main/github/client-work-items.test.ts b/src/main/github/client-work-items.test.ts
index 3dadca51830..128037ba919 100644
--- a/src/main/github/client-work-items.test.ts
+++ b/src/main/github/client-work-items.test.ts
@@ -28,6 +28,11 @@ const {
 vi.mock('./gh-utils', () => ({
   execFileAsync: execFileAsyncMock,
   ghExecFileAsync: ghExecFileAsyncMock,
+  githubRepoContext: (repoPath: string, connectionId?: string | null) => ({
+    repoPath,
+    connectionId: connectionId ?? null
+  }),
+  ghRepoExecOptions: (context: { repoPath: string }) => ({ cwd: context.repoPath }),
   getOwnerRepo: getOwnerRepoMock,
   getIssueOwnerRepo: getIssueOwnerRepoMock,
   getOwnerRepoForRemote: getOwnerRepoForRemoteMock,
diff --git a/src/main/github/client.test.ts b/src/main/github/client.test.ts
index 4af9e9aaba6..5880c738ffc 100644
--- a/src/main/github/client.test.ts
+++ b/src/main/github/client.test.ts
@@ -1,3 +1,4 @@
+/* oxlint-disable max-lines -- Why: GitHub client fixtures cover local and SSH repo identity paths in one suite so mocked CLI behavior stays consistent. */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const {
@@ -6,7 +7,10 @@ const {
   getOwnerRepoMock,
   getIssueOwnerRepoMock,
   getOwnerRepoForRemoteMock,
+  getRemoteUrlForRepoMock,
   gitExecFileAsyncMock,
+  ghRepoExecOptionsMock,
+  githubRepoContextMock,
   acquireMock,
   releaseMock
 } = vi.hoisted(() => ({
@@ -15,7 +19,15 @@ const {
   getOwnerRepoMock: vi.fn(),
   getIssueOwnerRepoMock: vi.fn(),
   getOwnerRepoForRemoteMock: vi.fn(),
+  getRemoteUrlForRepoMock: vi.fn(),
   gitExecFileAsyncMock: vi.fn(),
+  ghRepoExecOptionsMock: vi.fn((context) =>
+    context.connectionId ? {} : { cwd: context.repoPath }
+  ),
+  githubRepoContextMock: vi.fn((repoPath, connectionId) => ({
+    repoPath,
+    connectionId: connectionId ?? null
+  })),
   acquireMock: vi.fn(),
   releaseMock: vi.fn()
 }))
@@ -26,7 +38,10 @@ vi.mock('./gh-utils', () => ({
   getOwnerRepo: getOwnerRepoMock,
   getIssueOwnerRepo: getIssueOwnerRepoMock,
   getOwnerRepoForRemote: getOwnerRepoForRemoteMock,
+  getRemoteUrlForRepo: getRemoteUrlForRepoMock,
   gitExecFileAsync: gitExecFileAsyncMock,
+  ghRepoExecOptions: ghRepoExecOptionsMock,
+  githubRepoContext: githubRepoContextMock,
   parseGitHubOwnerRepo: (remoteUrl: string) => {
     const match = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/)
     return match ? { owner: match[1], repo: match[2] } : null
@@ -49,7 +64,10 @@ describe('getPRForBranch', () => {
     getOwnerRepoMock.mockReset()
     getIssueOwnerRepoMock.mockReset()
     getOwnerRepoForRemoteMock.mockReset()
+    getRemoteUrlForRepoMock.mockReset()
     gitExecFileAsyncMock.mockReset()
+    ghRepoExecOptionsMock.mockClear()
+    githubRepoContextMock.mockClear()
     acquireMock.mockReset()
     releaseMock.mockReset()
     acquireMock.mockResolvedValue(undefined)
@@ -79,7 +97,7 @@ describe('getPRForBranch', () => {
 
     const pr = await getPRForBranch('/repo-root', 'refs/heads/feature/test')
 
-    expect(getOwnerRepoMock).toHaveBeenCalledWith('/repo-root')
+    expect(getOwnerRepoMock).toHaveBeenCalledWith('/repo-root', undefined)
     expect(ghExecFileAsyncMock).toHaveBeenCalledWith(
       [
         'pr',
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index a34bd6ff012..4f0bb72c0ee 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -29,6 +29,9 @@ import {
   resolveIssueSource,
   classifyGhError,
   classifyListIssuesError,
+  ghRepoExecOptions,
+  githubRepoContext,
+  getRemoteUrlForRepo,
   type OwnerRepo
 } from './gh-utils'
 export { _resetOwnerRepoCache } from './gh-utils'
@@ -98,9 +101,12 @@ function sanitizeRemoteName(owner: string, repo: string): string {
 
 export async function getPullRequestPushTarget(
   repoPath: string,
-  prNumber: number
+  prNumber: number,
+  connectionId?: string | null
 ): Promise<GitPushTarget | null> {
-  const ownerRepo = await getOwnerRepo(repoPath)
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   if (!ownerRepo) {
     return null
   }
@@ -109,9 +115,9 @@ export async function getPullRequestPushTarget(
   try {
     const [{ stdout: prStdout }, origin] = await Promise.all([
       ghExecFileAsync(['api', `repos/${ownerRepo.owner}/${ownerRepo.repo}/pulls/${prNumber}`], {
-        cwd: repoPath
+        ...ghOptions
       }),
-      getOwnerRepoForRemote(repoPath, 'origin')
+      getOwnerRepoForRemote(repoPath, 'origin', connectionId)
     ])
     const pr = JSON.parse(prStdout) as {
       head?: {
@@ -144,8 +150,10 @@ export async function getPullRequestPushTarget(
 
     let originUrl: string | null = null
     try {
-      const { stdout } = await gitExecFileAsync(['remote', 'get-url', 'origin'], { cwd: repoPath })
-      originUrl = stdout.trim() || null
+      const rawOriginUrl = connectionId
+        ? await getRemoteUrlForRepo(context, 'origin')
+        : (await gitExecFileAsync(['remote', 'get-url', 'origin'], { cwd: repoPath })).stdout
+      originUrl = rawOriginUrl?.trim() || null
     } catch {
       originUrl = null
     }
@@ -318,12 +326,14 @@ function mapPullRequestWorkItem(
 async function fetchIssueWorkItem(
   repoPath: string,
   ownerRepo: OwnerRepo | null,
-  number: number
+  number: number,
+  connectionId?: string | null
 ): Promise<MainWorkItem | null> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
   if (ownerRepo) {
     const { stdout } = await ghExecFileAsync(
       ['api', `repos/${ownerRepo.owner}/${ownerRepo.repo}/issues/${number}`],
-      { cwd: repoPath }
+      ghOptions
     )
     const item = JSON.parse(stdout) as Record<string, unknown>
     if ('pull_request' in item) {
@@ -334,7 +344,7 @@ async function fetchIssueWorkItem(
 
   const { stdout } = await ghExecFileAsync(
     ['issue', 'view', String(number), '--json', 'number,title,state,url,labels,updatedAt,author'],
-    { cwd: repoPath }
+    ghOptions
   )
   return mapIssueWorkItem(JSON.parse(stdout) as Record<string, unknown>)
 }
@@ -342,12 +352,14 @@ async function fetchIssueWorkItem(
 async function fetchPullRequestWorkItem(
   repoPath: string,
   ownerRepo: OwnerRepo | null,
-  number: number
+  number: number,
+  connectionId?: string | null
 ): Promise<MainWorkItem> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
   if (ownerRepo) {
     const { stdout } = await ghExecFileAsync(
       ['api', `repos/${ownerRepo.owner}/${ownerRepo.repo}/pulls/${number}`],
-      { cwd: repoPath }
+      ghOptions
     )
     return mapPullRequestWorkItem(JSON.parse(stdout) as Record<string, unknown>, ownerRepo.owner)
   }
@@ -360,7 +372,7 @@ async function fetchPullRequestWorkItem(
       '--json',
       'number,title,state,url,labels,updatedAt,author,isDraft,headRefName,baseRefName,headRepositoryOwner'
     ],
-    { cwd: repoPath }
+    ghOptions
   )
   return mapPullRequestWorkItem(JSON.parse(stdout) as Record<string, unknown>)
 }
@@ -447,8 +459,10 @@ async function listRecentWorkItems(
   repoPath: string,
   issueOwnerRepo: OwnerRepo | null,
   prOwnerRepo: OwnerRepo | null,
-  limit: number
+  limit: number,
+  connectionId?: string | null
 ): Promise<PartialWorkItemsResult> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
   if (issueOwnerRepo || prOwnerRepo) {
     // Why: allSettled so a 403 on upstream issues doesn't zero out the origin
     // PR half — the UI renders partial results plus a banner for the failing
@@ -462,7 +476,7 @@ async function listRecentWorkItems(
               '120s',
               `repos/${issueOwnerRepo.owner}/${issueOwnerRepo.repo}/issues?per_page=${limit}&state=open&sort=updated&direction=desc`
             ],
-            { cwd: repoPath }
+            ghOptions
           )
         : ghExecFileAsync(
             [
@@ -475,7 +489,7 @@ async function listRecentWorkItems(
               '--json',
               'number,title,state,url,labels,updatedAt,author'
             ],
-            { cwd: repoPath }
+            ghOptions
           ),
       prOwnerRepo
         ? ghExecFileAsync(
@@ -485,7 +499,7 @@ async function listRecentWorkItems(
               '120s',
               `repos/${prOwnerRepo.owner}/${prOwnerRepo.repo}/pulls?per_page=${limit}&state=open&sort=updated&direction=desc`
             ],
-            { cwd: repoPath }
+            ghOptions
           )
         : ghExecFileAsync(
             [
@@ -498,7 +512,7 @@ async function listRecentWorkItems(
               '--json',
               'number,title,state,url,labels,updatedAt,author,isDraft,headRefName,baseRefName,headRepositoryOwner'
             ],
-            { cwd: repoPath }
+            ghOptions
           )
     ])
 
@@ -569,7 +583,7 @@ async function listRecentWorkItems(
         '--json',
         'number,title,state,url,labels,updatedAt,author'
       ],
-      { cwd: repoPath }
+      ghOptions
     ),
     ghExecFileAsync(
       [
@@ -582,7 +596,7 @@ async function listRecentWorkItems(
         '--json',
         'number,title,state,url,labels,updatedAt,author,isDraft,headRefName,baseRefName,headRepositoryOwner'
       ],
-      { cwd: repoPath }
+      ghOptions
     )
   ])
 
@@ -604,8 +618,10 @@ async function listQueriedWorkItems(
   prOwnerRepo: OwnerRepo | null,
   query: ParsedTaskQuery,
   limit: number,
-  before?: string
+  before?: string,
+  connectionId?: string | null
 ): Promise<PartialWorkItemsResult> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
   const issueScope = query.scope !== 'pr'
   const prScope = query.scope !== 'issue'
 
@@ -624,7 +640,7 @@ async function listQueriedWorkItems(
       before
     })
     try {
-      const { stdout } = await ghExecFileAsync(args, { cwd: repoPath })
+      const { stdout } = await ghExecFileAsync(args, ghOptions)
       return {
         items: (JSON.parse(stdout) as Record<string, unknown>[]).map(mapIssueWorkItem)
       }
@@ -646,7 +662,7 @@ async function listQueriedWorkItems(
       before
     })
     try {
-      const { stdout } = await ghExecFileAsync(args, { cwd: repoPath })
+      const { stdout } = await ghExecFileAsync(args, ghOptions)
       return (JSON.parse(stdout) as Record<string, unknown>[]).map((item) =>
         mapPullRequestWorkItem(item, prOwnerRepo?.owner ?? null)
       )
@@ -668,7 +684,8 @@ export async function listWorkItems(
   limit = 24,
   query?: string,
   before?: string,
-  preference?: IssueSourcePreference
+  preference?: IssueSourcePreference,
+  connectionId?: string | null
 ): Promise<ListWorkItemsResult<MainWorkItem>> {
   // Why: resolve the raw upstream candidate alongside the preference-aware
   // issue source. The selector needs to know whether an upstream remote
@@ -676,9 +693,9 @@ export async function listWorkItems(
   // has picked 'origin' (which would otherwise make `sources.issues` equal
   // origin and hide the selector permanently).
   const [issueResolved, prOwnerRepo, upstreamCandidate] = await Promise.all([
-    resolveIssueSource(repoPath, preference),
-    getOwnerRepo(repoPath),
-    getOwnerRepoForRemote(repoPath, 'upstream')
+    resolveIssueSource(repoPath, preference, connectionId),
+    getOwnerRepo(repoPath, connectionId),
+    getOwnerRepoForRemote(repoPath, 'upstream', connectionId)
   ])
   const issueOwnerRepo = issueResolved.source
   const trimmedQuery = query?.trim() ?? ''
@@ -689,14 +706,15 @@ export async function listWorkItems(
     // catch-all here would make an auth/network failure indistinguishable from
     // an empty result and silently under-report per-repo failures.
     const partial = !trimmedQuery
-      ? await listRecentWorkItems(repoPath, issueOwnerRepo, prOwnerRepo, limit)
+      ? await listRecentWorkItems(repoPath, issueOwnerRepo, prOwnerRepo, limit, connectionId)
       : await listQueriedWorkItems(
           repoPath,
           issueOwnerRepo,
           prOwnerRepo,
           parseTaskQuery(trimmedQuery),
           limit,
-          before
+          before,
+          connectionId
         )
 
     const errors = partial.issuesError ? { issues: partial.issuesError } : undefined
@@ -759,9 +777,11 @@ function buildSearchQueryString(
 async function countWorkItemsForQuery(
   repoPath: string,
   ownerRepo: OwnerRepo,
-  query: ParsedTaskQuery
+  query: ParsedTaskQuery,
+  connectionId?: string | null
 ): Promise<number> {
   const searchQ = buildSearchQueryString(ownerRepo, query)
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
   const { stdout } = await ghExecFileAsync(
     [
       'api',
@@ -771,7 +791,7 @@ async function countWorkItemsForQuery(
       '--jq',
       '.total_count'
     ],
-    { cwd: repoPath }
+    ghOptions
   )
   return parseInt(stdout.trim(), 10) || 0
 }
@@ -806,11 +826,12 @@ function defaultOpenWorkItemQuery(): ParsedTaskQuery {
 export async function countWorkItems(
   repoPath: string,
   query?: string,
-  preference?: IssueSourcePreference
+  preference?: IssueSourcePreference,
+  connectionId?: string | null
 ): Promise<number> {
   const [issueResolved, prOwnerRepo] = await Promise.all([
-    resolveIssueSource(repoPath, preference),
-    getOwnerRepo(repoPath)
+    resolveIssueSource(repoPath, preference, connectionId),
+    getOwnerRepo(repoPath, connectionId)
   ])
   const issueOwnerRepo = issueResolved.source
   const ownerRepo = prOwnerRepo ?? issueOwnerRepo
@@ -825,7 +846,7 @@ export async function countWorkItems(
   await acquire()
   try {
     if (sameOwnerRepo(issueOwnerRepo, prOwnerRepo)) {
-      return await countWorkItemsForQuery(repoPath, ownerRepo, effectiveQuery)
+      return await countWorkItemsForQuery(repoPath, ownerRepo, effectiveQuery, connectionId)
     }
 
     const counts: Promise<number>[] = []
@@ -843,11 +864,23 @@ export async function countWorkItems(
       issueOwnerRepo
     ) {
       counts.push(
-        countWorkItemsForQuery(repoPath, issueOwnerRepo, { ...effectiveQuery, scope: 'issue' })
+        countWorkItemsForQuery(
+          repoPath,
+          issueOwnerRepo,
+          { ...effectiveQuery, scope: 'issue' },
+          connectionId
+        )
       )
     }
     if (effectiveQuery.scope !== 'issue' && prOwnerRepo) {
-      counts.push(countWorkItemsForQuery(repoPath, prOwnerRepo, { ...effectiveQuery, scope: 'pr' }))
+      counts.push(
+        countWorkItemsForQuery(
+          repoPath,
+          prOwnerRepo,
+          { ...effectiveQuery, scope: 'pr' },
+          connectionId
+        )
+      )
     }
     // Why: allSettled so a single failing search (e.g. transient network, rate
     // limit on one side) doesn't silently zero out the total; sum only the
@@ -871,27 +904,44 @@ export async function countWorkItems(
 }
 
 export async function getRepoSlug(
-  repoPath: string
+  repoPath: string,
+  connectionId?: string | null
 ): Promise<{ owner: string; repo: string } | null> {
-  return getOwnerRepo(repoPath)
+  return getOwnerRepo(repoPath, connectionId)
 }
 
 export async function getWorkItem(
   repoPath: string,
   number: number,
-  type?: 'issue' | 'pr'
+  type?: 'issue' | 'pr',
+  connectionId?: string | null
 ): Promise<MainWorkItem | null> {
   await acquire()
   try {
     if (type === 'issue') {
-      return await fetchIssueWorkItem(repoPath, await getIssueOwnerRepo(repoPath), number)
+      return await fetchIssueWorkItem(
+        repoPath,
+        await getIssueOwnerRepo(repoPath, connectionId),
+        number,
+        connectionId
+      )
     }
     if (type === 'pr') {
-      return await fetchPullRequestWorkItem(repoPath, await getOwnerRepo(repoPath), number)
+      return await fetchPullRequestWorkItem(
+        repoPath,
+        await getOwnerRepo(repoPath, connectionId),
+        number,
+        connectionId
+      )
     }
 
     try {
-      const issue = await fetchIssueWorkItem(repoPath, await getIssueOwnerRepo(repoPath), number)
+      const issue = await fetchIssueWorkItem(
+        repoPath,
+        await getIssueOwnerRepo(repoPath, connectionId),
+        number,
+        connectionId
+      )
       if (issue) {
         return issue
       }
@@ -907,7 +957,12 @@ export async function getWorkItem(
         throw err
       }
     }
-    return await fetchPullRequestWorkItem(repoPath, await getOwnerRepo(repoPath), number)
+    return await fetchPullRequestWorkItem(
+      repoPath,
+      await getOwnerRepo(repoPath, connectionId),
+      number,
+      connectionId
+    )
   } catch {
     return null
   } finally {
@@ -919,14 +974,15 @@ export async function getWorkItemByOwnerRepo(
   repoPath: string,
   ownerRepo: OwnerRepo,
   number: number,
-  type: 'issue' | 'pr'
+  type: 'issue' | 'pr',
+  connectionId?: string | null
 ): Promise<MainWorkItem | null> {
   await acquire()
   try {
     if (type === 'issue') {
-      return await fetchIssueWorkItem(repoPath, ownerRepo, number)
+      return await fetchIssueWorkItem(repoPath, ownerRepo, number, connectionId)
     }
-    return await fetchPullRequestWorkItem(repoPath, ownerRepo, number)
+    return await fetchPullRequestWorkItem(repoPath, ownerRepo, number, connectionId)
   } catch {
     return null
   } finally {
@@ -947,14 +1003,17 @@ export async function getWorkItemByOwnerRepo(
 export async function getPRForBranch(
   repoPath: string,
   branch: string,
-  linkedPRNumber?: number | null
+  linkedPRNumber?: number | null,
+  connectionId?: string | null
 ): Promise<PRInfo | null> {
   // Strip refs/heads/ prefix if present
   const branchName = branch.replace(/^refs\/heads\//, '')
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
 
   await acquire()
   try {
-    const ownerRepo = await getOwnerRepo(repoPath)
+    const ownerRepo = await getOwnerRepo(repoPath, connectionId)
     let data: {
       number: number
       title: string
@@ -990,7 +1049,7 @@ export async function getPRForBranch(
             '--json',
             'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
           ],
-          { cwd: repoPath }
+          ghOptions
         )
         const list = JSON.parse(stdout) as NonNullable<typeof data>[]
         data = list[0] ?? null
@@ -1003,7 +1062,7 @@ export async function getPRForBranch(
             '--json',
             'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
           ],
-          { cwd: repoPath }
+          ghOptions
         )
         data = JSON.parse(stdout)
       }
@@ -1028,7 +1087,7 @@ export async function getPRForBranch(
             'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
           ]
       try {
-        const { stdout } = await ghExecFileAsync(args, { cwd: repoPath })
+        const { stdout } = await ghExecFileAsync(args, ghOptions)
         data = JSON.parse(stdout)
       } catch {
         // Why: a stale linkedPRNumber (PR deleted, wrong repo, …) makes
@@ -1044,7 +1103,11 @@ export async function getPRForBranch(
     }
 
     const conflictSummary =
-      data.mergeable === 'CONFLICTING' && data.baseRefName && data.baseRefOid && data.headRefOid
+      !connectionId &&
+      data.mergeable === 'CONFLICTING' &&
+      data.baseRefName &&
+      data.baseRefOid &&
+      data.headRefOid
         ? await getPRConflictSummary(repoPath, data.baseRefName, data.baseRefOid, data.headRefOid)
         : undefined
 
@@ -1075,9 +1138,11 @@ export async function getPRChecks(
   repoPath: string,
   prNumber: number,
   headSha?: string,
-  options?: { noCache?: boolean }
+  options?: { noCache?: boolean },
+  connectionId?: string | null
 ): Promise<PRCheckDetail[]> {
-  const ownerRepo = headSha ? await getOwnerRepo(repoPath) : null
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   await acquire()
   try {
     if (ownerRepo && headSha) {
@@ -1091,7 +1156,7 @@ export async function getPRChecks(
             ...cacheArgs,
             `repos/${ownerRepo.owner}/${ownerRepo.repo}/commits/${encodeURIComponent(headSha)}/check-runs?per_page=100`
           ],
-          { cwd: repoPath }
+          ghOptions
         )
         const data = JSON.parse(stdout) as {
           check_runs: {
@@ -1116,10 +1181,11 @@ export async function getPRChecks(
       }
     }
     // Fallback: no branch provided or non-GitHub remote
-    const { stdout } = await ghExecFileAsync(
-      ['pr', 'checks', String(prNumber), '--json', 'name,state,link'],
-      { cwd: repoPath }
-    )
+    const fallbackArgs = ['pr', 'checks', String(prNumber), '--json', 'name,state,link']
+    if (ownerRepo) {
+      fallbackArgs.push('--repo', `${ownerRepo.owner}/${ownerRepo.repo}`)
+    }
+    const { stdout } = await ghExecFileAsync(fallbackArgs, ghOptions)
     const data = JSON.parse(stdout) as { name: string; state: string; link: string }[]
     return data.map((d) => ({
       name: d.name,
@@ -1195,9 +1261,11 @@ query($owner: String!, $repo: String!, $pr: Int!) {
 export async function getPRComments(
   repoPath: string,
   prNumber: number,
-  options?: { noCache?: boolean }
+  options?: { noCache?: boolean },
+  connectionId?: string | null
 ): Promise<PRComment[]> {
-  const ownerRepo = await getOwnerRepo(repoPath)
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   await acquire()
   try {
     if (ownerRepo) {
@@ -1211,9 +1279,10 @@ export async function getPRComments(
       // Each source is parsed independently; failed sources contribute zero
       // comments instead of aborting the entire fetch.
       const [issueResult, threadsResult, reviewsResult] = await Promise.allSettled([
-        ghExecFileAsync(['api', ...cacheArgs, `${base}/issues/${prNumber}/comments?per_page=100`], {
-          cwd: repoPath
-        }),
+        ghExecFileAsync(
+          ['api', ...cacheArgs, `${base}/issues/${prNumber}/comments?per_page=100`],
+          ghOptions
+        ),
         ghExecFileAsync(
           [
             'api',
@@ -1227,15 +1296,16 @@ export async function getPRComments(
             '-F',
             `pr=${prNumber}`
           ],
-          { cwd: repoPath }
+          ghOptions
         ),
         // Why: review summaries (approve, request changes, general comments) live
         // under pulls/{n}/reviews, not under issue comments or review threads.
         // Without this, a reviewer who submits "LGTM" without inline threads
         // would have their comment silently dropped from the panel.
-        ghExecFileAsync(['api', ...cacheArgs, `${base}/pulls/${prNumber}/reviews?per_page=100`], {
-          cwd: repoPath
-        })
+        ghExecFileAsync(
+          ['api', ...cacheArgs, `${base}/pulls/${prNumber}/reviews?per_page=100`],
+          ghOptions
+        )
       ])
 
       // Parse issue comments (REST)
@@ -1384,9 +1454,7 @@ export async function getPRComments(
     // Fallback: non-GitHub remote — use gh pr view (only returns issue-level comments)
     const { stdout } = await ghExecFileAsync(
       ['pr', 'view', String(prNumber), '--json', 'comments'],
-      {
-        cwd: repoPath
-      }
+      ghOptions
     )
     const data = JSON.parse(stdout) as {
       comments: {
@@ -1418,16 +1486,17 @@ export async function getPRComments(
 export async function resolveReviewThread(
   repoPath: string,
   threadId: string,
-  resolve: boolean
+  resolve: boolean,
+  connectionId?: string | null
 ): Promise<boolean> {
   const mutation = resolve ? 'resolveReviewThread' : 'unresolveReviewThread'
   const query = `mutation($threadId: ID!) { ${mutation}(input: { threadId: $threadId }) { thread { isResolved } } }`
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
   await acquire()
   try {
-    await execFileAsync(
-      'gh',
+    await ghExecFileAsync(
       ['api', 'graphql', '-f', `query=${query}`, '-f', `threadId=${threadId}`],
-      { cwd: repoPath, encoding: 'utf-8' }
+      ghOptions
     )
     return true
   } catch (err) {
@@ -1476,9 +1545,11 @@ export async function addPRReviewCommentReply(
   body: string,
   threadId?: string,
   path?: string,
-  line?: number
+  line?: number,
+  connectionId?: string | null
 ): Promise<GitHubCommentResult> {
-  const ownerRepo = await getOwnerRepo(repoPath)
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   if (!ownerRepo) {
     return { ok: false, error: 'Could not resolve GitHub owner/repo for this repository' }
   }
@@ -1493,7 +1564,7 @@ export async function addPRReviewCommentReply(
         '--raw-field',
         `body=${body}`
       ],
-      { cwd: repoPath }
+      ghOptions
     )
     return {
       ok: true,
@@ -1508,9 +1579,10 @@ export async function addPRReviewCommentReply(
 }
 
 export async function addPRReviewComment(
-  args: GitHubPRReviewCommentInput
+  args: GitHubPRReviewCommentInput & { connectionId?: string | null }
 ): Promise<GitHubCommentResult> {
-  const ownerRepo = await getOwnerRepo(args.repoPath)
+  const ghOptions = ghRepoExecOptions(githubRepoContext(args.repoPath, args.connectionId))
+  const ownerRepo = await getOwnerRepo(args.repoPath, args.connectionId)
   if (!ownerRepo) {
     return { ok: false, error: 'Could not resolve GitHub owner/repo for this repository' }
   }
@@ -1540,7 +1612,7 @@ export async function addPRReviewComment(
         'start_side=RIGHT'
       )
     }
-    const { stdout } = await ghExecFileAsync(fields, { cwd: args.repoPath })
+    const { stdout } = await ghExecFileAsync(fields, ghOptions)
     return {
       ok: true,
       comment: mapReviewCommentResponse(
@@ -1566,15 +1638,22 @@ export async function addPRReviewComment(
 export async function mergePR(
   repoPath: string,
   prNumber: number,
-  method: 'merge' | 'squash' | 'rebase' = 'squash'
+  method: 'merge' | 'squash' | 'rebase' = 'squash',
+  connectionId?: string | null
 ): Promise<{ ok: true } | { ok: false; error: string }> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   await acquire()
   try {
     // Don't use --delete-branch: it tries to delete the local branch which
     // fails when the user's worktree is checked out on it. Branch cleanup
     // is handled by worktree deletion (local) and GitHub's auto-delete setting (remote).
-    await ghExecFileAsync(['pr', 'merge', String(prNumber), `--${method}`], {
-      cwd: repoPath,
+    const args = ['pr', 'merge', String(prNumber), `--${method}`]
+    if (ownerRepo) {
+      args.push('--repo', `${ownerRepo.owner}/${ownerRepo.repo}`)
+    }
+    await ghExecFileAsync(args, {
+      ...ghOptions,
       env: { ...process.env, GH_PROMPT_DISABLED: '1' }
     })
     return { ok: true }
@@ -1593,12 +1672,19 @@ export async function mergePR(
 export async function updatePRTitle(
   repoPath: string,
   prNumber: number,
-  title: string
+  title: string,
+  connectionId?: string | null
 ): Promise<boolean> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   await acquire()
   try {
-    await ghExecFileAsync(['pr', 'edit', String(prNumber), '--title', title], {
-      cwd: repoPath
+    const args = ['pr', 'edit', String(prNumber), '--title', title]
+    if (ownerRepo) {
+      args.push('--repo', `${ownerRepo.owner}/${ownerRepo.repo}`)
+    }
+    await ghExecFileAsync(args, {
+      ...ghOptions
     })
     return true
   } catch (err) {
diff --git a/src/main/github/gh-utils.test.ts b/src/main/github/gh-utils.test.ts
index 8e1b8d839a1..91cc8588b89 100644
--- a/src/main/github/gh-utils.test.ts
+++ b/src/main/github/gh-utils.test.ts
@@ -1,7 +1,8 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-const { gitExecFileAsyncMock } = vi.hoisted(() => ({
-  gitExecFileAsyncMock: vi.fn()
+const { gitExecFileAsyncMock, getSshGitProviderMock } = vi.hoisted(() => ({
+  gitExecFileAsyncMock: vi.fn(),
+  getSshGitProviderMock: vi.fn()
 }))
 
 vi.mock('../git/runner', () => ({
@@ -9,6 +10,10 @@ vi.mock('../git/runner', () => ({
   ghExecFileAsync: vi.fn()
 }))
 
+vi.mock('../providers/ssh-git-dispatch', () => ({
+  getSshGitProvider: getSshGitProviderMock
+}))
+
 import {
   _resetOwnerRepoCache,
   classifyGhError,
@@ -22,6 +27,7 @@ import {
 describe('github owner/repo resolution', () => {
   beforeEach(() => {
     gitExecFileAsyncMock.mockReset()
+    getSshGitProviderMock.mockReset()
     _resetOwnerRepoCache()
   })
 
@@ -85,11 +91,42 @@ describe('github owner/repo resolution', () => {
     await expect(getOwnerRepo('/repo')).resolves.toEqual({ owner: 'fork', repo: 'orca' })
     await expect(getIssueOwnerRepo('/repo')).resolves.toEqual({ owner: 'stablyai', repo: 'orca' })
   })
+
+  it('resolves SSH repo remotes through the registered SSH git provider', async () => {
+    const sshProvider = {
+      exec: vi.fn().mockResolvedValue({ stdout: 'git@github.com:stablyai/orca.git\n', stderr: '' })
+    }
+    getSshGitProviderMock.mockReturnValue(sshProvider)
+
+    await expect(getOwnerRepo('/home/user/orca', 'openclaw-2')).resolves.toEqual({
+      owner: 'stablyai',
+      repo: 'orca'
+    })
+
+    expect(gitExecFileAsyncMock).not.toHaveBeenCalled()
+    expect(getSshGitProviderMock).toHaveBeenCalledWith('openclaw-2')
+    expect(sshProvider.exec).toHaveBeenCalledWith(
+      ['remote', 'get-url', 'origin'],
+      '/home/user/orca'
+    )
+  })
+
+  it('keeps local and SSH owner/repo cache entries separate for the same path', async () => {
+    const sshProvider = {
+      exec: vi.fn().mockResolvedValue({ stdout: 'git@github.com:remote/orca.git\n', stderr: '' })
+    }
+    gitExecFileAsyncMock.mockResolvedValueOnce({ stdout: 'git@github.com:local/orca.git\n' })
+    getSshGitProviderMock.mockReturnValue(sshProvider)
+
+    await expect(getOwnerRepo('/repo')).resolves.toEqual({ owner: 'local', repo: 'orca' })
+    await expect(getOwnerRepo('/repo', 'ssh-1')).resolves.toEqual({ owner: 'remote', repo: 'orca' })
+  })
 })
 
 describe('resolveIssueSource', () => {
   beforeEach(() => {
     gitExecFileAsyncMock.mockReset()
+    getSshGitProviderMock.mockReset()
     _resetOwnerRepoCache()
   })
 
diff --git a/src/main/github/gh-utils.ts b/src/main/github/gh-utils.ts
index 48f7afedbf4..1fc45329445 100644
--- a/src/main/github/gh-utils.ts
+++ b/src/main/github/gh-utils.ts
@@ -2,6 +2,7 @@ import { execFile } from 'child_process'
 import { promisify } from 'util'
 import { gitExecFileAsync, ghExecFileAsync } from '../git/runner'
 import type { ClassifiedError, GitHubOwnerRepo, IssueSourcePreference } from '../../shared/types'
+import { getSshGitProvider } from '../providers/ssh-git-dispatch'
 
 // Why: legacy generic execFile wrapper — only used by callers that don't need
 // WSL-aware routing (e.g. non-repo-scoped gh commands). Repo-scoped callers
@@ -112,6 +113,28 @@ export function classifyListIssuesError(stderr: string): ClassifiedError {
 // short local name `OwnerRepo`.
 export type OwnerRepo = GitHubOwnerRepo
 
+export type GitHubRepoContext = {
+  repoPath: string
+  connectionId?: string | null
+}
+
+export function githubRepoContext(
+  repoPath: string,
+  connectionId?: string | null
+): GitHubRepoContext {
+  return { repoPath, connectionId: connectionId ?? null }
+}
+
+export function ghRepoExecOptions(context: GitHubRepoContext): {
+  cwd?: string
+  encoding?: BufferEncoding
+} {
+  // Why: SSH repo paths are meaningful only on the remote host. All GitHub
+  // calls in this layer pass explicit --repo/API targets, so local gh should
+  // not receive a remote-only cwd.
+  return context.connectionId ? {} : { cwd: context.repoPath }
+}
+
 const ownerRepoCache = new Map<string, OwnerRepo | null>()
 
 /** @internal — exposed for tests only */
@@ -127,19 +150,37 @@ export function parseGitHubOwnerRepo(remoteUrl: string): OwnerRepo | null {
   return { owner: match[1], repo: match[2] }
 }
 
+export async function getRemoteUrlForRepo(
+  context: GitHubRepoContext,
+  remoteName: string
+): Promise<string | null> {
+  if (context.connectionId) {
+    const provider = getSshGitProvider(context.connectionId)
+    if (!provider) {
+      return null
+    }
+    const { stdout } = await provider.exec(['remote', 'get-url', remoteName], context.repoPath)
+    return stdout
+  }
+  const { stdout } = await gitExecFileAsync(['remote', 'get-url', remoteName], {
+    cwd: context.repoPath
+  })
+  return stdout
+}
+
 export async function getOwnerRepoForRemote(
   repoPath: string,
-  remoteName: string
+  remoteName: string,
+  connectionId?: string | null
 ): Promise<OwnerRepo | null> {
-  const cacheKey = `${repoPath}\0${remoteName}`
+  const context = githubRepoContext(repoPath, connectionId)
+  const cacheKey = `${context.connectionId ?? 'local'}\0${context.repoPath}\0${remoteName}`
   if (ownerRepoCache.has(cacheKey)) {
     return ownerRepoCache.get(cacheKey)!
   }
   try {
-    const { stdout } = await gitExecFileAsync(['remote', 'get-url', remoteName], {
-      cwd: repoPath
-    })
-    const result = parseGitHubOwnerRepo(stdout)
+    const remoteUrl = await getRemoteUrlForRepo(context, remoteName)
+    const result = remoteUrl ? parseGitHubOwnerRepo(remoteUrl) : null
     if (result) {
       ownerRepoCache.set(cacheKey, result)
       return result
@@ -151,16 +192,22 @@ export async function getOwnerRepoForRemote(
   return null
 }
 
-export async function getOwnerRepo(repoPath: string): Promise<OwnerRepo | null> {
-  return getOwnerRepoForRemote(repoPath, 'origin')
+export async function getOwnerRepo(
+  repoPath: string,
+  connectionId?: string | null
+): Promise<OwnerRepo | null> {
+  return getOwnerRepoForRemote(repoPath, 'origin', connectionId)
 }
 
-export async function getIssueOwnerRepo(repoPath: string): Promise<OwnerRepo | null> {
-  const upstream = await getOwnerRepoForRemote(repoPath, 'upstream')
+export async function getIssueOwnerRepo(
+  repoPath: string,
+  connectionId?: string | null
+): Promise<OwnerRepo | null> {
+  const upstream = await getOwnerRepoForRemote(repoPath, 'upstream', connectionId)
   if (upstream) {
     return upstream
   }
-  return getOwnerRepoForRemote(repoPath, 'origin')
+  return getOwnerRepoForRemote(repoPath, 'origin', connectionId)
 }
 
 export type ResolvedIssueSource = {
@@ -181,10 +228,11 @@ export type ResolvedIssueSource = {
  */
 export async function resolveIssueSource(
   repoPath: string,
-  preference: IssueSourcePreference | undefined
+  preference: IssueSourcePreference | undefined,
+  connectionId?: string | null
 ): Promise<ResolvedIssueSource> {
   if (preference === 'upstream') {
-    const upstream = await getOwnerRepoForRemote(repoPath, 'upstream')
+    const upstream = await getOwnerRepoForRemote(repoPath, 'upstream', connectionId)
     if (upstream) {
       return { source: upstream, fellBack: false }
     }
@@ -194,12 +242,15 @@ export async function resolveIssueSource(
     // UI toast "using origin" would be misleading. Do NOT auto-reset the
     // preference: the user may be mid-way through a workflow and expect
     // their choice to re-engage if `upstream` is re-added.
-    const origin = await getOwnerRepoForRemote(repoPath, 'origin')
+    const origin = await getOwnerRepoForRemote(repoPath, 'origin', connectionId)
     return { source: origin, fellBack: origin !== null }
   }
   if (preference === 'origin') {
-    return { source: await getOwnerRepoForRemote(repoPath, 'origin'), fellBack: false }
+    return {
+      source: await getOwnerRepoForRemote(repoPath, 'origin', connectionId),
+      fellBack: false
+    }
   }
   // 'auto' or undefined
-  return { source: await getIssueOwnerRepo(repoPath), fellBack: false }
+  return { source: await getIssueOwnerRepo(repoPath, connectionId), fellBack: false }
 }
diff --git a/src/main/github/issues.ts b/src/main/github/issues.ts
index d9e2b7f5e09..ca722e95245 100644
--- a/src/main/github/issues.ts
+++ b/src/main/github/issues.ts
@@ -13,7 +13,7 @@ import type {
 } from '../../shared/types'
 import { mapIssueInfo } from './mappers'
 // prettier-ignore
-import { ghExecFileAsync, acquire, release, getIssueOwnerRepo, resolveIssueSource, classifyGhError, classifyListIssuesError } from './gh-utils'
+import { ghExecFileAsync, acquire, release, getIssueOwnerRepo, resolveIssueSource, classifyGhError, classifyListIssuesError, ghRepoExecOptions, githubRepoContext } from './gh-utils'
 
 // Why: distinguishes a successful-empty listing from a failed fetch. The
 // previous `catch { return [] }` conflated a 403 on a private upstream with an
@@ -40,8 +40,14 @@ export type IssueListResult = {
  * #1186 / the parent design doc guard against. List and create paths honor
  * preference; number-resolution stays on the heuristic.
  */
-export async function getIssue(repoPath: string, issueNumber: number): Promise<IssueInfo | null> {
-  const ownerRepo = await getIssueOwnerRepo(repoPath)
+export async function getIssue(
+  repoPath: string,
+  issueNumber: number,
+  connectionId?: string | null
+): Promise<IssueInfo | null> {
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const ownerRepo = await getIssueOwnerRepo(repoPath, connectionId)
   await acquire()
   try {
     if (ownerRepo) {
@@ -52,7 +58,7 @@ export async function getIssue(repoPath: string, issueNumber: number): Promise<I
           '300s',
           `repos/${ownerRepo.owner}/${ownerRepo.repo}/issues/${issueNumber}`
         ],
-        { cwd: repoPath }
+        ghOptions
       )
       const data = JSON.parse(stdout)
       return mapIssueInfo(data)
@@ -60,7 +66,7 @@ export async function getIssue(repoPath: string, issueNumber: number): Promise<I
     // Fallback for non-GitHub remotes
     const { stdout } = await ghExecFileAsync(
       ['issue', 'view', String(issueNumber), '--json', 'number,title,state,url,labels'],
-      { cwd: repoPath }
+      ghOptions
     )
     const data = JSON.parse(stdout)
     return mapIssueInfo(data)
@@ -85,9 +91,12 @@ export async function getIssue(repoPath: string, issueNumber: number): Promise<I
 export async function listIssues(
   repoPath: string,
   limit = 20,
-  preference?: IssueSourcePreference
+  preference?: IssueSourcePreference,
+  connectionId?: string | null
 ): Promise<IssueListResult> {
-  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference)
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference, connectionId)
   await acquire()
   try {
     if (ownerRepo) {
@@ -98,7 +107,7 @@ export async function listIssues(
           '120s',
           `repos/${ownerRepo.owner}/${ownerRepo.repo}/issues?per_page=${limit}&state=open&sort=updated&direction=desc`
         ],
-        { cwd: repoPath }
+        ghOptions
       )
       const data = JSON.parse(stdout) as Record<string, unknown>[]
       // Why: the GitHub REST `/repos/{owner}/{repo}/issues` endpoint returns
@@ -114,7 +123,7 @@ export async function listIssues(
     // Fallback for non-GitHub remotes
     const { stdout } = await ghExecFileAsync(
       ['issue', 'list', '--json', 'number,title,state,url,labels', '--limit', String(limit)],
-      { cwd: repoPath }
+      ghOptions
     )
     const data = JSON.parse(stdout) as unknown[]
     return {
@@ -140,13 +149,16 @@ export async function createIssue(
   repoPath: string,
   title: string,
   body: string,
-  preference?: IssueSourcePreference
+  preference?: IssueSourcePreference,
+  connectionId?: string | null
 ): Promise<{ ok: true; number: number; url: string } | { ok: false; error: string }> {
   const trimmedTitle = title.trim()
   if (!trimmedTitle) {
     return { ok: false, error: 'Title is required' }
   }
-  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference)
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference, connectionId)
   if (!ownerRepo) {
     return { ok: false, error: 'Could not resolve GitHub owner/repo for this repository' }
   }
@@ -163,7 +175,7 @@ export async function createIssue(
         '--raw-field',
         `body=${body}`
       ],
-      { cwd: repoPath }
+      ghOptions
     )
     const data = JSON.parse(stdout) as { number?: number; html_url?: string; url?: string }
     if (typeof data.number !== 'number') {
@@ -198,9 +210,12 @@ export async function createIssue(
 export async function updateIssue(
   repoPath: string,
   issueNumber: number,
-  updates: GitHubIssueUpdate
+  updates: GitHubIssueUpdate,
+  connectionId?: string | null
 ): Promise<{ ok: true } | { ok: false; error: string }> {
-  const ownerRepo = await getIssueOwnerRepo(repoPath)
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const ownerRepo = await getIssueOwnerRepo(repoPath, connectionId)
   if (!ownerRepo) {
     return { ok: false, error: 'Could not resolve GitHub owner/repo for this repository' }
   }
@@ -214,7 +229,7 @@ export async function updateIssue(
     try {
       const cmd = updates.state === 'closed' ? 'close' : 'reopen'
       await ghExecFileAsync(['issue', cmd, String(issueNumber), '--repo', repo], {
-        cwd: repoPath
+        ...ghOptions
       })
     } catch (err) {
       const stderr = err instanceof Error ? err.message : String(err)
@@ -255,7 +270,7 @@ export async function updateIssue(
   if (hasEditArgs) {
     await acquire()
     try {
-      await ghExecFileAsync(editArgs, { cwd: repoPath })
+      await ghExecFileAsync(editArgs, ghOptions)
     } catch (err) {
       const stderr = err instanceof Error ? err.message : String(err)
       errors.push(classifyGhError(stderr).message)
@@ -285,9 +300,12 @@ export async function updateIssue(
 export async function addIssueComment(
   repoPath: string,
   issueNumber: number,
-  body: string
+  body: string,
+  connectionId?: string | null
 ): Promise<GitHubCommentResult> {
-  const ownerRepo = await getIssueOwnerRepo(repoPath)
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const ownerRepo = await getIssueOwnerRepo(repoPath, connectionId)
   if (!ownerRepo) {
     return { ok: false, error: 'Could not resolve GitHub owner/repo for this repository' }
   }
@@ -302,7 +320,7 @@ export async function addIssueComment(
         '--raw-field',
         `body=${body}`
       ],
-      { cwd: repoPath }
+      ghOptions
     )
     const data = JSON.parse(stdout) as {
       id?: number
@@ -331,9 +349,12 @@ export async function addIssueComment(
 
 export async function listLabels(
   repoPath: string,
-  preference?: IssueSourcePreference
+  preference?: IssueSourcePreference,
+  connectionId?: string | null
 ): Promise<string[]> {
-  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference)
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference, connectionId)
   if (!ownerRepo) {
     return []
   }
@@ -347,7 +368,7 @@ export async function listLabels(
         '--jq',
         '.[].name'
       ],
-      { cwd: repoPath }
+      ghOptions
     )
     return stdout
       .trim()
@@ -362,9 +383,12 @@ export async function listLabels(
 
 export async function listAssignableUsers(
   repoPath: string,
-  preference?: IssueSourcePreference
+  preference?: IssueSourcePreference,
+  connectionId?: string | null
 ): Promise<GitHubAssignableUser[]> {
-  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference)
+  const context = githubRepoContext(repoPath, connectionId)
+  const ghOptions = ghRepoExecOptions(context)
+  const { source: ownerRepo } = await resolveIssueSource(repoPath, preference, connectionId)
   if (!ownerRepo) {
     return []
   }
@@ -383,7 +407,7 @@ export async function listAssignableUsers(
         '--jq',
         '.[] | {login, avatar_url}'
       ],
-      { cwd: repoPath }
+      ghOptions
     )
     type RESTAssignee = { login?: string; avatar_url?: string | null }
     const users: GitHubAssignableUser[] = []
diff --git a/src/main/github/work-item-details.test.ts b/src/main/github/work-item-details.test.ts
index b6f92b7417b..c8a8c3fa409 100644
--- a/src/main/github/work-item-details.test.ts
+++ b/src/main/github/work-item-details.test.ts
@@ -7,6 +7,8 @@ const {
   getWorkItemMock,
   getPRChecksMock,
   getPRCommentsMock,
+  ghRepoExecOptionsMock,
+  githubRepoContextMock,
   acquireMock,
   releaseMock
 } = vi.hoisted(() => ({
@@ -16,6 +18,13 @@ const {
   getWorkItemMock: vi.fn(),
   getPRChecksMock: vi.fn(),
   getPRCommentsMock: vi.fn(),
+  ghRepoExecOptionsMock: vi.fn((context) =>
+    context.connectionId ? {} : { cwd: context.repoPath }
+  ),
+  githubRepoContextMock: vi.fn((repoPath, connectionId) => ({
+    repoPath,
+    connectionId: connectionId ?? null
+  })),
   acquireMock: vi.fn(),
   releaseMock: vi.fn()
 }))
@@ -24,6 +33,8 @@ vi.mock('./gh-utils', () => ({
   ghExecFileAsync: ghExecFileAsyncMock,
   getOwnerRepo: getOwnerRepoMock,
   getIssueOwnerRepo: getIssueOwnerRepoMock,
+  ghRepoExecOptions: ghRepoExecOptionsMock,
+  githubRepoContext: githubRepoContextMock,
   acquire: acquireMock,
   release: releaseMock
 }))
@@ -44,6 +55,8 @@ describe('getWorkItemDetails', () => {
     getWorkItemMock.mockReset()
     getPRChecksMock.mockReset()
     getPRCommentsMock.mockReset()
+    ghRepoExecOptionsMock.mockClear()
+    githubRepoContextMock.mockClear()
     acquireMock.mockReset()
     releaseMock.mockReset()
     acquireMock.mockResolvedValue(undefined)
@@ -91,7 +104,7 @@ describe('getWorkItemDetails', () => {
 
     const details = await getWorkItemDetails('/repo-root', 923, 'issue')
 
-    expect(getWorkItemMock).toHaveBeenCalledWith('/repo-root', 923, 'issue')
+    expect(getWorkItemMock).toHaveBeenCalledWith('/repo-root', 923, 'issue', undefined)
     // Why: a single gh subprocess call replaces the previous REST + REST + GraphQL fan-out.
     expect(ghExecFileAsyncMock).toHaveBeenCalledTimes(1)
     expect(ghExecFileAsyncMock.mock.calls[0][0][0]).toBe('api')
@@ -144,4 +157,40 @@ describe('getWorkItemDetails', () => {
     )
     expect(details?.body).toBe('Issue body')
   })
+
+  it('uses SSH connection context for issue details without local cwd', async () => {
+    getWorkItemMock.mockResolvedValueOnce({
+      id: 'issue:923',
+      type: 'issue',
+      number: 923,
+      title: 'Use upstream issues',
+      state: 'open',
+      url: 'https://github.com/stablyai/orca/issues/923',
+      labels: [],
+      updatedAt: '2026-04-01T00:00:00Z',
+      author: 'octocat'
+    })
+    getIssueOwnerRepoMock.mockResolvedValue({ owner: 'stablyai', repo: 'orca' })
+    ghExecFileAsyncMock.mockResolvedValueOnce({
+      stdout: JSON.stringify({
+        data: {
+          repository: {
+            issue: {
+              body: 'Remote issue body',
+              assignees: { nodes: [] },
+              participants: { nodes: [] },
+              comments: { nodes: [] }
+            }
+          }
+        }
+      })
+    })
+
+    const details = await getWorkItemDetails('/home/jinwoo/orca', 923, 'issue', 'openclaw-2')
+
+    expect(getWorkItemMock).toHaveBeenCalledWith('/home/jinwoo/orca', 923, 'issue', 'openclaw-2')
+    expect(getIssueOwnerRepoMock).toHaveBeenCalledWith('/home/jinwoo/orca', 'openclaw-2')
+    expect(ghExecFileAsyncMock.mock.calls[0][1]).toEqual({})
+    expect(details?.body).toBe('Remote issue body')
+  })
 })
diff --git a/src/main/github/work-item-details.ts b/src/main/github/work-item-details.ts
index a0ea1983d79..7d7ab66d795 100644
--- a/src/main/github/work-item-details.ts
+++ b/src/main/github/work-item-details.ts
@@ -9,7 +9,15 @@ import type {
   GitHubWorkItemDetails,
   PRComment
 } from '../../shared/types'
-import { ghExecFileAsync, acquire, release, getOwnerRepo, getIssueOwnerRepo } from './gh-utils'
+import {
+  ghExecFileAsync,
+  acquire,
+  release,
+  getOwnerRepo,
+  getIssueOwnerRepo,
+  ghRepoExecOptions,
+  githubRepoContext
+} from './gh-utils'
 import { getWorkItem, getPRChecks, getPRComments } from './client'
 
 // Why: a PR "changed file" listing returned by the REST endpoint is paginated
@@ -91,14 +99,16 @@ type GraphQLIssueDetailsResponse = {
 
 async function getIssueDetailsViaGraphQL(
   repoPath: string,
-  issueNumber: number
+  issueNumber: number,
+  connectionId?: string | null
 ): Promise<{
   body: string
   comments: PRComment[]
   assignees: string[]
   participants: GitHubAssignableUser[]
 } | null> {
-  const ownerRepo = await getIssueOwnerRepo(repoPath)
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getIssueOwnerRepo(repoPath, connectionId)
   if (!ownerRepo) {
     return null
   }
@@ -116,7 +126,7 @@ async function getIssueDetailsViaGraphQL(
         '-F',
         `number=${issueNumber}`
       ],
-      { cwd: repoPath }
+      ghOptions
     )
     const parsed = JSON.parse(stdout) as GraphQLIssueDetailsResponse
     if (parsed.errors && parsed.errors.length > 0) {
@@ -235,14 +245,16 @@ function isBinaryHint(file: RESTPRFile): boolean {
 
 async function getPRHeadBaseSha(
   repoPath: string,
-  prNumber: number
+  prNumber: number,
+  connectionId?: string | null
 ): Promise<{ headSha: string; baseSha: string } | null> {
-  const ownerRepo = await getOwnerRepo(repoPath)
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   try {
     if (ownerRepo) {
       const { stdout } = await ghExecFileAsync(
         ['api', '--cache', '60s', `repos/${ownerRepo.owner}/${ownerRepo.repo}/pulls/${prNumber}`],
-        { cwd: repoPath }
+        ghOptions
       )
       const data = JSON.parse(stdout) as {
         head?: { sha?: string }
@@ -255,7 +267,7 @@ async function getPRHeadBaseSha(
     }
     const { stdout } = await ghExecFileAsync(
       ['pr', 'view', String(prNumber), '--json', 'headRefOid,baseRefOid'],
-      { cwd: repoPath }
+      ghOptions
     )
     const data = JSON.parse(stdout) as { headRefOid?: string; baseRefOid?: string }
     if (data.headRefOid && data.baseRefOid) {
@@ -267,8 +279,13 @@ async function getPRHeadBaseSha(
   }
 }
 
-async function getPRFiles(repoPath: string, prNumber: number): Promise<GitHubPRFile[]> {
-  const ownerRepo = await getOwnerRepo(repoPath)
+async function getPRFiles(
+  repoPath: string,
+  prNumber: number,
+  connectionId?: string | null
+): Promise<GitHubPRFile[]> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   if (!ownerRepo) {
     return []
   }
@@ -280,7 +297,7 @@ async function getPRFiles(repoPath: string, prNumber: number): Promise<GitHubPRF
         '60s',
         `repos/${ownerRepo.owner}/${ownerRepo.repo}/pulls/${prNumber}/files?per_page=100`
       ],
-      { cwd: repoPath }
+      ghOptions
     )
     const data = JSON.parse(stdout) as RESTPRFile[]
     return data.slice(0, MAX_PR_FILES).map((file) => ({
@@ -298,9 +315,11 @@ async function getPRFiles(repoPath: string, prNumber: number): Promise<GitHubPRF
 
 async function getIssueBodyAndComments(
   repoPath: string,
-  issueNumber: number
+  issueNumber: number,
+  connectionId?: string | null
 ): Promise<{ body: string; comments: PRComment[]; assignees: string[] }> {
-  const ownerRepo = await getIssueOwnerRepo(repoPath)
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getIssueOwnerRepo(repoPath, connectionId)
   try {
     if (ownerRepo) {
       const [issueResult, commentsResult] = await Promise.all([
@@ -311,7 +330,7 @@ async function getIssueBodyAndComments(
             '60s',
             `repos/${ownerRepo.owner}/${ownerRepo.repo}/issues/${issueNumber}`
           ],
-          { cwd: repoPath }
+          ghOptions
         ),
         ghExecFileAsync(
           [
@@ -320,7 +339,7 @@ async function getIssueBodyAndComments(
             '60s',
             `repos/${ownerRepo.owner}/${ownerRepo.repo}/issues/${issueNumber}/comments?per_page=100`
           ],
-          { cwd: repoPath }
+          ghOptions
         )
       ])
       const issue = JSON.parse(issueResult.stdout) as {
@@ -351,7 +370,7 @@ async function getIssueBodyAndComments(
     // Fallback: non-GitHub remote
     const { stdout } = await ghExecFileAsync(
       ['issue', 'view', String(issueNumber), '--json', 'body,comments,assignees'],
-      { cwd: repoPath }
+      ghOptions
     )
     const data = JSON.parse(stdout) as {
       body?: string
@@ -380,20 +399,26 @@ async function getIssueBodyAndComments(
   }
 }
 
-async function getPRBody(repoPath: string, prNumber: number): Promise<string> {
-  const ownerRepo = await getOwnerRepo(repoPath)
+async function getPRBody(
+  repoPath: string,
+  prNumber: number,
+  connectionId?: string | null
+): Promise<string> {
+  const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const ownerRepo = await getOwnerRepo(repoPath, connectionId)
   try {
     if (ownerRepo) {
       const { stdout } = await ghExecFileAsync(
         ['api', '--cache', '60s', `repos/${ownerRepo.owner}/${ownerRepo.repo}/pulls/${prNumber}`],
-        { cwd: repoPath }
+        ghOptions
       )
       const data = JSON.parse(stdout) as { body?: string | null }
       return data.body ?? ''
     }
-    const { stdout } = await ghExecFileAsync(['pr', 'view', String(prNumber), '--json', 'body'], {
-      cwd: repoPath
-    })
+    const { stdout } = await ghExecFileAsync(
+      ['pr', 'view', String(prNumber), '--json', 'body'],
+      ghOptions
+    )
     const data = JSON.parse(stdout) as { body?: string }
     return data.body ?? ''
   } catch {
@@ -403,13 +428,16 @@ async function getPRBody(repoPath: string, prNumber: number): Promise<string> {
 
 async function getWorkItemParticipants(
   repoPath: string,
-  item: Pick<GitHubWorkItem, 'number' | 'type'>
+  item: Pick<GitHubWorkItem, 'number' | 'type'>,
+  connectionId?: string | null
 ): Promise<GitHubAssignableUser[]> {
   // Why: issues in a fork live on the upstream remote, so participants must be
   // resolved via getIssueOwnerRepo to stay consistent with getIssueBodyAndComments.
   // PRs remain tied to origin via getOwnerRepo.
   const ownerRepo =
-    item.type === 'issue' ? await getIssueOwnerRepo(repoPath) : await getOwnerRepo(repoPath)
+    item.type === 'issue'
+      ? await getIssueOwnerRepo(repoPath, connectionId)
+      : await getOwnerRepo(repoPath, connectionId)
   if (!ownerRepo) {
     return []
   }
@@ -429,7 +457,7 @@ async function getWorkItemParticipants(
         '-F',
         `isPr=${item.type === 'pr'}`
       ],
-      { cwd: repoPath }
+      ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
     )
     const data = JSON.parse(stdout) as {
       data?: {
@@ -461,7 +489,8 @@ async function getWorkItemParticipants(
 
 async function getGitHubUsersByLogin(
   repoPath: string,
-  logins: string[]
+  logins: string[],
+  connectionId?: string | null
 ): Promise<GitHubAssignableUser[]> {
   const uniqueLogins = Array.from(
     new Set(logins.filter((login) => login && login !== 'ghost').map((login) => login.trim()))
@@ -478,9 +507,7 @@ async function getGitHubUsersByLogin(
   try {
     const { stdout } = await ghExecFileAsync(
       ['api', 'graphql', '-f', `query=query { ${fields} }`],
-      {
-        cwd: repoPath
-      }
+      ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
     )
     const data = JSON.parse(stdout) as {
       data?: Record<
@@ -506,26 +533,33 @@ async function getMentionParticipants(
   repoPath: string,
   item: Pick<GitHubWorkItem, 'author' | 'number' | 'type'>,
   comments: PRComment[],
-  participants: GitHubAssignableUser[]
+  participants: GitHubAssignableUser[],
+  connectionId?: string | null
 ): Promise<GitHubAssignableUser[]> {
   const visibleLogins = [item.author ?? '', ...comments.map((comment) => comment.author)]
   // Why: one aliased GraphQL query returns login/name/avatarUrl for every
   // mentioned author in a single round-trip. The previous REST fan-out
   // (/users/<login>) returned the same fields but cost one rate-limit point
   // per user.
-  const graphQlUsers = await getGitHubUsersByLogin(repoPath, visibleLogins)
+  const graphQlUsers = await getGitHubUsersByLogin(repoPath, visibleLogins, connectionId)
   return mergeGitHubUsers([...participants, ...graphQlUsers])
 }
 
 export async function getWorkItemDetails(
   repoPath: string,
   number: number,
-  type?: 'issue' | 'pr'
+  type?: 'issue' | 'pr',
+  connectionId?: string | null
 ): Promise<GitHubWorkItemDetails | null> {
   // Why: getWorkItem already handles acquire/release. We call it first (outside
   // our semaphore) so the known-cheap lookup doesn't compete with the richer
   // detail fetches that follow.
-  const item: Omit<GitHubWorkItem, 'repoId'> | null = await getWorkItem(repoPath, number, type)
+  const item: Omit<GitHubWorkItem, 'repoId'> | null = await getWorkItem(
+    repoPath,
+    number,
+    type,
+    connectionId
+  )
   if (!item) {
     return null
   }
@@ -540,7 +574,7 @@ export async function getWorkItemDetails(
       // is preserved. The GraphQL `participants` connection includes every
       // commenter, so we skip the extra `getMentionParticipants` aliased
       // user-hydration trip when the collapsed path succeeds.
-      const collapsed = await getIssueDetailsViaGraphQL(repoPath, item.number)
+      const collapsed = await getIssueDetailsViaGraphQL(repoPath, item.number, connectionId)
       if (collapsed) {
         return {
           item,
@@ -553,35 +587,36 @@ export async function getWorkItemDetails(
       // Why: fall back to body/comments and GraphQL participants in parallel;
       // the mention-participant merge is a cheap local operation afterward.
       const [{ body, comments, assignees }, participants] = await Promise.all([
-        getIssueBodyAndComments(repoPath, item.number),
-        getWorkItemParticipants(repoPath, item)
+        getIssueBodyAndComments(repoPath, item.number, connectionId),
+        getWorkItemParticipants(repoPath, item, connectionId)
       ])
       const mentionParticipants = await getMentionParticipants(
         repoPath,
         item,
         comments,
-        participants
+        participants,
+        connectionId
       )
       return { item, body, comments, assignees, participants: mentionParticipants }
     }
 
     // PR: fetch body + comments + checks + files + head/base SHAs in parallel.
     const [body, comments, shas, files, participants] = await Promise.all([
-      getPRBody(repoPath, item.number),
-      getPRComments(repoPath, item.number),
-      getPRHeadBaseSha(repoPath, item.number),
-      getPRFiles(repoPath, item.number),
-      getWorkItemParticipants(repoPath, item)
+      getPRBody(repoPath, item.number, connectionId),
+      getPRComments(repoPath, item.number, undefined, connectionId),
+      getPRHeadBaseSha(repoPath, item.number, connectionId),
+      getPRFiles(repoPath, item.number, connectionId),
+      getWorkItemParticipants(repoPath, item, connectionId)
     ])
 
     // Why: run the mention-author GraphQL lookup in parallel with the final
     // checks fetch instead of serially — both depend only on data from the
     // Promise.all above, so there's no ordering requirement between them.
     const [mentionParticipants, checks] = await Promise.all([
-      getMentionParticipants(repoPath, item, comments, participants),
+      getMentionParticipants(repoPath, item, comments, participants, connectionId),
       shas?.headSha
-        ? getPRChecks(repoPath, item.number, shas.headSha)
-        : getPRChecks(repoPath, item.number)
+        ? getPRChecks(repoPath, item.number, shas.headSha, undefined, connectionId)
+        : getPRChecks(repoPath, item.number, undefined, undefined, connectionId)
     ])
 
     return {
@@ -605,6 +640,7 @@ export async function getWorkItemDetails(
 // during rapid file-expand clicks in the drawer.
 async function fetchContentAtRef(args: {
   repoPath: string
+  connectionId?: string | null
   owner: string
   repo: string
   path: string
@@ -620,7 +656,7 @@ async function fetchContentAtRef(args: {
         'Accept: application/vnd.github.raw',
         `repos/${args.owner}/${args.repo}/contents/${encodeURI(args.path)}?ref=${encodeURIComponent(args.ref)}`
       ],
-      { cwd: args.repoPath }
+      ghRepoExecOptions(githubRepoContext(args.repoPath, args.connectionId))
     )
     // Raw content response: Electron's execFile returns string in utf-8. If the
     // file is binary, the string will contain replacement characters — we treat
@@ -637,6 +673,7 @@ async function fetchContentAtRef(args: {
 
 export async function getPRFileContents(args: {
   repoPath: string
+  connectionId?: string | null
   prNumber: number
   path: string
   oldPath?: string
@@ -644,7 +681,7 @@ export async function getPRFileContents(args: {
   headSha: string
   baseSha: string
 }): Promise<GitHubPRFileContents> {
-  const ownerRepo = await getOwnerRepo(args.repoPath)
+  const ownerRepo = await getOwnerRepo(args.repoPath, args.connectionId)
   if (!ownerRepo) {
     return {
       original: '',
@@ -668,6 +705,7 @@ export async function getPRFileContents(args: {
       needsOriginal
         ? fetchContentAtRef({
             repoPath: args.repoPath,
+            connectionId: args.connectionId,
             owner: ownerRepo.owner,
             repo: ownerRepo.repo,
             path: originalPath,
@@ -677,6 +715,7 @@ export async function getPRFileContents(args: {
       needsModified
         ? fetchContentAtRef({
             repoPath: args.repoPath,
+            connectionId: args.connectionId,
             owner: ownerRepo.owner,
             repo: ownerRepo.repo,
             path: args.path,
diff --git a/src/main/ipc/filesystem-watcher.test.ts b/src/main/ipc/filesystem-watcher.test.ts
index b6727bcf31f..4fcd2462fd4 100644
--- a/src/main/ipc/filesystem-watcher.test.ts
+++ b/src/main/ipc/filesystem-watcher.test.ts
@@ -98,7 +98,10 @@ describe('registerFilesystemWatcherHandlers', () => {
     expect(warnSpy).toHaveBeenCalledWith(
       '[filesystem-watcher] SSH filesystem provider unavailable; retrying watch for /home/me/repo on connection conn-1'
     )
-    handlers['fs:unwatchWorktree'](null, { worktreePath: '/home/me/repo', connectionId: 'conn-1' })
+    handlers['fs:unwatchWorktree'](
+      { sender: { id: 1 } },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
     warnSpy.mockRestore()
     vi.useRealTimers()
   })
@@ -128,7 +131,10 @@ describe('registerFilesystemWatcherHandlers', () => {
       events: [{ path: '/home/me/repo/file.txt', type: 'update' }]
     })
     warnSpy.mockRestore()
-    handlers['fs:unwatchWorktree'](null, { worktreePath: '/home/me/repo', connectionId: 'conn-1' })
+    handlers['fs:unwatchWorktree'](
+      { sender: { id: 1 } },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
     vi.useRealTimers()
   })
 
@@ -151,4 +157,41 @@ describe('registerFilesystemWatcherHandlers', () => {
     warnSpy.mockRestore()
     vi.useRealTimers()
   })
+
+  it('shares SSH worktree watchers across renderer senders until the last unwatch', async () => {
+    const sendOne = vi.fn()
+    const sendTwo = vi.fn()
+    const senderOne = { isDestroyed: () => false, send: sendOne, once: vi.fn(), id: 1 }
+    const senderTwo = { isDestroyed: () => false, send: sendTwo, once: vi.fn(), id: 2 }
+    const unwatchMock = vi.fn()
+    const watchMock = vi.fn().mockResolvedValue(unwatchMock)
+    getSshFilesystemProviderMock.mockReturnValue({ watch: watchMock })
+
+    await handlers['fs:watchWorktree'](
+      { sender: senderOne },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
+    await handlers['fs:watchWorktree'](
+      { sender: senderTwo },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
+
+    expect(watchMock).toHaveBeenCalledTimes(1)
+    const onEvents = watchMock.mock.calls[0][1]
+    onEvents([{ path: '/home/me/repo/file.txt', type: 'update' }])
+    expect(sendOne).toHaveBeenCalledTimes(1)
+    expect(sendTwo).toHaveBeenCalledTimes(1)
+
+    handlers['fs:unwatchWorktree'](
+      { sender: { id: 1 } },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
+    expect(unwatchMock).not.toHaveBeenCalled()
+
+    handlers['fs:unwatchWorktree'](
+      { sender: { id: 2 } },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
+    expect(unwatchMock).toHaveBeenCalledTimes(1)
+  })
 })
diff --git a/src/main/ipc/filesystem-watcher.ts b/src/main/ipc/filesystem-watcher.ts
index d6064b4696d..1555b859592 100644
--- a/src/main/ipc/filesystem-watcher.ts
+++ b/src/main/ipc/filesystem-watcher.ts
@@ -432,8 +432,13 @@ function unsubscribe(worktreePath: string, senderId: number): void {
 }
 
 // ── Remote watcher state ─────────────────────────────────────────────
-// Key: `${connectionId}:${worktreePath}`, Value: unwatch function
-const remoteWatchers = new Map<string, () => void>()
+type RemoteWatcherState = {
+  unwatch: () => void
+  listeners: Map<number, WebContents>
+}
+
+// Key: `${connectionId}:${worktreePath}`, Value: shared remote watch state.
+const remoteWatchers = new Map<string, RemoteWatcherState>()
 const loggedUnavailableRemoteWatchers = new Set<string>()
 const pendingRemoteWatcherRetries = new Map<string, ReturnType<typeof setTimeout>>()
 // Why: track in-flight `provider.watch()` calls so an unwatch/shutdown that
@@ -444,16 +449,28 @@ const inFlightRemoteInstalls = new Map<string, { cancelled: boolean }>()
 const REMOTE_WATCH_RETRY_MS = 1_000
 const REMOTE_WATCH_RETRY_TIMEOUT_MS = 60_000
 
-function replaceRemoteWatcher(key: string, unwatch: () => void): void {
-  const previous = remoteWatchers.get(key)
-  if (previous) {
-    // Why: SSH reconnect swaps in a fresh filesystem provider, but the
-    // renderer keeps watching the same worktree path. Replacing the existing
-    // unwatch callback here ensures a post-reconnect watch request rebinds to
-    // the new provider instead of early-returning forever on stale state.
-    previous()
+function addRemoteWatchListener(key: string, sender: WebContents): void {
+  const state = remoteWatchers.get(key)
+  if (!state) {
+    return
   }
-  remoteWatchers.set(key, unwatch)
+  state.listeners.set(sender.id, sender)
+  sender.once('destroyed', () => {
+    releaseRemoteWatchListener(key, sender.id)
+  })
+}
+
+function releaseRemoteWatchListener(key: string, senderId: number): void {
+  const state = remoteWatchers.get(key)
+  if (!state) {
+    return
+  }
+  state.listeners.delete(senderId)
+  if (state.listeners.size > 0) {
+    return
+  }
+  state.unwatch()
+  remoteWatchers.delete(key)
 }
 
 type RemoteWatcherInstallResult = 'installed' | 'unavailable' | 'cancelled'
@@ -469,13 +486,25 @@ async function installRemoteWatcher(
   }
 
   const key = `${connectionId}:${worktreePath}`
+  const existing = remoteWatchers.get(key)
+  if (existing) {
+    addRemoteWatchListener(key, sender)
+    return 'installed'
+  }
   const cancelToken = { cancelled: false }
   inFlightRemoteInstalls.set(key, cancelToken)
   let unwatch: () => void
   try {
     unwatch = await provider.watch(worktreePath, (events) => {
-      if (!sender.isDestroyed()) {
-        sender.send('fs:changed', {
+      const state = remoteWatchers.get(key)
+      if (!state) {
+        return
+      }
+      for (const listener of state.listeners.values()) {
+        if (listener.isDestroyed()) {
+          continue
+        }
+        listener.send('fs:changed', {
           worktreePath,
           events
         } satisfies FsChangedPayload)
@@ -494,21 +523,9 @@ async function installRemoteWatcher(
     }
     return 'cancelled'
   }
-  replaceRemoteWatcher(key, unwatch)
+  remoteWatchers.set(key, { unwatch, listeners: new Map() })
+  addRemoteWatchListener(key, sender)
   loggedUnavailableRemoteWatchers.delete(key)
-
-  sender.once('destroyed', () => {
-    const unwatchFn = remoteWatchers.get(key)
-    if (unwatchFn) {
-      unwatchFn()
-      remoteWatchers.delete(key)
-    }
-    const retryTimer = pendingRemoteWatcherRetries.get(key)
-    if (retryTimer) {
-      clearTimeout(retryTimer)
-      pendingRemoteWatcherRetries.delete(key)
-    }
-  })
   return 'installed'
 }
 
@@ -609,11 +626,7 @@ export function registerFilesystemWatcherHandlers(): void {
           inFlight.cancelled = true
         }
         loggedUnavailableRemoteWatchers.delete(key)
-        const unwatchFn = remoteWatchers.get(key)
-        if (unwatchFn) {
-          unwatchFn()
-          remoteWatchers.delete(key)
-        }
+        releaseRemoteWatchListener(key, _event?.sender?.id ?? 0)
         return
       }
       const senderId = _event.sender.id
@@ -657,9 +670,9 @@ export async function closeAllWatchers(): Promise<void> {
   // subscriptions. Without cleaning them up here, their unwatch callbacks
   // would never fire, leaving the relay polling for FS changes after the
   // app has shut down.
-  for (const [key, unwatchFn] of remoteWatchers) {
+  for (const [key, state] of remoteWatchers) {
     try {
-      unwatchFn()
+      state.unwatch()
     } catch (err) {
       console.error(`[filesystem-watcher] remote unwatch error for ${key}:`, err)
     }
diff --git a/src/main/ipc/github-work-item-args.test.ts b/src/main/ipc/github-work-item-args.test.ts
index 8bb38c8170a..b979bd40a88 100644
--- a/src/main/ipc/github-work-item-args.test.ts
+++ b/src/main/ipc/github-work-item-args.test.ts
@@ -2,16 +2,18 @@ import { describe, expect, it, vi } from 'vitest'
 import { dispatchWorkItem } from './github-work-item-args'
 
 describe('dispatchWorkItem', () => {
+  const repo = { path: '/r', connectionId: null }
+
   it('rejects non-integer numbers', () => {
     const fn = vi.fn()
-    expect(dispatchWorkItem({ repoPath: '/r', number: 1.5 }, '/r', fn)).toBeNull()
+    expect(dispatchWorkItem({ repoPath: '/r', number: 1.5 }, repo, fn)).toBeNull()
     expect(fn).not.toHaveBeenCalled()
   })
 
   it('rejects numbers < 1', () => {
     const fn = vi.fn()
-    expect(dispatchWorkItem({ repoPath: '/r', number: 0 }, '/r', fn)).toBeNull()
-    expect(dispatchWorkItem({ repoPath: '/r', number: -5 }, '/r', fn)).toBeNull()
+    expect(dispatchWorkItem({ repoPath: '/r', number: 0 }, repo, fn)).toBeNull()
+    expect(dispatchWorkItem({ repoPath: '/r', number: -5 }, repo, fn)).toBeNull()
     expect(fn).not.toHaveBeenCalled()
   })
 
@@ -19,7 +21,7 @@ describe('dispatchWorkItem', () => {
     const fn = vi.fn()
     // Renderer can send anything; simulate a string that slips past TS.
     const bogus = { repoPath: '/r', number: 'abc' as unknown as number }
-    expect(dispatchWorkItem(bogus, '/r', fn)).toBeNull()
+    expect(dispatchWorkItem(bogus, repo, fn)).toBeNull()
     expect(fn).not.toHaveBeenCalled()
   })
 
@@ -30,19 +32,29 @@ describe('dispatchWorkItem', () => {
       number: 42,
       type: 'bogus' as unknown as 'issue' | 'pr'
     }
-    await dispatchWorkItem(bogus, '/r', fn)
-    expect(fn).toHaveBeenCalledWith('/r', 42, undefined)
+    await dispatchWorkItem(bogus, repo, fn)
+    expect(fn).toHaveBeenCalledWith('/r', 42, undefined, null)
   })
 
   it('passes valid issue type through', async () => {
     const fn = vi.fn().mockResolvedValue(null)
-    await dispatchWorkItem({ repoPath: '/r', number: 42, type: 'issue' }, '/r', fn)
-    expect(fn).toHaveBeenCalledWith('/r', 42, 'issue')
+    await dispatchWorkItem({ repoPath: '/r', number: 42, type: 'issue' }, repo, fn)
+    expect(fn).toHaveBeenCalledWith('/r', 42, 'issue', null)
   })
 
   it('passes valid pr type through', async () => {
     const fn = vi.fn().mockResolvedValue(null)
-    await dispatchWorkItem({ repoPath: '/r', number: 42, type: 'pr' }, '/r', fn)
-    expect(fn).toHaveBeenCalledWith('/r', 42, 'pr')
+    await dispatchWorkItem({ repoPath: '/r', number: 42, type: 'pr' }, repo, fn)
+    expect(fn).toHaveBeenCalledWith('/r', 42, 'pr', null)
+  })
+
+  it('passes SSH connection context through', async () => {
+    const fn = vi.fn().mockResolvedValue(null)
+    await dispatchWorkItem(
+      { repoPath: '/remote/repo', number: 42, type: 'issue' },
+      { path: '/remote/repo', connectionId: 'ssh-1' },
+      fn
+    )
+    expect(fn).toHaveBeenCalledWith('/remote/repo', 42, 'issue', 'ssh-1')
   })
 })
diff --git a/src/main/ipc/github-work-item-args.ts b/src/main/ipc/github-work-item-args.ts
index 43b16deb600..c0c641f262e 100644
--- a/src/main/ipc/github-work-item-args.ts
+++ b/src/main/ipc/github-work-item-args.ts
@@ -4,19 +4,29 @@ export type WorkItemArgs = {
   type?: 'issue' | 'pr'
 }
 
+type RegisteredRepoContext = {
+  path: string
+  connectionId?: string | null
+}
+
 // Why: renderer input crosses the IPC boundary and is untrusted. Reject
 // non-integer or < 1 numbers, and coerce unrecognised `type` values to
 // undefined so getWorkItem falls through to its issue-then-PR probe rather
 // than silently dispatching to the wrong branch.
 export function dispatchWorkItem<T>(
   args: WorkItemArgs,
-  repoPath: string,
-  fn: (path: string, n: number, t?: 'issue' | 'pr') => Promise<T | null>
+  repo: RegisteredRepoContext,
+  fn: (
+    path: string,
+    n: number,
+    t?: 'issue' | 'pr',
+    connectionId?: string | null
+  ) => Promise<T | null>
 ): Promise<T | null> | null {
   const { number, type } = args
   if (typeof number !== 'number' || !Number.isInteger(number) || number < 1) {
     return null
   }
   const safeType = type === 'issue' || type === 'pr' ? type : undefined
-  return fn(repoPath, number, safeType)
+  return fn(repo.path, number, safeType, repo.connectionId ?? null)
 }
diff --git a/src/main/ipc/github.test.ts b/src/main/ipc/github.test.ts
index 8a74e3b741c..6d340e8f7e3 100644
--- a/src/main/ipc/github.test.ts
+++ b/src/main/ipc/github.test.ts
@@ -42,6 +42,7 @@ describe('registerGitHubHandlers', () => {
     displayName: string
     badgeColor: string
     addedAt: number
+    connectionId?: string | null
     issueSourcePreference?: 'origin' | 'upstream'
   }
   let repos: FixtureRepo[] = []
@@ -93,7 +94,7 @@ describe('registerGitHubHandlers', () => {
       branch: 'feature/test'
     })
 
-    expect(getPRForBranchMock).toHaveBeenCalledWith('/workspace/repo', 'feature/test', null)
+    expect(getPRForBranchMock).toHaveBeenCalledWith('/workspace/repo', 'feature/test', null, null)
   })
 
   it('rejects unknown repository paths', async () => {
@@ -119,7 +120,7 @@ describe('registerGitHubHandlers', () => {
       limit: 5
     })
 
-    expect(listIssuesMock).toHaveBeenCalledWith('/workspace/repo', 5, undefined)
+    expect(listIssuesMock).toHaveBeenCalledWith('/workspace/repo', 5, undefined, null)
     expect(result).toEqual([])
   })
 
@@ -147,7 +148,7 @@ describe('registerGitHubHandlers', () => {
       limit: 5
     })
 
-    expect(listIssuesMock).toHaveBeenCalledWith('/workspace/repo', 5, undefined)
+    expect(listIssuesMock).toHaveBeenCalledWith('/workspace/repo', 5, undefined, null)
     expect(result).toEqual([])
   })
 
@@ -166,7 +167,7 @@ describe('registerGitHubHandlers', () => {
       limit: 5
     })
 
-    expect(listIssuesMock).toHaveBeenCalledWith('/workspace/repo', 5, 'upstream')
+    expect(listIssuesMock).toHaveBeenCalledWith('/workspace/repo', 5, 'upstream', null)
   })
 
   it('threads issueSourcePreference through gh:listWorkItems', async () => {
@@ -189,7 +190,30 @@ describe('registerGitHubHandlers', () => {
       10,
       'is:open',
       'cursor-1',
-      'origin'
+      'origin',
+      null
+    )
+  })
+
+  it('threads SSH connectionId through GitHub work-item handlers', async () => {
+    repos[0].connectionId = 'openclaw-2'
+    listWorkItemsMock.mockResolvedValue({ items: [] })
+
+    registerGitHubHandlers(store as never, stats as never)
+
+    await handlers['gh:listWorkItems'](null, {
+      repoPath: '/workspace/repo',
+      limit: 10,
+      query: ''
+    })
+
+    expect(listWorkItemsMock).toHaveBeenCalledWith(
+      '/workspace/repo',
+      10,
+      '',
+      undefined,
+      undefined,
+      'openclaw-2'
     )
   })
 
diff --git a/src/main/ipc/github.ts b/src/main/ipc/github.ts
index 4b3e9c20280..ddaa07da8ea 100644
--- a/src/main/ipc/github.ts
+++ b/src/main/ipc/github.ts
@@ -82,6 +82,7 @@ import type {
 function broadcastWorkItemMutated(
   payload: {
     repoPath: string
+    repoId?: string
     type: 'issue' | 'pr'
     number: number
   },
@@ -100,21 +101,39 @@ function broadcastWorkItemMutated(
 
 // Why: returns the full Repo object instead of just the path string so that
 // callers have access to repo.id for stat tracking and other context.
-function assertRegisteredRepo(repoPath: string, store: Store): Repo {
+type RepoScopedArgs = { repoPath: string; repoId?: string }
+
+function assertRegisteredRepo(args: string | RepoScopedArgs, store: Store): Repo {
+  const repoPath = typeof args === 'string' ? args : args.repoPath
+  const repoId = typeof args === 'string' ? undefined : args.repoId
   const resolvedRepoPath = resolve(repoPath)
-  const repo = store.getRepos().find((r) => resolve(r.path) === resolvedRepoPath)
+  const repo = store
+    .getRepos()
+    .find((r) => (repoId ? r.id === repoId : resolve(r.path) === resolvedRepoPath))
   if (!repo) {
     throw new Error('Access denied: unknown repository path')
   }
+  if (repoId && resolve(repo.path) !== resolvedRepoPath) {
+    throw new Error('Access denied: repository path does not match repo id')
+  }
   return repo
 }
 
+function repoConnectionId(repo: Repo): string | null {
+  return repo.connectionId ?? null
+}
+
 export function registerGitHubHandlers(store: Store, stats: StatsCollector): void {
   ipcMain.handle(
     'gh:prForBranch',
     async (_event, args: { repoPath: string; branch: string; linkedPRNumber?: number | null }) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
-      const pr = await getPRForBranch(repo.path, args.branch, args.linkedPRNumber ?? null)
+      const repo = assertRegisteredRepo(args, store)
+      const pr = await getPRForBranch(
+        repo.path,
+        args.branch,
+        args.linkedPRNumber ?? null,
+        repoConnectionId(repo)
+      )
       // Emit pr_created when a PR is first detected for a branch.
       // Why here: the renderer polls gh:prForBranch to check PR status per worktree.
       // This captures PRs opened from any workflow (Orca UI, gh CLI, github.com).
@@ -131,47 +150,62 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
   )
 
   ipcMain.handle('gh:issue', (_event, args: { repoPath: string; number: number }) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
-    return getIssue(repo.path, args.number)
+    const repo = assertRegisteredRepo(args, store)
+    return getIssue(repo.path, args.number, repoConnectionId(repo))
   })
 
   ipcMain.handle('gh:listIssues', (_event, args: { repoPath: string; limit?: number }) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
+    const repo = assertRegisteredRepo(args, store)
     // Why: listIssues now returns { items, error? }. The IPC handler unwraps to
     // the items array for the existing contract; feature 1's UI consumes the
     // richer envelope through `gh:listWorkItems` instead.
-    return listIssues(repo.path, args.limit, repo.issueSourcePreference).then((r) => r.items)
+    return listIssues(
+      repo.path,
+      args.limit,
+      repo.issueSourcePreference,
+      repoConnectionId(repo)
+    ).then((r) => r.items)
   })
 
   ipcMain.handle(
     'gh:createIssue',
     (_event, args: { repoPath: string; title: string; body: string }) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
-      return createIssue(repo.path, args.title, args.body, repo.issueSourcePreference)
+      const repo = assertRegisteredRepo(args, store)
+      return createIssue(
+        repo.path,
+        args.title,
+        args.body,
+        repo.issueSourcePreference,
+        repoConnectionId(repo)
+      )
     }
   )
 
   ipcMain.handle(
     'gh:listWorkItems',
-    (_event, args: { repoPath: string; limit?: number; query?: string; before?: string }) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
+    (
+      _event,
+      args: { repoPath: string; repoId?: string; limit?: number; query?: string; before?: string }
+    ) => {
+      const repo = assertRegisteredRepo(args, store)
       return listWorkItems(
         repo.path,
         args.limit,
         args.query,
         args.before,
-        repo.issueSourcePreference
+        repo.issueSourcePreference,
+        repoConnectionId(repo)
       )
     }
   )
 
   ipcMain.handle('gh:countWorkItems', (_event, args: { repoPath: string; query?: string }) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
-    return countWorkItems(repo.path, args.query, repo.issueSourcePreference)
+    const repo = assertRegisteredRepo(args, store)
+    return countWorkItems(repo.path, args.query, repo.issueSourcePreference, repoConnectionId(repo))
   })
 
   ipcMain.handle('gh:workItem', (_event, args: WorkItemArgs) =>
-    dispatchWorkItem(args, assertRegisteredRepo(args.repoPath, store).path, getWorkItem)
+    dispatchWorkItem(args, assertRegisteredRepo(args, store), getWorkItem)
   )
   ipcMain.handle(
     'gh:workItemByOwnerRepo',
@@ -184,16 +218,19 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         number: number
         type: 'issue' | 'pr'
       }
-    ) =>
-      getWorkItemByOwnerRepo(
-        assertRegisteredRepo(args.repoPath, store).path,
+    ) => {
+      const repo = assertRegisteredRepo(args, store)
+      return getWorkItemByOwnerRepo(
+        repo.path,
         { owner: args.owner, repo: args.repo },
         args.number,
-        args.type
+        args.type,
+        repoConnectionId(repo)
       )
+    }
   )
   ipcMain.handle('gh:workItemDetails', (_event, args: WorkItemArgs) =>
-    dispatchWorkItem(args, assertRegisteredRepo(args.repoPath, store).path, getWorkItemDetails)
+    dispatchWorkItem(args, assertRegisteredRepo(args, store), getWorkItemDetails)
   )
 
   ipcMain.handle(
@@ -210,9 +247,10 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         baseSha: string
       }
     ) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
+      const repo = assertRegisteredRepo(args, store)
       return getPRFileContents({
         repoPath: repo.path,
+        connectionId: repoConnectionId(repo),
         prNumber: args.prNumber,
         path: args.path,
         oldPath: args.oldPath,
@@ -224,8 +262,8 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
   )
 
   ipcMain.handle('gh:repoSlug', (_event, args: { repoPath: string }) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
-    return getRepoSlug(repo.path)
+    const repo = assertRegisteredRepo(args, store)
+    return getRepoSlug(repo.path, repoConnectionId(repo))
   })
 
   ipcMain.handle(
@@ -239,31 +277,42 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         noCache?: boolean
       }
     ) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
-      return getPRChecks(repo.path, args.prNumber, args.headSha, {
-        noCache: args.noCache
-      })
+      const repo = assertRegisteredRepo(args, store)
+      return getPRChecks(
+        repo.path,
+        args.prNumber,
+        args.headSha,
+        {
+          noCache: args.noCache
+        },
+        repoConnectionId(repo)
+      )
     }
   )
 
   ipcMain.handle(
     'gh:prComments',
     (_event, args: { repoPath: string; prNumber: number; noCache?: boolean }) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
-      return getPRComments(repo.path, args.prNumber, { noCache: args.noCache })
+      const repo = assertRegisteredRepo(args, store)
+      return getPRComments(
+        repo.path,
+        args.prNumber,
+        { noCache: args.noCache },
+        repoConnectionId(repo)
+      )
     }
   )
 
   ipcMain.handle(
     'gh:resolveReviewThread',
     async (_event, args: { repoPath: string; threadId: string; resolve: boolean }) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
+      const repo = assertRegisteredRepo(args, store)
       // Why: thread resolve doesn't carry the PR number, so we cannot target
       // a specific cache entry. The renderer cache stores per-(repo, type, number)
       // entries — emitting a path-wide invalidation here would require a new
       // event shape; instead, the drawer's existing thread-resolve UI updates
       // its local state immediately and the next reopen pays one fresh fetch.
-      return resolveReviewThread(repo.path, args.threadId, args.resolve)
+      return resolveReviewThread(repo.path, args.threadId, args.resolve, repoConnectionId(repo))
     }
   )
 
@@ -281,7 +330,7 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         line?: number
       }
     ) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
+      const repo = assertRegisteredRepo(args, store)
       if (
         typeof args.prNumber !== 'number' ||
         !Number.isInteger(args.prNumber) ||
@@ -306,11 +355,12 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         args.body.trim(),
         args.threadId,
         args.path,
-        args.line
+        args.line,
+        repoConnectionId(repo)
       )
       if (result.ok) {
         broadcastWorkItemMutated(
-          { repoPath: repo.path, type: 'pr', number: args.prNumber },
+          { repoPath: repo.path, repoId: repo.id, type: 'pr', number: args.prNumber },
           event.sender.id
         )
       }
@@ -332,7 +382,7 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         body: string
       }
     ) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
+      const repo = assertRegisteredRepo(args, store)
       if (
         typeof args.prNumber !== 'number' ||
         !Number.isInteger(args.prNumber) ||
@@ -368,11 +418,12 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         path: args.path,
         line: args.line,
         startLine: args.startLine,
-        body: args.body.trim()
+        body: args.body.trim(),
+        connectionId: repoConnectionId(repo)
       })
       if (result.ok) {
         broadcastWorkItemMutated(
-          { repoPath: repo.path, type: 'pr', number: args.prNumber },
+          { repoPath: repo.path, repoId: repo.id, type: 'pr', number: args.prNumber },
           event.sender.id
         )
       }
@@ -383,11 +434,11 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
   ipcMain.handle(
     'gh:updatePRTitle',
     async (event, args: { repoPath: string; prNumber: number; title: string }) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
-      const ok = await updatePRTitle(repo.path, args.prNumber, args.title)
+      const repo = assertRegisteredRepo(args, store)
+      const ok = await updatePRTitle(repo.path, args.prNumber, args.title, repoConnectionId(repo))
       if (ok) {
         broadcastWorkItemMutated(
-          { repoPath: repo.path, type: 'pr', number: args.prNumber },
+          { repoPath: repo.path, repoId: repo.id, type: 'pr', number: args.prNumber },
           event.sender.id
         )
       }
@@ -401,11 +452,11 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
       event,
       args: { repoPath: string; prNumber: number; method?: 'merge' | 'squash' | 'rebase' }
     ) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
-      const result = await mergePR(repo.path, args.prNumber, args.method)
+      const repo = assertRegisteredRepo(args, store)
+      const result = await mergePR(repo.path, args.prNumber, args.method, repoConnectionId(repo))
       if (result.ok) {
         broadcastWorkItemMutated(
-          { repoPath: repo.path, type: 'pr', number: args.prNumber },
+          { repoPath: repo.path, repoId: repo.id, type: 'pr', number: args.prNumber },
           event.sender.id
         )
       }
@@ -415,18 +466,21 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
 
   ipcMain.handle(
     'gh:updateIssue',
-    async (event, args: { repoPath: string; number: number; updates: GitHubIssueUpdate }) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
+    async (
+      event,
+      args: { repoPath: string; repoId?: string; number: number; updates: GitHubIssueUpdate }
+    ) => {
+      const repo = assertRegisteredRepo(args, store)
       if (typeof args.number !== 'number' || !Number.isInteger(args.number) || args.number < 1) {
         return { ok: false, error: 'Invalid issue number' }
       }
       if (!args.updates || typeof args.updates !== 'object') {
         return { ok: false, error: 'Updates object is required' }
       }
-      const result = await updateIssue(repo.path, args.number, args.updates)
+      const result = await updateIssue(repo.path, args.number, args.updates, repoConnectionId(repo))
       if (result.ok) {
         broadcastWorkItemMutated(
-          { repoPath: repo.path, type: 'issue', number: args.number },
+          { repoPath: repo.path, repoId: repo.id, type: 'issue', number: args.number },
           event.sender.id
         )
       }
@@ -440,14 +494,19 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
       event,
       args: { repoPath: string; number: number; body: string; type?: 'issue' | 'pr' }
     ) => {
-      const repo = assertRegisteredRepo(args.repoPath, store)
+      const repo = assertRegisteredRepo(args, store)
       if (typeof args.number !== 'number' || !Number.isInteger(args.number) || args.number < 1) {
         return { ok: false, error: 'Invalid issue number' }
       }
       if (!args.body?.trim()) {
         return { ok: false, error: 'Comment body required' }
       }
-      const result = await addIssueComment(repo.path, args.number, args.body.trim())
+      const result = await addIssueComment(
+        repo.path,
+        args.number,
+        args.body.trim(),
+        repoConnectionId(repo)
+      )
       if (result.ok) {
         // Why: PR conversation comments hit `/issues/N/comments` too, but the
         // drawer's cache key uses type='pr'. The caller passes through which
@@ -455,7 +514,7 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
         // — broadcasting both would evict an unrelated PR/issue that happens
         // to share the number.
         broadcastWorkItemMutated(
-          { repoPath: repo.path, type: args.type ?? 'issue', number: args.number },
+          { repoPath: repo.path, repoId: repo.id, type: args.type ?? 'issue', number: args.number },
           event.sender.id
         )
       }
@@ -464,13 +523,13 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
   )
 
   ipcMain.handle('gh:listLabels', (_event, args: { repoPath: string }) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
-    return listLabels(repo.path, repo.issueSourcePreference)
+    const repo = assertRegisteredRepo(args, store)
+    return listLabels(repo.path, repo.issueSourcePreference, repoConnectionId(repo))
   })
 
   ipcMain.handle('gh:listAssignableUsers', (_event, args: { repoPath: string }) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
-    return listAssignableUsers(repo.path, repo.issueSourcePreference)
+    const repo = assertRegisteredRepo(args, store)
+    return listAssignableUsers(repo.path, repo.issueSourcePreference, repoConnectionId(repo))
   })
 
   // Star operations target the Orca repo itself — no repoPath validation needed
diff --git a/src/main/ipc/hosted-review.ts b/src/main/ipc/hosted-review.ts
index acd89711356..4f458914e0e 100644
--- a/src/main/ipc/hosted-review.ts
+++ b/src/main/ipc/hosted-review.ts
@@ -6,7 +6,14 @@ import type { Store } from '../persistence'
 import type { StatsCollector } from '../stats/collector'
 import { getHostedReviewForBranch } from '../source-control/hosted-review'
 
-function assertRegisteredRepo(repoPath: string, store: Store): Repo {
+function assertRegisteredRepo(repoPath: string, store: Store, repoId?: string): Repo {
+  if (repoId) {
+    const repo = store.getRepo(repoId)
+    if (!repo || repo.path !== repoPath) {
+      throw new Error('Access denied: unknown repository')
+    }
+    return repo
+  }
   const resolvedRepoPath = resolve(repoPath)
   const repo = store.getRepos().find((r) => resolve(r.path) === resolvedRepoPath)
   if (!repo) {
@@ -17,9 +24,10 @@ function assertRegisteredRepo(repoPath: string, store: Store): Repo {
 
 export function registerHostedReviewHandlers(store: Store, stats: StatsCollector): void {
   ipcMain.handle('hostedReview:forBranch', async (_event, args: HostedReviewForBranchArgs) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
+    const repo = assertRegisteredRepo(args.repoPath, store, args.repoId)
     const review = await getHostedReviewForBranch({
       repoPath: repo.path,
+      connectionId: repo.connectionId,
       branch: args.branch,
       linkedGitHubPR: args.linkedGitHubPR ?? null,
       linkedGitLabMR: args.linkedGitLabMR ?? null,
diff --git a/src/main/ipc/remote-workspace-events.ts b/src/main/ipc/remote-workspace-events.ts
new file mode 100644
index 00000000000..cd7ae2b7c45
--- /dev/null
+++ b/src/main/ipc/remote-workspace-events.ts
@@ -0,0 +1,24 @@
+type RemoteWorkspaceNotificationHandler = (
+  targetId: string,
+  method: string,
+  params: Record<string, unknown>
+) => void
+
+const handlers = new Set<RemoteWorkspaceNotificationHandler>()
+
+export function registerRemoteWorkspaceNotificationHandler(
+  handler: RemoteWorkspaceNotificationHandler
+): () => void {
+  handlers.add(handler)
+  return () => handlers.delete(handler)
+}
+
+export function notifyRemoteWorkspaceHandlers(
+  targetId: string,
+  method: string,
+  params: Record<string, unknown>
+): void {
+  for (const handler of handlers) {
+    handler(targetId, method, params)
+  }
+}
diff --git a/src/main/ipc/remote-workspace-namespace.ts b/src/main/ipc/remote-workspace-namespace.ts
new file mode 100644
index 00000000000..2af4f20fdc8
--- /dev/null
+++ b/src/main/ipc/remote-workspace-namespace.ts
@@ -0,0 +1,12 @@
+import { createHash } from 'crypto'
+import type { SshTarget } from '../../shared/ssh-types'
+
+export function getRemoteWorkspaceNamespace(target: SshTarget): string {
+  const stableKey = [
+    target.configHost || target.host,
+    target.host,
+    String(target.port),
+    target.username
+  ].join('\n')
+  return createHash('sha256').update(stableKey).digest('hex').slice(0, 32)
+}
diff --git a/src/main/ipc/remote-workspace.test.ts b/src/main/ipc/remote-workspace.test.ts
new file mode 100644
index 00000000000..73b8bdbf785
--- /dev/null
+++ b/src/main/ipc/remote-workspace.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import { remoteWorkspaceSessionMatchesSnapshot } from './remote-workspace'
+import type {
+  RemoteWorkspaceSession,
+  RemoteWorkspaceSnapshot
+} from '../../shared/remote-workspace-types'
+
+function snapshot(session: RemoteWorkspaceSession): RemoteWorkspaceSnapshot {
+  return {
+    namespace: 'target',
+    revision: 7,
+    updatedAt: 123,
+    schemaVersion: 1,
+    session
+  }
+}
+
+describe('remoteWorkspaceSessionMatchesSnapshot', () => {
+  it('matches normalized equivalent sessions', () => {
+    expect(
+      remoteWorkspaceSessionMatchesSnapshot(
+        snapshot({
+          activeWorktreePath: null,
+          activeTabId: null,
+          tabsByWorktreePath: {},
+          terminalLayoutsByTabId: {}
+        }),
+        {
+          activeWorktreePath: null,
+          activeTabId: null,
+          tabsByWorktreePath: {},
+          terminalLayoutsByTabId: {},
+          activeWorktreePathsOnShutdown: undefined,
+          activeTabIdByWorktreePath: undefined,
+          remoteSessionIdsByTabId: undefined,
+          lastVisitedAtByWorktreePath: undefined
+        }
+      )
+    ).toBe(true)
+  })
+
+  it('treats empty optional projection fields as equivalent to absent fields', () => {
+    expect(
+      remoteWorkspaceSessionMatchesSnapshot(
+        snapshot({
+          activeWorktreePath: null,
+          activeTabId: null,
+          tabsByWorktreePath: {},
+          terminalLayoutsByTabId: {},
+          activeWorktreePathsOnShutdown: [],
+          activeTabIdByWorktreePath: {},
+          remoteSessionIdsByTabId: {},
+          lastVisitedAtByWorktreePath: {}
+        }),
+        {
+          activeWorktreePath: null,
+          activeTabId: null,
+          tabsByWorktreePath: {},
+          terminalLayoutsByTabId: {}
+        }
+      )
+    ).toBe(true)
+  })
+
+  it('detects actual target session changes', () => {
+    expect(
+      remoteWorkspaceSessionMatchesSnapshot(
+        snapshot({
+          activeWorktreePath: '/repo',
+          activeTabId: 'tab-1',
+          tabsByWorktreePath: {
+            '/repo': [{ id: 'tab-1', type: 'terminal', title: 'Shell' } as never]
+          },
+          terminalLayoutsByTabId: {}
+        }),
+        {
+          activeWorktreePath: '/repo',
+          activeTabId: 'tab-2',
+          tabsByWorktreePath: {
+            '/repo': [{ id: 'tab-2', type: 'terminal', title: 'Shell 2' } as never]
+          },
+          terminalLayoutsByTabId: {}
+        }
+      )
+    ).toBe(false)
+  })
+})
diff --git a/src/main/ipc/remote-workspace.ts b/src/main/ipc/remote-workspace.ts
new file mode 100644
index 00000000000..29db0172b29
--- /dev/null
+++ b/src/main/ipc/remote-workspace.ts
@@ -0,0 +1,385 @@
+/* oxlint-disable max-lines -- Why: remote workspace IPC keeps snapshot normalization, relay compatibility, and handler registration together so revision/cache semantics stay auditable. */
+import { randomUUID } from 'crypto'
+import { ipcMain, type BrowserWindow } from 'electron'
+import { hostname } from 'os'
+import { isDeepStrictEqual } from 'util'
+import type { Store } from '../persistence'
+import { getActiveMultiplexer, getSshConnectionStore } from './ssh'
+import {
+  exportRemoteWorkspaceSession,
+  importRemoteWorkspaceSession
+} from '../../shared/remote-workspace-session-projection'
+import type {
+  RemoteWorkspaceChangedEvent,
+  RemoteWorkspaceConnectedClient,
+  RemoteWorkspacePatchResult,
+  RemoteWorkspaceSession,
+  RemoteWorkspaceSnapshot
+} from '../../shared/remote-workspace-types'
+import type { SshTarget } from '../../shared/ssh-types'
+import type { WorkspaceSessionState } from '../../shared/types'
+import { getRepoIdFromWorktreeId, splitWorktreeId } from '../../shared/worktree-id'
+import { getRemoteWorkspaceNamespace } from './remote-workspace-namespace'
+import { registerRemoteWorkspaceNotificationHandler } from './remote-workspace-events'
+
+const CLIENT_ID = randomUUID()
+const CLIENT_NAME = hostname() || 'This device'
+const SNAPSHOT_SCHEMA_VERSION = 1
+
+let mainWindowGetter: (() => BrowserWindow | null) | null = null
+const latestSnapshotByTargetId = new Map<string, RemoteWorkspaceSnapshot>()
+let unregisterRemoteWorkspaceNotifications: (() => void) | null = null
+
+function emptyRemoteSession(): RemoteWorkspaceSession {
+  return {
+    activeWorktreePath: null,
+    activeTabId: null,
+    tabsByWorktreePath: {},
+    terminalLayoutsByTabId: {}
+  }
+}
+
+function normalizeOptionalStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined
+  }
+  const normalized = value.filter((entry): entry is string => typeof entry === 'string')
+  return normalized.length > 0 ? normalized : undefined
+}
+
+function normalizeOptionalRecord<T extends Record<string, unknown>>(value: unknown): T | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined
+  }
+  return Object.keys(value).length > 0 ? (value as T) : undefined
+}
+
+function normalizeRemoteSession(raw: unknown): RemoteWorkspaceSession {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return emptyRemoteSession()
+  }
+  const input = raw as Partial<RemoteWorkspaceSession>
+  return {
+    activeWorktreePath:
+      typeof input.activeWorktreePath === 'string' ? input.activeWorktreePath : null,
+    activeTabId: typeof input.activeTabId === 'string' ? input.activeTabId : null,
+    tabsByWorktreePath:
+      input.tabsByWorktreePath &&
+      typeof input.tabsByWorktreePath === 'object' &&
+      !Array.isArray(input.tabsByWorktreePath)
+        ? input.tabsByWorktreePath
+        : {},
+    terminalLayoutsByTabId:
+      input.terminalLayoutsByTabId &&
+      typeof input.terminalLayoutsByTabId === 'object' &&
+      !Array.isArray(input.terminalLayoutsByTabId)
+        ? input.terminalLayoutsByTabId
+        : {},
+    activeWorktreePathsOnShutdown: normalizeOptionalStringArray(
+      input.activeWorktreePathsOnShutdown
+    ),
+    activeTabIdByWorktreePath: normalizeOptionalRecord<Record<string, string | null>>(
+      input.activeTabIdByWorktreePath
+    ),
+    remoteSessionIdsByTabId: normalizeOptionalRecord<Record<string, string>>(
+      input.remoteSessionIdsByTabId
+    ),
+    lastVisitedAtByWorktreePath: normalizeOptionalRecord<Record<string, number>>(
+      input.lastVisitedAtByWorktreePath
+    )
+  }
+}
+
+function normalizeSnapshot(raw: unknown, fallbackNamespace: string): RemoteWorkspaceSnapshot {
+  const input = raw as Partial<RemoteWorkspaceSnapshot> | null
+  return {
+    namespace: typeof input?.namespace === 'string' ? input.namespace : fallbackNamespace,
+    revision:
+      typeof input?.revision === 'number' && Number.isFinite(input.revision) ? input.revision : 0,
+    updatedAt:
+      typeof input?.updatedAt === 'number' && Number.isFinite(input.updatedAt)
+        ? input.updatedAt
+        : 0,
+    schemaVersion:
+      typeof input?.schemaVersion === 'number' && Number.isFinite(input.schemaVersion)
+        ? input.schemaVersion
+        : SNAPSHOT_SCHEMA_VERSION,
+    session: normalizeRemoteSession(input?.session)
+  }
+}
+
+export function remoteWorkspaceSessionMatchesSnapshot(
+  snapshot: RemoteWorkspaceSnapshot | undefined,
+  session: RemoteWorkspaceSession
+): boolean {
+  if (!snapshot) {
+    return false
+  }
+  return isDeepStrictEqual(
+    normalizeRemoteSession(snapshot.session),
+    normalizeRemoteSession(session)
+  )
+}
+
+function normalizeConnectedClients(
+  raw: unknown,
+  currentClientId: string
+): RemoteWorkspaceConnectedClient[] {
+  const clients = (raw as { clients?: unknown } | null)?.clients
+  if (!Array.isArray(clients)) {
+    return []
+  }
+  return clients
+    .map((entry): RemoteWorkspaceConnectedClient | null => {
+      const item = entry as Partial<RemoteWorkspaceConnectedClient> | null
+      const clientId = typeof item?.clientId === 'string' ? item.clientId.trim() : ''
+      if (!clientId || clientId.length > 200) {
+        return null
+      }
+      return {
+        clientId,
+        name:
+          typeof item?.name === 'string' && item.name.trim()
+            ? item.name.replace(/\s+/g, ' ').trim().slice(0, 80)
+            : 'Unknown device',
+        lastSeenAt:
+          typeof item?.lastSeenAt === 'number' && Number.isFinite(item.lastSeenAt)
+            ? item.lastSeenAt
+            : 0,
+        isCurrent: clientId === currentClientId
+      }
+    })
+    .filter((entry): entry is RemoteWorkspaceConnectedClient => entry !== null)
+}
+
+function targetForWorktree(store: Store, worktreeId: string): string | null {
+  const repoId = getRepoIdFromWorktreeId(worktreeId)
+  return store.getRepo(repoId)?.connectionId ?? null
+}
+
+function exportSessionForTarget(
+  store: Store,
+  targetId: string,
+  session: WorkspaceSessionState
+): RemoteWorkspaceSession {
+  return exportRemoteWorkspaceSession(session, {
+    isTargetWorktree: (worktreeId) => targetForWorktree(store, worktreeId) === targetId
+  })
+}
+
+function importSessionForTarget(
+  store: Store,
+  targetId: string,
+  remote: RemoteWorkspaceSession
+): WorkspaceSessionState {
+  const repos = store.getRepos().filter((repo) => repo.connectionId === targetId)
+  const repoById = new Map(repos.map((repo) => [repo.id, repo]))
+  return importRemoteWorkspaceSession(remote, {
+    resolveWorktreeId: (worktreePath) => {
+      for (const repo of repoById.values()) {
+        const candidate = `${repo.id}::${worktreePath}`
+        // Main does not own the live worktree list for SSH repos, so resolve
+        // against repo identity only. Renderer hydration later validates IDs
+        // against its fetched worktree list before panes mount.
+        if (splitWorktreeId(candidate)) {
+          return candidate
+        }
+      }
+      return null
+    }
+  })
+}
+
+async function getRemoteSnapshot(target: SshTarget): Promise<RemoteWorkspaceSnapshot | null> {
+  if (!target.remoteWorkspaceSyncEnabled) {
+    return null
+  }
+  const mux = getActiveMultiplexer(target.id)
+  if (!mux) {
+    return null
+  }
+  const namespace = getRemoteWorkspaceNamespace(target)
+  try {
+    const raw = await mux.request('workspace.get', { namespace })
+    const snapshot = normalizeSnapshot(raw, namespace)
+    latestSnapshotByTargetId.set(target.id, snapshot)
+    return snapshot
+  } catch (err) {
+    if ((err as { code?: unknown })?.code === -32601) {
+      return null
+    }
+    throw err
+  }
+}
+
+export function handleRemoteWorkspaceNotification(
+  targetId: string,
+  method: string,
+  params: Record<string, unknown>
+): void {
+  if (method !== 'workspace.changed') {
+    return
+  }
+  const target = getSshConnectionStore()?.getTarget(targetId)
+  if (!target?.remoteWorkspaceSyncEnabled) {
+    return
+  }
+  const namespace = getRemoteWorkspaceNamespace(target)
+  const snapshot = normalizeSnapshot(params.snapshot, namespace)
+  latestSnapshotByTargetId.set(targetId, snapshot)
+  const event: RemoteWorkspaceChangedEvent = {
+    targetId,
+    snapshot,
+    sourceClientId: typeof params.sourceClientId === 'string' ? params.sourceClientId : undefined
+  }
+  const win = mainWindowGetter?.()
+  if (win && !win.isDestroyed()) {
+    win.webContents.send('remoteWorkspace:changed', event)
+  }
+}
+
+export function registerRemoteWorkspaceHandlers(
+  store: Store,
+  getMainWindow: () => BrowserWindow | null
+): void {
+  mainWindowGetter = getMainWindow
+  unregisterRemoteWorkspaceNotifications?.()
+  unregisterRemoteWorkspaceNotifications = registerRemoteWorkspaceNotificationHandler(
+    handleRemoteWorkspaceNotification
+  )
+  ipcMain.removeHandler('remoteWorkspace:get')
+  ipcMain.removeHandler('remoteWorkspace:setForConnectedTargets')
+  ipcMain.removeHandler('remoteWorkspace:listEnabledConnectedTargets')
+  ipcMain.removeHandler('remoteWorkspace:listConnectedClients')
+  ipcMain.removeHandler('remoteWorkspace:clientId')
+
+  ipcMain.handle('remoteWorkspace:get', async (_event, args: { targetId: string }) => {
+    const target = getSshConnectionStore()?.getTarget(args.targetId)
+    if (!target) {
+      return null
+    }
+    return getRemoteSnapshot(target)
+  })
+
+  ipcMain.handle(
+    'remoteWorkspace:setForConnectedTargets',
+    async (_event, args: { session: WorkspaceSessionState; hydratedTargetIds?: string[] }) => {
+      const hydratedTargetIds = Array.isArray(args.hydratedTargetIds)
+        ? new Set(args.hydratedTargetIds)
+        : null
+      const targets =
+        getSshConnectionStore()
+          ?.listTargets()
+          .filter(
+            (target) =>
+              target.remoteWorkspaceSyncEnabled &&
+              getActiveMultiplexer(target.id) &&
+              (!hydratedTargetIds || hydratedTargetIds.has(target.id))
+          ) ?? []
+
+      const results: { targetId: string; result: RemoteWorkspacePatchResult }[] = []
+      for (const target of targets) {
+        const mux = getActiveMultiplexer(target.id)
+        if (!mux) {
+          continue
+        }
+        const namespace = getRemoteWorkspaceNamespace(target)
+        const current =
+          latestSnapshotByTargetId.get(target.id) ?? (await getRemoteSnapshot(target)) ?? undefined
+        const session = exportSessionForTarget(store, target.id, args.session)
+        let result: RemoteWorkspacePatchResult
+        if (current && remoteWorkspaceSessionMatchesSnapshot(current, session)) {
+          // Why: a pulled workspace snapshot rehydrates local state and can
+          // trigger session persistence. Identical target sessions must be a
+          // local no-op or two clients will echo revisions indefinitely.
+          result = { ok: true, snapshot: current }
+          results.push({ targetId: target.id, result })
+          continue
+        }
+        try {
+          result = (await mux.request('workspace.patch', {
+            namespace,
+            baseRevision: current?.revision ?? 0,
+            clientId: CLIENT_ID,
+            patch: { kind: 'replace-session', session }
+          })) as RemoteWorkspacePatchResult
+        } catch (err) {
+          result =
+            (err as { code?: unknown })?.code === -32601
+              ? {
+                  ok: false,
+                  reason: 'unavailable',
+                  message: 'Remote workspace sync is unavailable on this relay'
+                }
+              : {
+                  ok: false,
+                  reason: 'unavailable',
+                  message: err instanceof Error ? err.message : 'Remote workspace sync failed'
+                }
+        }
+        if (result.ok) {
+          latestSnapshotByTargetId.set(target.id, result.snapshot)
+        }
+        results.push({ targetId: target.id, result })
+      }
+      return results
+    }
+  )
+
+  ipcMain.handle(
+    'remoteWorkspace:listEnabledConnectedTargets',
+    async () =>
+      getSshConnectionStore()
+        ?.listTargets()
+        .filter((target) => target.remoteWorkspaceSyncEnabled && getActiveMultiplexer(target.id))
+        .map((target) => target.id) ?? []
+  )
+
+  ipcMain.handle(
+    'remoteWorkspace:listConnectedClients',
+    async (_event, args?: { targetIds?: string[] }) => {
+      const requestedTargetIds = Array.isArray(args?.targetIds) ? new Set(args.targetIds) : null
+      const targets =
+        getSshConnectionStore()
+          ?.listTargets()
+          .filter(
+            (target) =>
+              target.remoteWorkspaceSyncEnabled &&
+              getActiveMultiplexer(target.id) &&
+              (!requestedTargetIds || requestedTargetIds.has(target.id))
+          ) ?? []
+      const results: { targetId: string; clients: RemoteWorkspaceConnectedClient[] }[] = []
+      for (const target of targets) {
+        const mux = getActiveMultiplexer(target.id)
+        if (!mux) {
+          continue
+        }
+        const namespace = getRemoteWorkspaceNamespace(target)
+        try {
+          const raw = await mux.request('workspace.presence', {
+            namespace,
+            clientId: CLIENT_ID,
+            clientName: CLIENT_NAME
+          })
+          results.push({
+            targetId: target.id,
+            clients: normalizeConnectedClients(raw, CLIENT_ID)
+          })
+        } catch {
+          results.push({ targetId: target.id, clients: [] })
+        }
+      }
+      return results
+    }
+  )
+
+  ipcMain.handle('remoteWorkspace:clientId', () => CLIENT_ID)
+}
+
+export function materializeRemoteWorkspaceForTarget(
+  store: Store,
+  targetId: string,
+  snapshot: RemoteWorkspaceSnapshot
+): WorkspaceSessionState {
+  return importSessionForTarget(store, targetId, snapshot.session)
+}
diff --git a/src/main/ipc/ssh.ts b/src/main/ipc/ssh.ts
index 07d4a4de2b8..3f7f1dddad4 100644
--- a/src/main/ipc/ssh.ts
+++ b/src/main/ipc/ssh.ts
@@ -36,6 +36,15 @@ let portForwardManager: SshPortForwardManager | null = null
 // scattered Maps/Sets that previously tracked this state independently.
 const activeSessions = new Map<string, SshRelaySession>()
 
+function relayGracePeriodForTarget(target: SshTarget | null | undefined): number | undefined {
+  if (!target?.remoteWorkspaceSyncEnabled) {
+    return target?.relayGracePeriodSeconds
+  }
+  // Why: cross-device sync should survive transient app closes, but an
+  // unset value must not mean "keep remote PTYs forever" after disconnect.
+  return target.remoteWorkspaceSyncGracePeriodSeconds ?? 300
+}
+
 // Why: multiple renderer tabs for the same SSH target can fire ssh:connect
 // concurrently. Without serialization, the second call interleaves with the
 // first — both see no existing session, both create one, and the first one
@@ -260,7 +269,7 @@ export function registerSshHandlers(
         const target = sshStore?.getTarget(targetId)
         const conn = connectionManager?.getConnection(targetId)
         if (conn) {
-          void session.reconnect(conn, target?.relayGracePeriodSeconds)
+          void session.reconnect(conn, relayGracePeriodForTarget(target))
         }
       }
     }
@@ -495,7 +504,7 @@ export function registerSshHandlers(
           if (!liveConn || !activeSessions.has(tid)) {
             return
           }
-          void s.reconnect(liveConn, t?.relayGracePeriodSeconds)
+          void s.reconnect(liveConn, relayGracePeriodForTarget(t))
         }, delay)
         relayLostBackoff.set(tid, state)
         console.warn(
@@ -523,7 +532,7 @@ export function registerSshHandlers(
         void restorePortForwards(tid, getMainWindow)
       })
 
-      await session.establish(conn, target.relayGracePeriodSeconds)
+      await session.establish(conn, relayGracePeriodForTarget(target))
 
       // Why: we manually pushed `deploying-relay` above, so the renderer's
       // state is stuck there. Send `connected` directly to the renderer
diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index 066c39d981e..27883eec850 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -22,6 +22,7 @@ import { getPRForBranch } from '../github/client'
 import { listWorktrees, addWorktree, addSparseWorktree } from '../git/worktree'
 import { getGitUsername, getDefaultBaseRef, getBranchConflictKind } from '../git/repo'
 import { validateGitPushTarget } from '../git/push-target-validation'
+import { assertGitPushTargetShape } from '../../shared/git-push-target-validation'
 import { gitExecFileAsync } from '../git/runner'
 import { parseGitHubOwnerRepo } from '../github/gh-utils'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
@@ -150,6 +151,108 @@ export async function configureCreatedWorktreePushTarget(
   return target
 }
 
+async function findRemoteForUrlSsh(
+  provider: SshGitProvider,
+  repoPath: string,
+  remoteUrl: string
+): Promise<string | null> {
+  const target = parseGitHubOwnerRepo(remoteUrl)
+  try {
+    const { stdout } = await provider.exec(['remote'], repoPath)
+    for (const remote of stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)) {
+      try {
+        const { stdout: urlStdout } = await provider.exec(['remote', 'get-url', remote], repoPath)
+        const candidateUrl = urlStdout.trim()
+        const candidate = parseGitHubOwnerRepo(candidateUrl)
+        if (
+          target &&
+          candidate &&
+          target.owner.toLowerCase() === candidate.owner.toLowerCase() &&
+          target.repo.toLowerCase() === candidate.repo.toLowerCase()
+        ) {
+          return remote
+        }
+        if (candidateUrl === remoteUrl) {
+          return remote
+        }
+      } catch {
+        // Ignore a remote that disappeared or has no fetch URL.
+      }
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+async function ensureUniqueRemoteNameSsh(
+  provider: SshGitProvider,
+  repoPath: string,
+  preferred: string
+): Promise<string> {
+  const { stdout } = await provider.exec(['remote'], repoPath)
+  const existing = new Set(
+    stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+  )
+  if (!existing.has(preferred)) {
+    return preferred
+  }
+  for (let suffix = 2; suffix < 100; suffix += 1) {
+    const candidate = `${preferred}-${suffix}`
+    if (!existing.has(candidate)) {
+      return candidate
+    }
+  }
+  throw new Error(`Could not find an available remote name for ${preferred}.`)
+}
+
+async function prepareWorktreePushTargetSsh(
+  provider: SshGitProvider,
+  repoPath: string,
+  target: GitPushTarget
+): Promise<GitPushTarget> {
+  assertGitPushTargetShape(target)
+  await provider.exec(['check-ref-format', '--branch', target.branchName], repoPath)
+  let remoteName = target.remoteName
+  if (target.remoteUrl) {
+    const existingRemote = await findRemoteForUrlSsh(provider, repoPath, target.remoteUrl)
+    if (existingRemote) {
+      remoteName = existingRemote
+    } else {
+      remoteName = await ensureUniqueRemoteNameSsh(provider, repoPath, target.remoteName)
+      await provider.exec(['remote', 'add', remoteName, target.remoteUrl], repoPath)
+    }
+  }
+  await provider.exec(
+    [
+      'fetch',
+      remoteName,
+      `+refs/heads/${target.branchName}:refs/remotes/${remoteName}/${target.branchName}`
+    ],
+    repoPath
+  )
+  return { ...target, remoteName }
+}
+
+async function configureCreatedWorktreePushTargetSsh(
+  provider: SshGitProvider,
+  worktreePath: string,
+  branchName: string,
+  target: GitPushTarget
+): Promise<GitPushTarget> {
+  await provider.exec(
+    ['branch', '--set-upstream-to', `${target.remoteName}/${target.branchName}`, branchName],
+    worktreePath
+  )
+  return target
+}
+
 export function notifyWorktreesChanged(mainWindow: BrowserWindow, repoId: string): void {
   if (!mainWindow.isDestroyed()) {
     mainWindow.webContents.send('worktrees:changed', { repoId })
@@ -250,6 +353,13 @@ export async function createRemoteWorktree(
     /* best-effort */
   }
 
+  let preparedPushTarget: GitPushTarget | undefined
+  if (args.pushTarget) {
+    // Why: fork-PR SSH worktrees need the same contributor-remote setup as
+    // local worktrees before creation, otherwise Push/Sync can target origin.
+    preparedPushTarget = await prepareWorktreePushTargetSsh(provider, repo.path, args.pushTarget)
+  }
+
   const mux = getActiveMultiplexer(repo.connectionId!)
   if (!mux) {
     throw new Error('SSH connection is not available. Please reconnect and try again.')
@@ -310,6 +420,15 @@ export async function createRemoteWorktree(
 
   const worktreeId = `${repo.id}::${created.path}`
   const now = Date.now()
+  let configuredPushTarget: GitPushTarget | undefined
+  if (preparedPushTarget) {
+    configuredPushTarget = await configureCreatedWorktreePushTargetSsh(
+      provider,
+      created.path,
+      branchName,
+      preparedPushTarget
+    )
+  }
   const metaUpdates: Partial<WorktreeMeta> = {
     lastActivityAt: now,
     // Why: grants the new worktree a short grace window at the top of the
@@ -319,6 +438,8 @@ export async function createRemoteWorktree(
     // max(lastActivityAt, createdAt + GRACE_MS) to keep it on top until the
     // window elapses. See smart-sort.ts `CREATE_GRACE_MS`.
     createdAt: now,
+    baseRef: baseBranch,
+    ...(configuredPushTarget ? { pushTarget: configuredPushTarget } : {}),
     ...(requestedDisplayName
       ? { displayName: requestedDisplayName }
       : shouldSetDisplayName(requestedName, branchName, sanitizedName)
@@ -326,7 +447,8 @@ export async function createRemoteWorktree(
         : {}),
     ...(isTuiAgent(args.createdWithAgent) ? { createdWithAgent: args.createdWithAgent } : {}),
     ...(args.linkedIssue !== undefined ? { linkedIssue: args.linkedIssue } : {}),
-    ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {})
+    ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {}),
+    ...(args.linkedLinearIssue !== undefined ? { linkedLinearIssue: args.linkedLinearIssue } : {})
   }
   const meta = store.setWorktreeMeta(worktreeId, metaUpdates)
   const worktree = mergeWorktree(repo.id, created, meta)
@@ -617,7 +739,8 @@ export async function createLocalWorktree(
       : {}),
     ...(isTuiAgent(args.createdWithAgent) ? { createdWithAgent: args.createdWithAgent } : {}),
     ...(args.linkedIssue !== undefined ? { linkedIssue: args.linkedIssue } : {}),
-    ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {})
+    ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {}),
+    ...(args.linkedLinearIssue !== undefined ? { linkedLinearIssue: args.linkedLinearIssue } : {})
   }
   const meta = store.setWorktreeMeta(worktreeId, metaUpdates)
   const worktree = mergeWorktree(repo.id, created, meta)
diff --git a/src/main/ipc/worktrees.test.ts b/src/main/ipc/worktrees.test.ts
index 1b053b54004..71d3b459c71 100644
--- a/src/main/ipc/worktrees.test.ts
+++ b/src/main/ipc/worktrees.test.ts
@@ -427,20 +427,23 @@ describe('registerWorktreeHandlers', () => {
       repoId: 'repo-1',
       name: 'improve-dashboard',
       linkedIssue: 123,
-      linkedPR: 456
+      linkedPR: 456,
+      linkedLinearIssue: 'ENG-123'
     })
 
     expect(store.setWorktreeMeta).toHaveBeenCalledWith(
       'repo-1::/workspace/improve-dashboard',
       expect.objectContaining({
         linkedIssue: 123,
-        linkedPR: 456
+        linkedPR: 456,
+        linkedLinearIssue: 'ENG-123'
       })
     )
     expect(result).toEqual({
       worktree: expect.objectContaining({
         linkedIssue: 123,
-        linkedPR: 456
+        linkedPR: 456,
+        linkedLinearIssue: 'ENG-123'
       })
     })
   })
@@ -602,7 +605,8 @@ describe('registerWorktreeHandlers', () => {
       name: 'improve-dashboard',
       linkedIssue: 123,
       linkedPR: 456,
-      createdWithAgent: 'codex'
+      createdWithAgent: 'codex',
+      linkedLinearIssue: 'ENG-123'
     })
 
     expect(store.setWorktreeMeta).toHaveBeenCalledWith(
@@ -610,14 +614,16 @@ describe('registerWorktreeHandlers', () => {
       expect.objectContaining({
         linkedIssue: 123,
         linkedPR: 456,
-        createdWithAgent: 'codex'
+        createdWithAgent: 'codex',
+        linkedLinearIssue: 'ENG-123'
       })
     )
     expect(result).toEqual({
       worktree: expect.objectContaining({
         linkedIssue: 123,
         linkedPR: 456,
-        createdWithAgent: 'codex'
+        createdWithAgent: 'codex',
+        linkedLinearIssue: 'ENG-123'
       })
     })
   })
diff --git a/src/main/ipc/worktrees.ts b/src/main/ipc/worktrees.ts
index 91390b7c108..a22ad1d258a 100644
--- a/src/main/ipc/worktrees.ts
+++ b/src/main/ipc/worktrees.ts
@@ -377,14 +377,21 @@ export function registerWorktreeHandlers(
       if (!repo) {
         return { error: 'Repo not found' }
       }
-      // Why: remote SSH repos are out of scope in v1. The picker already
-      // disables its PR tab for them — this guard belt-and-suspenders it.
-      if (repo.connectionId) {
-        return { error: 'PR start points are not supported for remote repos yet.' }
-      }
       if (isFolderRepo(repo)) {
         return { error: 'Folder mode does not support creating worktrees.' }
       }
+      const gitExec = async (args: string[]): Promise<{ stdout: string; stderr: string }> => {
+        if (!repo.connectionId) {
+          return gitExecFileAsync(args, { cwd: repo.path })
+        }
+        const provider = getSshGitProvider(repo.connectionId)
+        if (!provider) {
+          throw new Error(
+            'SSH Git provider is not available. Reconnect to this target and try again.'
+          )
+        }
+        return provider.exec(args, repo.path)
+      }
 
       let headRefName = args.headRefName?.trim() ?? ''
       let isCrossRepository = args.isCrossRepository === true
@@ -395,7 +402,7 @@ export function registerWorktreeHandlers(
         // Why: the caller already knows this is a PR number, so scope the
         // lookup to `type: 'pr'` and skip the speculative issue-first probe
         // that would hit the upstream issue tracker for fork checkouts.
-        const item = await getWorkItem(repo.path, args.prNumber, 'pr')
+        const item = await getWorkItem(repo.path, args.prNumber, 'pr', repo.connectionId ?? null)
         if (!item || item.type !== 'pr') {
           return { error: `PR #${args.prNumber} not found.` }
         }
@@ -409,7 +416,9 @@ export function registerWorktreeHandlers(
       }
       if (isCrossRepository) {
         try {
-          pushTarget = (await getPullRequestPushTarget(repo.path, args.prNumber)) ?? undefined
+          pushTarget =
+            (await getPullRequestPushTarget(repo.path, args.prNumber, repo.connectionId ?? null)) ??
+            undefined
         } catch (error) {
           return {
             error:
@@ -425,7 +434,16 @@ export function registerWorktreeHandlers(
 
       let remote: string
       try {
-        remote = await getDefaultRemote(repo.path)
+        if (repo.connectionId) {
+          const { stdout } = await gitExec(['remote'])
+          remote =
+            stdout
+              .split('\n')
+              .map((line) => line.trim())
+              .find(Boolean) ?? 'origin'
+        } else {
+          remote = await getDefaultRemote(repo.path)
+        }
       } catch (error) {
         return { error: error instanceof Error ? error.message : 'Could not resolve git remote.' }
       }
@@ -440,7 +458,7 @@ export function registerWorktreeHandlers(
       if (isCrossRepository) {
         const pullRef = `refs/pull/${args.prNumber}/head`
         try {
-          await gitExecFileAsync(['fetch', remote, pullRef], { cwd: repo.path })
+          await gitExec(['fetch', remote, pullRef])
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error)
           return {
@@ -449,9 +467,7 @@ export function registerWorktreeHandlers(
         }
         let sha: string
         try {
-          const { stdout } = await gitExecFileAsync(['rev-parse', '--verify', 'FETCH_HEAD'], {
-            cwd: repo.path
-          })
+          const { stdout } = await gitExec(['rev-parse', '--verify', 'FETCH_HEAD'])
           sha = stdout.trim()
         } catch {
           return { error: `Could not resolve fork PR #${args.prNumber} head after fetch.` }
@@ -463,10 +479,11 @@ export function registerWorktreeHandlers(
       }
 
       try {
-        await gitExecFileAsync(
-          ['fetch', remote, `+refs/heads/${headRefName}:refs/remotes/${remote}/${headRefName}`],
-          { cwd: repo.path }
-        )
+        await gitExec([
+          'fetch',
+          remote,
+          `+refs/heads/${headRefName}:refs/remotes/${remote}/${headRefName}`
+        ])
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error)
         return {
@@ -476,7 +493,7 @@ export function registerWorktreeHandlers(
 
       const remoteRef = `${remote}/${headRefName}`
       try {
-        await gitExecFileAsync(['rev-parse', '--verify', remoteRef], { cwd: repo.path })
+        await gitExec(['rev-parse', '--verify', remoteRef])
       } catch {
         return { error: `Remote ref ${remoteRef} does not exist after fetch.` }
       }
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 3e3dfd25098..803dea1d4f3 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -4943,6 +4943,7 @@ export class OrcaRuntimeService {
     baseBranch?: string
     linkedIssue?: number | null
     linkedPR?: number | null
+    linkedLinearIssue?: string
     comment?: string
     displayName?: string
     sparseCheckout?: { directories: string[]; presetId?: string }
@@ -5100,6 +5101,9 @@ export class OrcaRuntimeService {
         : {}),
       ...(args.linkedIssue !== undefined ? { linkedIssue: args.linkedIssue } : {}),
       ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {}),
+      ...(args.linkedLinearIssue !== undefined
+        ? { linkedLinearIssue: args.linkedLinearIssue }
+        : {}),
       ...(args.createdWithAgent ? { createdWithAgent: args.createdWithAgent } : {}),
       ...(args.comment !== undefined ? { comment: args.comment } : {})
     })
diff --git a/src/main/runtime/rpc/methods/worktree.ts b/src/main/runtime/rpc/methods/worktree.ts
index 0dd7c5384ba..ee3de8f36e6 100644
--- a/src/main/runtime/rpc/methods/worktree.ts
+++ b/src/main/runtime/rpc/methods/worktree.ts
@@ -38,6 +38,7 @@ const WorktreeCreate = z.object({
   baseBranch: OptionalString,
   linkedIssue: TriStateLinkedIssue,
   linkedPR: TriStateLinkedIssue,
+  linkedLinearIssue: z.string().optional(),
   comment: OptionalString,
   displayName: OptionalString,
   sparseCheckout: z
@@ -155,6 +156,7 @@ export const WORKTREE_METHODS: RpcMethod[] = [
         baseBranch: params.baseBranch,
         linkedIssue: params.linkedIssue,
         linkedPR: params.linkedPR,
+        linkedLinearIssue: params.linkedLinearIssue,
         comment: params.comment,
         displayName: params.displayName,
         sparseCheckout: params.sparseCheckout,
diff --git a/src/main/source-control/hosted-review.test.ts b/src/main/source-control/hosted-review.test.ts
index c45138b2663..e77f51d6b7d 100644
--- a/src/main/source-control/hosted-review.test.ts
+++ b/src/main/source-control/hosted-review.test.ts
@@ -108,7 +108,7 @@ describe('getHostedReviewForBranch', () => {
       number: 3,
       status: 'pending'
     })
-    expect(getPRForBranchMock).toHaveBeenCalledWith('/repo', 'feature', 3)
+    expect(getPRForBranchMock).toHaveBeenCalledWith('/repo', 'feature', 3, undefined)
   })
 
   it('falls through to Bitbucket when origin is not GitLab or GitHub', async () => {
diff --git a/src/main/source-control/hosted-review.ts b/src/main/source-control/hosted-review.ts
index 1e3ce4e4b40..401f6b973a0 100644
--- a/src/main/source-control/hosted-review.ts
+++ b/src/main/source-control/hosted-review.ts
@@ -82,6 +82,7 @@ function mapGiteaReview(pr: GiteaPullRequestInfo): HostedReviewInfo {
 
 export async function getHostedReviewForBranch(input: {
   repoPath: string
+  connectionId?: string | null
   branch: string
   linkedGitHubPR?: number | null
   linkedGitLabMR?: number | null
@@ -110,9 +111,14 @@ export async function getHostedReviewForBranch(input: {
     return mr ? mapGitLabReview(mr) : null
   }
 
-  const githubRepo = await getRepoSlug(input.repoPath)
+  const githubRepo = await getRepoSlug(input.repoPath, input.connectionId)
   if (githubRepo) {
-    const pr = await getPRForBranch(input.repoPath, branchName, input.linkedGitHubPR ?? null)
+    const pr = await getPRForBranch(
+      input.repoPath,
+      branchName,
+      input.linkedGitHubPR ?? null,
+      input.connectionId
+    )
     return pr ? mapGitHubReview(pr) : null
   }
 
diff --git a/src/main/ssh/ssh-channel-multiplexer.ts b/src/main/ssh/ssh-channel-multiplexer.ts
index 9d95bbd05b8..a780de7242f 100644
--- a/src/main/ssh/ssh-channel-multiplexer.ts
+++ b/src/main/ssh/ssh-channel-multiplexer.ts
@@ -216,10 +216,12 @@ export class SshChannelMultiplexer {
     if (this.disposed) {
       return
     }
-    console.warn(
-      `[ssh-mux] Disposing multiplexer (reason: ${reason})`,
-      new Error('dispose trace').stack
-    )
+    if (process.env.ORCA_SSH_MUX_DEBUG === '1') {
+      console.warn(
+        `[ssh-mux] Disposing multiplexer (reason: ${reason})`,
+        new Error('dispose trace').stack
+      )
+    }
     this.disposed = true
 
     if (this.keepaliveTimer) {
diff --git a/src/main/ssh/ssh-relay-deploy.ts b/src/main/ssh/ssh-relay-deploy.ts
index 03dbeaf038b..26d589495fb 100644
--- a/src/main/ssh/ssh-relay-deploy.ts
+++ b/src/main/ssh/ssh-relay-deploy.ts
@@ -185,7 +185,7 @@ async function uploadRelay(
   const localRelayDir = getLocalRelayPath(platform)
   if (!localRelayDir || !existsSync(localRelayDir)) {
     throw new Error(
-      `Relay package for ${platform} not found at ${localRelayDir}. ` +
+      `Relay package for ${platform} not found. Searched: ${getLocalRelayCandidates(platform).join(', ')}. ` +
         `This may be a packaging issue — try reinstalling Orca.`
     )
   }
@@ -221,7 +221,10 @@ async function uploadRelay(
   }
 }
 
-const RELAY_NATIVE_DEPS = ['node-pty', '@parcel/watcher'] as const
+const RELAY_NATIVE_DEPS = {
+  'node-pty': '1.1.0',
+  '@parcel/watcher': '2.5.6'
+} as const
 
 async function hasRequiredNativeDeps(conn: SshConnection, remoteDir: string): Promise<boolean> {
   const nodePath = await resolveRemoteNodePath(conn)
@@ -298,7 +301,7 @@ async function installNativeDeps(
     version: '1.0.0',
     private: true,
     type: 'commonjs',
-    dependencies: Object.fromEntries(RELAY_NATIVE_DEPS.map((name) => [name, '*']))
+    dependencies: RELAY_NATIVE_DEPS
   })}\n`
   const sftpPkg = await conn.sftp()
   try {
@@ -316,10 +319,12 @@ async function installNativeDeps(
   }
 
   try {
-    const installArgs = RELAY_NATIVE_DEPS.map((dep) => shellEscape(dep)).join(' ')
+    const installArgs = Object.entries(RELAY_NATIVE_DEPS)
+      .map(([dep, version]) => shellEscape(`${dep}@${version}`))
+      .join(' ')
     await execCommand(
       conn,
-      `export PATH=${escapedBinDir}:$PATH && cd ${escapedDir} && npm install ${installArgs} 2>&1`
+      `export PATH=${escapedBinDir}:$PATH && cd ${escapedDir} && npm install --omit=dev --no-audit --no-fund ${installArgs} 2>&1`
     )
   } catch (err) {
     // Don't write .install-complete on hard fail; reconnect retries on a
@@ -364,28 +369,36 @@ async function installNativeDeps(
 }
 
 function getLocalRelayPath(platform: RelayPlatform): string | null {
-  if (process.env.ORCA_RELAY_PATH) {
-    const override = join(process.env.ORCA_RELAY_PATH, platform)
-    if (existsSync(override)) {
-      return override
+  for (const candidate of getLocalRelayCandidates(platform)) {
+    if (existsSync(candidate)) {
+      return candidate
     }
   }
-
-  // Production: bundled alongside the app
-  const prodPath = join(app.getAppPath(), 'resources', 'relay', platform)
-  if (existsSync(prodPath)) {
-    return prodPath
-  }
-
-  // Development: built by `pnpm build:relay` into out/relay/{platform}/
-  const devPath = join(app.getAppPath(), 'out', 'relay', platform)
-  if (existsSync(devPath)) {
-    return devPath
-  }
-
   return null
 }
 
+export function getLocalRelayCandidates(platform: RelayPlatform): string[] {
+  const candidates: string[] = []
+  if (process.env.ORCA_RELAY_PATH) {
+    candidates.push(join(process.env.ORCA_RELAY_PATH, platform))
+  }
+
+  // Why: electron-builder copies extraResources next to the app bundle, while
+  // app.getAppPath() points at app.asar in packaged builds.
+  if (process.resourcesPath) {
+    candidates.push(join(process.resourcesPath, 'relay', platform))
+    candidates.push(join(process.resourcesPath, 'app.asar.unpacked', 'out', 'relay', platform))
+  }
+
+  const appPath = app.getAppPath()
+  candidates.push(
+    join(appPath, 'resources', 'relay', platform),
+    join(appPath, 'out', 'relay', platform)
+  )
+
+  return [...new Set(candidates)]
+}
+
 async function launchRelay(
   conn: SshConnection,
   remoteDir: string,
@@ -400,7 +413,8 @@ async function launchRelay(
   const nodePath = await resolveRemoteNodePath(conn)
   // Why: graceTimeSeconds originates from user-editable SshTarget config.
   // Clamping to integer prevents shell injection if the type ever loosened.
-  const graceTime = Math.max(60, Math.min(3600, Math.floor(graceTimeSeconds ?? 300)))
+  const requestedGraceTime = Math.floor(graceTimeSeconds ?? 300)
+  const graceTime = requestedGraceTime === 0 ? 0 : Math.max(60, Math.min(3600, requestedGraceTime))
   const escapedDir = shellEscape(remoteDir)
   const escapedNode = shellEscape(nodePath)
   // Why: remoteRelayDir is shared by every Orca target for the same remote
diff --git a/src/main/ssh/ssh-relay-native-deps-install.test.ts b/src/main/ssh/ssh-relay-native-deps-install.test.ts
index cb4c6b6ec56..0a09308d6d7 100644
--- a/src/main/ssh/ssh-relay-native-deps-install.test.ts
+++ b/src/main/ssh/ssh-relay-native-deps-install.test.ts
@@ -234,7 +234,7 @@ describe('installNativeDeps (via deployAndLaunchRelay)', () => {
     // Why: pin commonjs so a future Node default flip doesn't silently
     // break `require('node-pty')`.
     expect(parsed.type).toBe('commonjs')
-    expect(parsed.dependencies).toEqual({ '@parcel/watcher': '*', 'node-pty': '*' })
+    expect(parsed.dependencies).toEqual({ '@parcel/watcher': '2.5.6', 'node-pty': '1.1.0' })
 
     const execCalls = vi.mocked(execCommand).mock.calls.map(([, c]) => c)
     const npmInstallIdx = execCalls.findIndex(
diff --git a/src/main/ssh/ssh-relay-session.ts b/src/main/ssh/ssh-relay-session.ts
index cbccd4bb4ce..7a9f5d4fb2a 100644
--- a/src/main/ssh/ssh-relay-session.ts
+++ b/src/main/ssh/ssh-relay-session.ts
@@ -41,6 +41,7 @@ import {
   getSshFilesystemProvider
 } from '../providers/ssh-filesystem-dispatch'
 import { registerSshGitProvider, unregisterSshGitProvider } from '../providers/ssh-git-dispatch'
+import { notifyRemoteWorkspaceHandlers } from '../ipc/remote-workspace-events'
 import { PortScanner } from './ssh-port-scanner'
 import type { SshPortForwardManager } from './ssh-port-forward'
 import type { SshConnection } from './ssh-connection'
@@ -449,6 +450,7 @@ export class SshRelaySession {
 
     this.wireUpPtyEvents(ptyProvider)
     this.wireUpAgentHookEvents(mux)
+    this.wireUpRemoteWorkspaceEvents(mux)
     return true
   }
 
@@ -493,6 +495,12 @@ export class SshRelaySession {
     }
   }
 
+  private wireUpRemoteWorkspaceEvents(mux: SshChannelMultiplexer): void {
+    mux.onNotification((method, params) => {
+      notifyRemoteWorkspaceHandlers(this.targetId, method, params)
+    })
+  }
+
   // Why: route the relay's `agent.hook` JSON-RPC notification into Orca's
   // shared `agentHookServer` via `ingestRemote`. The wire envelope carries
   // `connectionId: null` (the relay does not know Orca's local handle); we
diff --git a/src/main/window/attach-main-window-services.ts b/src/main/window/attach-main-window-services.ts
index afd62e898e3..6bc943dec84 100644
--- a/src/main/window/attach-main-window-services.ts
+++ b/src/main/window/attach-main-window-services.ts
@@ -13,6 +13,7 @@ import { registerWorktreeHandlers } from '../ipc/worktrees'
 import { registerPtyHandlers } from '../ipc/pty'
 import { registerDaemonManagementHandlers } from '../ipc/pty-management'
 import { registerSshHandlers } from '../ipc/ssh'
+import { registerRemoteWorkspaceHandlers } from '../ipc/remote-workspace'
 import { browserManager } from '../browser/browser-manager'
 import { hasSystemMediaAccess, requestSystemMediaAccess } from '../browser/browser-media-access'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
@@ -75,6 +76,7 @@ export function attachMainWindowServices(
   // git I/O or daemon RPC.
   void hydrateLocalPtyRegistryAtBoot(store)
   registerSshHandlers(store, () => mainWindow, runtime)
+  registerRemoteWorkspaceHandlers(store, () => mainWindow)
   registerFileDropRelay(mainWindow)
   setupAutoUpdater(mainWindow, {
     getLastUpdateCheckAt: () => store.getUI().lastUpdateCheckAt,
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 8bcb4ce9467..eb41cd2e376 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -206,6 +206,12 @@ import type {
 } from '../shared/codex-usage-types'
 import type { TelemetryConsentState } from '../shared/telemetry-consent-types'
 import type { AgentKind, LaunchSource, RequestKind } from '../shared/telemetry-events'
+import type {
+  RemoteWorkspaceChangedEvent,
+  RemoteWorkspaceConnectedClient,
+  RemoteWorkspacePatchResult,
+  RemoteWorkspaceSnapshot
+} from '../shared/remote-workspace-types'
 import type {
   Automation,
   AutomationCreateInput,
@@ -618,20 +624,30 @@ export type PreloadApi = {
   export: ExportApi
   gh: {
     viewer: () => Promise<GitHubViewer | null>
-    repoSlug: (args: { repoPath: string }) => Promise<{ owner: string; repo: string } | null>
+    repoSlug: (args: {
+      repoPath: string
+      repoId?: string
+    }) => Promise<{ owner: string; repo: string } | null>
     prForBranch: (args: {
       repoPath: string
+      repoId?: string
       branch: string
       linkedPRNumber?: number | null
     }) => Promise<PRInfo | null>
-    issue: (args: { repoPath: string; number: number }) => Promise<IssueInfo | null>
+    issue: (args: {
+      repoPath: string
+      repoId?: string
+      number: number
+    }) => Promise<IssueInfo | null>
     workItem: (args: {
       repoPath: string
+      repoId?: string
       number: number
       type?: 'issue' | 'pr'
     }) => Promise<Omit<GitHubWorkItem, 'repoId'> | null>
     workItemByOwnerRepo: (args: {
       repoPath: string
+      repoId?: string
       owner: string
       repo: string
       number: number
@@ -639,11 +655,13 @@ export type PreloadApi = {
     }) => Promise<Omit<GitHubWorkItem, 'repoId'> | null>
     workItemDetails: (args: {
       repoPath: string
+      repoId?: string
       number: number
       type?: 'issue' | 'pr'
     }) => Promise<GitHubWorkItemDetails | null>
     prFileContents: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       path: string
       oldPath?: string
@@ -651,48 +669,65 @@ export type PreloadApi = {
       headSha: string
       baseSha: string
     }) => Promise<GitHubPRFileContents>
-    listIssues: (args: { repoPath: string; limit?: number }) => Promise<IssueInfo[]>
+    listIssues: (args: {
+      repoPath: string
+      repoId?: string
+      limit?: number
+    }) => Promise<IssueInfo[]>
     createIssue: (args: {
       repoPath: string
+      repoId?: string
       title: string
       body: string
     }) => Promise<{ ok: true; number: number; url: string } | { ok: false; error: string }>
-    countWorkItems: (args: { repoPath: string; query?: string }) => Promise<number>
+    countWorkItems: (args: { repoPath: string; repoId?: string; query?: string }) => Promise<number>
     listWorkItems: (args: {
       repoPath: string
+      repoId?: string
       limit?: number
       query?: string
       before?: string
     }) => Promise<ListWorkItemsResult<Omit<GitHubWorkItem, 'repoId'>>>
     prChecks: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       headSha?: string
       noCache?: boolean
     }) => Promise<PRCheckDetail[]>
     prComments: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       noCache?: boolean
     }) => Promise<PRComment[]>
     resolveReviewThread: (args: {
       repoPath: string
+      repoId?: string
       threadId: string
       resolve: boolean
     }) => Promise<boolean>
-    updatePRTitle: (args: { repoPath: string; prNumber: number; title: string }) => Promise<boolean>
+    updatePRTitle: (args: {
+      repoPath: string
+      repoId?: string
+      prNumber: number
+      title: string
+    }) => Promise<boolean>
     mergePR: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       method?: 'merge' | 'squash' | 'rebase'
     }) => Promise<{ ok: true } | { ok: false; error: string }>
     updateIssue: (args: {
       repoPath: string
+      repoId?: string
       number: number
       updates: GitHubIssueUpdate
     }) => Promise<{ ok: true } | { ok: false; error: string }>
     addIssueComment: (args: {
       repoPath: string
+      repoId?: string
       number: number
       body: string
       /** Why: GitHub stores PR conversation comments under `/issues/N/comments`
@@ -704,6 +739,7 @@ export type PreloadApi = {
     }) => Promise<GitHubCommentResult>
     addPRReviewCommentReply: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       commentId: number
       body: string
@@ -711,16 +747,26 @@ export type PreloadApi = {
       path?: string
       line?: number
     }) => Promise<GitHubCommentResult>
-    addPRReviewComment: (args: GitHubPRReviewCommentInput) => Promise<GitHubCommentResult>
-    listLabels: (args: { repoPath: string }) => Promise<string[]>
-    listAssignableUsers: (args: { repoPath: string }) => Promise<GitHubAssignableUser[]>
+    addPRReviewComment: (
+      args: GitHubPRReviewCommentInput & { repoId?: string }
+    ) => Promise<GitHubCommentResult>
+    listLabels: (args: { repoPath: string; repoId?: string }) => Promise<string[]>
+    listAssignableUsers: (args: {
+      repoPath: string
+      repoId?: string
+    }) => Promise<GitHubAssignableUser[]>
     /**
      * Subscribe to local-mutation broadcasts. Used by the work-item-drawer
      * cache to invalidate entries across windows after a successful mutation.
      * Returns an unsubscribe function.
      */
     onWorkItemMutated: (
-      callback: (payload: { repoPath: string; type: 'issue' | 'pr'; number: number }) => void
+      callback: (payload: {
+        repoPath: string
+        repoId?: string
+        type: 'issue' | 'pr'
+        number: number
+      }) => void
     ) => () => void
     checkOrcaStarred: () => Promise<boolean | null>
     starOrca: () => Promise<boolean>
@@ -1052,6 +1098,19 @@ export type PreloadApi = {
     set: (args: WorkspaceSessionState) => Promise<void>
     setSync: (args: WorkspaceSessionState) => void
   }
+  remoteWorkspace: {
+    get: (args: { targetId: string }) => Promise<RemoteWorkspaceSnapshot | null>
+    setForConnectedTargets: (args: {
+      session: WorkspaceSessionState
+      hydratedTargetIds?: string[]
+    }) => Promise<{ targetId: string; result: RemoteWorkspacePatchResult }[]>
+    listEnabledConnectedTargets: () => Promise<string[]>
+    listConnectedClients: (args?: {
+      targetIds?: string[]
+    }) => Promise<{ targetId: string; clients: RemoteWorkspaceConnectedClient[] }[]>
+    clientId: () => Promise<string>
+    onChanged: (callback: (event: RemoteWorkspaceChangedEvent) => void) => () => void
+  }
   updater: {
     getVersion: () => Promise<string>
     getStatus: () => Promise<UpdateStatus>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index f007c51d429..3eb695a9d2c 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -683,26 +683,29 @@ const api = {
   gh: {
     viewer: (): Promise<unknown> => ipcRenderer.invoke('gh:viewer'),
 
-    repoSlug: (args: { repoPath: string }): Promise<unknown> =>
+    repoSlug: (args: { repoPath: string; repoId?: string }): Promise<unknown> =>
       ipcRenderer.invoke('gh:repoSlug', args),
 
     prForBranch: (args: {
       repoPath: string
+      repoId?: string
       branch: string
       linkedPRNumber?: number | null
     }): Promise<unknown> => ipcRenderer.invoke('gh:prForBranch', args),
 
-    issue: (args: { repoPath: string; number: number }): Promise<unknown> =>
+    issue: (args: { repoPath: string; repoId?: string; number: number }): Promise<unknown> =>
       ipcRenderer.invoke('gh:issue', args),
 
     workItem: (args: {
       repoPath: string
+      repoId?: string
       number: number
       type?: 'issue' | 'pr'
     }): Promise<unknown> => ipcRenderer.invoke('gh:workItem', args),
 
     workItemByOwnerRepo: (args: {
       repoPath: string
+      repoId?: string
       owner: string
       repo: string
       number: number
@@ -711,12 +714,14 @@ const api = {
 
     workItemDetails: (args: {
       repoPath: string
+      repoId?: string
       number: number
       type?: 'issue' | 'pr'
     }): Promise<unknown> => ipcRenderer.invoke('gh:workItemDetails', args),
 
     prFileContents: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       path: string
       oldPath?: string
@@ -725,21 +730,26 @@ const api = {
       baseSha: string
     }): Promise<unknown> => ipcRenderer.invoke('gh:prFileContents', args),
 
-    listIssues: (args: { repoPath: string; limit?: number }): Promise<unknown[]> =>
+    listIssues: (args: { repoPath: string; repoId?: string; limit?: number }): Promise<unknown[]> =>
       ipcRenderer.invoke('gh:listIssues', args),
 
     createIssue: (args: {
       repoPath: string
+      repoId?: string
       title: string
       body: string
     }): Promise<{ ok: true; number: number; url: string } | { ok: false; error: string }> =>
       ipcRenderer.invoke('gh:createIssue', args),
 
-    countWorkItems: (args: { repoPath: string; query?: string }): Promise<number> =>
-      ipcRenderer.invoke('gh:countWorkItems', args),
+    countWorkItems: (args: {
+      repoPath: string
+      repoId?: string
+      query?: string
+    }): Promise<number> => ipcRenderer.invoke('gh:countWorkItems', args),
 
     listWorkItems: (args: {
       repoPath: string
+      repoId?: string
       limit?: number
       query?: string
       before?: string
@@ -748,6 +758,7 @@ const api = {
 
     prChecks: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       headSha?: string
       noCache?: boolean
@@ -755,24 +766,28 @@ const api = {
 
     prComments: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       noCache?: boolean
     }): Promise<unknown[]> => ipcRenderer.invoke('gh:prComments', args),
 
     resolveReviewThread: (args: {
       repoPath: string
+      repoId?: string
       threadId: string
       resolve: boolean
     }): Promise<boolean> => ipcRenderer.invoke('gh:resolveReviewThread', args),
 
     updatePRTitle: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       title: string
     }): Promise<boolean> => ipcRenderer.invoke('gh:updatePRTitle', args),
 
     mergePR: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       method?: 'merge' | 'squash' | 'rebase'
     }): Promise<{ ok: true } | { ok: false; error: string }> =>
@@ -780,6 +795,7 @@ const api = {
 
     updateIssue: (args: {
       repoPath: string
+      repoId?: string
       number: number
       updates: unknown
     }): Promise<{ ok: true } | { ok: false; error: string }> =>
@@ -787,6 +803,7 @@ const api = {
 
     addIssueComment: (args: {
       repoPath: string
+      repoId?: string
       number: number
       body: string
       type?: 'issue' | 'pr'
@@ -794,6 +811,7 @@ const api = {
 
     addPRReviewCommentReply: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       commentId: number
       body: string
@@ -804,6 +822,7 @@ const api = {
 
     addPRReviewComment: (args: {
       repoPath: string
+      repoId?: string
       prNumber: number
       commitId: string
       path: string
@@ -812,22 +831,29 @@ const api = {
       body: string
     }): Promise<GitHubCommentResult> => ipcRenderer.invoke('gh:addPRReviewComment', args),
 
-    listLabels: (args: { repoPath: string }): Promise<string[]> =>
+    listLabels: (args: { repoPath: string; repoId?: string }): Promise<string[]> =>
       ipcRenderer.invoke('gh:listLabels', args),
 
-    listAssignableUsers: (args: { repoPath: string }): Promise<GitHubAssignableUser[]> =>
-      ipcRenderer.invoke('gh:listAssignableUsers', args),
+    listAssignableUsers: (args: {
+      repoPath: string
+      repoId?: string
+    }): Promise<GitHubAssignableUser[]> => ipcRenderer.invoke('gh:listAssignableUsers', args),
 
     // Why: every renderer subscribes to local mutation broadcasts so each
     // window's work-item-details cache invalidates the affected entry. The
     // event fires after a successful mutation in any window — see
     // src/main/ipc/github.ts broadcastWorkItemMutated.
     onWorkItemMutated: (
-      callback: (payload: { repoPath: string; type: 'issue' | 'pr'; number: number }) => void
+      callback: (payload: {
+        repoPath: string
+        repoId?: string
+        type: 'issue' | 'pr'
+        number: number
+      }) => void
     ): (() => void) => {
       const listener = (
         _event: Electron.IpcRendererEvent,
-        payload: { repoPath: string; type: 'issue' | 'pr'; number: number }
+        payload: { repoPath: string; repoId?: string; type: 'issue' | 'pr'; number: number }
       ): void => callback(payload)
       ipcRenderer.on('gh:workItemMutated', listener)
       return () => ipcRenderer.removeListener('gh:workItemMutated', listener)
@@ -1559,6 +1585,25 @@ const api = {
     }
   },
 
+  remoteWorkspace: {
+    get: (args: { targetId: string }): Promise<unknown> =>
+      ipcRenderer.invoke('remoteWorkspace:get', args),
+    setForConnectedTargets: (args: {
+      session: unknown
+      hydratedTargetIds?: string[]
+    }): Promise<unknown> => ipcRenderer.invoke('remoteWorkspace:setForConnectedTargets', args),
+    listEnabledConnectedTargets: (): Promise<string[]> =>
+      ipcRenderer.invoke('remoteWorkspace:listEnabledConnectedTargets'),
+    listConnectedClients: (args?: { targetIds?: string[] }): Promise<unknown> =>
+      ipcRenderer.invoke('remoteWorkspace:listConnectedClients', args),
+    clientId: (): Promise<string> => ipcRenderer.invoke('remoteWorkspace:clientId'),
+    onChanged: (callback: (event: unknown) => void): (() => void) => {
+      const listener = (_event: Electron.IpcRendererEvent, data: unknown) => callback(data)
+      ipcRenderer.on('remoteWorkspace:changed', listener)
+      return () => ipcRenderer.removeListener('remoteWorkspace:changed', listener)
+    }
+  },
+
   updater: {
     getStatus: (): Promise<unknown> => ipcRenderer.invoke('updater:getStatus'),
     getVersion: (): Promise<string> => ipcRenderer.invoke('updater:getVersion'),
diff --git a/src/relay/agent-exec-handler.test.ts b/src/relay/agent-exec-handler.test.ts
index 18a9a5966c9..da402b7d193 100644
--- a/src/relay/agent-exec-handler.test.ts
+++ b/src/relay/agent-exec-handler.test.ts
@@ -5,7 +5,7 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type * as ChildProcess from 'child_process'
-import type { MethodHandler } from './dispatcher'
+import type { MethodHandler, RequestContext } from './dispatcher'
 import { AgentExecHandler } from './agent-exec-handler'
 
 vi.mock('child_process', async (importOriginal) => {
@@ -58,6 +58,10 @@ function createHandlers(): Map<string, MethodHandler> {
   return handlers
 }
 
+function requestContext(clientId = 1): RequestContext {
+  return { clientId, isStale: () => false }
+}
+
 describe('AgentExecHandler', () => {
   beforeEach(() => {
     spawnMock.mockReset()
@@ -77,7 +81,7 @@ describe('AgentExecHandler', () => {
         stdin: 'PROMPT',
         timeoutMs: 5_000
       },
-      { isStale: () => false }
+      requestContext()
     )
 
     child.stdout.emit('data', Buffer.from('message'))
@@ -117,7 +121,7 @@ describe('AgentExecHandler', () => {
           PATH: '/managed/bin'
         }
       },
-      { isStale: () => false }
+      requestContext()
     )
 
     child.emit('close', 0)
@@ -159,7 +163,7 @@ describe('AgentExecHandler', () => {
             timeoutMs: 5_000,
             env: { PATH: tempDir }
           },
-          { isStale: () => false }
+          requestContext()
         )
 
         child.emit('close', 0)
@@ -201,7 +205,7 @@ describe('AgentExecHandler', () => {
           stdin: null,
           timeoutMs: 5_000
         },
-        { isStale: () => false }
+        requestContext()
       )
 
       expect(result).toEqual({
@@ -228,11 +232,11 @@ describe('AgentExecHandler', () => {
         stdin: null,
         timeoutMs: 5_000
       },
-      { isStale: () => false }
+      requestContext()
     )
 
     await expect(
-      handlers.get('agent.cancelExec')!({ cwd: '/repo' }, { isStale: () => false })
+      handlers.get('agent.cancelExec')!({ cwd: '/repo' }, requestContext())
     ).resolves.toEqual({ canceled: true })
 
     if (process.platform === 'win32') {
@@ -253,7 +257,7 @@ describe('AgentExecHandler', () => {
     const handlers = createHandlers()
 
     await expect(
-      handlers.get('agent.cancelExec')!({ cwd: '/repo' }, { isStale: () => false })
+      handlers.get('agent.cancelExec')!({ cwd: '/repo' }, requestContext())
     ).resolves.toEqual({ canceled: false })
   })
 })
diff --git a/src/relay/client-request-aborts.ts b/src/relay/client-request-aborts.ts
new file mode 100644
index 00000000000..636be796cd2
--- /dev/null
+++ b/src/relay/client-request-aborts.ts
@@ -0,0 +1,33 @@
+export class ClientRequestAborts {
+  private readonly controllers = new Map<string, AbortController>()
+
+  create(clientId: number, requestId: number): { key: string; controller: AbortController } {
+    const key = this.key(clientId, requestId)
+    const controller = new AbortController()
+    this.controllers.set(key, controller)
+    return { key, controller }
+  }
+
+  get(clientId: number, requestId: number): AbortController | undefined {
+    return this.controllers.get(this.key(clientId, requestId))
+  }
+
+  delete(key: string): void {
+    this.controllers.delete(key)
+  }
+
+  abortClient(clientId: number): void {
+    const prefix = `${clientId}:`
+    for (const [key, controller] of this.controllers) {
+      if (!key.startsWith(prefix)) {
+        continue
+      }
+      controller.abort()
+      this.controllers.delete(key)
+    }
+  }
+
+  private key(clientId: number, requestId: number): string {
+    return `${clientId}:${requestId}`
+  }
+}
diff --git a/src/relay/dispatcher.test.ts b/src/relay/dispatcher.test.ts
index 53733dcabd2..3e76c7055ea 100644
--- a/src/relay/dispatcher.test.ts
+++ b/src/relay/dispatcher.test.ts
@@ -153,7 +153,10 @@ describe('RelayDispatcher', () => {
     }
     dispatcher.feed(encodeJsonRpcFrame(notif, 1, 0))
 
-    expect(handler).toHaveBeenCalledWith({ x: 1 })
+    expect(handler).toHaveBeenCalledWith(
+      { x: 1 },
+      expect.objectContaining({ clientId: 1, isStale: expect.any(Function) })
+    )
   })
 
   it('sends notifications via notify()', () => {
@@ -178,6 +181,43 @@ describe('RelayDispatcher', () => {
     expect(msg.params).toEqual({ data: 'hello' })
   })
 
+  it('broadcasts notifications to attached socket clients with independent frame state', () => {
+    const socketWritten: Buffer[] = []
+    const clientId = dispatcher.attachClient((data) => {
+      socketWritten.push(Buffer.from(data))
+    })
+
+    dispatcher.notify('workspace.changed', { revision: 1 })
+
+    expect(written).toHaveLength(1)
+    expect(socketWritten).toHaveLength(1)
+    expect(decodeFirstFrame(written[0]).id).toBe(1)
+    expect(decodeFirstFrame(socketWritten[0]).id).toBe(1)
+
+    dispatcher.detachClient(clientId)
+    dispatcher.notify('workspace.changed', { revision: 2 })
+
+    expect(written).toHaveLength(2)
+    expect(socketWritten).toHaveLength(1)
+  })
+
+  it('isolates failed socket-client writes from other clients', () => {
+    const goodSocketWritten: Buffer[] = []
+    const failingClientId = dispatcher.attachClient(() => {
+      throw new Error('socket closed')
+    })
+    dispatcher.attachClient((data) => {
+      goodSocketWritten.push(Buffer.from(data))
+    })
+
+    dispatcher.notify('workspace.changed', { revision: 1 })
+    dispatcher.notify('workspace.changed', { revision: 2 })
+
+    expect(written).toHaveLength(2)
+    expect(goodSocketWritten).toHaveLength(2)
+    dispatcher.detachClient(failingClientId)
+  })
+
   it('tracks highest received seq in ack field', async () => {
     const handler = vi.fn().mockResolvedValue('ok')
     dispatcher.onRequest('ping', handler)
@@ -269,4 +309,13 @@ describe('RelayDispatcher', () => {
     resolveHandler()
     await vi.advanceTimersByTimeAsync(0)
   })
+
+  it('notifies listeners when the primary client is invalidated', () => {
+    const listener = vi.fn()
+    dispatcher.onClientDetached(listener)
+
+    dispatcher.invalidateClient()
+
+    expect(listener).toHaveBeenCalledWith(1)
+  })
 })
diff --git a/src/relay/dispatcher.ts b/src/relay/dispatcher.ts
index 1cd2cce034b..b1ce857c2b8 100644
--- a/src/relay/dispatcher.ts
+++ b/src/relay/dispatcher.ts
@@ -10,8 +10,10 @@ import {
   type JsonRpcNotification,
   type JsonRpcResponse
 } from './protocol'
+import { ClientRequestAborts } from './client-request-aborts'
 
 export type RequestContext = {
+  clientId: number
   isStale: () => boolean
   signal?: AbortSignal
 }
@@ -21,26 +23,32 @@ export type MethodHandler = (
   context: RequestContext
 ) => Promise<unknown>
 
-export type NotificationHandler = (params: Record<string, unknown>) => void
+export type NotificationHandler = (params: Record<string, unknown>, context: RequestContext) => void
+
+type RelayClient = {
+  id: number
+  decoder: FrameDecoder
+  write: (data: Buffer) => void
+  nextOutgoingSeq: number
+  highestReceivedSeq: number
+  generation: number
+  closed: boolean
+}
 
 export class RelayDispatcher {
-  private decoder: FrameDecoder
-  private write: (data: Buffer) => void
+  private readonly primaryClient: RelayClient
+  private readonly clients = new Map<number, RelayClient>()
   private requestHandlers = new Map<string, MethodHandler>()
   private notificationHandlers = new Map<string, NotificationHandler>()
-  private requestAbortControllers = new Map<number, AbortController>()
-  private nextOutgoingSeq = 1
-  private highestReceivedSeq = 0
+  private readonly requestAborts = new ClientRequestAborts()
+  private clientDetachListeners = new Set<(clientId: number) => void>()
   private keepaliveTimer: ReturnType<typeof setInterval> | null = null
   private disposed = false
-  // Why: incremented on every setWrite() call so async request handlers
-  // that started before a client swap can detect that their response
-  // would go to a different client and discard it instead of misrouting.
-  private generation = 0
+  private nextClientId = 1
 
   constructor(write: (data: Buffer) => void) {
-    this.write = write
-    this.decoder = new FrameDecoder((frame) => this.handleFrame(frame))
+    this.primaryClient = this.createClient(write)
+    this.clients.set(this.primaryClient.id, this.primaryClient)
     this.startKeepalive()
   }
 
@@ -53,23 +61,52 @@ export class RelayDispatcher {
   // client's SshChannelMultiplexer starts at seq=1. Without resetting, the
   // relay's highestReceivedSeq stays at the old client's last value, so it
   // never acks the new client's frames until the new client's seq catches
-  // up — causing the client's unacked-timeout checker to accumulate stale
+  // up - causing the client's unacked-timeout checker to accumulate stale
   // timestamps that could eventually fire a false connection-dead signal.
   setWrite(write: (data: Buffer) => void): void {
-    this.abortActiveRequests()
-    this.write = write
-    this.nextOutgoingSeq = 1
-    this.highestReceivedSeq = 0
-    this.decoder.reset()
-    this.generation++
+    this.requestAborts.abortClient(this.primaryClient.id)
+    this.primaryClient.write = write
+    this.primaryClient.closed = false
+    this.resetClient(this.primaryClient)
   }
 
   // Why: in-flight mutating requests must become stale when the active client
   // disconnects even if no replacement has connected yet. Otherwise a late
   // pty.spawn/fs.watch completion can create remote state nobody can own.
   invalidateClient(): void {
-    this.abortActiveRequests()
-    this.generation++
+    this.requestAborts.abortClient(this.primaryClient.id)
+    this.primaryClient.generation++
+    this.primaryClient.closed = true
+    this.notifyClientDetached(this.primaryClient.id)
+  }
+
+  // Why: synced remote workspaces can have more than one Orca client attached
+  // to the same relay. Frame sequence numbers and JSON-RPC request ids are per
+  // SSH channel, so each socket client needs independent protocol state.
+  attachClient(write: (data: Buffer) => void): number {
+    const client = this.createClient(write)
+    this.clients.set(client.id, client)
+    return client.id
+  }
+
+  detachClient(clientId: number): void {
+    const client = this.clients.get(clientId)
+    if (!client || client === this.primaryClient) {
+      return
+    }
+    this.requestAborts.abortClient(clientId)
+    client.generation++
+    client.closed = true
+    this.clients.delete(clientId)
+    this.notifyClientDetached(clientId)
+  }
+
+  feedClient(clientId: number, data: Buffer): void {
+    const client = this.clients.get(clientId)
+    if (!client) {
+      return
+    }
+    this.feedForClient(client, data)
   }
 
   onRequest(method: string, handler: MethodHandler): void {
@@ -80,19 +117,21 @@ export class RelayDispatcher {
     this.notificationHandlers.set(method, handler)
   }
 
-  private abortActiveRequests(): void {
-    for (const controller of this.requestAbortControllers.values()) {
-      controller.abort()
-    }
-    this.requestAbortControllers.clear()
+  onClientDetached(listener: (clientId: number) => void): () => void {
+    this.clientDetachListeners.add(listener)
+    return () => this.clientDetachListeners.delete(listener)
   }
 
   feed(data: Buffer): void {
+    this.feedForClient(this.primaryClient, data)
+  }
+
+  private feedForClient(client: RelayClient, data: Buffer): void {
     if (this.disposed) {
       return
     }
     try {
-      this.decoder.feed(data)
+      client.decoder.feed(data)
     } catch (err) {
       process.stderr.write(
         `[relay] Protocol error: ${err instanceof Error ? err.message : String(err)}\n`
@@ -109,7 +148,9 @@ export class RelayDispatcher {
       method,
       ...(params !== undefined ? { params } : {})
     }
-    this.sendFrame(msg)
+    for (const client of this.clients.values()) {
+      this.sendFrame(client, msg)
+    }
   }
 
   dispose(): void {
@@ -123,9 +164,31 @@ export class RelayDispatcher {
     }
   }
 
-  private handleFrame(frame: DecodedFrame): void {
-    if (frame.id > this.highestReceivedSeq) {
-      this.highestReceivedSeq = frame.id
+  private createClient(write: (data: Buffer) => void): RelayClient {
+    const id = this.nextClientId++
+    const client: RelayClient = {
+      id,
+      decoder: new FrameDecoder((frame) => this.handleFrame(client, frame)),
+      write,
+      nextOutgoingSeq: 1,
+      highestReceivedSeq: 0,
+      generation: 0,
+      closed: false
+    }
+    return client
+  }
+
+  private resetClient(client: RelayClient): void {
+    client.nextOutgoingSeq = 1
+    client.highestReceivedSeq = 0
+    client.decoder.reset()
+    client.generation++
+    client.closed = false
+  }
+
+  private handleFrame(client: RelayClient, frame: DecodedFrame): void {
+    if (frame.id > client.highestReceivedSeq) {
+      client.highestReceivedSeq = frame.id
     }
 
     if (frame.type === MessageType.KeepAlive) {
@@ -135,7 +198,7 @@ export class RelayDispatcher {
     if (frame.type === MessageType.Regular) {
       try {
         const msg = parseJsonRpcMessage(frame.payload)
-        this.handleMessage(msg)
+        this.handleMessage(client, msg)
       } catch (err) {
         process.stderr.write(
           `[relay] Parse error: ${err instanceof Error ? err.message : String(err)}\n`
@@ -144,68 +207,78 @@ export class RelayDispatcher {
     }
   }
 
-  private handleMessage(msg: JsonRpcRequest | JsonRpcNotification | JsonRpcResponse): void {
+  private handleMessage(
+    client: RelayClient,
+    msg: JsonRpcRequest | JsonRpcNotification | JsonRpcResponse
+  ): void {
     if ('id' in msg && 'method' in msg) {
-      void this.handleRequest(msg as JsonRpcRequest)
+      void this.handleRequest(client, msg as JsonRpcRequest)
     } else if ('method' in msg && !('id' in msg)) {
-      this.handleNotification(msg as JsonRpcNotification)
+      this.handleNotification(client, msg as JsonRpcNotification)
     }
   }
 
-  private async handleRequest(req: JsonRpcRequest): Promise<void> {
+  private async handleRequest(client: RelayClient, req: JsonRpcRequest): Promise<void> {
     const handler = this.requestHandlers.get(req.method)
     if (!handler) {
-      this.sendResponse(req.id, undefined, {
+      this.sendResponse(client, req.id, undefined, {
         code: -32601,
         message: `Method not found: ${req.method}`
       })
       return
     }
 
-    // Why: capture generation before the async handler runs. If a new
-    // client connects (setWrite increments generation) while this handler
-    // is in flight, the response belongs to the old client's request ID
-    // space. Sending it would misroute — the new client may have issued
-    // its own request with the same JSON-RPC id.
-    const gen = this.generation
-    const abortController = new AbortController()
-    this.requestAbortControllers.set(req.id, abortController)
+    // Why: capture this client's generation before the async handler runs.
+    // If that client disconnects while the handler is in flight, the response
+    // belongs to a dead request-id space and mutating work may need cleanup.
+    const gen = client.generation
+    const { key: abortKey, controller: abortController } = this.requestAborts.create(
+      client.id,
+      req.id
+    )
     const context: RequestContext = {
-      isStale: () => this.generation !== gen || abortController.signal.aborted,
+      clientId: client.id,
+      isStale: () =>
+        client.generation !== gen || !this.clients.has(client.id) || abortController.signal.aborted,
       signal: abortController.signal
     }
     try {
       const result = await handler(req.params ?? {}, context)
-      if (this.generation !== gen || abortController.signal.aborted) {
+      if (context.isStale()) {
         return
       }
-      this.sendResponse(req.id, result)
+      this.sendResponse(client, req.id, result)
     } catch (err) {
-      if (this.generation !== gen || abortController.signal.aborted) {
+      if (context.isStale()) {
         return
       }
       const message = err instanceof Error ? err.message : String(err)
       const code = (err as { code?: number }).code ?? -32000
-      this.sendResponse(req.id, undefined, { code, message })
+      this.sendResponse(client, req.id, undefined, { code, message })
     } finally {
-      this.requestAbortControllers.delete(req.id)
+      this.requestAborts.delete(abortKey)
     }
   }
 
-  private handleNotification(notif: JsonRpcNotification): void {
+  private handleNotification(client: RelayClient, notif: JsonRpcNotification): void {
     if (notif.method === 'rpc.cancel') {
       const id = Number((notif.params ?? {}).id)
-      const controller = this.requestAbortControllers.get(id)
+      const controller = this.requestAborts.get(client.id, id)
       controller?.abort()
       return
     }
     const handler = this.notificationHandlers.get(notif.method)
     if (handler) {
-      handler(notif.params ?? {})
+      const gen = client.generation
+      handler(notif.params ?? {}, {
+        clientId: client.id,
+        isStale: () => client.generation !== gen || !this.clients.has(client.id)
+      })
     }
   }
 
   private sendResponse(
+    client: RelayClient,
     id: number,
     result?: unknown,
     error?: { code: number; message: string; data?: unknown }
@@ -215,16 +288,19 @@ export class RelayDispatcher {
       id,
       ...(error ? { error } : { result: result ?? null })
     }
-    this.sendFrame(msg)
+    this.sendFrame(client, msg)
   }
 
-  private sendFrame(msg: JsonRpcRequest | JsonRpcResponse | JsonRpcNotification): void {
-    if (this.disposed) {
+  private sendFrame(
+    client: RelayClient,
+    msg: JsonRpcRequest | JsonRpcResponse | JsonRpcNotification
+  ): void {
+    if (this.disposed || client.closed) {
       return
     }
-    const seq = this.nextOutgoingSeq++
-    const frame = encodeJsonRpcFrame(msg, seq, this.highestReceivedSeq)
-    this.write(frame)
+    const seq = client.nextOutgoingSeq++
+    const frame = encodeJsonRpcFrame(msg, seq, client.highestReceivedSeq)
+    this.writeFrame(client, frame)
   }
 
   private startKeepalive(): void {
@@ -232,13 +308,46 @@ export class RelayDispatcher {
       if (this.disposed) {
         return
       }
-      const seq = this.nextOutgoingSeq++
-      const frame = encodeKeepAliveFrame(seq, this.highestReceivedSeq)
-      this.write(frame)
+      for (const client of this.clients.values()) {
+        if (client.closed) {
+          continue
+        }
+        const seq = client.nextOutgoingSeq++
+        const frame = encodeKeepAliveFrame(seq, client.highestReceivedSeq)
+        this.writeFrame(client, frame)
+      }
     }, KEEPALIVE_SEND_MS)
     // Why: without unref, the keepalive interval keeps the event loop alive
     // even when the relay should be winding down (e.g. after stdin ends and
     // all PTYs have exited). unref lets the process exit naturally.
     this.keepaliveTimer.unref()
   }
+
+  private writeFrame(client: RelayClient, frame: Buffer): void {
+    try {
+      client.write(frame)
+    } catch (err) {
+      client.closed = true
+      client.generation++
+      if (client !== this.primaryClient) {
+        this.clients.delete(client.id)
+        this.notifyClientDetached(client.id)
+      }
+      process.stderr.write(
+        `[relay] Client write failed: ${err instanceof Error ? err.message : String(err)}\n`
+      )
+    }
+  }
+
+  private notifyClientDetached(clientId: number): void {
+    for (const listener of this.clientDetachListeners) {
+      try {
+        listener(clientId)
+      } catch (err) {
+        process.stderr.write(
+          `[relay] Client detach listener failed: ${err instanceof Error ? err.message : String(err)}\n`
+        )
+      }
+    }
+  }
 }
diff --git a/src/relay/fs-handler.test.ts b/src/relay/fs-handler.test.ts
index d17df8c44a6..f3ad1ec250f 100644
--- a/src/relay/fs-handler.test.ts
+++ b/src/relay/fs-handler.test.ts
@@ -20,9 +20,19 @@ vi.mock('@parcel/watcher', () => ({
 function createMockDispatcher() {
   const requestHandlers = new Map<
     string,
-    (params: Record<string, unknown>, context?: { isStale: () => boolean }) => Promise<unknown>
+    (
+      params: Record<string, unknown>,
+      context?: { clientId: number; isStale: () => boolean }
+    ) => Promise<unknown>
   >()
-  const notificationHandlers = new Map<string, (params: Record<string, unknown>) => void>()
+  const notificationHandlers = new Map<
+    string,
+    (
+      params: Record<string, unknown>,
+      context?: { clientId: number; isStale: () => boolean }
+    ) => void
+  >()
+  const detachListeners = new Set<(clientId: number) => void>()
   const notifications: { method: string; params?: Record<string, unknown> }[] = []
 
   return {
@@ -31,38 +41,62 @@ function createMockDispatcher() {
         method: string,
         handler: (
           params: Record<string, unknown>,
-          context?: { isStale: () => boolean }
+          context?: { clientId: number; isStale: () => boolean }
         ) => Promise<unknown>
       ) => {
         requestHandlers.set(method, handler)
       }
     ),
-    onNotification: vi.fn((method: string, handler: (params: Record<string, unknown>) => void) => {
-      notificationHandlers.set(method, handler)
-    }),
+    onNotification: vi.fn(
+      (
+        method: string,
+        handler: (
+          params: Record<string, unknown>,
+          context?: { clientId: number; isStale: () => boolean }
+        ) => void
+      ) => {
+        notificationHandlers.set(method, handler)
+      }
+    ),
     notify: vi.fn((method: string, params?: Record<string, unknown>) => {
       notifications.push({ method, params })
     }),
+    onClientDetached: vi.fn((listener: (clientId: number) => void) => {
+      detachListeners.add(listener)
+      return () => detachListeners.delete(listener)
+    }),
     _requestHandlers: requestHandlers,
     _notificationHandlers: notificationHandlers,
     _notifications: notifications,
     async callRequest(
       method: string,
       params: Record<string, unknown> = {},
-      context?: { isStale: () => boolean }
+      context?: { clientId?: number; isStale: () => boolean }
     ) {
       const handler = requestHandlers.get(method)
       if (!handler) {
         throw new Error(`No handler for ${method}`)
       }
-      return handler(params, context)
+      return handler(params, {
+        clientId: context?.clientId ?? 1,
+        isStale: context?.isStale ?? (() => false)
+      })
     },
-    callNotification(method: string, params: Record<string, unknown> = {}) {
+    callNotification(
+      method: string,
+      params: Record<string, unknown> = {},
+      context?: { clientId: number; isStale: () => boolean }
+    ) {
       const handler = notificationHandlers.get(method)
       if (!handler) {
         throw new Error(`No handler for ${method}`)
       }
-      handler(params)
+      handler(params, context ?? { clientId: 1, isStale: () => false })
+    },
+    detachClient(clientId: number) {
+      for (const listener of detachListeners) {
+        listener(clientId)
+      }
     }
   }
 }
@@ -416,4 +450,108 @@ describe('FsHandler', () => {
     expect(firstUnsubscribe).toHaveBeenCalled()
     expect(replacementUnsubscribe).not.toHaveBeenCalled()
   })
+
+  it('removes stale watches for any root before enforcing the watch cap', async () => {
+    const staleUnsubscribe = vi.fn()
+    mockSubscribe
+      .mockResolvedValueOnce({ unsubscribe: staleUnsubscribe })
+      .mockResolvedValue({ unsubscribe: vi.fn() })
+
+    let stale = false
+    await dispatcher.callRequest('fs.watch', { rootPath: path.join(tmpDir, 'stale-root') }, {
+      isStale: () => stale
+    })
+    for (let index = 0; index < 19; index += 1) {
+      await dispatcher.callRequest('fs.watch', {
+        rootPath: path.join(tmpDir, `watched-${index}`)
+      })
+    }
+
+    stale = true
+
+    await expect(
+      dispatcher.callRequest('fs.watch', { rootPath: path.join(tmpDir, 'new-root') })
+    ).resolves.toBeUndefined()
+    expect(staleUnsubscribe).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps a shared watch alive until every client unwatches it', async () => {
+    const unsubscribe = vi.fn()
+    mockSubscribe.mockResolvedValue({ unsubscribe })
+
+    await dispatcher.callRequest('fs.watch', { rootPath: tmpDir }, { isStale: () => false })
+    await dispatcher.callRequest(
+      'fs.watch',
+      { rootPath: tmpDir },
+      {
+        clientId: 2,
+        isStale: () => false
+      }
+    )
+
+    dispatcher.callNotification(
+      'fs.unwatch',
+      { rootPath: tmpDir },
+      {
+        clientId: 1,
+        isStale: () => false
+      }
+    )
+    expect(unsubscribe).not.toHaveBeenCalled()
+
+    dispatcher.callNotification(
+      'fs.unwatch',
+      { rootPath: tmpDir },
+      {
+        clientId: 2,
+        isStale: () => false
+      }
+    )
+    expect(unsubscribe).toHaveBeenCalledTimes(1)
+  })
+
+  it('allows a shared watch attach even when the root watch cap is full', async () => {
+    mockSubscribe.mockResolvedValue({ unsubscribe: vi.fn() })
+
+    for (let index = 0; index < 20; index += 1) {
+      const dir = path.join(tmpDir, `watched-${index}`)
+      await fs.mkdir(dir)
+      await dispatcher.callRequest(
+        'fs.watch',
+        { rootPath: dir },
+        {
+          clientId: index + 1,
+          isStale: () => false
+        }
+      )
+    }
+
+    await expect(
+      dispatcher.callRequest(
+        'fs.watch',
+        { rootPath: path.join(tmpDir, 'watched-0') },
+        {
+          clientId: 99,
+          isStale: () => false
+        }
+      )
+    ).resolves.toBeUndefined()
+  })
+
+  it('releases a client watch when the dispatcher detaches that client', async () => {
+    const unsubscribe = vi.fn()
+    mockSubscribe.mockResolvedValue({ unsubscribe })
+
+    await dispatcher.callRequest(
+      'fs.watch',
+      { rootPath: tmpDir },
+      {
+        clientId: 7,
+        isStale: () => false
+      }
+    )
+    dispatcher.detachClient(7)
+
+    expect(unsubscribe).toHaveBeenCalledTimes(1)
+  })
 })
diff --git a/src/relay/fs-handler.ts b/src/relay/fs-handler.ts
index a2d6f2aa2a3..57fa9c8f8c6 100644
--- a/src/relay/fs-handler.ts
+++ b/src/relay/fs-handler.ts
@@ -26,7 +26,7 @@ type WatchState = {
   rootPath: string
   unwatchFn: (() => void) | null
   setupPromise: Promise<void> | null
-  isStale: () => boolean
+  clients: Map<number, () => boolean>
 }
 
 async function isDirectoryEntry(
@@ -56,6 +56,7 @@ export class FsHandler {
   constructor(dispatcher: RelayDispatcher, _context: RelayContext) {
     this.dispatcher = dispatcher
     this.registerHandlers()
+    this.dispatcher.onClientDetached?.((clientId) => this.releaseClientWatches(clientId))
   }
 
   private registerHandlers(): void {
@@ -75,7 +76,7 @@ export class FsHandler {
     this.dispatcher.onRequest('fs.listFiles', (p) => this.listFiles(p))
     this.dispatcher.onRequest('fs.workspaceSpaceScan', (p, c) => this.workspaceSpaceScan(p, c))
     this.dispatcher.onRequest('fs.watch', (p, context) => this.watch(p, context))
-    this.dispatcher.onNotification('fs.unwatch', (p) => this.unwatch(p))
+    this.dispatcher.onNotification('fs.unwatch', (p, context) => this.unwatch(p, context))
     this.dispatcher.onNotification('fs.cancelStream', (p) => this.cancelStream(p))
   }
 
@@ -102,12 +103,9 @@ export class FsHandler {
     return readRelayFileContent(filePath)
   }
 
-  private async readFileStream(
-    params: Record<string, unknown>,
-    context?: { isStale: () => boolean }
-  ) {
+  private async readFileStream(params: Record<string, unknown>, context?: RequestContext) {
     const filePath = expandTilde(params.filePath as string)
-    const ctx = context ?? { isStale: () => false }
+    const ctx = context ?? { clientId: 0, isStale: () => false }
     return readRelayFileStreamMetadata(filePath, this.dispatcher, this.streamRegistry, ctx)
   }
 
@@ -289,14 +287,17 @@ export class FsHandler {
   private async watch(params: Record<string, unknown>, context?: RequestContext) {
     const rootPath = expandTilde(params.rootPath as string)
 
+    this.releaseStaleWatches()
+
     const existing = this.watches.get(rootPath)
-    if (existing && !existing.isStale()) {
-      if (existing.setupPromise) {
-        await existing.setupPromise
+    if (existing) {
+      if ([...existing.clients.values()].some((isStale) => !isStale())) {
+        existing.clients.set(context?.clientId ?? 0, context?.isStale ?? (() => false))
+        if (existing.setupPromise) {
+          await existing.setupPromise
+        }
+        return
       }
-      return
-    }
-    if (existing?.isStale()) {
       existing.unwatchFn?.()
       this.watches.delete(rootPath)
     }
@@ -309,7 +310,7 @@ export class FsHandler {
       rootPath,
       unwatchFn: null,
       setupPromise: null,
-      isStale: () => context?.isStale() ?? false
+      clients: new Map([[context?.clientId ?? 0, context?.isStale ?? (() => false)]])
     }
     this.watches.set(rootPath, watchState)
 
@@ -335,11 +336,14 @@ export class FsHandler {
       watchState.unwatchFn = () => {
         void subscription.unsubscribe()
       }
-      if (watchState.isStale() || this.watches.get(rootPath) !== watchState) {
-        // Why: if the client reconnects while watcher setup is in flight, the
-        // response is discarded and no client can later balance it with
-        // fs.unwatch. Tear down only this request's subscription so a newer
-        // replacement watch for the same root is not removed.
+      if (
+        [...watchState.clients.values()].every((isStale) => isStale()) ||
+        this.watches.get(rootPath) !== watchState
+      ) {
+        // Why: if the only requesting client reconnects while watcher setup is
+        // in flight, no client can later balance it with fs.unwatch. Tear down
+        // only this request's subscription so a newer replacement watch for the
+        // same root is not removed.
         void subscription.unsubscribe()
         if (this.watches.get(rootPath) === watchState) {
           this.watches.delete(rootPath)
@@ -359,15 +363,39 @@ export class FsHandler {
     }
   }
 
-  private unwatch(params: Record<string, unknown>): void {
+  private unwatch(params: Record<string, unknown>, context?: RequestContext): void {
     const rootPath = expandTilde(params.rootPath as string)
     const state = this.watches.get(rootPath)
     if (state) {
+      this.releaseWatchClient(rootPath, state, context?.clientId ?? 0)
+    }
+  }
+
+  private releaseClientWatches(clientId: number): void {
+    for (const [rootPath, state] of this.watches) {
+      this.releaseWatchClient(rootPath, state, clientId)
+    }
+  }
+
+  private releaseStaleWatches(): void {
+    for (const [rootPath, state] of this.watches) {
+      if ([...state.clients.values()].some((isStale) => !isStale())) {
+        continue
+      }
       state.unwatchFn?.()
       this.watches.delete(rootPath)
     }
   }
 
+  private releaseWatchClient(rootPath: string, state: WatchState, clientId: number): void {
+    state.clients.delete(clientId)
+    if (state.clients.size > 0) {
+      return
+    }
+    state.unwatchFn?.()
+    this.watches.delete(rootPath)
+  }
+
   dispose(): void {
     for (const [, state] of this.watches) {
       state.unwatchFn?.()
diff --git a/src/relay/pty-handler.ts b/src/relay/pty-handler.ts
index deb6658b838..7cf3c947584 100644
--- a/src/relay/pty-handler.ts
+++ b/src/relay/pty-handler.ts
@@ -627,6 +627,9 @@ export class PtyHandler {
 
   startGraceTimer(onExpire: () => void): void {
     this.cancelGraceTimer()
+    if (this.graceTimeMs === 0) {
+      return
+    }
     // Why: always wait the full grace period even with zero PTYs.  A detached
     // relay may have no PTYs yet but a --connect client will arrive shortly.
     // Firing immediately would kill the relay before anyone could connect.
diff --git a/src/relay/relay.ts b/src/relay/relay.ts
index b221c712554..b550b490fd1 100644
--- a/src/relay/relay.ts
+++ b/src/relay/relay.ts
@@ -33,6 +33,7 @@ import { GitHandler } from './git-handler'
 import { PreflightHandler } from './preflight-handler'
 import { PortScanHandler } from './port-scan-handler'
 import { AgentExecHandler } from './agent-exec-handler'
+import { WorkspaceSessionHandler } from './workspace-session-handler'
 import { endpointDirForRelaySocket, RelayAgentHookServer } from './agent-hook-server'
 import { PluginOverlayManager } from './plugin-overlay'
 import {
@@ -60,8 +61,10 @@ function parseArgs(argv: string[]): {
   for (let i = 2; i < argv.length; i++) {
     if (argv[i] === '--grace-time' && argv[i + 1]) {
       const parsed = parseInt(argv[i + 1], 10)
-      // Why: the CLI flag is in seconds for ergonomics, but internally we track ms.
-      if (!isNaN(parsed) && parsed > 0) {
+      // Why: the CLI flag is in seconds for ergonomics, but internally we track
+      // ms. 0 is allowed for opt-in synced workspaces that intentionally keep a
+      // relay alive until explicitly terminated.
+      if (!isNaN(parsed) && parsed >= 0) {
         graceTimeMs = parsed * 1000
       }
       i++
@@ -240,6 +243,9 @@ async function main(): Promise<void> {
   const _agentExecHandler = new AgentExecHandler(dispatcher)
   void _agentExecHandler
 
+  const _workspaceSessionHandler = new WorkspaceSessionHandler(dispatcher)
+  void _workspaceSessionHandler
+
   // ── Agent-hook server ─────────────────────────────────────────────
   // Why: hosts a loopback HTTP receiver inside the relay process so agent
   // CLIs running in remote PTYs can post hook events without leaving the
@@ -380,53 +386,37 @@ async function main(): Promise<void> {
   // a new --connect bridge pipe data to the same dispatcher that owns the
   // live PTYs — no serialization or process handoff needed.
 
-  let activeSocket: Socket | null = null
+  const socketClients = new Map<Socket, number>()
   let socketServer: Server | null = null
   const launchVersion = readLaunchVersion()
 
   function attachAcceptedSocket(sock: Socket, leftover: Buffer): void {
-    // Why: only one client at a time. If a second reconnect arrives (e.g.
-    // user restarts again quickly), close the stale bridge so the new one
-    // takes over cleanly. We null activeSocket BEFORE destroying so the old
-    // socket's close handler sees it's been replaced and skips starting the
-    // grace timer.
-    if (activeSocket) {
-      process.stderr.write('[relay] Replacing existing socket client with new connection\n')
-      const replaced = activeSocket
-      activeSocket = null
-      replaced.destroy()
-    }
-    activeSocket = sock
-
-    // Why: stdin's data listener is still registered from the initial
-    // connection. If the old SSH channel hasn't fully closed yet (TCP FIN
-    // delayed), buffered stdin data would interleave with the new socket
-    // client's frames, corrupting the frame decoder.
+    // Why: stdin's data listener is still registered from the initial connection.
+    // Pause/remove it once the first socket client is accepted so stale bytes
+    // from the original SSH channel cannot interleave with socket frames.
     process.stdin.pause()
     process.stdin.removeAllListeners('data')
 
     ptyHandler.cancelGraceTimer()
 
-    dispatcher.setWrite((data) => {
+    const clientId = dispatcher.attachClient((data) => {
       if (!sock.destroyed) {
         sock.write(data)
       }
     })
+    socketClients.set(sock, clientId)
 
     // Why: bytes that arrived in the same TCP send as the handshake frame
     // were buffered inside the handshake's FrameDecoder. Feed them into the
     // dispatcher BEFORE wiring sock.on('data'), so frame ordering is
     // preserved and no client data is silently dropped at the transition.
     if (leftover.length > 0) {
-      dispatcher.feed(leftover)
+      dispatcher.feedClient(clientId, leftover)
     }
 
     sock.on('data', (chunk: Buffer) => {
-      if (activeSocket !== sock) {
-        return
-      }
       ptyHandler.cancelGraceTimer()
-      dispatcher.feed(chunk)
+      dispatcher.feedClient(clientId, chunk)
     })
   }
 
@@ -451,9 +441,12 @@ async function main(): Promise<void> {
       })
 
       sock.on('close', () => {
-        if (activeSocket === sock) {
-          activeSocket = null
-          dispatcher.invalidateClient()
+        const clientId = socketClients.get(sock)
+        socketClients.delete(sock)
+        if (clientId !== undefined) {
+          dispatcher.detachClient(clientId)
+        }
+        if (!stdoutAlive && socketClients.size === 0) {
           startGrace()
         }
       })
@@ -486,6 +479,7 @@ async function main(): Promise<void> {
   // before the grace period starts.
   process.stdout.on('error', () => {
     stdoutAlive = false
+    dispatcher.invalidateClient()
   })
 
   function startGrace(): void {
@@ -512,19 +506,19 @@ async function main(): Promise<void> {
     process.stdin.on('end', () => {
       // Why: stdout is piped to the SSH channel — once stdin closes the
       // channel is gone and stdout writes would hit a dead pipe.  Mark it
-      // dead so the dispatcher's write callback becomes a no-op until a
-      // socket client reconnects and calls setWrite with a live target.
+      // dead so the primary client write callback becomes a no-op while
+      // socket clients, if any, keep their own live transports.
       stdoutAlive = false
-      if (!activeSocket) {
-        dispatcher.invalidateClient()
+      dispatcher.invalidateClient()
+      if (socketClients.size === 0) {
         startGrace()
       }
     })
 
     process.stdin.on('error', () => {
       stdoutAlive = false
-      if (!activeSocket) {
-        dispatcher.invalidateClient()
+      dispatcher.invalidateClient()
+      if (socketClients.size === 0) {
         startGrace()
       }
     })
diff --git a/src/relay/workspace-session-handler.test.ts b/src/relay/workspace-session-handler.test.ts
new file mode 100644
index 00000000000..fd74c5ab12d
--- /dev/null
+++ b/src/relay/workspace-session-handler.test.ts
@@ -0,0 +1,142 @@
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { RelayDispatcher } from './dispatcher'
+import { WorkspaceSessionHandler } from './workspace-session-handler'
+import { encodeJsonRpcFrame, MessageType, type JsonRpcRequest } from './protocol'
+
+function decodeJsonFrames(written: Buffer[]): unknown[] {
+  return written
+    .filter((buf) => buf[0] === MessageType.Regular)
+    .map((buf) => {
+      const len = buf.readUInt32BE(9)
+      return JSON.parse(buf.subarray(13, 13 + len).toString('utf-8')) as unknown
+    })
+}
+
+async function sendRequest(
+  dispatcher: RelayDispatcher,
+  method: string,
+  params: Record<string, unknown>,
+  id: number
+): Promise<void> {
+  const req: JsonRpcRequest = {
+    jsonrpc: '2.0',
+    id,
+    method,
+    params
+  }
+  dispatcher.feed(encodeJsonRpcFrame(req, id, 0))
+  await Promise.resolve()
+}
+
+describe('WorkspaceSessionHandler', () => {
+  let baseDir: string
+  let dispatcher: RelayDispatcher
+  let written: Buffer[]
+
+  beforeEach(() => {
+    baseDir = mkdtempSync(join(tmpdir(), 'orca-workspace-session-'))
+    written = []
+    dispatcher = new RelayDispatcher((data) => {
+      written.push(Buffer.from(data))
+    })
+    new WorkspaceSessionHandler(dispatcher, baseDir)
+  })
+
+  afterEach(() => {
+    dispatcher.dispose()
+    rmSync(baseDir, { recursive: true, force: true })
+  })
+
+  it('stores snapshots atomically and rejects stale revisions', async () => {
+    const session = {
+      activeWorktreePath: '/repo/worktree',
+      activeTabId: 'tab-1',
+      tabsByWorktreePath: {
+        '/repo/worktree': [{ id: 'tab-1', title: 'Terminal', worktreePath: '/repo/worktree' }]
+      },
+      terminalLayoutsByTabId: {}
+    }
+
+    await sendRequest(
+      dispatcher,
+      'workspace.patch',
+      {
+        namespace: 'ssh target/path',
+        baseRevision: 0,
+        clientId: 'client-a',
+        patch: { kind: 'replace-session', session }
+      },
+      1
+    )
+
+    const frames = decodeJsonFrames(written)
+    const response = frames.find((frame) => (frame as { id?: number }).id === 1) as {
+      result: { ok: boolean; snapshot: { revision: number; session: unknown } }
+    }
+    expect(response.result.ok).toBe(true)
+    expect(response.result.snapshot.revision).toBe(1)
+    expect(response.result.snapshot.session).toEqual(session)
+    expect(
+      frames.some((frame) => (frame as { method?: string }).method === 'workspace.changed')
+    ).toBe(true)
+
+    written = []
+    await sendRequest(
+      dispatcher,
+      'workspace.patch',
+      {
+        namespace: 'ssh target/path',
+        baseRevision: 0,
+        clientId: 'client-b',
+        patch: { kind: 'replace-session', session: { ...session, activeTabId: 'tab-2' } }
+      },
+      2
+    )
+
+    const staleResponse = decodeJsonFrames(written).find(
+      (frame) => (frame as { id?: number }).id === 2
+    ) as { result: { ok: boolean; reason: string; snapshot: { revision: number } } }
+    expect(staleResponse.result.ok).toBe(false)
+    expect(staleResponse.result.reason).toBe('stale-revision')
+    expect(staleResponse.result.snapshot.revision).toBe(1)
+  })
+
+  it('tracks presence per namespace', async () => {
+    await sendRequest(
+      dispatcher,
+      'workspace.presence',
+      {
+        namespace: 'team',
+        clientId: 'client-a',
+        clientName: ' Laptop   A '
+      },
+      1
+    )
+    await sendRequest(
+      dispatcher,
+      'workspace.presence',
+      {
+        namespace: 'team',
+        clientId: 'client-b',
+        clientName: 'Laptop B'
+      },
+      2
+    )
+
+    const response = decodeJsonFrames(written).find(
+      (frame) => (frame as { id?: number }).id === 2
+    ) as {
+      result: { clients: { clientId: string; name: string }[] }
+    }
+    expect(response.result.clients.map((client) => client.clientId).sort()).toEqual([
+      'client-a',
+      'client-b'
+    ])
+    expect(response.result.clients.find((client) => client.clientId === 'client-a')?.name).toBe(
+      'Laptop A'
+    )
+  })
+})
diff --git a/src/relay/workspace-session-handler.ts b/src/relay/workspace-session-handler.ts
new file mode 100644
index 00000000000..ef97d5bfa19
--- /dev/null
+++ b/src/relay/workspace-session-handler.ts
@@ -0,0 +1,187 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import type { RelayDispatcher } from './dispatcher'
+
+type RemoteWorkspaceSnapshot = {
+  namespace: string
+  revision: number
+  updatedAt: number
+  schemaVersion: number
+  session: Record<string, unknown>
+}
+
+type ConnectedClient = {
+  clientId: string
+  name: string
+  lastSeenAt: number
+}
+
+type PatchResult =
+  | { ok: true; snapshot: RemoteWorkspaceSnapshot }
+  | {
+      ok: false
+      reason: 'stale-revision' | 'unavailable'
+      snapshot?: RemoteWorkspaceSnapshot
+      message?: string
+    }
+
+const SNAPSHOT_SCHEMA_VERSION = 1
+const PRESENCE_TTL_MS = 45_000
+
+function emptySession(): Record<string, unknown> {
+  return {
+    activeRepoId: null,
+    activeWorktreeId: null,
+    activeTabId: null,
+    tabsByWorktree: {},
+    terminalLayoutsByTabId: {}
+  }
+}
+
+function sanitizeNamespace(namespace: unknown): string {
+  const raw = typeof namespace === 'string' && namespace.trim() ? namespace.trim() : 'default'
+  return raw.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 160) || 'default'
+}
+
+function sanitizeClientName(value: string): string {
+  return value.replace(/\s+/g, ' ').trim().slice(0, 80)
+}
+
+function sanitizeClientId(value: string): string {
+  return value.trim().slice(0, 200)
+}
+
+export class WorkspaceSessionHandler {
+  private readonly clientsByNamespace = new Map<string, Map<string, ConnectedClient>>()
+
+  constructor(
+    private dispatcher: RelayDispatcher,
+    private baseDir = join(homedir(), '.orca', 'sessions')
+  ) {
+    this.dispatcher.onRequest('workspace.get', (params) => this.get(params))
+    this.dispatcher.onRequest('workspace.patch', (params) => this.patch(params))
+    this.dispatcher.onRequest('workspace.presence', (params) => this.presence(params))
+  }
+
+  private snapshotPath(namespace: string): string {
+    return join(this.baseDir, `${namespace}.json`)
+  }
+
+  private read(namespace: string): RemoteWorkspaceSnapshot {
+    const path = this.snapshotPath(namespace)
+    if (!existsSync(path)) {
+      return {
+        namespace,
+        revision: 0,
+        updatedAt: 0,
+        schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+        session: emptySession()
+      }
+    }
+
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<RemoteWorkspaceSnapshot>
+      return {
+        namespace,
+        revision:
+          typeof parsed.revision === 'number' && Number.isFinite(parsed.revision)
+            ? parsed.revision
+            : 0,
+        updatedAt:
+          typeof parsed.updatedAt === 'number' && Number.isFinite(parsed.updatedAt)
+            ? parsed.updatedAt
+            : 0,
+        schemaVersion:
+          typeof parsed.schemaVersion === 'number' && Number.isFinite(parsed.schemaVersion)
+            ? parsed.schemaVersion
+            : SNAPSHOT_SCHEMA_VERSION,
+        session:
+          parsed.session && typeof parsed.session === 'object' && !Array.isArray(parsed.session)
+            ? (parsed.session as Record<string, unknown>)
+            : emptySession()
+      }
+    } catch {
+      return {
+        namespace,
+        revision: 0,
+        updatedAt: 0,
+        schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+        session: emptySession()
+      }
+    }
+  }
+
+  private write(snapshot: RemoteWorkspaceSnapshot): void {
+    const path = this.snapshotPath(snapshot.namespace)
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    const tmpPath = `${path}.tmp`
+    writeFileSync(tmpPath, JSON.stringify(snapshot, null, 2), { mode: 0o600 })
+    renameSync(tmpPath, path)
+  }
+
+  private async get(params: Record<string, unknown>): Promise<RemoteWorkspaceSnapshot> {
+    return this.read(sanitizeNamespace(params.namespace))
+  }
+
+  private async patch(params: Record<string, unknown>): Promise<PatchResult> {
+    const namespace = sanitizeNamespace(params.namespace)
+    const current = this.read(namespace)
+    const baseRevision = Number(params.baseRevision)
+    if (Number.isFinite(baseRevision) && baseRevision !== current.revision) {
+      return { ok: false, reason: 'stale-revision', snapshot: current }
+    }
+
+    const patch = params.patch as { kind?: unknown; session?: unknown } | undefined
+    if (
+      !patch ||
+      patch.kind !== 'replace-session' ||
+      !patch.session ||
+      typeof patch.session !== 'object' ||
+      Array.isArray(patch.session)
+    ) {
+      return { ok: false, reason: 'unavailable', message: 'Invalid workspace patch' }
+    }
+
+    const snapshot: RemoteWorkspaceSnapshot = {
+      namespace,
+      revision: current.revision + 1,
+      updatedAt: Date.now(),
+      schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+      session: patch.session as Record<string, unknown>
+    }
+    this.write(snapshot)
+    this.dispatcher.notify('workspace.changed', {
+      namespace,
+      snapshot,
+      sourceClientId: typeof params.clientId === 'string' ? params.clientId : undefined
+    })
+    return { ok: true, snapshot }
+  }
+
+  private async presence(params: Record<string, unknown>): Promise<{ clients: ConnectedClient[] }> {
+    const namespace = sanitizeNamespace(params.namespace)
+    const clientId = typeof params.clientId === 'string' ? sanitizeClientId(params.clientId) : ''
+    const name = typeof params.clientName === 'string' ? sanitizeClientName(params.clientName) : ''
+    const clients = this.clientsByNamespace.get(namespace) ?? new Map<string, ConnectedClient>()
+    this.clientsByNamespace.set(namespace, clients)
+
+    const now = Date.now()
+    for (const [id, client] of clients) {
+      if (now - client.lastSeenAt > PRESENCE_TTL_MS) {
+        clients.delete(id)
+      }
+    }
+    if (clientId) {
+      clients.set(clientId, {
+        clientId,
+        name: name || 'Unknown device',
+        lastSeenAt: now
+      })
+    }
+
+    return {
+      clients: Array.from(clients.values()).sort((a, b) => b.lastSeenAt - a.lastSeenAt)
+    }
+  }
+}
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 13a8edf6bc9..83fa72b75bd 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -33,7 +33,7 @@ import {
 } from '@/components/ui/context-menu'
 import { useAppStore } from './store'
 import { useShallow } from 'zustand/react/shallow'
-import { useIpcEvents } from './hooks/useIpcEvents'
+import { isRemoteWorkspaceSnapshotApplyInProgress, useIpcEvents } from './hooks/useIpcEvents'
 import { useAutomationDispatchEvents } from './hooks/useAutomationDispatchEvents'
 import RetainedAgentsSyncGate from './components/dashboard/RetainedAgentsSyncGate'
 import { ActivityTitlebarControls } from './components/activity/ActivityTitlebarControls'
@@ -84,6 +84,7 @@ import {
   canGoBackWorktreeHistory,
   canGoForwardWorktreeHistory
 } from '@/store/slices/worktree-nav-history'
+import type { RemoteWorkspacePatchResult } from '../../shared/remote-workspace-types'
 import type { OnboardingState } from '../../shared/types'
 
 const isMac = navigator.userAgent.includes('Mac')
@@ -173,6 +174,36 @@ const PetOverlay = lazy(() => import('./components/pet/PetOverlay'))
 // module so no eager import path pulls OnboardingFlow into the main chunk.
 const OnboardingFlow = lazy(() => import('./components/onboarding/OnboardingFlow'))
 
+function applyRemoteWorkspacePatchStatus(
+  targetId: string,
+  result: RemoteWorkspacePatchResult
+): void {
+  const store = useAppStore.getState()
+  if (result.ok) {
+    store.setRemoteWorkspaceSyncStatus(targetId, {
+      phase: 'synced',
+      direction: 'push',
+      revision: result.snapshot.revision,
+      updatedAt: result.snapshot.updatedAt,
+      lastSyncedAt: Date.now(),
+      message: 'Workspace uploaded'
+    })
+    return
+  }
+  store.setRemoteWorkspaceSyncStatus(targetId, {
+    phase: result.reason === 'stale-revision' ? 'conflict' : 'offline',
+    direction: 'push',
+    revision: result.snapshot?.revision,
+    updatedAt: result.snapshot?.updatedAt,
+    lastSyncedAt: Date.now(),
+    message:
+      result.message ??
+      (result.reason === 'stale-revision'
+        ? 'Workspace changed on another device'
+        : 'Remote workspace sync unavailable')
+  })
+}
+
 function App(): React.JSX.Element {
   useUnreadDockBadge()
   const [floatingTerminalOpen, setFloatingTerminalOpen] = useState(false)
@@ -661,7 +692,32 @@ function App(): React.JSX.Element {
   useEffect(() => {
     return createSessionWriteSubscriber({
       store: useAppStore,
-      persist: (payload) => void window.api.session.set(payload)
+      shouldSchedulePersist: () => !isRemoteWorkspaceSnapshotApplyInProgress(),
+      persist: (payload) => {
+        void window.api.session.set(payload)
+        const state = useAppStore.getState()
+        const hydratedTargetIds = Array.from(state.remoteWorkspaceHydratedTargetIds).filter(
+          (targetId) => state.remoteWorkspaceSyncStatusByTargetId[targetId]?.phase !== 'conflict'
+        )
+        if (hydratedTargetIds.length > 0) {
+          void window.api.remoteWorkspace
+            ?.setForConnectedTargets({ session: payload, hydratedTargetIds })
+            .then((results) => {
+              for (const { targetId, result } of results) {
+                applyRemoteWorkspacePatchStatus(targetId, result)
+              }
+            })
+            .catch((err) => {
+              for (const targetId of hydratedTargetIds) {
+                useAppStore.getState().setRemoteWorkspaceSyncStatus(targetId, {
+                  phase: 'error',
+                  direction: 'push',
+                  message: err instanceof Error ? err.message : 'Workspace upload failed'
+                })
+              }
+            })
+        }
+      }
     })
   }, [])
 
diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index 86d4d378933..4db3dd8393c 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -164,6 +164,7 @@ export type GitHubItemDialogProjectOrigin = {
 type GitHubItemDialogProps = {
   workItem: GitHubWorkItem | null
   repoPath: string | null
+  repoId?: string | null
   /** Called when the user clicks the primary CTA to start work from this item. */
   onUse: (item: GitHubWorkItem) => void
   onClose: () => void
@@ -394,8 +395,8 @@ function findNearestBraceBlock(
 
 type FileRowProps = {
   file: GitHubPRFile
-  repoId?: string
   repoPath: string
+  repoId: string
   prNumber: number
   headSha: string | undefined
   baseSha: string | undefined
@@ -408,8 +409,8 @@ type DiffViewMode = 'flat' | 'tree'
 type DiffTreeNodeProps = {
   node: DiffTreeNode
   depth: number
-  repoId?: string
   repoPath: string
+  repoId: string
   prNumber: number
   headSha: string | undefined
   baseSha: string | undefined
@@ -419,8 +420,8 @@ type DiffTreeNodeProps = {
 function PRDiffTreeNode({
   node,
   depth,
-  repoId,
   repoPath,
+  repoId,
   prNumber,
   headSha,
   baseSha,
@@ -432,8 +433,8 @@ function PRDiffTreeNode({
     return (
       <PRFileRow
         file={node.file}
-        repoId={repoId}
         repoPath={repoPath}
+        repoId={repoId}
         prNumber={prNumber}
         headSha={headSha}
         baseSha={baseSha}
@@ -479,8 +480,8 @@ function PRDiffTreeNode({
               key={child.kind === 'file' ? child.file.path : child.path}
               node={child}
               depth={depth + 1}
-              repoId={repoId}
               repoPath={repoPath}
+              repoId={repoId}
               prNumber={prNumber}
               headSha={headSha}
               baseSha={baseSha}
@@ -495,8 +496,8 @@ function PRDiffTreeNode({
 
 type PRDiffTreeViewProps = {
   files: GitHubPRFile[]
-  repoId?: string
   repoPath: string
+  repoId: string
   prNumber: number
   headSha: string | undefined
   baseSha: string | undefined
@@ -505,8 +506,8 @@ type PRDiffTreeViewProps = {
 
 function PRDiffTreeView({
   files,
-  repoId,
   repoPath,
+  repoId,
   prNumber,
   headSha,
   baseSha,
@@ -520,8 +521,8 @@ function PRDiffTreeView({
           key={node.kind === 'file' ? node.file.path : node.path}
           node={node}
           depth={0}
-          repoId={repoId}
           repoPath={repoPath}
+          repoId={repoId}
           prNumber={prNumber}
           headSha={headSha}
           baseSha={baseSha}
@@ -567,21 +568,15 @@ function notifyWorkItemDetailsCache(): void {
 }
 
 function getWorkItemDetailsCacheKey(args: {
-  runtimeScope: string
   repoPath: string
+  repoId: string
   issueSourcePreference: string | undefined
   type: 'issue' | 'pr'
   number: number
 }): string {
   // Why: include all axes that change which (repo, item) the IPC resolves to.
   // `\0` separator avoids ambiguity between fields that may contain `:` or `/`.
-  return [
-    args.runtimeScope,
-    args.repoPath,
-    args.issueSourcePreference ?? 'auto',
-    args.type,
-    args.number
-  ].join('\0')
+  return [args.repoId, args.issueSourcePreference ?? 'auto', args.type, args.number].join('\0')
 }
 
 function touchWorkItemDetailsCache(key: string, entry: WorkItemDetailsCacheEntry): void {
@@ -624,14 +619,16 @@ let workItemDetailsCacheGeneration = 0
 // matches the (repoPath, type, number) tuple regardless of source preference.
 function invalidateWorkItemDetailsCacheByMatch(args: {
   repoPath: string
+  repoId?: string
   type: 'issue' | 'pr'
   number: number
 }): void {
   workItemDetailsCacheGeneration += 1
+  const suffix = `\0${args.type}\0${args.number}`
+  const prefix = `${args.repoId ?? args.repoPath}\0`
   let removed = false
   for (const key of Array.from(workItemDetailsCache.keys())) {
-    const [, repoPath, , type, number] = key.split('\0')
-    if (repoPath === args.repoPath && type === args.type && number === String(args.number)) {
+    if (key.startsWith(prefix) && key.endsWith(suffix)) {
       workItemDetailsCache.delete(key)
       removed = true
     }
@@ -651,6 +648,7 @@ if (typeof window !== 'undefined' && window.api?.gh?.onWorkItemMutated) {
   workItemMutatedUnsub = window.api.gh.onWorkItemMutated((payload) => {
     invalidateWorkItemDetailsCacheByMatch({
       repoPath: payload.repoPath,
+      repoId: payload.repoId,
       type: payload.type,
       number: payload.number
     })
@@ -685,16 +683,15 @@ function touchPRFileContentCache(
 }
 
 function getPRFileContentCacheKey(args: {
-  repoId?: string
   repoPath: string
+  repoId: string
   prNumber: number
   file: GitHubPRFile
   headSha: string
   baseSha: string
 }): string {
   return [
-    args.repoId ?? '',
-    args.repoPath,
+    args.repoId,
     args.prNumber,
     args.file.path,
     args.file.oldPath ?? '',
@@ -705,8 +702,8 @@ function getPRFileContentCacheKey(args: {
 }
 
 function loadPRFileContents(args: {
-  repoId?: string
   repoPath: string
+  repoId: string
   prNumber: number
   file: GitHubPRFile
   headSha: string
@@ -718,33 +715,17 @@ function loadPRFileContents(args: {
     touchPRFileContentCache(cacheKey, cached)
     return Promise.resolve(cached)
   }
-  const target = getRuntimeTargetForRepoId(args.repoId)
-  const request = (
-    target
-      ? callRuntimeRpc<GitHubPRFileContents>(
-          target,
-          'github.prFileContents',
-          {
-            repo: args.repoId,
-            prNumber: args.prNumber,
-            path: args.file.path,
-            oldPath: args.file.oldPath,
-            status: args.file.status,
-            headSha: args.headSha,
-            baseSha: args.baseSha
-          },
-          { timeoutMs: 30_000 }
-        )
-      : window.api.gh.prFileContents({
-          repoPath: args.repoPath,
-          prNumber: args.prNumber,
-          path: args.file.path,
-          oldPath: args.file.oldPath,
-          status: args.file.status,
-          headSha: args.headSha,
-          baseSha: args.baseSha
-        })
-  )
+  const request = window.api.gh
+    .prFileContents({
+      repoPath: args.repoPath,
+      repoId: args.repoId,
+      prNumber: args.prNumber,
+      path: args.file.path,
+      oldPath: args.file.oldPath,
+      status: args.file.status,
+      headSha: args.headSha,
+      baseSha: args.baseSha
+    })
     .then((contents) => {
       touchPRFileContentCache(cacheKey, contents)
       return contents
@@ -757,18 +738,6 @@ function loadPRFileContents(args: {
   return request
 }
 
-function getRuntimeTargetForRepoId(repoId: string | null | undefined) {
-  if (!repoId) {
-    return null
-  }
-  const state = useAppStore.getState()
-  const target = getActiveRuntimeTarget(state.settings)
-  if (target.kind !== 'environment') {
-    return null
-  }
-  return state.repos.some((repo) => repo.id === repoId) ? target : null
-}
-
 function addIssueCommentForRepo(args: {
   repoId?: string
   repoPath: string
@@ -776,17 +745,9 @@ function addIssueCommentForRepo(args: {
   body: string
   type?: 'issue' | 'pr'
 }): Promise<Awaited<ReturnType<typeof window.api.gh.addIssueComment>>> {
-  const target = getRuntimeTargetForRepoId(args.repoId)
-  if (target) {
-    return callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.addIssueComment>>>(
-      target,
-      'github.addIssueComment',
-      { repo: args.repoId, number: args.number, body: args.body, type: args.type },
-      { timeoutMs: 30_000 }
-    )
-  }
   return window.api.gh.addIssueComment({
     repoPath: args.repoPath,
+    repoId: args.repoId,
     number: args.number,
     body: args.body,
     type: args.type
@@ -803,25 +764,9 @@ function addPRReviewCommentForRepo(args: {
   startLine?: number
   body: string
 }): Promise<Awaited<ReturnType<typeof window.api.gh.addPRReviewComment>>> {
-  const target = getRuntimeTargetForRepoId(args.repoId)
-  if (target) {
-    return callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.addPRReviewComment>>>(
-      target,
-      'github.addPRReviewComment',
-      {
-        repo: args.repoId,
-        prNumber: args.prNumber,
-        commitId: args.commitId,
-        path: args.path,
-        line: args.line,
-        startLine: args.startLine,
-        body: args.body
-      },
-      { timeoutMs: 30_000 }
-    )
-  }
   return window.api.gh.addPRReviewComment({
     repoPath: args.repoPath,
+    repoId: args.repoId,
     prNumber: args.prNumber,
     commitId: args.commitId,
     path: args.path,
@@ -841,25 +786,9 @@ function addPRReviewCommentReplyForRepo(args: {
   path?: string
   line?: number
 }): Promise<Awaited<ReturnType<typeof window.api.gh.addPRReviewCommentReply>>> {
-  const target = getRuntimeTargetForRepoId(args.repoId)
-  if (target) {
-    return callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.addPRReviewCommentReply>>>(
-      target,
-      'github.addPRReviewCommentReply',
-      {
-        repo: args.repoId,
-        prNumber: args.prNumber,
-        commentId: args.commentId,
-        body: args.body,
-        threadId: args.threadId,
-        path: args.path,
-        line: args.line
-      },
-      { timeoutMs: 30_000 }
-    )
-  }
   return window.api.gh.addPRReviewCommentReply({
     repoPath: args.repoPath,
+    repoId: args.repoId,
     prNumber: args.prNumber,
     commentId: args.commentId,
     body: args.body,
@@ -875,17 +804,9 @@ function getWorkItemDetailsForRepo(args: {
   number: number
   type: 'issue' | 'pr'
 }): Promise<GitHubWorkItemDetails | null> {
-  const target = getRuntimeTargetForRepoId(args.repoId)
-  if (target) {
-    return callRuntimeRpc<GitHubWorkItemDetails | null>(
-      target,
-      'github.workItemDetails',
-      { repo: args.repoId, number: args.number, type: args.type },
-      { timeoutMs: 30_000 }
-    )
-  }
   return window.api.gh.workItemDetails({
     repoPath: args.repoPath,
+    repoId: args.repoId,
     number: args.number,
     type: args.type
   })
@@ -893,8 +814,8 @@ function getWorkItemDetailsForRepo(args: {
 
 function PRFileRow({
   file,
-  repoId,
   repoPath,
+  repoId,
   prNumber,
   headSha,
   baseSha,
@@ -920,8 +841,8 @@ function PRFileRow({
         setLoading(true)
         setError(null)
         loadPRFileContents({
-          repoId,
           repoPath,
+          repoId,
           prNumber,
           file,
           headSha,
@@ -958,8 +879,8 @@ function PRFileRow({
         return false
       }
       const result = await addPRReviewCommentForRepo({
-        repoId,
         repoPath,
+        repoId,
         prNumber,
         commitId: headSha,
         path: file.path,
@@ -1105,6 +1026,7 @@ function PRFileRow({
 function CommentCodeContext({
   comment,
   repoPath,
+  repoId,
   prNumber,
   files,
   headSha,
@@ -1112,6 +1034,7 @@ function CommentCodeContext({
 }: {
   comment: PRComment
   repoPath: string | null
+  repoId: string
   prNumber: number
   files: GitHubPRFile[]
   headSha: string | undefined
@@ -1135,7 +1058,7 @@ function CommentCodeContext({
       return
     }
     let cancelled = false
-    loadPRFileContents({ repoPath, prNumber, file, headSha, baseSha })
+    loadPRFileContents({ repoPath, repoId, prNumber, file, headSha, baseSha })
       .then((result) => {
         if (!cancelled) {
           setContents(result)
@@ -1149,7 +1072,7 @@ function CommentCodeContext({
     return () => {
       cancelled = true
     }
-  }, [baseSha, file, headSha, line, prNumber, repoPath])
+  }, [baseSha, file, headSha, line, prNumber, repoId, repoPath])
 
   useEffect(() => {
     setContextBefore(0)
@@ -1343,7 +1266,6 @@ function CommentCodeContext({
 
 function ConversationTab({
   item,
-  repoId,
   repoPath,
   body,
   comments,
@@ -1357,7 +1279,6 @@ function ConversationTab({
   onCommentAdded
 }: {
   item: GitHubWorkItem
-  repoId?: string
   repoPath: string | null
   body: string
   comments: PRComment[]
@@ -1370,11 +1291,10 @@ function ConversationTab({
   onUse: (item: GitHubWorkItem) => void
   onCommentAdded: (comment: PRComment) => void
 }): React.JSX.Element {
-  const settings = useAppStore((s) => s.settings)
   const authorLabel = item.author ?? 'unknown'
   const [replyingTo, setReplyingTo] = useState<number | null>(null)
   const [commentFilter, setCommentFilter] = useState<PRCommentAudienceFilter>('all')
-  const repoAssignees = useRepoAssignees(repoPath, repoId, settings)
+  const repoAssignees = useRepoAssignees(repoPath, item.repoId)
   const commentCounts = useMemo(() => getPRCommentAudienceCounts(comments), [comments])
   const visibleComments = useMemo(
     () => filterPRCommentsByAudience(comments, commentFilter),
@@ -1407,8 +1327,8 @@ function ConversationTab({
       const result =
         comment.path && item.type === 'pr'
           ? await addPRReviewCommentReplyForRepo({
-              repoId,
               repoPath,
+              repoId: item.repoId,
               prNumber: item.number,
               commentId: comment.id,
               body: replyBody,
@@ -1417,8 +1337,8 @@ function ConversationTab({
               line: comment.line
             })
           : await addIssueCommentForRepo({
-              repoId,
               repoPath,
+              repoId: item.repoId,
               number: item.number,
               body: `@${comment.author} ${replyBody}`,
               type: item.type
@@ -1433,7 +1353,7 @@ function ConversationTab({
       toast.success('Reply posted.')
       return true
     },
-    [item.number, item.type, onCommentAdded, repoId, repoPath]
+    [item.number, item.repoId, item.type, onCommentAdded, repoPath]
   )
 
   const startWorkspaceButton = (
@@ -1545,6 +1465,7 @@ function ConversationTab({
         <CommentCodeContext
           comment={comment}
           repoPath={repoPath}
+          repoId={item.repoId}
           prNumber={item.number}
           files={files}
           headSha={headSha}
@@ -1688,8 +1609,8 @@ function ConversationTab({
         {repoPath && (
           <GHCommentComposer
             className="mt-1"
-            repoId={repoId}
             repoPath={repoPath}
+            repoId={item.repoId}
             issueNumber={item.number}
             itemType={item.type}
             mentionOptions={mentionOptions}
@@ -2004,8 +1925,8 @@ function MentionTextarea({
 // to a thrown rejection so the existing `useImmediateMutation` flow
 // (which expects throws on failure) continues to work unchanged.
 async function runIssueUpdate(args: {
-  repoId?: string
   repoPath: string | null
+  repoId?: string | null
   projectOrigin: GitHubItemDialogProjectOrigin | undefined
   number: number
   updates: Parameters<typeof window.api.gh.updateIssue>[0]['updates']
@@ -2035,21 +1956,9 @@ async function runIssueUpdate(args: {
   if (!args.repoPath) {
     throw new Error('No repo context available for this edit.')
   }
-  const target = getRuntimeTargetForRepoId(args.repoId)
-  if (target) {
-    const res = await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.updateIssue>>>(
-      target,
-      'github.updateIssue',
-      { repo: args.repoId, number: args.number, updates: args.updates },
-      { timeoutMs: 30_000 }
-    )
-    if (!res.ok) {
-      throw new Error(res.error)
-    }
-    return
-  }
   await window.api.gh.updateIssue({
     repoPath: args.repoPath,
+    repoId: args.repoId ?? undefined,
     number: args.number,
     updates: args.updates
   })
@@ -2058,6 +1967,7 @@ async function runIssueUpdate(args: {
 function GHEditSection({
   item,
   repoPath,
+  repoId,
   projectOrigin,
   localState,
   localLabels,
@@ -2069,6 +1979,7 @@ function GHEditSection({
 }: {
   item: GitHubWorkItem
   repoPath: string | null
+  repoId: string | null
   projectOrigin: GitHubItemDialogProjectOrigin | undefined
   localState: GitHubWorkItem['state']
   localLabels: string[]
@@ -2088,8 +1999,6 @@ function GHEditSection({
   const patchWorkItem = useAppStore((s) => s.patchWorkItem)
   const patchProjectRowContent = useAppStore((s) => s.patchProjectRowContent)
   const { isPending, run } = useImmediateMutation()
-  const settings = useAppStore((s) => s.settings)
-
   // Why: when the dialog opens from a Project view, mutations route through
   // *BySlug IPCs and we must keep `projectViewCache` in sync alongside
   // `workItemsCache` — `patchWorkItem` only walks the latter, so without this
@@ -2112,17 +2021,15 @@ function GHEditSection({
   const slugRepo = projectOrigin?.repo ?? null
   const repoLabelsByPath = useRepoLabels(
     projectOrigin ? null : repoPath,
-    projectOrigin ? null : item.repoId,
-    settings
+    projectOrigin ? null : repoId
   )
-  const repoLabelsBySlug = useRepoLabelsBySlug(slugOwner, slugRepo, settings)
+  const repoLabelsBySlug = useRepoLabelsBySlug(slugOwner, slugRepo)
   const repoLabels = projectOrigin ? repoLabelsBySlug : repoLabelsByPath
   const repoAssigneesByPath = useRepoAssignees(
     projectOrigin ? null : repoPath,
-    projectOrigin ? null : item.repoId,
-    settings
+    projectOrigin ? null : repoId
   )
-  const repoAssigneesBySlug = useRepoAssigneesBySlug(slugOwner, slugRepo, assignees, settings)
+  const repoAssigneesBySlug = useRepoAssigneesBySlug(slugOwner, slugRepo, assignees)
   const repoAssignees = projectOrigin ? repoAssigneesBySlug : repoAssigneesByPath
 
   // Why: sync local assignees when item changes or when the detail fetch
@@ -2522,16 +2429,16 @@ function GHEditSection({
 
 function GHCommentComposer({
   className,
-  repoId,
   repoPath,
+  repoId,
   issueNumber,
   itemType,
   mentionOptions,
   onCommentAdded
 }: {
   className?: string
-  repoId?: string
   repoPath: string
+  repoId?: string | null
   issueNumber: number
   itemType: 'issue' | 'pr'
   mentionOptions: MentionOption[]
@@ -2558,8 +2465,8 @@ function GHCommentComposer({
     setSubmitting(true)
     try {
       const result = await addIssueCommentForRepo({
-        repoId,
         repoPath,
+        repoId: repoId ?? undefined,
         number: issueNumber,
         body: trimmed,
         type: itemType
@@ -2578,7 +2485,7 @@ function GHCommentComposer({
     } finally {
       setSubmitting(false)
     }
-  }, [autoGrow, body, repoId, repoPath, issueNumber, itemType, onCommentAdded])
+  }, [autoGrow, body, repoPath, repoId, issueNumber, itemType, onCommentAdded])
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -2640,10 +2547,10 @@ function GHCommentComposer({
 // doc §1 rule: hide when either side is unknown rather than guessing.
 function WorkItemIssueSourceIndicator({
   url,
-  repoPath
+  repoId
 }: {
   url: string
-  repoPath: string | null
+  repoId: string | null
 }): React.JSX.Element | null {
   // Why: subscribe to a single store-side selector that returns the resolved
   // sources for this repo — either the primary `(repoPath, PER_REPO_FETCH_LIMIT, '')`
@@ -2657,7 +2564,7 @@ function WorkItemIssueSourceIndicator({
   // indicator is small and the cache rewrite rate is bounded by user-initiated
   // refresh/search actions.
   const sources = useAppStore((s) =>
-    s.getWorkItemsAnySourcesForRepo(repoPath ?? '', PER_REPO_FETCH_LIMIT)
+    s.getWorkItemsAnySourcesForRepo(repoId ?? '', PER_REPO_FETCH_LIMIT)
   )
   const issues = useMemo<GitHubOwnerRepo | null>(() => {
     const fromUrl = parseOwnerRepoFromItemUrl(url)
@@ -2688,6 +2595,7 @@ function WorkItemIssueSourceIndicator({
 export default function GitHubItemDialog({
   workItem,
   repoPath,
+  repoId,
   projectOrigin,
   onUse,
   onClose
@@ -2700,6 +2608,7 @@ export default function GitHubItemDialog({
   const workItemId = workItem?.id
   const workItemState = workItem?.state
   const workItemLabels = workItem?.labels
+  const effectiveRepoId = repoId ?? workItem?.repoId ?? null
 
   // Why: the cache key has to include the issue source preference so a user
   // toggling between origin/upstream for the same issue number doesn't read
@@ -2707,28 +2616,24 @@ export default function GitHubItemDialog({
   // than threading it as a prop because every existing call site already has
   // the repo registered in the store.
   const issueSourcePreference = useAppStore((s) => {
-    if (!repoPath) {
+    if (!repoPath && !effectiveRepoId) {
       return undefined
     }
-    return s.repos.find((r) => r.path === repoPath)?.issueSourcePreference
+    return s.repos.find((r) => (effectiveRepoId ? r.id === effectiveRepoId : r.path === repoPath))
+      ?.issueSourcePreference
   })
-  const runtimeScope = useAppStore((s) =>
-    s.settings?.activeRuntimeEnvironmentId
-      ? `runtime:${s.settings.activeRuntimeEnvironmentId}`
-      : 'local'
-  )
   const detailsCacheKey = useMemo(() => {
-    if (!workItem || !repoPath) {
+    if (!workItem || !repoPath || !effectiveRepoId) {
       return null
     }
     return getWorkItemDetailsCacheKey({
-      runtimeScope,
       repoPath,
+      repoId: effectiveRepoId,
       issueSourcePreference,
       type: workItem.type,
       number: workItem.number
     })
-  }, [runtimeScope, repoPath, workItem, issueSourcePreference])
+  }, [repoPath, effectiveRepoId, workItem, issueSourcePreference])
 
   // Why: reset lifted edit state when the dialog switches items or when the
   // same item receives an optimistic cache patch from the surrounding table.
@@ -2871,8 +2776,8 @@ export default function GitHubItemDialog({
     const inflight: Promise<GitHubWorkItemDetails | null> =
       cached?.pending ??
       getWorkItemDetailsForRepo({
-        repoId: workItem.repoId,
         repoPath,
+        repoId: effectiveRepoId ?? undefined,
         number: workItem.number,
         type: workItem.type
       })
@@ -2933,7 +2838,7 @@ export default function GitHubItemDialog({
           error: message
         })
       })
-  }, [repoPath, workItem, detailsCacheKey, refetchTick])
+  }, [repoPath, effectiveRepoId, workItem, detailsCacheKey, refetchTick])
 
   const Icon = workItem?.type === 'pr' ? GitPullRequest : CircleDot
   const body = details?.body ?? ''
@@ -3054,7 +2959,7 @@ export default function GitHubItemDialog({
                     )}
                   </div>
                   {workItem.type === 'issue' && (
-                    <WorkItemIssueSourceIndicator url={workItem.url} repoPath={repoPath} />
+                    <WorkItemIssueSourceIndicator url={workItem.url} repoId={effectiveRepoId} />
                   )}
                 </div>
                 <div className="flex shrink-0 items-center gap-1">
@@ -3116,6 +3021,7 @@ export default function GitHubItemDialog({
               <GHEditSection
                 item={workItem}
                 repoPath={repoPath}
+                repoId={effectiveRepoId}
                 projectOrigin={projectOrigin}
                 localState={localState}
                 localLabels={localLabels}
@@ -3130,6 +3036,7 @@ export default function GitHubItemDialog({
                   if (repoPath) {
                     invalidateWorkItemDetailsCacheByMatch({
                       repoPath,
+                      repoId: effectiveRepoId ?? undefined,
                       type: workItem.type,
                       number: workItem.number
                     })
@@ -3174,7 +3081,6 @@ export default function GitHubItemDialog({
                     <TabsContent value="conversation" className="mt-0">
                       <ConversationTab
                         item={workItem}
-                        repoId={workItem.repoId}
                         repoPath={repoPath}
                         body={body}
                         comments={comments}
@@ -3253,8 +3159,8 @@ export default function GitHubItemDialog({
                                 <PRFileRow
                                   key={file.path}
                                   file={file}
-                                  repoId={workItem.repoId}
                                   repoPath={repoPath ?? ''}
+                                  repoId={effectiveRepoId ?? ''}
                                   prNumber={workItem.number}
                                   headSha={details?.headSha}
                                   baseSha={details?.baseSha}
@@ -3264,8 +3170,8 @@ export default function GitHubItemDialog({
                             ) : (
                               <PRDiffTreeView
                                 files={files}
-                                repoId={workItem.repoId}
                                 repoPath={repoPath ?? ''}
+                                repoId={effectiveRepoId ?? ''}
                                 prNumber={workItem.number}
                                 headSha={details?.headSha}
                                 baseSha={details?.baseSha}
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 7abc2f431ad..0133d5869f9 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -274,6 +274,7 @@ function GHStatusCell({
             )
           : window.api.gh.updateIssue({
               repoPath: repo.path,
+              repoId: repo.id,
               number: item.number,
               updates: { state: newState }
             })
@@ -895,7 +896,7 @@ export default function TaskPage(): React.JSX.Element {
     const trimmed = initialTaskQuery.trim()
     const merged: GitHubWorkItem[] = []
     for (const r of selectedRepos) {
-      const cached = getCachedWorkItems(r.path, PER_REPO_FETCH_LIMIT, trimmed)
+      const cached = getCachedWorkItems(r.id, PER_REPO_FETCH_LIMIT, trimmed)
       if (cached) {
         merged.push(...cached)
       }
@@ -1473,7 +1474,7 @@ export default function TaskPage(): React.JSX.Element {
     const preMerged: GitHubWorkItem[] = []
     let anyUncached = false
     for (const r of selectedRepos) {
-      const cached = getCachedWorkItems(r.path, PER_REPO_FETCH_LIMIT, q)
+      const cached = getCachedWorkItems(r.id, PER_REPO_FETCH_LIMIT, q)
       if (cached === null) {
         anyUncached = true
       } else {
@@ -1573,7 +1574,7 @@ export default function TaskPage(): React.JSX.Element {
     // The search API is cached 120s server-side so this doesn't add
     // meaningful latency or rate-limit pressure.
     void countWorkItemsAcrossRepos(
-      selectedRepos.map((r) => ({ path: r.path })),
+      selectedRepos.map((r) => ({ repoId: r.id, path: r.path })),
       q
     ).then((count) => {
       if (!cancelled) {
@@ -1697,6 +1698,7 @@ export default function TaskPage(): React.JSX.Element {
           )
         : await window.api.gh.createIssue({
             repoPath: newIssueTargetRepo.path,
+            repoId: newIssueTargetRepo.id,
             title,
             body: newIssueBody
           })
@@ -1744,6 +1746,7 @@ export default function TaskPage(): React.JSX.Element {
           )
         : window.api.gh.workItem({
             repoPath: newIssueTargetRepo.path,
+            repoId: newIssueTargetRepo.id,
             number: result.number,
             type: 'issue'
           })
@@ -1965,7 +1968,8 @@ export default function TaskPage(): React.JSX.Element {
         type: 'issue',
         number: 0,
         title: issue.title,
-        url: issue.url
+        url: issue.url,
+        linearIdentifier: issue.identifier
       }
       openModal('new-workspace-composer', {
         linkedWorkItem,
@@ -3552,6 +3556,7 @@ export default function TaskPage(): React.JSX.Element {
           // scan on every render while the dialog is open.
           dialogWorkItem ? (repoMap.get(dialogWorkItem.repoId)?.path ?? null) : null
         }
+        repoId={dialogWorkItem?.repoId ?? null}
         onUse={(item) => {
           setDialogWorkItem(null)
           handleUseWorkItem(item)
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index c575c0dd54f..822ffeb509e 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -23,7 +23,6 @@ import { cn } from '@/lib/utils'
 import { getWorktreeStatus, getWorktreeStatusLabel } from '@/lib/worktree-status'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
-import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import {
   searchWorktrees,
   type MatchRange,
@@ -42,8 +41,6 @@ import {
 import type {
   BrowserPage,
   BrowserWorkspace,
-  GitHubWorkItem,
-  Repo,
   Worktree
 } from '../../../shared/types'
 import { isGitRepoKind } from '../../../shared/repo-kind'
@@ -83,55 +80,6 @@ type BrowserSelection = {
   page: BrowserPage
 }
 
-type GitHubWorkItemWithoutRepo = Omit<GitHubWorkItem, 'repoId'>
-
-function getRuntimeTargetForRepo(
-  repo: Repo
-): { kind: 'environment'; environmentId: string } | null {
-  const target = getActiveRuntimeTarget(useAppStore.getState().settings)
-  if (target.kind !== 'environment') {
-    return null
-  }
-  return useAppStore.getState().repos.some((candidate) => candidate.id === repo.id) ? target : null
-}
-
-function getWorkItemForRepo(repo: Repo, number: number): Promise<GitHubWorkItemWithoutRepo | null> {
-  const target = getRuntimeTargetForRepo(repo)
-  if (target) {
-    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
-      target,
-      'github.workItem',
-      { repo: repo.id, number },
-      { timeoutMs: 30_000 }
-    )
-  }
-  return window.api.gh.workItem({ repoPath: repo.path, number })
-}
-
-function getWorkItemByOwnerRepoForRepo(
-  repo: Repo,
-  slug: { owner: string; repo: string },
-  number: number,
-  type: 'issue' | 'pr'
-): Promise<GitHubWorkItemWithoutRepo | null> {
-  const target = getRuntimeTargetForRepo(repo)
-  if (target) {
-    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
-      target,
-      'github.workItemByOwnerRepo',
-      { repo: repo.id, owner: slug.owner, ownerRepo: slug.repo, number, type },
-      { timeoutMs: 30_000 }
-    )
-  }
-  return window.api.gh.workItemByOwnerRepo({
-    repoPath: repo.path,
-    owner: slug.owner,
-    repo: slug.repo,
-    number,
-    type
-  })
-}
-
 function HighlightedText({
   text,
   matchRange
@@ -741,7 +689,15 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       // indefinitely on slow networks. Close immediately and populate the
       // composer once the lookup returns.
       closeModal()
-      void getWorkItemByOwnerRepoForRepo(repoForLookup, slug, number, ghLink.type)
+      void window.api.gh
+        .workItemByOwnerRepo({
+          repoPath: repoForLookup.path,
+          repoId: repoForLookup.id,
+          owner: slug.owner,
+          repo: slug.repo,
+          number,
+          type: ghLink.type
+        })
         .then((item) => {
           const data: Record<string, unknown> = { initialRepoId: repoForLookup.id }
           if (item) {
@@ -794,7 +750,8 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       }
 
       closeModal()
-      void getWorkItemForRepo(repoForLookup, ghNumber)
+      void window.api.gh
+        .workItem({ repoPath: repoForLookup.path, repoId: repoForLookup.id, number: ghNumber })
         .then((item) => {
           const data: Record<string, unknown> = { initialRepoId: repoForLookup.id }
           if (item) {
diff --git a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
index f670072fd6d..15cd8b41779 100644
--- a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
+++ b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
@@ -317,6 +317,7 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
   const [dialogRepoItem, setDialogRepoItem] = useState<{
     workItem: GitHubWorkItem
     repoPath: string
+    repoId: string
     origin: GitHubItemDialogProjectOrigin
   } | null>(null)
   // Why: the slug dialog is only opened for rows whose repo isn't registered
@@ -405,11 +406,12 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
         }
         return
       }
-      const matched = lookupSlug(`${origin.owner}/${origin.repo}`)
+      const matches = lookupSlug(`${origin.owner}/${origin.repo}`)
+      const matched = matches.length === 1 ? matches[0] : null
       if (matched) {
         const workItem = buildWorkItem(row, matched.id)
         if (workItem) {
-          setDialogRepoItem({ workItem, repoPath: matched.path, origin })
+          setDialogRepoItem({ workItem, repoPath: matched.path, repoId: matched.id, origin })
           return
         }
       }
@@ -428,7 +430,8 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
       if (!origin) {
         return
       }
-      const matched = lookupSlug(`${origin.owner}/${origin.repo}`)
+      const matches = lookupSlug(`${origin.owner}/${origin.repo}`)
+      const matched = matches.length === 1 ? matches[0] : null
       if (!matched) {
         setRepoNotInOrca({
           owner: origin.owner,
@@ -700,6 +703,7 @@ export default function ProjectViewWrapper(_props: Props = {} as Props): React.J
       <GitHubItemDialog
         workItem={dialogRepoItem?.workItem ?? null}
         repoPath={dialogRepoItem?.repoPath ?? null}
+        repoId={dialogRepoItem?.repoId ?? null}
         projectOrigin={dialogRepoItem?.origin}
         onUse={(item) => {
           const current = dialogRepoItem
diff --git a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
index acc44e650c8..cae02a249fe 100644
--- a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
+++ b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
@@ -41,11 +41,9 @@ import {
 import { parseGitLabIssueOrMRLink } from '@/lib/gitlab-links'
 import { cn } from '@/lib/utils'
 import { LinearIcon } from '@/components/icons/LinearIcon'
-import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import type {
   GitHubWorkItem,
   GitLabWorkItem,
-  GlobalSettings,
   LinearIssue
 } from '../../../../shared/types'
 
@@ -63,7 +61,6 @@ const MR_STATE_FILTERS: { id: MrStateFilter; label: string }[] = [
 ]
 
 type RepoOption = ReturnType<typeof useAppStore.getState>['repos'][number]
-type GitHubWorkItemWithoutRepo = Omit<GitHubWorkItem, 'repoId'>
 
 type SmartWorkspaceNameFieldProps = {
   repos: RepoOption[]
@@ -166,8 +163,6 @@ export default function SmartWorkspaceNameField({
       searchLinearIssues: s.searchLinearIssues
     }))
   )
-  const settings = useAppStore((s) => s.settings)
-
   const selectedRepo = useMemo(
     () => repos.find((repo) => repo.id === repoId) ?? null,
     [repoId, repos]
@@ -235,7 +230,7 @@ export default function SmartWorkspaceNameField({
   const shouldQueryLinear = mode === 'smart' || mode === 'linear'
 
   useEffect(() => {
-    if (!shouldQueryGithub || !selectedRepo?.path || selectedRepo.connectionId) {
+    if (!shouldQueryGithub || !selectedRepo?.path) {
       setGithubItems([])
       setGithubLoading(false)
       return
@@ -245,20 +240,21 @@ export default function SmartWorkspaceNameField({
     const directLink = parsedGhLink
     if (directLink !== null && handledCrossRepoUrlRef.current !== debouncedQuery.trim()) {
       setGithubLoading(true)
-      void getRepoSlugCached(selectedRepo, repoSlugCacheRef.current, settings)
+      void getRepoSlugCached(selectedRepo, repoSlugCacheRef.current)
         .then(async (selectedSlug) => {
           if (stale) {
             return
           }
           if (!selectedSlug || sameSlug(selectedSlug, directLink.slug)) {
             handledCrossRepoUrlRef.current = debouncedQuery.trim()
-            const item = await getWorkItemByOwnerRepo(
-              selectedRepo,
-              directLink.slug,
-              directLink.number,
-              directLink.type,
-              settings
-            )
+            const item = await window.api.gh.workItemByOwnerRepo({
+              repoPath: selectedRepo.path,
+              repoId: selectedRepo.id,
+              owner: directLink.slug.owner,
+              repo: directLink.slug.repo,
+              number: directLink.number,
+              type: directLink.type
+            })
             if (!stale) {
               setGithubItems(item ? [{ ...item, repoId: selectedRepo.id } as GitHubWorkItem] : [])
             }
@@ -267,8 +263,7 @@ export default function SmartWorkspaceNameField({
           const matchingRepo = await findMatchingRepoForSlug(
             repos,
             directLink.slug,
-            repoSlugCacheRef.current,
-            settings
+            repoSlugCacheRef.current
           )
           if (!stale) {
             setGithubItems([])
@@ -289,14 +284,19 @@ export default function SmartWorkspaceNameField({
       setGithubLoading(true)
       const request =
         directLink !== null
-          ? getWorkItemByOwnerRepo(
-              selectedRepo,
-              directLink.slug,
-              directLink.number,
-              directLink.type,
-              settings
-            )
-          : getWorkItem(selectedRepo, directNumber, undefined, settings)
+          ? window.api.gh.workItemByOwnerRepo({
+              repoPath: selectedRepo.path,
+              repoId: selectedRepo.id,
+              owner: directLink.slug.owner,
+              repo: directLink.slug.repo,
+              number: directLink.number,
+              type: directLink.type
+            })
+          : window.api.gh.workItem({
+              repoPath: selectedRepo.path,
+              repoId: selectedRepo.id,
+              number: directNumber
+            })
       void request
         .then((item) => {
           if (!stale) {
@@ -320,7 +320,7 @@ export default function SmartWorkspaceNameField({
 
     const trimmed = normalizedGhQuery.query.trim()
     const query = trimmed ? normalizedGhQuery.query : ''
-    const cached = getCachedWorkItems(selectedRepo.path, RESULT_LIMIT, query)
+    const cached = getCachedWorkItems(selectedRepo.id, RESULT_LIMIT, query)
     if (cached) {
       setGithubItems(cached.slice(0, RESULT_LIMIT))
       setGithubLoading(false)
@@ -354,7 +354,6 @@ export default function SmartWorkspaceNameField({
     parsedGhLink,
     repos,
     selectedRepo,
-    settings,
     shouldQueryGithub
   ])
 
@@ -715,13 +714,14 @@ export default function SmartWorkspaceNameField({
       handledCrossRepoUrlRef.current = debouncedQuery.trim()
       setGithubLoading(true)
       try {
-        const item = await getWorkItemByOwnerRepo(
-          targetRepo,
-          crossRepoPrompt.link.slug,
-          crossRepoPrompt.link.number,
-          crossRepoPrompt.link.type,
-          settings
-        )
+        const item = await window.api.gh.workItemByOwnerRepo({
+          repoPath: targetRepo.path,
+          repoId: targetRepo.id,
+          owner: crossRepoPrompt.link.slug.owner,
+          repo: crossRepoPrompt.link.slug.repo,
+          number: crossRepoPrompt.link.number,
+          type: crossRepoPrompt.link.type
+        })
         if (!item) {
           return
         }
@@ -733,7 +733,7 @@ export default function SmartWorkspaceNameField({
         setGithubLoading(false)
       }
     },
-    [crossRepoPrompt, debouncedQuery, onGitHubItemSelect, onRepoChange, settings]
+    [crossRepoPrompt, debouncedQuery, onGitHubItemSelect, onRepoChange]
   )
 
   const handleUseCurrentRepo = useCallback(async (): Promise<void> => {
@@ -753,11 +753,11 @@ export default function SmartWorkspaceNameField({
       return
     }
     repoSlugCacheRef.current.delete(added.id)
-    const slug = await getRepoSlugCached(added, repoSlugCacheRef.current, settings)
+    const slug = await getRepoSlugCached(added, repoSlugCacheRef.current)
     if (slug && sameSlug(slug, crossRepoPrompt.link.slug)) {
       await acceptGitHubLink(added)
     }
-  }, [acceptGitHubLink, addRepo, crossRepoPrompt, settings])
+  }, [acceptGitHubLink, addRepo, crossRepoPrompt])
 
   const dismissCrossRepoPrompt = useCallback((): void => {
     handledCrossRepoUrlRef.current = debouncedQuery.trim()
@@ -1175,37 +1175,16 @@ function sameSlug(left: RepoSlug, right: RepoSlug): boolean {
   )
 }
 
-function runtimeSlugScope(
-  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
-): string {
-  const target = getActiveRuntimeTarget(settings)
-  return target.kind === 'environment' ? `runtime:${target.environmentId}` : 'local'
-}
-
 async function getRepoSlugCached(
   repo: RepoOption,
-  cache: Map<string, RepoSlug | null>,
-  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+  cache: Map<string, RepoSlug | null>
 ): Promise<RepoSlug | null> {
-  const cacheKey = `${runtimeSlugScope(settings)}:${repo.id}`
+  const cacheKey = repo.id
   if (cache.has(cacheKey)) {
     return cache.get(cacheKey) ?? null
   }
-  if (repo.connectionId) {
-    cache.set(cacheKey, null)
-    return null
-  }
   try {
-    const target = getActiveRuntimeTarget(settings)
-    const slug =
-      target.kind === 'environment'
-        ? await callRuntimeRpc<RepoSlug | null>(
-            target,
-            'github.repoSlug',
-            { repo: repo.id },
-            { timeoutMs: 30_000 }
-          )
-        : await window.api.gh.repoSlug({ repoPath: repo.path })
+    const slug = await window.api.gh.repoSlug({ repoPath: repo.path, repoId: repo.id })
     cache.set(cacheKey, slug)
     return slug
   } catch {
@@ -1217,63 +1196,13 @@ async function getRepoSlugCached(
 async function findMatchingRepoForSlug(
   repos: RepoOption[],
   slug: RepoSlug,
-  cache: Map<string, RepoSlug | null>,
-  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
+  cache: Map<string, RepoSlug | null>
 ): Promise<RepoOption | null> {
   for (const repo of repos) {
-    const candidate = await getRepoSlugCached(repo, cache, settings)
+    const candidate = await getRepoSlugCached(repo, cache)
     if (candidate && sameSlug(candidate, slug)) {
       return repo
     }
   }
   return null
 }
-
-function getWorkItem(
-  repo: RepoOption,
-  number: number,
-  type: 'issue' | 'pr' | undefined,
-  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
-): Promise<GitHubWorkItemWithoutRepo | null> {
-  const target = getActiveRuntimeTarget(settings)
-  if (target.kind === 'environment') {
-    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
-      target,
-      'github.workItem',
-      { repo: repo.id, number, ...(type ? { type } : {}) },
-      { timeoutMs: 30_000 }
-    )
-  }
-  return window.api.gh.workItem({ repoPath: repo.path, number, ...(type ? { type } : {}) })
-}
-
-function getWorkItemByOwnerRepo(
-  repo: RepoOption,
-  slug: RepoSlug,
-  number: number,
-  type: 'issue' | 'pr',
-  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
-): Promise<GitHubWorkItemWithoutRepo | null> {
-  const target = getActiveRuntimeTarget(settings)
-  if (target.kind === 'environment') {
-    return callRuntimeRpc<GitHubWorkItemWithoutRepo | null>(
-      target,
-      'github.workItemByOwnerRepo',
-      {
-        repo: repo.id,
-        owner: slug.owner,
-        ownerRepo: slug.repo,
-        number,
-        type
-      },
-      { timeoutMs: 30_000 }
-    )
-  }
-  return window.api.gh.workItemByOwnerRepo({
-    repoPath: repo.path,
-    owner: slug.owner,
-    repo: slug.repo,
-    number,
-    type
-  })
-}
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index 886af2ef3bc..a550e225647 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -17,7 +17,6 @@ import {
 } from './checks-panel-content'
 import { ENTRY_REFRESH_GRACE_MS, shouldEntryRefresh } from './checks-entry-refresh'
 import type { PRInfo, PRCheckDetail, PRComment } from '../../../../shared/types'
-import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 export default function ChecksPanel(): React.JSX.Element {
   const activeWorktree = useActiveWorktree()
@@ -76,7 +75,7 @@ export default function ChecksPanel(): React.JSX.Element {
   // Find active worktree and repo
   const branch = activeWorktree ? activeWorktree.branch.replace(/^refs\/heads\//, '') : ''
   const isFolder = repo ? isFolderRepo(repo) : false
-  const prCacheKey = repo && branch ? `${repo.path}::${branch}` : ''
+  const prCacheKey = repo && branch ? `${repo.id}::${branch}` : ''
   const pr: PRInfo | null = prCacheKey ? (prCache[prCacheKey]?.data ?? null) : null
   const prNumber = pr?.number ?? null
   const conflictOperation = activeWorktreeId
@@ -89,8 +88,8 @@ export default function ChecksPanel(): React.JSX.Element {
   const prFetchedAt = useAppStore((s) =>
     prCacheKey ? s.prCache[prCacheKey]?.fetchedAt : undefined
   )
-  const checksCacheKey = repo && prNumber ? `${repo.path}::pr-checks::${prNumber}` : ''
-  const commentsCacheKey = repo && prNumber ? `${repo.path}::pr-comments::${prNumber}` : ''
+  const checksCacheKey = repo && prNumber ? `${repo.id}::pr-checks::${prNumber}` : ''
+  const commentsCacheKey = repo && prNumber ? `${repo.id}::pr-comments::${prNumber}` : ''
   const checksFetchedAt = useAppStore((s) =>
     checksCacheKey ? s.checksCache[checksCacheKey]?.fetchedAt : undefined
   )
@@ -104,7 +103,7 @@ export default function ChecksPanel(): React.JSX.Element {
   const linkedPR = activeWorktree?.linkedPR ?? null
   useEffect(() => {
     if (repo && !isFolder && branch) {
-      void fetchPRForBranch(repo.path, branch, { linkedPRNumber: linkedPR })
+      void fetchPRForBranch(repo.path, branch, { repoId: repo.id, linkedPRNumber: linkedPR })
     }
   }, [repo, isFolder, branch, linkedPR, fetchPRForBranch])
 
@@ -126,16 +125,18 @@ export default function ChecksPanel(): React.JSX.Element {
     // lists from an older payload.
     conflictSummaryRefreshKeyRef.current = refreshKey
     setConflictDetailsRefreshing(true)
-    void fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR }).finally(
-      () => {
-        // Why: fetchPRForBranch updates the PR cache before resolving, which
-        // can rerun this effect. Only the current refresh key may clear the
-        // spinner so stale requests don't race newer worktrees/branches.
-        if (conflictSummaryRefreshKeyRef.current === refreshKey) {
-          setConflictDetailsRefreshing(false)
-        }
+    void fetchPRForBranch(repo.path, branch, {
+      force: true,
+      repoId: repo.id,
+      linkedPRNumber: linkedPR
+    }).finally(() => {
+      // Why: fetchPRForBranch updates the PR cache before resolving, which
+      // can rerun this effect. Only the current refresh key may clear the
+      // spinner so stale requests don't race newer worktrees/branches.
+      if (conflictSummaryRefreshKeyRef.current === refreshKey) {
+        setConflictDetailsRefreshing(false)
       }
-    )
+    })
   }, [repo, isFolder, branch, pr, linkedPR, fetchPRForBranch])
 
   // Fetch checks via cached store method
@@ -151,7 +152,8 @@ export default function ChecksPanel(): React.JSX.Element {
       setChecksLoading(true)
       try {
         const result = await fetchPRChecks(repo.path, targetPRNumber, branch, pr?.headSha, {
-          force
+          force,
+          repoId: repo.id
         })
         setChecks(result)
 
@@ -219,7 +221,7 @@ export default function ChecksPanel(): React.JSX.Element {
       }
       setCommentsLoading(true)
       try {
-        const result = await fetchPRComments(repo.path, targetPRNumber, { force })
+        const result = await fetchPRComments(repo.path, targetPRNumber, { force, repoId: repo.id })
         setComments(result)
       } catch (err) {
         console.warn('Failed to fetch PR comments:', err)
@@ -240,7 +242,7 @@ export default function ChecksPanel(): React.JSX.Element {
     // state after the user switches worktrees, showing the wrong PR's comments.
     let cancelled = false
     setCommentsLoading(true)
-    void fetchPRComments(repo.path, prNumber).then(
+    void fetchPRComments(repo.path, prNumber, { repoId: repo.id }).then(
       (result) => {
         if (!cancelled) {
           setComments(result)
@@ -267,6 +269,7 @@ export default function ChecksPanel(): React.JSX.Element {
     try {
       const refreshedPR = await fetchPRForBranch(repo.path, branch, {
         force: true,
+        repoId: repo.id,
         linkedPRNumber: linkedPR
       })
       if (refreshedPR) {
@@ -279,7 +282,7 @@ export default function ChecksPanel(): React.JSX.Element {
           refreshedPR.number,
           branch,
           refreshedPR.headSha,
-          { force: true }
+          { force: true, repoId: repo.id }
         ).then(
           (result) => {
             setChecks(result)
@@ -378,23 +381,19 @@ export default function ChecksPanel(): React.JSX.Element {
     }
     setTitleSaving(true)
     try {
-      const target = getActiveRuntimeTarget(useAppStore.getState().settings)
-      const ok =
-        target.kind === 'environment'
-          ? await callRuntimeRpc<boolean>(
-              target,
-              'github.updatePRTitle',
-              { repo: repo.id, prNumber: pr.number, title: titleDraft.trim() },
-              { timeoutMs: 30_000 }
-            )
-          : await window.api.gh.updatePRTitle({
-              repoPath: repo.path,
-              prNumber: pr.number,
-              title: titleDraft.trim()
-            })
+      const ok = await window.api.gh.updatePRTitle({
+        repoPath: repo.path,
+        repoId: repo.id,
+        prNumber: pr.number,
+        title: titleDraft.trim()
+      })
       if (ok) {
         // Re-fetch PR to get updated title
-        await fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR })
+        await fetchPRForBranch(repo.path, branch, {
+          force: true,
+          repoId: repo.id,
+          linkedPRNumber: linkedPR
+        })
       }
     } finally {
       setTitleSaving(false)
@@ -419,14 +418,16 @@ export default function ChecksPanel(): React.JSX.Element {
       if (!repo || !prNumber) {
         return
       }
-      void resolveReviewThread(repo.path, prNumber, threadId, resolve).then((ok) => {
-        if (ok) {
-          // Update local state to match the optimistic store update
-          setComments((prev) =>
-            prev.map((c) => (c.threadId === threadId ? { ...c, isResolved: resolve } : c))
-          )
+      void resolveReviewThread(repo.path, prNumber, threadId, resolve, { repoId: repo.id }).then(
+        (ok) => {
+          if (ok) {
+            // Update local state to match the optimistic store update
+            setComments((prev) =>
+              prev.map((c) => (c.threadId === threadId ? { ...c, isResolved: resolve } : c))
+            )
+          }
         }
-      })
+      )
     },
     [repo, prNumber, resolveReviewThread]
   )
@@ -434,7 +435,11 @@ export default function ChecksPanel(): React.JSX.Element {
   // Refresh PR (passed to PRActions)
   const handleRefreshPR = useCallback(async () => {
     if (repo && branch) {
-      await fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR })
+      await fetchPRForBranch(repo.path, branch, {
+        force: true,
+        repoId: repo.id,
+        linkedPRNumber: linkedPR
+      })
     }
   }, [repo, branch, linkedPR, fetchPRForBranch])
 
diff --git a/src/renderer/src/components/right-sidebar/PRActions.tsx b/src/renderer/src/components/right-sidebar/PRActions.tsx
index bb913938c25..17a7fdac4b8 100644
--- a/src/renderer/src/components/right-sidebar/PRActions.tsx
+++ b/src/renderer/src/components/right-sidebar/PRActions.tsx
@@ -6,7 +6,6 @@ import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@/components/ui/tooltip'
 import type { PRInfo, Repo, Worktree } from '../../../../shared/types'
 import { runWorktreeDeleteWithToast } from '../sidebar/delete-worktree-flow'
-import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
 const MERGE_METHODS = ['squash', 'merge', 'rebase'] as const
 
@@ -40,20 +39,12 @@ export default function PRActions({
       setMergeError(null)
       setMergeMenuOpen(false)
       try {
-        const target = getActiveRuntimeTarget(useAppStore.getState().settings)
-        const result =
-          target.kind === 'environment'
-            ? await callRuntimeRpc<{ ok: true } | { ok: false; error: string }>(
-                target,
-                'github.mergePR',
-                { repo: repo.id, prNumber: pr.number, method },
-                { timeoutMs: 30_000 }
-              )
-            : await window.api.gh.mergePR({
-                repoPath: repo.path,
-                prNumber: pr.number,
-                method
-              })
+        const result = await window.api.gh.mergePR({
+          repoPath: repo.path,
+          repoId: repo.id,
+          prNumber: pr.number,
+          method
+        })
         if (!result.ok) {
           setMergeError(result.error)
         } else {
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index 71eaea8e1f4..ccfffb88c1d 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -461,10 +461,10 @@ function SourceControlInner(): React.JSX.Element {
 
   const branchName = activeWorktree?.branch.replace(/^refs\/heads\//, '') ?? 'HEAD'
   const hostedReviewCacheKey =
-    activeRepo && branchName ? getHostedReviewCacheKey(activeRepo.path, branchName, settings) : null
-  const hostedReviewEntry = hostedReviewCacheKey
-    ? hostedReviewCache[hostedReviewCacheKey]
-    : undefined
+    activeRepo && branchName
+      ? getHostedReviewCacheKey(activeRepo.path, branchName, settings, activeRepo.id)
+      : null
+  const hostedReviewEntry = hostedReviewCacheKey ? hostedReviewCache[hostedReviewCacheKey] : undefined
   const hostedReview: HostedReviewInfo | null = hostedReviewCacheKey
     ? (hostedReviewEntry?.data ?? null)
     : null
@@ -477,16 +477,16 @@ function SourceControlInner(): React.JSX.Element {
     if (!isBranchVisible || !activeRepo || isFolder || !branchName || branchName === 'HEAD') {
       return
     }
-    if (activeRepo.connectionId) {
-      return
-    }
-
     // Why: the Source Control panel renders branch review status directly.
     // When a terminal checkout moves this worktree onto a new branch, we need
     // to fetch that branch's PR/MR immediately instead of waiting for the user
     // to reselect the worktree. The linked ids handle create-from-review
     // worktrees whose local branch differs from the remote head branch.
-    void fetchHostedReviewForBranch(activeRepo.path, branchName, { linkedGitHubPR, linkedGitLabMR })
+    void fetchHostedReviewForBranch(activeRepo.path, branchName, {
+      repoId: activeRepo.id,
+      linkedGitHubPR,
+      linkedGitLabMR
+    })
   }, [
     activeRepo,
     branchName,
diff --git a/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts b/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts
index a871ca1a4e7..f7b0f80eeb2 100644
--- a/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts
+++ b/src/renderer/src/components/right-sidebar/useGitStatusPolling.test.ts
@@ -3,7 +3,7 @@ import type * as React from 'react'
 import type { GitStatusResult } from '../../../../shared/types'
 
 const worktree = { id: 'repo-1::/repo', repoId: 'repo-1', path: '/repo' }
-const repo = { id: 'repo-1', path: '/repo', kind: 'git' }
+const repo = { id: 'repo-1', path: '/repo', kind: 'git', connectionId: null as string | null }
 
 type PollState = {
   activeWorktreeId: string
@@ -13,6 +13,7 @@ type PollState = {
   setUpstreamStatus: ReturnType<typeof vi.fn>
   setConflictOperation: ReturnType<typeof vi.fn>
   gitConflictOperationByWorktree: Record<string, unknown>
+  sshConnectionStates: Map<string, { status: string }>
 }
 
 type GitStatusPollingHook = () => void
@@ -22,7 +23,14 @@ function GitStatusPollingHarness({ runPolling }: { runPolling: GitStatusPollingH
   return null
 }
 
-async function usePollingOnce(status: GitStatusResult): Promise<PollState> {
+async function usePollingOnce(
+  status: GitStatusResult,
+  options: {
+    connectionId?: string | null
+    sshStatus?: string
+    expectStatusCall?: boolean
+  } = {}
+): Promise<{ state: PollState; gitStatus: ReturnType<typeof vi.fn> }> {
   vi.resetModules()
 
   const state: PollState = {
@@ -32,8 +40,15 @@ async function usePollingOnce(status: GitStatusResult): Promise<PollState> {
     fetchUpstreamStatus: vi.fn().mockResolvedValue(undefined),
     setUpstreamStatus: vi.fn(),
     setConflictOperation: vi.fn(),
-    gitConflictOperationByWorktree: {}
+    gitConflictOperationByWorktree: {},
+    sshConnectionStates: new Map(
+      options.connectionId && options.sshStatus
+        ? [[options.connectionId, { status: options.sshStatus }]]
+        : []
+    )
   }
+  const mockedRepo = { ...repo, connectionId: options.connectionId ?? null }
+  const gitStatus = vi.fn().mockResolvedValue(status)
 
   vi.doMock('react', async () => {
     const actual = await vi.importActual<typeof React>('react')
@@ -56,18 +71,18 @@ async function usePollingOnce(status: GitStatusResult): Promise<PollState> {
   vi.doMock('@/store/selectors', () => ({
     useActiveWorktree: () => worktree,
     useAllWorktrees: () => [worktree],
-    useRepoById: () => repo,
-    useRepoMap: () => new Map([[repo.id, repo]])
+    useRepoById: () => mockedRepo,
+    useRepoMap: () => new Map([[mockedRepo.id, mockedRepo]])
   }))
 
   vi.doMock('@/lib/connection-context', () => ({
-    getConnectionId: () => undefined
+    getConnectionId: () => options.connectionId ?? undefined
   }))
 
   vi.stubGlobal('window', {
     api: {
       git: {
-        status: vi.fn().mockResolvedValue(status)
+        status: gitStatus
       }
     },
     addEventListener: vi.fn(),
@@ -80,11 +95,13 @@ async function usePollingOnce(status: GitStatusResult): Promise<PollState> {
 
   const { useGitStatusPolling: runPolling } = await import('./useGitStatusPolling')
   GitStatusPollingHarness({ runPolling })
-  await vi.waitFor(() => {
-    expect(state.setGitStatus).toHaveBeenCalled()
-  })
+  await (options.expectStatusCall !== false
+    ? vi.waitFor(() => {
+        expect(state.setGitStatus).toHaveBeenCalled()
+      })
+    : Promise.resolve())
 
-  return state
+  return { state, gitStatus }
 }
 
 describe('useGitStatusPolling', () => {
@@ -94,7 +111,7 @@ describe('useGitStatusPolling', () => {
   })
 
   it('uses upstream data from git status instead of spawning a separate upstream refresh', async () => {
-    const state = await usePollingOnce({
+    const { state } = await usePollingOnce({
       entries: [],
       conflictOperation: 'unknown',
       head: 'abc123',
@@ -117,7 +134,7 @@ describe('useGitStatusPolling', () => {
   })
 
   it('falls back to the upstream IPC for legacy status payloads', async () => {
-    const state = await usePollingOnce({
+    const { state } = await usePollingOnce({
       entries: [],
       conflictOperation: 'unknown',
       head: 'abc123',
@@ -127,4 +144,19 @@ describe('useGitStatusPolling', () => {
     expect(state.setUpstreamStatus).not.toHaveBeenCalled()
     expect(state.fetchUpstreamStatus).toHaveBeenCalledWith(worktree.id, '/repo', undefined)
   })
+
+  it('skips remote git status polling while the SSH target is disconnected', async () => {
+    const { state, gitStatus } = await usePollingOnce(
+      {
+        entries: [],
+        conflictOperation: 'unknown',
+        head: 'abc123',
+        branch: 'refs/heads/main'
+      },
+      { connectionId: 'ssh-target-1', sshStatus: 'disconnected', expectStatusCall: false }
+    )
+
+    expect(gitStatus).not.toHaveBeenCalled()
+    expect(state.setGitStatus).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts b/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts
index 07874284dfe..e989b921bdf 100644
--- a/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts
+++ b/src/renderer/src/components/right-sidebar/useGitStatusPolling.ts
@@ -19,12 +19,19 @@ export function useGitStatusPolling(): void {
   const setUpstreamStatus = useAppStore((s) => s.setUpstreamStatus)
   const setConflictOperation = useAppStore((s) => s.setConflictOperation)
   const conflictOperationByWorktree = useAppStore((s) => s.gitConflictOperationByWorktree)
+  const sshConnectionStates = useAppStore((s) => s.sshConnectionStates)
   const repoMap = useRepoMap()
 
   const worktreePath = activeWorktree?.path ?? null
   const activeRepoId = activeWorktree?.repoId ?? null
   const activeRepo = useRepoById(activeRepoId)
   const activeRepoSupportsGit = activeRepo ? isGitRepoKind(activeRepo) : false
+  const activeConnectionId = activeRepo?.connectionId ?? null
+  const isConnectionReady = useCallback(
+    (connectionId: string | null | undefined): boolean =>
+      !connectionId || sshConnectionStates.get(connectionId)?.status === 'connected',
+    [sshConnectionStates]
+  )
 
   // Why: build a list of non-active worktrees that still have a known conflict
   // operation (merge/rebase/cherry-pick). These need lightweight polling so
@@ -52,6 +59,9 @@ export function useGitStatusPolling(): void {
     if (!activeWorktreeId || !worktreePath || !activeRepoSupportsGit) {
       return
     }
+    if (!isConnectionReady(activeConnectionId)) {
+      return
+    }
     try {
       const connectionId = getConnectionId(activeWorktreeId) ?? undefined
       await refreshGitStatusForWorktree({
@@ -71,8 +81,10 @@ export function useGitStatusPolling(): void {
     }
   }, [
     activeRepoSupportsGit,
+    activeConnectionId,
     activeWorktreeId,
     fetchUpstreamStatus,
+    isConnectionReady,
     worktreePath,
     setGitStatus,
     setUpstreamStatus,
@@ -111,11 +123,17 @@ export function useGitStatusPolling(): void {
     const pollStale = async (): Promise<void> => {
       for (const { id, path } of staleConflictWorktrees) {
         try {
+          const connectionId = getConnectionId(id) ?? undefined
+          // Why: after explicit SSH disconnect the provider is intentionally
+          // gone; keep remote polling quiet until the target reconnects.
+          if (!isConnectionReady(connectionId)) {
+            continue
+          }
           const op = (await getRuntimeGitConflictOperation({
             settings: useAppStore.getState().settings,
             worktreeId: id,
             worktreePath: path,
-            connectionId: getConnectionId(id) ?? undefined
+            connectionId
           })) as GitConflictOperation
           setConflictOperation(id, op)
         } catch {
@@ -136,5 +154,5 @@ export function useGitStatusPolling(): void {
       clearInterval(intervalId)
       window.removeEventListener('focus', onFocus)
     }
-  }, [staleConflictWorktrees, setConflictOperation])
+  }, [staleConflictWorktrees, setConflictOperation, isConnectionReady])
 }
diff --git a/src/renderer/src/components/settings/SshPane.tsx b/src/renderer/src/components/settings/SshPane.tsx
index 5fdffbd3d4d..f1343c2a9f6 100644
--- a/src/renderer/src/components/settings/SshPane.tsx
+++ b/src/renderer/src/components/settings/SshPane.tsx
@@ -57,7 +57,7 @@ export function SshPane(_props: SshPaneProps): React.JSX.Element {
     null
   )
 
-  const setSshTargetLabels = useAppStore((s) => s.setSshTargetLabels)
+  const setSshTargetsMetadata = useAppStore((s) => s.setSshTargetsMetadata)
 
   const loadTargets = useCallback(
     async (opts?: { signal?: AbortSignal }) => {
@@ -67,18 +67,14 @@ export function SshPane(_props: SshPaneProps): React.JSX.Element {
           return
         }
         setTargets(result)
-        const labels = new Map<string, string>()
-        for (const t of result) {
-          labels.set(t.id, t.label)
-        }
-        setSshTargetLabels(labels)
+        setSshTargetsMetadata(result)
       } catch {
         if (!opts?.signal?.aborted) {
           toast.error('Failed to load SSH targets')
         }
       }
     },
-    [setSshTargetLabels]
+    [setSshTargetsMetadata]
   )
 
   useEffect(() => {
@@ -104,6 +100,14 @@ export function SshPane(_props: SshPaneProps): React.JSX.Element {
       toast.error('Relay grace period must be between 60 and 3600 seconds')
       return
     }
+    const remoteGraceSeconds = parseInt(form.remoteWorkspaceSyncGracePeriodSeconds, 10)
+    if (
+      form.remoteWorkspaceSyncEnabled &&
+      (isNaN(remoteGraceSeconds) || remoteGraceSeconds < 0 || remoteGraceSeconds > 3600)
+    ) {
+      toast.error('Synced relay grace period must be between 0 and 3600 seconds')
+      return
+    }
 
     const target = {
       label: form.label.trim() || `${form.username}@${form.host}`,
@@ -112,6 +116,10 @@ export function SshPane(_props: SshPaneProps): React.JSX.Element {
       port,
       username: form.username.trim(),
       relayGracePeriodSeconds: graceSeconds,
+      remoteWorkspaceSyncEnabled: form.remoteWorkspaceSyncEnabled,
+      remoteWorkspaceSyncGracePeriodSeconds: form.remoteWorkspaceSyncEnabled
+        ? remoteGraceSeconds
+        : 300,
       ...(form.identityFile.trim() ? { identityFile: form.identityFile.trim() } : {}),
       ...(form.proxyCommand.trim() ? { proxyCommand: form.proxyCommand.trim() } : {}),
       ...(form.jumpHost.trim() ? { jumpHost: form.jumpHost.trim() } : {})
@@ -173,7 +181,11 @@ export function SshPane(_props: SshPaneProps): React.JSX.Element {
       identityFile: target.identityFile ?? '',
       proxyCommand: target.proxyCommand ?? '',
       jumpHost: target.jumpHost ?? '',
-      relayGracePeriodSeconds: String(target.relayGracePeriodSeconds ?? 300)
+      relayGracePeriodSeconds: String(target.relayGracePeriodSeconds ?? 300),
+      remoteWorkspaceSyncEnabled: target.remoteWorkspaceSyncEnabled === true,
+      remoteWorkspaceSyncGracePeriodSeconds: String(
+        target.remoteWorkspaceSyncGracePeriodSeconds ?? 300
+      )
     })
     setShowForm(true)
   }
diff --git a/src/renderer/src/components/settings/SshTargetForm.tsx b/src/renderer/src/components/settings/SshTargetForm.tsx
index 49e97af57cc..ba372b13452 100644
--- a/src/renderer/src/components/settings/SshTargetForm.tsx
+++ b/src/renderer/src/components/settings/SshTargetForm.tsx
@@ -13,6 +13,8 @@ export type EditingTarget = {
   proxyCommand: string
   jumpHost: string
   relayGracePeriodSeconds: string
+  remoteWorkspaceSyncEnabled: boolean
+  remoteWorkspaceSyncGracePeriodSeconds: string
 }
 
 export const EMPTY_FORM: EditingTarget = {
@@ -24,7 +26,9 @@ export const EMPTY_FORM: EditingTarget = {
   identityFile: '',
   proxyCommand: '',
   jumpHost: '',
-  relayGracePeriodSeconds: '300'
+  relayGracePeriodSeconds: '300',
+  remoteWorkspaceSyncEnabled: false,
+  remoteWorkspaceSyncGracePeriodSeconds: '300'
 }
 
 type SshTargetFormProps = {
@@ -140,6 +144,47 @@ export function SshTargetForm({
             How long the relay keeps terminals alive after disconnect. Default: 300 (5 minutes).
           </p>
         </div>
+        <div className="col-span-2 space-y-3 border-t border-border/50 pt-3">
+          <label className="flex items-start gap-3 text-sm">
+            <input
+              type="checkbox"
+              className="mt-0.5 size-4 accent-foreground"
+              checked={form.remoteWorkspaceSyncEnabled}
+              onChange={(e) =>
+                onFormChange((f) => ({ ...f, remoteWorkspaceSyncEnabled: e.target.checked }))
+              }
+            />
+            <span className="space-y-1">
+              <span className="block font-medium">Sync remote workspace</span>
+              <span className="block text-[11px] text-muted-foreground">
+                Store terminal tabs and split layouts on the SSH host so another Orca client can
+                restore the same remote workspace.
+              </span>
+            </span>
+          </label>
+          {form.remoteWorkspaceSyncEnabled && (
+            <div className="space-y-1.5 pl-7">
+              <Label>Synced Relay Grace Period (seconds)</Label>
+              <Input
+                type="number"
+                value={form.remoteWorkspaceSyncGracePeriodSeconds}
+                onChange={(e) =>
+                  onFormChange((f) => ({
+                    ...f,
+                    remoteWorkspaceSyncGracePeriodSeconds: e.target.value
+                  }))
+                }
+                placeholder="0"
+                min={0}
+                max={3600}
+              />
+              <p className="text-[11px] text-muted-foreground">
+                How long synced remote workspace terminals stay alive after all clients disconnect.
+                0 keeps them alive until explicitly terminated.
+              </p>
+            </div>
+          )}
+        </div>
       </div>
 
       <div className="flex items-center gap-2">
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.tsx b/src/renderer/src/components/sidebar/WorktreeCard.tsx
index 8690617c281..9278d095d23 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.tsx
@@ -146,8 +146,8 @@ const WorktreeCard = React.memo(function WorktreeCard({
   const branch = branchDisplayName(worktree.branch)
   const isFolder = repo ? isFolderRepo(repo) : false
   const hostedReviewCacheKey =
-    repo && branch ? getHostedReviewCacheKey(repo.path, branch, settings) : ''
-  const issueCacheKey = repo && worktree.linkedIssue ? `${repo.path}::${worktree.linkedIssue}` : ''
+    repo && branch ? getHostedReviewCacheKey(repo.path, branch, settings, repo.id) : ''
+  const issueCacheKey = repo && worktree.linkedIssue ? `${repo.id}::${worktree.linkedIssue}` : ''
 
   // Subscribe to ONLY the specific cache entry, not entire review/issue caches.
   const hostedReviewEntry = useAppStore((s) =>
@@ -185,18 +185,12 @@ const WorktreeCard = React.memo(function WorktreeCard({
   // This preference is purely presentational, so background refreshes would
   // spend rate limit budget on data the user cannot see.
   useEffect(() => {
-    if (
-      repo &&
-      !repo.connectionId &&
-      !isFolder &&
-      !worktree.isBare &&
-      hostedReviewCacheKey &&
-      (showPR || showCI)
-    ) {
+    if (repo && !isFolder && !worktree.isBare && hostedReviewCacheKey && (showPR || showCI)) {
       // Why: pass linkedPR so worktrees created from a PR (whose new local
       // branch differs from the remote head ref) still resolve their PR/MR via
       // a number-based fallback in the main process.
       fetchHostedReviewForBranch(repo.path, branch, {
+        repoId: repo.id,
         linkedGitHubPR: worktree.linkedPR ?? null,
         linkedGitLabMR: worktree.linkedGitLabMR ?? null
       })
@@ -221,11 +215,11 @@ const WorktreeCard = React.memo(function WorktreeCard({
       return
     }
 
-    fetchIssue(repo.path, worktree.linkedIssue)
+    fetchIssue(repo.path, worktree.linkedIssue, { repoId: repo.id })
 
     // Background poll as fallback (activity triggers handle the fast path)
     const interval = setInterval(() => {
-      fetchIssue(repo.path, worktree.linkedIssue!)
+      fetchIssue(repo.path, worktree.linkedIssue!, { repoId: repo.id })
     }, 5 * 60_000) // 5 minutes
 
     return () => clearInterval(interval)
diff --git a/src/renderer/src/components/status-bar/SshStatusSegment.tsx b/src/renderer/src/components/status-bar/SshStatusSegment.tsx
index 8796375b8fb..1d7c365f011 100644
--- a/src/renderer/src/components/status-bar/SshStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/SshStatusSegment.tsx
@@ -1,5 +1,5 @@
 import React, { useCallback, useState } from 'react'
-import { Loader2, MonitorSmartphone, Server, ServerOff } from 'lucide-react'
+import { AlertTriangle, Cloud, Loader2, MonitorSmartphone, Server, ServerOff } from 'lucide-react'
 import { toast } from 'sonner'
 import {
   DropdownMenu,
@@ -11,6 +11,7 @@ import {
 import { useAppStore } from '../../store'
 import { STATUS_LABELS, statusColor } from '../settings/SshTargetCard'
 import type { SshConnectionStatus } from '../../../../shared/ssh-types'
+import type { RemoteWorkspaceSyncStatus } from '../../store/slices/ssh'
 
 function isConnecting(status: SshConnectionStatus): boolean {
   return ['connecting', 'deploying-relay', 'reconnecting'].includes(status)
@@ -64,14 +65,54 @@ function overallLabel(status: 'connected' | 'partial' | 'disconnected' | 'connec
   }
 }
 
+function syncStatusLabel(status: RemoteWorkspaceSyncStatus | undefined): string {
+  switch (status?.phase) {
+    case 'pulling':
+      return 'Sync pulling'
+    case 'pushing':
+      return 'Sync pushing'
+    case 'synced':
+      return status.direction === 'pull' ? 'Sync pulled' : 'Sync uploaded'
+    case 'conflict':
+      return 'Sync conflict'
+    case 'error':
+      return 'Sync error'
+    case 'offline':
+      return 'Sync unavailable'
+    default:
+      return 'Sync idle'
+  }
+}
+
+function syncStatusTone(status: RemoteWorkspaceSyncStatus | undefined): string {
+  switch (status?.phase) {
+    case 'conflict':
+    case 'error':
+      return 'text-destructive'
+    case 'offline':
+      return 'text-muted-foreground'
+    case 'pulling':
+    case 'pushing':
+      return 'text-yellow-500'
+    case 'synced':
+      return 'text-emerald-500'
+    default:
+      return 'text-muted-foreground'
+  }
+}
+
 function TargetRow({
   targetId,
   label,
-  status
+  status,
+  syncEnabled,
+  syncStatus
 }: {
   targetId: string
   label: string
   status: SshConnectionStatus
+  syncEnabled: boolean
+  syncStatus: RemoteWorkspaceSyncStatus | undefined
 }): React.JSX.Element {
   const [busy, setBusy] = useState(false)
 
@@ -102,7 +143,26 @@ function TargetRow({
       <span className={`size-1.5 shrink-0 rounded-full ${statusColor(status)}`} />
       <div className="min-w-0 flex-1">
         <div className="truncate text-[12px] font-medium">{label}</div>
-        <div className="text-[10px] text-muted-foreground">{STATUS_LABELS[status]}</div>
+        <div className="flex min-w-0 items-center gap-1.5 text-[10px] text-muted-foreground">
+          <span>{STATUS_LABELS[status]}</span>
+          {syncEnabled && (
+            <>
+              <span aria-hidden="true">·</span>
+              <span
+                className={`inline-flex min-w-0 items-center gap-1 ${syncStatusTone(syncStatus)}`}
+              >
+                {syncStatus?.phase === 'pulling' || syncStatus?.phase === 'pushing' ? (
+                  <Loader2 className="size-2.5 shrink-0 animate-spin" />
+                ) : syncStatus?.phase === 'conflict' || syncStatus?.phase === 'error' ? (
+                  <AlertTriangle className="size-2.5 shrink-0" />
+                ) : (
+                  <Cloud className="size-2.5 shrink-0" />
+                )}
+                <span className="truncate">{syncStatusLabel(syncStatus)}</span>
+              </span>
+            </>
+          )}
+        </div>
       </div>
       {busy ? (
         <Loader2 className="size-3 shrink-0 animate-spin text-muted-foreground" />
@@ -136,12 +196,22 @@ export function SshStatusSegment({
 }): React.JSX.Element | null {
   const sshConnectionStates = useAppStore((s) => s.sshConnectionStates)
   const sshTargetLabels = useAppStore((s) => s.sshTargetLabels)
+  const sshTargetRemoteSyncEnabled = useAppStore((s) => s.sshTargetRemoteSyncEnabled)
+  const remoteWorkspaceSyncStatusByTargetId = useAppStore(
+    (s) => s.remoteWorkspaceSyncStatusByTargetId
+  )
   const setActiveView = useAppStore((s) => s.setActiveView)
   const openSettingsTarget = useAppStore((s) => s.openSettingsTarget)
 
   const targets = Array.from(sshTargetLabels.entries()).map(([id, label]) => {
     const state = sshConnectionStates.get(id)
-    return { id, label, status: (state?.status ?? 'disconnected') as SshConnectionStatus }
+    return {
+      id,
+      label,
+      status: (state?.status ?? 'disconnected') as SshConnectionStatus,
+      syncEnabled: sshTargetRemoteSyncEnabled.get(id) === true,
+      syncStatus: remoteWorkspaceSyncStatusByTargetId[id]
+    }
   })
 
   if (targets.length === 0) {
@@ -151,6 +221,14 @@ export function SshStatusSegment({
   const statuses = targets.map((t) => t.status)
   const overall = overallStatus(statuses)
   const anyConnecting = overall === 'connecting'
+  const syncProblem = targets.find(
+    (t) => t.syncStatus?.phase === 'conflict' || t.syncStatus?.phase === 'error'
+  )
+  const syncProblemLabel = syncProblem
+    ? syncProblem.syncStatus?.phase === 'conflict'
+      ? 'Workspace conflict'
+      : 'Workspace sync error'
+    : null
 
   return (
     <DropdownMenu>
@@ -162,8 +240,14 @@ export function SshStatusSegment({
         >
           {iconOnly ? (
             <span className="inline-flex items-center gap-1">
-              <span className={`inline-block size-2 rounded-full ${overallDotColor(overall)}`} />
-              {anyConnecting ? (
+              <span
+                className={`inline-block size-2 rounded-full ${
+                  syncProblem ? 'bg-destructive' : overallDotColor(overall)
+                }`}
+              />
+              {syncProblem ? (
+                <AlertTriangle className="size-3 text-destructive" />
+              ) : anyConnecting ? (
                 <Loader2 className="size-3 animate-spin text-muted-foreground" />
               ) : (
                 <MonitorSmartphone className="size-3 text-muted-foreground" />
@@ -171,7 +255,9 @@ export function SshStatusSegment({
             </span>
           ) : (
             <span className="inline-flex items-center gap-1.5">
-              {anyConnecting ? (
+              {syncProblem ? (
+                <AlertTriangle className="size-3 text-destructive" />
+              ) : anyConnecting ? (
                 <Loader2 className="size-3 animate-spin text-yellow-500" />
               ) : overall === 'connected' ? (
                 <Server className="size-3 text-emerald-500" />
@@ -182,10 +268,17 @@ export function SshStatusSegment({
               )}
               {!compact && (
                 <span className="text-[11px]">
-                  SSH <span className="text-muted-foreground">{overallLabel(overall)}</span>
+                  SSH{' '}
+                  <span className={syncProblem ? 'text-destructive' : 'text-muted-foreground'}>
+                    {syncProblemLabel ?? overallLabel(overall)}
+                  </span>
                 </span>
               )}
-              <span className={`inline-block size-1.5 rounded-full ${overallDotColor(overall)}`} />
+              <span
+                className={`inline-block size-1.5 rounded-full ${
+                  syncProblem ? 'bg-destructive' : overallDotColor(overall)
+                }`}
+              />
             </span>
           )}
         </button>
@@ -195,7 +288,14 @@ export function SshStatusSegment({
           SSH Connections
         </div>
         {targets.map((t) => (
-          <TargetRow key={t.id} targetId={t.id} label={t.label} status={t.status} />
+          <TargetRow
+            key={t.id}
+            targetId={t.id}
+            label={t.label}
+            status={t.status}
+            syncEnabled={t.syncEnabled}
+            syncStatus={t.syncStatus}
+          />
         ))}
         <DropdownMenuSeparator />
         <DropdownMenuItem
diff --git a/src/renderer/src/hooks/useComposerState.ts b/src/renderer/src/hooks/useComposerState.ts
index 3acdc7f96b4..0ab7b97f693 100644
--- a/src/renderer/src/hooks/useComposerState.ts
+++ b/src/renderer/src/hooks/useComposerState.ts
@@ -143,7 +143,7 @@ export type ComposerCardProps = {
   baseBranchLinkedPrNumber: number | null
   /** Absolute path of the selected repo, used by Start-from picker for SWR. */
   selectedRepoPath: string | null
-  /** True when the selected repo is a remote SSH repo; disables the PR tab in v1. */
+  /** True when the selected repo is a remote SSH repo. */
   selectedRepoIsRemote: boolean
   /** Transient inline hint shown next to the Start-from trigger after a repo
    *  switch resets a prior selection (e.g. "was PR #8778"). Null when none. */
@@ -286,7 +286,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     if (persistDraft && newWorkspaceDraft?.linkedIssue) {
       return newWorkspaceDraft.linkedIssue
     }
-    if (initialLinkedWorkItem?.type === 'issue') {
+    if (initialLinkedWorkItem?.type === 'issue' && !initialLinkedWorkItem.linearIdentifier) {
       return String(initialLinkedWorkItem.number)
     }
     return ''
@@ -420,20 +420,12 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       return
     }
     let cancelled = false
-    const target = getActiveRuntimeTarget(settings)
-    const request =
-      target.kind === 'environment'
-        ? callRuntimeRpc<{ owner: string; repo: string } | null>(
-            target,
-            'github.repoSlug',
-            { repo: selectedRepo.id },
-            { timeoutMs: 30_000 }
-          )
-        : (window.api.gh.repoSlug({ repoPath: selectedRepoPath }) as Promise<{
-            owner: string
-            repo: string
-          } | null>)
-    void request
+    void (
+      window.api.gh.repoSlug({ repoPath: selectedRepoPath, repoId }) as Promise<{
+        owner: string
+        repo: string
+      } | null>
+    )
       .then((result) => {
         if (cancelled) {
           return
@@ -448,7 +440,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [selectedRepo, selectedRepoPath, settings])
+  }, [repoId, selectedRepo, selectedRepoPath])
   const sparsePresetsForRepo = sparsePresetsByRepo[repoId]
   const sparsePresets = sparsePresetsForRepo ?? EMPTY_SPARSE_PRESETS
   const normalizedSparseDirectories = useMemo(
@@ -755,13 +747,13 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
 
   // Why: warm the Start-from picker's PR cache on composer mount and whenever
   // the selected repo changes so opening the picker paints instantly from
-  // cache. Local repos only — remote SSH repos disable the PR tab in v1.
+  // cache.
   useEffect(() => {
-    if (!selectedRepo?.path || selectedRepo.connectionId) {
+    if (!selectedRepo?.path) {
       return
     }
     prefetchWorkItems(selectedRepo.id, selectedRepo.path, PER_REPO_FETCH_LIMIT, 'is:pr is:open')
-  }, [prefetchWorkItems, selectedRepo?.connectionId, selectedRepo?.id, selectedRepo?.path])
+  }, [prefetchWorkItems, selectedRepo?.id, selectedRepo?.path])
 
   // Reset setup decision when config / policy changes.
   useEffect(() => {
@@ -795,17 +787,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     setLinkItemsLoading(true)
 
     const lookupRepoId = selectedRepo.id
-    const target = getActiveRuntimeTarget(settings)
-    const request =
-      target.kind === 'environment'
-        ? callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.listWorkItems>>>(
-            target,
-            'github.listWorkItems',
-            { repo: selectedRepo.id, limit: 100 },
-            { timeoutMs: 30_000 }
-          )
-        : window.api.gh.listWorkItems({ repoPath: selectedRepo.path, limit: 100 })
-    void request
+    void window.api.gh
+      .listWorkItems({ repoPath: selectedRepo.path, repoId: selectedRepo.id, limit: 100 })
       .then((envelope) => {
         if (!cancelled) {
           // Why: IPC payload omits repoId — stamp it here from the repo we
@@ -852,7 +835,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [linkPopoverOpen, selectedRepo, settings])
+  }, [linkPopoverOpen, selectedRepo])
 
   useEffect(() => {
     if (!linkPopoverOpen || !selectedRepo || normalizedLinkQuery.directNumber === null) {
@@ -868,20 +851,12 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     // resolving direct lookups against the selected repo instead of requiring a
     // text match in the recent-items list.
     const lookupRepoId = selectedRepo.id
-    const target = getActiveRuntimeTarget(settings)
-    const request =
-      target.kind === 'environment'
-        ? callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.workItem>>>(
-            target,
-            'github.workItem',
-            { repo: selectedRepo.id, number: normalizedLinkQuery.directNumber },
-            { timeoutMs: 30_000 }
-          )
-        : window.api.gh.workItem({
-            repoPath: selectedRepo.path,
-            number: normalizedLinkQuery.directNumber
-          })
-    void request
+    void window.api.gh
+      .workItem({
+        repoPath: selectedRepo.path,
+        repoId: selectedRepo.id,
+        number: normalizedLinkQuery.directNumber
+      })
       .then((item) => {
         if (!cancelled) {
           setLinkDirectItem(
@@ -903,7 +878,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [linkPopoverOpen, normalizedLinkQuery.directNumber, selectedRepo, settings])
+  }, [linkPopoverOpen, normalizedLinkQuery.directNumber, selectedRepo])
 
   const applyLinkedWorkItem = useCallback(
     (item: GitHubWorkItem): void => {
@@ -1551,6 +1526,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
             : await ensureHooksConfirmed(useAppStore.getState(), repoId, 'issueCommand')
       }
 
+      const linkedLinearIssue = linkedWorkItem?.linearIdentifier
       const result = await createWorktree(
         repoId,
         workspaceName,
@@ -1567,7 +1543,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         parsedLinkedIssueNumber ?? undefined,
         effectiveLinkedPR ?? undefined,
         pushTarget,
-        tuiAgent
+        tuiAgent,
+        linkedLinearIssue
       )
       const worktree = result.worktree
 
@@ -1652,6 +1629,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     effectiveLinkedPR,
     linkedGitLabIssue,
     linkedGitLabMR,
+    linkedWorkItem?.linearIdentifier,
     linkedWorkItem?.title,
     linkedWorkItem?.url,
     normalizedSparseDirectories,
@@ -1711,6 +1689,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
             ? 'skip'
             : ((resolvedSetupDecision ?? 'inherit') as SetupDecision)
 
+        const linkedLinearIssue = linkedWorkItem?.linearIdentifier
         const result = await createWorktree(
           repoId,
           workspaceName,
@@ -1727,7 +1706,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
           parsedLinkedIssueNumber ?? undefined,
           effectiveLinkedPR ?? undefined,
           pushTarget,
-          agent ?? undefined
+          agent ?? undefined,
+          linkedLinearIssue
         )
         const worktree = result.worktree
 
diff --git a/src/renderer/src/hooks/useIpcEvents.test.ts b/src/renderer/src/hooks/useIpcEvents.test.ts
index f5d927fe68f..b73359289de 100644
--- a/src/renderer/src/hooks/useIpcEvents.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents.test.ts
@@ -1696,6 +1696,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
     onSet: (cb: (data: AgentStatusSetData) => void) => () => void
     getSnapshot?: () => Promise<AgentStatusSetData[]>
     drop?: (paneKey: string) => void
+    remoteWorkspace?: Record<string, unknown>
   }): Record<string, unknown> {
     return {
       api: {
@@ -1785,7 +1786,8 @@ describe('useIpcEvents agent status snapshot integration', () => {
           onSet: args.onSet,
           getSnapshot: args.getSnapshot ?? vi.fn(() => Promise.resolve([])),
           drop: args.drop ?? vi.fn()
-        }
+        },
+        remoteWorkspace: args.remoteWorkspace
       }
     }
   }
@@ -2023,6 +2025,103 @@ describe('useIpcEvents agent status snapshot integration', () => {
     expect(setAgentStatus).not.toHaveBeenCalled()
   })
 
+  it('waits for the remote workspace client id before dropping self notifications', async () => {
+    const hydrateWorkspaceSession = vi.fn()
+    const hydrateTabsSession = vi.fn()
+    const hydrateEditorSession = vi.fn()
+    const hydrateBrowserSession = vi.fn()
+    let resolveClientId!: (id: string) => void
+    const clientId = new Promise<string>((resolve) => {
+      resolveClientId = resolve
+    })
+    const onChangedListenerRef: {
+      current:
+        | ((event: {
+            targetId: string
+            sourceClientId?: string
+            snapshot: Record<string, unknown>
+          }) => void)
+        | null
+    } = { current: null }
+    const storeState: StoreLike = buildStoreState({
+      workspaceSessionReady: true,
+      repos: [{ id: 'repo-1', connectionId: 'conn-1' }],
+      worktreesByRepo: { 'repo-1': [{ id: 'repo-1::/repo', repoId: 'repo-1' }] },
+      hydrateWorkspaceSession,
+      hydrateTabsSession,
+      hydrateEditorSession,
+      hydrateBrowserSession,
+      markRemoteWorkspaceHydrated: vi.fn(),
+      setRemoteWorkspaceSyncStatus: vi.fn(),
+      reconnectPersistedTerminals: vi.fn(() => Promise.resolve())
+    })
+
+    stubReactSyncEffect()
+    vi.doMock('../store', () => ({
+      useAppStore: {
+        subscribe: vi.fn(() => () => {}),
+        getState: () => storeState
+      }
+    }))
+    stubAuxiliaryModules()
+    vi.stubGlobal(
+      'window',
+      buildWindowApi({
+        onSet: () => () => {},
+        remoteWorkspace: {
+          clientId: () => clientId,
+          onChanged: (cb: typeof onChangedListenerRef.current) => {
+            onChangedListenerRef.current = cb
+            return () => {}
+          }
+        }
+      })
+    )
+
+    const { useIpcEvents } = await import('./useIpcEvents')
+
+    useIpcEvents()
+    await Promise.resolve()
+
+    onChangedListenerRef.current?.({
+      targetId: 'conn-1',
+      sourceClientId: 'client-self',
+      snapshot: {
+        revision: 1,
+        updatedAt: Date.now(),
+        session: {
+          activeWorktreePath: '/repo',
+          activeTabId: 'tab-1',
+          tabsByWorktreePath: {
+            '/repo': [
+              {
+                id: 'tab-1',
+                ptyId: null,
+                worktreePath: '/repo',
+                title: 'Remote',
+                customTitle: null,
+                color: null,
+                sortOrder: 1,
+                createdAt: 1
+              }
+            ]
+          },
+          terminalLayoutsByTabId: {}
+        }
+      }
+    })
+    await Promise.resolve()
+    expect(hydrateWorkspaceSession).not.toHaveBeenCalled()
+
+    resolveClientId('client-self')
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(hydrateWorkspaceSession).not.toHaveBeenCalled()
+    expect(hydrateTabsSession).not.toHaveBeenCalled()
+    expect(hydrateEditorSession).not.toHaveBeenCalled()
+    expect(hydrateBrowserSession).not.toHaveBeenCalled()
+  })
+
   it('silently discards snapshot entries whose tabs are still unknown', async () => {
     const setAgentStatus = vi.fn()
     const getSnapshot = vi.fn(() =>
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index fdeedcf3608..6f1d69bc90f 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -9,10 +9,15 @@ import { SPLIT_TERMINAL_PANE_EVENT, CLOSE_TERMINAL_PANE_EVENT } from '@/constant
 import type { SplitTerminalPaneDetail, CloseTerminalPaneDetail } from '@/constants/terminal'
 import { getVisibleWorktreeIds } from '@/components/sidebar/visible-worktrees'
 import { nextEditorFontZoomLevel, computeEditorFontSize } from '@/lib/editor-font-zoom'
-import type { UpdateStatus } from '../../../shared/types'
+import type { UpdateStatus, WorkspaceSessionState } from '../../../shared/types'
+import type {
+  RemoteWorkspacePatchResult,
+  RemoteWorkspaceSnapshot
+} from '../../../shared/remote-workspace-types'
 import type { RateLimitState } from '../../../shared/rate-limit-types'
 import type { SshConnectionState } from '../../../shared/ssh-types'
 import type { RuntimeTerminalDriverState } from '../../../shared/runtime-types'
+import { importRemoteWorkspaceSession } from '../../../shared/remote-workspace-session-projection'
 import { zoomLevelToPercent, ZOOM_MIN, ZOOM_MAX } from '@/components/settings/SettingsConstants'
 import { dispatchZoomLevelChanged } from '@/lib/zoom-events'
 import { resolveZoomTarget } from './resolve-zoom-target'
@@ -38,10 +43,276 @@ import { parsePaneKey } from '../../../shared/stable-pane-id'
 import { collectLeafIdsInOrder } from '@/components/terminal-pane/layout-serialization'
 import { track } from '@/lib/telemetry'
 import { singlePaneLayoutSnapshot } from '@/store/slices/terminal-helpers'
+import { buildWorkspaceSessionPayload } from '@/lib/workspace-session'
 
 export { resolveZoomTarget } from './resolve-zoom-target'
 
 const ZOOM_STEP = 0.5
+let remoteWorkspaceSnapshotApplyDepth = 0
+let remoteWorkspaceSnapshotWriteSuppressUntil = 0
+const REMOTE_WORKSPACE_SNAPSHOT_WRITE_SUPPRESS_MS = 1000
+
+export function isRemoteWorkspaceSnapshotApplyInProgress(): boolean {
+  return (
+    remoteWorkspaceSnapshotApplyDepth > 0 || Date.now() < remoteWorkspaceSnapshotWriteSuppressUntil
+  )
+}
+
+async function waitForWorkspaceSessionReady(): Promise<boolean> {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (useAppStore.getState().workspaceSessionReady) {
+      return true
+    }
+    await new Promise((resolve) => window.setTimeout(resolve, 100))
+  }
+  return useAppStore.getState().workspaceSessionReady
+}
+
+async function prepareRemoteWorkspaceTarget(targetId: string): Promise<boolean> {
+  if (!(await waitForWorkspaceSessionReady())) {
+    return false
+  }
+  const store = useAppStore.getState()
+  let repos = store.repos.filter((repo) => repo.connectionId === targetId)
+  if (repos.length === 0) {
+    await store.fetchRepos()
+    repos = useAppStore.getState().repos.filter((repo) => repo.connectionId === targetId)
+  }
+  await Promise.all(repos.map((repo) => useAppStore.getState().fetchWorktrees(repo.id)))
+  return true
+}
+
+function targetRepoIds(targetId: string): Set<string> {
+  return new Set(
+    useAppStore
+      .getState()
+      .repos.filter((repo) => repo.connectionId === targetId)
+      .map((repo) => repo.id)
+  )
+}
+
+function targetWorktreeIds(targetId: string): Set<string> {
+  const repoIds = targetRepoIds(targetId)
+  return new Set(
+    Object.values(useAppStore.getState().worktreesByRepo)
+      .flat()
+      .filter((worktree) => repoIds.has(worktree.repoId))
+      .map((worktree) => worktree.id)
+  )
+}
+
+function mergeRemoteWorkspaceSession(
+  current: WorkspaceSessionState,
+  remote: WorkspaceSessionState,
+  targetId: string
+): WorkspaceSessionState {
+  const replaceWorktreeIds = targetWorktreeIds(targetId)
+  const remoteTabIds = new Set(
+    Object.values(remote.tabsByWorktree)
+      .flat()
+      .map((tab) => tab.id)
+  )
+  const replacedTabIds = new Set([
+    ...remoteTabIds,
+    ...Object.entries(current.tabsByWorktree)
+      .filter(([worktreeId]) => replaceWorktreeIds.has(worktreeId))
+      .flatMap(([, tabs]) => tabs.map((tab) => tab.id))
+  ])
+  const omitTargetWorktrees = <T>(record: Record<string, T> | undefined): Record<string, T> =>
+    Object.fromEntries(
+      Object.entries(record ?? {}).filter(([worktreeId]) => !replaceWorktreeIds.has(worktreeId))
+    )
+
+  return {
+    ...current,
+    activeRepoId:
+      remote.activeRepoId ??
+      (current.activeWorktreeId && replaceWorktreeIds.has(current.activeWorktreeId)
+        ? null
+        : current.activeRepoId),
+    activeWorktreeId:
+      remote.activeWorktreeId ??
+      (current.activeWorktreeId && replaceWorktreeIds.has(current.activeWorktreeId)
+        ? null
+        : current.activeWorktreeId),
+    activeTabId:
+      remote.activeTabId ??
+      (current.activeTabId && replacedTabIds.has(current.activeTabId) ? null : current.activeTabId),
+    tabsByWorktree: {
+      ...omitTargetWorktrees(current.tabsByWorktree),
+      ...remote.tabsByWorktree
+    },
+    terminalLayoutsByTabId: {
+      ...Object.fromEntries(
+        Object.entries(current.terminalLayoutsByTabId).filter(
+          ([tabId]) => !replacedTabIds.has(tabId)
+        )
+      ),
+      ...remote.terminalLayoutsByTabId
+    },
+    activeWorktreeIdsOnShutdown: [
+      ...(current.activeWorktreeIdsOnShutdown ?? []).filter((id) => !replaceWorktreeIds.has(id)),
+      ...(remote.activeWorktreeIdsOnShutdown ?? [])
+    ],
+    activeTabIdByWorktree: {
+      ...omitTargetWorktrees(current.activeTabIdByWorktree),
+      ...remote.activeTabIdByWorktree
+    },
+    remoteSessionIdsByTabId: {
+      ...Object.fromEntries(
+        Object.entries(current.remoteSessionIdsByTabId ?? {}).filter(
+          ([tabId]) => !replacedTabIds.has(tabId)
+        )
+      ),
+      ...remote.remoteSessionIdsByTabId
+    },
+    lastVisitedAtByWorktreeId: {
+      ...omitTargetWorktrees(current.lastVisitedAtByWorktreeId),
+      ...remote.lastVisitedAtByWorktreeId
+    }
+  }
+}
+
+async function applyRemoteWorkspaceSnapshot(
+  targetId: string,
+  snapshot: RemoteWorkspaceSnapshot
+): Promise<void> {
+  if (!(await prepareRemoteWorkspaceTarget(targetId))) {
+    throw new Error('Workspace sync waited for local session hydration and timed out')
+  }
+  const worktreeIds = targetWorktreeIds(targetId)
+  const localByPath = new Map(
+    Array.from(worktreeIds).map((worktreeId) => {
+      const separator = worktreeId.indexOf('::')
+      return [separator === -1 ? worktreeId : worktreeId.slice(separator + 2), worktreeId] as const
+    })
+  )
+  const remoteSession = importRemoteWorkspaceSession(snapshot.session, {
+    resolveWorktreeId: (worktreePath) => localByPath.get(worktreePath) ?? null
+  })
+  const current = buildWorkspaceSessionPayload(useAppStore.getState())
+  const merged = mergeRemoteWorkspaceSession(current, remoteSession, targetId)
+  const store = useAppStore.getState()
+  remoteWorkspaceSnapshotApplyDepth += 1
+  try {
+    store.hydrateWorkspaceSession(merged)
+    store.hydrateTabsSession(merged)
+    store.hydrateEditorSession(merged)
+    store.hydrateBrowserSession(merged)
+    store.markRemoteWorkspaceHydrated(targetId)
+    store.setRemoteWorkspaceSyncStatus(targetId, {
+      phase: 'synced',
+      direction: 'pull',
+      revision: snapshot.revision,
+      updatedAt: snapshot.updatedAt,
+      lastSyncedAt: Date.now(),
+      message: 'Workspace synced'
+    })
+    await useAppStore.getState().reconnectPersistedTerminals()
+  } finally {
+    // Why: remote terminal reattach can update pty ids and titles just after
+    // hydration. Those local side effects came from the remote snapshot and
+    // must not echo back as a fresh workspace revision.
+    remoteWorkspaceSnapshotWriteSuppressUntil =
+      Date.now() + REMOTE_WORKSPACE_SNAPSHOT_WRITE_SUPPRESS_MS
+    remoteWorkspaceSnapshotApplyDepth -= 1
+  }
+}
+
+async function syncRemoteWorkspaceAfterConnect(targetId: string): Promise<void> {
+  const store = useAppStore.getState()
+  if (store.sshTargetRemoteSyncEnabled.get(targetId) !== true) {
+    return
+  }
+  if (!(await prepareRemoteWorkspaceTarget(targetId))) {
+    store.setRemoteWorkspaceSyncStatus(targetId, {
+      phase: 'error',
+      direction: 'pull',
+      message: 'Workspace sync waited for local session hydration and timed out'
+    })
+    return
+  }
+  store.setRemoteWorkspaceSyncStatus(targetId, { phase: 'pulling', direction: 'pull' })
+  const worktreeIds = targetWorktreeIds(targetId)
+  const hasLocalTabs = Array.from(worktreeIds).some(
+    (worktreeId) => (useAppStore.getState().tabsByWorktree[worktreeId] ?? []).length > 0
+  )
+  const snapshot = await window.api.remoteWorkspace.get({ targetId })
+  if (!snapshot) {
+    useAppStore.getState().setRemoteWorkspaceSyncStatus(targetId, {
+      phase: 'offline',
+      direction: 'pull',
+      message: 'Remote workspace sync unavailable'
+    })
+    return
+  }
+  if (snapshot.revision > 0) {
+    await applyRemoteWorkspaceSnapshot(targetId, snapshot)
+    return
+  }
+
+  useAppStore.getState().markRemoteWorkspaceHydrated(targetId)
+  if (hasLocalTabs) {
+    // Why: first connect must read the relay before publishing local tabs.
+    // Otherwise a reconnecting device can overwrite a newer cross-device
+    // workspace snapshot with stale local renderer state.
+    const session = buildWorkspaceSessionPayload(useAppStore.getState())
+    const results = await window.api.remoteWorkspace.setForConnectedTargets({
+      session,
+      hydratedTargetIds: [targetId]
+    })
+    const result = results.find((entry) => entry.targetId === targetId)?.result
+    applyRemoteWorkspacePatchStatus(targetId, result)
+    if (result?.ok) {
+      useAppStore.getState().markRemoteWorkspaceHydrated(targetId)
+    }
+    return
+  }
+  useAppStore.getState().setRemoteWorkspaceSyncStatus(targetId, {
+    phase: 'idle',
+    revision: snapshot.revision,
+    updatedAt: snapshot.updatedAt,
+    message: 'No remote workspace yet'
+  })
+}
+
+function applyRemoteWorkspacePatchStatus(
+  targetId: string,
+  result: RemoteWorkspacePatchResult | undefined
+): void {
+  if (!result) {
+    useAppStore.getState().setRemoteWorkspaceSyncStatus(targetId, {
+      phase: 'offline',
+      direction: 'push',
+      lastSyncedAt: Date.now(),
+      message: 'Remote workspace sync unavailable'
+    })
+    return
+  }
+  if (result.ok) {
+    useAppStore.getState().setRemoteWorkspaceSyncStatus(targetId, {
+      phase: 'synced',
+      direction: 'push',
+      revision: result.snapshot.revision,
+      updatedAt: result.snapshot.updatedAt,
+      lastSyncedAt: Date.now(),
+      message: 'Workspace uploaded'
+    })
+    return
+  }
+  useAppStore.getState().setRemoteWorkspaceSyncStatus(targetId, {
+    phase: result.reason === 'stale-revision' ? 'conflict' : 'offline',
+    direction: 'push',
+    revision: result.snapshot?.revision,
+    updatedAt: result.snapshot?.updatedAt,
+    lastSyncedAt: Date.now(),
+    message:
+      result.message ??
+      (result.reason === 'stale-revision'
+        ? 'Workspace changed on another device'
+        : 'Remote workspace sync unavailable')
+  })
+}
 
 function isRuntimeEnvironmentActive(): boolean {
   return Boolean(useAppStore.getState().settings?.activeRuntimeEnvironmentId?.trim())
@@ -905,15 +1176,9 @@ export function useIpcEvents(): void {
     // reflect the correct connected/disconnected state on app launch.
     void (async () => {
       try {
-        const targets = (await window.api.ssh.listTargets()) as {
-          id: string
-          label: string
-        }[]
-        // Why: populate target labels map so WorktreeCard (and other components)
-        // can look up display labels without issuing per-card IPC calls.
-        const labels = new Map<string, string>()
+        const targets = await window.api.ssh.listTargets()
+        useAppStore.getState().setSshTargetsMetadata(targets)
         for (const target of targets) {
-          labels.set(target.id, target.label)
           const state = await window.api.ssh.getState({ targetId: target.id })
           if (state) {
             useAppStore.getState().setSshConnectionState(target.id, state as SshConnectionState)
@@ -934,10 +1199,17 @@ export function useIpcEvents(): void {
                 useAppStore.getState().setPortForwards(target.id, forwards)
                 useAppStore.getState().setDetectedPorts(target.id, detected)
               }
+              if (target.remoteWorkspaceSyncEnabled) {
+                void syncRemoteWorkspaceAfterConnect(target.id).catch((err) => {
+                  useAppStore.getState().setRemoteWorkspaceSyncStatus(target.id, {
+                    phase: 'error',
+                    message: err instanceof Error ? err.message : 'Workspace sync failed'
+                  })
+                })
+              }
             }
           }
         }
-        useAppStore.getState().setSshTargetLabels(labels)
       } catch {
         // SSH may not be configured
       }
@@ -980,11 +1252,7 @@ export function useIpcEvents(): void {
           window.api.ssh
             .listTargets()
             .then((targets) => {
-              const labels = new Map<string, string>()
-              for (const t of targets as { id: string; label: string }[]) {
-                labels.set(t.id, t.label)
-              }
-              useAppStore.getState().setSshTargetLabels(labels)
+              useAppStore.getState().setSshTargetsMetadata(targets)
             })
             .catch(() => {})
         }
@@ -1054,11 +1322,59 @@ export function useIpcEvents(): void {
                 }))
               }
             }
+            void syncRemoteWorkspaceAfterConnect(data.targetId).catch((err) => {
+              useAppStore.getState().setRemoteWorkspaceSyncStatus(data.targetId, {
+                phase: 'error',
+                message: err instanceof Error ? err.message : 'Workspace sync failed'
+              })
+            })
           })
         }
       })
     )
 
+    let remoteWorkspaceClientId: string | null = null
+    let remoteWorkspaceClientIdPromise: Promise<string | null> | null = null
+    const getRemoteWorkspaceClientId = (): Promise<string | null> => {
+      const remoteWorkspace = window.api.remoteWorkspace
+      if (!remoteWorkspace) {
+        return Promise.resolve(null)
+      }
+      if (remoteWorkspaceClientId) {
+        return Promise.resolve(remoteWorkspaceClientId)
+      }
+      remoteWorkspaceClientIdPromise ??= remoteWorkspace
+        .clientId()
+        .then((id) => {
+          remoteWorkspaceClientId = id
+          return id
+        })
+        .catch(() => null)
+      return remoteWorkspaceClientIdPromise
+    }
+    if (window.api.remoteWorkspace) {
+      void getRemoteWorkspaceClientId()
+      unsubs.push(
+        window.api.remoteWorkspace.onChanged((event) => {
+          void (async () => {
+            // Why: relay notifications can race the initial client-id IPC.
+            // Self-originated writes must never bounce back into restore.
+            const clientId = await getRemoteWorkspaceClientId()
+            if (event.sourceClientId && clientId && event.sourceClientId === clientId) {
+              return
+            }
+            await applyRemoteWorkspaceSnapshot(event.targetId, event.snapshot).catch((err) => {
+              useAppStore.getState().setRemoteWorkspaceSyncStatus(event.targetId, {
+                phase: 'error',
+                revision: event.snapshot.revision,
+                message: err instanceof Error ? err.message : 'Failed to apply remote workspace'
+              })
+            })
+          })()
+        })
+      )
+    }
+
     // Zoom handling for menu accelerators and keyboard fallback paths.
     unsubs.push(
       window.api.ui.onTerminalZoom((direction) => {
diff --git a/src/renderer/src/hooks/useIssueMetadata.ts b/src/renderer/src/hooks/useIssueMetadata.ts
index 93a1434a5f5..a7ce4531c3e 100644
--- a/src/renderer/src/hooks/useIssueMetadata.ts
+++ b/src/renderer/src/hooks/useIssueMetadata.ts
@@ -1,7 +1,7 @@
 /* eslint-disable max-lines -- Why: repo metadata hooks share TTL caches and
 Linear/GitHub cache invalidation entrypoints used by the issue dialog. */
 import { useEffect, useRef, useState } from 'react'
-import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import { getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import {
   linearTeamLabels,
   linearTeamMembers,
@@ -34,8 +34,7 @@ const ghAssigneeStore = createMetadataRequestStore<GitHubAssignableUser[]>()
 
 export function useRepoLabels(
   repoPath: string | null,
-  repoId?: string | null,
-  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+  repoId?: string | null
 ): MetadataState<string[]> {
   const [state, setState] = useState<MetadataState<string[]>>({
     data: [],
@@ -45,13 +44,10 @@ export function useRepoLabels(
   const activeKeyRef = useRef<string | null>(null)
 
   useEffect(() => {
-    const target = getActiveRuntimeTarget(settings)
-    if (!repoPath && !(target.kind === 'environment' && repoId)) {
+    if (!repoPath && !repoId) {
       return
     }
-    const cacheKey =
-      target.kind === 'environment' ? `runtime:${target.environmentId}:${repoId}` : (repoPath ?? '')
-
+    const cacheKey = repoId ?? repoPath ?? ''
     const cached = getFreshMetadata(ghLabelStore, cacheKey)
     if (cached) {
       if (activeKeyRef.current !== cacheKey) {
@@ -70,16 +66,9 @@ export function useRepoLabels(
       error: null
     }))
     loadMetadata(ghLabelStore, cacheKey, () =>
-      target.kind === 'environment'
-        ? callRuntimeRpc<string[]>(
-            target,
-            'github.listLabels',
-            { repo: repoId ?? '' },
-            { timeoutMs: 30_000 }
-          )
-        : window.api.gh
-            .listLabels({ repoPath: repoPath ?? '' })
-            .then((labels) => labels as string[])
+      window.api.gh
+        .listLabels({ repoPath: repoPath ?? '', repoId: repoId ?? undefined })
+        .then((labels) => labels as string[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -98,15 +87,14 @@ export function useRepoLabels(
           error: err instanceof Error ? err.message : 'Failed to load labels'
         }))
       })
-  }, [repoId, repoPath, settings])
+  }, [repoPath, repoId])
 
   return state
 }
 
 export function useRepoAssignees(
   repoPath: string | null,
-  repoId?: string | null,
-  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+  repoId?: string | null
 ): MetadataState<GitHubAssignableUser[]> {
   const [state, setState] = useState<MetadataState<GitHubAssignableUser[]>>({
     data: [],
@@ -116,13 +104,10 @@ export function useRepoAssignees(
   const activeKeyRef = useRef<string | null>(null)
 
   useEffect(() => {
-    const target = getActiveRuntimeTarget(settings)
-    if (!repoPath && !(target.kind === 'environment' && repoId)) {
+    if (!repoPath && !repoId) {
       return
     }
-    const cacheKey =
-      target.kind === 'environment' ? `runtime:${target.environmentId}:${repoId}` : (repoPath ?? '')
-
+    const cacheKey = repoId ?? repoPath ?? ''
     const cached = getFreshMetadata(ghAssigneeStore, cacheKey)
     if (cached) {
       if (activeKeyRef.current !== cacheKey) {
@@ -141,16 +126,9 @@ export function useRepoAssignees(
       error: null
     }))
     loadMetadata(ghAssigneeStore, cacheKey, () =>
-      target.kind === 'environment'
-        ? callRuntimeRpc<GitHubAssignableUser[]>(
-            target,
-            'github.listAssignableUsers',
-            { repo: repoId ?? '' },
-            { timeoutMs: 30_000 }
-          )
-        : window.api.gh
-            .listAssignableUsers({ repoPath: repoPath ?? '' })
-            .then((users) => users as GitHubAssignableUser[])
+      window.api.gh
+        .listAssignableUsers({ repoPath: repoPath ?? '', repoId: repoId ?? undefined })
+        .then((users) => users as GitHubAssignableUser[])
     )
       .then((data) => {
         if (activeKeyRef.current !== requestKey) {
@@ -169,7 +147,7 @@ export function useRepoAssignees(
           error: err instanceof Error ? err.message : 'Failed to load assignees'
         }))
       })
-  }, [repoId, repoPath, settings])
+  }, [repoPath, repoId])
 
   return state
 }
diff --git a/src/renderer/src/lib/launch-work-item-direct.ts b/src/renderer/src/lib/launch-work-item-direct.ts
index a297e508653..1914f8d7879 100644
--- a/src/renderer/src/lib/launch-work-item-direct.ts
+++ b/src/renderer/src/lib/launch-work-item-direct.ts
@@ -223,26 +223,13 @@ export async function launchWorkItemDirect(args: LaunchWorkItemDirectArgs): Prom
       telemetrySource,
       item.title,
       item.type === 'issue' && item.number ? item.number : undefined,
-      item.type === 'pr' && item.number ? item.number : undefined
+      item.type === 'pr' && item.number ? item.number : undefined,
+      undefined,
+      undefined,
+      item.linearIdentifier
     )
     worktreeId = result.worktree.id
     const worktreePath = result.worktree.path
-    const meta: {
-      linkedLinearIssue?: string
-    } = {}
-    if (item.linearIdentifier) {
-      meta.linkedLinearIssue = item.linearIdentifier
-    }
-    if (Object.keys(meta).length > 0) {
-      // Why: Project direct-launch activates the new workspace immediately.
-      // GitHub issue/PR links are persisted during create; Linear metadata
-      // still uses a best-effort follow-up because create args do not carry it.
-      // Best-effort: the worktree is already created on disk, so a meta
-      // write failure must not abort activation and orphan it.
-      void store.updateWorktreeMeta(worktreeId, meta).catch(() => {
-        // Non-critical: continue into activation without the link metadata.
-      })
-    }
 
     const detectedIds = new Set(await detectedAgentsPromise)
     effectiveAgent = pickAgent(settings?.defaultTuiAgent, detectedIds)
diff --git a/src/renderer/src/lib/new-workspace.ts b/src/renderer/src/lib/new-workspace.ts
index d15b28c05d6..583d0b5f9e3 100644
--- a/src/renderer/src/lib/new-workspace.ts
+++ b/src/renderer/src/lib/new-workspace.ts
@@ -49,6 +49,9 @@ export type LinkedWorkItemSummary = {
   number: number
   title: string
   url: string
+  /** Linear identifier (for example ENG-123) when this linked item came from
+   *  Linear rather than GitHub. */
+  linearIdentifier?: string
 }
 
 // Why: when a repo has no `orca.yaml` issueCommand and no per-user override,
diff --git a/src/renderer/src/lib/repo-slug-index.ts b/src/renderer/src/lib/repo-slug-index.ts
index 09028c370b2..530c5301ecb 100644
--- a/src/renderer/src/lib/repo-slug-index.ts
+++ b/src/renderer/src/lib/repo-slug-index.ts
@@ -1,7 +1,7 @@
 // Why: Project mode rows carry a GitHub `owner/repo` slug, but Orca's
 // `state.repos` stores only absolute paths. Before any repo-context action
 // (opening the item dialog in repo-backed mode, launching a worktree) can
-// dispatch correctly, we need a renderer-side index mapping slug → Repo.
+// dispatch correctly, we need a renderer-side index mapping slug → Repo[].
 //
 // The index is built lazily from `window.api.gh.repoSlug({ repoPath })` —
 // the main-process resolver that reads `git remote` and classifies the
@@ -19,11 +19,11 @@ import type { Repo } from '../../../shared/types'
 import type { GlobalSettings } from '../../../shared/types'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 
-/** Lowercased `owner/repo` → Repo. Case folded because GitHub treats slugs
+/** Lowercased `owner/repo` → Repo[]. Case folded because GitHub treats slugs
  *  case-insensitively but displays the canonical casing; the lookup side
  *  uses the row's `content.repository` which may or may not match the
  *  canonical casing depending on when the project item was indexed. */
-type SlugIndex = Map<string, Repo>
+type SlugIndex = Map<string, Repo[]>
 
 /** Module-scope cache keyed by runtime scope + repo.id. A Repo that has already failed
  *  resolution is not retried on re-mount; the value in the map is `null`
@@ -73,7 +73,7 @@ async function resolveRepoSlug(
             { repo: repo.id },
             { timeoutMs: 30_000 }
           )
-        : await window.api.gh.repoSlug({ repoPath: repo.path })
+        : await window.api.gh.repoSlug({ repoPath: repo.path, repoId: repo.id })
     if (!result) {
       slugByRepoId.set(cacheKey, null)
       return null
@@ -109,16 +109,16 @@ async function buildIndex(
   )
   for (const { repo, slug } of results) {
     if (slug) {
-      next.set(slug, repo)
+      next.set(slug, [...(next.get(slug) ?? []), repo])
     }
   }
   return next
 }
 
-/** Returns a lookup function `(slug) => Repo | null`. The lookup is stable
+/** Returns a lookup function `(slug) => Repo[]`. The lookup is stable
  *  across renders until `state.repos` changes; callers in deep trees can
  *  treat it as referentially equal inside a single render cycle. */
-export function useRepoSlugIndex(): (slug: string | null | undefined) => Repo | null {
+export function useRepoSlugIndex(): (slug: string | null | undefined) => Repo[] {
   const repos = useAppStore((s) => s.repos)
   const settings = useAppStore((s) => s.settings)
   const [index, setIndex] = useState<SlugIndex>(() => new Map())
@@ -138,11 +138,11 @@ export function useRepoSlugIndex(): (slug: string | null | undefined) => Repo |
 
   return useMemo(
     () =>
-      (slug: string | null | undefined): Repo | null => {
+      (slug: string | null | undefined): Repo[] => {
         if (!slug) {
-          return null
+          return []
         }
-        return index.get(slug.toLowerCase()) ?? null
+        return index.get(slug.toLowerCase()) ?? []
       },
     [index]
   )
diff --git a/src/renderer/src/lib/session-write-subscriber.test.ts b/src/renderer/src/lib/session-write-subscriber.test.ts
index 87f865fe2cc..1e6aad12010 100644
--- a/src/renderer/src/lib/session-write-subscriber.test.ts
+++ b/src/renderer/src/lib/session-write-subscriber.test.ts
@@ -112,6 +112,45 @@ describe('createSessionWriteSubscriber', () => {
     cleanup()
   })
 
+  it('updates its baseline without scheduling when shouldSchedulePersist returns false', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionState) => void>()
+    let shouldSchedule = false
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      shouldSchedulePersist: () => shouldSchedule
+    })
+
+    useAppStore.setState({ workspaceSessionReady: true, hydrationSucceeded: true })
+    vi.advanceTimersByTime(200)
+    expect(persist).not.toHaveBeenCalled()
+
+    shouldSchedule = true
+    useAppStore.setState({ activeTabId: 'tab-1' })
+    vi.advanceTimersByTime(200)
+    expect(persist).toHaveBeenCalledTimes(1)
+    cleanup()
+  })
+
+  it('cancels a pending debounce when shouldSchedulePersist returns false', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionState) => void>()
+    let shouldSchedule = true
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      shouldSchedulePersist: () => shouldSchedule
+    })
+
+    useAppStore.setState({ workspaceSessionReady: true })
+    vi.advanceTimersByTime(50)
+    shouldSchedule = false
+    useAppStore.setState({ activeTabId: 'remote-tab' })
+    vi.advanceTimersByTime(200)
+
+    expect(persist).not.toHaveBeenCalled()
+    cleanup()
+  })
+
   it('coalesces multiple relevant mutations within a debounce window', () => {
     const persist = vi.fn<(payload: WorkspaceSessionState) => void>()
     const cleanup = createSessionWriteSubscriber({ store: useAppStore, persist })
diff --git a/src/renderer/src/lib/session-write-subscriber.ts b/src/renderer/src/lib/session-write-subscriber.ts
index 56ad94ff806..58680e5b76c 100644
--- a/src/renderer/src/lib/session-write-subscriber.ts
+++ b/src/renderer/src/lib/session-write-subscriber.ts
@@ -12,6 +12,7 @@ export type SessionWriteSubscriberDeps = {
     getState: () => AppState
   }
   persist: (payload: WorkspaceSessionState) => void
+  shouldSchedulePersist?: () => boolean
   debounceMs?: number
 }
 
@@ -24,6 +25,7 @@ export type SessionWriteSubscriberDeps = {
 export function createSessionWriteSubscriber({
   store,
   persist,
+  shouldSchedulePersist,
   debounceMs = 150
 }: SessionWriteSubscriberDeps): () => void {
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -59,6 +61,13 @@ export function createSessionWriteSubscriber({
       next[key] = state[key]
     }
     prev = next
+    if (shouldSchedulePersist && !shouldSchedulePersist()) {
+      if (timer !== null) {
+        clearTimeout(timer)
+        timer = null
+      }
+      return
+    }
     if (timer !== null) {
       clearTimeout(timer)
     }
diff --git a/src/renderer/src/store/slices/github.test.ts b/src/renderer/src/store/slices/github.test.ts
index 6fbae94e642..8d06b7fb2d7 100644
--- a/src/renderer/src/store/slices/github.test.ts
+++ b/src/renderer/src/store/slices/github.test.ts
@@ -309,7 +309,7 @@ describe('createGitHubSlice.fetchWorkItems source/error envelope', () => {
 
     await store.getState().fetchWorkItems('repo-id', '/repo', 24, '')
 
-    const result = store.getState().getWorkItemsSourcesAndError('/repo', 24, '')
+    const result = store.getState().getWorkItemsSourcesAndError('repo-id', 24, '')
     expect(result.sources).toEqual({
       issues: { owner: 'up', repo: 'r' },
       prs: { owner: 'fork', repo: 'r' }
@@ -333,7 +333,7 @@ describe('createGitHubSlice.fetchWorkItems source/error envelope', () => {
 
     await store.getState().fetchWorkItems('repo-id', '/repo', 24, '')
 
-    const result = store.getState().getWorkItemsSourcesAndError('/repo', 24, '')
+    const result = store.getState().getWorkItemsSourcesAndError('repo-id', 24, '')
     expect(result.error).toMatchObject({
       type: 'permission_denied',
       message: 'no access',
@@ -369,11 +369,11 @@ describe('createGitHubSlice.fetchWorkItems source/error envelope', () => {
     await forcedFetch
 
     expect(mockApi.gh.listWorkItems).toHaveBeenCalledTimes(2)
-    const after = store.getState().getWorkItemsSourcesAndError('/repo', 24, '')
+    const after = store.getState().getWorkItemsSourcesAndError('repo-id', 24, '')
     expect(after.error).toBeNull()
   })
 
-  it('routes work item fetches through the active runtime environment', async () => {
+  it('routes work item fetches through repo-scoped IPC even when a runtime is active', async () => {
     const store = createTestStore()
     store.setState({
       settings: { activeRuntimeEnvironmentId: 'env-1' },
@@ -387,26 +387,21 @@ describe('createGitHubSlice.fetchWorkItems source/error envelope', () => {
         }
       ]
     } as Partial<AppState>)
-    runtimeEnvironmentCall.mockResolvedValueOnce({
-      id: 'rpc-1',
-      ok: true,
-      result: {
-        items: [{ type: 'issue', number: 7, title: 'Server issue', url: 'https://example.test/7' }],
-        sources: { issues: { owner: 'up', repo: 'r' }, prs: { owner: 'up', repo: 'r' } }
-      },
-      _meta: { runtimeId: 'remote-runtime' }
+    mockApi.gh.listWorkItems.mockResolvedValueOnce({
+      items: [{ type: 'issue', number: 7, title: 'Server issue', url: 'https://example.test/7' }],
+      sources: { issues: { owner: 'up', repo: 'r' }, prs: { owner: 'up', repo: 'r' } }
     })
 
     await store.getState().fetchWorkItems('repo-id', '/server/repo', 24, '')
 
-    expect(mockApi.gh.listWorkItems).not.toHaveBeenCalled()
-    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
-      selector: 'env-1',
-      method: 'github.listWorkItems',
-      params: { repo: 'repo-id', limit: 24, query: undefined },
-      timeoutMs: 30_000
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+    expect(mockApi.gh.listWorkItems).toHaveBeenCalledWith({
+      repoPath: '/server/repo',
+      repoId: 'repo-id',
+      limit: 24,
+      query: undefined
     })
-    expect(store.getState().workItemsCache['/server/repo::24::'].data?.[0]).toMatchObject({
+    expect(store.getState().workItemsCache['repo-id::24::'].data?.[0]).toMatchObject({
       repoId: 'repo-id',
       number: 7
     })
diff --git a/src/renderer/src/store/slices/github.ts b/src/renderer/src/store/slices/github.ts
index 4f007e839f1..73455f34bba 100644
--- a/src/renderer/src/store/slices/github.ts
+++ b/src/renderer/src/store/slices/github.ts
@@ -11,7 +11,6 @@ import type {
   IssueInfo,
   PRCheckDetail,
   PRComment,
-  Repo,
   Worktree,
   GitHubWorkItem
 } from '../../../../shared/types'
@@ -79,18 +78,6 @@ function queryOverrideKeyPart(queryOverride: string | undefined): string {
   return `:q=${queryOverride}`
 }
 
-function getRuntimeRepoTarget(
-  state: AppState,
-  repoPath: string
-): { target: { kind: 'environment'; environmentId: string }; repo: Repo } | null {
-  const target = getActiveRuntimeTarget(state.settings)
-  if (target.kind !== 'environment') {
-    return null
-  }
-  const repo = state.repos.find((candidate) => candidate.path === repoPath)
-  return repo ? { target, repo } : null
-}
-
 export function projectViewCacheKey(
   ownerType: GetProjectViewTableArgs['ownerType'],
   owner: string,
@@ -302,6 +289,10 @@ type FetchOptions = {
   force?: boolean
 }
 
+type RepoScopedFetchOptions = FetchOptions & {
+  repoId?: string
+}
+
 const CACHE_TTL = 300_000 // 5 minutes (stale data shown instantly, then refreshed)
 const CHECKS_CACHE_TTL = 60_000 // 1 minute — checks change more frequently
 // Why: the NewWorkspace page's work-item list is a browse surface, not a
@@ -356,8 +347,12 @@ function releaseWorkItemSlot(): void {
   workItemFetchInFlight -= 1
 }
 
-export function workItemsCacheKey(repoPath: string, limit: number, query: string): string {
-  return `${repoPath}::${limit}::${query}`
+export function workItemsCacheKey(repoId: string, limit: number, query: string): string {
+  return `${repoId}::${limit}::${query}`
+}
+
+function repoScopedCacheKey(repoPath: string, repoId: string | undefined, suffix: string): string {
+  return `${repoId ?? repoPath}::${suffix}`
 }
 
 // Why: 500 entries is generous enough that active developers will never hit it
@@ -414,33 +409,39 @@ export type GitHubSlice = {
   issueCache: Record<string, CacheEntry<IssueInfo>>
   checksCache: Record<string, CacheEntry<PRCheckDetail[]>>
   commentsCache: Record<string, CacheEntry<PRComment[]>>
-  // Why: keyed by repoPath + limit + query so the NewWorkspace page can render
+  // Why: keyed by repoId + limit + query so remote repos with the same path on
+  // different SSH targets do not share issue/PR results.
   // from cache instantly on mount (and on hover-prefetch from sidebar buttons)
   // while a background refresh keeps the list fresh.
   workItemsCache: Record<string, CacheEntry<GitHubWorkItem[]>>
   fetchPRForBranch: (
     repoPath: string,
     branch: string,
-    options?: FetchOptions & { linkedPRNumber?: number | null }
+    options?: RepoScopedFetchOptions & { linkedPRNumber?: number | null }
   ) => Promise<PRInfo | null>
-  fetchIssue: (repoPath: string, number: number) => Promise<IssueInfo | null>
+  fetchIssue: (
+    repoPath: string,
+    number: number,
+    options?: RepoScopedFetchOptions
+  ) => Promise<IssueInfo | null>
   fetchPRChecks: (
     repoPath: string,
     prNumber: number,
     branch?: string,
     headSha?: string,
-    options?: FetchOptions
+    options?: RepoScopedFetchOptions
   ) => Promise<PRCheckDetail[]>
   fetchPRComments: (
     repoPath: string,
     prNumber: number,
-    options?: FetchOptions
+    options?: RepoScopedFetchOptions
   ) => Promise<PRComment[]>
   resolveReviewThread: (
     repoPath: string,
     prNumber: number,
     threadId: string,
-    resolve: boolean
+    resolve: boolean,
+    options?: RepoScopedFetchOptions
   ) => Promise<boolean>
   initGitHubCache: () => Promise<void>
   refreshAllGitHub: () => void
@@ -451,7 +452,7 @@ export type GitHubSlice = {
    * background refresh when stale. Callers can render the cached list while
    * the SWR revalidate hydrates the latest.
    */
-  getCachedWorkItems: (repoPath: string, limit: number, query: string) => GitHubWorkItem[] | null
+  getCachedWorkItems: (repoId: string, limit: number, query: string) => GitHubWorkItem[] | null
   /**
    * Why: the Tasks view header reads sources from the cache to render the
    * "Issues from owner/repo" indicator, and the Tasks empty/partial banner
@@ -461,7 +462,7 @@ export type GitHubSlice = {
    * through the equality check.
    */
   getWorkItemsSourcesAndError: (
-    repoPath: string,
+    repoId: string,
     limit: number,
     query: string
   ) => { sources: WorkItemsCacheSources | null; error: WorkItemsCacheError | null }
@@ -480,7 +481,7 @@ export type GitHubSlice = {
    * mutated) on every write, so reference equality is preserved between
    * unchanged entries.
    */
-  getWorkItemsAnySourcesForRepo: (repoPath: string, limit: number) => WorkItemsCacheSources | null
+  getWorkItemsAnySourcesForRepo: (repoId: string, limit: number) => WorkItemsCacheSources | null
   fetchWorkItems: (
     repoId: string,
     repoPath: string,
@@ -518,7 +519,10 @@ export type GitHubSlice = {
    * Count total work items across repos using GitHub's search API.
    * Returns the sum of per-repo counts for the given query.
    */
-  countWorkItemsAcrossRepos: (repos: { path: string }[], query: string) => Promise<number>
+  countWorkItemsAcrossRepos: (
+    repos: { repoId: string; path: string }[],
+    query: string
+  ) => Promise<number>
   /**
    * Fire-and-forget prefetch used by UI entry points (hover/focus of the
    * "new workspace" buttons) to warm the cache before the page mounts.
@@ -537,9 +541,9 @@ export type GitHubSlice = {
   /**
    * Persist a per-repo issue-source preference, update the local Repo record
    * for reactive UI, and invalidate all cached work-items entries that key
-   * off this repo's path so the Tasks list re-fetches against the new source.
+   * off this repo's identity so the Tasks list re-fetches against the new source.
    *
-   * Why invalidate all `${repoPath}::*` keys and not only the primary entry:
+   * Why invalidate all `${repoId}::*` keys and not only the primary entry:
    * preferences flip the issue source for every list query (query-less +
    * user-entered queries alike). Surgical eviction of the primary key alone
    * would leave stale results in alternate-query cache lines.
@@ -1032,13 +1036,13 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     applyRowPatch(set, cacheKey, rowId, nextRow)
   },
 
-  getCachedWorkItems: (repoPath, limit, query) => {
-    const key = workItemsCacheKey(repoPath, limit, query)
+  getCachedWorkItems: (repoId, limit, query) => {
+    const key = workItemsCacheKey(repoId, limit, query)
     return get().workItemsCache[key]?.data ?? null
   },
 
-  getWorkItemsSourcesAndError: (repoPath, limit, query) => {
-    const key = workItemsCacheKey(repoPath, limit, query)
+  getWorkItemsSourcesAndError: (repoId, limit, query) => {
+    const key = workItemsCacheKey(repoId, limit, query)
     const entry = get().workItemsCache[key]
     return {
       sources: entry?.sources ?? null,
@@ -1046,14 +1050,14 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     }
   },
 
-  getWorkItemsAnySourcesForRepo: (repoPath, limit) => {
+  getWorkItemsAnySourcesForRepo: (repoId, limit) => {
     const cache = get().workItemsCache
-    const primaryKey = workItemsCacheKey(repoPath, limit, '')
+    const primaryKey = workItemsCacheKey(repoId, limit, '')
     const primary = cache[primaryKey]?.sources
     if (primary) {
       return primary
     }
-    const prefix = `${repoPath}::`
+    const prefix = `${repoId}::`
     for (const [key, entry] of Object.entries(cache)) {
       if (key.startsWith(prefix) && entry.sources) {
         return entry.sources
@@ -1063,7 +1067,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   fetchWorkItems: async (repoId, repoPath, limit, query, options): Promise<GitHubWorkItem[]> => {
-    const key = workItemsCacheKey(repoPath, limit, query)
+    const key = workItemsCacheKey(repoId, limit, query)
     const cached = get().workItemsCache[key]
     if (!options?.force && isFresh(cached, WORK_ITEMS_CACHE_TTL)) {
       return cached.data ?? []
@@ -1087,19 +1091,12 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const request = (async () => {
       await acquireWorkItemSlot()
       try {
-        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
-        const envelope = runtimeRepo
-          ? await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.listWorkItems>>>(
-              runtimeRepo.target,
-              'github.listWorkItems',
-              { repo: runtimeRepo.repo.id, limit, query: query || undefined },
-              { timeoutMs: 30_000 }
-            )
-          : await window.api.gh.listWorkItems({
-              repoPath,
-              limit,
-              query: query || undefined
-            })
+        const envelope = await window.api.gh.listWorkItems({
+          repoPath,
+          repoId,
+          limit,
+          query: query || undefined
+        })
         // Why: stamp repoId at the renderer fetch boundary so every downstream
         // consumer (cross-repo merge, row rendering, drawer) can rely on the
         // field being present. Main doesn't know Orca's Repo.id.
@@ -1168,7 +1165,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
           // nothing at all to contribute.
           // Why: must use perRepoLimit (not displayLimit) so the cache key
           // matches what fetchWorkItems wrote.
-          const key = workItemsCacheKey(r.path, perRepoLimit, query)
+          const key = workItemsCacheKey(r.repoId, perRepoLimit, query)
           const cached = get().workItemsCache[key]?.data
           if (cached) {
             console.warn(`[workItems] ${r.repoId} failed, serving cached:`, err)
@@ -1190,25 +1187,13 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       repos.map(async (r) => {
         await acquireWorkItemSlot()
         try {
-          const runtimeRepo = getRuntimeRepoTarget(get(), r.path)
-          const envelope = runtimeRepo
-            ? await callRuntimeRpc<Awaited<ReturnType<typeof window.api.gh.listWorkItems>>>(
-                runtimeRepo.target,
-                'github.listWorkItems',
-                {
-                  repo: runtimeRepo.repo.id,
-                  limit: perRepoLimit,
-                  query: query || undefined,
-                  before
-                },
-                { timeoutMs: 30_000 }
-              )
-            : await window.api.gh.listWorkItems({
-                repoPath: r.path,
-                limit: perRepoLimit,
-                query: query || undefined,
-                before
-              })
+          const envelope = await window.api.gh.listWorkItems({
+            repoPath: r.path,
+            repoId: r.repoId,
+            limit: perRepoLimit,
+            query: query || undefined,
+            before
+          })
           // Why: page-N partial failures don't participate in the cache's per-repo
           // error banner (which is keyed on the initial-fetch cache entry). Log the
           // classified issues-side error so pagination failures are at least
@@ -1240,18 +1225,11 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const counts = await Promise.all(
       repos.map(async (r) => {
         try {
-          const runtimeRepo = getRuntimeRepoTarget(get(), r.path)
-          return runtimeRepo
-            ? await callRuntimeRpc<number>(
-                runtimeRepo.target,
-                'github.countWorkItems',
-                { repo: runtimeRepo.repo.id, query: query || undefined },
-                { timeoutMs: 30_000 }
-              )
-            : await window.api.gh.countWorkItems({
-                repoPath: r.path,
-                query: query || undefined
-              })
+          return await window.api.gh.countWorkItems({
+            repoPath: r.path,
+            repoId: r.repoId,
+            query: query || undefined
+          })
         } catch {
           return 0
         }
@@ -1261,7 +1239,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   prefetchWorkItems: (repoId, repoPath, limit = PER_REPO_FETCH_LIMIT, query = '') => {
-    const key = workItemsCacheKey(repoPath, limit, query)
+    const key = workItemsCacheKey(repoId, limit, query)
     const cached = get().workItemsCache[key]
     // Skip when the cache is fresh or a request is already in flight.
     if (isFresh(cached, WORK_ITEMS_CACHE_TTL) || inflightWorkItemsRequests.has(key)) {
@@ -1287,7 +1265,8 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   fetchPRForBranch: async (repoPath, branch, options): Promise<PRInfo | null> => {
-    const cacheKey = `${repoPath}::${branch}`
+    const repoId = options?.repoId ?? get().repos?.find((repo) => repo.path === repoPath)?.id
+    const cacheKey = repoScopedCacheKey(repoPath, repoId, branch)
     const cached = get().prCache[cacheKey]
     // Why: if a prior caller without a linkedPR cached `null` for this branch,
     // the worktree-card lookup (which has a linked PR fallback) would otherwise
@@ -1309,15 +1288,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     const linkedPRNumber = options?.linkedPRNumber ?? null
     const request = (async () => {
       try {
-        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
-        const pr = runtimeRepo
-          ? await callRuntimeRpc<PRInfo | null>(
-              runtimeRepo.target,
-              'github.prForBranch',
-              { repo: runtimeRepo.repo.id, branch, linkedPRNumber },
-              { timeoutMs: 30_000 }
-            )
-          : await window.api.gh.prForBranch({ repoPath, branch, linkedPRNumber })
+        const pr = await window.api.gh.prForBranch({ repoPath, repoId, branch, linkedPRNumber })
         if (prRequestGenerations.get(cacheKey) === generation) {
           set((s) => ({
             prCache: { ...s.prCache, [cacheKey]: { data: pr, fetchedAt: Date.now() } }
@@ -1350,8 +1321,9 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     return request
   },
 
-  fetchIssue: async (repoPath, number) => {
-    const cacheKey = `${repoPath}::${number}`
+  fetchIssue: async (repoPath, number, options) => {
+    const repoId = options?.repoId ?? get().repos?.find((repo) => repo.path === repoPath)?.id
+    const cacheKey = repoScopedCacheKey(repoPath, repoId, String(number))
     const cached = get().issueCache[cacheKey]
     if (isFresh(cached)) {
       return cached.data
@@ -1364,15 +1336,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const request = (async () => {
       try {
-        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
-        const issue = runtimeRepo
-          ? await callRuntimeRpc<IssueInfo | null>(
-              runtimeRepo.target,
-              'github.issue',
-              { repo: runtimeRepo.repo.id, number },
-              { timeoutMs: 30_000 }
-            )
-          : await window.api.gh.issue({ repoPath, number })
+        const issue = await window.api.gh.issue({ repoPath, repoId, number })
         set((s) => ({
           issueCache: { ...s.issueCache, [cacheKey]: { data: issue, fetchedAt: Date.now() } }
         }))
@@ -1395,7 +1359,8 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   fetchPRChecks: async (repoPath, prNumber, branch, headSha, options): Promise<PRCheckDetail[]> => {
-    const cacheKey = `${repoPath}::pr-checks::${prNumber}`
+    const repoId = options?.repoId ?? get().repos?.find((repo) => repo.path === repoPath)?.id
+    const cacheKey = repoScopedCacheKey(repoPath, repoId, `pr-checks::${prNumber}`)
     const cached = get().checksCache[cacheKey]
     if (!options?.force && isFresh(cached, CHECKS_CACHE_TTL)) {
       const cachedChecks = cached.data ?? []
@@ -1414,20 +1379,13 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const request = (async () => {
       try {
-        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
-        const checks = runtimeRepo
-          ? await callRuntimeRpc<PRCheckDetail[]>(
-              runtimeRepo.target,
-              'github.prChecks',
-              { repo: runtimeRepo.repo.id, prNumber, headSha, noCache: options?.force },
-              { timeoutMs: 30_000 }
-            )
-          : ((await window.api.gh.prChecks({
-              repoPath,
-              prNumber,
-              headSha,
-              noCache: options?.force
-            })) as PRCheckDetail[])
+        const checks = (await window.api.gh.prChecks({
+          repoPath,
+          repoId,
+          prNumber,
+          headSha,
+          noCache: options?.force
+        })) as PRCheckDetail[]
         set((s) => {
           const nextState: Partial<AppState> = {
             checksCache: { ...s.checksCache, [cacheKey]: { data: checks, fetchedAt: Date.now() } }
@@ -1455,7 +1413,8 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   },
 
   fetchPRComments: async (repoPath, prNumber, options): Promise<PRComment[]> => {
-    const cacheKey = `${repoPath}::pr-comments::${prNumber}`
+    const repoId = options?.repoId ?? get().repos?.find((repo) => repo.path === repoPath)?.id
+    const cacheKey = repoScopedCacheKey(repoPath, repoId, `pr-comments::${prNumber}`)
     const cached = get().commentsCache[cacheKey]
     if (!options?.force && isFresh(cached)) {
       return cached.data ?? []
@@ -1468,19 +1427,12 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const request = (async () => {
       try {
-        const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
-        const comments = runtimeRepo
-          ? await callRuntimeRpc<PRComment[]>(
-              runtimeRepo.target,
-              'github.prComments',
-              { repo: runtimeRepo.repo.id, prNumber, noCache: options?.force },
-              { timeoutMs: 30_000 }
-            )
-          : ((await window.api.gh.prComments({
-              repoPath,
-              prNumber,
-              noCache: options?.force
-            })) as PRComment[])
+        const comments = (await window.api.gh.prComments({
+          repoPath,
+          repoId,
+          prNumber,
+          noCache: options?.force
+        })) as PRComment[]
         set((s) => ({
           commentsCache: {
             ...s.commentsCache,
@@ -1500,8 +1452,9 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     return request
   },
 
-  resolveReviewThread: async (repoPath, prNumber, threadId, resolve) => {
-    const cacheKey = `${repoPath}::pr-comments::${prNumber}`
+  resolveReviewThread: async (repoPath, prNumber, threadId, resolve, options) => {
+    const repoId = options?.repoId ?? get().repos?.find((repo) => repo.path === repoPath)?.id
+    const cacheKey = repoScopedCacheKey(repoPath, repoId, `pr-comments::${prNumber}`)
 
     // Optimistic update: toggle isResolved on all comments in this thread immediately
     // so the UI feels instant. Reverts if the API call fails.
@@ -1518,15 +1471,7 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
       }))
     }
 
-    const runtimeRepo = getRuntimeRepoTarget(get(), repoPath)
-    const ok = runtimeRepo
-      ? await callRuntimeRpc<boolean>(
-          runtimeRepo.target,
-          'github.resolveReviewThread',
-          { repo: runtimeRepo.repo.id, threadId, resolve },
-          { timeoutMs: 30_000 }
-        )
-      : await window.api.gh.resolveReviewThread({ repoPath, threadId, resolve })
+    const ok = await window.api.gh.resolveReviewThread({ repoPath, repoId, threadId, resolve })
     if (!ok && prev) {
       // Revert optimistic update on failure
       set((s) => ({
@@ -1571,17 +1516,17 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
         const branch = wt.branch.replace(/^refs\/heads\//, '')
         if (!wt.isBare && branch) {
-          const prKey = `${repo.path}::${branch}`
+          const prKey = repoScopedCacheKey(repo.path, repo.id, branch)
           const prEntry = state.prCache[prKey]
           if (!prEntry || now - prEntry.fetchedAt >= CACHE_TTL) {
-            void get().fetchPRForBranch(repo.path, branch)
+            void get().fetchPRForBranch(repo.path, branch, { repoId: repo.id })
           }
         }
         if (wt.linkedIssue) {
-          const issueKey = `${repo.path}::${wt.linkedIssue}`
+          const issueKey = repoScopedCacheKey(repo.path, repo.id, String(wt.linkedIssue))
           const issueEntry = state.issueCache[issueKey]
           if (!issueEntry || now - issueEntry.fetchedAt >= CACHE_TTL) {
-            void get().fetchIssue(repo.path, wt.linkedIssue)
+            void get().fetchIssue(repo.path, wt.linkedIssue, { repoId: repo.id })
           }
         }
       }
@@ -1608,8 +1553,10 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     // Invalidate this worktree's cache entries
     const branch = worktree.branch.replace(/^refs\/heads\//, '')
-    const prKey = `${repo.path}::${branch}`
-    const issueKey = worktree.linkedIssue ? `${repo.path}::${worktree.linkedIssue}` : ''
+    const prKey = repoScopedCacheKey(repo.path, repo.id, branch)
+    const issueKey = worktree.linkedIssue
+      ? repoScopedCacheKey(repo.path, repo.id, String(worktree.linkedIssue))
+      : ''
 
     set((s) => {
       const updates: Partial<AppState> = {}
@@ -1627,10 +1574,10 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     // Re-fetch (skip when branch is empty — detached HEAD during rebase)
     if (!worktree.isBare && branch) {
-      void get().fetchPRForBranch(repo.path, branch, { force: true })
+      void get().fetchPRForBranch(repo.path, branch, { force: true, repoId: repo.id })
     }
     if (worktree.linkedIssue) {
-      void get().fetchIssue(repo.path, worktree.linkedIssue)
+      void get().fetchIssue(repo.path, worktree.linkedIssue, { repoId: repo.id })
     }
   },
 
@@ -1704,22 +1651,22 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
     // first makes the "new fetch gets a fresh request" invariant impossible
     // to trip on later refactors that change zustand or React flush timing.
     for (const key of Array.from(inflightWorkItemsRequests.keys())) {
-      if (key.startsWith(`${repoPath}::`)) {
+      if (key.startsWith(`${repoId}::`) || key.startsWith(`${repoPath}::`)) {
         inflightWorkItemsRequests.delete(key)
       }
     }
-    // Why: evict every cache entry keyed on this repo's path AFTER the IPC
+    // Why: evict every cache entry keyed on this repo AFTER the IPC
     // resolves. If we evicted before awaiting, an overlapping fetch triggered
     // by a different subscriber would hit main with the pre-flip persisted
     // preference and repopulate the cache with stale-source data. Work-items
-    // cache keys are `${repoPath}::${limit}::${query}` so we can't selectively
-    // invalidate by query — the preference change affects all queries against
-    // this repo.
+    // cache keys are repo-scoped, but we also drop legacy path-scoped entries
+    // that may have been restored from older persisted cache data.
     set((s) => {
-      const prefix = `${repoPath}::`
+      const prefix = `${repoId}::`
+      const legacyPrefix = `${repoPath}::`
       const next: Record<string, CacheEntry<GitHubWorkItem[]>> = {}
       for (const [key, entry] of Object.entries(s.workItemsCache)) {
-        if (!key.startsWith(prefix)) {
+        if (!key.startsWith(prefix) && !key.startsWith(legacyPrefix)) {
           next[key] = entry
         }
       }
@@ -1755,19 +1702,19 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
 
     const now = Date.now()
     const branch = worktree.branch.replace(/^refs\/heads\//, '')
-    const prKey = `${repo.path}::${branch}`
+    const prKey = repoScopedCacheKey(repo.path, repo.id, branch)
     const prEntry = state.prCache[prKey]
     const prStale = !prEntry || now - prEntry.fetchedAt >= CACHE_TTL
 
     if (!worktree.isBare && branch && prStale) {
-      void get().fetchPRForBranch(repo.path, branch, { force: true })
+      void get().fetchPRForBranch(repo.path, branch, { force: true, repoId: repo.id })
     }
 
     if (worktree.linkedIssue) {
-      const issueKey = `${repo.path}::${worktree.linkedIssue}`
+      const issueKey = repoScopedCacheKey(repo.path, repo.id, String(worktree.linkedIssue))
       const issueEntry = state.issueCache[issueKey]
       if (!issueEntry || now - issueEntry.fetchedAt >= CACHE_TTL) {
-        void get().fetchIssue(repo.path, worktree.linkedIssue)
+        void get().fetchIssue(repo.path, worktree.linkedIssue, { repoId: repo.id })
       }
     }
   }
diff --git a/src/renderer/src/store/slices/hosted-review.test.ts b/src/renderer/src/store/slices/hosted-review.test.ts
index 13466b0a19c..f8d16c7eaef 100644
--- a/src/renderer/src/store/slices/hosted-review.test.ts
+++ b/src/renderer/src/store/slices/hosted-review.test.ts
@@ -94,6 +94,7 @@ describe('hosted review slice', () => {
       'hostedReview.forBranch',
       {
         repo: 'C:\\repo',
+        repoPath: 'C:\\repo',
         branch: 'feature/windows',
         linkedGitHubPR: 12,
         linkedGitLabMR: null,
diff --git a/src/renderer/src/store/slices/hosted-review.ts b/src/renderer/src/store/slices/hosted-review.ts
index 1c86e9d1221..c50609a918e 100644
--- a/src/renderer/src/store/slices/hosted-review.ts
+++ b/src/renderer/src/store/slices/hosted-review.ts
@@ -5,7 +5,7 @@ import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-cl
 import type { AppState } from '../types'
 
 type CacheEntry<T> = { data: T | null; fetchedAt: number }
-type FetchOptions = { force?: boolean }
+type FetchOptions = { force?: boolean; repoId?: string }
 
 const CACHE_TTL_MS = 60_000
 
@@ -22,11 +22,12 @@ function isFresh<T>(entry: CacheEntry<T> | undefined): entry is CacheEntry<T> {
 export function getHostedReviewCacheKey(
   repoPath: string,
   branch: string,
-  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null
+  settings?: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null,
+  repoId?: string | null
 ): string {
   const target = getActiveRuntimeTarget(settings)
   const scope = target.kind === 'environment' ? `runtime:${target.environmentId}` : 'local'
-  return `${scope}::${repoPath}::${branch}`
+  return `${scope}::${repoId ?? repoPath}::${branch}`
 }
 
 export type HostedReviewSlice = {
@@ -56,7 +57,7 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
   ): Promise<HostedReviewInfo | null> => {
     const settings = get().settings
     const target = getActiveRuntimeTarget(settings)
-    const cacheKey = getHostedReviewCacheKey(repoPath, branch, settings)
+    const cacheKey = getHostedReviewCacheKey(repoPath, branch, settings, options?.repoId)
     const cached = get().hostedReviewCache[cacheKey]
     const linkedRefetch =
       cached?.data === null &&
@@ -80,6 +81,7 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
       try {
         const args = {
           branch,
+          ...(options?.repoId !== undefined ? { repoId: options.repoId } : {}),
           linkedGitHubPR: options?.linkedGitHubPR ?? null,
           linkedGitLabMR: options?.linkedGitLabMR ?? null,
           linkedBitbucketPR: options?.linkedBitbucketPR ?? null,
@@ -90,7 +92,7 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
             ? await callRuntimeRpc<HostedReviewInfo | null>(
                 target,
                 'hostedReview.forBranch',
-                { repo: repoPath, ...args },
+                { repo: options?.repoId ?? repoPath, repoPath, ...args },
                 // Why: remote dev boxes can be slower at `git`/`gh` lookups
                 // than local desktop repos, especially on Windows filesystem
                 // paths. The main-process queue caps concurrency, so a longer
diff --git a/src/renderer/src/store/slices/ssh.ts b/src/renderer/src/store/slices/ssh.ts
index 9078bd9da17..4fc773840d8 100644
--- a/src/renderer/src/store/slices/ssh.ts
+++ b/src/renderer/src/store/slices/ssh.ts
@@ -3,9 +3,19 @@ import type { AppState } from '../types'
 import type {
   SshConnectionState,
   PortForwardEntry,
-  DetectedPort
+  DetectedPort,
+  SshTarget
 } from '../../../../shared/ssh-types'
 
+export type RemoteWorkspaceSyncStatus = {
+  phase: 'idle' | 'pulling' | 'pushing' | 'synced' | 'conflict' | 'error' | 'offline'
+  direction?: 'pull' | 'push'
+  revision?: number
+  updatedAt?: number
+  lastSyncedAt?: number
+  message?: string
+}
+
 export type SshCredentialRequest = {
   requestId: string
   targetId: string
@@ -18,6 +28,9 @@ export type SshSlice = {
   /** Maps target IDs to their user-facing labels. Populated during hydration
    * so components can look up labels without per-component IPC calls. */
   sshTargetLabels: Map<string, string>
+  sshTargetRemoteSyncEnabled: Map<string, boolean>
+  remoteWorkspaceHydratedTargetIds: Set<string>
+  remoteWorkspaceSyncStatusByTargetId: Record<string, RemoteWorkspaceSyncStatus>
   sshCredentialQueue: SshCredentialRequest[]
   /** Incremented when an SSH target transitions to 'connected'. Allows
    * components like the file explorer to re-trigger data loads that failed
@@ -33,6 +46,12 @@ export type SshSlice = {
   detectedPortsByConnection: Record<string, DetectedPort[]>
   setSshConnectionState: (targetId: string, state: SshConnectionState) => void
   setSshTargetLabels: (labels: Map<string, string>) => void
+  setSshTargetsMetadata: (
+    targets: Pick<SshTarget, 'id' | 'label' | 'remoteWorkspaceSyncEnabled'>[]
+  ) => void
+  markRemoteWorkspaceHydrated: (targetId: string) => void
+  clearRemoteWorkspaceHydrated: (targetId: string) => void
+  setRemoteWorkspaceSyncStatus: (targetId: string, status: RemoteWorkspaceSyncStatus) => void
   enqueueSshCredentialRequest: (req: SshCredentialRequest) => void
   removeSshCredentialRequest: (requestId: string) => void
   bumpSshConnectedGeneration: () => void
@@ -44,6 +63,9 @@ export type SshSlice = {
 export const createSshSlice: StateCreator<AppState, [], [], SshSlice> = (set) => ({
   sshConnectionStates: new Map(),
   sshTargetLabels: new Map(),
+  sshTargetRemoteSyncEnabled: new Map(),
+  remoteWorkspaceHydratedTargetIds: new Set(),
+  remoteWorkspaceSyncStatusByTargetId: {},
   sshCredentialQueue: [],
   sshConnectedGeneration: 0,
   portForwardsByConnection: {},
@@ -57,6 +79,32 @@ export const createSshSlice: StateCreator<AppState, [], [], SshSlice> = (set) =>
     }),
 
   setSshTargetLabels: (labels) => set({ sshTargetLabels: labels }),
+  setSshTargetsMetadata: (targets) =>
+    set({
+      sshTargetLabels: new Map(targets.map((target) => [target.id, target.label])),
+      sshTargetRemoteSyncEnabled: new Map(
+        targets.map((target) => [target.id, target.remoteWorkspaceSyncEnabled === true])
+      )
+    }),
+  markRemoteWorkspaceHydrated: (targetId) =>
+    set((s) => {
+      const next = new Set(s.remoteWorkspaceHydratedTargetIds)
+      next.add(targetId)
+      return { remoteWorkspaceHydratedTargetIds: next }
+    }),
+  clearRemoteWorkspaceHydrated: (targetId) =>
+    set((s) => {
+      const next = new Set(s.remoteWorkspaceHydratedTargetIds)
+      next.delete(targetId)
+      return { remoteWorkspaceHydratedTargetIds: next }
+    }),
+  setRemoteWorkspaceSyncStatus: (targetId, status) =>
+    set((s) => ({
+      remoteWorkspaceSyncStatusByTargetId: {
+        ...s.remoteWorkspaceSyncStatusByTargetId,
+        [targetId]: status
+      }
+    })),
   enqueueSshCredentialRequest: (req) =>
     set((s) => ({ sshCredentialQueue: [...s.sshCredentialQueue, req] })),
   removeSshCredentialRequest: (requestId) =>
diff --git a/src/renderer/src/store/slices/worktree-helpers.ts b/src/renderer/src/store/slices/worktree-helpers.ts
index 1c76c8a38fd..508daa7e65d 100644
--- a/src/renderer/src/store/slices/worktree-helpers.ts
+++ b/src/renderer/src/store/slices/worktree-helpers.ts
@@ -76,7 +76,8 @@ export type WorktreeSlice = {
     linkedIssue?: number,
     linkedPR?: number,
     pushTarget?: GitPushTarget,
-    createdWithAgent?: TuiAgent
+    createdWithAgent?: TuiAgent,
+    linkedLinearIssue?: string
   ) => Promise<CreateWorktreeResult>
   removeWorktree: (
     worktreeId: string,
diff --git a/src/renderer/src/store/slices/worktrees.test.ts b/src/renderer/src/store/slices/worktrees.test.ts
index b5517e65649..d89031ac1af 100644
--- a/src/renderer/src/store/slices/worktrees.test.ts
+++ b/src/renderer/src/store/slices/worktrees.test.ts
@@ -289,7 +289,8 @@ describe('createWorktree base status merge', () => {
       path: '/path/wt1',
       linkedIssue: 123,
       linkedPR: 456,
-      createdWithAgent: 'codex'
+      createdWithAgent: 'codex',
+      linkedLinearIssue: 'ENG-123'
     })
     mockApi.worktrees.create.mockResolvedValue({ worktree: wt })
 
@@ -306,7 +307,8 @@ describe('createWorktree base status merge', () => {
         123,
         456,
         undefined,
-        'codex'
+        'codex',
+        'ENG-123'
       )
 
     expect(mockApi.worktrees.create).toHaveBeenCalledWith(
@@ -315,13 +317,15 @@ describe('createWorktree base status merge', () => {
         name: 'feature',
         linkedIssue: 123,
         linkedPR: 456,
-        createdWithAgent: 'codex'
+        createdWithAgent: 'codex',
+        linkedLinearIssue: 'ENG-123'
       })
     )
     expect(store.getState().worktreesByRepo.repo1[0]).toMatchObject({
       linkedIssue: 123,
       linkedPR: 456,
-      createdWithAgent: 'codex'
+      createdWithAgent: 'codex',
+      linkedLinearIssue: 'ENG-123'
     })
   })
 
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 201f8570099..53ae531c8ab 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -271,7 +271,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     linkedIssue,
     linkedPR,
     pushTarget,
-    createdWithAgent
+    createdWithAgent,
+    linkedLinearIssue
   ) => {
     const retryableConflictPatterns = [
       /already exists locally/i,
@@ -296,7 +297,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             ...(linkedIssue !== undefined ? { linkedIssue } : {}),
             ...(linkedPR !== undefined ? { linkedPR } : {}),
             ...(pushTarget ? { pushTarget } : {}),
-            ...(createdWithAgent ? { createdWithAgent } : {})
+            ...(createdWithAgent ? { createdWithAgent } : {}),
+            ...(linkedLinearIssue !== undefined ? { linkedLinearIssue } : {})
           }
           const target = getActiveRuntimeTarget(get().settings)
           const result =
@@ -315,7 +317,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
                     ...(linkedIssue !== undefined ? { linkedIssue } : {}),
                     ...(linkedPR !== undefined ? { linkedPR } : {}),
                     ...(pushTarget ? { pushTarget } : {}),
-                    ...(createdWithAgent ? { createdWithAgent } : {})
+                    ...(createdWithAgent ? { createdWithAgent } : {}),
+                    ...(linkedLinearIssue !== undefined ? { linkedLinearIssue } : {})
                   },
                   { timeoutMs: 10 * 60_000 }
                 )
diff --git a/src/shared/hosted-review.ts b/src/shared/hosted-review.ts
index a1dee49d5b2..56bb9da2ed2 100644
--- a/src/shared/hosted-review.ts
+++ b/src/shared/hosted-review.ts
@@ -19,6 +19,7 @@ export type HostedReviewInfo = {
 
 export type HostedReviewForBranchArgs = {
   repoPath: string
+  repoId?: string
   branch: string
   linkedGitHubPR?: number | null
   linkedGitLabMR?: number | null
diff --git a/src/shared/remote-workspace-session-projection.test.ts b/src/shared/remote-workspace-session-projection.test.ts
new file mode 100644
index 00000000000..efd91adb111
--- /dev/null
+++ b/src/shared/remote-workspace-session-projection.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import {
+  exportRemoteWorkspaceSession,
+  importRemoteWorkspaceSession
+} from './remote-workspace-session-projection'
+import { getDefaultWorkspaceSession } from './constants'
+
+describe('remote workspace session projection', () => {
+  it('exports terminal state using remote worktree paths instead of local repo ids', () => {
+    const session = {
+      ...getDefaultWorkspaceSession(),
+      activeRepoId: 'repo-a',
+      activeWorktreeId: 'repo-a::/srv/app',
+      activeTabId: 'tab-1',
+      tabsByWorktree: {
+        'repo-a::/srv/app': [
+          {
+            id: 'tab-1',
+            ptyId: 'pty-1',
+            worktreeId: 'repo-a::/srv/app',
+            title: 'Remote',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          }
+        ],
+        'repo-local::/tmp/local': [
+          {
+            id: 'tab-local',
+            ptyId: 'pty-local',
+            worktreeId: 'repo-local::/tmp/local',
+            title: 'Local',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        'tab-1': { root: null, activeLeafId: null, expandedLeafId: null },
+        'tab-local': { root: null, activeLeafId: null, expandedLeafId: null }
+      },
+      remoteSessionIdsByTabId: {
+        'tab-1': 'pty-1',
+        'tab-local': 'pty-local'
+      }
+    }
+
+    const projected = exportRemoteWorkspaceSession(session, {
+      isTargetWorktree: (worktreeId) => worktreeId.startsWith('repo-a::')
+    })
+
+    expect(Object.keys(projected.tabsByWorktreePath)).toEqual(['/srv/app'])
+    expect(projected.tabsByWorktreePath['/srv/app'][0]).toMatchObject({
+      id: 'tab-1',
+      worktreePath: '/srv/app'
+    })
+    expect(projected.terminalLayoutsByTabId).toEqual({
+      'tab-1': { root: null, activeLeafId: null, expandedLeafId: null }
+    })
+    expect(projected.remoteSessionIdsByTabId).toEqual({ 'tab-1': 'pty-1' })
+  })
+
+  it('imports projected terminal state into this client repo id', () => {
+    const session = importRemoteWorkspaceSession(
+      {
+        activeWorktreePath: '/srv/app',
+        activeTabId: 'tab-1',
+        tabsByWorktreePath: {
+          '/srv/app': [
+            {
+              id: 'tab-1',
+              ptyId: 'pty-1',
+              worktreePath: '/srv/app',
+              title: 'Remote',
+              customTitle: null,
+              color: null,
+              sortOrder: 0,
+              createdAt: 1
+            }
+          ]
+        },
+        terminalLayoutsByTabId: {
+          'tab-1': { root: null, activeLeafId: null, expandedLeafId: null }
+        },
+        remoteSessionIdsByTabId: { 'tab-1': 'pty-1' }
+      },
+      { resolveWorktreeId: (path) => (path === '/srv/app' ? 'repo-b::/srv/app' : null) }
+    )
+
+    expect(session.activeRepoId).toBe('repo-b')
+    expect(session.activeWorktreeId).toBe('repo-b::/srv/app')
+    expect(session.tabsByWorktree['repo-b::/srv/app'][0]).toMatchObject({
+      id: 'tab-1',
+      worktreeId: 'repo-b::/srv/app'
+    })
+    expect(session.remoteSessionIdsByTabId).toEqual({ 'tab-1': 'pty-1' })
+  })
+
+  it('imports active worktree metadata even when the worktree has no terminal tabs', () => {
+    const session = importRemoteWorkspaceSession(
+      {
+        activeWorktreePath: '/srv/app',
+        activeTabId: null,
+        tabsByWorktreePath: {},
+        terminalLayoutsByTabId: {},
+        activeTabIdByWorktreePath: { '/srv/app': null },
+        lastVisitedAtByWorktreePath: { '/srv/app': 456 }
+      },
+      { resolveWorktreeId: (path) => (path === '/srv/app' ? 'repo-b::/srv/app' : null) }
+    )
+
+    expect(session.activeRepoId).toBe('repo-b')
+    expect(session.activeWorktreeId).toBe('repo-b::/srv/app')
+    expect(session.activeTabIdByWorktree).toEqual({ 'repo-b::/srv/app': null })
+    expect(session.lastVisitedAtByWorktreeId).toEqual({ 'repo-b::/srv/app': 456 })
+  })
+})
diff --git a/src/shared/remote-workspace-session-projection.ts b/src/shared/remote-workspace-session-projection.ts
new file mode 100644
index 00000000000..e8641783523
--- /dev/null
+++ b/src/shared/remote-workspace-session-projection.ts
@@ -0,0 +1,184 @@
+import { getDefaultWorkspaceSession } from './constants'
+import type { RemoteWorkspaceSession, RemoteWorkspaceTerminalTab } from './remote-workspace-types'
+import type { TerminalTab, WorkspaceSessionState } from './types'
+import { splitWorktreeId } from './worktree-id'
+
+type ExportOptions = {
+  isTargetWorktree: (worktreeId: string) => boolean
+}
+
+type ImportOptions = {
+  resolveWorktreeId: (worktreePath: string) => string | null
+}
+
+function worktreePathFromId(worktreeId: string): string | null {
+  return splitWorktreeId(worktreeId)?.worktreePath ?? null
+}
+
+function tabToRemote(tab: TerminalTab, worktreePath: string): RemoteWorkspaceTerminalTab {
+  const { worktreeId: _worktreeId, pendingActivationSpawn: _pendingActivationSpawn, ...rest } = tab
+  void _worktreeId
+  void _pendingActivationSpawn
+  return { ...rest, worktreePath }
+}
+
+function tabToLocal(tab: RemoteWorkspaceTerminalTab, worktreeId: string): TerminalTab {
+  const { worktreePath: _worktreePath, ...rest } = tab
+  void _worktreePath
+  return { ...rest, worktreeId }
+}
+
+export function exportRemoteWorkspaceSession(
+  session: WorkspaceSessionState,
+  options: ExportOptions
+): RemoteWorkspaceSession {
+  const tabsByWorktreePath: Record<string, RemoteWorkspaceTerminalTab[]> = {}
+  const terminalTabIds = new Set<string>()
+
+  for (const [worktreeId, tabs] of Object.entries(session.tabsByWorktree)) {
+    if (!options.isTargetWorktree(worktreeId)) {
+      continue
+    }
+    const worktreePath = worktreePathFromId(worktreeId)
+    if (!worktreePath) {
+      continue
+    }
+    tabsByWorktreePath[worktreePath] = tabs.map((tab) => {
+      terminalTabIds.add(tab.id)
+      return tabToRemote(tab, worktreePath)
+    })
+  }
+
+  const activeWorktreePath =
+    session.activeWorktreeId && options.isTargetWorktree(session.activeWorktreeId)
+      ? worktreePathFromId(session.activeWorktreeId)
+      : null
+
+  const activeTabId =
+    session.activeTabId && terminalTabIds.has(session.activeTabId) ? session.activeTabId : null
+
+  const activeTabIdByWorktreePath: Record<string, string | null> = {}
+  for (const [worktreeId, tabId] of Object.entries(session.activeTabIdByWorktree ?? {})) {
+    if (!options.isTargetWorktree(worktreeId)) {
+      continue
+    }
+    const worktreePath = worktreePathFromId(worktreeId)
+    if (worktreePath) {
+      activeTabIdByWorktreePath[worktreePath] = tabId && terminalTabIds.has(tabId) ? tabId : null
+    }
+  }
+
+  const lastVisitedAtByWorktreePath: Record<string, number> = {}
+  for (const [worktreeId, timestamp] of Object.entries(session.lastVisitedAtByWorktreeId ?? {})) {
+    if (!options.isTargetWorktree(worktreeId)) {
+      continue
+    }
+    const worktreePath = worktreePathFromId(worktreeId)
+    if (worktreePath) {
+      lastVisitedAtByWorktreePath[worktreePath] = timestamp
+    }
+  }
+
+  return {
+    activeWorktreePath,
+    activeTabId,
+    tabsByWorktreePath,
+    terminalLayoutsByTabId: Object.fromEntries(
+      Object.entries(session.terminalLayoutsByTabId ?? {}).filter(([tabId]) =>
+        terminalTabIds.has(tabId)
+      )
+    ),
+    activeWorktreePathsOnShutdown: session.activeWorktreeIdsOnShutdown
+      ?.filter(options.isTargetWorktree)
+      .map(worktreePathFromId)
+      .filter((path): path is string => Boolean(path)),
+    activeTabIdByWorktreePath,
+    remoteSessionIdsByTabId: session.remoteSessionIdsByTabId
+      ? Object.fromEntries(
+          Object.entries(session.remoteSessionIdsByTabId).filter(([tabId]) =>
+            terminalTabIds.has(tabId)
+          )
+        )
+      : undefined,
+    lastVisitedAtByWorktreePath
+  }
+}
+
+export function importRemoteWorkspaceSession(
+  remote: RemoteWorkspaceSession,
+  options: ImportOptions
+): WorkspaceSessionState {
+  const session = getDefaultWorkspaceSession()
+  const tabsByWorktree: Record<string, TerminalTab[]> = {}
+  const terminalTabIds = new Set<string>()
+  const worktreeIdByPath = new Map<string, string>()
+  const resolvePath = (worktreePath: string): string | null => {
+    if (worktreeIdByPath.has(worktreePath)) {
+      return worktreeIdByPath.get(worktreePath) ?? null
+    }
+    const worktreeId = options.resolveWorktreeId(worktreePath)
+    if (worktreeId) {
+      worktreeIdByPath.set(worktreePath, worktreeId)
+    }
+    return worktreeId
+  }
+
+  for (const [worktreePath, tabs] of Object.entries(remote.tabsByWorktreePath ?? {})) {
+    const worktreeId = resolvePath(worktreePath)
+    if (!worktreeId) {
+      continue
+    }
+    tabsByWorktree[worktreeId] = tabs.map((tab) => {
+      terminalTabIds.add(tab.id)
+      return tabToLocal(tab, worktreeId)
+    })
+  }
+
+  const activeWorktreeId = remote.activeWorktreePath ? resolvePath(remote.activeWorktreePath) : null
+
+  const activeTabId =
+    remote.activeTabId && terminalTabIds.has(remote.activeTabId) ? remote.activeTabId : null
+
+  const activeTabIdByWorktree: Record<string, string | null> = {}
+  for (const [worktreePath, tabId] of Object.entries(remote.activeTabIdByWorktreePath ?? {})) {
+    const worktreeId = resolvePath(worktreePath)
+    if (worktreeId) {
+      activeTabIdByWorktree[worktreeId] = tabId && terminalTabIds.has(tabId) ? tabId : null
+    }
+  }
+
+  const lastVisitedAtByWorktreeId: Record<string, number> = {}
+  for (const [worktreePath, timestamp] of Object.entries(
+    remote.lastVisitedAtByWorktreePath ?? {}
+  )) {
+    const worktreeId = resolvePath(worktreePath)
+    if (worktreeId) {
+      lastVisitedAtByWorktreeId[worktreeId] = timestamp
+    }
+  }
+
+  return {
+    ...session,
+    activeRepoId: activeWorktreeId ? (splitWorktreeId(activeWorktreeId)?.repoId ?? null) : null,
+    activeWorktreeId,
+    activeTabId,
+    tabsByWorktree,
+    terminalLayoutsByTabId: Object.fromEntries(
+      Object.entries(remote.terminalLayoutsByTabId ?? {}).filter(([tabId]) =>
+        terminalTabIds.has(tabId)
+      )
+    ),
+    activeWorktreeIdsOnShutdown: remote.activeWorktreePathsOnShutdown
+      ?.map((path) => worktreeIdByPath.get(path))
+      .filter((id): id is string => Boolean(id)),
+    activeTabIdByWorktree,
+    remoteSessionIdsByTabId: remote.remoteSessionIdsByTabId
+      ? Object.fromEntries(
+          Object.entries(remote.remoteSessionIdsByTabId).filter(([tabId]) =>
+            terminalTabIds.has(tabId)
+          )
+        )
+      : undefined,
+    lastVisitedAtByWorktreeId
+  }
+}
diff --git a/src/shared/remote-workspace-types.ts b/src/shared/remote-workspace-types.ts
new file mode 100644
index 00000000000..0a60057d241
--- /dev/null
+++ b/src/shared/remote-workspace-types.ts
@@ -0,0 +1,54 @@
+import type { TerminalLayoutSnapshot, TerminalTab } from './types'
+
+export type RemoteWorkspaceTerminalTab = Omit<TerminalTab, 'worktreeId'> & {
+  worktreePath: string
+}
+
+export type RemoteWorkspaceSession = {
+  activeWorktreePath: string | null
+  activeTabId: string | null
+  tabsByWorktreePath: Record<string, RemoteWorkspaceTerminalTab[]>
+  terminalLayoutsByTabId: Record<string, TerminalLayoutSnapshot>
+  activeWorktreePathsOnShutdown?: string[]
+  activeTabIdByWorktreePath?: Record<string, string | null>
+  remoteSessionIdsByTabId?: Record<string, string>
+  lastVisitedAtByWorktreePath?: Record<string, number>
+}
+
+export type RemoteWorkspaceSnapshot = {
+  namespace: string
+  revision: number
+  updatedAt: number
+  schemaVersion: number
+  session: RemoteWorkspaceSession
+}
+
+export type RemoteWorkspaceConnectedClient = {
+  clientId: string
+  name: string
+  lastSeenAt: number
+  isCurrent?: boolean
+}
+
+export type RemoteWorkspacePatch = {
+  kind: 'replace-session'
+  session: RemoteWorkspaceSession
+}
+
+export type RemoteWorkspacePatchResult =
+  | {
+      ok: true
+      snapshot: RemoteWorkspaceSnapshot
+    }
+  | {
+      ok: false
+      reason: 'stale-revision' | 'unavailable'
+      snapshot?: RemoteWorkspaceSnapshot
+      message?: string
+    }
+
+export type RemoteWorkspaceChangedEvent = {
+  targetId: string
+  snapshot: RemoteWorkspaceSnapshot
+  sourceClientId?: string
+}
diff --git a/src/shared/ssh-types.ts b/src/shared/ssh-types.ts
index adf7c789a40..7814d9aa90b 100644
--- a/src/shared/ssh-types.ts
+++ b/src/shared/ssh-types.ts
@@ -17,6 +17,12 @@ export type SshTarget = {
   /** Grace period in seconds before relay shuts down after disconnect.
    *  Default: 300 (5 minutes). */
   relayGracePeriodSeconds?: number
+  /** Opt in to remote-host-owned workspace/session state for this SSH target.
+   *  Classic SSH remains local-session-backed when this is false/absent. */
+  remoteWorkspaceSyncEnabled?: boolean
+  /** Grace period in seconds for synced remote workspace relays.
+   *  0 disables expiry. Only applies when remoteWorkspaceSyncEnabled is true. */
+  remoteWorkspaceSyncGracePeriodSeconds?: number
   /** Set to true after a successful connection that triggered a credential
    *  prompt (passphrase or password). Persisted so startup reconnect can
    *  partition targets into eager (no passphrase) vs deferred (passphrase)
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 04eb6588dcc..c51c54e63ec 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -963,6 +963,7 @@ export type CreateWorktreeArgs = {
   sparseCheckout?: CreateSparseCheckoutRequest
   linkedIssue?: number
   linkedPR?: number
+  linkedLinearIssue?: string
   pushTarget?: GitPushTarget
   /** Agent selected in the create surface. Omitted for blank-shell creates. */
   createdWithAgent?: TuiAgent

From c9bb5a5adeddf167125b532ad2b241abf35f7927 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 12:32:11 -0700
Subject: [PATCH 57/82] Improve GitHub list search (#1963)

Add Cmd/Ctrl+F support for GitHub Issues/PRs and Project search in Orca, and align project clear behavior with GitHub-style filter controls.
---
 src/renderer/src/components/TaskPage.tsx      | 56 +++++++++++++++++++
 .../github-project/ProjectViewWrapper.tsx     | 53 ++++++++++++++++--
 src/shared/github-project-types.ts            |  3 +-
 3 files changed, 106 insertions(+), 6 deletions(-)

diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 0133d5869f9..c059050d721 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -870,6 +870,7 @@ export default function TaskPage(): React.JSX.Element {
 
   const [taskSearchInput, setTaskSearchInput] = useState(initialTaskQuery)
   const [appliedTaskSearch, setAppliedTaskSearch] = useState(initialTaskQuery)
+  const taskSearchInputRef = useRef<HTMLInputElement>(null)
   const [activeTaskPreset, setActiveTaskPreset] = useState<TaskViewPresetId | null>(
     defaultTaskViewPreset
   )
@@ -1646,6 +1647,59 @@ export default function TaskPage(): React.JSX.Element {
     [handleApplyTaskSearch]
   )
 
+  useEffect(() => {
+    if (
+      taskSource !== 'github' ||
+      githubMode !== 'items' ||
+      dialogWorkItem ||
+      drawerLinearIssue ||
+      newIssueOpen ||
+      newLinearIssueOpen ||
+      activeModal !== 'none'
+    ) {
+      return
+    }
+
+    const onKeyDown = (event: KeyboardEvent): void => {
+      const isMac = navigator.userAgent.includes('Mac')
+      const modifierPressed = isMac ? event.metaKey : event.ctrlKey
+      if (!modifierPressed || event.altKey || event.shiftKey || event.key.toLowerCase() !== 'f') {
+        return
+      }
+
+      const input = taskSearchInputRef.current
+      if (!input) {
+        return
+      }
+      const target = event.target
+      if (
+        target instanceof HTMLElement &&
+        target !== input &&
+        (target instanceof HTMLInputElement ||
+          target instanceof HTMLTextAreaElement ||
+          target.isContentEditable)
+      ) {
+        return
+      }
+
+      event.preventDefault()
+      event.stopPropagation()
+      input.focus()
+      input.select()
+    }
+
+    window.addEventListener('keydown', onKeyDown, { capture: true })
+    return () => window.removeEventListener('keydown', onKeyDown, { capture: true })
+  }, [
+    activeModal,
+    dialogWorkItem,
+    drawerLinearIssue,
+    githubMode,
+    newIssueOpen,
+    newLinearIssueOpen,
+    taskSource
+  ])
+
   const openComposerForItem = useCallback(
     (item: GitHubWorkItem): void => {
       const linkedWorkItem: LinkedWorkItemSummary = {
@@ -2289,6 +2343,8 @@ export default function TaskPage(): React.JSX.Element {
                       <div className="relative min-w-[320px] flex-1">
                         <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
                         <Input
+                          ref={taskSearchInputRef}
+                          data-github-items-search-input
                           value={taskSearchInput}
                           onChange={handleTaskSearchChange}
                           onKeyDown={handleTaskSearchKeyDown}
diff --git a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
index 15cd8b41779..6c90f7609e1 100644
--- a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
+++ b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
@@ -2,7 +2,7 @@
 // Why: top-level container for Project mode. Handles the picker, header,
 // filter label, count pill, Open-in-GitHub, and all Interaction States
 // documented in the design doc.
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
   ExternalLink,
   Loader,
@@ -803,6 +803,7 @@ function ProjectSearchInput({
 }): React.JSX.Element {
   const initial = appliedOverride !== undefined ? appliedOverride : viewFilter
   const [value, setValue] = useState<string>(initial)
+  const inputRef = useRef<HTMLInputElement>(null)
   const applied = appliedOverride !== undefined ? appliedOverride : viewFilter
   const dirty = value !== applied
 
@@ -812,14 +813,55 @@ function ProjectSearchInput({
     onApply(next === viewFilter ? undefined : next)
   }
 
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent): void => {
+      const isMac = navigator.userAgent.includes('Mac')
+      const modifierPressed = isMac ? event.metaKey : event.ctrlKey
+      if (!modifierPressed || event.altKey || event.shiftKey || event.key.toLowerCase() !== 'f') {
+        return
+      }
+      if (document.querySelector('[role="dialog"]')) {
+        return
+      }
+
+      const input = inputRef.current
+      if (!input) {
+        return
+      }
+      const target = event.target
+      if (
+        target instanceof HTMLElement &&
+        target !== input &&
+        (target instanceof HTMLInputElement ||
+          target instanceof HTMLTextAreaElement ||
+          target.isContentEditable)
+      ) {
+        return
+      }
+
+      event.preventDefault()
+      event.stopPropagation()
+      input.focus()
+      input.select()
+    }
+
+    window.addEventListener('keydown', onKeyDown, { capture: true })
+    return () => window.removeEventListener('keydown', onKeyDown, { capture: true })
+  }, [])
+
   return (
     <div className="relative min-w-[280px] flex-1 max-w-xl">
       <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
       <Input
+        ref={inputRef}
+        data-github-project-search-input
         value={value}
         onChange={(e) => setValue(e.target.value)}
         onKeyDown={(e) => {
           if (e.key === 'Enter') {
+            if (e.nativeEvent.isComposing) {
+              return
+            }
             e.preventDefault()
             apply(value)
           } else if (e.key === 'Escape') {
@@ -839,13 +881,14 @@ function ProjectSearchInput({
           dirty && 'border-amber-500/50'
         )}
       />
-      {value && value !== viewFilter ? (
+      {value ? (
         <button
           type="button"
-          aria-label="Reset to view filter"
+          aria-label="Clear search"
+          onMouseDown={(e) => e.preventDefault()}
           onClick={() => {
-            setValue(viewFilter)
-            apply(viewFilter)
+            setValue('')
+            apply('')
           }}
           className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground transition hover:text-foreground"
         >
diff --git a/src/shared/github-project-types.ts b/src/shared/github-project-types.ts
index 90ea46f9e37..789d7272f1c 100644
--- a/src/shared/github-project-types.ts
+++ b/src/shared/github-project-types.ts
@@ -338,7 +338,8 @@ export type GetProjectViewTableArgs = {
   viewName?: string
   /** Ephemeral GitHub-search-syntax query that replaces the view's filter for
    *  this fetch only. The view's stored filter on GitHub is not modified.
-   *  Empty string and undefined both mean "use the view's filter as-is". */
+   *  `undefined` uses the view's saved filter; `''` explicitly clears it for
+   *  this fetch and gets a distinct renderer cache key. */
   queryOverride?: string
 }
 

From 57bf5c08242b561b41eedd03c43fdb0a00851543 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 12:38:47 -0700
Subject: [PATCH 58/82] Add markdown annotations

Add markdown annotation support and remove the temporary design doc from the PR.
---
 src/relay/fs-handler.test.ts                  |  10 +-
 src/renderer/src/assets/markdown-preview.css  |  58 +++
 .../src/components/WorktreeJumpPalette.tsx    |   6 +-
 .../diff-comments/DiffCommentCard.tsx         |   7 +-
 .../diff-comments/useDiffCommentDecorator.tsx |   1 +
 .../src/components/editor/DiffSectionItem.tsx |  15 +-
 .../src/components/editor/DiffViewer.tsx      |   5 +-
 .../src/components/editor/EditorContent.tsx   |   5 +
 .../src/components/editor/MarkdownPreview.tsx | 335 +++++++++++++++++-
 .../src/components/editor/MonacoEditor.tsx    | 119 ++++++-
 .../new-workspace/SmartWorkspaceNameField.tsx |   6 +-
 .../right-sidebar/SourceControl.tsx           |  63 +++-
 .../src/lib/diff-comment-compat.test.ts       |  43 +++
 src/renderer/src/lib/diff-comment-compat.ts   |  25 ++
 .../src/lib/diff-comments-format.test.ts      |  26 ++
 src/renderer/src/lib/diff-comments-format.ts  |  12 +-
 .../src/lib/markdown-comment-blocks.test.ts   |  41 +++
 .../src/lib/markdown-comment-blocks.ts        |  40 +++
 .../src/store/slices/diffComments.test.ts     |  57 +++
 src/renderer/src/store/slices/diffComments.ts |  27 +-
 src/shared/telemetry-events.ts                |   1 +
 src/shared/types.ts                           |   6 +
 22 files changed, 856 insertions(+), 52 deletions(-)
 create mode 100644 src/renderer/src/lib/diff-comment-compat.test.ts
 create mode 100644 src/renderer/src/lib/diff-comment-compat.ts
 create mode 100644 src/renderer/src/lib/markdown-comment-blocks.test.ts
 create mode 100644 src/renderer/src/lib/markdown-comment-blocks.ts

diff --git a/src/relay/fs-handler.test.ts b/src/relay/fs-handler.test.ts
index f3ad1ec250f..dd21dc09922 100644
--- a/src/relay/fs-handler.test.ts
+++ b/src/relay/fs-handler.test.ts
@@ -458,9 +458,13 @@ describe('FsHandler', () => {
       .mockResolvedValue({ unsubscribe: vi.fn() })
 
     let stale = false
-    await dispatcher.callRequest('fs.watch', { rootPath: path.join(tmpDir, 'stale-root') }, {
-      isStale: () => stale
-    })
+    await dispatcher.callRequest(
+      'fs.watch',
+      { rootPath: path.join(tmpDir, 'stale-root') },
+      {
+        isStale: () => stale
+      }
+    )
     for (let index = 0; index < 19; index += 1) {
       await dispatcher.callRequest('fs.watch', {
         rootPath: path.join(tmpDir, `watched-${index}`)
diff --git a/src/renderer/src/assets/markdown-preview.css b/src/renderer/src/assets/markdown-preview.css
index 1333e713e42..134c1147a8f 100644
--- a/src/renderer/src/assets/markdown-preview.css
+++ b/src/renderer/src/assets/markdown-preview.css
@@ -210,6 +210,64 @@
   background: color-mix(in srgb, #fb923c 60%, transparent);
 }
 
+.markdown-annotation-block {
+  position: relative;
+}
+
+.markdown-annotation-block:hover > .markdown-annotation-controls > .markdown-annotation-add,
+.markdown-annotation-block:focus-within > .markdown-annotation-controls > .markdown-annotation-add,
+li:hover > .markdown-annotation-controls > .markdown-annotation-add,
+li:focus-within > .markdown-annotation-controls > .markdown-annotation-add {
+  opacity: 1;
+}
+
+.markdown-annotation-controls {
+  margin-top: 6px;
+}
+
+.markdown-annotation-add {
+  display: inline-flex;
+  width: 20px;
+  height: 20px;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+  border-radius: 4px;
+  background: var(--background);
+  color: var(--muted-foreground);
+  cursor: pointer;
+  opacity: 0;
+  transition:
+    opacity 100ms ease,
+    color 100ms ease,
+    background-color 100ms ease;
+}
+
+.markdown-annotation-add:hover {
+  background: var(--accent);
+  color: var(--foreground);
+}
+
+.markdown-annotation-add:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 1px;
+  opacity: 1;
+}
+
+.markdown-annotation-composer,
+.markdown-annotation-card {
+  max-width: 520px;
+  margin-top: 6px;
+}
+
+.markdown-annotation-composer {
+  border: 1px solid color-mix(in srgb, var(--foreground) 18%, transparent);
+  border-radius: 6px;
+  background: var(--editor-surface);
+  padding: 8px;
+  box-shadow: 0 1px 2px color-mix(in srgb, var(--foreground) 12%, transparent);
+}
+
 .markdown-body h1,
 .markdown-body h2,
 .markdown-body h3,
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index 822ffeb509e..cfa51c11386 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -38,11 +38,7 @@ import {
   ORCA_BROWSER_FOCUS_REQUEST_EVENT,
   queueBrowserFocusRequest
 } from '@/components/browser-pane/browser-focus'
-import type {
-  BrowserPage,
-  BrowserWorkspace,
-  Worktree
-} from '../../../shared/types'
+import type { BrowserPage, BrowserWorkspace, Worktree } from '../../../shared/types'
 import { isGitRepoKind } from '../../../shared/repo-kind'
 
 type WorktreePaletteItem = {
diff --git a/src/renderer/src/components/diff-comments/DiffCommentCard.tsx b/src/renderer/src/components/diff-comments/DiffCommentCard.tsx
index 197e1452963..fe0424e7216 100644
--- a/src/renderer/src/components/diff-comments/DiffCommentCard.tsx
+++ b/src/renderer/src/components/diff-comments/DiffCommentCard.tsx
@@ -1,6 +1,7 @@
 import { CornerDownLeft, Pencil, Trash } from 'lucide-react'
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { Button } from '@/components/ui/button'
+import { getDiffCommentLineLabel } from '@/lib/diff-comment-compat'
 
 // Why: the saved-note card lives inside a Monaco view zone's DOM node.
 // useDiffCommentDecorator creates a React root per zone and renders this
@@ -14,6 +15,7 @@ import { Button } from '@/components/ui/button'
 
 type Props = {
   lineNumber: number
+  startLine?: number
   body: string
   onDelete: () => void
   // Why: Monaco view zones have a fixed `heightInPx` set at insertion time
@@ -26,6 +28,7 @@ type Props = {
 
 export function DiffCommentCard({
   lineNumber,
+  startLine,
   body,
   onDelete,
   onContentResize,
@@ -123,7 +126,9 @@ export function DiffCommentCard({
   return (
     <div className="orca-diff-comment-card">
       <div className="orca-diff-comment-header">
-        <span className="orca-diff-comment-meta">Note · line {lineNumber}</span>
+        <span className="orca-diff-comment-meta">
+          Note · {getDiffCommentLineLabel({ lineNumber, startLine }).toLowerCase()}
+        </span>
         <div className="orca-diff-comment-actions">
           {onSubmitEdit && !editing && (
             <button
diff --git a/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx b/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx
index dcc8e527c12..a05fcaacbb0 100644
--- a/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx
+++ b/src/renderer/src/components/diff-comments/useDiffCommentDecorator.tsx
@@ -395,6 +395,7 @@ export function useDiffCommentDecorator({
       root.render(
         <DiffCommentCard
           lineNumber={comment.lineNumber}
+          startLine={comment.startLine}
           body={comment.body}
           onDelete={() => onDeleteCommentRef.current(comment.id)}
           onSubmitEdit={
diff --git a/src/renderer/src/components/editor/DiffSectionItem.tsx b/src/renderer/src/components/editor/DiffSectionItem.tsx
index 917ae4df4bb..f30e6266691 100644
--- a/src/renderer/src/components/editor/DiffSectionItem.tsx
+++ b/src/renderer/src/components/editor/DiffSectionItem.tsx
@@ -22,6 +22,7 @@ import { DiffCommentPopover } from '../diff-comments/DiffCommentPopover'
 import { applyDiffEditorLineNumberOptions } from './diff-editor-line-number-options'
 import { computeLineStats } from './diff-line-stats'
 import type { DiffComment, GitDiffResult } from '../../../../shared/types'
+import { isDiffComment } from '@/lib/diff-comment-compat'
 
 const ImageDiffViewer = lazy(() => import('./ImageDiffViewer'))
 
@@ -88,7 +89,7 @@ export function DiffSectionItem({
     (s): DiffComment[] | undefined => findWorktreeById(s.worktreesByRepo, worktreeId)?.diffComments
   )
   const diffComments = useMemo(
-    () => (allDiffComments ?? []).filter((c) => c.filePath === section.path),
+    () => (allDiffComments ?? []).filter((c) => c.filePath === section.path && isDiffComment(c)),
     [allDiffComments, section.path]
   )
   const language = detectLanguage(section.path)
@@ -105,7 +106,11 @@ export function DiffSectionItem({
   const [modifiedEditor, setModifiedEditor] = useState<monacoEditor.ICodeEditor | null>(null)
   const diffEditorRef = useRef<monacoEditor.IStandaloneDiffEditor | null>(null)
   const lineNumberOptionsSubRef = useRef<{ dispose: () => void } | null>(null)
-  const [popover, setPopover] = useState<{ lineNumber: number; top: number } | null>(null)
+  const [popover, setPopover] = useState<{
+    lineNumber: number
+    startLine?: number
+    top: number
+  } | null>(null)
 
   const disposeDiffModels = useCallback(() => {
     window.setTimeout(() => {
@@ -143,7 +148,8 @@ export function DiffSectionItem({
     filePath: section.path,
     worktreeId,
     comments: diffComments,
-    onAddCommentClick: ({ lineNumber, top }) => setPopover({ lineNumber, top }),
+    onAddCommentClick: ({ lineNumber, startLine, top }) =>
+      setPopover({ lineNumber, startLine, top }),
     onDeleteComment: (id) => void deleteDiffComment(worktreeId, id),
     onUpdateComment: (id, body) => updateDiffComment(worktreeId, id, body),
     pendingScrollCommentId: pendingScrollForThisSection,
@@ -195,6 +201,8 @@ export function DiffSectionItem({
     const result = await addDiffComment({
       worktreeId,
       filePath: section.path,
+      source: 'diff',
+      startLine: popover.startLine,
       lineNumber: popover.lineNumber,
       body,
       side: 'modified'
@@ -364,6 +372,7 @@ export function DiffSectionItem({
             <DiffCommentPopover
               key={popover.lineNumber}
               lineNumber={popover.lineNumber}
+              startLine={popover.startLine}
               top={popover.top}
               onCancel={() => setPopover(null)}
               onSubmit={handleSubmitComment}
diff --git a/src/renderer/src/components/editor/DiffViewer.tsx b/src/renderer/src/components/editor/DiffViewer.tsx
index 13fe3d89076..c25f22235c0 100644
--- a/src/renderer/src/components/editor/DiffViewer.tsx
+++ b/src/renderer/src/components/editor/DiffViewer.tsx
@@ -11,6 +11,7 @@ import { useDiffCommentDecorator } from '../diff-comments/useDiffCommentDecorato
 import { DiffCommentPopover } from '../diff-comments/DiffCommentPopover'
 import { applyDiffEditorLineNumberOptions } from './diff-editor-line-number-options'
 import type { DiffComment } from '../../../../shared/types'
+import { isDiffComment } from '@/lib/diff-comment-compat'
 
 type DiffViewerProps = {
   modelKey: string
@@ -70,7 +71,7 @@ export default function DiffViewer({
     worktreeId ? findWorktreeById(s.worktreesByRepo, worktreeId)?.diffComments : undefined
   )
   const diffComments = useMemo(
-    () => (allDiffComments ?? []).filter((c) => c.filePath === relativePath),
+    () => (allDiffComments ?? []).filter((c) => c.filePath === relativePath && isDiffComment(c)),
     [allDiffComments, relativePath]
   )
   const editorFontSize = computeEditorFontSize(
@@ -250,6 +251,8 @@ export default function DiffViewer({
     const result = await addDiffComment({
       worktreeId,
       filePath: relativePath,
+      source: 'diff',
+      startLine: popover.startLine,
       lineNumber: popover.lineNumber,
       body,
       side: 'modified'
diff --git a/src/renderer/src/components/editor/EditorContent.tsx b/src/renderer/src/components/editor/EditorContent.tsx
index 872e43e1766..c7fd65722b4 100644
--- a/src/renderer/src/components/editor/EditorContent.tsx
+++ b/src/renderer/src/components/editor/EditorContent.tsx
@@ -158,6 +158,8 @@ export function EditorContent({
       language={monacoLanguage}
       onContentChange={handleContentChange}
       onSave={isMarkdown ? md.mdSave : handleSave}
+      worktreeId={activeFile.worktreeId}
+      markdownAnnotationsEnabled={isMarkdown && mdViewMode !== 'rich'}
       revealLine={
         pendingEditorReveal?.filePath === activeFile.filePath ? pendingEditorReveal.line : undefined
       }
@@ -279,6 +281,7 @@ export function EditorContent({
               scrollCacheKey={`${editorViewStateKey}:preview`}
               showTableOfContents={showMarkdownTableOfContents}
               onCloseTableOfContents={onCloseMarkdownTableOfContents}
+              markdownAnnotationsEnabled={mdViewMode !== 'rich'}
               {...md.previewProps}
             />
           </div>
@@ -368,6 +371,7 @@ export function EditorContent({
           initialAnchor={activeFile.markdownPreviewAnchor ?? null}
           showTableOfContents={showMarkdownTableOfContents}
           onCloseTableOfContents={onCloseMarkdownTableOfContents}
+          markdownAnnotationsEnabled={mdViewMode !== 'rich'}
           {...md.previewProps}
         />
       </div>
@@ -511,6 +515,7 @@ export function EditorContent({
             scrollCacheKey={`${diffViewStateKey}:preview`}
             showTableOfContents={showMarkdownTableOfContents}
             onCloseTableOfContents={onCloseMarkdownTableOfContents}
+            markdownAnnotationsEnabled
             {...md.previewProps}
           />
         </div>
diff --git a/src/renderer/src/components/editor/MarkdownPreview.tsx b/src/renderer/src/components/editor/MarkdownPreview.tsx
index 05ab3574c0e..038e6ba8a9e 100644
--- a/src/renderer/src/components/editor/MarkdownPreview.tsx
+++ b/src/renderer/src/components/editor/MarkdownPreview.tsx
@@ -14,7 +14,7 @@ import rehypeSanitize, { defaultSchema } from 'rehype-sanitize'
 import rehypeSlug from 'rehype-slug'
 import GithubSlugger from 'github-slugger'
 import { extractFrontMatter } from './markdown-frontmatter'
-import { ChevronDown, ChevronUp, X } from 'lucide-react'
+import { ChevronDown, ChevronUp, CornerDownLeft, Plus, X } from 'lucide-react'
 import type { Components } from 'react-markdown'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
@@ -24,7 +24,7 @@ import { computeEditorFontSize } from '@/lib/editor-font-zoom'
 import { getConnectionId } from '@/lib/connection-context'
 import { scrollTopCache, setWithLRU } from '@/lib/scroll-cache'
 import { detectLanguage } from '@/lib/language-detect'
-import type { MarkdownDocument, Worktree } from '../../../../shared/types'
+import type { DiffComment, MarkdownDocument, Worktree } from '../../../../shared/types'
 import {
   fileUrlToAbsolutePath,
   getMarkdownPreviewLinkTarget,
@@ -54,6 +54,8 @@ import { markdownPreviewUrlTransform } from './markdown-preview-url-transform'
 import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 import { buildMarkdownTableOfContents } from './markdown-table-of-contents'
 import { MarkdownTableOfContentsPanel } from './MarkdownTableOfContentsPanel'
+import { isMarkdownComment } from '@/lib/diff-comment-compat'
+import { DiffCommentCard } from '../diff-comments/DiffCommentCard'
 
 type MarkdownPreviewProps = {
   content: string
@@ -64,6 +66,35 @@ type MarkdownPreviewProps = {
   onCloseTableOfContents?: () => void
   markdownDocuments?: MarkdownDocument[]
   onOpenDocument?: (document: MarkdownDocument) => void | Promise<void>
+  markdownAnnotationsEnabled?: boolean
+}
+
+type MarkdownPreviewPositionNode = {
+  tagName?: string
+  position?: {
+    start?: { line?: number }
+    end?: { line?: number }
+  }
+  children?: MarkdownPreviewPositionNode[]
+}
+
+function getMarkdownPreviewBlockRange(
+  node: MarkdownPreviewPositionNode | undefined
+): { startLine: number; endLine: number } | null {
+  const startLine = node?.position?.start?.line
+  const endLine = node?.position?.end?.line
+  if (!Number.isInteger(startLine) || !Number.isInteger(endLine)) {
+    return null
+  }
+  if (typeof startLine !== 'number' || typeof endLine !== 'number' || startLine < 1) {
+    return null
+  }
+  return { startLine, endLine: Math.max(startLine, endLine) }
+}
+
+function hasMarkdownPreviewNestedBlock(node: MarkdownPreviewPositionNode | undefined): boolean {
+  const blockTags = new Set(['p', 'pre', 'table', 'blockquote', 'ul', 'ol'])
+  return Boolean(node?.children?.some((child) => child.tagName && blockTags.has(child.tagName)))
 }
 
 const markdownPreviewSanitizeSchema = {
@@ -173,7 +204,8 @@ export default function MarkdownPreview({
   showTableOfContents = false,
   onCloseTableOfContents,
   markdownDocuments = [],
-  onOpenDocument
+  onOpenDocument,
+  markdownAnnotationsEnabled = false
 }: MarkdownPreviewProps): React.JSX.Element {
   const rootRef = useRef<HTMLDivElement>(null)
   const bodyRef = useRef<HTMLDivElement>(null)
@@ -190,6 +222,13 @@ export default function MarkdownPreview({
   const openMarkdownPreview = useAppStore((s) => s.openMarkdownPreview)
   const setMarkdownViewMode = useAppStore((s) => s.setMarkdownViewMode)
   const setPendingEditorReveal = useAppStore((s) => s.setPendingEditorReveal)
+  const addDiffComment = useAppStore((s) => s.addDiffComment)
+  const deleteDiffComment = useAppStore((s) => s.deleteDiffComment)
+  const updateDiffComment = useAppStore((s) => s.updateDiffComment)
+  const allDiffComments = useAppStore((s): DiffComment[] | undefined => {
+    const worktree = findWorktreeForMarkdownPreviewPath(s.worktreesByRepo, filePath)
+    return worktree?.diffComments
+  })
   const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
   const sourceRuntimeEnvironmentId = useAppStore(
     (s) => s.openFiles.find((file) => file.filePath === filePath)?.runtimeEnvironmentId
@@ -197,6 +236,27 @@ export default function MarkdownPreview({
   const sourceWorktree = findWorktreeForMarkdownPreviewPath(worktreesByRepo, filePath)
   const sourceConnectionId = sourceWorktree ? getConnectionId(sourceWorktree.id) : null
   const worktreeRoot = sourceWorktree?.path ?? null
+  const sourceRelativePath = useMemo(() => {
+    if (!sourceWorktree) {
+      return null
+    }
+    const normalizedFilePath = normalizeMarkdownPreviewAbsolutePath(filePath)
+    const normalizedRoot = normalizeMarkdownPreviewAbsolutePath(sourceWorktree.path)
+    if (normalizedFilePath === normalizedRoot) {
+      return ''
+    }
+    if (!normalizedFilePath.startsWith(`${normalizedRoot}/`)) {
+      return null
+    }
+    return normalizedFilePath.slice(normalizedRoot.length + 1)
+  }, [filePath, sourceWorktree])
+  const markdownComments = useMemo(
+    () =>
+      (allDiffComments ?? []).filter(
+        (comment) => comment.filePath === sourceRelativePath && isMarkdownComment(comment)
+      ),
+    [allDiffComments, sourceRelativePath]
+  )
   const settings = useAppStore((s) => s.settings)
   const imageRuntimeContext = useMemo(
     () =>
@@ -237,6 +297,7 @@ export default function MarkdownPreview({
       .trim()
   }, [frontMatter])
   const sluggerRef = useRef(new GithubSlugger())
+  const [activeAnnotationBlockKey, setActiveAnnotationBlockKey] = useState<string | null>(null)
 
   // Why: each split pane needs its own markdown preview viewport even when the
   // underlying file is shared. The caller passes a pane-scoped cache key so
@@ -468,6 +529,116 @@ export default function MarkdownPreview({
     return () => window.removeEventListener('keydown', handleKeyDown, { capture: true })
   }, [closeSearch, isSearchOpen, openSearch])
 
+  const renderAnnotationControls = useCallback(
+    (range: { startLine: number; endLine: number }, blockKey: string): React.ReactNode => {
+      if (!sourceWorktree || sourceRelativePath === null) {
+        return null
+      }
+      const commentsForBlock = markdownComments.filter(
+        (comment) => range.startLine <= comment.lineNumber && comment.lineNumber <= range.endLine
+      )
+      const canAuthor = markdownAnnotationsEnabled
+      if (!canAuthor && commentsForBlock.length === 0) {
+        return null
+      }
+
+      const handleSubmit = async (body: string): Promise<boolean> => {
+        const result = await addDiffComment({
+          worktreeId: sourceWorktree.id,
+          filePath: sourceRelativePath,
+          source: 'markdown',
+          startLine: range.startLine === range.endLine ? undefined : range.startLine,
+          lineNumber: range.endLine,
+          body,
+          side: 'modified'
+        })
+        if (result) {
+          setActiveAnnotationBlockKey(null)
+          return true
+        }
+        return false
+      }
+
+      return (
+        <div className="markdown-annotation-controls">
+          {canAuthor ? (
+            <button
+              type="button"
+              className="markdown-annotation-add"
+              aria-label={`Add note on line ${range.startLine}`}
+              title="Add note"
+              onClick={(event) => {
+                event.preventDefault()
+                event.stopPropagation()
+                setActiveAnnotationBlockKey((current) => (current === blockKey ? null : blockKey))
+              }}
+            >
+              <Plus className="size-3" />
+            </button>
+          ) : null}
+          {activeAnnotationBlockKey === blockKey ? (
+            <MarkdownAnnotationComposer
+              lineNumber={range.endLine}
+              startLine={range.startLine === range.endLine ? undefined : range.startLine}
+              onCancel={() => setActiveAnnotationBlockKey(null)}
+              onSubmit={handleSubmit}
+            />
+          ) : null}
+          {commentsForBlock.map((comment) => (
+            <div key={comment.id} className="markdown-annotation-card">
+              <DiffCommentCard
+                lineNumber={comment.lineNumber}
+                startLine={comment.startLine}
+                body={comment.body}
+                onDelete={() => void deleteDiffComment(sourceWorktree.id, comment.id)}
+                onSubmitEdit={(body) => updateDiffComment(sourceWorktree.id, comment.id, body)}
+              />
+            </div>
+          ))}
+        </div>
+      )
+    },
+    [
+      activeAnnotationBlockKey,
+      addDiffComment,
+      deleteDiffComment,
+      markdownAnnotationsEnabled,
+      markdownComments,
+      sourceRelativePath,
+      sourceWorktree,
+      updateDiffComment
+    ]
+  )
+
+  const wrapAnnotatedBlock = useCallback(
+    (
+      tagName: string,
+      node: MarkdownPreviewPositionNode | undefined,
+      rendered: React.ReactNode
+    ): React.ReactNode => {
+      const range = getMarkdownPreviewBlockRange(node)
+      if (!range) {
+        return rendered
+      }
+      const blockKey = `${tagName}:${range.startLine}-${range.endLine}`
+      const controls = renderAnnotationControls(range, blockKey)
+      if (!controls) {
+        return rendered
+      }
+      return (
+        <div
+          className="markdown-annotation-block"
+          data-source-line={range.startLine}
+          data-source-end-line={range.endLine}
+        >
+          {rendered}
+          {controls}
+        </div>
+      )
+    },
+    [renderAnnotationControls]
+  )
+
   const components: Components = useMemo(() => {
     sluggerRef.current.reset()
     const slugger = sluggerRef.current
@@ -740,56 +911,102 @@ export default function MarkdownPreview({
       // unwrapped — MermaidBlock renders via useEffect/innerHTML, not React children,
       // so CodeBlockCopyButton's extractText() would copy an empty string, and a
       // <div> inside <pre> produces invalid HTML.
-      pre: ({ children, ...props }) => {
+      pre: ({ node, children, ...props }) => {
         const child = React.Children.toArray(children)[0]
         if (React.isValidElement(child) && child.type === MermaidBlock) {
           return <>{children}</>
         }
-        return <CodeBlockCopyButton {...props}>{children}</CodeBlockCopyButton>
+        return wrapAnnotatedBlock(
+          'pre',
+          node as MarkdownPreviewPositionNode,
+          <CodeBlockCopyButton {...props}>{children}</CodeBlockCopyButton>
+        )
       },
-      h1: ({ children, ...props }) => {
-        const id = createMarkdownPreviewHeadingId(getMarkdownPreviewNodeText(children), slugger)
+      p: ({ node, children, ...props }) =>
+        wrapAnnotatedBlock('p', node as MarkdownPreviewPositionNode, <p {...props}>{children}</p>),
+      blockquote: ({ node, children, ...props }) =>
+        wrapAnnotatedBlock(
+          'blockquote',
+          node as MarkdownPreviewPositionNode,
+          <blockquote {...props}>{children}</blockquote>
+        ),
+      table: ({ node, children, ...props }) =>
+        wrapAnnotatedBlock(
+          'table',
+          node as MarkdownPreviewPositionNode,
+          <table {...props}>{children}</table>
+        ),
+      li: ({ node, children, ...props }) => {
+        const positionNode = node as MarkdownPreviewPositionNode
+        const range = hasMarkdownPreviewNestedBlock(positionNode)
+          ? null
+          : getMarkdownPreviewBlockRange(positionNode)
+        if (!range) {
+          return <li {...props}>{children}</li>
+        }
+        const blockKey = `li:${range.startLine}-${range.endLine}`
         return (
+          <li {...props}>
+            {children}
+            {renderAnnotationControls(range, blockKey)}
+          </li>
+        )
+      },
+      h1: ({ node, children, ...props }) => {
+        const id = createMarkdownPreviewHeadingId(getMarkdownPreviewNodeText(children), slugger)
+        return wrapAnnotatedBlock(
+          'h1',
+          node as MarkdownPreviewPositionNode,
           <h1 {...props} id={id} tabIndex={-1}>
             {children}
           </h1>
         )
       },
-      h2: ({ children, ...props }) => {
+      h2: ({ node, children, ...props }) => {
         const id = createMarkdownPreviewHeadingId(getMarkdownPreviewNodeText(children), slugger)
-        return (
+        return wrapAnnotatedBlock(
+          'h2',
+          node as MarkdownPreviewPositionNode,
           <h2 {...props} id={id} tabIndex={-1}>
             {children}
           </h2>
         )
       },
-      h3: ({ children, ...props }) => {
+      h3: ({ node, children, ...props }) => {
         const id = createMarkdownPreviewHeadingId(getMarkdownPreviewNodeText(children), slugger)
-        return (
+        return wrapAnnotatedBlock(
+          'h3',
+          node as MarkdownPreviewPositionNode,
           <h3 {...props} id={id} tabIndex={-1}>
             {children}
           </h3>
         )
       },
-      h4: ({ children, ...props }) => {
+      h4: ({ node, children, ...props }) => {
         const id = createMarkdownPreviewHeadingId(getMarkdownPreviewNodeText(children), slugger)
-        return (
+        return wrapAnnotatedBlock(
+          'h4',
+          node as MarkdownPreviewPositionNode,
           <h4 {...props} id={id} tabIndex={-1}>
             {children}
           </h4>
         )
       },
-      h5: ({ children, ...props }) => {
+      h5: ({ node, children, ...props }) => {
         const id = createMarkdownPreviewHeadingId(getMarkdownPreviewNodeText(children), slugger)
-        return (
+        return wrapAnnotatedBlock(
+          'h5',
+          node as MarkdownPreviewPositionNode,
           <h5 {...props} id={id} tabIndex={-1}>
             {children}
           </h5>
         )
       },
-      h6: ({ children, ...props }) => {
+      h6: ({ node, children, ...props }) => {
         const id = createMarkdownPreviewHeadingId(getMarkdownPreviewNodeText(children), slugger)
-        return (
+        return wrapAnnotatedBlock(
+          'h6',
+          node as MarkdownPreviewPositionNode,
           <h6 {...props} id={id} tabIndex={-1}>
             {children}
           </h6>
@@ -809,6 +1026,7 @@ export default function MarkdownPreview({
     onOpenDocument,
     openFile,
     openMarkdownPreview,
+    renderAnnotationControls,
     scrollToAnchor,
     setMarkdownViewMode,
     setPendingEditorReveal,
@@ -816,7 +1034,8 @@ export default function MarkdownPreview({
     sourceRuntimeEnvironmentId,
     sourceWorktree,
     worktreeRoot,
-    worktreesByRepo
+    worktreesByRepo,
+    wrapAnnotatedBlock
   ])
 
   return (
@@ -951,3 +1170,83 @@ export default function MarkdownPreview({
     </div>
   )
 }
+
+function MarkdownAnnotationComposer({
+  lineNumber,
+  startLine,
+  onCancel,
+  onSubmit
+}: {
+  lineNumber: number
+  startLine?: number
+  onCancel: () => void
+  onSubmit: (body: string) => Promise<boolean>
+}): React.JSX.Element {
+  const [body, setBody] = useState('')
+  const [submitting, setSubmitting] = useState(false)
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null)
+
+  useEffect(() => {
+    textareaRef.current?.focus()
+  }, [])
+
+  const label =
+    startLine !== undefined && startLine !== lineNumber
+      ? `Lines ${startLine}-${lineNumber}`
+      : `Line ${lineNumber}`
+  const trimmed = body.trim()
+
+  const submit = async (): Promise<void> => {
+    if (submitting || !trimmed) {
+      return
+    }
+    setSubmitting(true)
+    try {
+      const ok = await onSubmit(trimmed)
+      if (ok) {
+        setBody('')
+      }
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  return (
+    <div className="markdown-annotation-composer" onClick={(event) => event.stopPropagation()}>
+      <div className="orca-diff-comment-popover-label">{label}</div>
+      <textarea
+        ref={textareaRef}
+        className="orca-diff-comment-popover-textarea"
+        placeholder="Add note for the AI"
+        value={body}
+        onChange={(event) => {
+          setBody(event.target.value)
+          const el = event.currentTarget
+          el.style.height = 'auto'
+          el.style.height = `${Math.min(el.scrollHeight, 240)}px`
+        }}
+        onKeyDown={(event) => {
+          if (event.key === 'Escape') {
+            event.preventDefault()
+            onCancel()
+            return
+          }
+          if (event.key === 'Enter' && !event.nativeEvent.isComposing && !event.shiftKey) {
+            event.preventDefault()
+            void submit()
+          }
+        }}
+        rows={3}
+      />
+      <div className="orca-diff-comment-popover-footer">
+        <Button variant="ghost" size="sm" onClick={onCancel} disabled={submitting}>
+          Cancel
+        </Button>
+        <Button size="sm" onClick={() => void submit()} disabled={submitting || !trimmed}>
+          {submitting ? 'Saving…' : 'Add note'}
+          {!submitting && <CornerDownLeft className="ml-1 size-3 opacity-70" />}
+        </Button>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/editor/MonacoEditor.tsx b/src/renderer/src/components/editor/MonacoEditor.tsx
index 404867084f7..fe966e7730b 100644
--- a/src/renderer/src/components/editor/MonacoEditor.tsx
+++ b/src/renderer/src/components/editor/MonacoEditor.tsx
@@ -1,4 +1,7 @@
-import React, { useRef, useCallback, useEffect, useLayoutEffect, useState } from 'react'
+/* eslint-disable max-lines -- Why: MonacoEditor centralizes Monaco setup,
+source-mode markdown annotations, persistence-safe content sync, reveal
+handling, and editor-local UI overlays so split-pane state remains coherent. */
+import React, { useRef, useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react'
 import Editor, { type OnMount } from '@monaco-editor/react'
 import type { editor } from 'monaco-editor'
 import type { MarkdownDocument } from '../../../../shared/types'
@@ -25,6 +28,11 @@ import {
   createMarkdownDocLinkDecorationController,
   type MarkdownDocLinkDecorationController
 } from './monaco-markdown-doc-link-decorations'
+import { findWorktreeById } from '@/store/slices/worktree-helpers'
+import type { DiffComment } from '../../../../shared/types'
+import { isMarkdownComment } from '@/lib/diff-comment-compat'
+import { useDiffCommentDecorator } from '../diff-comments/useDiffCommentDecorator'
+import { DiffCommentPopover } from '../diff-comments/DiffCommentPopover'
 
 type MonacoEditorProps = {
   filePath: string
@@ -38,6 +46,8 @@ type MonacoEditorProps = {
   revealColumn?: number
   revealMatchLength?: number
   markdownDocuments?: MarkdownDocument[]
+  worktreeId?: string
+  markdownAnnotationsEnabled?: boolean
 }
 
 export default function MonacoEditor({
@@ -51,9 +61,12 @@ export default function MonacoEditor({
   revealLine,
   revealColumn,
   revealMatchLength,
-  markdownDocuments
+  markdownDocuments,
+  worktreeId,
+  markdownAnnotationsEnabled = false
 }: MonacoEditorProps): React.JSX.Element {
   const editorRef = useRef<editor.IStandaloneCodeEditor | null>(null)
+  const [mountedEditor, setMountedEditor] = useState<editor.IStandaloneCodeEditor | null>(null)
   const modelKeyRef = useRef<string | null>(null)
   const languageRef = useRef(language)
   languageRef.current = language
@@ -79,15 +92,33 @@ export default function MonacoEditor({
   const editorFontZoomLevel = useAppStore((s) => s.editorFontZoomLevel)
   const setPendingEditorReveal = useAppStore((s) => s.setPendingEditorReveal)
   const setEditorCursorLine = useAppStore((s) => s.setEditorCursorLine)
+  const addDiffComment = useAppStore((s) => s.addDiffComment)
+  const deleteDiffComment = useAppStore((s) => s.deleteDiffComment)
+  const updateDiffComment = useAppStore((s) => s.updateDiffComment)
+  const scrollToDiffCommentId = useAppStore((s) => s.scrollToDiffCommentId)
+  const setScrollToDiffCommentId = useAppStore((s) => s.setScrollToDiffCommentId)
+  const allDiffComments = useAppStore((s): DiffComment[] | undefined =>
+    worktreeId ? findWorktreeById(s.worktreesByRepo, worktreeId)?.diffComments : undefined
+  )
   const editorFontSize = computeEditorFontSize(
     settings?.terminalFontSize ?? 13,
     editorFontZoomLevel
   )
+  const markdownComments = useMemo(
+    () =>
+      (allDiffComments ?? []).filter((c) => c.filePath === relativePath && isMarkdownComment(c)),
+    [allDiffComments, relativePath]
+  )
 
   // Gutter context menu state
   const [gutterMenuOpen, setGutterMenuOpen] = useState(false)
   const [gutterMenuPoint, setGutterMenuPoint] = useState({ x: 0, y: 0 })
   const [gutterMenuLine, setGutterMenuLine] = useState(1)
+  const [commentPopover, setCommentPopover] = useState<{
+    lineNumber: number
+    startLine?: number
+    top: number
+  } | null>(null)
   const isDark =
     settings?.theme === 'dark' ||
     (settings?.theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches)
@@ -108,6 +139,35 @@ export default function MonacoEditor({
     }
   }, [language, markdownDocuments])
 
+  const shouldShowMarkdownAnnotations =
+    markdownAnnotationsEnabled && language === 'markdown' && Boolean(worktreeId)
+
+  const pendingScrollForThisEditor = useMemo(() => {
+    if (!shouldShowMarkdownAnnotations || !scrollToDiffCommentId) {
+      return null
+    }
+    return markdownComments.some((c) => c.id === scrollToDiffCommentId)
+      ? scrollToDiffCommentId
+      : null
+  }, [markdownComments, scrollToDiffCommentId, shouldShowMarkdownAnnotations])
+
+  useDiffCommentDecorator({
+    editor: shouldShowMarkdownAnnotations ? mountedEditor : null,
+    filePath: relativePath,
+    worktreeId: worktreeId ?? '',
+    comments: shouldShowMarkdownAnnotations ? markdownComments : [],
+    onAddCommentClick: ({ lineNumber, startLine, top }) =>
+      setCommentPopover({ lineNumber, startLine, top }),
+    onDeleteComment: (id) => {
+      if (worktreeId) {
+        void deleteDiffComment(worktreeId, id)
+      }
+    },
+    onUpdateComment: worktreeId ? (id, body) => updateDiffComment(worktreeId, id, body) : undefined,
+    pendingScrollCommentId: pendingScrollForThisEditor,
+    onPendingScrollConsumed: () => setScrollToDiffCommentId(null)
+  })
+
   const clearTransientRevealHighlight = useCallback(() => {
     if (revealHighlightTimerRef.current !== null) {
       clearTimeout(revealHighlightTimerRef.current)
@@ -186,6 +246,7 @@ export default function MonacoEditor({
   const handleMount: OnMount = useCallback(
     (editorInstance, monaco) => {
       editorRef.current = editorInstance
+      setMountedEditor(editorInstance)
       markdownDocLinkDecorationsRef.current = createMarkdownDocLinkDecorationController(
         editorInstance,
         () => languageRef.current
@@ -229,6 +290,12 @@ export default function MonacoEditor({
         })
       })
 
+      editorInstance.onDidDispose(() => {
+        editorRef.current = null
+        setMountedEditor(null)
+        setCommentPopover(null)
+      })
+
       // Why: Writing to the Map at 60fps (every scroll frame) is unnecessary since
       // we only need the final position when the user stops scrolling or switches
       // tabs. A trailing throttle of ~150ms captures the resting position while
@@ -302,6 +369,44 @@ export default function MonacoEditor({
     ]
   )
 
+  useEffect(() => {
+    if (!mountedEditor || !commentPopover) {
+      return
+    }
+    const update = (): void => {
+      const top =
+        mountedEditor.getTopForLineNumber(commentPopover.lineNumber) - mountedEditor.getScrollTop()
+      setCommentPopover((prev) => (prev ? { ...prev, top } : prev))
+    }
+    const scrollSub = mountedEditor.onDidScrollChange(update)
+    const contentSub = mountedEditor.onDidContentSizeChange(update)
+    return () => {
+      scrollSub.dispose()
+      contentSub.dispose()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- match DiffViewer: don't resubscribe on top updates.
+  }, [mountedEditor, commentPopover?.lineNumber])
+
+  const handleSubmitMarkdownComment = async (body: string): Promise<void> => {
+    if (!commentPopover || !worktreeId) {
+      return
+    }
+    const result = await addDiffComment({
+      worktreeId,
+      filePath: relativePath,
+      source: 'markdown',
+      startLine: commentPopover.startLine,
+      lineNumber: commentPopover.lineNumber,
+      body,
+      side: 'modified'
+    })
+    if (result) {
+      setCommentPopover(null)
+    } else {
+      console.error('Failed to add markdown comment — draft preserved')
+    }
+  }
+
   const handleChange = useCallback(
     (value: string | undefined) => {
       if (value !== undefined) {
@@ -442,6 +547,16 @@ export default function MonacoEditor({
 
   return (
     <div className="relative h-full">
+      {commentPopover && shouldShowMarkdownAnnotations && (
+        <DiffCommentPopover
+          key={commentPopover.lineNumber}
+          lineNumber={commentPopover.lineNumber}
+          startLine={commentPopover.startLine}
+          top={commentPopover.top}
+          onCancel={() => setCommentPopover(null)}
+          onSubmit={handleSubmitMarkdownComment}
+        />
+      )}
       <Editor
         height="100%"
         language={language}
diff --git a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
index cae02a249fe..8ea4d0fa4c8 100644
--- a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
+++ b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
@@ -41,11 +41,7 @@ import {
 import { parseGitLabIssueOrMRLink } from '@/lib/gitlab-links'
 import { cn } from '@/lib/utils'
 import { LinearIcon } from '@/components/icons/LinearIcon'
-import type {
-  GitHubWorkItem,
-  GitLabWorkItem,
-  LinearIssue
-} from '../../../../shared/types'
+import type { GitHubWorkItem, GitLabWorkItem, LinearIssue } from '../../../../shared/types'
 
 type SmartNameMode = 'smart' | 'github' | 'gitlab' | 'branches' | 'linear' | 'text'
 
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index ccfffb88c1d..da59a37e7ce 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -88,6 +88,7 @@ import {
 } from '@/components/ui/dialog'
 import { BaseRefPicker } from '@/components/settings/BaseRefPicker'
 import { formatDiffComment, formatDiffComments } from '@/lib/diff-comments-format'
+import { getDiffCommentLineLabel, getDiffCommentSource } from '@/lib/diff-comment-compat'
 import { QuickLaunchAgentMenuItems } from '@/components/tab-bar/QuickLaunchButton'
 import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
 import {
@@ -265,6 +266,8 @@ function SourceControlInner(): React.JSX.Element {
   const openDiff = useAppStore((s) => s.openDiff)
   const openFile = useAppStore((s) => s.openFile)
   const setEditorViewMode = useAppStore((s) => s.setEditorViewMode)
+  const setMarkdownViewMode = useAppStore((s) => s.setMarkdownViewMode)
+  const setPendingEditorReveal = useAppStore((s) => s.setPendingEditorReveal)
   const openConflictFile = useAppStore((s) => s.openConflictFile)
   const openConflictReview = useAppStore((s) => s.openConflictReview)
   const openBranchDiff = useAppStore((s) => s.openBranchDiff)
@@ -464,7 +467,9 @@ function SourceControlInner(): React.JSX.Element {
     activeRepo && branchName
       ? getHostedReviewCacheKey(activeRepo.path, branchName, settings, activeRepo.id)
       : null
-  const hostedReviewEntry = hostedReviewCacheKey ? hostedReviewCache[hostedReviewCacheKey] : undefined
+  const hostedReviewEntry = hostedReviewCacheKey
+    ? hostedReviewCache[hostedReviewCacheKey]
+    : undefined
   const hostedReview: HostedReviewInfo | null = hostedReviewCacheKey
     ? (hostedReviewEntry?.data ?? null)
     : null
@@ -1424,13 +1429,41 @@ function SourceControlInner(): React.JSX.Element {
   // first, so the editor-tab fallback then leaves the global null and a
   // future DiffViewer mount can't accidentally consume a stale id.
   const handleOpenComment = useCallback(
-    (filePath: string, commentId?: string) => {
+    (comment: DiffComment) => {
       if (!activeWorktreeId || !worktreePath) {
         return
       }
+      const filePath = comment.filePath
+      const commentId = comment.id
       // Defensively clear any dangling prior scroll request before routing
       // this click; only the diff branches below will re-stamp it.
       setScrollToDiffCommentId(null)
+      if (getDiffCommentSource(comment) === 'markdown') {
+        const absPath = joinPath(worktreePath, filePath)
+        const language = detectLanguage(filePath)
+        setEditorViewMode(absPath, 'edit')
+        setMarkdownViewMode(absPath, 'source')
+        openFile({
+          filePath: absPath,
+          relativePath: filePath,
+          worktreeId: activeWorktreeId,
+          language,
+          mode: 'edit'
+        })
+        setPendingEditorReveal(null)
+        requestAnimationFrame(() => {
+          requestAnimationFrame(() => {
+            setPendingEditorReveal({
+              filePath: absPath,
+              line: comment.lineNumber,
+              column: 1,
+              matchLength: 0
+            })
+            setScrollToDiffCommentId(commentId)
+          })
+        })
+        return
+      }
       const matches = entries.filter((e) => e.path === filePath)
       const uncommitted =
         matches.find((e) => e.area === 'unstaged') ??
@@ -1482,6 +1515,8 @@ function SourceControlInner(): React.JSX.Element {
       openFile,
       setEditorViewMode,
       setScrollToDiffCommentId,
+      setMarkdownViewMode,
+      setPendingEditorReveal,
       worktreePath
     ]
   )
@@ -1859,7 +1894,7 @@ function SourceControlInner(): React.JSX.Element {
                     groupId={activeGroupId ?? activeWorktreeId}
                     onFocusTerminal={focusTerminalTabSurface}
                     prompt={diffCommentsPrompt}
-                    launchSource="diff_notes_send"
+                    launchSource="notes_send"
                   />
                 </DropdownMenuContent>
               </DropdownMenu>
@@ -1891,7 +1926,7 @@ function SourceControlInner(): React.JSX.Element {
               <DiffCommentsInlineList
                 comments={diffCommentsForActive}
                 onDelete={(id) => void deleteDiffComment(activeWorktreeId, id)}
-                onOpen={(filePath, commentId) => handleOpenComment(filePath, commentId)}
+                onOpen={(comment) => handleOpenComment(comment)}
               />
             )}
           </div>
@@ -2740,7 +2775,7 @@ function DiffCommentsInlineList({
   // Why: clicking the note row navigates the user to that file's diff (or
   // editor as a fallback) and, when a `commentId` is supplied, scrolls the
   // diff to that specific note via the scrollToDiffCommentId UI slice.
-  onOpen: (filePath: string, commentId?: string) => void
+  onOpen: (comment: DiffComment) => void
 }): React.JSX.Element {
   // Why: group by filePath so the inline list mirrors the structure in the
   // Notes tab — a compact section per file with line-number prefixes.
@@ -2794,7 +2829,12 @@ function DiffCommentsInlineList({
           <button
             type="button"
             className="block w-full truncate text-left text-[10px] font-medium text-muted-foreground hover:text-foreground"
-            onClick={() => onOpen(filePath)}
+            onClick={() => {
+              const first = list[0]
+              if (first) {
+                onOpen(first)
+              }
+            }}
             title={`Open ${filePath}`}
           >
             {filePath}
@@ -2814,12 +2854,15 @@ function DiffCommentsInlineList({
                   // for buttons and lets bubbled key events from the children
                   // fire the row's open handler.
                   className="flex min-w-0 flex-1 cursor-pointer items-center gap-1.5 rounded text-left"
-                  onClick={() => onOpen(c.filePath, c.id)}
-                  title={`Open ${c.filePath} (line ${c.lineNumber})`}
-                  aria-label={`Open note on line ${c.lineNumber}`}
+                  onClick={() => onOpen(c)}
+                  title={`Open ${c.filePath} (${getDiffCommentLineLabel(c).toLowerCase()})`}
+                  aria-label={`Open note on ${getDiffCommentLineLabel(c).toLowerCase()}`}
                 >
                   <span className="shrink-0 rounded bg-muted px-1 py-0.5 text-[10px] leading-none tabular-nums text-muted-foreground">
-                    L{c.lineNumber}
+                    {getDiffCommentLineLabel(c, true)}
+                  </span>
+                  <span className="shrink-0 rounded bg-muted/70 px-1 py-0.5 text-[10px] leading-none text-muted-foreground">
+                    {getDiffCommentSource(c) === 'markdown' ? 'MD' : 'Diff'}
                   </span>
                   <span className="block min-w-0 flex-1 whitespace-pre-wrap break-words text-[11px] leading-snug text-foreground">
                     {c.body}
diff --git a/src/renderer/src/lib/diff-comment-compat.test.ts b/src/renderer/src/lib/diff-comment-compat.test.ts
new file mode 100644
index 00000000000..48b6e3b22b3
--- /dev/null
+++ b/src/renderer/src/lib/diff-comment-compat.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest'
+import type { DiffComment } from '../../../shared/types'
+import {
+  getDiffCommentLineLabel,
+  getDiffCommentSource,
+  isDiffComment,
+  isMarkdownComment
+} from './diff-comment-compat'
+
+function makeComment(overrides: Partial<DiffComment> = {}): DiffComment {
+  return {
+    id: 'c1',
+    worktreeId: 'wt1',
+    filePath: 'README.md',
+    lineNumber: 4,
+    body: 'note',
+    createdAt: 0,
+    side: 'modified',
+    ...overrides
+  }
+}
+
+describe('diff comment compatibility helpers', () => {
+  it('routes legacy comments with no source as diff comments', () => {
+    const comment = makeComment()
+    expect(getDiffCommentSource(comment)).toBe('diff')
+    expect(isDiffComment(comment)).toBe(true)
+    expect(isMarkdownComment(comment)).toBe(false)
+  })
+
+  it('routes markdown comments by explicit source', () => {
+    const comment = makeComment({ source: 'markdown' })
+    expect(getDiffCommentSource(comment)).toBe('markdown')
+    expect(isMarkdownComment(comment)).toBe(true)
+    expect(isDiffComment(comment)).toBe(false)
+  })
+
+  it('formats compact and full range labels', () => {
+    const comment = makeComment({ startLine: 2, lineNumber: 4 })
+    expect(getDiffCommentLineLabel(comment)).toBe('Lines 2-4')
+    expect(getDiffCommentLineLabel(comment, true)).toBe('L2-L4')
+  })
+})
diff --git a/src/renderer/src/lib/diff-comment-compat.ts b/src/renderer/src/lib/diff-comment-compat.ts
new file mode 100644
index 00000000000..ed88baf0dd0
--- /dev/null
+++ b/src/renderer/src/lib/diff-comment-compat.ts
@@ -0,0 +1,25 @@
+import type { DiffComment, DiffCommentSource } from '../../../shared/types'
+
+export function getDiffCommentSource(comment: Pick<DiffComment, 'source'>): DiffCommentSource {
+  return comment.source === 'markdown' ? 'markdown' : 'diff'
+}
+
+export function isDiffComment(comment: Pick<DiffComment, 'source'>): boolean {
+  return getDiffCommentSource(comment) === 'diff'
+}
+
+export function isMarkdownComment(comment: Pick<DiffComment, 'source'>): boolean {
+  return getDiffCommentSource(comment) === 'markdown'
+}
+
+export function getDiffCommentLineLabel(
+  comment: Pick<DiffComment, 'lineNumber' | 'startLine'>,
+  compact = false
+): string {
+  if (comment.startLine !== undefined && comment.startLine !== comment.lineNumber) {
+    return compact
+      ? `L${comment.startLine}-L${comment.lineNumber}`
+      : `Lines ${comment.startLine}-${comment.lineNumber}`
+  }
+  return compact ? `L${comment.lineNumber}` : `Line ${comment.lineNumber}`
+}
diff --git a/src/renderer/src/lib/diff-comments-format.test.ts b/src/renderer/src/lib/diff-comments-format.test.ts
index 2b492ed7a24..5a692727165 100644
--- a/src/renderer/src/lib/diff-comments-format.test.ts
+++ b/src/renderer/src/lib/diff-comments-format.test.ts
@@ -23,6 +23,32 @@ describe('formatDiffComment', () => {
     )
   })
 
+  it('keeps explicit diff comments without ranges in the legacy format', () => {
+    const out = formatDiffComment(makeComment({ source: 'diff' }))
+    expect(out).toBe(
+      ['File: src/app.ts', 'Line: 10', 'User comment: "Needs validation"'].join('\n')
+    )
+  })
+
+  it('formats persisted ranges when startLine is present', () => {
+    const out = formatDiffComment(makeComment({ source: 'diff', startLine: 7 }))
+    expect(out).toBe(
+      ['File: src/app.ts', 'Lines: 7-10', 'User comment: "Needs validation"'].join('\n')
+    )
+  })
+
+  it('adds markdown source metadata for markdown notes', () => {
+    const out = formatDiffComment(makeComment({ source: 'markdown', startLine: 8 }))
+    expect(out).toBe(
+      [
+        'File: src/app.ts',
+        'Source: markdown',
+        'Lines: 8-10',
+        'User comment: "Needs validation"'
+      ].join('\n')
+    )
+  })
+
   it('escapes embedded quotes in the body', () => {
     const out = formatDiffComment(makeComment({ body: 'why "this" path?' }))
     expect(out).toContain('User comment: "why \\"this\\" path?"')
diff --git a/src/renderer/src/lib/diff-comments-format.ts b/src/renderer/src/lib/diff-comments-format.ts
index 0afd4c8dd7f..1af7ea9dcd7 100644
--- a/src/renderer/src/lib/diff-comments-format.ts
+++ b/src/renderer/src/lib/diff-comments-format.ts
@@ -1,4 +1,5 @@
 import type { DiffComment } from '../../../shared/types'
+import { isMarkdownComment } from './diff-comment-compat'
 
 // Why: the pasted format is the contract between this feature and whatever
 // agent consumes it. Keep it stable and deterministic — quote escaping matters
@@ -10,7 +11,16 @@ export function formatDiffComment(c: DiffComment): string {
     .replace(/"/g, '\\"')
     .replace(/\r/g, '\\r')
     .replace(/\n/g, '\\n')
-  return [`File: ${c.filePath}`, `Line: ${c.lineNumber}`, `User comment: "${escaped}"`].join('\n')
+  const lineLabel =
+    c.startLine !== undefined && c.startLine !== c.lineNumber
+      ? `Lines: ${c.startLine}-${c.lineNumber}`
+      : `Line: ${c.lineNumber}`
+  if (!isMarkdownComment(c)) {
+    return [`File: ${c.filePath}`, lineLabel, `User comment: "${escaped}"`].join('\n')
+  }
+  return [`File: ${c.filePath}`, 'Source: markdown', lineLabel, `User comment: "${escaped}"`].join(
+    '\n'
+  )
 }
 
 export function formatDiffComments(comments: DiffComment[]): string {
diff --git a/src/renderer/src/lib/markdown-comment-blocks.test.ts b/src/renderer/src/lib/markdown-comment-blocks.test.ts
new file mode 100644
index 00000000000..f3b0443d6ea
--- /dev/null
+++ b/src/renderer/src/lib/markdown-comment-blocks.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import type { DiffComment } from '../../../shared/types'
+import { mapMarkdownCommentsToBlocks, type MarkdownCommentBlock } from './markdown-comment-blocks'
+
+function makeComment(overrides: Partial<DiffComment> = {}): DiffComment {
+  return {
+    id: 'c1',
+    worktreeId: 'wt1',
+    filePath: 'README.md',
+    source: 'markdown',
+    lineNumber: 4,
+    body: 'note',
+    createdAt: 0,
+    side: 'modified',
+    ...overrides
+  }
+}
+
+describe('mapMarkdownCommentsToBlocks', () => {
+  it('maps comments to the rendered block that owns their anchor line', () => {
+    const blocks: MarkdownCommentBlock[] = [
+      { key: 'p:2-3', startLine: 2, endLine: 3 },
+      { key: 'p:4-6', startLine: 4, endLine: 6 }
+    ]
+    const mapped = mapMarkdownCommentsToBlocks([makeComment({ id: 'a', lineNumber: 5 })], blocks)
+
+    expect(mapped.byBlockKey.get('p:4-6')?.map((comment) => comment.id)).toEqual(['a'])
+    expect(mapped.unresolved).toEqual([])
+  })
+
+  it('keeps comments without a rendered block unresolved for shelf fallback', () => {
+    const blocks: MarkdownCommentBlock[] = [{ key: 'p:2-3', startLine: 2, endLine: 3 }]
+    const mapped = mapMarkdownCommentsToBlocks(
+      [makeComment({ id: 'stale', lineNumber: 20 })],
+      blocks
+    )
+
+    expect(mapped.byBlockKey.size).toBe(0)
+    expect(mapped.unresolved.map((comment) => comment.id)).toEqual(['stale'])
+  })
+})
diff --git a/src/renderer/src/lib/markdown-comment-blocks.ts b/src/renderer/src/lib/markdown-comment-blocks.ts
new file mode 100644
index 00000000000..59d11ed4402
--- /dev/null
+++ b/src/renderer/src/lib/markdown-comment-blocks.ts
@@ -0,0 +1,40 @@
+import type { DiffComment } from '../../../shared/types'
+
+export type MarkdownCommentBlock = {
+  key: string
+  startLine: number
+  endLine: number
+}
+
+export type MarkdownCommentBlockMapping = {
+  byBlockKey: Map<string, DiffComment[]>
+  unresolved: DiffComment[]
+}
+
+export function mapMarkdownCommentsToBlocks(
+  comments: DiffComment[],
+  blocks: MarkdownCommentBlock[]
+): MarkdownCommentBlockMapping {
+  const byBlockKey = new Map<string, DiffComment[]>()
+  const unresolved: DiffComment[] = []
+
+  for (const comment of comments) {
+    const block = blocks.find(
+      (candidate) =>
+        candidate.startLine <= comment.lineNumber && comment.lineNumber <= candidate.endLine
+    )
+    if (!block) {
+      unresolved.push(comment)
+      continue
+    }
+    const list = byBlockKey.get(block.key) ?? []
+    list.push(comment)
+    byBlockKey.set(block.key, list)
+  }
+
+  for (const list of byBlockKey.values()) {
+    list.sort((a, b) => a.lineNumber - b.lineNumber)
+  }
+
+  return { byBlockKey, unresolved }
+}
diff --git a/src/renderer/src/store/slices/diffComments.test.ts b/src/renderer/src/store/slices/diffComments.test.ts
index 22ba47359e3..f41a4750357 100644
--- a/src/renderer/src/store/slices/diffComments.test.ts
+++ b/src/renderer/src/store/slices/diffComments.test.ts
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Why: this test file owns the diff-comments
+slice's persistence, runtime routing, rollback, and compatibility behavior. */
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { create } from 'zustand'
 import type { AppState } from '../types'
@@ -171,6 +173,61 @@ function seed(store: ReturnType<typeof createTestStore>, comments: DiffComment[]
   })
 }
 
+describe('addDiffComment', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    clearRuntimeCompatibilityCacheForTests()
+    runtimeEnvironmentTransportCall.mockReset()
+    runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+      return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+    })
+    updateMeta.mockResolvedValue({})
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-1',
+      ok: true,
+      result: { ok: true },
+      _meta: { runtimeId: 'remote-runtime' }
+    })
+  })
+
+  it('persists source and startLine for ranged comments', async () => {
+    const store = createTestStore()
+    seed(store, [])
+
+    const saved = await store.getState().addDiffComment({
+      worktreeId: WT,
+      filePath: 'README.md',
+      source: 'markdown',
+      startLine: 2,
+      lineNumber: 4,
+      body: 'range note',
+      side: 'modified'
+    })
+
+    expect(saved).toEqual(
+      expect.objectContaining({
+        filePath: 'README.md',
+        source: 'markdown',
+        startLine: 2,
+        lineNumber: 4,
+        body: 'range note'
+      })
+    )
+    expect(updateMeta).toHaveBeenCalledWith({
+      worktreeId: WT,
+      updates: {
+        diffComments: [
+          expect.objectContaining({
+            source: 'markdown',
+            startLine: 2,
+            lineNumber: 4
+          })
+        ]
+      }
+    })
+  })
+})
+
 describe('updateDiffComment', () => {
   beforeEach(() => {
     vi.clearAllMocks()
diff --git a/src/renderer/src/store/slices/diffComments.ts b/src/renderer/src/store/slices/diffComments.ts
index 0a57741c8f4..410d0d7fbe2 100644
--- a/src/renderer/src/store/slices/diffComments.ts
+++ b/src/renderer/src/store/slices/diffComments.ts
@@ -16,6 +16,27 @@ function generateId(): string {
   return createBrowserUuid()
 }
 
+function normalizeDiffComment(comment: DiffComment): DiffComment {
+  const rawSource = (comment as { source?: unknown }).source
+  const source = rawSource === 'markdown' || rawSource === 'diff' ? rawSource : undefined
+  const rawStartLine = (comment as { startLine?: unknown }).startLine
+  const startLine =
+    Number.isInteger(rawStartLine) &&
+    typeof rawStartLine === 'number' &&
+    rawStartLine >= 1 &&
+    rawStartLine <= comment.lineNumber
+      ? rawStartLine
+      : undefined
+
+  return {
+    ...comment,
+    ...(source !== undefined ? { source } : {}),
+    ...(source === undefined ? { source: undefined } : {}),
+    ...(startLine !== undefined ? { startLine } : {}),
+    ...(startLine === undefined ? { startLine: undefined } : {})
+  }
+}
+
 // Why: return a stable reference when no comments exist so selectors don't
 // produce a fresh `[]` on every store update. A new array identity would
 // trigger re-renders in any consumer using referential equality.
@@ -70,7 +91,7 @@ function enqueuePersist(worktreeId: string, get: () => AppState): Promise<void>
     const repoId = getRepoIdFromWorktreeId(worktreeId)
     const repoList = get().worktreesByRepo[repoId]
     const target = repoList?.find((w) => w.id === worktreeId)
-    const latest = target?.diffComments ?? []
+    const latest = (target?.diffComments ?? []).map(normalizeDiffComment)
     await persist(get().settings, worktreeId, latest)
   }
   const next = prior.then(run, run)
@@ -196,11 +217,11 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
   },
 
   addDiffComment: async (input) => {
-    const comment: DiffComment = {
+    const comment: DiffComment = normalizeDiffComment({
       ...input,
       id: generateId(),
       createdAt: Date.now()
-    }
+    })
     const result = mutateComments(set, input.worktreeId, (existing) => [...existing, comment])
     if (!result) {
       return null
diff --git a/src/shared/telemetry-events.ts b/src/shared/telemetry-events.ts
index 1c79d526b8b..0d7ad55339c 100644
--- a/src/shared/telemetry-events.ts
+++ b/src/shared/telemetry-events.ts
@@ -133,6 +133,7 @@ export const launchSourceSchema = z.enum([
   'shortcut',
   'onboarding',
   'diff_notes_send',
+  'notes_send',
   'unknown'
 ])
 export type LaunchSource = z.infer<typeof launchSourceSchema>
diff --git a/src/shared/types.ts b/src/shared/types.ts
index c51c54e63ec..d4642212d5e 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -204,10 +204,16 @@ export type WorktreeMeta = {
 // a diff so they can be handed back to an AI agent (pasted into a terminal
 // or used to bootstrap a new agent session). Stored on WorktreeMeta so the
 // existing persistence layer writes them to orca-data.json automatically.
+export type DiffCommentSource = 'diff' | 'markdown'
+
 export type DiffComment = {
   id: string
   worktreeId: string
   filePath: string
+  /** Undefined means a legacy diff note. */
+  source?: DiffCommentSource
+  /** Inclusive range start. Must be <= lineNumber when present. */
+  startLine?: number
   lineNumber: number
   body: string
   createdAt: number

From ed97a8207f9543f2419a3e994282262c7e781617 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 12:44:37 -0700
Subject: [PATCH 59/82] fix: preserve restored working agent status (#1971)

---
 .../use-worktree-activity-status.test.tsx     | 91 +++++++++++++++++++
 .../sidebar/use-worktree-activity-status.ts   | 20 +++-
 src/renderer/src/lib/worktree-status.test.ts  | 22 +++++
 src/renderer/src/lib/worktree-status.ts       | 15 ++-
 4 files changed, 139 insertions(+), 9 deletions(-)
 create mode 100644 src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx

diff --git a/src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx b/src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx
new file mode 100644
index 00000000000..1fc614f9acb
--- /dev/null
+++ b/src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx
@@ -0,0 +1,91 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
+import type { TerminalTab } from '../../../../shared/types'
+import { useWorktreeActivityStatus } from './use-worktree-activity-status'
+
+type MockState = {
+  tabsByWorktree: Record<string, TerminalTab[]>
+  browserTabsByWorktree: Record<string, { id: string }[]>
+  runtimePaneTitlesByTabId: Record<string, Record<number, string>>
+  ptyIdsByTabId: Record<string, string[]>
+  agentStatusEpoch: number
+  agentStatusByPaneKey: Record<string, AgentStatusEntry>
+  retainedAgentsByPaneKey: Record<string, unknown>
+}
+
+let mockState: MockState
+
+vi.mock('@/store', () => ({
+  useAppStore: (selector: (state: MockState) => unknown) => selector(mockState)
+}))
+
+function makeTab(id: string, worktreeId: string): TerminalTab {
+  return {
+    id,
+    worktreeId,
+    ptyId: 'pty-1',
+    title: 'bash',
+    customTitle: null,
+    color: null,
+    sortOrder: 0,
+    createdAt: 0
+  }
+}
+
+function makeAgentStatusEntry(args: {
+  paneKey: string
+  state: AgentStatusEntry['state']
+}): AgentStatusEntry {
+  return {
+    paneKey: args.paneKey,
+    state: args.state,
+    prompt: '',
+    updatedAt: 1_000,
+    stateStartedAt: 1_000,
+    stateHistory: []
+  }
+}
+
+function StatusProbe({ worktreeId }: { worktreeId: string }) {
+  return <span>{useWorktreeActivityStatus(worktreeId)}</span>
+}
+
+describe('useWorktreeActivityStatus', () => {
+  beforeEach(() => {
+    vi.spyOn(Date, 'now').mockReturnValue(2_000)
+    mockState = {
+      tabsByWorktree: {},
+      browserTabsByWorktree: {},
+      runtimePaneTitlesByTabId: {},
+      ptyIdsByTabId: {},
+      agentStatusEpoch: 0,
+      agentStatusByPaneKey: {},
+      retainedAgentsByPaneKey: {}
+    }
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('keeps a restored offscreen working agent yellow from the hook snapshot', () => {
+    const worktreeId = 'repo1::/path/wt1'
+    mockState = {
+      ...mockState,
+      tabsByWorktree: {
+        [worktreeId]: [makeTab('tab-1', worktreeId)]
+      },
+      ptyIdsByTabId: {
+        'tab-1': ['pty-1']
+      },
+      agentStatusByPaneKey: {
+        'tab-1:1': makeAgentStatusEntry({ paneKey: 'tab-1:1', state: 'working' })
+      }
+    }
+
+    expect(renderToStaticMarkup(<StatusProbe worktreeId={worktreeId} />)).toBe(
+      '<span>working</span>'
+    )
+  })
+})
diff --git a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
index af547f8e886..882fb13df96 100644
--- a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
@@ -21,14 +21,15 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
   const ptyIdsForWorktree = useAppStore(
     useShallow((s) => selectLivePtyIdsForWorktree(s, worktreeId))
   )
-  const { hasPermission, hasLiveDone, hasRetainedDone } = useAppStore(
+  const { hasPermission, hasLiveWorking, hasLiveDone, hasRetainedDone } = useAppStore(
     useShallow((s) => {
       // Touch the epoch so this selector re-runs when a fresh hook entry
       // crosses the stale boundary.
       void s.agentStatusEpoch
       const wtTabs = s.tabsByWorktree[worktreeId] ?? EMPTY_TABS
       let perm = false
-      let live = false
+      let working = false
+      let done = false
       if (wtTabs.length > 0) {
         const tabIds = new Set(wtTabs.map((tab) => tab.id))
         const now = Date.now()
@@ -42,8 +43,10 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
           }
           if (entry.state === 'blocked' || entry.state === 'waiting') {
             perm = true
+          } else if (entry.state === 'working') {
+            working = true
           } else if (entry.state === 'done') {
-            live = true
+            done = true
           }
         }
         for (const unsupported of Object.values(s.migrationUnsupportedByPtyId)) {
@@ -65,13 +68,18 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
           break
         }
       }
-      return { hasPermission: perm, hasLiveDone: live, hasRetainedDone: retained }
+      return {
+        hasPermission: perm,
+        hasLiveWorking: working,
+        hasLiveDone: done,
+        hasRetainedDone: retained
+      }
     })
   )
 
   // Why: compact and detailed cards need the same status-dot semantics:
   // runtime liveness gates title-derived states, then explicit agent rows can
-  // promote permission/done so the dot matches visible agent state.
+  // promote working/permission/done so the dot matches visible agent state.
   return useMemo(
     () =>
       resolveWorktreeStatus({
@@ -80,6 +88,7 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
         ptyIdsByTabId: ptyIdsForWorktree,
         runtimePaneTitlesByTabId: runtimePaneTitlesForWorktree,
         hasPermission,
+        hasLiveWorking,
         hasLiveDone,
         hasRetainedDone
       }),
@@ -89,6 +98,7 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
       ptyIdsForWorktree,
       runtimePaneTitlesForWorktree,
       hasPermission,
+      hasLiveWorking,
       hasLiveDone,
       hasRetainedDone
     ]
diff --git a/src/renderer/src/lib/worktree-status.test.ts b/src/renderer/src/lib/worktree-status.test.ts
index 681bc1e74cd..b955f7a4322 100644
--- a/src/renderer/src/lib/worktree-status.test.ts
+++ b/src/renderer/src/lib/worktree-status.test.ts
@@ -86,6 +86,7 @@ describe('resolveWorktreeStatus', () => {
       // Slept: live-pty array empty; tab.ptyId would be the wake-hint sessionId.
       ptyIdsByTabId: { 'tab-1': [] },
       hasPermission: false,
+      hasLiveWorking: false,
       hasLiveDone: false,
       hasRetainedDone: false
     })
@@ -99,6 +100,7 @@ describe('resolveWorktreeStatus', () => {
       browserTabs: [],
       ptyIdsByTabId: { 'tab-1': [] },
       hasPermission: false,
+      hasLiveWorking: false,
       hasLiveDone: false,
       hasRetainedDone: true
     })
@@ -112,6 +114,7 @@ describe('resolveWorktreeStatus', () => {
       browserTabs: [],
       ptyIdsByTabId: { 'tab-1': [] },
       hasPermission: true,
+      hasLiveWorking: false,
       hasLiveDone: false,
       hasRetainedDone: false
     })
@@ -125,6 +128,7 @@ describe('resolveWorktreeStatus', () => {
       browserTabs: [],
       ptyIdsByTabId: livePtyMap('tab-1'),
       hasPermission: true,
+      hasLiveWorking: false,
       hasLiveDone: false,
       hasRetainedDone: false
     })
@@ -132,12 +136,27 @@ describe('resolveWorktreeStatus', () => {
     expect(status).toBe('permission')
   })
 
+  it('promotes to working from a fresh explicit agent row before pane titles restore', () => {
+    const status = resolveWorktreeStatus({
+      tabs: [{ id: 'tab-1', title: 'bash' }],
+      browserTabs: [],
+      ptyIdsByTabId: livePtyMap('tab-1'),
+      hasPermission: false,
+      hasLiveWorking: true,
+      hasLiveDone: false,
+      hasRetainedDone: false
+    })
+
+    expect(status).toBe('working')
+  })
+
   it('lets heuristic working beat hasLiveDone (newer in-progress signal wins)', () => {
     const status = resolveWorktreeStatus({
       tabs: [{ id: 'tab-1', title: 'claude [working]' }],
       browserTabs: [],
       ptyIdsByTabId: livePtyMap('tab-1'),
       hasPermission: false,
+      hasLiveWorking: false,
       hasLiveDone: true,
       hasRetainedDone: false
     })
@@ -156,6 +175,7 @@ describe('resolveWorktreeStatus', () => {
       browserTabs: [],
       ptyIdsByTabId: livePtyMap('tab-1'),
       hasPermission: false,
+      hasLiveWorking: false,
       hasLiveDone: true,
       hasRetainedDone: false
     })
@@ -169,6 +189,7 @@ describe('resolveWorktreeStatus', () => {
       browserTabs: [],
       ptyIdsByTabId: livePtyMap('tab-1'),
       hasPermission: false,
+      hasLiveWorking: false,
       hasLiveDone: false,
       hasRetainedDone: true
     })
@@ -182,6 +203,7 @@ describe('resolveWorktreeStatus', () => {
       browserTabs: [],
       ptyIdsByTabId: livePtyMap('tab-1'),
       hasPermission: false,
+      hasLiveWorking: false,
       hasLiveDone: false,
       hasRetainedDone: false
     })
diff --git a/src/renderer/src/lib/worktree-status.ts b/src/renderer/src/lib/worktree-status.ts
index 1f2380d6807..0c05cd2033d 100644
--- a/src/renderer/src/lib/worktree-status.ts
+++ b/src/renderer/src/lib/worktree-status.ts
@@ -78,9 +78,10 @@ export function getWorktreeStatusLabel(status: WorktreeStatus): string {
  * Apply the WorktreeCard priority overlay (permission > working > done >
  * heuristic) on top of the title-heuristic base. Live PTY liveness still gates
  * title-derived working/permission, but explicit agent rows are allowed to
- * promote the dot: if the sidebar shows a completed/blocking inline agent row,
- * the worktree status must agree with that visible row. Sleep cleanup owns
- * removing stale retained rows; once they are gone, no promotion occurs.
+ * promote the dot: if the sidebar shows a running/completed/blocking inline
+ * agent row, the worktree status must agree with that visible row. Sleep
+ * cleanup owns removing stale retained rows; once they are gone, no promotion
+ * occurs.
  *
  * Argument semantics (sourced by the WorktreeCard caller from the store):
  * - `tabs`, `browserTabs`: the worktree's terminal and browser tabs.
@@ -90,6 +91,8 @@ export function getWorktreeStatusLabel(status: WorktreeStatus): string {
  *   worktree (used by the title-heuristic for split-pane spinners).
  * - `hasPermission`: any fresh hook entry in {blocked, waiting} for a tab in
  *   this worktree.
+ * - `hasLiveWorking`: any fresh hook entry in {working} for a tab in this
+ *   worktree.
  * - `hasLiveDone`: any fresh hook entry in {done} for a tab in this worktree.
  * - `hasRetainedDone`: any retained-agent snapshot scoped to this worktreeId.
  */
@@ -99,6 +102,7 @@ export function resolveWorktreeStatus(args: {
   ptyIdsByTabId: Record<string, string[]>
   runtimePaneTitlesByTabId?: Record<string, Record<number, string>>
   hasPermission: boolean
+  hasLiveWorking: boolean
   hasLiveDone: boolean
   hasRetainedDone: boolean
 }): WorktreeStatus {
@@ -119,7 +123,10 @@ export function resolveWorktreeStatus(args: {
   if (heuristic === 'permission') {
     return 'permission'
   }
-  if (heuristic === 'working') {
+  // Why: restored-but-unfocused cards may have the startup hook snapshot before
+  // their terminal pane mounts and repopulates runtimePaneTitlesByTabId.
+  // Trust the fresh explicit working row so those cards stay yellow on restart.
+  if (args.hasLiveWorking || heuristic === 'working') {
     return 'working'
   }
   if (args.hasLiveDone || args.hasRetainedDone) {

From 9c601be19916f7023c2c5ad03bd9bd75d3538bba Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 12:49:53 -0700
Subject: [PATCH 60/82] Fix PR lookup during GitHub GraphQL limits (#1973)

---
 src/main/github/client.test.ts |  75 ++++++++++++++
 src/main/github/client.ts      | 180 ++++++++++++++++++++++++---------
 2 files changed, 205 insertions(+), 50 deletions(-)

diff --git a/src/main/github/client.test.ts b/src/main/github/client.test.ts
index 5880c738ffc..37b8241d565 100644
--- a/src/main/github/client.test.ts
+++ b/src/main/github/client.test.ts
@@ -42,6 +42,10 @@ vi.mock('./gh-utils', () => ({
   gitExecFileAsync: gitExecFileAsyncMock,
   ghRepoExecOptions: ghRepoExecOptionsMock,
   githubRepoContext: githubRepoContextMock,
+  classifyGhError: (stderr: string) =>
+    stderr.toLowerCase().includes('not found') || stderr.includes('HTTP 404')
+      ? { type: 'not_found', message: stderr }
+      : { type: 'unknown', message: stderr },
   parseGitHubOwnerRepo: (remoteUrl: string) => {
     const match = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/)
     return match ? { owner: match[1], repo: match[2] } : null
@@ -120,6 +124,44 @@ describe('getPRForBranch', () => {
     expect(pr?.mergeable).toBe('MERGEABLE')
   })
 
+  it('falls back to REST branch lookup when gh pr list is GraphQL rate limited', async () => {
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'acme', repo: 'widgets' })
+    ghExecFileAsyncMock
+      .mockRejectedValueOnce(new Error('GraphQL: API rate limit already exceeded'))
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify([
+          {
+            number: 43,
+            title: 'REST branch lookup',
+            state: 'open',
+            html_url: 'https://github.com/acme/widgets/pull/43',
+            updated_at: '2026-03-28T00:00:00Z',
+            draft: false,
+            mergeable: true,
+            head: { ref: 'feature/test', sha: 'rest-head-oid' },
+            base: { ref: 'main', sha: 'rest-base-oid' }
+          }
+        ])
+      })
+
+    const pr = await getPRForBranch('/repo-root', 'feature/test')
+
+    expect(ghExecFileAsyncMock).toHaveBeenNthCalledWith(
+      2,
+      ['api', 'repos/acme/widgets/pulls?head=acme%3Afeature%2Ftest&state=all&per_page=1'],
+      { cwd: '/repo-root' }
+    )
+    expect(pr).toMatchObject({
+      number: 43,
+      title: 'REST branch lookup',
+      state: 'open',
+      url: 'https://github.com/acme/widgets/pull/43',
+      checksStatus: 'neutral',
+      mergeable: 'MERGEABLE',
+      headSha: 'rest-head-oid'
+    })
+  })
+
   it('falls back to gh pr view when the remote cannot be resolved to GitHub', async () => {
     getOwnerRepoMock.mockResolvedValueOnce(null)
     ghExecFileAsyncMock.mockResolvedValueOnce({
@@ -288,6 +330,39 @@ describe('getPRForBranch', () => {
     expect(pr).toBeNull()
   })
 
+  it('falls back to REST number lookup when linked PR GraphQL lookup is rate limited', async () => {
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'acme', repo: 'widgets' })
+    ghExecFileAsyncMock
+      .mockResolvedValueOnce({ stdout: JSON.stringify([]) })
+      .mockRejectedValueOnce(new Error('GraphQL: API rate limit already exceeded'))
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify({
+          number: 99,
+          title: 'REST linked PR lookup',
+          state: 'closed',
+          merged_at: '2026-03-28T00:00:00Z',
+          html_url: 'https://github.com/acme/widgets/pull/99',
+          updated_at: '2026-03-28T00:00:00Z',
+          draft: false,
+          mergeable_state: 'clean',
+          head: { ref: 'someone/fix', sha: 'linked-head-oid' },
+          base: { ref: 'main', sha: 'linked-base-oid' }
+        })
+      })
+
+    const pr = await getPRForBranch('/repo-root', 'feature/test', 99)
+
+    expect(ghExecFileAsyncMock).toHaveBeenNthCalledWith(3, ['api', 'repos/acme/widgets/pulls/99'], {
+      cwd: '/repo-root'
+    })
+    expect(pr).toMatchObject({
+      number: 99,
+      state: 'merged',
+      mergeable: 'MERGEABLE',
+      headSha: 'linked-head-oid'
+    })
+  })
+
   it('resolves fork PR push target using the origin URL protocol', async () => {
     getOwnerRepoMock.mockResolvedValueOnce({ owner: 'stablyai', repo: 'orca' })
     getOwnerRepoForRemoteMock.mockResolvedValueOnce({ owner: 'stablyai', repo: 'orca' })
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index 4f0bb72c0ee..6787553a2e7 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -990,6 +990,99 @@ export async function getWorkItemByOwnerRepo(
   }
 }
 
+type PullRequestLookupData = {
+  number: number
+  title: string
+  state: string
+  url: string
+  statusCheckRollup: unknown[]
+  updatedAt: string
+  isDraft?: boolean
+  mergeable: string
+  baseRefName?: string
+  headRefName?: string
+  baseRefOid?: string
+  headRefOid?: string
+}
+
+type RestPullRequest = {
+  number: number
+  title: string
+  state: string
+  html_url?: string
+  url?: string
+  updated_at?: string
+  draft?: boolean
+  merged_at?: string | null
+  mergeable?: boolean | null
+  mergeable_state?: string | null
+  base?: { ref?: string; sha?: string }
+  head?: { ref?: string; sha?: string }
+}
+
+const PR_LOOKUP_JSON_FIELDS =
+  'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
+
+function mapRestPRMergeable(pr: RestPullRequest): PRMergeableState {
+  const mergeableState = pr.mergeable_state?.toLowerCase()
+  if (mergeableState === 'dirty') {
+    return 'CONFLICTING'
+  }
+  if (mergeableState === 'clean' || pr.mergeable === true) {
+    return 'MERGEABLE'
+  }
+  return 'UNKNOWN'
+}
+
+function mapRestPullRequest(pr: RestPullRequest): PullRequestLookupData {
+  return {
+    number: pr.number,
+    title: pr.title,
+    state: pr.merged_at ? 'MERGED' : pr.state,
+    url: pr.html_url ?? pr.url ?? '',
+    statusCheckRollup: [],
+    updatedAt: pr.updated_at ?? '',
+    isDraft: pr.draft,
+    mergeable: mapRestPRMergeable(pr),
+    baseRefName: pr.base?.ref,
+    headRefName: pr.head?.ref,
+    baseRefOid: pr.base?.sha,
+    headRefOid: pr.head?.sha
+  }
+}
+
+async function getRestPRForBranch(
+  ownerRepo: OwnerRepo,
+  branchName: string,
+  ghOptions: ReturnType<typeof ghRepoExecOptions>
+): Promise<PullRequestLookupData | null> {
+  const head = encodeURIComponent(`${ownerRepo.owner}:${branchName}`)
+  const { stdout } = await ghExecFileAsync(
+    ['api', `repos/${ownerRepo.owner}/${ownerRepo.repo}/pulls?head=${head}&state=all&per_page=1`],
+    ghOptions
+  )
+  const list = JSON.parse(stdout) as RestPullRequest[]
+  const pr = list[0]
+  return pr ? mapRestPullRequest(pr) : null
+}
+
+async function getRestPRByNumber(
+  ownerRepo: OwnerRepo,
+  number: number,
+  ghOptions: ReturnType<typeof ghRepoExecOptions>
+): Promise<PullRequestLookupData | null> {
+  const { stdout } = await ghExecFileAsync(
+    ['api', `repos/${ownerRepo.owner}/${ownerRepo.repo}/pulls/${number}`],
+    ghOptions
+  )
+  return mapRestPullRequest(JSON.parse(stdout) as RestPullRequest)
+}
+
+function isNotFoundGhError(err: unknown): boolean {
+  const stderr = err instanceof Error ? err.message : String(err)
+  return classifyGhError(stderr).type === 'not_found'
+}
+
 /**
  * Get PR info for a given branch using gh CLI.
  * Returns null if gh is not installed, or no PR exists for the branch.
@@ -1014,54 +1107,44 @@ export async function getPRForBranch(
   await acquire()
   try {
     const ownerRepo = await getOwnerRepo(repoPath, connectionId)
-    let data: {
-      number: number
-      title: string
-      state: string
-      url: string
-      statusCheckRollup: unknown[]
-      updatedAt: string
-      isDraft?: boolean
-      mergeable: string
-      baseRefName?: string
-      headRefName?: string
-      baseRefOid?: string
-      headRefOid?: string
-    } | null = null
+    let data: PullRequestLookupData | null = null
 
     // During a rebase the worktree is in detached HEAD and branch is empty.
     // An empty --head filter causes gh to return an arbitrary PR — skip the
     // branch lookup and rely on the linkedPR fallback below if available.
     if (branchName) {
       if (ownerRepo) {
-        const { stdout } = await ghExecFileAsync(
-          [
-            'pr',
-            'list',
-            '--repo',
-            `${ownerRepo.owner}/${ownerRepo.repo}`,
-            '--head',
-            branchName,
-            '--state',
-            'all',
-            '--limit',
-            '1',
-            '--json',
-            'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
-          ],
-          ghOptions
-        )
-        const list = JSON.parse(stdout) as NonNullable<typeof data>[]
-        data = list[0] ?? null
+        try {
+          const { stdout } = await ghExecFileAsync(
+            [
+              'pr',
+              'list',
+              '--repo',
+              `${ownerRepo.owner}/${ownerRepo.repo}`,
+              '--head',
+              branchName,
+              '--state',
+              'all',
+              '--limit',
+              '1',
+              '--json',
+              PR_LOOKUP_JSON_FIELDS
+            ],
+            ghOptions
+          )
+          const list = JSON.parse(stdout) as PullRequestLookupData[]
+          data = list[0] ?? null
+        } catch (err) {
+          // Why: `gh pr list/view` uses GraphQL and can hit that quota while
+          // REST is still available. Falling back prevents a real PR from
+          // rendering as "No pull request found" during GraphQL outages.
+          if (!isNotFoundGhError(err)) {
+            data = await getRestPRForBranch(ownerRepo, branchName, ghOptions)
+          }
+        }
       } else {
         const { stdout } = await ghExecFileAsync(
-          [
-            'pr',
-            'view',
-            branchName,
-            '--json',
-            'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
-          ],
+          ['pr', 'view', branchName, '--json', PR_LOOKUP_JSON_FIELDS],
           ghOptions
         )
         data = JSON.parse(stdout)
@@ -1077,24 +1160,21 @@ export async function getPRForBranch(
             '--repo',
             `${ownerRepo.owner}/${ownerRepo.repo}`,
             '--json',
-            'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
-          ]
-        : [
-            'pr',
-            'view',
-            String(linkedPRNumber),
-            '--json',
-            'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
+            PR_LOOKUP_JSON_FIELDS
           ]
+        : ['pr', 'view', String(linkedPRNumber), '--json', PR_LOOKUP_JSON_FIELDS]
       try {
         const { stdout } = await ghExecFileAsync(args, ghOptions)
         data = JSON.parse(stdout)
-      } catch {
+      } catch (err) {
         // Why: a stale linkedPRNumber (PR deleted, wrong repo, …) makes
         // `gh pr view <number>` reject. Treat that as the no-PR case so
         // callers see the historical `null` semantics instead of a thrown
         // error every poll cycle.
-        data = null
+        data =
+          ownerRepo && !isNotFoundGhError(err)
+            ? await getRestPRByNumber(ownerRepo, linkedPRNumber, ghOptions)
+            : null
       }
     }
 

From 09e6911ea8a0ccb8a61408e6f370911f81321fa3 Mon Sep 17 00:00:00 2001
From: Timothy J Laurent <timothyjlaurent@gmail.com>
Date: Fri, 15 May 2026 12:54:20 -0700
Subject: [PATCH 61/82] fix(browser): harden Comet cookie import replay

---
 .../browser-cookie-import.comet.test.ts       | 219 ++++++++++++++++
 .../browser/browser-cookie-import.test.ts     |   2 +-
 src/main/browser/browser-cookie-import.ts     |  32 ++-
 ...owser-session-registry.persistence.test.ts | 245 ++++++++++++++++++
 .../browser/browser-session-registry.test.ts  |  11 +
 src/main/browser/browser-session-registry.ts  | 217 ++++++++++++----
 .../src/components/settings/BrowserPane.tsx   |   2 +-
 src/shared/constants.ts                       |   1 +
 src/shared/types.ts                           |   2 +-
 9 files changed, 668 insertions(+), 63 deletions(-)
 create mode 100644 src/main/browser/browser-cookie-import.comet.test.ts
 create mode 100644 src/main/browser/browser-session-registry.persistence.test.ts

diff --git a/src/main/browser/browser-cookie-import.comet.test.ts b/src/main/browser/browser-cookie-import.comet.test.ts
new file mode 100644
index 00000000000..c528a6de356
--- /dev/null
+++ b/src/main/browser/browser-cookie-import.comet.test.ts
@@ -0,0 +1,219 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type * as childProcessModule from 'node:child_process'
+import type * as fsModule from 'node:fs'
+
+const { sessionFromPartitionMock, dialogShowOpenDialogMock } = vi.hoisted(() => ({
+  sessionFromPartitionMock: vi.fn(),
+  dialogShowOpenDialogMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  BrowserWindow: { fromWebContents: vi.fn() },
+  dialog: { showOpenDialog: dialogShowOpenDialogMock },
+  session: { fromPartition: sessionFromPartitionMock }
+}))
+
+import { BROWSER_FAMILY_LABELS } from '../../shared/constants'
+describe('detectInstalledBrowsers — Comet', () => {
+  const originalPlatform = process.platform
+  const originalHome = process.env.HOME
+
+  beforeEach(() => {
+    // Why: browser-cookie-import.ts uses destructured named imports from
+    // 'node:fs' which are bound at module-load time. Without vi.resetModules(),
+    // only the first test's vi.doMock takes effect — subsequent tests see the
+    // cached module with the first mock still applied. resetModules must run
+    // BEFORE each doMock so the next import() picks up the fresh mock factory.
+    vi.resetModules()
+    Object.defineProperty(process, 'platform', { value: 'darwin' })
+    process.env.HOME = '/Users/test'
+  })
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: originalPlatform })
+    process.env.HOME = originalHome
+    vi.restoreAllMocks()
+  })
+
+  it('detects Comet when its data directory and Cookies DB exist', async () => {
+    vi.doMock('node:fs', async () => {
+      const actual = await vi.importActual<typeof fsModule>('node:fs')
+      return {
+        ...actual,
+        existsSync: (p: string) => {
+          if (p.includes('Comet/Default/Network/Cookies')) {
+            return true
+          }
+          if (p.includes('Comet/Local State')) {
+            return true
+          }
+          return false
+        },
+        readFileSync: (p: string, enc?: string) => {
+          if (typeof p === 'string' && p.includes('Comet/Local State')) {
+            return JSON.stringify({ profile: { info_cache: { Default: { name: 'Default' } } } })
+          }
+          return actual.readFileSync(p as never, enc as never)
+        }
+      }
+    })
+
+    const { detectInstalledBrowsers } = await import('./browser-cookie-import')
+    const detected = detectInstalledBrowsers()
+    const comet = detected.find((b) => b.family === 'comet')
+    expect(comet).toBeDefined()
+    expect(comet?.label).toBe('Comet')
+    expect(comet?.cookiesPath).toContain('Comet/Default/Network/Cookies')
+    expect(comet?.keychainService).toBe('Comet Safe Storage')
+  })
+
+  it('does not list Comet when its data directory is absent', async () => {
+    vi.doMock('node:fs', async () => {
+      const actual = await vi.importActual<typeof fsModule>('node:fs')
+      return {
+        ...actual,
+        existsSync: () => false
+      }
+    })
+
+    const { detectInstalledBrowsers } = await import('./browser-cookie-import')
+    const detected = detectInstalledBrowsers()
+    expect(detected.find((b) => b.family === 'comet')).toBeUndefined()
+  })
+
+  it('enumerates all Comet profiles from Local State info_cache', async () => {
+    vi.doMock('node:fs', async () => {
+      const actual = await vi.importActual<typeof fsModule>('node:fs')
+      return {
+        ...actual,
+        existsSync: (p: string) => {
+          if (p.includes('Comet/Default/Network/Cookies')) {
+            return true
+          }
+          if (p.includes('Comet/Local State')) {
+            return true
+          }
+          return false
+        },
+        readFileSync: (p: string, enc?: string) => {
+          if (typeof p === 'string' && p.includes('Comet/Local State')) {
+            return JSON.stringify({
+              profile: {
+                info_cache: {
+                  Default: { name: 'Personal' },
+                  'Profile 1': { name: 'Work' },
+                  'Profile 2': { name: 'Research' }
+                }
+              }
+            })
+          }
+          return actual.readFileSync(p as never, enc as never)
+        }
+      }
+    })
+
+    const { detectInstalledBrowsers } = await import('./browser-cookie-import')
+    const detected = detectInstalledBrowsers()
+    const comet = detected.find((b) => b.family === 'comet')
+    expect(comet).toBeDefined()
+    const directories = comet!.profiles.map((p) => p.directory).sort()
+    expect(directories).toEqual(['Default', 'Profile 1', 'Profile 2'])
+    const names = comet!.profiles.map((p) => p.name).sort()
+    expect(names).toEqual(['Personal', 'Research', 'Work'])
+  })
+
+  it('skips Comet when the data directory exists but no Cookies DB is present', async () => {
+    vi.doMock('node:fs', async () => {
+      const actual = await vi.importActual<typeof fsModule>('node:fs')
+      return {
+        ...actual,
+        existsSync: (p: string) => {
+          if (p.includes('Comet/Local State')) {
+            return true
+          }
+          if (p.includes('Network/Cookies') || p.endsWith('/Cookies')) {
+            return false
+          }
+          return false
+        },
+        readFileSync: (p: string, enc?: string) => {
+          if (typeof p === 'string' && p.includes('Comet/Local State')) {
+            return JSON.stringify({ profile: { info_cache: { Default: { name: 'Default' } } } })
+          }
+          return actual.readFileSync(p as never, enc as never)
+        }
+      }
+    })
+
+    const { detectInstalledBrowsers } = await import('./browser-cookie-import')
+    const detected = detectInstalledBrowsers()
+    expect(detected.find((b) => b.family === 'comet')).toBeUndefined()
+  })
+})
+
+describe('getUserAgentForBrowser — Comet', () => {
+  const originalPlatform = process.platform
+
+  beforeEach(() => {
+    vi.resetModules()
+    Object.defineProperty(process, 'platform', { value: 'darwin' })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: originalPlatform })
+    vi.restoreAllMocks()
+  })
+
+  it('returns a Chrome-shaped UA string when Comet plist version reads successfully', async () => {
+    vi.doMock('node:child_process', async () => {
+      const actual = await vi.importActual<typeof childProcessModule>('node:child_process')
+      return {
+        ...actual,
+        execFileSync: (cmd: string, args: readonly string[]) => {
+          if (cmd === 'defaults' && args[1]?.includes('/Applications/Comet.app/Contents/Info')) {
+            return '120.0.6099.71\n'
+          }
+          return actual.execFileSync(cmd, args as never)
+        }
+      }
+    })
+
+    const { getUserAgentForBrowser } = await import('./browser-cookie-import')
+    const ua = getUserAgentForBrowser('comet')
+
+    expect(ua).not.toBeNull()
+    expect(ua).toContain('Macintosh; Intel Mac OS X 10_15_7')
+    expect(ua).toContain('AppleWebKit/537.36')
+    expect(ua).toContain('Chrome/120.0.6099.71')
+    expect(ua).toContain('Safari/537.36')
+  })
+
+  it('returns null when reading the Comet plist version throws', async () => {
+    vi.doMock('node:child_process', async () => {
+      const actual = await vi.importActual<typeof childProcessModule>('node:child_process')
+      return {
+        ...actual,
+        execFileSync: () => {
+          throw new Error('defaults: domain not found')
+        }
+      }
+    })
+
+    const { getUserAgentForBrowser } = await import('./browser-cookie-import')
+    const ua = getUserAgentForBrowser('comet')
+    expect(ua).toBeNull()
+  })
+
+  it('returns null on non-darwin platforms regardless of family', async () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' })
+    const { getUserAgentForBrowser } = await import('./browser-cookie-import')
+    const ua = getUserAgentForBrowser('comet')
+    expect(ua).toBeNull()
+  })
+})
+
+describe('BROWSER_FAMILY_LABELS — Comet', () => {
+  it('maps the comet family key to the user-facing label "Comet"', () => {
+    expect(BROWSER_FAMILY_LABELS.comet).toBe('Comet')
+  })
+})
diff --git a/src/main/browser/browser-cookie-import.test.ts b/src/main/browser/browser-cookie-import.test.ts
index 73698fbcdbe..4bc358ab5f6 100644
--- a/src/main/browser/browser-cookie-import.test.ts
+++ b/src/main/browser/browser-cookie-import.test.ts
@@ -227,7 +227,7 @@ describe('detectInstalledBrowsers', () => {
 
   it('each detected browser has a valid family', () => {
     const browsers = detectInstalledBrowsers()
-    const validFamilies = ['chrome', 'edge', 'arc', 'chromium', 'firefox', 'safari']
+    const validFamilies = ['chrome', 'edge', 'arc', 'chromium', 'firefox', 'safari', 'comet']
     for (const browser of browsers) {
       expect(validFamilies).toContain(browser.family)
     }
diff --git a/src/main/browser/browser-cookie-import.ts b/src/main/browser/browser-cookie-import.ts
index dfbdcd4f155..2da3a85b224 100644
--- a/src/main/browser/browser-cookie-import.ts
+++ b/src/main/browser/browser-cookie-import.ts
@@ -2,12 +2,13 @@
    that must stay together so the encryption, schema, and staging steps remain in sync. */
 import { app, type BrowserWindow, dialog, session } from 'electron'
 import { execFileSync } from 'node:child_process'
-import { createDecipheriv, pbkdf2Sync } from 'node:crypto'
+import { createDecipheriv, pbkdf2Sync, randomUUID } from 'node:crypto'
 import {
   appendFileSync,
   copyFileSync,
   existsSync,
   mkdtempSync,
+  mkdirSync,
   readFileSync,
   readdirSync,
   rmSync,
@@ -113,6 +114,15 @@ const CHROMIUM_BROWSERS: ChromiumBrowserDef[] = [
     macRoot: 'BraveSoftware/Brave-Browser',
     winRoot: 'BraveSoftware/Brave-Browser/User Data',
     linuxRoot: 'BraveSoftware/Brave-Browser'
+  },
+  {
+    family: 'comet',
+    label: 'Comet',
+    keychainService: 'Comet Safe Storage',
+    keychainAccount: 'Comet',
+    macRoot: 'Comet',
+    winRoot: 'Comet/User Data'
+    // linuxRoot intentionally omitted — Comet does not ship a Linux build as of 2026-05-15
   }
 ]
 
@@ -658,7 +668,7 @@ export async function importCookiesFromFile(
 // Why: Google and other services bind auth cookies to the User-Agent that
 // created them. We read the source browser's real version from its plist
 // and construct a matching UA string so imported sessions aren't invalidated.
-function getUserAgentForBrowser(
+export function getUserAgentForBrowser(
   family: BrowserSessionProfileSource['browserFamily']
 ): string | null {
   // Why: UA spoofing uses macOS-specific plist reading. On other platforms,
@@ -703,6 +713,12 @@ function getUserAgentForBrowser(
       const v = readBrowserVersion('/Applications/Brave Browser.app')
       return v ? `Mozilla/5.0 (${platform}) ${chromeBase} Chrome/${v} Safari/537.36` : null
     }
+    case 'comet': {
+      // Why: Comet is Chromium-based and ships a Chrome-shaped version in its plist.
+      // Use the same UA shape as Chrome itself so Google-bound auth cookies survive import.
+      const v = readBrowserVersion('/Applications/Comet.app')
+      return v ? `Mozilla/5.0 (${platform}) ${chromeBase} Chrome/${v} Safari/537.36` : null
+    }
     default:
       return null
   }
@@ -1343,8 +1359,14 @@ export async function importCookiesFromBrowser(
     return { ok: false, reason: 'Target cookie database not found. Open a browser tab first.' }
   }
 
-  const stagingCookiesPath = join(app.getPath('userData'), 'Cookies-staged')
+  const stagingDir = join(app.getPath('userData'), 'cookie-import-staging')
+  const partitionSegment = partitionName.replace(/[^a-zA-Z0-9_-]/g, '_')
+  const stagingCookiesPath = join(
+    stagingDir,
+    `Cookies-${partitionSegment}-${Date.now()}-${randomUUID()}`
+  )
   try {
+    mkdirSync(stagingDir, { recursive: true })
     copyFileSync(liveCookiesPath, stagingCookiesPath)
   } catch {
     rmSync(tmpDir, { recursive: true, force: true })
@@ -1565,7 +1587,7 @@ export async function importCookiesFromBrowser(
       // Why: some cookies couldn't be loaded via cookies.set() (non-ASCII values
       // or other validation failures). Keep the staging DB so the next cold start
       // picks them up from SQLite where CookieMonster reads them without validation.
-      browserSessionRegistry.setPendingCookieImport(stagingCookiesPath)
+      browserSessionRegistry.setPendingCookieImport(targetPartition, stagingCookiesPath)
       diag(`  staged at ${stagingCookiesPath} for ${memoryFailed} cookies that need restart`)
     } else {
       try {
@@ -1580,7 +1602,7 @@ export async function importCookiesFromBrowser(
     if (ua) {
       targetSession.setUserAgent(ua)
       setupClientHintsOverride(targetSession, ua)
-      browserSessionRegistry.persistUserAgent(ua)
+      browserSessionRegistry.persistUserAgent(targetPartition, ua)
       diag(`  set UA for partition: ${ua.substring(0, 80)}...`)
     }
 
diff --git a/src/main/browser/browser-session-registry.persistence.test.ts b/src/main/browser/browser-session-registry.persistence.test.ts
new file mode 100644
index 00000000000..18d9fc89931
--- /dev/null
+++ b/src/main/browser/browser-session-registry.persistence.test.ts
@@ -0,0 +1,245 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const USER_DATA = '/user-data'
+const META_PATH = `${USER_DATA}/browser-session-meta.json`
+
+type FsState = {
+  files: Map<string, string>
+  present: Set<string>
+}
+
+function createFsState(): FsState {
+  return { files: new Map(), present: new Set() }
+}
+
+function seedMeta(fsState: FsState, meta: unknown): void {
+  const raw = JSON.stringify(meta)
+  fsState.files.set(META_PATH, raw)
+  fsState.present.add(META_PATH)
+}
+
+function installModuleMocks(
+  fsState: FsState,
+  copyFailures: Set<string> = new Set()
+): {
+  sessionFromPartitionMock: ReturnType<typeof vi.fn>
+  setupClientHintsOverrideMock: ReturnType<typeof vi.fn>
+} {
+  const sessionFromPartitionMock = vi.fn((partition: string) => ({
+    partition,
+    setUserAgent: vi.fn(),
+    getUserAgent: vi.fn(() => 'Mozilla/5.0 Electron/31 Orca'),
+    setPermissionRequestHandler: vi.fn(),
+    setPermissionCheckHandler: vi.fn(),
+    setDisplayMediaRequestHandler: vi.fn(),
+    on: vi.fn(),
+    clearStorageData: vi.fn().mockResolvedValue(undefined),
+    clearCache: vi.fn().mockResolvedValue(undefined)
+  }))
+  const setupClientHintsOverrideMock = vi.fn()
+
+  vi.doMock('electron', () => ({
+    app: { getPath: vi.fn(() => USER_DATA) },
+    session: { fromPartition: sessionFromPartitionMock },
+    systemPreferences: {
+      askForMediaAccess: vi.fn().mockResolvedValue(true),
+      getMediaAccessStatus: vi.fn(() => 'granted')
+    }
+  }))
+
+  vi.doMock('node:fs', () => ({
+    copyFileSync: vi.fn((src: string, dst: string) => {
+      if (copyFailures.has(src)) {
+        throw new Error(`copy fail for ${src}`)
+      }
+      fsState.present.add(dst)
+      const value = fsState.files.get(src)
+      if (value !== undefined) {
+        fsState.files.set(dst, value)
+      }
+    }),
+    existsSync: vi.fn((p: string) => fsState.present.has(p)),
+    mkdirSync: vi.fn(),
+    readFileSync: vi.fn((p: string) => {
+      const v = fsState.files.get(p)
+      if (v === undefined) {
+        throw new Error('ENOENT')
+      }
+      return v
+    }),
+    renameSync: vi.fn((from: string, to: string) => {
+      const v = fsState.files.get(from)
+      if (v === undefined) {
+        throw new Error('ENOENT')
+      }
+      fsState.files.set(to, v)
+      fsState.present.add(to)
+      fsState.files.delete(from)
+      fsState.present.delete(from)
+    }),
+    unlinkSync: vi.fn((p: string) => {
+      fsState.present.delete(p)
+      fsState.files.delete(p)
+    }),
+    writeFileSync: vi.fn((p: string, data: string | Uint8Array) => {
+      const value = typeof data === 'string' ? data : Buffer.from(data).toString('utf-8')
+      fsState.files.set(p, value)
+      fsState.present.add(p)
+    })
+  }))
+
+  vi.doMock('./browser-manager', () => ({
+    browserManager: {
+      notifyPermissionDenied: vi.fn(),
+      handleGuestWillDownload: vi.fn()
+    }
+  }))
+  vi.doMock('./browser-media-access', () => ({
+    hasSystemMediaAccess: vi.fn(() => true),
+    requestSystemMediaAccess: vi.fn().mockResolvedValue(true)
+  }))
+  vi.doMock('./browser-session-ua', () => ({
+    cleanElectronUserAgent: vi.fn((ua: string) => ua.replace(/\s*Electron\/\S+/, '')),
+    setupClientHintsOverride: setupClientHintsOverrideMock
+  }))
+
+  return { sessionFromPartitionMock, setupClientHintsOverrideMock }
+}
+
+describe('BrowserSessionRegistry persistence', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.restoreAllMocks()
+  })
+
+  it('migrates and consumes legacy pendingCookieDbPath into default partition replay', async () => {
+    const fsState = createFsState()
+    seedMeta(fsState, {
+      defaultSource: null,
+      userAgent: null,
+      pendingCookieDbPath: '/staged/legacy',
+      profiles: []
+    })
+    fsState.present.add('/staged/legacy')
+
+    installModuleMocks(fsState)
+    const { browserSessionRegistry } = await import('./browser-session-registry')
+
+    browserSessionRegistry.applyPendingCookieImport()
+
+    const written = JSON.parse(fsState.files.get(META_PATH) ?? '{}')
+    expect(written.pendingCookieDbPath).toBeNull()
+    expect(written.pendingCookieImports).toEqual({})
+    expect(fsState.present.has('/user-data/Partitions/orca-browser/Cookies')).toBe(true)
+  })
+
+  it('merges partition-keyed pending entries without clobbering unrelated entries', async () => {
+    const fsState = createFsState()
+    seedMeta(fsState, {
+      defaultSource: null,
+      userAgent: null,
+      userAgentByPartition: {},
+      pendingCookieDbPath: null,
+      pendingCookieImports: {},
+      profiles: []
+    })
+
+    installModuleMocks(fsState)
+    const { browserSessionRegistry } = await import('./browser-session-registry')
+
+    browserSessionRegistry.setPendingCookieImport('persist:orca-browser', '/staged/default')
+    browserSessionRegistry.setPendingCookieImport(
+      'persist:orca-browser-session-aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+      '/staged/imported'
+    )
+
+    const written = JSON.parse(fsState.files.get(META_PATH) ?? '{}')
+    expect(written.pendingCookieDbPath).toBe('/staged/default')
+    expect(written.pendingCookieImports).toEqual({
+      'persist:orca-browser': '/staged/default',
+      'persist:orca-browser-session-aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa': '/staged/imported'
+    })
+  })
+
+  it('restores persisted UA for non-default partitions', async () => {
+    const importedPartition = 'persist:orca-browser-session-11111111-1111-4111-8111-111111111111'
+    const importedUa = 'Mozilla/5.0 Chrome/120.0.0.0 Safari/537.36'
+    const defaultUa = 'Mozilla/5.0 Chrome/119.0.0.0 Safari/537.36'
+    const fsState = createFsState()
+    seedMeta(fsState, {
+      defaultSource: null,
+      userAgent: defaultUa,
+      userAgentByPartition: {
+        'persist:orca-browser': defaultUa,
+        [importedPartition]: importedUa
+      },
+      pendingCookieDbPath: null,
+      pendingCookieImports: {},
+      profiles: [
+        {
+          id: '11111111-1111-4111-8111-111111111111',
+          scope: 'imported',
+          partition: importedPartition,
+          label: 'Imported',
+          source: { browserFamily: 'comet', importedAt: 1 }
+        }
+      ]
+    })
+
+    const { sessionFromPartitionMock, setupClientHintsOverrideMock } = installModuleMocks(fsState)
+    const { browserSessionRegistry } = await import('./browser-session-registry')
+
+    browserSessionRegistry.restorePersistedUserAgent()
+
+    const importedSessions = sessionFromPartitionMock.mock.results
+      .filter((_, idx) => sessionFromPartitionMock.mock.calls[idx]?.[0] === importedPartition)
+      .map((r) => r.value)
+    expect(importedSessions.length).toBeGreaterThan(0)
+    expect(
+      importedSessions.some((s) =>
+        s.setUserAgent.mock.calls.some((c: unknown[]) => c[0] === importedUa)
+      )
+    ).toBe(true)
+    expect(
+      setupClientHintsOverrideMock.mock.calls.some(
+        (c: unknown[]) =>
+          (c[0] as { partition?: string } | undefined)?.partition === importedPartition &&
+          c[1] === importedUa
+      )
+    ).toBe(true)
+  })
+
+  it('keeps failed partition replay pending and removes unrelated missing entries', async () => {
+    const importedPartition = 'persist:orca-browser-session-22222222-2222-4222-8222-222222222222'
+    const fsState = createFsState()
+    seedMeta(fsState, {
+      defaultSource: null,
+      userAgent: null,
+      userAgentByPartition: {},
+      pendingCookieDbPath: null,
+      pendingCookieImports: {
+        [importedPartition]: '/staged/imported',
+        'persist:orca-browser': '/staged/missing'
+      },
+      profiles: [
+        {
+          id: '22222222-2222-4222-8222-222222222222',
+          scope: 'imported',
+          partition: importedPartition,
+          label: 'Imported',
+          source: { browserFamily: 'comet', importedAt: 1 }
+        }
+      ]
+    })
+    fsState.present.add('/staged/imported')
+
+    installModuleMocks(fsState, new Set(['/staged/imported']))
+    const { browserSessionRegistry } = await import('./browser-session-registry')
+
+    browserSessionRegistry.applyPendingCookieImport()
+
+    const written = JSON.parse(fsState.files.get(META_PATH) ?? '{}')
+    expect(written.pendingCookieImports).toEqual({ [importedPartition]: '/staged/imported' })
+    expect(written.pendingCookieDbPath).toBeNull()
+  })
+})
diff --git a/src/main/browser/browser-session-registry.test.ts b/src/main/browser/browser-session-registry.test.ts
index 6a51a95c1bc..e6915755175 100644
--- a/src/main/browser/browser-session-registry.test.ts
+++ b/src/main/browser/browser-session-registry.test.ts
@@ -122,6 +122,17 @@ describe('BrowserSessionRegistry', () => {
     expect(updated!.source?.browserFamily).toBe('edge')
   })
 
+  it('updates profile source with comet family', () => {
+    const profile = browserSessionRegistry.createProfile('imported', 'Comet Source Test')
+    expect(profile).not.toBeNull()
+    const updated = browserSessionRegistry.updateProfileSource(profile!.id, {
+      browserFamily: 'comet',
+      importedAt: Date.now()
+    })
+    expect(updated).not.toBeNull()
+    expect(updated!.source?.browserFamily).toBe('comet')
+  })
+
   it('deletes a non-default profile', async () => {
     const profile = browserSessionRegistry.createProfile('isolated', 'Delete Test')
     expect(profile).not.toBeNull()
diff --git a/src/main/browser/browser-session-registry.ts b/src/main/browser/browser-session-registry.ts
index cf6d3fffa11..18d98cf8faf 100644
--- a/src/main/browser/browser-session-registry.ts
+++ b/src/main/browser/browser-session-registry.ts
@@ -7,6 +7,7 @@ import { randomUUID } from 'node:crypto'
 import {
   copyFileSync,
   existsSync,
+  mkdirSync,
   readFileSync,
   renameSync,
   unlinkSync,
@@ -22,7 +23,9 @@ import { cleanElectronUserAgent, setupClientHintsOverride } from './browser-sess
 type BrowserSessionMeta = {
   defaultSource: BrowserSessionProfile['source']
   userAgent: string | null
+  userAgentByPartition: Record<string, string>
   pendingCookieDbPath: string | null
+  pendingCookieImports: Record<string, string>
   profiles: BrowserSessionProfile[]
 }
 
@@ -57,6 +60,11 @@ class BrowserSessionRegistry {
     return this.loadPersistedMeta().defaultSource
   }
 
+  private static partitionCookiesPath(partition: string): string {
+    const partitionName = partition.replace('persist:', '')
+    return join(app.getPath('userData'), 'Partitions', partitionName, 'Cookies')
+  }
+
   // Why: write-to-temp-then-rename is atomic on all supported platforms.
   // A crash mid-write would only lose the temp file, not corrupt the live one.
   private persistMeta(updates: Partial<BrowserSessionMeta>): void {
@@ -88,14 +96,41 @@ class BrowserSessionRegistry {
     try {
       const raw = readFileSync(this.metadataPath, 'utf-8')
       const data = JSON.parse(raw)
+      const legacyUserAgent = typeof data?.userAgent === 'string' ? data.userAgent : null
+      const userAgentByPartition: Record<string, string> =
+        data && typeof data.userAgentByPartition === 'object' && data.userAgentByPartition
+          ? { ...data.userAgentByPartition }
+          : {}
+      if (legacyUserAgent && !userAgentByPartition[ORCA_BROWSER_PARTITION]) {
+        userAgentByPartition[ORCA_BROWSER_PARTITION] = legacyUserAgent
+      }
+
+      const legacyPendingCookieDbPath =
+        typeof data?.pendingCookieDbPath === 'string' ? data.pendingCookieDbPath : null
+      const pendingCookieImports: Record<string, string> =
+        data && typeof data.pendingCookieImports === 'object' && data.pendingCookieImports
+          ? { ...data.pendingCookieImports }
+          : {}
+      if (legacyPendingCookieDbPath && !pendingCookieImports[ORCA_BROWSER_PARTITION]) {
+        pendingCookieImports[ORCA_BROWSER_PARTITION] = legacyPendingCookieDbPath
+      }
       return {
         defaultSource: data?.defaultSource ?? null,
-        userAgent: data?.userAgent ?? null,
-        pendingCookieDbPath: data?.pendingCookieDbPath ?? null,
+        userAgent: legacyUserAgent,
+        userAgentByPartition,
+        pendingCookieDbPath: legacyPendingCookieDbPath,
+        pendingCookieImports,
         profiles: Array.isArray(data?.profiles) ? data.profiles : []
       }
     } catch {
-      return { defaultSource: null, userAgent: null, pendingCookieDbPath: null, profiles: [] }
+      return {
+        defaultSource: null,
+        userAgent: null,
+        userAgentByPartition: {},
+        pendingCookieDbPath: null,
+        pendingCookieImports: {},
+        profiles: []
+      }
     }
   }
 
@@ -110,22 +145,6 @@ class BrowserSessionRegistry {
   // after app is ready) ensures the default profile's source is populated.
   restorePersistedUserAgent(): void {
     const meta = this.loadPersistedMeta()
-    if (meta.userAgent) {
-      const sess = session.fromPartition(ORCA_BROWSER_PARTITION)
-      sess.setUserAgent(meta.userAgent)
-      setupClientHintsOverride(sess, meta.userAgent)
-    } else {
-      // Why: even without an imported session, the default Electron UA contains
-      // "Electron/X.X.X" and the app name which trip Cloudflare Turnstile.
-      try {
-        const sess = session.fromPartition(ORCA_BROWSER_PARTITION)
-        const cleanUA = cleanElectronUserAgent(sess.getUserAgent())
-        sess.setUserAgent(cleanUA)
-        setupClientHintsOverride(sess, cleanUA)
-      } catch {
-        /* session not available yet (e.g. unit tests or pre-ready) */
-      }
-    }
     if (meta.defaultSource) {
       const current = this.profiles.get('default')
       if (current && current.source === null) {
@@ -135,6 +154,30 @@ class BrowserSessionRegistry {
     if (meta.profiles.length > 0) {
       this.hydrateFromPersisted(meta.profiles)
     }
+
+    const partitions = new Set([
+      ORCA_BROWSER_PARTITION,
+      ...this.listProfiles().map((p) => p.partition)
+    ])
+    for (const partition of partitions) {
+      try {
+        const sess = session.fromPartition(partition)
+        const persistedUa = meta.userAgentByPartition[partition]
+        if (persistedUa) {
+          sess.setUserAgent(persistedUa)
+          setupClientHintsOverride(sess, persistedUa)
+          continue
+        }
+
+        // Why: even without an imported session, the default Electron UA contains
+        // "Electron/X.X.X" and the app name which trip Cloudflare Turnstile.
+        const cleanUA = cleanElectronUserAgent(sess.getUserAgent())
+        sess.setUserAgent(cleanUA)
+        setupClientHintsOverride(sess, cleanUA)
+      } catch {
+        /* session not available yet (e.g. unit tests or pre-ready) */
+      }
+    }
   }
 
   // Why: the import writes cookies to a staging DB because CookieMonster holds
@@ -144,56 +187,98 @@ class BrowserSessionRegistry {
   applyPendingCookieImport(): void {
     try {
       const meta = this.loadPersistedMeta()
-      if (!meta.pendingCookieDbPath) {
-        return
-      }
-      if (!existsSync(meta.pendingCookieDbPath)) {
-        this.persistMeta({ pendingCookieDbPath: null })
+      const pendingEntries = Object.entries(meta.pendingCookieImports)
+      if (pendingEntries.length === 0) {
         return
       }
+      const knownPartitions = new Set([
+        ORCA_BROWSER_PARTITION,
+        ...meta.profiles.map((p) => p.partition)
+      ])
+      const remainingEntries = { ...meta.pendingCookieImports }
 
-      const partitionName = ORCA_BROWSER_PARTITION.replace('persist:', '')
-      const liveCookiesPath = join(app.getPath('userData'), 'Partitions', partitionName, 'Cookies')
-
-      copyFileSync(meta.pendingCookieDbPath, liveCookiesPath)
-      // Why: SQLite WAL mode stores uncommitted data in sidecar files.
-      // Stale WAL/SHM from a previous session could corrupt CookieMonster's
-      // read of the freshly swapped DB.
-      for (const suffix of ['-wal', '-shm']) {
-        try {
-          unlinkSync(liveCookiesPath + suffix)
-        } catch {
-          /* may not exist */
+      for (const [partition, stagedPath] of pendingEntries) {
+        if (!knownPartitions.has(partition)) {
+          delete remainingEntries[partition]
+          continue
         }
-        const stagingSidecar = meta.pendingCookieDbPath + suffix
-        if (existsSync(stagingSidecar)) {
-          try {
-            copyFileSync(stagingSidecar, liveCookiesPath + suffix)
-          } catch {
-            /* best-effort */
+        if (!existsSync(stagedPath)) {
+          delete remainingEntries[partition]
+          continue
+        }
+
+        const liveCookiesPath = BrowserSessionRegistry.partitionCookiesPath(partition)
+        try {
+          mkdirSync(join(liveCookiesPath, '..'), { recursive: true })
+          copyFileSync(stagedPath, liveCookiesPath)
+          // Why: SQLite WAL mode stores uncommitted data in sidecar files.
+          // Stale WAL/SHM from a previous session could corrupt CookieMonster's
+          // read of the freshly swapped DB.
+          let sidecarCopyFailed = false
+          for (const suffix of ['-wal', '-shm']) {
+            try {
+              unlinkSync(liveCookiesPath + suffix)
+            } catch {
+              /* may not exist */
+            }
+            const stagingSidecar = stagedPath + suffix
+            if (!existsSync(stagingSidecar)) {
+              continue
+            }
+            try {
+              copyFileSync(stagingSidecar, liveCookiesPath + suffix)
+            } catch {
+              sidecarCopyFailed = true
+            }
           }
-        }
-      }
-      for (const ext of ['', '-wal', '-shm']) {
-        try {
-          unlinkSync(`${meta.pendingCookieDbPath}${ext}`)
+          if (sidecarCopyFailed) {
+            // Why: sidecar copy failures can leave an inconsistent replay state.
+            // Keep this entry for retry and preserve unrelated entries.
+            continue
+          }
+          for (const ext of ['', '-wal', '-shm']) {
+            try {
+              unlinkSync(`${stagedPath}${ext}`)
+            } catch {
+              /* best-effort */
+            }
+          }
+          delete remainingEntries[partition]
         } catch {
-          /* best-effort */
+          // Why: failed replay for one partition should not drop unrelated entries.
+          // Keep this entry for retry next launch.
         }
       }
-      this.persistMeta({ pendingCookieDbPath: null })
+      this.persistMeta({
+        pendingCookieImports: remainingEntries,
+        pendingCookieDbPath: remainingEntries[ORCA_BROWSER_PARTITION] ?? null
+      })
     } catch {
       // best-effort — if this fails, CookieMonster loads the old DB
     }
   }
 
-  setPendingCookieImport(stagingDbPath: string): void {
-    this.persistMeta({ pendingCookieDbPath: stagingDbPath })
+  setPendingCookieImport(partition: string, stagingDbPath: string): void {
+    const meta = this.loadPersistedMeta()
+    const pendingCookieImports = { ...meta.pendingCookieImports, [partition]: stagingDbPath }
+    this.persistMeta({
+      pendingCookieImports,
+      pendingCookieDbPath: pendingCookieImports[ORCA_BROWSER_PARTITION] ?? null
+    })
   }
 
-  persistUserAgent(userAgent: string | null): void {
-    const defaultProfile = this.profiles.get('default')
-    this.persistSource(defaultProfile?.source ?? null, userAgent)
+  persistUserAgent(partition: string, userAgent: string | null): void {
+    const meta = this.loadPersistedMeta()
+    const userAgentByPartition = { ...meta.userAgentByPartition }
+    if (userAgent) {
+      userAgentByPartition[partition] = userAgent
+    } else {
+      delete userAgentByPartition[partition]
+    }
+    this.persistMeta({
+      userAgentByPartition,
+      userAgent: userAgentByPartition[ORCA_BROWSER_PARTITION] ?? null
+    })
   }
 
   getDefaultProfile(): BrowserSessionProfile {
@@ -273,6 +358,17 @@ class BrowserSessionRegistry {
     }
     this.profiles.delete(profileId)
     this.persistProfiles()
+    const meta = this.loadPersistedMeta()
+    const pendingCookieImports = { ...meta.pendingCookieImports }
+    delete pendingCookieImports[profile.partition]
+    const userAgentByPartition = { ...meta.userAgentByPartition }
+    delete userAgentByPartition[profile.partition]
+    this.persistMeta({
+      pendingCookieImports,
+      pendingCookieDbPath: pendingCookieImports[ORCA_BROWSER_PARTITION] ?? null,
+      userAgentByPartition,
+      userAgent: userAgentByPartition[ORCA_BROWSER_PARTITION] ?? null
+    })
 
     // Why: clearing the partition's storage prevents orphaned cookies/cache from
     // lingering after the user deletes an imported or isolated session profile.
@@ -298,7 +394,18 @@ class BrowserSessionRegistry {
       if (defaultProfile) {
         this.profiles.set('default', { ...defaultProfile, source: null })
       }
-      this.persistMeta({ defaultSource: null, userAgent: null, pendingCookieDbPath: null })
+      const meta = this.loadPersistedMeta()
+      const pendingCookieImports = { ...meta.pendingCookieImports }
+      delete pendingCookieImports[ORCA_BROWSER_PARTITION]
+      const userAgentByPartition = { ...meta.userAgentByPartition }
+      delete userAgentByPartition[ORCA_BROWSER_PARTITION]
+      this.persistMeta({
+        defaultSource: null,
+        userAgent: null,
+        userAgentByPartition,
+        pendingCookieDbPath: null,
+        pendingCookieImports
+      })
 
       const sess = session.fromPartition(ORCA_BROWSER_PARTITION)
       await sess.clearStorageData({ storages: ['cookies'] })
diff --git a/src/renderer/src/components/settings/BrowserPane.tsx b/src/renderer/src/components/settings/BrowserPane.tsx
index 2d7d9ef7bd7..d28f5edffec 100644
--- a/src/renderer/src/components/settings/BrowserPane.tsx
+++ b/src/renderer/src/components/settings/BrowserPane.tsx
@@ -228,7 +228,7 @@ export function BrowserPane({ settings, updateSettings }: BrowserPaneProps): Rea
         <SearchableSetting
           id="browser-session-cookies"
           title="Session & Cookies"
-          description="Manage browser profiles and import cookies from Chrome, Edge, or other browsers."
+          description="Manage browser profiles and import cookies from Chrome, Edge, Comet, or other browsers."
           keywords={[
             'cookies',
             'session',
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index f643e0b7e11..ba5e93ebdcd 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -36,6 +36,7 @@ export const SSH_TERMINATE_RECONNECT_REQUIRED = 'SSH_TERMINATE_RECONNECT_REQUIRE
 export const BROWSER_FAMILY_LABELS: Record<string, string> = {
   chrome: 'Google Chrome',
   chromium: 'Chromium',
+  comet: 'Comet',
   arc: 'Arc',
   edge: 'Microsoft Edge',
   brave: 'Brave',
diff --git a/src/shared/types.ts b/src/shared/types.ts
index d4642212d5e..1a2e09757fc 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -384,7 +384,7 @@ export type BrowserTab = BrowserWorkspace
 export type BrowserSessionProfileScope = 'default' | 'isolated' | 'imported'
 
 export type BrowserSessionProfileSource = {
-  browserFamily: 'chrome' | 'chromium' | 'arc' | 'edge' | 'firefox' | 'safari' | 'manual'
+  browserFamily: 'chrome' | 'chromium' | 'arc' | 'edge' | 'firefox' | 'safari' | 'comet' | 'manual'
   profileName?: string
   importedAt: number
 }

From 1b7c5aa11d3c1ad1d73c7f00068175f0428040c2 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 12:55:57 -0700
Subject: [PATCH 62/82] Remove browser promo design doc

---
 docs/browser-computer-use-promo.md | 64 ------------------------------
 1 file changed, 64 deletions(-)
 delete mode 100644 docs/browser-computer-use-promo.md

diff --git a/docs/browser-computer-use-promo.md b/docs/browser-computer-use-promo.md
deleted file mode 100644
index 3d735efbcd3..00000000000
--- a/docs/browser-computer-use-promo.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Browser Computer Use Promo
-
-## Problem
-Browser Use setup is in **Browser** settings, while **Computer Use** is a separate section. Users are not told that Computer Use can control already-authenticated desktop apps (including system browsers), which can be lower-friction than cookie import for some tasks.
-
-## Current constraints (code-verified)
-- `BrowserUseSetup` currently accepts only `onConfigureMoreBrowsers?: () => void` (`BrowserUsePane.tsx`).
-- `BrowserPane` is desktop-only because the entire Browser section is gated by `showDesktopOnlySettings` in `Settings.tsx`.
-- Browser Use toggle and “skill installed” are persisted in `localStorage` keys (`BROWSER_USE_ENABLED_STORAGE_KEY`, `BROWSER_USE_SKILL_INSTALLED_STORAGE_KEY`), but each window keeps its own React state copy after initial read (no `storage` event sync).
-- Computer Use section id is `computer-use` (`SettingsSection id`).
-- Settings search filters section mounting; filtered sections are absent from the DOM.
-- Canonical jump behavior already exists in `Settings.tsx` via `pendingNavSectionRef`, `pendingScrollTargetRef`, `scrollSectionIntoView`, and `flashSectionHighlight`.
-- `ComputerUsePane` always renders the skill install block; macOS permission controls render only when platform resolves to macOS.
-
-## Goal
-Add a compact promo inside expanded Browser Use that links to Computer Use and uses the existing Settings pending-nav jump path.
-
-## Non-goals
-- No Computer Use controls duplicated inside Browser.
-- No Browser Use step semantics changes.
-- No Computer Use backend/API changes.
-
-## Implementation
-1. Add `onOpenComputerUse?: () => void` to `BrowserUseSetupProps`.
-2. Thread that prop through `BrowserPaneProps` and pass it from `BrowserPane` to `BrowserUseSetup`.
-3. In `Settings.tsx`, pass `onOpenComputerUse` into `BrowserPane` that:
-- sets `pendingNavSectionRef.current = 'computer-use'`
-- sets `pendingScrollTargetRef.current = 'computer-use'`
-- clears search only if non-empty (`setSettingsSearchQuery('')`) so the section can mount
-4. Rely on existing `visibleNavSections` effect to execute scroll + flash and clear pending refs.
-5. Render promo only when Browser Use is enabled/expanded and callback exists.
-6. Place promo at top of expanded Browser Use card, before Step 1.
-7. Style with existing tokens/primitives only (`rounded-xl border border-border/60 bg-card/50`, existing `Button` variants, `MousePointerClick` icon).
-
-Do not implement ad-hoc local scroll logic in `BrowserUsePane` for this jump; keep section navigation centralized in `Settings.tsx`.
-
-## Copy constraints
-- State capability, not guarantee: Computer Use can control local apps and may use existing logged-in sessions where applicable.
-- State prerequisites: Computer Use skill install is required; macOS permissions are additionally required on macOS.
-- Position as an alternative path, not a replacement for Browser Use cookie import.
-
-## Edge cases to handle
-- Active search currently filters out `computer-use`.
-- Repeated CTA clicks before prior pending jump resolves (last click should remain idempotent).
-- Browser Use collapsed/disabled (no promo).
-- Multi-window state drift: localStorage-backed Browser Use UI state is not live-synced across open windows.
-- Non-mac platforms: CTA remains valid (skill flow still exists even without mac permission rows).
-- Web client: Browser section is absent, so promo path is unreachable by design.
-
-## Search indexing
-Update `BROWSER_USE_PANE_SEARCH_ENTRIES` to add intent terms for this promo while keeping existing terms:
-- `computer use`
-- `system browser`
-- `existing session`
-- `authenticated browser`
-- `chrome profile`
-- `edge profile`
-- `arc profile`
-
-## Acceptance criteria
-- Expanded Browser Use shows promo + CTA.
-- CTA lands on `computer-use`, flashes section highlight, and works when search filters are active.
-- No Browser Use step behavior changes.
-- No duplicated Computer Use controls in Browser.

From ac818caae53b35beb81cd51cf7da825264a8cbb4 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:13:55 -0700
Subject: [PATCH 63/82] Reduce GitHub GraphQL rate-limit spend (#1974)

---
 .gitignore                                    |   2 +
 src/main/github/client-issue-source.test.ts   |  12 +
 src/main/github/client-pr-checks.test.ts      |  12 +
 src/main/github/client-work-items.test.ts     |  12 +
 src/main/github/client.test.ts                |  88 +++++-
 src/main/github/client.ts                     |  35 ++-
 src/main/github/work-item-details.test.ts     |  48 ++++
 src/main/github/work-item-details.ts          |  13 +
 .../components/github/GitHubRateLimitPill.tsx | 228 +--------------
 .../github/github-rate-limit-display.tsx      | 267 ++++++++++++++++++
 .../components/right-sidebar/ChecksPanel.tsx  |   3 +
 .../src/components/right-sidebar/index.tsx    |  10 +
 .../src/components/settings/GitPane.tsx       |  16 ++
 .../src/components/settings/git-search.ts     |   5 +
 .../src/components/status-bar/StatusBar.tsx   |   2 +
 15 files changed, 519 insertions(+), 234 deletions(-)
 create mode 100644 src/renderer/src/components/github/github-rate-limit-display.tsx

diff --git a/.gitignore b/.gitignore
index 92b3d28c436..eca545b5345 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,7 +72,9 @@ design-docs/
 
 # Local-only design/planning docs (not checked in)
 docs/*.md
+docs/**/*.md
 !docs/README*.md
+!docs/**/README*.md
 
 # Stably CLI (only docs/ are tracked)
 .stably/*
diff --git a/src/main/github/client-issue-source.test.ts b/src/main/github/client-issue-source.test.ts
index ddeeca3a0a0..e899b69ef21 100644
--- a/src/main/github/client-issue-source.test.ts
+++ b/src/main/github/client-issue-source.test.ts
@@ -12,6 +12,8 @@ const {
   getIssueOwnerRepoMock,
   getOwnerRepoForRemoteMock,
   resolveIssueSourceMock,
+  rateLimitGuardMock,
+  noteRateLimitSpendMock,
   acquireMock,
   releaseMock
 } = vi.hoisted(() => ({
@@ -21,6 +23,8 @@ const {
   getIssueOwnerRepoMock: vi.fn(),
   getOwnerRepoForRemoteMock: vi.fn(),
   resolveIssueSourceMock: vi.fn(),
+  rateLimitGuardMock: vi.fn(() => ({ blocked: false })),
+  noteRateLimitSpendMock: vi.fn(),
   acquireMock: vi.fn(),
   releaseMock: vi.fn()
 }))
@@ -41,6 +45,11 @@ vi.mock('./gh-utils', async () => {
   }
 })
 
+vi.mock('./rate-limit', () => ({
+  rateLimitGuard: rateLimitGuardMock,
+  noteRateLimitSpend: noteRateLimitSpendMock
+}))
+
 import { countWorkItems, getWorkItem, listWorkItems, _resetOwnerRepoCache } from './client'
 
 describe('GitHub issue source split', () => {
@@ -51,6 +60,9 @@ describe('GitHub issue source split', () => {
     getIssueOwnerRepoMock.mockReset()
     getOwnerRepoForRemoteMock.mockReset()
     resolveIssueSourceMock.mockReset()
+    rateLimitGuardMock.mockReset()
+    rateLimitGuardMock.mockReturnValue({ blocked: false })
+    noteRateLimitSpendMock.mockReset()
     acquireMock.mockReset()
     releaseMock.mockReset()
     acquireMock.mockResolvedValue(undefined)
diff --git a/src/main/github/client-pr-checks.test.ts b/src/main/github/client-pr-checks.test.ts
index 1a3dadf957c..669fa7503d7 100644
--- a/src/main/github/client-pr-checks.test.ts
+++ b/src/main/github/client-pr-checks.test.ts
@@ -6,6 +6,8 @@ const {
   getOwnerRepoMock,
   getIssueOwnerRepoMock,
   gitExecFileAsyncMock,
+  rateLimitGuardMock,
+  noteRateLimitSpendMock,
   acquireMock,
   releaseMock
 } = vi.hoisted(() => ({
@@ -14,6 +16,8 @@ const {
   getOwnerRepoMock: vi.fn(),
   getIssueOwnerRepoMock: vi.fn(),
   gitExecFileAsyncMock: vi.fn(),
+  rateLimitGuardMock: vi.fn(() => ({ blocked: false })),
+  noteRateLimitSpendMock: vi.fn(),
   acquireMock: vi.fn(),
   releaseMock: vi.fn()
 }))
@@ -37,6 +41,11 @@ vi.mock('../git/runner', () => ({
   gitExecFileAsync: gitExecFileAsyncMock
 }))
 
+vi.mock('./rate-limit', () => ({
+  rateLimitGuard: rateLimitGuardMock,
+  noteRateLimitSpend: noteRateLimitSpendMock
+}))
+
 import { getPRChecks, _resetOwnerRepoCache } from './client'
 
 describe('getPRChecks', () => {
@@ -46,6 +55,9 @@ describe('getPRChecks', () => {
     getOwnerRepoMock.mockReset()
     getIssueOwnerRepoMock.mockReset()
     gitExecFileAsyncMock.mockReset()
+    rateLimitGuardMock.mockReset()
+    rateLimitGuardMock.mockReturnValue({ blocked: false })
+    noteRateLimitSpendMock.mockReset()
     acquireMock.mockReset()
     releaseMock.mockReset()
     acquireMock.mockResolvedValue(undefined)
diff --git a/src/main/github/client-work-items.test.ts b/src/main/github/client-work-items.test.ts
index 128037ba919..f68e466db41 100644
--- a/src/main/github/client-work-items.test.ts
+++ b/src/main/github/client-work-items.test.ts
@@ -11,6 +11,8 @@ const {
   getOwnerRepoForRemoteMock,
   resolveIssueSourceMock,
   gitExecFileAsyncMock,
+  rateLimitGuardMock,
+  noteRateLimitSpendMock,
   acquireMock,
   releaseMock
 } = vi.hoisted(() => ({
@@ -21,6 +23,8 @@ const {
   getOwnerRepoForRemoteMock: vi.fn(),
   resolveIssueSourceMock: vi.fn(),
   gitExecFileAsyncMock: vi.fn(),
+  rateLimitGuardMock: vi.fn(() => ({ blocked: false })),
+  noteRateLimitSpendMock: vi.fn(),
   acquireMock: vi.fn(),
   releaseMock: vi.fn()
 }))
@@ -48,6 +52,11 @@ vi.mock('../git/runner', () => ({
   gitExecFileAsync: gitExecFileAsyncMock
 }))
 
+vi.mock('./rate-limit', () => ({
+  rateLimitGuard: rateLimitGuardMock,
+  noteRateLimitSpend: noteRateLimitSpendMock
+}))
+
 import { listWorkItems, _resetOwnerRepoCache } from './client'
 
 describe('listWorkItems', () => {
@@ -59,6 +68,9 @@ describe('listWorkItems', () => {
     getOwnerRepoForRemoteMock.mockReset()
     resolveIssueSourceMock.mockReset()
     gitExecFileAsyncMock.mockReset()
+    rateLimitGuardMock.mockReset()
+    rateLimitGuardMock.mockReturnValue({ blocked: false })
+    noteRateLimitSpendMock.mockReset()
     acquireMock.mockReset()
     releaseMock.mockReset()
     acquireMock.mockResolvedValue(undefined)
diff --git a/src/main/github/client.test.ts b/src/main/github/client.test.ts
index 37b8241d565..e6e647e6311 100644
--- a/src/main/github/client.test.ts
+++ b/src/main/github/client.test.ts
@@ -1,6 +1,10 @@
 /* oxlint-disable max-lines -- Why: GitHub client fixtures cover local and SSH repo identity paths in one suite so mocked CLI behavior stays consistent. */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
+type RateLimitGuardResult =
+  | { blocked: false }
+  | { blocked: true; remaining: number; limit: number; resetAt: number }
+
 const {
   execFileAsyncMock,
   ghExecFileAsyncMock,
@@ -9,6 +13,8 @@ const {
   getOwnerRepoForRemoteMock,
   getRemoteUrlForRepoMock,
   gitExecFileAsyncMock,
+  rateLimitGuardMock,
+  noteRateLimitSpendMock,
   ghRepoExecOptionsMock,
   githubRepoContextMock,
   acquireMock,
@@ -21,6 +27,8 @@ const {
   getOwnerRepoForRemoteMock: vi.fn(),
   getRemoteUrlForRepoMock: vi.fn(),
   gitExecFileAsyncMock: vi.fn(),
+  rateLimitGuardMock: vi.fn<() => RateLimitGuardResult>(() => ({ blocked: false })),
+  noteRateLimitSpendMock: vi.fn(),
   ghRepoExecOptionsMock: vi.fn((context) =>
     context.connectionId ? {} : { cwd: context.repoPath }
   ),
@@ -59,7 +67,18 @@ vi.mock('../git/runner', () => ({
   gitExecFileAsync: gitExecFileAsyncMock
 }))
 
-import { getPRForBranch, getPullRequestPushTarget, _resetOwnerRepoCache } from './client'
+vi.mock('./rate-limit', () => ({
+  rateLimitGuard: rateLimitGuardMock,
+  noteRateLimitSpend: noteRateLimitSpendMock
+}))
+
+import {
+  getPRComments,
+  getPRForBranch,
+  getPullRequestPushTarget,
+  resolveReviewThread,
+  _resetOwnerRepoCache
+} from './client'
 
 describe('getPRForBranch', () => {
   beforeEach(() => {
@@ -70,6 +89,9 @@ describe('getPRForBranch', () => {
     getOwnerRepoForRemoteMock.mockReset()
     getRemoteUrlForRepoMock.mockReset()
     gitExecFileAsyncMock.mockReset()
+    rateLimitGuardMock.mockReset()
+    rateLimitGuardMock.mockReturnValue({ blocked: false })
+    noteRateLimitSpendMock.mockReset()
     ghRepoExecOptionsMock.mockClear()
     githubRepoContextMock.mockClear()
     acquireMock.mockReset()
@@ -422,3 +444,67 @@ describe('getPRForBranch', () => {
     expect(gitExecFileAsyncMock).not.toHaveBeenCalled()
   })
 })
+
+describe('GitHub GraphQL rate-limit guard', () => {
+  beforeEach(() => {
+    execFileAsyncMock.mockReset()
+    ghExecFileAsyncMock.mockReset()
+    getOwnerRepoMock.mockReset()
+    getIssueOwnerRepoMock.mockReset()
+    getOwnerRepoForRemoteMock.mockReset()
+    getRemoteUrlForRepoMock.mockReset()
+    gitExecFileAsyncMock.mockReset()
+    rateLimitGuardMock.mockReset()
+    rateLimitGuardMock.mockReturnValue({ blocked: false })
+    noteRateLimitSpendMock.mockReset()
+    acquireMock.mockReset()
+    releaseMock.mockReset()
+    acquireMock.mockResolvedValue(undefined)
+    _resetOwnerRepoCache()
+  })
+
+  it('skips PR review-thread GraphQL fetch while preserving REST comments', async () => {
+    rateLimitGuardMock.mockReturnValue({
+      blocked: true,
+      remaining: 4,
+      limit: 5000,
+      resetAt: 1_800_000_000
+    })
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'acme', repo: 'widgets' })
+    ghExecFileAsyncMock
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify([
+          {
+            id: 10,
+            user: { login: 'octo', avatar_url: 'https://avatar', type: 'User' },
+            body: 'top-level',
+            created_at: '2026-04-01T00:00:00Z',
+            html_url: 'https://github.com/acme/widgets/pull/7#issuecomment-10'
+          }
+        ])
+      })
+      .mockResolvedValueOnce({ stdout: '[]' })
+
+    const comments = await getPRComments('/repo-root', 7)
+
+    expect(comments).toHaveLength(1)
+    expect(comments[0].body).toBe('top-level')
+    expect(ghExecFileAsyncMock).toHaveBeenCalledTimes(2)
+    expect(ghExecFileAsyncMock.mock.calls.some((call) => call[0][1] === 'graphql')).toBe(false)
+    expect(noteRateLimitSpendMock).not.toHaveBeenCalled()
+  })
+
+  it('blocks review-thread resolve mutations before spawning gh when GraphQL is low', async () => {
+    rateLimitGuardMock.mockReturnValue({
+      blocked: true,
+      remaining: 4,
+      limit: 5000,
+      resetAt: 1_800_000_000
+    })
+
+    await expect(resolveReviewThread('/repo-root', 'thread-1', true)).resolves.toBe(false)
+
+    expect(ghExecFileAsyncMock).not.toHaveBeenCalled()
+    expect(noteRateLimitSpendMock).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index 6787553a2e7..4dcf66bf4f3 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -53,6 +53,7 @@ import {
   deriveCheckStatus
 } from './mappers'
 import { mapGraphQLReactionGroups, type GitHubGraphQLReactionGroup } from './comment-reactions'
+import { noteRateLimitSpend, rateLimitGuard } from './rate-limit'
 
 const ORCA_REPO = 'stablyai/orca'
 
@@ -1358,12 +1359,13 @@ export async function getPRComments(
       // permissions, transient network error) doesn't blank out all comments.
       // Each source is parsed independently; failed sources contribute zero
       // comments instead of aborting the entire fetch.
-      const [issueResult, threadsResult, reviewsResult] = await Promise.allSettled([
-        ghExecFileAsync(
-          ['api', ...cacheArgs, `${base}/issues/${prNumber}/comments?per_page=100`],
-          ghOptions
-        ),
-        ghExecFileAsync(
+      const reviewThreadsGuard = rateLimitGuard('graphql')
+      let reviewThreadsFetch: Promise<{ stdout: string; stderr: string } | null>
+      if (reviewThreadsGuard.blocked) {
+        reviewThreadsFetch = Promise.resolve(null)
+      } else {
+        noteRateLimitSpend('graphql')
+        reviewThreadsFetch = ghExecFileAsync(
           [
             'api',
             'graphql',
@@ -1377,7 +1379,14 @@ export async function getPRComments(
             `pr=${prNumber}`
           ],
           ghOptions
+        )
+      }
+      const [issueResult, threadsResult, reviewsResult] = await Promise.allSettled([
+        ghExecFileAsync(
+          ['api', ...cacheArgs, `${base}/issues/${prNumber}/comments?per_page=100`],
+          ghOptions
         ),
+        reviewThreadsFetch,
         // Why: review summaries (approve, request changes, general comments) live
         // under pulls/{n}/reviews, not under issue comments or review threads.
         // Without this, a reviewer who submits "LGTM" without inline threads
@@ -1442,7 +1451,7 @@ export async function getPRComments(
         reactionGroups?: GitHubGraphQLReactionGroup[] | null
       }
       const reviewComments: PRComment[] = []
-      if (threadsResult.status === 'fulfilled') {
+      if (threadsResult.status === 'fulfilled' && threadsResult.value) {
         const threadsData = JSON.parse(threadsResult.value.stdout) as {
           data: {
             repository: {
@@ -1494,7 +1503,9 @@ export async function getPRComments(
           }
         }
       } else {
-        console.warn('Failed to fetch review threads:', threadsResult.reason)
+        if (threadsResult.status === 'rejected') {
+          console.warn('Failed to fetch review threads:', threadsResult.reason)
+        }
       }
 
       // Parse review summaries (REST) — only include reviews with a body,
@@ -1572,8 +1583,16 @@ export async function resolveReviewThread(
   const mutation = resolve ? 'resolveReviewThread' : 'unresolveReviewThread'
   const query = `mutation($threadId: ID!) { ${mutation}(input: { threadId: $threadId }) { thread { isResolved } } }`
   const ghOptions = ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
+  const guard = rateLimitGuard('graphql')
+  if (guard.blocked) {
+    console.warn(
+      `${mutation} skipped: GitHub GraphQL rate limit nearly exhausted (${guard.remaining}/${guard.limit})`
+    )
+    return false
+  }
   await acquire()
   try {
+    noteRateLimitSpend('graphql')
     await ghExecFileAsync(
       ['api', 'graphql', '-f', `query=${query}`, '-f', `threadId=${threadId}`],
       ghOptions
diff --git a/src/main/github/work-item-details.test.ts b/src/main/github/work-item-details.test.ts
index c8a8c3fa409..30517f8c4ae 100644
--- a/src/main/github/work-item-details.test.ts
+++ b/src/main/github/work-item-details.test.ts
@@ -1,5 +1,9 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
+type RateLimitGuardResult =
+  | { blocked: false }
+  | { blocked: true; remaining: number; limit: number; resetAt: number }
+
 const {
   ghExecFileAsyncMock,
   getOwnerRepoMock,
@@ -7,6 +11,8 @@ const {
   getWorkItemMock,
   getPRChecksMock,
   getPRCommentsMock,
+  rateLimitGuardMock,
+  noteRateLimitSpendMock,
   ghRepoExecOptionsMock,
   githubRepoContextMock,
   acquireMock,
@@ -18,6 +24,8 @@ const {
   getWorkItemMock: vi.fn(),
   getPRChecksMock: vi.fn(),
   getPRCommentsMock: vi.fn(),
+  rateLimitGuardMock: vi.fn<() => RateLimitGuardResult>(() => ({ blocked: false })),
+  noteRateLimitSpendMock: vi.fn(),
   ghRepoExecOptionsMock: vi.fn((context) =>
     context.connectionId ? {} : { cwd: context.repoPath }
   ),
@@ -45,6 +53,11 @@ vi.mock('./client', () => ({
   getPRComments: getPRCommentsMock
 }))
 
+vi.mock('./rate-limit', () => ({
+  rateLimitGuard: rateLimitGuardMock,
+  noteRateLimitSpend: noteRateLimitSpendMock
+}))
+
 import { getWorkItemDetails } from './work-item-details'
 
 describe('getWorkItemDetails', () => {
@@ -55,6 +68,9 @@ describe('getWorkItemDetails', () => {
     getWorkItemMock.mockReset()
     getPRChecksMock.mockReset()
     getPRCommentsMock.mockReset()
+    rateLimitGuardMock.mockReset()
+    rateLimitGuardMock.mockReturnValue({ blocked: false })
+    noteRateLimitSpendMock.mockReset()
     ghRepoExecOptionsMock.mockClear()
     githubRepoContextMock.mockClear()
     acquireMock.mockReset()
@@ -158,6 +174,38 @@ describe('getWorkItemDetails', () => {
     expect(details?.body).toBe('Issue body')
   })
 
+  it('skips optional GraphQL issue detail calls when the cached GraphQL budget is low', async () => {
+    rateLimitGuardMock.mockReturnValue({
+      blocked: true,
+      remaining: 3,
+      limit: 5000,
+      resetAt: 1_800_000_000
+    })
+    getWorkItemMock.mockResolvedValueOnce({
+      id: 'issue:923',
+      type: 'issue',
+      number: 923,
+      title: 'Use upstream issues',
+      state: 'open',
+      url: 'https://github.com/stablyai/orca/issues/923',
+      labels: [],
+      updatedAt: '2026-04-01T00:00:00Z',
+      author: 'octocat'
+    })
+    getIssueOwnerRepoMock.mockResolvedValue({ owner: 'stablyai', repo: 'orca' })
+    ghExecFileAsyncMock
+      .mockResolvedValueOnce({ stdout: JSON.stringify({ body: 'Issue body', assignees: [] }) })
+      .mockResolvedValueOnce({ stdout: '[]' })
+
+    const details = await getWorkItemDetails('/repo-root', 923, 'issue')
+
+    expect(ghExecFileAsyncMock).toHaveBeenCalledTimes(2)
+    expect(ghExecFileAsyncMock.mock.calls.some((call) => call[0][1] === 'graphql')).toBe(false)
+    expect(noteRateLimitSpendMock).not.toHaveBeenCalled()
+    expect(details?.body).toBe('Issue body')
+    expect(details?.participants).toEqual([])
+  })
+
   it('uses SSH connection context for issue details without local cwd', async () => {
     getWorkItemMock.mockResolvedValueOnce({
       id: 'issue:923',
diff --git a/src/main/github/work-item-details.ts b/src/main/github/work-item-details.ts
index 7d7ab66d795..d417cbe45f4 100644
--- a/src/main/github/work-item-details.ts
+++ b/src/main/github/work-item-details.ts
@@ -19,6 +19,7 @@ import {
   githubRepoContext
 } from './gh-utils'
 import { getWorkItem, getPRChecks, getPRComments } from './client'
+import { noteRateLimitSpend, rateLimitGuard } from './rate-limit'
 
 // Why: a PR "changed file" listing returned by the REST endpoint is paginated
 // at 100 per page; we cap at a reasonable total so a massive PR cannot starve
@@ -112,7 +113,11 @@ async function getIssueDetailsViaGraphQL(
   if (!ownerRepo) {
     return null
   }
+  if (rateLimitGuard('graphql').blocked) {
+    return null
+  }
   try {
+    noteRateLimitSpend('graphql')
     const { stdout } = await ghExecFileAsync(
       [
         'api',
@@ -441,7 +446,11 @@ async function getWorkItemParticipants(
   if (!ownerRepo) {
     return []
   }
+  if (rateLimitGuard('graphql').blocked) {
+    return []
+  }
   try {
+    noteRateLimitSpend('graphql')
     const { stdout } = await ghExecFileAsync(
       [
         'api',
@@ -498,6 +507,9 @@ async function getGitHubUsersByLogin(
   if (uniqueLogins.length === 0) {
     return []
   }
+  if (rateLimitGuard('graphql').blocked) {
+    return []
+  }
   const fields = uniqueLogins
     .map(
       (login, index) =>
@@ -505,6 +517,7 @@ async function getGitHubUsersByLogin(
     )
     .join('\n')
   try {
+    noteRateLimitSpend('graphql')
     const { stdout } = await ghExecFileAsync(
       ['api', 'graphql', '-f', `query=query { ${fields} }`],
       ghRepoExecOptions(githubRepoContext(repoPath, connectionId))
diff --git a/src/renderer/src/components/github/GitHubRateLimitPill.tsx b/src/renderer/src/components/github/GitHubRateLimitPill.tsx
index 714ad1510ba..532094cbc18 100644
--- a/src/renderer/src/components/github/GitHubRateLimitPill.tsx
+++ b/src/renderer/src/components/github/GitHubRateLimitPill.tsx
@@ -1,228 +1,6 @@
-/**
- * Compact GitHub API rate-limit indicator for the TaskPage header.
- *
- * Why: TaskPage fans out GitHub requests on every preset click, search
- * debounce, and repo-selection change (×N selected repos × 2 halves for
- * count). Users with large repo selections or heavy usage can exhaust the
- * search API's 30/min budget in a few clicks without knowing.
- *
- * Display policy: stay invisible during normal use. Only render when a
- * bucket drops to <25% remaining (warn) or <10% (crit). At healthy levels
- * the budget is not actionable information and surfacing it just trains
- * users to ignore the pill (or worry needlessly about ambiguous numbers
- * like "30/30"). The probe still refreshes while the page is active so we
- * can show the pill the moment something becomes actionable.
- *
- * This is an indicator, not a throttle — we deliberately don't block the
- * user from making requests when counts are low. Blocking would hurt the
- * hot path (well under quota) more than it helps the cold path (user can
- * also just wait for the reset, which is always < 1 hour).
- */
-import React, { useCallback, useEffect, useRef, useState } from 'react'
-import { Gauge } from 'lucide-react'
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
-import { cn } from '@/lib/utils'
-import { useAppStore } from '@/store'
-import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
-import type { GetRateLimitResult, GitHubRateLimitSnapshot } from '../../../../shared/types'
-
-// Why: 60s client-side cadence. Aligns with typical user action rhythm
-// (click → paint → click) without polling faster than GitHub's counters
-// move for typical request volumes. The server-side 30s cache absorbs
-// any faster-than-this polling.
-const REFRESH_INTERVAL_MS = 60_000
-
-type BucketKey = 'core' | 'search' | 'graphql'
-
-type BucketMeta = {
-  key: BucketKey
-  label: string
-  description: string
-}
-
-const BUCKETS: BucketMeta[] = [
-  { key: 'core', label: 'REST', description: 'REST API (5000/hr)' },
-  { key: 'search', label: 'Search', description: 'Search API (30/min)' },
-  { key: 'graphql', label: 'GraphQL', description: 'GraphQL (5000 pts/hr)' }
-]
-
-function formatReset(resetAt: number): string {
-  // Why: resetAt is seconds, Date.now() is ms. Compute the gap in seconds so
-  // "<1min" / "in 45s" / "in 12min" reads naturally without cognitive math.
-  const deltaSec = Math.max(0, resetAt - Math.floor(Date.now() / 1000))
-  if (deltaSec < 60) {
-    return `${deltaSec}s`
-  }
-  const mins = Math.round(deltaSec / 60)
-  return `${mins}m`
-}
-
-function toneFor(remaining: number, limit: number): 'ok' | 'warn' | 'crit' {
-  if (limit <= 0) {
-    return 'ok'
-  }
-  const pct = remaining / limit
-  if (pct < 0.1) {
-    return 'crit'
-  }
-  if (pct < 0.25) {
-    return 'warn'
-  }
-  return 'ok'
-}
-
-function worstTone(snapshot: GitHubRateLimitSnapshot): 'ok' | 'warn' | 'crit' {
-  const tones = BUCKETS.map((b) => toneFor(snapshot[b.key].remaining, snapshot[b.key].limit))
-  if (tones.includes('crit')) {
-    return 'crit'
-  }
-  if (tones.includes('warn')) {
-    return 'warn'
-  }
-  return 'ok'
-}
-
-function tightestBucket(snapshot: GitHubRateLimitSnapshot): BucketMeta {
-  // Why: "N left" in the pill shows the bucket closest to exhaustion by
-  // ratio — that's the actionable one. Absolute remaining would always
-  // favor GraphQL (5000 pts) over Search (30) even when Search is 1 away.
-  let worst = BUCKETS[0]
-  let worstPct = 1
-  for (const b of BUCKETS) {
-    const { remaining, limit } = snapshot[b.key]
-    const pct = limit > 0 ? remaining / limit : 1
-    if (pct < worstPct) {
-      worstPct = pct
-      worst = b
-    }
-  }
-  return worst
-}
+import React from 'react'
+import { GitHubRateLimitCompact } from './github-rate-limit-display'
 
 export default function GitHubRateLimitPill(): React.JSX.Element | null {
-  const [snapshot, setSnapshot] = useState<GitHubRateLimitSnapshot | null>(null)
-  const [hasError, setHasError] = useState(false)
-  const settings = useAppStore((s) => s.settings)
-  // Why: StrictMode double-invokes effects in dev. Without this guard the
-  // first mount fires two rate_limit IPCs back-to-back — benign (exempt
-  // endpoint, cached) but noisy in logs. Tracks the latest in-flight token
-  // so stale responses from an unmounted instance are dropped.
-  const latestToken = useRef(0)
-
-  const fetchSnapshot = useCallback(
-    async (force: boolean): Promise<void> => {
-      const token = ++latestToken.current
-      try {
-        const target = getActiveRuntimeTarget(settings)
-        const params = force ? { force: true } : undefined
-        const res =
-          target.kind === 'environment'
-            ? await callRuntimeRpc<GetRateLimitResult>(target, 'github.rateLimit', params ?? {}, {
-                timeoutMs: 30_000
-              })
-            : ((await window.api.gh.rateLimit(params)) as GetRateLimitResult | undefined)
-        if (token !== latestToken.current) {
-          return
-        }
-        if (res?.ok) {
-          setSnapshot(res.snapshot)
-          setHasError(false)
-        } else {
-          setHasError(true)
-        }
-      } catch {
-        if (token !== latestToken.current) {
-          return
-        }
-        setHasError(true)
-      }
-    },
-    [settings]
-  )
-
-  useEffect(() => {
-    const fetchIfVisible = (): void => {
-      if (document.visibilityState === 'visible' && document.hasFocus()) {
-        void fetchSnapshot(false)
-      }
-    }
-    void fetchSnapshot(false)
-    // Why: rate-limit probes are only useful while the TaskPage is visible.
-    // Skipping hidden-window ticks avoids spending gh/API work just to keep an
-    // invisible pill current; focus refreshes restore freshness before use.
-    const handle = window.setInterval(fetchIfVisible, REFRESH_INTERVAL_MS)
-    window.addEventListener('focus', fetchIfVisible)
-    document.addEventListener('visibilitychange', fetchIfVisible)
-    return () => {
-      window.clearInterval(handle)
-      window.removeEventListener('focus', fetchIfVisible)
-      document.removeEventListener('visibilitychange', fetchIfVisible)
-    }
-  }, [fetchSnapshot])
-
-  // Why: silently render nothing on error or before first load. The pill is
-  // informational — surfacing a red error here would mislead users into
-  // thinking their actual gh workflow is broken when only the probe failed.
-  if (!snapshot || hasError) {
-    return null
-  }
-
-  const tone = worstTone(snapshot)
-  // Why: hide the pill entirely at healthy levels. It only earns screen
-  // real estate when the user is actually approaching a wall — otherwise
-  // "30/30" is ambiguous noise that users can't act on.
-  if (tone === 'ok') {
-    return null
-  }
-  const tight = tightestBucket(snapshot)
-  const tightBucket = snapshot[tight.key]
-
-  return (
-    <Tooltip>
-      <TooltipTrigger asChild>
-        <button
-          type="button"
-          onClick={() => void fetchSnapshot(true)}
-          aria-label="GitHub rate limit"
-          className={cn(
-            'inline-flex h-6 items-center gap-1 rounded-md border px-1.5 text-[10px] font-medium transition',
-            tone === 'crit' &&
-              'border-red-500/40 bg-red-500/10 text-red-700 dark:text-red-300 hover:bg-red-500/20',
-            tone === 'warn' &&
-              'border-amber-500/40 bg-amber-500/10 text-amber-700 dark:text-amber-300 hover:bg-amber-500/20'
-          )}
-        >
-          <Gauge className="size-3" />
-          <span>
-            {/* Why: "N left" is unambiguous; "N/M" reads as either
-                used-of-total or remaining-of-total depending on the user's
-                prior. We only show this pill when low, so the count is
-                already actionable — no need for the denominator here. */}
-            {tightBucket.remaining} {tight.label.toLowerCase()} left · resets in{' '}
-            {formatReset(tightBucket.resetAt)}
-          </span>
-        </button>
-      </TooltipTrigger>
-      <TooltipContent side="bottom" sideOffset={6} className="text-xs">
-        <div className="font-medium">GitHub API budget</div>
-        <div className="mt-1 flex flex-col gap-0.5 font-mono">
-          {BUCKETS.map((b) => {
-            const v = snapshot[b.key]
-            const t = toneFor(v.remaining, v.limit)
-            return (
-              <div key={b.key} className="flex items-center justify-between gap-3">
-                <span>{b.description}</span>
-                <span
-                  className={cn(t === 'crit' && 'text-red-400', t === 'warn' && 'text-amber-400')}
-                >
-                  {v.remaining} of {v.limit} left · resets in {formatReset(v.resetAt)}
-                </span>
-              </div>
-            )
-          })}
-        </div>
-        <div className="mt-1 text-muted-foreground">Click to refresh</div>
-      </TooltipContent>
-    </Tooltip>
-  )
+  return <GitHubRateLimitCompact label="GitHub API budget" tooltipSide="bottom" />
 }
diff --git a/src/renderer/src/components/github/github-rate-limit-display.tsx b/src/renderer/src/components/github/github-rate-limit-display.tsx
new file mode 100644
index 00000000000..52fa0d66e6b
--- /dev/null
+++ b/src/renderer/src/components/github/github-rate-limit-display.tsx
@@ -0,0 +1,267 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { Gauge, RefreshCw } from 'lucide-react'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { cn } from '@/lib/utils'
+import { useAppStore } from '@/store'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import type { GetRateLimitResult, GitHubRateLimitSnapshot } from '../../../../shared/types'
+
+const REFRESH_INTERVAL_MS = 60_000
+
+type BucketKey = 'core' | 'search' | 'graphql'
+
+type BucketMeta = {
+  key: BucketKey
+  label: string
+  description: string
+}
+
+const BUCKETS: BucketMeta[] = [
+  { key: 'core', label: 'REST', description: 'REST API' },
+  { key: 'search', label: 'Search', description: 'Search API' },
+  { key: 'graphql', label: 'GraphQL', description: 'GraphQL API' }
+]
+
+export function formatGitHubRateLimitReset(resetAt: number): string {
+  const deltaSec = Math.max(0, resetAt - Math.floor(Date.now() / 1000))
+  if (deltaSec < 60) {
+    return `${deltaSec}s`
+  }
+  const mins = Math.round(deltaSec / 60)
+  return `${mins}m`
+}
+
+export function toneForGitHubBucket(remaining: number, limit: number): 'ok' | 'warn' | 'crit' {
+  if (limit <= 0) {
+    return 'ok'
+  }
+  const pct = remaining / limit
+  if (pct < 0.1) {
+    return 'crit'
+  }
+  if (pct < 0.25) {
+    return 'warn'
+  }
+  return 'ok'
+}
+
+function worstGitHubRateLimitTone(snapshot: GitHubRateLimitSnapshot): 'ok' | 'warn' | 'crit' {
+  const tones = BUCKETS.map((b) =>
+    toneForGitHubBucket(snapshot[b.key].remaining, snapshot[b.key].limit)
+  )
+  if (tones.includes('crit')) {
+    return 'crit'
+  }
+  if (tones.includes('warn')) {
+    return 'warn'
+  }
+  return 'ok'
+}
+
+function tightestGitHubBucket(snapshot: GitHubRateLimitSnapshot): BucketMeta {
+  let worst = BUCKETS[0]
+  let worstPct = 1
+  for (const b of BUCKETS) {
+    const { remaining, limit } = snapshot[b.key]
+    const pct = limit > 0 ? remaining / limit : 1
+    if (pct < worstPct) {
+      worstPct = pct
+      worst = b
+    }
+  }
+  return worst
+}
+
+export function useGitHubRateLimitSnapshot(options?: { autoRefresh?: boolean }): {
+  snapshot: GitHubRateLimitSnapshot | null
+  hasError: boolean
+  isFetching: boolean
+  refresh: (force?: boolean) => Promise<void>
+} {
+  const [snapshot, setSnapshot] = useState<GitHubRateLimitSnapshot | null>(null)
+  const [hasError, setHasError] = useState(false)
+  const [isFetching, setIsFetching] = useState(false)
+  const settings = useAppStore((s) => s.settings)
+  const latestToken = useRef(0)
+  const autoRefresh = options?.autoRefresh ?? true
+
+  const refresh = useCallback(
+    async (force = false): Promise<void> => {
+      const token = ++latestToken.current
+      setIsFetching(true)
+      try {
+        const target = getActiveRuntimeTarget(settings)
+        const params = force ? { force: true } : undefined
+        const res =
+          target.kind === 'environment'
+            ? await callRuntimeRpc<GetRateLimitResult>(target, 'github.rateLimit', params ?? {}, {
+                timeoutMs: 30_000
+              })
+            : ((await window.api.gh.rateLimit(params)) as GetRateLimitResult | undefined)
+        if (token !== latestToken.current) {
+          return
+        }
+        if (res?.ok) {
+          setSnapshot(res.snapshot)
+          setHasError(false)
+        } else {
+          setHasError(true)
+        }
+      } catch {
+        if (token === latestToken.current) {
+          setHasError(true)
+        }
+      } finally {
+        if (token === latestToken.current) {
+          setIsFetching(false)
+        }
+      }
+    },
+    [settings]
+  )
+
+  useEffect(() => {
+    if (!autoRefresh) {
+      return
+    }
+    const fetchIfVisible = (): void => {
+      if (document.visibilityState === 'visible' && document.hasFocus()) {
+        void refresh(false)
+      }
+    }
+    void refresh(false)
+    const handle = window.setInterval(fetchIfVisible, REFRESH_INTERVAL_MS)
+    window.addEventListener('focus', fetchIfVisible)
+    document.addEventListener('visibilitychange', fetchIfVisible)
+    return () => {
+      window.clearInterval(handle)
+      window.removeEventListener('focus', fetchIfVisible)
+      document.removeEventListener('visibilitychange', fetchIfVisible)
+    }
+  }, [autoRefresh, refresh])
+
+  return { snapshot, hasError, isFetching, refresh }
+}
+
+function GitHubRateLimitRows({
+  snapshot
+}: {
+  snapshot: GitHubRateLimitSnapshot
+}): React.JSX.Element {
+  return (
+    <div className="flex flex-col gap-1 font-mono">
+      {BUCKETS.map((b) => {
+        const v = snapshot[b.key]
+        const tone = toneForGitHubBucket(v.remaining, v.limit)
+        return (
+          <div key={b.key} className="flex items-center justify-between gap-3">
+            <span className="text-muted-foreground">{b.description}</span>
+            <span
+              className={cn(
+                'text-foreground',
+                tone === 'crit' && 'text-red-600 dark:text-red-300',
+                tone === 'warn' && 'text-amber-700 dark:text-amber-300'
+              )}
+            >
+              {v.remaining} of {v.limit} left · resets in {formatGitHubRateLimitReset(v.resetAt)}
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+export function GitHubRateLimitCompact({
+  className,
+  hideHealthy = true,
+  label = 'GitHub API budget',
+  tooltipSide = 'top'
+}: {
+  className?: string
+  hideHealthy?: boolean
+  label?: string
+  tooltipSide?: 'top' | 'right' | 'bottom' | 'left'
+}): React.JSX.Element | null {
+  const { snapshot, hasError, refresh } = useGitHubRateLimitSnapshot()
+  if (!snapshot || hasError) {
+    return null
+  }
+
+  const tone = worstGitHubRateLimitTone(snapshot)
+  if (hideHealthy && tone === 'ok') {
+    return null
+  }
+  const tight = tightestGitHubBucket(snapshot)
+  const tightBucket = snapshot[tight.key]
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          onClick={() => void refresh(true)}
+          aria-label={label}
+          className={cn(
+            'inline-flex h-6 min-w-0 items-center gap-1 rounded-md border px-1.5 text-[10px] font-medium transition',
+            tone === 'ok' && 'border-border bg-secondary text-secondary-foreground hover:bg-accent',
+            tone === 'crit' &&
+              'border-red-500/40 bg-red-500/10 text-red-700 dark:text-red-300 hover:bg-red-500/20',
+            tone === 'warn' &&
+              'border-amber-500/40 bg-amber-500/10 text-amber-700 dark:text-amber-300 hover:bg-amber-500/20',
+            className
+          )}
+        >
+          <Gauge className="size-3 shrink-0" />
+          <span className="truncate">
+            {tightBucket.remaining} {tight.label.toLowerCase()} left · resets in{' '}
+            {formatGitHubRateLimitReset(tightBucket.resetAt)}
+          </span>
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side={tooltipSide} sideOffset={6} className="text-xs">
+        <div className="font-medium">{label}</div>
+        <div className="mt-1">
+          <GitHubRateLimitRows snapshot={snapshot} />
+        </div>
+        <div className="mt-1 text-muted-foreground">Click to refresh</div>
+      </TooltipContent>
+    </Tooltip>
+  )
+}
+
+export function GitHubRateLimitPanel({ className }: { className?: string }): React.JSX.Element {
+  const { snapshot, hasError, isFetching, refresh } = useGitHubRateLimitSnapshot()
+
+  return (
+    <div className={cn('space-y-3 rounded-md border border-border/60 p-3', className)}>
+      <div className="flex items-start justify-between gap-3">
+        <div className="space-y-0.5">
+          <div className="flex items-center gap-1.5 text-sm font-medium text-foreground">
+            <Gauge className="size-4" />
+            GitHub API Budget
+          </div>
+          <p className="text-xs text-muted-foreground">
+            Orca uses REST, Search, and GraphQL through the GitHub CLI.
+          </p>
+        </div>
+        <button
+          type="button"
+          onClick={() => void refresh(true)}
+          disabled={isFetching}
+          className="inline-flex size-7 items-center justify-center rounded-md border border-border bg-secondary text-secondary-foreground transition hover:bg-accent disabled:opacity-50"
+          aria-label="Refresh GitHub API budget"
+        >
+          <RefreshCw className={cn('size-3.5', isFetching && 'animate-spin')} />
+        </button>
+      </div>
+      {hasError ? (
+        <div className="text-xs text-muted-foreground">GitHub API budget is unavailable.</div>
+      ) : snapshot ? (
+        <GitHubRateLimitRows snapshot={snapshot} />
+      ) : (
+        <div className="text-xs text-muted-foreground">Loading GitHub API budget…</div>
+      )}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index a550e225647..e22a31cb685 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -17,6 +17,7 @@ import {
 } from './checks-panel-content'
 import { ENTRY_REFRESH_GRACE_MS, shouldEntryRefresh } from './checks-entry-refresh'
 import type { PRInfo, PRCheckDetail, PRComment } from '../../../../shared/types'
+import { toast } from 'sonner'
 
 export default function ChecksPanel(): React.JSX.Element {
   const activeWorktree = useActiveWorktree()
@@ -425,6 +426,8 @@ export default function ChecksPanel(): React.JSX.Element {
             setComments((prev) =>
               prev.map((c) => (c.threadId === threadId ? { ...c, isResolved: resolve } : c))
             )
+          } else {
+            toast.error('Could not update review thread. Check the GitHub API budget.')
           }
         }
       )
diff --git a/src/renderer/src/components/right-sidebar/index.tsx b/src/renderer/src/components/right-sidebar/index.tsx
index a5a69821891..f277f827f9d 100644
--- a/src/renderer/src/components/right-sidebar/index.tsx
+++ b/src/renderer/src/components/right-sidebar/index.tsx
@@ -22,6 +22,7 @@ import SourceControl from './SourceControl'
 import SearchPanel from './Search'
 import ChecksPanel from './ChecksPanel'
 import PortsPanel from './PortsPanel'
+import { GitHubRateLimitCompact } from '@/components/github/github-rate-limit-display'
 
 const MIN_WIDTH = 220
 // Why: long file names (e.g. construction drawing sheets, multi-part document
@@ -213,6 +214,8 @@ function RightSidebarInner(): React.JSX.Element {
   const effectiveTab = visibleItems.some((item) => item.id === rightSidebarTab)
     ? rightSidebarTab
     : visibleItems[0].id
+  const showGitHubBudgetInPanel =
+    !isFolder && (effectiveTab === 'source-control' || effectiveTab === 'checks')
 
   const activityBarSideWidth = activityBarPosition === 'side' ? ACTIVITY_BAR_SIDE_WIDTH : 0
   const maxWidth = useWindowAwareMaxWidth()
@@ -333,6 +336,13 @@ function RightSidebarInner(): React.JSX.Element {
           </div>
         )}
 
+        {showGitHubBudgetInPanel ? (
+          <GitHubRateLimitCompact
+            className="mx-2 my-1.5 max-w-[calc(100%-1rem)] self-start"
+            label="GitHub API budget for this panel"
+          />
+        ) : null}
+
         {panelContent}
 
         {/* Resize handle on LEFT side */}
diff --git a/src/renderer/src/components/settings/GitPane.tsx b/src/renderer/src/components/settings/GitPane.tsx
index 6810ef47c07..e7c4d924b76 100644
--- a/src/renderer/src/components/settings/GitPane.tsx
+++ b/src/renderer/src/components/settings/GitPane.tsx
@@ -5,6 +5,7 @@ import { useAppStore } from '../../store'
 import { GIT_PANE_SEARCH_ENTRIES } from './git-search'
 import { SearchableSetting } from './SearchableSetting'
 import { matchesSettingsSearch } from './settings-search'
+import { GitHubRateLimitPanel } from '../github/github-rate-limit-display'
 
 export { GIT_PANE_SEARCH_ENTRIES }
 
@@ -110,6 +111,21 @@ export function GitPane({
         </button>
       </SearchableSetting>
     ) : null,
+    matchesSettingsSearch(searchQuery, {
+      title: 'GitHub API Budget',
+      description: 'Current GitHub CLI REST, Search, and GraphQL rate limits.',
+      keywords: ['github', 'gh', 'graphql', 'rate limit', 'api budget']
+    }) ? (
+      <SearchableSetting
+        key="github-api-budget"
+        title="GitHub API Budget"
+        description="Current GitHub CLI REST, Search, and GraphQL rate limits."
+        keywords={['github', 'gh', 'graphql', 'rate limit', 'api budget']}
+        className="space-y-3"
+      >
+        <GitHubRateLimitPanel />
+      </SearchableSetting>
+    ) : null,
     matchesSettingsSearch(searchQuery, {
       title: 'Orca Attribution',
       description: 'Add Orca attribution to commits, PRs, and issues.',
diff --git a/src/renderer/src/components/settings/git-search.ts b/src/renderer/src/components/settings/git-search.ts
index cb66e34ee00..e26ee40bb41 100644
--- a/src/renderer/src/components/settings/git-search.ts
+++ b/src/renderer/src/components/settings/git-search.ts
@@ -11,6 +11,11 @@ export const GIT_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
     description: 'Optionally fast-forward local main or master when creating worktrees.',
     keywords: ['main', 'master', 'origin/main', 'git diff', 'base ref', 'worktree']
   },
+  {
+    title: 'GitHub API Budget',
+    description: 'Current GitHub CLI REST, Search, and GraphQL rate limits.',
+    keywords: ['github', 'gh', 'graphql', 'rate limit', 'api budget']
+  },
   {
     title: 'Orca Attribution',
     description: 'Add Orca attribution to commits, PRs, and issues.',
diff --git a/src/renderer/src/components/status-bar/StatusBar.tsx b/src/renderer/src/components/status-bar/StatusBar.tsx
index 418292e0e93..c18c1f33efb 100644
--- a/src/renderer/src/components/status-bar/StatusBar.tsx
+++ b/src/renderer/src/components/status-bar/StatusBar.tsx
@@ -38,6 +38,7 @@ import { isStatusBarItemAvailable } from './status-bar-agent-gating'
 import { PetStatusSegment } from './PetStatusSegment'
 import { TOGGLE_FLOATING_TERMINAL_EVENT } from '@/lib/floating-terminal'
 import { FloatingTerminalIconContextMenu } from '@/components/floating-terminal/FloatingTerminalIconContextMenu'
+import { GitHubRateLimitCompact } from '@/components/github/github-rate-limit-display'
 
 type StatusBarProps = {
   floatingTerminalOpen: boolean
@@ -855,6 +856,7 @@ function StatusBarInner({ floatingTerminalOpen }: StatusBarProps): React.JSX.Ele
       }}
     >
       <div className="flex items-center gap-3">
+        <GitHubRateLimitCompact label="GitHub API budget" />
         {showClaude && <ClaudeSwitcherMenu claude={claude} compact={compact} iconOnly={iconOnly} />}
         {showCodex && <CodexSwitcherMenu codex={codex} compact={compact} iconOnly={iconOnly} />}
         {showGemini && (

From 79838275a45554b1e338c260ddeb32f2817cc881 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 15 May 2026 16:16:55 -0400
Subject: [PATCH 64/82] Improve Claude and Codex usage tracking (#1968)

Co-authored-by: Orca <help@stably.ai>
---
 src/main/claude-usage/scanner-scan.test.ts    | 136 +++++-
 src/main/claude-usage/scanner.test.ts         | 102 ++++-
 src/main/claude-usage/scanner.ts              | 331 ++++++++++++--
 src/main/claude-usage/store.test.ts           |  26 ++
 src/main/claude-usage/store.ts                | 164 ++++++-
 src/main/claude-usage/types.ts                |   9 +-
 src/main/codex-usage/scanner.test.ts          |  51 ++-
 src/main/codex-usage/scanner.ts               | 129 +++++-
 src/main/codex-usage/store.test.ts            |  74 +++-
 src/main/codex-usage/store.ts                 | 150 ++++++-
 .../src/components/settings/Settings.tsx      |   2 +-
 .../src/components/stats/StatsPane.tsx        |  19 +-
 .../components/stats/UsageOverviewPane.tsx    | 412 ++++++++++++++++++
 .../stats/usage-overview-model.test.ts        | 207 +++++++++
 .../components/stats/usage-overview-model.ts  | 319 ++++++++++++++
 tests/e2e/usage-overview.spec.ts              |  35 ++
 16 files changed, 2064 insertions(+), 102 deletions(-)
 create mode 100644 src/renderer/src/components/stats/UsageOverviewPane.tsx
 create mode 100644 src/renderer/src/components/stats/usage-overview-model.test.ts
 create mode 100644 src/renderer/src/components/stats/usage-overview-model.ts
 create mode 100644 tests/e2e/usage-overview.spec.ts

diff --git a/src/main/claude-usage/scanner-scan.test.ts b/src/main/claude-usage/scanner-scan.test.ts
index 18491b73b49..25f4d79acaa 100644
--- a/src/main/claude-usage/scanner-scan.test.ts
+++ b/src/main/claude-usage/scanner-scan.test.ts
@@ -3,6 +3,7 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type * as Os from 'os'
+import type * as FsPromises from 'fs/promises'
 
 const tempRoots: string[] = []
 
@@ -10,11 +11,13 @@ async function makeClaudeProjectsRoot(): Promise<string> {
   const root = await mkdtemp(join(tmpdir(), 'orca-claude-usage-'))
   tempRoots.push(root)
   await mkdir(join(root, '.claude', 'projects', 'project-a'), { recursive: true })
+  await mkdir(join(root, '.claude', 'transcripts'), { recursive: true })
   return root
 }
 
 afterEach(async () => {
   vi.doUnmock('os')
+  vi.doUnmock('fs/promises')
   vi.resetModules()
   await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
 })
@@ -23,8 +26,10 @@ describe('scanClaudeUsageFiles', () => {
   it('scans transcript files from the configured Claude projects directory', async () => {
     const root = await makeClaudeProjectsRoot()
     const projectDir = join(root, '.claude', 'projects', 'project-a')
+    const transcriptsDir = join(root, '.claude', 'transcripts')
     const firstFile = join(projectDir, 'a.jsonl')
     const secondFile = join(projectDir, 'b.jsonl')
+    const transcriptFile = join(transcriptsDir, 'ses_123.jsonl')
 
     await writeFile(
       firstFile,
@@ -63,6 +68,22 @@ describe('scanClaudeUsageFiles', () => {
         }
       })
     )
+    await writeFile(
+      transcriptFile,
+      JSON.stringify({
+        type: 'assistant',
+        timestamp: '2026-04-11T10:00:00.000Z',
+        cwd: '/workspace/repo-a/packages/app',
+        message: {
+          model: 'claude-sonnet-4-6',
+          usage: {
+            input_tokens: 70,
+            output_tokens: 15,
+            cache_read_input_tokens: 20
+          }
+        }
+      })
+    )
 
     vi.resetModules()
     vi.doMock('os', async () => ({
@@ -82,10 +103,119 @@ describe('scanClaudeUsageFiles', () => {
 
     expect(result.processedFiles.map((file) => [file.path, file.lineCount])).toEqual([
       [firstFile, 2],
-      [secondFile, 1]
+      [secondFile, 1],
+      [transcriptFile, 1]
     ])
-    expect(result.sessions.map((session) => session.sessionId)).toEqual(['session-2', 'session-1'])
-    expect(result.dailyAggregates).toHaveLength(2)
+    expect(result.sessions.map((session) => session.sessionId)).toEqual([
+      'ses_123',
+      'session-2',
+      'session-1'
+    ])
+    expect(result.dailyAggregates).toHaveLength(3)
     expect(result.dailyAggregates[0]?.projectLabel).toBe('Repo A')
+    expect(result.dailyAggregates[2]?.projectLabel).toBe('Repo A')
+  })
+
+  it('reuses unchanged transcript projections from the previous scan', async () => {
+    const root = await makeClaudeProjectsRoot()
+    const projectDir = join(root, '.claude', 'projects', 'project-a')
+    const transcriptFile = join(projectDir, 'session-1.jsonl')
+
+    await writeFile(
+      transcriptFile,
+      JSON.stringify({
+        type: 'assistant',
+        sessionId: 'session-1',
+        timestamp: '2026-04-09T10:00:00.000Z',
+        cwd: '/workspace/repo-a',
+        message: {
+          model: 'claude-sonnet-4-6',
+          usage: {
+            input_tokens: 100,
+            output_tokens: 20
+          }
+        }
+      })
+    )
+
+    vi.resetModules()
+    vi.doMock('os', async () => ({
+      ...(await vi.importActual<typeof Os>('os')),
+      homedir: () => root
+    }))
+    const { scanClaudeUsageFiles } = await import('./scanner')
+    const worktrees = [
+      {
+        repoId: 'repo-1',
+        worktreeId: 'worktree-1',
+        path: '/workspace/repo-a',
+        displayName: 'Repo A'
+      }
+    ]
+
+    const first = await scanClaudeUsageFiles(worktrees)
+    const cachedFile = structuredClone(first.processedFiles[0]!)
+    cachedFile.sessions[0]!.totalInputTokens = 999
+    cachedFile.sessions[0]!.locationBreakdown[0]!.inputTokens = 999
+    cachedFile.dailyAggregates[0]!.inputTokens = 999
+
+    const second = await scanClaudeUsageFiles(worktrees, [cachedFile])
+
+    expect(second.processedFiles[0]?.sessions[0]?.totalInputTokens).toBe(999)
+    expect(second.dailyAggregates[0]?.inputTokens).toBe(999)
+  })
+
+  it('canonicalizes repeated cwd paths once per scan file', async () => {
+    const root = await makeClaudeProjectsRoot()
+    const projectDir = join(root, '.claude', 'projects', 'project-a')
+    const transcriptFile = join(projectDir, 'session-1.jsonl')
+    const repeatedCwd = '/workspace/repo-a/packages/app'
+
+    await writeFile(
+      transcriptFile,
+      [1, 2, 3]
+        .map((index) =>
+          JSON.stringify({
+            type: 'assistant',
+            sessionId: 'session-1',
+            timestamp: `2026-04-09T10:0${index}:00.000Z`,
+            cwd: repeatedCwd,
+            message: {
+              model: 'claude-sonnet-4-6',
+              usage: {
+                input_tokens: 100,
+                output_tokens: 20
+              }
+            }
+          })
+        )
+        .join('\n')
+    )
+
+    const realpathCalls: string[] = []
+    vi.resetModules()
+    vi.doMock('os', async () => ({
+      ...(await vi.importActual<typeof Os>('os')),
+      homedir: () => root
+    }))
+    vi.doMock('fs/promises', async () => ({
+      ...(await vi.importActual<typeof FsPromises>('fs/promises')),
+      realpath: vi.fn(async (pathValue: string) => {
+        realpathCalls.push(pathValue)
+        return pathValue
+      })
+    }))
+    const { scanClaudeUsageFiles } = await import('./scanner')
+
+    await scanClaudeUsageFiles([
+      {
+        repoId: 'repo-1',
+        worktreeId: 'worktree-1',
+        path: '/workspace/repo-a',
+        displayName: 'Repo A'
+      }
+    ])
+
+    expect(realpathCalls.filter((pathValue) => pathValue === repeatedCwd)).toHaveLength(1)
   })
 })
diff --git a/src/main/claude-usage/scanner.test.ts b/src/main/claude-usage/scanner.test.ts
index e1d19fb5cdd..1448fe0b566 100644
--- a/src/main/claude-usage/scanner.test.ts
+++ b/src/main/claude-usage/scanner.test.ts
@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'vitest'
-import { aggregateClaudeUsage, attributeClaudeUsageTurns, parseClaudeUsageRecord } from './scanner'
+import {
+  aggregateClaudeUsage,
+  attributeClaudeUsageTurns,
+  parseClaudeUsageFile,
+  parseClaudeUsageRecord
+} from './scanner'
+import { mkdtemp, rm, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { tmpdir } from 'os'
 
 describe('parseClaudeUsageRecord', () => {
   it('extracts token usage from assistant transcript lines', () => {
@@ -34,6 +42,66 @@ describe('parseClaudeUsageRecord', () => {
       cacheWriteTokens: 5
     })
   })
+
+  it('merges duplicate streamed assistant usage by message and request id', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-claude-dedupe-'))
+    const filePath = join(root, 'session.jsonl')
+    try {
+      await writeFile(
+        filePath,
+        [
+          JSON.stringify({
+            type: 'assistant',
+            sessionId: 'session-1',
+            timestamp: '2026-04-09T10:00:00.000Z',
+            requestId: 'req-1',
+            message: {
+              id: 'msg-1',
+              model: 'claude-sonnet-4-6',
+              usage: {
+                input_tokens: 100,
+                output_tokens: 25,
+                cache_read_input_tokens: 10,
+                cache_creation_input_tokens: 5
+              }
+            }
+          }),
+          JSON.stringify({
+            type: 'assistant',
+            sessionId: 'session-1',
+            timestamp: '2026-04-09T10:00:01.000Z',
+            requestId: 'req-1',
+            message: {
+              id: 'msg-1',
+              model: 'claude-sonnet-4-6',
+              usage: {
+                input_tokens: 120,
+                output_tokens: 30,
+                cache_read_input_tokens: 12,
+                cache_creation_input_tokens: 7
+              }
+            }
+          })
+        ].join('\n')
+      )
+
+      await expect(parseClaudeUsageFile(filePath)).resolves.toEqual([
+        {
+          sessionId: 'session-1',
+          timestamp: '2026-04-09T10:00:00.000Z',
+          model: 'claude-sonnet-4-6',
+          cwd: null,
+          gitBranch: null,
+          inputTokens: 120,
+          outputTokens: 30,
+          cacheReadTokens: 12,
+          cacheWriteTokens: 7
+        }
+      ])
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
 })
 
 describe('Claude usage aggregation', () => {
@@ -104,4 +172,36 @@ describe('Claude usage aggregation', () => {
       }
     ])
   })
+
+  it('attributes nested cwd paths to the containing worktree', async () => {
+    const attributed = await attributeClaudeUsageTurns(
+      [
+        {
+          sessionId: 'session-1',
+          timestamp: '2026-04-09T10:00:00.000Z',
+          model: 'claude-sonnet-4-6',
+          cwd: '/workspace/repo-a/packages/app',
+          gitBranch: 'feature/a',
+          inputTokens: 100,
+          outputTokens: 20,
+          cacheReadTokens: 10,
+          cacheWriteTokens: 5
+        }
+      ],
+      new Map([
+        [
+          '/workspace/repo-a',
+          {
+            repoId: 'repo-1',
+            worktreeId: 'repo-1::/workspace/repo-a',
+            path: '/workspace/repo-a',
+            displayName: 'Repo A'
+          }
+        ]
+      ])
+    )
+
+    expect(attributed[0]?.projectKey).toBe('worktree:repo-1::/workspace/repo-a')
+    expect(attributed[0]?.projectLabel).toBe('Repo A')
+  })
 })
diff --git a/src/main/claude-usage/scanner.ts b/src/main/claude-usage/scanner.ts
index 1546983e767..2b250327912 100644
--- a/src/main/claude-usage/scanner.ts
+++ b/src/main/claude-usage/scanner.ts
@@ -10,6 +10,7 @@ import type {
   ClaudeUsageDailyAggregate,
   ClaudeUsageLocationBreakdown,
   ClaudeUsageParsedTurn,
+  ClaudeUsagePersistedFile,
   ClaudeUsageProcessedFile,
   ClaudeUsageSession
 } from './types'
@@ -27,7 +28,11 @@ type ClaudeUsageSourceRecord = {
   timestamp?: string
   cwd?: string
   gitBranch?: string
+  requestId?: string
+  isSidechain?: boolean
+  agentId?: string
   message?: {
+    id?: string
     model?: string
     usage?: {
       input_tokens?: number
@@ -39,8 +44,20 @@ type ClaudeUsageSourceRecord = {
 }
 
 const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects')
+const CLAUDE_TRANSCRIPTS_DIR = join(homedir(), '.claude', 'transcripts')
 const FILE_SCAN_BATCH_SIZE = 4
 
+type ClaudeUsageParsedSourceTurn = ClaudeUsageParsedTurn & {
+  dedupeKey: string | null
+}
+
+type ClaudeUsageWorktreeEntry = [string, ClaudeUsageWorktreeRef]
+
+const sortedWorktreeEntriesByLookup = new WeakMap<
+  Map<string, ClaudeUsageWorktreeRef>,
+  ClaudeUsageWorktreeEntry[]
+>()
+
 function getDefaultProjectLabel(cwd: string | null): string {
   if (!cwd) {
     return 'Unknown location'
@@ -66,6 +83,45 @@ function normalizeComparablePath(pathValue: string): string {
   return process.platform === 'win32' ? normalized.toLowerCase() : normalized
 }
 
+function isContainedPath(parentPath: string, childPath: string): boolean {
+  const parent = normalizeComparablePath(parentPath).replace(/\/+$/, '')
+  const child = normalizeComparablePath(childPath).replace(/\/+$/, '')
+  return child === parent || child.startsWith(`${parent}/`)
+}
+
+function findContainingWorktree(
+  cwd: string,
+  worktreeLookup: Map<string, ClaudeUsageWorktreeRef>
+): ClaudeUsageWorktreeRef | null {
+  const normalizedCwd = normalizeComparablePath(cwd)
+  const exact = worktreeLookup.get(normalizedCwd)
+  if (exact) {
+    return exact
+  }
+
+  for (const [worktreePath, worktree] of getSortedWorktreeEntries(worktreeLookup)) {
+    if (isContainedPath(worktreePath, normalizedCwd)) {
+      return worktree
+    }
+  }
+
+  return null
+}
+
+function getSortedWorktreeEntries(
+  worktreeLookup: Map<string, ClaudeUsageWorktreeRef>
+): ClaudeUsageWorktreeEntry[] {
+  const cached = sortedWorktreeEntriesByLookup.get(worktreeLookup)
+  if (cached) {
+    return cached
+  }
+  const sorted = [...worktreeLookup.entries()].sort(
+    ([leftPath], [rightPath]) => rightPath.length - leftPath.length
+  )
+  sortedWorktreeEntriesByLookup.set(worktreeLookup, sorted)
+  return sorted
+}
+
 async function yieldToEventLoop(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 0))
 }
@@ -89,11 +145,17 @@ async function walkJsonlFiles(dirPath: string): Promise<string[]> {
 }
 
 export async function listClaudeTranscriptFiles(): Promise<string[]> {
-  try {
-    return (await walkJsonlFiles(CLAUDE_PROJECTS_DIR)).sort()
-  } catch {
-    return []
-  }
+  const roots = [CLAUDE_PROJECTS_DIR, CLAUDE_TRANSCRIPTS_DIR]
+  const files = await Promise.all(
+    roots.map(async (root) => {
+      try {
+        return await walkJsonlFiles(root)
+      } catch {
+        return []
+      }
+    })
+  )
+  return [...new Set(files.flat())].sort()
 }
 
 export async function getProcessedFileInfo(filePath: string): Promise<ClaudeUsageProcessedFile> {
@@ -109,11 +171,69 @@ export async function getProcessedFileInfo(filePath: string): Promise<ClaudeUsag
   return {
     path: filePath,
     mtimeMs: fileStat.mtimeMs,
+    size: fileStat.size,
     lineCount
   }
 }
 
-export function parseClaudeUsageRecord(line: string): ClaudeUsageParsedTurn | null {
+async function getProcessedFileStat(
+  filePath: string
+): Promise<Omit<ClaudeUsageProcessedFile, 'lineCount'>> {
+  const fileStat = await stat(filePath)
+  return {
+    path: filePath,
+    mtimeMs: fileStat.mtimeMs,
+    size: fileStat.size
+  }
+}
+
+function stripClaudeSourceMetadata(turn: ClaudeUsageParsedSourceTurn): ClaudeUsageParsedTurn {
+  return {
+    sessionId: turn.sessionId,
+    timestamp: turn.timestamp,
+    model: turn.model,
+    cwd: turn.cwd,
+    gitBranch: turn.gitBranch,
+    inputTokens: turn.inputTokens,
+    outputTokens: turn.outputTokens,
+    cacheReadTokens: turn.cacheReadTokens,
+    cacheWriteTokens: turn.cacheWriteTokens
+  }
+}
+
+function dedupeClaudeUsageTurns(turns: ClaudeUsageParsedSourceTurn[]): ClaudeUsageParsedTurn[] {
+  const dedupeIndexByKey = new Map<string, number>()
+  const deduped: ClaudeUsageParsedTurn[] = []
+
+  for (const turn of turns) {
+    if (turn.dedupeKey) {
+      const existingIndex = dedupeIndexByKey.get(turn.dedupeKey)
+      if (existingIndex !== undefined) {
+        const existing = deduped[existingIndex]
+        // Why: Claude Code streams repeated assistant rows with the same
+        // message/request IDs; later rows can contain more complete usage.
+        existing.inputTokens = Math.max(existing.inputTokens, turn.inputTokens)
+        existing.outputTokens = Math.max(existing.outputTokens, turn.outputTokens)
+        existing.cacheReadTokens = Math.max(existing.cacheReadTokens, turn.cacheReadTokens)
+        existing.cacheWriteTokens = Math.max(existing.cacheWriteTokens, turn.cacheWriteTokens)
+        continue
+      }
+    }
+
+    const stripped = stripClaudeSourceMetadata(turn)
+    deduped.push(stripped)
+    if (turn.dedupeKey) {
+      dedupeIndexByKey.set(turn.dedupeKey, deduped.length - 1)
+    }
+  }
+
+  return deduped
+}
+
+function parseClaudeUsageSourceRecord(
+  line: string,
+  fallbackSessionId: string | null = null
+): ClaudeUsageParsedSourceTurn | null {
   let parsed: ClaudeUsageSourceRecord
   try {
     parsed = JSON.parse(line) as ClaudeUsageSourceRecord
@@ -124,7 +244,8 @@ export function parseClaudeUsageRecord(line: string): ClaudeUsageParsedTurn | nu
   if (parsed.type !== 'assistant') {
     return null
   }
-  if (!parsed.sessionId || !parsed.timestamp) {
+  const sessionId = parsed.sessionId ?? fallbackSessionId
+  if (!sessionId || !parsed.timestamp) {
     return null
   }
 
@@ -139,11 +260,13 @@ export function parseClaudeUsageRecord(line: string): ClaudeUsageParsedTurn | nu
   }
 
   return {
-    sessionId: parsed.sessionId,
+    sessionId,
     timestamp: parsed.timestamp,
     model: parsed.message?.model ?? null,
     cwd: parsed.cwd ?? null,
     gitBranch: parsed.gitBranch ?? null,
+    dedupeKey:
+      parsed.message?.id && parsed.requestId ? `${parsed.message.id}:${parsed.requestId}` : null,
     inputTokens,
     outputTokens,
     cacheReadTokens,
@@ -151,21 +274,27 @@ export function parseClaudeUsageRecord(line: string): ClaudeUsageParsedTurn | nu
   }
 }
 
+export function parseClaudeUsageRecord(line: string): ClaudeUsageParsedTurn | null {
+  const parsed = parseClaudeUsageSourceRecord(line)
+  return parsed ? stripClaudeSourceMetadata(parsed) : null
+}
+
 export async function parseClaudeUsageFile(filePath: string): Promise<ClaudeUsageParsedTurn[]> {
-  const turns: ClaudeUsageParsedTurn[] = []
+  const turns: ClaudeUsageParsedSourceTurn[] = []
+  const fallbackSessionId = basename(filePath, '.jsonl')
   const lines = createInterface({
     input: createReadStream(filePath, { encoding: 'utf-8' }),
     crlfDelay: Infinity
   })
 
   for await (const line of lines) {
-    const parsed = parseClaudeUsageRecord(line)
+    const parsed = parseClaudeUsageSourceRecord(line, fallbackSessionId)
     if (parsed) {
       turns.push(parsed)
     }
   }
 
-  return turns
+  return dedupeClaudeUsageTurns(turns)
 }
 
 async function readClaudeUsageScanFile(filePath: string): Promise<{
@@ -174,7 +303,8 @@ async function readClaudeUsageScanFile(filePath: string): Promise<{
 }> {
   const fileStat = await stat(filePath)
   let lineCount = 0
-  const turns: ClaudeUsageParsedTurn[] = []
+  const turns: ClaudeUsageParsedSourceTurn[] = []
+  const fallbackSessionId = basename(filePath, '.jsonl')
   const lines = createInterface({
     input: createReadStream(filePath, { encoding: 'utf-8' }),
     crlfDelay: Infinity
@@ -182,7 +312,7 @@ async function readClaudeUsageScanFile(filePath: string): Promise<{
 
   for await (const line of lines) {
     lineCount++
-    const parsed = parseClaudeUsageRecord(line)
+    const parsed = parseClaudeUsageSourceRecord(line, fallbackSessionId)
     if (parsed) {
       turns.push(parsed)
     }
@@ -192,9 +322,10 @@ async function readClaudeUsageScanFile(filePath: string): Promise<{
     processedFile: {
       path: filePath,
       mtimeMs: fileStat.mtimeMs,
+      size: fileStat.size,
       lineCount
     },
-    turns
+    turns: dedupeClaudeUsageTurns(turns)
   }
 }
 
@@ -224,6 +355,7 @@ export async function attributeClaudeUsageTurns(
   worktreeLookup: Map<string, ClaudeUsageWorktreeRef>
 ): Promise<ClaudeUsageAttributedTurn[]> {
   const attributed: ClaudeUsageAttributedTurn[] = []
+  const canonicalCwdByPath = new Map<string, string>()
 
   for (const turn of turns) {
     const day = localDayFromTimestamp(turn.timestamp)
@@ -237,7 +369,14 @@ export async function attributeClaudeUsageTurns(
     let projectLabel = getDefaultProjectLabel(turn.cwd)
 
     if (turn.cwd) {
-      const worktree = worktreeLookup.get(await canonicalizePath(turn.cwd))
+      let canonicalCwd = canonicalCwdByPath.get(turn.cwd)
+      if (canonicalCwd === undefined) {
+        // Why: Claude transcripts repeat the same cwd for many consecutive
+        // turns. Cache realpath work so attribution scales with unique paths.
+        canonicalCwd = await canonicalizePath(turn.cwd)
+        canonicalCwdByPath.set(turn.cwd, canonicalCwd)
+      }
+      const worktree = findContainingWorktree(canonicalCwd, worktreeLookup)
       if (worktree) {
         repoId = worktree.repoId
         worktreeId = worktree.worktreeId
@@ -261,6 +400,90 @@ export async function attributeClaudeUsageTurns(
   return attributed
 }
 
+function mergeClaudeSessions(
+  target: Map<string, ClaudeUsageSession>,
+  sessions: ClaudeUsageSession[]
+): void {
+  for (const session of sessions) {
+    const existing = target.get(session.sessionId)
+    if (!existing) {
+      target.set(session.sessionId, structuredClone(session))
+      continue
+    }
+
+    if (session.firstTimestamp < existing.firstTimestamp) {
+      existing.firstTimestamp = session.firstTimestamp
+    }
+    if (session.lastTimestamp > existing.lastTimestamp) {
+      existing.lastTimestamp = session.lastTimestamp
+      existing.lastCwd = session.lastCwd
+      existing.lastGitBranch = session.lastGitBranch
+    }
+    existing.model = session.model ?? existing.model
+    existing.turnCount += session.turnCount
+    existing.totalInputTokens += session.totalInputTokens
+    existing.totalOutputTokens += session.totalOutputTokens
+    existing.totalCacheReadTokens += session.totalCacheReadTokens
+    existing.totalCacheWriteTokens += session.totalCacheWriteTokens
+
+    for (const location of session.locationBreakdown) {
+      const existingLocation =
+        existing.locationBreakdown.find((entry) => entry.locationKey === location.locationKey) ??
+        null
+      if (existingLocation) {
+        existingLocation.turnCount += location.turnCount
+        existingLocation.inputTokens += location.inputTokens
+        existingLocation.outputTokens += location.outputTokens
+        existingLocation.cacheReadTokens += location.cacheReadTokens
+        existingLocation.cacheWriteTokens += location.cacheWriteTokens
+      } else {
+        existing.locationBreakdown.push({ ...location })
+      }
+    }
+  }
+}
+
+function mergeClaudeDailyAggregates(
+  target: Map<string, ClaudeUsageDailyAggregate>,
+  dailyAggregates: ClaudeUsageDailyAggregate[]
+): void {
+  for (const aggregate of dailyAggregates) {
+    const key = [aggregate.day, aggregate.model ?? 'unknown', aggregate.projectKey].join('::')
+    const existing = target.get(key)
+    if (!existing) {
+      target.set(key, { ...aggregate })
+      continue
+    }
+    existing.turnCount += aggregate.turnCount
+    existing.zeroCacheReadTurnCount += aggregate.zeroCacheReadTurnCount
+    existing.inputTokens += aggregate.inputTokens
+    existing.outputTokens += aggregate.outputTokens
+    existing.cacheReadTokens += aggregate.cacheReadTokens
+    existing.cacheWriteTokens += aggregate.cacheWriteTokens
+  }
+}
+
+function finalizeClaudeSessions(
+  sessionsById: Map<string, ClaudeUsageSession>
+): ClaudeUsageSession[] {
+  for (const session of sessionsById.values()) {
+    session.locationBreakdown.sort((left, right) => {
+      const leftTotal = left.inputTokens + left.outputTokens
+      const rightTotal = right.inputTokens + right.outputTokens
+      return rightTotal - leftTotal
+    })
+    const primaryLocation = session.locationBreakdown[0] ?? null
+    if (primaryLocation) {
+      session.primaryRepoId = primaryLocation.repoId
+      session.primaryWorktreeId = primaryLocation.worktreeId
+    }
+  }
+
+  return [...sessionsById.values()].sort((left, right) =>
+    right.lastTimestamp.localeCompare(left.lastTimestamp)
+  )
+}
+
 export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
   sessions: ClaudeUsageSession[]
   dailyAggregates: ClaudeUsageDailyAggregate[]
@@ -356,23 +579,8 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
     }
   }
 
-  for (const session of sessionsById.values()) {
-    session.locationBreakdown.sort((left, right) => {
-      const leftTotal = left.inputTokens + left.outputTokens
-      const rightTotal = right.inputTokens + right.outputTokens
-      return rightTotal - leftTotal
-    })
-    const primaryLocation = session.locationBreakdown[0] ?? null
-    if (primaryLocation) {
-      session.primaryRepoId = primaryLocation.repoId
-      session.primaryWorktreeId = primaryLocation.worktreeId
-    }
-  }
-
   return {
-    sessions: [...sessionsById.values()].sort((left, right) =>
-      right.lastTimestamp.localeCompare(left.lastTimestamp)
-    ),
+    sessions: finalizeClaudeSessions(sessionsById),
     dailyAggregates: [...dailyByKey.values()].sort((left, right) =>
       left.day === right.day
         ? left.projectLabel.localeCompare(right.projectLabel)
@@ -381,22 +589,55 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
   }
 }
 
-export async function scanClaudeUsageFiles(worktrees: ClaudeUsageWorktreeRef[]): Promise<{
-  processedFiles: ClaudeUsageProcessedFile[]
+async function parseClaudeUsagePersistedFile(
+  filePath: string,
+  worktreeLookup: Map<string, ClaudeUsageWorktreeRef>
+): Promise<ClaudeUsagePersistedFile> {
+  const { processedFile, turns } = await readClaudeUsageScanFile(filePath)
+  const attributed = await attributeClaudeUsageTurns(turns, worktreeLookup)
+  return {
+    ...processedFile,
+    ...aggregateClaudeUsage(attributed)
+  }
+}
+
+export async function scanClaudeUsageFiles(
+  worktrees: ClaudeUsageWorktreeRef[],
+  previousProcessedFiles: ClaudeUsagePersistedFile[] = []
+): Promise<{
+  processedFiles: ClaudeUsagePersistedFile[]
   sessions: ClaudeUsageSession[]
   dailyAggregates: ClaudeUsageDailyAggregate[]
 }> {
   const files = await listClaudeTranscriptFiles()
-  const processedFiles: ClaudeUsageProcessedFile[] = []
-  const allTurns: ClaudeUsageParsedTurn[] = []
+  const previousByPath = new Map(previousProcessedFiles.map((file) => [file.path, file]))
+  const processedFiles: ClaudeUsagePersistedFile[] = []
   const worktreeLookup = await buildWorktreeLookup(worktrees)
+  const sessionsById = new Map<string, ClaudeUsageSession>()
+  const dailyByKey = new Map<string, ClaudeUsageDailyAggregate>()
 
   for (let index = 0; index < files.length; index += FILE_SCAN_BATCH_SIZE) {
     const batch = files.slice(index, index + FILE_SCAN_BATCH_SIZE)
-    const results = await Promise.all(batch.map((filePath) => readClaudeUsageScanFile(filePath)))
-    for (const result of results) {
-      processedFiles.push(result.processedFile)
-      allTurns.push(...result.turns)
+    const results = await Promise.all(
+      batch.map(async (filePath) => {
+        const fileInfo = await getProcessedFileStat(filePath)
+        const previous = previousByPath.get(filePath)
+        // Why: Claude histories can be gigabytes. Unchanged files should pay
+        // only stat cost on refresh while preserving exactly the old projection.
+        const canReuse =
+          previous &&
+          previous.mtimeMs === fileInfo.mtimeMs &&
+          previous.size === fileInfo.size &&
+          Array.isArray(previous.sessions) &&
+          Array.isArray(previous.dailyAggregates)
+
+        return canReuse ? previous : parseClaudeUsagePersistedFile(filePath, worktreeLookup)
+      })
+    )
+    for (const processed of results) {
+      processedFiles.push(processed)
+      mergeClaudeSessions(sessionsById, processed.sessions)
+      mergeClaudeDailyAggregates(dailyByKey, processed.dailyAggregates)
     }
     // Why: transcript scans run in Electron's main process. Small parallel
     // batches cut independent file I/O without letting Settings stay blocked.
@@ -405,10 +646,14 @@ export async function scanClaudeUsageFiles(worktrees: ClaudeUsageWorktreeRef[]):
     }
   }
 
-  const attributed = await attributeClaudeUsageTurns(allTurns, worktreeLookup)
   return {
     processedFiles,
-    ...aggregateClaudeUsage(attributed)
+    sessions: finalizeClaudeSessions(sessionsById),
+    dailyAggregates: [...dailyByKey.values()].sort((left, right) =>
+      left.day === right.day
+        ? left.projectLabel.localeCompare(right.projectLabel)
+        : left.day.localeCompare(right.day)
+    )
   }
 }
 
@@ -416,6 +661,10 @@ export function getClaudeProjectsDirectory(): string {
   return CLAUDE_PROJECTS_DIR
 }
 
+export function getClaudeTranscriptsDirectory(): string {
+  return CLAUDE_TRANSCRIPTS_DIR
+}
+
 export function createWorktreeRefs(
   repos: Repo[],
   worktreesByRepo: Map<string, { path: string; worktreeId: string; displayName: string }[]>
diff --git a/src/main/claude-usage/store.test.ts b/src/main/claude-usage/store.test.ts
index e3e1ff416a2..2ae6a09990c 100644
--- a/src/main/claude-usage/store.test.ts
+++ b/src/main/claude-usage/store.test.ts
@@ -17,6 +17,7 @@ function createStoreWithState(state: Partial<ClaudeUsagePersistedState>): Claude
 
   ;(store as unknown as { state: ClaudeUsagePersistedState }).state = {
     schemaVersion: 1,
+    worktreeFingerprint: null,
     processedFiles: [],
     sessions: [],
     dailyAggregates: [],
@@ -231,4 +232,29 @@ describe('ClaudeUsageStore', () => {
 
     expect(summary.estimatedCostUsd).toBeCloseTo(110.25)
   })
+
+  it('prices Sonnet long-context usage with threshold rates', async () => {
+    const store = createStoreWithState({
+      dailyAggregates: [
+        {
+          day: '2026-04-09',
+          model: 'claude-sonnet-4-6',
+          projectKey: 'worktree:repo-1::/workspace/repo-a',
+          projectLabel: 'Repo A',
+          repoId: 'repo-1',
+          worktreeId: 'repo-1::/workspace/repo-a',
+          turnCount: 1,
+          zeroCacheReadTurnCount: 0,
+          inputTokens: 300_000,
+          outputTokens: 300_000,
+          cacheReadTokens: 300_000,
+          cacheWriteTokens: 300_000
+        }
+      ]
+    })
+
+    const summary = await store.getSummary('orca', '30d')
+
+    expect(summary.estimatedCostUsd).toBeCloseTo(8.07)
+  })
 })
diff --git a/src/main/claude-usage/store.ts b/src/main/claude-usage/store.ts
index 476782abf44..dbc2add004f 100644
--- a/src/main/claude-usage/store.ts
+++ b/src/main/claude-usage/store.ts
@@ -13,38 +13,87 @@ import type {
   ClaudeUsageSummary
 } from '../../shared/claude-usage-types'
 import type { Store } from '../persistence'
-import { loadKnownUsageWorktreesByRepo } from '../usage-worktree-metadata'
+import { loadKnownUsageWorktreesByRepo, type UsageWorktreeRef } from '../usage-worktree-metadata'
 import type { ClaudeUsagePersistedState } from './types'
 import { createWorktreeRefs, getSessionProjectLabel, scanClaudeUsageFiles } from './scanner'
 
-const SCHEMA_VERSION = 1
+const SCHEMA_VERSION = 3
 const STALE_MS = 5 * 60_000
 
 // Why: capture the path after configureDevUserDataPath() but before app.setName()
 // mutates Electron's derived userData location, matching the persistence/store pattern.
 let _claudeUsageFile: string | null = null
 
-const MODEL_PRICING: Record<
-  string,
-  { input: number; output: number; cacheRead: number; cacheWrite: number }
-> = {
+type ClaudeModelPricing = {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  thresholdTokens?: number
+  inputAboveThreshold?: number
+  outputAboveThreshold?: number
+  cacheReadAboveThreshold?: number
+  cacheWriteAboveThreshold?: number
+}
+
+const LONG_CONTEXT_THRESHOLD_TOKENS = 200_000
+const SONNET_LONG_CONTEXT_PRICING = {
+  thresholdTokens: LONG_CONTEXT_THRESHOLD_TOKENS,
+  inputAboveThreshold: 6,
+  outputAboveThreshold: 22.5,
+  cacheReadAboveThreshold: 0.6,
+  cacheWriteAboveThreshold: 7.5
+} satisfies Partial<ClaudeModelPricing>
+
+const MODEL_PRICING: Record<string, ClaudeModelPricing> = {
   'claude-opus-4-7': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
   'claude-opus-4-6': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
   'claude-opus-4-5': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
   'claude-opus-4-1': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
   'claude-opus-4': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-  'claude-sonnet-4-6': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  'claude-sonnet-4-5': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  'claude-sonnet-4': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  'claude-sonnet-4-6': {
+    input: 3,
+    output: 15,
+    cacheRead: 0.3,
+    cacheWrite: 3.75,
+    ...SONNET_LONG_CONTEXT_PRICING
+  },
+  'claude-sonnet-4-5': {
+    input: 3,
+    output: 15,
+    cacheRead: 0.3,
+    cacheWrite: 3.75,
+    ...SONNET_LONG_CONTEXT_PRICING
+  },
+  'claude-sonnet-4': {
+    input: 3,
+    output: 15,
+    cacheRead: 0.3,
+    cacheWrite: 3.75,
+    ...SONNET_LONG_CONTEXT_PRICING
+  },
   'claude-sonnet-3-7': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  'claude-sonnet-3-5': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
   'claude-haiku-4-5': { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
   'claude-haiku-3-5': { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
   'claude-haiku-3': { input: 0.25, output: 1.25, cacheRead: 0.03, cacheWrite: 0.3 }
 }
 
+const MODEL_ALIASES: Record<string, string> = {
+  model_placeholder_m26: 'claude-opus-4-6',
+  model_placeholder_m35: 'claude-sonnet-4-6',
+  'claude-opus-4.6': 'claude-opus-4-6',
+  'claude-sonnet-4.6': 'claude-sonnet-4-6',
+  'claude-opus-4.6-thinking': 'claude-opus-4-6',
+  'claude-sonnet-4.6-thinking': 'claude-sonnet-4-6',
+  'claude-opus-4-6-thinking': 'claude-opus-4-6',
+  'claude-sonnet-4-6-thinking': 'claude-sonnet-4-6'
+}
+
 function getDefaultState(): ClaudeUsagePersistedState {
   return {
     schemaVersion: SCHEMA_VERSION,
+    worktreeFingerprint: null,
     processedFiles: [],
     sessions: [],
     dailyAggregates: [],
@@ -72,7 +121,14 @@ function normalizeModelForPricing(model: string | null): string | null {
   if (!model) {
     return null
   }
-  const lower = model.toLowerCase()
+  const lower = model
+    .toLowerCase()
+    .trim()
+    .replace(/^anthropic[/:]/, '')
+  const alias = MODEL_ALIASES[lower]
+  if (alias) {
+    return alias
+  }
   if (lower.includes('opus-4-7')) {
     return 'claude-opus-4-7'
   }
@@ -103,8 +159,13 @@ function normalizeModelForPricing(model: string | null): string | null {
   // Why: legacy version-first IDs like `claude-3-5-sonnet-20241022` are still
   // present in historical Claude Code/SDK logs read off disk. Match them so
   // their cost is not silently dropped from the breakdown.
-  if (lower.includes('3-5-sonnet') || lower.includes('3.5-sonnet')) {
-    return 'claude-sonnet-3-7'
+  if (
+    lower.includes('sonnet-3-5') ||
+    lower.includes('sonnet-3.5') ||
+    lower.includes('3-5-sonnet') ||
+    lower.includes('3.5-sonnet')
+  ) {
+    return 'claude-sonnet-3-5'
   }
   if (lower.includes('haiku-4-5')) {
     return 'claude-haiku-4-5'
@@ -121,6 +182,20 @@ function normalizeModelForPricing(model: string | null): string | null {
   return null
 }
 
+function calculateTieredCost(
+  tokens: number,
+  basePrice: number,
+  abovePrice?: number,
+  threshold?: number
+): number {
+  if (threshold === undefined || abovePrice === undefined) {
+    return tokens * basePrice
+  }
+  const belowTokens = Math.min(tokens, threshold)
+  const aboveTokens = Math.max(tokens - threshold, 0)
+  return belowTokens * basePrice + aboveTokens * abovePrice
+}
+
 function estimateCostUsd(
   model: string | null,
   inputTokens: number,
@@ -134,10 +209,30 @@ function estimateCostUsd(
   }
   const pricing = MODEL_PRICING[normalized]
   return (
-    (inputTokens * pricing.input +
-      outputTokens * pricing.output +
-      cacheReadTokens * pricing.cacheRead +
-      cacheWriteTokens * pricing.cacheWrite) /
+    (calculateTieredCost(
+      inputTokens,
+      pricing.input,
+      pricing.inputAboveThreshold,
+      pricing.thresholdTokens
+    ) +
+      calculateTieredCost(
+        outputTokens,
+        pricing.output,
+        pricing.outputAboveThreshold,
+        pricing.thresholdTokens
+      ) +
+      calculateTieredCost(
+        cacheReadTokens,
+        pricing.cacheRead,
+        pricing.cacheReadAboveThreshold,
+        pricing.thresholdTokens
+      ) +
+      calculateTieredCost(
+        cacheWriteTokens,
+        pricing.cacheWrite,
+        pricing.cacheWriteAboveThreshold,
+        pricing.thresholdTokens
+      )) /
     1_000_000
   )
 }
@@ -167,6 +262,22 @@ function getLocalDay(timestamp: string): string | null {
   return `${year}-${month}-${day}`
 }
 
+function getWorktreeFingerprint(worktreesByRepo: Map<string, UsageWorktreeRef[]>): string {
+  const rows = [...worktreesByRepo.entries()]
+    .flatMap(([repoId, worktrees]) =>
+      worktrees.map((worktree) =>
+        JSON.stringify({
+          repoId,
+          worktreeId: worktree.worktreeId,
+          path: worktree.path,
+          displayName: worktree.displayName
+        })
+      )
+    )
+    .sort()
+  return JSON.stringify(rows)
+}
+
 export class ClaudeUsageStore {
   private state: ClaudeUsagePersistedState
   private readonly store: Store
@@ -184,6 +295,11 @@ export class ClaudeUsageStore {
         return getDefaultState()
       }
       const parsed = JSON.parse(readFileSync(usageFile, 'utf-8')) as ClaudeUsagePersistedState
+      if (parsed.schemaVersion !== SCHEMA_VERSION) {
+        // Why: scanner semantics affect persisted totals, so old Claude caches
+        // must be rebuilt after parser/source changes instead of reused briefly.
+        return getDefaultState()
+      }
       return {
         ...getDefaultState(),
         ...parsed,
@@ -233,9 +349,10 @@ export class ClaudeUsageStore {
     if (!this.state.scanState.enabled) {
       return this.getScanState()
     }
+    const currentWorktreeFingerprint = await this.getCurrentWorktreeFingerprint()
     if (!force && this.state.scanState.lastScanCompletedAt) {
       const ageMs = Date.now() - this.state.scanState.lastScanCompletedAt
-      if (ageMs < STALE_MS) {
+      if (ageMs < STALE_MS && this.state.worktreeFingerprint === currentWorktreeFingerprint) {
         return this.getScanState()
       }
     }
@@ -257,10 +374,15 @@ export class ClaudeUsageStore {
       try {
         const repos = this.store.getRepos()
         const worktreesByRepo = loadKnownUsageWorktreesByRepo(this.store, repos)
-        const result = await scanClaudeUsageFiles(createWorktreeRefs(repos, worktreesByRepo))
+        const worktreeFingerprint = getWorktreeFingerprint(worktreesByRepo)
+        const result = await scanClaudeUsageFiles(
+          createWorktreeRefs(repos, worktreesByRepo),
+          this.state.worktreeFingerprint === worktreeFingerprint ? this.state.processedFiles : []
+        )
         this.state.processedFiles = result.processedFiles
         this.state.sessions = result.sessions
         this.state.dailyAggregates = result.dailyAggregates
+        this.state.worktreeFingerprint = worktreeFingerprint
         this.state.scanState.lastScanCompletedAt = Date.now()
         this.state.scanState.lastScanError = null
         this.writeToDisk()
@@ -532,4 +654,10 @@ export class ClaudeUsageStore {
       return true
     })
   }
+
+  private async getCurrentWorktreeFingerprint(): Promise<string> {
+    const repos = this.store.getRepos()
+    const worktreesByRepo = loadKnownUsageWorktreesByRepo(this.store, repos)
+    return getWorktreeFingerprint(worktreesByRepo)
+  }
 }
diff --git a/src/main/claude-usage/types.ts b/src/main/claude-usage/types.ts
index af16c10f444..8760621d754 100644
--- a/src/main/claude-usage/types.ts
+++ b/src/main/claude-usage/types.ts
@@ -1,6 +1,7 @@
 export type ClaudeUsageProcessedFile = {
   path: string
   mtimeMs: number
+  size: number
   lineCount: number
 }
 
@@ -50,7 +51,8 @@ export type ClaudeUsageDailyAggregate = {
 
 export type ClaudeUsagePersistedState = {
   schemaVersion: number
-  processedFiles: ClaudeUsageProcessedFile[]
+  worktreeFingerprint: string | null
+  processedFiles: ClaudeUsagePersistedFile[]
   sessions: ClaudeUsageSession[]
   dailyAggregates: ClaudeUsageDailyAggregate[]
   scanState: {
@@ -61,6 +63,11 @@ export type ClaudeUsagePersistedState = {
   }
 }
 
+export type ClaudeUsagePersistedFile = ClaudeUsageProcessedFile & {
+  sessions: ClaudeUsageSession[]
+  dailyAggregates: ClaudeUsageDailyAggregate[]
+}
+
 export type ClaudeUsageParsedTurn = {
   sessionId: string
   timestamp: string
diff --git a/src/main/codex-usage/scanner.test.ts b/src/main/codex-usage/scanner.test.ts
index 7211c78ea20..d7251b684ea 100644
--- a/src/main/codex-usage/scanner.test.ts
+++ b/src/main/codex-usage/scanner.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { attributeCodexUsageEvent, parseCodexUsageRecord } from './scanner'
 
 describe('parseCodexUsageRecord', () => {
-  it('uses cumulative totals to avoid double-counting repeated token snapshots', () => {
+  it('uses token totals only as a duplicate baseline', () => {
     const context = {
       sessionId: 'session-1',
       sessionCwd: null,
@@ -100,7 +100,7 @@ describe('parseCodexUsageRecord', () => {
     expect(duplicate).toBeNull()
   })
 
-  it('falls back to inferred gpt-5 pricing when model metadata is missing', () => {
+  it('preserves unknown model metadata instead of assigning fallback pricing', () => {
     const context = {
       sessionId: 'session-1',
       sessionCwd: '/workspace/repo',
@@ -129,9 +129,54 @@ describe('parseCodexUsageRecord', () => {
       context
     )
 
-    expect(parsed?.model).toBe('gpt-5')
+    expect(parsed?.model).toBeNull()
     expect(parsed?.hasInferredPricing).toBe(true)
   })
+
+  it('uses last token usage for the first resumed-session event', () => {
+    const context = {
+      sessionId: 'session-1',
+      sessionCwd: '/workspace/repo',
+      currentCwd: '/workspace/repo',
+      currentModel: 'gpt-5.5',
+      previousTotals: null
+    }
+
+    const parsed = parseCodexUsageRecord(
+      JSON.stringify({
+        timestamp: '2026-04-09T10:00:00.000Z',
+        type: 'event_msg',
+        payload: {
+          type: 'token_count',
+          info: {
+            total_token_usage: {
+              input_tokens: 50_000,
+              cached_input_tokens: 40_000,
+              output_tokens: 5_000,
+              reasoning_output_tokens: 1_000,
+              total_tokens: 55_000
+            },
+            last_token_usage: {
+              input_tokens: 2_000,
+              cached_input_tokens: 1_500,
+              output_tokens: 500,
+              reasoning_output_tokens: 100,
+              total_tokens: 2_500
+            }
+          }
+        }
+      }),
+      context
+    )
+
+    expect(parsed).toMatchObject({
+      inputTokens: 2_000,
+      cachedInputTokens: 1_500,
+      outputTokens: 500,
+      reasoningOutputTokens: 100,
+      totalTokens: 2_500
+    })
+  })
 })
 
 describe('attributeCodexUsageEvent', () => {
diff --git a/src/main/codex-usage/scanner.ts b/src/main/codex-usage/scanner.ts
index 8cfc89ee81c..130336204db 100644
--- a/src/main/codex-usage/scanner.ts
+++ b/src/main/codex-usage/scanner.ts
@@ -47,8 +47,11 @@ type CodexUsageParseContext = {
   previousTotals: CodexUsageRawUsage | null
 }
 
+type CodexUsageDeltaResolution =
+  | { kind: 'event'; delta: CodexUsageRawUsage; nextTotals: CodexUsageRawUsage | null }
+  | { kind: 'baseline'; nextTotals: CodexUsageRawUsage }
+
 const DEFAULT_CODEX_SESSIONS_DIR = join(homedir(), '.codex', 'sessions')
-const LEGACY_FALLBACK_MODEL = 'gpt-5'
 const YIELD_EVERY_FILES = 10
 
 function ensureNumber(value: unknown): number {
@@ -171,6 +174,107 @@ function subtractRawUsage(
   }
 }
 
+function addRawUsage(left: CodexUsageRawUsage, right: CodexUsageRawUsage): CodexUsageRawUsage {
+  return {
+    inputTokens: left.inputTokens + right.inputTokens,
+    cachedInputTokens: left.cachedInputTokens + right.cachedInputTokens,
+    outputTokens: left.outputTokens + right.outputTokens,
+    reasoningOutputTokens: left.reasoningOutputTokens + right.reasoningOutputTokens,
+    totalTokens: left.totalTokens + right.totalTokens
+  }
+}
+
+function rawUsageEquals(left: CodexUsageRawUsage, right: CodexUsageRawUsage): boolean {
+  return (
+    left.inputTokens === right.inputTokens &&
+    left.cachedInputTokens === right.cachedInputTokens &&
+    left.outputTokens === right.outputTokens &&
+    left.reasoningOutputTokens === right.reasoningOutputTokens
+  )
+}
+
+function rawUsageIsMonotonic(current: CodexUsageRawUsage, previous: CodexUsageRawUsage): boolean {
+  return (
+    current.inputTokens >= previous.inputTokens &&
+    current.cachedInputTokens >= previous.cachedInputTokens &&
+    current.outputTokens >= previous.outputTokens &&
+    current.reasoningOutputTokens >= previous.reasoningOutputTokens
+  )
+}
+
+function rawUsageMagnitude(usage: CodexUsageRawUsage): number {
+  return (
+    usage.inputTokens + usage.cachedInputTokens + usage.outputTokens + usage.reasoningOutputTokens
+  )
+}
+
+function looksLikeStaleRegression(
+  current: CodexUsageRawUsage,
+  previous: CodexUsageRawUsage,
+  last: CodexUsageRawUsage
+): boolean {
+  const previousTotal = rawUsageMagnitude(previous)
+  const currentTotal = rawUsageMagnitude(current)
+  const lastTotal = rawUsageMagnitude(last)
+  if (previousTotal <= 0 || currentTotal <= 0 || lastTotal <= 0) {
+    return false
+  }
+  return currentTotal * 100 >= previousTotal * 98 || currentTotal + lastTotal * 2 >= previousTotal
+}
+
+function resolveCodexUsageDelta(
+  totalUsage: CodexUsageRawUsage | null,
+  lastUsage: CodexUsageRawUsage | null,
+  previousTotals: CodexUsageRawUsage | null
+): CodexUsageDeltaResolution | null {
+  if (totalUsage && lastUsage && previousTotals) {
+    if (rawUsageEquals(totalUsage, previousTotals)) {
+      return null
+    }
+    if (
+      !rawUsageIsMonotonic(totalUsage, previousTotals) &&
+      looksLikeStaleRegression(totalUsage, previousTotals, lastUsage)
+    ) {
+      return null
+    }
+    // Why: Codex totals are mutable snapshots after compaction/resume. The
+    // last_token_usage payload is the billable increment; totals are the baseline.
+    return { kind: 'event', delta: lastUsage, nextTotals: totalUsage }
+  }
+
+  if (totalUsage && lastUsage) {
+    return { kind: 'event', delta: lastUsage, nextTotals: totalUsage }
+  }
+
+  if (totalUsage && previousTotals) {
+    if (rawUsageEquals(totalUsage, previousTotals)) {
+      return null
+    }
+    if (!rawUsageIsMonotonic(totalUsage, previousTotals)) {
+      return { kind: 'baseline', nextTotals: totalUsage }
+    }
+    return {
+      kind: 'event',
+      delta: subtractRawUsage(totalUsage, previousTotals),
+      nextTotals: totalUsage
+    }
+  }
+
+  if (totalUsage) {
+    return { kind: 'event', delta: totalUsage, nextTotals: totalUsage }
+  }
+
+  if (lastUsage && previousTotals) {
+    return { kind: 'event', delta: lastUsage, nextTotals: addRawUsage(previousTotals, lastUsage) }
+  }
+
+  if (lastUsage) {
+    return { kind: 'event', delta: lastUsage, nextTotals: null }
+  }
+
+  return null
+}
+
 function extractString(value: unknown): string | null {
   if (typeof value !== 'string') {
     return null
@@ -688,17 +792,21 @@ export function parseCodexUsageRecord(
   const record = info as Record<string, unknown>
   const totalUsage = normalizeRawUsage(record.total_token_usage)
   const lastUsage = normalizeRawUsage(record.last_token_usage)
-  let delta = totalUsage ? subtractRawUsage(totalUsage, context.previousTotals) : lastUsage
-  if (totalUsage) {
-    context.previousTotals = totalUsage
+  const resolvedUsage = resolveCodexUsageDelta(totalUsage, lastUsage, context.previousTotals)
+  if (!resolvedUsage) {
+    return null
   }
-  if (!delta) {
+  if (resolvedUsage.kind === 'baseline') {
+    context.previousTotals = resolvedUsage.nextTotals
     return null
   }
 
-  delta = {
-    ...delta,
-    cachedInputTokens: Math.min(delta.cachedInputTokens, delta.inputTokens)
+  let delta = {
+    ...resolvedUsage.delta,
+    cachedInputTokens: Math.min(
+      resolvedUsage.delta.cachedInputTokens,
+      resolvedUsage.delta.inputTokens
+    )
   }
 
   if (
@@ -711,15 +819,16 @@ export function parseCodexUsageRecord(
     return null
   }
 
+  context.previousTotals = resolvedUsage.nextTotals
+
   const resolvedModel = extractModel(parsed.payload) ?? context.currentModel
-  const model = resolvedModel ?? LEGACY_FALLBACK_MODEL
   const hasInferredPricing = resolvedModel === null
 
   return {
     sessionId: context.sessionId,
     timestamp: parsed.timestamp,
     cwd: context.currentCwd ?? context.sessionCwd,
-    model,
+    model: resolvedModel,
     hasInferredPricing,
     inputTokens: delta.inputTokens,
     cachedInputTokens: delta.cachedInputTokens,
diff --git a/src/main/codex-usage/store.test.ts b/src/main/codex-usage/store.test.ts
index da0549d2387..00686de5971 100644
--- a/src/main/codex-usage/store.test.ts
+++ b/src/main/codex-usage/store.test.ts
@@ -233,15 +233,79 @@ describe('CodexUsageStore', () => {
     const summary = await store.getSummary('orca', '30d')
     const breakdown = await store.getBreakdown('orca', '30d', 'model')
 
-    expect(summary.estimatedCostUsd).toBeCloseTo(85.1)
+    expect(summary.estimatedCostUsd).toBeCloseTo(107.486)
     expect(breakdown.find((row) => row.key === 'gpt-5.2-codex')?.estimatedCostUsd).toBeCloseTo(
       15.925
     )
     expect(breakdown.find((row) => row.key === 'gpt-5.3-codex')?.estimatedCostUsd).toBeCloseTo(
       15.925
     )
-    expect(breakdown.find((row) => row.key === 'gpt-5.4')?.estimatedCostUsd).toBeCloseTo(17.75)
-    expect(breakdown.find((row) => row.key === 'gpt-5.5')?.estimatedCostUsd).toBeCloseTo(35.5)
+    expect(breakdown.find((row) => row.key === 'gpt-5.4')?.estimatedCostUsd).toBeCloseTo(25.212)
+    expect(breakdown.find((row) => row.key === 'gpt-5.5')?.estimatedCostUsd).toBeCloseTo(50.424)
+  })
+
+  it('normalizes Codex model variants and reasoning suffixes before pricing', async () => {
+    const store = createStoreWithState({
+      dailyAggregates: [
+        {
+          day: '2026-04-09',
+          model: 'gpt-5.4-mini-high',
+          projectKey: 'worktree:repo-1::/workspace/repo',
+          projectLabel: 'Repo',
+          repoId: 'repo-1',
+          worktreeId: 'repo-1::/workspace/repo',
+          eventCount: 1,
+          inputTokens: 1_000_000,
+          cachedInputTokens: 500_000,
+          outputTokens: 1_000_000,
+          reasoningOutputTokens: 100_000,
+          totalTokens: 2_000_000,
+          hasInferredPricing: false
+        },
+        {
+          day: '2026-04-09',
+          model: 'gpt-5.3-codex-spark-xhigh',
+          projectKey: 'worktree:repo-1::/workspace/repo',
+          projectLabel: 'Repo',
+          repoId: 'repo-1',
+          worktreeId: 'repo-1::/workspace/repo',
+          eventCount: 1,
+          inputTokens: 2_000_000,
+          cachedInputTokens: 1_000_000,
+          outputTokens: 1_000_000,
+          reasoningOutputTokens: 100_000,
+          totalTokens: 3_000_000,
+          hasInferredPricing: false
+        },
+        {
+          day: '2026-04-09',
+          model: 'gpt-5.5(xhigh)',
+          projectKey: 'worktree:repo-1::/workspace/repo',
+          projectLabel: 'Repo',
+          repoId: 'repo-1',
+          worktreeId: 'repo-1::/workspace/repo',
+          eventCount: 1,
+          inputTokens: 100_000,
+          cachedInputTokens: 50_000,
+          outputTokens: 25_000,
+          reasoningOutputTokens: 5_000,
+          totalTokens: 125_000,
+          hasInferredPricing: false
+        }
+      ]
+    })
+
+    const breakdown = await store.getBreakdown('orca', '30d', 'model')
+
+    expect(breakdown.find((row) => row.key === 'gpt-5.4-mini-high')?.estimatedCostUsd).toBeCloseTo(
+      4.9125
+    )
+    expect(
+      breakdown.find((row) => row.key === 'gpt-5.3-codex-spark-xhigh')?.estimatedCostUsd
+    ).toBeCloseTo(15.925)
+    expect(breakdown.find((row) => row.key === 'gpt-5.5(xhigh)')?.estimatedCostUsd).toBeCloseTo(
+      1.025
+    )
   })
 
   it('keeps cached input out of the full-price input bucket for GPT-5.5 totals', async () => {
@@ -267,7 +331,7 @@ describe('CodexUsageStore', () => {
 
     const summary = await store.getSummary('orca', '30d')
 
-    expect(summary.estimatedCostUsd).toBeCloseTo(446.840002)
+    expect(summary.estimatedCostUsd).toBeCloseTo(858.929724)
   })
 
   it('counts mixed-model sessions once for each real model row in the breakdown', async () => {
@@ -584,7 +648,7 @@ describe('CodexUsageStore', () => {
     } as unknown as CodexUsagePersistedState)
 
     expect(normalized).toEqual({
-      schemaVersion: 2,
+      schemaVersion: 3,
       worktreeFingerprint: null,
       processedFiles: [],
       sessions: [],
diff --git a/src/main/codex-usage/store.ts b/src/main/codex-usage/store.ts
index dba5c4165a0..8699e4f49d1 100644
--- a/src/main/codex-usage/store.ts
+++ b/src/main/codex-usage/store.ts
@@ -17,20 +17,71 @@ import { loadKnownUsageWorktreesByRepo, type UsageWorktreeRef } from '../usage-w
 import type { CodexUsagePersistedState } from './types'
 import { createWorktreeRefs, scanCodexUsageFiles } from './scanner'
 
-const SCHEMA_VERSION = 2
+const SCHEMA_VERSION = 3
 const STALE_MS = 5 * 60_000
 
 let _codexUsageFile: string | null = null
 
-const MODEL_PRICING: Record<string, { input: number; cachedInput: number; output: number }> = {
+type TieredPrice = { threshold: number; price: number }
+type CodexModelPricing = {
+  input: number
+  cachedInput: number
+  output: number
+  inputTiers?: TieredPrice[]
+  cachedInputTiers?: TieredPrice[]
+  outputTiers?: TieredPrice[]
+}
+
+const LONG_CONTEXT_THRESHOLD_TOKENS = 272_000
+
+const MODEL_PRICING: Record<string, CodexModelPricing> = {
   'gpt-5': { input: 1.25, cachedInput: 0.125, output: 10 },
   'gpt-5.1': { input: 1.25, cachedInput: 0.125, output: 10 },
+  'gpt-5.1-codex': { input: 1.25, cachedInput: 0.125, output: 10 },
+  'gpt-5.1-codex-max': { input: 1.25, cachedInput: 0.125, output: 10 },
   'gpt-5.2': { input: 1.75, cachedInput: 0.175, output: 14 },
+  'gpt-5.2-codex': { input: 1.75, cachedInput: 0.175, output: 14 },
+  'gpt-5.3': { input: 1.75, cachedInput: 0.175, output: 14 },
   'gpt-5.3-codex': { input: 1.75, cachedInput: 0.175, output: 14 },
-  'gpt-5.4': { input: 2.5, cachedInput: 0.25, output: 15 },
-  'gpt-5.5': { input: 5, cachedInput: 0.5, output: 30 }
+  'gpt-5.3-codex-spark': { input: 1.75, cachedInput: 0.175, output: 14 },
+  'gpt-5.4-mini': { input: 0.75, cachedInput: 0.075, output: 4.5 },
+  'gpt-5.4-nano': { input: 0.2, cachedInput: 0.02, output: 1.25 },
+  'gpt-5.4-pro': {
+    input: 30,
+    cachedInput: 30,
+    output: 180,
+    inputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 60 }],
+    cachedInputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 60 }],
+    outputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 270 }]
+  },
+  'gpt-5.4': {
+    input: 2.5,
+    cachedInput: 0.25,
+    output: 15,
+    inputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 5 }],
+    cachedInputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 0.5 }],
+    outputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 22.5 }]
+  },
+  'gpt-5.5-pro': {
+    input: 30,
+    cachedInput: 30,
+    output: 180,
+    inputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 60 }],
+    cachedInputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 60 }],
+    outputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 270 }]
+  },
+  'gpt-5.5': {
+    input: 5,
+    cachedInput: 0.5,
+    output: 30,
+    inputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 10 }],
+    cachedInputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 1 }],
+    outputTiers: [{ threshold: LONG_CONTEXT_THRESHOLD_TOKENS, price: 45 }]
+  }
 }
 
+const REASONING_TIER_SUFFIXES = ['minimal', 'low', 'medium', 'high', 'xhigh', 'auto', 'none']
+
 function getDefaultState(): CodexUsagePersistedState {
   return {
     schemaVersion: SCHEMA_VERSION,
@@ -75,33 +126,104 @@ function getCodexUsageFile(): string {
   return _codexUsageFile
 }
 
+function stripParenthesizedReasoningTier(model: string): string | null {
+  const match = model.match(/^(.*)\(([^()]*)\)$/)
+  if (!match) {
+    return model
+  }
+  const tier = match[2].trim().toLowerCase()
+  if (!REASONING_TIER_SUFFIXES.includes(tier)) {
+    return null
+  }
+  return match[1]
+}
+
+function stripDashReasoningTiers(model: string): string {
+  let current = model
+  for (let index = 0; index < 4; index++) {
+    const suffix = REASONING_TIER_SUFFIXES.find((tier) => current.endsWith(`-${tier}`))
+    if (!suffix) {
+      return current
+    }
+    current = current.slice(0, -suffix.length - 1)
+  }
+  return current
+}
+
 function normalizeModelForPricing(model: string | null): string | null {
   if (!model) {
     return null
   }
 
-  const lower = model.toLowerCase()
-  if (lower === 'gpt-5' || lower === 'gpt-5-codex') {
+  const lower = stripParenthesizedReasoningTier(model.toLowerCase().trim())
+  if (!lower) {
+    return null
+  }
+
+  const normalized = stripDashReasoningTiers(lower)
+  if (normalized === 'gpt-5' || normalized === 'gpt-5-codex') {
     return 'gpt-5'
   }
-  if (lower.startsWith('gpt-5.1')) {
+  if (normalized === 'gpt-5.1-codex-max' || normalized.startsWith('gpt-5.1-codex-max-')) {
+    return 'gpt-5.1-codex-max'
+  }
+  if (normalized === 'gpt-5.1-codex' || normalized.startsWith('gpt-5.1-codex-')) {
+    return 'gpt-5.1-codex'
+  }
+  if (normalized === 'gpt-5.1' || normalized.startsWith('gpt-5.1-')) {
     return 'gpt-5.1'
   }
-  if (lower.startsWith('gpt-5.2')) {
+  if (normalized === 'gpt-5.2-codex' || normalized.startsWith('gpt-5.2-codex-')) {
+    return 'gpt-5.2-codex'
+  }
+  if (normalized === 'gpt-5.2' || normalized.startsWith('gpt-5.2-')) {
     return 'gpt-5.2'
   }
-  if (lower.startsWith('gpt-5.3-codex')) {
+  if (normalized === 'gpt-5.3-codex-spark' || normalized.startsWith('gpt-5.3-codex-spark-')) {
+    return 'gpt-5.3-codex-spark'
+  }
+  if (normalized === 'gpt-5.3-codex' || normalized.startsWith('gpt-5.3-codex-')) {
     return 'gpt-5.3-codex'
   }
-  if (lower.startsWith('gpt-5.4')) {
+  if (normalized === 'gpt-5.3' || normalized.startsWith('gpt-5.3-')) {
+    return 'gpt-5.3'
+  }
+  if (normalized === 'gpt-5.4-mini' || normalized.startsWith('gpt-5.4-mini-')) {
+    return 'gpt-5.4-mini'
+  }
+  if (normalized === 'gpt-5.4-nano' || normalized.startsWith('gpt-5.4-nano-')) {
+    return 'gpt-5.4-nano'
+  }
+  if (normalized === 'gpt-5.4-pro' || normalized.startsWith('gpt-5.4-pro-')) {
+    return 'gpt-5.4-pro'
+  }
+  if (normalized === 'gpt-5.4' || normalized.startsWith('gpt-5.4-')) {
     return 'gpt-5.4'
   }
-  if (lower.startsWith('gpt-5.5')) {
+  if (normalized === 'gpt-5.5-pro' || normalized.startsWith('gpt-5.5-pro-')) {
+    return 'gpt-5.5-pro'
+  }
+  if (normalized === 'gpt-5.5' || normalized.startsWith('gpt-5.5-')) {
     return 'gpt-5.5'
   }
   return null
 }
 
+function calculateTieredCost(tokens: number, basePrice: number, tiers: TieredPrice[] = []): number {
+  let cost = 0
+  let lowerBound = 0
+  let activePrice = basePrice
+  for (const tier of tiers) {
+    if (tokens <= tier.threshold) {
+      return cost + Math.max(tokens - lowerBound, 0) * activePrice
+    }
+    cost += (tier.threshold - lowerBound) * activePrice
+    lowerBound = tier.threshold
+    activePrice = tier.price
+  }
+  return cost + Math.max(tokens - lowerBound, 0) * activePrice
+}
+
 function estimateCostUsd(
   model: string | null,
   inputTokens: number,
@@ -119,9 +241,9 @@ function estimateCostUsd(
   // price and again at cache-read price.
   const nonCachedInputTokens = Math.max(inputTokens - clampedCached, 0)
   return (
-    (nonCachedInputTokens * pricing.input +
-      clampedCached * pricing.cachedInput +
-      outputTokens * pricing.output) /
+    (calculateTieredCost(nonCachedInputTokens, pricing.input, pricing.inputTiers) +
+      calculateTieredCost(clampedCached, pricing.cachedInput, pricing.cachedInputTiers) +
+      calculateTieredCost(outputTokens, pricing.output, pricing.outputTiers)) /
     1_000_000
   )
 }
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index d6eb79a6dbe..9d377436631 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -559,7 +559,7 @@ function Settings(): React.JSX.Element {
       {
         id: 'stats',
         title: 'Stats & Usage',
-        description: 'Orca stats and Claude usage analytics.',
+        description: 'Orca stats plus Claude and Codex usage analytics.',
         icon: BarChart3,
         searchEntries: STATS_PANE_SEARCH_ENTRIES
       },
diff --git a/src/renderer/src/components/stats/StatsPane.tsx b/src/renderer/src/components/stats/StatsPane.tsx
index 6722489a9fe..266b18a0e9a 100644
--- a/src/renderer/src/components/stats/StatsPane.tsx
+++ b/src/renderer/src/components/stats/StatsPane.tsx
@@ -4,6 +4,7 @@ import { useAppStore } from '../../store'
 import { StatCard } from './StatCard'
 import { ClaudeUsagePane } from './ClaudeUsagePane'
 import { CodexUsagePane } from './CodexUsagePane'
+import { UsageOverviewPane } from './UsageOverviewPane'
 import type { SettingsSearchEntry } from '../settings/settings-search'
 import { cn } from '@/lib/utils'
 
@@ -11,7 +12,7 @@ export const STATS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
   {
     title: 'Stats & Usage',
     description:
-      'Orca stats plus Claude and Codex usage analytics, tokens, cache, models, and sessions.',
+      'Orca stats plus combined Claude and Codex usage analytics, tokens, cache, models, and sessions.',
     keywords: [
       'stats',
       'usage',
@@ -59,7 +60,7 @@ function formatTrackingSince(timestamp: number | null): string {
 export function StatsPane(): React.JSX.Element {
   const summary = useAppStore((s) => s.statsSummary)
   const fetchStatsSummary = useAppStore((s) => s.fetchStatsSummary)
-  const [activeUsageTab, setActiveUsageTab] = useState<'claude' | 'codex'>('claude')
+  const [activeUsageTab, setActiveUsageTab] = useState<'overview' | 'claude' | 'codex'>('overview')
 
   useEffect(() => {
     void fetchStatsSummary()
@@ -110,7 +111,7 @@ export function StatsPane(): React.JSX.Element {
             aria-label="Usage analytics provider"
             className="inline-flex w-fit items-center justify-center rounded-lg bg-muted p-[3px] text-muted-foreground"
           >
-            {(['claude', 'codex'] as const).map((tab) => (
+            {(['overview', 'claude', 'codex'] as const).map((tab) => (
               <button
                 key={tab}
                 type="button"
@@ -123,7 +124,7 @@ export function StatsPane(): React.JSX.Element {
                     : 'text-foreground/60 hover:text-foreground dark:text-muted-foreground dark:hover:text-foreground'
                 )}
               >
-                {tab === 'claude' ? 'Claude' : 'Codex'}
+                {tab === 'overview' ? 'Overview' : tab === 'claude' ? 'Claude' : 'Codex'}
               </button>
             ))}
           </div>
@@ -132,7 +133,15 @@ export function StatsPane(): React.JSX.Element {
         {/* Why: the Stats section lives inside the scroll-tracked settings page. Keeping only the
             active panel mounted avoids hidden tab-content layout/focus churn that produced a visible
             vertical jitter below the usage card when switching disabled providers. */}
-        <div>{activeUsageTab === 'claude' ? <ClaudeUsagePane /> : <CodexUsagePane />}</div>
+        <div>
+          {activeUsageTab === 'overview' ? (
+            <UsageOverviewPane />
+          ) : activeUsageTab === 'claude' ? (
+            <ClaudeUsagePane />
+          ) : (
+            <CodexUsagePane />
+          )}
+        </div>
       </div>
     </div>
   )
diff --git a/src/renderer/src/components/stats/UsageOverviewPane.tsx b/src/renderer/src/components/stats/UsageOverviewPane.tsx
new file mode 100644
index 00000000000..202fcdf09d4
--- /dev/null
+++ b/src/renderer/src/components/stats/UsageOverviewPane.tsx
@@ -0,0 +1,412 @@
+import { useEffect, useMemo } from 'react'
+import {
+  Activity,
+  AlertCircle,
+  CalendarDays,
+  Coins,
+  DatabaseZap,
+  RefreshCw,
+  Sparkles
+} from 'lucide-react'
+import { useAppStore } from '../../store'
+import { Badge } from '../ui/badge'
+import { Button } from '../ui/button'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
+import { StatCard } from './StatCard'
+import {
+  buildUsageOverview,
+  formatUsageCost,
+  formatUsageTokens,
+  getRecentUsageDays,
+  type UsageOverviewDailyPoint,
+  type UsageOverviewModel,
+  type UsageProviderOverview
+} from './usage-overview-model'
+
+const RECENT_DAY_COUNT = 42
+
+const INTENSITY_CLASS: Record<UsageOverviewDailyPoint['intensity'], string> = {
+  0: 'border-border/60 bg-muted/40',
+  1: 'border-border/60 bg-muted-foreground/20',
+  2: 'border-border/60 bg-muted-foreground/35',
+  3: 'border-border/60 bg-muted-foreground/55',
+  4: 'border-border/60 bg-foreground/75'
+}
+
+function formatPercent(value: number | null): string {
+  if (value === null) {
+    return 'n/a'
+  }
+  return `${Math.round(value * 100)}%`
+}
+
+function formatUpdatedAt(timestamp: number | null): string {
+  if (!timestamp) {
+    return 'Not scanned yet'
+  }
+  return `Updated ${new Date(timestamp).toLocaleString()}`
+}
+
+function formatDayLabel(day: string): string {
+  const parsed = new Date(`${day}T12:00:00`)
+  if (Number.isNaN(parsed.getTime())) {
+    return day
+  }
+  return parsed.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+}
+
+function TokenMixBar({ overview }: { overview: UsageOverviewModel }): React.JSX.Element {
+  const segments = [
+    {
+      key: 'new-input',
+      label: 'New input',
+      value: overview.newInputTokens,
+      className: 'bg-foreground'
+    },
+    {
+      key: 'output',
+      label: 'Output',
+      value: overview.outputTokens,
+      className: 'bg-muted-foreground'
+    },
+    {
+      key: 'cache',
+      label: 'Cache',
+      value: overview.cacheTokens,
+      className: 'bg-border'
+    }
+  ]
+  // Why: Codex cached input is a subset of input. The overview model normalizes
+  // that into new/cache buckets so the visual mix does not double-count it.
+  const mixTotal = segments.reduce((sum, segment) => sum + segment.value, 0)
+
+  return (
+    <section className="rounded-lg border border-border/60 bg-card/40 p-4">
+      <div className="mb-3 flex items-start justify-between gap-3">
+        <div>
+          <h4 className="text-sm font-semibold text-foreground">Token mix</h4>
+          <p className="text-xs text-muted-foreground">
+            Combined input, output, and cache tokens across enabled providers.
+          </p>
+        </div>
+        {overview.reasoningTokens > 0 ? (
+          <Badge variant="outline" className="shrink-0">
+            {formatUsageTokens(overview.reasoningTokens)} reasoning
+          </Badge>
+        ) : null}
+      </div>
+
+      {mixTotal > 0 ? (
+        <div
+          className="flex h-3 overflow-hidden rounded-full border border-border/60 bg-muted"
+          aria-label="Combined token mix"
+        >
+          {segments.map((segment) =>
+            segment.value > 0 ? (
+              <div
+                key={segment.key}
+                className={segment.className}
+                style={{ width: `${(segment.value / mixTotal) * 100}%` }}
+                aria-label={`${segment.label}: ${segment.value.toLocaleString()} tokens`}
+              />
+            ) : null
+          )}
+        </div>
+      ) : (
+        <div className="h-3 rounded-full border border-dashed border-border/60 bg-muted/40" />
+      )}
+
+      <div className="mt-3 grid gap-2 text-xs text-muted-foreground sm:grid-cols-3">
+        {segments.map((segment) => (
+          <div key={segment.key} className="flex min-w-0 items-center gap-2">
+            <span className={`size-2 shrink-0 rounded-full ${segment.className}`} />
+            <span className="min-w-0 truncate">
+              {segment.label}: {formatUsageTokens(segment.value)}
+            </span>
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}
+
+function DailyIntensityGrid({
+  days,
+  bestDay
+}: {
+  days: UsageOverviewDailyPoint[]
+  bestDay: UsageOverviewDailyPoint | null
+}): React.JSX.Element {
+  return (
+    <section className="rounded-lg border border-border/60 bg-card/40 p-4">
+      <div className="mb-3 flex items-start justify-between gap-3">
+        <div>
+          <h4 className="text-sm font-semibold text-foreground">Daily intensity</h4>
+          <p className="text-xs text-muted-foreground">
+            Recent combined Claude and Codex token activity.
+          </p>
+        </div>
+        {bestDay && bestDay.totalTokens > 0 ? (
+          <Badge variant="outline" className="shrink-0">
+            Best: {formatDayLabel(bestDay.day)}
+          </Badge>
+        ) : null}
+      </div>
+
+      <div
+        className="grid grid-cols-[repeat(14,minmax(0,1fr))] gap-1 sm:grid-cols-[repeat(21,minmax(0,1fr))]"
+        aria-label="Recent token activity heatmap"
+      >
+        {days.map((day) => (
+          <div
+            key={day.day}
+            className={`aspect-square min-h-3 rounded-[2px] border ${INTENSITY_CLASS[day.intensity]}`}
+            aria-label={`${day.day}: ${day.totalTokens.toLocaleString()} tokens`}
+          />
+        ))}
+      </div>
+
+      <div className="mt-3 flex items-center justify-between gap-3 text-xs text-muted-foreground">
+        <span>{formatDayLabel(days[0]?.day ?? '')}</span>
+        <span>Less</span>
+        <div className="flex items-center gap-1" aria-hidden>
+          {[0, 1, 2, 3, 4].map((intensity) => (
+            <span
+              key={intensity}
+              className={`size-2 rounded-[2px] border ${INTENSITY_CLASS[intensity as UsageOverviewDailyPoint['intensity']]}`}
+            />
+          ))}
+        </div>
+        <span>More</span>
+        <span>{formatDayLabel(days.at(-1)?.day ?? '')}</span>
+      </div>
+    </section>
+  )
+}
+
+function ProviderRow({
+  provider,
+  totalTokens,
+  onEnable
+}: {
+  provider: UsageProviderOverview
+  totalTokens: number
+  onEnable: () => void
+}): React.JSX.Element {
+  const share = totalTokens > 0 ? provider.totalTokens / totalTokens : 0
+  const status = provider.enabled ? (provider.isScanning ? 'Scanning' : 'Enabled') : 'Off'
+  const statusVariant = provider.enabled ? 'secondary' : 'outline'
+
+  return (
+    <div className="rounded-lg border border-border/60 bg-card/40 p-3">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <div className="flex min-w-0 items-center gap-2">
+            <h5 className="truncate text-sm font-semibold text-foreground">{provider.label}</h5>
+            <Badge variant={statusVariant}>{status}</Badge>
+          </div>
+          <p className="mt-1 truncate text-xs text-muted-foreground">
+            {provider.topModel ?? 'No model yet'}
+            {provider.topProject ? ` - ${provider.topProject}` : ''}
+          </p>
+        </div>
+        {!provider.enabled ? (
+          <Button variant="outline" size="xs" onClick={onEnable}>
+            Enable
+          </Button>
+        ) : null}
+      </div>
+
+      <div className="mt-3 grid gap-2 text-xs text-muted-foreground sm:grid-cols-3">
+        <span>{formatUsageTokens(provider.totalTokens)} tokens</span>
+        <span>
+          {provider.sessions.toLocaleString()} sessions - {provider.activityCount.toLocaleString()}{' '}
+          {provider.activityLabel}
+        </span>
+        <span>{formatUsageCost(provider.estimatedCostUsd)}</span>
+      </div>
+      <div className="mt-3 h-1.5 overflow-hidden rounded-full bg-muted">
+        <div
+          className="h-full rounded-full bg-foreground/75"
+          style={{ width: `${Math.max(share * 100, provider.totalTokens > 0 ? 2 : 0)}%` }}
+        />
+      </div>
+      {provider.lastScanError ? (
+        <p className="mt-2 flex items-center gap-1 text-xs text-destructive">
+          <AlertCircle className="size-3" />
+          {provider.lastScanError}
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+export function UsageOverviewPane(): React.JSX.Element {
+  const claudeScanState = useAppStore((state) => state.claudeUsageScanState)
+  const claudeSummary = useAppStore((state) => state.claudeUsageSummary)
+  const claudeDaily = useAppStore((state) => state.claudeUsageDaily)
+  const codexScanState = useAppStore((state) => state.codexUsageScanState)
+  const codexSummary = useAppStore((state) => state.codexUsageSummary)
+  const codexDaily = useAppStore((state) => state.codexUsageDaily)
+  const fetchClaudeUsage = useAppStore((state) => state.fetchClaudeUsage)
+  const fetchCodexUsage = useAppStore((state) => state.fetchCodexUsage)
+  const refreshClaudeUsage = useAppStore((state) => state.refreshClaudeUsage)
+  const refreshCodexUsage = useAppStore((state) => state.refreshCodexUsage)
+  const enableClaudeUsage = useAppStore((state) => state.enableClaudeUsage)
+  const enableCodexUsage = useAppStore((state) => state.enableCodexUsage)
+
+  useEffect(() => {
+    void fetchClaudeUsage()
+    void fetchCodexUsage()
+  }, [fetchClaudeUsage, fetchCodexUsage])
+
+  const overview = useMemo(
+    () =>
+      buildUsageOverview({
+        claude: {
+          scanState: claudeScanState,
+          summary: claudeSummary,
+          daily: claudeDaily
+        },
+        codex: {
+          scanState: codexScanState,
+          summary: codexSummary,
+          daily: codexDaily
+        }
+      }),
+    [claudeDaily, claudeScanState, claudeSummary, codexDaily, codexScanState, codexSummary]
+  )
+  const recentDays = useMemo(
+    () => getRecentUsageDays(overview.daily, RECENT_DAY_COUNT),
+    [overview.daily]
+  )
+  const isScanning = overview.providers.some((provider) => provider.isScanning)
+
+  const handleRefresh = (): void => {
+    void Promise.all([
+      claudeScanState?.enabled ? refreshClaudeUsage() : Promise.resolve(),
+      codexScanState?.enabled ? refreshCodexUsage() : Promise.resolve()
+    ])
+  }
+
+  return (
+    <div className="space-y-4" data-testid="usage-overview-pane">
+      <section className="rounded-lg border border-border/60 bg-card/30 p-4">
+        <div className="flex items-start justify-between gap-4">
+          <div className="min-w-0">
+            <h3 className="text-sm font-semibold text-foreground">Usage Overview</h3>
+            <p className="mt-1 text-xs text-muted-foreground">
+              {formatUpdatedAt(overview.lastUpdatedAt)}
+              {overview.hasPartialCost ? ' - some model prices are unavailable' : ''}
+            </p>
+          </div>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="ghost"
+                size="icon-xs"
+                onClick={handleRefresh}
+                disabled={!overview.hasAnyEnabledProvider || isScanning}
+                aria-label="Refresh usage overview"
+              >
+                <RefreshCw className={`size-3.5 ${isScanning ? 'animate-spin' : ''}`} />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={6}>
+              Refresh
+            </TooltipContent>
+          </Tooltip>
+        </div>
+
+        {!overview.hasAnyEnabledProvider ? (
+          <div className="mt-4 rounded-lg border border-dashed border-border/60 bg-card/30 px-4 py-5">
+            <div className="max-w-xl space-y-3">
+              <div>
+                <h4 className="text-sm font-semibold text-foreground">Start tracking tokens</h4>
+                <p className="mt-1 text-sm text-muted-foreground">
+                  Enable a provider to scan local agent logs and build the combined token ledger.
+                </p>
+              </div>
+              <div className="flex flex-wrap gap-2">
+                <Button size="sm" onClick={() => void enableClaudeUsage()}>
+                  Enable Claude
+                </Button>
+                <Button variant="secondary" size="sm" onClick={() => void enableCodexUsage()}>
+                  Enable Codex
+                </Button>
+              </div>
+            </div>
+          </div>
+        ) : (
+          <>
+            <div className="mt-4 grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+              <StatCard
+                label="Total tokens"
+                value={formatUsageTokens(overview.totalTokens)}
+                icon={<Sparkles className="size-4" />}
+              />
+              <StatCard
+                label="Est. cost"
+                value={formatUsageCost(overview.estimatedCostUsd)}
+                icon={<Coins className="size-4" />}
+              />
+              <StatCard
+                label="Active days"
+                value={overview.activeDays.toLocaleString()}
+                icon={<CalendarDays className="size-4" />}
+              />
+              <StatCard
+                label="Cache share"
+                value={formatPercent(overview.cacheShare)}
+                icon={<DatabaseZap className="size-4" />}
+              />
+            </div>
+
+            {!overview.hasAnyData ? (
+              <div className="mt-4 rounded-lg border border-dashed border-border/60 bg-card/30 px-4 py-5 text-sm text-muted-foreground">
+                No local Claude or Codex usage found yet. The overview will populate after the next
+                agent session writes token logs.
+              </div>
+            ) : (
+              <div className="mt-4 grid gap-4 xl:grid-cols-[minmax(0,1.2fr)_minmax(0,0.8fr)]">
+                <DailyIntensityGrid days={recentDays} bestDay={overview.bestDay} />
+                <TokenMixBar overview={overview} />
+              </div>
+            )}
+          </>
+        )}
+      </section>
+
+      <section className="space-y-3">
+        <div className="flex items-center justify-between gap-3">
+          <div>
+            <h4 className="text-sm font-semibold text-foreground">Providers</h4>
+            <p className="text-xs text-muted-foreground">
+              {overview.enabledProviderCount} enabled - {overview.dataProviderCount} with data
+            </p>
+          </div>
+          <Badge variant="outline" className="gap-1">
+            <Activity className="size-3" />
+            {overview.sessions.toLocaleString()} sessions
+          </Badge>
+        </div>
+        <div className="grid gap-3 xl:grid-cols-2">
+          {overview.providers.map((provider) => (
+            <ProviderRow
+              key={provider.id}
+              provider={provider}
+              totalTokens={overview.totalTokens}
+              onEnable={() => {
+                if (provider.id === 'claude') {
+                  void enableClaudeUsage()
+                } else {
+                  void enableCodexUsage()
+                }
+              }}
+            />
+          ))}
+        </div>
+      </section>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/stats/usage-overview-model.test.ts b/src/renderer/src/components/stats/usage-overview-model.test.ts
new file mode 100644
index 00000000000..490bcc1b8f4
--- /dev/null
+++ b/src/renderer/src/components/stats/usage-overview-model.test.ts
@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'vitest'
+import type {
+  ClaudeUsageDailyPoint,
+  ClaudeUsageScanState,
+  ClaudeUsageSummary
+} from '../../../../shared/claude-usage-types'
+import type {
+  CodexUsageDailyPoint,
+  CodexUsageScanState,
+  CodexUsageSummary
+} from '../../../../shared/codex-usage-types'
+import {
+  buildUsageOverview,
+  formatUsageCost,
+  formatUsageTokens,
+  getRecentUsageDays
+} from './usage-overview-model'
+
+function enabledClaudeScanState(): ClaudeUsageScanState {
+  return {
+    enabled: true,
+    isScanning: false,
+    lastScanStartedAt: 100,
+    lastScanCompletedAt: 200,
+    lastScanError: null,
+    hasAnyClaudeData: true
+  }
+}
+
+function enabledCodexScanState(): CodexUsageScanState {
+  return {
+    enabled: true,
+    isScanning: false,
+    lastScanStartedAt: 300,
+    lastScanCompletedAt: 400,
+    lastScanError: null,
+    hasAnyCodexData: true
+  }
+}
+
+describe('usage overview model', () => {
+  it('combines Claude and Codex totals without double-counting Codex cached input', () => {
+    const claudeSummary: ClaudeUsageSummary = {
+      scope: 'orca',
+      range: '30d',
+      sessions: 2,
+      turns: 4,
+      zeroCacheReadTurns: 1,
+      inputTokens: 1_000,
+      outputTokens: 500,
+      cacheReadTokens: 4_000,
+      cacheWriteTokens: 500,
+      cacheReuseRate: 0.8,
+      estimatedCostUsd: 0.04,
+      topModel: 'claude-sonnet-4-5',
+      topProject: 'orca-main',
+      hasAnyClaudeData: true
+    }
+    const codexSummary: CodexUsageSummary = {
+      scope: 'orca',
+      range: '30d',
+      sessions: 1,
+      events: 3,
+      inputTokens: 2_000,
+      cachedInputTokens: 800,
+      outputTokens: 1_200,
+      reasoningOutputTokens: 300,
+      totalTokens: 3_200,
+      estimatedCostUsd: 0.02,
+      topModel: 'gpt-5.4',
+      topProject: 'orca-secondary',
+      hasAnyCodexData: true
+    }
+    const claudeDaily: ClaudeUsageDailyPoint[] = [
+      {
+        day: '2026-05-13',
+        inputTokens: 500,
+        outputTokens: 500,
+        cacheReadTokens: 2_500,
+        cacheWriteTokens: 0
+      },
+      {
+        day: '2026-05-14',
+        inputTokens: 500,
+        outputTokens: 0,
+        cacheReadTokens: 1_500,
+        cacheWriteTokens: 500
+      }
+    ]
+    const codexDaily: CodexUsageDailyPoint[] = [
+      {
+        day: '2026-05-14',
+        inputTokens: 1_200,
+        cachedInputTokens: 400,
+        outputTokens: 800,
+        reasoningOutputTokens: 100,
+        totalTokens: 2_000
+      },
+      {
+        day: '2026-05-15',
+        inputTokens: 800,
+        cachedInputTokens: 400,
+        outputTokens: 400,
+        reasoningOutputTokens: 200,
+        totalTokens: 1_200
+      }
+    ]
+
+    const overview = buildUsageOverview({
+      claude: {
+        scanState: enabledClaudeScanState(),
+        summary: claudeSummary,
+        daily: claudeDaily
+      },
+      codex: {
+        scanState: enabledCodexScanState(),
+        summary: codexSummary,
+        daily: codexDaily
+      }
+    })
+
+    expect(overview.totalTokens).toBe(9_200)
+    expect(overview.newInputTokens).toBe(2_200)
+    expect(overview.cacheTokens).toBe(5_300)
+    expect(overview.outputTokens).toBe(1_700)
+    expect(overview.reasoningTokens).toBe(300)
+    expect(overview.sessions).toBe(3)
+    expect(overview.activityCount).toBe(7)
+    expect(overview.activeDays).toBe(3)
+    expect(overview.estimatedCostUsd).toBeCloseTo(0.06)
+    expect(overview.cacheShare).toBeCloseTo(5_300 / 7_500)
+    expect(overview.bestDay).toMatchObject({
+      day: '2026-05-14',
+      totalTokens: 4_500,
+      claudeTokens: 2_500,
+      codexTokens: 2_000,
+      intensity: 4
+    })
+    expect(overview.providers.find((provider) => provider.id === 'codex')).toMatchObject({
+      newInputTokens: 1_200,
+      cacheTokens: 800,
+      totalTokens: 3_200
+    })
+  })
+
+  it('pads recent usage days with zero-token cells', () => {
+    const recent = getRecentUsageDays(
+      [
+        {
+          day: '2026-05-14',
+          totalTokens: 4_500,
+          claudeTokens: 2_500,
+          codexTokens: 2_000,
+          intensity: 4
+        }
+      ],
+      3,
+      new Date('2026-05-15T12:00:00')
+    )
+
+    expect(recent).toEqual([
+      {
+        day: '2026-05-13',
+        totalTokens: 0,
+        claudeTokens: 0,
+        codexTokens: 0,
+        intensity: 0
+      },
+      {
+        day: '2026-05-14',
+        totalTokens: 4_500,
+        claudeTokens: 2_500,
+        codexTokens: 2_000,
+        intensity: 4
+      },
+      {
+        day: '2026-05-15',
+        totalTokens: 0,
+        claudeTokens: 0,
+        codexTokens: 0,
+        intensity: 0
+      }
+    ])
+  })
+
+  it('reports disabled providers as an empty overview', () => {
+    const overview = buildUsageOverview({
+      claude: { scanState: null, summary: null, daily: [] },
+      codex: { scanState: null, summary: null, daily: [] }
+    })
+
+    expect(overview.hasAnyEnabledProvider).toBe(false)
+    expect(overview.hasAnyData).toBe(false)
+    expect(overview.totalTokens).toBe(0)
+    expect(overview.estimatedCostUsd).toBeNull()
+    expect(overview.cacheShare).toBeNull()
+  })
+
+  it('formats token and cost values for compact UI labels', () => {
+    expect(formatUsageTokens(999)).toBe('999')
+    expect(formatUsageTokens(1_200)).toBe('1.2k')
+    expect(formatUsageTokens(2_500_000)).toBe('2.5M')
+    expect(formatUsageCost(null)).toBe('n/a')
+    expect(formatUsageCost(0.0042)).toBe('$0.0042')
+    expect(formatUsageCost(1.234)).toBe('$1.23')
+  })
+})
diff --git a/src/renderer/src/components/stats/usage-overview-model.ts b/src/renderer/src/components/stats/usage-overview-model.ts
new file mode 100644
index 00000000000..47104aec739
--- /dev/null
+++ b/src/renderer/src/components/stats/usage-overview-model.ts
@@ -0,0 +1,319 @@
+import type {
+  ClaudeUsageDailyPoint,
+  ClaudeUsageScanState,
+  ClaudeUsageSummary
+} from '../../../../shared/claude-usage-types'
+import type {
+  CodexUsageDailyPoint,
+  CodexUsageScanState,
+  CodexUsageSummary
+} from '../../../../shared/codex-usage-types'
+
+export type UsageProviderId = 'claude' | 'codex'
+
+export type UsageProviderOverview = {
+  id: UsageProviderId
+  label: string
+  enabled: boolean
+  isScanning: boolean
+  hasData: boolean
+  lastScanCompletedAt: number | null
+  lastScanError: string | null
+  sessions: number
+  activityLabel: 'turns' | 'events'
+  activityCount: number
+  totalTokens: number
+  newInputTokens: number
+  outputTokens: number
+  cacheTokens: number
+  reasoningTokens: number
+  estimatedCostUsd: number | null
+  topModel: string | null
+  topProject: string | null
+  activeDays: number
+}
+
+export type UsageOverviewDailyPoint = {
+  day: string
+  totalTokens: number
+  claudeTokens: number
+  codexTokens: number
+  intensity: 0 | 1 | 2 | 3 | 4
+}
+
+export type UsageOverviewModel = {
+  providers: UsageProviderOverview[]
+  enabledProviderCount: number
+  dataProviderCount: number
+  hasAnyEnabledProvider: boolean
+  hasAnyData: boolean
+  totalTokens: number
+  newInputTokens: number
+  outputTokens: number
+  cacheTokens: number
+  reasoningTokens: number
+  sessions: number
+  activityCount: number
+  activeDays: number
+  estimatedCostUsd: number | null
+  hasPartialCost: boolean
+  cacheShare: number | null
+  daily: UsageOverviewDailyPoint[]
+  bestDay: UsageOverviewDailyPoint | null
+  lastUpdatedAt: number | null
+}
+
+export type UsageOverviewInput = {
+  claude: {
+    scanState: ClaudeUsageScanState | null
+    summary: ClaudeUsageSummary | null
+    daily: ClaudeUsageDailyPoint[]
+  }
+  codex: {
+    scanState: CodexUsageScanState | null
+    summary: CodexUsageSummary | null
+    daily: CodexUsageDailyPoint[]
+  }
+}
+
+function getClaudeDailyTotal(entry: ClaudeUsageDailyPoint): number {
+  return entry.inputTokens + entry.outputTokens + entry.cacheReadTokens + entry.cacheWriteTokens
+}
+
+function getCodexNewInputTokens(summary: CodexUsageSummary | null): number {
+  if (!summary) {
+    return 0
+  }
+  return Math.max(summary.inputTokens - summary.cachedInputTokens, 0)
+}
+
+function getIntensity(totalTokens: number, maxTokens: number): 0 | 1 | 2 | 3 | 4 {
+  if (totalTokens <= 0 || maxTokens <= 0) {
+    return 0
+  }
+  const ratio = totalTokens / maxTokens
+  if (ratio <= 0.25) {
+    return 1
+  }
+  if (ratio <= 0.5) {
+    return 2
+  }
+  if (ratio <= 0.75) {
+    return 3
+  }
+  return 4
+}
+
+function countActiveDays(days: string[]): number {
+  return new Set(days).size
+}
+
+function createClaudeProvider(input: UsageOverviewInput['claude']): UsageProviderOverview {
+  const summary = input.summary
+  const dailyActiveDays = input.daily
+    .filter((entry) => getClaudeDailyTotal(entry) > 0)
+    .map((entry) => entry.day)
+  return {
+    id: 'claude',
+    label: 'Claude',
+    enabled: input.scanState?.enabled ?? false,
+    isScanning: input.scanState?.isScanning ?? false,
+    hasData: summary?.hasAnyClaudeData ?? input.scanState?.hasAnyClaudeData ?? false,
+    lastScanCompletedAt: input.scanState?.lastScanCompletedAt ?? null,
+    lastScanError: input.scanState?.lastScanError ?? null,
+    sessions: summary?.sessions ?? 0,
+    activityLabel: 'turns',
+    activityCount: summary?.turns ?? 0,
+    totalTokens: summary
+      ? summary.inputTokens +
+        summary.outputTokens +
+        summary.cacheReadTokens +
+        summary.cacheWriteTokens
+      : 0,
+    newInputTokens: summary?.inputTokens ?? 0,
+    outputTokens: summary?.outputTokens ?? 0,
+    cacheTokens: summary ? summary.cacheReadTokens + summary.cacheWriteTokens : 0,
+    reasoningTokens: 0,
+    estimatedCostUsd: summary?.estimatedCostUsd ?? null,
+    topModel: summary?.topModel ?? null,
+    topProject: summary?.topProject ?? null,
+    activeDays: countActiveDays(dailyActiveDays)
+  }
+}
+
+function createCodexProvider(input: UsageOverviewInput['codex']): UsageProviderOverview {
+  const summary = input.summary
+  const dailyActiveDays = input.daily
+    .filter((entry) => entry.totalTokens > 0)
+    .map((entry) => entry.day)
+  return {
+    id: 'codex',
+    label: 'Codex',
+    enabled: input.scanState?.enabled ?? false,
+    isScanning: input.scanState?.isScanning ?? false,
+    hasData: summary?.hasAnyCodexData ?? input.scanState?.hasAnyCodexData ?? false,
+    lastScanCompletedAt: input.scanState?.lastScanCompletedAt ?? null,
+    lastScanError: input.scanState?.lastScanError ?? null,
+    sessions: summary?.sessions ?? 0,
+    activityLabel: 'events',
+    activityCount: summary?.events ?? 0,
+    totalTokens: summary?.totalTokens ?? 0,
+    newInputTokens: getCodexNewInputTokens(summary),
+    outputTokens: summary?.outputTokens ?? 0,
+    cacheTokens: summary?.cachedInputTokens ?? 0,
+    reasoningTokens: summary?.reasoningOutputTokens ?? 0,
+    estimatedCostUsd: summary?.estimatedCostUsd ?? null,
+    topModel: summary?.topModel ?? null,
+    topProject: summary?.topProject ?? null,
+    activeDays: countActiveDays(dailyActiveDays)
+  }
+}
+
+function buildDailyOverview(input: UsageOverviewInput): UsageOverviewDailyPoint[] {
+  const byDay = new Map<string, Omit<UsageOverviewDailyPoint, 'intensity'>>()
+
+  for (const entry of input.claude.daily) {
+    const current = byDay.get(entry.day) ?? {
+      day: entry.day,
+      totalTokens: 0,
+      claudeTokens: 0,
+      codexTokens: 0
+    }
+    const total = getClaudeDailyTotal(entry)
+    current.totalTokens += total
+    current.claudeTokens += total
+    byDay.set(entry.day, current)
+  }
+
+  for (const entry of input.codex.daily) {
+    const current = byDay.get(entry.day) ?? {
+      day: entry.day,
+      totalTokens: 0,
+      claudeTokens: 0,
+      codexTokens: 0
+    }
+    current.totalTokens += entry.totalTokens
+    current.codexTokens += entry.totalTokens
+    byDay.set(entry.day, current)
+  }
+
+  const maxTokens = Math.max(0, ...[...byDay.values()].map((entry) => entry.totalTokens))
+  return [...byDay.values()]
+    .sort((left, right) => left.day.localeCompare(right.day))
+    .map((entry) => ({
+      ...entry,
+      intensity: getIntensity(entry.totalTokens, maxTokens)
+    }))
+}
+
+function formatLocalDay(date: Date): string {
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${year}-${month}-${day}`
+}
+
+export function getRecentUsageDays(
+  daily: UsageOverviewDailyPoint[],
+  dayCount: number,
+  anchorDate = new Date()
+): UsageOverviewDailyPoint[] {
+  const byDay = new Map(daily.map((entry) => [entry.day, entry]))
+  const count = Math.max(1, Math.floor(dayCount))
+  const end = new Date(anchorDate)
+  end.setHours(0, 0, 0, 0)
+
+  const result: UsageOverviewDailyPoint[] = []
+  for (let offset = count - 1; offset >= 0; offset--) {
+    const date = new Date(end)
+    date.setDate(end.getDate() - offset)
+    const day = formatLocalDay(date)
+    result.push(
+      byDay.get(day) ?? {
+        day,
+        totalTokens: 0,
+        claudeTokens: 0,
+        codexTokens: 0,
+        intensity: 0
+      }
+    )
+  }
+  return result
+}
+
+export function buildUsageOverview(input: UsageOverviewInput): UsageOverviewModel {
+  const providers = [createClaudeProvider(input.claude), createCodexProvider(input.codex)]
+  const daily = buildDailyOverview(input)
+  const bestDay =
+    daily.length === 0
+      ? null
+      : daily.reduce<UsageOverviewDailyPoint | null>(
+          (best, entry) => (!best || entry.totalTokens > best.totalTokens ? entry : best),
+          null
+        )
+  const totalTokens = providers.reduce((sum, provider) => sum + provider.totalTokens, 0)
+  const newInputTokens = providers.reduce((sum, provider) => sum + provider.newInputTokens, 0)
+  const outputTokens = providers.reduce((sum, provider) => sum + provider.outputTokens, 0)
+  const cacheTokens = providers.reduce((sum, provider) => sum + provider.cacheTokens, 0)
+  const reasoningTokens = providers.reduce((sum, provider) => sum + provider.reasoningTokens, 0)
+  const sessions = providers.reduce((sum, provider) => sum + provider.sessions, 0)
+  const activityCount = providers.reduce((sum, provider) => sum + provider.activityCount, 0)
+  const knownCost = providers.reduce((sum, provider) => sum + (provider.estimatedCostUsd ?? 0), 0)
+  const hasKnownCost = providers.some((provider) => provider.estimatedCostUsd !== null)
+  const hasPartialCost = providers.some(
+    (provider) => provider.hasData && provider.estimatedCostUsd === null
+  )
+  const lastUpdatedAt =
+    providers.reduce<number | null>(
+      (latest, provider) =>
+        provider.lastScanCompletedAt && (!latest || provider.lastScanCompletedAt > latest)
+          ? provider.lastScanCompletedAt
+          : latest,
+      null
+    ) ?? null
+
+  return {
+    providers,
+    enabledProviderCount: providers.filter((provider) => provider.enabled).length,
+    dataProviderCount: providers.filter((provider) => provider.hasData).length,
+    hasAnyEnabledProvider: providers.some((provider) => provider.enabled),
+    hasAnyData: providers.some((provider) => provider.hasData),
+    totalTokens,
+    newInputTokens,
+    outputTokens,
+    cacheTokens,
+    reasoningTokens,
+    sessions,
+    activityCount,
+    activeDays: countActiveDays(
+      daily.filter((entry) => entry.totalTokens > 0).map((entry) => entry.day)
+    ),
+    estimatedCostUsd: hasKnownCost ? knownCost : null,
+    hasPartialCost,
+    cacheShare:
+      newInputTokens + cacheTokens > 0 ? cacheTokens / (newInputTokens + cacheTokens) : null,
+    daily,
+    bestDay,
+    lastUpdatedAt
+  }
+}
+
+export function formatUsageTokens(value: number): string {
+  if (value >= 1_000_000_000) {
+    return `${(value / 1_000_000_000).toFixed(1)}B`
+  }
+  if (value >= 1_000_000) {
+    return `${(value / 1_000_000).toFixed(1)}M`
+  }
+  if (value >= 1_000) {
+    return `${(value / 1_000).toFixed(1)}k`
+  }
+  return value.toLocaleString()
+}
+
+export function formatUsageCost(value: number | null): string {
+  if (value === null) {
+    return 'n/a'
+  }
+  return value < 0.01 ? `$${value.toFixed(4)}` : `$${value.toFixed(2)}`
+}
diff --git a/tests/e2e/usage-overview.spec.ts b/tests/e2e/usage-overview.spec.ts
new file mode 100644
index 00000000000..07559cbb535
--- /dev/null
+++ b/tests/e2e/usage-overview.spec.ts
@@ -0,0 +1,35 @@
+import { test, expect } from './helpers/orca-app'
+import { getStoreState, waitForSessionReady } from './helpers/store'
+
+test.describe('usage overview', () => {
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+  })
+
+  test('Stats & Usage opens on the combined overview with provider controls', async ({
+    orcaPage
+  }) => {
+    await orcaPage.evaluate(() => {
+      const state = window.__store!.getState()
+      state.openSettingsTarget({ pane: 'stats' })
+      state.openSettingsPage()
+    })
+
+    await expect
+      .poll(async () => getStoreState<string>(orcaPage, 'activeView'), { timeout: 5_000 })
+      .toBe('settings')
+    await expect(orcaPage.getByRole('heading', { name: 'Usage Analytics' })).toBeVisible()
+    const providerTabs = orcaPage.getByRole('group', { name: 'Usage analytics provider' })
+    await expect(
+      providerTabs.getByRole('button', { name: 'Overview', exact: true })
+    ).toHaveAttribute('aria-pressed', 'true')
+    await expect(orcaPage.getByTestId('usage-overview-pane')).toBeVisible()
+    await expect(orcaPage.getByRole('heading', { name: 'Usage Overview' })).toBeVisible()
+    await expect(orcaPage.getByRole('heading', { name: 'Providers' })).toBeVisible()
+    await expect(orcaPage.getByRole('button', { name: 'Enable Claude' })).toBeVisible()
+    await expect(orcaPage.getByRole('button', { name: 'Enable Codex' })).toBeVisible()
+
+    await providerTabs.getByRole('button', { name: 'Codex', exact: true }).click()
+    await expect(orcaPage.getByRole('heading', { name: 'Codex Usage Tracking' })).toBeVisible()
+  })
+})

From 9217cf625d8d08daa482a1918dff9d19fe7c47ad Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 15 May 2026 16:17:35 -0400
Subject: [PATCH 65/82] Fix mobile TUI scroll gestures (#1940)

Co-authored-by: Orca <help@stably.ai>
---
 .../app/h/[hostId]/session/[worktreeId].tsx   | 186 ++++++-
 mobile/src/terminal/TerminalWebView.tsx       | 504 ++++++++++++++----
 .../terminal/terminal-gesture-input.test.ts   |  42 ++
 mobile/src/terminal/terminal-gesture-input.ts |  71 +++
 src/main/daemon/headless-emulator.test.ts     | 191 +++++++
 src/main/daemon/headless-emulator.ts          | 141 ++++-
 src/main/daemon/types.ts                      |  11 +-
 .../use-worktree-activity-status.test.tsx     |   6 +-
 .../sidebar/use-worktree-activity-status.ts   |   2 +-
 .../terminal-pane/terminal-appearance.ts      |   6 +-
 10 files changed, 1028 insertions(+), 132 deletions(-)
 create mode 100644 mobile/src/terminal/terminal-gesture-input.test.ts
 create mode 100644 mobile/src/terminal/terminal-gesture-input.ts

diff --git a/mobile/app/h/[hostId]/session/[worktreeId].tsx b/mobile/app/h/[hostId]/session/[worktreeId].tsx
index cab15d8e82c..6d03e194409 100644
--- a/mobile/app/h/[hostId]/session/[worktreeId].tsx
+++ b/mobile/app/h/[hostId]/session/[worktreeId].tsx
@@ -48,6 +48,7 @@ import {
   type TerminalModes,
   type TerminalWebViewHandle
 } from '../../../../src/terminal/TerminalWebView'
+import { countTerminalGestureInputSequences } from '../../../../src/terminal/terminal-gesture-input'
 import { StatusDot } from '../../../../src/components/StatusDot'
 import { ActionSheetModal } from '../../../../src/components/ActionSheetModal'
 import { TextInputModal } from '../../../../src/components/TextInputModal'
@@ -205,6 +206,28 @@ const STATUS_LABELS: Record<ConnectionState, string> = {
   'auth-failed': 'Auth failed'
 }
 
+const TERMINAL_GESTURE_INPUT_BUCKET_CAPACITY = 64
+const TERMINAL_GESTURE_INPUT_REFILL_PER_SECOND = 120
+const TERMINAL_GESTURE_INPUT_FLUSH_DELAY_MS = 16
+const TERMINAL_GESTURE_INPUT_MAX_PENDING_SEQUENCES = 32
+const TERMINAL_GESTURE_INPUT_MAX_QUEUE_AGE_MS = 250
+
+type TerminalGestureInputBucket = {
+  tokens: number
+  lastRefillMs: number
+}
+
+type TerminalGestureInputQueue = {
+  bytes: string
+  sequenceCount: number
+  timer: ReturnType<typeof setTimeout> | null
+  lastUpdatedMs: number
+}
+
+function isWheelMouseTrackingMode(mode: TerminalModes['mouseTrackingMode'] | undefined): boolean {
+  return mode === 'vt200' || mode === 'drag' || mode === 'any'
+}
+
 function TerminalPaneView({
   handle,
   active,
@@ -216,7 +239,8 @@ function TerminalPaneView({
   onSelectionEvicted,
   onModesChanged,
   onKeyboardAvoidanceMetrics,
-  onHaptic
+  onHaptic,
+  onTerminalInput
 }: {
   handle: string
   active: boolean
@@ -229,6 +253,7 @@ function TerminalPaneView({
   onModesChanged: (handle: string, modes: TerminalModes) => void
   onKeyboardAvoidanceMetrics: (handle: string, metrics: TerminalKeyboardAvoidanceMetrics) => void
   onHaptic: (kind: 'selection' | 'success' | 'error' | 'edge-bump') => void
+  onTerminalInput: (handle: string, bytes: string) => void
 }) {
   const setRef = useCallback(
     (ref: TerminalWebViewHandle | null) => {
@@ -256,6 +281,7 @@ function TerminalPaneView({
         onModesChanged={(m) => onModesChanged(handle, m)}
         onKeyboardAvoidanceMetrics={(m) => onKeyboardAvoidanceMetrics(handle, m)}
         onHaptic={onHaptic}
+        onTerminalInput={(bytes) => onTerminalInput(handle, bytes)}
       />
     </View>
   )
@@ -466,9 +492,13 @@ export default function SessionScreen() {
   // Why: WebView pushes terminal modes (bracketed-paste, alt-screen) on every
   // change so paste reads a synchronous snapshot — no round-trip required.
   const ptyModesRef = useRef<Map<string, TerminalModes>>(new Map())
+  const terminalGestureInputBucketsRef = useRef<Map<string, TerminalGestureInputBucket>>(new Map())
+  const terminalGestureInputQueuesRef = useRef<Map<string, TerminalGestureInputQueue>>(new Map())
+  const terminalGestureInputInFlightRef = useRef<Set<string>>(new Set())
   const initialModesSeenRef = useRef<Set<string>>(new Set())
   const deviceTokenRef = useRef<string | null>(null)
   const clientRef = useRef<RpcClient | null>(null)
+  const connStateRef = useRef<ConnectionState>(connState)
   // Why: measured once from TerminalWebView on mount, then passed with every
   // subscribe call so the server can auto-fit the PTY to phone dimensions.
   const viewportRef = useRef<{ cols: number; rows: number } | null>(null)
@@ -1295,6 +1325,16 @@ export default function SessionScreen() {
     clientRef.current = client
   }, [client])
 
+  useEffect(() => {
+    connStateRef.current = connState
+    if (connState === 'connected') return
+    for (const queued of terminalGestureInputQueuesRef.current.values()) {
+      if (queued.timer) clearTimeout(queued.timer)
+    }
+    terminalGestureInputQueuesRef.current.clear()
+    terminalGestureInputInFlightRef.current.clear()
+  }, [connState])
+
   // Why: only clear terminal cache on actual unmount. Running it whenever
   // `client` changes — including the initial null → real-client transition
   // from useHostClient's async open path — would unsubscribe terminals and
@@ -1432,6 +1472,11 @@ export default function SessionScreen() {
     activeSessionTabTypeRef.current = null
     pendingActiveSessionTabIdRef.current = null
     pendingActiveTerminalHandleRef.current = null
+    for (const queued of terminalGestureInputQueuesRef.current.values()) {
+      if (queued.timer) clearTimeout(queued.timer)
+    }
+    terminalGestureInputQueuesRef.current.clear()
+    terminalGestureInputInFlightRef.current.clear()
     setActiveHandle(null)
     setTerminals([])
     terminalsRef.current = []
@@ -1654,6 +1699,13 @@ export default function SessionScreen() {
       terminalRefs.current.set(handle, ref)
     } else {
       terminalRefs.current.delete(handle)
+      terminalGestureInputBucketsRef.current.delete(handle)
+      const queued = terminalGestureInputQueuesRef.current.get(handle)
+      if (queued?.timer) {
+        clearTimeout(queued.timer)
+      }
+      terminalGestureInputQueuesRef.current.delete(handle)
+      terminalGestureInputInFlightRef.current.delete(handle)
     }
   }, [])
 
@@ -1754,6 +1806,132 @@ export default function SessionScreen() {
     }
   }
 
+  const allowTerminalGestureInput = useCallback(
+    (handle: string, sequenceCount: number): boolean => {
+      const now = Date.now()
+      const current = terminalGestureInputBucketsRef.current.get(handle) ?? {
+        tokens: TERMINAL_GESTURE_INPUT_BUCKET_CAPACITY,
+        lastRefillMs: now
+      }
+      const elapsedSeconds = Math.max(0, now - current.lastRefillMs) / 1000
+      const tokens = Math.min(
+        TERMINAL_GESTURE_INPUT_BUCKET_CAPACITY,
+        current.tokens + elapsedSeconds * TERMINAL_GESTURE_INPUT_REFILL_PER_SECOND
+      )
+
+      // Why: tokens represent terminal control sequences, not WebView messages;
+      // one legitimate gesture message may batch up to 32 wheel/key reports.
+      if (tokens < sequenceCount) {
+        terminalGestureInputBucketsRef.current.set(handle, { tokens, lastRefillMs: now })
+        return false
+      }
+
+      terminalGestureInputBucketsRef.current.set(handle, {
+        tokens: tokens - sequenceCount,
+        lastRefillMs: now
+      })
+      return true
+    },
+    []
+  )
+
+  const flushTerminalGestureInput = useCallback(async (handle: string) => {
+    const queued = terminalGestureInputQueuesRef.current.get(handle)
+    if (!queued) return
+    if (queued.timer) {
+      clearTimeout(queued.timer)
+      queued.timer = null
+    }
+    if (terminalGestureInputInFlightRef.current.has(handle)) return
+
+    terminalGestureInputQueuesRef.current.delete(handle)
+    const isActive =
+      handle === activeHandleRef.current && activeSessionTabTypeRef.current === 'terminal'
+    const isFresh = Date.now() - queued.lastUpdatedMs <= TERMINAL_GESTURE_INPUT_MAX_QUEUE_AGE_MS
+    const rpc = clientRef.current
+    if (!rpc || connStateRef.current !== 'connected' || !isActive || !isFresh) return
+
+    terminalGestureInputInFlightRef.current.add(handle)
+    try {
+      await rpc.sendRequest('terminal.send', {
+        terminal: handle,
+        text: queued.bytes,
+        enter: false,
+        ...(deviceTokenRef.current
+          ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } }
+          : {})
+      })
+    } catch {
+      // Transient failure
+    } finally {
+      terminalGestureInputInFlightRef.current.delete(handle)
+      const next = terminalGestureInputQueuesRef.current.get(handle)
+      if (next) {
+        if (Date.now() - next.lastUpdatedMs > TERMINAL_GESTURE_INPUT_MAX_QUEUE_AGE_MS) {
+          if (next.timer) clearTimeout(next.timer)
+          terminalGestureInputQueuesRef.current.delete(handle)
+        } else {
+          void flushTerminalGestureInput(handle)
+        }
+      }
+    }
+  }, [])
+
+  const enqueueTerminalGestureInput = useCallback(
+    (handle: string, bytes: string, sequenceCount: number) => {
+      const now = Date.now()
+      const current = terminalGestureInputQueuesRef.current.get(handle)
+      if (
+        current &&
+        current.sequenceCount + sequenceCount <= TERMINAL_GESTURE_INPUT_MAX_PENDING_SEQUENCES
+      ) {
+        current.bytes += bytes
+        current.sequenceCount += sequenceCount
+        current.lastUpdatedMs = now
+        return
+      }
+
+      if (current) {
+        if (current.timer) clearTimeout(current.timer)
+        if (!terminalGestureInputInFlightRef.current.has(handle)) {
+          void flushTerminalGestureInput(handle)
+        } else {
+          terminalGestureInputQueuesRef.current.delete(handle)
+        }
+      }
+
+      const queued: TerminalGestureInputQueue = {
+        bytes,
+        sequenceCount,
+        timer: null,
+        lastUpdatedMs: now
+      }
+      queued.timer = setTimeout(() => {
+        queued.timer = null
+        void flushTerminalGestureInput(handle)
+      }, TERMINAL_GESTURE_INPUT_FLUSH_DELAY_MS)
+      terminalGestureInputQueuesRef.current.set(handle, queued)
+    },
+    [flushTerminalGestureInput]
+  )
+
+  const handleTerminalInput = useCallback(
+    async (handle: string, bytes: string) => {
+      if (!client || connState !== 'connected' || bytes.length === 0) return
+      if (handle !== activeHandleRef.current || activeSessionTabTypeRef.current !== 'terminal')
+        return
+      const modes = ptyModesRef.current.get(handle)
+      // Why: WebView messages can become PTY input here. Only TUI scroll paths
+      // generate gesture input, and the bridge is rate-limited for SSH safety.
+      if (!modes?.altScreen && !isWheelMouseTrackingMode(modes?.mouseTrackingMode)) return
+      const sequenceCount = countTerminalGestureInputSequences(bytes)
+      if (sequenceCount == null) return
+      if (!allowTerminalGestureInput(handle, sequenceCount)) return
+      enqueueTerminalGestureInput(handle, bytes, sequenceCount)
+    },
+    [allowTerminalGestureInput, client, connState, enqueueTerminalGestureInput]
+  )
+
   async function handleClearTerminal(target: Terminal) {
     if (!client) return
     getTerminalRef(target.handle)?.clear()
@@ -1890,7 +2068,10 @@ export default function SessionScreen() {
       if (text.length === 0) return
       const modes = ptyModesRef.current.get(activeHandle) || {
         bracketedPasteMode: false,
-        altScreen: false
+        altScreen: false,
+        mouseTrackingMode: 'none',
+        sgrMouseMode: false,
+        sgrMousePixelsMode: false
       }
       const wrap = modes.bracketedPasteMode && !modes.altScreen
       // Why: strip embedded bracketed-paste markers from clipboard text so a
@@ -2335,6 +2516,7 @@ export default function SessionScreen() {
                 onModesChanged={handleModesChanged}
                 onKeyboardAvoidanceMetrics={handleKeyboardAvoidanceMetrics}
                 onHaptic={handleHaptic}
+                onTerminalInput={handleTerminalInput}
               />
             ))}
             {toastMessage && (
diff --git a/mobile/src/terminal/TerminalWebView.tsx b/mobile/src/terminal/TerminalWebView.tsx
index 0504c4523f2..e1afc25f0b0 100644
--- a/mobile/src/terminal/TerminalWebView.tsx
+++ b/mobile/src/terminal/TerminalWebView.tsx
@@ -4,9 +4,14 @@ import { WebView } from 'react-native-webview'
 import type { WebViewMessageEvent } from 'react-native-webview'
 import { colors } from '../theme/mobile-theme'
 
+type TerminalMouseTrackingMode = 'none' | 'x10' | 'vt200' | 'drag' | 'any'
+
 export type TerminalModes = {
   bracketedPasteMode: boolean
   altScreen: boolean
+  mouseTrackingMode: TerminalMouseTrackingMode
+  sgrMouseMode: boolean
+  sgrMousePixelsMode: boolean
 }
 
 export type TerminalKeyboardAvoidanceMetrics = {
@@ -22,6 +27,7 @@ export type TerminalSelectionEvents = {
   onModesChanged?: (modes: TerminalModes) => void
   onKeyboardAvoidanceMetrics?: (metrics: TerminalKeyboardAvoidanceMetrics) => void
   onHaptic?: (kind: 'selection' | 'success' | 'error' | 'edge-bump') => void
+  onTerminalInput?: (bytes: string) => void
 }
 
 export type TerminalWebViewHandle = {
@@ -178,6 +184,8 @@ const XTERM_HTML = `<!DOCTYPE html>
 (function() {
   var surface = document.getElementById('terminal-surface');
   var ESC = String.fromCharCode(27);
+  var C1_CSI = String.fromCharCode(155);
+  var PRIVATE_MODE_SCAN_TAIL_LIMIT = 4096;
   var term = null;
   var writeQueue = [];
   var writesDraining = false;
@@ -190,6 +198,10 @@ const XTERM_HTML = `<!DOCTYPE html>
   var initRows = 24;
   var terminalGeneration = 0;
   var activeAltScreenSnapshot = false;
+  var trackedMouseTrackingMode = 'none';
+  var sgrMouseMode = false;
+  var sgrMousePixelsMode = false;
+  var mouseModeScanTail = '';
   var handledMessageIds = [];
   // Why: after init() the initial scrollback applyFitScale may have run
   // against an empty buffer (or one without the widest line yet). Re-fit
@@ -406,6 +418,58 @@ const XTERM_HTML = `<!DOCTYPE html>
     return on > 0 ? data.slice(on) : data;
   }
 
+  function updateMouseModeFromData(data) {
+    if (typeof data !== 'string' || data.length === 0) return;
+    var input = mouseModeScanTail + data;
+    mouseModeScanTail = extractMouseModeScanTail(input);
+    var re = new RegExp(ESC + 'c|' + ESC + '\\\\[\\\\?([0-9;]+)([hl])|' + C1_CSI + '\\\\?([0-9;]+)([hl])', 'g');
+    var match;
+    while ((match = re.exec(input)) !== null) {
+      if (match[0] === ESC + 'c') {
+        trackedMouseTrackingMode = 'none';
+        sgrMouseMode = false;
+        sgrMousePixelsMode = false;
+        continue;
+      }
+      var enabled = (match[2] || match[4]) === 'h';
+      var params = (match[1] || match[3]).split(';');
+      for (var i = 0; i < params.length; i++) {
+        if (params[i] === '') continue;
+        var param = Number(params[i]);
+        if (!Number.isInteger(param)) continue;
+        if (param === 9) trackedMouseTrackingMode = enabled ? 'x10' : 'none';
+        if (param === 1000) trackedMouseTrackingMode = enabled ? 'vt200' : 'none';
+        if (param === 1002) trackedMouseTrackingMode = enabled ? 'drag' : 'none';
+        if (param === 1003) trackedMouseTrackingMode = enabled ? 'any' : 'none';
+        if (param === 1006) {
+          sgrMouseMode = enabled;
+          sgrMousePixelsMode = false;
+        }
+        if (param === 1016) {
+          sgrMouseMode = false;
+          sgrMousePixelsMode = enabled;
+        }
+      }
+    }
+  }
+
+  function extractMouseModeScanTail(input) {
+    var start = Math.max(input.lastIndexOf(ESC), input.lastIndexOf(C1_CSI));
+    if (start === -1) return '';
+    var tail = input.slice(start);
+    // Why: PTY/SSH chunks can split a long combined DECSET before the final h/l.
+    // Keep parser state far beyond normal mode lists while still bounding memory.
+    if (tail.length > PRIVATE_MODE_SCAN_TAIL_LIMIT) return '';
+    if (tail === ESC || tail === ESC + '[' || tail === C1_CSI) return tail;
+    if (tail.indexOf(ESC + '[?') === 0) {
+      return /^[0-9;]*$/.test(tail.slice(3)) ? tail : '';
+    }
+    if (tail.indexOf(C1_CSI + '?') === 0) {
+      return /^[0-9;]*$/.test(tail.slice(2)) ? tail : '';
+    }
+    return '';
+  }
+
   function pumpWrites(gen) {
     if (!ready || !term || writesDraining || gen !== terminalGeneration) return;
     var next = writeQueue.shift();
@@ -439,7 +503,21 @@ const XTERM_HTML = `<!DOCTYPE html>
     afterDrainCallbacks = [];
     initRows = rows || 24;
     firstDataPending = true;
+    mouseModeScanTail = '';
+    trackedMouseTrackingMode = 'none';
+    sgrMouseMode = false;
+    sgrMousePixelsMode = false;
+    lastEmittedModes = {
+      bracketedPasteMode: false,
+      altScreen: false,
+      mouseTrackingMode: 'none',
+      sgrMouseMode: false,
+      sgrMousePixelsMode: false
+    };
     var replayData = normalizeInitialData(initialData);
+    // Why: normalizeInitialData can discard pre-alt-screen bytes. Keep the
+    // mirrored modes aligned with exactly what this mobile xterm replays.
+    updateMouseModeFromData(replayData);
     activeAltScreenSnapshot = isAltScreenActive(replayData);
     var oldTerm = term;
     var oldSurface = surface;
@@ -453,6 +531,7 @@ const XTERM_HTML = `<!DOCTYPE html>
       nextSurface.style.top = '0';
       document.getElementById('terminal-container').appendChild(nextSurface);
       surface = nextSurface;
+      attachSurfaceEventHandlers(surface);
       oldSurface.removeAttribute('id');
     }
 
@@ -522,6 +601,7 @@ const XTERM_HTML = `<!DOCTYPE html>
   }
 
   function write(data) {
+    updateMouseModeFromData(data);
     writeQueue.push(data);
     pumpWrites(terminalGeneration);
     // Why: first live data chunk after init may widen the buffer past
@@ -623,7 +703,12 @@ const XTERM_HTML = `<!DOCTYPE html>
       writeQueue = [];
       afterDrainCallbacks = [];
       writesDraining = false;
+      mouseModeScanTail = '';
+      trackedMouseTrackingMode = 'none';
+      sgrMouseMode = false;
+      sgrMousePixelsMode = false;
       if (term) { term.clear(); term.reset(); }
+      emitModesIfChanged();
       resetEvictionCounter();
       if (selMode === 'select') {
         notify({ type: 'selection-evicted' });
@@ -715,13 +800,39 @@ const XTERM_HTML = `<!DOCTYPE html>
     if (!term) return;
     var bp = !!(term.modes && term.modes.bracketedPasteMode);
     var alt = false;
+    var mouseTrackingMode = getMouseTrackingMode();
     try { alt = term.buffer && term.buffer.active && term.buffer.active.type === 'alternate'; } catch (e) {}
-    if (bp !== lastEmittedModes.bracketedPasteMode || alt !== lastEmittedModes.altScreen) {
-      lastEmittedModes = { bracketedPasteMode: bp, altScreen: alt };
-      notify({ type: 'modes', bracketedPasteMode: bp, altScreen: alt });
+    if (
+      bp !== lastEmittedModes.bracketedPasteMode ||
+      alt !== lastEmittedModes.altScreen ||
+      mouseTrackingMode !== lastEmittedModes.mouseTrackingMode ||
+      sgrMouseMode !== lastEmittedModes.sgrMouseMode ||
+      sgrMousePixelsMode !== lastEmittedModes.sgrMousePixelsMode
+    ) {
+      lastEmittedModes = {
+        bracketedPasteMode: bp,
+        altScreen: alt,
+        mouseTrackingMode: mouseTrackingMode,
+        sgrMouseMode: sgrMouseMode,
+        sgrMousePixelsMode: sgrMousePixelsMode
+      };
+      notify({
+        type: 'modes',
+        bracketedPasteMode: bp,
+        altScreen: alt,
+        mouseTrackingMode: mouseTrackingMode,
+        sgrMouseMode: sgrMouseMode,
+        sgrMousePixelsMode: sgrMousePixelsMode
+      });
     }
   }
-  var lastEmittedModes = { bracketedPasteMode: false, altScreen: false };
+  var lastEmittedModes = {
+    bracketedPasteMode: false,
+    altScreen: false,
+    mouseTrackingMode: 'none',
+    sgrMouseMode: false,
+    sgrMousePixelsMode: false
+  };
 
   function emitKeyboardAvoidanceMetrics() {
     if (!term) return;
@@ -772,6 +883,147 @@ const XTERM_HTML = `<!DOCTYPE html>
     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) };
+  }
+
+  function isAlternateBufferActive() {
+    try {
+      return !!(term && term.buffer && term.buffer.active && term.buffer.active.type === 'alternate');
+    } catch (e) {
+      return false;
+    }
+  }
+
+  function getMouseTrackingMode() {
+    try {
+      if (term && term.modes && typeof term.modes.mouseTrackingMode === 'string') {
+        var mode = term.modes.mouseTrackingMode;
+        if (mode === 'x10' || mode === 'vt200' || mode === 'drag' || mode === 'any') return mode;
+        return 'none';
+      }
+    } catch (e) {}
+    if (
+      trackedMouseTrackingMode === 'x10' ||
+      trackedMouseTrackingMode === 'vt200' ||
+      trackedMouseTrackingMode === 'drag' ||
+      trackedMouseTrackingMode === 'any'
+    ) {
+      return trackedMouseTrackingMode;
+    }
+    return 'none';
+  }
+
+  function repeatSequence(sequence, count) {
+    var out = '';
+    for (var i = 0; i < count; i++) out += sequence;
+    return out;
+  }
+
+  function buildArrowScrollSequence(lines) {
+    var prefix = '[';
+    try {
+      if (term && term.modes && term.modes.applicationCursorKeysMode) prefix = 'O';
+    } catch (e) {}
+    return ESC + prefix + (lines < 0 ? 'A' : 'B');
+  }
+
+  function buildMouseWheelSequence(lines, clientX, clientY) {
+    var cell = viewportToMouseReportCell(clientX, clientY);
+    if (!cell) return '';
+    var eventCode = lines < 0 ? 64 : 65;
+    if (sgrMousePixelsMode) {
+      return ESC + '[<' + eventCode + ';' + cell.x + ';' + cell.y + 'M';
+    }
+    if (sgrMouseMode) {
+      // Why: xterm increments zero-based mouse cells before encoding reports.
+      return ESC + '[<' + eventCode + ';' + (cell.col + 1) + ';' + (cell.row + 1) + 'M';
+    }
+    // Why: xterm increments zero-based mouse cells before encoding reports.
+    var button = eventCode + 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. Fall back to keys for wide terminals.
+    if (button > 126 || col > 126 || row > 126) return '';
+    return ESC + '[M' + String.fromCharCode(button) + String.fromCharCode(col) + String.fromCharCode(row);
+  }
+
+  function isWheelMouseTrackingMode(mode) {
+    return mode !== 'none' && mode !== 'x10';
+  }
+
+  function buildMouseWheelScrollInput(lines, clientX, clientY) {
+    var count = Math.min(Math.abs(lines), 32);
+    if (count === 0) return '';
+    var sequence = buildMouseWheelSequence(lines, clientX, clientY);
+    if (!sequence) return '';
+    return repeatSequence(sequence, count);
+  }
+
+  function buildTuiScrollInput(lines, clientX, clientY) {
+    var count = Math.min(Math.abs(lines), 32);
+    if (count === 0) return '';
+    var mouseTrackingMode = getMouseTrackingMode();
+    var sequence = '';
+    if (isWheelMouseTrackingMode(mouseTrackingMode)) {
+      sequence = buildMouseWheelSequence(lines, clientX, clientY);
+    }
+    if (!sequence) sequence = buildArrowScrollSequence(lines);
+    return repeatSequence(sequence, count);
+  }
+
+  function routeScrollLines(lines, clientX, clientY) {
+    if (!term || lines === 0) return;
+    var mouseTrackingMode = getMouseTrackingMode();
+    var alternateBufferActive = isAlternateBufferActive();
+    if (isWheelMouseTrackingMode(mouseTrackingMode)) {
+      // Why: xterm sends wheel events to mouse-aware TUIs before considering
+      // scrollback, even if the app stays on the normal buffer.
+      var mouseInput = buildMouseWheelScrollInput(lines, clientX, clientY);
+      if (mouseInput) {
+        notify({ type: 'terminal-input', bytes: mouseInput });
+        return;
+      }
+      // Why: default mouse encoding can be unrepresentable in our ASCII-safe
+      // RPC path on wide terminals. Send bounded arrows instead of local
+      // scrollback/no-op while a mouse-aware app owns scroll gestures.
+      var fallbackInput = buildTuiScrollInput(lines, clientX, clientY);
+      if (fallbackInput) notify({ type: 'terminal-input', bytes: fallbackInput });
+      return;
+    }
+    if (alternateBufferActive) {
+      // Why: alternate-screen TUIs own their scroll state and xterm has no
+      // scrollback there, so mobile scroll gestures must become terminal input.
+      var input = buildTuiScrollInput(lines, clientX, clientY);
+      if (input) notify({ type: 'terminal-input', bytes: input });
+      return;
+    }
+    term.scrollLines(lines);
+  }
+
   function cellToViewportPx(col, absRow) {
     if (!term) return { x: 0, y: 0 };
     var cellW = getCellWidth();
@@ -1134,12 +1386,6 @@ const XTERM_HTML = `<!DOCTYPE html>
     } catch (err) {}
   });
 
-  // Why: event listeners are registered once here (not inside init()) so
-  // they don't accumulate on re-init. They close over the mutable 'term'
-  // variable, so they always reference the current terminal instance.
-  surface.addEventListener('mousedown', function(e) { e.preventDefault(); e.stopPropagation(); }, true);
-  surface.addEventListener('click', function(e) { e.preventDefault(); e.stopPropagation(); }, true);
-
   var ts = {
     lastX: 0, lastY: 0, lastTime: 0, velY: 0,
     accumDelta: 0, momentumId: null, isPinching: false,
@@ -1151,121 +1397,132 @@ const XTERM_HTML = `<!DOCTYPE html>
     return Math.sqrt(dx * dx + dy * dy);
   }
 
-  surface.addEventListener('touchstart', function(e) {
-    if (dispatcherShouldBlockSurface()) return;
-    if (ts.momentumId) {
-      cancelAnimationFrame(ts.momentumId);
-      ts.momentumId = null;
-    }
-    if (e.touches.length === 2) {
-      ts.isPinching = true;
-      ts.pinchDist = getDistance(e.touches[0], e.touches[1]);
-      ts.pinchScale = userScale;
-      var mx = (e.touches[0].clientX + e.touches[1].clientX) / 2;
-      var my = (e.touches[0].clientY + e.touches[1].clientY) / 2;
-      var total = getTotalScale();
-      ts.pinchSurfX = (mx - panX) / total;
-      ts.pinchSurfY = (my - panY) / total;
-    } else if (e.touches.length === 1) {
-      ts.isPinching = false;
-      ts.lastX = e.touches[0].clientX;
-      ts.lastY = e.touches[0].clientY;
-      ts.lastTime = Date.now();
-      ts.velY = 0;
-      ts.accumDelta = 0;
-    }
-  }, { capture: true, passive: true });
+  function attachSurfaceEventHandlers(targetSurface) {
+    if (!targetSurface || targetSurface.__orcaSurfaceHandlersAttached) return;
+    targetSurface.__orcaSurfaceHandlersAttached = true;
+    // Why: init() swaps in a new hidden surface to avoid flicker; each
+    // replacement needs gesture handlers or tab-switch replays stop scrolling.
+    targetSurface.addEventListener('mousedown', function(e) { e.preventDefault(); e.stopPropagation(); }, true);
+    targetSurface.addEventListener('click', function(e) { e.preventDefault(); e.stopPropagation(); }, true);
 
-  surface.addEventListener('touchmove', function(e) {
-    if (dispatcherShouldBlockSurface()) return;
-    if (!term) return;
-    e.preventDefault();
-    e.stopPropagation();
-
-    if (e.touches.length === 2) {
-      ts.isPinching = true;
-      var dist = getDistance(e.touches[0], e.touches[1]);
-      var mx = (e.touches[0].clientX + e.touches[1].clientX) / 2;
-      var my = (e.touches[0].clientY + e.touches[1].clientY) / 2;
-
-      var ratio = dist / ts.pinchDist;
-      userScale = Math.max(1, Math.min(5, ts.pinchScale * ratio));
-
-      var total = getTotalScale();
-      panX = mx - ts.pinchSurfX * total;
-      panY = my - ts.pinchSurfY * total;
-      clampPan();
-      updateTransform();
-
-    } else if (e.touches.length === 1 && !ts.isPinching) {
-      var x = e.touches[0].clientX;
-      var y = e.touches[0].clientY;
-      var now = Date.now();
-      var dt = now - ts.lastTime;
-
-      if (userScale > 1.05) {
-        panX += x - ts.lastX;
-        panY += y - ts.lastY;
-        clampPan();
-        updateTransform();
-      } else {
-        var deltaY = ts.lastY - y;
-        if (dt > 0) ts.velY = deltaY / dt;
-        ts.lastTime = now;
-        var effectiveCellH = getCellHeight() * currentScale;
-        ts.accumDelta += deltaY;
-        var lines = Math.trunc(ts.accumDelta / effectiveCellH);
-        if (lines !== 0) {
-          ts.accumDelta -= lines * effectiveCellH;
-          term.scrollLines(lines);
-        }
+    targetSurface.addEventListener('touchstart', function(e) {
+      if (dispatcherShouldBlockSurface()) return;
+      if (ts.momentumId) {
+        cancelAnimationFrame(ts.momentumId);
+        ts.momentumId = null;
       }
-      ts.lastX = x;
-      ts.lastY = y;
-    }
-  }, { capture: true, passive: false });
-
-  surface.addEventListener('touchend', function(e) {
-    if (dispatcherShouldBlockSurface()) return;
-    if (!term) return;
-
-    if (ts.isPinching && e.touches.length < 2) {
-      ts.isPinching = false;
-      if (userScale < 1.15) {
-        userScale = 1; panX = 0; panY = 0;
-        updateTransform();
-      }
-      if (e.touches.length === 1) {
+      if (e.touches.length === 2) {
+        ts.isPinching = true;
+        ts.pinchDist = getDistance(e.touches[0], e.touches[1]);
+        ts.pinchScale = userScale;
+        var mx = (e.touches[0].clientX + e.touches[1].clientX) / 2;
+        var my = (e.touches[0].clientY + e.touches[1].clientY) / 2;
+        var total = getTotalScale();
+        ts.pinchSurfX = (mx - panX) / total;
+        ts.pinchSurfY = (my - panY) / total;
+      } else if (e.touches.length === 1) {
+        ts.isPinching = false;
         ts.lastX = e.touches[0].clientX;
         ts.lastY = e.touches[0].clientY;
         ts.lastTime = Date.now();
         ts.velY = 0;
         ts.accumDelta = 0;
       }
-      return;
-    }
+    }, { capture: true, passive: true });
 
-    if (e.touches.length === 0 && userScale <= 1.05) {
-      var vel = ts.velY;
-      var FRICTION = 0.95;
-      var MIN_VEL = 0.02;
-      function momentumStep() {
-        vel *= FRICTION;
-        if (Math.abs(vel) < MIN_VEL) { ts.momentumId = null; return; }
-        var effectiveCellH = getCellHeight() * currentScale;
-        ts.accumDelta += vel * 16;
-        var lines = Math.trunc(ts.accumDelta / effectiveCellH);
-        if (lines !== 0) {
-          ts.accumDelta -= lines * effectiveCellH;
-          term.scrollLines(lines);
+    targetSurface.addEventListener('touchmove', function(e) {
+      if (dispatcherShouldBlockSurface()) return;
+      if (!term) return;
+      e.preventDefault();
+      e.stopPropagation();
+
+      if (e.touches.length === 2) {
+        ts.isPinching = true;
+        var dist = getDistance(e.touches[0], e.touches[1]);
+        var mx = (e.touches[0].clientX + e.touches[1].clientX) / 2;
+        var my = (e.touches[0].clientY + e.touches[1].clientY) / 2;
+
+        var ratio = dist / ts.pinchDist;
+        userScale = Math.max(1, Math.min(5, ts.pinchScale * ratio));
+
+        var total = getTotalScale();
+        panX = mx - ts.pinchSurfX * total;
+        panY = my - ts.pinchSurfY * total;
+        clampPan();
+        updateTransform();
+
+      } else if (e.touches.length === 1 && !ts.isPinching) {
+        var x = e.touches[0].clientX;
+        var y = e.touches[0].clientY;
+        var now = Date.now();
+        var dt = now - ts.lastTime;
+
+        if (userScale > 1.05) {
+          panX += x - ts.lastX;
+          panY += y - ts.lastY;
+          clampPan();
+          updateTransform();
+        } else {
+          var deltaY = ts.lastY - y;
+          if (dt > 0) ts.velY = deltaY / dt;
+          ts.lastTime = now;
+          var effectiveCellH = getCellHeight() * currentScale;
+          ts.accumDelta += deltaY;
+          var lines = Math.trunc(ts.accumDelta / effectiveCellH);
+          if (lines !== 0) {
+            ts.accumDelta -= lines * effectiveCellH;
+            routeScrollLines(lines, x, y);
+          }
         }
-        ts.momentumId = requestAnimationFrame(momentumStep);
+        ts.lastX = x;
+        ts.lastY = y;
       }
-      if (Math.abs(vel) > MIN_VEL) {
-        ts.momentumId = requestAnimationFrame(momentumStep);
+    }, { capture: true, passive: false });
+
+    targetSurface.addEventListener('touchend', function(e) {
+      if (dispatcherShouldBlockSurface()) return;
+      if (!term) return;
+
+      if (ts.isPinching && e.touches.length < 2) {
+        ts.isPinching = false;
+        if (userScale < 1.15) {
+          userScale = 1; panX = 0; panY = 0;
+          updateTransform();
+        }
+        if (e.touches.length === 1) {
+          ts.lastX = e.touches[0].clientX;
+          ts.lastY = e.touches[0].clientY;
+          ts.lastTime = Date.now();
+          ts.velY = 0;
+          ts.accumDelta = 0;
+        }
+        return;
       }
-    }
-  }, { capture: true, passive: true });
+
+      if (e.touches.length === 0 && userScale <= 1.05) {
+        var vel = ts.velY;
+        var FRICTION = 0.95;
+        var MIN_VEL = 0.02;
+        function momentumStep() {
+          vel *= FRICTION;
+          if (Math.abs(vel) < MIN_VEL) { ts.momentumId = null; return; }
+          var effectiveCellH = getCellHeight() * currentScale;
+          ts.accumDelta += vel * 16;
+          var lines = Math.trunc(ts.accumDelta / effectiveCellH);
+          if (lines !== 0) {
+            ts.accumDelta -= lines * effectiveCellH;
+            routeScrollLines(lines, ts.lastX, ts.lastY);
+          }
+          ts.momentumId = requestAnimationFrame(momentumStep);
+        }
+        if (Math.abs(vel) > MIN_VEL) {
+          ts.momentumId = requestAnimationFrame(momentumStep);
+        }
+      }
+    }, { capture: true, passive: true });
+  }
+
+  attachSurfaceEventHandlers(surface);
 
   window.addEventListener('message', function(e) {
     try {
@@ -1310,7 +1567,8 @@ export const TerminalWebView = forwardRef<TerminalWebViewHandle, Props>(function
     onSelectionEvicted,
     onModesChanged,
     onKeyboardAvoidanceMetrics,
-    onHaptic
+    onHaptic,
+    onTerminalInput
   },
   ref
 ) {
@@ -1395,10 +1653,23 @@ export const TerminalWebView = forwardRef<TerminalWebViewHandle, Props>(function
       } else if (msg.type === 'selection-evicted') {
         onSelectionEvicted?.()
       } else if (msg.type === 'modes') {
+        const mouseTrackingMode =
+          msg.mouseTrackingMode === 'x10' ||
+          msg.mouseTrackingMode === 'vt200' ||
+          msg.mouseTrackingMode === 'drag' ||
+          msg.mouseTrackingMode === 'any'
+            ? msg.mouseTrackingMode
+            : 'none'
         onModesChanged?.({
           bracketedPasteMode: !!msg.bracketedPasteMode,
-          altScreen: !!msg.altScreen
+          altScreen: !!msg.altScreen,
+          mouseTrackingMode,
+          sgrMouseMode: !!msg.sgrMouseMode,
+          sgrMousePixelsMode: !!msg.sgrMousePixelsMode
         })
+      } else if (msg.type === 'terminal-input') {
+        const bytes = typeof msg.bytes === 'string' ? msg.bytes : ''
+        if (bytes.length > 0) onTerminalInput?.(bytes)
       } else if (msg.type === 'keyboard-avoidance-metrics') {
         const cursorY = typeof msg.cursorY === 'number' ? msg.cursorY : 0
         const rows = typeof msg.rows === 'number' ? msg.rows : 0
@@ -1430,7 +1701,8 @@ export const TerminalWebView = forwardRef<TerminalWebViewHandle, Props>(function
       onSelectionEvicted,
       onModesChanged,
       onKeyboardAvoidanceMetrics,
-      onHaptic
+      onHaptic,
+      onTerminalInput
     ]
   )
 
diff --git a/mobile/src/terminal/terminal-gesture-input.test.ts b/mobile/src/terminal/terminal-gesture-input.test.ts
new file mode 100644
index 00000000000..48ad19e10bd
--- /dev/null
+++ b/mobile/src/terminal/terminal-gesture-input.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import {
+  countTerminalGestureInputSequences,
+  isTerminalGestureInput
+} from './terminal-gesture-input'
+
+const ESC = '\x1b'
+
+describe('isTerminalGestureInput', () => {
+  it('accepts repeated arrow scroll sequences', () => {
+    expect(isTerminalGestureInput(`${ESC}[A${ESC}[B${ESC}OA${ESC}OB`)).toBe(true)
+    expect(isTerminalGestureInput(`${ESC}[A`.repeat(32))).toBe(true)
+    expect(countTerminalGestureInputSequences(`${ESC}[A${ESC}[B${ESC}OA${ESC}OB`)).toBe(4)
+    expect(countTerminalGestureInputSequences(`${ESC}[A`.repeat(32))).toBe(32)
+  })
+
+  it('accepts repeated SGR wheel sequences', () => {
+    expect(isTerminalGestureInput(`${ESC}[<64;1;1M${ESC}[<65;120;40M`)).toBe(true)
+    expect(isTerminalGestureInput(`${ESC}[<64;0;0M`)).toBe(true)
+  })
+
+  it('accepts repeated default mouse wheel sequences', () => {
+    expect(
+      isTerminalGestureInput(
+        `${ESC}[M${String.fromCharCode(96, 97, 33)}${ESC}[M${String.fromCharCode(97, 126, 126)}`
+      )
+    ).toBe(true)
+  })
+
+  it('rejects shell text and other terminal input', () => {
+    expect(isTerminalGestureInput('rm -rf .\r')).toBe(false)
+    expect(isTerminalGestureInput(`${ESC}[200~paste${ESC}[201~`)).toBe(false)
+  })
+
+  it('rejects malformed or oversized sequences', () => {
+    expect(isTerminalGestureInput(`${ESC}[<63;0;1M`)).toBe(false)
+    expect(isTerminalGestureInput(`${ESC}[M` + String.fromCharCode(97, 32, 33))).toBe(false)
+    expect(isTerminalGestureInput(`${ESC}[A`.repeat(33))).toBe(false)
+    expect(countTerminalGestureInputSequences(`${ESC}[A`.repeat(33))).toBeNull()
+    expect(isTerminalGestureInput(`${ESC}[A`.repeat(700))).toBe(false)
+  })
+})
diff --git a/mobile/src/terminal/terminal-gesture-input.ts b/mobile/src/terminal/terminal-gesture-input.ts
new file mode 100644
index 00000000000..15b3a9d11df
--- /dev/null
+++ b/mobile/src/terminal/terminal-gesture-input.ts
@@ -0,0 +1,71 @@
+const ESC = '\x1b'
+const MAX_TERMINAL_GESTURE_INPUT_LENGTH = 2048
+const MAX_TERMINAL_GESTURE_INPUT_SEQUENCES = 32
+const SGR_MOUSE_WHEEL_SEQUENCE_RE = new RegExp(`^${ESC}\\[<(64|65);[0-9]{1,4};[0-9]{1,4}M$`)
+
+function isDefaultMouseWheelSequence(bytes: string, offset: number): number | null {
+  if (!bytes.startsWith(`${ESC}[M`, offset) || offset + 6 > bytes.length) {
+    return null
+  }
+  const button = bytes.charCodeAt(offset + 3)
+  const col = bytes.charCodeAt(offset + 4)
+  const row = bytes.charCodeAt(offset + 5)
+  if ((button === 96 || button === 97) && col >= 33 && col <= 126 && row >= 33 && row <= 126) {
+    return offset + 6
+  }
+  return null
+}
+
+function isSgrMouseWheelSequence(bytes: string, offset: number): number | null {
+  if (!bytes.startsWith(`${ESC}[<`, offset)) {
+    return null
+  }
+  const end = bytes.indexOf('M', offset)
+  if (end === -1) {
+    return null
+  }
+  const sequence = bytes.slice(offset, end + 1)
+  return SGR_MOUSE_WHEEL_SEQUENCE_RE.test(sequence) ? end + 1 : null
+}
+
+function isArrowScrollSequence(bytes: string, offset: number): number | null {
+  const sequence = bytes.slice(offset, offset + 3)
+  if (
+    sequence === `${ESC}[A` ||
+    sequence === `${ESC}[B` ||
+    sequence === `${ESC}OA` ||
+    sequence === `${ESC}OB`
+  ) {
+    return offset + 3
+  }
+  return null
+}
+
+export function countTerminalGestureInputSequences(bytes: string): number | null {
+  if (bytes.length === 0 || bytes.length > MAX_TERMINAL_GESTURE_INPUT_LENGTH) {
+    return null
+  }
+
+  let offset = 0
+  let sequenceCount = 0
+  while (offset < bytes.length) {
+    const next =
+      isArrowScrollSequence(bytes, offset) ??
+      isSgrMouseWheelSequence(bytes, offset) ??
+      isDefaultMouseWheelSequence(bytes, offset)
+
+    if (next == null) {
+      return null
+    }
+    sequenceCount += 1
+    if (sequenceCount > MAX_TERMINAL_GESTURE_INPUT_SEQUENCES) {
+      return null
+    }
+    offset = next
+  }
+  return sequenceCount
+}
+
+export function isTerminalGestureInput(bytes: string): boolean {
+  return countTerminalGestureInputSequences(bytes) != null
+}
diff --git a/src/main/daemon/headless-emulator.test.ts b/src/main/daemon/headless-emulator.test.ts
index fd4a4a15c5c..5e73efd57c5 100644
--- a/src/main/daemon/headless-emulator.test.ts
+++ b/src/main/daemon/headless-emulator.test.ts
@@ -160,6 +160,162 @@ describe('HeadlessEmulator', () => {
       await emulator.write('\x1b[?1049l')
       expect(emulator.getSnapshot().modes.alternateScreen).toBe(false)
     })
+
+    it('tracks mouse reporting mode', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+      expect(emulator.getSnapshot().modes.mouseTracking).toBe(false)
+
+      await emulator.write('\x1b[?1002;1006h')
+      expect(emulator.getSnapshot().modes.mouseTracking).toBe(true)
+      expect(emulator.getSnapshot().modes.mouseTrackingMode).toBe('drag')
+      expect(emulator.getSnapshot().modes.sgrMouseMode).toBe(true)
+      expect(emulator.getSnapshot().modes.sgrMousePixelsMode).toBe(false)
+
+      await emulator.write('\x1b[?1002;1006l')
+      expect(emulator.getSnapshot().modes.mouseTracking).toBe(false)
+      expect(emulator.getSnapshot().modes.sgrMouseMode).toBe(false)
+    })
+
+    it('tracks split SGR mouse reporting sequences', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x1b[?1002;100')
+      await emulator.write('6h')
+      expect(emulator.getSnapshot().modes.mouseTrackingMode).toBe('drag')
+      expect(emulator.getSnapshot().modes.sgrMouseMode).toBe(true)
+
+      await emulator.write('\x1b[?100')
+      await emulator.write('6l')
+      expect(emulator.getSnapshot().modes.sgrMouseMode).toBe(false)
+    })
+
+    it('tracks long split private mouse mode sequences', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+      const fillerModes = Array.from({ length: 40 }, (_, i) => String(3000 + i)).join(';')
+
+      await emulator.write(`\x1b[?1002;${fillerModes};100`)
+      await emulator.write('6h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTrackingMode).toBe('drag')
+      expect(snapshot.modes.sgrMouseMode).toBe(true)
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1006h')
+    })
+
+    it('tracks private mouse modes with leading zero params', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x1b[?01002;01006h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTrackingMode).toBe('drag')
+      expect(snapshot.modes.sgrMouseMode).toBe(true)
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1006h')
+    })
+
+    it('tracks C1 CSI private mouse mode sequences', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x9b?1002;1006h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTrackingMode).toBe('drag')
+      expect(snapshot.modes.sgrMouseMode).toBe(true)
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1006h')
+    })
+
+    it('tracks split C1 CSI private mouse mode sequences', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x9b?1002;100')
+      await emulator.write('6h')
+      await emulator.write('\x9b?1002l')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTracking).toBe(false)
+      expect(snapshot.modes.sgrMouseMode).toBe(true)
+      expect(snapshot.rehydrateSequences).not.toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1006h')
+    })
+
+    it('tracks C1 CSI split before private marker', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x9b')
+      await emulator.write('?1002;1006h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTrackingMode).toBe('drag')
+      expect(snapshot.modes.sgrMouseMode).toBe(true)
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1006h')
+    })
+
+    it('does not retain complete private CSI queries as scan tail', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x1b[?2004$p')
+      await emulator.write('1002;1006h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTracking).toBe(false)
+      expect(snapshot.modes.sgrMouseMode).toBe(false)
+      expect(snapshot.rehydrateSequences).not.toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).not.toContain('\x1b[?1006h')
+    })
+
+    it('does not expose mouse modes before xterm applies the same write', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      const writePromise = emulator.write('\x1b[?1049h\x1b[?1002;1006h')
+      const snapshot = emulator.getSnapshot()
+      await writePromise
+
+      expect(snapshot.modes.alternateScreen).toBe(false)
+      expect(snapshot.modes.mouseTracking).toBe(false)
+      expect(snapshot.modes.sgrMouseMode).toBe(false)
+      expect(snapshot.rehydrateSequences).toBe('')
+
+      const after = emulator.getSnapshot()
+      expect(after.modes.alternateScreen).toBe(true)
+      expect(after.modes.mouseTrackingMode).toBe('drag')
+      expect(after.modes.sgrMouseMode).toBe(true)
+      expect(after.rehydrateSequences).toContain('\x1b[?1049h')
+      expect(after.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(after.rehydrateSequences).toContain('\x1b[?1006h')
+    })
+
+    it('clears SGR mouse reporting on full terminal reset', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x1b[?1002;1006h')
+      await emulator.write('\x1bc')
+      await emulator.write('\x1b[?1002h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTrackingMode).toBe('drag')
+      expect(snapshot.modes.sgrMouseMode).toBe(false)
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).not.toContain('\x1b[?1006h')
+    })
+
+    it('tracks SGR-pixels mouse reporting as a separate active encoding', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+
+      await emulator.write('\x1b[?1002;1006h')
+      await emulator.write('\x1b[?1016h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTrackingMode).toBe('drag')
+      expect(snapshot.modes.sgrMouseMode).toBe(false)
+      expect(snapshot.modes.sgrMousePixelsMode).toBe(true)
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1016h')
+      expect(snapshot.rehydrateSequences).not.toContain('\x1b[?1006h')
+    })
   })
 
   describe('rehydration sequences', () => {
@@ -178,6 +334,41 @@ describe('HeadlessEmulator', () => {
       const snapshot = emulator.getSnapshot()
       expect(snapshot.rehydrateSequences).toBe('')
     })
+
+    it('rehydrates mouse reporting after alternate screen activation', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+      await emulator.write('\x1b[?1049h\x1b[?1002;1006h')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1049h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1002h')
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1006h')
+      expect(snapshot.rehydrateSequences.indexOf('\x1b[?1049h')).toBeLessThan(
+        snapshot.rehydrateSequences.indexOf('\x1b[?1002h')
+      )
+    })
+
+    it('preserves mouse modes after mobile normalizes an alternate-screen replay', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+      await emulator.write('normal buffer\r\n\x1b[?1049h\x1b[?2004h\x1b[?1002;1006halternate')
+      const snapshot = emulator.getSnapshot()
+      const payload = snapshot.rehydrateSequences + snapshot.snapshotAnsi
+      expect(payload.split('\x1b[?1049h')).toHaveLength(2)
+      expect(payload.slice(payload.lastIndexOf('\x1b[?1049h'))).toContain('\x1b[?1002h')
+      expect(payload.slice(payload.lastIndexOf('\x1b[?1049h'))).toContain('\x1b[?1006h')
+    })
+
+    it('rehydrates mouse encoding independently from reporting mode', async () => {
+      emulator = new HeadlessEmulator({ cols: 80, rows: 24 })
+      await emulator.write('\x1b[?1002;1006h')
+      await emulator.write('\x1b[?1002l')
+
+      const snapshot = emulator.getSnapshot()
+      expect(snapshot.modes.mouseTracking).toBe(false)
+      expect(snapshot.modes.sgrMouseMode).toBe(true)
+      expect(snapshot.rehydrateSequences).toContain('\x1b[?1006h')
+      expect(snapshot.rehydrateSequences).not.toContain('\x1b[?1002h')
+    })
   })
 
   describe('dispose', () => {
diff --git a/src/main/daemon/headless-emulator.ts b/src/main/daemon/headless-emulator.ts
index 12645ec1e0a..90155072a94 100644
--- a/src/main/daemon/headless-emulator.ts
+++ b/src/main/daemon/headless-emulator.ts
@@ -14,6 +14,10 @@ export type HeadlessSnapshotOptions = {
 }
 
 const DEFAULT_SCROLLBACK = 5000
+// Why: PTY/SSH chunks can split a long combined DECSET before the final h/l.
+// Keep parser state far beyond normal mode lists while still bounding memory.
+const PRIVATE_MODE_SCAN_TAIL_LIMIT = 4096
+type MouseTrackingMode = NonNullable<TerminalModes['mouseTrackingMode']>
 
 function parseFileUriPath(uri: string): string | null {
   try {
@@ -47,6 +51,10 @@ export class HeadlessEmulator {
   private terminal: Terminal
   private serializer: SerializeAddon
   private cwd: string | null = null
+  private privateModeScanTail = ''
+  private mouseTrackingMode: MouseTrackingMode = 'none'
+  private sgrMouseMode = false
+  private sgrMousePixelsMode = false
   private disposed = false
 
   constructor(opts: HeadlessEmulatorOptions) {
@@ -80,7 +88,12 @@ export class HeadlessEmulator {
 
     this.scanOsc7(data)
     return new Promise<void>((resolve) => {
-      this.terminal.write(data, resolve)
+      this.terminal.write(data, () => {
+        // Why: snapshots combine serialized xterm state with mirrored mouse
+        // modes. Commit the mirror only after xterm has parsed the same bytes.
+        this.scanPrivateModes(data)
+        resolve()
+      })
     })
   }
 
@@ -93,8 +106,12 @@ export class HeadlessEmulator {
 
   getSnapshot(opts: HeadlessSnapshotOptions = {}): TerminalSnapshot {
     const modes = this.getModes()
+    const snapshotAnsi = this.normalizeSnapshotAnsiForModes(
+      this.serializer.serialize({ scrollback: opts.scrollbackRows }),
+      modes
+    )
     return {
-      snapshotAnsi: this.serializer.serialize({ scrollback: opts.scrollbackRows }),
+      snapshotAnsi,
       scrollbackAnsi: '',
       rehydrateSequences: this.buildRehydrateSequences(modes),
       cwd: this.cwd,
@@ -133,6 +150,93 @@ export class HeadlessEmulator {
     }
   }
 
+  private scanPrivateModes(data: string): void {
+    const input = this.privateModeScanTail + data
+    this.privateModeScanTail = this.extractPrivateModeScanTail(input)
+    // oxlint-disable-next-line no-control-regex -- terminal escape sequences require control chars
+    const privateModeRe = /\x1bc|\x1b\[\?([0-9;]+)([hl])|\x9b\?([0-9;]+)([hl])/g
+    let match: RegExpExecArray | null
+    while ((match = privateModeRe.exec(input)) !== null) {
+      if (match[0] === '\x1bc') {
+        this.mouseTrackingMode = 'none'
+        this.sgrMouseMode = false
+        this.sgrMousePixelsMode = false
+        continue
+      }
+      const params = match[1] ?? match[3]
+      const enabled = (match[2] ?? match[4]) === 'h'
+      for (const rawParam of params.split(';')) {
+        if (rawParam === '') {
+          continue
+        }
+        const param = Number(rawParam)
+        if (!Number.isInteger(param)) {
+          continue
+        }
+        if (param === 9) {
+          this.mouseTrackingMode = enabled ? 'x10' : 'none'
+        }
+        if (param === 1000) {
+          this.mouseTrackingMode = enabled ? 'vt200' : 'none'
+        }
+        if (param === 1002) {
+          this.mouseTrackingMode = enabled ? 'drag' : 'none'
+        }
+        if (param === 1003) {
+          this.mouseTrackingMode = enabled ? 'any' : 'none'
+        }
+        if (param === 1006) {
+          this.sgrMouseMode = enabled
+          this.sgrMousePixelsMode = false
+        }
+        if (param === 1016) {
+          this.sgrMouseMode = false
+          this.sgrMousePixelsMode = enabled
+        }
+      }
+    }
+  }
+
+  private extractPrivateModeScanTail(input: string): string {
+    const start = Math.max(input.lastIndexOf('\x1b'), input.lastIndexOf('\x9b'))
+    if (start === -1) {
+      return ''
+    }
+    const tail = input.slice(start)
+    if (tail.length > PRIVATE_MODE_SCAN_TAIL_LIMIT) {
+      return ''
+    }
+    if (tail === '\x1b' || tail === '\x1b[' || tail === '\x9b') {
+      return tail
+    }
+    if (tail.startsWith('\x1b[?')) {
+      return this.isIncompletePrivateModeParams(tail.slice(3)) ? tail : ''
+    }
+    if (tail.startsWith('\x9b?')) {
+      return this.isIncompletePrivateModeParams(tail.slice(2)) ? tail : ''
+    }
+    return ''
+  }
+
+  private isIncompletePrivateModeParams(params: string): boolean {
+    return /^[0-9;]*$/.test(params)
+  }
+
+  private normalizeSnapshotAnsiForModes(snapshotAnsi: string, modes: TerminalModes): string {
+    if (!modes.alternateScreen) {
+      return snapshotAnsi
+    }
+    const alternateScreenMarker = '\x1b[?1049h'
+    const start = snapshotAnsi.lastIndexOf(alternateScreenMarker)
+    if (start === -1) {
+      return snapshotAnsi
+    }
+    // Why: rehydrateSequences already enters the alternate screen and restores
+    // mouse modes. Dropping SerializeAddon's duplicate ?1049h keeps mobile's
+    // "slice from last alt-screen marker" replay from discarding those modes.
+    return snapshotAnsi.slice(start + alternateScreenMarker.length)
+  }
+
   private parseOsc7Uri(uri: string): void {
     const parsed = parseFileUriPath(uri)
     if (parsed) {
@@ -142,9 +246,13 @@ export class HeadlessEmulator {
 
   private getModes(): TerminalModes {
     const buffer = this.terminal.buffer.active
+    const mouseTrackingMode = this.mouseTrackingMode
     return {
       bracketedPaste: this.terminal.modes.bracketedPasteMode,
-      mouseTracking: this.terminal.modes.mouseTrackingMode !== 'none',
+      mouseTracking: mouseTrackingMode !== 'none',
+      mouseTrackingMode,
+      sgrMouseMode: this.sgrMouseMode,
+      sgrMousePixelsMode: this.sgrMousePixelsMode,
       applicationCursor:
         buffer.type === 'normal' ? this.terminal.modes.applicationCursorKeysMode : false,
       alternateScreen: buffer.type === 'alternate'
@@ -153,14 +261,37 @@ export class HeadlessEmulator {
 
   private buildRehydrateSequences(modes: TerminalModes): string {
     const seqs: string[] = []
+    if (modes.alternateScreen) {
+      seqs.push('\x1b[?1049h')
+    }
     if (modes.bracketedPaste) {
       seqs.push('\x1b[?2004h')
     }
     if (modes.applicationCursor) {
       seqs.push('\x1b[?1h')
     }
-    if (modes.alternateScreen) {
-      seqs.push('\x1b[?1049h')
+    // Why: mobile alt-screen scroll gestures need xterm's mouse mode restored
+    // from cold snapshots; OpenCode/OpenTUI enables scrollable panes this way.
+    switch (modes.mouseTracking ? (modes.mouseTrackingMode ?? 'vt200') : 'none') {
+      case 'x10':
+        seqs.push('\x1b[?9h')
+        break
+      case 'vt200':
+        seqs.push('\x1b[?1000h')
+        break
+      case 'drag':
+        seqs.push('\x1b[?1002h')
+        break
+      case 'any':
+        seqs.push('\x1b[?1003h')
+        break
+    }
+    // Why: xterm tracks the mouse protocol and SGR encoding as independent
+    // modes, so snapshots must preserve the encoding even when reporting is off.
+    if (modes.sgrMousePixelsMode) {
+      seqs.push('\x1b[?1016h')
+    } else if (modes.sgrMouseMode) {
+      seqs.push('\x1b[?1006h')
     }
     return seqs.join('')
   }
diff --git a/src/main/daemon/types.ts b/src/main/daemon/types.ts
index 7808225393f..a88fb46c659 100644
--- a/src/main/daemon/types.ts
+++ b/src/main/daemon/types.ts
@@ -1,10 +1,10 @@
 // ─── Protocol Version ────────────────────────────────────────────────
 // Why: daemons can survive app updates. Bump for IPC wire-shape changes, or
 // when daemon-baked behavior cannot be delivered by on-disk wrapper refresh.
-// Why: bumped from 5 -> 6 for OSC 133 shell wrapper changes layered on top of
-// OpenCode/Pi overlay restoration, both of which are baked into daemon spawns.
-export const PROTOCOL_VERSION = 6
-export const PREVIOUS_DAEMON_PROTOCOL_VERSIONS = [1, 2, 3, 4, 5] as const
+// Why: bumped from 6 -> 7 so existing daemons restart with the headless
+// emulator's mouse-mode snapshot tracking for mobile alternate-screen TUIs.
+export const PROTOCOL_VERSION = 7
+export const PREVIOUS_DAEMON_PROTOCOL_VERSIONS = [1, 2, 3, 4, 5, 6] as const
 
 // ─── Session State Machine ──────────────────────────────────────────
 export type SessionState = 'created' | 'spawning' | 'running' | 'exiting' | 'exited'
@@ -28,6 +28,9 @@ export type TerminalSnapshot = {
 export type TerminalModes = {
   bracketedPaste: boolean
   mouseTracking: boolean
+  mouseTrackingMode?: 'none' | 'x10' | 'vt200' | 'drag' | 'any'
+  sgrMouseMode?: boolean
+  sgrMousePixelsMode?: boolean
   applicationCursor: boolean
   alternateScreen: boolean
 }
diff --git a/src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx b/src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx
index 1fc614f9acb..f3bb8066ec0 100644
--- a/src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx
+++ b/src/renderer/src/components/sidebar/use-worktree-activity-status.test.tsx
@@ -1,9 +1,12 @@
 import { renderToStaticMarkup } from 'react-dom/server'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
 import type { TerminalTab } from '../../../../shared/types'
 import { useWorktreeActivityStatus } from './use-worktree-activity-status'
 
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+
 type MockState = {
   tabsByWorktree: Record<string, TerminalTab[]>
   browserTabsByWorktree: Record<string, { id: string }[]>
@@ -71,6 +74,7 @@ describe('useWorktreeActivityStatus', () => {
 
   it('keeps a restored offscreen working agent yellow from the hook snapshot', () => {
     const worktreeId = 'repo1::/path/wt1'
+    const paneKey = makePaneKey('tab-1', LEAF_ID)
     mockState = {
       ...mockState,
       tabsByWorktree: {
@@ -80,7 +84,7 @@ describe('useWorktreeActivityStatus', () => {
         'tab-1': ['pty-1']
       },
       agentStatusByPaneKey: {
-        'tab-1:1': makeAgentStatusEntry({ paneKey: 'tab-1:1', state: 'working' })
+        [paneKey]: makeAgentStatusEntry({ paneKey, state: 'working' })
       }
     }
 
diff --git a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
index 882fb13df96..66ffb16bc47 100644
--- a/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-activity-status.ts
@@ -49,7 +49,7 @@ export function useWorktreeActivityStatus(worktreeId: string): WorktreeStatus {
             done = true
           }
         }
-        for (const unsupported of Object.values(s.migrationUnsupportedByPtyId)) {
+        for (const unsupported of Object.values(s.migrationUnsupportedByPtyId ?? {})) {
           const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
           if (!entry) {
             continue
diff --git a/src/renderer/src/components/terminal-pane/terminal-appearance.ts b/src/renderer/src/components/terminal-pane/terminal-appearance.ts
index b9b87976070..570dc848ec1 100644
--- a/src/renderer/src/components/terminal-pane/terminal-appearance.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-appearance.ts
@@ -78,9 +78,9 @@ export function installMode2031Handlers(deps: Mode2031HandlerDeps): IDisposable[
         // scrollback (`SerializeAddon.serialize()`) never contain `?2031`:
         // SerializeAddon's _serializeModes whitelists only ?1h/?66h/?2004h/
         // [4h/?6h/?45h/?1004h/?7l/mouse modes/?25l, and buildRehydrateSequences
-        // emits only ?2004h/?1h/?1049h. If xterm ever adds ?2031 to that
-        // whitelist, this guard would start suppressing legitimate
-        // subscribes during snapshot reattach — revisit then.
+        // emits only ?1049h/?2004h/?1h/mouse reporting modes. If xterm ever
+        // adds ?2031 to that whitelist, this guard would start suppressing
+        // legitimate subscribes during snapshot reattach — revisit then.
         if (deps.isReplaying()) {
           return false
         }

From ac1a4e44e9bbda541ef6b47873480e29250653aa Mon Sep 17 00:00:00 2001
From: Honglei Liu <ppuliu@users.noreply.github.com>
Date: Fri, 15 May 2026 13:17:38 -0700
Subject: [PATCH 66/82] fix(sidebar): order repo headers by recency in
 Recent/Smart sort

---
 .../src/components/sidebar/WorktreeList.tsx   | 42 +++++++---
 .../src/components/sidebar/smart-sort.ts      |  2 +-
 .../sidebar/worktree-list-groups.test.ts      | 79 ++++++++++++++++++-
 .../sidebar/worktree-list-groups.ts           | 21 +++--
 4 files changed, 124 insertions(+), 20 deletions(-)

diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index be729c1a154..e44df69240e 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -30,10 +30,12 @@ import { track } from '@/lib/telemetry'
 import { tabHasLivePty } from '@/lib/tab-has-live-pty'
 import {
   type GroupHeaderRow,
+  type RepoGroupOrdering,
   type Row,
   type WorktreeGroupBy,
   PINNED_GROUP_KEY,
   buildRows,
+  getRepoGroupOrdering,
   getGroupKeyForWorktree
 } from './worktree-list-groups'
 import {
@@ -93,6 +95,7 @@ type VirtualizedWorktreeViewportProps = {
   rows: Row[]
   activeWorktreeId: string | null
   groupBy: WorktreeGroupBy
+  repoGroupOrdering: RepoGroupOrdering
   toggleGroup: (key: string) => void
   collapsedGroups: Set<string>
   handleCreateForRepo: (repoId: string) => void
@@ -132,6 +135,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
   rows,
   activeWorktreeId,
   groupBy,
+  repoGroupOrdering,
   toggleGroup,
   collapsedGroups,
   handleCreateForRepo,
@@ -156,10 +160,10 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
   const scrollRef = useRef<HTMLDivElement>(null)
   const [dragOverStatus, setDragOverStatus] = useState<WorkspaceStatus | null>(null)
   const [pinDragOver, setPinDragOver] = useState(false)
+  const canReorderRepoHeaders = groupBy === 'repo' && repoGroupOrdering === 'manual'
 
-  // Drag is only meaningful when the user is grouping by repo. When inert
-  // (groupBy !== 'repo'), the controller is still constructed for hook order
-  // stability but the handle is never rendered.
+  // Drag is only meaningful when repo headers are using manual order. The
+  // controller is still constructed for hook order stability when inert.
   const repoDrag = useRepoHeaderDrag({
     orderedRepoIds: allRepoIds,
     onCommit: reorderRepos,
@@ -321,7 +325,8 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         prCache,
         new Set<string>(),
         repoOrder,
-        workspaceStatuses
+        workspaceStatuses,
+        repoGroupOrdering
       ).filter((r): r is Extract<Row, { type: 'item' }> => r.type === 'item')
       if (worktreeRows.length === 0) {
         return
@@ -359,6 +364,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
       activeWorktreeId,
       virtualizer,
       groupBy,
+      repoGroupOrdering,
       worktrees,
       repoMap,
       prCache,
@@ -511,7 +517,9 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
         className="relative w-full"
         style={{ height: `${virtualizer.getTotalSize()}px` }}
       >
-        {repoDrag.state.draggingRepoId !== null && repoDrag.state.dropIndicatorY !== null ? (
+        {canReorderRepoHeaders &&
+        repoDrag.state.draggingRepoId !== null &&
+        repoDrag.state.dropIndicatorY !== null ? (
           <div
             role="presentation"
             className="pointer-events-none absolute left-2 right-2 z-10 border-t border-dashed border-muted-foreground/70"
@@ -525,6 +533,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
             const isRepoHeader = groupBy === 'repo' && row.repo !== undefined
             const repoIdForHeader = isRepoHeader ? row.repo!.id : undefined
             const isDraggingThis =
+              canReorderRepoHeaders &&
               repoDrag.state.draggingRepoId !== null &&
               repoDrag.state.draggingRepoId === repoIdForHeader
             const headerWorkspaceStatus =
@@ -592,7 +601,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
                   {row.icon ? (
                     <div
                       onPointerDown={
-                        isRepoHeader && repoIdForHeader
+                        canReorderRepoHeaders && isRepoHeader && repoIdForHeader
                           ? (e) => repoDrag.onHandlePointerDown(e, repoIdForHeader)
                           : undefined
                       }
@@ -1013,9 +1022,8 @@ const WorktreeList = React.memo(function WorktreeList() {
   const collapsedGroups = useAppStore((s) => s.collapsedGroups)
   const toggleGroup = useAppStore((s) => s.toggleCollapsedGroup)
 
-  // Why: header order in groupBy='repo' is bound to state.repos array order so
-  // manual reorder is the single source of truth. The Map lets buildRows do an
-  // O(1) rank lookup per group without depending on Repo identity.
+  // Why: manual repo header order is bound to state.repos. Recent/Smart derive
+  // header order from the sorted visible worktree stream instead.
   const repos = useAppStore((s) => s.repos)
   const repoOrder = useMemo(() => {
     const map = new Map<string, number>()
@@ -1024,6 +1032,7 @@ const WorktreeList = React.memo(function WorktreeList() {
   }, [repos])
   const allRepoIds = useMemo(() => repos.map((r) => r.id), [repos])
   const reorderReposAction = useAppStore((s) => s.reorderRepos)
+  const repoGroupOrdering = getRepoGroupOrdering(groupBy, sortBy)
 
   // Build flat row list for rendering
   const rows: Row[] = useMemo(
@@ -1035,9 +1044,19 @@ const WorktreeList = React.memo(function WorktreeList() {
         prCache,
         collapsedGroups,
         repoOrder,
-        workspaceStatuses
+        workspaceStatuses,
+        repoGroupOrdering
       ),
-    [groupBy, worktrees, repoMap, prCache, collapsedGroups, repoOrder, workspaceStatuses]
+    [
+      groupBy,
+      worktrees,
+      repoMap,
+      prCache,
+      collapsedGroups,
+      repoOrder,
+      workspaceStatuses,
+      repoGroupOrdering
+    ]
   )
   // Why: rows.length alone can stay the same when items migrate between
   // groups (e.g., PR cache loads on restart and a collapsed group absorbs
@@ -1240,6 +1259,7 @@ const WorktreeList = React.memo(function WorktreeList() {
       rows={rows}
       activeWorktreeId={selectedSidebarWorktreeId}
       groupBy={groupBy}
+      repoGroupOrdering={repoGroupOrdering}
       toggleGroup={toggleGroup}
       collapsedGroups={collapsedGroups}
       handleCreateForRepo={handleCreateForRepo}
diff --git a/src/renderer/src/components/sidebar/smart-sort.ts b/src/renderer/src/components/sidebar/smart-sort.ts
index 96872ba9ff3..3ccc7ae383c 100644
--- a/src/renderer/src/components/sidebar/smart-sort.ts
+++ b/src/renderer/src/components/sidebar/smart-sort.ts
@@ -6,7 +6,7 @@ import type {
 import { tabHasLivePty } from '@/lib/tab-has-live-pty'
 import { IDLE, buildAttentionByWorktree, type WorktreeAttention } from './smart-attention'
 
-type SortBy = 'name' | 'smart' | 'recent' | 'repo'
+export type SortBy = 'name' | 'smart' | 'recent' | 'repo'
 
 // Why: a newly-created worktree's lastActivityAt is stamped at the moment
 // createLocalWorktree finishes git + setup-runner prep (often several seconds
diff --git a/src/renderer/src/components/sidebar/worktree-list-groups.test.ts b/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
index 2f2c576520e..1dd46e3b41b 100644
--- a/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
+++ b/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
-import { buildRows, getPRGroupKey } from './worktree-list-groups'
+import { buildRows, getPRGroupKey, getRepoGroupOrdering } from './worktree-list-groups'
 import type { Repo, Worktree } from '../../../../shared/types'
 
 const repo: Repo = {
@@ -209,6 +209,7 @@ describe('buildRows repo grouping order', () => {
     [repoC.id, repoC]
   ])
   const wA: Worktree = { ...worktree, id: 'wt-a', repoId: repoA.id, displayName: 'a' }
+  const wAStale: Worktree = { ...worktree, id: 'wt-a-stale', repoId: repoA.id, displayName: 'a2' }
   const wB: Worktree = { ...worktree, id: 'wt-b', repoId: repoB.id, displayName: 'b' }
   const wC: Worktree = { ...worktree, id: 'wt-c', repoId: repoC.id, displayName: 'c' }
 
@@ -231,6 +232,82 @@ describe('buildRows repo grouping order', () => {
     const headerKeys = rows.filter((r) => r.type === 'header').map((r) => r.key)
     expect(headerKeys).toEqual(['repo:repo-b', 'repo:repo-a', 'repo:repo-c'])
   })
+
+  it('orders repo headers by first encounter when caller uses visible worktree order', () => {
+    // Caller already sorted worktrees by recency: C is freshest, then A, then B.
+    // Even though repoOrder pins B, A, C, dynamic sorts must follow the freshest
+    // worktree out of each repo so a just-active worktree's parent group
+    // bubbles to the top of the sidebar.
+    const repoOrder = new Map([
+      [repoB.id, 0],
+      [repoA.id, 1],
+      [repoC.id, 2]
+    ])
+    const rows = buildRows(
+      'repo',
+      [wC, wA, wB],
+      map,
+      null,
+      new Set(),
+      repoOrder,
+      undefined,
+      'visible-worktree-order'
+    )
+    const headerKeys = rows.filter((r) => r.type === 'header').map((r) => r.key)
+    expect(headerKeys).toEqual(['repo:repo-c', 'repo:repo-a', 'repo:repo-b'])
+  })
+
+  it('orders repo headers by each repo highest-ranked visible child', () => {
+    const repoOrder = new Map([
+      [repoB.id, 0],
+      [repoA.id, 1],
+      [repoC.id, 2]
+    ])
+    const rows = buildRows(
+      'repo',
+      [wA, wB, wAStale, wC],
+      map,
+      null,
+      new Set(),
+      repoOrder,
+      undefined,
+      'visible-worktree-order'
+    )
+
+    expect(rows).toMatchObject([
+      { type: 'header', key: 'repo:repo-a' },
+      { type: 'item', worktree: { id: 'wt-a' } },
+      { type: 'item', worktree: { id: 'wt-a-stale' } },
+      { type: 'header', key: 'repo:repo-b' },
+      { type: 'item', worktree: { id: 'wt-b' } },
+      { type: 'header', key: 'repo:repo-c' },
+      { type: 'item', worktree: { id: 'wt-c' } }
+    ])
+  })
+
+  it('keeps repoOrder for manual repo group ordering', () => {
+    const repoOrder = new Map([
+      [repoB.id, 0],
+      [repoA.id, 1],
+      [repoC.id, 2]
+    ])
+    const rows = buildRows('repo', [wC, wA, wB], map, null, new Set(), repoOrder)
+    const headerKeys = rows.filter((r) => r.type === 'header').map((r) => r.key)
+    expect(headerKeys).toEqual(['repo:repo-b', 'repo:repo-a', 'repo:repo-c'])
+  })
+})
+
+describe('getRepoGroupOrdering', () => {
+  it.each([
+    ['repo', 'recent', 'visible-worktree-order'],
+    ['repo', 'smart', 'visible-worktree-order'],
+    ['repo', 'name', 'manual'],
+    ['repo', 'repo', 'manual'],
+    ['none', 'recent', 'manual'],
+    ['pr-status', 'recent', 'manual']
+  ] as const)('uses %s/%s -> %s', (groupBy, sortBy, expected) => {
+    expect(getRepoGroupOrdering(groupBy, sortBy)).toBe(expected)
+  })
 })
 
 describe('WorktreeList header styles', () => {
diff --git a/src/renderer/src/components/sidebar/worktree-list-groups.ts b/src/renderer/src/components/sidebar/worktree-list-groups.ts
index 50e2d645719..fd292eadf9c 100644
--- a/src/renderer/src/components/sidebar/worktree-list-groups.ts
+++ b/src/renderer/src/components/sidebar/worktree-list-groups.ts
@@ -9,10 +9,18 @@ import {
   getWorkspaceStatusVisualMeta
 } from './workspace-status'
 import { cloneDefaultWorkspaceStatuses } from '../../../../shared/workspace-statuses'
+import type { SortBy } from './smart-sort'
 
 export { branchName }
 
 export type WorktreeGroupBy = 'none' | 'repo' | 'pr-status'
+export type RepoGroupOrdering = 'manual' | 'visible-worktree-order'
+
+export function getRepoGroupOrdering(groupBy: WorktreeGroupBy, sortBy: SortBy): RepoGroupOrdering {
+  return groupBy === 'repo' && (sortBy === 'recent' || sortBy === 'smart')
+    ? 'visible-worktree-order'
+    : 'manual'
+}
 
 export type GroupHeaderRow = {
   type: 'header'
@@ -146,7 +154,8 @@ export function buildRows(
   prCache: Record<string, unknown> | null,
   collapsedGroups: Set<string>,
   repoOrder?: Map<string, number>,
-  workspaceStatuses: readonly WorkspaceStatusDefinition[] = cloneDefaultWorkspaceStatuses()
+  workspaceStatuses: readonly WorkspaceStatusDefinition[] = cloneDefaultWorkspaceStatuses(),
+  repoGroupOrdering: RepoGroupOrdering = 'manual'
 ): Row[] {
   const result: Row[] = []
 
@@ -199,13 +208,11 @@ export function buildRows(
       }
     }
   } else {
-    // Why: header order must follow the canonical state.repos array order, not
-    // first-encounter from the smart-sorted worktree stream — otherwise sorting
-    // or filtering side effects could shuffle which repo header appears first,
-    // and manual reorder would have nothing to bind to. Unknown ids (no entry
-    // in repoOrder) sort last by label so they remain deterministic.
+    // Why: dynamic sorts need repo headers to follow their highest-ranked
+    // visible child. Manual ordering still uses the canonical state.repos
+    // order so repo-header drag has a stable source of truth.
     const entries = Array.from(grouped.entries())
-    if (repoOrder) {
+    if (repoGroupOrdering === 'manual' && repoOrder) {
       const rankFor = (key: string): number => {
         const repoId = key.startsWith('repo:') ? key.slice('repo:'.length) : key
         const rank = repoOrder.get(repoId)

From 194e7d36d7f8683910979b7e9d4164f12c40cdfc Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:18:05 -0700
Subject: [PATCH 67/82] feat(automations): manage external automation jobs
 (#1976)

* feat(automations): manage external automation jobs

* fix: restore worktree activity status compatibility
---
 src/main/automations/external-job-mappers.ts  | 164 ++++++++++++
 src/main/automations/external-manager.test.ts | 170 ++++++++++++
 src/main/automations/external-manager.ts      | 250 ++++++++++++++++++
 src/main/ipc/automations.ts                   |  15 ++
 src/preload/api-types.ts                      |   4 +
 src/preload/index.ts                          |   6 +
 src/relay/external-automations-handler.ts     | 118 +++++++++
 src/relay/relay.ts                            |   3 +
 .../automations/AutomationsPage.tsx           | 124 ++++++++-
 .../ExternalAutomationManagers.tsx            | 197 ++++++++++++++
 .../src/components/settings/agents-search.ts  |   1 +
 src/renderer/src/lib/agent-catalog.tsx        |   7 +
 src/renderer/src/lib/agent-status.ts          |   1 +
 src/shared/agent-detection.ts                 |  11 +-
 src/shared/agent-kind.ts                      |   1 +
 src/shared/automations-types.ts               |  48 ++++
 src/shared/telemetry-events.ts                |   1 +
 src/shared/tui-agent-config.ts                |   6 +
 src/shared/types.ts                           |   1 +
 19 files changed, 1125 insertions(+), 3 deletions(-)
 create mode 100644 src/main/automations/external-job-mappers.ts
 create mode 100644 src/main/automations/external-manager.test.ts
 create mode 100644 src/main/automations/external-manager.ts
 create mode 100644 src/relay/external-automations-handler.ts
 create mode 100644 src/renderer/src/components/automations/ExternalAutomationManagers.tsx

diff --git a/src/main/automations/external-job-mappers.ts b/src/main/automations/external-job-mappers.ts
new file mode 100644
index 00000000000..98c2b51d567
--- /dev/null
+++ b/src/main/automations/external-job-mappers.ts
@@ -0,0 +1,164 @@
+import type { ExternalAutomationJob } from '../../shared/automations-types'
+
+type ExternalJobRecord = Record<string, unknown>
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value : null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function formatDurationMs(value: unknown): string {
+  const ms = asNumber(value)
+  if (!ms) {
+    return '?'
+  }
+  if (ms % 86_400_000 === 0) {
+    return `${ms / 86_400_000}d`
+  }
+  if (ms % 3_600_000 === 0) {
+    return `${ms / 3_600_000}h`
+  }
+  if (ms % 60_000 === 0) {
+    return `${ms / 60_000}m`
+  }
+  if (ms % 1000 === 0) {
+    return `${ms / 1000}s`
+  }
+  return `${ms}ms`
+}
+
+function isoFromMs(value: unknown): string | null {
+  const ms = asNumber(value)
+  if (!ms) {
+    return null
+  }
+  const date = new Date(ms)
+  return Number.isNaN(date.getTime()) ? null : date.toISOString()
+}
+
+function hermesScheduleDisplay(job: ExternalJobRecord): string {
+  const direct = asString(job.schedule_display)
+  if (direct) {
+    return direct
+  }
+  const schedule = job.schedule
+  if (isRecord(schedule)) {
+    return (
+      asString(schedule.display) ??
+      asString(schedule.value) ??
+      asString(schedule.expr) ??
+      asString(schedule.run_at) ??
+      '?'
+    )
+  }
+  return asString(schedule) ?? '?'
+}
+
+function hermesPromptPreview(job: ExternalJobRecord): string {
+  const prompt = asString(job.prompt) ?? ''
+  if (prompt) {
+    return prompt.length > 120 ? `${prompt.slice(0, 117)}...` : prompt
+  }
+  const script = asString(job.script)
+  if (script) {
+    return job.no_agent ? `Script: ${script}` : `Prompt uses script context: ${script}`
+  }
+  const skills = Array.isArray(job.skills) ? job.skills.map((skill) => String(skill)) : []
+  return skills.length > 0 ? `Skills: ${skills.join(', ')}` : ''
+}
+
+function openClawScheduleDisplay(job: ExternalJobRecord): string {
+  const schedule = job.schedule
+  if (!isRecord(schedule)) {
+    return asString(schedule) ?? '?'
+  }
+  const kind = asString(schedule.kind)
+  if (kind === 'at') {
+    return `at ${asString(schedule.at) ?? '?'}`
+  }
+  if (kind === 'every') {
+    return `every ${formatDurationMs(schedule.everyMs)}`
+  }
+  if (kind === 'cron') {
+    const expr = asString(schedule.expr) ?? asString(schedule.cron) ?? '?'
+    const tz = asString(schedule.tz)
+    return tz ? `cron ${expr} @ ${tz}` : `cron ${expr}`
+  }
+  return kind ?? '?'
+}
+
+function openClawPromptPreview(job: ExternalJobRecord): string {
+  const payload = job.payload
+  if (!isRecord(payload)) {
+    return ''
+  }
+  const text = asString(payload.message) ?? asString(payload.text) ?? ''
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text
+}
+
+export function mapHermesJobs(managerId: string, rawJobs: unknown): ExternalAutomationJob[] {
+  if (!Array.isArray(rawJobs)) {
+    return []
+  }
+  return rawJobs.filter(isRecord).map((job) => {
+    const id = asString(job.id) ?? 'unknown'
+    const enabled = job.enabled !== false && job.state !== 'paused'
+    const preview = hermesPromptPreview(job)
+    return {
+      id,
+      managerId,
+      provider: 'hermes',
+      name: (asString(job.name) ?? preview) || id,
+      schedule: hermesScheduleDisplay(job),
+      enabled,
+      state: asString(job.state) ?? (enabled ? 'scheduled' : 'paused'),
+      promptPreview: preview,
+      nextRunAt: asString(job.next_run_at),
+      lastRunAt: asString(job.last_run_at),
+      lastStatus: asString(job.last_status),
+      lastError: asString(job.last_error) ?? asString(job.last_delivery_error),
+      workdir: asString(job.workdir)
+    }
+  })
+}
+
+export function mapOpenClawJobs(managerId: string, rawJobs: unknown): ExternalAutomationJob[] {
+  const jobs = Array.isArray(rawJobs)
+    ? rawJobs
+    : isRecord(rawJobs) && Array.isArray(rawJobs.jobs)
+      ? rawJobs.jobs
+      : []
+  return jobs.filter(isRecord).map((job) => {
+    const id = asString(job.id) ?? 'unknown'
+    const enabled = job.enabled !== false
+    const state = isRecord(job.state) ? job.state : {}
+    const preview = openClawPromptPreview(job)
+    const lastStatus = asString(state.lastRunStatus) ?? asString(state.lastStatus)
+    return {
+      id,
+      managerId,
+      provider: 'openclaw',
+      name: (asString(job.name) ?? preview) || id,
+      schedule: openClawScheduleDisplay(job),
+      enabled,
+      state: !enabled
+        ? 'disabled'
+        : asNumber(state.runningAtMs)
+          ? 'running'
+          : (lastStatus ?? 'idle'),
+      promptPreview: preview,
+      nextRunAt: isoFromMs(state.nextRunAtMs),
+      lastRunAt: isoFromMs(state.lastRunAtMs),
+      lastStatus,
+      lastError: asString(state.lastError) ?? asString(state.lastDeliveryError),
+      workdir: null
+    }
+  })
+}
diff --git a/src/main/automations/external-manager.test.ts b/src/main/automations/external-manager.test.ts
new file mode 100644
index 00000000000..bb1af7be23c
--- /dev/null
+++ b/src/main/automations/external-manager.test.ts
@@ -0,0 +1,170 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { runExternalAutomationAction } from './external-manager'
+import { mapHermesJobs, mapOpenClawJobs } from './external-job-mappers'
+
+const execFileMock = vi.hoisted(() =>
+  vi.fn((...args: unknown[]) => {
+    const callback = args.at(-1)
+    if (typeof callback === 'function') {
+      const execCallback = callback as (error: Error | null, stdout: string, stderr: string) => void
+      execCallback(null, '', '')
+    }
+  })
+)
+
+vi.mock('child_process', () => ({ execFile: execFileMock }))
+
+vi.mock('../ipc/ssh', () => ({
+  getActiveMultiplexer: vi.fn()
+}))
+
+beforeEach(() => {
+  execFileMock.mockClear()
+})
+
+describe('mapHermesJobs', () => {
+  it('normalizes Hermes cron jobs into external automation rows', () => {
+    const jobs = mapHermesJobs('hermes:local', [
+      {
+        id: 'job-1',
+        name: 'Nightly audit',
+        prompt: 'Audit the repo for risky dependency changes',
+        schedule_display: '0 9 * * 1-5',
+        enabled: true,
+        state: 'scheduled',
+        next_run_at: '2026-05-16T09:00:00Z',
+        last_run_at: '2026-05-15T09:00:00Z',
+        last_status: 'ok',
+        workdir: '/repo'
+      }
+    ])
+
+    expect(jobs).toEqual([
+      {
+        id: 'job-1',
+        managerId: 'hermes:local',
+        provider: 'hermes',
+        name: 'Nightly audit',
+        schedule: '0 9 * * 1-5',
+        enabled: true,
+        state: 'scheduled',
+        promptPreview: 'Audit the repo for risky dependency changes',
+        nextRunAt: '2026-05-16T09:00:00Z',
+        lastRunAt: '2026-05-15T09:00:00Z',
+        lastStatus: 'ok',
+        lastError: null,
+        workdir: '/repo'
+      }
+    ])
+  })
+
+  it('falls back to script and schedule fields for older Hermes records', () => {
+    const jobs = mapHermesJobs('hermes:local', [
+      {
+        id: 'job-2',
+        script: 'disk-check.sh',
+        no_agent: true,
+        schedule: { display: 'every 30m' },
+        enabled: false,
+        state: 'paused',
+        last_delivery_error: 'home channel missing'
+      }
+    ])
+
+    expect(jobs[0]).toMatchObject({
+      id: 'job-2',
+      name: 'Script: disk-check.sh',
+      schedule: 'every 30m',
+      enabled: false,
+      state: 'paused',
+      promptPreview: 'Script: disk-check.sh',
+      lastError: 'home channel missing'
+    })
+  })
+})
+
+describe('runExternalAutomationAction', () => {
+  it('runs local Hermes lifecycle actions through the CLI', async () => {
+    await runExternalAutomationAction({
+      managerId: 'hermes:local',
+      provider: 'hermes',
+      target: { type: 'local' },
+      jobId: 'job-1',
+      action: 'run'
+    })
+
+    expect(execFileMock).toHaveBeenCalledWith(
+      'hermes',
+      ['cron', 'run', 'job-1'],
+      { encoding: 'utf-8' },
+      expect.any(Function)
+    )
+  })
+
+  it('rejects job IDs that could be parsed as CLI options', async () => {
+    await expect(
+      runExternalAutomationAction({
+        managerId: 'hermes:local',
+        provider: 'hermes',
+        target: { type: 'local' },
+        jobId: '-help',
+        action: 'run'
+      })
+    ).rejects.toThrow('Invalid external automation job ID.')
+
+    expect(execFileMock).not.toHaveBeenCalled()
+  })
+
+  it('maps OpenClaw lifecycle actions through its cron CLI names', async () => {
+    await runExternalAutomationAction({
+      managerId: 'openclaw:local',
+      provider: 'openclaw',
+      target: { type: 'local' },
+      jobId: 'job-1',
+      action: 'pause'
+    })
+
+    expect(execFileMock).toHaveBeenCalledWith(
+      'openclaw',
+      ['cron', 'disable', 'job-1'],
+      { encoding: 'utf-8' },
+      expect.any(Function)
+    )
+  })
+})
+
+describe('mapOpenClawJobs', () => {
+  it('normalizes OpenClaw cron jobs into external automation rows', () => {
+    const jobs = mapOpenClawJobs('openclaw:local', {
+      version: 1,
+      jobs: [
+        {
+          id: 'claw-1',
+          name: 'Morning report',
+          enabled: true,
+          schedule: { kind: 'cron', expr: '0 9 * * *', tz: 'America/Phoenix' },
+          payload: { kind: 'agentTurn', message: 'Summarize overnight alerts' },
+          state: {
+            nextRunAtMs: Date.parse('2026-05-16T16:00:00Z'),
+            lastRunAtMs: Date.parse('2026-05-15T16:00:00Z'),
+            lastRunStatus: 'ok'
+          }
+        }
+      ]
+    })
+
+    expect(jobs[0]).toMatchObject({
+      id: 'claw-1',
+      managerId: 'openclaw:local',
+      provider: 'openclaw',
+      name: 'Morning report',
+      schedule: 'cron 0 9 * * * @ America/Phoenix',
+      enabled: true,
+      state: 'ok',
+      promptPreview: 'Summarize overnight alerts',
+      nextRunAt: '2026-05-16T16:00:00.000Z',
+      lastRunAt: '2026-05-15T16:00:00.000Z',
+      lastStatus: 'ok'
+    })
+  })
+})
diff --git a/src/main/automations/external-manager.ts b/src/main/automations/external-manager.ts
new file mode 100644
index 00000000000..a1585778a95
--- /dev/null
+++ b/src/main/automations/external-manager.ts
@@ -0,0 +1,250 @@
+import { execFile } from 'child_process'
+import { existsSync } from 'fs'
+import { readFile } from 'fs/promises'
+import { homedir } from 'os'
+import { join } from 'path'
+import { promisify } from 'util'
+import type {
+  ExternalAutomationAction,
+  ExternalAutomationActionInput,
+  ExternalAutomationManager,
+  ExternalAutomationProvider
+} from '../../shared/automations-types'
+import type { SshTarget } from '../../shared/ssh-types'
+import type { Store } from '../persistence'
+import { getActiveMultiplexer } from '../ipc/ssh'
+import { mapHermesJobs, mapOpenClawJobs } from './external-job-mappers'
+
+const execFileAsync = promisify(execFile)
+const HERMES_JOBS_FILE = join(homedir(), '.hermes', 'cron', 'jobs.json')
+const OPENCLAW_JOBS_FILE = join(homedir(), '.openclaw', 'cron', 'jobs.json')
+const EXTERNAL_JOB_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+async function isCommandOnPath(command: string): Promise<boolean> {
+  const finder = process.platform === 'win32' ? 'where' : 'which'
+  try {
+    await execFileAsync(finder, [command], { encoding: 'utf-8' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function readLocalHermesJobs(): Promise<unknown[]> {
+  if (!existsSync(HERMES_JOBS_FILE)) {
+    return []
+  }
+  const content = await readFile(HERMES_JOBS_FILE, 'utf-8')
+  const parsed = JSON.parse(content) as unknown
+  return Array.isArray(parsed) ? parsed : []
+}
+
+async function readLocalOpenClawJobs(): Promise<unknown[]> {
+  if (!existsSync(OPENCLAW_JOBS_FILE)) {
+    return []
+  }
+  const content = await readFile(OPENCLAW_JOBS_FILE, 'utf-8')
+  const parsed = JSON.parse(content) as unknown
+  return isRecord(parsed) && Array.isArray(parsed.jobs) ? parsed.jobs : []
+}
+
+async function listLocalHermesManager(): Promise<ExternalAutomationManager | null> {
+  const [hermesAvailableResult, jobsResult] = await Promise.allSettled([
+    isCommandOnPath('hermes'),
+    readLocalHermesJobs()
+  ])
+  const hermesAvailable =
+    hermesAvailableResult.status === 'fulfilled' && hermesAvailableResult.value
+  const jobs = jobsResult.status === 'fulfilled' ? jobsResult.value : []
+  const readError = jobsResult.status === 'rejected' ? String(jobsResult.reason) : null
+  if (!hermesAvailable && jobs.length === 0 && !readError) {
+    return null
+  }
+  const managerId = 'hermes:local'
+  return {
+    id: managerId,
+    provider: 'hermes',
+    label: 'Hermes on this computer',
+    target: { type: 'local' },
+    status: readError ? 'unavailable' : 'available',
+    error:
+      readError ??
+      (hermesAvailable ? null : 'Hermes jobs were found, but the hermes CLI is not on PATH.'),
+    canManage: !readError && hermesAvailable,
+    jobs: mapHermesJobs(managerId, jobs)
+  }
+}
+
+async function listLocalOpenClawManager(): Promise<ExternalAutomationManager | null> {
+  const [openClawAvailableResult, jobsResult] = await Promise.allSettled([
+    isCommandOnPath('openclaw'),
+    readLocalOpenClawJobs()
+  ])
+  const openClawAvailable =
+    openClawAvailableResult.status === 'fulfilled' && openClawAvailableResult.value
+  const jobs = jobsResult.status === 'fulfilled' ? jobsResult.value : []
+  const readError = jobsResult.status === 'rejected' ? String(jobsResult.reason) : null
+  if (!openClawAvailable && jobs.length === 0 && !readError) {
+    return null
+  }
+  const managerId = 'openclaw:local'
+  return {
+    id: managerId,
+    provider: 'openclaw',
+    label: 'OpenClaw on this computer',
+    target: { type: 'local' },
+    status: readError ? 'unavailable' : 'available',
+    error:
+      readError ??
+      (openClawAvailable ? null : 'OpenClaw jobs were found, but the openclaw CLI is not on PATH.'),
+    canManage: !readError && openClawAvailable,
+    jobs: mapOpenClawJobs(managerId, jobs)
+  }
+}
+
+function remoteRelayErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error)
+  if (message.includes('-32601') || /method not found/i.test(message)) {
+    return 'Remote relay does not support external automation management. Reconnect the SSH target to deploy the latest relay.'
+  }
+  return message
+}
+
+async function listRemoteHermesManager(target: SshTarget): Promise<ExternalAutomationManager> {
+  return listRemoteManager(target, 'hermes')
+}
+
+async function listRemoteOpenClawManager(target: SshTarget): Promise<ExternalAutomationManager> {
+  return listRemoteManager(target, 'openclaw')
+}
+
+async function listRemoteManager(
+  target: SshTarget,
+  provider: ExternalAutomationProvider
+): Promise<ExternalAutomationManager> {
+  const providerLabel = provider === 'hermes' ? 'Hermes' : 'OpenClaw'
+  const managerProviderId = `${provider}:ssh:${target.id}`
+  const mux = getActiveMultiplexer(target.id)
+  if (!mux || mux.isDisposed()) {
+    return {
+      id: managerProviderId,
+      provider,
+      label: `${providerLabel} on ${target.label}`,
+      target: { type: 'ssh', connectionId: target.id },
+      status: 'unavailable',
+      error: 'SSH target is not connected.',
+      canManage: false,
+      jobs: []
+    }
+  }
+  try {
+    const result = (await mux.request('externalAutomations.list', { provider })) as {
+      jobs?: unknown[]
+      hermesAvailable?: boolean
+      openclawAvailable?: boolean
+      error?: string | null
+    }
+    const commandAvailable =
+      provider === 'hermes' ? result.hermesAvailable === true : result.openclawAvailable === true
+    const readError = result.error ?? null
+    return {
+      id: managerProviderId,
+      provider,
+      label: `${providerLabel} on ${target.label}`,
+      target: { type: 'ssh', connectionId: target.id },
+      status: readError ? 'unavailable' : 'available',
+      error:
+        readError ?? (commandAvailable ? null : `${providerLabel} CLI is not on the remote PATH.`),
+      canManage: !readError && commandAvailable,
+      jobs:
+        provider === 'hermes'
+          ? mapHermesJobs(managerProviderId, result.jobs ?? [])
+          : mapOpenClawJobs(managerProviderId, result.jobs ?? [])
+    }
+  } catch (error) {
+    return {
+      id: managerProviderId,
+      provider,
+      label: `${providerLabel} on ${target.label}`,
+      target: { type: 'ssh', connectionId: target.id },
+      status: 'unavailable',
+      error: remoteRelayErrorMessage(error),
+      canManage: false,
+      jobs: []
+    }
+  }
+}
+
+export async function listExternalAutomationManagers(
+  store: Store
+): Promise<ExternalAutomationManager[]> {
+  const [localHermes, localOpenClaw, remote] = await Promise.all([
+    listLocalHermesManager(),
+    listLocalOpenClawManager(),
+    Promise.all(
+      store
+        .getSshTargets()
+        .flatMap((target) => [listRemoteHermesManager(target), listRemoteOpenClawManager(target)])
+    )
+  ])
+  return [
+    ...(localHermes ? [localHermes] : []),
+    ...(localOpenClaw ? [localOpenClaw] : []),
+    ...remote
+  ]
+}
+
+function hermesCommandForAction(action: ExternalAutomationAction): string {
+  switch (action) {
+    case 'pause':
+      return 'pause'
+    case 'resume':
+      return 'resume'
+    case 'run':
+      return 'run'
+    case 'delete':
+      return 'remove'
+  }
+}
+
+function openClawCommandForAction(action: ExternalAutomationAction): string {
+  switch (action) {
+    case 'pause':
+      return 'disable'
+    case 'resume':
+      return 'enable'
+    case 'run':
+      return 'run'
+    case 'delete':
+      return 'rm'
+  }
+}
+
+export async function runExternalAutomationAction(
+  input: ExternalAutomationActionInput
+): Promise<void> {
+  if (!EXTERNAL_JOB_ID_PATTERN.test(input.jobId)) {
+    throw new Error('Invalid external automation job ID.')
+  }
+  const command =
+    input.provider === 'hermes'
+      ? hermesCommandForAction(input.action)
+      : openClawCommandForAction(input.action)
+  if (input.target.type === 'local') {
+    await execFileAsync(input.provider, ['cron', command, input.jobId], { encoding: 'utf-8' })
+    return
+  }
+  const mux = getActiveMultiplexer(input.target.connectionId)
+  if (!mux || mux.isDisposed()) {
+    throw new Error(`SSH target "${input.target.connectionId}" is not connected.`)
+  }
+  await mux.request('externalAutomations.act', {
+    provider: input.provider,
+    action: input.action,
+    jobId: input.jobId
+  })
+}
diff --git a/src/main/ipc/automations.ts b/src/main/ipc/automations.ts
index e01d2767455..f5c762d265c 100644
--- a/src/main/ipc/automations.ts
+++ b/src/main/ipc/automations.ts
@@ -5,9 +5,15 @@ import type {
   Automation,
   AutomationCreateInput,
   AutomationDispatchResult,
+  ExternalAutomationActionInput,
+  ExternalAutomationManager,
   AutomationRun,
   AutomationUpdateInput
 } from '../../shared/automations-types'
+import {
+  listExternalAutomationManagers,
+  runExternalAutomationAction
+} from '../automations/external-manager'
 
 export function registerAutomationHandlers(store: Store, service: AutomationService): void {
   ipcMain.handle('automations:list', (): Automation[] => store.listAutomations())
@@ -16,6 +22,15 @@ export function registerAutomationHandlers(store: Store, service: AutomationServ
     (_event, args?: { automationId?: string }): AutomationRun[] =>
       store.listAutomationRuns(args?.automationId)
   )
+  ipcMain.handle('automations:listExternalManagers', (): Promise<ExternalAutomationManager[]> => {
+    return listExternalAutomationManagers(store)
+  })
+  ipcMain.handle(
+    'automations:runExternalAction',
+    (_event, input: ExternalAutomationActionInput) => {
+      return runExternalAutomationAction(input)
+    }
+  )
   ipcMain.handle(
     'automations:create',
     (_event, input: AutomationCreateInput): Automation => store.createAutomation(input)
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index eb41cd2e376..d02b9fad694 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -217,6 +217,8 @@ import type {
   AutomationCreateInput,
   AutomationDispatchRequest,
   AutomationDispatchResult,
+  ExternalAutomationActionInput,
+  ExternalAutomationManager,
   AutomationRun,
   AutomationUpdateInput
 } from '../shared/automations-types'
@@ -1599,6 +1601,8 @@ export type PreloadApi = {
   automations: {
     list: () => Promise<Automation[]>
     listRuns: (args?: { automationId?: string }) => Promise<AutomationRun[]>
+    listExternalManagers: () => Promise<ExternalAutomationManager[]>
+    runExternalAction: (input: ExternalAutomationActionInput) => Promise<void>
     create: (input: AutomationCreateInput) => Promise<Automation>
     update: (args: { id: string; updates: AutomationUpdateInput }) => Promise<Automation>
     delete: (args: { id: string }) => Promise<void>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 3eb695a9d2c..bbbc8942d7c 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -100,6 +100,8 @@ import type {
   AutomationCreateInput,
   AutomationDispatchRequest,
   AutomationDispatchResult,
+  ExternalAutomationActionInput,
+  ExternalAutomationManager,
   AutomationRun,
   AutomationUpdateInput
 } from '../shared/automations-types'
@@ -2641,6 +2643,10 @@ const api = {
     list: (): Promise<Automation[]> => ipcRenderer.invoke('automations:list'),
     listRuns: (args?: { automationId?: string }): Promise<AutomationRun[]> =>
       ipcRenderer.invoke('automations:listRuns', args),
+    listExternalManagers: (): Promise<ExternalAutomationManager[]> =>
+      ipcRenderer.invoke('automations:listExternalManagers'),
+    runExternalAction: (input: ExternalAutomationActionInput): Promise<void> =>
+      ipcRenderer.invoke('automations:runExternalAction', input),
     create: (input: AutomationCreateInput): Promise<Automation> =>
       ipcRenderer.invoke('automations:create', input),
     update: (args: { id: string; updates: AutomationUpdateInput }): Promise<Automation> =>
diff --git a/src/relay/external-automations-handler.ts b/src/relay/external-automations-handler.ts
new file mode 100644
index 00000000000..82d2c6d2799
--- /dev/null
+++ b/src/relay/external-automations-handler.ts
@@ -0,0 +1,118 @@
+import { execFile } from 'child_process'
+import { existsSync } from 'fs'
+import { readFile } from 'fs/promises'
+import { homedir } from 'os'
+import { join } from 'path'
+import { promisify } from 'util'
+import type { RelayDispatcher } from './dispatcher'
+
+const execFileAsync = promisify(execFile)
+const HERMES_JOBS_FILE = join(homedir(), '.hermes', 'cron', 'jobs.json')
+const OPENCLAW_JOBS_FILE = join(homedir(), '.openclaw', 'cron', 'jobs.json')
+const EXTERNAL_JOB_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/
+
+type ExternalProvider = 'hermes' | 'openclaw'
+type HermesAction = 'pause' | 'resume' | 'run' | 'delete'
+
+export class ExternalAutomationsHandler {
+  constructor(private readonly dispatcher: RelayDispatcher) {
+    this.dispatcher.onRequest('externalAutomations.list', (params) => this.listJobs(params))
+    this.dispatcher.onRequest('externalAutomations.act', (params) => this.runAction(params))
+  }
+
+  private async isCommandAvailable(command: string): Promise<boolean> {
+    try {
+      await execFileAsync('/bin/sh', ['-lc', `which ${command}`], {
+        encoding: 'utf-8',
+        timeout: 5000
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  private async readJobs(provider: ExternalProvider): Promise<unknown[]> {
+    const jobsFile = provider === 'hermes' ? HERMES_JOBS_FILE : OPENCLAW_JOBS_FILE
+    if (!existsSync(jobsFile)) {
+      return []
+    }
+    const content = await readFile(jobsFile, 'utf-8')
+    const parsed = JSON.parse(content) as unknown
+    if (Array.isArray(parsed)) {
+      return parsed
+    }
+    return typeof parsed === 'object' &&
+      parsed !== null &&
+      !Array.isArray(parsed) &&
+      Array.isArray((parsed as { jobs?: unknown }).jobs)
+      ? (parsed as { jobs: unknown[] }).jobs
+      : []
+  }
+
+  private async listJobs(params?: Record<string, unknown>): Promise<{
+    jobs: unknown[]
+    hermesAvailable: boolean
+    openclawAvailable: boolean
+    error: string | null
+  }> {
+    const provider = params?.provider === 'openclaw' ? 'openclaw' : 'hermes'
+    const [commandAvailable, jobsResult] = await Promise.allSettled([
+      this.isCommandAvailable(provider),
+      this.readJobs(provider)
+    ])
+    const jobs = jobsResult.status === 'fulfilled' ? jobsResult.value : []
+    const available = commandAvailable.status === 'fulfilled' && commandAvailable.value
+    return {
+      jobs,
+      hermesAvailable: provider === 'hermes' && available,
+      openclawAvailable: provider === 'openclaw' && available,
+      error: jobsResult.status === 'rejected' ? String(jobsResult.reason) : null
+    }
+  }
+
+  private hermesCommand(action: HermesAction): string {
+    switch (action) {
+      case 'pause':
+        return 'pause'
+      case 'resume':
+        return 'resume'
+      case 'run':
+        return 'run'
+      case 'delete':
+        return 'remove'
+    }
+  }
+
+  private openClawCommand(action: HermesAction): string {
+    switch (action) {
+      case 'pause':
+        return 'disable'
+      case 'resume':
+        return 'enable'
+      case 'run':
+        return 'run'
+      case 'delete':
+        return 'rm'
+    }
+  }
+
+  private async runAction(params: Record<string, unknown> = {}): Promise<{ ok: true }> {
+    const provider = params.provider === 'openclaw' ? 'openclaw' : 'hermes'
+    const action = params.action
+    const jobId = params.jobId
+    if (action !== 'pause' && action !== 'resume' && action !== 'run' && action !== 'delete') {
+      throw new Error('Unsupported external automation action.')
+    }
+    if (typeof jobId !== 'string' || !EXTERNAL_JOB_ID_PATTERN.test(jobId)) {
+      throw new Error('Invalid external automation job ID.')
+    }
+    const command =
+      provider === 'hermes' ? this.hermesCommand(action) : this.openClawCommand(action)
+    await execFileAsync('/bin/sh', ['-lc', `${provider} cron ${command} ${jobId}`], {
+      encoding: 'utf-8',
+      timeout: 30_000
+    })
+    return { ok: true }
+  }
+}
diff --git a/src/relay/relay.ts b/src/relay/relay.ts
index b550b490fd1..3ac7554f486 100644
--- a/src/relay/relay.ts
+++ b/src/relay/relay.ts
@@ -31,6 +31,7 @@ import { PtyHandler } from './pty-handler'
 import { FsHandler } from './fs-handler'
 import { GitHandler } from './git-handler'
 import { PreflightHandler } from './preflight-handler'
+import { ExternalAutomationsHandler } from './external-automations-handler'
 import { PortScanHandler } from './port-scan-handler'
 import { AgentExecHandler } from './agent-exec-handler'
 import { WorkspaceSessionHandler } from './workspace-session-handler'
@@ -235,7 +236,9 @@ async function main(): Promise<void> {
   void _gitHandler
 
   const _preflightHandler = new PreflightHandler(dispatcher)
+  const _externalAutomationsHandler = new ExternalAutomationsHandler(dispatcher)
   void _preflightHandler
+  void _externalAutomationsHandler
 
   const _portScanHandler = new PortScanHandler(dispatcher)
   void _portScanHandler
diff --git a/src/renderer/src/components/automations/AutomationsPage.tsx b/src/renderer/src/components/automations/AutomationsPage.tsx
index 09d5c9ebbb9..0027ee7d9eb 100644
--- a/src/renderer/src/components/automations/AutomationsPage.tsx
+++ b/src/renderer/src/components/automations/AutomationsPage.tsx
@@ -28,6 +28,9 @@ import { useRepoMap, useWorktreeMap } from '@/store/selectors'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import type {
   Automation,
+  ExternalAutomationAction,
+  ExternalAutomationJob,
+  ExternalAutomationManager,
   AutomationRun,
   AutomationUpdateInput
 } from '../../../../shared/automations-types'
@@ -36,6 +39,7 @@ import { buildAutomationRrule, parseAutomationRrule } from '../../../../shared/a
 import { formatAutomationDateTimeWithRelative } from './automation-page-parts'
 import { AutomationDetail } from './AutomationDetail'
 import { AutomationEditorDialog, type AutomationDraft } from './AutomationEditorDialog'
+import { ExternalAutomationManagers } from './ExternalAutomationManagers'
 
 const AGENTS = AGENT_CATALOG.map((agent) => agent.id)
 const DEFAULT_TIME = '09:00'
@@ -72,6 +76,8 @@ export default function AutomationsPage(): React.JSX.Element {
 
   const [automations, setAutomations] = useState<Automation[]>([])
   const [runs, setRuns] = useState<AutomationRun[]>([])
+  const [externalManagers, setExternalManagers] = useState<ExternalAutomationManager[]>([])
+  const [externalActionKey, setExternalActionKey] = useState<string | null>(null)
   const [isLoading, setIsLoading] = useState(true)
   const [isSaving, setIsSaving] = useState(false)
   const [createOpen, setCreateOpen] = useState(false)
@@ -79,6 +85,10 @@ export default function AutomationsPage(): React.JSX.Element {
   const [relativeNow, setRelativeNow] = useState(Date.now())
   const [draftAtOpen, setDraftAtOpen] = useState<AutomationDraft | null>(null)
   const [deleteTarget, setDeleteTarget] = useState<Automation | null>(null)
+  const [externalDeleteTarget, setExternalDeleteTarget] = useState<{
+    manager: ExternalAutomationManager
+    job: ExternalAutomationJob
+  } | null>(null)
   const [dontAskDeleteAgain, setDontAskDeleteAgain] = useState(false)
   const editRequestRef = useRef(0)
   const deleteConfirmButtonRef = useRef<HTMLButtonElement>(null)
@@ -129,12 +139,14 @@ export default function AutomationsPage(): React.JSX.Element {
   const refresh = useCallback(async () => {
     setIsLoading(true)
     try {
-      const [nextAutomations, nextRuns] = await Promise.all([
+      const [nextAutomations, nextRuns, nextExternalManagers] = await Promise.all([
         window.api.automations.list(),
-        window.api.automations.listRuns()
+        window.api.automations.listRuns(),
+        window.api.automations.listExternalManagers()
       ])
       setAutomations(nextAutomations)
       setRuns(nextRuns)
+      setExternalManagers(nextExternalManagers)
       const currentSelectedId = useAppStore.getState().selectedAutomationId
       const hasCurrentSelection = nextAutomations.some(
         (automation) => automation.id === currentSelectedId
@@ -464,6 +476,59 @@ export default function AutomationsPage(): React.JSX.Element {
     toast.message('Automation run queued.')
   }
 
+  const runExternalAction = async (
+    manager: ExternalAutomationManager,
+    job: ExternalAutomationJob,
+    action: ExternalAutomationAction
+  ): Promise<void> => {
+    const key = `${manager.id}:${job.id}:${action}`
+    setExternalActionKey(key)
+    try {
+      await window.api.automations.runExternalAction({
+        managerId: manager.id,
+        provider: manager.provider,
+        target: manager.target,
+        jobId: job.id,
+        action
+      })
+      await refresh()
+      toast.success(
+        action === 'delete'
+          ? 'External automation deleted.'
+          : action === 'run'
+            ? 'External automation queued.'
+            : action === 'pause'
+              ? 'External automation paused.'
+              : 'External automation resumed.'
+      )
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'External automation action failed.')
+    } finally {
+      setExternalActionKey(null)
+    }
+  }
+
+  const requestExternalAction = (
+    manager: ExternalAutomationManager,
+    job: ExternalAutomationJob,
+    action: ExternalAutomationAction
+  ): void => {
+    if (action === 'delete') {
+      setExternalDeleteTarget({ manager, job })
+      return
+    }
+    void runExternalAction(manager, job, action)
+  }
+
+  const confirmDeleteExternalAutomation = async (): Promise<void> => {
+    if (!externalDeleteTarget) {
+      return
+    }
+    const target = externalDeleteTarget
+    setExternalDeleteTarget(null)
+    await runExternalAction(target.manager, target.job, 'delete')
+  }
+
   const openRunWorkspace = (run: AutomationRun): void => {
     if (!run.workspaceId || !activateAndRevealWorktree(run.workspaceId)) {
       toast.error('Workspace is not available.')
@@ -613,6 +678,55 @@ export default function AutomationsPage(): React.JSX.Element {
         </DialogContent>
       </Dialog>
 
+      <Dialog
+        open={externalDeleteTarget !== null}
+        onOpenChange={(open) => {
+          if (!open) {
+            setExternalDeleteTarget(null)
+          }
+        }}
+      >
+        <DialogContent
+          className="max-w-md"
+          onOpenAutoFocus={(event) => {
+            event.preventDefault()
+            deleteConfirmButtonRef.current?.focus()
+          }}
+        >
+          <DialogHeader>
+            <DialogTitle className="text-sm">Delete External Automation</DialogTitle>
+            <DialogDescription className="text-xs">
+              Delete{' '}
+              <span className="break-all font-medium text-foreground">
+                {externalDeleteTarget?.job.name}
+              </span>{' '}
+              from {externalDeleteTarget?.manager.label}.
+            </DialogDescription>
+          </DialogHeader>
+          {externalDeleteTarget ? (
+            <div className="rounded-md border border-border/70 bg-muted/35 px-3 py-2 text-xs">
+              <div className="break-all font-medium text-foreground">
+                {externalDeleteTarget.job.name}
+              </div>
+              <div className="mt-1 text-muted-foreground">{externalDeleteTarget.job.schedule}</div>
+            </div>
+          ) : null}
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setExternalDeleteTarget(null)}>
+              Cancel
+            </Button>
+            <Button
+              ref={deleteConfirmButtonRef}
+              variant="destructive"
+              onClick={() => void confirmDeleteExternalAutomation()}
+            >
+              <Trash2 className="size-4" />
+              Delete
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
       <div className="grid min-h-0 flex-1 grid-cols-[minmax(280px,360px)_1fr] overflow-hidden border-t border-border/50">
         <section className="flex min-h-0 flex-col border-r border-border/50 bg-muted/20">
           <div className="min-h-0 flex-1 overflow-auto p-2">
@@ -716,6 +830,12 @@ export default function AutomationsPage(): React.JSX.Element {
             onToggle={(automation) => void toggleAutomation(automation)}
             onDelete={requestDeleteAutomation}
           />
+          <ExternalAutomationManagers
+            managers={externalManagers}
+            now={relativeNow}
+            runningActionKey={externalActionKey}
+            onAction={requestExternalAction}
+          />
         </section>
       </div>
     </main>
diff --git a/src/renderer/src/components/automations/ExternalAutomationManagers.tsx b/src/renderer/src/components/automations/ExternalAutomationManagers.tsx
new file mode 100644
index 00000000000..865422a30cb
--- /dev/null
+++ b/src/renderer/src/components/automations/ExternalAutomationManagers.tsx
@@ -0,0 +1,197 @@
+import React from 'react'
+import { Pause, Play, RefreshCw, Trash2 } from 'lucide-react'
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import type {
+  ExternalAutomationAction,
+  ExternalAutomationJob,
+  ExternalAutomationManager
+} from '../../../../shared/automations-types'
+import { formatAutomationDateTimeWithRelative } from './automation-page-parts'
+
+type ExternalAutomationManagersProps = {
+  managers: ExternalAutomationManager[]
+  now: number
+  runningActionKey: string | null
+  onAction: (
+    manager: ExternalAutomationManager,
+    job: ExternalAutomationJob,
+    action: ExternalAutomationAction
+  ) => void
+}
+
+function formatExternalDate(value: string | null, now: number): string {
+  if (!value) {
+    return 'Never'
+  }
+  const parsed = Date.parse(value)
+  if (!Number.isFinite(parsed)) {
+    return value
+  }
+  return formatAutomationDateTimeWithRelative(parsed, now)
+}
+
+function actionKey(
+  manager: ExternalAutomationManager,
+  job: ExternalAutomationJob,
+  action: ExternalAutomationAction
+): string {
+  return `${manager.id}:${job.id}:${action}`
+}
+
+function ExternalActionButton({
+  label,
+  disabled,
+  className,
+  onClick,
+  children
+}: {
+  label: string
+  disabled: boolean
+  className?: string
+  onClick: () => void
+  children: React.ReactNode
+}): React.JSX.Element {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon-xs"
+          aria-label={label}
+          className={className}
+          disabled={disabled}
+          onClick={onClick}
+        >
+          {children}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom" sideOffset={6}>
+        {label}
+      </TooltipContent>
+    </Tooltip>
+  )
+}
+
+export function ExternalAutomationManagers({
+  managers,
+  now,
+  runningActionKey,
+  onAction
+}: ExternalAutomationManagersProps): React.JSX.Element {
+  return (
+    <div className="mt-6 rounded-md border border-border/50 bg-muted/20 shadow-sm">
+      <div className="flex items-center justify-between border-b border-border/50 px-3 py-2">
+        <div>
+          <div className="text-sm font-medium">External managers</div>
+        </div>
+        <Badge variant="outline">
+          {managers.reduce((sum, manager) => sum + manager.jobs.length, 0)} jobs
+        </Badge>
+      </div>
+      <div className="divide-y divide-border/50">
+        {managers.map((manager) => (
+          <div key={manager.id} className="px-3 py-3">
+            <div className="mb-2 flex items-center justify-between gap-3">
+              <div className="min-w-0">
+                <div className="truncate text-sm font-medium">{manager.label}</div>
+                <div className="text-xs text-muted-foreground">
+                  {manager.status === 'available'
+                    ? manager.canManage
+                      ? 'Manageable'
+                      : 'Read-only'
+                    : 'Unavailable'}
+                  {manager.error ? ` - ${manager.error}` : null}
+                </div>
+              </div>
+              <Badge variant={manager.status === 'available' ? 'secondary' : 'outline'}>
+                {manager.provider}
+              </Badge>
+            </div>
+            <div className="divide-y divide-border/40">
+              {manager.jobs.map((job) => (
+                <div
+                  key={job.id}
+                  className="grid grid-cols-[minmax(0,1fr)_minmax(8rem,auto)_auto] items-center gap-3 px-3 py-2 text-sm"
+                >
+                  <div className="min-w-0">
+                    <div className="flex min-w-0 items-center gap-2">
+                      <span className="truncate font-medium">{job.name}</span>
+                      <Badge variant={job.enabled ? 'secondary' : 'outline'}>
+                        {job.enabled ? 'Active' : 'Paused'}
+                      </Badge>
+                    </div>
+                    <div className="mt-1 truncate text-xs text-muted-foreground">
+                      {job.schedule} · next {formatExternalDate(job.nextRunAt, now)}
+                    </div>
+                    {job.promptPreview || job.lastError ? (
+                      <div className="mt-1 truncate text-xs text-muted-foreground">
+                        {job.lastError ?? job.promptPreview}
+                      </div>
+                    ) : null}
+                  </div>
+                  <div className="hidden min-w-0 text-xs text-muted-foreground md:block">
+                    Last {formatExternalDate(job.lastRunAt, now)}
+                    {job.lastStatus ? ` · ${job.lastStatus}` : null}
+                  </div>
+                  <div className="flex items-center justify-end gap-1">
+                    <ExternalActionButton
+                      label="Run external automation"
+                      disabled={!manager.canManage || runningActionKey !== null}
+                      onClick={() => onAction(manager, job, 'run')}
+                    >
+                      {runningActionKey === actionKey(manager, job, 'run') ? (
+                        <RefreshCw className="size-3.5 animate-spin" />
+                      ) : (
+                        <Play className="size-3.5" />
+                      )}
+                    </ExternalActionButton>
+                    <ExternalActionButton
+                      label={
+                        job.enabled ? 'Pause external automation' : 'Resume external automation'
+                      }
+                      disabled={!manager.canManage || runningActionKey !== null}
+                      onClick={() => onAction(manager, job, job.enabled ? 'pause' : 'resume')}
+                    >
+                      {runningActionKey ===
+                      actionKey(manager, job, job.enabled ? 'pause' : 'resume') ? (
+                        <RefreshCw className="size-3.5 animate-spin" />
+                      ) : job.enabled ? (
+                        <Pause className="size-3.5" />
+                      ) : (
+                        <Play className="size-3.5" />
+                      )}
+                    </ExternalActionButton>
+                    <ExternalActionButton
+                      label="Delete external automation"
+                      className="text-destructive hover:text-destructive"
+                      disabled={!manager.canManage || runningActionKey !== null}
+                      onClick={() => onAction(manager, job, 'delete')}
+                    >
+                      {runningActionKey === actionKey(manager, job, 'delete') ? (
+                        <RefreshCw className="size-3.5 animate-spin" />
+                      ) : (
+                        <Trash2 className="size-3.5" />
+                      )}
+                    </ExternalActionButton>
+                  </div>
+                </div>
+              ))}
+              {manager.jobs.length === 0 ? (
+                <div className="px-3 py-4 text-sm text-muted-foreground">
+                  No {manager.provider === 'hermes' ? 'Hermes' : 'OpenClaw'} jobs found.
+                </div>
+              ) : null}
+            </div>
+          </div>
+        ))}
+        {managers.length === 0 ? (
+          <div className="px-3 py-6 text-center text-sm text-muted-foreground">
+            No external automation managers found.
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/settings/agents-search.ts b/src/renderer/src/components/settings/agents-search.ts
index b82fe2e1d1c..3d384e529c1 100644
--- a/src/renderer/src/components/settings/agents-search.ts
+++ b/src/renderer/src/components/settings/agents-search.ts
@@ -29,6 +29,7 @@ export const AGENTS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
       'qwen',
       'rovo',
       'hermes',
+      'openclaw',
       'copilot',
       'github',
       'github copilot',
diff --git a/src/renderer/src/lib/agent-catalog.tsx b/src/renderer/src/lib/agent-catalog.tsx
index 37a8713d9f1..30cac2a6870 100644
--- a/src/renderer/src/lib/agent-catalog.tsx
+++ b/src/renderer/src/lib/agent-catalog.tsx
@@ -182,6 +182,13 @@ export const AGENT_CATALOG: AgentCatalogEntry[] = [
     cmd: 'hermes',
     faviconDomain: 'nousresearch.com',
     homepageUrl: 'https://hermes-agent.nousresearch.com/docs/'
+  },
+  {
+    id: 'openclaw',
+    label: 'OpenClaw',
+    cmd: 'openclaw',
+    faviconDomain: 'openclaw.ai',
+    homepageUrl: 'https://github.com/openclaw/openclaw'
   }
 ]
 
diff --git a/src/renderer/src/lib/agent-status.ts b/src/renderer/src/lib/agent-status.ts
index 7c02d7bf06d..7f38952f24d 100644
--- a/src/renderer/src/lib/agent-status.ts
+++ b/src/renderer/src/lib/agent-status.ts
@@ -165,6 +165,7 @@ const ICONABLE_AGENT_TYPES: Record<TuiAgent, true> = {
   'qwen-code': true,
   rovo: true,
   hermes: true,
+  openclaw: true,
   copilot: true
 }
 
diff --git a/src/shared/agent-detection.ts b/src/shared/agent-detection.ts
index e4181e30468..c2ea5e881aa 100644
--- a/src/shared/agent-detection.ts
+++ b/src/shared/agent-detection.ts
@@ -21,7 +21,16 @@ const GEMINI_PERMISSION = '\u270B' // ✋
 // unsafe under the substring-based detector and would classify ordinary shell
 // titles like "timestamp ready" as agent activity. Product telemetry uses the
 // explicit launch/session facts Orca owns, not this inference path.
-export const AGENT_NAMES = ['claude', 'codex', 'copilot', 'cursor', 'gemini', 'opencode', 'aider']
+export const AGENT_NAMES = [
+  'claude',
+  'codex',
+  'copilot',
+  'cursor',
+  'gemini',
+  'opencode',
+  'openclaw',
+  'aider'
+]
 
 // Why: `android` contains `droid`; unlike the legacy agent names above, Droid
 // must be token-matched so Android terminal titles do not become agent status.
diff --git a/src/shared/agent-kind.ts b/src/shared/agent-kind.ts
index efd1da48318..ef26793cb0f 100644
--- a/src/shared/agent-kind.ts
+++ b/src/shared/agent-kind.ts
@@ -37,6 +37,7 @@ const TUI_AGENT_KIND_BY_AGENT = {
   'qwen-code': 'qwen-code',
   rovo: 'rovo',
   hermes: 'hermes',
+  openclaw: 'openclaw',
   copilot: 'copilot'
 } satisfies Record<TuiAgent, ConcreteAgentKind>
 
diff --git a/src/shared/automations-types.ts b/src/shared/automations-types.ts
index e45ec5027d1..fcbc5d32dba 100644
--- a/src/shared/automations-types.ts
+++ b/src/shared/automations-types.ts
@@ -103,3 +103,51 @@ export type AutomationDispatchResult = {
   terminalSessionId?: string | null
   error?: string | null
 }
+
+export type ExternalAutomationProvider = 'hermes' | 'openclaw'
+export type ExternalAutomationManagerStatus = 'available' | 'unavailable'
+export type ExternalAutomationAction = 'pause' | 'resume' | 'run' | 'delete'
+
+export type ExternalAutomationTarget =
+  | {
+      type: 'local'
+    }
+  | {
+      type: 'ssh'
+      connectionId: string
+    }
+
+export type ExternalAutomationJob = {
+  id: string
+  managerId: string
+  provider: ExternalAutomationProvider
+  name: string
+  schedule: string
+  enabled: boolean
+  state: string
+  promptPreview: string
+  nextRunAt: string | null
+  lastRunAt: string | null
+  lastStatus: string | null
+  lastError: string | null
+  workdir: string | null
+}
+
+export type ExternalAutomationManager = {
+  id: string
+  provider: ExternalAutomationProvider
+  label: string
+  target: ExternalAutomationTarget
+  status: ExternalAutomationManagerStatus
+  error: string | null
+  canManage: boolean
+  jobs: ExternalAutomationJob[]
+}
+
+export type ExternalAutomationActionInput = {
+  managerId: string
+  provider: ExternalAutomationProvider
+  target: ExternalAutomationTarget
+  jobId: string
+  action: ExternalAutomationAction
+}
diff --git a/src/shared/telemetry-events.ts b/src/shared/telemetry-events.ts
index 0d7ad55339c..d5694770e55 100644
--- a/src/shared/telemetry-events.ts
+++ b/src/shared/telemetry-events.ts
@@ -58,6 +58,7 @@ export const AGENT_KIND_VALUES = [
   'qwen-code',
   'rovo',
   'hermes',
+  'openclaw',
   'copilot',
   'other'
 ] as const
diff --git a/src/shared/tui-agent-config.ts b/src/shared/tui-agent-config.ts
index dd41fc17e82..ad868812de8 100644
--- a/src/shared/tui-agent-config.ts
+++ b/src/shared/tui-agent-config.ts
@@ -211,6 +211,12 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     expectedProcess: 'hermes',
     promptInjectionMode: 'stdin-after-start'
   },
+  openclaw: {
+    detectCmd: 'openclaw',
+    launchCmd: 'openclaw',
+    expectedProcess: 'openclaw',
+    promptInjectionMode: 'stdin-after-start'
+  },
   copilot: {
     detectCmd: 'copilot',
     launchCmd: 'copilot',
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 1a2e09757fc..78d96705b9f 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1143,6 +1143,7 @@ export type TuiAgent =
   | 'qwen-code' // Qwen Code
   | 'rovo' // Rovo Dev
   | 'hermes' // Hermes Agent
+  | 'openclaw' // OpenClaw
   | 'copilot' // GitHub Copilot CLI
 
 export type TaskViewPresetId = 'all' | 'issues' | 'review' | 'my-issues' | 'my-prs' | 'prs'

From e461650780209a9b5c90ab48831553027b60e5e6 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:29:43 -0700
Subject: [PATCH 68/82] feat(linear): make issue list first-class (#1970)

* feat(linear): add two-pane issue workspace

* feat(linear): make issue list first-class

* chore: rerun linear list CI

* fix(linear): resolve main shortcut integration
---
 .../src/components/LinearIssueWorkspace.tsx   | 408 ++++++++++
 .../src/components/LinearItemDrawer.tsx       |  31 +-
 src/renderer/src/components/TaskPage.tsx      | 715 ++++++++----------
 .../components/linear-issue-workspace-text.ts |  46 ++
 .../components/task-page-cache-selectors.ts   |  17 +-
 5 files changed, 784 insertions(+), 433 deletions(-)
 create mode 100644 src/renderer/src/components/LinearIssueWorkspace.tsx
 create mode 100644 src/renderer/src/components/linear-issue-workspace-text.ts

diff --git a/src/renderer/src/components/LinearIssueWorkspace.tsx b/src/renderer/src/components/LinearIssueWorkspace.tsx
new file mode 100644
index 00000000000..373c8708297
--- /dev/null
+++ b/src/renderer/src/components/LinearIssueWorkspace.tsx
@@ -0,0 +1,408 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  ArrowRight,
+  Clipboard,
+  ExternalLink,
+  GitBranch,
+  LoaderCircle,
+  RefreshCw,
+  X
+} from 'lucide-react'
+import { toast } from 'sonner'
+import { VisuallyHidden } from 'radix-ui'
+
+import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
+import {
+  initLinearIssueEditState,
+  LinearIssueCommentFooter,
+  LinearIssueEditSection,
+  type LinearEditState,
+  type LinearLocalComment
+} from '@/components/LinearItemDrawer'
+import { Button } from '@/components/ui/button'
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from '@/components/ui/sheet'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { createBrowserUuid } from '@/lib/browser-uuid'
+import { useAppStore } from '@/store'
+import {
+  buildLinearIssueBranchName,
+  buildLinearIssuePrompt,
+  formatLinearIssueRelativeTime
+} from '@/components/linear-issue-workspace-text'
+import { linearGetIssue, linearIssueComments } from '@/runtime/runtime-linear-client'
+import type { LinearComment, LinearIssue } from '../../../shared/types'
+
+type LinearIssueWorkspaceProps = {
+  issue: LinearIssue | null
+  onUse: (issue: LinearIssue) => void
+  onClose: () => void
+}
+
+async function copyTextToClipboard(text: string, label: string): Promise<void> {
+  try {
+    await window.api.ui.writeClipboardText(text)
+    toast.success(`${label} copied`)
+  } catch {
+    toast.error(`Failed to copy ${label.toLowerCase()}`)
+  }
+}
+
+export default function LinearIssueWorkspace({
+  issue,
+  onUse,
+  onClose
+}: LinearIssueWorkspaceProps): React.JSX.Element {
+  const settings = useAppStore((s) => s.settings)
+  const [fullIssue, setFullIssue] = useState<LinearIssue | null>(null)
+  const [issueLoading, setIssueLoading] = useState(false)
+  const [comments, setComments] = useState<LinearComment[]>([])
+  const [commentsLoading, setCommentsLoading] = useState(false)
+  const [commentsError, setCommentsError] = useState<string | null>(null)
+  const [editState, setEditState] = useState<LinearEditState | null>(null)
+  const requestIdRef = useRef(0)
+  const hasEditedRef = useRef(false)
+  const optimisticCommentsRef = useRef<LinearComment[]>([])
+
+  const handleEditStateChange = useCallback((patch: Partial<LinearEditState>) => {
+    hasEditedRef.current = true
+    setEditState((prev) => (prev ? { ...prev, ...patch } : prev))
+  }, [])
+
+  const loadComments = useCallback(
+    async (targetIssue: LinearIssue, requestId: number): Promise<void> => {
+      setCommentsLoading(true)
+      setCommentsError(null)
+      try {
+        let fetched = (await linearIssueComments(
+          settings,
+          targetIssue.id,
+          targetIssue.workspaceId
+        )) as LinearComment[]
+        if (requestId !== requestIdRef.current) {
+          return
+        }
+        const optimistic = optimisticCommentsRef.current
+        if (optimistic.length > 0) {
+          const fetchedIds = new Set(fetched.map((comment) => comment.id))
+          fetched = [...fetched, ...optimistic.filter((comment) => !fetchedIds.has(comment.id))]
+        }
+        setComments(fetched)
+      } catch (error) {
+        if (requestId === requestIdRef.current) {
+          setCommentsError(error instanceof Error ? error.message : 'Failed to load comments.')
+        }
+      } finally {
+        if (requestId === requestIdRef.current) {
+          setCommentsLoading(false)
+        }
+      }
+    },
+    [settings]
+  )
+
+  useEffect(() => {
+    if (!issue) {
+      setFullIssue(null)
+      setIssueLoading(false)
+      setComments([])
+      setCommentsError(null)
+      setEditState(null)
+      hasEditedRef.current = false
+      optimisticCommentsRef.current = []
+      return
+    }
+
+    requestIdRef.current += 1
+    const requestId = requestIdRef.current
+    hasEditedRef.current = false
+    optimisticCommentsRef.current = []
+    setFullIssue(issue)
+    setEditState(initLinearIssueEditState(issue))
+    setComments([])
+    setCommentsError(null)
+    setIssueLoading(true)
+
+    // Why: issue hydration and comments are separate surfaces; a comments
+    // failure should not blank the issue detail the user selected.
+    void linearGetIssue(settings, issue.id, issue.workspaceId)
+      .then((issueResult) => {
+        if (requestId !== requestIdRef.current) {
+          return
+        }
+        if (issueResult) {
+          const fetched = issueResult as LinearIssue
+          setFullIssue(fetched)
+          if (!hasEditedRef.current) {
+            setEditState(initLinearIssueEditState(fetched))
+          }
+        }
+      })
+      .catch(() => {
+        /* The list issue remains useful if detail hydration is temporarily unavailable. */
+      })
+      .finally(() => {
+        if (requestId === requestIdRef.current) {
+          setIssueLoading(false)
+        }
+      })
+
+    void loadComments(issue, requestId)
+  }, [issue, loadComments, settings])
+
+  const displayed = fullIssue ?? issue
+
+  const handleCommentAdded = useCallback((comment: LinearLocalComment) => {
+    const newComment: LinearComment = {
+      id: comment.id || createBrowserUuid(),
+      body: comment.body,
+      createdAt: comment.createdAt,
+      user: { displayName: 'You' }
+    }
+    optimisticCommentsRef.current.push(newComment)
+    setComments((prev) => [...prev, newComment])
+  }, [])
+
+  const actionItems = useMemo(() => {
+    if (!displayed) {
+      return []
+    }
+    return [
+      {
+        label: 'Open in Linear',
+        icon: ExternalLink,
+        action: () => window.api.shell.openUrl(displayed.url)
+      },
+      {
+        label: 'Copy URL',
+        icon: Clipboard,
+        action: () => void copyTextToClipboard(displayed.url, 'URL')
+      },
+      {
+        label: 'Copy identifier',
+        icon: Clipboard,
+        action: () => void copyTextToClipboard(displayed.identifier, 'Identifier')
+      },
+      {
+        label: 'Copy suggested branch name',
+        icon: GitBranch,
+        action: () =>
+          void copyTextToClipboard(buildLinearIssueBranchName(displayed), 'Suggested branch name')
+      },
+      {
+        label: 'Copy prompt',
+        icon: Clipboard,
+        action: () => void copyTextToClipboard(buildLinearIssuePrompt(displayed), 'Prompt')
+      }
+    ]
+  }, [displayed])
+
+  return (
+    <Sheet open={issue !== null} onOpenChange={(open) => !open && onClose()}>
+      <SheetContent
+        side="right"
+        showCloseButton={false}
+        className="w-[min(92vw,760px)] p-0 sm:max-w-[760px]"
+        onOpenAutoFocus={(event) => {
+          event.preventDefault()
+        }}
+      >
+        <VisuallyHidden.Root asChild>
+          <SheetTitle>{displayed?.title ?? 'Linear issue'}</SheetTitle>
+        </VisuallyHidden.Root>
+        <VisuallyHidden.Root asChild>
+          <SheetDescription>
+            Preview, edit, and start work from the selected issue.
+          </SheetDescription>
+        </VisuallyHidden.Root>
+
+        {displayed ? (
+          <div className="flex h-full min-h-0 flex-col overflow-hidden bg-background">
+            <div className="flex-none border-b border-border/50 bg-muted/30 px-4 py-3">
+              <div className="flex items-start gap-3">
+                <div className="min-w-0 flex-1">
+                  <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-[11px] text-muted-foreground">
+                    <span className="font-mono">{displayed.identifier}</span>
+                    {displayed.workspaceName ? <span>{displayed.workspaceName}</span> : null}
+                    <span>{displayed.team.name}</span>
+                    <span>{formatLinearIssueRelativeTime(displayed.updatedAt)}</span>
+                    {issueLoading ? <LoaderCircle className="size-3 animate-spin" /> : null}
+                  </div>
+                  <h2 className="mt-1 text-[20px] font-semibold leading-tight text-foreground">
+                    {displayed.title}
+                  </h2>
+                </div>
+                <Button
+                  onClick={() => onUse(displayed)}
+                  className="hidden shrink-0 gap-2 sm:inline-flex"
+                  size="sm"
+                >
+                  Start workspace
+                  <ArrowRight className="size-4" />
+                </Button>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button
+                      variant="ghost"
+                      size="icon-sm"
+                      className="shrink-0"
+                      onClick={onClose}
+                      aria-label="Close Linear issue preview"
+                    >
+                      <X className="size-4" />
+                    </Button>
+                  </TooltipTrigger>
+                  <TooltipContent side="bottom" sideOffset={6}>
+                    Close
+                  </TooltipContent>
+                </Tooltip>
+              </div>
+            </div>
+
+            {editState ? (
+              <LinearIssueEditSection
+                issue={displayed}
+                editState={editState}
+                onEditStateChange={handleEditStateChange}
+              />
+            ) : null}
+
+            <div className="grid min-h-0 flex-1 grid-cols-1 xl:grid-cols-[minmax(0,1fr)_220px]">
+              <div className="min-h-0 overflow-y-auto scrollbar-sleek">
+                <section className="border-b border-border/40 px-4 py-4">
+                  <div className="mb-2 flex items-center gap-2">
+                    <span
+                      className="inline-block size-2 rounded-full"
+                      style={{ backgroundColor: displayed.state.color }}
+                    />
+                    <span className="text-xs font-medium text-foreground">
+                      {displayed.state.name}
+                    </span>
+                    <span className="text-xs text-muted-foreground">
+                      {displayed.assignee?.displayName ?? 'Unassigned'}
+                    </span>
+                  </div>
+                  {displayed.description?.trim() ? (
+                    <CommentMarkdown
+                      content={displayed.description}
+                      className="text-[14px] leading-relaxed"
+                    />
+                  ) : (
+                    <p className="text-sm italic text-muted-foreground">No description provided.</p>
+                  )}
+                </section>
+
+                <section className="px-4 py-4">
+                  <div className="mb-3 flex items-center justify-between gap-3">
+                    <div className="flex items-center gap-2">
+                      <span className="text-[13px] font-medium text-foreground">Comments</span>
+                      {comments.length > 0 ? (
+                        <span className="text-[12px] text-muted-foreground">{comments.length}</span>
+                      ) : null}
+                    </div>
+                    {commentsError ? (
+                      <Button
+                        variant="outline"
+                        size="xs"
+                        onClick={() => void loadComments(displayed, requestIdRef.current)}
+                        disabled={commentsLoading}
+                        className="gap-1"
+                      >
+                        {commentsLoading ? (
+                          <LoaderCircle className="size-3 animate-spin" />
+                        ) : (
+                          <RefreshCw className="size-3" />
+                        )}
+                        Retry
+                      </Button>
+                    ) : null}
+                  </div>
+
+                  {commentsError ? (
+                    <div className="rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+                      {commentsError}
+                    </div>
+                  ) : commentsLoading && comments.length === 0 ? (
+                    <div className="flex items-center justify-center py-8">
+                      <LoaderCircle className="size-4 animate-spin text-muted-foreground" />
+                    </div>
+                  ) : comments.length === 0 ? (
+                    <p className="text-sm text-muted-foreground">No comments yet.</p>
+                  ) : (
+                    <div className="flex flex-col gap-3">
+                      {comments.map((comment) => (
+                        <div
+                          key={comment.id}
+                          className="rounded-md border border-border/50 bg-muted/20"
+                        >
+                          <div className="flex min-w-0 items-center gap-2 border-b border-border/40 px-3 py-2">
+                            {comment.user?.avatarUrl ? (
+                              <img
+                                src={comment.user.avatarUrl}
+                                alt={comment.user.displayName}
+                                className="size-5 shrink-0 rounded-full"
+                              />
+                            ) : null}
+                            <span className="truncate text-[13px] font-semibold text-foreground">
+                              {comment.user?.displayName ?? 'Unknown'}
+                            </span>
+                            <span className="shrink-0 text-[12px] text-muted-foreground">
+                              {formatLinearIssueRelativeTime(comment.createdAt)}
+                            </span>
+                          </div>
+                          <div className="px-3 py-2">
+                            <CommentMarkdown
+                              content={comment.body}
+                              className="text-[13px] leading-relaxed"
+                            />
+                          </div>
+                        </div>
+                      ))}
+                    </div>
+                  )}
+                </section>
+              </div>
+
+              <aside className="border-t border-border/50 bg-muted/20 px-3 py-3 xl:border-l xl:border-t-0">
+                <Button
+                  onClick={() => onUse(displayed)}
+                  className="mb-3 w-full justify-center gap-2 sm:hidden"
+                >
+                  Start workspace
+                  <ArrowRight className="size-4" />
+                </Button>
+                <div className="grid gap-1">
+                  {actionItems.map((item) => {
+                    const Icon = item.icon
+                    return (
+                      <Tooltip key={item.label}>
+                        <TooltipTrigger asChild>
+                          <button
+                            type="button"
+                            onClick={item.action}
+                            className="flex min-w-0 items-center gap-2 rounded-md px-2 py-1.5 text-left text-xs text-muted-foreground transition hover:bg-accent hover:text-accent-foreground"
+                          >
+                            <Icon className="size-3.5 shrink-0" />
+                            <span className="truncate">{item.label}</span>
+                          </button>
+                        </TooltipTrigger>
+                        <TooltipContent side="left" sideOffset={6}>
+                          {item.label}
+                        </TooltipContent>
+                      </Tooltip>
+                    )
+                  })}
+                </div>
+              </aside>
+            </div>
+
+            <LinearIssueCommentFooter
+              issueId={displayed.id}
+              workspaceId={displayed.workspaceId}
+              onCommentAdded={handleCommentAdded}
+            />
+          </div>
+        ) : null}
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/src/renderer/src/components/LinearItemDrawer.tsx b/src/renderer/src/components/LinearItemDrawer.tsx
index 7f55e78f572..4977e09c75f 100644
--- a/src/renderer/src/components/LinearItemDrawer.tsx
+++ b/src/renderer/src/components/LinearItemDrawer.tsx
@@ -26,6 +26,8 @@ import {
   linearUpdateIssue
 } from '@/runtime/runtime-linear-client'
 
+const IS_MAC = navigator.userAgent.includes('Mac')
+
 function LinearIcon({ className }: { className?: string }): React.JSX.Element {
   return (
     <svg viewBox="0 0 24 24" aria-hidden className={className} fill="currentColor">
@@ -77,7 +79,7 @@ type LinearItemDrawerProps = {
   onClose: () => void
 }
 
-type LinearEditState = {
+export type LinearEditState = {
   state: LinearIssue['state']
   priority: number
   assignee: LinearIssue['assignee']
@@ -91,7 +93,11 @@ type EditSectionProps = {
   onEditStateChange: (patch: Partial<LinearEditState>) => void
 }
 
-function EditSection({ issue, editState, onEditStateChange }: EditSectionProps): React.JSX.Element {
+export function LinearIssueEditSection({
+  issue,
+  editState,
+  onEditStateChange
+}: EditSectionProps): React.JSX.Element {
   const [labelPopoverOpen, setLabelPopoverOpen] = useState(false)
   const patchLinearIssue = useAppStore((s) => s.patchLinearIssue)
   const settings = useAppStore((s) => s.settings)
@@ -433,16 +439,16 @@ function EditSection({ issue, editState, onEditStateChange }: EditSectionProps):
   )
 }
 
-type LocalComment = { id: string; body: string; createdAt: string }
+export type LinearLocalComment = { id: string; body: string; createdAt: string }
 
-function CommentFooter({
+export function LinearIssueCommentFooter({
   issueId,
   workspaceId,
   onCommentAdded
 }: {
   issueId: string
   workspaceId?: string | null
-  onCommentAdded: (comment: LocalComment) => void
+  onCommentAdded: (comment: LinearLocalComment) => void
 }): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
   const [body, setBody] = useState('')
@@ -486,7 +492,8 @@ function CommentFooter({
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
-      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      const mod = IS_MAC ? e.metaKey : e.ctrlKey
+      if (e.key === 'Enter' && mod) {
         e.preventDefault()
         handleSubmit()
       }
@@ -525,7 +532,7 @@ function CommentFooter({
   )
 }
 
-function initEditState(issue: LinearIssue): LinearEditState {
+export function initLinearIssueEditState(issue: LinearIssue): LinearEditState {
   return {
     state: issue.state,
     priority: issue.priority,
@@ -568,7 +575,7 @@ export default function LinearItemDrawer({
     optimisticCommentsRef.current = []
     setComments([])
     setCommentsLoading(true)
-    setEditState(initEditState(issue))
+    setEditState(initLinearIssueEditState(issue))
     requestIdRef.current += 1
     const requestId = requestIdRef.current
     setFullIssue(issue)
@@ -586,7 +593,7 @@ export default function LinearItemDrawer({
           // Why: skip if the user already made optimistic edits — the fetch
           // carries pre-edit data that would clobber in-flight changes.
           if (!hasEditedRef.current) {
-            setEditState(initEditState(fetched))
+            setEditState(initLinearIssueEditState(fetched))
           }
         }
       })
@@ -645,7 +652,7 @@ export default function LinearItemDrawer({
     }
   }, [issue?.id])
 
-  const handleCommentAdded = useCallback((comment: LocalComment) => {
+  const handleCommentAdded = useCallback((comment: LinearLocalComment) => {
     const newComment: LinearComment = {
       id: comment.id,
       body: comment.body,
@@ -733,7 +740,7 @@ export default function LinearItemDrawer({
 
             {/* Edit section */}
             {editState && (
-              <EditSection
+              <LinearIssueEditSection
                 issue={displayed}
                 editState={editState}
                 onEditStateChange={handleEditStateChange}
@@ -802,7 +809,7 @@ export default function LinearItemDrawer({
             </div>
 
             {/* Comment footer + Start workspace */}
-            <CommentFooter
+            <LinearIssueCommentFooter
               issueId={displayed.id}
               workspaceId={displayed.workspaceId}
               onCommentAdded={handleCommentAdded}
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index c059050d721..a5b260ae00f 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -62,7 +62,7 @@ import { stripRepoQualifiers } from '../../../shared/task-query'
 import GitHubItemDialog from '@/components/GitHubItemDialog'
 import GitLabItemDialog from '@/components/GitLabItemDialog'
 import ProjectViewWrapper from '@/components/github-project/ProjectViewWrapper'
-import LinearItemDrawer from '@/components/LinearItemDrawer'
+import LinearIssueWorkspace from '@/components/LinearIssueWorkspace'
 import { cn } from '@/lib/utils'
 import {
   getLinkedWorkItemSuggestedName,
@@ -72,11 +72,10 @@ import {
 } from '@/lib/new-workspace'
 import type { LinkedWorkItemSummary } from '@/lib/new-workspace'
 import { isGitRepoKind } from '../../../shared/repo-kind'
-import { useTeamStates } from '@/hooks/useIssueMetadata'
 import {
   buildTaskPageRepoSourceState,
   findTaskPageDialogWorkItem,
-  findTaskPageLinearDrawerIssue,
+  findTaskPageLinearIssue,
   selectTaskPageWorkItemsCacheEntries,
   type TaskPageRepoSourceState
 } from '@/components/task-page-cache-selectors'
@@ -91,12 +90,7 @@ import type {
   TaskViewPresetId
 } from '../../../shared/types'
 import { shouldSuppressEnterSubmit } from '@/lib/new-workspace-enter-guard'
-import {
-  linearCreateIssue,
-  linearGetIssue,
-  linearListTeams,
-  linearUpdateIssue
-} from '@/runtime/runtime-linear-client'
+import { linearCreateIssue, linearGetIssue, linearListTeams } from '@/runtime/runtime-linear-client'
 
 type TaskSource = 'github' | 'linear' | 'gitlab'
 
@@ -238,6 +232,20 @@ const LINEAR_PRIORITY_LABELS: Record<number, string> = {
   4: 'Low'
 }
 
+function getLinearPriorityLabel(priority: number): string {
+  return LINEAR_PRIORITY_LABELS[priority] ?? `P${priority}`
+}
+
+// Why: Linear state colors come from the user's workspace, so derive the
+// quiet pill tint from the source color instead of inventing app-local tones.
+function getLinearStatePillStyle(color: string): React.CSSProperties {
+  return {
+    borderColor: `color-mix(in srgb, ${color} 28%, transparent)`,
+    backgroundColor: `color-mix(in srgb, ${color} 10%, transparent)`,
+    color
+  }
+}
+
 function GHStatusCell({
   item,
   repo
@@ -366,225 +374,6 @@ function GHStatusCell({
   )
 }
 
-function LinearStatusCell({ issue }: { issue: LinearIssue }): React.JSX.Element {
-  const patchLinearIssue = useAppStore((s) => s.patchLinearIssue)
-  const fetchLinearIssue = useAppStore((s) => s.fetchLinearIssue)
-  const settings = useAppStore((s) => s.settings)
-  const [localState, setLocalState] = useState(issue.state)
-  const reqRef = useRef(0)
-
-  useEffect(() => {
-    setLocalState(issue.state)
-  }, [issue.state])
-
-  const teamId = issue.team?.id || null
-  const states = useTeamStates(teamId, settings, issue.workspaceId)
-
-  const handleStateChange = useCallback(
-    (stateId: string) => {
-      const newState = states.data.find((s) => s.id === stateId)
-      if (!newState) {
-        return
-      }
-
-      const stateValue = { name: newState.name, type: newState.type, color: newState.color }
-      reqRef.current += 1
-      const reqId = reqRef.current
-
-      setLocalState(stateValue)
-      patchLinearIssue(issue.id, { state: stateValue })
-      linearUpdateIssue(settings, issue.id, { stateId }, issue.workspaceId)
-        .then((result) => {
-          if (reqId !== reqRef.current) {
-            return
-          }
-          const typed = result as { ok?: boolean; error?: string }
-          if (typed && typed.ok === false) {
-            setLocalState(issue.state)
-            patchLinearIssue(issue.id, { state: issue.state })
-            toast.error(typed.error ?? 'Failed to update status')
-          } else {
-            fetchLinearIssue(issue.id, issue.workspaceId)
-          }
-        })
-        .catch(() => {
-          if (reqId !== reqRef.current) {
-            return
-          }
-          setLocalState(issue.state)
-          patchLinearIssue(issue.id, { state: issue.state })
-          toast.error('Failed to update status')
-        })
-    },
-    [
-      issue.id,
-      issue.state,
-      issue.workspaceId,
-      settings,
-      states.data,
-      patchLinearIssue,
-      fetchLinearIssue
-    ]
-  )
-
-  const currentStateId = states.data.find(
-    (s) => s.name === localState.name && s.type === localState.type
-  )?.id
-
-  const [open, setOpen] = useState(false)
-
-  return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger asChild>
-        <button
-          type="button"
-          onClick={(e) => e.stopPropagation()}
-          disabled={states.loading}
-          className="group/status flex items-center gap-1.5 rounded-sm px-1 py-0.5 transition hover:bg-muted/60 disabled:opacity-50"
-        >
-          <span
-            className="inline-block size-2 shrink-0 rounded-full"
-            style={{ backgroundColor: localState.color }}
-          />
-          <span className="truncate text-xs text-muted-foreground">{localState.name}</span>
-          <ChevronDown className="size-2.5 shrink-0 text-muted-foreground opacity-50" />
-        </button>
-      </PopoverTrigger>
-      <PopoverContent
-        className="popover-scroll-content scrollbar-sleek w-48 p-1"
-        align="start"
-        onClick={(e) => e.stopPropagation()}
-      >
-        <div>
-          {states.data.map((s) => (
-            <button
-              key={s.id}
-              type="button"
-              onClick={() => {
-                handleStateChange(s.id)
-                setOpen(false)
-              }}
-              className={cn(
-                'flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-[12px] hover:bg-accent',
-                currentStateId === s.id && 'bg-accent/50'
-              )}
-            >
-              <span
-                className="inline-block size-2 rounded-full"
-                style={{ backgroundColor: s.color }}
-              />
-              {s.name}
-            </button>
-          ))}
-        </div>
-      </PopoverContent>
-    </Popover>
-  )
-}
-
-function LinearPriorityCell({ issue }: { issue: LinearIssue }): React.JSX.Element {
-  const patchLinearIssue = useAppStore((s) => s.patchLinearIssue)
-  const fetchLinearIssue = useAppStore((s) => s.fetchLinearIssue)
-  const settings = useAppStore((s) => s.settings)
-  const [localPriority, setLocalPriority] = useState(issue.priority)
-  const [pending, setPending] = useState(false)
-  const reqRef = useRef(0)
-
-  useEffect(() => {
-    setLocalPriority(issue.priority)
-  }, [issue.priority])
-
-  const handlePriorityChange = useCallback(
-    (priority: number) => {
-      if (priority === localPriority) {
-        return
-      }
-      reqRef.current += 1
-      const reqId = reqRef.current
-      setLocalPriority(priority)
-      patchLinearIssue(issue.id, { priority })
-      setPending(true)
-      linearUpdateIssue(settings, issue.id, { priority }, issue.workspaceId)
-        .then((result) => {
-          if (reqId !== reqRef.current) {
-            return
-          }
-          const typed = result as { ok?: boolean; error?: string }
-          if (typed && typed.ok === false) {
-            setLocalPriority(issue.priority)
-            patchLinearIssue(issue.id, { priority: issue.priority })
-            toast.error(typed.error ?? 'Failed to update priority')
-          } else {
-            fetchLinearIssue(issue.id, issue.workspaceId)
-          }
-        })
-        .catch(() => {
-          if (reqId !== reqRef.current) {
-            return
-          }
-          setLocalPriority(issue.priority)
-          patchLinearIssue(issue.id, { priority: issue.priority })
-          toast.error('Failed to update priority')
-        })
-        .finally(() => {
-          if (reqId !== reqRef.current) {
-            return
-          }
-          setPending(false)
-        })
-    },
-    [
-      issue.id,
-      issue.priority,
-      issue.workspaceId,
-      localPriority,
-      settings,
-      patchLinearIssue,
-      fetchLinearIssue
-    ]
-  )
-
-  const [open, setOpen] = useState(false)
-
-  return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger asChild>
-        <button
-          type="button"
-          onClick={(e) => e.stopPropagation()}
-          disabled={pending}
-          className="group/priority inline-flex items-center gap-0.5 rounded-sm px-1 py-0.5 text-xs text-muted-foreground transition hover:bg-muted/60 disabled:opacity-50"
-        >
-          {LINEAR_PRIORITY_LABELS[localPriority] ?? `P${localPriority}`}
-          {pending ? (
-            <LoaderCircle className="ml-1 inline size-3 animate-spin" />
-          ) : (
-            <ChevronDown className="size-2.5 shrink-0 opacity-50" />
-          )}
-        </button>
-      </PopoverTrigger>
-      <PopoverContent className="w-36 p-1" align="start" onClick={(e) => e.stopPropagation()}>
-        {[0, 1, 2, 3, 4].map((p) => (
-          <button
-            key={p}
-            type="button"
-            onClick={() => {
-              handlePriorityChange(p)
-              setOpen(false)
-            }}
-            className={cn(
-              'flex w-full items-center rounded-sm px-2 py-1.5 text-[12px] hover:bg-accent',
-              localPriority === p && 'bg-accent/50'
-            )}
-          >
-            {LINEAR_PRIORITY_LABELS[p]}
-          </button>
-        ))}
-      </PopoverContent>
-    </Popover>
-  )
-}
-
 // Why: builds the page number array with ellipsis gaps, matching GitHub's
 // pagination pattern: always show first page, last page, and a window of
 // pages around the current page with "..." gaps between distant ranges.
@@ -1045,24 +834,31 @@ export default function TaskPage(): React.JSX.Element {
     [selectedRepos, newIssueRepoId]
   )
 
-  const [drawerLinearIssueId, setDrawerLinearIssueId] = useState<string | null>(null)
-  const [drawerLinearIssueFallback, setDrawerLinearIssueFallback] = useState<LinearIssue | null>(
-    null
-  )
+  const [selectedLinearIssueId, setSelectedLinearIssueId] = useState<string | null>(null)
+  const [selectedLinearIssueFallback, setSelectedLinearIssueFallback] =
+    useState<LinearIssue | null>(null)
 
-  // Why: the Linear table keeps its own fetched array, while cell edits patch
-  // the shared caches. The selector returns null while the drawer is closed, so
-  // unrelated Linear cache writes don't re-render the whole Tasks page.
-  const cachedDrawerLinearIssue = useAppStore((s) =>
-    findTaskPageLinearDrawerIssue(s.linearIssueCache, s.linearSearchCache, drawerLinearIssueId)
+  // Why: the Linear list keeps its own fetched array, while cell edits patch
+  // the shared caches. Subscribing to just the Linear caches lets the list and
+  // inline detail reflect optimistic mutations without a second durable cache.
+  const linearCacheSnapshot = useAppStore(
+    useShallow((s) => ({
+      issueCache: s.linearIssueCache,
+      searchCache: s.linearSearchCache
+    }))
   )
-  const drawerLinearIssue = drawerLinearIssueId
-    ? (cachedDrawerLinearIssue ?? drawerLinearIssueFallback)
+  const cachedSelectedLinearIssue = findTaskPageLinearIssue(
+    linearCacheSnapshot.issueCache,
+    linearCacheSnapshot.searchCache,
+    selectedLinearIssueId
+  )
+  const selectedLinearIssue = selectedLinearIssueId
+    ? (cachedSelectedLinearIssue ?? selectedLinearIssueFallback)
     : null
 
-  const setDrawerLinearIssue = useCallback((issue: LinearIssue | null) => {
-    setDrawerLinearIssueId(issue?.id ?? null)
-    setDrawerLinearIssueFallback(issue)
+  const setSelectedLinearIssue = useCallback((issue: LinearIssue | null) => {
+    setSelectedLinearIssueId(issue?.id ?? null)
+    setSelectedLinearIssueFallback(issue)
   }, [])
 
   // Linear tab state
@@ -1293,9 +1089,22 @@ export default function TaskPage(): React.JSX.Element {
     }
   }, [availableTeams, defaultLinearTeamSelection])
 
+  const displayedLinearIssues = useMemo(
+    () =>
+      linearIssues.map(
+        (issue) =>
+          findTaskPageLinearIssue(
+            linearCacheSnapshot.issueCache,
+            linearCacheSnapshot.searchCache,
+            issue.id
+          ) ?? issue
+      ),
+    [linearIssues, linearCacheSnapshot.issueCache, linearCacheSnapshot.searchCache]
+  )
+
   const filteredLinearIssues = useMemo(
-    () => linearIssues.filter((issue) => linearTeamSelection.has(issue.team.id)),
-    [linearIssues, linearTeamSelection]
+    () => displayedLinearIssues.filter((issue) => linearTeamSelection.has(issue.team.id)),
+    [displayedLinearIssues, linearTeamSelection]
   )
   // New Linear issue dialog state
   const [newLinearIssueOpen, setNewLinearIssueOpen] = useState(false)
@@ -1652,7 +1461,6 @@ export default function TaskPage(): React.JSX.Element {
       taskSource !== 'github' ||
       githubMode !== 'items' ||
       dialogWorkItem ||
-      drawerLinearIssue ||
       newIssueOpen ||
       newLinearIssueOpen ||
       activeModal !== 'none'
@@ -1690,15 +1498,7 @@ export default function TaskPage(): React.JSX.Element {
 
     window.addEventListener('keydown', onKeyDown, { capture: true })
     return () => window.removeEventListener('keydown', onKeyDown, { capture: true })
-  }, [
-    activeModal,
-    dialogWorkItem,
-    drawerLinearIssue,
-    githubMode,
-    newIssueOpen,
-    newLinearIssueOpen,
-    taskSource
-  ])
+  }, [activeModal, dialogWorkItem, githubMode, newIssueOpen, newLinearIssueOpen, taskSource])
 
   const openComposerForItem = useCallback(
     (item: GitHubWorkItem): void => {
@@ -1854,12 +1654,12 @@ export default function TaskPage(): React.JSX.Element {
       setNewLinearIssueBody('')
       setLinearRefreshNonce((n) => n + 1)
 
-      // Why: auto-open the new issue in the side drawer so the user sees
-      // exactly what was filed, mirroring the GitHub create-issue flow.
+      // Why: auto-select the new issue in the inline workspace so the user
+      // sees exactly what was filed, mirroring the GitHub create-issue flow.
       void linearGetIssue(settings, result.id, newLinearIssueTargetTeam.workspaceId)
         .then((full) => {
           if (full) {
-            setDrawerLinearIssue(full)
+            setSelectedLinearIssue(full)
           }
         })
         .catch(() => {})
@@ -1872,18 +1672,12 @@ export default function TaskPage(): React.JSX.Element {
     newLinearIssueTargetTeam,
     newLinearIssueTitle,
     settings,
-    setDrawerLinearIssue
+    setSelectedLinearIssue
   ])
 
   useEffect(() => {
     // Why: when a modal is open, let it own Esc dismissal.
-    if (
-      dialogWorkItem ||
-      drawerLinearIssue ||
-      newIssueOpen ||
-      newLinearIssueOpen ||
-      activeModal !== 'none'
-    ) {
+    if (dialogWorkItem || newIssueOpen || newLinearIssueOpen || activeModal !== 'none') {
       return
     }
 
@@ -1917,14 +1711,7 @@ export default function TaskPage(): React.JSX.Element {
 
     window.addEventListener('keydown', onKeyDown, { capture: true })
     return () => window.removeEventListener('keydown', onKeyDown, { capture: true })
-  }, [
-    activeModal,
-    closeTaskPage,
-    dialogWorkItem,
-    drawerLinearIssue,
-    newIssueOpen,
-    newLinearIssueOpen
-  ])
+  }, [activeModal, closeTaskPage, dialogWorkItem, newIssueOpen, newLinearIssueOpen])
 
   // Why: check Linear connection status on mount so the UI can show the
   // correct connected/disconnected state without requiring a settings visit.
@@ -2012,6 +1799,44 @@ export default function TaskPage(): React.JSX.Element {
     taskResumeApplied
   ])
 
+  useEffect(() => {
+    if (!taskResumeApplied || taskSource !== 'linear') {
+      return
+    }
+
+    if (!linearStatus.connected || filteredLinearIssues.length === 0) {
+      if (selectedLinearIssueId !== null) {
+        setSelectedLinearIssueId(null)
+      }
+      if (selectedLinearIssueFallback !== null) {
+        setSelectedLinearIssueFallback(null)
+      }
+      return
+    }
+
+    // Why: the corrected Linear surface is list-first. Keep an open inspector
+    // only while its issue remains in the current filter instead of auto-opening
+    // the first row and turning the list back into navigation chrome.
+    if (
+      selectedLinearIssueId &&
+      !filteredLinearIssues.some((issue) => issue.id === selectedLinearIssueId)
+    ) {
+      if (selectedLinearIssueId !== null) {
+        setSelectedLinearIssueId(null)
+      }
+      if (selectedLinearIssueFallback !== null) {
+        setSelectedLinearIssueFallback(null)
+      }
+    }
+  }, [
+    filteredLinearIssues,
+    linearStatus.connected,
+    selectedLinearIssueFallback,
+    selectedLinearIssueId,
+    taskResumeApplied,
+    taskSource
+  ])
+
   // Why: for Linear issues the "Use" flow opens the composer with the issue
   // info adapted to the LinkedWorkItemSummary shape. Linear identifiers are
   // strings (e.g. "ENG-123") so we use 0 as a placeholder number since the
@@ -2143,6 +1968,11 @@ export default function TaskPage(): React.JSX.Element {
                         <Select
                           value={selectedLinearWorkspaceId ?? undefined}
                           onValueChange={(value) => {
+                            setSelectedLinearIssueId(null)
+                            setSelectedLinearIssueFallback(null)
+                            setLinearIssues([])
+                            setLinearError(null)
+                            setLinearLoading(true)
                             void selectLinearWorkspace(value).catch(() => {
                               toast.error('Failed to switch Linear workspace.')
                             })
@@ -3137,20 +2967,29 @@ export default function TaskPage(): React.JSX.Element {
               </Button>
             </div>
           ) : (
-            /* Connected state: Linear issues table */
-            <div className="flex min-h-0 max-h-full flex-col rounded-md border border-t-0 border-border/50 bg-muted/50 overflow-hidden rounded-t-none shadow-sm">
-              <div className="flex-none grid grid-cols-[90px_minmax(0,3fr)_100px_120px_80px_90px_80px] gap-3 border-b border-border/50 px-3 py-2 text-[10px] font-medium uppercase tracking-[0.16em] text-muted-foreground">
-                <span>Identifier</span>
-                <span>Title</span>
-                <span>Team</span>
-                <span>Status</span>
+            <div className="flex min-h-0 max-h-full flex-col overflow-hidden rounded-md rounded-t-none border border-t-0 border-border/50 bg-background shadow-sm">
+              <div className="flex h-10 flex-none items-center justify-between gap-3 border-b border-border/50 bg-muted/35 px-3">
+                <div className="min-w-0 text-[11px] font-medium uppercase tracking-[0.12em] text-muted-foreground">
+                  Linear issues
+                </div>
+                <div className="shrink-0 text-[11px] text-muted-foreground">
+                  {filteredLinearIssues.length} shown
+                </div>
+              </div>
+
+              <div className="grid h-8 flex-none grid-cols-[86px_minmax(0,1fr)_128px_92px_96px_64px] items-center gap-3 border-b border-border/50 bg-muted/25 px-3 text-[11px] font-medium uppercase tracking-[0.08em] text-muted-foreground max-md:!hidden lg:grid-cols-[92px_minmax(0,1.2fr)_132px_92px_136px_96px_64px] xl:grid-cols-[96px_minmax(0,1.4fr)_140px_92px_150px_160px_100px_72px]">
+                <span>Key</span>
+                <span>Issue</span>
+                <span>State</span>
                 <span>Priority</span>
+                <span className="block max-lg:!hidden">Assignee</span>
+                <span className="block max-xl:!hidden">Context</span>
                 <span>Updated</span>
                 <span />
               </div>
 
               <div
-                className="min-h-0 flex-initial overflow-y-auto scrollbar-sleek"
+                className="min-h-0 flex-1 overflow-y-auto scrollbar-sleek"
                 style={{ scrollbarGutter: 'stable' }}
               >
                 {linearError ? (
@@ -3160,36 +2999,11 @@ export default function TaskPage(): React.JSX.Element {
                 ) : null}
 
                 {linearLoading && linearIssues.length === 0 ? (
-                  // Why: shimmer skeleton matches the GitHub tab pattern — 3 placeholder
-                  // rows while the initial fetch is in flight so the card never flashes empty.
                   <div className="divide-y divide-border/50">
-                    {Array.from({ length: 3 }).map((_, i) => (
-                      <div
-                        key={i}
-                        className="grid w-full gap-2 px-3 py-2 grid-cols-[90px_minmax(0,3fr)_100px_120px_80px_90px_80px]"
-                      >
-                        <div className="flex items-center">
-                          <div className="h-7 w-16 animate-pulse rounded-lg bg-muted/70" />
-                        </div>
-                        <div className="min-w-0">
-                          <div className="h-4 w-3/5 animate-pulse rounded bg-muted/70" />
-                          <div className="mt-2 h-3 w-2/5 animate-pulse rounded bg-muted/60" />
-                        </div>
-                        <div className="flex items-center">
-                          <div className="h-3 w-16 animate-pulse rounded bg-muted/60" />
-                        </div>
-                        <div className="flex items-center">
-                          <div className="h-5 w-16 animate-pulse rounded-full bg-muted/70" />
-                        </div>
-                        <div className="flex items-center">
-                          <div className="h-3 w-12 animate-pulse rounded bg-muted/60" />
-                        </div>
-                        <div className="flex items-center">
-                          <div className="h-3 w-16 animate-pulse rounded bg-muted/60" />
-                        </div>
-                        <div className="flex items-center justify-start lg:justify-end">
-                          <div className="h-7 w-16 animate-pulse rounded-xl bg-muted/70" />
-                        </div>
+                    {Array.from({ length: 6 }).map((_, i) => (
+                      <div key={i} className="px-3 py-3">
+                        <div className="h-4 w-4/5 animate-pulse rounded bg-muted/70" />
+                        <div className="mt-2 h-3 w-3/5 animate-pulse rounded bg-muted/60" />
                       </div>
                     ))}
                   </div>
@@ -3197,7 +3011,7 @@ export default function TaskPage(): React.JSX.Element {
 
                 {!linearLoading && linearIssues.length === 0 && !linearError ? (
                   <div className="px-4 py-10 text-center">
-                    <p className="text-base font-medium text-foreground">No Linear issues found</p>
+                    <p className="text-sm font-medium text-foreground">No Linear issues found</p>
                     <p className="mt-2 text-sm text-muted-foreground">
                       {linearSearchInput
                         ? 'Try a different search query.'
@@ -3208,7 +3022,7 @@ export default function TaskPage(): React.JSX.Element {
 
                 {!linearLoading && linearIssues.length > 0 && filteredLinearIssues.length === 0 ? (
                   <div className="px-4 py-10 text-center">
-                    <p className="text-base font-medium text-foreground">
+                    <p className="text-sm font-medium text-foreground">
                       No issues match the selected teams
                     </p>
                     <p className="mt-2 text-sm text-muted-foreground">
@@ -3218,106 +3032,188 @@ export default function TaskPage(): React.JSX.Element {
                 ) : null}
 
                 <div className="divide-y divide-border/50">
-                  {filteredLinearIssues.map((issue) => (
-                    <div
-                      key={issue.id}
-                      role="button"
-                      tabIndex={0}
-                      onClick={() => setDrawerLinearIssue(issue)}
-                      onKeyDown={(e) => {
-                        if (e.key === 'Enter' || e.key === ' ') {
-                          e.preventDefault()
-                          setDrawerLinearIssue(issue)
-                        }
-                      }}
-                      className="cursor-pointer grid w-full gap-2 px-3 py-2 text-left transition hover:bg-muted/40 grid-cols-[90px_minmax(0,3fr)_100px_120px_80px_90px_80px]"
-                    >
-                      <div className="flex items-center">
-                        <span className="inline-flex items-center gap-1 rounded-md border border-border/50 bg-muted/40 px-1.5 py-0.5 text-muted-foreground">
-                          <span className="font-mono text-[11px] font-normal">
-                            {issue.identifier}
-                          </span>
+                  {filteredLinearIssues.map((issue) => {
+                    const selected = issue.id === selectedLinearIssueId
+                    const labels = issue.labels.slice(0, 3)
+                    const contextLabel =
+                      selectedLinearWorkspaceId === 'all' && issue.workspaceName
+                        ? `${issue.workspaceName} / ${issue.team.name}`
+                        : issue.team.name
+                    return (
+                      <div
+                        key={issue.id}
+                        role="button"
+                        tabIndex={0}
+                        aria-current={selected ? 'true' : undefined}
+                        data-current={selected ? 'true' : undefined}
+                        onClick={() => {
+                          setSelectedLinearIssue(issue)
+                        }}
+                        onKeyDown={(e) => {
+                          if (e.target !== e.currentTarget) {
+                            return
+                          }
+                          if (e.key === 'Enter' || e.key === ' ') {
+                            e.preventDefault()
+                            setSelectedLinearIssue(issue)
+                          }
+                        }}
+                        className={cn(
+                          'group/row grid min-h-12 cursor-pointer grid-cols-[minmax(0,1fr)_auto] items-center gap-3 px-3 py-2 text-left transition hover:bg-accent focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring md:grid-cols-[86px_minmax(0,1fr)_128px_92px_96px_64px] lg:grid-cols-[92px_minmax(0,1.2fr)_132px_92px_136px_96px_64px] xl:grid-cols-[96px_minmax(0,1.4fr)_140px_92px_150px_160px_100px_72px]',
+                          selected && 'bg-accent'
+                        )}
+                      >
+                        <span className="block truncate font-mono text-[12px] text-muted-foreground max-md:!hidden">
+                          {issue.identifier}
                         </span>
-                      </div>
 
-                      <div className="min-w-0">
-                        <h3 className="truncate text-[15px] font-semibold text-foreground">
-                          {issue.title}
-                        </h3>
-                        <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
-                          {selectedLinearWorkspaceId === 'all' && issue.workspaceName ? (
-                            <span>{issue.workspaceName}</span>
-                          ) : null}
-                          {issue.assignee ? <span>{issue.assignee.displayName}</span> : null}
-                          {issue.labels.slice(0, 3).map((label) => (
-                            <span
-                              key={label}
-                              className="rounded-full border border-border/50 bg-background/80 px-1.5 py-0 text-[10px] text-muted-foreground"
-                            >
-                              {label}
+                        <div className="min-w-0">
+                          <div className="flex min-w-0 items-center gap-2">
+                            <span className="shrink-0 font-mono text-[11px] text-muted-foreground md:hidden">
+                              {issue.identifier}
                             </span>
-                          ))}
+                            <h3 className="min-w-0 truncate text-[13px] font-medium text-foreground">
+                              {issue.title}
+                            </h3>
+                          </div>
+                          <div className="mt-1 flex min-w-0 items-center gap-1.5 md:!hidden">
+                            <span
+                              className="inline-flex min-w-0 items-center gap-1 rounded-full border px-1.5 py-0.5 text-[11px] font-medium"
+                              style={getLinearStatePillStyle(issue.state.color)}
+                            >
+                              <span
+                                className="size-1.5 shrink-0 rounded-full"
+                                style={{ backgroundColor: issue.state.color }}
+                              />
+                              <span className="truncate">{issue.state.name}</span>
+                            </span>
+                            <span className="shrink-0 text-[11px] text-muted-foreground">
+                              {getLinearPriorityLabel(issue.priority)}
+                            </span>
+                            <span className="min-w-0 truncate text-[11px] text-muted-foreground">
+                              {issue.assignee?.displayName ?? 'Unassigned'}
+                            </span>
+                          </div>
+                          <div className="mt-1 flex min-w-0 items-center gap-1 max-lg:!hidden">
+                            <span className="max-w-[160px] truncate text-[10px] text-muted-foreground xl:!hidden">
+                              {contextLabel}
+                            </span>
+                            {labels.map((label) => (
+                              <span
+                                key={label}
+                                className="max-w-[140px] truncate rounded-full border border-border/50 bg-muted/35 px-1.5 py-0.5 text-[10px] text-muted-foreground"
+                              >
+                                {label}
+                              </span>
+                            ))}
+                            {issue.labels.length > labels.length ? (
+                              <span className="text-[10px] text-muted-foreground">
+                                +{issue.labels.length - labels.length}
+                              </span>
+                            ) : null}
+                          </div>
+                        </div>
+
+                        <div className="flex min-w-0 max-md:!hidden">
+                          <span
+                            className="inline-flex max-w-full items-center gap-1 rounded-full border px-2 py-0.5 text-[11px] font-medium"
+                            style={getLinearStatePillStyle(issue.state.color)}
+                          >
+                            <span
+                              className="size-1.5 shrink-0 rounded-full"
+                              style={{ backgroundColor: issue.state.color }}
+                            />
+                            <span className="truncate">{issue.state.name}</span>
+                          </span>
+                        </div>
+
+                        <span className="block truncate text-[12px] text-muted-foreground max-md:!hidden">
+                          {getLinearPriorityLabel(issue.priority)}
+                        </span>
+
+                        <div className="flex min-w-0 items-center gap-2 text-[12px] text-muted-foreground max-lg:!hidden">
+                          {issue.assignee?.avatarUrl ? (
+                            <img
+                              src={issue.assignee.avatarUrl}
+                              alt={issue.assignee.displayName}
+                              className="size-5 shrink-0 rounded-full"
+                            />
+                          ) : (
+                            <span className="flex size-5 shrink-0 items-center justify-center rounded-full border border-border/50 bg-muted/40 text-[10px]">
+                              {issue.assignee?.displayName?.slice(0, 1) ?? '-'}
+                            </span>
+                          )}
+                          <span className="truncate">
+                            {issue.assignee?.displayName ?? 'Unassigned'}
+                          </span>
+                        </div>
+
+                        <div className="block min-w-0 text-[12px] text-muted-foreground max-xl:!hidden">
+                          {selectedLinearWorkspaceId === 'all' && issue.workspaceName ? (
+                            <div className="truncate">{issue.workspaceName}</div>
+                          ) : null}
+                          <div className="truncate">{issue.team.name}</div>
+                        </div>
+
+                        <Tooltip>
+                          <TooltipTrigger asChild>
+                            <div className="block min-w-0 truncate text-[12px] text-muted-foreground max-md:!hidden">
+                              {formatRelativeTime(issue.updatedAt)}
+                            </div>
+                          </TooltipTrigger>
+                          <TooltipContent side="bottom" sideOffset={6}>
+                            {new Date(issue.updatedAt).toLocaleString()}
+                          </TooltipContent>
+                        </Tooltip>
+
+                        <div className="flex shrink-0 items-center justify-end gap-1 md:opacity-0 md:transition-opacity md:group-hover/row:opacity-100 md:group-focus-within/row:opacity-100">
+                          <Tooltip>
+                            <TooltipTrigger asChild>
+                              <Button
+                                variant="ghost"
+                                size="icon-xs"
+                                onClick={(event) => {
+                                  event.stopPropagation()
+                                  handleUseLinearItem(issue)
+                                }}
+                                aria-label={`Start workspace from ${issue.identifier}`}
+                              >
+                                <ArrowRight className="size-3.5" />
+                              </Button>
+                            </TooltipTrigger>
+                            <TooltipContent side="bottom" sideOffset={6}>
+                              Start workspace
+                            </TooltipContent>
+                          </Tooltip>
+                          <Tooltip>
+                            <TooltipTrigger asChild>
+                              <Button
+                                variant="ghost"
+                                size="icon-xs"
+                                onClick={(event) => {
+                                  event.stopPropagation()
+                                  window.api.shell.openUrl(issue.url)
+                                }}
+                                aria-label={`Open ${issue.identifier} in Linear`}
+                              >
+                                <ExternalLink className="size-3.5" />
+                              </Button>
+                            </TooltipTrigger>
+                            <TooltipContent side="bottom" sideOffset={6}>
+                              Open in Linear
+                            </TooltipContent>
+                          </Tooltip>
                         </div>
                       </div>
-
-                      <div className="min-w-0 flex items-center text-xs text-muted-foreground">
-                        <span className="truncate">{issue.team.name}</span>
-                      </div>
-
-                      <div className="flex items-center">
-                        <LinearStatusCell issue={issue} />
-                      </div>
-
-                      <div className="flex items-center">
-                        <LinearPriorityCell issue={issue} />
-                      </div>
-
-                      <Tooltip>
-                        <TooltipTrigger asChild>
-                          <div className="flex items-center text-[11px] text-muted-foreground">
-                            {formatRelativeTime(issue.updatedAt)}
-                          </div>
-                        </TooltipTrigger>
-                        <TooltipContent side="bottom" sideOffset={6}>
-                          {new Date(issue.updatedAt).toLocaleString()}
-                        </TooltipContent>
-                      </Tooltip>
-
-                      <div className="flex items-center justify-start gap-1 lg:justify-end">
-                        <button
-                          type="button"
-                          onClick={(e) => {
-                            e.stopPropagation()
-                            handleUseLinearItem(issue)
-                          }}
-                          className="inline-flex items-center gap-1 rounded-md border border-border/50 bg-background/80 px-2 py-1 text-[11px] text-foreground transition hover:bg-muted/60"
-                        >
-                          Use
-                          <ArrowRight className="size-3" />
-                        </button>
-                        <DropdownMenu modal={false}>
-                          <DropdownMenuTrigger asChild>
-                            <button
-                              type="button"
-                              onClick={(e) => e.stopPropagation()}
-                              className="rounded-lg p-1.5 text-muted-foreground transition hover:bg-muted/60 hover:text-foreground"
-                              aria-label="More actions"
-                            >
-                              <EllipsisVertical className="size-4" />
-                            </button>
-                          </DropdownMenuTrigger>
-                          <DropdownMenuContent align="end" onClick={(e) => e.stopPropagation()}>
-                            <DropdownMenuItem onSelect={() => window.api.shell.openUrl(issue.url)}>
-                              <ExternalLink className="size-4" />
-                              Open in browser
-                            </DropdownMenuItem>
-                          </DropdownMenuContent>
-                        </DropdownMenu>
-                      </div>
-                    </div>
-                  ))}
+                    )
+                  })}
                 </div>
               </div>
+              <LinearIssueWorkspace
+                issue={selectedLinearIssue}
+                onUse={handleUseLinearItem}
+                onClose={() => setSelectedLinearIssue(null)}
+              />
             </div>
           )}
         </div>
@@ -3620,15 +3516,6 @@ export default function TaskPage(): React.JSX.Element {
         onClose={() => setDialogWorkItem(null)}
       />
 
-      <LinearItemDrawer
-        issue={drawerLinearIssue}
-        onUse={(issue) => {
-          setDrawerLinearIssue(null)
-          handleUseLinearItem(issue)
-        }}
-        onClose={() => setDrawerLinearIssue(null)}
-      />
-
       <GitLabItemDialog
         item={gitlabDialogItem}
         // Why: dialog's repoPath has to come from the clicked item's
diff --git a/src/renderer/src/components/linear-issue-workspace-text.ts b/src/renderer/src/components/linear-issue-workspace-text.ts
new file mode 100644
index 00000000000..fdf6842f23e
--- /dev/null
+++ b/src/renderer/src/components/linear-issue-workspace-text.ts
@@ -0,0 +1,46 @@
+import { getLinkedWorkItemSuggestedName } from '@/lib/new-workspace'
+import type { LinearIssue } from '../../../shared/types'
+
+const relativeTimeFormatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' })
+
+export function formatLinearIssueRelativeTime(input: string): string {
+  const date = new Date(input)
+  if (Number.isNaN(date.getTime())) {
+    return 'recently'
+  }
+  const diffMs = date.getTime() - Date.now()
+  const diffMinutes = Math.round(diffMs / 60_000)
+  if (Math.abs(diffMinutes) < 60) {
+    return relativeTimeFormatter.format(diffMinutes, 'minute')
+  }
+  const diffHours = Math.round(diffMinutes / 60)
+  if (Math.abs(diffHours) < 24) {
+    return relativeTimeFormatter.format(diffHours, 'hour')
+  }
+  const diffDays = Math.round(diffHours / 24)
+  return relativeTimeFormatter.format(diffDays, 'day')
+}
+
+export function buildLinearIssueBranchName(issue: LinearIssue): string {
+  const titleSlug = getLinkedWorkItemSuggestedName(issue)
+  const key = issue.identifier.toLowerCase()
+  return titleSlug ? `${key}-${titleSlug}` : key
+}
+
+export function buildLinearIssuePrompt(issue: LinearIssue): string {
+  const lines = [
+    `Linear issue: ${issue.identifier} ${issue.title}`,
+    `URL: ${issue.url}`,
+    `State: ${issue.state.name}`,
+    `Assignee: ${issue.assignee?.displayName ?? 'Unassigned'}`,
+    `Team: ${issue.team.name}`
+  ]
+  if (issue.workspaceName) {
+    lines.push(`Workspace: ${issue.workspaceName}`)
+  }
+  const description = issue.description?.trim()
+  if (description) {
+    lines.push('', 'Description:', description)
+  }
+  return lines.join('\n')
+}
diff --git a/src/renderer/src/components/task-page-cache-selectors.ts b/src/renderer/src/components/task-page-cache-selectors.ts
index 70789977467..977c974b7a6 100644
--- a/src/renderer/src/components/task-page-cache-selectors.ts
+++ b/src/renderer/src/components/task-page-cache-selectors.ts
@@ -70,22 +70,23 @@ export function findTaskPageDialogWorkItem(
   return null
 }
 
-export function findTaskPageLinearDrawerIssue(
+export function findTaskPageLinearIssue(
   linearIssueCache: LinearIssueCache,
   linearSearchCache: LinearSearchCache,
-  drawerLinearIssueId: string | null
+  linearIssueId: string | null
 ): LinearIssue | null {
-  if (!drawerLinearIssueId) {
+  if (!linearIssueId) {
     return null
   }
 
-  const cachedIssue = linearIssueCache[drawerLinearIssueId]?.data
-  if (cachedIssue) {
-    return cachedIssue
+  for (const entry of Object.values(linearIssueCache)) {
+    if (entry?.data?.id === linearIssueId) {
+      return entry.data
+    }
   }
 
   for (const entry of Object.values(linearSearchCache)) {
-    const found = entry?.data?.find((issue) => issue.id === drawerLinearIssueId)
+    const found = entry?.data?.find((issue) => issue.id === linearIssueId)
     if (found) {
       return found
     }
@@ -93,3 +94,5 @@ export function findTaskPageLinearDrawerIssue(
 
   return null
 }
+
+export const findTaskPageLinearDrawerIssue = findTaskPageLinearIssue

From 0fcf2e79257e0d4ae1b1086464e025cad190ec34 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:30:53 -0700
Subject: [PATCH 69/82] feat: add configurable markdown review notes (#1980)

---
 .../runtime-home-service.test.ts              |   1 +
 src/main/codex-accounts/service.test.ts       |   1 +
 src/renderer/src/assets/markdown-preview.css  | 211 ++++++++++++
 .../src/components/editor/EditorContent.tsx   |  10 +-
 .../src/components/editor/EditorPanel.tsx     |   7 +
 .../components/editor/EditorPanelHeader.tsx   |   8 +
 .../components/editor/EditorPanelShell.tsx    |   7 +
 .../src/components/editor/MarkdownPreview.tsx | 302 ++++++++++++++++--
 .../src/components/settings/GeneralPane.tsx   |  32 ++
 .../src/components/settings/general-search.ts |   5 +
 .../src/lib/markdown-review-notes.test.ts     |  63 ++++
 src/renderer/src/lib/markdown-review-notes.ts |  74 +++++
 src/shared/constants.ts                       |   1 +
 src/shared/types.ts                           |   2 +
 14 files changed, 697 insertions(+), 27 deletions(-)
 create mode 100644 src/renderer/src/lib/markdown-review-notes.test.ts
 create mode 100644 src/renderer/src/lib/markdown-review-notes.ts

diff --git a/src/main/codex-accounts/runtime-home-service.test.ts b/src/main/codex-accounts/runtime-home-service.test.ts
index d2d914e14ef..50b31ee9f5c 100644
--- a/src/main/codex-accounts/runtime-home-service.test.ts
+++ b/src/main/codex-accounts/runtime-home-service.test.ts
@@ -42,6 +42,7 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     editorAutoSave: false,
     editorAutoSaveDelayMs: 1000,
     editorMinimapEnabled: false,
+    markdownReviewToolsEnabled: true,
     terminalFontSize: 14,
     terminalFontFamily: 'JetBrains Mono',
     terminalFontWeight: 500,
diff --git a/src/main/codex-accounts/service.test.ts b/src/main/codex-accounts/service.test.ts
index 89f82473d7d..40532ad3c8e 100644
--- a/src/main/codex-accounts/service.test.ts
+++ b/src/main/codex-accounts/service.test.ts
@@ -35,6 +35,7 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     editorAutoSave: false,
     editorAutoSaveDelayMs: 1000,
     editorMinimapEnabled: false,
+    markdownReviewToolsEnabled: true,
     terminalFontSize: 14,
     terminalFontFamily: 'JetBrains Mono',
     terminalFontWeight: 500,
diff --git a/src/renderer/src/assets/markdown-preview.css b/src/renderer/src/assets/markdown-preview.css
index 134c1147a8f..e7ace8cd465 100644
--- a/src/renderer/src/assets/markdown-preview.css
+++ b/src/renderer/src/assets/markdown-preview.css
@@ -210,6 +210,212 @@
   background: color-mix(in srgb, #fb923c 60%, transparent);
 }
 
+.markdown-review-toolbar {
+  position: sticky;
+  top: 0;
+  z-index: 15;
+  display: flex;
+  width: fit-content;
+  max-width: 100%;
+  align-items: center;
+  gap: 4px;
+  margin-left: auto;
+  margin-bottom: 8px;
+  padding: 4px;
+  border: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--background) 94%, var(--editor-surface));
+  box-shadow: 0 1px 2px color-mix(in srgb, var(--foreground) 12%, transparent);
+}
+
+.markdown-review-toolbar-button,
+.markdown-review-icon-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+  height: 26px;
+  border: 1px solid transparent;
+  border-radius: 5px;
+  background: transparent;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.markdown-review-toolbar-button {
+  gap: 6px;
+  padding: 0 8px;
+}
+
+.markdown-review-icon-button {
+  width: 26px;
+  padding: 0;
+}
+
+.markdown-review-toolbar-button:hover,
+.markdown-review-toolbar-button[aria-expanded='true'],
+.markdown-review-icon-button:hover:not(:disabled) {
+  border-color: color-mix(in srgb, var(--border) 82%, transparent);
+  background: var(--accent);
+  color: var(--foreground);
+}
+
+.markdown-review-icon-button:disabled {
+  cursor: default;
+  opacity: 0.45;
+}
+
+.markdown-review-count {
+  display: inline-flex;
+  min-width: 18px;
+  height: 18px;
+  align-items: center;
+  justify-content: center;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--foreground) 8%, transparent);
+  color: var(--muted-foreground);
+  font-size: 11px;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+
+.markdown-review-panel {
+  display: flex;
+  width: 310px;
+  min-width: 260px;
+  max-width: 36%;
+  flex-shrink: 0;
+  flex-direction: column;
+  border-left: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+  background: color-mix(in srgb, var(--background) 90%, var(--editor-surface));
+}
+
+.markdown-review-panel-header {
+  display: flex;
+  min-height: 40px;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+  padding: 0 8px 0 12px;
+}
+
+.markdown-review-panel-title,
+.markdown-review-panel-actions {
+  display: inline-flex;
+  min-width: 0;
+  align-items: center;
+  gap: 6px;
+}
+
+.markdown-review-panel-title {
+  color: var(--foreground);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.markdown-review-panel-actions {
+  flex-shrink: 0;
+  gap: 2px;
+}
+
+.markdown-review-note-list {
+  min-height: 0;
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px;
+}
+
+.markdown-review-empty {
+  padding: 8px 4px;
+  color: var(--muted-foreground);
+  font-size: 12px;
+  line-height: 1.45;
+}
+
+.markdown-review-note {
+  border: 1px solid transparent;
+  border-radius: 7px;
+  padding: 6px;
+}
+
+.markdown-review-note + .markdown-review-note {
+  margin-top: 8px;
+}
+
+.markdown-review-note.is-active {
+  border-color: color-mix(in srgb, var(--foreground) 28%, transparent);
+  background: color-mix(in srgb, var(--foreground) 5%, transparent);
+}
+
+.markdown-review-note-anchor {
+  display: flex;
+  width: 100%;
+  min-width: 0;
+  align-items: flex-start;
+  gap: 7px;
+  border: 0;
+  border-radius: 5px;
+  background: transparent;
+  padding: 4px 5px 6px;
+  color: inherit;
+  cursor: pointer;
+  text-align: left;
+}
+
+.markdown-review-note-anchor:hover {
+  background: var(--accent);
+}
+
+.markdown-review-note-line {
+  flex-shrink: 0;
+  color: var(--muted-foreground);
+  font-size: 11px;
+  font-variant-numeric: tabular-nums;
+  font-weight: 700;
+  line-height: 1.35;
+}
+
+.markdown-review-note-excerpt {
+  min-width: 0;
+  display: -webkit-box;
+  overflow: hidden;
+  color: var(--muted-foreground);
+  font-size: 11px;
+  line-height: 1.35;
+  white-space: pre-wrap;
+  word-break: break-word;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+}
+
+.markdown-review-note .orca-diff-comment-card {
+  max-width: none;
+}
+
+@media (max-width: 900px) {
+  .markdown-review-panel {
+    width: 260px;
+    max-width: 48%;
+  }
+}
+
+@container (max-width: 560px) {
+  .markdown-review-panel {
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 32;
+    width: min(310px, 82cqw);
+    min-width: 0;
+    max-width: calc(100cqw - 36px);
+    box-shadow: -10px 0 24px rgb(0 0 0 / 0.14);
+  }
+}
+
 .markdown-annotation-block {
   position: relative;
 }
@@ -260,6 +466,11 @@ li:focus-within > .markdown-annotation-controls > .markdown-annotation-add {
   margin-top: 6px;
 }
 
+.markdown-annotation-card.is-active > .orca-diff-comment-card {
+  border-color: color-mix(in srgb, var(--foreground) 32%, transparent);
+  background: color-mix(in srgb, var(--foreground) 8%, var(--editor-surface));
+}
+
 .markdown-annotation-composer {
   border: 1px solid color-mix(in srgb, var(--foreground) 18%, transparent);
   border-radius: 6px;
diff --git a/src/renderer/src/components/editor/EditorContent.tsx b/src/renderer/src/components/editor/EditorContent.tsx
index c7fd65722b4..4afce4ffa48 100644
--- a/src/renderer/src/components/editor/EditorContent.tsx
+++ b/src/renderer/src/components/editor/EditorContent.tsx
@@ -84,6 +84,7 @@ export function EditorContent({
   isChangesMode,
   sideBySide,
   showMarkdownTableOfContents = false,
+  markdownReviewToolsEnabled = true,
   onCloseMarkdownTableOfContents = () => {},
   pendingEditorReveal,
   handleContentChange,
@@ -106,6 +107,7 @@ export function EditorContent({
   isChangesMode: boolean
   sideBySide: boolean
   showMarkdownTableOfContents?: boolean
+  markdownReviewToolsEnabled?: boolean
   onCloseMarkdownTableOfContents?: () => void
   pendingEditorReveal: {
     filePath?: string
@@ -159,7 +161,7 @@ export function EditorContent({
       onContentChange={handleContentChange}
       onSave={isMarkdown ? md.mdSave : handleSave}
       worktreeId={activeFile.worktreeId}
-      markdownAnnotationsEnabled={isMarkdown && mdViewMode !== 'rich'}
+      markdownAnnotationsEnabled={markdownReviewToolsEnabled && isMarkdown && mdViewMode !== 'rich'}
       revealLine={
         pendingEditorReveal?.filePath === activeFile.filePath ? pendingEditorReveal.line : undefined
       }
@@ -281,7 +283,7 @@ export function EditorContent({
               scrollCacheKey={`${editorViewStateKey}:preview`}
               showTableOfContents={showMarkdownTableOfContents}
               onCloseTableOfContents={onCloseMarkdownTableOfContents}
-              markdownAnnotationsEnabled={mdViewMode !== 'rich'}
+              markdownAnnotationsEnabled={markdownReviewToolsEnabled && mdViewMode !== 'rich'}
               {...md.previewProps}
             />
           </div>
@@ -371,7 +373,7 @@ export function EditorContent({
           initialAnchor={activeFile.markdownPreviewAnchor ?? null}
           showTableOfContents={showMarkdownTableOfContents}
           onCloseTableOfContents={onCloseMarkdownTableOfContents}
-          markdownAnnotationsEnabled={mdViewMode !== 'rich'}
+          markdownAnnotationsEnabled={markdownReviewToolsEnabled && mdViewMode !== 'rich'}
           {...md.previewProps}
         />
       </div>
@@ -515,7 +517,7 @@ export function EditorContent({
             scrollCacheKey={`${diffViewStateKey}:preview`}
             showTableOfContents={showMarkdownTableOfContents}
             onCloseTableOfContents={onCloseMarkdownTableOfContents}
-            markdownAnnotationsEnabled
+            markdownAnnotationsEnabled={markdownReviewToolsEnabled}
             {...md.previewProps}
           />
         </div>
diff --git a/src/renderer/src/components/editor/EditorPanel.tsx b/src/renderer/src/components/editor/EditorPanel.tsx
index c0835db1e23..909098a6a66 100644
--- a/src/renderer/src/components/editor/EditorPanel.tsx
+++ b/src/renderer/src/components/editor/EditorPanel.tsx
@@ -48,6 +48,7 @@ function EditorPanelInner({
   const editorDrafts = useAppStore((s) => s.editorDrafts)
   const setEditorDraft = useAppStore((s) => s.setEditorDraft)
   const settings = useAppStore((s) => s.settings)
+  const updateSettings = useAppStore((s) => s.updateSettings)
   const panelRef = useRef<HTMLDivElement>(null)
   const [copiedPathToast, setCopiedPathToast] = useState<{ fileId: string; token: number } | null>(
     null
@@ -55,6 +56,7 @@ function EditorPanelInner({
   const [showMarkdownTableOfContents, setShowMarkdownTableOfContents] = useState(false)
   const [sideBySide, setSideBySide] = useState(settings?.diffDefaultView === 'side-by-side')
   const [prevDiffView, setPrevDiffView] = useState(settings?.diffDefaultView)
+  const markdownReviewToolsEnabled = settings?.markdownReviewToolsEnabled ?? true
 
   if (settings?.diffDefaultView !== prevDiffView) {
     setPrevDiffView(settings?.diffDefaultView)
@@ -252,6 +254,9 @@ function EditorPanelInner({
     }
     window.api.shell.openPath(activeFile.filePath)
   }
+  const handleToggleMarkdownReviewTools = (): void => {
+    void updateSettings({ markdownReviewToolsEnabled: !markdownReviewToolsEnabled })
+  }
   const disableRenameBrowse = Boolean(
     settingsForRuntimeOwner(
       settings,
@@ -268,6 +273,7 @@ function EditorPanelInner({
       model={model}
       copiedPathVisible={copiedPathToast?.fileId === activeFile.id}
       showMarkdownTableOfContents={showMarkdownTableOfContents}
+      markdownReviewToolsEnabled={markdownReviewToolsEnabled}
       sideBySide={sideBySide}
       fileContents={fileContents}
       diffContents={diffContents}
@@ -284,6 +290,7 @@ function EditorPanelInner({
       onToggleSideBySide={() => setSideBySide((prev) => !prev)}
       onEditorToggleChange={handleEditorToggleChange}
       onToggleMarkdownTableOfContents={() => setShowMarkdownTableOfContents((shown) => !shown)}
+      onToggleMarkdownReviewTools={handleToggleMarkdownReviewTools}
       onExportMarkdownToPdf={() => void exportActiveMarkdownToPdf()}
       onContentChange={handleContentChange}
       onDirtyStateHint={handleDirtyStateHint}
diff --git a/src/renderer/src/components/editor/EditorPanelHeader.tsx b/src/renderer/src/components/editor/EditorPanelHeader.tsx
index e9e63339b4d..f49ec831cf2 100644
--- a/src/renderer/src/components/editor/EditorPanelHeader.tsx
+++ b/src/renderer/src/components/editor/EditorPanelHeader.tsx
@@ -58,6 +58,7 @@ type EditorPanelHeaderProps = {
   canShowMarkdownTableOfContents: boolean
   isMarkdownTableOfContentsDisabled: boolean
   showMarkdownTableOfContents: boolean
+  markdownReviewToolsEnabled: boolean
   sideBySide: boolean
   openFileState: EditorHeaderOpenFileState
   onCopyPath: () => void
@@ -68,6 +69,7 @@ type EditorPanelHeaderProps = {
   onToggleSideBySide: () => void
   onEditorToggleChange: (next: EditorToggleValue) => void
   onToggleMarkdownTableOfContents: () => void
+  onToggleMarkdownReviewTools: () => void
   onExportMarkdownToPdf: () => void
 }
 
@@ -89,6 +91,7 @@ export function EditorPanelHeader({
   canShowMarkdownTableOfContents,
   isMarkdownTableOfContentsDisabled,
   showMarkdownTableOfContents,
+  markdownReviewToolsEnabled,
   sideBySide,
   openFileState,
   onCopyPath,
@@ -99,6 +102,7 @@ export function EditorPanelHeader({
   onToggleSideBySide,
   onEditorToggleChange,
   onToggleMarkdownTableOfContents,
+  onToggleMarkdownReviewTools,
   onExportMarkdownToPdf
 }: EditorPanelHeaderProps): React.JSX.Element {
   const [pathMenuOpen, setPathMenuOpen] = useState(false)
@@ -304,6 +308,10 @@ export function EditorPanelHeader({
             >
               Export as PDF
             </DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onSelect={onToggleMarkdownReviewTools}>
+              {markdownReviewToolsEnabled ? 'Hide Review Notes' : 'Show Review Notes'}
+            </DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>
       )}
diff --git a/src/renderer/src/components/editor/EditorPanelShell.tsx b/src/renderer/src/components/editor/EditorPanelShell.tsx
index f48d22855d1..11b66e1a1eb 100644
--- a/src/renderer/src/components/editor/EditorPanelShell.tsx
+++ b/src/renderer/src/components/editor/EditorPanelShell.tsx
@@ -18,6 +18,7 @@ type EditorPanelShellProps = {
   model: EditorPanelRenderModel
   copiedPathVisible: boolean
   showMarkdownTableOfContents: boolean
+  markdownReviewToolsEnabled: boolean
   sideBySide: boolean
   fileContents: Record<string, FileContent>
   diffContents: Record<string, DiffContent>
@@ -34,6 +35,7 @@ type EditorPanelShellProps = {
   onToggleSideBySide: () => void
   onEditorToggleChange: (next: EditorToggleValue) => void
   onToggleMarkdownTableOfContents: () => void
+  onToggleMarkdownReviewTools: () => void
   onExportMarkdownToPdf: () => void
   onContentChange: (content: string) => void
   onDirtyStateHint: (dirty: boolean) => void
@@ -51,6 +53,7 @@ export function EditorPanelShell({
   model,
   copiedPathVisible,
   showMarkdownTableOfContents,
+  markdownReviewToolsEnabled,
   sideBySide,
   fileContents,
   diffContents,
@@ -67,6 +70,7 @@ export function EditorPanelShell({
   onToggleSideBySide,
   onEditorToggleChange,
   onToggleMarkdownTableOfContents,
+  onToggleMarkdownReviewTools,
   onExportMarkdownToPdf,
   onContentChange,
   onDirtyStateHint,
@@ -97,6 +101,7 @@ export function EditorPanelShell({
           canShowMarkdownTableOfContents={model.canShowMarkdownTableOfContents}
           isMarkdownTableOfContentsDisabled={model.isMarkdownTableOfContentsDisabled}
           showMarkdownTableOfContents={showMarkdownTableOfContents}
+          markdownReviewToolsEnabled={markdownReviewToolsEnabled}
           sideBySide={sideBySide}
           openFileState={model.openFileState}
           onCopyPath={onCopyPath}
@@ -107,6 +112,7 @@ export function EditorPanelShell({
           onToggleSideBySide={onToggleSideBySide}
           onEditorToggleChange={onEditorToggleChange}
           onToggleMarkdownTableOfContents={onToggleMarkdownTableOfContents}
+          onToggleMarkdownReviewTools={onToggleMarkdownReviewTools}
           onExportMarkdownToPdf={onExportMarkdownToPdf}
         />
       )}
@@ -132,6 +138,7 @@ export function EditorPanelShell({
           handleSave={onSave}
           reloadFileContent={onReloadFileContent}
           showMarkdownTableOfContents={showMarkdownTableOfContents}
+          markdownReviewToolsEnabled={markdownReviewToolsEnabled}
           onCloseMarkdownTableOfContents={onCloseMarkdownTableOfContents}
         />
       </Suspense>
diff --git a/src/renderer/src/components/editor/MarkdownPreview.tsx b/src/renderer/src/components/editor/MarkdownPreview.tsx
index 038e6ba8a9e..90d755ce0c2 100644
--- a/src/renderer/src/components/editor/MarkdownPreview.tsx
+++ b/src/renderer/src/components/editor/MarkdownPreview.tsx
@@ -14,9 +14,24 @@ import rehypeSanitize, { defaultSchema } from 'rehype-sanitize'
 import rehypeSlug from 'rehype-slug'
 import GithubSlugger from 'github-slugger'
 import { extractFrontMatter } from './markdown-frontmatter'
-import { ChevronDown, ChevronUp, CornerDownLeft, Plus, X } from 'lucide-react'
+import {
+  Check,
+  ChevronDown,
+  ChevronUp,
+  Copy,
+  CornerDownLeft,
+  MessageSquare,
+  Plus,
+  Send,
+  X
+} from 'lucide-react'
 import type { Components } from 'react-markdown'
 import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
 import { Input } from '@/components/ui/input'
 import { useAppStore } from '@/store'
 import { toast } from 'sonner'
@@ -54,8 +69,16 @@ import { markdownPreviewUrlTransform } from './markdown-preview-url-transform'
 import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
 import { buildMarkdownTableOfContents } from './markdown-table-of-contents'
 import { MarkdownTableOfContentsPanel } from './MarkdownTableOfContentsPanel'
-import { isMarkdownComment } from '@/lib/diff-comment-compat'
+import { getDiffCommentLineLabel, isMarkdownComment } from '@/lib/diff-comment-compat'
 import { DiffCommentCard } from '../diff-comments/DiffCommentCard'
+import {
+  formatMarkdownReviewNotes,
+  getMarkdownReviewExcerpt,
+  sortMarkdownReviewNotes,
+  type MarkdownReviewNote
+} from '@/lib/markdown-review-notes'
+import { QuickLaunchAgentMenuItems } from '@/components/tab-bar/QuickLaunchButton'
+import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
 
 type MarkdownPreviewProps = {
   content: string
@@ -298,6 +321,20 @@ export default function MarkdownPreview({
   }, [frontMatter])
   const sluggerRef = useRef(new GithubSlugger())
   const [activeAnnotationBlockKey, setActiveAnnotationBlockKey] = useState<string | null>(null)
+  const [reviewPanelOpen, setReviewPanelOpen] = useState(false)
+  const [reviewNotesCopied, setReviewNotesCopied] = useState(false)
+  const [activeReviewCommentId, setActiveReviewCommentId] = useState<string | null>(null)
+  const markdownReviewNotes = useMemo(
+    () => sortMarkdownReviewNotes(markdownComments as MarkdownReviewNote[]),
+    [markdownComments]
+  )
+  const markdownReviewPrompt = useMemo(
+    () => formatMarkdownReviewNotes(markdownReviewNotes, renderedContent),
+    [markdownReviewNotes, renderedContent]
+  )
+  const canShowReviewTools = Boolean(
+    markdownAnnotationsEnabled && sourceWorktree && sourceRelativePath !== null
+  )
 
   // Why: each split pane needs its own markdown preview viewport even when the
   // underlying file is shared. The caller passes a pane-scoped cache key so
@@ -529,18 +566,56 @@ export default function MarkdownPreview({
     return () => window.removeEventListener('keydown', handleKeyDown, { capture: true })
   }, [closeSearch, isSearchOpen, openSearch])
 
+  const handleCopyMarkdownReviewNotes = useCallback(async (): Promise<void> => {
+    if (markdownReviewNotes.length === 0) {
+      return
+    }
+    try {
+      await window.api.ui.writeClipboardText(markdownReviewPrompt)
+      setReviewNotesCopied(true)
+    } catch {
+      // Best-effort clipboard action; failures usually mean the window is not focused.
+    }
+  }, [markdownReviewNotes.length, markdownReviewPrompt])
+
+  useEffect(() => {
+    if (!reviewNotesCopied) {
+      return
+    }
+    const timeout = window.setTimeout(() => setReviewNotesCopied(false), 1600)
+    return () => window.clearTimeout(timeout)
+  }, [reviewNotesCopied])
+
+  const scrollToReviewNote = useCallback((comment: DiffComment): void => {
+    setActiveReviewCommentId(comment.id)
+    const root = rootRef.current
+    if (!root) {
+      return
+    }
+    const blocks = root.querySelectorAll<HTMLElement>('[data-source-line][data-source-end-line]')
+    let target: HTMLElement | null = null
+    for (const block of blocks) {
+      const startLine = Number(block.dataset.sourceLine)
+      const endLine = Number(block.dataset.sourceEndLine)
+      if (startLine <= comment.lineNumber && comment.lineNumber <= endLine) {
+        target = block
+        break
+      }
+    }
+    target?.scrollIntoView({ behavior: 'smooth', block: 'center' })
+  }, [])
+
   const renderAnnotationControls = useCallback(
     (range: { startLine: number; endLine: number }, blockKey: string): React.ReactNode => {
       if (!sourceWorktree || sourceRelativePath === null) {
         return null
       }
+      if (!markdownAnnotationsEnabled) {
+        return null
+      }
       const commentsForBlock = markdownComments.filter(
         (comment) => range.startLine <= comment.lineNumber && comment.lineNumber <= range.endLine
       )
-      const canAuthor = markdownAnnotationsEnabled
-      if (!canAuthor && commentsForBlock.length === 0) {
-        return null
-      }
 
       const handleSubmit = async (body: string): Promise<boolean> => {
         const result = await addDiffComment({
@@ -561,21 +636,19 @@ export default function MarkdownPreview({
 
       return (
         <div className="markdown-annotation-controls">
-          {canAuthor ? (
-            <button
-              type="button"
-              className="markdown-annotation-add"
-              aria-label={`Add note on line ${range.startLine}`}
-              title="Add note"
-              onClick={(event) => {
-                event.preventDefault()
-                event.stopPropagation()
-                setActiveAnnotationBlockKey((current) => (current === blockKey ? null : blockKey))
-              }}
-            >
-              <Plus className="size-3" />
-            </button>
-          ) : null}
+          <button
+            type="button"
+            className="markdown-annotation-add"
+            aria-label={`Add note on line ${range.startLine}`}
+            title="Add note"
+            onClick={(event) => {
+              event.preventDefault()
+              event.stopPropagation()
+              setActiveAnnotationBlockKey((current) => (current === blockKey ? null : blockKey))
+            }}
+          >
+            <Plus className="size-3" />
+          </button>
           {activeAnnotationBlockKey === blockKey ? (
             <MarkdownAnnotationComposer
               lineNumber={range.endLine}
@@ -585,7 +658,12 @@ export default function MarkdownPreview({
             />
           ) : null}
           {commentsForBlock.map((comment) => (
-            <div key={comment.id} className="markdown-annotation-card">
+            <div
+              key={comment.id}
+              className={`markdown-annotation-card ${
+                activeReviewCommentId === comment.id ? 'is-active' : ''
+              }`.trim()}
+            >
               <DiffCommentCard
                 lineNumber={comment.lineNumber}
                 startLine={comment.startLine}
@@ -600,6 +678,7 @@ export default function MarkdownPreview({
     },
     [
       activeAnnotationBlockKey,
+      activeReviewCommentId,
       addDiffComment,
       deleteDiffComment,
       markdownAnnotationsEnabled,
@@ -946,7 +1025,7 @@ export default function MarkdownPreview({
         }
         const blockKey = `li:${range.startLine}-${range.endLine}`
         return (
-          <li {...props}>
+          <li {...props} data-source-line={range.startLine} data-source-end-line={range.endLine}>
             {children}
             {renderAnnotationControls(range, blockKey)}
           </li>
@@ -1118,6 +1197,55 @@ export default function MarkdownPreview({
             </Button>
           </div>
         ) : null}
+        {canShowReviewTools ? (
+          <div className="markdown-review-toolbar">
+            <button
+              type="button"
+              className="markdown-review-toolbar-button"
+              onClick={() => setReviewPanelOpen((open) => !open)}
+              aria-expanded={reviewPanelOpen}
+              title={reviewPanelOpen ? 'Hide review notes' : 'Show review notes'}
+            >
+              <MessageSquare className="size-3.5" />
+              <span>Review notes</span>
+              <span className="markdown-review-count">{markdownReviewNotes.length}</span>
+            </button>
+            <button
+              type="button"
+              className="markdown-review-icon-button"
+              onClick={() => void handleCopyMarkdownReviewNotes()}
+              disabled={markdownReviewNotes.length === 0}
+              title="Copy notes for agent"
+              aria-label="Copy notes for agent"
+            >
+              {reviewNotesCopied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+            </button>
+            {sourceWorktree ? (
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <button
+                    type="button"
+                    className="markdown-review-icon-button"
+                    disabled={markdownReviewNotes.length === 0}
+                    title="Send notes to a new agent"
+                    aria-label="Send notes to a new agent"
+                  >
+                    <Send className="size-3.5" />
+                  </button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="end" className="min-w-[180px]">
+                  <QuickLaunchAgentMenuItems
+                    worktreeId={sourceWorktree.id}
+                    groupId={sourceWorktree.id}
+                    onFocusTerminal={focusTerminalTabSurface}
+                    prompt={markdownReviewPrompt}
+                    launchSource="notes_send"
+                  />
+                </DropdownMenuContent>
+              </DropdownMenu>
+            ) : null}
+          </div>
+        ) : null}
         <div ref={bodyRef} className="markdown-body">
           {/* Why: remarkFrontmatter silently strips front-matter from rendered
         output. We extract it ourselves and render it as a styled code block so
@@ -1160,6 +1288,21 @@ export default function MarkdownPreview({
           </Markdown>
         </div>
       </div>
+      {canShowReviewTools && reviewPanelOpen && sourceWorktree ? (
+        <MarkdownReviewNotesPanel
+          notes={markdownReviewNotes}
+          content={renderedContent}
+          activeId={activeReviewCommentId}
+          copied={reviewNotesCopied}
+          onClose={() => setReviewPanelOpen(false)}
+          onCopy={() => void handleCopyMarkdownReviewNotes()}
+          onSelect={scrollToReviewNote}
+          onDelete={(id) => void deleteDiffComment(sourceWorktree.id, id)}
+          onSubmitEdit={(id, body) => updateDiffComment(sourceWorktree.id, id, body)}
+          prompt={markdownReviewPrompt}
+          worktreeId={sourceWorktree.id}
+        />
+      ) : null}
       {showTableOfContents ? (
         <MarkdownTableOfContentsPanel
           items={tableOfContentsItems}
@@ -1171,6 +1314,119 @@ export default function MarkdownPreview({
   )
 }
 
+function MarkdownReviewNotesPanel({
+  notes,
+  content,
+  activeId,
+  copied,
+  onClose,
+  onCopy,
+  onSelect,
+  onDelete,
+  onSubmitEdit,
+  prompt,
+  worktreeId
+}: {
+  notes: MarkdownReviewNote[]
+  content: string
+  activeId: string | null
+  copied: boolean
+  onClose: () => void
+  onCopy: () => void
+  onSelect: (note: MarkdownReviewNote) => void
+  onDelete: (id: string) => void
+  onSubmitEdit: (id: string, body: string) => Promise<boolean>
+  prompt: string
+  worktreeId: string
+}): React.JSX.Element {
+  return (
+    <aside className="markdown-review-panel">
+      <div className="markdown-review-panel-header">
+        <div className="markdown-review-panel-title">
+          <MessageSquare className="size-3.5" />
+          <span>Review notes</span>
+          <span className="markdown-review-count">{notes.length}</span>
+        </div>
+        <div className="markdown-review-panel-actions">
+          <button
+            type="button"
+            className="markdown-review-icon-button"
+            onClick={onCopy}
+            disabled={notes.length === 0}
+            title="Copy notes for agent"
+            aria-label="Copy notes for agent"
+          >
+            {copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+          </button>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <button
+                type="button"
+                className="markdown-review-icon-button"
+                disabled={notes.length === 0}
+                title="Send notes to a new agent"
+                aria-label="Send notes to a new agent"
+              >
+                <Send className="size-3.5" />
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="min-w-[180px]">
+              <QuickLaunchAgentMenuItems
+                worktreeId={worktreeId}
+                groupId={worktreeId}
+                onFocusTerminal={focusTerminalTabSurface}
+                prompt={prompt}
+                launchSource="notes_send"
+              />
+            </DropdownMenuContent>
+          </DropdownMenu>
+          <button
+            type="button"
+            className="markdown-review-icon-button"
+            onClick={onClose}
+            title="Close notes"
+            aria-label="Close notes"
+          >
+            <X className="size-3.5" />
+          </button>
+        </div>
+      </div>
+      <div className="markdown-review-note-list scrollbar-sleek">
+        {notes.length === 0 ? (
+          <div className="markdown-review-empty">No review notes for this file.</div>
+        ) : (
+          notes.map((note) => (
+            <div
+              key={note.id}
+              className={`markdown-review-note ${activeId === note.id ? 'is-active' : ''}`.trim()}
+            >
+              <button
+                type="button"
+                className="markdown-review-note-anchor"
+                onClick={() => onSelect(note)}
+              >
+                <span className="markdown-review-note-line">
+                  {getDiffCommentLineLabel(note, true)}
+                </span>
+                <span className="markdown-review-note-excerpt">
+                  {getMarkdownReviewExcerpt(content, note).replace(/^> /gm, '') || 'No preview'}
+                </span>
+              </button>
+              <DiffCommentCard
+                lineNumber={note.lineNumber}
+                startLine={note.startLine}
+                body={note.body}
+                onDelete={() => onDelete(note.id)}
+                onSubmitEdit={(body) => onSubmitEdit(note.id, body)}
+              />
+            </div>
+          ))
+        )}
+      </div>
+    </aside>
+  )
+}
+
 function MarkdownAnnotationComposer({
   lineNumber,
   startLine,
diff --git a/src/renderer/src/components/settings/GeneralPane.tsx b/src/renderer/src/components/settings/GeneralPane.tsx
index c5a9ae65964..28ff5016db2 100644
--- a/src/renderer/src/components/settings/GeneralPane.tsx
+++ b/src/renderer/src/components/settings/GeneralPane.tsx
@@ -434,6 +434,38 @@ export function GeneralPane({ settings, updateSettings }: GeneralPaneProps): Rea
             />
           </button>
         </SearchableSetting>
+
+        <SearchableSetting
+          title="Markdown Review Notes"
+          description="Show local markdown review note controls and the review panel."
+          keywords={['markdown', 'review', 'notes', 'annotations', 'agents']}
+          className="flex items-center justify-between gap-4 px-1 py-2"
+        >
+          <div className="space-y-0.5">
+            <Label>Markdown Review Notes</Label>
+            <p className="text-xs text-muted-foreground">
+              Show local markdown note controls, the review panel, and agent handoff actions.
+            </p>
+          </div>
+          <button
+            role="switch"
+            aria-checked={settings.markdownReviewToolsEnabled}
+            onClick={() =>
+              updateSettings({
+                markdownReviewToolsEnabled: !settings.markdownReviewToolsEnabled
+              })
+            }
+            className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-colors ${
+              settings.markdownReviewToolsEnabled ? 'bg-foreground' : 'bg-muted-foreground/30'
+            }`}
+          >
+            <span
+              className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
+                settings.markdownReviewToolsEnabled ? 'translate-x-4' : 'translate-x-0.5'
+              }`}
+            />
+          </button>
+        </SearchableSetting>
       </section>
     ) : null,
     matchesSettingsSearch(searchQuery, GENERAL_CLI_SEARCH_ENTRIES) ? (
diff --git a/src/renderer/src/components/settings/general-search.ts b/src/renderer/src/components/settings/general-search.ts
index cdb6dc733a2..26417f4d74a 100644
--- a/src/renderer/src/components/settings/general-search.ts
+++ b/src/renderer/src/components/settings/general-search.ts
@@ -43,6 +43,11 @@ export const GENERAL_EDITOR_SEARCH_ENTRIES: SettingsSearchEntry[] = [
     title: 'Minimap',
     description: 'Show the minimap overview when editing a file.',
     keywords: ['minimap', 'overview', 'code', 'scroll']
+  },
+  {
+    title: 'Markdown Review Notes',
+    description: 'Show local markdown review note controls and the review panel.',
+    keywords: ['markdown', 'review', 'notes', 'annotations', 'agents']
   }
 ]
 
diff --git a/src/renderer/src/lib/markdown-review-notes.test.ts b/src/renderer/src/lib/markdown-review-notes.test.ts
new file mode 100644
index 00000000000..b00b6e5e5cc
--- /dev/null
+++ b/src/renderer/src/lib/markdown-review-notes.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import type { DiffComment } from '../../../shared/types'
+import {
+  formatMarkdownReviewNotes,
+  getMarkdownReviewExcerpt,
+  sortMarkdownReviewNotes,
+  type MarkdownReviewNote
+} from './markdown-review-notes'
+
+function note(overrides: Partial<Omit<DiffComment, 'source'>> = {}): MarkdownReviewNote {
+  return {
+    id: 'n1',
+    worktreeId: 'wt1',
+    filePath: 'README.md',
+    source: 'markdown',
+    lineNumber: 2,
+    body: 'needs detail',
+    createdAt: 0,
+    side: 'modified',
+    ...overrides
+  }
+}
+
+describe('markdown review notes', () => {
+  it('sorts by file path, source line, then creation time', () => {
+    const sorted = sortMarkdownReviewNotes([
+      note({ id: 'later', lineNumber: 4, createdAt: 2 }),
+      note({ id: 'other-file', filePath: 'docs/a.md', lineNumber: 10 }),
+      note({ id: 'earlier', lineNumber: 4, createdAt: 1 }),
+      note({ id: 'first', lineNumber: 1 })
+    ])
+
+    expect(sorted.map((item) => item.id)).toEqual(['other-file', 'first', 'earlier', 'later'])
+  })
+
+  it('extracts the annotated markdown lines as quoted context', () => {
+    const excerpt = getMarkdownReviewExcerpt(
+      'one\ntwo\nthree',
+      note({ startLine: 2, lineNumber: 3 })
+    )
+
+    expect(excerpt).toBe('> two\n> three')
+  })
+
+  it('formats a deterministic prompt for terminal agents', () => {
+    const formatted = formatMarkdownReviewNotes(
+      [note({ startLine: 2, lineNumber: 3, body: 'replace "maybe"\nwith specifics' })],
+      'one\ntwo\nthree'
+    )
+
+    expect(formatted).toBe(
+      [
+        'File: README.md',
+        'Source: markdown',
+        'Lines 2-3',
+        'Excerpt:',
+        '> two',
+        '> three',
+        'User comment: "replace \\"maybe\\"\\nwith specifics"'
+      ].join('\n')
+    )
+  })
+})
diff --git a/src/renderer/src/lib/markdown-review-notes.ts b/src/renderer/src/lib/markdown-review-notes.ts
new file mode 100644
index 00000000000..be9167d4cd4
--- /dev/null
+++ b/src/renderer/src/lib/markdown-review-notes.ts
@@ -0,0 +1,74 @@
+import type { DiffComment } from '../../../shared/types'
+import { getDiffCommentLineLabel } from './diff-comment-compat'
+
+const MAX_EXCERPT_LINES = 8
+
+export type MarkdownReviewNote = DiffComment & { source: 'markdown' }
+
+export function sortMarkdownReviewNotes(
+  notes: readonly MarkdownReviewNote[]
+): MarkdownReviewNote[] {
+  return [...notes].sort((a, b) => {
+    const pathCompare = a.filePath.localeCompare(b.filePath)
+    if (pathCompare !== 0) {
+      return pathCompare
+    }
+    const startA = a.startLine ?? a.lineNumber
+    const startB = b.startLine ?? b.lineNumber
+    if (startA !== startB) {
+      return startA - startB
+    }
+    if (a.lineNumber !== b.lineNumber) {
+      return a.lineNumber - b.lineNumber
+    }
+    return a.createdAt - b.createdAt
+  })
+}
+
+export function getMarkdownReviewExcerpt(
+  content: string,
+  note: Pick<DiffComment, 'lineNumber' | 'startLine'>
+): string {
+  const lines = content.split(/\r?\n/)
+  const startLine = Math.max(1, note.startLine ?? note.lineNumber)
+  const endLine = Math.max(startLine, note.lineNumber)
+  const selected = lines.slice(startLine - 1, endLine)
+  if (selected.length === 0) {
+    return ''
+  }
+
+  const excerpt =
+    selected.length <= MAX_EXCERPT_LINES
+      ? selected
+      : [
+          ...selected.slice(0, Math.ceil(MAX_EXCERPT_LINES / 2)),
+          '...',
+          ...selected.slice(selected.length - Math.floor(MAX_EXCERPT_LINES / 2))
+        ]
+
+  return excerpt.map((line) => `> ${line}`).join('\n')
+}
+
+export function formatMarkdownReviewNotes(
+  notes: readonly MarkdownReviewNote[],
+  content: string
+): string {
+  return sortMarkdownReviewNotes(notes)
+    .map((note) => {
+      const escapedBody = note.body
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n')
+      const excerpt = getMarkdownReviewExcerpt(content, note)
+      const parts = [
+        `File: ${note.filePath}`,
+        'Source: markdown',
+        getDiffCommentLineLabel(note),
+        excerpt ? `Excerpt:\n${excerpt}` : null,
+        `User comment: "${escapedBody}"`
+      ]
+      return parts.filter((part): part is string => part !== null).join('\n')
+    })
+    .join('\n\n')
+}
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index ba5e93ebdcd..42270639004 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -164,6 +164,7 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     editorAutoSave: false,
     editorAutoSaveDelayMs: DEFAULT_EDITOR_AUTO_SAVE_DELAY_MS,
     editorMinimapEnabled: false,
+    markdownReviewToolsEnabled: true,
     terminalFontSize: 14,
     terminalFontFamily: defaultTerminalFontFamily(),
     terminalFontWeight: DEFAULT_TERMINAL_FONT_WEIGHT,
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 78d96705b9f..c6364d024b2 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1209,6 +1209,8 @@ export type GlobalSettings = {
   editorAutoSave: boolean
   editorAutoSaveDelayMs: number
   editorMinimapEnabled: boolean
+  /** Whether local markdown review note controls and the review panel are shown. */
+  markdownReviewToolsEnabled: boolean
   terminalFontSize: number
   terminalFontFamily: string
   terminalFontWeight: number

From e5c394b09b205317ebd1d347c14fbac634d92058 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 15 May 2026 13:36:06 -0700
Subject: [PATCH 70/82] Add pull request creation flow (#1960)

Co-authored-by: Orca <help@stably.ai>
---
 src/main/github/client-create-pr.test.ts      | 188 +++++++++
 src/main/github/client.ts                     | 223 +++++++++++
 src/main/github/gh-utils.ts                   |   4 +-
 src/main/ipc/hosted-review.ts                 |  59 ++-
 src/main/runtime/orca-runtime.ts              |  56 ++-
 .../runtime/rpc/methods/hosted-review.test.ts |  86 +++++
 src/main/runtime/rpc/methods/hosted-review.ts |  56 +++
 .../hosted-review-creation.test.ts            | 321 ++++++++++++++++
 .../source-control/hosted-review-creation.ts  | 323 ++++++++++++++++
 src/preload/api-types.ts                      |  13 +-
 src/preload/index.ts                          |   5 +-
 .../components/right-sidebar/ChecksPanel.tsx  | 211 +++++++++--
 .../right-sidebar/CreatePullRequestDialog.tsx | 357 ++++++++++++++++++
 .../right-sidebar/SourceControl.tsx           | 174 ++++++++-
 .../source-control-dropdown-items.test.ts     |  23 ++
 .../source-control-dropdown-items.ts          |  58 ++-
 .../source-control-primary-action.test.ts     |  22 ++
 .../source-control-primary-action.ts          |  26 +-
 .../src/store/slices/hosted-review.ts         |  56 ++-
 src/renderer/src/web/web-preload-api.ts       |   1 +
 src/shared/hosted-review-refs.test.ts         |  16 +
 src/shared/hosted-review-refs.ts              |  11 +
 src/shared/hosted-review.ts                   |  89 ++++-
 tests/e2e/source-control-create-pr.spec.ts    | 201 ++++++++++
 24 files changed, 2535 insertions(+), 44 deletions(-)
 create mode 100644 src/main/github/client-create-pr.test.ts
 create mode 100644 src/main/source-control/hosted-review-creation.test.ts
 create mode 100644 src/main/source-control/hosted-review-creation.ts
 create mode 100644 src/renderer/src/components/right-sidebar/CreatePullRequestDialog.tsx
 create mode 100644 src/shared/hosted-review-refs.test.ts
 create mode 100644 src/shared/hosted-review-refs.ts
 create mode 100644 tests/e2e/source-control-create-pr.spec.ts

diff --git a/src/main/github/client-create-pr.test.ts b/src/main/github/client-create-pr.test.ts
new file mode 100644
index 00000000000..907ef905ff8
--- /dev/null
+++ b/src/main/github/client-create-pr.test.ts
@@ -0,0 +1,188 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { ghExecFileAsyncMock, getOwnerRepoMock, extractExecErrorMock, acquireMock, releaseMock } =
+  vi.hoisted(() => ({
+    ghExecFileAsyncMock: vi.fn(),
+    getOwnerRepoMock: vi.fn(),
+    extractExecErrorMock: vi.fn((error: unknown) => {
+      const value = error as { stderr?: string; stdout?: string; message?: string }
+      return {
+        stderr: value?.stderr ?? value?.message ?? '',
+        stdout: value?.stdout ?? ''
+      }
+    }),
+    acquireMock: vi.fn(),
+    releaseMock: vi.fn()
+  }))
+
+vi.mock('./gh-utils', () => ({
+  execFileAsync: vi.fn(),
+  ghExecFileAsync: ghExecFileAsyncMock,
+  getOwnerRepo: getOwnerRepoMock,
+  getIssueOwnerRepo: vi.fn(),
+  getOwnerRepoForRemote: vi.fn(),
+  gitExecFileAsync: vi.fn(),
+  extractExecError: extractExecErrorMock,
+  parseGitHubOwnerRepo: vi.fn(),
+  acquire: acquireMock,
+  release: releaseMock,
+  _resetOwnerRepoCache: vi.fn()
+}))
+
+vi.mock('../git/runner', () => ({
+  gitExecFileAsync: vi.fn()
+}))
+
+import { createGitHubPullRequest } from './client'
+
+describe('createGitHubPullRequest', () => {
+  beforeEach(() => {
+    ghExecFileAsyncMock.mockReset()
+    getOwnerRepoMock.mockReset()
+    extractExecErrorMock.mockClear()
+    acquireMock.mockReset()
+    releaseMock.mockReset()
+    acquireMock.mockResolvedValue(undefined)
+  })
+
+  it('creates a GitHub pull request with normalized refs and a body file', async () => {
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'acme', repo: 'widgets' })
+    ghExecFileAsyncMock.mockResolvedValueOnce({
+      stdout: JSON.stringify({
+        number: 42,
+        url: 'https://github.com/acme/widgets/pull/42'
+      })
+    })
+
+    await expect(
+      createGitHubPullRequest('/repo-root', {
+        provider: 'github',
+        base: 'origin/main',
+        head: 'refs/heads/feature/create-pr',
+        title: '  Create PR UI  ',
+        body: 'Body text',
+        draft: true
+      })
+    ).resolves.toEqual({
+      ok: true,
+      number: 42,
+      url: 'https://github.com/acme/widgets/pull/42'
+    })
+
+    const [args, options] = ghExecFileAsyncMock.mock.calls[0]
+    expect(args).toEqual(
+      expect.arrayContaining([
+        'pr',
+        'create',
+        '--repo',
+        'acme/widgets',
+        '--base',
+        'main',
+        '--head',
+        'feature/create-pr',
+        '--title',
+        'Create PR UI',
+        '--draft'
+      ])
+    )
+    expect(args[args.indexOf('--body-file') + 1]).toMatch(/body\.md$/)
+    expect(options).toMatchObject({
+      cwd: '/repo-root',
+      timeout: 60_000,
+      idempotent: false
+    })
+    expect(acquireMock).toHaveBeenCalledOnce()
+    expect(releaseMock).toHaveBeenCalledOnce()
+  })
+
+  it('falls back to parsing the PR URL for older gh output', async () => {
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'acme', repo: 'widgets' })
+    ghExecFileAsyncMock.mockResolvedValueOnce({
+      stdout: 'https://github.com/acme/widgets/pull/43\n'
+    })
+
+    await expect(
+      createGitHubPullRequest('/repo-root', {
+        provider: 'github',
+        base: 'main',
+        head: 'feature/url-output',
+        title: 'URL output'
+      })
+    ).resolves.toEqual({
+      ok: true,
+      number: 43,
+      url: 'https://github.com/acme/widgets/pull/43'
+    })
+  })
+
+  it('returns the existing PR when gh reports an already-open pull request', async () => {
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'acme', repo: 'widgets' })
+    ghExecFileAsyncMock
+      .mockRejectedValueOnce({ stderr: 'a pull request already exists for feature/existing' })
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify([
+          {
+            number: 44,
+            url: 'https://github.com/acme/widgets/pull/44'
+          }
+        ])
+      })
+
+    await expect(
+      createGitHubPullRequest('/repo-root', {
+        provider: 'github',
+        base: 'main',
+        head: 'refs/remotes/origin/feature/existing',
+        title: 'Existing'
+      })
+    ).resolves.toEqual({
+      ok: false,
+      code: 'already_exists',
+      error: 'A pull request already exists for this branch.',
+      existingReview: {
+        number: 44,
+        url: 'https://github.com/acme/widgets/pull/44'
+      }
+    })
+
+    expect(ghExecFileAsyncMock.mock.calls[1]).toEqual([
+      [
+        'pr',
+        'list',
+        '--repo',
+        'acme/widgets',
+        '--head',
+        'feature/existing',
+        '--base',
+        'main',
+        '--state',
+        'open',
+        '--limit',
+        '2',
+        '--json',
+        'number,url'
+      ],
+      { cwd: '/repo-root' }
+    ])
+  })
+
+  it('validates base, head, and title before invoking gh', async () => {
+    getOwnerRepoMock.mockResolvedValueOnce({ owner: 'acme', repo: 'widgets' })
+
+    await expect(
+      createGitHubPullRequest('/repo-root', {
+        provider: 'github',
+        base: 'refs/heads/feature',
+        head: 'feature',
+        title: 'Feature'
+      })
+    ).resolves.toEqual({
+      ok: false,
+      code: 'validation',
+      error: 'Create PR failed: choose a different base branch before creating a pull request.'
+    })
+
+    expect(ghExecFileAsyncMock).not.toHaveBeenCalled()
+    expect(acquireMock).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index 4dcf66bf4f3..feedb3db761 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -14,13 +14,22 @@ import type {
   GitHubViewer,
   GitHubWorkItem
 } from '../../shared/types'
+import type { CreateHostedReviewInput, CreateHostedReviewResult } from '../../shared/hosted-review'
+import {
+  normalizeHostedReviewBaseRef,
+  normalizeHostedReviewHeadRef
+} from '../../shared/hosted-review-refs'
 import { parseTaskQuery, type ParsedTaskQuery } from '../../shared/task-query'
 import { sortWorkItemsByUpdatedAt } from '../../shared/work-items'
+import { mkdtemp, rm, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { tmpdir } from 'os'
 import { getPRConflictSummary } from './conflict-summary'
 import {
   execFileAsync,
   ghExecFileAsync,
   gitExecFileAsync,
+  extractExecError,
   acquire,
   release,
   getOwnerRepo,
@@ -911,6 +920,220 @@ export async function getRepoSlug(
   return getOwnerRepo(repoPath, connectionId)
 }
 
+function classifyCreatePRError(error: unknown): CreateHostedReviewResult {
+  const { stderr, stdout } = extractExecError(error)
+  const message = `${stderr}\n${stdout}`.trim()
+  if (message) {
+    console.warn('createGitHubPullRequest failed:', message)
+  }
+  const lower = message.toLowerCase()
+  if (
+    lower.includes('not logged') ||
+    lower.includes('not authenticated') ||
+    lower.includes('authentication') ||
+    lower.includes('gh auth login') ||
+    lower.includes('http 401')
+  ) {
+    return {
+      ok: false,
+      code: 'auth_required',
+      error:
+        'Create PR failed: GitHub is not authenticated. Next step: run gh auth login in this environment.'
+    }
+  }
+  if (lower.includes('already exists') || lower.includes('a pull request already exists')) {
+    return {
+      ok: false,
+      code: 'already_exists',
+      error: 'A pull request already exists for this branch.'
+    }
+  }
+  if (lower.includes('timed out') || lower.includes('timeout')) {
+    return {
+      ok: false,
+      code: 'unknown_completion',
+      error: 'PR creation may have completed. Refreshing branch review state...'
+    }
+  }
+  if (lower.includes('validation failed') || lower.includes('http 422')) {
+    return {
+      ok: false,
+      code: 'validation',
+      error:
+        'Create PR failed: GitHub rejected the pull request. Check the base branch and branch state, then try again.'
+    }
+  }
+  return {
+    ok: false,
+    code: 'unknown',
+    error: 'Create PR failed: GitHub could not create the pull request. Try again in a moment.'
+  }
+}
+
+function parseCreatePRPayload(stdout: string): { number: number; url: string } | null {
+  const trimmed = stdout.trim()
+  if (!trimmed) {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(trimmed) as { number?: unknown; url?: unknown }
+    const number = Number(parsed.number)
+    const url = typeof parsed.url === 'string' ? parsed.url.trim() : ''
+    if (Number.isInteger(number) && number > 0 && url) {
+      return { number, url }
+    }
+  } catch {
+    // Fall through to URL parsing for older gh versions without --json support.
+  }
+  const urlMatch = trimmed.match(/https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/(\d+)/)
+  if (!urlMatch) {
+    return null
+  }
+  return { number: Number(urlMatch[1]), url: urlMatch[0] }
+}
+
+async function findOpenPRByHeadBase(args: {
+  repoPath: string
+  ownerRepo: OwnerRepo
+  head: string
+  base: string
+}): Promise<{ number: number; url: string } | null> {
+  const { stdout } = await ghExecFileAsync(
+    [
+      'pr',
+      'list',
+      '--repo',
+      `${args.ownerRepo.owner}/${args.ownerRepo.repo}`,
+      '--head',
+      args.head,
+      '--base',
+      args.base,
+      '--state',
+      'open',
+      '--limit',
+      '2',
+      '--json',
+      'number,url'
+    ],
+    { cwd: args.repoPath }
+  )
+  const list = JSON.parse(stdout) as { number?: number; url?: string }[]
+  if (list.length !== 1 || !list[0]?.number || !list[0]?.url) {
+    return null
+  }
+  return { number: list[0].number, url: list[0].url }
+}
+
+export async function createGitHubPullRequest(
+  repoPath: string,
+  input: CreateHostedReviewInput
+): Promise<CreateHostedReviewResult> {
+  if (input.provider !== 'github') {
+    return {
+      ok: false,
+      code: 'unsupported_provider',
+      error: 'Creating reviews for this provider is not supported yet.'
+    }
+  }
+
+  const ownerRepo = await getOwnerRepo(repoPath)
+  if (!ownerRepo) {
+    return {
+      ok: false,
+      code: 'unsupported_provider',
+      error: 'Creating pull requests requires a GitHub remote.'
+    }
+  }
+
+  const base = normalizeHostedReviewBaseRef(input.base)
+  const head = input.head ? normalizeHostedReviewHeadRef(input.head) || undefined : undefined
+  const title = input.title.trim()
+  if (!base || !title) {
+    return {
+      ok: false,
+      code: 'validation',
+      error: 'Create PR failed: base branch and title are required.'
+    }
+  }
+  if (head && head.toLowerCase() === base.toLowerCase()) {
+    return {
+      ok: false,
+      code: 'validation',
+      error: 'Create PR failed: choose a different base branch before creating a pull request.'
+    }
+  }
+
+  const tempDir = await mkdtemp(join(tmpdir(), 'orca-pr-body-'))
+  await acquire()
+  const bodyPath = join(tempDir, 'body.md')
+  try {
+    await writeFile(bodyPath, input.body ?? '', 'utf8')
+    const createArgs = [
+      'pr',
+      'create',
+      '--repo',
+      `${ownerRepo.owner}/${ownerRepo.repo}`,
+      '--base',
+      base,
+      '--title',
+      title,
+      '--body-file',
+      bodyPath
+    ]
+    if (head) {
+      createArgs.push('--head', head)
+    }
+    if (input.draft) {
+      createArgs.push('--draft')
+    }
+    try {
+      const { stdout } = await ghExecFileAsync(createArgs, {
+        cwd: repoPath,
+        timeout: 60_000,
+        idempotent: false
+      })
+      const created = parseCreatePRPayload(stdout)
+      if (created) {
+        return { ok: true, ...created }
+      }
+      const found = head
+        ? await findOpenPRByHeadBase({ repoPath, ownerRepo, head, base }).catch(() => null)
+        : null
+      if (found) {
+        return { ok: true, ...found }
+      }
+      return {
+        ok: false,
+        code: 'unknown_completion',
+        error: 'PR creation may have completed. Refreshing branch review state...'
+      }
+    } catch (error) {
+      const classified = classifyCreatePRError(error)
+      if (
+        !classified.ok &&
+        (classified.code === 'already_exists' || classified.code === 'unknown_completion') &&
+        head
+      ) {
+        const existing = await findOpenPRByHeadBase({ repoPath, ownerRepo, head, base }).catch(
+          () => null
+        )
+        if (existing) {
+          return {
+            ok: false,
+            code: 'already_exists',
+            error: 'A pull request already exists for this branch.',
+            existingReview: existing
+          }
+        }
+      }
+      return classified
+    }
+  } finally {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => undefined)
+    release()
+  }
+}
+
 export async function getWorkItem(
   repoPath: string,
   number: number,
diff --git a/src/main/github/gh-utils.ts b/src/main/github/gh-utils.ts
index 1fc45329445..3d8b3478850 100644
--- a/src/main/github/gh-utils.ts
+++ b/src/main/github/gh-utils.ts
@@ -1,6 +1,6 @@
 import { execFile } from 'child_process'
 import { promisify } from 'util'
-import { gitExecFileAsync, ghExecFileAsync } from '../git/runner'
+import { gitExecFileAsync, ghExecFileAsync, extractExecError } from '../git/runner'
 import type { ClassifiedError, GitHubOwnerRepo, IssueSourcePreference } from '../../shared/types'
 import { getSshGitProvider } from '../providers/ssh-git-dispatch'
 
@@ -8,7 +8,7 @@ import { getSshGitProvider } from '../providers/ssh-git-dispatch'
 // WSL-aware routing (e.g. non-repo-scoped gh commands). Repo-scoped callers
 // should use ghExecFileAsync or gitExecFileAsync from the runner instead.
 export const execFileAsync = promisify(execFile)
-export { ghExecFileAsync, gitExecFileAsync }
+export { ghExecFileAsync, gitExecFileAsync, extractExecError }
 
 // Concurrency limiter - max 4 parallel gh processes
 const MAX_CONCURRENT = 4
diff --git a/src/main/ipc/hosted-review.ts b/src/main/ipc/hosted-review.ts
index 4f458914e0e..f19276e59b3 100644
--- a/src/main/ipc/hosted-review.ts
+++ b/src/main/ipc/hosted-review.ts
@@ -1,9 +1,17 @@
 import { ipcMain } from 'electron'
 import { resolve } from 'path'
-import type { HostedReviewForBranchArgs } from '../../shared/hosted-review'
+import type {
+  CreateHostedReviewArgs,
+  HostedReviewCreationEligibilityArgs,
+  HostedReviewForBranchArgs
+} from '../../shared/hosted-review'
 import type { Repo } from '../../shared/types'
 import type { Store } from '../persistence'
 import type { StatsCollector } from '../stats/collector'
+import {
+  createHostedReview,
+  getHostedReviewCreationEligibility
+} from '../source-control/hosted-review-creation'
 import { getHostedReviewForBranch } from '../source-control/hosted-review'
 
 function assertRegisteredRepo(repoPath: string, store: Store, repoId?: string): Repo {
@@ -44,4 +52,53 @@ export function registerHostedReviewHandlers(store: Store, stats: StatsCollector
     }
     return review
   })
+
+  ipcMain.handle(
+    'hostedReview:getCreationEligibility',
+    async (_event, args: HostedReviewCreationEligibilityArgs) => {
+      const repo = assertRegisteredRepo(args.repoPath, store)
+      if (repo.connectionId) {
+        return {
+          provider: 'unsupported' as const,
+          review: null,
+          canCreate: false,
+          blockedReason: 'unsupported_provider' as const,
+          nextAction: null,
+          defaultBaseRef: args.base ?? null,
+          head: args.branch,
+          title: null,
+          body: null
+        }
+      }
+      return getHostedReviewCreationEligibility({ ...args, repoPath: repo.path })
+    }
+  )
+
+  ipcMain.handle('hostedReview:create', async (_event, args: CreateHostedReviewArgs) => {
+    const repo = assertRegisteredRepo(args.repoPath, store)
+    if (repo.connectionId) {
+      return {
+        ok: false as const,
+        code: 'unsupported_provider' as const,
+        error: 'Creating pull requests from SSH worktrees is not supported yet.'
+      }
+    }
+    const result = await createHostedReview(repo.path, {
+      provider: args.provider,
+      base: args.base,
+      head: args.head,
+      title: args.title,
+      body: args.body,
+      draft: args.draft
+    })
+    if (result.ok && !stats.hasCountedPR(result.url)) {
+      stats.record({
+        type: 'pr_created',
+        at: Date.now(),
+        repoId: repo.id,
+        meta: { prNumber: result.number, prUrl: result.url }
+      })
+    }
+    return result
+  })
 }
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index 803dea1d4f3..d589fbeab65 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -113,8 +113,18 @@ import type {
   GitHubPRFile,
   GitHubPRReviewCommentInput
 } from '../../shared/types'
-import type { HostedReviewInfo } from '../../shared/hosted-review'
+import type {
+  CreateHostedReviewInput,
+  CreateHostedReviewResult,
+  HostedReviewCreationEligibility,
+  HostedReviewCreationEligibilityArgs,
+  HostedReviewInfo
+} from '../../shared/hosted-review'
 import { getHostedReviewForBranch as getHostedReviewForBranchFromRepo } from '../source-control/hosted-review'
+import {
+  createHostedReview as createHostedReviewFromRepo,
+  getHostedReviewCreationEligibility as getHostedReviewCreationEligibilityFromRepo
+} from '../source-control/hosted-review-creation'
 import {
   connect as connectLinear,
   disconnect as disconnectLinear,
@@ -4457,6 +4467,50 @@ export class OrcaRuntimeService {
     return review
   }
 
+  async getHostedReviewCreationEligibility(
+    args: Omit<HostedReviewCreationEligibilityArgs, 'repoPath'> & { repoSelector: string }
+  ): Promise<HostedReviewCreationEligibility> {
+    const repo = await this.resolveRepoSelector(args.repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'hosted_review')
+    return getHostedReviewCreationEligibilityFromRepo({
+      repoPath: repo.path,
+      branch: args.branch,
+      base: args.base ?? null,
+      hasUncommittedChanges: args.hasUncommittedChanges,
+      hasUpstream: args.hasUpstream,
+      ahead: args.ahead,
+      behind: args.behind,
+      linkedGitHubPR: args.linkedGitHubPR ?? null,
+      linkedGitLabMR: args.linkedGitLabMR ?? null,
+      linkedBitbucketPR: args.linkedBitbucketPR ?? null,
+      linkedGiteaPR: args.linkedGiteaPR ?? null
+    })
+  }
+
+  async createHostedReview(
+    args: CreateHostedReviewInput & { repoSelector: string }
+  ): Promise<CreateHostedReviewResult> {
+    const repo = await this.resolveRepoSelector(args.repoSelector)
+    this.assertHostIntegrationRepoIsLocal(repo, 'hosted_review')
+    const result = await createHostedReviewFromRepo(repo.path, {
+      provider: args.provider,
+      base: args.base,
+      head: args.head,
+      title: args.title,
+      body: args.body,
+      draft: args.draft
+    })
+    if (result.ok && this.stats && !this.stats.hasCountedPR(result.url)) {
+      this.stats.record({
+        type: 'pr_created',
+        at: Date.now(),
+        repoId: repo.id,
+        meta: { prNumber: result.number, prUrl: result.url }
+      })
+    }
+    return result
+  }
+
   async getRepoIssue(
     repoSelector: string,
     number: number
diff --git a/src/main/runtime/rpc/methods/hosted-review.test.ts b/src/main/runtime/rpc/methods/hosted-review.test.ts
index e7eaab3009f..0474ccaa2e1 100644
--- a/src/main/runtime/rpc/methods/hosted-review.test.ts
+++ b/src/main/runtime/rpc/methods/hosted-review.test.ts
@@ -46,4 +46,90 @@ describe('hosted review RPC methods', () => {
       result: { provider: 'github', number: 12 }
     })
   })
+
+  it('dispatches creation eligibility requests to the runtime', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      getHostedReviewCreationEligibility: vi.fn().mockResolvedValue({
+        provider: 'github',
+        review: null,
+        canCreate: true,
+        blockedReason: null,
+        nextAction: null,
+        defaultBaseRef: 'main',
+        head: 'feature/create-pr',
+        title: 'Create PR'
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: HOSTED_REVIEW_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('hostedReview.getCreationEligibility', {
+        repo: 'repo-1',
+        branch: 'feature/create-pr',
+        base: 'origin/main',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0,
+        linkedGitHubPR: null
+      })
+    )
+
+    expect(runtime.getHostedReviewCreationEligibility).toHaveBeenCalledWith({
+      repoSelector: 'repo-1',
+      branch: 'feature/create-pr',
+      base: 'origin/main',
+      hasUncommittedChanges: false,
+      hasUpstream: true,
+      ahead: 0,
+      behind: 0,
+      linkedGitHubPR: null,
+      linkedGitLabMR: null,
+      linkedBitbucketPR: null,
+      linkedGiteaPR: null
+    })
+    expect(response).toMatchObject({
+      ok: true,
+      result: { provider: 'github', canCreate: true }
+    })
+  })
+
+  it('dispatches create requests to the runtime', async () => {
+    const runtime = {
+      getRuntimeId: () => 'test-runtime',
+      createHostedReview: vi.fn().mockResolvedValue({
+        ok: true,
+        number: 51,
+        url: 'https://github.com/acme/orca/pull/51'
+      })
+    } as unknown as OrcaRuntimeService
+    const dispatcher = new RpcDispatcher({ runtime, methods: HOSTED_REVIEW_METHODS })
+
+    const response = await dispatcher.dispatch(
+      makeRequest('hostedReview.create', {
+        repo: 'repo-1',
+        provider: 'github',
+        base: 'main',
+        head: 'feature/create-pr',
+        title: 'Create PR',
+        body: 'Body',
+        draft: true
+      })
+    )
+
+    expect(runtime.createHostedReview).toHaveBeenCalledWith({
+      repoSelector: 'repo-1',
+      provider: 'github',
+      base: 'main',
+      head: 'feature/create-pr',
+      title: 'Create PR',
+      body: 'Body',
+      draft: true
+    })
+    expect(response).toMatchObject({
+      ok: true,
+      result: { ok: true, number: 51 }
+    })
+  })
 })
diff --git a/src/main/runtime/rpc/methods/hosted-review.ts b/src/main/runtime/rpc/methods/hosted-review.ts
index 3d38f36604a..3416e9939fc 100644
--- a/src/main/runtime/rpc/methods/hosted-review.ts
+++ b/src/main/runtime/rpc/methods/hosted-review.ts
@@ -11,6 +11,30 @@ const HostedReviewForBranch = z.object({
   linkedGiteaPR: z.number().int().positive().nullable().optional()
 })
 
+const HostedReviewCreationEligibility = z.object({
+  repo: requiredString('Missing repo selector'),
+  branch: requiredString('Missing branch'),
+  base: z.string().nullable().optional(),
+  hasUncommittedChanges: z.boolean().optional(),
+  hasUpstream: z.boolean().optional(),
+  ahead: z.number().int().nonnegative().optional(),
+  behind: z.number().int().nonnegative().optional(),
+  linkedGitHubPR: z.number().int().positive().nullable().optional(),
+  linkedGitLabMR: z.number().int().positive().nullable().optional(),
+  linkedBitbucketPR: z.number().int().positive().nullable().optional(),
+  linkedGiteaPR: z.number().int().positive().nullable().optional()
+})
+
+const HostedReviewCreate = z.object({
+  repo: requiredString('Missing repo selector'),
+  provider: z.enum(['github', 'gitlab', 'bitbucket', 'gitea', 'unsupported']),
+  base: requiredString('Missing base branch'),
+  head: z.string().optional(),
+  title: requiredString('Missing title'),
+  body: z.string().optional(),
+  draft: z.boolean().optional()
+})
+
 export const HOSTED_REVIEW_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'hostedReview.forBranch',
@@ -24,5 +48,37 @@ export const HOSTED_REVIEW_METHODS: RpcMethod[] = [
         linkedBitbucketPR: params.linkedBitbucketPR ?? null,
         linkedGiteaPR: params.linkedGiteaPR ?? null
       })
+  }),
+  defineMethod({
+    name: 'hostedReview.getCreationEligibility',
+    params: HostedReviewCreationEligibility,
+    handler: async (params, { runtime }) =>
+      runtime.getHostedReviewCreationEligibility({
+        repoSelector: params.repo,
+        branch: params.branch,
+        base: params.base ?? null,
+        hasUncommittedChanges: params.hasUncommittedChanges,
+        hasUpstream: params.hasUpstream,
+        ahead: params.ahead,
+        behind: params.behind,
+        linkedGitHubPR: params.linkedGitHubPR ?? null,
+        linkedGitLabMR: params.linkedGitLabMR ?? null,
+        linkedBitbucketPR: params.linkedBitbucketPR ?? null,
+        linkedGiteaPR: params.linkedGiteaPR ?? null
+      })
+  }),
+  defineMethod({
+    name: 'hostedReview.create',
+    params: HostedReviewCreate,
+    handler: async (params, { runtime }) =>
+      runtime.createHostedReview({
+        repoSelector: params.repo,
+        provider: params.provider,
+        base: params.base,
+        head: params.head,
+        title: params.title,
+        body: params.body,
+        draft: params.draft
+      })
   })
 ]
diff --git a/src/main/source-control/hosted-review-creation.test.ts b/src/main/source-control/hosted-review-creation.test.ts
new file mode 100644
index 00000000000..ddaede683f5
--- /dev/null
+++ b/src/main/source-control/hosted-review-creation.test.ts
@@ -0,0 +1,321 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const {
+  createGitHubPullRequestMock,
+  getRepoSlugMock,
+  getProjectSlugMock,
+  getBitbucketRepoSlugMock,
+  getGiteaRepoSlugMock,
+  getHostedReviewForBranchMock,
+  ghExecFileAsyncMock,
+  gitExecFileAsyncMock,
+  getUpstreamStatusMock
+} = vi.hoisted(() => ({
+  createGitHubPullRequestMock: vi.fn(),
+  getRepoSlugMock: vi.fn(),
+  getProjectSlugMock: vi.fn(),
+  getBitbucketRepoSlugMock: vi.fn(),
+  getGiteaRepoSlugMock: vi.fn(),
+  getHostedReviewForBranchMock: vi.fn(),
+  ghExecFileAsyncMock: vi.fn(),
+  gitExecFileAsyncMock: vi.fn(),
+  getUpstreamStatusMock: vi.fn()
+}))
+
+vi.mock('../github/client', () => ({
+  createGitHubPullRequest: createGitHubPullRequestMock,
+  getRepoSlug: getRepoSlugMock
+}))
+
+vi.mock('../gitlab/client', () => ({
+  getProjectSlug: getProjectSlugMock
+}))
+
+vi.mock('../bitbucket/client', () => ({
+  getBitbucketRepoSlug: getBitbucketRepoSlugMock
+}))
+
+vi.mock('../gitea/client', () => ({
+  getGiteaRepoSlug: getGiteaRepoSlugMock
+}))
+
+vi.mock('../github/gh-utils', () => ({
+  acquire: vi.fn(),
+  release: vi.fn(),
+  ghExecFileAsync: ghExecFileAsyncMock,
+  gitExecFileAsync: gitExecFileAsyncMock
+}))
+
+vi.mock('../git/upstream', () => ({
+  getUpstreamStatus: getUpstreamStatusMock
+}))
+
+vi.mock('./hosted-review', () => ({
+  getHostedReviewForBranch: getHostedReviewForBranchMock
+}))
+
+import { createHostedReview, getHostedReviewCreationEligibility } from './hosted-review-creation'
+
+describe('createHostedReview', () => {
+  beforeEach(() => {
+    createGitHubPullRequestMock.mockReset()
+    getRepoSlugMock.mockReset()
+    getProjectSlugMock.mockReset()
+    getBitbucketRepoSlugMock.mockReset()
+    getGiteaRepoSlugMock.mockReset()
+    getHostedReviewForBranchMock.mockReset()
+    ghExecFileAsyncMock.mockReset()
+    gitExecFileAsyncMock.mockReset()
+    getUpstreamStatusMock.mockReset()
+
+    getProjectSlugMock.mockResolvedValue(null)
+    getRepoSlugMock.mockResolvedValue({ owner: 'acme', repo: 'orca' })
+    getBitbucketRepoSlugMock.mockResolvedValue(null)
+    getGiteaRepoSlugMock.mockResolvedValue(null)
+    getHostedReviewForBranchMock.mockResolvedValue(null)
+    ghExecFileAsyncMock.mockResolvedValue({ stdout: '', stderr: '' })
+    getUpstreamStatusMock.mockResolvedValue({
+      hasUpstream: true,
+      upstreamName: 'origin/feature',
+      ahead: 0,
+      behind: 0
+    })
+    gitExecFileAsyncMock.mockImplementation(async (args: string[]) => {
+      if (args[0] === 'rev-parse') {
+        return { stdout: 'feature\n', stderr: '' }
+      }
+      if (args[0] === 'status') {
+        return { stdout: '', stderr: '' }
+      }
+      if (args[0] === 'log' && args.includes('--pretty=%s')) {
+        return { stdout: 'Feature title\n', stderr: '' }
+      }
+      if (args[0] === 'log') {
+        return { stdout: '- Feature title\n', stderr: '' }
+      }
+      return { stdout: '', stderr: '' }
+    })
+    createGitHubPullRequestMock.mockResolvedValue({
+      ok: true,
+      number: 12,
+      url: 'https://github.com/acme/orca/pull/12'
+    })
+  })
+
+  it('revalidates ahead commits before creating a GitHub pull request', async () => {
+    getUpstreamStatusMock.mockResolvedValue({
+      hasUpstream: true,
+      upstreamName: 'origin/feature',
+      ahead: 1,
+      behind: 0
+    })
+
+    await expect(
+      createHostedReview('/repo', {
+        provider: 'github',
+        base: 'main',
+        head: 'feature',
+        title: 'Feature'
+      })
+    ).resolves.toEqual({
+      ok: false,
+      code: 'validation',
+      error: 'Create PR failed: push this branch before creating a pull request.'
+    })
+    expect(createGitHubPullRequestMock).not.toHaveBeenCalled()
+  })
+
+  it('rejects creation when the selected head is no longer checked out', async () => {
+    gitExecFileAsyncMock.mockImplementation(async (args: string[]) => {
+      if (args[0] === 'rev-parse') {
+        return { stdout: 'other-branch\n', stderr: '' }
+      }
+      return { stdout: '', stderr: '' }
+    })
+
+    await expect(
+      createHostedReview('/repo', {
+        provider: 'github',
+        base: 'main',
+        head: 'feature',
+        title: 'Feature'
+      })
+    ).resolves.toEqual({
+      ok: false,
+      code: 'validation',
+      error: 'Create PR failed: switch back to the selected branch before creating a pull request.'
+    })
+    expect(createGitHubPullRequestMock).not.toHaveBeenCalled()
+  })
+
+  it('creates the pull request after fresh main-process validation passes', async () => {
+    await expect(
+      createHostedReview('/repo', {
+        provider: 'github',
+        base: 'main',
+        head: 'feature',
+        title: 'Feature'
+      })
+    ).resolves.toEqual({
+      ok: true,
+      number: 12,
+      url: 'https://github.com/acme/orca/pull/12'
+    })
+    expect(createGitHubPullRequestMock).toHaveBeenCalledOnce()
+  })
+
+  it('returns the existing review instead of creating a duplicate', async () => {
+    getHostedReviewForBranchMock.mockResolvedValue({
+      provider: 'github',
+      number: 31,
+      title: 'Existing feature',
+      state: 'open',
+      url: 'https://github.com/acme/orca/pull/31',
+      status: 'pending',
+      updatedAt: '2026-05-15T00:00:00.000Z',
+      mergeable: 'UNKNOWN'
+    })
+
+    await expect(
+      createHostedReview('/repo', {
+        provider: 'github',
+        base: 'main',
+        head: 'feature',
+        title: 'Feature'
+      })
+    ).resolves.toEqual({
+      ok: false,
+      code: 'already_exists',
+      error: 'A pull request already exists for this branch.',
+      existingReview: {
+        number: 31,
+        url: 'https://github.com/acme/orca/pull/31'
+      }
+    })
+    expect(createGitHubPullRequestMock).not.toHaveBeenCalled()
+  })
+})
+
+describe('getHostedReviewCreationEligibility', () => {
+  beforeEach(() => {
+    createGitHubPullRequestMock.mockReset()
+    getRepoSlugMock.mockReset()
+    getProjectSlugMock.mockReset()
+    getBitbucketRepoSlugMock.mockReset()
+    getGiteaRepoSlugMock.mockReset()
+    getHostedReviewForBranchMock.mockReset()
+    ghExecFileAsyncMock.mockReset()
+    gitExecFileAsyncMock.mockReset()
+    getUpstreamStatusMock.mockReset()
+
+    getProjectSlugMock.mockResolvedValue(null)
+    getRepoSlugMock.mockResolvedValue({ owner: 'acme', repo: 'orca' })
+    getBitbucketRepoSlugMock.mockResolvedValue(null)
+    getGiteaRepoSlugMock.mockResolvedValue(null)
+    getHostedReviewForBranchMock.mockResolvedValue(null)
+    ghExecFileAsyncMock.mockResolvedValue({ stdout: '', stderr: '' })
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: 'Feature title\n', stderr: '' })
+  })
+
+  it('treats short remote base refs as the default branch name', async () => {
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'main',
+        base: 'origin/main',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({
+      canCreate: false,
+      blockedReason: 'default_branch',
+      defaultBaseRef: 'origin/main'
+    })
+  })
+
+  it('blocks dirty tracked GitHub branches before PR creation', async () => {
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'feature/create-pr',
+        base: 'main',
+        hasUncommittedChanges: true,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({
+      provider: 'github',
+      canCreate: false,
+      blockedReason: 'dirty',
+      nextAction: 'commit',
+      head: 'feature/create-pr'
+    })
+  })
+
+  it('enables creation for clean, in-sync, authenticated GitHub feature branches', async () => {
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'refs/heads/feature/create-pr',
+        base: 'origin/main',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({
+      provider: 'github',
+      canCreate: true,
+      blockedReason: null,
+      nextAction: null,
+      defaultBaseRef: 'origin/main',
+      head: 'feature/create-pr',
+      title: 'Feature title',
+      body: 'Feature title'
+    })
+  })
+
+  it('offers push as the next action for authenticated branches with local-only commits', async () => {
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'feature/create-pr',
+        base: 'main',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 2,
+        behind: 0
+      })
+    ).resolves.toMatchObject({
+      canCreate: false,
+      blockedReason: 'needs_push',
+      nextAction: 'push'
+    })
+  })
+
+  it('blocks unsupported providers before GitHub authentication checks', async () => {
+    getProjectSlugMock.mockResolvedValue({ host: 'gitlab.com', path: 'acme/orca' })
+    getRepoSlugMock.mockResolvedValue(null)
+
+    await expect(
+      getHostedReviewCreationEligibility({
+        repoPath: '/repo',
+        branch: 'feature/gitlab',
+        base: 'main',
+        hasUncommittedChanges: false,
+        hasUpstream: true,
+        ahead: 0,
+        behind: 0
+      })
+    ).resolves.toMatchObject({
+      provider: 'gitlab',
+      canCreate: false,
+      blockedReason: 'unsupported_provider',
+      nextAction: null
+    })
+    expect(ghExecFileAsyncMock).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/source-control/hosted-review-creation.ts b/src/main/source-control/hosted-review-creation.ts
new file mode 100644
index 00000000000..7b8b59bbcfe
--- /dev/null
+++ b/src/main/source-control/hosted-review-creation.ts
@@ -0,0 +1,323 @@
+/* eslint-disable max-lines -- Why: provider detection, eligibility, and creation
+   preflight share one boundary so renderer and main-process gating cannot drift. */
+import type {
+  CreateHostedReviewInput,
+  CreateHostedReviewResult,
+  HostedReviewCreationBlockedReason,
+  HostedReviewCreationEligibility,
+  HostedReviewCreationEligibilityArgs,
+  HostedReviewProvider
+} from '../../shared/hosted-review'
+import {
+  normalizeHostedReviewBaseRef,
+  normalizeHostedReviewHeadRef
+} from '../../shared/hosted-review-refs'
+import { getBitbucketRepoSlug } from '../bitbucket/client'
+import { getGiteaRepoSlug } from '../gitea/client'
+import { createGitHubPullRequest, getRepoSlug } from '../github/client'
+import { acquire, ghExecFileAsync, gitExecFileAsync, release } from '../github/gh-utils'
+import { resolveDefaultBaseRefViaExec } from '../git/repo'
+import { getUpstreamStatus } from '../git/upstream'
+import { getProjectSlug } from '../gitlab/client'
+import { getHostedReviewForBranch } from './hosted-review'
+
+function stripRefPrefix(ref: string): string {
+  return normalizeHostedReviewHeadRef(ref)
+}
+
+function branchToTitle(branch: string): string {
+  const lastSegment = branch.split('/').filter(Boolean).at(-1) ?? branch
+  return lastSegment
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+}
+
+async function detectHostedReviewProvider(repoPath: string): Promise<HostedReviewProvider> {
+  if (await getProjectSlug(repoPath)) {
+    return 'gitlab'
+  }
+  if (await getRepoSlug(repoPath)) {
+    return 'github'
+  }
+  if (await getBitbucketRepoSlug(repoPath)) {
+    return 'bitbucket'
+  }
+  if (await getGiteaRepoSlug(repoPath)) {
+    return 'gitea'
+  }
+  return 'unsupported'
+}
+
+async function isGitHubAuthenticated(repoPath: string): Promise<boolean> {
+  await acquire()
+  try {
+    await ghExecFileAsync(['auth', 'status', '--hostname', 'github.com'], { cwd: repoPath })
+    return true
+  } catch {
+    return false
+  } finally {
+    release()
+  }
+}
+
+async function getLatestCommitSubject(repoPath: string): Promise<string | null> {
+  try {
+    const { stdout } = await gitExecFileAsync(['log', '-1', '--pretty=%s'], { cwd: repoPath })
+    const subject = stdout.trim()
+    return subject || null
+  } catch {
+    return null
+  }
+}
+
+async function getCommitSummaryBody(repoPath: string, base: string | null): Promise<string | null> {
+  if (!base) {
+    return null
+  }
+  try {
+    const { stdout } = await gitExecFileAsync(
+      ['log', '--pretty=format:- %s', '--max-count=20', `${base}..HEAD`],
+      { cwd: repoPath }
+    )
+    const body = stdout.trim()
+    return body || null
+  } catch {
+    return null
+  }
+}
+
+async function getDefaultBaseRef(repoPath: string): Promise<string | null> {
+  return resolveDefaultBaseRefViaExec((argv) => gitExecFileAsync(argv, { cwd: repoPath }))
+}
+
+async function getCurrentBranch(repoPath: string): Promise<string> {
+  const { stdout } = await gitExecFileAsync(['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: repoPath
+  })
+  return stripRefPrefix(stdout.trim())
+}
+
+async function hasUncommittedChanges(repoPath: string): Promise<boolean> {
+  const { stdout } = await gitExecFileAsync(['status', '--porcelain'], { cwd: repoPath })
+  return stdout.trim().length > 0
+}
+
+const blockedCreateResultByReason = {
+  auth_required: {
+    ok: false,
+    code: 'auth_required',
+    error:
+      'Create PR failed: GitHub is not authenticated. Next step: run gh auth login in this environment.'
+  },
+  unsupported_provider: {
+    ok: false,
+    code: 'unsupported_provider',
+    error: 'Creating pull requests requires a GitHub remote.'
+  },
+  dirty: {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: commit or discard local changes before creating a pull request.'
+  },
+  detached_head: {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: switch to a branch before creating a pull request.'
+  },
+  default_branch: {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: choose a feature branch before creating a pull request.'
+  },
+  no_upstream: {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: publish this branch before creating a pull request.'
+  },
+  needs_push: {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: push this branch before creating a pull request.'
+  },
+  needs_sync: {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: sync this branch before creating a pull request.'
+  },
+  fork_head_unsupported: {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: refresh source control status and try again.'
+  }
+} satisfies Partial<
+  Record<NonNullable<HostedReviewCreationBlockedReason>, CreateHostedReviewResult>
+>
+
+function blockedEligibilityToCreateResult(
+  eligibility: HostedReviewCreationEligibility
+): CreateHostedReviewResult | null {
+  if (eligibility.canCreate) {
+    return null
+  }
+  if (eligibility.review?.url) {
+    return {
+      ok: false,
+      code: 'already_exists',
+      error: 'A pull request already exists for this branch.',
+      existingReview: eligibility.review
+    }
+  }
+  if (eligibility.blockedReason) {
+    return blockedCreateResultByReason[eligibility.blockedReason] ?? null
+  }
+  return {
+    ok: false,
+    code: 'validation',
+    error: 'Create PR failed: refresh source control status and try again.'
+  }
+}
+
+async function validateCurrentBranchCanCreateReview(
+  repoPath: string,
+  input: CreateHostedReviewInput
+): Promise<CreateHostedReviewResult | null> {
+  const requestedHead = input.head ? stripRefPrefix(input.head).trim() : ''
+  const currentBranch = await getCurrentBranch(repoPath)
+  if (requestedHead && requestedHead !== currentBranch) {
+    return {
+      ok: false,
+      code: 'validation',
+      error: 'Create PR failed: switch back to the selected branch before creating a pull request.'
+    }
+  }
+
+  try {
+    const [dirty, upstreamStatus] = await Promise.all([
+      hasUncommittedChanges(repoPath),
+      getUpstreamStatus(repoPath)
+    ])
+    const eligibility = await getHostedReviewCreationEligibility({
+      repoPath,
+      branch: requestedHead || currentBranch,
+      base: normalizeHostedReviewBaseRef(input.base),
+      hasUncommittedChanges: dirty,
+      hasUpstream: upstreamStatus.hasUpstream,
+      ahead: upstreamStatus.ahead,
+      behind: upstreamStatus.behind
+    })
+    // Why: renderer eligibility can be stale by submit time; the main process
+    // is the last chance to avoid creating a PR from an out-of-date remote head.
+    return blockedEligibilityToCreateResult(eligibility)
+  } catch (error) {
+    console.warn('Hosted review creation preflight failed:', error)
+    return {
+      ok: false,
+      code: 'validation',
+      error:
+        'Create PR failed: could not verify branch status. Refresh source control and try again.'
+    }
+  }
+}
+
+export async function getHostedReviewCreationEligibility(
+  args: HostedReviewCreationEligibilityArgs
+): Promise<HostedReviewCreationEligibility> {
+  const branch = stripRefPrefix(args.branch).trim()
+  const provider = await detectHostedReviewProvider(args.repoPath)
+  const defaultBaseRef = args.base?.trim() || (await getDefaultBaseRef(args.repoPath))
+  const baseBranch = defaultBaseRef ? normalizeHostedReviewBaseRef(defaultBaseRef) : null
+  const review = await getHostedReviewForBranch({
+    repoPath: args.repoPath,
+    branch,
+    linkedGitHubPR: args.linkedGitHubPR ?? null,
+    linkedGitLabMR: args.linkedGitLabMR ?? null,
+    linkedBitbucketPR: args.linkedBitbucketPR ?? null,
+    linkedGiteaPR: args.linkedGiteaPR ?? null
+  })
+
+  const title = (await getLatestCommitSubject(args.repoPath)) ?? branchToTitle(branch)
+  const body = await getCommitSummaryBody(args.repoPath, defaultBaseRef ?? null)
+  const baseResult = {
+    provider,
+    review: review ? { number: review.number, url: review.url } : null,
+    defaultBaseRef,
+    head: branch || null,
+    title,
+    body
+  }
+
+  if (!branch || branch === 'HEAD') {
+    return { ...baseResult, canCreate: false, blockedReason: 'detached_head', nextAction: null }
+  }
+  if (review) {
+    return {
+      ...baseResult,
+      canCreate: false,
+      blockedReason: 'existing_review',
+      nextAction: 'open_existing_review'
+    }
+  }
+  if (provider !== 'github') {
+    return {
+      ...baseResult,
+      canCreate: false,
+      blockedReason: 'unsupported_provider',
+      nextAction: null
+    }
+  }
+  if (baseBranch && branch.toLowerCase() === baseBranch.toLowerCase()) {
+    return { ...baseResult, canCreate: false, blockedReason: 'default_branch', nextAction: null }
+  }
+  if (args.hasUncommittedChanges) {
+    return { ...baseResult, canCreate: false, blockedReason: 'dirty', nextAction: 'commit' }
+  }
+  if (args.hasUpstream === false) {
+    return { ...baseResult, canCreate: false, blockedReason: 'no_upstream', nextAction: 'publish' }
+  }
+  if (args.hasUpstream !== true) {
+    return { ...baseResult, canCreate: false, blockedReason: null, nextAction: null }
+  }
+  if ((args.behind ?? 0) > 0) {
+    return { ...baseResult, canCreate: false, blockedReason: 'needs_sync', nextAction: 'sync' }
+  }
+  if (!(await isGitHubAuthenticated(args.repoPath))) {
+    return {
+      ...baseResult,
+      canCreate: false,
+      blockedReason: 'auth_required',
+      nextAction: 'authenticate'
+    }
+  }
+  if ((args.ahead ?? 0) > 0) {
+    return { ...baseResult, canCreate: false, blockedReason: 'needs_push', nextAction: 'push' }
+  }
+  return { ...baseResult, canCreate: Boolean(baseBranch), blockedReason: null, nextAction: null }
+}
+
+export async function createHostedReview(
+  repoPath: string,
+  input: CreateHostedReviewInput
+): Promise<CreateHostedReviewResult> {
+  if (input.provider !== 'github') {
+    return {
+      ok: false,
+      code: 'unsupported_provider',
+      error: 'Creating reviews for this provider is not supported yet.'
+    }
+  }
+  const provider = await detectHostedReviewProvider(repoPath)
+  if (provider !== 'github') {
+    return {
+      ok: false,
+      code: 'unsupported_provider',
+      error: 'Creating pull requests requires a GitHub remote.'
+    }
+  }
+  const blocked = await validateCurrentBranchCanCreateReview(repoPath, input)
+  if (blocked) {
+    return blocked
+  }
+  return createGitHubPullRequest(repoPath, input)
+}
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index d02b9fad694..ab03644b477 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -1,5 +1,12 @@
 /* eslint-disable max-lines -- Why: the preload contract is intentionally centralized in one declaration file so renderer and preload stay in lockstep when IPC surfaces change. */
-import type { HostedReviewForBranchArgs, HostedReviewInfo } from '../shared/hosted-review'
+import type {
+  CreateHostedReviewArgs,
+  CreateHostedReviewResult,
+  HostedReviewCreationEligibility,
+  HostedReviewCreationEligibilityArgs,
+  HostedReviewForBranchArgs,
+  HostedReviewInfo
+} from '../shared/hosted-review'
 import type {
   BaseRefDefaultResult,
   BrowserCookieImportResult,
@@ -820,6 +827,10 @@ export type PreloadApi = {
   }
   hostedReview: {
     forBranch: (args: HostedReviewForBranchArgs) => Promise<HostedReviewInfo | null>
+    getCreationEligibility: (
+      args: HostedReviewCreationEligibilityArgs
+    ) => Promise<HostedReviewCreationEligibility>
+    create: (args: CreateHostedReviewArgs) => Promise<CreateHostedReviewResult>
   }
   // ── GitLab — parallel to gh, MR/issue surface only in v1 ────────
   // Shapes mirror gh.* one-to-one where the data matches; diverge
diff --git a/src/preload/index.ts b/src/preload/index.ts
index bbbc8942d7c..314d84a134c 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -925,7 +925,10 @@ const api = {
 
   hostedReview: {
     forBranch: (args: HostedReviewForBranchArgs): Promise<unknown> =>
-      ipcRenderer.invoke('hostedReview:forBranch', args)
+      ipcRenderer.invoke('hostedReview:forBranch', args),
+    getCreationEligibility: (args: unknown): Promise<unknown> =>
+      ipcRenderer.invoke('hostedReview:getCreationEligibility', args),
+    create: (args: unknown): Promise<unknown> => ipcRenderer.invoke('hostedReview:create', args)
   },
 
   // Why: GitLab bindings live in `./gitlab` so adding or changing a
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index e22a31cb685..7099e13c492 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -5,6 +5,7 @@ import { LoaderCircle, ExternalLink, RefreshCw, Check, X, Pencil } from 'lucide-
 import { useAppStore } from '@/store'
 import { useActiveWorktree, useRepoById } from '@/store/selectors'
 import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
 import { isFolderRepo } from '../../../../shared/repo-kind'
 import PRActions from './PRActions'
 import {
@@ -17,6 +18,9 @@ import {
 } from './checks-panel-content'
 import { ENTRY_REFRESH_GRACE_MS, shouldEntryRefresh } from './checks-entry-refresh'
 import type { PRInfo, PRCheckDetail, PRComment } from '../../../../shared/types'
+import { getConnectionId } from '@/lib/connection-context'
+import { CreatePullRequestDialog } from './CreatePullRequestDialog'
+import type { HostedReviewCreationEligibility } from '../../../../shared/hosted-review'
 import { toast } from 'sonner'
 
 export default function ChecksPanel(): React.JSX.Element {
@@ -25,7 +29,17 @@ export default function ChecksPanel(): React.JSX.Element {
   const repo = useRepoById(activeWorktree?.repoId ?? null)
   const prCache = useAppStore((s) => s.prCache)
   const fetchPRForBranch = useAppStore((s) => s.fetchPRForBranch)
+  const fetchHostedReviewForBranch = useAppStore((s) => s.fetchHostedReviewForBranch)
+  const getHostedReviewCreationEligibility = useAppStore(
+    (s) => s.getHostedReviewCreationEligibility
+  )
   const gitConflictOperationByWorktree = useAppStore((s) => s.gitConflictOperationByWorktree)
+  const gitStatusByWorktree = useAppStore((s) => s.gitStatusByWorktree)
+  const remoteStatusesByWorktree = useAppStore((s) => s.remoteStatusesByWorktree)
+  const pushBranch = useAppStore((s) => s.pushBranch)
+  const fetchUpstreamStatus = useAppStore((s) => s.fetchUpstreamStatus)
+  const setRightSidebarOpen = useAppStore((s) => s.setRightSidebarOpen)
+  const setRightSidebarTab = useAppStore((s) => s.setRightSidebarTab)
 
   // Why: the sidebar stays mounted when closed (for performance). Gate
   // polling on visibility so we don't fetch checks/comments in the background
@@ -45,6 +59,10 @@ export default function ChecksPanel(): React.JSX.Element {
   const [emptyRefreshing, setEmptyRefreshing] = useState(false)
   const [isRefreshing, setIsRefreshing] = useState(false)
   const [conflictDetailsRefreshing, setConflictDetailsRefreshing] = useState(false)
+  const [createPrDialogOpen, setCreatePrDialogOpen] = useState(false)
+  const [createPrPushFirst, setCreatePrPushFirst] = useState(false)
+  const [hostedReviewCreation, setHostedReviewCreation] =
+    useState<HostedReviewCreationEligibility | null>(null)
   const [editingTitle, setEditingTitle] = useState(false)
   const [titleDraft, setTitleDraft] = useState('')
   const [titleSaving, setTitleSaving] = useState(false)
@@ -70,6 +88,8 @@ export default function ChecksPanel(): React.JSX.Element {
     setIsRefreshing(false)
     setEmptyRefreshing(false)
     setConflictDetailsRefreshing(false)
+    setCreatePrDialogOpen(false)
+    setCreatePrPushFirst(false)
     conflictSummaryRefreshKeyRef.current = null
   }
 
@@ -79,6 +99,10 @@ export default function ChecksPanel(): React.JSX.Element {
   const prCacheKey = repo && branch ? `${repo.id}::${branch}` : ''
   const pr: PRInfo | null = prCacheKey ? (prCache[prCacheKey]?.data ?? null) : null
   const prNumber = pr?.number ?? null
+  const remoteStatus = activeWorktreeId ? remoteStatusesByWorktree[activeWorktreeId] : undefined
+  const hasUncommittedChanges = activeWorktreeId
+    ? (gitStatusByWorktree[activeWorktreeId]?.length ?? 0) > 0
+    : false
   const conflictOperation = activeWorktreeId
     ? (gitConflictOperationByWorktree[activeWorktreeId] ?? 'unknown')
     : 'unknown'
@@ -108,6 +132,48 @@ export default function ChecksPanel(): React.JSX.Element {
     }
   }, [repo, isFolder, branch, linkedPR, fetchPRForBranch])
 
+  useEffect(() => {
+    if (!repo || isFolder || !branch || !isPanelVisible) {
+      setHostedReviewCreation(null)
+      return
+    }
+    let stale = false
+    void getHostedReviewCreationEligibility({
+      repoPath: repo.path,
+      branch,
+      base: repo.worktreeBaseRef ?? null,
+      hasUncommittedChanges,
+      hasUpstream: remoteStatus?.hasUpstream,
+      ahead: remoteStatus?.ahead,
+      behind: remoteStatus?.behind,
+      linkedGitHubPR: linkedPR
+    })
+      .then((result) => {
+        if (!stale) {
+          setHostedReviewCreation(result)
+        }
+      })
+      .catch(() => {
+        if (!stale) {
+          setHostedReviewCreation(null)
+        }
+      })
+    return () => {
+      stale = true
+    }
+  }, [
+    branch,
+    getHostedReviewCreationEligibility,
+    hasUncommittedChanges,
+    isFolder,
+    isPanelVisible,
+    linkedPR,
+    remoteStatus?.ahead,
+    remoteStatus?.behind,
+    remoteStatus?.hasUpstream,
+    repo
+  ])
+
   useEffect(() => {
     if (!repo || isFolder || !branch || !pr || pr.mergeable !== 'CONFLICTING') {
       conflictSummaryRefreshKeyRef.current = null
@@ -453,6 +519,66 @@ export default function ChecksPanel(): React.JSX.Element {
     }
   }, [pr])
 
+  const pushBeforeCreatePullRequest = useCallback(async (): Promise<boolean> => {
+    if (!activeWorktreeId || !activeWorktree?.path) {
+      return false
+    }
+    const connectionId = getConnectionId(activeWorktreeId) ?? undefined
+    try {
+      await pushBranch(
+        activeWorktreeId,
+        activeWorktree.path,
+        false,
+        connectionId,
+        activeWorktree.pushTarget
+      )
+      await fetchUpstreamStatus(activeWorktreeId, activeWorktree.path, connectionId)
+      return true
+    } catch {
+      return false
+    }
+  }, [activeWorktree, activeWorktreeId, fetchUpstreamStatus, pushBranch])
+
+  const handlePullRequestCreated = useCallback(
+    async (result: { number: number; url: string }): Promise<void> => {
+      if (!repo || !branch) {
+        return
+      }
+      setRightSidebarOpen(true)
+      setRightSidebarTab('checks')
+      try {
+        const refreshedPR = await fetchPRForBranch(repo.path, branch, {
+          force: true,
+          linkedPRNumber: result.number
+        })
+        await fetchHostedReviewForBranch(repo.path, branch, {
+          force: true,
+          linkedGitHubPR: result.number
+        })
+        if (refreshedPR) {
+          await Promise.all([
+            fetchPRChecks(repo.path, refreshedPR.number, branch, refreshedPR.headSha, {
+              force: true
+            }).then(setChecks),
+            fetchPRComments(repo.path, refreshedPR.number, { force: true }).then(setComments)
+          ])
+        }
+      } catch {
+        // The success toast keeps the hosted URL available; Checks can be refreshed manually.
+      }
+    },
+    [
+      branch,
+      fetchHostedReviewForBranch,
+      fetchPRChecks,
+      fetchPRComments,
+      fetchPRForBranch,
+      repo,
+      setRightSidebarOpen,
+      setRightSidebarTab
+    ]
+  )
+
   // ── Empty state ──
   if (!activeWorktree) {
     return (
@@ -490,34 +616,67 @@ export default function ChecksPanel(): React.JSX.Element {
             ? 'Cherry-pick'
             : null
 
+    const canCreate = hostedReviewCreation?.canCreate
+    const canPushCreate = hostedReviewCreation?.blockedReason === 'needs_push'
     return (
-      <div className="px-4 py-6">
-        <div className="text-sm font-medium text-foreground">
-          {operationInProgress ? `${operationLabel} in progress` : 'No pull request found'}
-        </div>
-        <div className="mt-1 text-xs text-muted-foreground">
-          {operationInProgress
-            ? 'PR checks will be available after the operation completes'
-            : 'Push your branch and open a PR to see checks here'}
-        </div>
-        {!operationInProgress && (
-          <button
-            className="mt-3 px-3 py-1 text-xs font-medium rounded-md border border-border bg-accent/50 text-foreground hover:bg-accent transition-colors disabled:opacity-50"
-            disabled={emptyRefreshing}
-            onClick={() => {
-              if (!activeWorktreeId) {
-                return
-              }
-              setEmptyRefreshing(true)
-              void handleRefresh().finally(() => {
-                setEmptyRefreshing(false)
-              })
-            }}
-          >
-            {emptyRefreshing ? 'Refreshing…' : 'Refresh'}
-          </button>
+      <>
+        {repo && (
+          <CreatePullRequestDialog
+            open={createPrDialogOpen}
+            repoId={repo.id}
+            repoPath={repo.path}
+            branch={branch}
+            eligibility={hostedReviewCreation}
+            pushBeforeCreate={createPrPushFirst}
+            onOpenChange={setCreatePrDialogOpen}
+            onPushBeforeCreate={pushBeforeCreatePullRequest}
+            onCreated={handlePullRequestCreated}
+          />
         )}
-      </div>
+        <div className="px-4 py-6">
+          <div className="text-sm font-medium text-foreground">
+            {operationInProgress ? `${operationLabel} in progress` : 'No pull request found'}
+          </div>
+          <div className="mt-1 text-xs text-muted-foreground">
+            {operationInProgress
+              ? 'PR checks will be available after the operation completes'
+              : canPushCreate
+                ? 'Push your branch before creating a pull request.'
+                : 'Create a pull request to start checks and review.'}
+          </div>
+          {!operationInProgress && (
+            <div className="mt-3 flex flex-wrap gap-2">
+              {(canCreate || canPushCreate) && (
+                <Button
+                  size="xs"
+                  onClick={() => {
+                    setCreatePrPushFirst(canPushCreate)
+                    setCreatePrDialogOpen(true)
+                  }}
+                >
+                  {canPushCreate ? 'Push & Create PR' : 'Create PR'}
+                </Button>
+              )}
+              <Button
+                size="xs"
+                variant="outline"
+                disabled={emptyRefreshing}
+                onClick={() => {
+                  if (!activeWorktreeId) {
+                    return
+                  }
+                  setEmptyRefreshing(true)
+                  void handleRefresh().finally(() => {
+                    setEmptyRefreshing(false)
+                  })
+                }}
+              >
+                {emptyRefreshing ? 'Refreshing…' : 'Refresh'}
+              </Button>
+            </div>
+          )}
+        </div>
+      </>
     )
   }
 
diff --git a/src/renderer/src/components/right-sidebar/CreatePullRequestDialog.tsx b/src/renderer/src/components/right-sidebar/CreatePullRequestDialog.tsx
new file mode 100644
index 00000000000..bcfefc5f50d
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/CreatePullRequestDialog.tsx
@@ -0,0 +1,357 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { Check, ChevronsUpDown, Loader2 } from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '@/components/ui/dialog'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import { cn } from '@/lib/utils'
+import { useAppStore } from '@/store'
+import {
+  getRuntimeRepoBaseRefDefault,
+  searchRuntimeRepoBaseRefs
+} from '@/runtime/runtime-repo-client'
+import type {
+  CreateHostedReviewResult,
+  HostedReviewCreationEligibility
+} from '../../../../shared/hosted-review'
+import {
+  normalizeHostedReviewBaseRef,
+  normalizeHostedReviewHeadRef
+} from '../../../../shared/hosted-review-refs'
+
+type CreatePullRequestDialogProps = {
+  open: boolean
+  repoId: string
+  repoPath: string
+  branch: string
+  eligibility: HostedReviewCreationEligibility | null
+  pushBeforeCreate: boolean
+  onOpenChange: (open: boolean) => void
+  onPushBeforeCreate: () => Promise<boolean>
+  onCreated: (result: { number: number; url: string }) => Promise<void>
+}
+
+function stripBaseRef(ref: string): string {
+  return normalizeHostedReviewBaseRef(ref)
+}
+
+function formatCreateError(result: CreateHostedReviewResult, pushed: boolean): string {
+  if (result.ok) {
+    return ''
+  }
+  if (pushed) {
+    return `Push succeeded, but PR creation failed: ${result.error.replace(/^Create PR failed:\s*/i, '')}`
+  }
+  return result.error
+}
+
+export function CreatePullRequestDialog({
+  open,
+  repoId,
+  repoPath,
+  branch,
+  eligibility,
+  pushBeforeCreate,
+  onOpenChange,
+  onPushBeforeCreate,
+  onCreated
+}: CreatePullRequestDialogProps): React.JSX.Element {
+  const settings = useAppStore((s) => s.settings)
+  const createHostedReview = useAppStore((s) => s.createHostedReview)
+  const submitInFlightRef = useRef(false)
+  const initializedFromEligibilityRef = useRef<string | null>(null)
+  const [base, setBase] = useState('')
+  const [title, setTitle] = useState('')
+  const [body, setBody] = useState('')
+  const [draft, setDraft] = useState(false)
+  const [baseQuery, setBaseQuery] = useState('')
+  const [baseResults, setBaseResults] = useState<string[]>([])
+  const [baseSearchError, setBaseSearchError] = useState<string | null>(null)
+  const [submitting, setSubmitting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!open) {
+      submitInFlightRef.current = false
+      initializedFromEligibilityRef.current = null
+      setSubmitting(false)
+      setError(null)
+      return
+    }
+    const initializationKey = `${repoId}:${branch}:${eligibility ? 'ready' : 'pending'}`
+    if (initializedFromEligibilityRef.current === initializationKey) {
+      return
+    }
+    // Why: eligibility refreshes while the dialog is open; only seed fields
+    // once per branch so late refreshes do not overwrite user edits.
+    initializedFromEligibilityRef.current = initializationKey
+    const initialBase = eligibility?.defaultBaseRef ?? ''
+    setBase(stripBaseRef(initialBase))
+    setTitle(eligibility?.title ?? '')
+    setBody(eligibility?.body ?? '')
+    setDraft(false)
+    setBaseQuery('')
+    setBaseResults([])
+    setBaseSearchError(null)
+  }, [branch, eligibility, open, repoId])
+
+  useEffect(() => {
+    if (!open || base) {
+      return
+    }
+    let stale = false
+    void getRuntimeRepoBaseRefDefault(settings, repoId)
+      .then((result) => {
+        if (!stale && result.defaultBaseRef) {
+          setBase(stripBaseRef(result.defaultBaseRef))
+        }
+      })
+      .catch(() => undefined)
+    return () => {
+      stale = true
+    }
+  }, [base, open, repoId, settings])
+
+  useEffect(() => {
+    if (!open || baseQuery.trim().length < 2) {
+      setBaseResults([])
+      setBaseSearchError(null)
+      return
+    }
+    let stale = false
+    const timer = window.setTimeout(() => {
+      void searchRuntimeRepoBaseRefs(settings, repoId, baseQuery.trim(), 20)
+        .then((results) => {
+          if (!stale) {
+            setBaseResults(results.map(stripBaseRef))
+            setBaseSearchError(null)
+          }
+        })
+        .catch(() => {
+          if (!stale) {
+            setBaseResults([])
+            setBaseSearchError('Branch discovery failed.')
+          }
+        })
+    }, 200)
+    return () => {
+      stale = true
+      window.clearTimeout(timer)
+    }
+  }, [baseQuery, open, repoId, settings])
+
+  const submitDisabled =
+    submitting ||
+    title.trim().length === 0 ||
+    base.trim().length === 0 ||
+    stripBaseRef(base).toLowerCase() === stripBaseRef(branch).toLowerCase()
+
+  const handleSubmit = useCallback(async (): Promise<void> => {
+    if (submitDisabled || submitInFlightRef.current) {
+      return
+    }
+    submitInFlightRef.current = true
+    setSubmitting(true)
+    setError(null)
+    let pushed = false
+    try {
+      if (pushBeforeCreate) {
+        const ok = await onPushBeforeCreate()
+        if (!ok) {
+          setError('Push failed. Resolve the push error, then try again.')
+          return
+        }
+        pushed = true
+      }
+      const result = await createHostedReview(repoPath, {
+        provider: 'github',
+        base: stripBaseRef(base.trim()),
+        head: normalizeHostedReviewHeadRef(branch),
+        title: title.trim(),
+        body,
+        draft
+      })
+      if (result.ok) {
+        toast.success(`Pull request #${result.number} created`, {
+          action: {
+            label: 'Open on GitHub',
+            onClick: () => window.api.shell.openUrl(result.url)
+          }
+        })
+        await onCreated(result)
+        onOpenChange(false)
+        return
+      }
+      if (result.existingReview?.url) {
+        const number = result.existingReview.number
+        toast.success(
+          number ? `Pull request #${number} is already open` : 'Pull request is already open',
+          {
+            action: {
+              label: 'Open on GitHub',
+              onClick: () => window.api.shell.openUrl(result.existingReview!.url)
+            }
+          }
+        )
+        if (number) {
+          await onCreated({ number, url: result.existingReview.url })
+          onOpenChange(false)
+          return
+        }
+      }
+      setError(formatCreateError(result, pushed))
+    } finally {
+      submitInFlightRef.current = false
+      setSubmitting(false)
+    }
+  }, [
+    base,
+    body,
+    branch,
+    createHostedReview,
+    draft,
+    onCreated,
+    onOpenChange,
+    onPushBeforeCreate,
+    pushBeforeCreate,
+    repoPath,
+    submitDisabled,
+    title
+  ])
+
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean): void => {
+      // Why: closing during submit would reset the in-flight guard while the
+      // main-process create call can still complete, allowing duplicate clicks.
+      if (submitting && !nextOpen) {
+        return
+      }
+      onOpenChange(nextOpen)
+    },
+    [onOpenChange, submitting]
+  )
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="max-w-lg">
+        <DialogHeader>
+          <DialogTitle>Create Pull Request</DialogTitle>
+          <DialogDescription>
+            Confirm the target branch and PR details before creating the hosted review.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4">
+          <div className="space-y-1">
+            <Label>Head branch</Label>
+            <div className="inline-flex max-w-full items-center rounded-full border border-border bg-muted px-2 py-1 text-xs font-medium text-foreground">
+              <span className="truncate">{branch}</span>
+            </div>
+          </div>
+
+          <div className="space-y-2">
+            <div className="space-y-1">
+              <Label htmlFor="create-pr-base">Base branch</Label>
+              <p className="text-xs text-muted-foreground">
+                Search remote branches or enter a branch name.
+              </p>
+            </div>
+            <div className="relative">
+              <Input
+                id="create-pr-base"
+                value={baseQuery || base}
+                onChange={(event) => {
+                  setBaseQuery(event.target.value)
+                  setBase(event.target.value)
+                }}
+                placeholder="main"
+                aria-invalid={!base.trim()}
+                className="pr-8"
+              />
+              <ChevronsUpDown className="pointer-events-none absolute right-2 top-2.5 size-3.5 text-muted-foreground" />
+            </div>
+            {baseSearchError ? <p className="text-xs text-destructive">{baseSearchError}</p> : null}
+            {baseResults.length > 0 ? (
+              <div className="max-h-36 overflow-auto rounded-md border border-border p-1 scrollbar-sleek">
+                {baseResults.map((ref) => (
+                  <button
+                    key={ref}
+                    type="button"
+                    className={cn(
+                      'flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-left text-xs hover:bg-accent',
+                      stripBaseRef(base) === ref && 'bg-accent text-accent-foreground'
+                    )}
+                    onClick={() => {
+                      setBase(ref)
+                      setBaseQuery('')
+                      setBaseResults([])
+                    }}
+                  >
+                    <span className="truncate">{ref}</span>
+                    {stripBaseRef(base) === ref ? <Check className="size-3" /> : null}
+                  </button>
+                ))}
+              </div>
+            ) : null}
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="create-pr-title">Title</Label>
+            <Input
+              id="create-pr-title"
+              value={title}
+              onChange={(event) => setTitle(event.target.value)}
+              aria-invalid={!title.trim()}
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="create-pr-body">Description</Label>
+            <textarea
+              id="create-pr-body"
+              value={body}
+              onChange={(event) => setBody(event.target.value)}
+              rows={6}
+              className="w-full resize-none rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-1 focus-visible:ring-ring"
+            />
+          </div>
+
+          <label className="flex items-center gap-2 text-sm text-foreground">
+            <input
+              type="checkbox"
+              checked={draft}
+              onChange={(event) => setDraft(event.target.checked)}
+              className="size-4 rounded border-border accent-primary"
+            />
+            Draft
+          </label>
+
+          {stripBaseRef(base).toLowerCase() === stripBaseRef(branch).toLowerCase() ? (
+            <p className="text-xs text-destructive">
+              Choose a different base branch before creating a pull request.
+            </p>
+          ) : null}
+          {error ? <p className="text-xs text-destructive">{error}</p> : null}
+        </div>
+
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)} disabled={submitting}>
+            Cancel
+          </Button>
+          <Button onClick={() => void handleSubmit()} disabled={submitDisabled}>
+            {submitting ? <Loader2 className="size-4 animate-spin" /> : null}
+            {pushBeforeCreate ? 'Push & Create PR' : 'Create PR'}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index da59a37e7ce..1e05fb0ab0b 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -107,6 +107,7 @@ import {
 } from '@/runtime/runtime-git-client'
 import { getRuntimeRepoBaseRefDefault } from '@/runtime/runtime-repo-client'
 import { PullRequestIcon } from './checks-panel-content'
+import { CreatePullRequestDialog } from './CreatePullRequestDialog'
 import type {
   DiffComment,
   GitBranchChangeEntry,
@@ -116,7 +117,10 @@ import type {
   GitStatusEntry,
   GitUpstreamStatus
 } from '../../../../shared/types'
-import type { HostedReviewInfo } from '../../../../shared/hosted-review'
+import type {
+  HostedReviewCreationEligibility,
+  HostedReviewInfo
+} from '../../../../shared/hosted-review'
 import { STATUS_COLORS, STATUS_LABELS } from './status-display'
 
 type SourceControlScope = 'all' | 'uncommitted'
@@ -150,7 +154,8 @@ const PRIMARY_ICONS: Partial<
   stage: Plus,
   push: ArrowUp,
   sync: ArrowDownUp,
-  publish: CloudUpload
+  publish: CloudUpload,
+  create_pr: GitPullRequestArrow
 }
 
 // Why: unstaged ("Changes") is listed first so that conflict files — which
@@ -250,6 +255,10 @@ function SourceControlInner(): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
   const hostedReviewCache = useAppStore((s) => s.hostedReviewCache)
   const fetchHostedReviewForBranch = useAppStore((s) => s.fetchHostedReviewForBranch)
+  const getHostedReviewCreationEligibility = useAppStore(
+    (s) => s.getHostedReviewCreationEligibility
+  )
+  const fetchPRForBranch = useAppStore((s) => s.fetchPRForBranch)
   const updateRepo = useAppStore((s) => s.updateRepo)
   const setGitStatus = useAppStore((s) => s.setGitStatus)
   const updateWorktreeGitIdentity = useAppStore((s) => s.updateWorktreeGitIdentity)
@@ -275,6 +284,8 @@ function SourceControlInner(): React.JSX.Element {
   const openBranchAllDiffs = useAppStore((s) => s.openBranchAllDiffs)
   const deleteDiffComment = useAppStore((s) => s.deleteDiffComment)
   const setScrollToDiffCommentId = useAppStore((s) => s.setScrollToDiffCommentId)
+  const setRightSidebarOpen = useAppStore((s) => s.setRightSidebarOpen)
+  const setRightSidebarTab = useAppStore((s) => s.setRightSidebarTab)
   // Why: pass activeWorktreeId directly (even when null/undefined) so the
   // slice's getDiffComments returns its stable EMPTY_COMMENTS sentinel. An
   // inline `[]` fallback would allocate a new array each store update, break
@@ -352,6 +363,10 @@ function SourceControlInner(): React.JSX.Element {
   const [generateErrors, setGenerateErrors] = useState<Record<string, string | null>>({})
   const isGenerating = generateInFlightByWorktree[activeWorktreeId ?? ''] ?? false
   const generateError = generateErrors[activeWorktreeId ?? ''] ?? null
+  const [hostedReviewCreation, setHostedReviewCreation] =
+    useState<HostedReviewCreationEligibility | null>(null)
+  const [createPrDialogOpen, setCreatePrDialogOpen] = useState(false)
+  const [createPrPushFirst, setCreatePrPushFirst] = useState(false)
   const commitMessageAi = useAppStore((s) => s.settings?.commitMessageAi)
   const filterInputRef = useRef<HTMLInputElement>(null)
   const commitMessage = readCommitDraftForWorktree(commitDrafts, activeWorktreeId)
@@ -502,6 +517,52 @@ function SourceControlInner(): React.JSX.Element {
     linkedGitLabMR
   ])
 
+  useEffect(() => {
+    if (!isBranchVisible || !activeRepo || isFolder || !branchName) {
+      setHostedReviewCreation(null)
+      return
+    }
+    let stale = false
+    void getHostedReviewCreationEligibility({
+      repoPath: activeRepo.path,
+      branch: branchName,
+      base: effectiveBaseRef ?? null,
+      hasUncommittedChanges: hasUncommittedEntries,
+      hasUpstream: remoteStatus?.hasUpstream,
+      ahead: remoteStatus?.ahead,
+      behind: remoteStatus?.behind,
+      linkedGitHubPR,
+      linkedGitLabMR
+    })
+      .then((result) => {
+        if (!stale) {
+          setHostedReviewCreation(result)
+        }
+      })
+      .catch((error) => {
+        console.warn('[SourceControl] hosted review creation eligibility failed', error)
+        if (!stale) {
+          setHostedReviewCreation(null)
+        }
+      })
+    return () => {
+      stale = true
+    }
+  }, [
+    activeRepo,
+    branchName,
+    effectiveBaseRef,
+    getHostedReviewCreationEligibility,
+    hasUncommittedEntries,
+    isBranchVisible,
+    isFolder,
+    linkedGitHubPR,
+    linkedGitLabMR,
+    remoteStatus?.ahead,
+    remoteStatus?.behind,
+    remoteStatus?.hasUpstream
+  ])
+
   const grouped = useMemo(() => {
     const groups = {
       staged: [] as GitStatusEntry[],
@@ -627,6 +688,8 @@ function SourceControlInner(): React.JSX.Element {
     // repos and back to re-trigger the resolver.
     setFilterQuery('')
     setIsExecutingBulk(false)
+    setCreatePrDialogOpen(false)
+    setCreatePrPushFirst(false)
     // Why: no reset for commit-in-flight state — it now lives in a per-worktree
     // map, so it cannot leak across worktrees. Resetting here would actually
     // clear in-flight state for the *incoming* worktree if the user is coming
@@ -892,6 +955,76 @@ function SourceControlInner(): React.JSX.Element {
     [handleCommit, runRemoteAction]
   )
 
+  const openCreatePullRequestDialog = useCallback((pushFirst: boolean): void => {
+    setCreatePrPushFirst(pushFirst)
+    setCreatePrDialogOpen(true)
+  }, [])
+
+  const pushBeforeCreatePullRequest = useCallback(async (): Promise<boolean> => {
+    if (!activeWorktreeId || !worktreePath) {
+      return false
+    }
+    const connectionId = getConnectionId(activeWorktreeId) ?? undefined
+    try {
+      await pushBranch(
+        activeWorktreeId,
+        worktreePath,
+        false,
+        connectionId,
+        activeWorktree?.pushTarget
+      )
+      await refreshActiveGitStatusAfterMutation()
+      return true
+    } catch {
+      return false
+    }
+  }, [
+    activeWorktree?.pushTarget,
+    activeWorktreeId,
+    pushBranch,
+    refreshActiveGitStatusAfterMutation,
+    worktreePath
+  ])
+
+  const handlePullRequestCreated = useCallback(
+    async (result: { number: number; url: string }): Promise<void> => {
+      if (!activeRepo || !branchName) {
+        return
+      }
+      setRightSidebarOpen(true)
+      setRightSidebarTab('checks')
+      try {
+        await Promise.all([
+          fetchHostedReviewForBranch(activeRepo.path, branchName, {
+            force: true,
+            linkedGitHubPR: result.number,
+            linkedGitLabMR
+          }),
+          fetchPRForBranch(activeRepo.path, branchName, {
+            force: true,
+            linkedPRNumber: result.number
+          })
+        ])
+      } catch {
+        toast.warning('Pull request created, but Orca could not refresh it yet.', {
+          action: {
+            label: 'Open on GitHub',
+            onClick: () => window.api.shell.openUrl(result.url)
+          }
+        })
+      }
+    },
+    [
+      activeRepo,
+      branchName,
+      fetchHostedReviewForBranch,
+      fetchPRForBranch,
+      linkedGitLabMR,
+      setRightSidebarOpen,
+      setRightSidebarTab
+    ]
+  )
+
   const hasUnstagedChanges = grouped.unstaged.length > 0 || grouped.untracked.length > 0
 
   const primaryAction: PrimaryAction = useMemo(
@@ -906,7 +1039,8 @@ function SourceControlInner(): React.JSX.Element {
         upstreamStatus: remoteStatus,
         prState: hostedReview?.state ?? null,
         isPRStateLoading: isHostedReviewStateLoading,
-        inFlightRemoteOpKind
+        inFlightRemoteOpKind,
+        hostedReviewCreation
       }),
     [
       commitMessage,
@@ -915,6 +1049,7 @@ function SourceControlInner(): React.JSX.Element {
       isCommitting,
       isRemoteOperationActive,
       inFlightRemoteOpKind,
+      hostedReviewCreation,
       isHostedReviewStateLoading,
       hostedReview?.state,
       remoteStatus,
@@ -934,7 +1069,8 @@ function SourceControlInner(): React.JSX.Element {
         upstreamStatus: remoteStatus,
         prState: hostedReview?.state ?? null,
         isPRStateLoading: isHostedReviewStateLoading,
-        inFlightRemoteOpKind
+        inFlightRemoteOpKind,
+        hostedReviewCreation
       }),
     [
       commitMessage,
@@ -943,6 +1079,7 @@ function SourceControlInner(): React.JSX.Element {
       isCommitting,
       isRemoteOperationActive,
       inFlightRemoteOpKind,
+      hostedReviewCreation,
       isHostedReviewStateLoading,
       hostedReview?.state,
       remoteStatus,
@@ -966,6 +1103,12 @@ function SourceControlInner(): React.JSX.Element {
         case 'commit_sync':
           void runCompoundCommitAction('sync')
           return
+        case 'create_pr':
+          openCreatePullRequestDialog(false)
+          return
+        case 'push_create_pr':
+          openCreatePullRequestDialog(true)
+          return
         case 'push':
         case 'pull':
         case 'sync':
@@ -982,7 +1125,7 @@ function SourceControlInner(): React.JSX.Element {
         }
       }
     },
-    [handleCommit, runCompoundCommitAction, runRemoteAction]
+    [handleCommit, openCreatePullRequestDialog, runCompoundCommitAction, runRemoteAction]
   )
 
   const handleOpenDiff = useCallback(
@@ -1238,6 +1381,7 @@ function SourceControlInner(): React.JSX.Element {
       case 'pull':
       case 'sync':
       case 'publish':
+      case 'create_pr':
         handleActionInvoke(primaryAction.kind)
         return
       default: {
@@ -1794,6 +1938,17 @@ function SourceControlInner(): React.JSX.Element {
 
   return (
     <>
+      <CreatePullRequestDialog
+        open={createPrDialogOpen}
+        repoId={activeRepo.id}
+        repoPath={activeRepo.path}
+        branch={branchName}
+        eligibility={hostedReviewCreation}
+        pushBeforeCreate={createPrPushFirst}
+        onOpenChange={setCreatePrDialogOpen}
+        onPushBeforeCreate={pushBeforeCreatePullRequest}
+        onCreated={handlePullRequestCreated}
+      />
       <div ref={sourceControlRef} className="relative flex h-full flex-col overflow-hidden">
         <div className="flex items-center px-3 pt-2 border-b border-border">
           {(['all', 'uncommitted'] as const).map((value) => (
@@ -2572,7 +2727,14 @@ export function CommitArea({
                     onDropdownAction(entry.kind)
                   }}
                 >
-                  {entry.label}
+                  <span className="flex min-w-0 flex-col">
+                    <span>{entry.label}</span>
+                    {entry.hint ? (
+                      <span className="truncate text-[10px] text-muted-foreground">
+                        {entry.hint}
+                      </span>
+                    ) : null}
+                  </span>
                 </DropdownMenuItem>
               )
             )}
diff --git a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
index 8d9aa907db3..2f30edc6038 100644
--- a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.test.ts
@@ -33,6 +33,8 @@ describe('resolveDropdownItems', () => {
       'commit_sync',
       'separator',
       'push',
+      'create_pr',
+      'push_create_pr',
       'pull',
       'sync',
       'fetch',
@@ -221,4 +223,25 @@ describe('resolveDropdownItems', () => {
     expect(byKind.push.label).toBe('Push (2)')
     expect(byKind.sync.label).toBe('Sync (↓3 ↑2)')
   })
+
+  it('enables Push & Create PR when review creation is only blocked by unpushed commits', () => {
+    const items = resolveDropdownItems(
+      inputs({
+        upstreamStatus: { hasUpstream: true, ahead: 2, behind: 0 },
+        hostedReviewCreation: {
+          provider: 'github',
+          review: null,
+          canCreate: false,
+          blockedReason: 'needs_push',
+          nextAction: 'push'
+        }
+      })
+    )
+    const byKind = Object.fromEntries(
+      items.filter((e) => e.kind !== 'separator').map((e) => [e.kind, e])
+    )
+    expect(byKind.create_pr.disabled).toBe(true)
+    expect(byKind.create_pr.hint).toBe('Push first')
+    expect(byKind.push_create_pr.disabled).toBe(false)
+  })
 })
diff --git a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
index 53656a8821a..ed7fca8d87c 100644
--- a/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-dropdown-items.ts
@@ -6,6 +6,8 @@ export type DropdownActionKind =
   | 'commit'
   | 'commit_push'
   | 'commit_sync'
+  | 'create_pr'
+  | 'push_create_pr'
   | 'push'
   | 'pull'
   | 'sync'
@@ -17,6 +19,7 @@ export type DropdownItem = {
   label: string
   title: string
   disabled: boolean
+  hint?: string
 }
 
 export type DropdownSeparator = { kind: 'separator' }
@@ -60,7 +63,8 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
     isRemoteOperationActive,
     upstreamStatus,
     prState,
-    isPRStateLoading
+    isPRStateLoading,
+    hostedReviewCreation
   } = inputs
 
   const hasStaged = stagedCount > 0
@@ -239,12 +243,64 @@ export function resolveDropdownItems(inputs: PrimaryActionInputs): DropdownEntry
       publishBlockedByMergedPR
   }
 
+  const createBlockedHint = (() => {
+    switch (hostedReviewCreation?.blockedReason) {
+      case 'dirty':
+        return 'Commit changes first'
+      case 'detached_head':
+        return 'Check out a branch first'
+      case 'default_branch':
+        return 'Switch to a feature branch'
+      case 'no_upstream':
+        return 'Publish Branch'
+      case 'needs_push':
+        return 'Push first'
+      case 'needs_sync':
+        return 'Sync first'
+      case 'auth_required':
+        return 'Run gh auth login in this environment'
+      case 'unsupported_provider':
+        return 'Unsupported provider'
+      case 'existing_review':
+        return 'A pull request already exists'
+      case 'fork_head_unsupported':
+        return 'Fork head unsupported'
+      default:
+        return upstreamLoading ? 'Checking branch status…' : 'Branch is not ready'
+    }
+  })()
+
+  const createPRItem: DropdownItem = {
+    kind: 'create_pr',
+    label: 'Create PR',
+    title: hostedReviewCreation?.canCreate
+      ? 'Create a pull request for this branch'
+      : createBlockedHint,
+    hint: hostedReviewCreation?.canCreate ? undefined : createBlockedHint,
+    disabled: globalBusy || upstreamLoading || !hostedReviewCreation?.canCreate
+  }
+
+  const canPushAndCreate =
+    !globalBusy &&
+    !upstreamLoading &&
+    hostedReviewCreation?.provider === 'github' &&
+    hostedReviewCreation.blockedReason === 'needs_push'
+  const pushCreatePRItem: DropdownItem = {
+    kind: 'push_create_pr',
+    label: 'Push & Create PR',
+    title: canPushAndCreate ? 'Push local commits, then create a pull request' : createBlockedHint,
+    hint: canPushAndCreate ? undefined : createBlockedHint,
+    disabled: !canPushAndCreate
+  }
+
   return [
     commitItem,
     commitPushItem,
     commitSyncItem,
     { kind: 'separator' },
     pushItem,
+    createPRItem,
+    pushCreatePRItem,
     pullItem,
     syncItem,
     fetchItem,
diff --git a/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts b/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
index 6838b2f7af7..8cfb44aff3c 100644
--- a/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-primary-action.test.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- Why: this state-machine table intentionally keeps every primary-action priority case together so merge regressions are visible in one file. */
 import { describe, expect, it } from 'vitest'
 import { resolvePrimaryAction, type PrimaryActionInputs } from './source-control-primary-action'
 
@@ -335,4 +336,25 @@ describe('resolvePrimaryAction', () => {
       disabled: true
     })
   })
+
+  it('returns Create PR when a clean tracked branch is eligible for review creation', () => {
+    const result = resolvePrimaryAction(
+      inputs({
+        upstreamStatus: upstreamInSync,
+        hostedReviewCreation: {
+          provider: 'github',
+          review: null,
+          canCreate: true,
+          blockedReason: null,
+          nextAction: null
+        }
+      })
+    )
+    expect(result).toEqual({
+      kind: 'create_pr',
+      label: 'Create PR',
+      title: 'Create a pull request for this branch',
+      disabled: false
+    })
+  })
 })
diff --git a/src/renderer/src/components/right-sidebar/source-control-primary-action.ts b/src/renderer/src/components/right-sidebar/source-control-primary-action.ts
index 04bfdf04542..022c0d38327 100644
--- a/src/renderer/src/components/right-sidebar/source-control-primary-action.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-primary-action.ts
@@ -1,5 +1,6 @@
 // Why: split from the combined primary+dropdown module because the primary and dropdown are independent derivations with different priority ladders; together they exceed the max-lines budget and tangle unrelated concerns.
 
+import type { HostedReviewCreationEligibility } from '../../../../shared/hosted-review'
 import type { GitUpstreamStatus, PRState } from '../../../../shared/types'
 
 // Why: this module owns the pure state-machine logic for the Source Control
@@ -14,7 +15,14 @@ import type { GitUpstreamStatus, PRState } from '../../../../shared/types'
 // `handlePrimaryClick` switch exhaustively over only the kinds the
 // primary can actually emit, and it kills the compound-commit branch in
 // the isRemoteOperationActive tooltip below at compile time.
-export type PrimaryActionKind = 'commit' | 'stage' | 'push' | 'pull' | 'sync' | 'publish'
+export type PrimaryActionKind =
+  | 'commit'
+  | 'stage'
+  | 'push'
+  | 'pull'
+  | 'sync'
+  | 'publish'
+  | 'create_pr'
 
 // Why: the in-flight remote op tracker stores which action the user actually
 // triggered, so the primary button can mirror that label/spinner instead of
@@ -46,6 +54,7 @@ export type PrimaryActionInputs = {
   // the user-triggered action on the primary button instead of leaving a
   // stale label that no longer matches what the slice is doing.
   inFlightRemoteOpKind?: RemoteOpKind | null
+  hostedReviewCreation?: HostedReviewCreationEligibility | null
 }
 
 const PRIMARY_LABEL_BY_KIND: Record<Exclude<PrimaryActionKind, 'commit'>, string> = {
@@ -53,7 +62,8 @@ const PRIMARY_LABEL_BY_KIND: Record<Exclude<PrimaryActionKind, 'commit'>, string
   push: 'Push',
   pull: 'Pull',
   sync: 'Sync',
-  publish: 'Publish Branch'
+  publish: 'Publish Branch',
+  create_pr: 'Create PR'
 }
 
 function describePushCount(ahead: number): string {
@@ -97,7 +107,8 @@ export function resolvePrimaryAction(inputs: PrimaryActionInputs): PrimaryAction
     upstreamStatus,
     prState,
     isPRStateLoading,
-    inFlightRemoteOpKind
+    inFlightRemoteOpKind,
+    hostedReviewCreation
   } = inputs
 
   // 1. Commit in flight — lock the primary no matter what else is true.
@@ -269,6 +280,15 @@ export function resolvePrimaryAction(inputs: PrimaryActionInputs): PrimaryAction
     }
   }
 
+  if (hostedReviewCreation?.canCreate) {
+    return {
+      kind: 'create_pr',
+      label: 'Create PR',
+      title: 'Create a pull request for this branch',
+      disabled: false
+    }
+  }
+
   // Clean + tracked + in sync — distinguish truly clean from work that still
   // needs staging before commit can proceed.
   return {
diff --git a/src/renderer/src/store/slices/hosted-review.ts b/src/renderer/src/store/slices/hosted-review.ts
index c50609a918e..f788f4e0bce 100644
--- a/src/renderer/src/store/slices/hosted-review.ts
+++ b/src/renderer/src/store/slices/hosted-review.ts
@@ -1,5 +1,11 @@
 import type { StateCreator } from 'zustand'
-import type { HostedReviewInfo } from '../../../../shared/hosted-review'
+import type {
+  CreateHostedReviewInput,
+  CreateHostedReviewResult,
+  HostedReviewCreationEligibility,
+  HostedReviewCreationEligibilityArgs,
+  HostedReviewInfo
+} from '../../../../shared/hosted-review'
 import type { GlobalSettings } from '../../../../shared/types'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import type { AppState } from '../types'
@@ -32,6 +38,13 @@ export function getHostedReviewCacheKey(
 
 export type HostedReviewSlice = {
   hostedReviewCache: Record<string, CacheEntry<HostedReviewInfo>>
+  getHostedReviewCreationEligibility: (
+    args: HostedReviewCreationEligibilityArgs
+  ) => Promise<HostedReviewCreationEligibility>
+  createHostedReview: (
+    repoPath: string,
+    input: CreateHostedReviewInput
+  ) => Promise<CreateHostedReviewResult>
   fetchHostedReviewForBranch: (
     repoPath: string,
     branch: string,
@@ -50,6 +63,47 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
 ) => ({
   hostedReviewCache: {},
 
+  getHostedReviewCreationEligibility: async (args) => {
+    const settings = get().settings
+    const target = getActiveRuntimeTarget(settings)
+    if (target.kind === 'environment') {
+      const repo = get().repos.find((candidate) => candidate.path === args.repoPath)
+      const { repoPath: _repoPath, ...runtimeArgs } = args
+      void _repoPath
+      return callRuntimeRpc<HostedReviewCreationEligibility>(
+        target,
+        'hostedReview.getCreationEligibility',
+        { repo: repo?.id ?? args.repoPath, ...runtimeArgs },
+        { timeoutMs: 30_000 }
+      )
+    }
+    const repo = get().repos.find((candidate) => candidate.path === args.repoPath)
+    return window.api.hostedReview.getCreationEligibility({
+      ...args,
+      connectionId: repo?.connectionId ?? null
+    })
+  },
+
+  createHostedReview: async (repoPath, input) => {
+    const settings = get().settings
+    const target = getActiveRuntimeTarget(settings)
+    if (target.kind === 'environment') {
+      const repo = get().repos.find((candidate) => candidate.path === repoPath)
+      return callRuntimeRpc<CreateHostedReviewResult>(
+        target,
+        'hostedReview.create',
+        { repo: repo?.id ?? repoPath, ...input },
+        { timeoutMs: 60_000 }
+      )
+    }
+    const repo = get().repos.find((candidate) => candidate.path === repoPath)
+    return window.api.hostedReview.create({
+      repoPath,
+      connectionId: repo?.connectionId ?? null,
+      ...input
+    })
+  },
+
   fetchHostedReviewForBranch: async (
     repoPath,
     branch,
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index 378be8f8b9d..6d990c00532 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -128,6 +128,7 @@ function createWebPreloadApi(): Partial<PreloadApi> {
     git: createGitApi(),
     browser: createBrowserApi(),
     gh: createGitHubApi(),
+    hostedReview: createRuntimeNamespaceApi('hostedReview'),
     linear: createRuntimeNamespaceApi('linear'),
     hooks: createHooksApi(),
     stats: {
diff --git a/src/shared/hosted-review-refs.test.ts b/src/shared/hosted-review-refs.test.ts
new file mode 100644
index 00000000000..63f7c9c8cd9
--- /dev/null
+++ b/src/shared/hosted-review-refs.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { normalizeHostedReviewBaseRef, normalizeHostedReviewHeadRef } from './hosted-review-refs'
+
+describe('hosted review ref normalization', () => {
+  it('normalizes local and remote head refs to branch names', () => {
+    expect(normalizeHostedReviewHeadRef(' refs/heads/feature/create-pr ')).toBe('feature/create-pr')
+    expect(normalizeHostedReviewHeadRef('refs/remotes/origin/feature/create-pr')).toBe(
+      'feature/create-pr'
+    )
+  })
+
+  it('strips common remote prefixes from base refs', () => {
+    expect(normalizeHostedReviewBaseRef('origin/main')).toBe('main')
+    expect(normalizeHostedReviewBaseRef('refs/remotes/upstream/release/1.0')).toBe('release/1.0')
+  })
+})
diff --git a/src/shared/hosted-review-refs.ts b/src/shared/hosted-review-refs.ts
new file mode 100644
index 00000000000..6dc7255fc14
--- /dev/null
+++ b/src/shared/hosted-review-refs.ts
@@ -0,0 +1,11 @@
+export function normalizeHostedReviewHeadRef(ref: string): string {
+  return ref
+    .trim()
+    .replace(/^refs\/heads\//, '')
+    .replace(/^refs\/remotes\/[^/]+\//, '')
+}
+
+export function normalizeHostedReviewBaseRef(ref: string): string {
+  const normalized = normalizeHostedReviewHeadRef(ref)
+  return normalized.replace(/^(origin|upstream)\//, '')
+}
diff --git a/src/shared/hosted-review.ts b/src/shared/hosted-review.ts
index 56bb9da2ed2..c26d6a0b14e 100644
--- a/src/shared/hosted-review.ts
+++ b/src/shared/hosted-review.ts
@@ -1,6 +1,6 @@
 import type { CheckStatus, PRConflictSummary, PRMergeableState } from './types'
 
-export type HostedReviewProvider = 'github' | 'gitlab' | 'bitbucket' | 'gitea'
+export type HostedReviewProvider = 'github' | 'gitlab' | 'bitbucket' | 'gitea' | 'unsupported'
 
 export type HostedReviewState = 'open' | 'closed' | 'merged' | 'draft'
 
@@ -26,3 +26,90 @@ export type HostedReviewForBranchArgs = {
   linkedBitbucketPR?: number | null
   linkedGiteaPR?: number | null
 }
+
+export type HostedReviewSummary = {
+  number?: number
+  url: string
+}
+
+export type CreateHostedReviewInput = {
+  provider: HostedReviewProvider
+  base: string
+  head?: string
+  title: string
+  body?: string
+  draft?: boolean
+}
+
+export type CreateHostedReviewArgs = CreateHostedReviewInput & {
+  repoPath: string
+  connectionId?: string | null
+}
+
+export type CreateHostedReviewErrorCode =
+  | 'auth_required'
+  | 'unsupported_provider'
+  | 'already_exists'
+  | 'validation'
+  | 'timeout'
+  | 'unknown_completion'
+  | 'push_failed'
+  | 'unknown'
+
+export type CreateHostedReviewResult =
+  | { ok: true; number: number; url: string }
+  | {
+      ok: false
+      code: CreateHostedReviewErrorCode
+      error: string
+      existingReview?: HostedReviewSummary
+    }
+
+export type HostedReviewCreationBlockedReason =
+  | 'dirty'
+  | 'detached_head'
+  | 'default_branch'
+  | 'no_upstream'
+  | 'needs_push'
+  | 'needs_sync'
+  | 'auth_required'
+  | 'fork_head_unsupported'
+  | 'unsupported_provider'
+  | 'existing_review'
+  | null
+
+export type HostedReviewCreationNextAction =
+  | 'commit'
+  | 'publish'
+  | 'push'
+  | 'sync'
+  | 'authenticate'
+  | 'open_existing_review'
+  | null
+
+export type HostedReviewCreationEligibility = {
+  provider: HostedReviewProvider
+  review: HostedReviewSummary | null
+  canCreate: boolean
+  blockedReason: HostedReviewCreationBlockedReason
+  nextAction: HostedReviewCreationNextAction
+  defaultBaseRef?: string | null
+  head?: string | null
+  title?: string | null
+  body?: string | null
+}
+
+export type HostedReviewCreationEligibilityArgs = {
+  repoPath: string
+  connectionId?: string | null
+  branch: string
+  base?: string | null
+  hasUncommittedChanges?: boolean
+  hasUpstream?: boolean
+  ahead?: number
+  behind?: number
+  linkedGitHubPR?: number | null
+  linkedGitLabMR?: number | null
+  linkedBitbucketPR?: number | null
+  linkedGiteaPR?: number | null
+}
diff --git a/tests/e2e/source-control-create-pr.spec.ts b/tests/e2e/source-control-create-pr.spec.ts
new file mode 100644
index 00000000000..328764e5a26
--- /dev/null
+++ b/tests/e2e/source-control-create-pr.spec.ts
@@ -0,0 +1,201 @@
+import type { Page } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+
+type CreatePRPayload = {
+  repoPath: string
+  input: {
+    provider: string
+    base: string
+    head?: string
+    title: string
+    body?: string
+    draft?: boolean
+  }
+}
+
+async function openSourceControl(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const state = window.__store?.getState()
+    state?.setRightSidebarOpen(true)
+    state?.setRightSidebarTab('source-control')
+  })
+  await expect(page.getByRole('button', { name: /Source Control/ })).toBeVisible()
+  await expect(page.getByLabel('Commit message')).toBeVisible()
+}
+
+async function forceCreatePREligibleStatus(
+  page: Page,
+  worktreeId: string,
+  branch: string
+): Promise<void> {
+  await page.evaluate(
+    ({ worktreeId, branch }) => {
+      window.__store?.setState((current) => ({
+        remoteStatusesByWorktree: {
+          ...current.remoteStatusesByWorktree,
+          [worktreeId]: {
+            hasUpstream: true,
+            upstreamName: `origin/${branch}`,
+            ahead: 0,
+            behind: 0
+          }
+        }
+      }))
+    },
+    { worktreeId, branch }
+  )
+}
+
+async function seedCreatePREligibleBranch(
+  page: Page
+): Promise<{ branch: string; worktreeId: string }> {
+  return page.evaluate(async () => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('window.__store is not available')
+    }
+    const state = store.getState()
+    const worktreeId = state.activeWorktreeId
+    const worktrees = Object.values(state.worktreesByRepo).flat()
+    const activeWorktree = worktrees.find((entry) => entry.id === worktreeId)
+    const worktree =
+      worktrees.find((entry) => {
+        const branchName = entry.branch.replace(/^refs\/heads\//, '')
+        return branchName !== 'main' && !entry.isMainWorktree
+      }) ?? activeWorktree
+    if (!worktree) {
+      throw new Error('active worktree not found')
+    }
+    if (state.activeWorktreeId !== worktree.id) {
+      state.setActiveWorktree(worktree.id)
+    }
+    const repo = state.repos.find((entry) => entry.id === worktree.repoId)
+    if (!repo) {
+      throw new Error('active repo not found')
+    }
+    const branch = worktree.branch.replace(/^refs\/heads\//, '')
+    const pr = {
+      number: 73,
+      title: 'Create PR from E2E',
+      state: 'open' as const,
+      url: 'https://github.com/acme/orca/pull/73',
+      checksStatus: 'pending' as const,
+      updatedAt: '2026-05-15T00:00:00.000Z',
+      mergeable: 'UNKNOWN' as const
+    }
+    const eligibility = {
+      provider: 'github' as const,
+      review: null,
+      canCreate: true,
+      blockedReason: null,
+      nextAction: null,
+      defaultBaseRef: 'origin/main',
+      head: branch,
+      title: 'Create PR from E2E',
+      body: '- Initial commit for E2E'
+    }
+
+    ;(window as unknown as { __createPRPayloads: CreatePRPayload[] }).__createPRPayloads = []
+    store.setState((current) => ({
+      repos: current.repos.map((candidate) =>
+        candidate.id === repo.id ? { ...candidate, worktreeBaseRef: 'origin/main' } : candidate
+      ),
+      gitStatusByWorktree: {
+        ...current.gitStatusByWorktree,
+        [worktree.id]: []
+      },
+      remoteStatusesByWorktree: {
+        ...current.remoteStatusesByWorktree,
+        [worktree.id]: {
+          hasUpstream: true,
+          upstreamName: `origin/${branch}`,
+          ahead: 0,
+          behind: 0
+        }
+      },
+      getHostedReviewCreationEligibility: async () => eligibility,
+      fetchHostedReviewForBranch: async () => null,
+      setUpstreamStatus: () => undefined,
+      fetchUpstreamStatus: async () => undefined,
+      fetchPRForBranch: async (repoPath: string, targetBranch: string) => {
+        store.setState((next) => ({
+          prCache: {
+            ...next.prCache,
+            [`${repo.id}::${targetBranch}`]: {
+              data: pr,
+              fetchedAt: Date.now()
+            },
+            [`${repoPath}::${targetBranch}`]: {
+              data: pr,
+              fetchedAt: Date.now()
+            }
+          }
+        }))
+        return pr
+      },
+      fetchPRChecks: async () => [],
+      fetchPRComments: async () => [],
+      createHostedReview: async (repoPath, input) => {
+        ;(window as unknown as { __createPRPayloads: CreatePRPayload[] }).__createPRPayloads.push({
+          repoPath,
+          input
+        })
+        return {
+          ok: true as const,
+          number: 73,
+          url: 'https://github.com/acme/orca/pull/73'
+        }
+      }
+    }))
+
+    state.setRightSidebarOpen(true)
+    state.setRightSidebarTab('source-control')
+    return { branch, worktreeId: worktree.id }
+  })
+}
+
+test.describe('Source Control create pull request', () => {
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+    await waitForActiveWorktree(orcaPage)
+  })
+
+  test('opens the PR dialog from Source Control and creates the pull request', async ({
+    orcaPage
+  }) => {
+    const { branch, worktreeId } = await seedCreatePREligibleBranch(orcaPage)
+    await openSourceControl(orcaPage)
+    await forceCreatePREligibleStatus(orcaPage, worktreeId, branch)
+
+    const createButton = orcaPage.getByRole('button', { name: 'Create PR' })
+    await expect(createButton).toBeVisible({ timeout: 10_000 })
+    await expect(createButton).toBeEnabled()
+    await createButton.click()
+
+    const dialog = orcaPage.getByRole('dialog', { name: 'Create Pull Request' })
+    await expect(dialog).toBeVisible()
+    await expect(dialog).toContainText(branch)
+    await expect(dialog.getByLabel('Base branch')).toHaveValue('main')
+    await expect(dialog.getByLabel('Title')).toHaveValue('Create PR from E2E')
+    await expect(dialog.getByLabel('Description')).toHaveValue('- Initial commit for E2E')
+
+    await dialog.getByRole('button', { name: 'Create PR' }).click()
+
+    await expect(dialog).toBeHidden({ timeout: 10_000 })
+    await expect(orcaPage.getByText('Create PR from E2E')).toBeVisible({ timeout: 10_000 })
+
+    const payloads = await orcaPage.evaluate(
+      () => (window as unknown as { __createPRPayloads: CreatePRPayload[] }).__createPRPayloads
+    )
+    expect(payloads).toHaveLength(1)
+    expect(payloads[0].input).toMatchObject({
+      provider: 'github',
+      base: 'main',
+      head: branch,
+      title: 'Create PR from E2E',
+      body: '- Initial commit for E2E',
+      draft: false
+    })
+  })
+})

From 5f7b13e01e15121f040e231bffa5abb3d7e9d604 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 13:37:28 -0700
Subject: [PATCH 71/82] Add terminal pane equalize action

Add a terminal context menu action that equalizes split pane sizes and handles nested split weighting.
---
 .../terminal-pane/TerminalContextMenu.tsx     | 11 +++
 .../components/terminal-pane/TerminalPane.tsx |  2 +
 .../use-terminal-pane-context-menu.ts         | 12 ++++
 .../src/lib/pane-manager/pane-manager.ts      | 17 ++++-
 .../lib/pane-manager/pane-tree-ops.test.ts    | 69 ++++++++++++++++++-
 .../src/lib/pane-manager/pane-tree-ops.ts     | 51 ++++++++++++++
 6 files changed, 159 insertions(+), 3 deletions(-)

diff --git a/src/renderer/src/components/terminal-pane/TerminalContextMenu.tsx b/src/renderer/src/components/terminal-pane/TerminalContextMenu.tsx
index f1946791c53..f4fce7e402a 100644
--- a/src/renderer/src/components/terminal-pane/TerminalContextMenu.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalContextMenu.tsx
@@ -5,6 +5,7 @@ import {
   Maximize2,
   Minimize2,
   PanelBottomClose,
+  PanelsTopLeft,
   PanelRightClose,
   Pencil,
   SquareTerminal,
@@ -36,6 +37,8 @@ type TerminalContextMenuProps = {
   onPaste: () => void
   onSplitRight: () => void
   onSplitDown: () => void
+  canEqualizePaneSizes: boolean
+  onEqualizePaneSizes: () => void
   onClosePane: () => void
   onClearScreen: () => void
   quickCommands: TerminalQuickCommand[]
@@ -56,6 +59,8 @@ export default function TerminalContextMenu({
   onPaste,
   onSplitRight,
   onSplitDown,
+  canEqualizePaneSizes,
+  onEqualizePaneSizes,
   onClosePane,
   onClearScreen,
   quickCommands,
@@ -154,6 +159,12 @@ export default function TerminalContextMenu({
               Ctrl+Shift+D is taken by split-right (#586). */}
           <DropdownMenuShortcut>{isMac ? `${mod}${shift}D` : `Alt+${shift}D`}</DropdownMenuShortcut>
         </DropdownMenuItem>
+        {canEqualizePaneSizes && (
+          <DropdownMenuItem onSelect={onEqualizePaneSizes}>
+            <PanelsTopLeft />
+            Equalize Pane Sizes
+          </DropdownMenuItem>
+        )}
         {canExpandPane && (
           <DropdownMenuItem onSelect={onToggleExpand}>
             {menuPaneIsExpanded ? <Minimize2 /> : <Maximize2 />}
diff --git a/src/renderer/src/components/terminal-pane/TerminalPane.tsx b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
index f891f762d67..da162b18ccc 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
@@ -1150,6 +1150,7 @@ export default function TerminalPane({
         menuOpenedAtRef={contextMenu.menuOpenedAtRef}
         canClosePane={contextMenu.paneCount > 1}
         canExpandPane={contextMenu.paneCount > 1}
+        canEqualizePaneSizes={contextMenu.paneCount > 1 && expandedPaneId === null}
         menuPaneIsExpanded={
           contextMenu.menuPaneId !== null && contextMenu.menuPaneId === expandedPaneId
         }
@@ -1157,6 +1158,7 @@ export default function TerminalPane({
         onPaste={() => void contextMenu.onPaste()}
         onSplitRight={contextMenu.onSplitRight}
         onSplitDown={contextMenu.onSplitDown}
+        onEqualizePaneSizes={contextMenu.onEqualizePaneSizes}
         onClosePane={contextMenu.onClosePane}
         onClearScreen={contextMenu.onClearScreen}
         quickCommands={(settings?.terminalQuickCommands ?? []).filter(
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-context-menu.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-context-menu.ts
index c418419213e..e265ca980b6 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-context-menu.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-context-menu.ts
@@ -30,6 +30,7 @@ type TerminalMenuState = {
   onPaste: () => Promise<void>
   onSplitRight: () => void
   onSplitDown: () => void
+  onEqualizePaneSizes: () => void
   onClosePane: () => void
   onClearScreen: () => void
   onQuickCommand: (command: TerminalQuickCommand) => void
@@ -148,6 +149,16 @@ export function useTerminalPaneContextMenu({
   const onSplitRight = (): void => splitWithInheritedCwd('vertical')
   const onSplitDown = (): void => splitWithInheritedCwd('horizontal')
 
+  const onEqualizePaneSizes = (): void => {
+    const pane = resolveMenuPane()
+    const manager = managerRef.current
+    if (!pane || !manager) {
+      return
+    }
+    manager.equalizePaneSizes()
+    pane.terminal.focus()
+  }
+
   const onClosePane = (): void => {
     const pane = resolveMenuPane()
     if (pane && (managerRef.current?.getPanes().length ?? 0) > 1) {
@@ -241,6 +252,7 @@ export function useTerminalPaneContextMenu({
     onPaste,
     onSplitRight,
     onSplitDown,
+    onEqualizePaneSizes,
     onClosePane,
     onClearScreen,
     onQuickCommand,
diff --git a/src/renderer/src/lib/pane-manager/pane-manager.ts b/src/renderer/src/lib/pane-manager/pane-manager.ts
index 5ead38cc96b..6923fa3339d 100644
--- a/src/renderer/src/lib/pane-manager/pane-manager.ts
+++ b/src/renderer/src/lib/pane-manager/pane-manager.ts
@@ -14,7 +14,7 @@ import {
 import { createDragReorderState, hideDropOverlay, handlePaneDrop } from './pane-drag-reorder'
 import { createPaneDOM, openTerminal, setLigaturesEnabled, disposePane } from './pane-lifecycle'
 import { shouldFollowMouseFocus } from './focus-follows-mouse'
-import { safeFit, fitAllPanesInternal, refitPanesUnder } from './pane-tree-ops'
+import { equalizePaneSplitSizes, safeFit, fitAllPanesInternal, refitPanesUnder } from './pane-tree-ops'
 import { toPublicPane } from './pane-public-view'
 import { applyTerminalGpuAcceleration } from './pane-terminal-gpu-acceleration'
 import {
@@ -119,6 +119,21 @@ export class PaneManager {
     fitAllPanesInternal(this.panes)
   }
 
+  equalizePaneSizes(): void {
+    if (this.panes.size < 2) {
+      return
+    }
+
+    const changed = equalizePaneSplitSizes(
+      this.root.firstElementChild instanceof HTMLElement ? this.root.firstElementChild : null
+    )
+    if (!changed) {
+      return
+    }
+
+    this.options.onLayoutChanged?.()
+  }
+
   getActivePane(): ManagedPane | null {
     if (this.activePaneId === null) {
       return null
diff --git a/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts b/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
index b163d4934f3..577dd8e0234 100644
--- a/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
+++ b/src/renderer/src/lib/pane-manager/pane-tree-ops.test.ts
@@ -1,8 +1,24 @@
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { safeFit } from './pane-tree-ops'
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { equalizePaneSplitSizes, safeFit } from './pane-tree-ops'
 import type { ManagedPaneInternal, ScrollState } from './pane-manager-types'
 import { setFitOverride, hydrateOverrides } from './mobile-fit-overrides'
 
+class MockHTMLElement {
+  classList: { contains: (cls: string) => boolean }
+  children: MockHTMLElement[]
+  style: Record<string, string>
+
+  constructor(classes: string[], children: MockHTMLElement[] = [], flex = '') {
+    this.classList = { contains: (cls: string) => classes.includes(cls) }
+    this.children = children
+    this.style = { flex }
+  }
+}
+
+beforeAll(() => {
+  ;(globalThis as unknown as Record<string, unknown>).HTMLElement = MockHTMLElement
+})
+
 afterEach(() => {
   hydrateOverrides([])
 })
@@ -214,3 +230,52 @@ describe('safeFit', () => {
     expect(paneB.terminal.resize).not.toHaveBeenCalled()
   })
 })
+
+describe('equalizePaneSplitSizes', () => {
+  const pane = (flex = '1 1 0%'): MockHTMLElement => new MockHTMLElement(['pane'], [], flex)
+  const split = (
+    direction: 'vertical' | 'horizontal',
+    children: MockHTMLElement[],
+    flex = '1 1 0%'
+  ): MockHTMLElement =>
+    new MockHTMLElement(
+      ['pane-split', direction === 'vertical' ? 'is-vertical' : 'is-horizontal'],
+      children,
+      flex
+    )
+
+  it('weights nested same-axis splits so same-axis panes equalize evenly', () => {
+    const left = pane('10 1 0%')
+    const middle = pane('20 1 0%')
+    const right = pane('30 1 0%')
+    const rightSplit = split('vertical', [middle, right], '90 1 0%')
+    const root = split('vertical', [left, rightSplit])
+
+    expect(equalizePaneSplitSizes(root as unknown as HTMLElement)).toBe(true)
+
+    expect(left.style.flex).toBe('1 1 0%')
+    expect(rightSplit.style.flex).toBe('2 1 0%')
+    expect(middle.style.flex).toBe('1 1 0%')
+    expect(right.style.flex).toBe('1 1 0%')
+  })
+
+  it('treats perpendicular child splits as one weighted region', () => {
+    const top = pane('7 1 0%')
+    const bottom = pane('3 1 0%')
+    const leftStack = split('horizontal', [top, bottom], '15 1 0%')
+    const right = pane('85 1 0%')
+    const root = split('vertical', [leftStack, right])
+
+    expect(equalizePaneSplitSizes(root as unknown as HTMLElement)).toBe(true)
+
+    expect(leftStack.style.flex).toBe('1 1 0%')
+    expect(right.style.flex).toBe('1 1 0%')
+    expect(top.style.flex).toBe('1 1 0%')
+    expect(bottom.style.flex).toBe('1 1 0%')
+  })
+
+  it('returns false when there is no split tree to change', () => {
+    expect(equalizePaneSplitSizes(pane() as unknown as HTMLElement)).toBe(false)
+    expect(equalizePaneSplitSizes(null)).toBe(false)
+  })
+})
diff --git a/src/renderer/src/lib/pane-manager/pane-tree-ops.ts b/src/renderer/src/lib/pane-manager/pane-tree-ops.ts
index 4359e4fd7c2..cdb97e47ff9 100644
--- a/src/renderer/src/lib/pane-manager/pane-tree-ops.ts
+++ b/src/renderer/src/lib/pane-manager/pane-tree-ops.ts
@@ -280,6 +280,57 @@ export function findPaneChildren(parent: HTMLElement): HTMLElement[] {
   )
 }
 
+function getSplitDirection(split: HTMLElement): 'vertical' | 'horizontal' {
+  return split.classList.contains('is-horizontal') ? 'horizontal' : 'vertical'
+}
+
+function getEqualizeWeight(el: HTMLElement, direction: 'vertical' | 'horizontal'): number {
+  if (!el.classList.contains('pane-split') || getSplitDirection(el) !== direction) {
+    return 1
+  }
+
+  const children = findPaneChildren(el)
+  return Math.max(
+    1,
+    children.reduce((sum, child) => sum + getEqualizeWeight(child, direction), 0)
+  )
+}
+
+export function equalizePaneSplitSizes(root: HTMLElement | null): boolean {
+  if (!root) {
+    return false
+  }
+
+  let changed = false
+  const visit = (el: HTMLElement): void => {
+    if (!el.classList.contains('pane-split')) {
+      return
+    }
+
+    const direction = getSplitDirection(el)
+    const children = findPaneChildren(el)
+    if (children.length >= 2) {
+      for (const child of children) {
+        // Why: same-axis nested splits need pane-count weighting so three
+        // side-by-side panes become thirds, not 50/25/25.
+        const weight = getEqualizeWeight(child, direction)
+        const nextFlex = `${weight} 1 0%`
+        if (child.style.flex !== nextFlex) {
+          child.style.flex = nextFlex
+          changed = true
+        }
+      }
+    }
+
+    for (const child of children) {
+      visit(child)
+    }
+  }
+
+  visit(root)
+  return changed
+}
+
 /**
  * Create a flex split wrapper that replaces `existingContainer` in the DOM,
  * then places [existing] [divider] [new] inside it.

From b93849a577671857e4a97efc11dc3fe38a50cc29 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:41:30 -0700
Subject: [PATCH 72/82] Add inline diff note edit E2E coverage (#1951)

* Add inline diff note edit coverage

* test: add diff note edit coverage
---
 tests/e2e/diff-note-edit.spec.ts | 130 +++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 tests/e2e/diff-note-edit.spec.ts

diff --git a/tests/e2e/diff-note-edit.spec.ts b/tests/e2e/diff-note-edit.spec.ts
new file mode 100644
index 00000000000..9d465d6fa76
--- /dev/null
+++ b/tests/e2e/diff-note-edit.spec.ts
@@ -0,0 +1,130 @@
+import { test, expect } from './helpers/orca-app'
+import { waitForSessionReady, waitForActiveWorktree } from './helpers/store'
+
+test.describe('Diff note edit', () => {
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+    await waitForActiveWorktree(orcaPage)
+  })
+
+  test('editing a saved inline note updates the open diff card', async ({ orcaPage }) => {
+    const worktreeId = await waitForActiveWorktree(orcaPage)
+    const seededBody = 'edit-me note'
+    const editedBody = 'edited note from the inline card'
+
+    // Why: create a real modified-file diff so Monaco mounts the saved-note
+    // view zone on the same local surface that wires updateDiffComment.
+    const { relativePath } = await orcaPage.evaluate(async (wId) => {
+      const store = window.__store
+      if (!store) {
+        throw new Error('window.__store is not available - is the app in dev mode?')
+      }
+      const state = store.getState()
+      const worktree = Object.values(state.worktreesByRepo)
+        .flat()
+        .find((entry) => entry.id === wId)
+      if (!worktree) {
+        throw new Error('active worktree not found')
+      }
+      const separator = worktree.path.includes('\\') ? '\\' : '/'
+      const rel = `src${separator}index.ts`
+      const absolutePath = `${worktree.path}${separator}${rel}`
+      await window.api.fs.writeFile({
+        filePath: absolutePath,
+        content: 'export const hello = "note-edit-test"\n'
+      })
+      return { relativePath: rel }
+    }, worktreeId)
+
+    const addResult = await orcaPage.evaluate(
+      async ({ wId, rel, body }) => {
+        const store = window.__store
+        if (!store) {
+          throw new Error('window.__store is not available')
+        }
+        return store.getState().addDiffComment({
+          worktreeId: wId,
+          filePath: rel,
+          lineNumber: 1,
+          body,
+          side: 'modified'
+        })
+      },
+      { wId: worktreeId, rel: relativePath, body: seededBody }
+    )
+    expect(addResult, 'addDiffComment returned null').not.toBeNull()
+    const commentId = addResult!.id
+
+    await orcaPage.evaluate(
+      ({ wId, rel }) => {
+        const store = window.__store
+        if (!store) {
+          throw new Error('window.__store is not available')
+        }
+        const state = store.getState()
+        const worktree = Object.values(state.worktreesByRepo)
+          .flat()
+          .find((entry) => entry.id === wId)
+        if (!worktree) {
+          throw new Error('active worktree not found')
+        }
+        const separator = worktree.path.includes('\\') ? '\\' : '/'
+        state.openDiff(wId, `${worktree.path}${separator}${rel}`, rel, 'typescript', false)
+      },
+      { wId: worktreeId, rel: relativePath }
+    )
+
+    const card = orcaPage.locator('.orca-diff-comment-card').first()
+    await expect(card, 'seeded inline note did not render').toBeVisible({ timeout: 15_000 })
+    await expect(card.locator('.orca-diff-comment-body')).toHaveText(seededBody)
+
+    await card.locator('.orca-diff-comment-edit').click()
+
+    const textarea = card.locator('.orca-diff-comment-popover-textarea')
+    await expect(textarea).toBeVisible()
+    await expect(textarea).toHaveValue(seededBody)
+
+    const saveButton = card
+      .locator('.orca-diff-comment-popover-footer button')
+      .filter({ hasText: 'Save' })
+    await expect(saveButton, 'Save should be disabled before the body changes').toBeDisabled()
+
+    await textarea.fill(editedBody)
+    await expect(saveButton, 'Save should be enabled for a non-empty changed body').toBeEnabled()
+    await saveButton.click()
+
+    await expect(textarea, 'edit controls did not close after saving').toHaveCount(0, {
+      timeout: 5_000
+    })
+
+    await expect
+      .poll(
+        async () =>
+          orcaPage.evaluate((id: string) => {
+            const store = window.__store
+            if (!store) {
+              return null
+            }
+            const all = Object.values(store.getState().worktreesByRepo)
+              .flat()
+              .flatMap((w) => w.diffComments ?? [])
+            const comment = all.find((c) => c.id === id)
+            return comment?.body ?? null
+          }, commentId),
+        {
+          timeout: 5_000,
+          message: 'updateDiffComment did not persist the edited body in the store'
+        }
+      )
+      .toBe(editedBody)
+
+    const updatedCard = orcaPage
+      .locator('.orca-diff-comment-card')
+      .filter({ has: orcaPage.locator('.orca-diff-comment-body', { hasText: editedBody }) })
+      .first()
+    await expect(updatedCard, 'inline card did not update in the open diff').toBeVisible()
+    await expect(updatedCard.locator('.orca-diff-comment-body')).toHaveText(editedBody)
+    await expect(updatedCard.locator('.orca-diff-comment-body')).not.toHaveText(seededBody)
+    await expect(updatedCard.locator('.orca-diff-comment-edit')).toBeVisible()
+  })
+})

From 12609a50e33de5e858de78618f2b1a437e7a389b Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:42:44 -0700
Subject: [PATCH 73/82] fix: address review findings (#1981)

---
 src/renderer/src/components/TaskPage.tsx      |  12 +--
 .../dashboard/DashboardAgentRow.tsx           | 102 +++++++-----------
 .../sidebar/useWorktreeAgentRows.ts           |   2 +-
 .../task-page-linear-team-selection.test.ts   |  37 +++++++
 .../task-page-linear-team-selection.ts        |  19 ++++
 src/renderer/src/components/ui/button.tsx     |  23 ++--
 .../migration-unsupported-agent-entry.test.ts |  33 ++++++
 .../lib/migration-unsupported-agent-entry.ts  |  46 +++++---
 8 files changed, 174 insertions(+), 100 deletions(-)
 create mode 100644 src/renderer/src/components/task-page-linear-team-selection.test.ts
 create mode 100644 src/renderer/src/components/task-page-linear-team-selection.ts
 create mode 100644 src/renderer/src/lib/migration-unsupported-agent-entry.test.ts

diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index a5b260ae00f..37cc7d74a79 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -58,6 +58,7 @@ import RepoDotLabel from '@/components/repo/RepoDotLabel'
 import IssueSourceIndicator, { sameGitHubOwnerRepo } from '@/components/github/IssueSourceIndicator'
 import IssueSourceSelector, { issueSourceChipClass } from '@/components/github/IssueSourceSelector'
 import GitHubRateLimitPill from '@/components/github/GitHubRateLimitPill'
+import { reconcileLinearTeamSelection } from '@/components/task-page-linear-team-selection'
 import { stripRepoQualifiers } from '../../../shared/task-query'
 import GitHubItemDialog from '@/components/GitHubItemDialog'
 import GitLabItemDialog from '@/components/GitLabItemDialog'
@@ -1078,15 +1079,10 @@ export default function TaskPage(): React.JSX.Element {
     return new Set(defaultLinearTeamSelection)
   })
 
-  // Why: in sticky-all mode, auto-include all teams once the list arrives.
-  // In explicit-selection mode, the set is already correct from the initializer.
+  // Why: team IDs belong to one Linear workspace. Switching workspaces while a
+  // saved subset exists must not leave the task list filtered by stale team IDs.
   useEffect(() => {
-    if (availableTeams.length === 0) {
-      return
-    }
-    if (!defaultLinearTeamSelection) {
-      setLinearTeamSelection(new Set(availableTeams.map((t) => t.id)))
-    }
+    setLinearTeamSelection(reconcileLinearTeamSelection(availableTeams, defaultLinearTeamSelection))
   }, [availableTeams, defaultLinearTeamSelection])
 
   const displayedLinearIssues = useMemo(
diff --git a/src/renderer/src/components/dashboard/DashboardAgentRow.tsx b/src/renderer/src/components/dashboard/DashboardAgentRow.tsx
index 6b9f841b8d4..e8c6cbcea2f 100644
--- a/src/renderer/src/components/dashboard/DashboardAgentRow.tsx
+++ b/src/renderer/src/components/dashboard/DashboardAgentRow.tsx
@@ -1,7 +1,6 @@
 import React, { useState, useCallback } from 'react'
 import { X, Wrench, ChevronDown } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import { Tooltip, TooltipTrigger, TooltipContent } from '@/components/ui/tooltip'
 import { AgentStateDot, agentStateLabel, type AgentDotState } from '@/components/AgentStateDot'
 import { AgentIcon } from '@/lib/agent-catalog'
 import { agentTypeToIconAgent, formatAgentTypeLabel } from '@/lib/agent-status'
@@ -222,16 +221,12 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
             bar + right-side dot combo, which double-encoded state. Size md
             gives the glyph enough presence for the leading slot without
             overpowering the prompt text. */}
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <span className="inline-flex shrink-0 items-center justify-center">
-              <AgentStateDot state={asDotState(agent.state)} size={stateDotSize} />
-            </span>
-          </TooltipTrigger>
-          <TooltipContent side="top" sideOffset={4}>
-            {agent.entry.interrupted ? 'Interrupted' : agentStateLabel(asDotState(agent.state))}
-          </TooltipContent>
-        </Tooltip>
+        <span
+          className="inline-flex shrink-0 items-center justify-center"
+          title={agent.entry.interrupted ? 'Interrupted' : agentStateLabel(asDotState(agent.state))}
+        >
+          <AgentStateDot state={asDotState(agent.state)} size={stateDotSize} />
+        </span>
         {/* Why: identity (Claude/Codex/Gemini/…) sits inline with the prompt
             so the reader gets "state → who → what they said" left-to-right
             on the top row. The sub-rows (tool step, assistant response) are
@@ -239,16 +234,9 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
             them — keeping the icon only on the prompt row lets the sub-rows
             indent under the prompt text cleanly. */}
         {!hideIdentityIcon && (
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <span className="inline-flex shrink-0">
-                <AgentIcon agent={agentTypeToIconAgent(agent.agentType)} size={14} />
-              </span>
-            </TooltipTrigger>
-            <TooltipContent side="top" sideOffset={4}>
-              {formatAgentTypeLabel(agent.agentType)}
-            </TooltipContent>
-          </Tooltip>
+          <span className="inline-flex shrink-0" title={formatAgentTypeLabel(agent.agentType)}>
+            <AgentIcon agent={agentTypeToIconAgent(agent.agentType)} size={14} />
+          </span>
         )}
         {/* Why: animate between a 1-line clipped height and the content's
             natural height using Chromium's `interpolate-size: allow-keywords`
@@ -321,27 +309,21 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
                     ? formatTimeAgo(startedAt, now)
                     : null}
               </span>
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <button
-                    type="button"
-                    onClick={handleDismiss}
-                    onMouseDown={stopMouseDown}
-                    onKeyDown={stopKeyDown}
-                    className={cn(
-                      '[grid-area:1/1] inline-flex items-center justify-center text-muted-foreground/70 hover:text-foreground',
-                      'opacity-0 transition-opacity duration-150',
-                      'group-hover:opacity-100 focus-visible:opacity-100'
-                    )}
-                    aria-label="Dismiss agent"
-                  >
-                    <X className="size-3.5" />
-                  </button>
-                </TooltipTrigger>
-                <TooltipContent side="top" sideOffset={4}>
-                  Dismiss
-                </TooltipContent>
-              </Tooltip>
+              <button
+                type="button"
+                onClick={handleDismiss}
+                onMouseDown={stopMouseDown}
+                onKeyDown={stopKeyDown}
+                className={cn(
+                  '[grid-area:1/1] inline-flex items-center justify-center text-muted-foreground/70 hover:text-foreground',
+                  'opacity-0 transition-opacity duration-150',
+                  'group-hover:opacity-100 focus-visible:opacity-100'
+                )}
+                aria-label="Dismiss agent"
+                title="Dismiss"
+              >
+                <X className="size-3.5" />
+              </button>
             </span>
           )}
           {/* Why: when there is no timestamp yet (fresh agent, never
@@ -350,27 +332,21 @@ const DashboardAgentRow = React.memo(function DashboardAgentRow({
               reachable. Rare path; most rows have a timestamp the moment
               they start. */}
           {startedAt === null && doneAt === null && (
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <button
-                  type="button"
-                  onClick={handleDismiss}
-                  onMouseDown={stopMouseDown}
-                  onKeyDown={stopKeyDown}
-                  className={cn(
-                    'inline-flex shrink-0 items-center justify-center text-muted-foreground/70 hover:text-foreground',
-                    'opacity-0 transition-opacity duration-150',
-                    'group-hover:opacity-100 focus-visible:opacity-100'
-                  )}
-                  aria-label="Dismiss agent"
-                >
-                  <X className="size-3.5" />
-                </button>
-              </TooltipTrigger>
-              <TooltipContent side="top" sideOffset={4}>
-                Dismiss
-              </TooltipContent>
-            </Tooltip>
+            <button
+              type="button"
+              onClick={handleDismiss}
+              onMouseDown={stopMouseDown}
+              onKeyDown={stopKeyDown}
+              className={cn(
+                'inline-flex shrink-0 items-center justify-center text-muted-foreground/70 hover:text-foreground',
+                'opacity-0 transition-opacity duration-150',
+                'group-hover:opacity-100 focus-visible:opacity-100'
+              )}
+              aria-label="Dismiss agent"
+              title="Dismiss"
+            >
+              <X className="size-3.5" />
+            </button>
           )}
           {/* Why: chevron points down when collapsed (content below is
               available) and rotates 180° to point up when expanded
diff --git a/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts b/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
index 20d13af57db..d0286bbeb20 100644
--- a/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
+++ b/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
@@ -115,7 +115,7 @@ export function useWorktreeAgentRows(worktreeId: string): DashboardAgentRow[] {
         }
         out.push(entry)
       }
-      for (const unsupported of Object.values(s.migrationUnsupportedByPtyId)) {
+      for (const unsupported of Object.values(s.migrationUnsupportedByPtyId ?? {})) {
         const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
         if (!entry) {
           continue
diff --git a/src/renderer/src/components/task-page-linear-team-selection.test.ts b/src/renderer/src/components/task-page-linear-team-selection.test.ts
new file mode 100644
index 00000000000..a3d1a207b12
--- /dev/null
+++ b/src/renderer/src/components/task-page-linear-team-selection.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+import type { LinearTeam } from '../../../shared/types'
+import { reconcileLinearTeamSelection } from './task-page-linear-team-selection'
+
+function team(id: string): LinearTeam {
+  return {
+    id,
+    name: id,
+    key: id.toUpperCase()
+  }
+}
+
+describe('reconcileLinearTeamSelection', () => {
+  it('selects every available team when the saved selection is sticky-all', () => {
+    expect(Array.from(reconcileLinearTeamSelection([team('a'), team('b')], null))).toEqual([
+      'a',
+      'b'
+    ])
+  })
+
+  it('preserves saved teams that still exist', () => {
+    expect(Array.from(reconcileLinearTeamSelection([team('a'), team('b')], ['b']))).toEqual(['b'])
+  })
+
+  it('drops stale saved teams after switching workspaces', () => {
+    expect(Array.from(reconcileLinearTeamSelection([team('c'), team('d')], ['a', 'd']))).toEqual([
+      'd'
+    ])
+  })
+
+  it('falls back to all current teams when every saved team is stale', () => {
+    expect(Array.from(reconcileLinearTeamSelection([team('c'), team('d')], ['a', 'b']))).toEqual([
+      'c',
+      'd'
+    ])
+  })
+})
diff --git a/src/renderer/src/components/task-page-linear-team-selection.ts b/src/renderer/src/components/task-page-linear-team-selection.ts
new file mode 100644
index 00000000000..f6d7e52fa1f
--- /dev/null
+++ b/src/renderer/src/components/task-page-linear-team-selection.ts
@@ -0,0 +1,19 @@
+import type { LinearTeam } from '../../../shared/types'
+
+export function reconcileLinearTeamSelection(
+  availableTeams: LinearTeam[],
+  storedSelection: readonly string[] | null | undefined
+): ReadonlySet<string> {
+  const availableIds = availableTeams.map((team) => team.id)
+  if (availableIds.length === 0) {
+    return new Set()
+  }
+
+  const availableIdSet = new Set(availableIds)
+  const validStoredSelection = (storedSelection ?? []).filter((id) => availableIdSet.has(id))
+  if (validStoredSelection.length > 0) {
+    return new Set(validStoredSelection)
+  }
+
+  return new Set(availableIds)
+}
diff --git a/src/renderer/src/components/ui/button.tsx b/src/renderer/src/components/ui/button.tsx
index d87333920c9..d73a70461d4 100644
--- a/src/renderer/src/components/ui/button.tsx
+++ b/src/renderer/src/components/ui/button.tsx
@@ -36,20 +36,21 @@ const buttonVariants = cva(
   }
 )
 
-function Button({
-  className,
-  variant = 'default',
-  size = 'default',
-  asChild = false,
-  ...props
-}: React.ComponentProps<'button'> &
-  VariantProps<typeof buttonVariants> & {
-    asChild?: boolean
-  }) {
+const Button = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<'button'> &
+    VariantProps<typeof buttonVariants> & {
+      asChild?: boolean
+    }
+>(function Button(
+  { className, variant = 'default', size = 'default', asChild = false, ...props },
+  ref
+) {
   const Comp = asChild ? Slot.Root : 'button'
 
   return (
     <Comp
+      ref={ref}
       data-slot="button"
       data-variant={variant}
       data-size={size}
@@ -57,6 +58,6 @@ function Button({
       {...props}
     />
   )
-}
+})
 
 export { Button, buttonVariants }
diff --git a/src/renderer/src/lib/migration-unsupported-agent-entry.test.ts b/src/renderer/src/lib/migration-unsupported-agent-entry.test.ts
new file mode 100644
index 00000000000..cdb59cc02e1
--- /dev/null
+++ b/src/renderer/src/lib/migration-unsupported-agent-entry.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { migrationUnsupportedToAgentStatusEntry } from './migration-unsupported-agent-entry'
+import type { MigrationUnsupportedPtyEntry } from '../../../shared/agent-status-types'
+
+describe('migrationUnsupportedToAgentStatusEntry', () => {
+  it('returns a stable synthetic entry for the same migration record', () => {
+    const unsupported: MigrationUnsupportedPtyEntry = {
+      ptyId: 'pty-1',
+      paneKey: 'tab-1:11111111-1111-4111-8111-111111111111',
+      reason: 'legacy-numeric-pane-key',
+      source: 'local',
+      updatedAt: 1234
+    }
+
+    const first = migrationUnsupportedToAgentStatusEntry(unsupported)
+    const second = migrationUnsupportedToAgentStatusEntry(unsupported)
+
+    expect(second).toBe(first)
+    expect(first?.updatedAt).toBe(Number.MAX_SAFE_INTEGER)
+  })
+
+  it('caches null for records that cannot be projected to a pane key', () => {
+    const unsupported: MigrationUnsupportedPtyEntry = {
+      ptyId: 'pty-1',
+      reason: 'legacy-numeric-pane-key',
+      source: 'ssh',
+      updatedAt: 1234
+    }
+
+    expect(migrationUnsupportedToAgentStatusEntry(unsupported)).toBeNull()
+    expect(migrationUnsupportedToAgentStatusEntry(unsupported)).toBeNull()
+  })
+})
diff --git a/src/renderer/src/lib/migration-unsupported-agent-entry.ts b/src/renderer/src/lib/migration-unsupported-agent-entry.ts
index 5f3e83496c9..20033a486c5 100644
--- a/src/renderer/src/lib/migration-unsupported-agent-entry.ts
+++ b/src/renderer/src/lib/migration-unsupported-agent-entry.ts
@@ -3,25 +3,37 @@ import type {
   MigrationUnsupportedPtyEntry
 } from '../../../shared/agent-status-types'
 
+const cachedMigrationUnsupportedEntries = new WeakMap<
+  MigrationUnsupportedPtyEntry,
+  AgentStatusEntry | null
+>()
+
 export function migrationUnsupportedToAgentStatusEntry(
   entry: MigrationUnsupportedPtyEntry
 ): AgentStatusEntry | null {
-  if (!entry.paneKey) {
-    return null
-  }
-  const now = Date.now()
-  return {
-    state: 'blocked',
-    prompt: 'Agent unavailable after pane identity migration',
-    // Why: this is a persistent migration block, not a hook heartbeat. Keep it
-    // fresh while present so normal stale-status decay does not hide it.
-    updatedAt: Math.max(entry.updatedAt, now),
-    stateStartedAt: entry.updatedAt,
-    agentType: 'unknown',
-    paneKey: entry.paneKey,
-    terminalTitle: 'Migration unsupported',
-    stateHistory: [],
-    lastAssistantMessage:
-      'Restart this terminal so Orca can attach a stable UUID pane key to agent hooks.'
+  const cached = cachedMigrationUnsupportedEntries.get(entry)
+  if (cached !== undefined) {
+    return cached
   }
+
+  const converted: AgentStatusEntry | null = !entry.paneKey
+    ? null
+    : {
+        state: 'blocked',
+        prompt: 'Agent unavailable after pane identity migration',
+        // Why: this synthetic row represents a persistent migration block. Keep
+        // it "fresh" without Date.now() so Zustand selectors can return a stable
+        // cached object for the same store snapshot.
+        updatedAt: Number.MAX_SAFE_INTEGER,
+        stateStartedAt: entry.updatedAt,
+        agentType: 'unknown',
+        paneKey: entry.paneKey,
+        terminalTitle: 'Migration unsupported',
+        stateHistory: [],
+        lastAssistantMessage:
+          'Restart this terminal so Orca can attach a stable UUID pane key to agent hooks.'
+      }
+
+  cachedMigrationUnsupportedEntries.set(entry, converted)
+  return converted
 }

From 027f561b5bba2d7a9d903a55811b14bdaac818e2 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:43:07 -0700
Subject: [PATCH 74/82] fix: speed up quick workspace create (#1985)

---
 .../components/NewWorkspaceComposerModal.tsx  |   4 +-
 src/renderer/src/hooks/useComposerState.ts    | 129 +++++++++++++++---
 .../lib/new-workspace-create-gates.test.ts    |  61 +++++++++
 .../src/lib/new-workspace-create-gates.ts     |  36 +++++
 4 files changed, 207 insertions(+), 23 deletions(-)
 create mode 100644 src/renderer/src/lib/new-workspace-create-gates.test.ts
 create mode 100644 src/renderer/src/lib/new-workspace-create-gates.ts

diff --git a/src/renderer/src/components/NewWorkspaceComposerModal.tsx b/src/renderer/src/components/NewWorkspaceComposerModal.tsx
index 9db64d763cd..b7e5958a1ee 100644
--- a/src/renderer/src/components/NewWorkspaceComposerModal.tsx
+++ b/src/renderer/src/components/NewWorkspaceComposerModal.tsx
@@ -112,7 +112,9 @@ function QuickTabBody({
     ...(modalData.initialBaseBranch ? { initialBaseBranch: modalData.initialBaseBranch } : {}),
     persistDraft: false,
     onCreated: onClose,
-    ...(modalData.telemetrySource ? { telemetrySource: modalData.telemetrySource } : {})
+    ...(modalData.telemetrySource ? { telemetrySource: modalData.telemetrySource } : {}),
+    enableIssueAutomation: false,
+    createGateMode: 'quick'
   })
   // Why: the composer's built-in `onOpenAgentSettings` handler navigates to
   // the settings page and closes the modal. For the quick-create flow we want
diff --git a/src/renderer/src/hooks/useComposerState.ts b/src/renderer/src/hooks/useComposerState.ts
index 0ab7b97f693..3ff303c7bb5 100644
--- a/src/renderer/src/hooks/useComposerState.ts
+++ b/src/renderer/src/hooks/useComposerState.ts
@@ -46,13 +46,21 @@ import {
   renderIssueCommandTemplate,
   type LinkedWorkItemSummary
 } from '@/lib/new-workspace'
+import {
+  getFullComposerCreateDisabled,
+  getQuickComposerCreateDisabled
+} from '@/lib/new-workspace-create-gates'
 import { getSuggestedCreatureName } from '@/components/sidebar/worktree-name-suggestions'
 import type { SmartWorkspaceNameSelection } from '@/components/new-workspace/SmartWorkspaceNameField'
 import { ensureHooksConfirmed } from '@/lib/ensure-hooks-confirmed'
 import { normalizeSparseDirectoryLines, sparseDirectoriesMatch } from '@/lib/sparse-paths'
 import { joinPath } from '@/lib/path'
 import { importExternalPathsToRuntime } from '@/runtime/runtime-file-client'
-import { checkRuntimeHooks, readRuntimeIssueCommand } from '@/runtime/runtime-hooks-client'
+import {
+  checkRuntimeHooks,
+  readRuntimeIssueCommand,
+  type HookCheckResult
+} from '@/runtime/runtime-hooks-client'
 
 export type UseComposerStateOptions = {
   initialRepoId?: string
@@ -80,6 +88,11 @@ export type UseComposerStateOptions = {
    *  `sidebar`, keyboard shortcut → `shortcut`). Omitted callers default
    *  to `unknown` at the IPC boundary. */
   telemetrySource?: WorkspaceCreateTelemetrySource
+  /** Quick-create launches a blank/draft agent session and does not run
+   *  issueCommand automation, so it can skip the issue-command probe that the
+   *  full composer needs for linked-item prompt previews. */
+  enableIssueAutomation?: boolean
+  createGateMode?: 'full' | 'quick'
 }
 
 export type ComposerCardProps = {
@@ -198,7 +211,9 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     onCreated,
     repoIdOverride,
     onRepoIdOverrideChange,
-    telemetrySource
+    telemetrySource,
+    enableIssueAutomation = true,
+    createGateMode = 'full'
   } = options
 
   // Why: each `useAppStore(s => s.someAction)` registers its own equality
@@ -256,6 +271,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
 
   const [internalRepoId, setInternalRepoId] = useState<string>(resolvedInitialRepoId)
   const repoId = repoIdOverride ?? internalRepoId
+  const repoIdRef = useRef(repoId)
+  repoIdRef.current = repoId
   const setRepoId = useCallback(
     (value: string) => {
       if (onRepoIdOverrideChange) {
@@ -414,6 +431,31 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   selectedRepoPathRef.current = selectedRepoPath
   const settingsRef = useRef(settings)
   settingsRef.current = settings
+  const hookCheckRef = useRef<{
+    key: string
+    promise: Promise<HookCheckResult>
+  } | null>(null)
+  const loadHookCheckForRepo = useCallback((targetRepoId: string): Promise<HookCheckResult> => {
+    const key = `${settingsRef.current?.activeRuntimeEnvironmentId ?? 'local'}:${targetRepoId}`
+    const existing = hookCheckRef.current
+    if (existing?.key === key) {
+      return existing.promise
+    }
+    const promise = checkRuntimeHooks(settingsRef.current, targetRepoId)
+    hookCheckRef.current = { key, promise }
+    return promise
+  }, [])
+  const commitHookCheckIfCurrent = useCallback(
+    (targetRepoId: string, hooks: OrcaHooks | null): boolean => {
+      if (repoIdRef.current !== targetRepoId) {
+        return false
+      }
+      setYamlHooks(hooks)
+      setCheckedHooksRepoId(targetRepoId)
+      return true
+    },
+    []
+  )
   useEffect(() => {
     if (!selectedRepo || !selectedRepoPath) {
       setSelectedRepoSlug(null)
@@ -515,14 +557,17 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     [selectedRepo, yamlHooks]
   )
   const setupPolicy: SetupRunPolicy = selectedRepo?.hookSettings?.setupRunPolicy ?? 'run-by-default'
-  const hasIssueAutomationConfig = issueCommandTemplate.length > 0
+  const hasIssueAutomationConfig = enableIssueAutomation && issueCommandTemplate.length > 0
   const canOfferIssueAutomation = parsedLinkedIssueNumber !== null && hasIssueAutomationConfig
   // Why: the "no prompt + linked item" path below rehydrates the issueCommand
   // template into the main startup prompt. When that happens we suppress the
   // separate split pane that would otherwise run the same command twice.
-  const willApplyIssueCommandAsPrompt = !agentPrompt.trim() && Boolean(linkedWorkItem)
+  const willApplyIssueCommandAsPrompt =
+    enableIssueAutomation && !agentPrompt.trim() && Boolean(linkedWorkItem)
   const shouldWaitForIssueAutomationCheck =
-    (parsedLinkedIssueNumber !== null || willApplyIssueCommandAsPrompt) && !hasLoadedIssueCommand
+    enableIssueAutomation &&
+    (parsedLinkedIssueNumber !== null || willApplyIssueCommandAsPrompt) &&
+    !hasLoadedIssueCommand
   const shouldRunIssueAutomation = canOfferIssueAutomation && !willApplyIssueCommandAsPrompt
   const requiresExplicitSetupChoice = Boolean(setupConfig) && setupPolicy === 'ask'
   const resolvedSetupDecision =
@@ -561,7 +606,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   // the common "paste a link and hit enter" flow produce a useful agent task
   // instead of a bare URL bullet.
   const shouldApplyLinkedOnlyTemplate =
-    !agentPrompt.trim() && Boolean(linkedWorkItem) && hasLoadedIssueCommand
+    enableIssueAutomation && !agentPrompt.trim() && Boolean(linkedWorkItem) && hasLoadedIssueCommand
   const linkedOnlyTemplatePrompt = useMemo(() => {
     if (!shouldApplyLinkedOnlyTemplate || !linkedWorkItem) {
       return ''
@@ -712,20 +757,25 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     setYamlHooks(null)
     setCheckedHooksRepoId(null)
 
-    void checkRuntimeHooks(settings, repoId)
+    void loadHookCheckForRepo(repoId)
       .then((result) => {
         if (!cancelled) {
-          setYamlHooks(result.hooks)
-          setCheckedHooksRepoId(repoId)
+          commitHookCheckIfCurrent(repoId, result.hooks)
         }
       })
       .catch(() => {
         if (!cancelled) {
-          setYamlHooks(null)
-          setCheckedHooksRepoId(repoId)
+          commitHookCheckIfCurrent(repoId, null)
         }
       })
 
+    if (!enableIssueAutomation) {
+      setHasLoadedIssueCommand(true)
+      return () => {
+        cancelled = true
+      }
+    }
+
     void readRuntimeIssueCommand(settings, repoId)
       .then((result) => {
         if (!cancelled) {
@@ -743,7 +793,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     return () => {
       cancelled = true
     }
-  }, [repoId, settings])
+  }, [commitHookCheckIfCurrent, enableIssueAutomation, loadHookCheckForRepo, repoId, settings])
 
   // Why: warm the Start-from picker's PR cache on composer mount and whenever
   // the selected repo changes so opening the picker paints instantly from
@@ -1673,7 +1723,6 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         !repoId ||
         !workspaceName ||
         !selectedRepo ||
-        shouldWaitForSetupCheck ||
         (requiresExplicitSetupChoice && !setupDecision) ||
         sparseError !== null
       ) {
@@ -1683,11 +1732,37 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       setCreateError(null)
       setCreating(true)
       try {
+        let submitSetupConfig = setupConfig
+        let submitResolvedSetupDecision = resolvedSetupDecision
+        if (checkedHooksRepoId !== repoId) {
+          let hookCheck: HookCheckResult
+          try {
+            hookCheck = await loadHookCheckForRepo(repoId)
+          } catch {
+            hookCheck = { hasHooks: false, hooks: null, mayNeedUpdate: false }
+          }
+          if (!commitHookCheckIfCurrent(repoId, hookCheck.hooks)) {
+            return
+          }
+          submitSetupConfig = getSetupConfig(selectedRepo, hookCheck.hooks)
+          submitResolvedSetupDecision =
+            setupDecision ??
+            (!submitSetupConfig || setupPolicy === 'ask'
+              ? null
+              : setupPolicy === 'run-by-default'
+                ? 'run'
+                : 'skip')
+        }
+        if (submitSetupConfig && setupPolicy === 'ask' && !setupDecision) {
+          setAdvancedOpen(true)
+          return
+        }
+
         const trustDecision = await ensureHooksConfirmed(useAppStore.getState(), repoId, 'setup')
         const effectiveSetupDecision: SetupDecision =
           trustDecision === 'skip'
             ? 'skip'
-            : ((resolvedSetupDecision ?? 'inherit') as SetupDecision)
+            : ((submitResolvedSetupDecision ?? 'inherit') as SetupDecision)
 
         const linkedLinearIssue = linkedWorkItem?.linearIdentifier
         const result = await createWorktree(
@@ -1858,18 +1933,28 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       sparseError,
       effectivePresetId,
       telemetrySource,
-      shouldWaitForSetupCheck
+      checkedHooksRepoId,
+      commitHookCheckIfCurrent,
+      loadHookCheckForRepo,
+      setupConfig,
+      setupPolicy
     ]
   )
 
+  const createGateInput = {
+    repoId,
+    workspaceSeedName,
+    creating,
+    shouldWaitForSetupCheck,
+    shouldWaitForIssueAutomationCheck,
+    requiresExplicitSetupChoice,
+    hasSetupDecision: Boolean(setupDecision),
+    sparseError
+  }
   const createDisabled =
-    !repoId ||
-    !workspaceSeedName ||
-    creating ||
-    shouldWaitForSetupCheck ||
-    shouldWaitForIssueAutomationCheck ||
-    (requiresExplicitSetupChoice && !setupDecision) ||
-    sparseError !== null
+    createGateMode === 'quick'
+      ? getQuickComposerCreateDisabled(createGateInput)
+      : getFullComposerCreateDisabled(createGateInput)
 
   const cardProps: ComposerCardProps = {
     eligibleRepos,
diff --git a/src/renderer/src/lib/new-workspace-create-gates.test.ts b/src/renderer/src/lib/new-workspace-create-gates.test.ts
new file mode 100644
index 00000000000..d23102ddb3b
--- /dev/null
+++ b/src/renderer/src/lib/new-workspace-create-gates.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import {
+  getFullComposerCreateDisabled,
+  getQuickComposerCreateDisabled,
+  type ComposerCreateGateInput
+} from './new-workspace-create-gates'
+
+const readyInput: ComposerCreateGateInput = {
+  repoId: 'repo-1',
+  workspaceSeedName: 'feature',
+  creating: false,
+  shouldWaitForSetupCheck: false,
+  shouldWaitForIssueAutomationCheck: false,
+  requiresExplicitSetupChoice: false,
+  hasSetupDecision: false,
+  sparseError: null
+}
+
+describe('new workspace create gates', () => {
+  it('keeps the full composer disabled while setup and issue automation probes are pending', () => {
+    expect(
+      getFullComposerCreateDisabled({
+        ...readyInput,
+        shouldWaitForSetupCheck: true
+      })
+    ).toBe(true)
+
+    expect(
+      getFullComposerCreateDisabled({
+        ...readyInput,
+        shouldWaitForIssueAutomationCheck: true
+      })
+    ).toBe(true)
+  })
+
+  it('lets quick create submit while background setup and issue probes are pending', () => {
+    expect(
+      getQuickComposerCreateDisabled({
+        ...readyInput,
+        shouldWaitForSetupCheck: true,
+        shouldWaitForIssueAutomationCheck: true
+      })
+    ).toBe(false)
+  })
+
+  it('still blocks quick create for missing form state and explicit setup choices', () => {
+    expect(getQuickComposerCreateDisabled({ ...readyInput, repoId: '' })).toBe(true)
+    expect(getQuickComposerCreateDisabled({ ...readyInput, workspaceSeedName: '' })).toBe(true)
+    expect(getQuickComposerCreateDisabled({ ...readyInput, creating: true })).toBe(true)
+    expect(
+      getQuickComposerCreateDisabled({
+        ...readyInput,
+        requiresExplicitSetupChoice: true,
+        hasSetupDecision: false
+      })
+    ).toBe(true)
+    expect(getQuickComposerCreateDisabled({ ...readyInput, sparseError: 'Bad sparse path' })).toBe(
+      true
+    )
+  })
+})
diff --git a/src/renderer/src/lib/new-workspace-create-gates.ts b/src/renderer/src/lib/new-workspace-create-gates.ts
new file mode 100644
index 00000000000..e5ad63484ef
--- /dev/null
+++ b/src/renderer/src/lib/new-workspace-create-gates.ts
@@ -0,0 +1,36 @@
+export type ComposerCreateGateInput = {
+  repoId: string
+  workspaceSeedName: string
+  creating: boolean
+  shouldWaitForSetupCheck: boolean
+  shouldWaitForIssueAutomationCheck: boolean
+  requiresExplicitSetupChoice: boolean
+  hasSetupDecision: boolean
+  sparseError: string | null
+}
+
+function hasBlockingCreateState(input: ComposerCreateGateInput): boolean {
+  return (
+    !input.repoId ||
+    !input.workspaceSeedName ||
+    input.creating ||
+    (input.requiresExplicitSetupChoice && !input.hasSetupDecision) ||
+    input.sparseError !== null
+  )
+}
+
+export function getFullComposerCreateDisabled(input: ComposerCreateGateInput): boolean {
+  return (
+    hasBlockingCreateState(input) ||
+    input.shouldWaitForSetupCheck ||
+    input.shouldWaitForIssueAutomationCheck
+  )
+}
+
+export function getQuickComposerCreateDisabled(input: ComposerCreateGateInput): boolean {
+  // Why: Cmd/Ctrl+N quick create can resolve setup hooks inside the submit
+  // handler, and it never runs issue-command automation. Keeping those
+  // background probes out of the disabled gate makes the primary action usable
+  // as soon as the form has enough local state to submit.
+  return hasBlockingCreateState(input)
+}

From c90b9f72efaf4e365b07e7feb52a3ea0a5e3f2d7 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:37:25 -0700
Subject: [PATCH 75/82] Add PR review queue badge foundation

- Add provider-neutral review queue types, adapter, and checks-panel badges.\n- Keep the design doc out of the PR diff.
---
 src/main/github/gh-utils.test.ts              |  15 +++
 src/main/github/gh-utils.ts                   |  21 ++-
 .../components/right-sidebar/ChecksPanel.tsx  |  80 ++++++++++++
 src/shared/hosted-review-github.test.ts       |  98 ++++++++++++++
 src/shared/hosted-review-github.ts            |  88 +++++++++++++
 src/shared/hosted-review-queue.test.ts        | 103 +++++++++++++++
 src/shared/hosted-review-queue.ts             | 122 ++++++++++++++++++
 src/shared/hosted-review.ts                   |  53 ++++++++
 8 files changed, 577 insertions(+), 3 deletions(-)
 create mode 100644 src/shared/hosted-review-github.test.ts
 create mode 100644 src/shared/hosted-review-github.ts
 create mode 100644 src/shared/hosted-review-queue.test.ts
 create mode 100644 src/shared/hosted-review-queue.ts

diff --git a/src/main/github/gh-utils.test.ts b/src/main/github/gh-utils.test.ts
index 91cc8588b89..41ce4f465c3 100644
--- a/src/main/github/gh-utils.test.ts
+++ b/src/main/github/gh-utils.test.ts
@@ -20,6 +20,7 @@ import {
   classifyListIssuesError,
   getIssueOwnerRepo,
   getOwnerRepo,
+  parseGitHubRemoteIdentity,
   parseGitHubOwnerRepo,
   resolveIssueSource
 } from './gh-utils'
@@ -47,6 +48,20 @@ describe('github owner/repo resolution', () => {
     expect(parseGitHubOwnerRepo('git@example.com:stablyai/orca.git')).toBeNull()
   })
 
+  it('parses GitHub Enterprise host identity', () => {
+    expect(parseGitHubRemoteIdentity('https://ghe.acme.internal/acme/orca.git')).toEqual({
+      host: 'ghe.acme.internal',
+      owner: 'acme',
+      repo: 'orca'
+    })
+    expect(parseGitHubRemoteIdentity('git@ghe.acme.internal:acme/orca.git')).toEqual({
+      host: 'ghe.acme.internal',
+      owner: 'acme',
+      repo: 'orca'
+    })
+    expect(parseGitHubOwnerRepo('https://ghe.acme.internal/acme/orca.git')).toBeNull()
+  })
+
   it('keeps getOwnerRepo origin-based', async () => {
     gitExecFileAsyncMock.mockResolvedValueOnce({
       stdout: 'git@github.com:fork/orca.git\n'
diff --git a/src/main/github/gh-utils.ts b/src/main/github/gh-utils.ts
index 3d8b3478850..bcff859ad58 100644
--- a/src/main/github/gh-utils.ts
+++ b/src/main/github/gh-utils.ts
@@ -113,6 +113,8 @@ export function classifyListIssuesError(stderr: string): ClassifiedError {
 // short local name `OwnerRepo`.
 export type OwnerRepo = GitHubOwnerRepo
 
+export type GitHubRemoteIdentity = GitHubOwnerRepo & { host: string }
+
 export type GitHubRepoContext = {
   repoPath: string
   connectionId?: string | null
@@ -143,11 +145,24 @@ export function _resetOwnerRepoCache(): void {
 }
 
 export function parseGitHubOwnerRepo(remoteUrl: string): OwnerRepo | null {
-  const match = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/)
-  if (!match) {
+  const identity = parseGitHubRemoteIdentity(remoteUrl)
+  if (!identity || identity.host.toLowerCase() !== 'github.com') {
     return null
   }
-  return { owner: match[1], repo: match[2] }
+  return { owner: identity.owner, repo: identity.repo }
+}
+
+export function parseGitHubRemoteIdentity(remoteUrl: string): GitHubRemoteIdentity | null {
+  const trimmed = remoteUrl.trim()
+  const httpsMatch = trimmed.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i)
+  if (httpsMatch) {
+    return { host: httpsMatch[1], owner: httpsMatch[2], repo: httpsMatch[3] }
+  }
+  const sshMatch = trimmed.match(/^git@([^:]+):([^/]+)\/([^/]+?)(?:\.git)?$/i)
+  if (sshMatch) {
+    return { host: sshMatch[1], owner: sshMatch[2], repo: sshMatch[3] }
+  }
+  return null
 }
 
 export async function getRemoteUrlForRepo(
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index 7099e13c492..582a552a77c 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -22,6 +22,11 @@ import { getConnectionId } from '@/lib/connection-context'
 import { CreatePullRequestDialog } from './CreatePullRequestDialog'
 import type { HostedReviewCreationEligibility } from '../../../../shared/hosted-review'
 import { toast } from 'sonner'
+import {
+  classifyHostedReview,
+  type HostedReviewClassificationOptions
+} from '../../../../shared/hosted-review-queue'
+import { hostedReviewSummaryFromGitHubPRInfo } from '../../../../shared/hosted-review-github'
 
 export default function ChecksPanel(): React.JSX.Element {
   const activeWorktree = useActiveWorktree()
@@ -579,6 +584,68 @@ export default function ChecksPanel(): React.JSX.Element {
     ]
   )
 
+  const activeReviewClassification = React.useMemo(() => {
+    if (!pr || !repo) {
+      return null
+    }
+    let host = 'github.com'
+    let owner = 'unknown'
+    let repoName = 'unknown'
+    try {
+      const parsed = new URL(pr.url)
+      host = parsed.host || host
+      const segments = parsed.pathname.split('/').filter(Boolean)
+      if (segments.length >= 2) {
+        owner = segments[0]
+        repoName = segments[1]
+      }
+    } catch {
+      // Why: malformed URLs should not block queue-state classification.
+    }
+
+    // Why: unresolved thread data is paginated and fetched separately. Until
+    // comments have loaded for this PR, do not let queue badges imply a clean review.
+    const commentsForClassification =
+      commentsFetchedAt !== undefined && !commentsLoading ? comments : undefined
+    const summary = hostedReviewSummaryFromGitHubPRInfo({
+      pr,
+      owner,
+      repo: repoName,
+      host,
+      comments: commentsForClassification,
+      checks
+    })
+    const options: HostedReviewClassificationOptions = {
+      agentAuthorLogins: [],
+      viewer: null
+    }
+    return classifyHostedReview(summary, options)
+  }, [pr, repo, comments, commentsFetchedAt, commentsLoading, checks])
+
+  const queueBadges = React.useMemo(() => {
+    if (!activeReviewClassification) {
+      return [] as string[]
+    }
+    const badges: string[] = []
+    if (activeReviewClassification.needsResponse) {
+      badges.push('Needs response')
+    }
+    if (activeReviewClassification.readyToMerge) {
+      badges.push('Ready to merge')
+    }
+    if (activeReviewClassification.requested) {
+      badges.push('Review requested')
+    }
+    if (activeReviewClassification.state === 'mine') {
+      badges.push('My PR')
+    } else if (activeReviewClassification.state === 'agent') {
+      badges.push('AI PR')
+    } else {
+      badges.push('Teammate PR')
+    }
+    return badges
+  }, [activeReviewClassification])
+
   // ── Empty state ──
   if (!activeWorktree) {
     return (
@@ -763,6 +830,19 @@ export default function ChecksPanel(): React.JSX.Element {
           </div>
         )}
 
+        {queueBadges.length > 0 && (
+          <div className="flex flex-wrap gap-1.5">
+            {queueBadges.map((badge) => (
+              <span
+                key={badge}
+                className="rounded border border-border bg-accent/30 px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-wide text-muted-foreground"
+              >
+                {badge}
+              </span>
+            ))}
+          </div>
+        )}
+
         {/* Merge / Delete Worktree actions */}
         {activeWorktree && repo && (
           <PRActions pr={pr} repo={repo} worktree={activeWorktree} onRefreshPR={handleRefreshPR} />
diff --git a/src/shared/hosted-review-github.test.ts b/src/shared/hosted-review-github.test.ts
new file mode 100644
index 00000000000..6ab4dac0172
--- /dev/null
+++ b/src/shared/hosted-review-github.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+import { hostedReviewSummaryFromGitHubPRInfo } from './hosted-review-github'
+import type { PRInfo } from './types'
+
+const pr: PRInfo = {
+  number: 12,
+  title: 'Add queue badges',
+  state: 'open',
+  url: 'https://github.com/acme/orca/pull/12',
+  checksStatus: 'pending',
+  updatedAt: '2026-05-12T00:00:00.000Z',
+  mergeable: 'MERGEABLE',
+  headSha: 'abc123'
+}
+
+describe('hostedReviewSummaryFromGitHubPRInfo', () => {
+  it('maps PRInfo into provider-neutral summary with host identity', () => {
+    const summary = hostedReviewSummaryFromGitHubPRInfo({
+      pr,
+      owner: 'acme',
+      repo: 'orca',
+      host: 'github.acme.internal'
+    })
+
+    expect(summary.identity).toEqual({
+      provider: 'github',
+      host: 'github.acme.internal',
+      owner: 'acme',
+      repo: 'orca',
+      number: 12
+    })
+    expect(summary.checksStatus).toBe('pending')
+    expect(summary.threadSummary).toBeUndefined()
+  })
+
+  it('derives unresolved thread count and failing status from enrichers', () => {
+    const summary = hostedReviewSummaryFromGitHubPRInfo({
+      pr: { ...pr, checksStatus: 'success' },
+      owner: 'acme',
+      repo: 'orca',
+      comments: [
+        {
+          id: 1,
+          author: 'a',
+          authorAvatarUrl: '',
+          body: '',
+          createdAt: '',
+          url: '',
+          threadId: 't1',
+          isResolved: false
+        },
+        {
+          id: 2,
+          author: 'b',
+          authorAvatarUrl: '',
+          body: '',
+          createdAt: '',
+          url: '',
+          threadId: 't1',
+          isResolved: false
+        },
+        {
+          id: 3,
+          author: 'c',
+          authorAvatarUrl: '',
+          body: '',
+          createdAt: '',
+          url: '',
+          threadId: 't2',
+          isResolved: true
+        }
+      ],
+      checks: [{ name: 'ci', status: 'completed', conclusion: 'failure', url: null }]
+    })
+
+    expect(summary.threadSummary).toEqual({ unresolvedCount: 1, dataCompleteness: 'partial' })
+    expect(summary.checksStatus).toBe('failure')
+  })
+
+  it('distinguishes loaded empty comments from unknown comments', () => {
+    expect(
+      hostedReviewSummaryFromGitHubPRInfo({
+        pr,
+        owner: 'acme',
+        repo: 'orca'
+      }).threadSummary
+    ).toBeUndefined()
+
+    expect(
+      hostedReviewSummaryFromGitHubPRInfo({
+        pr,
+        owner: 'acme',
+        repo: 'orca',
+        comments: []
+      }).threadSummary
+    ).toEqual({ unresolvedCount: 0, dataCompleteness: 'partial' })
+  })
+})
diff --git a/src/shared/hosted-review-github.ts b/src/shared/hosted-review-github.ts
new file mode 100644
index 00000000000..ea733a59d1f
--- /dev/null
+++ b/src/shared/hosted-review-github.ts
@@ -0,0 +1,88 @@
+import type { PRCheckDetail, PRComment, PRInfo } from './types'
+import type { HostedReviewQueueSummary } from './hosted-review'
+
+export type HostedReviewFromGitHubPRInfoArgs = {
+  pr: PRInfo
+  owner: string
+  repo: string
+  host?: string
+  authorLogin?: string | null
+  authorIsBot?: boolean
+  requestedReviewerLogins?: string[] | null
+  comments?: PRComment[]
+  checks?: PRCheckDetail[]
+  lastViewedAt?: number
+}
+
+function unresolvedThreadCount(comments?: PRComment[]): number | null {
+  if (comments === undefined) {
+    return null
+  }
+  const unresolved = new Set<string>()
+  for (const comment of comments) {
+    if (!comment.threadId || comment.isResolved !== false) {
+      continue
+    }
+    unresolved.add(comment.threadId)
+  }
+  return unresolved.size
+}
+
+function deriveChecksStatus(
+  prChecksStatus: PRInfo['checksStatus'],
+  checks?: PRCheckDetail[]
+): PRInfo['checksStatus'] {
+  if (!checks || checks.length === 0) {
+    return prChecksStatus
+  }
+  const hasFailure = checks.some(
+    (check) => check.conclusion === 'failure' || check.conclusion === 'timed_out'
+  )
+  if (hasFailure) {
+    return 'failure'
+  }
+  const hasPending = checks.some(
+    (check) =>
+      check.status !== 'completed' || check.conclusion === null || check.conclusion === 'pending'
+  )
+  if (hasPending) {
+    return 'pending'
+  }
+  const hasSuccess = checks.some((check) => check.conclusion === 'success')
+  if (hasSuccess) {
+    return 'success'
+  }
+  return 'neutral'
+}
+
+export function hostedReviewSummaryFromGitHubPRInfo(
+  args: HostedReviewFromGitHubPRInfoArgs
+): HostedReviewQueueSummary {
+  const unresolvedCount = unresolvedThreadCount(args.comments)
+  return {
+    identity: {
+      provider: 'github',
+      host: args.host ?? 'github.com',
+      owner: args.owner,
+      repo: args.repo,
+      number: args.pr.number
+    },
+    title: args.pr.title,
+    url: args.pr.url,
+    state: args.pr.state,
+    author: args.authorLogin ? { login: args.authorLogin, isBot: args.authorIsBot } : null,
+    updatedAt: args.pr.updatedAt,
+    mergeable: args.pr.mergeable,
+    checksStatus: deriveChecksStatus(args.pr.checksStatus, args.checks),
+    threadSummary:
+      unresolvedCount === null
+        ? undefined
+        : {
+            unresolvedCount,
+            dataCompleteness: 'partial'
+          },
+    requestedReviewerLogins: args.requestedReviewerLogins,
+    lastViewedAt: args.lastViewedAt,
+    draft: args.pr.state === 'draft'
+  }
+}
diff --git a/src/shared/hosted-review-queue.test.ts b/src/shared/hosted-review-queue.test.ts
new file mode 100644
index 00000000000..4e75f314af5
--- /dev/null
+++ b/src/shared/hosted-review-queue.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import type { HostedReviewQueueSummary } from './hosted-review'
+import {
+  classifyHostedReview,
+  hostedReviewIdentityKey,
+  reviewNeedsResponse,
+  reviewReadyToMerge
+} from './hosted-review-queue'
+
+function baseSummary(overrides: Partial<HostedReviewQueueSummary> = {}): HostedReviewQueueSummary {
+  return {
+    identity: { provider: 'github', host: 'github.com', owner: 'acme', repo: 'orca', number: 42 },
+    title: 'Improve checks panel',
+    url: 'https://github.com/acme/orca/pull/42',
+    state: 'open',
+    author: { login: 'teammate' },
+    updatedAt: '2026-05-10T00:00:00.000Z',
+    mergeable: 'MERGEABLE',
+    checksStatus: 'success',
+    threadSummary: { unresolvedCount: 0 },
+    ...overrides
+  }
+}
+
+describe('hostedReviewIdentityKey', () => {
+  it('includes provider and host for enterprise-safe keys', () => {
+    const dotcom = hostedReviewIdentityKey({
+      provider: 'github',
+      host: 'github.com',
+      owner: 'acme',
+      repo: 'orca',
+      number: 7
+    })
+    const ghe = hostedReviewIdentityKey({
+      provider: 'github',
+      host: 'github.acme.internal',
+      owner: 'acme',
+      repo: 'orca',
+      number: 7
+    })
+    expect(dotcom).not.toBe(ghe)
+  })
+})
+
+describe('classifyHostedReview', () => {
+  it('classifies mine/requested/agent/teammate', () => {
+    expect(
+      classifyHostedReview(baseSummary({ author: { login: 'me' } }), {
+        viewer: { login: 'me' }
+      }).state
+    ).toBe('mine')
+
+    expect(
+      classifyHostedReview(baseSummary({ requestedReviewerLogins: ['me'] }), {
+        viewer: { login: 'me' }
+      }).state
+    ).toBe('requested')
+
+    expect(
+      classifyHostedReview(baseSummary({ author: { login: 'orca-ci' } }), {
+        agentAuthorLogins: ['orca-ci']
+      }).state
+    ).toBe('agent')
+
+    expect(classifyHostedReview(baseSummary()).state).toBe('teammate')
+  })
+})
+
+describe('reviewNeedsResponse', () => {
+  it('returns true for unresolved threads, failed checks, conflicts, and newer remote updates', () => {
+    expect(reviewNeedsResponse(baseSummary({ threadSummary: { unresolvedCount: 1 } }))).toBe(true)
+    expect(reviewNeedsResponse(baseSummary({ checksStatus: 'failure' }))).toBe(true)
+    expect(reviewNeedsResponse(baseSummary({ mergeable: 'CONFLICTING' }))).toBe(true)
+    expect(
+      reviewNeedsResponse(
+        baseSummary({
+          updatedAt: '2026-05-11T00:00:00.000Z',
+          lastViewedAt: Date.parse('2026-05-10T00:00:00.000Z')
+        })
+      )
+    ).toBe(true)
+  })
+
+  it('does not mark needs-response from updatedAt alone when lastViewedAt is missing', () => {
+    expect(reviewNeedsResponse(baseSummary({ updatedAt: '2026-05-11T00:00:00.000Z' }))).toBe(false)
+  })
+})
+
+describe('reviewReadyToMerge', () => {
+  it('rejects drafts, conflicts, failed/pending checks, unresolved threads, and unknown mergeability', () => {
+    expect(reviewReadyToMerge(baseSummary({ state: 'draft', draft: true }))).toBe(false)
+    expect(reviewReadyToMerge(baseSummary({ mergeable: 'CONFLICTING' }))).toBe(false)
+    expect(reviewReadyToMerge(baseSummary({ checksStatus: 'failure' }))).toBe(false)
+    expect(reviewReadyToMerge(baseSummary({ checksStatus: 'pending' }))).toBe(false)
+    expect(reviewReadyToMerge(baseSummary({ threadSummary: { unresolvedCount: 2 } }))).toBe(false)
+    expect(reviewReadyToMerge(baseSummary({ threadSummary: undefined }))).toBe(false)
+    expect(reviewReadyToMerge(baseSummary({ mergeable: 'UNKNOWN' }))).toBe(false)
+  })
+
+  it('accepts neutral checks when all other gates pass', () => {
+    expect(reviewReadyToMerge(baseSummary({ checksStatus: 'neutral' }))).toBe(true)
+  })
+})
diff --git a/src/shared/hosted-review-queue.ts b/src/shared/hosted-review-queue.ts
new file mode 100644
index 00000000000..ddd6a4212d7
--- /dev/null
+++ b/src/shared/hosted-review-queue.ts
@@ -0,0 +1,122 @@
+import type {
+  HostedReviewIdentity,
+  HostedReviewQueueClassification,
+  HostedReviewQueueState,
+  HostedReviewQueueSummary,
+  HostedReviewUser
+} from './hosted-review'
+
+export type HostedReviewClassificationOptions = {
+  viewer?: HostedReviewUser | null
+  agentAuthorLogins?: string[]
+}
+
+export function hostedReviewIdentityKey(identity: HostedReviewIdentity): string {
+  return `${identity.provider}::${identity.host.toLowerCase()}::${identity.owner.toLowerCase()}::${identity.repo.toLowerCase()}::${identity.number}`
+}
+
+function hasRequestedReviewerSignal(
+  summary: HostedReviewQueueSummary,
+  viewer?: HostedReviewUser | null
+): boolean {
+  if (!viewer?.login) {
+    return false
+  }
+  const requested = summary.requestedReviewerLogins
+  if (!requested || requested.length === 0) {
+    return false
+  }
+  const viewerLogin = viewer.login.toLowerCase()
+  return requested.some((login) => login.toLowerCase() === viewerLogin)
+}
+
+function isAgentAuthored(
+  summary: HostedReviewQueueSummary,
+  options?: HostedReviewClassificationOptions
+): boolean {
+  if (summary.author?.isBot) {
+    return true
+  }
+  const author = summary.author?.login?.toLowerCase()
+  if (!author) {
+    return false
+  }
+  if (options?.agentAuthorLogins?.some((login) => login.toLowerCase() === author)) {
+    return true
+  }
+  return author.endsWith('[bot]') || author.includes('bot')
+}
+
+function getQueueState(
+  summary: HostedReviewQueueSummary,
+  options?: HostedReviewClassificationOptions
+): HostedReviewQueueState {
+  const viewerLogin = options?.viewer?.login?.toLowerCase() ?? null
+  const authorLogin = summary.author?.login?.toLowerCase() ?? null
+  if (viewerLogin && authorLogin && viewerLogin === authorLogin) {
+    return 'mine'
+  }
+  if (hasRequestedReviewerSignal(summary, options?.viewer)) {
+    return 'requested'
+  }
+  if (isAgentAuthored(summary, options)) {
+    return 'agent'
+  }
+  return 'teammate'
+}
+
+export function reviewNeedsResponse(
+  summary: HostedReviewQueueSummary,
+  viewer?: HostedReviewUser | null
+): boolean {
+  void viewer
+  if (summary.state !== 'open' && summary.state !== 'draft') {
+    return false
+  }
+  if ((summary.threadSummary?.unresolvedCount ?? 0) > 0) {
+    return true
+  }
+  if (summary.checksStatus === 'failure') {
+    return true
+  }
+  if (summary.mergeable === 'CONFLICTING') {
+    return true
+  }
+  if (summary.lastViewedAt === undefined) {
+    return false
+  }
+  const updatedAt = Date.parse(summary.updatedAt)
+  return Number.isFinite(updatedAt) && updatedAt > summary.lastViewedAt
+}
+
+export function reviewReadyToMerge(summary: HostedReviewQueueSummary): boolean {
+  if (summary.state !== 'open') {
+    return false
+  }
+  if (summary.draft) {
+    return false
+  }
+  if (summary.mergeable !== 'MERGEABLE') {
+    return false
+  }
+  if (summary.checksStatus !== 'success' && summary.checksStatus !== 'neutral') {
+    return false
+  }
+  if (summary.threadSummary?.unresolvedCount !== 0) {
+    return false
+  }
+  return true
+}
+
+export function classifyHostedReview(
+  summary: HostedReviewQueueSummary,
+  options?: HostedReviewClassificationOptions
+): HostedReviewQueueClassification {
+  const state = getQueueState(summary, options)
+  return {
+    state,
+    requested: hasRequestedReviewerSignal(summary, options?.viewer),
+    needsResponse: reviewNeedsResponse(summary, options?.viewer),
+    readyToMerge: reviewReadyToMerge(summary)
+  }
+}
diff --git a/src/shared/hosted-review.ts b/src/shared/hosted-review.ts
index c26d6a0b14e..4ebd122c4b3 100644
--- a/src/shared/hosted-review.ts
+++ b/src/shared/hosted-review.ts
@@ -113,3 +113,56 @@ export type HostedReviewCreationEligibilityArgs = {
   linkedBitbucketPR?: number | null
   linkedGiteaPR?: number | null
 }
+
+export type HostedReviewIdentity = {
+  provider: HostedReviewProvider
+  host: string
+  owner: string
+  repo: string
+  number: number
+}
+
+export type HostedReviewUser = {
+  login: string | null
+  isBot?: boolean
+}
+
+export type HostedReviewDecision = 'approved' | 'changes_requested' | 'review_required' | null
+
+export type HostedReviewThreadSummary = {
+  unresolvedCount: number | null
+  dataCompleteness?: 'full' | 'partial'
+}
+
+export type HostedReviewQueueSummary = {
+  identity: HostedReviewIdentity
+  title: string
+  url: string
+  state: HostedReviewState
+  author: HostedReviewUser | null
+  updatedAt: string
+  lastViewedAt?: number
+  mergeable: PRMergeableState
+  checksStatus: CheckStatus
+  reviewDecision?: HostedReviewDecision
+  threadSummary?: HostedReviewThreadSummary
+  requestedReviewerLogins?: string[] | null
+  draft?: boolean
+}
+
+export type HostedReviewQueueKey =
+  | 'mine'
+  | 'requested'
+  | 'agent'
+  | 'teammate'
+  | 'needs-response'
+  | 'ready-to-merge'
+
+export type HostedReviewQueueState = 'mine' | 'requested' | 'agent' | 'teammate'
+
+export type HostedReviewQueueClassification = {
+  state: HostedReviewQueueState
+  needsResponse: boolean
+  readyToMerge: boolean
+  requested: boolean
+}

From e7f3bb6034740592fed9ab4967d0fe9b5e4ee45d Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 13:52:39 -0700
Subject: [PATCH 76/82] Add Grok agent support

---
 README.md                                     |   5 +-
 docs/README.es.md                             |   3 +-
 docs/README.ja.md                             |   1 +
 docs/README.ko.md                             |   3 +-
 docs/README.zh-CN.md                          |   1 +
 mobile/src/components/NewWorktreeModal.tsx    |   2 +
 .../remote-hook-service-installers.test.ts    |  29 +-
 src/main/grok/hook-service.test.ts            |  95 ++++++
 src/main/grok/hook-service.ts                 | 276 ++++++++++++++++++
 src/main/index.ts                             |   4 +-
 src/main/ipc/agent-hooks.test.ts              |   6 +
 src/main/ipc/agent-hooks.ts                   |  15 +
 src/preload/api-types.ts                      |   1 +
 src/preload/index.ts                          |   4 +-
 .../src/components/settings/agents-search.ts  |   1 +
 .../src/components/settings/general-search.ts |   3 +-
 .../sidebar/useWorktreeAgentRows.test.ts      |  39 ++-
 .../sidebar/useWorktreeAgentRows.ts           | 136 ++++++---
 src/renderer/src/lib/agent-catalog.tsx        |   7 +
 src/renderer/src/lib/agent-status.test.ts     |   1 +
 src/renderer/src/lib/agent-status.ts          |   6 +-
 .../src/lib/tui-agent-startup.test.ts         |  16 +
 src/renderer/src/web/web-preload-api.ts       |   5 +-
 src/shared/agent-detection.ts                 |   6 +-
 src/shared/agent-hook-listener.test.ts        |  70 +++++
 src/shared/agent-hook-listener.ts             | 184 +++++++++++-
 src/shared/agent-hook-relay.ts                |  10 +-
 src/shared/agent-hook-types.ts                |   2 +-
 src/shared/agent-kind.ts                      |   3 +-
 src/shared/agent-status-types.ts              |   1 +
 src/shared/telemetry-events.ts                |   1 +
 src/shared/tui-agent-config.ts                |   6 +
 src/shared/types.ts                           |   1 +
 33 files changed, 876 insertions(+), 67 deletions(-)
 create mode 100644 src/main/grok/hook-service.test.ts
 create mode 100644 src/main/grok/hook-service.ts

diff --git a/README.md b/README.md
index 5dfd755e0c2..ccd76d71fe0 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 
 <p align="center">
   <strong>The AI Orchestrator for 100x builders.</strong><br/>
-  Run Claude Code, Codex, or OpenCode side-by-side across repos — each in its own worktree, tracked in one place.<br/>
+  Run Claude Code, Codex, Grok, or OpenCode side-by-side across repos — each in its own worktree, tracked in one place.<br/>
   Available for <strong>macOS, Windows, and Linux</strong>.
 </p>
 
@@ -33,6 +33,7 @@ Orca supports any CLI agent (*not just this list*).
 <p>
   <a href="https://docs.anthropic.com/claude/docs/claude-code"><kbd><img src="docs/assets/claude-logo.svg" width="16" valign="middle" /> Claude Code</kbd></a> &nbsp;
   <a href="https://github.com/openai/codex"><kbd><img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" width="16" valign="middle" /> Codex</kbd></a> &nbsp;
+  <a href="https://x.ai/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=x.ai&sz=64" width="16" valign="middle" /> Grok</kbd></a> &nbsp;
   <a href="https://github.com/google-gemini/gemini-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=gemini.google.com&sz=64" width="16" valign="middle" /> Gemini</kbd></a> &nbsp;
   <a href="https://pi.dev"><kbd><img src="https://pi.dev/favicon.svg" width="16" valign="middle" /> Pi</kbd></a> &nbsp;
   <a href="https://hermes-agent.nousresearch.com/docs/"><kbd><img src="https://www.google.com/s2/favicons?domain=nousresearch.com&sz=64" width="16" valign="middle" /> Hermes Agent</kbd></a> &nbsp;
@@ -60,7 +61,7 @@ Orca supports any CLI agent (*not just this list*).
 
 ## Features
 
-- **No login required** — Bring your own Claude Code or Codex subscription.
+- **No login required** — Bring your own Claude Code, Codex, or Grok subscription.
 - **Worktree-native** — Every feature gets its own worktree. No stashing, no branch juggling. Spin up and switch instantly.
 - **Multi-agent terminals** — Run multiple AI agents side-by-side in tabs and panes. See which ones are active at a glance.
 - **Built-in source control** — Review AI-generated diffs, make quick edits, and commit without leaving Orca.
diff --git a/docs/README.es.md b/docs/README.es.md
index 1147e3b7bc8..4701a21fbcb 100644
--- a/docs/README.es.md
+++ b/docs/README.es.md
@@ -14,7 +14,7 @@
 
 <p align="center">
   <strong>El orquestador de IA para desarrolladores 100x.</strong><br/>
-  Ejecuta Claude Code, Codex u OpenCode en paralelo entre repositorios — cada uno en su propio worktree, todo administrado desde un solo lugar.<br/>
+  Ejecuta Claude Code, Codex, Grok u OpenCode en paralelo entre repositorios — cada uno en su propio worktree, todo administrado desde un solo lugar.<br/>
   Disponible para <strong>macOS, Windows y Linux</strong>.
 </p>
 
@@ -33,6 +33,7 @@ Orca es compatible con cualquier agente CLI (*no solo los de esta lista*).
 <p>
   <a href="https://docs.anthropic.com/claude/docs/claude-code"><kbd><img src="assets/claude-logo.svg" width="16" valign="middle" /> Claude Code</kbd></a> &nbsp;
   <a href="https://github.com/openai/codex"><kbd><img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" width="16" valign="middle" /> Codex</kbd></a> &nbsp;
+  <a href="https://x.ai/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=x.ai&sz=64" width="16" valign="middle" /> Grok</kbd></a> &nbsp;
   <a href="https://github.com/google-gemini/gemini-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=gemini.google.com&sz=64" width="16" valign="middle" /> Gemini</kbd></a> &nbsp;
   <a href="https://pi.dev"><kbd><img src="https://pi.dev/favicon.svg" width="16" valign="middle" /> Pi</kbd></a> &nbsp;
   <a href="https://hermes-agent.nousresearch.com/docs/"><kbd><img src="https://www.google.com/s2/favicons?domain=nousresearch.com&sz=64" width="16" valign="middle" /> Hermes Agent</kbd></a> &nbsp;
diff --git a/docs/README.ja.md b/docs/README.ja.md
index 35f688e949b..bd7dcd3dc30 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -33,6 +33,7 @@ Orca は任意の CLI エージェントに対応しています（*このリス
 <p>
   <a href="https://docs.anthropic.com/claude/docs/claude-code"><kbd><img src="assets/claude-logo.svg" width="16" valign="middle" /> Claude Code</kbd></a> &nbsp;
   <a href="https://github.com/openai/codex"><kbd><img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" width="16" valign="middle" /> Codex</kbd></a> &nbsp;
+  <a href="https://x.ai/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=x.ai&sz=64" width="16" valign="middle" /> Grok</kbd></a> &nbsp;
   <a href="https://github.com/google-gemini/gemini-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=gemini.google.com&sz=64" width="16" valign="middle" /> Gemini</kbd></a> &nbsp;
   <a href="https://pi.dev"><kbd><img src="https://pi.dev/favicon.svg" width="16" valign="middle" /> Pi</kbd></a> &nbsp;
   <a href="https://hermes-agent.nousresearch.com/docs/"><kbd><img src="https://www.google.com/s2/favicons?domain=nousresearch.com&sz=64" width="16" valign="middle" /> Hermes Agent</kbd></a> &nbsp;
diff --git a/docs/README.ko.md b/docs/README.ko.md
index 42fabf357ed..070f1666579 100644
--- a/docs/README.ko.md
+++ b/docs/README.ko.md
@@ -14,7 +14,7 @@
 
 <p align="center">
   <strong>100x 빌더를 위한 AI 오케스트레이터.</strong><br/>
-  Claude Code, Codex, OpenCode를 여러 리포지토리에서 나란히 실행하세요. 각 에이전트는 자체 worktree에서 실행되고 한곳에서 추적됩니다.<br/>
+  Claude Code, Codex, Grok, OpenCode를 여러 리포지토리에서 나란히 실행하세요. 각 에이전트는 자체 worktree에서 실행되고 한곳에서 추적됩니다.<br/>
   <strong>macOS, Windows, Linux</strong>에서 사용할 수 있습니다.
 </p>
 
@@ -33,6 +33,7 @@ Orca는 모든 CLI 에이전트를 지원합니다(*아래 목록에만 한정
 <p>
   <a href="https://docs.anthropic.com/claude/docs/claude-code"><kbd><img src="assets/claude-logo.svg" width="16" valign="middle" /> Claude Code</kbd></a> &nbsp;
   <a href="https://github.com/openai/codex"><kbd><img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" width="16" valign="middle" /> Codex</kbd></a> &nbsp;
+  <a href="https://x.ai/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=x.ai&sz=64" width="16" valign="middle" /> Grok</kbd></a> &nbsp;
   <a href="https://github.com/google-gemini/gemini-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=gemini.google.com&sz=64" width="16" valign="middle" /> Gemini</kbd></a> &nbsp;
   <a href="https://pi.dev"><kbd><img src="https://pi.dev/favicon.svg" width="16" valign="middle" /> Pi</kbd></a> &nbsp;
   <a href="https://hermes-agent.nousresearch.com/docs/"><kbd><img src="https://www.google.com/s2/favicons?domain=nousresearch.com&sz=64" width="16" valign="middle" /> Hermes Agent</kbd></a> &nbsp;
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 855471739c8..aaa651d7917 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -33,6 +33,7 @@ Orca 支持任何 CLI 智能体（*不仅限于以下列表*）。
 <p>
   <a href="https://docs.anthropic.com/claude/docs/claude-code"><kbd><img src="assets/claude-logo.svg" width="16" valign="middle" /> Claude Code</kbd></a> &nbsp;
   <a href="https://github.com/openai/codex"><kbd><img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" width="16" valign="middle" /> Codex</kbd></a> &nbsp;
+  <a href="https://x.ai/cli"><kbd><img src="https://www.google.com/s2/favicons?domain=x.ai&sz=64" width="16" valign="middle" /> Grok</kbd></a> &nbsp;
   <a href="https://github.com/google-gemini/gemini-cli"><kbd><img src="https://www.google.com/s2/favicons?domain=gemini.google.com&sz=64" width="16" valign="middle" /> Gemini</kbd></a> &nbsp;
   <a href="https://pi.dev"><kbd><img src="https://pi.dev/favicon.svg" width="16" valign="middle" /> Pi</kbd></a> &nbsp;
   <a href="https://hermes-agent.nousresearch.com/docs/"><kbd><img src="https://www.google.com/s2/favicons?domain=nousresearch.com&sz=64" width="16" valign="middle" /> Hermes Agent</kbd></a> &nbsp;
diff --git a/mobile/src/components/NewWorktreeModal.tsx b/mobile/src/components/NewWorktreeModal.tsx
index a7e7d2579b3..20f74e7d643 100644
--- a/mobile/src/components/NewWorktreeModal.tsx
+++ b/mobile/src/components/NewWorktreeModal.tsx
@@ -36,6 +36,7 @@ type AgentOption = {
 const AGENT_OPTIONS: AgentOption[] = [
   { id: 'claude', label: 'Claude' },
   { id: 'codex', label: 'Codex' },
+  { id: 'grok', label: 'Grok', faviconDomain: 'x.ai' },
   { id: 'copilot', label: 'GitHub Copilot', faviconDomain: 'github.com' },
   { id: 'opencode', label: 'OpenCode', faviconDomain: 'opencode.ai' },
   { id: 'pi', label: 'Pi' },
@@ -67,6 +68,7 @@ const ALL_AGENTS = [...AGENT_OPTIONS, BLANK_TERMINAL]
 const AGENT_COMMANDS: Record<string, string> = {
   claude: 'claude',
   codex: 'codex',
+  grok: 'grok',
   copilot: 'copilot',
   opencode: 'opencode',
   pi: 'pi',
diff --git a/src/main/agent-hooks/remote-hook-service-installers.test.ts b/src/main/agent-hooks/remote-hook-service-installers.test.ts
index 95db6b6ba95..f273a47c815 100644
--- a/src/main/agent-hooks/remote-hook-service-installers.test.ts
+++ b/src/main/agent-hooks/remote-hook-service-installers.test.ts
@@ -11,6 +11,7 @@ import { CodexHookService } from '../codex/hook-service'
 import { CursorHookService } from '../cursor/hook-service'
 import { GeminiHookService } from '../gemini/hook-service'
 import { ClaudeHookService } from '../claude/hook-service'
+import { GrokHookService } from '../grok/hook-service'
 
 type FakeFs = {
   files: Map<string, string>
@@ -124,6 +125,10 @@ describe('remote hook service installers', () => {
         {
           path: '/home/dev/.orca/agent-hooks/cursor-hook.sh',
           install: (sftp: SFTPWrapper) => new CursorHookService().installRemote(sftp, '/home/dev')
+        },
+        {
+          path: '/home/dev/.orca/agent-hooks/grok-hook.sh',
+          install: (sftp: SFTPWrapper) => new GrokHookService().installRemote(sftp, '/home/dev')
         }
       ]
 
@@ -185,12 +190,14 @@ describe('remote hook service installers', () => {
     expect(fs.files.get('/home/dev/.orca/agent-hooks/codex-hook.sh')).toContain('#!/bin/sh')
   })
 
-  it('installs remote Gemini and Cursor configs using their CLI-specific schemas', async () => {
+  it('installs remote Gemini, Cursor, and Grok configs using their CLI-specific schemas', async () => {
     const gemini = createFakeSftp()
     const cursor = createFakeSftp()
+    const grok = createFakeSftp()
 
     await new GeminiHookService().installRemote(gemini.sftp, '/home/dev')
     await new CursorHookService().installRemote(cursor.sftp, '/home/dev')
+    await new GrokHookService().installRemote(grok.sftp, '/home/dev')
 
     const geminiConfig = JSON.parse(gemini.fs.files.get('/home/dev/.gemini/settings.json')!) as {
       hooks: Record<string, { hooks: { command: string }[] }[]>
@@ -220,5 +227,25 @@ describe('remote hook service installers', () => {
       expect(definition?.command).toContain('/home/dev/.orca/agent-hooks/cursor-hook.sh')
       expect(definition?.hooks).toBeUndefined()
     }
+
+    const grokConfig = JSON.parse(grok.fs.files.get('/home/dev/.grok/hooks/orca-status.json')!) as {
+      hooks: Record<string, { matcher?: string; hooks?: { command: string }[] }[]>
+    }
+    for (const eventName of [
+      'SessionStart',
+      'UserPromptSubmit',
+      'Stop',
+      'SessionEnd',
+      'PreToolUse',
+      'PostToolUse',
+      'PostToolUseFailure',
+      'Notification'
+    ]) {
+      const definition = grokConfig.hooks[eventName]?.[0]
+      const command = definition?.hooks?.[0]?.command
+      expect(command).toContain('/home/dev/.orca/agent-hooks/grok-hook.sh')
+      expect(command).toMatch(/^if \[ -x /)
+    }
+    expect(grokConfig.hooks.PreToolUse?.[0]?.matcher).toBe('*')
   })
 })
diff --git a/src/main/grok/hook-service.test.ts b/src/main/grok/hook-service.test.ts
new file mode 100644
index 00000000000..b64c70d7be1
--- /dev/null
+++ b/src/main/grok/hook-service.test.ts
@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join } from 'path'
+
+const { homedirMock } = vi.hoisted(() => ({
+  homedirMock: vi.fn<() => string>()
+}))
+
+vi.mock('os', async () => {
+  const actual = (await vi.importActual('os')) as Record<string, unknown>
+  return {
+    ...actual,
+    homedir: homedirMock
+  }
+})
+
+import { GrokHookService } from './hook-service'
+
+describe('GrokHookService', () => {
+  let homeDir: string
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), 'orca-grok-home-'))
+    homedirMock.mockReturnValue(homeDir)
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+    rmSync(homeDir, { recursive: true, force: true })
+  })
+
+  it('installs a dedicated global Grok hook config and managed script', () => {
+    const status = new GrokHookService().install()
+
+    expect(status.state).toBe('installed')
+    expect(status.configPath).toBe(join(homeDir, '.grok', 'hooks', 'orca-status.json'))
+    expect(status.managedHooksPresent).toBe(true)
+
+    const config = JSON.parse(
+      readFileSync(join(homeDir, '.grok', 'hooks', 'orca-status.json'), 'utf8')
+    ) as {
+      hooks: Record<string, { matcher?: string; hooks: { command: string }[] }[]>
+    }
+    expect(Object.keys(config.hooks).sort()).toEqual(
+      [
+        'Notification',
+        'PostToolUse',
+        'PostToolUseFailure',
+        'PreToolUse',
+        'SessionEnd',
+        'SessionStart',
+        'Stop',
+        'UserPromptSubmit'
+      ].sort()
+    )
+    expect(config.hooks.PreToolUse[0].matcher).toBe('*')
+    expect(config.hooks.PostToolUseFailure[0].matcher).toBe('*')
+    expect(config.hooks.Notification[0].matcher).toBeUndefined()
+    expect(config.hooks.PreToolUse[0].hooks[0].command).toContain('grok-hook')
+    expect(config.hooks.PreToolUse[0].hooks[0].command).toContain(join(homeDir, '.orca'))
+
+    const script = readFileSync(join(homeDir, '.orca', 'agent-hooks', 'grok-hook.sh'), 'utf8')
+    expect(script).toContain('/hook/grok')
+    expect(script).toContain('payload=$(cat)')
+  })
+
+  it('preserves user-authored hook entries in the Orca Grok config file', () => {
+    const configPath = join(homeDir, '.grok', 'hooks', 'orca-status.json')
+    mkdirSync(dirname(configPath), { recursive: true })
+    writeFileSync(
+      configPath,
+      `${JSON.stringify(
+        {
+          hooks: {
+            Notification: [{ hooks: [{ type: 'command', command: '/usr/local/bin/user-hook' }] }]
+          }
+        },
+        null,
+        2
+      )}\n`
+    )
+
+    new GrokHookService().install()
+
+    const config = JSON.parse(readFileSync(configPath, 'utf8')) as {
+      hooks: Record<string, { hooks: { command: string }[] }[]>
+    }
+    const commands = config.hooks.Notification.flatMap((definition) =>
+      definition.hooks.map((hook) => hook.command)
+    )
+    expect(commands).toContain('/usr/local/bin/user-hook')
+    expect(commands.some((command) => command.includes('grok-hook.sh'))).toBe(true)
+  })
+})
diff --git a/src/main/grok/hook-service.ts b/src/main/grok/hook-service.ts
new file mode 100644
index 00000000000..0ffc12abbec
--- /dev/null
+++ b/src/main/grok/hook-service.ts
@@ -0,0 +1,276 @@
+import { homedir } from 'os'
+import { join } from 'path'
+import type { SFTPWrapper } from 'ssh2'
+import type { AgentHookInstallState, AgentHookInstallStatus } from '../../shared/agent-hook-types'
+import {
+  createManagedCommandMatcher,
+  getSharedManagedScriptPath,
+  readHooksJson,
+  removeManagedCommands,
+  wrapPosixHookCommand,
+  writeHooksJson,
+  writeManagedScript,
+  type HookDefinition
+} from '../agent-hooks/installer-utils'
+import {
+  readHooksJsonRemote,
+  writeHooksJsonRemote,
+  writeManagedScriptRemote
+} from '../agent-hooks/installer-utils-remote'
+
+const GROK_EVENTS = [
+  { eventName: 'SessionStart', definition: { hooks: [{ type: 'command', command: '' }] } },
+  { eventName: 'UserPromptSubmit', definition: { hooks: [{ type: 'command', command: '' }] } },
+  { eventName: 'Stop', definition: { hooks: [{ type: 'command', command: '' }] } },
+  { eventName: 'SessionEnd', definition: { hooks: [{ type: 'command', command: '' }] } },
+  {
+    eventName: 'PreToolUse',
+    definition: { matcher: '*', hooks: [{ type: 'command', command: '' }] }
+  },
+  {
+    eventName: 'PostToolUse',
+    definition: { matcher: '*', hooks: [{ type: 'command', command: '' }] }
+  },
+  {
+    eventName: 'PostToolUseFailure',
+    definition: { matcher: '*', hooks: [{ type: 'command', command: '' }] }
+  },
+  { eventName: 'Notification', definition: { hooks: [{ type: 'command', command: '' }] } }
+] as const
+
+function getConfigPath(): string {
+  // Why: Grok loads trusted global hook files from ~/.grok/hooks/*.json. Keep
+  // Orca's managed entries in a dedicated file so user-authored hook files stay
+  // untouched and project-level trust is not required for status reporting.
+  return join(homedir(), '.grok', 'hooks', 'orca-status.json')
+}
+
+function getManagedScriptFileName(): string {
+  return process.platform === 'win32' ? 'grok-hook.cmd' : 'grok-hook.sh'
+}
+
+function getManagedScriptPath(): string {
+  return getSharedManagedScriptPath(getManagedScriptFileName())
+}
+
+function getManagedCommand(scriptPath: string): string {
+  return process.platform === 'win32' ? scriptPath : wrapPosixHookCommand(scriptPath)
+}
+
+function getManagedScript(target: 'local' | 'posix' = 'local'): string {
+  if (target === 'local' && process.platform === 'win32') {
+    return [
+      '@echo off',
+      'setlocal',
+      'if defined ORCA_AGENT_HOOK_ENDPOINT if exist "%ORCA_AGENT_HOOK_ENDPOINT%" call "%ORCA_AGENT_HOOK_ENDPOINT%" 2>nul',
+      'if "%ORCA_AGENT_HOOK_PORT%"=="" exit /b 0',
+      'if "%ORCA_AGENT_HOOK_TOKEN%"=="" exit /b 0',
+      'if "%ORCA_PANE_KEY%"=="" exit /b 0',
+      `powershell -NoProfile -ExecutionPolicy Bypass -Command "$inputData=[Console]::In.ReadToEnd(); if ([string]::IsNullOrWhiteSpace($inputData)) { exit 0 }; try { $body=@{ paneKey=$env:ORCA_PANE_KEY; tabId=$env:ORCA_TAB_ID; worktreeId=$env:ORCA_WORKTREE_ID; env=$env:ORCA_AGENT_HOOK_ENV; version=$env:ORCA_AGENT_HOOK_VERSION; payload=($inputData | ConvertFrom-Json) } | ConvertTo-Json -Depth 100; Invoke-WebRequest -UseBasicParsing -Method Post -Uri ('http://127.0.0.1:' + $env:ORCA_AGENT_HOOK_PORT + '/hook/grok') -Headers @{ 'Content-Type'='application/json'; 'X-Orca-Agent-Hook-Token'=$env:ORCA_AGENT_HOOK_TOKEN } -Body $body | Out-Null } catch {}"`,
+      'exit /b 0',
+      ''
+    ].join('\r\n')
+  }
+
+  return [
+    '#!/bin/sh',
+    'if [ -n "$ORCA_AGENT_HOOK_ENDPOINT" ] && [ -r "$ORCA_AGENT_HOOK_ENDPOINT" ]; then',
+    '  . "$ORCA_AGENT_HOOK_ENDPOINT" 2>/dev/null || :',
+    'fi',
+    'if [ -z "$ORCA_AGENT_HOOK_PORT" ] || [ -z "$ORCA_AGENT_HOOK_TOKEN" ] || [ -z "$ORCA_PANE_KEY" ]; then',
+    '  exit 0',
+    'fi',
+    'payload=$(cat)',
+    'if [ -z "$payload" ]; then',
+    '  exit 0',
+    'fi',
+    'curl -sS -X POST "http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/grok" \\',
+    '  -H "Content-Type: application/x-www-form-urlencoded" \\',
+    '  -H "X-Orca-Agent-Hook-Token: ${ORCA_AGENT_HOOK_TOKEN}" \\',
+    '  --data-urlencode "paneKey=${ORCA_PANE_KEY}" \\',
+    '  --data-urlencode "tabId=${ORCA_TAB_ID}" \\',
+    '  --data-urlencode "worktreeId=${ORCA_WORKTREE_ID}" \\',
+    '  --data-urlencode "env=${ORCA_AGENT_HOOK_ENV}" \\',
+    '  --data-urlencode "version=${ORCA_AGENT_HOOK_VERSION}" \\',
+    '  --data-urlencode "payload=${payload}" >/dev/null 2>&1 || true',
+    'exit 0',
+    ''
+  ].join('\n')
+}
+
+function buildInstalledConfig(
+  config: NonNullable<ReturnType<typeof readHooksJson>>,
+  command: string,
+  scriptFileName: string
+): void {
+  const nextHooks = { ...config.hooks }
+  const isManagedCommand = createManagedCommandMatcher(scriptFileName)
+  const managedEvents = new Set<string>(GROK_EVENTS.map((event) => event.eventName))
+
+  // Why: Orca owns only grok-hook.* entries. Sweep stale managed commands out
+  // of retired events while preserving any user-authored hooks in this file.
+  for (const [eventName, definitions] of Object.entries(nextHooks)) {
+    if (managedEvents.has(eventName) || !Array.isArray(definitions)) {
+      continue
+    }
+    const cleaned = removeManagedCommands(definitions, isManagedCommand)
+    if (cleaned.length === 0) {
+      delete nextHooks[eventName]
+    } else {
+      nextHooks[eventName] = cleaned
+    }
+  }
+
+  for (const event of GROK_EVENTS) {
+    const current = Array.isArray(nextHooks[event.eventName]) ? nextHooks[event.eventName] : []
+    const cleaned = removeManagedCommands(current, isManagedCommand)
+    const definition: HookDefinition = {
+      ...event.definition,
+      hooks: [{ type: 'command', command }]
+    }
+    nextHooks[event.eventName] = [...cleaned, definition]
+  }
+
+  config.hooks = nextHooks
+}
+
+export class GrokHookService {
+  getStatus(): AgentHookInstallStatus {
+    const configPath = getConfigPath()
+    const scriptPath = getManagedScriptPath()
+    const config = readHooksJson(configPath)
+    if (!config) {
+      return {
+        agent: 'grok',
+        state: 'error',
+        configPath,
+        managedHooksPresent: false,
+        detail: 'Could not parse Grok hook config'
+      }
+    }
+
+    const command = getManagedCommand(scriptPath)
+    const missing: string[] = []
+    let presentCount = 0
+    for (const event of GROK_EVENTS) {
+      const definitions = Array.isArray(config.hooks?.[event.eventName])
+        ? config.hooks![event.eventName]!
+        : []
+      const hasCommand = definitions.some((definition) =>
+        (definition.hooks ?? []).some((hook) => hook.command === command)
+      )
+      if (hasCommand) {
+        presentCount += 1
+      } else {
+        missing.push(event.eventName)
+      }
+    }
+
+    const managedHooksPresent = presentCount > 0
+    let state: AgentHookInstallState
+    let detail: string | null
+    if (missing.length === 0) {
+      state = 'installed'
+      detail = null
+    } else if (presentCount === 0) {
+      state = 'not_installed'
+      detail = null
+    } else {
+      state = 'partial'
+      detail = `Managed hook missing for events: ${missing.join(', ')}`
+    }
+    return { agent: 'grok', state, configPath, managedHooksPresent, detail }
+  }
+
+  install(): AgentHookInstallStatus {
+    const configPath = getConfigPath()
+    const scriptPath = getManagedScriptPath()
+    const config = readHooksJson(configPath)
+    if (!config) {
+      return {
+        agent: 'grok',
+        state: 'error',
+        configPath,
+        managedHooksPresent: false,
+        detail: 'Could not parse Grok hook config'
+      }
+    }
+
+    buildInstalledConfig(config, getManagedCommand(scriptPath), getManagedScriptFileName())
+    writeManagedScript(scriptPath, getManagedScript())
+    writeHooksJson(configPath, config)
+    return this.getStatus()
+  }
+
+  async installRemote(sftp: SFTPWrapper, remoteHome: string): Promise<AgentHookInstallStatus> {
+    const home = remoteHome.replace(/\/$/, '')
+    const remoteConfigPath = `${home}/.grok/hooks/orca-status.json`
+    const remoteScriptPath = `${home}/.orca/agent-hooks/grok-hook.sh`
+    try {
+      const config = await readHooksJsonRemote(sftp, remoteConfigPath)
+      if (!config) {
+        return {
+          agent: 'grok',
+          state: 'error',
+          configPath: remoteConfigPath,
+          managedHooksPresent: false,
+          detail: 'Could not parse remote Grok hook config'
+        }
+      }
+
+      buildInstalledConfig(config, wrapPosixHookCommand(remoteScriptPath), 'grok-hook.sh')
+      await writeManagedScriptRemote(sftp, remoteScriptPath, getManagedScript('posix'))
+      await writeHooksJsonRemote(sftp, remoteConfigPath, config)
+
+      return {
+        agent: 'grok',
+        state: 'installed',
+        configPath: remoteConfigPath,
+        managedHooksPresent: true,
+        detail: null
+      }
+    } catch (err) {
+      return {
+        agent: 'grok',
+        state: 'error',
+        configPath: remoteConfigPath,
+        managedHooksPresent: false,
+        detail: err instanceof Error ? err.message : String(err)
+      }
+    }
+  }
+
+  remove(): AgentHookInstallStatus {
+    const configPath = getConfigPath()
+    const config = readHooksJson(configPath)
+    if (!config) {
+      return {
+        agent: 'grok',
+        state: 'error',
+        configPath,
+        managedHooksPresent: false,
+        detail: 'Could not parse Grok hook config'
+      }
+    }
+
+    const nextHooks = { ...config.hooks }
+    const isManagedCommand = createManagedCommandMatcher(getManagedScriptFileName())
+    for (const [eventName, definitions] of Object.entries(nextHooks)) {
+      if (!Array.isArray(definitions)) {
+        continue
+      }
+      const cleaned = removeManagedCommands(definitions, isManagedCommand)
+      if (cleaned.length === 0) {
+        delete nextHooks[eventName]
+      } else {
+        nextHooks[eventName] = cleaned
+      }
+    }
+
+    config.hooks = nextHooks
+    writeHooksJson(configPath, config)
+    return this.getStatus()
+  }
+}
+
+export const grokHookService = new GrokHookService()
diff --git a/src/main/index.ts b/src/main/index.ts
index e87525574d9..af7af86db47 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -55,6 +55,7 @@ import { codexHookService } from './codex/hook-service'
 import { geminiHookService } from './gemini/hook-service'
 import { cursorHookService } from './cursor/hook-service'
 import { droidHookService } from './droid/hook-service'
+import { grokHookService } from './grok/hook-service'
 import {
   getPtyIdForPaneKey,
   registerPaneKeyTeardownListener,
@@ -712,7 +713,8 @@ app.whenReady().then(async () => {
     ['codex', () => codexHookService.install()],
     ['gemini', () => geminiHookService.install()],
     ['cursor', () => cursorHookService.install()],
-    ['droid', () => droidHookService.install()]
+    ['droid', () => droidHookService.install()],
+    ['grok', () => grokHookService.install()]
   ])
 
   registerAppMenu({
diff --git a/src/main/ipc/agent-hooks.test.ts b/src/main/ipc/agent-hooks.test.ts
index f82ade795e1..75e76a74f7c 100644
--- a/src/main/ipc/agent-hooks.test.ts
+++ b/src/main/ipc/agent-hooks.test.ts
@@ -53,6 +53,12 @@ vi.mock('../gemini/hook-service', () => ({
 vi.mock('../cursor/hook-service', () => ({
   cursorHookService: { getStatus: vi.fn(() => ({ agent: 'cursor', state: 'absent' })) }
 }))
+vi.mock('../droid/hook-service', () => ({
+  droidHookService: { getStatus: vi.fn(() => ({ agent: 'droid', state: 'absent' })) }
+}))
+vi.mock('../grok/hook-service', () => ({
+  grokHookService: { getStatus: vi.fn(() => ({ agent: 'grok', state: 'absent' })) }
+}))
 
 beforeEach(() => {
   dropStatusEntry.mockReset()
diff --git a/src/main/ipc/agent-hooks.ts b/src/main/ipc/agent-hooks.ts
index 350c1c9200e..2ecb426feab 100644
--- a/src/main/ipc/agent-hooks.ts
+++ b/src/main/ipc/agent-hooks.ts
@@ -14,6 +14,7 @@ import { codexHookService } from '../codex/hook-service'
 import { geminiHookService } from '../gemini/hook-service'
 import { cursorHookService } from '../cursor/hook-service'
 import { droidHookService } from '../droid/hook-service'
+import { grokHookService } from '../grok/hook-service'
 
 // Why: install/remove are intentionally not exposed to the renderer. Orca
 // auto-installs managed hooks at app startup (see src/main/index.ts), so a
@@ -31,6 +32,7 @@ export function registerAgentHookHandlers(): void {
   ipcMain.removeHandler('agentHooks:geminiStatus')
   ipcMain.removeHandler('agentHooks:cursorStatus')
   ipcMain.removeHandler('agentHooks:droidStatus')
+  ipcMain.removeHandler('agentHooks:grokStatus')
   ipcMain.removeHandler('agentStatus:getSnapshot')
   ipcMain.removeHandler('agentStatus:getMigrationUnsupportedSnapshot')
   // Why: agentStatus:drop is sent fire-and-forget from the renderer via
@@ -133,4 +135,17 @@ export function registerAgentHookHandlers(): void {
       }
     }
   })
+  ipcMain.handle('agentHooks:grokStatus', (): AgentHookInstallStatus => {
+    try {
+      return grokHookService.getStatus()
+    } catch (err) {
+      return {
+        agent: 'grok',
+        state: 'error',
+        configPath: '',
+        managedHooksPresent: false,
+        detail: err instanceof Error ? err.message : String(err)
+      }
+    }
+  })
 }
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index ab03644b477..828d0be1c44 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -1021,6 +1021,7 @@ export type PreloadApi = {
     geminiStatus: () => Promise<AgentHookInstallStatus>
     cursorStatus: () => Promise<AgentHookInstallStatus>
     droidStatus: () => Promise<AgentHookInstallStatus>
+    grokStatus: () => Promise<AgentHookInstallStatus>
   }
   agentTrust: {
     markTrusted: (args: { preset: 'cursor' | 'copilot'; workspacePath: string }) => Promise<void>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 314d84a134c..a45f433e6ee 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -1092,7 +1092,9 @@ const api = {
       ipcRenderer.invoke('agentHooks:geminiStatus'),
     cursorStatus: (): Promise<AgentHookInstallStatus> =>
       ipcRenderer.invoke('agentHooks:cursorStatus'),
-    droidStatus: (): Promise<AgentHookInstallStatus> => ipcRenderer.invoke('agentHooks:droidStatus')
+    droidStatus: (): Promise<AgentHookInstallStatus> =>
+      ipcRenderer.invoke('agentHooks:droidStatus'),
+    grokStatus: (): Promise<AgentHookInstallStatus> => ipcRenderer.invoke('agentHooks:grokStatus')
   },
 
   agentTrust: {
diff --git a/src/renderer/src/components/settings/agents-search.ts b/src/renderer/src/components/settings/agents-search.ts
index 3d384e529c1..319f780f8a8 100644
--- a/src/renderer/src/components/settings/agents-search.ts
+++ b/src/renderer/src/components/settings/agents-search.ts
@@ -31,6 +31,7 @@ export const AGENTS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
       'hermes',
       'openclaw',
       'copilot',
+      'grok',
       'github',
       'github copilot',
       'command',
diff --git a/src/renderer/src/components/settings/general-search.ts b/src/renderer/src/components/settings/general-search.ts
index 26417f4d74a..254b63336bf 100644
--- a/src/renderer/src/components/settings/general-search.ts
+++ b/src/renderer/src/components/settings/general-search.ts
@@ -93,7 +93,8 @@ export const GENERAL_AGENT_SEARCH_ENTRIES: SettingsSearchEntry[] = [
       'pi',
       'gemini',
       'aider',
-      'copilot'
+      'copilot',
+      'grok'
     ]
   }
 ]
diff --git a/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts b/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts
index 986e96d1f1d..a9827e3d217 100644
--- a/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts
+++ b/src/renderer/src/components/sidebar/useWorktreeAgentRows.test.ts
@@ -1,11 +1,15 @@
 import { describe, expect, it } from 'vitest'
 import {
   AGENT_STATUS_STALE_AFTER_MS,
-  type AgentStatusEntry
+  type AgentStatusEntry,
+  type MigrationUnsupportedPtyEntry
 } from '../../../../shared/agent-status-types'
 import type { TerminalTab } from '../../../../shared/types'
 import type { RetainedAgentEntry } from '@/store/slices/agent-status'
-import { buildWorktreeAgentRows } from './useWorktreeAgentRows'
+import {
+  buildWorktreeAgentRows,
+  selectMigrationUnsupportedEntriesForWorktree
+} from './useWorktreeAgentRows'
 import { makePaneKey } from '../../../../shared/stable-pane-id'
 
 const ORPHAN_PANE_KEY = makePaneKey('tab-orphan', '11111111-1111-4111-8111-111111111111')
@@ -108,3 +112,34 @@ describe('buildWorktreeAgentRows', () => {
     expect(done?.state).toBe('done')
   })
 })
+
+describe('selectMigrationUnsupportedEntriesForWorktree', () => {
+  it('returns raw migration records so shallow selectors can cache snapshots', () => {
+    const unsupported: MigrationUnsupportedPtyEntry = {
+      ptyId: 'pty-1',
+      worktreeId: 'wt-1',
+      tabId: 'tab-1',
+      leafId: '44444444-4444-4444-8444-444444444444',
+      paneKey: makePaneKey('tab-1', '44444444-4444-4444-8444-444444444444'),
+      reason: 'legacy-numeric-pane-key',
+      source: 'local',
+      updatedAt: 1000
+    }
+    const state = {
+      tabsByWorktree: { 'wt-1': [makeTab('tab-1')] },
+      agentStatusByPaneKey: {},
+      migrationUnsupportedByPtyId: { 'pty-1': unsupported },
+      retainedAgentsByPaneKey: {}
+    }
+
+    const first = selectMigrationUnsupportedEntriesForWorktree(state, 'wt-1')
+    const second = selectMigrationUnsupportedEntriesForWorktree(state, 'wt-1')
+
+    // Why: the Electron black-screen regression came from creating converted
+    // AgentStatusEntry objects inside the Zustand selector. Returning store
+    // records preserves element identity for useShallow.
+    expect(first).toEqual([unsupported])
+    expect(second).toEqual([unsupported])
+    expect(first[0]).toBe(second[0])
+  })
+})
diff --git a/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts b/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
index d0286bbeb20..196e6a116ca 100644
--- a/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
+++ b/src/renderer/src/components/sidebar/useWorktreeAgentRows.ts
@@ -4,10 +4,12 @@ import { useAppStore } from '@/store'
 import type { DashboardAgentRow } from '@/components/dashboard/useDashboardData'
 import { isExplicitAgentStatusFresh } from '@/lib/agent-status'
 import type { RetainedAgentEntry } from '@/store/slices/agent-status'
+import type { AppState } from '@/store/types'
 import type { TerminalTab } from '../../../../shared/types'
 import {
   AGENT_STATUS_STALE_AFTER_MS,
-  type AgentStatusEntry
+  type AgentStatusEntry,
+  type MigrationUnsupportedPtyEntry
 } from '../../../../shared/agent-status-types'
 import { parsePaneKey } from '../../../../shared/stable-pane-id'
 import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
@@ -18,8 +20,76 @@ import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsuppor
 // unnecessary re-renders — defeating the purpose of the narrow selector.
 const EMPTY_TABS: TerminalTab[] = []
 const EMPTY_LIVE_ENTRIES: AgentStatusEntry[] = []
+const EMPTY_MIGRATION_UNSUPPORTED_ENTRIES: MigrationUnsupportedPtyEntry[] = []
 const EMPTY_RETAINED: RetainedAgentEntry[] = []
 
+type WorktreeAgentRowsState = Pick<
+  AppState,
+  | 'agentStatusByPaneKey'
+  | 'migrationUnsupportedByPtyId'
+  | 'retainedAgentsByPaneKey'
+  | 'tabsByWorktree'
+>
+
+export function selectLiveAgentStatusEntriesForWorktree(
+  state: WorktreeAgentRowsState,
+  worktreeId: string
+): AgentStatusEntry[] {
+  const wtTabs = state.tabsByWorktree[worktreeId] ?? EMPTY_TABS
+  if (wtTabs.length === 0) {
+    return EMPTY_LIVE_ENTRIES
+  }
+  const tabIds = new Set(wtTabs.map((t) => t.id))
+  const out: AgentStatusEntry[] = []
+  for (const [paneKey, entry] of Object.entries(state.agentStatusByPaneKey)) {
+    const parsed = parsePaneKey(paneKey)
+    if (!parsed) {
+      continue
+    }
+    if (!tabIds.has(parsed.tabId)) {
+      continue
+    }
+    out.push(entry)
+  }
+  return out.length > 0 ? out : EMPTY_LIVE_ENTRIES
+}
+
+export function selectMigrationUnsupportedEntriesForWorktree(
+  state: WorktreeAgentRowsState,
+  worktreeId: string
+): MigrationUnsupportedPtyEntry[] {
+  const wtTabs = state.tabsByWorktree[worktreeId] ?? EMPTY_TABS
+  if (wtTabs.length === 0) {
+    return EMPTY_MIGRATION_UNSUPPORTED_ENTRIES
+  }
+  const tabIds = new Set(wtTabs.map((t) => t.id))
+  const out: MigrationUnsupportedPtyEntry[] = []
+  for (const unsupported of Object.values(state.migrationUnsupportedByPtyId)) {
+    if (!unsupported.paneKey) {
+      continue
+    }
+    const parsed = parsePaneKey(unsupported.paneKey)
+    if (!parsed || !tabIds.has(parsed.tabId)) {
+      continue
+    }
+    out.push(unsupported)
+  }
+  return out.length > 0 ? out : EMPTY_MIGRATION_UNSUPPORTED_ENTRIES
+}
+
+export function selectRetainedAgentEntriesForWorktree(
+  state: WorktreeAgentRowsState,
+  worktreeId: string
+): RetainedAgentEntry[] {
+  const out: RetainedAgentEntry[] = []
+  for (const ra of Object.values(state.retainedAgentsByPaneKey)) {
+    if (ra.worktreeId === worktreeId) {
+      out.push(ra)
+    }
+  }
+  return out.length > 0 ? out : EMPTY_RETAINED
+}
+
 export function buildWorktreeAgentRows(args: {
   tabs: TerminalTab[]
   entries: AgentStatusEntry[]
@@ -97,48 +167,17 @@ export function useWorktreeAgentRows(worktreeId: string): DashboardAgentRow[] {
   // every on-screen card re-render on any agent-status update anywhere —
   // O(worktrees²) render amplification. Pre-filtering here means the card
   // only re-renders when something relevant to THIS worktree changes.
-  const entries = useAppStore(
-    useShallow((s) => {
-      const wtTabs = s.tabsByWorktree[worktreeId] ?? EMPTY_TABS
-      if (wtTabs.length === 0) {
-        return EMPTY_LIVE_ENTRIES
-      }
-      const tabIds = new Set(wtTabs.map((t) => t.id))
-      const out: AgentStatusEntry[] = []
-      for (const [paneKey, entry] of Object.entries(s.agentStatusByPaneKey)) {
-        const parsed = parsePaneKey(paneKey)
-        if (!parsed) {
-          continue
-        }
-        if (!tabIds.has(parsed.tabId)) {
-          continue
-        }
-        out.push(entry)
-      }
-      for (const unsupported of Object.values(s.migrationUnsupportedByPtyId ?? {})) {
-        const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
-        if (!entry) {
-          continue
-        }
-        const parsed = parsePaneKey(entry.paneKey)
-        if (!parsed || !tabIds.has(parsed.tabId)) {
-          continue
-        }
-        out.push(entry)
-      }
-      return out.length > 0 ? out : EMPTY_LIVE_ENTRIES
-    })
+  const liveEntries = useAppStore(
+    useShallow((s) => selectLiveAgentStatusEntriesForWorktree(s, worktreeId))
+  )
+  // Why: keep the store selector limited to stable raw records. Converting
+  // migration entries creates fresh objects with Date.now(), which breaks
+  // useSyncExternalStore's cached-snapshot contract and can blank Electron.
+  const migrationUnsupported = useAppStore(
+    useShallow((s) => selectMigrationUnsupportedEntriesForWorktree(s, worktreeId))
   )
   const retained = useAppStore(
-    useShallow((s) => {
-      const out: RetainedAgentEntry[] = []
-      for (const ra of Object.values(s.retainedAgentsByPaneKey)) {
-        if (ra.worktreeId === worktreeId) {
-          out.push(ra)
-        }
-      }
-      return out.length > 0 ? out : EMPTY_RETAINED
-    })
+    useShallow((s) => selectRetainedAgentEntriesForWorktree(s, worktreeId))
   )
   // Why: agentStatusEpoch is included in the dependency array (but not in the
   // computation itself) so the memo recomputes when freshness boundaries
@@ -150,12 +189,23 @@ export function useWorktreeAgentRows(worktreeId: string): DashboardAgentRow[] {
     // Why: Date.now() is read inside the memo (not as a dep) so stale-decay
     // recalculates whenever agentStatusEpoch ticks — same pattern as
     // useDashboardData.
+    const now = Date.now()
+    const entries =
+      migrationUnsupported.length > 0
+        ? [
+            ...liveEntries,
+            ...migrationUnsupported.flatMap((unsupported) => {
+              const entry = migrationUnsupportedToAgentStatusEntry(unsupported)
+              return entry ? [entry] : []
+            })
+          ]
+        : liveEntries
     return buildWorktreeAgentRows({
       tabs: tabs ?? [],
       entries,
       retained,
-      now: Date.now()
+      now
     })
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [tabs, entries, retained, agentStatusEpoch])
+  }, [tabs, liveEntries, migrationUnsupported, retained, agentStatusEpoch])
 }
diff --git a/src/renderer/src/lib/agent-catalog.tsx b/src/renderer/src/lib/agent-catalog.tsx
index 30cac2a6870..1d77e38ae27 100644
--- a/src/renderer/src/lib/agent-catalog.tsx
+++ b/src/renderer/src/lib/agent-catalog.tsx
@@ -28,6 +28,13 @@ export const AGENT_CATALOG: AgentCatalogEntry[] = [
     cmd: 'codex',
     homepageUrl: 'https://github.com/openai/codex'
   },
+  {
+    id: 'grok',
+    label: 'Grok',
+    cmd: 'grok',
+    faviconDomain: 'x.ai',
+    homepageUrl: 'https://x.ai/cli'
+  },
   {
     id: 'copilot',
     label: 'GitHub Copilot',
diff --git a/src/renderer/src/lib/agent-status.test.ts b/src/renderer/src/lib/agent-status.test.ts
index 770a6302cc1..5aaff7a9204 100644
--- a/src/renderer/src/lib/agent-status.test.ts
+++ b/src/renderer/src/lib/agent-status.test.ts
@@ -377,6 +377,7 @@ describe('getAgentLabel', () => {
     expect(getAgentLabel('✦ Gemini CLI')).toBe('Gemini CLI')
     expect(getAgentLabel('⠂ Claude Code')).toBe('Claude Code')
     expect(getAgentLabel('⠋ Codex is thinking')).toBe('Codex')
+    expect(getAgentLabel('Grok running')).toBe('Grok')
     expect(getAgentLabel('⠋ Droid')).toBe('Droid')
     expect(getAgentLabel('Droid ready')).toBe('Droid')
   })
diff --git a/src/renderer/src/lib/agent-status.ts b/src/renderer/src/lib/agent-status.ts
index 7f38952f24d..f1a3a0de942 100644
--- a/src/renderer/src/lib/agent-status.ts
+++ b/src/renderer/src/lib/agent-status.ts
@@ -117,7 +117,8 @@ const WELL_KNOWN_LABELS: Record<string, string> = {
   cursor: 'Cursor',
   aider: 'Aider',
   pi: 'Pi',
-  droid: 'Droid'
+  droid: 'Droid',
+  grok: 'Grok'
 }
 
 export function formatAgentTypeLabel(agentType: AgentType | null | undefined): string {
@@ -166,7 +167,8 @@ const ICONABLE_AGENT_TYPES: Record<TuiAgent, true> = {
   rovo: true,
   hermes: true,
   openclaw: true,
-  copilot: true
+  copilot: true,
+  grok: true
 }
 
 export function agentTypeToIconAgent(agentType: AgentType | null | undefined): TuiAgent | null {
diff --git a/src/renderer/src/lib/tui-agent-startup.test.ts b/src/renderer/src/lib/tui-agent-startup.test.ts
index 1adc0dd4a7b..aa634c5bf90 100644
--- a/src/renderer/src/lib/tui-agent-startup.test.ts
+++ b/src/renderer/src/lib/tui-agent-startup.test.ts
@@ -118,6 +118,22 @@ describe('buildAgentStartupPlan', () => {
     })
   })
 
+  it('launches Grok first and injects the prompt after startup', () => {
+    expect(
+      buildAgentStartupPlan({
+        agent: 'grok',
+        prompt: 'Trace the failing test',
+        cmdOverrides: {},
+        platform: 'linux'
+      })
+    ).toEqual({
+      agent: 'grok',
+      launchCommand: 'grok',
+      expectedProcess: 'grok',
+      followupPrompt: 'Trace the failing test'
+    })
+  })
+
   it('returns null when there is no prompt to inject', () => {
     expect(
       buildAgentStartupPlan({
diff --git a/src/renderer/src/web/web-preload-api.ts b/src/renderer/src/web/web-preload-api.ts
index 6d990c00532..172742c0b21 100644
--- a/src/renderer/src/web/web-preload-api.ts
+++ b/src/renderer/src/web/web-preload-api.ts
@@ -791,7 +791,7 @@ function createCliApi(): NonNullable<Partial<PreloadApi>['cli']> {
 }
 
 function createAgentHooksApi(): NonNullable<Partial<PreloadApi>['agentHooks']> {
-  const status = (agent: 'claude' | 'codex' | 'gemini' | 'cursor' | 'droid') =>
+  const status = (agent: 'claude' | 'codex' | 'gemini' | 'cursor' | 'droid' | 'grok') =>
     Promise.resolve({
       agent,
       state: 'not_installed',
@@ -804,7 +804,8 @@ function createAgentHooksApi(): NonNullable<Partial<PreloadApi>['agentHooks']> {
     codexStatus: () => status('codex'),
     geminiStatus: () => status('gemini'),
     cursorStatus: () => status('cursor'),
-    droidStatus: () => status('droid')
+    droidStatus: () => status('droid'),
+    grokStatus: () => status('grok')
   }
 }
 
diff --git a/src/shared/agent-detection.ts b/src/shared/agent-detection.ts
index c2ea5e881aa..fe824797c9a 100644
--- a/src/shared/agent-detection.ts
+++ b/src/shared/agent-detection.ts
@@ -29,7 +29,8 @@ export const AGENT_NAMES = [
   'gemini',
   'opencode',
   'openclaw',
-  'aider'
+  'aider',
+  'grok'
 ]
 
 // Why: `android` contains `droid`; unlike the legacy agent names above, Droid
@@ -354,6 +355,9 @@ export function getAgentLabel(title: string): string | null {
   if (lower.includes('copilot')) {
     return 'GitHub Copilot'
   }
+  if (lower.includes('grok')) {
+    return 'Grok'
+  }
   if (lower.includes('opencode')) {
     return 'OpenCode'
   }
diff --git a/src/shared/agent-hook-listener.test.ts b/src/shared/agent-hook-listener.test.ts
index fa3c0e8acbf..54329755534 100644
--- a/src/shared/agent-hook-listener.test.ts
+++ b/src/shared/agent-hook-listener.test.ts
@@ -33,6 +33,7 @@ describe('shared agent-hook-listener', () => {
   it('routes pathnames to a known source or null', () => {
     expect(resolveHookSource('/hook/claude')).toBe('claude')
     expect(resolveHookSource('/hook/cursor')).toBe('cursor')
+    expect(resolveHookSource('/hook/grok')).toBe('grok')
     expect(resolveHookSource('/hook/unknown')).toBeNull()
     expect(resolveHookSource('/')).toBeNull()
   })
@@ -123,6 +124,75 @@ describe('shared agent-hook-listener', () => {
     expect(event!.payload.prompt).toBe('')
   })
 
+  it('normalizes Grok hookEventName payloads and keeps prompt across tool events', () => {
+    const prompt = normalizeHookPayload(
+      state,
+      'grok',
+      {
+        paneKey: PANE_KEY,
+        tabId: 'tab-1',
+        worktreeId: 'wt',
+        payload: { hookEventName: 'user_prompt_submit', prompt: 'run the check' }
+      },
+      'production'
+    )
+    expect(prompt).not.toBeNull()
+    expect(prompt!.payload).toMatchObject({
+      state: 'working',
+      prompt: 'run the check',
+      agentType: 'grok'
+    })
+
+    const tool = normalizeHookPayload(
+      state,
+      'grok',
+      {
+        paneKey: PANE_KEY,
+        tabId: 'tab-1',
+        payload: {
+          hookEventName: 'pre_tool_use',
+          toolName: 'run_terminal_cmd',
+          toolInput: { command: 'pnpm test' }
+        }
+      },
+      'production'
+    )
+    expect(tool).not.toBeNull()
+    expect(tool!.payload).toMatchObject({
+      state: 'working',
+      prompt: 'run the check',
+      agentType: 'grok',
+      toolName: 'run_terminal_cmd',
+      toolInput: 'pnpm test'
+    })
+  })
+
+  it('maps Grok feedback notifications to waiting without overwriting the prompt', () => {
+    normalizeHookPayload(
+      state,
+      'grok',
+      { paneKey: PANE_KEY, payload: { hookEventName: 'UserPromptSubmit', prompt: 'ship it' } },
+      'production'
+    )
+
+    const event = normalizeHookPayload(
+      state,
+      'grok',
+      {
+        paneKey: PANE_KEY,
+        payload: { hookEventName: 'Notification', message: 'Grok needs your feedback to proceed' }
+      },
+      'production'
+    )
+
+    expect(event).not.toBeNull()
+    expect(event!.payload).toMatchObject({
+      state: 'waiting',
+      prompt: 'ship it',
+      agentType: 'grok'
+    })
+  })
+
   describe('writeEndpointFile', () => {
     let dir: string
     beforeEach(() => {
diff --git a/src/shared/agent-hook-listener.ts b/src/shared/agent-hook-listener.ts
index 3b5e2c36bf6..e3e93abc7b8 100644
--- a/src/shared/agent-hook-listener.ts
+++ b/src/shared/agent-hook-listener.ts
@@ -305,6 +305,7 @@ const TOOL_INPUT_KEYS_BY_TOOL: Record<string, readonly string[]> = {
   google_web_search: ['query'],
   exec_command: ['cmd', 'command'],
   shell_command: ['cmd', 'command'],
+  run_terminal_cmd: ['command'],
   apply_patch: ['path', 'file_path'],
   view_image: ['path', 'file_path'],
   bash: ['command'],
@@ -741,8 +742,102 @@ function extractDroidToolFields(
   return {}
 }
 
+function normalizeHookEventName(value: unknown): string {
+  if (typeof value !== 'string') {
+    return ''
+  }
+  return value
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[-\s]+/g, '_')
+    .toLowerCase()
+}
+
+function isGrokEvent(eventName: unknown, ...expected: readonly string[]): boolean {
+  const normalized = normalizeHookEventName(eventName)
+  return expected.includes(normalized)
+}
+
+function extractGrokToolFields(
+  eventName: unknown,
+  hookPayload: Record<string, unknown>
+): ToolSnapshot {
+  if (isGrokEvent(eventName, 'pre_tool_use', 'post_tool_use', 'post_tool_use_failure')) {
+    const toolName =
+      readString(hookPayload, 'toolName') ??
+      readString(hookPayload, 'tool_name') ??
+      readString(hookPayload, 'name')
+    const toolInput =
+      deriveToolInputPreview(toolName, hookPayload.toolInput) ??
+      deriveToolInputPreview(toolName, hookPayload.tool_input) ??
+      deriveToolInputPreview(toolName, hookPayload.input) ??
+      deriveToolInputPreview(toolName, hookPayload.arguments)
+    const update: ToolSnapshot = { toolName, toolInput }
+    if (isGrokEvent(eventName, 'post_tool_use', 'post_tool_use_failure')) {
+      const responseText =
+        extractToolResponseText(hookPayload.toolResponse) ??
+        extractToolResponseText(hookPayload.tool_response) ??
+        extractToolResponseText(hookPayload.toolOutput) ??
+        extractToolResponseText(hookPayload.tool_output) ??
+        readString(hookPayload, 'error') ??
+        readString(hookPayload, 'message')
+      if (responseText) {
+        update.lastAssistantMessage = responseText
+      }
+    }
+    return update
+  }
+  if (isGrokEvent(eventName, 'stop', 'session_end')) {
+    const direct =
+      readString(hookPayload, 'lastAssistantMessage') ??
+      readString(hookPayload, 'last_assistant_message')
+    if (direct) {
+      return { lastAssistantMessage: direct }
+    }
+    const fromTranscript = readLastAssistantFromTranscript(
+      hookPayload.transcriptPath ?? hookPayload.transcript_path
+    )
+    if (fromTranscript) {
+      return { lastAssistantMessage: fromTranscript }
+    }
+  }
+  return {}
+}
+
+function isGrokPermissionNotification(message: string | undefined): boolean {
+  if (!message) {
+    return false
+  }
+  const lower = message.toLowerCase()
+  return (
+    lower.includes('permission') ||
+    lower.includes('approval') ||
+    lower.includes('approve') ||
+    lower.includes('allow') ||
+    lower.includes('confirm') ||
+    lower.includes('needs your') ||
+    lower.includes('requires your') ||
+    lower.includes('feedback') ||
+    lower.includes('clarify') ||
+    lower.includes('question')
+  )
+}
+
+function isGrokIdleNotification(message: string | undefined): boolean {
+  if (!message) {
+    return false
+  }
+  const lower = message.toLowerCase()
+  return (
+    lower.includes('type your message') ||
+    lower.includes('enter send') ||
+    lower.includes('shift-tab normal') ||
+    lower.includes('ask a side question')
+  )
+}
+
 function isNewTurnEvent(source: AgentHookSource, eventName: unknown): boolean {
-  // Why: exhaustive switch so adding an 8th source to AgentHookSource fails
+  // Why: exhaustive switch so adding a source to AgentHookSource fails
   // typecheck here instead of silently falling through to `false`.
   switch (source) {
     case 'claude':
@@ -759,6 +854,8 @@ function isNewTurnEvent(source: AgentHookSource, eventName: unknown): boolean {
       return eventName === 'before_agent_start'
     case 'droid':
       return eventName === 'UserPromptSubmit'
+    case 'grok':
+      return isGrokEvent(eventName, 'user_prompt_submit')
     default: {
       const _exhaustive: never = source
       void _exhaustive
@@ -772,7 +869,7 @@ function extractToolFields(
   eventName: unknown,
   hookPayload: Record<string, unknown>
 ): ToolSnapshot {
-  // Why: exhaustive switch so adding an 8th source to AgentHookSource fails
+  // Why: exhaustive switch so adding a source to AgentHookSource fails
   // typecheck here instead of silently routing through OpenCode's extractor.
   switch (source) {
     case 'claude':
@@ -789,6 +886,8 @@ function extractToolFields(
       return extractPiToolFields(eventName, hookPayload)
     case 'droid':
       return extractDroidToolFields(eventName, hookPayload)
+    case 'grok':
+      return extractGrokToolFields(eventName, hookPayload)
     default: {
       const _exhaustive: never = source
       void _exhaustive
@@ -1141,6 +1240,75 @@ function normalizeDroidEvent(
   )
 }
 
+function normalizeGrokEvent(
+  state: HookListenerState,
+  eventName: unknown,
+  promptText: string,
+  paneKey: string,
+  hookPayload: Record<string, unknown>
+): ParsedAgentStatusPayload | null {
+  if (isGrokEvent(eventName, 'session_start')) {
+    // Why: Grok emits SessionStart when the TUI opens/resumes. It should reset
+    // stale per-turn details without creating a visible "working" row before a
+    // user prompt or tool event exists.
+    clearPaneTurnCacheState(state, paneKey)
+    return null
+  }
+
+  const notificationMessage = readString(hookPayload, 'message')
+  let stateName: 'working' | 'waiting' | 'done' | null = null
+  if (
+    isGrokEvent(
+      eventName,
+      'user_prompt_submit',
+      'pre_tool_use',
+      'post_tool_use',
+      'post_tool_use_failure'
+    )
+  ) {
+    stateName = 'working'
+  } else if (isGrokEvent(eventName, 'stop', 'session_end')) {
+    stateName = 'done'
+  } else if (
+    isGrokEvent(eventName, 'notification') &&
+    isGrokPermissionNotification(notificationMessage)
+  ) {
+    stateName = 'waiting'
+  } else if (
+    isGrokEvent(eventName, 'notification') &&
+    isGrokIdleNotification(notificationMessage)
+  ) {
+    stateName = 'done'
+  }
+  if (!stateName) {
+    return null
+  }
+
+  const snapshot = resolveToolState(
+    state,
+    paneKey,
+    extractToolFields('grok', eventName, hookPayload),
+    { resetOnNewTurn: isNewTurnEvent('grok', eventName) }
+  )
+
+  // Why: Grok Notification.message is status UI text, not necessarily the
+  // user's prompt. Preserve the cached UserPromptSubmit prompt for the row.
+  const effectivePrompt = isGrokEvent(eventName, 'notification') ? '' : promptText
+
+  return parseAgentStatusPayload(
+    JSON.stringify({
+      state: stateName,
+      prompt: resolvePrompt(state, paneKey, effectivePrompt, {
+        resetOnNewTurn: isNewTurnEvent('grok', eventName)
+      }),
+      agentType: 'grok',
+      toolName: snapshot.toolName,
+      toolInput: snapshot.toolInput,
+      lastAssistantMessage: snapshot.lastAssistantMessage
+    })
+  )
+}
+
 function readStringField(record: Record<string, unknown>, key: string): string | undefined {
   const value = record[key]
   if (typeof value !== 'string') {
@@ -1196,10 +1364,10 @@ export function normalizeHookPayload(
   }
   const worktreeId = readStringField(record, 'worktreeId')
 
-  const eventName = (hookPayload as Record<string, unknown>).hook_event_name
-  const promptText = extractPromptText(hookPayload as Record<string, unknown>)
   const hookPayloadRecord = hookPayload as Record<string, unknown>
-  // Why: exhaustive switch so adding an 8th source to AgentHookSource fails
+  const eventName = hookPayloadRecord.hook_event_name ?? hookPayloadRecord.hookEventName
+  const promptText = extractPromptText(hookPayload as Record<string, unknown>)
+  // Why: exhaustive switch so adding a source to AgentHookSource fails
   // typecheck here instead of silently routing through OpenCode's normalizer.
   let payload: ParsedAgentStatusPayload | null
   switch (source) {
@@ -1224,6 +1392,9 @@ export function normalizeHookPayload(
     case 'droid':
       payload = normalizeDroidEvent(state, eventName, promptText, paneKey, hookPayloadRecord)
       break
+    case 'grok':
+      payload = normalizeGrokEvent(state, eventName, promptText, paneKey, hookPayloadRecord)
+      break
     default: {
       const _exhaustive: never = source
       void _exhaustive
@@ -1247,7 +1418,8 @@ export const HOOK_SOURCE_BY_PATHNAME: Readonly<Record<string, AgentHookSource>>
   '/hook/opencode': 'opencode',
   '/hook/cursor': 'cursor',
   '/hook/pi': 'pi',
-  '/hook/droid': 'droid'
+  '/hook/droid': 'droid',
+  '/hook/grok': 'grok'
 })
 
 export function resolveHookSource(pathname: string): AgentHookSource | null {
diff --git a/src/shared/agent-hook-relay.ts b/src/shared/agent-hook-relay.ts
index a0d78bdccf8..d855f67d5ac 100644
--- a/src/shared/agent-hook-relay.ts
+++ b/src/shared/agent-hook-relay.ts
@@ -30,7 +30,15 @@ import type { ParsedAgentStatusPayload } from './agent-status-types'
 // Promoted from `src/main/agent-hooks/server.ts` so the relay can import it
 // without dragging Electron in (the shared listener module is the only place
 // that consumes it from the relay side).
-export type AgentHookSource = 'claude' | 'codex' | 'gemini' | 'opencode' | 'cursor' | 'pi' | 'droid'
+export type AgentHookSource =
+  | 'claude'
+  | 'codex'
+  | 'gemini'
+  | 'opencode'
+  | 'cursor'
+  | 'pi'
+  | 'droid'
+  | 'grok'
 
 /** Env marker used by the remote relay. It is a transport/location marker, not
  *  a dev-vs-prod build tag, so main-process env mismatch diagnostics ignore it. */
diff --git a/src/shared/agent-hook-types.ts b/src/shared/agent-hook-types.ts
index 68cbf758b82..1013dc84106 100644
--- a/src/shared/agent-hook-types.ts
+++ b/src/shared/agent-hook-types.ts
@@ -4,7 +4,7 @@
 // gemini/cursor/hook-service.ts). Lives in `shared/` to keep a single
 // source of truth for the version string and status contract.
 
-export const AGENT_HOOK_TARGETS = ['claude', 'codex', 'gemini', 'cursor', 'droid'] as const
+export const AGENT_HOOK_TARGETS = ['claude', 'codex', 'gemini', 'cursor', 'droid', 'grok'] as const
 export type AgentHookTarget = (typeof AGENT_HOOK_TARGETS)[number]
 
 export type AgentHookInstallState = 'installed' | 'not_installed' | 'partial' | 'error'
diff --git a/src/shared/agent-kind.ts b/src/shared/agent-kind.ts
index ef26793cb0f..33585d5a823 100644
--- a/src/shared/agent-kind.ts
+++ b/src/shared/agent-kind.ts
@@ -38,7 +38,8 @@ const TUI_AGENT_KIND_BY_AGENT = {
   rovo: 'rovo',
   hermes: 'hermes',
   openclaw: 'openclaw',
-  copilot: 'copilot'
+  copilot: 'copilot',
+  grok: 'grok'
 } satisfies Record<TuiAgent, ConcreteAgentKind>
 
 // Why: `satisfies Record<TuiAgent, …>` makes the lookup exhaustive at compile
diff --git a/src/shared/agent-status-types.ts b/src/shared/agent-status-types.ts
index 402907d339b..9bf00dc6eb0 100644
--- a/src/shared/agent-status-types.ts
+++ b/src/shared/agent-status-types.ts
@@ -18,6 +18,7 @@ export type WellKnownAgentType =
   | 'aider'
   | 'pi'
   | 'droid'
+  | 'grok'
   | 'unknown'
 export type AgentType = WellKnownAgentType | (string & {})
 
diff --git a/src/shared/telemetry-events.ts b/src/shared/telemetry-events.ts
index d5694770e55..1878c7e0b2c 100644
--- a/src/shared/telemetry-events.ts
+++ b/src/shared/telemetry-events.ts
@@ -60,6 +60,7 @@ export const AGENT_KIND_VALUES = [
   'hermes',
   'openclaw',
   'copilot',
+  'grok',
   'other'
 ] as const
 export const agentKindSchema = z.enum(AGENT_KIND_VALUES)
diff --git a/src/shared/tui-agent-config.ts b/src/shared/tui-agent-config.ts
index ad868812de8..81b7dd699e5 100644
--- a/src/shared/tui-agent-config.ts
+++ b/src/shared/tui-agent-config.ts
@@ -232,6 +232,12 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     // `addTrustedFolder` writes after the user accepts) makes the menu skip
     // entirely. See agent-trust-presets.ts for the file layout.
     preflightTrust: 'copilot'
+  },
+  grok: {
+    detectCmd: 'grok',
+    launchCmd: 'grok',
+    expectedProcess: 'grok',
+    promptInjectionMode: 'stdin-after-start'
   }
 }
 
diff --git a/src/shared/types.ts b/src/shared/types.ts
index c6364d024b2..5f4fa70fb36 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1145,6 +1145,7 @@ export type TuiAgent =
   | 'hermes' // Hermes Agent
   | 'openclaw' // OpenClaw
   | 'copilot' // GitHub Copilot CLI
+  | 'grok' // xAI Grok CLI
 
 export type TaskViewPresetId = 'all' | 'issues' | 'review' | 'my-issues' | 'my-prs' | 'prs'
 

From 8fff0a08e006528e81c6961db4c350362e920dfd Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 13:53:50 -0700
Subject: [PATCH 77/82] Add GitHub issue link from worktree details (#1987)

---
 .../components/sidebar/WorktreeMetaDialog.tsx | 124 ++++++++++++++++--
 1 file changed, 115 insertions(+), 9 deletions(-)

diff --git a/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx b/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx
index 5abb326083e..b400ad0109b 100644
--- a/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx
@@ -10,14 +10,27 @@ import {
 } from '@/components/ui/dialog'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
-import { parseGitHubIssueOrPRNumber } from '@/lib/github-links'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { parseGitHubIssueOrPRLink, parseGitHubIssueOrPRNumber } from '@/lib/github-links'
+import { ExternalLink, LoaderCircle } from 'lucide-react'
 import type { WorktreeMeta } from '../../../../shared/types'
 
+function parseExplicitGitHubIssueUrl(input: string): string | null {
+  const trimmed = input.trim()
+  const link = parseGitHubIssueOrPRLink(trimmed)
+  if (!link || link.type !== 'issue') {
+    return null
+  }
+
+  return trimmed
+}
+
 const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
   const activeModal = useAppStore((s) => s.activeModal)
   const modalData = useAppStore((s) => s.modalData)
   const closeModal = useAppStore((s) => s.closeModal)
   const updateWorktreeMeta = useAppStore((s) => s.updateWorktreeMeta)
+  const fetchIssue = useAppStore((s) => s.fetchIssue)
 
   const isEditMeta = activeModal === 'edit-meta'
   const isOpen = isEditMeta
@@ -37,6 +50,7 @@ const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
   const [prInput, setPrInput] = useState('')
   const [commentInput, setCommentInput] = useState('')
   const [saving, setSaving] = useState(false)
+  const [openingIssue, setOpeningIssue] = useState(false)
   const isMac = navigator.userAgent.includes('Mac')
 
   const issueInputRef = useRef<HTMLInputElement>(null)
@@ -49,9 +63,35 @@ const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
     setIssueInput(currentIssue)
     setPrInput(currentPR)
     setCommentInput(currentComment)
+    setOpeningIssue(false)
   }
   prevIsOpenRef.current = isOpen
 
+  const issueNumber = useMemo(() => parseGitHubIssueOrPRNumber(issueInput), [issueInput])
+  const issueUrlFromInput = useMemo(() => parseExplicitGitHubIssueUrl(issueInput), [issueInput])
+  const issueInputLooksLikeUrl = useMemo(
+    () => /^https?:\/\//i.test(issueInput.trim()),
+    [issueInput]
+  )
+  const issueRepo = useAppStore((s) => {
+    const worktree = Object.values(s.worktreesByRepo)
+      .flat()
+      .find((item) => item.id === worktreeId)
+    if (!worktree) {
+      return undefined
+    }
+    return s.repos.find((repo) => repo.id === worktree.repoId)
+  })
+  const cachedIssueUrl = useAppStore((s) => {
+    if (!issueRepo || issueNumber === null) {
+      return null
+    }
+    return s.issueCache[`${issueRepo.id}::${issueNumber}`]?.data?.url ?? null
+  })
+  const canOpenIssue = issueInputLooksLikeUrl
+    ? Boolean(issueUrlFromInput)
+    : Boolean(cachedIssueUrl || (issueRepo && issueNumber))
+
   const autoResize = useCallback(() => {
     const ta = textareaRef.current
     if (!ta) {
@@ -154,6 +194,48 @@ const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
     [handleSave]
   )
 
+  const handleOpenIssue = useCallback(async () => {
+    if (openingIssue) {
+      return
+    }
+
+    if (issueUrlFromInput) {
+      void window.api.shell.openUrl(issueUrlFromInput)
+      return
+    }
+
+    if (issueInputLooksLikeUrl) {
+      return
+    }
+
+    if (cachedIssueUrl) {
+      void window.api.shell.openUrl(cachedIssueUrl)
+      return
+    }
+
+    if (!issueRepo || issueNumber === null) {
+      return
+    }
+
+    setOpeningIssue(true)
+    try {
+      const issue = await fetchIssue(issueRepo.path, issueNumber, { repoId: issueRepo.id })
+      if (issue?.url) {
+        void window.api.shell.openUrl(issue.url)
+      }
+    } finally {
+      setOpeningIssue(false)
+    }
+  }, [
+    cachedIssueUrl,
+    fetchIssue,
+    issueInputLooksLikeUrl,
+    issueNumber,
+    issueRepo,
+    issueUrlFromInput,
+    openingIssue
+  ])
+
   return (
     <Dialog open={isOpen} onOpenChange={handleOpenChange}>
       <DialogContent
@@ -197,14 +279,38 @@ const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
 
           <div className="space-y-1">
             <label className="text-[11px] font-medium text-muted-foreground">GH Issue</label>
-            <Input
-              ref={issueInputRef}
-              value={issueInput}
-              onChange={(e) => setIssueInput(e.target.value)}
-              onKeyDown={handleIssueKeyDown}
-              placeholder="Issue # or GitHub URL"
-              className="h-8 text-xs"
-            />
+            <div className="relative">
+              <Input
+                ref={issueInputRef}
+                value={issueInput}
+                onChange={(e) => setIssueInput(e.target.value)}
+                onKeyDown={handleIssueKeyDown}
+                placeholder="Issue # or GitHub URL"
+                className="h-8 pr-9 text-xs"
+              />
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    aria-label="Open GitHub issue"
+                    disabled={!canOpenIssue || openingIssue}
+                    onClick={handleOpenIssue}
+                    className="absolute right-1 top-1 text-muted-foreground"
+                  >
+                    {openingIssue ? (
+                      <LoaderCircle className="size-3 animate-spin" />
+                    ) : (
+                      <ExternalLink className="size-3" />
+                    )}
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent side="top" sideOffset={4}>
+                  Open GitHub issue
+                </TooltipContent>
+              </Tooltip>
+            </div>
             <p className="text-[10px] text-muted-foreground">
               Paste an issue URL, or enter a number. Leave blank to remove the link.
             </p>

From f5cc8196f9c5ee2eb07c04cbf1cb6e666eae6b88 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 15 May 2026 14:00:23 -0700
Subject: [PATCH 78/82] Clean up old workspaces (#1873)

Co-authored-by: Orca <help@stably.ai>
---
 src/main/ipc/workspace-cleanup.test.ts        | 418 ++++++++
 src/main/ipc/workspace-cleanup.ts             | 700 +++++++++++++
 src/main/runtime/orca-runtime.ts              |  17 +
 .../attach-main-window-services.test.ts       |   1 +
 .../window/attach-main-window-services.ts     |   4 +-
 src/preload/api-types.ts                      |  15 +
 src/preload/index.ts                          |  13 +
 src/renderer/src/App.tsx                      |   5 +
 .../status-bar/ResourceUsageStatusSegment.tsx |  50 +-
 .../WorkspaceCleanupDialog.tsx                | 980 ++++++++++++++++++
 src/renderer/src/store/index.ts               |   4 +-
 .../src/store/slices/diffComments.test.ts     |   4 +-
 .../slices/store-session-cascades.test.ts     |   4 +-
 .../src/store/slices/store-test-helpers.ts    |   4 +-
 src/renderer/src/store/slices/tabs.test.ts    |   4 +-
 src/renderer/src/store/slices/ui.ts           |  42 +
 .../store/slices/workspace-cleanup.test.ts    | 363 +++++++
 .../src/store/slices/workspace-cleanup.ts     | 527 ++++++++++
 src/renderer/src/store/types.ts               |   4 +-
 src/shared/constants.ts                       |   3 +-
 src/shared/types.ts                           |   2 +
 src/shared/workspace-cleanup.test.ts          | 129 +++
 src/shared/workspace-cleanup.ts               | 232 +++++
 23 files changed, 3511 insertions(+), 14 deletions(-)
 create mode 100644 src/main/ipc/workspace-cleanup.test.ts
 create mode 100644 src/main/ipc/workspace-cleanup.ts
 create mode 100644 src/renderer/src/components/workspace-cleanup/WorkspaceCleanupDialog.tsx
 create mode 100644 src/renderer/src/store/slices/workspace-cleanup.test.ts
 create mode 100644 src/renderer/src/store/slices/workspace-cleanup.ts
 create mode 100644 src/shared/workspace-cleanup.test.ts
 create mode 100644 src/shared/workspace-cleanup.ts

diff --git a/src/main/ipc/workspace-cleanup.test.ts b/src/main/ipc/workspace-cleanup.test.ts
new file mode 100644
index 00000000000..2a1e5072183
--- /dev/null
+++ b/src/main/ipc/workspace-cleanup.test.ts
@@ -0,0 +1,418 @@
+/* eslint-disable max-lines -- Why: scan and IPC process-liveness tests share
+   hoisted Electron/git provider mocks; splitting would duplicate brittle setup. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ipcMain } from 'electron'
+import type { Store } from '../persistence'
+import type { DiffComment, GitStatusResult, Repo } from '../../shared/types'
+
+const {
+  listRepoWorktreesMock,
+  getStatusMock,
+  gitExecFileAsyncMock,
+  getSshGitProviderMock,
+  getSshPtyProviderMock,
+  listRegisteredPtysMock
+} = vi.hoisted(() => ({
+  listRepoWorktreesMock: vi.fn(),
+  getStatusMock: vi.fn(),
+  gitExecFileAsyncMock: vi.fn(),
+  getSshGitProviderMock: vi.fn(),
+  getSshPtyProviderMock: vi.fn(),
+  listRegisteredPtysMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: vi.fn(),
+    removeHandler: vi.fn()
+  }
+}))
+
+vi.mock('../repo-worktrees', () => ({
+  listRepoWorktrees: listRepoWorktreesMock,
+  createFolderWorktree: vi.fn()
+}))
+
+vi.mock('../git/status', () => ({
+  getStatus: getStatusMock
+}))
+
+vi.mock('../git/runner', () => ({
+  gitExecFileAsync: gitExecFileAsyncMock
+}))
+
+vi.mock('../providers/ssh-git-dispatch', () => ({
+  getSshGitProvider: getSshGitProviderMock
+}))
+
+vi.mock('../memory/pty-registry', () => ({
+  listRegisteredPtys: listRegisteredPtysMock
+}))
+
+vi.mock('./pty', () => ({
+  getSshPtyProvider: getSshPtyProviderMock
+}))
+
+import { registerWorkspaceCleanupHandlers, scanWorkspaceCleanup } from './workspace-cleanup'
+
+const NOW = 1_700_000_000_000
+const REPO: Repo = {
+  id: 'repo-1',
+  path: '/repo',
+  displayName: 'Repo',
+  badgeColor: '#000',
+  addedAt: NOW
+}
+
+function makeStore(
+  options: {
+    baseRef?: string
+    diffComments?: DiffComment[]
+    lastActivityAt?: number
+    linkedIssue?: number | null
+    repos?: Repo[]
+  } = {}
+): Store {
+  const baseRef = Object.hasOwn(options, 'baseRef') ? options.baseRef : 'origin/main'
+  return {
+    getRepos: () => options.repos ?? [REPO],
+    getWorktreeMeta: () => ({
+      linkedPR: null,
+      linkedIssue: options.linkedIssue ?? null,
+      lastActivityAt: options.lastActivityAt ?? NOW - 40 * 24 * 60 * 60 * 1000,
+      baseRef,
+      diffComments: options.diffComments
+    }),
+    getAllWorktreeMeta: () => ({}),
+    getGitHubCache: () => ({
+      pr: {},
+      issue: {}
+    })
+  } as unknown as Store
+}
+
+describe('workspace cleanup scan', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    listRepoWorktreesMock.mockReset()
+    getStatusMock.mockReset()
+    gitExecFileAsyncMock.mockReset()
+    getSshGitProviderMock.mockReset()
+    getSshPtyProviderMock.mockReset()
+    listRegisteredPtysMock.mockReset()
+    listRegisteredPtysMock.mockReturnValue([])
+    vi.mocked(ipcMain.handle).mockReset()
+    vi.mocked(ipcMain.removeHandler).mockReset()
+    listRepoWorktreesMock.mockResolvedValue([
+      {
+        path: '/repo-feature',
+        head: 'abc123',
+        branch: 'refs/heads/feature',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+    getStatusMock.mockResolvedValue({
+      entries: [],
+      conflictOperation: 'unknown',
+      upstreamStatus: { hasUpstream: true, ahead: 0, behind: 0 }
+    } satisfies GitStatusResult)
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: '0\n', stderr: '' })
+    getSshGitProviderMock.mockReturnValue(undefined)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('default-selects inactive workspaces when git status is clean', async () => {
+    const result = await scanWorkspaceCleanup(makeStore())
+
+    expect(getStatusMock).toHaveBeenCalledTimes(1)
+    expect(result.candidates).toHaveLength(1)
+    expect(result.candidates[0]).toMatchObject({
+      tier: 'ready',
+      selectedByDefault: true,
+      reasons: ['idle-clean'],
+      git: {
+        clean: true,
+        upstreamAhead: 0
+      }
+    })
+  })
+
+  it('keeps raw scan errors out of renderer-facing results', async () => {
+    listRepoWorktreesMock.mockRejectedValue(new Error('fatal: path /Users/alice/private failed'))
+
+    const result = await scanWorkspaceCleanup(makeStore())
+
+    expect(result.errors).toEqual([
+      {
+        repoId: 'repo-1',
+        repoName: 'Repo',
+        message: 'Git could not list worktrees.'
+      }
+    ])
+  })
+
+  it('skips disconnected remote workspaces without a scan warning', async () => {
+    const result = await scanWorkspaceCleanup(
+      makeStore({
+        repos: [{ ...REPO, connectionId: 'ssh-1' }]
+      })
+    )
+
+    expect(result.errors).toEqual([])
+    expect(result.candidates).toEqual([])
+  })
+
+  it('scans connected remote workspaces through the SSH git provider', async () => {
+    const provider = {
+      listWorktrees: vi.fn().mockResolvedValue([
+        {
+          path: '/remote/repo-feature',
+          head: 'abc123',
+          branch: 'refs/heads/feature',
+          isBare: false,
+          isMainWorktree: false
+        }
+      ]),
+      getStatus: vi.fn().mockResolvedValue({
+        entries: [],
+        conflictOperation: 'unknown',
+        upstreamStatus: { hasUpstream: true, ahead: 0, behind: 0 }
+      } satisfies GitStatusResult)
+    }
+    getSshGitProviderMock.mockReturnValue(provider)
+
+    const result = await scanWorkspaceCleanup(
+      makeStore({
+        repos: [{ ...REPO, connectionId: 'ssh-1' }]
+      })
+    )
+
+    expect(provider.listWorktrees).toHaveBeenCalledWith('/repo')
+    expect(provider.getStatus).toHaveBeenCalledWith('/remote/repo-feature')
+    expect(result.errors).toEqual([])
+    expect(result.candidates[0]).toMatchObject({
+      connectionId: 'ssh-1',
+      tier: 'ready',
+      selectedByDefault: true,
+      reasons: ['idle-clean']
+    })
+  })
+
+  it('skips connected remote workspaces that fail during broad scans', async () => {
+    const provider = {
+      listWorktrees: vi.fn().mockRejectedValue(new Error('ssh timeout')),
+      getStatus: vi.fn()
+    }
+    getSshGitProviderMock.mockReturnValue(provider)
+
+    const result = await scanWorkspaceCleanup(
+      makeStore({
+        repos: [{ ...REPO, connectionId: 'ssh-1' }]
+      })
+    )
+
+    expect(provider.listWorktrees).toHaveBeenCalledWith('/repo')
+    expect(result.errors).toEqual([])
+    expect(result.candidates).toEqual([])
+  })
+
+  it('filters out recent workspaces before running git status', async () => {
+    const result = await scanWorkspaceCleanup(
+      makeStore({
+        lastActivityAt: NOW - 2 * 24 * 60 * 60 * 1000
+      })
+    )
+
+    expect(getStatusMock).not.toHaveBeenCalled()
+    expect(gitExecFileAsyncMock).not.toHaveBeenCalled()
+    expect(result.candidates).toEqual([])
+  })
+
+  it('includes focused remove preflight rows even when they are recent', async () => {
+    const result = await scanWorkspaceCleanup(
+      makeStore({
+        lastActivityAt: NOW - 2 * 24 * 60 * 60 * 1000
+      }),
+      { worktreeId: 'repo-1::/repo-feature' }
+    )
+
+    expect(getStatusMock).toHaveBeenCalledTimes(1)
+    expect(result.candidates[0]).toMatchObject({
+      tier: 'review',
+      selectedByDefault: false,
+      reasons: [],
+      git: {
+        clean: true,
+        checkedAt: expect.any(Number)
+      }
+    })
+  })
+
+  it('honors renderer git deferrals without hiding the workspace', async () => {
+    const result = await scanWorkspaceCleanup(makeStore(), {
+      skipGitWorktreeIds: ['repo-1::/repo-feature']
+    })
+
+    expect(getStatusMock).not.toHaveBeenCalled()
+    expect(result.candidates[0]).toMatchObject({
+      tier: 'review',
+      selectedByDefault: false,
+      reasons: ['idle-clean'],
+      git: {
+        clean: null,
+        checkedAt: null
+      }
+    })
+  })
+
+  it('uses remote commit presence when a clean inactive workspace has no upstream', async () => {
+    getStatusMock.mockResolvedValue({
+      entries: [],
+      conflictOperation: 'unknown',
+      upstreamStatus: { hasUpstream: false, ahead: 0, behind: 0 }
+    } satisfies GitStatusResult)
+
+    const result = await scanWorkspaceCleanup(makeStore())
+
+    expect(getStatusMock).toHaveBeenCalledTimes(1)
+    expect(gitExecFileAsyncMock).toHaveBeenCalledWith(
+      ['rev-list', '--count', 'HEAD', '--not', '--remotes'],
+      { cwd: '/repo-feature' }
+    )
+    expect(result.candidates[0]).toMatchObject({
+      tier: 'ready',
+      selectedByDefault: true,
+      git: {
+        clean: true,
+        upstreamAhead: null
+      }
+    })
+  })
+
+  it('protects clean inactive workspaces with local-only commits', async () => {
+    getStatusMock.mockResolvedValue({
+      entries: [],
+      conflictOperation: 'unknown',
+      upstreamStatus: { hasUpstream: false, ahead: 0, behind: 0 }
+    } satisfies GitStatusResult)
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: '2\n', stderr: '' })
+
+    const result = await scanWorkspaceCleanup(makeStore())
+
+    expect(result.candidates[0]).toMatchObject({
+      tier: 'protected',
+      selectedByDefault: false,
+      blockers: ['unpushed-commits'],
+      git: {
+        clean: true,
+        upstreamAhead: null
+      }
+    })
+  })
+
+  it('keeps diff notes as context instead of blocking inactive cleanup', async () => {
+    const result = await scanWorkspaceCleanup(
+      makeStore({
+        baseRef: undefined,
+        diffComments: [
+          {
+            id: 'comment-1',
+            worktreeId: 'repo-1::/repo-feature',
+            filePath: 'src/file.ts',
+            lineNumber: 12,
+            body: 'Follow up before deleting',
+            createdAt: NOW - 1_000,
+            side: 'modified'
+          }
+        ]
+      })
+    )
+
+    expect(result.candidates[0]).toMatchObject({
+      tier: 'ready',
+      selectedByDefault: true,
+      reasons: ['idle-clean'],
+      localContext: {
+        diffCommentCount: 1,
+        newestDiffCommentAt: NOW - 1_000
+      }
+    })
+  })
+
+  it('does not expose PR cache state in inactivity cleanup results', async () => {
+    const result = await scanWorkspaceCleanup(
+      makeStore({
+        repos: [REPO, { ...REPO, id: 'repo-2' }]
+      })
+    )
+
+    expect(result.candidates[0]).toMatchObject({
+      tier: 'ready',
+      selectedByDefault: true,
+      reasons: ['idle-clean']
+    })
+    expect(result.candidates[0]).not.toHaveProperty('linkedPR')
+  })
+
+  it('reports local processes that workspace deletion would kill', async () => {
+    const localProvider = {
+      listProcesses: vi.fn().mockResolvedValue([
+        {
+          id: 'repo-1::/repo-feature@@session-1',
+          cwd: '/repo-feature',
+          title: 'zsh'
+        }
+      ])
+    }
+    registerWorkspaceCleanupHandlers(makeStore(), {
+      runtime: {
+        hasTerminalsForWorktree: vi.fn().mockResolvedValue(false)
+      } as never,
+      getLocalPtyProvider: () => localProvider as never
+    })
+
+    const handler = vi
+      .mocked(ipcMain.handle)
+      .mock.calls.find(([channel]) => channel === 'workspaceCleanup:hasKillableLocalProcesses')?.[1]
+
+    await expect(handler?.({} as never, { worktreeId: 'repo-1::/repo-feature' })).resolves.toEqual({
+      hasKillableProcesses: true
+    })
+  })
+
+  it('reports SSH processes inside the remote workspace path', async () => {
+    getSshPtyProviderMock.mockReturnValue({
+      listProcesses: vi.fn().mockResolvedValue([
+        {
+          id: 'remote-session-1',
+          cwd: '/remote/repo-feature/subdir',
+          title: 'codex'
+        }
+      ])
+    })
+    registerWorkspaceCleanupHandlers(makeStore(), {
+      runtime: {
+        hasTerminalsForWorktree: vi.fn().mockResolvedValue(false)
+      } as never
+    })
+
+    const handler = vi
+      .mocked(ipcMain.handle)
+      .mock.calls.find(([channel]) => channel === 'workspaceCleanup:hasKillableLocalProcesses')?.[1]
+
+    await expect(
+      handler?.({} as never, {
+        worktreeId: 'repo-ssh::/remote/repo-feature',
+        connectionId: 'ssh-1',
+        worktreePath: '/remote/repo-feature'
+      })
+    ).resolves.toEqual({
+      hasKillableProcesses: true
+    })
+  })
+})
diff --git a/src/main/ipc/workspace-cleanup.ts b/src/main/ipc/workspace-cleanup.ts
new file mode 100644
index 00000000000..21c7e26819a
--- /dev/null
+++ b/src/main/ipc/workspace-cleanup.ts
@@ -0,0 +1,700 @@
+/* eslint-disable max-lines */
+import { ipcMain } from 'electron'
+import { basename } from 'node:path'
+import type { Store } from '../persistence'
+import { getStatus } from '../git/status'
+import { gitExecFileAsync } from '../git/runner'
+import { listRepoWorktrees, createFolderWorktree } from '../repo-worktrees'
+import { getSshGitProvider } from '../providers/ssh-git-dispatch'
+import type { IGitProvider, IPtyProvider } from '../providers/types'
+import type { OrcaRuntimeService } from '../runtime/orca-runtime'
+import { listRegisteredPtys } from '../memory/pty-registry'
+import { getSshPtyProvider } from './pty'
+import { isFolderRepo } from '../../shared/repo-kind'
+import type { GitStatusResult, GitWorktreeInfo, Repo, Worktree } from '../../shared/types'
+import { mergeWorktree } from './worktree-logic'
+import { splitWorktreeId } from '../../shared/worktree-id'
+import {
+  WORKSPACE_CLEANUP_CLASSIFIER_VERSION,
+  applyWorkspaceCleanupPolicy,
+  createWorkspaceCleanupFingerprint,
+  getWorkspaceCleanupInactivityReasons,
+  isWorkspaceOldForCleanup,
+  type WorkspaceCleanupBlocker,
+  type WorkspaceCleanupCandidate,
+  type WorkspaceCleanupDismissArgs,
+  type WorkspaceCleanupLocalProcessArgs,
+  type WorkspaceCleanupLocalProcessResult,
+  type WorkspaceCleanupReason,
+  type WorkspaceCleanupScanError,
+  type WorkspaceCleanupScanArgs,
+  type WorkspaceCleanupScanResult
+} from '../../shared/workspace-cleanup'
+
+const GIT_READ_TIMEOUT_MS = 8_000
+const WORKTREE_SCAN_CONCURRENCY = 3
+
+type GitEvidence = {
+  clean: boolean | null
+  upstreamAhead: number | null
+  upstreamBehind: number | null
+  checkedAt: number | null
+  blockers: WorkspaceCleanupBlocker[]
+}
+
+type WorkspaceCleanupHandlerDeps = {
+  runtime?: OrcaRuntimeService
+  getLocalPtyProvider?: () => IPtyProvider
+}
+
+export function registerWorkspaceCleanupHandlers(
+  store: Store,
+  deps: WorkspaceCleanupHandlerDeps = {}
+): void {
+  ipcMain.removeHandler('workspaceCleanup:scan')
+  ipcMain.removeHandler('workspaceCleanup:dismiss')
+  ipcMain.removeHandler('workspaceCleanup:clearDismissals')
+  ipcMain.removeHandler('workspaceCleanup:hasKillableLocalProcesses')
+
+  ipcMain.handle(
+    'workspaceCleanup:scan',
+    (_event, args?: WorkspaceCleanupScanArgs): Promise<WorkspaceCleanupScanResult> =>
+      scanWorkspaceCleanup(store, args ?? {})
+  )
+
+  ipcMain.handle('workspaceCleanup:dismiss', (_event, args: WorkspaceCleanupDismissArgs) => {
+    const current = store.getUI().workspaceCleanup?.dismissals ?? {}
+    const next = { ...current }
+    for (const dismissal of args.dismissals ?? []) {
+      if (
+        dismissal &&
+        dismissal.classifierVersion === WORKSPACE_CLEANUP_CLASSIFIER_VERSION &&
+        typeof dismissal.worktreeId === 'string' &&
+        typeof dismissal.fingerprint === 'string'
+      ) {
+        next[dismissal.worktreeId] = dismissal
+      }
+    }
+    store.updateUI({ workspaceCleanup: { dismissals: next } })
+  })
+
+  ipcMain.handle('workspaceCleanup:clearDismissals', () => {
+    store.updateUI({ workspaceCleanup: { dismissals: {} } })
+  })
+
+  ipcMain.handle(
+    'workspaceCleanup:hasKillableLocalProcesses',
+    async (
+      _event,
+      args: WorkspaceCleanupLocalProcessArgs
+    ): Promise<WorkspaceCleanupLocalProcessResult> => ({
+      hasKillableProcesses: await hasKillableProcesses(args, deps)
+    })
+  )
+}
+
+async function hasKillableProcesses(
+  args: WorkspaceCleanupLocalProcessArgs,
+  deps: WorkspaceCleanupHandlerDeps
+): Promise<boolean | null> {
+  const { worktreeId } = args
+  if (typeof worktreeId !== 'string' || worktreeId.length === 0) {
+    return false
+  }
+
+  let livenessUnknown = false
+  if (deps.runtime) {
+    try {
+      if (await deps.runtime.hasTerminalsForWorktree(worktreeId)) {
+        return true
+      }
+    } catch {
+      livenessUnknown = true
+    }
+  }
+
+  if (args.connectionId) {
+    return hasKillableSshProcesses(args.connectionId, args.worktreePath ?? '', livenessUnknown)
+  }
+
+  const registryPtyIds = new Set(
+    listRegisteredPtys()
+      .filter((entry) => entry.worktreeId === worktreeId)
+      .map((entry) => entry.ptyId)
+  )
+
+  const provider = deps.getLocalPtyProvider?.()
+  if (!provider) {
+    return registryPtyIds.size > 0 ? true : null
+  }
+
+  try {
+    const prefix = `${worktreeId}@@`
+    const sessions = await provider.listProcesses()
+    if (
+      sessions.some((session) => session.id.startsWith(prefix) || registryPtyIds.has(session.id))
+    ) {
+      return true
+    }
+    return livenessUnknown ? null : false
+  } catch {
+    return registryPtyIds.size > 0 ? true : null
+  }
+}
+
+async function hasKillableSshProcesses(
+  connectionId: string,
+  worktreePath: string,
+  livenessUnknown: boolean
+): Promise<boolean | null> {
+  const provider = getSshPtyProvider(connectionId)
+  if (!provider) {
+    return null
+  }
+
+  try {
+    const normalizedWorktreePath = normalizeRemotePath(worktreePath)
+    const sessions = await provider.listProcesses()
+    if (
+      sessions.some((session) => {
+        if (session.id.startsWith(`${worktreePath}@@`)) {
+          return true
+        }
+        return (
+          normalizedWorktreePath.length > 0 &&
+          isPathWithin(normalizeRemotePath(session.cwd), normalizedWorktreePath)
+        )
+      })
+    ) {
+      return true
+    }
+    return livenessUnknown ? null : false
+  } catch {
+    return null
+  }
+}
+
+function normalizeRemotePath(path: string): string {
+  return path.replace(/\\/g, '/').replace(/\/+$/, '')
+}
+
+function isPathWithin(candidatePath: string, parentPath: string): boolean {
+  return candidatePath === parentPath || candidatePath.startsWith(`${parentPath}/`)
+}
+
+export async function scanWorkspaceCleanup(
+  store: Store,
+  args: WorkspaceCleanupScanArgs = {}
+): Promise<WorkspaceCleanupScanResult> {
+  const scannedAt = Date.now()
+  const repos = store.getRepos()
+  const errors: WorkspaceCleanupScanResult['errors'] = []
+  const candidates: WorkspaceCleanupCandidate[] = []
+
+  for (const repo of repos) {
+    const result = await scanRepoWorkspaces({
+      store,
+      repo,
+      scannedAt,
+      targetWorktreeId: args.worktreeId,
+      skipGitWorktreeIds: new Set(args.skipGitWorktreeIds ?? [])
+    })
+    candidates.push(...result.candidates)
+    errors.push(...result.errors)
+  }
+
+  return { scannedAt, candidates, errors }
+}
+
+async function scanRepoWorkspaces(args: {
+  store: Store
+  repo: Repo
+  scannedAt: number
+  targetWorktreeId?: string
+  skipGitWorktreeIds: Set<string>
+}): Promise<WorkspaceCleanupScanResult> {
+  const { store, repo, scannedAt, targetWorktreeId, skipGitWorktreeIds } = args
+  const errors: WorkspaceCleanupScanResult['errors'] = []
+  let provider: IGitProvider | null = null
+  let gitWorktrees: GitWorktreeInfo[] = []
+  const repoIsFolder = isFolderRepo(repo)
+
+  try {
+    if (repoIsFolder) {
+      gitWorktrees = [createFolderWorktree(repo)]
+    } else if (repo.connectionId) {
+      provider = getSshGitProvider(repo.connectionId) ?? null
+      if (!provider) {
+        // Why: cleanup should reflect only workspaces Orca can currently
+        // inspect. Disconnected SSH repos are skipped in broad scans.
+        return {
+          scannedAt,
+          candidates: targetWorktreeId
+            ? synthesizeDisconnectedSshCandidates(store, repo, scannedAt, targetWorktreeId)
+            : [],
+          errors: []
+        }
+      }
+      gitWorktrees = await withTimeout(
+        provider.listWorktrees(repo.path),
+        GIT_READ_TIMEOUT_MS,
+        'Timed out listing SSH worktrees.'
+      )
+    } else {
+      gitWorktrees = await withTimeout(
+        listRepoWorktrees(repo),
+        GIT_READ_TIMEOUT_MS,
+        'Timed out listing worktrees.'
+      )
+    }
+  } catch (error) {
+    console.error('Workspace cleanup repo scan failed', error)
+    if (repo.connectionId && !targetWorktreeId) {
+      // Why: broad cleanup only shows remote workspaces Orca can inspect now.
+      // A connected SSH repo that fails mid-scan is omitted, not bannered.
+      return { scannedAt, candidates: [], errors: [] }
+    }
+    errors.push(createScanError(repo, toSafeRepoScanError(error)))
+    return { scannedAt, candidates: [], errors }
+  }
+
+  const worktrees = gitWorktrees
+    .map((gitWorktree) => {
+      const worktreeId = `${repo.id}::${gitWorktree.path}`
+      const meta = store.getWorktreeMeta(worktreeId)
+      return mergeWorktree(repo.id, gitWorktree, meta, repo.displayName)
+    })
+    .filter((worktree) => {
+      if (targetWorktreeId) {
+        return worktree.id === targetWorktreeId
+      }
+      return (
+        !repoIsFolder &&
+        !worktree.isMainWorktree &&
+        isWorkspaceInactiveForCleanup(worktree, scannedAt)
+      )
+    })
+
+  const candidates = await mapWithConcurrency(worktrees, WORKTREE_SCAN_CONCURRENCY, (worktree) =>
+    buildCandidate({
+      repo,
+      worktree,
+      scannedAt,
+      provider,
+      skipGit: skipGitWorktreeIds.has(worktree.id),
+      forceGitCheck: Boolean(targetWorktreeId)
+    }).catch((error) => {
+      console.error('Workspace cleanup candidate scan failed', error)
+      return buildCandidateFromError(repo, worktree, scannedAt, toErrorMessage(error))
+    })
+  )
+
+  return { scannedAt, candidates, errors }
+}
+
+async function buildCandidate(args: {
+  repo: Repo
+  worktree: Worktree
+  scannedAt: number
+  provider: IGitProvider | null
+  skipGit: boolean
+  forceGitCheck: boolean
+}): Promise<WorkspaceCleanupCandidate> {
+  const { repo, worktree, scannedAt, provider, skipGit, forceGitCheck } = args
+  const blockers: WorkspaceCleanupBlocker[] = []
+  const reasons = getInactivityReasons(worktree, scannedAt)
+  const repoIsFolder = isFolderRepo(repo)
+
+  if (worktree.isMainWorktree) {
+    blockers.push('main-worktree')
+  }
+  if (repoIsFolder) {
+    blockers.push('folder-repo')
+  }
+  if (worktree.isPinned) {
+    blockers.push('pinned')
+  }
+
+  const localContext = buildLocalContext(worktree)
+  const shouldReadGit = shouldReadGitEvidence({
+    repoIsFolder,
+    blockers,
+    worktree,
+    skipGit,
+    forceGitCheck
+  })
+
+  const gitEvidence = !shouldReadGit
+    ? createEmptyGitEvidence()
+    : await readGitEvidence(worktree, repo, provider)
+  blockers.push(...gitEvidence.blockers)
+
+  const candidateWithoutFingerprint: WorkspaceCleanupCandidate = {
+    worktreeId: worktree.id,
+    repoId: repo.id,
+    repoName: repo.displayName,
+    connectionId: repo.connectionId ?? null,
+    displayName: worktree.displayName,
+    branch: shortBranchName(worktree.branch),
+    path: worktree.path,
+    tier: 'review',
+    selectedByDefault: false,
+    reasons,
+    blockers: uniqueBlockers(blockers),
+    lastActivityAt: worktree.lastActivityAt,
+    ...(worktree.createdAt !== undefined ? { createdAt: worktree.createdAt } : {}),
+    localContext,
+    git: {
+      clean: gitEvidence.clean,
+      upstreamAhead: gitEvidence.upstreamAhead,
+      upstreamBehind: gitEvidence.upstreamBehind,
+      checkedAt: gitEvidence.checkedAt
+    },
+    fingerprint: ''
+  }
+
+  const fingerprint = createWorkspaceCleanupFingerprint({
+    branch: candidateWithoutFingerprint.branch,
+    head: worktree.head,
+    gitClean: gitEvidence.clean,
+    lastActivityAt: worktree.lastActivityAt
+  })
+
+  return applyWorkspaceCleanupPolicy({
+    ...candidateWithoutFingerprint,
+    reasons: uniqueReasons(reasons),
+    blockers: uniqueBlockers(blockers),
+    fingerprint
+  })
+}
+
+function shouldReadGitEvidence(args: {
+  repoIsFolder: boolean
+  blockers: WorkspaceCleanupBlocker[]
+  worktree: Worktree
+  skipGit: boolean
+  forceGitCheck: boolean
+}): boolean {
+  const { repoIsFolder, blockers, worktree, skipGit, forceGitCheck } = args
+  if ((skipGit && !forceGitCheck) || repoIsFolder || worktree.isMainWorktree) {
+    return false
+  }
+  if (
+    blockers.includes('pinned') ||
+    blockers.includes('main-worktree') ||
+    blockers.includes('folder-repo')
+  ) {
+    return false
+  }
+
+  // Why: inactivity is the only recommendation signal now. Git is read only
+  // to keep the destructive path from deleting dirty or local-only branch work.
+  return true
+}
+
+async function readGitEvidence(
+  worktree: Worktree,
+  repo: Repo,
+  provider: IGitProvider | null
+): Promise<GitEvidence> {
+  const blockers: WorkspaceCleanupBlocker[] = []
+  let status: GitStatusResult
+  const checkedAt = Date.now()
+
+  try {
+    status = await withTimeout(
+      repo.connectionId ? provider!.getStatus(worktree.path) : getStatus(worktree.path),
+      GIT_READ_TIMEOUT_MS,
+      'Timed out reading git status.'
+    )
+  } catch {
+    return {
+      ...createEmptyGitEvidence(),
+      blockers: ['git-status-error']
+    }
+  }
+
+  if (status.upstreamStatus === undefined) {
+    return {
+      ...createEmptyGitEvidence(),
+      blockers: ['git-status-error']
+    }
+  }
+
+  const clean = status.entries.length === 0
+  if (!clean) {
+    blockers.push('dirty-files')
+  }
+
+  const upstreamAhead = status.upstreamStatus.hasUpstream ? status.upstreamStatus.ahead : null
+  const upstreamBehind = status.upstreamStatus.hasUpstream ? status.upstreamStatus.behind : null
+  if (upstreamAhead !== null && upstreamAhead > 0) {
+    blockers.push('unpushed-commits')
+  }
+  if (clean && upstreamAhead === null) {
+    const unpushedCommitCount = await readUnpushedCommitCount(worktree, repo, provider)
+    if (unpushedCommitCount === null) {
+      blockers.push('unknown-base')
+    } else if (unpushedCommitCount > 0) {
+      blockers.push('unpushed-commits')
+    }
+  }
+
+  const evidence: GitEvidence = {
+    clean,
+    upstreamAhead,
+    upstreamBehind,
+    checkedAt,
+    blockers
+  }
+
+  return { ...evidence, blockers: uniqueBlockers(blockers) }
+}
+
+async function readUnpushedCommitCount(
+  worktree: Worktree,
+  repo: Repo,
+  provider: IGitProvider | null
+): Promise<number | null> {
+  try {
+    const result = await withTimeout(
+      repo.connectionId
+        ? provider!.exec(['rev-list', '--count', 'HEAD', '--not', '--remotes'], worktree.path)
+        : gitExecFileAsync(['rev-list', '--count', 'HEAD', '--not', '--remotes'], {
+            cwd: worktree.path
+          }),
+      GIT_READ_TIMEOUT_MS,
+      'Timed out checking unpushed commits.'
+    )
+    const count = Number.parseInt(result.stdout.trim(), 10)
+    return Number.isFinite(count) ? count : null
+  } catch {
+    return null
+  }
+}
+
+function buildCandidateFromError(
+  repo: Repo,
+  worktree: Worktree,
+  scannedAt: number,
+  _message: string
+): WorkspaceCleanupCandidate {
+  return applyWorkspaceCleanupPolicy({
+    worktreeId: worktree.id,
+    repoId: repo.id,
+    repoName: repo.displayName,
+    connectionId: repo.connectionId ?? null,
+    displayName: worktree.displayName,
+    branch: shortBranchName(worktree.branch),
+    path: worktree.path,
+    tier: 'protected',
+    selectedByDefault: false,
+    reasons: getInactivityReasons(worktree, scannedAt),
+    blockers: ['git-status-error'],
+    lastActivityAt: worktree.lastActivityAt,
+    ...(worktree.createdAt !== undefined ? { createdAt: worktree.createdAt } : {}),
+    localContext: buildLocalContext(worktree),
+    git: {
+      clean: null,
+      upstreamAhead: null,
+      upstreamBehind: null,
+      checkedAt: scannedAt
+    },
+    fingerprint: createWorkspaceCleanupFingerprint({
+      branch: shortBranchName(worktree.branch),
+      head: worktree.head,
+      gitClean: null,
+      lastActivityAt: worktree.lastActivityAt
+    })
+  })
+}
+
+function synthesizeDisconnectedSshCandidates(
+  store: Store,
+  repo: Repo,
+  scannedAt: number,
+  targetWorktreeId?: string
+): WorkspaceCleanupCandidate[] {
+  return Object.entries(store.getAllWorktreeMeta())
+    .filter(([worktreeId, meta]) => {
+      if (!worktreeId.startsWith(`${repo.id}::`)) {
+        return false
+      }
+      if (targetWorktreeId) {
+        return targetWorktreeId === worktreeId
+      }
+      return isWorkspaceInactiveForCleanup(meta, scannedAt)
+    })
+    .map(([worktreeId, meta]) => {
+      const parsed = splitWorktreeId(worktreeId)
+      const path = parsed?.worktreePath ?? worktreeId
+      const reasons = getInactivityReasons(meta, scannedAt)
+      return applyWorkspaceCleanupPolicy({
+        worktreeId,
+        repoId: repo.id,
+        repoName: repo.displayName,
+        connectionId: repo.connectionId ?? null,
+        displayName: meta.displayName || basename(path),
+        branch: basename(path),
+        path,
+        tier: 'protected',
+        selectedByDefault: false,
+        reasons,
+        blockers: ['ssh-disconnected'],
+        lastActivityAt: meta.lastActivityAt,
+        ...(meta.createdAt !== undefined ? { createdAt: meta.createdAt } : {}),
+        localContext: {
+          terminalTabCount: 0,
+          cleanEditorTabCount: 0,
+          browserTabCount: 0,
+          diffCommentCount: meta.diffComments?.length ?? 0,
+          newestDiffCommentAt: getNewestDiffCommentAt(meta.diffComments),
+          retainedDoneAgentCount: 0
+        },
+        git: {
+          clean: null,
+          upstreamAhead: null,
+          upstreamBehind: null,
+          checkedAt: null
+        },
+        fingerprint: createWorkspaceCleanupFingerprint({
+          branch: basename(path),
+          head: '',
+          gitClean: null,
+          lastActivityAt: meta.lastActivityAt
+        })
+      })
+    })
+}
+
+function buildLocalContext(worktree: Worktree): WorkspaceCleanupCandidate['localContext'] {
+  return {
+    terminalTabCount: 0,
+    cleanEditorTabCount: 0,
+    browserTabCount: 0,
+    diffCommentCount: worktree.diffComments?.length ?? 0,
+    newestDiffCommentAt: getNewestDiffCommentAt(worktree.diffComments),
+    retainedDoneAgentCount: 0
+  }
+}
+
+function getNewestDiffCommentAt(diffComments: Worktree['diffComments'] | undefined): number | null {
+  if (!diffComments || diffComments.length === 0) {
+    return null
+  }
+  return Math.max(...diffComments.map((comment) => comment.createdAt))
+}
+
+function createEmptyGitEvidence(): GitEvidence {
+  return {
+    clean: null,
+    upstreamAhead: null,
+    upstreamBehind: null,
+    checkedAt: null,
+    blockers: []
+  }
+}
+
+function shortBranchName(branch: string): string {
+  return branch.replace(/^refs\/heads\//, '') || 'HEAD'
+}
+
+function uniqueBlockers(blockers: WorkspaceCleanupBlocker[]): WorkspaceCleanupBlocker[] {
+  return [...new Set(blockers)]
+}
+
+function uniqueReasons(reasons: WorkspaceCleanupReason[]): WorkspaceCleanupReason[] {
+  return [...new Set(reasons)]
+}
+
+function isWorkspaceInactiveForCleanup(
+  workspace: Pick<Worktree, 'isArchived' | 'lastActivityAt'>,
+  scannedAt: number
+): boolean {
+  return isWorkspaceOldForCleanup(workspace, scannedAt)
+}
+
+function getInactivityReasons(
+  workspace: Pick<Worktree, 'isArchived' | 'lastActivityAt'>,
+  scannedAt: number
+): WorkspaceCleanupReason[] {
+  return getWorkspaceCleanupInactivityReasons(workspace, scannedAt)
+}
+
+async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = []
+  let nextIndex = 0
+  const workerCount = Math.min(limit, items.length)
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (nextIndex < items.length) {
+        const index = nextIndex
+        nextIndex += 1
+        results[index] = await fn(items[index])
+      }
+    })
+  )
+  return results
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+  let timeoutId: NodeJS.Timeout | undefined
+  const timeoutPromise = new Promise<T>((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error(message)), timeoutMs)
+  })
+  try {
+    return await Promise.race([promise, timeoutPromise])
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function createScanError(repo: Repo, message: string): WorkspaceCleanupScanError {
+  return {
+    repoId: repo.id,
+    repoName: repo.displayName || basename(repo.path),
+    message
+  }
+}
+
+// Why: git errors often include absolute paths or command output. Keep the
+// cause useful without leaking raw local/remote filesystem details to the UI.
+function toSafeRepoScanError(error: unknown): string {
+  const message = toErrorMessage(error)
+  if (message === 'Timed out listing SSH worktrees.') {
+    return 'Timed out listing remote worktrees.'
+  }
+  if (message === 'Timed out listing worktrees.') {
+    return 'Timed out listing worktrees.'
+  }
+  if (message.startsWith('Timed out ')) {
+    return message.replace(/\.$/, '')
+  }
+
+  const lower = message.toLowerCase()
+  if (lower.includes('not a git repository') || lower.includes('not a git worktree')) {
+    return 'Repository is not a git checkout.'
+  }
+  if (
+    lower.includes('enoent') ||
+    lower.includes('no such file') ||
+    lower.includes('cannot find') ||
+    lower.includes('does not exist')
+  ) {
+    return 'Repository folder was not found.'
+  }
+  if (lower.includes('eacces') || lower.includes('eperm') || lower.includes('permission denied')) {
+    return 'Repository folder is not accessible.'
+  }
+  return 'Git could not list worktrees.'
+}
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index d589fbeab65..f52bc0ebcfa 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -6466,6 +6466,23 @@ export class OrcaRuntimeService {
     return { stopped }
   }
 
+  async hasTerminalsForWorktree(worktreeSelector: string): Promise<boolean> {
+    const graphEpoch = this.captureReadyGraphEpoch()
+    const worktree = await this.resolveWorktreeSelector(worktreeSelector)
+    this.assertStableReadyGraph(graphEpoch)
+    for (const leaf of this.leaves.values()) {
+      if (leaf.worktreeId === worktree.id && leaf.ptyId) {
+        return true
+      }
+    }
+    for (const pty of this.ptysById.values()) {
+      if (pty.worktreeId === worktree.id && pty.connected) {
+        return true
+      }
+    }
+    return false
+  }
+
   markRendererReloading(windowId: number): void {
     if (windowId !== this.authoritativeWindowId) {
       return
diff --git a/src/main/window/attach-main-window-services.test.ts b/src/main/window/attach-main-window-services.test.ts
index 1a11ddd2f69..24c9afc1839 100644
--- a/src/main/window/attach-main-window-services.test.ts
+++ b/src/main/window/attach-main-window-services.test.ts
@@ -61,6 +61,7 @@ vi.mock('../ipc/worktrees', () => ({
 }))
 
 vi.mock('../ipc/pty', () => ({
+  getLocalPtyProvider: vi.fn(),
   registerPtyHandlers: registerPtyHandlersMock
 }))
 
diff --git a/src/main/window/attach-main-window-services.ts b/src/main/window/attach-main-window-services.ts
index 6bc943dec84..32389c5c704 100644
--- a/src/main/window/attach-main-window-services.ts
+++ b/src/main/window/attach-main-window-services.ts
@@ -10,7 +10,8 @@ import type { CreateWorktreeResult, WorktreeStartupLaunch } from '../../shared/t
 import { ORCA_BROWSER_PARTITION } from '../../shared/constants'
 import { registerRepoHandlers } from '../ipc/repos'
 import { registerWorktreeHandlers } from '../ipc/worktrees'
-import { registerPtyHandlers } from '../ipc/pty'
+import { registerWorkspaceCleanupHandlers } from '../ipc/workspace-cleanup'
+import { getLocalPtyProvider, registerPtyHandlers } from '../ipc/pty'
 import { registerDaemonManagementHandlers } from '../ipc/pty-management'
 import { registerSshHandlers } from '../ipc/ssh'
 import { registerRemoteWorkspaceHandlers } from '../ipc/remote-workspace'
@@ -44,6 +45,7 @@ export function attachMainWindowServices(
 ): void {
   registerRepoHandlers(mainWindow, store)
   registerWorktreeHandlers(mainWindow, store, runtime)
+  registerWorkspaceCleanupHandlers(store, { runtime, getLocalPtyProvider })
   registerPtyHandlers(
     mainWindow,
     runtime,
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 828d0be1c44..df7aaa2b59c 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -229,6 +229,13 @@ import type {
   AutomationRun,
   AutomationUpdateInput
 } from '../shared/automations-types'
+import type {
+  WorkspaceCleanupDismissArgs,
+  WorkspaceCleanupLocalProcessArgs,
+  WorkspaceCleanupLocalProcessResult,
+  WorkspaceCleanupScanArgs,
+  WorkspaceCleanupScanResult
+} from '../shared/workspace-cleanup'
 
 export type BrowserApi = {
   registerGuest: (args: {
@@ -552,6 +559,14 @@ export type PreloadApi = {
       callback: (data: WorktreeRemoteBranchConflictEvent) => void
     ) => () => void
   }
+  workspaceCleanup: {
+    scan: (args?: WorkspaceCleanupScanArgs) => Promise<WorkspaceCleanupScanResult>
+    dismiss: (args: WorkspaceCleanupDismissArgs) => Promise<void>
+    clearDismissals: () => Promise<void>
+    hasKillableLocalProcesses: (
+      args: WorkspaceCleanupLocalProcessArgs
+    ) => Promise<WorkspaceCleanupLocalProcessResult>
+  }
   workspaceSpace: {
     analyze: () => Promise<WorkspaceSpaceAnalyzeResult>
     cancel: () => Promise<boolean>
diff --git a/src/preload/index.ts b/src/preload/index.ts
index a45f433e6ee..e7330fd1b9c 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -494,6 +494,19 @@ const api = {
     }
   },
 
+  workspaceCleanup: {
+    scan: (args?: { worktreeId?: string; skipGitWorktreeIds?: string[] }): Promise<unknown> =>
+      ipcRenderer.invoke('workspaceCleanup:scan', args),
+    dismiss: (args: { dismissals: unknown[] }): Promise<void> =>
+      ipcRenderer.invoke('workspaceCleanup:dismiss', args),
+    clearDismissals: (): Promise<void> => ipcRenderer.invoke('workspaceCleanup:clearDismissals'),
+    hasKillableLocalProcesses: (args: {
+      worktreeId: string
+      connectionId?: string | null
+      worktreePath?: string
+    }): Promise<unknown> => ipcRenderer.invoke('workspaceCleanup:hasKillableLocalProcesses', args)
+  },
+
   workspaceSpace: {
     analyze: (): Promise<WorkspaceSpaceAnalyzeResult> =>
       ipcRenderer.invoke('workspaceSpace:analyze'),
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 83fa72b75bd..6a7a0e96053 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -165,6 +165,9 @@ const WorkspaceSpacePage = lazy(() => import('./components/workspace-space/Works
 const QuickOpen = lazy(() => import('./components/QuickOpen'))
 const WorktreeJumpPalette = lazy(() => import('./components/WorktreeJumpPalette'))
 const NewWorkspaceComposerModal = lazy(() => import('./components/NewWorkspaceComposerModal'))
+const WorkspaceCleanupDialog = lazy(
+  () => import('./components/workspace-cleanup/WorkspaceCleanupDialog')
+)
 const FeatureWallModal = lazy(() => import('./components/feature-wall/FeatureWallModal'))
 // Why: lazy-loaded so the WebP asset + overlay module aren't fetched unless
 // the user opts into the experimental flag.
@@ -1045,6 +1048,7 @@ function App(): React.JSX.Element {
       activeModal !== 'quick-open' &&
       activeModal !== 'worktree-palette' &&
       activeModal !== 'new-workspace-composer' &&
+      activeModal !== 'workspace-cleanup' &&
       activeModal !== 'feature-wall'
     ) {
       return
@@ -1408,6 +1412,7 @@ function App(): React.JSX.Element {
             whether triggered from Cmd+J or any future entry point. */}
         <Suspense fallback={null}>
           {mountedLazyModalIds.has('new-workspace-composer') ? <NewWorkspaceComposerModal /> : null}
+          {mountedLazyModalIds.has('workspace-cleanup') ? <WorkspaceCleanupDialog /> : null}
         </Suspense>
       </TooltipProvider>
       <Suspense fallback={null}>
diff --git a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
index 213a0de60d9..a904e9796db 100644
--- a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
@@ -7,6 +7,7 @@
 import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
   AlertTriangle,
+  ArchiveX,
   ChevronDown,
   ChevronRight,
   LoaderCircle,
@@ -32,12 +33,14 @@ import { cn } from '@/lib/utils'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { activateTabAndFocusPane } from '@/lib/activate-tab-and-focus-pane'
 import { useAppStore } from '../../store'
-import { useWorktreeMap } from '../../store/selectors'
+import { useAllWorktrees, useWorktreeMap } from '../../store/selectors'
 import { runWorktreeDelete } from '../sidebar/delete-worktree-flow'
 import { runSleepWorktree } from '../sidebar/sleep-worktree-flow'
 import { useDaemonActions, DaemonActionDialog } from '../shared/useDaemonActions'
 import type { AppMemory, UsageValues, Worktree } from '../../../../shared/types'
 import { ORPHAN_WORKTREE_ID } from '../../../../shared/constants'
+import { isFolderRepo } from '../../../../shared/repo-kind'
+import { isWorkspaceOldForCleanup } from '../../../../shared/workspace-cleanup'
 import { parsePaneKey } from '../../../../shared/stable-pane-id'
 import {
   mergeSnapshotAndSessions,
@@ -656,8 +659,10 @@ export function ResourceUsageStatusSegment({
   const tabsByWorktree = useAppStore((s) => s.tabsByWorktree)
   const runtimePaneTitlesByTabId = useAppStore((s) => s.runtimePaneTitlesByTabId)
   const setActiveView = useAppStore((s) => s.setActiveView)
+  const openModal = useAppStore((s) => s.openModal)
   const openSpacePage = useAppStore((s) => s.openSpacePage)
   const repos = useAppStore((s) => s.repos)
+  const allWorktrees = useAllWorktrees()
   const activeRuntimeEnvironmentId = useAppStore(
     (s) => s.settings?.activeRuntimeEnvironmentId ?? null
   )
@@ -778,6 +783,23 @@ export function ResourceUsageStatusSegment({
     return map
   }, [repos])
 
+  const repoById = useMemo(() => new Map(repos.map((repo) => [repo.id, repo])), [repos])
+
+  const oldWorkspaceCount = useMemo(() => {
+    const now = Date.now()
+    let count = 0
+    for (const worktree of allWorktrees) {
+      const repo = repoById.get(worktree.repoId)
+      if (!repo || isFolderRepo(repo) || worktree.isMainWorktree) {
+        continue
+      }
+      if (isWorkspaceOldForCleanup(worktree, now)) {
+        count += 1
+      }
+    }
+    return count
+  }, [allWorktrees, repoById])
+
   // Why: skip the merge entirely when the popover is closed. The merged
   // tree is only ever displayed inside <PopoverContent>; computing it on
   // every store mutation (e.g. runtimePaneTitlesByTabId, which changes on
@@ -926,6 +948,11 @@ export function ResourceUsageStatusSegment({
     void runSleepWorktree(id)
   }, [])
 
+  const handleOpenWorkspaceCleanup = useCallback((): void => {
+    setOpen(false)
+    queueMicrotask(() => openModal('workspace-cleanup'))
+  }, [openModal])
+
   const handleKillSession = useCallback(
     (session: UnifiedSessionRow): void => {
       // Why: orphan sessions have no tab in this Orca instance, so there's
@@ -1294,17 +1321,28 @@ export function ResourceUsageStatusSegment({
           </div>
         </div>
 
-        {orphanCount > 0 && (
-          <div className="border-t border-border/50 px-3 py-2 shrink-0">
+        <div className="border-t border-border/50 px-3 py-2 shrink-0">
+          <button
+            type="button"
+            onClick={handleOpenWorkspaceCleanup}
+            className="inline-flex w-full items-center justify-between gap-2 rounded-md border border-border/70 px-2.5 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-accent/60"
+          >
+            <span className="inline-flex min-w-0 items-center gap-1.5">
+              <ArchiveX className="size-3.5 shrink-0" />
+              <span className="truncate">Clean up old workspaces ({oldWorkspaceCount})</span>
+            </span>
+            <ChevronRight className="size-3.5 shrink-0 text-muted-foreground" aria-hidden />
+          </button>
+          {orphanCount > 0 ? (
             <button
               type="button"
               onClick={() => void handleKillOrphans()}
-              className="inline-flex w-full items-center justify-center rounded-md border border-border/70 px-2.5 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-accent/60"
+              className="mt-2 inline-flex w-full items-center justify-center rounded-md border border-border/70 px-2.5 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-accent/60"
             >
               Kill {orphanCount} orphan terminal{orphanCount === 1 ? '' : 's'}
             </button>
-          </div>
-        )}
+          ) : null}
+        </div>
 
         <WorkspaceSpaceCompactPanel onOpenFullPage={openSpaceResults} />
       </PopoverContent>
diff --git a/src/renderer/src/components/workspace-cleanup/WorkspaceCleanupDialog.tsx b/src/renderer/src/components/workspace-cleanup/WorkspaceCleanupDialog.tsx
new file mode 100644
index 00000000000..212da4f0370
--- /dev/null
+++ b/src/renderer/src/components/workspace-cleanup/WorkspaceCleanupDialog.tsx
@@ -0,0 +1,980 @@
+/* eslint-disable max-lines */
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import {
+  AlertTriangle,
+  Check,
+  EyeOff,
+  Loader2,
+  Minus,
+  RefreshCcw,
+  Search,
+  Trash2,
+  X
+} from 'lucide-react'
+import { toast } from 'sonner'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '@/components/ui/dialog'
+import { Button } from '@/components/ui/button'
+import { ScrollArea } from '@/components/ui/scroll-area'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { useAppStore } from '@/store'
+import { cn } from '@/lib/utils'
+import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import {
+  canQueueWorkspaceCleanupCandidate,
+  type WorkspaceCleanupBlocker,
+  type WorkspaceCleanupCandidate,
+  type WorkspaceCleanupScanError,
+  type WorkspaceCleanupTier
+} from '../../../../shared/workspace-cleanup'
+
+const TIER_LABELS: Record<WorkspaceCleanupTier, string> = {
+  ready: 'Suggested cleanup',
+  review: 'Needs a closer look',
+  protected: 'Not suggested for cleanup'
+}
+
+type CleanupView = WorkspaceCleanupTier | 'hidden'
+
+const BLOCKER_LABELS: Record<WorkspaceCleanupBlocker, string> = {
+  'main-worktree': 'Main workspace',
+  'folder-repo': 'Folder project',
+  pinned: 'Pinned',
+  'active-workspace': 'Active workspace',
+  'running-terminal': 'Running terminal process',
+  'terminal-liveness-unknown': 'Terminal liveness unknown',
+  'dirty-editor-buffer': 'Unsaved editor buffer',
+  'volatile-local-context': 'Volatile local context',
+  'recent-visible-context': 'Recently visited tabs',
+  'live-agent': 'Active agent',
+  'ssh-disconnected': 'Remote unavailable',
+  'git-status-error': 'Git status unavailable',
+  'dirty-files': 'Changed files',
+  'unpushed-commits': 'Unpushed commits',
+  'unknown-base': 'Could not verify unpushed commits',
+  dismissed: 'Ignored'
+}
+
+function formatRelativeTime(timestamp: number): string {
+  if (!timestamp) {
+    return 'Never'
+  }
+  const deltaMs = Date.now() - timestamp
+  if (deltaMs < 60_000) {
+    return 'Just now'
+  }
+  const minutes = Math.floor(deltaMs / 60_000)
+  if (minutes < 60) {
+    return `${minutes}m ago`
+  }
+  const hours = Math.floor(minutes / 60)
+  if (hours < 48) {
+    return `${hours}h ago`
+  }
+  return `${Math.floor(hours / 24)}d ago`
+}
+
+function isDisconnectedRemoteScanError(message: string): boolean {
+  return (
+    message === 'SSH provider is unavailable.' ||
+    message === 'Remote workspaces are not connected. Reconnect and refresh to check them.'
+  )
+}
+
+function formatScanNoticeMessage(
+  errors: WorkspaceCleanupScanError[],
+  repoNameById: Map<string, string>
+): string | null {
+  const visibleErrors = errors.filter(
+    (error) => !isDisconnectedRemoteScanError(error.message ?? '')
+  )
+  if (visibleErrors.length === 0) {
+    return null
+  }
+  if (visibleErrors.length === 1) {
+    const error = visibleErrors[0]
+    const repoName = formatScanErrorRepoName(error, repoNameById)
+    return `Could not check ${repoName}: ${formatScanErrorReason(error.message)}. Some old workspaces may be missing. Refresh to try again.`
+  }
+  const repoNames = visibleErrors
+    .slice(0, 3)
+    .map((error) => formatScanErrorRepoName(error, repoNameById))
+    .join(', ')
+  const moreCount = visibleErrors.length - 3
+  const suffix = moreCount > 0 ? `, +${moreCount} more` : ''
+  return `Could not check ${visibleErrors.length} repositories (${repoNames}${suffix}). Some old workspaces may be missing. Refresh to try again.`
+}
+
+function formatScanErrorRepoName(
+  error: Partial<WorkspaceCleanupScanError>,
+  repoNameById: Map<string, string>
+): string {
+  const repoName = error.repoName?.trim()
+  if (repoName) {
+    return repoName
+  }
+  const fallback = error.repoId ? repoNameById.get(error.repoId)?.trim() : ''
+  return fallback || 'a repository'
+}
+
+function formatScanErrorReason(message: string | undefined): string {
+  if (!message) {
+    return 'Git could not list worktrees'
+  }
+  if (message === 'Could not scan workspace cleanup for this repository.') {
+    return 'Git could not list worktrees'
+  }
+  return message.replace(/\.$/, '')
+}
+
+function isOldWorkspaceCandidate(candidate: WorkspaceCleanupCandidate): boolean {
+  if (candidate.blockers.includes('main-worktree') || candidate.blockers.includes('folder-repo')) {
+    return false
+  }
+  return candidate.reasons.includes('archived') || candidate.reasons.includes('idle-clean')
+}
+
+function compareCleanupCandidates(
+  a: WorkspaceCleanupCandidate,
+  b: WorkspaceCleanupCandidate
+): number {
+  const priorityA = getCleanupCandidatePriority(a)
+  const priorityB = getCleanupCandidatePriority(b)
+  if (priorityA !== priorityB) {
+    return priorityA - priorityB
+  }
+  return a.lastActivityAt - b.lastActivityAt
+}
+
+function getCleanupCandidatePriority(candidate: WorkspaceCleanupCandidate): number {
+  if (candidate.tier === 'ready') {
+    return 0
+  }
+  if (candidate.reasons.length > 0) {
+    return 1
+  }
+  if (isOldWorkspaceCandidate(candidate)) {
+    return 2
+  }
+  return 3
+}
+
+export default function WorkspaceCleanupDialog(): React.JSX.Element {
+  const activeModal = useAppStore((s) => s.activeModal)
+  const closeModal = useAppStore((s) => s.closeModal)
+  const scan = useAppStore((s) => s.workspaceCleanupScan)
+  const loading = useAppStore((s) => s.workspaceCleanupLoading)
+  const error = useAppStore((s) => s.workspaceCleanupError)
+  const repos = useAppStore((s) => s.repos)
+  const scanWorkspaceCleanup = useAppStore((s) => s.scanWorkspaceCleanup)
+  const markCandidateViewed = useAppStore((s) => s.markWorkspaceCleanupCandidateViewed)
+  const dismissCandidates = useAppStore((s) => s.dismissWorkspaceCleanupCandidates)
+  const resetDismissals = useAppStore((s) => s.resetWorkspaceCleanupDismissals)
+  const removeCandidates = useAppStore((s) => s.removeWorkspaceCleanupCandidates)
+
+  const open = activeModal === 'workspace-cleanup'
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(() => new Set())
+  const [activeView, setActiveView] = useState<CleanupView>('ready')
+  const [confirming, setConfirming] = useState(false)
+  const [removing, setRemoving] = useState(false)
+  const [rowFailures, setRowFailures] = useState<Record<string, string>>({})
+
+  useEffect(() => {
+    if (open) {
+      setRowFailures({})
+      setActiveView('ready')
+      void scanWorkspaceCleanup().catch((err: unknown) => {
+        toast.error('Workspace cleanup scan failed', {
+          description: err instanceof Error ? err.message : String(err)
+        })
+      })
+    }
+  }, [open, scanWorkspaceCleanup])
+
+  const candidates = useMemo(() => scan?.candidates ?? [], [scan?.candidates])
+
+  useEffect(() => {
+    if (!open || !scan) {
+      return
+    }
+    setSelectedIds(
+      new Set(
+        candidates
+          .filter((candidate) => candidate.selectedByDefault)
+          .map((candidate) => candidate.worktreeId)
+      )
+    )
+    setConfirming(false)
+  }, [open, scan, scan?.scannedAt, candidates])
+
+  const visibleCandidates = useMemo(() => {
+    const rows = candidates.filter((candidate) => !candidate.blockers.includes('dismissed'))
+    return [...rows].sort(compareCleanupCandidates)
+  }, [candidates])
+  const hiddenCandidates = useMemo(
+    () =>
+      candidates
+        .filter((candidate) => candidate.blockers.includes('dismissed'))
+        .sort(compareCleanupCandidates),
+    [candidates]
+  )
+  const groups = useMemo(
+    () => ({
+      ready: visibleCandidates.filter((candidate) => candidate.tier === 'ready'),
+      review: visibleCandidates.filter((candidate) => candidate.tier === 'review'),
+      protected: visibleCandidates.filter((candidate) => candidate.tier === 'protected')
+    }),
+    [visibleCandidates]
+  )
+  const selectedCandidates = useMemo(() => {
+    const byId = new Map(candidates.map((candidate) => [candidate.worktreeId, candidate]))
+    return [...selectedIds]
+      .map((id) => byId.get(id))
+      .filter(
+        (candidate): candidate is WorkspaceCleanupCandidate =>
+          candidate != null && canQueueWorkspaceCleanupCandidate(candidate)
+      )
+  }, [candidates, selectedIds])
+
+  const hiddenByKeepCount = candidates.filter((candidate) =>
+    candidate.blockers.includes('dismissed')
+  ).length
+  const repoNameById = useMemo(
+    () => new Map(repos.map((repo) => [repo.id, repo.displayName || repo.path])),
+    [repos]
+  )
+  const scanNoticeMessage = useMemo(
+    () => formatScanNoticeMessage(scan?.errors ?? [], repoNameById),
+    [repoNameById, scan?.errors]
+  )
+  const readyCount = groups.ready.length
+  const oldCandidateCount = useMemo(
+    () => candidates.filter(isOldWorkspaceCandidate).length,
+    [candidates]
+  )
+  const initialLoading = loading && !scan
+  const activeRows = activeView === 'hidden' ? hiddenCandidates : groups[activeView]
+  const activeQueueableRows = useMemo(
+    () => activeRows.filter(canQueueWorkspaceCleanupCandidate),
+    [activeRows]
+  )
+  const activeQueueableSelected = useMemo(
+    () => activeQueueableRows.filter((candidate) => selectedIds.has(candidate.worktreeId)).length,
+    [activeQueueableRows, selectedIds]
+  )
+  const allActiveQueueableSelected =
+    activeQueueableRows.length > 0 && activeQueueableSelected === activeQueueableRows.length
+  const someActiveQueueableSelected = activeQueueableSelected > 0
+  const activeSelectionState = allActiveQueueableSelected
+    ? 'checked'
+    : someActiveQueueableSelected
+      ? 'mixed'
+      : 'unchecked'
+
+  useEffect(() => {
+    if (!open || loading || !scan) {
+      return
+    }
+    if (activeRows.length > 0) {
+      return
+    }
+    if (readyCount > 0) {
+      setActiveView('ready')
+    } else if (groups.review.length > 0) {
+      setActiveView('review')
+    } else if (groups.protected.length > 0) {
+      setActiveView('protected')
+    } else if (hiddenCandidates.length > 0) {
+      setActiveView('hidden')
+    }
+  }, [
+    activeRows.length,
+    groups.protected.length,
+    groups.review.length,
+    hiddenCandidates.length,
+    loading,
+    open,
+    readyCount,
+    scan
+  ])
+
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (!nextOpen && !removing) {
+        closeModal()
+      }
+    },
+    [closeModal, removing]
+  )
+
+  const refresh = useCallback(() => {
+    setRowFailures({})
+    void scanWorkspaceCleanup().catch((err: unknown) => {
+      toast.error('Workspace cleanup scan failed', {
+        description: err instanceof Error ? err.message : String(err)
+      })
+    })
+  }, [scanWorkspaceCleanup])
+
+  const toggleActiveSelection = useCallback(() => {
+    if (activeQueueableRows.length === 0) {
+      return
+    }
+    setSelectedIds((current) => {
+      const next = new Set(current)
+      if (allActiveQueueableSelected) {
+        for (const candidate of activeQueueableRows) {
+          next.delete(candidate.worktreeId)
+        }
+      } else {
+        for (const candidate of activeQueueableRows) {
+          next.add(candidate.worktreeId)
+        }
+      }
+      return next
+    })
+  }, [activeQueueableRows, allActiveQueueableSelected])
+
+  const ignoreCandidate = useCallback(
+    (candidate: WorkspaceCleanupCandidate) => {
+      void dismissCandidates([candidate])
+        .then(() => {
+          setSelectedIds((current) => {
+            const next = new Set(current)
+            next.delete(candidate.worktreeId)
+            return next
+          })
+        })
+        .catch((err: unknown) => {
+          toast.error('Could not ignore cleanup suggestion', {
+            description: err instanceof Error ? err.message : String(err)
+          })
+        })
+    },
+    [dismissCandidates]
+  )
+
+  const confirmRemove = useCallback(async () => {
+    if (selectedCandidates.length === 0) {
+      return
+    }
+    setRemoving(true)
+    setRowFailures({})
+    try {
+      const result = await removeCandidates(
+        selectedCandidates.map((candidate) => candidate.worktreeId)
+      )
+      const nextFailures: Record<string, string> = {}
+      for (const failure of result.failures) {
+        nextFailures[failure.worktreeId] = failure.message
+      }
+      setRowFailures(nextFailures)
+      setSelectedIds((current) => {
+        const next = new Set(current)
+        for (const id of result.removedIds) {
+          next.delete(id)
+        }
+        return next
+      })
+      if (result.removedIds.length > 0) {
+        toast.success(
+          `Removed ${result.removedIds.length} workspace${result.removedIds.length === 1 ? '' : 's'}`
+        )
+      }
+      if (result.failures.length > 0) {
+        toast.error(
+          `${result.failures.length} workspace${result.failures.length === 1 ? '' : 's'} could not be removed`
+        )
+      } else {
+        setConfirming(false)
+      }
+    } finally {
+      setRemoving(false)
+    }
+  }, [removeCandidates, selectedCandidates])
+
+  const selectedCount = selectedCandidates.length
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent
+        showCloseButton={false}
+        className="flex h-[min(820px,90vh)] w-[calc(100vw-3rem)] max-w-[calc(100vw-3rem)] flex-col gap-0 overflow-hidden p-0 sm:max-w-[calc(100vw-3rem)] xl:w-[920px] xl:max-w-[920px]"
+      >
+        {!confirming ? (
+          <>
+            <DialogHeader className="border-b border-border px-5 py-4">
+              <div className="flex items-start justify-between gap-4">
+                <div className="min-w-0">
+                  <DialogTitle className="text-base">Clean Up Old Workspaces</DialogTitle>
+                  <DialogDescription className="mt-1 text-xs">
+                    Review old workspaces before deleting their local files and Orca state.
+                  </DialogDescription>
+                </div>
+                <div className="flex shrink-0 items-center gap-2">
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        variant="outline"
+                        size="icon-sm"
+                        aria-label="Refresh"
+                        onClick={refresh}
+                        disabled={loading}
+                      >
+                        <RefreshCcw className={cn('size-3.5', loading && 'animate-spin')} />
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent side="bottom" sideOffset={4}>
+                      Refresh
+                    </TooltipContent>
+                  </Tooltip>
+                  <Button
+                    variant="ghost"
+                    size="icon-sm"
+                    aria-label="Close"
+                    onClick={() => closeModal()}
+                    disabled={removing}
+                  >
+                    <X className="size-4" />
+                  </Button>
+                </div>
+              </div>
+            </DialogHeader>
+
+            {initialLoading ? (
+              <div className="flex items-center gap-2 border-b border-border bg-muted/25 px-5 py-3 text-xs text-muted-foreground">
+                <Loader2 className="size-3.5 animate-spin" />
+                Checking old workspaces
+              </div>
+            ) : oldCandidateCount > 0 || hiddenByKeepCount > 0 ? (
+              <div className="flex flex-wrap items-center justify-between gap-3 border-b border-border bg-muted/25 px-4 py-2.5">
+                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                  <div className="min-w-0 text-sm font-medium text-foreground">
+                    {selectedCount} selected
+                  </div>
+                  {readyCount > 0 ? (
+                    <StatusPill tone="ready">{readyCount} safe to remove</StatusPill>
+                  ) : null}
+                  {groups.review.length > 0 ? (
+                    <StatusPill tone="review">{groups.review.length} need review</StatusPill>
+                  ) : null}
+                </div>
+                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                  <Button
+                    variant="destructive"
+                    size="sm"
+                    onClick={() => setConfirming(true)}
+                    disabled={selectedCount === 0}
+                  >
+                    <Trash2 className="size-3.5" />
+                    Remove selected
+                  </Button>
+                </div>
+              </div>
+            ) : null}
+
+            {error ? (
+              <div className="border-b border-destructive/30 bg-destructive/10 px-5 py-2 text-xs text-destructive">
+                {error}
+              </div>
+            ) : scanNoticeMessage ? (
+              <div className="flex items-center gap-2 border-b border-border bg-muted/25 px-5 py-2 text-xs text-muted-foreground">
+                <AlertTriangle className="size-3.5 shrink-0" />
+                <span>{scanNoticeMessage}</span>
+              </div>
+            ) : null}
+
+            <div className="grid min-h-0 flex-1 grid-cols-1 overflow-hidden md:grid-cols-[185px_minmax(0,1fr)]">
+              <CleanupViewNav
+                activeView={activeView}
+                counts={{
+                  ready: groups.ready.length,
+                  review: groups.review.length,
+                  protected: groups.protected.length,
+                  hidden: hiddenByKeepCount
+                }}
+                onViewChange={setActiveView}
+              />
+              <div className="flex min-w-0 flex-col border-t border-border md:border-l md:border-t-0">
+                <div className="flex min-h-10 items-center justify-between gap-3 border-b border-border px-3 py-2">
+                  <div className="flex min-w-0 items-center gap-2">
+                    {activeView !== 'hidden' && activeQueueableRows.length > 0 ? (
+                      <button
+                        type="button"
+                        role="checkbox"
+                        aria-checked={
+                          activeSelectionState === 'mixed' ? 'mixed' : allActiveQueueableSelected
+                        }
+                        aria-label={
+                          allActiveQueueableSelected
+                            ? `Unselect all in ${TIER_LABELS[activeView]}`
+                            : `Select all in ${TIER_LABELS[activeView]}`
+                        }
+                        onClick={toggleActiveSelection}
+                        className="flex size-4 shrink-0 items-center justify-center rounded border border-border bg-background text-primary hover:bg-accent"
+                      >
+                        {activeSelectionState === 'checked' ? (
+                          <Check className="size-3" strokeWidth={3} />
+                        ) : activeSelectionState === 'mixed' ? (
+                          <Minus className="size-3" strokeWidth={3} />
+                        ) : null}
+                      </button>
+                    ) : null}
+                    <div className="min-w-0 truncate text-[11px] font-semibold uppercase tracking-[0.05em] text-muted-foreground">
+                      {activeView === 'hidden'
+                        ? 'Ignored cleanup suggestions'
+                        : TIER_LABELS[activeView]}
+                    </div>
+                  </div>
+                  {activeView === 'hidden' && hiddenByKeepCount > 0 ? (
+                    <Button
+                      variant="link"
+                      size="xs"
+                      className="h-auto shrink-0 px-0 text-xs"
+                      onClick={() => void resetDismissals()}
+                    >
+                      Restore ignored suggestions
+                    </Button>
+                  ) : (
+                    <div className="shrink-0 text-xs text-muted-foreground">
+                      Sorted by oldest activity
+                    </div>
+                  )}
+                </div>
+                <ScrollArea className="min-h-0 flex-1">
+                  <div>
+                    {initialLoading ? <SkeletonRows /> : null}
+                    {!loading && scan && candidates.length === 0 && !scanNoticeMessage ? (
+                      <EmptyState title="No old workspaces to clean up." />
+                    ) : null}
+                    {!loading && scan && candidates.length === 0 && scanNoticeMessage ? (
+                      <EmptyState title="No old workspaces found in checked repositories." />
+                    ) : null}
+                    {!loading && scan && candidates.length > 0 && visibleCandidates.length === 0 ? (
+                      <EmptyState
+                        title="All cleanup suggestions are ignored."
+                        actionLabel="Review ignored workspaces"
+                        onAction={() => setActiveView('hidden')}
+                      />
+                    ) : null}
+                    {!loading && scan && activeRows.length === 0 && visibleCandidates.length > 0 ? (
+                      <EmptyState title="No workspaces in this cleanup set." />
+                    ) : null}
+                    {activeRows.map((candidate, index) => (
+                      <CandidateRow
+                        key={candidate.worktreeId}
+                        candidate={candidate}
+                        last={index === activeRows.length - 1}
+                        selected={selectedIds.has(candidate.worktreeId)}
+                        failure={rowFailures[candidate.worktreeId]}
+                        onToggleSelected={(id) =>
+                          setSelectedIds((current) => toggleSetMember(current, id))
+                        }
+                        onView={closeAndView}
+                        onIgnore={ignoreCandidate}
+                        onRemove={(candidate) => {
+                          setSelectedIds(new Set([candidate.worktreeId]))
+                          setConfirming(true)
+                        }}
+                      />
+                    ))}
+                  </div>
+                </ScrollArea>
+              </div>
+            </div>
+          </>
+        ) : (
+          <ConfirmRemove
+            count={selectedCount}
+            removing={removing}
+            onCancel={() => setConfirming(false)}
+            onConfirm={() => void confirmRemove()}
+          />
+        )}
+      </DialogContent>
+    </Dialog>
+  )
+
+  function closeAndView(candidate: WorkspaceCleanupCandidate): void {
+    markCandidateViewed(candidate)
+    closeModal()
+    activateAndRevealWorktree(candidate.worktreeId)
+  }
+}
+
+function StatusPill({
+  children,
+  tone = 'neutral'
+}: {
+  children: React.ReactNode
+  tone?: 'neutral' | 'ready' | 'review' | 'destructive'
+}): React.JSX.Element {
+  return (
+    <span
+      className={cn(
+        'inline-flex h-5 items-center rounded-full border px-2 text-[11px] font-medium',
+        tone === 'neutral' && 'border-border bg-background text-muted-foreground',
+        tone === 'ready' && 'border-border text-[var(--git-decoration-added)]',
+        tone === 'review' && 'border-border text-[var(--git-decoration-modified)]',
+        tone === 'destructive' && 'border-destructive/30 text-destructive'
+      )}
+    >
+      {children}
+    </span>
+  )
+}
+
+function CleanupViewNav({
+  activeView,
+  counts,
+  onViewChange
+}: {
+  activeView: CleanupView
+  counts: Record<CleanupView, number>
+  onViewChange: (view: CleanupView) => void
+}): React.JSX.Element {
+  const items: { view: CleanupView; label: string }[] = [
+    { view: 'ready', label: 'Suggested' },
+    { view: 'review', label: 'Needs review' },
+    { view: 'protected', label: 'Not suggested' },
+    { view: 'hidden', label: 'Ignored' }
+  ]
+
+  return (
+    <aside className="border-t border-border bg-background md:border-t-0">
+      <div className="space-y-1 p-2">
+        {items.map((item) => (
+          <button
+            key={item.view}
+            type="button"
+            className={cn(
+              'flex h-8 w-full items-center justify-between gap-2 rounded-md px-2 text-left text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground',
+              activeView === item.view && 'bg-accent text-accent-foreground'
+            )}
+            onClick={() => onViewChange(item.view)}
+          >
+            <span className="truncate">{item.label}</span>
+            <span className="tabular-nums text-muted-foreground">{counts[item.view]}</span>
+          </button>
+        ))}
+      </div>
+    </aside>
+  )
+}
+
+function CandidateRow({
+  candidate,
+  last,
+  selected,
+  failure,
+  onToggleSelected,
+  onView,
+  onIgnore,
+  onRemove
+}: {
+  candidate: WorkspaceCleanupCandidate
+  last: boolean
+  selected: boolean
+  failure?: string
+  onToggleSelected: (worktreeId: string) => void
+  onView: (candidate: WorkspaceCleanupCandidate) => void
+  onIgnore: (candidate: WorkspaceCleanupCandidate) => void
+  onRemove: (candidate: WorkspaceCleanupCandidate) => void
+}): React.JSX.Element {
+  const selectable = canQueueWorkspaceCleanupCandidate(candidate)
+  const ignored = candidate.blockers.includes('dismissed')
+  const blockers = candidate.blockers.map((blocker) => BLOCKER_LABELS[blocker])
+  const contextDetails = formatContextDetails(candidate)
+  const branchSafetyDetails = formatBranchSafetyDetails(candidate)
+  const status = getCandidateStatus(candidate)
+
+  return (
+    <div
+      className={cn(
+        'group w-full border-b border-border/60 px-3 py-3 text-left text-foreground transition-colors hover:bg-accent/40',
+        last && 'border-b-0'
+      )}
+    >
+      <div className="grid grid-cols-[auto_minmax(0,1fr)] items-start gap-x-2.5 gap-y-1 md:grid-cols-[auto_minmax(0,1fr)_auto]">
+        {selectable ? (
+          <button
+            type="button"
+            role="checkbox"
+            aria-checked={selected}
+            aria-label={`Select ${candidate.displayName}`}
+            onClick={() => onToggleSelected(candidate.worktreeId)}
+            className="mt-0.5 flex size-4 shrink-0 items-center justify-center rounded border border-border bg-background text-primary hover:bg-accent"
+          >
+            {selected ? <Check className="size-3" strokeWidth={3} /> : null}
+          </button>
+        ) : (
+          <div className="mt-0.5 size-4 shrink-0" aria-hidden="true" />
+        )}
+        <div className="min-w-0">
+          <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-0.5">
+            <span className="min-w-0 truncate text-sm font-medium">{candidate.displayName}</span>
+            <StatusPill tone={status.tone}>{status.label}</StatusPill>
+            <span className="text-xs text-muted-foreground">
+              Last active {formatRelativeTime(candidate.lastActivityAt)}
+            </span>
+            {blockers.length > 0 ? (
+              <span className="min-w-0 truncate text-xs text-muted-foreground">
+                {blockers.slice(0, 2).join(', ')}
+              </span>
+            ) : null}
+          </div>
+          <div className="mt-1 min-w-0 truncate font-mono text-[11px] text-muted-foreground">
+            {candidate.path}
+          </div>
+          <div className="mt-1 flex min-w-0 flex-wrap gap-x-3 gap-y-1 text-xs text-muted-foreground">
+            <span className="min-w-0 truncate">Repo {candidate.repoName}</span>
+            <span className="min-w-0 truncate font-mono">Branch {candidate.branch}</span>
+            <span>{formatGitStatus(candidate)}</span>
+            {branchSafetyDetails.slice(0, 1).map((detail) => (
+              <span key={detail}>{detail}</span>
+            ))}
+            {contextDetails ? <span className="min-w-0 truncate">{contextDetails}</span> : null}
+          </div>
+          {failure ? (
+            <div className="mt-2 flex items-center gap-1.5 text-xs text-destructive">
+              <AlertTriangle className="size-3.5" />
+              {failure}
+            </div>
+          ) : null}
+        </div>
+        <div className="col-start-2 flex flex-wrap items-center gap-0.5 md:col-start-auto md:justify-end">
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="ghost"
+                size="icon-xs"
+                aria-label={`View ${candidate.displayName}`}
+                onClick={() => onView(candidate)}
+              >
+                <Search className="size-3.5" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="top" sideOffset={4}>
+              View
+            </TooltipContent>
+          </Tooltip>
+          {!ignored ? (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  variant="ghost"
+                  size="icon-xs"
+                  aria-label={`Ignore ${candidate.displayName}`}
+                  onClick={() => onIgnore(candidate)}
+                >
+                  <EyeOff className="size-3.5" />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={4}>
+                Ignore
+              </TooltipContent>
+            </Tooltip>
+          ) : null}
+          {selectable ? (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  variant="ghost"
+                  size="icon-xs"
+                  aria-label={`Remove ${candidate.displayName}`}
+                  className="text-destructive hover:text-destructive"
+                  onClick={() => onRemove(candidate)}
+                >
+                  <Trash2 className="size-3.5" />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={4}>
+                Remove
+              </TooltipContent>
+            </Tooltip>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function getCandidateStatus(candidate: WorkspaceCleanupCandidate): {
+  label: string
+  tone: 'neutral' | 'ready' | 'review' | 'destructive'
+} {
+  if (candidate.blockers.includes('dismissed')) {
+    return { label: 'Ignored', tone: 'neutral' }
+  }
+  if (candidate.tier === 'ready') {
+    return { label: candidate.reasons.includes('archived') ? 'Archived' : 'Clean', tone: 'ready' }
+  }
+  if (candidate.blockers.length > 0) {
+    return { label: BLOCKER_LABELS[candidate.blockers[0]], tone: 'neutral' }
+  }
+  if (candidate.git.upstreamAhead && candidate.git.upstreamAhead > 0) {
+    return { label: 'Unpushed commits', tone: 'review' }
+  }
+  if (candidate.git.clean === false) {
+    return { label: 'Dirty', tone: 'review' }
+  }
+  if (candidate.tier === 'review') {
+    return { label: 'Review', tone: 'review' }
+  }
+  return { label: 'Not suggested', tone: 'neutral' }
+}
+
+function formatGitStatus(candidate: WorkspaceCleanupCandidate): string {
+  if (candidate.git.clean === true) {
+    return 'Clean git'
+  }
+  if (candidate.git.clean === false) {
+    return 'Dirty git'
+  }
+  return 'Git unknown'
+}
+
+function formatBranchSafetyDetails(candidate: WorkspaceCleanupCandidate): string[] {
+  const details: string[] = []
+  if (candidate.git.upstreamAhead !== null) {
+    details.push(
+      candidate.git.upstreamAhead === 0
+        ? 'No unpushed commits'
+        : `${candidate.git.upstreamAhead} unpushed commit${
+            candidate.git.upstreamAhead === 1 ? '' : 's'
+          }`
+    )
+  }
+  return details
+}
+
+function formatContextDetails(candidate: WorkspaceCleanupCandidate): string | null {
+  const parts: string[] = []
+  if (candidate.localContext.terminalTabCount > 0) {
+    parts.push(
+      `${candidate.localContext.terminalTabCount} terminal tab${
+        candidate.localContext.terminalTabCount === 1 ? '' : 's'
+      }`
+    )
+  }
+  if (candidate.localContext.cleanEditorTabCount > 0) {
+    parts.push(
+      `${candidate.localContext.cleanEditorTabCount} editor tab${
+        candidate.localContext.cleanEditorTabCount === 1 ? '' : 's'
+      }`
+    )
+  }
+  if (candidate.localContext.browserTabCount > 0) {
+    parts.push(
+      `${candidate.localContext.browserTabCount} browser tab${
+        candidate.localContext.browserTabCount === 1 ? '' : 's'
+      }`
+    )
+  }
+  if (candidate.localContext.diffCommentCount > 0) {
+    parts.push(
+      `${candidate.localContext.diffCommentCount} diff note${
+        candidate.localContext.diffCommentCount === 1 ? '' : 's'
+      }`
+    )
+  }
+  if (candidate.localContext.retainedDoneAgentCount > 0) {
+    parts.push(
+      `${candidate.localContext.retainedDoneAgentCount} completed agent${
+        candidate.localContext.retainedDoneAgentCount === 1 ? '' : 's'
+      }`
+    )
+  }
+  return parts.length > 0 ? parts.join(', ') : null
+}
+
+function ConfirmRemove({
+  count,
+  removing,
+  onCancel,
+  onConfirm
+}: {
+  count: number
+  removing: boolean
+  onCancel: () => void
+  onConfirm: () => void
+}): React.JSX.Element {
+  return (
+    <>
+      <DialogHeader className="border-b border-border px-5 py-4">
+        <DialogTitle className="text-base">
+          Remove {count} workspace{count === 1 ? '' : 's'}?
+        </DialogTitle>
+        <DialogDescription className="mt-2 text-xs leading-5">
+          Removing a workspace deletes its working tree folder, local Orca metadata, terminal
+          history, browser workspace state, and the local branch when the existing git deletion path
+          decides that branch is no longer used.
+        </DialogDescription>
+      </DialogHeader>
+      <div className="flex-1 px-5 py-4 text-sm">
+        Cleanup rechecks each selected workspace before deletion. Suggested rows use the normal
+        git-safe removal path; not suggested rows may need forced worktree removal and are reported
+        if they cannot be removed.
+      </div>
+      <DialogFooter className="border-t border-border px-5 py-3">
+        <Button variant="outline" onClick={onCancel} disabled={removing}>
+          Cancel
+        </Button>
+        <Button variant="destructive" onClick={onConfirm} disabled={removing || count === 0}>
+          {removing ? <Loader2 className="size-4 animate-spin" /> : <Trash2 className="size-4" />}
+          Remove {count}
+        </Button>
+      </DialogFooter>
+    </>
+  )
+}
+
+function SkeletonRows(): React.JSX.Element {
+  return (
+    <div className="space-y-2">
+      {[0, 1, 2].map((index) => (
+        <div
+          key={index}
+          className="h-24 animate-pulse rounded-lg border border-border bg-muted/35"
+        />
+      ))}
+    </div>
+  )
+}
+
+function EmptyState({
+  title,
+  actionLabel,
+  onAction
+}: {
+  title: string
+  actionLabel?: string
+  onAction?: () => void
+}): React.JSX.Element {
+  return (
+    <div className="flex min-h-48 flex-col items-center justify-center gap-3 rounded-lg border border-border bg-muted/20 text-sm text-muted-foreground">
+      <span>{title}</span>
+      {actionLabel && onAction ? (
+        <Button variant="outline" size="sm" onClick={onAction}>
+          {actionLabel}
+        </Button>
+      ) : null}
+    </div>
+  )
+}
+
+function toggleSetMember(current: Set<string>, value: string): Set<string> {
+  const next = new Set(current)
+  if (next.has(value)) {
+    next.delete(value)
+  } else {
+    next.add(value)
+  }
+  return next
+}
diff --git a/src/renderer/src/store/index.ts b/src/renderer/src/store/index.ts
index 76a8c91ed87..3337e94403a 100644
--- a/src/renderer/src/store/index.ts
+++ b/src/renderer/src/store/index.ts
@@ -24,6 +24,7 @@ import { createDiffCommentsSlice } from './slices/diffComments'
 import { createDetectedAgentsSlice } from './slices/detected-agents'
 import { createWorktreeNavHistorySlice } from './slices/worktree-nav-history'
 import { createDictationSlice } from './slices/dictation'
+import { createWorkspaceCleanupSlice } from './slices/workspace-cleanup'
 import { e2eConfig } from '@/lib/e2e-config'
 import { registerHttpLinkStoreAccessor } from '@/lib/http-link-routing'
 
@@ -51,7 +52,8 @@ export const useAppStore = create<AppState>()((...a) => ({
   ...createDiffCommentsSlice(...a),
   ...createDetectedAgentsSlice(...a),
   ...createWorktreeNavHistorySlice(...a),
-  ...createDictationSlice(...a)
+  ...createDictationSlice(...a),
+  ...createWorkspaceCleanupSlice(...a)
 }))
 
 registerHttpLinkStoreAccessor(() => useAppStore.getState())
diff --git a/src/renderer/src/store/slices/diffComments.test.ts b/src/renderer/src/store/slices/diffComments.test.ts
index f41a4750357..7f7018d7231 100644
--- a/src/renderer/src/store/slices/diffComments.test.ts
+++ b/src/renderer/src/store/slices/diffComments.test.ts
@@ -111,6 +111,7 @@ import { createDiffCommentsSlice } from './diffComments'
 import { createDetectedAgentsSlice } from './detected-agents'
 import { createWorktreeNavHistorySlice } from './worktree-nav-history'
 import { createDictationSlice } from './dictation'
+import { createWorkspaceCleanupSlice } from './workspace-cleanup'
 
 function createTestStore() {
   return create<AppState>()((...a) => ({
@@ -137,7 +138,8 @@ function createTestStore() {
     ...createDiffCommentsSlice(...a),
     ...createDetectedAgentsSlice(...a),
     ...createWorktreeNavHistorySlice(...a),
-    ...createDictationSlice(...a)
+    ...createDictationSlice(...a),
+    ...createWorkspaceCleanupSlice(...a)
   }))
 }
 
diff --git a/src/renderer/src/store/slices/store-session-cascades.test.ts b/src/renderer/src/store/slices/store-session-cascades.test.ts
index 990a4f3fc01..bff2a4ff2ae 100644
--- a/src/renderer/src/store/slices/store-session-cascades.test.ts
+++ b/src/renderer/src/store/slices/store-session-cascades.test.ts
@@ -114,6 +114,7 @@ import { createDiffCommentsSlice } from './diffComments'
 import { createDetectedAgentsSlice } from './detected-agents'
 import { createWorktreeNavHistorySlice } from './worktree-nav-history'
 import { createDictationSlice } from './dictation'
+import { createWorkspaceCleanupSlice } from './workspace-cleanup'
 
 function createTestStore() {
   return create<AppState>()((...a) => ({
@@ -140,7 +141,8 @@ function createTestStore() {
     ...createDiffCommentsSlice(...a),
     ...createDetectedAgentsSlice(...a),
     ...createWorktreeNavHistorySlice(...a),
-    ...createDictationSlice(...a)
+    ...createDictationSlice(...a),
+    ...createWorkspaceCleanupSlice(...a)
   }))
 }
 
diff --git a/src/renderer/src/store/slices/store-test-helpers.ts b/src/renderer/src/store/slices/store-test-helpers.ts
index e4c43e4dfb8..ab8b589ce24 100644
--- a/src/renderer/src/store/slices/store-test-helpers.ts
+++ b/src/renderer/src/store/slices/store-test-helpers.ts
@@ -32,6 +32,7 @@ import { createDiffCommentsSlice } from './diffComments'
 import { createDetectedAgentsSlice } from './detected-agents'
 import { createWorktreeNavHistorySlice } from './worktree-nav-history'
 import { createDictationSlice } from './dictation'
+import { createWorkspaceCleanupSlice } from './workspace-cleanup'
 
 export const TEST_REPO = {
   id: 'repo1',
@@ -66,7 +67,8 @@ export function createTestStore() {
     ...createDiffCommentsSlice(...a),
     ...createDetectedAgentsSlice(...a),
     ...createWorktreeNavHistorySlice(...a),
-    ...createDictationSlice(...a)
+    ...createDictationSlice(...a),
+    ...createWorkspaceCleanupSlice(...a)
   }))
 }
 
diff --git a/src/renderer/src/store/slices/tabs.test.ts b/src/renderer/src/store/slices/tabs.test.ts
index 32e245f1d2e..a68f34b135f 100644
--- a/src/renderer/src/store/slices/tabs.test.ts
+++ b/src/renderer/src/store/slices/tabs.test.ts
@@ -108,6 +108,7 @@ import { createDiffCommentsSlice } from './diffComments'
 import { createDetectedAgentsSlice } from './detected-agents'
 import { createWorktreeNavHistorySlice } from './worktree-nav-history'
 import { createDictationSlice } from './dictation'
+import { createWorkspaceCleanupSlice } from './workspace-cleanup'
 
 const WT = 'repo1::/tmp/feature'
 
@@ -136,7 +137,8 @@ function createTestStore() {
     ...createDiffCommentsSlice(...a),
     ...createDetectedAgentsSlice(...a),
     ...createWorktreeNavHistorySlice(...a),
-    ...createDictationSlice(...a)
+    ...createDictationSlice(...a),
+    ...createWorkspaceCleanupSlice(...a)
   }))
 }
 
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index e807ec3a67a..a6688a47dc5 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -16,6 +16,10 @@ import type {
   WorktreeCardProperty
 } from '../../../../shared/types'
 import { PET_SIZE_DEFAULT, PET_SIZE_MAX, PET_SIZE_MIN } from '../../../../shared/types'
+import {
+  WORKSPACE_CLEANUP_CLASSIFIER_VERSION,
+  type WorkspaceCleanupDismissal
+} from '../../../../shared/workspace-cleanup'
 import { PER_REPO_FETCH_LIMIT } from '../../../../shared/work-items'
 import {
   DEFAULT_STATUS_BAR_ITEMS,
@@ -152,6 +156,40 @@ function sanitizeAcknowledgedAgentsByPaneKey(value: unknown): Record<string, num
   return out
 }
 
+function sanitizeWorkspaceCleanupDismissals(
+  value: unknown
+): Record<string, WorkspaceCleanupDismissal> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return {}
+  }
+  const out: Record<string, WorkspaceCleanupDismissal> = {}
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      continue
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      continue
+    }
+    const input = raw as Record<string, unknown>
+    if (
+      typeof input.worktreeId !== 'string' ||
+      typeof input.dismissedAt !== 'number' ||
+      !Number.isFinite(input.dismissedAt) ||
+      typeof input.fingerprint !== 'string' ||
+      input.classifierVersion !== WORKSPACE_CLEANUP_CLASSIFIER_VERSION
+    ) {
+      continue
+    }
+    out[key] = {
+      worktreeId: input.worktreeId,
+      dismissedAt: input.dismissedAt,
+      fingerprint: input.fingerprint,
+      classifierVersion: input.classifierVersion
+    }
+  }
+  return out
+}
+
 function sanitizeTaskResumeState(value: unknown): TaskResumeState | undefined {
   if (!value || typeof value !== 'object') {
     return undefined
@@ -284,6 +322,7 @@ export type UISlice = {
     | 'add-repo'
     | 'quick-open'
     | 'worktree-palette'
+    | 'workspace-cleanup'
     | 'feature-wall'
     | 'new-workspace-composer'
     | 'confirm-orca-yaml-hooks'
@@ -896,6 +935,9 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         acknowledgedAgentsByPaneKey: sanitizeAcknowledgedAgentsByPaneKey(
           ui.acknowledgedAgentsByPaneKey
         ),
+        workspaceCleanupDismissals: sanitizeWorkspaceCleanupDismissals(
+          ui.workspaceCleanup?.dismissals
+        ),
         persistedUIReady: true
       }
     }),
diff --git a/src/renderer/src/store/slices/workspace-cleanup.test.ts b/src/renderer/src/store/slices/workspace-cleanup.test.ts
new file mode 100644
index 00000000000..70dc8e2afed
--- /dev/null
+++ b/src/renderer/src/store/slices/workspace-cleanup.test.ts
@@ -0,0 +1,363 @@
+/* eslint-disable max-lines -- Why: cleanup store tests share a Zustand store
+   harness and mocked window API; splitting would obscure the state transitions. */
+import { create } from 'zustand'
+import { describe, expect, it, vi } from 'vitest'
+import type { AppState } from '../types'
+import type {
+  WorkspaceCleanupCandidate,
+  WorkspaceCleanupScanResult
+} from '../../../../shared/workspace-cleanup'
+import { createWorkspaceCleanupSlice, enrichWorkspaceCleanupCandidates } from './workspace-cleanup'
+
+const WORKTREE_ID = 'repo1::/tmp/old-workspace'
+const NOW = 1_700_000_000_000
+
+function makeCandidate(
+  overrides: Partial<WorkspaceCleanupCandidate> = {}
+): WorkspaceCleanupCandidate {
+  return {
+    worktreeId: WORKTREE_ID,
+    repoId: 'repo1',
+    repoName: 'Repo 1',
+    connectionId: null,
+    displayName: 'old-workspace',
+    branch: 'old-workspace',
+    path: '/tmp/old-workspace',
+    tier: 'ready',
+    selectedByDefault: true,
+    reasons: ['idle-clean'],
+    blockers: [],
+    lastActivityAt: NOW - 30 * 24 * 60 * 60 * 1000,
+    localContext: {
+      terminalTabCount: 0,
+      cleanEditorTabCount: 0,
+      browserTabCount: 0,
+      diffCommentCount: 0,
+      newestDiffCommentAt: null,
+      retainedDoneAgentCount: 0
+    },
+    git: {
+      clean: true,
+      upstreamAhead: 0,
+      upstreamBehind: 0,
+      checkedAt: NOW
+    },
+    fingerprint: 'fingerprint-1',
+    ...overrides
+  }
+}
+
+function makeState(overrides: Partial<AppState> = {}): AppState {
+  return {
+    tabsByWorktree: {},
+    ptyIdsByTabId: {},
+    openFiles: [],
+    editorDrafts: {},
+    browserTabsByWorktree: {},
+    retainedAgentsByPaneKey: {},
+    activeWorktreeId: null,
+    agentStatusByPaneKey: {},
+    runtimePaneTitlesByTabId: {},
+    lastVisitedAtByWorktreeId: {},
+    workspaceCleanupDismissals: {},
+    workspaceCleanupViewedCandidates: {},
+    ...overrides
+  } as AppState
+}
+
+function createCleanupTestStore(removeWorktree = vi.fn()) {
+  return create<AppState>()(
+    (...a) =>
+      ({
+        tabsByWorktree: {},
+        ptyIdsByTabId: {},
+        openFiles: [],
+        editorDrafts: {},
+        browserTabsByWorktree: {},
+        retainedAgentsByPaneKey: {},
+        activeWorktreeId: null,
+        agentStatusByPaneKey: {},
+        runtimePaneTitlesByTabId: {},
+        lastVisitedAtByWorktreeId: {},
+        removeWorktree,
+        ...createWorkspaceCleanupSlice(...a)
+      }) as unknown as AppState
+  )
+}
+
+describe('workspace cleanup viewed rows', () => {
+  it('demotes an active suggested workspace when it was not viewed from cleanup', async () => {
+    const [candidate] = await enrichWorkspaceCleanupCandidates(
+      [makeCandidate()],
+      makeState({ activeWorktreeId: WORKTREE_ID }),
+      { applyDismissals: false }
+    )
+
+    expect(candidate.tier).toBe('protected')
+    expect(candidate.blockers).toContain('active-workspace')
+  })
+
+  it('keeps a viewed active workspace visible but not removable', async () => {
+    const [candidate] = await enrichWorkspaceCleanupCandidates(
+      [makeCandidate()],
+      makeState({
+        activeWorktreeId: WORKTREE_ID,
+        workspaceCleanupViewedCandidates: {
+          [WORKTREE_ID]: {
+            viewedAt: Date.now(),
+            fingerprint: 'fingerprint-1',
+            wasSuggested: true
+          }
+        }
+      }),
+      { applyDismissals: false }
+    )
+
+    expect(candidate.tier).toBe('protected')
+    expect(candidate.selectedByDefault).toBe(false)
+    expect(candidate.blockers).toContain('active-workspace')
+  })
+
+  it('does not preserve the cleanup view exception after the row changes', async () => {
+    const [candidate] = await enrichWorkspaceCleanupCandidates(
+      [makeCandidate({ fingerprint: 'fingerprint-2' })],
+      makeState({
+        activeWorktreeId: WORKTREE_ID,
+        workspaceCleanupViewedCandidates: {
+          [WORKTREE_ID]: {
+            viewedAt: Date.now(),
+            fingerprint: 'fingerprint-1',
+            wasSuggested: true
+          }
+        }
+      }),
+      { applyDismissals: false }
+    )
+
+    expect(candidate.tier).toBe('protected')
+    expect(candidate.blockers).toContain('active-workspace')
+  })
+
+  it('protects recently visible old workspaces with open context', async () => {
+    const [candidate] = await enrichWorkspaceCleanupCandidates(
+      [makeCandidate()],
+      makeState({
+        openFiles: [
+          {
+            id: 'file-1',
+            worktreeId: WORKTREE_ID,
+            filePath: '/tmp/old-workspace/src/app.ts',
+            relativePath: 'src/app.ts',
+            language: 'typescript',
+            isDirty: false
+          }
+        ] as AppState['openFiles'],
+        lastVisitedAtByWorktreeId: {
+          [WORKTREE_ID]: Date.now()
+        }
+      }),
+      { applyDismissals: false }
+    )
+
+    expect(candidate.tier).toBe('protected')
+    expect(candidate.selectedByDefault).toBe(false)
+    expect(candidate.blockers).toContain('recent-visible-context')
+  })
+
+  it('uses current renderer state after async delete preflight scan resolves', async () => {
+    let resolveScan: (value: WorkspaceCleanupScanResult) => void
+    const removeWorktree = vi.fn().mockResolvedValue({ ok: true })
+    const store = createCleanupTestStore(removeWorktree)
+
+    ;(globalThis as { window: unknown }).window = {
+      api: {
+        workspaceCleanup: {
+          scan: vi.fn(
+            (): Promise<WorkspaceCleanupScanResult> =>
+              new Promise<WorkspaceCleanupScanResult>((resolve) => {
+                resolveScan = resolve
+              })
+          ),
+          dismiss: vi.fn().mockResolvedValue(undefined),
+          clearDismissals: vi.fn().mockResolvedValue(undefined),
+          hasKillableLocalProcesses: vi.fn().mockResolvedValue({
+            hasKillableProcesses: false
+          })
+        }
+      }
+    }
+
+    const removal = store.getState().removeWorkspaceCleanupCandidates([WORKTREE_ID])
+    store.setState({ activeWorktreeId: WORKTREE_ID })
+    resolveScan!({ scannedAt: NOW, candidates: [makeCandidate()], errors: [] })
+
+    await expect(removal).resolves.toEqual({
+      removedIds: [WORKTREE_ID],
+      failures: []
+    })
+    expect(removeWorktree).toHaveBeenCalledWith(WORKTREE_ID, false)
+  })
+
+  it('defers git checks for locally active workspaces on initial scans', async () => {
+    const scan = vi.fn().mockResolvedValue({
+      scannedAt: NOW,
+      candidates: [],
+      errors: []
+    } satisfies WorkspaceCleanupScanResult)
+    ;(globalThis as { window: unknown }).window = {
+      api: {
+        workspaceCleanup: {
+          scan,
+          dismiss: vi.fn().mockResolvedValue(undefined),
+          clearDismissals: vi.fn().mockResolvedValue(undefined),
+          hasKillableLocalProcesses: vi.fn().mockResolvedValue({
+            hasKillableProcesses: false
+          })
+        }
+      }
+    }
+
+    const store = createCleanupTestStore()
+    store.setState({
+      activeWorktreeId: WORKTREE_ID,
+      tabsByWorktree: {
+        'repo1::/tmp/terminal-workspace': [
+          { id: 'tab-1', title: 'zsh' }
+        ] as AppState['tabsByWorktree'][string]
+      },
+      ptyIdsByTabId: { 'tab-1': ['pty-1'] }
+    } as Partial<AppState>)
+
+    await store.getState().scanWorkspaceCleanup()
+
+    expect(scan).toHaveBeenCalledWith({
+      skipGitWorktreeIds: expect.arrayContaining([WORKTREE_ID, 'repo1::/tmp/terminal-workspace'])
+    })
+  })
+
+  it('does not defer git checks for focused remove preflights', async () => {
+    const scan = vi.fn().mockResolvedValue({
+      scannedAt: NOW,
+      candidates: [makeCandidate()],
+      errors: []
+    } satisfies WorkspaceCleanupScanResult)
+    ;(globalThis as { window: unknown }).window = {
+      api: {
+        workspaceCleanup: {
+          scan,
+          dismiss: vi.fn().mockResolvedValue(undefined),
+          clearDismissals: vi.fn().mockResolvedValue(undefined),
+          hasKillableLocalProcesses: vi.fn().mockResolvedValue({
+            hasKillableProcesses: false
+          })
+        }
+      }
+    }
+
+    const removeWorktree = vi.fn().mockResolvedValue({ ok: true })
+    const store = createCleanupTestStore(removeWorktree)
+    store.setState({ activeWorktreeId: 'repo1::/tmp/other-workspace' } as Partial<AppState>)
+
+    await store.getState().removeWorkspaceCleanupCandidates([WORKTREE_ID])
+
+    expect(scan).toHaveBeenCalledWith({ worktreeId: WORKTREE_ID })
+  })
+
+  it('lets explicitly selected not-suggested workspaces reach the removal path', async () => {
+    const scan = vi.fn().mockResolvedValue({
+      scannedAt: NOW,
+      candidates: [makeCandidate()],
+      errors: []
+    } satisfies WorkspaceCleanupScanResult)
+    const removeWorktree = vi.fn().mockResolvedValue({ ok: true })
+    ;(globalThis as { window: unknown }).window = {
+      api: {
+        workspaceCleanup: {
+          scan,
+          dismiss: vi.fn().mockResolvedValue(undefined),
+          clearDismissals: vi.fn().mockResolvedValue(undefined),
+          hasKillableLocalProcesses: vi.fn().mockResolvedValue({
+            hasKillableProcesses: true
+          })
+        }
+      }
+    }
+
+    const store = createCleanupTestStore(removeWorktree)
+
+    store.setState({
+      tabsByWorktree: {
+        [WORKTREE_ID]: [{ id: 'tab-1', title: 'zsh' }] as AppState['tabsByWorktree'][string]
+      },
+      ptyIdsByTabId: { 'tab-1': ['pty-1'] }
+    } as Partial<AppState>)
+
+    await expect(store.getState().removeWorkspaceCleanupCandidates([WORKTREE_ID])).resolves.toEqual(
+      {
+        removedIds: [WORKTREE_ID],
+        failures: []
+      }
+    )
+    expect(removeWorktree).toHaveBeenCalledWith(WORKTREE_ID, false)
+  })
+
+  it('protects old workspaces when an agent process is still foregrounded', async () => {
+    ;(globalThis as { window: unknown }).window = {
+      api: {
+        pty: {
+          hasChildProcesses: vi.fn().mockResolvedValue(true),
+          getForegroundProcess: vi.fn().mockResolvedValue('codex')
+        }
+      }
+    }
+
+    const [candidate] = await enrichWorkspaceCleanupCandidates(
+      [makeCandidate()],
+      makeState({
+        tabsByWorktree: {
+          [WORKTREE_ID]: [{ id: 'tab-1', title: 'zsh' }] as AppState['tabsByWorktree'][string]
+        },
+        ptyIdsByTabId: { 'tab-1': ['pty-1'] }
+      }),
+      { applyDismissals: false }
+    )
+
+    expect(candidate.tier).toBe('protected')
+    expect(candidate.selectedByDefault).toBe(false)
+    expect(candidate.blockers).toContain('running-terminal')
+  })
+
+  it('does not let an idle title in another tab mask a running agent process', async () => {
+    ;(globalThis as { window: unknown }).window = {
+      api: {
+        pty: {
+          hasChildProcesses: vi.fn(async (ptyId: string) => ptyId === 'pty-running'),
+          getForegroundProcess: vi.fn(async (ptyId: string) =>
+            ptyId === 'pty-running' ? 'codex' : 'zsh'
+          )
+        }
+      }
+    }
+
+    const [candidate] = await enrichWorkspaceCleanupCandidates(
+      [makeCandidate()],
+      makeState({
+        tabsByWorktree: {
+          [WORKTREE_ID]: [
+            { id: 'tab-running', title: 'zsh' },
+            { id: 'tab-idle', title: 'Codex done' }
+          ] as AppState['tabsByWorktree'][string]
+        },
+        ptyIdsByTabId: {
+          'tab-running': ['pty-running'],
+          'tab-idle': ['pty-idle']
+        }
+      }),
+      { applyDismissals: false }
+    )
+
+    expect(candidate.tier).toBe('protected')
+    expect(candidate.selectedByDefault).toBe(false)
+    expect(candidate.blockers).toContain('running-terminal')
+  })
+})
diff --git a/src/renderer/src/store/slices/workspace-cleanup.ts b/src/renderer/src/store/slices/workspace-cleanup.ts
new file mode 100644
index 00000000000..e9f112e7bff
--- /dev/null
+++ b/src/renderer/src/store/slices/workspace-cleanup.ts
@@ -0,0 +1,527 @@
+/* eslint-disable max-lines */
+import type { StateCreator } from 'zustand'
+import type { AppState } from '../types'
+import {
+  AGENT_STATUS_STALE_AFTER_MS,
+  type AgentStatusEntry
+} from '../../../../shared/agent-status-types'
+import {
+  WORKSPACE_CLEANUP_CLASSIFIER_VERSION,
+  applyWorkspaceCleanupPolicy,
+  canQueueWorkspaceCleanupCandidate,
+  canSelectWorkspaceCleanupCandidate,
+  shouldForceWorkspaceCleanupRemoval,
+  shouldHideWorkspaceCleanupCandidate,
+  type WorkspaceCleanupBlocker,
+  type WorkspaceCleanupCandidate,
+  type WorkspaceCleanupDismissal,
+  type WorkspaceCleanupScanArgs,
+  type WorkspaceCleanupScanResult
+} from '../../../../shared/workspace-cleanup'
+import { detectAgentStatusFromTitle, isExplicitAgentStatusFresh } from '@/lib/agent-status'
+
+export type WorkspaceCleanupFailure = {
+  worktreeId: string
+  displayName: string
+  message: string
+}
+
+export type WorkspaceCleanupRemoveResult = {
+  removedIds: string[]
+  failures: WorkspaceCleanupFailure[]
+}
+
+type WorkspaceCleanupViewedCandidate = {
+  viewedAt: number
+  fingerprint: string
+  wasSuggested: boolean
+}
+
+export type WorkspaceCleanupSlice = {
+  workspaceCleanupScan: WorkspaceCleanupScanResult | null
+  workspaceCleanupLoading: boolean
+  workspaceCleanupError: string | null
+  workspaceCleanupDismissals: Record<string, WorkspaceCleanupDismissal>
+  workspaceCleanupViewedCandidates: Record<string, WorkspaceCleanupViewedCandidate>
+  scanWorkspaceCleanup: (args?: WorkspaceCleanupScanArgs) => Promise<WorkspaceCleanupScanResult>
+  markWorkspaceCleanupCandidateViewed: (candidate: WorkspaceCleanupCandidate) => void
+  dismissWorkspaceCleanupCandidates: (
+    candidates: readonly WorkspaceCleanupCandidate[]
+  ) => Promise<void>
+  resetWorkspaceCleanupDismissals: () => Promise<void>
+  removeWorkspaceCleanupCandidates: (
+    worktreeIds: readonly string[]
+  ) => Promise<WorkspaceCleanupRemoveResult>
+}
+
+type EnrichOptions = {
+  applyDismissals?: boolean
+}
+
+const RECENT_VISIBLE_CONTEXT_MS = 24 * 60 * 60 * 1000
+const VIEWED_FROM_CLEANUP_MS = 2 * 60 * 60 * 1000
+
+const SHELL_PROCESS_NAMES = new Set([
+  'bash',
+  'cmd',
+  'cmd.exe',
+  'fish',
+  'nu',
+  'powershell',
+  'powershell.exe',
+  'pwsh',
+  'pwsh.exe',
+  'sh',
+  'zsh'
+])
+
+const AGENT_PROCESS_NAMES = new Set([
+  'aider',
+  'amp',
+  'claude',
+  'claude-code',
+  'codex',
+  'crush',
+  'droid',
+  'gemini',
+  'gemini-cli',
+  'goose',
+  'opencode'
+])
+
+export const createWorkspaceCleanupSlice: StateCreator<AppState, [], [], WorkspaceCleanupSlice> = (
+  set,
+  get
+) => ({
+  workspaceCleanupScan: null,
+  workspaceCleanupLoading: false,
+  workspaceCleanupError: null,
+  workspaceCleanupDismissals: {},
+  workspaceCleanupViewedCandidates: {},
+
+  scanWorkspaceCleanup: async (args) => {
+    set({ workspaceCleanupLoading: true, workspaceCleanupError: null })
+    try {
+      const scanArgs =
+        args?.worktreeId !== undefined
+          ? args
+          : {
+              ...args,
+              skipGitWorktreeIds: [
+                ...new Set([
+                  ...(args?.skipGitWorktreeIds ?? []),
+                  ...getInitialWorkspaceCleanupGitDeferrals(get())
+                ])
+              ]
+            }
+      const scan = await window.api.workspaceCleanup.scan(scanArgs)
+      const enriched = await enrichWorkspaceCleanupCandidates(scan.candidates, get())
+      const result = { ...scan, candidates: enriched }
+      set({ workspaceCleanupScan: result, workspaceCleanupLoading: false })
+      return result
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      set({ workspaceCleanupError: message, workspaceCleanupLoading: false })
+      throw error
+    }
+  },
+
+  markWorkspaceCleanupCandidateViewed: (candidate) => {
+    set((state) => ({
+      workspaceCleanupViewedCandidates: {
+        ...state.workspaceCleanupViewedCandidates,
+        [candidate.worktreeId]: {
+          viewedAt: Date.now(),
+          fingerprint: candidate.fingerprint,
+          wasSuggested: candidate.tier === 'ready' && canSelectWorkspaceCleanupCandidate(candidate)
+        }
+      }
+    }))
+  },
+
+  dismissWorkspaceCleanupCandidates: async (candidates) => {
+    const now = Date.now()
+    const dismissals = candidates.map((candidate) => ({
+      worktreeId: candidate.worktreeId,
+      dismissedAt: now,
+      fingerprint: candidate.fingerprint,
+      classifierVersion: WORKSPACE_CLEANUP_CLASSIFIER_VERSION
+    }))
+
+    set((state) => {
+      const nextDismissals = { ...state.workspaceCleanupDismissals }
+      for (const dismissal of dismissals) {
+        nextDismissals[dismissal.worktreeId] = dismissal
+      }
+      const nextScan = state.workspaceCleanupScan
+        ? {
+            ...state.workspaceCleanupScan,
+            candidates: state.workspaceCleanupScan.candidates.map((candidate) =>
+              applyDismissal(candidate, nextDismissals)
+            )
+          }
+        : state.workspaceCleanupScan
+      return {
+        workspaceCleanupDismissals: nextDismissals,
+        workspaceCleanupScan: nextScan
+      }
+    })
+
+    await window.api.workspaceCleanup.dismiss({ dismissals })
+  },
+
+  resetWorkspaceCleanupDismissals: async () => {
+    set((state) => ({
+      workspaceCleanupDismissals: {},
+      workspaceCleanupScan: state.workspaceCleanupScan
+        ? {
+            ...state.workspaceCleanupScan,
+            candidates: state.workspaceCleanupScan.candidates.map((candidate) =>
+              applyWorkspaceCleanupPolicy({
+                ...candidate,
+                blockers: candidate.blockers.filter((blocker) => blocker !== 'dismissed')
+              })
+            )
+          }
+        : state.workspaceCleanupScan
+    }))
+    await window.api.workspaceCleanup.clearDismissals()
+  },
+
+  removeWorkspaceCleanupCandidates: async (worktreeIds) => {
+    const removedIds: string[] = []
+    const failures: WorkspaceCleanupFailure[] = []
+
+    for (const worktreeId of worktreeIds) {
+      const preflight = await preflightWorkspaceCleanupCandidate(worktreeId, get)
+      if (!preflight.ok) {
+        failures.push(preflight.failure)
+        continue
+      }
+
+      const result = await get().removeWorktree(
+        worktreeId,
+        shouldForceWorkspaceCleanupRemoval(preflight.candidate)
+      )
+      if (result.ok) {
+        removedIds.push(worktreeId)
+      } else {
+        failures.push({
+          worktreeId,
+          displayName: preflight.candidate.displayName,
+          message: result.error
+        })
+      }
+    }
+
+    if (removedIds.length > 0) {
+      set((state) => ({
+        workspaceCleanupScan: state.workspaceCleanupScan
+          ? {
+              ...state.workspaceCleanupScan,
+              candidates: state.workspaceCleanupScan.candidates.filter(
+                (candidate) => !removedIds.includes(candidate.worktreeId)
+              )
+            }
+          : state.workspaceCleanupScan
+      }))
+    }
+
+    return { removedIds, failures }
+  }
+})
+
+function getInitialWorkspaceCleanupGitDeferrals(state: AppState): string[] {
+  const ids = new Set<string>()
+  if (state.activeWorktreeId) {
+    ids.add(state.activeWorktreeId)
+  }
+
+  for (const file of state.openFiles) {
+    if (file.isDirty || state.editorDrafts[file.id] !== undefined) {
+      ids.add(file.worktreeId)
+    }
+  }
+
+  const openEditorWorktreeIds = new Set(state.openFiles.map((file) => file.worktreeId))
+  for (const [worktreeId, tabs] of Object.entries(state.tabsByWorktree)) {
+    const tabIds = new Set(tabs.map((tab) => tab.id))
+    if (tabs.some((tab) => (state.ptyIdsByTabId[tab.id]?.length ?? 0) > 0)) {
+      ids.add(worktreeId)
+    }
+    if (hasFreshLiveAgent(state, tabIds) || hasWorkingTitleAgent(state, tabs)) {
+      ids.add(worktreeId)
+    }
+  }
+
+  for (const worktreeId of new Set([
+    ...openEditorWorktreeIds,
+    ...Object.keys(state.browserTabsByWorktree)
+  ])) {
+    const hasVisibleContext =
+      openEditorWorktreeIds.has(worktreeId) ||
+      (state.browserTabsByWorktree[worktreeId]?.length ?? 0) > 0
+    const lastVisitedAt = state.lastVisitedAtByWorktreeId[worktreeId] ?? 0
+    if (
+      hasVisibleContext &&
+      lastVisitedAt > 0 &&
+      Date.now() - lastVisitedAt <= RECENT_VISIBLE_CONTEXT_MS
+    ) {
+      ids.add(worktreeId)
+    }
+  }
+
+  // Why: these rows must stay visible, but they already need user attention.
+  // Defer expensive git reads until a focused refresh/remove preflight.
+  return [...ids]
+}
+
+export async function enrichWorkspaceCleanupCandidates(
+  candidates: readonly WorkspaceCleanupCandidate[],
+  state: AppState,
+  options: EnrichOptions = {}
+): Promise<WorkspaceCleanupCandidate[]> {
+  return Promise.all(
+    candidates.map((candidate) => enrichWorkspaceCleanupCandidate(candidate, state, options))
+  )
+}
+
+async function enrichWorkspaceCleanupCandidate(
+  candidate: WorkspaceCleanupCandidate,
+  state: AppState,
+  options: EnrichOptions
+): Promise<WorkspaceCleanupCandidate> {
+  const tabs = state.tabsByWorktree[candidate.worktreeId] ?? []
+  const tabIds = new Set(tabs.map((tab) => tab.id))
+  const openFiles = state.openFiles.filter((file) => file.worktreeId === candidate.worktreeId)
+  const dirtyEditorBuffers = openFiles.filter(
+    (file) => file.isDirty || state.editorDrafts[file.id] !== undefined
+  )
+  const cleanEditorTabCount = openFiles.length - dirtyEditorBuffers.length
+  const browserTabCount = (state.browserTabsByWorktree[candidate.worktreeId] ?? []).length
+  const retainedDoneAgentCount = Object.values(state.retainedAgentsByPaneKey).filter(
+    (entry) => entry.worktreeId === candidate.worktreeId && entry.entry.state === 'done'
+  ).length
+  const blockers = candidate.blockers.filter((blocker) => blocker !== 'dismissed')
+  const preserveCleanupInspection = shouldPreserveCleanupInspection(candidate, state)
+
+  if (state.activeWorktreeId === candidate.worktreeId) {
+    blockers.push('active-workspace')
+  }
+  if (dirtyEditorBuffers.length > 0) {
+    blockers.push('dirty-editor-buffer')
+  }
+  if (hasFreshLiveAgent(state, tabIds)) {
+    blockers.push('live-agent')
+  }
+  if (hasWorkingTitleAgent(state, tabs)) {
+    blockers.push('live-agent')
+  }
+
+  const terminalProbe = await probeTerminalLiveness(state, tabs)
+  if (terminalProbe === 'running') {
+    blockers.push('running-terminal')
+  } else if (terminalProbe === 'unknown') {
+    blockers.push('terminal-liveness-unknown')
+  }
+
+  const lastVisitedAt = state.lastVisitedAtByWorktreeId[candidate.worktreeId] ?? 0
+  const hasVisibleContext = cleanEditorTabCount > 0 || browserTabCount > 0
+  if (
+    hasVisibleContext &&
+    !preserveCleanupInspection &&
+    lastVisitedAt > 0 &&
+    Date.now() - lastVisitedAt <= RECENT_VISIBLE_CONTEXT_MS
+  ) {
+    blockers.push('recent-visible-context')
+  }
+
+  const enriched = applyWorkspaceCleanupPolicy({
+    ...candidate,
+    blockers: [...new Set(blockers)],
+    localContext: {
+      ...candidate.localContext,
+      terminalTabCount: tabs.length,
+      cleanEditorTabCount,
+      browserTabCount,
+      retainedDoneAgentCount
+    }
+  })
+
+  return options.applyDismissals === false
+    ? enriched
+    : applyDismissal(enriched, state.workspaceCleanupDismissals)
+}
+
+function shouldPreserveCleanupInspection(
+  candidate: WorkspaceCleanupCandidate,
+  state: AppState
+): boolean {
+  const viewed = state.workspaceCleanupViewedCandidates[candidate.worktreeId]
+  if (!viewed?.wasSuggested || viewed.fingerprint !== candidate.fingerprint) {
+    return false
+  }
+  // Why: View is part of cleanup review. It should not make the same
+  // suggested row vanish on the next scan, but this exception must expire.
+  return Date.now() - viewed.viewedAt <= VIEWED_FROM_CLEANUP_MS
+}
+
+function applyDismissal(
+  candidate: WorkspaceCleanupCandidate,
+  dismissals: Record<string, WorkspaceCleanupDismissal>
+): WorkspaceCleanupCandidate {
+  if (!shouldHideWorkspaceCleanupCandidate(candidate, dismissals[candidate.worktreeId])) {
+    return candidate
+  }
+  return applyWorkspaceCleanupPolicy({
+    ...candidate,
+    blockers: [...new Set<WorkspaceCleanupBlocker>([...candidate.blockers, 'dismissed'])]
+  })
+}
+
+async function preflightWorkspaceCleanupCandidate(
+  worktreeId: string,
+  getState: () => AppState
+): Promise<
+  | { ok: true; candidate: WorkspaceCleanupCandidate }
+  | { ok: false; failure: WorkspaceCleanupFailure }
+> {
+  const scan = await window.api.workspaceCleanup.scan({ worktreeId })
+  const [candidate] = await enrichWorkspaceCleanupCandidates(scan.candidates, getState(), {
+    applyDismissals: false
+  })
+  if (!candidate) {
+    return {
+      ok: false,
+      failure: {
+        worktreeId,
+        displayName: worktreeId,
+        message: 'Workspace no longer exists.'
+      }
+    }
+  }
+  if (!canQueueWorkspaceCleanupCandidate(candidate)) {
+    return {
+      ok: false,
+      failure: {
+        worktreeId,
+        displayName: candidate.displayName,
+        message: candidate.blockers.length
+          ? candidate.blockers.join(', ')
+          : 'Workspace is no longer safe to remove.'
+      }
+    }
+  }
+  return { ok: true, candidate }
+}
+
+function hasFreshLiveAgent(state: AppState, tabIds: Set<string>): boolean {
+  const now = Date.now()
+  return Object.values(state.agentStatusByPaneKey).some(
+    (entry) =>
+      tabIds.has(getPaneKeyTabId(entry.paneKey)) &&
+      isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS) &&
+      (entry.state === 'working' || entry.state === 'blocked' || entry.state === 'waiting')
+  )
+}
+
+function hasWorkingTitleAgent(state: AppState, tabs: { id: string; title: string }[]): boolean {
+  for (const tab of tabs) {
+    if ((state.ptyIdsByTabId[tab.id]?.length ?? 0) === 0) {
+      continue
+    }
+    const paneTitles = state.runtimePaneTitlesByTabId[tab.id]
+    const titles =
+      paneTitles && Object.keys(paneTitles).length > 0 ? Object.values(paneTitles) : [tab.title]
+    for (const title of titles) {
+      const status = detectAgentStatusFromTitle(title)
+      if (status === 'working' || status === 'permission') {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+async function probeTerminalLiveness(
+  state: AppState,
+  tabs: { id: string; title: string }[]
+): Promise<'idle' | 'running' | 'unknown'> {
+  const ptyChecks = tabs.flatMap((tab) =>
+    (state.ptyIdsByTabId[tab.id] ?? []).map((ptyId) => ({ tab, ptyId }))
+  )
+  if (ptyChecks.length === 0) {
+    return 'idle'
+  }
+
+  let unknown = false
+  for (const { tab, ptyId } of ptyChecks) {
+    try {
+      const [hasChildProcesses, foregroundProcess] = await Promise.all([
+        window.api.pty.hasChildProcesses(ptyId),
+        window.api.pty.getForegroundProcess(ptyId)
+      ])
+      const processName = normalizeProcessName(foregroundProcess)
+      if (!hasChildProcesses && (!processName || SHELL_PROCESS_NAMES.has(processName))) {
+        continue
+      }
+      if (
+        processName &&
+        AGENT_PROCESS_NAMES.has(processName) &&
+        hasIdleAgentTitleForPty(state, tab, ptyId)
+      ) {
+        continue
+      }
+      return 'running'
+    } catch {
+      unknown = true
+    }
+  }
+
+  return unknown ? 'unknown' : 'idle'
+}
+
+function hasIdleAgentTitleForPty(
+  state: AppState,
+  tab: { id: string; title: string },
+  ptyId: string
+): boolean {
+  const paneTitles = state.runtimePaneTitlesByTabId[tab.id] ?? {}
+  const layoutPtyIds = state.terminalLayoutsByTabId?.[tab.id]?.ptyIdsByLeafId ?? {}
+  const matchingTitles = Object.entries(layoutPtyIds)
+    .filter(([, leafPtyId]) => leafPtyId === ptyId)
+    .map(([leafId]) => paneTitles[leafId.replace(/^pane:/, '')])
+    .filter((title): title is string => typeof title === 'string')
+
+  if (matchingTitles.length > 0) {
+    return matchingTitles.some(isIdleAgentTitle)
+  }
+
+  // Why: without a pane->PTY binding, a tab-level idle title is safe evidence
+  // only when this tab has a single live PTY. Multi-pane tabs stay protected.
+  const tabPtyIds = state.ptyIdsByTabId[tab.id] ?? []
+  if (tabPtyIds.length !== 1) {
+    return false
+  }
+
+  const titles = Object.keys(paneTitles).length > 0 ? Object.values(paneTitles) : [tab.title]
+  return titles.some(isIdleAgentTitle)
+}
+
+function isIdleAgentTitle(title: string): boolean {
+  return detectAgentStatusFromTitle(title) === 'idle'
+}
+
+function getPaneKeyTabId(paneKey: AgentStatusEntry['paneKey']): string {
+  const separatorIndex = paneKey.lastIndexOf(':')
+  return separatorIndex === -1 ? paneKey : paneKey.slice(0, separatorIndex)
+}
+
+function normalizeProcessName(value: string | null): string | null {
+  if (!value) {
+    return null
+  }
+  const normalizedPath = value.replace(/\\/g, '/')
+  const name = normalizedPath.slice(normalizedPath.lastIndexOf('/') + 1).toLowerCase()
+  return name.replace(/\.exe$/i, '.exe')
+}
diff --git a/src/renderer/src/store/types.ts b/src/renderer/src/store/types.ts
index 4c8f148985f..ec246109a53 100644
--- a/src/renderer/src/store/types.ts
+++ b/src/renderer/src/store/types.ts
@@ -22,6 +22,7 @@ import type { DiffCommentsSlice } from './slices/diffComments'
 import type { DetectedAgentsSlice } from './slices/detected-agents'
 import type { WorktreeNavHistorySlice } from './slices/worktree-nav-history'
 import type { DictationSlice } from './slices/dictation'
+import type { WorkspaceCleanupSlice } from './slices/workspace-cleanup'
 
 export type AppState = RepoSlice &
   SparsePresetsSlice &
@@ -46,4 +47,5 @@ export type AppState = RepoSlice &
   DiffCommentsSlice &
   DetectedAgentsSlice &
   WorktreeNavHistorySlice &
-  DictationSlice
+  DictationSlice &
+  WorkspaceCleanupSlice
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 42270639004..777b7142f86 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -349,7 +349,8 @@ export function getDefaultUIState(): PersistedUIState {
     dismissedUpdateVersion: null,
     lastUpdateCheckAt: null,
     trustedOrcaHooks: {},
-    acknowledgedAgentsByPaneKey: {}
+    acknowledgedAgentsByPaneKey: {},
+    workspaceCleanup: { dismissals: {} }
   }
 }
 
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 5f4fa70fb36..9e8f171acca 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -5,6 +5,7 @@ import type { WorkspaceSource } from './telemetry-events'
 import type { GitHubProjectSettings } from './github-project-types'
 import type { MigrationUnsupportedPtyEntry } from './agent-status-types'
 import type { VoiceSettings } from './speech-types'
+import type { WorkspaceCleanupUIState } from './workspace-cleanup'
 import type { GitLabProjectSettings } from './gitlab-types'
 
 // Re-exported for backward compat with renderer call sites that import
@@ -1730,6 +1731,7 @@ export type PersistedUIState = {
    *  using their existing settings paths; this only restores transient tabs
    *  and applied searches. */
   taskResumeState?: TaskResumeState
+  workspaceCleanup?: WorkspaceCleanupUIState
 }
 
 export const PET_SIZE_MIN = 60
diff --git a/src/shared/workspace-cleanup.test.ts b/src/shared/workspace-cleanup.test.ts
new file mode 100644
index 00000000000..e1576bf5f86
--- /dev/null
+++ b/src/shared/workspace-cleanup.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest'
+import {
+  WORKSPACE_CLEANUP_CLASSIFIER_VERSION,
+  applyWorkspaceCleanupPolicy,
+  canQueueWorkspaceCleanupCandidate,
+  canSelectWorkspaceCleanupCandidate,
+  createWorkspaceCleanupFingerprint,
+  shouldForceWorkspaceCleanupRemoval,
+  shouldHideWorkspaceCleanupCandidate,
+  type WorkspaceCleanupCandidate
+} from './workspace-cleanup'
+
+type CandidateOverrides = Partial<Omit<WorkspaceCleanupCandidate, 'git' | 'localContext'>> & {
+  git?: Partial<WorkspaceCleanupCandidate['git']>
+  localContext?: Partial<WorkspaceCleanupCandidate['localContext']>
+}
+
+function makeCandidate(overrides: CandidateOverrides = {}): WorkspaceCleanupCandidate {
+  const { git, localContext, ...candidateOverrides } = overrides
+  const candidate: WorkspaceCleanupCandidate = {
+    worktreeId: 'repo-1::/tmp/feature',
+    repoId: 'repo-1',
+    repoName: 'Repo',
+    connectionId: null,
+    displayName: 'feature',
+    branch: 'feature',
+    path: '/tmp/feature',
+    tier: 'review',
+    selectedByDefault: false,
+    reasons: ['idle-clean'],
+    blockers: [],
+    lastActivityAt: 1_700_000_000_000,
+    localContext: {
+      terminalTabCount: 0,
+      cleanEditorTabCount: 0,
+      browserTabCount: 0,
+      diffCommentCount: 0,
+      newestDiffCommentAt: null,
+      retainedDoneAgentCount: 0
+    },
+    git: {
+      clean: true,
+      upstreamAhead: 0,
+      upstreamBehind: 0,
+      checkedAt: 1_700_000_000_000
+    },
+    fingerprint: 'fingerprint',
+    ...candidateOverrides
+  }
+  return {
+    ...candidate,
+    git: { ...candidate.git, ...git },
+    localContext: { ...candidate.localContext, ...localContext }
+  }
+}
+
+describe('workspace cleanup policy', () => {
+  it('marks clean inactive workspaces as ready and selected', () => {
+    const candidate = applyWorkspaceCleanupPolicy(makeCandidate())
+
+    expect(candidate.tier).toBe('ready')
+    expect(candidate.selectedByDefault).toBe(true)
+    expect(canSelectWorkspaceCleanupCandidate(candidate)).toBe(true)
+  })
+
+  it('requires an inactivity reason before selecting a workspace', () => {
+    const candidate = applyWorkspaceCleanupPolicy(makeCandidate({ reasons: [] }))
+
+    expect(canSelectWorkspaceCleanupCandidate(candidate)).toBe(false)
+    expect(candidate.tier).toBe('review')
+    expect(candidate.selectedByDefault).toBe(false)
+  })
+
+  it('keeps not-suggested candidates queueable when git evidence is clean', () => {
+    const candidate = applyWorkspaceCleanupPolicy(makeCandidate({ blockers: ['unpushed-commits'] }))
+
+    expect(candidate.tier).toBe('protected')
+    expect(candidate.selectedByDefault).toBe(false)
+    expect(canSelectWorkspaceCleanupCandidate(candidate)).toBe(false)
+    expect(canQueueWorkspaceCleanupCandidate(candidate)).toBe(true)
+    expect(shouldForceWorkspaceCleanupRemoval(candidate)).toBe(true)
+  })
+
+  it('does not queue main worktrees or folder projects for cleanup removal', () => {
+    const mainWorktree = applyWorkspaceCleanupPolicy(makeCandidate({ blockers: ['main-worktree'] }))
+    const folderProject = applyWorkspaceCleanupPolicy(makeCandidate({ blockers: ['folder-repo'] }))
+
+    expect(canQueueWorkspaceCleanupCandidate(mainWorktree)).toBe(false)
+    expect(canQueueWorkspaceCleanupCandidate(folderProject)).toBe(false)
+  })
+
+  it('requires current git status before selecting a workspace', () => {
+    const candidate = applyWorkspaceCleanupPolicy(
+      makeCandidate({
+        git: { clean: null, checkedAt: null }
+      })
+    )
+
+    expect(candidate.tier).toBe('review')
+    expect(canSelectWorkspaceCleanupCandidate(candidate)).toBe(false)
+  })
+
+  it('matches dismissals only for the current classifier fingerprint', () => {
+    const fingerprint = createWorkspaceCleanupFingerprint({
+      branch: 'feature',
+      head: 'abc123',
+      gitClean: true,
+      lastActivityAt: 1_700_000_000_000
+    })
+    const candidate = makeCandidate({ fingerprint })
+
+    expect(
+      shouldHideWorkspaceCleanupCandidate(candidate, {
+        worktreeId: candidate.worktreeId,
+        dismissedAt: 1_700_000_000_000,
+        fingerprint,
+        classifierVersion: WORKSPACE_CLEANUP_CLASSIFIER_VERSION
+      })
+    ).toBe(true)
+    expect(
+      shouldHideWorkspaceCleanupCandidate(candidate, {
+        worktreeId: candidate.worktreeId,
+        dismissedAt: 1_700_000_000_000,
+        fingerprint: `${fingerprint}|changed`,
+        classifierVersion: WORKSPACE_CLEANUP_CLASSIFIER_VERSION
+      })
+    ).toBe(false)
+  })
+})
diff --git a/src/shared/workspace-cleanup.ts b/src/shared/workspace-cleanup.ts
new file mode 100644
index 00000000000..f751b7738a5
--- /dev/null
+++ b/src/shared/workspace-cleanup.ts
@@ -0,0 +1,232 @@
+export const WORKSPACE_CLEANUP_CLASSIFIER_VERSION = 2
+export const WORKSPACE_CLEANUP_ARCHIVED_IDLE_MS = 7 * 24 * 60 * 60 * 1000
+export const WORKSPACE_CLEANUP_IDLE_MS = 30 * 24 * 60 * 60 * 1000
+
+export type WorkspaceCleanupTier = 'ready' | 'review' | 'protected'
+
+export type WorkspaceCleanupReason = 'archived' | 'idle-clean'
+
+export type WorkspaceCleanupInactivityInput = {
+  isArchived: boolean
+  lastActivityAt: number
+}
+
+export type WorkspaceCleanupBlocker =
+  | 'main-worktree'
+  | 'folder-repo'
+  | 'pinned'
+  | 'active-workspace'
+  | 'running-terminal'
+  | 'terminal-liveness-unknown'
+  | 'dirty-editor-buffer'
+  | 'volatile-local-context'
+  | 'recent-visible-context'
+  | 'live-agent'
+  | 'ssh-disconnected'
+  | 'git-status-error'
+  | 'dirty-files'
+  | 'unpushed-commits'
+  | 'unknown-base'
+  | 'dismissed'
+
+export type WorkspaceCleanupDismissal = {
+  worktreeId: string
+  dismissedAt: number
+  fingerprint: string
+  classifierVersion: number
+}
+
+export type WorkspaceCleanupUIState = {
+  dismissals: Record<string, WorkspaceCleanupDismissal>
+}
+
+export type WorkspaceCleanupCandidate = {
+  worktreeId: string
+  repoId: string
+  repoName: string
+  connectionId: string | null
+  displayName: string
+  branch: string
+  path: string
+  tier: WorkspaceCleanupTier
+  selectedByDefault: boolean
+  reasons: WorkspaceCleanupReason[]
+  blockers: WorkspaceCleanupBlocker[]
+  lastActivityAt: number
+  createdAt?: number
+  localContext: {
+    terminalTabCount: number
+    cleanEditorTabCount: number
+    browserTabCount: number
+    diffCommentCount: number
+    newestDiffCommentAt: number | null
+    retainedDoneAgentCount: number
+  }
+  git: {
+    clean: boolean | null
+    upstreamAhead: number | null
+    upstreamBehind: number | null
+    checkedAt: number | null
+  }
+  fingerprint: string
+}
+
+export type WorkspaceCleanupScanArgs = {
+  worktreeId?: string
+  skipGitWorktreeIds?: string[]
+}
+
+export type WorkspaceCleanupLocalProcessArgs = {
+  worktreeId: string
+  connectionId?: string | null
+  worktreePath?: string
+}
+
+export type WorkspaceCleanupScanError = {
+  repoId: string
+  repoName: string
+  message: string
+}
+
+export type WorkspaceCleanupScanResult = {
+  scannedAt: number
+  candidates: WorkspaceCleanupCandidate[]
+  errors: WorkspaceCleanupScanError[]
+}
+
+export type WorkspaceCleanupLocalProcessResult = {
+  hasKillableProcesses: boolean | null
+}
+
+export type WorkspaceCleanupDismissArgs = {
+  dismissals: WorkspaceCleanupDismissal[]
+}
+
+export const WORKSPACE_CLEANUP_HARD_BLOCKERS: ReadonlySet<WorkspaceCleanupBlocker> = new Set([
+  'main-worktree',
+  'folder-repo',
+  'pinned',
+  'active-workspace',
+  'running-terminal',
+  'terminal-liveness-unknown',
+  'dirty-editor-buffer',
+  'volatile-local-context',
+  'live-agent',
+  'recent-visible-context',
+  'ssh-disconnected',
+  'git-status-error',
+  'dirty-files',
+  'unpushed-commits',
+  'unknown-base',
+  'dismissed'
+])
+
+const WORKSPACE_CLEANUP_QUEUE_BLOCKERS: ReadonlySet<WorkspaceCleanupBlocker> = new Set([
+  'main-worktree',
+  'folder-repo',
+  'dismissed'
+])
+
+export const WORKSPACE_CLEANUP_FORCE_REMOVE_BLOCKERS: ReadonlySet<WorkspaceCleanupBlocker> =
+  new Set(['dirty-files', 'unpushed-commits', 'unknown-base', 'git-status-error'])
+
+export function isWorkspaceCleanupHardBlocker(blocker: WorkspaceCleanupBlocker): boolean {
+  return WORKSPACE_CLEANUP_HARD_BLOCKERS.has(blocker)
+}
+
+export function canQueueWorkspaceCleanupCandidate(
+  candidate: Pick<WorkspaceCleanupCandidate, 'blockers' | 'reasons'>
+): boolean {
+  return (
+    candidate.reasons.length > 0 &&
+    !candidate.blockers.some((blocker) => WORKSPACE_CLEANUP_QUEUE_BLOCKERS.has(blocker))
+  )
+}
+
+export function shouldForceWorkspaceCleanupRemoval(
+  candidate: Pick<WorkspaceCleanupCandidate, 'blockers' | 'git'>
+): boolean {
+  return (
+    candidate.git.clean !== true ||
+    candidate.git.checkedAt === null ||
+    candidate.blockers.some((blocker) => WORKSPACE_CLEANUP_FORCE_REMOVE_BLOCKERS.has(blocker))
+  )
+}
+
+export function canSelectWorkspaceCleanupCandidate(
+  candidate: Pick<WorkspaceCleanupCandidate, 'blockers' | 'git' | 'reasons'>
+): boolean {
+  return (
+    candidate.reasons.length > 0 &&
+    candidate.git.clean === true &&
+    candidate.git.checkedAt !== null &&
+    !candidate.blockers.some(isWorkspaceCleanupHardBlocker)
+  )
+}
+
+export function applyWorkspaceCleanupPolicy(
+  candidate: WorkspaceCleanupCandidate
+): WorkspaceCleanupCandidate {
+  const canSelect = canSelectWorkspaceCleanupCandidate(candidate)
+  const hasHardBlocker = candidate.blockers.some(isWorkspaceCleanupHardBlocker)
+  const tier: WorkspaceCleanupTier = hasHardBlocker ? 'protected' : canSelect ? 'ready' : 'review'
+
+  return {
+    ...candidate,
+    tier,
+    selectedByDefault: tier === 'ready' && canSelect
+  }
+}
+
+export function createWorkspaceCleanupFingerprint(args: {
+  branch: string
+  head: string
+  gitClean: boolean | null
+  lastActivityAt: number
+  classifierVersion?: number
+}): string {
+  const version = args.classifierVersion ?? WORKSPACE_CLEANUP_CLASSIFIER_VERSION
+  const lastActivityBucket = Math.floor((args.lastActivityAt || 0) / (24 * 60 * 60 * 1000))
+  return [
+    version,
+    args.branch,
+    args.head,
+    args.gitClean === null ? 'unknown' : args.gitClean ? 'clean' : 'dirty',
+    lastActivityBucket
+  ].join('|')
+}
+
+export function getWorkspaceCleanupInactivityReasons(
+  workspace: WorkspaceCleanupInactivityInput,
+  scannedAt: number
+): WorkspaceCleanupReason[] {
+  const reasons: WorkspaceCleanupReason[] = []
+  if (
+    workspace.isArchived &&
+    scannedAt - workspace.lastActivityAt >= WORKSPACE_CLEANUP_ARCHIVED_IDLE_MS
+  ) {
+    reasons.push('archived')
+  }
+  if (scannedAt - workspace.lastActivityAt >= WORKSPACE_CLEANUP_IDLE_MS) {
+    reasons.push('idle-clean')
+  }
+  return reasons
+}
+
+export function isWorkspaceOldForCleanup(
+  workspace: WorkspaceCleanupInactivityInput,
+  scannedAt: number
+): boolean {
+  return getWorkspaceCleanupInactivityReasons(workspace, scannedAt).length > 0
+}
+
+export function shouldHideWorkspaceCleanupCandidate(
+  candidate: Pick<WorkspaceCleanupCandidate, 'worktreeId' | 'fingerprint'>,
+  dismissal: WorkspaceCleanupDismissal | undefined
+): boolean {
+  return (
+    dismissal?.worktreeId === candidate.worktreeId &&
+    dismissal.fingerprint === candidate.fingerprint &&
+    dismissal.classifierVersion === WORKSPACE_CLEANUP_CLASSIFIER_VERSION
+  )
+}

From b10177b8e4b6609c41b5cfc351f66796d90ebb84 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 15 May 2026 14:01:27 -0700
Subject: [PATCH 79/82] Fix code pointer line reveals

---
 .../src/components/editor/MarkdownPreview.tsx | 33 ++++---
 .../src/components/editor/MonacoEditor.tsx    | 85 +++++++++++--------
 .../editor/MonacoGutterContextMenu.tsx        |  9 +-
 .../components/editor/line-copy-path.test.ts  | 10 +++
 .../src/components/editor/line-copy-path.ts   |  3 +
 .../editor/markdown-internal-links.test.ts    | 11 +++
 .../editor/markdown-internal-links.ts         | 19 ++++-
 .../src/components/editor/monaco-reveal.ts    |  2 +
 src/renderer/src/store/slices/editor.test.ts  | 24 ++++++
 src/renderer/src/store/slices/editor.ts       | 41 +++++----
 10 files changed, 170 insertions(+), 67 deletions(-)
 create mode 100644 src/renderer/src/components/editor/line-copy-path.test.ts
 create mode 100644 src/renderer/src/components/editor/line-copy-path.ts

diff --git a/src/renderer/src/components/editor/MarkdownPreview.tsx b/src/renderer/src/components/editor/MarkdownPreview.tsx
index 90d755ce0c2..29cda7cd53d 100644
--- a/src/renderer/src/components/editor/MarkdownPreview.tsx
+++ b/src/renderer/src/components/editor/MarkdownPreview.tsx
@@ -800,13 +800,18 @@ export default function MarkdownPreview({
                 return
               }
               const classified = resolveMarkdownLinkTarget(href, filePath, worktreeRoot)
-              if (classified?.kind === 'markdown') {
+              if (
+                classified?.kind === 'markdown' ||
+                (classified?.kind === 'file' && classified.line !== undefined)
+              ) {
                 // Why: use the classifier's stripped absolutePath (no `:line:col`
                 // or `#L10` suffix) so the OS handler receives a clean file URI.
                 const cleanUri = absolutePathToFileUri(classified.absolutePath)
                 void window.api.shell.pathExists(classified.absolutePath).then((exists) => {
                   if (!exists) {
-                    toast.error(`File not found: ${classified.relativePath}`)
+                    toast.error(
+                      `File not found: ${classified.relativePath ?? classified.absolutePath}`
+                    )
                     return
                   }
                   void window.api.shell.openFileUri(cleanUri)
@@ -832,12 +837,19 @@ export default function MarkdownPreview({
             return
           }
 
-          const absolutePath = fileUrlToAbsolutePath(target)
+          const classified = resolveMarkdownLinkTarget(href, filePath, worktreeRoot)
+          const classifiedFileTarget =
+            classified?.kind === 'markdown' || classified?.kind === 'file' ? classified : null
+          const absolutePath = classifiedFileTarget?.absolutePath ?? fileUrlToAbsolutePath(target)
           if (!absolutePath) {
             return
           }
+          const lineTarget =
+            classifiedFileTarget?.line !== undefined
+              ? { line: classifiedFileTarget.line, column: classifiedFileTarget.column }
+              : parseLineTarget(target.hash)
 
-          if (absolutePath === filePath && target.hash) {
+          if (absolutePath === filePath && target.hash && !lineTarget) {
             void scrollToAnchor(target.hash.slice(1))
             return
           }
@@ -874,13 +886,12 @@ export default function MarkdownPreview({
           const relativePath = absolutePath.slice(targetWorktree.path.length + 1)
           const language = detectLanguage(absolutePath)
 
-          // Why: line-target fragments like #L10 or #L10C5 should open the
-          // source editor and reveal the line, not open a preview tab that
-          // treats "L10" as a heading anchor.
-          const lineTarget = parseLineTarget(target.hash)
-          if (language === 'markdown' && lineTarget) {
-            const fileId = absolutePath
-            setMarkdownViewMode(fileId, 'source')
+          // Why: line targets like #L10 and path.ts:10 should reveal in Monaco,
+          // not open a preview tab or a literal path with the suffix included.
+          if (lineTarget) {
+            if (language === 'markdown') {
+              setMarkdownViewMode(absolutePath, 'source')
+            }
             openFile({
               filePath: absolutePath,
               relativePath,
diff --git a/src/renderer/src/components/editor/MonacoEditor.tsx b/src/renderer/src/components/editor/MonacoEditor.tsx
index fe966e7730b..82df9211ae0 100644
--- a/src/renderer/src/components/editor/MonacoEditor.tsx
+++ b/src/renderer/src/components/editor/MonacoEditor.tsx
@@ -11,7 +11,7 @@ import '@/lib/monaco-setup'
 import { computeEditorFontSize } from '@/lib/editor-font-zoom'
 
 import { useContextualCopySetup } from './useContextualCopySetup'
-import { performReveal } from './monaco-reveal'
+import { MAX_REVEAL_CONTENT_WAIT_FRAMES, performReveal } from './monaco-reveal'
 import { syncContentOnMount, syncContentUpdate } from './monaco-content-sync'
 import {
   beginProgrammaticContentSync,
@@ -104,6 +104,21 @@ export default function MonacoEditor({
     settings?.terminalFontSize ?? 13,
     editorFontZoomLevel
   )
+  // Why: `keepCurrentModel` retains Monaco models across unmounts, and
+  // @monaco-editor/react skips its value→model sync on the first render after
+  // a remount. Without explicit sync, external file changes that arrived
+  // while the tab was unmounted leave the retained model showing stale text.
+  // contentRef lets handleMount read the current content without re-binding;
+  // lastSyncedContentRef lets the update effect distinguish our own onChange
+  // emissions from real prop drift.
+  // Invariant: the mount path (handleMount's syncContentOnMount call) MUST
+  // read `contentRef.current`, never `lastSyncedContentRef.current`. The
+  // useLayoutEffect below can run before mount with `editorRef.current === null`
+  // and bails without updating lastSyncedContentRef, so that ref may be stale
+  // pre-mount; only contentRef is guaranteed to reflect the latest prop.
+  const contentRef = useRef(content)
+  contentRef.current = content
+  const lastSyncedContentRef = useRef<string>(content)
   const markdownComments = useMemo(
     () =>
       (allDiffComments ?? []).filter((c) => c.filePath === relativePath && isMarkdownComment(c)),
@@ -197,46 +212,46 @@ export default function MonacoEditor({
       onApplied?: () => void
     ) => {
       cancelScheduledReveal()
+      let waitFrames = 0
 
-      // Why: the search click path already waits two frames before publishing
-      // the reveal intent, but Monaco can still mount before its viewport math
-      // settles. Deferring the actual reveal by two editor-owned frames keeps
-      // scroll-to-match and inline highlight deterministic on fresh opens.
-      revealRafRef.current = requestAnimationFrame(() => {
-        revealInnerRafRef.current = requestAnimationFrame(() => {
-          performReveal(
-            editorInstance,
-            line,
-            column,
-            matchLength,
-            clearTransientRevealHighlight,
-            revealDecorationRef,
-            revealHighlightTimerRef
-          )
-          onApplied?.()
-          revealRafRef.current = null
-          revealInnerRafRef.current = null
+      const schedule = (): void => {
+        // Why: the search click path already waits two frames before publishing
+        // the reveal intent, but Monaco can still mount before its viewport math
+        // settles. Deferring the actual reveal by two editor-owned frames keeps
+        // scroll-to-match and inline highlight deterministic on fresh opens.
+        revealRafRef.current = requestAnimationFrame(() => {
+          revealInnerRafRef.current = requestAnimationFrame(() => {
+            revealRafRef.current = null
+            revealInnerRafRef.current = null
+            const modelLineCount = editorInstance.getModel()?.getLineCount() ?? 0
+            if (line > 1 && modelLineCount < line && waitFrames < MAX_REVEAL_CONTENT_WAIT_FRAMES) {
+              // Why: fresh file opens can mount Monaco against an empty one-line
+              // model before the async file read arrives. Waiting prevents the
+              // requested line from being clamped to 1 and then cleared.
+              waitFrames += 2
+              schedule()
+              return
+            }
+
+            performReveal(
+              editorInstance,
+              line,
+              column,
+              matchLength,
+              clearTransientRevealHighlight,
+              revealDecorationRef,
+              revealHighlightTimerRef
+            )
+            onApplied?.()
+          })
         })
-      })
+      }
+
+      schedule()
     },
     [cancelScheduledReveal, clearTransientRevealHighlight]
   )
 
-  // Why: `keepCurrentModel` retains Monaco models across unmounts, and
-  // @monaco-editor/react skips its value→model sync on the first render after
-  // a remount. Without explicit sync, external file changes that arrived
-  // while the tab was unmounted leave the retained model showing stale text.
-  // contentRef lets handleMount read the current content without re-binding;
-  // lastSyncedContentRef lets the update effect distinguish our own onChange
-  // emissions from real prop drift.
-  // Invariant: the mount path (handleMount's syncContentOnMount call) MUST
-  // read `contentRef.current`, never `lastSyncedContentRef.current`. The
-  // useLayoutEffect below can run before mount with `editorRef.current === null`
-  // and bails without updating lastSyncedContentRef, so that ref may be stale
-  // pre-mount; only contentRef is guaranteed to reflect the latest prop.
-  const contentRef = useRef(content)
-  contentRef.current = content
-  const lastSyncedContentRef = useRef<string>(content)
   // Why: Monaco model reconciliation reuses real edit operations so retained
   // models keep sane undo behavior. Those edits are programmatic, not user
   // typing, so split panes must suppress the resulting onChange callback or a
diff --git a/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx b/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx
index a702e9d6d5b..1b6db18d423 100644
--- a/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx
+++ b/src/renderer/src/components/editor/MonacoGutterContextMenu.tsx
@@ -10,6 +10,7 @@ import { useAppStore } from '@/store'
 import { getConnectionId } from '@/lib/connection-context'
 import { findWorktreeById } from '@/store/slices/worktree-helpers'
 import { getRuntimeGitRemoteFileUrl } from '@/runtime/runtime-git-client'
+import { formatPathLineReference } from './line-copy-path'
 
 type MonacoGutterContextMenuProps = {
   open: boolean
@@ -39,12 +40,16 @@ export function MonacoGutterContextMenu({
         />
       </DropdownMenuTrigger>
       <DropdownMenuContent sideOffset={0} align="start">
-        <DropdownMenuItem onSelect={() => window.api.ui.writeClipboardText(`${filePath}#L${line}`)}>
+        <DropdownMenuItem
+          onSelect={() => window.api.ui.writeClipboardText(formatPathLineReference(filePath, line))}
+        >
           <Copy className="w-3.5 h-3.5 mr-1.5" />
           Copy Path to Line
         </DropdownMenuItem>
         <DropdownMenuItem
-          onSelect={() => window.api.ui.writeClipboardText(`${relativePath}#L${line}`)}
+          onSelect={() =>
+            window.api.ui.writeClipboardText(formatPathLineReference(relativePath, line))
+          }
         >
           <Copy className="w-3.5 h-3.5 mr-1.5" />
           Copy Rel. Path to Line
diff --git a/src/renderer/src/components/editor/line-copy-path.test.ts b/src/renderer/src/components/editor/line-copy-path.test.ts
new file mode 100644
index 00000000000..b4d90556fb4
--- /dev/null
+++ b/src/renderer/src/components/editor/line-copy-path.test.ts
@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest'
+import { formatPathLineReference } from './line-copy-path'
+
+describe('formatPathLineReference', () => {
+  it('uses the standard path:line format', () => {
+    expect(formatPathLineReference('src/components/PdfViewer.tsx', 142)).toBe(
+      'src/components/PdfViewer.tsx:142'
+    )
+  })
+})
diff --git a/src/renderer/src/components/editor/line-copy-path.ts b/src/renderer/src/components/editor/line-copy-path.ts
new file mode 100644
index 00000000000..47623c1ff39
--- /dev/null
+++ b/src/renderer/src/components/editor/line-copy-path.ts
@@ -0,0 +1,3 @@
+export function formatPathLineReference(filePath: string, line: number): string {
+  return `${filePath}:${line}`
+}
diff --git a/src/renderer/src/components/editor/markdown-internal-links.test.ts b/src/renderer/src/components/editor/markdown-internal-links.test.ts
index 11a9824e6eb..95e8e6407f5 100644
--- a/src/renderer/src/components/editor/markdown-internal-links.test.ts
+++ b/src/renderer/src/components/editor/markdown-internal-links.test.ts
@@ -44,6 +44,17 @@ describe('resolveMarkdownLinkTarget', () => {
     expect(r).toMatchObject({ kind: 'markdown', line: 10, column: 5 })
   })
 
+  it('extracts line+col from non-markdown file links', () => {
+    const r = resolveMarkdownLinkTarget('../src/PdfViewer.tsx:142:7', SOURCE, ROOT)
+    expect(r).toMatchObject({
+      kind: 'file',
+      absolutePath: '/repo/src/PdfViewer.tsx',
+      relativePath: 'src/PdfViewer.tsx',
+      line: 142,
+      column: 7
+    })
+  })
+
   it('ignores non-line-col hashes', () => {
     const r = resolveMarkdownLinkTarget('./guide.md#intro', SOURCE, ROOT)
     expect(r).toMatchObject({ kind: 'markdown', line: undefined, column: undefined })
diff --git a/src/renderer/src/components/editor/markdown-internal-links.ts b/src/renderer/src/components/editor/markdown-internal-links.ts
index c2512629a59..deac13b4c50 100644
--- a/src/renderer/src/components/editor/markdown-internal-links.ts
+++ b/src/renderer/src/components/editor/markdown-internal-links.ts
@@ -15,7 +15,14 @@ export type MarkdownLinkTarget =
       line?: number
       column?: number
     }
-  | { kind: 'file'; uri: string; absolutePath: string; relativePath?: string }
+  | {
+      kind: 'file'
+      uri: string
+      absolutePath: string
+      relativePath?: string
+      line?: number
+      column?: number
+    }
 
 // Why: renderer runs with sandbox + contextIsolation, so process.platform is
 // unavailable. navigator.userAgent is the portable fallback (AGENTS.md).
@@ -210,8 +217,12 @@ export function resolveMarkdownLinkTarget(
   // approximation; for trailing-colon paths there's no clean URL form,
   // so we reconstruct from the stripped absolute path.
   const cleanUri = line === undefined ? resolved.toString() : toFileUrl(pathForClassification)
-  if (line === undefined) {
-    return { kind: 'file', uri: cleanUri, absolutePath: pathForClassification, relativePath }
+  return {
+    kind: 'file',
+    uri: cleanUri,
+    absolutePath: pathForClassification,
+    relativePath,
+    line,
+    column
   }
-  return { kind: 'file', uri: cleanUri, absolutePath: pathForClassification, relativePath }
 }
diff --git a/src/renderer/src/components/editor/monaco-reveal.ts b/src/renderer/src/components/editor/monaco-reveal.ts
index 3ab623da329..1a6d1510f5b 100644
--- a/src/renderer/src/components/editor/monaco-reveal.ts
+++ b/src/renderer/src/components/editor/monaco-reveal.ts
@@ -2,6 +2,8 @@ import type React from 'react'
 import type { editor } from 'monaco-editor'
 import { computeMonacoRevealRange } from './monaco-reveal-range'
 
+export const MAX_REVEAL_CONTENT_WAIT_FRAMES = 120
+
 /**
  * Shared reveal logic used by both onMount and useEffect paths in MonacoEditor.
  * Positions the cursor, optionally selects the match range, scrolls into center,
diff --git a/src/renderer/src/store/slices/editor.test.ts b/src/renderer/src/store/slices/editor.test.ts
index 875946f1d4a..9ec1e7a766a 100644
--- a/src/renderer/src/store/slices/editor.test.ts
+++ b/src/renderer/src/store/slices/editor.test.ts
@@ -1457,6 +1457,30 @@ describe('createEditorSlice activateMarkdownLink', () => {
     expect(openFileUriMock).not.toHaveBeenCalled()
   })
 
+  it('reveals line targets for non-markdown file links', async () => {
+    const store = createEditorStore()
+    await store.getState().activateMarkdownLink('../src/PdfViewer.tsx:142:7', {
+      sourceFilePath: '/repo/docs/note.md',
+      worktreeId: 'wt-1',
+      worktreeRoot: '/repo'
+    })
+
+    expect(store.getState().openFiles).toEqual([
+      expect.objectContaining({
+        filePath: '/repo/src/PdfViewer.tsx',
+        relativePath: 'src/PdfViewer.tsx',
+        mode: 'edit',
+        isPreview: true
+      })
+    ])
+    expect(store.getState().pendingEditorReveal).toEqual({
+      filePath: '/repo/src/PdfViewer.tsx',
+      line: 142,
+      column: 7,
+      matchLength: 0
+    })
+  })
+
   it('opens explicit file URLs inside the worktree in Orca', async () => {
     const store = createEditorStore()
     await store.getState().activateMarkdownLink('file:///repo/docs/image.png', {
diff --git a/src/renderer/src/store/slices/editor.ts b/src/renderer/src/store/slices/editor.ts
index 74fe667f474..b93ceeee6a6 100644
--- a/src/renderer/src/store/slices/editor.ts
+++ b/src/renderer/src/store/slices/editor.ts
@@ -157,6 +157,27 @@ export type ClosedEditorTabSnapshot = Omit<OpenFile, 'id' | 'isDirty'>
 
 const MAX_RECENT_CLOSED_EDITOR_TABS = 10
 
+function scheduleEditorLineReveal(
+  get: () => AppState,
+  filePath: string,
+  line: number,
+  column?: number
+): void {
+  // Why: openFile can replace a preview and remount Monaco asynchronously; the
+  // reveal must land after that remount or the old editor can clear it.
+  get().setPendingEditorReveal(null)
+  requestAnimationFrame(() => {
+    requestAnimationFrame(() => {
+      get().setPendingEditorReveal({
+        filePath,
+        line,
+        column: column ?? 1,
+        matchLength: 0
+      })
+    })
+  })
+}
+
 export type EditorSlice = {
   // Why: #300 originally kept EditorPanel mounted while hidden so unsaved
   // drafts and autosave timers could survive tab switches. Drafts live in the
@@ -2226,6 +2247,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
       return
     }
     if (target.kind === 'file') {
+      const { line, column } = target
       if (target.relativePath === undefined) {
         if (sourceSettings?.activeRuntimeEnvironmentId?.trim()) {
           // Why: a file:// link outside the worktree is a client-local escape
@@ -2255,6 +2277,9 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
           recordReplacedPreview: true
         }
       )
+      if (line !== undefined) {
+        scheduleEditorLineReveal(get, target.absolutePath, line, column)
+      }
       return
     }
 
@@ -2311,21 +2336,7 @@ export const createEditorSlice: StateCreator<AppState, [], [], EditorSlice> = (s
     }
 
     if (line !== undefined) {
-      // Why: double-RAF matches search-match-open.ts. openFile may replace a
-      // preview, remounting Monaco asynchronously; the mount's own
-      // setPendingEditorReveal(null) would otherwise clobber a reveal scheduled
-      // in the same tick.
-      get().setPendingEditorReveal(null)
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          get().setPendingEditorReveal({
-            filePath: absolutePath,
-            line,
-            column: column ?? 1,
-            matchLength: 0
-          })
-        })
-      })
+      scheduleEditorLineReveal(get, absolutePath, line, column)
     }
   },
 

From 0cb2da1b45dd7a12fde3b28df195f4bb1b456457 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 14:02:52 -0700
Subject: [PATCH 80/82] Add settings for task providers (#1977)

---
 .../runtime-home-service.test.ts              |   1 +
 src/main/codex-accounts/service.test.ts       |   1 +
 src/main/persistence.test.ts                  |  17 +++
 src/main/persistence.ts                       |   9 ++
 src/renderer/src/components/TaskPage.tsx      |  47 +++++-
 .../src/components/settings/Settings.tsx      |  20 +++
 .../src/components/settings/TasksPane.tsx     | 142 ++++++++++++++++++
 .../src/components/settings/tasks-search.ts   |   9 ++
 .../src/components/sidebar/SidebarNav.tsx     | 120 +++++++++------
 src/renderer/src/store/slices/settings.ts     |   6 +
 src/renderer/src/store/slices/ui.ts           |  14 +-
 src/shared/constants.ts                       |   2 +
 src/shared/task-providers.test.ts             |  19 +++
 src/shared/task-providers.ts                  |  35 +++++
 src/shared/types.ts                           |   8 +-
 15 files changed, 395 insertions(+), 55 deletions(-)
 create mode 100644 src/renderer/src/components/settings/TasksPane.tsx
 create mode 100644 src/renderer/src/components/settings/tasks-search.ts
 create mode 100644 src/shared/task-providers.test.ts
 create mode 100644 src/shared/task-providers.ts

diff --git a/src/main/codex-accounts/runtime-home-service.test.ts b/src/main/codex-accounts/runtime-home-service.test.ts
index 50b31ee9f5c..6dc357320bd 100644
--- a/src/main/codex-accounts/runtime-home-service.test.ts
+++ b/src/main/codex-accounts/runtime-home-service.test.ts
@@ -93,6 +93,7 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     skipDeleteAutomationConfirm: false,
     defaultTaskViewPreset: 'all',
     defaultTaskSource: 'github',
+    visibleTaskProviders: ['github', 'gitlab', 'linear'],
     defaultRepoSelection: null,
     defaultLinearTeamSelection: null,
     opencodeSessionCookie: '',
diff --git a/src/main/codex-accounts/service.test.ts b/src/main/codex-accounts/service.test.ts
index 40532ad3c8e..41ac18b260f 100644
--- a/src/main/codex-accounts/service.test.ts
+++ b/src/main/codex-accounts/service.test.ts
@@ -86,6 +86,7 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     skipDeleteAutomationConfirm: false,
     defaultTaskViewPreset: 'all',
     defaultTaskSource: 'github',
+    visibleTaskProviders: ['github', 'gitlab', 'linear'],
     defaultRepoSelection: null,
     defaultLinearTeamSelection: null,
     opencodeSessionCookie: '',
diff --git a/src/main/persistence.test.ts b/src/main/persistence.test.ts
index ec9aceee279..1b6b38cc064 100644
--- a/src/main/persistence.test.ts
+++ b/src/main/persistence.test.ts
@@ -165,6 +165,7 @@ describe('Store', () => {
     expect(settings.terminalFontWeight).toBe(500)
     expect(settings.rightSidebarOpenByDefault).toBe(true)
     expect(settings.showTasksButton).toBe(true)
+    expect(settings.visibleTaskProviders).toEqual(['github', 'gitlab', 'linear'])
     expect(settings.experimentalActivity).toBe(true)
     expect(settings.floatingTerminalEnabled).toBe(true)
     expect(settings.floatingTerminalDefaultedForAllUsers).toBe(true)
@@ -306,12 +307,28 @@ describe('Store', () => {
     expect(store.getSettings().refreshLocalBaseRefOnWorktreeCreate).toBe(false)
     expect(store.getSettings().rightSidebarOpenByDefault).toBe(true)
     expect(store.getSettings().showTasksButton).toBe(true)
+    expect(store.getSettings().visibleTaskProviders).toEqual(['github', 'gitlab', 'linear'])
     expect(store.getSettings().experimentalActivity).toBe(true)
     expect(store.getSettings().notifications.customSoundPath).toBeNull()
     // repos should be loaded
     expect(store.getRepos()).toHaveLength(1)
   })
 
+  it('normalizes malformed visible task providers on load', async () => {
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [],
+      worktreeMeta: {},
+      settings: { visibleTaskProviders: ['gitlab', 'unknown', 'gitlab'] },
+      ui: {},
+      githubCache: { pr: {}, issue: {} },
+      workspaceSession: {}
+    })
+
+    const store = await createStore()
+    expect(store.getSettings().visibleTaskProviders).toEqual(['gitlab'])
+  })
+
   it('migrates the legacy floating terminal disabled default to enabled', async () => {
     writeDataFile({
       schemaVersion: 1,
diff --git a/src/main/persistence.ts b/src/main/persistence.ts
index 00bb9bc4409..5f1aab4c33f 100644
--- a/src/main/persistence.ts
+++ b/src/main/persistence.ts
@@ -66,6 +66,7 @@ import { pruneLocalTerminalScrollbackBuffers } from '../shared/workspace-session
 import { pruneWorkspaceSessionBrowserHistory } from '../shared/workspace-session-browser-history'
 import { getRepoIdFromWorktreeId } from '../shared/worktree-id'
 import { normalizeTerminalQuickCommands } from '../shared/terminal-quick-commands'
+import { normalizeVisibleTaskProviders } from '../shared/task-providers'
 import {
   DEFAULT_WORKSPACE_STATUS_ID,
   clampWorkspaceBoardOpacity,
@@ -989,6 +990,9 @@ export class Store {
             terminalQuickCommands: normalizeTerminalQuickCommands(
               parsed.settings?.terminalQuickCommands
             ),
+            visibleTaskProviders: normalizeVisibleTaskProviders(
+              parsed.settings?.visibleTaskProviders
+            ),
             notifications: {
               ...getDefaultNotificationSettings(),
               ...parsed.settings?.notifications
@@ -1741,6 +1745,11 @@ export class Store {
         updates.terminalQuickCommands
       )
     }
+    if ('visibleTaskProviders' in updates) {
+      sanitizedUpdates.visibleTaskProviders = normalizeVisibleTaskProviders(
+        updates.visibleTaskProviders
+      )
+    }
     // Why: `telemetry` is deep-merged for the same reason `notifications` is —
     // partial updates from the Privacy pane / consent flow (e.g., flipping
     // only `optedIn`) must not clobber sibling fields like `installId` or
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 37cc7d74a79..f67d38c33a4 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -88,12 +88,17 @@ import type {
   LinearIssue,
   LinearTeam,
   Repo,
+  TaskProvider,
   TaskViewPresetId
 } from '../../../shared/types'
 import { shouldSuppressEnterSubmit } from '@/lib/new-workspace-enter-guard'
 import { linearCreateIssue, linearGetIssue, linearListTeams } from '@/runtime/runtime-linear-client'
+import {
+  normalizeVisibleTaskProviders,
+  resolveVisibleTaskProvider
+} from '../../../shared/task-providers'
 
-type TaskSource = 'github' | 'linear' | 'gitlab'
+type TaskSource = TaskProvider
 
 type GitLabTaskFilter = 'opened' | 'merged' | 'closed' | 'all'
 
@@ -605,6 +610,14 @@ export default function TaskPage(): React.JSX.Element {
     linearStatus.activeWorkspaceId ??
     linearWorkspaces[0]?.id ??
     null
+  const visibleTaskProviders = useMemo(
+    () => normalizeVisibleTaskProviders(settings?.visibleTaskProviders),
+    [settings?.visibleTaskProviders]
+  )
+  const visibleSourceOptions = useMemo(
+    () => SOURCE_OPTIONS.filter((source) => visibleTaskProviders.includes(source.id)),
+    [visibleTaskProviders]
+  )
 
   // Why: seed the preset + query from the user's saved default synchronously
   // so the first fetch effect issues exactly one request keyed to the final
@@ -615,7 +628,9 @@ export default function TaskPage(): React.JSX.Element {
   const initialTaskQuery = getTaskPresetQuery(defaultTaskViewPreset)
 
   const defaultTaskSource = settings?.defaultTaskSource ?? 'github'
-  const [taskSource, setTaskSource] = useState<TaskSource>(pageData.taskSource ?? defaultTaskSource)
+  const [taskSource, setTaskSource] = useState<TaskSource>(
+    resolveVisibleTaskProvider(pageData.taskSource ?? defaultTaskSource, visibleTaskProviders)
+  )
   const taskResumeAppliedRef = useRef(false)
   const githubSearchPersistReadyRef = useRef(false)
   const linearSearchPersistReadyRef = useRef(false)
@@ -626,9 +641,15 @@ export default function TaskPage(): React.JSX.Element {
   // initializes once, so sync from the store when the value changes.
   useEffect(() => {
     if (pageData.taskSource) {
-      setTaskSource(pageData.taskSource)
+      setTaskSource(resolveVisibleTaskProvider(pageData.taskSource, visibleTaskProviders))
     }
-  }, [pageData.taskSource])
+  }, [pageData.taskSource, visibleTaskProviders])
+
+  useEffect(() => {
+    if (!visibleTaskProviders.includes(taskSource)) {
+      setTaskSource(resolveVisibleTaskProvider(settings?.defaultTaskSource, visibleTaskProviders))
+    }
+  }, [settings?.defaultTaskSource, taskSource, visibleTaskProviders])
 
   // Why: Project mode is a sub-tab within the GitHub source. Visible whenever
   // the user is on the GitHub task source — actual entry into Project mode is
@@ -876,7 +897,12 @@ export default function TaskPage(): React.JSX.Element {
       return
     }
 
-    setTaskSource(pageData.taskSource ?? settings.defaultTaskSource)
+    setTaskSource(
+      resolveVisibleTaskProvider(
+        pageData.taskSource ?? settings.defaultTaskSource,
+        visibleTaskProviders
+      )
+    )
     setRepoSelection(resolvedInitialSelection)
 
     const nextGithubMode = taskResumeState?.githubMode ?? 'items'
@@ -906,7 +932,14 @@ export default function TaskPage(): React.JSX.Element {
     // Tasks context exactly once so later source/filter clicks remain local.
     taskResumeAppliedRef.current = true
     setTaskResumeApplied(true)
-  }, [persistedUIReady, settings, pageData.taskSource, resolvedInitialSelection, taskResumeState])
+  }, [
+    persistedUIReady,
+    settings,
+    pageData.taskSource,
+    resolvedInitialSelection,
+    taskResumeState,
+    visibleTaskProviders
+  ])
 
   // Why: fetch the full team list from the Linear API so the selector shows
   // all teams the user belongs to, not just teams with issues in the current
@@ -1925,7 +1958,7 @@ export default function TaskPage(): React.JSX.Element {
                       </TooltipContent>
                     </Tooltip>
                     <div className="mx-1 h-5 w-px bg-border/50" aria-hidden />
-                    {SOURCE_OPTIONS.map((source) => {
+                    {visibleSourceOptions.map((source) => {
                       const active = taskSource === source.id
                       return (
                         <Tooltip key={source.id}>
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 9d377436631..2938353c754 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -10,6 +10,7 @@ import {
   Globe,
   Info,
   Keyboard,
+  ListChecks,
   Lock,
   MousePointerClick,
   Network,
@@ -56,6 +57,8 @@ import { ORCHESTRATION_PANE_SEARCH_ENTRIES } from './orchestration-search'
 import { AccountsPane, ACCOUNTS_PANE_SEARCH_ENTRIES } from './AccountsPane'
 import { StatsPane, STATS_PANE_SEARCH_ENTRIES } from '../stats/StatsPane'
 import { IntegrationsPane, INTEGRATIONS_PANE_SEARCH_ENTRIES } from './IntegrationsPane'
+import { TasksPane } from './TasksPane'
+import { TASKS_PANE_SEARCH_ENTRIES } from './tasks-search'
 import {
   DeveloperPermissionsPane,
   DEVELOPER_PERMISSIONS_PANE_SEARCH_ENTRIES
@@ -80,6 +83,7 @@ type SettingsNavTarget =
   | 'accounts'
   | 'browser'
   | 'git'
+  | 'tasks'
   | 'appearance'
   | 'terminal'
   | 'notifications'
@@ -447,6 +451,13 @@ function Settings(): React.JSX.Element {
         // "claude" or "thinking" still surfaces the section.
         searchEntries: [...GIT_PANE_SEARCH_ENTRIES, ...COMMIT_MESSAGE_AI_PANE_SEARCH_ENTRIES]
       },
+      {
+        id: 'tasks',
+        title: 'Tasks',
+        description: 'Choose which task providers appear in the Tasks page and sidebar.',
+        icon: ListChecks,
+        searchEntries: TASKS_PANE_SEARCH_ENTRIES
+      },
       {
         id: 'appearance',
         title: 'Appearance',
@@ -831,6 +842,15 @@ function Settings(): React.JSX.Element {
                   <CommitMessageAiPane settings={settings} updateSettings={updateSettings} />
                 </SettingsSection>
 
+                <SettingsSection
+                  id="tasks"
+                  title="Tasks"
+                  description="Choose which task providers appear in the Tasks page and sidebar."
+                  searchEntries={TASKS_PANE_SEARCH_ENTRIES}
+                >
+                  <TasksPane settings={settings} updateSettings={updateSettings} />
+                </SettingsSection>
+
                 <SettingsSection
                   id="appearance"
                   title="Appearance"
diff --git a/src/renderer/src/components/settings/TasksPane.tsx b/src/renderer/src/components/settings/TasksPane.tsx
new file mode 100644
index 00000000000..7bf4e50f005
--- /dev/null
+++ b/src/renderer/src/components/settings/TasksPane.tsx
@@ -0,0 +1,142 @@
+import { Check, Github, Gitlab } from 'lucide-react'
+import type { GlobalSettings, TaskProvider } from '../../../../shared/types'
+import {
+  TASK_PROVIDERS,
+  normalizeVisibleTaskProviders,
+  resolveVisibleTaskProvider
+} from '../../../../shared/task-providers'
+import { cn } from '@/lib/utils'
+import { LinearIcon } from '@/components/icons/LinearIcon'
+import { Label } from '../ui/label'
+import { SearchableSetting } from './SearchableSetting'
+
+type TasksPaneProps = {
+  settings: GlobalSettings
+  updateSettings: (updates: Partial<GlobalSettings>) => void
+}
+
+const TASK_PROVIDER_OPTIONS: readonly {
+  id: TaskProvider
+  label: string
+  description: string
+  Icon: (props: { className?: string }) => React.JSX.Element
+}[] = [
+  {
+    id: 'github',
+    label: 'GitHub',
+    description: 'Show GitHub in the Tasks source picker and sidebar shortcuts.',
+    Icon: ({ className }) => <Github className={className} />
+  },
+  {
+    id: 'gitlab',
+    label: 'GitLab',
+    description: 'Show GitLab in the Tasks source picker and sidebar shortcuts.',
+    Icon: ({ className }) => <Gitlab className={className} />
+  },
+  {
+    id: 'linear',
+    label: 'Linear',
+    description: 'Show Linear in the Tasks source picker and sidebar shortcuts.',
+    Icon: ({ className }) => <LinearIcon className={className} />
+  }
+]
+
+export function TasksPane({ settings, updateSettings }: TasksPaneProps): React.JSX.Element {
+  const visibleProviders = normalizeVisibleTaskProviders(settings.visibleTaskProviders)
+
+  const toggleProvider = (provider: TaskProvider): void => {
+    const isVisible = visibleProviders.includes(provider)
+    if (isVisible && visibleProviders.length === 1) {
+      return
+    }
+
+    const nextProviders = isVisible
+      ? visibleProviders.filter((entry) => entry !== provider)
+      : TASK_PROVIDERS.filter((entry) => entry === provider || visibleProviders.includes(entry))
+
+    updateSettings({
+      visibleTaskProviders: nextProviders,
+      defaultTaskSource: resolveVisibleTaskProvider(settings.defaultTaskSource, nextProviders)
+    })
+  }
+
+  return (
+    <div className="space-y-6">
+      <section className="space-y-4">
+        <div className="space-y-1">
+          <h3 className="text-sm font-semibold">Task Sources</h3>
+          <p className="text-xs text-muted-foreground">
+            Choose which task providers appear in the Tasks page source picker and sidebar
+            shortcuts. At least one provider must stay visible.
+          </p>
+        </div>
+
+        <SearchableSetting
+          title="Task Providers"
+          description="Choose which task providers appear in the Tasks page and sidebar shortcuts."
+          keywords={[
+            'tasks',
+            'provider',
+            'source',
+            'github',
+            'gitlab',
+            'linear',
+            'display',
+            'hide'
+          ]}
+          className="grid gap-2"
+        >
+          {TASK_PROVIDER_OPTIONS.map((option) => {
+            const enabled = visibleProviders.includes(option.id)
+            const isLastEnabled = enabled && visibleProviders.length === 1
+            const Icon = option.Icon
+
+            return (
+              <button
+                key={option.id}
+                type="button"
+                role="checkbox"
+                aria-checked={enabled}
+                aria-disabled={isLastEnabled}
+                onClick={() => toggleProvider(option.id)}
+                className={cn(
+                  'flex w-full items-center gap-3 rounded-md border border-border/60 px-3 py-2.5 text-left transition-colors',
+                  enabled
+                    ? 'bg-accent/70 text-accent-foreground'
+                    : 'bg-transparent hover:bg-muted/50',
+                  isLastEnabled && 'cursor-not-allowed'
+                )}
+              >
+                <span
+                  className={cn(
+                    'flex size-7 shrink-0 items-center justify-center rounded-md border',
+                    enabled
+                      ? 'border-foreground/20 bg-background/70'
+                      : 'border-border/60 bg-muted/40 text-muted-foreground'
+                  )}
+                >
+                  <Icon className="size-3.5" />
+                </span>
+                <span className="min-w-0 flex-1 space-y-0.5">
+                  <Label className="cursor-inherit">{option.label}</Label>
+                  <span className="block text-xs text-muted-foreground">{option.description}</span>
+                </span>
+                <span
+                  aria-hidden
+                  className={cn(
+                    'flex size-4 shrink-0 items-center justify-center rounded border text-[10px]',
+                    enabled
+                      ? 'border-foreground/50 bg-foreground text-background'
+                      : 'border-border bg-background'
+                  )}
+                >
+                  {enabled ? <Check className="size-3" /> : null}
+                </span>
+              </button>
+            )
+          })}
+        </SearchableSetting>
+      </section>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/settings/tasks-search.ts b/src/renderer/src/components/settings/tasks-search.ts
new file mode 100644
index 00000000000..a309c42412d
--- /dev/null
+++ b/src/renderer/src/components/settings/tasks-search.ts
@@ -0,0 +1,9 @@
+import type { SettingsSearchEntry } from './settings-search'
+
+export const TASKS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
+  {
+    title: 'Task Providers',
+    description: 'Choose which task providers appear in the Tasks page and sidebar shortcuts.',
+    keywords: ['tasks', 'provider', 'source', 'github', 'gitlab', 'linear', 'display', 'hide']
+  }
+]
diff --git a/src/renderer/src/components/sidebar/SidebarNav.tsx b/src/renderer/src/components/sidebar/SidebarNav.tsx
index febf70e7aea..2bc8c6f7200 100644
--- a/src/renderer/src/components/sidebar/SidebarNav.tsx
+++ b/src/renderer/src/components/sidebar/SidebarNav.tsx
@@ -7,6 +7,10 @@ import { isGitRepoKind } from '../../../../shared/repo-kind'
 import { getTaskPresetQuery, PER_REPO_FETCH_LIMIT } from '@/lib/new-workspace'
 import { LinearIcon } from '@/components/icons/LinearIcon'
 import { migrationUnsupportedToAgentStatusEntry } from '@/lib/migration-unsupported-agent-entry'
+import {
+  normalizeVisibleTaskProviders,
+  resolveVisibleTaskProvider
+} from '../../../../shared/task-providers'
 
 const isMac = typeof navigator !== 'undefined' && navigator.userAgent.includes('Mac')
 
@@ -22,6 +26,16 @@ const SidebarNav = React.memo(function SidebarNav() {
   // Why: the setting is opt-out (default true). `!== false` keeps the button
   // visible for users whose persisted settings predate this field.
   const showTasksButton = useAppStore((s) => s.settings?.showTasksButton !== false)
+  const rawVisibleTaskProviders = useAppStore((s) => s.settings?.visibleTaskProviders)
+  const defaultTaskSource = useAppStore((s) => s.settings?.defaultTaskSource ?? 'github')
+  const visibleTaskProviders = React.useMemo(
+    () => normalizeVisibleTaskProviders(rawVisibleTaskProviders),
+    [rawVisibleTaskProviders]
+  )
+  const resolvedDefaultTaskSource = React.useMemo(
+    () => resolveVisibleTaskProvider(defaultTaskSource, visibleTaskProviders),
+    [defaultTaskSource, visibleTaskProviders]
+  )
 
   // Why: warm the GitHub work-item cache on hover/focus so by the time the
   // user's click finishes the round-trip has either completed or is already
@@ -30,7 +44,7 @@ const SidebarNav = React.memo(function SidebarNav() {
   const activeRepoId = useAppStore((s) => s.activeRepoId)
   const defaultTaskViewPreset = useAppStore((s) => s.settings?.defaultTaskViewPreset ?? 'all')
   const handlePrefetch = React.useCallback(() => {
-    if (!canBrowseTasks) {
+    if (!canBrowseTasks || resolvedDefaultTaskSource !== 'github') {
       return
     }
     const activeRepo = activeRepoId ? (repoMap.get(activeRepoId) ?? null) : null
@@ -48,7 +62,15 @@ const SidebarNav = React.memo(function SidebarNav() {
         getTaskPresetQuery(defaultTaskViewPreset)
       )
     }
-  }, [activeRepoId, canBrowseTasks, defaultTaskViewPreset, prefetchWorkItems, repoMap, repos])
+  }, [
+    activeRepoId,
+    canBrowseTasks,
+    defaultTaskViewPreset,
+    prefetchWorkItems,
+    repoMap,
+    repos,
+    resolvedDefaultTaskSource
+  ])
 
   const tasksActive = activeView === 'tasks'
   const automationsActive = activeView === 'automations'
@@ -119,49 +141,57 @@ const SidebarNav = React.memo(function SidebarNav() {
           />
           <span className="flex-1">Tasks</span>
           <span className="flex items-center gap-1">
-            <span
-              role="button"
-              tabIndex={-1}
-              onClick={(e) => {
-                e.stopPropagation()
-                if (!canBrowseTasks) {
-                  return
-                }
-                openTaskPage({ taskSource: 'github' })
-              }}
-              className="rounded p-0.5 text-muted-foreground/70 transition-colors hover:text-foreground"
-            >
-              <Github className="size-3.5" aria-hidden />
-            </span>
-            <span
-              role="button"
-              tabIndex={-1}
-              onClick={(e) => {
-                e.stopPropagation()
-                if (!canBrowseTasks) {
-                  return
-                }
-                openTaskPage({ taskSource: 'gitlab' })
-              }}
-              className="rounded p-0.5 text-muted-foreground/70 transition-colors hover:text-foreground"
-              aria-label="Open GitLab tasks"
-            >
-              <Gitlab className="size-3.5" aria-hidden />
-            </span>
-            <span
-              role="button"
-              tabIndex={-1}
-              onClick={(e) => {
-                e.stopPropagation()
-                if (!canBrowseTasks) {
-                  return
-                }
-                openTaskPage({ taskSource: 'linear' })
-              }}
-              className="rounded p-0.5 text-muted-foreground/70 transition-colors hover:text-foreground"
-            >
-              <LinearIcon className="size-3.5" />
-            </span>
+            {visibleTaskProviders.includes('github') ? (
+              <span
+                role="button"
+                tabIndex={-1}
+                onClick={(e) => {
+                  e.stopPropagation()
+                  if (!canBrowseTasks) {
+                    return
+                  }
+                  openTaskPage({ taskSource: 'github' })
+                }}
+                className="rounded p-0.5 text-muted-foreground/70 transition-colors hover:text-foreground"
+                aria-label="Open GitHub tasks"
+              >
+                <Github className="size-3.5" aria-hidden />
+              </span>
+            ) : null}
+            {visibleTaskProviders.includes('gitlab') ? (
+              <span
+                role="button"
+                tabIndex={-1}
+                onClick={(e) => {
+                  e.stopPropagation()
+                  if (!canBrowseTasks) {
+                    return
+                  }
+                  openTaskPage({ taskSource: 'gitlab' })
+                }}
+                className="rounded p-0.5 text-muted-foreground/70 transition-colors hover:text-foreground"
+                aria-label="Open GitLab tasks"
+              >
+                <Gitlab className="size-3.5" aria-hidden />
+              </span>
+            ) : null}
+            {visibleTaskProviders.includes('linear') ? (
+              <span
+                role="button"
+                tabIndex={-1}
+                onClick={(e) => {
+                  e.stopPropagation()
+                  if (!canBrowseTasks) {
+                    return
+                  }
+                  openTaskPage({ taskSource: 'linear' })
+                }}
+                className="rounded p-0.5 text-muted-foreground/70 transition-colors hover:text-foreground"
+                aria-label="Open Linear tasks"
+              >
+                <LinearIcon className="size-3.5" />
+              </span>
+            ) : null}
           </span>
         </button>
       ) : null}
diff --git a/src/renderer/src/store/slices/settings.ts b/src/renderer/src/store/slices/settings.ts
index eb11cbf64f6..4a30c09f905 100644
--- a/src/renderer/src/store/slices/settings.ts
+++ b/src/renderer/src/store/slices/settings.ts
@@ -8,6 +8,7 @@ import {
   getRemoteRuntimeTerminalHandle
 } from '@/runtime/runtime-terminal-stream'
 import { normalizeTerminalQuickCommands } from '../../../../shared/terminal-quick-commands'
+import { normalizeVisibleTaskProviders } from '../../../../shared/task-providers'
 
 export type SettingsSlice = {
   settings: GlobalSettings | null
@@ -229,6 +230,11 @@ export const createSettingsSlice: StateCreator<AppState, [], [], SettingsSlice>
           updates.terminalQuickCommands
         )
       }
+      if ('visibleTaskProviders' in updates) {
+        sanitizedUpdates.visibleTaskProviders = normalizeVisibleTaskProviders(
+          updates.visibleTaskProviders
+        )
+      }
       await window.api.settings.set(sanitizedUpdates)
       set((s) => {
         if (!s.settings) {
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index a6688a47dc5..a24fe6aa507 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -8,6 +8,7 @@ import type {
   PersistedTrustedOrcaHooks,
   PersistedUIState,
   StatusBarItem,
+  TaskProvider,
   TaskResumeState,
   TaskViewPresetId,
   TuiAgent,
@@ -21,6 +22,10 @@ import {
   type WorkspaceCleanupDismissal
 } from '../../../../shared/workspace-cleanup'
 import { PER_REPO_FETCH_LIMIT } from '../../../../shared/work-items'
+import {
+  normalizeVisibleTaskProviders,
+  resolveVisibleTaskProvider
+} from '../../../../shared/task-providers'
 import {
   DEFAULT_STATUS_BAR_ITEMS,
   DEFAULT_WORKTREE_CARD_PROPERTIES
@@ -249,7 +254,7 @@ export type UISlice = {
   taskPageData: {
     preselectedRepoId?: string
     prefilledName?: string
-    taskSource?: 'github' | 'linear' | 'gitlab'
+    taskSource?: TaskProvider
   }
   taskResumeState: TaskResumeState | undefined
   setTaskResumeState: (updates: Partial<TaskResumeState>) => void
@@ -295,6 +300,7 @@ export type UISlice = {
       | 'general'
       | 'browser'
       | 'appearance'
+      | 'tasks'
       | 'terminal'
       | 'computer-use'
       | 'developer-permissions'
@@ -504,7 +510,11 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
     // be deduped. This removes ~300–800ms of perceived latency on initial
     // page load.
     const state = get()
-    const resolvedSource = data.taskSource ?? state.settings?.defaultTaskSource ?? 'github'
+    const visibleTaskProviders = normalizeVisibleTaskProviders(state.settings?.visibleTaskProviders)
+    const resolvedSource = resolveVisibleTaskProvider(
+      data.taskSource ?? state.settings?.defaultTaskSource,
+      visibleTaskProviders
+    )
     const resolvedMode = state.taskResumeState?.githubMode ?? 'items'
     if (resolvedSource === 'github' && resolvedMode === 'items') {
       const eligibleRepos = state.repos.filter((repo) => isGitRepoKind(repo) && repo.path)
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 777b7142f86..fbc518ccf16 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -14,6 +14,7 @@ import { DEFAULT_TERMINAL_FONT_WEIGHT } from './terminal-fonts'
 import { getDefaultTerminalQuickCommands } from './terminal-quick-commands'
 import type { VoiceSettings } from './speech-types'
 import { cloneDefaultWorkspaceStatuses } from './workspace-statuses'
+import { TASK_PROVIDERS } from './task-providers'
 
 export const SCHEMA_VERSION = 1
 export const DEFAULT_APP_FONT_FAMILY = 'Geist'
@@ -230,6 +231,7 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     skipDeleteAutomationConfirm: false,
     defaultTaskViewPreset: 'all',
     defaultTaskSource: 'github',
+    visibleTaskProviders: [...TASK_PROVIDERS],
     defaultRepoSelection: null,
     defaultLinearTeamSelection: null,
     opencodeSessionCookie: '',
diff --git a/src/shared/task-providers.test.ts b/src/shared/task-providers.test.ts
new file mode 100644
index 00000000000..6ef00ac85c2
--- /dev/null
+++ b/src/shared/task-providers.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { normalizeVisibleTaskProviders, resolveVisibleTaskProvider } from './task-providers'
+
+describe('task providers', () => {
+  it('normalizes provider lists while preserving supported order', () => {
+    expect(normalizeVisibleTaskProviders(['gitlab', 'unknown', 'gitlab', 'linear'])).toEqual([
+      'gitlab',
+      'linear'
+    ])
+  })
+
+  it('falls back to all providers when none are visible', () => {
+    expect(normalizeVisibleTaskProviders([])).toEqual(['github', 'gitlab', 'linear'])
+  })
+
+  it('resolves hidden preferred providers to the first visible provider', () => {
+    expect(resolveVisibleTaskProvider('github', ['linear'])).toBe('linear')
+  })
+})
diff --git a/src/shared/task-providers.ts b/src/shared/task-providers.ts
new file mode 100644
index 00000000000..a94484ad60d
--- /dev/null
+++ b/src/shared/task-providers.ts
@@ -0,0 +1,35 @@
+export type TaskProvider = 'github' | 'gitlab' | 'linear'
+
+export const TASK_PROVIDERS: readonly TaskProvider[] = ['github', 'gitlab', 'linear']
+
+const TASK_PROVIDER_SET = new Set<TaskProvider>(TASK_PROVIDERS)
+
+export function normalizeVisibleTaskProviders(value: unknown): TaskProvider[] {
+  if (!Array.isArray(value)) {
+    return [...TASK_PROVIDERS]
+  }
+
+  const normalized: TaskProvider[] = []
+  for (const provider of value) {
+    if (!TASK_PROVIDER_SET.has(provider as TaskProvider)) {
+      continue
+    }
+    if (!normalized.includes(provider as TaskProvider)) {
+      normalized.push(provider as TaskProvider)
+    }
+  }
+
+  // Why: at least one provider must remain visible so the Tasks surface always
+  // has a valid source to select after settings hydration or manual edits.
+  return normalized.length > 0 ? normalized : [...TASK_PROVIDERS]
+}
+
+export function resolveVisibleTaskProvider(
+  preferred: TaskProvider | null | undefined,
+  visibleProviders: readonly TaskProvider[]
+): TaskProvider {
+  if (preferred && visibleProviders.includes(preferred)) {
+    return preferred
+  }
+  return visibleProviders[0] ?? 'github'
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 9e8f171acca..688b137daf5 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -7,10 +7,12 @@ import type { MigrationUnsupportedPtyEntry } from './agent-status-types'
 import type { VoiceSettings } from './speech-types'
 import type { WorkspaceCleanupUIState } from './workspace-cleanup'
 import type { GitLabProjectSettings } from './gitlab-types'
+import type { TaskProvider } from './task-providers'
 
 // Re-exported for backward compat with renderer call sites that import
 // `WorkspaceCreateTelemetrySource` from '../../../shared/types'.
 export type { WorkspaceSource as WorkspaceCreateTelemetrySource } from './telemetry-events'
+export type { TaskProvider } from './task-providers'
 
 // ─── Shell PATH hydration ────────────────────────────────────────────
 // Why: shared so the main-side `HydrationResult` discriminator and the
@@ -1350,7 +1352,11 @@ export type GlobalSettings = {
   defaultTaskViewPreset: TaskViewPresetId
   /** Why: persists the user's last-used task source so the Tasks page
    *  reopens to the same provider instead of always defaulting to GitHub. */
-  defaultTaskSource: 'github' | 'linear' | 'gitlab'
+  defaultTaskSource: TaskProvider
+  /** Why: users may only work from one hosted task system. Persisting this
+   *  list hides unused providers from Tasks chrome and sidebar shortcuts while
+   *  leaving the chosen default source stable when it is still visible. */
+  visibleTaskProviders: TaskProvider[]
   /** Why: persists the user's repo selection in the cross-repo tasks view.
    *  `null` means sticky-all — every eligible repo is selected, including
    *  repos added in future sessions, so the "All repos" label stays

From a1a78d12d59f05a78c5b325bd3a54ca457186991 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 14:28:45 -0700
Subject: [PATCH 81/82] fix: address review findings (#1990)

---
 .../activity/ActivityPrototypePage.test.ts    |  33 +++++
 .../activity/ActivityPrototypePage.tsx        | 121 ++++++++++++------
 2 files changed, 117 insertions(+), 37 deletions(-)

diff --git a/src/renderer/src/components/activity/ActivityPrototypePage.test.ts b/src/renderer/src/components/activity/ActivityPrototypePage.test.ts
index d56c546be6c..dfbe612c34a 100644
--- a/src/renderer/src/components/activity/ActivityPrototypePage.test.ts
+++ b/src/renderer/src/components/activity/ActivityPrototypePage.test.ts
@@ -5,6 +5,7 @@ import {
   AGENT_STATUS_STALE_AFTER_MS,
   type AgentStatusEntry
 } from '../../../../shared/agent-status-types'
+import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../../shared/constants'
 import type { Repo, TerminalTab, Worktree } from '../../../../shared/types'
 import { formatAgentTypeLabel } from '@/lib/agent-status'
 import type { RetainedAgentEntry } from '@/store/slices/agent-status'
@@ -240,6 +241,38 @@ describe('buildActivityEvents', () => {
     })
   })
 
+  it('creates a thread for a repo-less floating terminal agent', () => {
+    const tab = makeTabWithIds('tab-1', FLOATING_TERMINAL_WORKTREE_ID, 'Claude')
+    const result = buildActivityEvents({
+      agentStatusByPaneKey: {
+        [PANE_KEY]: makeWorkingEntryWithoutHistory()
+      },
+      retainedAgentsByPaneKey: {},
+      tabsByWorktree: {
+        [FLOATING_TERMINAL_WORKTREE_ID]: [tab]
+      },
+      worktreeMap: new Map(),
+      repoMap: new Map(),
+      acknowledgedAgentsByPaneKey: {},
+      now: 3_000
+    })
+
+    const threads = makeThreads(result)
+
+    expect(result.events).toHaveLength(0)
+    expect(threads).toHaveLength(1)
+    expect(threads[0]).toMatchObject({
+      paneKey: PANE_KEY,
+      paneTitle: 'New run',
+      currentAgentState: 'working',
+      repo: null
+    })
+    expect(threads[0].worktree).toMatchObject({
+      id: FLOATING_TERMINAL_WORKTREE_ID,
+      displayName: 'Floating terminal'
+    })
+  })
+
   it('matches a custom-titled live thread by its current prompt', () => {
     const tab = { ...makeTab(), customTitle: 'Pinned agent title' }
     const entry = {
diff --git a/src/renderer/src/components/activity/ActivityPrototypePage.tsx b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
index 6188cadfbca..80c318e8d46 100644
--- a/src/renderer/src/components/activity/ActivityPrototypePage.tsx
+++ b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
@@ -53,6 +53,7 @@ import {
   type ActivityTerminalPortalTarget
 } from './activity-terminal-portal'
 import type { Repo, TerminalTab, Worktree } from '../../../../shared/types'
+import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../../shared/constants'
 import {
   AGENT_STATUS_STALE_AFTER_MS,
   type AgentStateHistoryEntry,
@@ -145,6 +146,7 @@ const ACTIVITY_STATUS_GROUP_ORDER: ActivityStatusGroupId[] = [
   'done',
   'interrupted'
 ]
+const STANDALONE_ACTIVITY_WORKTREE_REPO_ID = '__activity_standalone__'
 
 const absoluteDateFormatter = new Intl.DateTimeFormat(undefined, {
   year: 'numeric',
@@ -475,6 +477,30 @@ function freshActivityLiveAgentState(
   return isExplicitAgentStatusFresh(entry, now, AGENT_STATUS_STALE_AFTER_MS) ? entry.state : null
 }
 
+function standaloneActivityWorktree(worktreeId: string): Worktree {
+  const displayName =
+    worktreeId === FLOATING_TERMINAL_WORKTREE_ID ? 'Floating terminal' : 'Standalone terminal'
+  return {
+    id: worktreeId,
+    repoId: STANDALONE_ACTIVITY_WORKTREE_REPO_ID,
+    path: '',
+    head: '',
+    branch: displayName,
+    isBare: false,
+    isMainWorktree: false,
+    displayName,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0
+  }
+}
+
 // Why: per-pane cap guarantees each agent appears in the left list even when one pane has a long history.
 const EVENTS_PER_PANE_CAP = 5
 
@@ -585,8 +611,8 @@ export function buildActivityEvents(args: {
   const tabContext = new Map<string, { worktree: Worktree; tab: TerminalTab }>()
   const liveAgentByPaneKey: Record<string, ActivityLiveAgentSnapshot> = {}
 
-  for (const worktree of args.worktreeMap.values()) {
-    const tabs = args.tabsByWorktree[worktree.id] ?? []
+  for (const [worktreeId, tabs] of Object.entries(args.tabsByWorktree)) {
+    const worktree = args.worktreeMap.get(worktreeId) ?? standaloneActivityWorktree(worktreeId)
     for (const tab of tabs) {
       tabContext.set(tab.id, { worktree, tab })
     }
@@ -671,7 +697,11 @@ export function buildActivityEvents(args: {
     if (!parsePaneKey(paneKey)) {
       continue
     }
-    const worktree = args.worktreeMap.get(retained.worktreeId)
+    const worktree =
+      args.worktreeMap.get(retained.worktreeId) ??
+      (args.tabsByWorktree[retained.worktreeId]
+        ? standaloneActivityWorktree(retained.worktreeId)
+        : null)
     if (!worktree) {
       continue
     }
@@ -1000,6 +1030,7 @@ function ThreadRow({
   onSelect,
   onJump,
   onMarkUnread,
+  canJump,
   compactMode
 }: {
   thread: AgentPaneThread
@@ -1007,6 +1038,7 @@ function ThreadRow({
   onSelect: () => void
   onJump: () => void
   onMarkUnread: () => void
+  canJump: boolean
   compactMode: boolean
 }): React.JSX.Element {
   const renderedResponsePreview = activityThreadResponseRenderPreview({
@@ -1140,32 +1172,34 @@ function ThreadRow({
             the worktree name. Reserved layout via `invisible` +
             `pointer-events-none` keeps the worktree-name's flex-1 width
             stable across hover. */}
-        <span
-          className={cn(
-            'ml-auto inline-flex shrink-0 items-center transition-opacity',
-            'pointer-events-none invisible opacity-0',
-            'group-hover:pointer-events-auto group-hover:visible group-hover:opacity-100'
-          )}
-        >
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <Button
-                type="button"
-                variant="outline"
-                size="icon-xs"
-                aria-label="Jump to workspace"
-                onClick={(event) => {
-                  event.stopPropagation()
-                  onJump()
-                }}
-                onMouseDown={(event) => event.stopPropagation()}
-              >
-                <ExternalLink className="size-3" />
-              </Button>
-            </TooltipTrigger>
-            <TooltipContent side="left">Jump to workspace</TooltipContent>
-          </Tooltip>
-        </span>
+        {canJump ? (
+          <span
+            className={cn(
+              'ml-auto inline-flex shrink-0 items-center transition-opacity',
+              'pointer-events-none invisible opacity-0',
+              'group-hover:pointer-events-auto group-hover:visible group-hover:opacity-100'
+            )}
+          >
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="icon-xs"
+                  aria-label="Jump to workspace"
+                  onClick={(event) => {
+                    event.stopPropagation()
+                    onJump()
+                  }}
+                  onMouseDown={(event) => event.stopPropagation()}
+                >
+                  <ExternalLink className="size-3" />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent side="left">Jump to workspace</TooltipContent>
+            </Tooltip>
+          </span>
+        ) : null}
       </div>
     </div>
   )
@@ -1271,8 +1305,10 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     ? (allThreads.find((thread) => thread.paneKey === selectedPaneKey) ?? null)
     : null
   const selectedTabId = selectedThread?.tab.id ?? null
+  // Why: repo-less terminal buckets can still produce Activity rows, but the
+  // workspace Terminal tree only portals real worktrees.
   const selectedHasLiveTab =
-    selectedThread && selectedTabId
+    selectedThread && selectedTabId && storeData.worktreeMap.has(selectedThread.worktree.id)
       ? (storeData.tabsByWorktree[selectedThread.worktree.id] ?? []).some(
           (tab) => tab.id === selectedTabId
         )
@@ -1282,7 +1318,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     : null
   const displayedTabId = displayedThread?.tab.id ?? null
   const displayedHasLiveTab =
-    displayedThread && displayedTabId
+    displayedThread && displayedTabId && storeData.worktreeMap.has(displayedThread.worktree.id)
       ? (storeData.tabsByWorktree[displayedThread.worktree.id] ?? []).some(
           (tab) => tab.id === displayedTabId
         )
@@ -1443,19 +1479,23 @@ export default function ActivityPrototypePage(): React.JSX.Element {
 
   const activateThreadTerminal = (thread: AgentPaneThread): void => {
     const state = useAppStore.getState()
+    const worktree = getWorktreeMapFromState(state).get(thread.worktree.id)
+    if (!worktree) {
+      return
+    }
     // Why: retained-agent threads can outlive their tab. With no live tab, the
     // right pane shows the empty-state placeholder; reorienting the workspace
     // and dispatching focus to a dead tab id would just confuse the user.
-    const liveTabs = state.tabsByWorktree[thread.worktree.id] ?? []
+    const liveTabs = state.tabsByWorktree[worktree.id] ?? []
     const hasLiveTab = liveTabs.some((t) => t.id === thread.tab.id)
     if (!hasLiveTab) {
       return
     }
-    if (state.activeRepoId !== thread.worktree.repoId) {
-      state.setActiveRepo(thread.worktree.repoId)
+    if (state.activeRepoId !== worktree.repoId) {
+      state.setActiveRepo(worktree.repoId)
     }
-    if (state.activeWorktreeId !== thread.worktree.id) {
-      state.setActiveWorktree(thread.worktree.id)
+    if (state.activeWorktreeId !== worktree.id) {
+      state.setActiveWorktree(worktree.id)
     }
     state.setActiveTabType('terminal')
     const parsed = parsePaneKey(thread.paneKey)
@@ -1497,6 +1537,10 @@ export default function ActivityPrototypePage(): React.JSX.Element {
   ])
 
   const jumpToWorkspace = (thread: AgentPaneThread): void => {
+    const state = useAppStore.getState()
+    if (!getWorktreeMapFromState(state).has(thread.worktree.id)) {
+      return
+    }
     markThreadRead(thread)
     activateAndRevealWorktree(thread.worktree.id)
   }
@@ -1626,6 +1670,7 @@ export default function ActivityPrototypePage(): React.JSX.Element {
                     onSelect={() => selectThread(thread)}
                     onJump={() => jumpToWorkspace(thread)}
                     onMarkUnread={() => markThreadUnread(thread)}
+                    canJump={storeData.worktreeMap.has(thread.worktree.id)}
                     compactMode={compactMode}
                   />
                 ))}
@@ -1695,7 +1740,9 @@ export default function ActivityPrototypePage(): React.JSX.Element {
                   return (
                     <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-2 p-4 text-sm text-muted-foreground">
                       <TerminalSquare className="size-7" />
-                      Agent terminal closed. Open a new terminal in this workspace to continue.
+                      {storeData.worktreeMap.has(selectedThread.worktree.id)
+                        ? 'Agent terminal closed. Open a new terminal in this workspace to continue.'
+                        : 'Standalone terminal unavailable in Activity.'}
                     </div>
                   )
                 }

From c393e4e779fbbe315ea3e3a9ae5b895191b52f02 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 15 May 2026 14:29:37 -0700
Subject: [PATCH 82/82] Fix terminal code pointer reveals (#1991)

---
 .../terminal-link-handlers.test.ts            | 95 ++++++++++++++++++-
 .../terminal-pane/terminal-link-handlers.ts   | 20 +++-
 2 files changed, 113 insertions(+), 2 deletions(-)

diff --git a/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts b/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts
index 5aa8b5766e2..98a111a5009 100644
--- a/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-link-handlers.test.ts
@@ -28,6 +28,7 @@ const runtimeEnvironmentCallMock = vi.fn()
 const runtimeEnvironmentTransportCallMock = vi.fn()
 const setActiveWorktreeMock = vi.fn()
 const createBrowserTabMock = vi.fn()
+const setPendingEditorRevealMock = vi.fn()
 
 const deps = { worktreeId: 'wt-1', worktreePath: '/tmp' }
 const storeState = {
@@ -36,7 +37,8 @@ const storeState = {
     | undefined,
   setActiveWorktree: setActiveWorktreeMock,
   createBrowserTab: createBrowserTabMock,
-  openFile: openFileMock
+  openFile: openFileMock,
+  setPendingEditorReveal: setPendingEditorRevealMock
 }
 
 vi.mock('@/store', () => ({
@@ -65,6 +67,23 @@ function setPlatform(userAgent: string): void {
   vi.stubGlobal('navigator', { userAgent })
 }
 
+function createDeferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((res) => {
+    resolve = res
+  })
+  return { promise, resolve }
+}
+
+async function flushAsyncWork(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+async function flushDoubleRaf(): Promise<void> {
+  await flushAsyncWork()
+  await flushAsyncWork()
+}
+
 beforeEach(() => {
   clearRuntimeCompatibilityCacheForTests()
   vi.clearAllMocks()
@@ -76,6 +95,7 @@ beforeEach(() => {
   storeState.settings = undefined
   registerHttpLinkStoreAccessor(() => storeState)
   vi.stubGlobal('window', {
+    dispatchEvent: vi.fn(),
     api: {
       shell: {
         openUrl: openUrlMock,
@@ -90,6 +110,9 @@ beforeEach(() => {
       runtimeEnvironments: { call: runtimeEnvironmentTransportCallMock }
     }
   })
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback): number => {
+    return setTimeout(() => callback(0), 0) as unknown as number
+  })
 })
 
 afterEach(() => {
@@ -191,6 +214,7 @@ describe('handleOscLink', () => {
 
     // Why: .html should not open Monaco — it should render in the browser tab.
     expect(openFileMock).not.toHaveBeenCalled()
+    expect(setPendingEditorRevealMock).not.toHaveBeenCalled()
     expect(createBrowserTabMock).toHaveBeenCalledWith(
       'wt-1',
       'file:///tmp/report.html',
@@ -205,6 +229,7 @@ describe('handleOscLink', () => {
     await new Promise((resolve) => setTimeout(resolve, 0))
 
     expect(openFileMock).not.toHaveBeenCalled()
+    expect(setPendingEditorRevealMock).not.toHaveBeenCalled()
     expect(createBrowserTabMock).toHaveBeenCalledWith(
       'wt-1',
       'file:///tmp/legacy.HTM',
@@ -212,6 +237,41 @@ describe('handleOscLink', () => {
     )
   })
 
+  it('schedules Monaco reveal with default column 1 for :line links', async () => {
+    setPlatform('Macintosh')
+
+    openDetectedFilePath('/tmp/src/main.ts', 42, null, deps)
+    await flushAsyncWork()
+    await flushDoubleRaf()
+
+    expect(openFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({ filePath: '/tmp/src/main.ts' })
+    )
+    expect(setPendingEditorRevealMock).toHaveBeenNthCalledWith(1, null)
+    expect(setPendingEditorRevealMock).toHaveBeenNthCalledWith(2, {
+      filePath: '/tmp/src/main.ts',
+      line: 42,
+      column: 1,
+      matchLength: 0
+    })
+  })
+
+  it('preserves explicit column for :line:column links', async () => {
+    setPlatform('Macintosh')
+
+    openDetectedFilePath('/tmp/src/main.ts', 42, 7, deps)
+    await flushAsyncWork()
+    await flushDoubleRaf()
+
+    expect(setPendingEditorRevealMock).toHaveBeenNthCalledWith(1, null)
+    expect(setPendingEditorRevealMock).toHaveBeenNthCalledWith(2, {
+      filePath: '/tmp/src/main.ts',
+      line: 42,
+      column: 7,
+      matchLength: 0
+    })
+  })
+
   it('advertises the browser-open behavior in the html hover hint', () => {
     setPlatform('Macintosh')
     expect(getTerminalHtmlFileOpenHint()).toBe('⌘+click to open in browser')
@@ -386,6 +446,39 @@ describe('handleOscLink', () => {
     expect(openFilePathMock).not.toHaveBeenCalled()
     expect(openFileMock).not.toHaveBeenCalled()
   })
+
+  it('ignores stale async completion so latest click wins for open and reveal', async () => {
+    setPlatform('Macintosh')
+    const firstStat = createDeferred<{ isDirectory: boolean }>()
+    const secondStat = createDeferred<{ isDirectory: boolean }>()
+    statMock
+      .mockImplementationOnce(() => firstStat.promise)
+      .mockImplementationOnce(() => secondStat.promise)
+
+    openDetectedFilePath('/tmp/src/first.ts', 10, 2, deps)
+    openDetectedFilePath('/tmp/src/second.ts', 20, 3, deps)
+
+    secondStat.resolve({ isDirectory: false })
+    await flushAsyncWork()
+    await flushDoubleRaf()
+
+    firstStat.resolve({ isDirectory: false })
+    await flushAsyncWork()
+    await flushDoubleRaf()
+
+    expect(openFileMock).toHaveBeenCalledTimes(1)
+    expect(openFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({ filePath: '/tmp/src/second.ts' })
+    )
+    expect(setPendingEditorRevealMock).toHaveBeenNthCalledWith(1, null)
+    expect(setPendingEditorRevealMock).toHaveBeenNthCalledWith(2, {
+      filePath: '/tmp/src/second.ts',
+      line: 20,
+      column: 3,
+      matchLength: 0
+    })
+    expect(setPendingEditorRevealMock).toHaveBeenCalledTimes(2)
+  })
 })
 
 describe('createFilePathLinkProvider range bounds', () => {
diff --git a/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts b/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
index 582fac1e131..0e40e98f8e3 100644
--- a/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
@@ -87,6 +87,8 @@ function getTerminalFileContext(
   }
 }
 
+let latestOpenDetectedFilePathRequestId = 0
+
 export function openDetectedFilePath(
   filePath: string,
   line: number | null,
@@ -94,6 +96,7 @@ export function openDetectedFilePath(
   deps: Pick<LinkHandlerDeps, 'worktreeId' | 'worktreePath' | 'runtimeEnvironmentId'>
 ): void {
   const { runtimeEnvironmentId, worktreeId, worktreePath } = deps
+  const requestId = ++latestOpenDetectedFilePathRequestId
 
   void (async () => {
     let statResult
@@ -109,6 +112,10 @@ export function openDetectedFilePath(
       return
     }
 
+    if (requestId !== latestOpenDetectedFilePathRequestId) {
+      return
+    }
+
     if (statResult.isDirectory) {
       const fileContext = getTerminalFileContext(worktreeId, worktreePath, runtimeEnvironmentId)
       if (fileContext.connectionId || isRemoteRuntimeFileOperation(fileContext, filePath)) {
@@ -158,11 +165,22 @@ export function openDetectedFilePath(
     })
 
     if (line !== null) {
+      const targetColumn = column ?? 1
+      store.setPendingEditorReveal(null)
       requestAnimationFrame(() => {
         requestAnimationFrame(() => {
+          if (requestId !== latestOpenDetectedFilePathRequestId) {
+            return
+          }
+          store.setPendingEditorReveal({
+            filePath,
+            line,
+            column: targetColumn,
+            matchLength: 0
+          })
           window.dispatchEvent(
             new CustomEvent('orca:editor-reveal-location', {
-              detail: { filePath, line, column }
+              detail: { filePath, line, column: targetColumn }
             })
           )
         })