diff --git a/.github/workflows/release-cut.yml b/.github/workflows/release-cut.yml
index 2b9d0bde0f9..87c383fea69 100644
--- a/.github/workflows/release-cut.yml
+++ b/.github/workflows/release-cut.yml
@@ -518,8 +518,48 @@ jobs:
           APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
 
+      # 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
+      # that identity from the release tag here — `stable` for plain semver
+      # (`vX.Y.Z`), `rc` for prerelease (`vX.Y.Z-rc.N`). The strict regex is
+      # a safety net: this workflow only fires on cut-tags that already match
+      # one of those shapes, but if a future change ever loosens that, we
+      # refuse to ship rather than let an unclassified build go out with
+      # `BUILD_IDENTITY = null`.
+      - name: Classify release tag for telemetry build identity
+        id: tag-classify
+        shell: bash
+        env:
+          TAG: ${{ needs.cut.outputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$ ]]; then
+            identity=rc
+          elif [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            identity=stable
+          else
+            echo "::error::Tag $TAG does not match stable or rc pattern; refusing to build official artifact"
+            exit 1
+          fi
+          echo "identity=$identity" >>"$GITHUB_OUTPUT"
+          echo "Classified $TAG as $identity"
+
+      # Why ORCA_POSTHOG_WRITE_KEY here: this is the only build that
+      # produces a published binary, so this is the only place the secret
+      # needs to be in scope. The key is a PostHog *project* API key, not
+      # a server secret — it ships in every official binary's app.asar
+      # and is therefore extractable from any release. We still keep it
+      # in GitHub Actions secrets so the literal stays out of the repo
+      # (and out of fork CI runs / log scrapers / casual greps).
+      # Why ORCA_BUILD_IDENTITY here (not in env at the job level): the
+      # value comes from the per-tag classification above and electron-vite
+      # reads it from `process.env` during `pnpm build:release` only.
       - name: Build app
         run: pnpm build:release
+        env:
+          ORCA_BUILD_IDENTITY: ${{ steps.tag-classify.outputs.identity }}
+          ORCA_POSTHOG_WRITE_KEY: ${{ secrets.ORCA_POSTHOG_WRITE_KEY }}
 
       # Why: macOS signing secrets (CSC_LINK, CSC_KEY_PASSWORD) must NOT be
       # passed to non-macOS builds. electron-builder uses CSC_LINK as the
@@ -561,6 +601,24 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      # Why post-publish (not pre-publish): electron-builder packs and
+      # uploads in a single `--publish always` invocation, so there is no
+      # cheap insertion point between pack and upload without splitting
+      # that step. Running verify last still blocks the bad release: the
+      # binary is uploaded to the draft, but a failed matrix job blocks
+      # the `publish-release` job (which depends on `build`) from flipping
+      # the release from draft → published, so users never see it. A human
+      # then deletes the draft and re-cuts.
+      #
+      # Why this guards against: a misconfigured CI run where
+      # `ORCA_POSTHOG_WRITE_KEY` is unset or the tag fails to classify
+      # would otherwise produce a binary with `BUILD_IDENTITY = null` and
+      # `WRITE_KEY = null`, which silently disables transport
+      # (`IS_OFFICIAL_BUILD === false`) — the exact failure mode flagged
+      # in PR #1385's deferred follow-up.
+      - name: Verify telemetry constants present in app.asar
+        run: node config/scripts/verify-telemetry-constants.mjs
+
   publish-release:
     needs:
       - cut
diff --git a/CLAUDE.md b/CLAUDE.md
index 656f0c42715..43c994c2d36 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,24 +1 @@
-# CLAUDE.md
-
-See also: [AGENTS.md](./AGENTS.md) for agent-specific rules.
-
-## Code Comments: Document the "Why"
-
-When implementing behavior driven by a design doc, spec, or non-obvious constraint, **add a comment explaining why** the code does what it does — not just what it does. This is especially important for:
-
-- **Safety constraints** — e.g., suppressing an action because it could silently erase a signal, re-create a conflict, or mislead the user.
-- **Fallback/error-handling choices** — e.g., defaulting to `'modified'` on fs error because it's the least misleading option.
-- **Architectural boundaries** — e.g., why state lives in the renderer and never crosses IPC, or why a feature belongs to Source Control and not Checks.
-- **Compatibility shims** — e.g., when a field exists purely for downstream plumbing and does not carry semantic meaning.
-- **Intentional omissions** — e.g., skipping submodule conflicts or not providing rename metadata because the data source doesn't support it.
-
-A future maintainer who hasn't read the design doc should be able to understand from the comment alone why the code must not be changed casually.
-
-## Package Manager
-
-This project uses **pnpm**. Never use `npm` or `yarn`.
-
-- Use `pnpm install` (not `npm install`)
-- Use `pnpm add <pkg>` (not `npm install <pkg>`)
-- Use `pnpm run <script>` (not `npm run <script>`)
-- The lock file is `pnpm-lock.yaml`. Do not generate `package-lock.json` or `yarn.lock`.
+@AGENTS.md
diff --git a/README.md b/README.md
index bc7b0835c2a..38f6fa93b30 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,7 @@ Orca supports any CLI agent (*not just this list*).
   <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;
@@ -149,6 +150,7 @@ npx skills add https://github.com/stablyai/orca --skill orca-cli
 - **Discord:** Join the community on **[Discord](https://discord.gg/fzjDKHxv8Q)**.
 - **Twitter / X:** Follow **[@orca_build](https://x.com/orca_build)** for updates and announcements.
 - **Feedback &amp; Ideas:** We ship fast. Missing something? [Request a new feature](https://github.com/stablyai/orca/issues).
+- **Privacy:** See the [privacy & telemetry docs](https://www.onorca.dev/docs/telemetry) for what anonymous usage data Orca collects and how to opt out.
 - **Show Support:** Star this repo to follow along with our daily ships.
 
 ---
diff --git a/config/scripts/verify-telemetry-constants.mjs b/config/scripts/verify-telemetry-constants.mjs
new file mode 100644
index 00000000000..24f36563532
--- /dev/null
+++ b/config/scripts/verify-telemetry-constants.mjs
@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+// Asserts that the telemetry compile-time constants — `ORCA_BUILD_IDENTITY`
+// and `ORCA_POSTHOG_WRITE_KEY` — were substituted into the shipped binary.
+// Closes the gap PR #1385 flagged: a release built without those env vars
+// produces an `IS_OFFICIAL_BUILD === false` binary that ships silently and
+// transmits nothing. This script runs after `electron-builder` has packed
+// the app and BEFORE the GitHub release is flipped from draft → published.
+// A failure here fails the matrix job; the draft release stays in place
+// until a human resolves it.
+//
+// We grep the packed `app.asar`'s `out/main/*.js` files (the same files
+// that the runtime loads) rather than the unpacked `out/`. asar is a
+// tar-like archive that doesn't transform contents, so the two are
+// byte-equivalent today — but verifying the asar protects against any
+// future config change that excludes the main bundle from the package.
+//
+// Forward-compat: while `TELEMETRY_ENABLED` is `false` in the source, the
+// bundler dead-code-eliminates the entire transport block, so the
+// `BUILD_IDENTITY = "..."` and `WRITE_KEY = "phc_..."` constants do not
+// appear in the binary even when env vars are correctly injected. This
+// script reads the source flag at build time and skips the assertion in
+// that case — the moment the flag flips to `true` (PR #1385), every
+// subsequent release is enforced.
+//
+// Cross-platform note: written in Node so it runs identically on the Mac,
+// Linux, and Windows release runners. Locating `app.asar` via `fs.readdir`
+// (instead of POSIX `find`) avoids depending on Git Bash on Windows.
+// Reading the asar via the programmatic `@electron/asar` API (instead of
+// shelling out to `npx asar`) avoids both a network fetch on every run
+// and the Windows `.cmd`-shim/`shell: true` workaround.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+// Why @electron/asar: canonical replacement for the deprecated `asar` package.
+// It's transitively available via electron-builder (and pnpm's
+// `shamefully-hoist=true` in `.npmrc` flattens it into the root
+// `node_modules`). If electron-builder ever drops it, promote this to a
+// direct devDependency in package.json.
+import { extractFile, listPackage } from '@electron/asar'
+
+// Why resolve from import.meta.url instead of cwd: a release runner (or a
+// developer debugging locally) may invoke this script from a non-root cwd.
+// Resolving relative to the script's own location turns a misleading
+// "could not parse TELEMETRY_ENABLED flag" parse error into a clear
+// file-not-found error, and decouples the script from the caller's cwd.
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+function findAsar(rootDir) {
+  // Why: electron-builder produces one `app.asar` per platform-arch combo.
+  // Linux/Windows targets ship one (`dist/linux-unpacked/resources/app.asar`,
+  // `dist/win-unpacked/resources/app.asar`); macOS dual-arch ships two
+  // (`dist/mac/Orca.app/Contents/Resources/app.asar` for x64,
+  // `dist/mac-arm64/Orca.app/Contents/Resources/app.asar` for arm64) because
+  // `electron-builder.config.cjs` declares `arch: ['x64', 'arm64']`. Both
+  // arches share the same JS bundle through electron-vite's single `main`
+  // build, so the constants are identical across them — but verifying every
+  // match catches the regression where one arch's pack drifts (e.g. a future
+  // arch-specific bundle split that forgets to thread the `define` block).
+  const matches = []
+  const stack = [rootDir]
+  while (stack.length > 0) {
+    const dir = stack.pop()
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        stack.push(fullPath)
+      } else if (entry.isFile() && entry.name === 'app.asar') {
+        matches.push(fullPath)
+      }
+    }
+  }
+  return matches
+}
+
+const distDir = process.argv[2] ?? 'dist'
+if (!existsSync(distDir) || !statSync(distDir).isDirectory()) {
+  console.error(`::error::dist directory not found at ${distDir}`)
+  process.exit(1)
+}
+
+// Why: with `TELEMETRY_ENABLED = false` in source, Rollup eliminates the
+// transport block and the substituted constants vanish from the binary.
+// Verifying in that state would always fail. Read the flag from source
+// instead of inferring it from the build, so the gate cannot drift.
+const clientSrcPath = join(repoRoot, 'src/main/telemetry/client.ts')
+const clientSrc = readFileSync(clientSrcPath, 'utf8')
+const enabledMatch = /^const\s+TELEMETRY_ENABLED\s*=\s*(true|false)/m.exec(clientSrc)
+if (!enabledMatch) {
+  console.error(`::error::could not parse TELEMETRY_ENABLED flag from ${clientSrcPath}`)
+  process.exit(1)
+}
+if (enabledMatch[1] === 'false') {
+  console.log(
+    'TELEMETRY_ENABLED is false in source — transport is dead-code-eliminated, ' +
+      'so the BUILD_IDENTITY/WRITE_KEY constants are not expected in the binary. ' +
+      'Skipping asar grep. (Once the flag flips to true, this verify becomes enforcing.)'
+  )
+  process.exit(0)
+}
+
+const asarMatches = findAsar(distDir)
+if (asarMatches.length === 0) {
+  console.error(`::error::could not locate app.asar under ${distDir}`)
+  process.exit(1)
+}
+console.log(`Found ${asarMatches.length} app.asar payload(s) under ${distDir}:`)
+for (const m of asarMatches) {
+  console.log(`  - ${m}`)
+}
+
+// Why these regexes: electron-vite's `define` block substitutes the bare
+// identifiers `ORCA_BUILD_IDENTITY` and `ORCA_POSTHOG_WRITE_KEY` with their
+// JSON-stringified values at build time. `src/main/telemetry/client.ts`
+// then assigns those into module-local consts named `BUILD_IDENTITY` and
+// `WRITE_KEY`. electron-vite's main config is not minified (Vite default for
+// Electron main builds), so Rollup emits the substituted constants verbatim
+// as `const BUILD_IDENTITY = "stable";`. Match that exact emitted shape so a
+// regression — e.g. the env var unset and the substitution falling back to
+// literal `null` — fails the grep instead of slipping through as a falsy-
+// but-stringy value. NOTE: if `build.minify` is ever enabled on the main
+// bundle, esbuild/terser will rename top-level consts and this regex must
+// be revisited (or replaced with a value-based assertion).
+//
+// WRITE_KEY char class includes `_` and `-` because PostHog project API
+// keys use URL-safe base64 alphabet beyond `phc_`.
+const BUILD_IDENTITY_RE = /const\s+BUILD_IDENTITY\s*=\s*"(rc|stable)"/
+const WRITE_KEY_RE = /const\s+WRITE_KEY\s*=\s*"(phc_[A-Za-z0-9_-]+)"/
+
+function verifyAsar(asarPath) {
+  console.log(`Verifying ${asarPath}`)
+
+  // Why list-then-extract (not a hardcoded path): future electron-vite
+  // chunking (e.g. `manualChunks`) could move the constants out of
+  // `out/main/index.js` into `out/main/chunks/telemetry-XYZ.js`. Enumerate
+  // every `.js` under `out/main/` and concatenate before grepping so the
+  // verify is resilient to chunking. listPackage builds entries with the
+  // host `path` module, so on Windows runners separators are backslashes
+  // (`\out\main\index.js`); normalize to forward slashes for the filter
+  // and strip the leading separator (of either kind) before passing the
+  // entry to extractFile.
+  const allEntries = listPackage(asarPath)
+  const mainJsEntries = allEntries.filter((p) => {
+    const normalized = p.replace(/\\/g, '/').replace(/^\/+/, '')
+    return normalized.startsWith('out/main/') && normalized.endsWith('.js')
+  })
+
+  if (mainJsEntries.length === 0) {
+    console.error(`::error::no .js files found under out/main/ in ${asarPath}`)
+    return null
+  }
+
+  const indexJs = mainJsEntries
+    .map((entry) => {
+      // extractFile uses the host path module internally; pass the
+      // host-separator path with the leading separator stripped.
+      const internal = entry.replace(/^[\\/]+/, '')
+      return extractFile(asarPath, internal).toString('utf8')
+    })
+    .join('\n')
+
+  const buildIdentityMatch = BUILD_IDENTITY_RE.exec(indexJs)
+  const writeKeyMatch = WRITE_KEY_RE.exec(indexJs)
+
+  if (!buildIdentityMatch) {
+    console.error(
+      `::error::BUILD_IDENTITY constant missing or unexpected value in ${asarPath}`
+    )
+    const sample = indexJs.match(/.{0,80}BUILD_IDENTITY.{0,80}/g)?.slice(0, 5) ?? []
+    for (const line of sample) {
+      console.error(`  ${line.slice(0, 200)}`)
+    }
+    return null
+  }
+  if (!writeKeyMatch) {
+    console.error(`::error::PostHog WRITE_KEY missing from ${asarPath}`)
+    const sample = indexJs.match(/.{0,80}WRITE_KEY.{0,80}/g)?.slice(0, 5) ?? []
+    for (const line of sample) {
+      console.error(`  ${line.slice(0, 200)}`)
+    }
+    return null
+  }
+
+  return { asarPath, buildIdentity: buildIdentityMatch[1], writeKey: writeKeyMatch[1] }
+}
+
+// Why verify every match (not just the first): macOS dual-arch produces one
+// asar per arch from the same `out/main` bundle, so identical constants are
+// expected — but if a future change introduces an arch-specific bundle split
+// (or a per-arch `electron-vite build` invocation) that forgets to thread
+// the `define` values, only one of the asars would carry the constants and
+// the broken arch would ship transmitting nothing. Looping is cheap insurance
+// against that class of regression. We additionally require every asar to
+// agree on the BUILD_IDENTITY and WRITE_KEY values — a mismatch means the
+// matrix shipped inconsistent build-identity claims, or (worse) per-arch
+// PostHog keys that would split events across projects, both of which are
+// release bugs.
+const results = []
+for (const asarPath of asarMatches) {
+  const result = verifyAsar(asarPath)
+  if (!result) {
+    process.exit(1)
+  }
+  results.push(result)
+}
+
+const distinctIdentities = new Set(results.map((r) => r.buildIdentity))
+if (distinctIdentities.size > 1) {
+  console.error(
+    `::error::asars disagree on BUILD_IDENTITY: ${[...distinctIdentities].join(', ')}`
+  )
+  for (const r of results) {
+    console.error(`  - ${r.asarPath}: ${r.buildIdentity}`)
+  }
+  process.exit(1)
+}
+
+const distinctWriteKeys = new Set(results.map((r) => r.writeKey))
+if (distinctWriteKeys.size > 1) {
+  console.error(`::error::asars disagree on WRITE_KEY across arches`)
+  for (const r of results) {
+    console.error(`  - ${r.asarPath}: ${r.writeKey.slice(0, 8)}... (length=${r.writeKey.length})`)
+  }
+  process.exit(1)
+}
+
+const [first] = results
+console.log(
+  `Telemetry constants verified across ${results.length} asar(s): ` +
+    `BUILD_IDENTITY="${first.buildIdentity}", ` +
+    `WRITE_KEY="${first.writeKey.slice(0, 8)}..." (length=${first.writeKey.length})`
+)
diff --git a/docs/README.es.md b/docs/README.es.md
index 6e2b2ba80c0..c3c531c35f3 100644
--- a/docs/README.es.md
+++ b/docs/README.es.md
@@ -40,6 +40,7 @@ Orca es compatible con cualquier agente CLI (*no solo los de esta lista*).
   <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;
diff --git a/docs/README.ja.md b/docs/README.ja.md
index 43e78f103fd..2fbf2d0387a 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -40,6 +40,7 @@ Orca は任意の CLI エージェントに対応しています（*このリス
   <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;
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 1502ad61318..1f390e29b88 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -40,6 +40,7 @@ Orca 支持任何 CLI 智能体（*不仅限于以下列表*）。
   <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;
diff --git a/docs/back-button-tasks-page.md b/docs/back-button-tasks-page.md
deleted file mode 100644
index 370117cf5d0..00000000000
--- a/docs/back-button-tasks-page.md
+++ /dev/null
@@ -1,138 +0,0 @@
-# Back/Forward support for the Tasks page
-
-## Goal
-
-Make the titlebar back/forward buttons and the `Cmd/Ctrl+Alt+←/→` shortcut
-traverse Tasks visits in addition to worktree activations. Today both are
-no-ops outside `activeView === 'terminal'` (see `App.tsx:616`, `App.tsx:900`).
-
-## Current shape
-
-- History lives in `src/renderer/src/store/slices/worktree-nav-history.ts`.
-- Entries are `string[]` (worktree IDs), recorded from
-  `worktree-activation.ts:96` via `recordWorktreeVisit`.
-- `goBackWorktree`/`goForwardWorktree` skip dead worktrees via
-  `findPrev/NextLiveWorktreeHistoryIndex`, gated by an `activator` ref and
-  `isNavigatingHistory` to prevent re-recording.
-- UI (pre-change): titlebar buttons hidden unless
-  `activeView === 'terminal'`; shortcut ignored outside terminal view.
-
-## Minimal implementation (downscoped)
-
-1. **History entry type** → `string | 'tasks'`.
-   - `findPrev/NextLiveWorktreeHistoryIndex` must short-circuit on `'tasks'`
-     before calling `findWorktreeById` (which takes a worktree id, not a
-     view tag) — Tasks entries are unconditionally live.
-   - Keep `recordWorktreeVisit(worktreeId: string)` signature to avoid churn
-     in `terminals-hydration.test.ts`. Add a sibling
-     `recordViewVisit(entry: 'tasks')` that shares the dedupe/truncate/cap
-     logic.
-   - Keep existing names (`worktreeNavHistory`, `goBackWorktree`,
-     `canGoBackWorktreeHistory`). They're now slight misnomers since
-     entries may be `'tasks'`, but renaming touches ~20 call sites for no
-     behavioral win. Add a one-line comment at the top of the slice
-     stating the entry type and the intentional keeping of the name, so
-     future readers don't assume it's worktree-only.
-
-2. **Record Tasks visits** → call `recordViewVisit('tasks')` from
-   `openTaskPage` (`ui.ts:189`). No `isNavigatingHistory` guard needed:
-   back-to-Tasks routes through `setActiveView('tasks')` per step 3, which
-   never touches `openTaskPage`. The slice's existing adjacent-entry dedupe
-   covers any other re-entry. Note: `openTaskPage` is called with varying
-   `taskPageData` (e.g. `{ taskSource: 'github' }` vs `'linear'` from
-   `SidebarNav.tsx:88,102`); all collapse to a single `'tasks'` entry and
-   dedupe against the current entry, so toggling presets produces no extra
-   history entries. This is consistent with the out-of-scope "no per-entry
-   snapshotting" decision.
-
-3. **Dispatch in goBack/goForward** → based on entry kind:
-   - worktreeId → existing `activator(worktreeId)` path. When current entry
-     is `'tasks'`, no extra view handling is needed:
-     `activateAndRevealWorktree` at `worktree-activation.ts:82-84` already
-     switches `activeView` back to `'terminal'`.
-   - `'tasks'` → `setActiveView('tasks')` (not `openTaskPage` — avoids
-     mutating `previousViewBeforeTasks` and the SWR prefetch).
-
-4. **Fix Esc-close history desync.** `closeTaskPage` (`ui.ts:210`) currently
-   sets `activeView` to `previousViewBeforeTasks` without touching the
-   history index, so after `A → Tasks → Esc` the index still points at the
-   `'tasks'` entry and Back becomes a visual no-op (activator re-activates A)
-   while Forward re-opens Tasks. Fix: in `closeTaskPage`, if the current
-   history entry is `'tasks'`, move the index to the previous live entry
-   (same scan as `findPrevLiveWorktreeHistoryIndex`). Sub-case: if there is
-   no previous live entry (e.g. user's first action was open Tasks, then
-   Esc — history `['tasks']` at index 0), leave the index unchanged at 0.
-   Accept the minor cost (Back becomes a visual no-op until a real visit
-   records a new entry) rather than setting to -1, which would lose the
-   only forward target. Guard with `isNavigatingHistory` is unnecessary
-   here — `closeTaskPage` is never invoked from the history path.
-
-5. **Unhide UI on Tasks** (allowlist, not denylist — `activeView` union is
-   `'terminal' | 'settings' | 'tasks'`, but an allowlist won't silently
-   include future views):
-   - Replace the `activeView !== 'terminal'` early-return at `App.tsx:616`
-     with `activeView !== 'terminal' && activeView !== 'tasks'`. Update the
-     adjacent comment (`App.tsx:613-615`) — it currently claims the
-     shortcut is a no-op outside terminal because the buttons are hidden;
-     replace with: back/forward traverse worktree + Tasks visits, so the
-     shortcut is active whenever the button cluster is (terminal or
-     Tasks); still suppressed elsewhere (Settings).
-   - Change the titlebar cluster guard at `App.tsx:900` to
-     `activeView === 'terminal' || activeView === 'tasks'`. Update the
-     adjacent comment (`App.tsx:896-899`) — drop the "terminal view only"
-     framing; explain the cluster is shown wherever the history shortcut
-     is live, and hidden in Settings to keep that view modal-ish.
-
-6. **Tests**: extend `worktree-nav-history.test.ts` for mixed entries:
-   - `A → Tasks → B`, back lands on Tasks, back again on A.
-   - Tasks dedupe against current entry.
-   - Dead worktree between Tasks entries is skipped.
-   - `A → Tasks → closeTaskPage()`: index moves back to A; subsequent Back
-     is a no-op, Forward re-opens Tasks.
-   - `Tasks (only entry) → closeTaskPage()`: index stays at 0, Back is a
-     visual no-op.
-
-## Explicitly out of scope
-
-- **Settings in history.** Stays modal-ish; closes via
-  `previousViewBeforeSettings`.
-- **Per-entry `taskPageData` snapshotting.** Back-to-Tasks opens Tasks with
-  default filters/source. Revisit if users complain.
-- **Session persistence of history.** Keep in-memory only (it already is).
-
-## Edge cases handled
-
-- Worktree deletion mid-session → skipped by existing live-check; Tasks
-  entries always live.
-- Dedupe semantics → same adjacency rule works for `'tasks'`.
-- Activator failure on worktree → unchanged (`result !== false` gate). Tasks
-  dispatch can't fail.
-- Editable-target guard at `App.tsx:600` still fires first → typing in the
-  Tasks search box + `Cmd+Alt+←` remains a no-op.
-- `MAX_HISTORY = 50` → Tasks entries consume slots; worst-case effective
-  worktree depth halves to ~25. Acceptable.
-
-## Known residual quirks (accepted)
-
-1. **Prefetch loss on back-to-Tasks.** Routing through `setActiveView('tasks')`
-   skips the SWR prefetch at `ui.ts:201-208`; back-to-Tasks is ~300–800ms
-   slower than a fresh open via the sidebar. Not a regression vs today
-   (back-to-Tasks isn't possible at all today).
-
-2. **Titlebar layout shift.** Revealing the button cluster on Tasks changes
-   the titlebar — needs a visual check that nothing Tasks-specific collides.
-
-## Files touched
-
-- `src/renderer/src/store/slices/worktree-nav-history.ts` — entry type,
-  `recordViewVisit`, dispatch in `goBack/goForwardWorktree`.
-- `src/renderer/src/store/slices/worktree-nav-history.test.ts` — new cases.
-- `src/renderer/src/store/slices/ui.ts` — `openTaskPage` records via
-  `recordViewVisit`; `closeTaskPage` rewinds history index when the current
-  entry is `'tasks'`.
-- `src/renderer/src/App.tsx` — widen the two `activeView === 'terminal'`
-  guards to include `'tasks'`, and update the adjacent "why" comments at
-  `App.tsx:613-615` and `App.tsx:896-899` to reflect the new invariant.
-
-Estimated diff: ~30 lines of slice logic, 1 call site in `ui.ts`, 2 guards
-in `App.tsx`, plus tests.
diff --git a/docs/cmd-j-empty-query-ordering.md b/docs/cmd-j-empty-query-ordering.md
deleted file mode 100644
index d687f27527b..00000000000
--- a/docs/cmd-j-empty-query-ordering.md
+++ /dev/null
@@ -1,222 +0,0 @@
-# Cmd+J empty-query ordering: use visit recency, not activity recency
-
-## Problem
-
-When Cmd+J opens with no query, the `sortedWorktrees` memo in
-`WorktreeJumpPalette.tsx` orders the Worktrees section by
-`Worktree.lastActivityAt` before the empty-query cap is applied. The cap is
-conditional: with browser tabs present, Worktrees is capped at 5 so browser
-rows stay visible above the fold (see the `__hint_worktree_cap__` branch in
-the same file); with no browser tabs, the list is uncapped.
-
-For worktrees with low background signal — notably SSH-backed worktrees —
-`lastActivityAt` can remain old even when the user was just working there.
-Those worktrees get pushed below the visible empty-query rows by local
-worktrees that emitted incidental PTY/activity events. The user then has to
-type a substring to surface the worktree they just visited, which defeats
-the purpose of the empty-query switcher.
-
-Reported symptom: an SSH worktree the user was working in minutes ago does
-not appear in the visible Cmd+J empty-query list; typing any substring
-surfaces it.
-
-## Product model
-
-Cmd+J with an empty query is a fast switcher. It should answer: "where am I
-likely to jump next?"
-
-That is different from both existing recency signals:
-
-- `lastActivityAt` answers "where did work happen?" Right for activity-aware
-  surfaces, wrong for SSH or quiet worktrees where user focus is not
-  accompanied by local PTY/activity signals.
-- `worktreeNavHistory` (see `recordWorktreeVisit` in the
-  `worktree-nav-history` slice) answers "what is the Back/Forward stack?"
-  That stack has index, forward-history, duplicate, and `'tasks'` semantics
-  that are useful for sequential navigation but unrelated to switcher
-  ranking.
-
-The switcher needs its own persisted focus-recency signal. This doc uses
-"focus recency" throughout.
-
-## Proposal
-
-Persist a per-worktree focus-recency timestamp and use it as the primary
-ordering signal for Cmd+J's empty-query Worktrees section.
-
-Store shape, added to `src/renderer/src/store/slices/worktrees.ts` (the
-slice that already owns `activeWorktreeId` and is the natural home for
-per-worktree UI recency):
-
-```ts
-lastVisitedAtByWorktreeId: Record<string, number>
-markWorktreeVisited: (worktreeId: string, visitedAt?: number) => void
-```
-
-`markWorktreeVisited` must be monotonic: if the supplied (or current)
-timestamp is not strictly greater than the stored value, it is a no-op. This
-matters because CLI-driven and IPC-driven activations can race, and we do
-not want an older timestamp to regress recency.
-
-### Stamp site
-
-Stamp from `activateAndRevealWorktree` (`src/renderer/src/lib/worktree-activation.ts`),
-**immediately after the `state.setActiveWorktree(worktreeId)` call at
-line 91**, synchronously, before any of the later view/terminal/reveal
-steps. This guarantees the stamp lands even if a subsequent async step
-fails, since the user already perceives the switch as successful once
-`activeWorktreeId` flips.
-
-Do this *in addition to*, not gated on, the existing
-`state.recordWorktreeVisit(worktreeId)` call; the nav-history slice has
-different semantics (see "Why not use `worktreeNavHistory`").
-
-Do **not** stamp from `setActiveWorktree` directly. That raw setter is
-invoked by hydration, session restore, and test setup — stamping there
-would reset focus recency for the restored workspace on every app launch.
-
-### Activation-path audit
-
-Every user-initiated worktree switch must route through
-`activateAndRevealWorktree`. Before landing, audit direct callers of
-`setActiveWorktree` and classify each:
-
-- **User switches** (sidebar clicks, Cmd+J selections, CLI activations,
-  status-bar/session jumps, deep links) — must go through activation.
-- **Non-user transitions** (store hydration, session restore, tests) — must
-  NOT stamp.
-
-The audit output belongs in the PR description. Do not stamp
-`Worktree.lastActivityAt`.
-
-### Ordering rule (empty query only)
-
-1. Start from visible worktrees: skip `isArchived`, and keep honoring
-   `hideDefaultBranchWorkspace` via `isDefaultBranchWorkspace`.
-2. Build a separate `switchableWorktrees` list that excludes the currently
-   active worktree. Keep the full visible list for loading/empty-state/count
-   logic so the palette never claims there are no worktrees just because the
-   only visible worktree is current.
-3. Sort `switchableWorktrees` by:
-   - `lastVisitedAtByWorktreeId[id]` descending, when present.
-   - `lastActivityAt` descending as the fallback for never-visited or
-     pre-migration worktrees.
-   - `displayName.localeCompare` as the final stable tie-breaker.
-4. Preserve the conditional cap: cap Worktrees at 5 only when browser rows
-   exist (the existing `__hint_worktree_cap__` logic); otherwise leave the
-   Worktrees section uncapped.
-5. Preserve the existing "Type to see all N worktrees" hint, but compute `N`
-   from switchable rows. Empty-state copy is based on the full visible list.
-
-Typing any non-empty query still routes through `sortWorktreesSmart`. No
-change to the sidebar, `sortEpoch`, or `lastActivityAt` semantics.
-
-### Current worktree handling
-
-Cmd+J is a switch surface. Exclude the current worktree from empty-query
-rows in v1. Keep two separate lists so empty-state logic is not affected:
-
-- `visibleWorktreesForState`: includes the current worktree and drives
-  "loading", "has any worktrees", and empty-state decisions.
-- `switchableWorktreesForRows`: excludes the current worktree and drives the
-  actual empty-query Worktrees rows.
-
-A "Current" row variant is out of scope.
-
-## Why not use `worktreeNavHistory`
-
-`worktreeNavHistory` records activations but is the wrong abstraction for
-Cmd+J ordering.
-
-- Back/Forward history is an indexed stack. Cmd+J is an unordered switcher
-  ranked by likely target.
-- History contains `'tasks'` entries; Cmd+J rows should not need to
-  understand task-page sentinels.
-- Back/Forward navigation can leave forward entries in the stack. A raw
-  newest-to-oldest walk either incorrectly includes future entries or needs
-  custom interpretation of `worktreeNavHistoryIndex`.
-- History dedupe rules are stack-oriented. A per-worktree timestamp is
-  simpler and directly models the switcher need.
-
-Keep `worktreeNavHistory` for Back/Forward.
-
-## Migration and persistence
-
-Persist `lastVisitedAtByWorktreeId` via the same zustand persist path that
-survives app restart.
-
-- **Downgrade:** older builds will drop the unknown key on rehydrate
-  (zustand `partialize` strips anything the slice doesn't declare). No
-  custom migration needed; record this explicitly in the PR so nobody
-  invents one.
-- **Pruning:** drop entries whose worktree IDs are no longer present —
-  **after worktree hydration completes**, not on raw rehydrate. Repos load
-  async; pruning too early would nuke timestamps for worktrees whose repo
-  hasn't yet hydrated.
-- **Seeding active on restore:** if, after hydration, the active worktree
-  has no stored timestamp, seed it with the current time from the
-  hydration-complete handler — not by calling `markWorktreeVisited` from
-  `setActiveWorktree`. The two paths have intentionally different
-  semantics (seeding is a migration fixup; stamping is focus recency).
-- Never-visited worktrees stay without timestamps and fall back to
-  `lastActivityAt`.
-
-The map is bounded by live worktree IDs, so no history cap is needed.
-
-## Non-goals
-
-- Changing sidebar sort order.
-- Changing `lastActivityAt` semantics or when it is stamped.
-- Changing the typed-query path; smart-sort remains authoritative.
-- Making Cmd+J mirror Back/Forward history.
-- Persisting Cmd+J UI state such as query, scroll position, or selection.
-- Adding a "Current" row variant.
-
-## Implementation sketch
-
-- Add `lastVisitedAtByWorktreeId` and `markWorktreeVisited` to the
-  `worktrees` slice; persist via the existing persist config.
-- In `activateAndRevealWorktree`, call `markWorktreeVisited(worktreeId)`
-  immediately after `state.setActiveWorktree(worktreeId)` (line 91),
-  synchronously. Focus recency, not work activity.
-- Update the `sortedWorktrees` memo in `WorktreeJumpPalette.tsx` so the
-  empty-query branch uses subscribed store inputs:
-  `lastVisitedAtByWorktreeId`, `activeWorktreeId`, visible worktrees, and
-  existing palette filters. Avoid reading `useAppStore.getState()` inside a
-  memo as the only source of ordering data; that can produce stale UI.
-- Keep the typed-query branch on `sortWorktreesSmart`.
-- Keep browser-tab search ordering unchanged unless a separate browser
-  visit-recency issue is discovered.
-- Extract a pure function `orderEmptyQueryWorktrees` so ordering,
-  current-worktree exclusion, and fallback behavior are testable without
-  mounting the whole palette.
-
-## Tests
-
-Add focused tests for the ordering helper:
-
-- Recently visited SSH/quiet worktree ranks above a locally active worktree
-  with newer `lastActivityAt`.
-- Never-visited worktrees fall back to `lastActivityAt`.
-- Current worktree is excluded from empty-query rows but still counted for
-  empty-state logic.
-- Worktrees cap remains conditional on browser rows.
-- `hideDefaultBranchWorkspace` and `isArchived` still filter rows.
-- Non-empty query still uses `sortWorktreesSmart` order.
-- Hydration seeds the active worktree's timestamp when missing.
-- `markWorktreeVisited` is monotonic: an older timestamp does not regress
-  the stored value.
-
-Do not put these tests in `worktree-palette-search.test.ts` unless the pure
-search function itself changes. That file verifies matching behavior and
-input order preservation, not empty-query ranking.
-
-## Risks
-
-- **Activation paths that bypass `activateAndRevealWorktree`.** Any
-  user-visible switch that calls `setActiveWorktree` directly will skip the
-  stamp. Mitigation: the activation-path audit above.
-- **False empty states after current-worktree exclusion.** Mitigation:
-  separate `visibleWorktreesForState` and `switchableWorktreesForRows`.
-- **Pruning before hydration.** Mitigation: prune in the
-  hydration-complete handler, not on raw rehydrate.
diff --git a/docs/cmd-j-scoped-jump-palette-plan.md b/docs/cmd-j-scoped-jump-palette-plan.md
deleted file mode 100644
index a93a02f241f..00000000000
--- a/docs/cmd-j-scoped-jump-palette-plan.md
+++ /dev/null
@@ -1,480 +0,0 @@
-# Design Document: Scoped Cmd+J Jump Palette for Worktrees and Browser Tabs
-
-**Status:** Draft
-**Date:** 2026-04-15
-
-## 1. Summary
-
-Extend Orca's existing `Cmd+J` / `Ctrl+Shift+J` worktree palette into a single app-wide jump surface with explicit scopes. The first release keeps the palette centered on two jobs:
-
-- jump to a worktree
-- jump to an already-open browser page across any worktree
-
-The palette opens into a lightweight scope switcher with three modes:
-
-- `All`
-- `Worktrees`
-- `Browser Tabs`
-
-Users can press `Tab` / `Shift+Tab` to cycle scopes without leaving the keyboard. The default contract on open remains `Worktrees`, not `All`, so existing users still land in the familiar worktree-first flow before opting into broader search. Search results stay intentionally narrow: browser-only discovery is supported because the user explicitly needs to find already-open pages across worktrees, but the palette does not become a generic "everything" bucket in v1.
-
-## 1.1 Phase 0.5 Direction Lock
-
-Phase 0.5 locked three product decisions for v1:
-
-- `Cmd+J` still opens into `Worktrees` by default.
-- Browser discovery indexes live open `BrowserPage`s, not just browser workspace containers.
-- Browser ordering uses a simple context-first heuristic instead of true last-focused recency state.
-
-Why these decisions were chosen:
-
-- `Cmd+J` already has a strong worktree-switching contract in Orca. Making `All` the default would silently turn a familiar command into a mixed-ranking surface and force existing users to re-learn the first screen they see.
-- The remembered object in the browser case is the page itself. Searching only browser workspace shells would miss the page-level titles and URLs users actually recall when they say "I know I already have this open somewhere."
-- True global browser recency would require new focus-tracking state whose only initial consumer is palette ranking. A simple heuristic is easier to ship, easier to explain, and good enough for the first version of this discovery workflow.
-
-## 2. Problem
-
-Orca already supports multiple concurrent worktrees and persistent in-app browser tabs. Users can jump between worktrees with the existing `Cmd+J` palette, but they cannot quickly answer a more specific question:
-
-> "I know I already have this page open somewhere. Which worktree is it in, and how do I get back to it?"
-
-The current worktree palette is container-first. That works when the user remembers the worktree identity, but it breaks down when the remembered thing is a page title, host, or URL path.
-
-This is a discovery problem, not a recency problem. A cycle UI is poor at it because:
-
-- the user often does not know which worktree owns the target tab
-- multiple browser tabs can share similar titles
-- cycling scales badly once many worktrees have open tabs
-
-## 3. Goals
-
-- Preserve `Cmd+J` / `Ctrl+Shift+J` as Orca's single global jump entry point.
-- Let users search open browser pages across all worktrees.
-- Keep worktree search fast and familiar for existing users.
-- Make scope switching explicit and keyboard-first.
-- Avoid overcommitting Orca to a generic "search all open items" model before the product is ready to support terminals, editors, and commands consistently.
-- Preserve the existing expectation that `Cmd+J` opens as a worktree-first jump flow.
-
-## 4. Non-Goals
-
-- Searching terminal scrollback or editor contents.
-- Adding a persistent sidebar or browser-tab manager panel.
-- Replacing local `Ctrl+Tab` behavior or introducing a new cycle UI.
-- Expanding `Cmd+J` into files, terminals, editor tabs, or commands in this change.
-
-## 5. UX
-
-### 5.1 Entry Point
-
-Keep the existing shortcut:
-
-- macOS: `Cmd+J`
-- Windows/Linux: `Ctrl+Shift+J`
-
-This shortcut already means "global jump" inside Orca and is already forwarded correctly even when an embedded browser guest owns focus. Reusing it preserves muscle memory and avoids proliferating navigation surfaces.
-
-### 5.2 Scope Model
-
-The palette header contains three explicit scope chips:
-
-- `All`
-- `Worktrees`
-- `Browser Tabs`
-
-Keyboard behavior:
-
-- `Tab`: next scope
-- `Shift+Tab`: previous scope
-- `Up` / `Down`: move selection within results
-- `Enter`: activate selected result
-- `Esc`: close palette
-
-Default scope on open: `Worktrees`.
-
-Why this shape:
-
-- one entry point is easier to remember than separate dialogs
-- explicit scopes prevent a mixed list from becoming noisy
-- `Tab` matches the mental model of "move across modes" without conflicting with list navigation
-- opening in `Worktrees` preserves today's default behavior and makes `All` an explicit expansion, not a silent contract change
-
-### 5.3 Scope Semantics
-
-#### `All`
-
-Merged result list of:
-
-- open browser pages across all worktrees
-- worktrees across all repos
-
-Ranking rules:
-
-- strong browser title matches rank above weak worktree metadata matches
-- host/url matches get boosted when the query resembles a domain, URL, or path fragment
-- exact worktree name matches still beat weak browser matches
-- current worktree/current browser page receive a small context boost when otherwise tied
-- browser results use the same heuristic ordering as `Browser Tabs`; v1 does not add hidden last-focused browser recency state just for this merged scope
-
-`All` is meant to feel smart, not exhaustive.
-
-#### `Worktrees`
-
-Equivalent to today's worktree palette behavior:
-
-- same global search semantics for worktree metadata
-- same recent-first ordering for the default empty-query state
-- same selection and activation behavior
-
-#### `Browser Tabs`
-
-Shows only open browser pages across all worktrees. The user-facing scope label stays `Browser Tabs`, but each row maps to a live `BrowserPage`, not a browser workspace shell.
-
-Empty query ordering:
-
-1. current browser page, if any
-2. other open browser pages in the current worktree
-3. browser pages in other worktrees, grouped by the existing worktree ordering and then sorted by title, falling back to URL
-
-This mode is the direct answer to "just show me all open browsers."
-
-Why this ordering:
-
-- it pulls the user's current context to the top without inventing new global recency state
-- it stays stable enough that users can learn where results tend to land
-- it keeps the implementation honest about what Orca already knows today versus what would require new focus-history plumbing
-
-### 5.4 Result Rows
-
-#### Browser tab row
-
-Primary text:
-
-- current page title, falling back to formatted URL when the title is blank or useless
-
-Secondary text:
-
-- host + trimmed path
-
-Context chips on the right:
-
-- repo name
-- worktree display name
-
-Optional badges:
-
-- `Current Tab`
-- `Current Worktree`
-
-Why this is required:
-
-- browser tab titles are often duplicated (`localhost`, `Settings`, `Dashboard`)
-- users need immediate disambiguation without opening the result
-- worktree context is the whole point of the feature
-- each row represents the actual page the user remembers, while worktree and repo chips explain where that page lives
-
-#### Worktree row
-
-Keep the existing row structure:
-
-- worktree display name
-- branch
-- optional supporting text for comment / PR / issue
-- repo badge
-
-This avoids making existing users relearn the palette.
-
-### 5.5 Empty States
-
-`All`
-
-- If no worktrees and no browser tabs exist: `No worktrees or open browser tabs`
-- If query yields no results: `No matches in worktrees or browser tabs`
-
-`Worktrees`
-
-- Preserve existing copy
-
-`Browser Tabs`
-
-- No open browser tabs: `No open browser tabs`
-- No query matches: `No browser tabs match your search`
-
-### 5.6 Activation Behavior
-
-Selecting a worktree result:
-
-- preserve current `activateAndRevealWorktree(worktreeId)` behavior
-
-Selecting a browser result:
-
-1. activate and reveal the owning worktree
-2. focus the target browser workspace tab
-3. select the target `BrowserPage` inside that workspace
-4. set `activeTabType` to `browser`
-5. close the palette
-6. restore focus into the browser surface, not the terminal/editor fallback
-
-Why this ordering matters:
-
-- browser pages are subordinate to worktree activation in Orca's model
-- worktree-first activation restores the right workspace state and sidebar visibility
-- selecting a browser result should feel like "take me there directly," not "switch worktree and make me pick again"
-
-## 6. Data Model and Search Inputs
-
-### 6.1 Worktree Results
-
-Use the existing search surface:
-
-- `displayName`
-- branch
-- repo name
-- comment
-- linked PR number/title
-- linked issue number/title
-
-### 6.2 Browser Tab Results
-
-Search only currently open browser pages, not history and not just browser workspace shells.
-
-For each browser result, index:
-
-- page title
-- page URL
-- formatted host/path
-- owning browser workspace label, if available
-- owning worktree display name
-- owning repo display name
-
-Each open `BrowserPage` contributes its own result row. Browser workspaces still matter for ownership and activation, but they are context, not the searchable unit.
-
-This is intentionally limited to live open pages because Orca still is not an app-wide browsing history system. The goal is to help users recover something they already have open, not to introduce a second browsing history feature through the palette.
-
-### 6.3 Why Not Terminal Tabs Yet
-
-Terminal tabs are deliberately out of scope for text-first search in this change.
-
-Reasons:
-
-- terminal tab titles are less stable and less descriptive than browser titles
-- the meaningful part of a terminal session often lives in scrollback, not tab metadata
-- adding terminal tabs only because browser tabs are added would create a low-signal mixed palette
-
-This design keeps the palette honest: it supports browser-page search because that metadata makes the target genuinely searchable. If Orca later wants an "all open items" palette, that should be a deliberate follow-up with result quality standards for each item type.
-
-## 7. Architecture
-
-### 7.1 Existing Pieces Reused
-
-- `WorktreeJumpPalette.tsx` remains the base surface and interaction shell.
-- Existing worktree search logic remains intact for the `Worktrees` scope.
-- Browser search input comes from the live open `BrowserPage`s already held by renderer browser state.
-- Browser activation continues to use the existing browser-workspace activation pathway after worktree activation, then selects the matching page inside that workspace.
-- Main-process shortcut forwarding remains unchanged.
-
-### 7.2 New Search Model
-
-Add a palette view-model layer that produces typed results:
-
-```ts
-type JumpPaletteScope = 'all' | 'worktrees' | 'browser-tabs'
-
-type JumpPaletteResult =
-  | { type: 'worktree'; worktreeId: string; score: number; ... }
-  | {
-      type: 'browser-page'
-      worktreeId: string
-      browserTabId: string
-      browserPageId: string
-      score: number
-      ...
-    }
-```
-
-The existing worktree search helper remains responsible for worktree scoring. A new browser-page search helper handles browser result scoring and formatting. The palette shell merges and sorts results only in `All`.
-
-Why split the search helpers:
-
-- worktree matching logic is already non-trivial and should not be regressed
-- browser result ranking has different signals than worktree ranking
-- typed results keep selection and rendering explicit instead of relying on ad hoc ID prefixes
-- page-level browser hits need both workspace ownership and page identity for activation
-
-### 7.3 Focus and Close Semantics
-
-The existing palette already manages focus restoration carefully. That logic should be extended, not replaced.
-
-New rule:
-
-- if the selected result is a browser page, the post-close focus path targets the active browser surface
-- otherwise preserve today's terminal/editor focus restoration behavior
-
-### 7.4 System Context
-
-```text
-+------------------+        +-----------------------+
-| Main Process     |        | Renderer Store        |
-| shortcut forward | -----> | activeModal           |
-| Cmd+J / Ctrl+... |        | worktreesByRepo       |
-+------------------+        | browser state         |
-                            | activeWorktreeId      |
-                            +-----------+-----------+
-                                        |
-                                        v
-                            +------------------------+
-                            | Cmd+J Jump Palette     |
-                            | scopes + search + list |
-                            +-----+-------------+----+
-                                  |             |
-                    worktree hit   |             | browser-page hit
-                                  v             v
-                     +------------------+   +---------------------+
-                     | activate/reveal  |   | activate/reveal     |
-                     | target worktree  |   | target worktree     |
-                     +------------------+   +----------+----------+
-                                                       |
-                                                       v
-                                            +----------------------+
-                                            | activate browser     |
-                                            | workspace + page     |
-                                            | focus browser pane   |
-                                            +----------------------+
-```
-
-### 7.5 Data Flows
-
-#### Happy path: browser-page search and jump
-
-```text
-Cmd+J -> palette opens in Worktrees -> user switches to Browser Tabs ->
-query matches browser page ->
-user presses Enter -> activateAndRevealWorktree(worktreeId) ->
-activate target browser workspace and page -> palette closes -> browser surface focused
-```
-
-#### Nil path: user opens palette with no browser pages
-
-```text
-Cmd+J -> palette opens -> Browser Tabs scope selected ->
-search model sees zero browser pages -> empty state shown -> no side effects
-```
-
-#### Empty path: query yields no browser or worktree matches
-
-```text
-query typed -> search returns [] -> scope-specific empty state rendered ->
-selection cleared or pinned to no result -> Enter does nothing
-```
-
-#### Upstream error path: selected browser page disappears before activation
-
-```text
-user selects browser result -> store lookup fails because page/worktree closed ->
-show toast error -> keep palette open if possible, otherwise close safely without switching
-```
-
-## 8. Alternatives Considered
-
-### 8.1 Dedicated browser-tab-only dialog
-
-Pros:
-
-- clearer mental model for the browser-specific job
-- no mixed-result ranking complexity
-
-Cons:
-
-- adds another shortcut and another navigation surface
-- weakens `Cmd+J` as the single place to jump around Orca
-
-Decision: rejected for now. The scoped palette gives the same utility with less surface area.
-
-### 8.2 Browser tabs only inside `Cmd+J`, no scopes
-
-Pros:
-
-- least new UI chrome
-
-Cons:
-
-- mixed results become harder to reason about
-- users cannot quickly answer "just show me browser tabs"
-
-Decision: rejected. Explicit scopes are worth the small extra header chrome.
-
-### 8.3 Expand immediately to terminals, files, and commands
-
-Pros:
-
-- one "go to anything" story
-
-Cons:
-
-- scope explosion
-- result quality is uneven across item types
-- much higher design and implementation complexity
-
-Decision: rejected for v1. Start with the two jobs the user clearly asked for.
-
-### 8.4 Make `All` the default scope
-
-Pros:
-
-- makes browser discovery visible immediately
-- creates a more obviously "global" first impression
-
-Cons:
-
-- breaks the current worktree-first contract of `Cmd+J`
-- makes the first screen depend on mixed ranking logic instead of today's predictable worktree list
-
-Decision: rejected for v1. `All` remains available, but opening in `Worktrees` preserves muscle memory and keeps the expansion explicit.
-
-### 8.5 Search browser workspaces instead of live pages
-
-Pros:
-
-- simpler indexing model
-- reuses the existing browser workspace abstraction directly
-
-Cons:
-
-- misses the page titles and URLs users actually remember
-- treats the container as the search target even when the user wants a specific page inside it
-
-Decision: rejected. The palette should index the page the user is trying to recover, then use workspace and worktree context to explain where it lives.
-
-### 8.6 Add true browser recency tracking for v1 ranking
-
-Pros:
-
-- could produce sharper empty-query ordering over time
-
-Cons:
-
-- requires new state and focus bookkeeping for a thin initial payoff
-- introduces ranking behavior that is harder to explain and debug
-
-Decision: rejected for v1. Start with a deterministic context-first heuristic and revisit true recency only if usage shows the heuristic is insufficient.
-
-## 9. Rollout
-
-### Phase 1
-
-- Add scoped header to the existing `Cmd+J` palette
-- Keep `Worktrees` as the default scope on open
-- Preserve worktree-only behavior under the `Worktrees` scope
-- Add browser-page search and activation
-- Search live open `BrowserPage`s rather than browser workspace shells
-- Add `All` merged ranking
-
-### Phase 2 (optional follow-up)
-
-- Evaluate whether users need additional scopes such as editor tabs or commands
-- Only add a new scope if it has a clear, high-signal search model
-
-## 10. Open Questions
-
-- Whether a later iteration should remember a last-used non-default scope without changing the default-open `Worktrees` contract
-- Whether browser-tab results should expose close actions from the palette in a later pass
-- Whether `All` should group results visually by type or keep one flat ranked list
diff --git a/docs/codex-account-switching-design.md b/docs/codex-account-switching-design.md
deleted file mode 100644
index f9ef5c06862..00000000000
--- a/docs/codex-account-switching-design.md
+++ /dev/null
@@ -1,451 +0,0 @@
-# Codex Account Switching Design
-
-**Status:** Draft
-**Date:** 2026-04-17
-
-## Summary
-
-Orca's current Codex account switcher swaps the entire `CODEX_HOME` for each managed account. That isolates authentication, but it also unintentionally forks config, permissions, history, sessions, memories, skills, and other local Codex state. The result is that account switching feels like switching between separate Codex installs instead of switching which account powers the same Codex environment.
-
-The recommended design is:
-
-- Keep `~/.codex` as the shared runtime `CODEX_HOME` for all Codex user state.
-- Store only `auth.json` per managed account in Orca-owned storage.
-- Introduce a dedicated main-process runtime-home owner that materializes the selected account's `auth.json` into the shared runtime home before any Codex launch, login, or rate-limit fetch.
-- Restart live Codex panes after switch; newly launched panes use the new account while preserving the shared Codex state.
-
-This matches the intended product behavior: account switching is for authentication and usage limits, not for creating separate Codex worlds. It also matches how manual Codex account switching already behaves outside Orca: logging out and back in mutates the same `~/.codex` state the user sees in terminal Codex.
-
-## Motivation
-
-The current managed-account design causes user-visible problems:
-
-- `config.toml` diverges per account, so permissions and sandbox defaults reset unexpectedly.
-- `history.jsonl` and `sessions/` are scoped per managed home, so chat history appears to disappear after account switches.
-- `memories`, `skills`, `rules`, and likely sqlite-backed local state drift per account.
-- Live sessions require restart because the active terminal process keeps using the old `CODEX_HOME`.
-
-We already patched the first symptom by syncing `config.toml` into managed homes. That is a tactical fix, not the right long-term model. The full-home-per-account design still leaves history and session continuity split across accounts.
-
-The deeper issue is ownership. Orca currently has no single component that owns Codex runtime state preparation. `CodexAccountService`, `pty.ts`, rate-limit fetchers, and usage scanning each participate in path or environment decisions. The long-term fix must therefore be a runtime-home ownership refactor, not just a storage-layout tweak.
-
-## Current State
-
-### Orca behavior today
-
-- Managed accounts are created under `app.getPath('userData')/codex-accounts/<id>/home`.
-- Orca selects an account by updating `settings.activeCodexManagedAccountId`.
-- New Codex PTYs inherit the selected managed home's path as `CODEX_HOME`.
-- Codex rate-limit fetches also use that selected managed home.
-
-Relevant code:
-
-- [src/main/codex-accounts/service.ts](/Users/jinwoohong/orca/workspaces/orca/codex-fix-2/src/main/codex-accounts/service.ts)
-- [src/main/ipc/pty.ts](/Users/jinwoohong/orca/workspaces/orca/codex-fix-2/src/main/ipc/pty.ts)
-- [src/main/codex-usage/scanner.ts](/Users/jinwoohong/orca/workspaces/orca/codex-fix-2/src/main/codex-usage/scanner.ts)
-
-### Codex state observed on disk
-
-On a typical install, `CODEX_HOME` contains at least:
-
-- `auth.json`
-- `config.toml`
-- `history.jsonl`
-- `sessions/`
-- `memories/`
-- `skills/`
-- `rules/`
-- `shell_snapshots/`
-- `models_cache.json`
-- `logs_2.sqlite`
-- `state_5.sqlite`
-- `installation_id`
-- `version.json`
-
-Because Orca currently swaps the whole home, all of that becomes account-scoped.
-
-## Goals
-
-- Make Codex account switching feel like swapping credentials, not swapping environments.
-- Preserve one continuous Codex history and session store across accounts.
-- Keep permissions, sandbox defaults, MCP config, memories, and other user state stable across account changes.
-- Preserve Orca's existing account-switch UX: one selected active account at a time, with restart prompts for live Codex panes.
-- Keep the solution cross-platform across macOS, Linux, and Windows.
-
-## Non-Goals
-
-- Supporting simultaneous live Codex sessions under different accounts in the same Orca instance.
-- Changing Codex upstream behavior or requiring first-class multi-account support from Codex.
-- Building a replication system that continuously merges multiple independent `CODEX_HOME` trees.
-
-## Constraints
-
-### Codex does not currently expose a separate auth path
-
-From local CLI inspection, Codex supports:
-
-- `CODEX_HOME`
-- config overrides via `-c key=value`
-
-It does not currently expose a first-class "shared config/home plus separate auth profile" interface. There is an upstream feature request for auth profiles, which suggests Orca cannot rely on such a feature today.
-
-### Orca is cross-platform
-
-The design must work on macOS, Linux, and Windows. That rules out relying on symlink-heavy designs as the primary solution:
-
-- Windows symlink/junction behavior is more fragile.
-- Atomic copy + rename is simpler and more portable.
-- Node path utilities should be used everywhere.
-
-### Orca's current mental model is single selected account
-
-The current switcher already assumes one active account at a time and uses restart prompts for live Codex panes. The recommended design leans into that model rather than trying to support concurrent mixed-account sessions.
-
-## Options Considered
-
-### Option 1: Keep full per-account homes and sync everything
-
-Each managed account keeps its own full `CODEX_HOME`, and Orca syncs:
-
-- `config.toml`
-- `history.jsonl`
-- `sessions/`
-- sqlite state
-- memories, skills, rules
-
-**Pros**
-
-- Minimal conceptual change from the current design.
-- Per-account auth isolation stays simple.
-
-**Cons**
-
-- Orca becomes a replication system for Codex state.
-- `history.jsonl` is mergeable, but `sessions/` and sqlite-backed files are much harder to reconcile safely.
-- Concurrent activity can easily cause stale-copy or overwrite bugs.
-- More code, more edge cases, weaker guarantees.
-
-**Verdict**
-
-Not recommended. This is the highest-complexity path for the weakest product result.
-
-### Option 2: Shared runtime home, per-account `auth.json`
-
-Keep a single shared runtime `CODEX_HOME` and store one `auth.json` per managed account. On switch, Orca copies the selected account's `auth.json` into the shared runtime home before launching or restarting Codex sessions.
-
-**Pros**
-
-- Cleanest mapping to the product intent.
-- `config.toml`, history, sessions, memories, skills, rules, and local state are naturally shared.
-- No state replication logic.
-- Cross-platform implementation is straightforward with normal file copy and rename.
-
-**Cons**
-
-- Does not support simultaneous different-account live sessions in the same runtime home.
-- Existing live sessions still likely need restart because Codex may read auth only at startup.
-
-**Verdict**
-
-Recommended.
-
-### Option 3: Wait for upstream Codex auth profiles
-
-If Codex eventually supports a true auth-profile model, Orca could delegate account isolation to Codex itself.
-
-**Pros**
-
-- Best long-term upstream integration.
-- Less Orca-specific state management.
-
-**Cons**
-
-- Not available today.
-- Does not solve Orca's user-facing problems now.
-
-**Verdict**
-
-Good future migration target, not a current solution.
-
-## Recommended Design
-
-### High-level model
-
-Introduce two separate concepts:
-
-1. **Shared runtime home**
-   The single `CODEX_HOME` used for all Codex launches inside Orca. For this design, the canonical shared runtime home is `~/.codex`.
-
-2. **Per-account auth store**
-   Orca-managed storage that keeps one `auth.json` per account.
-
-3. **Codex runtime-home owner**
-   A dedicated main-process component that prepares active Codex runtime state before any Codex subprocess, rate-limit fetch, or login flow touches it.
-
-At runtime:
-
-- Orca picks the selected managed account.
-- The runtime-home owner copies that account's `auth.json` into `~/.codex/auth.json`.
-- All Codex entry points consume the runtime-home owner's resolved home path instead of reasoning about Codex paths independently.
-- Orca launches Codex with `CODEX_HOME` pointing to `~/.codex`.
-
-### Shared vs per-account state
-
-**Shared runtime home**
-
-- `config.toml`
-- `history.jsonl`
-- `sessions/`
-- `memories/`
-- `skills/`
-- `rules/`
-- `shell_snapshots/`
-- `models_cache.json`
-- `logs_2.sqlite`
-- `state_5.sqlite`
-- `installation_id`
-- `version.json`
-- transient caches and temp dirs, unless we later discover they must be treated specially
-
-**Per-account storage**
-
-- `auth.json`
-- Orca account metadata already stored in Orca settings
-
-### Why this is the right split
-
-`auth.json` is the only file we explicitly know needs to vary by account. The rest of the files represent user environment, session continuity, and local Codex behavior. If those are split by account, the switcher does not feel seamless.
-
-## Detailed Design
-
-### Storage layout
-
-Recommended paths:
-
-- Shared runtime home:
-  - `~/.codex`
-- Per-account auth store:
-  - `app.getPath('userData')/codex-accounts/<id>/home/auth.json`
-
-The important part is the separation of concerns, not the exact path choice.
-
-### Ownership and API
-
-The design should introduce a dedicated main-process owner for runtime-home preparation. A representative API shape:
-
-```ts
-type PreparedCodexRuntime = {
-  homePath: string
-  activeAccountId: string | null
-}
-
-interface CodexRuntimeHomeService {
-  prepareForAccountSwitch(accountId: string | null): PreparedCodexRuntime
-  prepareForCodexLaunch(): PreparedCodexRuntime
-  prepareForRateLimitFetch(): PreparedCodexRuntime
-  prepareForLogin(accountId: string): { loginHomePath: string }
-}
-```
-
-Why: today path/runtime ownership is fragmented across `CodexAccountService`, PTY spawn env injection, rate-limit fetches, and usage scanning. A single owner prevents those code paths from drifting again.
-
-### Serialization contract
-
-Because `~/.codex/auth.json` is shared mutable state, the runtime-home owner must be the only component allowed to mutate active Codex auth. It must serialize these operations behind one coordination primitive:
-
-- `prepareForAccountSwitch`
-- `prepareForCodexLaunch`
-- `prepareForRateLimitFetch`
-- `prepareForLogin`
-- any future reauth or logout helpers
-
-Required contract:
-
-- account switch auth materialization is exclusive
-- launch and rate-limit preparation must either observe the auth state from before the switch or the fully committed auth state from after the switch
-- they must never observe an in-progress partial write
-- login preparation must not mutate the active runtime auth in place
-
-Why: without this contract, PTY launch, quota fetch, and auth swap can still race and intermittently bind work to the wrong account.
-
-### Account switch flow
-
-1. User selects a managed account.
-2. Orca validates that account's stored `auth.json`.
-3. The runtime-home owner writes the selected `auth.json` into `~/.codex/auth.json`.
-4. Orca refreshes Codex rate-limit state using the same prepared runtime home.
-5. Orca prompts restart for live Codex panes, marks them stale until restarted, and blocks further Codex execution from those panes.
-6. New or restarted Codex panes launch with:
-   - `CODEX_HOME=~/.codex`
-   - shared config/history/session state
-   - selected account auth
-
-Interaction states that must be explicit in product/UI copy:
-
-- **Switch in progress**: selection disabled while auth materialization and rate-limit refresh run.
-- **Switch complete, restart required**: existing live Codex panes are stale, must show a restart affordance, and must not be allowed to submit further Codex work until restarted.
-- **Switch failed**: active account remains unchanged and stale restart notices are not applied.
-- **Switch to system default**: Orca clears managed-account selection and restores the system-default auth snapshot into `~/.codex`.
-
-### System default source of truth
-
-This design treats “System default” as a first-class auth source, not as “whatever happens to be left in `~/.codex/auth.json`.”
-
-Rules:
-
-- On first startup of the new architecture, before any managed-account switch mutates `~/.codex/auth.json`, Orca captures a `system-default` auth snapshot from the current `~/.codex/auth.json` when present.
-- That snapshot is stored in Orca-owned storage separately from managed account auth blobs.
-- Switching to “System default” restores `~/.codex/auth.json` from that stored snapshot.
-- If the user changes external Codex auth outside Orca and wants Orca’s “System default” target to follow it, Orca should expose an explicit refresh/import action or perform refresh only at startup before any managed account takes ownership in the current app session.
-
-Why: without a defined snapshot-and-restore model, switching back to “System default” is nondeterministic and can leave the last managed account active or overwrite the user’s expected external Codex auth.
-
-### New account add flow
-
-1. Orca prepares a temporary login home that inherits the current shared config baseline but does not dirty the active runtime state on failure.
-2. Orca runs `codex login` against that temporary login home.
-3. Orca captures the resulting `auth.json`.
-4. Orca stores only that `auth.json` under the managed account's storage.
-5. Orca does not change the active runtime home until the user selects that account or explicitly makes it active on completion.
-
-Why: a failed or aborted login must not poison the currently active `~/.codex` runtime state.
-
-### Legacy managed-home migration
-
-Migration of existing managed-home history and sessions is required, not optional.
-
-Rules:
-
-- On first startup after the new architecture lands, Orca scans legacy managed homes for:
-  - `history.jsonl`
-  - `sessions/`
-- Orca imports legacy history into `~/.codex/history.jsonl` using append/merge semantics that avoid dropping existing shared-home history.
-- Orca imports legacy sessions into `~/.codex/sessions/` with an explicit collision policy:
-  - import non-conflicting legacy session files directly
-  - for conflicting session files, merge turns when Orca can prove the files represent the same logical session with append-only divergence
-  - if Orca cannot safely merge a conflicting session file, preserve both copies under deterministic names and emit a diagnostic record rather than silently dropping either side
-- Orca records migration completion so the import does not repeat on every startup.
-
-Why: shared history/session continuity is a core goal of the design. Leaving legacy managed-home data unresolved would make the upgrade look like history loss for users who previously used managed accounts.
-
-### Live session behavior
-
-The safe assumption is:
-
-- switching accounts affects new Codex launches
-- existing live Codex sessions should still restart
-- stale live Codex panes are blocked from further execution until restart completes
-
-If future validation shows Codex hot-reloads `auth.json`, Orca can relax this. The architecture should not rely on hot-reload behavior today.
-
-### Startup and recovery behavior
-
-The design must explicitly cover startup and error handling:
-
-- If `~/.codex` exists but has no `history.jsonl` or `sessions/`, Orca should launch cleanly and let Codex create them lazily.
-- If the selected managed account's stored `auth.json` is missing or corrupt, Orca should:
-  - log a recoverable warning,
-  - fall back to system-default semantics,
-  - clear or mark invalid the selected managed account,
-  - avoid leaving rate-limit UI bound to the wrong identity.
-- If a rate-limit refresh fails after account switch, Orca should keep the account switch result but show quota fetch failure separately rather than rolling back auth materialization implicitly.
-
-## Why `~/.codex` Is The Shared Home
-
-This document explicitly chooses `~/.codex` as the canonical shared runtime home.
-
-Reasons:
-
-- It matches the user's existing Codex mental model inside and outside Orca.
-- It avoids split-brain between Orca Codex usage and terminal Codex usage.
-- It matches what manual account switching already does today: logout/login mutates the same shared Codex state.
-
-Tradeoff:
-
-- Orca account switching will mutate the same Codex state used outside Orca.
-
-That is acceptable for this product direction. Orca is acting as an automated frontend for the user's existing Codex environment, not a separate Codex silo.
-
-## Migration Plan
-
-### Phase 1: Preserve the config sync patch
-
-Keep the existing `config.toml` sync patch as a tactical fix while the broader migration is in progress.
-
-### Phase 2: Introduce runtime-home owner
-
-- Add a dedicated main-process runtime-home owner/service.
-- Route PTY spawning, rate-limit fetches, and login preparation through it.
-- Make `~/.codex` the explicit resolved runtime home for those flows.
-
-### Phase 3: Move managed accounts to auth-only semantics
-
-- Update account add/reauth logic to persist only the account's `auth.json`.
-- Stop treating per-account homes as full runtime environments.
-
-### Phase 4: Account switch writes auth into shared runtime home
-
-- On select, materialize the chosen account's `auth.json` into `~/.codex`.
-- Keep the existing restart notice flow for live Codex panes.
-
-### Phase 5: Cleanup / compatibility
-
-- Run the one-time legacy managed-home migration into `~/.codex`.
-- Mark old full-home-per-account storage as legacy.
-- Remove code paths that assume managed homes are full `CODEX_HOME`s.
-
-## Risks
-
-### Concurrent mixed-account sessions
-
-This design assumes one selected active account at a time. If Orca ever needs simultaneous live sessions under different accounts, a single shared runtime home with one `auth.json` will not be sufficient.
-
-### Unknown Codex coupling
-
-We know `auth.json` is account-specific. We infer that most other files are environment/user-state and should be shared. If Codex later proves that some sqlite or cache files are also account-coupled, Orca may need to carve out a small additional per-account subset. That is still far simpler than syncing whole homes.
-
-### Mutating the shared runtime home
-
-This design intentionally updates `~/.codex/auth.json`. That means Orca and terminal Codex outside Orca share one Codex world. This is a deliberate product choice, not an accidental side effect.
-
-## Testing Strategy
-
-### Unit tests
-
-- account selection writes the selected `auth.json` into `~/.codex`
-- PTY spawn uses `~/.codex` instead of the managed account home
-- config/history/session paths resolve from `~/.codex`
-- invalid or unreadable account auth does not corrupt the shared runtime home
-- startup with missing shared runtime files is repaired gracefully
-- rate-limit fetches and PTY launches consume the same runtime-home owner output
-
-### Integration tests
-
-- add account A, launch Codex, verify `~/.codex` gets history
-- switch to account B, restart pane, verify history remains available
-- verify `config.toml` and permissions do not change across account switches
-- verify only `auth.json` differs across account switches
-
-### Manual verification
-
-1. Start a Codex session under account A and create visible history.
-2. Switch to account B.
-3. Restart the Codex pane.
-4. Verify the session uses account B for auth/rate limits.
-5. Verify history, sessions, config, memories, and skills remain available.
-
-## Open Questions
-
-- Do `logs_2.sqlite` and `state_5.sqlite` behave correctly when fully shared across account switches? This is the expected design, but should be validated during rollout.
-- How should Orca expose refresh of the stored `system-default` auth snapshot when the user logs into Codex outside Orca?
-
-## Recommendation
-
-Adopt **`~/.codex` as the shared runtime `CODEX_HOME`, plus per-account `auth.json` only**, and implement it through a dedicated runtime-home owner in the main process.
-
-This is the simplest design that:
-
-- matches the intended account-switching UX,
-- avoids fragile replication logic,
-- works cross-platform,
-- and leaves room to adopt upstream Codex auth-profile support later if it becomes available.
diff --git a/docs/create-from-start-field.md b/docs/create-from-start-field.md
deleted file mode 100644
index 7655d6d9048..00000000000
--- a/docs/create-from-start-field.md
+++ /dev/null
@@ -1,355 +0,0 @@
-# Engineering Spec: "Start from" field in Create Workspace
-
-## Summary
-
-Add a **"Start from"** field to the Create Workspace composer that lets the user pick a **branch or PR** as the basis for the new workspace. The picker is scoped to the selected repo; changing repo resets the field. This replaces no existing behavior: "Start from" defaults to the repo's **effective base ref** (`repo.worktreeBaseRef` when configured, otherwise the repo's detected default branch), so the current quick-create flow is unchanged.
-
-This spec targets the shared composer flow, not just the modal wrapper. The quick-create modal and the full-page composer both consume `NewWorkspaceComposerCard` + `useComposerState`, so the new field/state should live there unless a piece is truly modal-only.
-
-**Issues are out of scope for this picker.** Picking an issue does not change the base ref — it only sets `linkedIssue`, which the existing Link-work-item UI (`useComposerState.ts:256–260`) already handles. Putting Issues in a picker called "Start from" creates a second entry point into the same state and misleads the user. Users who want to link an issue use the existing Link UI.
-
-## User-visible behavior
-
-| Selection | Branch created from | Workspace metadata |
-|---|---|---|
-| Branch (default or other) | selected branch/ref | — |
-| PR | PR's same-repo head branch/ref | `linkedPR = #N` |
-
-Important: Orca's create flow always creates a new worktree branch derived from the workspace name. "Start from PR" therefore means **branch from the PR head**, not "check out the PR branch directly".
-
-**Scope for v1:** local repos support both picker tabs. Remote SSH repos support **Branches** only in this spec; PR start points stay disabled there until GitHub lookup can run without assuming a local `cwd`.
-
-**PR scope for v1:** only PRs whose head branch lives in the selected repo are selectable. Fork PRs render disabled with copy like *"Fork PRs aren't supported yet in Start from"* because the current create flow cannot safely resolve a fork head from `headRefName` alone.
-
-**Repo ↔ Start from contradiction:** the picker is repo-scoped. Changing `repoId` clears the prior selection and resets the field to the new repo's effective base ref. The field renders the reset inline (e.g. trigger reads *"Default branch — was PR #8778"*) instead of a fading toast, so the state is recoverable visually and not missed by users focused on another field.
-
-**Naming:** when the picker selects a PR and the Name field is still auto-managed (matches `lastAutoNameRef.current`, including empty), apply the existing auto-name behavior from `getLinkedWorkItemSuggestedName()` to the actual `name` state. Once the user edits the name, subsequent PR selections leave `name` alone. This matches the existing Link-UI rule exactly — one code path, not two.
-
-**Linked-work-item interaction:** the picker writes into the *same* `linkedWorkItem`/`linkedPR` state that the Link UI owns. A PR selection is a `linkedWorkItem` assignment. Switching back to a branch leaves `linkedWorkItem` alone: the user changed the *start ref*, not the *link*. If the user wants to remove the link, they use the Link UI. No source-tagging, no parallel state, no "whose selection was it" bookkeeping.
-
----
-
-## Data model
-
-**No new shared type.** The "Start from" picker is a UI affordance that writes into fields the system already has:
-
-- `CreateWorktreeArgs.baseBranch` (existing, `src/shared/types.ts:461`) — carries the resolved git ref the new worktree branches from.
-- `WorktreeMeta.linkedPR` (existing, `src/shared/types.ts:56`) — set on PR selection. `useComposerState` already owns `linkedWorkItem` + `linkedPR` state and already writes it via `applyWorktreeMeta` post-create (`useComposerState.ts:880`).
-
-Every picker selection reduces to one of:
-
-| Picker selection | `baseBranch` passed to create | Linked metadata |
-|---|---|---|
-| Branch, local row | short branch name (e.g. `main`) | — |
-| Branch, remote-tracking row | remote-qualified form from the row's full refname (e.g. `origin/main`, `upstream/feat-x`) | — |
-| PR #N (same-repo head) | `<remote>/<headRefName>` after main-process `git fetch` of that ref (see PR head resolution) | `linkedPR = N` |
-
-Why full-ref precision without a new type: local and remote-tracking refs are not interchangeable. The picker emits the right short form to `baseBranch` — remote-tracking rows pass the `<remote>/<name>` form so the new branch tracks the remote ref instead of creating a detached HEAD. Classification at the picker must use the row's underlying full refname (`refs/heads/…` vs `refs/remotes/<remote>/…`), never prefix-matching a short name (a local branch literally named `origin/foo` is legal). The remote name comes from the row's full refname, not a hardcoded `origin` — repos can have `upstream` or other remotes.
-
-**Scope note on main-side remote derivation.** `createRemoteWorktree` (`worktree-remote.ts:96`) and `createLocalWorktree` (`worktree-remote.ts:243`) currently derive the remote as `baseBranch.includes('/') ? baseBranch.split('/')[0] : 'origin'`. For picker selections this is fine — remote-tracking rows and PR refs always contain a slash, so the derived remote is correct. Branch-picker rows without a slash are local heads, and the `'origin'` fallback is unused. Non-picker code paths that pass slashless remote refs still hit the `origin` hardcode; fixing that is *out of scope* for this spec. The `resolvePrBase` resolver (below) must derive the push remote explicitly, since the PR head may live on `upstream` or another remote configured at the repo level.
-
-**PR head resolution lives in main, not the renderer.** `gh pr list` returns `headRefName` as a short branch name that typically does not exist locally. Passing the bare `headRefName` as `baseBranch` will fail `git worktree add` in the common case. Git-ref resolution (`git fetch`, `git rev-parse`) belongs in main; the renderer does not shell out.
-
-New IPC: `worktrees:resolvePrBase`
-```ts
-window.api.worktrees.resolvePrBase({
-  repoId,
-  prNumber,
-  // Optional cache hints from the renderer's existing PR cache.
-  // When both are present, main skips the `gh pr view` lookup.
-  headRefName?: string,
-  isCrossRepository?: boolean,
-}) => Promise<{ baseBranch: string } | { error: string }>
-```
-On PR selection, the picker calls this resolver. Main:
-1. If both hints are present, skip GitHub lookup. Otherwise resolve the PR via the existing GitHub client to obtain `headRefName` + `isCrossRepository`.
-2. Reject fork PRs (`isCrossRepository === true`) with `"Fork PRs aren't supported yet"`.
-3. Runs `git fetch <remote> <headRefName>` against the repo's default remote (see Default remote selection below).
-4. Verifies the fetched ref with `git rev-parse --verify <remote>/<headRefName>`.
-5. Returns `{ baseBranch: "<remote>/<headRefName>" }` or a user-readable error.
-
-Pre-submit resolution surfaces "branch deleted on remote" in the picker, not at create time. The resolved string is the one passed to `CreateWorktreeArgs.baseBranch` — no special `kind: 'pr'` at the IPC boundary.
-
-**Concurrency / stale resolves.** A PR selection commits to `baseBranch` only after `resolvePrBase` succeeds. If the user selects a second PR before the first resolves, the first resolve's result is discarded (last-click-wins). Track this in the picker with a per-click token or `AbortController`; do not simply `await` sequentially, or late resolves will clobber newer selections.
-
-**Submit while resolve pending.** If the user triggers create while a `resolvePrBase` is still in flight, the submit path waits for the pending resolve (or fails fast with a visible "Resolving PR head…" state). It must not submit with an unresolved `baseBranch` and it must not submit with the *previous* selection's `baseBranch`.
-
-**Default remote selection.** "Default remote" is not "the one named `origin`." Resolve inside `resolvePrBase` in this order: (1) the remote configured on the repo's default branch (`git config branch.<default>.remote`); (2) `origin` if present; (3) the single remote if the repo has exactly one; (4) error otherwise (ask the user to configure). Centralize this in a helper in `src/main/git/repo.ts` rather than re-deriving per call site.
-
-**WSL repos.** The existing main-process helpers route through `isWslPath` / `parseWslPath` (`src/main/ipc/worktree-remote.ts:19`). `worktrees:resolvePrBase` must use the same routing for its `git fetch` / `rev-parse` calls, not bare `gitExecFileAsync` on a raw path, or WSL repos will fail to resolve.
-
-**Draft restore.** `newWorkspaceDraft.baseBranch` is persisted. On composer mount a restored `baseBranch` may reference a ref that no longer exists (PR closed, branch deleted since yesterday). Current main-process behavior will silently fall back to `worktreeBaseRef` / default branch rather than erroring — this is the same v1 hole tracked in Follow-up chores. Optional v1 nicety: run a cheap `rev-parse --verify` on mount (local repos only); if the ref is gone, clear `baseBranch` in the draft and show a one-line hint in the field ("Previous start ref no longer exists"). Don't block the user.
-
-**Accessibility.** The popover must support keyboard-only operation: arrow keys within a tab, Tab / Shift+Tab between tabs, Enter to commit, Esc to close without committing. Reuse the existing Link-UI popover's keyboard hook rather than re-implementing.
-
-### `GitHubWorkItem` additions (`src/shared/types.ts:390`)
-
-One new field is needed. `GitHubWorkItem` already carries `branchName?: string` (`src/shared/types.ts:400`), which `src/main/github/client.ts:636` populates from `headRefName` for PR rows. **Reuse `branchName` — do not introduce a second field meaning "PR head branch".** Throughout this spec, reads of "the PR's head branch" on `GitHubWorkItem` refer to `branchName`.
-
-```ts
-isCrossRepository?: boolean // true = fork PR; disabled in picker
-```
-
-**Verification:** `gh pr list` in `src/main/github/client.ts:280,401,610` currently requests `number,title,state,url,labels,updatedAt,author,isDraft,headRefName,baseRefName`. Add `headRepositoryOwner` to the field list at all three sites; compute `isCrossRepository` in the mapper as `item.headRepositoryOwner?.login !== <selected repo owner>`. Mapper change lands at `src/main/github/client.ts:636`, where `branchName` is already set — this is the one place fork detection is computed.
-
-### Draft persistence (`src/renderer/src/store/slices/ui.ts:64`)
-
-Extend `newWorkspaceDraft` with `baseBranch?: string`. Absence means "use the repo's effective base ref" — no `null`-plus-conversion step, shape matches `CreateWorktreeArgs.baseBranch`. `linkedPR` / `linkedWorkItem` are already persisted, so PR selections round-trip without further schema changes.
-
-No new `worktrees:create` wire change. The existing contract already carries `baseBranch`.
-
----
-
-## Main-process changes
-
-### IPC handlers
-
-- `src/main/ipc/worktrees.ts` — wire the new `worktrees:resolvePrBase` handler (signature + algorithm defined in §Data model). Handler module may live adjacent if it grows.
-- `src/main/ipc/worktree-remote.ts` — **no changes**. The existing `||` fallback chain is preserved as-is. The picker emits validated refs (branch rows from `searchBaseRefs` exist; PR refs are `git fetch`ed + `rev-parse`d inside `resolvePrBase` before the picker commits them to `baseBranch`), so in practice the picker never hands an unresolvable ref to create.
-
-### Base-ref resolution
-
-No main-process branching on "kind". The renderer collapses every picker selection into a `baseBranch` string (and, for PR selections, `linkedPR` metadata). The existing `args.baseBranch || repo.worktreeBaseRef || <detected default>` chain in `createLocalWorktree` / `createRemoteWorktree` is unchanged.
-
-Known limitation (acceptable for v1): if a picker-selected ref is deleted between selection and submit, create silently falls back instead of erroring. In practice this requires the remote branch to disappear in the seconds between picker commit and Create click — vanishingly rare. Tightening this into strict-when-explicit behavior is tracked as a follow-up chore (see `Follow-up chores`).
-
-### Metadata persistence
-
-PR selections set `linkedPR` in the existing composer state. The existing post-create `applyWorktreeMeta` call (`useComposerState.ts:880`) already writes it — no new write path.
-
-If metadata persistence fails after the git worktree already exists, log and continue. The worktree is still valid even if the link badge is missing.
-
-### GitHub data scope
-
-- local repos, PRs: existing `gh:listWorkItems` (cached — see caching rules below)
-- local repos, direct number lookup: existing `gh:workItem` (cached)
-- branches: existing `repos:searchBaseRefs`
-
-No new GitHub IPC is required for local repos in v1.
-
-### Create-time validation
-
-Unchanged. The picker pre-validates refs (branches via `searchBaseRefs` results, PR heads via `resolvePrBase`'s fetch + `rev-parse`), so most bad paths are caught before submit. The one remaining hole — ref deleted between commit and create — falls through to today's silent fallback; see `Follow-up chores`.
-
----
-
-## Caching rules (must read)
-
-PR searches and number lookups hit the user's `gh` CLI quota. The picker **must** ride on the existing SWR caches in `src/renderer/src/store/slices/github.ts`; it must not introduce a parallel fetch path.
-
-**Required behavior:**
-
-- **Always call `fetchWorkItems(repoPath, limit, query, options?)`** — never `window.api.gh.listWorkItems(...)` directly. The store already deduplicates in-flight requests (`inflightWorkItemsRequests`) and applies `WORK_ITEMS_CACHE_TTL`. Direct calls bypass both.
-- **Use the prefetch path to warm shared keys.** The cache key is `(repoPath, limit, query)`. The picker's query **must** match the prefetch query exactly or cache hits won't share. Use:
-  - Prefetch on composer mount (local repo): `prefetchWorkItems(repoPath, 36, 'is:pr is:open')`.
-  - Picker PR tab default list: `fetchWorkItems(repoPath, 36, 'is:pr is:open')`.
-  - Picker PR tab user query: `fetchWorkItems(repoPath, 36, \`is:pr is:open \${userQuery}\`)` — queries debounced ~150ms (matches existing Link-UI debounce) so rapid typing collapses to one fetch.
-- **Render cached results synchronously while revalidating.** Use `getCachedWorkItems(...)` for the first paint so opening the popover is instant and costs zero API calls when the cache is fresh.
-- **Direct-number lookup (`#123`, full URL) uses `gh:workItem` via its cache.** Same SWR contract; the picker reads `prCache`/`issueCache` synchronously first.
-- **Do not prefetch on every keystroke.** Only prefetch (a) on composer mount and (b) on popover open. Search queries go through the debounced `fetchWorkItems`, which dedupes against the cache anyway.
-- **PR resolver (`worktrees:resolvePrBase`) must reuse the renderer-side PR cache when available.** The renderer passes the already-known `headRefName` and `isCrossRepository` to the resolver (as an optional hint); main skips the `gh pr view` call when the hint is present. Only the `git fetch` + `git rev-parse` steps always run, since remote refs can change.
-- **Branch search (`repos:searchBaseRefs`) is git-local and cheap**; it does not count against GitHub quota, so fetch-on-demand when the Branches tab becomes active is acceptable. Debounce ~150ms to avoid redundant `git for-each-ref` invocations on large repos.
-
-**Do not** call `prefetchWorkItems(repoPath, 'is:open')` — the second argument is `limit`, not `query`, and this would silently prefetch a different cache key than the picker reads.
-
-**Audit existing prefetch callers.** `ui.ts:195` already calls `prefetchWorkItems(repo.path, 36, presetToQuery(preset))`. Confirm during implementation that at least one active task preset produces `'is:pr is:open'` (the exact string the picker queries) so the sidebar prefetch and the picker fetch share a cache key. If no preset matches exactly, add a dedicated mount-time prefetch in the composer and do not rely on the sidebar's opportunistic warming.
-
-**Cache invalidation.** The existing SWR caches are keyed by `(repoPath, limit, query)` and expire via `WORK_ITEMS_CACHE_TTL`. The picker does **not** call `force: true` on every open — that defeats the cache. It only forces a refresh on explicit user action (e.g. a "Refresh" control in the popover, if added later). Stale-within-TTL is acceptable for picker use.
-
----
-
-## Renderer changes
-
-### 1. New components
-
-- `src/renderer/src/components/new-workspace/StartFromField.tsx`
-  - popover trigger (pill + title + chevron)
-- `src/renderer/src/components/new-workspace/StartFromPicker.tsx`
-  - tabs: **Branches · Pull requests**
-  - search input debounced ~150ms
-  - PR tab calls `worktrees:resolvePrBase` on selection; shows an inline error on fetch/resolve failure *before* the user submits
-  - on selection, calls back into `useComposerState` with `{ baseBranch, linkedWorkItem? }` — no new shared type
-
-### 2. Popover state coverage
-
-Each tab must render these states explicitly:
-
-| Flow | Loading | Empty | Error | Success |
-|---|---|---|---|---|
-| Branches | skeleton rows | "No branches match" | inline error | list |
-| Pull requests | skeleton rows (only if no cached data) | "No open PRs" | "gh not available — Branches tab still works" | list (cached first, revalidated in background) |
-
-Cached results must paint immediately; the loading state appears only when nothing is cached. This makes the common case a zero-API-cost open.
-
-### 3. Integrate into shared composer state
-
-Add `baseBranch?: string` state in `src/renderer/src/hooks/useComposerState.ts` (reusing the existing `linkedWorkItem` / `linkedPR` state for PR selections — don't introduce parallel `startFrom` state). The hook already owns:
-
-- repo selection
-- `linkedWorkItem` + `linkedPR` (see `useComposerState.ts:209,223`)
-- auto-name behavior via `lastAutoNameRef` (`useComposerState.ts:262`)
-- full-page draft persistence
-- submit / submitQuick, with post-create `applyWorktreeMeta` already writing linked metadata (`useComposerState.ts:880`)
-
-The modal wrapper should stay thin. `NewWorkspaceComposerModal.tsx` continues to pass through `cardProps` to `NewWorkspaceComposerCard`, while the card gets new props for rendering the field.
-
-### 4. Picker data sources
-
-- Branches tab:
-  - `window.api.repos.searchBaseRefs({ repoId, query })`
-- PRs tab:
-  - `fetchWorkItems(repoPath, 36, 'is:pr is:open')` for the default list
-  - `fetchWorkItems(repoPath, 36, \`is:pr is:open \${userQuery}\`)` for typed queries
-  - `getCachedWorkItems(...)` for first paint
-
-Use the selected repo object already derived in `useComposerState`; do not introduce a separate `reposById` dependency unless the store actually gains one.
-
-Filter PR results to same-repo heads only (`!isCrossRepository`). Fork PRs render disabled with explanatory copy, not silently filtered, so the user understands why their PR isn't selectable.
-
-Normalize PR queries before dispatching GitHub lookups. Route by shape:
-
-- bare number (`123`), `#123`, or a full GitHub PR URL for the selected repo → strip to the number and dispatch `gh:workItem` (reads `prCache` first per §Caching rules). `getWorkItem` returns `type: 'pr' | 'issue'`; when `type !== 'pr'`, treat as no-match in the PR tab (number collides with an issue).
-- full GitHub PR URL for a *different* repo → silently fall back to free-text search. Do not hard-block; users paste URLs because they want the content.
-- anything else → pass through as a free-text query to `fetchWorkItems(..., \`is:pr is:open \${query}\`)`.
-
-### 5. Repo-change reset
-
-On repo change:
-
-- reset `baseBranch` to `undefined` (so the field shows the new repo's effective base ref as placeholder)
-- clear any transient picker state tied to the previous repo
-- the field's trigger copy shows the reset inline (e.g. *"Default branch — was PR #N"*) when a selection was cleared
-
-The existing `handleRepoChange` callback (`useComposerState.ts:819`) already clears `linkedIssue` / `linkedPR` / `linkedWorkItem` inline; extend it to also clear `baseBranch`. One callback, not a new effect.
-
-### 6. Naming behavior
-
-When the picker selects a PR, it sets the existing `linkedWorkItem` state. The composer's existing auto-name path (which reacts to `linkedWorkItem` via `getLinkedWorkItemSuggestedName` and `lastAutoNameRef`) will update `name` iff `name === '' || name === lastAutoNameRef.current` — i.e. the name is still auto-managed. Once the user edits the name, subsequent selections leave it alone. This is the existing Link-UI rule; no new naming code.
-
-### 7. Submission
-
-Thread `baseBranch` through:
-
-- `useComposerState` submit paths (already constructs `CreateWorktreeArgs` — just add the field)
-- persisted `newWorkspaceDraft`
-- store `createWorktree(...)` → preload `window.api.worktrees.create(...)` → main `CreateWorktreeArgs` (field already exists)
-
-`linkedPR` needs no new wiring — the post-create `applyWorktreeMeta` call already writes it.
-
-### 8. Prefetch
-
-On composer mount (local repo only), warm the PR cache:
-
-```ts
-prefetchWorkItems(repoPath, 36, 'is:pr is:open')
-```
-
-Do **not** call `prefetchWorkItems(repoPath, 'is:open')`; the second argument is `limit`, not `query`. Do **not** use a query string that differs from what the picker will fetch — mismatched keys produce a double fetch.
-
-Branch results stay fetch-on-demand when the Branches tab becomes active.
-
----
-
-## Shortcut discoverability
-
-Out of scope for this spec. A follow-up can add a split "+" button with `CmdOrCtrl+Shift+N` for a more explicit "Create from…" entry point.
-
-## Explicitly out of scope
-
-- **Issues tab.** Issues do not change the start ref; use the existing Link UI to link an issue.
-- **Checking out an existing branch without `-b`.** Orca's create flow always derives a new branch from the workspace name; "Start from PR" means branch from the PR head, not open the PR branch directly.
-- **Fork PR start points.** Disabled in v1.
-- **SSH PR start points.** Disabled in v1.
-
----
-
-## Edge cases
-
-| Case | Behavior |
-|---|---|
-| User picks PR, then renames Name manually | Manual name wins (existing `lastAutoNameRef` rule) |
-| User picks PR, then picks a different PR without editing name | Name updates to the new PR's suggestion |
-| User picks PR from a fork | picker disables it in v1; no create attempt |
-| PR head branch has since been deleted at picker open | picker surfaces resolve error before submit; create never attempted |
-| PR head fetch fails (network/auth) | picker surfaces the fetch error; selection does not commit |
-| User picks branch, switches repo, switches back | no cross-repo picker state is preserved |
-| Offline / `gh` CLI missing | PRs tab shows error state; Branches tab still works |
-| Remote repo over SSH | only Branches tab is enabled in v1; PRs tab disabled with explanatory copy |
-| Repo has `worktreeBaseRef` set to non-default branch | reset behavior uses that configured base ref |
-| User pastes `#123` or a full GitHub PR URL | picker normalizes to the work item number and uses `gh:workItem` cache |
-| Pasted number resolves to an issue, not a PR, in the PR tab | treated as no-match; user sees empty-state copy |
-| User pastes a PR URL for a different repo | picker silently falls back to free-text search |
-| Selected ref (branch or PR head) disappears between picker commit and create | falls through to today's `worktreeBaseRef` / default-branch fallback (acceptable v1 hole; tracked in Follow-up chores) |
-| Restored draft references a ref that no longer exists | same silent fallback at create; optional v1 nicety clears the draft field with an inline hint on mount |
-| Popover opened with fresh cache | renders instantly from `getCachedWorkItems`; zero API calls |
-| User selects PR, then quickly selects a different PR before first resolve returns | last-click wins; stale resolve is discarded (AbortController / token) |
-| User hits Create while `resolvePrBase` is still pending | submit waits for the in-flight resolve; never submits with a stale `baseBranch` |
-| User rapidly toggles between Branches and PRs tabs mid-fetch | in-flight search requests for the prior tab are aborted; stale rows never render |
-
----
-
-## Test plan
-
-- **Unit / renderer**
-  - `StartFromField` renders the correct pill for each selection kind
-  - repo change resets `baseBranch` and the field shows the reset inline
-  - full-page draft persistence round-trips `baseBranch` (and existing linked-work-item fields)
-  - PR selection updates the actual `name` state only while it remains auto-managed (`name === '' || name === lastAutoNameRef.current`)
-  - PR selection mirrors into linked-work-item state; switching back to branch does **not** clear the link
-  - SSH repos disable PR tab
-  - cross-repo PRs are disabled with explanatory copy
-  - `#123` and full GitHub PR URLs normalize to number search
-  - pasted cross-repo URLs fall back to free-text search (no hard error)
-  - picker writes short name for local branch rows, `<remote>/<name>` for remote-tracking rows
-  - PR selection calls `worktrees:resolvePrBase` and threads the resolved ref into `baseBranch`
-- **Caching**
-  - opening the PR tab with a fresh cache triggers **zero** `window.api.gh.listWorkItems` calls (assert via spy)
-  - prefetch on composer mount and picker default fetch share the same cache key (`(repoPath, 36, 'is:pr is:open')`)
-  - rapid typing in the PR search debounces to a single fetch
-  - direct-number lookup (`#123`) reads `prCache`/`issueCache` synchronously before hitting `gh:workItem`
-  - `worktrees:resolvePrBase` skips `gh pr view` when the renderer passes a cached `headRefName` hint
-  - rapid re-selection aborts prior `resolvePrBase`; only the latest selection's result commits
-  - submit while `resolvePrBase` is pending waits for it; never submits a stale `baseBranch`
-- **Main-process**
-  - `worktrees:resolvePrBase` fetches via the repo's default remote (not hardcoded `origin`), returns resolved ref on success
-  - `worktrees:resolvePrBase` returns a user-readable error when the remote branch is missing or fetch fails
-  - `worktrees:resolvePrBase` rejects fork PRs
-  - `isCrossRepository` is populated on `GitHubWorkItem` PR rows from `headRepositoryOwner`
-- **Manual**
-  - quick create without touching the field behaves exactly as today
-  - create from same-repo PR creates a new branch from the PR head and shows the PR badge
-  - SSH repo shows branch start points only
-  - changing repo mid-flow resets the field and shows the inline reset copy
-  - opening the picker a second time within the cache TTL makes zero network calls
-
----
-
-## Rollout
-
-Single PR. No feature flag. The change is additive and backward-compatible — `baseBranch` is already optional on `CreateWorktreeArgs`, and `linkedPR` metadata is already written by existing code.
-
-## Files touched
-
-```text
-src/shared/types.ts                                                  (add isCrossRepository to GitHubWorkItem; branchName already carries PR head)
-src/main/github/client.ts                                            (add headRepositoryOwner to gh pr list field set; populate isCrossRepository)
-src/main/ipc/worktrees.ts                                            (new worktrees:resolvePrBase handler)
-src/main/git/repo.ts                                                 (default-remote helper used by resolvePrBase)
-src/preload/index.ts                                                 (invoke worktrees:resolvePrBase)
-src/preload/api-types.d.ts                                           (type worktrees.resolvePrBase)
-src/renderer/src/hooks/useComposerState.ts                           (baseBranch state + repo-change reset)
-src/renderer/src/components/NewWorkspaceComposerCard.tsx             (render the field)
-src/renderer/src/components/new-workspace/StartFromField.tsx         (new: pill trigger)
-src/renderer/src/components/new-workspace/StartFromPicker.tsx        (new: tabs + picker; SWR via fetchWorkItems/getCachedWorkItems)
-src/renderer/src/store/slices/ui.ts                                  (baseBranch in newWorkspaceDraft)
-src/renderer/src/lib/new-workspace.ts                                (if a small display helper is needed)
-```
-
-Estimated effort: ~1.5 engineering days — new `worktrees:resolvePrBase` IPC, `isCrossRepository` plumbing through the `gh` client and its mappers, picker + cancellation, URL normalization, prefetch key alignment, and renderer + main tests. Fully additive; no behavior change for existing flows.
-
-## Follow-up chores
-
-File these as separate issues at ship time, not in this PR:
-
-- **Strict-when-explicit base-ref validation.** Today `createLocalWorktree` / `createRemoteWorktree` silently fall back when an explicit `args.baseBranch` is unresolvable. The Start-from picker avoids this in practice by pre-validating, but a ref deleted between selection and submit still falls through. Replace the `||` chain with strict-when-explicit / fallback-when-implicit; add `SshGitProvider.verifyRef` for the remote path. Standalone refactor, own test coverage, affects all callers of `CreateWorktreeArgs.baseBranch`.
-- **Main-side default-remote derivation.** `createLocalWorktree` / `createRemoteWorktree` derive remote as `origin` when `baseBranch` lacks a slash. Centralize default-remote resolution (push remote of default branch → `origin` → single remote) and share with `resolvePrBase`.
diff --git a/docs/debug/mobile-fit-debug-status.md b/docs/debug/mobile-fit-debug-status.md
deleted file mode 100644
index 8bd9518aa1c..00000000000
--- a/docs/debug/mobile-fit-debug-status.md
+++ /dev/null
@@ -1,203 +0,0 @@
-# Mobile Phone-Fit Debug Status
-
-## Architecture Overview
-
-```
-Mobile Client                    Server (orca-runtime)              Desktop Renderer
-─────────────                    ────────────────────              ────────────────
-subscribeToTerminal(handle)  →   terminal.subscribe handler    →   IPC: terminalFitOverrideChanged
-  sends { client, viewport }     calls handleMobileSubscribe()     setFitOverride() → banner render
-                                 resizes PTY, sets override
-                                 serializes scrollback
-                              ←  scrollback { cols, rows,
-                                   serialized, displayMode }
-
-switchTab(handle)            →   terminal.unsubscribe (old)
-  unsub old, subscribe new       handleMobileUnsubscribe()
-                                 starts 300ms restore timer
-                             →   terminal.subscribe (new)
-                                 handleMobileSubscribe()
-                                 cancels timer, inline-restores old
-                                 resizes new PTY
-
-toggleDisplayMode(handle)    →   terminal.setDisplayMode
-                                 applyMobileDisplayMode()
-                             ←   resized event on stream
-```
-
-## Key Data Structures (Server)
-
-- `mobileSubscribers: Map<ptyId, { clientId, viewport, wasResizedToPhone, previousCols, previousRows }>`
-- `pendingRestoreTimers: Map<ptyId, { timer, clientId }>` (changed from clientId-keyed to ptyId-keyed)
-- `terminalFitOverrides: Map<ptyId, { mode, cols, rows, previousCols, previousRows, clientId }>`
-- `mobileDisplayModes: Map<ptyId, 'auto' | 'phone' | 'desktop'>`
-
-## Key Data Structures (Mobile Client)
-
-- `viewportRef: { cols, rows } | null` — measured once from xterm, passed with every subscribe
-- `viewportMeasuredRef: boolean` — true after first successful measurement
-- `terminalUnsubsRef: Map<handle, unsub()>` — active subscription cleanup closures
-- `initializedHandlesRef: Set<handle>` — tracks which terminals have been init'd (prevents double-init)
-- `subscribeSeqRef: Map<handle, number>` — monotonic counter to ignore stale scrollback
-
----
-
-## Bug 1: pendingRestoreTimers lost when 2 unsubscribes happen back-to-back
-
-**Status: FIXED (verification inconclusive — may need more testing)**
-
-**Root cause**: `pendingRestoreTimers` was keyed by `clientId` (one slot per device). When two terminals were unsubscribed in quick succession, the second timer overwrote the first.
-
-**Fix applied**:
-1. Changed `pendingRestoreTimers` from `Map<clientId, {timer, ptyId}>` to `Map<ptyId, {timer, clientId}>`
-2. `handleMobileSubscribe` cancels only the restore timer for the SAME ptyId (re-subscribe case). Other terminals' timers fire normally so their desktop banners clear.
-3. `handleMobileSubscribe` skips resize if PTY is already at target phone dims
-4. `handleCreateTerminal` now unsubscribes the old active terminal before setting the new one
-5. Restore happens via: 300ms timer (tab switch), or `onClientDisconnected` (full disconnect)
-
-**Bug 8 (banners accumulate on tab switch)**: The original Bug 1 fix was too aggressive — it cancelled ALL pending restore timers for the client, not just the one for the ptyId being re-subscribed. This prevented the 300ms restore timer from firing for the old terminal, so its desktop banner persisted. Fixed by narrowing the cancel scope to only the same ptyId.
-
-**Files**: `orca-runtime.ts`, `[worktreeId].tsx`
-
----
-
-## Bug 2: Intermittent blank terminal on tab switch
-
-**Status: FIX v2 APPLIED — needs testing**
-
-**Symptom**: After creating a new terminal tab, the original 2 terminals occasionally show blank. Leaving the worktree and re-entering fixes it.
-
-**Root cause**: The WebView loads xterm.js from CDN, which takes time. Messages sent before `web-ready` queue in `pendingMessagesRef` and flush when ready. The original `handleTerminalWebReady` would unsub+resub ALL initialized terminals (even inactive ones), creating stale server-side subscriptions and disrupting the data stream.
-
-**Fix v1 (FAILED)**: Gated `subscribeToTerminal` on webReady. This was too aggressive — it prevented subscriptions entirely, so no scrollback arrived, no init was queued, and the terminal stayed blank.
-
-**Fix v2 (current)**:
-1. `subscribeToTerminal` has NO webReady guard — subscriptions start immediately, init messages queue in `pendingMessagesRef`, and flush when `web-ready` fires
-2. `handleTerminalWebReady` distinguishes first load vs reload:
-   - **First load** (`wasAlreadyReady=false`): just marks webReady, triggers viewport measurement for active terminal. Pending messages flush after this callback returns → terminal renders.
-   - **Reload** (`wasAlreadyReady=true`): unsubscribes and resubscribes to get fresh scrollback (old xterm buffer is gone). Only resubscribes if active.
-3. `setTerminalWebViewRef` simplified to just store the ref (no subscription logic)
-
-**Flow (first load)**:
-1. `fetchTerminals` → `subscribeToTerminal(active)` → stream starts
-2. Scrollback arrives → `init()` queued in pendingMessages (WebView not ready yet)
-3. WebView loads xterm from CDN → `web-ready` fires
-4. `handleTerminalWebReady`: marks webReady, triggers viewport measurement (async)
-5. `flushPendingMessages()`: sends queued init → terminal renders
-6. Viewport measured → resubscribe with dims → server phone-fits → reinit with phone dims
-
----
-
-## Bug 5: Desktop banner not showing for initial split pane after creating new tab
-
-**Status: FIXED (verified via CDP + e2e testing)**
-
-**Root cause**: The bug was caused by the inline restore mechanism in `handleMobileSubscribe`. When mobile switched tabs, the server would restore the previous terminal to desktop dims (sending `desktop-fit` IPC), which cleared the override from `overridesByPtyId`. After the next subscribe, the override was re-set via `mobile-fit` IPC, but the timing was tight and the banner could flicker or fail to appear.
-
-**Fix**: Removed inline restore from `handleMobileSubscribe` (Bug 1 fix). PTYs now stay at phone dims when the mobile client switches tabs. Overrides persist in `overridesByPtyId` until the mobile client disconnects. This means ALL terminals the mobile client has subscribed to show the banner — which is correct since the mobile client "owns" those terminals.
-
-**Verification**: E2e testing via CDP (desktop renderer) and agent-device (mobile) confirmed:
-- `setFitOverride()` is called correctly via IPC
-- `onOverrideChange` fires and triggers re-renders
-- `getFitOverrideForPane()` finds overrides when `ptyIdByPaneId` bindings exist
-- Banners show correctly for all terminals (1, 2, and 3 tabs) including after creating new tabs
-- The earlier diagnostic showed HMR clearing module-level maps was a test artifact, not a production issue
-
----
-
-## Bug 7: Terminals disappear ("0 terminals") during rapid tab switching
-
-**Status: FIXED (verified via e2e testing)**
-
-**Symptom**: During rapid tab switching (3+ toggles in quick succession), all terminals disappear from the mobile UI. The terminal list shows "0 terminals". Leaving the worktree and re-entering fixes it.
-
-**Root cause**: The periodic `fetchTerminals()` (every 2s) calls with `allowEmptyLoaded: true`. The server can transiently return an empty terminal list during rapid operations. The old code's subscription cleanup loop (`liveHandles` check) ran before the empty guard, unsubscribing all terminals, which then made the empty guard's `terminalUnsubsRef.current.size > 0` check fail.
-
-**Fix applied**:
-1. Added `lastKnownTerminalCountRef` to track the previous non-zero terminal count
-2. When the server returns 0 terminals but `lastKnownTerminalCountRef > 0`, skip the FIRST empty response (set ref to 0 and return early)
-3. On the NEXT fetch, if still empty, `lastKnownTerminalCountRef` is 0, so the guard doesn't trigger and terminals are cleared normally
-4. This gives a ~2s grace period (one polling interval) to filter out transient empty responses
-5. The guard runs BEFORE the subscription cleanup loop, preventing premature unsubscription
-
-**Verification**: Rapid tab switching (8 cycles across 3 terminals in ~1.6s) with 20s wait — terminals survived. Previous code cleared to "0 terminals" within 18s.
-
-**Files**: `[worktreeId].tsx`
-
----
-
-## Bug 3: Viewport measurement chicken-and-egg
-
-**Status: SOLVED (workaround in place)**
-
-The first subscribe has `viewport=none`. After scrollback init, async measure viewport, resubscribe with dims. Takes 2-3 round-trips. Works reliably.
-
----
-
-## Bug 4: Desktop terminal focus doesn't follow mobile tab switching
-
-**Status: FIXED**
-
-`switchTab` now calls `terminal.focus` RPC.
-
----
-
-## Bug 6: Claude not launching on new workspace
-
-**Status: FIXED**
-
-**Root cause**: Mobile's `NewWorktreeModal` sends `startupCommand` (e.g. `'claude'`) in the `worktree.create` RPC call, but the Zod schema (`WorktreeCreate`) did not include `startupCommand`, so it was silently stripped during validation. The runtime's `createManagedWorktree` never received the startup command, so `args.startup` was always undefined and the activation IPC never included a startup payload. The left pane spawned a plain shell instead of the selected agent.
-
-**Fix applied**:
-1. Added `startupCommand: OptionalString` to the `WorktreeCreate` Zod schema in `src/main/runtime/rpc/methods/worktree.ts`
-2. RPC handler maps `params.startupCommand` → `{ command }` and passes to `runtime.createManagedWorktree()`
-3. Added `startup?: WorktreeStartupLaunch` to `createManagedWorktree`'s args type in `orca-runtime.ts`
-
-**Bug 6b: `waitForLeafPtyId` times out due to handle invalidation**
-
-When a leaf's ptyId changes from null to a real value, `syncWindowGraph` invalidates the old handle (deletes it from `this.handles`). The `waitForLeafPtyId` callback calls `resolveLeafForHandle(handle)` which returns null because the handle no longer exists. The wait never resolves.
-
-**Fix**: `waitForLeafPtyId` now captures the handle's `tabId` and `leafId` before the handle can be invalidated. The callback falls back to direct `this.leaves.get(getLeafKey(tabId, leafId))` lookup when the handle-based lookup fails.
-
-**Files**: `src/main/runtime/rpc/methods/worktree.ts`, `src/main/runtime/orca-runtime.ts`
-
----
-
-## Diagnostic Logging
-
-All logs prefixed with `[mobile-fit]`.
-
-### Server-side (main process stdout)
-| Location | What it logs |
-|----------|-------------|
-| `terminal.subscribe` handler | handle, ptyId, client type, viewport |
-| `handleMobileSubscribe` | ptyId, mode, viewport, skip reasons, resize details |
-| `handleMobileUnsubscribe` | ptyId, subscriber state, wasResized |
-| `applyMobileDisplayMode` | ptyId, mode, subscriber state |
-
-### Mobile client (React Native console)
-| Location | What it logs |
-|----------|-------------|
-| `subscribeToTerminal` | handle, seq, viewport, measured state |
-| scrollback handler | cols, rows, displayMode, hasSerialized, alreadyInit |
-| resized handler | cols, rows, displayMode, reason |
-| `switchTab` | prev/next handle, hasUnsub, hasRef |
-| `toggleDisplayMode` | handle, current mode, next mode |
-| `setTerminalWebViewRef` | handle, isActive, activeHandle |
-
-### Desktop renderer (DevTools console)
-| Location | What it logs |
-|----------|-------------|
-| `useIpcEvents.ts` | fitOverrideChanged IPC events received |
-| `TerminalPane.tsx` | onOverrideChange callbacks fired |
-
----
-
-## Priority Order
-
-1. ~~**Bug 2 (blank terminal)**~~ — **FIXED**. WebView readiness lifecycle corrected.
-2. ~~**Duplicate prompt lines**~~ — **FIXED**. Removed inline restore, added alreadyAtTarget skip.
-3. ~~**Bug 7 (0 terminals)**~~ — **FIXED**. Consecutive-empty guard with `lastKnownTerminalCountRef`.
-4. ~~**Bug 5 (banner missing)**~~ — **FIXED**. Side effect of inline restore removal + verified via CDP.
-5. ~~**Bug 1 (timer overwrite)**~~ — **FIXED**. `pendingRestoreTimers` keyed by ptyId, cancel without restore.
-6. **Cleanup** — Remove `[mobile-fit]` diagnostic logs, Debug Test button, dead code.
diff --git a/docs/design-379.md b/docs/design-379.md
deleted file mode 100644
index 5c2f7ddf6ff..00000000000
--- a/docs/design-379.md
+++ /dev/null
@@ -1,143 +0,0 @@
-# Design: Searchable Repository Selection in New Worktree Dialog
-
-## 1. Problem Statement
-
-GitHub issue [#379](https://github.com/stablyai/orca/issues/379): when creating a new worktree, the user must manually scroll a plain `Select` dropdown to pick the target repository. This does not scale once Orca manages many repositories.
-
-The current Radix `Select` in `AddWorktreeDialog` has two product problems:
-
-- It forces serial scanning instead of direct search.
-- It makes the most important first step in the worktree-creation flow slower than every subsequent step.
-
-The issue has no explicit acceptance criteria, so implementation requirements are inferred from the existing UX:
-
-- Users must be able to search for a repository by name while creating a worktree.
-- Existing auto-preselection behavior (preselectedRepoId, activeWorktreeRepoId, activeRepoId fallback chain) must keep working.
-- Keyboard and mouse selection must both work.
-- The change must not break the rest of the create-worktree flow: setup lookup, issue-command lookup, validation, and Enter-to-create behavior.
-
-## 2. Approach
-
-Replace the repository `Select` with a searchable combobox built from Orca's existing `Command` primitive (cmdk-based) and a new shared `Popover` primitive (Radix-based).
-
-Rationale:
-
-- A combobox is the standard pattern for "pick one item from a potentially long list, with search."
-- Orca already ships `cmdk`-based command surfaces and Radix primitives, so this fits the existing stack without introducing new dependencies.
-- Keeping the search scoped to the repo field preserves the current worktree-creation layout instead of turning the entire dialog into a command palette.
-- Search logic lives in a pure helper (`searchRepos`) so matching rules are explicit and regression-testable outside React.
-
-### Matching and ranking
-
-- Search is case-insensitive substring matching.
-- Primary target is `repo.displayName` (what issue #379 is specifically about). Secondary target is `repo.path` for disambiguating repos with similar display names.
-- Ranking uses position-based scoring: matches earlier in the string rank higher. Display-name matches always outrank path-only matches (path scores are offset by 1000). Ties preserve original list order.
-- Empty query returns the full eligible repo list in its original order.
-
-## 3. Implementation Plan
-
-### `src/renderer/src/components/ui/popover.tsx`
-
-New shared Popover wrapper around Radix `Popover`. Follows the same styling conventions as existing `dialog.tsx`, `select.tsx`, and `dropdown-menu.tsx`. Generic and reusable — not inlined inside the worktree dialog.
-
-### `src/renderer/src/lib/repo-search.ts`
-
-New pure helper (`searchRepos`) that filters and ranks eligible repositories by a query string. Normalizes trimming and lowercasing in one place. Scoring logic:
-
-- Display-name hit: score = index of substring match within `displayName`.
-- Path-only hit: score = 1000 + index of substring match within `path`.
-- No hit: excluded from results.
-- Stable sort by `(score, originalIndex)` so equivalent matches preserve list order.
-
-### `src/renderer/src/lib/repo-search.test.ts`
-
-Unit tests covering:
-
-- Empty query returns all repos in original order.
-- Display-name matching is case-insensitive.
-- Path fallback works when the display name does not match.
-- Display-name matches rank ahead of path-only matches.
-
-### `src/renderer/src/components/repo/RepoCombobox.tsx`
-
-New reusable combobox component. Props: `repos`, `value`, `onValueChange`, optional `placeholder`.
-
-Key design decisions:
-
-- **External filtering**: `Command` is rendered with `shouldFilter={false}` because filtering is handled by `searchRepos`, not by cmdk's built-in filter. This keeps ranking rules in the pure helper where they are testable.
-- **Trigger and content markup**: Both the trigger `Button` and `PopoverContent` carry `data-repo-combobox-root="true"` so the parent dialog's keydown handler can detect events originating inside the combobox surface (see Section 5).
-- **Selected repo display**: The trigger renders the selected repo using the existing `RepoDotLabel` component, consistent with how repos appear elsewhere in Orca.
-- **Result items**: Each item shows `RepoDotLabel` for the display name plus the full `repo.path` as secondary text, so repos with similar names are visually distinguishable.
-- **Popover width**: `PopoverContent` uses `w-[var(--radix-popover-trigger-width)]` to match the trigger width for visual alignment.
-- **Focus management**: `CommandInput` has `autoFocus` so the search input receives focus immediately when the popover opens.
-- **Query reset on close**: `handleOpenChange` clears the query when the popover closes so stale filter text from a previous interaction does not hide repos on the next open.
-- **Empty state**: `CommandEmpty` shows an explicit message when no repo matches.
-
-### `src/renderer/src/components/sidebar/AddWorktreeDialog.tsx`
-
-Changes to the existing dialog:
-
-- Replace the `Select` repository control with `RepoCombobox`.
-- All existing repo-selection state and side effects are preserved unchanged: `repoId`, `handleRepoChange`, auto-preselection on open, hook lookup, and issue-command lookup.
-- Update the dialog-level `handleKeyDown` to suppress Enter when the event target lives inside a `[data-repo-combobox-root="true"]` element (see Section 5).
-
-## 4. Edge Cases
-
-| Scenario | Handling |
-|---|---|
-| No eligible git repos | Existing guard closes the dialog; the combobox is never rendered in a broken state. |
-| Only one eligible repo | The combobox still renders normally. Search is trivial, but the UI stays consistent. |
-| Multiple repos share a similar display name | Search also matches `repo.path`, and each item shows the full path as secondary text for disambiguation. |
-| User opens combobox, types a query, closes, reopens | Query resets on close so the next open starts from the full list. |
-| Enter pressed while focus is inside the repo search input | The dialog-level create shortcut is suppressed for events originating inside the combobox (see Section 5). |
-| Preselected repo is not the first repo in the list | Auto-preselection logic is unchanged; the selected value is still controlled by `repoId` state. |
-| Repo list changes while the dialog is open | The combobox renders from the live `eligibleRepos` array and updates reactively. If the selected repo disappears, existing dialog validation prevents create without a valid `selectedRepo`. |
-
-## 5. Regressions and Mitigations
-
-### Enter inside repo search creates a worktree
-
-This is the most important correctness constraint. Without mitigation, typing a search query and pressing Enter to select a repo would bubble up to the dialog's keydown handler and trigger worktree creation.
-
-Mitigation: `data-repo-combobox-root="true"` is placed on both the combobox trigger button and the popover content. The dialog's `handleKeyDown` checks `e.target.closest('[data-repo-combobox-root="true"]')` and returns early when it finds a match. This covers Enter events from:
-
-- The `CommandInput` search field (inside the popover content).
-- The trigger button itself when the popover is closed (Enter should open the popover, not submit the form).
-
-An inline comment in `handleKeyDown` documents why this guard exists.
-
-### Stale search query hides repos on reopen
-
-Mitigation: `RepoCombobox.handleOpenChange` resets the query to `''` whenever the popover closes. An inline comment documents the timing interaction with the dialog's own delayed field reset.
-
-### Repo preselection breaks
-
-Mitigation: `repoId` remains the single source of truth for the selected repository. Only the presentation control was swapped; the state management and auto-selection logic in `AddWorktreeDialog` are untouched.
-
-### Users cannot distinguish similarly named repos
-
-Mitigation: Each combobox item shows both the `RepoDotLabel` display name and the full `repo.path` as secondary text.
-
-### Matching behavior drifts over time
-
-Mitigation: Search rules live in the pure `searchRepos` helper with dedicated unit tests, not inlined in JSX.
-
-## 6. Test Plan
-
-### Unit tests (`repo-search.test.ts`)
-
-- Empty query returns all repos in original order.
-- Display-name matching is case-insensitive.
-- Path fallback works when the display name does not match.
-- Display-name matches rank ahead of path-only matches.
-
-### Manual verification
-
-- Open the New Worktree dialog with multiple repos.
-- Confirm the repo field opens a searchable combobox instead of a plain dropdown.
-- Type part of a repo name and verify the list filters immediately.
-- Press Enter to select a filtered repo and verify the dialog does not submit.
-- Create a worktree after selecting a repo through search and verify the existing create flow still works end-to-end (setup, issue command, metadata).
-- Reopen the dialog and verify the previous search text is cleared.
-- Verify the preselected repo still appears when opening from flows that pass `preselectedRepoId`.
-- Verify keyboard navigation (arrow keys, Enter to select, Escape to close popover) works within the combobox.
diff --git a/docs/design-preserve-scroll-position.md b/docs/design-preserve-scroll-position.md
deleted file mode 100644
index b149225facf..00000000000
--- a/docs/design-preserve-scroll-position.md
+++ /dev/null
@@ -1,213 +0,0 @@
-# Design: Preserve Scroll Position Per File in Editor
-
-## Context
-
-When navigating between file tabs, the scroll position resets to the top because each editor component unmounts and remounts. The cursor line is already tracked per file via `editorCursorLine` in the store, but scroll position is not. This causes a poor UX when users switch between files frequently.
-
-## Approach
-
-Use a module-scoped `Map<string, number>` with LRU eviction, following the proven pattern from `CombinedDiffViewer` (lines 39–58). The scroll cache is extracted into a shared utility at `src/renderer/src/lib/scroll-cache.ts` so all viewer components share one bounded Map.
-
-**Why not Zustand?** Scroll position updates at high frequency during user interaction. Putting it in Zustand means every write spreads a new object (`{ ...s.editorScrollTop, [fileId]: scrollTop }`), which (a) causes React re-render notifications even though no component subscribes to scroll position for rendering, and (b) generates object allocation churn on every scroll event. A module-scoped Map avoids both problems: zero re-renders, zero GC pressure, O(1) reads and writes. CombinedDiffViewer already validates this approach in production.
-
-**Why LRU at 20 entries?** Without a cap, the Map grows unboundedly as unique file IDs accumulate across a session. 20 entries covers typical tab working sets with headroom. This matches `CombinedDiffViewer`'s existing cap and means no explicit cleanup is needed when files are closed — eviction is automatic.
-
-## Files to Modify
-
-### 1. Shared Utility: `src/renderer/src/lib/scroll-cache.ts` (new file)
-
-Extract `setWithLRU` from `CombinedDiffViewer` into a shared module, and expose a single scroll cache Map:
-
-```ts
-const CACHE_MAX_ENTRIES = 20
-
-// Why: Module-scoped Maps grow unboundedly as unique file keys accumulate.
-// Cap them with a simple LRU eviction: after each set, if the map exceeds
-// this limit, delete the oldest entry (Maps iterate in insertion order).
-export function setWithLRU<K, V>(map: Map<K, V>, key: K, value: V): void {
-  // Re-insert to refresh insertion order (move to end).
-  map.delete(key)
-  map.set(key, value)
-  if (map.size > CACHE_MAX_ENTRIES) {
-    const oldestKey = map.keys().next().value
-    if (oldestKey !== undefined) {
-      map.delete(oldestKey)
-    }
-  }
-}
-
-// Why: A single shared Map for scroll positions across all editor components.
-// Module-scoped so it survives component unmount/remount without triggering
-// React re-renders (unlike Zustand, which would broadcast state changes on
-// every scroll event even though no component renders from scroll position).
-export const scrollTopCache = new Map<string, number>()
-```
-
-After extracting, update `CombinedDiffViewer` to import `setWithLRU` from this module instead of defining it inline. `CombinedDiffViewer`'s own `combinedDiffViewStateCache` and `combinedDiffScrollTopCache` stay local since their value types are component-specific.
-
----
-
-### 2. MonacoEditor: `src/renderer/src/components/editor/MonacoEditor.tsx`
-
-**Save scroll position:**
-
-In `handleMount` (line ~62), add a throttled scroll listener:
-
-```ts
-import { scrollTopCache, setWithLRU } from '@renderer/lib/scroll-cache'
-
-// 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
-// avoiding excessive writes.
-let scrollThrottleTimer: ReturnType<typeof setTimeout> | null = null
-
-editorInstance.onDidScrollChange((e) => {
-  if (scrollThrottleTimer !== null) clearTimeout(scrollThrottleTimer)
-  scrollThrottleTimer = setTimeout(() => {
-    setWithLRU(scrollTopCache, filePath, e.scrollTop)
-    scrollThrottleTimer = null
-  }, 150)
-})
-```
-
-Also snapshot the current position synchronously in the cleanup/unmount path (before the timeout fires) so tab switches always capture the latest value — same pattern as `CombinedDiffViewer`'s `updateCachedScrollPosition()` call in its cleanup return.
-
-**Restore scroll position:**
-
-In the `else` branch (line ~118) where there is NO pending reveal:
-
-```ts
-const savedScrollTop = scrollTopCache.get(filePath)
-if (savedScrollTop !== undefined) {
-  // Why: Monaco renders synchronously, so a single RAF is sufficient to
-  // wait for the layout pass. Unlike react-markdown or Tiptap, there is
-  // no async content loading that would require a retry loop.
-  requestAnimationFrame(() => editorInstance.setScrollTop(savedScrollTop))
-}
-```
-
-**Key edge case:** When `pendingEditorReveal` exists (search-result navigation), skip scroll restoration — `performReveal` handles its own scroll.
-
----
-
-### 3. MarkdownPreview: `src/renderer/src/components/editor/MarkdownPreview.tsx`
-
-**Mode-scoped cache key:**
-
-```ts
-// Why: Each markdown viewing mode (source/rich/preview) produces different
-// DOM structures and content heights. A scroll position saved in source mode
-// (a code block at line 500) has no meaningful correspondence in preview mode
-// (rendered HTML at a completely different height). Using mode-scoped keys
-// means each mode remembers its own position independently.
-const scrollCacheKey = `${filePath}:preview`
-```
-
-**Save scroll position:**
-
-Add a throttled scroll listener on `rootRef.current` (the scrollable div, line 192) via `useLayoutEffect`:
-
-```ts
-useLayoutEffect(() => {
-  const container = rootRef.current
-  if (!container) return
-
-  let throttleTimer: ReturnType<typeof setTimeout> | null = null
-
-  const onScroll = (): void => {
-    if (throttleTimer !== null) clearTimeout(throttleTimer)
-    throttleTimer = setTimeout(() => {
-      setWithLRU(scrollTopCache, scrollCacheKey, container.scrollTop)
-      throttleTimer = null
-    }, 150)
-  }
-
-  container.addEventListener('scroll', onScroll, { passive: true })
-  return () => {
-    // Snapshot final position synchronously before detach.
-    setWithLRU(scrollTopCache, scrollCacheKey, container.scrollTop)
-    if (throttleTimer !== null) clearTimeout(throttleTimer)
-    container.removeEventListener('scroll', onScroll)
-  }
-}, [scrollCacheKey])
-```
-
-**Restore scroll position (RAF retry loop):**
-
-react-markdown renders asynchronously — content may not be in the DOM when the layout effect first runs, so `scrollHeight` is still small and `scrollTop` gets clamped to 0. Use `CombinedDiffViewer`'s RAF retry pattern (lines 353–388) to keep attempting until content has loaded:
-
-```ts
-useLayoutEffect(() => {
-  const container = rootRef.current
-  const targetScrollTop = scrollTopCache.get(scrollCacheKey)
-  if (!container || targetScrollTop === undefined) return
-
-  let frameId = 0
-  let attempts = 0
-
-  // Why: react-markdown renders asynchronously, so scrollHeight may still be
-  // too small on the first frame. Retry up to 30 frames (~500ms at 60fps) to
-  // accommodate content loading. This matches CombinedDiffViewer's proven
-  // pattern for dynamic-height content restoration.
-  const tryRestore = (): void => {
-    const maxScrollTop = Math.max(0, container.scrollHeight - container.clientHeight)
-    const nextScrollTop = Math.min(targetScrollTop, maxScrollTop)
-    container.scrollTop = nextScrollTop
-
-    if (Math.abs(container.scrollTop - targetScrollTop) <= 1 || maxScrollTop >= targetScrollTop) {
-      return
-    }
-
-    attempts += 1
-    if (attempts < 30) {
-      frameId = window.requestAnimationFrame(tryRestore)
-    }
-  }
-
-  tryRestore()
-  return () => window.cancelAnimationFrame(frameId)
-}, [scrollCacheKey])
-```
-
----
-
-### 4. RichMarkdownEditor: `src/renderer/src/components/editor/RichMarkdownEditor.tsx`
-
-Same approach as MarkdownPreview with two differences:
-
-1. **Cache key:** `${filePath}:rich`
-2. **Scroll container:** The scrollable container is `<EditorContent>` with `overflow-auto` (line 334). Wrap in a div with a ref to get the scroll container, move `overflow-auto` to wrapper.
-
-The RAF retry loop is needed here too — Tiptap renders asynchronously as it hydrates its ProseMirror document, so `scrollHeight` may be undersized on the initial frame.
-
-Save/restore logic is identical to MarkdownPreview, substituting the container ref and cache key.
-
----
-
-### 5. DiffViewer — Deferred
-
-DiffViewer doesn't currently receive `filePath` and diff views are typically opened for brief review. Deferring to avoid scope creep. `CombinedDiffViewer` already has its own scroll cache; if DiffViewer needs one later it can import from `scroll-cache.ts`.
-
-## Edge Cases
-
-| Case                                    | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Pending reveal (search nav)             | Scroll restoration skipped; `performReveal` takes priority                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| First open (no saved position)          | `undefined` in cache → no restoration, starts at top                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| Markdown mode switch (source → preview) | Mode-scoped keys (`path:source`, `path:preview`, `path:rich`) mean each mode preserves its own position independently. No cross-mode confusion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Scroll at 0                             | Always restore (including 0) to guard against Monaco auto-scroll behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| External file content changes           | **Known trade-off:** When external changes add/remove content above the viewport, the saved scroll position points to different content. Monaco clamps `scrollTop` if it exceeds the new document length, but does not adjust for insertions above the viewport. HTML containers (`MarkdownPreview`, `RichMarkdownEditor`) behave the same way — the browser clamps `scrollTop` to `scrollHeight - clientHeight`. This is acceptable: scroll position is a best-effort hint, not a semantic anchor. Fixing this would require mapping scroll offsets to content anchors (like line numbers), which is out of scope. |
-| LRU eviction (>20 files)                | Oldest scroll entry is evicted. User sees top-of-file on return to a very old tab — same as a fresh open. No data corruption or memory leak.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Close file, reopen                      | LRU may or may not still have the entry. If present, position restores. If evicted, starts at top. No explicit cleanup needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| Async content (react-markdown, Tiptap)  | RAF retry loop (up to 30 attempts) handles content that renders after the initial layout pass. Falls back to best-effort clamped position if content never reaches the target height.                                                                                                                                                                                                                                                                                                                                                                                                                               |
-
-## Verification
-
-1. Open a code file, scroll down ~50%, switch to another tab, switch back → verify position preserved
-2. Open a markdown file in preview mode, scroll down, switch tabs, return → verify position preserved
-3. Open a markdown file in rich mode, scroll down, switch tabs, return → verify position preserved
-4. Switch a markdown file from source to preview mode → verify each mode has independent scroll position (scroll in source, switch to preview, preview starts at its own saved position or top)
-5. Use Cmd+Shift+F to search, click a result → verify it scrolls to the match (NOT saved position)
-6. Open 25+ files to trigger LRU eviction, return to the earliest file → verify it starts at top gracefully
-7. `pnpm run typecheck` passes
diff --git a/docs/design/persist-ssh-sessions.md b/docs/design/persist-ssh-sessions.md
deleted file mode 100644
index 08dbb290e26..00000000000
--- a/docs/design/persist-ssh-sessions.md
+++ /dev/null
@@ -1,654 +0,0 @@
-# Design: Persist and Auto-Restore SSH Sessions Across App Restarts
-
-**Issue:** [#985](https://github.com/stablyai/orca/issues/985)
-**Branch:** `Jinwoo-H/persist-ssh-985`
-**Author:** Jinwoo Hong
-**Status:** Draft
-
-## Problem
-
-When Orca quits (intentionally, via update, or crash), all SSH connections and remote terminal sessions are lost. On restart, users must manually re-open each remote worktree, wait for SSH + relay redeploy, and re-start every remote process — even though the relay daemon on the remote host stays alive during its 5-minute grace window.
-
-Three specific gaps:
-
-1. **SSH connections are not persisted.** `buildWorkspaceSessionPayload()` in `src/renderer/src/lib/workspace-session.ts` captures terminal tabs, layouts, editor files, and browser tabs but has zero SSH state. `WorkspaceSessionState` has no fields for active connection IDs.
-
-2. **Remote PTY session IDs are not persisted.** `reconnectPersistedTerminals()` in `src/renderer/src/store/slices/terminals.ts:1205` explicitly skips SSH-backed repos (`const supportsDeferredReattach = !repo?.connectionId`). Even if the relay keeps PTYs alive, Orca doesn't know their session IDs after restart.
-
-3. **Shutdown doesn't serialize SSH state.** Neither `beforeunload` in `App.tsx` nor `will-quit` in `src/main/index.ts` records which SSH targets were connected or what remote PTY session IDs existed.
-
-## Scope
-
-**In scope (Layer 1 — app-bound lifetime):**
-- Persist active SSH connection targets and remote PTY session IDs at shutdown
-- Auto-reconnect SSH targets on startup
-- Reattach remote PTYs via the relay's existing `pty.attach` RPC
-- Make the relay grace window configurable via settings
-
-**Out of scope (Layer 2 — future):**
-- Background daemon owning SSH connections independent of app lifecycle
-- Credential persistence (passphrases/passwords remain session-only)
-
-## Existing Architecture
-
-### What already works
-
-| Component | File | Behavior |
-|-----------|------|----------|
-| Relay grace timer | `src/relay/relay.ts:15,70-76` | Keeps PTYs alive 5 min after client disconnect |
-| Relay `pty.attach` | `src/relay/pty-handler.ts` | Replays buffered output on reattach |
-| In-session reconnect | `src/main/ipc/ssh-relay-helpers.ts` | `reestablishRelayStack()` re-deploys relay, reattaches PTYs for transient drops |
-| SSH target persistence | `src/main/persistence.ts:365-398` | Target configs (host, user, identity) survive restarts |
-| Local PTY reattach | `src/renderer/src/store/slices/terminals.ts:1167-1266` | Daemon-mode local PTYs reattach via `pendingReconnectPtyIdByTabId` |
-| PTY ownership tracking | `src/main/ipc/pty.ts` | `getPtyIdsForConnection()` maps PTY IDs to connection targets (in-memory) |
-| SSH connection retry | `src/main/ssh/ssh-connection.ts` | Exponential backoff reconnection for transient errors |
-
-### Connection lifecycle (current)
-
-```
-App Start → hydrate repos/worktrees → reconnectPersistedTerminals()
-                                        ↓
-                              skips SSH repos (connectionId truthy)
-                                        ↓
-                              SSH tabs show as disconnected
-```
-
-```
-App Shutdown → beforeunload → buildWorkspaceSessionPayload()
-                                ↓
-                     captures local PTY IDs, tabs, layouts
-                     does NOT capture SSH connection state
-                     does NOT capture remote PTY session IDs
-```
-
-## Design
-
-### 1. Extend WorkspaceSessionState
-
-**File:** `src/shared/types.ts`
-
-Add two new optional fields:
-
-```typescript
-export type WorkspaceSessionState = {
-  // ... existing fields ...
-
-  /** SSH target IDs that were connected at shutdown. Used on startup to
-   *  auto-reconnect before attempting remote PTY reattach. */
-  activeConnectionIdsAtShutdown?: string[]
-
-  /** Maps tab IDs to their remote relay PTY session IDs. Mirrors
-   *  pendingReconnectPtyIdByTabId but for SSH-backed terminals. Populated
-   *  at shutdown from the main-process PTY ownership registry. */
-  remoteSessionIdsByTabId?: Record<string, string>
-}
-```
-
-**File:** `src/shared/workspace-session-schema.ts`
-
-Add corresponding Zod schemas:
-
-```typescript
-activeConnectionIdsAtShutdown: z.array(z.string()).optional(),
-remoteSessionIdsByTabId: z.record(z.string(), z.string()).optional(),
-```
-
-### 2. Capture SSH state at shutdown
-
-**File:** `src/renderer/src/lib/workspace-session.ts`
-
-The `WorkspaceSessionSnapshot` type gains two new fields from AppState, and `buildWorkspaceSessionPayload()` populates the new session fields.
-
-The renderer already has the data it needs — no IPC required. `tabsByWorktree` contains each tab's `ptyId`, and the renderer knows which worktrees are SSH-backed via `repo.connectionId`. Building the map renderer-side avoids a synchronous IPC call during `beforeunload` (which is fragile: sync IPC blocks the main process and can be dropped under time pressure on quit).
-
-**File:** `src/renderer/src/lib/workspace-session.ts`
-
-Add `sshConnectionStates` and `repos` / `worktreesByRepo` to the `WorkspaceSessionSnapshot` Pick type, then build both new fields in `buildWorkspaceSessionPayload()`:
-
-```typescript
-// Capture active SSH connections.
-// Why: sshConnectionStates is a Map<string, SshConnectionState>, not a plain
-// object. Object.entries() on a Map returns [] — must use Array.from().
-const connectedTargetIds = Array.from(snapshot.sshConnectionStates.entries())
-  .filter(([, state]) => state.status === 'connected')
-  .map(([targetId]) => targetId)
-
-// Build remote PTY session IDs from renderer state.
-// Why: the renderer already has tab.ptyId for every terminal tab and knows
-// which worktrees are SSH-backed via repo.connectionId. Deriving the map
-// here avoids a sync IPC round-trip during beforeunload, which is fragile
-// (can be dropped by Chromium under shutdown time pressure).
-const remoteSessionIdsByTabId: Record<string, string> = {}
-for (const [worktreeId, tabs] of Object.entries(snapshot.tabsByWorktree)) {
-  const worktree = Object.values(snapshot.worktreesByRepo)
-    .flat()
-    .find((w) => w.id === worktreeId)
-  const repo = worktree
-    ? snapshot.repos.find((r) => r.id === worktree.repoId)
-    : null
-  if (!repo?.connectionId) continue  // not SSH-backed
-  for (const tab of tabs) {
-    if (tab.ptyId) {
-      remoteSessionIdsByTabId[tab.id] = tab.ptyId
-    }
-  }
-}
-
-return {
-  // ... existing fields ...
-  activeConnectionIdsAtShutdown: connectedTargetIds.length > 0
-    ? connectedTargetIds : undefined,
-  remoteSessionIdsByTabId: Object.keys(remoteSessionIdsByTabId).length > 0
-    ? remoteSessionIdsByTabId : undefined,
-}
-```
-
-### 3. Auto-reconnect SSH on startup
-
-**File:** `src/renderer/src/App.tsx`
-
-Insert an SSH reconnect pass between workspace hydration and `reconnectPersistedTerminals()`. Targets are split into two categories:
-
-1. **Non-passphrase targets** — reconnected eagerly at startup in parallel.
-2. **Passphrase-protected targets** — deferred until the user focuses an SSH-backed terminal tab.
-
-**Why defer passphrase targets:** Eagerly reconnecting passphrase-protected keys would pop credential dialogs before the user has context about which terminal is reconnecting. Stacking multiple passphrase prompts at startup is disorienting and error-prone (wrong passphrase entered for the wrong key). Deferring to tab focus lets the user see the terminal they're about to reconnect and provide the credential with full context.
-
-```typescript
-// After repos/worktrees hydrated, before terminal reconnect
-const connectionIds = session.activeConnectionIdsAtShutdown ?? []
-const SSH_RECONNECT_TIMEOUT_MS = 15_000
-
-if (connectionIds.length > 0) {
-  // Partition targets: eagerly reconnect non-passphrase targets,
-  // defer passphrase-protected targets to tab focus.
-  // Why: use listTargets (which already has an IPC handler) and index
-  // by ID, rather than adding a per-target IPC call. Fetching all
-  // targets in one call is simpler and avoids adding a new ssh:getTarget
-  // handler that would only be used here.
-  const allTargets = await window.api.ssh.listTargets()
-  const targetMap = new Map(allTargets.map((t) => [t.id, t]))
-  const targets = connectionIds.map((targetId) => {
-    const target = targetMap.get(targetId)
-    return { targetId, needsPassphrase: target?.lastRequiredPassphrase ?? false }
-  })
-
-  const eagerTargets = targets.filter((t) => !t.needsPassphrase)
-  const deferredTargets = targets.filter((t) => t.needsPassphrase)
-
-  // Store deferred targets so on-demand reconnect can pick them up
-  if (deferredTargets.length > 0) {
-    actions.setDeferredSshReconnectTargets(
-      deferredTargets.map((t) => t.targetId)
-    )
-  }
-
-  // Reconnect eager targets in parallel with per-target timeout.
-  // Why: a per-target timeout prevents a single unreachable host from
-  // blocking the entire startup sequence. 15 seconds is long enough for
-  // a typical SSH handshake + relay redeploy over broadband, short enough
-  // to avoid the user staring at a frozen app.
-  await Promise.allSettled(
-    eagerTargets.map(({ targetId }) =>
-      Promise.race([
-        window.api.ssh.connect({ targetId }),
-        new Promise((_, reject) =>
-          setTimeout(() => reject(new Error('SSH reconnect timeout')),
-            SSH_RECONNECT_TIMEOUT_MS)
-        )
-      ]).catch((err) => {
-        console.warn(`SSH auto-reconnect failed for ${targetId}:`, err)
-      })
-    )
-  )
-}
-
-// Now proceed with terminal reconnect (which can now include SSH tabs)
-await actions.reconnectPersistedTerminals(abortController.signal)
-```
-
-**On-demand reconnect for deferred (passphrase-protected) targets:**
-
-When the user focuses a terminal tab backed by a deferred SSH target, the tab's mount logic checks `deferredSshReconnectTargets`. If the tab's `connectionId` is in that set, it triggers `ssh:connect` for that target, shows the passphrase dialog naturally, and on success proceeds with `pty.attach` for that tab's persisted session ID. The target is removed from the deferred set once connected (or after the user cancels).
-
-```typescript
-// In terminal pane mount / tab focus handler
-const deferredTargets = get().deferredSshReconnectTargets ?? []
-if (repo?.connectionId && deferredTargets.includes(repo.connectionId)) {
-  // Show reconnecting overlay on this tab (see Section 6)
-  try {
-    await window.api.ssh.connect({ targetId: repo.connectionId })
-    actions.removeDeferredSshReconnectTarget(repo.connectionId)
-    // Proceed to pty.attach with the persisted sessionId
-  } catch (err) {
-    // Leave tab in disconnected state with retry affordance
-  }
-}
-```
-
-The `ssh:connect` IPC handler already exists and handles the full flow: SSH connect → relay deploy → provider registration. No new main-process code needed for the connect path.
-
-**Error handling:** Each connection attempt is independent. Failed connections show the existing `SshDisconnectedDialog` with manual retry. Successful connections proceed to PTY reattach.
-
-**Credential prompts:** For eager (non-passphrase) targets, the reconnect completes without user interaction. For deferred targets, the existing `SshPassphraseDialog` flow fires at tab focus — `ssh:credential-request` IPC is already wired.
-
-### 4. Enable remote PTY reattach
-
-**File:** `src/renderer/src/store/slices/terminals.ts`
-
-The current gate at line 1205:
-
-```typescript
-const supportsDeferredReattach = !repo?.connectionId
-```
-
-Changes to:
-
-```typescript
-const supportsDeferredReattach = !repo?.connectionId || hasActiveConnection(repo.connectionId)
-```
-
-Where `hasActiveConnection` checks the renderer's `sshConnectionStates` store for `status === 'connected'`.
-
-For SSH-backed tabs, the reattach data comes from the new `remoteSessionIdsByTabId` session field instead of `pendingReconnectPtyIdByTabId` (which is populated from the local daemon). The hydration step in `hydrateWorkspaceSession` needs to merge remote session IDs into `pendingReconnectPtyIdByTabId`.
-
-**Critical placement constraint:** The existing `pendingReconnectPtyIdByTabId` population loop (lines 1090-1108) is guarded by `if (daemonEnabled)` and explicitly skips SSH-backed repos (`if (repo?.connectionId) { continue }`). The remote session ID merge must run **outside and after** that guard block — SSH PTY reattach does not depend on the local terminal daemon; it uses the relay's `pty.attach` RPC. If the merge is placed inside the `daemonEnabled` block, users without the experimental daemon flag will never have remote session IDs populated, silently breaking the entire reattach feature.
-
-**File:** `src/renderer/src/store/slices/terminals.ts` — In `hydrateWorkspaceSession`, after the existing `if (daemonEnabled) { ... }` block (line 1108):
-
-```typescript
-// Existing code (unchanged):
-const daemonEnabled = s.settings?.experimentalTerminalDaemon === true
-const pendingReconnectPtyIdByTabId: Record<string, string> = {}
-if (daemonEnabled) {
-  // ... existing loop for local daemon session IDs (skips SSH repos) ...
-}
-
-// NEW: merge remote PTY session IDs from SSH persistence.
-// Why: this runs outside the daemonEnabled guard because remote PTY reattach
-// uses the relay's pty.attach RPC, not the local terminal daemon. SSH-backed
-// tabs need their session IDs regardless of the experimentalTerminalDaemon
-// setting. The existing loop above correctly skips SSH repos (connectionId
-// check), so there is no overlap — local daemon IDs and remote session IDs
-// are mutually exclusive per-tab.
-const remoteSessionIds = session.remoteSessionIdsByTabId ?? {}
-for (const [tabId, sessionId] of Object.entries(remoteSessionIds)) {
-  if (validTabIds.has(tabId)) {
-    pendingReconnectPtyIdByTabId[tabId] = sessionId
-  }
-}
-```
-
-The inner guard in `reconnectPersistedTerminals` (`if (supportsDeferredReattach && tabLevelPtyId)`) works correctly for SSH tabs because `tabLevelPtyId` is now populated by this merge, and `supportsDeferredReattach` is `true` for connected SSH targets.
-
-**File:** `src/main/providers/ssh-pty-provider.ts` — Modify `spawn()` to detect sessionId:
-
-The current `SshPtyProvider.spawn()` unconditionally calls `pty.spawn` and ignores `opts.sessionId`. This is the critical missing link — without this change, passing a sessionId through `connectPanePty` has no effect on the remote relay.
-
-```typescript
-async spawn(opts: PtySpawnOptions): Promise<PtySpawnResult> {
-  // Why: when sessionId is present, the caller is requesting reattach to an
-  // existing relay PTY (persisted across app restart). Calling pty.spawn would
-  // create a new shell and discard the buffered output the relay kept alive
-  // during the grace window. pty.attach replays that buffer instead.
-  if (opts.sessionId) {
-    try {
-      await this.mux.request('pty.attach', {
-        id: opts.sessionId,
-        cols: opts.cols,
-        rows: opts.rows
-      })
-      return { id: opts.sessionId }
-    } catch (err) {
-      // Why: pty.attach fails when the relay grace window has elapsed and the
-      // PTY no longer exists (relay returns "not found"). Without this catch,
-      // the error propagates as an unhandled rejection and the terminal tab
-      // stays stuck. Falling through to pty.spawn gives the user a fresh
-      // shell, and sessionExpired lets the renderer show a brief toast
-      // ("Session expired — new shell started") so the user understands why
-      // their scrollback is gone.
-      console.warn(`[ssh-pty] pty.attach failed for ${opts.sessionId}, falling back to fresh spawn:`, err)
-    }
-  }
-
-  const result = await this.mux.request('pty.spawn', {
-    cols: opts.cols,
-    rows: opts.rows,
-    cwd: opts.cwd,
-    env: opts.env
-  })
-  // Why: sessionExpired is only set when we attempted reattach and it failed.
-  // The renderer checks this flag to show the "Session expired" toast. When
-  // sessionId was never provided (fresh terminal), this field is omitted.
-  return {
-    ...(result as PtySpawnResult),
-    ...(opts.sessionId ? { sessionExpired: true } : {})
-  }
-}
-```
-
-The `PtySpawnResult` type (in `src/main/providers/types.ts`) needs a new optional field:
-
-```typescript
-export type PtySpawnResult = {
-  id: string
-  /** True when the caller requested reattach (sessionId was provided) but the
-   *  relay PTY was gone (grace window elapsed). The renderer uses this to show
-   *  a brief "Session expired — new shell started" toast. */
-  sessionExpired?: boolean
-}
-```
-
-This routes through to the relay's existing `pty.attach` RPC, which replays buffered output via the `pty.replay` notification.
-
-**File:** `src/main/ipc/ssh-relay-helpers.ts` — Wire `onReplay` in `wireUpSshPtyEvents()`:
-
-The current `wireUpSshPtyEvents()` only wires `onData` and `onExit`. It does **not** wire `onReplay`. After `pty.attach`, the relay sends a `pty.replay` notification with buffered output, but without this wiring the replay data is silently dropped and the terminal renders blank after reattach.
-
-Why use a dedicated `pty:replay` IPC channel (not `pty:data`): the renderer's `pty-transport.ts` has a `replayingBufferedData` flag that suppresses xterm auto-replies to embedded terminal query sequences (e.g., `\x1b[6n` for cursor position reports) during replay. If relay replay data arrives via the regular `pty:data` channel, this flag is **not set** — xterm processes the data as normal output and auto-replies leak into the remote shell as stray input, potentially executing unintended commands. A dedicated `pty:replay` channel lets the renderer route replay through the guarded `onReplayData` callback, which suppresses auto-replies.
-
-```typescript
-export function wireUpSshPtyEvents(
-  ptyProvider: SshPtyProvider,
-  getMainWindow: () => BrowserWindow | null
-): void {
-  ptyProvider.onData((payload) => {
-    const win = getMainWindow()
-    if (win && !win.isDestroyed()) {
-      win.webContents.send('pty:data', payload)
-    }
-  })
-  // Why: after pty.attach, the relay sends pty.replay with buffered output
-  // from the grace window. Without this, reattached terminals render blank.
-  // Uses a dedicated pty:replay channel (not pty:data) so the renderer can
-  // route it through the replay-guarded onReplayData callback, which
-  // suppresses xterm auto-replies to embedded query sequences.
-  ptyProvider.onReplay((payload) => {
-    const win = getMainWindow()
-    if (win && !win.isDestroyed()) {
-      win.webContents.send('pty:replay', payload)
-    }
-  })
-  ptyProvider.onExit((payload) => {
-    clearProviderPtyState(payload.id)
-    deletePtyOwnership(payload.id)
-    const win = getMainWindow()
-    if (win && !win.isDestroyed()) {
-      win.webContents.send('pty:exit', payload)
-    }
-  })
-}
-```
-
-The renderer needs a corresponding `pty:replay` handler in `pty-dispatcher.ts` that routes through the existing `onReplayData` callback (same path used by the local daemon's eager buffer replay). This ensures `replayingBufferedData` is set and xterm auto-replies are suppressed during relay replay.
-
-The preload bridge (`src/preload/index.ts`) needs a new `onReplay` binding alongside the existing `onData`:
-
-```typescript
-pty: {
-  // ... existing bindings ...
-  onReplay: (callback: (payload: PtyDataPayload) => void) =>
-    ipcRenderer.on('pty:replay', (_event, payload) => callback(payload)),
-}
-```
-
-Then in `reconnectPersistedTerminals`, when the SSH connection is confirmed active, the existing `pty.spawn` call in `connectPanePty` receives the `sessionId` which routes through `SshPtyProvider.spawn()` → relay `pty.attach()`, replaying buffered output.
-
-**Wait for SSH before reattach:** The key ordering constraint is that `reconnectPersistedTerminals` must run *after* SSH connections are established. The sequential await in App.tsx (step 3) guarantees this.
-
-### 5. Configurable relay grace window
-
-**File:** `src/shared/ssh-types.ts` — Extend `SshTarget`:
-
-```typescript
-export type SshTarget = {
-  // ... existing fields ...
-
-  /** Grace period in seconds before relay shuts down after disconnect.
-   *  Default: 300 (5 minutes). */
-  relayGracePeriodSeconds?: number
-
-  /** Set to true after a successful connection that triggered a credential
-   *  prompt (passphrase or password), false after one that didn't. Persisted
-   *  with the target config so the startup reconnect logic can partition
-   *  targets into eager (no passphrase) vs deferred (passphrase) without
-   *  attempting a connection first.
-   *
-   *  Why a persisted flag instead of inspecting the key at startup: detecting
-   *  whether a key is encrypted requires attempting to load it, which is
-   *  expensive and may itself trigger an OS keychain prompt. Recording the
-   *  outcome of the last successful connection is both cheaper and more
-   *  accurate (it reflects the user's actual auth experience). */
-  lastRequiredPassphrase?: boolean
-}
-```
-
-**Population:** The `lastRequiredPassphrase` flag is set during `ssh:connect` success handling in the main process. When `SshConnection.connect()` succeeds, the handler checks whether a credential prompt was issued during the attempt (the `onCredentialRequest` callback was invoked). If yes, the flag is set to `true` on the target and persisted; if no, it is set to `false`. This ensures the flag stays up to date as users add/remove passphrases from their keys.
-
-**File:** `src/main/ssh/ssh-relay-deploy.ts` — Pass grace time to relay launch:
-
-```typescript
-const graceSeconds = target.relayGracePeriodSeconds ?? 300
-const command = `${relayPath} --grace-time ${graceSeconds}`
-```
-
-**File:** `src/renderer/src/components/settings/SshTargetForm.tsx` — Add UI field with reasonable bounds (60s–3600s).
-
-The relay already accepts `--grace-time` CLI arg (`src/relay/relay.ts:17-29`).
-
-## Sequence Diagram
-
-### Shutdown
-
-```
-Renderer                        Main Process
-   │                                │
-   ├─ beforeunload fires            │
-   ├─ capture terminal buffers      │
-   ├─ build session payload         │
-   │  (derives remoteSessionIdsByTabId from
-   │   Zustand state: tabsByWorktree + repo.connectionId;
-   │   derives activeConnectionIdsAtShutdown from
-   │   sshConnectionStates — no IPC needed)
-   ├─ session:set-sync ────────────►├─ write to orca-data.json
-   │                                ├─ flush()
-   └─ window closes                 └─ SSH connections drop
-                                       relay grace timer starts
-```
-
-### Startup (eager targets — no passphrase)
-
-```
-Renderer                        Main Process              Remote Relay
-   │                                │                         │
-   ├─ session:get ─────────────────►├─ read orca-data.json    │
-   │◄─ session ────────────────────┤                          │
-   ├─ hydrate repos, tabs, layouts  │                         │
-   ├─ partition targets:            │                         │
-   │   eager vs deferred            │                         │
-   │                                │                         │
-   ├─ ssh:connect(eager1) ─────────►├─ SSH handshake ────────►│
-   │  (15s timeout per target)      ├─ deploy relay ─────────►├─ READY
-   │                                ├─ register roots         │
-   │◄─ connected ──────────────────┤                          │
-   │                                │                         │
-   ├─ reconnectPersistedTerminals() │                         │
-   │  (SSH tabs no longer skipped   │                         │
-   │   for connected targets)       │                         │
-   │                                │                         │
-   ├─ connectPanePty(sessionId) ───►├─ SshPtyProvider.spawn() │
-   │                                │  detects sessionId      │
-   │                                ├─ pty.attach(id) ──────►├─ replay buffer
-   │◄─ pty.replay ─────────────────┤◄─ pty.replay ──────────┤
-   │  terminal shows restored       │                         │
-   │  scrollback + live shell       │                         │
-```
-
-### Startup (deferred targets — passphrase-protected)
-
-```
-Renderer                        Main Process              Remote Relay
-   │                                │                         │
-   │  (passphrase targets stored    │                         │
-   │   in deferredSshReconnectTargets)                        │
-   │                                │                         │
-   ├─ user focuses SSH tab ─────────│                         │
-   │  tab shows "Reconnecting..."   │                         │
-   │  overlay                       │                         │
-   ├─ ssh:connect(deferred1) ──────►├─ SSH handshake          │
-   │                                ├─ ssh:credential-request │
-   │◄─ passphrase dialog ──────────┤                          │
-   ├─ user enters passphrase ──────►├─ auth continues ───────►│
-   │                                ├─ deploy relay ─────────►├─ READY
-   │◄─ connected ──────────────────┤                          │
-   │                                │                         │
-   ├─ connectPanePty(sessionId) ───►├─ pty.attach(id) ──────►├─ replay buffer
-   │◄─ pty.replay ─────────────────┤◄─ pty.replay ──────────┤
-   │  overlay removed, terminal     │                         │
-   │  shows restored scrollback     │                         │
-```
-
-## Per-Tab Reconnect Status
-
-During SSH reconnection and PTY reattach, individual terminal tabs need visual feedback so the user knows what's happening and which tabs are still in progress.
-
-**Reconnecting state:** While an SSH target is being reconnected (either eagerly at startup or on-demand at tab focus), each affected terminal tab shows a semi-transparent overlay with a spinner and the text "Reconnecting to [host]...". The terminal content beneath is dimmed but visible — the user can see their previous scrollback through the overlay.
-
-**Reattaching state:** After SSH connects but before `pty.attach` completes and replays the buffer, the overlay updates to "Reattaching session...". This is typically brief (<1 second) but visible on high-latency connections.
-
-**Success:** The overlay is removed and the terminal receives the replayed buffer. No toast or notification — the terminal being live is sufficient signal.
-
-**Failure — target failed:** If the SSH connection fails (timeout, network error, cancelled passphrase), the overlay is replaced with a persistent banner: "SSH connection failed — [reason]" with a "Retry" button. The terminal content remains visible but dimmed and non-interactive.
-
-**Failure — session expired:** If SSH connects but `pty.attach` returns `not-found` (grace window elapsed), the tab shows a brief inline message "Session expired — new shell started" and spawns a fresh PTY. The message auto-dismisses after 5 seconds.
-
-## Partial Failure Behavior
-
-When multiple SSH targets are reconnected at startup, some may succeed and others may fail. The user needs clear per-tab attribution of which connections failed:
-
-- **Tabs backed by a successful target:** Proceed to PTY reattach normally. No special indicator — they work as expected.
-- **Tabs backed by a failed target:** Show the persistent failure banner described above. The banner includes the target hostname so the user can identify which remote host is unreachable.
-- **Tabs backed by a deferred (passphrase) target:** Show a static overlay: "Waiting for connection — focus this tab to reconnect". This distinguishes intentionally-deferred tabs from failed tabs.
-
-This ensures the user can scan their tab bar and immediately tell which terminals are live, which need attention, and which are waiting for credentials.
-
-## Data Flow Diagrams
-
-### Path 1: Happy path (restart within grace window)
-
-```
-SHUTDOWN:
-  Zustand state ──► buildWorkspaceSessionPayload() ──► orca-data.json
-  (tabsByWorktree,    (derives remoteSessionIdsByTabId,    (persisted)
-   sshConnectionStates, activeConnectionIdsAtShutdown)
-   repos, worktreesByRepo)
-
-STARTUP:
-  orca-data.json ──► hydrateWorkspaceSession() ──► ssh:connect(eager) ──► reconnectPersistedTerminals()
-  (read)              (merges remoteSessionIds       (SSH + relay up)       (pty.attach via SshPtyProvider)
-                       into pendingReconnectPtyIdByTabId)                     ──► pty.replay ──► terminal live
-```
-
-### Path 2: Nil path (no SSH state persisted)
-
-```
-SHUTDOWN:
-  No SSH connections active ──► buildWorkspaceSessionPayload() ──► orca-data.json
-                                 (activeConnectionIdsAtShutdown     (no SSH fields)
-                                  omitted, remoteSessionIdsByTabId
-                                  omitted)
-
-STARTUP:
-  orca-data.json ──► hydrateWorkspaceSession() ──► reconnectPersistedTerminals()
-  (no SSH fields)     (no remote IDs to merge)      (SSH tabs still skipped — connectionId
-                                                      but no active connection)
-```
-
-### Path 3: Grace expired (restart after relay grace window)
-
-```
-SHUTDOWN:
-  (same as happy path — SSH state persisted to orca-data.json)
-
-STARTUP:
-  orca-data.json ──► ssh:connect() ──► relay redeploy ──► pty.attach(sessionId)
-                     (SSH succeeds)     (new relay instance;    ──► NOT FOUND
-                                         old PTYs gone)             ──► spawn fresh PTY
-                                                                    ──► "Session expired" message
-```
-
-### Path 4: Error path (SSH connect fails)
-
-```
-SHUTDOWN:
-  (same as happy path — SSH state persisted to orca-data.json)
-
-STARTUP:
-  orca-data.json ──► ssh:connect() ──► TIMEOUT/ERROR (15s)
-                                         ──► tab shows failure banner
-                                         ──► reconnectPersistedTerminals()
-                                              skips tabs for failed targets
-                                              (no active connection)
-                                         ──► user retries manually via banner
-```
-
-## Migration & Backwards Compatibility
-
-- New session fields are optional (`z.optional()`), so older sessions parse without error
-- Older Orca versions ignore unknown fields, so a downgrade doesn't break
-- If `activeConnectionIdsAtShutdown` references a deleted SSH target, the connect call fails gracefully and the tab shows as disconnected
-- If `remoteSessionIdsByTabId` references a PTY that expired (grace window elapsed), `pty.attach` returns `not-found` and the tab spawns a fresh shell
-
-## Edge Cases
-
-| Scenario | Behavior |
-|----------|----------|
-| Relay grace expired before restart | `pty.attach` fails → tab spawns fresh PTY, shows "Session expired — new shell started" |
-| SSH target deleted between shutdown and startup | `ssh:connect` fails → tabs for that target remain disconnected, user sees reconnect dialog |
-| Network unreachable on startup | `ssh:connect` times out → existing retry/backoff kicks in, shows reconnecting status |
-| Passphrase-protected key | Target deferred to on-demand reconnect at tab focus; passphrase dialog fires in context of the specific terminal |
-| Multiple SSH targets | Non-passphrase targets reconnect eagerly in parallel via `Promise.allSettled`; passphrase targets deferred; partial success is fine |
-| Per-target timeout exceeded | Target treated as failed after 15s; tabs show disconnected state with manual retry affordance |
-| Crash (no beforeunload) | No session captured → same as today (no regression). Periodic save (future improvement) could mitigate |
-| App update with relay version bump | Relay redeploy triggers naturally; old PTYs lost (acceptable — version change implies incompatibility) |
-
-## Testing Strategy
-
-### Unit Tests
-
-- `workspace-session.test.ts`: Verify `buildWorkspaceSessionPayload` includes SSH fields when connections are active and omits them when none are
-- `workspace-session-schema.test.ts`: Verify schema parses sessions with/without new optional fields
-- `terminals.test.ts`: Verify `reconnectPersistedTerminals` processes SSH-backed tabs when connection is active and skips when not
-
-### Integration Tests
-
-- `store-session-cascades.test.ts`: Extend existing local daemon reattach test suite (lines 660-960) to cover SSH-backed tabs
-- `terminal-restart-persistence.spec.ts`: Add E2E scenario for SSH terminal restore
-
-### Manual Test Plan
-
-1. Connect to SSH target with 2+ terminal tabs running long processes
-2. Quit Orca
-3. Relaunch within grace window → verify SSH reconnects, terminals show scrollback, processes still running
-4. Quit Orca, wait past grace window, relaunch → verify SSH reconnects, terminals show "session expired" and spawn fresh shells
-5. Quit Orca with passphrase-protected key → verify tabs show "Waiting for connection" overlay, focus a tab → verify passphrase dialog, enter passphrase → verify terminal restores
-6. Kill Orca (force quit) → verify no crash on next launch (no session saved, clean fallback)
-
-## Files to Modify
-
-| File | Change |
-|------|--------|
-| `src/shared/types.ts` | Add `activeConnectionIdsAtShutdown`, `remoteSessionIdsByTabId` to `WorkspaceSessionState` |
-| `src/shared/ssh-types.ts` | Add `relayGracePeriodSeconds` and `lastRequiredPassphrase` to `SshTarget` |
-| `src/shared/workspace-session-schema.ts` | Add Zod schemas for new fields |
-| `src/main/providers/ssh-pty-provider.ts` | Modify `spawn()` to detect `sessionId`, call `pty.attach` with try/catch fallback to `pty.spawn` |
-| `src/main/providers/types.ts` | Add `sessionExpired?: boolean` to `PtySpawnResult` |
-| `src/main/ipc/ssh-relay-helpers.ts` | Wire `onReplay` in `wireUpSshPtyEvents()` to forward replay data via dedicated `pty:replay` IPC channel |
-| `src/preload/index.ts` | Add `pty.onReplay` binding for the new `pty:replay` IPC channel |
-| `src/renderer/src/lib/pty-dispatcher.ts` | Add `pty:replay` handler that routes through replay-guarded `onReplayData` callback |
-| `src/main/ipc/ssh.ts` | Set `lastRequiredPassphrase` on target after successful `ssh:connect` based on whether credential prompt was triggered |
-| `src/renderer/src/lib/workspace-session.ts` | Add `sshConnectionStates`, `repos`, `worktreesByRepo` to snapshot; build `remoteSessionIdsByTabId` from renderer state |
-| `src/renderer/src/App.tsx` | Add SSH reconnect pass (eager + deferred) before `reconnectPersistedTerminals()` |
-| `src/renderer/src/store/slices/terminals.ts` | Remove SSH skip gate; merge remote session IDs into pending reconnect map; add `deferredSshReconnectTargets` state + actions |
-| `src/main/ssh/ssh-relay-deploy.ts` | Pass configurable grace time to relay |
-| `src/renderer/src/components/settings/SshTargetForm.tsx` | Add grace period setting UI |
diff --git a/docs/design/persist-task-source-preference.md b/docs/design/persist-task-source-preference.md
deleted file mode 100644
index d3ae54027bf..00000000000
--- a/docs/design/persist-task-source-preference.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# Design: Persist Task Source Preference (GitHub / Linear)
-
-## Problem
-
-The Tasks button in the sidebar always defaults to GitHub when clicked without an explicit source. If a user switches to Linear inside the Task page, that choice is lost when they navigate away and return. Users who primarily use Linear must switch every time.
-
-## Goal
-
-Remember which task source (GitHub or Linear) the user last selected and default to it the next time they open the Tasks page without an explicit source override.
-
-## Current Behavior
-
-1. **SidebarNav.tsx** — The main Tasks button calls `openTaskPage()` with no arguments. The small GitHub/Linear icons call `openTaskPage({ taskSource: 'github' })` or `openTaskPage({ taskSource: 'linear' })` respectively.
-
-2. **ui.ts (store)** — `openTaskPage(data = {})` stores `data` into `taskPageData`. No `taskSource` field is persisted.
-
-3. **TaskPage.tsx (line 597)** — Initializes source with `useState<TaskSource>(pageData.taskSource ?? 'github')`. The hardcoded `'github'` fallback is the root cause.
-
-4. **TaskPage.tsx (line 1259)** — In-page source toggle calls `setTaskSource(source.id)` — local state only, never persisted.
-
-## Proposed Solution
-
-Piggyback on the existing `GlobalSettings` persistence pattern already used by `defaultTaskViewPreset` and `defaultRepoSelection`.
-
-### Changes
-
-#### 1. `src/shared/types.ts` — Add setting field
-
-Add `defaultTaskSource: 'github' | 'linear'` to the `GlobalSettings` type, alongside the existing `defaultTaskViewPreset` field (~line 818). Use the inline union (matching the existing `taskPageData` pattern in `ui.ts`) rather than importing the file-local `TaskSource` alias from TaskPage.
-
-#### 1b. `src/shared/constants.ts` — Add default value
-
-Add `defaultTaskSource: 'github'` to the `GlobalSettings` defaults object (adjacent to `defaultTaskViewPreset: 'all'` ~line 158).
-
-#### 2. `src/renderer/src/components/TaskPage.tsx` — Read and write the preference
-
-**Read (line 597):** Change the fallback from the hardcoded `'github'` to the persisted setting:
-
-```ts
-// Before
-const [taskSource, setTaskSource] = useState<TaskSource>(pageData.taskSource ?? 'github')
-
-// After
-const defaultTaskSource = settings?.defaultTaskSource ?? 'github'
-const [taskSource, setTaskSource] = useState<TaskSource>(pageData.taskSource ?? defaultTaskSource)
-```
-
-**Sync effect (after line 606):** `settings` may be `null` on first render (async hydration). Add a sync effect so the persisted preference applies once settings arrive, mirroring the existing `pageData.taskSource` sync pattern on lines 602-606:
-
-```ts
-// Why: settings load asynchronously — the useState initializer may
-// capture null settings on fast navigation. Sync once settings arrive,
-// but only when no explicit source was passed via sidebar icon click.
-useEffect(() => {
-  if (!pageData.taskSource && settings?.defaultTaskSource) {
-    setTaskSource(settings.defaultTaskSource)
-  }
-}, [settings?.defaultTaskSource, pageData.taskSource])
-```
-
-**Write (line 1259):** When the user toggles the source inside the page, persist the choice:
-
-```ts
-// Before
-onClick={() => setTaskSource(source.id)}
-
-// After
-onClick={() => {
-  setTaskSource(source.id)
-  void updateSettings({ defaultTaskSource: source.id }).catch(() => {
-    toast.error('Failed to save default task source.')
-  })
-}}
-```
-
-This mirrors the exact pattern used by `handleSetDefaultTaskPreset` (line 859-868).
-
-#### 3. Settings initialization / migration
-
-Wherever `GlobalSettings` defaults are constructed (the main process settings loader), add `defaultTaskSource: 'github'` so existing users get the current behavior with no migration needed. The field is optional in the type — missing means `'github'`.
-
-### No changes needed
-
-- **SidebarNav.tsx** — No changes. The main Tasks button continues to call `openTaskPage()` with no `taskSource`. The explicit GitHub/Linear icons continue to pass their source. TaskPage handles the default resolution.
-- **ui.ts store** — No changes. `taskPageData` remains ephemeral. The preference is a setting, not UI state.
-- **Prefetch logic** — The prefetch in `openTaskPage` and `SidebarNav` only warms GitHub work items. This is fine — Linear fetches are fast and don't benefit from the same prefetch pattern. Optionally, we could skip the GitHub prefetch when the saved source is Linear, but that's a separate optimization.
-
-## Behavior Matrix
-
-| Action | Result |
-|---|---|
-| Click main Tasks button (no saved pref) | Opens GitHub (backward-compatible default) |
-| Click main Tasks button (saved pref = linear) | Opens Linear |
-| Click GitHub icon in sidebar | Opens GitHub (does not change saved preference) |
-| Click Linear icon in sidebar | Opens Linear (does not change saved preference) |
-| Toggle source inside TaskPage | Switches view, saves new preference |
-| Fresh install / no setting | Defaults to `'github'` |
-
-## Scope
-
-- ~20 lines of code across 3 files (`types.ts`, `constants.ts`, `TaskPage.tsx`)
-- No new IPC channels
-- No migrations
-- No UI changes — only behavior change is remembering the last choice
-
-## Resolved Questions
-
-1. **Should clicking the sidebar GitHub/Linear icons also persist the preference?** No — sidebar icons are pure navigation ("go to GitHub tasks" / "go to Linear tasks"). Persisting from a one-off exploratory click would surprise users. Only the in-page toggle persists, keeping the mental model clean: sidebar icons = navigate, in-page toggle = set preference.
-
-2. **Should we skip GitHub prefetch when saved source is Linear?** Deferred to a follow-up. The prefetch is cheap and doesn't hurt.
diff --git a/docs/design/share-text-search.md b/docs/design/share-text-search.md
deleted file mode 100644
index 63f857da90b..00000000000
--- a/docs/design/share-text-search.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# Design: Share Text Search Logic Between Local Main and SSH Relay
-
-**Branch:** `fix-ssh-keywords-search`
-**Status:** Draft
-
-## Problem
-
-The right-sidebar keywords search (`fs:search`) and the Cmd+P quick-open file search historically shared no code between the local main process and the SSH relay. Each side reinvented: rg argument construction, rg `--json` stdout parsing, the git-grep fallback, the submatch regex, the `SearchFileResult` accumulator, and the "kill previous search on new query" logic.
-
-This drift already caused one user-visible bug: the relay's `searchWithRg` in `src/relay/fs-handler-utils.ts:139` uses `execFile('rg', ..., { maxBuffer: 50 * 1024 * 1024 })`. `execFile` buffers stdout internally and kills the child when `maxBuffer` is exceeded, even when `data` listeners are attached. Under rg's `--json` output (one verbose JSON object per match), 50MB fills well before the match cap in large folders. The `child.once('error', () => resolveOnce())` then silently resolves with whatever was accumulated — users see "some files can't be found" with no error.
-
-The local handler at `src/main/ipc/filesystem.ts:402` uses `wslAwareSpawn` (plain `spawn`) and has never had this bug. The two paths must not be allowed to drift again.
-
-## Scope
-
-**In scope:**
-- Extract rg + git-grep search logic into `src/shared/text-search.ts`, matching the pattern already established by `src/shared/quick-open-filter.ts` for listFiles.
-- Remove the `execFile`/`maxBuffer` footgun from the relay path.
-- Unify the accumulator, truncation semantics, and submatch regex construction.
-
-**Out of scope:**
-- Changing the `fs.search` request shape or existing `SearchResult`/`SearchOptions` fields.
-- Adding new search features (multiline, semantic, etc).
-- Changing how quick-open lists files (already shared via `quick-open-filter.ts`).
-- Re-homing WSL path translation — that stays in the local main process; the relay never sees WSL paths.
-
-## Existing Code Map
-
-| Concern | Local (main) | Remote (relay) |
-|---|---|---|
-| rg `--json` run + parse | `src/main/ipc/filesystem.ts:286-441` (inline in IPC handler) | `src/relay/fs-handler-utils.ts:78-231` (`searchWithRg`) |
-| git-grep fallback | `src/main/ipc/filesystem-search-git.ts:43-220` (`searchWithGitGrep`) | `src/relay/fs-handler-git-fallback.ts:140-297` (`searchWithGitGrep`) |
-| rg availability check | `src/main/ipc/rg-availability.ts` (`checkRgAvailable`) | `src/relay/fs-handler-utils.ts:241-260` (`checkRgAvailable`) |
-| rg arg construction | inline in filesystem.ts | inline in fs-handler-utils.ts |
-| git-grep arg construction | inline in filesystem-search-git.ts | inline in fs-handler-git-fallback.ts |
-| Submatch regex | `filesystem-search-git.ts:115-119` | `fs-handler-git-fallback.ts:200-204` |
-| Accumulator (fileMap, totalMatches, truncated) | duplicated in all four files | duplicated in all four files |
-| Relative-path normalization | `normalizeRelativePath` (collapses `\\`/`/`, strips leading slashes) | plain `.replace(/\\/g, '/')` |
-| git-grep signature | `searchWithGitGrep(rootPath, args, maxResults)` (maxResults positional) | `searchWithGitGrep(rootPath, query, opts)` (maxResults inside opts) |
-| Process spawn | `wslAwareSpawn` (local) / `gitSpawn` (local) | `execFile` (rg, buggy) / `spawn` (git) |
-
-Net duplicate: ~400 lines across four files that do nearly the same thing.
-
-## Design
-
-### New module: `src/shared/text-search.ts`
-
-Pure, IO-agnostic helpers. No Electron, no child_process, no fs. Mirrors `quick-open-filter.ts` — the caller owns process execution and transport-specific path quirks.
-
-```ts
-// Types (re-exported from shared/types or defined here)
-export type SearchAccumulator = {
-  fileMap: Map<string, SearchFileResult>
-  totalMatches: number
-  truncated: boolean
-}
-
-export function createAccumulator(): SearchAccumulator
-
-// ── rg ─────────────────────────────────────────────────────────────
-// Returns the full argv including '--', query, and target. Both callers
-// pass `rootPath` unchanged as the target — the local side does NOT
-// translate the target to a WSL-native path. WSL only affects the
-// invocation (via `wslAwareSpawn`) and the *output* paths rg emits,
-// which the caller translates back via `transformAbsPath` below.
-export function buildRgArgs(
-  query: string,
-  target: string,
-  opts: SearchOptions
-): string[]
-
-// Ingest one rg --json stdout line. Mutates `acc`. Returns 'continue'
-// or 'stop' (stop = totalMatches hit maxResults). Takes an optional
-// path transform so the local caller can apply WSL translation.
-export function ingestRgJsonLine(
-  line: string,
-  rootPath: string,
-  acc: SearchAccumulator,
-  maxResults: number,
-  transformAbsPath?: (p: string) => string
-): 'continue' | 'stop'
-
-// ── git grep ───────────────────────────────────────────────────────
-// Also owns include/exclude glob → git pathspec translation
-// (`toGitGlobPathspec`), which today is duplicated inline in both
-// `filesystem-search-git.ts` and `fs-handler-git-fallback.ts`.
-export function buildGitGrepArgs(
-  query: string,
-  opts: SearchOptions
-): string[]
-
-// Build the submatch regex used to locate column positions within a
-// matched line (git grep only reports the first hit per line).
-export function buildSubmatchRegex(
-  query: string,
-  opts: { useRegex?: boolean; wholeWord?: boolean; caseSensitive?: boolean }
-): RegExp
-
-export function ingestGitGrepLine(
-  line: string,
-  rootPath: string,
-  submatchRegex: RegExp,
-  acc: SearchAccumulator,
-  maxResults: number
-): 'continue' | 'stop'
-
-// ── finalize ───────────────────────────────────────────────────────
-export function finalize(acc: SearchAccumulator): SearchResult
-```
-
-### What stays environment-specific
-
-| Stays local | Stays in relay |
-|---|---|
-| `wslAwareSpawn`, `gitSpawn` | plain `spawn` |
-| `parseWslPath` / `toWindowsWslPath` transform passed to `ingestRgJsonLine` | no-op transform |
-| `activeTextSearches` kill-on-new-query map keyed by `sender.id` | single-search-at-a-time per client (already one channel) |
-| `resolveAuthorizedPath` | `context.validatePathResolved` |
-| `checkRgAvailable` wrapping `wslAwareSpawn` (accepts a `searchPath` for WSL resolution) | `checkRgAvailable` wrapping plain `execFile` (no WSL) |
-
-### Call sites after refactor
-
-**`src/main/ipc/filesystem.ts`** shrinks from ~180 lines of search logic to ~40:
-```
-const rgAvailable = await checkRgAvailable(rootPath)
-if (!rgAvailable) return searchWithGitGrep(rootPath, args, maxResults)
-
-const acc = createAccumulator()
-const rgArgs = buildRgArgs(args.query, rootPath, args)
-const child = wslAwareSpawn('rg', rgArgs, { cwd: rootPath, stdio: ... })
-activeTextSearches.get(searchKey)?.kill()
-activeTextSearches.set(searchKey, child)
-// stream stdout → ingestRgJsonLine(line, rootPath, acc, maxResults, wslTransform)
-// on 'stop' → child.kill()
-// on close/error → resolve(finalize(acc))
-// timeout → set acc.truncated = true, child.kill()
-```
-
-**`src/main/ipc/filesystem-search-git.ts`** becomes a thin wrapper around `buildGitGrepArgs` + `ingestGitGrepLine`. File drops from 220 → ~80 lines.
-
-**`src/relay/fs-handler.ts::search`** and the relay's rg/git-grep helpers: identical shape to the local caller, minus the WSL transform and `activeTextSearches` tracking. `searchWithRg` in `fs-handler-utils.ts` is deleted; its callers inline the spawn loop or we keep a thin relay-side wrapper (`src/relay/fs-handler-search.ts`).
-
-**Critical:** the relay's rg caller uses `spawn`, not `execFile`. This alone fixes the reported bug.
-
-### Signature + path normalization (unified)
-
-The shared helpers settle two small existing asymmetries:
-
-- git-grep callers in main and relay take `maxResults` differently today (third positional arg vs. folded into opts). The shared `buildGitGrepArgs` / `ingestGitGrepLine` take `maxResults` on the accumulator-ingest side only, so callers no longer invent their own shape.
-- Relative-path normalization is unified on `normalizeRelativePath` (collapse mixed separators, strip leading slashes). The relay's plain `replace(/\\/g, '/')` is replaced, removing a drift seam that would surface the first time someone passed a path with a leading slash through the relay.
-
-### Truncation semantics (unified)
-
-One rule: `acc.truncated = true` if and only if rg/git-grep would have emitted more matches after we stopped consuming. Specifically:
-
-- `maxResults` reached while processing submatches for a match record → truncated.
-- Kill-timeout fires → truncated.
-- rg/git-grep exits with non-zero status → *not* truncated; this is a clean "no results or early termination" path. (Matches current local behavior.)
-
-This removes the existing inconsistency where the relay's `execFile` maxBuffer overflow silently returned `truncated: false` despite dropping matches.
-
-**Ordering invariant (do not break during migration).** Today the caller flips `truncated = true` synchronously in the same tick it calls `child.kill()`, before the `close` handler resolves the promise. The shared module must preserve that ordering: `ingestRgJsonLine` / `ingestGitGrepLine` mutate `acc.truncated` synchronously when they return `'stop'`, and the caller must kill the child *after* that mutation. If a naive refactor moves the kill inside the helper but leaves `truncated` setting in the caller — or vice versa — a `close` event can resolve the promise with `truncated: false` even though matches were dropped. This is the exact silent-truncation footgun the refactor is meant to kill; regressing it reintroduces the original bug in a harder-to-spot form.
-
-### Regex parity
-
-`buildSubmatchRegex` centralizes the "escape literal query, wrap in `\b` for whole-word, add `gi` flags" logic currently in two files. Includes the zero-length-match guard (`matchRegex.lastIndex++` when `m[0].length === 0`) that the relay version also has but that would regress if one side is touched without the other.
-
-## Migration Plan
-
-1. **Land the shared module with tests.** Unit tests live at `src/shared/text-search.test.ts`, modeled on `src/shared/quick-open-filter.test.ts`. Cover: arg construction (every flag combination), rg JSON line ingestion (match/non-match/malformed/multi-submatch/maxResults boundary), git-grep line parsing (null-byte delimiter, colons in filenames, unicode, zero-length regex), and finalize shape.
-
-2. **Migrate the local path.** Replace the inline rg loop in `filesystem.ts` and rewrite `filesystem-search-git.ts` to use the shared helpers. Existing `filesystem-list-files.test.ts` + `filesystem.test.ts` catch regressions; add a test specifically for the `execFile` → `spawn` equivalence (large result set that would have overflowed 50MB under `execFile`).
-
-3. **Migrate the relay path.** Replace `searchWithRg` (`execFile` → `spawn`) and consolidate `fs-handler-git-fallback.ts`'s search half. Delete `searchWithRg` and the relay's git-grep duplicate once the last caller is gone.
-
-4. **Drift guard.** Add a short comment at the top of `shared/text-search.ts` pointing to this design doc and naming both call sites. The existing comment at the top of `shared/quick-open-filter.ts` is the template.
-
-## Non-goals / Explicit Non-changes
-
-- **Not merging `checkRgAvailable`.** Both versions already agreed (no caching — see the "Why no cache" comments in `src/main/ipc/rg-availability.ts` and `src/relay/fs-handler-utils.ts`), but they wrap different spawn primitives: the local side runs through `wslAwareSpawn` and accepts a `searchPath` so WSL distro resolution works, while the relay uses plain `execFile`. Sharing would force one side to import the other's spawn wrapper. Two thin files, one contract.
-- **Not unifying spawn.** `wslAwareSpawn` and `gitSpawn` carry WSL and git-auth concerns the relay has no business with.
-- **Not changing the request shape or existing result fields.** `SearchOptions` stays as-is, and
-  `SearchResult` keeps the same required fields. Long-line clamping may add optional display-only
-  coordinates to a match so the sidebar can highlight bounded snippets without corrupting the
-  source `column`/`matchLength` used for editor reveal.
-- **Not touching the renderer.** `right-sidebar/Search.tsx` and `QuickOpen.tsx` are unchanged.
-
-## Risks
-
-- **Test coverage for relay search is thin.** Current tests exercise the local path. Plan: port the new shared-module tests plus add a relay-specific integration check (`fs-handler` test that streams a large mock rg stdout through the `spawn`-based loop to confirm no drop).
-- **Behavioral parity is not 1:1 today.** The local path has WSL translation; the relay does not. Parity we're preserving is output *shape*, not output *paths*. Tests must not assume absolute-path equality across the two callers.
-- **Kill-previous-search is only local.** The relay can process multiple concurrent `fs.search` requests over the mux. If that becomes a problem, add relay-side cancellation later — it is not part of this refactor.
diff --git a/docs/drag-drop-files-ssh.md b/docs/drag-drop-files-ssh.md
deleted file mode 100644
index 4d62efe9228..00000000000
--- a/docs/drag-drop-files-ssh.md
+++ /dev/null
@@ -1,317 +0,0 @@
-# Design Document: Drag-and-Drop File Import over SSH
-
-## 1. Overview
-
-Orca's file explorer supports dragging external files from the OS into the explorer when working with a local worktree (see `docs/file-explorer-external-drop.md`). However, this feature does not work when connected to an SSH remote. The `fs:importExternalPaths` IPC handler uses Node's local filesystem APIs (`copyFile`, `lstat`, `readdir`, `mkdir`) and has no `connectionId` parameter — the renderer never passes one, and the main process has no code path to route import operations through the SSH filesystem provider.
-
-This document proposes extending the import flow to support SSH connections, enabling users to drop local files onto the explorer and have them uploaded to the remote server.
-
-**Origin:** User feedback — [Slack thread](https://stablygroup.slack.com/archives/C0ASMDT6LQZ/p1777530155421009), [GitHub #200](https://github.com/stablyai/orca-internal/issues/200).
-
-## 2. Current Architecture
-
-### 2.1 Local Import Path
-
-The existing local import flow:
-
-1. **Preload** intercepts native OS `drop` events, extracts `FileList` paths, resolves the destination directory from `data-native-file-drop-dir` DOM markers, and emits one IPC event: `{ target: 'file-explorer', paths, destinationDir }`.
-2. **Renderer** (`useFileExplorerImport.ts`) receives the event and calls `window.api.fs.importExternalPaths({ sourcePaths, destDir })`.
-3. **Main** (`filesystem-mutations.ts`) runs the import: authorize paths → `lstat` validation → symlink pre-scan → deconflict names → `copyFile`/`recursiveCopyDir`.
-
-All of this is local filesystem only. No `connectionId` is threaded anywhere.
-
-### 2.2 SSH Filesystem Provider
-
-The `SshFilesystemProvider` communicates with a relay binary on the remote host via a JSON-RPC multiplexer (`SshChannelMultiplexer`). It supports:
-
-- `readDir`, `readFile`, `writeFile`, `stat`, `deletePath`, `createFile`, `createDir`, `rename`, `copy`, `realpath`, `search`, `listFiles`, `watch`
-
-`writeFile` accepts a `string` content parameter — it is text-only and unsuitable for binary files (images, compiled assets, etc.).
-
-`copy` is remote-to-remote — it tells the relay to copy a file on the remote side.
-
-### 2.3 Direct SFTP
-
-The codebase already uses direct SFTP for relay deployment (`ssh-relay-deploy-helpers.ts`):
-
-- `uploadFile(sftp, localPath, remotePath)` — streams a local file to the remote via `createReadStream` → `sftp.createWriteStream`.
-- `uploadDirectory(sftp, localDir, remoteDir)` — recursively creates directories and uploads files.
-- `mkdirSftp(sftp, remotePath)` — creates remote directories.
-
-These helpers use `ssh2`'s `SFTPWrapper` obtained from `SshConnection.sftp()`.
-
-### 2.4 Other SSH-Aware Mutations
-
-Other filesystem mutations (`createFile`, `createDir`, `rename`) already accept `connectionId` and route through `getSshFilesystemProvider()`. The import handler is the exception.
-
-### 2.5 System Context
-
-```
-┌──────────────────────────────────────────────────────────┐
-│ Renderer (file-explorer)                                 │
-│  useFileExplorerImport  ──► IPC: fs:importExternalPaths  │
-│    { sourcePaths, destDir, connectionId? }               │
-└──────────────────────┬───────────────────────────────────┘
-                       │
-          ┌────────────▼────────────┐
-          │   Main Process          │
-          │   filesystem-mutations  │
-          │                         │
-          │   connectionId present? │
-          │     ├─ NO  → local fs   │
-          │     │   copyFile / mkdir │
-          │     └─ YES → SFTP       │
-          │         SshConnection   │
-          │           .sftp()       │
-          └──────┬──────────┬───────┘
-                 │          │
-        ┌────────▼──┐  ┌───▼────────────┐
-        │ Local FS  │  │  Remote Host   │
-        │ (source   │  │  (destination  │
-        │  always   │  │   via SFTP)    │
-        │  local)   │  │                │
-        └───────────┘  └────────────────┘
-```
-
-> **Architecture note:** The import handler bypasses `SshFilesystemProvider` and uses `SshConnection.sftp()` directly. This is intentional — the relay's JSON-RPC `fs.writeFile` is text-only and cannot carry binary data without base64 encoding overhead. Future maintainers should not "fix" this to route through the provider.
-
-## 3. Gap Analysis
-
-| Requirement | Local | SSH |
-|---|---|---|
-| Source path validation (`lstat`) | Local `fs.lstat` | Local `fs.lstat` (source is always local) |
-| Symlink pre-scan | Local `fs.readdir` | Local `fs.readdir` (source is always local) |
-| Name deconfliction | Local `fs.lstat` on dest | Remote `stat` via relay/SFTP |
-| File copy | `fs.copyFile` | SFTP stream upload |
-| Directory creation | `fs.mkdir` | SFTP `mkdir` or relay `fs.createDir` |
-| Recursive directory copy | Local `readdir` + `copyFile` | Local `readdir` + SFTP upload per file |
-
-Key insight: **source paths are always local** (they come from the user's OS file manager). Only the destination is remote. This means source validation (lstat, symlink pre-scan) stays unchanged — only the copy-to-destination step needs an SSH path.
-
-## 4. Proposed Design
-
-### 4.1 Strategy: Direct SFTP Upload
-
-Use `ssh2`'s SFTP channel directly from the main process, reusing the existing `uploadFile`/`uploadDirectory`/`mkdirSftp` helpers from `ssh-relay-deploy-helpers.ts`. Do NOT route through the relay's JSON-RPC `fs.writeFile` because:
-
-- `fs.writeFile` is text-only (string content over JSON-RPC).
-- Binary files (images, PDFs, compiled assets) would require base64 encoding + relay-side decode, adding complexity and ~33% bandwidth overhead.
-- The SFTP helpers already exist, are tested, and handle streaming correctly.
-
-### 4.2 IPC Changes
-
-**`api-types.ts`** — Add `connectionId` to the import args:
-
-```ts
-importExternalPaths: (args: {
-  sourcePaths: string[]
-  destDir: string
-  connectionId?: string
-}) => Promise<{ results: ImportItemResult[] }>
-```
-
-**`preload/index.ts`** — Thread `connectionId` through the IPC invoke.
-
-### 4.3 Main-Process Import Handler
-
-Extend the `fs:importExternalPaths` handler in `filesystem-mutations.ts`:
-
-```
-if (connectionId) {
-  → check SSH connection state; if reconnecting, return user-friendly error
-  → guard: if sourcePaths is empty, return { results: [] } immediately
-  → get SshConnection from session registry
-  → open SFTP channel
-  → show indeterminate "Importing files…" toast
-  → try:
-      run SSH import path (4.4)
-    finally:
-      close SFTP channel (guaranteed cleanup)
-      dismiss toast
-else
-  → resolveAuthorizedPath(destDir)
-  → existing local import path (unchanged)
-```
-
-**Implementation constraint — `resolveAuthorizedPath` placement:** The current handler calls `resolveAuthorizedPath(destDir)` unconditionally before any copy work. This must be restructured: move `resolveAuthorizedPath(destDir)` inside the `else` (local) branch. For SSH imports, `destDir` is a remote path that does not exist on the local filesystem, so `resolveAuthorizedPath` will throw. The SSH branch skips local path authorization because remote paths are authorized by the SSH connection boundary itself (see Section 9).
-
-**Connection-state check:** Before attempting `connection.sftp()`, the handler must inspect the connection state. If the connection is in `reconnecting` state, fail early with a toast: _"SSH connection is reconnecting — please try again in a moment."_ This avoids an unhelpful generic "Not connected" SFTP error that gives the user no guidance.
-
-**Empty source paths:** If `sourcePaths` is an empty array, return `{ results: [] }` immediately without opening an SFTP channel. This avoids unnecessary channel overhead for a no-op.
-
-**SFTP channel cleanup:** The SFTP channel opened for the import must be closed on all code paths — success, partial failure, or exception. The handler must use `try/finally` semantics around the upload loop. Note that individual `uploadFile` calls receive the `sftp` handle as a parameter and do not manage its lifecycle; the caller (the import handler) is solely responsible for closing the channel.
-
-**In-progress feedback:** Show an indeterminate "Importing files…" toast when the IPC call begins and dismiss it when the import completes (success or failure). This costs almost nothing to implement and significantly improves the experience on slow connections where network latency makes the drop-to-toast gap noticeable.
-
-### 4.4 SSH Import Pipeline
-
-For each source path in the batch:
-
-1. **Source validation** — unchanged. `lstat` the local source path. Reject symlinks, missing, permission-denied. Pre-scan directories for nested symlinks.
-
-2. **Name deconfliction** — use SFTP `lstat` (not `stat`) on the remote destination to check for collisions, matching the local import's use of `lstat`. This ensures consistent collision semantics: a dangling symlink at the destination is still treated as "name taken." SFTP lstat throws `SSH_FX_NO_SUCH_FILE` (code 2) when the path doesn't exist — use this as the "no collision" signal.
-
-3. **Upload** — for files, use `uploadFile(sftp, localPath, remotePath)`. For directories, use recursive SFTP mkdir + uploadFile. Reuse the existing helpers from `ssh-relay-deploy-helpers.ts` after extracting them to a shared location.
-
-4. **Result reporting** — same per-item `ImportItemResult` schema. The renderer doesn't need to know whether the import went local or SSH.
-
-### 4.5 Accessing the SFTP Channel
-
-The `SshConnection` class already exposes `async sftp(): Promise<SFTPWrapper>`. The import handler needs access to the connection for a given `connectionId`.
-
-Current architecture: `SshRelaySession` owns the connection lifecycle but doesn't directly expose the `SshConnection`. The `getSshFilesystemProvider()` dispatch only returns the `IFilesystemProvider` interface.
-
-Options:
-
-**Option A: Expose `SshConnection` via a session registry.**
-Add a `getSshConnection(connectionId)` function that returns the `SshConnection` from the `SshRelaySession` map. The import handler calls `connection.sftp()` directly.
-
-**Option B: Add an `uploadFile` method to `IFilesystemProvider`.**
-Extend the provider interface with `uploadFile(localPath: string, remotePath: string): Promise<void>` and `uploadDirectory(localDir: string, remoteDir: string): Promise<void>`. The SSH provider implements them via SFTP; the local provider implements them as `copyFile`/`recursiveCopyDir`.
-
-**Recommendation: Option A.** Option B pollutes the provider interface with a local↔remote transfer concern that only applies to import. The relay-based provider should stay focused on remote-side operations. A direct SFTP path from the import handler is simpler and keeps the provider interface clean.
-
-### 4.6 Renderer Changes
-
-**`useFileExplorerImport.ts`** — Pass `connectionId` from the active worktree:
-
-```ts
-const connectionId = getConnectionId(activeWorktreeIdRef.current) ?? undefined
-const { results } = await window.api.fs.importExternalPaths({
-  sourcePaths: paths,
-  destDir: destinationDir,
-  connectionId
-})
-```
-
-This is the only renderer change needed. The rest of the import UX (drag state, highlight, toast, reveal) works identically for local and SSH.
-
-### 4.7 Helper Extraction
-
-Move `uploadFile`, `uploadDirectory`, and `mkdirSftp` from `ssh-relay-deploy-helpers.ts` to a shared module (e.g., `src/main/ssh/sftp-upload.ts`). The relay deploy code imports from the new location. This avoids coupling the import feature to relay deployment internals.
-
-**Async filesystem calls:** The existing `uploadDirectory` uses `readdirSync` and `statSync`, which block the event loop. During extraction, replace these with their async counterparts (`readdir` with `{ withFileTypes: true }` from `fs/promises`). The local import's `recursiveCopyDir` already uses async fs calls and serves as the template for this conversion.
-
-## 5. Symlink Policy
-
-Unchanged from the local import design. Source-side symlinks are rejected before upload begins. The pre-scan uses local `readdir` + `lstat`, which works identically regardless of the destination being local or remote.
-
-## 6. Conflict Policy
-
-Same as local: non-destructive, prompt-free deconfliction. The difference is that collision checks use SFTP `lstat` instead of local `lstat`. Using `lstat` (rather than `stat`) matches the local path's semantics: a symlink at the destination is treated as a collision even if its target doesn't exist.
-
-SFTP lstat error handling:
-
-- `SSH_FX_NO_SUCH_FILE` (status code 2) → no collision, name is available.
-- `SSH_FX_PERMISSION_DENIED` (status code 3) → fail the item.
-- Any other error → fail the item with the error message.
-
-## 7. Performance Considerations
-
-### 7.1 SFTP Channel Lifecycle
-
-Open one SFTP channel per import gesture, not per file. Close it after all items are uploaded using `try/finally` to guarantee cleanup even on partial failure. Opening an SFTP subsystem has ~100ms overhead per channel due to the SSH handshake.
-
-### 7.2 Sequential vs. Parallel Upload
-
-v1: sequential upload (one file at a time). This matches the existing relay deploy behavior and avoids SFTP channel contention. SFTP supports multiple concurrent operations, but managing parallel uploads with error handling and progress adds complexity that isn't needed for v1.
-
-### 7.3 Large File Handling
-
-`uploadFile` uses `createReadStream` → `sftp.createWriteStream`, which streams data rather than buffering entire files into memory. This handles large files without OOM risk.
-
-### 7.4 Network Latency
-
-Unlike local imports, SSH imports are bounded by network throughput. For large drops, the user may see a noticeable delay between the drop gesture and the toast/reveal. v1 includes an indeterminate "Importing files…" toast during the upload to bridge this gap. Granular per-file progress UI is deferred to v2.
-
-## 8. Error Handling
-
-Same per-item error reporting as local imports, plus SSH-specific failures:
-
-- **SSH connection in `reconnecting` state at drop time:** Fail immediately with toast: _"SSH connection is reconnecting — please try again in a moment."_ Do not attempt to open an SFTP channel.
-- **SSH connection lost during upload:** Fail remaining items. Partially uploaded files may be left on the remote — acceptable for v1 since partial files are visible in the explorer and can be deleted manually.
-- **SFTP channel failure:** Fail the entire import. The `finally` block still runs to release the channel handle.
-- **Remote disk full:** SFTP write stream error — fail the affected item.
-- **Permission denied on remote directory:** Fail the affected item.
-
-Toast messages remain the same format:
-
-- `Imported 5 items to ~/project/src`
-- `Imported 4 items to ~/project/src. 1 item was skipped.`
-- `Could not import dropped items`
-- `SSH connection is reconnecting — please try again in a moment`
-
-### 8.1 Data Flow Paths
-
-**Happy path:** Renderer sends `{ sourcePaths: ["/a.txt"], destDir: "/remote/dir", connectionId: "abc" }` → main checks connection state (connected) → opens SFTP → shows "Importing files…" toast → validates source locally → deconflicts name via SFTP stat → uploads via SFTP stream → closes SFTP → dismisses toast → returns `{ results: [{ path: "/remote/dir/a.txt", status: "ok" }] }` → renderer shows success toast and reveals file.
-
-**Empty sourcePaths:** Renderer sends `{ sourcePaths: [], destDir: "/remote/dir", connectionId: "abc" }` → main returns `{ results: [] }` immediately, no SFTP channel opened, no toast shown.
-
-**Nil connectionId (local fallback):** Renderer sends `{ sourcePaths: [...], destDir: "/local/dir" }` → main takes existing local import path unchanged.
-
-**Error — reconnecting:** Renderer sends `{ sourcePaths: [...], destDir: "/remote/dir", connectionId: "abc" }` → main checks connection state → state is `reconnecting` → returns error → renderer shows "SSH connection is reconnecting — please try again in a moment" toast.
-
-**Error — mid-upload failure:** Main opens SFTP → uploads file 1 OK → file 2 throws (e.g., permission denied) → file 2 marked as failed → file 3 continues → SFTP closed in `finally` → toast dismissed → returns mixed results → renderer shows "Imported 2 items … 1 item was skipped."
-
-## 9. Security
-
-- Source paths are still authorized via `authorizeExternalPath()` — unchanged.
-- Destination paths on the remote are not subject to local path authorization (they're on the remote host). The SSH connection itself is the authorization boundary.
-- SFTP operations run under the SSH user's permissions on the remote host.
-
-## 10. Testing
-
-### 10.1 Unit Tests (Main Process)
-
-- SSH import handler routes to SFTP when `connectionId` is present.
-- SSH import handler falls back to local import when `connectionId` is absent.
-- Empty `sourcePaths` array returns `{ results: [] }` without opening an SFTP channel.
-- Reconnecting connection state returns a user-friendly error without attempting SFTP.
-- Name deconfliction works with SFTP stat (mock SFTP stat to simulate collisions).
-- Source-side symlink rejection works identically for SSH imports.
-- SFTP channel is opened once per gesture, not per file.
-- SFTP channel is closed after import completes (success or failure) — verify `finally` cleanup runs even when upload throws.
-- Partial failure (some files succeed, some fail) returns correct per-item results.
-- Indeterminate "Importing files…" toast is shown during upload and dismissed on completion.
-
-### 10.2 Integration Tests
-
-- Drop a single file into an SSH-connected explorer root → file appears on remote.
-- Drop a directory into an SSH-connected explorer → directory tree appears on remote.
-- Drop a file that collides with an existing remote file → deconflicted name used.
-- Drop onto a subdirectory row → file lands in that directory on remote.
-
-### 10.3 Renderer Tests
-
-- `useFileExplorerImport` passes `connectionId` when active worktree has an SSH connection.
-- `useFileExplorerImport` passes `undefined` for `connectionId` when local.
-
-## 11. Implementation Plan
-
-1. **Extract SFTP helpers** — Move `uploadFile`, `uploadDirectory`, `mkdirSftp` from `ssh-relay-deploy-helpers.ts` to `src/main/ssh/sftp-upload.ts`. Update relay deploy imports.
-
-2. **Expose SSH connection accessor** — Add `getSshConnection(connectionId)` to the session registry so the import handler can obtain an SFTP channel.
-
-3. **Add `connectionId` to import IPC** — Update `api-types.ts`, `preload/index.ts`, and the `fs:importExternalPaths` handler signature.
-
-4. **Implement SSH import path** — In `filesystem-mutations.ts` (or a new `filesystem-import-ssh.ts`), add the SSH branch: open SFTP → validate sources locally → deconflict names via SFTP stat → upload via SFTP → close SFTP → return results.
-
-5. **Thread `connectionId` in renderer** — Update `useFileExplorerImport.ts` to pass `connectionId` from the active worktree.
-
-6. **Tests** — Unit tests for the SSH import path, integration tests for end-to-end flow.
-
-## 12. Complexity Assessment
-
-**Estimated difficulty: Medium.**
-
-- The hardest part is already done — the local drag-drop UX, preload routing, and renderer import hook all exist and work.
-- SFTP upload helpers exist and are proven in relay deployment.
-- The main new work is: (a) wiring `connectionId` through the import IPC, (b) implementing SFTP-based name deconfliction, (c) connecting the import handler to the SSH connection's SFTP channel.
-- No relay protocol changes needed. No new renderer UI. No new preload routing.
-- Risk areas: SFTP error handling edge cases, ensuring the SFTP channel is cleaned up on all code paths, and testing against real SSH servers.
-
-## 13. Open Questions
-
-- Whether v2 should show granular per-file upload progress for SSH imports (v1 includes an indeterminate toast; per-file progress would require tracking bytes transferred).
-- Whether partial uploads should be cleaned up on failure (currently left on remote).
-- Whether to support drag-and-drop *from* the SSH explorer to the local OS (reverse direction).
diff --git a/docs/file-explorer-external-drop.md b/docs/file-explorer-external-drop.md
deleted file mode 100644
index dc3c362a3ed..00000000000
--- a/docs/file-explorer-external-drop.md
+++ /dev/null
@@ -1,374 +0,0 @@
-# Design Document: External File Drop Import in File Explorer
-
-## 1. Overview
-
-Orca's file explorer already supports drag-and-drop for moving items that originate inside the explorer, but it does not support dropping files or folders from the OS into the explorer to add them to the active worktree.
-
-This document proposes a native file-drop import flow that works in both places users expect:
-
-- Dropping onto the explorer background imports into the worktree root.
-- Dropping onto a directory row imports into that directory.
-- Dropping onto a file row imports into that file's parent directory.
-
-The design follows the same high-level split used by VS Code: external/native drops are handled as imports, while in-explorer drags remain move operations. Superset is a useful reference for renderer-side drag-state handling: it treats `Files` drags as a distinct UX path with explicit hover state instead of trying to force them through the in-app DnD codepath.
-
-## 2. Goals
-
-- Let users drop external files and folders from Finder/Explorer/Linux file managers into Orca's file explorer.
-- Support root-level drops and nested directory drops.
-- Preserve the current in-explorer move behavior for `text/x-orca-file-path`.
-- Keep the implementation cross-platform across macOS, Linux, and Windows.
-- Avoid destructive overwrites by default.
-- Keep the import path performant for large multi-file and directory drops.
-
-## 3. Non-Goals
-
-- No drag-out export from Orca to the OS.
-- No cross-worktree move semantics for external drops. External drops always copy/import.
-- No full upload/progress manager in v1.
-- No overwrite prompt flow in v1.
-
-## 4. Current State
-
-Today the relevant pieces are split across three layers:
-
-- `src/renderer/src/components/right-sidebar/useFileExplorerDragDrop.ts` and `FileExplorerRow.tsx` handle only internal explorer drags via `text/x-orca-file-path`, and complete the action with `window.api.fs.rename(...)`.
-- `src/preload/index.ts` intercepts native OS drops before React sees them and classifies them only as `editor` or `terminal`.
-- `src/renderer/src/hooks/useGlobalFileDrop.ts` opens dropped files in the editor, while terminal panes insert dropped paths into the active PTY.
-
-That means the explorer never receives a native-drop route, and there is no filesystem API that copies a dropped file tree into the worktree.
-
-## 5. Reference Behavior
-
-### 5.1 VS Code
-
-VS Code explicitly separates:
-
-- native drag/drop import (`NativeDragAndDropData` -> `ExternalFileImport.import(...)`)
-- in-explorer drag/drop move/copy (`handleExplorerDrop(...)`)
-
-The important design takeaway is not the exact API shape. It is that external drops resolve a destination directory first and then run an import pipeline instead of trying to reuse the internal move path.
-
-### 5.2 Superset
-
-Superset's desktop app uses renderer-side `onDragOver` / `onDragLeave` / `onDrop` handling keyed off `e.dataTransfer.types.includes("Files")`, with explicit hover UI and defensive `getPathForFile(...)` handling.
-
-The useful precedent for Orca is the UX structure:
-
-- treat native file drags as their own interaction mode
-- show a clear copy/import affordance
-- clear drag state reliably on `drop` and `dragend`
-
-## 6. Proposed UX
-
-When the user drags external files over the file explorer:
-
-- The explorer root shows a copy/import highlight when the drop target is the worktree root.
-- Directory rows highlight as valid copy targets.
-- Hovering a collapsed directory during a native drag auto-expands it after the same delay used for internal moves.
-- The cursor uses `dropEffect = "copy"`.
-
-The explorer root drop surface must remain available even when the tree is empty, still loading, or showing a read error. In v1, the right sidebar should keep rendering a root-level explorer container for those states so users can still drop into the worktree root instead of losing the target entirely.
-
-This requires restructuring the current early-return branches in `FileExplorer.tsx`. Today the component returns dedicated loading / error / empty placeholders before it renders the shared `ScrollArea`, so adding dataset markers only to the existing populated-tree path would still leave root import unavailable in those states.
-
-When the user drops:
-
-- On explorer background: import into the worktree root.
-- On directory row: import into that directory.
-- On file row: import into the parent directory.
-
-In v1, "inside the folder" means dropping on that folder's row. Orca's explorer is a virtualized flat list rather than nested DOM containers, so arbitrary whitespace under a folder's rendered children is not treated as a separate interior drop zone.
-
-After completion:
-
-- Refresh the destination directory.
-- Reveal and flash the first imported path.
-- Show a summary toast, for example `Imported 3 items to src/components`.
-
-The explorer should not auto-open dropped files in v1. Dropping into the explorer is an "add here" action, not an "open in editor" action.
-
-## 7. Architecture
-
-### 7.1 Extend Native Drop Routing
-
-Add a third native-drop target in preload:
-
-- `editor`
-- `terminal`
-- `file-explorer`
-
-The current `getNativeFileDropTarget(...)` helper in `src/preload/index.ts` should become a richer resolver that walks `event.composedPath()` and extracts:
-
-- the high-level target kind
-- the nearest explorer destination directory, if any
-
-The explorer DOM should expose two dataset markers:
-
-- `data-native-file-drop-target="file-explorer"` on the root scroll area
-- `data-native-file-drop-dir="<absolute dir path>"` on the root container and on each row drop target
-
-Routing must fail closed for explorer drops. If preload sees `data-native-file-drop-target="file-explorer"` but cannot resolve a `destinationDir`, it should reject the gesture and emit no fallback `editor` drop event.
-
-Why this is necessary: the preload layer consumes native OS `drop` events before React can read filesystem paths. If preload does not capture the destination directory at drop time, the renderer can no longer tell whether the user meant "root" or "inside this folder".
-
-The relayed payload should become:
-
-```ts
-type NativeFileDropEvent =
-  | { paths: string[]; target: 'editor' }
-  | { paths: string[]; target: 'terminal' }
-  | { paths: string[]; target: 'file-explorer'; destinationDir: string }
-```
-
-Preload/main must emit exactly one native-drop event per drop gesture.
-
-Why: the preload layer already has the full `FileList`. Re-emitting one IPC message per path and asking the renderer to reconstruct the gesture via timing would be both fragile and slower under large drops.
-
-**Impact on existing listeners:**
-Because the relay payload changes from `{ path: string }` to `{ paths: string[] }`, existing `ui.onFileDrop` handlers in:
-- `src/renderer/src/hooks/useGlobalFileDrop.ts` (editor target)
-- `src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.ts` (terminal target)
-must be updated to loop over the `paths` array.
-
-### 7.2 Renderer Explorer Drag State
-
-`useFileExplorerDragDrop(...)` should handle two drag families:
-
-- internal Orca drags: `text/x-orca-file-path`
-- external/native drags: `Files`
-
-The existing move logic stays unchanged for internal drags.
-
-For native drags, the hook should:
-
-- accept `Files` in root and row `onDragOver`
-- set copy affordance and hover state
-- reuse the existing row auto-expand timer for directory targets
-- clear root/row highlight on `dragleave`, `dragend`, and after the import event fires
-
-The hook should use the same explicit destination model as the drop router:
-
-- root background -> worktree root
-- directory row -> that directory
-- file row -> file's parent directory
-
-This follows Superset's approach of treating external drags as a distinct renderer interaction, even though the final import action is triggered from the preload-delivered event instead of the React `drop` handler.
-
-### 7.3 New Filesystem Import IPC
-
-Add a dedicated filesystem mutation:
-
-```ts
-window.api.fs.importExternalPaths({
-  sourcePaths: string[],
-  destDir: string
-}): Promise<{
-  results: Array<
-    | {
-        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
-      }
-  >
-}>
-```
-
-Implementation lives alongside the existing filesystem mutations in `src/main/ipc/filesystem-mutations.ts`.
-
-Behavior:
-
-1. Authorize every source path with the existing external-path mechanism.
-2. Validate every source path from its unresolved path using `lstat(...)` before any canonicalization so top-level symlinks are rejected instead of being silently dereferenced by `realpath(...)`.
-3. Resolve `destDir` through `resolveAuthorizedPath(...)`.
-4. Copy, never rename.
-5. Support both files and directories.
-6. Return per-top-level-item results so the renderer can produce correct summary UX for success, partial success, and renames.
-
-### 7.4 Copy Semantics
-
-Use recursive copy semantics in the main process:
-
-- File source: copy file bytes.
-- Directory source: create the top-level directory, then recursively copy descendants.
-
-This should be implemented in Node-side filesystem code, not in the renderer, so path authorization and cross-platform behavior stay centralized.
-
-### 7.5 Atomic Import Rules
-
-Directory imports must be atomic at the top-level item boundary.
-
-Required behavior:
-
-- Before importing a dropped directory, pre-scan that directory tree for disallowed entries such as symlinks.
-- Source validation must inspect the dropped path itself with `lstat(...)` before calling helpers like `resolveAuthorizedPath(...)` that canonicalize existing paths.
-- If the pre-scan finds a disallowed entry, skip that top-level source entirely.
-- Do not create any destination files or directories for a top-level source that fails pre-scan.
-
-Why: if recursive copy discovers a symlink halfway through, Orca would otherwise leave a partially imported tree behind. Pre-scan is the preferred v1 design because it is simpler and more performant than temp-directory staging while still avoiding partial output.
-
-## 8. Conflict Policy
-
-v1 should be non-destructive and prompt-free:
-
-- Never overwrite an existing file or folder.
-- If a top-level dropped item collides with an existing name in `destDir`, generate a unique sibling name before copying.
-
-Examples:
-
-- `logo.png` -> `logo copy.png`
-- `logo.png` -> `logo copy 2.png`
-- `assets/` -> `assets copy/`
-
-This matches Orca's current bias toward safe filesystem mutations and avoids blocking the drop on a modal confirmation flow.
-
-Top-level deconfliction is sufficient for dropped directories because the copy target becomes a newly created directory. Once that top-level directory name is unique, nested collisions disappear inside that subtree.
-
-If multiple dropped items collide with each other, the same deconfliction pass should run against the union of:
-
-- already existing destination entries
-- names reserved earlier in the same import batch
-
-The result payload must preserve whether each successful import was renamed by deconfliction.
-
-## 9. Symlink Policy
-
-Reject symlinks in v1.
-
-Rationale:
-
-- Symlink copy semantics differ across platforms.
-- Copying a symlink literal can produce confusing repository state.
-- Following symlinks can escape the dropped subtree and import unintended content.
-
-If a dropped source or descendant is a symlink, fail that top-level item and surface a toast summary such as `Skipped 1 item containing symlinks`.
-
-## 10. Renderer Flow
-
-The renderer-side import path should be:
-
-1. `window.api.ui.onFileDrop(...)` receives one gesture-scoped event: `{ target: 'file-explorer', paths, destinationDir }`.
-2. The explorer calls `window.api.fs.importExternalPaths({ sourcePaths: paths, destDir: destinationDir })`.
-3. On success or partial success, it calls `refreshDir(destinationDir)` once.
-4. It reveals and flashes the first successfully imported destination path, if any, by routing through Orca's existing expansion-aware reveal pipeline (`pendingExplorerReveal` / `useFileExplorerReveal`) or an equivalent mechanism that can expand collapsed ancestors before selecting the imported path.
-5. It clears drag state and shows one summary toast derived from the returned per-item results.
-
-## 11. Error Handling
-
-Failure modes should be explicit but non-destructive:
-
-- Source path no longer exists: skip and report.
-- Permission denied: fail the affected item and report.
-- Unsupported symlink: skip and report.
-- Destination path unauthorized: fail the whole import.
-
-Toast copy should summarize, not spam:
-
-- Success: `Imported 5 items to src`
-- Partial: `Imported 4 items to src. 1 item was skipped.`
-- Failure: `Could not import dropped items`
-
-The renderer should derive these counts from the returned result payload rather than inferring them from thrown exceptions.
-
-## 12. Watcher and Refresh Strategy
-
-The filesystem watcher in `useFileExplorerWatch.ts` is a useful backstop, but the import flow should still refresh explicitly after completion.
-
-Why: native drops can create many files quickly, and the UX should not depend on watcher timing to make the destination directory show the new content.
-
-The minimal explicit refresh is:
-
-- `refreshDir(destinationDir)` after import
-
-If imported content lands under directories that were already expanded, the watcher can reconcile the rest.
-
-## 13. Performance
-
-Performance is a core requirement for this feature.
-
-### 13.1 Event Routing
-
-- Preload should extract the native `FileList` once and relay one IPC event per drop gesture.
-- The renderer should not do timer-based gesture reconstruction or emit one IPC call per dropped path.
-
-### 13.2 Main-Process Import
-
-- Import work must stay in the main process so the renderer remains responsive.
-- The copy path should use native filesystem copy primitives or streaming I/O, not `readFile()` buffering whole files into memory.
-- Pre-scan should walk dropped directories once per top-level source to detect symlinks before copy starts.
-- Top-level deconfliction should happen once per dropped source before the copy loop, avoiding repeated deep-path collision checks.
-
-### 13.3 UI Updates
-
-- The renderer should call `refreshDir(destinationDir)` once per completed gesture.
-- The renderer should emit one summary toast per gesture.
-- The renderer should reveal only the first successful import rather than forcing multiple scroll/reveal passes.
-
-### 13.4 Scope Control
-
-To keep v1 fast and predictable, it should not include per-file progress rows, per-item toasts, or overwrite prompts inside the copy loop.
-
-## 14. Testing
-
-### 14.1 Preload / Main
-
-- target resolution picks `file-explorer` when the composed path contains explorer markers
-- nearest `data-native-file-drop-dir` wins over outer containers
-- relay payload includes `destinationDir`
-- relay emits one event containing all dropped `paths`
-- file-explorer routing fails closed when the target marker is present but `destinationDir` is missing
-- editor-target drops still open every dropped file from the single gesture payload
-- terminal-target drops still insert every dropped path from the single gesture payload
-
-### 14.2 Filesystem Mutation Tests
-
-- imports a single file
-- imports multiple files in one batch
-- imports a directory recursively
-- deconflicts top-level filename collisions
-- deconflicts top-level directory collisions
-- rejects top-level symlink sources before canonicalization
-- skips a dropped directory with nested symlinks without leaving partial output
-- rejects unauthorized destinations
-- returns per-item results including rename metadata
-
-### 14.3 Renderer Tests
-
-- root drop surface remains active while the explorer is empty, loading, or showing a root read error
-- root highlight appears for `Files` drag
-- directory rows highlight and auto-expand for `Files` drag
-- file rows map to parent directory targets
-- one drop gesture triggers one import IPC call
-- one drop gesture produces one summary toast
-- success reveals the first imported destination path
-- success reveal still works when the imported path lives under ancestors that were collapsed before the drop
-
-## 15. Implementation Plan
-
-1. Extend native-drop typing and relay payload in preload/main to send one event per drop gesture with `paths[]`.
-2. Update existing editor and terminal `ui.onFileDrop` handlers in the renderer to accept `paths[]`.
-3. Refactor `FileExplorer.tsx` so the shared root explorer container stays mounted for loading, error, and empty states, then add explorer DOM markers for root and per-row destination directories.
-4. Teach `useFileExplorerDragDrop(...)` to track native `Files` drag state separately from internal move state.
-5. Add `fs.importExternalPaths(...)` to preload typings and main IPC with a per-item result schema.
-6. Implement pre-scan + recursive copy + top-level deconfliction + symlink rejection in `filesystem-mutations.ts`.
-7. Wire the explorer import success path through the existing expansion-aware reveal flow so drops into collapsed folders still reveal correctly.
-8. Add renderer import handling, refresh, reveal, and one-toast-per-gesture summary handling.
-9. Add tests across preload, IPC, and renderer.
-
-## 16. Open Questions
-
-- Whether v2 should support an overwrite confirmation flow like VS Code instead of prompt-free deconfliction.
-- Whether v2 should show progress UI for large directory imports.
-- Whether symlink rejection should later become a user-visible choice for trusted repos.
diff --git a/docs/fix-codex-token-refresh-loss.md b/docs/fix-codex-token-refresh-loss.md
deleted file mode 100644
index d5822cc3ae5..00000000000
--- a/docs/fix-codex-token-refresh-loss.md
+++ /dev/null
@@ -1,478 +0,0 @@
-# Fix: Claude & Codex accounts intermittently return 401 Unauthorized
-
-**Issue:** [#1284](https://github.com/stablyai/orca/issues/1284)
-**Status:** Proposed fix
-**Approach:** Add `readBackRefreshedTokens()` to both `CodexRuntimeHomeService` and `ClaudeRuntimeAuthService`
-
-## Problem
-
-Codex (and Claude) managed accounts intermittently return `401 Unauthorized` / `token_expired` errors after working normally for some time.
-
-### Root Cause
-
-Both `CodexRuntimeHomeService` and `ClaudeRuntimeAuthService` perform a **one-directional** auth sync: they always copy the managed account's credentials into the shared runtime path, but never read back refreshed tokens.
-
-**The problematic flow (identical for both providers):**
-
-1. User authenticates → credentials saved to managed storage
-2. `syncForCurrentSelection()` copies managed credentials → runtime path
-3. CLI runs using the runtime credentials
-4. OAuth access token expires over time. **CLI refreshes it and writes updated tokens back to the runtime path**
-5. Next PTY launch or rate-limit fetch triggers `syncForCurrentSelection()` again
-6. **The sync overwrites the runtime credentials with the stale managed copy** — the refreshed token is lost
-7. Next request uses the expired token → `401 Unauthorized`
-
-**Codex specifics:**
-- Runtime path: `~/.codex/auth.json`
-- Managed path: `<userData>/codex-accounts/<id>/home/auth.json`
-- Affected: `CodexRuntimeHomeService.syncForCurrentSelection()` line 84
-
-**Claude specifics:**
-- Runtime path: `~/.claude/.credentials.json` (+ Keychain on macOS)
-- Managed path: `<userData>/claude-accounts/<id>/auth/.credentials.json` (+ Keychain)
-- Affected: `ClaudeRuntimeAuthService.doSyncForCurrentSelection()` line 125
-- Note: Claude already has `lastWrittenCredentialsJson` and `detectExternalLoginAndUpdateSnapshot()` for the managed→system-default transition, but it **does not** read back refreshed tokens during steady-state sync — the same one-directional overwrite happens
-
-### Why it's intermittent
-
-- Tokens have a multi-hour lifetime, so the bug only surfaces after enough time passes for the original token to expire
-- The overwrite only happens on PTY launch or rate-limit fetch, not continuously
-- If the user re-authenticates, the cycle resets with a fresh token
-
-### Affected code
-
-**Codex:**
-- `src/main/codex-accounts/runtime-home-service.ts` — `syncForCurrentSelection()` (line 49-85)
-- Called from `prepareForCodexLaunch()` (line 39) and `prepareForRateLimitFetch()` (line 44)
-
-**Claude:**
-- `src/main/claude-accounts/runtime-auth-service.ts` — `doSyncForCurrentSelection()` (line 96-131)
-- Called from `prepareForClaudeLaunch()` (line 47) and `prepareForRateLimitFetch()` (line 52)
-
-## System Context
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                         Orca (main process)                  │
-│                                                              │
-│  ┌──────────────────────────────────────────────────┐        │
-│  │          CodexRuntimeHomeService                  │        │
-│  │                                                   │        │
-│  │  lastSyncedAccountId: string | null               │        │
-│  │  lastWrittenAuthJson: string | null  ← NEW        │        │
-│  │                                                   │        │
-│  │  syncForCurrentSelection()                        │        │
-│  │    ├─ captureSystemDefaultSnapshotIfNeeded()       │        │
-│  │    ├─ readBackRefreshedTokens()          ← NEW    │        │
-│  │    └─ writeRuntimeAuth()                          │        │
-│  │                                                   │        │
-│  │  restoreSystemDefaultSnapshot()                   │        │
-│  │    └─ detectExternalLoginAndUpdateSnapshot() ← NEW│        │
-│  └──────────┬──────────────────────────┬─────────────┘        │
-│             │                          │                      │
-│     ┌───────▼───────┐         ┌────────▼──────────┐          │
-│     │ Managed Home  │         │  Runtime Home     │          │
-│     │ <userData>/   │         │  ~/.codex/        │          │
-│     │ codex-accounts│         │  auth.json        │          │
-│     │ /<id>/home/   │         │                   │          │
-│     │ auth.json     │         │                   │          │
-│     └───────────────┘         └────────┬──────────┘          │
-└──────────────────────────────────────────┼────────────────────┘
-                                           │
-                                   ┌───────▼───────┐
-                                   │   Codex CLI   │
-                                   │               │
-                                   │ reads auth.json
-                                   │ refreshes token
-                                   │ writes back   │
-                                   └───────────────┘
-```
-
-## Data Flow: Token Refresh Preservation
-
-```
-  PTY launch / rate-limit fetch
-           │
-           ▼
-  syncForCurrentSelection()
-           │
-           ├─ captureSystemDefaultSnapshotIfNeeded()
-           │
-           ├─ Is lastSyncedAccountId === activeAccount.id?
-           │      │
-           │    YES → readBackRefreshedTokens()
-           │      │     │
-           │      │     ├─ Read ~/.codex/auth.json (current runtime)
-           │      │     ├─ Compare to lastWrittenAuthJson
-           │      │     │     │
-           │      │     │   DIFFER → Codex CLI refreshed the token
-           │      │     │     │       Write runtime auth.json back
-           │      │     │     │       to managed home auth.json
-           │      │     │     │
-           │      │     │   MATCH  → No external changes, continue
-           │      │     │
-           │      │     └─ (try/catch: failures log + continue)
-           │      │
-           │    NO  → Skip read-back (account switch in progress)
-           │
-           ├─ Read managed auth.json
-           ├─ writeRuntimeAuth(contents)
-           │     ├─ Write to ~/.codex/auth.json
-           │     └─ Record lastWrittenAuthJson = contents
-           │
-           └─ lastSyncedAccountId = activeAccount.id
-```
-
-## Data Flow: External Login Detection (managed → system-default)
-
-```
-  User deselects managed account (activeAccount = null)
-           │
-           ▼
-  syncForCurrentSelection()
-           │
-           ├─ lastSyncedAccountId !== null? (was managed)
-           │      │
-           │    YES → restoreSystemDefaultSnapshot()
-           │      │     │
-           │      │     ├─ detectExternalLoginAndUpdateSnapshot()
-           │      │     │     │
-           │      │     │     ├─ lastWrittenAuthJson !== null?
-           │      │     │     ├─ Read current ~/.codex/auth.json
-           │      │     │     ├─ Compare to lastWrittenAuthJson
-           │      │     │     │     │
-           │      │     │     │   DIFFER → External login detected
-           │      │     │     │     │       (e.g. `codex auth login`)
-           │      │     │     │     │       Delete stale snapshot
-           │      │     │     │     │       Clear lastWrittenAuthJson
-           │      │     │     │     │       Return true (skip restore)
-           │      │     │     │     │
-           │      │     │     │   MATCH  → No external login
-           │      │     │     │           Return false (do restore)
-           │      │     │     │
-           │      │     │     └─ (try/catch: failures → return false)
-           │      │     │
-           │      │     └─ If not external: restore snapshot as before
-           │      │
-           │    NO  → Skip (was never managed)
-           │
-           └─ lastSyncedAccountId = null
-```
-
-## Fix: Add `readBackRefreshedTokens()` to Both Services
-
-The fix adds the same read-back mechanism to both `CodexRuntimeHomeService` and `ClaudeRuntimeAuthService`. The core logic is identical: before overwriting runtime credentials, compare the file to what Orca last wrote. If they differ, the CLI refreshed the token — write it back to managed storage.
-
-### What each service needs
-
-| Change | Codex (`runtime-home-service.ts`) | Claude (`runtime-auth-service.ts`) |
-|--------|-----------------------------------|-------------------------------------|
-| Add `lastWrittenAuthJson` field | **NEW** | Already exists as `lastWrittenCredentialsJson` |
-| Track writes in `writeRuntime*()` | **NEW** | Already done (line 271) |
-| `readBackRefreshedTokens()` | **NEW** | **NEW** (missing despite having the tracking field) |
-| `detectExternalLoginAndUpdateSnapshot()` | **NEW** | Already exists (line 224) |
-| `clearLastWritten*()` for re-auth | **NEW** | **NEW** (same re-auth clobbering risk) |
-
-### Key differences between services
-
-| Aspect | Claude | Codex |
-|--------|--------|-------|
-| Auth storage | Keychain (macOS) + `.credentials.json` | `auth.json` only |
-| Sync model | Async (serialized via `mutationQueue`) | Synchronous |
-| Managed path | `managedAuthPath/.credentials.json` | `managedHomePath/auth.json` |
-| Tracking field | `lastWrittenCredentialsJson` | `lastWrittenAuthJson` |
-
-### Codex implementation
-
-Add a `lastWrittenAuthJson` field and three new behaviors:
-
-1. **`writeRuntimeAuth()`** — record what was written
-2. **`readBackRefreshedTokens()`** — before overwriting, check if Codex CLI refreshed the token
-3. **`detectExternalLoginAndUpdateSnapshot()`** — on managed→system-default transition, detect external logins
-
-### Pseudocode
-
-```typescript
-export class CodexRuntimeHomeService {
-  private lastSyncedAccountId: string | null = null
-
-  // Why: tracks the auth.json content Orca last wrote to ~/.codex/auth.json.
-  // On managed→system-default transition, if the file differs from this value,
-  // an external login (e.g. `codex auth login`) overwrote it — so Orca adopts
-  // the file as the new system default instead of restoring a stale snapshot.
-  // Between syncs, if the file differs, Codex CLI refreshed the token — so
-  // Orca writes back the refreshed token to managed storage.
-  private lastWrittenAuthJson: string | null = null
-
-  // ... constructor, prepare methods unchanged ...
-
-  syncForCurrentSelection(): void {
-    this.captureSystemDefaultSnapshotIfNeeded()
-
-    const settings = this.store.getSettings()
-    const activeAccount = this.getActiveAccount(
-      settings.codexManagedAccounts,
-      settings.activeCodexManagedAccountId
-    )
-    if (!activeAccount) {
-      if (this.lastSyncedAccountId !== null) {
-        this.restoreSystemDefaultSnapshot()
-        this.lastSyncedAccountId = null
-      }
-      return
-    }
-
-    const activeAuthPath = join(activeAccount.managedHomePath, 'auth.json')
-    if (!existsSync(activeAuthPath)) {
-      console.warn(
-        '[codex-runtime-home] Active managed account is missing auth.json, restoring system default'
-      )
-      this.store.updateSettings({ activeCodexManagedAccountId: null })
-      if (this.lastSyncedAccountId !== null) {
-        this.restoreSystemDefaultSnapshot()
-        this.lastSyncedAccountId = null
-      }
-      return
-    }
-
-    // NEW: Before overwriting runtime auth, check if Codex CLI refreshed
-    // the token since our last write. If so, preserve those refreshed tokens
-    // back to managed storage so they aren't lost.
-    if (this.lastSyncedAccountId === activeAccount.id) {
-      this.readBackRefreshedTokens(activeAuthPath)
-    }
-
-    this.lastSyncedAccountId = activeAccount.id
-    this.writeRuntimeAuth(readFileSync(activeAuthPath, 'utf-8'))
-  }
-
-  // Why: Codex CLI refreshes expired OAuth tokens and writes them back to
-  // ~/.codex/auth.json. If we detect the runtime file differs from what Orca
-  // last wrote, the CLI must have refreshed — so we write the updated tokens
-  // back to managed storage before overwriting runtime with managed state.
-  // This is the Codex analog of the read-back logic implied by
-  // lastWrittenCredentialsJson in ClaudeRuntimeAuthService.
-  private readBackRefreshedTokens(managedAuthPath: string): void {
-    try {
-      const runtimeAuthPath = this.getRuntimeAuthPath()
-      if (!existsSync(runtimeAuthPath)) {
-        return
-      }
-
-      // Nothing to compare against — first sync or after restart.
-      // Skip read-back to avoid capturing stale/unknown state.
-      if (this.lastWrittenAuthJson === null) {
-        return
-      }
-
-      const runtimeContents = readFileSync(runtimeAuthPath, 'utf-8')
-      if (runtimeContents === this.lastWrittenAuthJson) {
-        return
-      }
-
-      // Codex CLI refreshed tokens at runtime — preserve them in managed storage.
-      writeFileAtomically(managedAuthPath, runtimeContents, { mode: 0o600 })
-    } catch (error) {
-      // Why: read-back is best-effort. A transient fs error (permissions,
-      // file locked by another process) must not block the forward sync
-      // path — the worst case is one more stale-token cycle, which is
-      // strictly better than failing the entire sync.
-      console.warn('[codex-runtime-home] Failed to read back refreshed tokens:', error)
-    }
-  }
-
-  private restoreSystemDefaultSnapshot(): void {
-    // Why: detect whether an external tool (e.g. `codex auth login`) overwrote
-    // auth.json while a managed account was active. If so, that external login
-    // becomes the new system default — skip the stale snapshot restore.
-    if (this.detectExternalLoginAndUpdateSnapshot()) {
-      return
-    }
-
-    const snapshotPath = this.getSystemDefaultSnapshotPath()
-    if (!existsSync(snapshotPath)) {
-      return
-    }
-
-    this.writeRuntimeAuth(readFileSync(snapshotPath, 'utf-8'))
-  }
-
-  // Why: mirrors ClaudeRuntimeAuthService.detectExternalLoginAndUpdateSnapshot().
-  // If the runtime auth.json differs from what Orca last wrote, something
-  // external changed it. That external state should become the new system
-  // default rather than being overwritten by a potentially stale snapshot.
-  private detectExternalLoginAndUpdateSnapshot(): boolean {
-    if (this.lastWrittenAuthJson === null) {
-      return false
-    }
-
-    const runtimeAuthPath = this.getRuntimeAuthPath()
-    if (!existsSync(runtimeAuthPath)) {
-      return false
-    }
-
-    try {
-      const currentAuth = readFileSync(runtimeAuthPath, 'utf-8')
-      if (currentAuth === this.lastWrittenAuthJson) {
-        return false
-      }
-    } catch {
-      return false
-    }
-
-    // External login detected — adopt current state as the new system default.
-    const snapshotPath = this.getSystemDefaultSnapshotPath()
-    rmSync(snapshotPath, { force: true })
-    this.lastWrittenAuthJson = null
-    return true
-  }
-
-  private writeRuntimeAuth(contents: string): void {
-    writeFileAtomically(this.getRuntimeAuthPath(), contents, { mode: 0o600 })
-    // Why: record what we wrote so readBackRefreshedTokens() and
-    // detectExternalLoginAndUpdateSnapshot() can detect external changes.
-    this.lastWrittenAuthJson = contents
-  }
-}
-```
-
-### Re-auth safety: clearing `lastWrittenAuthJson`
-
-When `CodexAccountService.doReauthenticateAccount()` runs, it writes fresh tokens to managed storage via `codex login`, then calls `syncForCurrentSelection()`. Without intervention, the read-back logic would see that runtime differs from `lastWrittenAuthJson` (because Codex CLI may have refreshed the runtime token between syncs) and write the stale runtime content back to managed — overwriting the fresh re-auth tokens.
-
-**Fix:** `CodexRuntimeHomeService` must expose a method to clear `lastWrittenAuthJson` so that the re-auth caller can signal "managed storage was externally updated, skip read-back on next sync."
-
-```typescript
-// Called by CodexAccountService before syncForCurrentSelection() after re-auth or add-account.
-clearLastWrittenAuthJson(): void {
-  this.lastWrittenAuthJson = null
-}
-```
-
-The same applies to `doAddAccount()`, which also writes managed auth then syncs. Both callers must call `clearLastWrittenAuthJson()` before `syncForCurrentSelection()`.
-
-### Changes to `CodexAccountService`
-
-Both `doAddAccount()` and `doReauthenticateAccount()` write fresh tokens to managed storage (via `codex login`) then call `syncForCurrentSelection()`. They must clear the tracking field first to prevent read-back from overwriting the fresh tokens:
-
-```typescript
-// In doAddAccount(), after runCodexLogin succeeds:
-this.runtimeHome.clearLastWrittenAuthJson()
-this.runtimeHome.syncForCurrentSelection()
-
-// In doReauthenticateAccount(), after runCodexLogin succeeds:
-this.runtimeHome.clearLastWrittenAuthJson()
-this.runtimeHome.syncForCurrentSelection()
-```
-
-### Safety considerations
-
-- **Only reads back when Orca owns the runtime auth** (`lastSyncedAccountId === activeAccount.id`), so external `codex login` changes are not accidentally captured into the wrong managed account
-- **Skips read-back when `lastWrittenAuthJson` is null** (first sync, after restart, or after re-auth/add) — avoids capturing stale or unknown state that Orca didn't write
-- **try/catch around read-back** — a transient fs error (permissions, locked file) logs a warning but does not block the forward sync. Worst case: one more stale-token cycle, strictly better than a sync failure
-- **try/catch around external login detection** — same rationale; detection failure falls through to normal snapshot restore, which is the safe default
-- **Atomic write** to managed auth prevents partial-write corruption
-- **No behavior change for account switches** — when switching accounts, `lastSyncedAccountId` differs from the new account ID, so no read-back occurs
-- **No behavior change for system-default flow** — read-back only runs when a managed account is active and was previously synced
-- **External login detection on managed→system-default transition** — if `codex auth login` ran while a managed account was active, the snapshot is stale. Deleting it and clearing `lastWrittenAuthJson` lets the external login persist as the new system default
-- **In-memory tracking only** — `lastWrittenAuthJson` is not persisted to disk. After an Orca restart, the field is null, and the first sync performs a clean write without read-back. This is intentionally conservative: we'd rather do one redundant overwrite than risk reading back unknown state
-
-### Claude implementation
-
-Claude already has `lastWrittenCredentialsJson` tracking and `detectExternalLoginAndUpdateSnapshot()`. It only needs two additions:
-
-1. **`readBackRefreshedTokens()`** — same logic as Codex, adapted for Claude's async model and Keychain
-2. **`clearLastWrittenCredentialsJson()`** — for re-auth safety (same pattern as Codex)
-
-```typescript
-// In ClaudeRuntimeAuthService:
-
-// Add to doSyncForCurrentSelection(), before writeRuntimeCredentials():
-if (this.lastSyncedAccountId === activeAccount.id) {
-  await this.readBackRefreshedTokens(activeAccount)
-}
-
-// Why: Claude CLI refreshes expired OAuth tokens and writes them back to
-// .credentials.json (and Keychain on macOS). If we detect the runtime file
-// differs from what Orca last wrote, the CLI must have refreshed.
-private async readBackRefreshedTokens(account: ClaudeManagedAccount): Promise<void> {
-  try {
-    if (this.lastWrittenCredentialsJson === null) {
-      return
-    }
-
-    const paths = this.pathResolver.getRuntimePaths()
-    if (!existsSync(paths.credentialsPath)) {
-      return
-    }
-
-    const runtimeContents = readFileSync(paths.credentialsPath, 'utf-8')
-    if (runtimeContents === this.lastWrittenCredentialsJson) {
-      return
-    }
-
-    // CLI refreshed tokens — write back to managed storage.
-    if (process.platform === 'darwin') {
-      await writeManagedClaudeKeychainCredentials(account.id, runtimeContents)
-    } else {
-      const credentialsPath = join(account.managedAuthPath, '.credentials.json')
-      writeFileAtomically(credentialsPath, runtimeContents, { mode: 0o600 })
-    }
-  } catch (error) {
-    console.warn('[claude-runtime-auth] Failed to read back refreshed tokens:', error)
-  }
-}
-
-// Exposed for ClaudeAccountService to call before sync after re-auth/add.
-clearLastWrittenCredentialsJson(): void {
-  this.lastWrittenCredentialsJson = null
-}
-```
-
-### Changes to `ClaudeAccountService`
-
-Same pattern as Codex — both `doAddAccount()` and `doReauthenticateAccount()` must clear the tracking field before syncing:
-
-```typescript
-// In doAddAccount(), after login succeeds:
-this.runtimeAuth.clearLastWrittenCredentialsJson()
-await this.runtimeAuth.syncForCurrentSelection()
-
-// In doReauthenticateAccount(), after login succeeds:
-this.runtimeAuth.clearLastWrittenCredentialsJson()
-await this.runtimeAuth.syncForCurrentSelection()
-```
-
-### Structural alignment
-
-The two services should stay structurally aligned. Both now have the same three mechanisms:
-
-| Mechanism | Codex | Claude |
-|-----------|-------|--------|
-| Track what we wrote | `lastWrittenAuthJson` | `lastWrittenCredentialsJson` |
-| Read back refreshed tokens | `readBackRefreshedTokens()` | `readBackRefreshedTokens()` |
-| Detect external logins | `detectExternalLoginAndUpdateSnapshot()` | `detectExternalLoginAndUpdateSnapshot()` |
-| Clear tracking on re-auth | `clearLastWrittenAuthJson()` | `clearLastWrittenCredentialsJson()` |
-
-Future changes to either service should be cross-checked against the other.
-
-### Files to modify
-
-**Codex:**
-- `src/main/codex-accounts/runtime-home-service.ts` — add `lastWrittenAuthJson` field, `readBackRefreshedTokens()`, `detectExternalLoginAndUpdateSnapshot()`, `clearLastWrittenAuthJson()`, update `writeRuntimeAuth()` and `restoreSystemDefaultSnapshot()`
-- `src/main/codex-accounts/service.ts` — add `clearLastWrittenAuthJson()` calls in `doAddAccount()` and `doReauthenticateAccount()`
-- `src/main/codex-accounts/runtime-home-service.test.ts` — add test cases
-
-**Claude:**
-- `src/main/claude-accounts/runtime-auth-service.ts` — add `readBackRefreshedTokens()`, `clearLastWrittenCredentialsJson()`, call read-back in `doSyncForCurrentSelection()`
-- `src/main/claude-accounts/service.ts` — add `clearLastWrittenCredentialsJson()` calls in `doAddAccount()` and `doReauthenticateAccount()`
-- `src/main/claude-accounts/runtime-auth-service.test.ts` — add test cases
-
-**Test cases (both services):**
-- Token read-back when CLI refreshes tokens between syncs
-- No read-back on first sync (tracking field is null)
-- No read-back on account switch (`lastSyncedAccountId` differs)
-- External login detection on managed→system-default transition
-- Graceful degradation when read-back throws (fs error)
-- Re-auth does not lose fresh tokens: after clearing tracking field + sync, managed storage retains the re-auth tokens
-- Add-account does not lose fresh tokens: same pattern as re-auth
diff --git a/docs/fix-missing-single-instance-lock.md b/docs/fix-missing-single-instance-lock.md
deleted file mode 100644
index 3d8bdf74f72..00000000000
--- a/docs/fix-missing-single-instance-lock.md
+++ /dev/null
@@ -1,443 +0,0 @@
-# Fix: Missing single-instance lock corrupts `orca-runtime.json` + `endpoint.env` on every relaunch
-
-**Issue:** [#1312](https://github.com/stablyai/orca/issues/1312)
-**Status:** Proposed fix
-**Approach:** Add `app.requestSingleInstanceLock()`, clear owned metadata on clean exit, and sweep orphaned sockets on startup.
-
-## Problem
-
-Orca v1.3.24 does not call `app.requestSingleInstanceLock()`. Every launch of the AppImage / `.app` bundle starts a new Electron main process that unconditionally:
-
-1. Opens a fresh Unix socket `o-<NEW_PID>-<runtimeId-prefix>.sock`.
-2. Atomically rewrites `<userData>/orca-runtime.json` with the new pid / socket / runtimeId / authToken, clobbering the previously-running instance's metadata.
-3. Picks a new random port and rewrites `<userData>/agent-hooks/endpoint.env` with the new port + token.
-
-The earlier Orca keeps its socket + hook-port alive, but the canonical metadata files no longer point at it. When the most-recent instance quits, the socket is `rmSync`'d in `OrcaRuntimeRpcServer.stop()` but the metadata file is left pointing at the dead pid. `orca status` then returns `runtime.state = 'stale_bootstrap'` even though earlier Orca instances are still running healthily.
-
-### Root cause
-
-Three distinct gaps in the main-process lifecycle:
-
-1. **No single-instance lock.** `grep -rn requestSingleInstanceLock src/` returns zero matches. Every launch boots a full second Electron process instead of focusing the existing window.
-2. **No metadata clear on clean exit.** `src/main/runtime/runtime-metadata.ts:29` exports `clearRuntimeMetadata()` but it is never called. The `will-quit` handler in `src/main/index.ts:516` stops the RPC server (removes the socket) but leaves `orca-runtime.json` on disk pointing at a dead pid + missing socket. The safety comment in `src/main/runtime/runtime-rpc.ts:132-136` explicitly declines to clear metadata, citing the risk of erasing another live runtime's bootstrap during restarts / updates / dev overlap — that concern is real but is the *symptom* of missing single-instance, not a principled design.
-3. **No startup sweep of orphaned sockets.** A process killed by SIGKILL / OOM-kill skips `OrcaRuntimeRpcServer.stop()` entirely, leaving `o-<dead-pid>-*.sock` files in `<userData>/` with no cleanup path. The reporter observed three such orphans on a single live system.
-
-### Symptom (from the issue)
-
-Healthy state with one orca running (pid 50926):
-
-```json
-{
-  "app":     { "running": true, "pid": 50926 },
-  "runtime": { "state": "ready", "reachable": true, "runtimeId": "2ad0..." },
-  "graph":   { "state": "ready" }
-}
-```
-
-After launching a second instance and quitting it while the first stays open:
-
-```json
-{
-  "app":     { "running": false, "pid": null },
-  "runtime": { "state": "stale_bootstrap", "reachable": false, "runtimeId": null },
-  "graph":   { "state": "not_running" }
-}
-```
-
-The `stale_bootstrap` branch is distinguished at `src/cli/runtime/status.ts:17-20` — "metadata file exists but pid not running" vs. "no metadata at all".
-
-### Affected code
-
-- `src/main/index.ts` — app lifecycle entry; `app.whenReady` at line 315, `will-quit` at line 516.
-- `src/main/runtime/runtime-rpc.ts` — `OrcaRuntimeRpcServer.start()` line 51, `stop()` line 112 (with the deferred-cleanup comment at lines 132-136).
-- `src/main/runtime/runtime-metadata.ts` — `writeRuntimeMetadata` / `readRuntimeMetadata` / `clearRuntimeMetadata`.
-- `src/main/agent-hooks/server.ts` — `writeEndpointFile` line 1299, `stop()` line 1223 (with a parallel deferred-cleanup comment at lines 1230-1237).
-- `src/shared/runtime-bootstrap.ts` — `RuntimeMetadata` shape and `getRuntimeMetadataPath()`.
-- `src/main/startup/configure-process.ts` — `configureDevUserDataPath(isDev)` redirects dev runs to `orca-dev` userData.
-- `src/cli/runtime/status.ts` — CLI reader, never writes metadata.
-
-## Architecture
-
-### Current (buggy) state
-
-Every launch boots a new Electron main. All live instances race on the same `orca-runtime.json` / `endpoint.env`, and SIGKILL'd predecessors leave orphaned sockets behind.
-
-```
-                <userData>/ (e.g. ~/.config/orca)
-                ┌────────────────────────────────────────────┐
-                │ orca-runtime.json   ← clobbered on every   │
-                │                       launch (last writer  │
-                │                       wins, pid may be     │
-                │                       dead)                │
-                │ agent-hooks/endpoint.env  ← same race      │
-                │ o-<pid-A>-*.sock    (live, owned by A)     │
-                │ o-<pid-B>-*.sock    (orphan — B SIGKILL'd) │
-                │ o-<pid-C>-*.sock    (orphan — C OOM-killed)│
-                └────────────────────────────────────────────┘
-                          ▲            ▲            ▲
-                          │ writes     │ writes     │ writes
-                          │            │            │
-                  ┌───────┴──┐  ┌──────┴───┐  ┌─────┴────┐
-                  │ Electron │  │ Electron │  │ Electron │
-                  │   #1     │  │   #2     │  │   #3     │
-                  │ (live,   │  │ (live,   │  │ (quit;   │
-                  │  hook    │  │  hook    │  │  left    │
-                  │  HTTP)   │  │  HTTP)   │  │  stale   │
-                  └──────────┘  └──────────┘  │  meta)   │
-                                              └──────────┘
-                          ▲
-                          │ reads orca-runtime.json
-                          │ → sees wrong/dead pid
-                  ┌───────┴───────┐
-                  │ CLI (status)  │ reports 'stale_bootstrap'
-                  └───────────────┘
-```
-
-### Post-fix state
-
-A single Electron owns the userData. Second launches fire `second-instance` and exit. The ownership guard at `clearRuntimeMetadataIfOwned()` protects the auto-updater handoff. Sweep runs at startup.
-
-```
-                <userData>/
-                ┌────────────────────────────────────────────┐
-                │ orca-runtime.json   ← one writer (pid A)   │
-                │ agent-hooks/endpoint.env                   │
-                │ o-<pid-A>-*.sock    (live, owned by A)     │
-                │ (orphans swept on next start)              │
-                └────────────────────────────────────────────┘
-                          ▲
-                          │ writes
-                  ┌───────┴──────────────┐
-                  │ Electron #1 (holds   │──── hook HTTP ──►
-                  │ single-instance lock)│
-                  └──────────▲───────────┘
-                             │ 'second-instance' event
-                  ┌──────────┴───────────┐
-                  │ Electron #2 (boots,  │
-                  │ lock fails, focuses  │
-                  │ #1's window, quits)  │── transient, no writes
-                  └──────────────────────┘
-                          ▲
-                          │ reads orca-runtime.json
-                  ┌───────┴───────┐
-                  │ CLI (status)  │ reports 'ready'
-                  └───────────────┘
-
-Ownership guard site: src/main/runtime/runtime-metadata.ts
-  → clearRuntimeMetadataIfOwned(userData, ownedPid, ownedRuntimeId)
-```
-
-### Data flow
-
-**Happy path — single instance steady state**
-
-```
-[user action] → Electron #1 main loop
-  → Electron #1 RPC server (Unix socket) handles IPC
-  → hook HTTP server answers localhost requests
-  → orca-runtime.json unchanged (only written at start)
-  → CLI reads orca-runtime.json → 'ready'
-```
-
-**First-launch cold start**
-
-```
-[launch] → configureDevUserDataPath(is.dev)    (startup/configure-process.ts)
-  → app.requestSingleInstanceLock() → true     (main/index.ts)
-  → sweepOrphanedRuntimeSockets(userData)      (runtime-rpc.ts start())
-  → OrcaRuntimeRpcServer.start() binds o-<pid>-*.sock
-  → writeRuntimeMetadata({pid, runtimeId, ...}) (runtime-metadata.ts)
-  → agent-hooks server writes endpoint.env
-  → openMainWindow()
-```
-
-**Second-launch rejected**
-
-```
-[launch] → configureDevUserDataPath(is.dev)
-  → app.requestSingleInstanceLock() → false    (lock held by #1)
-  → app.quit()                                  (transient process exits)
-  → Electron #1 receives 'second-instance' event
-  → Electron #1 restores + focuses mainWindow
-  → no writes to orca-runtime.json or endpoint.env
-```
-
-**Auto-updater handoff (two orderings, both safe)**
-
-```
-Ordering X: old clears first
-  old.runtimeRpc.stop() rmSync's o-<oldPid>-*.sock
-  old.clearRuntimeMetadataIfOwned() — current.pid == oldPid → clear
-  new.writeRuntimeMetadata() — fresh file, no conflict
-
-Ordering Y: new writes first
-  new.writeRuntimeMetadata() — file now points at newPid/newRuntimeId
-  old.clearRuntimeMetadataIfOwned() — current.pid != oldPid → SUPPRESSED
-  new continues undisturbed
-
-Invariant: the ownership guard (pid + runtimeId match) is what makes
-both orderings safe. Without it, Ordering Y would erase the new
-process's just-written metadata.
-```
-
-## Proposed fix
-
-Three surgical changes, in decreasing order of importance:
-
-### 1. Single-instance lock (primary — kills ~90% of the bug surface)
-
-In `src/main/index.ts`, immediately **after** `configureDevUserDataPath(is.dev)` (line 89) and **before** any handler registration or `app.whenReady(...)`, gate the rest of the module on a new helper `acquireSingleInstanceLock()` (see "Helper extraction" in the testing section):
-
-```ts
-function focusExistingWindow(): void {
-  // Why: focus the existing window instead of spawning a parallel Electron
-  // process that would clobber orca-runtime.json and endpoint.env.
-  if (mainWindow) {
-    if (mainWindow.isMinimized()) mainWindow.restore()
-    mainWindow.focus()
-  }
-  // Pre-window case: the active instance is still booting and will call
-  // openMainWindow() from whenReady(). No action needed here.
-}
-
-if (!acquireSingleInstanceLock(app, focusExistingWindow)) {
-  if (is.dev) {
-    console.log(
-      'Another Orca instance is already running against this userData path — focusing existing window.'
-    )
-  }
-  app.quit()
-  // Why: early-return is what prevents the service constructors and handler
-  // registrations below (whenReady, before-quit, will-quit, etc.) from
-  // running in a process that is already losing the lock race.
-  return
-}
-// All existing app lifecycle setup below.
-```
-
-**Placement rationale (from codex review):** the lock must come *after* `configureDevUserDataPath(is.dev)` so dev (`orca-dev` userData) and packaged (`orca` userData) instances lock in separate namespaces — Electron derives the lock identity from the `userData` path. Placing it before would force dev and packaged builds to serialize against each other, which is the opposite of the current dev/prod isolation contract.
-
-**Dev-mode behavior:** kept unconditional. `configureDevUserDataPath` already isolates `pnpm dev` from packaged runs, so devs who want two instances already get the answer by running both a packaged build and a dev build. Allowing multi-instance against the same userData reopens the exact corruption this fix targets.
-
-**Dev-mode ergonomics:** when the lock fails in dev mode, write a single `console.log('Another Orca instance is already running against this userData path — focusing existing window.')` immediately before `app.quit()`. This makes the behavior discoverable in the `pnpm dev` console so internal devs don't mistake a silent exit for a broken launcher. Packaged runs skip the log — there's no attached console.
-
-### 2. Clear owned metadata on clean exit (secondary — hardens `stale_bootstrap` reporting)
-
-Add a guarded clear in `src/main/runtime/runtime-metadata.ts`:
-
-```ts
-/**
- * Why: clearing metadata unconditionally would race with a sibling Orca
- * process during auto-updater handoff or dev/prod overlap — see the comment
- * in runtime-rpc.ts:132-136. The ownership guard preserves the original
- * safety invariant while still letting us report 'not_running' (not
- * 'stale_bootstrap') after a clean exit.
- */
-export function clearRuntimeMetadataIfOwned(
-  userDataPath: string,
-  ownedPid: number,
-  ownedRuntimeId: string
-): void {
-  const current = readRuntimeMetadata(userDataPath)
-  if (!current) return
-  if (current.pid !== ownedPid) return
-  if (current.runtimeId !== ownedRuntimeId) return
-  clearRuntimeMetadata(userDataPath)
-}
-```
-
-In `src/main/index.ts` `will-quit` handler (line 516-548), the clear must be **awaited before Electron exits**, not fire-and-forget. The existing handler uses a two-pass `preventDefault()` pattern with `disconnectDaemon().finally(app.quit())`. The existing `void runtimeRpc.stop().catch(...)` at line 530-534 currently fires independently of that chain; Electron may exit before `runtimeRpc.stop()` resolves, and a `.then(clear)` appended to it would race the second-pass `app.quit()`. Fold both into the awaited chain instead — and do the work **inside** the `!daemonDisconnectDone` guard so `runtimeRpc.stop()` fires exactly once, on the first pass:
-
-```ts
-if (!daemonDisconnectDone) {
-  e.preventDefault()
-  // Why: capture ownership synchronously (before any await) so the guard
-  // still has the right pid/runtimeId to compare against if shutdown
-  // partially clears global state. Evaluating these inside .then() would
-  // let a later teardown path null them out mid-chain.
-  const ownedPid = process.pid
-  const ownedRuntimeId = runtime?.getRuntimeId()
-  // Why: the construction AND the allSettled() must both live inside the
-  // `!daemonDisconnectDone` guard. The will-quit handler re-fires after
-  // app.quit() below; without this guard, the second pass would re-invoke
-  // runtimeRpc.stop() (redundant rmSync on an already-removed socket) and
-  // re-run the ownership-guarded clear against a metadata file that may
-  // now belong to the auto-updater's replacement process.
-  const rpcStopAndClear = runtimeRpc
-    ? runtimeRpc
-        .stop()
-        .then(() => {
-          if (ownedRuntimeId) {
-            clearRuntimeMetadataIfOwned(app.getPath('userData'), ownedPid, ownedRuntimeId)
-          }
-        })
-        .catch((error) => {
-          console.error('[runtime] Failed to stop local RPC transport:', error)
-        })
-    : Promise.resolve()
-  // Why: Promise.allSettled — we need BOTH the daemon disconnect and the RPC
-  // stop + owned-metadata clear to complete before Electron exits. Using
-  // allSettled (not all) preserves the existing fail-open posture: if
-  // disconnectDaemon rejects, we still quit instead of hanging the app.
-  Promise.allSettled([disconnectDaemon(), rpcStopAndClear]).then(() => {
-    daemonDisconnectDone = true
-    app.quit()
-  })
-}
-```
-
-Remove the standalone `void runtimeRpc.stop().catch(...)` at line 530-534 — it is folded into `rpcStopAndClear` above.
-
-**Why compare-before-clear is not over-engineering:** `autoUpdater.quitAndInstall()` quits the old process immediately and relaunches. The new process may already be starting (writing its own metadata) while the old `will-quit` is running. An unconditional clear would delete the new process's fresh metadata. Codex confirmed this is the correct posture.
-
-### 3. Orphaned-socket sweep on startup (tertiary — hygiene)
-
-In `OrcaRuntimeRpcServer.start()` (`src/main/runtime/runtime-rpc.ts:51`), before creating the new listener, enumerate `<userData>/o-*.sock` and remove any whose pid component is dead:
-
-```ts
-// Why: processes killed by SIGKILL / OOM-kill skip stop() and leave behind
-// o-<pid>-*.sock files. Sweep dead-pid sockets on startup so the userData
-// directory does not accumulate orphans over the app's lifetime.
-function sweepOrphanedRuntimeSockets(userDataPath: string, ownPid: number): void {
-  let entries: string[]
-  try {
-    entries = readdirSync(userDataPath)
-  } catch {
-    return
-  }
-  for (const entry of entries) {
-    const match = /^o-(\d+)-[A-Za-z0-9_-]+\.sock$/.exec(entry)
-    if (!match) continue
-    const pid = Number(match[1])
-    if (!Number.isFinite(pid) || pid === ownPid) continue
-    try {
-      process.kill(pid, 0)
-      // Pid is alive — leave its socket alone. Another Orca instance owns it.
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ESRCH') {
-        try {
-          rmSync(join(userDataPath, entry), { force: true })
-        } catch {
-          // Best-effort sweep; a permission error is fine to ignore.
-        }
-      }
-    }
-  }
-}
-```
-
-**Constraints:** only sweep sockets with the exact `o-<digits>-<base64url-ish>.sock` shape; skip anything else. Never touch the current process's own pid even though the stricter `start()` flow already rmSync's it.
-
-**Windows note:** this sweep is POSIX-only by construction — on Windows the transport is a named pipe (`\\.\pipe\orca-<pid>-<suffix>`) and named pipes don't leave filesystem entries in `userData`. No sweep needed.
-
-**Socket-name invariant:** the sweep regex `^o-(\d+)-[A-Za-z0-9_-]+\.sock$` must stay in lockstep with `createRuntimeTransportMetadata()` in `runtime-rpc.ts`, which emits `o-${pid}-${endpointSuffix}.sock`. The cheap guard — and what this doc recommends — is a unit test that constructs a transport name via `createRuntimeTransportMetadata()` and asserts the sweep regex matches it; any future change to the socket-name shape trips the test. Longer-term, if the transport name grows more fields, the preferred answer is to export a shared constant or factory from `runtime-rpc.ts` that both the creator and the sweep regex consume, so the two can never drift by construction. Deferred here to keep the diff surgical.
-
-## Deliberately not in scope
-
-- **No CLI-side reader fallback.** Scanning for any live `o-*.sock` in `getCliStatus()` would require a per-socket sidecar metadata file (authToken, runtimeId) since today only one shared `orca-runtime.json` exists. That is a multi-instance-by-design change, not a bug fix. The fix above assumes the intended model is one Orca per userData.
-- **No per-instance userData.** The env-var override `ORCA_USER_DATA_PATH` at `src/cli/runtime/metadata.js` already exists for power users who genuinely want parallel runtimes. No change.
-- **No unlink of `endpoint.env` on stop.** The deferred-cleanup rationale at `src/main/agent-hooks/server.ts:1230-1237` (TOCTOU with a concurrent writer) is still correct under the single-instance lock: auto-update handoff still briefly has two processes sharing the file. Leaving the file unchanged on quit matches the existing fail-open policy and no user symptom motivates changing it.
-
-## Testing strategy
-
-### Unit tests (`src/main/runtime/runtime-metadata.test.ts`, extend)
-
-- `clearRuntimeMetadataIfOwned` with matching `{pid, runtimeId}` → file removed.
-- `clearRuntimeMetadataIfOwned` with mismatched pid → file retained.
-- `clearRuntimeMetadataIfOwned` with mismatched runtimeId → file retained (simulates another instance having overwritten while we were still alive).
-- `clearRuntimeMetadataIfOwned` with no file → no-op, no throw.
-
-### Unit tests (new `src/main/runtime/runtime-socket-sweep.test.ts`)
-
-Seed a temp userData directory with four entries so the three retention branches are distinct:
-
-- `o-1-aaaa.sock` → own-pid-skipped branch (test passes `ownPid: 1`, so this is skipped via the `pid === ownPid` early-exit).
-- `o-<process.pid>-bbbb.sock` → alive-but-not-own branch (`process.kill(pid, 0)` succeeds without `ESRCH` → retained).
-- `o-99999999-cccc.sock` → dead-pid branch (`process.kill(pid, 0)` throws `ESRCH` → swept).
-- `foo.sock` → non-matching-shape branch (regex miss → retained untouched).
-
-Run sweep with `ownPid = 1` and assert: the `o-99999999-*.sock` file is gone; the other three remain. Using a synthetic `ownPid` (init pid `1`, effectively always alive on POSIX and never the test runner's own pid) means each of the three retained-entries covers a *distinct* code path, instead of collapsing "own-pid-skipped" and "alive-non-own-pid-retained" into the same observation.
-
-### Helper extraction for the single-instance lock
-
-Extract the lock acquisition into `src/main/startup/single-instance-lock.ts`:
-
-```ts
-export function acquireSingleInstanceLock(
-  app: Electron.App,
-  onSecondInstance: () => void
-): boolean {
-  if (!app.requestSingleInstanceLock()) {
-    return false
-  }
-  app.on('second-instance', onSecondInstance)
-  return true
-}
-```
-
-`src/main/index.ts` wires it up inline after `configureDevUserDataPath(is.dev)`. Because the module's top-level cannot `return`, gate the file-writing init (`initDataPath` / `initStatsPath` / `initClaudeUsagePath` / `initCodexUsagePath` / `enableMainProcessGpuFeatures` / `installDevParentWatchdog` / `installDevParentDisconnectQuit`) behind an `if (hasSingleInstanceLock)` block and let the lifecycle handler registrations fire unconditionally — `app.quit()` prevents `whenReady` from ever dispatching, so `runtime` / `runtimeRpc` / `store` / `stats` stay `null` and every shutdown handler short-circuits via optional chaining:
-
-```ts
-const hasSingleInstanceLock = acquireSingleInstanceLock(app, focusExistingWindow)
-if (!hasSingleInstanceLock) {
-  if (is.dev) {
-    console.log(
-      '[single-instance] Another Orca instance is already running against this userData path — focusing existing window.'
-    )
-  }
-  app.quit()
-}
-
-if (hasSingleInstanceLock) {
-  installDevParentDisconnectQuit(is.dev)
-  installDevParentWatchdog(is.dev)
-  initDataPath()
-  initStatsPath()
-  initClaudeUsagePath()
-  initCodexUsagePath()
-  enableMainProcessGpuFeatures()
-}
-```
-
-### Unit test of the helper (`src/main/startup/single-instance-lock.test.ts`)
-
-With a fake `app` (stub `requestSingleInstanceLock()` + `on()`):
-
-- When `requestSingleInstanceLock()` returns `false` → helper returns `false` and does NOT register `'second-instance'`.
-- When it returns `true` → helper returns `true` and registers exactly one `'second-instance'` listener that invokes the callback.
-
-### Integration assertion (narrow)
-
-Do NOT try to assert "downstream service constructors were not invoked" by re-importing `src/main/index.ts`. Module-level side effects at lines 67-101 (dev watchdog, shell path hydration, userData path configuration) run before the lock check and would fire regardless, either failing the test or requiring heavy mocking.
-
-Instead, the integration surface the fix cares about is already covered by: (a) the helper unit test above, and (b) the manual repro below. If deeper coverage is wanted later, the right move is to refactor `src/main/index.ts` so the `whenReady`-guarded setup is exported as a testable function — that is a separate refactor and deliberately out of scope for this fix.
-
-### Manual repro (matches the issue's steps)
-
-1. Launch packaged Orca. `cp ~/.config/orca/orca-runtime.json /tmp/before.json`.
-2. Launch the AppImage / `.app` a second time. Verify the existing window receives focus (no new window appears) and `stat` shows `orca-runtime.json` mtime is unchanged.
-3. Quit Orca. Verify `~/.config/orca/orca-runtime.json` is gone and `orca status --json` reports `runtime.state = 'not_running'` (not `'stale_bootstrap'`).
-4. Kill a running Orca with `SIGKILL`. Verify that the next Orca launch removes the orphaned `o-<killed-pid>-*.sock` during `OrcaRuntimeRpcServer.start()`.
-
-### Regression watch — auto-updater
-
-`autoUpdater.quitAndInstall()` in `src/main/updater.ts:194` triggers the relaunch flow. The handoff is short (~1s) but non-atomic, so the design relies on the ownership guard to keep both interleavings safe:
-
-- **Socket is removed before the new process binds.** The old process's `runtimeRpc.stop()` `rmSync`'s `o-<oldPid>-*.sock` as part of teardown. The new process then binds its own `o-<newPid>-*.sock`. The brief window of inconsistency is "metadata absent" + "no socket", never "metadata points at a live-but-wrong pid with a still-mounted old socket."
-- **New writes before old clears (Ordering Y).** If the new process calls `writeRuntimeMetadata()` before the old process's `clearRuntimeMetadataIfOwned()` runs, the guard sees `current.pid !== ownedPid` (and `current.runtimeId !== ownedRuntimeId`) and suppresses the clear. The new metadata survives.
-- **Old clears before new writes (Ordering X).** The old process finds its own pid + runtimeId in the file, clears it, and exits. The new process then writes its fresh metadata onto an empty slot. Same end state.
-- **CLI behavior during the ~1s window.** `orca status` transitions `ready` → `not_running` (clean, not `stale_bootstrap`) → `starting` → `ready`. It never reports a wrong-pid reading, because the only two observable file states are "file for old pid" (pre-teardown) and "file for new pid" (post-write); the guard prevents a mixed state.
-
-A future regression report that catches the transient `not_running` during an auto-update should be recognized as intended behavior.
-
-### Cross-platform coverage
-
-- **macOS / Linux / Windows:** single-instance lock path is identical (Electron handles the OS-level plumbing).
-- **Windows:** named-pipe transport means no socket-sweep work; assert the sweep early-returns on `platform === 'win32'` (or simply does nothing because no matching entries exist).
-- **Dev mode:** lock acquired against `orca-dev` userData; asserted by running `pnpm dev` twice and seeing the second exit immediately.
-
-## Confidence
-
-High. The diagnosis matches the reported symptom and filesystem evidence one-for-one; the fix adds only calls that Electron and the existing metadata module already expose. Second opinion from codex flagged the `configureDevUserDataPath` ordering constraint and the `clearRuntimeMetadataIfOwned` ownership guard, both incorporated above.
-
-Concretely, the fix closes the reported data-integrity scenarios: double-click relaunch, `gtk-launch` relaunch, clean-quit of a second instance while the first stays open, and orphaned `o-<pid>-*.sock` files left by SIGKILL / OOM-kill. It deliberately leaves two narrow scenarios open: (1) the auto-updater handoff, where `orca status` may transiently report `not_running` for ~1s between the old process's clear and the new process's write — covered in the regression-watch section above; and (2) deliberate multi-instance launches via `ORCA_USER_DATA_PATH` / `ORCA_DEV_USER_DATA_PATH`, which remain an explicit power-user escape hatch with isolated userData per instance and are not in scope for this fix.
diff --git a/docs/fix-pty-fd-leak.md b/docs/fix-pty-fd-leak.md
deleted file mode 100644
index 1205407873f..00000000000
--- a/docs/fix-pty-fd-leak.md
+++ /dev/null
@@ -1,628 +0,0 @@
-# Fix per-session PTY fd leak in the current daemon
-
-## Status: resolved (2026-05-01)
-
-**Native-side root cause confirmed and patched.** E2E validation under both Node and Electron ABIs: 50 spawn/kill cycles, ptmx count stays at baseline (0). Before the patch, the same harness reproduced a 1-fd-per-spawn linear leak (5 → 55 ptmx fds over 50 cycles).
-
-## Root cause (actual)
-
-The leak is a native-side off-by-one in `node-pty@1.1.0`'s `pty_posix_spawn` cleanup loop on macOS. In `src/unix/pty.cc`:
-
-- **Allocation** (lines 697-701) walks `low_fds[0..2]`, allocating via `posix_openpt(O_RDWR)`. The loop `break`s at the first `low_fds[count] >= STDERR_FILENO`, so `count` holds the index of the last allocated slot (0, 1, or 2). These are decoy `/dev/ptmx` handles used as a workaround for a macOS pty race condition that ensures the real master fd lands above `STDERR_FILENO`.
-- **Cleanup** (lines 781-783, buggy):
-  ```c
-  for (; count > 0; count--) {
-    close(low_fds[count]);
-  }
-  ```
-  When the typical case triggers (`break` at `count=0`, i.e. the very first `posix_openpt` returned an fd ≥ 2), the loop body never executes — `low_fds[0]` is never closed. Every spawn leaks one ptmx handle.
-
-Upstream fixed this in commit [`af053f2`](https://github.com/microsoft/node-pty/commit/af053f2) (PR #882, 2026-01-28), but version 1.1.0 (pinned here) predates that fix.
-
-**Applied fix:** minimal 3-line backport in `config/patches/node-pty@1.1.0.patch`:
-
-```c
--  for (; count > 0; count--) {
--    close(low_fds[count]);
-+  for (size_t i = 0; i <= count && i < 3; i++) {
-+    close(low_fds[i]);
-   }
-```
-
-The `i < 3` bound is an over-cautious defense against the pathological case where all three `posix_openpt` calls returned fds < `STDERR_FILENO` (loop exhausts to `count=3`, which would otherwise read `low_fds[3]` — UB in upstream's fix too, though unreachable in practice).
-
-## Why the JS-side `destroy()` discipline (below) is still correct
-
-The native patch alone closes the leak. But the JS-side changes landed in `pty-subprocess.ts`, `session.ts`, `terminal-host.ts`, `local-pty-provider.ts`, and `relay/pty-handler.ts` remain load-bearing for separate reasons:
-
-1. **SIGHUP-to-recycled-pid hazard.** `UnixTerminal.destroy()` registers `_socket.once('close', () => this.kill('SIGHUP'))`. After the child is reaped, its pid can be recycled to an unrelated user process (Chrome tab, editor, etc.) before the socket close event fires. Neutralizing `proc.kill` on POSIX before `destroy()` prevents delivering SIGHUP to a stranger.
-2. **`forceKill`/`signal` guard against recycled pid.** `process.kill(proc.pid, …)` after `onExit` targets a potentially-recycled pid. The internal `dead` guard converts these into no-ops.
-3. **Daemon shutdown determinism.** `TerminalHost.dispose()` → `Session.forceKillAndDisposeSubprocess()` reaps stubborn children via SIGKILL and releases the master fd synchronously, bypassing the 5s `KILL_TIMEOUT_MS` fallback.
-4. **Belt-and-suspenders fd release.** Calling `destroy()` on every teardown path remains the contract that will keep holding if the pinned node-pty is ever replaced or upgraded to a build without the bug.
-
-## Original problem statement (for historical context)
-
-## Problem
-
-The current `daemon-v4` is leaking PTY master file descriptors (`ptmx`) at a rate roughly 20× the live session count. In a real reported case, the live v4 daemon was holding **269 `ptmx` fds for only 13 active terminals** — every closed terminal should have returned its `ptmx` to the OS, but the daemon keeps accumulating them until it hits macOS's `kern.tty.ptmx_max=511` cap and every new terminal (Orca or otherwise) fails with "cannot allocate any more pty devices."
-
-This is a distinct bug from the orphaned-daemon issue handled in [auto-kill-old-daemons.md](./auto-kill-old-daemons.md):
-
-| Bug | Fd leak unit | Lifetime | Fix surface |
-|---|---|---|---|
-| Orphaned daemons | Whole daemon process | Across app upgrades | `daemon-init.ts`, `daemon-pty-router.ts` |
-| **This doc** | Per-PTY `ptmx` | Within any node-pty-hosting process | `pty-subprocess.ts` (daemon), `local-pty-provider.ts` (legacy), `relay/pty-handler.ts` (SSH) + wiring |
-
-Both bugs compound each other (stale daemons × leaky sessions), but either one is sufficient to exhaust the cap in a few days of normal use. Fixing orphan daemons alone would only slow down the bleed — the PTY wrappers themselves must stop leaking.
-
-The same missing `destroy()` call exists in all three node-pty-hosting code paths (daemon, legacy local provider, SSH relay), so the fix is scoped to all three.
-
-### Root cause
-
-The master ptmx fd is owned by a `tty.ReadStream` that node-pty stores on the `UnixTerminal` instance as `_socket` (see `node_modules/node-pty/lib/unixTerminal.js`). That socket wraps the fd via libuv. The fd only gets closed when the socket is destroyed, and the socket is only destroyed by one of:
-
-1. `UnixTerminal.destroy()` — calls `_close()`, then `_socket.destroy()`, then `_writeStream.dispose()`.
-2. The socket's own `'close'` / `'error'` event firing, which hits the `self._socket.on('close', ...)` wiring inside node-pty's constructor.
-
-None of our current teardown paths reliably trigger either. Specifically:
-
-1. **`forceKill` via raw `process.kill(pid, 'SIGKILL')`** (`pty-subprocess.ts:159-168`) kills the child but does nothing to the libuv socket on the parent side. The slave fd closing in the kernel does not, by itself, cause the parent's read-side socket to emit `'close'` on all platforms / node versions — and even when it does, it races GC.
-2. **`dead = true` after a thrown native error** (`pty-subprocess.ts:127-157`) leaves the `_socket` fully alive. We just stop touching `proc`; the read stream keeps the fd.
-3. **Session `dispose()` / `handleSubprocessExit`** (`session.ts:189-228`, `session.ts:250-271`) never call anything that reaches `_socket.destroy()`. They kill the child and move on.
-
-So the fd leaks until the JS wrapper is GC'd and libuv finalizes the stream — which may be much later, or never, within the daemon's lifetime. Evidence from the reported case is consistent with this: 269 ptmx − 13 live ≈ 256 orphaned fds from terminals that were opened and closed during the daemon's lifetime, which matches a few days of create/kill churn at ~50-100 terminal ops/day.
-
-node-pty already exposes the fix: `UnixTerminal.prototype.destroy` (unixTerminal.js:219) and `WindowsTerminal.prototype.destroy` (windowsTerminal.js:141). We just never call it.
-
-## Goals
-
-- After a PTY terminates (by any path — natural exit, kill, force-kill, native throw, disposal), the master fd is released to the OS on the same tick as teardown.
-- The fix covers every code path in the repo that spawns `node-pty`: the daemon, the legacy local provider, and the SSH relay.
-- Zero regressions to the `dead` flag pattern (`pty-subprocess.ts:119-122`) that prevents `Napi::Error` from killing the daemon.
-- No renderer-visible change. Public IPC / RPC contracts are untouched.
-- Measurable: a repeatable test harness spawns N PTYs, terminates them via each exit path, and asserts the fd count returns to baseline.
-
-## Non-goals
-
-- Fixing the orphaned-daemon issue. Handled in [auto-kill-old-daemons.md](./auto-kill-old-daemons.md).
-- Killing daemon-side sessions when a worktree is deleted. Separate follow-up.
-- Upgrading or replacing `node-pty`. We are calling node-pty's existing `destroy()` — no library change needed.
-- Adding a generic "fd leak monitor" watchdog. Observability belongs in a separate effort (see Related work).
-
-## Design decisions
-
-### Call `node-pty`'s `destroy()` on every teardown path
-
-The fix is exactly that. Each provider already wraps the raw `IPty` in its own small handle/struct. Add a single `dispose()` entry point on those wrappers whose body does:
-
-```ts
-try {
-  ;(proc as unknown as { destroy?: () => void }).destroy?.()
-} catch {
-  /* swallow — already torn down, or native-side error we can't recover from */
-}
-```
-
-That is the primary mechanism. `destroy()` is what drives `_close()` → `_socket.destroy()` → `_writeStream.dispose()` inside node-pty, which is what releases the master fd. Everything else the wrapper needs (idempotency, callback nulling, SIGKILL fallback for unresponsive children) is a local concern layered around that single call.
-
-### Why not reinvent `destroy()`
-
-An earlier draft of this design proposed a hand-rolled body: null callbacks + raw SIGKILL + `proc.kill()` in try/catch. That was wrong. None of those steps touch `_socket`, which is the thing holding the fd. The only reliable trigger is the close path node-pty already ships — `UnixTerminal.prototype.destroy` on POSIX, `WindowsTerminal.prototype.destroy` on ConPTY. Duplicating that logic in our wrappers would (a) not work on POSIX anyway because `_socket` is private and (b) drift from upstream on any future node-pty update. Forward to `destroy()`, layer idempotency and error-swallowing on top, stop.
-
-### Shared handle contract
-
-Each provider exposes a dispose entry point with the same semantics: idempotent, synchronous, throws never. The daemon already has a `SubprocessHandle` type that is the right place to hang it; the local provider and relay each have equivalent internal records (`ptyProcesses` / `ManagedPty`) and get a small helper function that wraps the same `destroy()` call plus their provider-specific bookkeeping (listener disposal, map cleanup).
-
-```ts
-// src/main/daemon/session.ts
-export type SubprocessHandle = {
-  pid: number
-  write(data: string): void
-  resize(cols: number, rows: number): void
-  kill(): void
-  forceKill(): void
-  signal(sig: string): void
-  onData(cb: (data: string) => void): void
-  onExit(cb: (code: number) => void): void
-  /** Release the native PTY handle via node-pty's own destroy() path.
-   *  Idempotent. Safe to call after exit. Called by Session on every teardown
-   *  path (natural exit, kill, force-kill, native throw, session dispose). */
-  dispose(): void
-}
-```
-
-### Daemon: `pty-subprocess.ts`
-
-Track a `disposed` flag. `dispose()`:
-
-1. If already disposed, return.
-2. Mark `disposed = true` and `dead = true`.
-3. Null the JS-side `onDataCb` / `onExitCb` references so the wrapper stops fanning out anything after destroy.
-4. **On POSIX only, neutralize `proc.kill` on this instance.** Replace it with a no-op before step 5. This closes the pid-recycle SIGHUP hazard described below. Windows is exempt because `WindowsTerminal.destroy` *is* a call to `kill()` — neutralizing it turns destroy() into a no-op and leaks the ConPTY agent.
-5. Call `proc.destroy()` inside try/catch. On Unix this runs `_close()` → `_socket.destroy()` → `_writeStream.dispose()`; on Windows it defers to the ConPTY agent's close via `_deferNoArgs(_this.kill())` (`windowsTerminal.js:141-146`).
-
-```ts
-dispose(): void {
-  if (disposed) return
-  disposed = true
-  dead = true
-  onDataCb = null
-  onExitCb = null
-  // Why: node-pty's UnixTerminal.destroy() registers `_socket.once('close', () => this.kill('SIGHUP'))`
-  // (unixTerminal.js:219-229). On the dispose-while-alive path (e.g. daemon shutdown
-  // of an active session), SIGTERM has already been sent. The socket close fires
-  // asynchronously; by then the child may have exited and its pid been recycled
-  // to an unrelated process. Without this neutralization, SIGHUP can be delivered
-  // to a Chrome tab, editor, or other user process — silent cross-app corruption.
-  // `_socket.destroy()` still releases the fd; only the dangerous SIGHUP is removed.
-  //
-  // Platform guard: WindowsTerminal.destroy() implements the ConPTY close by
-  // CALLING `this.kill()` via `_deferNoArgs` (windowsTerminal.js:141-146). If we
-  // neutralize `kill` on Windows, destroy() becomes a no-op and the ConPTY
-  // agent leaks. The SIGHUP hazard is POSIX-only, so the neutralization is too.
-  if (process.platform !== 'win32') {
-    ;(proc as unknown as { kill?: (sig?: string) => void }).kill = () => {}
-  }
-  try {
-    ;(proc as unknown as { destroy?: () => void }).destroy?.()
-  } catch {
-    /* swallow — already torn down, or native-side error we can't recover from */
-  }
-}
-```
-
-`kill` neutralization lives on this `proc` instance only — the wrapper's exposed `kill()` / `forceKill()` entry points call `process.kill(proc.pid, sig)` directly (`pty-subprocess.ts:149-175`), which is unaffected. Callers that want to send SIGTERM/SIGKILL still can; what they can't do after dispose is have node-pty's internal close listener deliver an unexpected SIGHUP against a stale pid.
-
-No extra SIGKILL is needed from `dispose()`: `forceKill` remains available as a separate entry point for the "we need the child gone now" case. Callers that want both (Session on timeout) call `forceKill()` then `dispose()`.
-
-### Daemon: Session / TerminalHost wiring
-
-`Session.dispose()` (`session.ts:189-228`) and `Session.handleSubprocessExit()` (`session.ts:250-271`) each call `this.subprocess.dispose()`:
-
-- `handleSubprocessExit`: call it immediately after updating `_state = 'exited'` and before fan-out to `attachedClients`. try/catch around the call — a throwing dispose must not prevent exit-code delivery.
-- `dispose()`: call it at the end, after `emulator.dispose()` and after the attached-client fanout.
-- `forceDispose()` (`session.ts:319-347`): same as `dispose()`.
-
-`subprocess.dispose()` is idempotent because `handleSubprocessExit` and the outer `dispose()` can both fire for the same session (manual kill → child exits → handleSubprocessExit runs → later Session.dispose runs).
-
-`TerminalHost.dispose()` (`terminal-host.ts:215-240`) already kills every session. Replace the `session.kill()` call in the shutdown loop with a new `session.forceKillAndDisposeSubprocess()` method, so daemon shutdown reaps stubborn children (SIGKILL) AND releases the PTY master fd synchronously — without depending on the 5s `KILL_TIMEOUT_MS` eventually calling `forceDispose`:
-
-```ts
-for (const [, session] of this.sessions) {
-  session.detachAllClients()
-  session.forceKillAndDisposeSubprocess() // synchronous; bypasses the 5s timer
-}
-// Preserve existing post-loop cleanup: sessions.clear(), killedTombstones.clear(),
-// and any cleanup callbacks fire unchanged after the loop. Only the per-session
-// kill() → forceKillAndDisposeSubprocess() substitution is new.
-```
-
-**Why `forceKillAndDisposeSubprocess` instead of `kill() + disposeSubprocess()`.** Today's shutdown path is `session.kill()` (SIGTERM, start 5s timer) → if the child ignores SIGTERM, `forceDispose()` eventually fires and sends SIGKILL. That 5s fallback is load-bearing: shells with traps, hung compilers, and long-running processes with signal handlers routinely ignore SIGTERM. The earlier draft dropped `killTimer` during disposeSubprocess, which would close the fd but leave the child orphaned at the OS level — worse than today's behavior. `forceKillAndDisposeSubprocess` explicitly sends SIGKILL (via `subprocess.forceKill()`) before releasing the fd, so stubborn children are still reaped synchronously:
-
-```ts
-// Public: orderly-shutdown path. Force-kills the child (SIGKILL is not
-// ignorable), then releases the PTY master fd synchronously. Used only by
-// TerminalHost.dispose() — renderer reconnects cold after daemon exit.
-forceKillAndDisposeSubprocess(): void {
-  // Why: forceKill before the subprocess dispose. disposeSubprocess below
-  // neutralizes node-pty's kill() on POSIX, which is what the internal SIGHUP
-  // close listener would call. forceKill uses process.kill(pid, 'SIGKILL')
-  // directly (pty-subprocess.ts:159-168) — unaffected by the neutralization,
-  // because it does not go through proc.kill. SIGKILL is not ignorable; any
-  // child that would have survived the 5s timer is reaped immediately.
-  try {
-    this.subprocess.forceKill()
-  } catch {
-    /* swallow — child may already be gone */
-  }
-  this.#teardownSubprocess()
-}
-```
-
-`disposeSubprocess()` is a tight helper — it flips the session to the terminal state, cancels any pending timers, and forwards to the subprocess dispose. It deliberately does not fan out `onExit` to attached clients, because `TerminalHost.dispose()` is the orderly-shutdown path and the renderer will reconnect cold.
-
-**Shared `#teardown` helper.** Both `Session.dispose()` and `Session.disposeSubprocess()` mutate the same state (`_disposed`, `_state`, `killTimer`, `shellReadyTimer`) and forward to `this.subprocess.dispose()`. Route them through a single private helper `#teardownSubprocess()` so the state transition is defined exactly once — two dispose paths that drift on which flag gets flipped would be a merge hazard (a future change to one that forgets the other silently drops exit events):
-
-```ts
-// Session — shared private helper, called by both public paths.
-#teardownSubprocess(): void {
-  if (this._disposed) return
-  this._disposed = true
-  // Note: `_state = 'exited'` is NOT set here — the outer caller (Session.dispose,
-  // Session.forceDispose) is responsible for the state transition AFTER capturing
-  // any invariants that depend on the pre-flip value. See the `wasTerminating`
-  // capture in Session.dispose for the load-bearing example.
-  if (this.killTimer) { clearTimeout(this.killTimer); this.killTimer = null }
-  if (this.shellReadyTimer) { clearTimeout(this.shellReadyTimer); this.shellReadyTimer = null }
-  try {
-    this.subprocess.dispose()
-  } catch (err) {
-    // Why: dispose() is documented never to throw, but if it does we must not
-    // prevent callers from completing their own cleanup (fanout, map removal).
-    console.warn('[Session] subprocess.dispose() threw:', err)
-  }
-}
-
-// Public: orderly-shutdown path. Does NOT broadcast onExit to clients; the
-// renderer reconnects cold after TerminalHost.dispose(). Sets _state = 'exited'
-// after teardown because this path has no pre-flip invariants to preserve.
-disposeSubprocess(): void {
-  this.#teardownSubprocess()
-  this._state = 'exited'
-}
-
-// Public: existing Session.dispose() — MUST capture `wasTerminating` BEFORE
-// calling #teardownSubprocess, because the check depends on `_state !== 'exited'`
-// being the PRE-flip value. Forgetting this check would orphan processes that
-// ignored SIGTERM (the `_isTerminating && _state !== 'exited'` guard at
-// session.ts:200 is the only path that calls `subprocess.forceKill()` in the
-// dispose-while-terminating case).
-dispose(): void {
-  // Why: captured BEFORE the `_state = 'exited'` flip at line 230. This check
-  // guards the "dispose while kill() was already in flight" case — if true,
-  // the child hasn't reaped yet and we need to forceKill it here (the 5s
-  // killTimer is also about to be cleared by #teardownSubprocess). Matches
-  // the existing invariant at session.ts:200. Do not move this line below
-  // #teardownSubprocess or the `_state = 'exited'` assignment.
-  const wasTerminating = this._isTerminating && this._state !== 'exited'
-  const clientsToNotify = wasTerminating ? this.attachedClients.slice() : []
-
-  if (wasTerminating) {
-    // Existing forceDispose semantics — child hasn't reaped yet, force it now.
-    try { this.subprocess.forceKill() } catch { /* already dead */ }
-    this._exitCode = -1
-    this._isTerminating = false
-  }
-
-  this.#teardownSubprocess()
-  this._state = 'exited'
-
-  this.attachedClients = []
-  this.preReadyStdinQueue = []
-  this.postReadyFlushGate.clear()
-  this.emulator.dispose()
-
-  for (const client of clientsToNotify) {
-    client.onExit(-1)
-  }
-}
-```
-
-Single source of truth for the state transition. If we ever need to add a new piece of tear-down state, one edit keeps both paths in sync. The asymmetry (`_state = 'exited'` lives in the public methods, not the helper) is deliberate: `dispose()` has a pre-flip invariant (`wasTerminating`) to preserve, `disposeSubprocess()` doesn't. Forcing both through a single helper that flipped `_state` would reintroduce the ordering bug.
-
-**`forceDispose()` must also route through the helper.** `forceDispose` fires from the 5s `killTimer` when a SIGTERM'd child refused to exit (`session.ts:319-347`). This is the exact kill-timeout path this fd-leak fix targets — if `forceDispose` doesn't call `subprocess.dispose()`, the ptmx fd leaks on every force-kill. The current body flips `_disposed = true` directly at `session.ts:324`, which would short-circuit a later `Session.dispose()` call from `TerminalHost` tombstone cleanup at `#teardownSubprocess`'s `if (this._disposed) return` guard, silently skipping `subprocess.dispose()`.
-
-```ts
-// Private: fires from the 5s killTimer when SIGTERM was ignored.
-// `_state === 'exited'` already short-circuits above; below that guard the
-// session is still running, so the fd is still open. MUST release it.
-private forceDispose(): void {
-  if (this._state === 'exited') {
-    return
-  }
-  // Why: unlike dispose(), forceDispose has no pre-flip invariants to capture.
-  // The caller (killTimer) has no attached-client fanout obligation beyond
-  // what the helper + the existing client loop below cover. Route the
-  // subprocess tear-down through the shared helper so `proc.destroy()` runs
-  // exactly once and `_disposed` is flipped in the same transition.
-  try { this.subprocess.forceKill() } catch { /* already dead */ }
-  this._exitCode = -1
-  this._isTerminating = false
-
-  this.#teardownSubprocess()  // ← sets _disposed = true, calls subprocess.dispose()
-  this._state = 'exited'
-
-  const clients = this.attachedClients
-  this.attachedClients = []
-  this.preReadyStdinQueue = []
-  this.postReadyFlushGate.clear()
-  this.emulator.dispose()
-
-  for (const client of clients) {
-    client.onExit(-1)
-  }
-}
-```
-
-Order matters. `forceKill()` must run BEFORE `#teardownSubprocess()` — the helper's `subprocess.dispose()` neutralizes `proc.kill` on POSIX, but `subprocess.forceKill()` uses `process.kill(proc.pid, 'SIGKILL')` directly and is unaffected by that neutralization. If we reorder, nothing changes functionally, but the explicit order documents the invariant.
-
-After `session.forceKillAndDisposeSubprocess()`, the 5s `killTimer` started by any prior `kill()` is cleared, so `forceDispose` cannot fire against an already-disposed subprocess. Even if the timer somehow survived the clear, `_state` is now `'exited'` and `forceDispose`'s early-return guard (`session.ts:320`) would short-circuit it.
-
-### LocalPtyProvider
-
-`local-pty-provider.ts` stores each spawned `IPty` in a module-level `ptyProcesses` map and has two teardown sites: `shutdown(id)` (single PTY) and `killAll()` / `safeKillAndClean()` (bulk). Both currently call `proc.kill()` and delete the map entry.
-
-Change: add a `destroyPtyProcess(proc)` helper. Same shape as `disposeManagedPty` in the relay: on POSIX, neutralize `proc.kill` before calling `destroy()` to close the same SIGHUP-to-recycled-pid hazard; on Windows, skip the neutralization because `WindowsTerminal.destroy` calls `kill()` internally. Invoke the helper at the end of `safeKillAndClean` (after listener disposal, after `proc.kill()`), at the end of `shutdown` (same spot), and in the natural-exit `onExit` path after `clearPtyState(id)`.
-
-```ts
-function destroyPtyProcess(proc: IPty): void {
-  // Why: same SIGHUP-to-recycled-pid hazard as the daemon and relay paths.
-  // UnixTerminal.destroy() registers `_socket.once('close', () => this.kill('SIGHUP'))`.
-  // LocalPtyProvider's own kill() has already fired; if the close listener
-  // delivers a trailing SIGHUP after pid recycling, it lands on a random user
-  // process. Local machines recycle pids fast — regression risk is highest here.
-  // Windows exempt: WindowsTerminal.destroy IS a kill() call via _deferNoArgs.
-  if (process.platform !== 'win32') {
-    ;(proc as unknown as { kill?: (sig?: string) => void }).kill = () => {}
-  }
-  try {
-    ;(proc as unknown as { destroy?: () => void }).destroy?.()
-  } catch {
-    /* swallow — already torn down */
-  }
-}
-```
-
-The natural-exit `onExit` invocation is load-bearing: without it, a shell that exits cleanly (the common case) never releases its ptmx fd until the next GC. `onExit` is also the only path that runs without an external kill having been issued, so the neutralization is defensive against future reorderings — today `proc.kill` is a no-op after the child is reaped, but the kernel may still emit the close event.
-
-### Relay: `relay/pty-handler.ts`
-
-`PtyHandler` stores each `IPty` on a `ManagedPty` record. Teardown happens in five places:
-
-- `shutdown(params)` — SIGTERM + 5s SIGKILL fallback, or SIGKILL immediately when `immediate === true`.
-- The `onExit` wiring inside `wireAndStore` — deletes the map entry.
-- `spawn()`'s stale-context path (`pty-handler.ts:144-154`) — client reconnected before the PTY response was delivered, so the PTY is orphaned and gets SIGTERM + 5s SIGKILL fallback.
-- `dispose()` — loops every managed pty and shuts it down.
-- `sendSignal()` — public entry point that forwards arbitrary signals; must keep working after dispose is queued.
-
-Change (ordering matters):
-
-1. **`onExit` wiring**: after the map-delete, call `disposeManagedPty(managed)`. This is the natural-exit path — the child has already exited and been reaped. Neutralizing `pty.kill` here is defensive: any trailing invocation from the socket close listener is no-op'd regardless of pid-recycle timing. The fd is released synchronously.
-2. **`shutdown(params)` with `immediate === true`**: after `managed.pty.kill('SIGKILL')`, call `disposeManagedPty(managed)`. SIGKILL has already reaped the child.
-3. **`shutdown(params)` graceful path (SIGTERM)**: do **not** call `destroy()` immediately after the SIGTERM send. The 5s `killTimer` and the natural `onExit` already cover fd release via step 1. Calling `destroy()` right after SIGTERM collapses the graceful-shutdown window and risks interrupting shell `EXIT` traps or cleanup hooks that run between SIGTERM and shell exit. If the `killTimer` fires (SIGKILL fallback), the SIGKILL reaps the child and `onExit` (step 1) calls `disposeManagedPty` on its own — **do not add a redundant call inside the killTimer closure**. The `disposed` guard makes a redundant call harmless but wiring it in both places is a merge hazard.
-4. **`spawn()` stale-context killTimer**: this path (`pty-handler.ts:149-153`) already sends SIGTERM then SIGKILL at 5s if the PTY wasn't acked. The relevant teardown path is `onExit` (step 1), which now calls `disposeManagedPty`. No code change needed in the stale-context branch itself — the onExit wiring in `wireAndStore` runs for this PTY the same as for any other. Confirmed covered.
-5. **`dispose()` loop**: call `disposeManagedPty` for each active managed pty AFTER `managed.pty.kill('SIGTERM')`. This is the relay-shutdown path — we accept that any in-flight shell cleanup is cut short because the relay process itself is exiting.
-
-The common shape, extracted into a helper:
-
-```ts
-function disposeManagedPty(managed: ManagedPty): void {
-  if (managed.disposed) return
-  managed.disposed = true
-  // Why: clear any pending 5s SIGKILL fallback timer. If graceful-shutdown
-  // armed a killTimer and the child then exited cleanly (firing onExit →
-  // disposeManagedPty), the timer would otherwise fire later and attempt
-  // pty.kill('SIGKILL') on an already-disposed instance. The ptys.has(id)
-  // guard inside the timer short-circuits today, but symmetry is clearer.
-  if (managed.killTimer) {
-    clearTimeout(managed.killTimer)
-    managed.killTimer = undefined
-  }
-  // Why: same SIGHUP-to-recycled-pid hazard as the daemon fix — neutralize
-  // node-pty's kill on the instance before calling destroy(). The relay
-  // typically runs on Linux remote hosts where pid recycling is fast.
-  // Windows exempt: WindowsTerminal.destroy calls kill() internally, so
-  // neutralizing it turns destroy() into a no-op.
-  if (process.platform !== 'win32') {
-    ;(managed.pty as unknown as { kill?: (sig?: string) => void }).kill = () => {}
-  }
-  try {
-    ;(managed.pty as unknown as { destroy?: () => void }).destroy?.()
-  } catch {
-    /* swallow */
-  }
-}
-```
-
-**`disposed` flag on `ManagedPty`.** The flag is new — add it to the `ManagedPty` type. Purpose: prevent `disposeManagedPty` from running twice (both `onExit` and `shutdown` can fire for the same PTY), and — more importantly — let `sendSignal`, `writeData`, and other pre-existing entry points short-circuit if the caller tries to use a disposed PTY:
-
-```ts
-private async sendSignal(params: Record<string, unknown>): Promise<void> {
-  // ... existing signal validation ...
-  const managed = this.ptys.get(id)
-  if (!managed || managed.disposed) {
-    throw new Error(`PTY "${id}" not found`)
-  }
-  managed.pty.kill(signal)  // ← on POSIX this is neutralized-to-no-op only
-                            //   AFTER disposeManagedPty runs. The early return
-                            //   above means we never reach this line post-dispose.
-}
-```
-
-Without the `disposed` guard, a `sendSignal('SIGTERM')` call landing after `onExit` → `disposeManagedPty` has neutralized `managed.pty.kill` would silently succeed (return success, do nothing). The `disposed` check converts the silent failure into the existing "not found" error, which is what callers already handle.
-
-The graceful-SIGTERM path of `shutdown` remains unchanged (SIGTERM + 5s killTimer that sends SIGKILL). Fd release on that path happens either via the `onExit` hook (step 1) when the shell exits cleanly, or via the killTimer → SIGKILL → `onExit` chain if SIGTERM was ignored. Under no circumstance does `shutdown`'s graceful branch synchronously call `destroy()`.
-
-### Why not just replace `node-pty`
-
-Tempting, and probably correct long-term. Out of scope here: node-pty's API surface is deeply woven into the daemon, LocalPtyProvider, and the relay. Swapping it is a multi-week effort with its own regression surface. This bug is a one-line miss against an API the library already ships — fix that first.
-
-### Why not a daemon-level fd watchdog
-
-A periodic "count my open fds, restart if over threshold" watchdog would mask the bug, not fix it. It also introduces the exact timer-based lifecycle the orphan-daemon design [explicitly rejected](./auto-kill-old-daemons.md) for the same reasons (cold-restore instead of warm-reattach, false positives against live work). Observability yes, auto-restart no.
-
-## Interaction states
-
-Because this fix sits below the IPC layer, the renderer sees no state changes. All user-visible interaction states are identical to today:
-
-| Trigger | User-visible state | Behind the scenes (new) |
-|---|---|---|
-| Click "Close terminal" | Tab closes immediately | `terminal:kill` IPC → `Session.kill()` → `handleSubprocessExit` → `subprocess.dispose()` → `proc.destroy()` → fd released |
-| Shell exits naturally (`exit` / Ctrl-D) | Tab shows exit code | `handleSubprocessExit` → `subprocess.dispose()` → `proc.destroy()` → fd released |
-| Daemon is killed mid-session | Renderer reconnects cold on next app launch | On orderly shutdown: `TerminalHost.dispose()` loop → per-session `forceKillAndDisposeSubprocess()` — SIGKILL first (stubborn children reaped), then `proc.destroy()` releases the fd synchronously. Does not depend on the 5s `KILL_TIMEOUT_MS`. |
-| Child hits `Napi::Error` race | Silent (today) | Silent (same) — next teardown trigger reaches `subprocess.dispose()`, which forwards to `proc.destroy()` regardless of `dead` |
-| Session.kill hits `KILL_TIMEOUT_MS` | User sees "force-closed" log entry (unchanged) | `forceDispose` → `forceKill` + `subprocess.dispose()` → fd released |
-| SSH worktree session closed | Tab closes immediately | Relay `PtyHandler.shutdown` → SIGTERM + `managed.pty.destroy()` on exit → fd released on remote host |
-
-## Data flow
-
-```
-Renderer                 Main (IPC)                Daemon (TerminalHost)          node-pty
-   │                         │                            │                          │
-   │  terminal:kill          │                            │                          │
-   ├────────────────────────▶│   RPC: kill(sessionId)     │                          │
-   │                         ├───────────────────────────▶│  Session.kill()          │
-   │                         │                            ├─ subprocess.kill() ─────▶│  (SIGTERM)
-   │                         │                            │                          │
-   │                         │                            │◀── onExit(code) ─────────│
-   │                         │                            │  handleSubprocessExit    │
-   │                         │                            │  ├─ state='exited'       │
-   │                         │                            │  ├─ subprocess.dispose()─┼─▶ destroy() →
-   │                         │                            │  │                       │   _close() +
-   │                         │                            │  │                       │   _socket.destroy() +
-   │                         │                            │  │                       │   _writeStream.dispose()
-   │                         │                            │  │                       │   → ptmx fd released ✔
-   │                         │                            │  └─ fanout onExit        │
-   │                         │◀─── event: 'exit' ─────────│                          │
-   │◀── terminal:exit ───────│                            │                          │
-```
-
-### Failure paths
-
-**Natural exit.** Child dies, `proc` emits `onExit` → `handleSubprocessExit` → `subprocess.dispose()` → `proc.destroy()` → `_socket.destroy()` → fd released, same tick.
-
-**Explicit kill (`Session.kill`).** SIGTERM → child exits → same path as above.
-
-**Kill timeout.** Child ignores SIGTERM → `KILL_TIMEOUT_MS` elapses → `forceDispose` → `subprocess.forceKill()` (SIGKILL) + `subprocess.dispose()` (`proc.destroy()`). Fd released within 5s worst case.
-
-**Native throw.** `proc.write/resize/kill` throws `Napi::Error` → `dead = true`. Session is wedged but still reachable. The next teardown trigger (user close, daemon shutdown, worktree close) reaches `subprocess.dispose()`, which forwards to `proc.destroy()`. The destroy() body itself is try/catch-wrapped — if the native side is already half-torn-down and throws, we swallow; the socket side still gets destroyed by any prior event.
-
-**Daemon shutdown.** `TerminalHost.dispose()` iterates sessions and calls `session.forceKillAndDisposeSubprocess()` synchronously. The ordering is: SIGKILL (`subprocess.forceKill()` → `process.kill(pid, 'SIGKILL')`) → `subprocess.dispose()` → `proc.destroy()`. SIGKILL is not ignorable, so any child that would have survived the normal 5s `KILL_TIMEOUT_MS` SIGTERM window is reaped before the fd release. On POSIX, every `ptmx` fd is released before the daemon process exits. On Windows, `WindowsTerminal.destroy` defers via `_deferNoArgs` — dispose is enqueued but may not run synchronously; this is acceptable because ConPTY is not subject to the POSIX `ptmx` cap (see Risks).
-
-**Local provider (non-daemon).** `LocalPtyProvider.shutdown(id)` / `killAll()` / natural `onExit` all route through the new `destroyPtyProcess(proc)` helper, same `proc.destroy()` call. Fd released symmetrically with the daemon path.
-
-**Relay (SSH).** `PtyHandler.shutdown` and `PtyHandler.dispose` both call `managed.pty.destroy()` after the existing kill. On relay shutdown the loop is synchronous, so ptmx fds in the remote host's relay process are released before the relay exits.
-
-## Architectural fit
-
-```
-┌─ Daemon (forked) ───────────────┐   ┌─ Main process ─────────────┐   ┌─ Relay (remote host) ────┐
-│  TerminalHost                   │   │  LocalPtyProvider          │   │  PtyHandler              │
-│     └─ Session                  │   │     └─ ptyProcesses map    │   │     └─ ManagedPty map    │
-│         └─ SubprocessHandle     │   │         (proc.destroy ←NEW)│   │         (pty.destroy ←NEW)│
-│             └─ dispose() ←NEW   │   │                            │   │                          │
-│                 └─ proc.destroy()│   └────────────────────────────┘   └──────────────────────────┘
-└─────────────────────────────────┘           │                                 │
-              │                               └───────────┬─────────────────────┘
-              └───────────────┐                           │
-                              ▼                           ▼
-                   ┌──────────────────────────────────────────────┐
-                   │  node-pty destroy()                          │
-                   │   → _close() → _socket.destroy() → fd freed  │
-                   └──────────────────────────────────────────────┘
-```
-
-Three providers, one shared fix: forward the local dispose call to `node-pty.destroy()`. No new layer, no new dependency direction. Each provider already owns its handle lifecycle — we are filling a gap in three existing chains, not creating them.
-
-## Implementation plan
-
-### Files to change
-
-| File | Change |
-|---|---|
-| `src/main/daemon/session.ts` | Add `dispose(): void` to `SubprocessHandle` type. Add `forceKillAndDisposeSubprocess()` + `disposeSubprocess()` public methods. Add private `#teardownSubprocess()` helper that does NOT flip `_state` (see `dispose` section). Call `subprocess.dispose()` from `handleSubprocessExit`, `dispose`, `forceDispose`. Preserve the `wasTerminating = this._isTerminating && this._state !== 'exited'` invariant by capturing it BEFORE any state flip in the refactored `dispose`. |
-| `src/main/daemon/pty-subprocess.ts` | Implement `dispose()` on the returned handle. Idempotent. Nulls callbacks, sets `dead = true`, gates the `proc.kill = noop` neutralization on `process.platform !== 'win32'`, forwards to `(proc as unknown as { destroy?: () => void }).destroy?.()` in try/catch. |
-| `src/main/daemon/terminal-host.ts` | In `dispose()`, call `session.forceKillAndDisposeSubprocess()` instead of `session.kill()`. Preserves the SIGKILL-fallback behavior without depending on the 5s timer. |
-| `src/main/providers/local-pty-provider.ts` | Add `destroyPtyProcess(proc)` helper: gates `proc.kill = noop` neutralization on POSIX, then calls `proc.destroy()` in try/catch. Invoke from `safeKillAndClean`, `shutdown`, and the `onExit` path (after `clearPtyState`). |
-| `src/relay/pty-handler.ts` | Add `disposed: boolean` field to `ManagedPty`. In `wireAndStore`'s `onExit` (after map delete) and in `dispose()` loop, call `disposeManagedPty(managed)`. In `shutdown` immediate-path (after SIGKILL), call `disposeManagedPty`. In the 5s killTimer SIGKILL fallback (graceful path and spawn stale-context path), also call `disposeManagedPty`. Do **not** call it in the graceful SIGTERM branch. Guard `sendSignal`, `writeData`, `resize`, `getCwd`, `getInitialCwd`, `clearBuffer`, `hasChildProcesses`, `getForegroundProcess`, `attach` with `managed.disposed` checks (treat disposed as "not found"). |
-| `src/main/daemon/session.test.ts` | Add `dispose: vi.fn()` to `createMockSubprocess`. |
-| `src/main/daemon/terminal-host.test.ts` | Add `dispose: vi.fn()` to `createMockSubprocess`. |
-| `src/main/daemon/terminal-host-startup.test.ts` | Add `dispose: vi.fn()` to `mockSubprocess`. |
-| `src/main/daemon/production-launcher.test.ts` | Add `dispose: vi.fn()` to `createMockSubprocess`. |
-| `src/main/daemon/daemon-pty-provider.test.ts` | Add `dispose: vi.fn()` to `createMockSubprocess`. |
-| `src/main/daemon/reattach-snapshot.test.ts` | Add `dispose: vi.fn()` to `createMockSubprocess`. |
-| `src/main/daemon/__tests__/pty-fd-leak.test.ts` (new) | Integration test for the daemon path: spawn N sessions, tear them down via each path, assert fd count returns to baseline. |
-| `src/main/providers/__tests__/local-pty-fd-leak.test.ts` (new) | Same test, targeting `LocalPtyProvider` directly. |
-| `src/relay/__tests__/pty-fd-leak.test.ts` (new) | Same test, targeting `PtyHandler` directly. |
-
-### Testing plan
-
-The hard part of this fix is not the code — it's proving the leak is closed in all three providers. Two layers:
-
-#### 1. Unit-level handle behaviour
-
-Per provider, for each exit path (`kill`, `forceKill`, native throw simulated by calling `dispose` after an artificial dead state, natural exit), assert:
-
-- `proc.destroy()` is called exactly once per PTY (spy on the mock `IPty`).
-- Calling the provider's dispose a second time is a no-op (idempotency).
-- After dispose, subsequent `write/resize/kill` are no-ops and do not throw.
-- No `Napi::Error` surfaces from any follow-on method call.
-
-#### 2. Integration-level fd count
-
-One test file per provider (`src/main/daemon/__tests__/pty-fd-leak.test.ts`, `src/main/providers/__tests__/local-pty-fd-leak.test.ts`, `src/relay/__tests__/pty-fd-leak.test.ts`), same shape:
-
-```
-baseline = countPtmxFds(process.pid)
-for i in 1..50:
-  pty = provider.spawn(...)
-  provider.shutdown(pty.id)   // or forceKill / dispose / let it exit naturally
-  await exit event
-after = countPtmxFds(process.pid)
-assert after === baseline
-```
-
-Loop once per exit path per provider.
-
-**Platform-specific `countPtmxFds` implementation:**
-
-- **macOS:** `lsof -p <pid> -Ffn` → parse as (fd, name) pairs → count pairs whose fd is numeric (not `cwd`/`txt`/`rtd`) AND whose name is exactly `/dev/ptmx`. The `-Ffn` machine-readable mode emits one field per line prefixed with `f` (fd) or `n` (name); a naive `startsWith('n')` filter that doesn't cross-check the preceding `f` row false-matches on non-fd rows whose NAME happens to be `/dev/ptmx`. Never use `grep ptmx` unqualified — it false-matches on env vars and any path containing the substring.
-- **Linux:** iterate `/proc/<pid>/fd/*`, `readlink` each entry, match against the regex `/^(\/dev\/ptmx$|\/dev\/pts\/ptmx$|anon_inode:\[?ptmx\]?$)/`. The master pty fd does not show as `/dev/ptmx` on modern Linux kernels — depending on the pty backend and kernel version, `readlink` returns `anon_inode:[ptmx]` (devpts backend on many distros) or `/dev/pts/ptmx`. A naive `grep /dev/ptmx` yields zero matches and the test passes vacuously — **zero regression coverage** instead of real coverage. CI runs on `ubuntu-latest`; this matters.
-- **Windows:** skip entirely (ConPTY doesn't expose ptmx; rely on the unit-level `destroy()` spy).
-
-**Mandatory `beforeAll` counter smoke.** Before the first assertion, spawn one real PTY, measure `countPtmxFds`, kill it, measure again, and assert `beforeSpawn < afterSpawn` and `afterKill <= beforeSpawn`. If either check fails, the counter itself is broken on this platform — skip the whole suite with a clear message (`skip('ptmx counter not functional on this platform')`). Otherwise, the fd-count assertions could go green on a broken counter and we'd think the fix landed when it didn't.
-
-```ts
-beforeAll(async () => {
-  const baseline = countPtmxFds(process.pid)
-  const probe = pty.spawn('/bin/sh', ['-c', 'sleep 30'], { /* ... */ })
-  await new Promise((r) => setTimeout(r, 100))
-  const withProbe = countPtmxFds(process.pid)
-  probe.kill('SIGKILL')
-  await new Promise((r) => setTimeout(r, 200))
-  const afterKill = countPtmxFds(process.pid)
-  if (!(withProbe > baseline) || !(afterKill <= baseline)) {
-    // Why: if the counter can't even observe spawn/kill deltas on a known-good
-    // PTY, it can't observe the leak we're trying to prove closed. Vacuously
-    // passing assertions would give false confidence. Skip instead.
-    return describe.skip('ptmx counter smoke failed; skipping fd-leak suite')
-  }
-})
-```
-
-These tests spawn 50 real subprocesses each and must be gated behind an env-var skip (not a vitest tag — vitest 4 doesn't ship built-in tag filtering in this repo's config). Use `describe.skipIf(!process.env.RUN_SLOW_TESTS)`. Every spawn inside the loop must be wrapped in try/finally that force-kills the child regardless of assertion outcome — otherwise a mid-loop failure leaks the remaining subprocesses into the test runner, corrupting the next suite's baseline.
-
-#### 3. Manual verification
-
-Reproduce the reported 269/13 case locally:
-1. Start a fresh daemon.
-2. Baseline: `lsof -p $(pgrep -f daemon-entry) | grep -c ptmx` → small (one per live session).
-3. Churn: open and close 50 terminals via the UI.
-4. Verify the count returns to baseline within seconds. Before the fix, it stays at ~50.
-5. Repeat against a non-daemon worktree (LocalPtyProvider path) and against an SSH worktree (relay path).
-
-### Rollout
-
-No flag needed. The change is pure bug-fix with strictly smaller resource footprint. Ship with the orphan-daemon fix in the same release — they are complementary and together close the full leak story.
-
-### Regression surface
-
-| Regression | Mitigation |
-|---|---|
-| `dispose()` throws, breaking exit-code fanout to clients | Wrap every dispose call site in try/catch. `destroy()` call itself is also in try/catch inside the wrapper. |
-| `proc.destroy()` is not present on an older/forked node-pty build | Optional chain: `(proc as unknown as { destroy?: () => void }).destroy?.()`. Current pinned version has it on both UnixTerminal and WindowsTerminal; tests assert it's called. |
-| Double-dispose double-frees the native handle | Idempotency guard (`if (disposed) return`) at the top of dispose. node-pty's own `destroy()` is also safe to call twice — `_close()` is idempotent (it replaces `write`/`end` with no-ops and flips `_writable`/`_readable` to false the first time; the second call overwrites no-ops with no-ops). `_socket.destroy()` and `_writeStream.dispose()` are both idempotent per Node stream semantics. |
-| `dead` flag pattern regresses, `Napi::Error` kills daemon | All existing `dead`-guarded methods stay exactly as-is. `dispose()` sets `dead = true` and then calls `destroy()`; it adds to the pattern, does not replace it. |
-| Newly-nulled onData callback drops final data burst | Session already fans out synchronously in `handleSubprocessData` before exit. Nulling after exit is safe. |
-| Neutralizing `proc.kill` on Windows turns `destroy()` into a no-op (ConPTY leak) | `WindowsTerminal.destroy` calls `kill()` via `_deferNoArgs` — we gate neutralization on `process.platform !== 'win32'`. Verified in `pty-subprocess.ts` and `local-pty-provider.ts` and `relay/pty-handler.ts` helpers. Test: mock `process.platform = 'win32'`; assert `proc.kill` is NOT replaced with noop; assert `destroy()` is still called. |
-| Shared `#teardownSubprocess` helper flips `_state` before callers capture `wasTerminating`, orphaning stubborn children | Helper explicitly does NOT flip `_state`. Each public method (`dispose`, `disposeSubprocess`, `forceKillAndDisposeSubprocess`) owns its own `_state = 'exited'` line and captures any pre-flip invariants before calling the helper. Test: session with `_isTerminating=true`, `_state='running'` calls `dispose()`; assert `subprocess.forceKill()` is called before `subprocess.dispose()`. |
-| `sendSignal` / `writeData` / `resize` silently no-op after relay `onExit` neutralized `managed.pty.kill` | Every public entry point on `PtyHandler` that touches a `ManagedPty` checks `managed.disposed` first and treats disposed as "not found" (existing error path). Converts silent failure to an explicit error callers already handle. |
-| `TerminalHost.dispose()` drops 5s SIGKILL fallback for stubborn children | New `forceKillAndDisposeSubprocess` method explicitly sends SIGKILL via `subprocess.forceKill()` before releasing the fd. SIGKILL is not ignorable. Test: session whose child ignores SIGTERM; call `forceKillAndDisposeSubprocess`; assert child is reaped AND fd is released, both synchronously. |
-| LocalPtyProvider delivers trailing SIGHUP to recycled pid | `destroyPtyProcess(proc)` mirrors the daemon and relay helpers: POSIX-guarded `proc.kill = noop` neutralization before `destroy()`. Covers natural-exit, `safeKillAndClean`, and `shutdown` paths. |
-
-## Risks
-
-| Risk | Severity | Why acceptable |
-|---|---|---|
-| `destroy()` doesn't actually release the fd | Low | We are literally calling node-pty's canonical close path (`_close()` → `_socket.destroy()` → `_writeStream.dispose()`). Only way this is ineffective is a node-pty bug or a version regression — and the integration fd-count tests catch both before merge. |
-| Idempotent dispose hides a real double-free bug | Low | Idempotency only skips work; it does not suppress errors. |
-| `TerminalHost.dispose()` synchronous loop blocks daemon shutdown | Low | `destroy()` on each PTY is a handful of syscalls; 50 sessions ≈ single-digit ms. |
-| `destroy()` on Windows defers via `_deferNoArgs` | Low | ConPTY never hit the ptmx cap (it's a POSIX resource). Windows dispose is correctness-for-symmetry, not a load-bearing leak fix. |
-| The real leak is elsewhere (e.g., an fd leak outside the PTY code path) | Low | Integration tests directly measure fd reclamation across a full spawn/kill lifecycle. If the fix works there, it addresses the observed symptom. |
-
-## Related work (out of scope)
-
-- **Orphaned legacy daemons**: [auto-kill-old-daemons.md](./auto-kill-old-daemons.md) — complementary fix targeting daemon-level lifecycle.
-- **Worktree-delete does not kill sessions**: separate follow-up. Today, deleting a worktree from the sidebar leaves its PTY sessions live in the daemon, which is a different leak vector.
-- **Daemon fd observability**: expose an IPC `daemon:stats` handler so Orca can surface fd count in a debug view. Would let us detect regressions in production rather than waiting for user reports.
-- **Replace `node-pty`**: out of scope; see "Why not just replace node-pty" above.
diff --git a/docs/focus-follows-mouse-design.md b/docs/focus-follows-mouse-design.md
deleted file mode 100644
index c021af18e05..00000000000
--- a/docs/focus-follows-mouse-design.md
+++ /dev/null
@@ -1,350 +0,0 @@
-# Focus-Follows-Mouse for Terminal Panes
-
-**Status:** Draft
-**Date:** 2026-04-08
-
-## Summary
-
-Add a Ghostty-style `focus-follows-mouse` behavior to Orca's terminal panes: when enabled, hovering a split makes it the active pane (cursor focus + input routing + opacity update) without requiring a click. Scoped to splits within a single tab, default off, immediate on `mouseenter`. Safety guards preserve text selections, pane drags, window-focus semantics, and overlays.
-
-## Motivation
-
-Orca's terminal panes already borrow heavily from Ghostty's look and feel (themes, dividers, drag handles, close dialog, URL tooltip). Focus-follows-mouse is one of the few Ghostty interaction conventions Orca doesn't yet mirror. Users coming from Ghostty expect it; users who've never used it can leave the default off and see no change.
-
-## Scope
-
-**In scope:**
-
-- Hovering a terminal split in the current tab activates it when the setting is enabled.
-- A new `GlobalSettings.terminalFocusFollowsMouse` boolean persisted in user settings.
-- A new toggle in Settings → Terminal → Pane Styling.
-- Full unit test coverage of the gating logic.
-
-**Out of scope:**
-
-- Cross-tab hover activation (hovering a background tab does nothing).
-- Hovering non-terminal panes (file editor, source control, sidebars) — this setting only affects terminal splits.
-- Adjustable hover delay / settle time. Immediate switching matches Ghostty and is what users asking for Ghostty parity expect.
-- Migrating `PaneStyleOptions` into a split style-vs-behavior type. Bundling that refactor here would balloon the diff for marginal clarity. Left as a follow-up for when a second behavior flag lands.
-
-## Non-Goals
-
-- Cross-window focus. If Orca isn't the OS-focused window, hovering a pane must not switch focus.
-- Breaking existing click-to-focus. Clicking a pane must continue to work exactly as today; this feature is additive.
-
-## Design
-
-### Data model and settings plumbing
-
-**New field on `GlobalSettings`** (`src/shared/types.ts`):
-
-```ts
-terminalFocusFollowsMouse: boolean
-```
-
-**Default value** (`src/shared/constants.ts` → `getDefaultSettings`):
-
-```ts
-terminalFocusFollowsMouse: false
-```
-
-Default off matches Ghostty. Existing users upgrading receive the default automatically since `getDefaultSettings` is used as the fallback for missing fields on read — no migration needed.
-
-**Extension of `PaneStyleOptions`** (`src/renderer/src/lib/pane-manager/pane-manager-types.ts`):
-
-```ts
-export type PaneStyleOptions = {
-  splitBackground?: string
-  paneBackground?: string
-  inactivePaneOpacity?: number
-  activePaneOpacity?: number
-  opacityTransitionMs?: number
-  dividerThicknessPx?: number
-  // Why this behavior flag lives on "style" options: this type is already
-  // the single runtime-settings bag the PaneManager exposes. Splitting into
-  // separate style vs behavior types is a refactor worth its own change when
-  // a second behavior flag lands. See docs/focus-follows-mouse-design.md.
-  focusFollowsMouse?: boolean
-}
-```
-
-**Plumbing path** (same pattern already used by `terminalInactivePaneOpacity`):
-
-1. `GlobalSettings.terminalFocusFollowsMouse` — persisted
-2. `resolvePaneStyleOptions` in `src/renderer/src/lib/terminal-theme.ts:103` extracts the style-related fields from `GlobalSettings` and returns them. Add `'terminalFocusFollowsMouse'` to the `Pick<GlobalSettings, ...>` parameter union, and add `focusFollowsMouse: settings.terminalFocusFollowsMouse` to the returned object (no clamping needed — boolean pass-through, unlike the existing numeric fields that go through `clampNumber`).
-3. `applyTerminalAppearance` in `src/renderer/src/components/terminal-pane/terminal-appearance.ts:48` calls `manager.setPaneStyleOptions({...})` — add `focusFollowsMouse: paneStyles.focusFollowsMouse` to that object literal.
-4. `PaneManager.setPaneStyleOptions()` stores into `this.styleOptions`. The `handlePaneMouseEnter` method reads `this.styleOptions.focusFollowsMouse` fresh on every event, so toggling the setting takes effect immediately without re-wiring listeners.
-
-### Runtime event wiring
-
-**Pure gate helper** — extracted to a new file so it can be unit tested without a DOM.
-
-`src/renderer/src/lib/pane-manager/focus-follows-mouse.ts`:
-
-```ts
-export type FocusFollowsMouseInput = {
-  featureEnabled: boolean
-  activePaneId: number | null
-  hoveredPaneId: number
-  mouseButtons: number // from MouseEvent.buttons bitmask
-  windowHasFocus: boolean // from document.hasFocus()
-  managerDestroyed: boolean
-}
-
-/** Pure gate: returns true iff the hovered pane should be activated.
- *  Isolated from DOM so it can be unit-tested without an environment. */
-export function shouldFollowMouseFocus(input: FocusFollowsMouseInput): boolean {
-  if (!input.featureEnabled) return false
-  if (input.managerDestroyed) return false
-  if (input.activePaneId === input.hoveredPaneId) return false
-  // Why event.buttons !== 0: any held mouse button means a selection or a
-  // drag is in progress. Switching focus mid-drag would break xterm.js text
-  // selection and the pane drag-to-reorder flow. This single check also
-  // covers drag-to-reorder: the drag is always button-held, so buttons is
-  // always non-zero during it. No separate drag-state gate needed.
-  if (input.mouseButtons !== 0) return false
-  // Why document.hasFocus: if Orca isn't the OS-focused window, the mouse
-  // event is from the user passing through on their way to another app.
-  // We must not hijack focus in that case. Also returns false when DevTools
-  // is focused (DevTools runs in a separate WebContents) — accepted.
-  if (!input.windowHasFocus) return false
-  return true
-}
-```
-
-**Updated `createPaneDOM` signature** (`src/renderer/src/lib/pane-manager/pane-lifecycle.ts`):
-
-```ts
-export function createPaneDOM(
-  id: number,
-  options: PaneManagerOptions,
-  dragState: DragReorderState,
-  dragCallbacks: DragReorderCallbacks,
-  onPointerDown: (id: number) => void,
-  onMouseEnter: (id: number, event: MouseEvent) => void // NEW
-): ManagedPaneInternal
-```
-
-**New listener** attached in `createPaneDOM` next to the existing `pointerdown` listener:
-
-```ts
-container.addEventListener('mouseenter', (event) => {
-  onMouseEnter(id, event)
-})
-```
-
-The pane DOM layer stays dumb — it knows nothing about settings, active state, or window focus. All gating logic lives in the PaneManager callback.
-
-**PaneManager wiring** (`src/renderer/src/lib/pane-manager/pane-manager.ts`, inside `createPaneInternal`):
-
-```ts
-private createPaneInternal(): ManagedPaneInternal {
-  const id = this.nextPaneId++
-  const pane = createPaneDOM(
-    id,
-    this.options,
-    this.dragState,
-    this.getDragCallbacks(),
-    (paneId) => {
-      if (!this.destroyed && this.activePaneId !== paneId) {
-        this.setActivePane(paneId, { focus: true })
-      }
-    },
-    (paneId, event) => {
-      this.handlePaneMouseEnter(paneId, event)
-    }
-  )
-  this.panes.set(id, pane)
-  return pane
-}
-
-/** Focus-follows-mouse entry point. Collects gate inputs from the manager
- *  and delegates to the pure gate helper.
- *
- *  Invariant for future contributors: modal overlays (context menus, close
- *  dialogs, command palette) must be rendered as portals/siblings OUTSIDE
- *  the pane container. If a future overlay is rendered inside a .pane
- *  element, mouseenter will still fire on the pane underneath and this
- *  handler will incorrectly switch focus. Keep overlays out of the pane. */
-private handlePaneMouseEnter(paneId: number, event: MouseEvent): void {
-  if (
-    shouldFollowMouseFocus({
-      featureEnabled: this.styleOptions.focusFollowsMouse ?? false,
-      activePaneId: this.activePaneId,
-      hoveredPaneId: paneId,
-      mouseButtons: event.buttons,
-      windowHasFocus: document.hasFocus(),
-      managerDestroyed: this.destroyed
-    })
-  ) {
-    this.setActivePane(paneId, { focus: true })
-  }
-}
-```
-
-**Why no explicit drag-state gate:** An earlier draft of this design included a `dragSourcePaneId !== null` check as belt-and-suspenders. Verification against `src/renderer/src/lib/pane-manager/pane-drag-reorder.ts:77-103` showed it's strictly redundant:
-
-- The drag only activates while the user is holding a mouse button (pointerdown → drag threshold → pointerup). During that entire window, `event.buttons !== 0` on any mouseenter.
-- `dragSourcePaneId` is unconditionally cleared at line 101 inside the `if (dragging)` branch of the pointerup handler, so it cannot outlive a pointerup.
-- Therefore `mouseButtons !== 0` is sufficient on its own. Adding a second check would be dead code.
-
-### Settings UI
-
-**Placement** — under the existing "Pane Styling" section in `src/renderer/src/components/settings/TerminalPane.tsx`, below the `<div className="grid gap-4 md:grid-cols-2">` that holds Inactive Pane Opacity + Divider Thickness. The new toggle is a full-width row (toggles don't balance well next to numeric fields in a 2-column grid).
-
-**Toggle shape** — mirrors the existing `role="switch"` pattern used by e.g. "Nest Workspaces" in `GeneralPane.tsx`:
-
-```tsx
-<SearchableSetting
-  title="Focus Follows Mouse"
-  description="Hovering a terminal pane activates it without needing to click. Mirrors Ghostty's focus-follows-mouse setting."
-  keywords={['focus', 'follows', 'mouse', 'hover', 'pane', 'ghostty', 'active']}
-  className="flex items-center justify-between gap-4 px-1 py-2"
->
-  <div className="space-y-0.5">
-    <Label>Focus Follows Mouse</Label>
-    <p className="text-xs text-muted-foreground">
-      Hovering a terminal pane activates it without needing to click. Mirrors Ghostty&apos;s
-      focus-follows-mouse setting. Selections and window switching stay safe.
-    </p>
-  </div>
-  <button
-    role="switch"
-    aria-checked={settings.terminalFocusFollowsMouse}
-    onClick={() =>
-      updateSettings({
-        terminalFocusFollowsMouse: !settings.terminalFocusFollowsMouse
-      })
-    }
-    className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-colors ${
-      settings.terminalFocusFollowsMouse ? 'bg-foreground' : 'bg-muted-foreground/30'
-    }`}
-  >
-    <span
-      className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
-        settings.terminalFocusFollowsMouse ? 'translate-x-4' : 'translate-x-0.5'
-      }`}
-    />
-  </button>
-</SearchableSetting>
-```
-
-**Settings search integration** — add a new entry to `TERMINAL_PANE_STYLE_SEARCH_ENTRIES` in `src/renderer/src/components/settings/terminal-search.ts:34` (alongside "Inactive Pane Opacity" and "Divider Thickness"):
-
-```ts
-{
-  title: 'Focus Follows Mouse',
-  description: 'Hovering a terminal pane activates it without needing to click.',
-  keywords: ['focus', 'follows', 'mouse', 'hover', 'pane', 'ghostty', 'active']
-}
-```
-
-This surfaces the toggle in the settings search box for queries like "focus", "hover", or "ghostty". No changes needed to `TERMINAL_PANE_SEARCH_ENTRIES` (the aggregator) since it spreads `TERMINAL_PANE_STYLE_SEARCH_ENTRIES` automatically.
-
-### Edge cases
-
-**Gate-covered (code enforces):**
-
-| Case                            | Gate                                                                                                                                                                                                                   |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Mouse button held mid-selection | `mouseButtons !== 0`                                                                                                                                                                                                   |
-| Mid-drag-to-reorder             | `mouseButtons !== 0` (drag is always button-held)                                                                                                                                                                      |
-| Orca window unfocused (alt-tab) | `!document.hasFocus()`                                                                                                                                                                                                 |
-| DevTools panel focused          | `!document.hasFocus()` — DevTools runs in a separate WebContents so the main document loses focus. Feature pauses until DevTools is closed or the pane is clicked. Acceptable — same behavior as any other focus loss. |
-| Hover the already-active pane   | `activePaneId === hoveredPaneId`                                                                                                                                                                                       |
-| Manager destroyed mid-event     | `managerDestroyed`                                                                                                                                                                                                     |
-
-**Implicitly safe (relies on platform behavior, documented):**
-
-- **Context menus / close-confirm dialogs / command palette** — These render as React portals above the pane DOM. `mouseenter` does not reach the pane when an overlay is open. If a future contributor ever renders an overlay _inside_ the pane container, this assumption breaks — a code comment flags this.
-- **Tab / worktree switching** — Hidden PaneManagers' DOM doesn't receive events. No cross-manager interference possible.
-- **Single-pane layouts** — The `activePaneId === hoveredPaneId` early-return handles this with no special case.
-- **Right-click** — `contextmenu` doesn't trigger `mouseenter` (no boundary crossing). Existing right-click behavior is preserved.
-
-**Intentionally accepted quirks:**
-
-- **Setting toggled ON while hovering a non-active pane** → feature doesn't kick in until next `mouseenter`. User must wiggle the mouse. The fix (track last hovered pane and replay on setting change) adds persistent state for a rare case. Not worth it.
-- **Traversal flicker** (A → C via B on a three-pane layout) → briefly focuses B. Accepted as the cost of Ghostty-parity immediate switching. Confirmed during brainstorming.
-- **Window-resize-under-stationary-mouse** → if pane boundaries cross the cursor during a resize, focus can shift to the newly-hovered pane even though the user didn't move the mouse. Arguably correct; adding a "suppress during resize" gate introduces fragile state.
-
-### Error handling
-
-The mouseenter handler does no I/O, no promises, no external state lookups. No error surface worth defending:
-
-- `document.hasFocus()` — synchronous boolean, cannot throw
-- `event.buttons` — number, cannot throw
-- `this.styleOptions.focusFollowsMouse ?? false` — missing settings fail safe (feature off)
-- `setActivePane` — already handles pane-not-found silently at `pane-manager.ts:188`
-
-No try/catch added. If `setActivePane` throws, propagating to the window `error` handler is the correct failure mode — silently swallowing would hide a real bug.
-
-### Testing strategy
-
-**Constraint:** vitest runs with `environment: 'node'` (no jsdom). No synthetic event dispatch in automated tests.
-
-**1. Unit tests — `src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts`**
-
-Table of inputs against `shouldFollowMouseFocus`, one case per gate plus happy paths. Expected coverage: every branch.
-
-- Happy path: all gates pass → `true`
-- Feature disabled → `false`
-- Manager destroyed → `false`
-- Hover the already-active pane → `false`
-- Mouse button held (primary `buttons=1`, secondary `=2`, both `=3`) → `false` each
-- Window lacks OS focus → `false`
-- `activePaneId === null` (theoretically-unreachable defensive case — `createInitialPane` always sets `activePaneId` before mouse events are possible, but the gate logic must still behave correctly if this state ever occurs) → `true`
-
-**2. Manual smoke test checklist (PR description)**
-
-- [ ] Toggle persists across app restart.
-- [ ] Multi-split: hovering an inactive pane activates it.
-- [ ] Start text selection in pane A, drag into pane B. Selection extends normally; focus does NOT switch mid-drag.
-- [ ] Drag a pane by its drag-handle (the top strip that appears on hover). Release on a drop zone. Focus/activation does NOT flicker during the drag.
-- [ ] Cmd-Tab out, move mouse over a different Orca pane, Cmd-Tab back. Previously-active pane still active.
-- [ ] Open DevTools, focus the DevTools panel, move mouse over a different Orca pane. Focus does NOT switch. Close DevTools, wiggle mouse → focus-follows-mouse resumes.
-- [ ] Open close-terminal confirmation, hover a different pane. No focus shift.
-- [ ] Hover a URL in an inactive pane. Focus-follows-mouse activates the pane. Verify the `Cmd+click to open` URL tooltip still appears correctly on the newly-activated pane (tests for interaction between our `setActivePane → terminal.focus()` call and xterm.js's `WebLinksAddon` hover tracking).
-- [ ] Disable the setting. Hover does nothing; click still works.
-- [ ] Single-pane layout with the setting enabled. No crash, pane stays focused.
-- [ ] Three-pane layout, quick A→C sweep. Traversal flicker visible but tolerable.
-
-**Explicitly not tested:**
-
-- DOM event dispatch integration (no jsdom, not worth adding)
-- Settings UI render (no precedent in the codebase for per-control UI tests)
-- Electron's `document.hasFocus()` semantics (trust the platform)
-
-## Files Touched
-
-| File                                                               | Change                                                                                             |
-| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| `src/shared/types.ts`                                              | Add `terminalFocusFollowsMouse: boolean` to `GlobalSettings`                                       |
-| `src/shared/constants.ts`                                          | Default `terminalFocusFollowsMouse: false` in `getDefaultSettings`                                 |
-| `src/renderer/src/lib/pane-manager/pane-manager-types.ts`          | Add `focusFollowsMouse?: boolean` to `PaneStyleOptions` with a commented rationale                 |
-| `src/renderer/src/lib/pane-manager/focus-follows-mouse.ts`         | **New file.** Pure `shouldFollowMouseFocus` gate helper                                            |
-| `src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts`    | **New file.** Unit tests for the gate helper                                                       |
-| `src/renderer/src/lib/pane-manager/pane-lifecycle.ts`              | Add `onMouseEnter` param to `createPaneDOM`; attach `mouseenter` listener on pane container        |
-| `src/renderer/src/lib/pane-manager/pane-manager.ts`                | Pass new callback from `createPaneInternal`; add `handlePaneMouseEnter` private method             |
-| `src/renderer/src/components/settings/TerminalPane.tsx`            | Add `SearchableSetting` toggle under Pane Styling                                                  |
-| `src/renderer/src/components/settings/terminal-search.ts`          | Add entry to `TERMINAL_PANE_STYLE_SEARCH_ENTRIES`                                                  |
-| `src/renderer/src/lib/terminal-theme.ts`                           | Extend `resolvePaneStyleOptions` to pass `focusFollowsMouse` through                               |
-| `src/renderer/src/components/terminal-pane/terminal-appearance.ts` | Add `focusFollowsMouse: paneStyles.focusFollowsMouse` to the `setPaneStyleOptions` call at line 48 |
-
-## Build Order
-
-1. Add `terminalFocusFollowsMouse` to `GlobalSettings` type and default. Build passes; no behavior change.
-2. Add `focusFollowsMouse` to `PaneStyleOptions`. Build passes; no behavior change.
-3. Create `focus-follows-mouse.ts` pure helper + `focus-follows-mouse.test.ts`. Tests pass.
-4. Update `createPaneDOM` signature and wire `mouseenter` listener.
-5. Add `handlePaneMouseEnter` in `PaneManager` and the new callback in `createPaneInternal`.
-6. Thread `terminalFocusFollowsMouse → focusFollowsMouse` through `resolvePaneStyleOptions` and `applyTerminalAppearance`.
-7. Add the settings toggle UI in `TerminalPane.tsx` and the search entry in `terminal-search.ts`.
-8. Run the manual smoke test checklist against a local build.
-
-## Risks & Open Questions
-
-**Risk: traversal flicker on three-pane layouts may feel worse than expected.** Mitigation: the user explicitly chose immediate switching for Ghostty parity. If complaints arrive, adding a `terminalFocusFollowsMouseDelayMs` setting is a clean follow-up without schema breakage.
-
-**Risk: overlay assumption could break if a future contributor renders a modal inside the pane container.** Mitigation: a code comment on `handlePaneMouseEnter` documents the "overlays must live outside the pane container" invariant so it surfaces during review of any future overlay changes.
-
-**Open: should the setting description link to Ghostty's docs?** Currently the description just says "Mirrors Ghostty's focus-follows-mouse setting." No external link. If Orca's settings UI supports hyperlinks in descriptions elsewhere, we could link to Ghostty's config docs — otherwise leave as plain text. Not a blocker.
diff --git a/docs/focus-follows-mouse-plan.md b/docs/focus-follows-mouse-plan.md
deleted file mode 100644
index 36ad9519f74..00000000000
--- a/docs/focus-follows-mouse-plan.md
+++ /dev/null
@@ -1,837 +0,0 @@
-# Focus-Follows-Mouse Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a Ghostty-style `focus-follows-mouse` behavior to Orca's terminal panes. When enabled, hovering a split activates it (cursor focus, input routing, opacity update) without a click.
-
-**Architecture:** Extend `PaneStyleOptions` with a `focusFollowsMouse?: boolean` flag. Attach a `mouseenter` listener on each pane container in `createPaneDOM`. Delegate all gating logic to a pure `shouldFollowMouseFocus` helper (no DOM, unit-testable) that checks five gates: feature enabled, manager not destroyed, not already active, no mouse button held, window has OS focus. Thread the setting through the existing `resolvePaneStyleOptions → applyTerminalAppearance → setPaneStyleOptions` pipeline.
-
-**Tech Stack:** TypeScript, Electron (renderer), React (settings UI), xterm.js (terminal), vanilla DOM (PaneManager), vitest (tests, node environment).
-
-**Spec:** [docs/focus-follows-mouse-design.md](./focus-follows-mouse-design.md) — read this first for design rationale, edge case reasoning, and the full manual smoke test checklist.
-
----
-
-## File Structure
-
-**New files (2):**
-
-- `src/renderer/src/lib/pane-manager/focus-follows-mouse.ts` — Pure gate helper. Exports `FocusFollowsMouseInput` type and `shouldFollowMouseFocus(input)` function. Zero DOM dependencies.
-- `src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts` — Unit tests for the pure helper. Table-style assertions, one case per gate.
-
-**Modified files (9):**
-
-- `src/shared/types.ts` — Add `terminalFocusFollowsMouse: boolean` field to `GlobalSettings` type.
-- `src/shared/constants.ts` — Add `terminalFocusFollowsMouse: false` default in `getDefaultSettings`.
-- `src/renderer/src/lib/pane-manager/pane-manager-types.ts` — Add `focusFollowsMouse?: boolean` to `PaneStyleOptions`.
-- `src/renderer/src/lib/pane-manager/pane-lifecycle.ts` — Add `onMouseEnter` parameter to `createPaneDOM`, attach a `mouseenter` listener on the pane container.
-- `src/renderer/src/lib/pane-manager/pane-manager.ts` — Add `handlePaneMouseEnter` private method. Pass the new callback from `createPaneInternal`.
-- `src/renderer/src/lib/terminal-theme.ts` — Extend `resolvePaneStyleOptions` to pass `focusFollowsMouse` through.
-- `src/renderer/src/components/terminal-pane/terminal-appearance.ts` — Add `focusFollowsMouse: paneStyles.focusFollowsMouse` to the `setPaneStyleOptions` call.
-- `src/renderer/src/components/settings/TerminalPane.tsx` — Add a `SearchableSetting` toggle under Pane Styling.
-- `src/renderer/src/components/settings/terminal-search.ts` — Add an entry to `TERMINAL_PANE_STYLE_SEARCH_ENTRIES`.
-
-Each task below produces a standalone, type-checking commit. The sequence is chosen so the build stays green at every step.
-
----
-
-## Task 1: Add `terminalFocusFollowsMouse` to GlobalSettings
-
-**Files:**
-
-- Modify: `src/shared/types.ts` (insert field in `GlobalSettings` type around line 311)
-- Modify: `src/shared/constants.ts` (insert default in `getDefaultSettings` around line 83)
-
-Because `GlobalSettings` is an exact type, both the type declaration and the `getDefaultSettings` initializer must be updated together or `tsc` fails. Combine both edits in one commit.
-
-- [ ] **Step 1: Add the field to the GlobalSettings type**
-
-Edit `src/shared/types.ts`. Find the line with `terminalDividerThicknessPx: number` (near line 311) and add the new field immediately after it:
-
-```ts
-terminalDividerThicknessPx: number
-terminalFocusFollowsMouse: boolean
-terminalScrollbackBytes: number
-```
-
-- [ ] **Step 2: Add the default value in getDefaultSettings**
-
-Edit `src/shared/constants.ts`. Find the line `terminalDividerThicknessPx: 3,` in `getDefaultSettings` (near line 83) and add the default immediately after it:
-
-```ts
-    terminalDividerThicknessPx: 3,
-    terminalFocusFollowsMouse: false,
-    terminalScrollbackBytes: 10_000_000,
-```
-
-**Why default `false`:** Matches Ghostty's default. Existing users upgrading receive this default automatically because `src/main/persistence.ts:73-75` merges persisted settings over `defaults.settings` (`{ ...defaults.settings, ...parsed.settings }`), so any new field not in the persisted JSON falls through to the default. No explicit migration needed.
-
-- [ ] **Step 3: Run typecheck to verify both edits**
-
-Run: `pnpm run tc:web && pnpm run tc:node`
-Expected: Both pass. No output beyond the tsgo banner.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/shared/types.ts src/shared/constants.ts
-git commit -m "feat: add terminalFocusFollowsMouse to GlobalSettings (default off)"
-```
-
----
-
-## Task 2: Extend `PaneStyleOptions` with `focusFollowsMouse`
-
-**Files:**
-
-- Modify: `src/renderer/src/lib/pane-manager/pane-manager-types.ts` (line 23-30, the `PaneStyleOptions` type)
-
-- [ ] **Step 1: Add the field with a commented rationale**
-
-Edit `src/renderer/src/lib/pane-manager/pane-manager-types.ts`. Replace the existing `PaneStyleOptions` type definition (lines 23-30) with:
-
-```ts
-export type PaneStyleOptions = {
-  splitBackground?: string
-  paneBackground?: string
-  inactivePaneOpacity?: number
-  activePaneOpacity?: number
-  opacityTransitionMs?: number
-  dividerThicknessPx?: number
-  // Why this behavior flag lives on "style" options: this type is already
-  // the single runtime-settings bag the PaneManager exposes. Splitting into
-  // separate style vs behavior types is a refactor worth its own change
-  // when a second behavior flag lands. See docs/focus-follows-mouse-design.md.
-  focusFollowsMouse?: boolean
-}
-```
-
-- [ ] **Step 2: Run typecheck**
-
-Run: `pnpm run tc:web`
-Expected: Pass.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/renderer/src/lib/pane-manager/pane-manager-types.ts
-git commit -m "refactor: add focusFollowsMouse to PaneStyleOptions type"
-```
-
----
-
-## Task 3: Create the pure `shouldFollowMouseFocus` gate helper (TDD)
-
-**Files:**
-
-- Create: `src/renderer/src/lib/pane-manager/focus-follows-mouse.ts`
-- Create: `src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts`
-
-This is the only part of the feature with isolated business logic, so it's the only part we can TDD. We write the test file first, run it to see it fail, then create the implementation to make it pass.
-
-- [ ] **Step 1: Write the failing test file**
-
-Create `src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts` with the following contents:
-
-```ts
-import { describe, expect, it } from 'vitest'
-import { shouldFollowMouseFocus, type FocusFollowsMouseInput } from './focus-follows-mouse'
-
-describe('shouldFollowMouseFocus', () => {
-  // Base input where every gate passes. Individual tests flip one field
-  // at a time to assert that each gate blocks focus independently.
-  const base: FocusFollowsMouseInput = {
-    featureEnabled: true,
-    activePaneId: 1,
-    hoveredPaneId: 2,
-    mouseButtons: 0,
-    windowHasFocus: true,
-    managerDestroyed: false
-  }
-
-  it('switches focus when all gates pass', () => {
-    expect(shouldFollowMouseFocus(base)).toBe(true)
-  })
-
-  it('blocks when the feature is disabled', () => {
-    expect(shouldFollowMouseFocus({ ...base, featureEnabled: false })).toBe(false)
-  })
-
-  it('blocks when the manager is destroyed', () => {
-    expect(shouldFollowMouseFocus({ ...base, managerDestroyed: true })).toBe(false)
-  })
-
-  it('blocks when hovering the already-active pane', () => {
-    expect(shouldFollowMouseFocus({ ...base, hoveredPaneId: 1 })).toBe(false)
-  })
-
-  it('blocks while the primary mouse button is held (buttons=1)', () => {
-    expect(shouldFollowMouseFocus({ ...base, mouseButtons: 1 })).toBe(false)
-  })
-
-  it('blocks while the secondary mouse button is held (buttons=2)', () => {
-    expect(shouldFollowMouseFocus({ ...base, mouseButtons: 2 })).toBe(false)
-  })
-
-  it('blocks while multiple buttons are held (buttons=3)', () => {
-    expect(shouldFollowMouseFocus({ ...base, mouseButtons: 3 })).toBe(false)
-  })
-
-  it('blocks when the window does not have OS focus', () => {
-    expect(shouldFollowMouseFocus({ ...base, windowHasFocus: false })).toBe(false)
-  })
-
-  // Defensive case: createInitialPane always sets activePaneId before any
-  // mouse events are possible in production, but the gate must still behave
-  // correctly if the state ever occurs (e.g. future refactor of init flow).
-  it('switches when activePaneId is null (defensive)', () => {
-    expect(shouldFollowMouseFocus({ ...base, activePaneId: null })).toBe(true)
-  })
-})
-```
-
-- [ ] **Step 2: Run the test file to confirm it fails**
-
-Run: `pnpm exec vitest run src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts`
-Expected: FAIL with an error resolving `./focus-follows-mouse` (the implementation file doesn't exist yet).
-
-- [ ] **Step 3: Create the implementation file**
-
-Create `src/renderer/src/lib/pane-manager/focus-follows-mouse.ts` with the following contents:
-
-```ts
-/**
- * Pure decision logic for the focus-follows-mouse feature. Kept free of
- * DOM/event dependencies so it can be unit-tested under vitest's node env.
- *
- * See docs/focus-follows-mouse-design.md for rationale behind each gate.
- */
-
-export type FocusFollowsMouseInput = {
-  featureEnabled: boolean
-  activePaneId: number | null
-  hoveredPaneId: number
-  mouseButtons: number // MouseEvent.buttons bitmask
-  windowHasFocus: boolean // document.hasFocus()
-  managerDestroyed: boolean
-}
-
-/** Returns true iff the hovered pane should be activated. */
-export function shouldFollowMouseFocus(input: FocusFollowsMouseInput): boolean {
-  if (!input.featureEnabled) return false
-  if (input.managerDestroyed) return false
-  if (input.activePaneId === input.hoveredPaneId) return false
-  // Why event.buttons !== 0: any held mouse button means a selection or
-  // a drag is in progress. Switching focus mid-drag would break xterm.js
-  // text selection and the pane drag-to-reorder flow. This single check
-  // also covers drag-to-reorder, since the drag is always button-held.
-  // See pane-drag-reorder.ts:77-103 for the drag state lifecycle.
-  if (input.mouseButtons !== 0) return false
-  // Why document.hasFocus: if Orca isn't the OS-focused window, the mouse
-  // event is from the user passing through on their way to another app.
-  // Also returns false when DevTools is focused (DevTools runs in a
-  // separate WebContents) — accepted. Users close DevTools or click to
-  // resume normal behavior.
-  if (!input.windowHasFocus) return false
-  return true
-}
-```
-
-- [ ] **Step 4: Run the test file again to confirm all tests pass**
-
-Run: `pnpm exec vitest run src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts`
-Expected: PASS — 9 tests passing, 0 failing.
-
-- [ ] **Step 5: Run the full test suite to confirm nothing else broke**
-
-Run: `pnpm run test`
-Expected: All pre-existing tests still pass, plus the 9 new ones.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/renderer/src/lib/pane-manager/focus-follows-mouse.ts src/renderer/src/lib/pane-manager/focus-follows-mouse.test.ts
-git commit -m "feat: add pure shouldFollowMouseFocus gate helper"
-```
-
----
-
-## Task 4: Wire the `mouseenter` listener through `createPaneDOM` and `PaneManager`
-
-**Files:**
-
-- Modify: `src/renderer/src/lib/pane-manager/pane-lifecycle.ts` (update `createPaneDOM` signature around line 23-29, attach listener around line 126)
-- Modify: `src/renderer/src/lib/pane-manager/pane-manager.ts` (add import around line 28, update `createPaneInternal` around line 287, add `handlePaneMouseEnter` after it)
-
-Both files must be updated in the same commit: `createPaneDOM` gains a required parameter that its sole caller (`createPaneInternal`) must provide, so partial landings break the build.
-
-- [ ] **Step 1: Add the `onMouseEnter` parameter to `createPaneDOM`**
-
-Edit `src/renderer/src/lib/pane-manager/pane-lifecycle.ts`. Find the `createPaneDOM` function signature (around line 23-29) and update it:
-
-```ts
-export function createPaneDOM(
-  id: number,
-  options: PaneManagerOptions,
-  dragState: DragReorderState,
-  dragCallbacks: DragReorderCallbacks,
-  onPointerDown: (id: number) => void,
-  onMouseEnter: (id: number, event: MouseEvent) => void
-): ManagedPaneInternal {
-```
-
-- [ ] **Step 2: Attach the `mouseenter` listener next to the existing `pointerdown` listener**
-
-In the same file, find the existing `pointerdown` listener (around line 126):
-
-```ts
-// Focus handler: clicking a pane makes it active and explicitly focuses
-// the terminal. We must call focus: true here because after DOM reparenting
-// (e.g. splitPane moves the original pane into a flex container), xterm.js's
-// native click-to-focus on its internal textarea may not fire reliably.
-container.addEventListener('pointerdown', () => {
-  onPointerDown(id)
-})
-
-return pane
-```
-
-Replace it with:
-
-```ts
-// Focus handler: clicking a pane makes it active and explicitly focuses
-// the terminal. We must call focus: true here because after DOM reparenting
-// (e.g. splitPane moves the original pane into a flex container), xterm.js's
-// native click-to-focus on its internal textarea may not fire reliably.
-container.addEventListener('pointerdown', () => {
-  onPointerDown(id)
-})
-
-// Focus-follows-mouse handler: when the setting is enabled, hovering a
-// pane makes it active. All gating (feature flag, drag-in-progress,
-// window focus, etc.) lives in the PaneManager callback — this layer
-// just forwards the event.
-container.addEventListener('mouseenter', (event) => {
-  onMouseEnter(id, event)
-})
-
-return pane
-```
-
-- [ ] **Step 3: Import the gate helper in `pane-manager.ts`**
-
-Edit `src/renderer/src/lib/pane-manager/pane-manager.ts`. Find the existing imports (around line 20-28) and add a new import immediately after the existing pane-manager-related imports:
-
-```ts
-import { createPaneDOM, openTerminal, attachWebgl, disposePane } from './pane-lifecycle'
-import { shouldFollowMouseFocus } from './focus-follows-mouse'
-import {
-  findPaneChildren,
-  removeDividers,
-  promoteSibling,
-  wrapInSplit,
-  safeFit,
-  refitPanesUnder
-} from './pane-tree-ops'
-```
-
-- [ ] **Step 4: Pass the new callback from `createPaneInternal`**
-
-In the same file, find the `createPaneInternal` method (around line 287-302):
-
-```ts
-  private createPaneInternal(): ManagedPaneInternal {
-    const id = this.nextPaneId++
-    const pane = createPaneDOM(
-      id,
-      this.options,
-      this.dragState,
-      this.getDragCallbacks(),
-      (paneId) => {
-        if (!this.destroyed && this.activePaneId !== paneId) {
-          this.setActivePane(paneId, { focus: true })
-        }
-      }
-    )
-    this.panes.set(id, pane)
-    return pane
-  }
-```
-
-Replace it with:
-
-```ts
-  private createPaneInternal(): ManagedPaneInternal {
-    const id = this.nextPaneId++
-    const pane = createPaneDOM(
-      id,
-      this.options,
-      this.dragState,
-      this.getDragCallbacks(),
-      (paneId) => {
-        if (!this.destroyed && this.activePaneId !== paneId) {
-          this.setActivePane(paneId, { focus: true })
-        }
-      },
-      (paneId, event) => {
-        this.handlePaneMouseEnter(paneId, event)
-      }
-    )
-    this.panes.set(id, pane)
-    return pane
-  }
-
-  /**
-   * Focus-follows-mouse entry point. Collects gate inputs from the manager
-   * and delegates to the pure gate helper.
-   *
-   * Invariant for future contributors: modal overlays (context menus, close
-   * dialogs, command palette) must be rendered as portals/siblings OUTSIDE
-   * the pane container. If a future overlay is ever rendered inside a .pane
-   * element, mouseenter will still fire on the pane underneath and this
-   * handler will incorrectly switch focus. Keep overlays out of the pane.
-   */
-  private handlePaneMouseEnter(paneId: number, event: MouseEvent): void {
-    if (
-      shouldFollowMouseFocus({
-        featureEnabled: this.styleOptions.focusFollowsMouse ?? false,
-        activePaneId: this.activePaneId,
-        hoveredPaneId: paneId,
-        mouseButtons: event.buttons,
-        windowHasFocus: document.hasFocus(),
-        managerDestroyed: this.destroyed
-      })
-    ) {
-      this.setActivePane(paneId, { focus: true })
-    }
-  }
-```
-
-- [ ] **Step 5: Run typecheck to verify both files**
-
-Run: `pnpm run tc:web`
-Expected: Pass. If it fails with "Expected 6 arguments, but got 5" at `createPaneDOM`, you forgot to update the caller in `createPaneInternal`.
-
-- [ ] **Step 6: Run the full test suite**
-
-Run: `pnpm run test`
-Expected: All tests pass, including the 9 from Task 3.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/renderer/src/lib/pane-manager/pane-lifecycle.ts src/renderer/src/lib/pane-manager/pane-manager.ts
-git commit -m "feat: wire mouseenter listener through PaneManager for focus-follows-mouse"
-```
-
----
-
-## Task 5: Thread the setting through `resolvePaneStyleOptions` and `applyTerminalAppearance`
-
-**Files:**
-
-- Modify: `src/renderer/src/lib/terminal-theme.ts` (around line 103-120)
-- Modify: `src/renderer/src/components/terminal-pane/terminal-appearance.ts` (around line 48-55)
-
-At this point the gate helper reads `this.styleOptions.focusFollowsMouse`, which is always `undefined` because nothing populates it yet. This task plumbs the user setting into the runtime options bag.
-
-- [ ] **Step 1: Extend `resolvePaneStyleOptions` to accept and pass the boolean**
-
-**Callers of `resolvePaneStyleOptions`** (verified via grep — there are two, both pass a full `GlobalSettings` so widening the `Pick` union is non-breaking):
-
-1. `src/renderer/src/components/terminal-pane/terminal-appearance.ts:21` — the runtime call from `applyTerminalAppearance`. You WILL modify this file in Step 2.
-2. `src/renderer/src/components/settings/TerminalPane.tsx:68` — the settings-pane preview call that powers the theme preview. You will NOT need to modify this file in this task (it passes full `GlobalSettings`, which will contain `terminalFocusFollowsMouse` after Task 1). The new field will silently appear in the returned object and be ignored by the preview — that's fine.
-
-Edit `src/renderer/src/lib/terminal-theme.ts`. Find the `resolvePaneStyleOptions` function (lines 103-118). The current full body is:
-
-```ts
-export function resolvePaneStyleOptions(
-  settings: Pick<
-    GlobalSettings,
-    | 'terminalInactivePaneOpacity'
-    | 'terminalActivePaneOpacity'
-    | 'terminalPaneOpacityTransitionMs'
-    | 'terminalDividerThicknessPx'
-  >
-) {
-  return {
-    inactivePaneOpacity: clampNumber(settings.terminalInactivePaneOpacity, 0, 1),
-    activePaneOpacity: clampNumber(settings.terminalActivePaneOpacity, 0, 1),
-    opacityTransitionMs: clampNumber(settings.terminalPaneOpacityTransitionMs, 0, 5000),
-    dividerThicknessPx: clampNumber(settings.terminalDividerThicknessPx, 1, 32)
-  }
-}
-```
-
-Replace it with:
-
-```ts
-export function resolvePaneStyleOptions(
-  settings: Pick<
-    GlobalSettings,
-    | 'terminalInactivePaneOpacity'
-    | 'terminalActivePaneOpacity'
-    | 'terminalPaneOpacityTransitionMs'
-    | 'terminalDividerThicknessPx'
-    | 'terminalFocusFollowsMouse'
-  >
-) {
-  return {
-    inactivePaneOpacity: clampNumber(settings.terminalInactivePaneOpacity, 0, 1),
-    activePaneOpacity: clampNumber(settings.terminalActivePaneOpacity, 0, 1),
-    opacityTransitionMs: clampNumber(settings.terminalPaneOpacityTransitionMs, 0, 5000),
-    dividerThicknessPx: clampNumber(settings.terminalDividerThicknessPx, 1, 32),
-    // Why no clamping: boolean pass-through. Both true and false are valid.
-    focusFollowsMouse: settings.terminalFocusFollowsMouse
-  }
-}
-```
-
-- [ ] **Step 2: Pass `focusFollowsMouse` to `setPaneStyleOptions` in `applyTerminalAppearance`**
-
-Edit `src/renderer/src/components/terminal-pane/terminal-appearance.ts`. Find the `setPaneStyleOptions` call (around line 48-55):
-
-```ts
-manager.setPaneStyleOptions({
-  splitBackground: paneBackground,
-  paneBackground,
-  inactivePaneOpacity: paneStyles.inactivePaneOpacity,
-  activePaneOpacity: paneStyles.activePaneOpacity,
-  opacityTransitionMs: paneStyles.opacityTransitionMs,
-  dividerThicknessPx: paneStyles.dividerThicknessPx
-})
-```
-
-Replace it with:
-
-```ts
-manager.setPaneStyleOptions({
-  splitBackground: paneBackground,
-  paneBackground,
-  inactivePaneOpacity: paneStyles.inactivePaneOpacity,
-  activePaneOpacity: paneStyles.activePaneOpacity,
-  opacityTransitionMs: paneStyles.opacityTransitionMs,
-  dividerThicknessPx: paneStyles.dividerThicknessPx,
-  focusFollowsMouse: paneStyles.focusFollowsMouse
-})
-```
-
-- [ ] **Step 3: Run typecheck**
-
-Run: `pnpm run tc:web`
-Expected: Pass. If it fails saying `paneStyles.focusFollowsMouse` is not assignable (e.g. `undefined` vs `boolean`), double-check that Step 1 added the field to `resolvePaneStyleOptions`'s returned object.
-
-- [ ] **Step 4: Run the full test suite**
-
-Run: `pnpm run test`
-Expected: All tests pass.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/renderer/src/lib/terminal-theme.ts src/renderer/src/components/terminal-pane/terminal-appearance.ts
-git commit -m "feat: thread focusFollowsMouse through pane-style pipeline"
-```
-
-**At this point the feature is functionally complete internally.** If a developer manually flipped `terminalFocusFollowsMouse: true` in the persisted settings file, it would work. Tasks 6 and 7 add the discoverable user-facing surface.
-
----
-
-## Task 6: Add the settings toggle UI in TerminalPane.tsx
-
-**Files:**
-
-- Modify: `src/renderer/src/components/settings/TerminalPane.tsx` (disable comment at line 1; toggle insertion around line 290, the closing of the Pane Styling grid)
-
-**⚠️ Line-count constraint:** `TerminalPane.tsx` is currently exactly 400 lines total (and oxlint passes, so effective non-blank/non-comment lines are ≤ 400). The project's `.oxlintrc.json` sets `max-lines: 400` for `.tsx` files (line 71). Adding the new toggle (~33 lines) would push the file over the limit and the commit in Step 3 would fail under the lint-staged `oxlint` pre-commit hook.
-
-**The project's established workaround** is a file-scoped `eslint-disable` comment with justification — see `src/renderer/src/components/settings/GeneralPane.tsx:1-3`, which does the same for the same reason (484 lines, all owning general settings UI). Step 1 below applies this pattern to `TerminalPane.tsx` _before_ adding the toggle, so the file never goes over the limit.
-
-- [ ] **Step 1: Add the `max-lines` eslint-disable at the top of TerminalPane.tsx**
-
-Edit `src/renderer/src/components/settings/TerminalPane.tsx`. The file currently starts with:
-
-```tsx
-import { useState } from 'react'
-import type { GlobalSettings } from '../../../../shared/types'
-```
-
-Prepend a file-level disable comment with an explicit justification (matching the `GeneralPane.tsx` precedent):
-
-```tsx
-/* eslint-disable max-lines -- Why: TerminalPane is the single owner of all terminal settings UI;
-   splitting individual settings into separate files would scatter related controls without a
-   meaningful abstraction boundary. Mirrors the same decision made for GeneralPane.tsx. */
-import { useState } from 'react'
-import type { GlobalSettings } from '../../../../shared/types'
-```
-
-- [ ] **Step 2: Add the `SearchableSetting` toggle below the Pane Styling grid**
-
-Edit `src/renderer/src/components/settings/TerminalPane.tsx`. Find the end of the Pane Styling grid (around line 290):
-
-```tsx
-          <SearchableSetting
-            title="Divider Thickness"
-            description="Thickness of the pane divider line."
-            keywords={['pane', 'divider', 'thickness']}
-          >
-            <NumberField
-              label="Divider Thickness"
-              description="Thickness of the pane divider line."
-              value={paneStyleOptions.dividerThicknessPx}
-              defaultValue={1}
-              min={1}
-              max={32}
-              step={1}
-              suffix="px"
-              onChange={(value) =>
-                updateSettings({
-                  terminalDividerThicknessPx: clampNumber(value, 1, 32)
-                })
-              }
-            />
-          </SearchableSetting>
-        </div>
-      </section>
-```
-
-Insert a new `SearchableSetting` toggle between the closing `</div>` of the grid and the closing `</section>`:
-
-```tsx
-          <SearchableSetting
-            title="Divider Thickness"
-            description="Thickness of the pane divider line."
-            keywords={['pane', 'divider', 'thickness']}
-          >
-            <NumberField
-              label="Divider Thickness"
-              description="Thickness of the pane divider line."
-              value={paneStyleOptions.dividerThicknessPx}
-              defaultValue={1}
-              min={1}
-              max={32}
-              step={1}
-              suffix="px"
-              onChange={(value) =>
-                updateSettings({
-                  terminalDividerThicknessPx: clampNumber(value, 1, 32)
-                })
-              }
-            />
-          </SearchableSetting>
-        </div>
-
-        <SearchableSetting
-          title="Focus Follows Mouse"
-          description="Hovering a terminal pane activates it without needing to click. Mirrors Ghostty's focus-follows-mouse setting."
-          keywords={['focus', 'follows', 'mouse', 'hover', 'pane', 'ghostty', 'active']}
-          className="flex items-center justify-between gap-4 px-1 py-2"
-        >
-          <div className="space-y-0.5">
-            <Label>Focus Follows Mouse</Label>
-            <p className="text-xs text-muted-foreground">
-              Hovering a terminal pane activates it without needing to click.
-              Mirrors Ghostty&apos;s focus-follows-mouse setting. Selections and
-              window switching stay safe.
-            </p>
-          </div>
-          <button
-            role="switch"
-            aria-checked={settings.terminalFocusFollowsMouse}
-            onClick={() =>
-              updateSettings({
-                terminalFocusFollowsMouse: !settings.terminalFocusFollowsMouse
-              })
-            }
-            className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-colors ${
-              settings.terminalFocusFollowsMouse ? 'bg-foreground' : 'bg-muted-foreground/30'
-            }`}
-          >
-            <span
-              className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
-                settings.terminalFocusFollowsMouse ? 'translate-x-4' : 'translate-x-0.5'
-              }`}
-            />
-          </button>
-        </SearchableSetting>
-      </section>
-```
-
-**Placement rationale:** The new toggle sits _below_ the existing 2-column `grid` (not inside it) because a full-width toggle row doesn't balance well next to numeric input fields in a 2-column layout.
-
-- [ ] **Step 3: Run typecheck and lint**
-
-Run: `pnpm run tc:web && pnpm exec oxlint src/renderer/src/components/settings/TerminalPane.tsx`
-Expected: Both pass with 0 errors. The explicit `oxlint` run is a safety net: if the file somehow still trips `max-lines` (e.g., the disable comment was formatted incorrectly), catch it here rather than in the pre-commit hook.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/renderer/src/components/settings/TerminalPane.tsx
-git commit -m "feat: add Focus Follows Mouse toggle to Terminal settings"
-```
-
----
-
-## Task 7: Add the settings search entry
-
-**Files:**
-
-- Modify: `src/renderer/src/components/settings/terminal-search.ts` (around line 34-45, the `TERMINAL_PANE_STYLE_SEARCH_ENTRIES` array)
-
-- [ ] **Step 1: Add the new entry to `TERMINAL_PANE_STYLE_SEARCH_ENTRIES`**
-
-Edit `src/renderer/src/components/settings/terminal-search.ts`. Find `TERMINAL_PANE_STYLE_SEARCH_ENTRIES` (around line 34):
-
-```ts
-export const TERMINAL_PANE_STYLE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
-  {
-    title: 'Inactive Pane Opacity',
-    description: 'Opacity applied to panes that are not currently active.',
-    keywords: ['pane', 'opacity', 'dimming']
-  },
-  {
-    title: 'Divider Thickness',
-    description: 'Thickness of the pane divider line.',
-    keywords: ['pane', 'divider', 'thickness']
-  }
-]
-```
-
-Replace it with:
-
-```ts
-export const TERMINAL_PANE_STYLE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
-  {
-    title: 'Inactive Pane Opacity',
-    description: 'Opacity applied to panes that are not currently active.',
-    keywords: ['pane', 'opacity', 'dimming']
-  },
-  {
-    title: 'Divider Thickness',
-    description: 'Thickness of the pane divider line.',
-    keywords: ['pane', 'divider', 'thickness']
-  },
-  {
-    title: 'Focus Follows Mouse',
-    description: 'Hovering a terminal pane activates it without needing to click.',
-    keywords: ['focus', 'follows', 'mouse', 'hover', 'pane', 'ghostty', 'active']
-  }
-]
-```
-
-**Note:** No changes needed to `TERMINAL_PANE_SEARCH_ENTRIES` (the aggregator at line 86) because it spreads `TERMINAL_PANE_STYLE_SEARCH_ENTRIES` automatically.
-
-- [ ] **Step 2: Run typecheck and tests**
-
-Run: `pnpm run tc:web && pnpm run test`
-Expected: Both pass.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/renderer/src/components/settings/terminal-search.ts
-git commit -m "feat: add Focus Follows Mouse to settings search index"
-```
-
----
-
-## Task 8: Manual smoke test verification
-
-This task does not produce a commit. It verifies the feature end-to-end in a running build and catches any issue that couldn't be caught by typecheck or unit tests (DOM event interactions, xterm.js behavior, Electron window focus, visual correctness).
-
-- [ ] **Step 1: Launch the app in dev mode**
-
-Run: `pnpm run dev`
-Expected: Orca opens. Wait for it to fully initialize (worktree list populates).
-
-- [ ] **Step 2: Enable the setting**
-
-Open Settings (gear icon or menu) → Terminal → Pane Styling. Find the "Focus Follows Mouse" toggle. Toggle it ON.
-
-Expected: The toggle visibly flips to the on state (dark background, white dot on the right).
-
-- [ ] **Step 3: Restart the app and verify persistence**
-
-Close Orca. Run `pnpm run dev` again. Open Settings → Terminal → Pane Styling.
-
-Expected: The toggle is still ON (the setting persisted to the JSON state file).
-
-- [ ] **Step 4: Verify multi-split hover activation**
-
-Open a worktree with a terminal. Create at least 2 splits (use the split-pane UI or keyboard shortcut). Click on pane A to make it active. Move the mouse over pane B without clicking.
-
-Expected: Pane B's opacity updates to the active value, pane B's cursor starts blinking, and typing on the keyboard routes to pane B's shell.
-
-- [ ] **Step 5: Verify text selection is not broken mid-drag**
-
-In a single pane, click-drag to select text. Start the drag in pane A and continue dragging the selection into pane B.
-
-Expected: The text selection extends normally. Focus does NOT switch from pane A to pane B during the drag. When you release the mouse button, the selection is finalized in pane A. (If focus switches mid-drag, the `mouseButtons !== 0` gate is broken.)
-
-- [ ] **Step 6: Verify pane drag-to-reorder is not broken**
-
-Hover a pane so the drag handle (the top strip) appears. Click-drag the pane by its drag handle to a drop zone.
-
-Expected: The drag animation completes normally. No focus flicker during the drag.
-
-- [ ] **Step 7: Verify window-focus gating with Cmd-Tab**
-
-With 2+ splits and the setting enabled: click pane A to make it active. Cmd-Tab to another app. Move the mouse over pane B (still visible). Cmd-Tab back to Orca.
-
-Expected: Pane A (the previously-active pane) is still active — focus did NOT switch to pane B just because the mouse was over it when Orca regained focus.
-
-- [ ] **Step 8: Verify DevTools focus pauses the feature**
-
-With 2+ splits, open Orca DevTools (View → Toggle Developer Tools, or Cmd-Opt-I). Click inside the DevTools panel to focus it. Move the mouse over an inactive pane.
-
-Expected: Focus does NOT switch. `document.hasFocus()` returns false while DevTools is focused, so the gate blocks. Close DevTools, wiggle the mouse → focus-follows-mouse resumes on the next `mouseenter`.
-
-- [ ] **Step 9: Verify modal overlay safety**
-
-With 2+ splits, open the close-terminal confirmation dialog (Cmd-W or the close button on a pane). While the confirmation dialog is visible, move the mouse over a different pane.
-
-Expected: Focus does NOT switch. The modal portal sits above the pane DOM, so `mouseenter` on the pane never fires while the modal is open.
-
-- [ ] **Step 10: Verify URL hover tooltip still works**
-
-With the setting ON, hover a URL in an inactive pane (run `echo https://example.com` in one pane, then hover that URL from another pane).
-
-Expected: (1) The pane activates via focus-follows-mouse. (2) The `Cmd+click to open` URL tooltip appears in the bottom-left of the newly-activated pane. (If the tooltip fails to appear or flickers, there's an interaction issue between `setActivePane → terminal.focus()` and xterm.js's `WebLinksAddon` hover tracking — worth filing and debugging separately.)
-
-- [ ] **Step 11: Verify disabling the setting stops the behavior**
-
-Toggle the setting OFF in Settings. Return to the terminal view. Hover an inactive pane.
-
-Expected: Focus does NOT switch on hover. Click on the pane — the click still activates it. (Disabling the feature must not regress click-to-focus.)
-
-- [ ] **Step 12: Verify single-pane layout has no regressions**
-
-Close all splits so only one pane remains. Toggle the setting ON. Hover the pane.
-
-Expected: No crash, no console errors. The single pane stays focused. (The `activePaneId === hoveredPaneId` gate makes this a no-op.)
-
-- [ ] **Step 13: Verify three-pane traversal flicker (informational)**
-
-Create a horizontal layout of 3 panes: A | B | C. Click pane A. Move the mouse quickly from A straight to C.
-
-Expected: A brief flicker of activation on B as the mouse traverses it (this is the accepted cost of Ghostty-parity immediate switching, documented in the spec). Confirm the flicker is tolerable. If it feels bad, the spec has a follow-up plan for adding a settle delay.
-
-- [ ] **Step 14: Mark the plan complete**
-
-If all 13 checks above passed, the feature is complete. The PR description should embed this smoke test checklist for the reviewer to verify.
-
----
-
-## Verification Summary
-
-After all 8 tasks are complete, the final state should be:
-
-- 7 new commits on the branch (one per task, Task 8 is verify-only).
-- 9 new unit tests passing (`focus-follows-mouse.test.ts`).
-- Full typecheck passes (`pnpm run tc`).
-- Full test suite passes (`pnpm run test`).
-- Manual smoke test checklist (Task 8 Steps 1-13) passes in `pnpm run dev`.
-- The setting is discoverable via Settings → Terminal → Pane Styling AND via the settings search box (queries: "focus", "follows", "mouse", "hover", "ghostty").
-- The setting defaults to **off** for both new and upgrading users.
diff --git a/docs/homebrew-cask.md b/docs/homebrew-cask.md
deleted file mode 100644
index 3292115c2d5..00000000000
--- a/docs/homebrew-cask.md
+++ /dev/null
@@ -1,90 +0,0 @@
-# Homebrew Cask
-
-Orca is distributed on macOS as a Homebrew Cask. This doc covers how the cask
-is wired up, how it interacts with Orca's in-app updater, and what to do when
-something drifts.
-
-## For users
-
-```bash
-brew tap stablyai/orca
-brew install --cask orca
-```
-
-Or in one command: `brew install --cask stablyai/orca/orca`. Both forms install
-`Orca.app` into `/Applications`. Subsequent updates are handled by Orca's
-in-app updater (electron-updater) — `brew upgrade` is a no-op because the
-cask is marked `auto_updates true`. Users who want brew to force-reinstall
-from the cask version can pass `--greedy`.
-
-## How the pieces fit together
-
-There are three moving parts:
-
-1. **`Casks/orca.rb`** in this repo — source of truth for the cask file.
-   Edited by automation on every stable release; can be edited manually if
-   metadata (zap list, macOS floor, desc) needs to change.
-2. **`stablyai/homebrew-orca`** — the public tap users consume. Mirrors
-   `Casks/orca.rb` from this repo via the bump workflow. Nothing else lives
-   there; do not hand-edit.
-3. **`.github/workflows/homebrew-bump.yml`** — runs on `release.published`
-   for stable tags (skips `-rc.*` and GitHub pre-releases). Downloads the
-   two DMGs, rewrites `version`/`sha256` in `Casks/orca.rb`, pushes a PR to
-   the tap, and auto-merges it.
-
-### Why the cask uses `auto_updates true`
-
-`electron-updater` (`src/main/updater.ts`) downloads each new release and
-swaps `Orca.app` in place. Homebrew-Cask's tracking of installed versions is
-based on the cask's `version:` field plus an install receipt — so when the
-app mutates itself, brew's metadata drifts. `auto_updates true` tells
-Homebrew this is expected: `brew outdated` and `brew upgrade` ignore the
-cask unless `--greedy` is passed. Uninstall still works normally.
-
-The hidden requirement: Squirrel.Mac (what electron-updater uses) needs
-write access to `/Applications/Orca.app`. Cask installs into `/Applications`
-with user ownership by default, so this works out of the box. If a user ever
-`sudo`-installs or the bundle becomes root-owned, the in-app updater will
-fail silently; they'd need `brew reinstall --cask orca` or `brew upgrade
---cask orca --greedy` to recover.
-
-## One-time setup (already done, documented here for reference)
-
-1. **Tap repo**: `stablyai/homebrew-orca` on GitHub. Must be named
-   `homebrew-<anything>` so `brew tap stablyai/orca` resolves. Public.
-2. **Auto-merge** enabled in tap repo settings.
-3. **Seeded** with a copy of `Casks/orca.rb` for the initial version.
-
-The workflow authenticates as the existing `buf0-bot` GitHub App
-(installed org-wide on stablyai), reusing the `BUFO_BOT_PRIVATE_KEY`
-secret that's already on `stablyai/orca` for `track-community-prs.yaml`.
-No PAT rotation, no new secret.
-
-## Submitting to homebrew-cask (the main tap)
-
-The `stablyai/homebrew-orca` tap ships first. Once Orca has stable user
-demand and has been on a release cadence for ~30+ days without the version
-string breaking conventions (no `-rc`, no date suffixes), we can submit to
-`Homebrew/homebrew-cask` so users can `brew install --cask orca` without a
-tap prefix. That submission is a one-time PR against
-https://github.com/Homebrew/homebrew-cask; subsequent bumps to the main tap
-are handled by their own [autobump infrastructure](https://docs.brew.sh/Autobump)
-as long as the release cadence matches their expectations. T3 Code's
-[cask](https://github.com/Homebrew/homebrew-cask/blob/main/Casks/t/t3-code.rb)
-is a close structural analogue.
-
-## Troubleshooting
-
-- **"electron-updater says no update available, but brew says I'm out of
-  date"** — expected if the user ran `brew upgrade --greedy` or installed
-  the cask before the in-app updater picked up a newer release. The
-  `auto_updates true` flag usually prevents this; if a user reports it,
-  check that their cask file still has the marker.
-- **Bump workflow failed to PR the tap** — verify the `buf0-bot` app is
-  still installed on `stablyai/homebrew-orca` (org-wide install, should
-  auto-cover any new org repo). Re-run via `workflow_dispatch` with the
-  tag name.
-- **Squirrel-mac fails during update** — almost always bundle permissions
-  or a signing-identity mismatch. See the `Why: signing identity stability`
-  comment in `config/electron-builder.config.cjs` and the updater logs in
-  `~/Library/Application Support/Orca/logs/`.
diff --git a/docs/mobile-prefer-renderer-scrollback.md b/docs/mobile-prefer-renderer-scrollback.md
new file mode 100644
index 00000000000..1c9f1a254d2
--- /dev/null
+++ b/docs/mobile-prefer-renderer-scrollback.md
@@ -0,0 +1,651 @@
+# Mobile scrollback parity: hydrate headless emulator from renderer on first PTY data
+
+## Problem
+
+When a mobile companion client subscribes to a terminal, it sees substantially less scrollback than the desktop renderer for the same PTY. In the worst case observed (a `claude`-then-shell session in the `edit-issues` worktree), the desktop shows ~30 lines of post-exit agent summary while mobile shows a single bare prompt.
+
+The mismatch is reproducible and not a transient race: it persists across resubscribes, app return-from-background, and PTY-clean shell prompts.
+
+## Where data lives today
+
+Two separate xterm.js instances exist for every connected PTY:
+
+1. **Renderer xterm** — owned by `TerminalPane` in the renderer process. Created when the user mounts the pane. Listens to `pty:data` IPC for the lifetime of the pane. 50,000-row scrollback. Source of truth for the visible desktop terminal.
+
+2. **Runtime headless emulator** — `HeadlessEmulator` in `src/main/runtime/orca-runtime.ts`. Created lazily on first `runtime.onPtyData(ptyId, …)` call. 5,000-row scrollback. Used to serve `terminal.read`, `terminal.subscribe`, `lastAgentStatus`, and TUI-idle detection. This is what mobile, the CLI, and any non-renderer consumer get.
+
+| Consumer | Reads from | Lifetime |
+|---|---|---|
+| Desktop pane | Renderer xterm | Pane mount → unmount |
+| Mobile (`terminal.subscribe`) | Headless emulator (primary), renderer (fallback) | Runtime startup → PTY exit |
+| `terminal.read` (CLI / agent) | Headless emulator | Runtime startup → PTY exit |
+| `lastAgentStatus` | Headless emulator (via OSC detection on `onPtyData`) | Runtime startup → PTY exit |
+
+The two xterms are fed by the same provider stream but are "born" at different moments:
+
+- The renderer xterm gets hydrated on attach via cold-restore data (`result.coldRestore.scrollback`) or warm reattach (`result.snapshot`) in `pty-connection.ts`, plus all live bytes since.
+- The headless emulator only sees bytes that flow through `runtime.onPtyData` since *runtime* startup. After an Orca relaunch, the headless emulator starts empty and only catches up on new live data; it never replays the cold-restore payload.
+- Commit `8a5ea4b7` added `seedHeadlessTerminal(ptyId, data, size?)` which runs from `ipc/pty.ts` on `provider.spawn` and seeds the emulator from `result.snapshot` / `result.coldRestore.scrollback`. That helps daemon-restored sessions but **does not help when the daemon's persisted state is itself near-empty** — the `edit-issues` reproduction has `checkpoint.json` with `scrollbackAnsi: ""` because the daemon checkpoint only stores the visible screen, not real scrollback.
+
+So the dominant residual case is: daemon checkpoint is near-empty, the user opens a desktop pane (which hydrates from the live PTY post-spawn and accumulates a rich 50k-row buffer), then the user opens mobile — and mobile reads from the headless emulator, which has only seen bytes since runtime startup with nothing to replay.
+
+## Goal
+
+Mobile, CLI, and `lastAgentStatus` should display the same scrollback as the desktop renderer for any PTY whenever the user has a desktop pane mounted for it. The fix must:
+
+- Be a small, targeted change to the runtime (no daemon, IPC schema, or persistence-format changes).
+- Not regress the "no desktop pane mounted" cases (background terminals, headless agent runs, CLI on a freshly-restored daemon).
+- Not introduce reflow / SGR drift between desktop and mobile.
+- Not introduce a per-keystroke or per-subscribe renderer round-trip on the hot path.
+- Reinforce — not violate — the existing invariant that the main process is authoritative for terminal state served to mobile/CLI/`terminal.read`.
+
+## Non-goals
+
+- **Mobile-only-after-relaunch (Scenario A).** A user who relaunches Orca and opens mobile *without* ever opening the desktop pane will still see only what the daemon checkpoint stored (often the visible screen and nothing more). Solving this requires daemon-side persisted scrollback, which is a separate, larger effort with its own privacy, format-stability, retention, and IO-cost considerations. This design explicitly does not solve Scenario A.
+- Persisting full scrollback to disk (the "option 2" architecture).
+- Unifying the renderer and headless emulators into a single main-process service.
+- Changing mobile's xterm-side replay logic. Today it correctly handles either source.
+- Changing the read-priority order in `serializeTerminalBufferFromAvailableState`. Headless stays primary; renderer stays the no-headless fallback.
+
+## Proposed change
+
+When the runtime first sees `pty:data` for a `ptyId` that already has a renderer pane registered (detected via a new `ptyController.hasRendererSerializer(ptyId)` predicate, backed by the `serializersByPtyId` registry in `pty-buffer-serializer.ts`), perform a one-time IPC round-trip to the renderer, get its serialized buffer, and seed the headless emulator with it **before** writing the live byte that just arrived. Subsequent `pty:data` calls for the same `ptyId` skip hydration via a per-PTY guard. If no renderer serializer is registered yet on the first byte, the guard is left absent so a later byte can retry once the pane mounts.
+
+This is structurally the same operation `seedHeadlessTerminal` already does on `provider.spawn` from daemon-restored state. The new path covers the gap the existing seeding doesn't: the renderer has a richer buffer than the daemon does, and we want that richer buffer mirrored into the headless emulator on first runtime touch.
+
+After hydration, all consumers (`terminal.read`, `terminal.subscribe`, `lastAgentStatus`, mobile, CLI) get the same fuller scrollback through the existing read paths. No priority flip is required. No per-consumer fallback. No per-subscribe IPC.
+
+### System context — before
+
+```
+                    ┌─────────────────────────────────────────────┐
+                    │  Renderer process                           │
+                    │                                             │
+                    │   TerminalPane → xterm.js (50k rows)        │
+                    │     ▲                                       │
+                    │     │ replayIntoTerminal(coldRestore.       │
+                    │     │   scrollback) on pane mount           │
+                    │     │ + live pty:data writes                │
+                    └─────┼───────────────────────────────────────┘
+                          │
+                  pty:data│IPC
+                          │
+                    ┌─────┴───────────────────────────────────────┐
+                    │  Main process                               │
+                    │                                             │
+                    │   ipc/pty.ts (provider.spawn)               │
+                    │     ├─→ seedHeadlessTerminal(snapshot)      │
+                    │     │      ↓                                │
+                    │     │   HeadlessEmulator (5k rows) ───┐     │
+                    │     │      ▲                          │     │
+                    │     │      │ trackHeadlessTerminalData│     │
+                    │     │      │ on every onPtyData       │     │
+                    │     └─→ runtime.onPtyData(...)────────┘     │
+                    │                                       ▼     │
+                    │                       serializeHeadless     │
+                    │                       (primary read source) │
+                    │                              │              │
+                    │                              ▼              │
+                    │                   mobile / CLI / lastStatus │
+                    └─────────────────────────────────────────────┘
+                          ▲
+                  pty:data│from daemon
+                          │
+                    ┌─────┴───────────────────────────────────────┐
+                    │  Daemon                                     │
+                    │   checkpoint.json (visible screen only)     │
+                    └─────────────────────────────────────────────┘
+
+Bug: when daemon checkpoint is near-empty but the renderer xterm has
+accumulated a rich live buffer, mobile reads from the headless emulator
+which only saw bytes since runtime startup — and so sees less than desktop.
+```
+
+### System context — after
+
+```
+                    ┌─────────────────────────────────────────────┐
+                    │  Renderer process                           │
+                    │                                             │
+                    │   TerminalPane → xterm.js (50k rows)        │
+                    │     │ ▲                                     │
+                    │     │ │ unchanged hydration path            │
+                    │     │ └─── live pty:data writes             │
+                    │     │                                       │
+                    │     │ ptyController.serializeBuffer(ptyId)  │
+                    │     │ called ONCE per (ptyId, runtime)      │
+                    │     │ on first onPtyData                    │
+                    │     ▼                                       │
+                    └─────┼───────────────────────────────────────┘
+                          │
+                  pty:data│IPC + one-time serialize round-trip
+                          │
+                    ┌─────┴───────────────────────────────────────┐
+                    │  Main process                               │
+                    │                                             │
+                    │   onPtyData(ptyId, data) (first time)       │
+                    │     ├─→ if ptyController.serializeBuffer    │
+                    │     │     returns non-empty:                │
+                    │     │       hydrateHeadlessFromRenderer →   │
+                    │     │       seedHeadlessTerminal(rendered)  │
+                    │     │     mark hydrated                     │
+                    │     ├─→ trackHeadlessTerminalData(data)     │
+                    │     │   (chained via writeChain after seed) │
+                    │     │                                       │
+                    │   HeadlessEmulator (5k rows, now seeded     │
+                    │     with renderer's view)                   │
+                    │       ↓                                     │
+                    │   serializeHeadless (UNCHANGED PRIMARY)     │
+                    │       ↓                                     │
+                    │   mobile / CLI / lastAgentStatus / read     │
+                    └─────────────────────────────────────────────┘
+
+Read priorities are unchanged. Headless emulator is still the primary
+source of truth; renderer is consulted exactly once, at hydration time,
+not per consumer or per subscribe.
+```
+
+### Ordering invariant (DO NOT REORDER)
+
+In `onPtyData(ptyId, data, at)`, the call sequence is:
+
+```ts
+this.agentDetector?.onData(ptyId, data, at)
+this.maybeHydrateHeadlessFromRenderer(ptyId)   // ← MUST come BEFORE
+this.trackHeadlessTerminalData(ptyId, data)    // ← this line
+```
+
+**`maybeHydrateHeadlessFromRenderer` MUST be invoked before `trackHeadlessTerminalData`.** If reordered, `trackHeadlessTerminalData`'s lazy-create branch will populate `headlessTerminals` with a fresh empty emulator first, and `maybeHydrateHeadlessFromRenderer`'s `!headlessTerminals.has(ptyId)` precondition (the "live bytes already arrived" guard) will short-circuit — silently disabling hydration for the lifetime of the PTY. There is no test that catches this regression cheaply (the failure mode is "less scrollback than expected", which is the original bug); the guarantee lives in the call-site comment in `orca-runtime.ts`.
+
+A `// DO NOT REORDER — see "Ordering invariant" in mobile-prefer-renderer-scrollback.md` comment is mandatory at this call site.
+
+### Pseudocode
+
+```ts
+// Per-PTY hydration tracker. Key absent = idle (next byte may attempt).
+// 'pending' = round-trip in flight; 'done' = succeeded or unrecoverably
+// finished; 'skipped' is no longer used — instead we leave the key absent
+// when the precondition fails so a later byte can retry.
+private headlessHydrationState = new Map<string, 'pending' | 'done'>()
+
+onPtyData(ptyId: string, data: string, at: number): void {
+  this.agentDetector?.onData(ptyId, data, at)
+  this.maybeHydrateHeadlessFromRenderer(ptyId)
+  this.trackHeadlessTerminalData(ptyId, data)
+  // …existing OSC / tail / leaf bookkeeping unchanged
+}
+
+private async maybeHydrateHeadlessFromRenderer(ptyId: string): Promise<void> {
+  if (this.headlessHydrationState.has(ptyId)) return
+  if (this.headlessTerminals.has(ptyId)) {
+    // Live bytes already arrived for this ptyId — re-seeding now would
+    // duplicate them. Mark done; never retry. (Daemon-snapshot seeding
+    // is handled separately: see "Cooperation with seedHeadlessTerminal"
+    // — that path is gated on `!hasRendererSerializer(ptyId)` so it does
+    // not pre-empt this hydration when a renderer pane is mounted.)
+    this.headlessHydrationState.set(ptyId, 'done')
+    return
+  }
+  // Why: leave the state absent (not 'done') when there's no renderer
+  // serializer or controller. The pane may mount one byte later; the
+  // next onPtyData call gets another chance. This is the contract change
+  // motivated by Open Question P2-2.
+  if (!this.ptyController?.serializeBuffer) return
+  if (!this.ptyController.hasRendererSerializer?.(ptyId)) return  // not yet registered
+
+  this.headlessHydrationState.set(ptyId, 'pending')
+
+  // Why: eagerly create the headless state at PTY dims so concurrent live
+  // writes from trackHeadlessTerminalData chain onto the same writeChain.
+  // This matches seedHeadlessTerminal's pattern (orca-runtime.ts:780-803);
+  // without it, a live byte arriving during the serializeBuffer await would
+  // lazy-create a separate state that we'd later overwrite, dropping the
+  // live byte.
+  const dims = this.getTerminalSize(ptyId) ?? { cols: 80, rows: 24 }
+  const state: RuntimeHeadlessTerminal = {
+    emulator: new HeadlessEmulator({ cols: dims.cols, rows: dims.rows }),
+    writeChain: Promise.resolve()
+  }
+  this.headlessTerminals.set(ptyId, state)
+
+  // Why: append the renderer-fetch + seed-write to the chain. Live writes
+  // that arrive before the chain head resolves are queued behind it via
+  // trackHeadlessTerminalData's existing `state.writeChain.then(...)` pattern.
+  state.writeChain = state.writeChain.then(async () => {
+    try {
+      const rendered = await this.ptyController!.serializeBuffer!(ptyId, {
+        scrollbackRows: MOBILE_SUBSCRIBE_SCROLLBACK_ROWS,
+        altScreenForcesZeroRows: true
+      })
+      if (!rendered || rendered.data.length === 0) {
+        this.headlessHydrationState.set(ptyId, 'done')
+        return
+      }
+      // Why: resize to the renderer's reported dims before writing the seed
+      // so the serialized layout reflows correctly. Then resize back to the
+      // PTY's current dims after the seed lands so subsequent live writes
+      // use the right cell grid.
+      state.emulator.resize(rendered.cols, rendered.rows)
+      await state.emulator.write(rendered.data)
+      const ptyDims = this.getTerminalSize(ptyId)
+      if (ptyDims && (ptyDims.cols !== rendered.cols || ptyDims.rows !== rendered.rows)) {
+        state.emulator.resize(ptyDims.cols, ptyDims.rows)
+      }
+      // Why: status parity. SerializeAddon does NOT round-trip OSC 0/1/2
+      // title bytes, so extracting from rendered.data would always be null.
+      // applySeededAgentStatus runs detectAgentStatusFromTitle and writes
+      // leaf.lastAgentStatus only when the result is non-null; it MUST NOT
+      // call resolveTuiIdleWaiters or deliverPendingMessages because seed-
+      // derived status reflects historical state.
+      if (rendered.lastTitle) {
+        this.applySeededAgentStatus(ptyId, rendered.lastTitle)
+      }
+    } catch {
+      // Hydration is best-effort. Live writes continue via the same
+      // writeChain that this catch-arm leaves intact.
+    } finally {
+      this.headlessHydrationState.set(ptyId, 'done')
+    }
+  })
+}
+```
+
+**Eager-state ordering invariant.** Even though the chain head blocks live writes until the seed completes, the LIVE BYTE ITSELF (the one that triggered `onPtyData`) is enqueued onto `state.writeChain` BY `trackHeadlessTerminalData` AFTER `maybeHydrateHeadlessFromRenderer` returns synchronously and registers its seed-write link. The live byte's chain link executes after the seed-write resolves. That is the ordering invariant the eager-state pattern preserves.
+
+**Resize-during-hydration note.** `resizeHeadlessTerminal` (orca-runtime.ts:828) deliberately bypasses `writeChain` and calls `state.emulator.resize(...)` directly — that's existing behavior we preserve. If a `pty:resize` IPC arrives during the hydration window (between `headlessTerminals.set` and `seedPromise` resolution), the resize lands on the emulator while the seed-write is mid-flight; this can produce a one-frame visual artifact in the seed but cannot corrupt subsequent live writes (which the seed-then-resize-back invariant restores). The narrow window — typically <200ms — is bounded by the renderer-IPC round-trip duration.
+
+The cap and alt-screen rule on the renderer side mirror `serializeHeadlessTerminalBuffer`: 1000-row limit on rehydration payload, force `scrollbackRows = 0` when the renderer xterm reports `buffer.active.type === 'alternate'`. This unifies semantics between hydration source and live-serialize source — the user sees the same depth regardless of which path served them, and an alt-screen TUI never bleeds normal-buffer scrollback into the seed.
+
+### IPC contract changes
+
+Hydration relies on the renderer-side serializer accepting an option bag. Today the chain is single-arg end to end, so changes must land in lockstep:
+
+- `src/preload/index.ts` — the `pty:serializeBuffer:request` payload extends to `{ requestId, ptyId, opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean } }`. Renderer-side type for the listener callback widens accordingly.
+- `src/main/ipc/pty.ts` — `requestSerializedBuffer(ptyId, opts?)` accepts the opts object and forwards it on the IPC `webContents.send` payload. Snapshot-shape validation widens to accept an optional `lastTitle: string`. Existing 750 ms timeout unchanged.
+- `src/main/runtime/orca-runtime.ts` — the `RuntimePtyController.serializeBuffer?` signature widens to `(ptyId, opts?) => Promise<{ data: string, cols: number, rows: number, lastTitle?: string } | null>`. A new optional `hasRendererSerializer?(ptyId): boolean` lets the runtime check pane mount status before paying the IPC cost (implementation: a getter against `serializersByPtyId` in `pty-buffer-serializer.ts`).
+- `src/renderer/src/components/terminal-pane/pty-buffer-serializer.ts` — the registered `SerializeFn` widens to `(opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }) => Promise<{ data, cols, rows, lastTitle?: string } | null> | …`. The pane's serializer reads the opts: if `altScreenForcesZeroRows && pane.terminal.buffer.active.type === 'alternate'`, call `pane.serializeAddon.serialize({ scrollback: 0 })`; otherwise `pane.serializeAddon.serialize({ scrollback: opts?.scrollbackRows })`. The response payload includes `lastTitle: lastTitleByPtyId.get(ptyId)?.title` (omitted when no title has been observed for this PTY). Default behavior (no opts) preserves today's full-buffer serialize for any caller that hasn't migrated.
+- `serializeTerminalBufferFromAvailableState` (the renderer-fallback read path in `orca-runtime.ts:843`) forwards `scrollbackRows` so the fallback's depth matches the primary path. **It does NOT pass `altScreenForcesZeroRows: true`** — see "alt-screen flag scoping" below.
+
+**alt-screen flag scoping (only on hydration path).** `altScreenForcesZeroRows: true` is passed ONLY by `maybeHydrateHeadlessFromRenderer` (the hydration path). The read-fallback path (`serializeTerminalBufferFromAvailableState`) passes `altScreenForcesZeroRows: false` (or omits the flag, default false). Reasoning:
+
+- **Hydration:** wants the *normal* buffer's scrollback. xterm discards alt-screen content when alt-screen exits anyway, so suppressing scrollback during alt-screen prevents transient TUI bytes from bleeding into the seed that the headless emulator will hold for the rest of the session.
+- **Read fallback:** is invoked by `terminal.read` / `terminal.subscribe` for an actively-running TUI when the headless emulator returned null. The caller wants whatever is currently visible — including alt-screen content — so suppressing it would produce a worse result than today.
+
+Both call sites pass explicit opts in the pseudocode (no implicit defaults relied on). The read-fallback shape:
+
+```ts
+// In serializeTerminalBufferFromAvailableState (read-fallback):
+rendererSnapshot = await (this.ptyController?.serializeBuffer?.(ptyId, {
+  scrollbackRows: opts.scrollbackRows,
+  altScreenForcesZeroRows: false  // read-fallback wants visible alt-screen content
+}) ?? Promise.resolve(null))
+```
+
+### Renderer-side prerequisite
+
+Today, `registerPtySerializer(ptyId, …)` is only called inside `handleReattachResult` (`pty-connection.ts:571`). Fresh spawns — the dominant case — never register, so `hasRendererSerializer(ptyId)` would always return false and hydration would no-op. The renderer change required:
+
+- Move (or duplicate) the `registerPtySerializer` call so it fires for **both** reattach and fresh spawn paths. Cleanest shape: extract the body (closure capturing `pane`, `deps.pendingWritesRef`, `deps.replayingPanesRef`) into a `registerPaneSerializerFor(ptyId)` helper and call it from `handleReattachResult` AND from `startFreshSpawn`'s `.then(spawnedPtyId => …)` once a `ptyId` is known.
+- The helper accepts the new `opts` arg and threads it into `pane.serializeAddon.serialize({ scrollback: … })` per the IPC contract above.
+
+**Cleanup contract & StrictMode safety.** Two requirements, both motivated by React 18 StrictMode double-mount and async pane disposal:
+
+1. **`if (disposed) return` guard at the top of every post-spawn registration call** (both reattach and fresh-spawn paths). Rationale: StrictMode mounts the pane twice; the first mount is disposed before the second runs, but its `pty:spawn` IPC may have already resolved by the time `disposed` flips to true. Without the guard, the disposed first mount would call `registerPaneSerializerFor` after teardown — replacing the live registration from the second mount or registering a closure over a torn-down `pane.terminal`.
+
+2. **Unregister via ownership token, not unconditional delete.** `serializersByPtyId` becomes `Map<ptyId, { fn: SerializeFn, owner: symbol }>`. Each call to `registerPtySerializer` mints a fresh `owner` symbol and returns an unregister closure that **only deletes the entry when the current entry's `owner === thisOwner`**. If a later registration has overwritten the entry (StrictMode second mount, fast pane swap), the unregister is a no-op so the live registration is preserved. The body of the unregister closure also clears any module-level state keyed off the same owner (lastTitle bookkeeping introduced below) AND disposes the xterm `onTitleChange` IDisposable that was installed at register time.
+
+   ```ts
+   export function registerPtySerializer(ptyId, fn): () => void {
+     const owner = Symbol(ptyId)
+     serializersByPtyId.set(ptyId, { fn, owner })
+     ensureSerializerListener()
+     return () => {
+       const current = serializersByPtyId.get(ptyId)
+       if (current?.owner === owner) {
+         serializersByPtyId.delete(ptyId)
+       }
+     }
+   }
+   ```
+
+3. **Spawn-rejection cleanup is mandatory.** The renderer MUST call `pty:clearPendingPaneSerializer(paneKey, gen)` from the catch-arm of `pty:spawn` AND from pane unmount AFTER pre-signal but BEFORE settle. Without this, a failed-spawn paneKey leaks a pending intent that suppresses the next legitimate daemon-snapshot seed for that paneKey.
+
+4. **Pre-signal applies to BOTH fresh-spawn AND reattach paths.** `declarePendingPaneSerializer(paneKey)` is mandatory on both — mirroring the `registerPaneSerializerFor(ptyId)` requirement. Reattach paths today already register the serializer in `handleReattachResult`, but the pre-signal must also fire on the reattach path so the cooperation gate in `pty:spawn` behaves consistently regardless of whether the renderer is taking over a pre-existing PTY or a fresh one.
+
+The `unregisterSerializer()` call is wired into `onDataDisposable.dispose` so the registration is torn down on pane unmount, regardless of which path registered it.
+
+### Renderer pre-signal handshake
+
+The cooperation gate (`ipc/pty.ts` skipping `seedHeadlessTerminal` when a renderer serializer is registered) has a fundamental timing problem on **fresh spawns**: the renderer cannot have registered the serializer for the new ptyId yet, because it doesn't know the ptyId until `pty:spawn` resolves. So at the moment the cooperation gate runs (immediately after `provider.spawn` returns inside `pty:spawn`'s handler), `runtime.hasRendererSerializerFor(ptyId) === false` for every fresh spawn — and the daemon-snapshot seed always wins, defeating the gate for the dominant case.
+
+The renderer does, however, know its **paneKey** before spawn: every pane has a stable `ORCA_PANE_KEY` env var that is part of `args.env` on `pty:spawn`. We use the paneKey as a pre-signal, on a channel that doesn't depend on knowing the ptyId yet:
+
+1. **Pre-signal IPC with generation token.** Renderer calls `pty:declarePendingPaneSerializer(paneKey)` BEFORE invoking `pty:spawn`. Main process maintains `pendingByPaneKey: Map<paneKey, generation: number>` keyed by paneKey. On each pre-signal, main mints a fresh monotonic `gen` value (incrementing a module-level `genSeq` counter) and overwrites the entry, then returns `gen` to the renderer. The renderer awaits this IPC (capturing `gen`), then awaits the spawn IPC — guaranteeing the main process has the pending intent recorded by the time `pty:spawn` runs.
+
+   ```ts
+   let genSeq = 0
+   const pendingByPaneKey = new Map<string, number>()  // paneKey -> generation
+
+   function declarePending(paneKey: string): number {
+     const gen = ++genSeq
+     pendingByPaneKey.set(paneKey, gen)
+     return gen  // returned to renderer, echoed back on settle/clear
+   }
+
+   function settlePending(paneKey: string, gen: number): void {
+     if (pendingByPaneKey.get(paneKey) === gen) pendingByPaneKey.delete(paneKey)
+   }
+
+   paneKeyTeardownListeners.add((paneKey, gen) => settlePending(paneKey, gen))
+   ```
+
+   Why a generation counter: today's design hooks `pendingByPaneKey.delete(paneKey)` into `clearProviderPtyState` via `paneKeyTeardownListeners`. If the OLD PTY's `clearProviderPtyState` fires AFTER mount-2's pre-signal but BEFORE mount-2's spawn, an unconditional teardown deletes mount-2's pending entry — defeating the gate. The generation counter solves this: the `paneKeyTeardownListeners` wiring captures the generation at the time the old PTY was REGISTERED (via the existing `registerPty` call site) and the teardown only fires `settlePending` with that generation. If mount-2 has already replaced the entry with a new gen, `pendingByPaneKey.get(K) !== oldGen` and the teardown is a no-op.
+
+2. **Cooperation gate consults the pre-signal.** Inside `pty:spawn`, after `provider.spawn` returns, the gate becomes:
+   ```ts
+   const paneKey = args.env?.ORCA_PANE_KEY
+   const rendererPreSignaled =
+     typeof paneKey === 'string' && paneKey.length > 0 && paneKey.length <= 256
+       && pendingByPaneKey.has(paneKey)
+   const rendererAlreadyRegistered =
+     runtime?.hasRendererSerializerFor?.(result.id) ?? false
+   if (!rendererPreSignaled && !rendererAlreadyRegistered) {
+     // No renderer is or will be authoritative for this PTY — daemon-snapshot
+     // seed runs as today.
+     runtime?.seedHeadlessTerminal(result.id, /* …snapshot/coldRestore… */)
+   }
+   ```
+   The `rendererAlreadyRegistered` branch covers reattach, where the pane mounted before spawn returned and registration completed in the meantime. The `rendererPreSignaled` branch covers fresh spawn, where registration has not happened yet but is imminent. Note: the gate matches when `pendingByPaneKey.has(paneKey)` is true *regardless of generation*; the generation is only used by cleanup paths (teardown listeners, settle, clear) to prevent cross-generation deletion. **Invariant:** fresh-spawn always relies on the pre-signal branch (`hasRendererSerializerFor(ptyId)` is necessarily false at gate-time since the renderer hasn't received `ptyId` yet); the registered branch only fires for reattach where the pane mounted before spawn returned.
+
+3. **Settle / clear (echo gen back).** After the spawn IPC resolves and the renderer calls `registerPtySerializer(ptyId, …)`, it calls `pty:settlePaneSerializer(paneKey, gen)` to remove the pending intent (echoing the `gen` value it captured from declarePending). The handler runs `settlePending(paneKey, gen)` which only deletes if the stored gen still matches. (The simpler "clear on first onPtyData" or "clear on receipt of `pty:registerPaneSerializer`" alternatives work too — the design picks the explicit `settle` IPC because it makes the contract auditable from the renderer side and avoids coupling main-process state to onPtyData flow.) On pane unmount or registration failure, the renderer also calls `pty:clearPendingPaneSerializer(paneKey, gen)` (sibling handler with the same `settlePending` semantics) to drop the pending intent.
+
+**Sequence diagram (fresh spawn, happy path):**
+
+```
+Renderer                            Main / ipc-pty.ts                Runtime
+  │                                       │                              │
+  │ pty:declarePendingPaneSerializer      │                              │
+  │ (paneKey) ───────────────────────────▶│ pendingByPaneKey.set(K, gen) │
+  │ ◀──────────────────────── ack(gen) ──│                              │
+  │                                       │                              │
+  │ pty:spawn(args incl. ORCA_PANE_KEY) ─▶│                              │
+  │                                       │ provider.spawn(...) → result │
+  │                                       │ pendingByPaneKey.has(paneKey)│
+  │                                       │   === true → SKIP            │
+  │                                       │   seedHeadlessTerminal       │
+  │                                       │                              │
+  │ ◀──────────────────────────── ptyId ──│                              │
+  │                                       │                              │
+  │ registerPtySerializer(ptyId, fn)      │                              │
+  │ pty:settlePaneSerializer(paneKey,     │                              │
+  │   gen) ──────────────────────────────▶│ settlePending(paneKey, gen)  │
+  │                                       │   if gen matches → delete    │
+  │                                       │                              │
+  │                                       │ first onPtyData(ptyId,data)──▶│
+  │                                       │                              │ maybeHydrateFromRenderer
+  │                                       │                              │ (headlessTerminals empty,
+  │                                       │                              │  hasRendererSerializer true
+  │                                       │                              │  → IPC round-trip → seed)
+```
+
+**Renderer-side call shape.** The renderer threads `gen` through every call site so cleanup (settle/clear) can be matched against the generation it captured at declare time:
+
+```ts
+// In pty-connection.ts startFreshSpawn / handleReattachResult:
+const gen = await window.api.pty.declarePendingPaneSerializer(paneKey)
+try {
+  const ptyId = await window.api.pty.spawn(args)
+  registerPaneSerializerFor(ptyId)
+  await window.api.pty.settlePaneSerializer(paneKey, gen)
+} catch (err) {
+  await window.api.pty.clearPendingPaneSerializer(paneKey, gen)
+  throw err
+}
+```
+
+**Correctness properties:**
+
+1. **Pre-signal arrives before `pty:spawn`.** The renderer awaits the pre-signal IPC, then awaits the spawn IPC. Electron `ipcRenderer.invoke`/`send` ordering on a single renderer is preserved on the main side, so the main process processes the pre-signal before `pty:spawn`'s handler runs.
+2. **Missing paneKey degrades to today's behavior.** If `args.env?.ORCA_PANE_KEY` is absent (e.g., a pane that isn't yet wired to set it, an old renderer build, or a non-pane spawn path), the pre-signal lookup returns false, `rendererAlreadyRegistered` is also false on a fresh spawn, and the daemon-snapshot seed runs as today. No regression for callers that don't participate in the handshake.
+3. **Pre-signal without settle (renderer crashes between spawn and registerPtySerializer).** The pending intent stays in the map, but it has no observable effect: the cooperation gate already ran, so the daemon snapshot was suppressed; the headless emulator stays empty; the first `onPtyData` falls through `hasRendererSerializer(ptyId) === false` and hydration's precondition leaves the state map absent. `trackHeadlessTerminalData` then lazy-creates the emulator and live writes populate it. We lose the daemon snapshot for this PTY in that narrow window — accepted limitation, since the renderer was clearly going to be authoritative but didn't make it. (To bound staleness, the entry in `pendingByPaneKey` is cleared whenever a paneKey teardown event fires via the existing `paneKeyTeardownListeners` registry, gated by the generation token.)
+
+**Files-touched implications:** see "IPC contract changes" and "Files touched" — both `pty:declarePendingPaneSerializer` and `pty:settlePaneSerializer` need preload bindings AND main handlers.
+
+### Status parity
+
+Seeding the emulator bypasses `onPtyData`'s OSC-extraction path, so without intervention `leaf.lastAgentStatus` stays whatever it was (typically `null` for daemon-restored leaves) until the next live byte happens to carry an OSC title. Mobile would then see a stale or missing agent badge despite a rich seed.
+
+A previous draft of this design called `extractLastOscTitle(rendered.data)` on the seed payload to recover the title. **That doesn't work**: xterm's `SerializeAddon.serialize()` writes out the visible buffer as a stream of cursor moves, SGR resets, and printable characters — it does NOT round-trip OSC 0/1/2 (window/icon title) escape sequences. The renderer xterm consumes the OSC and sets `terminal.options.title`, but the bytes never appear in `serialize()`'s output. So `extractLastOscTitle` on a seed payload is dead code — it always returns null even when the renderer's pane currently shows a perfectly good title. We need the title via a different channel.
+
+**Approach: ship now via IPC widening, document as best-effort.** The renderer pane already wires `pane.terminal.onTitleChange` (in `pty-connection.ts`) to keep the tab title in sync. We capture the latest observed title in module state alongside the serializer registration, and widen the serialize-buffer IPC payload to carry it back to main:
+
+1. **Renderer side** (`pty-buffer-serializer.ts`):
+   - Module-level `lastTitleByPtyId: Map<ptyId, { title: string, owner: symbol, disposable: IDisposable }>` keyed by the same ownership-token symbol as `serializersByPtyId` (see "Renderer-side prerequisite"). Populated by a wrapper around `pane.terminal.onTitleChange` installed at the same time as `registerPtySerializer`. The entry stores BOTH the IDisposable returned from `pane.terminal.onTitleChange(...)` AND the owner symbol alongside the latest title.
+   - When the pane unregisters, the `unregisterSerializer` closure disposes the IDisposable AND deletes the map entry, both gated by the owner-token match — same ownership semantics as the serializer map, so a StrictMode disposed first-mount cannot wipe the live second-mount's title or leak a dangling listener.
+   - The IPC response payload widens from `{ data, cols, rows }` to `{ data, cols, rows, lastTitle?: string }`. Default omitted when no title was observed for this PTY (e.g., fresh shell pre-prompt).
+
+2. **Main side** (`ipc/pty.ts`, `orca-runtime.ts`):
+   - `requestSerializedBuffer` snapshot-shape validation accepts `lastTitle?: string`.
+   - `RuntimePtyController.serializeBuffer(ptyId, opts?)` returns `Promise<{ data, cols, rows, lastTitle?: string } | null>`.
+   - `maybeHydrateHeadlessFromRenderer` calls `applySeededAgentStatus(ptyId, rendered.lastTitle)` only when `rendered.lastTitle` is a non-empty string (the helper itself also short-circuits on null/empty for safety). The helper internally runs `detectAgentStatusFromTitle` and only writes `leaf.lastAgentStatus` when the result is one of `'idle' | 'working' | 'permission'`.
+
+3. **`applySeededAgentStatus(ptyId, title)`** (new helper in `orca-runtime.ts`). Behavior:
+   - If `title == null` or empty, no-op.
+   - Look up the leaf for `ptyId` via the existing pty→leaf mapping. Run `detectAgentStatusFromTitle(rendered.lastTitle)` (the helper from `src/shared/agent-detection.ts`). If the result is non-null, set `leaf.lastAgentStatus = result`. If null (title is not a recognizable agent title), leave `lastAgentStatus` untouched — the next live OSC byte will populate it through the normal onPtyData path.
+   - **MUST NOT** call `resolveTuiIdleWaiters(leaf)` or `deliverPendingMessages(leaf)`. The seeded status reflects the renderer's last-observed historical title, not a live transition; resolving idle waiters or delivering pending messages on stale data could mistakenly unblock orchestration callers that should only react to a fresh prompt-return.
+   - **Why** (mandatory comment in the helper definition): `// seed-derived status reflects historical state; orchestration waiters must only react to live transitions to avoid resolving on stale data.`
+   - **Rationale for routing through `detectAgentStatusFromTitle`:** we mirror the live path (`onPtyData` already uses `detectAgentStatusFromTitle`) so seeded and live paths produce the same union value, and downstream `leaf.lastAgentStatus === 'idle'` consumers (orchestration `tui-idle` waiters, pending-message gating) keep working. `leaf.lastAgentStatus` is typed `AgentStatus | null` where `AgentStatus = 'working' | 'idle' | 'permission'`; assigning the raw title string would be type-incorrect.
+
+This delivers status parity for the dominant case via the `lastTitle` field (any pane that has rendered a prompt or had a TUI emit OSC titles will have populated `lastTitleByPtyId` long before mobile subscribes). Edge cases where the renderer never observed a title — fresh shell pre-prompt, pane that mounted but never received bytes — leave `lastAgentStatus` as `null`; that's acceptable since `lastAgentStatus` is documented best-effort and the next live OSC title will populate it through the normal `onPtyData` path.
+
+**Status parity / accepted limitations.** Side effect of seeding `lastAgentStatus`: if the seed sets status to `'idle'`, the next live OSC byte that re-emits the same `'idle'` title will see `prevStatus === 'idle'` and the existing transition gate (`agentStatus === 'idle' && prevStatus !== 'idle'`) skips. Orchestration `tui-idle` waiters registered between seeding and the next idle transition will hang until either (a) a non-idle status arrives followed by another idle transition, or (b) the waiter times out. This is an accepted limitation. If it becomes a real problem, future work could split into `lastSeededAgentStatus` (informational, not gating) vs `lastAgentStatus` (gates transitions).
+
+### Files touched
+
+- `src/main/runtime/orca-runtime.ts` — add `headlessHydrationState`, `maybeHydrateHeadlessFromRenderer`, wire into `onPtyData` (with mandatory `// DO NOT REORDER` comment per "Ordering invariant"). Widen `RuntimePtyController.serializeBuffer?` to `(ptyId, opts?) => Promise<{ data, cols, rows, lastTitle?: string } | null>` and add `hasRendererSerializer?(ptyId)`. Add `applySeededAgentStatus(ptyId, title)` helper that writes `leaf.lastAgentStatus` only — must NOT call `resolveTuiIdleWaiters` or `deliverPendingMessages` (mandatory "Why" comment in the helper definition). Add `hasRendererSerializerFor(ptyId)` runtime-service-level method that delegates to `ptyController.hasRendererSerializer` (consumed by `ipc/pty.ts`'s cooperation gate). Forward `scrollbackRows` from `serializeTerminalBufferFromAvailableState` into the renderer-fallback call (do NOT pass `altScreenForcesZeroRows: true` on this path — see "alt-screen flag scoping").
+- `src/main/ipc/pty.ts` — `requestSerializedBuffer(ptyId, opts?)` accepts opts and forwards them on the `pty:serializeBuffer:request` IPC payload. Wire `hasRendererSerializer` through a renderer-registry getter. **Cooperate with hydration:** when a renderer serializer is registered for the spawning PTY *or* the renderer pre-signaled intent for `args.env.ORCA_PANE_KEY`, skip seeding from `result.snapshot` / `result.coldRestore.scrollback` so the daemon's bare-prompt state cannot pre-empt the richer renderer hydration that follows on first byte. **Add three new IPC handlers** with consistent paneKey validation (`typeof paneKey === 'string' && paneKey.length > 0 && paneKey.length <= 256` — invalid input is rejected before mutating state): `pty:declarePendingPaneSerializer(paneKey): Promise<number>` (renderer → main, before `pty:spawn`) mints a fresh generation `gen`, stores `pendingByPaneKey.set(paneKey, gen)` in a module-level `pendingByPaneKey: Map<string, number>`, and returns `gen` to the renderer; `pty:settlePaneSerializer(paneKey, gen)` (renderer → main, after `registerPtySerializer`) runs `settlePending(paneKey, gen)` which deletes only if the stored gen still matches; `pty:clearPendingPaneSerializer(paneKey, gen)` (renderer → main, on spawn-rejection / unmount-before-settle) has the same `settlePending` semantics. Hook `paneKeyTeardownListeners.add((paneKey, gen) => settlePending(paneKey, gen))` so a torn-down PTY's listener captures the generation it was registered under and only clears the map when that generation still matches — ensuring a teardown for the OLD PTY cannot delete a NEW PTY's pending intent if mount-2's pre-signal landed in between. (See "Renderer pre-signal handshake" and "Cooperation with seedHeadlessTerminal" in Open questions.)
+- `src/preload/index.ts` — extend the `pty:serializeBuffer:request` listener payload type to include `opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }`. Add three new bindings under `pty`: `declarePendingPaneSerializer(paneKey: string): Promise<number>` (returns the `gen` token), `settlePaneSerializer(paneKey: string, gen: number): Promise<void>`, and `clearPendingPaneSerializer(paneKey: string, gen: number): Promise<void>`, all forwarded as `ipcRenderer.invoke('pty:declarePendingPaneSerializer', …)` / `'pty:settlePaneSerializer'` / `'pty:clearPendingPaneSerializer'` so the renderer can `await` them and rely on main-side ordering before issuing `pty:spawn` / after `registerPtySerializer`. The renderer captures `gen` from declare and threads it through every settle/clear call.
+- `src/renderer/src/components/terminal-pane/pty-buffer-serializer.ts` — widen `SerializeFn` to `(opts?) => Promise<{ data, cols, rows, lastTitle?: string } | null> | …`; default to today's full-buffer behavior when opts is absent. Convert `serializersByPtyId: Map<ptyId, SerializeFn>` to `Map<ptyId, { fn: SerializeFn, owner: symbol }>` and have `registerPtySerializer` mint a fresh owner symbol per call, returning an unregister closure that deletes only when `current?.owner === thisOwner` (StrictMode safety — see "Renderer-side prerequisite"). Add a parallel `lastTitleByPtyId: Map<ptyId, { title: string, owner: symbol, disposable: IDisposable }>` populated by a wrapper around `pane.terminal.onTitleChange`, with the unregister closure both disposing the IDisposable AND deleting the entry under the same owner-token check. The serialize listener reads from `lastTitleByPtyId` to populate `lastTitle` in the IPC response.
+- `src/renderer/src/components/terminal-pane/pty-connection.ts` — register the serializer for **fresh spawns** as well as reattach. Extract the registration body into a shared `registerPaneSerializerFor(ptyId)` helper called from both `handleReattachResult` AND the post-spawn callback in `startFreshSpawn`. Thread opts (scrollback cap, alt-screen flag) into `pane.serializeAddon.serialize`. Add `if (disposed) return` guard at the top of every post-spawn registration call (StrictMode safety — see "Renderer-side prerequisite"). Track the latest `pane.terminal.onTitleChange` value in module state alongside the serializer registration so the serializer's IPC response can include `lastTitle` (see "Status parity"). Call `const gen = await window.api.pty.declarePendingPaneSerializer(paneKey)` BEFORE `pty:spawn` on every fresh-spawn path (capturing the returned generation token), and `settlePaneSerializer(paneKey, gen)` AFTER `registerPaneSerializerFor(ptyId)` succeeds. On spawn-rejection (catch-arm) AND on pane unmount AFTER pre-signal but BEFORE settle, call `clearPendingPaneSerializer(paneKey, gen)` — this is mandatory (see "Renderer-side prerequisite" item 3). Unregister on pane unmount via the existing `onDataDisposable.dispose` hook (now using the ownership-token contract from "Renderer-side prerequisite").
+- `src/main/runtime/scrollback-limits.ts` (new) — main-process module exporting `MOBILE_SUBSCRIBE_SCROLLBACK_ROWS = 1000`. Imported by both `src/main/runtime/rpc/methods/terminal.ts` and `src/main/runtime/orca-runtime.ts`. (The constant is main-process-only; promoting it to `src/shared/` would expose a runtime cap to the renderer for no benefit.)
+- `src/main/runtime/orca-runtime.test.ts` — add hydration unit tests (see "Test plan").
+- `src/main/runtime/mobile-subscribe-integration.test.ts` — extend with cross-process hydration scenario.
+
+No changes to:
+- `pty:data` batching, daemon adapter.
+- `serializeTerminalBufferFromAvailableState` priority order (headless still primary; renderer still no-headless fallback).
+- Mobile RPC method signatures (`terminal.subscribe`, `terminal.resizeForClient`).
+- Mobile WebView / `TerminalWebView.tsx`.
+- Persistence (`HistoryManager`, `checkpoint.json` shape).
+
+## Why this is structurally sound
+
+The renderer xterm is, in practice, the fuller and more authoritative state for any mounted pane:
+
+1. **It hydrates on attach.** `pty-connection.ts` calls `replayIntoTerminal(pane, …, coldRestore.scrollback)` and writes `snapshot` immediately after pane mount. The headless emulator never replays either. So even on a session that started before the current Orca run, the renderer xterm contains the full history; the headless emulator does not.
+
+2. **It has a bigger buffer.** 50,000 rows vs 5,000.
+
+3. **It is updated on the same IPC tick as the visible UI.** No staleness vs what the user sees.
+
+Hydrating the headless emulator from the renderer on first runtime touch is the same shape of operation as the existing `seedHeadlessTerminal(provider.spawn snapshot)` path. We are not introducing a new architectural pattern; we are extending an existing one to the case where the daemon snapshot is empty but the renderer is rich. The runtime remains authoritative for everything mobile, CLI, `terminal.read`, and `lastAgentStatus` see — the renderer is consulted exactly once per `(ptyId, runtime)` pair.
+
+This is a structural-adjacent improvement that fixes the dominant case (user has both desktop and mobile open) while consciously deferring Scenario A (mobile-only after relaunch) to a separate daemon-persistence design. It is honest about what it does and does not solve.
+
+## Data flow paths
+
+### Happy path — renderer mounted, hydration succeeds
+
+```
+T0  user opens desktop pane.
+    - Fresh spawn: pty-connection.ts calls
+      const gen = await pty:declarePendingPaneSerializer(paneKey)
+      BEFORE pty:spawn, then awaits both. Main mints a fresh gen and
+      records the pending intent under it. After spawn resolves with
+      ptyId, registerPaneSerializerFor(ptyId) +
+      pty:settlePaneSerializer(paneKey, gen) clear the intent (only if
+      the stored gen still matches). On spawn-rejection or unmount-
+      before-settle, pty:clearPendingPaneSerializer(paneKey, gen) runs
+      instead (mandatory — see "Renderer-side prerequisite" item 3).
+    - Reattach: registerPaneSerializerFor(ptyId) runs in
+      handleReattachResult once the ptyId is known.
+    Either way, ipc/pty.ts's cooperation gate sees that the renderer
+    is or will be authoritative for this PTY (via either
+    hasRendererSerializerFor(ptyId) === true OR a pre-signaled paneKey)
+    and SKIPS the daemon-snapshot seedHeadlessTerminal call.
+T1  PTY emits live byte → ipc/pty.ts forwards to renderer (xterm grows)
+                       → ipc/pty.ts forwards to runtime.onPtyData
+T2  onPtyData: maybeHydrateHeadlessFromRenderer
+      - hasRendererSerializer(ptyId) === true → state: absent → pending
+      - serialize round-trip with opts {scrollbackRows, altScreenForcesZeroRows}
+      - on resolve: HeadlessEmulator built at rendered.cols/rows,
+        applySeededAgentStatus(ptyId, rendered.lastTitle), write(rendered.data)
+      - resize emulator to PTY dims if they diverge from rendered dims
+T3  trackHeadlessTerminalData(data) chains AFTER the seed via writeChain,
+    so the live byte is appended on top of the seeded buffer — order
+    preserved.
+T4  hydration state → done. Subsequent onPtyData calls skip the guard.
+T5  user opens mobile → terminal.subscribe → serializeHeadless returns
+    seeded buffer + everything since. Mobile == desktop, and
+    leaf.lastAgentStatus is populated from rendered.lastTitle
+    (sourced from pane.terminal.onTitleChange, NOT from the seed payload —
+    SerializeAddon does not round-trip OSC titles).
+```
+
+### Nil path — Scenario A: no renderer ever mounts
+
+```
+T0  user relaunches Orca, opens mobile only.
+T1  ipc/pty.ts: provider.spawn returns coldRestore.scrollback = ""
+    (daemon checkpoint had scrollbackAnsi: "" — visible screen only)
+    or a thin visible-screen snapshot. hasRendererSerializerFor(ptyId)
+    is false (no pane mounted), so the cooperation gate does NOT skip:
+    seedHeadlessTerminal runs as today.
+T2  PTY emits live byte → onPtyData → maybeHydrateHeadlessFromRenderer
+      - hasRendererSerializer(ptyId) is false → state map left absent.
+        (Pane could still mount later in this runtime; we'd retry then.)
+T3  trackHeadlessTerminalData populates from live bytes; emulator
+    already contains the daemon-snapshot seed.
+T4  Mobile sees daemon's visible-screen snapshot + live bytes since.
+    KNOWN LIMITATION; out of scope for this design.
+```
+
+### Error path — renderer throws or unmounts mid-hydration
+
+```
+T0–T1  same as happy path through `pending` state.
+T2     ptyController.serializeBuffer rejects (renderer disposed,
+       channel closed, IPC timeout, etc.).
+       - catch swallows the error.
+       - hydration state → done (we do not loop on every byte).
+T3     Live bytes continue to populate the emulator via
+       trackHeadlessTerminalData (which lazily creates the headless
+       state at PTY dims). We lose the seed for this runtime but do
+       not block live data flow.
+```
+
+The "advance to done on serialize failure" rule is intentional. Re-trying on every subsequent byte would create a renderer round-trip on every byte until success — too costly for a best-effort path. The "leave state absent when the renderer isn't ready yet" rule (the precondition checks before `pending`) is the inverse trade-off: those checks are cheap (Map lookups), so retrying them is fine.
+
+### SSH note
+
+SSH-backed PTYs flow through the same `runtime.onPtyData` entry point as local and daemon-backed PTYs (see `ipc/pty.ts` provider listener — all providers call `runtime.onPtyData(id, data, at)` uniformly). Hydration applies to SSH PTYs without special-casing: when a desktop pane is mounted on an SSH-backed terminal, its `registerPtySerializer` registration is identical to the local case, and the runtime sees `hasRendererSerializer(ptyId) === true` regardless of provider. The mobile + SSH + relaunch case (rare in practice) inherits Scenario A's known-limitation behavior.
+
+### Concurrent path — live data arrives during hydration
+
+The renderer round-trip is asynchronous; live `pty:data` will continue to arrive before `serializeBuffer` resolves. The pattern from `seedHeadlessTerminal` already handles this: every emulator write is appended to `state.writeChain`, so:
+
+```
+writeChain: Promise.resolve()
+          → seed write       ← scheduled by maybeHydrateHeadlessFromRenderer
+          → live byte 1      ← scheduled by trackHeadlessTerminalData
+          → live byte 2
+          → live byte N
+```
+
+`emulator.write` is invoked in chain order, preserving the byte sequence exactly as the wire delivered it. The seed always lands before the live bytes that triggered hydration, because the trigger logic schedules the seed write *before* it returns control to `onPtyData`, which then schedules the live write.
+
+## Performance
+
+`ptyController.serializeBuffer(ptyId)` does an IPC round-trip to the renderer where xterm's SerializeAddon runs synchronously over the buffer. Cost is roughly proportional to scrollback size: empirically ~50–200 ms for a full 50k-row buffer.
+
+The cost profile is materially different from the rejected priority-flip approach:
+
+| Approach | Renderer round-trip frequency |
+|---|---|
+| Priority flip (rejected) | Once per `terminal.subscribe` AND `terminal.resizeForClient` |
+| Hydrate-on-first-touch (this) | Once per `(ptyId, runtime)` pair, ever |
+
+For a typical session — Orca starts, user opens desktop pane, agent runs for hours, user opens mobile periodically — this approach pays the IPC cost exactly once *for hydration* per `(ptyId, runtime)` pair. The existing renderer-fallback inside `serializeTerminalBufferFromAvailableState` is preserved — it can still hit the renderer on `terminal.read` / `terminal.subscribe` when the headless emulator returns null — but that path is the read-time fallback, not the hydration path. The priority-flip approach paid the IPC cost on every mobile re-subscribe (foreground/background, navigation between worktrees, phone-fit toggle). The "first byte after pane mount" trigger ties the hydration cost to a moment that is already doing IO work, so the latency is hidden inside the existing flow.
+
+There is no per-keystroke cost; `trackHeadlessTerminalData` is unchanged.
+
+## Reflow asymmetry
+
+Hydration happens at whatever cols the renderer is currently at — typically the desktop's natural size (e.g., 105 cols). When mobile later subscribes and triggers a 49-col phone-fit resize, the headless emulator (now seeded with 105-col data) reflows to 49 cols just like the renderer would. Both buffers reflow from the same starting content, so they stay in sync.
+
+This is a real improvement over the priority-flip proposal, which was sensitive to the order in which renderer and headless reflow completed across the IPC tick boundary. With hydrate-on-mount the seed has already landed before any phone-fit resize is even requested, so the reflow asymmetry concerns largely go away: at subscribe time both buffers contain the same content and respond to the same resize event in the same `handleMobileSubscribe` synchronous block.
+
+## Risks
+
+1. **Live data arrives during pending hydration.** Mitigated by chaining through `state.writeChain`, exactly as `seedHeadlessTerminal` already does. Order is preserved.
+
+2. **Renderer pane unmount mid-round-trip.** Caught by `try/catch`; the guard advances to `done` so we don't loop on every subsequent byte, and live writes continue via lazy emulator creation in `trackHeadlessTerminalData`. We lose the seed for that PTY, which is acceptable given how rare unmount-during-IPC is.
+
+3. **Wire-payload size on hydration.** Capped at 1000 rows from day one via the shared `MOBILE_SUBSCRIBE_SCROLLBACK_ROWS` constant. Alt-screen forces 0 rows. This matches the existing serialize path's behavior, so users see identical depth from both sources. The headless emulator's own 5,000-row `DEFAULT_SCROLLBACK` (in `HeadlessEmulator`) is comfortably above the 1k hydration cap; if a future change raises the hydration cap, `HeadlessEmulator`'s default must be bumped in lockstep or the seed will be silently truncated as it lands in the emulator.
+
+4. **Renderer xterm is *behind* the runtime.** Theoretically possible if `pty:data` is delivered to the runtime before the renderer (depends on dispatch order in `ipc/pty.ts`). The renderer's xterm uses an asynchronous `write(callback)`, so even when bytes are delivered the buffer may not yet contain them. In practice this is sub-millisecond and the seed will be at most one frame behind the live byte that triggered it — better than today's headless-only path which has none of those bytes.
+
+5. **Hydration races registerPty.** If `onPtyData` fires before `runtime.registerPty` has been called for this PTY, `getTerminalSize` may return null and we default to 80×24 for the post-seed PTY dims. The seed itself is constructed at the renderer's reported dims (see Pseudocode), so xterm reflow only happens on the post-seed `resize` call — at most one reflow, and only when PTY and renderer dims actually diverge.
+
+6. **PTY-size vs renderer-dim divergence (resize-after-seed reflow).** Under mobile-fit overrides, or in the brief window before a `pty:resize` lands on the main process, the renderer's xterm dims and the runtime's `ptySizes` entry can disagree. Constructing the headless emulator at PTY-size and then writing a seed captured at renderer-dim would force xterm to wrap/reflow the seed in the wrong column count — visible as broken line breaks or doubled prompts. Mitigation: build the emulator at `rendered.cols / rendered.rows`, then resize to PTY-size after the seed lands. See Pseudocode. **At extreme size deltas (e.g., 105→32), the seed-then-reflow path can produce minor visible divergence vs the renderer's own reflow** (xterm reflow is not strictly invertible across very different widths, and the headless emulator runs the reflow on already-laid-out cells rather than the original byte stream). This is an accepted limitation, not a correctness issue: the reflow result is still valid xterm output, just potentially line-broken slightly differently than what the desktop pane shows for the same scrollback. Mobile users have always seen a phone-fit reflow distinct from desktop's; this design does not change that.
+
+7. **Note: writes are flushed before serialize.** The renderer-side serializer (`pty-buffer-serializer.ts:registerPtySerializer`) flushes `pendingWritesRef` via `replayIntoTerminalAsync` before calling `pane.serializeAddon.serialize()`, so the seed faithfully includes hidden-pane buffered writes. No additional sequencing logic is needed in the runtime.
+
+8. **`pendingWritesRef` double-write window (severity-adjusted P2).** When a pane is hidden at the moment bytes arrive, the renderer-side `pendingWritesRef` buffers them while `runtime.onPtyData` simultaneously routes the same bytes into the headless emulator via `trackHeadlessTerminalData`. The renderer's serializer flushes `pendingWritesRef` before serializing, so the seed payload includes those bytes. If hydration runs after `trackHeadlessTerminalData` has already written the same bytes, the headless emulator ends up with a duplicated stretch.
+
+   **Mitigation: the P0-A2 pre-signal handshake makes this rare in practice.** With pre-signal, hydration is the FIRST writer for a fresh-spawn-with-pre-signal — `trackHeadlessTerminalData`'s lazy-create check sees the emulator already exists (created at hydration time) and just appends, so live bytes between seed-fetch and seed-resolve are queued behind the seed via `state.writeChain`. The double-write only manifests in the narrow combo of: (a) reattach path, (b) hidden pane buffering live bytes into `pendingWritesRef`, AND (c) hydration runs after `trackHeadlessTerminalData` has already populated the headless emulator. The impact is bounded: at most one ~8 ms PTY-batch's worth of bytes can be duplicated, the duplicate is visible only in mobile/CLI scrollback (desktop renders from its own xterm which never duplicates), and a future shell prompt overwrites the area anyway. Document as a known limitation; not a correctness-blocking issue. If it becomes user-visible, the fix is to track a per-pty "live bytes seen since last serialize request" cursor on the renderer and trim the seed payload to bytes the renderer observed before hydration started — out of scope for this design.
+
+## Test plan
+
+### Unit (`orca-runtime.test.ts`)
+
+- Hydration runs on the *first* `onPtyData` for a `ptyId` when `hasRendererSerializer` is true and `serializeBuffer` returns non-empty data. Assert the emulator's serialized output contains both the seeded prefix and the live byte.
+- Subsequent `onPtyData` calls do **not** re-trigger hydration after a successful run. Mock `serializeBuffer` and assert it was called exactly once across N `onPtyData` invocations for the same ptyId.
+- "Exactly once" claim is qualified: the renderer round-trip happens once per `(ptyId, runtime)` for hydration. The existing `serializeTerminalBufferFromAvailableState` renderer-fallback (consulted only when the headless emulator returns null) is preserved and may still hit the renderer on `terminal.read` / `terminal.subscribe` paths.
+- When `ptyController` is null (CLI / headless test runs), hydration leaves the state map untouched, headless emulator is created lazily as today, no IPC attempt.
+- When `hasRendererSerializer(ptyId)` returns false on the first byte but true on a later byte, hydration **does** run on the later byte (state is left absent on idle, not consumed). Confirms the contract change for Open Question P2-2.
+- When `ptyController.serializeBuffer` rejects, the guard advances to `done` (no infinite retry), the emulator is created lazily by `trackHeadlessTerminalData`, live bytes still write through.
+- Live data arriving during pending hydration is queued behind the seed write. Schedule the seed-write as a long pending promise, fire several `onPtyData` calls, await `writeChain`, assert the final emulator content has the seed prefix followed by the live bytes in correct order.
+- The 1000-row cap is applied to the renderer-sourced hydration: mock `serializeBuffer` to return a payload representing >1000 rows, assert the requested option bag includes `scrollbackRows: MOBILE_SUBSCRIBE_SCROLLBACK_ROWS`.
+- Alt-screen flag is forwarded: assert the request includes `altScreenForcesZeroRows: true`. (The alt-screen branch is exercised in renderer-side serializer tests where it has access to a real xterm `buffer.active.type`.)
+- **Status parity (lastTitle field):** mock `serializeBuffer` to return `{ data, cols, rows, lastTitle }` where `lastTitle` is a recognizable agent title. Fire `onPtyData`. Assert `leaf.lastAgentStatus` is one of `'idle' | 'working' | 'permission'` (whatever `detectAgentStatusFromTitle` returns for that title) after hydration and before any live OSC title bytes are observed. Conversely, when `lastTitle` is absent / undefined OR `detectAgentStatusFromTitle(lastTitle)` returns `null` (unrecognizable title), assert `leaf.lastAgentStatus` is left unchanged from its prior value (no overwrite).
+- **Multi-PTY concurrent hydration:** fire `onPtyData` for ptyA and ptyB before either `serializeBuffer` resolves. Assert each PTY's hydration completes with its own payload (no cross-talk through the IPC response listener pool — each request has a unique `requestId`).
+- **Re-entrant `onPtyData`:** when `agentDetector.onData` synchronously triggers another `onPtyData` for the same ptyId (or a different ptyId), confirm the hydration state machine still holds — no double-pending, no skipped seed, no out-of-order emulator writes.
+- **Cooperation with `seedHeadlessTerminal`:** when a renderer serializer is registered for `ptyId`, the spawn-time call from `ipc/pty.ts` skips seeding (no daemon-snapshot bytes written to the emulator). When no serializer is registered, the daemon-snapshot path runs as today.
+- **Fresh-spawn timing race (P0-A2 pre-signal handshake):** simulate the renderer pre-signaling intent for paneKey via `const gen = await pty:declarePendingPaneSerializer(paneKey)`, then call the `pty:spawn` handler with `args.env.ORCA_PANE_KEY === paneKey`. Assert `seedHeadlessTerminal` is **NOT** invoked even though `hasRendererSerializerFor(result.id)` is false at that moment (the renderer hasn't received the ptyId yet). The renderer mock then `registerPtySerializer(ptyId, …)` and `pty:settlePaneSerializer(paneKey, gen)`. Fire `onPtyData(ptyId, liveByte)`. Assert `maybeHydrateHeadlessFromRenderer` runs and the headless emulator is populated from the renderer's serialize payload, with the live byte appended after the seed via `writeChain`.
+- **Pre-signal without settle (renderer crash):** simulate `pty:declarePendingPaneSerializer(paneKey)` followed by `pty:spawn` (gate skips daemon seed) but the renderer never calls `registerPtySerializer` or `settlePaneSerializer`. Fire `onPtyData`. Assert hydration's preconditions leave the state map absent, `trackHeadlessTerminalData` lazy-creates the emulator, and live bytes populate it. The pending-paneKey entry is dropped on the next paneKey teardown event.
+- **Pre-signal preserved across paneKey reuse during teardown:** simulate (a) old PTY for paneKey K is exiting, its `paneKeyTeardownListener` is queued (captured at registration time with `gen1`). (b) Mount-2 calls `pty:declarePendingPaneSerializer(K)` and stores generation `gen2` (`gen2 > gen1`). (c) The queued teardown for the old PTY runs; the listener invokes `settlePending(K, gen1)` and SKIPS the delete because `pendingByPaneKey.get(K) === gen2`. (d) Mount-2 calls `pty:spawn`; the cooperation gate matches (`pendingByPaneKey.has(K) === true`) and seed is suppressed. Assert daemon-snapshot seed did NOT run.
+- **Test imports for `scrollback-limits.ts`:** tests in `orca-runtime.test.ts` and `mobile-subscribe-integration.test.ts` import `MOBILE_SUBSCRIBE_SCROLLBACK_ROWS` from `../scrollback-limits` so cap-assertion lines match the production constant (no hardcoded `1000`).
+- **Status parity (real `SerializeAddon` round-trip):** in a renderer-side unit test (using a real `xterm` `Terminal` + `SerializeAddon`), write OSC 0/1/2 title bytes (e.g., `\x1b]0;some-title\x07`) into the terminal, await the `onTitleChange` listener, then call `serializeAddon.serialize()`. **Assert the serialize output does NOT contain the OSC title bytes** — this codifies the limitation that motivated the `lastTitle` field. Then, in a runtime-side unit test, mock the renderer-IPC response to include `{ data, cols, rows, lastTitle }` where `lastTitle` is a known agent title, fire `onPtyData`, and assert `applySeededAgentStatus` was called with that title and `leaf.lastAgentStatus` is the corresponding `'idle' | 'working' | 'permission'` value returned by `detectAgentStatusFromTitle` afterward.
+- **`applySeededAgentStatus` does not resolve waiters:** with a leaf that has pending TUI-idle waiters and pending orchestration messages registered, call `applySeededAgentStatus(ptyId, title)` where `title` is a recognizable agent title. Assert `leaf.lastAgentStatus` matches `detectAgentStatusFromTitle(title)` (one of `'idle' | 'working' | 'permission'`), AND assert `resolveTuiIdleWaiters` and `deliverPendingMessages` were **NOT** invoked. (Spy on the methods or assert the waiter / pending-message queues are unchanged.) This guards against future drift where a refactor lifts shared logic between the live and seeded paths.
+
+### Integration (`mobile-subscribe-integration.test.ts`)
+
+- Cross-process scenario with a mocked renderer that registers a richer scrollback than the headless adapter would produce. After the runtime sees its first live byte, mobile subscribes; assert the `scrollback` frame's `serialized` field includes the seeded prefix.
+- Scenario A regression guard: no renderer registered, mobile subscribes, assert mobile receives only what the daemon snapshot + live bytes provide, hydration was never invoked. (Documents the known limitation.)
+
+### Manual
+
+On a real device, reproduce the original `edit-issues` post-claude-exit scenario, confirm the mobile WebView now shows the same agent summary the desktop shows.
+
+## Open questions
+
+- **Hydration trigger point.** Three plausible options: (a) first `onPtyData`, (b) `runtime.registerPty`, (c) an explicit renderer-pane-mount notification from the renderer. (a) is the chosen approach: cheap, ties cost to a moment already paying IO, and **retryable within a runtime**. The state map is left absent (not `done` or `skipped`) when the renderer serializer isn't yet registered, so a later byte can attempt hydration once the pane mounts. The only consume-on-idle case is `headlessTerminals.has(ptyId)` (live bytes already arrived), where re-seeding would duplicate. (b) fires before the renderer has any data to serialize. (c) needs a new wire from `pty-connection.ts → ipc/pty.ts → runtime`.
+
+- **Cooperation with `seedHeadlessTerminal`.** Today `seedHeadlessTerminal` writes to the headless emulator on `provider.spawn` from `result.snapshot` / `result.coldRestore.scrollback`. The daemon's `result.snapshot` is the visible-screen-only ANSI from `checkpoint.json` — almost always non-empty (it includes the bare prompt) but typically much thinner than what the renderer pane has. If both fire for the same PTY, the daemon path lands first and `headlessTerminals.has(ptyId)` becomes true; the hydration guard would then mark itself `done` and the richer renderer payload is lost. **Decision: gate `seedHeadlessTerminal` on (a) an already-registered renderer serializer OR (b) a renderer pre-signal for the spawning PTY's paneKey.** In `ipc/pty.ts`, before calling `runtime.seedHeadlessTerminal(...)`, check both `runtime.hasRendererSerializerFor(result.id)` AND `pendingByPaneKey.has(args.env?.ORCA_PANE_KEY)` (after validating the paneKey shape — see P1-B2 in the cooperation gate snippet). If either is true, skip the daemon-snapshot seed entirely and let renderer hydration be canonical. (a) covers reattach, where the pane mounted before spawn returned. (b) covers fresh spawn, where the renderer pre-signaled intent before `pty:spawn` but cannot have registered yet because it doesn't know the ptyId. If neither is true (Scenario A — mobile-only, no desktop pane), the daemon-snapshot path runs unchanged. See "Renderer pre-signal handshake" for the full sequence and correctness properties. This is cleaner than a length-comparison "richness heuristic" and lets the renderer be authoritative whenever it's mounted *or* about to mount.
+
+## Rollout
+
+Single change touching the runtime and the renderer-side serialize controller. No feature flag — the hydration is best-effort and degrades to today's behavior when the renderer cannot answer or has nothing useful to share.
+
+Ready for implementation review. Scenario A remains a known limitation tracked for a future daemon-persistence design.
diff --git a/docs/mobile-presence-lock.md b/docs/mobile-presence-lock.md
new file mode 100644
index 00000000000..3aaf8f7fe04
--- /dev/null
+++ b/docs/mobile-presence-lock.md
@@ -0,0 +1,690 @@
+# Mobile Presence Lock for Desktop Terminal
+
+Design doc for repurposing the existing "phone-fit" banner into a general
+presence-based interaction lock between the desktop renderer and mobile
+clients sharing a single PTY.
+
+## Problem
+
+The desktop and mobile clients share full read/write access to the same
+underlying PTY. There is no synchronization between desktop's xterm `onData`
+(which calls `provider.write(ptyId, bytes)` via the `pty:write` IPC) and
+mobile's `terminal.send` RPC (which also calls `provider.write` through the
+runtime). When both parties type at the same time, bytes interleave at the
+TTY level — `ls<enter>` and `pwd<enter>` typed concurrently can produce
+`lpws<enter>d<enter>` and execute unintended commands.
+
+The same is true for resize: desktop `pty:resize` and mobile
+`terminal.resizeForClient` both reach `provider.resize(ptyId, ...)` without
+coordination. The renderer-side `safeFit` has a partial guard, but the
+`pty:resize` IPC handler does not check the override server-side.
+
+A teammate using the original mobile build reported "odd behavior using
+laptop + mobile at the same time." The most visible symptom is the desktop
+terminal jumping to phone dimensions; the more dangerous symptom is silent
+input interleaving.
+
+## Today's banner
+
+The existing banner in `TerminalPane.tsx` is keyed on
+`getFitOverrideForPty(ptyId)`:
+
+- It only appears when mobile is in `auto`/`phone` display mode AND a phone
+  resize actually happened.
+- It says "Terminal resized for phone (W×H)" with a "Restore" button that
+  calls `runtime:restoreTerminalFit(ptyId)`.
+- That IPC handler sets the display mode to `desktop` and applies the
+  display mode, which resizes the PTY back to desktop dims and clears the
+  override. The banner unmounts.
+
+In `desktop` display mode (mobile is subscribed but viewing at desktop dims)
+there is no override and no banner — the desktop user has no idea mobile is
+watching.
+
+## Goal
+
+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
+> 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
+> reclaim the floor (no mobile-side banner — see "Asymmetric UX" below).
+
+The lock exists at two layers:
+
+- **Renderer guard** (primary UX): `pty-connection.ts` drops xterm `onData`
+  and `onResize` while a mobile client is the driver. Banner explains why.
+- **Server-side defense** (defense-in-depth): the `pty:write` and
+  `pty:resize` IPC handlers consult the runtime's driver state and drop
+  desktop-side calls while a mobile client is the driver.
+
+## Behavioral model
+
+### Driver state machine
+
+Instead of a binary lock, each PTY carries a tagged driver state. There is
+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 }
+```
+
+- `idle` — no mobile subscribers; desktop input and resize flow through
+  normally. (We don't bother distinguishing "no one is here" from "only
+  desktop is here" since they behave identically; `idle` is the catch-all
+  for "nothing is currently locking the desktop out.")
+- `desktop` — at least one mobile client is subscribed but the desktop has
+  reclaimed the floor; desktop input and resize flow through.
+- `mobile{clientId}` — `clientId` is the mobile actor that most recently
+  drove this PTY. The banner is mounted on desktop; desktop input and
+  resize are dropped.
+
+Invariants:
+
+- `currentDriver(ptyId)` is always exactly one of the three kinds.
+- On the main process, a transition mutates `currentDriver(ptyId)` and
+  emits `terminalDriverChanged(ptyId, driver)` in the same critical
+  section. The renderer's mirror in `mobile-driver-state.ts` is updated
+  only when the IPC arrives — there is a brief IPC-hop window during
+  which the renderer's `getDriverForPty(ptyId)` returns a stale value.
+  This is why the server-side `pty:write` / `pty:resize` defenses are
+  **load-bearing, not redundant**: a desktop keystroke fired during
+  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
+  only the most recent mobile actor is the driver.
+
+### Transitions
+
+| Current driver | Trigger | Next driver | Side effect |
+|---|---|---|---|
+| `idle` | mobile subscribes with `displayMode='auto'\|'phone'` (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/phone |
+| `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
+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 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
+forward-path coordinator described at the bottom of this doc, and for the
+multi-mobile semantics described below).
+
+### Take back and PTY dimensions
+
+Take back has two sub-cases:
+
+1. **Mobile was in `phone`/`auto` mode (PTY at phone dims)**. Take back
+   resizes PTY back to desktop dims (existing behavior of
+   `applyMobileDisplayMode('desktop')` when `wasResizedToPhone` is true).
+2. **Mobile was in `desktop` mode (PTY already at desktop dims)**. Take
+   back is a pure lock-flag flip; no resize. Today's
+   `applyMobileDisplayMode('desktop')` already short-circuits the resize in
+   this case.
+
+In the symmetric direction, mobile reclaim:
+
+1. **Mobile is in `phone`/`auto` mode but PTY is at desktop dims** (because
+   desktop just clicked Take back): mobile reclaim re-applies the phone
+   resize via `applyMobileDisplayMode(currentMode)`.
+2. **Mobile is in `desktop` mode**: pure lock-flag flip; no resize.
+
+## 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 |
+
+Walkthroughs:
+
+**Phone connects while you're typing.** Banner pops in. 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
+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
+next keystroke is blocked. PTY may snap back to phone dims (if mobile is in
+auto/phone mode).
+
+**Mobile disconnects.** Banner gone permanently. Driver returns to `idle`.
+
+**Multiple panes.** Driver state is per-pane. Phone on pane A doesn't
+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 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
+flow is unaffected.
+
+## Asymmetric UX (accepted tradeoff)
+
+Mobile sees no banner in this PR. The mobile UI is visually unchanged: no
+"Desktop is driving" indicator, no analog to the Take back affordance.
+This is asymmetric and we are accepting it deliberately:
+
+- **Smaller mobile UI surface.** Mobile already has limited screen real
+  estate and a constrained component set; introducing a presence banner
+  there is a non-trivial design + i18n + dismissibility task that we want
+  to defer until the lock model has settled in production.
+- **Faster ship.** Driver state machine + multi-mobile subscriber fix +
+  desktop banner is the smallest change that fixes the dangerous collision
+  (silent input interleaving). Adding a mobile-side banner doubles the UI
+  scope.
+- **Mobile reclaim is naturally signaled.** When a mobile user types
+  while desktop drives, the runtime flips the driver to
+  `mobile{thatClient}`, the desktop banner remounts, and (if mobile is in
+  auto/phone mode) the PTY snaps back to phone dims. The mobile user sees
+  the pane reflow and their keystrokes appear in the output stream. There
+  is no silent black-hole condition on mobile that a banner would
+  resolve.
+- **Mobile keystrokes always reclaim implicitly.** The protocol on mobile
+  is "just type to take the floor." There is no mobile-side button to
+  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
+"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
+where the risk of unintended action is much higher.
+
+If usage data later shows mobile users frequently being surprised by
+desktop activity, a mobile banner can be added without changing the wire
+format — `terminalDriverChanged(ptyId, driver)` already carries everything
+needed.
+
+## Architecture
+
+### Where the truth lives
+
+The `mobileSubscribers` map (re-keyed; see "Multi-mobile subscriber model"
+below) plus a new `currentDriver: Map<ptyId, DriverState>` on the runtime
+are the source of truth. The renderer learns the driver state via a new
+IPC event `terminal-driver-changed(ptyId, driver: DriverState)` emitted
+from the runtime through the existing notifier path. The structured
+payload is intentional: a binary `locked: boolean` would lose the
+`clientId` we need for multi-mobile semantics today and for the unified
+write coordinator on the forward path.
+
+The runtime exposes `getDriver(ptyId): DriverState`, replacing the old
+`isLocked(ptyId): boolean`. Server-side `pty:write` / `pty:resize`
+defenses check `runtime.getDriver(ptyId).kind === 'mobile'` to drop
+desktop-side calls.
+
+A new renderer module `mobile-driver-state.ts` mirrors
+`mobile-fit-overrides.ts`: keyed by ptyId, supports
+`getDriverForPty(ptyId): DriverState` and a subscribe-style change
+listener. The `TerminalPane` banner mounts when
+`getDriverForPty(ptyId).kind === 'mobile'`, and `pty-connection`'s
+`onData`/`onResize` guards drop input/resize under the same predicate.
+
+### Why not reuse `getFitOverrideForPty`?
+
+The fit override only fires when the PTY was actually resized
+(`mode='auto'|'phone'` and `wasResizedToPhone=true`). It misses the
+desktop-mode case where mobile is subscribed but no resize happened. The
+driver state is broader than the fit override.
+
+### Why a new IPC event vs extending `terminal-fit-override-changed`?
+
+Cleaner separation. The fit override is about dimensions; the driver
+state is about ownership. They happen to overlap in the auto/phone
+subcase, but conflating them long-term ties future work on either to the
+other.
+
+### Why a structured payload vs `locked: boolean`?
+
+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
+LoC over a binary lock; the payoff is a symmetric UX foundation and a
+future-proof wire format.
+
+## Multi-mobile subscriber model
+
+The `mobileSubscribers` map is today shaped `Map<ptyId, Subscriber>` and
+each `terminal.subscribe` call overwrites the previous subscriber for that
+ptyId. That overwrite is fine for a binary `has(ptyId)` presence check but
+breaks the moment we treat presence as a real set: phone B subscribing
+silently evicts phone A, so phone A unsubscribing or its WS dropping looks
+like "no mobile clients" even while phone B is still on the line. The
+driver state machine sits directly on top of presence, so soundness here
+is a prerequisite, not a polish.
+
+We rekey to `Map<ptyId, Map<clientId, Subscriber>>` and update each
+callsite:
+
+- **`handleMobileSubscribe(ptyId, clientId, subscriber)`** — get-or-create
+  the inner map, then `inner.set(clientId, subscriber)`. Do not overwrite
+  peer clients. If the inner map was empty before insert, this is the
+  first subscriber for the PTY; emit the `idle → mobile{clientId}` driver
+  transition.
+- **`handleMobileUnsubscribe(ptyId, clientId)`** — `inner.delete(clientId)`,
+  then if the inner map is now empty, delete the outer entry, run the
+  existing restore-resize logic, and emit the `* → idle` driver
+  transition. If the inner map is non-empty, do **not** fire restore /
+  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
+  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.
+
+  **Active phone-fit dim selection (multi-mobile).** When two or more
+  mobile clients subscribe with different viewports (e.g., iPhone +
+  iPad), the PTY can only be at one phone-fit size at a time. Rule:
+  **the most recent mobile actor's viewport wins**. This matches the
+  driver state machine — whoever last took the floor (`mobile{X}`)
+  also dictates the active phone-fit dims. When that client
+  unsubscribes, the next-most-recent surviving subscriber's viewport
+  wins; on the last client leaving, the inner map empties and we run
+  the existing restore back to the earliest-recorded desktop dims. We
+  do not use `min(cols, rows)` across subscribers because that
+  produces no clear principal — multiple TUIs are forced to render
+  for an aggregate viewport that nobody actually has, which is worse
+  than picking a single owner. Most-recent-actor is consistent with
+  the rest of the protocol (whoever acted last has the floor) and is
+  cheap to reason about.
+
+  **Subscriber record extension.** "Most-recent actor" and
+  "earliest-by-subscribe-time" both require timestamps that today's
+  Subscriber record does not carry. Extend it with two fields:
+
+  ```ts
+  interface Subscriber {
+    clientId: string
+    viewport: { cols: number; rows: number }
+    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
+  }
+  ```
+
+  - `applyMobileDisplayMode(ptyId)` for active phone-fit dims:
+    iterate the inner map, pick `argmax(lastActedAt)`, use that
+    subscriber's `viewport`.
+  - For restore-to-desktop semantics on last-client-leaves: pick
+    `argmin(subscribedAt)` **among subscribers with non-null
+    `previousCols`/`previousRows`** and use that subscriber's
+    `previousCols/Rows` as the restore target. Desktop-mode
+    subscribers carry `previousCols/Rows = null` by design (the
+    existing `handleMobileSubscribe` short-circuits dim capture for
+    desktop-mode joins to avoid capturing a stale full-width size),
+    so they are not viable restore targets. If no surviving
+    subscriber has captured dims, fall back to
+    `lastRendererSizes.get(ptyId)` (the desktop renderer's most
+    recent reported size) — same fallback the existing first-insert
+    capture path uses.
+
+  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
+  recent mobile actor. Whenever any mobile client sends
+  input/resize/setDisplayMode/subscribes-fresh, that client becomes the
+  `currentDriver` (`mobile{thatClient}`). Phone B taking over from phone A
+  is an internal mobile→mobile transition: no banner change, but the
+  recorded `clientId` updates so the runtime always knows who is the
+  authoritative mobile actor.
+
+The semantic upshot is that the desktop banner is governed by "is the
+inner map non-empty AND has the desktop not reclaimed?" rather than the
+old single-slot heuristic, and Take back / mobile-reclaim correctly
+ping-pong even when two phones are on the same PTY.
+
+## Implementation
+
+Files touched:
+
+1. `src/main/runtime/orca-runtime.ts` — rekey `mobileSubscribers` to
+   `Map<ptyId, Map<clientId, Subscriber>>`, add `currentDriver` map,
+   `getDriver(ptyId)` getter, transition methods, notifier hook. Update
+   `handleMobileSubscribe` / `handleMobileUnsubscribe` /
+   `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.
+   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
+   `terminalDriverChanged(ptyId, driver: DriverState)`.
+3. `src/main/window-manager.ts` (or wherever `RuntimeNotifier` is wired) —
+   forward to renderer via `webContents.send('terminal-driver-changed', …)`.
+4. `src/preload/index.ts` + `src/preload/api-types.ts` — expose the new
+   event with the structured `DriverState` payload.
+5. `src/main/ipc/runtime.ts` — add `runtime:reclaimTerminal` IPC (or
+   extend `runtime:restoreTerminalFit`) which drives the
+   `mobile{*} → desktop` transition.
+6. `src/main/runtime/rpc/methods/terminal.ts` — drive the
+   `* → mobile{clientId}` transition in `terminal.send`,
+   `terminal.resizeForClient`, `terminal.setDisplayMode`, and the
+   subscribe handler (with the subscribe-in-desktop-mode exception
+   above).
+
+   **Wire-format changes required.** The driver state machine tags
+   the active mobile actor with `clientId`, so every mobile RPC method
+   that can take the floor must carry the caller's identity. Today
+   only `terminal.subscribe` and `terminal.resizeForClient` do; we
+   extend the others.
+
+   **Canonical identity shape.** Use the existing
+   `terminal.subscribe` shape: `client: { id: string; type: 'mobile'
+   \| '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
+     to "the most recent mobile actor" when absent).
+   - `TerminalSetDisplayMode` gains the same `client` field.
+   - `TerminalUnsubscribe` gains `client: { id: string }` so the
+     server can derive the composite cleanup key (see below); the
+     existing `subscriptionId` field is kept and remains the primary
+     lookup, with `client.id` used only when the caller passed a
+     bare-handle `subscriptionId`.
+
+   **Subscribe-side composite key.** Change `subscriptionId` from
+   `params.terminal` to `${params.terminal}:${params.client.id}` so
+   two phones subscribing to the same terminal handle do not evict
+   each other via `registerSubscriptionCleanup`. Without this fix,
+   the multi-mobile rekey to `Map<ptyId, Map<clientId, Subscriber>>`
+   would be silently defeated at the RPC subscription layer (phone
+   B's subscribe runs phone A's cleanup → A's data listener tears
+   down → A's `handleMobileUnsubscribe` fires).
+
+   **Unsubscribe-side composite key.** The mobile RPC client today
+   emits `terminal.unsubscribe` with `params: { subscriptionId:
+   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
+   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
+   reconstructs the composite key from `client.id`. Belt-and-braces
+   so a stale older mobile build still cleans up correctly.
+
+   This is a coordinated client/server wire-format change. The
+   mobile app must ship in lockstep; if a stale mobile client emits
+   bare-handle unsubscribe to a new server, the server's
+   reconstruction path catches it. If a new mobile client emits
+   composite-handle unsubscribe to a stale server, the stale server
+   ignores `client.id` and the composite key fails to match — but
+   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
+   guards have different purposes: `isResizeSuppressed()` blocks the
+   safeFit cascade after a take-back transition (preventing
+   collateral resize corruption of background panes), while the
+   driver-state check blocks desktop-side resizes whenever mobile is
+   driving. Both must apply.
+8. `src/renderer/src/lib/pane-manager/mobile-driver-state.ts` — new
+   renderer store mirroring `mobile-fit-overrides.ts`. Exposes
+   `getDriverForPty(ptyId): DriverState` and a change listener.
+9. `src/renderer/src/components/terminal-pane/pty-connection.ts` — guard
+   `onData` and `onResize` on
+   `getDriverForPty(ptyId).kind === 'mobile'`.
+10. `src/renderer/src/components/terminal-pane/TerminalPane.tsx` — switch
+    banner to consume driver state, update copy, rename Restore → Take
+    back.
+
+### Server-side detail
+
+```ts
+// orca-runtime.ts
+private currentDriver = new Map<string, DriverState>()
+
+getDriver(ptyId: string): DriverState {
+  return this.currentDriver.get(ptyId) ?? { kind: 'idle' }
+}
+
+private setDriver(ptyId: string, next: DriverState): void {
+  this.currentDriver.set(ptyId, next)
+  this.notifier?.terminalDriverChanged(ptyId, next)
+}
+
+reclaimTerminalForDesktop(ptyId: string): void {
+  if (!this.isMobileSubscriberActive(ptyId)) return
+  // Snap PTY back to desktop dims if currently at phone dims.
+  // applyMobileDisplayMode is a no-op resize when already at desktop dims.
+  this.setMobileDisplayMode(ptyId, 'desktop')
+  this.applyMobileDisplayMode(ptyId)
+  this.setDriver(ptyId, { kind: 'desktop' })
+}
+
+private mobileTookFloor(ptyId: string, clientId: string): void {
+  // If mobile is in phone/auto mode, re-apply phone resize on the first
+  // hand-off back from desktop. Mobile-to-mobile hand-offs are no-ops
+  // for resize.
+  const prev = this.getDriver(ptyId)
+  if (prev.kind === 'desktop') this.applyMobileDisplayMode(ptyId)
+  this.setDriver(ptyId, { kind: 'mobile', clientId })
+}
+
+handleMobileUnsubscribe(ptyId: string, clientId: string) {
+  const inner = this.mobileSubscribers.get(ptyId)
+  if (!inner) return
+  inner.delete(clientId)
+  if (inner.size > 0) return  // peer mobile clients still drive
+  this.mobileSubscribers.delete(ptyId)
+  // Drive transition fires synchronously so the desktop banner
+  // unmounts immediately. The PTY restore runs inside the existing
+  // 300ms pendingRestoreTimers debounce — see "Restore-debounce
+  // window" under Edge cases.
+  this.setDriver(ptyId, { kind: 'idle' })
+  // Existing restore-resize logic (300ms debounced timer) runs here.
+}
+```
+
+The mobile-took-floor path is invoked from the RPC method handlers (not
+from `sendTerminal` directly) so that the driver flip is bound to
+deliberate mobile actions, not to internal runtime calls.
+
+### Renderer guards
+
+```ts
+// pty-connection.ts onData
+if (currentPtyId && getDriverForPty(currentPtyId).kind === 'mobile') {
+  return  // Mobile is driving this PTY; banner explains.
+}
+// existing transport.sendInput(data)
+
+// pty-connection.ts onResize
+// Why: keep both predicates. getFitOverrideForPty fires synchronously
+// in the renderer the moment safeFit runs; getDriverForPty arrives via
+// IPC and lags by one round-trip. Removing the fit-override predicate
+// would re-introduce the resize-over-mobile-fit bug mobile-fit-overrides
+// was added to prevent.
+if (
+  currentPtyId &&
+  (getFitOverrideForPty(currentPtyId) ||
+    getDriverForPty(currentPtyId).kind === 'mobile')
+) {
+  return
+}
+```
+
+### Banner copy
+
+```
+🔒 Mobile is driving this terminal — your input is paused. [ Take back ]
+```
+
+When PTY is at phone dims, append the dim suffix:
+```
+🔒 Mobile is driving this terminal (80×24) — your input is paused. [ Take back ]
+```
+
+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.
+
+## Edge cases
+
+- **Mobile drops network**. WS doesn't immediately know. The inner
+  subscriber map retains the entry for ~30s until ping timeout. Banner
+  stays. Take back still works during this window — it transitions to
+  `desktop` immediately. When mobile eventually reconnects with
+  `terminal.subscribe`, that client takes the floor again
+  (`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
+  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
+  dropped keystroke is on the renderer side, which is good enough.
+- **Take back while phone is offline**. Works (transitions to `desktop`).
+  When phone reconnects with a fresh subscribe, driver flips to
+  `mobile{thatClient}`.
+- **Display mode toggle from mobile**. `terminal.setDisplayMode` is
+  treated as mobile interaction → that client takes the floor. Aligns
+  with "any deliberate mobile action takes the floor."
+- **Subscribe from a fresh client (reconnect with new clientId)**. The
+  subscribe path runs the `desktop → mobile{thatClient}` (or
+  `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.
+
+## Tests
+
+- `orca-runtime.test.ts` (driver state machine):
+  - Every transition row in the table above has a unit test asserting
+    `(prev, trigger) → (next, side effect, emitted event payload)`.
+  - `getDriver` defaults to `{ kind: 'idle' }` for unknown ptyIds.
+  - `terminalDriverChanged` is emitted exactly once per state change and
+    carries the structured `DriverState` payload (not a boolean).
+- `orca-runtime.test.ts` (multi-mobile subscriber sequencing):
+  - Phone A subscribes (`auto`) → driver is `mobile{A}`, banner emit
+    fires.
+  - Phone A subscribes (`desktop`) from `idle` → driver stays `desktop`
+    (subscribe-in-desktop-mode does not take the floor); inner map
+    has A.
+  - Phone B subscribes (`auto`) while A is still on (`auto`) → driver
+    flips to `mobile{B}` (subscribe-fresh-with-auto/phone counts as
+    take-floor); inner map has both subscribers; active phone-fit
+    dims switch to B's viewport.
+  - Phone B unsubscribes while A is still on → driver remains mobile;
+    active phone-fit dims revert to A's viewport (next-most-recent
+    actor); banner stays up; no `idle` transition.
+  - Phone A unsubscribes (last client leaves) → driver transitions to
+    `idle`, banner unmounts, PTY restores to earliest-recorded
+    desktop dims.
+  - `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*
+    transition to `desktop` automatically (existing setDisplayMode
+    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):
+  - Phone A subscribes to terminal handle `T`, phone B subscribes to
+    the same handle `T` → A's data listener still receives bytes
+    after B's subscribe (subscriptionId is `${T}:${clientId}` so
+    `registerSubscriptionCleanup` does not collide).
+  - Regression: prior to the fix, the second subscribe ran the first
+    subscribe's cleanup and tore down phone A's stream.
+- `pty-connection.test.ts`:
+  - `onData` is dropped while `getDriverForPty(id).kind === 'mobile'`.
+  - `onData` is delivered when driver flips to `desktop` or `idle`.
+  - `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'`.
+  - `pty:resize` IPC is dropped under the same predicate.
+
+## Out of scope
+
+- Mobile yanking desktop tab focus via `terminal.focus`.
+- Cold-restore ack from mobile-only attach.
+- Mobile-side "Desktop is driving" banner (see "Asymmetric UX" above).
+
+These are independent collisions tracked separately.
+
+## Forward path
+
+The natural next step (not in this PR) is unifying both writers — the
+desktop renderer's `pty:write` IPC and the mobile RPC's `terminal.send`
+— into a single coordinator that queues bytes through a runtime-owned
+write path. The driver state machine cleanly supports this: the
+coordinator can use `currentDriver(ptyId)` as the admission predicate
+(only the current driver's bytes are dequeued), and the
+`mobile{clientId}` payload tells it which queue head to drain when a
+specific phone is the active actor. Today's PR keeps two independent
+write paths and uses driver state purely as a drop-filter; the same
+state machine becomes the scheduling input on the forward path without
+a wire-format change.
+
+## Rollout
+
+Single PR. No feature flag needed; behavior is strictly additive (locks
+an existing collision surface) and the existing banner UX continues to
+work under the new driver-state model with sharper copy.
diff --git a/docs/mobile-shared-client-per-host.md b/docs/mobile-shared-client-per-host.md
new file mode 100644
index 00000000000..e9a8cee4d19
--- /dev/null
+++ b/docs/mobile-shared-client-per-host.md
@@ -0,0 +1,406 @@
+# Single Shared RPC Client per Host (Mobile)
+
+Design doc for collapsing the per-screen WebSocket connection model into a
+single shared `RpcClient` per paired host, owned by a React context that
+sits above the route tree.
+
+## Problem
+
+The mobile app today opens **one WebSocket per screen per host**:
+
+| Screen | Connections per host |
+|---|---|
+| Home (`app/index.tsx`) | 1 (with persistent `accounts.subscribe` stream) |
+| Host detail (`app/h/[hostId]/index.tsx`) | +1 |
+| Worktree session (`app/h/[hostId]/session/[worktreeId].tsx`) | +1 |
+| Accounts (`app/h/[hostId]/accounts.tsx`) | +1 |
+| Pair confirm (briefly) | +1 |
+
+A user actively browsing one host typically holds **3–4 simultaneous
+sockets** to the desktop runtime. Each call to `connect()` runs its own
+E2EE handshake, allocates an ephemeral keypair, and runs an independent
+reconnect loop with exponential backoff.
+
+This causes three observable problems:
+
+1. **Stuck-connecting / reconnecting for minutes.** The desktop's
+   `MAX_WS_CONNECTIONS = 32` is shared across all clients. A user who
+   navigates rapidly accumulates stale sockets faster than they can be
+   reaped by TCP keepalive (which can take 60–300s on default systems
+   for half-open connections from a phone leaving Wi-Fi range or
+   backgrounding). Once the cap is hit, new sockets are rejected with WS
+   close code `1013 Maximum connections reached`. The mobile reconnect
+   loop does not recognize 1013 as terminal — it retries with backoff,
+   each retry also dropped, until enough stale sockets are reaped.
+   Result: a screen that should connect in <1s is stuck for 1–5 minutes.
+2. **Tab create/delete hangs.** `client.sendRequest('terminal.create')`
+   awaits `waitForConnected()`. If the session-screen client is in
+   `connecting`/`reconnecting` state because its socket lost the cap
+   race, the await blocks until the 30s `REQUEST_TIMEOUT_MS` fires.
+   The user sees nothing happen.
+3. **Triple cost on every cold-start.** Three E2EE handshakes,
+   three Curve25519 keypair generations, three subscription
+   re-registrations on every app launch. On low-end Android, this
+   visibly delays first paint by hundreds of milliseconds.
+
+The architecture also wastes server resources: each socket carries its
+own E2EE channel, its own subscription set, its own driver-state-machine
+client identity (cf. `docs/mobile-presence-lock.md`). The server already
+has logic to reconcile multi-socket-per-token tear-down
+(`hasOtherConnections` in `ws-transport.ts`) — that logic exists *because*
+this design forced the question; with a single client per host, it becomes
+unnecessary.
+
+## Today's transport ownership
+
+Five files independently call `connect(endpoint, deviceToken, publicKeyB64)`:
+
+```
+mobile/app/pair-confirm.tsx       # one-shot during pairing
+mobile/app/pair-scan.tsx          # one-shot during pairing
+mobile/app/index.tsx              # N (one per paired host)
+mobile/app/h/[hostId]/index.tsx   # 1 (host detail)
+mobile/app/h/[hostId]/session/[worktreeId].tsx  # 1 (session)
+mobile/app/h/[hostId]/accounts.tsx              # 1 (accounts)
+```
+
+Each owns a `useRef<RpcClient | null>` and calls `client.close()` from a
+cleanup function. The home screen additionally maintains a
+`clientsRef: Array<{ hostId, client }>` so its own usage of the per-host
+client survives across navigation events.
+
+This pattern works for *correctness* — every cleanup eventually closes
+its socket — but it breaks under three real-world conditions:
+
+1. **Rapid navigation.** Mounts spawn before unmounts complete; cleanup
+   `client.close()` runs after a new screen has already opened a fresh
+   socket to the same host. Two sockets briefly coexist for the same
+   token, multiplied across screens.
+2. **Network drops.** A backgrounded/locked phone on a flaky network
+   leaves sockets half-open. The server doesn't get a FIN; cleanup
+   relies on TCP keepalive timing. Meanwhile the foreground app, on
+   resume, opens fresh sockets. The half-open ones eat the cap until
+   reaped.
+3. **Hot reload during dev.** Each Metro hot reload fires a new render
+   tree without unmounting the old, so connections leak.
+
+## Goal
+
+> A paired host has at most **one active WebSocket** at any time, owned
+> by a context provider above the route tree. All screens for that host
+> share that client. The pair flows are the only places that create
+> short-lived clients (and they explicitly close those after pairing
+> completes).
+
+This is the architectural fix to the symptoms above. Combined with the
+two recently-shipped hotfixes (token cache + stable `useEffect`
+dependency on home screen), this completes the connection-lifecycle
+work.
+
+## Design
+
+### Layered ownership
+
+```
+RootLayout (<RpcClientProvider>)
+└── routes
+    └── <HostScopedClientGate hostId={...}>   // mounts when route has hostId
+        ├── h/[hostId]/                       // host detail
+        ├── h/[hostId]/session/[worktreeId]/  // session
+        └── h/[hostId]/accounts/              // accounts
+```
+
+Two providers, layered:
+
+1. **`RpcClientProvider` (root)** — owns one `RpcClient` per host,
+   keyed by `hostId`. Lifecycle: opens on first request for that
+   host's client, holds open until app shutdown OR until the host is
+   removed (`removeHost(hostId)` triggers explicit close). Reuses
+   existing `loadHosts()` cache from the recently-merged
+   `host-store.ts` work.
+2. **`HostScopedClientGate` (per host)** — a thin route-layout
+   component placed at `app/h/_layout.tsx`. Reads `hostId` from
+   route params, requests the client for that host from the root
+   provider, exposes it via context to descendants, and renders a
+   loading state until the client reaches `connected`. Guarantees
+   every descendant screen sees the same client instance for that
+   host — no per-screen `connect()` calls.
+
+The home screen (`app/index.tsx`) lives outside `HostScopedClientGate`
+since it spans all hosts; it consumes the root provider directly via
+a multi-host hook (see API below).
+
+### API
+
+```ts
+// New file: mobile/src/transport/client-context.tsx
+type RpcClientContext = {
+  // Get-or-open. Returns the singleton client for hostId; opens it
+  // lazily on first call, reuses it for all subsequent callers. Never
+  // returns null (returns a placeholder client in 'connecting' state
+  // if open hasn't completed).
+  getClient: (hostId: string) => RpcClient
+  // Connection state for a given host (driven by client.onStateChange).
+  useHostState: (hostId: string) => ConnectionState
+  // Useful for the home screen which renders all hosts at once.
+  useAllClients: () => Array<{ hostId: string; client: RpcClient }>
+}
+
+export const RpcClientProvider: React.FC<{ children: React.ReactNode }>
+
+export const useHostClient: (hostId: string) => {
+  client: RpcClient
+  state: ConnectionState
+}
+```
+
+Internal store (single `useRef` in the provider):
+
+```ts
+type StoreEntry = {
+  client: RpcClient
+  state: ConnectionState
+  refCount: number       // number of active screens holding this client
+  closeTimer: NodeJS.Timeout | null
+}
+const store = useRef(new Map<string, StoreEntry>())
+```
+
+### Lifecycle rules
+
+1. **Open on first read.** First `getClient(hostId)` call for a host
+   reads the host record (uses cached `loadHosts()`), then calls
+   `connect()` and stores the client. Subsequent calls return the
+   cached entry.
+2. **Idle close timer.** When `refCount` drops to 0 (all screens for
+   that host unmounted), schedule a 30-second close timer. If a screen
+   for the same host mounts within 30s, cancel the timer. Otherwise,
+   close the client and remove from the store.
+   - Why 30s: covers fast tab-switching and back-navigation without
+     keeping idle sockets forever. Tunable based on observed behavior.
+3. **Forced close on host removal.** `removeHost(hostId)` from
+   `host-store.ts` calls into the provider to close the client
+   immediately and delete the store entry.
+4. **App backgrounded.** No special action — let TCP keepalive and
+   server-side reaping handle it. Reconnect happens on foreground.
+5. **App foregrounded.** Trigger a `getState()` poll on every
+   non-closed entry; if any are in `disconnected` (TCP died while
+   backgrounded), the existing reconnect loop handles it. No new
+   client allocations.
+
+### Public surface for screens
+
+Each screen replaces:
+
+```ts
+// Before
+const [client, setClient] = useState<RpcClient | null>(null)
+const [connState, setConnState] = useState<ConnectionState>('disconnected')
+
+useEffect(() => {
+  let rpcClient: RpcClient | null = null
+  void (async () => {
+    const hosts = await loadHosts()
+    const host = hosts.find((h) => h.id === hostId)
+    if (!host) return
+    rpcClient = connect(host.endpoint, host.deviceToken, host.publicKeyB64, setConnState)
+    setClient(rpcClient)
+  })()
+  return () => {
+    rpcClient?.close()
+  }
+}, [hostId])
+```
+
+with:
+
+```ts
+// After
+const { client, state } = useHostClient(hostId)
+```
+
+Total LoC reduction across screens: ~150 lines.
+
+### Pair flow exception
+
+`app/pair-confirm.tsx` and `app/pair-scan.tsx` continue to call `connect()`
+directly with **explicit `client.close()`** after the test request returns.
+Reason: the host record doesn't yet exist in `loadHosts()` during pairing,
+so the provider has nothing to look up. The pair flow's client is a
+short-lived transient that delivers `getStatus()` once and then dies.
+
+After `saveHost()` succeeds, the user is navigated away; the next time
+they enter `/h/[hostId]/...`, the provider opens a fresh client through
+the normal path.
+
+### Streaming subscription handling
+
+The home screen's `accounts.subscribe` stream and the session screen's
+terminal subscriptions remain owned by their respective screens — the
+provider doesn't manage subscriptions, only the underlying transport.
+Each screen's effect calls `client.subscribe(...)` and stores the
+returned unsubscribe function. On unmount, the screen unsubscribes
+(returns to the existing per-screen pattern, just over a shared
+transport). The transport's `subscribe()` already correctly multiplexes
+multiple listeners on one WebSocket via the `id` field.
+
+### State propagation
+
+`useHostState(hostId)` returns the live `ConnectionState`. The provider
+maintains a per-host `useState` keyed by hostId; the `client.onStateChange`
+listener is wired once at client creation and updates the corresponding
+state slot. `useHostState` reads from this state via `useSyncExternalStore`
+or a context selector — the choice is mostly preference; in this
+codebase, given the small state shape, a simple `useContext + useMemo`
+of the matching slot is fine.
+
+## Migration
+
+Step-by-step, each step independently shippable:
+
+1. **Add `RpcClientProvider` and `useHostClient`.** No callers yet.
+   Wire into `app/_layout.tsx`. Existing screens unchanged.
+2. **Migrate session screen** (highest-risk, most-used). Replace
+   per-screen `connect()` with `useHostClient`. Test connection
+   behavior, terminal create/delete, scrollback hydration.
+3. **Migrate host detail and accounts screens.** Same pattern.
+4. **Migrate home screen.** Replace `clientsRef` with
+   `useAllClients()`. The home screen's per-host streaming
+   subscriptions move into a hook that runs per-host.
+5. **Add `HostScopedClientGate`** at `app/h/_layout.tsx` to centralize
+   the gate and remove duplicated loading-state logic.
+6. **Delete legacy code.** Remove the dead `connect()` import paths
+   from each screen. Codepoint reduction.
+7. **Remove server-side `hasOtherConnections` complexity** in a
+   follow-up: with one socket per token, the multi-socket reconciliation
+   in `runtime-rpc.ts` `wsTransport.onConnectionClose` simplifies.
+   This is a desktop-side cleanup PR done after mobile rolls out.
+
+Each step is tested in isolation; rollback per step is trivial.
+
+## Risks
+
+### R1: Connection loss while screens are mounted
+
+**Risk.** Today, when a screen unmounts due to network loss, its
+client closes and reopens on remount. Under the new design, a
+network-loss-during-screen-mounted means the client lives but is in
+`reconnecting` state.
+
+**Mitigation.** The existing `RpcClient` already handles this — its
+internal reconnect loop runs invisibly. Screens already render based
+on `connState === 'connected'`, so they stay in their `connecting`
+UI until the loop succeeds. No regression.
+
+### R2: One bad host poisons the singleton
+
+**Risk.** If the client for one host is wedged in `reconnecting` due
+to a desktop-side issue, all screens for that host inherit the wedged
+state. Under the per-screen design, navigating to a different screen
+gave a fresh client with a chance to connect cleanly.
+
+**Mitigation.** "Force reconnect" affordance: a button on the host
+detail "Connection issues" UI calls
+`provider.forceReconnect(hostId)` — close + reopen the client. Users
+who hit a stuck state get a one-tap recovery without uninstalling.
+Implemented as part of step 2.
+
+### R3: Idle close timer races
+
+**Risk.** A user navigates from session → home → back to session
+within 35 seconds. The 30s idle timer fires between hops and closes
+the client; the back-navigation has to wait for a fresh handshake.
+
+**Mitigation.** Cancel the timer at `getClient(hostId)` time, not at
+mount time. As long as the consumer holds a reference to the client,
+the timer is paused. Standard refcount pattern.
+
+### R4: Memory / state leak on rapid host removal
+
+**Risk.** User removes a host while a screen for it is mounted.
+The screen's reference is now dangling.
+
+**Mitigation.** `removeHost(hostId)` triggers an explicit close +
+delete from the store. Screens already handle `auth-failed` /
+`disconnected` states (the client transitions to one of them on
+forced close). Add a navigation-bounce in those states so the screen
+returns to the host list.
+
+### R5: Pair-flow socket leaks through provider
+
+**Risk.** If pair-confirm crashes mid-handshake before its explicit
+`close()`, the socket leaks.
+
+**Mitigation.** Independent of the provider — same risk exists today.
+Add a try/finally + cleanup useEffect in pair-confirm.
+
+### R6: Provider re-initialization on hot reload (dev only)
+
+**Risk.** Metro hot reload re-runs `RpcClientProvider`, possibly
+spawning new clients while old ones are still in the store.
+
+**Mitigation.** On provider mount, scan the store for entries whose
+clients report `closed` state and prune. Acceptable dev-only friction.
+
+## Test Plan
+
+### Unit / hook tests
+
+- `useHostClient` returns the same client instance across multiple
+  consumers for the same hostId.
+- `removeHost(hostId)` immediately closes the client (assert via
+  `client.getState()`).
+- Idle close timer: zero refcount → 30s wait → client closed.
+- Idle close timer cancellation: zero refcount → 15s wait →
+  consumer subscribes → no close.
+
+### Integration / manual
+
+- Create one host; navigate home → host detail → session → back ×10
+  rapidly. Single socket on desktop (verify via desktop debug log).
+- Background app for 5 min; foreground; verify reconnect uses same
+  client instance, no leak.
+- Remove host while session screen mounted; screen bounces back to
+  home; client closed.
+- Force-reconnect button on host detail; client closes and reopens
+  cleanly.
+- Hot reload during development; no socket leak (verify desktop
+  active-connection count).
+
+### Regression
+
+- Terminal create/delete works during normal browse (Bug A from
+  initial reports — should never recur once cap pressure is removed).
+- Scrollback hydration unchanged.
+- Phone-fit / driver-lock state machine unchanged
+  (`docs/mobile-presence-lock.md` invariants hold).
+
+## Out of scope
+
+- **Desktop-side connection LRU eviction.** Useful as a defense-in-depth
+  but not needed once mobile self-limits to one socket per host.
+- **Application-level ping/pong.** Worth adding but separate concern;
+  helps server reap dead sockets faster regardless of how many a single
+  client opens.
+- **iOS share extension or system-wide deep-link integration.** Future
+  product work.
+
+## Effort estimate
+
+3–4 hours including tests and incremental migration. Each step
+independently mergeable.
+
+## References
+
+- `docs/mobile-presence-lock.md` — driver-state-machine that depends
+  on per-client identity. Single-client-per-host simplifies but
+  doesn't break this contract.
+- `docs/mobile-prefer-renderer-scrollback.md` — scrollback hydration
+  flow. Subscriptions remain per-screen; transport changes are
+  transparent.
+- `mobile/src/transport/rpc-client.ts` — existing `connect()`
+  implementation; reconnect loop, E2EE handshake, subscription
+  multiplexing all preserved as-is.
+- `src/main/runtime/rpc/ws-transport.ts` — server-side
+  `MAX_WS_CONNECTIONS = 32`, `hasOtherConnections` reconciliation
+  that becomes simpler post-migration.
diff --git a/docs/performance-audit.md b/docs/performance-audit.md
deleted file mode 100644
index a5f984cf241..00000000000
--- a/docs/performance-audit.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Orca Performance Audit
-
-Audit date: 2026-04-13
-Branch: `Jinwoo-H/performance-improvement`
-
----
-
-## Tier 1 — High Impact, Low Complexity
-
-| # | Area | Issue | File(s) | Status |
-|---|------|-------|---------|--------|
-| 1 | Renderer | `App.tsx` has 53 separate Zustand subscriptions — nearly every state change re-renders the root and cascades through the entire tree | `src/renderer/src/App.tsx:40-180` | DONE (53→22 subs, memo barriers on 4 children) |
-| 2 | Renderer | `Terminal.tsx` has unscoped `useAppStore.subscribe()` — fires on every store mutation, does O(worktrees×tabs) scan each time | `src/renderer/src/components/Terminal.tsx:645-659` | DONE |
-| 3 | Terminal | No IPC batching — every PTY data chunk is a separate `webContents.send` call, hundreds/sec under load | `src/main/ipc/pty.ts:173-177` | DONE |
-| 4 | Terminal | Divider drag calls `fitAddon.fit()` on every `pointermove` pixel — xterm reflow can take 500ms+ with large scrollback | `src/renderer/src/lib/pane-manager/pane-divider.ts:90-119` | DONE |
-| 5 | Main | Startup blocks: `openCodeHookService.start()` and `runtimeRpc.start()` awaited sequentially before window opens | `src/main/index.ts:131-168` | DONE |
-| 6 | Main | `persistence.ts` uses `readFileSync`/`writeFileSync`/`renameSync` on the main thread — blocks during startup and every 300ms save | `src/main/persistence.ts:59-125` | DONE |
-| 7 | Worktree | `worktrees:listAll` iterates repos sequentially with `await` — total time = sum of all repos instead of max | `src/main/ipc/worktrees.ts:53-84` | DONE |
-| 8 | Browser | Reverse Map scan O(N) on every mouse/load/permission event in `BrowserManager` | `src/main/browser/browser-manager.ts:91-96` | DONE |
-| 9 | Browser | `before-mouse-event` listener fires for ALL mouse events on ALL guests, even background ones | `src/main/browser/browser-guest-ui.ts:78-93` | DONE |
-| 10 | Worktree | `refreshGitHubForWorktree` bypasses 5-min cache TTL on every worktree switch — fires GitHub API calls on rapid tab switching | `src/renderer/src/store/slices/worktrees.ts:467-489` | DONE |
-
----
-
-## Tier 2 — Medium Impact
-
-| # | Area | Issue | File(s) | Status |
-|---|------|-------|---------|--------|
-| 11 | Main | `git/repo.ts`: `execSync('gh api user ...')` and chains of 5 sync git processes block main thread | `src/main/git/repo.ts:87-138` | TODO |
-| 12 | Main | `hooks.ts`: `readFileSync`/`writeFileSync`/`mkdirSync`/`gitExecFileSync` in IPC handlers | `src/main/hooks.ts:113-416` | TODO |
-| 13 | Renderer | `useSettings` returns entire `GlobalSettings` (~30+ fields) — any setting change re-renders all consumers | `src/renderer/src/store/selectors.ts` | TODO |
-| 14 | Renderer | Tab title changes bump `sortEpoch` for ALL worktrees → triggers WorktreeList re-sort on every PTY title event | `src/renderer/src/store/slices/terminals.ts:325` | TODO |
-| 15 | Renderer | `CacheTimer`: one `setInterval` per mounted card (20 cards = 20 intervals/sec), each with O(n) selector work | `src/renderer/src/components/sidebar/CacheTimer.tsx:28-48` | TODO |
-| 16 | Renderer | Three simultaneous 3-second polling intervals per active worktree (git status, worktrees, stale conflict) | `src/renderer/src/components/right-sidebar/useGitStatusPolling.ts` | TODO |
-| 17 | Renderer | 6 components missing `React.memo`: `SourceControl`, `RightSidebar`, `EditorPanel`, `ChecksPanel`, `FileExplorer`, `TabBar` | Various files in `src/renderer/src/components/` | DONE (8 components wrapped) |
-| 18 | Worktree | Git polling fires immediately on every worktree switch (burst of `git status` + `git worktree list`) | `src/renderer/src/components/right-sidebar/useGitStatusPolling.ts:69-103` | REVERTED (150ms debounce caused visible flash on switch) |
-| 19 | Worktree | `FileExplorer` `dirCache` discarded on every worktree switch — re-fetches entire tree from scratch | `src/renderer/src/components/right-sidebar/useFileExplorerTree.ts:27,81-96` | TODO |
-| 20 | Terminal | `pty:resize` uses `ipcRenderer.invoke` (round-trip) instead of fire-and-forget `send` | `src/preload/index.ts:203-205` | DONE |
-| 21 | Terminal | Flow control watermarks defined but never enforced for local PTYs — unbounded output floods renderer | `src/main/providers/local-pty-provider.ts:330-332` | TODO |
-| 22 | Browser | `BrowserPane` subscribes to entire `browserPagesByWorkspace` map — any tab's navigation re-renders all panes | `src/renderer/src/components/browser-pane/BrowserPane.tsx:312` | TODO |
-| 23 | Browser | `findPage`/`findWorkspace` do O(N) `Object.values().flat().find()` scans on every navigation event | `src/renderer/src/store/slices/browser.ts:221-240` | TODO |
-| 24 | Browser | Download progress IPC fires at full Chromium frequency (many/sec) | `src/main/browser/browser-manager.ts:421-430` | TODO |
-| 25 | Main | `detectConflictOperation` runs 4 `existsSync` + `readFile` on every 3s poll before git status | `src/main/git/status.ts:236-265` | DONE |
-| 26 | Main | `getBranchCompare`: `loadBranchChanges` and `countAheadCommits` run sequentially | `src/main/git/status.ts:374-375` | DONE |
-| 27 | Main | `addWorktree` calls 4-5 synchronous git processes from IPC handler | `src/main/git/worktree.ts:116-157` | DONE |
-
----
-
-## Tier 3 — Lower Impact / Architectural
-
-| # | Area | Issue | File(s) | Status |
-|---|------|-------|---------|--------|
-| 28 | Terminal | SSH relay `FrameDecoder` uses `Buffer.concat` on every chunk (quadratic copy) | `src/relay/protocol.ts:84` | TODO |
-| 29 | Terminal | SSH relay replay buffer uses string concatenation (quadratic allocation) | `src/relay/pty-handler.ts:68-72` | TODO |
-| 30 | Terminal | `extractLastOscTitle` regex runs on every PTY chunk with no fast-path bail | `src/shared/agent-detection.ts:23-39` | TODO |
-| 31 | Terminal | Binary search calls `serialize()` up to 16× at shutdown | `src/renderer/src/components/terminal-pane/TerminalPane.tsx:579-596` | TODO |
-| 32 | Browser | `capturePage()` captures full viewport then crops — should pass rect directly | `src/main/browser/browser-grab-screenshot.ts:36` | TODO |
-| 33 | Browser | Parked webviews retain full 100vw×100vh compositor surfaces | `src/renderer/src/components/browser-pane/BrowserPane.tsx:94-107` | TODO |
-| 34 | Browser | `onBeforeSendHeaders` intercepts every HTTPS request even when UA override unused | `src/main/browser/browser-session-registry.ts:126-137` | TODO |
-| 35 | Main | `setBackgroundThrottling(false)` wastes CPU when window is minimized | `src/main/window/createMainWindow.ts:97` | TODO |
-| 36 | Main | `warmSystemFontFamilies()` competes with startup I/O | `src/main/system-fonts.ts:30-32` | TODO |
-| 37 | Renderer | Session persistence effect has 15 deps — fires on every tab title change | `src/renderer/src/App.tsx:239-283` | TODO |
-| 38 | Renderer | Per-card `fetchPRForBranch` on mount — 30 worktrees = 30 simultaneous IPC calls | `src/renderer/src/components/sidebar/WorktreeCard.tsx:128-132` | TODO |
-| 39 | Renderer | Synchronous full `monaco-editor` import blocks EditorPanel chunk evaluation | `src/renderer/src/components/editor/EditorPanel.tsx:7` | TODO |
-| 40 | Worktree | `removeWorktree` runs `git worktree list` twice (pre and post removal) | `src/main/git/worktree.ts:163-208` | TODO |
-| 41 | Worktree | `worktrees:list` can trigger duplicate `git worktree list` when cache is dirty | `src/main/ipc/worktrees.ts:86-116` | TODO |
-| 42 | Renderer | SSH targets initialized sequentially in a `for...await` loop | `src/renderer/src/hooks/useIpcEvents.ts:232-252` | TODO |
-
----
-
-## Key Themes
-
-1. **Zustand subscription granularity** — `App.tsx` subscribes to 53 slices, `Terminal.tsx` subscribes to everything, `useSettings` returns the full object. Almost any state change cascades through the entire tree.
-
-2. **Synchronous I/O on the main thread** — `persistence.ts`, `hooks.ts`, `git/repo.ts`, and `git/worktree.ts` use `readFileSync`/`writeFileSync`/`execSync` in startup and IPC handler paths.
-
-3. **Unthrottled high-frequency events** — PTY data (no IPC batching), divider drag (fit on every pixel), download progress (no throttle), `before-mouse-event` (all mouse events on all guests), CacheTimer (20 intervals/sec).
-
-4. **Sequential operations that could be parallel** — Startup server binds, repo iteration in `listAll`, git ref probing, `loadBranchChanges`/`countAheadCommits`, SSH target init.
-
-5. **Aggressive polling** — Three 3-second intervals per worktree, per-card 1-second cache timers, per-card 5-minute issue polling, 250ms error-page detection.
diff --git a/docs/performance-implementation-plan.md b/docs/performance-implementation-plan.md
deleted file mode 100644
index 5d3c9a854ec..00000000000
--- a/docs/performance-implementation-plan.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Performance Improvement — Implementation Plan
-
-Branch: `Jinwoo-H/performance-improvement`
-
----
-
-## Completed (Tier 1)
-
-### Fix 3 — PTY IPC Data Batching
-**Files:** `src/main/ipc/pty.ts`
-**Change:** Added 8ms flush-window batching for PTY data. Instead of calling `webContents.send('pty:data', ...)` on every `node-pty` onData event, data is accumulated per-PTY in a `Map<string, string>` and flushed once per 8ms interval. Reduces IPC round-trips from hundreds/sec to ~120/sec under high throughput. Interactive latency stays below one frame (16ms).
-
-### Fix 4 — Divider Drag Throttled to rAF
-**Files:** `src/renderer/src/lib/pane-manager/pane-divider.ts`
-**Change:** Wrapped `refitPanesUnder` calls in `requestAnimationFrame` guard during `onPointerMove`. Previously `fitAddon.fit()` ran on every pointer event (~250Hz), each triggering a full xterm.js reflow (500ms+ with large scrollback). Now capped at 60fps. Cleanup on `onPointerUp` cancels pending rAF and runs one final refit.
-
-### Fix 5 — Startup Parallelization
-**Files:** `src/main/index.ts`
-**Change:** `openCodeHookService.start()`, `runtimeRpc.start()`, and `openMainWindow()` now run concurrently via `Promise.all` instead of three sequential `await`s. Window creation no longer blocked by server bind operations.
-
-### Fix 6 — Async Persistence Writes
-**Files:** `src/main/persistence.ts`, `src/main/persistence.test.ts`
-**Change:** Debounced `scheduleSave()` now calls `writeToDiskAsync()` using `fs/promises` (writeFile, rename, mkdir) instead of `writeFileSync`/`renameSync`. Synchronous `writeToDiskSync()` retained only for `flush()` at shutdown. Added `waitForPendingWrite()` for test await support.
-
-### Fix 7 — Parallel Worktree Listing
-**Files:** `src/main/ipc/worktrees.ts`
-**Change:** `worktrees:listAll` handler now uses `Promise.all(repos.map(...))` instead of sequential `for...of` loop. Total time = slowest repo, not sum of all repos. Each repo's `listRepoWorktrees` spawns `git worktree list` subprocess independently.
-
-### Fix 8 — BrowserManager Reverse Map
-**Files:** `src/main/browser/browser-manager.ts`
-**Change:** Added `tabIdByWebContentsId` reverse Map maintained in sync with `webContentsIdByTabId`. Replaced two O(N) `[...entries()].find()` scans with O(1) `.get()` lookups. Updated `registerGuest`, `unregisterGuest`, and `unregisterAll` to keep both maps in sync.
-
-### Fix 9 — Context Menu Listener Scoping
-**Files:** `src/main/browser/browser-guest-ui.ts`
-**Change:** `before-mouse-event` listener is now installed only when a context menu is open (on `context-menu` event) and removed on first `mouseDown` (dismiss). Previously fired for every mouse event on every guest surface.
-
-### Fix 10 — GitHub Cache TTL on Worktree Switch
-**Files:** `src/renderer/src/store/slices/github.ts`, `src/renderer/src/store/slices/worktrees.ts`, `src/renderer/src/store/slices/store-cascades.test.ts`
-**Change:** Added `refreshGitHubForWorktreeIfStale()` that checks cache age before fetching. `setActiveWorktree` now calls this instead of `refreshGitHubForWorktree` (which always force-refreshes). Eliminates unnecessary GitHub API calls on rapid worktree switching. Force-refresh still available via explicit user action.
-
-### Fix 20 (Tier 2 bonus) — PTY Resize Fire-and-Forget
-**Files:** `src/main/ipc/pty.ts`, `src/preload/index.ts`
-**Change:** `pty:resize` changed from `ipcMain.handle`/`ipcRenderer.invoke` (round-trip) to `ipcMain.on`/`ipcRenderer.send` (fire-and-forget). Halves IPC traffic for terminal resize events since the renderer never awaited the response anyway.
-
----
-
-## Completed (Tier 1 — continued)
-
-### Fix 1b — Session Persistence Extracted from React
-**Files:** `src/renderer/src/App.tsx`
-**Change:** Replaced the session-persistence `useEffect` (which had ~15 Zustand subscriptions as deps) with a single `useAppStore.subscribe()` call that runs outside React's render cycle. The subscriber debounces writes to disk via `window.setTimeout(150ms)`. This removed 12 `useAppStore` subscriptions from App's render cycle (`activeRepoId`, `terminalLayoutsByTabId`, `openFiles`, `activeFileIdByWorktree`, `activeTabTypeByWorktree`, `activeTabIdByWorktree`, `browserTabsByWorktree`, `browserPagesByWorkspace`, `activeBrowserTabIdByWorktree`, `unifiedTabsByWorktree`, `groupsByWorktree`, `activeGroupIdByWorktree`) — none of which ever drove JSX.
-
-### Fix 1a — Consolidated Action Subscriptions
-**Files:** `src/renderer/src/App.tsx`
-**Change:** Consolidated 19 stable action-ref subscriptions (`toggleSidebar`, `fetchRepos`, `openModal`, `setRightSidebarTab`, etc.) into a single `useShallow` selector returning an `actions` object. Since Zustand actions are referentially stable, the shallow equality check always passes and this subscription never triggers a re-render. All call sites updated to `actions.fetchRepos()`, `actions.toggleSidebar()`, etc.
-
-### Fix 1c — React.memo Barriers for Children
-**Files:** `src/renderer/src/components/sidebar/index.tsx`, `src/renderer/src/components/Terminal.tsx`, `src/renderer/src/components/right-sidebar/index.tsx`, `src/renderer/src/components/status-bar/StatusBar.tsx`
-**Change:** Wrapped `Sidebar`, `Terminal`, `RightSidebar`, and `StatusBar` in `React.memo`. These components accept no props from App — they read state from the store directly. The memo barrier prevents App's remaining re-renders (from layout state like `sidebarWidth`, `activeView`) from cascading into the full component tree.
-
-### Fix 2 — Terminal.tsx Scoped Subscribe
-**Files:** `src/renderer/src/components/Terminal.tsx`
-**Change:** The `useAppStore.subscribe()` that destroys orphaned browser webviews now short-circuits with a reference equality check (`state.browserTabsByWorktree === prevBrowserTabs`). Previously fired on every store mutation; now only runs the O(tabs) scan when `browserTabsByWorktree` actually changes.
-
-**Total App.tsx subscription reduction: 53 → 22 (58% fewer)**
-
----
-
-## Planned — Tier 2
-
-### Fix 11 — Async Git Username/Login
-**Files:** `src/main/git/repo.ts`
-**Change:** Replace `execSync('gh api user ...')` and `gitExecFileSync` chains in `getGhLogin`, `getGitUsername`, and `getDefaultBaseRef` with their async equivalents. `getDefaultBaseRefAsync` already exists — remove the sync variant and migrate all callers. The `Store.hydrateRepo` call in `getRepos()` is synchronous and uses `getGitUsername` — convert to a lazy-populate pattern where the `gitUsername` field is initially empty and filled by an async hydration pass after construction.
-
-### Fix 12 — Async Hooks File I/O
-**Files:** `src/main/hooks.ts`
-**Change:** Convert `loadHooks`, `hasHooksFile`, `hasUnrecognizedOrcaYamlKeys`, `readIssueCommand`, `writeIssueCommand`, and `createWorktreeRunnerScript` from `readFileSync`/`writeFileSync`/`mkdirSync`/`gitExecFileSync` to `fs/promises` + `gitExecFileAsync`. Update all callers in `src/main/ipc/worktrees.ts` to await the new async versions.
-
-### Fix 13 — Narrow `useSettings` Selector
-**Files:** `src/renderer/src/store/selectors.ts`, all 10 consumers
-**Change:** The current `useSettings = () => useAppStore((s) => s.settings)` returns the entire GlobalSettings object (~30 fields). Any setting change re-renders every consumer. Replace with field-specific selectors or use `useShallow` at each call site to select only the fields used by that component:
-- `App.tsx` only uses `settings.theme` → `useAppStore((s) => s.settings?.theme)`
-- `MonacoEditor.tsx` uses font/tab/theme → `useShallow` for those 3 fields
-- `AddWorktreeDialog.tsx` uses one field → direct selector
-
-### Fix 14 — Narrow sortEpoch Bumping
-**Files:** `src/renderer/src/store/slices/terminals.ts`
-**Change:** `updateTabTitle` currently bumps `sortEpoch` on every title string change for background worktrees (line 354). Title strings change frequently during agent runs (shell prompts, command names). Only bump `sortEpoch` when the agent working/idle status boundary is actually crossed. This requires comparing the old and new title against the agent-status detection logic before deciding to increment.
-
-### Fix 15 — Shared CacheTimer Interval
-**Files:** `src/renderer/src/components/sidebar/CacheTimer.tsx`
-**Change:** Each `CacheTimer` instance creates its own 1-second `setInterval`. With 20 visible cards this means 20 intervals firing per second, each running a Zustand selector that iterates `Object.keys(s.cacheTimerByKey)`. Replace with a single shared interval at the module level (or in the store slice) that updates a `remainingByWorktreeId` map in one `set()` call. Components subscribe to only their specific worktree's entry.
-
-### Fix 16 — Consolidate Git Status Polling
-**Files:** `src/renderer/src/components/right-sidebar/useGitStatusPolling.ts`
-**Change:** Three `setInterval(fn, 3000)` calls run simultaneously: git status, fetchWorktrees, and stale conflict poll. The worktree list poll (every 3s) is aggressive — branch changes inside terminals are low-frequency. Consolidate into a single interval:
-- Git status poll: keep at 3s (drives diff gutter, status badge)
-- Worktree list poll: increase to 15s (only needed when user runs `git checkout` in terminal)
-- Stale conflict poll: keep at 3s but only when stale worktrees exist (already gated)
-
-### Fix 17 — React.memo on Heavy Components
-**Files:** `SourceControl.tsx`, `EditorPanel.tsx`, `FileExplorer.tsx`, `TabBar.tsx`
-**Change:** Wrapped all four in `React.memo`. Combined with the Tier 1 memo barriers on Sidebar/Terminal/RightSidebar/StatusBar, a total of 8 heavy components now prevent parent re-render cascades.
-
-### Fix 18 — Debounce Git Polling on Worktree Switch
-**Files:** `src/renderer/src/components/right-sidebar/useGitStatusPolling.ts`
-**Change:** Replaced the immediate `void fetchStatus()` and `void fetchWorktrees(activeRepoId)` calls with 150ms `setTimeout` debounces. The interval polling continues as before. Rapid worktree switching now only fires one git status + one git worktree list subprocess instead of N.
-
-### Fix 19 — Cache FileExplorer dirCache Per Worktree
-**Files:** `src/renderer/src/components/right-sidebar/useFileExplorerTree.ts`
-**Change:** `dirCache` is local `useState` — reset on every worktree switch. Cache the directory tree per worktree in a `useRef<Map<string, DirCache>>()` at the hook level. On switch, restore from cache instantly (with a background revalidation fetch). This makes repeated worktree switches O(1) for the file explorer.
-
-### Fix 21 — Local PTY Flow Control
-**Files:** `src/main/providers/local-pty-provider.ts`, `src/renderer/src/components/terminal-pane/pty-dispatcher.ts`
-**Change:** Wire up the already-defined `PTY_FLOW_HIGH_WATERMARK` (100KB) and `PTY_FLOW_LOW_WATERMARK` (5KB) constants. Track pending bytes per PTY in the renderer's `EagerPtyBuffer`. When pending exceeds high watermark, send an IPC message to pause the node-pty stream. Resume when acknowledged down to low watermark. The `acknowledgeDataEvent` channel is already plumbed — just needs implementation.
-
-### Fix 22 — Narrow BrowserPane Selector
-**Files:** `src/renderer/src/components/browser-pane/BrowserPane.tsx`
-**Change:** Line 312: `useAppStore((s) => s.browserPagesByWorkspace)` subscribes to the entire map. Any tab's navigation re-renders all BrowserPane instances. Narrow to: `useAppStore((s) => s.browserPagesByWorkspace[browserTab.id] ?? EMPTY_BROWSER_PAGES)`.
-
-### Fix 23 — Index-Based findPage/findWorkspace
-**Files:** `src/renderer/src/store/slices/browser.ts`
-**Change:** `findWorkspace` and `findPage` (lines 221-240) use `Object.values().flat().find()` on every navigation event. Accept `worktreeId`/`workspaceId` as a hint parameter and do direct key access: `browserTabsByWorktree[worktreeId]?.find(...)` instead of flattening across all worktrees.
-
-### Fix 24 — Throttle Download Progress
-**Files:** `src/main/browser/browser-manager.ts`
-**Change:** `download.item.on('updated', ...)` fires at full Chromium frequency. Add per-download throttle timer — only call `sendDownloadProgress` at most once per 250ms. Clear throttle timer on download done/cancel.
-
-### Fix 25 — Parallelize detectConflictOperation with git status
-**Files:** `src/main/git/status.ts`
-**Change:** `getStatus()` now kicks off both `detectConflictOperation()` and `git status` concurrently. The conflict detection promise is started first and awaited before the status result, preserving error semantics while overlapping I/O.
-
-### Fix 26 — Parallelize getBranchCompare
-**Files:** `src/main/git/status.ts`
-**Change:** `loadBranchChanges` and `countAheadCommits` now run via `Promise.all` instead of sequentially. These are independent git subprocess calls.
-
-### Fix 27 — Async addWorktree
-**Files:** `src/main/git/worktree.ts`, `src/main/ipc/worktree-remote.ts`, `src/main/runtime/orca-runtime.ts`
-**Change:** Converted `addWorktree` from synchronous (`gitExecFileSync`) to async (`gitExecFileAsync`). This was the last major sync git operation on the main thread — 4-5 sequential subprocess calls that blocked the event loop during worktree creation. Updated callers and all 7 tests.
-
----
-
-## Benchmark Validation Results (2026-04-14)
-
-Ran 6 targeted benchmarks to validate optimization claims. Full scripts in `benchmarks/`.
-
-| Fix | What was measured | Result | Verdict |
-|-----|-------------------|--------|---------|
-| 3 — PTY Batching | IPC calls/sec: unbatched vs 8ms window | 5000→125 calls/sec (98% reduction) | **Validated — high impact** |
-| 5/7 — Parallelization | Sequential vs parallel subprocess at N=5 | 119ms→46ms (2.6x, 73ms saved) | **Validated — high impact** |
-| 6 — Async I/O | Main-thread blocking: sync vs fire-and-forget | 439µs→21µs per write (21x less blocking) | **Validated — high impact** |
-| 1 — Zustand Subs | Selector cost: 53 subs vs 18 subs | 2.61µs→1.59µs per mutation (1.6x) | **Validated — moderate** (real win is cascade prevention via React.memo) |
-| 8 — Reverse Map | entries().find() vs Map.get() at N=10 | 409ns→1ns (479x) but 0.04ms/sec total | **Deprioritize** — micro-optimization |
-| 23 — flat().find() | Object.values().flat().find() vs direct at 50 tabs | 1958ns→62ns (31x) but 0.02ms/sec total | **Deprioritize** — micro-optimization |
-
-### Deprioritized based on benchmarks
-
-The following fixes are technically correct but save <0.1ms/sec at realistic load. Moved to "nice to have":
-- Fix 8 (Reverse Map) — already implemented, keep as-is
-- Fix 14 (sortEpoch) — per-mutation overhead is negligible
-- Fix 15 (CacheTimer shared interval) — 20 intervals/sec is fine for modern JS engines
-- Fix 22 (BrowserPane selector) — sub-microsecond per render
-- Fix 23 (findPage/findWorkspace) — 0.02ms/sec at 10 nav/sec
-- Fix 24 (Download progress throttle) — infrequent event
-- Fix 26 (getBranchCompare parallel) — implemented anyway since it was a one-liner
-
----
-
-## Key Themes
-
-1. **Zustand subscription granularity** — Fixes 1, 2, 13, 14, 17, 22 all reduce the blast radius of state changes on React re-renders.
-
-2. **Synchronous I/O on main thread** — Fixes 6, 11, 12, 27 convert blocking filesystem and git operations to async.
-
-3. **Unthrottled high-frequency events** — Fixes 3, 4, 9, 15, 20, 24 cap event processing to reasonable rates.
-
-4. **Sequential → parallel** — Fixes 5, 7, 25, 26 run independent async operations concurrently.
-
-5. **Aggressive polling** — Fixes 16, 18 consolidate and debounce polling intervals.
diff --git a/docs/preload-typecheck-hole.md b/docs/preload-typecheck-hole.md
deleted file mode 100644
index dad51a267a5..00000000000
--- a/docs/preload-typecheck-hole.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Preload typecheck hole: why project-owned types live in `.ts`
-
-## The rule
-
-Project-owned type declarations under `src/preload/` and `src/shared/`
-**must live in `.ts` files, not `.d.ts`**. The CI step
-"Guard against project-owned .d.ts in preload/shared" in
-`.github/workflows/pr.yml` enforces this.
-
-## Why
-
-Orca inherits `skipLibCheck: true` from `@electron-toolkit/tsconfig`.
-That setting is the ecosystem default — it exists so a broken `.d.ts`
-in some random `node_modules` package can't block your build. TypeScript
-has no way to scope it to `node_modules`, so **`skipLibCheck`
-applies to our own `.d.ts` files too**.
-
-In a project-owned `.d.ts`, any type reference that fails to resolve
-silently becomes `any` at its call sites instead of erroring. Downstream
-assignments against that `any` are also silently accepted. The error
-never surfaces during `pnpm typecheck`.
-
-For example, with `skipLibCheck: true`:
-
-```ts
-// in src/preload/index.d.ts — Worktree is never imported
-type WorktreesApi = {
-  list: () => Promise<Worktree[]>  // silently becomes Promise<any[]>
-}
-```
-
-and at the call site:
-
-```ts
-// in any renderer file
-window.api.worktrees.list().then((arr) => {
-  setWorktreeName(arr)  // setWorktreeName expects string; accepted anyway because arr is any[]
-})
-```
-
-No compile error. Crashes at runtime.
-
-The standard TS convention that sidesteps this: put project-owned types in
-`.ts` (which are always checked), reserve `.d.ts` for ambient shims
-(`env.d.ts`, `vite/client.d.ts`, etc.). The CI guard encodes that
-convention mechanically.
-
-## Incident that forced the fix
-
-PR #1186 changed the `repos:getBaseRefDefault` IPC return shape from
-`Promise<string | null>` to `Promise<BaseRefDefaultResult>` (an envelope
-object). Two of three renderer callers were updated; the third
-(`StartFromField.tsx`) wasn't. That caller passed the envelope object
-into a `setState<string | null>` setter, which rendered as JSX and threw
-React error #31 (`Objects are not valid as a React child`).
-
-**The call site should have been a compile error.** It wasn't, because
-`src/preload/index.d.ts` (now deleted) was a 246-line project-owned
-`.d.ts` that referenced ~20 type names it never imported (`Worktree`,
-`PRInfo`, `GlobalSettings`, `BaseRefDefaultResult`, and more). Under
-`skipLibCheck`, each unresolved name became `any`, which widened the
-`.then((ref) => …)` callback parameter to `any` at the consuming call
-site. `setDefaultBaseRef(ref: any)` compiled cleanly.
-
-The crash is fixed by #1189. The typecheck hole is fixed by this PR
-(#1197), which collapses the two preload type files (`index.d.ts` +
-`api-types.d.ts`) into a single type-checked `api-types.ts`. Full design
-discussion, alternatives considered, and rollout notes live in PR #1197.
-
-## Non-obvious subtleties worth remembering
-
-- **It's not the hand-authored types that failed — it was the missing
-  imports.** The types in the old `index.d.ts` were individually fine;
-  the file only went wrong because names like `Worktree` and `PRInfo`
-  weren't imported and `skipLibCheck` swallowed the error. A future
-  contributor copy-pasting types out of a `.d.ts` into `.ts` may be
-  surprised by a wall of "Cannot find name 'X'" errors — that's the
-  flag catching its target, not a real regression.
-- **`.d.ts` is still legitimate for ambient shims.** `env.d.ts`,
-  `mermaid.d.ts`, `hosted-git-info.d.ts` all live *outside* the CI
-  guard's scan roots (`src/preload/` and `src/shared/`) and stay as
-  `.d.ts`. If a future file under those roots genuinely needs to be
-  `.d.ts` (e.g., an ambient module shim for a third-party package that
-  can't live in `.ts`), add it to an allowlist in `pr.yml` at that
-  time — don't relax the guard wholesale.
-- **Intersection types on `window.api` are what actually widened the
-  `.then` callback to `any`.** The old layout used
-  `type Api = PreloadApi & { repos: ReposApi, worktrees: WorktreesApi, … }`.
-  TypeScript's intersection-of-function-types resolution widens callback
-  parameters to `any` when one side of the intersection has unresolved
-  names, *even though static-inspection views
-  (`ReturnType<typeof fn>`) still report the correct type*. So
-  `ReturnType<typeof window.api.repos.getBaseRefDefault>` printed
-  `Promise<BaseRefDefaultResult>` during debugging while the live
-  `.then((ref) => …)` callback treated `ref` as `any`. Don't re-introduce
-  intersection typing on the preload surface for any reason.
-- **Don't try to fix this by flipping `skipLibCheck: false` globally.**
-  It would force every transitive `@types/*` package to type-check
-  cleanly, which is why the ecosystem-wide default is `true`. The
-  structural fix (project-owned types in `.ts`) removes our last
-  reason to care about the flag for our code.
diff --git a/docs/quickly-jump-to-worktree.md b/docs/quickly-jump-to-worktree.md
deleted file mode 100644
index 43e48a91b02..00000000000
--- a/docs/quickly-jump-to-worktree.md
+++ /dev/null
@@ -1,242 +0,0 @@
-# Design Document: Quick Jump to Worktree (Issue #426)
-
-## 1. Overview
-
-As Orca scales to support multiple parallel agents and tasks, users frequently need to switch between dozens of active worktrees. Navigating via the sidebar becomes inefficient at scale.
-
-This document describes the shipped "Quick Jump" palette in Orca: a globally accessible Command Palette-style dialog that lets users jump across active worktrees, open browser tabs that live inside worktrees, and create a new worktree from typed input. Search covers worktree metadata (name, branch, repo, comment, PR metadata, issue metadata) and browser metadata (page title, URL, worktree, repo).
-
-## 2. User Experience (UX)
-
-### 2.1 The Shortcut: `Cmd+J` (macOS) / `Ctrl+Shift+J` (Windows/Linux)
-
-To establish this palette as the central "Switch Worktree" action in Orca, `**Cmd+J**` (macOS) and `**Ctrl+Shift+J**` (Windows/Linux) are the chosen shortcuts.
-
-**Why `Cmd+J` / `Ctrl+Shift+J`?**
-
-- **Matches the action honestly:** This palette switches between existing worktrees. "Jump" is a better semantic fit than "Open" because the user is navigating, not creating a new file-open flow.
-- **Avoids `Ctrl+J` (Line Feed) conflict:** On Windows and Linux, `Ctrl+J` translates to a Line Feed (`\n`) in bash, zsh, and almost all readline-based CLI applications. For many terminal power users, `Ctrl+J` and `Ctrl+M` (Carriage Return) are used interchangeably with the physical `Enter` key to execute commands. In Vim, it is used for navigation or inserting newlines, and in Emacs it maps to `newline-and-indent`. Intercepting `Ctrl+J` globally would severely disrupt core terminal workflows. Thus, `Ctrl+Shift+J` is used on these platforms. (On macOS, `Cmd` is an OS-level modifier, so `Cmd+J` safely avoids this issue).
-- **Avoids `Cmd+K` conflict:** In terminal-heavy apps, `Cmd+K` is universally expected to "Clear Terminal". Overriding it breaks developer muscle memory.
-- **Avoids `Cmd+P` conflict:** `Cmd+P` is already in use for Quick Open File (`QuickOpen.tsx`).
-- **Avoids `Ctrl+E` (readline):** `Ctrl+E` is "end of line" in bash/zsh readline. Stealing it in a terminal-heavy app would break shell navigation muscle memory — the same class of conflict that rules out `Cmd+K`.
-- **Discoverability:** The shortcut should be registered in the Electron Application Menu (e.g., `View -> Open Worktree Palette`) so users can discover it visually.
-
-### 2.2 The Interface
-
-When the shortcut is pressed, a modal dialog appears at the center top of the screen (similar to VS Code's palette or Spotlight).
-
-- **Input:** A text input focused automatically.
-- **List:** A scrollable list constrained to `max-h-[min(460px,62vh)]` to prevent the palette from overflowing the viewport when many results are present.
-- **Default state (empty query):** When the palette opens with no query, the full list of non-archived worktrees is shown first, ordered by Orca's smart sort. If browser tabs also exist, they appear as a secondary section preview below the worktree list. The palette intentionally ignores the sidebar's `showActiveOnly` and `filterRepoIds` filters — it is a global jump tool, not a filtered view.
-- **Sorting (Smart Semantics):** The palette uses Orca's smart worktree ordering via `sortWorktreesSmart(...)`, not plain recency. In practice this prioritizes active agent work, permission-needed state, unread state, live terminals, PR signal, linked issue, and recent activity, with a cold-start fallback to persisted `sortOrder` until any PTY is live.
-- **Visual Hierarchy &amp; Highlights:** Because search covers multiple fields simultaneously, the list items must visually clarify *why* a result matched. If the match is inside a comment, display a truncated snippet of that comment centered around the matched range, with the matching text highlighted.
-- **Multi-repo disambiguation:** Each list item always displays the repository name (e.g., `stablyai/orca`) alongside the worktree name. This is required because the palette spans all repos — without it, two worktrees named "main" from different repos would be indistinguishable.
-- **Cross-surface scope:** The palette is not limited to worktrees. It also surfaces browser tabs, and when the user types a string that matches no worktree results it offers a "Create worktree" action using the current query.
-- **Empty State:** Two cases: (1) If the user has no active worktrees and no browser tabs, display "No active worktrees or browser tabs". (2) If items exist but none match the search query, display "No results match your search." Both use `<Command.Empty>`.
-- **Search fields:** The search input will match against:
-  - Worktree `displayName`
-  - Worktree `branch`, normalized via `branchName()` to strip the `refs/heads/` prefix (e.g., `refs/heads/feature/auth-fix` → `feature/auth-fix`)
-  - Repository name (e.g., `stablyai/orca`)
-  - Full `comment` text attached to the worktree
-  - Linked PR number/title. Two paths: (a) auto-detected PR via `prCache` (cache key: `${repo.path}::${branch}`), which has both number and title; (b) manual `linkedPR` fallback, which has number only (no title to search against). If `prCache` has a hit, prefer it; otherwise fall back to `linkedPR` number matching.
-  - Linked issue number/title. The issue number comes from `w.linkedIssue`; the title comes from `issueCache` (cache key: `${repo.path}::${w.linkedIssue}`). Number matching works even without a cache hit; title matching requires the cache entry to be populated.
-  - **Cache freshness caveat:** PR and issue data is populated by `refreshGitHubForWorktree`, which runs on worktree activation, and by `refreshAllGitHub`, which runs on window re-focus (`visibilitychange`). On startup, `initGitHubCache` loads previously persisted PR/issue data from disk, so worktrees fetched in prior sessions start with warm caches. Worktrees that have never been activated, were not covered by a `refreshAllGitHub` pass, and have no persisted cache entry will have empty caches — PR/issue title search will silently miss them. This is acceptable: the gap is limited to brand-new worktrees between creation and the next activation or window re-focus cycle. Number-based matching (e.g., `#304`) always works because it checks `w.linkedPR` / `w.linkedIssue` directly, without the cache.
-  - `**#`-prefix handling:** A leading `#` in the query is stripped before matching PR/issue numbers (e.g., `#304` matches number `304`), with a guard against bare `#` which would produce an empty string and match everything. This mirrors the existing `matchesSearch()` behavior.
-- **Browser search fields:** Browser page title, URL/secondary text, worktree name, and repo name.
-- **Navigation:** `Up` / `Down` arrows to navigate the list, `Enter` to select. `Escape` closes the modal.
-
-## 3. Technical Architecture
-
-### 3.1 UI Components
-
-Orca uses `shadcn/ui` and ships the **Command** component, which wraps the `cmdk` library.
-
-**Dependency:** `cmdk` is a direct dependency in `package.json`.
-
-```bash
-pnpm dlx shadcn@latest add command
-```
-
-Note: `CommandDialog` uses Radix Dialog internally. Orca keeps this inside the shared `components/ui/command.tsx` wrapper so both palettes use the same dialog primitives and styling hooks.
-
-**z-index:** The `CommandDialog` must use `z-50` or higher to reliably overlay the terminal and sidebar, consistent with `QuickOpen.tsx` which uses `z-50` on its fixed overlay container.
-
-- `**WorktreeJumpPalette.tsx`:** A new component mounted at the root of the app (inside `App.tsx`, alongside the existing `<QuickOpen />`) to ensure it can be summoned from anywhere.
-- `**CommandDialog`:** The shadcn component used to render the modal.
-
-### 3.2 Keyboard Shortcut
-
-The shipped shortcut uses a **hybrid main-process + renderer architecture**:
-
-1. The main window listens in `before-input-event` and resolves the chord through the shared window shortcut policy.
-2. On `toggleWorktreePalette`, the main process sends `ui:toggleWorktreePalette` to the renderer.
-3. The renderer toggles `activeModal === 'worktree-palette'` in `useIpcEvents.ts`.
-
-This extra main-process hop is required because browser guests and other embedded Chromium surfaces can keep keyboard focus inside a guest `webContents`, bypassing the renderer's `window`-level `keydown` listener. A renderer-only implementation would fail from browser-tab focus.
-
-**Toggle semantics:** If the palette is already open, the shortcut closes it; otherwise it opens it. There is no `activeWorktreeId` or `activeView` guard, so the palette is available from settings, from landing states with no active worktree, and from browser focus.
-
-**Overlay mutual exclusion:** The current app models both Quick Open and the worktree palette inside the existing `activeModal` union in `ui.ts` (`'quick-open'` and `'worktree-palette'`). This keeps the two command palettes mutually exclusive without needing separate booleans.
-
-**Menu registration:** Register a `View -> Open Worktree Palette` entry in `register-app-menu.ts` for discoverability, consistent with Section 2.1. The entry must use a **display-only shortcut hint** — do **not** set `accelerator: 'CmdOrCtrl+J'`. In Electron, menu accelerators intercept key events at the main-process level *before* the renderer's `keydown` handler fires (this is how `CmdOrCtrl+,` for Settings works — its `click` handler runs in the main process via `onOpenSettings`). If `CmdOrCtrl+J` were registered as a real accelerator, the renderer `keydown` handler would never see the event, and the overlay mutual-exclusion logic (which runs in the renderer) would be bypassed. Instead, show the shortcut text in the menu label (e.g., `label: 'Open Worktree Palette\tCmdOrCtrl+J'`) without binding `accelerator`, matching the pattern used by `Cmd+P` (QuickOpen), which has no menu entry at all and relies solely on the renderer handler.
-
-### 3.3 State Management
-
-- **Visibility state:** The palette is represented by `activeModal === 'worktree-palette'` in the UI slice. Quick Open similarly uses `activeModal === 'quick-open'`.
-- **Palette session state:** `query` and `selectedIndex` are ephemeral to the palette component and should live in React component state (not Zustand). They reset on every open.
-- **Render optimization:** When the modal is closed, `CommandDialog` unmounts its content, which is sufficient.
-- **Ordering:** Worktree results are fed through `sortWorktreesSmart(...)`, and browser results are ordered relative to that same worktree ordering so both sections feel consistent.
-
-### 3.4 Data Layer &amp; Search
-
-The palette needs access to all worktrees known to Orca.
-
-- **Data source:** Read from the existing `worktreesByRepo` in Zustand (already populated via `fetchAllWorktrees` on startup and kept in sync via IPC push events). No new IPC channel is needed. Filter out archived worktrees (`!w.isArchived`) before searching or displaying. Do **not** apply the sidebar's `showActiveOnly` or `filterRepoIds` filters — the palette is a global jump tool that surfaces all non-archived worktrees regardless of the sidebar's filter state. Because the palette reads directly from `worktreesByRepo`, it reactively updates if a worktree is created or deleted via IPC push while the palette is open — no special stale-list handling is needed.
-
-#### Search implementation
-
-The sidebar already has a `matchesSearch()` function in `worktree-list-groups.ts` that does **substring matching** (`includes(q)`) against displayName, branch, repo, comment, PR, and issue fields. The palette search builds on this foundation but extends it. Note: `branchName()` (used to strip `refs/heads/` prefixes) is currently exported from `worktree-list-groups.ts` — a sidebar-specific module that imports Lucide icons (`CircleCheckBig`, `CircleDot`, etc.) at the top level. Importing `branchName` from it would pull the entire module (including unused icon components) into the palette's bundle. `smart-sort.ts` has its own duplicate: `branchDisplayName()` doing the identical `branch.replace(/^refs\/heads\//, '')`. Extract `branchName()` to a shared utility (`lib/git-utils.ts`) in Phase 1, and update `worktree-list-groups.ts` and `smart-sort.ts` to import from there. This is a 3-line function — the extraction is trivial and avoids the bundle bloat.
-
-1. **Matching strategy: substring, not fuzzy.** Use case-insensitive substring matching for worktrees and browser entries. True fuzzy matching (ordered-character, like `QuickOpen.tsx`'s `fuzzyMatch`) is not used here.
-2. **Structured match metadata:** Unlike `matchesSearch()` (which returns `boolean`), the palette search helper returns a result object:
-
-```ts
-type MatchRange = { start: number; end: number }
-
-type PaletteMatchBase = { worktreeId: string }
-
-/** Empty query — all non-archived worktrees shown, no match metadata. */
-type PaletteMatchAll = PaletteMatchBase & {
-  matchedField: null
-  matchRange: null
-}
-
-/** Comment match — includes a truncated snippet centered on the matched range. */
-type PaletteMatchComment = PaletteMatchBase & {
-  matchedField: 'comment'
-  matchRange: MatchRange
-  snippet: string
-}
-
-/** Non-comment field match — range within the matched field's display value. */
-type PaletteMatchField = PaletteMatchBase & {
-  matchedField: 'displayName' | 'branch' | 'repo' | 'pr' | 'issue'
-  matchRange: MatchRange
-}
-
-type PaletteMatch = PaletteMatchAll | PaletteMatchComment | PaletteMatchField
-```
-
-3. **Field priority order:** When multiple fields match, report the first match by priority: `displayName` &gt; `branch` &gt; `repo` &gt; `comment` &gt; `pr` &gt; `issue`. This determines which badge/highlight is shown.
-4. **Comment snippet extraction:** Search against the full `comment` text. Only the *rendered snippet* is truncated — extract ~80 characters of surrounding context centered on the matched range. Clamping: `snippetStart = Math.max(0, matchStart - 40)`, `snippetEnd = Math.min(comment.length, matchEnd + 40)`. After clamping, snap to word boundaries: scan `snippetStart` backward (up to 10 chars) to the nearest whitespace or string start; scan `snippetEnd` forward (up to 10 chars) to the nearest whitespace or string end. This avoids cutting words mid-character (e.g., `…e implementation of th…` → `…the implementation of the…`). Prepend `…` if `snippetStart > 0`; append `…` if `snippetEnd < comment.length`.
-5. `**cmdk` wiring:** Render with `shouldFilter={false}` so the palette controls filtering. Pass only the filtered result set to `<Command.Item>`:
-
-```tsx
-<Command.Item
-  key={worktree.id}
-  value={worktree.id}
-  onSelect={() => handleSelectWorktree(worktree.id)}
->
-  {/* Render worktree row with match badge + highlighted range */}
-</Command.Item>
-```
-
-6. **Performance:** Keep `value` compact and do not stuff full comments into `keywords`. The current implementation debounces the query by 150ms before recomputing result sets. That keeps mixed worktree + browser searching cheap without materially hurting responsiveness at Orca's current scale.
-
-### 3.5 Action (Worktree Activation)
-
-#### Existing callsite analysis
-
-The codebase has several worktree activation paths with inconsistent step coverage:
-
-
-| Step                                 | `WorktreeCard` click | `Cmd+1–9` | `AddRepoDialog` | `AddWorktreeDialog` |
-| ------------------------------------ | -------------------- | --------- | --------------- | ------------------- |
-| Set `activeRepoId`                   | No                   | No        | Yes             | Yes                 |
-| Set `activeView`                     | No                   | No        | Yes             | Yes                 |
-| `setActiveWorktree()`                | Yes                  | Yes       | Yes             | Yes                 |
-| `ensureWorktreeHasInitialTerminal()` | No                   | No        | Yes             | Yes                 |
-| `revealWorktreeInSidebar()`          | No                   | Yes       | Yes             | Yes                 |
-
-
-Sidebar card clicks and `Cmd+1–9` work without setting `activeRepoId` because `activeRepoId` is only consumed by the "Create Worktree" dialog (to pre-select a repo) and session persistence — it does not gate rendering or data fetching for the switched-to worktree. Similarly, `ensureWorktreeHasInitialTerminal` is only needed for newly created worktrees that have never been opened; existing worktrees already have terminal tabs.
-
-#### Palette activation sequence
-
-The palette should match what `Cmd+1–9` does today (the closest analog: jumping to a visible worktree from any context), plus a few extras justified by the palette's cross-repo scope:
-
-1. **Set `activeRepoId`:** If the target worktree's `repoId` differs from the current `activeRepoId`, call `setActiveRepo(repoId)`. This keeps session persistence and the "Create Worktree" repo pre-selection accurate. Sidebar clicks skip this because they operate within a single repo group; the palette does not have that constraint.
-2. **Switch `activeView`:** If `activeView` is `'settings'`, set it to `'terminal'` so the main content area renders the worktree surface. `Cmd+1–9` does not handle this because it refuses to fire at all from the settings view (gated on `activeView !== 'settings'` in the `onKeyDown` handler); the palette intentionally has no such guard so users can jump to a worktree directly from settings.
-3. **Call `setActiveWorktree(worktreeId)`:** This runs Orca's existing activation sequence: sets `activeWorktreeId`, restores per-worktree editor state (`activeFileId`, `activeTabType`, `activeBrowserTabId`), restores the last-active terminal tab, clears unread state, bumps dead PTY generations, and triggers `refreshGitHubForWorktree` to ensure PR/issue/checks data is current for the newly active worktree.
-4. **Ensure a focusable surface:** If the worktree has no renderable tabs, call `ensureWorktreeHasInitialTerminal` (`worktree-activation.ts`). The helper now decides this via the reconciled tab model, not by checking whether the legacy terminal-tab array is empty.
-5. **Reveal in sidebar:** Call `revealWorktreeInSidebar(worktreeId)` to ensure the selected worktree is visible (handles collapsed groups and scroll position).
-6. **Close the palette.**
-
-#### Shared helper
-
-The five activation steps above overlap heavily with `AddRepoDialog.handleOpenWorktree` and `AddWorktreeDialog`'s post-create flow. With three callsites now sharing the same core sequence, extract a shared `activateAndRevealWorktree(worktreeId: string, opts?: { setup?: WorktreeSetupLaunch })` helper in `worktree-activation.ts` that covers the common steps: set `activeRepoId` (cross-repo), switch `activeView` (from settings), `setActiveWorktree`, `ensureWorktreeHasInitialTerminal`, clear sidebar filters that would hide the target, and `revealWorktreeInSidebar`.
-
-**Sidebar filter clearing:** The helper must clear any sidebar filter state that would prevent the target card from being rendered, because `revealWorktreeInSidebar` relies on the worktree card being *rendered* in the sidebar (the `pendingRevealWorktreeId` effect in `WorktreeList` finds the target in the rendered `rows` array via `findIndex`). If sidebar filters exclude the target, the card is never rendered and the reveal silently no-ops — the user selects a worktree and nothing visually happens. `AddWorktreeDialog` already handles this inline (clears both `searchQuery` and `filterRepoIds` before activation); the shared helper absorbs that responsibility. Specifically:
-
-- Clear `filterRepoIds` if it is non-empty and does not include the target worktree's repo.
-- Clear `searchQuery` unconditionally if it is non-empty. Even if the target repo is visible, an active text search might exclude the specific worktree being jumped to.
-
-Callsite-specific extras that remain inline after calling the shared helper:
-
-- `**AddWorktreeDialog`:** `setSidebarOpen(true)`, open right sidebar if `rightSidebarOpenByDefault`.
-- `**AddRepoDialog`:** `closeModal()` (the palette closes itself separately).
-- **Palette:** close the palette, focus management (Section 3.5 Focus management).
-
-The helper derives `repoId` internally via `findWorktreeById(worktreesByRepo, worktreeId)` (`worktree-helpers.ts:45`) — the caller only passes `worktreeId`. If the worktree is not found (e.g., deleted between palette open and select), the helper returns early without side effects.
-
-#### Focus management
-
-- **On worktree select:** After closing the palette, use a double `requestAnimationFrame` (nested rAF) to focus the active terminal/editor surface for the target worktree. `onCloseAutoFocus` calls `preventDefault()` so Radix does not steal focus.
-- **On browser-tab select:** Restore focus to the selected browser page, preferring the address bar for blank/new pages and the webview for loaded pages.
-- **On escape/cancel:** Restore focus to the previously active browser page when the palette was opened from browser context; otherwise fall back to the terminal/editor surface for the previously active worktree. If no worktree was active, focus falls to the document body.
-
-### 3.6 Accessibility
-
-The `cmdk` library provides built-in ARIA support:
-
-- `role="combobox"` on the input
-- `role="listbox"` / `role="option"` on the list and items
-- `aria-activedescendant` for keyboard navigation
-- `aria-expanded` on the dialog
-
-**Additional requirements:**
-
-- Announce filtered result count changes to screen readers via an `aria-live="polite"` region (e.g., "3 worktrees found").
-- Match-field badges (e.g., `Branch`, `Comment`) should include `aria-label` text so screen readers convey why the result matched.
-
-## 4. Implementation Status
-
-The core design is implemented:
-
-- `cmdk` is a direct dependency and Orca ships a shared `CommandDialog`.
-- `WorktreeJumpPalette.tsx` is mounted at the app root.
-- The palette opens through main-process shortcut forwarding plus renderer IPC toggle handling.
-- Worktree activation is routed through `activateAndRevealWorktree(...)`.
-- Search supports comment snippets, PR/issue metadata, browser pages, and a create-worktree action.
-- Menu discoverability is implemented with a display-only `View -> Open Worktree Palette` hint and no accelerator binding.
-
-## 5. Remaining Gaps / Future Work
-
-- Add broader integration coverage for the mixed worktree/browser palette behavior; current tests focus on search helper behavior and shortcut/menu plumbing.
-- Evaluate whether the 150ms debounce should become adaptive if the palette eventually indexes substantially more browser pages.
-- Consider unifying the worktree and browser result models further if future result types are added.
-
-**Future work (out of scope)**
-
-- Evaluate migrating `QuickOpen.tsx` (currently a custom overlay with manual keyboard handling) to `cmdk`/`CommandDialog` for visual and behavioral consistency with the palette. This is a separate project — `QuickOpen` has its own fuzzy matching, file-loading, and keyboard handling that would need reworking.
-- Add richer end-to-end coverage for palette interactions launched from browser focus, including focus restoration after browser-tab selection and dismissal.
-
-## 6. Alternatives Considered
-
-- `**Cmd+O` (Open):** Standard app semantic, but less honest for this feature because the palette switches between existing worktrees rather than opening a new file or workspace. Rejected in favor of `Cmd+J`, which better matches the action users are taking.
-- `**Ctrl+E` (Explore):** Initially considered for Windows/Linux. Rejected because `Ctrl+E` is "end of line" in bash/zsh readline — stealing it in a terminal-heavy app breaks shell navigation muscle memory.
-- `**Ctrl+Alt+O`:** Initially considered for Windows/Linux but rejected to avoid `AltGr` collisions on international keyboards (e.g., Polish, German layouts).
-- `**Cmd+1...9` (Direct jumping):** Doesn't scale past 9 worktrees and requires the user to memorize sidebar positions. Already implemented as a complementary feature.
-- `**Cmd+K`:** Rejected due to conflict with "Clear Terminal".
-- `**Cmd+P`:** Rejected because it is already used for file searching (`QuickOpen.tsx`).
-- **Renderer-only shortcut handling:** Initially attractive because it mirrors simpler shortcuts, but rejected for the shipped palette. Browser guests can keep keyboard focus inside a separate `webContents`, so a renderer-only `window` listener would miss `Cmd+J` / `Ctrl+Shift+J` from browser-tab focus.
diff --git a/docs/remote-folder-picker-redesign.md b/docs/remote-folder-picker-redesign.md
deleted file mode 100644
index 79036d1b607..00000000000
--- a/docs/remote-folder-picker-redesign.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Remote SSH Folder Picker — Redesign Proposal
-
-## Context
-
-The "Browse remote filesystem" dialog lets users pick a directory on a connected SSH target to open as a remote project. It's reached from: sidebar → Add project → Open remote project → folder-picker icon next to the Remote path input.
-
-**Source:** `src/renderer/src/components/sidebar/RemoteFileBrowser.tsx`
-**Invoked from:** `src/renderer/src/components/sidebar/AddRepoSteps.tsx` (`RemoteStep`, around line 167)
-
-## User complaints
-
-1. **Hard to find the desired folder** — list is flat and unfiltered; on a home directory with 30+ dotfiles/dirs, you scroll.
-2. **Nested folders not discoverable as navigable** — current model is single-click = highlight, double-click = navigate. Users don't discover the double-click.
-3. **Unclear consequence of pressing "Select"** — button is generic; the dialog doesn't say what happens to the chosen folder next.
-
-## Current behavior (for reference)
-
-- Single-click a row → sets `selectedName`, highlights the row.
-- Double-click a folder row → navigates into it.
-- "Select" button → if a row is highlighted, returns `<resolvedPath>/<selectedName>`; otherwise returns `resolvedPath` (the current directory).
-- Breadcrumb bar at top with ↑, 🏠, and clickable path segments.
-- Footer shows the path that will be returned: either current dir or `current/highlighted`.
-
-## Reference: how others do it
-
-- **VS Code** (`simpleFileDialog.ts`): one unified input at the top doubles as (a) current path, (b) filter as you type, (c) editable path entry. Enter key navigates into folders; OK button label is caller-supplied ("Open Folder", etc.). Auto-complete suggests folders inline.
-- **Superset, Warp**: no comparable picker.
-
-## Options considered
-
-### Option A — VS Code-style: selection = current directory
-Drop the "highlight a row" model entirely. Navigate into the folder you want (single-click enters it), then "Select" always returns the current directory.
-
-**Rejected because:** breaks Finder/Explorer muscle memory (double-click to open is a universal convention), and adds a click for the common case of picking a visible child folder.
-
-### Option B — chevron-on-folders affordance
-Add a `›` navigation button on folder rows to make "enter this folder" discoverable to mouse users. A permanent chevron is visual noise, so we show it only on row hover (and on keyboard focus for a11y parity).
-
-### Option C — add a filter input
-Add a text input at the top of the list that live-filters visible entries by substring. No change to the selection model.
-
-### Chosen: Option C + Option B
-The filter input (C) addresses complaint #1 and surfaces `Enter`-to-navigate for keyboard users. The hover/focus chevron (B) addresses complaint #2 for mouse users without the visual noise of a permanent affordance. The two are independent and compose cleanly.
-
-## Proposed change
-
-### 1. Filter input (addresses complaint #1)
-
-- Add a text input above the file list (below the breadcrumb bar) that auto-focuses on mount. The picker only mounts when the outer dialog opens (verified: `AddRepoSteps.tsx` conditionally renders `RemoteFileBrowser` based on dialog-open state), so the auto-focus cannot steal focus from the outer dialog's inputs.
-- Live-filter `entries` by case-insensitive substring match on `entry.name`. **Filters both files and folders** — hiding files would confuse users trying to confirm they're in the right directory (e.g. looking for a README). Files remain non-actionable.
-- Keyboard (handled on the input's `onKeyDown`):
-  - `↓` / `↑` — move the highlight (`selectedName`) through the *filtered* list. `preventDefault` so the caret doesn't jump. Clamps at the ends: ArrowUp at the first filtered entry (or with nothing highlighted) stays put; it never triggers parent-directory navigation. Parent-nav is exclusively the breadcrumb `↑` button.
-  - `Enter` — precedence: (a) if a folder is highlighted, navigate into it; (b) else if a **file** is highlighted, surface the transient footer hint (below) and do not navigate; (c) else if the filtered set contains exactly one folder (regardless of how many files are also in the set), navigate into that folder; (d) else highlight the first filtered entry (file or folder) — this is a highlight-only step and the visible highlight is the feedback; a subsequent `Enter` then re-enters this ladder and hits (a) or (b). Rule (b) is the only path that triggers the hint, so a filter that matches only files and is already highlighted on the first entry keeps yielding the hint on repeated `Enter`, never a silent no-op. The hint text is `Files can't be opened as a project`, shown in the footer for 2s before reverting. Chose the footer hint over an input shake/flash because it needs no animation infrastructure and the footer is already the dialog's status region.
-  - `Esc` — if filter is non-empty, clear it and `stopPropagation` so the outer dialog doesn't close; otherwise let the event bubble and call `onCancel`.
-- **Focus management:** the input retains focus across row clicks. Clicking a row calls `setSelectedName` but does not steal focus (`onMouseDown` with `preventDefault` on the row buttons, or explicit `inputRef.current?.focus()` after selection). This keeps arrow keys and typing working after the user mouses.
-- **Navigation helper.** Introduce a `navigate(path)` wrapper that calls `loadDir(path)` *and* clears the filter. All user-initiated navigation (breadcrumb segment click, the breadcrumb `↑` parent-directory button, double-click, chevron click, `Enter`-to-enter-folder) goes through `navigate`. The `↑`/`↓` ArrowUp/ArrowDown *keys* move the filter-list highlight per the keyboard spec above and do not call `navigate`. The mount effect calls `loadDir(path)` directly — it never clears the filter, so a user who types before the first load completes does not lose their input. This removes the `didInitialLoad` ref.
-- When the filter changes, if the current `selectedName` is no longer in the filtered list, clear it so the button label doesn't go stale.
-- **Empty-state copy.** When `entries.length > 0` but `filteredEntries.length === 0`, render `No matches for '<filter>'` instead of the generic `Empty directory` copy — the latter is misleading when the directory has contents that are simply filtered out.
-- Placeholder: `Type to filter…` with a leading `Search` icon (lucide) for scannability, matching the existing icon-prefixed inputs in the sidebar.
-
-### 2. Dynamic button label (addresses complaint #3)
-
-Replace the static "Select" label with the path it will return:
-
-- When a row is highlighted: `Select /home/neil/myproject`
-- When no row is highlighted: `Select /home/neil` (the current directory)
-- **Left-ellipsis truncation.** Plain Tailwind `truncate` right-ellipsizes, which hides the meaningful tail. Use `direction: rtl; text-align: left;` on an inner span wrapping the path (keep the word "Select" in a separate LTR span), or equivalent CSS. Add the full path as a `title` attribute for hover-tooltip verification. Note: RTL-directionality on the path span can reorder punctuation in filenames that themselves contain RTL characters — accepted as a tiny edge-case risk for SSH target paths.
-
-This makes the two selection modes (child vs. current dir) visible without any model change, and tells the user exactly what will be opened.
-
-### 3. Footer
-
-Keep the existing muted full-path line — it's the unambiguous source of truth when the button label is ellipsized. Prepend a short hint so first-time users know what Select does:
-
-> Opens as a remote project · `/home/neil/myproject`
-
-Single line, muted, truncates with right-ellipsis (the prefix is the fixed part, the path tail can be cut since it's already in the button's `title`).
-
-When `Enter` is pressed on a highlighted file, swap this line for `Files can't be opened as a project` (same muted style) for 2s, then revert. Clear the hint's timer eagerly on any filter change or navigation so the message never outlives the state it describes.
-
-### 4. Folder-row chevron (addresses complaint #2)
-
-Folder rows render a `›` icon (lucide `ChevronRight`) on the right edge, shown only on row hover or keyboard focus. Files never render the chevron.
-
-- **Trigger:** CSS `:hover` on the row plus a `:focus-visible` rule so keyboard-focused rows also show it. Never always-visible — a permanent chevron is visual noise across a long list.
-- **Click handler:** the chevron is a nested `<button>` with its own `onClick` that calls `navigate(entry.path)`. It must `stopPropagation` so the parent row's single-click-select handler doesn't also fire. Clicking the chevron is equivalent to double-clicking the row.
-- **a11y:** `aria-label="Open <name>"`. Reachable via Tab when the row is focused; `Enter`/`Space` on the focused chevron navigates into the folder. Screen readers announce the label distinctly from the row's select action.
-- **Hit target:** ≥ 24px square, padded inside the row so touchpad taps land reliably.
-
-## What is NOT changing
-
-- **Selection model** — single-click highlights, double-click navigates. Finder/Explorer conventions preserved.
-- **Breadcrumb bar** — already good; nicer than VS Code's path-in-input approach.
-- **Non-git-folder handling** — `AddRepoSteps.tsx` lines 108–117 still opens the `confirm-non-git-folder` modal on `Not a valid git repository`. Out of scope.
-
-## Tests
-
-Add a co-located test file (following the pattern of `smart-sort.test.ts` etc. in the same directory). Minimum coverage:
-
-- Filter substring-matches case-insensitively across files and folders.
-- `Enter` with a single folder match navigates into it.
-- `Enter` with multiple matches and no highlight highlights the first filtered entry.
-- `Enter` on a highlighted file surfaces the transient footer hint (`Files can't be opened as a project`) and does not navigate.
-- `Esc` with a non-empty filter clears it and does not call `onCancel`; `Esc` with empty filter calls `onCancel`.
-- `selectedName` is cleared when the filter change removes it from the visible list.
-- Filter is *not* cleared by the initial mount load; *is* cleared by a subsequent `navigate(path)` call.
-- **Path equivalence:** navigating into `foo` (via chevron/double-click/`Enter`) then pressing `Select` returns the same `onSelect` path as highlighting `foo` from its parent and pressing `Select`.
-- Clicking a folder row's chevron navigates into the folder and does not leave the row merely highlighted (i.e. chevron click is not swallowed by the row's select handler).
-- Empty-state copy: with a non-empty directory and a filter that matches nothing, the list shows `No matches for '<filter>'`, not `Empty directory`.
-
-## Files to change
-
-- `src/renderer/src/components/sidebar/RemoteFileBrowser.tsx` — all UI changes live here (filter input, `navigate` wrapper, chevron on folder rows, footer hint state, empty-state copy).
-- `src/renderer/src/components/sidebar/RemoteFileBrowser.test.tsx` — new.
-- No IPC, main-process, or `AddRepoSteps.tsx` changes required.
-
-## Follow-ups (not this PR)
-
-- **State bloat.** The component will accumulate several pieces of local state (`entries`, `selectedName`, `filter`, `resolvedPath`, transient footer-hint flag, loading/error). Consider consolidating into a `useReducer` in a later pass; leaving as discrete `useState` hooks for this PR to keep the diff reviewable.
diff --git a/docs/resource-usage-merge-spec.md b/docs/resource-usage-merge-spec.md
new file mode 100644
index 00000000000..46e56612557
--- /dev/null
+++ b/docs/resource-usage-merge-spec.md
@@ -0,0 +1,387 @@
+# Resource Usage popover: merge Resources + Sessions into one view
+
+## Problem
+
+The status-bar Resource Usage popover currently has two tabs:
+
+- **Resources** — per-worktree CPU/memory grouped by repo, sourced from
+  `MemorySnapshot.worktrees`. Local PTYs only (SSH excluded by design at
+  `src/main/ipc/pty.ts:832` because remote process trees are not visible
+  to the local `ps`/`wmic` sweep).
+- **Sessions** — flat list of every PTY the daemon tracks (local **and**
+  SSH), sourced from `pty.listSessions()`. Adds tab-binding info, click-
+  to-navigate, kill-X per row, and "Kill N orphans".
+
+The data sources only partially overlap: Sessions can show worktrees
+(e.g. `orca/Porpoise`, `orca/Stingray`) that never appear in Resources
+because they're SSH-backed. Users see this as a confusing inconsistency
+between two adjacent tabs in the same popover.
+
+The user wants one unified view that:
+
+1. Lists every PTY the daemon knows about (the union, not the
+   intersection).
+2. Shows CPU/memory **when available** (i.e. for local PTYs) and `—` for
+   remote ones, rather than silently dropping remote sessions.
+3. Keeps tab-binding affordances (click row → navigate, kill X with
+   confirm dialog) on every row.
+4. Surfaces orphans (PTYs not bound to any tab) with the "Kill N
+   orphans" bulk action.
+
+## Direction (already decided by user)
+
+> Merge into one tab, drop the switcher entirely.
+
+Out of scope:
+
+- Adding new IPC. The merge uses **only** the data already available:
+  `MemorySnapshot` and `pty.listSessions()`.
+- Changing what the memory collector tracks. SSH PTYs remain unsampled.
+  The unified view simply shows them with empty metric cells instead of
+  hiding them.
+- Adding new actions (e.g. "stop all in repo", per-repo restart, etc.).
+  The exact action set today (kill one with confirm, kill orphans, sleep
+  worktree, restart daemon, kill-all-sessions) is preserved.
+
+## Data model
+
+### Inputs
+
+- `snapshot: MemorySnapshot | null` — local-only CPU/Mem data, grouped
+  by `worktreeId`. May be `null` while the daemon is unreachable.
+- `sessions: DaemonSession[]` — every PTY id the daemon knows, with
+  `cwd`, `title`, and a sticky `isAlive`-equivalent.
+- `tabsByWorktree`, `ptyIdsByTabId`, `runtimePaneTitlesByTabId`,
+  `workspaceSessionReady` — store-side context used to (a) compute
+  bound/orphan and (b) resolve human labels.
+
+### Output: a renderer-local view model
+
+The merge produces a renderer-local view-model — **not** a widening of
+the shared `WorktreeMemory` shape. `src/shared/types.ts` and the
+collector are untouched. New types live next to the merge helper:
+
+```ts
+// src/renderer/src/components/status-bar/unifiedRow.ts
+type Metric = number | null  // null === "no local sample" (e.g. SSH)
+
+type UnifiedSessionRow = {
+  sessionId: string
+  label: string
+  bound: boolean
+  tabId: string | null
+  cpu: Metric
+  memory: Metric
+  hasLocalSamples: boolean
+}
+
+type UnifiedWorktreeRow = {
+  worktreeId: string
+  worktreeName: string
+  repoId: string
+  repoName: string
+  cpu: Metric
+  memory: Metric
+  history: number[]          // empty when hasLocalSamples is false
+  hasLocalSamples: boolean
+  sessions: UnifiedSessionRow[]
+}
+
+type UnifiedRepoGroup = {
+  repoId: string
+  repoName: string
+  cpu: Metric                // null if every child has hasLocalSamples false
+  memory: Metric
+  hasRemoteChildren: boolean // drives the "· remote" badge on the row
+  worktrees: UnifiedWorktreeRow[]
+}
+```
+
+A small adapter inside `mergeSnapshotAndSessions` converts each
+`WorktreeMemory` from the shared type into a `UnifiedWorktreeRow` with
+numeric metrics and `hasLocalSamples: true`. Synthetic remote rows are
+constructed directly with `null` metrics. The existing `MetricPair` and
+`Sparkline` callsites in the popover get a thin wrapper that renders
+`—` when its input is `null`; nothing in `src/shared/` or `src/main/`
+changes.
+
+### Merge algorithm
+
+The merge is renderer-only and pure. Inputs in priority order:
+
+- **Snapshot first.** `snapshot.worktrees` is the authoritative source
+  for any local PTY's CPU/Mem and for the worktree's identity (it
+  already carries `worktreeId`, `worktreeName`, `repoId`, `repoName`,
+  and a `sessions[]` array with per-session metrics).
+- **Sessions augments.** `sessions: DaemonSession[]` is the union over
+  the snapshot — it adds (a) SSH PTYs that the local memory collector
+  cannot see and (b) any local PTY that registered too late to make
+  this snapshot's sweep.
+
+#### Join key (snapshot session ↔ daemon session)
+
+Both layers identify a session by the **same string**: the PTY id.
+
+- `SessionMemory.sessionId` (collector) is `pty.sessionId ?? pty.ptyId`
+  from `pty-registry.ts`. In-process local PTYs spawn with
+  `args.sessionId === undefined` (`pty.ts:684`), so the registry stores
+  `sessionId: null` and the fallback `pty.ptyId` is used — which equals
+  `result.id` from the local provider's spawn, which is also what
+  `LocalPtyProvider.listProcesses()` returns as `id`
+  (`local-pty-provider.ts:518-522`).
+- For daemon-hosted spawns, `mintPtySessionId(worktreeId)` produces the
+  `${worktreeId}@@${shortUuid}` form
+  (`src/main/daemon/pty-session-id.ts`); both the registry and
+  `pty.listSessions()` carry that exact string as the id.
+
+Therefore the dedup key is simply `session.id` on both sides. The
+merge MUST build `Set<string>` of all `SessionMemory.sessionId`s from
+the snapshot and skip any `DaemonSession` whose `id` is already in the
+set (so a local session never appears twice — once with metrics, once
+as a `—` placeholder).
+
+#### Worktree resolution for `DaemonSession`s
+
+When a `DaemonSession` is **not** already accounted for by the
+snapshot, we need to bucket it under a worktree group. Try in order:
+
+1. **Tab-store walk** (existing logic in `SessionsTabPanel`): look up
+   `ptyIdsByTabId` → `tabId` → `tabsByWorktree` → `worktreeId`. This
+   resolves any session bound to a live tab in *this* renderer.
+2. **Session-id parse**: if the id contains `@@`, take
+   `id.slice(0, id.lastIndexOf('@@'))` as a candidate `worktreeId`.
+   This is the convention enforced by `mintPtySessionId` (see
+   `pty-session-id.ts:5-7` and the symmetric parser in
+   `daemon-pty-adapter.ts:328-331`). It correctly recovers the
+   worktreeId for SSH sessions that haven't been bound to a tab in
+   this Orca instance — which is the user's primary scenario
+   (`orca/Stingray`, `orca/Sawfish`, etc.).
+3. **Unattributed**: if neither resolves, bucket under a synthetic
+   `unattributed` repo group at the bottom of the list.
+
+The `repoId` for each new worktree group is recovered the same way the
+collector does it (`collector.ts:resolveWorktreeNames`): split the
+worktreeId on the first `::`. Resolved repo display name comes from
+the renderer-side store (`store.repos[repoId]?.displayName`) when
+available; otherwise the bare `repoId` is used.
+
+#### Step-by-step
+
+1. Initialize `repos: Map<repoId, UnifiedRepoGroup>` empty.
+2. Insert all `snapshot.worktrees` (if any) into the map, grouped by
+   their `repoId`. Each worktree carries `hasLocalSamples: true` and
+   numeric metrics; its sessions inherit numeric metrics.
+3. Build `seenSessionIds = new Set<string>(...all session ids in
+   snapshot.worktrees[].sessions)`.
+4. For each `DaemonSession` in `sessions: DaemonSession[]`:
+   - If `seenSessionIds.has(session.id)`, skip (already merged from
+     snapshot).
+   - Resolve `worktreeId` per the three-step rule above.
+   - If the resolved `worktreeId` is already a worktree group in the
+     map, append the session to its `sessions[]` with `cpu: null`,
+     `memory: null`, `hasLocalSamples: false`. (Reachable for SSH
+     sessions whose worktree happens to match a locally-active
+     worktree id — rare but possible.)
+   - Otherwise, create a new worktree group with `cpu: null`,
+     `memory: null`, `history: []`, `hasLocalSamples: false`, and
+     append the session.
+5. Compute per-repo aggregates: sum `cpu`/`memory` from worktrees with
+   `hasLocalSamples === true`. If the repo has *any* worktree with
+   `hasLocalSamples === false`, set `repoHasRemoteChildren: true` (used
+   by the UI to render a `· remote` badge on the repo header so the
+   user knows the displayed totals exclude remote worktrees).
+6. The Orca app section (Main / Renderer / Other) renders unchanged
+   below the list.
+
+The whole pass is O(W + S) where W = snapshot worktrees and S =
+sessions. No nested scans.
+
+### Why this is safe with current data
+
+- Every existing local session continues to render with the same
+  numbers. The merge **adds** rows; it does not change values.
+- The snapshot rebuilds every poll (10s), so SSH sessions transitioning
+  to local (or vice versa) flip representation on the next tick. No
+  reconciliation logic needed.
+- Orphan detection still works: a session is "bound" iff its
+  `sessionId` appears in `boundPtyIds`. Sessions in repos we couldn't
+  resolve still get the X-kill affordance.
+
+## UI
+
+### Trigger (status-bar badge) — unchanged
+
+Mac/Linux/Windows safe (no platform-specific glyphs introduced).
+
+### Popover — single panel, fixed height
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Resource Usage                          ⟳   🗑  ✕         │ ← header
+├─────────────────────────────────────────────────────────────┤
+│  1.9% · 955.2 MB · 3% of system RAM                         │ ← summary
+├─────────────────────────────────────────────────────────────┤
+│  Name                                       CPU   Memory  · │ ← sort row
+├─────────────────────────────────────────────────────────────┤
+│  ▾ Triton                                   0.0%  125.5 MB │
+│      Terminal 1                             0.0%   63.2 MB ✕│
+│      Terminal 1                             0.0%    1.3 MB ✕│
+│  ▾ Stingray              ⓘ remote            —      —       │
+│      orca/Stingray                          —      —      ✕│
+│  ▾ Sawfish               ⓘ remote            —      —       │
+│      orca/Sawfish                           —      —      ✕│
+│  ─────────────────────────                                  │
+│  ▸ Orca app                                 0.5%  829.7 MB │
+└─────────────────────────────────────────────────────────────┘
+                        ↑ fixed 420px body, owns its own scroll
+                        ↓ orphan bulk-kill pill renders here when N>0
+```
+
+The header keeps the icon-only **Restart daemon** (RotateCw) and
+**Kill all sessions** (Trash2) buttons in the top-right.
+
+### Interaction states (4 paths)
+
+| Scenario                    | Resource cells | Kill X      | Click row    |
+|-----------------------------|----------------|-------------|--------------|
+| Local PTY, bound            | numeric        | hover only  | navigates    |
+| Local PTY, orphan           | numeric        | always      | no-op        |
+| Remote PTY, bound           | `—`            | hover only  | navigates    |
+| Remote PTY, orphan          | `—`            | always      | no-op        |
+
+`—` is rendered as `text-muted-foreground/50`. The worktree row carries
+a small `· remote` badge when `hasLocalSamples === false`; the repo row
+carries the same badge when `hasRemoteChildren === true` (so users
+know the displayed repo totals exclude remote worktrees).
+
+**`bound` semantics are unchanged from today:** a session is bound iff
+`boundPtyIds.has(session.id)` evaluated against this renderer's
+`ptyIdsByTabId`. SSH sessions bound to tabs in *another* Orca process
+look identical to local orphans here — same as before the merge.
+
+### Empty / loading / error states
+
+- Daemon unreachable → existing banner remains, body shows nothing.
+- Sessions error AND no snapshot AND zero sessions → "Resource data
+  unavailable. Restart daemon."
+- Snapshot present but zero worktrees AND zero sessions → "Nothing
+  running right now."
+- Loading (no snapshot, no error) → "Loading…".
+
+### Sort
+
+Three buttons in the sort row: **Name**, **CPU**, **Memory**. CPU/Mem
+sort puts `null` metrics last (stable). Name uses `localeCompare`.
+Selection is repo-group aware: sorting by CPU sorts repos by aggregate
+CPU and worktrees within a repo by their CPU.
+
+### Confirm dialogs (unchanged)
+
+- Per-row kill X: confirm Dialog with copy "Kill this session? Force-
+  quits `<id>`. Any unsaved work in that pane is lost. This can't be
+  undone."
+- Header Trash2: existing "Kill all sessions" Dialog from
+  `useDaemonActions`.
+- Header RotateCw: existing "Restart daemon" Dialog from
+  `useDaemonActions`.
+- Worktree-level Sleep / Delete: unchanged.
+
+## Implementation plan
+
+1. **New helper** `mergeSnapshotAndSessions.ts` (renderer-side, pure
+   function) that takes `(snapshot, sessions, storeContext)` and
+   returns the unified `RepoGroup[]` shape above. Unit-testable.
+2. **Refactor `ResourceUsageStatusSegment.tsx`**:
+   - Remove the tab switcher (drop `activeTab` state, both
+     `'resources'` / `'sessions'` branches, the inline pill component,
+     and the `Trash2` import for the old switcher).
+   - Replace the body with a single render path that consumes the
+     unified `RepoGroup[]` from the helper.
+   - Keep the existing `WorktreeSection`/`AppSection` patterns — extend
+     them to render `null` metrics as `—` and to render the kill-X on
+     each session row (with bound-vs-orphan visibility rule).
+   - Promote `killConfirm` state and the confirm Dialog from
+     `SessionsTabPanel` to the segment level since there's only one
+     panel now.
+   - Keep `onSessionsChanged` plumbing — call it from kill / kill-
+     orphans handlers to trigger an immediate `refreshSessions()`.
+   - Delete the now-unused `SessionsTabPanel` component.
+3. **Wire metric formatting** to render `—` when metric is `null`. Use
+   the `null`-vs-`0` distinction already present in the data model;
+   don't conflate them.
+4. **Migration**: status-bar item id stays `'resource-usage'`. The
+   `migrateStatusBarItems` helper is unchanged. No persistence
+   migration needed for this UI-only change.
+
+## Testing
+
+- Unit: `mergeSnapshotAndSessions` with synthetic inputs covering:
+  - All 4 interaction-state paths (local-bound, local-orphan,
+    remote-bound, remote-orphan).
+  - **Dedup**: a local session that appears in both the snapshot and
+    the daemon list is rendered exactly once with numeric metrics.
+  - **`@@` parse**: an SSH session id `repoX::/path/wtA@@abcd` with no
+    matching tab resolves to repoId `repoX`, worktreeId
+    `repoX::/path/wtA`.
+  - **Tab walk wins over `@@` parse**: a session bound to a tab whose
+    worktreeId differs from the `@@` prefix uses the tab's worktreeId
+    (defensive against id-format drift).
+  - **Repo aggregate excludes remote children**: a repo with one
+    local (125 MB) and one remote (`null`) worktree reports
+    `cpu/memory = 125 MB` and `hasRemoteChildren = true`.
+  - Edge cases: snapshot null, sessions empty, both empty, sessionId
+    without `@@` and no tab match → falls into Unattributed.
+- Manual:
+  - Open with mixed local + SSH worktrees → both render, SSH rows show
+    `—` and a `· remote` badge on their worktree and repo headers.
+  - Kill a remote session via the X → confirm dialog → optimistic
+    removal so row disappears immediately (does not wait 10s).
+  - Kill all (header trash) → orphans gone, bound sessions remain.
+  - Resize window / scroll the body → fixed 420px holds, no reflow.
+  - Accessibility: tab through rows → kill X focusable; after kill
+    confirm, focus lands back on the popover content root, not on
+    `<body>`. Dialog is keyboard-dismissable except while in-flight.
+
+## Risks & mitigations
+
+- **Risk**: SSH worktrees the user never opened locally still appear in
+  Resources (potentially noisy if the daemon retains many idle SSH
+  sessions). **Mitigation**: bucketing under a `· remote` badge keeps
+  them visually distinct from local-active groups; sort-by-memory pushes
+  them to the bottom. If noise becomes a real complaint, a future PR
+  can add a "hide remote" toggle.
+- **Risk**: Some sessions can't be resolved to any worktreeId (e.g.
+  daemon-internal sessions whose ids don't follow the `@@` convention,
+  or sessions whose worktreeId resolves to a repo store doesn't know
+  about). **Mitigation**: synthetic `Unattributed` repo group at the
+  bottom, which already exists in spirit as `ORPHAN_WORKTREE_ID` in the
+  memory collector.
+- **Risk**: Kill-X on a remote session fires `pty.kill(id)`, which the
+  IPC layer routes through `ptyOwnership` to the right SSH provider.
+  Behavior is identical to the old Sessions tab — no new failure mode.
+- **Risk: poll-rate skew between snapshot (2s) and sessions (10s).**
+  After killing an SSH session, the daemon-side `sessions` list can
+  retain the dead row for up to 10s while the snapshot has already
+  moved on; conversely a freshly-spawned local PTY shows up in
+  `sessions` first and is rendered as a remote placeholder for up to
+  2s before the next snapshot promotes it.
+  **Mitigation**: per-row kill optimistically removes the session id
+  from the renderer's local `sessions` state immediately after the IPC
+  resolves (in addition to calling `onSessionsChanged()`), so the
+  killed row never lingers on screen. The new-session-flash is
+  bounded by `POLL_MS` and acceptable.
+- **Risk: focus dropped to `<body>` after kill confirm.** When the
+  killed session disappears on the next refresh, the per-row X that
+  had focus is unmounted. With the confirm Dialog now mounted at the
+  segment level, this regression is more visible.
+  **Mitigation**: after `runKillConfirmed` resolves, focus the
+  popover's content root via a stable ref so keyboard users land back
+  in the list, not on `<body>`.
+
+## Non-goals
+
+- No new IPC.
+- No collector changes.
+- No new persisted UI prefs (the per-tab visibility split is gone, not
+  replaced with a per-section toggle).
+- No remote memory sampling — that's a separate, much bigger project.
diff --git a/docs/split-groups-rollout-pr1.md b/docs/split-groups-rollout-pr1.md
deleted file mode 100644
index 44f2053b3b8..00000000000
--- a/docs/split-groups-rollout-pr1.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Split Groups PR 1: Model Foundations
-
-This branch lands the behavior-neutral tab-group model groundwork.
-
-Scope:
-- add persisted tab-group layout state
-- add active-group persistence and hydration
-- add group-aware unified-tab helpers in the store
-- connect editor/open-file flows to the unified tab-group model
-
-What Is Actually Hooked Up In This PR:
-- the store persists `groupsByWorktree`, `layoutByWorktree`, and `activeGroupIdByWorktree`
-- workspace session save/hydration includes tab-group layouts
-- editor actions create and activate unified tabs through the group model
-- the visible workspace renderer is still the legacy single-surface path
-
-What Is Not Hooked Up Yet:
-- `Terminal.tsx` does not render split groups
-- no split-group UI components are mounted
-- no PTY lifecycle changes land here
-- no worktree activation fallback changes land here
-
-Non-goals:
-- no split-group UI rollout
-- no terminal PTY lifecycle changes
-- no worktree activation changes
diff --git a/docs/split-groups-rollout-pr2.md b/docs/split-groups-rollout-pr2.md
deleted file mode 100644
index fb295edb3be..00000000000
--- a/docs/split-groups-rollout-pr2.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Split Groups PR 2: Terminal Lifecycle Hardening
-
-This branch lands the terminal ownership and remount safety work required
-before split groups can be exposed.
-
-Scope:
-- preserve PTYs across remounts
-- fix pending-spawn dedupe paths
-- fix split-pane PTY ownership
-- keep visible-but-unfocused panes rendering correctly
-
-What Is Actually Hooked Up In This PR:
-- the existing terminal path uses the new PTY attach/detach/remount behavior
-- split panes inside a terminal tab get distinct PTY ownership
-- visible terminal panes continue rendering even when another pane or group has focus
-
-What Is Not Hooked Up Yet:
-- no split-group layout is rendered
-- `Terminal.tsx` still uses the legacy single-surface host path
-- no worktree restore/activation changes land here
-
-Non-goals:
-- no split-group UI rollout
-- no worktree activation fallback changes
diff --git a/docs/split-groups-rollout-pr3.md b/docs/split-groups-rollout-pr3.md
deleted file mode 100644
index 429f1b23348..00000000000
--- a/docs/split-groups-rollout-pr3.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Split Groups PR 3: Worktree Restore Ownership
-
-This branch moves worktree activation and restore logic onto the reconciled
-tab-group model.
-
-Scope:
-- reconcile stale unified tabs before restore
-- restore active surfaces from the group model first
-- fall back to terminal when a grouped worktree has no renderable surface
-- create a root group before initial terminal fallback attaches a new tab
-
-What Is Actually Hooked Up In This PR:
-- opening an existing worktree restores from the reconciled group/tab model
-- reopening an empty grouped worktree falls back to a terminal instead of a blank pane
-- initial terminal creation is now driven by renderable grouped content instead of one-time init guards
-
-What Is Not Hooked Up Yet:
-- no split-group layout is rendered
-- the visible workspace host is still the legacy terminal/browser/editor surface path
-- tab-group UI components still are not mounted here
-
-Non-goals:
-- no split-group UI enablement yet
diff --git a/docs/split-groups-rollout-pr4.md b/docs/split-groups-rollout-pr4.md
deleted file mode 100644
index 1a660d7f42f..00000000000
--- a/docs/split-groups-rollout-pr4.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Split Groups PR 4: Split-Group UI Scaffolding
-
-This branch adds the split-group UI pieces, but does not mount them in the
-main workspace host yet.
-
-Scope:
-- add `TabGroupPanel`, `TabGroupSplitLayout`, and `useTabGroupController`
-- add split-group actions to tab menus and tab-bar affordances
-- add the follow-up design note for the architecture
-
-What Is Actually Hooked Up In This PR:
-- the new split-group components compile and exist in the tree
-- tab-bar level split-group affordances are present in the component layer
-
-What Is Not Hooked Up Yet:
-- `Terminal.tsx` does not mount `TabGroupSplitLayout` in this branch
-- users still see the legacy single-surface renderer
-- no feature switch exists here because the code path is not wired in yet
-
-Non-goals:
-- no rollout to users
-- no main-renderer ownership change yet
diff --git a/docs/split-groups-rollout-pr5.md b/docs/split-groups-rollout-pr5.md
deleted file mode 100644
index 09ea2543f1d..00000000000
--- a/docs/split-groups-rollout-pr5.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Split Groups PR 5: Hook Group Surfaces Into Flagged Path
-
-This branch wires terminal, editor, and browser surfaces into the split-group
-ownership path inside `Terminal.tsx`, but holds that path behind a temporary
-local gate.
-
-Scope:
-- remove duplicate legacy ownership under the flagged path
-- route group-local surface creation and restore through the new model
-- preserve existing default behavior while the flag stays off
-
-What Is Actually Hooked Up In This PR:
-- `Terminal.tsx` now contains the real split-group surface path
-- the new path mounts `TabGroupSplitLayout` and avoids keeping duplicate legacy surfaces mounted underneath
-- the old legacy surface path is still present as the active runtime path in this branch
-
-What Is Not Hooked Up Yet:
-- the split-group path is still disabled by the temporary local rollout gate in `Terminal.tsx`
-- users should still get legacy behavior by default in this branch
diff --git a/docs/split-groups-rollout-pr6.md b/docs/split-groups-rollout-pr6.md
deleted file mode 100644
index 4abd45f787a..00000000000
--- a/docs/split-groups-rollout-pr6.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Split Groups PR 6: Enable Split Groups
-
-This branch turns split groups on after the earlier model, lifecycle, restore,
-and renderer-ownership branches are in place.
-
-Scope:
-- remove the temporary rollout gate from `Terminal.tsx`
-- make the split-group ownership path the active renderer path
-- keep only the small bootstrap fallback for cases where no layout exists yet
-
-What Is Actually Hooked Up In This PR:
-- split groups are live
-- `Terminal.tsx` always resolves through the split-group path when layout/group state exists
-- the temporary gate introduced in the dark-launch PR is removed instead of left behind as dead config
diff --git a/docs/ssh-folder-import-path-entry.md b/docs/ssh-folder-import-path-entry.md
deleted file mode 100644
index e22a1ef48d0..00000000000
--- a/docs/ssh-folder-import-path-entry.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# SSH Folder Picker — Path-Aware Filter
-
-## Problem
-
-On the "Browse remote filesystem" screen, the filter input only searches entries in the current directory. Users who know where they want to go, for example `Documents/orca-internal`, still have to click through each level manually. Typing a path with `/` currently produces "No matches" because the input treats it as a literal filter string.
-
-## Goal
-
-Let the user type a remote folder path like `Documents/orca-internal`, `~/Documents`, `/var/log`, or `../sibling` and navigate there from the existing filter input. The feature should preserve filter-only behavior for users who type ordinary names, avoid request storms over flaky SSH links, and fit the current `RemoteFileBrowser` model where `Select folder` returns the committed current directory.
-
-## Current Implementation Constraints
-
-The renderer entry point is `src/renderer/src/components/sidebar/RemoteFileBrowser.tsx`. Directory loading goes through `window.api.ssh.browseDir`, backed by `src/main/ipc/ssh-browse.ts`.
-
-The browse IPC currently accepts a `dirPath` string and returns `{ resolvedPath, entries }`, where each entry only has `{ name, isDirectory }`. It uses a remote shell command, `cd <path> && pwd && ls -1ap`, not SFTP `readdir`/`stat`. The design below must therefore be implementable using repeated `browseDir` calls. Anything that requires symlink metadata, file type metadata beyond "directory or not", or a cancellable SSH command needs an explicit IPC contract change.
-
-## Design
-
-### Mode Switch
-
-The input has two modes:
-
-- **Filter mode**: ordinary text filters entries in the current directory.
-- **Path mode**: path-like text resolves directory segments and uses the final partial segment as the filter in the resolved parent.
-
-Enter path mode when the input:
-
-- contains `/`
-- starts with `~/`, `./`, or `../`
-- equals `~`, `.`, or `..`
-
-The explicit `..` cases are required because "presence of `/`" alone would make bare `..` behave like a filter instead of parent navigation.
-
-### Input Parsing
-
-| Input | Meaning |
-|---|---|
-| `docs` | Filter current directory |
-| `Documents/orca-internal` | Resolve `Documents`, then filter by `orca-internal` |
-| `Documents/` | Resolve and show `Documents` with no filter |
-| `/var/log` | Resolve from remote root |
-| `~/Documents` | Resolve from the SSH user's home |
-| `..` | Parent of current directory |
-| `../sibling` | Parent of current directory, then filter by `sibling` |
-
-Parsing should preserve the raw input. Do not normalize away a trailing slash, because `Documents` and `Documents/` mean different things: the first stays in filter mode until Enter, while the second enters path mode and previews `Documents` with an empty filter. Typing a trailing slash does not by itself commit navigation; Enter, a row click, or a breadcrumb click are the only navigation commit actions.
-
-### Base Path
-
-Resolution starts from:
-
-- `/` for absolute inputs beginning with `/`
-- the resolved home directory for inputs beginning with `~`
-- the current `resolvedPath` for relative inputs
-
-`browseDir('~')` already resolves the remote user's home and returns the absolute `resolvedPath`. Cache that result, but do not hardcode a home path in the renderer. Treat `~` as a base marker, not as a directory name to match under the current directory.
-
-### Resolution Algorithm
-
-For a path-mode input:
-
-1. Split the input into a base, committed path segments, and a trailing filter segment. A segment is committed when it appears before the final separator or when the input is exactly `~`, `.`, or `..`. Ignore the empty segment created by one leading `/` for absolute paths and by one trailing `/`; other empty segments from repeated separators should produce an inline invalid-path error instead of silently rewriting the user input.
-2. Resolve committed segments one at a time from the base path:
-   - `.` keeps the current base.
-   - `..` moves to the parent path. If already at `/`, stay at `/`.
-   - exact directory match descends.
-   - exact non-directory match stops resolution and shows an inline error.
-   - unique prefix match among directories descends.
-   - ambiguous prefix stops resolution and shows an inline error.
-   - no directory match stops resolution and shows an inline error.
-3. Once committed segments resolve, display that directory's cached or fetched listing.
-4. Apply the trailing segment as the local filter in that resolved directory.
-5. Keep the raw input intact on errors. Do not clear user text unless navigation is committed by Enter, a row click, or a breadcrumb click.
-
-Path-mode typing must not call the existing `navigate(path)` wrapper directly. It should update separate preview state, for example `{ previewResolvedPath, previewEntries, previewFilter, previewError, previewLoading }`, while leaving the committed `resolvedPath` untouched. Otherwise typing `Documents/` would change the `Select folder` target before the user commits the path. All committed navigation still goes through `navigate(path)` so the committed current directory, breadcrumb, loading state, and `Select folder` target remain consistent.
-
-The list can render the preview listing while path mode is active, but the footer and `Select folder` target should make the committed path clear. A simple implementation is:
-
-- `Select folder` keeps today's behavior and selects the committed `resolvedPath` when the input is empty or in filter mode.
-- `Select folder` is disabled while a non-empty path-mode preview is visible. This prevents silently selecting the old committed directory while the list is showing a different preview directory.
-- A row click in a preview listing commits navigation relative to `previewResolvedPath`, not the old committed `resolvedPath`.
-
-### Enter Key
-
-In filter mode, keep today's behavior:
-
-- one matching folder navigates into it
-- only file matches show the file hint
-- ambiguous folder matches do nothing
-
-In path mode:
-
-- fully resolved directory, including a trailing `/`, navigates there and clears the input
-- resolved parent plus one matching child folder navigates into that child and clears the input
-- resolved parent plus one exact non-directory match shows the file hint or an inline "not a directory" error and does not clear the input
-- ambiguous or invalid path keeps the input and shows the inline error
-
-### Backspace Out Of Empty Input
-
-Optional. If implemented, Backspace on an empty input navigates to the parent directory, equivalent to the breadcrumb up button. It should not fire when the caret is inside non-empty text.
-
-### Paste
-
-Pasting a path resolves through the same parser as typing. Treat a paste as one logical operation: start resolving immediately, show loading state, and drop stale results if the user edits before it completes.
-
-## Debouncing And Request Control
-
-### Filter Mode
-
-Filtering is local against the current `entries` array. Do not call `browseDir` for filter-only edits. A 60-100ms render debounce is acceptable for large directories, but it is not required for correctness. If directories can contain thousands of entries, list virtualization is the larger performance fix.
-
-### Path Mode
-
-Remote calls are only needed when a committed segment requires a listing that is not already cached.
-
-Rules:
-
-- Debounce typed path resolution by 250-350ms.
-- Do not debounce paste.
-- Track a monotonically increasing request id and ignore stale responses. `AbortController` alone is insufficient unless the IPC contract is changed to support cancellation.
-- Cache directory listings by `targetId + absolute resolved path` for the lifetime of the picker.
-- Reuse the already-loaded current directory listing as the first cache entry.
-- Keep committed directory state and preview directory state separate. The existing `genRef` pattern in `RemoteFileBrowser` protects committed `loadDir` calls, but path preview needs its own request id so a stale preview cannot overwrite committed navigation after the user clicks a breadcrumb or row.
-- Do not fetch for partial trailing segment changes. For `Documents/orc` to `Documents/orca`, `Documents` is already resolved, so only the local filter changes.
-- Keep the previous visible listing while resolving the next directory. Show a subtle spinner in the input instead of flashing the list to empty.
-
-Invariant: ordinary typing should cause at most one uncached `browseDir` call per newly committed path segment. Paste may issue multiple sequential `browseDir` calls, one per uncached segment, because resolving `/home/neil/project` requires proving each intermediate directory.
-
-## Errors And Empty States
-
-Path-mode errors render below the input and do not replace the file list:
-
-- unresolved segment: `Documentz isn't a directory in /home/neil`
-- ambiguous segment: `Doc matches multiple directories in /home/neil`
-- permission denied: `Permission denied: /home/neil/private`
-
-The current `ssh:browseDir` implementation needs a small correctness fix for this to work reliably. It rejects only when `stderr` is present and `stdout` is empty, but `cd <path> && pwd && ls -1ap` can print `pwd` to stdout and then fail `ls` with permission denied. In that case the handler currently looks like a successful empty directory. The handler should reject on non-zero exit status, or use a command shape that emits a machine-readable status for `ls`, before this PR claims permission-denied handling.
-
-Empty-state copy should distinguish filter emptiness from directory emptiness:
-
-- current directory has no entries: `Empty directory`
-- path mode resolved to an empty directory: `/home/neil/Documents is empty`
-- filter hides every entry: `No matches for 'orca'`
-
-## Edge Cases
-
-- **Symlinks to directories**: the current IPC cannot identify or follow them reliably while also exposing symlink metadata. Do not promise symlink-specific UI in this PR unless `ssh:browseDir` is changed to return richer entry metadata.
-- **Case sensitivity**: the remote listing is authoritative. Exact (case-sensitive) match wins first so users with both `Documents` and `documents` get what they typed. When no case-sensitive match exists, fall back to a case-insensitive exact match, then a case-insensitive unique prefix match. Without this fallback, typing `documents/` errors while `documents` (no slash) finds `Documents` via the filter — the two modes must not disagree.
-- **Trailing slash**: `foo/` commits `foo` as a path segment for preview resolution and shows that directory with an empty filter. It does not commit picker navigation until Enter or a row click.
-- **Repeated separators**: reject `foo//bar` as invalid in path mode. Silently collapsing it would make the visible input disagree with the path being resolved.
-- **Whitespace**: filter mode can continue trimming for search, but path mode must preserve spaces inside segments and should not trim the full input before parsing. Remote paths can legitimately begin or end with spaces.
-- **Remote Windows paths**: the current browse command and this design are POSIX-path oriented. Do not add partial `C:\...` support in the renderer without first making `ssh:browseDir` shell/path handling Windows-aware.
-- **Names containing `/`**: impossible to represent as path segments. Treat `/` as a separator.
-
-## Tests
-
-Add focused unit tests around a pure parser/resolver helper, then keep `RemoteFileBrowser` tests thin:
-
-- no slash stays in filter mode
-- `..` enters path mode and resolves to parent
-- `../sibling` resolves parent and filters by `sibling`
-- `Documents/orca` resolves `Documents` and filters by `orca`
-- `Documents/` previews `Documents` with an empty filter, and Enter navigates into it
-- `/var/log` resolves from root
-- `~/Documents` resolves from remote home
-- `~` resolves and commits the remote home on Enter
-- `./child` resolves from the committed current directory
-- exact file match in a committed segment reports "not a directory" instead of descending by prefix
-- repeated separators report an invalid-path error
-- path-mode parsing preserves spaces in segments
-- path preview does not change `resolvedPath` or the `Select folder` target before commit
-- `Select folder` is disabled while a non-empty path preview is visible
-- unique prefix descends
-- ambiguous prefix reports an error and does not navigate
-- missing segment reports an error and does not clear input
-- permission denied from `ls` rejects instead of rendering an empty directory
-- stale async resolution result is ignored after input changes
-- stale async preview result is ignored after committed navigation
-- cached directories are not fetched again
-- partial trailing filter edits do not call `browseDir`
-- paste resolves immediately and sequentially
-- Enter in path mode clears input only after successful navigation
-- existing filter-mode Enter behavior is unchanged
-
-## Files To Change
-
-- `src/renderer/src/components/sidebar/remote-file-browser-helpers.ts`: add parser and pure resolution decision helpers.
-- `src/renderer/src/components/sidebar/remote-file-browser-helpers.test.ts`: expand coverage for path mode.
-- `src/renderer/src/components/sidebar/RemoteFileBrowser.tsx`: wire path mode, cache, request ids, inline errors, loading affordance, and Enter behavior.
-- `src/main/ipc/ssh-browse.ts`: fix error reporting so a failed `ls` after a successful `pwd` rejects instead of returning an empty listing. No metadata or cancellation contract change is required for the base path-entry feature.
-
-## Non-Goals
-
-- New UI controls such as a "go to path" button.
-- Rich symlink display.
-- Remote Windows path support beyond what the current SSH browse command already handles.
-- Changing the picker selection model. `Select folder` continues to return the current resolved directory.
diff --git a/docs/ssh-split-pane-inherit-cwd.md b/docs/ssh-split-pane-inherit-cwd.md
deleted file mode 100644
index 926962a65b0..00000000000
--- a/docs/ssh-split-pane-inherit-cwd.md
+++ /dev/null
@@ -1,176 +0,0 @@
-# Split-Pane CWD Inheritance (Cmd+D / Cmd+Shift+D)
-
-## Problem
-
-When the user presses **Cmd+D** or **Cmd+Shift+D** to split a terminal pane, the new pane spawns at the worktree root instead of the source pane's current working directory. Most visible on **SSH** workspaces, but true locally as well — local only appears to "work" when the user hasn't `cd`'d away from the worktree root.
-
-Reference point: Ghostty, iTerm2, kitty, Warp, and WezTerm all inherit the source pane's live CWD when splitting.
-
-## Current behavior (code-level trace)
-
-1. `src/renderer/src/components/terminal-pane/keyboard-handlers.ts:283` dispatches on `action.type === 'splitActivePane'`; the `manager.splitPane(pane.id, direction)` call is at `:296`.
-2. `src/renderer/src/lib/pane-manager/pane-manager.ts:93 splitPane()` creates the new pane and fires `onPaneCreated(newPane)`.
-3. `src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts:349 onPaneCreated` → `connectPanePty(pane, manager, {...ptyDeps})`.
-4. `src/renderer/src/components/terminal-pane/pty-connection.ts:272` builds the transport with `cwd: deps.cwd`.
-5. `deps.cwd` is set once per tab at mount from the `TerminalPane` prop, always `worktree.path`.
-
-There is **no plumbing** anywhere in the renderer that (a) tracks the live CWD of a pane or (b) threads a per-split CWD override into `splitPane`.
-
-The renderer does not currently register any OSC-7 handler. Only the headless daemon emulator (`src/main/daemon/headless-emulator.ts`) parses OSC-7 — that path only feeds daemon snapshot metadata, never the renderer's pane state.
-
-## Prior art: Superset
-
-Superset (sibling project at `../../superset`) already implements renderer-side OSC-7 tracking:
-
-- `parseCwd.ts` — regex `ESC]7;file://[^/]*(/...)BEL|ST`, URI-decodes the path, returns the most recent match in a data chunk.
-- `useTerminalCwd.ts` — per-pane hook: seeds from `initialCwd`/`workspaceCwd`, calls `parseCwd` on every xterm data event, stores `{terminalCwd, cwdConfirmed}` with a 150ms debounce.
-
-Superset's split action accepts `options.initialCwd` but its Cmd+D wiring passes a **preset** CWD, not the source pane's tracked `terminalCwd`. We will close that loop.
-
-## Design
-
-### Overview
-
-Track each pane's live CWD in the renderer via OSC-7, fall back to a one-shot `pty.getCwd` query, and pass the resolved value as `cwd` when spawning the new split PTY.
-
-### 1. Track per-pane CWD via OSC-7
-
-Add an OSC-7 handler alongside the existing OSC-52 handler in `use-terminal-pane-lifecycle.ts` `onPaneCreated` (near line 369):
-
-```ts
-const osc7Disposable = pane.terminal.parser.registerOscHandler(7, (data) => {
-  const cwd = parseOsc7(data)
-  if (cwd) {
-    paneCwdRef.current.set(pane.id, cwd)
-  }
-  // Return true so xterm marks the sequence handled and does not fall
-  // through to any builtin behavior. Note: xterm's `registerOscHandler`
-  // contract is "first handler that returns true wins"; if a future
-  // consumer (e.g. a shared daemon emulator path) also registers on
-  // code 7, registration order decides who sees each sequence.
-  return true
-})
-```
-
-- New ref on `TerminalPane`: `paneCwdRef = useRef<Map<number, string>>(new Map())`.
-- Disposable tracked in an `osc7DisposablesRef` map parallel to `osc52DisposablesRef`, torn down in `onPaneClosed` (see `use-terminal-pane-lifecycle.ts:481-484` for the OSC-52 pattern). `onPaneClosed` must also `paneCwdRef.current.delete(paneId)` so the map doesn't accumulate dead entries across splits/closes.
-- **Why `registerOscHandler(7)` rather than scanning raw data:** xterm's OSC parser handles BEL/ST termination, sequence fragmentation across chunks, and nesting. A regex on raw data (as Superset does) misses sequences split across PTY read boundaries.
-- **Handler install must stay before PTY attach.** The current `onPaneCreated` body (`use-terminal-pane-lifecycle.ts:349-460`) installs OSC parser handlers synchronously *before* `connectPanePty`. That ordering is load-bearing: it guarantees the first byte of the PTY stream — which in the cold-restore path is replayed scrollback containing OSC-7 — reaches our handler. Add a `// Why:` comment so a future refactor does not move the install after attach.
-- **Replay + stale OSC-7.** Replayed scrollback can contain OSC-7 from an earlier `cd` that no longer reflects the live shell cwd. `paneCwdRef` does not distinguish replayed vs. live entries. Store `{cwd, confirmed: boolean}` and mark `confirmed = false` when `isPaneReplaying(...)` is true at handler fire time, `confirmed = true` otherwise. `resolveSplitCwd` prefers a `confirmed` entry and otherwise falls through to `pty.getCwd`, which reflects live shell state via `/proc` or `lsof`. **Why the flag is reliable during replay:** `replayIntoTerminal` (`replay-guard.ts:37-55`) increments the counter *before* `pane.terminal.write(data, cb)` and decrements it inside xterm's write-completion callback. xterm fires parser handlers synchronously as it consumes the buffer, so every OSC-7 parsed out of the replayed chunk sees a non-zero counter. Do **not** change `replay-guard.ts` to a pre-`write` decrement — the whole design depends on the decrement being post-parse.
-
-No debouncing needed — `Map.set` is cheap and the value is read only on demand at split time.
-
-### 2. Resolve CWD at split time
-
-Introduce a helper `resolveSplitCwd(sourcePaneId, sourcePtyId, fallbackCwd): Promise<string>`. Owned by `use-terminal-pane-lifecycle.ts` (co-located with `paneCwdRef`) and passed down to keyboard and context-menu handlers as a dep, symmetric with the existing `paneTransportsRef` wiring.
-
-1. If `paneCwdRef.current.get(sourcePaneId)` has `confirmed === true`, return its `cwd` **synchronously** (no await). OSC-7 from a live shell is authoritative and instant.
-2. Otherwise `await window.api.pty.getCwd(sourcePtyId)` with a ~200ms soft timeout enforced renderer-side via `Promise.race` — keeps the "fall through to fallback" semantics in one place rather than threading timeouts into the provider. Use the result if non-empty.
-3. Otherwise, if `paneCwdRef.current.get(sourcePaneId)` has `confirmed === false` (replayed OSC-7 only), return its `cwd` as a last-ditch guess before falling back.
-4. Otherwise return `fallbackCwd` (the existing worktree root).
-
-**Sync vs async in the keydown handler.** The current Cmd+D handler at `keyboard-handlers.ts:283` is synchronous and calls `e.preventDefault()` / `e.stopImmediatePropagation()` before `splitPane`. The new flow preserves sync ordering:
-
-- Compute `preventDefault` + pane snapshot synchronously.
-- Read `paneCwdRef` synchronously. If hit → call `splitPane` immediately (no `await`).
-- If miss → fire-and-forget an `async` IIFE that awaits `pty.getCwd` then calls `splitPane`. This is equivalent to today's async pane-creation lifecycle, which is already non-blocking.
-
-Double Cmd+D in the cache-miss window: the second keypress fires before the first fire-and-forget IIFE has called `splitPane`, so both async callbacks still see the original source pane as active, resolve the same `pty.getCwd`, and produce two splits off that source (not a chain). This differs from today's fully-sync behavior, which would have chained the second split off the just-created pane. Accepted tradeoff — the window is ~1 IPC round-trip (≤200 ms) and "both splits inherit the same cwd" is not wrong, just not chained. Cache-hit (common case: an active shell with OSC-7 already seen) is still sync and preserves chaining.
-
-### 3. Thread CWD through splitPane
-
-`PaneManager.splitPane(paneId, direction, opts?)` currently accepts `opts: { ratio?: number }` (`pane-manager.ts:93-97`). Extend to `{ ratio?: number; cwd?: string }`.
-
-Plumb the hint to `onPaneCreated` by widening its signature to `(pane, spawnHints?: { cwd?: string })`. The hint is forwarded synchronously inside `splitPane` and has no reason to outlive that call. The existing `pendingSplitScrollState` field on `ManagedPaneInternal` exists only because rAFs read it *later*; that is not the case here.
-
-**Typed API break — all call sites of `onPaneCreated` must update:**
-
-- `PaneManagerOptions.onPaneCreated` type declaration in `pane-manager.ts`.
-- The `createPane` invocation at `pane-manager.ts:89` passes `undefined` for `spawnHints` (new panes aren't splits).
-- The `splitPane` invocation at `pane-manager.ts:133` forwards `opts?.cwd` as `{ cwd: opts.cwd }` when set.
-
-In `use-terminal-pane-lifecycle.ts`:
-
-```ts
-onPaneCreated: (pane, spawnHints) => {
-  // ...existing handler install...
-  const panePtyBinding = connectPanePty(pane, manager, {
-    ...ptyDeps,
-    ...(spawnHints?.cwd ? { cwd: spawnHints.cwd } : {}),
-    restoredLeafId
-  })
-}
-```
-
-Spread order matters: `spawnHints.cwd` overrides the tab-level `ptyDeps.cwd`.
-
-**Callers of `splitPane` — which inherit, which don't.**
-
-| Call site | File:line | Passes `cwd`? | Why |
-|---|---|---|---|
-| Cmd+D / Cmd+Shift+D | `keyboard-handlers.ts:296` | **yes** | primary feature |
-| Context menu: Split Right / Split Down | `use-terminal-pane-context-menu.ts:114,121` | **yes** | same user intent as Cmd+D |
-
-Both Cmd+D and context-menu call sites receive a new dep `resolveSplitCwd: (paneId, ptyId, fallbackCwd) => Promise<string>` and replace `manager.splitPane(pane.id, dir)` with roughly:
-
-```ts
-const ptyId = paneTransportsRef.current.get(pane.id)?.getPtyId() ?? null
-const cached = paneCwdRef.current.get(pane.id)
-if (cached?.confirmed) {
-  manager.splitPane(pane.id, dir, { cwd: cached.cwd })
-  return
-}
-void (async () => {
-  const cwd = await resolveSplitCwd(pane.id, ptyId, fallbackCwd)
-  managerRef.current?.splitPane(pane.id, dir, { cwd })
-})()
-```
-
-The keydown handler still calls `e.preventDefault()` / `e.stopImmediatePropagation()` synchronously before dispatching the async resolution — matches existing async pane-creation lifecycle.
-| Worktree setup split | `use-terminal-pane-lifecycle.ts:693` | no | bootstrap command runs at worktree root by contract |
-| Issue-command split | `use-terminal-pane-lifecycle.ts:719` | no | per-repo automation; runs at worktree root by contract |
-| CLI-triggered split (`onCliSplitPane`) | `use-terminal-pane-lifecycle.ts:754,757` | no | CLI protocol today carries only `paneRuntimeId` + `direction`; no cwd field. Preserve today's behavior until the CLI protocol adds one. |
-| Layout restore | `layout-serialization.ts:299` | no | restored panes re-emit their own OSC-7 on first prompt |
-
-The setup/issue/CLI sites go through `splitPaneWithOneShotStartup`, which is a wrapper receiving a `() => manager.splitPane(...)` thunk. Widening the `splitPane` opts is backward-compatible; the wrapper is unaffected because the new `spawnHints` is a parameter of the `onPaneCreated` *callback*, not of `splitPane` itself.
-
-`pendingSpawnByPaneKey` (`pty-connection.ts:21`) keys by pane key; each new split gets a fresh pane id, so no collision between the inherited-cwd path and existing dedup.
-
-### 4. Preload / main bridge for `pty.getCwd`
-
-`SshPtyProvider.getCwd` already exists (`ssh-pty-provider.ts:132`) and delegates to the relay which calls `resolveProcessCwd(pid, initialCwd)` via `/proc/<pid>/cwd` or `lsof`. Changes needed:
-
-- **`LocalPtyProvider.getCwd` (`src/main/providers/local-pty-provider.ts:388`) currently `throw`s when the id is unknown and returns `''` otherwise.** Change: return `''` on unknown id (do not throw), and on a known id call `resolveProcessCwd(proc.pid, '')` where `proc = ptyProcesses.get(id)`. Pass `''` as the fallback — **not** the pane's initial cwd — because the renderer uses empty-string to mean "no result, try the next fallback layer"; returning the initial cwd would make the renderer think it had an answer and skip its own fallback chain. Do **not** throw on unknown id: the caller treats that case as non-exceptional.
-- **Code sharing for `resolveProcessCwd`.** The helper currently lives in `src/relay/pty-shell-utils.ts` and is bundled into the relay binary. The Electron main process and the relay have separate build graphs; having main import from `src/relay/` (or vice-versa) is not a pattern this repo uses. Rather than force a `src/shared/` split (and touch the relay build), keep the relay's copy in place and add a tiny duplicate in `src/main/providers/process-cwd.ts` for `LocalPtyProvider`. The function is ~30 lines and has no shared state; the cost of duplication is lower than the cost of reshaping two bundle graphs.
-- **IPC handler:** add `ipcMain.handle('pty:getCwd', (_e, {id}) => getProviderForPty(id).getCwd(id))` in `src/main/ipc/pty.ts`, and add `ipcMain.removeHandler('pty:getCwd')` to the removeHandler block at `pty.ts:325-331` (next to the existing `pty:hasChildProcesses` / `pty:getForegroundProcess` entries).
-- **Preload:** add `pty.getCwd(id: string): Promise<string>` in `src/preload/index.ts` alongside `hasChildProcesses`/`getForegroundProcess`, and mirror in `src/preload/api-types.ts`. Returns `''` when unknown.
-
-### 5. Edge cases
-
-- **Agent TUIs (Claude Code, Codex, cursor-agent).** No OSC-7 because no shell prompt. `paneCwdRef` stays empty; `pty.getCwd` via `/proc/<pid>/cwd` still resolves against the running agent process.
-- **Just-split panes (no OSC-7 yet).** A fresh pane before its first prompt has no entry. `pty.getCwd` fallback handles it. Double-Cmd+D inherits from the still-fresh shell's spawn CWD — correct.
-- **SSH reconnect / cold-restore.** OSC-7 entries are keyed by ephemeral `paneId`. Replayed OSC-7 in the scrollback re-feeds the handler via `terminal.write` (`replay-guard.ts:47`) and repopulates the map with `confirmed: false`. The first live OSC-7 after the first prompt upgrades it to `confirmed: true`. If the user hits Cmd+D before the first live prompt, `resolveSplitCwd` takes the `pty.getCwd` path (which queries `/proc/<pid>/cwd` on the live shell) and only falls back to the replayed entry if IPC yields nothing.
-- **Non-emitting shells.** Minimal `sh` without OSC-7 → `pty.getCwd` fallback carries it. Explicit reason to keep the two-layer strategy.
-- **Windows.** `/proc` is absent and `lsof` isn't native. On Windows, `LocalPtyProvider.getCwd` must return `''` (fall through to worktree root) and must **not** throw — after the §4 change, the existing `throw`-on-unknown-id is replaced with `''`, and the Windows branch simply returns `''` unconditionally. Not a regression over today's behavior. OSC-7 from PowerShell/pwsh still works because parsing is renderer-side and platform-agnostic.
-- **Expanded-pane mode.** `keyboard-handlers.ts:286` exits expanded mode before splitting. CWD lookup runs on the currently-active pane before that exit, which is the correct source.
-
-### 6. Tests
-
-- Unit: `parseOsc7` — BEL vs ST termination, percent-decoded spaces, empty host, Windows drive-letter URIs (`file:///C:/Users/...`). On Windows, `parseOsc7` must return a string that `node-pty` accepts as `cwd` on `spawn` (backslash- or forward-slash-separated, with drive letter, no leading `/`). Normalize inside `parseOsc7` via `path.win32.normalize` when `process.platform === 'win32'` and assert the test output equals what `spawn`'s `cwd` option tolerates — don't leave the choice implicit.
-- Unit: `resolveSplitCwd` priority — OSC-7 cache hit skips IPC; cache miss queries IPC; empty IPC result falls through to `deps.cwd`; IPC timeout falls through to `deps.cwd`.
-- Unit: `LocalPtyProvider.getCwd` returns `''` (not throws) for unknown ids.
-- Integration (`tests/e2e/terminal-panes.spec.ts`): `cd /tmp && emit OSC-7; Cmd+D → new pane pwd === /tmp`.
-- No SSH e2e suite exists in `tests/e2e/` today; skip.
-
-### 7. Rollout / compatibility
-
-- No migration or settings surface.
-- Safe default: if OSC-7 and `pty.getCwd` both fail, fall back to worktree root. Users never end up worse off.
-- Ships without a flag.
-
-## Out of scope
-
-- Persisting per-pane CWD across app restarts. Each session starts fresh; OSC-7 re-arrives on first prompt.
-- **New-tab-from-pane inheritance (Cmd+T).** Deliberately deferred — users will ask why Cmd+D inherits and Cmd+T does not, but new-tab also implies worktree choice and startup payload semantics that are not in scope here. Reuse `paneCwdRef` + `resolveSplitCwd` when the new-tab flow is revisited.
-- Using tracked CWD for status-bar display or any other non-split consumer. Separate features that can reuse `paneCwdRef` later.
-- CWD for context-menu entries that open external tools (file manager, editor). Those already have their own resolution paths.
diff --git a/docs/superpowers/plans/2026-04-10-terminal-search-shortcuts.md b/docs/superpowers/plans/2026-04-10-terminal-search-shortcuts.md
deleted file mode 100644
index d5ad7c80e58..00000000000
--- a/docs/superpowers/plans/2026-04-10-terminal-search-shortcuts.md
+++ /dev/null
@@ -1,408 +0,0 @@
-# Terminal Search Next/Previous Shortcuts — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add `Cmd+G` / `Cmd+Shift+G` shortcuts to navigate terminal search matches when the search bar is open.
-
-**Architecture:** A `searchStateRef` bridges the search query/options from `TerminalSearch` (which owns the state) to `keyboard-handlers.ts` (which handles the shortcut). The `Cmd+G` handler is placed before the `isEditableTarget` guard so it works even when focus is in the search input.
-
-**Tech Stack:** React, TypeScript, xterm.js (`@xterm/addon-search`), Vitest
-
----
-
-## File Map
-
-| File | Action | Responsibility |
-|------|--------|---------------|
-| `src/renderer/src/components/terminal-pane/keyboard-handlers.ts` | Modify | Add `Cmd+G` / `Cmd+Shift+G` handler |
-| `src/renderer/src/components/TerminalSearch.tsx` | Modify | Accept and sync `searchStateRef` |
-| `src/renderer/src/components/terminal-pane/TerminalPane.tsx` | Modify | Create and wire `searchStateRef` |
-| `src/renderer/src/components/terminal-pane/keyboard-handlers.test.ts` | Create | Test the new shortcut handler logic |
-
----
-
-### Task 1: Extract and test the `Cmd+G` / `Cmd+Shift+G` key-matching logic
-
-The keyboard handler uses a capture-phase `window` listener with DOM dependencies (`e.target`, `pane.terminal.focus()`). Rather than mocking all of that, we test the **decision logic** in isolation: given a key event shape + search state, should the handler fire findNext, findPrevious, or do nothing?
-
-**Files:**
-- Create: `src/renderer/src/components/terminal-pane/keyboard-handlers.test.ts`
-
-- [ ] **Step 1: Write failing tests for the search-navigate decision logic**
-
-We'll test a pure helper function `matchSearchNavigate` that we'll extract in Task 2. For now, write the tests against the expected interface.
-
-```ts
-// src/renderer/src/components/terminal-pane/keyboard-handlers.test.ts
-import { describe, it, expect } from 'vitest'
-import { matchSearchNavigate } from './keyboard-handlers'
-
-function makeKeyEvent(overrides: Partial<{
-  key: string
-  metaKey: boolean
-  ctrlKey: boolean
-  shiftKey: boolean
-  altKey: boolean
-}>): Pick<KeyboardEvent, 'key' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey'> {
-  return {
-    key: 'g',
-    metaKey: false,
-    ctrlKey: false,
-    shiftKey: false,
-    altKey: false,
-    ...overrides
-  }
-}
-
-describe('matchSearchNavigate', () => {
-  const isMac = true
-  const searchState = { query: 'hello', caseSensitive: false, regex: false }
-
-  it('returns "next" for Cmd+G on macOS', () => {
-    const e = makeKeyEvent({ metaKey: true })
-    expect(matchSearchNavigate(e, isMac, true, searchState)).toBe('next')
-  })
-
-  it('returns "previous" for Cmd+Shift+G on macOS', () => {
-    const e = makeKeyEvent({ metaKey: true, shiftKey: true })
-    expect(matchSearchNavigate(e, isMac, true, searchState)).toBe('previous')
-  })
-
-  it('returns null when search is closed', () => {
-    const e = makeKeyEvent({ metaKey: true })
-    expect(matchSearchNavigate(e, isMac, false, searchState)).toBeNull()
-  })
-
-  it('returns null when query is empty', () => {
-    const e = makeKeyEvent({ metaKey: true })
-    expect(matchSearchNavigate(e, isMac, true, { query: '', caseSensitive: false, regex: false })).toBeNull()
-  })
-
-  it('returns null for wrong key', () => {
-    const e = makeKeyEvent({ metaKey: true, key: 'f' })
-    expect(matchSearchNavigate(e, isMac, true, searchState)).toBeNull()
-  })
-
-  it('returns null when alt is pressed', () => {
-    const e = makeKeyEvent({ metaKey: true, altKey: true })
-    expect(matchSearchNavigate(e, isMac, true, searchState)).toBeNull()
-  })
-
-  it('returns "next" for Ctrl+G on Linux/Windows', () => {
-    const e = makeKeyEvent({ ctrlKey: true })
-    expect(matchSearchNavigate(e, false, true, searchState)).toBe('next')
-  })
-
-  it('returns null for Ctrl+G on macOS (wrong modifier)', () => {
-    const e = makeKeyEvent({ ctrlKey: true })
-    expect(matchSearchNavigate(e, true, true, searchState)).toBeNull()
-  })
-})
-```
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `pnpm test -- src/renderer/src/components/terminal-pane/keyboard-handlers.test.ts`
-Expected: FAIL — `matchSearchNavigate` is not exported from `keyboard-handlers`
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/renderer/src/components/terminal-pane/keyboard-handlers.test.ts
-git commit -m "test: add failing tests for search-navigate key matching"
-```
-
----
-
-### Task 2: Implement `matchSearchNavigate` and wire it into the keyboard handler
-
-**Files:**
-- Modify: `src/renderer/src/components/terminal-pane/keyboard-handlers.ts`
-
-- [ ] **Step 1: Add the `SearchState` type and `matchSearchNavigate` function**
-
-Add this above the `useTerminalKeyboardShortcuts` function:
-
-```ts
-export type SearchState = {
-  query: string
-  caseSensitive: boolean
-  regex: boolean
-}
-
-/**
- * Pure decision function for Cmd+G / Cmd+Shift+G search navigation.
- * Returns 'next', 'previous', or null (no match).
- * Extracted so the key-matching logic is testable without DOM dependencies.
- */
-export function matchSearchNavigate(
-  e: Pick<KeyboardEvent, 'key' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey'>,
-  isMac: boolean,
-  searchOpen: boolean,
-  searchState: SearchState
-): 'next' | 'previous' | null {
-  if (e.altKey) return null
-  const mod = isMac ? e.metaKey && !e.ctrlKey : e.ctrlKey && !e.metaKey
-  if (!mod) return null
-  if (e.key.toLowerCase() !== 'g') return null
-  if (!searchOpen) return null
-  if (!searchState.query) return null
-  return e.shiftKey ? 'previous' : 'next'
-}
-```
-
-- [ ] **Step 2: Add `searchOpen` and `searchStateRef` to the deps type**
-
-Update the `KeyboardHandlersDeps` type — add two new fields:
-
-```ts
-type KeyboardHandlersDeps = {
-  isActive: boolean
-  managerRef: React.RefObject<PaneManager | null>
-  paneTransportsRef: React.RefObject<Map<number, PtyTransport>>
-  expandedPaneIdRef: React.RefObject<number | null>
-  setExpandedPane: (paneId: number | null) => void
-  restoreExpandedLayout: () => void
-  refreshPaneSizes: (focusActive: boolean) => void
-  persistLayoutSnapshot: () => void
-  toggleExpandPane: (paneId: number) => void
-  setSearchOpen: React.Dispatch<React.SetStateAction<boolean>>
-  onRequestClosePane: (paneId: number) => void
-  searchOpen: boolean
-  searchStateRef: React.RefObject<SearchState>
-}
-```
-
-- [ ] **Step 3: Add the `Cmd+G` handler inside `onKeyDown`, before the `isEditableTarget` guard**
-
-Insert this block in `onKeyDown` right after the `if (e.repeat) return` check (line 62) and before `if (isEditableTarget(e.target))` (line 64):
-
-```ts
-      // Cmd+G / Cmd+Shift+G navigates terminal search matches.
-      // Placed before the isEditableTarget guard so it works when focus
-      // is in the search input. Uses its own mod-key check because this
-      // runs before the shared `mod` variable is declared.
-      // preventDefault suppresses macOS/Electron's native "find next".
-      const direction = matchSearchNavigate(e, isMac, searchOpen, searchStateRef.current)
-      if (direction !== null) {
-        e.preventDefault()
-        e.stopPropagation()
-        const pane = manager.getActivePane() ?? manager.getPanes()[0]
-        if (!pane) return
-        const { query, caseSensitive, regex } = searchStateRef.current
-        if (direction === 'next') {
-          pane.searchAddon.findNext(query, { caseSensitive, regex })
-        } else {
-          pane.searchAddon.findPrevious(query, { caseSensitive, regex })
-        }
-        pane.terminal.focus()
-        return
-      }
-```
-
-Note: this block accesses `manager` which is declared further down. Move the `const manager = managerRef.current; if (!manager) return` check above the `isEditableTarget` guard as well, so the search handler can reference it. This reorder is safe — the code between the old `manager` position and `isEditableTarget` only computes `mod` and checks `altKey`, neither of which references `manager`. The minor behavioral change is that `!manager` now short-circuits before `isEditableTarget` runs, which is harmless (no manager means no terminal to handle shortcuts for). The full reordering inside `onKeyDown` becomes:
-
-```
-if (e.repeat) return
-const manager = managerRef.current    // ← moved up from line 72
-if (!manager) return                  // ← moved up from line 73
-// Cmd+G / Cmd+Shift+G handler (new)
-if (isEditableTarget(e.target)) return
-const mod = ...
-```
-
-- [ ] **Step 4: Add `searchOpen` and `searchStateRef` to the destructuring and useEffect deps array**
-
-Update the function signature destructuring to include `searchOpen` and `searchStateRef`. Add both to the `useEffect` dependency array (alongside the existing entries):
-
-```ts
-export function useTerminalKeyboardShortcuts({
-  isActive,
-  managerRef,
-  paneTransportsRef,
-  expandedPaneIdRef,
-  setExpandedPane,
-  restoreExpandedLayout,
-  refreshPaneSizes,
-  persistLayoutSnapshot,
-  toggleExpandPane,
-  setSearchOpen,
-  onRequestClosePane,
-  searchOpen,
-  searchStateRef
-}: KeyboardHandlersDeps): void {
-  useEffect(() => {
-    // ...
-  }, [
-    isActive,
-    managerRef,
-    paneTransportsRef,
-    expandedPaneIdRef,
-    setExpandedPane,
-    restoreExpandedLayout,
-    refreshPaneSizes,
-    persistLayoutSnapshot,
-    toggleExpandPane,
-    setSearchOpen,
-    onRequestClosePane,
-    searchOpen,
-    searchStateRef
-  ])
-}
-```
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-Run: `pnpm test -- src/renderer/src/components/terminal-pane/keyboard-handlers.test.ts`
-Expected: All 8 tests PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/renderer/src/components/terminal-pane/keyboard-handlers.ts src/renderer/src/components/terminal-pane/keyboard-handlers.test.ts
-git commit -m "feat: add Cmd+G / Cmd+Shift+G search navigation to keyboard handler"
-```
-
----
-
-### Task 3: Wire `searchStateRef` through `TerminalPane`, `TerminalSearch`, and sync it
-
-Tasks 3 modifies both `TerminalPane.tsx` and `TerminalSearch.tsx` together because `searchStateRef` is a required prop — modifying them separately would break TypeScript compilation between commits.
-
-**Files:**
-- Modify: `src/renderer/src/components/terminal-pane/TerminalPane.tsx`
-- Modify: `src/renderer/src/components/TerminalSearch.tsx`
-
-- [ ] **Step 1: Import `SearchState` and create the ref in `TerminalPane`**
-
-Add the import at the top of `TerminalPane.tsx` alongside the existing `keyboard-handlers` import:
-
-```ts
-import { useTerminalKeyboardShortcuts } from './keyboard-handlers'
-```
-
-becomes:
-
-```ts
-import { useTerminalKeyboardShortcuts, type SearchState } from './keyboard-handlers'
-```
-
-Then add the ref near the other refs (after `const [searchOpen, setSearchOpen] = useState(false)` on line 65):
-
-```ts
-  const searchStateRef = useRef<SearchState>({ query: '', caseSensitive: false, regex: false })
-```
-
-- [ ] **Step 2: Pass `searchOpen` and `searchStateRef` to `useTerminalKeyboardShortcuts`**
-
-Update the call (around line 263) to include the two new fields:
-
-```ts
-  useTerminalKeyboardShortcuts({
-    isActive,
-    managerRef,
-    paneTransportsRef,
-    expandedPaneIdRef,
-    setExpandedPane,
-    restoreExpandedLayout,
-    refreshPaneSizes,
-    persistLayoutSnapshot,
-    toggleExpandPane,
-    setSearchOpen,
-    onRequestClosePane: handleRequestClosePane,
-    searchOpen,
-    searchStateRef
-  })
-```
-
-- [ ] **Step 3: Pass `searchStateRef` to `TerminalSearch`**
-
-Update the `TerminalSearch` JSX (around line 567) to include the new prop:
-
-```tsx
-          <TerminalSearch
-            isOpen={searchOpen}
-            onClose={() => setSearchOpen(false)}
-            searchAddon={activePane.searchAddon ?? null}
-            searchStateRef={searchStateRef}
-          />,
-```
-
-- [ ] **Step 4: Add `searchStateRef` prop to `TerminalSearch`**
-
-In `TerminalSearch.tsx`, import the `SearchState` type from `keyboard-handlers` and use it in the props type. This keeps the type definition in one place so it can't silently diverge:
-
-```ts
-import type { SearchState } from '@/components/terminal-pane/keyboard-handlers'
-```
-
-Then update the props type and destructuring:
-
-```ts
-type TerminalSearchProps = {
-  isOpen: boolean
-  onClose: () => void
-  searchAddon: SearchAddon | null
-  searchStateRef: React.MutableRefObject<SearchState>
-}
-
-export default function TerminalSearch({
-  isOpen,
-  onClose,
-  searchAddon,
-  searchStateRef
-}: TerminalSearchProps): React.JSX.Element | null {
-```
-
-- [ ] **Step 5: Sync the ref inside the existing incremental-search `useEffect`**
-
-The existing `useEffect` (lines 47–55) already runs whenever `query`, `caseSensitive`, or `regex` change. Add the ref sync at the top, before the early return on empty query. This ensures the ref stays in sync even when the query is cleared (so it reflects the true current state):
-
-```ts
-  useEffect(() => {
-    // Keep the ref in sync so the keyboard handler (Cmd+G / Cmd+Shift+G)
-    // can read the current search state without lifting it to parent state.
-    searchStateRef.current = { query, caseSensitive, regex }
-
-    if (!query) {
-      searchAddon?.clearDecorations()
-      return
-    }
-    if (searchAddon && isOpen) {
-      searchAddon.findNext(query, { caseSensitive, regex, incremental: true })
-    }
-  }, [query, searchAddon, isOpen, caseSensitive, regex, searchStateRef])
-```
-
-Note: `searchStateRef` is added to the dependency array to satisfy the linter, though as a ref it never changes identity.
-
-- [ ] **Step 6: Run the full test suite to verify nothing is broken**
-
-Run: `pnpm test`
-Expected: All tests pass (no regressions)
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/renderer/src/components/terminal-pane/TerminalPane.tsx src/renderer/src/components/TerminalSearch.tsx
-git commit -m "feat: wire searchStateRef through TerminalPane and TerminalSearch"
-```
-
----
-
-### Task 4: TypeScript build verification
-
-**Files:** None (verification only)
-
-- [ ] **Step 1: Run the TypeScript compiler to check for type errors**
-
-Run: `pnpm run typecheck` (or the equivalent — check `package.json` scripts)
-If no `typecheck` script exists, run: `npx tsc --noEmit`
-Expected: No type errors
-
-- [ ] **Step 2: Run the full test suite one final time**
-
-Run: `pnpm test`
-Expected: All tests pass
-
-- [ ] **Step 3: Commit if any fixes were needed, otherwise skip**
diff --git a/docs/superpowers/plans/2026-04-13-mermaid-file-viewer.md b/docs/superpowers/plans/2026-04-13-mermaid-file-viewer.md
deleted file mode 100644
index 1d1f6fe9b85..00000000000
--- a/docs/superpowers/plans/2026-04-13-mermaid-file-viewer.md
+++ /dev/null
@@ -1,360 +0,0 @@
-# Mermaid File Viewer Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Open `.mmd` / `.mermaid` files and render them as live, themed diagrams with a source/diagram toggle in the editor header.
-
-**Architecture:** Orca already has a `MermaidBlock` component that renders mermaid syntax to SVG, and a `MarkdownViewToggle` that switches between source and rich modes. This plan registers `.mmd`/`.mermaid` as a new language (`'mermaid'`), adds a `MermaidViewer` component that wraps `MermaidBlock` for full-file rendering with scroll caching and centering, and wires it into the existing `EditorPanel` / `EditorContent` routing alongside the markdown path. The view mode store (`markdownViewMode`) is reused since it is already keyed by file ID.
-
-**Tech Stack:** React, Zustand (existing store), mermaid (already installed v11.14), DOMPurify (already installed), Monaco (source mode), existing `MermaidBlock` component.
-
----
-
-## File Map
-
-| Action | Path | Responsibility |
-|--------|------|---------------|
-| Modify | `src/renderer/src/lib/language-detect.ts` | Register `.mmd` and `.mermaid` extensions |
-| Create | `src/renderer/src/components/editor/MermaidViewer.tsx` | Full-file mermaid diagram viewer with scroll caching |
-| Modify | `src/renderer/src/components/editor/EditorPanel.tsx` | Add `isMermaid` flag, show view toggle for mermaid files |
-| Modify | `src/renderer/src/components/editor/EditorContent.tsx` | Add `isMermaid` prop, route to `MermaidViewer` or Monaco |
-| Modify | `src/renderer/src/assets/markdown-preview.css` | Add `.mermaid-viewer` styles |
-
----
-
-### Task 1: Register `.mmd` and `.mermaid` file extensions
-
-**Files:**
-- Modify: `src/renderer/src/lib/language-detect.ts:10-76` (add two entries to `EXT_TO_LANGUAGE`)
-
-- [ ] **Step 1: Add mermaid extensions to the language map**
-
-In `src/renderer/src/lib/language-detect.ts`, add these two entries to the `EXT_TO_LANGUAGE` object (between `.mdx` and `.css`):
-
-```typescript
-'.mmd': 'mermaid',
-'.mermaid': 'mermaid',
-```
-
-- [ ] **Step 2: Verify the change compiles**
-
-Run: `cd src/renderer && npx tsc --noEmit --pretty 2>&1 | head -20`
-Expected: No errors related to `language-detect.ts`.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/renderer/src/lib/language-detect.ts
-git commit -m "feat: register .mmd and .mermaid file extensions"
-```
-
----
-
-### Task 2: Create `MermaidViewer` component
-
-**Files:**
-- Create: `src/renderer/src/components/editor/MermaidViewer.tsx`
-
-This component renders the entire file content as a mermaid diagram. It reuses the existing `MermaidBlock` for rendering and follows the same dark-mode detection and scroll-caching patterns as `MarkdownPreview`.
-
-- [ ] **Step 1: Create the `MermaidViewer` component**
-
-Create `src/renderer/src/components/editor/MermaidViewer.tsx`:
-
-```tsx
-import React, { useLayoutEffect, useRef } from 'react'
-import { useAppStore } from '@/store'
-import { scrollTopCache, setWithLRU } from '@/lib/scroll-cache'
-import MermaidBlock from './MermaidBlock'
-
-type MermaidViewerProps = {
-  content: string
-  filePath: string
-}
-
-// Why: MermaidViewer is the full-file counterpart to MermaidBlock (which
-// renders fenced mermaid blocks inside markdown). When a user opens a .mmd
-// or .mermaid file in diagram mode, the entire file content is the diagram
-// source — no markdown wrapper, no frontmatter, just mermaid syntax.
-export default function MermaidViewer({
-  content,
-  filePath
-}: MermaidViewerProps): React.JSX.Element {
-  const rootRef = useRef<HTMLDivElement>(null)
-  const settings = useAppStore((s) => s.settings)
-  const isDark =
-    settings?.theme === 'dark' ||
-    (settings?.theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches)
-
-  // Why: Each viewing mode (source vs diagram) produces different DOM heights.
-  // Mode-scoped keys prevent restoring a source-mode scroll position in diagram
-  // mode (same reasoning as MarkdownPreview's scrollCacheKey).
-  const scrollCacheKey = `${filePath}:mermaid-diagram`
-
-  useLayoutEffect(() => {
-    const container = rootRef.current
-    if (!container) {
-      return
-    }
-
-    let throttleTimer: ReturnType<typeof setTimeout> | null = null
-
-    const onScroll = (): void => {
-      if (throttleTimer !== null) {
-        clearTimeout(throttleTimer)
-      }
-      throttleTimer = setTimeout(() => {
-        setWithLRU(scrollTopCache, scrollCacheKey, container.scrollTop)
-        throttleTimer = null
-      }, 150)
-    }
-
-    container.addEventListener('scroll', onScroll, { passive: true })
-    return () => {
-      setWithLRU(scrollTopCache, scrollCacheKey, container.scrollTop)
-      if (throttleTimer !== null) {
-        clearTimeout(throttleTimer)
-      }
-      container.removeEventListener('scroll', onScroll)
-    }
-  }, [scrollCacheKey])
-
-  useLayoutEffect(() => {
-    const container = rootRef.current
-    const targetScrollTop = scrollTopCache.get(scrollCacheKey)
-    if (!container || targetScrollTop === undefined) {
-      return
-    }
-
-    let frameId = 0
-    let attempts = 0
-
-    // Why: mermaid.render() is async, so the SVG may not exist on the first
-    // frame. Retry up to 30 frames (~500ms) to match MarkdownPreview's pattern.
-    const tryRestore = (): void => {
-      const maxScrollTop = Math.max(0, container.scrollHeight - container.clientHeight)
-      const nextScrollTop = Math.min(targetScrollTop, maxScrollTop)
-      container.scrollTop = nextScrollTop
-
-      if (Math.abs(container.scrollTop - targetScrollTop) <= 1 || maxScrollTop >= targetScrollTop) {
-        return
-      }
-
-      attempts += 1
-      if (attempts < 30) {
-        frameId = window.requestAnimationFrame(tryRestore)
-      }
-    }
-
-    tryRestore()
-    return () => window.cancelAnimationFrame(frameId)
-  }, [scrollCacheKey, content])
-
-  return (
-    <div
-      ref={rootRef}
-      className="mermaid-viewer h-full min-h-0 overflow-auto scrollbar-editor"
-    >
-      <div className="mermaid-viewer-canvas">
-        <MermaidBlock content={content.trim()} isDark={isDark} />
-      </div>
-    </div>
-  )
-}
-```
-
-- [ ] **Step 2: Verify it compiles**
-
-Run: `cd src/renderer && npx tsc --noEmit --pretty 2>&1 | head -20`
-Expected: No errors.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/renderer/src/components/editor/MermaidViewer.tsx
-git commit -m "feat: add MermaidViewer component for .mmd file rendering"
-```
-
----
-
-### Task 3: Add `.mermaid-viewer` styles
-
-**Files:**
-- Modify: `src/renderer/src/assets/markdown-preview.css` (append after existing `.mermaid-error` block, around line 242)
-
-- [ ] **Step 1: Add viewer styles**
-
-Append after the `.mermaid-error` rule block (line ~242) in `markdown-preview.css`:
-
-```css
-/* Full-file mermaid diagram viewer — used when opening .mmd/.mermaid files
-   in diagram mode. Centers the rendered SVG and adds padding so diagrams
-   don't press against viewport edges. */
-.mermaid-viewer {
-  background: var(--color-background, #fff);
-}
-.mermaid-viewer-canvas {
-  display: flex;
-  align-items: flex-start;
-  justify-content: center;
-  min-height: 100%;
-  padding: 32px 24px;
-}
-.mermaid-viewer-canvas .mermaid-block {
-  max-width: 100%;
-}
-.mermaid-viewer-canvas .mermaid-block svg {
-  max-width: 100%;
-  height: auto;
-}
-```
-
-- [ ] **Step 2: Commit**
-
-```bash
-git add src/renderer/src/assets/markdown-preview.css
-git commit -m "feat: add mermaid-viewer CSS for full-file diagram display"
-```
-
----
-
-### Task 4: Wire mermaid files into `EditorPanel` and `EditorContent`
-
-**Files:**
-- Modify: `src/renderer/src/components/editor/EditorPanel.tsx:427-519`
-- Modify: `src/renderer/src/components/editor/EditorContent.tsx:1-67,262-270`
-
-This task threads the `isMermaid` flag through the same path as `isMarkdown`, reusing the existing `markdownViewMode` store (keyed by file ID, so no collision) and `MarkdownViewToggle` (icon-only, works for both).
-
-- [ ] **Step 1: Update `EditorPanel.tsx`**
-
-**Change 1** — add `isMermaid` flag and widen the view-mode condition (around line 427):
-
-Replace:
-```typescript
-  const isMarkdown = resolvedLanguage === 'markdown'
-  const mdViewMode: MarkdownViewMode =
-    isMarkdown && activeFile.mode === 'edit'
-      ? (markdownViewMode[activeFile.id] ?? 'rich')
-      : 'source'
-```
-
-With:
-```typescript
-  const isMarkdown = resolvedLanguage === 'markdown'
-  const isMermaid = resolvedLanguage === 'mermaid'
-  // Why: mermaid files reuse the same per-file view mode store as markdown.
-  // Both default to 'rich' (rendered view) and fall back to 'source' (Monaco).
-  const hasViewModeToggle = (isMarkdown || isMermaid) && activeFile.mode === 'edit'
-  const mdViewMode: MarkdownViewMode = hasViewModeToggle
-    ? (markdownViewMode[activeFile.id] ?? 'rich')
-    : 'source'
-```
-
-**Change 2** — update the toggle condition in the header (around line 515):
-
-Replace:
-```tsx
-          {isMarkdown && activeFile.mode === 'edit' && (
-            <MarkdownViewToggle
-```
-
-With:
-```tsx
-          {hasViewModeToggle && (
-            <MarkdownViewToggle
-```
-
-**Change 3** — pass `isMermaid` to `EditorContent` (around line 531):
-
-Add `isMermaid={isMermaid}` after the `isMarkdown` prop:
-
-```tsx
-          isMarkdown={isMarkdown}
-          isMermaid={isMermaid}
-```
-
-- [ ] **Step 2: Update `EditorContent.tsx`**
-
-**Change 1** — add lazy import for `MermaidViewer` (after the `ImageDiffViewer` lazy import, around line 18):
-
-```typescript
-const MermaidViewer = lazy(() => import('./MermaidViewer'))
-```
-
-**Change 2** — add `isMermaid` to the component props type and destructuring (around line 34-67):
-
-Add `isMermaid: boolean` to the props type (after `isMarkdown: boolean`), and add `isMermaid` to the destructuring.
-
-**Change 3** — add mermaid routing in the edit-mode branch (around line 266):
-
-Replace:
-```tsx
-          {isMarkdown ? renderMarkdownContent(fc) : renderMonacoEditor(fc)}
-```
-
-With:
-```tsx
-          {isMarkdown
-            ? renderMarkdownContent(fc)
-            : isMermaid && mdViewMode === 'rich'
-              ? <MermaidViewer
-                  key={activeFile.id}
-                  content={editBuffers[activeFile.id] ?? fc.content}
-                  filePath={activeFile.filePath}
-                />
-              : renderMonacoEditor(fc)}
-```
-
-- [ ] **Step 3: Verify everything compiles**
-
-Run: `cd src/renderer && npx tsc --noEmit --pretty 2>&1 | head -20`
-Expected: No errors.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/renderer/src/components/editor/EditorPanel.tsx src/renderer/src/components/editor/EditorContent.tsx
-git commit -m "feat: wire mermaid file viewer into editor panel routing"
-```
-
----
-
-### Task 5: Manual verification
-
-- [ ] **Step 1: Create a test `.mmd` file in any worktree**
-
-Place a file like `test-diagram.mmd` in a worktree directory with content:
-
-```
-graph TD
-    A[Open .mmd file] --> B{Rendered?}
-    B -->|Yes| C[Diagram view]
-    B -->|No| D[Source view]
-    C --> E[Toggle to source]
-    D --> F[Toggle to diagram]
-```
-
-- [ ] **Step 2: Open the file in Orca and verify**
-
-Check:
-1. File opens in diagram mode by default (rendered SVG, centered)
-2. Source/diagram toggle appears in the editor header
-3. Clicking the Code icon switches to Monaco with mermaid syntax
-4. Clicking the Eye icon switches back to the rendered diagram
-5. Dark mode: diagram respects the current theme
-6. Large diagrams scroll properly
-7. Scroll position is preserved when switching tabs and back
-
-- [ ] **Step 3: Verify no regressions**
-
-Check:
-1. Opening a `.md` file still works with source/rich toggle
-2. Mermaid fenced blocks inside `.md` files still render
-3. Non-markdown, non-mermaid files open normally in Monaco
-
-- [ ] **Step 4: Clean up the test file and commit everything**
-
-```bash
-rm test-diagram.mmd
-```
diff --git a/docs/superpowers/specs/2026-04-10-terminal-search-shortcuts-design.md b/docs/superpowers/specs/2026-04-10-terminal-search-shortcuts-design.md
deleted file mode 100644
index c81bf9c0c1b..00000000000
--- a/docs/superpowers/specs/2026-04-10-terminal-search-shortcuts-design.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Terminal Search Next/Previous Shortcuts
-
-## Summary
-
-Add `Cmd+G` (find next) and `Cmd+Shift+G` (find previous) keyboard shortcuts to navigate terminal search matches. These follow macOS native conventions and only activate when the search bar is already open.
-
-## Requirements
-
-- `Cmd+G` calls `findNext` on the active pane's `SearchAddon`
-- `Cmd+Shift+G` calls `findPrevious` on the active pane's `SearchAddon`
-- Shortcuts are no-ops when the search bar is closed
-- After navigating, focus moves to the terminal (not the search input)
-- Shortcuts are not documented in ShortcutsPane (consistent with `Cmd+F`)
-
-## Architecture
-
-### Data bridge: `searchStateRef`
-
-The search query and options (`caseSensitive`, `regex`) live as local state in `TerminalSearch.tsx`. The keyboard handler in `keyboard-handlers.ts` needs read access to call `searchAddon.findNext(query, opts)`.
-
-A `MutableRefObject<{ query: string; caseSensitive: boolean; regex: boolean }>` is created in `TerminalPane` and passed to both components. `TerminalSearch` writes to it on state changes; the keyboard handler reads from it on `Cmd+G` / `Cmd+Shift+G`. This follows the existing ref-bridge pattern used throughout `TerminalPane` (e.g., `paneTitlesRef`, `isActiveRef`, `settingsRef`).
-
-### Changes by file
-
-**`TerminalPane.tsx`**
-- Create `searchStateRef = useRef({ query: '', caseSensitive: false, regex: false })`
-- Pass `searchStateRef` to `TerminalSearch` as a new prop
-- Pass `searchOpen` and `searchStateRef` to `useTerminalKeyboardShortcuts`
-
-**`TerminalSearch.tsx`**
-- Accept `searchStateRef: React.MutableRefObject<{ query: string; caseSensitive: boolean; regex: boolean }>` prop
-- Sync the ref whenever `query`, `caseSensitive`, or `regex` changes — inside the existing `useEffect` that already depends on `[query, caseSensitive, regex]`, so all three values are kept in sync together. Note: the existing effect has an early return when query is empty (`clearDecorations`), so the ref won't update on clear — this is benign because the keyboard handler already guards on non-empty query
-
-**`keyboard-handlers.ts`**
-- Add `searchOpen` (boolean) and `searchStateRef` to `KeyboardHandlersDeps`
-- Exempt `[data-terminal-search-root]` descendants from the `isEditableTarget` early return for `Cmd+G` / `Cmd+Shift+G`. Without this, pressing the shortcut while the search input has focus would be silently swallowed. The paste handler in `TerminalPane` already uses this same `data-terminal-search-root` exemption pattern.
-- Add handler for `Cmd+G` / `Cmd+Shift+G` inside `onKeyDown`, placed before the `isEditableTarget` guard. Because this runs before the `const mod = ...` declaration, the handler must perform its own mod-key check (`isMac ? e.metaKey && !e.ctrlKey : e.ctrlKey && !e.metaKey`) and key match (`e.key.toLowerCase() === 'g'`) inline:
-  - Guard: mod key active, key is `g`, `searchOpen` is true, `searchStateRef.current.query` is non-empty
-  - Read `query`, `caseSensitive`, `regex` from `searchStateRef.current`
-  - Get active pane's `searchAddon` via `manager.getActivePane().searchAddon`
-  - Call `findNext` or `findPrevious` with `{ caseSensitive, regex }` (no `incremental` — matches the chevron button behavior, not the live-typing behavior)
-  - Call `pane.terminal.focus()` to return focus to the terminal
-  - `preventDefault` + `stopPropagation` — important to suppress macOS/Electron's native "find next" which could otherwise trigger the built-in find bar
-
-### Edge cases
-
-- **No query**: no-op (empty string guard)
-- **No active pane**: no-op (existing pane guard)
-- **Search closed**: no-op (`searchOpen` guard)
-- **Key repeat**: filtered by existing `if (e.repeat) return` at top of `onKeyDown`
-- **Focus in search input**: `Cmd+G` / `Cmd+Shift+G` must bypass the `isEditableTarget` guard for search input descendants (see keyboard-handlers.ts changes above)
diff --git a/docs/tab-group-model-follow-up.md b/docs/tab-group-model-follow-up.md
deleted file mode 100644
index a569a8a73f8..00000000000
--- a/docs/tab-group-model-follow-up.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# Tab Group Model Follow-Up
-
-## Goal
-
-Move Orca's split tab-group implementation from a store-plus-controller shape to a true model/service boundary that is closer to VS Code's editor-group architecture, without porting VS Code wholesale.
-
-This follow-up is intentionally **not** part of the current PR. The current PR already moved the feature in the right direction by:
-
-- making split ratios persisted model state
-- centralizing move/copy/merge group operations in the tabs store
-- thinning `TabGroupPanel` into more of a view
-
-The next step is to make tab-group behavior a first-class model instead of a set of store records plus helper/controller logic.
-
-## Why
-
-Split tab groups are no longer just a rendering concern. They now carry:
-
-- layout structure
-- persisted split ratios
-- active group state
-- cross-group move/copy semantics
-- close/merge behavior
-- mixed content types per group
-
-As this grows, keeping behavior split across Zustand records, controller hooks, and React components will become harder to reason about and easier to regress.
-
-VS Code handles this by making editor groups a first-class model/service. Orca does not need the full VS Code abstraction surface, but it should adopt the same direction:
-
-- model owns behavior
-- views render model state
-- imperative operations go through one boundary
-
-## Current Gaps
-
-Even after the current PR, these gaps remain:
-
-1. Group activation is still minimal.
-   Orca tracks `activeGroupIdByWorktree`, but not true MRU group ordering or activation reasons.
-
-2. Group operations are still store-action centric, not model-object centric.
-   The store now owns the mutations, but callers still think in terms of raw IDs and records.
-
-3. There are no group lifecycle events.
-   React consumers read state snapshots, but there is no explicit event surface for add/remove/move/merge/activate.
-
-4. Hydration and runtime behavior are still tightly coupled to raw store shape.
-   This makes it harder to evolve the model without touching many callers.
-
-5. `TabGroupPanel` is thinner, but still knows too much about worktree/group coordination.
-
-## Target Shape
-
-Introduce a per-worktree tab-group model/controller layer, for example:
-
-- `TabGroupWorkspaceModel`
-- `TabGroupModel`
-- `TabGroupLayoutModel`
-
-This layer should:
-
-- wrap the normalized store state for a single worktree
-- expose typed operations instead of raw state surgery
-- centralize MRU group activation
-- centralize group lifecycle transitions
-- provide derived read models for rendering
-
-React components should consume:
-
-- derived selectors for render state
-- a small command surface for mutations
-
-They should not need to understand layout tree mutation details.
-
-## Proposed Responsibilities
-
-### `TabGroupWorkspaceModel`
-
-Owns all tab-group state for one worktree:
-
-- groups
-- layout tree
-- active group
-- MRU group order
-
-Exposes commands like:
-
-- `splitGroup(groupId, direction)`
-- `closeGroup(groupId)`
-- `mergeGroup(groupId, targetGroupId?)`
-- `activateGroup(groupId, reason)`
-- `moveTab(tabId, targetGroupId, options?)`
-- `copyTab(tabId, targetGroupId, options?)`
-- `reorderGroupTabs(groupId, orderedTabIds)`
-- `resizeSplit(nodePath, ratio)`
-
-### `TabGroupModel`
-
-Represents one group and exposes:
-
-- `id`
-- `tabs`
-- `activeTab`
-- `tabOrder`
-- `isActive`
-- `isEmpty`
-
-This can be a thin wrapper over store state rather than a heavy OO abstraction.
-
-### `TabGroupLayoutModel`
-
-Encapsulates layout operations:
-
-- replace leaf with split
-- remove leaf and collapse tree
-- find sibling group
-- update split ratio
-- validate layout against live groups
-
-This logic is currently spread across `tabs.ts` helpers and should move into one focused module.
-
-## Migration Plan
-
-### Phase 1: Extract Pure Model Utilities
-
-Create a new module for pure tab-group model operations:
-
-- layout mutation
-- group merge/collapse rules
-- MRU group bookkeeping
-- validation helpers
-
-This phase should not change runtime behavior.
-
-### Phase 2: Add Workspace Model Facade
-
-Introduce a facade over the Zustand store for one worktree:
-
-- input: `worktreeId`
-- output: commands + derived state
-
-This can begin as a hook-backed facade, but the logic should live outside React as much as possible.
-
-### Phase 3: Move Components To Render-Only
-
-Reduce `TabGroupPanel` and `TabGroupSplitLayout` to:
-
-- render derived state
-- dispatch commands
-
-They should no longer assemble group/tab mutation behavior themselves.
-
-### Phase 4: Add MRU Group Semantics
-
-Track:
-
-- active group
-- most recently active group order
-
-Use this for:
-
-- close-group merge target selection
-- focus restoration after group removal
-- more VS Code-like group activation behavior
-
-### Phase 5: Hydration Boundary Cleanup
-
-Move hydration/restore validation through the model layer so layout and groups are repaired in one place.
-
-## Non-Goals
-
-- Porting VS Code's editor-group implementation directly
-- Replacing Zustand
-- Introducing a large class hierarchy for its own sake
-- Refactoring terminal pane internals as part of the same follow-up
-
-## Risks
-
-1. Terminal/editor/browser tabs currently share the unified tab model.
-   Refactors must preserve mixed-content behavior across groups.
-
-2. Hydration and worktree switching depend on current store shape.
-   The migration should preserve persisted session compatibility.
-
-3. Closing and merging groups can easily regress active-tab restoration.
-   MRU rules need explicit tests.
-
-## Test Plan For Follow-Up
-
-Add focused tests around:
-
-- split + resize + restore
-- close empty group
-- close non-empty group merges into MRU/sibling target
-- move tab between groups
-- copy tab between groups
-- active group restoration after merge
-- hydration repairing invalid layout/group combinations
-- worktree switch preserving active group and active tab
-
-## Suggested PR Breakdown
-
-1. `refactor: extract tab group layout model helpers`
-2. `refactor: add worktree tab group model facade`
-3. `refactor: move tab group components to render-only`
-4. `feat: add MRU group activation model`
-5. `refactor: route hydration through tab group model`
-
-## Recommendation
-
-Do this as a dedicated follow-up PR sequence, not as an extension of the current PR.
-
-The current PR is already the right stopping point:
-
-- enough model centralization to stabilize the feature
-- not so much architectural churn that review and regression risk explode
diff --git a/docs/tasks-page-resume-state.md b/docs/tasks-page-resume-state.md
new file mode 100644
index 00000000000..64589b277ac
--- /dev/null
+++ b/docs/tasks-page-resume-state.md
@@ -0,0 +1,176 @@
+# Tasks Page Resume State
+
+## Goal
+
+When a user leaves the Tasks page and comes back later, Orca should reopen the page in the same working context instead of falling back to a generic GitHub Issues/PRs list.
+
+The resume behavior should cover:
+
+- GitHub vs Linear.
+- GitHub Issues/PRs vs GitHub Project mode.
+- The selected GitHub Issues/PRs preset or custom search.
+- The selected GitHub Project and Project view.
+- The selected repos for GitHub Issues/PRs.
+- The selected Linear teams.
+
+This should be lightweight. It should not introduce a second project-selection model or duplicate state that is already persisted elsewhere.
+
+## Existing Persisted State
+
+The current settings model already remembers most durable task choices:
+
+- `settings.defaultTaskSource` remembers GitHub vs Linear.
+- `settings.defaultRepoSelection` remembers GitHub repo selection for cross-repo Issues/PRs.
+- `settings.defaultLinearTeamSelection` remembers Linear team selection.
+- `settings.githubProjects.activeProject` remembers the active GitHub Project.
+- `settings.githubProjects.lastViewByProject` remembers the last selected Project view per Project.
+- `settings.defaultTaskViewPreset` remembers the user's default GitHub Issues/PRs preset.
+
+These should stay in place. They are already wired into the page and, for repo/team/project selection, they represent actual user preferences rather than purely transient page state.
+
+## Missing State
+
+The missing piece is the user's current page position inside Tasks:
+
+- Whether GitHub is showing `Issues/PRs` or `Project`.
+- Which GitHub Issues/PRs preset is currently active.
+- The currently applied GitHub Issues/PRs query when the user has typed a custom search.
+- Which Linear preset is currently active.
+- The currently applied Linear query when the user has typed a search.
+
+Linear presets are visible task tabs and drive the fetch path, so they must be restored too.
+
+## Proposed Shape
+
+Add a small optional field to `PersistedUIState`:
+
+```ts
+export type TaskResumeState = {
+  githubMode?: 'items' | 'project'
+  githubItemsPreset?: TaskViewPresetId | null
+  githubItemsQuery?: string
+  linearPreset?: 'assigned' | 'created' | 'all' | 'completed'
+  linearQuery?: string
+}
+```
+
+Then add:
+
+```ts
+taskResumeState?: TaskResumeState
+```
+
+to `PersistedUIState`.
+
+Why `PersistedUIState`: this is page-position UI state, similar to sidebar filters and widths. It is not an app-wide setting and should not be presented as a configurable default.
+
+Do not add `source` to `TaskResumeState`. `settings.defaultTaskSource` already represents the user's last-used task source today, and duplicating it would create two persisted sources of truth. Keep source changes on the existing settings path.
+
+Do not reset `githubMode` just because the current source is Linear. Source selection and GitHub sub-mode are independent pieces of context: if the user was in GitHub Project mode, switched to Linear, then later switches back to GitHub, GitHub should still reopen in Project mode.
+
+## Restore Rules
+
+On Tasks page mount:
+
+1. If `taskPageData.taskSource` was passed by a caller, use it. Explicit navigation intent should win.
+2. Otherwise fall back to `settings.defaultTaskSource`.
+3. Apply these restore rules only after both settings and persisted UI state have hydrated. The current app loads those asynchronously before setting `persistedUIReady`; a `useState` initializer that reads `settings === null` or an unhydrated `taskResumeState` will capture defaults and miss the restored context.
+
+The restore should run once per Tasks page mount, after hydration is ready. It should not keep reapplying persisted state over local user interactions while the page remains open.
+
+For GitHub:
+
+1. Restore `githubMode` from `taskResumeState.githubMode`.
+2. If mode is `items`, restore `githubItemsPreset` and `githubItemsQuery`.
+3. Repo selection continues to come from `settings.defaultRepoSelection`.
+4. If mode is `project`, use `settings.githubProjects.activeProject` and `settings.githubProjects.lastViewByProject`.
+5. If Project mode has no active project or view, show the Project picker empty state instead of silently switching to Issues/PRs.
+
+For Linear:
+
+1. Restore `linearPreset`.
+2. Restore `linearQuery`.
+3. Team selection continues to come from `settings.defaultLinearTeamSelection`.
+
+Fallback behavior:
+
+- If resume state is absent, use today's defaults.
+- If `githubItemsPreset` is non-null, derive the query from the preset unless `githubItemsQuery` disagrees because of a future migration. The preset should be treated as authoritative.
+- If `githubItemsPreset` is null, use `githubItemsQuery` as a custom search.
+- If `linearQuery` is non-empty, treat it as custom search and keep the restored `linearPreset` as the preset to return to after the search is cleared. The visible active preset should be suppressed while the search input is non-empty, matching today's UI.
+
+## Write Rules
+
+Update `taskResumeState` only when the user changes the active page context:
+
+- Switching GitHub mode between Issues/PRs and Project.
+- Clicking a GitHub Issues/PRs preset.
+- Applying the debounced GitHub Issues/PRs search.
+- Clearing the GitHub Issues/PRs search.
+- Clicking a Linear preset.
+- Applying the debounced Linear search.
+- Clearing the Linear search.
+
+Do not persist every raw search keystroke. The current UI applies search after a 300 ms debounce, so the persisted value should follow the debounced applied query, not the raw input. A user who types, waits for results, leaves Tasks, and comes back should see the same applied query.
+
+Task source, repo selection, Linear team selection, active Project, and active Project view should continue writing through their existing settings paths.
+
+The resume setter should merge partial updates with the existing resume state so changing one dimension does not erase the others. It should persist via `window.api.ui.set({ taskResumeState })` after updating local Zustand state.
+
+When writing preset selections, clear stale custom-query ambiguity explicitly:
+
+- GitHub preset click: write `{ githubItemsPreset: presetId, githubItemsQuery: undefined }` or the canonical preset query. Restore must still use the preset as authoritative.
+- GitHub custom search apply/debounce: write `{ githubItemsPreset: null, githubItemsQuery: trimmedQuery }`.
+- GitHub search clear: write `{ githubItemsPreset: null, githubItemsQuery: '' }`.
+- Linear preset click: write `{ linearPreset: presetId, linearQuery: '' }`.
+- Linear custom search apply/debounce: write `{ linearQuery: trimmedQuery }` without changing `linearPreset`.
+- Linear search clear: write `{ linearQuery: '' }` without changing `linearPreset`.
+
+Do not persist mode changes caused only by hiding Project mode while another source is active. In practice, avoid an effect that changes persisted `githubMode` from `project` to `items` when `taskSource !== 'github'`.
+
+## Implementation Notes
+
+Primary files:
+
+- `src/shared/types.ts`: add `TaskResumeState` and `taskResumeState?: TaskResumeState`.
+- `src/shared/constants.ts`: no required default beyond leaving the field absent. If a concrete default is preferred, use GitHub Issues/PRs with the existing default preset.
+- `src/renderer/src/store/slices/ui.ts`: hydrate `taskResumeState` defensively, expose a setter such as `setTaskResumeState`, and use it in `openTaskPage` prefetch selection.
+- `src/renderer/src/components/TaskPage.tsx`: initialize source from existing settings/page data, and initialize GitHub mode, GitHub item preset/query, Linear preset, and Linear query from the resume state.
+- `src/renderer/src/App.tsx`: no new work should be needed if the field rides the existing `ui:get` hydration.
+
+The setter should call `window.api.ui.set({ taskResumeState })` through the same persistence path used by other persisted UI fields, or follow the existing store pattern if there is already a central UI save effect for the relevant slice.
+
+Hydration must sanitize the nested object because `PersistedUIState` comes from disk. Invalid `githubMode`, invalid GitHub preset ids, invalid Linear preset ids, or non-string queries should fall back field-by-field rather than entering Zustand as untrusted values.
+
+`TaskPage` should subscribe to `persistedUIReady`, `settings`, and `taskResumeState`, then perform a one-shot local initialization once both settings and UI hydration are available. This avoids the current class of bugs where `useState(settings?.defaultTaskViewPreset ?? 'all')` captures `'all'` before settings arrive.
+
+`openTaskPage` currently prefetches the settings default GitHub preset. After this change, it should prefetch the query the Tasks page will actually mount with:
+
+1. If explicit `taskPageData.taskSource` is `linear`, skip GitHub prefetch.
+2. If explicit `taskPageData.taskSource` is `github`, or the resolved source is GitHub, prefetch only when the resolved GitHub mode is `items`.
+3. If `githubItemsPreset` is non-null, prefetch that preset query.
+4. If `githubItemsPreset` is null and `githubItemsQuery` is non-empty, prefetch the custom query.
+5. Otherwise prefetch `settings.defaultTaskViewPreset`.
+
+The prefetch should also use the same repo selection the page will use: `taskPageData.preselectedRepoId` when present, otherwise `settings.defaultRepoSelection`, otherwise all eligible repos. Warming only `activeRepoId` is acceptable as an optimization fallback, but it is not equivalent to the mounted cross-repo query.
+
+## Non-Goals
+
+Do not remember scroll position, selected table row, open dialogs, pagination page, Project search overrides, or cached API results in this pass.
+
+Those states are more fragile because they depend on live remote data. The first version should only restore the user's broad working context.
+
+## Acceptance Criteria
+
+- Open Tasks, switch to Linear, leave Tasks, return to Tasks: Linear is selected.
+- Open Tasks, switch to GitHub Project mode, switch to Linear, leave Tasks, return to Tasks, then switch back to GitHub: GitHub is still in Project mode.
+- Open Tasks, switch to GitHub Project mode, select a Project view, leave Tasks, return to Tasks: Project mode opens on the same Project view.
+- Open Tasks, choose GitHub Issues/PRs `My PRs`, leave Tasks, return to Tasks: GitHub Issues/PRs opens with `My PRs` active.
+- Open Tasks, type and apply a custom GitHub search, leave Tasks, return to Tasks: GitHub Issues/PRs opens with that custom query and no preset selected.
+- Open Tasks, type a GitHub search, wait for the debounced results, leave Tasks, return to Tasks: GitHub Issues/PRs opens with that applied query and no preset selected.
+- Open Tasks, choose Linear `Completed`, leave Tasks, return to Tasks: Linear opens with `Completed` active.
+- Open Tasks, type a Linear search, wait for the debounced results, leave Tasks, return to Tasks: Linear opens with that applied query.
+- Open Tasks before hydration has completed, then wait for hydration: Tasks applies the persisted source/mode/preset/query exactly once and does not overwrite subsequent user changes.
+- Corrupt `taskResumeState` on disk with invalid modes/preset ids/non-string queries, restart, and open Tasks: invalid fields are ignored field-by-field without breaking the page.
+- Existing repo selection, Linear team selection, and GitHub Project view persistence keep working unchanged.
+- Restart the app after each source/mode/preset/custom-query scenario above: the same Tasks context is restored from persisted UI/settings state.
diff --git a/docs/term-shortcut-fix.md b/docs/term-shortcut-fix.md
deleted file mode 100644
index e04d10399f0..00000000000
--- a/docs/term-shortcut-fix.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# Terminal Shortcut Audit And Fix Plan
-
-## Context
-
-Linked reports:
-
-- `#443`: `Ctrl+R` / `Cmd+R` reverse search was blocked in the terminal.
-- `#453`: fixed `#443` by removing the app-level reload accelerator conflict.
-- `#481`: reports `Ctrl+U` (`unix-line-discard`) being swallowed.
-- `#482`: reports `Ctrl+E` (`end-of-line`) being swallowed, but is marked not reproducible.
-
-The symptom across all four links is "terminal control chord does not reach readline", but the current code shows they are not all the same bug.
-
-## Findings
-
-1. `#443` and `#453` are directly related.
-   `CmdOrCtrl+R` was reserved above the renderer, so the terminal never saw the chord. `#453` fixed that by removing the reload accelerator and keeping only `Shift+CmdOrCtrl+R` for force reload.
-
-2. `#481` and `#482` are related to the same problem class, but not proven to share `#443`'s exact root cause.
-   Current `mainWindow.webContents.on('before-input-event', ...)` no longer reserves `R`, `U`, or `E`.
-   Current terminal renderer shortcut handling also does not reserve macOS `Ctrl+R`, `Ctrl+U`, or `Ctrl+E`.
-
-3. The real gap was auditability, not just one missing exception.
-   Shortcut interception lived in multiple places:
-   - main window `before-input-event`
-   - browser guest `before-input-event`
-   - terminal renderer `keydown` capture
-
-   That made it easy to fix one conflict (`Cmd/Ctrl+R`) while leaving the overall reservation surface implicit and hard to verify.
-
-## Reproduction Matrix
-
-Expected behavior from a focused terminal on macOS:
-
-- Pass through to shell/readline:
-  - `Ctrl+R`
-  - `Ctrl+U`
-  - `Ctrl+E`
-  - `Ctrl+A`
-  - `Ctrl+W`
-  - `Ctrl+K`
-  - `Alt+B`
-  - `Alt+F`
-  - `Alt+D`
-
-- Reserved by Orca:
-  - `Cmd+F`
-  - `Cmd+K`
-  - `Cmd+W`
-  - `Cmd+D`
-  - `Cmd+Shift+D`
-  - `Cmd+[`
-  - `Cmd+]`
-  - `Cmd+Shift+Enter`
-  - `Ctrl+Backspace`
-  - `Cmd+Backspace`
-  - `Cmd+Delete`
-  - `Alt+Backspace`
-
-Expected behavior from main-process/browser-guest forwarding:
-
-- Reserved:
-  - zoom shortcuts
-  - worktree palette
-  - quick open
-  - worktree index jump
-
-- Must never be reserved there:
-  - `Cmd/Ctrl+R`
-  - readline control chords like `Ctrl+U`, `Ctrl+E`, `Ctrl+R`
-
-## Plan
-
-1. Centralize the window-level shortcut allowlist into a shared pure helper.
-   Why: main-window and browser-guest forwarding should not drift apart, because either one can steal terminal input before the renderer sees it.
-
-2. Centralize terminal-pane shortcut classification into a pure helper.
-   Why: the terminal shortcut layer must stay an explicit allowlist so future shortcuts do not accidentally swallow readline chords.
-
-3. Add regression tests that enumerate both sides:
-   - allowed Orca shortcuts
-   - guaranteed shell passthrough chords
-
-4. Keep `#443` fixed and make the current status of `#481` / `#482` testable.
-   Why: even if one report later turns out to be environment-specific, Orca should still have an executable contract for what it reserves.
-
-## Implementation Notes
-
-- Shared helper added for main-process shortcut resolution.
-- Shared helper added for terminal-pane shortcut resolution.
-- Tests added to encode the allowlist and passthrough matrix explicitly.
-
-## Follow-Up Risk
-
-This change makes the current reservation surface auditable, but it does not redesign non-macOS terminal shortcuts. Orca still uses `Ctrl` as the primary modifier for several terminal actions on Linux/Windows, which is a separate UX question from the macOS control-chord regressions linked above.
diff --git a/docs/terminal-drop-ssh.md b/docs/terminal-drop-ssh.md
deleted file mode 100644
index 09f44a63887..00000000000
--- a/docs/terminal-drop-ssh.md
+++ /dev/null
@@ -1,452 +0,0 @@
-# Terminal drag-and-drop over SSH
-
-## Problem
-
-Dragging a local file onto a terminal pane inserts the file's absolute path
-into the PTY, so the user can reference it in a CLI or TUI-agent prompt. On
-SSH worktrees the terminal runs remotely, so injecting a **local** path
-(`/Users/alice/Desktop/log.txt`) is useless — the remote agent has no access
-to it.
-
-The file-explorer drop path was fixed in PR #1279 by routing through SFTP
-upload (`importExternalPathsSsh`). The terminal drop path was not touched
-and still breaks for SSH worktrees.
-
-Reported: https://stablygroup.slack.com/archives/C0ASMDT6LQZ/p1777530155421009
-
-## Goals
-
-- Dropping a local file onto a terminal connected to an SSH worktree makes
-  that file available to the remote shell/agent, and injects a path the
-  remote process can read.
-- Local terminal drops keep their current behavior: reference-in-place, no
-  copy, no authorization, no repo pollution.
-- Local and SSH paths share one main-side resolver. The renderer may pass
-  connection context and show progress UI, but copy/upload/deconfliction
-  policy stays out of the renderer so the two modes do not drift over time.
-
-## Non-goals
-
-- Unifying terminal drop with file-explorer drop. They have different
-  semantics (explorer always copies into a user-picked `destDir`; terminal
-  references a path). They share the SSH upload primitive internally but
-  remain separate IPCs.
-- Cleanup / garbage collection of staged remote files. Tracked as follow-up
-  (see "Follow-ups" below — file **before merging** and replace this
-  parenthetical with the issue number so the reference is locatable). Until
-  GC lands, files uploaded by a drop whose pane is unmounted before the
-  upload resolves are orphaned in `.orca/drops/` with no injected path.
-  Users should know uploads are not cancellable.
-- Abortable uploads. SFTP transfers run to completion even if the terminal
-  pane is unmounted mid-flight.
-
-## Considered: Option A (full unification)
-
-Terminal drop calls `fs:importExternalPaths` with
-`destDir = worktreePath`, then injects `result.destPath` into the PTY.
-Shares exactly the file-explorer code path.
-
-Rejected because it changes **local** terminal-drop UX: today dropping
-`~/Desktop/log.txt` into the terminal pastes `/Users/…/Desktop/log.txt`
-so the agent reads the file in place; under Option A the file would be
-copied into the repo. Users rely on the reference-in-place behavior to
-point agents at files without polluting the worktree.
-
-## Design (Option B)
-
-### New IPC
-
-```
-fs:resolveDroppedPathsForAgent({
-  paths: string[],
-  worktreePath: string,
-  connectionId?: string,
-}) → {
-  resolvedPaths: string[],
-  skipped: { sourcePath: string; reason: 'missing' | 'symlink' | 'permission-denied' | 'unsupported' }[],
-  failed: { sourcePath: string; reason: string }[],
-}
-```
-
-Contract:
-
-- **Local (`connectionId == null`):** returns
-  `{ resolvedPaths: paths, skipped: [], failed: [] }` unchanged. No copy. No
-  authorization (matches today's behavior — the agent's own read is what gets
-  authorized, not the drop). Use `args.connectionId == null` (not `!args.connectionId`)
-  so an empty string cannot silently pick the local branch.
-- **SSH (`connectionId` is a non-empty string):** uploads each path via SFTP
-  into a staging dir under the worktree. Returns remote absolute paths for
-  items that uploaded successfully, items rejected by policy (symlinks,
-  missing sources, permission-denied, unsupported file types) in `skipped`,
-  and hard upload errors in `failed`. The split mirrors `ImportItemResult`'s
-  existing `'imported' | 'skipped' | 'failed'` and lets the renderer toast
-  "Skipped N symlinks" distinctly from "Failed to upload N files." Collapsing
-  skipped into failed would mislabel routine policy rejections as errors.
-
-### SSH staging dir
-
-`${worktreePath}/.orca/drops/` on the remote. `.orca/` is reserved as an
-Orca-owned directory for future remote state (GC metadata, cached remote
-capability probes, etc.); this is its first use. Future features adding
-subpaths under `.orca/` should namespace themselves (`.orca/drops/`,
-`.orca/<feature>/`) rather than placing files at the root.
-
-Rationale:
-
-- No need to resolve remote `$HOME` (which would require a round-trip and
-  caching layer).
-- Lives inside the worktree, so cleaned up naturally when the worktree is
-  deleted.
-- The agent has read access by construction (it runs with the worktree's
-  cwd).
-
-The main process must bootstrap `.orca/.gitignore` with `*\n!.gitignore\n`
-before the first successful upload. Otherwise every SSH terminal drop dirties
-source control with an untracked `.orca/` directory, which recreates the
-repo-pollution problem that ruled out Option A for local terminal drops. The
-`!.gitignore` negation keeps the marker file itself trackable if we ever want
-to (and costs nothing today — `git status` stays clean either way because
-nothing tries to add it).
-
-The staging directory must be created recursively over SFTP before upload:
-
-- create `${worktreePath}/.orca` (ignore "already exists")
-- write `${worktreePath}/.orca/.gitignore` as `*\n!.gitignore\n` **only if it
-  does not already exist** — never overwrite. A user may have added patterns
-  there, and silently clobbering user-authored content violates least
-  surprise even inside an Orca-owned directory. Use `sftpPathExists` before
-  writing. (Two concurrent first-drops racing through the `sftpPathExists`
-  check will both write the same bytes — last writer wins, idempotent, so
-  the race is benign and not worth locking.)
-- create `${worktreePath}/.orca/drops` (ignore "already exists")
-
-Do not rely on `uploadFile`, `uploadDirectory`, or the existing
-`mkdirSftp(destPath)` calls to create missing parents. `uploadFile` writes
-directly to the final remote file path, and `mkdirSftp` is not recursive, so
-the first terminal drop into a fresh SSH worktree would fail if the parents do
-not already exist.
-
-### Main-side implementation
-
-`src/main/ipc/filesystem-mutations.ts`:
-
-```ts
-ipcMain.handle('fs:resolveDroppedPathsForAgent', async (_e, args) => {
-  // Why: `== null` (not `!args.connectionId`) so an empty string is treated
-  // as an error from the renderer, not silently routed to the local branch.
-  if (args.connectionId == null) {
-    return { resolvedPaths: args.paths, skipped: [], failed: [] }
-  }
-  const worktreePath = args.worktreePath.replace(/\/+$/, '')
-  const destDir = `${worktreePath}/.orca/drops`
-  const { results } = await importExternalPathsSsh(
-    args.paths,
-    destDir,
-    args.connectionId,
-    { ensureDir: true },
-  )
-  const resolvedPaths: string[] = []
-  const skipped: { sourcePath: string; reason: ImportSkipReason }[] = []
-  const failed: { sourcePath: string; reason: string }[] = []
-  // Iterate in input order so injected paths align with the user's drop order.
-  for (const r of results) {
-    if (r.status === 'imported') {
-      resolvedPaths.push(r.destPath)
-    } else if (r.status === 'skipped') {
-      skipped.push({ sourcePath: r.sourcePath, reason: r.reason })
-    } else {
-      failed.push({ sourcePath: r.sourcePath, reason: r.reason })
-    }
-  }
-  return { resolvedPaths, skipped, failed }
-})
-```
-
-Reuses `importExternalPathsSsh` — SFTP upload, symlink pre-scan, name
-deconfliction, per-item error reporting are all already there.
-
-**Staging bootstrap lives inside `importExternalPathsSsh`** behind a new
-optional `{ ensureDir?: boolean }` parameter. When set, before the first
-upload the function creates `${destDir}`'s parent chain (`.orca`, then
-`drops`) and writes `.orca/.gitignore` (`*\n`) only if missing, all on the
-**same SFTP session** already opened for the upload. Do not add a separate
-`ensureSshDropStagingDir` helper that opens its own channel — that would
-double the SFTP handshake cost on every drop.
-
-### Renderer-side implementation
-
-**API change to `shellEscapePath`.** Today the second arg is a *userAgent
-string* (substring-matched for `"Windows"`), which couples escape rules to
-the client OS. For SSH drops we need to escape for the *target shell*,
-which is always POSIX on the remote regardless of client OS. Change the
-signature to take an explicit target:
-
-```ts
-shellEscapePath(path: string, targetShell: 'posix' | 'windows')
-```
-
-Callers derive `targetShell` from context: local drops pass
-`isWindowsUserAgent() ? 'windows' : 'posix'`; SSH drops always pass
-`'posix'`. This makes test #11 (Windows client → Linux SSH worktree)
-correct by construction instead of by coincidence.
-
-**Migration — all three call sites + tests must change together:**
-
-- `src/renderer/src/components/terminal-pane/pane-helpers.ts:53` — update
-  signature; drop the `userAgent` default.
-- `src/renderer/src/components/terminal-pane/TerminalPane.tsx:937`
-  (file-explorer → terminal drop). This is a **local-only** code path
-  (explorer drag uses a DOM MIME type that the preload SSH bridge does not
-  forward), so pass `isWindowsUserAgent() ? 'windows' : 'posix'` to preserve
-  today's behavior exactly.
-- `src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.ts:344`
-  — replaced by the new SSH-aware handler below; the `shellEscapePath` call
-  moves inside it with an explicit `targetShell`.
-- `src/renderer/src/components/terminal-pane/pane-helpers.test.ts` — the
-  existing cases pass `'Macintosh'`, `'Linux'`, `'Windows'` as the userAgent
-  arg. Rewrite to pass `'posix'` (for Mac/Linux) and `'windows'`, so tests
-  exercise the new contract rather than the legacy substring match.
-
-No local behavior changes if this migration is done in one commit: Mac/Linux
-already took the POSIX branch via the userAgent string match; Windows
-already took the Windows branch. The new signature just names that
-explicitly.
-
-`src/renderer/src/components/terminal-pane/use-terminal-pane-global-effects.ts`:
-
-```ts
-return window.api.ui.onFileDrop(async (data) => {
-  if (data.target !== 'terminal') return
-  if (data.paths.length === 0) return
-  const manager = managerRef.current
-  if (!manager) return
-  const pane = manager.getActivePane() ?? manager.getPanes()[0]
-  if (!pane) return
-  const paneId = pane.id
-  const transport = paneTransportsRef.current.get(paneId)
-  if (!transport) return
-
-  const wtId = worktreeIdRef.current
-  const worktreePath = worktreePathRef.current
-  if (!wtId || !worktreePath) return
-
-  // Why: getConnectionId (selector on the terminals/repos slice:
-  // `state.repos.find(r => r.id === <worktree's repoId>)?.connectionId`,
-  // exposed via the store) returns `string` (SSH), `null` (local repo
-  // found), or `undefined` (store not hydrated / worktree not found).
-  // Treat `undefined` as an error, not as "local" — otherwise a drop
-  // during hydration would silently paste local paths into a remote
-  // shell.
-  const connectionId = getConnectionId(wtId)
-  if (connectionId === undefined) {
-    toast.error('Worktree not ready — try again in a moment.')
-    return
-  }
-  const isRemote = connectionId !== null
-  const targetShell: 'posix' | 'windows' = isRemote
-    ? 'posix'
-    : isWindowsUserAgent()
-      ? 'windows'
-      : 'posix'
-
-  // Local fast path: no IPC round-trip, no toast. Preserves today's
-  // zero-latency behavior exactly — same code shape as before, only the
-  // shellEscapePath signature is new (and resolves to the same branch).
-  if (!isRemote) {
-    for (const p of data.paths) {
-      transport.sendInput(`${shellEscapePath(p, targetShell)} `)
-    }
-    pane.terminal.focus()
-    return
-  }
-
-  const pending = toast.loading(
-    `Uploading ${data.paths.length} file(s) to remote…`,
-  )
-  try {
-    const { resolvedPaths, skipped, failed } =
-      await window.api.fs.resolveDroppedPathsForAgent({
-        paths: data.paths,
-        worktreePath,
-        connectionId,
-      })
-    // Why: pane may have unmounted during the SFTP upload (tab closed,
-    // worktree switched). Re-check the transport map before writing so
-    // we don't call sendInput on a torn-down PTY. Orphaned uploads are
-    // acknowledged in Non-goals.
-    const liveTransport = paneTransportsRef.current.get(paneId)
-    if (liveTransport) {
-      // resolvedPaths preserves input order (main-side iterates results in
-      // order); injected paths line up with the user's drop gesture.
-      for (const p of resolvedPaths) {
-        liveTransport.sendInput(`${shellEscapePath(p, targetShell)} `)
-      }
-      pane.terminal.focus()
-    }
-    if (skipped.length > 0) {
-      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}.`)
-    }
-  } catch (err) {
-    toast.error(extractIpcErrorMessage(err, 'Failed to upload files.'))
-  } finally {
-    toast.dismiss(pending)
-  }
-})
-```
-
-`extractIpcErrorMessage` is the existing helper at
-`src/renderer/src/lib/ipc-error.ts:6` (already used by
-`useFileExplorerImport.ts`, `Terminal.tsx`, etc.). Reuse it — do not copy
-the body locally.
-
-New dependencies on the hook: `worktreeId` and `worktreePath` refs. Use the
-`TerminalPane`'s own `worktreeId` prop, not global `activeWorktreeId`. The
-drop listener is already gated by `isActive`, and the pane's own
-`worktreeId` is the authoritative identity of the terminal being written
-to; reading from global state would race during worktree switches. Promote
-this reasoning into a `// Why:` comment at the call site per CLAUDE.md.
-
-Derive `worktreePath` the same way `use-terminal-pane-lifecycle.ts` does
-today: find the worktree by `worktreeId` in the store, then fall back to
-`cwd`.
-
-### Why not branch in the renderer
-
-- Keeps upload semantics in one place. Adding a second terminal consumer
-  (e.g. a standalone TUI pane) should call the same resolver instead of
-  deciding where to copy, how to deconflict names, or how to report per-item
-  failures.
-- The renderer can know that the worktree is SSH for progress UI and shell
-  escaping, but it should not know SFTP details or construct uploaded
-  destination filenames itself.
-
-### UX details
-
-- **SSH "Uploading…" toast:** SFTP of a few MB can take seconds. Without
-  feedback the user thinks the drop failed. Dismiss on success, replace
-  with an error toast on failure.
-- **Don't inject until upload resolves.** Injecting the remote path before
-  the file lands means the agent may try to read a file that doesn't yet
-  exist and error. Worth the extra perceived latency.
-- **Failure policy:** partial failures still inject the succeeded paths
-  and toast the count of failures (same pattern as the explorer).
-- **Escape for the terminal that receives the path.** Local drops keep the
-  existing platform-specific quoting. SSH drops must use POSIX shell quoting
-  for the returned remote paths; do not let a Windows client choose Windows
-  quoting for a Linux/macOS SSH shell.
-
-## System fit
-
-```
-[Electron preload native drop]
-             |
-             v
-[terminal:file-drop IPC relay]
-             |
-             v
-[active TerminalPane drop handler]
-             |
-             v
-[fs:resolveDroppedPathsForAgent]
-      | local                           | SSH
-      v                                 v
-[return original paths]          [SFTP stage into ${worktreePath}/.orca/drops]
-      |                                 |
-      |                                 v
-      |                          [return remote readable paths]
-      |                                 |
-      +---------------+-----------------+
-                      |
-                      v
-          [PTY sendInput escaped paths]
-```
-
-## Testing
-
-1. Local worktree, drop a single file onto the terminal → original
-   absolute path pasted. No copy. No change from today.
-2. Local worktree, drop multiple files → each path pasted separated by a
-   space. No change from today.
-3. SSH worktree, drop a single file → file uploads to
-   `${worktreePath}/.orca/drops/<file>` on remote; remote path pasted
-   into PTY; agent can read it.
-4. SSH worktree, drop a folder → folder uploads recursively; remote dir
-   path pasted.
-5. SSH worktree, drop a symlink → no injection; toast reads
-   "Skipped 1 symlink." (not "Failed to upload") because symlink rejection
-   is policy, not error.
-6. SSH worktree, drop 5 files where items 2 and 4 are permission-denied at
-   the local source → paths 1, 3, 5 are injected **in that order**
-   (matching input order), toast says "Skipped 2 items." (permission-denied
-   is classified `skipped`, not `failed`, by `importExternalPathsSsh`).
-   Additionally, simulate an SFTP write error mid-upload to cover the
-   `failed` branch → "Failed to upload N files" toast.
-7. SSH worktree disconnected mid-drag → user-visible error toast, no
-   partial injection.
-8. Name collision: drop the same file twice in quick succession → second
-   upload lands as `<name> copy.<ext>` (deconfliction inherited from
-   `importExternalPathsSsh`).
-9. Fresh SSH worktree with no `.orca` directory → first drop creates
-   `.orca/`, `.orca/.gitignore`, and `.orca/drops/`; upload succeeds.
-10. After an SSH drop, `git status --short` in the remote worktree does not
-   show `.orca/`.
-11. Windows client dropping `my file's $draft.txt` into a Linux SSH worktree
-   pastes a POSIX-escaped remote path, not Windows double-quoted syntax.
-   Expected output for remote path `/home/u/wt/.orca/drops/my file's $draft.txt`:
-   `'/home/u/wt/.orca/drops/my file'\''s $draft.txt'` (literal `$draft`
-   inside single quotes — no expansion, no backslash-escaping).
-16. Local terminal drop on macOS / Linux / Windows clients behaves
-    byte-identically to pre-change: same injected string, no toast, no IPC
-    call. Run the existing `pane-helpers.test.ts` expectations through the
-    new `'posix' | 'windows'` API and confirm outputs match the legacy
-    userAgent-based outputs.
-17. File-explorer → terminal drop (`TerminalPane.tsx` onDrop) continues to
-    work on local and SSH worktrees exactly as today — this path is not
-    touched by the new IPC and must still use the explorer's own handling.
-12. Empty drop (`data.paths.length === 0`) → no IPC call, no toast, no
-   injection. (Possible on some OSes when a drag contains only non-file
-   items.)
-13. Store unhydrated (`getConnectionId` returns `undefined`) → user-visible
-   "Worktree not ready" toast, no injection, no IPC call. Not a silent
-   local fallback.
-14. Existing user-authored `.orca/.gitignore` with extra patterns → after
-   first SSH drop the file is unchanged (bootstrap writes only when
-   missing).
-15. Unit coverage:
-    - preload/API types expose `resolveDroppedPathsForAgent` and the
-      channel is registered in the preload `contextBridge` / IPC
-      allowlist (regression guard — easy to forget).
-    - main IPC covers: local passthrough, SSH success, partial failure
-      (order preserved), fresh-worktree staging bootstrap, bootstrap
-      preserves existing `.gitignore`, and disconnected SSH.
-    - terminal-pane coverage verifies the resolver is called once per
-      gesture, no path is injected until the promise resolves, and
-      `shellEscapePath` is called with `'posix'` for SSH drops regardless
-      of client userAgent.
-
-## Follow-ups
-
-File each of these as a GitHub issue before merging the implementation PR
-so "tracked as follow-up" is actually locatable. Inline the issue number
-next to each item once filed (e.g. `- GC drops dir (#1301)`), and update
-the GC paragraph in Non-goals to point to that issue directly.
-
-- GC `${worktreePath}/.orca/drops/` on worktree delete / disconnect.
-- `AbortController` plumbing so unmounting the terminal pane cancels the
-  in-flight SFTP upload (related to the pane-unmount guard added in the
-  renderer handler: today we no-op the injection, but the bytes still
-  transfer).
-- Drag-over affordance on the terminal pane (it has the
-  `data-native-file-drop-target="terminal"` marker but no hover style),
-  so users get feedback that dropping into the terminal is supported.
diff --git a/docs/terminal-extended-keys.md b/docs/terminal-extended-keys.md
deleted file mode 100644
index 7b4ea52a26c..00000000000
--- a/docs/terminal-extended-keys.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Extended Key Chords in the Terminal (Shift+Enter, etc.)
-
-## What Orca sends
-
-Orca's built‑in terminal already encodes extended key chords using the
-[kitty keyboard protocol][kitty] (CSI‑u). For example, **Shift+Enter** is sent
-as the byte sequence:
-
-```
-ESC [ 1 3 ; 2 u      (i.e. \x1b[13;2u)
-```
-
-See `src/renderer/src/components/terminal-pane/terminal-shortcut-policy.ts`
-for the full table.
-
-Orca also advertises kitty‑protocol support to the running program via
-`vtExtensions.kittyKeyboard` on xterm.js (see
-`src/renderer/src/lib/pane-manager/pane-terminal-options.ts`), so CLIs that
-probe with `CSI ? u` learn that the terminal speaks CSI‑u and enable their
-enhanced input handlers.
-
-## Why Shift+Enter may not reach your CLI inside tmux
-
-tmux, by default, strips both extended‑key encodings (modifyOtherKeys
-`CSI 27 ; 2 ; 13 ~` *and* kitty‑style `CSI 13 ; 2 u`). If you run Claude
-Code, Codex, or any other CLI under tmux, Shift+Enter will look like a
-plain `Enter` unless tmux is told to pass those bytes through.
-
-Add this to `~/.tmux.conf` (tmux 3.2+):
-
-```tmux
-set -s extended-keys on
-set -as terminal-features 'xterm*:extkeys'
-```
-
-Then reload: `tmux source-file ~/.tmux.conf` (or restart the tmux server).
-
-- `extended-keys on` — tell tmux to accept and forward the extended
-  encodings instead of collapsing them to the unshifted key.
-- `terminal-features 'xterm*:extkeys'` — tell tmux that the surrounding
-  terminal (Orca, in this case) understands those encodings, so tmux is
-  willing to emit them.
-
-## Verifying end‑to‑end
-
-Inside an Orca terminal (no tmux), run:
-
-```
-cat -v
-```
-
-Press **Shift+Enter**. You should see:
-
-```
-^[[13;2u
-```
-
-That's caret notation for `\x1b[13;2u` — the expected CSI‑u encoding. If
-you see `^M` (or a blank newline) instead, either the chord isn't reaching
-the terminal (check `keyboard-handlers.ts` / `terminal-shortcut-policy.ts`)
-or you're inside tmux without the config above.
-
-Inside tmux after the config, the same `cat -v` test should print the same
-`^[[13;2u`.
-
-[kitty]: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
diff --git a/mobile/README.md b/mobile/README.md
index 4d9181b161f..ff03e6b91e1 100644
--- a/mobile/README.md
+++ b/mobile/README.md
@@ -138,6 +138,37 @@ cd ..
 pnpm typecheck:node
 ```
 
+## Protocol Version Compatibility
+
+Mobile and desktop talk over a versioned protocol. Because mobile updates lag desktop by 24-48h via the App Store, both sides exchange version numbers on `status.get` so a genuinely incompatible combo can hard-block instead of silently misbehaving.
+
+Constants live in two files (Metro can't resolve outside `mobile/`):
+
+- `src/shared/protocol-version.ts` — `DESKTOP_PROTOCOL_VERSION`, `MIN_COMPATIBLE_MOBILE_VERSION`
+- `mobile/src/transport/protocol-version.ts` — `MOBILE_PROTOCOL_VERSION`, `MIN_COMPATIBLE_DESKTOP_VERSION`
+
+Today all four are set so `evaluateCompat` always returns `{ kind: 'ok' }` — nothing blocks. The wire format is in place to flip a switch when needed.
+
+### When to bump
+
+Bump `DESKTOP_PROTOCOL_VERSION` (and the mobile mirror `MOBILE_PROTOCOL_VERSION` when relevant) for **breaking** changes:
+
+- Removed RPC method or required parameter that mobile uses
+- Changed meaning (units, nullability) of an existing field mobile reads
+- Changed encryption, framing, or auth handshake
+
+Do **not** bump for additive changes:
+
+- New RPC methods
+- New optional fields on existing methods
+- New event types in `terminal.subscribe`
+
+Set `MIN_COMPATIBLE_MOBILE_VERSION` (kill-switch) when desktop ships a change that requires a minimum mobile version to function safely. Same for `MIN_COMPATIBLE_DESKTOP_VERSION` from the mobile side.
+
+When a verdict is `blocked`, `mobile/src/components/ProtocolBlockScreen.tsx` renders a screen pointing the user at either the App Store (mobile too old) or GitHub Releases (desktop too old).
+
+To exercise the block screen locally: set `MIN_COMPATIBLE_DESKTOP_VERSION = 999` in `mobile/src/transport/protocol-version.ts`, rebuild, pair to any desktop. Revert before merging.
+
 ## Mock Server
 
 Develop the mobile app without a running Orca desktop instance:
diff --git a/mobile/app.json b/mobile/app.json
index 25cc7cf02f6..e4a8ffd0b22 100644
--- a/mobile/app.json
+++ b/mobile/app.json
@@ -2,7 +2,7 @@
   "expo": {
     "name": "Orca",
     "slug": "orca-mobile",
-    "version": "0.0.1",
+    "version": "0.0.4",
     "orientation": "portrait",
     "icon": "./assets/icon.png",
     "userInterfaceStyle": "automatic",
@@ -14,14 +14,34 @@
       "backgroundColor": "#111111"
     },
     "ios": {
-      "supportsTablet": true,
+      "supportsTablet": false,
       "bundleIdentifier": "com.stably.orca.mobile",
-      "buildNumber": "2",
+      "buildNumber": "11",
       "infoPlist": {
         "NSLocalNetworkUsageDescription": "Orca connects to the desktop app on your local network.",
         "NSAppTransportSecurity": {
           "NSAllowsLocalNetworking": true
-        }
+        },
+        "ITSAppUsesNonExemptEncryption": false
+      },
+      "privacyManifests": {
+        "NSPrivacyTracking": false,
+        "NSPrivacyTrackingDomains": [],
+        "NSPrivacyCollectedDataTypes": [],
+        "NSPrivacyAccessedAPITypes": [
+          {
+            "NSPrivacyAccessedAPIType": "NSPrivacyAccessedAPICategoryUserDefaults",
+            "NSPrivacyAccessedAPITypeReasons": ["CA92.1"]
+          },
+          {
+            "NSPrivacyAccessedAPIType": "NSPrivacyAccessedAPICategoryFileTimestamp",
+            "NSPrivacyAccessedAPITypeReasons": ["C617.1"]
+          },
+          {
+            "NSPrivacyAccessedAPIType": "NSPrivacyAccessedAPICategorySystemBootTime",
+            "NSPrivacyAccessedAPITypeReasons": ["35F9.1"]
+          }
+        ]
       }
     },
     "android": {
@@ -45,7 +65,9 @@
       [
         "expo-camera",
         {
-          "cameraPermission": "Allow Orca to use the camera for QR code scanning."
+          "cameraPermission": "Allow Orca to use the camera for QR code scanning.",
+          "microphonePermission": false,
+          "recordAudioAndroid": false
         }
       ],
       [
diff --git a/mobile/app/_layout.tsx b/mobile/app/_layout.tsx
index 742addac1cb..5bfb54283e5 100644
--- a/mobile/app/_layout.tsx
+++ b/mobile/app/_layout.tsx
@@ -1,11 +1,13 @@
-import { useCallback } from 'react'
+import { useCallback, useEffect } from 'react'
 import { View, StyleSheet } from 'react-native'
-import { Stack } from 'expo-router'
+import { Stack, useRouter } from 'expo-router'
 import { StatusBar } from 'expo-status-bar'
 import * as SplashScreen from 'expo-splash-screen'
 import * as Notifications from 'expo-notifications'
+import * as Linking from 'expo-linking'
 import { colors } from '../src/theme/mobile-theme'
 import { OrcaLogo } from '../src/components/OrcaLogo'
+import { RpcClientProvider } from '../src/transport/client-context'
 
 // Why: keeps the native splash screen visible until the React tree is mounted
 // and ready to render. Without this the user sees a blank white/black frame
@@ -26,7 +28,49 @@ Notifications.setNotificationHandler({
   })
 })
 
+// Why: extract the path+payload that follows the orca://pair anchor so we
+// can route it to the confirm screen. Accept either a hash payload
+// (`orca://pair#<base64>`, the QR / shared form) or a query param
+// (`orca://pair?code=<...>`, future-proof for share sheets that strip
+// fragments).
+function extractPairCode(url: string): string | null {
+  if (!url.startsWith('orca://pair')) return null
+  const hashIndex = url.indexOf('#')
+  if (hashIndex !== -1) {
+    return url.slice(hashIndex + 1) || null
+  }
+  const queryIndex = url.indexOf('?')
+  if (queryIndex !== -1) {
+    const params = new URLSearchParams(url.slice(queryIndex + 1))
+    return params.get('code')
+  }
+  return null
+}
+
 export default function RootLayout() {
+  const router = useRouter()
+
+  // Why: route `orca://pair#<code>` deep links to the confirm screen so
+  // the same pairing flow runs whether the link arrived via QR scan,
+  // paste, AirDrop, Messages, or `xcrun simctl openurl`. getInitialURL
+  // covers cold-start (link tapped while app was closed); the listener
+  // covers warm-start (link tapped while app is in memory).
+  useEffect(() => {
+    function handleUrl(url: string) {
+      const code = extractPairCode(url)
+      if (code) {
+        router.push({ pathname: '/pair-confirm', params: { code } })
+      }
+    }
+
+    void Linking.getInitialURL().then((url) => {
+      if (url) handleUrl(url)
+    })
+
+    const sub = Linking.addEventListener('url', ({ url }) => handleUrl(url))
+    return () => sub.remove()
+  }, [router])
+
   // Why: hide the native splash only once the navigation Stack has been laid
   // out — this is the earliest moment the user will see actual app content.
   // Previously the splash hid when a placeholder View rendered, leaving a
@@ -36,32 +80,35 @@ export default function RootLayout() {
   }, [])
 
   return (
-    <View style={styles.root} onLayout={onNavigatorLayout}>
-      <StatusBar style="light" />
-      <Stack
-        screenOptions={{
-          headerStyle: { backgroundColor: colors.bgPanel },
-          headerTintColor: colors.textPrimary,
-          headerTitleStyle: { fontSize: 16, fontWeight: '600' },
-          contentStyle: { backgroundColor: colors.bgBase },
-          headerShadowVisible: false
-        }}
-      >
-        <Stack.Screen
-          name="index"
-          options={{
-            headerShown: false,
-            headerTitle: () => <OrcaLogo size={22} />
+    <RpcClientProvider>
+      <View style={styles.root} onLayout={onNavigatorLayout}>
+        <StatusBar style="light" />
+        <Stack
+          screenOptions={{
+            headerStyle: { backgroundColor: colors.bgPanel },
+            headerTintColor: colors.textPrimary,
+            headerTitleStyle: { fontSize: 16, fontWeight: '600' },
+            contentStyle: { backgroundColor: colors.bgBase },
+            headerShadowVisible: false
           }}
-        />
-        <Stack.Screen name="pair-scan" options={{ headerShown: false }} />
-        <Stack.Screen name="settings" options={{ headerShown: false }} />
-        <Stack.Screen name="notifications" options={{ headerShown: false }} />
-        <Stack.Screen name="troubleshoot" options={{ headerShown: false }} />
-        <Stack.Screen name="about" options={{ headerShown: false }} />
-        <Stack.Screen name="h" options={{ headerShown: false }} />
-      </Stack>
-    </View>
+        >
+          <Stack.Screen
+            name="index"
+            options={{
+              headerShown: false,
+              headerTitle: () => <OrcaLogo size={22} />
+            }}
+          />
+          <Stack.Screen name="pair-scan" options={{ headerShown: false }} />
+          <Stack.Screen name="pair-confirm" options={{ headerShown: false }} />
+          <Stack.Screen name="settings" options={{ headerShown: false }} />
+          <Stack.Screen name="notifications" options={{ headerShown: false }} />
+          <Stack.Screen name="troubleshoot" options={{ headerShown: false }} />
+          <Stack.Screen name="about" options={{ headerShown: false }} />
+          <Stack.Screen name="h" options={{ headerShown: false }} />
+        </Stack>
+      </View>
+    </RpcClientProvider>
   )
 }
 
diff --git a/mobile/app/about.tsx b/mobile/app/about.tsx
index 088c6da211f..70a1effa44b 100644
--- a/mobile/app/about.tsx
+++ b/mobile/app/about.tsx
@@ -1,11 +1,25 @@
-import { View, Text, StyleSheet, Pressable, Linking } from 'react-native'
+import { View, Text, StyleSheet, Pressable, Linking, Platform } from 'react-native'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useRouter } from 'expo-router'
 import { ChevronLeft, Globe } from 'lucide-react-native'
 import Svg, { Path } from 'react-native-svg'
+import Constants from 'expo-constants'
 import { OrcaLogo } from '../src/components/OrcaLogo'
 import { colors, spacing, typography } from '../src/theme/mobile-theme'
 
+// Why: read version + native build identifier from expo-constants at
+// runtime so the About screen never drifts out of sync with app.json.
+// nativeBuildVersion is iOS buildNumber on iOS and versionCode on
+// Android — different concepts, same role (monotonic native build id).
+function getVersionLabel(): string {
+  const version = Constants.expoConfig?.version ?? '?.?.?'
+  const build =
+    Platform.OS === 'ios'
+      ? Constants.expoConfig?.ios?.buildNumber
+      : String(Constants.expoConfig?.android?.versionCode ?? '')
+  return build ? `v${version} (${build})` : `v${version}`
+}
+
 function GithubIcon({ size = 16, color = colors.textSecondary }) {
   return (
     <Svg width={size} height={size} viewBox="0 0 24 24" fill={color}>
@@ -66,6 +80,8 @@ export default function AboutScreen() {
           <Text style={styles.rowValue}>@orca_build</Text>
         </Pressable>
       </View>
+
+      <Text style={styles.versionText}>{getVersionLabel()}</Text>
     </View>
   )
 }
@@ -141,5 +157,11 @@ const styles = StyleSheet.create({
     height: StyleSheet.hairlineWidth,
     backgroundColor: colors.borderSubtle,
     marginHorizontal: spacing.md
+  },
+  versionText: {
+    marginTop: spacing.lg,
+    textAlign: 'center',
+    fontSize: typography.metaSize,
+    color: colors.textMuted
   }
 })
diff --git a/mobile/app/h/[hostId]/accounts.tsx b/mobile/app/h/[hostId]/accounts.tsx
new file mode 100644
index 00000000000..24a555b7f2c
--- /dev/null
+++ b/mobile/app/h/[hostId]/accounts.tsx
@@ -0,0 +1,414 @@
+import { useEffect, useState, useCallback, useRef } from 'react'
+import {
+  View,
+  Text,
+  StyleSheet,
+  Pressable,
+  ScrollView,
+  ActivityIndicator,
+  RefreshControl,
+  Alert
+} from 'react-native'
+import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context'
+import { useLocalSearchParams, useRouter } from 'expo-router'
+import { ChevronLeft, Check, RefreshCw, User } from 'lucide-react-native'
+import type { RpcClient } from '../../../src/transport/rpc-client'
+import { loadHosts } from '../../../src/transport/host-store'
+import { useHostClient } from '../../../src/transport/client-context'
+import type { RpcSuccess } from '../../../src/transport/types'
+import { colors, spacing, typography, radii } from '../../../src/theme/mobile-theme'
+import { ClaudeIcon, OpenAIIcon } from '../../../src/components/AgentIcons'
+import {
+  type AccountsSnapshot,
+  type ProviderKey,
+  getActiveProviderRateLimits,
+  getInactiveProviderUsage,
+  UsageBar
+} from '../../../src/components/AccountUsage'
+
+export default function AccountsScreen() {
+  const router = useRouter()
+  const insets = useSafeAreaInsets()
+  const { hostId } = useLocalSearchParams<{ hostId: string }>()
+
+  // Why: shared client per host. See docs/mobile-shared-client-per-host.md.
+  const { client, state: connState } = useHostClient(hostId)
+  const [hostName, setHostName] = useState<string>('')
+  const [snapshot, setSnapshot] = useState<AccountsSnapshot | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [refreshing, setRefreshing] = useState(false)
+  const [busyAccountId, setBusyAccountId] = useState<string | null>(null)
+  const clientRef = useRef<RpcClient | null>(null)
+
+  useEffect(() => {
+    clientRef.current = client
+  }, [client])
+
+  useEffect(() => {
+    if (!hostId) return
+    let stale = false
+    void loadHosts().then((hosts) => {
+      if (stale) return
+      const host = hosts.find((h) => h.id === hostId)
+      if (!host) {
+        setError('Host not found')
+        return
+      }
+      setHostName(host.name)
+    })
+    return () => {
+      stale = true
+    }
+  }, [hostId])
+
+  // Why: subscribe to streaming snapshot updates so usage bars refresh in
+  // place when the desktop's rate-limit poll completes (every 5 min) or
+  // when the user switches accounts. Falls back to a one-shot accounts.list
+  // if the subscription stream errors.
+  useEffect(() => {
+    if (!client || connState !== 'connected') return
+    const unsubscribe = client.subscribe('accounts.subscribe', null, (payload) => {
+      if (!payload || typeof payload !== 'object') return
+      const evt = payload as { type?: string; snapshot?: AccountsSnapshot }
+      if ((evt.type === 'ready' || evt.type === 'snapshot') && evt.snapshot) {
+        setSnapshot(evt.snapshot)
+        setError(null)
+      }
+    })
+    return unsubscribe
+  }, [client, connState])
+
+  const refresh = useCallback(async () => {
+    if (!client) return
+    setRefreshing(true)
+    try {
+      const res = await client.sendRequest('accounts.list')
+      if (res.ok) {
+        setSnapshot((res as RpcSuccess).result as AccountsSnapshot)
+        setError(null)
+      } else {
+        setError(res.error.message)
+      }
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e))
+    } finally {
+      setRefreshing(false)
+    }
+  }, [client])
+
+  const selectAccount = useCallback(
+    async (provider: ProviderKey, accountId: string | null) => {
+      if (!client) return
+      setBusyAccountId(accountId ?? `${provider}:default`)
+      const method = provider === 'claude' ? 'accounts.selectClaude' : 'accounts.selectCodex'
+      try {
+        const res = await client.sendRequest(method, { accountId })
+        if (!res.ok) {
+          Alert.alert('Could not switch account', res.error.message)
+        } else {
+          // Why: optimistic refresh — the streaming subscription will also
+          // emit, but a one-shot keeps the UI responsive even if the stream
+          // is temporarily disconnected.
+          await refresh()
+        }
+      } catch (e) {
+        Alert.alert('Could not switch account', e instanceof Error ? e.message : String(e))
+      } finally {
+        setBusyAccountId(null)
+      }
+    },
+    [client, refresh]
+  )
+
+  const renderProviderSection = (provider: ProviderKey, title: string) => {
+    if (!snapshot) return null
+    const state = provider === 'claude' ? snapshot.claude : snapshot.codex
+    const activeUsage = getActiveProviderRateLimits(snapshot, provider)
+    const Icon = provider === 'claude' ? ClaudeIcon : OpenAIIcon
+    return (
+      <View style={styles.section}>
+        <View style={styles.sectionHeader}>
+          <Icon size={14} />
+          <Text style={styles.sectionHeading}>{title}</Text>
+        </View>
+        <View style={styles.card}>
+          {/* System default row */}
+          <Pressable
+            style={({ pressed }) => [styles.row, pressed && styles.rowPressed]}
+            onPress={() => selectAccount(provider, null)}
+            disabled={busyAccountId !== null || connState !== 'connected'}
+          >
+            <View style={styles.rowMain}>
+              <Text style={styles.rowTitle}>System default</Text>
+              <Text style={styles.rowSubtitle}>Use the agent's own login</Text>
+            </View>
+            <View style={styles.rowTrailing}>
+              {state.activeAccountId === null ? (
+                <Check size={16} color={colors.accentBlue} />
+              ) : busyAccountId === `${provider}:default` ? (
+                <ActivityIndicator size="small" color={colors.textSecondary} />
+              ) : null}
+            </View>
+          </Pressable>
+
+          {state.accounts.map((account) => {
+            const isActive = state.activeAccountId === account.id
+            const inactiveEntry = !isActive
+              ? getInactiveProviderUsage(snapshot, provider, account.id)
+              : null
+            const usage = isActive ? activeUsage : (inactiveEntry?.claude ?? null)
+            const isFetching =
+              (isActive && usage?.status === 'fetching') ||
+              (!isActive && inactiveEntry?.isFetching === true)
+            const session = usage?.session
+            const weekly = usage?.weekly
+            return (
+              <View key={account.id}>
+                <View style={styles.separator} />
+                <Pressable
+                  style={({ pressed }) => [styles.row, pressed && styles.rowPressed]}
+                  onPress={() => selectAccount(provider, account.id)}
+                  disabled={busyAccountId !== null || connState !== 'connected' || isActive}
+                >
+                  <View style={styles.rowMain}>
+                    <Text style={styles.rowTitle} numberOfLines={1}>
+                      {account.email}
+                    </Text>
+                    <View style={styles.usageRow}>
+                      <UsageBar
+                        label="5h"
+                        usedPercent={session?.usedPercent ?? null}
+                        unavailable={!session && !isFetching}
+                        loading={isFetching && !session}
+                      />
+                      <UsageBar
+                        label="7d"
+                        usedPercent={weekly?.usedPercent ?? null}
+                        unavailable={!weekly && !isFetching}
+                        loading={isFetching && !weekly}
+                      />
+                    </View>
+                    {usage?.error ? (
+                      <Text style={styles.errorText} numberOfLines={1}>
+                        {usage.error}
+                      </Text>
+                    ) : null}
+                  </View>
+                  <View style={styles.rowTrailing}>
+                    {isActive ? (
+                      <Check size={16} color={colors.accentBlue} />
+                    ) : busyAccountId === account.id ? (
+                      <ActivityIndicator size="small" color={colors.textSecondary} />
+                    ) : null}
+                  </View>
+                </Pressable>
+              </View>
+            )
+          })}
+        </View>
+      </View>
+    )
+  }
+
+  return (
+    <SafeAreaView style={styles.container} edges={['top']}>
+      <View style={styles.topRow}>
+        <Pressable style={styles.backButton} onPress={() => router.back()}>
+          <ChevronLeft size={22} color={colors.textPrimary} />
+        </Pressable>
+        <View style={styles.titleWrap}>
+          <Text style={styles.heading}>Accounts</Text>
+          {hostName ? (
+            <Text style={styles.subheading} numberOfLines={1}>
+              {hostName}
+            </Text>
+          ) : null}
+        </View>
+        <Pressable
+          style={styles.iconButton}
+          onPress={refresh}
+          disabled={!client || refreshing || connState !== 'connected'}
+        >
+          {refreshing ? (
+            <ActivityIndicator size="small" color={colors.textSecondary} />
+          ) : (
+            <RefreshCw size={18} color={colors.textSecondary} />
+          )}
+        </Pressable>
+      </View>
+
+      <ScrollView
+        contentContainerStyle={[styles.scroll, { paddingBottom: insets.bottom + spacing.xl }]}
+        refreshControl={
+          <RefreshControl
+            refreshing={refreshing}
+            onRefresh={refresh}
+            tintColor={colors.textSecondary}
+          />
+        }
+      >
+        {connState !== 'connected' && !snapshot ? (
+          <View style={styles.placeholder}>
+            <ActivityIndicator color={colors.textSecondary} />
+            <Text style={styles.placeholderText}>Connecting to {hostName || 'host'}…</Text>
+          </View>
+        ) : error && !snapshot ? (
+          <View style={styles.placeholder}>
+            <Text style={styles.errorText}>{error}</Text>
+          </View>
+        ) : !snapshot ? (
+          <View style={styles.placeholder}>
+            <ActivityIndicator color={colors.textSecondary} />
+            <Text style={styles.placeholderText}>Loading accounts…</Text>
+          </View>
+        ) : (
+          <>
+            {renderProviderSection('claude', 'Claude')}
+            {renderProviderSection('codex', 'Codex')}
+            <View style={styles.footerHint}>
+              <User size={14} color={colors.textMuted} />
+              <Text style={styles.footerHintText}>
+                Add or re-authenticate accounts from desktop Settings → Accounts.
+              </Text>
+            </View>
+          </>
+        )}
+      </ScrollView>
+    </SafeAreaView>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.bgBase
+  },
+  topRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: spacing.md,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    gap: spacing.sm
+  },
+  backButton: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  iconButton: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  titleWrap: {
+    flex: 1
+  },
+  heading: {
+    fontSize: 20,
+    fontWeight: '700',
+    color: colors.textPrimary
+  },
+  subheading: {
+    fontSize: typography.metaSize,
+    color: colors.textSecondary,
+    marginTop: 1
+  },
+  scroll: {
+    paddingHorizontal: spacing.lg,
+    paddingTop: spacing.sm
+  },
+  section: {
+    marginBottom: spacing.xl
+  },
+  sectionHeader: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm,
+    marginBottom: spacing.sm
+  },
+  sectionHeading: {
+    fontSize: typography.metaSize,
+    fontWeight: '600',
+    color: colors.textSecondary,
+    textTransform: 'uppercase',
+    letterSpacing: 0.5
+  },
+  card: {
+    backgroundColor: colors.bgPanel,
+    borderRadius: radii.card,
+    overflow: 'hidden'
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: spacing.md,
+    paddingHorizontal: spacing.md + 2
+  },
+  rowPressed: {
+    backgroundColor: colors.bgRaised
+  },
+  rowMain: {
+    flex: 1,
+    gap: 4
+  },
+  // Why: fixed-width trailing slot so the usage bars in `rowMain` keep the
+  // same width whether or not the row is currently selected (otherwise the
+  // checkmark on the active account squeezes the bars narrower than the
+  // inactive rows above/below it).
+  rowTrailing: {
+    width: 24,
+    alignItems: 'flex-end',
+    justifyContent: 'center',
+    marginLeft: spacing.sm
+  },
+  rowTitle: {
+    fontSize: typography.bodySize,
+    fontWeight: '500',
+    color: colors.textPrimary
+  },
+  rowSubtitle: {
+    fontSize: typography.metaSize,
+    color: colors.textSecondary
+  },
+  separator: {
+    height: StyleSheet.hairlineWidth,
+    backgroundColor: colors.borderSubtle,
+    marginHorizontal: spacing.md
+  },
+  usageRow: {
+    flexDirection: 'row',
+    gap: spacing.md,
+    marginTop: 4
+  },
+  errorText: {
+    fontSize: typography.metaSize,
+    color: colors.statusRed
+  },
+  placeholder: {
+    paddingVertical: spacing.xl * 2,
+    alignItems: 'center',
+    gap: spacing.sm
+  },
+  placeholderText: {
+    fontSize: typography.bodySize,
+    color: colors.textSecondary
+  },
+  footerHint: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: spacing.sm,
+    paddingHorizontal: spacing.sm,
+    paddingTop: spacing.sm
+  },
+  footerHintText: {
+    flex: 1,
+    fontSize: typography.metaSize,
+    color: colors.textMuted,
+    lineHeight: 18
+  }
+})
diff --git a/mobile/app/h/[hostId]/index.tsx b/mobile/app/h/[hostId]/index.tsx
index 72373333dd1..342077407d4 100644
--- a/mobile/app/h/[hostId]/index.tsx
+++ b/mobile/app/h/[hostId]/index.tsx
@@ -8,7 +8,7 @@ import {
   ActivityIndicator,
   TextInput
 } from 'react-native'
-import { SafeAreaView } from 'react-native-safe-area-context'
+import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useLocalSearchParams, useRouter } from 'expo-router'
 import {
   Search,
@@ -24,10 +24,17 @@ import {
   Plus,
   Moon,
   Filter,
-  Check
+  Check,
+  UserCircle
 } from 'lucide-react-native'
-import { connect, type RpcClient } from '../../../src/transport/rpc-client'
+import type { RpcClient } from '../../../src/transport/rpc-client'
 import { loadHosts, updateLastConnected, removeHost } from '../../../src/transport/host-store'
+import {
+  useHostClient,
+  useCloseHost,
+  useForceReconnect,
+  useReconnectAttempt
+} from '../../../src/transport/client-context'
 import type { ConnectionState, RpcSuccess } from '../../../src/transport/types'
 import { triggerMediumImpact } from '../../../src/platform/haptics'
 import { StatusDot } from '../../../src/components/StatusDot'
@@ -37,8 +44,10 @@ import { PickerModal, type PickerOption } from '../../../src/components/PickerMo
 import { ActionSheetContent } from '../../../src/components/ActionSheetModal'
 import { ConfirmModal } from '../../../src/components/ConfirmModal'
 import { BottomDrawer } from '../../../src/components/BottomDrawer'
+import { ProtocolBlockScreen } from '../../../src/components/ProtocolBlockScreen'
 import { getCachedWorktrees } from '../../../src/cache/worktree-cache'
-import { colors, spacing, typography } from '../../../src/theme/mobile-theme'
+import { colors, radii, spacing, typography } from '../../../src/theme/mobile-theme'
+import { evaluateCompat, type CompatVerdict } from '../../../src/transport/protocol-compat'
 import {
   loadPinnedIds,
   savePinnedIds,
@@ -46,11 +55,25 @@ import {
   savePreferences
 } from '../../../src/storage/preferences'
 
+// Why: locally-typed subset of the desktop's RuntimeStatus we read from
+// `status.get`. Only the version fields matter to mobile today; everything
+// else is opaque. Both fields are optional since pre-PR desktops won't
+// return them — the compat evaluator handles undefined gracefully.
+type DesktopStatus = {
+  protocolVersion?: number
+  minCompatibleMobileVersion?: number
+}
+
 type Worktree = {
   worktreeId: string
   repo: string
   branch: string
   displayName: string
+  // Why: on-disk worktree directory path. Needed by NewWorktreeModal so the
+  // marine-creature fallback dedupes against the actual filesystem basenames
+  // (matching the desktop's collision check), not against displayName which
+  // the user may have renamed.
+  path: string
   liveTerminalCount: number
   hasAttachedPty: boolean
   preview: string
@@ -79,6 +102,22 @@ const STATUS_LABELS: Record<ConnectionState, string> = {
   'auth-failed': 'Auth failed'
 }
 
+// Why: same threshold as the home screen — kicks the label from
+// "Reconnecting…" to "Can't connect" once the rpc-client has cycled enough
+// times to indicate a real problem (wrong port, server down, network change).
+const RECONNECT_FAILURE_THRESHOLD = 3
+
+function getStatusDisplay(
+  state: ConnectionState,
+  attempts: number
+): { label: string; isError: boolean } {
+  if (state === 'auth-failed') return { label: 'Auth failed', isError: true }
+  if (state === 'reconnecting' && attempts >= RECONNECT_FAILURE_THRESHOLD) {
+    return { label: "Can't connect", isError: true }
+  }
+  return { label: STATUS_LABELS[state], isError: false }
+}
+
 const SORT_OPTIONS: PickerOption<SortMode>[] = [
   { value: 'smart', label: 'Smart', subtitle: 'Unread and active first' },
   { value: 'name', label: 'Name', subtitle: 'Alphabetical by name' },
@@ -235,16 +274,22 @@ function buildSections(
 export default function HostScreen() {
   const { hostId, action } = useLocalSearchParams<{ hostId: string; action?: string }>()
   const router = useRouter()
+  const insets = useSafeAreaInsets()
   const [initialCache] = useState(() =>
     hostId ? (getCachedWorktrees(hostId) as Worktree[] | null) : null
   )
-  const [client, setClient] = useState<RpcClient | null>(null)
+  // Why: shared client per host owned by RpcClientProvider. See
+  // docs/mobile-shared-client-per-host.md.
+  const { client, state: connState } = useHostClient(hostId)
+  const reconnectAttempts = useReconnectAttempt(hostId)
   const clientRef = useRef<RpcClient | null>(null)
-  const [connState, setConnState] = useState<ConnectionState>('disconnected')
+  const closeHostClient = useCloseHost()
+  const forceReconnectHost = useForceReconnect()
   const [worktrees, setWorktrees] = useState<Worktree[]>(initialCache ?? [])
   const [worktreesLoaded, setWorktreesLoaded] = useState(initialCache != null)
   const [hostName, setHostName] = useState('')
   const [error, setError] = useState('')
+  const [compatVerdict, setCompatVerdict] = useState<CompatVerdict>({ kind: 'ok' })
   const [lastKnownWorktrees, setLastKnownWorktrees] = useState<Worktree[]>(initialCache ?? [])
   const [search, setSearch] = useState('')
   const [showSearch, setShowSearch] = useState(false)
@@ -296,14 +341,17 @@ export default function HostScreen() {
     }
   }, [hostId])
 
+  // Why: keep clientRef in sync so existing imperative call sites work
+  // unchanged. Also re-seed the cached worktree list on hostId change
+  // since the useState initializer only runs on first mount.
+  useEffect(() => {
+    clientRef.current = client
+  }, [client])
+
   useEffect(() => {
-    let disposed = false
-    let rpcClient: RpcClient | null = null
-    clientRef.current = null
-    setClient(null)
-    setConnState('connecting')
     setHostName('')
     setError('')
+    setCompatVerdict({ kind: 'ok' })
     // Why: re-seed from the current host's cache on every hostId change.
     // The useState initializer only runs on first mount, so if Expo Router
     // reuses this screen with a different hostId, we must reset here.
@@ -317,45 +365,20 @@ export default function HostScreen() {
       setWorktrees([])
       setLastKnownWorktrees([])
     }
-
-    // Why: defer the RPC connection until after the navigation animation
-    // completes. Without this, connect() and loadHosts() block the JS
-    // thread during mount, delaying the screen transition by ~200-400ms.
-    // With cached worktrees the user sees content instantly; the live
-    // connection starts once the animation settles.
-    const rafId = requestAnimationFrame(() => {
-      if (disposed) return
-      void (async () => {
-        const hosts = await loadHosts()
-        const host = hosts.find((h) => h.id === hostId)
-        if (!host || disposed) {
-          if (!host && !disposed) setError('Host not found')
-          return
-        }
-
-        rpcClient = connect(host.endpoint, host.deviceToken, host.publicKeyB64, (state) => {
-          if (!disposed) setConnState(state)
-        })
-        if (disposed) {
-          rpcClient.close()
-          rpcClient = null
-          return
-        }
-        setHostName(host.name)
-        clientRef.current = rpcClient
-        setClient(rpcClient)
-
-        await updateLastConnected(host.id)
-      })()
-    })
-
-    return () => {
-      disposed = true
-      cancelAnimationFrame(rafId)
-      rpcClient?.close()
-      if (clientRef.current === rpcClient) {
-        clientRef.current = null
+    if (!hostId) return
+    let stale = false
+    void loadHosts().then((hosts) => {
+      if (stale) return
+      const host = hosts.find((h) => h.id === hostId)
+      if (!host) {
+        setError('Host not found')
+        return
       }
+      setHostName(host.name)
+      void updateLastConnected(host.id)
+    })
+    return () => {
+      stale = true
     }
   }, [hostId])
 
@@ -413,6 +436,47 @@ export default function HostScreen() {
     }
   }, [connState, fetchWorktrees])
 
+  // Why: read desktop's protocol version from status.get on every connect
+  // and re-evaluate compatibility. If the desktop declares this mobile
+  // build too old (or vice versa via the local minimum), the host detail
+  // screen swaps to a hard-block screen instead of the worktree list.
+  // Today's compat constants are wide-open so this never blocks; the wire
+  // format is in place to flip a switch in a future release.
+  useEffect(() => {
+    if (connState !== 'connected' || !client) return
+    let cancelled = false
+    const requestClient = client
+    void (async () => {
+      try {
+        const response = await requestClient.sendRequest('status.get')
+        if (cancelled || clientRef.current !== requestClient) return
+        if (!response.ok) return
+        const status = (response as RpcSuccess).result as DesktopStatus
+        const verdict = evaluateCompat({
+          desktopProtocolVersion: status.protocolVersion,
+          desktopMinCompatibleMobileVersion: status.minCompatibleMobileVersion
+        })
+        setCompatVerdict(verdict)
+        if (verdict.kind === 'blocked') {
+          // Why: deterministic breadcrumb so support can confirm a block
+          // actually fired (vs a render bug). No PII — just version ints.
+          console.warn('[protocol-compat] blocked', {
+            reason: verdict.reason,
+            desktopVersion: verdict.desktopVersion,
+            requiredMobileVersion: verdict.requiredMobileVersion,
+            requiredDesktopVersion: verdict.requiredDesktopVersion
+          })
+        }
+      } catch {
+        // Why: rare path — sendRequest can throw on transport tear-down.
+        // Treat as transient; verdict stays at previous value.
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [connState, client])
+
   useEffect(() => {
     if (connState !== 'connected') return
     const interval = setInterval(() => {
@@ -492,9 +556,14 @@ export default function HostScreen() {
 
   const handleRemoveHost = useCallback(async () => {
     if (!hostId) return
+    // Why: close the shared client first so its WebSocket is gone before
+    // the host record disappears; otherwise the next loadHosts() the
+    // provider does (e.g. on remount) wouldn't find this host but the
+    // socket would still be open, leaking state.
+    closeHostClient(hostId)
     await removeHost(hostId)
     router.back()
-  }, [hostId, router])
+  }, [hostId, router, closeHostClient])
 
   const openWorktreeSession = useCallback(
     (item: Worktree) => {
@@ -625,6 +694,10 @@ export default function HostScreen() {
     )
   }
 
+  if (compatVerdict.kind === 'blocked') {
+    return <ProtocolBlockScreen verdict={compatVerdict} />
+  }
+
   return (
     <SafeAreaView style={styles.container} edges={['top']}>
       <View style={styles.topChrome}>
@@ -638,9 +711,27 @@ export default function HostScreen() {
               {hostName || 'Host'}
             </Text>
           </View>
-          {connState !== 'connected' && (
-            <Text style={styles.statusText}>{STATUS_LABELS[connState]}</Text>
-          )}
+          {connState !== 'connected' &&
+            (() => {
+              const status = getStatusDisplay(connState, reconnectAttempts)
+              const showReconnectButton = status.isError && hostId && connState !== 'auth-failed'
+              return (
+                <View style={styles.statusRow}>
+                  <Text style={[styles.statusText, status.isError && { color: colors.statusRed }]}>
+                    {status.label}
+                  </Text>
+                  {showReconnectButton && (
+                    <Pressable
+                      style={styles.reconnectButton}
+                      onPress={() => void forceReconnectHost(hostId!)}
+                      hitSlop={8}
+                    >
+                      <Text style={styles.reconnectButtonText}>Reconnect</Text>
+                    </Pressable>
+                  )}
+                </View>
+              )
+            })()}
         </View>
 
         {/* Filter/sort/group toolbar */}
@@ -676,6 +767,17 @@ export default function HostScreen() {
 
           <View style={styles.toolbarSpacer} />
 
+          <Pressable
+            style={styles.searchToggle}
+            onPress={() => router.push(`/h/${hostId}/accounts`)}
+            disabled={connState !== 'connected'}
+          >
+            <UserCircle
+              size={16}
+              color={connState === 'connected' ? colors.textSecondary : colors.textMuted}
+            />
+          </Pressable>
+
           <Pressable
             style={styles.newButton}
             onPress={() => setShowNewWorktree(true)}
@@ -764,7 +866,10 @@ export default function HostScreen() {
           sections={sections}
           keyExtractor={(w) => w.worktreeId}
           stickySectionHeadersEnabled={false}
-          contentContainerStyle={styles.list}
+          // Why: edge-to-edge — the list scrolls under the system nav bar
+          // while reserving insets.bottom keeps the last worktree row reachable
+          // above the Samsung 3-button nav / iOS home indicator.
+          contentContainerStyle={[styles.list, { paddingBottom: spacing.lg + insets.bottom }]}
           renderSectionHeader={({ section }) => {
             if (!section.title) return null
             const isCollapsed = collapsedGroups.has(section.title)
@@ -1016,6 +1121,7 @@ export default function HostScreen() {
       <NewWorktreeModal
         visible={showNewWorktree}
         client={client}
+        existingWorktreePaths={worktrees.map((w) => w.path)}
         onCreated={(worktreeId, worktreeName) => {
           void fetchWorktrees()
           const params = new URLSearchParams({ name: worktreeName, created: '1' })
@@ -1080,6 +1186,24 @@ const styles = StyleSheet.create({
     color: colors.textSecondary,
     fontSize: typography.metaSize
   },
+  statusRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm
+  },
+  reconnectButton: {
+    paddingVertical: 4,
+    paddingHorizontal: spacing.sm,
+    borderRadius: radii.button,
+    backgroundColor: colors.bgPanel,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle
+  },
+  reconnectButtonText: {
+    color: colors.textPrimary,
+    fontSize: typography.metaSize,
+    fontWeight: '600'
+  },
   authBanner: {
     backgroundColor: colors.bgPanel,
     paddingVertical: spacing.sm,
diff --git a/mobile/app/h/[hostId]/session/[worktreeId].tsx b/mobile/app/h/[hostId]/session/[worktreeId].tsx
index 320dcfadf2e..196a2f9fa6b 100644
--- a/mobile/app/h/[hostId]/session/[worktreeId].tsx
+++ b/mobile/app/h/[hostId]/session/[worktreeId].tsx
@@ -6,16 +6,18 @@ import {
   ScrollView,
   TextInput,
   Pressable,
-  KeyboardAvoidingView,
+  Keyboard,
   Platform,
-  ActivityIndicator
+  ActivityIndicator,
+  type KeyboardEvent
 } from 'react-native'
-import { SafeAreaView } from 'react-native-safe-area-context'
+import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useLocalSearchParams, useRouter } from 'expo-router'
 import AsyncStorage from '@react-native-async-storage/async-storage'
 import { ArrowUp, ChevronLeft, Monitor, Plus, Smartphone } from 'lucide-react-native'
-import { connect, type RpcClient } from '../../../../src/transport/rpc-client'
+import type { RpcClient } from '../../../../src/transport/rpc-client'
 import { loadHosts } from '../../../../src/transport/host-store'
+import { useHostClient } from '../../../../src/transport/client-context'
 import type { ConnectionState, RpcSuccess } from '../../../../src/transport/types'
 import { triggerMediumImpact } from '../../../../src/platform/haptics'
 import {
@@ -121,8 +123,10 @@ export default function SessionScreen() {
     created?: string
   }>()
   const router = useRouter()
-  const [client, setClient] = useState<RpcClient | null>(null)
-  const [connState, setConnState] = useState<ConnectionState>('disconnected')
+  const insets = useSafeAreaInsets()
+  // Why: shared client per host owned by RpcClientProvider. See
+  // docs/mobile-shared-client-per-host.md.
+  const { client, state: connState } = useHostClient(hostId)
   const [terminals, setTerminals] = useState<Terminal[]>([])
   const [terminalsLoaded, setTerminalsLoaded] = useState(false)
   const [input, setInput] = useState('')
@@ -134,6 +138,11 @@ export default function SessionScreen() {
   const [customKeys, setCustomKeys] = useState<CustomKey[]>([])
   const [showCustomKeyModal, setShowCustomKeyModal] = useState(false)
   const [deleteKeyTarget, setDeleteKeyTarget] = useState<CustomKey | null>(null)
+  // Why: in Expo SDK 55 edge-to-edge mode the OS does NOT resize the window when
+  // the IME opens — the keyboard draws on top of the app. We track the keyboard
+  // height ourselves and apply it as paddingBottom on the input/accessory area
+  // so the input lifts above the IME and the terminal flex container shrinks.
+  const [keyboardHeight, setKeyboardHeight] = useState(0)
   // Why: server-authoritative display mode per terminal. The runtime is the
   // single source of truth — this state is populated from subscribe responses.
   const [terminalModes, setTerminalModes] = useState<Map<string, MobileDisplayMode>>(new Map())
@@ -217,10 +226,6 @@ export default function SessionScreen() {
       const seq = (subscribeSeqRef.current.get(handle) ?? 0) + 1
       subscribeSeqRef.current.set(handle, seq)
 
-      console.log(
-        `[mobile-fit] subscribeToTerminal handle=${handle} seq=${seq} viewport=${viewportRef.current ? `${viewportRef.current.cols}x${viewportRef.current.rows}` : 'none'} measured=${viewportMeasuredRef.current}`
-      )
-
       // Why: server handles auto-fit on subscribe — no terminal.focus call needed.
       // The viewport is embedded in the subscribe params so the server resizes
       // the PTY before serializing scrollback. This eliminates the focus→safeFit
@@ -236,9 +241,6 @@ export default function SessionScreen() {
           if (subscribeSeqRef.current.get(handle) !== seq) return
           const data = result as Record<string, unknown>
           if (data.type === 'scrollback') {
-            console.log(
-              `[mobile-fit] scrollback handle=${handle} cols=${data.cols} rows=${data.rows} displayMode=${data.displayMode} hasSerialized=${!!data.serialized} alreadyInit=${initializedHandlesRef.current.has(handle)}`
-            )
             if (initializedHandlesRef.current.has(handle)) return
             const cols = (data.cols as number) || 80
             const rows = (data.rows as number) || 24
@@ -253,6 +255,14 @@ export default function SessionScreen() {
                 new Map(prev).set(handle, data.displayMode as MobileDisplayMode)
               )
             }
+            // Why: cold-start fit-to-screen guard. The first init() runs
+            // before xterm's DOM/canvas has fully laid out, so the
+            // applyFitScale that init queues internally can land while
+            // term.element.scrollWidth is still stale or zero — leaving
+            // the terminal un-zoomed until the user toggles the resize
+            // button. Re-fire resetZoom after a short delay so it runs
+            // against a settled DOM. Mirrors the 'resized' handler below.
+            setTimeout(() => getTerminalRef(handle)?.resetZoom(), 200)
             // Why: viewport measurement needs xterm to be initialized (cell
             // dimensions come from the renderer). On the first subscribe the
             // WebView hasn't loaded yet, so viewportRef is null and the server
@@ -275,9 +285,6 @@ export default function SessionScreen() {
           } else if (data.type === 'data') {
             getTerminalRef(handle)?.write(data.chunk as string)
           } else if (data.type === 'resized') {
-            console.log(
-              `[mobile-fit] resized handle=${handle} cols=${data.cols} rows=${data.rows} displayMode=${data.displayMode} reason=${(data as Record<string, unknown>).reason}`
-            )
             // Why: inline resize event — the server changed the PTY dimensions
             // (mode toggle or desktop restore). Reinitialize xterm at the new
             // dims with fresh scrollback. No resubscribe needed.
@@ -320,7 +327,15 @@ export default function SessionScreen() {
       const next: MobileDisplayMode = current === 'auto' || current === 'phone' ? 'desktop' : 'auto'
       toggleInFlightRef.current.add(handle)
       try {
-        await client.sendRequest('terminal.setDisplayMode', { terminal: handle, mode: next })
+        await client.sendRequest('terminal.setDisplayMode', {
+          terminal: handle,
+          mode: next,
+          // Why: presence-lock take-floor signal. Sending mode=auto/phone
+          // is a deliberate "I want to drive at phone dims" gesture.
+          ...(deviceTokenRef.current
+            ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } }
+            : {})
+        })
       } catch {
         // Mode change failed — server state unchanged, UI stays in sync.
       } finally {
@@ -343,9 +358,6 @@ export default function SessionScreen() {
         })
         if (response.ok) {
           const result = (response as RpcSuccess).result as { terminals: Terminal[] }
-          console.log(
-            `[mobile-fit] fetchTerminals count=${result.terminals.length} allowEmpty=${allowEmptyLoaded} activeHandle=${activeHandleRef.current} lastKnown=${lastKnownTerminalCountRef.current}`
-          )
 
           if (result.terminals.length === 0 && !allowEmptyLoaded) {
             return
@@ -357,9 +369,6 @@ export default function SessionScreen() {
           // rapid interactions while still allowing genuine cleanup.
           if (result.terminals.length === 0 && lastKnownTerminalCountRef.current > 0) {
             lastKnownTerminalCountRef.current = 0
-            console.log(
-              `[mobile-fit] fetchTerminals SKIP first empty — will clear on next fetch if still empty`
-            )
             return
           }
 
@@ -374,7 +383,19 @@ export default function SessionScreen() {
           lastKnownTerminalCountRef.current = result.terminals.length
           const current = activeHandleRef.current
 
-          setTerminals(result.terminals)
+          // Why: defense-in-depth dedupe. If the server ever returns a list
+          // with the same handle twice (race during rename/split, or stale
+          // process tracking), React would throw 'two children with same
+          // key' on render. Keep the first occurrence — list order matters
+          // for the tab strip, and createParams puts new tabs at the end.
+          const seen = new Set<string>()
+          const deduped = result.terminals.filter((t) => {
+            if (seen.has(t.handle)) return false
+            seen.add(t.handle)
+            return true
+          })
+
+          setTerminals(deduped)
           setTerminalsLoaded(true)
 
           if (!current || !result.terminals.some((t) => t.handle === current)) {
@@ -396,39 +417,124 @@ export default function SessionScreen() {
     [client, worktreeId, subscribeToTerminal, unsubscribeTerminal]
   )
 
+  // Why: keep clientRef in sync with the shared client from
+  // useHostClient() so the existing imperative call sites
+  // (clientRef.current.sendRequest...) keep working without churn.
   useEffect(() => {
-    let disposed = false
-    let rpcClient: RpcClient | null = null
-
-    void (async () => {
-      const hosts = await loadHosts()
-      const host = hosts.find((h) => h.id === hostId)
-      if (!host || disposed) return
-
-      deviceTokenRef.current = host.deviceToken
-      rpcClient = connect(host.endpoint, host.deviceToken, host.publicKeyB64, setConnState)
-      if (disposed) {
-        rpcClient.close()
-        return
-      }
-      setClient(rpcClient)
-      clientRef.current = rpcClient
-    })()
-
+    clientRef.current = client
     return () => {
-      disposed = true
       clearTerminalCache()
-      rpcClient?.close()
-      if (clientRef.current === rpcClient) {
-        clientRef.current = null
-      }
     }
-  }, [clearTerminalCache, hostId])
+  }, [client, clearTerminalCache])
+
+  // Why: deviceToken is read from host record so feature code can pass
+  // `client.id` on subscribe/send for driver-state-machine identity.
+  // The shared client itself stays alive across screens; we just need
+  // the token alongside the client.
+  useEffect(() => {
+    if (!hostId) return
+    let stale = false
+    void loadHosts().then((hosts) => {
+      if (stale) return
+      const host = hosts.find((h) => h.id === hostId)
+      if (host) deviceTokenRef.current = host.deviceToken
+    })
+    return () => {
+      stale = true
+    }
+  }, [hostId])
 
   useEffect(() => {
     void loadCustomKeys().then(setCustomKeys)
   }, [])
 
+  // Why: drive the bottom padding from the keyboard height (edge-to-edge mode
+  // doesn't resize the window) and refit xterm once the layout settles so the
+  // terminal grid matches the new visible area. iOS exposes 'will' events that
+  // animate in sync with the IME; Android only fires 'did' events reliably.
+  // Also drives re-measurement when other layout-affecting state changes
+  // (e.g. tab strip toggling visibility when the terminal count crosses
+  // 0↔1 — without this, a freshly-created 2nd tab subscribes with a
+  // stale viewport that doesn't account for the now-visible tab strip,
+  // and the server phone-fits to dims a few rows too tall).
+  const refitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const scheduleViewportRefit = useCallback(() => {
+    if (refitTimerRef.current) clearTimeout(refitTimerRef.current)
+    refitTimerRef.current = setTimeout(() => {
+      const handle = activeHandleRef.current
+      if (!handle) return
+      const ref = terminalRefs.current.get(handle)
+      if (!ref) return
+      void (async () => {
+        const dims = await ref.measureFitDimensions(terminalFrameHeightRef.current || undefined)
+        if (!dims) return
+        const prev = viewportRef.current
+        if (prev && prev.cols === dims.cols && prev.rows === dims.rows) return
+        viewportRef.current = dims
+        viewportMeasuredRef.current = true
+        // Why: prefer the in-place viewport update RPC over the legacy
+        // unsubscribe → subscribe cycle. This keeps the server-side
+        // mobile subscriber record alive (no driver=idle blip on the
+        // desktop banner; no false phone-fit baseline capture on the
+        // re-subscribe). See docs/mobile-presence-lock.md.
+        const rpc = clientRef.current
+        const deviceToken = deviceTokenRef.current
+        if (rpc && deviceToken) {
+          try {
+            const response = await rpc.sendRequest('terminal.updateViewport', {
+              terminal: handle,
+              client: { id: deviceToken, type: 'mobile' as const },
+              viewport: dims
+            })
+            if (response.ok) return
+          } catch {
+            // Fall through to legacy resubscribe.
+          }
+        }
+        unsubscribeTerminal(handle)
+        initializedHandlesRef.current.delete(handle)
+        subscribeToTerminal(handle)
+      })()
+    }, 150)
+  }, [subscribeToTerminal, unsubscribeTerminal])
+
+  useEffect(() => {
+    const onShow = (e: KeyboardEvent) => {
+      setKeyboardHeight(e.endCoordinates?.height ?? 0)
+      scheduleViewportRefit()
+    }
+    const onHide = () => {
+      setKeyboardHeight(0)
+      scheduleViewportRefit()
+    }
+    const showEvent = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow'
+    const hideEvent = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide'
+    const showSub = Keyboard.addListener(showEvent, onShow)
+    const hideSub = Keyboard.addListener(hideEvent, onHide)
+    return () => {
+      if (refitTimerRef.current) clearTimeout(refitTimerRef.current)
+      showSub.remove()
+      hideSub.remove()
+    }
+  }, [scheduleViewportRefit])
+
+  // Why: the tab strip is hidden when only one terminal exists and shown
+  // once a second is created. Crossing the 1↔2 boundary changes the
+  // visible terminal area by ~40px, so the cached viewport dims in
+  // viewportRef become stale. Mark the viewport as un-measured so the
+  // next subscribe path's self-correcting loop (init → measure →
+  // resubscribe-with-fresh-viewport, see the !viewportMeasuredRef branch
+  // above) re-runs against the new layout. Also schedule an explicit
+  // refit to cover the case where no new subscribe is happening.
+  const tabStripVisible = terminals.length > 1
+  const prevTabStripVisibleRef = useRef(tabStripVisible)
+  useEffect(() => {
+    if (prevTabStripVisibleRef.current === tabStripVisible) return
+    prevTabStripVisibleRef.current = tabStripVisible
+    viewportMeasuredRef.current = false
+    scheduleViewportRefit()
+  }, [tabStripVisible, scheduleViewportRefit])
+
   useEffect(() => {
     if (hostId && worktreeId) {
       void AsyncStorage.setItem(
@@ -519,9 +625,6 @@ export default function SessionScreen() {
   const switchTab = useCallback(
     (handle: string) => {
       const prev = activeHandleRef.current
-      console.log(
-        `[mobile-fit] switchTab prev=${prev} next=${handle} hasUnsub=${terminalUnsubsRef.current.has(handle)} hasRef=${!!terminalRefs.current.get(handle)}`
-      )
       activeHandleRef.current = handle
       setActiveHandle(handle)
       if (prev && prev !== handle) {
@@ -548,9 +651,6 @@ export default function SessionScreen() {
   const setTerminalWebViewRef = useCallback((handle: string, ref: TerminalWebViewHandle | null) => {
     if (ref) {
       terminalRefs.current.set(handle, ref)
-      console.log(
-        `[mobile-fit] setTerminalWebViewRef handle=${handle} isActive=${handle === activeHandleRef.current} webReady=${webReadyHandlesRef.current.has(handle)}`
-      )
     } else {
       terminalRefs.current.delete(handle)
     }
@@ -560,9 +660,6 @@ export default function SessionScreen() {
     (handle: string) => {
       const wasAlreadyReady = webReadyHandlesRef.current.has(handle)
       webReadyHandlesRef.current.add(handle)
-      console.log(
-        `[mobile-fit] handleTerminalWebReady handle=${handle} isActive=${handle === activeHandleRef.current} wasAlreadyReady=${wasAlreadyReady} wasInitialized=${initializedHandlesRef.current.has(handle)}`
-      )
       if (wasAlreadyReady && initializedHandlesRef.current.has(handle)) {
         // Why: the native WebView reloaded (Metro hot reload or Android
         // process churn). The old xterm buffer is gone, so force a fresh
@@ -599,7 +696,13 @@ export default function SessionScreen() {
       await client.sendRequest('terminal.send', {
         terminal: activeHandle,
         text,
-        enter: true
+        enter: true,
+        // Why: presence-lock take-floor signal. Identifies this phone as
+        // the active mobile actor so the runtime can resolve multi-mobile
+        // contention (most-recent-actor's viewport wins).
+        ...(deviceTokenRef.current
+          ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } }
+          : {})
       })
     } catch {
       setInput(text)
@@ -615,7 +718,10 @@ export default function SessionScreen() {
       await client.sendRequest('terminal.send', {
         terminal: activeHandle,
         text: bytes,
-        enter: false
+        enter: false,
+        ...(deviceTokenRef.current
+          ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } }
+          : {})
       })
     } catch {
       // Transient failure
@@ -645,10 +751,17 @@ export default function SessionScreen() {
         }
         activeHandleRef.current = created.handle
         setActiveHandle(created.handle)
-        setTerminals((prev) => [
-          ...prev,
-          { handle: created.handle, title: created.title || 'Terminal', isActive: true }
-        ])
+        setTerminals((prev) => {
+          // Why: guard against duplicates if a parallel fetchTerminals()
+          // already inserted this handle. Without this, React throws
+          // 'two children with the same key' when both the optimistic
+          // insert and a canonical refetch race during creation.
+          if (prev.some((t) => t.handle === created.handle)) return prev
+          return [
+            ...prev,
+            { handle: created.handle, title: created.title || 'Terminal', isActive: true }
+          ]
+        })
         subscribeToTerminal(created.handle)
         setTimeout(() => void fetchTerminals(), 500)
       } else {
@@ -733,13 +846,21 @@ export default function SessionScreen() {
           : `${terminals.length} terminals`
       : STATUS_LABELS[connState]
 
+  // Why: on Android (Samsung 3-button) the keyboard event reports only the IME
+  // height; the system nav bar sits below the keyboard and adds its own height
+  // on top, so we must add insets.bottom too or the input stays clipped behind
+  // the nav bar. On iOS the keyboard coordinates already include the home
+  // indicator region, so adding insets.bottom would double-count.
+  const bottomPadding =
+    keyboardHeight > 0
+      ? Platform.OS === 'ios'
+        ? keyboardHeight
+        : keyboardHeight + insets.bottom
+      : insets.bottom
+
   return (
     <View style={styles.container}>
-      <KeyboardAvoidingView
-        style={styles.kavInner}
-        behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
-        keyboardVerticalOffset={0}
-      >
+      <View style={styles.kavInner}>
         <SafeAreaView style={styles.sessionChrome} edges={['top']}>
           <View style={styles.sessionTopBar}>
             <Pressable
@@ -845,113 +966,120 @@ export default function SessionScreen() {
           </View>
         )}
 
-        {/* Accessory keys */}
-        <View style={styles.accessoryBar}>
-          <ScrollView
-            horizontal
-            showsHorizontalScrollIndicator={false}
-            contentContainerStyle={styles.accessoryContent}
-          >
-            <Pressable
-              style={({ pressed }) => [
-                styles.accessoryKey,
-                pressed && styles.accessoryKeyPressed,
-                !canSend && styles.accessoryKeyDisabled
-              ]}
-              disabled={!canSend}
-              onPress={() => {
-                if (activeHandle) {
-                  void toggleDisplayMode(activeHandle)
-                }
-              }}
-              accessibilityLabel={
-                isPhoneMode(activeHandle) ? 'Switch to desktop mode' : 'Switch to phone mode'
-              }
+        {/* Why: bottomPadding lifts the entire input region above the keyboard
+            (when shown) or above the system nav bar / home indicator (when hidden). */}
+        <View style={{ paddingBottom: bottomPadding }}>
+          {/* Accessory keys */}
+          <View style={styles.accessoryBar}>
+            <ScrollView
+              horizontal
+              showsHorizontalScrollIndicator={false}
+              contentContainerStyle={styles.accessoryContent}
             >
-              {isPhoneMode(activeHandle) ? (
-                <Monitor size={14} color={canSend ? colors.textSecondary : colors.textMuted} />
-              ) : (
-                <Smartphone size={14} color={canSend ? colors.textSecondary : colors.textMuted} />
-              )}
-            </Pressable>
-            {ACCESSORY_KEYS.map((key) => (
               <Pressable
-                key={key.label}
                 style={({ pressed }) => [
                   styles.accessoryKey,
                   pressed && styles.accessoryKeyPressed,
                   !canSend && styles.accessoryKeyDisabled
                 ]}
                 disabled={!canSend}
-                onPress={() => void handleAccessoryKey(key.bytes)}
-                accessibilityLabel={key.accessibilityLabel ?? `Send ${key.label}`}
-              >
-                <Text
-                  style={[styles.accessoryKeyText, !canSend && styles.accessoryKeyTextDisabled]}
-                >
-                  {key.label}
-                </Text>
-              </Pressable>
-            ))}
-            {customKeys.map((key) => (
-              <Pressable
-                key={key.id}
-                style={({ pressed }) => [
-                  styles.accessoryKey,
-                  styles.customAccessoryKey,
-                  pressed && styles.accessoryKeyPressed,
-                  !canSend && styles.accessoryKeyDisabled
-                ]}
-                disabled={!canSend}
-                onPress={() => void handleAccessoryKey(key.bytes)}
-                onLongPress={() => {
-                  triggerMediumImpact()
-                  setDeleteKeyTarget(key)
+                onPress={() => {
+                  if (activeHandle) {
+                    void toggleDisplayMode(activeHandle)
+                  }
                 }}
-                delayLongPress={400}
-                accessibilityLabel={`Send ${key.label}`}
+                accessibilityLabel={
+                  isPhoneMode(activeHandle) ? 'Switch to desktop mode' : 'Switch to phone mode'
+                }
               >
-                <Text
-                  style={[styles.accessoryKeyText, !canSend && styles.accessoryKeyTextDisabled]}
-                >
-                  {key.label}
-                </Text>
+                {isPhoneMode(activeHandle) ? (
+                  <Monitor size={14} color={canSend ? colors.textSecondary : colors.textMuted} />
+                ) : (
+                  <Smartphone size={14} color={canSend ? colors.textSecondary : colors.textMuted} />
+                )}
               </Pressable>
-            ))}
-            <Pressable
-              style={({ pressed }) => [styles.accessoryKey, pressed && styles.accessoryKeyPressed]}
-              onPress={() => setShowCustomKeyModal(true)}
-              accessibilityLabel="Add custom shortcut"
-            >
-              <Plus size={14} color={colors.textSecondary} strokeWidth={2.2} />
-            </Pressable>
-          </ScrollView>
-        </View>
+              {ACCESSORY_KEYS.map((key) => (
+                <Pressable
+                  key={key.label}
+                  style={({ pressed }) => [
+                    styles.accessoryKey,
+                    pressed && styles.accessoryKeyPressed,
+                    !canSend && styles.accessoryKeyDisabled
+                  ]}
+                  disabled={!canSend}
+                  onPress={() => void handleAccessoryKey(key.bytes)}
+                  accessibilityLabel={key.accessibilityLabel ?? `Send ${key.label}`}
+                >
+                  <Text
+                    style={[styles.accessoryKeyText, !canSend && styles.accessoryKeyTextDisabled]}
+                  >
+                    {key.label}
+                  </Text>
+                </Pressable>
+              ))}
+              {customKeys.map((key) => (
+                <Pressable
+                  key={key.id}
+                  style={({ pressed }) => [
+                    styles.accessoryKey,
+                    styles.customAccessoryKey,
+                    pressed && styles.accessoryKeyPressed,
+                    !canSend && styles.accessoryKeyDisabled
+                  ]}
+                  disabled={!canSend}
+                  onPress={() => void handleAccessoryKey(key.bytes)}
+                  onLongPress={() => {
+                    triggerMediumImpact()
+                    setDeleteKeyTarget(key)
+                  }}
+                  delayLongPress={400}
+                  accessibilityLabel={`Send ${key.label}`}
+                >
+                  <Text
+                    style={[styles.accessoryKeyText, !canSend && styles.accessoryKeyTextDisabled]}
+                  >
+                    {key.label}
+                  </Text>
+                </Pressable>
+              ))}
+              <Pressable
+                style={({ pressed }) => [
+                  styles.accessoryKey,
+                  pressed && styles.accessoryKeyPressed
+                ]}
+                onPress={() => setShowCustomKeyModal(true)}
+                accessibilityLabel="Add custom shortcut"
+              >
+                <Plus size={14} color={colors.textSecondary} strokeWidth={2.2} />
+              </Pressable>
+            </ScrollView>
+          </View>
 
-        {/* Input bar */}
-        <View style={styles.inputBar}>
-          <TextInput
-            style={styles.textInput}
-            value={input}
-            onChangeText={setInput}
-            placeholder="Type a command…"
-            placeholderTextColor={colors.textMuted}
-            autoCapitalize="none"
-            autoCorrect={false}
-            returnKeyType="send"
-            editable={canSend}
-            onSubmitEditing={() => void handleSend()}
-          />
-          <Pressable
-            style={[styles.sendButton, !canSend && styles.sendButtonDisabled]}
-            disabled={!canSend}
-            onPress={() => void handleSend()}
-            accessibilityLabel="Send command"
-          >
-            <ArrowUp size={18} color={colors.textSecondary} strokeWidth={2.5} />
-          </Pressable>
+          {/* Input bar */}
+          <View style={styles.inputBar}>
+            <TextInput
+              style={styles.textInput}
+              value={input}
+              onChangeText={setInput}
+              placeholder="Type a command…"
+              placeholderTextColor={colors.textMuted}
+              autoCapitalize="none"
+              autoCorrect={false}
+              returnKeyType="send"
+              editable={canSend}
+              onSubmitEditing={() => void handleSend()}
+            />
+            <Pressable
+              style={[styles.sendButton, !canSend && styles.sendButtonDisabled]}
+              disabled={!canSend}
+              onPress={() => void handleSend()}
+              accessibilityLabel="Send command"
+            >
+              <ArrowUp size={18} color={colors.textSecondary} strokeWidth={2.5} />
+            </Pressable>
+          </View>
         </View>
-      </KeyboardAvoidingView>
+      </View>
 
       <ActionSheetModal
         visible={actionTarget != null}
diff --git a/mobile/app/h/_layout.tsx b/mobile/app/h/_layout.tsx
index 59bbf7eeaf4..1bd3fec4185 100644
--- a/mobile/app/h/_layout.tsx
+++ b/mobile/app/h/_layout.tsx
@@ -10,6 +10,7 @@ export default function HostGroupLayout() {
       }}
     >
       <Stack.Screen name="[hostId]/index" options={{ title: 'Host' }} />
+      <Stack.Screen name="[hostId]/accounts" options={{ title: 'Accounts' }} />
       <Stack.Screen name="[hostId]/session/[worktreeId]" options={{ title: 'Terminal' }} />
     </Stack>
   )
diff --git a/mobile/app/index.tsx b/mobile/app/index.tsx
index 046e8ddb01a..c5c4579c620 100644
--- a/mobile/app/index.tsx
+++ b/mobile/app/index.tsx
@@ -1,6 +1,6 @@
 import { useState, useCallback, useEffect, useMemo, useRef } from 'react'
 import { View, Text, StyleSheet, Pressable, FlatList } from 'react-native'
-import { SafeAreaView } from 'react-native-safe-area-context'
+import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useRouter, useFocusEffect } from 'expo-router'
 import {
   Monitor,
@@ -11,19 +11,37 @@ import {
   GitPullRequest,
   ChevronRight,
   Terminal,
-  Plus
+  Plus,
+  RefreshCw,
+  PowerOff,
+  Edit3
 } from 'lucide-react-native'
+import { ClaudeIcon, OpenAIIcon } from '../src/components/AgentIcons'
+import {
+  type AccountsSnapshot,
+  type ProviderKey,
+  getActiveProviderRateLimits,
+  UsageBar
+} from '../src/components/AccountUsage'
 import AsyncStorage from '@react-native-async-storage/async-storage'
 import { loadHosts, removeHost, renameHost } from '../src/transport/host-store'
-import { connect, type RpcClient } from '../src/transport/rpc-client'
+import type { RpcClient } from '../src/transport/rpc-client'
+import {
+  useAllHostClients,
+  useCloseHost,
+  useForceReconnect,
+  usePrimeHosts
+} from '../src/transport/client-context'
 import { subscribeToDesktopNotifications } from '../src/notifications/mobile-notifications'
 import type { ConnectionState, HostProfile } from '../src/transport/types'
 import { triggerMediumImpact } from '../src/platform/haptics'
 import { OrcaLogo } from '../src/components/OrcaLogo'
+import { StatusDot } from '../src/components/StatusDot'
 import { TextInputModal } from '../src/components/TextInputModal'
-import { ActionSheetModal } from '../src/components/ActionSheetModal'
+import { ActionSheetModal, type ActionSheetAction } from '../src/components/ActionSheetModal'
 import { ConfirmModal } from '../src/components/ConfirmModal'
 import { setCachedWorktrees, getCachedWorktrees } from '../src/cache/worktree-cache'
+import { loadHomeSnapshot, saveHomeSnapshot } from '../src/cache/home-snapshot-cache'
 import { colors, spacing, radii } from '../src/theme/mobile-theme'
 
 function endpointLabel(endpoint: string): string {
@@ -44,6 +62,23 @@ const STATUS_LABELS: Record<ConnectionState, string> = {
   'auth-failed': 'Auth failed'
 }
 
+// Why: a few quick reconnects are normal (laptop wake, brief network blip).
+// After this many failed attempts in a row, the user almost certainly has
+// a real problem (wrong port, server down, network change), so escalate
+// the label and color so it's obvious something's wrong.
+const RECONNECT_FAILURE_THRESHOLD = 3
+
+function getStatusDisplay(
+  state: ConnectionState,
+  attempts: number
+): { label: string; isError: boolean } {
+  if (state === 'auth-failed') return { label: 'Auth failed', isError: true }
+  if (state === 'reconnecting' && attempts >= RECONNECT_FAILURE_THRESHOLD) {
+    return { label: "Can't connect", isError: true }
+  }
+  return { label: STATUS_LABELS[state], isError: false }
+}
+
 type StatsSummary = {
   totalAgentsSpawned: number
   totalPRsCreated: number
@@ -102,16 +137,24 @@ function fetchWorktreeInfo(
   ) => void,
   disposed: () => boolean
 ) {
-  const markLoaded = () => {
-    setInfo((prev) => ({
-      ...prev,
-      [hostId]: {
-        hostId,
-        totalWorktrees: 0,
-        activeCount: 0,
-        lastActiveWorktree: null
+  // Why: only seed an empty zeroed entry when this host has no prior info
+  // at all (e.g., first ever load before any cache hydration). On a
+  // transient failure for a host that already has cached data, leave the
+  // cached entry alone so the Resume card and host-meta line don't
+  // momentarily flip to "0 worktrees" / disappear during reconnects.
+  const markLoadedIfMissing = () => {
+    setInfo((prev) => {
+      if (prev[hostId]) return prev
+      return {
+        ...prev,
+        [hostId]: {
+          hostId,
+          totalWorktrees: 0,
+          activeCount: 0,
+          lastActiveWorktree: null
+        }
       }
-    }))
+    })
   }
 
   client
@@ -135,14 +178,34 @@ function fetchWorktreeInfo(
           }
         }))
       } else {
-        markLoaded()
+        markLoadedIfMissing()
       }
     })
     .catch(() => {
-      if (!disposed()) markLoaded()
+      if (!disposed()) markLoadedIfMissing()
     })
 }
 
+function fetchAccountsSnapshot(
+  client: RpcClient,
+  hostId: string,
+  setSnapshots: (
+    updater: (prev: Record<string, AccountsSnapshot>) => Record<string, AccountsSnapshot>
+  ) => void,
+  disposed: () => boolean
+) {
+  client
+    .sendRequest('accounts.list')
+    .then((response) => {
+      if (disposed()) return
+      if (response.ok) {
+        const snapshot = response.result as AccountsSnapshot
+        setSnapshots((prev) => ({ ...prev, [hostId]: snapshot }))
+      }
+    })
+    .catch(() => {})
+}
+
 // Why: repo names get a stable color derived from hashing, matching the
 // host detail page's colored dots for visual consistency.
 const REPO_COLORS = ['#8b5cf6', '#3b82f6', '#22c55e', '#f59e0b', '#ef4444', '#ec4899', '#06b6d4']
@@ -156,17 +219,83 @@ function repoColor(name: string): string {
 
 export default function HomeScreen() {
   const router = useRouter()
+  const insets = useSafeAreaInsets()
   const [hosts, setHosts] = useState<HostProfile[]>([])
   const [actionTarget, setActionTarget] = useState<HostProfile | null>(null)
   const [renameTarget, setRenameTarget] = useState<HostProfile | null>(null)
   const [confirmRemove, setConfirmRemove] = useState<HostProfile | null>(null)
   const [hostStates, setHostStates] = useState<Record<string, ConnectionState>>({})
+  const [hostAttempts, setHostAttempts] = useState<Record<string, number>>({})
   const [stats, setStats] = useState<StatsSummary | null>(null)
   const [worktreeInfo, setWorktreeInfo] = useState<Record<string, HostWorktreeInfo>>({})
+  const [accountsByHost, setAccountsByHost] = useState<Record<string, AccountsSnapshot>>({})
   const [lastVisited, setLastVisited] = useState<{ hostId: string; worktreeId: string } | null>(
     null
   )
-  const clientsRef = useRef<Array<{ hostId: string; client: RpcClient }>>([])
+
+  // Why: read shared clients from the per-host store. Replaces the prior
+  // pattern of opening N independent WebSockets here. See
+  // docs/mobile-shared-client-per-host.md.
+  const hostIds = useMemo(() => hosts.map((h) => h.id), [hosts])
+  const allClients = useAllHostClients(hostIds)
+  const closeHostClient = useCloseHost()
+  const forceReconnectHost = useForceReconnect()
+  const primeHosts = usePrimeHosts()
+  // Why: feed the loaded HostProfiles into the provider's prime cache as
+  // soon as we have them. This avoids a second Keychain pass inside
+  // openEntry on cold start (which serialised behind the first one and
+  // showed up as multi-second connect latency).
+  useEffect(() => {
+    if (hosts.length > 0) primeHosts(hosts)
+  }, [hosts, primeHosts])
+  const allClientsRef = useRef<Array<{ hostId: string; client: RpcClient }>>([])
+  useEffect(() => {
+    allClientsRef.current = allClients.map((entry) => ({
+      hostId: entry.hostId,
+      client: entry.client
+    }))
+  }, [allClients])
+
+  // Why: hydrate the home page from a persisted snapshot on cold-start so
+  // Resume + Account-usage cards paint immediately with last-known data
+  // instead of flashing empty for ~1s while the WebSocket reconnects.
+  // Stream/list responses overwrite this seed in place when they arrive.
+  const hydratedRef = useRef(false)
+  useEffect(() => {
+    if (hydratedRef.current) return
+    hydratedRef.current = true
+    let cancelled = false
+    void loadHomeSnapshot().then((snap) => {
+      if (cancelled || !snap) return
+      setWorktreeInfo((prev) => (Object.keys(prev).length > 0 ? prev : snap.worktreeInfo))
+      setAccountsByHost((prev) => (Object.keys(prev).length > 0 ? prev : snap.accountsByHost))
+      for (const [hostId, info] of Object.entries(snap.worktreeInfo)) {
+        const wt = info.lastActiveWorktree
+        if (wt) {
+          // Why: also seed the in-memory worktree cache so resumeWorktree's
+          // lastVisited fast-path can find the cached worktree object.
+          setCachedWorktrees(hostId, [wt])
+        }
+      }
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  // Why: persist the merged snapshot whenever either piece updates so the
+  // next cold-start has fresh seed data. The cache module debounces writes
+  // internally so a flurry of streamed updates doesn't hammer disk.
+  useEffect(() => {
+    if (Object.keys(worktreeInfo).length === 0 && Object.keys(accountsByHost).length === 0) {
+      return
+    }
+    saveHomeSnapshot({
+      worktreeInfo,
+      accountsByHost,
+      savedAt: Date.now()
+    })
+  }, [worktreeInfo, accountsByHost])
 
   useFocusEffect(
     useCallback(() => {
@@ -180,10 +309,11 @@ export default function HomeScreen() {
           setLastVisited(JSON.parse(raw))
         } catch {}
       })
-      for (const entry of clientsRef.current) {
+      for (const entry of allClientsRef.current) {
         if (entry.client.getState() === 'connected') {
           fetchStats(entry.client, setStats, () => stale)
           fetchWorktreeInfo(entry.client, entry.hostId, setWorktreeInfo, () => stale)
+          fetchAccountsSnapshot(entry.client, entry.hostId, setAccountsByHost, () => stale)
         }
       }
       return () => {
@@ -197,73 +327,143 @@ export default function HomeScreen() {
     [hosts]
   )
 
+  // Why: mirror per-host connection state into hostStates so existing
+  // render code (status dots, connecting indicators) keeps working.
   useEffect(() => {
-    let disposed = false
-    const notifCleanups: Array<() => void> = []
-    const entries = hosts.flatMap((host) => {
-      if (!host.publicKeyB64 || !host.deviceToken) {
-        setHostStates((prev) => ({ ...prev, [host.id]: 'auth-failed' }))
-        return []
+    setHostAttempts((prev) => {
+      const next: Record<string, number> = { ...prev }
+      let changed = false
+      for (const entry of allClients) {
+        const a = entry.client.getReconnectAttempt()
+        if (next[entry.hostId] !== a) {
+          next[entry.hostId] = a
+          changed = true
+        }
       }
-      setHostStates((prev) => ({
-        ...prev,
-        [host.id]: prev[host.id] ?? 'connecting'
-      }))
-      let client: ReturnType<typeof connect>
-      try {
-        client = connect(host.endpoint, host.deviceToken, host.publicKeyB64, (state) => {
-          if (disposed) return
-          setHostStates((prev) => ({ ...prev, [host.id]: state }))
-        })
-      } catch {
-        setHostStates((prev) => ({ ...prev, [host.id]: 'auth-failed' }))
-        return []
+      return changed ? next : prev
+    })
+    setHostStates((prev) => {
+      const next: Record<string, ConnectionState> = { ...prev }
+      let changed = false
+      const liveIds = new Set(allClients.map((e) => e.hostId))
+      for (const entry of allClients) {
+        if (next[entry.hostId] !== entry.state) {
+          next[entry.hostId] = entry.state
+          changed = true
+        }
       }
+      // Why: when a paired host disappears from allClients (because the
+      // user tapped Disconnect, or the host record was invalid) the card
+      // must reflect that. We only force-update hosts whose state was
+      // already tracked — otherwise the initial-acquire frame (entry not
+      // yet materialised) would briefly flip every host to 'disconnected'.
+      for (const host of hosts) {
+        if (liveIds.has(host.id)) continue
+        if (!host.publicKeyB64 || !host.deviceToken) {
+          if (next[host.id] !== 'auth-failed') {
+            next[host.id] = 'auth-failed'
+            changed = true
+          }
+          continue
+        }
+        const prevState = next[host.id]
+        if (prevState && prevState !== 'disconnected' && prevState !== 'auth-failed') {
+          next[host.id] = 'disconnected'
+          changed = true
+        }
+      }
+      // Drop entries for hosts we no longer track at all.
+      for (const id of Object.keys(next)) {
+        if (!liveIds.has(id) && hosts.some((h) => h.id === id) === false) {
+          delete next[id]
+          changed = true
+        }
+      }
+      return changed ? next : prev
+    })
+  }, [allClients, hosts])
 
+  // Why: per-host streaming subscriptions (notifications + accounts) and
+  // one-shot stats fetches when each host transitions to 'connected'.
+  // Runs once per (hostId, client) pair and tears down when that pair
+  // changes. The provider keeps the underlying socket open across
+  // resubscription cycles so this is cheap.
+  useEffect(() => {
+    const cleanups: Array<() => void> = []
+    for (const entry of allClients) {
       let unsubNotif: (() => void) | null = null
+      let unsubAccounts: (() => void) | null = null
       let statsFetched = false
-      const unsubState = client.onStateChange((state) => {
+      const wireUp = (state: ConnectionState) => {
         if (state === 'connected') {
           if (!unsubNotif) {
-            unsubNotif = subscribeToDesktopNotifications(client)
+            unsubNotif = subscribeToDesktopNotifications(entry.client)
+          }
+          if (!unsubAccounts) {
+            unsubAccounts = entry.client.subscribe('accounts.subscribe', null, (payload) => {
+              if (!payload || typeof payload !== 'object') return
+              const evt = payload as { type?: string; snapshot?: AccountsSnapshot }
+              if ((evt.type === 'ready' || evt.type === 'snapshot') && evt.snapshot) {
+                setAccountsByHost((prev) => ({ ...prev, [entry.hostId]: evt.snapshot! }))
+              }
+            })
           }
           if (!statsFetched) {
             statsFetched = true
-            fetchStats(client, setStats, () => disposed)
-            fetchWorktreeInfo(client, host.id, setWorktreeInfo, () => disposed)
+            fetchStats(entry.client, setStats, () => false)
+            fetchWorktreeInfo(entry.client, entry.hostId, setWorktreeInfo, () => false)
+          }
+        } else {
+          if (unsubNotif) {
+            unsubNotif()
+            unsubNotif = null
+          }
+          if (unsubAccounts) {
+            unsubAccounts()
+            unsubAccounts = null
           }
-        } else if (unsubNotif) {
-          unsubNotif()
-          unsubNotif = null
         }
-      })
-      notifCleanups.push(() => {
+      }
+      wireUp(entry.state)
+      const unsubState = entry.client.onStateChange(wireUp)
+      cleanups.push(() => {
         unsubState()
         unsubNotif?.()
+        unsubAccounts?.()
       })
-
-      return [{ hostId: host.id, client }]
-    })
-
-    clientsRef.current = entries
-
-    return () => {
-      disposed = true
-      clientsRef.current = []
-      for (const cleanup of notifCleanups) cleanup()
-      for (const entry of entries) entry.client.close()
     }
-  }, [hosts])
+    return () => {
+      for (const c of cleanups) c()
+    }
+    // Why: depend on the host-id set, not the whole allClients array, so
+    // resubscriptions don't fire on every render that produces a new
+    // array reference. Client identity is stable per hostId for the
+    // lifetime of the underlying transport.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    allClients
+      .map((e) => e.hostId)
+      .sort()
+      .join(',')
+  ])
 
   // Why: prefer the worktree the user last opened on this device so the
   // "Resume" card reflects their mobile session history, not just the
   // desktop's most-recently-outputting worktree.
+  // Why: rendering used to be gated on hostStates === 'connected', which
+  // caused the Resume card to vanish for ~1s on every cold-start /
+  // resume-from-background while the WebSocket reconnected, even though we
+  // had perfectly good cached worktree data. Now the card stays visible as
+  // long as we have a cached lastActiveWorktree for any known host; the
+  // tap target is still the same and a fresher snapshot from the live RPC
+  // overwrites the card's contents in place when it lands.
   const resumeWorktree = useMemo(() => {
-    if (lastVisited && hostStates[lastVisited.hostId] === 'connected') {
+    if (lastVisited && sortedHosts.some((h) => h.id === lastVisited.hostId)) {
       const cached = getCachedWorktrees(lastVisited.hostId) as WorktreeSummary[] | null
       const match = cached?.find((w) => w.worktreeId === lastVisited.worktreeId)
       if (match) return { hostId: lastVisited.hostId, worktree: match }
     }
+    // Prefer a currently-connected host's data when we have it.
     for (const host of sortedHosts) {
       if (hostStates[host.id] !== 'connected') continue
       const info = worktreeInfo[host.id]
@@ -271,6 +471,14 @@ export default function HomeScreen() {
         return { hostId: host.id, worktree: info.lastActiveWorktree }
       }
     }
+    // Fall back to whichever known host has cached data, regardless of
+    // current connection state.
+    for (const host of sortedHosts) {
+      const info = worktreeInfo[host.id]
+      if (info?.lastActiveWorktree) {
+        return { hostId: host.id, worktree: info.lastActiveWorktree }
+      }
+    }
     return null
   }, [sortedHosts, hostStates, worktreeInfo, lastVisited])
 
@@ -288,6 +496,23 @@ export default function HomeScreen() {
     [sortedHosts, hostStates, worktreeInfo]
   )
 
+  // Why: only show the Account usage section for hosts that have at least
+  // one Claude or Codex account configured. Render whenever cached data
+  // exists, regardless of current connection state, so the cards don't
+  // disappear for ~1s on resume while the WebSocket reconnects. Streamed
+  // updates from the live RPC overwrite the snapshot in place when ready.
+  const accountsHosts = useMemo(() => {
+    const items: Array<{ host: HostProfile; snapshot: AccountsSnapshot }> = []
+    for (const host of sortedHosts) {
+      const snap = accountsByHost[host.id]
+      if (!snap) continue
+      const hasClaude = snap.claude.accounts.length > 0
+      const hasCodex = snap.codex.accounts.length > 0
+      if (hasClaude || hasCodex) items.push({ host, snapshot: snap })
+    }
+    return items
+  }, [sortedHosts, hostStates, accountsByHost])
+
   async function handleRename(newName: string) {
     if (!renameTarget) return
     try {
@@ -302,6 +527,9 @@ export default function HomeScreen() {
   async function handleRemove() {
     if (!confirmRemove) return
     try {
+      // Why: close the shared client first so the WebSocket is gone
+      // before the host record disappears from loadHosts().
+      closeHostClient(confirmRemove.id)
       await removeHost(confirmRemove.id)
       setConfirmRemove(null)
       setHosts(await loadHosts())
@@ -330,16 +558,16 @@ export default function HomeScreen() {
 
       {hosts.length === 0 ? (
         /* ─── Empty state: onboarding ─── */
-        <View style={styles.emptyContainer}>
+        <View style={[styles.emptyContainer, { paddingBottom: insets.bottom }]}>
           <View style={styles.emptyHero}>
             <Text style={styles.emptyTitle}>Connect your desktop</Text>
             <Text style={styles.emptyBody}>
-              Pair with Orca on your computer to monitor worktrees, watch agents work, and manage
-              terminals — all from your phone.
+              Pair with Orca on your computer to check on your agents, jump into any terminal, and
+              drive work from your phone.
             </Text>
             <Pressable style={styles.primaryButton} onPress={() => router.push('/pair-scan')}>
               <QrCode size={17} color={colors.bgBase} />
-              <Text style={styles.primaryButtonText}>Scan Pairing Code</Text>
+              <Text style={styles.primaryButtonText}>Pair Desktop</Text>
             </Pressable>
           </View>
 
@@ -363,7 +591,10 @@ export default function HomeScreen() {
         <FlatList
           data={sortedHosts}
           keyExtractor={(h) => h.id}
-          contentContainerStyle={styles.list}
+          // Why: edge-to-edge — let the list scroll under the system nav bar
+          // but reserve insets.bottom so the last row stays reachable above
+          // the Samsung 3-button nav / iOS home indicator.
+          contentContainerStyle={[styles.list, { paddingBottom: spacing.xl + insets.bottom }]}
           ListHeaderComponent={
             <View>
               <View style={styles.hero}>
@@ -404,8 +635,10 @@ export default function HomeScreen() {
           ItemSeparatorComponent={CardGap}
           renderItem={({ item }) => {
             const state = hostStates[item.id] ?? 'connecting'
+            const attempts = hostAttempts[item.id] ?? 0
             const connected = state === 'connected'
             const info = worktreeInfo[item.id]
+            const status = getStatusDisplay(state, attempts)
             return (
               <Pressable
                 style={({ pressed }) => [styles.hostCard, pressed && styles.hostCardPressed]}
@@ -430,14 +663,11 @@ export default function HomeScreen() {
                     {item.name}
                   </Text>
                   <View style={styles.hostMeta}>
-                    <View
-                      style={[
-                        styles.statusDot,
-                        { backgroundColor: connected ? colors.statusGreen : colors.textMuted }
-                      ]}
-                    />
-                    <Text style={styles.hostMetaItem}>
-                      {STATUS_LABELS[state]}
+                    <StatusDot state={state} />
+                    <Text
+                      style={[styles.hostMetaItem, status.isError && { color: colors.statusRed }]}
+                    >
+                      {status.label}
                       {connected && info
                         ? ` · ${info.totalWorktrees} worktree${info.totalWorktrees !== 1 ? 's' : ''}${info.activeCount > 0 ? ` · ${info.activeCount} active` : ''}`
                         : ''}
@@ -499,6 +729,85 @@ export default function HomeScreen() {
                 </>
               ) : null}
 
+              {/* ─── Account usage ─── */}
+              {accountsHosts.length > 0 ? (
+                <>
+                  <Text style={[styles.sectionHeading, { marginTop: spacing.xl }]}>
+                    Account usage
+                  </Text>
+                  {accountsHosts.map(({ host, snapshot }) => {
+                    const claudeActiveId = snapshot.claude.activeAccountId
+                    const claudeActive =
+                      snapshot.claude.accounts.find((a) => a.id === claudeActiveId) ?? null
+                    const codexActiveId = snapshot.codex.activeAccountId
+                    const codexActive =
+                      snapshot.codex.accounts.find((a) => a.id === codexActiveId) ?? null
+                    const showHostName = accountsHosts.length > 1
+                    return (
+                      <Pressable
+                        key={host.id}
+                        style={({ pressed }) => [
+                          styles.accountsCard,
+                          pressed && styles.hostCardPressed
+                        ]}
+                        onPress={() => router.push(`/h/${host.id}/accounts`)}
+                      >
+                        {showHostName ? (
+                          <Text style={styles.accountsHostLabel} numberOfLines={1}>
+                            {host.name}
+                          </Text>
+                        ) : null}
+                        {(['claude', 'codex'] as ProviderKey[]).map((provider) => {
+                          const active = provider === 'claude' ? claudeActive : codexActive
+                          const accounts =
+                            provider === 'claude'
+                              ? snapshot.claude.accounts
+                              : snapshot.codex.accounts
+                          if (accounts.length === 0) return null
+                          const limits = getActiveProviderRateLimits(snapshot, provider)
+                          const isFetching =
+                            limits?.status === 'fetching' || limits?.status === 'idle'
+                          const unavailable =
+                            limits == null ||
+                            limits.status === 'unavailable' ||
+                            limits.status === 'error'
+                          return (
+                            <View key={provider} style={styles.accountsRow}>
+                              <View style={styles.accountsIcon}>
+                                {provider === 'claude' ? (
+                                  <ClaudeIcon size={18} />
+                                ) : (
+                                  <OpenAIIcon size={18} color={colors.textPrimary} />
+                                )}
+                              </View>
+                              <View style={styles.accountsInfo}>
+                                <Text style={styles.accountsEmail} numberOfLines={1}>
+                                  {active?.email ?? 'System default'}
+                                </Text>
+                                <View style={styles.accountsBars}>
+                                  <UsageBar
+                                    label="5h"
+                                    usedPercent={limits?.session?.usedPercent ?? null}
+                                    unavailable={unavailable}
+                                    loading={isFetching && limits?.session == null}
+                                  />
+                                  <UsageBar
+                                    label="7d"
+                                    usedPercent={limits?.weekly?.usedPercent ?? null}
+                                    unavailable={unavailable}
+                                    loading={isFetching && limits?.weekly == null}
+                                  />
+                                </View>
+                              </View>
+                            </View>
+                          )
+                        })}
+                      </Pressable>
+                    )
+                  })}
+                </>
+              ) : null}
+
               {/* ─── Quick actions ─── */}
               <Text style={[styles.sectionHeading, { marginTop: spacing.xl }]}>Quick Actions</Text>
               <View style={styles.quickActions}>
@@ -507,7 +816,7 @@ export default function HomeScreen() {
                   onPress={() => router.push('/pair-scan')}
                 >
                   <View style={styles.quickActionIcon}>
-                    <QrCode size={20} color={colors.textSecondary} />
+                    <QrCode size={16} color={colors.textSecondary} />
                   </View>
                   <Text style={styles.quickActionLabel}>Pair Desktop</Text>
                 </Pressable>
@@ -521,7 +830,7 @@ export default function HomeScreen() {
                   }}
                 >
                   <View style={styles.quickActionIcon}>
-                    <Plus size={20} color={colors.textSecondary} />
+                    <Plus size={16} color={colors.textSecondary} />
                   </View>
                   <Text style={styles.quickActionLabel}>New Worktree</Text>
                 </Pressable>
@@ -536,25 +845,52 @@ export default function HomeScreen() {
         visible={actionTarget != null}
         title={actionTarget?.name}
         message={actionTarget ? endpointLabel(actionTarget.endpoint) : undefined}
-        actions={[
-          {
-            label: 'Rename',
+        actions={(() => {
+          const host = actionTarget
+          if (!host) return []
+          const state = hostStates[host.id] ?? 'connecting'
+          const isLive =
+            state === 'connected' ||
+            state === 'connecting' ||
+            state === 'handshaking' ||
+            state === 'reconnecting'
+          const items: ActionSheetAction[] = []
+          items.push({
+            label: 'Reconnect',
+            icon: RefreshCw,
             onPress: () => {
-              const host = actionTarget
               setActionTarget(null)
-              if (host) setRenameTarget(host)
+              void forceReconnectHost(host.id)
             }
-          },
-          {
+          })
+          if (isLive) {
+            items.push({
+              label: 'Disconnect',
+              icon: PowerOff,
+              onPress: () => {
+                setActionTarget(null)
+                closeHostClient(host.id)
+              }
+            })
+          }
+          items.push({
+            label: 'Rename',
+            icon: Edit3,
+            onPress: () => {
+              setActionTarget(null)
+              setRenameTarget(host)
+            }
+          })
+          items.push({
             label: 'Remove',
             destructive: true,
             onPress: () => {
-              const host = actionTarget
               setActionTarget(null)
-              if (host) setConfirmRemove(host)
+              setConfirmRemove(host)
             }
-          }
-        ]}
+          })
+          return items
+        })()}
         onClose={() => setActionTarget(null)}
       />
 
@@ -663,20 +999,21 @@ const styles = StyleSheet.create({
     borderWidth: 1,
     borderColor: colors.borderSubtle,
     borderRadius: 10,
-    padding: spacing.md
+    paddingVertical: 10,
+    paddingHorizontal: spacing.md
   },
   statIcon: {
-    width: 30,
-    height: 30,
-    borderRadius: 7,
+    width: 26,
+    height: 26,
+    borderRadius: 6,
     backgroundColor: 'rgba(255,255,255,0.04)',
     alignItems: 'center',
     justifyContent: 'center',
-    marginBottom: 10
+    marginBottom: 6
   },
   statValue: {
     color: colors.textPrimary,
-    fontSize: 20,
+    fontSize: 18,
     fontWeight: '700',
     letterSpacing: -0.3
   },
@@ -684,7 +1021,7 @@ const styles = StyleSheet.create({
     color: colors.textMuted,
     fontSize: 11,
     fontWeight: '500',
-    marginTop: 3
+    marginTop: 2
   },
 
   /* ─── Section heading ─── */
@@ -813,6 +1150,53 @@ const styles = StyleSheet.create({
     flex: 1
   },
 
+  /* ─── Account usage ─── */
+  accountsCard: {
+    backgroundColor: colors.bgPanel,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    borderRadius: radii.card,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm + 2,
+    gap: spacing.sm,
+    marginBottom: spacing.sm
+  },
+  accountsHostLabel: {
+    fontSize: 11,
+    color: colors.textMuted,
+    fontWeight: '500',
+    textTransform: 'uppercase',
+    letterSpacing: 0.4
+  },
+  accountsRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm + 2
+  },
+  accountsIcon: {
+    width: 32,
+    height: 32,
+    borderRadius: 9,
+    backgroundColor: colors.bgRaised,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  accountsInfo: {
+    flex: 1,
+    minWidth: 0,
+    gap: 2
+  },
+  accountsEmail: {
+    fontSize: 13,
+    fontWeight: '600',
+    color: colors.textPrimary
+  },
+  accountsBars: {
+    flexDirection: 'row',
+    gap: spacing.md,
+    marginTop: 4
+  },
+
   /* ─── Skeleton ─── */
   skeletonBlock: {
     backgroundColor: colors.bgRaised,
@@ -832,18 +1216,20 @@ const styles = StyleSheet.create({
   },
   quickAction: {
     flex: 1,
+    flexDirection: 'row',
     backgroundColor: colors.bgPanel,
     borderWidth: 1,
     borderColor: colors.borderSubtle,
     borderRadius: radii.card,
-    padding: spacing.lg,
+    paddingVertical: 10,
+    paddingHorizontal: 12,
     alignItems: 'center',
     gap: 10
   },
   quickActionIcon: {
-    width: 40,
-    height: 40,
-    borderRadius: 12,
+    width: 28,
+    height: 28,
+    borderRadius: 9,
     backgroundColor: 'rgba(255,255,255,0.04)',
     alignItems: 'center',
     justifyContent: 'center'
@@ -851,8 +1237,7 @@ const styles = StyleSheet.create({
   quickActionLabel: {
     fontSize: 12,
     fontWeight: '600',
-    color: colors.textSecondary,
-    textAlign: 'center'
+    color: colors.textSecondary
   },
 
   /* ─── Empty state ─── */
diff --git a/mobile/app/notifications.tsx b/mobile/app/notifications.tsx
index 7b0fdf9cd43..f7922074d6e 100644
--- a/mobile/app/notifications.tsx
+++ b/mobile/app/notifications.tsx
@@ -1,5 +1,5 @@
-import { useState, useCallback } from 'react'
-import { View, Text, StyleSheet, Pressable, Switch } from 'react-native'
+import { useState, useCallback, useEffect } from 'react'
+import { AppState, Linking, View, Text, StyleSheet, Pressable, Switch } from 'react-native'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useRouter, useFocusEffect } from 'expo-router'
 import { ChevronLeft } from 'lucide-react-native'
@@ -8,28 +8,69 @@ import {
   loadPushNotificationsEnabled,
   savePushNotificationsEnabled
 } from '../src/storage/preferences'
-import { ensureNotificationPermissions } from '../src/notifications/mobile-notifications'
+import {
+  ensureNotificationPermissions,
+  getNotificationPermissionState,
+  type NotificationPermissionState
+} from '../src/notifications/mobile-notifications'
+
+const DEFAULT_PERMISSION_STATE: NotificationPermissionState = {
+  granted: false,
+  status: 'undetermined',
+  canAskAgain: true
+}
 
 export default function NotificationsScreen() {
   const router = useRouter()
   const insets = useSafeAreaInsets()
-  const [pushEnabled, setPushEnabled] = useState(true)
+  const [pushEnabled, setPushEnabled] = useState(false)
+  const [permissionState, setPermissionState] = useState(DEFAULT_PERMISSION_STATE)
+
+  const refreshSettings = useCallback(async () => {
+    const [enabled, permission] = await Promise.all([
+      loadPushNotificationsEnabled(),
+      getNotificationPermissionState()
+    ])
+    setPushEnabled(enabled)
+    setPermissionState(permission)
+  }, [])
 
   useFocusEffect(
     useCallback(() => {
-      void loadPushNotificationsEnabled().then(setPushEnabled)
-    }, [])
+      void refreshSettings()
+    }, [refreshSettings])
   )
 
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') {
+        void refreshSettings()
+      }
+    })
+    return () => subscription.remove()
+  }, [refreshSettings])
+
   const togglePush = async (value: boolean) => {
     if (value) {
       const granted = await ensureNotificationPermissions()
-      if (!granted) return
+      const permission = await getNotificationPermissionState()
+      setPermissionState(permission)
+      if (!granted) {
+        setPushEnabled(false)
+        await savePushNotificationsEnabled(false)
+        return
+      }
     }
     setPushEnabled(value)
     await savePushNotificationsEnabled(value)
   }
 
+  const switchEnabled = pushEnabled && permissionState.granted
+  const notificationsBlocked = permissionState.status === 'denied'
+  const hint = notificationsBlocked
+    ? 'Notifications are disabled in system settings.'
+    : 'Receive notifications when an agent task completes on your desktop.'
+
   return (
     <View style={[styles.container, { paddingTop: insets.top + spacing.sm }]}>
       <View style={styles.topRow}>
@@ -43,15 +84,25 @@ export default function NotificationsScreen() {
         <View style={styles.row}>
           <Text style={styles.rowLabel}>Push Notifications</Text>
           <Switch
-            value={pushEnabled}
+            value={switchEnabled}
+            disabled={notificationsBlocked}
             onValueChange={(v) => void togglePush(v)}
             trackColor={{ false: colors.bgRaised, true: colors.textSecondary }}
             thumbColor={colors.textPrimary}
           />
         </View>
-        <Text style={styles.hint}>
-          Receive notifications when an agent task completes on your desktop.
-        </Text>
+        <Text style={styles.hint}>{hint}</Text>
+        {notificationsBlocked && (
+          <Pressable
+            style={({ pressed }) => [
+              styles.settingsButton,
+              pressed && styles.settingsButtonPressed
+            ]}
+            onPress={() => void Linking.openSettings()}
+          >
+            <Text style={styles.settingsButtonText}>Open Settings</Text>
+          </Pressable>
+        )}
       </View>
     </View>
   )
@@ -105,5 +156,22 @@ const styles = StyleSheet.create({
     lineHeight: 18,
     paddingHorizontal: spacing.md + 2,
     paddingBottom: spacing.md
+  },
+  settingsButton: {
+    alignSelf: 'flex-start',
+    marginHorizontal: spacing.md + 2,
+    marginBottom: spacing.md,
+    paddingVertical: spacing.xs,
+    paddingHorizontal: spacing.sm,
+    borderRadius: 8,
+    backgroundColor: colors.bgRaised
+  },
+  settingsButtonPressed: {
+    opacity: 0.6
+  },
+  settingsButtonText: {
+    color: colors.textPrimary,
+    fontSize: typography.metaSize,
+    fontWeight: '600'
   }
 })
diff --git a/mobile/app/pair-confirm.tsx b/mobile/app/pair-confirm.tsx
new file mode 100644
index 00000000000..fefa84ee053
--- /dev/null
+++ b/mobile/app/pair-confirm.tsx
@@ -0,0 +1,212 @@
+import { useEffect, useState } from 'react'
+import { View, Text, StyleSheet, Pressable, ActivityIndicator } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+import { useLocalSearchParams, useRouter } from 'expo-router'
+import { ChevronLeft } from 'lucide-react-native'
+import { parsePairingCode } from '../src/transport/pairing'
+import { connect } from '../src/transport/rpc-client'
+import { saveHost, getNextHostName } from '../src/transport/host-store'
+import type { PairingOffer, RpcResponse } from '../src/transport/types'
+import { colors, spacing, radii, typography } from '../src/theme/mobile-theme'
+
+type Status = 'awaiting-confirm' | 'connecting' | 'error'
+
+export default function PairConfirmScreen() {
+  const router = useRouter()
+  const insets = useSafeAreaInsets()
+  const params = useLocalSearchParams<{ code?: string }>()
+  const [offer, setOffer] = useState<PairingOffer | null>(null)
+  const [status, setStatus] = useState<Status>('awaiting-confirm')
+  const [errorMessage, setErrorMessage] = useState('')
+
+  useEffect(() => {
+    if (!params.code) {
+      setStatus('error')
+      setErrorMessage('Missing pairing code')
+      return
+    }
+    const parsed = parsePairingCode(params.code)
+    if (!parsed) {
+      setStatus('error')
+      setErrorMessage('Not a valid pairing code')
+      return
+    }
+    setOffer(parsed)
+  }, [params.code])
+
+  async function confirm() {
+    if (!offer) return
+    setStatus('connecting')
+    let client: ReturnType<typeof connect> | null = null
+
+    // Why: split the try/catch around the network call vs the local save
+    // so a Keychain or AsyncStorage failure doesn't masquerade as a
+    // "Cannot connect" error.
+    let response: RpcResponse
+    try {
+      client = connect(offer.endpoint, offer.deviceToken, offer.publicKeyB64)
+      response = await client.sendRequest('status.get')
+      client.close()
+      client = null
+    } catch (err) {
+      console.warn('[pair-confirm] connect failed', err)
+      setStatus('error')
+      setErrorMessage('Cannot connect — check that your computer is on the same network')
+      client?.close()
+      return
+    }
+
+    if (!response.ok) {
+      setStatus('error')
+      setErrorMessage(
+        response.error.code === 'unauthorized'
+          ? 'Authentication failed — token may be expired'
+          : `Server error: ${response.error.message}`
+      )
+      return
+    }
+
+    try {
+      const hostId = `host-${Date.now()}`
+      const hostName = await getNextHostName()
+      await saveHost({
+        id: hostId,
+        name: hostName,
+        endpoint: offer.endpoint,
+        deviceToken: offer.deviceToken,
+        publicKeyB64: offer.publicKeyB64,
+        lastConnected: Date.now()
+      })
+      router.replace(`/h/${hostId}`)
+    } catch (err) {
+      console.warn('[pair-confirm] save failed', err)
+      setStatus('error')
+      setErrorMessage(
+        `Pairing succeeded but couldn't save the host: ${err instanceof Error ? err.message : String(err)}`
+      )
+    }
+  }
+
+  function cancel() {
+    router.replace('/')
+  }
+
+  const containerPadding = { paddingTop: insets.top + spacing.sm }
+
+  return (
+    <View style={[styles.container, containerPadding]}>
+      <Pressable style={styles.backButton} onPress={cancel}>
+        <ChevronLeft size={22} color={colors.textSecondary} />
+      </Pressable>
+
+      <View style={styles.content}>
+        {offer && status === 'awaiting-confirm' && (
+          <>
+            <Text style={styles.title}>Pair with this desktop?</Text>
+            <Text style={styles.subtitle}>
+              You opened a pairing link from your desktop. Confirm to add it to your hosts.
+            </Text>
+            <Pressable style={styles.primaryButton} onPress={() => void confirm()}>
+              <Text style={styles.primaryButtonText}>Pair</Text>
+            </Pressable>
+            <Pressable style={styles.secondaryButton} onPress={cancel}>
+              <Text style={styles.secondaryButtonText}>Cancel</Text>
+            </Pressable>
+          </>
+        )}
+
+        {status === 'connecting' && (
+          <>
+            <ActivityIndicator size="large" color={colors.textSecondary} />
+            <Text style={styles.connectingText}>Connecting…</Text>
+          </>
+        )}
+
+        {status === 'error' && (
+          <>
+            <Text style={styles.errorText}>{errorMessage}</Text>
+            <Pressable style={styles.primaryButton} onPress={cancel}>
+              <Text style={styles.primaryButtonText}>Back to home</Text>
+            </Pressable>
+          </>
+        )}
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.bgBase,
+    padding: spacing.lg
+  },
+  backButton: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginBottom: spacing.sm
+  },
+  content: {
+    flex: 1,
+    justifyContent: 'center',
+    paddingHorizontal: spacing.sm,
+    // Why: nudges the centered group slightly above the geometric
+    // middle so the eye reads it as visually centered above the home
+    // indicator / nav bar.
+    paddingBottom: spacing.xl * 2
+  },
+  title: {
+    fontSize: typography.titleSize,
+    fontWeight: '600',
+    color: colors.textPrimary,
+    marginBottom: spacing.sm,
+    textAlign: 'center'
+  },
+  subtitle: {
+    fontSize: typography.bodySize,
+    color: colors.textSecondary,
+    lineHeight: 20,
+    marginBottom: spacing.xl,
+    textAlign: 'center'
+  },
+  primaryButton: {
+    backgroundColor: colors.textPrimary,
+    paddingHorizontal: spacing.xl,
+    paddingVertical: spacing.sm + 2,
+    borderRadius: radii.button,
+    alignItems: 'center',
+    marginBottom: spacing.sm
+  },
+  primaryButtonText: {
+    color: colors.bgBase,
+    fontSize: typography.bodySize,
+    fontWeight: '600'
+  },
+  secondaryButton: {
+    paddingHorizontal: spacing.xl,
+    paddingVertical: spacing.sm + 2,
+    borderRadius: radii.button,
+    alignItems: 'center'
+  },
+  secondaryButtonText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    fontWeight: '500'
+  },
+  connectingText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    marginTop: spacing.lg,
+    textAlign: 'center'
+  },
+  errorText: {
+    color: colors.statusRed,
+    fontSize: typography.bodySize,
+    textAlign: 'center',
+    marginBottom: spacing.xl,
+    lineHeight: 20
+  }
+})
diff --git a/mobile/app/pair-scan.tsx b/mobile/app/pair-scan.tsx
index ca522e7ddae..734787400f2 100644
--- a/mobile/app/pair-scan.tsx
+++ b/mobile/app/pair-scan.tsx
@@ -1,14 +1,15 @@
 import { useState, useRef, useCallback } from 'react'
-import { View, Text, StyleSheet, Pressable, ActivityIndicator } from 'react-native'
+import { View, Text, StyleSheet, Pressable, ActivityIndicator, Linking } from 'react-native'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { CameraView, useCameraPermissions } from 'expo-camera'
 import { useRouter } from 'expo-router'
-import { ChevronLeft } from 'lucide-react-native'
-import { decodePairingUrl } from '../src/transport/pairing'
+import { ChevronLeft, Clipboard as ClipboardIcon, QrCode } from 'lucide-react-native'
+import { decodePairingUrl, parsePairingCode } from '../src/transport/pairing'
 import { connect } from '../src/transport/rpc-client'
 import { saveHost, getNextHostName } from '../src/transport/host-store'
-import type { PairingOffer } from '../src/transport/types'
+import type { PairingOffer, RpcResponse } from '../src/transport/types'
 import { colors, spacing, radii, typography } from '../src/theme/mobile-theme'
+import { TextInputModal } from '../src/components/TextInputModal'
 
 function Step({ number, text }: { number: number; text: string }) {
   return (
@@ -27,6 +28,7 @@ export default function PairScanScreen() {
   const [permission, requestPermission] = useCameraPermissions()
   const [status, setStatus] = useState<'scanning' | 'connecting' | 'error'>('scanning')
   const [errorMessage, setErrorMessage] = useState('')
+  const [pasteVisible, setPasteVisible] = useState(false)
   const processingRef = useRef(false)
 
   const handleBarCodeScanned = useCallback(
@@ -47,32 +49,61 @@ export default function PairScanScreen() {
     [router]
   )
 
+  const handlePasteSubmit = useCallback((input: string) => {
+    setPasteVisible(false)
+    if (processingRef.current) return
+    processingRef.current = true
+
+    const offer = parsePairingCode(input)
+    if (!offer) {
+      setStatus('error')
+      setErrorMessage('Not a valid pairing code — copy it from your computer and paste again')
+      processingRef.current = false
+      return
+    }
+
+    void testAndSave(offer)
+  }, [])
+
   async function testAndSave(offer: PairingOffer) {
     setStatus('connecting')
     let client: ReturnType<typeof connect> | null = null
 
+    // Why: split the try/catch around the network call vs the local save
+    // so a Keychain or AsyncStorage failure doesn't masquerade as a
+    // "Cannot connect — same network?" error. Pairing reached the
+    // desktop fine; the failure is local persistence.
+    let response: RpcResponse
     try {
       client = connect(offer.endpoint, offer.deviceToken, offer.publicKeyB64)
-      const response = await client.sendRequest('status.get')
+      response = await client.sendRequest('status.get')
       client.close()
       client = null
+    } catch (err) {
+      console.warn('[pair] connect failed', err)
+      setStatus('error')
+      setErrorMessage('Cannot connect — check that your computer is on the same network')
+      processingRef.current = false
+      client?.close()
+      return
+    }
 
-      if (!response.ok) {
-        if (response.error.code === 'unauthorized') {
-          setStatus('error')
-          setErrorMessage('Authentication failed — token may be expired')
-          processingRef.current = false
-          return
-        }
+    if (!response.ok) {
+      if (response.error.code === 'unauthorized') {
         setStatus('error')
-        setErrorMessage(`Server error: ${response.error.message}`)
+        setErrorMessage('Authentication failed — token may be expired')
         processingRef.current = false
         return
       }
+      setStatus('error')
+      setErrorMessage(`Server error: ${response.error.message}`)
+      processingRef.current = false
+      return
+    }
 
+    try {
       const hostId = `host-${Date.now()}`
       const hostName = await getNextHostName()
-
       await saveHost({
         id: hostId,
         name: hostName,
@@ -81,14 +112,14 @@ export default function PairScanScreen() {
         publicKeyB64: offer.publicKeyB64,
         lastConnected: Date.now()
       })
-
       router.replace(`/h/${hostId}`)
-    } catch {
+    } catch (err) {
+      console.warn('[pair] save failed', err)
       setStatus('error')
-      setErrorMessage('Cannot connect — check that your computer is on the same network')
+      setErrorMessage(
+        `Pairing succeeded but couldn't save the host: ${err instanceof Error ? err.message : String(err)}`
+      )
       processingRef.current = false
-    } finally {
-      client?.close()
     }
   }
 
@@ -98,7 +129,13 @@ export default function PairScanScreen() {
     processingRef.current = false
   }
 
-  const containerPadding = { paddingTop: insets.top + spacing.sm }
+  // Why: bottom inset accounts for Android 3-button nav bars and iOS
+  // home-indicator areas that would otherwise overlap the 'Or paste
+  // pairing code' button at the bottom of the scan screen.
+  const containerPadding = {
+    paddingTop: insets.top + spacing.sm,
+    paddingBottom: insets.bottom + spacing.sm
+  }
 
   if (!permission) {
     return (
@@ -109,20 +146,46 @@ export default function PairScanScreen() {
   }
 
   if (!permission.granted) {
+    const canAskAgain = permission.canAskAgain !== false
     return (
       <View style={[styles.container, containerPadding]}>
         <Pressable style={styles.backButton} onPress={() => router.back()}>
           <ChevronLeft size={22} color={colors.textSecondary} />
         </Pressable>
         <View style={styles.centered}>
-          <Text style={styles.title}>Camera Permission</Text>
-          <Text style={styles.subtitle}>
-            Orca needs camera access to scan the pairing QR code from your desktop.
+          <Text style={styles.title}>
+            {canAskAgain ? 'Pair with desktop' : 'Camera Access Disabled'}
           </Text>
-          <Pressable style={styles.primaryButton} onPress={requestPermission}>
-            <Text style={styles.primaryButtonText}>Grant Camera Access</Text>
+          <Text style={styles.subtitle}>
+            {canAskAgain
+              ? 'Scan the QR code from Orca on your desktop, or paste the pairing code instead.'
+              : 'Enable camera access in Settings, or paste the pairing code instead.'}
+          </Text>
+          <Pressable
+            style={styles.primaryButton}
+            onPress={canAskAgain ? requestPermission : () => void Linking.openSettings()}
+          >
+            {canAskAgain && <QrCode size={16} color={colors.bgBase} />}
+            <Text style={styles.primaryButtonText}>
+              {canAskAgain ? 'Continue' : 'Open Settings'}
+            </Text>
+          </Pressable>
+          <Pressable
+            style={({ pressed }) => [styles.pasteButton, pressed && styles.pasteButtonPressed]}
+            onPress={() => setPasteVisible(true)}
+          >
+            <ClipboardIcon size={16} color={colors.textSecondary} />
+            <Text style={styles.pasteButtonText}>Paste code instead</Text>
           </Pressable>
         </View>
+        <TextInputModal
+          visible={pasteVisible}
+          title="Paste pairing code"
+          message="Copy the code shown under the QR on your computer."
+          placeholder="orca://pair#... or paste the code"
+          onSubmit={handlePasteSubmit}
+          onCancel={() => setPasteVisible(false)}
+        />
       </View>
     )
   }
@@ -140,20 +203,37 @@ export default function PairScanScreen() {
       </View>
 
       {status === 'scanning' && (
-        <View style={styles.cameraWrap}>
-          <CameraView
-            style={styles.camera}
-            facing="back"
-            barcodeScannerSettings={{ barcodeTypes: ['qr'] }}
-            onBarcodeScanned={handleBarCodeScanned}
-          />
-          <View style={styles.reticle} pointerEvents="none">
-            <View style={[styles.corner, styles.cornerTL]} />
-            <View style={[styles.corner, styles.cornerTR]} />
-            <View style={[styles.corner, styles.cornerBL]} />
-            <View style={[styles.corner, styles.cornerBR]} />
-          </View>
-        </View>
+        <>
+          {/* Why: unmount the camera while the paste sheet is open. The
+              user has clearly chosen the paste path; keeping the camera
+              streaming behind a sheet wastes power and looks weird if
+              they cancel the sheet and the QR was scanned silently in
+              the meantime. */}
+          {!pasteVisible && (
+            <View style={styles.cameraWrap}>
+              <CameraView
+                style={styles.camera}
+                facing="back"
+                barcodeScannerSettings={{ barcodeTypes: ['qr'] }}
+                onBarcodeScanned={handleBarCodeScanned}
+              />
+              <View style={styles.reticle} pointerEvents="none">
+                <View style={[styles.corner, styles.cornerTL]} />
+                <View style={[styles.corner, styles.cornerTR]} />
+                <View style={[styles.corner, styles.cornerBL]} />
+                <View style={[styles.corner, styles.cornerBR]} />
+              </View>
+            </View>
+          )}
+          {pasteVisible && <View style={styles.cameraPlaceholder} />}
+          <Pressable
+            style={({ pressed }) => [styles.pasteButton, pressed && styles.pasteButtonPressed]}
+            onPress={() => setPasteVisible(true)}
+          >
+            <ClipboardIcon size={16} color={colors.textSecondary} />
+            <Text style={styles.pasteButtonText}>Or paste pairing code</Text>
+          </Pressable>
+        </>
       )}
 
       {status === 'connecting' && (
@@ -166,11 +246,34 @@ export default function PairScanScreen() {
       {status === 'error' && (
         <View style={styles.centered}>
           <Text style={styles.errorText}>{errorMessage}</Text>
-          <Pressable style={styles.primaryButton} onPress={retry}>
-            <Text style={styles.primaryButtonText}>Try Again</Text>
-          </Pressable>
+          <View style={styles.errorActions}>
+            <Pressable style={styles.primaryButton} onPress={retry}>
+              <Text style={styles.primaryButtonText}>Try Again</Text>
+            </Pressable>
+            <Pressable
+              style={({ pressed }) => [
+                styles.secondaryButton,
+                pressed && styles.pasteButtonPressed
+              ]}
+              onPress={() => {
+                retry()
+                setPasteVisible(true)
+              }}
+            >
+              <Text style={styles.secondaryButtonText}>Paste code instead</Text>
+            </Pressable>
+          </View>
         </View>
       )}
+
+      <TextInputModal
+        visible={pasteVisible}
+        title="Paste pairing code"
+        message="Copy the code shown under the QR on your computer."
+        placeholder="orca://pair#... or paste the code"
+        onSubmit={handlePasteSubmit}
+        onCancel={() => setPasteVisible(false)}
+      />
     </View>
   )
 }
@@ -221,6 +324,14 @@ const styles = StyleSheet.create({
     borderRadius: radii.camera,
     overflow: 'hidden'
   },
+  // Why: holds the layout slot while the camera is unmounted during
+  // paste, so the bottom action button doesn't snap up to fill the
+  // empty space.
+  cameraPlaceholder: {
+    flex: 1,
+    backgroundColor: colors.bgPanel,
+    borderRadius: radii.camera
+  },
   camera: {
     ...StyleSheet.absoluteFillObject
   },
@@ -275,6 +386,7 @@ const styles = StyleSheet.create({
     marginBottom: spacing.sm
   },
   subtitle: {
+    maxWidth: 310,
     fontSize: typography.bodySize,
     color: colors.textSecondary,
     textAlign: 'center',
@@ -294,6 +406,10 @@ const styles = StyleSheet.create({
     lineHeight: 20
   },
   primaryButton: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.xs,
     backgroundColor: colors.textPrimary,
     paddingHorizontal: spacing.xl,
     paddingVertical: spacing.sm + 2,
@@ -303,5 +419,36 @@ const styles = StyleSheet.create({
     color: colors.bgBase,
     fontSize: typography.bodySize,
     fontWeight: '600'
+  },
+  pasteButton: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.xs,
+    marginTop: spacing.md,
+    paddingVertical: spacing.sm,
+    borderRadius: radii.button
+  },
+  pasteButtonPressed: {
+    opacity: 0.6
+  },
+  pasteButtonText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    fontWeight: '500'
+  },
+  errorActions: {
+    alignItems: 'center',
+    gap: spacing.sm
+  },
+  secondaryButton: {
+    paddingHorizontal: spacing.xl,
+    paddingVertical: spacing.sm,
+    borderRadius: radii.button
+  },
+  secondaryButtonText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    fontWeight: '500'
   }
 })
diff --git a/mobile/app/settings.tsx b/mobile/app/settings.tsx
index 171bd004853..c0285de3696 100644
--- a/mobile/app/settings.tsx
+++ b/mobile/app/settings.tsx
@@ -1,7 +1,15 @@
-import { View, Text, StyleSheet, Pressable } from 'react-native'
+import { View, Text, StyleSheet, Pressable, Linking } from 'react-native'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useRouter } from 'expo-router'
-import { ChevronLeft, ChevronRight, Info, Bell, Wrench } from 'lucide-react-native'
+import {
+  ChevronLeft,
+  ChevronRight,
+  Info,
+  Bell,
+  Wrench,
+  Shield,
+  LifeBuoy
+} from 'lucide-react-native'
 import { colors, spacing, typography } from '../src/theme/mobile-theme'
 
 export default function SettingsScreen() {
@@ -45,6 +53,24 @@ export default function SettingsScreen() {
           <ChevronRight size={16} color={colors.textMuted} />
         </Pressable>
       </View>
+
+      <View style={[styles.section, styles.sectionSpacer]}>
+        <Pressable
+          style={({ pressed }) => [styles.row, pressed && styles.rowPressed]}
+          onPress={() => void Linking.openURL('https://www.onorca.dev/privacy')}
+        >
+          <Shield size={16} color={colors.textSecondary} />
+          <Text style={styles.rowLabel}>Privacy Policy</Text>
+        </Pressable>
+        <View style={styles.separator} />
+        <Pressable
+          style={({ pressed }) => [styles.row, pressed && styles.rowPressed]}
+          onPress={() => void Linking.openURL('https://github.com/stablyai/orca/issues')}
+        >
+          <LifeBuoy size={16} color={colors.textSecondary} />
+          <Text style={styles.rowLabel}>Support</Text>
+        </Pressable>
+      </View>
     </View>
   )
 }
@@ -78,6 +104,9 @@ const styles = StyleSheet.create({
     borderRadius: 12,
     overflow: 'hidden'
   },
+  sectionSpacer: {
+    marginTop: spacing.md
+  },
   row: {
     flexDirection: 'row',
     alignItems: 'center',
diff --git a/mobile/assets/icon.png b/mobile/assets/icon.png
index d056b1f01e9..96d88074a77 100644
Binary files a/mobile/assets/icon.png and b/mobile/assets/icon.png differ
diff --git a/mobile/package.json b/mobile/package.json
index 6006461c802..02fa1bf57d0 100644
--- a/mobile/package.json
+++ b/mobile/package.json
@@ -22,6 +22,7 @@
     "expo-linking": "^55.0.14",
     "expo-notifications": "^55.0.21",
     "expo-router": "^55.0.13",
+    "expo-secure-store": "^55.0.13",
     "expo-splash-screen": "^55.0.19",
     "expo-status-bar": "^55.0.5",
     "lucide-react-native": "^1.11.0",
diff --git a/mobile/pnpm-lock.yaml b/mobile/pnpm-lock.yaml
index 11f0e80157f..9a346120f2a 100644
--- a/mobile/pnpm-lock.yaml
+++ b/mobile/pnpm-lock.yaml
@@ -38,6 +38,9 @@ importers:
       expo-router:
         specifier: ^55.0.13
         version: 55.0.13(121105c3b042d5e83ab3c1d3b84ed55f)
+      expo-secure-store:
+        specifier: ^55.0.13
+        version: 55.0.13(expo@55.0.17)
       expo-splash-screen:
         specifier: ^55.0.19
         version: 55.0.19(expo@55.0.17)(typescript@5.9.3)
@@ -3234,6 +3237,11 @@ packages:
       react-server-dom-webpack:
         optional: true
 
+  expo-secure-store@55.0.13:
+    resolution: {integrity: sha512-I6r0JNO1Fd4o0Gu7Ixiic7s89lqgdUHq17uBH9y1f/AntoyKn71TdtYJH82RgfsBbu5qNVzrwImmvlANyOlITQ==}
+    peerDependencies:
+      expo: '*'
+
   expo-server@55.0.8:
     resolution: {integrity: sha512-AoV5TKuO4biSzrhe/OVLyInfTT0pV9/OOc/g/oVq5vmCjL8SaSYTkES8PLt+67Tm7VqX+Dn0+kSx1nQcjEKaPw==}
     engines: {node: '>=20.16.0'}
@@ -9565,6 +9573,10 @@ snapshots:
       - expo-font
       - supports-color
 
+  expo-secure-store@55.0.13(expo@55.0.17):
+    dependencies:
+      expo: 55.0.17(@babel/core@7.29.0)(@expo/dom-webview@55.0.5)(@expo/metro-runtime@55.0.10)(expo-router@55.0.13)(react-dom@19.2.5(react@19.2.0))(react-native-webview@13.16.1(react-native@0.83.6(@babel/core@7.29.0)(@react-native/metro-config@0.85.2(@babel/core@7.29.0))(@types/react@19.2.14)(react@19.2.0))(react@19.2.0))(react-native-worklets@0.7.4(@babel/core@7.29.0)(react-native@0.83.6(@babel/core@7.29.0)(@react-native/metro-config@0.85.2(@babel/core@7.29.0))(@types/react@19.2.14)(react@19.2.0))(react@19.2.0))(react-native@0.83.6(@babel/core@7.29.0)(@react-native/metro-config@0.85.2(@babel/core@7.29.0))(@types/react@19.2.14)(react@19.2.0))(react@19.2.0)(typescript@5.9.3)
+
   expo-server@55.0.8: {}
 
   expo-splash-screen@55.0.19(expo@55.0.17)(typescript@5.9.3):
diff --git a/mobile/src/cache/home-snapshot-cache.ts b/mobile/src/cache/home-snapshot-cache.ts
new file mode 100644
index 00000000000..57256be8ea0
--- /dev/null
+++ b/mobile/src/cache/home-snapshot-cache.ts
@@ -0,0 +1,66 @@
+// Why: persist the data needed to render the home page so cold-start /
+// resume-from-background paints instantly with the last known good
+// values, then updates in place when fresh RPC data arrives. Without
+// this, Resume and Account-usage cards flash empty for ~1s while the
+// WebSocket reconnects and the first responses come back.
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import type { AccountsSnapshot } from '../components/AccountUsage'
+
+const STORAGE_KEY = 'orca:home-snapshot:v1'
+
+type WorktreeSummary = {
+  worktreeId: string
+  repo: string
+  branch: string
+  displayName: string
+  liveTerminalCount: number
+  status?: 'working' | 'active' | 'permission' | 'done' | 'inactive'
+}
+
+type HostWorktreeInfo = {
+  hostId: string
+  totalWorktrees: number
+  activeCount: number
+  lastActiveWorktree: WorktreeSummary | null
+}
+
+export type HomeSnapshot = {
+  worktreeInfo: Record<string, HostWorktreeInfo>
+  accountsByHost: Record<string, AccountsSnapshot>
+  savedAt: number
+}
+
+let memoryCache: HomeSnapshot | null = null
+let writeTimer: ReturnType<typeof setTimeout> | null = null
+
+export async function loadHomeSnapshot(): Promise<HomeSnapshot | null> {
+  if (memoryCache) return memoryCache
+  try {
+    const raw = await AsyncStorage.getItem(STORAGE_KEY)
+    if (!raw) return null
+    const parsed = JSON.parse(raw) as HomeSnapshot
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      typeof parsed.worktreeInfo !== 'object' ||
+      typeof parsed.accountsByHost !== 'object'
+    ) {
+      return null
+    }
+    memoryCache = parsed
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+// Why: throttle writes so a flurry of streamed account-snapshot updates
+// (one per provider fetch finishing) doesn't hammer AsyncStorage.
+export function saveHomeSnapshot(snapshot: HomeSnapshot): void {
+  memoryCache = snapshot
+  if (writeTimer) clearTimeout(writeTimer)
+  writeTimer = setTimeout(() => {
+    writeTimer = null
+    void AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(snapshot)).catch(() => {})
+  }, 250)
+}
diff --git a/mobile/src/components/AccountUsage.tsx b/mobile/src/components/AccountUsage.tsx
new file mode 100644
index 00000000000..0ff706638b9
--- /dev/null
+++ b/mobile/src/components/AccountUsage.tsx
@@ -0,0 +1,155 @@
+import { View, Text, StyleSheet, ActivityIndicator } from 'react-native'
+import { colors, spacing, typography } from '../theme/mobile-theme'
+
+// Why: keep these shapes in lockstep with src/shared/types.ts and
+// src/shared/rate-limit-types.ts. We don't import from desktop here because
+// the mobile bundle must not pull in Electron-coupled type files.
+export type RateLimitWindow = {
+  usedPercent: number
+  windowMinutes: number
+  resetsAt: number | null
+  resetDescription: string | null
+}
+
+export type ProviderRateLimits = {
+  provider: 'claude' | 'codex' | 'gemini' | 'opencode-go'
+  session: RateLimitWindow | null
+  weekly: RateLimitWindow | null
+  monthly?: RateLimitWindow | null
+  updatedAt: number
+  error: string | null
+  status: 'idle' | 'fetching' | 'ok' | 'error' | 'unavailable'
+}
+
+export type InactiveAccountUsage = {
+  accountId: string
+  claude: ProviderRateLimits | null
+  updatedAt: number
+  isFetching: boolean
+}
+
+export type ClaudeAccountSummary = {
+  id: string
+  email: string
+  organizationName?: string | null
+}
+
+export type CodexAccountSummary = {
+  id: string
+  email: string
+  workspaceLabel?: string | null
+}
+
+export type AccountsSnapshot = {
+  claude: { accounts: ClaudeAccountSummary[]; activeAccountId: string | null }
+  codex: { accounts: CodexAccountSummary[]; activeAccountId: string | null }
+  rateLimits: {
+    claude: ProviderRateLimits | null
+    codex: ProviderRateLimits | null
+    inactiveClaudeAccounts: InactiveAccountUsage[]
+    inactiveCodexAccounts: InactiveAccountUsage[]
+  }
+}
+
+export type ProviderKey = 'claude' | 'codex'
+
+export function getActiveProviderRateLimits(
+  snapshot: AccountsSnapshot,
+  provider: ProviderKey
+): ProviderRateLimits | null {
+  return provider === 'claude' ? snapshot.rateLimits.claude : snapshot.rateLimits.codex
+}
+
+export function getInactiveProviderUsage(
+  snapshot: AccountsSnapshot,
+  provider: ProviderKey,
+  accountId: string
+): InactiveAccountUsage | null {
+  const list =
+    provider === 'claude'
+      ? snapshot.rateLimits.inactiveClaudeAccounts
+      : snapshot.rateLimits.inactiveCodexAccounts
+  return list.find((u) => u.accountId === accountId) ?? null
+}
+
+// Why: matches desktop StatusBar convention — bars show percent remaining
+// (so a fresh account renders full, a depleted one renders empty), not
+// percent used. Color thresholds invert accordingly.
+export function UsageBar({
+  label,
+  usedPercent,
+  unavailable,
+  loading
+}: {
+  label: string
+  usedPercent: number | null
+  unavailable: boolean
+  loading?: boolean
+}) {
+  const remaining = usedPercent == null ? null : Math.max(0, Math.min(100, 100 - usedPercent))
+  const barColor =
+    remaining == null
+      ? colors.textMuted
+      : remaining <= 10
+        ? colors.statusRed
+        : remaining <= 30
+          ? colors.statusAmber
+          : colors.statusGreen
+  return (
+    <View style={styles.usageBar}>
+      <Text style={styles.usageLabel}>{label}</Text>
+      <View style={styles.usageTrack}>
+        <View
+          style={[
+            styles.usageFill,
+            {
+              width: `${remaining ?? 0}%`,
+              backgroundColor: unavailable ? colors.textMuted : barColor
+            }
+          ]}
+        />
+      </View>
+      {loading ? (
+        <ActivityIndicator size="small" color={colors.textSecondary} style={styles.usageSpinner} />
+      ) : (
+        <Text style={styles.usageValue}>
+          {unavailable || remaining == null ? '—' : `${Math.round(remaining)}%`}
+        </Text>
+      )}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  usageBar: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    flex: 1
+  },
+  usageLabel: {
+    fontSize: typography.metaSize,
+    color: colors.textMuted,
+    width: 22
+  },
+  usageTrack: {
+    flex: 1,
+    height: 6,
+    borderRadius: 3,
+    backgroundColor: colors.bgRaised,
+    overflow: 'hidden'
+  },
+  usageFill: {
+    height: '100%',
+    borderRadius: 3
+  },
+  usageValue: {
+    fontSize: typography.metaSize,
+    color: colors.textSecondary,
+    width: 36,
+    textAlign: 'right'
+  },
+  usageSpinner: {
+    width: 36
+  }
+})
diff --git a/mobile/src/components/AgentIcons.tsx b/mobile/src/components/AgentIcons.tsx
new file mode 100644
index 00000000000..714fe76e0f5
--- /dev/null
+++ b/mobile/src/components/AgentIcons.tsx
@@ -0,0 +1,30 @@
+import Svg, { Path } from 'react-native-svg'
+import { colors } from '../theme/mobile-theme'
+
+// Why: SVG paths sourced from the desktop codebase
+// (src/renderer/src/components/status-bar/icons.tsx) so mobile and desktop
+// stay visually identical for Claude/Codex branding.
+
+export function ClaudeIcon({ size = 16 }: { size?: number }) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24">
+      <Path
+        d="M4.709 15.955l4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 01-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312-.006.006z"
+        fill="#D97757"
+        fillRule="nonzero"
+      />
+    </Svg>
+  )
+}
+
+export function OpenAIIcon({ size = 16, color }: { size?: number; color?: string }) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24">
+      <Path
+        d="M9.205 8.658v-2.26c0-.19.072-.333.238-.428l4.543-2.616c.619-.357 1.356-.523 2.117-.523 2.854 0 4.662 2.212 4.662 4.566 0 .167 0 .357-.024.547l-4.71-2.759a.797.797 0 00-.856 0l-5.97 3.473zm10.609 8.8V12.06c0-.333-.143-.57-.429-.737l-5.97-3.473 1.95-1.118a.433.433 0 01.476 0l4.543 2.617c1.309.76 2.189 2.378 2.189 3.948 0 1.808-1.07 3.473-2.76 4.163zM7.802 12.703l-1.95-1.142c-.167-.095-.239-.238-.239-.428V5.899c0-2.545 1.95-4.472 4.591-4.472 1 0 1.927.333 2.712.928L8.23 5.067c-.285.166-.428.404-.428.737v6.898zM12 15.128l-2.795-1.57v-3.33L12 8.658l2.795 1.57v3.33L12 15.128zm1.796 7.23c-1 0-1.927-.332-2.712-.927l4.686-2.712c.285-.166.428-.404.428-.737v-6.898l1.974 1.142c.167.095.238.238.238.428v5.233c0 2.545-1.974 4.472-4.614 4.472zm-5.637-5.303l-4.544-2.617c-1.308-.761-2.188-2.378-2.188-3.948A4.482 4.482 0 014.21 6.327v5.423c0 .333.143.571.428.738l5.947 3.449-1.95 1.118a.432.432 0 01-.476 0zm-.262 3.9c-2.688 0-4.662-2.021-4.662-4.519 0-.19.024-.38.047-.57l4.686 2.71c.286.167.571.167.856 0l5.97-3.448v2.26c0 .19-.07.333-.237.428l-4.543 2.616c-.619.357-1.356.523-2.117.523zm5.899 2.83a5.947 5.947 0 005.827-4.756C22.287 18.339 24 15.84 24 13.296c0-1.665-.713-3.282-1.998-4.448.119-.5.19-.999.19-1.498 0-3.401-2.759-5.947-5.946-5.947-.642 0-1.26.095-1.88.31A5.962 5.962 0 0010.205 0a5.947 5.947 0 00-5.827 4.757C1.713 5.447 0 7.945 0 10.49c0 1.666.713 3.283 1.998 4.448-.119.5-.19 1-.19 1.499 0 3.401 2.759 5.946 5.946 5.946.642 0 1.26-.095 1.88-.309a5.96 5.96 0 004.162 1.713z"
+        fill={color ?? colors.textPrimary}
+        fillRule="evenodd"
+      />
+    </Svg>
+  )
+}
diff --git a/mobile/src/components/AgentSpinner.tsx b/mobile/src/components/AgentSpinner.tsx
index 734cb8bbc6d..673bbff049e 100644
--- a/mobile/src/components/AgentSpinner.tsx
+++ b/mobile/src/components/AgentSpinner.tsx
@@ -1,15 +1,20 @@
 import { useEffect, useRef } from 'react'
 import { Animated, Easing, StyleSheet, View } from 'react-native'
-import { colors } from '../theme/mobile-theme'
 
 type WorktreeStatus = 'working' | 'active' | 'permission' | 'done' | 'inactive'
 
+// Why: colors and sizing are 1:1 with the desktop StatusIndicator
+// (src/renderer/src/components/sidebar/StatusIndicator.tsx) so the mobile
+// worktree list reads identically to the sidebar — same yellow spinner for
+// 'working', same emerald dot for 'active'/'done', same neutral-500 @ 40%
+// for 'inactive', same red for 'permission'. Diverging palettes here lose
+// the design intent ('moving' vs 'alive' vs 'completed') the desktop encodes.
 const STATUS_COLORS: Record<WorktreeStatus, string> = {
-  working: colors.statusGreen,
-  active: colors.statusGreen,
-  permission: colors.statusRed,
-  done: '#38bdf8',
-  inactive: '#666666'
+  working: '#eab308',
+  active: '#10b981',
+  done: '#10b981',
+  permission: '#ef4444',
+  inactive: 'rgba(115,115,115,0.4)'
 }
 
 export function AgentSpinner({ status }: { status: WorktreeStatus }) {
@@ -39,23 +44,39 @@ export function AgentSpinner({ status }: { status: WorktreeStatus }) {
       outputRange: ['0deg', '360deg']
     })
     return (
-      <Animated.View style={[styles.spinner, { borderColor: color, transform: [{ rotate }] }]} />
+      <View style={styles.wrapper}>
+        <Animated.View style={[styles.spinner, { borderColor: color, transform: [{ rotate }] }]} />
+      </View>
     )
   }
 
-  return <View style={[styles.dot, { backgroundColor: color }]} />
+  return (
+    <View style={styles.wrapper}>
+      <View style={[styles.dot, { backgroundColor: color }]} />
+    </View>
+  )
 }
 
 const styles = StyleSheet.create({
+  // Why: 12x12 wrapper centered around an 8x8 inner glyph mirrors the
+  // desktop's `inline-flex h-3 w-3 ... items-center justify-center` shell
+  // around `size-2` indicator — keeps row height/baseline alignment stable
+  // across status transitions.
+  wrapper: {
+    width: 12,
+    height: 12,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
   dot: {
     width: 8,
     height: 8,
     borderRadius: 4
   },
   spinner: {
-    width: 10,
-    height: 10,
-    borderRadius: 5,
+    width: 8,
+    height: 8,
+    borderRadius: 4,
     borderWidth: 2,
     borderTopColor: 'transparent'
   }
diff --git a/mobile/src/components/NewWorktreeModal.tsx b/mobile/src/components/NewWorktreeModal.tsx
index 63d00cf8b0a..a7e7d2579b3 100644
--- a/mobile/src/components/NewWorktreeModal.tsx
+++ b/mobile/src/components/NewWorktreeModal.tsx
@@ -16,6 +16,8 @@ import type { RpcClient } from '../transport/rpc-client'
 import type { RpcSuccess } from '../transport/types'
 import { colors, spacing, radii, typography } from '../theme/mobile-theme'
 import { BottomDrawer } from './BottomDrawer'
+import { ClaudeIcon, OpenAIIcon } from './AgentIcons'
+import { getSuggestedCreatureName } from './worktree-name-suggestion'
 
 type Repo = {
   id: string
@@ -90,34 +92,10 @@ const AGENT_COMMANDS: Record<string, string> = {
 
 // ── Agent icons ─────────────────────────────────────────────────────
 // SVG paths sourced from the desktop codebase:
-//   Claude & OpenAI: src/renderer/src/components/status-bar/icons.tsx
+//   Claude & OpenAI: shared in ./AgentIcons.tsx
 //   Pi & Aider: src/renderer/src/lib/agent-catalog.tsx
 // Agents with a faviconDomain use Google's favicon service (same as desktop).
 
-function ClaudeIcon({ size = 16 }: { size?: number }) {
-  return (
-    <Svg width={size} height={size} viewBox="0 0 24 24">
-      <Path
-        d="M4.709 15.955l4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 01-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312-.006.006z"
-        fill="#D97757"
-        fillRule="nonzero"
-      />
-    </Svg>
-  )
-}
-
-function OpenAIIcon({ size = 16 }: { size?: number }) {
-  return (
-    <Svg width={size} height={size} viewBox="0 0 24 24">
-      <Path
-        d="M9.205 8.658v-2.26c0-.19.072-.333.238-.428l4.543-2.616c.619-.357 1.356-.523 2.117-.523 2.854 0 4.662 2.212 4.662 4.566 0 .167 0 .357-.024.547l-4.71-2.759a.797.797 0 00-.856 0l-5.97 3.473zm10.609 8.8V12.06c0-.333-.143-.57-.429-.737l-5.97-3.473 1.95-1.118a.433.433 0 01.476 0l4.543 2.617c1.309.76 2.189 2.378 2.189 3.948 0 1.808-1.07 3.473-2.76 4.163zM7.802 12.703l-1.95-1.142c-.167-.095-.239-.238-.239-.428V5.899c0-2.545 1.95-4.472 4.591-4.472 1 0 1.927.333 2.712.928L8.23 5.067c-.285.166-.428.404-.428.737v6.898zM12 15.128l-2.795-1.57v-3.33L12 8.658l2.795 1.57v3.33L12 15.128zm1.796 7.23c-1 0-1.927-.332-2.712-.927l4.686-2.712c.285-.166.428-.404.428-.737v-6.898l1.974 1.142c.167.095.238.238.238.428v5.233c0 2.545-1.974 4.472-4.614 4.472zm-5.637-5.303l-4.544-2.617c-1.308-.761-2.188-2.378-2.188-3.948A4.482 4.482 0 014.21 6.327v5.423c0 .333.143.571.428.738l5.947 3.449-1.95 1.118a.432.432 0 01-.476 0zm-.262 3.9c-2.688 0-4.662-2.021-4.662-4.519 0-.19.024-.38.047-.57l4.686 2.71c.286.167.571.167.856 0l5.97-3.448v2.26c0 .19-.07.333-.237.428l-4.543 2.616c-.619.357-1.356.523-2.117.523zm5.899 2.83a5.947 5.947 0 005.827-4.756C22.287 18.339 24 15.84 24 13.296c0-1.665-.713-3.282-1.998-4.448.119-.5.19-.999.19-1.498 0-3.401-2.759-5.947-5.946-5.947-.642 0-1.26.095-1.88.31A5.962 5.962 0 0010.205 0a5.947 5.947 0 00-5.827 4.757C1.713 5.447 0 7.945 0 10.49c0 1.666.713 3.283 1.998 4.448-.119.5-.19 1-.19 1.499 0 3.401 2.759 5.946 5.946 5.946.642 0 1.26-.095 1.88-.309a5.96 5.96 0 004.162 1.713z"
-        fill={colors.textPrimary}
-        fillRule="evenodd"
-      />
-    </Svg>
-  )
-}
-
 function PiIcon({ size = 16 }: { size?: number }) {
   return (
     <Svg width={size} height={size} viewBox="0 0 800 800">
@@ -248,11 +226,23 @@ function PickerListModal<T extends { id: string; label: string }>({
 type Props = {
   visible: boolean
   client: RpcClient | null
+  // Why: existing worktree paths from the host so we can pick a unique
+  // marine-creature default when the user leaves the name blank, matching
+  // the desktop UI's behavior. The "already exists locally" collision is
+  // on the on-disk directory basename, so paths (not displayNames) are
+  // what the suggestion logic must dedupe against.
+  existingWorktreePaths?: readonly string[]
   onCreated: (worktreeId: string, name: string) => void
   onClose: () => void
 }
 
-export function NewWorktreeModal({ visible, client, onCreated, onClose }: Props) {
+export function NewWorktreeModal({
+  visible,
+  client,
+  existingWorktreePaths,
+  onCreated,
+  onClose
+}: Props) {
   const [repos, setRepos] = useState<Repo[]>([])
   const [selectedRepo, setSelectedRepo] = useState<Repo | null>(null)
   const [showRepoPicker, setShowRepoPicker] = useState(false)
@@ -268,6 +258,12 @@ export function NewWorktreeModal({ visible, client, onCreated, onClose }: Props)
   const [error, setError] = useState('')
   const [loading, setLoading] = useState(true)
 
+  // Why: matches the desktop UI — the input shows a generic "Workspace name"
+  // placeholder, not the suggested creature. The creature name is only used
+  // as a server-bound fallback when the user submits with a blank field, so
+  // it's recomputed lazily inside handleCreate() to stay fresh against
+  // existingWorktreePaths at submission time.
+
   useEffect(() => {
     if (!visible) {
       setShowRepoPicker(false)
@@ -358,25 +354,57 @@ export function NewWorktreeModal({ visible, client, onCreated, onClose }: Props)
       const command =
         selectedAgent.id !== '__blank__' ? AGENT_COMMANDS[selectedAgent.id] : undefined
 
-      const params: Record<string, unknown> = {
-        repo: `id:${selectedRepo.id}`,
-        startupCommand: command,
-        setupDecision: runSetup ? 'inherit' : 'skip'
-      }
-      if (name.trim()) params.name = name.trim()
-      if (note.trim()) params.comment = note.trim()
+      // Why: blank name field — match desktop behavior by computing the
+      // next available marine-creature name at submit time and passing it
+      // to the server. The server's worktree.create rejects empty/invalid
+      // names, so we must generate one client-side rather than letting the
+      // server invent one. The pre-flight basename dedupe is only a hint;
+      // the authoritative collision is checked server-side against git
+      // branches/remotes/PRs, so we also retry-with-suffix on conflict.
+      const trimmedName = name.trim()
+      const baseName = trimmedName || getSuggestedCreatureName(existingWorktreePaths ?? [])
 
-      const response = await client.sendRequest('worktree.create', params)
+      // Why: mirrors src/renderer/src/store/slices/worktrees.ts
+      // (createWorktree retry loop). Server-side checks (Branch X already
+      // exists locally / on a remote / already has PR #N) can fire even
+      // after the pre-flight basename dedupe — branches outlive worktrees
+      // in git, and remote branches/PRs aren't visible from worktree.ps.
+      // Retry up to 25 times by appending -2, -3, ... before surfacing
+      // the error. The desktop applies this to user-typed names too, so
+      // mobile follows suit for parity.
+      const retryablePatterns = [
+        /already exists locally/i,
+        /already exists on a remote/i,
+        /already has pr #\d+/i
+      ]
+      const candidateFor = (attempt: number): string =>
+        attempt === 0 ? baseName : `${baseName}-${attempt + 1}`
 
-      if (response.ok) {
-        const result = (response as RpcSuccess).result as { worktree: { id: string } }
-        const worktreeId = result.worktree.id
+      let lastError: string | null = null
+      for (let attempt = 0; attempt < 25; attempt += 1) {
+        const candidateName = candidateFor(attempt)
+        const params: Record<string, unknown> = {
+          repo: `id:${selectedRepo.id}`,
+          startupCommand: command,
+          setupDecision: runSetup ? 'inherit' : 'skip',
+          name: candidateName
+        }
+        if (note.trim()) params.comment = note.trim()
 
-        onClose()
-        onCreated(worktreeId, name.trim() || 'New workspace')
-      } else {
-        setError(response.error.message)
+        const response = await client.sendRequest('worktree.create', params)
+        if (response.ok) {
+          const result = (response as RpcSuccess).result as { worktree: { id: string } }
+          onClose()
+          onCreated(result.worktree.id, candidateName)
+          return
+        }
+
+        lastError = response.error.message
+        if (!retryablePatterns.some((p) => p.test(lastError ?? ''))) {
+          break
+        }
       }
+      setError(lastError ?? 'Failed to create workspace')
     } catch (e) {
       setError(e instanceof Error ? e.message : 'Failed to create workspace')
     } finally {
diff --git a/mobile/src/components/ProtocolBlockScreen.tsx b/mobile/src/components/ProtocolBlockScreen.tsx
new file mode 100644
index 00000000000..368976676f1
--- /dev/null
+++ b/mobile/src/components/ProtocolBlockScreen.tsx
@@ -0,0 +1,105 @@
+import { Linking, Pressable, StyleSheet, Text, View } from 'react-native'
+import { router } from 'expo-router'
+import { colors, radii, spacing, typography } from '../theme/mobile-theme'
+import type { CompatVerdict } from '../transport/protocol-compat'
+import { MOBILE_PROTOCOL_VERSION } from '../transport/protocol-version'
+
+const RELEASES_URL = 'https://github.com/stablyai/orca/releases'
+
+type Props = {
+  verdict: Extract<CompatVerdict, { kind: 'blocked' }>
+}
+
+export function ProtocolBlockScreen({ verdict }: Props) {
+  const isMobileTooOld = verdict.reason === 'mobile-too-old'
+
+  const title = isMobileTooOld ? 'Update Orca Mobile' : 'Update Orca desktop'
+  const body = isMobileTooOld
+    ? `The Orca desktop on this host requires Orca Mobile v${verdict.requiredMobileVersion ?? '?'}+. You have v${MOBILE_PROTOCOL_VERSION}.\n\nUpdate Orca Mobile from the App Store to continue.`
+    : `Orca Mobile requires Orca desktop v${verdict.requiredDesktopVersion ?? '?'}+ to use this host. The desktop is reporting v${verdict.desktopVersion}.`
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.card}>
+        <Text style={styles.title}>{title}</Text>
+        <Text style={styles.body}>{body}</Text>
+        {/* Why: only desktop side has a deep-link target today —
+            App Store ID isn't published yet, so mobile-too-old is text-only. */}
+        {!isMobileTooOld ? (
+          <Pressable
+            style={({ pressed }) => [styles.primaryButton, pressed && styles.pressed]}
+            onPress={() => {
+              void Linking.openURL(RELEASES_URL)
+            }}
+          >
+            <Text style={styles.primaryButtonText}>Open GitHub Releases</Text>
+          </Pressable>
+        ) : null}
+        <Pressable
+          style={({ pressed }) => [styles.secondaryButton, pressed && styles.pressed]}
+          onPress={() => {
+            // Why: route back to the host list so the user can pair a
+            // different host instead of getting trapped on this screen.
+            router.replace('/')
+          }}
+        >
+          <Text style={styles.secondaryButtonText}>Pair a different host</Text>
+        </Pressable>
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.bgBase,
+    justifyContent: 'center',
+    paddingHorizontal: spacing.lg
+  },
+  card: {
+    backgroundColor: colors.bgPanel,
+    borderRadius: radii.card,
+    padding: spacing.lg,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle
+  },
+  title: {
+    fontSize: typography.titleSize,
+    fontWeight: '700',
+    color: colors.textPrimary,
+    marginBottom: spacing.sm
+  },
+  body: {
+    fontSize: typography.bodySize,
+    color: colors.textSecondary,
+    lineHeight: 20,
+    marginBottom: spacing.lg
+  },
+  primaryButton: {
+    backgroundColor: colors.textPrimary,
+    paddingVertical: spacing.sm + 2,
+    borderRadius: radii.button,
+    alignItems: 'center',
+    marginBottom: spacing.sm
+  },
+  primaryButtonText: {
+    fontSize: typography.bodySize,
+    fontWeight: '600',
+    color: colors.bgBase
+  },
+  secondaryButton: {
+    backgroundColor: colors.bgRaised,
+    paddingVertical: spacing.sm + 2,
+    borderRadius: radii.button,
+    alignItems: 'center'
+  },
+  secondaryButtonText: {
+    fontSize: typography.bodySize,
+    fontWeight: '600',
+    color: colors.textPrimary
+  },
+  pressed: {
+    opacity: 0.7
+  }
+})
diff --git a/mobile/src/components/StatusDot.tsx b/mobile/src/components/StatusDot.tsx
index 63777890d70..86f36f45033 100644
--- a/mobile/src/components/StatusDot.tsx
+++ b/mobile/src/components/StatusDot.tsx
@@ -7,7 +7,7 @@ const stateColors: Record<ConnectionState, string> = {
   connecting: colors.statusAmber,
   handshaking: colors.statusAmber,
   reconnecting: colors.statusAmber,
-  disconnected: colors.statusRed,
+  disconnected: colors.textMuted,
   'auth-failed': colors.statusRed
 }
 
diff --git a/mobile/src/components/TextInputModal.tsx b/mobile/src/components/TextInputModal.tsx
index 70a9f323f56..ae6f3ee3e7f 100644
--- a/mobile/src/components/TextInputModal.tsx
+++ b/mobile/src/components/TextInputModal.tsx
@@ -41,23 +41,19 @@ export function TextInputModal({
         {message ? <Text style={styles.message}>{message}</Text> : null}
       </View>
 
-      <View style={styles.group}>
-        <View style={styles.inputWrap}>
-          <TextInput
-            style={styles.input}
-            value={value}
-            onChangeText={setValue}
-            placeholder={placeholder}
-            placeholderTextColor={colors.textMuted}
-            autoFocus
-            autoCapitalize="none"
-            autoCorrect={false}
-            returnKeyType="done"
-            onSubmitEditing={handleSubmit}
-            selectionColor={colors.accentBlue}
-          />
-        </View>
-      </View>
+      <TextInput
+        style={styles.input}
+        value={value}
+        onChangeText={setValue}
+        placeholder={placeholder}
+        placeholderTextColor={colors.textMuted}
+        autoFocus
+        autoCapitalize="none"
+        autoCorrect={false}
+        returnKeyType="done"
+        onSubmitEditing={handleSubmit}
+        selectionColor={colors.accentBlue}
+      />
 
       <View style={styles.actions}>
         <Pressable
@@ -97,16 +93,12 @@ const styles = StyleSheet.create({
     color: colors.textMuted,
     marginTop: 2
   },
-  group: {
-    backgroundColor: colors.bgPanel,
-    borderRadius: 12,
-    overflow: 'hidden'
-  },
-  inputWrap: {
-    padding: spacing.md
-  },
+  // Why: matches NewWorktreeModal's input — bgRaised on the modal
+  // background reads as a tappable surface (brighter than the wrapper)
+  // rather than a recessed pit (darker than the wrapper, which is what
+  // bgBase looked like inside a bgPanel group).
   input: {
-    backgroundColor: colors.bgBase,
+    backgroundColor: colors.bgRaised,
     color: colors.textPrimary,
     borderRadius: radii.input,
     paddingHorizontal: spacing.md,
@@ -127,7 +119,7 @@ const styles = StyleSheet.create({
     borderRadius: radii.button
   },
   submitButton: {
-    backgroundColor: colors.accentBlue,
+    backgroundColor: colors.textPrimary,
     paddingHorizontal: spacing.lg,
     paddingVertical: spacing.sm,
     borderRadius: radii.button
@@ -144,7 +136,7 @@ const styles = StyleSheet.create({
     fontWeight: '500'
   },
   submitText: {
-    color: '#fff',
+    color: colors.bgBase,
     fontSize: typography.bodySize,
     fontWeight: '600'
   }
diff --git a/mobile/src/components/worktree-name-suggestion.ts b/mobile/src/components/worktree-name-suggestion.ts
new file mode 100644
index 00000000000..59ec500f603
--- /dev/null
+++ b/mobile/src/components/worktree-name-suggestion.ts
@@ -0,0 +1,42 @@
+import { MARINE_CREATURES } from '../constants/marine-creatures'
+
+// Why: matches the desktop fallback in
+// src/renderer/src/components/sidebar/worktree-name-suggestions.ts. The
+// "already exists locally" collision is on the on-disk worktree directory
+// name (the path basename), not the user-facing displayName — so we derive
+// the used set from path basenames just like the desktop does.
+
+function stripTrailingSeparators(p: string): string {
+  return p.replace(/[\\/]+$/, '')
+}
+
+// Why: cross-platform path basename — handles both POSIX ("/") and Windows
+// ("\\") separators, mirroring src/renderer/src/lib/path.ts so the mobile
+// suggestion logic agrees with the desktop's collision check.
+export function pathBasename(p: string): string {
+  const normalized = stripTrailingSeparators(p)
+  const idx = Math.max(normalized.lastIndexOf('/'), normalized.lastIndexOf('\\'))
+  return idx === -1 ? normalized : normalized.slice(idx + 1)
+}
+
+function normalize(name: string): string {
+  return name.trim().toLowerCase()
+}
+
+export function getSuggestedCreatureName(existingPaths: readonly string[]): string {
+  const used = new Set<string>()
+  for (const p of existingPaths) {
+    used.add(normalize(pathBasename(p)))
+  }
+  for (const candidate of MARINE_CREATURES) {
+    if (!used.has(normalize(candidate))) return candidate
+  }
+  let suffix = 2
+  while (true) {
+    for (const candidate of MARINE_CREATURES) {
+      const numbered = `${candidate}-${suffix}`
+      if (!used.has(normalize(numbered))) return numbered
+    }
+    suffix += 1
+  }
+}
diff --git a/mobile/src/constants/marine-creatures.ts b/mobile/src/constants/marine-creatures.ts
new file mode 100644
index 00000000000..c3f1df7f024
--- /dev/null
+++ b/mobile/src/constants/marine-creatures.ts
@@ -0,0 +1,262 @@
+export const MARINE_CREATURES = [
+  'Nautilus',
+  'Seahorse',
+  'Starfish',
+  'Coral',
+  'Narwhal',
+  'Jellyfish',
+  'Octopus',
+  'Manta',
+  'Dolphin',
+  'Manatee',
+  'Cuttlefish',
+  'Anemone',
+  'Urchin',
+  'Triton',
+  'Nudibranch',
+  'Coelacanth',
+  'Oarfish',
+  'Beluga',
+  'Dugong',
+  'Porpoise',
+  'Stingray',
+  'Hammerhead',
+  'Wobbegong',
+  'Sawfish',
+  'Chimaera',
+  'Anglerfish',
+  'Viperfish',
+  'Dragonfish',
+  'Axolotl',
+  'Otter',
+  'Seadragon',
+  'Seahare',
+  'Squid',
+  'Argonaut',
+  'Sponge',
+  'Barnacle',
+  'Cowrie',
+  'Guitarfish',
+  'Lamprey',
+  'Isopod',
+  'Lionfish',
+  'Clownfish',
+  'Angelfish',
+  'Butterflyfish',
+  'Parrotfish',
+  'Pufferfish',
+  'Moonfish',
+  'Firefish',
+  'Unicornfish',
+  'Rainbowfish',
+  'Betta',
+  'Discus',
+  'Arowana',
+  'Koi',
+  'Piranha',
+  'Barracuda',
+  'Moray',
+  'Sunfish',
+  'Lanternfish',
+  'Archerfish',
+  'Mudskipper',
+  'Hatchetfish',
+  'Knifefish',
+  'Leaffish',
+  'Glassfish',
+  'Ropefish',
+  'Bichir',
+  'Tigerfish',
+  'Cardinalfish',
+  'Lungfish',
+  'Opah',
+  'Frogfish',
+  'Stonefish',
+  'Cutlassfish',
+  'Paddlefish',
+  'Arapaima',
+  'Mandarin',
+  'Blobfish',
+  'Thresher',
+  'Vaquita',
+  'Pipefish',
+  'Guppy',
+  'Tetra',
+  'Danio',
+  'Cichlid',
+  'Oscar',
+  'Gourami',
+  'Killifish',
+  'Rasbora',
+  'Pleco',
+  'Goldfish',
+  'Molly',
+  'Platy',
+  'Barb',
+  'Loach',
+  'Medaka',
+  'Pacu',
+  'Filefish',
+  'Boxfish',
+  'Cowfish',
+  'Surgeonfish',
+  'Damselfish',
+  'Wrasse',
+  'Goby',
+  'Blenny',
+  'Conger',
+  'Sculpin',
+  'Darter',
+  'Remora',
+  'Pilotfish',
+  'Trumpetfish',
+  'Cornetfish',
+  'Jawfish',
+  'Toadfish',
+  'Pearlfish',
+  'Driftfish',
+  'Lumpfish',
+  'Snailfish',
+  'Stickleback',
+  'Halfbeak',
+  'Snipefish',
+  'Pencilfish',
+  'Snakehead',
+  'Tripletail',
+  'Lookdown',
+  'Sweetlips',
+  'Squirrelfish',
+  'Soldierfish',
+  'Rabbitfish',
+  'Hawkfish',
+  'Bannerfish',
+  'Batfish',
+  'Chromis',
+  'Anthias',
+  'Fusilier',
+  'Sweeper',
+  'Emperor',
+  'Ponyfish',
+  'Kelpfish',
+  'Weever',
+  'Pearlside',
+  'Opaleye',
+  'Ballyhoo',
+  'Needlefish',
+  'Triggerfish',
+  'Gar',
+  'Tarpon',
+  'Sailfish',
+  'Conch',
+  'Walrus',
+  'Seal',
+  'Penguin',
+  'Hagfish',
+  'Gulper',
+  'Hydra',
+  'Krill',
+  'Salp',
+  'Tunicate',
+  'Crinoid',
+  'Polyp',
+  'Limpet',
+  'Whelk',
+  'Bowfin',
+  'Minnow',
+  'Gudgeon',
+  'Goldeye',
+  'Mooneye',
+  'Soapfish',
+  'Leatherjacket',
+  'Rudderfish',
+  'Sabrefish',
+  'Puffin',
+  'Albatross',
+  'Osprey',
+  'Pelican',
+  'Petrel',
+  'Gannet',
+  'Tern',
+  'Cormorant',
+  'Leatherback',
+  'Hawksbill',
+  'Loggerhead',
+  'Dottyback',
+  'Basslet',
+  'Gramma',
+  'Hamlet',
+  'Hogfish',
+  'Dartfish',
+  'Foxface',
+  'Shrimpfish',
+  'Pyrosome',
+  'Seapen',
+  'Medusa',
+  'Candlefish',
+  'Silverside',
+  'Shiner',
+  'Eelpout',
+  'Madtom',
+  'Shovelnose',
+  'Sandlance',
+  'Tubesnout',
+  'Marlin',
+  'Bonefish',
+  'Dace',
+  'Rudd',
+  'Spirula',
+  'Permit',
+  'Grunt',
+  'Trevally',
+  'Croaker',
+  'Drum',
+  'Ladyfish',
+  'Bullhead',
+  'Torpedo',
+  'Skate',
+  'Hermit',
+  'Fiddler',
+  'Fireworm',
+  'Tubeworm',
+  'Amphipod',
+  'Copepod',
+  'Pteropod',
+  'Seaslug',
+  'Swordtail',
+  'Bluegill',
+  'Pickerel',
+  'Redhorse',
+  'Logperch',
+  'Goblin',
+  'Catshark',
+  'Harlequin',
+  'Murex',
+  'Volute',
+  'Wentletrap',
+  'Nerite',
+  'Stargazer',
+  'Handfish',
+  'Flyingfish',
+  'Waspfish',
+  'Skua',
+  'Shearwater',
+  'Guillemot',
+  'Razorbill',
+  'Auk',
+  'Fulmar',
+  'Murre',
+  'Velvetfish',
+  'Prowfish',
+  'Sandperch',
+  'Bobtail',
+  'Chiton',
+  'Featherstar',
+  'Nereid',
+  'Siren',
+  'Kraken',
+  'Selkie',
+  'Leviathan',
+  'Wolffish',
+  'Wreckfish',
+  'Horseshoe'
+] as const
diff --git a/mobile/src/notifications/mobile-notifications.ts b/mobile/src/notifications/mobile-notifications.ts
index 287de38a0ec..987eed64e83 100644
--- a/mobile/src/notifications/mobile-notifications.ts
+++ b/mobile/src/notifications/mobile-notifications.ts
@@ -16,22 +16,32 @@ type SubscribeResult = {
   subscriptionId: string
 }
 
-let permissionGranted: boolean | null = null
+export type NotificationPermissionState = {
+  granted: boolean
+  status: string
+  canAskAgain: boolean
+}
+
+export async function getNotificationPermissionState(): Promise<NotificationPermissionState> {
+  const { status, canAskAgain } = await Notifications.getPermissionsAsync()
+  return {
+    granted: status === 'granted',
+    status,
+    canAskAgain
+  }
+}
 
 // Why: permissions must be requested before scheduling any local notification.
-// Cache the result so we only prompt once per app session.
+// Read the OS state every time because users can change it in Settings while
+// Orca remains alive in the background.
 export async function ensureNotificationPermissions(): Promise<boolean> {
-  if (permissionGranted !== null) return permissionGranted
-
-  const { status: existingStatus } = await Notifications.getPermissionsAsync()
-  if (existingStatus === 'granted') {
-    permissionGranted = true
+  const existing = await getNotificationPermissionState()
+  if (existing.granted) {
     return true
   }
 
   const { status } = await Notifications.requestPermissionsAsync()
-  permissionGranted = status === 'granted'
-  return permissionGranted
+  return status === 'granted'
 }
 
 function configureNotificationChannel(): void {
diff --git a/mobile/src/storage/preferences.ts b/mobile/src/storage/preferences.ts
index efd4dc75c9b..7a588902d86 100644
--- a/mobile/src/storage/preferences.ts
+++ b/mobile/src/storage/preferences.ts
@@ -4,13 +4,18 @@ const PINS_PREFIX = 'orca:pins:'
 const PREFS_PREFIX = 'orca:prefs:'
 const NOTIF_KEY = 'orca:pushNotificationsEnabled'
 
+// Why: default-off so the iOS notification permission prompt never
+// fires until the user explicitly opts in via Settings → Notifications.
+// Apple's review guideline 4.5.4 and HIG both prefer user-initiated
+// permission prompts; default-on would fire the prompt the moment the
+// desktop sent its first notification, which can read as unsolicited.
 export async function loadPushNotificationsEnabled(): Promise<boolean> {
   try {
     const raw = await AsyncStorage.getItem(NOTIF_KEY)
-    if (raw === null) return true
+    if (raw === null) return false
     return raw === 'true'
   } catch {
-    return true
+    return false
   }
 }
 
diff --git a/mobile/src/terminal/TerminalWebView.tsx b/mobile/src/terminal/TerminalWebView.tsx
index 22a93bcc7da..9766354f1e5 100644
--- a/mobile/src/terminal/TerminalWebView.tsx
+++ b/mobile/src/terminal/TerminalWebView.tsx
@@ -159,7 +159,41 @@ const XTERM_HTML = `<!DOCTYPE html>
     }
   }
 
+  // Why: on cold start (first WebView load + first scrollback) xterm's DOM
+  // and canvas need several frames to reflow after term.open(). If we
+  // computeFitScale() too eagerly we read scrollWidth=0 or a stale width
+  // from before the new cols took effect, scrollWidth/vpWidth >= 1, and
+  // currentScale snaps to 1 — which is exactly the "didn't zoom to fit"
+  // bug users see on first load. Retry across frames until we get a
+  // positive, stable scrollWidth, then commit. Capped to keep this from
+  // spinning forever if the WebView never lays out (e.g. backgrounded).
+  var FIT_RETRY_MAX_FRAMES = 30;
+  var fitRetryToken = 0;
   function applyFitScale() {
+    if (!term || !term.element) return;
+    var token = ++fitRetryToken;
+    var attempts = 0;
+    var lastWidth = -1;
+    function attempt() {
+      if (token !== fitRetryToken) return;
+      if (!term || !term.element) return;
+      var w = term.element.scrollWidth;
+      attempts++;
+      if (w > 0 && w === lastWidth) {
+        commitFitScale();
+        return;
+      }
+      lastWidth = w;
+      if (attempts >= FIT_RETRY_MAX_FRAMES) {
+        commitFitScale();
+        return;
+      }
+      requestAnimationFrame(attempt);
+    }
+    requestAnimationFrame(attempt);
+  }
+
+  function commitFitScale() {
     if (!term || !term.element) return;
     currentScale = computeFitScale();
     // Why: when the scale is very close to 1 (e.g. 0.97 due to xterm
@@ -316,12 +350,15 @@ const XTERM_HTML = `<!DOCTYPE html>
       ? containerHeightPx
       : window.innerHeight;
     var cols = Math.floor(vpWidth / cellWidth);
-    // Why: subtract 2 rows after dividing. The WebView's reported height
-    // can slightly overstate the usable area (layout timing, subpixel
-    // rounding, safe-area insets). Subtracting 2 guarantees the last
-    // visible row plus the shell prompt (which often wraps on narrow
-    // screens) stays fully above the accessory bar.
-    var rows = Math.max(8, Math.floor(vpHeight / cellHeight) - 2);
+    // Why: the rows we report become the PTY's actual row count after the
+    // server fits to viewport, and xterm renders exactly that many lines
+    // anchored top-left of the WebView. Subtracting rows here would leave
+    // dead xterm-background space at the bottom of the container and make
+    // the last PTY rows visually appear above an "invisible line." Any
+    // safety margin between the prompt and the accessory bar must come
+    // from RN layout (terminalFrame's flex bounds), not from undersizing
+    // the PTY.
+    var rows = Math.max(8, Math.floor(vpHeight / cellHeight));
     notify({ type: 'measure-result', cols: cols, rows: rows });
   }
 
diff --git a/mobile/src/transport/client-context.tsx b/mobile/src/transport/client-context.tsx
new file mode 100644
index 00000000000..176b80355e8
--- /dev/null
+++ b/mobile/src/transport/client-context.tsx
@@ -0,0 +1,450 @@
+// Why: collapses the per-screen WebSocket connection model into a single
+// shared RpcClient per host. Implements the design in
+// docs/mobile-shared-client-per-host.md.
+//
+// Lifecycle rules:
+// - First request for a host opens its client lazily.
+// - Refcount tracks active subscribers; when it drops to zero we schedule
+//   a 30-second idle close timer. If a new subscriber arrives within that
+//   window we cancel and reuse the same client.
+// - removeHost() forces an immediate close so re-pairing gets a fresh
+//   transport.
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode
+} from 'react'
+import { connect, type RpcClient } from './rpc-client'
+import { loadHosts } from './host-store'
+import type { ConnectionState, HostProfile } from './types'
+
+type StoreEntry = {
+  client: RpcClient
+  state: ConnectionState
+  refCount: number
+  unsubState: () => void
+}
+
+type ContextValue = {
+  acquire: (hostId: string, host?: HostProfile) => RpcClient | null
+  release: (hostId: string) => void
+  forceReconnect: (hostId: string) => Promise<void>
+  closeHost: (hostId: string) => void
+  getState: (hostId: string) => ConnectionState
+  getReconnectAttempt: (hostId: string) => number
+  subscribeHostState: (hostId: string, listener: (state: ConnectionState) => void) => () => void
+  getAllClients: () => Array<{ hostId: string; client: RpcClient }>
+  subscribeAllHosts: (listener: () => void) => () => void
+  // Why: lets the home screen feed already-loaded HostProfiles in so we
+  // don't pay loadHosts() latency twice (once in the focus-effect, again
+  // inside openEntry).
+  primeHosts: (hosts: HostProfile[]) => void
+}
+
+const Ctx = createContext<ContextValue | null>(null)
+
+export function RpcClientProvider({ children }: { children: ReactNode }) {
+  // Why: entries live in a ref so updates don't force re-renders of the
+  // entire tree on every connection state change. State propagation goes
+  // through per-host listener Sets instead.
+  const storeRef = useRef<Map<string, StoreEntry>>(new Map())
+  const stateListenersRef = useRef<Map<string, Set<(state: ConnectionState) => void>>>(new Map())
+  const allHostsListenersRef = useRef<Set<() => void>>(new Set())
+
+  // Pending opens (avoid two acquire() callers in the same render racing the
+  // host lookup). Keyed by hostId, value is a sentinel resolved when the
+  // entry materialises.
+  const pendingOpensRef = useRef<Map<string, Promise<void>>>(new Map())
+
+  // Why: a fast-path cache of already-loaded HostProfiles. Screens that
+  // have run loadHosts() can call primeHosts() to populate this and skip
+  // the second loadHosts() inside openEntry. Without this we'd serialize
+  // two Keychain passes on cold start.
+  const primedHostsRef = useRef<Map<string, HostProfile>>(new Map())
+
+  function notifyHostState(hostId: string, state: ConnectionState) {
+    const set = stateListenersRef.current.get(hostId)
+    if (!set) return
+    for (const listener of set) listener(state)
+  }
+
+  function notifyAllHosts() {
+    for (const listener of allHostsListenersRef.current) listener()
+  }
+
+  const closeEntry = useCallback((hostId: string) => {
+    const entry = storeRef.current.get(hostId)
+    if (!entry) return
+    entry.unsubState()
+    entry.client.close()
+    storeRef.current.delete(hostId)
+    notifyHostState(hostId, 'disconnected')
+    notifyAllHosts()
+  }, [])
+
+  const openEntry = useCallback(async (hostId: string): Promise<StoreEntry | null> => {
+    const existing = pendingOpensRef.current.get(hostId)
+    if (existing) {
+      await existing
+      return storeRef.current.get(hostId) ?? null
+    }
+    let resolve: () => void = () => {}
+    const promise = new Promise<void>((res) => {
+      resolve = res
+    })
+    pendingOpensRef.current.set(hostId, promise)
+
+    try {
+      // Why: prefer the primed cache (populated by primeHosts when the
+      // screen already ran loadHosts) so we don't serialize a second
+      // Keychain pass behind the first one on cold start.
+      let host = primedHostsRef.current.get(hostId)
+      if (!host) {
+        try {
+          const hosts = await loadHosts()
+          host = hosts.find((h) => h.id === hostId)
+        } catch {
+          // Why: a Keychain failure on cold start (rare but observed —
+          // happens when iOS Keychain is mid-unlock or Android Keystore
+          // races the JS bridge). Surface it as 'disconnected' so the
+          // home card flips off the perma-spinner and the user can hit
+          // Reconnect from the action sheet to retry.
+          notifyHostState(hostId, 'disconnected')
+          notifyAllHosts()
+          return null
+        }
+        if (!host) return null
+      }
+
+      // Re-check after any await — another acquire() may have completed.
+      const after = storeRef.current.get(hostId)
+      if (after) return after
+
+      let client: RpcClient
+      try {
+        client = connect(host.endpoint, host.deviceToken, host.publicKeyB64)
+      } catch {
+        // Why: connect() can throw synchronously if the public key is
+        // malformed or the endpoint URL is invalid. Notify so the UI
+        // doesn't sit on a stale 'connecting' label forever.
+        notifyHostState(hostId, 'disconnected')
+        notifyAllHosts()
+        return null
+      }
+      const unsubState = client.onStateChange((state) => {
+        const cur = storeRef.current.get(hostId)
+        if (!cur) return
+        cur.state = state
+        notifyHostState(hostId, state)
+      })
+      const entry: StoreEntry = {
+        client,
+        state: client.getState(),
+        refCount: 0,
+        unsubState
+      }
+      storeRef.current.set(hostId, entry)
+      notifyHostState(hostId, entry.state)
+      notifyAllHosts()
+      return entry
+    } finally {
+      pendingOpensRef.current.delete(hostId)
+      resolve()
+    }
+  }, [])
+
+  // Why: `acquire` is the synchronous get-or-open. If the entry already
+  // exists, return its client immediately and bump the refcount. If not,
+  // kick off an async open (the consumer will subscribe via
+  // `subscribeHostState` and re-read once 'connecting' fires). Optionally
+  // accepts the HostProfile so the caller can avoid an extra loadHosts()
+  // pass inside openEntry.
+  const acquire = useCallback(
+    (hostId: string, host?: HostProfile): RpcClient | null => {
+      if (host) primedHostsRef.current.set(hostId, host)
+      const existing = storeRef.current.get(hostId)
+      if (existing) {
+        existing.refCount += 1
+        return existing.client
+      }
+      // Trigger async open. The acquire-side will return null this tick and
+      // try again once the state listener fires; consumers are expected to
+      // call acquire() inside an effect that re-runs on state changes.
+      void openEntry(hostId).then((entry) => {
+        if (!entry) return
+        entry.refCount += 1
+      })
+      return null
+    },
+    [openEntry]
+  )
+
+  const primeHosts = useCallback((hosts: HostProfile[]) => {
+    for (const host of hosts) primedHostsRef.current.set(host.id, host)
+  }, [])
+
+  // Why: refcount dropping to 0 no longer triggers an idle-close. The
+  // app deliberately keeps live WebSockets open while the app itself is
+  // foregrounded — closing on transient navigation gaps was producing
+  // false 'disconnected' flashes when the user navigated home → host →
+  // back to home faster than React could re-acquire on the home side.
+  // Connections still close on: explicit user Disconnect, host removal,
+  // app backgrounding (OS-level socket suspension), and provider
+  // unmount (app shutdown).
+  const release = useCallback((hostId: string) => {
+    const entry = storeRef.current.get(hostId)
+    if (!entry) return
+    entry.refCount = Math.max(0, entry.refCount - 1)
+  }, [])
+
+  const forceReconnect = useCallback(
+    async (hostId: string) => {
+      const entry = storeRef.current.get(hostId)
+      // Why: preserve refcount across the swap. If the user reaches
+      // forceReconnect via the Disconnect → Reconnect path, the entry
+      // was already closed and refCount=0; fall back to active listener
+      // count as a proxy for "screens still watching this host."
+      const listenerCount = stateListenersRef.current.get(hostId)?.size ?? 0
+      const savedRefCount = entry?.refCount ?? Math.max(1, listenerCount)
+      if (entry) {
+        entry.unsubState()
+        entry.client.close()
+        storeRef.current.delete(hostId)
+      }
+      const fresh = await openEntry(hostId)
+      if (fresh) fresh.refCount = savedRefCount
+    },
+    [openEntry]
+  )
+
+  const getState = useCallback((hostId: string): ConnectionState => {
+    return storeRef.current.get(hostId)?.state ?? 'disconnected'
+  }, [])
+
+  const getReconnectAttempt = useCallback((hostId: string): number => {
+    return storeRef.current.get(hostId)?.client.getReconnectAttempt() ?? 0
+  }, [])
+
+  const subscribeHostState = useCallback(
+    (hostId: string, listener: (state: ConnectionState) => void) => {
+      let set = stateListenersRef.current.get(hostId)
+      if (!set) {
+        set = new Set()
+        stateListenersRef.current.set(hostId, set)
+      }
+      set.add(listener)
+      return () => {
+        const s = stateListenersRef.current.get(hostId)
+        if (!s) return
+        s.delete(listener)
+        if (s.size === 0) stateListenersRef.current.delete(hostId)
+      }
+    },
+    []
+  )
+
+  const getAllClients = useCallback((): Array<{ hostId: string; client: RpcClient }> => {
+    const out: Array<{ hostId: string; client: RpcClient }> = []
+    for (const [hostId, entry] of storeRef.current) {
+      out.push({ hostId, client: entry.client })
+    }
+    return out
+  }, [])
+
+  const subscribeAllHosts = useCallback((listener: () => void) => {
+    allHostsListenersRef.current.add(listener)
+    return () => {
+      allHostsListenersRef.current.delete(listener)
+    }
+  }, [])
+
+  // Close all clients on provider unmount (app shutdown).
+  // Why: deps must be empty so this cleanup ONLY runs on real unmount.
+  // Hot-reload re-evaluates this module, which makes closeEntry a new
+  // function identity. With [closeEntry] as deps, every Fast Refresh
+  // would tear down all open WebSockets, leaving screens holding closed
+  // clients and the user staring at a 'Reconnecting…' card. Reading
+  // storeRef.current and the locally-scoped closeEntry inside the
+  // cleanup is safe — the ref is stable across renders, and the
+  // function captured here will be the one defined in the same
+  // closure as this effect.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    const store = storeRef.current
+    return () => {
+      for (const [hostId] of store) closeEntry(hostId)
+    }
+  }, [])
+
+  const value = useMemo<ContextValue>(
+    () => ({
+      acquire,
+      release,
+      forceReconnect,
+      closeHost: closeEntry,
+      getState,
+      getReconnectAttempt,
+      subscribeHostState,
+      getAllClients,
+      subscribeAllHosts,
+      primeHosts
+    }),
+    [
+      acquire,
+      release,
+      forceReconnect,
+      closeEntry,
+      getState,
+      getReconnectAttempt,
+      subscribeHostState,
+      getAllClients,
+      subscribeAllHosts,
+      primeHosts
+    ]
+  )
+
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>
+}
+
+function useCtx(): ContextValue {
+  const ctx = useContext(Ctx)
+  if (!ctx) throw new Error('useHostClient must be used inside <RpcClientProvider>')
+  return ctx
+}
+
+// Why: the primary hook for screens. Acquires the shared client for a
+// hostId on mount and releases on unmount. Re-renders when the host's
+// connection state changes.
+export function useHostClient(hostId: string | undefined): {
+  client: RpcClient | null
+  state: ConnectionState
+} {
+  const ctx = useCtx()
+  const [, force] = useState(0)
+  const [state, setState] = useState<ConnectionState>(() =>
+    hostId ? ctx.getState(hostId) : 'disconnected'
+  )
+  const clientRef = useRef<RpcClient | null>(null)
+
+  useEffect(() => {
+    if (!hostId) {
+      clientRef.current = null
+      setState('disconnected')
+      return
+    }
+    let cancelled = false
+    // Subscribe before acquire so any state change during open is captured.
+    const unsub = ctx.subscribeHostState(hostId, (next) => {
+      if (cancelled) return
+      setState(next)
+      // Why: if the client was null at first acquire (async open), the
+      // first state change ('connecting'/'handshaking'/'connected') is our
+      // signal to re-read.
+      if (clientRef.current == null) {
+        const all = ctx.getAllClients()
+        const found = all.find((entry) => entry.hostId === hostId)
+        if (found) {
+          clientRef.current = found.client
+          force((n) => n + 1)
+        }
+      }
+    })
+    const initial = ctx.acquire(hostId)
+    if (initial) {
+      clientRef.current = initial
+      setState(ctx.getState(hostId))
+    }
+    return () => {
+      cancelled = true
+      unsub()
+      ctx.release(hostId)
+      clientRef.current = null
+    }
+  }, [ctx, hostId])
+
+  return { client: clientRef.current, state }
+}
+
+// Why: home screen renders all paired hosts at once. Acquires each on
+// mount, releases on unmount. The provider's refcounting ensures we
+// don't double-open if a host-detail screen is also open.
+export function useAllHostClients(hostIds: string[]): Array<{
+  hostId: string
+  client: RpcClient
+  state: ConnectionState
+}> {
+  const ctx = useCtx()
+  // Stable key so we don't tear down on every render of the array.
+  const key = useMemo(() => [...hostIds].sort().join(','), [hostIds])
+  const [tick, setTick] = useState(0)
+
+  useEffect(() => {
+    if (hostIds.length === 0) return
+    for (const id of hostIds) ctx.acquire(id)
+    const unsubs: Array<() => void> = []
+    for (const id of hostIds) {
+      unsubs.push(ctx.subscribeHostState(id, () => setTick((n) => n + 1)))
+    }
+    unsubs.push(ctx.subscribeAllHosts(() => setTick((n) => n + 1)))
+    return () => {
+      for (const u of unsubs) u()
+      for (const id of hostIds) ctx.release(id)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key])
+
+  return useMemo(() => {
+    const out: Array<{ hostId: string; client: RpcClient; state: ConnectionState }> = []
+    for (const id of hostIds) {
+      const all = ctx.getAllClients().find((entry) => entry.hostId === id)
+      if (all) {
+        out.push({ hostId: id, client: all.client, state: ctx.getState(id) })
+      }
+    }
+    return out
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, tick])
+}
+
+// Why: removeHost() in host-store.ts must close the live client, but
+// host-store has no React-side handle. Expose a hook that lets callers
+// close a host after removal.
+export function useCloseHost(): (hostId: string) => void {
+  const ctx = useCtx()
+  return ctx.closeHost
+}
+
+// Why: future-proof "Connection issues — try again" affordance.
+export function useForceReconnect(): (hostId: string) => Promise<void> {
+  const ctx = useCtx()
+  return ctx.forceReconnect
+}
+
+// Why: lets the home screen feed already-loaded HostProfiles in so the
+// provider can skip its own loadHosts() pass when it eventually opens
+// each host — collapses two serial Keychain reads on cold-start into one.
+export function usePrimeHosts(): (hosts: HostProfile[]) => void {
+  const ctx = useCtx()
+  return ctx.primeHosts
+}
+
+// Why: lets the home/host-detail UI escalate "Reconnecting…" to a more
+// alarming "Can't connect" once the rpc-client has cycled enough times to
+// indicate something's actually wrong (wrong port, server down, network
+// loss). Reads through the context so it stays in sync with the live
+// rpc-client instance even after forceReconnect swaps the underlying
+// client.
+export function useReconnectAttempt(hostId: string | undefined): number {
+  const ctx = useCtx()
+  const [, force] = useState(0)
+  useEffect(() => {
+    if (!hostId) return
+    return ctx.subscribeHostState(hostId, () => force((n) => n + 1))
+  }, [ctx, hostId])
+  return hostId ? ctx.getReconnectAttempt(hostId) : 0
+}
diff --git a/mobile/src/transport/host-store.ts b/mobile/src/transport/host-store.ts
index 7f35fb742a2..119e10d7c34 100644
--- a/mobile/src/transport/host-store.ts
+++ b/mobile/src/transport/host-store.ts
@@ -1,16 +1,101 @@
 import AsyncStorage from '@react-native-async-storage/async-storage'
-import { HostProfileSchema, type HostProfile } from './types'
+import * as SecureStore from 'expo-secure-store'
+import {
+  HostProfileSchema,
+  StoredHostProfileSchema,
+  type HostProfile,
+  type StoredHostProfile
+} from './types'
 
 const STORAGE_KEY = 'orca:hosts'
+// Why: SecureStore keys must match [A-Za-z0-9._-]; colons are rejected.
+// Use dots as the separator so the key shape stays readable while
+// satisfying the validator.
+const TOKEN_KEY_PREFIX = 'orca.host-token.'
+
+// Why: WHEN_UNLOCKED_THIS_DEVICE_ONLY keeps the pairing token off
+// iCloud Keychain and out of iCloud/iTunes backup restores onto a
+// different physical device. Reads/writes are silent (no biometric
+// prompt) since we don't request access control flags.
+const KEYCHAIN_OPTIONS: SecureStore.SecureStoreOptions = {
+  keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY
+}
+
+function tokenKey(hostId: string): string {
+  return `${TOKEN_KEY_PREFIX}${hostId}`
+}
+
+// Why: SecureStore reads on Android Keystore can take 50-200ms each, and
+// loadHosts() is called from every screen mount + every useFocusEffect.
+// Stack with N hosts and you get N*200ms blocking every navigation, which
+// triggers connection-churn cycles in the home-screen useEffect. Cache
+// per-hostId in memory; invalidate only on save/remove. The cache lives
+// for the JS-runtime lifetime, which matches AsyncStorage semantics
+// (cleared on app uninstall, persisted across foreground/background).
+const tokenCache = new Map<string, string>()
+let inflightLoad: Promise<HostProfile[]> | null = null
 
 export async function loadHosts(): Promise<HostProfile[]> {
+  // Why: deduplicate concurrent loadHosts() calls so multiple screens
+  // mounting simultaneously share one Keychain read pass.
+  if (inflightLoad) return inflightLoad
+  inflightLoad = doLoadHosts().finally(() => {
+    inflightLoad = null
+  })
+  return inflightLoad
+}
+
+async function doLoadHosts(): Promise<HostProfile[]> {
+  const raw = await AsyncStorage.getItem(STORAGE_KEY)
+  if (!raw) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed)) return []
+
+  const out: HostProfile[] = []
+  for (const item of parsed) {
+    // Why: pre-v0.0.3 records carry the deviceToken in AsyncStorage.
+    // Drop them silently — the three pre-launch users will re-pair on
+    // first run rather than carry a migration shim through the auth
+    // path.
+    if (item && typeof item === 'object' && 'deviceToken' in item) {
+      continue
+    }
+    const stored = StoredHostProfileSchema.safeParse(item)
+    if (!stored.success) continue
+
+    let token = tokenCache.get(stored.data.id)
+    if (!token) {
+      const fetched = await SecureStore.getItemAsync(tokenKey(stored.data.id), KEYCHAIN_OPTIONS)
+      if (!fetched) {
+        // Why: orphaned metadata with no matching keychain entry — most
+        // likely a stale record from a development install. Skip it
+        // rather than surface a half-broken host.
+        continue
+      }
+      token = fetched
+      tokenCache.set(stored.data.id, token)
+    }
+    out.push({ ...stored.data, deviceToken: token })
+  }
+  return out
+}
+
+async function loadStoredHosts(): Promise<StoredHostProfile[]> {
   const raw = await AsyncStorage.getItem(STORAGE_KEY)
   if (!raw) return []
   try {
     const parsed = JSON.parse(raw) as unknown
     if (!Array.isArray(parsed)) return []
     return parsed.flatMap((item) => {
-      const result = HostProfileSchema.safeParse(item)
+      // Why: same drop-old-records rule as loadHosts; keeps internal
+      // mutators from re-persisting pre-v0.0.3 entries.
+      if (item && typeof item === 'object' && 'deviceToken' in item) return []
+      const result = StoredHostProfileSchema.safeParse(item)
       return result.success ? [result.data] : []
     })
   } catch {
@@ -18,25 +103,41 @@ export async function loadHosts(): Promise<HostProfile[]> {
   }
 }
 
-export async function saveHost(host: HostProfile): Promise<void> {
-  const hosts = await loadHosts()
-  const index = hosts.findIndex((h) => h.id === host.id)
-  if (index >= 0) {
-    hosts[index] = host
-  } else {
-    hosts.push(host)
+function toStored(host: HostProfile): StoredHostProfile {
+  return {
+    id: host.id,
+    name: host.name,
+    endpoint: host.endpoint,
+    publicKeyB64: host.publicKeyB64,
+    lastConnected: host.lastConnected
   }
+}
+
+export async function saveHost(host: HostProfile): Promise<void> {
+  const validated = HostProfileSchema.parse(host)
+  const hosts = await loadStoredHosts()
+  const stored = toStored(validated)
+  const index = hosts.findIndex((h) => h.id === stored.id)
+  if (index >= 0) {
+    hosts[index] = stored
+  } else {
+    hosts.push(stored)
+  }
+  await SecureStore.setItemAsync(tokenKey(stored.id), validated.deviceToken, KEYCHAIN_OPTIONS)
   await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(hosts))
+  tokenCache.set(stored.id, validated.deviceToken)
 }
 
 export async function removeHost(hostId: string): Promise<void> {
-  const hosts = await loadHosts()
+  const hosts = await loadStoredHosts()
   const filtered = hosts.filter((h) => h.id !== hostId)
   await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(filtered))
+  await SecureStore.deleteItemAsync(tokenKey(hostId), KEYCHAIN_OPTIONS)
+  tokenCache.delete(hostId)
 }
 
 export async function renameHost(hostId: string, newName: string): Promise<void> {
-  const hosts = await loadHosts()
+  const hosts = await loadStoredHosts()
   const host = hosts.find((h) => h.id === hostId)
   if (host) {
     host.name = newName
@@ -45,7 +146,7 @@ export async function renameHost(hostId: string, newName: string): Promise<void>
 }
 
 export async function getNextHostName(): Promise<string> {
-  const hosts = await loadHosts()
+  const hosts = await loadStoredHosts()
   const existingNumbers = hosts
     .map((h) => {
       const match = h.name.match(/^Host (\d+)$/)
@@ -57,7 +158,7 @@ export async function getNextHostName(): Promise<string> {
 }
 
 export async function updateLastConnected(hostId: string): Promise<void> {
-  const hosts = await loadHosts()
+  const hosts = await loadStoredHosts()
   const host = hosts.find((h) => h.id === hostId)
   if (host) {
     host.lastConnected = Date.now()
diff --git a/mobile/src/transport/pairing.ts b/mobile/src/transport/pairing.ts
index ada3e2715eb..2b54f4e58db 100644
--- a/mobile/src/transport/pairing.ts
+++ b/mobile/src/transport/pairing.ts
@@ -1,16 +1,38 @@
 import { PairingOfferSchema, type PairingOffer } from './types'
 
+// Why: this file mirrors src/shared/pairing.ts (which is covered by CI
+// vitest) but uses atob/btoa because Metro/Hermes don't ship Node's
+// Buffer. Keep the parsing semantics in sync — when one changes, update
+// the other.
+
 export function decodePairingUrl(url: string): PairingOffer | null {
   try {
     const hashIndex = url.indexOf('#')
     if (!url.startsWith('orca://pair') || hashIndex === -1) return null
-
-    const base64url = url.slice(hashIndex + 1)
-    const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/')
-    const json = atob(base64)
-    const parsed = JSON.parse(json)
-    return PairingOfferSchema.parse(parsed)
+    return decodePairingBase64(url.slice(hashIndex + 1))
   } catch {
     return null
   }
 }
+
+// Why: accept either an `orca://pair#<base64>` URL or the bare base64
+// string so the paste-pair flow can take whichever the user actually
+// copied from desktop.
+export function parsePairingCode(input: string): PairingOffer | null {
+  const trimmed = input.trim()
+  if (!trimmed) return null
+  try {
+    if (trimmed.startsWith('orca://pair')) {
+      return decodePairingUrl(trimmed)
+    }
+    return decodePairingBase64(trimmed)
+  } catch {
+    return null
+  }
+}
+
+function decodePairingBase64(base64url: string): PairingOffer {
+  const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/')
+  const json = atob(base64)
+  return PairingOfferSchema.parse(JSON.parse(json))
+}
diff --git a/mobile/src/transport/protocol-compat.ts b/mobile/src/transport/protocol-compat.ts
new file mode 100644
index 00000000000..12dc0de4093
--- /dev/null
+++ b/mobile/src/transport/protocol-compat.ts
@@ -0,0 +1,42 @@
+// Why: this file mirrors src/shared/protocol-compat.ts (which is
+// covered by CI vitest). Metro can't resolve out of mobile/, so the
+// pure function is duplicated here. Keep the two files in sync — when
+// you change the evaluator's logic, update both. The src/shared/ copy
+// is the tested canonical version.
+import { MIN_COMPATIBLE_DESKTOP_VERSION, MOBILE_PROTOCOL_VERSION } from './protocol-version'
+
+export type CompatVerdict =
+  | { kind: 'ok' }
+  | {
+      kind: 'blocked'
+      reason: 'mobile-too-old' | 'desktop-too-old'
+      desktopVersion: number
+      requiredMobileVersion?: number
+      requiredDesktopVersion?: number
+    }
+
+export function evaluateCompat(input: {
+  desktopProtocolVersion: number | undefined
+  desktopMinCompatibleMobileVersion: number | undefined
+}): CompatVerdict {
+  const desktopVersion = input.desktopProtocolVersion ?? 0
+  const requiredMobile = input.desktopMinCompatibleMobileVersion ?? 0
+
+  if (MOBILE_PROTOCOL_VERSION < requiredMobile) {
+    return {
+      kind: 'blocked',
+      reason: 'mobile-too-old',
+      desktopVersion,
+      requiredMobileVersion: requiredMobile
+    }
+  }
+  if (desktopVersion < MIN_COMPATIBLE_DESKTOP_VERSION) {
+    return {
+      kind: 'blocked',
+      reason: 'desktop-too-old',
+      desktopVersion,
+      requiredDesktopVersion: MIN_COMPATIBLE_DESKTOP_VERSION
+    }
+  }
+  return { kind: 'ok' }
+}
diff --git a/mobile/src/transport/protocol-version.ts b/mobile/src/transport/protocol-version.ts
new file mode 100644
index 00000000000..9445c1f2881
--- /dev/null
+++ b/mobile/src/transport/protocol-version.ts
@@ -0,0 +1,20 @@
+// Why: declares the mobile's pairing protocol version and the minimum
+// desktop version 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
+//     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.
+
+export const MOBILE_PROTOCOL_VERSION = 1
+export const MIN_COMPATIBLE_DESKTOP_VERSION = 0
diff --git a/mobile/src/transport/rpc-client.test.ts b/mobile/src/transport/rpc-client.test.ts
new file mode 100644
index 00000000000..505a5722bd4
--- /dev/null
+++ b/mobile/src/transport/rpc-client.test.ts
@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { connect } from './rpc-client'
+
+vi.mock('./e2ee', () => ({
+  generateKeyPair: () => ({
+    publicKey: new Uint8Array(32),
+    secretKey: new Uint8Array(32)
+  }),
+  deriveSharedKey: () => new Uint8Array(32),
+  publicKeyFromBase64: () => new Uint8Array(32),
+  publicKeyToBase64: () => 'client-public-key',
+  encrypt: (plaintext: string) => `encrypted:${plaintext}`,
+  decrypt: (raw: string) => raw.replace(/^encrypted:/, '')
+}))
+
+class MockWebSocket {
+  static CONNECTING = 0
+  static OPEN = 1
+  static CLOSING = 2
+  static CLOSED = 3
+
+  readonly CONNECTING = MockWebSocket.CONNECTING
+  readonly OPEN = MockWebSocket.OPEN
+  readonly CLOSING = MockWebSocket.CLOSING
+  readonly CLOSED = MockWebSocket.CLOSED
+
+  readyState = MockWebSocket.CONNECTING
+  onopen: (() => void) | null = null
+  onclose: (() => void) | null = null
+  onmessage: ((event: { data: string }) => void) | null = null
+  onerror: (() => void) | null = null
+  emitCloseOnClose = true
+  sent: string[] = []
+  close = vi.fn(() => {
+    if (this.readyState === MockWebSocket.CLOSED) return
+    this.readyState = MockWebSocket.CLOSED
+    if (this.emitCloseOnClose) {
+      this.onclose?.()
+    }
+  })
+
+  constructor(readonly endpoint: string) {
+    mockSockets.push(this)
+  }
+
+  send(payload: string): void {
+    this.sent.push(payload)
+  }
+
+  open(): void {
+    this.readyState = MockWebSocket.OPEN
+    this.onopen?.()
+  }
+
+  receive(payload: string): void {
+    this.onmessage?.({ data: payload })
+  }
+}
+
+const mockSockets: MockWebSocket[] = []
+const originalWebSocket = globalThis.WebSocket
+
+describe('mobile rpc-client connection timeout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    mockSockets.length = 0
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    globalThis.WebSocket = originalWebSocket
+  })
+
+  it('closes a socket that never opens so reconnect can run', () => {
+    const states: string[] = []
+    const client = connect('ws://desktop.invalid', 'token', 'server-key', (state) => {
+      states.push(state)
+    })
+
+    expect(client.getState()).toBe('connecting')
+    expect(mockSockets).toHaveLength(1)
+    mockSockets[0]!.emitCloseOnClose = false
+
+    vi.advanceTimersByTime(12_000)
+
+    expect(mockSockets[0]!.close).toHaveBeenCalledTimes(1)
+    expect(client.getState()).toBe('reconnecting')
+    expect(states).toContain('reconnecting')
+
+    client.close()
+  })
+
+  it('clears the open timeout once the socket opens and authenticates', () => {
+    const client = connect('ws://desktop.invalid', 'token', 'server-key')
+    const socket = mockSockets[0]!
+
+    socket.open()
+    socket.receive(JSON.stringify({ type: 'e2ee_ready' }))
+    socket.receive('encrypted:{"type":"e2ee_authenticated"}')
+
+    expect(client.getState()).toBe('connected')
+
+    vi.advanceTimersByTime(12_000)
+
+    expect(socket.close).not.toHaveBeenCalled()
+    expect(client.getState()).toBe('connected')
+
+    client.close()
+  })
+})
diff --git a/mobile/src/transport/rpc-client.ts b/mobile/src/transport/rpc-client.ts
index 10b51ab19d2..d1269000382 100644
--- a/mobile/src/transport/rpc-client.ts
+++ b/mobile/src/transport/rpc-client.ts
@@ -25,13 +25,40 @@ export type RpcClient = {
   sendRequest: (method: string, params?: unknown) => Promise<RpcResponse>
   subscribe: (method: string, params: unknown, onData: StreamingListener) => () => void
   getState: () => ConnectionState
+  // Why: UI escalates "Reconnecting…" to "Can't connect" once attempts cross
+  // a threshold. 0 means never failed; counter is reset on successful open.
+  getReconnectAttempt: () => number
   onStateChange: (listener: (state: ConnectionState) => void) => () => void
   close: () => void
 }
 
-const RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 16000]
+// Why: capped at 4s so the worst-case "stuck reconnecting" window the
+// user perceives is short. Prior 16s ceiling combined with Android's
+// suspended-timer behaviour during background → foreground transitions
+// often felt like the app would just sit on 'Reconnecting…' forever
+// (the timer was queued, the OS had simply not run it yet). Tapping the
+// manual Reconnect button bypassed the timer, which is why it felt
+// "magic". Shorter backoff makes the auto-recovery path feel as fast.
+const RECONNECT_DELAYS = [500, 1000, 2000, 4000]
 const REQUEST_TIMEOUT_MS = 30_000
+const CONNECT_TIMEOUT_MS = 12_000
 const HANDSHAKE_TIMEOUT_MS = 5_000
+// Why: RN's WebSocket implementation may not expose static readyState
+// constants, but the protocol value for CONNECTING is stable across runtimes.
+const WEBSOCKET_CONNECTING_STATE = 0
+
+// Why: app-level liveness probe. The server runs its own ping/pong sweep
+// at 15s, but RN's WebSocket runtime auto-pongs at the native layer
+// without surfacing anything to JS — so the mobile side can't *see* that
+// the server thinks the link is fine. To detect a half-open socket from
+// the mobile direction (e.g. server crashed, phone moved between wifi
+// and cellular without TCP RST) we periodically round-trip a tiny RPC.
+// If two consecutive probes time out we force-close the WS, which fires
+// the existing reconnect path. 20s cadence + the 30s request timeout =
+// worst-case ~50s before mobile decides the link is dead and kicks
+// reconnect, which is still inside the user's perceived "responsive"
+// window and well below iOS's typical background-disconnect window.
+const ACTIVITY_PROBE_INTERVAL_MS = 20_000
 
 export function connect(
   endpoint: string,
@@ -44,7 +71,9 @@ export function connect(
   let requestCounter = 0
   let reconnectAttempt = 0
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  let connectTimer: ReturnType<typeof setTimeout> | null = null
   let handshakeTimer: ReturnType<typeof setTimeout> | null = null
+  let activityProbeTimer: ReturnType<typeof setInterval> | null = null
   let intentionallyClosed = false
 
   // Why: fresh ephemeral keypair per connection provides forward secrecy.
@@ -95,8 +124,23 @@ export function connect(
     sharedKey = null
 
     ws = new WebSocket(endpoint)
+    const openingWs = ws
+
+    // Why: React Native can leave TCP/WebSocket opens pending indefinitely on
+    // flaky network handoffs. Force the existing onclose reconnect path if
+    // onopen never arrives, instead of leaving the UI stuck at "Connecting...".
+    connectTimer = setTimeout(() => {
+      connectTimer = null
+      if (ws === openingWs && openingWs.readyState === WEBSOCKET_CONNECTING_STATE) {
+        openingWs.close()
+        if (ws === openingWs) {
+          handleSocketClosed(openingWs)
+        }
+      }
+    }, CONNECT_TIMEOUT_MS)
 
     ws.onopen = () => {
+      clearConnectTimer()
       reconnectAttempt = 0
       setState('handshaking')
 
@@ -151,6 +195,7 @@ export function connect(
               handshakeTimer = null
             }
             setState('connected')
+            startActivityProbe()
             for (const [id, stream] of streamListeners) {
               sendEncrypted({ id, deviceToken, method: stream.method, params: stream.params })
             }
@@ -233,20 +278,7 @@ export function connect(
     }
 
     ws.onclose = () => {
-      ws = null
-      sharedKey = null
-      if (handshakeTimer) {
-        clearTimeout(handshakeTimer)
-        handshakeTimer = null
-      }
-      if (intentionallyClosed) {
-        setState('disconnected')
-        rejectAllPending('Connection closed')
-        return
-      }
-      rejectAllPending('Connection interrupted')
-      setState('reconnecting')
-      scheduleReconnect()
+      handleSocketClosed(openingWs)
     }
 
     ws.onerror = () => {
@@ -254,6 +286,28 @@ export function connect(
     }
   }
 
+  function handleSocketClosed(closedWs: WebSocket) {
+    if (ws !== closedWs) {
+      return
+    }
+    clearConnectTimer()
+    ws = null
+    sharedKey = null
+    if (handshakeTimer) {
+      clearTimeout(handshakeTimer)
+      handshakeTimer = null
+    }
+    stopActivityProbe()
+    if (intentionallyClosed) {
+      setState('disconnected')
+      rejectAllPending('Connection closed')
+      return
+    }
+    rejectAllPending('Connection interrupted')
+    setState('reconnecting')
+    scheduleReconnect()
+  }
+
   function scheduleReconnect() {
     const delay = RECONNECT_DELAYS[Math.min(reconnectAttempt, RECONNECT_DELAYS.length - 1)]!
     reconnectAttempt++
@@ -263,6 +317,65 @@ export function connect(
     }, delay)
   }
 
+  function clearConnectTimer() {
+    if (connectTimer) {
+      clearTimeout(connectTimer)
+      connectTimer = null
+    }
+  }
+
+  // Why: app-level liveness probe — see ACTIVITY_PROBE_INTERVAL_MS comment
+  // at the top of the file. Fires while the channel is in 'connected'
+  // state, sends a tiny status.get, and force-closes the WS if the probe
+  // fails (which the existing onclose path then turns into a reconnect).
+  function startActivityProbe() {
+    stopActivityProbe()
+    activityProbeTimer = setInterval(() => {
+      // Why: only probe while the channel is actually in 'connected'. The
+      // sendRequest path itself waits for connected, but a probe scheduled
+      // during a reconnect would just stack up timeouts and confuse logs.
+      if (state !== 'connected' || !ws) return
+      const probeWs = ws
+      // Why: short timeout (8s) — server's heartbeat is 15s, so if we
+      // don't see *anything* back within 8s the link is almost certainly
+      // half-open. Using REQUEST_TIMEOUT_MS (30s) here would make the
+      // user wait nearly a minute before reconnect kicks in.
+      const id = nextId()
+      let timedOut = false
+      const timeout = setTimeout(() => {
+        timedOut = true
+        pending.delete(id)
+        // Why: only force-close if this is still the same socket the
+        // probe was sent on; a normal close that already swapped `ws`
+        // shouldn't trigger a redundant terminate.
+        if (probeWs === ws && probeWs.readyState === WebSocket.OPEN) {
+          probeWs.close()
+        }
+      }, 8_000)
+      pending.set(id, {
+        resolve: () => {
+          if (timedOut) return
+          clearTimeout(timeout)
+        },
+        reject: () => {
+          if (timedOut) return
+          clearTimeout(timeout)
+        }
+      })
+      if (!sendEncrypted({ id, deviceToken, method: 'status.get' })) {
+        clearTimeout(timeout)
+        pending.delete(id)
+      }
+    }, ACTIVITY_PROBE_INTERVAL_MS)
+  }
+
+  function stopActivityProbe() {
+    if (activityProbeTimer) {
+      clearInterval(activityProbeTimer)
+      activityProbeTimer = null
+    }
+  }
+
   function rejectAllPending(reason: string) {
     const error = new Error(reason)
     for (const [id, req] of pending) {
@@ -328,13 +441,29 @@ export function connect(
           typeof stream.params === 'object' &&
           typeof (stream.params as { terminal?: unknown }).terminal === 'string'
         ) {
+          // Why: the runtime registers cleanup under the composite key
+          // `${terminal}:${clientId}` so two phones subscribing to the same
+          // terminal handle don't evict each other. Echo that composite key
+          // back on unsubscribe; also include `client.id` so the server can
+          // reconstruct it if a stale build emits a bare-handle id. See
+          // docs/mobile-presence-lock.md.
+          const subscribeParams = stream.params as {
+            terminal: string
+            client?: { id?: string }
+          }
+          const clientId =
+            typeof subscribeParams.client?.id === 'string' ? subscribeParams.client.id : undefined
+          const subscriptionId = clientId
+            ? `${subscribeParams.terminal}:${clientId}`
+            : subscribeParams.terminal
           sendEncrypted({
             id: nextId(),
             deviceToken,
             method: 'terminal.unsubscribe',
-            // Why: the runtime keys terminal subscription cleanup by terminal
-            // handle, not by the RPC request id used to open the stream.
-            params: { subscriptionId: (stream.params as { terminal: string }).terminal }
+            params: {
+              subscriptionId,
+              ...(clientId ? { client: { id: clientId } } : {})
+            }
           })
         }
       }
@@ -344,6 +473,10 @@ export function connect(
       return state
     },
 
+    getReconnectAttempt(): number {
+      return reconnectAttempt
+    },
+
     onStateChange(listener: (state: ConnectionState) => void): () => void {
       stateListeners.add(listener)
       return () => stateListeners.delete(listener)
@@ -355,10 +488,12 @@ export function connect(
         clearTimeout(reconnectTimer)
         reconnectTimer = null
       }
+      clearConnectTimer()
       if (handshakeTimer) {
         clearTimeout(handshakeTimer)
         handshakeTimer = null
       }
+      stopActivityProbe()
       if (ws) {
         ws.close()
         ws = null
diff --git a/mobile/src/transport/types.ts b/mobile/src/transport/types.ts
index c73489a9751..2e9e8fcf7ff 100644
--- a/mobile/src/transport/types.ts
+++ b/mobile/src/transport/types.ts
@@ -60,3 +60,16 @@ export const HostProfileSchema = z.object({
   publicKeyB64: z.string().min(1),
   lastConnected: z.number().finite()
 })
+
+// Why: persisted host record after the v0.0.3 keychain split. The
+// deviceToken is held in iOS Keychain via expo-secure-store and joined
+// in at load time; it must NOT appear in AsyncStorage anymore.
+export const StoredHostProfileSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  endpoint: z.string().min(1),
+  publicKeyB64: z.string().min(1),
+  lastConnected: z.number().finite()
+})
+
+export type StoredHostProfile = z.infer<typeof StoredHostProfileSchema>
diff --git a/mobile/tsconfig.json b/mobile/tsconfig.json
index c07b7787f55..6aea44464c3 100644
--- a/mobile/tsconfig.json
+++ b/mobile/tsconfig.json
@@ -6,5 +6,6 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["**/*.ts", "**/*.tsx"]
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["**/*.test.ts", "**/*.test.tsx"]
 }
diff --git a/package.json b/package.json
index a20272b3ea6..e4f95a336a3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.3.34-rc.1",
+  "version": "1.3.37-rc.1",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",
@@ -104,7 +104,7 @@
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
     "shadcn": "^4.1.0",
-    "simple-git": "^3.33.0",
+    "simple-git": "^3.36.0",
     "sonner": "^2.0.7",
     "ssh2": "^1.17.0",
     "tailwind-merge": "^3.5.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7f0204d0552..0c995a70eb2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -206,8 +206,8 @@ importers:
         specifier: ^4.1.0
         version: 4.1.0(@types/node@25.5.0)(typescript@5.9.3)
       simple-git:
-        specifier: ^3.33.0
-        version: 3.33.0
+        specifier: ^3.36.0
+        version: 3.36.0
       sonner:
         specifier: ^2.0.7
         version: 2.0.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -2338,6 +2338,12 @@ packages:
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
+  '@simple-git/args-pathspec@1.0.3':
+    resolution: {integrity: sha512-ngJMaHlsWDTfjyq9F3VIQ8b7NXbBLq5j9i5bJ6XLYtD6qlDXT7fdKY2KscWWUF8t18xx052Y/PUO1K1TRc9yKA==}
+
+  '@simple-git/argv-parser@1.1.1':
+    resolution: {integrity: sha512-Q9lBcfQ+VQCpQqGJFHe5yooOS5hGdLFFbJ5R+R5aDsnkPCahtn1hSkMcORX65J2Z5lxSkD0lQorMsncuBQxYUw==}
+
   '@sindresorhus/is@4.6.0':
     resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
     engines: {node: '>=10'}
@@ -5797,8 +5803,8 @@ packages:
   simple-get@4.0.1:
     resolution: {integrity: sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==}
 
-  simple-git@3.33.0:
-    resolution: {integrity: sha512-D4V/tGC2sjsoNhoMybKyGoE+v8A60hRawKQ1iFRA1zwuDgGZCBJ4ByOzZ5J8joBbi4Oam0qiPH+GhzmSBwbJng==}
+  simple-git@3.36.0:
+    resolution: {integrity: sha512-cGQjLjK8bxJw4QuYT7gxHw3/IouVESbhahSsHrX97MzCL1gu2u7oy38W6L2ZIGECEfIBG4BabsWDPjBxJENv9Q==}
 
   simple-update-notifier@2.0.0:
     resolution: {integrity: sha512-a2B9Y0KlNXl9u/vsW6sTIu9vGEpfKu2wRV6l1H3XEas/0gUIzGzBoP/IouTcUQbm9JWZLH3COxyn03TYlFax6w==}
@@ -8314,6 +8320,12 @@ snapshots:
 
   '@sec-ant/readable-stream@0.4.1': {}
 
+  '@simple-git/args-pathspec@1.0.3': {}
+
+  '@simple-git/argv-parser@1.1.1':
+    dependencies:
+      '@simple-git/args-pathspec': 1.0.3
+
   '@sindresorhus/is@4.6.0': {}
 
   '@sindresorhus/merge-streams@4.0.0': {}
@@ -12503,10 +12515,12 @@ snapshots:
       once: 1.4.0
       simple-concat: 1.0.1
 
-  simple-git@3.33.0:
+  simple-git@3.36.0:
     dependencies:
       '@kwsites/file-exists': 1.1.1
       '@kwsites/promise-deferred': 1.1.1
+      '@simple-git/args-pathspec': 1.0.3
+      '@simple-git/argv-parser': 1.1.1
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
diff --git a/src/cli/args.ts b/src/cli/args.ts
index f61cfb751a1..7f13996deb3 100644
--- a/src/cli/args.ts
+++ b/src/cli/args.ts
@@ -64,7 +64,7 @@ export function supportsBrowserPageFlag(commandPath: string[]): boolean {
   if (['repo', 'worktree', 'terminal'].includes(commandPath[0])) {
     return false
   }
-  return !['tab list', 'tab create'].includes(joined)
+  return !['tab list', 'tab create', 'tab current'].includes(joined)
 }
 
 export function isCommandGroup(commandPath: string[]): boolean {
diff --git a/src/cli/browser.test.ts b/src/cli/browser.test.ts
index c0f518b8ede..c84a0f7e7b8 100644
--- a/src/cli/browser.test.ts
+++ b/src/cli/browser.test.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- Why: this file groups every CLI browser-command test (page targeting, profiles, waits, viewport) so test-fixture imports and the runtime-client mock stay shared in one place. */
 import path from 'path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -126,6 +127,369 @@ describe('orca cli browser page targeting', () => {
       worktree: `path:${path.resolve('/tmp/repo/feature')}`
     })
   })
+
+  it('passes explicit profile ids to tab create', async () => {
+    queueFixtures(callMock, okFixture('req_create', { browserPageId: 'page-3' }))
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      [
+        'tab',
+        'create',
+        '--url',
+        'https://example.com',
+        '--profile',
+        'work',
+        '--worktree',
+        'all',
+        '--json'
+      ],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith(
+      'browser.tabCreate',
+      {
+        url: 'https://example.com',
+        worktree: undefined,
+        profileId: 'work'
+      },
+      { timeoutMs: 60_000 }
+    )
+  })
+
+  it('passes tab profile updates through by page id', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_set_profile', {
+        browserPageId: 'page-2',
+        profileId: 'work',
+        profileLabel: 'Work'
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'set', '--page', 'page-2', '--profile', 'work', '--json'],
+      '/tmp/repo/feature/src'
+    )
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabSetProfile', {
+      page: 'page-2',
+      profileId: 'work'
+    })
+  })
+
+  it('shows tab profile labels in text mode when requested', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_list', {
+        tabs: [
+          {
+            browserPageId: 'page-1',
+            index: 0,
+            url: 'https://example.com',
+            title: 'Example',
+            active: true,
+            profileId: 'default',
+            profileLabel: 'Default'
+          },
+          {
+            browserPageId: 'page-2',
+            index: 1,
+            url: 'https://mail.example.com',
+            title: 'Mail',
+            active: false,
+            profileId: 'work',
+            profileLabel: 'Work'
+          }
+        ]
+      })
+    )
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['tab', 'list', '--show-profile', '--worktree', 'all'], '/tmp/not-an-orca-worktree')
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabList', { worktree: undefined })
+    expect(logSpy).toHaveBeenCalledWith(
+      '* [0] page-1  Example — https://example.com  [Default]\n' +
+        '  [1] page-2  Mail — https://mail.example.com  [Work]'
+    )
+  })
+
+  it('shows a single tab by page id', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_tab_show', {
+        tab: {
+          browserPageId: 'page-1',
+          index: 0,
+          url: 'https://example.com',
+          title: 'Example',
+          active: true,
+          worktreeId: 'repo::/tmp/repo/feature',
+          profileId: 'work',
+          profileLabel: 'Work'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['tab', 'show', '--page', 'page-1', '--json'], '/tmp/not-an-orca-worktree')
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabShow', { page: 'page-1' })
+  })
+
+  it('resolves the current tab in a worktree', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_tab_current', {
+        tab: {
+          browserPageId: 'page-2',
+          index: 1,
+          url: 'https://mail.example.com',
+          title: 'Mail',
+          active: true,
+          worktreeId: 'repo::/tmp/repo/feature',
+          profileId: 'default',
+          profileLabel: 'Default'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['tab', 'current', '--worktree', 'all', '--json'], '/tmp/not-an-orca-worktree')
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabCurrent', { worktree: undefined })
+  })
+})
+
+describe('orca cli browser tab profiles', () => {
+  beforeEach(() => {
+    callMock.mockReset()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('shows the profile bound to a tab', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_profile_show', {
+        browserPageId: 'page-2',
+        worktreeId: 'repo::/tmp/repo/feature',
+        profileId: 'work',
+        profileLabel: 'Work'
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'show', '--page', 'page-2', '--json'],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabProfileShow', { page: 'page-2' })
+  })
+
+  it('switches a tab back to the default profile', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_profile_default', {
+        browserPageId: 'page-2',
+        profileId: 'default',
+        profileLabel: 'Default'
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'use-default', '--page', 'page-2', '--json'],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabSetProfile', {
+      page: 'page-2',
+      profileId: 'default'
+    })
+  })
+
+  it('clones a tab into a different profile', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_profile_clone', {
+        browserPageId: 'page-9',
+        sourceBrowserPageId: 'page-2',
+        profileId: 'work',
+        profileLabel: 'Work'
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'clone', '--page', 'page-2', '--profile', 'work', '--json'],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.tabProfileClone', {
+      page: 'page-2',
+      profileId: 'work'
+    })
+  })
+})
+
+describe('orca cli browser tab profiles', () => {
+  beforeEach(() => {
+    callMock.mockReset()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('lists browser tab profiles', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_profiles', {
+        profiles: [
+          { id: 'default', scope: 'default', label: 'Default', partition: 'persist:orca-browser' },
+          {
+            id: 'work',
+            scope: 'isolated',
+            label: 'Work',
+            partition: 'persist:orca-browser-session-work'
+          }
+        ]
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['tab', 'profile', 'list', '--json'], '/tmp/not-an-orca-worktree')
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.profileList')
+  })
+
+  it('reports an empty browser tab profile list with a friendly message', async () => {
+    queueFixtures(callMock, okFixture('req_profiles', { profiles: [] }))
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['tab', 'profile', 'list'], '/tmp/not-an-orca-worktree')
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.profileList')
+    expect(logSpy).toHaveBeenCalledWith('No browser profiles found.')
+  })
+
+  it('creates isolated browser tab profiles by default', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_profile_create', {
+        profile: {
+          id: 'work',
+          scope: 'isolated',
+          label: 'Work',
+          partition: 'persist:orca-browser-session-work'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'create', '--label', 'Work', '--json'],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.profileCreate', {
+      label: 'Work',
+      scope: 'isolated'
+    })
+  })
+
+  it('forwards --scope imported through to the runtime', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_profile_create', {
+        profile: {
+          id: 'imp',
+          scope: 'imported',
+          label: 'From Chrome',
+          partition: 'persist:orca-browser-session-imp'
+        }
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'create', '--label', 'From Chrome', '--scope', 'imported', '--json'],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).toHaveBeenCalledWith('browser.profileCreate', {
+      label: 'From Chrome',
+      scope: 'imported'
+    })
+  })
+
+  it('rejects unknown --scope values instead of silently defaulting to isolated', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'create', '--label', 'Work', '--scope', 'isloated'],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).not.toHaveBeenCalled()
+    expect(errorSpy).toHaveBeenCalledWith('--scope must be "isolated" or "imported"')
+  })
+
+  it('surfaces a runtime error if the registry refuses to create a profile', async () => {
+    queueFixtures(callMock, okFixture('req_profile_create', { profile: null }))
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    await main(['tab', 'profile', 'create', '--label', 'Bogus'], '/tmp/not-an-orca-worktree')
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Failed to create browser profile (label=Bogus, scope=isolated)'
+    )
+  })
+
+  it('deletes browser tab profiles by id', async () => {
+    queueFixtures(callMock, okFixture('req_profile_delete', { deleted: true, profileId: 'work' }))
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(
+      ['tab', 'profile', 'delete', '--profile', 'work', '--json'],
+      '/tmp/not-an-orca-worktree'
+    )
+
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock).toHaveBeenCalledWith('browser.profileDelete', { profileId: 'work' })
+  })
+
+  it('reports a not-deleted profile in text mode without throwing', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_profile_delete', { deleted: false, profileId: 'default' })
+    )
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main(['tab', 'profile', 'delete', '--profile', 'default'], '/tmp/not-an-orca-worktree')
+
+    expect(callMock).toHaveBeenCalledWith('browser.profileDelete', { profileId: 'default' })
+    expect(logSpy).toHaveBeenCalledWith('Profile default was not deleted')
+  })
 })
 
 describe('orca cli browser waits and viewport flags', () => {
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index 5b245c99230..6dd41e3a554 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -7,6 +7,7 @@ import { TERMINAL_HANDLERS } from './handlers/terminal'
 import { BROWSER_NAV_HANDLERS } from './handlers/browser-nav'
 import { BROWSER_INTERACT_HANDLERS } from './handlers/browser-interact'
 import { BROWSER_TAB_HANDLERS } from './handlers/browser-tab'
+import { BROWSER_PROFILE_HANDLERS } from './handlers/browser-profile'
 import { BROWSER_COOKIE_HANDLERS } from './handlers/browser-cookie'
 import { BROWSER_CAPTURE_HANDLERS } from './handlers/browser-capture'
 import { BROWSER_ENV_HANDLERS } from './handlers/browser-env'
@@ -32,6 +33,7 @@ function buildHandlers(): Map<string, CommandHandler> {
     BROWSER_NAV_HANDLERS,
     BROWSER_INTERACT_HANDLERS,
     BROWSER_TAB_HANDLERS,
+    BROWSER_PROFILE_HANDLERS,
     BROWSER_COOKIE_HANDLERS,
     BROWSER_CAPTURE_HANDLERS,
     BROWSER_ENV_HANDLERS,
diff --git a/src/cli/format.ts b/src/cli/format.ts
index b1d1ac43269..2ea429e13a1 100644
--- a/src/cli/format.ts
+++ b/src/cli/format.ts
@@ -1,7 +1,12 @@
 import type {
+  BrowserProfileListResult,
+  BrowserTabCurrentResult,
   BrowserScreenshotResult,
   BrowserSnapshotResult,
   BrowserTabListResult,
+  BrowserTabProfileCloneResult,
+  BrowserTabProfileShowResult,
+  BrowserTabShowResult,
   CliStatusResult,
   RuntimeRepoList,
   RuntimeRepoSearchRefs,
@@ -237,13 +242,59 @@ export function formatScreenshot(result: BrowserScreenshotResult): string {
 }
 
 export function formatTabList(result: BrowserTabListResult): string {
+  return formatTabListWithProfiles(result, false)
+}
+
+export function formatTabListWithProfiles(
+  result: BrowserTabListResult,
+  showProfile: boolean
+): string {
   if (result.tabs.length === 0) {
     return 'No browser tabs open.'
   }
   return result.tabs
     .map((t) => {
       const marker = t.active ? '* ' : '  '
-      return `${marker}[${t.index}] ${t.browserPageId}  ${t.title} — ${t.url}`
+      const profile = showProfile ? `  [${t.profileLabel ?? t.profileId ?? 'Unknown'}]` : ''
+      return `${marker}[${t.index}] ${t.browserPageId}  ${t.title} — ${t.url}${profile}`
     })
     .join('\n')
 }
+
+export function formatBrowserProfileList(result: BrowserProfileListResult): string {
+  if (result.profiles.length === 0) {
+    return 'No browser profiles found.'
+  }
+  return result.profiles
+    .map((profile) => {
+      const marker = profile.scope === 'default' ? '* ' : '  '
+      const source = profile.source?.browserFamily ?? 'none'
+      return `${marker}${profile.id}  ${profile.label}  ${profile.scope}  source:${source}`
+    })
+    .join('\n')
+}
+
+export function formatTabShow(result: BrowserTabShowResult | BrowserTabCurrentResult): string {
+  const tab = result.tab
+  return [
+    `page: ${tab.browserPageId}`,
+    `title: ${tab.title}`,
+    `url: ${tab.url}`,
+    `active: ${tab.active}`,
+    `worktree: ${tab.worktreeId ?? 'unknown'}`,
+    `profile: ${tab.profileLabel ?? tab.profileId ?? 'unknown'}`
+  ].join('\n')
+}
+
+export function formatTabProfileShow(result: BrowserTabProfileShowResult): string {
+  return [
+    `page: ${result.browserPageId}`,
+    `worktree: ${result.worktreeId ?? 'unknown'}`,
+    `profileId: ${result.profileId ?? 'default'}`,
+    `profile: ${result.profileLabel ?? result.profileId ?? 'default'}`
+  ].join('\n')
+}
+
+export function formatTabProfileClone(result: BrowserTabProfileCloneResult): string {
+  return `Cloned ${result.sourceBrowserPageId} to ${result.browserPageId} (${result.profileLabel ?? result.profileId ?? 'default'})`
+}
diff --git a/src/cli/handlers/browser-profile.ts b/src/cli/handlers/browser-profile.ts
new file mode 100644
index 00000000000..4dc8ad731b3
--- /dev/null
+++ b/src/cli/handlers/browser-profile.ts
@@ -0,0 +1,106 @@
+import type {
+  BrowserProfileCreateResult,
+  BrowserProfileDeleteResult,
+  BrowserProfileListResult,
+  BrowserTabProfileCloneResult,
+  BrowserTabProfileShowResult,
+  BrowserTabSetProfileResult
+} from '../../shared/runtime-types'
+import type { CommandHandler } from '../dispatch'
+import { getOptionalStringFlag, getRequiredStringFlag } from '../flags'
+import {
+  formatBrowserProfileList,
+  formatTabProfileClone,
+  formatTabProfileShow,
+  printResult
+} from '../format'
+import { RuntimeClientError } from '../runtime-client'
+import { getBrowserCommandTarget } from '../selectors'
+
+function parseScopeFlag(flags: Map<string, string | boolean>): 'isolated' | 'imported' {
+  const raw = getOptionalStringFlag(flags, 'scope')
+  if (raw === undefined || raw === 'isolated') {
+    return 'isolated'
+  }
+  if (raw === 'imported') {
+    return 'imported'
+  }
+  throw new RuntimeClientError('invalid_argument', '--scope must be "isolated" or "imported"')
+}
+
+export const BROWSER_PROFILE_HANDLERS: Record<string, CommandHandler> = {
+  'tab profile list': async ({ client, json }) => {
+    const result = await client.call<BrowserProfileListResult>('browser.profileList')
+    printResult(result, json, formatBrowserProfileList)
+  },
+  'tab profile create': async ({ flags, client, json }) => {
+    const label = getRequiredStringFlag(flags, 'label')
+    const scope = parseScopeFlag(flags)
+    const result = await client.call<BrowserProfileCreateResult>('browser.profileCreate', {
+      label,
+      scope
+    })
+    if (result.result.profile === null) {
+      // Why: registry refuses non-isolated/imported scopes; we already validated
+      // the scope client-side, so a null here means a server-side rejection we
+      // shouldn't silently report as success.
+      throw new RuntimeClientError(
+        'runtime_error',
+        `Failed to create browser profile (label=${label}, scope=${scope})`
+      )
+    }
+    printResult(
+      result,
+      json,
+      (value) =>
+        `Created profile ${value.profile?.id ?? 'unknown'} (${value.profile?.label ?? label})`
+    )
+  },
+  'tab profile delete': async ({ flags, client, json }) => {
+    const profileId = getRequiredStringFlag(flags, 'profile')
+    const result = await client.call<BrowserProfileDeleteResult>('browser.profileDelete', {
+      profileId
+    })
+    printResult(result, json, (value) =>
+      value.deleted
+        ? `Deleted profile ${value.profileId}`
+        : `Profile ${value.profileId} was not deleted`
+    )
+  },
+  'tab profile set': async ({ flags, client, cwd, json }) => {
+    const profileId = getRequiredStringFlag(flags, 'profile')
+    const target = await getBrowserCommandTarget(flags, cwd, client)
+    const result = await client.call<BrowserTabSetProfileResult>('browser.tabSetProfile', {
+      ...target,
+      profileId
+    })
+    printResult(
+      result,
+      json,
+      (value) =>
+        `Switched ${value.browserPageId} to ${value.profileLabel ?? value.profileId ?? 'default'}`
+    )
+  },
+  'tab profile show': async ({ flags, client, cwd, json }) => {
+    const target = await getBrowserCommandTarget(flags, cwd, client)
+    const result = await client.call<BrowserTabProfileShowResult>('browser.tabProfileShow', target)
+    printResult(result, json, formatTabProfileShow)
+  },
+  'tab profile use-default': async ({ flags, client, cwd, json }) => {
+    const target = await getBrowserCommandTarget(flags, cwd, client)
+    const result = await client.call<BrowserTabSetProfileResult>('browser.tabSetProfile', {
+      ...target,
+      profileId: 'default'
+    })
+    printResult(result, json, (value) => `Switched ${value.browserPageId} to Default`)
+  },
+  'tab profile clone': async ({ flags, client, cwd, json }) => {
+    const profileId = getRequiredStringFlag(flags, 'profile')
+    const target = await getBrowserCommandTarget(flags, cwd, client)
+    const result = await client.call<BrowserTabProfileCloneResult>('browser.tabProfileClone', {
+      ...target,
+      profileId
+    })
+    printResult(result, json, formatTabProfileClone)
+  }
+}
diff --git a/src/cli/handlers/browser-tab.ts b/src/cli/handlers/browser-tab.ts
index e842cd33c14..0fe3e151b4f 100644
--- a/src/cli/handlers/browser-tab.ts
+++ b/src/cli/handlers/browser-tab.ts
@@ -1,6 +1,11 @@
-import type { BrowserTabListResult, BrowserTabSwitchResult } from '../../shared/runtime-types'
+import type {
+  BrowserTabCurrentResult,
+  BrowserTabListResult,
+  BrowserTabShowResult,
+  BrowserTabSwitchResult
+} from '../../shared/runtime-types'
 import type { CommandHandler } from '../dispatch'
-import { formatTabList, printResult } from '../format'
+import { formatTabList, formatTabListWithProfiles, formatTabShow, printResult } from '../format'
 import {
   getOptionalNonNegativeIntegerFlag,
   getOptionalStringFlag,
@@ -13,7 +18,20 @@ export const BROWSER_TAB_HANDLERS: Record<string, CommandHandler> = {
   'tab list': async ({ flags, client, cwd, json }) => {
     const worktree = await getBrowserWorktreeSelector(flags, cwd, client)
     const result = await client.call<BrowserTabListResult>('browser.tabList', { worktree })
-    printResult(result, json, formatTabList)
+    const showProfile = flags.has('show-profile')
+    printResult(result, json, (value) =>
+      showProfile ? formatTabListWithProfiles(value, true) : formatTabList(value)
+    )
+  },
+  'tab show': async ({ flags, client, cwd, json }) => {
+    const target = await getBrowserCommandTarget(flags, cwd, client)
+    const result = await client.call<BrowserTabShowResult>('browser.tabShow', target)
+    printResult(result, json, formatTabShow)
+  },
+  'tab current': async ({ flags, client, cwd, json }) => {
+    const worktree = await getBrowserWorktreeSelector(flags, cwd, client)
+    const result = await client.call<BrowserTabCurrentResult>('browser.tabCurrent', { worktree })
+    printResult(result, json, formatTabShow)
   },
   'tab switch': async ({ flags, client, cwd, json }) => {
     const index = getOptionalNonNegativeIntegerFlag(flags, 'index')
@@ -34,10 +52,11 @@ export const BROWSER_TAB_HANDLERS: Record<string, CommandHandler> = {
   },
   'tab create': async ({ flags, client, cwd, json }) => {
     const url = getOptionalStringFlag(flags, 'url')
+    const profileId = getOptionalStringFlag(flags, 'profile')
     const worktree = await getBrowserWorktreeSelector(flags, cwd, client)
     const result = await client.call<{ browserPageId: string }>(
       'browser.tabCreate',
-      { url, worktree },
+      { url, worktree, profileId },
       { timeoutMs: 60_000 }
     )
     printResult(result, json, (v) => `Created tab ${v.browserPageId}`)
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 2e8f6ddb9f5..3adb9cc9810 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -59,6 +59,15 @@ Orchestration:
 Browser Automation:
   tab create                Create a new browser tab (navigates to --url)
   tab list                  List open browser tabs
+  tab show                  Show one browser tab by page id
+  tab current               Show the current browser tab
+  tab profile list          List browser session profiles
+  tab profile create        Create a browser session profile
+  tab profile delete        Delete a browser session profile
+  tab profile set           Switch a browser tab to a different profile
+  tab profile show          Show the profile bound to a browser tab
+  tab profile use-default   Switch a browser tab back to the default profile
+  tab profile clone         Clone a browser tab into another profile
   tab switch                Switch the active browser tab by --index or --page
   tab close                 Close a browser tab by --index/--page or the current tab
   snapshot                  Accessibility snapshot with element refs (e.g. @e1, @e2)
@@ -183,6 +192,8 @@ Browser Options:
   --amount <pixels>         Scroll distance in pixels (default: viewport height)
   --index <n>               Tab index (from \`tab list\`)
   --page <id>               Stable browser page id (preferred for concurrent workflows)
+  --profile <id>            Browser profile id
+  --show-profile            Include the tab's browser profile in text output
   --format <png|jpeg>       Screenshot image format
   --from <ref>              Drag source element ref
   --to <ref>                Drag target element ref
@@ -202,7 +213,10 @@ Examples:
   $ orca terminal list --worktree path:/Users/me/orca/workspaces/orca/cli-test-1 --json
   $ orca terminal send --terminal term_123 --text "hi" --enter
   $ orca terminal wait --terminal term_123 --for exit --timeout-ms 60000 --json
-  $ orca tab create --url https://example.com
+  $ orca tab current --json
+  $ orca tab show --page page_123 --json
+  $ orca tab create --url https://example.com --profile work
+  $ orca tab profile clone --page page_123 --profile work --json
   $ orca snapshot
   $ orca click --element e3
   $ orca fill --element e5 --value "hello"
@@ -306,6 +320,8 @@ export function formatFlagHelp(flag: string): string {
     amount: '--amount <pixels>      Scroll distance in pixels',
     index: '--index <n>            Tab index to switch to',
     page: '--page <id>            Stable browser page id from `orca tab list --json`',
+    profile: '--profile <id>        Browser profile id',
+    'show-profile': '--show-profile        Include tab profile in text output',
     format: '--format <png|jpeg>    Screenshot image format'
   }
 
diff --git a/src/cli/specs/browser-basic.ts b/src/cli/specs/browser-basic.ts
index 8a1e0289330..42af901ab09 100644
--- a/src/cli/specs/browser-basic.ts
+++ b/src/cli/specs/browser-basic.ts
@@ -154,7 +154,19 @@ export const BROWSER_BASIC_COMMAND_SPECS: CommandSpec[] = [
   {
     path: ['tab', 'list'],
     summary: 'List open browser tabs',
-    usage: 'orca tab list [--worktree <selector|all>] [--json]',
+    usage: 'orca tab list [--worktree <selector|all>] [--show-profile] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'worktree', 'show-profile']
+  },
+  {
+    path: ['tab', 'show'],
+    summary: 'Show one browser tab by page id',
+    usage: 'orca tab show --page <id> [--worktree <selector>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'worktree']
+  },
+  {
+    path: ['tab', 'current'],
+    summary: 'Show the current browser tab',
+    usage: 'orca tab current [--worktree <selector|all>] [--json]',
     allowedFlags: [...GLOBAL_FLAGS, 'worktree']
   },
   {
@@ -166,8 +178,50 @@ export const BROWSER_BASIC_COMMAND_SPECS: CommandSpec[] = [
   {
     path: ['tab', 'create'],
     summary: 'Create a new browser tab in the current worktree',
-    usage: 'orca tab create [--url <url>] [--worktree <selector>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'url', 'worktree']
+    usage: 'orca tab create [--url <url>] [--worktree <selector>] [--profile <id>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'url', 'worktree', 'profile']
+  },
+  {
+    path: ['tab', 'profile', 'list'],
+    summary: 'List browser session profiles available to browser tabs',
+    usage: 'orca tab profile list [--json]',
+    allowedFlags: [...GLOBAL_FLAGS]
+  },
+  {
+    path: ['tab', 'profile', 'create'],
+    summary: 'Create a browser session profile for browser tabs',
+    usage: 'orca tab profile create --label <name> [--scope <isolated|imported>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'label', 'scope']
+  },
+  {
+    path: ['tab', 'profile', 'delete'],
+    summary: 'Delete a browser session profile used by browser tabs',
+    usage: 'orca tab profile delete --profile <id> [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'profile']
+  },
+  {
+    path: ['tab', 'profile', 'set'],
+    summary: 'Switch a browser tab to a different browser profile',
+    usage: 'orca tab profile set (--page <id> | --worktree <selector>) --profile <id> [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'profile', 'worktree']
+  },
+  {
+    path: ['tab', 'profile', 'show'],
+    summary: 'Show the browser profile bound to a tab',
+    usage: 'orca tab profile show --page <id> [--worktree <selector>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'worktree']
+  },
+  {
+    path: ['tab', 'profile', 'use-default'],
+    summary: 'Switch a browser tab back to the default browser profile',
+    usage: 'orca tab profile use-default --page <id> [--worktree <selector>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'worktree']
+  },
+  {
+    path: ['tab', 'profile', 'clone'],
+    summary: 'Clone a browser tab into a different browser profile',
+    usage: 'orca tab profile clone --profile <id> [--page <id>] [--worktree <selector>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'profile', 'worktree']
   },
   {
     path: ['tab', 'close'],
diff --git a/src/main/agent-hooks/server.test.ts b/src/main/agent-hooks/server.test.ts
index d12c7375435..ba321dc1799 100644
--- a/src/main/agent-hooks/server.test.ts
+++ b/src/main/agent-hooks/server.test.ts
@@ -660,6 +660,22 @@ describe('OpenCode hook normalization', () => {
     expect(result?.payload.state).toBe('waiting')
   })
 
+  it('AskUserQuestion maps to waiting', () => {
+    // Why: OpenCode emits `question.asked` when the agent uses an ask-the-user
+    // tool (distinct from `permission.asked`, which blocks on tool approval).
+    // Both leave the agent idle-but-waiting on a human, so both must render
+    // the same red "needs attention" indicator. Without this mapping the pane
+    // silently stays in `working` and the user has no visual cue that the
+    // agent is waiting on them.
+    const result = _internals.normalizeHookPayload(
+      'opencode',
+      buildBody({ hook_event_name: 'AskUserQuestion' }),
+      'production'
+    )
+    expect(result?.payload.state).toBe('waiting')
+    expect(result?.payload.agentType).toBe('opencode')
+  })
+
   it('unknown event name returns null', () => {
     const result = _internals.normalizeHookPayload(
       'opencode',
diff --git a/src/main/agent-hooks/server.ts b/src/main/agent-hooks/server.ts
index aee9c83e780..92db2823b2b 100644
--- a/src/main/agent-hooks/server.ts
+++ b/src/main/agent-hooks/server.ts
@@ -844,11 +844,13 @@ function normalizeCodexEvent(
 
 // Why: OpenCode has no declarative hook surface — it exposes in-process plugin
 // events (session.status busy/idle, session.idle, permission.asked,
-// message.updated, message.part.updated). The bundled plugin (see
-// opencode/hook-service) pre-maps those to our stable hook_event_name
+// question.asked, message.updated, message.part.updated). The bundled plugin
+// (see opencode/hook-service) pre-maps those to our stable hook_event_name
 // vocabulary before POSTing so this normalizer can share the same switch
 // shape as Claude/Codex/Gemini. SessionBusy = turn started, SessionIdle =
-// turn finished, PermissionRequest = blocked on user approval, MessagePart =
+// turn finished, PermissionRequest = blocked on user approval, AskUserQuestion =
+// blocked on user reply to an ask-the-user tool (both map to `waiting` so the
+// sidebar renders the red "needs attention" indicator), MessagePart =
 // incremental text from user prompt or assistant reply (stays in `working`
 // because streaming chunks must not flip the row to done mid-turn).
 function normalizeOpenCodeEvent(
@@ -862,7 +864,7 @@ function normalizeOpenCodeEvent(
       ? 'working'
       : eventName === 'SessionIdle'
         ? 'done'
-        : eventName === 'PermissionRequest'
+        : eventName === 'PermissionRequest' || eventName === 'AskUserQuestion'
           ? 'waiting'
           : null
 
diff --git a/src/main/agent-trust-presets.test.ts b/src/main/agent-trust-presets.test.ts
new file mode 100644
index 00000000000..df328ad647d
--- /dev/null
+++ b/src/main/agent-trust-presets.test.ts
@@ -0,0 +1,113 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const testState = {
+  fakeHomeDir: ''
+}
+
+vi.mock('node:os', async () => {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-imports -- vi.importActual requires inline import()
+  const actual = await vi.importActual<typeof import('node:os')>('node:os')
+  return {
+    ...actual,
+    homedir: () => testState.fakeHomeDir
+  }
+})
+
+const { markCopilotFolderTrusted, markCursorWorkspaceTrusted } =
+  await import('./agent-trust-presets')
+
+beforeEach(() => {
+  testState.fakeHomeDir = mkdtempSync(join(tmpdir(), 'orca-trust-presets-'))
+})
+
+afterEach(() => {
+  rmSync(testState.fakeHomeDir, { recursive: true, force: true })
+  testState.fakeHomeDir = ''
+})
+
+describe('markCursorWorkspaceTrusted', () => {
+  it('writes ~/.cursor/projects/<slug>/.workspace-trusted with the cwd payload', () => {
+    const workspace = mkdtempSync(join(tmpdir(), 'orca-cursor-ws-'))
+    try {
+      markCursorWorkspaceTrusted(workspace)
+      const projectsDir = join(testState.fakeHomeDir, '.cursor', 'projects')
+      const slugDirs = readdirSync(projectsDir)
+      expect(slugDirs.length).toBe(1)
+      const trustFile = join(projectsDir, slugDirs[0], '.workspace-trusted')
+      expect(existsSync(trustFile)).toBe(true)
+      const payload = JSON.parse(readFileSync(trustFile, 'utf-8'))
+      expect(payload.workspacePath).toBeTruthy()
+      expect(typeof payload.trustedAt).toBe('string')
+    } finally {
+      rmSync(workspace, { recursive: true, force: true })
+    }
+  })
+
+  it('is idempotent — re-marking the same workspace does not overwrite trustedAt', () => {
+    const workspace = mkdtempSync(join(tmpdir(), 'orca-cursor-ws-'))
+    try {
+      markCursorWorkspaceTrusted(workspace)
+      const projectsDir = join(testState.fakeHomeDir, '.cursor', 'projects')
+      const slugDirs = readdirSync(projectsDir)
+      const trustFile = join(projectsDir, slugDirs[0], '.workspace-trusted')
+      const firstPayload = readFileSync(trustFile, 'utf-8')
+      markCursorWorkspaceTrusted(workspace)
+      const secondPayload = readFileSync(trustFile, 'utf-8')
+      expect(secondPayload).toBe(firstPayload)
+    } finally {
+      rmSync(workspace, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('markCopilotFolderTrusted', () => {
+  it('appends the workspace to trustedFolders in ~/.copilot/config.json', () => {
+    const workspace = mkdtempSync(join(tmpdir(), 'orca-copilot-ws-'))
+    try {
+      markCopilotFolderTrusted(workspace)
+      const configPath = join(testState.fakeHomeDir, '.copilot', 'config.json')
+      expect(existsSync(configPath)).toBe(true)
+      const parsed = JSON.parse(readFileSync(configPath, 'utf-8'))
+      expect(Array.isArray(parsed.trustedFolders)).toBe(true)
+      expect(parsed.trustedFolders.length).toBe(1)
+      expect(typeof parsed.trustedFolders[0]).toBe('string')
+    } finally {
+      rmSync(workspace, { recursive: true, force: true })
+    }
+  })
+
+  it('preserves existing config keys and dedups already-trusted folders', () => {
+    const workspace = mkdtempSync(join(tmpdir(), 'orca-copilot-ws-'))
+    const realpath = realpathSync(workspace)
+    try {
+      mkdirSync(join(testState.fakeHomeDir, '.copilot'), { recursive: true })
+      writeFileSync(
+        join(testState.fakeHomeDir, '.copilot', 'config.json'),
+        JSON.stringify({
+          firstLaunchAt: '2026-01-01T00:00:00.000Z',
+          trustedFolders: [realpath]
+        })
+      )
+      markCopilotFolderTrusted(workspace)
+      const parsed = JSON.parse(
+        readFileSync(join(testState.fakeHomeDir, '.copilot', 'config.json'), 'utf-8')
+      )
+      expect(parsed.firstLaunchAt).toBe('2026-01-01T00:00:00.000Z')
+      expect(parsed.trustedFolders).toHaveLength(1)
+    } finally {
+      rmSync(workspace, { recursive: true, force: true })
+    }
+  })
+})
diff --git a/src/main/agent-trust-presets.ts b/src/main/agent-trust-presets.ts
new file mode 100644
index 00000000000..e6c87c52b3f
--- /dev/null
+++ b/src/main/agent-trust-presets.ts
@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { writeFileAtomically } from './codex-accounts/fs-utils'
+
+/**
+ * Pre-mark a workspace as trusted for cursor-agent / GitHub Copilot CLI so
+ * the agent's "Do you trust this folder?" menu does not fire on first launch.
+ *
+ * Why: Orca's "drop URL into agent input as a draft" flow injects the URL
+ * via bracketed-paste once the TUI is up. If the trust menu intercepts the
+ * keystrokes (each menu reads a single character or numbered option), the
+ * paste either selects an arbitrary option or quits the session. Pre-writing
+ * the same trust artifacts that the agent writes after the user accepts is
+ * the only documented bypass — both CLIs read these files at startup before
+ * showing the menu.
+ *
+ * Side note: a `--trust`-style CLI flag exists in cursor-agent but only
+ * applies in `--print/headless` mode (per its --help). Copilot has no
+ * documented flag at all (verified against @github/copilot 1.0.32 bundle).
+ */
+
+/**
+ * Cursor's CLI keeps a per-workspace trust marker at:
+ *   ~/.cursor/projects/<slug>/.workspace-trusted
+ * where <slug> is the absolute path with the leading `/` stripped and
+ * remaining `/` replaced with `-`. The file payload is `{ trustedAt,
+ * workspacePath }`. Verified against the cursor-agent CLI bundle
+ * (versions/2026.04.17-787b533/index.ts: `_=".workspace-trusted"`, slug
+ * derived via the same util that resolves `~/.cursor/projects/<slug>`).
+ */
+export function markCursorWorkspaceTrusted(workspacePath: string): void {
+  const absPath = canonicalize(workspacePath)
+  const slug = cursorWorkspaceSlug(absPath)
+  if (!slug) {
+    return
+  }
+  const trustDir = join(homedir(), '.cursor', 'projects', slug)
+  const trustFile = join(trustDir, '.workspace-trusted')
+  if (existsSync(trustFile)) {
+    return
+  }
+  mkdirSync(trustDir, { recursive: true })
+  const payload = JSON.stringify(
+    { trustedAt: new Date().toISOString(), workspacePath: absPath },
+    null,
+    2
+  )
+  writeFileAtomically(trustFile, `${payload}\n`)
+}
+
+/**
+ * GitHub Copilot CLI keeps a global list of trusted folders in
+ * ~/.copilot/config.json under `trustedFolders` (verified against the
+ * @github/copilot 1.0.32 bundle: `addTrustedFolder` and `isFolderTrusted`
+ * both read/write this exact key, and folder comparison is done after a
+ * realpath() resolution).
+ *
+ * We append to the array in-place so unrelated config keys (loggedInUsers,
+ * copilotTokens, etc.) survive untouched.
+ */
+export function markCopilotFolderTrusted(workspacePath: string): void {
+  const absPath = canonicalize(workspacePath)
+  const configDir = join(homedir(), '.copilot')
+  const configPath = join(configDir, 'config.json')
+  let config: Record<string, unknown> = {}
+  try {
+    if (existsSync(configPath)) {
+      const raw = readFileSync(configPath, 'utf-8')
+      const parsed = JSON.parse(raw)
+      if (parsed && typeof parsed === 'object') {
+        config = parsed as Record<string, unknown>
+      }
+    }
+  } catch {
+    // Why: a corrupted config.json is the user's to fix — refuse to overwrite
+    // it from this side-effect path. Copilot will rewrite the file itself
+    // after the user accepts the trust prompt manually.
+    return
+  }
+  const existing = Array.isArray(config.trustedFolders) ? (config.trustedFolders as unknown[]) : []
+  const normalizedExisting = existing.map((entry) =>
+    typeof entry === 'string' ? canonicalize(entry) : null
+  )
+  if (normalizedExisting.includes(absPath)) {
+    return
+  }
+  const next = [...existing.filter((e) => typeof e === 'string'), absPath]
+  config.trustedFolders = next
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true })
+  }
+  writeFileAtomically(configPath, `${JSON.stringify(config, null, 2)}\n`)
+}
+
+function canonicalize(p: string): string {
+  // Why: macOS reports `/tmp/x` and `/private/tmp/x` as the same inode, but
+  // both Cursor and Copilot's trust comparators run realpath() before the
+  // string compare. Mirror that so a worktree under a symlinked parent
+  // (orca caches realpath()'d worktree paths) matches the agent's lookup.
+  try {
+    if (existsSync(p)) {
+      return realpathSync(p)
+    }
+  } catch {
+    // Fall through to the raw input.
+  }
+  return p
+}
+
+function cursorWorkspaceSlug(absPath: string): string {
+  const stripped = absPath.replace(/^[\\/]+/, '')
+  const slug = stripped.replace(/[\\/]+/g, '-')
+  return slug
+}
diff --git a/src/main/browser/browser-guest-ui.ts b/src/main/browser/browser-guest-ui.ts
index a448f6fdf4b..9bc0370ec17 100644
--- a/src/main/browser/browser-guest-ui.ts
+++ b/src/main/browser/browser-guest-ui.ts
@@ -345,7 +345,7 @@ export function setupGuestShortcutForwarding(args: {
         return () => renderer.send('ui:openQuickOpen')
       }
       if (action?.type === 'openNewWorkspace') {
-        return () => renderer.send('ui:openNewWorkspace', action.tab)
+        return () => renderer.send('ui:openNewWorkspace')
       }
       if (action?.type === 'jumpToWorktreeIndex') {
         return () => renderer.send('ui:jumpToWorktreeIndex', action.index)
diff --git a/src/main/browser/browser-manager.test.ts b/src/main/browser/browser-manager.test.ts
index 192c8aaf3b1..4a21b095b76 100644
--- a/src/main/browser/browser-manager.test.ts
+++ b/src/main/browser/browser-manager.test.ts
@@ -131,6 +131,32 @@ describe('browserManager', () => {
     })
   })
 
+  it('remembers the registered session profile for a browser page', () => {
+    const guest = {
+      id: 104,
+      isDestroyed: vi.fn(() => false),
+      getType: vi.fn(() => 'webview'),
+      setBackgroundThrottling: guestSetBackgroundThrottlingMock,
+      setWindowOpenHandler: guestSetWindowOpenHandlerMock,
+      on: guestOnMock,
+      off: guestOffMock,
+      openDevTools: guestOpenDevToolsMock
+    }
+    webContentsFromIdMock.mockReturnValue(guest)
+
+    browserManager.attachGuestPolicies(guest as never)
+    browserManager.registerGuest({
+      browserPageId: 'browser-1',
+      workspaceId: 'workspace-1',
+      worktreeId: 'wt-1',
+      webContentsId: guest.id,
+      rendererWebContentsId,
+      sessionProfileId: 'work'
+    })
+
+    expect(browserManager.getSessionProfileIdForTab('browser-1')).toBe('work')
+  })
+
   it('falls back to opening popup URLs externally before a guest is registered', () => {
     const guest = {
       id: 105,
diff --git a/src/main/browser/browser-manager.ts b/src/main/browser/browser-manager.ts
index 1a5996d1e13..fb89bbd6b47 100644
--- a/src/main/browser/browser-manager.ts
+++ b/src/main/browser/browser-manager.ts
@@ -55,6 +55,7 @@ export type BrowserGuestRegistration = {
   browserTabId?: string
   workspaceId?: string
   worktreeId?: string
+  sessionProfileId?: string | null
   webContentsId: number
   rendererWebContentsId: number
 }
@@ -97,6 +98,7 @@ export class BrowserManager {
   // visibility/focus state is keyed by browser workspace id. Screenshot prep
   // has to bridge that mismatch to activate the right tab before capture.
   private readonly workspaceIdByPageId = new Map<string, string>()
+  private readonly sessionProfileIdByPageId = new Map<string, string | null>()
   private readonly rendererWebContentsIdByTabId = new Map<string, number>()
   // Why: chain setViewportOverride calls per tab so rapid toggles don't
   // interleave CDP commands. Without serialization, two concurrent calls can
@@ -543,6 +545,7 @@ export class BrowserManager {
     browserTabId: legacyBrowserTabId,
     workspaceId,
     worktreeId,
+    sessionProfileId,
     webContentsId,
     rendererWebContentsId
   }: BrowserGuestRegistration): void {
@@ -592,6 +595,7 @@ export class BrowserManager {
     if (workspaceId) {
       this.workspaceIdByPageId.set(browserTabId, workspaceId)
     }
+    this.sessionProfileIdByPageId.set(browserTabId, sessionProfileId ?? null)
     this.rendererWebContentsIdByTabId.set(browserTabId, rendererWebContentsId)
     if (worktreeId) {
       this.worktreeIdByTabId.set(browserTabId, worktreeId)
@@ -655,6 +659,7 @@ export class BrowserManager {
     this.webContentsIdByTabId.delete(browserTabId)
     this.rendererWebContentsIdByTabId.delete(browserTabId)
     this.workspaceIdByPageId.delete(browserTabId)
+    this.sessionProfileIdByPageId.delete(browserTabId)
     this.worktreeIdByTabId.delete(browserTabId)
     // Why: drop any pending viewport-op chain for this tab so the Map doesn't
     // retain a resolved promise keyed to a destroyed guest.
@@ -681,6 +686,7 @@ export class BrowserManager {
     this.policyCleanupByGuestId.clear()
     this.tabIdByWebContentsId.clear()
     this.worktreeIdByTabId.clear()
+    this.sessionProfileIdByPageId.clear()
     this.pendingLoadFailuresByGuestId.clear()
     this.pendingPermissionEventsByGuestId.clear()
     this.pendingPopupEventsByGuestId.clear()
@@ -699,6 +705,10 @@ export class BrowserManager {
     return this.worktreeIdByTabId.get(browserTabId)
   }
 
+  getSessionProfileIdForTab(browserTabId: string): string | null {
+    return this.sessionProfileIdByPageId.get(browserTabId) ?? null
+  }
+
   notifyPermissionDenied(args: {
     guestWebContentsId: number
     permission: string
diff --git a/src/main/codex-accounts/runtime-home-service.test.ts b/src/main/codex-accounts/runtime-home-service.test.ts
index 65d304f71b6..d24edef5f2b 100644
--- a/src/main/codex-accounts/runtime-home-service.test.ts
+++ b/src/main/codex-accounts/runtime-home-service.test.ts
@@ -30,6 +30,7 @@ vi.mock('node:os', async () => {
 })
 
 function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings {
+  const appFontFamily = overrides.appFontFamily ?? 'Geist'
   return {
     workspaceDir: testState.fakeHomeDir,
     nestWorkspaces: false,
@@ -72,7 +73,8 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
       enabled: true,
       agentTaskComplete: true,
       terminalBell: false,
-      suppressWhenFocused: true
+      suppressWhenFocused: true,
+      customSoundPath: null
     },
     promptCacheTimerEnabled: false,
     promptCacheTtlMs: 300_000,
@@ -96,10 +98,12 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     experimentalAgentDashboard: false,
     experimentalMobile: false,
     experimentalSidekick: false,
+    experimentalWorktreeSymlinks: false,
     terminalWindowsShell: 'powershell.exe',
     terminalWindowsPowerShellImplementation: 'powershell.exe',
     enableGitHubAttribution: true,
-    ...overrides
+    ...overrides,
+    appFontFamily
   }
 }
 
diff --git a/src/main/codex-accounts/service.test.ts b/src/main/codex-accounts/service.test.ts
index cff5f956d75..2d78c279504 100644
--- a/src/main/codex-accounts/service.test.ts
+++ b/src/main/codex-accounts/service.test.ts
@@ -24,6 +24,7 @@ vi.mock('node:os', async () => {
 })
 
 function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings {
+  const appFontFamily = overrides.appFontFamily ?? 'Geist'
   return {
     workspaceDir: testState.fakeHomeDir,
     nestWorkspaces: false,
@@ -66,7 +67,8 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
       enabled: true,
       agentTaskComplete: true,
       terminalBell: false,
-      suppressWhenFocused: true
+      suppressWhenFocused: true,
+      customSoundPath: null
     },
     promptCacheTimerEnabled: false,
     promptCacheTtlMs: 300_000,
@@ -90,10 +92,12 @@ function createSettings(overrides: Partial<GlobalSettings> = {}): GlobalSettings
     experimentalAgentDashboard: false,
     experimentalMobile: false,
     experimentalSidekick: false,
+    experimentalWorktreeSymlinks: false,
     terminalWindowsShell: 'powershell.exe',
     terminalWindowsPowerShellImplementation: 'powershell.exe',
     enableGitHubAttribution: true,
-    ...overrides
+    ...overrides,
+    appFontFamily
   }
 }
 
diff --git a/src/main/daemon/daemon-pty-adapter.test.ts b/src/main/daemon/daemon-pty-adapter.test.ts
index af8c7edac04..1049365d753 100644
--- a/src/main/daemon/daemon-pty-adapter.test.ts
+++ b/src/main/daemon/daemon-pty-adapter.test.ts
@@ -129,7 +129,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
   describe('shutdown', () => {
     it('kills the session', async () => {
       const { id } = await adapter.spawn({ cols: 80, rows: 24 })
-      await adapter.shutdown(id, false)
+      await adapter.shutdown(id, { immediate: false })
       expect(lastSubprocess.kill).toHaveBeenCalled()
     })
   })
@@ -312,7 +312,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
     it('prevents spawn after shutdown for same sessionId', async () => {
       const sessionId = 'tombstone-test'
       await adapter.spawn({ cols: 80, rows: 24, sessionId })
-      await adapter.shutdown(sessionId, true)
+      await adapter.shutdown(sessionId, { immediate: true })
 
       await expect(adapter.spawn({ cols: 80, rows: 24, sessionId })).rejects.toThrow(
         'was explicitly killed'
@@ -321,7 +321,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
 
     it('allows spawn for different sessionId after shutdown', async () => {
       await adapter.spawn({ cols: 80, rows: 24, sessionId: 'kill-me' })
-      await adapter.shutdown('kill-me', true)
+      await adapter.shutdown('kill-me', { immediate: true })
 
       const result = await adapter.spawn({ cols: 80, rows: 24, sessionId: 'fresh-one' })
       expect(result.id).toBe('fresh-one')
@@ -330,7 +330,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
     it('clearTombstone allows re-spawn', async () => {
       const sessionId = 'cleared-tombstone'
       await adapter.spawn({ cols: 80, rows: 24, sessionId })
-      await adapter.shutdown(sessionId, true)
+      await adapter.shutdown(sessionId, { immediate: true })
 
       adapter.clearTombstone(sessionId)
 
@@ -349,7 +349,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
         const id = `evict-${i}`
         ids.push(id)
         await adapter.spawn({ cols: 80, rows: 24, sessionId: id })
-        await adapter.shutdown(id, true)
+        await adapter.shutdown(id, { immediate: true })
       }
 
       // All 5 should be tombstoned
@@ -362,7 +362,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
       // clearTombstone the first one, then re-kill it — it should still work
       adapter.clearTombstone(ids[0])
       await adapter.spawn({ cols: 80, rows: 24, sessionId: ids[0] })
-      await adapter.shutdown(ids[0], true)
+      await adapter.shutdown(ids[0], { immediate: true })
 
       // First tombstone was re-added at the end of the Map, so eviction
       // order is now [evict-1, evict-2, evict-3, evict-4, evict-0]
@@ -488,7 +488,7 @@ describe('DaemonPtyAdapter (IPtyProvider)', () => {
 
       expect(existsSync(join(historyDir, getHistorySessionDirName(id)))).toBe(true)
 
-      await historyAdapter.shutdown(id, true)
+      await historyAdapter.shutdown(id, { immediate: true })
       await new Promise((r) => setTimeout(r, 50))
 
       expect(existsSync(join(historyDir, getHistorySessionDirName(id)))).toBe(false)
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 349ca4d5136..a182b898f76 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -230,26 +230,31 @@ export class DaemonPtyAdapter implements IPtyProvider {
     this.client.notify('resize', { sessionId: id, cols, rows })
   }
 
-  async shutdown(id: string, _immediate: boolean): Promise<void> {
+  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
     await this.client.request('kill', { sessionId: id })
     this.activeSessionIds.delete(id)
     this.initialCwds.delete(id)
-    // Why: user explicitly closed this terminal — clean up disk history
-    // so it doesn't trigger a false cold restore on next launch.
-    if (this.historyManager) {
+    // Why: history removal is for the "user explicitly closed this terminal"
+    // path. Sleep also calls shutdown but expects scrollback to survive — wake
+    // re-spawns and the cold-restore reader needs the dir intact. Caller
+    // indicates intent via opts.keepHistory.
+    if (this.historyManager && !opts.keepHistory) {
       void this.historyManager
         .removeSession(id)
         .catch((err) => console.warn('[history] removeSession failed:', id, err))
     }
 
-    // Why: delete-then-set ensures the entry moves to the end of Map iteration
-    // order, so re-killing a session doesn't leave it as the first eviction target.
-    this.killedSessionTombstones.delete(id)
-    this.killedSessionTombstones.set(id, Date.now())
-    if (this.killedSessionTombstones.size > MAX_TOMBSTONES) {
-      const oldest = this.killedSessionTombstones.keys().next().value
-      if (oldest) {
-        this.killedSessionTombstones.delete(oldest)
+    // Why: tombstone rejects reattach against a session the user explicitly
+    // killed. Sleep legitimately reattaches on wake, so skip both the LRU bump
+    // and the size-cap eviction under keepHistory.
+    if (!opts.keepHistory) {
+      this.killedSessionTombstones.delete(id)
+      this.killedSessionTombstones.set(id, Date.now())
+      if (this.killedSessionTombstones.size > MAX_TOMBSTONES) {
+        const oldest = this.killedSessionTombstones.keys().next().value
+        if (oldest) {
+          this.killedSessionTombstones.delete(oldest)
+        }
       }
     }
   }
diff --git a/src/main/daemon/daemon-pty-provider.test.ts b/src/main/daemon/daemon-pty-provider.test.ts
index a773a0720a1..eb50820993d 100644
--- a/src/main/daemon/daemon-pty-provider.test.ts
+++ b/src/main/daemon/daemon-pty-provider.test.ts
@@ -131,7 +131,7 @@ describe('DaemonPtyProvider', () => {
   describe('shutdown (kill session)', () => {
     it('kills the session in the daemon', async () => {
       await provider.spawn({ cols: 80, rows: 24, sessionId: 's1' })
-      await provider.shutdown('s1', false)
+      await provider.shutdown('s1', { immediate: false })
 
       expect(lastSubprocess.kill).toHaveBeenCalled()
     })
diff --git a/src/main/daemon/daemon-pty-provider.ts b/src/main/daemon/daemon-pty-provider.ts
index 6380cc27f0b..74a5d834874 100644
--- a/src/main/daemon/daemon-pty-provider.ts
+++ b/src/main/daemon/daemon-pty-provider.ts
@@ -62,7 +62,7 @@ export class DaemonPtyProvider {
     this.client.notify('resize', { sessionId: id, cols, rows })
   }
 
-  async shutdown(id: string, _immediate: boolean): Promise<void> {
+  async shutdown(id: string, _opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
     await this.client.request('kill', { sessionId: id })
   }
 
diff --git a/src/main/daemon/daemon-pty-router.ts b/src/main/daemon/daemon-pty-router.ts
index d6ba74ef73e..70e383f7226 100644
--- a/src/main/daemon/daemon-pty-router.ts
+++ b/src/main/daemon/daemon-pty-router.ts
@@ -63,8 +63,8 @@ export class DaemonPtyRouter implements IPtyProvider {
     this.adapterFor(id).resize(id, cols, rows)
   }
 
-  async shutdown(id: string, immediate: boolean): Promise<void> {
-    await this.adapterFor(id).shutdown(id, immediate)
+  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
+    await this.adapterFor(id).shutdown(id, opts)
     this.sessionAdapters.delete(id)
   }
 
diff --git a/src/main/git/remove-worktree.test.ts b/src/main/git/remove-worktree.test.ts
index 97f8eee820b..8039abd3748 100644
--- a/src/main/git/remove-worktree.test.ts
+++ b/src/main/git/remove-worktree.test.ts
@@ -87,7 +87,7 @@ describe('removeWorktree', () => {
 
   it('removes the worktree, prunes stale refs, and deletes its local branch', async () => {
     mockGitCommands({
-      'git worktree list --porcelain -z': {
+      'git worktree list --porcelain': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -97,7 +97,7 @@ HEAD def456
 branch refs/heads/feature/test
 `
       },
-      'git worktree list --porcelain -z#2': {
+      'git worktree list --porcelain#2': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -121,7 +121,7 @@ branch refs/heads/main
 
   it('skips branch deletion when another worktree still points at the branch', async () => {
     mockGitCommands({
-      'git worktree list --porcelain -z': {
+      'git worktree list --porcelain': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -135,7 +135,7 @@ HEAD def456
 branch refs/heads/feature/test
 `
       },
-      'git worktree list --porcelain -z#2': {
+      'git worktree list --porcelain#2': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -154,7 +154,7 @@ branch refs/heads/feature/test
       expect.arrayContaining([
         'git worktree remove /repo-feature',
         'git worktree prune',
-        'git worktree list --porcelain -z'
+        'git worktree list --porcelain'
       ])
     )
     expect(calls).not.toContain('git branch -D feature/test')
@@ -163,7 +163,7 @@ branch refs/heads/feature/test
 
   it('deletes the branch after prune removes stale sibling worktree entries', async () => {
     mockGitCommands({
-      'git worktree list --porcelain -z': {
+      'git worktree list --porcelain': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -178,7 +178,7 @@ branch refs/heads/feature/test
 prunable gitdir file points to non-existent location
 `
       },
-      'git worktree list --porcelain -z#2': {
+      'git worktree list --porcelain#2': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -201,7 +201,7 @@ branch refs/heads/main
 
   it('passes --force before the worktree path when forced removal is requested', async () => {
     mockGitCommands({
-      'git worktree list --porcelain -z': {
+      'git worktree list --porcelain': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -211,7 +211,7 @@ HEAD def456
 branch refs/heads/feature/test
 `
       },
-      'git worktree list --porcelain -z#2': {
+      'git worktree list --porcelain#2': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -226,7 +226,7 @@ branch refs/heads/main
 
   it('matches Windows worktree paths before deleting the branch', async () => {
     mockGitCommands({
-      'git worktree list --porcelain -z': {
+      'git worktree list --porcelain': {
         stdout: `worktree C:/repo
 HEAD abc123
 branch refs/heads/main
@@ -236,7 +236,7 @@ HEAD def456
 branch refs/heads/feature/test
 `
       },
-      'git worktree list --porcelain -z#2': {
+      'git worktree list --porcelain#2': {
         stdout: `worktree C:/repo
 HEAD abc123
 branch refs/heads/main
@@ -259,7 +259,7 @@ branch refs/heads/main
   it('keeps removal successful when branch cleanup fails', async () => {
     const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
     mockGitCommands({
-      'git worktree list --porcelain -z': {
+      'git worktree list --porcelain': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -269,7 +269,7 @@ HEAD def456
 branch refs/heads/feature/test
 `
       },
-      'git worktree list --porcelain -z#2': {
+      'git worktree list --porcelain#2': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -306,16 +306,15 @@ describe('listWorktrees', () => {
     resolveGitDirMock.mockImplementation(async (worktreePath: string) => `${worktreePath}/.git`)
   })
 
-  it('translates parsed path fields from NUL-delimited porcelain output', async () => {
+  it('translates parsed path fields from line-block porcelain output', async () => {
     gitExecFileAsyncMock.mockResolvedValueOnce({
       stdout:
-        'worktree /home/me/repo\0HEAD abc123\0branch refs/heads/main\0\0' +
-        'worktree /home/me/repo-feature\0HEAD def456\0branch refs/heads/feature/test\0sparse\0\0'
-    })
-    translateWslOutputPathsMock.mockImplementation((output: string) => {
-      expect(output).not.toContain('\0')
-      return output.replace('/home/me/', '\\\\wsl.localhost\\Ubuntu\\home\\me\\')
+        'worktree /home/me/repo\nHEAD abc123\nbranch refs/heads/main\n\n' +
+        'worktree /home/me/repo-feature\nHEAD def456\nbranch refs/heads/feature/test\nsparse\n\n'
     })
+    translateWslOutputPathsMock.mockImplementation((output: string) =>
+      output.replace('/home/me/', '\\\\wsl.localhost\\Ubuntu\\home\\me\\')
+    )
 
     await expect(listWorktrees('\\\\wsl.localhost\\Ubuntu\\home\\me\\repo')).resolves.toEqual([
       {
@@ -337,27 +336,47 @@ describe('listWorktrees', () => {
     // Why: the non-sparse main worktree gets an fs probe of its sparse config
     // file; the linked worktree short-circuits on the parsed `sparse` token and
     // does not. Only one git subprocess runs regardless of worktree count.
-    expect(getGitCalls()).toEqual(['git worktree list --porcelain -z'])
+    expect(getGitCalls()).toEqual(['git worktree list --porcelain'])
     expect(statMock).toHaveBeenCalledTimes(1)
     expect(translateWslOutputPathsMock).toHaveBeenCalledTimes(2)
   })
 
+  it('returns no worktrees when the repo path is gone', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    gitExecFileAsyncMock.mockRejectedValueOnce(
+      Object.assign(new Error('spawn git ENOENT'), {
+        code: 'ENOENT'
+      })
+    )
+    statMock.mockRejectedValueOnce(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }))
+
+    await expect(listWorktrees('/workspace/deleted-repo')).resolves.toEqual([])
+
+    expect(gitExecFileAsyncMock).toHaveBeenCalledWith(['worktree', 'list', '--porcelain'], {
+      cwd: '/workspace/deleted-repo'
+    })
+    expect(statMock).toHaveBeenCalledWith('/workspace/deleted-repo')
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[git/worktree] repo path missing; skipping worktree list: /workspace/deleted-repo'
+    )
+    warnSpy.mockRestore()
+  })
+
   it('detects sparse checkout after translating paths when porcelain omits sparse token', async () => {
     gitExecFileAsyncMock.mockImplementation((args: string[]) => {
-      if (args.join(' ') === 'worktree list --porcelain -z') {
+      if (args.join(' ') === 'worktree list --porcelain') {
         return {
           stdout:
-            'worktree /home/me/repo\0HEAD abc123\0branch refs/heads/main\0\0' +
-            'worktree /home/me/repo-feature\0HEAD def456\0branch refs/heads/feature/test\0\0',
+            'worktree /home/me/repo\nHEAD abc123\nbranch refs/heads/main\n\n' +
+            'worktree /home/me/repo-feature\nHEAD def456\nbranch refs/heads/feature/test\n\n',
           stderr: ''
         }
       }
       throw new Error(`Unexpected git call: ${args.join(' ')}`)
     })
-    translateWslOutputPathsMock.mockImplementation((output: string) => {
-      expect(output).not.toContain('\0')
-      return output.replace('/home/me/', '\\\\wsl.localhost\\Ubuntu\\home\\me\\')
-    })
+    translateWslOutputPathsMock.mockImplementation((output: string) =>
+      output.replace('/home/me/', '\\\\wsl.localhost\\Ubuntu\\home\\me\\')
+    )
     const featureWorktreePath = '\\\\wsl.localhost\\Ubuntu\\home\\me\\repo-feature'
     resolveGitDirMock.mockImplementation(async (worktreePath: string) =>
       worktreePath === featureWorktreePath
@@ -394,7 +413,7 @@ describe('listWorktrees', () => {
     // Why: the detection path must not spawn a git subprocess per worktree —
     // the perf regression in #1131 came from `git sparse-checkout list` firing
     // on every poll.
-    expect(getGitCalls()).toEqual(['git worktree list --porcelain -z'])
+    expect(getGitCalls()).toEqual(['git worktree list --porcelain'])
   })
 })
 
@@ -428,7 +447,7 @@ describe('addSparseWorktree', () => {
       'git sparse-checkout set -- packages/web': {
         error: new Error('sparse setup failed')
       },
-      'git worktree list --porcelain -z': {
+      'git worktree list --porcelain': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
@@ -438,7 +457,7 @@ HEAD def456
 branch refs/heads/feature/test
 `
       },
-      'git worktree list --porcelain -z#2': {
+      'git worktree list --porcelain#2': {
         stdout: `worktree /repo
 HEAD abc123
 branch refs/heads/main
diff --git a/src/main/git/runner.test.ts b/src/main/git/runner.test.ts
new file mode 100644
index 00000000000..e83af8c115f
--- /dev/null
+++ b/src/main/git/runner.test.ts
@@ -0,0 +1,91 @@
+// Why: covers two recent classifier fixes — Retry-After honoring on 429
+// (transient detection must propagate, not silently retry on 250ms cadence)
+// and stderr extraction from execFile rejections (err.message is unreliable).
+import { describe, expect, it } from 'vitest'
+import { extractExecError, isTransientGhError, parseRetryAfterMs } from './runner'
+
+describe('parseRetryAfterMs', () => {
+  it('returns null when no Retry-After is present', () => {
+    expect(parseRetryAfterMs('HTTP 429 Too Many Requests')).toBeNull()
+  })
+
+  it('parses integer seconds', () => {
+    expect(parseRetryAfterMs('HTTP 429\nRetry-After: 30\n')).toBe(30_000)
+  })
+
+  it('handles case-insensitive header name and surrounding whitespace', () => {
+    expect(parseRetryAfterMs('  retry-after:   12  \n')).toBe(12_000)
+  })
+
+  it('returns null for malformed values', () => {
+    expect(parseRetryAfterMs('Retry-After: not-a-date')).toBeNull()
+  })
+})
+
+describe('isTransientGhError', () => {
+  it('retries 5xx errors', () => {
+    expect(isTransientGhError('HTTP 502 Bad Gateway')).toBe(true)
+    expect(isTransientGhError('http 503')).toBe(true)
+  })
+
+  it('retries network resets', () => {
+    expect(isTransientGhError('connect ECONNRESET 10.0.0.1:443')).toBe(true)
+    expect(isTransientGhError('socket hang up')).toBe(true)
+  })
+
+  it('retries 429 without Retry-After', () => {
+    expect(isTransientGhError('HTTP 429 Too Many Requests')).toBe(true)
+  })
+
+  it('does NOT retry 429 with Retry-After', () => {
+    // Why: when GitHub returns Retry-After, the server is telling us how long
+    // to wait. Retrying on our 250ms cadence just earns another 429 and burns
+    // the retry budget.
+    expect(isTransientGhError('HTTP 429 Too Many Requests\nRetry-After: 60\n')).toBe(false)
+  })
+
+  it("does NOT retry 4xx that aren't 429", () => {
+    expect(isTransientGhError('HTTP 401 Unauthorized')).toBe(false)
+    expect(isTransientGhError('HTTP 404 Not Found')).toBe(false)
+    expect(isTransientGhError('HTTP 422 Unprocessable Entity')).toBe(false)
+  })
+})
+
+describe('extractExecError', () => {
+  it('reads stderr and stdout from explicit fields', () => {
+    const err = Object.assign(new Error('Command failed'), {
+      stderr: 'real stderr content',
+      stdout: '{"data": null}'
+    })
+    expect(extractExecError(err)).toEqual({
+      stderr: 'real stderr content',
+      stdout: '{"data": null}'
+    })
+  })
+
+  it('decodes Buffer stderr/stdout', () => {
+    const err = Object.assign(new Error('Command failed'), {
+      stderr: Buffer.from('buf-stderr', 'utf-8'),
+      stdout: Buffer.from('buf-stdout', 'utf-8')
+    })
+    expect(extractExecError(err)).toEqual({
+      stderr: 'buf-stderr',
+      stdout: 'buf-stdout'
+    })
+  })
+
+  it('falls back to err.message when stderr/stdout are absent', () => {
+    const err = new Error('Some message')
+    expect(extractExecError(err)).toEqual({
+      stderr: 'Some message',
+      stdout: ''
+    })
+  })
+
+  it('handles non-Error rejections', () => {
+    expect(extractExecError('plain string error')).toEqual({
+      stderr: 'plain string error',
+      stdout: ''
+    })
+  })
+})
diff --git a/src/main/git/runner.ts b/src/main/git/runner.ts
index 9ed285df923..c43058504b4 100644
--- a/src/main/git/runner.ts
+++ b/src/main/git/runner.ts
@@ -6,13 +6,7 @@
  * This module detects WSL paths and routes command execution through `wsl.exe -d <distro>`
  * with translated Linux paths, so every call site gets WSL support for free.
  */
-import {
-  execFile,
-  execFileSync,
-  spawn,
-  type ChildProcess,
-  type SpawnOptions
-} from 'child_process'
+import { execFile, execFileSync, spawn, type ChildProcess, type SpawnOptions } from 'child_process'
 import { promisify } from 'util'
 import { parseWslPath, toWindowsWslPath, type WslPathInfo } from '../wsl'
 
@@ -70,13 +64,26 @@ function translateArgsForWsl(args: string[]): string[] {
 function resolveCommand(
   command: string,
   args: string[],
-  cwd: string | undefined
+  cwd: string | undefined,
+  wslDistroOverride?: string
 ): ResolvedCommand {
-  if (!cwd || process.platform !== 'win32') {
+  if (process.platform !== 'win32') {
     return { binary: command, args, cwd, wsl: null }
   }
 
-  const wsl = parseWslPath(cwd)
+  // Why: global gh callers (rate_limit, listAccessibleProjects) have no
+  // meaningful cwd to derive a WSL distro from. On WSL-only Windows setups,
+  // gh.exe isn't on the host PATH and the spawn fails with ENOENT. Allow
+  // callers to pass a distro hint so we can route through wsl.exe regardless.
+  // TODO(wsl-default-distro): the codebase currently has no persistent
+  // "default WSL distro" setting — distros are derived from individual repo
+  // paths. Until such a setting exists, global gh callers without an explicit
+  // override silently fall back to host gh.exe, which on WSL-only Windows
+  // installs will ENOENT. The wslDistroOverride parameter is the hook for
+  // wiring a future setting in without re-plumbing the runner.
+  const cwdWsl = cwd ? parseWslPath(cwd) : null
+  const wsl: WslPathInfo | null =
+    cwdWsl ?? (wslDistroOverride ? { distro: wslDistroOverride, linuxPath: '' } : null)
   if (!wsl) {
     return { binary: command, args, cwd, wsl: null }
   }
@@ -86,11 +93,14 @@ function resolveCommand(
   // inside the bash -c string. Single quotes are safe for all chars except
   // single quotes themselves, which we escape as '\'' (end quote, escaped
   // literal, reopen quote).
-  const escapedArgs = translatedArgs.map(
-    (a) => `'${a.replace(/'/g, "'\\''")}'`
-  )
-  const escapedCwd = wsl.linuxPath.replace(/'/g, "'\\''")
-  const shellCmd = `cd '${escapedCwd}' && ${command} ${escapedArgs.join(' ')}`
+  const escapedArgs = translatedArgs.map((a) => `'${a.replace(/'/g, "'\\''")}'`)
+  // Why: when cwd is supplied as a WSL UNC path, prepend `cd <linuxPath> &&`
+  // so the command runs in the expected directory. When the caller only
+  // supplied a distro override (no cwd), skip the cd entirely — the gh CLI
+  // doesn't need a particular cwd for global calls like `api rate_limit`.
+  const shellCmd = cwdWsl
+    ? `cd '${cwdWsl.linuxPath.replace(/'/g, "'\\''")}' && ${command} ${escapedArgs.join(' ')}`
+    : `${command} ${escapedArgs.join(' ')}`
 
   return {
     binary: 'wsl.exe',
@@ -175,10 +185,7 @@ export function gitExecFileSync(
  * Spawn a git child process. Drop-in replacement for
  * `spawn('git', args, { cwd, stdio, ... })`.
  */
-export function gitSpawn(
-  args: string[],
-  options: SpawnOptions & { cwd: string }
-): ChildProcess {
+export function gitSpawn(args: string[], options: SpawnOptions & { cwd: string }): ChildProcess {
   const resolved = resolveCommand('git', args, options.cwd)
   return spawn(resolved.binary, resolved.args, {
     ...options,
@@ -188,23 +195,246 @@ export function gitSpawn(
 
 // ─── gh CLI runners ─────────────────────────────────────────────────
 
+// Why: non-repo-scoped gh calls (listAccessibleProjects, rate_limit, etc.)
+// have no meaningful cwd. Allow it to be omitted so the one WSL-aware wrapper
+// serves both repo-scoped and global callers and we stop having two spawn
+// sites (the other one — a plain execFileAsync in project-view.ts — bypasses
+// retry/backoff and any future quota tracker).
+// Why: `wslDistro` is an explicit hint for global (cwd-less) gh callers on
+// WSL-only Windows installs where gh.exe isn't on the host PATH. When set,
+// resolveCommand routes the spawn through `wsl.exe -d <distro> -- gh ...`
+// even without a UNC cwd to parse a distro from. Repo-scoped callers should
+// keep using cwd — the distro derives from the path automatically there.
+// Why: `idempotent` gates the transient-error retry. When undefined we
+// auto-detect from argv (writes are detected by `-X POST/PATCH/PUT/DELETE`
+// or a `query=mutation …` arg); callers can also pass an explicit override.
+// A 5xx/socket reset after the request reaches GitHub but before the
+// response returns is the canonical case where the server-side write
+// succeeded; retrying would create a duplicate comment/issue/label addition.
+// See bug-scan finding 1.
+type GhExecOptions = Omit<GitExecOptions, 'cwd'> & {
+  cwd?: string
+  wslDistro?: string
+  idempotent?: boolean
+}
+
+const NON_IDEMPOTENT_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE'])
+// `gh <noun> <verb>` write subcommands. Reads (view/list/status/checks)
+// are absent on purpose so the default of "retry" stays for them.
+const NON_IDEMPOTENT_GH_VERBS = new Set([
+  'create',
+  'edit',
+  'delete',
+  'close',
+  'reopen',
+  'merge',
+  'comment',
+  'review',
+  'ready',
+  'lock',
+  'unlock',
+  'pin',
+  'unpin',
+  'transfer',
+  'develop'
+])
+
+function argsLookIdempotent(args: string[]): boolean {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '-X' || a === '--method') {
+      const next = args[i + 1]
+      if (typeof next === 'string' && NON_IDEMPOTENT_METHODS.has(next.toUpperCase())) {
+        return false
+      }
+    }
+    // `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=')) {
+      const trimmed = a.slice('query='.length).trimStart().toLowerCase()
+      if (trimmed.startsWith('mutation')) {
+        return false
+      }
+    }
+  }
+  // `gh issue close`, `gh pr edit`, `gh pr merge`, etc. The first arg is the
+  // noun (issue/pr/repo/label/...) and the second is the verb. Defaulting
+  // `gh api` calls without an explicit -X to GET-equivalent (idempotent) is
+  // intentional: callers that POST through `gh api` set `-X POST`.
+  if (args.length >= 2 && args[0] !== 'api') {
+    if (NON_IDEMPOTENT_GH_VERBS.has(args[1])) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Extract stderr from an execFile rejection.
+ *
+ * Why: Node's execFile rejects with an Error that has `.stdout` and `.stderr`
+ * fields populated separately from `.message`. Reading `err.message` alone is
+ * unreliable — it can truncate stderr or omit it entirely depending on Node
+ * version and maxBuffer behavior. We prefer the explicit fields and fall
+ * back to `.message` only when neither is present.
+ */
+export function extractExecError(err: unknown): { stderr: string; stdout: string } {
+  if (err && typeof err === 'object') {
+    const e = err as { stderr?: unknown; stdout?: unknown; message?: unknown }
+    const stderr =
+      typeof e.stderr === 'string'
+        ? e.stderr
+        : Buffer.isBuffer(e.stderr)
+          ? e.stderr.toString('utf-8')
+          : ''
+    const stdout =
+      typeof e.stdout === 'string'
+        ? e.stdout
+        : Buffer.isBuffer(e.stdout)
+          ? e.stdout.toString('utf-8')
+          : ''
+    if (stderr || stdout) {
+      return { stderr, stdout }
+    }
+    if (typeof e.message === 'string') {
+      return { stderr: e.message, stdout: '' }
+    }
+  }
+  return { stderr: String(err), stdout: '' }
+}
+
+/**
+ * Detect a Retry-After hint in gh stderr and return the suggested delay in ms,
+ * or null when the response includes no Retry-After.
+ *
+ * Why: gh forwards response headers when verbose, and prints "Retry-After:
+ * <seconds>" in error output for primary rate-limit 429s. When present, the
+ * caller is better served by propagating the error so the UI can surface the
+ * real wait time — retrying on our own 250ms cadence just earns another 429
+ * and burns the retry budget. Also supports HTTP-date Retry-After values.
+ */
+export function parseRetryAfterMs(stderr: string): number | null {
+  const m = stderr.match(/retry-after:\s*([^\r\n]+)/i)
+  if (!m) {
+    return null
+  }
+  const raw = m[1].trim()
+  if (/^\d+$/.test(raw)) {
+    const seconds = Number(raw)
+    return Number.isFinite(seconds) ? seconds * 1000 : null
+  }
+  const ts = Date.parse(raw)
+  if (Number.isNaN(ts)) {
+    return null
+  }
+  return Math.max(0, ts - Date.now())
+}
+
+/**
+ * Classify whether a gh execFile rejection is worth retrying.
+ *
+ * Why: gh surfaces HTTP status in stderr as "HTTP 504", "HTTP 502", etc.
+ * Network resets and DNS hiccups also show up as stderr substrings. We retry
+ * those and 429 (rate-limited) — but only 429s without an explicit
+ * Retry-After (the caller is better off propagating so the UI can show the
+ * actual wait time). The primary-rate-limit 403 branch is NOT retried: those
+ * require the user to back off for minutes, which is not transient.
+ */
+export function isTransientGhError(stderr: string): boolean {
+  const s = stderr.toLowerCase()
+  if (
+    s.includes('http 500') ||
+    s.includes('http 502') ||
+    s.includes('http 503') ||
+    s.includes('http 504') ||
+    s.includes('econnreset') ||
+    s.includes('etimedout') ||
+    s.includes('socket hang up')
+  ) {
+    return true
+  }
+  // 429 without Retry-After: retry. With Retry-After: propagate.
+  if (s.includes('http 429')) {
+    return parseRetryAfterMs(stderr) === null
+  }
+  return false
+}
+
+// Why: total of 3 attempts (original + 2 retries) with 250ms → 1s backoff.
+// These are standard "transient 5xx" values. Longer waits push past user
+// patience for an interactive action; shorter waits would hammer the same
+// unhealthy upstream that just failed. The array length defines retry count;
+// total attempts = length + 1.
+const GH_RETRY_DELAYS_MS = [250, 1000] as const
+
+// Why: the upstream Retry-After header is server-suggested but unbounded —
+// GitHub has been observed to send tens-of-seconds values on rare incidents,
+// and a malicious or misconfigured proxy could send anything. Cap the wait
+// at 30s so a single transient gh call can never block the IPC main thread
+// for longer than the user's patience budget for an interactive action.
+const GH_RETRY_AFTER_MAX_MS = 30_000
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
 /**
  * Async gh CLI execution. Drop-in replacement for
  * `execFileAsync('gh', args, { cwd, encoding, ... })`.
+ *
+ * Retries transient 5xx / 429 (without Retry-After) / network-reset failures
+ * with exponential backoff. Non-transient errors (auth, 404, rate-limit 403,
+ * validation, 429-with-Retry-After) fail fast on the first attempt.
  */
 export async function ghExecFileAsync(
   args: string[],
-  options: GitExecOptions
+  options: GhExecOptions = {}
 ): Promise<{ stdout: string; stderr: string }> {
-  const resolved = resolveCommand('gh', args, options.cwd)
-  const { stdout, stderr } = await execFileAsync(resolved.binary, resolved.args, {
-    cwd: resolved.cwd,
-    encoding: (options.encoding ?? 'utf-8') as BufferEncoding,
-    maxBuffer: options.maxBuffer,
-    timeout: options.timeout,
-    env: options.env
-  })
-  return { stdout: stdout as string, stderr: stderr as string }
+  const resolved = resolveCommand('gh', args, options.cwd, options.wslDistro)
+  let lastError: unknown
+  for (let attempt = 0; attempt <= GH_RETRY_DELAYS_MS.length; attempt++) {
+    try {
+      const { stdout, stderr } = await execFileAsync(resolved.binary, resolved.args, {
+        cwd: resolved.cwd,
+        encoding: (options.encoding ?? 'utf-8') as BufferEncoding,
+        maxBuffer: options.maxBuffer,
+        timeout: options.timeout,
+        env: options.env
+      })
+      return { stdout: stdout as string, stderr: stderr as string }
+    } catch (err) {
+      lastError = err
+      const { stderr } = extractExecError(err)
+      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
+      // would duplicate the write (e.g. double-post a comment, double-add
+      // a label). When the caller doesn't say, we auto-detect from argv —
+      // explicit `-X <method>` and GraphQL `query=mutation …` are treated
+      // as non-idempotent. See bug-scan finding 1.
+      const idempotent = options.idempotent ?? argsLookIdempotent(args)
+      if (idempotent && !isLastAttempt && isTransientGhError(stderr)) {
+        // Why: when the upstream surfaced a Retry-After (e.g. on a transient
+        // 5xx that GitHub explicitly recommends backing off for), honor it
+        // instead of using our default backoff — sleeping less than the
+        // server suggests just earns another failure and burns our retry
+        // budget. Cap at GH_RETRY_AFTER_MAX_MS so a pathologically large
+        // hint can't block IPC for minutes; if the real wait is longer, the
+        // attempt will fail again and the error will propagate to the UI
+        // where the user can see it.
+        const retryAfterMs = parseRetryAfterMs(stderr)
+        const delayMs =
+          retryAfterMs !== null
+            ? Math.min(retryAfterMs, GH_RETRY_AFTER_MAX_MS)
+            : GH_RETRY_DELAYS_MS[attempt]
+        await sleep(delayMs)
+        continue
+      }
+      throw err
+    }
+  }
+  // Unreachable: the loop either returns or throws. Here for TS exhaustiveness.
+  throw lastError
 }
 
 // ─── Generic command runner (for rg, etc.) ──────────────────────────
@@ -234,10 +464,7 @@ export function wslAwareSpawn(
  * are Linux-native (/home/user/repo). The rest of Orca needs Windows UNC
  * paths (\\wsl.localhost\Ubuntu\home\user\repo) to read files via Node fs.
  */
-export function translateWslOutputPaths(
-  output: string,
-  originalCwd: string
-): string {
+export function translateWslOutputPaths(output: string, originalCwd: string): string {
   const wsl = parseWslPath(originalCwd)
   if (!wsl) {
     return output
@@ -245,9 +472,8 @@ export function translateWslOutputPaths(
 
   // Replace absolute Linux paths that start with / and look like filesystem
   // paths in structured git output (e.g. "worktree /home/user/repo/feature")
-  return output.replace(
-    /(?<=worktree )(\/.+)$/gm,
-    (_match, linuxPath: string) => toWindowsWslPath(linuxPath, wsl.distro)
+  return output.replace(/(?<=worktree )(\/.+)$/gm, (_match, linuxPath: string) =>
+    toWindowsWslPath(linuxPath, wsl.distro)
   )
 }
 
diff --git a/src/main/git/worktree.ts b/src/main/git/worktree.ts
index b77b89e33f6..ff6bc69fd83 100644
--- a/src/main/git/worktree.ts
+++ b/src/main/git/worktree.ts
@@ -8,6 +8,12 @@ type SparseWorktreeCreateError = Error & {
   cleanupFailed?: boolean
 }
 
+function getErrorCode(error: unknown): string | undefined {
+  return typeof error === 'object' && error !== null && 'code' in error
+    ? String((error as { code?: unknown }).code)
+    : undefined
+}
+
 function normalizeLocalBranchRef(branch: string): string {
   return branch.replace(/^refs\/heads\//, '')
 }
@@ -35,12 +41,10 @@ function looksLikeWindowsPath(pathValue: string): boolean {
  */
 export function parseWorktreeList(output: string): GitWorktreeInfo[] {
   const worktrees: GitWorktreeInfo[] = []
-  const blocks = output.includes('\0')
-    ? parseNullDelimitedWorktreeBlocks(output)
-    : output
-        .trim()
-        .split(/\r?\n\r?\n/)
-        .map((block) => block.trim().split(/\r?\n/))
+  const blocks = output
+    .trim()
+    .split(/\r?\n\r?\n/)
+    .map((block) => block.trim().split(/\r?\n/))
 
   for (const lines of blocks) {
     if (lines.length === 0) {
@@ -88,11 +92,12 @@ export function parseWorktreeList(output: string): GitWorktreeInfo[] {
  */
 export async function listWorktrees(repoPath: string): Promise<GitWorktreeInfo[]> {
   try {
-    const { stdout } = await gitExecFileAsync(['worktree', 'list', '--porcelain', '-z'], {
+    // Why: do not pass `-z` here. `-z` requires Git ≥ 2.36; older Git rejects
+    // it, listWorktrees returns [], and every create flow throws "Worktree
+    // created but not found in listing" (issue #1453).
+    const { stdout } = await gitExecFileAsync(['worktree', 'list', '--porcelain'], {
       cwd: repoPath
     })
-    // Why: WSL path translation is line-oriented, but `-z` porcelain output is
-    // NUL-delimited. Parse first so only complete path fields are translated.
     const worktrees = parseWorktreeList(stdout).map((worktree) => {
       const translatedPath = translateWorktreePath(worktree.path, repoPath)
       return translatedPath === worktree.path ? worktree : { ...worktree, path: translatedPath }
@@ -106,7 +111,21 @@ export async function listWorktrees(repoPath: string): Promise<GitWorktreeInfo[]
         return isSparse ? { ...worktree, isSparse } : worktree
       })
     )
-  } catch {
+  } catch (err) {
+    if (getErrorCode(err) === 'ENOENT') {
+      try {
+        await stat(repoPath)
+      } catch (statErr) {
+        if (getErrorCode(statErr) === 'ENOENT') {
+          console.warn(`[git/worktree] repo path missing; skipping worktree list: ${repoPath}`)
+          return []
+        }
+      }
+    }
+    // Why: a silent catch turned issue #1453's underlying
+    // "git: unknown switch -z" into the opaque "not found in listing" toast.
+    // Surface the cause so future regressions show up immediately.
+    console.warn(`[git/worktree] listWorktrees failed for ${repoPath}:`, err)
     return []
   }
 }
@@ -273,28 +292,6 @@ export async function removeWorktree(
   }
 }
 
-function parseNullDelimitedWorktreeBlocks(output: string): string[][] {
-  const blocks: string[][] = []
-  let current: string[] = []
-
-  for (const token of output.split('\0')) {
-    if (!token) {
-      if (current.length > 0) {
-        blocks.push(current)
-        current = []
-      }
-      continue
-    }
-    current.push(token)
-  }
-
-  if (current.length > 0) {
-    blocks.push(current)
-  }
-
-  return blocks
-}
-
 function translateWorktreePath(worktreePath: string, repoPath: string): string {
   const prefix = 'worktree '
   const translated = translateWslOutputPaths(`${prefix}${worktreePath}`, repoPath)
diff --git a/src/main/github/auth-diagnose.test.ts b/src/main/github/auth-diagnose.test.ts
new file mode 100644
index 00000000000..35e3775b478
--- /dev/null
+++ b/src/main/github/auth-diagnose.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import { parseAuthStatus } from './auth-diagnose'
+
+describe('parseAuthStatus', () => {
+  it('parses an env-shadowed login alongside a keyring login (real gh output)', () => {
+    const text = `github.com
+  ✓ Logged in to github.com account nwparker (GITHUB_TOKEN)
+  - Active account: true
+  - Git operations protocol: https
+  - Token: gho_************************************
+  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'
+
+  ✓ Logged in to github.com account nwparker (keyring)
+  - Active account: false
+  - Git operations protocol: https
+  - Token: gho_************************************
+  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'
+`
+    const accounts = parseAuthStatus(text)
+    expect(accounts).toHaveLength(2)
+    expect(accounts[0]).toMatchObject({
+      host: 'github.com',
+      user: 'nwparker',
+      active: true,
+      envToken: 'GITHUB_TOKEN',
+      source: 'env'
+    })
+    expect(accounts[0].scopes).toEqual(['gist', 'read:org', 'repo', 'workflow'])
+    expect(accounts[1]).toMatchObject({
+      active: false,
+      envToken: null,
+      source: 'keyring'
+    })
+  })
+
+  it('parses a single keyring login', () => {
+    const text = `github.com
+  ✓ Logged in to github.com account alice (keyring)
+  - Active account: true
+  - Token scopes: 'project', 'read:org', 'repo'
+`
+    const accounts = parseAuthStatus(text)
+    expect(accounts).toHaveLength(1)
+    expect(accounts[0]).toMatchObject({
+      user: 'alice',
+      active: true,
+      envToken: null,
+      source: 'keyring'
+    })
+    expect(accounts[0].scopes).toContain('project')
+  })
+
+  it('detects GH_TOKEN env source', () => {
+    const text = `github.com
+  ✓ Logged in to github.com account bot (GH_TOKEN)
+  - Active account: true
+  - Token scopes: 'repo'
+`
+    const [acc] = parseAuthStatus(text)
+    expect(acc.envToken).toBe('GH_TOKEN')
+    expect(acc.source).toBe('env')
+  })
+
+  it('returns empty array when nothing is logged in', () => {
+    expect(parseAuthStatus('You are not logged into any GitHub hosts.')).toEqual([])
+  })
+
+  it('parses multiple hosts in one output (github.com + GHES)', () => {
+    const text = `github.com
+  ✓ Logged in to github.com account alice (keyring)
+  - Active account: true
+  - Token scopes: 'read:org', 'repo'
+
+ghe.acme.io
+  ✓ Logged in to ghe.acme.io account bob (keyring)
+  - Active account: true
+  - Token scopes: 'project', 'repo'
+`
+    const accounts = parseAuthStatus(text)
+    expect(accounts.map((a) => a.host)).toEqual(['github.com', 'ghe.acme.io'])
+    expect(accounts.map((a) => a.user)).toEqual(['alice', 'bob'])
+    expect(accounts[1].scopes).toContain('project')
+  })
+
+  it('recovers host from the Logged-in line when the section header is missing', () => {
+    // gh prints a colon after the host on some versions; we tolerate it,
+    // but if the regex ever fails to match the header we still want
+    // accounts attributed to the host from the inline message.
+    const text = `  ✓ Logged in to github.acme.io account carol (keyring)
+  - Active account: true
+  - Token scopes: 'project'
+`
+    const accounts = parseAuthStatus(text)
+    expect(accounts).toHaveLength(1)
+    expect(accounts[0].host).toBe('github.acme.io')
+  })
+})
diff --git a/src/main/github/auth-diagnose.ts b/src/main/github/auth-diagnose.ts
new file mode 100644
index 00000000000..b356bf7b68e
--- /dev/null
+++ b/src/main/github/auth-diagnose.ts
@@ -0,0 +1,142 @@
+/**
+ * gh CLI auth diagnostics.
+ *
+ * Why: when project queries fail with "missing scope", the canned
+ * remediation `gh auth refresh -s project ...` silently no-ops if the user
+ * has `GITHUB_TOKEN` (or `GH_TOKEN`) exported in their shell — gh prefers
+ * env tokens over keyring credentials and refuses to refresh env-supplied
+ * tokens. Users follow the instructions, see no error, retry, and stay
+ * stuck. This probe makes that failure mode legible in the UI.
+ *
+ * Output is parsed from `gh auth status`, which prints free-form text but
+ * uses stable field labels ("Token scopes:", "(GITHUB_TOKEN)", etc.).
+ */
+import { ghExecFileAsync } from '../git/runner'
+import type { GhAuthDiagnostic, GhAuthAccount } from '../../shared/github-auth-types'
+
+// Required scopes for ProjectV2 GraphQL access in Orca. `project` is the
+// scope that gates ProjectV2 reads/writes; the others are needed for the
+// surrounding repo/org queries we already run.
+const REQUIRED_SCOPES = ['project', 'read:org', 'repo'] as const
+
+/**
+ * Parse `gh auth status` stderr/stdout. gh writes to stderr by default but
+ * has used stdout in some versions; we accept either. Format (per host):
+ *
+ *   github.com
+ *     ✓ Logged in to github.com account NAME (GITHUB_TOKEN)
+ *     - Active account: true
+ *     - Token scopes: 'gist', 'read:org', 'repo'
+ */
+export function parseAuthStatus(text: string): GhAuthAccount[] {
+  const accounts: GhAuthAccount[] = []
+  let currentHost: string | null = null
+  let current: GhAuthAccount | null = null
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.replace(/\r$/, '')
+    // Host header: a non-indented hostname token, with an optional
+    // trailing colon some gh versions emit. Permits single-label hostnames
+    // (internal GHES like `github` or `ghe-internal`); we also recover the
+    // host from the `Logged in to <host>` line below if this header was
+    // missed, so a parser miss never silently drops every account.
+    const hostMatch = line.match(/^([a-z0-9][a-z0-9.-]*)\s*:?\s*$/i)
+    if (hostMatch && !/^logged\b/i.test(line)) {
+      currentHost = hostMatch[1]
+      continue
+    }
+    const loggedIn = line.match(/Logged in to (\S+) account (\S+)(?:\s+\(([^)]+)\))?/i)
+    if (loggedIn) {
+      if (current) {
+        accounts.push(current)
+      }
+      // Prefer the host from the `Logged in to <host>` line itself — it's
+      // always present, whereas the section header above can be skipped
+      // by the regex on unfamiliar gh output.
+      const host = loggedIn[1] || currentHost || 'github.com'
+      const sourceLabel = (loggedIn[3] ?? '').trim()
+      // gh emits "(keyring)" for stored creds and "(GITHUB_TOKEN)" /
+      // "(GH_TOKEN)" when an env var is shadowing the keyring.
+      const envToken =
+        sourceLabel === 'GITHUB_TOKEN' || sourceLabel === 'GH_TOKEN' ? sourceLabel : null
+      current = {
+        host,
+        user: loggedIn[2],
+        active: false,
+        envToken,
+        source: envToken ? 'env' : 'keyring',
+        scopes: []
+      }
+      continue
+    }
+    if (!current) {
+      continue
+    }
+    const activeMatch = line.match(/Active account:\s*(true|false)/i)
+    if (activeMatch) {
+      current.active = activeMatch[1].toLowerCase() === 'true'
+      continue
+    }
+    const scopesMatch = line.match(/Token scopes:\s*(.+)$/i)
+    if (scopesMatch) {
+      current.scopes = scopesMatch[1]
+        .split(',')
+        .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+        .filter(Boolean)
+    }
+  }
+  if (current) {
+    accounts.push(current)
+  }
+  return accounts
+}
+
+export async function diagnoseGhAuth(): Promise<GhAuthDiagnostic> {
+  let raw = ''
+  let ghAvailable = true
+  try {
+    // `gh auth status` exits non-zero when no host is logged in but still
+    // prints the same diagnostic text we want, so capture both streams.
+    const { stdout, stderr } = await ghExecFileAsync(['auth', 'status'])
+    raw = `${stdout}\n${stderr}`
+  } catch (err) {
+    const stderr =
+      err && typeof err === 'object' && 'stderr' in err
+        ? String((err as { stderr?: unknown }).stderr ?? '')
+        : ''
+    const stdout =
+      err && typeof err === 'object' && 'stdout' in err
+        ? String((err as { stdout?: unknown }).stdout ?? '')
+        : ''
+    raw = `${stdout}\n${stderr}`
+    if (!raw.trim()) {
+      const message = err instanceof Error ? err.message : String(err)
+      // Most likely cause: gh CLI not installed or not on PATH.
+      if (/ENOENT|not found|command not found/i.test(message)) {
+        ghAvailable = false
+      }
+      raw = message
+    }
+  }
+  const accounts = parseAuthStatus(raw)
+  const active = accounts.find((a) => a.active) ?? accounts[0] ?? null
+  const envTokenInProcess: 'GITHUB_TOKEN' | 'GH_TOKEN' | null = process.env.GH_TOKEN
+    ? 'GH_TOKEN'
+    : process.env.GITHUB_TOKEN
+      ? 'GITHUB_TOKEN'
+      : null
+  const missingScopes = active
+    ? REQUIRED_SCOPES.filter((s) => !active.scopes.includes(s))
+    : [...REQUIRED_SCOPES]
+  // Is there a non-env (keyring) account we could fall back to by unsetting
+  // the env var? Only meaningful if the active account is env-shadowed.
+  const keyringFallback = accounts.find((a) => a.source === 'keyring') ?? null
+  return {
+    ghAvailable,
+    activeAccount: active,
+    accounts,
+    envTokenInProcess,
+    missingScopes,
+    requiredScopes: [...REQUIRED_SCOPES],
+    hasKeyringFallback: Boolean(keyringFallback && keyringFallback !== active)
+  }
+}
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index ebf866f3248..033998d85ac 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -829,20 +829,43 @@ export async function getWorkItem(
   }
 }
 
+export async function getWorkItemByOwnerRepo(
+  repoPath: string,
+  ownerRepo: OwnerRepo,
+  number: number,
+  type: 'issue' | 'pr'
+): Promise<MainWorkItem | null> {
+  await acquire()
+  try {
+    if (type === 'issue') {
+      return await fetchIssueWorkItem(repoPath, ownerRepo, number)
+    }
+    return await fetchPullRequestWorkItem(repoPath, ownerRepo, number)
+  } catch {
+    return null
+  } finally {
+    release()
+  }
+}
+
 /**
  * Get PR info for a given branch using gh CLI.
  * Returns null if gh is not installed, or no PR exists for the branch.
+ *
+ * When `linkedPRNumber` is provided and the branch lookup yields nothing,
+ * falls back to looking up the PR by number. This handles "create from PR"
+ * worktrees, whose branch is a fresh local branch (not the PR's head ref) —
+ * the branch-keyed lookup misses, but the user still expects the linked PR
+ * to surface on the worktree card.
  */
-export async function getPRForBranch(repoPath: string, branch: string): Promise<PRInfo | null> {
+export async function getPRForBranch(
+  repoPath: string,
+  branch: string,
+  linkedPRNumber?: number | null
+): Promise<PRInfo | null> {
   // Strip refs/heads/ prefix if present
   const branchName = branch.replace(/^refs\/heads\//, '')
 
-  // During a rebase the worktree is in detached HEAD and branch is empty.
-  // An empty --head filter causes gh to return an arbitrary PR — bail early.
-  if (!branchName) {
-    return null
-  }
-
   await acquire()
   try {
     const ownerRepo = await getOwnerRepo(repoPath)
@@ -861,38 +884,73 @@ export async function getPRForBranch(repoPath: string, branch: string): Promise<
       headRefOid?: string
     } | null = null
 
-    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'
-        ],
-        { cwd: repoPath }
-      )
-      const list = JSON.parse(stdout) as NonNullable<typeof data>[]
-      data = list[0] ?? null
-    } else {
-      const { stdout } = await ghExecFileAsync(
-        [
-          'pr',
-          'view',
-          branchName,
-          '--json',
-          'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
-        ],
-        { cwd: repoPath }
-      )
-      data = JSON.parse(stdout)
+    // 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'
+          ],
+          { cwd: repoPath }
+        )
+        const list = JSON.parse(stdout) as NonNullable<typeof data>[]
+        data = list[0] ?? null
+      } else {
+        const { stdout } = await ghExecFileAsync(
+          [
+            'pr',
+            'view',
+            branchName,
+            '--json',
+            'number,title,state,url,statusCheckRollup,updatedAt,isDraft,mergeable,baseRefName,headRefName,baseRefOid,headRefOid'
+          ],
+          { cwd: repoPath }
+        )
+        data = JSON.parse(stdout)
+      }
+    }
+
+    if (!data && typeof linkedPRNumber === 'number') {
+      const args = ownerRepo
+        ? [
+            'pr',
+            'view',
+            String(linkedPRNumber),
+            '--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'
+          ]
+      try {
+        const { stdout } = await ghExecFileAsync(args, { cwd: repoPath })
+        data = JSON.parse(stdout)
+      } catch {
+        // 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
+      }
     }
 
     if (!data) {
diff --git a/src/main/github/project-view.test.ts b/src/main/github/project-view.test.ts
new file mode 100644
index 00000000000..383fcb1d412
--- /dev/null
+++ b/src/main/github/project-view.test.ts
@@ -0,0 +1,144 @@
+// Why: covers the recent fixes —
+// (a) network errors must NOT be misclassified as not_found ("could not
+//     resolve host" partially overlaps "could not resolve to a"),
+// (b) repo slug validation must accept names with leading underscore
+//     (GitHub allows them, e.g. `_internal`),
+// (c) owner slug validation must reject `.`/`_` (GitHub disallows them in
+//     usernames/orgs),
+// (d) parseProjectPaste shorthand owner-only alphabet matches the renderer.
+import { describe, expect, it } from 'vitest'
+import {
+  classifyProjectError,
+  isValidOwnerSlug,
+  isValidRepoSlug,
+  parseProjectPaste
+} from './project-view'
+
+describe('classifyProjectError', () => {
+  it('classifies HTTP 404 as not_found', () => {
+    expect(classifyProjectError('HTTP 404 Not Found', '').type).toBe('not_found')
+  })
+
+  it('classifies "Could not resolve to a User" as not_found', () => {
+    expect(classifyProjectError('Could not resolve to a User with the login of foo', '').type).toBe(
+      'not_found'
+    )
+  })
+
+  it('classifies "could not resolve host" as network_error, NOT not_found', () => {
+    // Why: this was the bug — substring "could not resolve" overlaps. The
+    // network branch must run before not_found, and the not_found check
+    // must require "to a " to disambiguate.
+    expect(classifyProjectError('could not resolve host: api.github.com', '').type).toBe(
+      'network_error'
+    )
+  })
+
+  it('classifies "dial tcp" timeouts as network_error', () => {
+    expect(classifyProjectError('dial tcp 140.82.112.3:443: i/o timeout', '').type).toBe(
+      'network_error'
+    )
+  })
+
+  it('classifies rate-limit text as rate_limited', () => {
+    expect(classifyProjectError('API rate limit exceeded for user', '').type).toBe('rate_limited')
+  })
+
+  it('classifies missing-scope as scope_missing', () => {
+    expect(
+      classifyProjectError('your token has not been granted the required scopes', '').type
+    ).toBe('scope_missing')
+  })
+
+  it('classifies auth-required when gh is not signed in', () => {
+    expect(classifyProjectError('gh auth login required', '').type).toBe('auth_required')
+  })
+})
+
+describe('isValidOwnerSlug', () => {
+  it('accepts plain alphanumerics and hyphens', () => {
+    expect(isValidOwnerSlug('acme')).toBe(true)
+    expect(isValidOwnerSlug('acme-co')).toBe(true)
+    expect(isValidOwnerSlug('user1')).toBe(true)
+  })
+
+  it('rejects underscore (GitHub disallows it in usernames/orgs)', () => {
+    expect(isValidOwnerSlug('_acme')).toBe(false)
+    expect(isValidOwnerSlug('acme_co')).toBe(false)
+  })
+
+  it('rejects leading hyphen and dot', () => {
+    expect(isValidOwnerSlug('-acme')).toBe(false)
+    expect(isValidOwnerSlug('.acme')).toBe(false)
+  })
+
+  it('rejects empty and slash-containing values', () => {
+    expect(isValidOwnerSlug('')).toBe(false)
+    expect(isValidOwnerSlug('a/b')).toBe(false)
+    expect(isValidOwnerSlug(123)).toBe(false)
+  })
+})
+
+describe('isValidRepoSlug', () => {
+  it('accepts leading underscore (GitHub allows it for repo names)', () => {
+    expect(isValidRepoSlug('_internal')).toBe(true)
+  })
+
+  it('accepts leading dot', () => {
+    expect(isValidRepoSlug('.github')).toBe(true)
+  })
+
+  it('accepts dots, dashes, underscores anywhere', () => {
+    expect(isValidRepoSlug('repo-name')).toBe(true)
+    expect(isValidRepoSlug('repo.name')).toBe(true)
+    expect(isValidRepoSlug('repo_name')).toBe(true)
+  })
+
+  it('rejects reserved single/double dot', () => {
+    expect(isValidRepoSlug('.')).toBe(false)
+    expect(isValidRepoSlug('..')).toBe(false)
+  })
+
+  it('rejects path separators and empty', () => {
+    expect(isValidRepoSlug('a/b')).toBe(false)
+    expect(isValidRepoSlug('')).toBe(false)
+  })
+})
+
+describe('parseProjectPaste', () => {
+  it('parses owner/number shorthand', () => {
+    expect(parseProjectPaste('acme/42')).toEqual({ kind: 'bare', owner: 'acme', number: 42 })
+  })
+
+  it('rejects shorthand with underscore in owner (renderer parity)', () => {
+    // Why: the renderer's parser uses `[A-Za-z0-9][A-Za-z0-9-]*` for owner
+    // (matches OWNER_SLUG_RE). Both sides must reject the same inputs.
+    expect(parseProjectPaste('co_op/45')).toBeNull()
+  })
+
+  it('parses org URL with view number', () => {
+    expect(parseProjectPaste('https://github.com/orgs/acme/projects/42/views/3')).toEqual({
+      kind: 'org',
+      owner: 'acme',
+      number: 42,
+      viewNumber: 3
+    })
+  })
+
+  it('parses user URL', () => {
+    expect(parseProjectPaste('https://github.com/users/octocat/projects/1')).toEqual({
+      kind: 'user',
+      owner: 'octocat',
+      number: 1
+    })
+  })
+
+  it('rejects URLs whose owner has invalid characters', () => {
+    expect(parseProjectPaste('https://github.com/orgs/co_op/projects/1')).toBeNull()
+  })
+
+  it('returns null for empty input', () => {
+    expect(parseProjectPaste('')).toBeNull()
+    expect(parseProjectPaste('   ')).toBeNull()
+  })
+})
diff --git a/src/main/github/project-view.ts b/src/main/github/project-view.ts
new file mode 100644
index 00000000000..1a06723e90c
Binary files /dev/null and b/src/main/github/project-view.ts differ
diff --git a/src/main/github/project-view/internals.ts b/src/main/github/project-view/internals.ts
new file mode 100644
index 00000000000..52509c30652
--- /dev/null
+++ b/src/main/github/project-view/internals.ts
@@ -0,0 +1,378 @@
+/* eslint-disable max-lines -- Why: shared infrastructure for project-view —
+slug validation, error classification, runGraphql/runRest, and rate-limit
+synthesis. Co-located so the read and write paths observe identical
+classification semantics. */
+// Why: `ghExecFileAsync` (WSL-aware, retry-enabled) is the single spawn site
+// for gh calls. The legacy plain `execFileAsync` is NOT used here — routing
+// every gh call through the runner gives us transient-5xx retry, WSL path
+// translation, and a single hook point for future quota tracking.
+import { acquire, release } from '../gh-utils'
+import { extractExecError, ghExecFileAsync } from '../../git/runner'
+import { rateLimitGuard, noteRateLimitSpend, type RateLimitBucketKind } from '../rate-limit'
+import type { GitHubProjectViewError } from '../../../shared/github-project-types'
+
+export { acquire, release, extractExecError, ghExecFileAsync, rateLimitGuard, noteRateLimitSpend }
+export type { RateLimitBucketKind }
+
+// ─── Slug validation ──────────────────────────────────────────────────
+
+// Why: GitHub usernames/org logins disallow `_`, `.`, leading `-`. Repo names
+// are looser — they allow leading `_`, `.`, `-` (`.` and `..` reserved). We
+// validate each separately so untrusted Project row data (`nameWithOwner`)
+// can't become an arbitrary REST path while still accepting realistic repo
+// names like `_internal` or `.github`.
+const OWNER_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/
+const REPO_SLUG_RE = /^[A-Za-z0-9._-]+$/
+const REPO_SLUG_RESERVED = new Set(['.', '..'])
+
+export function isValidOwnerSlug(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && OWNER_SLUG_RE.test(value)
+}
+
+export function isValidRepoSlug(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    REPO_SLUG_RE.test(value) &&
+    !REPO_SLUG_RESERVED.has(value)
+  )
+}
+
+// Backwards-compatible alias for callers that don't distinguish owner vs repo.
+// Prefer `isValidOwnerSlug` / `isValidRepoSlug` at new call sites.
+export function isValidSlug(value: unknown): value is string {
+  return isValidOwnerSlug(value) || isValidRepoSlug(value)
+}
+
+export function assertSlug(
+  value: unknown,
+  field: 'owner' | 'repo'
+): { ok: true; slug: string } | { ok: false; error: GitHubProjectViewError } {
+  const valid = field === 'owner' ? isValidOwnerSlug(value) : isValidRepoSlug(value)
+  if (!valid) {
+    return {
+      ok: false,
+      error: {
+        type: 'validation_error',
+        message: `Invalid ${field}: "${String(value)}" is not a valid GitHub slug.`
+      }
+    }
+  }
+  return { ok: true, slug: value as string }
+}
+
+export function assertPositiveInt(
+  value: unknown,
+  field: string
+): { ok: true; n: number } | { ok: false; error: GitHubProjectViewError } {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    return {
+      ok: false,
+      error: {
+        type: 'validation_error',
+        message: `Invalid ${field}: must be a positive integer.`
+      }
+    }
+  }
+  return { ok: true, n: value }
+}
+
+export function validateSlugArgs(
+  owner: unknown,
+  repo: unknown
+): { ok: true } | { ok: false; error: GitHubProjectViewError } {
+  const o = assertSlug(owner, 'owner')
+  if (!o.ok) {
+    return { ok: false, error: o.error }
+  }
+  const r = assertSlug(repo, 'repo')
+  if (!r.ok) {
+    return { ok: false, error: r.error }
+  }
+  return { ok: true }
+}
+
+// ─── Error classification ──────────────────────────────────────────────
+
+export type GhGraphqlErrorShape = {
+  type?: string
+  message?: string
+  path?: (string | number)[]
+  extensions?: { code?: string }
+}
+
+export function extractGraphqlErrors(stderr: string, stdout: string): GhGraphqlErrorShape[] {
+  // `gh api graphql` prints the response JSON to stdout even on GraphQL
+  // errors, and the stderr carries a summary. Try stdout first; if parsing
+  // fails, fall back to stderr.
+  const sources = [stdout, stderr]
+  for (const src of sources) {
+    if (!src) {
+      continue
+    }
+    try {
+      const parsed = JSON.parse(src) as { errors?: GhGraphqlErrorShape[] }
+      if (parsed.errors && parsed.errors.length > 0) {
+        return parsed.errors
+      }
+    } catch {
+      // not JSON — continue
+    }
+  }
+  return []
+}
+
+export function errorsIndicateParentField(errors: GhGraphqlErrorShape[], stderr: string): boolean {
+  const lower = stderr.toLowerCase()
+  // Preview-header shape: gh returns a 4xx with "preview" in the message.
+  if (lower.includes('preview') && lower.includes('parent')) {
+    return true
+  }
+  return errors.some((e) => {
+    const type = (e.type ?? '').toUpperCase()
+    if (type === 'FIELD_NOT_FOUND' || type === 'UNDEFINED_FIELD' || type === 'FIELD_ERRORS') {
+      const tail = e.path?.at(-1)
+      if (tail === 'parent') {
+        return true
+      }
+      // FIELD_ERRORS often omits `path`; match on message for the parent field.
+      if ((e.message ?? '').toLowerCase().includes('parent')) {
+        return true
+      }
+    }
+    return false
+  })
+}
+
+export function classifyProjectError(stderr: string, stdout: string): GitHubProjectViewError {
+  const errors = extractGraphqlErrors(stderr, stdout)
+  const s = stderr.toLowerCase()
+
+  // Auth
+  if (
+    s.includes('authentication required') ||
+    s.includes('not logged in') ||
+    s.includes('gh auth login')
+  ) {
+    return {
+      type: 'auth_required',
+      message: 'Sign in to GitHub to load project tasks. Run `gh auth login`.'
+    }
+  }
+  // Scope
+  if (
+    s.includes('missing required scope') ||
+    s.includes('your token has not been granted') ||
+    (s.includes('resource not accessible') && (s.includes('project') || s.includes('scope')))
+  ) {
+    return {
+      type: 'scope_missing',
+      message:
+        'GitHub project access needs additional scopes. Run `gh auth refresh -s project -s read:org -s repo`.'
+    }
+  }
+  // Rate limit
+  if (s.includes('rate limit') || s.includes('api rate limit exceeded')) {
+    return { type: 'rate_limited', message: 'GitHub rate limit hit. Try again in a few minutes.' }
+  }
+  // Network — checked BEFORE not_found because DNS failures surface as
+  // "could not resolve host", which would otherwise be partially matched by
+  // the not_found branch's "could not resolve" check. Substring matching here
+  // is a one-way trapdoor: a real GraphQL "Could not resolve to a User…"
+  // error always contains "to a", so we tighten the not_found check below to
+  // require that token.
+  if (
+    s.includes('timeout') ||
+    s.includes('no such host') ||
+    s.includes('network') ||
+    s.includes('could not resolve host') ||
+    s.includes('dial tcp')
+  ) {
+    return { type: 'network_error', message: 'Network error — check your connection.' }
+  }
+  // Not found
+  if (
+    s.includes('http 404') ||
+    errors.some((e) => (e.type ?? '').toUpperCase() === 'NOT_FOUND') ||
+    // Why: GitHub uses "to an" for vowel-leading types ("to an Issue", "to
+    // an Organization") and "to a" otherwise. The previous singular-only
+    // check missed the "an" variants when gh emits only the stderr summary
+    // without a structured GraphQL error array. See bug-scan finding 3.
+    /could not resolve to an? /.test(s)
+  ) {
+    const firstNotFound = errors.find((e) => (e.type ?? '').toUpperCase() === 'NOT_FOUND')
+    return {
+      type: 'not_found',
+      message: 'Project or view not found.',
+      details: firstNotFound
+        ? { path: firstNotFound.path, code: firstNotFound.extensions?.code }
+        : undefined
+    }
+  }
+  // Validation
+  if (s.includes('http 422') || s.includes('validation failed')) {
+    return { type: 'validation_error', message: `Invalid request — ${stderr.trim()}` }
+  }
+  // GraphQL error with structured info
+  if (errors.length > 0) {
+    const first = errors[0]
+    return {
+      type: 'unknown',
+      message: first.message ?? 'Unknown GraphQL error.',
+      details: { path: first.path, code: first.extensions?.code }
+    }
+  }
+  // Why: don't leak full stderr to the UI — it can include verbose request
+  // dumps with header diagnostics. Truncate to the first non-empty line and
+  // cap length so unexpected diagnostics stay readable but bounded.
+  const firstLine =
+    stderr
+      .split('\n')
+      .map((l) => l.trim())
+      .find((l) => l.length > 0) ?? ''
+  const safe = firstLine.length > 200 ? `${firstLine.slice(0, 200)}…` : firstLine
+  return {
+    type: 'unknown',
+    message: safe ? `GitHub request failed: ${safe}` : 'GitHub request failed.'
+  }
+}
+
+export function driftError(
+  reason: string,
+  details?: { path?: (string | number)[]; code?: string }
+): GitHubProjectViewError {
+  return { type: 'schema_drift', message: `Could not read this project view: ${reason}.`, details }
+}
+
+// Why: the rate-limit circuit breaker short-circuits before we spawn `gh`
+// when the cached snapshot says we're below the safety floor. Synthesize the
+// same `rate_limited` error shape as the post-hoc classifier so the UI path
+// is unchanged. We DO NOT fail open here when there's no cached snapshot —
+// rateLimitGuard already handles that case (returns `blocked:false`).
+export function rateLimitedError(blocked: {
+  remaining: number
+  limit: number
+  resetAt: number
+}): GitHubProjectViewError {
+  const resetIn = Math.max(0, blocked.resetAt - Math.floor(Date.now() / 1000))
+  const mins = Math.ceil(resetIn / 60)
+  return {
+    type: 'rate_limited',
+    message: `GitHub rate limit nearly exhausted (${blocked.remaining}/${blocked.limit} left). Resets in ~${mins}m.`
+  }
+}
+
+// ─── Low-level gh api graphql invocation ───────────────────────────────
+
+export type GraphqlVars = Record<string, string | number | boolean>
+
+export async function runGraphql<T>(
+  query: string,
+  vars: GraphqlVars,
+  cwd?: string
+): Promise<
+  | { ok: true; data: T }
+  | { ok: false; error: GitHubProjectViewError; raw: { stderr: string; stdout: string } }
+> {
+  const guard = rateLimitGuard('graphql')
+  if (guard.blocked) {
+    return { ok: false, error: rateLimitedError(guard), raw: { stderr: '', stdout: '' } }
+  }
+  // Why: build argv as an array. `-f` for strings (including numbers passed
+  // as strings), `-F` coerces to typed. We use `-f` uniformly and coerce in
+  // the query via Int! casts, because `gh` can confuse empty strings.
+  const args: string[] = ['api', 'graphql', '-f', `query=${query}`]
+  for (const [k, v] of Object.entries(vars)) {
+    if (typeof v === 'number' || typeof v === 'boolean') {
+      args.push('-F', `${k}=${String(v)}`)
+    } else {
+      args.push('-f', `${k}=${v}`)
+    }
+  }
+  await acquire()
+  noteRateLimitSpend('graphql')
+  try {
+    const { stdout, stderr } = await ghExecFileAsync(args, {
+      encoding: 'utf-8',
+      ...(cwd ? { cwd } : {})
+    })
+    try {
+      const parsed = JSON.parse(stdout) as { data?: T; errors?: GhGraphqlErrorShape[] }
+      if (parsed.errors && parsed.errors.length > 0) {
+        return {
+          ok: false,
+          error: classifyProjectError(stderr, stdout),
+          raw: { stderr, stdout }
+        }
+      }
+      if (parsed.data === undefined) {
+        return {
+          ok: false,
+          error: driftError('response missing data'),
+          raw: { stderr, stdout }
+        }
+      }
+      return { ok: true, data: parsed.data }
+    } catch (parseErr) {
+      return {
+        ok: false,
+        error: driftError(
+          `failed to parse response (${parseErr instanceof Error ? parseErr.message : String(parseErr)})`
+        ),
+        raw: { stderr, stdout }
+      }
+    }
+  } catch (err) {
+    // gh executable failures (non-zero exit). Read stderr/stdout from the
+    // exec rejection's explicit fields — `err.message` may truncate stderr.
+    const { stderr, stdout: maybeStdout } = extractExecError(err)
+    return {
+      ok: false,
+      error: classifyProjectError(stderr, maybeStdout),
+      raw: { stderr, stdout: maybeStdout }
+    }
+  } finally {
+    release()
+  }
+}
+
+export async function runRest<T>(
+  args: string[],
+  cwd?: string,
+  bucket: RateLimitBucketKind = 'core',
+  options?: { expectEmpty?: boolean }
+): Promise<{ ok: true; data: T } | { ok: false; error: GitHubProjectViewError }> {
+  const guard = rateLimitGuard(bucket)
+  if (guard.blocked) {
+    return { ok: false, error: rateLimitedError(guard) }
+  }
+  await acquire()
+  noteRateLimitSpend(bucket)
+  try {
+    const { stdout, stderr } = await ghExecFileAsync(['api', ...args], {
+      encoding: 'utf-8',
+      ...(cwd ? { cwd } : {})
+    })
+    // Why: 204/empty-body endpoints (DELETE label, DELETE comment) return no
+    // body. Treat empty stdout as success rather than misclassifying the
+    // unparseable response as 'unknown' — which the caller would otherwise
+    // need to special-case and risks masking real failures whose stderr the
+    // classifier also tags as 'unknown'.
+    if (options?.expectEmpty && stdout.trim() === '') {
+      return { ok: true, data: undefined as T }
+    }
+    try {
+      return { ok: true, data: JSON.parse(stdout) as T }
+    } catch {
+      return {
+        ok: false,
+        error: { type: 'unknown', message: `Unexpected REST response: ${stderr.trim()}` }
+      }
+    }
+  } catch (err) {
+    const { stderr, stdout: maybeStdout } = extractExecError(err)
+    return { ok: false, error: classifyProjectError(stderr, maybeStdout) }
+  } finally {
+    release()
+  }
+}
diff --git a/src/main/github/project-view/mutations.ts b/src/main/github/project-view/mutations.ts
new file mode 100644
index 00000000000..cd4e0944fc9
--- /dev/null
+++ b/src/main/github/project-view/mutations.ts
@@ -0,0 +1,841 @@
+/* eslint-disable max-lines -- Why: slug-addressed mutations + work-item
+details share the validate/runRest/runGraphql plumbing with the read path.
+Keeping them together preserves a single review surface for the write side. */
+import {
+  acquire,
+  release,
+  extractExecError,
+  ghExecFileAsync,
+  rateLimitGuard,
+  noteRateLimitSpend,
+  classifyProjectError,
+  rateLimitedError,
+  runGraphql,
+  runRest,
+  validateSlugArgs,
+  assertPositiveInt,
+  type GraphqlVars
+} from './internals'
+import type { GitHubAssignableUser, GitHubWorkItemDetails, PRComment } from '../../../shared/types'
+import type {
+  AddIssueCommentBySlugArgs,
+  ClearProjectItemFieldArgs,
+  DeleteIssueCommentBySlugArgs,
+  GitHubProjectCommentMutationResult,
+  GitHubProjectFieldMutationValue,
+  GitHubProjectMutationResult,
+  ListAssignableUsersBySlugArgs,
+  ListAssignableUsersBySlugResult,
+  ListIssueTypesBySlugArgs,
+  ListIssueTypesBySlugResult,
+  ListLabelsBySlugArgs,
+  ListLabelsBySlugResult,
+  ProjectWorkItemDetailsBySlugArgs,
+  ProjectWorkItemDetailsBySlugResult,
+  UpdateIssueBySlugArgs,
+  UpdateIssueCommentBySlugArgs,
+  UpdateIssueTypeBySlugArgs,
+  UpdatePullRequestBySlugArgs,
+  UpdateProjectItemFieldArgs
+} from '../../../shared/github-project-types'
+
+// ─── Project field mutations ──────────────────────────────────────────
+
+class UnknownFieldMutationKindError extends Error {
+  constructor(kind: string) {
+    super(`Unknown project field mutation kind: ${kind}`)
+  }
+}
+
+function graphqlValueForFieldMutation(value: GitHubProjectFieldMutationValue): string {
+  // Serialize the value fragment for the GraphQL mutation. We use GraphQL
+  // variables for every dynamic piece, so here we only pick the variable name
+  // to reference per value kind.
+  switch (value.kind) {
+    case 'single-select':
+      return 'singleSelectOptionId: $value'
+    case 'iteration':
+      return 'iterationId: $value'
+    case 'text':
+      return 'text: $value'
+    case 'number':
+      return 'number: $value'
+    case 'date':
+      return 'date: $value'
+    default:
+      // Why: defensive default. If a new mutation kind is added to the type
+      // but not handled here, returning undefined would silently produce a
+      // broken GraphQL query. Throw so updateProjectItemFieldValue can map it
+      // to a validation_error rather than dispatching a malformed mutation.
+      throw new UnknownFieldMutationKindError((value as { kind: string }).kind)
+  }
+}
+
+function mutationValueVar(value: GitHubProjectFieldMutationValue): {
+  type: string
+  val: string | number
+} {
+  switch (value.kind) {
+    case 'single-select':
+      return { type: 'String!', val: value.optionId }
+    case 'iteration':
+      return { type: 'String!', val: value.iterationId }
+    case 'text':
+      return { type: 'String!', val: value.text }
+    case 'number':
+      return { type: 'Float!', val: value.number }
+    case 'date':
+      return { type: 'Date!', val: value.date }
+    default:
+      // Why: see graphqlValueForFieldMutation — surface unknown kinds loudly
+      // instead of returning undefined and dispatching an invalid mutation.
+      throw new UnknownFieldMutationKindError((value as { kind: string }).kind)
+  }
+}
+
+export async function updateProjectItemFieldValue(
+  args: UpdateProjectItemFieldArgs
+): Promise<GitHubProjectMutationResult> {
+  if (!args.projectId || !args.itemId || !args.fieldId) {
+    return { ok: false, error: { type: 'validation_error', message: 'Missing ids.' } }
+  }
+  let valFrag: string
+  let valVar: { type: string; val: string | number }
+  try {
+    valFrag = graphqlValueForFieldMutation(args.value)
+    valVar = mutationValueVar(args.value)
+  } catch (err) {
+    if (err instanceof UnknownFieldMutationKindError) {
+      return { ok: false, error: { type: 'validation_error', message: err.message } }
+    }
+    throw err
+  }
+  const query = `
+    mutation($projectId:ID!, $itemId:ID!, $fieldId:ID!, $value:${valVar.type}) {
+      updateProjectV2ItemFieldValue(input: {
+        projectId: $projectId
+        itemId: $itemId
+        fieldId: $fieldId
+        value: { ${valFrag} }
+      }) { projectV2Item { id } }
+    }
+  `
+  const vars: GraphqlVars = {
+    projectId: args.projectId,
+    itemId: args.itemId,
+    fieldId: args.fieldId,
+    value: valVar.val
+  }
+  const res = await runGraphql<unknown>(query, vars)
+  if (!res.ok) {
+    return { ok: false, error: res.error }
+  }
+  return { ok: true }
+}
+
+export async function clearProjectItemFieldValue(
+  args: ClearProjectItemFieldArgs
+): Promise<GitHubProjectMutationResult> {
+  if (!args.projectId || !args.itemId || !args.fieldId) {
+    return { ok: false, error: { type: 'validation_error', message: 'Missing ids.' } }
+  }
+  const query = `
+    mutation($projectId:ID!, $itemId:ID!, $fieldId:ID!) {
+      clearProjectV2ItemFieldValue(input: {
+        projectId: $projectId
+        itemId: $itemId
+        fieldId: $fieldId
+      }) { projectV2Item { id } }
+    }
+  `
+  const res = await runGraphql<unknown>(query, {
+    projectId: args.projectId,
+    itemId: args.itemId,
+    fieldId: args.fieldId
+  })
+  if (!res.ok) {
+    return { ok: false, error: res.error }
+  }
+  return { ok: true }
+}
+
+// ─── Slug-addressed issue/PR mutations ────────────────────────────────
+
+export async function updateIssueBySlug(
+  args: UpdateIssueBySlugArgs
+): Promise<GitHubProjectMutationResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const n = assertPositiveInt(args.number, 'number')
+  if (!n.ok) {
+    return { ok: false, error: n.error }
+  }
+  if (!args.updates || typeof args.updates !== 'object') {
+    return { ok: false, error: { type: 'validation_error', message: 'Updates required.' } }
+  }
+  const { title, body, state, addLabels, removeLabels, addAssignees, removeAssignees } =
+    args.updates
+
+  // Title / body / state go through PATCH /repos/{owner}/{repo}/issues/{n}.
+  // Labels/assignees go through their dedicated endpoints.
+  const base = `repos/${args.owner}/${args.repo}/issues/${args.number}`
+
+  // 1) PATCH body
+  if (title !== undefined || body !== undefined || state !== undefined) {
+    const patchArgs: string[] = ['-X', 'PATCH', base]
+    if (title !== undefined) {
+      patchArgs.push('--raw-field', `title=${title}`)
+    }
+    if (body !== undefined) {
+      patchArgs.push('--raw-field', `body=${body}`)
+    }
+    if (state !== undefined) {
+      patchArgs.push('--raw-field', `state=${state}`)
+    }
+    const r = await runRest<unknown>(patchArgs)
+    if (!r.ok) {
+      return { ok: false, error: r.error }
+    }
+  }
+
+  // 2) Labels — collapse multi-delete fan-out into a single PUT when removing
+  //    >1 label. PUT /labels replaces the entire label set, so we fetch the
+  //    current labels first and compute the resulting set client-side. This
+  //    turns an N-delete + 1-add (=N+1 calls) into 1-fetch + 1-PUT (=2 calls)
+  //    once removeLabels has more than one entry, capping the cost at 2 even
+  //    for a "remove all 20 labels" mutation.
+  const removeCount = removeLabels?.length ?? 0
+  const addCount = addLabels?.length ?? 0
+  if (removeCount > 1) {
+    type RawLabelResp = { name?: string }[]
+    const fetched = await runRest<RawLabelResp>(['-X', 'GET', `${base}/labels`])
+    if (!fetched.ok) {
+      return { ok: false, error: fetched.error }
+    }
+    const currentNames = new Set(
+      fetched.data.map((l) => l.name).filter((n): n is string => typeof n === 'string')
+    )
+    for (const l of removeLabels ?? []) {
+      currentNames.delete(l)
+    }
+    for (const l of addLabels ?? []) {
+      currentNames.add(l)
+    }
+    if (currentNames.size === 0) {
+      // Why: `gh api -X PUT` with no `--raw-field` arguments sends an empty
+      // body — GitHub does NOT interpret that as "clear labels". The
+      // dedicated DELETE endpoint is the documented way to remove all
+      // labels in a single call.
+      const r = await runRest<unknown>(['-X', 'DELETE', `${base}/labels`], undefined, 'core', {
+        expectEmpty: true
+      })
+      if (!r.ok && r.error.type !== 'not_found') {
+        return { ok: false, error: r.error }
+      }
+    } else {
+      const putArgs = ['-X', 'PUT', `${base}/labels`]
+      for (const name of currentNames) {
+        putArgs.push('--raw-field', `labels[]=${name}`)
+      }
+      const r = await runRest<unknown>(putArgs)
+      if (!r.ok) {
+        return { ok: false, error: r.error }
+      }
+    }
+  } else {
+    if (addCount > 0) {
+      const restArgs = ['-X', 'POST', `${base}/labels`]
+      for (const l of addLabels ?? []) {
+        restArgs.push('--raw-field', `labels[]=${l}`)
+      }
+      const r = await runRest<unknown>(restArgs)
+      if (!r.ok) {
+        return { ok: false, error: r.error }
+      }
+    }
+    if (removeCount === 1) {
+      const r = await runRest<unknown>(
+        ['-X', 'DELETE', `${base}/labels/${encodeURIComponent(removeLabels![0])}`],
+        undefined,
+        'core',
+        { expectEmpty: true }
+      )
+      if (!r.ok && r.error.type !== 'not_found') {
+        return { ok: false, error: r.error }
+      }
+    }
+  }
+
+  // 3) Assignees — POST and DELETE both accept arrays in a single call, so
+  //    add/remove are at most 2 calls regardless of array size.
+  if (addAssignees && addAssignees.length > 0) {
+    const restArgs = ['-X', 'POST', `${base}/assignees`]
+    for (const u of addAssignees) {
+      restArgs.push('--raw-field', `assignees[]=${u}`)
+    }
+    const r = await runRest<unknown>(restArgs)
+    if (!r.ok) {
+      return { ok: false, error: r.error }
+    }
+  }
+  if (removeAssignees && removeAssignees.length > 0) {
+    const restArgs = ['-X', 'DELETE', `${base}/assignees`]
+    for (const u of removeAssignees) {
+      restArgs.push('--raw-field', `assignees[]=${u}`)
+    }
+    const r = await runRest<unknown>(restArgs)
+    if (!r.ok) {
+      return { ok: false, error: r.error }
+    }
+  }
+  return { ok: true }
+}
+
+export async function updatePullRequestBySlug(
+  args: UpdatePullRequestBySlugArgs
+): Promise<GitHubProjectMutationResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const n = assertPositiveInt(args.number, 'number')
+  if (!n.ok) {
+    return { ok: false, error: n.error }
+  }
+  if (!args.updates || typeof args.updates !== 'object') {
+    return { ok: false, error: { type: 'validation_error', message: 'Updates required.' } }
+  }
+  const patchArgs: string[] = [
+    '-X',
+    'PATCH',
+    `repos/${args.owner}/${args.repo}/pulls/${args.number}`
+  ]
+  // Why: count fields explicitly rather than inferring from patchArgs.length —
+  // adding a future header/flag arg silently breaks an array-length check.
+  let fieldCount = 0
+  if (args.updates.title !== undefined) {
+    patchArgs.push('--raw-field', `title=${args.updates.title}`)
+    fieldCount++
+  }
+  if (args.updates.body !== undefined) {
+    patchArgs.push('--raw-field', `body=${args.updates.body}`)
+    fieldCount++
+  }
+  if (fieldCount === 0) {
+    // No fields to update — nothing to do.
+    return { ok: true }
+  }
+  const r = await runRest<unknown>(patchArgs)
+  if (!r.ok) {
+    return { ok: false, error: r.error }
+  }
+  return { ok: true }
+}
+
+type RawIssueCommentResponse = {
+  id?: number
+  user?: { login?: string; avatar_url?: string; type?: string } | null
+  body?: string
+  created_at?: string
+  html_url?: string
+}
+
+function mapIssueComment(data: RawIssueCommentResponse, fallbackBody: string): PRComment {
+  return {
+    id: data.id ?? Date.now(),
+    author: data.user?.login ?? 'You',
+    authorAvatarUrl: data.user?.avatar_url ?? '',
+    body: data.body ?? fallbackBody,
+    createdAt: data.created_at ?? new Date().toISOString(),
+    url: data.html_url ?? '',
+    isBot: data.user?.type === 'Bot'
+  }
+}
+
+export async function addIssueCommentBySlug(
+  args: AddIssueCommentBySlugArgs
+): Promise<GitHubProjectCommentMutationResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const n = assertPositiveInt(args.number, 'number')
+  if (!n.ok) {
+    return { ok: false, error: n.error }
+  }
+  if (typeof args.body !== 'string' || !args.body.trim()) {
+    return { ok: false, error: { type: 'validation_error', message: 'Comment body required.' } }
+  }
+  const r = await runRest<RawIssueCommentResponse>([
+    '-X',
+    'POST',
+    `repos/${args.owner}/${args.repo}/issues/${args.number}/comments`,
+    '--raw-field',
+    `body=${args.body}`
+  ])
+  if (!r.ok) {
+    return { ok: false, error: r.error }
+  }
+  return { ok: true, comment: mapIssueComment(r.data, args.body) }
+}
+
+export async function updateIssueCommentBySlug(
+  args: UpdateIssueCommentBySlugArgs
+): Promise<GitHubProjectMutationResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const n = assertPositiveInt(args.commentId, 'commentId')
+  if (!n.ok) {
+    return { ok: false, error: n.error }
+  }
+  if (typeof args.body !== 'string' || !args.body.trim()) {
+    return { ok: false, error: { type: 'validation_error', message: 'Comment body required.' } }
+  }
+  const r = await runRest<unknown>([
+    '-X',
+    'PATCH',
+    `repos/${args.owner}/${args.repo}/issues/comments/${args.commentId}`,
+    '--raw-field',
+    `body=${args.body}`
+  ])
+  if (!r.ok) {
+    return { ok: false, error: r.error }
+  }
+  return { ok: true }
+}
+
+export async function deleteIssueCommentBySlug(
+  args: DeleteIssueCommentBySlugArgs
+): Promise<GitHubProjectMutationResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const n = assertPositiveInt(args.commentId, 'commentId')
+  if (!n.ok) {
+    return { ok: false, error: n.error }
+  }
+  const r = await runRest<unknown>(
+    ['-X', 'DELETE', `repos/${args.owner}/${args.repo}/issues/comments/${args.commentId}`],
+    undefined,
+    'core',
+    { expectEmpty: true }
+  )
+  if (!r.ok) {
+    return { ok: false, error: r.error }
+  }
+  return { ok: true }
+}
+
+// ─── Slug-addressed picker sources ────────────────────────────────────
+
+export async function listLabelsBySlug(
+  args: ListLabelsBySlugArgs
+): Promise<ListLabelsBySlugResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const guard = rateLimitGuard('core')
+  if (guard.blocked) {
+    return { ok: false, error: rateLimitedError(guard) }
+  }
+  await acquire()
+  // Why: `--paginate` may fan out to multiple pages; we can only reasonably
+  // estimate a 1-call spend up front. The next probe will reconcile.
+  noteRateLimitSpend('core')
+  try {
+    const { stdout } = await ghExecFileAsync(
+      ['api', '--paginate', `repos/${args.owner}/${args.repo}/labels`, '--jq', '.[].name'],
+      { encoding: 'utf-8' }
+    )
+    return {
+      ok: true,
+      labels: stdout
+        .trim()
+        .split('\n')
+        .filter((l) => l.length > 0)
+    }
+  } catch (err) {
+    const { stderr, stdout: maybeStdout } = extractExecError(err)
+    return { ok: false, error: classifyProjectError(stderr, maybeStdout) }
+  } finally {
+    release()
+  }
+}
+
+export async function listAssignableUsersBySlug(
+  args: ListAssignableUsersBySlugArgs
+): Promise<ListAssignableUsersBySlugResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  // Seed logins merge after the fetch so callers can include currently-visible
+  // assignees even if the repo participant search is sparse.
+  const result: GitHubAssignableUser[] = []
+  const guard = rateLimitGuard('core')
+  if (guard.blocked) {
+    return { ok: false, error: rateLimitedError(guard) }
+  }
+  await acquire()
+  noteRateLimitSpend('core')
+  try {
+    const { stdout } = await ghExecFileAsync(
+      [
+        'api',
+        '--paginate',
+        `repos/${args.owner}/${args.repo}/assignees`,
+        '--jq',
+        '.[] | {login: .login, name: null, avatarUrl: .avatar_url}'
+      ],
+      { encoding: 'utf-8' }
+    )
+    for (const line of stdout
+      .trim()
+      .split('\n')
+      .filter((l) => l.length > 0)) {
+      try {
+        const u = JSON.parse(line) as { login?: string; avatarUrl?: string; name?: string | null }
+        if (typeof u.login === 'string') {
+          result.push({ login: u.login, name: u.name ?? null, avatarUrl: u.avatarUrl ?? '' })
+        }
+      } catch {
+        // skip malformed jq line
+      }
+    }
+  } catch (err) {
+    const { stderr } = extractExecError(err)
+    return { ok: false, error: classifyProjectError(stderr, '') }
+  } finally {
+    release()
+  }
+  if (args.seedLogins) {
+    const seen = new Set(result.map((u) => u.login))
+    for (const login of args.seedLogins) {
+      if (typeof login === 'string' && !seen.has(login)) {
+        result.push({ login, name: null, avatarUrl: '' })
+        seen.add(login)
+      }
+    }
+  }
+  return { ok: true, users: result }
+}
+
+// Why: Issue Types are a repo-level taxonomy (Bug/Feature/Task/etc) only
+// available on repos opted into typed-issues. Empty list (or schema_drift on
+// older GitHub deployments) is the legitimate "this repo doesn't use issue
+// types" signal — callers should treat it as "no editor".
+export async function listIssueTypesBySlug(
+  args: ListIssueTypesBySlugArgs
+): Promise<ListIssueTypesBySlugResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const query = `
+    query($owner:String!, $repo:String!) {
+      repository(owner:$owner, name:$repo) {
+        issueTypes(first:50) {
+          nodes { id name color description }
+        }
+      }
+    }
+  `
+  const res = await runGraphql<{
+    repository?: {
+      issueTypes?: {
+        nodes?: ({
+          id?: string
+          name?: string
+          color?: string | null
+          description?: string | null
+        } | null)[]
+      } | null
+    } | null
+  }>(query, { owner: args.owner, repo: args.repo })
+  if (!res.ok) {
+    // Why: repos without issue types respond with a GraphQL error claiming the
+    // `issueTypes` field is unknown. Map that to an empty list so the UI shows
+    // "no editor" instead of an angry banner.
+    if (res.error.type === 'schema_drift' || res.error.type === 'validation_error') {
+      return { ok: true, types: [] }
+    }
+    return { ok: false, error: res.error }
+  }
+  const nodes = res.data.repository?.issueTypes?.nodes ?? []
+  const types = nodes
+    .filter(
+      (n): n is NonNullable<typeof n> =>
+        n !== null && typeof n.id === 'string' && typeof n.name === 'string'
+    )
+    .map((n) => ({
+      id: n.id as string,
+      name: n.name as string,
+      color: typeof n.color === 'string' ? n.color : null,
+      description: typeof n.description === 'string' ? n.description : null
+    }))
+  return { ok: true, types }
+}
+
+export async function updateIssueTypeBySlug(
+  args: UpdateIssueTypeBySlugArgs
+): Promise<GitHubProjectMutationResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const n = assertPositiveInt(args.number, 'number')
+  if (!n.ok) {
+    return { ok: false, error: n.error }
+  }
+  // Why: `updateIssueIssueType` is the dedicated mutation; passing null for
+  // `issueTypeId` clears the type. We resolve the issue id via a lightweight
+  // GraphQL lookup because the REST endpoint doesn't accept issue types.
+  const lookup = await runGraphql<{
+    repository?: { issue?: { id?: string } | null } | null
+  }>(
+    `query($owner:String!, $repo:String!, $num:Int!) {
+       repository(owner:$owner, name:$repo) { issue(number:$num) { id } }
+     }`,
+    { owner: args.owner, repo: args.repo, num: args.number }
+  )
+  if (!lookup.ok) {
+    return { ok: false, error: lookup.error }
+  }
+  const issueId = lookup.data.repository?.issue?.id
+  if (!issueId) {
+    return { ok: false, error: { type: 'not_found', message: 'Issue not found.' } }
+  }
+  // Why: build the mutation conditionally so a null clear doesn't have to
+  // smuggle a null GraphQL variable through `gh api graphql -f`. The
+  // mutation accepts a literal `null` in the input object directly.
+  const query = args.issueTypeId
+    ? `
+        mutation($issueId:ID!, $issueTypeId:ID!) {
+          updateIssueIssueType(input: { issueId: $issueId, issueTypeId: $issueTypeId }) {
+            issue { id }
+          }
+        }
+      `
+    : `
+        mutation($issueId:ID!) {
+          updateIssueIssueType(input: { issueId: $issueId, issueTypeId: null }) {
+            issue { id }
+          }
+        }
+      `
+  const vars: GraphqlVars = args.issueTypeId
+    ? { issueId, issueTypeId: args.issueTypeId }
+    : { issueId }
+  const res = await runGraphql<unknown>(query, vars)
+  if (!res.ok) {
+    return { ok: false, error: res.error }
+  }
+  return { ok: true }
+}
+
+// ─── Slug-addressed work-item details ─────────────────────────────────
+
+type RawUser = { login?: string; name?: string | null; avatarUrl?: string | null }
+type RawLabel = { name?: string; color?: string }
+type RawWorkItemContent = {
+  id?: string
+  number?: number
+  title?: string
+  url?: string
+  state?: string
+  stateReason?: string | null
+  isDraft?: boolean
+  labels?: { nodes?: RawLabel[] }
+  assignees?: { nodes?: RawUser[] }
+}
+
+export async function getWorkItemDetailsBySlug(
+  args: ProjectWorkItemDetailsBySlugArgs
+): Promise<ProjectWorkItemDetailsBySlugResult> {
+  const v = validateSlugArgs(args.owner, args.repo)
+  if (!v.ok) {
+    return v
+  }
+  const n = assertPositiveInt(args.number, 'number')
+  if (!n.ok) {
+    return { ok: false, error: n.error }
+  }
+  if (args.type !== 'issue' && args.type !== 'pr') {
+    return { ok: false, error: { type: 'validation_error', message: 'Invalid type.' } }
+  }
+
+  // Single GraphQL round-trip to fetch the issue/PR summary + comments + labels + assignees.
+  const contentFrag =
+    args.type === 'issue'
+      ? `
+        issue(number:$num) {
+          id number title url state stateReason updatedAt
+          body
+          author { login }
+          labels(first:50) { nodes { name } }
+          assignees(first:50) { nodes { login } }
+          participants(first:50) { nodes { login name avatarUrl } }
+          comments(first:100) {
+            nodes {
+              databaseId
+              author { login avatarUrl __typename }
+              body createdAt url
+            }
+          }
+        }
+      `
+      : `
+        pullRequest(number:$num) {
+          id number title url state isDraft updatedAt headRefName baseRefName
+          body
+          author { login }
+          labels(first:50) { nodes { name } }
+          assignees(first:50) { nodes { login } }
+          participants(first:50) { nodes { login name avatarUrl } }
+          comments(first:100) {
+            nodes {
+              databaseId
+              author { login avatarUrl __typename }
+              body createdAt url
+            }
+          }
+        }
+      `
+  const query = `
+    query($owner:String!, $repo:String!, $num:Int!) {
+      repository(owner:$owner, name:$repo) {
+        ${contentFrag}
+      }
+    }
+  `
+  const res = await runGraphql<{
+    repository?: {
+      issue?:
+        | (RawWorkItemContent & {
+            updatedAt?: string
+            body?: string
+            author?: { login?: string } | null
+            participants?: { nodes?: RawUser[] }
+            comments?: {
+              nodes?: ({
+                databaseId?: number
+                author?: { login?: string; avatarUrl?: string; __typename?: string } | null
+                body?: string
+                createdAt?: string
+                url?: string
+              } | null)[]
+            }
+          })
+        | null
+      pullRequest?:
+        | (RawWorkItemContent & {
+            updatedAt?: string
+            body?: string
+            headRefName?: string
+            baseRefName?: string
+            author?: { login?: string } | null
+            participants?: { nodes?: RawUser[] }
+            comments?: {
+              nodes?: ({
+                databaseId?: number
+                author?: { login?: string; avatarUrl?: string; __typename?: string } | null
+                body?: string
+                createdAt?: string
+                url?: string
+              } | null)[]
+            }
+          })
+        | null
+    } | null
+  }>(query, { owner: args.owner, repo: args.repo, num: args.number })
+  if (!res.ok) {
+    return { ok: false, error: res.error }
+  }
+  const raw = args.type === 'issue' ? res.data.repository?.issue : res.data.repository?.pullRequest
+  if (!raw) {
+    return { ok: false, error: { type: 'not_found', message: 'Item not found.' } }
+  }
+
+  const labels = (raw.labels?.nodes ?? [])
+    .map((l) => l?.name)
+    .filter((n): n is string => typeof n === 'string')
+  const assignees = (raw.assignees?.nodes ?? [])
+    .map((a) => a?.login)
+    .filter((l): l is string => typeof l === 'string')
+  const comments: PRComment[] = []
+  for (const c of raw.comments?.nodes ?? []) {
+    if (!c || typeof c.body !== 'string') {
+      continue
+    }
+    comments.push({
+      id: typeof c.databaseId === 'number' ? c.databaseId : Date.now(),
+      author: c.author?.login ?? '',
+      authorAvatarUrl: c.author?.avatarUrl ?? '',
+      body: c.body,
+      createdAt: typeof c.createdAt === 'string' ? c.createdAt : '',
+      url: typeof c.url === 'string' ? c.url : '',
+      isBot: c.author?.__typename === 'Bot'
+    })
+  }
+  const participants: GitHubAssignableUser[] = []
+  for (const p of raw.participants?.nodes ?? []) {
+    if (p && typeof p.login === 'string') {
+      participants.push({ login: p.login, name: p.name ?? null, avatarUrl: p.avatarUrl ?? '' })
+    }
+  }
+
+  const state: 'open' | 'closed' | 'merged' | 'draft' =
+    args.type === 'pr'
+      ? raw.isDraft
+        ? 'draft'
+        : raw.state === 'MERGED'
+          ? 'merged'
+          : raw.state === 'CLOSED'
+            ? 'closed'
+            : 'open'
+      : raw.state === 'CLOSED'
+        ? 'closed'
+        : 'open'
+
+  const details: GitHubWorkItemDetails = {
+    item: {
+      id: typeof raw.id === 'string' ? raw.id : '',
+      type: args.type,
+      number: typeof raw.number === 'number' ? raw.number : args.number,
+      title: typeof raw.title === 'string' ? raw.title : '',
+      state,
+      url: typeof raw.url === 'string' ? raw.url : '',
+      labels,
+      updatedAt:
+        typeof (raw as { updatedAt?: string }).updatedAt === 'string'
+          ? (raw as { updatedAt: string }).updatedAt
+          : '',
+      author:
+        typeof (raw as { author?: { login?: string } | null }).author?.login === 'string'
+          ? ((raw as { author: { login: string } }).author.login as string)
+          : null,
+      branchName:
+        args.type === 'pr' && typeof (raw as { headRefName?: string }).headRefName === 'string'
+          ? ((raw as { headRefName: string }).headRefName as string)
+          : undefined,
+      baseRefName:
+        args.type === 'pr' && typeof (raw as { baseRefName?: string }).baseRefName === 'string'
+          ? ((raw as { baseRefName: string }).baseRefName as string)
+          : undefined
+    },
+    body: typeof raw.body === 'string' ? raw.body : '',
+    comments,
+    participants,
+    // Why: PR files/checks/review-thread tabs depend on a local repo path and
+    // are out of Project-mode slug scope for v1. Omit them here; the dialog
+    // branches on their absence and hides those tabs.
+    ...(args.type === 'issue' ? { assignees } : {})
+  }
+  return { ok: true, details }
+}
diff --git a/src/main/github/rate-limit.ts b/src/main/github/rate-limit.ts
new file mode 100644
index 00000000000..1108b6bd219
--- /dev/null
+++ b/src/main/github/rate-limit.ts
@@ -0,0 +1,155 @@
+/**
+ * GitHub API rate-limit probe.
+ *
+ * Why: `listWorkItems` fan-out × selected repos plus `countWorkItems` in
+ * parallel, plus `listAccessibleProjects` org-walk, can chew through the
+ * core (5000/hr) or search (30/min) buckets quickly. Surfacing the remaining
+ * budget in the TaskPage header lets users self-regulate before they hit the
+ * wall — without actually throttling (which would hurt responsiveness in
+ * the common not-near-the-limit case). The probe itself is exempt from
+ * rate-limit accounting per GitHub docs.
+ *
+ * The result is intentionally minimal: we expose just the counts the UI
+ * needs (remaining + limit for the three buckets we actually stress). If a
+ * future feature needs reset-time countdowns we can add resetAt here.
+ */
+import type {
+  GetRateLimitResult,
+  GitHubRateLimitBucket,
+  GitHubRateLimitSnapshot
+} from '../../shared/types'
+import { acquire, release } from './gh-utils'
+import { ghExecFileAsync } from '../git/runner'
+
+// Why: GitHub explicitly states `GET /rate_limit` does NOT count against
+// any bucket, so the only reason to cache is to avoid spawning a `gh`
+// subprocess on every render. 30s is a pragmatic balance — short enough
+// that the number in the header feels live, long enough to absorb the
+// 1-per-second "is it safe now?" polling pattern UIs tend to fall into.
+const RATE_LIMIT_CACHE_TTL_MS = 30_000
+let cached: GitHubRateLimitSnapshot | null = null
+
+type GhRateLimitPayload = {
+  resources?: {
+    core?: { limit?: number; remaining?: number; reset?: number }
+    search?: { limit?: number; remaining?: number; reset?: number }
+    graphql?: { limit?: number; remaining?: number; reset?: number }
+  }
+}
+
+function parseBucket(
+  raw:
+    | {
+        limit?: number
+        remaining?: number
+        reset?: number
+      }
+    | undefined
+): GitHubRateLimitBucket {
+  // Why: if a bucket is absent from the response (old gh, partial response),
+  // return 0/0/now so the UI shows a clear "unknown" state (0/0 is
+  // unambiguous) rather than a misleading "plenty left" fallback.
+  return {
+    limit: typeof raw?.limit === 'number' ? raw.limit : 0,
+    remaining: typeof raw?.remaining === 'number' ? raw.remaining : 0,
+    resetAt: typeof raw?.reset === 'number' ? raw.reset : Math.floor(Date.now() / 1000)
+  }
+}
+
+/** @internal — test-only */
+export function _resetRateLimitCache(): void {
+  cached = null
+}
+
+// Why: hard-stop thresholds for the circuit breaker. We refuse to issue a new
+// gh request when the cached snapshot says the relevant bucket is below this
+// floor. Numbers chosen as "enough budget for one user-initiated flow":
+// - core/graphql at 50: a typical work-item details fetch + a few mutations
+// - search at 2: a search-driven view paginates in chunks of 1; 2 leaves the
+//   user one safety click without tipping into the 30/min hard limit
+// Below the floor, callers get a synthesized rate_limited error and never
+// spawn a gh subprocess.
+const MIN_REMAINING_CORE = 50
+const MIN_REMAINING_GRAPHQL = 50
+const MIN_REMAINING_SEARCH = 2
+
+export type RateLimitBucketKind = 'core' | 'graphql' | 'search'
+
+/**
+ * Return a "soft" stop reason if we should refuse to issue a new gh request
+ * for the given bucket. Returns null when there's no cached snapshot (we
+ * haven't probed yet — fail open) or when the bucket has enough budget left.
+ *
+ * Why: this is the proactive guard the pill alone cannot provide. The pill is
+ * informational; this function actually blocks the spawn. We deliberately keep
+ * it advisory (returns a reason, doesn't throw) so callers can format the
+ * envelope/error in their own shape.
+ */
+export function rateLimitGuard(bucket: RateLimitBucketKind):
+  | { blocked: false }
+  | {
+      blocked: true
+      remaining: number
+      limit: number
+      resetAt: number
+    } {
+  if (!cached) {
+    return { blocked: false }
+  }
+  const b = cached[bucket]
+  const floor =
+    bucket === 'core'
+      ? MIN_REMAINING_CORE
+      : bucket === 'graphql'
+        ? MIN_REMAINING_GRAPHQL
+        : MIN_REMAINING_SEARCH
+  // Why: only block when we have a positive limit (limit:0 means "unknown" per
+  // parseBucket fallback — don't block on missing data, that would brick the
+  // app on a single bad rate_limit response).
+  if (b.limit > 0 && b.remaining < floor) {
+    return { blocked: true, remaining: b.remaining, limit: b.limit, resetAt: b.resetAt }
+  }
+  return { blocked: false }
+}
+
+/**
+ * Decrement the cached `remaining` counter for a bucket after a successful
+ * spawn. Why: the canonical numbers come from the next probe, but between
+ * probes the cached snapshot would over-report budget if we didn't account
+ * for the work we just did. The decrement keeps the circuit breaker honest
+ * during a burst (e.g. paginating items) instead of waiting 30s for the cache
+ * to expire.
+ */
+export function noteRateLimitSpend(bucket: RateLimitBucketKind, cost = 1): void {
+  if (!cached) {
+    return
+  }
+  const b = cached[bucket]
+  if (b.remaining > 0) {
+    cached = { ...cached, [bucket]: { ...b, remaining: Math.max(0, b.remaining - cost) } }
+  }
+}
+
+export async function getRateLimit(options?: { force?: boolean }): Promise<GetRateLimitResult> {
+  if (!options?.force && cached && Date.now() - cached.fetchedAt < RATE_LIMIT_CACHE_TTL_MS) {
+    return { ok: true, snapshot: cached }
+  }
+  await acquire()
+  try {
+    const { stdout } = await ghExecFileAsync(['api', 'rate_limit'], { encoding: 'utf-8' })
+    const parsed = JSON.parse(stdout) as GhRateLimitPayload
+    const snapshot: GitHubRateLimitSnapshot = {
+      core: parseBucket(parsed.resources?.core),
+      search: parseBucket(parsed.resources?.search),
+      graphql: parseBucket(parsed.resources?.graphql),
+      fetchedAt: Date.now()
+    }
+    cached = snapshot
+    return { ok: true, snapshot }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { ok: false, error: message }
+  } finally {
+    release()
+  }
+}
diff --git a/src/main/index.ts b/src/main/index.ts
index 862055ddaf6..0cfc5d925d3 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -16,7 +16,8 @@ import { setAppRuntimeFlags } from './ipc/app'
 import { closeAllWatchers } from './ipc/filesystem-watcher'
 import { registerCoreHandlers } from './ipc/register-core-handlers'
 import { registerMobileHandlers } from './ipc/mobile'
-import { initTelemetry, shutdownTelemetry } from './telemetry/client'
+import { initTelemetry, shutdownTelemetry, trackAppOpenedOnce } from './telemetry/client'
+import { resolveConsent } from './telemetry/consent'
 import { triggerStartupNotificationRegistration } from './ipc/notifications'
 import { OrcaRuntimeService } from './runtime/orca-runtime'
 import { OrcaRuntimeRpcServer } from './runtime/runtime-rpc'
@@ -121,7 +122,16 @@ function focusExistingWindow(): void {
 // derives the lock identity from the `userData` path, so this placement lets
 // dev (`orca-dev`) and packaged (`orca`) runs lock in separate namespaces
 // instead of serialising against each other.
-const hasSingleInstanceLock = acquireSingleInstanceLock(app, focusExistingWindow)
+//
+// Why skip in dev: engineers routinely run `pnpm dev` in parallel from
+// multiple worktrees while shipping features, and the lock makes the second
+// `pnpm dev` exit silently. In dev we accept that `orca-runtime.json` and
+// `endpoint.env` may race (the bundled `orca-dev` CLI / agent hooks route
+// to whichever instance wrote last). The dev build is not used for real
+// 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)
 if (!hasSingleInstanceLock) {
   if (is.dev) {
     // Why: packaged runs have no attached console, but dev runs do. Emit a
@@ -208,6 +218,22 @@ function openMainWindow(): BrowserWindow {
     }
   })
 
+  // Why: telemetry-plan.md§First-launch experience anchors default-on
+  // `app_opened` to the first main-window load. Existing users in the
+  // pending-banner cohort resolve through telemetry/client.ts; this load
+  // path only fires once consent is already enabled.
+  const onFirstWindowLoad = (): void => {
+    if (!store) {
+      return
+    }
+    const consent = resolveConsent(store.getSettings())
+    if (consent.effective !== 'enabled') {
+      return
+    }
+    trackAppOpenedOnce()
+  }
+  window.webContents.on('did-finish-load', onFirstWindowLoad)
+
   registerCoreHandlers(
     store,
     runtime,
@@ -414,6 +440,7 @@ app.whenReady().then(async () => {
     // and defeat the teardown helper's prefix sweep (design §4.3 wire-up).
     getLocalProvider: () => getLocalPtyProvider()
   })
+  runtime.setAccountServices({ claudeAccounts, codexAccounts, rateLimits })
   starNag = new StarNagService(store, stats)
   starNag.start()
   starNag.registerIpcHandlers()
diff --git a/src/main/ipc/agent-trust.ts b/src/main/ipc/agent-trust.ts
new file mode 100644
index 00000000000..9ded836a371
--- /dev/null
+++ b/src/main/ipc/agent-trust.ts
@@ -0,0 +1,35 @@
+import { ipcMain } from 'electron'
+import { markCopilotFolderTrusted, markCursorWorkspaceTrusted } from '../agent-trust-presets'
+
+export type AgentTrustPreset = 'cursor' | 'copilot'
+
+/**
+ * Why: cursor-agent and GitHub Copilot CLI gate first-launch in an unfamiliar
+ * directory behind a "Do you trust this folder?" menu that consumes
+ * keystrokes (numbered options / single-letter shortcuts). Orca's draft-URL
+ * paste flow needs the input box, not the menu, so before Orca spawns the
+ * agent it asks main to write the same trust artifacts the agents write
+ * after the user accepts. Best-effort: any IO error is swallowed so a failed
+ * trust write never blocks the workspace from opening.
+ */
+export function registerAgentTrustHandlers(): void {
+  ipcMain.removeHandler('agentTrust:markTrusted')
+  ipcMain.handle(
+    'agentTrust:markTrusted',
+    async (_event, args: { preset: AgentTrustPreset; workspacePath: string }): Promise<void> => {
+      if (!args || typeof args.workspacePath !== 'string' || !args.workspacePath) {
+        return
+      }
+      try {
+        if (args.preset === 'cursor') {
+          markCursorWorkspaceTrusted(args.workspacePath)
+        } else if (args.preset === 'copilot') {
+          markCopilotFolderTrusted(args.workspacePath)
+        }
+      } catch {
+        // Best-effort: see Why above. The user can still accept the trust
+        // prompt manually if writing the artifact fails.
+      }
+    }
+  )
+}
diff --git a/src/main/ipc/browser.ts b/src/main/ipc/browser.ts
index 2aa42699d26..e2424648b98 100644
--- a/src/main/ipc/browser.ts
+++ b/src/main/ipc/browser.ts
@@ -103,6 +103,7 @@ export function registerBrowserHandlers(): void {
         browserPageId: string
         workspaceId: string
         worktreeId: string
+        sessionProfileId?: string | null
         webContentsId: number
       }
     ) => {
diff --git a/src/main/ipc/filesystem-watcher.test.ts b/src/main/ipc/filesystem-watcher.test.ts
new file mode 100644
index 00000000000..d1e3bafdebb
--- /dev/null
+++ b/src/main/ipc/filesystem-watcher.test.ts
@@ -0,0 +1,123 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { handleMock, getSshFilesystemProviderMock } = vi.hoisted(() => ({
+  handleMock: vi.fn(),
+  getSshFilesystemProviderMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: handleMock
+  }
+}))
+
+vi.mock('fs/promises', () => ({
+  stat: vi.fn()
+}))
+
+vi.mock('@parcel/watcher', () => ({
+  subscribe: vi.fn()
+}))
+
+vi.mock('./filesystem-watcher-wsl', () => ({
+  createWslWatcher: vi.fn()
+}))
+
+vi.mock('../providers/ssh-filesystem-dispatch', () => ({
+  getSshFilesystemProvider: getSshFilesystemProviderMock
+}))
+
+import { closeAllWatchers, registerFilesystemWatcherHandlers } from './filesystem-watcher'
+
+type HandlerMap = Record<string, (_event: unknown, args: unknown) => Promise<unknown> | unknown>
+
+describe('registerFilesystemWatcherHandlers', () => {
+  const handlers: HandlerMap = {}
+
+  beforeEach(() => {
+    vi.useRealTimers()
+    handleMock.mockReset()
+    getSshFilesystemProviderMock.mockReset()
+    for (const key of Object.keys(handlers)) {
+      delete handlers[key]
+    }
+    handleMock.mockImplementation((channel, handler) => {
+      handlers[channel] = handler
+    })
+    registerFilesystemWatcherHandlers()
+  })
+
+  it('quietly skips SSH worktree watches while the filesystem provider is unavailable', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    getSshFilesystemProviderMock.mockReturnValue(undefined)
+
+    await expect(
+      handlers['fs:watchWorktree'](
+        { sender: { isDestroyed: () => false, send: vi.fn(), once: vi.fn(), id: 1 } },
+        { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+      )
+    ).resolves.toBeUndefined()
+    await handlers['fs:watchWorktree'](
+      { sender: { isDestroyed: () => false, send: vi.fn(), once: vi.fn(), id: 1 } },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    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' })
+    warnSpy.mockRestore()
+    vi.useRealTimers()
+  })
+
+  it('binds a pending SSH worktree watch after the filesystem provider appears', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const sendMock = vi.fn()
+    const sender = { isDestroyed: () => false, send: sendMock, once: vi.fn(), id: 1 }
+    const unwatchMock = vi.fn()
+    const watchMock = vi.fn().mockResolvedValue(unwatchMock)
+    getSshFilesystemProviderMock.mockReturnValueOnce(undefined)
+
+    await handlers['fs:watchWorktree'](
+      { sender },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
+
+    getSshFilesystemProviderMock.mockReturnValue({ watch: watchMock })
+    await vi.advanceTimersByTimeAsync(1_000)
+
+    expect(watchMock).toHaveBeenCalledWith('/home/me/repo', expect.any(Function))
+    const onEvents = watchMock.mock.calls[0][1]
+    onEvents([{ path: '/home/me/repo/file.txt', type: 'update' }])
+    expect(sendMock).toHaveBeenCalledWith('fs:changed', {
+      worktreePath: '/home/me/repo',
+      events: [{ path: '/home/me/repo/file.txt', type: 'update' }]
+    })
+    warnSpy.mockRestore()
+    handlers['fs:unwatchWorktree'](null, { worktreePath: '/home/me/repo', connectionId: 'conn-1' })
+    vi.useRealTimers()
+  })
+
+  it('cancels pending SSH watch retries during watcher shutdown', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const watchMock = vi.fn()
+    getSshFilesystemProviderMock.mockReturnValueOnce(undefined)
+
+    await handlers['fs:watchWorktree'](
+      { sender: { isDestroyed: () => false, send: vi.fn(), once: vi.fn(), id: 1 } },
+      { worktreePath: '/home/me/repo', connectionId: 'conn-1' }
+    )
+
+    await closeAllWatchers()
+    getSshFilesystemProviderMock.mockReturnValue({ watch: watchMock })
+    await vi.advanceTimersByTimeAsync(1_000)
+
+    expect(watchMock).not.toHaveBeenCalled()
+    warnSpy.mockRestore()
+    vi.useRealTimers()
+  })
+})
diff --git a/src/main/ipc/filesystem-watcher.ts b/src/main/ipc/filesystem-watcher.ts
index c3c79b33997..ec40832e730 100644
--- a/src/main/ipc/filesystem-watcher.ts
+++ b/src/main/ipc/filesystem-watcher.ts
@@ -428,6 +428,10 @@ function unsubscribe(worktreePath: string, senderId: number): void {
 // ── Remote watcher state ─────────────────────────────────────────────
 // Key: `${connectionId}:${worktreePath}`, Value: unwatch function
 const remoteWatchers = new Map<string, () => void>()
+const loggedUnavailableRemoteWatchers = new Set<string>()
+const pendingRemoteWatcherRetries = new Map<string, ReturnType<typeof setTimeout>>()
+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)
@@ -441,6 +445,75 @@ function replaceRemoteWatcher(key: string, unwatch: () => void): void {
   remoteWatchers.set(key, unwatch)
 }
 
+async function installRemoteWatcher(
+  sender: WebContents,
+  connectionId: string,
+  worktreePath: string
+): Promise<boolean> {
+  const provider = getSshFilesystemProvider(connectionId)
+  if (!provider || sender.isDestroyed()) {
+    return false
+  }
+
+  const key = `${connectionId}:${worktreePath}`
+  const unwatch = await provider.watch(worktreePath, (events) => {
+    if (!sender.isDestroyed()) {
+      sender.send('fs:changed', {
+        worktreePath,
+        events
+      } satisfies FsChangedPayload)
+    }
+  })
+  replaceRemoteWatcher(key, unwatch)
+  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 true
+}
+
+function scheduleRemoteWatcherRetry(
+  sender: WebContents,
+  connectionId: string,
+  worktreePath: string,
+  startedAt = Date.now()
+): void {
+  const key = `${connectionId}:${worktreePath}`
+  if (pendingRemoteWatcherRetries.has(key)) {
+    return
+  }
+
+  if (Date.now() - startedAt >= REMOTE_WATCH_RETRY_TIMEOUT_MS || sender.isDestroyed()) {
+    pendingRemoteWatcherRetries.delete(key)
+    loggedUnavailableRemoteWatchers.delete(key)
+    return
+  }
+
+  const retryTimer = setTimeout(() => {
+    pendingRemoteWatcherRetries.delete(key)
+    void installRemoteWatcher(sender, connectionId, worktreePath)
+      .then((installed) => {
+        if (!installed) {
+          scheduleRemoteWatcherRetry(sender, connectionId, worktreePath, startedAt)
+        }
+      })
+      .catch(() => {
+        scheduleRemoteWatcherRetry(sender, connectionId, worktreePath, startedAt)
+      })
+  }, REMOTE_WATCH_RETRY_MS)
+  pendingRemoteWatcherRetries.set(key, retryTimer)
+}
+
 // ── Public API ───────────────────────────────────────────────────────
 
 export function registerFilesystemWatcherHandlers(): void {
@@ -448,29 +521,22 @@ export function registerFilesystemWatcherHandlers(): void {
     'fs:watchWorktree',
     async (event, args: { worktreePath: 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}"`)
-        }
         const key = `${args.connectionId}:${args.worktreePath}`
-
-        const unwatch = await provider.watch(args.worktreePath, (events) => {
-          if (!event.sender.isDestroyed()) {
-            event.sender.send('fs:changed', {
-              worktreePath: args.worktreePath,
-              events
-            } satisfies FsChangedPayload)
+        const installed = await installRemoteWatcher(
+          event.sender,
+          args.connectionId,
+          args.worktreePath
+        )
+        if (!installed) {
+          if (!loggedUnavailableRemoteWatchers.has(key)) {
+            loggedUnavailableRemoteWatchers.add(key)
+            console.warn(
+              `[filesystem-watcher] SSH filesystem provider unavailable; retrying watch for ${args.worktreePath} on connection ${args.connectionId}`
+            )
           }
-        })
-        replaceRemoteWatcher(key, unwatch)
-
-        event.sender.once('destroyed', () => {
-          const unwatchFn = remoteWatchers.get(key)
-          if (unwatchFn) {
-            unwatchFn()
-            remoteWatchers.delete(key)
-          }
-        })
+          scheduleRemoteWatcherRetry(event.sender, args.connectionId, args.worktreePath)
+          return
+        }
         return
       }
       await subscribe(args.worktreePath, event.sender)
@@ -482,6 +548,12 @@ export function registerFilesystemWatcherHandlers(): void {
     (_event, args: { worktreePath: string; connectionId?: string }): void => {
       if (args.connectionId) {
         const key = `${args.connectionId}:${args.worktreePath}`
+        const retryTimer = pendingRemoteWatcherRetries.get(key)
+        if (retryTimer) {
+          clearTimeout(retryTimer)
+          pendingRemoteWatcherRetries.delete(key)
+        }
+        loggedUnavailableRemoteWatchers.delete(key)
         const unwatchFn = remoteWatchers.get(key)
         if (unwatchFn) {
           unwatchFn()
@@ -503,6 +575,12 @@ export async function closeAllWatchers(): Promise<void> {
   }
   pendingTeardowns.clear()
 
+  for (const timer of pendingRemoteWatcherRetries.values()) {
+    clearTimeout(timer)
+  }
+  pendingRemoteWatcherRetries.clear()
+  loggedUnavailableRemoteWatchers.clear()
+
   for (const [rootKey, root] of watchedRoots) {
     if (root.batch.timer) {
       clearTimeout(root.batch.timer)
diff --git a/src/main/ipc/github.test.ts b/src/main/ipc/github.test.ts
index 8e09575309c..8a74e3b741c 100644
--- a/src/main/ipc/github.test.ts
+++ b/src/main/ipc/github.test.ts
@@ -93,7 +93,7 @@ describe('registerGitHubHandlers', () => {
       branch: 'feature/test'
     })
 
-    expect(getPRForBranchMock).toHaveBeenCalledWith('/workspace/repo', 'feature/test')
+    expect(getPRForBranchMock).toHaveBeenCalledWith('/workspace/repo', 'feature/test', null)
   })
 
   it('rejects unknown repository paths', async () => {
diff --git a/src/main/ipc/github.ts b/src/main/ipc/github.ts
index 371bf6cd280..8fa182e31c1 100644
--- a/src/main/ipc/github.ts
+++ b/src/main/ipc/github.ts
@@ -15,6 +15,7 @@ import {
   listWorkItems,
   countWorkItems,
   getWorkItem,
+  getWorkItemByOwnerRepo,
   createIssue,
   updateIssue,
   addIssueComment,
@@ -32,8 +33,45 @@ import {
   starOrca
 } from '../github/client'
 import { getWorkItemDetails, getPRFileContents } from '../github/work-item-details'
+import { getRateLimit } from '../github/rate-limit'
+import { diagnoseGhAuth } from '../github/auth-diagnose'
 import type { GitHubPRFile } from '../../shared/types'
 import { dispatchWorkItem, type WorkItemArgs } from './github-work-item-args'
+import {
+  getProjectViewTable,
+  listAccessibleProjects,
+  resolveProjectRef,
+  listProjectViews,
+  getWorkItemDetailsBySlug,
+  updateProjectItemFieldValue,
+  clearProjectItemFieldValue,
+  updateIssueBySlug,
+  updatePullRequestBySlug,
+  addIssueCommentBySlug,
+  updateIssueCommentBySlug,
+  deleteIssueCommentBySlug,
+  listLabelsBySlug,
+  listAssignableUsersBySlug,
+  listIssueTypesBySlug,
+  updateIssueTypeBySlug
+} from '../github/project-view'
+import type {
+  AddIssueCommentBySlugArgs,
+  ClearProjectItemFieldArgs,
+  DeleteIssueCommentBySlugArgs,
+  GetProjectViewTableArgs,
+  ListAssignableUsersBySlugArgs,
+  ListIssueTypesBySlugArgs,
+  ListLabelsBySlugArgs,
+  ListProjectViewsArgs,
+  ProjectWorkItemDetailsBySlugArgs,
+  ResolveProjectRefArgs,
+  UpdateIssueBySlugArgs,
+  UpdateIssueCommentBySlugArgs,
+  UpdateIssueTypeBySlugArgs,
+  UpdateProjectItemFieldArgs,
+  UpdatePullRequestBySlugArgs
+} from '../../shared/github-project-types'
 
 // 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.
@@ -47,22 +85,25 @@ function assertRegisteredRepo(repoPath: string, store: Store): Repo {
 }
 
 export function registerGitHubHandlers(store: Store, stats: StatsCollector): void {
-  ipcMain.handle('gh:prForBranch', async (_event, args: { repoPath: string; branch: string }) => {
-    const repo = assertRegisteredRepo(args.repoPath, store)
-    const pr = await getPRForBranch(repo.path, args.branch)
-    // 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).
-    if (pr && !stats.hasCountedPR(pr.url)) {
-      stats.record({
-        type: 'pr_created',
-        at: Date.now(),
-        repoId: repo.id,
-        meta: { prNumber: pr.number, prUrl: pr.url }
-      })
+  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)
+      // 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).
+      if (pr && !stats.hasCountedPR(pr.url)) {
+        stats.record({
+          type: 'pr_created',
+          at: Date.now(),
+          repoId: repo.id,
+          meta: { prNumber: pr.number, prUrl: pr.url }
+        })
+      }
+      return pr
     }
-    return pr
-  })
+  )
 
   ipcMain.handle('gh:issue', (_event, args: { repoPath: string; number: number }) => {
     const repo = assertRegisteredRepo(args.repoPath, store)
@@ -107,6 +148,25 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
   ipcMain.handle('gh:workItem', (_event, args: WorkItemArgs) =>
     dispatchWorkItem(args, assertRegisteredRepo(args.repoPath, store).path, getWorkItem)
   )
+  ipcMain.handle(
+    'gh:workItemByOwnerRepo',
+    (
+      _event,
+      args: {
+        repoPath: string
+        owner: string
+        repo: string
+        number: number
+        type: 'issue' | 'pr'
+      }
+    ) =>
+      getWorkItemByOwnerRepo(
+        assertRegisteredRepo(args.repoPath, store).path,
+        { owner: args.owner, repo: args.repo },
+        args.number,
+        args.type
+      )
+  )
   ipcMain.handle('gh:workItemDetails', (_event, args: WorkItemArgs) =>
     dispatchWorkItem(args, assertRegisteredRepo(args.repoPath, store).path, getWorkItemDetails)
   )
@@ -338,6 +398,86 @@ export function registerGitHubHandlers(store: Store, stats: StatsCollector): voi
   ipcMain.handle('gh:checkOrcaStarred', () => checkOrcaStarred())
   ipcMain.handle('gh:starOrca', () => starOrca())
 
+  // Why: `rate_limit` is exempt from GitHub's rate-limit accounting, so
+  // polling is cheap. A 30s in-process cache still avoids the gh subprocess
+  // cost on every render — see getRateLimit for the ttl rationale. Force
+  // parameter lets the renderer bust the cache after a known-expensive op
+  // (e.g. post-ProjectPicker discovery) without waiting out the ttl.
+  ipcMain.handle('gh:rateLimit', (_event, args?: { force?: boolean }) =>
+    getRateLimit(args?.force ? { force: true } : undefined)
+  )
+
+  ipcMain.handle('gh:diagnoseAuth', () => diagnoseGhAuth())
+
+  // ── GitHub ProjectV2 view handlers ─────────────────────────────────
+  // Why: registered unconditionally so enabling the experimental flag at
+  // runtime takes effect without a restart. The renderer gates entry points.
+  // Handlers never throw across IPC — every failure mode resolves through the
+  // GitHubProjectViewError envelope.
+
+  ipcMain.handle('gh:listAccessibleProjects', () => listAccessibleProjects())
+
+  ipcMain.handle('gh:resolveProjectRef', (_event, args: ResolveProjectRefArgs) =>
+    resolveProjectRef(args)
+  )
+
+  ipcMain.handle('gh:listProjectViews', (_event, args: ListProjectViewsArgs) =>
+    listProjectViews(args)
+  )
+
+  ipcMain.handle('gh:getProjectViewTable', (_event, args: GetProjectViewTableArgs) =>
+    getProjectViewTable(args)
+  )
+
+  ipcMain.handle(
+    'gh:projectWorkItemDetailsBySlug',
+    (_event, args: ProjectWorkItemDetailsBySlugArgs) => getWorkItemDetailsBySlug(args)
+  )
+
+  ipcMain.handle('gh:updateProjectItemField', (_event, args: UpdateProjectItemFieldArgs) =>
+    updateProjectItemFieldValue(args)
+  )
+
+  ipcMain.handle('gh:clearProjectItemField', (_event, args: ClearProjectItemFieldArgs) =>
+    clearProjectItemFieldValue(args)
+  )
+
+  ipcMain.handle('gh:updateIssueBySlug', (_event, args: UpdateIssueBySlugArgs) =>
+    updateIssueBySlug(args)
+  )
+
+  ipcMain.handle('gh:updatePullRequestBySlug', (_event, args: UpdatePullRequestBySlugArgs) =>
+    updatePullRequestBySlug(args)
+  )
+
+  ipcMain.handle('gh:addIssueCommentBySlug', (_event, args: AddIssueCommentBySlugArgs) =>
+    addIssueCommentBySlug(args)
+  )
+
+  ipcMain.handle('gh:updateIssueCommentBySlug', (_event, args: UpdateIssueCommentBySlugArgs) =>
+    updateIssueCommentBySlug(args)
+  )
+
+  ipcMain.handle('gh:deleteIssueCommentBySlug', (_event, args: DeleteIssueCommentBySlugArgs) =>
+    deleteIssueCommentBySlug(args)
+  )
+
+  ipcMain.handle('gh:listLabelsBySlug', (_event, args: ListLabelsBySlugArgs) =>
+    listLabelsBySlug(args)
+  )
+
+  ipcMain.handle('gh:listAssignableUsersBySlug', (_event, args: ListAssignableUsersBySlugArgs) =>
+    listAssignableUsersBySlug(args)
+  )
+
+  ipcMain.handle('gh:listIssueTypesBySlug', (_event, args: ListIssueTypesBySlugArgs) =>
+    listIssueTypesBySlug(args)
+  )
+
+  ipcMain.handle('gh:updateIssueTypeBySlug', (_event, args: UpdateIssueTypeBySlugArgs) =>
+    updateIssueTypeBySlug(args)
+  )
+
   // Why: issue-source preference writes go through the generic `repos:update`
   // IPC (extended in this PR to accept `issueSourcePreference`). Routing
   // through the same channel keeps a single write path, guarantees the
diff --git a/src/main/ipc/mobile.ts b/src/main/ipc/mobile.ts
index c7ee87d07ee..528749c29b5 100644
--- a/src/main/ipc/mobile.ts
+++ b/src/main/ipc/mobile.ts
@@ -82,6 +82,7 @@ export function registerMobileHandlers(rpcServer: OrcaRuntimeRpcServer): void {
     return {
       available: true as const,
       qrDataUrl,
+      pairingUrl: url,
       endpoint,
       deviceId: device.deviceId
     }
diff --git a/src/main/ipc/notifications.test.ts b/src/main/ipc/notifications.test.ts
index fbe6c508348..2d1e6c39188 100644
--- a/src/main/ipc/notifications.test.ts
+++ b/src/main/ipc/notifications.test.ts
@@ -1,5 +1,8 @@
 /* eslint-disable max-lines */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 const {
   removeHandlerMock,
@@ -62,9 +65,12 @@ import {
 } from './notifications'
 
 describe('registerNotificationHandlers', () => {
+  let tempDir: string
+
   beforeEach(() => {
     vi.useFakeTimers()
     vi.setSystemTime(new Date('2026-03-28T16:00:00Z'))
+    tempDir = mkdtempSync(join(tmpdir(), 'orca-notification-test-'))
     removeHandlerMock.mockReset()
     handleMock.mockReset()
     notificationCtorMock.mockClear()
@@ -77,6 +83,10 @@ describe('registerNotificationHandlers', () => {
     getAllWindowsMock.mockReturnValue([])
   })
 
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true })
+  })
+
   function getDispatchHandler(): (event: unknown, args: unknown) => unknown {
     const call = handleMock.mock.calls.find((c: unknown[]) => c[0] === 'notifications:dispatch')
     if (!call) {
@@ -85,6 +95,24 @@ describe('registerNotificationHandlers', () => {
     return call[1] as (event: unknown, args: unknown) => unknown
   }
 
+  function getLoadSoundHandler(): (event: unknown) => Promise<unknown> {
+    const call = handleMock.mock.calls.find((c: unknown[]) => c[0] === 'notifications:loadSound')
+    if (!call) {
+      throw new Error('notifications:loadSound handler not registered')
+    }
+    return call[1] as (event: unknown) => Promise<unknown>
+  }
+
+  function getResolveSoundPathHandler(): (event: unknown) => unknown {
+    const call = handleMock.mock.calls.find(
+      (c: unknown[]) => c[0] === 'notifications:resolveSoundPath'
+    )
+    if (!call) {
+      throw new Error('notifications:resolveSoundPath handler not registered')
+    }
+    return call[1] as (event: unknown) => unknown
+  }
+
   it('registers the IPC handler', () => {
     registerNotificationHandlers({
       getSettings: () => ({
@@ -171,6 +199,28 @@ describe('registerNotificationHandlers', () => {
     expect(notificationShowMock).toHaveBeenCalledTimes(1)
   })
 
+  it('silences the native notification when a custom sound is configured', () => {
+    registerNotificationHandlers({
+      getSettings: () => ({
+        notifications: {
+          enabled: true,
+          agentTaskComplete: true,
+          terminalBell: true,
+          suppressWhenFocused: true,
+          customSoundPath: '/Users/kaylee/Downloads/Note_block_pling.ogg'
+        }
+      })
+    } as never)
+
+    const handler = getDispatchHandler()
+    expect(handler({}, { source: 'test' })).toEqual({ delivered: true })
+    expect(notificationCtorMock).toHaveBeenCalledWith({
+      title: 'Orca notifications are on',
+      body: 'This is a test notification from Orca.',
+      silent: true
+    })
+  })
+
   it('returns source-disabled when the specific source toggle is off', () => {
     registerNotificationHandlers({
       getSettings: () => ({
@@ -242,6 +292,87 @@ describe('registerNotificationHandlers', () => {
     })
     expect(notificationShowMock).toHaveBeenCalledTimes(1)
   })
+
+  it('loads allowed custom sound files for preload playback', async () => {
+    const soundPath = join(tempDir, 'sound.ogg')
+    writeFileSync(soundPath, Buffer.from([1, 2, 3]))
+    registerNotificationHandlers({
+      getSettings: () => ({
+        notifications: {
+          enabled: true,
+          agentTaskComplete: true,
+          terminalBell: true,
+          suppressWhenFocused: false,
+          customSoundPath: soundPath
+        }
+      })
+    } as never)
+
+    const handler = getLoadSoundHandler()
+    await expect(handler({})).resolves.toMatchObject({
+      ok: true,
+      data: new Uint8Array([1, 2, 3]),
+      mimeType: 'audio/ogg'
+    })
+  })
+
+  it('rejects unsupported custom sound file types', async () => {
+    const soundPath = join(tempDir, 'sound.txt')
+    writeFileSync(soundPath, 'not audio')
+    registerNotificationHandlers({
+      getSettings: () => ({
+        notifications: {
+          enabled: true,
+          agentTaskComplete: true,
+          terminalBell: true,
+          suppressWhenFocused: false,
+          customSoundPath: soundPath
+        }
+      })
+    } as never)
+
+    const handler = getLoadSoundHandler()
+    await expect(handler({})).resolves.toEqual({
+      ok: false,
+      reason: 'unsupported-type'
+    })
+  })
+
+  it('resolves the sound path without reading the file', () => {
+    const soundPath = join(tempDir, 'sound.ogg')
+    writeFileSync(soundPath, Buffer.from([1, 2, 3]))
+    registerNotificationHandlers({
+      getSettings: () => ({
+        notifications: {
+          enabled: true,
+          agentTaskComplete: true,
+          terminalBell: true,
+          suppressWhenFocused: false,
+          customSoundPath: soundPath
+        }
+      })
+    } as never)
+
+    const handler = getResolveSoundPathHandler()
+    expect(handler({})).toEqual({ ok: true, path: soundPath })
+  })
+
+  it('rejects unsupported types from resolveSoundPath without touching the disk', () => {
+    registerNotificationHandlers({
+      getSettings: () => ({
+        notifications: {
+          enabled: true,
+          agentTaskComplete: true,
+          terminalBell: true,
+          suppressWhenFocused: false,
+          customSoundPath: '/some/where/sound.txt'
+        }
+      })
+    } as never)
+
+    const handler = getResolveSoundPathHandler()
+    expect(handler({})).toEqual({ ok: false, reason: 'unsupported-type' })
+  })
 })
 
 describe('triggerStartupNotificationRegistration', () => {
diff --git a/src/main/ipc/notifications.ts b/src/main/ipc/notifications.ts
index c8f2856e5e8..8ec5752eec7 100644
--- a/src/main/ipc/notifications.ts
+++ b/src/main/ipc/notifications.ts
@@ -1,9 +1,24 @@
 import { app, BrowserWindow, Notification, ipcMain, shell } from 'electron'
+import { readFile, stat } from 'node:fs/promises'
+import { extname, isAbsolute, normalize } from 'node:path'
 import type { Store } from '../persistence'
-import type { NotificationDispatchRequest, NotificationDispatchResult } from '../../shared/types'
+import type {
+  NotificationDispatchRequest,
+  NotificationDispatchResult,
+  NotificationSoundDataResult
+} from '../../shared/types'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
 
 const NOTIFICATION_COOLDOWN_MS = 5000
+const MAX_NOTIFICATION_SOUND_BYTES = 10 * 1024 * 1024
+const NOTIFICATION_SOUND_MIME_BY_EXTENSION: ReadonlyMap<string, string> = new Map([
+  ['.ogg', 'audio/ogg'],
+  ['.mp3', 'audio/mpeg'],
+  ['.wav', 'audio/wav'],
+  ['.m4a', 'audio/mp4'],
+  ['.aac', 'audio/aac'],
+  ['.flac', 'audio/flac']
+])
 
 // Why: Electron Notification objects are normal JS objects — if the only
 // reference is a local variable inside the ipcMain handler, the GC can
@@ -90,7 +105,11 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
         }
       }
 
-      const notification = new Notification(buildNotificationOptions(args))
+      const notificationOptions = buildNotificationOptions(args)
+      if (settings.customSoundPath) {
+        notificationOptions.silent = true
+      }
+      const notification = new Notification(notificationOptions)
 
       // Why: prevent GC from collecting the notification (and its click
       // handler) while it's still visible in macOS Notification Center.
@@ -139,6 +158,64 @@ export function registerNotificationHandlers(store: Store, runtime?: OrcaRuntime
       return { delivered: true }
     }
   )
+
+  // Why: the preload caches the decoded blob keyed by path. Returning just
+  // the validated path lets it skip the 10MB IPC round-trip on every dispatch
+  // when the user's selection hasn't changed — terminal-bell bursts can fire
+  // many notifications in seconds.
+  ipcMain.removeHandler('notifications:resolveSoundPath')
+  ipcMain.handle(
+    'notifications:resolveSoundPath',
+    ():
+      | { ok: true; path: string }
+      | { ok: false; reason: 'missing-path' | 'invalid-path' | 'unsupported-type' } => {
+      const pathValue = store.getSettings().notifications.customSoundPath
+      if (!pathValue) {
+        return { ok: false, reason: 'missing-path' }
+      }
+      const normalizedPath = normalize(pathValue)
+      if (!isAbsolute(normalizedPath)) {
+        return { ok: false, reason: 'invalid-path' }
+      }
+      if (!NOTIFICATION_SOUND_MIME_BY_EXTENSION.has(extname(normalizedPath).toLowerCase())) {
+        return { ok: false, reason: 'unsupported-type' }
+      }
+      return { ok: true, path: normalizedPath }
+    }
+  )
+
+  ipcMain.removeHandler('notifications:loadSound')
+  ipcMain.handle('notifications:loadSound', async (): Promise<NotificationSoundDataResult> => {
+    const pathValue = store.getSettings().notifications.customSoundPath
+    if (!pathValue) {
+      return { ok: false, reason: 'missing-path' }
+    }
+
+    const normalizedPath = normalize(pathValue)
+    if (!isAbsolute(normalizedPath)) {
+      return { ok: false, reason: 'invalid-path' }
+    }
+
+    const mimeType = NOTIFICATION_SOUND_MIME_BY_EXTENSION.get(extname(normalizedPath).toLowerCase())
+    if (!mimeType) {
+      return { ok: false, reason: 'unsupported-type' }
+    }
+
+    try {
+      const fileStat = await stat(normalizedPath)
+      if (!fileStat.isFile()) {
+        return { ok: false, reason: 'invalid-path' }
+      }
+      if (fileStat.size > MAX_NOTIFICATION_SOUND_BYTES) {
+        return { ok: false, reason: 'too-large' }
+      }
+
+      const data = await readFile(normalizedPath)
+      return { ok: true, data: new Uint8Array(data), mimeType, path: normalizedPath }
+    } catch {
+      return { ok: false, reason: 'read-failed' }
+    }
+  })
 }
 
 /**
diff --git a/src/main/ipc/pty-management.test.ts b/src/main/ipc/pty-management.test.ts
index 9e4c6c93f5d..c4d5d1c19db 100644
--- a/src/main/ipc/pty-management.test.ts
+++ b/src/main/ipc/pty-management.test.ts
@@ -238,10 +238,10 @@ describe('pty:management IPC handlers', () => {
       expect(result).toEqual({ killedCount: 3, remainingCount: 0 })
       // Each initial session receives exactly one shutdown — no retries.
       expect(current.shutdown).toHaveBeenCalledTimes(2)
-      expect(current.shutdown).toHaveBeenCalledWith('new-1', true)
-      expect(current.shutdown).toHaveBeenCalledWith('new-2', true)
+      expect(current.shutdown).toHaveBeenCalledWith('new-1', { immediate: true })
+      expect(current.shutdown).toHaveBeenCalledWith('new-2', { immediate: true })
       expect(legacy.shutdown).toHaveBeenCalledTimes(1)
-      expect(legacy.shutdown).toHaveBeenCalledWith('old-1', true)
+      expect(legacy.shutdown).toHaveBeenCalledWith('old-1', { immediate: true })
     })
 
     it('reports remainingCount when sessions refuse to die after the poll window', async () => {
@@ -327,8 +327,8 @@ describe('pty:management IPC handlers', () => {
       const handlers = buildHandlerMap()
       const result = await runKillAllWithPolls(handlers['pty:management:killAll'])
 
-      expect(current.shutdown).toHaveBeenCalledWith('a', true)
-      expect(current.shutdown).toHaveBeenCalledWith('b', true)
+      expect(current.shutdown).toHaveBeenCalledWith('a', { immediate: true })
+      expect(current.shutdown).toHaveBeenCalledWith('b', { immediate: true })
       // 'a' rejected and is still alive → counts as remaining; 'b' reaped.
       expect(result).toEqual({ killedCount: 1, remainingCount: 1 })
     })
@@ -348,7 +348,7 @@ describe('pty:management IPC handlers', () => {
       }
 
       expect(result.success).toBe(true)
-      expect(legacy.shutdown).toHaveBeenCalledWith('old-1', true)
+      expect(legacy.shutdown).toHaveBeenCalledWith('old-1', { immediate: true })
       expect(current.shutdown).not.toHaveBeenCalled()
     })
 
diff --git a/src/main/ipc/pty-management.ts b/src/main/ipc/pty-management.ts
index 05d8f4ab109..014aef35d36 100644
--- a/src/main/ipc/pty-management.ts
+++ b/src/main/ipc/pty-management.ts
@@ -107,7 +107,7 @@ export function registerDaemonManagementHandlers(): void {
           // and so a future adapter could honor it. Rejections are swallowed
           // per-session — remainingCount surfaces truly-stuck sessions in
           // the toast.
-          await owner.shutdown(session.sessionId, true).catch(() => {})
+          await owner.shutdown(session.sessionId, { immediate: true }).catch(() => {})
         })
       )
 
@@ -151,7 +151,7 @@ export function registerDaemonManagementHandlers(): void {
         return { success: false }
       }
       try {
-        await owner.shutdown(args.sessionId, true)
+        await owner.shutdown(args.sessionId, { immediate: true })
         return { success: true }
       } catch {
         return { success: false }
diff --git a/src/main/ipc/pty.test.ts b/src/main/ipc/pty.test.ts
index 19e8626ff31..43737c28ff0 100644
--- a/src/main/ipc/pty.test.ts
+++ b/src/main/ipc/pty.test.ts
@@ -21,7 +21,9 @@ const {
   buildAgentHookEnvMock,
   piBuildPtyEnvMock,
   piClearPtyMock,
-  isPwshAvailableMock
+  isPwshAvailableMock,
+  trackMock,
+  classifyErrorMock
 } = vi.hoisted(() => ({
   handleMock: vi.fn(),
   onMock: vi.fn(),
@@ -40,7 +42,9 @@ const {
   openCodeClearPtyMock: vi.fn(),
   buildAgentHookEnvMock: vi.fn(),
   piBuildPtyEnvMock: vi.fn(),
-  piClearPtyMock: vi.fn()
+  piClearPtyMock: vi.fn(),
+  trackMock: vi.fn(),
+  classifyErrorMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -95,6 +99,14 @@ vi.mock('../pi/titlebar-extension-service', () => ({
 vi.mock('../pwsh', () => ({
   isPwshAvailable: isPwshAvailableMock
 }))
+
+vi.mock('../telemetry/client', () => ({
+  track: trackMock
+}))
+
+vi.mock('../telemetry/classify-error', () => ({
+  classifyError: classifyErrorMock
+}))
 import { LocalPtyProvider } from '../providers/local-pty-provider'
 import {
   registerPtyHandlers,
@@ -142,6 +154,8 @@ describe('registerPtyHandlers', () => {
     piBuildPtyEnvMock.mockReset()
     piClearPtyMock.mockReset()
     isPwshAvailableMock.mockReset()
+    trackMock.mockReset()
+    classifyErrorMock.mockReset()
     mainWindow.webContents.on.mockReset()
     mainWindow.webContents.send.mockReset()
 
@@ -812,7 +826,10 @@ describe('registerPtyHandlers', () => {
     )
 
     await handlers.get('pty:kill')!(null, { id: 'remote-pty' })
-    expect(sshShutdown).toHaveBeenCalledWith('remote-pty', true)
+    expect(sshShutdown).toHaveBeenCalledWith('remote-pty', {
+      immediate: true,
+      keepHistory: false
+    })
   })
 
   it('injects ORCA_TERMINAL_HANDLE for non-local PTY providers', async () => {
@@ -1629,4 +1646,86 @@ describe('registerPtyHandlers', () => {
     expect(openCodeClearPtyMock).toHaveBeenCalledWith(spawnResult.id)
     expect(piClearPtyMock).toHaveBeenCalledWith(spawnResult.id)
   })
+
+  describe('agent_started telemetry', () => {
+    // Why: telemetry-plan.md§Agent launch semantics — agent_started must
+    // fire only after provider.spawn resolves. The renderer threads
+    // launch metadata through `pty:spawn`; a missing or malformed
+    // payload must not produce a silently-malformed event.
+    it('emits agent_started after a successful spawn when telemetry is supplied', async () => {
+      handlers.clear()
+      registerPtyHandlers(mainWindow as never)
+      await handlers.get('pty:spawn')!(null, {
+        cols: 80,
+        rows: 24,
+        telemetry: {
+          agent_kind: 'claude-code',
+          launch_source: 'new_workspace_composer',
+          request_kind: 'new'
+        }
+      })
+      expect(trackMock).toHaveBeenCalledWith('agent_started', {
+        agent_kind: 'claude-code',
+        launch_source: 'new_workspace_composer',
+        request_kind: 'new'
+      })
+    })
+
+    it('does not emit agent_started when telemetry is omitted (bare-shell tab)', async () => {
+      handlers.clear()
+      registerPtyHandlers(mainWindow as never)
+      await handlers.get('pty:spawn')!(null, { cols: 80, rows: 24 })
+      expect(trackMock).not.toHaveBeenCalled()
+    })
+
+    it('drops the event when any telemetry field is outside its closed enum', async () => {
+      handlers.clear()
+      registerPtyHandlers(mainWindow as never)
+      await handlers.get('pty:spawn')!(null, {
+        cols: 80,
+        rows: 24,
+        telemetry: {
+          agent_kind: 'claude-code',
+          launch_source: 'not_a_real_surface',
+          request_kind: 'new'
+        }
+      })
+      expect(trackMock).not.toHaveBeenCalledWith('agent_started', expect.anything())
+    })
+
+    it('does not emit agent_started when provider.spawn throws', async () => {
+      // Why: telemetry-plan contract is that agent_started fires only on
+      // confirmed launch. Inject a provider whose spawn throws so we hit
+      // the catch path with no race against the real LocalPtyProvider.
+      setLocalPtyProvider({
+        spawn: vi.fn(async () => {
+          throw new Error('spawn boom')
+        }),
+        write: vi.fn(),
+        resize: vi.fn(),
+        kill: vi.fn(),
+        shutdown: vi.fn(),
+        onData: vi.fn(() => vi.fn()),
+        onExit: vi.fn(() => vi.fn()),
+        listProcesses: vi.fn(async () => []),
+        getForegroundProcess: vi.fn(async () => null)
+      } as never)
+      classifyErrorMock.mockReturnValue({ error_class: 'unknown' })
+      handlers.clear()
+      registerPtyHandlers(mainWindow as never)
+      await expect(
+        handlers.get('pty:spawn')!(null, {
+          cols: 80,
+          rows: 24,
+          command: 'claude',
+          telemetry: {
+            agent_kind: 'claude-code',
+            launch_source: 'new_workspace_composer',
+            request_kind: 'new'
+          }
+        })
+      ).rejects.toThrow(/spawn boom/)
+      expect(trackMock).not.toHaveBeenCalledWith('agent_started', expect.anything())
+    })
+  })
 })
diff --git a/src/main/ipc/pty.ts b/src/main/ipc/pty.ts
index b8962fc823d..d9bdb590cf4 100644
--- a/src/main/ipc/pty.ts
+++ b/src/main/ipc/pty.ts
@@ -8,6 +8,7 @@ import { randomUUID } from 'crypto'
 import { type BrowserWindow, ipcMain, app } from 'electron'
 export { getBashShellReadyRcfileContent } from '../providers/local-pty-shell-ready'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
+import type { Store } from '../persistence'
 import type { GlobalSettings } from '../../shared/types'
 import { openCodeHookService } from '../opencode/hook-service'
 import { agentHookServer } from '../agent-hooks/server'
@@ -25,6 +26,13 @@ import {
 } from '../claude-accounts/live-pty-gate'
 import { applyTerminalAttributionEnv } from '../attribution/terminal-attribution'
 import { registerPty, unregisterPty } from '../memory/pty-registry'
+import { track } from '../telemetry/client'
+import { classifyError } from '../telemetry/classify-error'
+import {
+  agentKindSchema,
+  launchSourceSchema,
+  requestKindSchema
+} from '../../shared/telemetry-events'
 
 // ─── Provider Registry ──────────────────────────────────────────────
 // Routes PTY operations by connectionId. null = local provider.
@@ -70,6 +78,45 @@ export function registerPaneKeyTeardownListener(listener: PaneKeyTeardownListene
   return () => paneKeyTeardownListeners.delete(listener)
 }
 
+// Why: pre-signal handshake — the renderer declares it will own the serializer
+// for a paneKey BEFORE issuing pty:spawn. The cooperation gate at provider.spawn
+// return consults this map to suppress the daemon-snapshot seed when a renderer
+// is taking over. Generation tokens prevent paneKey-reuse races during teardown:
+// a paneKeyTeardownListener cleanup only fires settle when the captured gen
+// still matches, so a remount that pre-signals before the old PTY's teardown
+// runs is preserved. See docs/mobile-prefer-renderer-scrollback.md.
+let pendingSerializerGenSeq = 0
+const pendingByPaneKey = new Map<string, number>()
+// Why: at PTY spawn time we capture the gen that was pending for the spawn's
+// paneKey, so teardown can settle ONLY that gen. Without this, a paneKey
+// remount that replaces the pending entry with a new gen would still get
+// stomped by the old PTY's teardown firing settle on the wrong gen.
+const ptyPendingGenByPtyId = new Map<string, number>()
+// Why: the runtime's hasRendererSerializer probe needs a ptyId-keyed signal.
+// Populated on settlePaneSerializer (renderer has registered for this ptyId)
+// and cleared on PTY teardown.
+const rendererSerializerByPtyId = new Set<string>()
+
+function isValidPaneKey(paneKey: unknown): paneKey is string {
+  return typeof paneKey === 'string' && paneKey.length > 0 && paneKey.length <= 256
+}
+
+function declarePendingPaneSerializer(paneKey: string): number {
+  const gen = ++pendingSerializerGenSeq
+  pendingByPaneKey.set(paneKey, gen)
+  return gen
+}
+
+function settlePendingPaneSerializer(paneKey: string, gen: number): void {
+  if (pendingByPaneKey.get(paneKey) === gen) {
+    pendingByPaneKey.delete(paneKey)
+  }
+}
+
+export function hasPendingRendererSerializerForPaneKey(paneKey: string): boolean {
+  return isValidPaneKey(paneKey) && pendingByPaneKey.has(paneKey)
+}
+
 function getProvider(connectionId: string | null | undefined): IPtyProvider {
   if (!connectionId) {
     return localProvider
@@ -293,6 +340,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)
+  rendererSerializerByPtyId.delete(id)
   // Why: the hook server's per-paneKey caches (lastPrompt / lastTool) would
   // otherwise accumulate entries for dead panes over the process lifetime.
   // Use the spawn-time paneKey mapping since the server has no other way to
@@ -302,6 +350,17 @@ export function clearProviderPtyState(id: string): void {
     agentHookServer.clearPaneState(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
+    // the second mount's hydration loses to the daemon-snapshot seed. See
+    // the generation-token rationale in
+    // docs/mobile-prefer-renderer-scrollback.md.
+    const ownedGen = ptyPendingGenByPtyId.get(id)
+    if (ownedGen !== undefined) {
+      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.
@@ -358,7 +417,8 @@ export function registerPtyHandlers(
   runtime?: OrcaRuntimeService,
   getSelectedCodexHomePath?: () => string | null,
   getSettings?: () => GlobalSettings,
-  prepareClaudeAuth?: () => Promise<ClaudeRuntimeAuthPreparation>
+  prepareClaudeAuth?: () => Promise<ClaudeRuntimeAuthPreparation>,
+  store?: Store
 ): void {
   // Remove any previously registered handlers so we can re-register them
   // (e.g. when macOS re-activates the app and creates a new window).
@@ -368,6 +428,9 @@ export function registerPtyHandlers(
   ipcMain.removeHandler('pty:hasChildProcesses')
   ipcMain.removeHandler('pty:getForegroundProcess')
   ipcMain.removeHandler('pty:getCwd')
+  ipcMain.removeHandler('pty:declarePendingPaneSerializer')
+  ipcMain.removeHandler('pty:settlePaneSerializer')
+  ipcMain.removeHandler('pty:clearPendingPaneSerializer')
   ipcMain.removeAllListeners('pty:write')
   ipcMain.removeAllListeners('pty:ackColdRestore')
 
@@ -492,8 +555,9 @@ export function registerPtyHandlers(
   rebindProviderListeners = bindProviderListeners
 
   function requestSerializedBuffer(
-    ptyId: string
-  ): Promise<{ data: string; cols: number; rows: number } | null> {
+    ptyId: string,
+    opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }
+  ): Promise<{ data: string; cols: number; rows: number; lastTitle?: string } | null> {
     if (mainWindow.isDestroyed()) {
       return Promise.resolve(null)
     }
@@ -514,7 +578,12 @@ export function registerPtyHandlers(
         _event: Electron.IpcMainEvent,
         args: {
           requestId?: string
-          snapshot?: { data?: unknown; cols?: unknown; rows?: unknown } | null
+          snapshot?: {
+            data?: unknown
+            cols?: unknown
+            rows?: unknown
+            lastTitle?: unknown
+          } | null
         }
       ): void => {
         if (args.requestId !== requestId) {
@@ -528,14 +597,30 @@ export function registerPtyHandlers(
           typeof snapshot.cols === 'number' &&
           typeof snapshot.rows === 'number'
         ) {
-          resolve({ data: snapshot.data, cols: snapshot.cols, rows: snapshot.rows })
+          const result: { data: string; cols: number; rows: number; lastTitle?: string } = {
+            data: snapshot.data,
+            cols: snapshot.cols,
+            rows: snapshot.rows
+          }
+          if (typeof snapshot.lastTitle === 'string' && snapshot.lastTitle.length > 0) {
+            result.lastTitle = snapshot.lastTitle
+          }
+          resolve(result)
         } else {
           resolve(null)
         }
       }
 
       ipcMain.on('pty:serializeBuffer:response', onResponse)
-      mainWindow.webContents.send('pty:serializeBuffer:request', { requestId, ptyId })
+      const payload: {
+        requestId: string
+        ptyId: string
+        opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }
+      } = { requestId, ptyId }
+      if (opts) {
+        payload.opts = opts
+      }
+      mainWindow.webContents.send('pty:serializeBuffer:request', payload)
     })
   }
 
@@ -578,7 +663,7 @@ export function registerPtyHandlers(
       // Why: shutdown() is async but the PtyController interface is sync.
       // Swallowing the rejection prevents an unhandled promise rejection crash
       // if the remote SSH session is already gone.
-      void provider.shutdown(ptyId, false).catch(() => {})
+      void provider.shutdown(ptyId, { immediate: false }).catch(() => {})
       clearProviderPtyState(ptyId)
       markClaudePtyExited(ptyId)
       runtime?.onPtyExit(ptyId, -1)
@@ -598,10 +683,18 @@ export function registerPtyHandlers(
       ])
       return providerSessions.flat()
     },
-    serializeBuffer: (ptyId) => {
+    serializeBuffer: (ptyId, opts) => {
       // Why: mobile xterm must start from the desktop xterm's exact screen
       // state and dimensions before live TUI chunks can render correctly.
-      return requestSerializedBuffer(ptyId)
+      return requestSerializedBuffer(ptyId, opts)
+    },
+    hasRendererSerializer: (ptyId) => {
+      // Why: the runtime needs a synchronous probe so it can decide whether to
+      // skip the daemon-snapshot seed (the renderer will hydrate it) or run the
+      // seed (no renderer authoritative for this PTY). A registry write happens
+      // when the renderer calls registerPtySerializer; we check via the same
+      // pendingByPaneKey + ptyId pairing that the cooperation gate uses.
+      return rendererSerializerByPtyId.has(ptyId)
     },
     getSize: (ptyId) => ptySizes.get(ptyId) ?? null,
     resize: (ptyId, cols, rows) => {
@@ -631,6 +724,25 @@ export function registerPtyHandlers(
         worktreeId?: string
         sessionId?: string
         shellOverride?: string
+        // Why: closes the SIGKILL race documented in INVESTIGATION.md by
+        // letting main patch + sync-flush the (worktreeId, tabId, leafId →
+        // ptyId) binding before pty:spawn returns. Only the renderer's
+        // user-typing-Ctrl+T daemon-host path threads these; mobile/runtime
+        // CLI/SSH spawns leave them undefined and the main-side guard
+        // short-circuits.
+        tabId?: string
+        leafId?: string
+        // Why: telemetry-plan.md§Agent launch semantics. The renderer
+        // threads what Orca was *asked* to launch through this field; main
+        // fires `agent_started` only after `provider.spawn` resolves. Loose
+        // typing on the IPC boundary because the main-side schema
+        // validator is the single enforcement point — `track()` will drop
+        // the event if any field is outside its closed enum.
+        telemetry?: {
+          agent_kind?: unknown
+          launch_source?: unknown
+          request_kind?: unknown
+        }
       }
     ) => {
       const provider = getProvider(args.connectionId)
@@ -795,6 +907,30 @@ export function registerPtyHandlers(
         if (isMintedSessionId && effectiveSessionId !== undefined) {
           clearProviderPtyState(effectiveSessionId)
         }
+        // Why: telemetry-plan.md§agent_error — when the renderer threaded
+        // agent_kind through args.telemetry, attribute the error to that agent.
+        // Otherwise fall back to sniffing the command for `claude` (the one
+        // agent the main process can identify on its own via the existing
+        // `isClaudeLaunchCommand` regex used for auth gating). Bare-shell
+        // catches and unknown-agent catches without renderer telemetry remain
+        // unattributed. The event still emits with a classified `error_class`;
+        // raw error messages are dropped at the telemetry validator boundary.
+        const rendererAgentKindParse =
+          args.telemetry?.agent_kind !== undefined
+            ? agentKindSchema.safeParse(args.telemetry.agent_kind)
+            : null
+        const errorAgentKind = rendererAgentKindParse?.success
+          ? rendererAgentKindParse.data
+          : isClaudeLaunch
+            ? ('claude-code' as const)
+            : null
+        if (errorAgentKind) {
+          const classified = classifyError(err)
+          track('agent_error', {
+            agent_kind: errorAgentKind,
+            error_class: classified.error_class
+          })
+        }
         throw err
       }
       ptyOwnership.set(result.id, args.connectionId ?? null)
@@ -802,6 +938,74 @@ export function registerPtyHandlers(
         runtime?.registerPreAllocatedHandleForPty(result.id, preAllocatedHandle)
       }
       ptySizes.set(result.id, { cols: args.cols, rows: args.rows })
+      // Why: closes the SIGKILL-between-spawn-and-persist race (Issue #217).
+      // The renderer's debounced session writer runs in parallel for every
+      // other field; we patch the load-bearing (tab.ptyId, ptyIdsByLeafId)
+      // binding synchronously so a force-quit in the ~450 ms debounce window
+      // can no longer orphan the daemon's history dir. Other spawn callers
+      // (mobile, runtime CLI, SSH) leave tabId/leafId undefined and this
+      // short-circuits — preserves their existing behavior.
+      if (
+        isDaemonHostSpawn &&
+        store &&
+        args.worktreeId !== undefined &&
+        args.tabId !== undefined &&
+        args.leafId !== undefined
+      ) {
+        store.persistPtyBinding({
+          worktreeId: args.worktreeId,
+          tabId: args.tabId,
+          leafId: args.leafId,
+          ptyId: result.id
+        })
+      }
+      // Why: pre-signal cooperation gate — when the renderer has declared it
+      // will own the serializer for this paneKey, suppress the daemon-snapshot
+      // seed so the renderer's hydration path (maybeHydrateHeadlessFromRenderer)
+      // 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 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 (gen !== undefined) {
+          ptyPendingGenByPtyId.set(result.id, gen)
+        }
+      }
+
+      // Why: hydrate the runtime's headless emulator with the adapter's
+      // restore data BEFORE registerPty so any live PTY data that arrives
+      // concurrently lands on top of the seed instead of replacing it. Mobile
+      // subscribers then see the same scrollback the desktop xterm received
+      // via coldRestore/snapshot. Without this, mobile snapshots after a
+      // daemon-restored attach contain only bytes emitted since the relaunch
+      // and the prior agent output silently disappears.
+      //
+      // Skip when the renderer is or will be authoritative for this PTY:
+      // its hydration path will seed the emulator from xterm's live buffer,
+      // which is richer than the daemon snapshot.
+      if (runtime && !rendererPreSignaled && !rendererAlreadyRegistered) {
+        const seedSize =
+          typeof result.snapshotCols === 'number' && typeof result.snapshotRows === 'number'
+            ? { cols: result.snapshotCols, rows: result.snapshotRows }
+            : undefined
+        if (typeof result.snapshot === 'string' && result.snapshot.length > 0) {
+          runtime.seedHeadlessTerminal(result.id, result.snapshot, seedSize)
+        } else if (
+          result.coldRestore &&
+          typeof result.coldRestore.scrollback === 'string' &&
+          result.coldRestore.scrollback.length > 0
+        ) {
+          runtime.seedHeadlessTerminal(result.id, result.coldRestore.scrollback, seedSize)
+        }
+      }
       if (
         typeof args.worktreeId === 'string' &&
         args.worktreeId.length > 0 &&
@@ -862,11 +1066,42 @@ export function registerPtyHandlers(
               : null
         })
       }
+      // Why: telemetry-plan.md§Agent launch semantics — fire `agent_started`
+      // only after `provider.spawn` resolved. The renderer threads
+      // `args.telemetry` through the spawn IPC for every launch we want to
+      // attribute; bare-shell tabs (no agent) leave the field undefined and
+      // do not produce an event. Each field is parsed against its closed
+      // enum here so a malformed renderer payload (or a spoofed IPC) does
+      // not poison the event — `safeParse` failure drops that field, and
+      // if any required field is missing we skip the event entirely. The
+      // main-side `track()` validator re-runs the schema on the full
+      // payload as a second defense-in-depth check.
+      if (args.telemetry) {
+        const agentKindParse = agentKindSchema.safeParse(args.telemetry.agent_kind)
+        const launchSourceParse = launchSourceSchema.safeParse(args.telemetry.launch_source)
+        const requestKindParse = requestKindSchema.safeParse(args.telemetry.request_kind)
+        if (agentKindParse.success && launchSourceParse.success && requestKindParse.success) {
+          track('agent_started', {
+            agent_kind: agentKindParse.data,
+            launch_source: launchSourceParse.data,
+            request_kind: requestKindParse.data
+          })
+        }
+      }
       return result
     }
   )
 
   ipcMain.on('pty:write', (_event, args: { id: string; data: string }) => {
+    // Why: defense-in-depth for the mobile-presence lock. The renderer's
+    // xterm.onData guard already drops desktop keystrokes when mobile is
+    // driving, but a stale view between the main-side state flip and the
+    // IPC arriving in the renderer can let one keystroke slip through.
+    // This server-side check catches it. See
+    // docs/mobile-presence-lock.md.
+    if (runtime?.getDriver(args.id).kind === 'mobile') {
+      return
+    }
     getProviderForPty(args.id).write(args.id, args.data)
   })
 
@@ -883,6 +1118,16 @@ export function registerPtyHandlers(
     if (runtime?.isResizeSuppressed()) {
       return
     }
+    // Why: presence-lock defense-in-depth. While mobile is driving,
+    // desktop-side resizes (auto-fit on window resize, split drag) must
+    // not reach the PTY. The renderer guard checks the driver state too,
+    // but this is the load-bearing layer because the renderer mirror lags
+    // by one IPC hop. Note: BOTH guards apply — isResizeSuppressed handles
+    // the safeFit cascade after take-back; this driver check handles the
+    // ongoing locked state. See docs/mobile-presence-lock.md.
+    if (runtime?.getDriver(args.id).kind === 'mobile') {
+      return
+    }
     ptySizes.set(args.id, { cols: args.cols, rows: args.rows })
     getProviderForPty(args.id).resize(args.id, args.cols, args.rows)
     runtime?.onExternalPtyResize(args.id, args.cols, args.rows)
@@ -904,13 +1149,16 @@ export function registerPtyHandlers(
       .catch(() => {})
   })
 
-  ipcMain.handle('pty:kill', async (_event, args: { id: string }) => {
+  ipcMain.handle('pty:kill', async (_event, args: { id: string; keepHistory?: boolean }) => {
     // Why: try/finally ensures ptyOwnership is cleaned up even if shutdown
     // throws (e.g. SSH connection already gone or daemon session already
     // reaped). Swallowing the error prevents noisy renderer-side rejections
     // when killing orphaned sessions that the daemon has already discarded.
     try {
-      await getProviderForPty(args.id).shutdown(args.id, true)
+      await getProviderForPty(args.id).shutdown(args.id, {
+        immediate: true,
+        keepHistory: args.keepHistory ?? false
+      })
     } catch {
       /* session already dead — cleanup below handles the rest */
     } finally {
@@ -980,6 +1228,51 @@ export function registerPtyHandlers(
       return ''
     }
   })
+
+  // Why: pre-signal handshake handlers. See
+  // docs/mobile-prefer-renderer-scrollback.md and the rationale on
+  // `pendingByPaneKey` above. The IPC contract is: renderer awaits declare
+  // (capturing the returned gen), awaits pty:spawn, then registers its
+  // serializer locally and calls settle (echoing the gen). On spawn rejection
+  // or pane unmount before settle, renderer calls clear with the same gen.
+  ipcMain.handle(
+    'pty:declarePendingPaneSerializer',
+    async (_event, args: { paneKey?: unknown }): Promise<number> => {
+      if (!isValidPaneKey(args.paneKey)) {
+        throw new Error('Invalid paneKey')
+      }
+      return declarePendingPaneSerializer(args.paneKey)
+    }
+  )
+
+  ipcMain.handle(
+    'pty:settlePaneSerializer',
+    async (_event, args: { paneKey?: unknown; gen?: unknown }): Promise<void> => {
+      if (!isValidPaneKey(args.paneKey) || typeof args.gen !== 'number') {
+        return
+      }
+      settlePendingPaneSerializer(args.paneKey, args.gen)
+      // Why: settle means the renderer has registered its serializer locally
+      // for whatever ptyId came back from spawn. The renderer doesn't carry
+      // the ptyId back through this IPC because the cooperation gate ran
+      // pre-spawn; instead we mark the pane as authoritative by paneKey →
+      // ptyId via the existing paneKeyPtyId mapping populated at spawn.
+      const ptyId = paneKeyPtyId.get(args.paneKey)
+      if (ptyId) {
+        rendererSerializerByPtyId.add(ptyId)
+      }
+    }
+  )
+
+  ipcMain.handle(
+    'pty:clearPendingPaneSerializer',
+    async (_event, args: { paneKey?: unknown; gen?: unknown }): Promise<void> => {
+      if (!isValidPaneKey(args.paneKey) || typeof args.gen !== 'number') {
+        return
+      }
+      settlePendingPaneSerializer(args.paneKey, args.gen)
+    }
+  )
 }
 
 /**
diff --git a/src/main/ipc/register-core-handlers.test.ts b/src/main/ipc/register-core-handlers.test.ts
index b1d7cda9b9e..e43f3de60c9 100644
--- a/src/main/ipc/register-core-handlers.test.ts
+++ b/src/main/ipc/register-core-handlers.test.ts
@@ -21,6 +21,7 @@ const {
   registerRuntimeHandlersMock,
   registerCodexAccountHandlersMock,
   registerAgentHookHandlersMock,
+  registerAgentTrustHandlersMock,
   registerClaudeAccountHandlersMock,
   registerClipboardHandlersMock,
   registerUpdaterHandlersMock,
@@ -53,6 +54,7 @@ const {
   registerRuntimeHandlersMock: vi.fn(),
   registerCodexAccountHandlersMock: vi.fn(),
   registerAgentHookHandlersMock: vi.fn(),
+  registerAgentTrustHandlersMock: vi.fn(),
   registerClaudeAccountHandlersMock: vi.fn(),
   registerClipboardHandlersMock: vi.fn(),
   registerUpdaterHandlersMock: vi.fn(),
@@ -158,6 +160,10 @@ vi.mock('./agent-hooks', () => ({
   registerAgentHookHandlers: registerAgentHookHandlersMock
 }))
 
+vi.mock('./agent-trust', () => ({
+  registerAgentTrustHandlers: registerAgentTrustHandlersMock
+}))
+
 vi.mock('./claude-accounts', () => ({
   registerClaudeAccountHandlers: registerClaudeAccountHandlersMock
 }))
@@ -205,6 +211,7 @@ describe('registerCoreHandlers', () => {
     registerRuntimeHandlersMock.mockReset()
     registerCodexAccountHandlersMock.mockReset()
     registerAgentHookHandlersMock.mockReset()
+    registerAgentTrustHandlersMock.mockReset()
     registerClaudeAccountHandlersMock.mockReset()
     registerClipboardHandlersMock.mockReset()
     registerUpdaterHandlersMock.mockReset()
@@ -254,6 +261,7 @@ describe('registerCoreHandlers', () => {
     expect(registerNotificationHandlersMock).toHaveBeenCalledWith(store, runtime)
     expect(registerDeveloperPermissionHandlersMock).toHaveBeenCalled()
     expect(registerSettingsHandlersMock).toHaveBeenCalledWith(store)
+    expect(registerTelemetryHandlersMock).toHaveBeenCalledWith(store)
     expect(registerSessionHandlersMock).toHaveBeenCalledWith(store)
     expect(registerUIHandlersMock).toHaveBeenCalledWith(store)
     expect(registerFilesystemHandlersMock).toHaveBeenCalledWith(store)
diff --git a/src/main/ipc/register-core-handlers.ts b/src/main/ipc/register-core-handlers.ts
index 273a679d4ff..2213476ca7f 100644
--- a/src/main/ipc/register-core-handlers.ts
+++ b/src/main/ipc/register-core-handlers.ts
@@ -29,6 +29,7 @@ import { registerSidekickHandlers } from './sidekick'
 import { registerUIHandlers } from './ui'
 import { registerCodexAccountHandlers } from './codex-accounts'
 import { registerAgentHookHandlers } from './agent-hooks'
+import { registerAgentTrustHandlers } from './agent-trust'
 import { registerClaudeAccountHandlers } from './claude-accounts'
 import { warmSystemFontFamilies } from '../system-fonts'
 import {
@@ -72,6 +73,7 @@ export function registerCoreHandlers(
   registerCodexUsageHandlers(codexUsage)
   registerCodexAccountHandlers(codexAccounts)
   registerAgentHookHandlers()
+  registerAgentTrustHandlers()
   registerClaudeAccountHandlers(claudeAccounts)
   registerRateLimitHandlers(rateLimits)
   registerGitHubHandlers(store, stats)
@@ -83,7 +85,7 @@ export function registerCoreHandlers(
   registerNotificationHandlers(store, runtime)
   registerDeveloperPermissionHandlers()
   registerSettingsHandlers(store)
-  registerTelemetryHandlers()
+  registerTelemetryHandlers(store)
   registerBrowserHandlers()
   // Why: applyPendingCookieImport MUST run before restorePersistedUserAgent
   // because the latter calls session.fromPartition() which initializes
diff --git a/src/main/ipc/repos.ts b/src/main/ipc/repos.ts
index 252ee4748ac..15ac89ad25c 100644
--- a/src/main/ipc/repos.ts
+++ b/src/main/ipc/repos.ts
@@ -29,6 +29,25 @@ import {
 import { getSshGitProvider } from '../providers/ssh-git-dispatch'
 import { getActiveMultiplexer } from './ssh'
 import { normalizeSparseDirectories } from './sparse-checkout-directories'
+import { track } from '../telemetry/client'
+import type { RepoMethod } from '../../shared/telemetry-events'
+
+// Why: `method` answers "which entry point did the user take?", not "what did
+// they add?" — so the IPC the renderer invoked IS the method. We never send
+// the path, URL, or display name. `repos:create` collapses into
+// `folder_picker` because the user's entry was the folder picker, even
+// though main also `git init`s. `drag_drop` is reserved for a future call
+// site; no current renderer surface produces it.
+function emitRepoAdded(method: RepoMethod, alreadyExisted: boolean): void {
+  // Why: re-adding an existing repo (matched by path inside the handler)
+  // is not a new activation event. Suppressing the duplicate keeps the
+  // funnel honest and avoids inflating `repo_added` for users who
+  // re-pick the same folder.
+  if (alreadyExisted) {
+    return
+  }
+  track('repo_added', { method })
+}
 
 // Why: module-scoped so the abort handle survives window re-creation on macOS.
 // registerRepoHandlers is called again when a new BrowserWindow is created,
@@ -74,6 +93,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       // Check if already added
       const existing = store.getRepos().find((r) => r.path === args.path)
       if (existing) {
+        emitRepoAdded('folder_picker', true)
         return { repo: existing }
       }
 
@@ -89,6 +109,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       store.addRepo(repo)
       await rebuildAuthorizedRootsCache(store)
       notifyReposChanged(mainWindow)
+      emitRepoAdded('folder_picker', false)
       return { repo }
     }
   )
@@ -135,6 +156,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
         .getRepos()
         .find((r) => r.connectionId === args.connectionId && r.path === resolvedPath)
       if (existing) {
+        emitRepoAdded('folder_picker', true)
         return { repo: existing }
       }
 
@@ -195,6 +217,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
         mux.notify('session.registerRoot', { rootPath: resolvedPath })
       }
 
+      emitRepoAdded('folder_picker', false)
       return { repo }
     }
   )
@@ -241,6 +264,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       // the race matters even after this one passes.
       const existing = store.getRepos().find((r) => r.path === targetPath)
       if (existing) {
+        emitRepoAdded('folder_picker', true)
         return { repo: existing }
       }
 
@@ -382,6 +406,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       store.addRepo(repo)
       await rebuildAuthorizedRootsCache(store)
       notifyReposChanged(mainWindow)
+      emitRepoAdded('folder_picker', false)
       return { repo }
     }
   )
@@ -406,6 +431,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
             | 'hookSettings'
             | 'worktreeBaseRef'
             | 'kind'
+            | 'symlinkPaths'
             | 'issueSourcePreference'
           >
         >
@@ -427,6 +453,18 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       ) {
         delete updates.issueSourcePreference
       }
+      // Why: `symlinkPaths` is consumed by `createWorktreeSymlinks` which
+      // calls `.trim()` on each entry. A renderer bug or preload-version skew
+      // that persists a non-`string[]` value (e.g. `[42, null]`, a bare
+      // string) would throw inside the worktree-create path with no UI
+      // signal. Strip invalid shapes at the boundary the same way
+      // `issueSourcePreference` is validated above.
+      if ('symlinkPaths' in updates && updates.symlinkPaths !== undefined) {
+        const v = updates.symlinkPaths as unknown
+        if (!Array.isArray(v) || !v.every((e) => typeof e === 'string')) {
+          delete updates.symlinkPaths
+        }
+      }
       const updated = store.updateRepo(args.repoId, updates)
       if (updated) {
         notifyReposChanged(mainWindow)
@@ -608,9 +646,12 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
           const updated = store.updateRepo(existing.id, { kind: 'git' })
           if (updated) {
             notifyReposChanged(mainWindow)
+            // Why: folder→git upgrade is a real new git repo provisioning event.
+            emitRepoAdded('clone_url', false)
             return updated
           }
         }
+        emitRepoAdded('clone_url', true)
         return existing
       }
 
@@ -626,6 +667,7 @@ export function registerRepoHandlers(mainWindow: BrowserWindow, store: Store): v
       store.addRepo(repo)
       await rebuildAuthorizedRootsCache(store)
       notifyReposChanged(mainWindow)
+      emitRepoAdded('clone_url', false)
       return repo
     }
   )
diff --git a/src/main/ipc/runtime.ts b/src/main/ipc/runtime.ts
index 3931869c7bb..c4aef20d31e 100644
--- a/src/main/ipc/runtime.ts
+++ b/src/main/ipc/runtime.ts
@@ -39,14 +39,15 @@ export function registerRuntimeHandlers(runtime: OrcaRuntimeService): void {
   // code path as the mobile toggle button (terminal.setDisplayMode RPC).
   ipcMain.removeHandler('runtime:restoreTerminalFit')
   ipcMain.handle('runtime:restoreTerminalFit', (_event, args: { ptyId: string }) => {
-    const override = runtime.getTerminalFitOverride(args.ptyId)
-    if (!override) {
-      return { restored: false }
-    }
+    // Why: this IPC powers the desktop "Take back" button. Beyond restoring
+    // PTY dims (the original semantic), it now also reclaims the input
+    // floor for the desktop via the driver state machine. The lock banner
+    // unmounts and desktop input/resize are unblocked until the next
+    // mobile interaction takes the floor again. See
+    // docs/mobile-presence-lock.md.
     try {
-      runtime.setMobileDisplayMode(args.ptyId, 'desktop')
-      runtime.applyMobileDisplayMode(args.ptyId)
-      return { restored: true }
+      const reclaimed = runtime.reclaimTerminalForDesktop(args.ptyId)
+      return { restored: reclaimed }
     } catch {
       return { restored: false }
     }
diff --git a/src/main/ipc/settings.ts b/src/main/ipc/settings.ts
index 92aecef4868..30fe923b1d4 100644
--- a/src/main/ipc/settings.ts
+++ b/src/main/ipc/settings.ts
@@ -4,6 +4,13 @@ import type { GlobalSettings, PersistedState } from '../../shared/types'
 import { listSystemFontFamilies } from '../system-fonts'
 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'
+
+// 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
+// check stay O(1) without re-coercing the readonly tuple on every call.
+const SETTINGS_CHANGED_WHITELIST_SET = new Set<string>(SETTINGS_CHANGED_WHITELIST)
 
 // Why: fields that appear in the View > Appearance submenu need the menu
 // rebuilt after any update so the checkbox `checked` state stays in sync
@@ -23,10 +30,43 @@ export function registerSettingsHandlers(store: Store): void {
     if (args.theme) {
       nativeTheme.themeSource = args.theme
     }
+    // Why: capture the pre-update value so we only emit when the value
+    // actually changes. The settings UI sometimes re-saves the same value
+    // (e.g. blur after a no-op edit), and a `settings_changed` event for a
+    // no-op flip would inflate the experimental-feature-adoption signal.
+    const before = store.getSettings()
     const result = store.updateSettings(args)
     if (APPEARANCE_MENU_KEYS.some((key) => key in args)) {
       rebuildAppMenu()
     }
+
+    // Why: telemetry-plan.md§Settings — fire `settings_changed` only for
+    // whitelisted keys, with `value_kind` distinguishing booleans from
+    // string-enum settings. We deliberately do NOT send the raw value for
+    // non-enum settings; the whitelist is currently scoped to experimental
+    // toggles, all of which are booleans, so `value_kind === 'bool'` is
+    // the path the v1 enum has a slot for. If a non-bool whitelisted
+    // setting is ever added, extend the discriminator here at the same
+    // time the schema's `value_kind` enum gains the new value.
+    for (const key of Object.keys(args)) {
+      if (!SETTINGS_CHANGED_WHITELIST_SET.has(key)) {
+        continue
+      }
+      const beforeValue = (before as Record<string, unknown>)[key]
+      const afterValue = (result as Record<string, unknown>)[key]
+      if (beforeValue === afterValue) {
+        continue
+      }
+      if (typeof afterValue !== 'boolean') {
+        // No non-bool whitelist entries today; skip rather than guess.
+        continue
+      }
+      track('settings_changed', {
+        setting_key: key as SettingsChangedKey,
+        value_kind: 'bool'
+      })
+    }
+
     return result
   })
 
diff --git a/src/main/ipc/shell.test.ts b/src/main/ipc/shell.test.ts
new file mode 100644
index 00000000000..cd7ce56d893
--- /dev/null
+++ b/src/main/ipc/shell.test.ts
@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { handleMock, showOpenDialogMock } = vi.hoisted(() => ({
+  handleMock: vi.fn(),
+  showOpenDialogMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: handleMock
+  },
+  shell: {
+    showItemInFolder: vi.fn(),
+    openExternal: vi.fn(),
+    openPath: vi.fn()
+  },
+  dialog: {
+    showOpenDialog: showOpenDialogMock
+  }
+}))
+
+import { registerShellHandlers } from './shell'
+
+describe('registerShellHandlers', () => {
+  beforeEach(() => {
+    handleMock.mockReset()
+    showOpenDialogMock.mockReset()
+  })
+
+  function getHandler(channel: string): (event: unknown, args?: unknown) => Promise<unknown> {
+    registerShellHandlers()
+    const call = handleMock.mock.calls.find((c: unknown[]) => c[0] === channel)
+    if (!call) {
+      throw new Error(`${channel} handler not registered`)
+    }
+    return call[1] as (event: unknown, args?: unknown) => Promise<unknown>
+  }
+
+  it('picks audio files with a constrained native dialog filter', async () => {
+    showOpenDialogMock.mockResolvedValue({
+      canceled: false,
+      filePaths: ['/Users/kaylee/Downloads/Note_block_pling.ogg']
+    })
+
+    const handler = getHandler('shell:pickAudio')
+    await expect(handler({})).resolves.toBe('/Users/kaylee/Downloads/Note_block_pling.ogg')
+    expect(showOpenDialogMock).toHaveBeenCalledWith({
+      properties: ['openFile'],
+      filters: [{ name: 'Audio', extensions: ['ogg', 'mp3', 'wav', 'm4a', 'aac', 'flac'] }]
+    })
+  })
+
+  it('returns null when audio picking is canceled', async () => {
+    showOpenDialogMock.mockResolvedValue({
+      canceled: true,
+      filePaths: []
+    })
+
+    const handler = getHandler('shell:pickAudio')
+    await expect(handler({})).resolves.toBeNull()
+  })
+})
diff --git a/src/main/ipc/shell.ts b/src/main/ipc/shell.ts
index 62fc383ca5c..51dff5ae5b6 100644
--- a/src/main/ipc/shell.ts
+++ b/src/main/ipc/shell.ts
@@ -123,6 +123,17 @@ export function registerShellHandlers(): void {
     return result.filePaths[0]
   })
 
+  ipcMain.handle('shell:pickAudio', async (): Promise<string | null> => {
+    const result = await dialog.showOpenDialog({
+      properties: ['openFile'],
+      filters: [{ name: 'Audio', extensions: ['ogg', 'mp3', 'wav', 'm4a', 'aac', 'flac'] }]
+    })
+    if (result.canceled || result.filePaths.length === 0) {
+      return null
+    }
+    return result.filePaths[0]
+  })
+
   // Why: copying a picked image next to the markdown file lets us insert a
   // relative path (e.g. `![](image.png)`) instead of embedding base64,
   // keeping markdown files small and portable.
diff --git a/src/main/ipc/sidekick.ts b/src/main/ipc/sidekick.ts
index ee8e97b6852..f7de7f10e45 100644
--- a/src/main/ipc/sidekick.ts
+++ b/src/main/ipc/sidekick.ts
@@ -1,7 +1,9 @@
-import { app, BrowserWindow, dialog, ipcMain } from 'electron'
-import { copyFile, mkdir, readFile, rm, stat } from 'node:fs/promises'
+/* eslint-disable max-lines */
+import { app, BrowserWindow, dialog, ipcMain, nativeImage } from 'electron'
+import { copyFile, mkdir, readFile, rename, rm, stat, lstat } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
-import { basename, extname, join, normalize, sep } from 'node:path'
+import { basename, dirname, extname, isAbsolute, join, normalize, resolve, sep } from 'node:path'
+import { z } from 'zod'
 import type { CustomSidekick } from '../../shared/types'
 
 // Why: image-only sidekick uploads. Static + animated variants render natively
@@ -35,36 +37,125 @@ function getSidekicksDir(): string {
 }
 
 const MAX_BYTES = 64 * 1024 * 1024 // 64 MB — generous but bounded so a user can't point at a multi-GB file and OOM the renderer when it builds a Blob URL.
+const MAX_MANIFEST_BYTES = 64 * 1024 // pet.json is tiny by spec; cap to defend against a malicious bundle stuffing megabytes into the manifest.
 
 function isSafeId(id: string): boolean {
-  // UUIDs only; blocks path traversal and unexpected characters.
+  // UUIDs only; blocks path traversal and unexpected characters. Storage ids
+  // are always generated in main (never sourced from the bundle's manifest.id),
+  // so this regex is the canonical gate for any fs path that includes the id.
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)
 }
 
-function resolveSidekickFile(id: string, fileName: string): string | null {
+function resolveSidekickFile(
+  id: string,
+  fileName: string,
+  kind: 'image' | 'bundle'
+): string | null {
   if (!isSafeId(id)) {
     return null
   }
-  // Why: the renderer hands back the persisted fileName (which includes the
-  // original extension so Blob MIME detection works). We still normalize and
-  // prefix-check against the sidekicks dir to defend against any edge case that
-  // slipped the id regex.
   const safeName = basename(fileName)
+  const root = normalize(getSidekicksDir())
+  let filePath: string
+  if (kind === 'bundle') {
+    // Bundle layout: custom/<id>/<fileName>. fileName is just the spritesheet
+    // basename (e.g. "spritesheet.webp"); pet.json is read by main only and
+    // never served to the renderer.
+    filePath = normalize(join(root, id, safeName))
+    const bundleDir = normalize(join(root, id)) + sep
+    if (!filePath.startsWith(bundleDir)) {
+      return null
+    }
+    return filePath
+  }
+  // Legacy image layout: custom/<id>.<ext>. Filename must start with the id
+  // so the prefix check catches any edge case that slipped the regex.
   if (!safeName.startsWith(`${id}.`)) {
     return null
   }
-  const filePath = normalize(join(getSidekicksDir(), safeName))
-  if (!filePath.startsWith(normalize(getSidekicksDir()) + sep)) {
+  filePath = normalize(join(root, safeName))
+  if (!filePath.startsWith(root + sep)) {
     return null
   }
   return filePath
 }
 
+const PetManifestSchema = z
+  .object({
+    id: z.string().min(1).max(128).optional(),
+    displayName: z.string().min(1).max(120).optional(),
+    description: z.string().max(2000).optional(),
+    spritesheetPath: z
+      .string()
+      .min(1)
+      .max(255)
+      // Why: belt-and-suspenders against malicious manifests — downstream
+      // resolve+prefix check still runs as defense in depth.
+      .refine(
+        (p) => !p.includes('\0') && !p.startsWith('/') && !p.startsWith('\\') && !p.includes('..'),
+        'invalid spritesheetPath'
+      ),
+    frame: z
+      .object({
+        width: z.number().int().positive().max(1024),
+        height: z.number().int().positive().max(1024)
+      })
+      .optional(),
+    fps: z.number().positive().max(60).optional(),
+    defaultAnimation: z.string().min(1).max(64).optional(),
+    animations: z
+      .record(
+        z.string().min(1).max(64),
+        z.object({
+          row: z.number().int().min(0).max(256),
+          frames: z.number().int().positive().max(512)
+        })
+      )
+      .optional()
+  })
+  // Why: tolerate unknown top-level fields. Pet-bundle generators may emit
+  // descriptive metadata (e.g. "kind": "person") we don't consume yet, and
+  // strict mode would reject those imports with a confusing "unrecognized
+  // key" error instead of just ignoring the extras.
+  .loose()
+
+type PetManifest = z.infer<typeof PetManifestSchema>
+
+// Why: renderer-supplied IPC inputs are untrusted — validate shape before any
+// path resolution. resolveSidekickFile still gates the actual filesystem path.
+const SidekickFileRequestSchema = z.object({
+  id: z.string(),
+  fileName: z.string(),
+  kind: z.enum(['image', 'bundle']).optional()
+})
+
+async function readSheetDimensions(
+  buffer: Buffer
+): Promise<{ width: number; height: number } | null> {
+  // Why: nativeImage decodes PNG/JPEG/GIF/WebP/BMP. SVG isn't supported here
+  // (vector → no integer pixel grid), so pet bundles must use a raster sheet.
+  const image = nativeImage.createFromBuffer(buffer)
+  if (image.isEmpty()) {
+    return null
+  }
+  const size = image.getSize()
+  if (size.width <= 0 || size.height <= 0) {
+    return null
+  }
+  return { width: size.width, height: size.height }
+}
+
+async function isSymlink(path: string): Promise<boolean> {
+  try {
+    const s = await lstat(path)
+    return s.isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
 export function registerSidekickHandlers(): void {
   ipcMain.handle('sidekick:import', async (event): Promise<CustomSidekick | null> => {
-    // Why: parent the file picker to the sender window so the dialog opens as
-    // a sheet attached to the main window. Without a parent, on macOS the
-    // dialog can land behind the main window.
     const senderWindow =
       BrowserWindow.fromWebContents(event.sender) ?? BrowserWindow.getFocusedWindow()
     const options: Electron.OpenDialogOptions = {
@@ -129,14 +220,215 @@ export function registerSidekickHandlers(): void {
       id,
       label,
       fileName,
-      mimeType: classified.mimeType
+      mimeType: classified.mimeType,
+      kind: 'image'
+    }
+  })
+
+  ipcMain.handle('sidekick:importPetBundle', async (event): Promise<CustomSidekick | null> => {
+    const senderWindow =
+      BrowserWindow.fromWebContents(event.sender) ?? BrowserWindow.getFocusedWindow()
+    // Why: the bundle is a folder. macOS users may also pick `pet.json` itself
+    // when Finder is set to show package contents — the post-pick logic walks
+    // up to the parent directory in that case.
+    const options: Electron.OpenDialogOptions = {
+      title: 'Pick a .codex-pet bundle',
+      properties: ['openFile', 'openDirectory', 'treatPackageAsDirectory']
+    }
+    const result = senderWindow
+      ? await dialog.showOpenDialog(senderWindow, options)
+      : await dialog.showOpenDialog(options)
+    if (result.canceled || result.filePaths.length === 0) {
+      return null
+    }
+    const picked = result.filePaths[0]
+    let bundleDir: string
+    try {
+      const pickedStat = await stat(picked)
+      bundleDir = pickedStat.isDirectory() ? picked : dirname(picked)
+    } catch {
+      throw new Error('Could not read the selected path.')
+    }
+
+    const manifestPath = join(bundleDir, 'pet.json')
+    let manifestStat: Awaited<ReturnType<typeof stat>>
+    try {
+      manifestStat = await stat(manifestPath)
+    } catch {
+      throw new Error('Bundle is missing pet.json.')
+    }
+    if (!manifestStat.isFile() || manifestStat.size > MAX_MANIFEST_BYTES) {
+      throw new Error('pet.json is invalid.')
+    }
+    if (await isSymlink(manifestPath)) {
+      throw new Error('pet.json must not be a symlink.')
+    }
+
+    let manifest: PetManifest
+    try {
+      const raw = await readFile(manifestPath, 'utf8')
+      // Why: defend against TOCTOU between stat and read — the file could have
+      // grown after the stat check.
+      if (Buffer.byteLength(raw, 'utf8') > MAX_MANIFEST_BYTES) {
+        throw new Error('pet.json exceeded the manifest size limit.')
+      }
+      manifest = PetManifestSchema.parse(JSON.parse(raw))
+    } catch (error) {
+      throw new Error(`Invalid pet.json: ${error instanceof Error ? error.message : 'parse error'}`)
+    }
+
+    // Why: spritesheetPath is bundle-relative. Reject absolute paths and any
+    // resolved path that escapes the bundle directory. Also reject symlinks so
+    // a malicious bundle can't reach outside via a sibling link.
+    if (isAbsolute(manifest.spritesheetPath)) {
+      throw new Error('spritesheetPath must be relative to the bundle.')
+    }
+    const sheetSrc = resolve(bundleDir, manifest.spritesheetPath)
+    const bundleResolved = resolve(bundleDir)
+    if (sheetSrc === bundleResolved) {
+      throw new Error('spritesheetPath must point to a file, not the bundle root.')
+    }
+    const bundleRoot = bundleResolved + sep
+    // Why: NTFS/macOS HFS+ default volumes are case-insensitive — a path like
+    // `BUNDLE\sheet.png` is still inside `bundle\`. Compare lowercased on
+    // Windows so the prefix check isn't bypassed by case differences.
+    const cmp = process.platform === 'win32' ? (s: string) => s.toLowerCase() : (s: string) => s
+    if (!cmp(sheetSrc + sep).startsWith(cmp(bundleRoot))) {
+      throw new Error('spritesheetPath escapes the bundle.')
+    }
+    if (await isSymlink(sheetSrc)) {
+      throw new Error('spritesheet must not be a symlink.')
+    }
+    const sheetClass = classifyFile(sheetSrc)
+    if (!sheetClass || sheetClass.ext === '.svg') {
+      // SVG can't be used as a sprite sheet (no pixel grid).
+      throw new Error('Spritesheet must be a PNG, APNG, JPG, GIF, or WebP.')
+    }
+    let sheetStat: Awaited<ReturnType<typeof stat>>
+    try {
+      sheetStat = await stat(sheetSrc)
+    } catch {
+      throw new Error('Spritesheet file not found.')
+    }
+    if (!sheetStat.isFile()) {
+      throw new Error('Spritesheet path is not a file.')
+    }
+    if (sheetStat.size > MAX_BYTES) {
+      throw new Error(
+        `Spritesheet is too large (${(sheetStat.size / (1024 * 1024)).toFixed(1)} MB).`
+      )
+    }
+
+    let sprite: NonNullable<CustomSidekick['sprite']> | undefined
+    if (manifest.frame) {
+      // Why: only decode the sheet when we need to validate frame layout.
+      // nativeImage may fail on some WebP variants in headless contexts, and
+      // bundles without `frame` render as a static image where dimensions
+      // don't matter.
+      const sheetBuf = await readFile(sheetSrc)
+      // Why: defend against TOCTOU — file may have grown between stat and read.
+      if (sheetBuf.byteLength > MAX_BYTES) {
+        throw new Error('Spritesheet exceeded the size limit.')
+      }
+      const dims = await readSheetDimensions(sheetBuf)
+      if (!dims) {
+        throw new Error('Could not decode the spritesheet image.')
+      }
+      const { width: fw, height: fh } = manifest.frame
+      if (dims.width % fw !== 0 || dims.height % fh !== 0) {
+        throw new Error(
+          `Spritesheet ${dims.width}×${dims.height} is not a clean multiple of frame ${fw}×${fh}.`
+        )
+      }
+      const columns = dims.width / fw
+      const rows = dims.height / fh
+      if (manifest.animations) {
+        for (const [name, anim] of Object.entries(manifest.animations)) {
+          if (anim.row >= rows) {
+            throw new Error(`Animation "${name}" references row ${anim.row} but sheet has ${rows}.`)
+          }
+          if (anim.frames > columns) {
+            throw new Error(
+              `Animation "${name}" has ${anim.frames} frames but sheet only has ${columns} columns.`
+            )
+          }
+        }
+        if (manifest.defaultAnimation && !manifest.animations[manifest.defaultAnimation]) {
+          throw new Error(`defaultAnimation "${manifest.defaultAnimation}" not in animations.`)
+        }
+      }
+      sprite = {
+        frameWidth: fw,
+        frameHeight: fh,
+        columns,
+        rows,
+        sheetWidth: dims.width,
+        sheetHeight: dims.height,
+        fps: manifest.fps ?? 8,
+        defaultAnimation: manifest.defaultAnimation,
+        animations: manifest.animations
+      }
+    }
+
+    // Why: storage id is always a fresh UUID — the manifest's `id` is purely
+    // a display hint. This guards against (a) collisions with bundled
+    // sidekick ids, (b) failing isSafeId, and (c) re-import clobbering an
+    // earlier copy of the same bundle.
+    const id = randomUUID()
+    const root = getSidekicksDir()
+    await mkdir(root, { recursive: true })
+    const destDir = join(root, id)
+    const sheetExt = sheetClass.ext
+    const sheetFileName = `spritesheet${sheetExt}`
+    // Why: stage the bundle into a sibling .tmp directory and atomically rename
+    // into place so destDir only appears once both files are written. Avoids
+    // half-imported bundles if a copy fails midway.
+    const tmpDir = `${destDir}.tmp`
+    try {
+      await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
+      await mkdir(tmpDir, { recursive: true })
+      await copyFile(sheetSrc, join(tmpDir, sheetFileName))
+      await copyFile(manifestPath, join(tmpDir, 'pet.json'))
+      await rename(tmpDir, destDir)
+    } catch {
+      await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
+      throw new Error('Could not save the pet bundle.')
+    }
+
+    const rawLabel = (manifest.displayName ?? manifest.id ?? basename(bundleDir)).trim()
+    const label = rawLabel.length > 0 ? rawLabel.slice(0, 40) : 'Pet bundle'
+    return {
+      id,
+      label,
+      fileName: sheetFileName,
+      mimeType: sheetClass.mimeType,
+      kind: 'bundle',
+      sprite,
+      // Why: carries manifest.fps for detected-frame bundles where `sprite`
+      // is undefined — renderer falls back to this when sprite is absent.
+      ...(manifest.fps !== undefined ? { spriteFps: manifest.fps } : {})
     }
   })
 
   ipcMain.handle(
     'sidekick:read',
-    async (_event, id: string, fileName: string): Promise<ArrayBuffer | null> => {
-      const filePath = resolveSidekickFile(id, fileName)
+    async (
+      _event,
+      id: string,
+      fileName: string,
+      kind?: 'image' | 'bundle'
+    ): Promise<ArrayBuffer | null> => {
+      // Why: validate IPC inputs before any path logic — renderer is not
+      // trusted to send strings of the right shape.
+      let parsed: z.infer<typeof SidekickFileRequestSchema>
+      try {
+        parsed = SidekickFileRequestSchema.parse({ id, fileName, kind })
+      } catch {
+        throw new Error('Invalid sidekick:read arguments')
+      }
+      // Why: missing kind defaults to 'image' for backwards compatibility with
+      // pre-bundle persisted state.
+      const filePath = resolveSidekickFile(parsed.id, parsed.fileName, parsed.kind ?? 'image')
       if (!filePath) {
         return null
       }
@@ -150,15 +442,44 @@ export function registerSidekickHandlers(): void {
     }
   )
 
-  ipcMain.handle('sidekick:delete', async (_event, id: string, fileName: string): Promise<void> => {
-    const filePath = resolveSidekickFile(id, fileName)
-    if (!filePath) {
-      return
+  ipcMain.handle(
+    'sidekick:delete',
+    async (_event, id: string, fileName: string, kind?: 'image' | 'bundle'): Promise<void> => {
+      // Why: validate IPC inputs before any path logic.
+      let parsed: z.infer<typeof SidekickFileRequestSchema>
+      try {
+        parsed = SidekickFileRequestSchema.parse({ id, fileName, kind })
+      } catch {
+        throw new Error('Invalid sidekick:delete arguments')
+      }
+      if (!isSafeId(parsed.id)) {
+        return
+      }
+      if ((parsed.kind ?? 'image') === 'bundle') {
+        // Why: bundle imports own a whole directory. isSafeId already gates id;
+        // we still build the path under the sidekicks root and verify the
+        // prefix before recursive removal as defense in depth.
+        const root = normalize(getSidekicksDir())
+        const target = normalize(join(root, parsed.id))
+        if (!target.startsWith(root + sep)) {
+          return
+        }
+        try {
+          await rm(target, { recursive: true, force: true })
+        } catch (error) {
+          console.warn('[sidekick-overlay] sidekick:delete (bundle) failed', error)
+        }
+        return
+      }
+      const filePath = resolveSidekickFile(parsed.id, parsed.fileName, 'image')
+      if (!filePath) {
+        return
+      }
+      try {
+        await rm(filePath, { force: true })
+      } catch (error) {
+        console.warn('[sidekick-overlay] sidekick:delete failed', error)
+      }
     }
-    try {
-      await rm(filePath, { force: true })
-    } catch (error) {
-      console.warn('[sidekick-overlay] sidekick:delete failed', error)
-    }
-  })
+  )
 }
diff --git a/src/main/ipc/ssh.ts b/src/main/ipc/ssh.ts
index 91bba2f0487..edb556697b1 100644
--- a/src/main/ipc/ssh.ts
+++ b/src/main/ipc/ssh.ts
@@ -162,6 +162,7 @@ export function registerSshHandlers(
     'ssh:connect',
     'ssh:disconnect',
     'ssh:getState',
+    'ssh:needsPassphrasePrompt',
     'ssh:testConnection',
     'ssh:addPortForward',
     'ssh:updatePortForward',
@@ -424,6 +425,21 @@ export function registerSshHandlers(
     return connectionManager!.getState(args.targetId)
   })
 
+  // Why: callers that want to auto-connect (Cmd+J jump, terminal reattach) need
+  // to know whether doing so will pop a passphrase/password dialog. Auto-firing
+  // the connect is fine when no prompt is needed, but surprising otherwise —
+  // the user expects to enter the credential before the app starts connecting.
+  // Returns true if the target's last successful connect required a credential
+  // AND the live SshConnection (if any) does not already have one cached.
+  ipcMain.handle('ssh:needsPassphrasePrompt', (_event, args: { targetId: string }) => {
+    const target = sshStore!.getTarget(args.targetId)
+    if (!target?.lastRequiredPassphrase) {
+      return false
+    }
+    const conn = connectionManager!.getConnection(args.targetId)
+    return !conn?.hasCachedCredential()
+  })
+
   ipcMain.handle('ssh:testConnection', async (_event, args: { targetId: string }) => {
     const target = sshStore!.getTarget(args.targetId)
     if (!target) {
diff --git a/src/main/ipc/telemetry.test.ts b/src/main/ipc/telemetry.test.ts
index 151889d4fdb..9e1b9231cc5 100644
--- a/src/main/ipc/telemetry.test.ts
+++ b/src/main/ipc/telemetry.test.ts
@@ -1,28 +1,41 @@
-// IPC boundary behavior. Strict type narrows must drop obviously-malformed
-// calls before they reach the validator (the renderer is in the threat
-// model). Also pins the consent-mutation rate limit: ≤5
-// `telemetry:setOptIn` calls per session.
+// IPC boundary behavior for the telemetry surface. Strict type narrows must
+// drop obviously-malformed calls before they reach the validator (the
+// renderer is in the threat model). Pins the consent-mutation rate limit:
+// ≤5 consent-related IPC calls per session. Pins the main-side `via`
+// derivation: both `OptInVia` branches are reachable from renderer input,
+// and the one path that must NOT emit (`acknowledgeBanner`) has its own
+// channel and handler rather than being a flag on `setOptIn`.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { GlobalSettings } from '../../shared/types'
+import type { Store } from '../persistence'
 
 const handlers = new Map<string, (_event: unknown, ...args: unknown[]) => unknown>()
-const { handleMock, trackMock, setOptInMock, consumeConsentMutationTokenMock } = vi.hoisted(() => ({
+const {
+  handleMock,
+  trackMock,
+  setOptInMock,
+  persistBannerAcknowledgeMock,
+  consumeConsentMutationTokenMock
+} = vi.hoisted(() => ({
   handleMock: vi.fn(),
   trackMock: vi.fn(),
   setOptInMock: vi.fn(),
+  persistBannerAcknowledgeMock: vi.fn(),
   consumeConsentMutationTokenMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({ ipcMain: { handle: handleMock } }))
 vi.mock('../telemetry/client', () => ({
   track: trackMock,
-  setOptIn: setOptInMock
+  setOptIn: setOptInMock,
+  persistBannerAcknowledgeWithoutEmitting: persistBannerAcknowledgeMock
 }))
 vi.mock('../telemetry/burst-cap', () => ({
   consumeConsentMutationToken: consumeConsentMutationTokenMock
 }))
 
-import { registerTelemetryHandlers } from './telemetry'
+import { _resetStoreForTests, registerTelemetryHandlers } from './telemetry'
 
 function captureHandlers(): void {
   handlers.clear()
@@ -35,28 +48,62 @@ function captureHandlers(): void {
   }
 }
 
+// Build a fake Store with a settable `telemetry` block. Tests reassign
+// `settings.telemetry` between handler invocations to seed the two
+// derivation states.
+type FakeStoreState = { settings: GlobalSettings }
+function makeFakeStore(telemetry: GlobalSettings['telemetry']): {
+  store: Store
+  state: FakeStoreState
+} {
+  const state: FakeStoreState = { settings: { telemetry } as unknown as GlobalSettings }
+  const store = {
+    getSettings: vi.fn(() => state.settings),
+    updateSettings: vi.fn((updates: Partial<GlobalSettings>) => {
+      state.settings = { ...state.settings, ...updates } as GlobalSettings
+      return state.settings
+    })
+  } as unknown as Store
+  return { store, state }
+}
+
+function registerWith(telemetry: GlobalSettings['telemetry']): FakeStoreState {
+  const { store, state } = makeFakeStore(telemetry)
+  registerTelemetryHandlers(store)
+  captureHandlers()
+  return state
+}
+
 describe('telemetry IPC handlers', () => {
   beforeEach(() => {
     handleMock.mockReset()
     trackMock.mockReset()
     setOptInMock.mockReset()
+    persistBannerAcknowledgeMock.mockReset()
     consumeConsentMutationTokenMock.mockReset()
     consumeConsentMutationTokenMock.mockReturnValue(true)
-    registerTelemetryHandlers()
-    captureHandlers()
+    _resetStoreForTests()
   })
   afterEach(() => {
     vi.restoreAllMocks()
   })
 
-  it('registers both channels', () => {
+  it('registers all four channels', () => {
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: false,
+      optedIn: true
+    })
     expect(handlers.has('telemetry:track')).toBe(true)
     expect(handlers.has('telemetry:setOptIn')).toBe(true)
+    expect(handlers.has('telemetry:acknowledgeBanner')).toBe(true)
+    expect(handlers.has('telemetry:getConsentState')).toBe(true)
   })
 
   // ── telemetry:track ──────────────────────────────────────────────────
 
   it('forwards a well-typed track call to track()', () => {
+    registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     const handler = handlers.get('telemetry:track')!
     handler({}, 'app_opened', {})
     expect(trackMock).toHaveBeenCalledTimes(1)
@@ -64,6 +111,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   it('drops track calls with a non-string name', () => {
+    registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     const handler = handlers.get('telemetry:track')!
     handler({}, 42, {})
     handler({}, null, {})
@@ -72,6 +120,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   it('drops track calls with non-object props', () => {
+    registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     const handler = handlers.get('telemetry:track')!
     handler({}, 'app_opened', 'string-not-object')
     handler({}, 'app_opened', 42)
@@ -79,6 +128,7 @@ describe('telemetry IPC handlers', () => {
   })
 
   it('treats null/undefined props as an empty object', () => {
+    registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     const handler = handlers.get('telemetry:track')!
     handler({}, 'app_opened', null)
     handler({}, 'app_opened', undefined)
@@ -87,9 +137,10 @@ describe('telemetry IPC handlers', () => {
     expect(trackMock).toHaveBeenNthCalledWith(2, 'app_opened', {})
   })
 
-  // ── telemetry:setOptIn ───────────────────────────────────────────────
+  // ── telemetry:setOptIn — input narrowing ─────────────────────────────
 
   it('drops setOptIn with non-boolean optedIn', () => {
+    registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     const handler = handlers.get('telemetry:setOptIn')!
     handler({}, 'true')
     handler({}, 1)
@@ -100,19 +151,176 @@ describe('telemetry IPC handlers', () => {
     expect(consumeConsentMutationTokenMock).not.toHaveBeenCalled()
   })
 
-  it('forwards a boolean setOptIn to setOptIn(settings, optedIn) when the token is available', () => {
-    const handler = handlers.get('telemetry:setOptIn')!
-    consumeConsentMutationTokenMock.mockReturnValue(true)
-    handler({}, true)
-    expect(setOptInMock).toHaveBeenCalledWith('settings', true)
-    handler({}, false)
-    expect(setOptInMock).toHaveBeenCalledWith('settings', false)
-  })
-
   it('drops setOptIn past the consent-mutation rate limit', () => {
+    registerWith({ installId: 'x', existedBeforeTelemetryRelease: false, optedIn: true })
     const handler = handlers.get('telemetry:setOptIn')!
     consumeConsentMutationTokenMock.mockReturnValue(false)
     handler({}, true)
     expect(setOptInMock).not.toHaveBeenCalled()
   })
+
+  // ── telemetry:setOptIn — `via` derivation ────────────────────────────
+
+  it("derives via='first_launch_banner' for an existing user with optedIn=null clicking Turn off", () => {
+    // Existing-user notice is the only path where an existing user (cohort
+    // marker true) with optedIn=null flips to false. That is the contract
+    // the notice's "Turn off" button routes through.
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: true,
+      optedIn: null
+    })
+    const handler = handlers.get('telemetry:setOptIn')!
+    handler({}, false)
+    expect(setOptInMock).toHaveBeenCalledWith('first_launch_banner', false)
+  })
+
+  it("derives via='settings' (not 'first_launch_banner') for a defensive opt-in call from the pre-notice state", () => {
+    // Defensive: the notice's opt-in path is the ✕ (silent acknowledge),
+    // which does NOT route through setOptIn. A compromised renderer
+    // could try to call telemetrySetOptIn(true) in the pre-notice state
+    // and synthesize a spurious telemetry_opted_in { via:
+    // 'first_launch_banner' }. The derivation must refuse that tag for
+    // the true-incoming case and fall through to 'settings'.
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: true,
+      optedIn: null
+    })
+    const handler = handlers.get('telemetry:setOptIn')!
+    handler({}, true)
+    expect(setOptInMock).toHaveBeenCalledWith('settings', true)
+  })
+
+  it("derives via='settings' for a new user toggling off from Settings (no first-launch surface exists)", () => {
+    // New users (existedBeforeTelemetryRelease=false) are initialized with
+    // optedIn=true at migration and see no first-launch surface. Any
+    // opt-out from this cohort routes through Settings → Privacy and
+    // must tag as `via: 'settings'`.
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: false,
+      optedIn: true
+    })
+    const handler = handlers.get('telemetry:setOptIn')!
+    handler({}, false)
+    expect(setOptInMock).toHaveBeenCalledWith('settings', false)
+  })
+
+  it("derives via='settings' for an opt-in toggle flip after a prior opt-out", () => {
+    // User flipped off in Settings, flipping back on in Settings. Neither
+    // cohort marker nor notice state triggers a first-launch tag.
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: true,
+      optedIn: false
+    })
+    const handler = handlers.get('telemetry:setOptIn')!
+    handler({}, true)
+    expect(setOptInMock).toHaveBeenCalledWith('settings', true)
+  })
+
+  it("derives via='settings' for a new user flipping Settings off→on (not a first-launch interaction)", () => {
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: false,
+      optedIn: false
+    })
+    const handler = handlers.get('telemetry:setOptIn')!
+    handler({}, true)
+    expect(setOptInMock).toHaveBeenCalledWith('settings', true)
+  })
+
+  it("derives via='settings' when the telemetry block is missing (defensive)", () => {
+    // Should never happen post-migration, but if it does the handler must
+    // fall through to 'settings' rather than throwing or mis-tagging.
+    registerWith(undefined)
+    const handler = handlers.get('telemetry:setOptIn')!
+    handler({}, true)
+    expect(setOptInMock).toHaveBeenCalledWith('settings', true)
+  })
+
+  // ── telemetry:acknowledgeBanner — silent-persist path ────────────────
+
+  it('routes banner ✕ through persistBannerAcknowledgeWithoutEmitting without invoking setOptIn', () => {
+    // This is the whole point of the separate channel: the silent-persist
+    // path MUST NOT reach setOptIn, which would derive a `via` and fire
+    // `telemetry_opted_in`. The client primitive may unlock `app_opened`,
+    // but the acknowledge channel itself must not emit an opt-in event.
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: true,
+      optedIn: null
+    })
+    const handler = handlers.get('telemetry:acknowledgeBanner')!
+    handler({})
+    expect(persistBannerAcknowledgeMock).toHaveBeenCalledTimes(1)
+    expect(setOptInMock).not.toHaveBeenCalled()
+    expect(trackMock).not.toHaveBeenCalled()
+  })
+
+  it('acknowledgeBanner consumes a consent-mutation token and drops past the cap', () => {
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: true,
+      optedIn: null
+    })
+    const handler = handlers.get('telemetry:acknowledgeBanner')!
+    consumeConsentMutationTokenMock.mockReturnValue(false)
+    handler({})
+    expect(persistBannerAcknowledgeMock).not.toHaveBeenCalled()
+  })
+
+  // ── telemetry:acknowledgeBanner — state-precondition guard ───────────
+  // These tests pin the guard, which rejects any cohort/optedIn
+  // combination other than (existed=true, optedIn=null). The guard is
+  // the defense against a compromised renderer silently flipping
+  // optedIn=true for a user who already resolved consent — a future
+  // refactor that weakens it must fail here. The guard also runs BEFORE
+  // consumeConsentMutationToken, so a rejected call must not burn a
+  // token either.
+
+  it('acknowledgeBanner rejects an existing user who already opted in', () => {
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: true,
+      optedIn: true
+    })
+    const handler = handlers.get('telemetry:acknowledgeBanner')!
+    handler({})
+    expect(persistBannerAcknowledgeMock).not.toHaveBeenCalled()
+    expect(consumeConsentMutationTokenMock).not.toHaveBeenCalled()
+  })
+
+  it('acknowledgeBanner rejects an existing user who already opted out', () => {
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: true,
+      optedIn: false
+    })
+    const handler = handlers.get('telemetry:acknowledgeBanner')!
+    handler({})
+    expect(persistBannerAcknowledgeMock).not.toHaveBeenCalled()
+    expect(consumeConsentMutationTokenMock).not.toHaveBeenCalled()
+  })
+
+  it('acknowledgeBanner rejects the new-user cohort regardless of optedIn', () => {
+    registerWith({
+      installId: 'x',
+      existedBeforeTelemetryRelease: false,
+      optedIn: true
+    })
+    const handler = handlers.get('telemetry:acknowledgeBanner')!
+    handler({})
+    expect(persistBannerAcknowledgeMock).not.toHaveBeenCalled()
+    expect(consumeConsentMutationTokenMock).not.toHaveBeenCalled()
+  })
+
+  it('acknowledgeBanner rejects a missing telemetry block', () => {
+    registerWith(undefined)
+    const handler = handlers.get('telemetry:acknowledgeBanner')!
+    handler({})
+    expect(persistBannerAcknowledgeMock).not.toHaveBeenCalled()
+    expect(consumeConsentMutationTokenMock).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/main/ipc/telemetry.ts b/src/main/ipc/telemetry.ts
index 2d263c04211..1bfddc07d41 100644
--- a/src/main/ipc/telemetry.ts
+++ b/src/main/ipc/telemetry.ts
@@ -1,14 +1,17 @@
-// IPC surface for the telemetry transport. Two handlers, both renderer-
-// facing: one pipe (`telemetry:track`) and one consent-mutation
-// (`telemetry:setOptIn`). Every track call from the renderer lands here,
-// and from here funnels into the same `track()` the main-originated events
-// go through — the validator is the single enforcement point, not this
-// file.
+// IPC surface for the telemetry transport. Four handlers, all renderer-
+// facing: one pipe (`telemetry:track`), one consent-mutation
+// (`telemetry:setOptIn`), one silent-persist for the banner ✕ path
+// (`telemetry:acknowledgeBanner`), and one read-only getter for effective
+// consent state (`telemetry:getConsentState`, used by the Privacy pane to
+// render env-var blocked-state helper text). Every track call from the
+// renderer lands here and funnels into the same `track()` the main-
+// originated events go through — the validator is the single enforcement
+// point, not this file.
 //
 // Threat model: the renderer renders attacker-controllable content (agent
 // output, MCP responses, file contents, markdown, diff views). An
 // XSS-equivalent rendering bug in any of those surfaces gives an attacker
-// the ability to invoke `window.api.telemetry*` at will. Both handlers
+// the ability to invoke `window.api.telemetry*` at will. The handlers
 // below are designed to fail closed under that model:
 //
 //   - Strict main-side type narrows. TypeScript types do not survive IPC
@@ -18,13 +21,84 @@
 //   - Consent-mutation rate limit. A real user flips the Privacy pane
 //     toggle a handful of times at most; beyond 5 per session it is either
 //     a UI bug or a compromised renderer. Drop silently past the cap.
+//     Applies to `acknowledgeBanner` as well — that path also mutates
+//     persisted consent, so it lives under the same per-session ceiling.
+//
+// `via` derivation: the renderer does NOT pass `via` across the wire. That
+// design was rejected specifically because a compromised renderer could
+// misreport `via`, muddying the one signal we use to distinguish
+// first-launch interactions from settings flips. Main derives `via` from
+// fields main already owns (`existedBeforeTelemetryRelease`, current
+// `optedIn`) before any state mutation. The two product paths map cleanly
+// to the two schema values (`first_launch_banner` for the existing-user
+// notice's "Turn off" button; `settings` for everything else — new users
+// have no first-launch surface, so their opt-outs always come through
+// Settings).
 
 import { ipcMain } from 'electron'
 import { consumeConsentMutationToken } from '../telemetry/burst-cap'
-import { setOptIn, track } from '../telemetry/client'
+import { persistBannerAcknowledgeWithoutEmitting, setOptIn, track } from '../telemetry/client'
+import { resolveConsent, type ConsentState } from '../telemetry/consent'
+import type { Store } from '../persistence'
 import type { EventName, EventProps } from '../../shared/telemetry-events'
+import type { OptInVia } from '../../shared/telemetry-events'
+
+// Module-level store reference, populated by `registerTelemetryHandlers`.
+// The handlers need a synchronous read of `settings.telemetry` at call time
+// to derive `via` before any mutation runs — threading the store through
+// every handler closure is the least-surprising shape for that, and it
+// mirrors how other core-handlers accept the store explicitly.
+let storeRef: Store | null = null
+
+/**
+ * Derive the `via` discriminator for a `telemetry:setOptIn` call from
+ * main-owned state. Called BEFORE any state mutation so the cohort + opt-in
+ * snapshot reflects the pre-click world.
+ *
+ * Two cases (mirrors the product surfaces defined in telemetry-plan.md):
+ *   - existing-user notice "Turn off" → `'first_launch_banner'`
+ *     (existedBeforeTelemetryRelease=true, optedIn=null, incoming false)
+ *   - any other flip → `'settings'`
+ *     (Privacy pane, post-first-launch mutations, etc.)
+ *
+ * New users never reach a `'first_launch_banner'` tag — their cohort marker
+ * is false and they see no first-launch surface at all (see telemetry-plan.md
+ * §First-launch experience). Any consent flip they make routes through
+ * Settings → Privacy and tags as `'settings'`.
+ *
+ * Note: the notice's ✕ (silent acknowledge) path does NOT come through this
+ * function — it routes through `telemetry:acknowledgeBanner` and
+ * `persistBannerAcknowledgeWithoutEmitting`, which intentionally does not
+ * emit. Derivation here would tag it as `'first_launch_banner'` and emit
+ * `telemetry_opted_in`, which the ✕-as-silent-acknowledge semantics
+ * forbid.
+ */
+function deriveOptInVia(store: Store, incomingOptedIn: boolean): OptInVia {
+  const telemetry = store.getSettings().telemetry
+  const existedBefore = telemetry?.existedBeforeTelemetryRelease === true
+  const currentOptedIn = telemetry?.optedIn
+
+  // Existing-user cohort, notice still pending. The only surface that calls
+  // `setOptIn` in this state is the FirstLaunchBanner's "Turn off" click;
+  // the ✕ path does not route here (it goes through
+  // `telemetry:acknowledgeBanner`). We additionally narrow on
+  // `incomingOptedIn === false` as a defensive guard: a compromised
+  // renderer could otherwise call `telemetrySetOptIn(true)` in this
+  // pre-notice state and synthesize a spurious
+  // `telemetry_opted_in { via: 'first_launch_banner' }`, which the
+  // ✕-as-silent-acknowledge contract forbids. Falling through to
+  // 'settings' for the true case keeps the forbidden tag unreachable
+  // from IPC.
+  if (existedBefore && currentOptedIn === null && incomingOptedIn === false) {
+    return 'first_launch_banner'
+  }
+
+  return 'settings'
+}
+
+export function registerTelemetryHandlers(store: Store): void {
+  storeRef = store
 
-export function registerTelemetryHandlers(): void {
   ipcMain.handle('telemetry:track', (_event, name: unknown, props: unknown): void => {
     // Strict input typing: non-string names are dropped at the boundary
     // before the validator even sees them. The validator would also drop
@@ -48,17 +122,94 @@ export function registerTelemetryHandlers(): void {
     track(name as EventName, (props ?? {}) as EventProps<EventName>)
   })
 
-  ipcMain.handle('telemetry:setOptIn', (_event, optedIn: unknown): void => {
+  ipcMain.handle('telemetry:setOptIn', (_event, optedIn: unknown): Promise<void> | void => {
     // Strict input typing — renderer can pass anything over IPC.
     if (typeof optedIn !== 'boolean') {
       return
     }
+    // Check storeRef BEFORE consuming a consent-mutation token. If the store
+    // isn't ready (pre-registration race, test harness misuse, a future
+    // refactor), consuming a token here would burn budget for a no-op and
+    // eventually block legitimate mutations from the same session.
+    if (!storeRef) {
+      return
+    }
     // Consent-mutation bucket: ≤5 per session. See `burst-cap.ts`. Does not
     // apply to main-originated consent mutations that bypass IPC (none
     // today; this is future-proofing rather than a current code path).
     if (!consumeConsentMutationToken()) {
       return
     }
-    setOptIn('settings', optedIn)
+    // Read settings BEFORE any state mutation. The derivation must see the
+    // pre-mutation world so an existing user clicking "Turn off" on the
+    // notice still presents as (optedIn=null → false) at the moment `via`
+    // is computed, not (optedIn=false → false) after the write lands.
+    const via = deriveOptInVia(storeRef, optedIn)
+    return setOptIn(via, optedIn)
+  })
+
+  // Read-only view of the effective consent state. The Privacy pane needs
+  // this to render the correct helper text when an env var
+  // (DO_NOT_TRACK / ORCA_TELEMETRY_DISABLED / CI) blocks transmission —
+  // those variables are main-side process state and the renderer has no
+  // way to read them directly. No rate limit: this is a synchronous getter
+  // with no mutation, bounded in work by one `resolveConsent` call.
+  ipcMain.handle('telemetry:getConsentState', (): ConsentState => {
+    if (!storeRef) {
+      // Fail closed — a missing store means we cannot honor the user's
+      // stored preference, so surface pending_banner rather than a
+      // misleading 'enabled'. The renderer treats pending_banner like a
+      // disabled state in the UI.
+      return { effective: 'pending_banner' }
+    }
+    return resolveConsent(storeRef.getSettings())
+  })
+
+  ipcMain.handle('telemetry:acknowledgeBanner', (_event): Promise<void> | void => {
+    // Banner ✕ — persist `optedIn = true` without emitting a telemetry opt-in
+    // event. The acknowledge still unlocks `app_opened`, but this outcome
+    // cannot route through `telemetry:setOptIn` because the derivation above
+    // would tag it `first_launch_banner` and fire `telemetry_opted_in`.
+    //
+    // Check storeRef BEFORE consuming a consent-mutation token, mirroring
+    // the setOptIn handler's guard above — see that comment for why
+    // burning a token on a no-op blocks legitimate mutations later in
+    // the same session.
+    if (!storeRef) {
+      return
+    }
+    // State-precondition guard: this channel is ONLY valid when the notice
+    // is pending resolution — i.e. existing-user cohort
+    // (existedBeforeTelemetryRelease=true) with optedIn still null. Any
+    // other state is either a UI bug (the notice should not be reachable
+    // post-resolution) or a compromised renderer trying to silently flip
+    // optedIn=true after the user already opted out, which would bypass
+    // the audit signal entirely. `deriveOptInVia` already applies the
+    // symmetric guard on `telemetry:setOptIn` (it refuses to tag a true
+    // flip as `first_launch_banner`); this narrows the silent-persist
+    // attack surface on the acknowledge channel to exactly the state the
+    // notice contract covers. Must run BEFORE the token consume — same
+    // "don't burn a token on a no-op" reasoning as the !storeRef guard
+    // above.
+    const telemetry = storeRef.getSettings().telemetry
+    if (telemetry?.existedBeforeTelemetryRelease !== true || telemetry?.optedIn !== null) {
+      return
+    }
+    // This path still goes through `consumeConsentMutationToken` — a
+    // compromised renderer could otherwise burn through the
+    // acknowledgeBanner channel to force unbounded settings-file writes,
+    // which is a CPU/disk amplification vector even without any event
+    // emission.
+    if (!consumeConsentMutationToken()) {
+      return
+    }
+    return persistBannerAcknowledgeWithoutEmitting()
   })
 }
+
+// Test-only reset for the module-level store reference. Tests can
+// re-register handlers against a fresh mock store without leaking state
+// between describes.
+export function _resetStoreForTests(): void {
+  storeRef = null
+}
diff --git a/src/main/ipc/worktree-logic.ts b/src/main/ipc/worktree-logic.ts
index f4fc0e292b8..d6472413bf3 100644
--- a/src/main/ipc/worktree-logic.ts
+++ b/src/main/ipc/worktree-logic.ts
@@ -172,6 +172,7 @@ export function mergeWorktree(
     isPinned: meta?.isPinned ?? false,
     sortOrder: meta?.sortOrder ?? 0,
     lastActivityAt: meta?.lastActivityAt ?? 0,
+    ...(meta?.createdAt !== undefined ? { createdAt: meta.createdAt } : {}),
     ...(git.isSparse === true
       ? {
           sparseDirectories: meta?.sparseDirectories,
diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index 49385ef2f37..416206d2687 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -37,6 +37,7 @@ import {
   areWorktreePathsEqual
 } from './worktree-logic'
 import { invalidateAuthorizedRootsCache } from './filesystem-auth'
+import { createWorktreeSymlinks } from './worktree-symlinks'
 import { normalizeSparseDirectories } from './sparse-checkout-directories'
 
 export function notifyWorktreesChanged(mainWindow: BrowserWindow, repoId: string): void {
@@ -203,8 +204,16 @@ export async function createRemoteWorktree(
   }
 
   const worktreeId = `${repo.id}::${created.path}`
+  const now = Date.now()
   const metaUpdates: Partial<WorktreeMeta> = {
-    lastActivityAt: Date.now(),
+    lastActivityAt: now,
+    // Why: grants the new worktree a short grace window at the top of the
+    // Recent sort. During worktree creation (git fetch + add can take several
+    // seconds) other worktrees get ambient PTY bumps that would otherwise
+    // leave the newly-created one below them; the Recent comparator uses
+    // max(lastActivityAt, createdAt + GRACE_MS) to keep it on top until the
+    // window elapses. See smart-sort.ts `CREATE_GRACE_MS`.
+    createdAt: now,
     ...(shouldSetDisplayName(requestedName, branchName, sanitizedName)
       ? { displayName: requestedName }
       : {})
@@ -212,6 +221,12 @@ export async function createRemoteWorktree(
   const meta = store.setWorktreeMeta(worktreeId, metaUpdates)
   const worktree = mergeWorktree(repo.id, created, meta)
 
+  // Why: `experimentalWorktreeSymlinks` is intentionally not wired up for
+  // remote (SSH) worktrees. Creating symlinks on the remote host would
+  // require a new relay method and authorization surface; the feature is
+  // local-only until that protocol work is in scope. Remote repos with
+  // `symlinkPaths` configured have them silently ignored here.
+
   notifyWorktreesChanged(mainWindow, repo.id)
   return { worktree }
 }
@@ -427,11 +442,15 @@ export async function createLocalWorktree(
   }
 
   const worktreeId = `${repo.id}::${created.path}`
+  const now = Date.now()
   const metaUpdates: Partial<WorktreeMeta> = {
     // Stamp activity so the worktree sorts into its final position
     // immediately — prevents scroll-to-reveal racing with a later
     // bumpWorktreeActivity that would re-sort the list.
-    lastActivityAt: Date.now(),
+    lastActivityAt: now,
+    // See createRemoteWorktree above: createdAt protects the newly-created
+    // worktree from ambient PTY bumps in other worktrees for CREATE_GRACE_MS.
+    createdAt: now,
     ...(shouldSetDisplayName(effectiveRequestedName, branchName, effectiveSanitizedName)
       ? { displayName: effectiveRequestedName }
       : {}),
@@ -452,6 +471,15 @@ export async function createLocalWorktree(
   // adds 100ms+ to every create.
   invalidateAuthorizedRootsCache()
 
+  // Why: create user-configured symlinks from the primary checkout into the
+  // new worktree before any setup script runs, so scripts that reuse shared
+  // state (e.g. `node_modules`, `.env`) see the links already in place.
+  // Gated on the experimental flag so disabling the feature globally skips
+  // the work even when a repo still has paths configured.
+  if (settings.experimentalWorktreeSymlinks && repo.symlinkPaths && repo.symlinkPaths.length > 0) {
+    await createWorktreeSymlinks(repo.path, created.path, repo.symlinkPaths)
+  }
+
   // Why: the worktree's own `orca.yaml` (at the tip of the base branch) is
   // authoritative for what runs post-creation. The repo-level trust already
   // granted by the user in the pre-create flow covers execution of that
diff --git a/src/main/ipc/worktree-symlinks.test.ts b/src/main/ipc/worktree-symlinks.test.ts
new file mode 100644
index 00000000000..155655c159a
--- /dev/null
+++ b/src/main/ipc/worktree-symlinks.test.ts
@@ -0,0 +1,227 @@
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  statSync,
+  lstatSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+  existsSync
+} from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createWorktreeSymlinks, removeWorktreeSymlinks } from './worktree-symlinks'
+
+describe('createWorktreeSymlinks', () => {
+  let root: string
+  let primary: string
+  let worktree: string
+  let warn: ReturnType<typeof vi.spyOn>
+  let error: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'orca-symlinks-'))
+    primary = join(root, 'primary')
+    worktree = join(root, 'worktree')
+    mkdirSync(primary, { recursive: true })
+    mkdirSync(worktree, { recursive: true })
+    warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    error = vi.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    warn.mockRestore()
+    error.mockRestore()
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  it('symlinks a file from primary into the worktree at the same relative path', async () => {
+    writeFileSync(join(primary, '.env'), 'SECRET=1\n')
+    await createWorktreeSymlinks(primary, worktree, ['.env'])
+
+    const linkStat = lstatSync(join(worktree, '.env'))
+    expect(linkStat.isSymbolicLink()).toBe(true)
+    expect(readlinkSync(join(worktree, '.env'))).toBe(join(primary, '.env'))
+    // Following the link yields the primary's contents.
+    expect(statSync(join(worktree, '.env')).isFile()).toBe(true)
+  })
+
+  it('symlinks a directory from primary into the worktree', async () => {
+    mkdirSync(join(primary, 'node_modules'))
+    writeFileSync(join(primary, 'node_modules', 'marker'), 'installed')
+    await createWorktreeSymlinks(primary, worktree, ['node_modules'])
+
+    expect(lstatSync(join(worktree, 'node_modules')).isSymbolicLink()).toBe(true)
+    expect(statSync(join(worktree, 'node_modules', 'marker')).isFile()).toBe(true)
+  })
+
+  it('creates parent directories lazily for nested paths', async () => {
+    mkdirSync(join(primary, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(primary, 'apps', 'web', '.env'), 'X=1\n')
+    await createWorktreeSymlinks(primary, worktree, ['apps/web/.env'])
+
+    expect(lstatSync(join(worktree, 'apps', 'web', '.env')).isSymbolicLink()).toBe(true)
+  })
+
+  it('skips entries whose source is missing in the primary checkout', async () => {
+    await createWorktreeSymlinks(primary, worktree, ['node_modules'])
+    // No link created, no throw.
+    expect(() => lstatSync(join(worktree, 'node_modules'))).toThrow()
+    expect(error).not.toHaveBeenCalled()
+  })
+
+  it('preserves a pre-existing target in the worktree (no clobber)', async () => {
+    writeFileSync(join(primary, '.env'), 'FROM_PRIMARY=1\n')
+    writeFileSync(join(worktree, '.env'), 'FROM_WORKTREE=1\n')
+
+    await createWorktreeSymlinks(primary, worktree, ['.env'])
+
+    // The pre-existing regular file stays; no symlink was created.
+    expect(lstatSync(join(worktree, '.env')).isSymbolicLink()).toBe(false)
+    expect(statSync(join(worktree, '.env')).isFile()).toBe(true)
+  })
+
+  it('does not escape the primary checkout via a leading-slash path', async () => {
+    // Why: the helper strips leading slashes (so `/etc/passwd` becomes the
+    // relative `etc/passwd`). No file is created outside the worktree, and the
+    // resolved source — which falls inside `primary/etc/passwd` — is missing,
+    // so the entry is silently skipped rather than linking to `/etc/passwd`.
+    await createWorktreeSymlinks(primary, worktree, ['/etc/passwd'])
+
+    expect(() => lstatSync(join(worktree, 'etc', 'passwd'))).toThrow()
+    expect(error).not.toHaveBeenCalled()
+  })
+
+  it('rejects parent-directory traversal', async () => {
+    await createWorktreeSymlinks(primary, worktree, ['../secrets'])
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('[worktree-symlinks] Skipping unsafe path "../secrets"')
+    )
+  })
+
+  it('rejects nested traversal via ..', async () => {
+    await createWorktreeSymlinks(primary, worktree, ['safe/../../escape'])
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('[worktree-symlinks] Skipping unsafe path "safe/../../escape"')
+    )
+  })
+
+  it('rejects traversal using backslash separators (Windows form)', async () => {
+    // Why: users configuring paths on Windows (or pasting a mixed-separator
+    // value) could bypass a POSIX-only split. The guard normalizes across
+    // `/` and `\` so `..\escape` and `foo\..\..\escape` both get rejected.
+    await createWorktreeSymlinks(primary, worktree, ['..\\escape'])
+    await createWorktreeSymlinks(primary, worktree, ['foo\\..\\..\\escape'])
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('[worktree-symlinks] Skipping unsafe path "..\\escape"')
+    )
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('[worktree-symlinks] Skipping unsafe path "foo\\..\\..\\escape"')
+    )
+  })
+
+  it('strips a leading slash then treats the remainder as a relative path', async () => {
+    writeFileSync(join(primary, '.env'), 'X=1\n')
+    await createWorktreeSymlinks(primary, worktree, ['/.env'])
+
+    // Leading slash is stripped in the helper; the remaining `.env` is a valid relative path.
+    expect(lstatSync(join(worktree, '.env')).isSymbolicLink()).toBe(true)
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('skips empty and whitespace-only entries', async () => {
+    // The helper logs an "unsafe path" warn for these; nothing gets linked.
+    await createWorktreeSymlinks(primary, worktree, ['', '   '])
+    expect(error).not.toHaveBeenCalled()
+  })
+
+  it('continues processing later entries after one fails', async () => {
+    writeFileSync(join(primary, '.env'), 'X=1\n')
+    writeFileSync(join(primary, 'config.json'), '{}')
+
+    await createWorktreeSymlinks(primary, worktree, [
+      '../escape', // rejected
+      'missing-source', // no source, skipped
+      '.env', // succeeds
+      'config.json' // succeeds
+    ])
+
+    expect(lstatSync(join(worktree, '.env')).isSymbolicLink()).toBe(true)
+    expect(lstatSync(join(worktree, 'config.json')).isSymbolicLink()).toBe(true)
+  })
+
+  it('is a no-op for an empty paths list', async () => {
+    await createWorktreeSymlinks(primary, worktree, [])
+    expect(warn).not.toHaveBeenCalled()
+    expect(error).not.toHaveBeenCalled()
+  })
+})
+
+describe('removeWorktreeSymlinks', () => {
+  let root: string
+  let primary: string
+  let worktree: string
+  let error: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'orca-unlink-'))
+    primary = join(root, 'primary')
+    worktree = join(root, 'worktree')
+    mkdirSync(primary, { recursive: true })
+    mkdirSync(worktree, { recursive: true })
+    error = vi.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    error.mockRestore()
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  it('unlinks configured symlinks from the worktree', async () => {
+    writeFileSync(join(primary, '.env'), 'SECRET=1\n')
+    mkdirSync(join(primary, 'node_modules'))
+    symlinkSync(join(primary, '.env'), join(worktree, '.env'), 'file')
+    symlinkSync(join(primary, 'node_modules'), join(worktree, 'node_modules'), 'dir')
+
+    await removeWorktreeSymlinks(worktree, ['.env', 'node_modules'])
+
+    expect(existsSync(join(worktree, '.env'))).toBe(false)
+    expect(existsSync(join(worktree, 'node_modules'))).toBe(false)
+    // Source is untouched.
+    expect(statSync(join(primary, '.env')).isFile()).toBe(true)
+    expect(statSync(join(primary, 'node_modules')).isDirectory()).toBe(true)
+  })
+
+  it('leaves a regular file at the configured path alone', async () => {
+    // Why: a user who created a real file at `.env` (instead of symlinking)
+    // must not lose it just because `.env` is in the configured list.
+    writeFileSync(join(worktree, '.env'), 'USER_WROTE_THIS=1\n')
+
+    await removeWorktreeSymlinks(worktree, ['.env'])
+
+    expect(lstatSync(join(worktree, '.env')).isSymbolicLink()).toBe(false)
+    expect(statSync(join(worktree, '.env')).isFile()).toBe(true)
+  })
+
+  it('ignores missing entries', async () => {
+    await removeWorktreeSymlinks(worktree, ['.env', 'node_modules'])
+    expect(error).not.toHaveBeenCalled()
+  })
+
+  it('rejects unsafe paths without touching the filesystem', async () => {
+    // Parent-dir traversal is silently skipped; no unlink attempted.
+    writeFileSync(join(root, 'outside-file'), 'DO_NOT_DELETE')
+    await removeWorktreeSymlinks(worktree, ['../outside-file'])
+    expect(existsSync(join(root, 'outside-file'))).toBe(true)
+  })
+
+  it('is a no-op for an empty paths list', async () => {
+    await removeWorktreeSymlinks(worktree, [])
+    expect(error).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/ipc/worktree-symlinks.ts b/src/main/ipc/worktree-symlinks.ts
new file mode 100644
index 00000000000..d08ee8d536f
--- /dev/null
+++ b/src/main/ipc/worktree-symlinks.ts
@@ -0,0 +1,111 @@
+import { symlink, mkdir, stat, lstat, unlink } from 'fs/promises'
+import { dirname, isAbsolute, resolve } from 'path'
+
+/** Create filesystem symlinks from the primary checkout into a freshly-created
+ *  worktree for each configured path. Failures on individual paths are logged
+ *  and skipped so a missing/stale entry never blocks worktree creation.
+ *
+ *  Each entry is interpreted relative to `primaryPath` and placed at the same
+ *  relative location inside `worktreePath`. Nested paths (e.g.
+ *  `apps/web/.env`) are supported — parent directories are created lazily. */
+export async function createWorktreeSymlinks(
+  primaryPath: string,
+  worktreePath: string,
+  paths: readonly string[]
+): Promise<void> {
+  for (const rawPath of paths) {
+    // Why: strip leading separators (both `/` and `\`) before the guard so
+    // Windows-style input like `\foo` is normalized the same way POSIX `/foo`
+    // is, and the traversal check below sees the already-relative form.
+    const rel = rawPath.trim().replace(/^[\\/]+/, '')
+    // Why: split on both separators so a Windows-authored `..\escape` is
+    // rejected the same way POSIX `../escape` is. `path.isAbsolute` catches
+    // drive-letter absolutes (`C:\...`); the split catches relative
+    // backslash traversal that `.split('/')` would otherwise miss.
+    if (!rel || isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+      // Users can only configure paths relative to the repo root; absolute
+      // paths and `..` traversal are not supported.
+      console.warn(`[worktree-symlinks] Skipping unsafe path "${rawPath}"`)
+      continue
+    }
+
+    const source = resolve(primaryPath, rel)
+    const target = resolve(worktreePath, rel)
+
+    let sourceIsDirectory = false
+    try {
+      const s = await stat(source)
+      sourceIsDirectory = s.isDirectory()
+    } catch {
+      // Source doesn't exist in primary checkout — nothing to link to. This is
+      // a common case for fresh clones where `node_modules` hasn't been
+      // installed yet; silently skip rather than leaving a dangling symlink.
+      continue
+    }
+
+    try {
+      // Why: if a file/dir already exists at the target location (e.g.
+      // git-tracked sibling with the same name), leave it alone rather than
+      // clobber something the user didn't mean to replace. Use `lstat` so a
+      // pre-existing symlink (including a broken one whose source has moved)
+      // is detected and skipped, rather than falling through to `symlink()`
+      // and failing with EEXIST.
+      await lstat(target)
+      continue
+    } catch {
+      // Target does not exist — proceed with symlink creation.
+    }
+
+    try {
+      await mkdir(dirname(target), { recursive: true })
+      // Why: Windows requires an explicit `type` ('dir' vs 'file' vs
+      // 'junction') for `fs.symlink`. On POSIX the argument is ignored, so
+      // passing it unconditionally is safe and removes a Windows-only
+      // failure mode when Node can't auto-detect from the source.
+      await symlink(source, target, sourceIsDirectory ? 'dir' : 'file')
+    } catch (error) {
+      console.error(
+        `[worktree-symlinks] Failed to symlink "${rel}" (${source} -> ${target}):`,
+        error
+      )
+    }
+  }
+}
+
+/** Remove previously-created symlinks from a worktree before deletion.
+ *
+ *  Why: `git worktree remove` refuses to delete a worktree that has modified
+ *  or untracked files. A symlink pointing at the primary's `node_modules`
+ *  looks "untracked" to git, so users would hit "It has changed files. Use
+ *  Force Delete" on every deletion once they've configured this feature.
+ *  Unlink the known symlinks up front so the non-force path keeps working.
+ *
+ *  Safety: only removes entries that are actually symbolic links. A regular
+ *  file or directory at the same path is left alone — we never want to clobber
+ *  something the user created that happens to share a name with a configured
+ *  entry. Missing entries (ENOENT) are silently ignored. */
+export async function removeWorktreeSymlinks(
+  worktreePath: string,
+  paths: readonly string[]
+): Promise<void> {
+  for (const rawPath of paths) {
+    const rel = rawPath.trim().replace(/^[\\/]+/, '')
+    if (!rel || isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+      continue
+    }
+    const target = resolve(worktreePath, rel)
+    try {
+      const s = await lstat(target)
+      if (!s.isSymbolicLink()) {
+        continue
+      }
+    } catch {
+      continue
+    }
+    try {
+      await unlink(target)
+    } catch (error) {
+      console.error(`[worktree-symlinks] Failed to unlink "${rel}" (${target}):`, error)
+    }
+  }
+}
diff --git a/src/main/ipc/worktrees.test.ts b/src/main/ipc/worktrees.test.ts
index 12547caecde..e2e055f0866 100644
--- a/src/main/ipc/worktrees.test.ts
+++ b/src/main/ipc/worktrees.test.ts
@@ -378,6 +378,136 @@ describe('registerWorktreeHandlers', () => {
     expect(listWorktreesMock).not.toHaveBeenCalled()
   })
 
+  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
+    // newly-added git repo) would otherwise fall back to `lastActivityAt: 0`
+    // and rank dead last in the Recent sort.
+    listWorktreesMock.mockResolvedValue([
+      {
+        path: '/workspace/discovered-wt',
+        head: 'abc123',
+        branch: 'refs/heads/feature',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+    store.getWorktreeMeta.mockReturnValue(undefined)
+    const stampedMeta = { lastActivityAt: 1_700_000_000_000 }
+    store.setWorktreeMeta.mockReturnValue(stampedMeta)
+
+    const listed = (await handlers['worktrees:list'](null, { repoId: 'repo-1' })) as {
+      id: string
+      lastActivityAt: number
+    }[]
+
+    expect(store.setWorktreeMeta).toHaveBeenCalledWith(
+      'repo-1::/workspace/discovered-wt',
+      expect.objectContaining({ lastActivityAt: expect.any(Number) })
+    )
+    expect(listed[0]).toMatchObject({
+      id: 'repo-1::/workspace/discovered-wt',
+      lastActivityAt: 1_700_000_000_000
+    })
+  })
+
+  it('does not re-stamp lastActivityAt when a worktree already has persisted meta', async () => {
+    // Why: only the *first* discovery should stamp. Re-stamping on every list
+    // would overwrite real activity and reshuffle the sidebar on refresh.
+    listWorktreesMock.mockResolvedValue([
+      {
+        path: '/workspace/existing-wt',
+        head: 'abc123',
+        branch: 'refs/heads/feature',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+    store.getWorktreeMeta.mockReturnValue({
+      displayName: '',
+      comment: '',
+      linkedIssue: null,
+      linkedPR: null,
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 42
+    })
+
+    const listed = (await handlers['worktrees:list'](null, { repoId: 'repo-1' })) as {
+      id: string
+      lastActivityAt: number
+    }[]
+
+    expect(store.setWorktreeMeta).not.toHaveBeenCalled()
+    expect(listed[0].lastActivityAt).toBe(42)
+  })
+
+  it('stamps lastActivityAt on first discovery for folder-mode repos', async () => {
+    // Why: folder repos produce a synthetic worktree that flows through the
+    // same list path. Without the stamp, adding a folder puts its card at the
+    // bottom of Recent even though the user just added it.
+    store.getRepos.mockReturnValue([
+      {
+        id: 'repo-1',
+        path: '/workspace/folder',
+        displayName: 'folder',
+        badgeColor: '#000',
+        addedAt: 0,
+        kind: 'folder'
+      }
+    ])
+    store.getRepo.mockReturnValue({
+      id: 'repo-1',
+      path: '/workspace/folder',
+      displayName: 'folder',
+      badgeColor: '#000',
+      addedAt: 0,
+      kind: 'folder'
+    })
+    store.getWorktreeMeta.mockReturnValue(undefined)
+    store.setWorktreeMeta.mockReturnValue({ lastActivityAt: 1_700_000_000_000 })
+
+    await handlers['worktrees:list'](null, { repoId: 'repo-1' })
+
+    expect(store.setWorktreeMeta).toHaveBeenCalledWith(
+      'repo-1::/workspace/folder',
+      expect.objectContaining({ lastActivityAt: expect.any(Number) })
+    )
+  })
+
+  it('stamps lastActivityAt on first discovery via worktrees:listAll', async () => {
+    // Why: the stamping logic lives in both worktrees:list and worktrees:listAll.
+    // Without a dedicated test, a regression in the listAll loop would silently
+    // bury newly-discovered worktrees from the multi-repo sidebar view.
+    listWorktreesMock.mockResolvedValue([
+      {
+        path: '/workspace/discovered-wt',
+        head: 'abc123',
+        branch: 'refs/heads/feature',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+    store.getWorktreeMeta.mockReturnValue(undefined)
+    store.setWorktreeMeta.mockReturnValue({ lastActivityAt: 1_700_000_000_000 })
+
+    const listed = (await handlers['worktrees:listAll'](null, undefined)) as {
+      id: string
+      lastActivityAt: number
+    }[]
+
+    expect(store.setWorktreeMeta).toHaveBeenCalledWith(
+      'repo-1::/workspace/discovered-wt',
+      expect.objectContaining({ lastActivityAt: expect.any(Number) })
+    )
+    expect(listed[0]).toMatchObject({
+      id: 'repo-1::/workspace/discovered-wt',
+      lastActivityAt: 1_700_000_000_000
+    })
+  })
+
   it('skips past a suffix that already belongs to a PR after an initial branch conflict', async () => {
     // Why: `gh pr list` is network-bound and previously fired on every single
     // create, adding 1–3s to the happy path. We now only probe PR conflicts
diff --git a/src/main/ipc/worktrees.ts b/src/main/ipc/worktrees.ts
index 1cf22e79ef7..1d82f5e505e 100644
--- a/src/main/ipc/worktrees.ts
+++ b/src/main/ipc/worktrees.ts
@@ -37,6 +37,38 @@ import { rebuildAuthorizedRootsCache, ensureAuthorizedRootsCache } from './files
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
 import { killAllProcessesForWorktree } from '../runtime/worktree-teardown'
 import { getLocalPtyProvider } from './pty'
+import { removeWorktreeSymlinks } from './worktree-symlinks'
+import { track } from '../telemetry/client'
+import { workspaceSourceSchema, type WorkspaceSource } from '../../shared/telemetry-events'
+
+// Why: worktrees discovered on disk (not created via Orca's UI) have no
+// persisted WorktreeMeta, so mergeWorktree falls back to `lastActivityAt: 0`.
+// That makes them sort to the bottom of "Recent" even though the user just
+// added the repo / folder. Stamp discovery time the first time we see a
+// worktree so its very existence counts as a recency signal. Subsequent
+// list calls find the persisted meta and skip the stamp.
+function resolveWorktreeMetaWithDiscoveryStamp(store: Store, worktreeId: string): WorktreeMeta {
+  const existing = store.getWorktreeMeta(worktreeId)
+  if (existing) {
+    return existing
+  }
+  return store.setWorktreeMeta(worktreeId, { lastActivityAt: Date.now() })
+}
+
+const loggedUnavailableSshGitProviders = new Set<string>()
+const loggedWorktreeListFailures = new Set<string>()
+
+function warnOnce(keySet: Set<string>, key: string, message: string, error?: unknown): void {
+  if (keySet.has(key)) {
+    return
+  }
+  keySet.add(key)
+  if (error) {
+    console.warn(message, error)
+  } else {
+    console.warn(message)
+  }
+}
 
 export function registerWorktreeHandlers(
   mainWindow: BrowserWindow,
@@ -75,18 +107,31 @@ export function registerWorktreeHandlers(
           } else if (repo.connectionId) {
             const provider = getSshGitProvider(repo.connectionId)
             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 []
             }
+            loggedUnavailableSshGitProviders.delete(`${repo.connectionId}:${repo.id}`)
             gitWorktrees = await provider.listWorktrees(repo.path)
           } else {
             gitWorktrees = await listRepoWorktrees(repo)
           }
+          loggedWorktreeListFailures.delete(`${repo.id}:${repo.path}`)
           return gitWorktrees.map((gw) => {
             const worktreeId = `${repo.id}::${gw.path}`
-            const meta = store.getWorktreeMeta(worktreeId)
+            const meta = resolveWorktreeMetaWithDiscoveryStamp(store, worktreeId)
             return mergeWorktree(repo.id, gw, meta, repo.displayName)
           })
-        } catch {
+        } catch (err) {
+          warnOnce(
+            loggedWorktreeListFailures,
+            `${repo.id}:${repo.path}`,
+            `[worktrees] failed to list worktrees for repo "${repo.displayName}" (${repo.id}) at ${repo.path}`,
+            err
+          )
           return []
         }
       })
@@ -105,29 +150,46 @@ export function registerWorktreeHandlers(
       return []
     }
 
-    let gitWorktrees
-    if (isFolderRepo(repo)) {
-      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) {
-        return []
+    try {
+      let gitWorktrees
+      if (isFolderRepo(repo)) {
+        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 []
+        }
+        loggedUnavailableSshGitProviders.delete(`${repo.connectionId}:${repo.id}`)
+        gitWorktrees = await provider.listWorktrees(repo.path)
+      } else {
+        gitWorktrees = await listRepoWorktrees(repo)
       }
-      gitWorktrees = await provider.listWorktrees(repo.path)
-    } else {
-      gitWorktrees = await listRepoWorktrees(repo)
+      loggedWorktreeListFailures.delete(`${repo.id}:${repo.path}`)
+      return gitWorktrees.map((gw) => {
+        const worktreeId = `${repo.id}::${gw.path}`
+        const meta = resolveWorktreeMetaWithDiscoveryStamp(store, worktreeId)
+        return mergeWorktree(repo.id, gw, meta, repo.displayName)
+      })
+    } catch (err) {
+      warnOnce(
+        loggedWorktreeListFailures,
+        `${repo.id}:${repo.path}`,
+        `[worktrees] failed to list worktrees for repo "${repo.displayName}" (${repo.id}) at ${repo.path}`,
+        err
+      )
+      return []
     }
-    return gitWorktrees.map((gw) => {
-      const worktreeId = `${repo.id}::${gw.path}`
-      const meta = store.getWorktreeMeta(worktreeId)
-      return mergeWorktree(repo.id, gw, meta, repo.displayName)
-    })
   })
 
   ipcMain.handle(
@@ -142,11 +204,26 @@ export function registerWorktreeHandlers(
       }
 
       // Remote repos route all git operations through the relay
-      if (repo.connectionId) {
-        return createRemoteWorktree(args, repo, store, mainWindow)
-      }
+      const result = repo.connectionId
+        ? await createRemoteWorktree(args, repo, store, mainWindow)
+        : await createLocalWorktree(args, repo, store, mainWindow, runtime)
 
-      return createLocalWorktree(args, repo, store, mainWindow, runtime)
+      // Why: emit `workspace_created` only after the underlying create has
+      // resolved (the helpers throw on failure, so reaching this line means
+      // git-add succeeded — we deliberately do not also emit a separate
+      // `workspace_initialized`, see telemetry-plan.md§Deferred events).
+      // `from_existing_branch` is true iff the caller specified a non-empty
+      // baseBranch; an unspecified baseBranch means "branch from default
+      // HEAD", which is the not-from-existing-branch case. We never send
+      // the branch name itself.
+      const sourceParse = workspaceSourceSchema.safeParse(args.telemetrySource)
+      const source: WorkspaceSource = sourceParse.success ? sourceParse.data : 'unknown'
+      track('workspace_created', {
+        source,
+        from_existing_branch: typeof args.baseBranch === 'string' && args.baseBranch.length > 0
+      })
+
+      return result
     }
   )
 
@@ -312,6 +389,15 @@ export function registerWorktreeHandlers(
         }
       }
 
+      // Why: `git worktree remove` (non-force) refuses to delete a worktree
+      // that has untracked files, and a symlink pointing into the primary
+      // checkout looks untracked to git. Unlink the user-configured symlinks
+      // 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)
+      }
+
       try {
         await removeWorktree(repo.path, worktreePath, args.force ?? false)
       } catch (error) {
diff --git a/src/main/opencode/hook-service.test.ts b/src/main/opencode/hook-service.test.ts
index b1ed29622b5..21fb9229ab5 100644
--- a/src/main/opencode/hook-service.test.ts
+++ b/src/main/opencode/hook-service.test.ts
@@ -80,6 +80,21 @@ describe('OpenCode hook plugin source', () => {
     expect(source).toContain('cachedEndpointValues = null;')
   })
 
+  it('forwards question.asked as AskUserQuestion so the pane flips to waiting', () => {
+    // Why: OpenCode exposes two separate plugin events for human-in-the-loop
+    // moments — `permission.asked` (blocks on tool approval) and
+    // `question.asked` (the agent called an ask-the-user tool). The plugin
+    // must forward both so the server-side normalizer can map each to
+    // `waiting` and render the red indicator. Dropping `question.asked`
+    // leaves the pane stuck in `working` while the agent is actually idle,
+    // waiting on a human reply — exactly the bug three other OpenCode
+    // integrations (cmux, t3code, open-vibe-island) all handle.
+    const source = _internals.getOpenCodePluginSource()
+
+    expect(source).toContain('if (event.type === "question.asked")')
+    expect(source).toContain('await post("AskUserQuestion", event.properties || {});')
+  })
+
   it('guards endpoint-file parse warnings with a process-lifetime latch', () => {
     // Why: ENOENT is the normal pre-install case and must stay silent, but a
     // malformed/unreadable file (EACCES, EIO, parse error) would otherwise
diff --git a/src/main/opencode/hook-service.ts b/src/main/opencode/hook-service.ts
index 5990fa667ae..b789b2146e4 100644
--- a/src/main/opencode/hook-service.ts
+++ b/src/main/opencode/hook-service.ts
@@ -259,6 +259,18 @@ function getOpenCodePluginSource(): string {
     '      return;',
     '    }',
     '',
+    '    if (event.type === "question.asked") {',
+    '      // Why: question.asked fires when OpenCode uses an ask-the-user tool',
+    '      // (distinct from permission.asked, which blocks on tool approval).',
+    '      // The agent is idle-but-waiting on a human reply, not running, so we',
+    '      // must flip the pane to the same red "needs attention" state used for',
+    '      // permission requests. Like permission.asked, do not touch lastStatus',
+    '      // so the next SessionBusy/SessionIdle after the user answers still',
+    '      // fires and restores the normal working/done flow.',
+    '      await post("AskUserQuestion", event.properties || {});',
+    '      return;',
+    '    }',
+    '',
     '    if (event.type === "message.updated") {',
     '      // Why: role is already cached above the isChildSession await so the',
     '      // back-to-back message.part.updated for the same messageID is not',
diff --git a/src/main/persistence.test.ts b/src/main/persistence.test.ts
index d658bb22835..09a7b43cbf4 100644
--- a/src/main/persistence.test.ts
+++ b/src/main/persistence.test.ts
@@ -72,12 +72,14 @@ describe('Store', () => {
     expect(settings.branchPrefix).toBe('git-username')
     expect(settings.refreshLocalBaseRefOnWorktreeCreate).toBe(false)
     expect(settings.theme).toBe('system')
+    expect(settings.appFontFamily).toBe('Geist')
     expect(settings.editorAutoSave).toBe(false)
     expect(settings.editorAutoSaveDelayMs).toBe(1000)
     expect(settings.terminalFontSize).toBe(14)
     expect(settings.terminalFontWeight).toBe(500)
     expect(settings.rightSidebarOpenByDefault).toBe(true)
     expect(settings.showTasksButton).toBe(true)
+    expect(settings.notifications.customSoundPath).toBeNull()
   })
 
   it('returns default UI state when no data file exists', async () => {
@@ -146,10 +148,36 @@ describe('Store', () => {
     expect(store.getSettings().refreshLocalBaseRefOnWorktreeCreate).toBe(false)
     expect(store.getSettings().rightSidebarOpenByDefault).toBe(true)
     expect(store.getSettings().showTasksButton).toBe(true)
+    expect(store.getSettings().notifications.customSoundPath).toBeNull()
     // repos should be loaded
     expect(store.getRepos()).toHaveLength(1)
   })
 
+  it('preserves custom notification sound paths from persisted settings', async () => {
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [],
+      worktreeMeta: {},
+      settings: {
+        notifications: {
+          customSoundPath: '/Users/kaylee/Downloads/Note_block_pling.ogg'
+        }
+      },
+      ui: {},
+      githubCache: { pr: {}, issue: {} },
+      workspaceSession: {}
+    })
+
+    const store = await createStore()
+    expect(store.getSettings().notifications).toMatchObject({
+      enabled: true,
+      agentTaskComplete: true,
+      terminalBell: false,
+      suppressWhenFocused: true,
+      customSoundPath: '/Users/kaylee/Downloads/Note_block_pling.ogg'
+    })
+  })
+
   it('preserves editorAutoSaveDelayMs when set in persisted data', async () => {
     writeDataFile({
       schemaVersion: 1,
@@ -310,12 +338,14 @@ describe('Store', () => {
       theme: 'dark',
       editorAutoSave: true,
       editorAutoSaveDelayMs: 1500,
+      appFontFamily: 'Inter',
       terminalFontSize: 16,
       terminalFontWeight: 600
     })
     expect(updated.theme).toBe('dark')
     expect(updated.editorAutoSave).toBe(true)
     expect(updated.editorAutoSaveDelayMs).toBe(1500)
+    expect(updated.appFontFamily).toBe('Inter')
     expect(updated.terminalFontSize).toBe(16)
     expect(updated.terminalFontWeight).toBe(600)
     // Other fields preserved
@@ -790,8 +820,7 @@ describe('Store', () => {
         telemetry: {
           optedIn: true,
           installId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
-          existedBeforeTelemetryRelease: false,
-          firstRunNoticeShown: true
+          existedBeforeTelemetryRelease: false
         }
       },
       ui: {},
@@ -802,8 +831,7 @@ describe('Store', () => {
     expect(store.getSettings().telemetry).toEqual({
       optedIn: true,
       installId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
-      existedBeforeTelemetryRelease: false,
-      firstRunNoticeShown: true
+      existedBeforeTelemetryRelease: false
     })
   })
 })
diff --git a/src/main/persistence.ts b/src/main/persistence.ts
index 48f96569644..1ac53c5ee55 100644
--- a/src/main/persistence.ts
+++ b/src/main/persistence.ts
@@ -253,13 +253,13 @@ export class Store {
   // One-shot telemetry cohort migration. Runs on every `load()` but is a
   // no-op once `existedBeforeTelemetryRelease` is set, so subsequent launches
   // pay only the property lookup. Populates:
-  //   - `existedBeforeTelemetryRelease` — cohort discriminator (drives the
-  //     first-launch toast vs. banner in PR 3).
+  //   - `existedBeforeTelemetryRelease` — cohort discriminator (drives
+  //     whether the existing-user opt-in banner is shown in PR 3;
+  //     new users get no first-launch surface).
   //   - `optedIn` — new users start opted in; existing users are `null` until
   //     the banner resolves (the consent resolver returns `pending_banner`
   //     until then, so nothing transmits).
-  //   - `installId` — anonymous UUID v4. Stable across launches; regenerable
-  //     from the Privacy pane (PR 3).
+  //   - `installId` — anonymous UUID v4. Stable across launches; not surfaced in the UI.
   private migrateTelemetry(state: PersistedState, fileExistedOnLoad: boolean): PersistedState {
     const existing = state.settings?.telemetry
     // Why: the one-shot is complete only when all three invariants hold.
@@ -274,16 +274,22 @@ export class Store {
     ) {
       return state
     }
+    // Why: cohort is the authoritative discriminator per invariant #8, so
+    // resolve it once and reuse it below — the `optedIn` fallback must not
+    // re-infer cohort from `fileExistedOnLoad` or field presence, or a
+    // partially-written telemetry block could land a new user in the
+    // existing-user `pending_banner` state.
+    const resolvedExistedBefore =
+      typeof existing?.existedBeforeTelemetryRelease === 'boolean'
+        ? existing.existedBeforeTelemetryRelease
+        : fileExistedOnLoad
     return {
       ...state,
       settings: {
         ...state.settings,
         telemetry: {
           ...existing,
-          existedBeforeTelemetryRelease:
-            typeof existing?.existedBeforeTelemetryRelease === 'boolean'
-              ? existing.existedBeforeTelemetryRelease
-              : fileExistedOnLoad,
+          existedBeforeTelemetryRelease: resolvedExistedBefore,
           // Why: preserve an explicit opt-in/out if the user has ever resolved
           // it. Only fall back to the cohort default (new users: on; existing
           // users: undecided until the first-launch banner resolves) when
@@ -291,7 +297,7 @@ export class Store {
           optedIn:
             existing?.optedIn === true || existing?.optedIn === false || existing?.optedIn === null
               ? existing.optedIn
-              : fileExistedOnLoad
+              : resolvedExistedBefore
                 ? null
                 : true,
           installId:
@@ -616,6 +622,53 @@ export class Store {
     this.scheduleSave()
   }
 
+  // Why: closes the SIGKILL-between-spawn-and-persist race (Issue #217). The
+  // renderer's debounced session writer (~450 ms total) is normally the only
+  // path that writes tab.ptyId / ptyIdsByLeafId; a force-quit inside that
+  // window orphans the daemon's history dir. Patching + sync flushing here
+  // before pty:spawn returns guarantees the renderer cannot observe a
+  // spawn-success without the binding already being durable on disk.
+  persistPtyBinding(args: {
+    worktreeId: string
+    tabId: string
+    leafId: string
+    ptyId: string
+  }): void {
+    const session = this.state.workspaceSession
+    if (!session) {
+      return
+    }
+    const tabs = session.tabsByWorktree?.[args.worktreeId]
+    const tab = tabs?.find((t) => t.id === args.tabId)
+    if (tab) {
+      tab.ptyId = args.ptyId
+    }
+    const layout = session.terminalLayoutsByTabId?.[args.tabId]
+    if (layout) {
+      layout.ptyIdsByLeafId = {
+        ...layout.ptyIdsByLeafId,
+        [args.leafId]: args.ptyId
+      }
+    } else {
+      // Why: first-spawn-ever for a new tab — the renderer's debounced writer
+      // creates the layout entry on PaneManager init, but the binding has to
+      // be on disk before pty:spawn returns or a SIGKILL inside the same
+      // window would lose ptyIdsByLeafId for split-pane cold restore. The
+      // renderer will overwrite this minimal layout once persistLayoutSnapshot
+      // fires.
+      session.terminalLayoutsByTabId = {
+        ...session.terminalLayoutsByTabId,
+        [args.tabId]: {
+          root: { type: 'leaf', leafId: args.leafId },
+          activeLeafId: args.leafId,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [args.leafId]: args.ptyId }
+        }
+      }
+    }
+    this.flush()
+  }
+
   // ── SSH Targets ────────────────────────────────────────────────────
 
   getSshTargets(): SshTarget[] {
diff --git a/src/main/pi/titlebar-extension-service.test.ts b/src/main/pi/titlebar-extension-service.test.ts
index e8458c77f9d..b0715df7cd5 100644
--- a/src/main/pi/titlebar-extension-service.test.ts
+++ b/src/main/pi/titlebar-extension-service.test.ts
@@ -71,7 +71,7 @@ describe('PiTitlebarExtensionService', () => {
     expect(env.PI_CODING_AGENT_DIR).toBe(join(userDataDir, 'pi-agent-overlays', 'pty-1'))
     // Orca's titlebar extension is added alongside user extensions, not replacing them.
     const overlayExtensions = readdirSync(join(env.PI_CODING_AGENT_DIR!, 'extensions')).sort()
-    expect(overlayExtensions).toEqual(['orca-titlebar-spinner.ts', 'user-ext'])
+    expect(overlayExtensions).toEqual(['orca-prefill.ts', 'orca-titlebar-spinner.ts', 'user-ext'])
     // User's top-level resources are reachable via the overlay.
     expect(existsSync(join(env.PI_CODING_AGENT_DIR!, 'skills', 'my-skill', 'SKILL.md'))).toBe(true)
     expect(existsSync(join(env.PI_CODING_AGENT_DIR!, 'auth.json'))).toBe(true)
diff --git a/src/main/pi/titlebar-extension-service.ts b/src/main/pi/titlebar-extension-service.ts
index 407adbc18ce..05832b126e1 100644
--- a/src/main/pi/titlebar-extension-service.ts
+++ b/src/main/pi/titlebar-extension-service.ts
@@ -15,10 +15,44 @@ import { basename, join, relative, resolve, sep } from 'path'
 import { app } from 'electron'
 
 const ORCA_PI_EXTENSION_FILE = 'orca-titlebar-spinner.ts'
+const ORCA_PI_PREFILL_EXTENSION_FILE = 'orca-prefill.ts'
 const PI_AGENT_DIR_NAME = '.pi'
 const PI_AGENT_SUBDIR = 'agent'
 const PI_OVERLAY_DIR_NAME = 'pi-agent-overlays'
 
+// Why: env-var name read by the prefill extension. Mirrors Claude's
+// `--prefill <text>` semantics for pi — the editor mounts with the text
+// already in its input box but unsubmitted, so the user can review/edit
+// before sending. Used by the new-workspace draft-launch flow to drop a
+// linked GitHub/Linear issue URL into pi without racing pi's lengthy
+// startup output (banner + skills + extensions) against the bracketed-
+// paste readiness detector.
+export const ORCA_PI_PREFILL_ENV_VAR = 'ORCA_PI_PREFILL'
+
+// Why: pi exposes `pi.ui.setEditorText(text)` from inside an extension's
+// session_start handler — that's the equivalent of Claude's `--prefill`.
+// We can't use a CLI flag (pi has none) and bracketed-paste-after-ready
+// races against pi's startup output, so we ship a tiny extension that
+// reads ORCA_PI_PREFILL on session_start and types it into the editor.
+// The env var is consumed (deleted from process.env) so /new in the same
+// session doesn't re-prefill.
+function getPiPrefillExtensionSource(): string {
+  return [
+    'export default function (pi) {',
+    "  pi.on('session_start', async (event, ctx) => {",
+    `    const prefill = process.env.${ORCA_PI_PREFILL_ENV_VAR}`,
+    '    if (!prefill) return',
+    `    delete process.env.${ORCA_PI_PREFILL_ENV_VAR}`,
+    "    if (event.reason !== 'startup') return",
+    '    try {',
+    '      ctx.ui.setEditorText(prefill)',
+    '    } catch {}',
+    '  })',
+    '}',
+    ''
+  ].join('\n')
+}
+
 function getPiTitlebarExtensionSource(): string {
   return [
     'const BRAILLE_FRAMES = [',
@@ -272,6 +306,10 @@ export class PiTitlebarExtensionService {
       // instead of replacing that directory, otherwise Orca terminals would
       // silently disable the user's Pi customization inside Orca only.
       writeFileSync(join(extensionsDir, ORCA_PI_EXTENSION_FILE), getPiTitlebarExtensionSource())
+      writeFileSync(
+        join(extensionsDir, ORCA_PI_PREFILL_EXTENSION_FILE),
+        getPiPrefillExtensionSource()
+      )
     } catch {
       // Why: overlay creation is best-effort — permission errors (EPERM/EACCES)
       // on Windows can occur when the userData directory is restricted or when
diff --git a/src/main/providers/local-pty-provider.test.ts b/src/main/providers/local-pty-provider.test.ts
index 25cdabc469c..fe660ed6dfa 100644
--- a/src/main/providers/local-pty-provider.test.ts
+++ b/src/main/providers/local-pty-provider.test.ts
@@ -211,7 +211,7 @@ describe('LocalPtyProvider', () => {
       // socket-close → SIGHUP-to-recycled-pid race (see docs/fix-pty-fd-leak.md).
       const killSpy = mockProc.kill
       const { id } = await provider.spawn({ cols: 80, rows: 24 })
-      await provider.shutdown(id, true)
+      await provider.shutdown(id, { immediate: true })
       expect(killSpy).toHaveBeenCalled()
     })
 
@@ -219,12 +219,12 @@ describe('LocalPtyProvider', () => {
       const onExit = vi.fn()
       provider.configure({ onExit })
       const { id } = await provider.spawn({ cols: 80, rows: 24 })
-      await provider.shutdown(id, true)
+      await provider.shutdown(id, { immediate: true })
       expect(onExit).toHaveBeenCalledWith(id, -1)
     })
 
     it('is a no-op for unknown PTY ids', async () => {
-      await provider.shutdown('nonexistent', true)
+      await provider.shutdown('nonexistent', { immediate: true })
       expect(mockProc.kill).not.toHaveBeenCalled()
     })
   })
diff --git a/src/main/providers/local-pty-provider.ts b/src/main/providers/local-pty-provider.ts
index e156f429c92..8529a5d3f9b 100644
--- a/src/main/providers/local-pty-provider.ts
+++ b/src/main/providers/local-pty-provider.ts
@@ -415,7 +415,7 @@ export class LocalPtyProvider implements IPtyProvider {
     ptyProcesses.get(id)?.resize(cols, rows)
   }
 
-  async shutdown(id: string, _immediate: boolean): Promise<void> {
+  async shutdown(id: string, _opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
     const proc = ptyProcesses.get(id)
     if (!proc) {
       return
diff --git a/src/main/providers/ssh-pty-provider.test.ts b/src/main/providers/ssh-pty-provider.test.ts
index fc4c1ca9170..e705ef8f552 100644
--- a/src/main/providers/ssh-pty-provider.test.ts
+++ b/src/main/providers/ssh-pty-provider.test.ts
@@ -122,8 +122,21 @@ describe('SshPtyProvider', () => {
   })
 
   it('shutdown sends pty.shutdown request', async () => {
-    await provider.shutdown('pty-1', true)
-    expect(mux.request).toHaveBeenCalledWith('pty.shutdown', { id: 'pty-1', immediate: true })
+    await provider.shutdown('pty-1', { immediate: true })
+    expect(mux.request).toHaveBeenCalledWith('pty.shutdown', {
+      id: 'pty-1',
+      immediate: true,
+      keepHistory: false
+    })
+  })
+
+  it('shutdown forwards keepHistory: true over the relay', async () => {
+    await provider.shutdown('pty-1', { immediate: true, keepHistory: true })
+    expect(mux.request).toHaveBeenCalledWith('pty.shutdown', {
+      id: 'pty-1',
+      immediate: true,
+      keepHistory: true
+    })
   })
 
   it('sendSignal sends pty.sendSignal request', async () => {
diff --git a/src/main/providers/ssh-pty-provider.ts b/src/main/providers/ssh-pty-provider.ts
index 8d251ca3bd4..652c28922d2 100644
--- a/src/main/providers/ssh-pty-provider.ts
+++ b/src/main/providers/ssh-pty-provider.ts
@@ -121,8 +121,12 @@ export class SshPtyProvider implements IPtyProvider {
     this.mux.notify('pty.resize', { id, cols, rows })
   }
 
-  async shutdown(id: string, immediate: boolean): Promise<void> {
-    await this.mux.request('pty.shutdown', { id, immediate })
+  async shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void> {
+    await this.mux.request('pty.shutdown', {
+      id,
+      immediate: opts.immediate ?? false,
+      keepHistory: opts.keepHistory ?? false
+    })
   }
 
   async sendSignal(id: string, signal: string): Promise<void> {
diff --git a/src/main/providers/types.ts b/src/main/providers/types.ts
index c2d07d8d6cf..6f36505ec2a 100644
--- a/src/main/providers/types.ts
+++ b/src/main/providers/types.ts
@@ -79,7 +79,7 @@ export type IPtyProvider = {
   attach(id: string): Promise<void>
   write(id: string, data: string): void
   resize(id: string, cols: number, rows: number): void
-  shutdown(id: string, immediate: boolean): Promise<void>
+  shutdown(id: string, opts: { immediate?: boolean; keepHistory?: boolean }): Promise<void>
   sendSignal(id: string, signal: string): Promise<void>
   getCwd(id: string): Promise<string>
   getInitialCwd(id: string): Promise<string>
diff --git a/src/main/rate-limits/service.ts b/src/main/rate-limits/service.ts
index ef827a820b4..b90568567ff 100644
--- a/src/main/rate-limits/service.ts
+++ b/src/main/rate-limits/service.ts
@@ -74,9 +74,17 @@ export class RateLimitService {
   private inactiveCodexFetching = new Set<string>()
   private lastInactiveClaudeFetchAt = 0
   private lastInactiveCodexFetchAt = 0
+  private stateListeners = new Set<(state: RateLimitState) => void>()
 
   constructor() {}
 
+  onStateChange(listener: (state: RateLimitState) => void): () => void {
+    this.stateListeners.add(listener)
+    return () => {
+      this.stateListeners.delete(listener)
+    }
+  }
+
   setCodexHomePathResolver(resolver: () => string | null): void {
     this.codexHomePathResolver = resolver
   }
@@ -757,9 +765,17 @@ export class RateLimitService {
   }
 
   private pushToRenderer(): void {
+    const state = this.getState()
+    for (const listener of this.stateListeners) {
+      try {
+        listener(state)
+      } catch {
+        // ignore — one bad listener must not break the others
+      }
+    }
     if (!this.mainWindow || this.mainWindow.isDestroyed()) {
       return
     }
-    this.mainWindow.webContents.send('rateLimits:update', this.getState())
+    this.mainWindow.webContents.send('rateLimits:update', state)
   }
 }
diff --git a/src/main/runtime/fit-override-integration.test.ts b/src/main/runtime/fit-override-integration.test.ts
index 763b7d8cbf9..a8e7e2ba85c 100644
--- a/src/main/runtime/fit-override-integration.test.ts
+++ b/src/main/runtime/fit-override-integration.test.ts
@@ -98,7 +98,8 @@ describe('fit override integration', () => {
       sleepWorktree: vi.fn(),
       terminalFitOverrideChanged: (ptyId, mode, cols, rows) => {
         notifications.push({ ptyId, mode, cols, rows })
-      }
+      },
+      terminalDriverChanged: vi.fn()
     })
 
     // Simulate a synced leaf (mounted desktop pane)
@@ -200,7 +201,8 @@ describe('fit override integration', () => {
       focusTerminal: vi.fn(),
       closeTerminal: vi.fn(),
       sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn()
+      terminalFitOverrideChanged: vi.fn(),
+      terminalDriverChanged: vi.fn()
     })
 
     // Synced leaf = mounted desktop pane
@@ -261,7 +263,8 @@ describe('fit override integration', () => {
       focusTerminal: vi.fn(),
       closeTerminal: vi.fn(),
       sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn()
+      terminalFitOverrideChanged: vi.fn(),
+      terminalDriverChanged: vi.fn()
     })
 
     runtime.resizeForClient('pty-1', 'mobile-fit', 'phone-disconnect', 45, 20)
diff --git a/src/main/runtime/mobile-presence-lock.test.ts b/src/main/runtime/mobile-presence-lock.test.ts
new file mode 100644
index 00000000000..eea0cb88512
--- /dev/null
+++ b/src/main/runtime/mobile-presence-lock.test.ts
@@ -0,0 +1,346 @@
+/**
+ * Tests for the presence-based mobile driver lock.
+ *
+ * Covers (per docs/mobile-presence-lock.md):
+ *   - State machine transitions (idle | desktop | mobile{clientId})
+ *   - Most-recent-actor wins for active phone-fit dims
+ *   - Earliest-by-subscribe-time wins for desktop-restore target
+ *   - Subscribe-in-desktop-mode is a passive watch (does NOT take floor)
+ *   - mobileTookFloor → re-applies phone-fit when transitioning from desktop
+ *   - reclaimTerminalForDesktop → idempotent, drops banner, restores dims
+ *   - Multi-mobile sequencing: A subscribes / B subscribes / B unsubscribes /
+ *     A unsubscribes leaves the runtime cleanly idle without dim regressions
+ *   - terminalDriverChanged notifications fire at the right transitions
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { OrcaRuntimeService } from './orca-runtime'
+
+vi.mock('../git/worktree', () => ({
+  listWorktrees: vi.fn().mockResolvedValue([])
+}))
+vi.mock('../hooks', () => ({
+  createSetupRunnerScript: vi.fn(),
+  getEffectiveHooks: vi.fn().mockReturnValue(null),
+  runHook: vi.fn().mockResolvedValue({ success: true, output: '' })
+}))
+vi.mock('../ipc/worktree-logic', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>
+  return { ...actual, computeWorktreePath: vi.fn(), ensurePathWithinWorkspace: vi.fn() }
+})
+vi.mock('../ipc/filesystem-auth', () => ({ invalidateAuthorizedRootsCache: vi.fn() }))
+vi.mock('../git/repo', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>
+  return {
+    ...actual,
+    getDefaultBaseRef: vi.fn().mockReturnValue('origin/main'),
+    getBranchConflictKind: vi.fn().mockResolvedValue(null),
+    getGitUsername: vi.fn().mockReturnValue('')
+  }
+})
+
+const store = {
+  getRepo: () => ({
+    id: 'repo-1',
+    path: '/tmp/repo',
+    displayName: 'repo',
+    badgeColor: 'blue',
+    addedAt: 1
+  }),
+  getRepos: () => [store.getRepo()],
+  addRepo: () => {},
+  updateRepo: () => undefined as never,
+  getAllWorktreeMeta: () => ({}),
+  getWorktreeMeta: () => undefined,
+  getGitHubCache: () => ({ pr: {}, issue: {} }),
+  setWorktreeMeta: () => undefined as never,
+  removeWorktreeMeta: () => {},
+  getSettings: () => ({
+    workspaceDir: '/tmp/workspaces',
+    nestWorkspaces: false,
+    refreshLocalBaseRefOnWorktreeCreate: false,
+    branchPrefix: 'none',
+    branchPrefixCustom: ''
+  })
+}
+
+function createRuntime() {
+  const runtime = new OrcaRuntimeService(store)
+  const ptySizes = new Map<string, { cols: number; rows: number }>([
+    ['pty-1', { cols: 150, rows: 40 }]
+  ])
+  const resizes: { ptyId: string; cols: number; rows: number }[] = []
+  const driverEvents: { ptyId: string; driver: { kind: string; clientId?: string } }[] = []
+
+  runtime.setPtyController({
+    write: () => true,
+    kill: () => true,
+    getForegroundProcess: async () => null,
+    resize: (ptyId, cols, rows) => {
+      ptySizes.set(ptyId, { cols, rows })
+      resizes.push({ ptyId, cols, rows })
+      return true
+    },
+    getSize: (ptyId) => ptySizes.get(ptyId) ?? null
+  })
+  runtime.setNotifier({
+    worktreesChanged: vi.fn(),
+    reposChanged: vi.fn(),
+    activateWorktree: vi.fn(),
+    createTerminal: vi.fn(),
+    splitTerminal: vi.fn(),
+    renameTerminal: vi.fn(),
+    focusTerminal: vi.fn(),
+    closeTerminal: vi.fn(),
+    sleepWorktree: vi.fn(),
+    terminalFitOverrideChanged: vi.fn(),
+    terminalDriverChanged: (ptyId, driver) => {
+      driverEvents.push({ ptyId, driver: { ...driver } })
+    }
+  })
+
+  return { runtime, ptySizes, resizes, driverEvents }
+}
+
+describe('mobile presence lock — driver state machine', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('starts idle for unknown PTY', () => {
+    const { runtime } = createRuntime()
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
+  })
+
+  it('handleMobileSubscribe in auto mode transitions idle → mobile{clientId}', () => {
+    const { runtime, driverEvents } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+    expect(driverEvents.at(-1)?.driver).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+  })
+
+  it('handleMobileSubscribe in desktop mode is passive — does NOT take floor', () => {
+    const { runtime, driverEvents } = createRuntime()
+    // Pretend a previous take-back put us in desktop mode.
+    runtime.setMobileDisplayMode('pty-1', 'desktop')
+
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+
+    // Driver stays idle (the desktop banner was already gone). Phone is
+    // "passively watching" at desktop dims.
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
+    expect(driverEvents.find((e) => e.driver.kind === 'mobile')).toBeUndefined()
+  })
+
+  it('reclaimTerminalForDesktop transitions mobile → desktop and is idempotent', () => {
+    const { runtime } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    expect(runtime.getDriver('pty-1').kind).toBe('mobile')
+
+    expect(runtime.reclaimTerminalForDesktop('pty-1')).toBe(true)
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'desktop' })
+
+    // Idempotent — second call is a no-op (no active mobile subscriber to
+    // reclaim from).
+    expect(runtime.reclaimTerminalForDesktop('pty-1')).toBe(true)
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'desktop' })
+  })
+
+  it('mobileTookFloor after reclaim re-applies phone-fit and flips driver back to mobile', () => {
+    const { runtime, ptySizes } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    runtime.reclaimTerminalForDesktop('pty-1')
+    expect(runtime.getDriver('pty-1').kind).toBe('desktop')
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
+
+    runtime.mobileTookFloor('pty-1', 'phone-A')
+
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+    // PTY is back at phone dims.
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
+  })
+
+  it('handleMobileUnsubscribe last leaver flips driver to idle after soft-leave grace', () => {
+    const { runtime, driverEvents } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
+
+    // Why: soft-leave grace keeps driver=mobile{phone-A} for ~250ms so a
+    // re-subscribe (e.g. mobile keyboard show/hide on legacy clients)
+    // doesn't cause a desktop banner flash.
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+
+    vi.advanceTimersByTime(250)
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
+    expect(driverEvents.at(-1)?.driver).toEqual({ kind: 'idle' })
+  })
+
+  it('resubscribe within soft-leave grace cancels idle without driver flap', () => {
+    const { runtime, driverEvents } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+
+    // Same client re-subscribes inside the grace window — no idle should
+    // ever be observed by the renderer.
+    vi.advanceTimersByTime(100)
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    vi.advanceTimersByTime(500)
+
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+    expect(driverEvents.find((e) => e.driver.kind === 'idle')).toBeUndefined()
+  })
+
+  it('onPtyExit clears driver state and emits idle', () => {
+    const { runtime, driverEvents } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+
+    runtime.onPtyExit('pty-1', 0)
+
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
+    // The last emitted event for pty-1 must be idle.
+    const last = [...driverEvents].reverse().find((e) => e.ptyId === 'pty-1')
+    expect(last?.driver).toEqual({ kind: 'idle' })
+  })
+})
+
+describe('mobile presence lock — multi-mobile semantics', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('most-recent actor wins active phone-fit dims (B subscribes after A)', () => {
+    const { runtime, ptySizes } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 45, rows: 20 })
+
+    // Advance fake clock so B's subscribedAt is strictly greater than A's.
+    vi.advanceTimersByTime(10)
+    // B's narrower viewport must win when it subscribes.
+    runtime.handleMobileSubscribe('pty-1', 'phone-B', { cols: 38, rows: 18 })
+
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 38, rows: 18 })
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-B' })
+  })
+
+  it('B unsubscribes — A still present, driver re-elects to A', () => {
+    const { runtime, driverEvents } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    vi.advanceTimersByTime(10)
+    runtime.handleMobileSubscribe('pty-1', 'phone-B', { cols: 38, rows: 18 })
+
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-B')
+
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+    expect(driverEvents.at(-1)?.driver).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+  })
+
+  it('A then B unsubscribes — peer survives; final unsubscribe goes idle', () => {
+    const { runtime } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    vi.advanceTimersByTime(10)
+    runtime.handleMobileSubscribe('pty-1', 'phone-B', { cols: 38, rows: 18 })
+
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-B' })
+
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-B')
+    // Last leaver enters soft-grace; advance past it before asserting idle.
+    vi.advanceTimersByTime(250)
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
+  })
+
+  it('terminal.send by phone-B updates lastActedAt — applyMobileDisplayMode picks B viewport', () => {
+    const { runtime, ptySizes } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    // Advance the fake clock so phone-B's subscribe records a strictly
+    // later subscribedAt/lastActedAt — keeps tie-break deterministic.
+    vi.advanceTimersByTime(10)
+    runtime.handleMobileSubscribe('pty-1', 'phone-B', { cols: 38, rows: 18 })
+    // Switch to desktop, then phone-B types — its viewport wins on re-fit.
+    runtime.setMobileDisplayMode('pty-1', 'desktop')
+    runtime.applyMobileDisplayMode('pty-1')
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
+
+    // Simulate B taking the floor by typing (advance again so lastActedAt
+    // is unambiguously the most recent).
+    vi.advanceTimersByTime(10)
+    runtime.mobileTookFloor('pty-1', 'phone-B')
+
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 38, rows: 18 })
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-B' })
+  })
+
+  it('updateMobileViewport re-fits PTY without flipping the driver', () => {
+    const { runtime, ptySizes, driverEvents } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 49, rows: 38 })
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 49, rows: 38 })
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+    const before = driverEvents.length
+
+    // Keyboard opens — viewport shrinks.
+    expect(runtime.updateMobileViewport('pty-1', 'phone-A', { cols: 49, rows: 16 })).toBe(true)
+
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 49, rows: 16 })
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+    // Why: a viewport update may re-emit driver to refresh listener
+    // wiring, but it must never go through `idle` (no banner flash).
+    expect(driverEvents.slice(before).every((e) => e.driver.kind === 'mobile')).toBe(true)
+  })
+
+  it('updateMobileViewport then disconnect restores PTY to original baseline', () => {
+    const { runtime, ptySizes } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 49, rows: 38 })
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 49, rows: 38 })
+
+    // Keyboard cycles a few times.
+    runtime.updateMobileViewport('pty-1', 'phone-A', { cols: 49, rows: 16 })
+    runtime.updateMobileViewport('pty-1', 'phone-A', { cols: 49, rows: 38 })
+    runtime.updateMobileViewport('pty-1', 'phone-A', { cols: 49, rows: 16 })
+
+    // Phone disconnects (router.back → WS close).
+    runtime.onClientDisconnected('phone-A')
+
+    // PTY must restore to the original 150x40 baseline, not the last
+    // phone-fit dim. This was the stuck-dim bug.
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'idle' })
+  })
+
+  it('legacy unsubscribe → resubscribe within grace preserves baseline (regression)', () => {
+    const { runtime, ptySizes } = createRuntime()
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 49, rows: 38 })
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 49, rows: 38 })
+
+    // Simulate legacy keyboard re-subscribe cycle within grace.
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
+    vi.advanceTimersByTime(100)
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 49, rows: 16 })
+    // Apply mode after re-subscribe so the new viewport drives PTY dims.
+    runtime.applyMobileDisplayMode('pty-1')
+
+    // PTY at new viewport, phone-A still drives.
+    expect(runtime.getDriver('pty-1')).toEqual({ kind: 'mobile', clientId: 'phone-A' })
+
+    // Disconnect — must restore to original 150x40, not 49x16.
+    runtime.onClientDisconnected('phone-A')
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
+  })
+
+  it('earliest-subscribe restore target is preserved when peers churn', () => {
+    const { runtime, ptySizes } = createRuntime()
+    // A captures the original 150x40 baseline.
+    runtime.handleMobileSubscribe('pty-1', 'phone-A', { cols: 45, rows: 20 })
+    // B subscribes later at 38x18 (advance clock for unambiguous ordering).
+    vi.advanceTimersByTime(10)
+    runtime.handleMobileSubscribe('pty-1', 'phone-B', { cols: 38, rows: 18 })
+
+    // A leaves, B leaves — final restore must use A's earliest baseline (150x40),
+    // NOT B's (which captured 45x20 when it joined a phone-fitted PTY).
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-A')
+    runtime.handleMobileUnsubscribe('pty-1', 'phone-B')
+    vi.advanceTimersByTime(300)
+
+    expect(ptySizes.get('pty-1')).toEqual({ cols: 150, rows: 40 })
+  })
+})
diff --git a/src/main/runtime/mobile-subscribe-integration.test.ts b/src/main/runtime/mobile-subscribe-integration.test.ts
index f5eed223526..fd344c61511 100644
--- a/src/main/runtime/mobile-subscribe-integration.test.ts
+++ b/src/main/runtime/mobile-subscribe-integration.test.ts
@@ -102,7 +102,8 @@ function createRuntime() {
     sleepWorktree: vi.fn(),
     terminalFitOverrideChanged: (ptyId, mode, cols, rows) => {
       notifications.push({ ptyId, mode, cols, rows })
-    }
+    },
+    terminalDriverChanged: vi.fn()
   })
 
   return { runtime, ptySizes, resizes, notifications }
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index 3fb54c5a637..2133215a265 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -209,6 +209,16 @@ describe('OrcaRuntimeService', () => {
     expect(runtime.getRuntimeId()).toBeTruthy()
   })
 
+  it('reports protocol version and minimum compatible mobile version on status', () => {
+    const runtime = createRuntime()
+
+    const status = runtime.getStatus()
+    expect(typeof status.protocolVersion).toBe('number')
+    expect(typeof status.minCompatibleMobileVersion).toBe('number')
+    expect(status.protocolVersion).toBeGreaterThanOrEqual(1)
+    expect(status.minCompatibleMobileVersion).toBeGreaterThanOrEqual(0)
+  })
+
   it('claims the first window as authoritative and ignores later windows', () => {
     const runtime = createRuntime()
 
@@ -793,6 +803,46 @@ describe('OrcaRuntimeService', () => {
     })
   })
 
+  it('clears stale working status after the agent exits and the shell takes over the title', async () => {
+    // Why: regression test for issue #1437 — the mobile worktree-list spinner
+    // kept playing forever because lastAgentStatus was sticky on 'working'
+    // once an agent exited without emitting an idle/agent-shaped final OSC
+    // title. worktree.ps must recompute from the live OSC title each call.
+    const runtime = new OrcaRuntimeService(store)
+
+    runtime.attachWindow(1)
+    runtime.syncWindowGraph(1, {
+      tabs: [
+        {
+          tabId: 'tab-1',
+          worktreeId: 'repo-1::/tmp/worktree-a',
+          title: 'Codex working',
+          activeLeafId: 'pane:1',
+          layout: null
+        }
+      ],
+      leaves: [
+        {
+          tabId: 'tab-1',
+          worktreeId: 'repo-1::/tmp/worktree-a',
+          leafId: 'pane:1',
+          paneRuntimeId: 1,
+          ptyId: 'pty-1'
+        }
+      ]
+    })
+
+    runtime.onPtyData('pty-1', '\x1b]0;Codex working\x07', 100)
+    const working = await runtime.getWorktreePs()
+    expect(working.worktrees[0].status).toBe('working')
+
+    // Agent exits, shell title takes over — desktop's getWorktreeStatus would
+    // immediately flip back to 'active'. Mobile must do the same.
+    runtime.onPtyData('pty-1', '\x1b]0;bash\x07', 200)
+    const afterExit = await runtime.getWorktreePs()
+    expect(afterExit.worktrees[0].status).toBe('active')
+  })
+
   it('fails terminal stop closed while the renderer graph is reloading', async () => {
     const runtime = new OrcaRuntimeService(store)
     let killed = false
@@ -945,7 +995,8 @@ describe('OrcaRuntimeService', () => {
       focusTerminal: vi.fn(),
       closeTerminal: vi.fn(),
       sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn()
+      terminalFitOverrideChanged: vi.fn(),
+      terminalDriverChanged: vi.fn()
     })
     runtime.attachWindow(1)
 
@@ -1022,7 +1073,8 @@ describe('OrcaRuntimeService', () => {
       focusTerminal: vi.fn(),
       closeTerminal: vi.fn(),
       sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn()
+      terminalFitOverrideChanged: vi.fn(),
+      terminalDriverChanged: vi.fn()
     })
     runtime.attachWindow(1)
 
@@ -1062,6 +1114,54 @@ describe('OrcaRuntimeService', () => {
     expect(activateWorktree).toHaveBeenCalledWith('repo-1', expect.any(String), 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
+    // after creation can push the new worktree below them in Recent sort.
+    const runtime = new OrcaRuntimeService(store)
+    runtime.setNotifier({
+      worktreesChanged: vi.fn(),
+      reposChanged: vi.fn(),
+      activateWorktree: vi.fn(),
+      createTerminal: 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-grace')
+    ensurePathWithinWorkspaceMock.mockReturnValue('/tmp/workspaces/runtime-grace')
+    vi.mocked(getEffectiveHooks).mockReturnValue({ scripts: {} })
+    vi.mocked(listWorktrees).mockResolvedValueOnce([
+      {
+        path: '/tmp/workspaces/runtime-grace',
+        head: 'def',
+        branch: 'runtime-grace',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+
+    const before = Date.now()
+    const result = await runtime.createManagedWorktree({
+      repoSelector: 'id:repo-1',
+      name: 'runtime-grace'
+    })
+    const after = Date.now()
+
+    expect(result.worktree.createdAt).toBeDefined()
+    expect(result.worktree.createdAt).toBeGreaterThanOrEqual(before)
+    expect(result.worktree.createdAt).toBeLessThanOrEqual(after)
+    // Both fields must be stamped from the same `now` so the grace-window
+    // math (max(lastActivityAt, createdAt + GRACE_MS)) is well-defined.
+    expect(result.worktree.createdAt).toBe(result.worktree.lastActivityAt)
+  })
+
   it('skips archive hooks for CLI worktree removal by default', async () => {
     const runtime = new OrcaRuntimeService(store)
     vi.mocked(getEffectiveHooks).mockReturnValue({
@@ -1115,7 +1215,8 @@ describe('OrcaRuntimeService', () => {
       focusTerminal: vi.fn(),
       closeTerminal: vi.fn(),
       sleepWorktree: vi.fn(),
-      terminalFitOverrideChanged: vi.fn()
+      terminalFitOverrideChanged: vi.fn(),
+      terminalDriverChanged: vi.fn()
     })
 
     computeWorktreePathMock.mockReturnValue('/tmp/workspaces/cli-worktree')
@@ -1483,10 +1584,9 @@ describe('OrcaRuntimeService', () => {
 
       // The post-daemon provider's prefix-matching session must have been
       // shut down, proving the thunk resolved lazily at call time.
-      expect(postDaemonProvider.shutdown).toHaveBeenCalledWith(
-        `${TEST_WORKTREE_ID}@@aaaaaaaa`,
-        true
-      )
+      expect(postDaemonProvider.shutdown).toHaveBeenCalledWith(`${TEST_WORKTREE_ID}@@aaaaaaaa`, {
+        immediate: true
+      })
       // The pre-daemon provider must not have been consulted for the kill.
       expect(preDaemonProvider.shutdown).not.toHaveBeenCalled()
     })
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index be4210e28f7..a61d0498ef2 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -21,6 +21,10 @@ import type {
   WorktreeStartupLaunch
 } from '../../shared/types'
 import { isFolderRepo } from '../../shared/repo-kind'
+import {
+  DESKTOP_PROTOCOL_VERSION,
+  MIN_COMPATIBLE_MOBILE_VERSION
+} from '../../shared/protocol-version'
 import type {
   RuntimeGraphStatus,
   RuntimeRepoSearchRefs,
@@ -53,9 +57,17 @@ import type {
   BrowserScrollResult,
   BrowserBackResult,
   BrowserReloadResult,
+  BrowserProfileCreateResult,
+  BrowserProfileDeleteResult,
+  BrowserProfileListResult,
   BrowserScreenshotResult,
   BrowserEvalResult,
+  BrowserTabCurrentResult,
   BrowserTabListResult,
+  BrowserTabProfileCloneResult,
+  BrowserTabProfileShowResult,
+  BrowserTabSetProfileResult,
+  BrowserTabShowResult,
   BrowserTabSwitchResult,
   BrowserHoverResult,
   BrowserDragResult,
@@ -81,7 +93,9 @@ import type {
 } from '../../shared/runtime-types'
 import { 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 {
@@ -122,7 +136,25 @@ import {
 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 { ClaudeAccountService } from '../claude-accounts/service'
+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'
+
+type RuntimeAccountServices = {
+  claudeAccounts: ClaudeAccountService
+  codexAccounts: CodexAccountService
+  rateLimits: RateLimitService
+}
+
+export type AccountsSnapshot = {
+  claude: ClaudeRateLimitAccountsState
+  codex: CodexRateLimitAccountsState
+  rateLimits: RateLimitState
+}
 
 type RuntimeStore = {
   getRepos: Store['getRepos']
@@ -156,6 +188,12 @@ type RuntimeLeafRecord = RuntimeSyncedLeaf & {
   tailLinesTotal: number
   preview: string
   lastAgentStatus: AgentStatus | null
+  // Why: the most recent OSC title observed on this leaf's PTY data. Used by
+  // worktree.ps so daemon-hosted terminals (no renderer pushing pane titles)
+  // still recompute working/idle from the live title each call instead of
+  // serving a stale `lastAgentStatus` after the agent process exits and the
+  // shell takes over the title — the bug behind issue #1437.
+  lastOscTitle: string | null
 }
 
 type RuntimePtyWorktreeRecord = {
@@ -181,7 +219,14 @@ type RuntimePtyController = {
   getForegroundProcess(ptyId: string): Promise<string | null>
   resize?(ptyId: string, cols: number, rows: number): boolean
   listProcesses?(): Promise<{ id: string; cwd: string; title: string }[]>
-  serializeBuffer?(ptyId: string): Promise<{ data: string; cols: number; rows: number } | null>
+  serializeBuffer?(
+    ptyId: string,
+    opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }
+  ): Promise<{ data: string; cols: number; rows: number; lastTitle?: string } | null>
+  // Why: synchronous probe used by maybeHydrateHeadlessFromRenderer to skip
+  // hydration when no renderer is authoritative for this PTY. See
+  // docs/mobile-prefer-renderer-scrollback.md.
+  hasRendererSerializer?(ptyId: string): boolean
   getSize?(ptyId: string): { cols: number; rows: number } | null
 }
 
@@ -210,6 +255,13 @@ type RuntimeNotifier = {
     cols: number,
     rows: number
   ): void
+  // Why: presence-based lock signal — desktop renderer mounts the lock
+  // banner when `driver.kind === 'mobile'` and unmounts otherwise. The
+  // structured payload (vs a `locked: boolean`) carries the active mobile
+  // actor's clientId so the renderer can disambiguate multi-phone scenarios
+  // and so a future write coordinator can use the same signal as scheduling
+  // input. See docs/mobile-presence-lock.md.
+  terminalDriverChanged(ptyId: string, driver: DriverState): void
 }
 
 type TerminalHandleRecord = {
@@ -278,6 +330,20 @@ export type MobileNotificationEvent = {
   worktreeId?: string
 }
 
+// Why: presence-based driver state for the mobile-presence lock. Exactly one
+// driver per PTY at any moment. See docs/mobile-presence-lock.md.
+//   - `idle`: no mobile subscribers; desktop input flows freely
+//   - `desktop`: at least one mobile client subscribed but desktop reclaimed
+//      (or all mobile clients are passive `desktop`-mode watchers); desktop
+//      input flows freely
+//   - `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 class OrcaRuntimeService {
   private readonly runtimeId = randomUUID()
   private readonly startedAt = Date.now()
@@ -312,6 +378,12 @@ export class OrcaRuntimeService {
     Set<(event: { mode: 'mobile-fit' | 'desktop-fit'; cols: number; rows: number }) => 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
+  // touching subscriptions on other live sockets that share the same
+  // deviceToken (multi-screen mobile).
+  private subscriptionsByConnection = new Map<string, Set<string>>()
+  private subscriptionConnectionByEntry = new Map<string, string>()
   // Why: mobile clients subscribe to desktop notifications via
   // notifications.subscribe. This set enables fan-out — each connected
   // mobile client gets its own listener, and dispatchMobileNotification
@@ -319,6 +391,12 @@ export class OrcaRuntimeService {
   private notificationListeners = new Set<(event: MobileNotificationEvent) => void>()
   private ptysById = new Map<string, RuntimePtyWorktreeRecord>()
   private headlessTerminals = new Map<string, RuntimeHeadlessTerminal>()
+  // Why: per-PTY hydration state guards against double-hydration. Keys:
+  //   'pending'  → maybeHydrateHeadlessFromRenderer is in flight
+  //   'done'     → hydration completed (success or skip); never run again
+  // Absent  → hydration has not been considered yet for this PTY.
+  // See docs/mobile-prefer-renderer-scrollback.md.
+  private headlessHydrationState = new Map<string, 'pending' | 'done'>()
   // Why: mobile-fit overrides are keyed by ptyId (not terminal handle) because
   // handles can be reissued while the PTY identity is stable. In-memory only —
   // a stale phone override should not survive an app restart.
@@ -340,17 +418,68 @@ export class OrcaRuntimeService {
   // the mode regardless of subscriber state. In-memory only — modes reset on restart.
   private mobileDisplayModes = new Map<string, 'auto' | 'phone' | 'desktop'>()
 
-  // Why: tracks active mobile subscriber per PTY so the runtime can restore
+  // Why: tracks active mobile subscribers per PTY so the runtime can restore
   // desktop dimensions on unsubscribe and prevent orphaned overrides during
-  // rapid tab switches. Keyed by ptyId (single mobile client per terminal).
+  // rapid tab switches. Keyed by ptyId → inner map of clientId → subscriber.
+  // The two-level map preserves multi-mobile soundness: phone B subscribing
+  // does not silently overwrite phone A's record. See
+  // docs/mobile-presence-lock.md "Multi-mobile subscriber model".
+  // subscribedAt drives "earliest-by-subscribe-time" restore-target selection
+  // (only among subscribers with non-null previousCols/Rows; desktop-mode
+  // joins carry null and are skipped). lastActedAt drives "most-recent
+  // actor's viewport wins" for active phone-fit dims.
   private mobileSubscribers = new Map<
+    string,
+    Map<
+      string,
+      {
+        clientId: string
+        viewport: { cols: number; rows: number } | null
+        wasResizedToPhone: boolean
+        previousCols: number | null
+        previousRows: number | null
+        subscribedAt: number
+        lastActedAt: number
+      }
+    >
+  >()
+
+  // Why: per-PTY driver state. The "driver" is whoever currently owns the
+  // input/resize floor. While `kind === 'mobile'` the desktop renderer drops
+  // xterm.onData/onResize and shows the lock banner; `terminal.send` /
+  // `pty:write` and `pty:resize` IPC handlers also drop desktop-side calls
+  // server-side as defense-in-depth. The `clientId` carried on the mobile
+  // variant is the most recent mobile actor — used by
+  // `applyMobileDisplayMode` to pick the active phone-fit viewport. See
+  // docs/mobile-presence-lock.md.
+  private currentDriver = new Map<string, DriverState>()
+
+  // Why: resubscribe-grace window. When the last mobile subscriber for a
+  // PTY unsubscribes, we hold the driver=mobile{clientId} state and the
+  // inner-map record open for ~250ms. If the same (ptyId, clientId)
+  // re-subscribes inside the window — typically because the mobile app
+  // tore down the stream to reconfigure (rare with the new
+  // updateMobileViewport path, but still possible on reconnects, network
+  // hiccups, or older client builds) — we cancel the deferred idle and
+  // restore-timer so the desktop banner doesn't flash and the new
+  // subscriber doesn't capture an already-phone-fitted PTY size as its
+  // restore baseline. Keyed by ptyId; carries the timer plus the snapshot
+  // of the leaving subscriber so we can re-insert it on cancel. See
+  // docs/mobile-presence-lock.md.
+  private pendingSoftLeavers = new Map<
     string,
     {
       clientId: string
-      viewport: { cols: number; rows: number } | null
-      wasResizedToPhone: boolean
-      previousCols: number | null
-      previousRows: number | null
+      timer: ReturnType<typeof setTimeout>
+      record: {
+        clientId: string
+        viewport: { cols: number; rows: number } | null
+        wasResizedToPhone: boolean
+        previousCols: number | null
+        previousRows: number | null
+        subscribedAt: number
+        lastActedAt: number
+      }
     }
   >()
 
@@ -409,6 +538,7 @@ export class OrcaRuntimeService {
   private fetchInflight = new Map<string, Promise<void>>()
   private fetchLastCompletedAt = new Map<string, number>()
   private readonly getLocalProviderFn: (() => IPtyProvider) | null
+  private accountServices: RuntimeAccountServices | null = null
 
   constructor(
     store: RuntimeStore | null = null,
@@ -468,7 +598,9 @@ export class OrcaRuntimeService {
       graphStatus: this.graphStatus,
       authoritativeWindowId: this.authoritativeWindowId,
       liveTabCount: this.tabs.size,
-      liveLeafCount: this.leaves.size
+      liveLeafCount: this.leaves.size,
+      protocolVersion: DESKTOP_PROTOCOL_VERSION,
+      minCompatibleMobileVersion: MIN_COMPATIBLE_MOBILE_VERSION
     }
   }
 
@@ -536,7 +668,8 @@ export class OrcaRuntimeService {
         tailTruncated: existing?.ptyId === ptyId ? existing.tailTruncated : false,
         tailLinesTotal: existing?.ptyId === ptyId ? existing.tailLinesTotal : 0,
         preview: existing?.ptyId === ptyId ? existing.preview : '',
-        lastAgentStatus: existing?.ptyId === ptyId ? existing.lastAgentStatus : null
+        lastAgentStatus: existing?.ptyId === ptyId ? existing.lastAgentStatus : null,
+        lastOscTitle: existing?.ptyId === ptyId ? existing.lastOscTitle : null
       })
 
       if (leaf.ptyId) {
@@ -646,6 +779,14 @@ export class OrcaRuntimeService {
     // Agent detection runs on raw data before leaf processing, since the
     // tail buffer logic normalizes away the OSC sequences we need.
     this.agentDetector?.onData(ptyId, data, at)
+    // Ordering invariant (DO NOT REORDER): maybeHydrateHeadlessFromRenderer
+    // MUST run before trackHeadlessTerminalData so the eager-state pattern
+    // (set headlessTerminals + writeChain head = seedPromise) is in place
+    // before the live byte's chain link is queued. Without this ordering,
+    // trackHeadlessTerminalData would lazy-create a fresh state at PTY dims
+    // that the later seed-resolve would overwrite, dropping the live byte.
+    // See docs/mobile-prefer-renderer-scrollback.md.
+    this.maybeHydrateHeadlessFromRenderer(ptyId)
     this.trackHeadlessTerminalData(ptyId, data)
 
     // Why: extract OSC title from raw PTY data before tail-buffer processing
@@ -686,8 +827,21 @@ export class OrcaRuntimeService {
       leaf.tailLinesTotal += nextTail.newCompleteLines
       leaf.preview = buildPreview(leaf.tailBuffer, leaf.tailPartialLine)
 
-      if (agentStatus !== null) {
+      if (oscTitle !== null) {
+        // Why: keep the latest OSC title on the leaf so worktree.ps can
+        // recompute status from the live title each call. Without this,
+        // daemon-hosted terminals (no renderer pushing pane titles) had no
+        // way to clear a stale 'working' status after the agent exited and
+        // the shell took over the title — the stuck-spinner bug in #1437.
+        leaf.lastOscTitle = oscTitle
         const prevStatus = leaf.lastAgentStatus
+        // Why: when a new OSC title doesn't classify as an agent state (e.g.
+        // bare shell title after the agent exits), clear lastAgentStatus so
+        // it is no longer sticky. Tui-idle waiters that needed the previous
+        // 'idle' transition were already resolved at the moment of the
+        // transition below; only fresh waiters registered after the agent
+        // exits would observe the cleared value, and they correctly fall
+        // back to title-based detection / polling.
         leaf.lastAgentStatus = agentStatus
         // Why: resolve tui-idle on any transition TO idle (not just working→idle).
         // Claude Code may skip "working" entirely on fast tasks, going null→idle,
@@ -759,15 +913,142 @@ export class OrcaRuntimeService {
   }
 
   serializeTerminalBuffer(
-    ptyId: string
+    ptyId: string,
+    opts: { scrollbackRows?: number } = {}
   ): Promise<{ data: string; cols: number; rows: number } | null> {
-    return this.serializeTerminalBufferFromAvailableState(ptyId)
+    return this.serializeTerminalBufferFromAvailableState(ptyId, opts)
   }
 
   getTerminalSize(ptyId: string): { cols: number; rows: number } | null {
     return this.ptyController?.getSize?.(ptyId) ?? null
   }
 
+  // Why: daemon-backed PTYs that the runtime adopted after an Orca relaunch
+  // start with a fresh headless emulator that has zero scrollback, even though
+  // the daemon's on-disk checkpoint and the desktop xterm both contain the
+  // full prior history. Without this hydration, mobile subscribers see only
+  // the bare current prompt because serializeHeadlessTerminalBuffer always
+  // wins over the renderer-path fallback. Seeding the emulator with the
+  // adapter's snapshot/cold-restore data makes mobile and desktop agree on
+  // what scrollback is available.
+  seedHeadlessTerminal(ptyId: string, data: string, size?: { cols: number; rows: number }): void {
+    if (!data) {
+      return
+    }
+    const existing = this.headlessTerminals.get(ptyId)
+    if (existing) {
+      // Why: emulator already has live data — re-seeding would duplicate
+      // every byte. The seed is only valid when the emulator is fresh.
+      return
+    }
+    const dims = size ?? this.getTerminalSize(ptyId) ?? { cols: 80, rows: 24 }
+    const state: RuntimeHeadlessTerminal = {
+      emulator: new HeadlessEmulator({ cols: dims.cols, rows: dims.rows }),
+      writeChain: Promise.resolve()
+    }
+    this.headlessTerminals.set(ptyId, state)
+    state.writeChain = state.writeChain
+      .then(() => state.emulator.write(data))
+      .catch(() => {
+        // Seeding is best-effort; live data will continue to populate the
+        // emulator even if the snapshot replay fails.
+      })
+  }
+
+  // Why: hydrate the runtime headless emulator from the desktop renderer's
+  // xterm buffer on the first onPtyData byte after a PTY is taken over by a
+  // pane. Eager-state pattern matches seedHeadlessTerminal: headlessTerminals
+  // is populated synchronously so concurrent live writes from
+  // trackHeadlessTerminalData chain after the seed via the same writeChain.
+  // See docs/mobile-prefer-renderer-scrollback.md.
+  private maybeHydrateHeadlessFromRenderer(ptyId: string): void {
+    if (this.headlessHydrationState.has(ptyId)) {
+      return
+    }
+    if (this.headlessTerminals.has(ptyId)) {
+      // Daemon-snapshot seed already populated the emulator — skip hydration.
+      this.headlessHydrationState.set(ptyId, 'done')
+      return
+    }
+    const controller = this.ptyController
+    if (!controller?.serializeBuffer || !controller.hasRendererSerializer) {
+      return
+    }
+    if (!controller.hasRendererSerializer(ptyId)) {
+      // Renderer hasn't registered yet (or never will). Live writes lazy-
+      // create the state via trackHeadlessTerminalData on this same tick.
+      return
+    }
+
+    this.headlessHydrationState.set(ptyId, 'pending')
+    const dims = this.getTerminalSize(ptyId) ?? { cols: 80, rows: 24 }
+    const state: RuntimeHeadlessTerminal = {
+      emulator: new HeadlessEmulator({ cols: dims.cols, rows: dims.rows }),
+      writeChain: Promise.resolve()
+    }
+    this.headlessTerminals.set(ptyId, state)
+
+    // Why: append the seed work to writeChain so live writes queued by
+    // trackHeadlessTerminalData (after this method returns synchronously)
+    // execute AFTER the seed-write resolves. If we awaited inline before
+    // setting headlessTerminals, the live byte would lazy-create a separate
+    // state and the seed-resolve would overwrite it, dropping live bytes.
+    state.writeChain = state.writeChain.then(async () => {
+      try {
+        const rendered = await controller.serializeBuffer!(ptyId, {
+          scrollbackRows: MOBILE_SUBSCRIBE_SCROLLBACK_ROWS,
+          altScreenForcesZeroRows: true
+        })
+        if (!rendered || rendered.data.length === 0) {
+          return
+        }
+        // Resize to renderer's dims so the seed reflows correctly into the
+        // emulator's grid, then resize back to PTY dims (if known) so live
+        // writes use the correct cell layout.
+        if (rendered.cols !== dims.cols || rendered.rows !== dims.rows) {
+          state.emulator.resize(rendered.cols, rendered.rows)
+        }
+        await state.emulator.write(rendered.data)
+        const ptyDims = this.getTerminalSize(ptyId)
+        if (ptyDims && (ptyDims.cols !== rendered.cols || ptyDims.rows !== rendered.rows)) {
+          state.emulator.resize(ptyDims.cols, ptyDims.rows)
+        }
+        if (rendered.lastTitle) {
+          this.applySeededAgentStatus(ptyId, rendered.lastTitle)
+        }
+      } catch {
+        // Hydration is best-effort. Live writes continue via the same
+        // writeChain that this catch-arm leaves intact.
+      } finally {
+        this.headlessHydrationState.set(ptyId, 'done')
+      }
+    })
+  }
+
+  // Why: seed-derived agent status reflects historical state. Orchestration
+  // waiters (resolveTuiIdleWaiters, deliverPendingMessages) must only react
+  // to LIVE transitions, so this helper writes leaf.lastAgentStatus only and
+  // never resolves waiters. detectAgentStatusFromTitle wrap mirrors the live
+  // path so seeded and live values are the same union member, keeping
+  // downstream `=== 'idle'` checks correct.
+  private applySeededAgentStatus(ptyId: string, title: string): void {
+    if (!title) {
+      return
+    }
+    const status = detectAgentStatusFromTitle(title)
+    for (const leaf of this.leaves.values()) {
+      if (leaf.ptyId === ptyId) {
+        // Why: seed lastOscTitle even when the seeded title doesn't classify
+        // as an agent state, so worktree.ps recomputes status from the live
+        // title rather than treating the leaf as agentless.
+        leaf.lastOscTitle = title
+        if (status !== null) {
+          leaf.lastAgentStatus = status
+        }
+      }
+    }
+  }
+
   private trackHeadlessTerminalData(ptyId: string, data: string): void {
     const state = this.getOrCreateHeadlessTerminal(ptyId)
     state.writeChain = state.writeChain
@@ -797,17 +1078,29 @@ export class OrcaRuntimeService {
   }
 
   private async serializeTerminalBufferFromAvailableState(
-    ptyId: string
+    ptyId: string,
+    opts: { scrollbackRows?: number } = {}
   ): Promise<{ data: string; cols: number; rows: number } | null> {
-    const headlessSnapshot = await this.serializeHeadlessTerminalBuffer(ptyId)
+    const headlessSnapshot = await this.serializeHeadlessTerminalBuffer(ptyId, opts)
     if (headlessSnapshot) {
       return headlessSnapshot
     }
 
-    let rendererSnapshot: { data: string; cols: number; rows: number } | null = null
+    let rendererSnapshot: {
+      data: string
+      cols: number
+      rows: number
+      lastTitle?: string
+    } | null = null
     try {
-      rendererSnapshot = await (this.ptyController?.serializeBuffer?.(ptyId) ??
-        Promise.resolve(null))
+      // Why: read-fallback wants visible alt-screen content (e.g. an active
+      // TUI like vim) so altScreenForcesZeroRows is FALSE here. Hydration is
+      // the only path that suppresses alt-screen scrollback. See
+      // docs/mobile-prefer-renderer-scrollback.md.
+      rendererSnapshot = await (this.ptyController?.serializeBuffer?.(ptyId, {
+        scrollbackRows: opts.scrollbackRows,
+        altScreenForcesZeroRows: false
+      }) ?? Promise.resolve(null))
     } catch {
       // Why: mobile scrollback should not depend on a mounted renderer pane.
       // If renderer serialization races reload/unmount, the runtime snapshot
@@ -820,22 +1113,30 @@ export class OrcaRuntimeService {
   }
 
   private async serializeHeadlessTerminalBuffer(
-    ptyId: string
+    ptyId: string,
+    opts: { scrollbackRows?: number } = {}
   ): Promise<{ data: string; cols: number; rows: number } | null> {
     const state = this.headlessTerminals.get(ptyId)
     if (!state) {
       return null
     }
     await state.writeChain
-    // Why: terminal.subscribe needs the current visible screen, not the full
-    // launch history. Full scrollback plus a normal-buffer TUI can replay the
-    // shell prompt and active TUI frame together, which looks duplicated.
-    const snapshot = state.emulator.getSnapshot({ scrollbackRows: 0 })
+    // Why: when an alternate-screen TUI (Claude Code, vim, etc.) is currently
+    // active, the visible content is the alt-screen snapshot — replaying any
+    // normal-buffer scrollback before it can duplicate shell prompts and
+    // flatten SGR attributes when the mobile xterm replays the data. Force
+    // scrollbackRows=0 in that case. When the buffer is in normal mode the
+    // caller can request scrollback so the user can scroll up to see prior
+    // agent output.
+    const requested = opts.scrollbackRows ?? 0
+    const scrollbackRows = state.emulator.isAlternateScreen ? 0 : requested
+    const snapshot = state.emulator.getSnapshot({ scrollbackRows })
     const data = snapshot.rehydrateSequences + snapshot.snapshotAnsi
     return data.length > 0 ? { data, cols: snapshot.cols, rows: snapshot.rows } : null
   }
 
   private disposeHeadlessTerminal(ptyId: string): void {
+    this.headlessHydrationState.delete(ptyId)
     const state = this.headlessTerminals.get(ptyId)
     if (!state) {
       return
@@ -859,7 +1160,11 @@ export class OrcaRuntimeService {
     return { ptyId: leaf.ptyId }
   }
 
-  registerSubscriptionCleanup(subscriptionId: string, cleanup: () => void): void {
+  registerSubscriptionCleanup(
+    subscriptionId: string,
+    cleanup: () => void,
+    connectionId?: string
+  ): void {
     // Why: mobile clients reconnect frequently (phone lock, network switch).
     // The RPC client re-sends terminal.subscribe on reconnect, creating a new
     // handler before the old one is cleaned up. Without this, the old data
@@ -867,18 +1172,57 @@ export class OrcaRuntimeService {
     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.subscriptionCleanups.set(subscriptionId, cleanup)
+    if (connectionId) {
+      let set = this.subscriptionsByConnection.get(connectionId)
+      if (!set) {
+        set = new Set()
+        this.subscriptionsByConnection.set(connectionId, set)
+      }
+      set.add(subscriptionId)
+      this.subscriptionConnectionByEntry.set(subscriptionId, connectionId)
+    }
   }
 
   cleanupSubscription(subscriptionId: string): void {
     const cleanup = this.subscriptionCleanups.get(subscriptionId)
     if (cleanup) {
       this.subscriptionCleanups.delete(subscriptionId)
+      const connectionId = this.subscriptionConnectionByEntry.get(subscriptionId)
+      if (connectionId) {
+        this.subscriptionConnectionByEntry.delete(subscriptionId)
+        const set = this.subscriptionsByConnection.get(connectionId)
+        if (set) {
+          set.delete(subscriptionId)
+          if (set.size === 0) {
+            this.subscriptionsByConnection.delete(connectionId)
+          }
+        }
+      }
       cleanup()
     }
   }
 
+  // Why: invoked from the WebSocket transport's on-close hook so streaming
+  // listeners registered for this exact socket get torn down even when other
+  // sockets sharing the same deviceToken are still alive (multi-screen
+  // mobile). Without this sweep, listeners leak across every reconnect.
+  cleanupSubscriptionsForConnection(connectionId: string): void {
+    const set = this.subscriptionsByConnection.get(connectionId)
+    if (!set) {
+      return
+    }
+    // Why: snapshot the ids before iterating because cleanupSubscription
+    // mutates both the set and the index map.
+    const ids = Array.from(set)
+    for (const id of ids) {
+      this.cleanupSubscription(id)
+    }
+  }
+
   // Why: mobile clients subscribe via notifications.subscribe streaming RPC.
   // Each subscriber gets its own listener. Returns an unsubscribe function
   // that the subscription cleanup mechanism calls on disconnect.
@@ -899,6 +1243,73 @@ export class OrcaRuntimeService {
     }
   }
 
+  // ─── Account Services (mobile RPC bridge) ─────────────────────
+
+  setAccountServices(services: RuntimeAccountServices): void {
+    this.accountServices = services
+  }
+
+  private requireAccountServices(): RuntimeAccountServices {
+    if (!this.accountServices) {
+      throw new Error('Account services are not configured on this runtime')
+    }
+    return this.accountServices
+  }
+
+  getAccountsSnapshot(): AccountsSnapshot {
+    const { claudeAccounts, codexAccounts, rateLimits } = this.requireAccountServices()
+    return {
+      claude: claudeAccounts.listAccounts(),
+      codex: codexAccounts.listAccounts(),
+      rateLimits: rateLimits.getState()
+    }
+  }
+
+  // Why: RateLimitService polls only when the Electron window is visible AND
+  // focused, and the inactive-account caches fill lazily when the user opens
+  // the desktop AccountsPane. Mobile has neither trigger, so without this the
+  // phone shows 0% / "—" against a backgrounded desktop. Errors swallowed
+  // because partial usage is still useful for the rest of the snapshot.
+  async refreshAccountsForMobile(): Promise<void> {
+    const { rateLimits } = this.requireAccountServices()
+    await Promise.allSettled([
+      rateLimits.refresh(),
+      rateLimits.fetchInactiveClaudeAccountsOnOpen(),
+      rateLimits.fetchInactiveCodexAccountsOnOpen()
+    ])
+  }
+
+  selectClaudeAccount(accountId: string | null): Promise<ClaudeRateLimitAccountsState> {
+    return this.requireAccountServices().claudeAccounts.selectAccount(accountId)
+  }
+
+  selectCodexAccount(accountId: string | null): Promise<CodexRateLimitAccountsState> {
+    return this.requireAccountServices().codexAccounts.selectAccount(accountId)
+  }
+
+  removeClaudeAccount(accountId: string): Promise<ClaudeRateLimitAccountsState> {
+    return this.requireAccountServices().claudeAccounts.removeAccount(accountId)
+  }
+
+  removeCodexAccount(accountId: string): Promise<CodexRateLimitAccountsState> {
+    return this.requireAccountServices().codexAccounts.removeAccount(accountId)
+  }
+
+  // Why: rate-limit polling fires every 5 minutes and on account switch.
+  // Mobile clients subscribe to receive a fresh AccountsSnapshot whenever
+  // RateLimitService pushes new usage data, mirroring the existing
+  // `rateLimits:update` IPC channel desktop already uses.
+  onAccountsChanged(listener: (snapshot: AccountsSnapshot) => void): () => void {
+    const services = this.requireAccountServices()
+    return services.rateLimits.onStateChange(() => {
+      listener({
+        claude: services.claudeAccounts.listAccounts(),
+        codex: services.codexAccounts.listAccounts(),
+        rateLimits: services.rateLimits.getState()
+      })
+    })
+  }
+
   // ─── Mobile Fit Override Management ─────────────────────────
 
   resizeForClient(
@@ -945,11 +1356,13 @@ export class OrcaRuntimeService {
       }
       this.resizeHeadlessTerminal(ptyId, clampedCols, clampedRows)
 
-      console.log(
-        `[mobile-fit] handleMobileSubscribe notifier=${!!this.notifier} ptyId=${ptyId} mode=mobile-fit cols=${clampedCols} rows=${clampedRows}`
-      )
       this.notifier?.terminalFitOverrideChanged(ptyId, 'mobile-fit', clampedCols, clampedRows)
 
+      // Why: mobile-fit via resizeForClient is a deliberate mobile action;
+      // the actor takes the floor. mobileTookFloor updates the actor's
+      // lastActedAt and re-applies phone-fit if previously in desktop mode.
+      this.mobileTookFloor(ptyId, clientId)
+
       return {
         cols: clampedCols,
         rows: clampedRows,
@@ -1024,18 +1437,68 @@ export class OrcaRuntimeService {
         this.pendingRestoreTimers.delete(ptyId)
       }
     }
+    // Why: if the disconnecting client was in soft-leave grace, the grace
+    // is meaningless now (the client is gone for real). Promote each
+    // matching grace into immediate finalization: restore PTY dims to the
+    // captured baseline, drop driver to idle, and clear fit overrides.
+    // Without this, a phone that exited the screen (router.back → WS
+    // close) would leave the PTY stuck at phone dims forever — the soft
+    // grace held the inner-map empty so the mobileSubscribers loop below
+    // can't see it, and the 300ms restore timer could mis-fire after the
+    // grace if the PTY had already been mutated.
+    for (const [ptyId, soft] of this.pendingSoftLeavers) {
+      if (soft.clientId !== clientId) {
+        continue
+      }
+      clearTimeout(soft.timer)
+      this.pendingSoftLeavers.delete(ptyId)
+
+      // Cancel any in-flight 300ms restore timer too — we'll do it now.
+      const pending = this.pendingRestoreTimers.get(ptyId)
+      if (pending) {
+        clearTimeout(pending.timer)
+        this.pendingRestoreTimers.delete(ptyId)
+      }
+
+      const mode = this.mobileDisplayModes.get(ptyId) ?? 'auto'
+      const { previousCols, previousRows, wasResizedToPhone } = soft.record
+      if (mode === 'auto' && wasResizedToPhone) {
+        const fallback = this.lastRendererSizes.get(ptyId)
+        const cols = previousCols ?? fallback?.cols ?? null
+        const rows = previousRows ?? fallback?.rows ?? null
+        if (cols != null && rows != null) {
+          this.ptyController?.resize?.(ptyId, cols, rows)
+          this.resizeHeadlessTerminal(ptyId, cols, rows)
+        }
+        this.lastRendererSizes.delete(ptyId)
+        this.suppressResizesForMs(500)
+        this.terminalFitOverrides.delete(ptyId)
+        this.notifier?.terminalFitOverrideChanged(ptyId, 'desktop-fit', cols ?? 0, rows ?? 0)
+        this.notifyFitOverrideListeners(ptyId, 'desktop-fit', cols ?? 0, rows ?? 0)
+      }
+      this.setDriver(ptyId, { kind: 'idle' })
+    }
 
     // Immediately restore PTYs that this client had phone-fitted (no debounce —
     // client is gone, no point waiting for a re-subscribe that won't come).
-    for (const [ptyId, subscriber] of this.mobileSubscribers) {
-      if (subscriber.clientId !== clientId) {
+    // With the multi-mobile rekey, only the disconnecting client's record is
+    // removed from the inner map; peer mobile clients keep the floor and the
+    // banner stays mounted.
+    const ptysWithSurvivingPeers: string[] = []
+    for (const [ptyId, inner] of this.mobileSubscribers) {
+      const subscriber = inner.get(clientId)
+      if (!subscriber) {
+        continue
+      }
+      const wasResizedToPhone = subscriber.wasResizedToPhone
+      const { previousCols, previousRows } = subscriber
+      inner.delete(clientId)
+      if (inner.size > 0) {
+        ptysWithSurvivingPeers.push(ptyId)
         continue
       }
-
       this.mobileSubscribers.delete(ptyId)
-
-      if (subscriber.wasResizedToPhone) {
-        const { previousCols, previousRows } = subscriber
+      if (wasResizedToPhone) {
         if (previousCols != null && previousRows != null) {
           this.ptyController?.resize?.(ptyId, previousCols, previousRows)
           this.resizeHeadlessTerminal(ptyId, previousCols, previousRows)
@@ -1049,6 +1512,21 @@ export class OrcaRuntimeService {
         )
         this.notifyFitOverrideListeners(ptyId, 'desktop-fit', previousCols ?? 0, previousRows ?? 0)
       }
+      this.setDriver(ptyId, { kind: 'idle' })
+    }
+    // Why: if peers survived but the disconnecting client was the active
+    // driver, re-elect the most-recent surviving subscriber as the driver
+    // and re-fit if needed. This keeps the lock/dim-selection invariant.
+    for (const ptyId of ptysWithSurvivingPeers) {
+      const driver = this.getDriver(ptyId)
+      if (driver.kind === 'mobile' && driver.clientId === clientId) {
+        const inner = this.mobileSubscribers.get(ptyId)
+        const next = inner ? this.pickMostRecentActor(inner) : null
+        if (next) {
+          this.setDriver(ptyId, { kind: 'mobile', clientId: next.clientId })
+          this.applyMobileDisplayMode(ptyId)
+        }
+      }
     }
 
     // Legacy cleanup for any terminalFitOverrides not covered by mobileSubscribers
@@ -1077,12 +1555,25 @@ export class OrcaRuntimeService {
       clearTimeout(pendingRestore.timer)
       this.pendingRestoreTimers.delete(ptyId)
     }
+    const pendingSoft = this.pendingSoftLeavers.get(ptyId)
+    if (pendingSoft) {
+      clearTimeout(pendingSoft.timer)
+      this.pendingSoftLeavers.delete(ptyId)
+    }
 
     if (this.terminalFitOverrides.has(ptyId)) {
       this.terminalFitOverrides.delete(ptyId)
       this.notifier?.terminalFitOverrideChanged(ptyId, 'desktop-fit', 0, 0)
       this.notifyFitOverrideListeners(ptyId, 'desktop-fit', 0, 0)
     }
+    // Why: clear driver state and notify the renderer so any lock banner on
+    // this dead pane unmounts. Without this, the pane shows a stuck banner
+    // until tab teardown, and `getDriver(deadPtyId)` would keep returning a
+    // stale `mobile{X}` to any caller that hasn't yet seen the exit IPC.
+    if (this.currentDriver.has(ptyId)) {
+      this.currentDriver.delete(ptyId)
+      this.notifier?.terminalDriverChanged(ptyId, { kind: 'idle' })
+    }
     this.disposeHeadlessTerminal(ptyId)
     this.agentDetector?.onExit(ptyId)
     const pty = this.ptysById.get(ptyId)
@@ -1103,6 +1594,191 @@ export class OrcaRuntimeService {
     }
   }
 
+  // ─── Driver state (mobile-presence lock) ──────────────────────────
+  //
+  // See docs/mobile-presence-lock.md.
+
+  getDriver(ptyId: string): DriverState {
+    return this.currentDriver.get(ptyId) ?? { kind: 'idle' }
+  }
+
+  private setDriver(ptyId: string, next: DriverState): void {
+    const prev = this.getDriver(ptyId)
+    if (prev.kind === next.kind) {
+      if (prev.kind === 'mobile' && next.kind === 'mobile' && prev.clientId === next.clientId) {
+        return
+      }
+      if (prev.kind !== 'mobile' && next.kind !== 'mobile') {
+        return
+      }
+    }
+    if (next.kind === 'idle') {
+      this.currentDriver.delete(ptyId)
+    } else {
+      this.currentDriver.set(ptyId, next)
+    }
+    this.notifier?.terminalDriverChanged(ptyId, next)
+  }
+
+  // Why: invoked from mobile RPC method handlers (terminal.send / setDisplayMode /
+  // resizeForClient / fresh subscribe with auto/phone). Records the actor as
+  // the most recent mobile driver and re-applies phone-fit if we were previously
+  // in `desktop` mode (mobile reclaims a take-back). Mobile-to-mobile hand-offs
+  // are no-ops for resize.
+  mobileTookFloor(ptyId: string, clientId: string): void {
+    const inner = this.mobileSubscribers.get(ptyId)
+    const sub = inner?.get(clientId)
+    if (sub) {
+      sub.lastActedAt = Date.now()
+    }
+    const prev = this.getDriver(ptyId)
+    const currentMode = this.mobileDisplayModes.get(ptyId)
+    // Why: a deliberate mobile action implies mobile is resuming control.
+    // If the display mode is currently 'desktop' (set by an earlier
+    // take-back), flip it back to 'auto' and re-apply so phone-fit takes
+    // hold again. Without flipping the mode, applyMobileDisplayMode would
+    // take the desktop branch and leave the PTY at desktop dims while the
+    // driver says `mobile`. The same path also covers the case where the
+    // driver flipped to `desktop` and we're returning to mobile control.
+    // See docs/mobile-presence-lock.md.
+    if (prev.kind === 'desktop' || currentMode === 'desktop') {
+      if (currentMode === 'desktop' || currentMode === undefined) {
+        this.mobileDisplayModes.set(ptyId, 'auto')
+      }
+      this.applyMobileDisplayMode(ptyId)
+    }
+    this.setDriver(ptyId, { kind: 'mobile', clientId })
+  }
+
+  // Why: in-place viewport update on the existing mobile subscription —
+  // used when the mobile keyboard opens/closes and shrinks/grows the
+  // visible terminal area. We refresh the subscriber's viewport, re-fit
+  // the PTY to the new dims, and emit a 'resized' event so the mobile
+  // xterm reinits inline at the new dims without re-subscribing. This
+  // avoids the unsubscribe → resubscribe cycle which would (a) flash the
+  // desktop lock banner during the brief idle gap and (b) cause the new
+  // subscribe to capture the already-phone-fitted PTY size as its
+  // restore baseline (stuck-dim bug on later disconnect).
+  // No-op when the client isn't actually subscribed to this PTY.
+  updateMobileViewport(
+    ptyId: string,
+    clientId: string,
+    viewport: { cols: number; rows: number }
+  ): boolean {
+    const inner = this.mobileSubscribers.get(ptyId)
+    const sub = inner?.get(clientId)
+    if (!sub) {
+      return false
+    }
+    sub.viewport = viewport
+    sub.lastActedAt = Date.now()
+
+    const mode = this.mobileDisplayModes.get(ptyId) ?? 'auto'
+    if (mode === 'desktop') {
+      // Watching at desktop dims — viewport is informational only.
+      return true
+    }
+    // Drive PTY dims by the most-recent-actor (just updated to this client).
+    const winner = this.pickMostRecentActor(inner!)
+    if (!winner) {
+      return false
+    }
+    const winnerSub = inner!.get(winner.clientId)
+    const driveViewport = winnerSub?.viewport ?? viewport
+    const clampedCols = Math.max(20, Math.min(240, Math.round(driveViewport.cols)))
+    const clampedRows = Math.max(8, Math.min(120, Math.round(driveViewport.rows)))
+
+    const currentSize = this.getTerminalSize(ptyId)
+    const alreadyAtTarget = currentSize?.cols === clampedCols && currentSize?.rows === clampedRows
+    if (!alreadyAtTarget) {
+      this.ptyController?.resize?.(ptyId, clampedCols, clampedRows)
+      this.resizeHeadlessTerminal(ptyId, clampedCols, clampedRows)
+    }
+
+    sub.wasResizedToPhone = true
+    this.terminalFitOverrides.set(ptyId, {
+      mode: 'mobile-fit',
+      cols: clampedCols,
+      rows: clampedRows,
+      previousCols: sub.previousCols,
+      previousRows: sub.previousRows,
+      updatedAt: Date.now(),
+      clientId
+    })
+    this.notifier?.terminalFitOverrideChanged(ptyId, 'mobile-fit', clampedCols, clampedRows)
+
+    // Why: emit a 'resized' event on the mobile subscription stream so the
+    // mobile xterm reinits inline at the new dims — same shape as a
+    // setDisplayMode-triggered resize, so the existing client-side handler
+    // path applies without changes.
+    this.notifyTerminalResize(ptyId, {
+      cols: clampedCols,
+      rows: clampedRows,
+      displayMode: mode,
+      reason: 'viewport-update'
+    })
+
+    // The driver is already mobile{this client} when we got here; refresh it
+    // to update lastActedAt-based ordering on later actor selection.
+    this.setDriver(ptyId, { kind: 'mobile', clientId })
+    return true
+  }
+
+  // Why: invoked from `runtime:restoreTerminalFit` IPC (the desktop "Take
+  // back" button). Forces the PTY back to desktop dims and flips the driver
+  // to `desktop`, suppressing further mobile-driven dim changes until a
+  // mobile actor takes the floor again.
+  reclaimTerminalForDesktop(ptyId: string): boolean {
+    if (!this.isMobileSubscriberActive(ptyId)) {
+      return false
+    }
+    this.setMobileDisplayMode(ptyId, 'desktop')
+    this.applyMobileDisplayMode(ptyId)
+    this.setDriver(ptyId, { kind: 'desktop' })
+    return true
+  }
+
+  // Why: with multiple subscribers, the active phone-fit dims follow the
+  // most recent mobile actor (argmax(lastActedAt)). See
+  // docs/mobile-presence-lock.md "Active phone-fit dim selection".
+  private pickMostRecentActor(
+    inner: Map<string, { clientId: string; lastActedAt: number }>
+  ): { clientId: string; lastActedAt: number } | null {
+    let best: { clientId: string; lastActedAt: number } | null = null
+    for (const sub of inner.values()) {
+      if (best === null || sub.lastActedAt > best.lastActedAt) {
+        best = sub
+      }
+    }
+    return best
+  }
+
+  // Why: restore-target selection on last-subscriber-leaves picks the
+  // earliest-by-subscribe-time subscriber AMONG those with non-null
+  // previousCols/Rows. Desktop-mode joins carry null and are skipped — they
+  // never captured pre-fit dims by design.
+  private pickEarliestRestoreTarget(
+    inner: Map<
+      string,
+      { subscribedAt: number; previousCols: number | null; previousRows: number | null }
+    >
+  ): { previousCols: number; previousRows: number } | null {
+    let best: { subscribedAt: number; previousCols: number; previousRows: number } | null = null
+    for (const sub of inner.values()) {
+      if (sub.previousCols == null || sub.previousRows == null) {
+        continue
+      }
+      if (best === null || sub.subscribedAt < best.subscribedAt) {
+        best = {
+          subscribedAt: sub.subscribedAt,
+          previousCols: sub.previousCols,
+          previousRows: sub.previousRows
+        }
+      }
+    }
+    return best ? { previousCols: best.previousCols, previousRows: best.previousRows } : null
+  }
+
   // ─── Server-Authoritative Mobile Display Mode ─────────────────────
 
   setMobileDisplayMode(ptyId: string, mode: 'auto' | 'phone' | 'desktop'): void {
@@ -1118,13 +1794,23 @@ export class OrcaRuntimeService {
   }
 
   isMobileSubscriberActive(ptyId: string): boolean {
-    return this.mobileSubscribers.has(ptyId)
+    const inner = this.mobileSubscribers.get(ptyId)
+    return inner !== undefined && inner.size > 0
   }
 
   // Why: server-side auto-fit on mobile subscribe. The runtime is the single
   // source of truth — the mobile client just passes its viewport and the runtime
   // decides whether to resize. This eliminates the measure→RPC→resubscribe
   // pipeline that caused race conditions.
+  //
+  // Multi-mobile keying: each subscriber lives in `mobileSubscribers[ptyId]`'s
+  // inner map under its own clientId. Phone B subscribing does not overwrite
+  // phone A's record — both stay until each unsubscribes.
+  //
+  // Subscribe-in-desktop-mode rule: a subscribe with displayMode='desktop' is
+  // a passive watch; it does NOT take the floor. The driver remains
+  // `idle`/`desktop`. The lock banner is reserved for actual mobile
+  // interaction (input/resize/setDisplayMode/auto-or-phone subscribe).
   handleMobileSubscribe(
     ptyId: string,
     clientId: string,
@@ -1135,51 +1821,111 @@ export class OrcaRuntimeService {
       return false
     }
 
-    // Why: only cancel the restore timer for THIS ptyId (re-subscribe case).
-    // Other terminals' timers must fire so their banners clear on the desktop.
+    // Why: cancel ALL pending restore timers for this ptyId on any new
+    // subscribe — the timer is keyed by ptyId+old-clientId but with the
+    // multi-mobile rekey, "any new subscriber" supersedes "any old client's
+    // restore". Without this, A unsub → B sub within 300ms could fire A's
+    // timer and snap PTY to desktop dims while B is meant to drive.
     const pendingRestore = this.pendingRestoreTimers.get(ptyId)
-    if (pendingRestore && pendingRestore.clientId === clientId) {
+    if (pendingRestore) {
       clearTimeout(pendingRestore.timer)
       this.pendingRestoreTimers.delete(ptyId)
     }
 
+    // Why: resubscribe-grace honor. If the same client just unsubscribed
+    // within the soft-leave window, restore its prior record (preserving
+    // previousCols/Rows so we don't capture an already-phone-fitted PTY
+    // size as the new baseline). The driver state was kept at
+    // mobile{clientId} during the window, so no banner flash occurred.
+    const softLeaver = this.pendingSoftLeavers.get(ptyId)
+    if (softLeaver && softLeaver.clientId === clientId) {
+      clearTimeout(softLeaver.timer)
+      this.pendingSoftLeavers.delete(ptyId)
+      let inner = this.mobileSubscribers.get(ptyId)
+      if (!inner) {
+        inner = new Map()
+        this.mobileSubscribers.set(ptyId, inner)
+      }
+      inner.set(clientId, {
+        ...softLeaver.record,
+        // Refresh viewport from the new subscribe payload — the keyboard
+        // state may have changed during the window.
+        viewport,
+        lastActedAt: Date.now()
+      })
+      // The driver was already mobile{clientId}; refresh to update
+      // listener wiring (and re-emit, harmless if unchanged).
+      this.setDriver(ptyId, { kind: 'mobile', clientId })
+      // If display-mode is auto/phone, reapply the fit at the new viewport
+      // so a keyboard show/hide that resubscribes (older clients) still
+      // updates dims correctly. updateMobileViewport is the preferred path
+      // and avoids the unsubscribe → subscribe cycle entirely.
+      if (mode !== 'desktop') {
+        this.applyMobileDisplayMode(ptyId)
+      }
+      return true
+    }
+
+    let inner = this.mobileSubscribers.get(ptyId)
+    if (!inner) {
+      inner = new Map()
+      this.mobileSubscribers.set(ptyId, inner)
+    }
+
     // Why: prefer lastRendererSizes (the actual pane geometry reported by the
     // desktop renderer's safeFit via pty:resize IPC) over getTerminalSize (the
     // server-side PTY size, which may be stale — e.g. 214 full-width when the
     // pane is actually in a split at ~105). Fall back to existing subscriber's
     // previousCols (re-subscribe case) then currentSize (first subscribe).
-    const existing = this.mobileSubscribers.get(ptyId)
+    //
+    // Multi-mobile: if an existing subscriber on this PTY is already
+    // phone-fitted, the current PTY size is NOT a valid restore baseline for
+    // a *new* subscriber — it would point to a phone-fit dim, not the
+    // pre-mobile desktop size. Set previousCols/Rows to null so the new
+    // joiner is skipped from earliest-restore selection; the original
+    // subscriber's captured baseline remains the source of truth. See
+    // docs/mobile-presence-lock.md.
+    const existing = inner.get(clientId)
+    const someoneAlreadyFitted = [...inner.values()].some((s) => s.wasResizedToPhone)
     const currentSize = this.getTerminalSize(ptyId)
     const rendererSize = this.lastRendererSizes.get(ptyId)
-    const previousCols = existing?.previousCols ?? rendererSize?.cols ?? currentSize?.cols ?? null
-    const previousRows = existing?.previousRows ?? rendererSize?.rows ?? currentSize?.rows ?? null
+    const previousCols =
+      existing?.previousCols ??
+      (someoneAlreadyFitted ? null : (rendererSize?.cols ?? currentSize?.cols ?? null))
+    const previousRows =
+      existing?.previousRows ??
+      (someoneAlreadyFitted ? null : (rendererSize?.rows ?? currentSize?.rows ?? null))
+    const now = Date.now()
+    const subscribedAt = existing?.subscribedAt ?? now
 
-    // Why: always register the subscriber so applyMobileDisplayMode can find
-    // the viewport when the user later toggles from desktop to auto/phone.
-    // Without this, toggling to auto after subscribing in desktop mode sees
-    // hasSubscriber=false and can't perform the phone resize.
     if (mode === 'desktop') {
       // Why: set previousCols/Rows to null so we don't capture a stale PTY
       // size that may not match the actual pane geometry (e.g. 214 when the
       // pane is in a split at 105). When the user later toggles to auto/phone,
       // handleMobileSubscribe will capture currentSize at that point, which
       // will be correct because safeFit has had time to adjust the PTY.
-      this.mobileSubscribers.set(ptyId, {
+      inner.set(clientId, {
         clientId,
         viewport,
         wasResizedToPhone: false,
         previousCols: null,
-        previousRows: null
+        previousRows: null,
+        subscribedAt,
+        lastActedAt: now
       })
+      // Subscribe-in-desktop-mode is passive: leave driver at idle/desktop.
+      // Do not transition to mobile{clientId}.
       return false
     }
 
-    this.mobileSubscribers.set(ptyId, {
+    inner.set(clientId, {
       clientId,
       viewport,
       wasResizedToPhone: true,
       previousCols,
-      previousRows
+      previousRows,
+      subscribedAt,
+      lastActedAt: now
     })
 
     const clampedCols = Math.max(20, Math.min(240, Math.round(viewport.cols)))
@@ -1206,31 +1952,136 @@ export class OrcaRuntimeService {
       clientId
     })
 
+    // Subscribe-fresh with auto/phone mode counts as "take the floor".
+    this.setDriver(ptyId, { kind: 'mobile', clientId })
+
     return true
   }
 
   // Why: delayed restore prevents resize thrashing during rapid tab switches.
   // The 300ms debounce means only the final tab triggers a PTY restore;
   // intermediate terminals keep their current dims harmlessly.
+  //
+  // Multi-mobile: only the last subscriber leaving for this ptyId triggers
+  // restore + driver=idle. Peer mobile clients still on the inner map keep
+  // the lock banner mounted; if the disconnecting client was the active
+  // driver, we re-elect the most-recent surviving subscriber.
   handleMobileUnsubscribe(ptyId: string, clientId: string): void {
-    const subscriber = this.mobileSubscribers.get(ptyId)
-    if (!subscriber || subscriber.clientId !== clientId) {
+    const inner = this.mobileSubscribers.get(ptyId)
+    if (!inner) {
+      return
+    }
+    const subscriber = inner.get(clientId)
+    if (!subscriber) {
+      return
+    }
+    const wasResizedToPhone = subscriber.wasResizedToPhone
+
+    // Why: snapshot the earliest-by-subscribe-time restore target BEFORE
+    // mutating the inner map. If the disconnecting client is the original
+    // baseline-holder, that information must survive into the last-leaver
+    // restore path even after their record is deleted. See
+    // docs/mobile-presence-lock.md "Restore-target selection".
+    const restoreTargetSnapshot = this.pickEarliestRestoreTarget(inner)
+    inner.delete(clientId)
+
+    if (inner.size > 0) {
+      // Why: if the leaving client was the only one with a non-null restore
+      // baseline (typical when peer joiners subscribed against an
+      // already-phone-fitted PTY and got null prevCols), donate the baseline
+      // to the earliest surviving subscriber so a future last-leaver can
+      // still restore correctly. Without this, A leaves first, B leaves
+      // last with null prevCols → no restore fires. See
+      // docs/mobile-presence-lock.md.
+      if (
+        subscriber.previousCols != null &&
+        subscriber.previousRows != null &&
+        !this.pickEarliestRestoreTarget(inner)
+      ) {
+        let earliestSurvivor: { clientId: string; subscribedAt: number } | null = null
+        for (const sub of inner.values()) {
+          if (earliestSurvivor === null || sub.subscribedAt < earliestSurvivor.subscribedAt) {
+            earliestSurvivor = { clientId: sub.clientId, subscribedAt: sub.subscribedAt }
+          }
+        }
+        if (earliestSurvivor) {
+          const heir = inner.get(earliestSurvivor.clientId)
+          if (heir) {
+            heir.previousCols = subscriber.previousCols
+            heir.previousRows = subscriber.previousRows
+          }
+        }
+      }
+      // Peers still on the line. If the disconnecting client was the active
+      // mobile driver, re-elect the most-recent surviving subscriber so the
+      // banner remains correct and active phone-fit dims follow them.
+      const driver = this.getDriver(ptyId)
+      if (driver.kind === 'mobile' && driver.clientId === clientId) {
+        const next = this.pickMostRecentActor(inner)
+        if (next) {
+          this.setDriver(ptyId, { kind: 'mobile', clientId: next.clientId })
+          this.applyMobileDisplayMode(ptyId)
+        }
+      }
       return
     }
 
-    const mode = this.mobileDisplayModes.get(ptyId) ?? 'auto'
+    // Last subscriber leaving — clean up.
     this.mobileSubscribers.delete(ptyId)
+    const mode = this.mobileDisplayModes.get(ptyId) ?? 'auto'
 
-    if (mode === 'auto' && subscriber.wasResizedToPhone) {
+    // Why: resubscribe-grace. Hold the driver=mobile{clientId} state and
+    // the leaving subscriber's record for ~250ms. If the same client
+    // re-subscribes in that window, handleMobileSubscribe cancels the
+    // pending-soft-leaver and re-inserts the record (preserving
+    // previousCols and avoiding a desktop-banner flash). Otherwise the
+    // grace timer fires, sets driver=idle, and lets the existing 300ms
+    // restore debounce (kept below) run as before.
+    const SOFT_LEAVE_GRACE_MS = 250
+    const existingSoft = this.pendingSoftLeavers.get(ptyId)
+    if (existingSoft) {
+      clearTimeout(existingSoft.timer)
+      this.pendingSoftLeavers.delete(ptyId)
+    }
+    const softTimer = setTimeout(() => {
+      this.pendingSoftLeavers.delete(ptyId)
+      // Why: only flip to idle if no peer has reclaimed in the meantime.
+      if (!this.mobileSubscribers.has(ptyId)) {
+        this.setDriver(ptyId, { kind: 'idle' })
+      }
+    }, SOFT_LEAVE_GRACE_MS)
+    this.pendingSoftLeavers.set(ptyId, {
+      clientId,
+      timer: softTimer,
+      record: {
+        clientId: subscriber.clientId,
+        viewport: subscriber.viewport,
+        wasResizedToPhone: subscriber.wasResizedToPhone,
+        previousCols: subscriber.previousCols,
+        previousRows: subscriber.previousRows,
+        subscribedAt: subscriber.subscribedAt,
+        lastActedAt: subscriber.lastActedAt
+      }
+    })
+
+    if (mode === 'auto' && wasResizedToPhone) {
       const existing = this.pendingRestoreTimers.get(ptyId)
       if (existing) {
         clearTimeout(existing.timer)
       }
 
-      const { previousCols, previousRows } = subscriber
+      // Restore target: earliest-by-subscribe-time among non-null
+      // previousCols/Rows captured BEFORE deletion. Falls back to the
+      // disconnecting subscriber's own dims and finally lastRendererSizes
+      // (matches the existing first-insert capture path).
+      const fallback = this.lastRendererSizes.get(ptyId)
+      const previousCols =
+        restoreTargetSnapshot?.previousCols ?? subscriber.previousCols ?? fallback?.cols ?? null
+      const previousRows =
+        restoreTargetSnapshot?.previousRows ?? subscriber.previousRows ?? fallback?.rows ?? null
       const timer = setTimeout(() => {
         this.pendingRestoreTimers.delete(ptyId)
-        if (this.mobileSubscribers.has(ptyId)) {
+        if (this.isMobileSubscriberActive(ptyId)) {
           return
         }
         if (previousCols != null && previousRows != null) {
@@ -1258,34 +2109,49 @@ export class OrcaRuntimeService {
   // Why: called when mode changes via terminal.setDisplayMode. Applies the
   // mode change immediately if there's an active subscriber, and emits a
   // 'resized' event so the mobile client can reinitialize xterm inline.
+  //
+  // Multi-mobile: the most recent mobile actor's viewport drives the active
+  // phone-fit dims. The earliest-by-subscribe-time subscriber's
+  // previousCols/Rows drive the desktop-restore target.
   applyMobileDisplayMode(ptyId: string): void {
     const mode = this.mobileDisplayModes.get(ptyId) ?? 'auto'
-    const subscriber = this.mobileSubscribers.get(ptyId)
+    const inner = this.mobileSubscribers.get(ptyId)
+    const subscriber = inner ? this.pickMostRecentActor(inner) : null
+    const subscriberRecord = subscriber && inner ? inner.get(subscriber.clientId) : null
 
     if (mode === 'desktop') {
-      if (subscriber?.wasResizedToPhone) {
-        const { previousCols, previousRows } = subscriber
-        if (previousCols != null && previousRows != null) {
-          this.ptyController?.resize?.(ptyId, previousCols, previousRows)
-          this.resizeHeadlessTerminal(ptyId, previousCols, previousRows)
+      // Find the first subscriber (any clientId) that was previously
+      // phone-fitted, and reset its flag. The desktop-restore target uses
+      // earliest-by-subscribe-time among non-null prevCols/Rows.
+      if (inner) {
+        const restore = this.pickEarliestRestoreTarget(inner)
+        let anyWasResized = false
+        for (const sub of inner.values()) {
+          if (sub.wasResizedToPhone) {
+            anyWasResized = true
+            sub.wasResizedToPhone = false
+          }
+        }
+        if (anyWasResized && restore) {
+          this.ptyController?.resize?.(ptyId, restore.previousCols, restore.previousRows)
+          this.resizeHeadlessTerminal(ptyId, restore.previousCols, restore.previousRows)
+          // Why: clear stale renderer size so the next mobile subscribe falls
+          // through to currentSize (which is correct after the server restore).
+          // Without this, a polluted 214 from a prior collateral safeFit cascade
+          // persists in lastRendererSizes and gets used as previousCols.
+          this.lastRendererSizes.delete(ptyId)
+          // Why: 500ms not 200ms — the desktop renderer's collateral safeFit
+          // cascade (IPC → React re-render → rAF → DOM measure → IPC back)
+          // takes ~360ms to propagate to background-tab terminals.
+          this.suppressResizesForMs(500)
+          this.terminalFitOverrides.delete(ptyId)
+          this.notifier?.terminalFitOverrideChanged(
+            ptyId,
+            'desktop-fit',
+            restore.previousCols,
+            restore.previousRows
+          )
         }
-        subscriber.wasResizedToPhone = false
-        // Why: clear stale renderer size so the next mobile subscribe falls
-        // through to currentSize (which is correct after the server restore).
-        // Without this, a polluted 214 from a prior collateral safeFit cascade
-        // persists in lastRendererSizes and gets used as previousCols.
-        this.lastRendererSizes.delete(ptyId)
-        // Why: 500ms not 200ms — the desktop renderer's collateral safeFit
-        // cascade (IPC → React re-render → rAF → DOM measure → IPC back)
-        // takes ~360ms to propagate to background-tab terminals.
-        this.suppressResizesForMs(500)
-        this.terminalFitOverrides.delete(ptyId)
-        this.notifier?.terminalFitOverrideChanged(
-          ptyId,
-          'desktop-fit',
-          previousCols ?? 0,
-          previousRows ?? 0
-        )
       }
       const size = this.getTerminalSize(ptyId)
       this.notifyTerminalResize(ptyId, {
@@ -1295,10 +2161,10 @@ export class OrcaRuntimeService {
         reason: 'mode-change'
       })
     } else if (mode === 'phone' || mode === 'auto') {
-      if (subscriber && !subscriber.wasResizedToPhone) {
-        const viewport = subscriber.viewport
+      if (subscriberRecord && !subscriberRecord.wasResizedToPhone) {
+        const viewport = subscriberRecord.viewport
         if (viewport) {
-          this.handleMobileSubscribe(ptyId, subscriber.clientId, viewport)
+          this.handleMobileSubscribe(ptyId, subscriberRecord.clientId, viewport)
         }
       }
       // Why: always emit the mode change even when no resize occurred (e.g.
@@ -1322,13 +2188,18 @@ export class OrcaRuntimeService {
   onExternalPtyResize(ptyId: string, cols: number, rows: number): void {
     this.lastRendererSizes.set(ptyId, { cols, rows })
 
-    const subscriber = this.mobileSubscribers.get(ptyId)
-    if (!subscriber) {
+    const inner = this.mobileSubscribers.get(ptyId)
+    if (!inner) {
       return
     }
-    if (!subscriber.wasResizedToPhone) {
-      subscriber.previousCols = cols
-      subscriber.previousRows = rows
+    // Capture the renderer-reported size as the next-restore target on any
+    // subscriber that hasn't yet been phone-fitted. Subscribers in
+    // wasResizedToPhone state already have a captured pre-fit baseline.
+    for (const sub of inner.values()) {
+      if (!sub.wasResizedToPhone) {
+        sub.previousCols = cols
+        sub.previousRows = rows
+      }
     }
   }
 
@@ -2099,8 +2970,14 @@ export class OrcaRuntimeService {
     }
 
     const worktreeId = `${repo.id}::${created.path}`
+    const now = Date.now()
     const meta = this.store.setWorktreeMeta(worktreeId, {
-      lastActivityAt: Date.now(),
+      lastActivityAt: now,
+      // See createRemoteWorktree: createdAt grants the new worktree a grace
+      // window in Recent sort so ambient PTY bumps in OTHER worktrees can't
+      // 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 }
         : {}),
@@ -3747,7 +4624,24 @@ export class OrcaRuntimeService {
 
   async browserTabList(params: { worktree?: string }): Promise<BrowserTabListResult> {
     const worktreeId = await this.resolveBrowserWorktreeId(params.worktree)
-    return this.requireAgentBrowserBridge().tabList(worktreeId)
+    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(
@@ -4399,51 +5293,17 @@ export class OrcaRuntimeService {
   async browserTabCreate(params: {
     url?: string
     worktree?: string
+    profileId?: string
   }): Promise<{ browserPageId: string }> {
-    const win = this.getAuthoritativeWindow()
-    const requestId = randomUUID()
     const url = params.url ?? 'about:blank'
-
-    // Why: the renderer's Zustand store keys browser tabs by worktreeId in
-    // "repoId::path" format. The CLI sends a selector (e.g. "path:/Users/...").
-    // Resolve it here so the renderer receives the store-compatible ID.
     const worktreeId = params.worktree
       ? (await this.resolveWorktreeSelector(params.worktree)).id
       : undefined
-
-    // Why: browser webviews only mount when their worktree is active in the UI.
-    // Switch to it before creating the tab so the webview attaches immediately.
-    if (worktreeId) {
-      await this.ensureBrowserWorktreeActive(worktreeId)
-    }
-
-    // Why: tab creation is a renderer-side Zustand store operation. The main process
-    // sends a request, the renderer creates the tab and replies with the workspace ID
-    // (which is the browserPageId used by registerGuest and the bridge).
-    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 })
-    })
+    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
@@ -4484,6 +5344,160 @@ export class OrcaRuntimeService {
     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')
+    }
+    const profile = browserSessionRegistry.getProfile(params.profileId)
+    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
@@ -4556,6 +5570,84 @@ export class OrcaRuntimeService {
     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 getAuthoritativeWindow(): BrowserWindow {
     if (this.authoritativeWindowId === null) {
       throw new Error('No renderer window available')
@@ -4769,7 +5861,14 @@ function getLeafWorktreeStatus(
   leaf: RuntimeLeafRecord,
   tabTitle: string | null
 ): RuntimeWorktreeStatus {
-  const detected = leaf.lastAgentStatus ?? detectAgentStatusFromTitle(leaf.title ?? tabTitle ?? '')
+  // Why: recompute from the live title each call so worktree.ps mirrors what
+  // the desktop sidebar's getWorktreeStatus does (no sticky state). Prefer
+  // the runtime-tracked OSC title (covers daemon-hosted terminals) over the
+  // renderer-pushed leaf.title and the tab title. Falling back to
+  // lastAgentStatus only when no title is available preserves a sensible
+  // signal for very fresh leaves before any title has been observed.
+  const liveTitle = leaf.lastOscTitle ?? leaf.title ?? tabTitle ?? ''
+  const detected = liveTitle ? detectAgentStatusFromTitle(liveTitle) : leaf.lastAgentStatus
   if (detected === 'permission') {
     return 'permission'
   }
diff --git a/src/main/runtime/rpc/core.ts b/src/main/runtime/rpc/core.ts
index 9c6eab7212a..0340561938e 100644
--- a/src/main/runtime/rpc/core.ts
+++ b/src/main/runtime/rpc/core.ts
@@ -46,6 +46,12 @@ export type RpcContext = {
   // runtime-rpc transport (direct in-process callers don't need it).
   // See design doc §3.1 counter-lifecycle.
   signal?: AbortSignal
+  // Why: streaming handlers (notifications/accounts/terminal subscribe)
+  // register cleanup callbacks against the runtime so reconnects don't leak
+  // listeners. Keying those cleanups by per-WebSocket connectionId lets the
+  // server reap all subscriptions for a closing socket, even when other
+  // sockets for the same deviceToken stay alive (multi-screen mobile).
+  connectionId?: string
 }
 
 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 faa8c57e33d..bdd2f181b30 100644
--- a/src/main/runtime/rpc/dispatcher.ts
+++ b/src/main/runtime/rpc/dispatcher.ts
@@ -74,7 +74,11 @@ export class RpcDispatcher {
   // Why: streaming dispatch sends multiple responses through the reply callback
   // instead of returning a single Promise. This enables terminal.subscribe and
   // other subscription-style methods that push data over time.
-  async dispatchStreaming(request: RpcRequest, reply: (response: string) => void): Promise<void> {
+  async dispatchStreaming(
+    request: RpcRequest,
+    reply: (response: string) => void,
+    options?: { connectionId?: string }
+  ): Promise<void> {
     const meta = this.meta()
     const method = this.registry.get(request.method)
     if (!method) {
@@ -94,7 +98,10 @@ export class RpcDispatcher {
 
     if (!isStreamingMethod(method)) {
       try {
-        const result = await method.handler(parsedParams.value, { runtime: this.runtime })
+        const result = await method.handler(parsedParams.value, {
+          runtime: this.runtime,
+          connectionId: options?.connectionId
+        })
         reply(JSON.stringify(successResponse(request.id, meta, result)))
       } catch (error) {
         reply(JSON.stringify(this.mapError(request, meta, error)))
@@ -109,7 +116,11 @@ export class RpcDispatcher {
     }
 
     try {
-      await method.handler(parsedParams.value, { runtime: this.runtime }, emit)
+      await method.handler(
+        parsedParams.value,
+        { runtime: this.runtime, connectionId: options?.connectionId },
+        emit
+      )
     } catch (error) {
       reply(JSON.stringify(this.mapError(request, meta, error)))
     }
diff --git a/src/main/runtime/rpc/e2ee-channel.test.ts b/src/main/runtime/rpc/e2ee-channel.test.ts
index 43920ed4d79..69b242c4ca8 100644
--- a/src/main/runtime/rpc/e2ee-channel.test.ts
+++ b/src/main/runtime/rpc/e2ee-channel.test.ts
@@ -262,5 +262,31 @@ describe('E2EEChannel', () => {
 
       expect(received).toEqual([])
     })
+
+    // Why: streaming RPC handlers (terminal.subscribe) retain the
+    // encryptedReply closure created inside handleRawMessage. If destroy()
+    // runs (mobile disconnect) before a late streaming emit, the closure's
+    // captured this.sharedKey is null. Without a guard, encrypt() would
+    // call nacl.box.after with a null key and throw an unhandled
+    // "unexpected type, use Uint8Array" rejection.
+    it('does not throw when streaming emit fires after destroy', () => {
+      const ctx = setup()
+      const sharedKey = doHandshake(ctx)
+      const sentBefore = ctx.ws.sent.length
+
+      let capturedReply: ((response: string) => void) | null = null
+      ctx.channel.onMessage((_plaintext, encryptedReply) => {
+        capturedReply = encryptedReply
+      })
+
+      ctx.channel.handleRawMessage(encrypt('subscribe-trigger', sharedKey))
+      expect(capturedReply).not.toBeNull()
+
+      ctx.channel.destroy()
+
+      const callLateEmit = () => capturedReply?.('late streaming frame')
+      expect(callLateEmit).not.toThrow()
+      expect(ctx.ws.sent.length).toBe(sentBefore)
+    })
   })
 })
diff --git a/src/main/runtime/rpc/e2ee-channel.ts b/src/main/runtime/rpc/e2ee-channel.ts
index 25bfd1e72fb..f3100584d56 100644
--- a/src/main/runtime/rpc/e2ee-channel.ts
+++ b/src/main/runtime/rpc/e2ee-channel.ts
@@ -88,10 +88,17 @@ export class E2EEChannel {
       return
     }
 
+    // Why: streaming RPC handlers (e.g. terminal.subscribe) retain this
+    // closure and may fire emits long after the inbound message handled
+    // here. If destroy() runs in between (mobile disconnect, handshake
+    // failure) sharedKey becomes null and tweetnacl throws "unexpected
+    // type, use Uint8Array" from inside nacl.box.after. Guard both the
+    // socket state AND the key so late emits become silent no-ops.
     const encryptedReply = (response: string) => {
-      if (this.ws.readyState === this.ws.OPEN) {
-        this.ws.send(encrypt(response, this.sharedKey!))
+      if (!this.sharedKey || this.ws.readyState !== this.ws.OPEN) {
+        return
       }
+      this.ws.send(encrypt(response, this.sharedKey))
     }
     this.messageHandler?.(plaintext, encryptedReply)
   }
diff --git a/src/main/runtime/rpc/methods/accounts.ts b/src/main/runtime/rpc/methods/accounts.ts
new file mode 100644
index 00000000000..21612a707f0
--- /dev/null
+++ b/src/main/runtime/rpc/methods/accounts.ts
@@ -0,0 +1,111 @@
+import { z } from 'zod'
+import { defineMethod, defineStreamingMethod, type RpcAnyMethod } from '../core'
+
+// Why: monotonically increasing per-process counter avoids the Date.now()
+// collision that fired when two near-simultaneous accounts.subscribe calls
+// collided on the same millisecond and one evicted the other through
+// registerSubscriptionCleanup's existing-key eviction path.
+let accountsSubscriptionSeq = 0
+
+const SelectAccountParams = z.object({
+  accountId: z
+    .union([z.string().min(1, 'Missing accountId'), z.null()])
+    .transform((v) => (v === null ? null : v))
+})
+
+const RemoveAccountParams = z.object({
+  accountId: z.string().min(1, 'Missing accountId')
+})
+
+const AccountsUnsubscribeParams = z.object({
+  subscriptionId: z
+    .unknown()
+    .transform((value) => (typeof value === 'string' && value.length > 0 ? value : ''))
+    .pipe(z.string().min(1, 'Missing subscriptionId'))
+})
+
+// Why: bridges the desktop ClaudeAccountService / CodexAccountService /
+// RateLimitService into the mobile WebSocket RPC. Read + switch + remove
+// only — interactive add/re-auth flows spawn `claude login` / `codex login`
+// PTYs that need a desktop browser, so they intentionally remain
+// desktop-only. See plan in spec doc for issue #1438.
+export const ACCOUNT_METHODS: readonly RpcAnyMethod[] = [
+  defineMethod({
+    name: 'accounts.list',
+    params: null,
+    handler: async (_params, { runtime }) => {
+      // Why: ensure the snapshot reflects the latest provider state before
+      // returning. Desktop polling pauses when the window is unfocused and
+      // inactive-account caches only fill on AccountsPane open, so without
+      // this the mobile UI would render stale nulls / zeroes.
+      await runtime.refreshAccountsForMobile()
+      return runtime.getAccountsSnapshot()
+    }
+  }),
+  defineMethod({
+    name: 'accounts.selectClaude',
+    params: SelectAccountParams,
+    handler: async (params, { runtime }) => runtime.selectClaudeAccount(params.accountId)
+  }),
+  defineMethod({
+    name: 'accounts.selectCodex',
+    params: SelectAccountParams,
+    handler: async (params, { runtime }) => runtime.selectCodexAccount(params.accountId)
+  }),
+  defineMethod({
+    name: 'accounts.removeClaude',
+    params: RemoveAccountParams,
+    handler: async (params, { runtime }) => runtime.removeClaudeAccount(params.accountId)
+  }),
+  defineMethod({
+    name: 'accounts.removeCodex',
+    params: RemoveAccountParams,
+    handler: async (params, { runtime }) => runtime.removeCodexAccount(params.accountId)
+  }),
+  // Why: streaming counterpart so mobile usage bars refresh in place when the
+  // desktop's 5-minute rate-limit poll completes or when the user switches
+  // accounts on either side. Mirrors the notifications.subscribe pattern.
+  defineStreamingMethod({
+    name: 'accounts.subscribe',
+    params: null,
+    handler: async (_params, { runtime, connectionId }, emit) => {
+      await new Promise<void>((resolve) => {
+        const unsubscribe = runtime.onAccountsChanged((snapshot) => {
+          emit({ type: 'snapshot', snapshot })
+        })
+
+        // Why: scope the id by connectionId so two sockets from the same
+        // device (host + accounts screen) cannot evict each other through
+        // registerSubscriptionCleanup's "existing key" branch, and append a
+        // per-process counter so two concurrent subscribes on the same
+        // socket also can't collide.
+        const seq = ++accountsSubscriptionSeq
+        const subscriptionId = `accounts-${connectionId ?? 'inproc'}-${seq}`
+        runtime.registerSubscriptionCleanup(
+          subscriptionId,
+          () => {
+            unsubscribe()
+            emit({ type: 'end' })
+            resolve()
+          },
+          connectionId
+        )
+
+        // Why: emit the current snapshot synchronously so the phone has
+        // something to render immediately, then kick a forced refresh that
+        // will broadcast a fresh snapshot through the listener once each
+        // provider fetch completes.
+        emit({ type: 'ready', subscriptionId, snapshot: runtime.getAccountsSnapshot() })
+        void runtime.refreshAccountsForMobile()
+      })
+    }
+  }),
+  defineMethod({
+    name: 'accounts.unsubscribe',
+    params: AccountsUnsubscribeParams,
+    handler: async (params, { runtime }) => {
+      runtime.cleanupSubscription(params.subscriptionId)
+      return { unsubscribed: true }
+    }
+  })
+]
diff --git a/src/main/runtime/rpc/methods/browser-core.ts b/src/main/runtime/rpc/methods/browser-core.ts
index 5d272137300..b141c0b14a3 100644
--- a/src/main/runtime/rpc/methods/browser-core.ts
+++ b/src/main/runtime/rpc/methods/browser-core.ts
@@ -16,13 +16,19 @@ import {
   KeyboardInsert,
   Keypress,
   LimitParam,
+  ProfileCreate,
+  ProfileDelete,
   Screenshot,
   Scroll,
   Select,
   SelectorPath,
+  TabCurrent,
+  TabSetProfile,
   TabClose,
   TabCreate,
   TabList,
+  TabProfileClone,
+  TabShow,
   TabSwitch,
   Type,
   Upload,
@@ -90,6 +96,16 @@ export const BROWSER_CORE_METHODS: RpcMethod[] = [
     params: TabList,
     handler: async (params, { runtime }) => runtime.browserTabList(params)
   }),
+  defineMethod({
+    name: 'browser.tabShow',
+    params: TabShow,
+    handler: async (params, { runtime }) => runtime.browserTabShow(params)
+  }),
+  defineMethod({
+    name: 'browser.tabCurrent',
+    params: TabCurrent,
+    handler: async (params, { runtime }) => runtime.browserTabCurrent(params)
+  }),
   defineMethod({
     name: 'browser.tabSwitch',
     params: TabSwitch,
@@ -100,11 +116,41 @@ export const BROWSER_CORE_METHODS: RpcMethod[] = [
     params: TabCreate,
     handler: async (params, { runtime }) => runtime.browserTabCreate(params)
   }),
+  defineMethod({
+    name: 'browser.tabSetProfile',
+    params: TabSetProfile,
+    handler: async (params, { runtime }) => runtime.browserTabSetProfile(params)
+  }),
+  defineMethod({
+    name: 'browser.tabProfileShow',
+    params: TabShow,
+    handler: async (params, { runtime }) => runtime.browserTabProfileShow(params)
+  }),
+  defineMethod({
+    name: 'browser.tabProfileClone',
+    params: TabProfileClone,
+    handler: async (params, { runtime }) => runtime.browserTabProfileClone(params)
+  }),
   defineMethod({
     name: 'browser.tabClose',
     params: TabClose,
     handler: async (params, { runtime }) => runtime.browserTabClose(params)
   }),
+  defineMethod({
+    name: 'browser.profileList',
+    params: null,
+    handler: async (_params, { runtime }) => runtime.browserProfileList()
+  }),
+  defineMethod({
+    name: 'browser.profileCreate',
+    params: ProfileCreate,
+    handler: async (params, { runtime }) => runtime.browserProfileCreate(params)
+  }),
+  defineMethod({
+    name: 'browser.profileDelete',
+    params: ProfileDelete,
+    handler: async (params, { runtime }) => runtime.browserProfileDelete(params)
+  }),
   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 3a8e3cf0ace..13ba12aeb42 100644
--- a/src/main/runtime/rpc/methods/browser-schemas.ts
+++ b/src/main/runtime/rpc/methods/browser-schemas.ts
@@ -90,6 +90,16 @@ export const TabSwitch = BrowserTarget.extend({
 
 export const TabCreate = z.object({
   url: OptionalString,
+  worktree: OptionalString,
+  profileId: OptionalString
+})
+
+export const TabShow = z.object({
+  page: requiredString('Missing required --page'),
+  worktree: OptionalString
+})
+
+export const TabCurrent = z.object({
   worktree: OptionalString
 })
 
@@ -102,6 +112,25 @@ export const TabClose = z.object({
   worktree: OptionalString
 })
 
+export const TabSetProfile = BrowserTarget.extend({
+  profileId: requiredString('Missing required --profile')
+})
+
+export const TabProfileClone = BrowserTarget.extend({
+  profileId: requiredString('Missing required --profile')
+})
+
+export const ProfileCreate = z.object({
+  label: requiredString('Missing required --label'),
+  // Strict enum so unknown scope values surface validation errors instead of being
+  // silently coerced to 'isolated' (pr-bug-scan finding from #1397).
+  scope: z.enum(['isolated', 'imported'])
+})
+
+export const ProfileDelete = z.object({
+  profileId: requiredString('Missing required --profile')
+})
+
 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/index.ts b/src/main/runtime/rpc/methods/index.ts
index cf3fbf34f86..bce5a50c4e0 100644
--- a/src/main/runtime/rpc/methods/index.ts
+++ b/src/main/runtime/rpc/methods/index.ts
@@ -8,6 +8,7 @@ import { BROWSER_EXTRA_METHODS } from './browser-extras'
 import { ORCHESTRATION_METHODS } from './orchestration'
 import { NOTIFICATION_METHODS } from './notifications'
 import { STATS_METHODS } from './stats'
+import { ACCOUNT_METHODS } from './accounts'
 
 // Why: a flat manifest keeps registration order explicit and provides one
 // grep-point for "what methods does the RPC server expose?" — useful when
@@ -21,5 +22,6 @@ export const ALL_RPC_METHODS: readonly RpcAnyMethod[] = [
   ...BROWSER_EXTRA_METHODS,
   ...ORCHESTRATION_METHODS,
   ...NOTIFICATION_METHODS,
-  ...STATS_METHODS
+  ...STATS_METHODS,
+  ...ACCOUNT_METHODS
 ]
diff --git a/src/main/runtime/rpc/methods/notifications.ts b/src/main/runtime/rpc/methods/notifications.ts
index 607474bb941..1d63f26d785 100644
--- a/src/main/runtime/rpc/methods/notifications.ts
+++ b/src/main/runtime/rpc/methods/notifications.ts
@@ -1,6 +1,11 @@
 import { z } from 'zod'
 import { defineStreamingMethod, defineMethod, type RpcAnyMethod } from '../core'
 
+// Why: monotonically increasing per-process counter eliminates the
+// Date.now() collision that could fire when two near-simultaneous
+// notifications.subscribe calls landed on the same millisecond.
+let notificationsSubscriptionSeq = 0
+
 const NotificationUnsubscribeParams = z.object({
   subscriptionId: z
     .unknown()
@@ -16,18 +21,25 @@ export const NOTIFICATION_METHODS: readonly RpcAnyMethod[] = [
   defineStreamingMethod({
     name: 'notifications.subscribe',
     params: null,
-    handler: async (_params, { runtime }, emit) => {
+    handler: async (_params, { runtime, connectionId }, emit) => {
       await new Promise<void>((resolve) => {
         const unsubscribe = runtime.onNotificationDispatched((event) => {
           emit({ type: 'notification', ...event })
         })
 
-        const subscriptionId = `notifications-${Date.now()}`
-        runtime.registerSubscriptionCleanup(subscriptionId, () => {
-          unsubscribe()
-          emit({ type: 'end' })
-          resolve()
-        })
+        // Why: scope by per-ws connectionId + per-process counter so
+        // concurrent subscribes never collide on the cleanup map.
+        const seq = ++notificationsSubscriptionSeq
+        const subscriptionId = `notifications-${connectionId ?? 'inproc'}-${seq}`
+        runtime.registerSubscriptionCleanup(
+          subscriptionId,
+          () => {
+            unsubscribe()
+            emit({ type: 'end' })
+            resolve()
+          },
+          connectionId
+        )
 
         emit({ type: 'ready', subscriptionId })
       })
diff --git a/src/main/runtime/rpc/methods/terminal.ts b/src/main/runtime/rpc/methods/terminal.ts
index f69a3fc9c84..97c5224cc90 100644
--- a/src/main/runtime/rpc/methods/terminal.ts
+++ b/src/main/runtime/rpc/methods/terminal.ts
@@ -3,6 +3,14 @@ import { z } from 'zod'
 import { defineMethod, defineStreamingMethod, type RpcAnyMethod } from '../core'
 import { OptionalFiniteNumber, OptionalString, requiredString } from '../schemas'
 
+// Why: when a mobile client subscribes the server resizes the PTY to phone
+// dims and serializes the buffer. Sending only the visible screen meant
+// users coming back to the app or switching terminals could no longer scroll
+// up to see prior agent output. Include enough scrollback to keep typical
+// agent runs (Claude Code chats, command output) reachable. The mobile
+// WebView's xterm has a 5000-row buffer so this fits comfortably.
+const MOBILE_SUBSCRIBE_SCROLLBACK_ROWS = 1000
+
 const TerminalHandle = z.object({
   terminal: requiredString('Missing terminal handle')
 })
@@ -50,7 +58,18 @@ const TerminalRename = TerminalHandle.extend({
 const TerminalSend = TerminalHandle.extend({
   text: OptionalString,
   enter: z.unknown().optional(),
-  interrupt: z.unknown().optional()
+  interrupt: z.unknown().optional(),
+  // Why: identifies the caller for the driver state machine. Optional for
+  // backward compatibility with older mobile clients (server falls back to
+  // the most recent mobile actor when absent). New mobile builds populate
+  // this so multi-mobile semantics resolve correctly. See
+  // docs/mobile-presence-lock.md.
+  client: z
+    .object({
+      id: requiredString('Missing client ID'),
+      type: z.enum(['mobile', 'desktop']).default('desktop').optional()
+    })
+    .optional()
 })
 
 const TerminalWait = TerminalHandle.extend({
@@ -109,11 +128,47 @@ const TerminalSubscribe = TerminalHandle.extend({
 })
 
 const TerminalSetDisplayMode = TerminalHandle.extend({
-  mode: z.enum(['auto', 'phone', 'desktop'])
+  mode: z.enum(['auto', 'phone', 'desktop']),
+  // Why: identifies the caller for the driver state machine. Optional for
+  // backward compatibility with older mobile clients.
+  client: z
+    .object({
+      id: requiredString('Missing client ID'),
+      type: z.enum(['mobile', 'desktop']).default('desktop').optional()
+    })
+    .optional()
 })
 
 const TerminalUnsubscribe = z.object({
-  subscriptionId: requiredString('Missing subscription ID')
+  subscriptionId: requiredString('Missing subscription ID'),
+  // Why: required when subscribe registered the cleanup under the composite
+  // key `${terminal}:${clientId}`. If the caller passes a bare-handle
+  // subscriptionId (older clients), the server reconstructs the composite
+  // key from `client.id`. See docs/mobile-presence-lock.md.
+  client: z
+    .object({
+      id: requiredString('Missing client ID')
+    })
+    .optional()
+})
+
+// Why: in-place viewport update for an existing mobile subscription. Used
+// when the keyboard opens/closes on the mobile client and the visible
+// terminal area changes — without this, the mobile app had to
+// unsubscribe → resubscribe, which (a) flashed the desktop lock banner
+// during the brief idle gap and (b) caused the new subscribe to capture
+// the already-phone-fitted PTY size as its restore baseline, leaving the
+// PTY stuck at phone dims after the phone disconnected. See
+// docs/mobile-presence-lock.md.
+const TerminalUpdateViewport = TerminalHandle.extend({
+  client: z.object({
+    id: requiredString('Missing client ID'),
+    type: z.enum(['mobile', 'desktop']).default('mobile').optional()
+  }),
+  viewport: z.object({
+    cols: z.number().int().min(20).max(240),
+    rows: z.number().int().min(8).max(120)
+  })
 })
 
 export const TERMINAL_METHODS: RpcAnyMethod[] = [
@@ -153,13 +208,27 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
   defineMethod({
     name: 'terminal.send',
     params: TerminalSend,
-    handler: async (params, { runtime }) => ({
-      send: await runtime.sendTerminal(params.terminal, {
+    handler: async (params, { runtime }) => {
+      const result = await runtime.sendTerminal(params.terminal, {
         text: params.text,
         enter: params.enter === true,
         interrupt: params.interrupt === true
       })
-    })
+      // 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;
+      // desktop callers (CLI / agents) do not. Older mobile builds without
+      // a `client` field continue to work — the runtime then keeps the
+      // current driver state.
+      if (params.client && params.client.type === 'mobile') {
+        const leaf = runtime.resolveLeafForHandle(params.terminal)
+        if (leaf?.ptyId) {
+          runtime.mobileTookFloor(leaf.ptyId, params.client.id)
+        }
+      }
+      return { send: result }
+    }
   }),
   defineMethod({
     name: 'terminal.wait',
@@ -243,6 +312,13 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       }
       runtime.setMobileDisplayMode(leaf.ptyId, params.mode)
       runtime.applyMobileDisplayMode(leaf.ptyId)
+      // Why: a deliberate mobile mode change is a take-floor action when
+      // moving to auto/phone (the user explicitly chose to drive at phone
+      // dims). Setting mode to desktop is intentionally NOT a take-floor
+      // action — that's a "watch from desktop dims" gesture.
+      if (params.client && params.client.type === 'mobile' && params.mode !== 'desktop') {
+        runtime.mobileTookFloor(leaf.ptyId, params.client.id)
+      }
       return { mode: params.mode }
     }
   }),
@@ -256,6 +332,18 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       return { mode, isPhoneFitted }
     }
   }),
+  defineMethod({
+    name: 'terminal.updateViewport',
+    params: TerminalUpdateViewport,
+    handler: async (params, { runtime }) => {
+      const leaf = runtime.resolveLeafForHandle(params.terminal)
+      if (!leaf?.ptyId) {
+        throw new Error('no_connected_pty')
+      }
+      const updated = runtime.updateMobileViewport(leaf.ptyId, params.client.id, params.viewport)
+      return { updated }
+    }
+  }),
   // 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.
@@ -302,7 +390,9 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
       }
 
       const read = await runtime.readTerminal(params.terminal)
-      const serialized = await runtime.serializeTerminalBuffer(ptyId)
+      const serialized = await runtime.serializeTerminalBuffer(ptyId, {
+        scrollbackRows: isMobile ? MOBILE_SUBSCRIBE_SCROLLBACK_ROWS : 0
+      })
       const size = runtime.getTerminalSize(ptyId)
       const displayMode = runtime.getMobileDisplayMode(ptyId)
       emit({
@@ -324,7 +414,12 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
         // mobile clients. They include fresh serialized scrollback so the client
         // can reinitialize xterm without resubscribing.
         const unsubscribeResize = runtime.subscribeToTerminalResize(ptyId, async (event) => {
-          const fresh = await runtime.serializeTerminalBuffer(ptyId)
+          // Why: mobile subscriptions need the same scrollback on inline
+          // resize as on initial subscribe — without it, toggling phone/desktop
+          // mode or the keyboard-driven refit would silently wipe history.
+          const fresh = await runtime.serializeTerminalBuffer(ptyId, {
+            scrollbackRows: isMobile ? MOBILE_SUBSCRIBE_SCROLLBACK_ROWS : 0
+          })
           emit({
             type: 'resized',
             cols: event.cols,
@@ -347,7 +442,11 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
             })
           : () => {}
 
-        const subscriptionId = params.terminal
+        // Why: composite subscriptionId per (terminal, clientId) so two
+        // mobile clients subscribing to the same terminal handle do not
+        // evict each other via registerSubscriptionCleanup's
+        // duplicate-key cleanup. See docs/mobile-presence-lock.md.
+        const subscriptionId = clientId ? `${params.terminal}:${clientId}` : params.terminal
         runtime.registerSubscriptionCleanup(subscriptionId, () => {
           unsubscribeData()
           unsubscribeResize()
@@ -365,7 +464,16 @@ export const TERMINAL_METHODS: RpcAnyMethod[] = [
     name: 'terminal.unsubscribe',
     params: TerminalUnsubscribe,
     handler: async (params, { runtime }) => {
+      // Why: the subscribe handler now registers cleanup under a composite
+      // key `${terminal}:${clientId}`. New mobile builds emit the composite
+      // key directly. Older builds emit a bare-handle subscriptionId; if
+      // they additionally provide `client.id`, reconstruct the composite
+      // key server-side. We always try the as-sent value first, then fall
+      // back to the reconstructed composite, so both wire formats work.
       runtime.cleanupSubscription(params.subscriptionId)
+      if (params.client && !params.subscriptionId.includes(':')) {
+        runtime.cleanupSubscription(`${params.subscriptionId}:${params.client.id}`)
+      }
       return { unsubscribed: true }
     }
   })
diff --git a/src/main/runtime/rpc/ws-transport.test.ts b/src/main/runtime/rpc/ws-transport.test.ts
index ea3acd486fb..8bd80ca53d8 100644
--- a/src/main/runtime/rpc/ws-transport.test.ts
+++ b/src/main/runtime/rpc/ws-transport.test.ts
@@ -253,4 +253,60 @@ describe('WebSocketTransport', () => {
     const ws = await connectWs(second.resolvedPort)
     ws.close()
   })
+
+  it('reaps a half-open client that stops responding to pings', async () => {
+    // Why: regression cover for the half-open-socket leak that would
+    // strand mobile clients in the connection pool until OS TCP keepalive
+    // (~2 hours) reaped them. With the heartbeat, two consecutive ping
+    // ticks without a pong should cause terminate() to fire and free the
+    // slot. Verifying via the server's connection-close handler, which
+    // is what frees up the MAX_WS_CONNECTIONS budget in production.
+    const tls = makeTls()
+    const port = findFreePort()
+    const transport = new WebSocketTransport({
+      host: '127.0.0.1',
+      port,
+      tlsCert: tls.cert,
+      tlsKey: tls.key,
+      heartbeatIntervalMs: 50
+    })
+    transport.onMessage(() => {})
+    transports.push(transport)
+
+    let serverClosed = false
+    transport.onConnectionClose(() => {
+      serverClosed = true
+    })
+
+    // Why: setClientId is what registers the ws → clientId mapping that
+    // onConnectionClose fires off. Hook the connection event before
+    // start so we can stamp every accepted ws with a token.
+    await transport.start()
+
+    const ws = await connectWs(port)
+    // 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
+    // perspective the client looks half-open — exactly the production
+    // failure mode iOS produces when it suspends a backgrounded socket.
+    const underlying = (ws as unknown as { _socket: { pause: () => void } })._socket
+    underlying.pause()
+
+    // Why: we need a clientId on the ws so onConnectionClose actually
+    // fires. The transport sets it lazily via setClientId in production
+    // (after auth); in this test we don't run auth, so reach in.
+    const wss = (transport as unknown as { wss: { clients: Set<{ readyState: number }> } }).wss
+    for (const c of wss.clients) {
+      transport.setClientId(c as never, 'test-client')
+    }
+
+    // Wait long enough for two heartbeat ticks (50ms each) plus slack.
+    const start = Date.now()
+    while (!serverClosed && Date.now() - start < 2_000) {
+      await new Promise((r) => setTimeout(r, 25))
+    }
+
+    expect(serverClosed).toBe(true)
+    expect(wss.clients.size).toBe(0)
+  }, 5_000)
 })
diff --git a/src/main/runtime/rpc/ws-transport.ts b/src/main/runtime/rpc/ws-transport.ts
index 218bdfe2851..5a97642a30c 100644
--- a/src/main/runtime/rpc/ws-transport.ts
+++ b/src/main/runtime/rpc/ws-transport.ts
@@ -11,11 +11,25 @@ import type { RpcTransport } from './transport'
 const MAX_WS_MESSAGE_BYTES = 1024 * 1024
 const MAX_WS_CONNECTIONS = 32
 
+// Why: mobile clients (iOS/Android) regularly background-suspend their
+// sockets without the OS sending a TCP FIN/RST, leaving the server with
+// half-open WebSockets that count toward MAX_WS_CONNECTIONS. Without this
+// heartbeat the only thing that ever reaps them is the OS's TCP keepalive
+// (default macOS: ~2 hours idle + 11 min of probes), which is the
+// "connection randomly turns green again after a long delay" symptom.
+// Pinging every 15s and terminating any client that hasn't pong'd by the
+// next tick collapses that worst case to ~30s. RN/browser WebSocket
+// runtimes auto-respond to server pings with pongs at the protocol layer,
+// so this works for any client that speaks RFC 6455.
+const HEARTBEAT_INTERVAL_MS = 15_000
+
 export type WebSocketTransportOptions = {
   host: string
   port: number
   tlsCert?: string
   tlsKey?: string
+  // Why: test-only override. Production uses HEARTBEAT_INTERVAL_MS.
+  heartbeatIntervalMs?: number
 }
 
 export class WebSocketTransport implements RpcTransport {
@@ -23,21 +37,30 @@ export class WebSocketTransport implements RpcTransport {
   private readonly port: number
   private readonly tlsCert: string | undefined
   private readonly tlsKey: string | undefined
+  private readonly heartbeatIntervalMs: number
   private httpServer: HttpsServer | HttpServer | null = null
   private wss: WebSocketServer | null = null
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  // Why: tracks whether each socket has pong'd since the last heartbeat
+  // sweep. A socket missing from the set when the next sweep fires is
+  // assumed dead and terminated.
+  private wsAlive = new WeakSet<WebSocket>()
   private messageHandler:
     | ((msg: string, reply: (response: string) => void, ws: WebSocket) => void)
     | null = null
-  private connectionCloseHandler: ((clientId: string) => void) | null = null
+  private connectionCloseHandler:
+    | ((clientId: string, 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>()
 
-  constructor({ host, port, tlsCert, tlsKey }: WebSocketTransportOptions) {
+  constructor({ host, port, tlsCert, tlsKey, heartbeatIntervalMs }: WebSocketTransportOptions) {
     this.host = host
     this.port = port
     this.tlsCert = tlsCert
     this.tlsKey = tlsKey
+    this.heartbeatIntervalMs = heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS
   }
 
   onMessage(
@@ -46,7 +69,15 @@ export class WebSocketTransport implements RpcTransport {
     this.messageHandler = handler
   }
 
-  onConnectionClose(handler: (clientId: string) => void): void {
+  // Why: handlers receive the closing `ws` so per-connection state can be
+  // targeted exactly (one paired device may hold multiple concurrent sockets,
+  // e.g. host screen + accounts screen). `hasOtherConnections` tells the
+  // runtime whether other sockets for the same deviceToken are still alive,
+  // so client-scoped teardown (mobile-fit overrides, etc.) only fires on the
+  // last disconnect.
+  onConnectionClose(
+    handler: (clientId: string, ws: WebSocket, hasOtherConnections: boolean) => void
+  ): void {
     this.connectionCloseHandler = handler
   }
 
@@ -123,6 +154,49 @@ export class WebSocketTransport implements RpcTransport {
 
     this.httpServer = httpServer
     this.wss = wss
+    this.startHeartbeat()
+  }
+
+  // Why: ping every live socket on a fixed cadence and terminate any that
+  // didn't pong since the previous tick. This is the only thing that
+  // reliably reaps half-open mobile sockets stranded by background
+  // suspension without a TCP FIN. See HEARTBEAT_INTERVAL_MS comment.
+  private startHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      return
+    }
+    this.heartbeatTimer = setInterval(() => {
+      const wss = this.wss
+      if (!wss) {
+        return
+      }
+      for (const ws of wss.clients) {
+        if (!this.wsAlive.has(ws)) {
+          // Why: terminate() (vs close()) skips the close handshake and
+          // immediately fires the 'close' event, freeing the slot. close()
+          // on an already-dead socket can hang for the OS-level TCP timeout.
+          ws.terminate()
+          continue
+        }
+        this.wsAlive.delete(ws)
+        try {
+          ws.ping()
+        } catch {
+          // Why: ping() can throw on a socket that's mid-tear-down; the
+          // close handler will run regardless, so swallow the throw.
+        }
+      }
+    }, this.heartbeatIntervalMs)
+    if (typeof this.heartbeatTimer.unref === 'function') {
+      this.heartbeatTimer.unref()
+    }
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
   }
 
   async stop(): Promise<void> {
@@ -130,6 +204,7 @@ export class WebSocketTransport implements RpcTransport {
     const httpServer = this.httpServer
     this.wss = null
     this.httpServer = null
+    this.stopHeartbeat()
 
     if (wss) {
       for (const client of wss.clients) {
@@ -156,7 +231,21 @@ 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 {
+    // 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.
+    this.wsAlive.add(ws)
+
+    ws.on('pong', () => {
+      this.wsAlive.add(ws)
+    })
+
     ws.on('message', (data) => {
+      // Why: any inbound traffic counts as proof of life, not just pongs.
+      // RN's WebSocket runtime auto-pongs server pings transparently, but
+      // app-level frames also count toward liveness so an actively-talking
+      // client doesn't get terminated mid-request.
+      this.wsAlive.add(ws)
       const msg = typeof data === 'string' ? data : data.toString('utf-8')
       this.messageHandler?.(
         msg,
@@ -178,7 +267,13 @@ export class WebSocketTransport implements RpcTransport {
       const clientId = this.wsClientIds.get(ws)
       this.wsClientIds.delete(ws)
       if (clientId) {
-        this.connectionCloseHandler?.(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)
       }
     })
 
diff --git a/src/main/runtime/runtime-rpc.ts b/src/main/runtime/runtime-rpc.ts
index b2e4cf27660..c1f946e6990 100644
--- a/src/main/runtime/runtime-rpc.ts
+++ b/src/main/runtime/runtime-rpc.ts
@@ -88,6 +88,10 @@ export class OrcaRuntimeRpcServer {
   // Why: each WebSocket connection has its own E2EE channel that manages the
   // handshake and encrypt/decrypt lifecycle. Keyed by WebSocket instance.
   private e2eeChannels = new Map<WebSocket, E2EEChannel>()
+  // Why: stable per-WebSocket id used as the cleanup key for streaming
+  // 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>()
   // 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.
@@ -220,6 +224,11 @@ export class OrcaRuntimeRpcServer {
         wsTransport.onMessage((msg, _reply, ws) => {
           let channel = this.e2eeChannels.get(ws)
           if (!channel) {
+            // Why: stable per-ws id used as the cleanup-index key for
+            // streaming subscriptions, so the server can reap them exactly
+            // when this socket closes (without affecting other live sockets
+            // that share the same deviceToken).
+            this.wsConnectionIds.set(ws, randomBytes(8).toString('hex'))
             channel = new E2EEChannel(ws, {
               serverSecretKey: this.e2eeKeypair!.secretKey,
               validateToken: (token) => this.deviceRegistry?.validateToken(token) != null,
@@ -251,16 +260,28 @@ export class OrcaRuntimeRpcServer {
 
         // Why: when a mobile client disconnects, the runtime must clean up
         // connection-scoped state like mobile-fit overrides and the E2EE
-        // channel to prevent orphaned state.
-        wsTransport.onConnectionClose((clientId) => {
-          for (const [ws, channel] of this.e2eeChannels) {
-            if (channel.deviceToken === clientId) {
-              channel.destroy()
-              this.e2eeChannels.delete(ws)
-              break
-            }
+        // channel to prevent orphaned state. A single paired device can hold
+        // multiple concurrent sockets (host screen + accounts screen, etc.),
+        // so destroy the channel for THIS exact ws and skip the per-client
+        // teardown when other sockets for the same token are still alive.
+        wsTransport.onConnectionClose((clientId, ws, hasOtherConnections) => {
+          // Why: sweep streaming subscriptions for THIS ws regardless of
+          // hasOtherConnections, so per-ws listeners (notifications,
+          // accounts, terminal) don't leak across reconnects. This is
+          // independent of the deviceToken-scoped onClientDisconnected.
+          const connectionId = this.wsConnectionIds.get(ws)
+          if (connectionId) {
+            this.runtime.cleanupSubscriptionsForConnection(connectionId)
+            this.wsConnectionIds.delete(ws)
+          }
+          const channel = this.e2eeChannels.get(ws)
+          if (channel) {
+            channel.destroy()
+            this.e2eeChannels.delete(ws)
+          }
+          if (!hasOtherConnections) {
+            this.runtime.onClientDisconnected(clientId)
           }
-          this.runtime.onClientDisconnected(clientId)
         })
 
         await wsTransport.start()
@@ -429,7 +450,8 @@ export class OrcaRuntimeRpcServer {
       wsTransport.setClientId(ws, token)
     }
 
-    await this.dispatcher.dispatchStreaming(request, reply)
+    const connectionId = ws ? this.wsConnectionIds.get(ws) : undefined
+    await this.dispatcher.dispatchStreaming(request, reply, { connectionId })
   }
 
   private buildError(id: string, code: string, message: string): RpcResponse {
diff --git a/src/main/runtime/scrollback-limits.ts b/src/main/runtime/scrollback-limits.ts
new file mode 100644
index 00000000000..95308afcff8
--- /dev/null
+++ b/src/main/runtime/scrollback-limits.ts
@@ -0,0 +1,7 @@
+// Why: mobile subscribers hydrate the runtime headless emulator from the
+// desktop renderer's xterm buffer. The renderer holds a 50k-row scrollback;
+// shipping all of it across IPC + replaying through HeadlessEmulator is
+// expensive and unnecessary for a phone screen. Cap at 1000 rows so the seed
+// covers a meaningful amount of agent context while keeping the round-trip
+// bounded. See docs/mobile-prefer-renderer-scrollback.md.
+export const MOBILE_SUBSCRIBE_SCROLLBACK_ROWS = 1000
diff --git a/src/main/runtime/worktree-teardown.test.ts b/src/main/runtime/worktree-teardown.test.ts
index 6fcfd9c798c..c66749a7aac 100644
--- a/src/main/runtime/worktree-teardown.test.ts
+++ b/src/main/runtime/worktree-teardown.test.ts
@@ -60,10 +60,10 @@ describe('killAllProcessesForWorktree', () => {
     expect(result.providerStopped).toBe(1)
     expect(result.registryStopped).toBe(1)
 
-    expect(localProvider.shutdown).toHaveBeenCalledWith('w1@@abcd1234', true)
-    expect(localProvider.shutdown).toHaveBeenCalledWith('w1-registry-1', true)
-    expect(localProvider.shutdown).not.toHaveBeenCalledWith('w2@@efef5678', true)
-    expect(localProvider.shutdown).not.toHaveBeenCalledWith('w2-registry-2', true)
+    expect(localProvider.shutdown).toHaveBeenCalledWith('w1@@abcd1234', { immediate: true })
+    expect(localProvider.shutdown).toHaveBeenCalledWith('w1-registry-1', { immediate: true })
+    expect(localProvider.shutdown).not.toHaveBeenCalledWith('w2@@efef5678', { immediate: true })
+    expect(localProvider.shutdown).not.toHaveBeenCalledWith('w2-registry-2', { immediate: true })
   })
 
   it('skips the daemon prefix sweep safely when the provider uses numeric ids', async () => {
@@ -81,7 +81,7 @@ describe('killAllProcessesForWorktree', () => {
     // Prefix sweep must kill nothing; registry sweep must still fire.
     expect(result.providerStopped).toBe(0)
     expect(result.registryStopped).toBe(1)
-    expect(localProvider.shutdown).toHaveBeenCalledWith('1', true)
+    expect(localProvider.shutdown).toHaveBeenCalledWith('1', { immediate: true })
     expect(localProvider.shutdown).toHaveBeenCalledTimes(1)
   })
 
@@ -114,12 +114,12 @@ describe('killAllProcessesForWorktree', () => {
     listRegisteredPtysMock.mockReturnValue([])
 
     const r1 = await killAllProcessesForWorktree('w1', { localProvider: providerA })
-    expect(providerA.shutdown).toHaveBeenCalledWith('w1@@aaaa', true)
+    expect(providerA.shutdown).toHaveBeenCalledWith('w1@@aaaa', { immediate: true })
     expect(providerB.shutdown).not.toHaveBeenCalled()
     expect(r1.providerStopped).toBe(1)
 
     const r2 = await killAllProcessesForWorktree('w1', { localProvider: providerB })
-    expect(providerB.shutdown).toHaveBeenCalledWith('w1@@bbbb', true)
+    expect(providerB.shutdown).toHaveBeenCalledWith('w1@@bbbb', { immediate: true })
     expect(providerB.shutdown).toHaveBeenCalledTimes(1)
     expect(r2.providerStopped).toBe(1)
   })
diff --git a/src/main/runtime/worktree-teardown.ts b/src/main/runtime/worktree-teardown.ts
index a25d46ec482..3488d5033af 100644
--- a/src/main/runtime/worktree-teardown.ts
+++ b/src/main/runtime/worktree-teardown.ts
@@ -65,7 +65,7 @@ async function sweepProviderByPrefix(worktreeId: string, provider: IPtyProvider)
       continue
     }
     try {
-      await provider.shutdown(s.id, true)
+      await provider.shutdown(s.id, { immediate: true })
       killed += 1
     } catch {
       // Already dead, or the backend dropped the session — treat as success.
@@ -83,7 +83,7 @@ async function sweepRegistryForWorktree(
   let killed = 0
   for (const entry of entries) {
     try {
-      await localProvider.shutdown(entry.ptyId, true)
+      await localProvider.shutdown(entry.ptyId, { immediate: true })
       killed += 1
     } catch {
       /* ignore — best-effort */
diff --git a/src/main/ssh/ssh-connection.ts b/src/main/ssh/ssh-connection.ts
index 6c986fbcb48..fc19c622b1c 100644
--- a/src/main/ssh/ssh-connection.ts
+++ b/src/main/ssh/ssh-connection.ts
@@ -55,6 +55,16 @@ export class SshConnection {
     return { ...this.target }
   }
 
+  // Why: exposes whether a passphrase/password is already cached in-memory for
+  // this connection. Used by ssh:needsPassphrasePrompt so callers can decide
+  // whether a manual-reconnect will prompt or go through silently. Without this,
+  // lastRequiredPassphrase stays true across the session even after the user
+  // has entered the credential once, causing redundant "enter passphrase"
+  // prompts on disconnect→reconnect cycles within a single app session.
+  hasCachedCredential(): boolean {
+    return this.cachedPassphrase != null || this.cachedPassword != null
+  }
+
   async exec(cmd: string): Promise<ClientChannel> {
     if (!this.client) {
       throw new Error('Not connected')
@@ -110,7 +120,9 @@ export class SshConnection {
     this.proxyProcess = null
     const connectGeneration = ++this.connectGeneration
 
-    const resolved = await resolveWithSshG(this.target.configHost || this.target.label).catch(() => null)
+    const resolved = await resolveWithSshG(this.target.configHost || this.target.label).catch(
+      () => null
+    )
     const config = buildConnectConfig(this.target, resolved)
 
     // Why: ssh2 doesn't support ProxyCommand/ProxyJump natively. Spawn the
diff --git a/src/main/telemetry/burst-cap.ts b/src/main/telemetry/burst-cap.ts
index ae11520f518..382e6600dfa 100644
--- a/src/main/telemetry/burst-cap.ts
+++ b/src/main/telemetry/burst-cap.ts
@@ -12,9 +12,10 @@
 //       abuse at the per-event cap could emit ~650K events and blow the
 //       PostHog billing cap in one session.
 //
-//   (3) Consent-mutation bucket (≤5 `setOptIn` calls per session) — a real
-//       user flips the Privacy pane toggle a handful of times at most;
-//       beyond that it is either a bug or a compromised renderer.
+//   (3) Consent-mutation bucket (≤5 per session, shared across `setOptIn`
+//       and `acknowledgeBanner`) — a real user flips the Privacy pane
+//       toggle a handful of times at most; beyond that it is either a bug
+//       or a compromised renderer.
 //
 // All buckets reset when `resetBurstCapsForSession()` is called at the start
 // of a fresh telemetry session (on `initTelemetry`). Within a session, the
diff --git a/src/main/telemetry/classify-error.test.ts b/src/main/telemetry/classify-error.test.ts
new file mode 100644
index 00000000000..bad63bb06aa
--- /dev/null
+++ b/src/main/telemetry/classify-error.test.ts
@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { classifyError } from './classify-error'
+
+describe('classifyError', () => {
+  it('classifies ENOENT as binary_not_found', () => {
+    expect(classifyError(new Error('spawn zsh ENOENT'))).toEqual({
+      error_class: 'binary_not_found'
+    })
+    expect(classifyError(Object.assign(new Error('missing'), { code: 'ENOENT' }))).toEqual({
+      error_class: 'binary_not_found'
+    })
+  })
+
+  it('keeps shell-output-shaped not-found messages unknown', () => {
+    expect(classifyError(new Error('command not found: claude'))).toEqual({
+      error_class: 'unknown'
+    })
+    expect(classifyError(new Error('workspace not found'))).toEqual({
+      error_class: 'unknown'
+    })
+    expect(
+      classifyError(
+        Object.assign(new Error('socket missing'), { code: 'ENOENT', syscall: 'connect' })
+      )
+    ).toEqual({ error_class: 'unknown' })
+  })
+
+  it('returns unknown for null/undefined input', () => {
+    expect(classifyError(null)).toEqual({ error_class: 'unknown' })
+    expect(classifyError(undefined)).toEqual({ error_class: 'unknown' })
+  })
+
+  it('returns unknown for an unrecognized message', () => {
+    expect(classifyError(new Error('some unique failure mode we do not know'))).toEqual({
+      error_class: 'unknown'
+    })
+  })
+
+  it('returns unknown for non-Error throws', () => {
+    expect(classifyError('a bare string')).toEqual({ error_class: 'unknown' })
+    expect(classifyError({ random: 'object' })).toEqual({ error_class: 'unknown' })
+  })
+})
diff --git a/src/main/telemetry/classify-error.ts b/src/main/telemetry/classify-error.ts
new file mode 100644
index 00000000000..06b5700dbe4
--- /dev/null
+++ b/src/main/telemetry/classify-error.ts
@@ -0,0 +1,44 @@
+// Best-effort classifier from a thrown value to the closed `error_class`
+// enum on `agent_error`. The wire never carries a raw error message or stack
+// — every transmitted error is bucketed into one of the two enum members
+// (`binary_not_found` for ENOENT-shaped failures, `unknown` for everything
+// else). A non-zero `unknown` slice on the dashboard is the trigger to add a
+// new enum value alongside the call site that would emit it.
+
+import type { ErrorClass } from '../../shared/telemetry-events'
+
+export type ClassifiedError = {
+  error_class: ErrorClass
+}
+
+export function classifyError(err: unknown): ClassifiedError {
+  if (err === null || err === undefined) {
+    return { error_class: 'unknown' }
+  }
+
+  const code =
+    typeof err === 'object' && err !== null && 'code' in err
+      ? (err as { code?: unknown }).code
+      : undefined
+  const syscall =
+    typeof err === 'object' && err !== null && 'syscall' in err
+      ? (err as { syscall?: unknown }).syscall
+      : undefined
+  const message =
+    typeof err === 'object' && err !== null && 'message' in err
+      ? (err as { message?: unknown }).message
+      : undefined
+
+  if (
+    code === 'ENOENT' &&
+    (typeof syscall !== 'string' || syscall.toLowerCase().startsWith('spawn'))
+  ) {
+    return { error_class: 'binary_not_found' }
+  }
+
+  if (typeof message === 'string' && /\bspawn\b/i.test(message) && /\benoent\b/i.test(message)) {
+    return { error_class: 'binary_not_found' }
+  }
+
+  return { error_class: 'unknown' }
+}
diff --git a/src/main/telemetry/client.test.ts b/src/main/telemetry/client.test.ts
index fef3d27fec6..2b76dd44c36 100644
--- a/src/main/telemetry/client.test.ts
+++ b/src/main/telemetry/client.test.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 // End-to-end behavior of the track() wrapper against a mock PostHog. These
 // tests pin the ordering contracts:
 //
@@ -5,8 +6,8 @@
 //   - burst cap runs BEFORE consent resolve (opted-out flood does not hit
 //     resolveConsent)
 //   - per-session 1000-event ceiling enforced
-//   - opt-out event fires BEFORE posthog.optOut() — the one event that
-//     transmits against the user's new preference
+//   - opt-out event reaches the SDK queue BEFORE posthog.optOut() — the one
+//     event that transmits against the user's new preference
 //   - serialized capture payload is exactly CommonProps ∪ EventProps ∪ the
 //     allowed auto-properties ({ $process_person_profile }); an unexpected
 //     auto-property from a future SDK upgrade fails the drift check
@@ -25,9 +26,13 @@ import {
   _setPostHogClientForTests,
   _setShuttingDownForTests,
   _setStoreForTests,
+  _resetFirstAppOpenedFiredForTests,
+  persistBannerAcknowledgeWithoutEmitting,
   setOptIn,
+  shouldOptOutSdkAtInit,
   shutdownTelemetry,
-  track
+  track,
+  trackAppOpenedOnce
 } from './client'
 
 // Minimal mock of the PostHog client surface the wrapper actually calls.
@@ -39,14 +44,42 @@ type MockPostHog = {
   optIn: ReturnType<typeof vi.fn>
   optOut: ReturnType<typeof vi.fn>
   shutdown: ReturnType<typeof vi.fn>
+  on: ReturnType<typeof vi.fn>
+  emitForTests: (event: string, payload: unknown) => void
 }
 
 function makeMockPostHog(): MockPostHog {
+  const listeners = new Map<string, Set<(payload: unknown) => void>>()
+  const emitForTests = (event: string, payload: unknown): void => {
+    for (const listener of listeners.get(event) ?? []) {
+      listener(payload)
+    }
+  }
+
   return {
-    capture: vi.fn(),
-    optIn: vi.fn(),
-    optOut: vi.fn(),
-    shutdown: vi.fn(async () => {})
+    capture: vi.fn((message: { event?: string; uuid?: string }) => {
+      queueMicrotask(() => {
+        emitForTests('capture', {
+          event: message.event,
+          uuid: message.uuid
+        })
+      })
+    }),
+    optIn: vi.fn(async () => {}),
+    optOut: vi.fn(async () => {}),
+    shutdown: vi.fn(async () => {}),
+    on: vi.fn((event: string, listener: (payload: unknown) => void) => {
+      let eventListeners = listeners.get(event)
+      if (!eventListeners) {
+        eventListeners = new Set()
+        listeners.set(event, eventListeners)
+      }
+      eventListeners.add(listener)
+      return () => {
+        eventListeners?.delete(listener)
+      }
+    }),
+    emitForTests
   }
 }
 
@@ -140,12 +173,14 @@ describe('track()', () => {
     _setStoreForTests(store)
     _setShuttingDownForTests(false)
     _enableTransportForTests(true)
+    _resetFirstAppOpenedFiredForTests()
   })
   afterEach(() => {
     _enableTransportForTests(false)
     _setPostHogClientForTests(null)
     _setCommonPropsForTests(null)
     _setStoreForTests(null)
+    _resetFirstAppOpenedFiredForTests()
     vi.restoreAllMocks()
     restoreConsentEnv(envStash)
   })
@@ -240,12 +275,19 @@ describe('track()', () => {
   it('drops invalid events before calling capture', () => {
     // Raw error strings on agent_error are rejected by `.strict()`.
     track('agent_error', {
-      error_class: 'auth_expired',
+      error_class: 'unknown',
       agent_kind: 'claude-code',
       error_message: 'leaked message' // rejected by .strict()
     } as never)
     expect(mock.capture).not.toHaveBeenCalled()
   })
+
+  it('trackAppOpenedOnce emits app_opened at most once per session', () => {
+    trackAppOpenedOnce()
+    trackAppOpenedOnce()
+    expect(mock.capture).toHaveBeenCalledTimes(1)
+    expect(mock.capture.mock.calls[0]![0].event).toBe('app_opened')
+  })
 })
 
 describe('setOptIn()', () => {
@@ -271,40 +313,152 @@ describe('setOptIn()', () => {
     _setStoreForTests(store)
     _setShuttingDownForTests(false)
     _enableTransportForTests(true)
+    _resetFirstAppOpenedFiredForTests()
   })
   afterEach(() => {
     _enableTransportForTests(false)
     _setPostHogClientForTests(null)
     _setCommonPropsForTests(null)
     _setStoreForTests(null)
+    _resetFirstAppOpenedFiredForTests()
     vi.restoreAllMocks()
     restoreConsentEnv(envStash)
   })
 
   // Ordering invariant: the opt-out event is the one signal that transmits
-  // against the user's new preference. It MUST reach capture() before we
-  // disable the SDK — otherwise the signal is lost.
-  it('fires telemetry_opted_out BEFORE posthog.optOut()', () => {
+  // against the user's new preference. It MUST reach the SDK queue before
+  // we disable the SDK — otherwise posthog-node drops it at enqueue time.
+  it('waits for telemetry_opted_out to enqueue before posthog.optOut()', async () => {
     const order: string[] = []
-    mock.capture.mockImplementation(() => {
-      order.push('capture')
+    mock.capture.mockImplementation((message: { event?: string; uuid?: string }) => {
+      order.push('capture called')
+      queueMicrotask(() => {
+        order.push('sdk enqueue')
+        mock.emitForTests('capture', {
+          event: message.event,
+          uuid: message.uuid
+        })
+      })
     })
-    mock.optOut.mockImplementation(() => {
+    mock.optOut.mockImplementation(async () => {
       order.push('optOut')
     })
-    setOptIn('settings', false)
-    expect(order).toEqual(['capture', 'optOut'])
+    await setOptIn('settings', false)
+    expect(order).toEqual(['capture called', 'sdk enqueue', 'optOut'])
   })
 
-  it('fires telemetry_opted_in AFTER posthog.optIn()', () => {
+  it('fires telemetry_opted_in after posthog.optIn without app_opened for settings opt-in', async () => {
     // Flip settings to currently-opted-out so the flip to true exercises
-    // the opt-in branch cleanly.
+    // the opt-in branch cleanly. This is not the pending-banner path, so
+    // it must not replay the once-per-session app_opened event.
     settings.telemetry!.optedIn = false
     const order: string[] = []
-    mock.optIn.mockImplementation(() => order.push('optIn'))
-    mock.capture.mockImplementation(() => order.push('capture'))
-    setOptIn('settings', true)
-    expect(order).toEqual(['optIn', 'capture'])
+    mock.optIn.mockImplementation(async () => order.push('optIn'))
+    mock.capture.mockImplementation((message: { event?: string }) => {
+      order.push(`capture:${message.event}`)
+    })
+    await setOptIn('settings', true)
+    expect(order).toEqual(['optIn', 'capture:telemetry_opted_in'])
+  })
+
+  it('drops telemetry_opted_in silently in non-official builds', async () => {
+    settings.telemetry!.optedIn = false
+    _setPostHogClientForTests(null)
+    _enableTransportForTests(false)
+
+    await setOptIn('settings', true)
+
+    expect(mock.capture).not.toHaveBeenCalled()
+    expect(console.debug).not.toHaveBeenCalled()
+  })
+
+  it('fires app_opened once after pending-banner opt-in enables the SDK', async () => {
+    settings.telemetry = {
+      optedIn: null,
+      installId: BASE_COMMON.install_id,
+      existedBeforeTelemetryRelease: true
+    }
+    const order: string[] = []
+    mock.optIn.mockImplementation(async () => order.push('optIn'))
+    mock.capture.mockImplementation((message: { event?: string }) => {
+      order.push(`capture:${message.event}`)
+    })
+
+    await setOptIn('settings', true)
+
+    expect(order).toEqual(['optIn', 'capture:app_opened', 'capture:telemetry_opted_in'])
+  })
+})
+
+describe('persistBannerAcknowledgeWithoutEmitting()', () => {
+  let mock: MockPostHog
+  let store: Store
+  let settings: GlobalSettings
+  let envStash: Record<string, string | undefined>
+
+  beforeEach(() => {
+    envStash = stashAndClearConsentEnv()
+    vi.spyOn(console, 'debug').mockImplementation(() => {})
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    resetBurstCapsForSession()
+    mock = makeMockPostHog()
+    settings = makeFakeSettings({
+      optedIn: null,
+      installId: BASE_COMMON.install_id,
+      existedBeforeTelemetryRelease: true
+    })
+    store = makeFakeStore(settings)
+    _setPostHogClientForTests(mock as unknown as PostHog)
+    _setCommonPropsForTests(BASE_COMMON)
+    _setStoreForTests(store)
+    _setShuttingDownForTests(false)
+    _enableTransportForTests(true)
+    _resetFirstAppOpenedFiredForTests()
+  })
+
+  afterEach(() => {
+    _enableTransportForTests(false)
+    _setPostHogClientForTests(null)
+    _setCommonPropsForTests(null)
+    _setStoreForTests(null)
+    _resetFirstAppOpenedFiredForTests()
+    vi.restoreAllMocks()
+    restoreConsentEnv(envStash)
+  })
+
+  it('fires app_opened after re-enabling the SDK and does not emit telemetry_opted_in', async () => {
+    const order: string[] = []
+    mock.optIn.mockImplementation(async () => order.push('optIn'))
+    mock.capture.mockImplementation((message: { event?: string }) => {
+      order.push(`capture:${message.event}`)
+    })
+
+    await persistBannerAcknowledgeWithoutEmitting()
+
+    expect(order).toEqual(['optIn', 'capture:app_opened'])
+    expect(settings.telemetry?.optedIn).toBe(true)
+  })
+})
+
+// Pin the init-time SDK opt-out decision. The bug this test prevents: if
+// `initTelemetry` flipped the SDK's `optedOut` flag for `pending_banner`
+// (existing users who have not yet resolved the notice), the direct
+// `posthog.capture(telemetry_opted_out)` on the Turn-off path would be
+// dropped by posthog-core's enqueue — silently losing the one signal that
+// tells us the existing-user opt-out flow works.
+describe('shouldOptOutSdkAtInit()', () => {
+  it('opts out the SDK for every disabled-reason', () => {
+    for (const reason of ['user_opt_out', 'ci', 'do_not_track', 'orca_disabled'] as const) {
+      expect(shouldOptOutSdkAtInit({ effective: 'disabled', reason })).toBe(true)
+    }
+  })
+
+  it('does NOT opt out the SDK for pending_banner', () => {
+    expect(shouldOptOutSdkAtInit({ effective: 'pending_banner' })).toBe(false)
+  })
+
+  it('does NOT opt out the SDK for enabled', () => {
+    expect(shouldOptOutSdkAtInit({ effective: 'enabled' })).toBe(false)
   })
 })
 
diff --git a/src/main/telemetry/client.ts b/src/main/telemetry/client.ts
index 2fbccf9e268..03b8effc7f9 100644
--- a/src/main/telemetry/client.ts
+++ b/src/main/telemetry/client.ts
@@ -30,18 +30,22 @@ import { randomUUID } from 'node:crypto'
 import { arch as osArch, platform as osPlatform, release as osRelease } from 'node:os'
 import { app } from 'electron'
 import { PostHog } from 'posthog-node'
-import type { CommonProps, EventName, EventProps } from '../../shared/telemetry-events'
+import type { CommonProps, EventName, EventProps, OptInVia } from '../../shared/telemetry-events'
 import type { Store } from '../persistence'
 import { consumeBurstToken, resetBurstCapsForSession } from './burst-cap'
-import { resolveConsent } from './consent'
+import { resolveConsent, type ConsentState } from './consent'
 import { commonPropsSchema, validate } from './validator'
 
-// Compile-time feature flag. PR 2 ships with this `false` — the SDK is wired
-// but no event transmits. PR 3 flips it to `true` once the PostHog project
-// is live and dashboards are verified. Independent of the build-identity
-// gate below: both must be satisfied to transmit, so flipping the flag
-// alone still leaves contributor builds silent.
-const TELEMETRY_ENABLED = false
+// Compile-time feature flag. PR 2 shipped with this `false` so the SDK was
+// wired but no event transmitted. PR 3 flips it to `true`. Independent of
+// the build-identity gate below: both must be satisfied to transmit, so
+// flipping the flag alone still leaves contributor builds silent.
+//
+// NOTE: config/scripts/verify-telemetry-constants.mjs greps this declaration
+// shape (`const TELEMETRY_ENABLED = true|false`) to gate release verification.
+// If you refactor this (e.g. let, export, computed-from-env, moved into a
+// config object), update the regex in that script too.
+const TELEMETRY_ENABLED = true
 
 // Eligible-to-transmit only if the CI release pipeline injected BOTH the
 // build-identity constant and a write key. One without the other is treated
@@ -79,6 +83,8 @@ let commonProps: CommonProps | null = null
 let shuttingDown = false
 let storeRef: Store | null = null
 
+const OPT_OUT_CAPTURE_ENQUEUE_TIMEOUT_MS = 1_000
+
 // Test-only override for the transport gate. Set by `_enableTransportForTests`
 // so the client.test.ts suite can exercise the full pipeline (burst cap,
 // consent, validator, capture) without waiting on a real CI build. Left
@@ -86,6 +92,11 @@ let storeRef: Store | null = null
 // be bounded by `resolveConsent` + the validator.
 let testTransportEnabled = false
 
+// First-launch `app_opened` session gate. The existing-user banner contract is:
+// no events transmit until the notice resolves. Keep "mark" and "emit"
+// atomic so no path can accidentally suppress the event without firing it.
+let appOpenedTrackedThisSession = false
+
 function buildCommonProps(installId: string, sid: string, channel: 'stable' | 'rc'): CommonProps {
   // `.max(64)` on every free-form string field in `commonPropsSchema` is the
   // upper bound; node's platform / arch / release strings are always well
@@ -110,6 +121,9 @@ export function initTelemetry(store: Store): void {
   storeRef = store
   resetBurstCapsForSession()
   shuttingDown = false
+  // Gate reset per session: the "no app_opened until banner resolution"
+  // invariant is per-launch, not across the lifetime of the install.
+  appOpenedTrackedThisSession = false
 
   if (!TELEMETRY_ENABLED || !IS_OFFICIAL_BUILD) {
     return
@@ -168,31 +182,85 @@ export function initTelemetry(store: Store): void {
     maxQueueSize: 5000
   })
 
-  // Re-apply the user's persisted opt-out on every boot: the PostHog SDK's
-  // in-memory opt-out flag does NOT persist across process restarts, and
-  // `GlobalSettings.telemetry.optedIn` is what actually gates whether a user
-  // has said yes. Do not remove this re-apply thinking it is redundant with
-  // the persisted setting; the SDK flag is the thing that gates capture().
-  const consent = resolveConsent(settings)
-  if (consent.effective !== 'enabled') {
+  if (shouldOptOutSdkAtInit(resolveConsent(settings))) {
     posthog.optOut()
   }
 }
 
+/**
+ * Decide whether to flip the PostHog SDK's in-memory `optedOut` flag at boot.
+ *
+ * Applied to DISABLED cohorts only (`user_opt_out` / CI / DO_NOT_TRACK /
+ * ORCA_TELEMETRY_DISABLED). The SDK flag does not persist across process
+ * restarts, so we re-apply on every boot as defense-in-depth: any direct
+ * `posthog.capture()` that bypasses `track()` (and therefore bypasses the
+ * consent gate in this module) must still drop at the SDK boundary for a
+ * user who has opted out.
+ *
+ * Intentionally NOT applied to `pending_banner`: the existing-user Turn-off
+ * path in `setOptIn(_, false)` does a direct `posthog.capture()` for the
+ * `telemetry_opted_out { via: 'first_launch_banner' }` signal, bypassing
+ * `track()` (see the long comment in the opt-out branch below explaining
+ * why). If the SDK were already opted-out at that point, the capture would
+ * silently drop inside posthog-core's `enqueue()` — losing the one signal
+ * that tells us the opt-out flow works. `track()`'s own consent gate
+ * (`resolveConsent() !== 'enabled'`) still drops every other event while
+ * the cohort is `pending_banner`, so there is no risk of stray transmission
+ * during the pre-banner window.
+ *
+ * Exported for tests; production has exactly one call site above.
+ */
+export function shouldOptOutSdkAtInit(consent: ConsentState): boolean {
+  return consent.effective === 'disabled'
+}
+
+function waitForCaptureEnqueue(client: PostHog, event: EventName, uuid: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false
+    let stopListening: (() => void) | null = null
+    let timeout: ReturnType<typeof setTimeout> | null = null
+
+    const settle = (enqueued: boolean): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      if (timeout) {
+        clearTimeout(timeout)
+      }
+      stopListening?.()
+      resolve(enqueued)
+    }
+
+    // Why: posthog-node's capture() prepares/enqueues asynchronously; this
+    // public SDK event is the durable boundary we need before calling optOut().
+    stopListening = client.on('capture', (payload: unknown) => {
+      if (!payload || typeof payload !== 'object') {
+        return
+      }
+      const message = payload as { event?: unknown; uuid?: unknown }
+      if (message.event === event && message.uuid === uuid) {
+        settle(true)
+      }
+    })
+
+    timeout = setTimeout(() => settle(false), OPT_OUT_CAPTURE_ENQUEUE_TIMEOUT_MS)
+  })
+}
+
+// In `pnpm dev` and any contributor / non-official build, `track()` is a
+// no-op: it returns immediately without transmitting, logging, or running
+// the burst-cap / consent / validator pipeline. Telemetry only flows in
+// official stable/rc builds where CI injects `ORCA_BUILD_IDENTITY` and
+// `ORCA_POSTHOG_WRITE_KEY`.
 export function track<N extends EventName>(name: N, props: EventProps<N>): void {
-  // Console mirror: always in non-official builds (so the whole team —
-  // contributors included — sees exactly what would transmit) and also in
-  // official builds when `TELEMETRY_ENABLED` is off (PR 2 verification).
-  // These are the only two paths that short-circuit before the pipeline.
   if (!testTransportEnabled && (!IS_OFFICIAL_BUILD || !TELEMETRY_ENABLED)) {
-    console.debug('[telemetry]', name, props)
     return
   }
 
   // (1) Shutdown gate. Late IPC arrivals should not attempt to enqueue
   // against a client that is actively flushing.
   if (shuttingDown) {
-    console.debug('[telemetry] shutdown-gate drop:', name)
     return
   }
   if (!posthog || !commonProps || !storeRef) {
@@ -241,14 +309,15 @@ export function track<N extends EventName>(name: N, props: EventProps<N>): void
   })
 }
 
-export function setOptIn(
-  via: 'settings' | 'first_launch_banner' | 'first_launch_notice',
-  optedIn: boolean
-): void {
+export async function setOptIn(via: OptInVia, optedIn: boolean): Promise<void> {
   if (!storeRef) {
     return
   }
   const settings = storeRef.getSettings()
+  const telemetryBeforeUpdate = settings.telemetry
+  const wasPendingBanner =
+    telemetryBeforeUpdate?.existedBeforeTelemetryRelease === true &&
+    telemetryBeforeUpdate.optedIn === null
   // `updateSettings` is a partial-merge (see persistence.ts:552). The Store's
   // `telemetry` field is deep-merged there specifically so an `optedIn` flip
   // from the Privacy pane / consent flow does not clobber `installId` or
@@ -260,13 +329,19 @@ export function setOptIn(
     }
   })
 
-  if (!posthog) {
-    return
-  }
+  const client = posthog
   if (optedIn) {
-    posthog.optIn()
+    if (client) {
+      await client.optIn()
+    }
+    if (wasPendingBanner) {
+      trackAppOpenedOnce()
+    }
     track('telemetry_opted_in', { via })
   } else {
+    if (!client) {
+      return
+    }
     // Fire opt-out event BEFORE disabling the SDK. This is the one event
     // that transmits against the user's new preference — the user chose to
     // tell us they are opting out, and that single signal is what tells us
@@ -279,24 +354,91 @@ export function setOptIn(
     // Burst cap + validator still run; consent is the only gate bypassed,
     // and it is bypassed exactly once per user per session at most (IPC
     // consent-mutation cap is 5/session).
-    if (!shuttingDown && commonProps && consumeBurstToken('telemetry_opted_out')) {
-      const validated = validate('telemetry_opted_out', { via })
-      if (validated.ok) {
-        posthog.capture({
-          distinctId: commonProps.install_id,
-          event: 'telemetry_opted_out',
-          properties: {
-            ...commonProps,
-            ...validated.props,
-            $process_person_profile: false
+    //
+    // posthog-node prepares capture() asynchronously, so "call capture
+    // before optOut" is not enough; wait until the SDK confirms enqueue.
+    // We do not wait for network flush here — the SDK queue and shutdown
+    // flush own delivery, while the enqueue boundary owns the optOut race.
+    try {
+      if (!shuttingDown && commonProps && consumeBurstToken('telemetry_opted_out')) {
+        const validated = validate('telemetry_opted_out', { via })
+        if (validated.ok) {
+          const uuid = randomUUID()
+          const enqueued = waitForCaptureEnqueue(client, 'telemetry_opted_out', uuid)
+          client.capture({
+            distinctId: commonProps.install_id,
+            event: 'telemetry_opted_out',
+            uuid,
+            properties: {
+              ...commonProps,
+              ...validated.props,
+              $process_person_profile: false
+            }
+          })
+          if (!(await enqueued)) {
+            console.warn('[telemetry] telemetry_opted_out did not enqueue before SDK opt-out')
           }
-        })
+        }
       }
+    } catch (err) {
+      console.warn('[telemetry] telemetry_opted_out capture failed before SDK opt-out:', err)
+    } finally {
+      await client.optOut()
     }
-    posthog.optOut()
   }
 }
 
+// Banner ✕ path. Writes `optedIn = true` permanently without emitting a
+// telemetry opt-in event. `app_opened` still fires because resolving the
+// banner is the first point where this session is eligible to transmit.
+// That outcome cannot route through `setOptIn()` — `setOptIn()` always
+// fires a `telemetry_opted_in/out` event and the IPC handler always
+// derives a non-`null` `via` value, which would tag a ✕ click as
+// `first_launch_banner` + `telemetry_opted_in`. The ✕-as-silent-
+// acknowledge contract is explicit: the user did not explicitly opt in,
+// they declined to intervene, so no opt-in event transmits.
+//
+// So this primitive exists as a named, non-overloaded code path: persist
+// the opt-in, unlock the SDK, and fire the once-per-session app-opened event.
+// The corresponding `telemetry:acknowledgeBanner` IPC channel
+// routes renderer ✕ clicks here instead of through `telemetry:setOptIn`.
+//
+// Do NOT extend this with a `via` parameter or emission flag. If a future
+// surface also needs a silent persisted opt-in, give it its own named
+// function rather than overloading this one — the grep'ability of
+// `persistBannerAcknowledgeWithoutEmitting` is the whole point.
+export async function persistBannerAcknowledgeWithoutEmitting(): Promise<void> {
+  if (!storeRef) {
+    return
+  }
+  const settings = storeRef.getSettings()
+  // Defensive merge mirrors `setOptIn`: updateSettings deep-merges the
+  // telemetry block (persistence.ts:560), so the fallback object here only
+  // matters if the migration invariant has been violated and `telemetry`
+  // is somehow absent — in which case we still want to persist an opt-in
+  // rather than no-op.
+  storeRef.updateSettings({
+    telemetry: {
+      ...(settings.telemetry ?? { installId: '', existedBeforeTelemetryRelease: true }),
+      optedIn: true
+    }
+  })
+  if (posthog) {
+    await posthog.optIn()
+  }
+  // Why: resolving the banner is the first eligible moment for app_opened.
+  // Re-enable the SDK first so capture sees the new consent state.
+  trackAppOpenedOnce()
+}
+
+export function trackAppOpenedOnce(): void {
+  if (appOpenedTrackedThisSession) {
+    return
+  }
+  appOpenedTrackedThisSession = true
+  track('app_opened', {})
+}
+
 export async function shutdownTelemetry(): Promise<void> {
   // Setting the shutdown gate is synchronous and cheap — it matters that
   // late IPC-arrived tracks hit it before the bounded flush starts.
@@ -344,3 +486,7 @@ export function _getSessionIdForTests(): string | null {
 export function _enableTransportForTests(enabled: boolean): void {
   testTransportEnabled = enabled
 }
+
+export function _resetFirstAppOpenedFiredForTests(): void {
+  appOpenedTrackedThisSession = false
+}
diff --git a/src/main/telemetry/consent.ts b/src/main/telemetry/consent.ts
index b72e79c4bb2..85ed0dfd481 100644
--- a/src/main/telemetry/consent.ts
+++ b/src/main/telemetry/consent.ts
@@ -7,6 +7,7 @@
 // the variable on the next launch restores the user's stored preference.
 
 import type { GlobalSettings } from '../../shared/types'
+import type { TelemetryConsentState } from '../../shared/telemetry-consent-types'
 
 // Discriminated union instead of a boolean: the Privacy pane (PR 3) needs the
 // `reason` to render the correct "disabled because X" helper text, and the
@@ -14,13 +15,11 @@ import type { GlobalSettings } from '../../shared/types'
 // (`pending_banner`) from "user explicitly opted out" (`disabled`). A boolean
 // would force the UI to re-derive that, re-introducing the scattered env
 // checks this module exists to eliminate.
-export type ConsentState =
-  | { effective: 'enabled' }
-  | {
-      effective: 'disabled'
-      reason: 'do_not_track' | 'orca_disabled' | 'ci' | 'user_opt_out'
-    }
-  | { effective: 'pending_banner' }
+//
+// The type itself lives in `shared/telemetry-consent-types.ts` so the
+// renderer can import it across the IPC boundary; this re-export keeps
+// existing call sites in main working without a rename.
+export type ConsentState = TelemetryConsentState
 
 // Precedence for the `disabled` branches is documented alongside
 // `resolveConsent` below.
diff --git a/src/main/telemetry/install-id.test.ts b/src/main/telemetry/install-id.test.ts
index 0bf934369ed..69591a72663 100644
--- a/src/main/telemetry/install-id.test.ts
+++ b/src/main/telemetry/install-id.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest'
 import type { Store } from '../persistence'
 import type { GlobalSettings } from '../../shared/types'
-import { generateInstallId, readInstallId, resetInstallId } from './install-id'
+import { generateInstallId, readInstallId } from './install-id'
 
 // Minimal in-memory store stand-in. The real `Store` pulls in Electron + fs,
 // which is overkill for testing the install-id read/write contract. We only
@@ -48,44 +48,4 @@ describe('install-id', () => {
       expect(readInstallId(store)).toBeUndefined()
     })
   })
-
-  describe('resetInstallId', () => {
-    it('generates a new id, persists it, and preserves sibling telemetry fields', () => {
-      const store = makeFakeStore({
-        telemetry: {
-          optedIn: true,
-          installId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
-          existedBeforeTelemetryRelease: false,
-          firstRunNoticeShown: true
-        }
-      })
-
-      const newId = resetInstallId(store)
-
-      expect(newId).not.toBe('aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa')
-      expect(newId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/)
-
-      // Read-back should reflect the new id and keep everything else intact.
-      expect(store.getSettings().telemetry).toEqual({
-        optedIn: true,
-        installId: newId,
-        existedBeforeTelemetryRelease: false,
-        firstRunNoticeShown: true
-      })
-    })
-
-    it('initializes telemetry defensively if the block is somehow missing', () => {
-      // Should not happen after migration — exercised to prove the Privacy
-      // pane button will not throw if the user reaches it before migration
-      // has run (startup-ordering bug). We prefer a usable store over a
-      // silent crash; a future maintainer should leave this branch in place.
-      const store = makeFakeStore({})
-      const newId = resetInstallId(store)
-      expect(store.getSettings().telemetry).toEqual({
-        optedIn: null,
-        installId: newId,
-        existedBeforeTelemetryRelease: true
-      })
-    })
-  })
 })
diff --git a/src/main/telemetry/install-id.ts b/src/main/telemetry/install-id.ts
index 5351c688dc9..04c6d89a61f 100644
--- a/src/main/telemetry/install-id.ts
+++ b/src/main/telemetry/install-id.ts
@@ -1,20 +1,11 @@
 import { randomUUID } from 'node:crypto'
 import type { Store } from '../persistence'
 
-// Anonymous UUID v4 that keys the user as a telemetry subject. Two contracts
-// this module must preserve:
-//
-// 1. Stability across launches. The migration in `persistence.ts` populates
-//    `GlobalSettings.telemetry.installId` once; `readInstallId` is the sole
-//    read path so call sites cannot accidentally regenerate it by reaching
-//    into the store themselves.
-//
-// 2. Rotability from the Privacy pane. `resetInstallId` generates a fresh
-//    UUID and persists it via `store.updateSettings` so the normal debounced
-//    save picks it up. PR 3 wires the Privacy pane button to this; PR 2
-//    wires the PostHog reset(). In PR 1 the reset path exists but has no
-//    caller — keeping it here (vs. client.ts) keeps pure install-id logic in
-//    one file and leaves `client.ts` a thin vendor wrapper.
+// Anonymous UUID v4 that keys the user as a telemetry subject. Stability
+// across launches is the single contract this module preserves: the
+// migration in `persistence.ts` populates `GlobalSettings.telemetry.installId`
+// once, and `readInstallId` is the sole read path so call sites cannot
+// accidentally regenerate it by reaching into the store themselves.
 
 export function generateInstallId(): string {
   return randomUUID()
@@ -28,29 +19,3 @@ export function generateInstallId(): string {
 export function readInstallId(store: Store): string | undefined {
   return store.getSettings().telemetry?.installId
 }
-
-// Rotation path used by the Privacy pane's "Reset anonymous ID" button. Why
-// `updateSettings` instead of a bespoke setter: `updateSettings` already
-// performs the deep-merge that keeps `notifications` intact, schedules the
-// 300 ms debounced save, and is the one sanctioned way to mutate persisted
-// settings. Duplicating the merge path risks dropping sibling fields on a
-// future schema addition.
-export function resetInstallId(store: Store): string {
-  const settings = store.getSettings()
-  const telemetry = settings.telemetry
-  // Defensive: migration should have populated this by the time the Privacy
-  // pane can call reset. If it somehow hasn't, initialize rather than throw
-  // — the user clicked a button; failing silently loudly is worse than
-  // returning a fresh ID.
-  const newId = generateInstallId()
-  store.updateSettings({
-    telemetry: telemetry
-      ? { ...telemetry, installId: newId }
-      : {
-          optedIn: null,
-          installId: newId,
-          existedBeforeTelemetryRelease: true
-        }
-  })
-  return newId
-}
diff --git a/src/main/telemetry/validator.test.ts b/src/main/telemetry/validator.test.ts
index 3da5b021ba2..d6619448f34 100644
--- a/src/main/telemetry/validator.test.ts
+++ b/src/main/telemetry/validator.test.ts
@@ -49,7 +49,7 @@ describe('validate', () => {
   // transmits.
   it('rejects error_message on agent_error', () => {
     const result = validate('agent_error', {
-      error_class: 'auth_expired',
+      error_class: 'unknown',
       agent_kind: 'claude-code',
       error_message: 'at /Users/alice/secret/path/index.ts:42'
     } as never)
@@ -58,7 +58,7 @@ describe('validate', () => {
 
   it('rejects error_stack on agent_error', () => {
     const result = validate('agent_error', {
-      error_class: 'auth_expired',
+      error_class: 'unknown',
       agent_kind: 'claude-code',
       error_stack: 'Error: boom\n    at /Users/alice/...'
     } as never)
@@ -83,36 +83,21 @@ describe('validate', () => {
     expect(result.ok).toBe(false)
   })
 
-  it('drops overlength strings past the .max() cap', () => {
-    // commonPropsSchema's `.max(64)` caps don't live on per-event schemas —
-    // the per-event schemas use enum-only strings — so we exercise the cap
-    // via a whitelisted `error_name` that is *one specific enum value*
-    // meaning any attempt to smuggle a long string fails the enum check
-    // regardless. For explicit string-length cap coverage we also confirm
-    // the agent_error schema does not accept an overlength error_name
-    // even if it matches the prefix of a whitelisted value.
+  it('accepts a well-formed agent_error payload', () => {
     const result = validate('agent_error', {
-      error_class: 'auth_expired',
-      agent_kind: 'claude-code',
-      error_name: 'AuthExpiredButAlsoWithExtraGarbageThatMakesItTooLong'
-    } as never)
-    expect(result.ok).toBe(false)
-  })
-
-  it('accepts whitelisted error_name on agent_error', () => {
-    const result = validate('agent_error', {
-      error_class: 'auth_expired',
-      agent_kind: 'claude-code',
-      error_name: 'AuthExpired'
+      error_class: 'binary_not_found',
+      agent_kind: 'claude-code'
     })
     expect(result.ok).toBe(true)
   })
 
-  it('rejects error_name outside the whitelist', () => {
+  it('rejects agent_error with a deferred enum value', () => {
+    // `auth_expired` was in an earlier draft; the trimmed enum is
+    // ['binary_not_found', 'unknown']. Pin that contract so re-introducing
+    // a deferred value silently is impossible.
     const result = validate('agent_error', {
       error_class: 'auth_expired',
-      agent_kind: 'claude-code',
-      error_name: 'CustomErrorNotInList'
+      agent_kind: 'claude-code'
     } as never)
     expect(result.ok).toBe(false)
   })
diff --git a/src/main/updater.ts b/src/main/updater.ts
index 72048271cee..d99f6521222 100644
--- a/src/main/updater.ts
+++ b/src/main/updater.ts
@@ -284,17 +284,20 @@ async function pinPrereleaseFeed(): Promise<void> {
   // back to the default /releases/latest/download/ URL. In the "no newer"
   // case that feed will report the latest stable and compareVersions in the
   // 'update-available' handler will correctly mark it as not-available.
-  const newerTag = await fetchNewerReleaseTag(app.getVersion())
+  const currentVersion = app.getVersion()
+  const newerTag = await fetchNewerReleaseTag(currentVersion)
+  // Why: console.info goes to stdout and is captured by Console.app on macOS
+  // and by --enable-logging elsewhere. This is the only window we have into
+  // the updater on a user's machine when something goes wrong (issue: RC user
+  // not offered newer stable). Cheap to keep, invaluable when triaging.
   if (newerTag) {
-    autoUpdater.setFeedURL({
-      provider: 'generic',
-      url: getReleaseDownloadUrl(newerTag)
-    })
+    const url = getReleaseDownloadUrl(newerTag)
+    console.info(`[updater] prerelease feed pinned: current=${currentVersion} → ${url}`)
+    autoUpdater.setFeedURL({ provider: 'generic', url })
   } else {
-    autoUpdater.setFeedURL({
-      provider: 'generic',
-      url: 'https://github.com/stablyai/orca/releases/latest/download'
-    })
+    const url = 'https://github.com/stablyai/orca/releases/latest/download'
+    console.info(`[updater] prerelease feed fallback: current=${currentVersion} → ${url}`)
+    autoUpdater.setFeedURL({ provider: 'generic', url })
   }
 }
 
@@ -509,6 +512,19 @@ export function setupAutoUpdater(
   autoUpdater.autoDownload = false
   autoUpdater.autoInstallOnAppQuit = true
 
+  // Why: the only on-machine window we have into electron-updater. Without
+  // this, an unexpected `update-not-available` (e.g. RC user not offered
+  // newer stable) is invisible — we can't tell whether the manifest fetch
+  // got the wrong version, the request failed, or a stale in-flight check
+  // was deduped. Logs go to main-process stdout, captured on macOS by
+  // Console.app under the app bundle, and on Win/Linux by --enable-logging.
+  autoUpdater.logger = {
+    info: (m: unknown) => console.info('[autoUpdater]', m),
+    warn: (m: unknown) => console.warn('[autoUpdater]', m),
+    error: (m: unknown) => console.error('[autoUpdater]', m),
+    debug: (m: unknown) => console.debug('[autoUpdater]', m)
+  } as never
+
   // Why: no Windows Authenticode certificate exists for this project.
   // electron-builder embeds the code-signing publisherName into the app's
   // bundled app-update.yml at build time. Versions that were incorrectly
diff --git a/src/main/window/attach-main-window-services.ts b/src/main/window/attach-main-window-services.ts
index 58099648cf4..0d9b54a7998 100644
--- a/src/main/window/attach-main-window-services.ts
+++ b/src/main/window/attach-main-window-services.ts
@@ -40,7 +40,8 @@ export function attachMainWindowServices(
     runtime,
     getSelectedCodexHomePath,
     () => store.getSettings(),
-    prepareClaudeAuth
+    prepareClaudeAuth,
+    store
   )
   // Why: the Manage Sessions settings panel (docs/daemon-staleness-ux.md §Phase 1)
   // uses a narrow `pty:management:*` IPC surface that reads the live
@@ -235,7 +236,9 @@ function registerRuntimeWindowLifecycle(
     closeTerminal: (tabId, paneRuntimeId) => send('ui:closeTerminal', { tabId, paneRuntimeId }),
     sleepWorktree: (worktreeId) => send('ui:sleepWorktree', { worktreeId }),
     terminalFitOverrideChanged: (ptyId, mode, cols, rows) =>
-      send('runtime:terminalFitOverrideChanged', { ptyId, mode, cols, rows })
+      send('runtime:terminalFitOverrideChanged', { ptyId, mode, cols, rows }),
+    terminalDriverChanged: (ptyId, driver) =>
+      send('runtime:terminalDriverChanged', { ptyId, driver })
   })
   // Why: the runtime must fail closed while the renderer graph is being torn
   // down or rebuilt, otherwise future CLI calls could act on stale terminal
diff --git a/src/main/window/createMainWindow.ts b/src/main/window/createMainWindow.ts
index fddf4e76d3b..597f50327c3 100644
--- a/src/main/window/createMainWindow.ts
+++ b/src/main/window/createMainWindow.ts
@@ -521,9 +521,7 @@ export function createMainWindow(
       // Why: routed through the main process so focus contexts that bypass
       // the renderer's window-level keydown (contentEditable markdown editor,
       // browser-guest webContents) still reach the new-workspace composer.
-      // Forward the target tab so Cmd/Ctrl+Shift+N lands on the
-      // "Create from…" tab instead of the default quick-create form.
-      mainWindow.webContents.send('ui:openNewWorkspace', action.tab)
+      mainWindow.webContents.send('ui:openNewWorkspace')
       return
     }
 
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 5dcbfe0a82e..5032874a8b7 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -41,8 +41,10 @@ import type {
   LinearTeam,
   MarkdownDocument,
   GitHubIssueUpdate,
+  GetRateLimitResult,
   NotificationDispatchRequest,
   NotificationDispatchResult,
+  NotificationSoundResult,
   OrcaHooks,
   PersistedUIState,
   PRCheckDetail,
@@ -61,6 +63,33 @@ import type {
   WorktreeStartupLaunch,
   WorkspaceSessionState
 } from '../shared/types'
+import type {
+  AddIssueCommentBySlugArgs,
+  ClearProjectItemFieldArgs,
+  DeleteIssueCommentBySlugArgs,
+  GetProjectViewTableArgs,
+  GetProjectViewTableResult,
+  GitHubProjectCommentMutationResult,
+  GitHubProjectMutationResult,
+  ListAccessibleProjectsResult,
+  ListAssignableUsersBySlugArgs,
+  ListAssignableUsersBySlugResult,
+  ListIssueTypesBySlugArgs,
+  ListIssueTypesBySlugResult,
+  ListLabelsBySlugArgs,
+  ListLabelsBySlugResult,
+  ListProjectViewsArgs,
+  ListProjectViewsResult,
+  ProjectWorkItemDetailsBySlugArgs,
+  ProjectWorkItemDetailsBySlugResult,
+  ResolveProjectRefArgs,
+  ResolveProjectRefResult,
+  UpdateIssueBySlugArgs,
+  UpdateIssueCommentBySlugArgs,
+  UpdateIssueTypeBySlugArgs,
+  UpdatePullRequestBySlugArgs,
+  UpdateProjectItemFieldArgs
+} from '../shared/github-project-types'
 import type {
   BrowserSetGrabModeArgs,
   BrowserSetGrabModeResult,
@@ -103,6 +132,7 @@ import type {
   ClaudeUsageSummary
 } from '../shared/claude-usage-types'
 import type { RateLimitState } from '../shared/rate-limit-types'
+import type { GhAuthDiagnostic } from '../shared/github-auth-types'
 import type {
   SshConnectionState,
   SshTarget,
@@ -119,12 +149,15 @@ import type {
   CodexUsageSessionRow,
   CodexUsageSummary
 } from '../shared/codex-usage-types'
+import type { TelemetryConsentState } from '../shared/telemetry-consent-types'
+import type { AgentKind, LaunchSource, RequestKind } from '../shared/telemetry-events'
 
 export type BrowserApi = {
   registerGuest: (args: {
     browserPageId: string
     workspaceId: string
     worktreeId: string
+    sessionProfileId?: string | null
     webContentsId: number
   }) => Promise<void>
   unregisterGuest: (args: { browserPageId: string }) => Promise<void>
@@ -418,6 +451,16 @@ export type PreloadApi = {
       // Preserved from the deleted index.d.ts PtyApi duplicate during the
       // single-source-of-truth collapse (see docs/preload-typecheck-hole.md §1).
       shellOverride?: string
+      // Why: closes the SIGKILL race documented in INVESTIGATION.md — main
+      // sync-flushes the (worktreeId, tabId, leafId → ptyId) binding before
+      // pty:spawn returns. Only the renderer's daemon-host path threads these.
+      tabId?: string
+      leafId?: string
+      // Why: telemetry-plan.md§Agent launch semantics — main emits
+      // `agent_started` only after the PTY/session is created successfully,
+      // so the renderer threads the launch metadata through this field and
+      // the IPC handler fires the event from the spawn-success branch.
+      telemetry?: { agent_kind: AgentKind; launch_source: LaunchSource; request_kind: RequestKind }
     }) => Promise<{
       id: string
       snapshot?: string
@@ -432,7 +475,7 @@ export type PreloadApi = {
     write: (id: string, data: string) => void
     resize: (id: string, cols: number, rows: number) => void
     signal: (id: string, signal: string) => void
-    kill: (id: string) => Promise<void>
+    kill: (id: string, opts?: { keepHistory?: boolean }) => Promise<void>
     ackColdRestore: (id: string) => void
     hasChildProcesses: (id: string) => Promise<boolean>
     getForegroundProcess: (id: string) => Promise<string | null>
@@ -442,12 +485,19 @@ export type PreloadApi = {
     onReplay: (callback: (data: { id: string; data: string }) => void) => () => void
     onExit: (callback: (data: { id: string; code: number }) => void) => () => void
     onSerializeBufferRequest: (
-      callback: (data: { requestId: string; ptyId: string }) => void
+      callback: (data: {
+        requestId: string
+        ptyId: string
+        opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }
+      }) => void
     ) => () => void
     sendSerializedBuffer: (
       requestId: string,
-      snapshot: { data: string; cols: number; rows: number } | null
+      snapshot: { data: string; cols: number; rows: number; lastTitle?: string } | null
     ) => void
+    declarePendingPaneSerializer: (paneKey: string) => Promise<number>
+    settlePaneSerializer: (paneKey: string, gen: number) => Promise<void>
+    clearPendingPaneSerializer: (paneKey: string, gen: number) => Promise<void>
     management: PtyManagementApi
   }
   feedback: {
@@ -461,13 +511,24 @@ export type PreloadApi = {
   gh: {
     viewer: () => Promise<GitHubViewer | null>
     repoSlug: (args: { repoPath: string }) => Promise<{ owner: string; repo: string } | null>
-    prForBranch: (args: { repoPath: string; branch: string }) => Promise<PRInfo | null>
+    prForBranch: (args: {
+      repoPath: string
+      branch: string
+      linkedPRNumber?: number | null
+    }) => Promise<PRInfo | null>
     issue: (args: { repoPath: string; number: number }) => Promise<IssueInfo | null>
     workItem: (args: {
       repoPath: string
       number: number
       type?: 'issue' | 'pr'
     }) => Promise<Omit<GitHubWorkItem, 'repoId'> | null>
+    workItemByOwnerRepo: (args: {
+      repoPath: string
+      owner: string
+      repo: string
+      number: number
+      type: 'issue' | 'pr'
+    }) => Promise<Omit<GitHubWorkItem, 'repoId'> | null>
     workItemDetails: (args: {
       repoPath: string
       number: number
@@ -541,6 +602,51 @@ export type PreloadApi = {
     listAssignableUsers: (args: { repoPath: string }) => Promise<GitHubAssignableUser[]>
     checkOrcaStarred: () => Promise<boolean | null>
     starOrca: () => Promise<boolean>
+    /**
+     * GitHub API rate-limit snapshot. Does NOT consume quota (the
+     * `rate_limit` endpoint is exempt). Cached 30s server-side — pass
+     * `force: true` to bust after a known-expensive op.
+     */
+    rateLimit: (args?: { force?: boolean }) => Promise<GetRateLimitResult>
+    /**
+     * Probe `gh auth status` and the Electron process env to explain
+     * why ProjectV2 calls are failing with scope_missing. Surfaces the
+     * common gotcha where `GITHUB_TOKEN` is exported in the user's
+     * shell and silently shadows the keyring credential — in that case
+     * `gh auth refresh` is a no-op and the UI must say so.
+     */
+    diagnoseAuth: () => Promise<GhAuthDiagnostic>
+    // ── ProjectV2 (GitHub Projects) ─────────────────────────────────
+    listAccessibleProjects: () => Promise<ListAccessibleProjectsResult>
+    resolveProjectRef: (args: ResolveProjectRefArgs) => Promise<ResolveProjectRefResult>
+    listProjectViews: (args: ListProjectViewsArgs) => Promise<ListProjectViewsResult>
+    getProjectViewTable: (args: GetProjectViewTableArgs) => Promise<GetProjectViewTableResult>
+    projectWorkItemDetailsBySlug: (
+      args: ProjectWorkItemDetailsBySlugArgs
+    ) => Promise<ProjectWorkItemDetailsBySlugResult>
+    updateProjectItemField: (
+      args: UpdateProjectItemFieldArgs
+    ) => Promise<GitHubProjectMutationResult>
+    clearProjectItemField: (args: ClearProjectItemFieldArgs) => Promise<GitHubProjectMutationResult>
+    updateIssueBySlug: (args: UpdateIssueBySlugArgs) => Promise<GitHubProjectMutationResult>
+    updatePullRequestBySlug: (
+      args: UpdatePullRequestBySlugArgs
+    ) => Promise<GitHubProjectMutationResult>
+    addIssueCommentBySlug: (
+      args: AddIssueCommentBySlugArgs
+    ) => Promise<GitHubProjectCommentMutationResult>
+    updateIssueCommentBySlug: (
+      args: UpdateIssueCommentBySlugArgs
+    ) => Promise<GitHubProjectMutationResult>
+    deleteIssueCommentBySlug: (
+      args: DeleteIssueCommentBySlugArgs
+    ) => Promise<GitHubProjectMutationResult>
+    listLabelsBySlug: (args: ListLabelsBySlugArgs) => Promise<ListLabelsBySlugResult>
+    listAssignableUsersBySlug: (
+      args: ListAssignableUsersBySlugArgs
+    ) => Promise<ListAssignableUsersBySlugResult>
+    listIssueTypesBySlug: (args: ListIssueTypesBySlugArgs) => Promise<ListIssueTypesBySlugResult>
+    updateIssueTypeBySlug: (args: UpdateIssueTypeBySlugArgs) => Promise<GitHubProjectMutationResult>
   }
   linear: {
     connect: (args: {
@@ -590,6 +696,19 @@ export type PreloadApi = {
   /** Flip the persisted opt-in preference. Subject to a per-session
    *  consent-mutation rate limit on the main side (≤5/session). */
   telemetrySetOptIn: (optedIn: boolean) => Promise<void>
+  /** Read-only view of effective consent state, including the reason if
+   *  disabled (env var / user opt-out / CI / pending banner). Used by the
+   *  Privacy pane to render the correct "blocked by X" helper text — env
+   *  vars are main-side state the renderer cannot read directly. */
+  telemetryGetConsentState: () => Promise<TelemetryConsentState>
+  /** Banner ✕ — persist `optedIn = true` silently, emit nothing. Deliberately
+   *  a separate channel from `telemetrySetOptIn` because main's `via`
+   *  derivation on that channel would tag this path as `first_launch_banner`
+   *  and fire `telemetry_opted_in`, which the ✕-as-silent-acknowledge
+   *  semantics forbid (the user did not explicitly opt in, they declined to
+   *  intervene). Subject to the same per-session consent-mutation rate
+   *  limit as `telemetrySetOptIn`. */
+  telemetryAcknowledgeBanner: () => Promise<void>
   settings: {
     get: () => Promise<GlobalSettings>
     set: (args: Partial<GlobalSettings>) => Promise<GlobalSettings>
@@ -625,10 +744,14 @@ export type PreloadApi = {
     geminiStatus: () => Promise<AgentHookInstallStatus>
     cursorStatus: () => Promise<AgentHookInstallStatus>
   }
+  agentTrust: {
+    markTrusted: (args: { preset: 'cursor' | 'copilot'; workspacePath: string }) => Promise<void>
+  }
   preflight: PreflightApi
   notifications: {
     dispatch: (args: NotificationDispatchRequest) => Promise<NotificationDispatchResult>
     openSystemSettings: () => Promise<void>
+    playSound: (options?: { force?: boolean }) => Promise<NotificationSoundResult>
   }
   developerPermissions: {
     getStatus: () => Promise<DeveloperPermissionState[]>
@@ -643,13 +766,15 @@ export type PreloadApi = {
     pathExists: (path: string) => Promise<boolean>
     pickAttachment: () => Promise<string | null>
     pickImage: () => Promise<string | null>
+    pickAudio: () => Promise<string | null>
     pickDirectory: (args: { defaultPath?: string }) => Promise<string | null>
     copyFile: (args: { srcPath: string; destPath: string }) => Promise<void>
   }
   sidekick: {
     import: () => Promise<CustomSidekick | null>
-    read: (id: string, fileName: string) => Promise<ArrayBuffer | null>
-    delete: (id: string, fileName: string) => Promise<void>
+    importPetBundle: () => Promise<CustomSidekick | null>
+    read: (id: string, fileName: string, kind?: 'image' | 'bundle') => Promise<ArrayBuffer | null>
+    delete: (id: string, fileName: string, kind?: 'image' | 'bundle') => Promise<void>
   }
   browser: BrowserApi
   hooks: {
@@ -847,14 +972,23 @@ export type PreloadApi = {
     onToggleRightSidebar: (callback: () => void) => () => void
     onToggleWorktreePalette: (callback: () => void) => () => void
     onOpenQuickOpen: (callback: () => void) => () => void
-    onOpenNewWorkspace: (callback: (tab: 'quick' | 'create-from') => void) => () => void
+    onOpenNewWorkspace: (callback: () => void) => () => void
     onJumpToWorktreeIndex: (callback: (index: number) => void) => () => void
     onWorktreeHistoryNavigate: (callback: (direction: 'back' | 'forward') => void) => () => void
     onNewBrowserTab: (callback: () => void) => () => void
     onRequestTabCreate: (
-      callback: (data: { requestId: string; url: string; worktreeId?: string }) => void
+      callback: (data: {
+        requestId: string
+        url: string
+        worktreeId?: string
+        sessionProfileId?: string
+      }) => void
     ) => () => void
     replyTabCreate: (reply: { requestId: string; browserPageId?: string; error?: string }) => void
+    onRequestTabSetProfile: (
+      callback: (data: { requestId: string; browserPageId: string; profileId: string }) => void
+    ) => () => void
+    replyTabSetProfile: (reply: { requestId: string; error?: string }) => void
     onRequestTabClose: (
       callback: (data: { requestId: string; tabId: string | null; worktreeId?: string }) => void
     ) => () => void
@@ -949,6 +1083,12 @@ export type PreloadApi = {
         rows: number
       }) => void
     ) => () => void
+    onTerminalDriverChanged: (
+      callback: (event: {
+        ptyId: string
+        driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
+      }) => void
+    ) => () => void
   }
   rateLimits: {
     get: () => Promise<RateLimitState>
@@ -970,6 +1110,7 @@ export type PreloadApi = {
     connect: (args: { targetId: string }) => Promise<SshConnectionState | null>
     disconnect: (args: { targetId: string }) => Promise<void>
     getState: (args: { targetId: string }) => Promise<SshConnectionState | null>
+    needsPassphrasePrompt: (args: { targetId: string }) => Promise<boolean>
     testConnection: (args: {
       targetId: string
     }) => Promise<{ success: boolean; error?: string; state?: SshConnectionState }>
@@ -1042,11 +1183,15 @@ export type PreloadApi = {
     listNetworkInterfaces: () => Promise<{
       interfaces: { name: string; address: string }[]
     }>
-    getPairingQR: (args?: {
-      address?: string
-    }) => Promise<
+    getPairingQR: (args?: { address?: string }) => Promise<
       | { available: false }
-      | { available: true; qrDataUrl: string; endpoint: string; deviceId: string }
+      | {
+          available: true
+          qrDataUrl: string
+          pairingUrl: string
+          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 87dcefa62a9..5feda7fed4e 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -13,6 +13,7 @@ import type {
   CreateWorktreeArgs,
   CustomSidekick,
   FsChangedPayload,
+  GetRateLimitResult,
   GitHubAssignableUser,
   GitHubCommentResult,
   GitHubWorkItem,
@@ -20,10 +21,41 @@ import type {
   ListWorkItemsResult,
   MemorySnapshot,
   NotificationDispatchResult,
+  NotificationSoundDataResult,
+  NotificationSoundPathResult,
+  NotificationSoundResult,
   SearchResult
 } from '../shared/types'
 import type { RuntimeStatus, RuntimeSyncWindowGraph } from '../shared/runtime-types'
 import type { RateLimitState } from '../shared/rate-limit-types'
+import type { GhAuthDiagnostic } from '../shared/github-auth-types'
+import type {
+  AddIssueCommentBySlugArgs,
+  ClearProjectItemFieldArgs,
+  DeleteIssueCommentBySlugArgs,
+  GetProjectViewTableArgs,
+  GetProjectViewTableResult,
+  GitHubProjectCommentMutationResult,
+  GitHubProjectMutationResult,
+  ListAccessibleProjectsResult,
+  ListAssignableUsersBySlugArgs,
+  ListAssignableUsersBySlugResult,
+  ListIssueTypesBySlugArgs,
+  ListIssueTypesBySlugResult,
+  ListLabelsBySlugArgs,
+  ListLabelsBySlugResult,
+  ListProjectViewsArgs,
+  ListProjectViewsResult,
+  ProjectWorkItemDetailsBySlugArgs,
+  ProjectWorkItemDetailsBySlugResult,
+  ResolveProjectRefArgs,
+  ResolveProjectRefResult,
+  UpdateIssueBySlugArgs,
+  UpdateIssueCommentBySlugArgs,
+  UpdateIssueTypeBySlugArgs,
+  UpdatePullRequestBySlugArgs,
+  UpdateProjectItemFieldArgs
+} from '../shared/github-project-types'
 import type {
   SshConnectionState,
   SshTarget,
@@ -31,6 +63,8 @@ import type {
   DetectedPort
 } from '../shared/ssh-types'
 import type { AgentStatusState } from '../shared/agent-status-types'
+import type { TelemetryConsentState } from '../shared/telemetry-consent-types'
+import type { AgentKind, LaunchSource, RequestKind } from '../shared/telemetry-events'
 import {
   ORCA_EDITOR_SAVE_DIRTY_FILES_EVENT,
   type EditorSaveDirtyFilesDetail
@@ -50,6 +84,29 @@ type NativeDropResolution =
   // falling back to 'editor' — fail-closed behavior per design §7.1.
   | { target: 'rejected' }
 
+// Why: one shared HTMLAudioElement per sound file, restarted from t=0 on each
+// play, with an in-flight guard that drops new plays while the sound is still
+// ringing. This mirrors VS Code's AccessibilitySignalService and GNOME's
+// libcanberra: a burst of triggers self-dedupes by the sound's own duration
+// (no magic time constant), while distinct sounds are still allowed to overlap.
+// We also cache the decoded blob URL by path so we don't re-read 10MB from
+// disk and re-transfer it over IPC on every notification.
+let cachedNotificationSound: {
+  path: string
+  blobUrl: string
+  audio: HTMLAudioElement
+} | null = null
+let isNotificationSoundPlaying = false
+
+function disposeCachedNotificationSound(): void {
+  if (cachedNotificationSound) {
+    cachedNotificationSound.audio.pause()
+    cachedNotificationSound.audio.src = ''
+    URL.revokeObjectURL(cachedNotificationSound.blobUrl)
+    cachedNotificationSound = null
+  }
+}
+
 /**
  * Walk the composed event path to classify which UI surface the native OS drop
  * landed on, and — for file-explorer drops — extract the nearest destination
@@ -328,6 +385,18 @@ const api = {
       worktreeId?: string
       sessionId?: string
       shellOverride?: string
+      // Why: closes the SIGKILL race documented in INVESTIGATION.md by
+      // letting main patch + sync-flush the (worktreeId, tabId, leafId →
+      // ptyId) binding before pty:spawn returns. Only the renderer's
+      // user-typing-Ctrl+T daemon-host path threads these.
+      tabId?: string
+      leafId?: string
+      // Why: telemetry-plan.md§Agent launch semantics — main fires
+      // `agent_started` only after the spawn succeeds. The renderer is the
+      // source of truth for the launch metadata; main is the source of
+      // truth for whether the launch happened. Loose typing here on
+      // purpose: validation lives at the main-side schema validator.
+      telemetry?: { agent_kind: AgentKind; launch_source: LaunchSource; request_kind: RequestKind }
     }): Promise<{
       id: string
       snapshot?: string
@@ -356,7 +425,8 @@ const api = {
       ipcRenderer.send('pty:ackColdRestore', { id })
     },
 
-    kill: (id: string): Promise<void> => ipcRenderer.invoke('pty:kill', { id }),
+    kill: (id: string, opts?: { keepHistory?: boolean }): Promise<void> =>
+      ipcRenderer.invoke('pty:kill', { id, keepHistory: opts?.keepHistory ?? false }),
 
     listSessions: (): Promise<{ id: string; cwd: string; title: string }[]> =>
       ipcRenderer.invoke('pty:listSessions'),
@@ -396,11 +466,19 @@ const api = {
     },
 
     onSerializeBufferRequest: (
-      callback: (data: { requestId: string; ptyId: string }) => void
+      callback: (data: {
+        requestId: string
+        ptyId: string
+        opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }
+      }) => void
     ): (() => void) => {
       const listener = (
         _event: Electron.IpcRendererEvent,
-        data: { requestId: string; ptyId: string }
+        data: {
+          requestId: string
+          ptyId: string
+          opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean }
+        }
       ) => callback(data)
       ipcRenderer.on('pty:serializeBuffer:request', listener)
       return () => ipcRenderer.removeListener('pty:serializeBuffer:request', listener)
@@ -408,11 +486,25 @@ const api = {
 
     sendSerializedBuffer: (
       requestId: string,
-      snapshot: { data: string; cols: number; rows: number } | null
+      snapshot: { data: string; cols: number; rows: number; lastTitle?: string } | null
     ): void => {
       ipcRenderer.send('pty:serializeBuffer:response', { requestId, snapshot })
     },
 
+    // Why: pre-signal handshake — renderer declares it will own the serializer
+    // for `paneKey` BEFORE issuing pty:spawn so the cooperation gate in main
+    // can suppress the daemon-snapshot seed. Returns a generation token that
+    // the renderer must echo on settle/clear so paneKey-reuse during teardown
+    // cannot defeat the pre-signal. See docs/mobile-prefer-renderer-scrollback.md.
+    declarePendingPaneSerializer: (paneKey: string): Promise<number> =>
+      ipcRenderer.invoke('pty:declarePendingPaneSerializer', { paneKey }),
+
+    settlePaneSerializer: (paneKey: string, gen: number): Promise<void> =>
+      ipcRenderer.invoke('pty:settlePaneSerializer', { paneKey, gen }),
+
+    clearPendingPaneSerializer: (paneKey: string, gen: number): Promise<void> =>
+      ipcRenderer.invoke('pty:clearPendingPaneSerializer', { paneKey, gen }),
+
     management: {
       listSessions: () => ipcRenderer.invoke('pty:management:listSessions'),
       killAll: () => ipcRenderer.invoke('pty:management:killAll'),
@@ -445,8 +537,11 @@ const api = {
     repoSlug: (args: { repoPath: string }): Promise<unknown> =>
       ipcRenderer.invoke('gh:repoSlug', args),
 
-    prForBranch: (args: { repoPath: string; branch: string }): Promise<unknown> =>
-      ipcRenderer.invoke('gh:prForBranch', args),
+    prForBranch: (args: {
+      repoPath: string
+      branch: string
+      linkedPRNumber?: number | null
+    }): Promise<unknown> => ipcRenderer.invoke('gh:prForBranch', args),
 
     issue: (args: { repoPath: string; number: number }): Promise<unknown> =>
       ipcRenderer.invoke('gh:issue', args),
@@ -457,6 +552,14 @@ const api = {
       type?: 'issue' | 'pr'
     }): Promise<unknown> => ipcRenderer.invoke('gh:workItem', args),
 
+    workItemByOwnerRepo: (args: {
+      repoPath: string
+      owner: string
+      repo: string
+      number: number
+      type: 'issue' | 'pr'
+    }): Promise<unknown> => ipcRenderer.invoke('gh:workItemByOwnerRepo', args),
+
     workItemDetails: (args: {
       repoPath: string
       number: number
@@ -566,7 +669,65 @@ const api = {
       ipcRenderer.invoke('gh:listAssignableUsers', args),
 
     checkOrcaStarred: (): Promise<boolean | null> => ipcRenderer.invoke('gh:checkOrcaStarred'),
-    starOrca: (): Promise<boolean> => ipcRenderer.invoke('gh:starOrca')
+    starOrca: (): Promise<boolean> => ipcRenderer.invoke('gh:starOrca'),
+
+    // Why: rate_limit is exempt from rate-limit accounting, but we still pass
+    // `force` through so callers can bust the 30s in-process cache after a
+    // known-expensive op (e.g. after ProjectPicker discovery).
+    rateLimit: (args?: { force?: boolean }): Promise<GetRateLimitResult> =>
+      ipcRenderer.invoke('gh:rateLimit', args),
+
+    diagnoseAuth: (): Promise<GhAuthDiagnostic> => ipcRenderer.invoke('gh:diagnoseAuth'),
+
+    // ── ProjectV2 (GitHub Projects) ───────────────────────────────────
+    listAccessibleProjects: (): Promise<ListAccessibleProjectsResult> =>
+      ipcRenderer.invoke('gh:listAccessibleProjects'),
+    resolveProjectRef: (args: ResolveProjectRefArgs): Promise<ResolveProjectRefResult> =>
+      ipcRenderer.invoke('gh:resolveProjectRef', args),
+    listProjectViews: (args: ListProjectViewsArgs): Promise<ListProjectViewsResult> =>
+      ipcRenderer.invoke('gh:listProjectViews', args),
+    getProjectViewTable: (args: GetProjectViewTableArgs): Promise<GetProjectViewTableResult> =>
+      ipcRenderer.invoke('gh:getProjectViewTable', args),
+    projectWorkItemDetailsBySlug: (
+      args: ProjectWorkItemDetailsBySlugArgs
+    ): Promise<ProjectWorkItemDetailsBySlugResult> =>
+      ipcRenderer.invoke('gh:projectWorkItemDetailsBySlug', args),
+    updateProjectItemField: (
+      args: UpdateProjectItemFieldArgs
+    ): Promise<GitHubProjectMutationResult> =>
+      ipcRenderer.invoke('gh:updateProjectItemField', args),
+    clearProjectItemField: (
+      args: ClearProjectItemFieldArgs
+    ): Promise<GitHubProjectMutationResult> => ipcRenderer.invoke('gh:clearProjectItemField', args),
+    updateIssueBySlug: (args: UpdateIssueBySlugArgs): Promise<GitHubProjectMutationResult> =>
+      ipcRenderer.invoke('gh:updateIssueBySlug', args),
+    updatePullRequestBySlug: (
+      args: UpdatePullRequestBySlugArgs
+    ): Promise<GitHubProjectMutationResult> =>
+      ipcRenderer.invoke('gh:updatePullRequestBySlug', args),
+    addIssueCommentBySlug: (
+      args: AddIssueCommentBySlugArgs
+    ): Promise<GitHubProjectCommentMutationResult> =>
+      ipcRenderer.invoke('gh:addIssueCommentBySlug', args),
+    updateIssueCommentBySlug: (
+      args: UpdateIssueCommentBySlugArgs
+    ): Promise<GitHubProjectMutationResult> =>
+      ipcRenderer.invoke('gh:updateIssueCommentBySlug', args),
+    deleteIssueCommentBySlug: (
+      args: DeleteIssueCommentBySlugArgs
+    ): Promise<GitHubProjectMutationResult> =>
+      ipcRenderer.invoke('gh:deleteIssueCommentBySlug', args),
+    listLabelsBySlug: (args: ListLabelsBySlugArgs): Promise<ListLabelsBySlugResult> =>
+      ipcRenderer.invoke('gh:listLabelsBySlug', args),
+    listAssignableUsersBySlug: (
+      args: ListAssignableUsersBySlugArgs
+    ): Promise<ListAssignableUsersBySlugResult> =>
+      ipcRenderer.invoke('gh:listAssignableUsersBySlug', args),
+    listIssueTypesBySlug: (args: ListIssueTypesBySlugArgs): Promise<ListIssueTypesBySlugResult> =>
+      ipcRenderer.invoke('gh:listIssueTypesBySlug', args),
+    updateIssueTypeBySlug: (
+      args: UpdateIssueTypeBySlugArgs
+    ): Promise<GitHubProjectMutationResult> => ipcRenderer.invoke('gh:updateIssueTypeBySlug', args)
   },
 
   linear: {
@@ -648,6 +809,10 @@ const api = {
     ipcRenderer.invoke('telemetry:track', name, props),
   telemetrySetOptIn: (optedIn: boolean): Promise<void> =>
     ipcRenderer.invoke('telemetry:setOptIn', optedIn),
+  telemetryAcknowledgeBanner: (): Promise<void> =>
+    ipcRenderer.invoke('telemetry:acknowledgeBanner'),
+  telemetryGetConsentState: (): Promise<TelemetryConsentState> =>
+    ipcRenderer.invoke('telemetry:getConsentState'),
 
   settings: {
     get: (): Promise<unknown> => ipcRenderer.invoke('settings:get'),
@@ -709,6 +874,11 @@ const api = {
       ipcRenderer.invoke('agentHooks:cursorStatus')
   },
 
+  agentTrust: {
+    markTrusted: (args: { preset: 'cursor' | 'copilot'; workspacePath: string }): Promise<void> =>
+      ipcRenderer.invoke('agentTrust:markTrusted', args)
+  },
+
   preflight: {
     check: (args?: {
       force?: boolean
@@ -730,7 +900,66 @@ const api = {
   notifications: {
     dispatch: (args: Record<string, unknown>): Promise<NotificationDispatchResult> =>
       ipcRenderer.invoke('notifications:dispatch', args),
-    openSystemSettings: (): Promise<void> => ipcRenderer.invoke('notifications:openSystemSettings')
+    openSystemSettings: (): Promise<void> => ipcRenderer.invoke('notifications:openSystemSettings'),
+    playSound: async (options?: { force?: boolean }): Promise<NotificationSoundResult> => {
+      try {
+        // Why: drop replays while the sound is still ringing. The "test"
+        // button bypasses with force so the user always hears a confirmation.
+        if (!options?.force && isNotificationSoundPlaying) {
+          return { played: false, reason: 'deduped' }
+        }
+
+        const resolved = (await ipcRenderer.invoke(
+          'notifications:resolveSoundPath'
+        )) as NotificationSoundPathResult
+        if (!resolved.ok) {
+          if (cachedNotificationSound) {
+            disposeCachedNotificationSound()
+          }
+          return { played: false, reason: resolved.reason }
+        }
+
+        let entry = cachedNotificationSound
+        if (!entry || entry.path !== resolved.path) {
+          const sound = (await ipcRenderer.invoke(
+            'notifications:loadSound'
+          )) as NotificationSoundDataResult
+          if (!sound.ok) {
+            disposeCachedNotificationSound()
+            return { played: false, reason: sound.reason }
+          }
+          const arrayBuffer = new ArrayBuffer(sound.data.byteLength)
+          new Uint8Array(arrayBuffer).set(sound.data)
+          const blob = new Blob([arrayBuffer], { type: sound.mimeType })
+          disposeCachedNotificationSound()
+          const blobUrl = URL.createObjectURL(blob)
+          entry = { path: sound.path, blobUrl, audio: new Audio(blobUrl) }
+          cachedNotificationSound = entry
+        }
+
+        const audio = entry.audio
+        // Why: restart-from-zero on every play so a burst of triggers replays
+        // the sound from the start instead of stacking overlapping copies.
+        // Matches GNOME canberra and VS Code AccessibilitySignalService.
+        audio.currentTime = 0
+        isNotificationSoundPlaying = true
+        const release = (): void => {
+          isNotificationSoundPlaying = false
+        }
+        audio.addEventListener('ended', release, { once: true })
+        audio.addEventListener('error', release, { once: true })
+        try {
+          await audio.play()
+        } catch {
+          release()
+          return { played: false, reason: 'playback-failed' }
+        }
+        return { played: true }
+      } catch {
+        isNotificationSoundPlaying = false
+        return { played: false, reason: 'playback-failed' }
+      }
+    }
   },
 
   developerPermissions: {
@@ -756,6 +985,8 @@ const api = {
 
     pickImage: (): Promise<string | null> => ipcRenderer.invoke('shell:pickImage'),
 
+    pickAudio: (): Promise<string | null> => ipcRenderer.invoke('shell:pickAudio'),
+
     pickDirectory: (args: { defaultPath?: string }): Promise<string | null> =>
       ipcRenderer.invoke('shell:pickDirectory', args),
 
@@ -765,10 +996,12 @@ const api = {
 
   sidekick: {
     import: (): Promise<CustomSidekick | null> => ipcRenderer.invoke('sidekick:import'),
-    read: (id: string, fileName: string): Promise<ArrayBuffer | null> =>
-      ipcRenderer.invoke('sidekick:read', id, fileName),
-    delete: (id: string, fileName: string): Promise<void> =>
-      ipcRenderer.invoke('sidekick:delete', id, fileName)
+    importPetBundle: (): Promise<CustomSidekick | null> =>
+      ipcRenderer.invoke('sidekick:importPetBundle'),
+    read: (id: string, fileName: string, kind?: 'image' | 'bundle'): Promise<ArrayBuffer | null> =>
+      ipcRenderer.invoke('sidekick:read', id, fileName, kind),
+    delete: (id: string, fileName: string, kind?: 'image' | 'bundle'): Promise<void> =>
+      ipcRenderer.invoke('sidekick:delete', id, fileName, kind)
   },
 
   browser: {
@@ -776,6 +1009,7 @@ const api = {
       browserPageId: string
       workspaceId: string
       worktreeId: string
+      sessionProfileId?: string | null
       webContentsId: number
     }): Promise<void> => ipcRenderer.invoke('browser:registerGuest', args),
 
@@ -1362,13 +1596,8 @@ const api = {
       ipcRenderer.on('ui:openQuickOpen', listener)
       return () => ipcRenderer.removeListener('ui:openQuickOpen', listener)
     },
-    onOpenNewWorkspace: (callback: (tab: 'quick' | 'create-from') => void): (() => void) => {
-      const listener = (_event: Electron.IpcRendererEvent, tab: 'quick' | 'create-from') => {
-        // Why: older main-process builds may send this event without a payload
-        // — default to 'quick' so the preload contract stays forward-compatible
-        // during a partial rollout where only one side has shipped the tab arg.
-        callback(tab ?? 'quick')
-      }
+    onOpenNewWorkspace: (callback: () => void): (() => void) => {
+      const listener = (_event: Electron.IpcRendererEvent) => callback()
       ipcRenderer.on('ui:openNewWorkspace', listener)
       return () => ipcRenderer.removeListener('ui:openNewWorkspace', listener)
     },
@@ -1391,11 +1620,16 @@ const api = {
       return () => ipcRenderer.removeListener('ui:newBrowserTab', listener)
     },
     onRequestTabCreate: (
-      callback: (data: { requestId: string; url: string; worktreeId?: string }) => void
+      callback: (data: {
+        requestId: string
+        url: string
+        worktreeId?: string
+        sessionProfileId?: string
+      }) => void
     ): (() => void) => {
       const listener = (
         _event: Electron.IpcRendererEvent,
-        data: { requestId: string; url: string; worktreeId?: string }
+        data: { requestId: string; url: string; worktreeId?: string; sessionProfileId?: string }
       ) => callback(data)
       ipcRenderer.on('browser:requestTabCreate', listener)
       return () => ipcRenderer.removeListener('browser:requestTabCreate', listener)
@@ -1407,6 +1641,19 @@ const api = {
     }): void => {
       ipcRenderer.send('browser:tabCreateReply', reply)
     },
+    onRequestTabSetProfile: (
+      callback: (data: { requestId: string; browserPageId: string; profileId: string }) => void
+    ): (() => void) => {
+      const listener = (
+        _event: Electron.IpcRendererEvent,
+        data: { requestId: string; browserPageId: string; profileId: string }
+      ) => callback(data)
+      ipcRenderer.on('browser:requestTabSetProfile', listener)
+      return () => ipcRenderer.removeListener('browser:requestTabSetProfile', listener)
+    },
+    replyTabSetProfile: (reply: { requestId: string; error?: string }): void => {
+      ipcRenderer.send('browser:tabSetProfileReply', reply)
+    },
     onRequestTabClose: (
       callback: (data: { requestId: string; tabId: string | null; worktreeId?: string }) => void
     ): (() => void) => {
@@ -1729,6 +1976,22 @@ const api = {
       ) => callback(data)
       ipcRenderer.on('runtime:terminalFitOverrideChanged', listener)
       return () => ipcRenderer.removeListener('runtime:terminalFitOverrideChanged', listener)
+    },
+    onTerminalDriverChanged: (
+      callback: (event: {
+        ptyId: string
+        driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
+      }) => void
+    ): (() => void) => {
+      const listener = (
+        _event: Electron.IpcRendererEvent,
+        data: {
+          ptyId: string
+          driver: { kind: 'idle' } | { kind: 'desktop' } | { kind: 'mobile'; clientId: string }
+        }
+      ) => callback(data)
+      ipcRenderer.on('runtime:terminalDriverChanged', listener)
+      return () => ipcRenderer.removeListener('runtime:terminalDriverChanged', listener)
     }
   },
 
@@ -1773,6 +2036,9 @@ const api = {
     getState: (args: { targetId: string }): Promise<SshConnectionState | null> =>
       ipcRenderer.invoke('ssh:getState', args),
 
+    needsPassphrasePrompt: (args: { targetId: string }): Promise<boolean> =>
+      ipcRenderer.invoke('ssh:needsPassphrasePrompt', args),
+
     testConnection: (args: {
       targetId: string
     }): Promise<{ success: boolean; error?: string; state?: SshConnectionState }> =>
@@ -1889,7 +2155,13 @@ const api = {
       address?: string
     }): Promise<
       | { available: false }
-      | { available: true; qrDataUrl: string; endpoint: string; deviceId: string }
+      | {
+          available: true
+          qrDataUrl: string
+          pairingUrl: string
+          endpoint: string
+          deviceId: string
+        }
     > => ipcRenderer.invoke('mobile:getPairingQR', args),
 
     listDevices: (): Promise<{
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 2a60b19024f..f9ad204936f 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -3,12 +3,10 @@ import { lazy, Suspense, useEffect, useLayoutEffect, useMemo, useRef, useState }
 import { DEFAULT_STATUS_BAR_ITEMS, DEFAULT_WORKTREE_CARD_PROPERTIES } from '../../shared/constants'
 
 import { ArrowLeft, ArrowRight, Minimize2, PanelLeft, PanelRight } from 'lucide-react'
-import {
-  FOCUS_TERMINAL_PANE_EVENT,
-  SYNC_FIT_PANES_EVENT,
-  TOGGLE_TERMINAL_PANE_EXPAND_EVENT
-} from '@/constants/terminal'
+import { SYNC_FIT_PANES_EVENT, TOGGLE_TERMINAL_PANE_EXPAND_EVENT } from '@/constants/terminal'
 import { syncZoomCSSVar } from '@/lib/ui-zoom'
+import { buildAppFontFamily } from '@/lib/app-font-family'
+import { activateTabAndFocusPane } from '@/lib/activate-tab-and-focus-pane'
 import { toast } from 'sonner'
 import { Toaster } from '@/components/ui/sonner'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
@@ -18,11 +16,12 @@ import { useIpcEvents } from './hooks/useIpcEvents'
 import RetainedAgentsSyncGate from './components/dashboard/RetainedAgentsSyncGate'
 import Sidebar from './components/Sidebar'
 import Terminal from './components/Terminal'
-import { shutdownBufferCaptures } from './components/terminal-pane/TerminalPane'
+import { shutdownBufferCaptures } from './components/terminal-pane/shutdown-buffer-captures'
 import RightSidebar from './components/right-sidebar'
 import { StatusBar } from './components/status-bar/StatusBar'
 import { UpdateCard } from './components/UpdateCard'
 import { StarNagCard } from './components/StarNagCard'
+import { TelemetryFirstLaunchSurface } from './components/TelemetryFirstLaunchSurface'
 import { ZoomOverlay } from './components/ZoomOverlay'
 import { SshPassphraseDialog } from './components/settings/SshPassphraseDialog'
 import { useGitStatusPolling } from './components/right-sidebar/useGitStatusPolling'
@@ -37,6 +36,7 @@ import { registerUpdaterBeforeUnloadBypass } from './lib/updater-beforeunload'
 import { buildWorkspaceSessionPayload } from './lib/workspace-session'
 import { countWorkingAgents, getWorkingAgentsPerWorktree } from './lib/agent-status'
 import { activateAndRevealWorktree } from './lib/worktree-activation'
+import { applyDocumentTheme } from './lib/document-theme'
 import { Popover, PopoverTrigger, PopoverContent } from '@/components/ui/popover'
 import { findWorktreeById, getRepoIdFromWorktreeId } from '@/store/slices/worktree-helpers'
 import {
@@ -435,7 +435,7 @@ function App(): React.JSX.Element {
       if (!useAppStore.getState().workspaceSessionReady) {
         return
       }
-      for (const capture of shutdownBufferCaptures) {
+      for (const capture of shutdownBufferCaptures.values()) {
         try {
           capture()
         } catch {
@@ -497,26 +497,29 @@ function App(): React.JSX.Element {
       return
     }
 
-    const applyTheme = (dark: boolean): void => {
-      document.documentElement.classList.toggle('dark', dark)
-    }
-
     if (settings.theme === 'dark') {
-      applyTheme(true)
+      applyDocumentTheme('dark')
       return undefined
     } else if (settings.theme === 'light') {
-      applyTheme(false)
+      applyDocumentTheme('light')
       return undefined
     } else {
       // system
       const mq = window.matchMedia('(prefers-color-scheme: dark)')
-      applyTheme(mq.matches)
-      const handler = (e: MediaQueryListEvent): void => applyTheme(e.matches)
+      applyDocumentTheme('system')
+      const handler = (): void => applyDocumentTheme('system')
       mq.addEventListener('change', handler)
       return () => mq.removeEventListener('change', handler)
     }
   }, [settings])
 
+  useEffect(() => {
+    document.documentElement.style.setProperty(
+      '--app-font-family',
+      buildAppFontFamily(settings?.appFontFamily)
+    )
+  }, [settings?.appFontFamily])
+
   // Refresh GitHub data (PR/issue status) when window regains focus
   useEffect(() => {
     const handler = (): void => {
@@ -838,22 +841,7 @@ function App(): React.JSX.Element {
                             className="titlebar-agent-hovercard-agent"
                             onClick={() => {
                               activateAndRevealWorktree(worktreeId)
-                              useAppStore.getState().setActiveTab(agent.tabId)
-                              if (agent.paneId !== null) {
-                                // Why: a split-terminal tab can host multiple
-                                // agents. After selecting the tab, wait one
-                                // frame so the active TerminalPane can mount
-                                // and then focus the specific pane the user
-                                // clicked instead of leaving whichever pane
-                                // was previously active highlighted.
-                                requestAnimationFrame(() => {
-                                  window.dispatchEvent(
-                                    new CustomEvent(FOCUS_TERMINAL_PANE_EVENT, {
-                                      detail: { tabId: agent.tabId, paneId: agent.paneId }
-                                    })
-                                  )
-                                })
-                              }
+                              activateTabAndFocusPane(agent.tabId, agent.paneId)
                             }}
                           >
                             <span className="titlebar-agent-hovercard-agent-label">
@@ -969,118 +957,130 @@ function App(): React.JSX.Element {
             The hooks' internal early-returns remain as defense-in-depth
             (see the comment above useIpcEvents()). */}
         {agentDashboardEnabled ? <RetainedAgentsSyncGate /> : null}
-        {/* Why: in workspace view (split groups always enabled), the full-width
-            titlebar is removed so tab groups + terminal extend to the top of
-            the window. Left titlebar controls move to a header above the sidebar.
-            Settings, landing, and the tasks page keep the full-width titlebar. */}
-        {!workspaceActive ? (
-          <div className="titlebar">
-            <div
-              className={`flex items-center${showSidebar && sidebarOpen ? ' overflow-hidden shrink-0' : ' shrink-0 mr-2'}`}
-              style={{ width: showSidebar && sidebarOpen ? sidebarWidth : undefined }}
-            >
-              {titlebarLeftControls}
-            </div>
-            <div
-              id="titlebar-tabs"
-              className={`flex flex-1 min-w-0 self-stretch${activeView !== 'terminal' || !activeWorktreeId ? ' invisible pointer-events-none' : ''}`}
-            />
-            {showTitlebarExpandButton && (
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <button
-                    className="titlebar-icon-button"
-                    onClick={handleToggleExpand}
-                    aria-label="Collapse pane"
-                    disabled={!activeTabCanExpand}
-                  >
-                    <Minimize2 size={14} />
-                  </button>
-                </TooltipTrigger>
-                <TooltipContent side="bottom" sideOffset={6}>
-                  Collapse pane
-                </TooltipContent>
-              </Tooltip>
-            )}
-            {rightSidebarToggle}
-          </div>
-        ) : null}
         <div className="flex flex-row flex-1 min-h-0 overflow-hidden">
-          {showSidebar ? (
-            workspaceActive ? (
-              /* Why: left column wraps the sidebar with a titlebar-height
-                 header above it. The header holds the same controls
-                 (traffic lights, sidebar toggle, "Orca" title, agent badge)
-                 that the full-width titlebar held while the center and right
-                 columns keep their own top strips at the same 42px height.
-                 When the sidebar is collapsed, take this header out of flex
-                 layout so the terminal/editor reclaim the left edge instead of
-                 leaving behind a content-width blank strip. */
-              <div
-                className={`flex min-h-0 flex-col shrink-0${sidebarOpen ? '' : ' relative w-0 overflow-visible'}`}
-              >
+          {/* Why: the non-workspace titlebar lives inside this left+center
+              wrapper so it does not span over the right-sidebar column —
+              when the right sidebar is open, its own header anchors at the
+              top alongside the titlebar instead of being pushed below it. */}
+          <div className="flex flex-col flex-1 min-w-0 min-h-0">
+            {/* Why: in workspace view (split groups always enabled), the
+                full-width titlebar is removed so tab groups + terminal extend
+                to the top of the window. Left titlebar controls move to a
+                header above the sidebar. Settings, landing, and the tasks
+                page keep the titlebar. */}
+            {!workspaceActive ? (
+              <div className="titlebar">
                 <div
-                  // Why: when the sidebar is collapsed, titlebar-left floats
-                  // absolutely on top of the center column's own `border-l`
-                  // (see TabGroupSplitLayout), occluding that seam. Add a
-                  // `border-r` in the floating state so the vertical line
-                  // between the traffic-light/nav cluster and the tab strip
-                  // stays visible in both states.
-                  className={`titlebar-left${sidebarOpen ? '' : ' absolute top-0 left-0 z-10 border-r border-border'}`}
-                  style={{
-                    // Why: the Sidebar resize hook updates the sidebar DOM width
-                    // directly during drag and only persists to Zustand on
-                    // mouseup. In workspace view, size this header from the
-                    // wrapper's live width so it tracks those in-flight resizes
-                    // instead of leaving a stale-width gap until the drag ends.
-                    width: sidebarOpen ? '100%' : undefined
-                  }}
+                  className={`flex items-center${showSidebar && sidebarOpen ? ' overflow-hidden shrink-0' : ' shrink-0 mr-2'}`}
+                  style={{ width: showSidebar && sidebarOpen ? sidebarWidth : undefined }}
                 >
                   {titlebarLeftControls}
                 </div>
-                <div className="flex min-h-0 flex-1">
-                  {/* Why: the workspace-view wrapper adds a fixed 42px header
-                      above the sidebar. Without a flex-1/min-h-0 slot here,
-                      the sidebar falls back to its content height, so the
-                      worktree list loses its scroll viewport and the fixed
-                      bottom toolbar (including Add Project) gets pushed offscreen. */}
+                <div
+                  id="titlebar-tabs"
+                  className={`flex flex-1 min-w-0 self-stretch${activeView !== 'terminal' || !activeWorktreeId ? ' invisible pointer-events-none' : ''}`}
+                />
+                {showTitlebarExpandButton && (
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <button
+                        className="titlebar-icon-button"
+                        onClick={handleToggleExpand}
+                        aria-label="Collapse pane"
+                        disabled={!activeTabCanExpand}
+                      >
+                        <Minimize2 size={14} />
+                      </button>
+                    </TooltipTrigger>
+                    <TooltipContent side="bottom" sideOffset={6}>
+                      Collapse pane
+                    </TooltipContent>
+                  </Tooltip>
+                )}
+                {/* Why: when the right sidebar is open, its own header renders
+                    an identical close button — hide this copy so only one is
+                    visible at a time. */}
+                {!rightSidebarOpen && rightSidebarToggle}
+              </div>
+            ) : null}
+            <div className="flex flex-row flex-1 min-h-0 overflow-hidden">
+              {showSidebar ? (
+                workspaceActive ? (
+                  /* Why: left column wraps the sidebar with a titlebar-height
+                     header above it. The header holds the same controls
+                     (traffic lights, sidebar toggle, "Orca" title, agent badge)
+                     that the full-width titlebar held while the center and right
+                     columns keep their own top strips at the same 36px height.
+                     When the sidebar is collapsed, take this header out of flex
+                     layout so the terminal/editor reclaim the left edge instead of
+                     leaving behind a content-width blank strip. */
+                  <div
+                    className={`flex min-h-0 flex-col shrink-0${sidebarOpen ? '' : ' relative w-0 overflow-visible'}`}
+                  >
+                    <div
+                      // Why: when the sidebar is collapsed, titlebar-left floats
+                      // absolutely on top of the center column's own `border-l`
+                      // (see TabGroupSplitLayout), occluding that seam. Add a
+                      // `border-r` in the floating state so the vertical line
+                      // between the traffic-light/nav cluster and the tab strip
+                      // stays visible in both states.
+                      className={`titlebar-left${sidebarOpen ? '' : ' absolute top-0 left-0 z-10 border-r border-border'}`}
+                      style={{
+                        // Why: the Sidebar resize hook updates the sidebar DOM width
+                        // directly during drag and only persists to Zustand on
+                        // mouseup. In workspace view, size this header from the
+                        // wrapper's live width so it tracks those in-flight resizes
+                        // instead of leaving a stale-width gap until the drag ends.
+                        width: sidebarOpen ? '100%' : undefined
+                      }}
+                    >
+                      {titlebarLeftControls}
+                    </div>
+                    <div className="flex min-h-0 flex-1">
+                      {/* Why: the workspace-view wrapper adds a fixed 36px header
+                          above the sidebar. Without a flex-1/min-h-0 slot here,
+                          the sidebar falls back to its content height, so the
+                          worktree list loses its scroll viewport and the fixed
+                          bottom toolbar (including Add Project) gets pushed offscreen. */}
+                      <Sidebar />
+                    </div>
+                  </div>
+                ) : (
                   <Sidebar />
+                )
+              ) : null}
+              <div className="relative flex flex-1 min-w-0 min-h-0 overflow-hidden">
+                {/* Why: right sidebar toggle floats at the top-right of the center
+                    column so it's always accessible whether the right sidebar is
+                    open or closed. Match the RightSidebar header's 36px height and
+                    top-0 anchor so the icon's vertical center is identical between
+                    open and closed states — otherwise toggling makes the icon jump
+                    a few pixels, which reads as layout jitter. */}
+                {workspaceActive && !rightSidebarOpen && (
+                  <div
+                    className="absolute top-0 right-0 z-10 flex items-center h-[36px]"
+                    style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
+                  >
+                    {rightSidebarToggle}
+                  </div>
+                )}
+                <div className="flex flex-1 min-w-0 min-h-0 flex-col">
+                  <div
+                    className={
+                      activeView !== 'terminal' || !activeWorktreeId
+                        ? 'hidden flex-1 min-w-0 min-h-0'
+                        : 'flex flex-1 min-w-0 min-h-0'
+                    }
+                  >
+                    <Terminal />
+                  </div>
+                  <Suspense fallback={null}>
+                    {activeView === 'settings' ? <Settings /> : null}
+                    {activeView === 'tasks' ? <TaskPage /> : null}
+                    {activeView === 'terminal' && !activeWorktreeId ? <Landing /> : null}
+                  </Suspense>
                 </div>
               </div>
-            ) : (
-              <Sidebar />
-            )
-          ) : null}
-          <div className="relative flex flex-1 min-w-0 min-h-0 overflow-hidden">
-            {/* Why: right sidebar toggle floats at the top-right of the center
-                column so it's always accessible whether the right sidebar is
-                open or closed. Match the RightSidebar header's 42px height and
-                top-0 anchor so the icon's vertical center is identical between
-                open and closed states — otherwise toggling makes the icon jump
-                a few pixels, which reads as layout jitter. */}
-            {workspaceActive && !rightSidebarOpen && (
-              <div
-                className="absolute top-0 right-0 z-10 flex items-center h-[36px]"
-                style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
-              >
-                {rightSidebarToggle}
-              </div>
-            )}
-            <div className="flex flex-1 min-w-0 min-h-0 flex-col">
-              <div
-                className={
-                  activeView !== 'terminal' || !activeWorktreeId
-                    ? 'hidden flex-1 min-w-0 min-h-0'
-                    : 'flex flex-1 min-w-0 min-h-0'
-                }
-              >
-                <Terminal />
-              </div>
-              <Suspense fallback={null}>
-                {activeView === 'settings' ? <Settings /> : null}
-                {activeView === 'tasks' ? <TaskPage /> : null}
-                {activeView === 'terminal' && !activeWorktreeId ? <Landing /> : null}
-              </Suspense>
             </div>
           </div>
           {/* Why: keep RightSidebar mounted even when closed so that its
@@ -1114,6 +1114,14 @@ function App(): React.JSX.Element {
       ) : null}
       <UpdateCard />
       <StarNagCard />
+      {/* Why: the existing-user opt-in banner mounts at App root so it
+          renders once per renderer session, not per view. It gates
+          internally on the cohort markers populated by the migration,
+          so it only shows for users who installed before the telemetry
+          release and have not yet resolved consent. New users get no
+          first-launch surface — see telemetry-plan.md §First-launch
+          experience. */}
+      <TelemetryFirstLaunchSurface />
       <ZoomOverlay />
       <SshPassphraseDialog />
       <Toaster closeButton toastOptions={{ className: 'font-sans text-sm' }} />
diff --git a/src/renderer/src/assets/main.css b/src/renderer/src/assets/main.css
index 964d39195e0..5ddadaebf4f 100644
--- a/src/renderer/src/assets/main.css
+++ b/src/renderer/src/assets/main.css
@@ -16,6 +16,14 @@
 
 @custom-variant dark (&:is(.dark *));
 
+.theme-transition-disabled *,
+.theme-transition-disabled *::before,
+.theme-transition-disabled *::after {
+  /* Why: theme swaps flip many CSS variables at once; transitions make parts of
+     the UI fade at different speeds. Animations stay enabled for spinners. */
+  transition: none !important;
+}
+
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
@@ -61,6 +69,8 @@
 /* ── Light Mode ──────────────────────────────────────── */
 
 :root {
+  --app-font-family: 'Geist', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --font-sans: var(--app-font-family);
   --font-mono:
     'SF Mono', SFMono-Regular, ui-monospace, 'Cascadia Code', Menlo, Consolas, 'Liberation Mono',
     monospace;
@@ -165,12 +175,14 @@
     padding: 0;
     overflow: hidden;
     height: 100vh;
-    font-family:
+    font-family: var(
+      --app-font-family,
       'Geist',
       -apple-system,
       BlinkMacSystemFont,
       'Segoe UI',
-      sans-serif;
+      sans-serif
+    );
     letter-spacing: 0.01em;
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
@@ -347,8 +359,8 @@
 }
 
 .titlebar {
-  height: 42px;
-  min-height: 42px;
+  height: 36px;
+  min-height: 36px;
   display: flex;
   flex-direction: row;
   align-items: center;
diff --git a/src/renderer/src/components/FirstLaunchBanner.tsx b/src/renderer/src/components/FirstLaunchBanner.tsx
new file mode 100644
index 00000000000..8a03379786e
--- /dev/null
+++ b/src/renderer/src/components/FirstLaunchBanner.tsx
@@ -0,0 +1,174 @@
+// Existing-user first-launch notice. Shown to users whose cohort marker is
+// `existedBeforeTelemetryRelease === true` and whose `optedIn` is still
+// `null`, i.e. users who installed Orca before the telemetry release and
+// have not yet resolved the notice.
+//
+// Why existing users see a notice at all (and new users do not): pre-
+// telemetry users installed Orca under a "no telemetry" social contract,
+// so default-on for them would be a silent policy flip. New users are
+// covered by the install-time disclosure and receive no first-launch UI —
+// see telemetry-plan.md §First-launch experience.
+//
+// Three actions, two semantics:
+//   - "Got it" and the ✕ in the corner → silent acknowledge. Both persist
+//     `optedIn: true`, fire no opt-in event, route through
+//     `window.api.telemetryAcknowledgeBanner()` to a dedicated main-side
+//     channel so no `via` derivation can tag this path. Two surfaces for
+//     the same action because the ✕ alone is easy to miss; "Got it" is
+//     the discoverable primary, ✕ is the keyboard/notification-style
+//     escape. Either way the user sees the notice, chooses not to
+//     intervene, and is opted in silently.
+//   - "Turn off" → explicit opt-out. Routes through
+//     `window.api.telemetrySetOptIn(false)`; main derives
+//     `via = 'first_launch_banner'` from the pre-mutation state
+//     (existedBeforeTelemetryRelease=true, optedIn=null, incoming=false)
+//     and fires `telemetry_opted_out { via: 'first_launch_banner' }`
+//     BEFORE disabling the SDK — the one signal that tells us the
+//     opt-out flow is working must not be silenced by the opt-out it
+//     announces.
+//   - "Privacy policy" link → opens the privacy doc URL, no state change,
+//     no dismiss.
+//
+// No auto-dismiss, no delayed re-ask: once resolved (Got it / ✕ / Turn
+// off), the notice never returns, because the cohort condition
+// (`optedIn === null`) clears in all three resolving paths.
+
+import { useState } from 'react'
+import { X } from 'lucide-react'
+
+import { Button } from './ui/button'
+import { acknowledgeBanner, PRIVACY_URL, setOptIn as telemetrySetOptIn } from '../lib/telemetry'
+
+type FirstLaunchBannerProps = {
+  onResolve: () => void
+  fetchSettings: () => Promise<void>
+}
+
+export function FirstLaunchBanner({
+  onResolve,
+  fetchSettings
+}: FirstLaunchBannerProps): React.JSX.Element {
+  // Double-click guard. Without this, a fast second click on "Turn off"
+  // would re-enter telemetrySetOptIn(false); on the second call, main's
+  // deriveOptInVia sees currentOptedIn=false (just persisted by click 1)
+  // and falls through to the 'settings' branch, producing one opt-out
+  // intent tagged as two different `via` values. The acknowledge paths
+  // are guarded symmetrically — a second Got-it/✕ click would be a
+  // wasted IPC round-trip, but the guard also blocks a Turn-off click
+  // arriving mid-flight after an acknowledge (or vice versa).
+  const [inFlight, setInFlight] = useState(false)
+
+  const handleAcknowledge = async (): Promise<void> => {
+    if (inFlight) {
+      return
+    }
+    setInFlight(true)
+    // Main's `telemetry:acknowledgeBanner` handler persists `optedIn: true`
+    // without an opt-in event and intentionally does NOT broadcast
+    // `settings:changed` (see src/main/ipc/telemetry.ts). Without an
+    // explicit `fetchSettings()` refresh, the renderer store would retain
+    // `optedIn: null` and PrivacyPane would keep rendering its pending-
+    // banner helper text until the next full relaunch. Mirror
+    // PrivacyPane's handleToggle pattern which refetches for the same
+    // reason before surfacing UI changes.
+    try {
+      await acknowledgeBanner()
+      await fetchSettings()
+      onResolve()
+    } finally {
+      // Why: if `fetchSettings` rejects (IPC error during shutdown,
+      // settings file lock, etc.), `onResolve` never runs and the banner
+      // stays mounted. Without resetting `inFlight`, every button stays
+      // permanently disabled for the rest of the session.
+      setInFlight(false)
+    }
+  }
+
+  const handleTurnOff = async (): Promise<void> => {
+    if (inFlight) {
+      return
+    }
+    setInFlight(true)
+    // Opt-out fires `telemetry_opted_out { via: 'first_launch_banner' }`
+    // BEFORE the SDK disable — main enforces that ordering inside
+    // `setOptIn` (client.ts). The renderer just needs to route through
+    // `telemetrySetOptIn(false)` so the IPC handler derives the correct
+    // `via` and fires the event.
+    try {
+      await telemetrySetOptIn(false)
+      await fetchSettings()
+      onResolve()
+    } finally {
+      setInFlight(false)
+    }
+  }
+
+  return (
+    // Fixed-top strip so the notice overlays whatever is beneath without
+    // shifting the rest of the layout. `top-2` hugs the top edge of the
+    // window; on macOS the titlebar is drawn over the same region but the
+    // banner stays below the traffic lights via centering + narrow width.
+    // The notice is non-modal and intentionally does not occlude the main
+    // content — clicks pass through to below-notice regions outside this
+    // box.
+    //
+    // `relative` is load-bearing: the absolutely-positioned ✕ anchors to
+    // this container.
+    <div
+      className="fixed left-1/2 top-2 z-40 flex w-[min(44.625rem,calc(100vw-2rem))] -translate-x-1/2 items-start gap-4 rounded-lg border border-border bg-card/95 py-3 pl-4 pr-3 shadow-lg backdrop-blur"
+      role="region"
+      aria-label="Telemetry notice"
+      aria-live="polite"
+    >
+      {/* Text column — title + body stack on the left, takes remaining
+          width so the action column never pushes copy into a wrap. */}
+      <div className="flex-1 space-y-0.5 pr-1 text-sm">
+        <p className="font-medium leading-snug">Help us decide what to build next</p>
+        <p className="text-xs leading-snug text-muted-foreground">
+          Anonymous counts of which features you use help us prioritize what to build. No file
+          contents, prompts, terminal output, or anything that identifies you. Change anytime in
+          Settings &rarr; Privacy &amp; Telemetry.{' '}
+          <button
+            type="button"
+            className="underline underline-offset-2 hover:text-foreground"
+            onClick={() => void window.api.shell.openUrl(PRIVACY_URL)}
+          >
+            Privacy policy
+          </button>
+          .
+        </p>
+      </div>
+      {/* Action column — vertically centered against the text block.
+          "Got it" is the affirmative primary so it reads as the easy
+          path; "Turn off" is the secondary outline so the destructive
+          (from telemetry's perspective) action requires an explicit
+          choice. ✕ stays in the corner as a familiar escape and to
+          satisfy keyboard/notification-style dismiss expectations. */}
+      <div className="flex shrink-0 items-center gap-2 self-center pr-6">
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={handleTurnOff}
+          disabled={inFlight}
+          className="border-border/60 text-muted-foreground"
+        >
+          Opt out
+        </Button>
+        <Button size="sm" onClick={handleAcknowledge} disabled={inFlight}>
+          Got it
+        </Button>
+      </div>
+      {/* aria-label says "Dismiss" — the action persists silent opt-in,
+          not just hides the UI. */}
+      <button
+        type="button"
+        aria-label="Dismiss notice"
+        onClick={handleAcknowledge}
+        disabled={inFlight}
+        className="absolute right-1.5 top-1.5 rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50"
+      >
+        <X className="size-3.5" />
+      </button>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index ea8f3dfe7a4..6eef848bdcd 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -62,6 +62,7 @@ import {
 } from '@/lib/pr-comment-groups'
 import { useAppStore } from '@/store'
 import { useRepoLabels, useRepoAssignees, useImmediateMutation } from '@/hooks/useIssueMetadata'
+import { useRepoLabelsBySlug, useRepoAssigneesBySlug } from '@/hooks/useGitHubSlugMetadata'
 import IssueSourceIndicator, { sameGitHubOwnerRepo } from '@/components/github/IssueSourceIndicator'
 import type {
   GitHubOwnerRepo,
@@ -131,12 +132,35 @@ const REACTION_EMOJI: Record<GitHubReaction['content'], string> = {
   eyes: '👀'
 }
 
+/** Why: Project-origin rows don't always belong to the active local repo.
+ *  When set, GHEditSection routes label/assignee/state mutations through
+ *  slug-addressed IPCs against `owner`/`repo` instead of through `repoPath`,
+ *  preventing edits from silently landing on the workspace's repo when the
+ *  Project view is showing rows from a different repo. See
+ *  docs/design/github-project-view-tasks.md §Dialog editing from Project rows.
+ */
+export type GitHubItemDialogProjectOrigin = {
+  owner: string
+  repo: string
+  number: number
+  type: 'issue' | 'pr'
+  projectId: string
+  projectItemId: string
+  cacheKey: string
+}
+
 type GitHubItemDialogProps = {
   workItem: GitHubWorkItem | null
   repoPath: string | null
   /** Called when the user clicks the primary CTA to start work from this item. */
   onUse: (item: GitHubWorkItem) => void
   onClose: () => void
+  /** Optional Project-origin context. When set, edits in the dialog are
+   *  routed via slug-addressed mutation IPCs against the row's actual repo
+   *  instead of the active workspace's `repoPath`. Both can be set
+   *  simultaneously (Project mode where the row also lives in the active
+   *  workspace) — slug routing wins for writes. */
+  projectOrigin?: GitHubItemDialogProjectOrigin
 }
 
 function formatRelativeTime(input: string): string {
@@ -1332,7 +1356,18 @@ function ConversationTab({
           />
         )}
 
-        {item.type !== 'pr' ? <div className="pt-1">{startWorkspaceButton}</div> : null}
+        {item.type !== 'pr' ? (
+          <div className="flex justify-start pt-1">
+            <Button
+              onClick={() => onUse(item)}
+              className="gap-2"
+              aria-label="Start workspace from issue"
+            >
+              Start workspace from issue
+              <ArrowRight className="size-4" />
+            </Button>
+          </div>
+        ) : null}
       </div>
 
       {rightPanel}
@@ -1634,9 +1669,44 @@ function MentionTextarea({
   )
 }
 
+// Why: when the dialog opens for a Project row whose repo differs from the
+// active workspace, mutations must target the row's actual repo via
+// slug-addressed IPCs. Otherwise edits silently apply to the workspace's
+// repo. The edit IPCs return a structured `{ ok, error }` shape; we adapt
+// to a thrown rejection so the existing `useImmediateMutation` flow
+// (which expects throws on failure) continues to work unchanged.
+async function runIssueUpdate(args: {
+  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({
+      owner: args.projectOrigin.owner,
+      repo: args.projectOrigin.repo,
+      number: args.number,
+      updates: args.updates
+    })
+    if (!res.ok) {
+      throw new Error(res.error.message)
+    }
+    return
+  }
+  if (!args.repoPath) {
+    throw new Error('No repo context available for this edit.')
+  }
+  await window.api.gh.updateIssue({
+    repoPath: args.repoPath,
+    number: args.number,
+    updates: args.updates
+  })
+}
+
 function GHEditSection({
   item,
   repoPath,
+  projectOrigin,
   localState,
   localLabels,
   onStateChange,
@@ -1644,7 +1714,8 @@ function GHEditSection({
   assignees
 }: {
   item: GitHubWorkItem
-  repoPath: string
+  repoPath: string | null
+  projectOrigin: GitHubItemDialogProjectOrigin | undefined
   localState: GitHubWorkItem['state']
   localLabels: string[]
   onStateChange: (state: GitHubWorkItem['state']) => void
@@ -1656,10 +1727,35 @@ function GHEditSection({
   const [localAssignees, setLocalAssignees] = useState<string[]>(assignees)
   const hasEditedAssigneesRef = useRef(false)
   const patchWorkItem = useAppStore((s) => s.patchWorkItem)
+  const patchProjectRowContent = useAppStore((s) => s.patchProjectRowContent)
   const { isPending, run } = useImmediateMutation()
 
-  const repoLabels = useRepoLabels(repoPath)
-  const repoAssignees = useRepoAssignees(repoPath)
+  // 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
+  // helper the Project table would render stale data until manual refresh.
+  // See docs/design/github-project-view-tasks.md §Dialog editing from Project rows.
+  const patchProjectRowIfNeeded = useCallback(
+    (patch: Parameters<typeof patchProjectRowContent>[2]) => {
+      if (!projectOrigin) {
+        return
+      }
+      patchProjectRowContent(projectOrigin.cacheKey, projectOrigin.projectItemId, patch)
+    },
+    [projectOrigin, patchProjectRowContent]
+  )
+
+  // Why: when projectOrigin is set we MUST read labels/assignees from the
+  // row's repo, not from the workspace path — otherwise the popovers list
+  // 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 repoLabels = projectOrigin ? repoLabelsBySlug : repoLabelsByPath
+  const repoAssigneesByPath = useRepoAssignees(projectOrigin ? null : repoPath)
+  const repoAssigneesBySlug = useRepoAssigneesBySlug(slugOwner, slugRepo, assignees)
+  const repoAssignees = projectOrigin ? repoAssigneesBySlug : repoAssigneesByPath
 
   // Why: sync local assignees when item changes or when the detail fetch
   // resolves with real data — but skip if the user already made an
@@ -1684,26 +1780,40 @@ function GHEditSection({
       const prevState = localState
       run('state', {
         mutate: () =>
-          window.api.gh.updateIssue({
+          runIssueUpdate({
             repoPath,
+            projectOrigin,
             number: item.number,
             updates: { state: newState }
           }),
         onOptimistic: () => {
           onStateChange(newState)
           patchWorkItem(item.id, { state: newState })
+          patchProjectRowIfNeeded({ state: newState })
         },
         onRevert: () => {
           onStateChange(prevState)
           patchWorkItem(item.id, { state: prevState })
+          patchProjectRowIfNeeded({ state: prevState })
         },
         onSuccess: () => {
           patchWorkItem(item.id, { state: newState })
+          patchProjectRowIfNeeded({ state: newState })
         },
         onError: (err) => toast.error(err)
       })
     },
-    [item.id, item.number, localState, repoPath, patchWorkItem, run, onStateChange]
+    [
+      item.id,
+      item.number,
+      localState,
+      repoPath,
+      projectOrigin,
+      patchWorkItem,
+      patchProjectRowIfNeeded,
+      run,
+      onStateChange
+    ]
   )
 
   const handleLabelToggle = useCallback(
@@ -1715,44 +1825,60 @@ function GHEditSection({
       if (isAdding) {
         run('labels', {
           mutate: () =>
-            window.api.gh.updateIssue({
+            runIssueUpdate({
               repoPath,
+              projectOrigin,
               number: item.number,
               updates: { addLabels: [label] }
             }),
           onOptimistic: () => {
             onLabelsChange(newLabels)
             patchWorkItem(item.id, { labels: newLabels })
+            patchProjectRowIfNeeded({ labels: newLabels })
           },
           onSuccess: () => {},
           onRevert: () => {
             onLabelsChange(prevLabels)
             patchWorkItem(item.id, { labels: prevLabels })
+            patchProjectRowIfNeeded({ labels: prevLabels })
           },
           onError: (err) => toast.error(err)
         })
       } else {
         run('labels', {
           mutate: () =>
-            window.api.gh.updateIssue({
+            runIssueUpdate({
               repoPath,
+              projectOrigin,
               number: item.number,
               updates: { removeLabels: [label] }
             }),
           onOptimistic: () => {
             onLabelsChange(newLabels)
             patchWorkItem(item.id, { labels: newLabels })
+            patchProjectRowIfNeeded({ labels: newLabels })
           },
           onRevert: () => {
             onLabelsChange(prevLabels)
             patchWorkItem(item.id, { labels: prevLabels })
+            patchProjectRowIfNeeded({ labels: prevLabels })
           },
           onSuccess: () => {},
           onError: (err) => toast.error(err)
         })
       }
     },
-    [item.id, item.number, localLabels, repoPath, patchWorkItem, run, onLabelsChange]
+    [
+      item.id,
+      item.number,
+      localLabels,
+      repoPath,
+      projectOrigin,
+      patchWorkItem,
+      patchProjectRowIfNeeded,
+      run,
+      onLabelsChange
+    ]
   )
 
   const handleAssigneeToggle = useCallback(
@@ -1767,16 +1893,19 @@ function GHEditSection({
       if (isAssigned) {
         run('assignees', {
           mutate: () =>
-            window.api.gh.updateIssue({
+            runIssueUpdate({
               repoPath,
+              projectOrigin,
               number: item.number,
               updates: { removeAssignees: [login] }
             }),
           onOptimistic: () => {
             setLocalAssignees(newAssignees)
+            patchProjectRowIfNeeded({ assignees: newAssignees })
           },
           onRevert: () => {
             setLocalAssignees(prevAssignees)
+            patchProjectRowIfNeeded({ assignees: prevAssignees })
           },
           onSuccess: () => {},
           onError: (err) => toast.error(err)
@@ -1784,23 +1913,26 @@ function GHEditSection({
       } else {
         run('assignees', {
           mutate: () =>
-            window.api.gh.updateIssue({
+            runIssueUpdate({
               repoPath,
+              projectOrigin,
               number: item.number,
               updates: { addAssignees: [login] }
             }),
           onOptimistic: () => {
             setLocalAssignees(newAssignees)
+            patchProjectRowIfNeeded({ assignees: newAssignees })
           },
           onSuccess: () => {},
           onRevert: () => {
             setLocalAssignees(prevAssignees)
+            patchProjectRowIfNeeded({ assignees: prevAssignees })
           },
           onError: (err) => toast.error(err)
         })
       }
     },
-    [item.number, repoPath, localAssignees, run]
+    [item.number, repoPath, projectOrigin, localAssignees, patchProjectRowIfNeeded, run]
   )
 
   if (item.type === 'pr') {
@@ -2006,7 +2138,7 @@ function GHCommentComposer({
       return
     }
     el.style.height = 'auto'
-    el.style.height = `${Math.max(36, Math.min(el.scrollHeight, 96))}px`
+    el.style.height = `${Math.max(80, Math.min(el.scrollHeight, 240))}px`
   }, [])
 
   const handleSubmit = useCallback(async () => {
@@ -2048,12 +2180,7 @@ function GHCommentComposer({
   )
 
   return (
-    <div
-      className={cn(
-        'flex items-center gap-2 rounded-lg border border-border/50 bg-background/30 p-2',
-        className
-      )}
-    >
+    <div className={cn('flex items-start gap-2', className)}>
       <MentionTextarea
         textareaRef={textareaRef}
         value={body}
@@ -2063,10 +2190,10 @@ function GHCommentComposer({
         }}
         onKeyDown={handleKeyDown}
         placeholder="Add a comment…"
-        rows={1}
+        rows={4}
         mentionOptions={mentionOptions}
-        wrapperClassName="flex min-h-9 items-center"
-        className="scrollbar-sleek block h-9 max-h-[96px] min-h-9 w-full resize-none overflow-y-auto rounded-md border border-input bg-transparent px-3 py-2 text-[13px] leading-5 placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        wrapperClassName="flex min-h-20 items-stretch"
+        className="scrollbar-sleek block h-20 max-h-[240px] min-h-20 w-full resize-none overflow-y-auto rounded-md border border-input bg-card px-3 py-2 text-[13px] leading-5 placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
       />
       <Button
         size="icon"
@@ -2150,6 +2277,7 @@ function WorkItemIssueSourceIndicator({
 export default function GitHubItemDialog({
   workItem,
   repoPath,
+  projectOrigin,
   onUse,
   onClose
 }: GitHubItemDialogProps): React.JSX.Element {
@@ -2304,7 +2432,7 @@ export default function GitHubItemDialog({
       <SheetContent
         side="right"
         showCloseButton={false}
-        className="flex w-full flex-col gap-0 overflow-hidden p-0 sm:max-w-[960px] lg:max-w-[1100px] xl:max-w-[1280px]"
+        className="flex w-full flex-col gap-0 overflow-hidden p-0 sm:max-w-[640px] lg:max-w-[760px] xl:max-w-[900px]"
         onOpenAutoFocus={(event) => {
           // Why: focusing the first actionable element inside the drawer
           // causes the "Start workspace" action to receive focus and
@@ -2329,15 +2457,15 @@ export default function GitHubItemDialog({
           <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">
-                <Icon className="mt-1 size-4 shrink-0 text-muted-foreground" />
                 <div className="min-w-0 flex-1">
                   <span className="font-mono text-[12px] text-muted-foreground">
                     #{workItem.number}
                   </span>
-                  <h2 className="mt-1 text-[15px] font-semibold leading-tight text-foreground">
-                    {workItem.title}
+                  <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>
                   </h2>
-                  <div className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-[11px] text-muted-foreground">
+                  <div className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 pl-6 text-[11px] text-muted-foreground">
                     <span>{workItem.author ?? 'unknown'}</span>
                     <span>· {formatRelativeTime(workItem.updatedAt)}</span>
                     {workItem.branchName && (
@@ -2387,10 +2515,11 @@ export default function GitHubItemDialog({
               </div>
             </div>
 
-            {repoPath && (
+            {(repoPath || projectOrigin) && (
               <GHEditSection
                 item={workItem}
                 repoPath={repoPath}
+                projectOrigin={projectOrigin}
                 localState={localState}
                 localLabels={localLabels}
                 onStateChange={setLocalState}
diff --git a/src/renderer/src/components/Landing.tsx b/src/renderer/src/components/Landing.tsx
index 8d1ca8072b1..3e97240c3a1 100644
--- a/src/renderer/src/components/Landing.tsx
+++ b/src/renderer/src/components/Landing.tsx
@@ -252,7 +252,7 @@ export default function Landing(): React.JSX.Element {
               className="inline-flex items-center gap-1.5 bg-secondary/70 border border-border/80 text-foreground font-medium text-sm px-4 py-2 rounded-md transition-colors disabled:opacity-40 disabled:cursor-not-allowed enabled:cursor-pointer enabled:hover:bg-accent"
               disabled={!canCreateWorktree}
               title={!canCreateWorktree ? 'Add a Git project first' : undefined}
-              onClick={() => openModal('new-workspace-composer')}
+              onClick={() => openModal('new-workspace-composer', { telemetrySource: 'unknown' })}
             >
               <GitBranchPlus className="size-3.5" />
               Create Worktree
diff --git a/src/renderer/src/components/NewWorkspaceComposerCard.tsx b/src/renderer/src/components/NewWorkspaceComposerCard.tsx
index 78230e9d879..7cacd39f437 100644
--- a/src/renderer/src/components/NewWorkspaceComposerCard.tsx
+++ b/src/renderer/src/components/NewWorkspaceComposerCard.tsx
@@ -11,15 +11,17 @@ import {
   Settings2
 } from 'lucide-react'
 import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import RepoCombobox from '@/components/repo/RepoCombobox'
 import AgentCombobox from '@/components/agent/AgentCombobox'
 import { AGENT_CATALOG } from '@/lib/agent-catalog'
 import { useAppStore } from '@/store'
 import { cn } from '@/lib/utils'
-import type { SparsePreset, TuiAgent } from '../../../shared/types'
+import type { GitHubWorkItem, LinearIssue, SparsePreset, TuiAgent } from '../../../shared/types'
 import SparseCheckoutPresetSelect from '@/components/sparse/SparseCheckoutPresetSelect'
+import SmartWorkspaceNameField, {
+  type SmartWorkspaceNameSelection
+} from '@/components/new-workspace/SmartWorkspaceNameField'
 
 const isMac = typeof navigator !== 'undefined' && navigator.userAgent.includes('Mac')
 
@@ -35,7 +37,12 @@ type NewWorkspaceComposerCardProps = {
   repoId: string
   onRepoChange: (value: string) => void
   name: string
-  onNameChange: (event: React.ChangeEvent<HTMLInputElement>) => void
+  onNameValueChange: (value: string) => void
+  onSmartGitHubItemSelect: (item: GitHubWorkItem) => void
+  onSmartBranchSelect: (refName: string) => void
+  onSmartLinearIssueSelect: (issue: LinearIssue) => void
+  smartNameSelection: SmartWorkspaceNameSelection | null
+  onClearSmartNameSelection: () => void
   detectedAgentIds: Set<TuiAgent> | null
   onOpenAgentSettings: () => void
   advancedOpen: boolean
@@ -175,7 +182,12 @@ export default function NewWorkspaceComposerCard({
   repoId,
   onRepoChange,
   name,
-  onNameChange,
+  onNameValueChange,
+  onSmartGitHubItemSelect,
+  onSmartBranchSelect,
+  onSmartLinearIssueSelect,
+  smartNameSelection,
+  onClearSmartNameSelection,
   detectedAgentIds,
   onOpenAgentSettings,
   advancedOpen,
@@ -240,12 +252,12 @@ export default function NewWorkspaceComposerCard({
       onDragEnter={dragHandlers.onDragEnter}
       onDragLeave={dragHandlers.onDragLeave}
       className={cn(
-        'grid gap-1 rounded-md transition',
+        'grid min-w-0 gap-1 rounded-md transition',
         isFileDragOver && 'ring-2 ring-ring/30',
         containerClassName
       )}
     >
-      <div className="space-y-4 pt-3">
+      <div className="min-w-0 space-y-4 pt-3">
         <div className="space-y-1">
           <div className="flex items-center justify-between gap-2">
             <label className="text-xs font-medium text-muted-foreground">Repository</label>
@@ -284,30 +296,33 @@ export default function NewWorkspaceComposerCard({
           />
         </div>
 
-        <div className="space-y-1">
+        <div className="min-w-0 space-y-1">
           <label className="text-xs font-medium text-muted-foreground">
-            Workspace Name <span className="text-muted-foreground/70">[Optional]</span>
+            Name or &apos;Create From&apos;{' '}
+            <span className="text-muted-foreground/70">[Optional]</span>
           </label>
-          <Input
-            ref={nameInputRef}
+          <SmartWorkspaceNameField
+            inputRef={nameInputRef}
+            repos={eligibleRepos}
+            repoId={repoId}
+            onRepoChange={onRepoChange}
             value={name}
-            onChange={onNameChange}
-            onKeyDown={(event) => {
+            onValueChange={onNameValueChange}
+            onGitHubItemSelect={onSmartGitHubItemSelect}
+            onBranchSelect={onSmartBranchSelect}
+            onLinearIssueSelect={onSmartLinearIssueSelect}
+            selectedSource={smartNameSelection}
+            onClearSelectedSource={onClearSmartNameSelection}
+            onPlainEnter={() => {
               // Why: Enter on the workspace name advances focus to the next
               // field (Agent combobox) rather than submitting, letting the user
               // progress through the form with just the keyboard.
-              if (event.key !== 'Enter' || event.shiftKey || event.metaKey || event.ctrlKey) {
-                return
-              }
-              event.preventDefault()
               const root = composerRef?.current
               const agentTrigger = root?.querySelector<HTMLElement>(
                 '[data-agent-combobox-root="true"][role="combobox"]'
               )
               agentTrigger?.focus()
             }}
-            placeholder="Workspace name"
-            className="h-9 text-sm"
           />
         </div>
 
@@ -348,6 +363,21 @@ export default function NewWorkspaceComposerCard({
           />
         </div>
 
+        <div>
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            onClick={onToggleAdvanced}
+            className="-ml-2 text-xs"
+          >
+            Advanced
+            <ChevronDown
+              className={cn('size-4 transition-transform', advancedOpen && 'rotate-180')}
+            />
+          </Button>
+        </div>
+
         <div
           className={cn(
             'grid overflow-hidden transition-[grid-template-rows] duration-200 ease-out',
@@ -368,6 +398,25 @@ export default function NewWorkspaceComposerCard({
                   : '-translate-y-1 opacity-0 delay-0'
               )}
             >
+              {smartNameSelection ? (
+                // Why: when a source (PR/issue/Linear/branch) is picked the
+                // smart field shows a pill instead of an editable name, so
+                // surface the auto-derived workspace name here under Advanced
+                // where it can be reviewed/overridden. When the user typed an
+                // explicit name there's no source pill — the smart input is
+                // already the name field, so we don't duplicate it here.
+                <div className="space-y-1">
+                  <label className="text-xs font-medium text-muted-foreground">Name</label>
+                  <input
+                    type="text"
+                    value={name}
+                    onChange={(event) => onNameValueChange(event.target.value)}
+                    placeholder="Workspace name"
+                    className="w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1.5 text-sm shadow-xs transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50"
+                  />
+                </div>
+              ) : null}
+
               <div className="space-y-1">
                 <label className="text-xs font-medium text-muted-foreground">Note</label>
                 <textarea
@@ -496,21 +545,6 @@ export default function NewWorkspaceComposerCard({
         </div>
       ) : null}
 
-      <div>
-        <Button
-          type="button"
-          variant="ghost"
-          size="sm"
-          onClick={onToggleAdvanced}
-          className="-ml-2 text-xs"
-        >
-          Advanced
-          <ChevronDown
-            className={cn('size-4 transition-transform', advancedOpen && 'rotate-180')}
-          />
-        </Button>
-      </div>
-
       <div className="flex justify-end">
         <Button
           onClick={() => void onCreate()}
diff --git a/src/renderer/src/components/NewWorkspaceComposerModal.tsx b/src/renderer/src/components/NewWorkspaceComposerModal.tsx
index 8a00a32370b..a8cda39fab6 100644
--- a/src/renderer/src/components/NewWorkspaceComposerModal.tsx
+++ b/src/renderer/src/components/NewWorkspaceComposerModal.tsx
@@ -1,47 +1,24 @@
-import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
 import { useAppStore } from '@/store'
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle
-} from '@/components/ui/dialog'
-import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
 import NewWorkspaceComposerCard from '@/components/NewWorkspaceComposerCard'
 import AgentSettingsDialog from '@/components/agent/AgentSettingsDialog'
-import CreateFromTab from '@/components/new-workspace/CreateFromTab'
 import { useComposerState } from '@/hooks/useComposerState'
 import { AGENT_CATALOG } from '@/lib/agent-catalog'
 import type { LinkedWorkItemSummary } from '@/lib/new-workspace'
 import { shouldSuppressEnterSubmit } from '@/lib/new-workspace-enter-guard'
-import { cn } from '@/lib/utils'
-import type { TuiAgent } from '../../../shared/types'
+import type { TuiAgent, WorkspaceCreateTelemetrySource } from '../../../shared/types'
 
 type ComposerModalData = {
   prefilledName?: string
   initialRepoId?: string
   linkedWorkItem?: LinkedWorkItemSummary | null
   initialBaseBranch?: string
-  initialTab?: 'quick' | 'create-from'
-}
-
-const isMac = typeof navigator !== 'undefined' && navigator.userAgent.includes('Mac')
-const tabShortcut = {
-  quick: isMac ? '⌘N' : 'Ctrl+N',
-  'create-from': isMac ? '⌘⇧N' : 'Ctrl+Shift+N'
-} as const
-
-function ShortcutHint({ children }: { children: React.ReactNode }): React.JSX.Element {
-  // Why: a flat muted string reads as "secondary hint" rather than the
-  // bordered kbd chip, which drew too much attention for a label most users
-  // will learn once and forget. Stays inside the tab trigger so the hit
-  // target covers it too.
-  return (
-    <span className="text-[10px] font-normal tracking-wide text-muted-foreground/70">
-      {children}
-    </span>
-  )
+  /** Telemetry surface that opened the composer. Set by each
+   *  `openModal('new-workspace-composer', ...)` site so
+   *  `workspace_created.source` carries the right value. Falls back to
+   *  `unknown` when omitted. */
+  telemetrySource?: WorkspaceCreateTelemetrySource
 }
 
 export default function NewWorkspaceComposerModal(): React.JSX.Element | null {
@@ -83,56 +60,15 @@ function ComposerModalBody({
   onClose: () => void
   onOpenChange: (open: boolean) => void
 }): React.JSX.Element {
-  const activeTab = useAppStore((s) => s.newWorkspaceComposerTab)
-  const setActiveTab = useAppStore((s) => s.setNewWorkspaceComposerTab)
-
-  // Why: when the user starts something on Create-from that needs to fall
-  // back to Quick (setup policy = 'ask', PR head resolution failed, ...) we
-  // feed the prefill through this local override and remount the Quick
-  // composer via a bumped key so its initial state absorbs the new data.
-  // Without the key bump the useComposerState hook would keep its first
-  // snapshot and the Quick tab would appear empty after fallback.
-  const [prefillOverride, setPrefillOverride] = useState<ComposerModalData | null>(null)
-  const [quickKey, setQuickKey] = useState(0)
-
-  const effectiveQuickData = prefillOverride ?? modalData
-
-  const handleFallbackToQuick = useCallback(
-    (data: {
-      initialRepoId?: string
-      linkedWorkItem?: LinkedWorkItemSummary | null
-      prefilledName?: string
-      initialBaseBranch?: string
-    }) => {
-      setPrefillOverride({ ...data })
-      setQuickKey((k) => k + 1)
-      setActiveTab('quick')
-    },
-    [setActiveTab]
-  )
-
-  const handleCreateFromLaunched = useCallback(() => {
-    onClose()
-  }, [onClose])
-
   return (
     <Dialog open onOpenChange={onOpenChange}>
       <DialogContent
-        // Why: pin a single width across both tabs. Create-from needs the
-        // extra horizontal room for PR titles + branch names; Quick tolerates
-        // it fine. Animating between widths was jarring and made the modal
-        // feel unstable every time the user toggled tabs.
         className="flex flex-col sm:max-w-lg"
         onOpenAutoFocus={(event) => {
-          // Why: Radix's FocusScope fires this once the dialog has mounted and
-          // the DOM is ready. preventDefault stops it from focusing the first
-          // tabbable in the Quick tab (the repo combobox trigger) when the
-          // Create-from tab is active — that tab wants the search input to
-          // own initial focus. The QuickTabBody handles its own focus below
-          // when the Quick tab is active.
-          if (activeTab === 'create-from') {
-            return
-          }
+          // Why: Radix's FocusScope fires this once the dialog has mounted.
+          // preventDefault stops it from focusing whatever first-tabbable it
+          // picks (close button), and we instead focus the repo picker so the
+          // keyboard flow starts at the top of the unified create form.
           event.preventDefault()
           const content = event.currentTarget as HTMLElement
           const trigger = content.querySelector<HTMLElement>(
@@ -141,68 +77,11 @@ function ComposerModalBody({
           trigger?.focus({ preventScroll: true })
         }}
       >
-        <Tabs
-          value={activeTab}
-          onValueChange={(next) => setActiveTab(next as 'quick' | 'create-from')}
-          // Why: both panels are force-mounted so switching tabs preserves
-          // their local state (typed query on Create-from, repo pick /
-          // workspace name on Quick) instead of remounting each time.
-          // Height is driven by the active panel's intrinsic size — the
-          // DialogContent handles overflow if the viewport is too short.
-          className="flex flex-col gap-0"
-        >
-          {/* Why: use the shared underline variant so both levels of tabs
-              read as "tabs" — the default pill variant fought the sub-tabs
-              inside Create-from for visual weight. The bottom border on the
-              list gives it clear separation from the content below. */}
-          {/* Why: DialogContent has p-6 (24px top) and the close button sits
-              absolutely at top-4 (16px), so its 16px icon centers around 24px
-              from the top. Pull the h-8 tab list up with -mt-4 so its center
-              (8 + 16 = 24px) lines up with the X on the same row. Reserve
-              right padding so the last trigger doesn't slide under the X. */}
-          <TabsList
-            variant="line"
-            className="-mt-4 h-8 w-full justify-start gap-6 border-b border-border/60 px-0 pr-8"
-          >
-            <TabsTrigger value="quick" className="flex-none gap-2 px-0 text-xs font-medium">
-              Form
-              <ShortcutHint>{tabShortcut.quick}</ShortcutHint>
-            </TabsTrigger>
-            <TabsTrigger value="create-from" className="flex-none gap-2 px-0 text-xs font-medium">
-              Create from…
-              <ShortcutHint>{tabShortcut['create-from']}</ShortcutHint>
-            </TabsTrigger>
-          </TabsList>
+        <DialogHeader className="gap-1">
+          <DialogTitle className="text-base font-semibold">Create Workspace</DialogTitle>
+        </DialogHeader>
 
-          <DialogHeader className="gap-1 pt-4">
-            <DialogTitle className="text-base font-semibold">Create Workspace</DialogTitle>
-            <DialogDescription className="text-xs text-muted-foreground">
-              {activeTab === 'quick'
-                ? 'Pick a repository and agent to spin up a new workspace.'
-                : 'Start from an existing PR, issue, branch, or Linear ticket.'}
-            </DialogDescription>
-          </DialogHeader>
-
-          <AnimatedTabPanels active={activeTab}>
-            {{
-              quick: (
-                <QuickTabBody
-                  key={quickKey}
-                  modalData={effectiveQuickData}
-                  onClose={onClose}
-                  active={activeTab === 'quick'}
-                />
-              ),
-              'create-from': (
-                <CreateFromTab
-                  onLaunched={handleCreateFromLaunched}
-                  onFallbackToQuick={handleFallbackToQuick}
-                  active={activeTab === 'create-from'}
-                />
-              )
-            }}
-          </AnimatedTabPanels>
-        </Tabs>
+        <QuickTabBody modalData={modalData} onClose={onClose} active />
       </DialogContent>
     </Dialog>
   )
@@ -227,7 +106,8 @@ function QuickTabBody({
     initialRepoId: modalData.initialRepoId,
     ...(modalData.initialBaseBranch ? { initialBaseBranch: modalData.initialBaseBranch } : {}),
     persistDraft: false,
-    onCreated: onClose
+    onCreated: onClose,
+    ...(modalData.telemetrySource ? { telemetrySource: modalData.telemetrySource } : {})
   })
   // Why: the composer's built-in `onOpenAgentSettings` handler navigates to
   // the settings page and closes the modal. For the quick-create flow we want
@@ -321,24 +201,6 @@ function QuickTabBody({
     return () => window.removeEventListener('keydown', onKeyDown, { capture: true })
   }, [active, composerRef, createDisabled, handleCreate, onClose])
 
-  // Why: when the Quick tab becomes active (initial mount, or switched to
-  // from Create-from), focus the repo combobox trigger so the confirmed
-  // selection sits ready and the keyboard flow starts at the top of the
-  // form — matching Dialog's onOpenAutoFocus behavior in the pre-tabs modal.
-  useEffect(() => {
-    if (!active) {
-      return
-    }
-    const root = composerRef.current
-    if (!root) {
-      return
-    }
-    const trigger = root.querySelector<HTMLElement>(
-      '[data-repo-combobox-root="true"][role="combobox"]'
-    )
-    trigger?.focus({ preventScroll: true })
-  }, [active, composerRef])
-
   return (
     <>
       <NewWorkspaceComposerCard
@@ -354,161 +216,3 @@ function QuickTabBody({
     </>
   )
 }
-
-type TabKey = 'quick' | 'create-from'
-
-/**
- * Keeps both tab panels mounted so their local state (typed query on
- * Create-from, repo pick / workspace name on Quick) survives a tab swap.
- * Only the active panel is in normal flow; the inactive panel is
- * absolutely positioned + `visibility: hidden` + `pointer-events-none`
- * so it
- *   (a) doesn't contribute to DialogContent's scrollHeight (otherwise the
- *       host dialog grows a scrollbar whenever the inactive panel is
- *       taller than the active one), and
- *   (b) keeps its React subtree mounted (no remount, so input focus,
- *       typed query, and selection survive).
- *
- * The wrapper's height is JS-driven: a ResizeObserver on the active
- * panel's inner node keeps wrapper height in sync with content so the
- * wrapper never clips. On tab change we capture the pre-swap wrapper
- * height and transition to the new active panel's measured height — a
- * FLIP-style animation so the modal resizes smoothly rather than
- * snapping.
- */
-function AnimatedTabPanels({
-  active,
-  children
-}: {
-  active: TabKey
-  children: Record<TabKey, React.ReactNode>
-}): React.JSX.Element {
-  const wrapperRef = useRef<HTMLDivElement | null>(null)
-  const quickRef = useRef<HTMLDivElement | null>(null)
-  const createFromRef = useRef<HTMLDivElement | null>(null)
-  const previousActiveRef = useRef<TabKey>(active)
-  const [wrapperHeight, setWrapperHeight] = useState<number | null>(null)
-  const [isAnimating, setIsAnimating] = useState(false)
-
-  // Why: track the active panel's intrinsic height via ResizeObserver so
-  // the wrapper follows content (Advanced drawer open/close, async search
-  // results landing). When active changes, the FLIP effect below runs
-  // first (capturing the outgoing height), then this observer swings the
-  // wrapper height toward the new active panel's height via the CSS
-  // transition on `height`.
-  //
-  // Why offsetHeight and not getBoundingClientRect().height: Radix's
-  // dialog open animation (`data-[state=open]:zoom-in-95`) scales the
-  // dialog from 0.95 → 1.0 over 200ms. getBoundingClientRect reports the
-  // *visual* (transformed) height, so the very first measurement lands at
-  // ~95 % of the real layout size and pins that into the inline height.
-  // The ResizeObserver never refires because actual layout size didn't
-  // change — only the transform did — so the wrapper stays permanently
-  // ~16 px short and clips the Create Workspace button at the bottom.
-  // offsetHeight returns the un-transformed layout box, which is what the
-  // wrapper should match.
-  useLayoutEffect(() => {
-    const target = active === 'quick' ? quickRef.current : createFromRef.current
-    if (!target) {
-      return
-    }
-    const update = (): void => {
-      const next = target.offsetHeight
-      if (next > 0) {
-        setWrapperHeight(next)
-      }
-    }
-    update()
-    const observer = new ResizeObserver(update)
-    observer.observe(target)
-    return () => observer.disconnect()
-  }, [active])
-
-  // Why: on tab swap, override the observer-driven height for one frame
-  // so the transition starts from the outgoing panel's size. Without this
-  // the wrapper would snap to the new panel's height before the ResizeObserver
-  // could read it.
-  useLayoutEffect(() => {
-    const prev = previousActiveRef.current
-    previousActiveRef.current = active
-    if (prev === active) {
-      return
-    }
-    const wrapper = wrapperRef.current
-    if (!wrapper) {
-      return
-    }
-    // Why: offsetHeight, not getBoundingClientRect — see comment on the
-    // observer effect above. Same transform-scale trap applies to this
-    // FLIP capture if a tab swap happens while any ancestor transform is
-    // still animating.
-    const from = wrapper.offsetHeight
-    if (from > 0) {
-      setWrapperHeight(from)
-      setIsAnimating(true)
-    }
-  }, [active])
-
-  useEffect(() => {
-    const wrapper = wrapperRef.current
-    if (!wrapper || !isAnimating) {
-      return
-    }
-    const onEnd = (event: TransitionEvent): void => {
-      if (event.propertyName !== 'height') {
-        return
-      }
-      setIsAnimating(false)
-    }
-    wrapper.addEventListener('transitionend', onEnd)
-    return () => wrapper.removeEventListener('transitionend', onEnd)
-  }, [isAnimating])
-
-  return (
-    <div
-      ref={wrapperRef}
-      // Why: `overflow: clip` isolates the absolutely-positioned inactive
-      // panel so the wrapper's measured height drives the dialog (not the
-      // stacked panel heights). We avoid plain `overflow: hidden` because
-      // that also clips the 3px focus rings painted by nested inputs
-      // (RepoCombobox, workspace name field, etc.) — the inner panels are
-      // `inset-x-0` so their triggers sit flush against the wrapper edges,
-      // leaving no room for a ring to paint. `overflow-clip-margin` gives
-      // the ring breathing room on every side without re-introducing scroll
-      // containers or letting the inactive panel leak layout.
-      className={cn(
-        'relative overflow-clip',
-        isAnimating && 'transition-[height] duration-200 ease-out'
-      )}
-      style={{
-        ...(wrapperHeight !== null ? { height: wrapperHeight } : null),
-        overflowClipMargin: '8px'
-      }}
-    >
-      <div
-        ref={quickRef}
-        className={cn(
-          'pt-4',
-          active === 'quick'
-            ? 'pointer-events-auto'
-            : 'pointer-events-none invisible absolute inset-x-0 top-0'
-        )}
-        aria-hidden={active !== 'quick'}
-      >
-        {children.quick}
-      </div>
-      <div
-        ref={createFromRef}
-        className={cn(
-          'pt-3',
-          active === 'create-from'
-            ? 'pointer-events-auto'
-            : 'pointer-events-none invisible absolute inset-x-0 top-0'
-        )}
-        aria-hidden={active !== 'create-from'}
-      >
-        {children['create-from']}
-      </div>
-    </div>
-  )
-}
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index 4319dd131b9..04bd6348374 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -59,8 +59,10 @@ import TeamMultiCombobox from '@/components/ui/team-multi-combobox'
 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 { stripRepoQualifiers } from '../../../shared/task-query'
 import GitHubItemDialog from '@/components/GitHubItemDialog'
+import ProjectViewWrapper from '@/components/github-project/ProjectViewWrapper'
 import LinearItemDrawer from '@/components/LinearItemDrawer'
 import { cn } from '@/lib/utils'
 import {
@@ -70,7 +72,6 @@ import {
   CROSS_REPO_DISPLAY_LIMIT
 } from '@/lib/new-workspace'
 import type { LinkedWorkItemSummary } from '@/lib/new-workspace'
-import { launchWorkItemDirect } from '@/lib/launch-work-item-direct'
 import { isGitRepoKind } from '../../../shared/repo-kind'
 import { useTeamStates } from '@/hooks/useIssueMetadata'
 import type {
@@ -652,6 +653,9 @@ const hasUpstreamCandidateDivergence = (
 
 export default function TaskPage(): React.JSX.Element {
   const settings = useAppStore((s) => s.settings)
+  const persistedUIReady = useAppStore((s) => s.persistedUIReady)
+  const taskResumeState = useAppStore((s) => s.taskResumeState)
+  const setTaskResumeState = useAppStore((s) => s.setTaskResumeState)
   const pageData = useAppStore((s) => s.taskPageData)
   const closeTaskPage = useAppStore((s) => s.closeTaskPage)
   const activeModal = useAppStore((s) => s.activeModal)
@@ -674,7 +678,7 @@ export default function TaskPage(): React.JSX.Element {
   const listLinearIssues = useAppStore((s) => s.listLinearIssues)
   const checkLinearConnection = useAppStore((s) => s.checkLinearConnection)
   // Why: in workspace view (a worktree is active) App.tsx hides its
-  // full-width titlebar, so this page renders its own 42px titlebar strip to
+  // full-width titlebar, so this page renders its own 36px titlebar strip to
   // keep the top band continuous with the sidebar header and tab rows. When
   // the sidebar is also collapsed, App.tsx floats its titlebar-left controls
   // (traffic lights, sidebar toggle, agent badge) over our strip — reserve
@@ -767,6 +771,10 @@ export default function TaskPage(): React.JSX.Element {
 
   const defaultTaskSource = settings?.defaultTaskSource ?? 'github'
   const [taskSource, setTaskSource] = useState<TaskSource>(pageData.taskSource ?? defaultTaskSource)
+  const taskResumeAppliedRef = useRef(false)
+  const githubSearchPersistReadyRef = useRef(false)
+  const linearSearchPersistReadyRef = useRef(false)
+  const [taskResumeApplied, setTaskResumeApplied] = useState(false)
 
   // Why: pageData.taskSource changes when the user clicks a specific source
   // icon in the sidebar while the task page is already open. useState only
@@ -777,15 +785,23 @@ export default function TaskPage(): React.JSX.Element {
     }
   }, [pageData.taskSource])
 
-  // Why: settings load asynchronously — the useState initializer may capture
-  // null settings on fast navigation. Sync once settings arrive, but only
-  // when no explicit source was passed via sidebar icon click.
+  // Why: settings.defaultTaskSource can change while Tasks is open (Settings
+  // panel is reachable without unmounting Tasks). The one-shot resume effect
+  // only seeds taskSource on first mount, so without this sync a mid-session
+  // change to the default would not propagate when no explicit page-level
+  // taskSource was passed.
   useEffect(() => {
     if (!pageData.taskSource && settings?.defaultTaskSource) {
       setTaskSource(settings.defaultTaskSource)
     }
   }, [settings?.defaultTaskSource, pageData.taskSource])
 
+  // 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
+  // gated on a non-null `activeProject` once they pick one.
+  const projectModeVisible = taskSource === 'github'
+  const [githubMode, setGithubMode] = useState<'items' | 'project'>('items')
+
   const [taskSearchInput, setTaskSearchInput] = useState(initialTaskQuery)
   const [appliedTaskSearch, setAppliedTaskSearch] = useState(initialTaskQuery)
   const [activeTaskPreset, setActiveTaskPreset] = useState<TaskViewPresetId | null>(
@@ -1019,9 +1035,47 @@ export default function TaskPage(): React.JSX.Element {
   const [linearLoading, setLinearLoading] = useState(false)
   const [linearError, setLinearError] = useState<string | null>(null)
   const [linearSearchInput, setLinearSearchInput] = useState('')
+  const [appliedLinearSearch, setAppliedLinearSearch] = useState('')
   const [activeLinearPreset, setActiveLinearPreset] = useState<LinearPresetId>('all')
   const [linearRefreshNonce, setLinearRefreshNonce] = useState(0)
 
+  useEffect(() => {
+    if (taskResumeAppliedRef.current || !persistedUIReady || !settings) {
+      return
+    }
+
+    setTaskSource(pageData.taskSource ?? settings.defaultTaskSource)
+    setRepoSelection(resolvedInitialSelection)
+
+    const nextGithubMode = taskResumeState?.githubMode ?? 'items'
+    setGithubMode(nextGithubMode)
+
+    const preset = taskResumeState?.githubItemsPreset
+    if (preset === null) {
+      const query = taskResumeState?.githubItemsQuery ?? ''
+      setTaskSearchInput(query)
+      setAppliedTaskSearch(query)
+      setActiveTaskPreset(null)
+    } else {
+      const presetId = preset ?? settings.defaultTaskViewPreset
+      const query = getTaskPresetQuery(presetId)
+      setTaskSearchInput(query)
+      setAppliedTaskSearch(query)
+      setActiveTaskPreset(presetId)
+    }
+
+    const linearPreset = taskResumeState?.linearPreset ?? 'all'
+    const linearQuery = taskResumeState?.linearQuery ?? ''
+    setActiveLinearPreset(linearPreset)
+    setLinearSearchInput(linearQuery)
+    setAppliedLinearSearch(linearQuery)
+
+    // Why: settings and persisted UI hydrate asynchronously. Apply the restored
+    // Tasks context exactly once so later source/filter clicks remain local.
+    taskResumeAppliedRef.current = true
+    setTaskResumeApplied(true)
+  }, [persistedUIReady, settings, pageData.taskSource, resolvedInitialSelection, taskResumeState])
+
   // 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.
@@ -1030,6 +1084,9 @@ export default function TaskPage(): React.JSX.Element {
   )
 
   useEffect(() => {
+    if (!taskResumeApplied) {
+      return
+    }
     if (taskSource !== 'linear' || !linearStatus.connected) {
       return
     }
@@ -1040,7 +1097,7 @@ export default function TaskPage(): React.JSX.Element {
         console.warn('[TaskPage] Failed to fetch Linear teams')
       })
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [taskSource, linearStatus.connected])
+  }, [taskSource, linearStatus.connected, taskResumeApplied])
 
   const defaultLinearTeamSelection = settings?.defaultLinearTeamSelection
   const [linearTeamSelection, setLinearTeamSelection] = useState<ReadonlySet<string>>(() => {
@@ -1183,19 +1240,45 @@ export default function TaskPage(): React.JSX.Element {
   )
 
   useEffect(() => {
+    if (!taskResumeApplied) {
+      return
+    }
     const timeout = window.setTimeout(() => {
       setAppliedTaskSearch(taskSearchInput)
     }, TASK_SEARCH_DEBOUNCE_MS)
     return () => window.clearTimeout(timeout)
-  }, [taskSearchInput])
+  }, [taskSearchInput, taskResumeApplied])
 
   useEffect(() => {
+    if (!taskResumeApplied) {
+      return
+    }
+    if (!githubSearchPersistReadyRef.current) {
+      githubSearchPersistReadyRef.current = true
+      return
+    }
+    // Why: persist the debounced applied query regardless of the active
+    // preset. The preset-click handler writes the canonical query for that
+    // preset, so persisting again here is at worst idempotent. When the
+    // user types into the search box `handleTaskSearchChange` clears the
+    // preset, but persisting unconditionally also covers paths that change
+    // appliedTaskSearch without going through that handler.
+    setTaskResumeState({
+      githubItemsPreset: activeTaskPreset,
+      githubItemsQuery: appliedTaskSearch.trim()
+    })
+  }, [activeTaskPreset, appliedTaskSearch, setTaskResumeState, taskResumeApplied])
+
+  useEffect(() => {
+    if (!taskResumeApplied) {
+      return
+    }
     // Why: both early-return branches must clear `retryingRepoPaths` — if the
     // user clicks Retry and then switches `taskSource` away from 'github' (or
     // somehow ends up with zero repos selected) before the fetch dispatches,
     // neither the `.then` nor the `.catch` below will fire, and the Retry
     // button would stay stuck in its disabled/Retrying state indefinitely.
-    if (taskSource !== 'github') {
+    if (taskSource !== 'github' || githubMode !== 'items') {
       setRetryingRepoPaths(new Set())
       return
     }
@@ -1333,15 +1416,24 @@ export default function TaskPage(): React.JSX.Element {
     // updates. `workItemsInvalidationNonce` is explicitly included so a
     // preference flip (which only evicts cache) re-dispatches this effect.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [selectedRepos, appliedTaskSearch, taskRefreshNonce, taskSource, workItemsInvalidationNonce])
+  }, [
+    selectedRepos,
+    appliedTaskSearch,
+    taskRefreshNonce,
+    taskSource,
+    githubMode,
+    workItemsInvalidationNonce,
+    taskResumeApplied
+  ])
 
   const handleApplyTaskSearch = useCallback((): void => {
     const trimmed = taskSearchInput.trim()
     setTaskSearchInput(trimmed)
     setAppliedTaskSearch(trimmed)
     setActiveTaskPreset(null)
+    setTaskResumeState({ githubItemsPreset: null, githubItemsQuery: trimmed })
     setTaskRefreshNonce((current) => current + 1)
-  }, [taskSearchInput])
+  }, [setTaskResumeState, taskSearchInput])
 
   const handleTaskSearchChange = useCallback((event: React.ChangeEvent<HTMLInputElement>): void => {
     const next = event.target.value
@@ -1391,7 +1483,8 @@ export default function TaskPage(): React.JSX.Element {
       openModal('new-workspace-composer', {
         linkedWorkItem,
         prefilledName: getLinkedWorkItemSuggestedName(item),
-        initialRepoId: item.repoId
+        initialRepoId: item.repoId,
+        telemetrySource: 'sidebar'
       })
     },
     [openModal]
@@ -1399,17 +1492,14 @@ export default function TaskPage(): React.JSX.Element {
 
   const handleUseWorkItem = useCallback(
     (item: GitHubWorkItem): void => {
-      // Why: the "Use" CTA is the primary way to start work from this page, so
-      // skip the composer for the common case and create+activate the workspace
-      // immediately, launch the user's default agent, and paste the work item
-      // URL into the agent's input as a reviewable draft. Fall back to the
-      // composer modal only when explicit per-workspace decisions are required
-      // (setupRunPolicy === 'ask') or the repo/agent resolution fails.
-      void launchWorkItemDirect({
-        item,
-        repoId: item.repoId,
-        openModalFallback: () => openComposerForItem(item)
-      })
+      // Why: open the unified New Workspace dialog pre-filled with the work
+      // item as the selected source so the user can confirm name / agent /
+      // setup before the worktree is created. Earlier the "Use" CTA created
+      // and activated the worktree synchronously, which was disorienting —
+      // the worktree appeared in the sidebar before the user had a chance
+      // to review it. The composer already owns the prefill flow. Telemetry
+      // attribution flows via `openComposerForItem` (sets telemetrySource).
+      openComposerForItem(item)
     },
     [openComposerForItem]
   )
@@ -1595,18 +1685,34 @@ export default function TaskPage(): React.JSX.Element {
 
   // Why: debounce the Linear search input so we don't fire a request on every
   // keystroke — matches the 300ms cadence used for GitHub search.
-  const [appliedLinearSearch, setAppliedLinearSearch] = useState('')
   useEffect(() => {
+    if (!taskResumeApplied) {
+      return
+    }
     const timeout = window.setTimeout(() => {
       setAppliedLinearSearch(linearSearchInput)
     }, TASK_SEARCH_DEBOUNCE_MS)
     return () => window.clearTimeout(timeout)
-  }, [linearSearchInput])
+  }, [linearSearchInput, taskResumeApplied])
+
+  useEffect(() => {
+    if (!taskResumeApplied) {
+      return
+    }
+    if (!linearSearchPersistReadyRef.current) {
+      linearSearchPersistReadyRef.current = true
+      return
+    }
+    setTaskResumeState({ linearQuery: appliedLinearSearch.trim() })
+  }, [appliedLinearSearch, setTaskResumeState, taskResumeApplied])
 
   // Why: fetch Linear issues when the tab is active and the account is
   // connected. An empty search falls back to `listLinearIssues` (assigned
   // issues) so the default view shows the user's own work.
   useEffect(() => {
+    if (!taskResumeApplied) {
+      return
+    }
     if (taskSource !== 'linear') {
       return
     }
@@ -1651,7 +1757,8 @@ export default function TaskPage(): React.JSX.Element {
     linearStatus.connected,
     appliedLinearSearch,
     activeLinearPreset,
-    linearRefreshNonce
+    linearRefreshNonce,
+    taskResumeApplied
   ])
 
   // Why: for Linear issues the "Use" flow opens the composer with the issue
@@ -1668,7 +1775,8 @@ export default function TaskPage(): React.JSX.Element {
       }
       openModal('new-workspace-composer', {
         linkedWorkItem,
-        prefilledName: getLinkedWorkItemSuggestedName(issue)
+        prefilledName: getLinkedWorkItemSuggestedName(issue),
+        telemetrySource: 'sidebar'
       })
     },
     [openModal]
@@ -1676,30 +1784,13 @@ export default function TaskPage(): React.JSX.Element {
 
   const handleUseLinearItem = useCallback(
     (issue: LinearIssue): void => {
-      const repoId = primaryRepo?.id
-      if (!repoId) {
-        openComposerForLinearItem(issue)
-        return
-      }
-      // Why: unlike GitHub issues (fetchable via `gh`), Linear has no CLI —
-      // paste the full issue context so the agent can act on it without needing
-      // to fetch anything externally.
-      const parts = [
-        `[${issue.identifier}] ${issue.title}`,
-        `Status: ${issue.state.name} · Team: ${issue.team.name}`,
-        issue.assignee ? `Assignee: ${issue.assignee.displayName}` : null,
-        issue.labels.length > 0 ? `Labels: ${issue.labels.join(', ')}` : null,
-        `URL: ${issue.url}`,
-        issue.description ? `\n${issue.description}` : null
-      ]
-      const pasteContent = parts.filter(Boolean).join('\n')
-      void launchWorkItemDirect({
-        item: { title: issue.title, url: issue.url, type: 'issue', number: null, pasteContent },
-        repoId,
-        openModalFallback: () => openComposerForLinearItem(issue)
-      })
+      // Why: same rationale as handleUseWorkItem — open the New Workspace
+      // dialog pre-filled rather than yolo-creating the worktree, so the
+      // user can confirm name / agent / setup before the worktree lands in
+      // the sidebar. Telemetry attribution flows via openComposerForLinearItem.
+      openComposerForLinearItem(issue)
     },
-    [openComposerForLinearItem, primaryRepo?.id]
+    [openComposerForLinearItem]
   )
 
   const handleLinearConnect = useCallback(async (): Promise<void> => {
@@ -1738,7 +1829,7 @@ export default function TaskPage(): React.JSX.Element {
           paint above our content and receive the click cleanly. */}
       <div className="relative flex min-h-0 flex-1 flex-col">
         {/* Why: in workspace view App.tsx suppresses its full-width titlebar,
-            so render a matching 42px strip here to keep the top band
+            so render a matching 36px strip here to keep the top band
             continuous with the sidebar header and tab rows. When the sidebar
             is collapsed, App.tsx floats its titlebar-left controls (traffic
             lights, sidebar toggle, agent badge) over the top-left of this
@@ -1751,7 +1842,7 @@ export default function TaskPage(): React.JSX.Element {
             non-workspace mode because App.tsx already owns the top titlebar
             and a second strip would produce a duplicate band. */}
         {workspaceActive ? (
-          <div className="flex-none flex h-[42px]">
+          <div className="flex-none flex h-9">
             {reserveCollapsedHeaderSpace ? (
               // Why: the floating titlebar-left hosts real interactive chrome
               // (sidebar-expand toggle, agent badge) under this segment. Both
@@ -1778,7 +1869,13 @@ export default function TaskPage(): React.JSX.Element {
           </div>
         ) : null}
 
-        <div className="mx-auto flex w-full flex-1 flex-col min-h-0 px-5 pt-3 pb-5 md:px-8 md:pt-3 md:pb-7">
+        {/* Why: pt-1.5 vertically centers this row's 32px icon cluster (X +
+            source toggles) with the sidebar's "Tasks" nav row. Sidebar Tasks
+            center sits 22px below the titlebar (pt-2 + py-1.5 + half size-4
+            icon). Matching that here needs 6px top padding above the 32px
+            cluster (6 + 16 = 22). The previous pt-3 placed the cluster 6px
+            too low, breaking the visual band across the top chrome. */}
+        <div className="mx-auto flex w-full flex-1 flex-col min-h-0 px-5 pt-1.5 pb-5 md:px-8 md:pt-1.5 md:pb-7">
           <div className="flex-none flex flex-col gap-3">
             <section className="flex flex-col gap-3">
               <div className="flex flex-col gap-3">
@@ -1838,27 +1935,8 @@ export default function TaskPage(): React.JSX.Element {
                       )
                     })}
                   </div>
-                  <div className="w-[200px]">
-                    {taskSource === 'github' ? (
-                      <RepoMultiCombobox
-                        repos={eligibleRepos}
-                        selected={repoSelection}
-                        onChange={(next) => {
-                          setRepoSelection(next)
-                          void updateSettings({ defaultRepoSelection: [...next] }).catch(() => {
-                            toast.error('Failed to save repo selection.')
-                          })
-                        }}
-                        onSelectAll={() => {
-                          const allIds = new Set(eligibleRepos.map((r) => r.id))
-                          setRepoSelection(allIds)
-                          void updateSettings({ defaultRepoSelection: null }).catch(() => {
-                            toast.error('Failed to save repo 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"
-                      />
-                    ) : availableTeams.length > 0 ? (
+                  {taskSource === 'linear' && availableTeams.length > 0 ? (
+                    <div className="w-[200px]">
                       <TeamMultiCombobox
                         teams={availableTeams}
                         selected={linearTeamSelection}
@@ -1878,11 +1956,68 @@ export default function TaskPage(): React.JSX.Element {
                         }}
                         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"
                       />
-                    ) : null}
-                  </div>
+                    </div>
+                  ) : null}
                 </div>
 
                 {taskSource === 'github' ? (
+                  <div className="flex items-center gap-2">
+                    {projectModeVisible ? (
+                      <div className="flex items-center gap-1 text-xs">
+                        {(['items', 'project'] as const).map((mode) => {
+                          const active = githubMode === mode
+                          return (
+                            <button
+                              key={mode}
+                              type="button"
+                              onClick={() => {
+                                setGithubMode(mode)
+                                setTaskResumeState({ githubMode: mode })
+                              }}
+                              className={cn(
+                                'rounded-md border px-2 py-1 text-xs transition',
+                                active
+                                  ? 'border-border/50 bg-foreground/90 text-background'
+                                  : 'border-border/50 bg-transparent text-foreground hover:bg-muted/50'
+                              )}
+                            >
+                              {mode === 'items' ? 'Issues/PRs' : 'Project'}
+                            </button>
+                          )
+                        })}
+                      </div>
+                    ) : null}
+                    {/* Why: the repo combobox filters Items mode by repo. In
+                        Project mode the row set comes from the project's
+                        view filter (server-side), so this control would be
+                        inert — hide it to avoid suggesting it does
+                        something. */}
+                    {githubMode !== 'project' && (
+                      <div className="w-[200px]">
+                        <RepoMultiCombobox
+                          repos={eligibleRepos}
+                          selected={repoSelection}
+                          onChange={(next) => {
+                            setRepoSelection(next)
+                            void updateSettings({ defaultRepoSelection: [...next] }).catch(() => {
+                              toast.error('Failed to save repo selection.')
+                            })
+                          }}
+                          onSelectAll={() => {
+                            const allIds = new Set(eligibleRepos.map((r) => r.id))
+                            setRepoSelection(allIds)
+                            void updateSettings({ defaultRepoSelection: null }).catch(() => {
+                              toast.error('Failed to save repo 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>
+                    )}
+                  </div>
+                ) : null}
+
+                {taskSource === 'github' && githubMode === 'items' ? (
                   <div className="rounded-md rounded-b-none border border-border/50 bg-muted/50 p-3 shadow-sm">
                     <div className="flex flex-wrap items-center justify-between gap-3">
                       <div className="flex flex-wrap gap-2">
@@ -1897,6 +2032,10 @@ export default function TaskPage(): React.JSX.Element {
                                 setTaskSearchInput(query)
                                 setAppliedTaskSearch(query)
                                 setActiveTaskPreset(option.id)
+                                setTaskResumeState({
+                                  githubItemsPreset: option.id,
+                                  githubItemsQuery: query
+                                })
                                 setTaskRefreshNonce((current) => current + 1)
                               }}
                               onContextMenu={(event) => {
@@ -1917,6 +2056,13 @@ export default function TaskPage(): React.JSX.Element {
                       </div>
 
                       <div className="flex shrink-0 items-center gap-2">
+                        {/* Why: GitHub API budget pill is anchored next to the
+                            Refresh button so the "maybe I shouldn't click
+                            refresh again" decision is one glance away. Only
+                            rendered in the GitHub section because Linear has
+                            its own SDK-based quota and doesn't consume gh
+                            budget. */}
+                        <GitHubRateLimitPill />
                         <Tooltip>
                           <TooltipTrigger asChild>
                             <Button
@@ -1981,6 +2127,7 @@ export default function TaskPage(): React.JSX.Element {
                               setTaskSearchInput('')
                               setAppliedTaskSearch('')
                               setActiveTaskPreset(null)
+                              setTaskResumeState({ githubItemsPreset: null, githubItemsQuery: '' })
                               setTaskRefreshNonce((current) => current + 1)
                             }}
                             className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground transition hover:text-foreground"
@@ -2063,7 +2210,7 @@ export default function TaskPage(): React.JSX.Element {
                       )
                     })()}
                   </div>
-                ) : linearStatus.connected ? (
+                ) : taskSource === 'linear' && linearStatus.connected ? (
                   <div className="rounded-md rounded-b-none border border-border/50 bg-muted/50 p-3 shadow-sm">
                     <div className="flex flex-wrap items-center justify-between gap-3">
                       <div className="flex flex-wrap gap-2">
@@ -2077,6 +2224,7 @@ export default function TaskPage(): React.JSX.Element {
                                 setLinearSearchInput('')
                                 setAppliedLinearSearch('')
                                 setActiveLinearPreset(preset.id)
+                                setTaskResumeState({ linearPreset: preset.id, linearQuery: '' })
                                 setLinearRefreshNonce((n) => n + 1)
                               }}
                               className={cn(
@@ -2154,7 +2302,10 @@ export default function TaskPage(): React.JSX.Element {
                                 return
                               }
                               e.preventDefault()
-                              setAppliedLinearSearch(linearSearchInput.trim())
+                              const trimmed = linearSearchInput.trim()
+                              setLinearSearchInput(trimmed)
+                              setAppliedLinearSearch(trimmed)
+                              setTaskResumeState({ linearQuery: trimmed })
                               setLinearRefreshNonce((n) => n + 1)
                             }
                           }}
@@ -2168,6 +2319,7 @@ export default function TaskPage(): React.JSX.Element {
                             onClick={() => {
                               setLinearSearchInput('')
                               setAppliedLinearSearch('')
+                              setTaskResumeState({ linearQuery: '' })
                               setLinearRefreshNonce((n) => n + 1)
                             }}
                             className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground transition hover:text-foreground"
@@ -2183,7 +2335,11 @@ export default function TaskPage(): React.JSX.Element {
             </section>
           </div>
 
-          {taskSource === 'github' ? (
+          {taskSource === 'github' && githubMode === 'project' ? (
+            <div className="mt-3 flex min-h-0 max-h-full flex-col rounded-md border border-border/50 bg-muted/50 overflow-hidden shadow-sm">
+              <ProjectViewWrapper />
+            </div>
+          ) : taskSource === 'github' ? (
             <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-[80px_minmax(0,3fr)_minmax(110px,0.8fr)_100px_110px_112px] gap-3 border-b border-border/50 px-3 py-2 text-[10px] font-medium uppercase tracking-[0.16em] text-muted-foreground">
                 <span>ID</span>
diff --git a/src/renderer/src/components/TelemetryFirstLaunchSurface.tsx b/src/renderer/src/components/TelemetryFirstLaunchSurface.tsx
new file mode 100644
index 00000000000..2c311c32e52
--- /dev/null
+++ b/src/renderer/src/components/TelemetryFirstLaunchSurface.tsx
@@ -0,0 +1,57 @@
+// Root-mounted gate for the existing-user first-launch notice. New users
+// get NO first-launch surface — default-on with no first-run notice
+// matches the category norm set by every direct-shape competitor (emdash,
+// Conductor, superset-sh, cmux, T3 Code, Continue, GitButler); see
+// telemetry-plan.md §First-launch experience for the rationale.
+//
+// Cohort marker populated by the migration in `src/main/persistence.ts`:
+//
+//   - `existedBeforeTelemetryRelease === true && optedIn === null`
+//       → FirstLaunchBanner (notice; no events transmit until the user
+//         resolves it via ✕ or Turn off)
+//   - otherwise → null (nothing to show)
+//
+// A local `dismissed` state hides the notice for the rest of the session
+// after a button click — the store refresh after the IPC resolves also
+// clears the cohort condition, but the optimistic flip removes a
+// frame-lag flash where the notice briefly re-renders while settings
+// round-trip through IPC.
+
+import { useState } from 'react'
+import { useAppStore } from '../store'
+import { FirstLaunchBanner } from './FirstLaunchBanner'
+
+export function TelemetryFirstLaunchSurface(): React.JSX.Element | null {
+  const settings = useAppStore((s) => s.settings)
+  // Main's `telemetry:setOptIn` / `telemetry:acknowledgeBanner` handlers
+  // intentionally do NOT broadcast `settings:changed`, so the notice
+  // must call `fetchSettings()` itself after its IPC writes to keep the
+  // renderer store (and PrivacyPane) from rendering stale telemetry
+  // state. See PrivacyPane.tsx for the identical pattern.
+  const fetchSettings = useAppStore((s) => s.fetchSettings)
+  const [dismissedThisSession, setDismissedThisSession] = useState(false)
+
+  if (!settings || dismissedThisSession) {
+    return null
+  }
+
+  const telemetry = settings.telemetry
+  if (!telemetry) {
+    // Defensive: migration guarantees the block exists. If it somehow
+    // doesn't, show nothing rather than guessing a cohort wrong.
+    return null
+  }
+
+  const isExistingUserAwaitingBanner =
+    telemetry.existedBeforeTelemetryRelease === true && telemetry.optedIn === null
+  if (!isExistingUserAwaitingBanner) {
+    return null
+  }
+
+  return (
+    <FirstLaunchBanner
+      fetchSettings={fetchSettings}
+      onResolve={() => setDismissedThisSession(true)}
+    />
+  )
+}
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index dd0de65d7f5..6eb655f98f0 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -601,7 +601,9 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       closeModal()
       // Why: defer opening so Radix fully unmounts the palette's dialog before
       // the composer modal mounts, avoiding focus churn between the two.
-      queueMicrotask(() => openModal('new-workspace-composer', data))
+      queueMicrotask(() =>
+        openModal('new-workspace-composer', { ...data, telemetrySource: 'command_palette' })
+      )
     }
 
     // Case 1: user pasted a GH issue/PR URL.
@@ -654,11 +656,16 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
             // Fallback: we couldn't resolve the URL, just seed the name.
             data.prefilledName = `${slug.owner}-${slug.repo}-${number}`
           }
-          queueMicrotask(() => openModal('new-workspace-composer', data))
+          queueMicrotask(() =>
+            openModal('new-workspace-composer', { ...data, telemetrySource: 'command_palette' })
+          )
         })
         .catch(() => {
           queueMicrotask(() =>
-            openModal('new-workspace-composer', { initialRepoId: repoForLookup.id })
+            openModal('new-workspace-composer', {
+              initialRepoId: repoForLookup.id,
+              telemetrySource: 'command_palette'
+            })
           )
         })
       return
@@ -702,13 +709,16 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
           } else {
             data.prefilledName = trimmed
           }
-          queueMicrotask(() => openModal('new-workspace-composer', data))
+          queueMicrotask(() =>
+            openModal('new-workspace-composer', { ...data, telemetrySource: 'command_palette' })
+          )
         })
         .catch(() => {
           queueMicrotask(() =>
             openModal('new-workspace-composer', {
               initialRepoId: repoForLookup.id,
-              prefilledName: trimmed
+              prefilledName: trimmed,
+              telemetrySource: 'command_palette'
             })
           )
         })
diff --git a/src/renderer/src/components/browser-pane/BrowserPane.tsx b/src/renderer/src/components/browser-pane/BrowserPane.tsx
index 8d151ce9190..113b580b1a8 100644
--- a/src/renderer/src/components/browser-pane/BrowserPane.tsx
+++ b/src/renderer/src/components/browser-pane/BrowserPane.tsx
@@ -933,7 +933,11 @@ function BrowserPagePane({
       webview.style.width = '100%'
       webview.style.height = '100%'
       webview.style.border = 'none'
-      webview.style.background = 'transparent'
+      // Why: default to white so sites that don't set an html/body background
+      // (e.g. httpbin.org/html) don't show through to Orca's dark chrome. Real
+      // browsers paint the viewport white by default; sites that specify their
+      // own background (including dark ones) still override this.
+      webview.style.background = '#ffffff'
       webviewRegistry.set(browserTab.id, webview)
       container.appendChild(webview)
       needsInitialNavigation = true
@@ -949,6 +953,7 @@ function BrowserPagePane({
           browserPageId: browserTab.id,
           workspaceId,
           worktreeId,
+          sessionProfileId,
           webContentsId
         })
       }
diff --git a/src/renderer/src/components/browser-pane/webview-registry.ts b/src/renderer/src/components/browser-pane/webview-registry.ts
index e59c0c6a042..a3238f627da 100644
--- a/src/renderer/src/components/browser-pane/webview-registry.ts
+++ b/src/renderer/src/components/browser-pane/webview-registry.ts
@@ -36,7 +36,11 @@ export function setWebviewsDragPassthrough(passthrough: boolean): void {
 
 const DRAG_LISTENER_KEY = '__orcaBrowserPaneDragListeners'
 
-if (typeof window !== 'undefined') {
+// Why: vitest 'node' env stubs `window` as a plain object via vi.stubGlobal,
+// so `typeof window !== 'undefined'` is true but addEventListener is missing.
+// Gate on the function we actually call so importing this module from a hook
+// test (which transitively pulls us in) does not throw at module load.
+if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
   type DragListenerRegistry = {
     dragstart: () => void
     dragend: () => void
diff --git a/src/renderer/src/components/github-project/GhAuthErrorHelp.tsx b/src/renderer/src/components/github-project/GhAuthErrorHelp.tsx
new file mode 100644
index 00000000000..31cbf6c64bc
--- /dev/null
+++ b/src/renderer/src/components/github-project/GhAuthErrorHelp.tsx
@@ -0,0 +1,257 @@
+/**
+ * Inline guidance for `auth_required` / `scope_missing` errors from gh.
+ *
+ * Why: the canned remediation `gh auth refresh -s project ...` silently
+ * no-ops when GITHUB_TOKEN/GH_TOKEN is exported in the user's shell — gh
+ * prefers env tokens and refuses to refresh them. Users follow the
+ * instructions, see no error, retry, and stay stuck. This component runs
+ * a one-shot diagnostic and rewrites the suggested fix to match what gh
+ * is actually doing: env-shadow vs. plain missing-scope vs. not-installed.
+ */
+import { useEffect, useState } from 'react'
+import { Copy, ExternalLink } from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import type { GitHubProjectViewError } from '@/../../shared/github-project-types'
+import type { GhAuthDiagnostic } from '@/../../shared/github-auth-types'
+
+type AuthErrorKind = 'auth_required' | 'scope_missing'
+
+const REFRESH_CMD = 'gh auth refresh -s project -s read:org -s repo'
+const LOGIN_CMD = 'gh auth login'
+
+// AGENTS.md requires platform-specific shell guidance. The env-shadow
+// remediation needs different commands per host shell — bash/zsh on
+// macOS/Linux vs PowerShell on Windows.
+const IS_WINDOWS = typeof navigator !== 'undefined' && /Win(dows|32|64)/i.test(navigator.userAgent)
+
+function findEnvVarCommand(varName: string): { label: string; command: string } {
+  if (IS_WINDOWS) {
+    return {
+      label: 'Check if it’s set (PowerShell)',
+      command: `Get-ChildItem Env:${varName}`
+    }
+  }
+  return {
+    label: 'Find where it’s set',
+    command: `grep -RIn '${varName}' ~/.zshrc ~/.zshenv ~/.bashrc ~/.bash_profile ~/.profile ~/.config 2>/dev/null`
+  }
+}
+
+function unsetEnvVarCommand(varName: string): { label: string; command: string } {
+  if (IS_WINDOWS) {
+    // Persistent removal at the user scope; the user still needs a fresh
+    // shell/Orca relaunch for the change to take effect.
+    return {
+      label: 'Unset (PowerShell, persistent)',
+      command: `Remove-Item Env:${varName}; [Environment]::SetEnvironmentVariable('${varName}', $null, 'User')`
+    }
+  }
+  return { label: 'Unset for this shell', command: `unset ${varName}` }
+}
+
+function openExternal(url: string): void {
+  // In Electron renderers, raw `window.open` doesn't reliably route to the
+  // user's default browser. Use the same shell IPC the rest of the app
+  // uses (see SidebarToolbar.openExternalUrl).
+  void window.api.shell.openUrl(url)
+}
+
+async function copyToClipboard(text: string): Promise<void> {
+  try {
+    await window.api.ui.writeClipboardText(text)
+    toast.success('Copied to clipboard')
+  } catch {
+    toast.error('Failed to copy')
+  }
+}
+
+type Remediation = {
+  /** Short human-readable summary of why the error is happening. */
+  summary: string
+  /** Optional follow-up paragraph explaining the fix. */
+  detail?: string
+  /** Commands to surface as copyable buttons, in order. */
+  commands: { label: string; command: string }[]
+  /** Optional external doc link. */
+  docsUrl?: string
+}
+
+function buildRemediation(
+  errorMessage: string,
+  kind: AuthErrorKind,
+  diag: GhAuthDiagnostic | null
+): Remediation {
+  // Diagnostic still loading or unavailable — fall back to the canned advice
+  // so the UI never gets worse than the pre-diagnosis behavior.
+  if (!diag) {
+    return {
+      summary: errorMessage,
+      commands: [
+        { label: 'Copy command', command: kind === 'auth_required' ? LOGIN_CMD : REFRESH_CMD }
+      ]
+    }
+  }
+
+  if (!diag.ghAvailable) {
+    return {
+      summary: 'GitHub CLI (`gh`) is not installed or not on PATH.',
+      detail:
+        'Orca uses `gh` to talk to GitHub Projects. Install it from cli.github.com, then sign in.',
+      commands: [{ label: 'Copy login command', command: LOGIN_CMD }],
+      docsUrl: 'https://cli.github.com/'
+    }
+  }
+
+  const active = diag.activeAccount
+  // Most insidious failure mode: gh is using a token from the environment,
+  // so `gh auth refresh` prints "GITHUB_TOKEN is being used... first clear
+  // the value from the environment" and exits 0 without doing anything.
+  if (active?.envToken) {
+    const varName = active.envToken
+    const fallback = diag.hasKeyringFallback
+      ? ' Your keyring already has a `gh` login that will take over once the env var is gone.'
+      : ' After unsetting it, run `gh auth login` to sign in normally, then retry.'
+    return {
+      summary: `\`${varName}\` is set in your environment, so \`gh\` is using that token instead of your keyring login. \`gh auth refresh\` cannot modify env-supplied tokens — that's why running it didn't help.`,
+      detail: IS_WINDOWS
+        ? `Find where \`${varName}\` is set (System or User environment variables, or your PowerShell profile), remove it, then restart Orca so the new environment is picked up.${fallback}`
+        : `Find where \`${varName}\` is exported (commonly \`~/.zshrc\`, \`~/.zshenv\`, \`~/.bashrc\`, \`~/.profile\`, or your shell's secrets manager), remove it, then restart Orca so the new environment is picked up.${fallback}`,
+      commands: [findEnvVarCommand(varName), unsetEnvVarCommand(varName)],
+      docsUrl: 'https://cli.github.com/manual/gh_help_environment'
+    }
+  }
+
+  // gh is not the problem, but the Electron process inherited GITHUB_TOKEN
+  // from the parent shell. Even after the user runs `gh auth refresh` in a
+  // separate terminal, Orca's gh subprocess sees the env var and uses it.
+  if (diag.envTokenInProcess && (!active || diag.missingScopes.length > 0)) {
+    const varName = diag.envTokenInProcess
+    return {
+      summary: `Orca inherited \`${varName}\` from your shell, and \`gh\` is using that token. \`gh auth refresh\` doesn't apply to env-supplied tokens.`,
+      detail: `Unset \`${varName}\` in the shell that launches Orca${
+        IS_WINDOWS ? ' (or in your user environment variables)' : ' (or in your shell rc file)'
+      }, then restart Orca.`,
+      commands: [findEnvVarCommand(varName), unsetEnvVarCommand(varName)],
+      docsUrl: 'https://cli.github.com/manual/gh_help_environment'
+    }
+  }
+
+  if (kind === 'auth_required' || !active) {
+    return {
+      summary: 'You’re not signed in to GitHub via `gh`.',
+      commands: [{ label: 'Copy login command', command: LOGIN_CMD }]
+    }
+  }
+
+  // Plain missing-scope case on a keyring login — refresh will work.
+  if (diag.missingScopes.length > 0) {
+    return {
+      summary: `Your \`gh\` token is missing the ${diag.missingScopes
+        .map((s) => `\`${s}\``)
+        .join(
+          ', '
+        )} scope${diag.missingScopes.length === 1 ? '' : 's'} needed for GitHub Projects.`,
+      detail:
+        'Run the refresh command in a terminal. It will open a browser to authorize the new scopes, then come back here and reload.',
+      commands: [{ label: 'Copy refresh command', command: REFRESH_CMD }]
+    }
+  }
+
+  // Scopes look fine but GitHub still rejected us — likely SAML SSO not
+  // authorized for this org's token, or the project is in an org the token
+  // can't see. Surface the most likely fix.
+  return {
+    summary: errorMessage,
+    detail:
+      'Your token has the required scopes but GitHub still denied access. If the project is in an org with SAML SSO, you must authorize this token for the org under Settings → Developer settings → Personal access tokens → Configure SSO.',
+    commands: [{ label: 'Copy refresh command', command: REFRESH_CMD }],
+    docsUrl:
+      'https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on'
+  }
+}
+
+export function GhAuthErrorHelp({
+  error,
+  variant = 'block'
+}: {
+  error: GitHubProjectViewError & { type: AuthErrorKind }
+  variant?: 'block' | 'banner'
+}): React.JSX.Element {
+  const [diag, setDiag] = useState<GhAuthDiagnostic | null>(null)
+  useEffect(() => {
+    let cancelled = false
+    window.api.gh
+      .diagnoseAuth()
+      .then((d) => {
+        if (!cancelled) {
+          setDiag(d)
+        }
+      })
+      // Diagnostic is best-effort; never block the error UI on it.
+      .catch(() => {})
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  const remedy = buildRemediation(error.message, error.type, diag)
+  const docsUrl = remedy.docsUrl
+
+  if (variant === 'banner') {
+    return (
+      <div className="border-b border-amber-500/30 bg-amber-500/10 px-3 py-2 text-xs text-amber-800 dark:text-amber-200">
+        <div className="font-medium">{remedy.summary}</div>
+        {remedy.detail ? <div className="mt-0.5 opacity-80">{remedy.detail}</div> : null}
+        <div className="mt-1 flex flex-wrap gap-1">
+          {remedy.commands.map((c) => (
+            <button
+              key={c.command}
+              type="button"
+              onClick={() => copyToClipboard(c.command)}
+              title={c.command}
+              className="inline-flex items-center gap-1 rounded border border-amber-500/30 bg-amber-500/10 px-1.5 py-0.5 text-[11px] hover:bg-amber-500/20"
+            >
+              <Copy className="size-3" /> {c.label}
+            </button>
+          ))}
+          {docsUrl ? (
+            <a
+              href={docsUrl}
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex items-center gap-1 rounded border border-amber-500/30 px-1.5 py-0.5 text-[11px] hover:bg-amber-500/20"
+            >
+              <ExternalLink className="size-3" /> Docs
+            </a>
+          ) : null}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex flex-col gap-2 text-sm">
+      <div className="text-foreground">{remedy.summary}</div>
+      {remedy.detail ? <div className="text-muted-foreground">{remedy.detail}</div> : null}
+      <div className="flex flex-wrap gap-2">
+        {remedy.commands.map((c) => (
+          <Button
+            key={c.command}
+            size="sm"
+            variant="outline"
+            title={c.command}
+            onClick={() => copyToClipboard(c.command)}
+          >
+            <Copy className="mr-1 size-3.5" /> {c.label}
+          </Button>
+        ))}
+        {docsUrl ? (
+          <Button size="sm" variant="outline" onClick={() => openExternal(docsUrl)}>
+            <ExternalLink className="mr-1 size-3.5" /> Docs
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/github-project/ProjectCell.tsx b/src/renderer/src/components/github-project/ProjectCell.tsx
new file mode 100644
index 00000000000..e714d35fba0
--- /dev/null
+++ b/src/renderer/src/components/github-project/ProjectCell.tsx
@@ -0,0 +1,1076 @@
+/* eslint-disable max-lines -- Why: ProjectCell dispatches on field.dataType for every supported ProjectV2 field type; keeping the dispatch table and renderers colocated keeps the type-to-renderer mapping easy to audit. */
+// Why: one cell per visible column. Dispatch on `field.dataType` first (so
+// built-in ASSIGNEES/LABELS cells render their dedicated content) and fall
+// through to `fieldValuesByFieldId[field.id].kind` as a safety net so a
+// fetched value is never silently dropped.
+import React, { useState } from 'react'
+import { CircleDot, FileText, GitPullRequest, Lock } from 'lucide-react'
+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 type {
+  GitHubIssueType,
+  GitHubProjectField,
+  GitHubProjectFieldMutationValue,
+  GitHubProjectLabel,
+  GitHubProjectRow,
+  GitHubProjectUser
+} from '../../../../shared/github-project-types'
+
+type Props = {
+  row: GitHubProjectRow
+  field: GitHubProjectField
+  editable: boolean
+  onEditField?: (fieldId: string, value: GitHubProjectFieldMutationValue | null) => void
+  /** Called with add/remove login deltas when the inline assignees picker
+   *  commits a change. The parent routes this through `patchProjectIssueOrPr`
+   *  so the mutation uses the row's slug — never the active workspace repo. */
+  onEditAssignees?: (add: string[], remove: string[]) => void
+  /** Called with add/remove label-name deltas when the inline labels picker
+   *  commits a change. Routed through `patchProjectIssueOrPr` so the mutation
+   *  uses the row's slug — never the active workspace repo. */
+  onEditLabels?: (add: string[], remove: string[]) => void
+  onEditIssueType?: (issueType: GitHubIssueType | null) => void
+  onOpenDialog?: () => void
+}
+
+export default function ProjectCell({
+  row,
+  field,
+  editable,
+  onEditField,
+  onEditAssignees,
+  onEditLabels,
+  onEditIssueType,
+  onOpenDialog
+}: Props): React.JSX.Element {
+  const value = row.fieldValuesByFieldId[field.id]
+  const isRedacted = row.itemType === 'REDACTED'
+
+  // Built-in dataType dispatch first.
+  if (field.dataType === 'TITLE') {
+    return <TitleCell row={row} onOpenDialog={onOpenDialog} />
+  }
+  if (field.dataType === TYPE_FIELD_DATA_TYPE) {
+    const editableHere = editable && !isRedacted && row.itemType === 'ISSUE'
+    return <TypeCell row={row} editable={editableHere} onEditIssueType={onEditIssueType} />
+  }
+  if (field.dataType === 'ASSIGNEES') {
+    const editableHere = editable && !isRedacted && row.itemType !== 'DRAFT_ISSUE'
+    return <AssigneesCell row={row} editable={editableHere} onEditAssignees={onEditAssignees} />
+  }
+  if (field.dataType === 'LABELS') {
+    const editableHere = editable && !isRedacted && row.itemType !== 'DRAFT_ISSUE'
+    return <LabelsCell row={row} editable={editableHere} onEditLabels={onEditLabels} />
+  }
+  if (field.dataType === 'REPOSITORY') {
+    return (
+      <span className="truncate text-xs text-muted-foreground">
+        {row.content.repository ?? '—'}
+      </span>
+    )
+  }
+  if (field.dataType === 'PARENT_ISSUE') {
+    return (
+      <span className="truncate text-xs text-muted-foreground">
+        {row.content.parentIssue ? `#${row.content.parentIssue.number}` : '—'}
+      </span>
+    )
+  }
+
+  // Why: dispatch on the field's kind/dataType — not the value's kind — so an
+  // unset cell still renders the appropriate editor and the user can assign a
+  // value from scratch (e.g. set Status when it's currently empty).
+  if (field.kind === 'single-select') {
+    return (
+      <SingleSelectCell
+        row={row}
+        field={field}
+        editable={editable && !isRedacted}
+        onEditField={onEditField}
+      />
+    )
+  }
+  if (field.kind === 'iteration') {
+    return (
+      <IterationCell
+        row={row}
+        field={field}
+        editable={editable && !isRedacted}
+        onEditField={onEditField}
+      />
+    )
+  }
+  if (field.dataType === 'TEXT') {
+    const text = value?.kind === 'text' ? value.text : ''
+    return (
+      <TextCell
+        value={text}
+        editable={editable && !isRedacted}
+        onCommit={(next) => {
+          if (next === '') {
+            onEditField?.(field.id, null)
+          } else {
+            onEditField?.(field.id, { kind: 'text', text: next })
+          }
+        }}
+      />
+    )
+  }
+  if (field.dataType === 'NUMBER') {
+    const num = value?.kind === 'number' ? String(value.number) : ''
+    return (
+      <TextCell
+        value={num}
+        editable={editable && !isRedacted}
+        numeric
+        onCommit={(next) => {
+          if (next === '') {
+            onEditField?.(field.id, null)
+            return
+          }
+          const parsed = Number(next)
+          if (Number.isFinite(parsed)) {
+            onEditField?.(field.id, { kind: 'number', number: parsed })
+          }
+        }}
+      />
+    )
+  }
+  if (field.dataType === 'DATE') {
+    const date = value?.kind === 'date' ? value.date : ''
+    return (
+      <DateCell
+        value={date}
+        editable={editable && !isRedacted}
+        onCommit={(next) => {
+          if (!next) {
+            onEditField?.(field.id, null)
+          } else {
+            onEditField?.(field.id, { kind: 'date', date: next })
+          }
+        }}
+      />
+    )
+  }
+  // Read-only fallback for value kinds that aren't user-editable inline
+  // (labels/users baked into custom fields, plus any unknown shape).
+  if (value?.kind === 'labels') {
+    return (
+      <div className="flex flex-wrap gap-1">
+        {value.labels.map((l) => (
+          <LabelChip key={l.name} label={l} />
+        ))}
+      </div>
+    )
+  }
+  if (value?.kind === 'users') {
+    return (
+      <div className="flex flex-wrap gap-1">
+        {value.users.map((u) => (
+          <UserChip key={u.login} user={u} />
+        ))}
+      </div>
+    )
+  }
+  return <span className="text-xs italic text-muted-foreground">—</span>
+}
+
+function TitleCell({
+  row,
+  onOpenDialog
+}: {
+  row: GitHubProjectRow
+  onOpenDialog?: () => void
+}): React.JSX.Element {
+  if (row.itemType === 'REDACTED') {
+    return (
+      <div className="flex items-center gap-2 text-muted-foreground">
+        <Lock className="size-3.5" />
+        <span className="italic">Restricted item</span>
+      </div>
+    )
+  }
+  // Why: only PRs get a type icon. The CircleDot used for issues/drafts added
+  // visual noise without disambiguating anything (issue numbers + titles
+  // already read as issues), so it's omitted.
+  const content = (
+    <div className="flex min-w-0 items-center gap-2">
+      {row.itemType === 'PULL_REQUEST' ? (
+        <GitPullRequest className="size-3.5 shrink-0 text-muted-foreground" />
+      ) : null}
+      {row.content.number != null ? (
+        <span className="shrink-0 text-xs text-muted-foreground">#{row.content.number}</span>
+      ) : null}
+      <span className="truncate text-sm font-medium">{row.content.title}</span>
+    </div>
+  )
+  if (row.itemType === 'DRAFT_ISSUE') {
+    // Why: non-interactive for drafts. Body preview is rendered in a hover
+    // card (not wired here to avoid pulling in another component; see parent).
+    return <div className="flex items-center gap-2">{content}</div>
+  }
+  return (
+    <button
+      type="button"
+      onClick={onOpenDialog}
+      className="min-w-0 cursor-pointer text-left hover:underline"
+    >
+      {content}
+    </button>
+  )
+}
+
+function TypeCell({
+  row,
+  editable,
+  onEditIssueType
+}: {
+  row: GitHubProjectRow
+  editable: boolean
+  onEditIssueType?: (issueType: GitHubIssueType | null) => void
+}): React.JSX.Element {
+  // Why: for issues we surface the repo's `issueType` (Bug/Feature/Task etc)
+  // when set — that's the editable taxonomy. PR/Draft/Restricted rows render
+  // the static itemType glyph because there's no equivalent editable type.
+  if (row.itemType === 'ISSUE') {
+    return <IssueTypeCell row={row} editable={editable} onEditIssueType={onEditIssueType} />
+  }
+  const meta =
+    row.itemType === 'PULL_REQUEST'
+      ? { Icon: GitPullRequest, label: 'PR' }
+      : row.itemType === 'DRAFT_ISSUE'
+        ? { Icon: FileText, label: 'Draft' }
+        : { Icon: Lock, label: 'Restricted' }
+  const { Icon, label } = meta
+  return (
+    <span className="inline-flex items-center gap-1 text-xs text-muted-foreground">
+      <Icon className="size-3.5 shrink-0" />
+      <span className="truncate">{label}</span>
+    </span>
+  )
+}
+
+function IssueTypeCell({
+  row,
+  editable,
+  onEditIssueType
+}: {
+  row: GitHubProjectRow
+  editable: boolean
+  onEditIssueType?: (issueType: GitHubIssueType | null) => void
+}): React.JSX.Element {
+  const issueType = row.content.issueType
+  const [open, setOpen] = useState(false)
+  const [options, setOptions] = useState<GitHubIssueType[]>([])
+  const [loading, setLoading] = useState(false)
+  const [owner, repo] = (row.content.repository ?? '').split('/')
+
+  React.useEffect(() => {
+    if (!open || !owner || !repo) {
+      return
+    }
+    let cancelled = false
+    setLoading(true)
+    window.api.gh
+      .listIssueTypesBySlug({ owner, repo })
+      .then((res) => {
+        if (cancelled) {
+          return
+        }
+        if (res.ok) {
+          setOptions(res.types)
+        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setLoading(false)
+        }
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [open, owner, repo])
+
+  const trigger = (
+    <span className="inline-flex items-center gap-1 text-xs">
+      <CircleDot className="size-3.5 shrink-0 text-muted-foreground" />
+      {issueType ? (
+        (() => {
+          const colors = singleSelectChipColors(issueType.color ?? '')
+          return (
+            <span
+              className="inline-flex items-center rounded-md px-1.5 py-0.5 text-[10px] font-medium leading-none text-[var(--github-project-chip-fg-light)] dark:text-[var(--github-project-chip-fg-dark)]"
+              style={chipStyle(colors)}
+            >
+              {issueType.name}
+            </span>
+          )
+        })()
+      ) : (
+        <span className="text-muted-foreground">Issue</span>
+      )}
+    </span>
+  )
+
+  if (!editable) {
+    return <div>{trigger}</div>
+  }
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="cursor-pointer rounded text-left hover:bg-muted/40 px-0.5 -mx-0.5"
+        >
+          {trigger}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-64 p-1" align="start">
+        {!owner || !repo ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">Row has no repo slug.</div>
+        ) : loading ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
+        ) : options.length === 0 ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">
+            This repo has no Issue Types.
+          </div>
+        ) : (
+          options.map((t) => (
+            <button
+              key={t.id}
+              type="button"
+              className="flex w-full items-start gap-2 rounded px-2 py-1 text-left text-xs hover:bg-muted/50"
+              onClick={() => {
+                onEditIssueType?.(t)
+                setOpen(false)
+              }}
+            >
+              <span
+                className="mt-1 inline-block size-2 shrink-0 rounded-full"
+                style={{ background: colorHex(t.color ?? '') || '#8b949e' }}
+              />
+              <span className="min-w-0">
+                <span className="block truncate">{t.name}</span>
+                {t.description ? (
+                  <span className="block truncate text-[10px] text-muted-foreground">
+                    {t.description}
+                  </span>
+                ) : null}
+              </span>
+            </button>
+          ))
+        )}
+        {issueType ? (
+          <button
+            type="button"
+            className="mt-1 w-full rounded px-2 py-1 text-left text-xs text-muted-foreground hover:bg-muted/50"
+            onClick={() => {
+              onEditIssueType?.(null)
+              setOpen(false)
+            }}
+          >
+            Clear
+          </button>
+        ) : null}
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function SingleSelectCell({
+  row,
+  field,
+  editable,
+  onEditField
+}: {
+  row: GitHubProjectRow
+  field: GitHubProjectField
+  editable: boolean
+  onEditField?: (fieldId: string, value: GitHubProjectFieldMutationValue | null) => void
+}): React.JSX.Element {
+  const value = row.fieldValuesByFieldId[field.id]
+  const [open, setOpen] = useState(false)
+  const options = field.kind === 'single-select' ? field.options : []
+  // Why: GitHub single-select options ship a hue that is too dark to read on
+  // the app's dark background when used as plain text. Reuse the label-chip
+  // dark-mode mapping (translucent fill + brightened hue text) so status pills
+  // stay readable across the same color palette.
+  const label =
+    value?.kind === 'single-select' ? (
+      (() => {
+        const colors = singleSelectChipColors(value.color)
+        return (
+          <span
+            className="inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 text-xs font-medium leading-none text-[var(--github-project-chip-fg-light)] dark:text-[var(--github-project-chip-fg-dark)]"
+            style={chipStyle(colors)}
+          >
+            {value.name}
+          </span>
+        )
+      })()
+    ) : (
+      <EmptyCellPlaceholder editable={editable} />
+    )
+  if (!editable) {
+    return <div>{label}</div>
+  }
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="cursor-pointer text-left rounded hover:bg-muted/40 px-0.5 -mx-0.5"
+        >
+          {label}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-56 p-1">
+        {options.map((o) => (
+          <button
+            key={o.id}
+            type="button"
+            className="flex w-full items-center gap-2 rounded px-2 py-1 text-sm hover:bg-muted/50"
+            onClick={() => {
+              onEditField?.(field.id, { kind: 'single-select', optionId: o.id })
+              setOpen(false)
+            }}
+          >
+            <span
+              className="inline-block size-2 rounded-full"
+              style={{ background: colorHex(o.color) }}
+            />
+            {o.name}
+          </button>
+        ))}
+        <button
+          type="button"
+          className="mt-1 w-full rounded px-2 py-1 text-left text-xs text-muted-foreground hover:bg-muted/50"
+          onClick={() => {
+            onEditField?.(field.id, null)
+            setOpen(false)
+          }}
+        >
+          Clear
+        </button>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function IterationCell({
+  row,
+  field,
+  editable,
+  onEditField
+}: {
+  row: GitHubProjectRow
+  field: GitHubProjectField
+  editable: boolean
+  onEditField?: (fieldId: string, value: GitHubProjectFieldMutationValue | null) => void
+}): React.JSX.Element {
+  const value = row.fieldValuesByFieldId[field.id]
+  const [open, setOpen] = useState(false)
+  const iterations = field.kind === 'iteration' ? field.iterations : []
+  const completed = iterations.filter((it) => it.completed)
+  const active = iterations.filter((it) => !it.completed)
+  const label =
+    value?.kind === 'iteration' ? (
+      <span className="inline-flex items-center gap-1 rounded-md border border-border/50 bg-muted/40 px-1.5 py-0.5 text-xs">
+        {value.title}
+      </span>
+    ) : (
+      <EmptyCellPlaceholder editable={editable} />
+    )
+  if (!editable) {
+    return <div>{label}</div>
+  }
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="cursor-pointer text-left rounded hover:bg-muted/40 px-0.5 -mx-0.5"
+        >
+          {label}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-64 p-1">
+        {completed.length > 0 ? (
+          <div className="px-2 pt-1 text-[10px] uppercase tracking-wide text-muted-foreground">
+            Completed
+          </div>
+        ) : null}
+        {completed.map((it) => (
+          <IterationRow
+            key={it.id}
+            iteration={it}
+            onClick={() => {
+              onEditField?.(field.id, { kind: 'iteration', iterationId: it.id })
+              setOpen(false)
+            }}
+          />
+        ))}
+        {active.length > 0 ? (
+          <div className="px-2 pt-1 text-[10px] uppercase tracking-wide text-muted-foreground">
+            Current & upcoming
+          </div>
+        ) : null}
+        {active.map((it) => (
+          <IterationRow
+            key={it.id}
+            iteration={it}
+            onClick={() => {
+              onEditField?.(field.id, { kind: 'iteration', iterationId: it.id })
+              setOpen(false)
+            }}
+          />
+        ))}
+        <button
+          type="button"
+          className="mt-1 w-full rounded px-2 py-1 text-left text-xs text-muted-foreground hover:bg-muted/50"
+          onClick={() => {
+            onEditField?.(field.id, null)
+            setOpen(false)
+          }}
+        >
+          Clear
+        </button>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function IterationRow({
+  iteration,
+  onClick
+}: {
+  iteration: { title: string; startDate: string; duration: number }
+  onClick: () => void
+}): React.JSX.Element {
+  return (
+    <button
+      type="button"
+      className="flex w-full flex-col items-start rounded px-2 py-1 hover:bg-muted/50"
+      onClick={onClick}
+    >
+      <span className="text-sm">{iteration.title}</span>
+      <span className="text-[10px] text-muted-foreground">
+        {iteration.startDate} · {iteration.duration}d
+      </span>
+    </button>
+  )
+}
+
+function TextCell({
+  value,
+  editable,
+  numeric,
+  onCommit
+}: {
+  value: string
+  editable: boolean
+  numeric?: boolean
+  onCommit: (next: string) => void
+}): React.JSX.Element {
+  const [editing, setEditing] = useState(false)
+  const [draft, setDraft] = useState(value)
+  if (!editable) {
+    return <span className="truncate text-xs">{value || '—'}</span>
+  }
+  if (!editing) {
+    return (
+      <button
+        type="button"
+        onClick={() => {
+          setDraft(value)
+          setEditing(true)
+        }}
+        className="cursor-pointer text-left text-xs hover:underline"
+      >
+        {value || <span className="italic text-muted-foreground">—</span>}
+      </button>
+    )
+  }
+  return (
+    <Input
+      autoFocus
+      type={numeric ? 'number' : 'text'}
+      value={draft}
+      onChange={(e) => setDraft(e.target.value)}
+      onBlur={() => {
+        setEditing(false)
+        if (draft !== value) {
+          onCommit(draft)
+        }
+      }}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') {
+          e.preventDefault()
+          setEditing(false)
+          if (draft !== value) {
+            onCommit(draft)
+          }
+        } else if (e.key === 'Escape') {
+          e.preventDefault()
+          setEditing(false)
+          setDraft(value)
+        }
+      }}
+      className="h-6 text-xs"
+    />
+  )
+}
+
+function DateCell({
+  value,
+  editable,
+  onCommit
+}: {
+  value: string
+  editable: boolean
+  onCommit: (next: string) => void
+}): React.JSX.Element {
+  // Why: a date <input> fires onChange on every digit/spinner adjustment.
+  // Committing on each fires a GraphQL mutation per keystroke. Buffer the
+  // edit locally and commit on blur or Enter — same UX as TextCell.
+  const [draft, setDraft] = React.useState(value ?? '')
+  React.useEffect(() => {
+    setDraft(value ?? '')
+  }, [value])
+  if (!editable) {
+    return <span className="text-xs">{value || '—'}</span>
+  }
+  return (
+    <input
+      type="date"
+      value={draft}
+      onChange={(e) => setDraft(e.target.value)}
+      onBlur={() => {
+        if (draft !== (value ?? '')) {
+          onCommit(draft)
+        }
+      }}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') {
+          e.preventDefault()
+          ;(e.target as HTMLInputElement).blur()
+        } else if (e.key === 'Escape') {
+          e.preventDefault()
+          setDraft(value ?? '')
+          ;(e.target as HTMLInputElement).blur()
+        }
+      }}
+      className="h-6 cursor-pointer rounded border border-border/50 bg-background px-1 text-xs"
+    />
+  )
+}
+
+function LabelChip({ label }: { label: GitHubProjectLabel }): React.JSX.Element {
+  // Why: match GitHub's dark-mode label rendering — translucent fill of the
+  // label color with a brighter foreground derived from the same hue. The
+  // outline-only chip we had before was hard to read against the dark UI.
+  const colors = labelChipColors(label.color)
+  return (
+    <span
+      className="inline-flex items-center rounded-full px-1.5 py-0.5 text-[10px] font-medium leading-none text-[var(--github-project-chip-fg-light)] dark:text-[var(--github-project-chip-fg-dark)]"
+      style={chipStyle(colors)}
+    >
+      {label.name}
+    </span>
+  )
+}
+
+function UserChip({ user }: { user: GitHubProjectUser }): React.JSX.Element {
+  if (user.avatarUrl) {
+    return (
+      <img
+        src={user.avatarUrl}
+        alt={user.login}
+        title={user.login}
+        className="size-5 rounded-full border border-border/40"
+      />
+    )
+  }
+  return (
+    <span
+      title={user.login}
+      className="inline-flex size-5 items-center justify-center rounded-full bg-muted text-[10px]"
+    >
+      {user.login.slice(0, 1).toUpperCase()}
+    </span>
+  )
+}
+
+function AssigneesCell({
+  row,
+  editable,
+  onEditAssignees
+}: {
+  row: GitHubProjectRow
+  editable: boolean
+  onEditAssignees?: (add: string[], remove: string[]) => void
+}): React.JSX.Element {
+  const assignees = row.content.assignees
+  const [open, setOpen] = useState(false)
+  const [options, setOptions] = useState<GitHubAssignableUser[]>([])
+  const [loading, setLoading] = useState(false)
+
+  const [owner, repo] = (row.content.repository ?? '').split('/')
+
+  // Why: stabilize the assignee identity used as the seed list. `assignees`
+  // is a fresh array every parent render, so depending on it directly would
+  // refire the IPC on every unrelated re-render while the popover is open
+  // (the same call the rate-limit pill is meant to discourage). Joining the
+  // sorted logins gives us a stable string identity.
+  const seedKey = React.useMemo(
+    () =>
+      assignees
+        .map((a) => a.login)
+        .sort()
+        .join(','),
+    [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 labelContent =
+    assignees.length === 0 ? (
+      <span className="italic">—</span>
+    ) : (
+      assignees.map((u) => <UserChip key={u.login} user={u} />)
+    )
+
+  if (!editable) {
+    return (
+      <div className="flex flex-wrap items-center gap-1 text-xs text-muted-foreground">
+        {labelContent}
+      </div>
+    )
+  }
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className={cn(
+            'flex flex-wrap items-center gap-1 cursor-pointer text-xs text-muted-foreground hover:text-foreground'
+          )}
+        >
+          {labelContent}
+        </button>
+      </PopoverTrigger>
+      <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 ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
+        ) : (
+          options.map((u) => {
+            const isOn = assignees.some((a) => a.login === u.login)
+            return (
+              <button
+                key={u.login}
+                type="button"
+                className="flex w-full items-center gap-2 rounded px-2 py-1 text-xs hover:bg-muted/50"
+                onClick={() => {
+                  if (isOn) {
+                    onEditAssignees?.([], [u.login])
+                  } else {
+                    onEditAssignees?.([u.login], [])
+                  }
+                }}
+              >
+                <span
+                  className={cn(
+                    'inline-block size-2 rounded-full',
+                    isOn ? 'bg-primary' : 'bg-muted-foreground/40'
+                  )}
+                />
+                {u.avatarUrl ? (
+                  <img src={u.avatarUrl} alt="" className="size-4 rounded-full" />
+                ) : null}
+                {u.login}
+              </button>
+            )
+          })
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function LabelsCell({
+  row,
+  editable,
+  onEditLabels
+}: {
+  row: GitHubProjectRow
+  editable: boolean
+  onEditLabels?: (add: string[], remove: string[]) => void
+}): React.JSX.Element {
+  const labels = row.content.labels
+  const [open, setOpen] = useState(false)
+  const [options, setOptions] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+
+  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 labelContent =
+    labels.length === 0 ? (
+      <EmptyCellPlaceholder editable={editable} />
+    ) : (
+      labels.map((l) => <LabelChip key={l.name} label={l} />)
+    )
+
+  if (!editable) {
+    return <div className="flex flex-wrap items-center gap-1">{labelContent}</div>
+  }
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className={cn(
+            'flex flex-wrap items-center gap-1 cursor-pointer rounded px-0.5 -mx-0.5 hover:bg-muted/40'
+          )}
+        >
+          {labelContent}
+        </button>
+      </PopoverTrigger>
+      <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 ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
+        ) : options.length === 0 ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">No labels in this repo.</div>
+        ) : (
+          options.map((name) => {
+            const isOn = labels.some((l) => l.name === name)
+            return (
+              <button
+                key={name}
+                type="button"
+                className="flex w-full cursor-pointer items-center gap-2 rounded px-2 py-1 text-xs hover:bg-muted/50"
+                onClick={() => {
+                  if (isOn) {
+                    onEditLabels?.([], [name])
+                  } else {
+                    onEditLabels?.([name], [])
+                  }
+                }}
+              >
+                <span
+                  className={cn(
+                    'inline-block size-2 rounded-full',
+                    isOn ? 'bg-primary' : 'bg-muted-foreground/40'
+                  )}
+                />
+                {name}
+              </button>
+            )
+          })
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function EmptyCellPlaceholder({ editable }: { editable: boolean }): React.JSX.Element {
+  // Why: an unset cell still needs to be a visible click target so users can
+  // assign a value from scratch. The em-dash is intentional — the wrapping
+  // PopoverTrigger button supplies the hover background that signals
+  // clickability, so we don't need a wordy "Set value" placeholder.
+  return (
+    <span
+      className={cn(
+        'text-xs italic',
+        editable ? 'text-muted-foreground/60' : 'text-muted-foreground'
+      )}
+    >
+      —
+    </span>
+  )
+}
+
+function colorHex(color: string): string {
+  if (!color) {
+    return 'inherit'
+  }
+  if (color.startsWith('#')) {
+    return color
+  }
+  // GitHub returns 6-hex without `#`.
+  if (/^[0-9a-fA-F]{6}$/.test(color)) {
+    return `#${color}`
+  }
+  return color
+}
+
+// Why: GitHub single-select fields return color as a keyword like "RED" or
+// "PURPLE", not a hex value. Map to Primer's dark-mode option palette so we
+// can reuse labelChipColors for the chip styling.
+const SINGLE_SELECT_HEX: Record<string, string> = {
+  GRAY: '#8b949e',
+  RED: '#f85149',
+  ORANGE: '#db6d28',
+  YELLOW: '#d29922',
+  GREEN: '#3fb950',
+  BLUE: '#58a6ff',
+  PURPLE: '#bc8cff',
+  PINK: '#db61a2'
+}
+
+type ChipColors = {
+  bg: string
+  fgLight: string
+  fgDark: string
+  border: string
+}
+
+function chipStyle(colors: ChipColors): React.CSSProperties {
+  return {
+    '--github-project-chip-fg-light': colors.fgLight,
+    '--github-project-chip-fg-dark': colors.fgDark,
+    backgroundColor: colors.bg,
+    boxShadow: `inset 0 0 0 1px ${colors.border}`
+  } as React.CSSProperties
+}
+
+function singleSelectChipColors(color: string): ChipColors {
+  if (!color) {
+    return labelChipColors('')
+  }
+  const upper = color.toUpperCase()
+  const hex = SINGLE_SELECT_HEX[upper]
+  if (hex) {
+    return labelChipColors(hex)
+  }
+  return labelChipColors(color)
+}
+
+// Why: GitHub renders labels in dark mode as a low-alpha tint of the label
+// color with text re-mapped to a lightness that reads well on the tint. We
+// approximate Primer's algorithm so our chips match the GitHub UI.
+function labelChipColors(color: string): ChipColors {
+  const fallback = {
+    bg: 'rgba(125,125,125,0.18)',
+    fgLight: '#4b5563',
+    fgDark: '#e6edf3',
+    border: 'rgba(125,125,125,0.36)'
+  }
+  if (!color) {
+    return fallback
+  }
+  const hex = color.startsWith('#') ? color.slice(1) : color
+  if (!/^[0-9a-fA-F]{6}$/.test(hex)) {
+    return fallback
+  }
+  const r = parseInt(hex.slice(0, 2), 16)
+  const g = parseInt(hex.slice(2, 4), 16)
+  const b = parseInt(hex.slice(4, 6), 16)
+  const [h, s] = rgbToHsl(r, g, b)
+  const bg = `rgba(${r}, ${g}, ${b}, 0.18)`
+  const border = `rgba(${r}, ${g}, ${b}, 0.3)`
+  // Why: the dark-theme text lift turns chips into near-white-on-pastel in
+  // light mode. Keep the same tint, but anchor text in the darker hue range.
+  const fgLight = hslToCss(h, Math.max(s, 0.45), 0.32)
+  // Primer dark-theme label: bg ~18% alpha of base, border ~30%, text lifted
+  // to L≈85% so it stays bright but keeps the hue.
+  const fgDark = hslToCss(h, Math.max(s, 0.5), 0.85)
+  return { bg, fgLight, fgDark, border }
+}
+
+function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
+  const rn = r / 255
+  const gn = g / 255
+  const bn = b / 255
+  const max = Math.max(rn, gn, bn)
+  const min = Math.min(rn, gn, bn)
+  const l = (max + min) / 2
+  const d = max - min
+  if (d === 0) {
+    return [0, 0, l]
+  }
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+  let h = 0
+  switch (max) {
+    case rn:
+      h = ((gn - bn) / d + (gn < bn ? 6 : 0)) * 60
+      break
+    case gn:
+      h = ((bn - rn) / d + 2) * 60
+      break
+    default:
+      h = ((rn - gn) / d + 4) * 60
+  }
+  return [h, s, l]
+}
+
+function hslToCss(h: number, s: number, l: number): string {
+  return `hsl(${h.toFixed(0)} ${(s * 100).toFixed(0)}% ${(l * 100).toFixed(0)}%)`
+}
diff --git a/src/renderer/src/components/github-project/ProjectGroupHeader.tsx b/src/renderer/src/components/github-project/ProjectGroupHeader.tsx
new file mode 100644
index 00000000000..5f77a8a094e
--- /dev/null
+++ b/src/renderer/src/components/github-project/ProjectGroupHeader.tsx
@@ -0,0 +1,53 @@
+import React from 'react'
+import { ChevronDown, ChevronRight } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { isIterationCurrent, type ProjectGroup } from './group-sort'
+
+type Props = {
+  group: ProjectGroup
+  expanded: boolean
+  onToggle: () => void
+}
+
+export default function ProjectGroupHeader({
+  group,
+  expanded,
+  onToggle
+}: Props): React.JSX.Element {
+  const isCurrent = group.iteration ? isIterationCurrent(group.iteration) : false
+  const dateRange = group.iteration
+    ? formatDateRange(group.iteration.startDate, group.iteration.duration)
+    : null
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      className={cn(
+        'flex w-full items-center gap-2 border-b border-border/50 bg-muted/40 px-3 py-1.5 text-left text-xs',
+        'hover:bg-muted/60'
+      )}
+    >
+      {expanded ? <ChevronDown className="size-3.5" /> : <ChevronRight className="size-3.5" />}
+      <span className="font-medium">{group.label || 'All'}</span>
+      <span className="rounded-full border border-border/50 bg-background px-1.5 text-[10px] text-muted-foreground">
+        {group.rows.length}
+      </span>
+      {dateRange ? <span className="text-[10px] text-muted-foreground">{dateRange}</span> : null}
+      {isCurrent ? (
+        <span className="rounded-full border border-emerald-500/30 bg-emerald-500/10 px-1.5 text-[10px] text-emerald-700 dark:text-emerald-300">
+          Current
+        </span>
+      ) : null}
+    </button>
+  )
+}
+
+function formatDateRange(startDate: string, duration: number): string {
+  const start = new Date(`${startDate}T00:00:00Z`)
+  if (Number.isNaN(start.getTime())) {
+    return ''
+  }
+  const end = new Date(start.getTime() + (duration - 1) * 86_400_000)
+  const fmt = (d: Date): string => `${d.getUTCMonth() + 1}/${d.getUTCDate()}`
+  return `${fmt(start)} – ${fmt(end)}`
+}
diff --git a/src/renderer/src/components/github-project/ProjectItemSlugDialog.tsx b/src/renderer/src/components/github-project/ProjectItemSlugDialog.tsx
new file mode 100644
index 00000000000..6cde9f00bf8
--- /dev/null
+++ b/src/renderer/src/components/github-project/ProjectItemSlugDialog.tsx
@@ -0,0 +1,45 @@
+// Why: when a Project row's `content.repository` does not match any
+// registered Orca repo, the main `GitHubItemDialog` cannot be used in
+// repo-backed mode — it requires a `repoPath` for label/assignee pickers
+// and conversation details. Per design doc §Dialog editing from Project
+// rows, the dialog for unknown-repo rows is allowed to be a simplified
+// surface (conversation + title/body/labels/assignees/comments) with
+// Files, Checks, and review-thread tabs hidden. This component is that
+// simplified surface; it also routes every write through slug-addressed
+// mutation helpers and patches the Project table cache on success.
+import React from 'react'
+import { VisuallyHidden } from 'radix-ui'
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from '@/components/ui/sheet'
+import type { GitHubItemDialogProjectOrigin } from '@/components/GitHubItemDialog'
+import { SlugDialogBody } from './slug-dialog/SlugDialogBody'
+
+type Props = {
+  projectOrigin: GitHubItemDialogProjectOrigin | null
+  onClose: () => void
+}
+
+export default function ProjectItemSlugDialog({
+  projectOrigin,
+  onClose
+}: Props): React.JSX.Element {
+  const open = projectOrigin !== null
+
+  return (
+    <Sheet open={open} onOpenChange={(o) => !o && onClose()}>
+      <SheetContent
+        side="right"
+        showCloseButton={false}
+        className="flex w-full flex-col gap-0 overflow-hidden p-0 sm:max-w-[720px] lg:max-w-[860px]"
+        onOpenAutoFocus={(e) => e.preventDefault()}
+      >
+        <VisuallyHidden.Root asChild>
+          <SheetTitle>GitHub item</SheetTitle>
+        </VisuallyHidden.Root>
+        <VisuallyHidden.Root asChild>
+          <SheetDescription>Project row preview.</SheetDescription>
+        </VisuallyHidden.Root>
+        {projectOrigin ? <SlugDialogBody projectOrigin={projectOrigin} onClose={onClose} /> : null}
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/src/renderer/src/components/github-project/ProjectPicker.tsx b/src/renderer/src/components/github-project/ProjectPicker.tsx
new file mode 100644
index 00000000000..54ea8496d75
--- /dev/null
+++ b/src/renderer/src/components/github-project/ProjectPicker.tsx
@@ -0,0 +1,699 @@
+/* eslint-disable max-lines -- Why: project picker handles pinned, recent, browse-all listing, paste-to-add, view selection, and accessibility-related orchestration in one place to keep the entry-point flow coherent. */
+// Why: the picker is the only v1 entry point for switching projects (no
+// header tab strip). Pinned + Recent come from settings; Browse all lazy-loads
+// from `listAccessibleProjects` and is cached for 5 minutes. Paste-to-add
+// accepts org/user project URLs and `owner/number` shorthand.
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import { AlertTriangle, ChevronDown, Loader, Pin, Search } from 'lucide-react'
+import { toast } from 'sonner'
+import { GhAuthErrorHelp } from '@/components/github-project/GhAuthErrorHelp'
+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 { useAppStore } from '@/store'
+import type {
+  GitHubProjectOwnerType,
+  GitHubProjectSettings,
+  GitHubProjectSummary,
+  GitHubProjectViewError,
+  GitHubProjectViewSummary
+} from '../../../../shared/github-project-types'
+
+export type ResolvedProjectSelection = {
+  owner: string
+  ownerType: GitHubProjectOwnerType
+  projectNumber: number
+  viewId?: string
+}
+
+type Props = {
+  activeProject: {
+    owner: string
+    ownerType: GitHubProjectOwnerType
+    number: number
+    title?: string
+  } | null
+  onSelect: (selection: ResolvedProjectSelection) => void
+}
+
+const BROWSE_CACHE_TTL_MS = 5 * 60_000
+let browseCache: {
+  fetchedAt: number
+  projects: GitHubProjectSummary[]
+  partialFailures?: { owner: string; message: string }[]
+} | null = null
+
+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 [open, setOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const [browseLoading, setBrowseLoading] = useState(false)
+  const [browseError, setBrowseError] = useState<GitHubProjectViewError | null>(null)
+  const [browseProjects, setBrowseProjects] = useState<GitHubProjectSummary[]>(
+    () => browseCache?.projects ?? []
+  )
+  // Why: partial-failures are cached alongside projects so dismissing the
+  // popover and reopening within the 5min window doesn't flicker the
+  // banner back. Populated only when discovery succeeded but a subset of
+  // orgs failed (the 504 path the user reported).
+  const [partialFailures, setPartialFailures] = useState<{ owner: string; message: string }[]>(
+    () => browseCache?.partialFailures ?? []
+  )
+  const [pasteInput, setPasteInput] = useState('')
+  const [pasteError, setPasteError] = useState<string | null>(null)
+  const [pasteBusy, setPasteBusy] = useState(false)
+
+  // View-pick step state.
+  const [viewPickFor, setViewPickFor] = useState<ResolvedProjectSelection | null>(null)
+  const [viewList, setViewList] = useState<GitHubProjectViewSummary[]>([])
+  const [viewLoading, setViewLoading] = useState(false)
+
+  const loadBrowse = useCallback(async () => {
+    if (browseCache && Date.now() - browseCache.fetchedAt < BROWSE_CACHE_TTL_MS) {
+      setBrowseProjects(browseCache.projects)
+      setPartialFailures(browseCache.partialFailures ?? [])
+      return
+    }
+    setBrowseLoading(true)
+    setBrowseError(null)
+    try {
+      const res = await window.api.gh.listAccessibleProjects()
+      if (res.ok) {
+        browseCache = {
+          fetchedAt: Date.now(),
+          projects: res.projects,
+          partialFailures: res.partialFailures
+        }
+        setBrowseProjects(res.projects)
+        setPartialFailures(res.partialFailures ?? [])
+      } else {
+        setBrowseError(res.error)
+      }
+    } catch (err) {
+      setBrowseError({
+        type: 'unknown',
+        message: err instanceof Error ? err.message : 'Failed to list projects'
+      })
+    } finally {
+      setBrowseLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    if (open && !viewPickFor) {
+      void loadBrowse()
+    }
+  }, [open, viewPickFor, loadBrowse])
+
+  const updateProjectSettings = useCallback(
+    async (mutate: (prev: GitHubProjectSettings) => GitHubProjectSettings) => {
+      const prev = projectSettings
+      const next = mutate(prev)
+      // Why: settings deep-merges only notifications; write the full
+      // githubProjects object so sibling fields (pinned/recent/lastView/active)
+      // are not clobbered by a partial write.
+      await updateSettings({ githubProjects: next })
+    },
+    [projectSettings, updateSettings]
+  )
+
+  const commitSelection = useCallback(
+    async (selection: ResolvedProjectSelection, title: string | null) => {
+      const key = `${selection.ownerType}:${selection.owner}:${selection.projectNumber}`
+      await updateProjectSettings((prev) => {
+        const recent = [
+          {
+            owner: selection.owner,
+            ownerType: selection.ownerType,
+            number: selection.projectNumber,
+            lastOpenedAt: new Date().toISOString()
+          },
+          ...prev.recent.filter((r) => `${r.ownerType}:${r.owner}:${r.number}` !== key)
+        ].slice(0, 10)
+        const lastViewByProject = { ...prev.lastViewByProject }
+        if (selection.viewId) {
+          lastViewByProject[key] = { viewId: selection.viewId }
+        }
+        return {
+          ...prev,
+          recent,
+          lastViewByProject,
+          activeProject: {
+            owner: selection.owner,
+            ownerType: selection.ownerType,
+            number: selection.projectNumber
+          }
+        }
+      })
+      onSelect(selection)
+      setOpen(false)
+      setQuery('')
+      setViewPickFor(null)
+      void title
+    },
+    [onSelect, updateProjectSettings]
+  )
+
+  const handleChooseProject = useCallback(
+    async (selection: {
+      owner: string
+      ownerType: GitHubProjectOwnerType
+      number: number
+      title?: string
+      // Why: when the paste resolver parsed a /views/{n} URL, the caller
+      // passes the view number through so we can skip the view-pick step
+      // and commit directly once listProjectViews returns the matching id.
+      viewNumber?: number
+    }) => {
+      const key = `${selection.ownerType}:${selection.owner}:${selection.number}`
+      const lastView = projectSettings.lastViewByProject[key]?.viewId
+      // Why: an explicit viewNumber from the URL takes precedence over the
+      // remembered last view — the user's intent (paste this exact view) wins
+      // over the heuristic (re-open the last view they used).
+      if (lastView && selection.viewNumber === undefined) {
+        await commitSelection(
+          {
+            owner: selection.owner,
+            ownerType: selection.ownerType,
+            projectNumber: selection.number,
+            viewId: lastView
+          },
+          selection.title ?? null
+        )
+        return
+      }
+      // No prior view (or explicit viewNumber from URL) — load views.
+      setViewPickFor({
+        owner: selection.owner,
+        ownerType: selection.ownerType,
+        projectNumber: selection.number
+      })
+      setViewLoading(true)
+      try {
+        const res = await window.api.gh.listProjectViews({
+          owner: selection.owner,
+          ownerType: selection.ownerType,
+          projectNumber: selection.number
+        })
+        if (res.ok) {
+          setViewList(res.views)
+          if (selection.viewNumber !== undefined) {
+            // Why: the URL pinned a specific view number — find its id and
+            // commit directly, bypassing the view-pick step. If the number
+            // doesn't match any view (deleted/renumbered), fall through to
+            // the picker so the user can choose another view.
+            const match = res.views.find((v) => v.number === selection.viewNumber)
+            if (match) {
+              await commitSelection(
+                {
+                  owner: selection.owner,
+                  ownerType: selection.ownerType,
+                  projectNumber: selection.number,
+                  viewId: match.id
+                },
+                selection.title ?? null
+              )
+            }
+          }
+        } else {
+          setViewList([])
+          toast.error(res.error.message)
+        }
+      } catch (err) {
+        // Why: IPC transport errors (channel disconnect, serialization
+        // failure) propagate as rejected promises and would otherwise become
+        // unhandled rejections — leaving the picker stuck on the view-pick
+        // step with a perpetual spinner. Treat as an empty result and toast
+        // a transport-level message so the user can retry or paste again.
+        setViewList([])
+        toast.error(`Failed to load views: ${err instanceof Error ? err.message : String(err)}`)
+      } finally {
+        setViewLoading(false)
+      }
+    },
+    [commitSelection, projectSettings.lastViewByProject]
+  )
+
+  const handlePaste = useCallback(async () => {
+    const parsed = parseProjectInput(pasteInput.trim())
+    if (!parsed) {
+      setPasteError('Expected a project URL or owner/number')
+      return
+    }
+    setPasteError(null)
+    setPasteBusy(true)
+    try {
+      const res = await window.api.gh.resolveProjectRef({ input: pasteInput.trim() })
+      if (!res.ok) {
+        setPasteError(res.error.message)
+        return
+      }
+      setPasteInput('')
+      await handleChooseProject({
+        owner: res.owner,
+        ownerType: res.ownerType,
+        number: res.number,
+        title: res.title,
+        // Why: forward the parsed view number from /views/{n} URLs so the
+        // chooser can skip the view-pick step and commit directly.
+        ...(res.viewNumber !== undefined ? { viewNumber: res.viewNumber } : {})
+      })
+    } finally {
+      setPasteBusy(false)
+    }
+  }, [handleChooseProject, pasteInput])
+
+  const filteredBrowse = useMemo(() => {
+    const q = query.trim().toLowerCase()
+    const pinnedKeys = new Set(
+      projectSettings.pinned.map((p) => `${p.ownerType}:${p.owner}:${p.number}`)
+    )
+    const recentKeys = new Set(
+      projectSettings.recent.map((r) => `${r.ownerType}:${r.owner}:${r.number}`)
+    )
+    return browseProjects.filter((p) => {
+      const key = `${p.ownerType}:${p.owner}:${p.number}`
+      if (pinnedKeys.has(key) || recentKeys.has(key)) {
+        return false
+      }
+      if (!q) {
+        return true
+      }
+      return (
+        p.title.toLowerCase().includes(q) ||
+        p.owner.toLowerCase().includes(q) ||
+        String(p.number).includes(q)
+      )
+    })
+  }, [browseProjects, projectSettings.pinned, projectSettings.recent, query])
+
+  const buttonLabel = activeProject
+    ? `${activeProject.owner} / ${activeProject.title ?? `#${activeProject.number}`}`
+    : 'Choose a project'
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          size="sm"
+          className="h-8 gap-1 border-border/50 bg-transparent text-xs"
+        >
+          <span className="truncate">{buttonLabel}</span>
+          <ChevronDown className="size-3.5" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[360px] p-0" align="start">
+        {viewPickFor ? (
+          <ViewPickStep
+            loading={viewLoading}
+            views={viewList}
+            onPick={async (view) => {
+              await commitSelection({ ...viewPickFor, viewId: view.id }, null)
+            }}
+            onBack={() => setViewPickFor(null)}
+          />
+        ) : (
+          <div className="flex flex-col">
+            <div className="border-b border-border/50 p-2">
+              <div className="relative">
+                <Search className="pointer-events-none absolute left-2 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+                <Input
+                  value={query}
+                  onChange={(e) => setQuery(e.target.value)}
+                  placeholder="Search projects"
+                  className="h-8 pl-7 text-xs"
+                />
+              </div>
+            </div>
+            {browseError ? <AuthErrorBanner error={browseError} /> : null}
+            {!browseError && partialFailures.length > 0 ? (
+              <PartialFailuresBanner failures={partialFailures} />
+            ) : null}
+            <div className="max-h-[340px] overflow-y-auto p-1">
+              {projectSettings.pinned.length > 0 ? (
+                <Section label="Pinned">
+                  {projectSettings.pinned.map((p) => {
+                    const key = `${p.ownerType}:${p.owner}:${p.number}`
+                    const knownGood = projectSettings.lastViewByProject[key]?.viewId != null
+                    const match = browseProjects.find(
+                      (bp) => `${bp.ownerType}:${bp.owner}:${bp.number}` === key
+                    )
+                    return (
+                      <PickerRow
+                        key={key}
+                        title={match?.title ?? `#${p.number}`}
+                        subtitle={`${p.owner}`}
+                        zombie={!knownGood}
+                        onClick={() =>
+                          handleChooseProject({
+                            owner: p.owner,
+                            ownerType: p.ownerType,
+                            number: p.number,
+                            title: match?.title
+                          })
+                        }
+                        onRemovePin={async () => {
+                          await updateProjectSettings((prev) => ({
+                            ...prev,
+                            pinned: prev.pinned.filter(
+                              (x) => `${x.ownerType}:${x.owner}:${x.number}` !== key
+                            )
+                          }))
+                        }}
+                      />
+                    )
+                  })}
+                </Section>
+              ) : null}
+              {projectSettings.recent.length > 0 ? (
+                <Section label="Recent">
+                  {projectSettings.recent
+                    .filter(
+                      (r) =>
+                        !projectSettings.pinned.some(
+                          (p) =>
+                            p.ownerType === r.ownerType &&
+                            p.owner === r.owner &&
+                            p.number === r.number
+                        )
+                    )
+                    .map((r) => {
+                      const key = `${r.ownerType}:${r.owner}:${r.number}`
+                      const match = browseProjects.find(
+                        (bp) => `${bp.ownerType}:${bp.owner}:${bp.number}` === key
+                      )
+                      const pinnable = projectSettings.lastViewByProject[key]?.viewId != null
+                      return (
+                        <PickerRow
+                          key={key}
+                          title={match?.title ?? `#${r.number}`}
+                          subtitle={r.owner}
+                          canPin={pinnable}
+                          onPin={async () => {
+                            await updateProjectSettings((prev) => ({
+                              ...prev,
+                              pinned: [
+                                ...prev.pinned,
+                                { owner: r.owner, ownerType: r.ownerType, number: r.number }
+                              ].slice(0, 20)
+                            }))
+                          }}
+                          onClick={() =>
+                            handleChooseProject({
+                              owner: r.owner,
+                              ownerType: r.ownerType,
+                              number: r.number,
+                              title: match?.title
+                            })
+                          }
+                        />
+                      )
+                    })}
+                </Section>
+              ) : null}
+              <Section label={browseLoading ? 'Browse all (loading…)' : 'Browse all'}>
+                {browseLoading ? (
+                  <div className="flex items-center gap-2 px-2 py-2 text-xs text-muted-foreground">
+                    <Loader className="size-3 animate-spin" /> Loading…
+                  </div>
+                ) : null}
+                {filteredBrowse.map((p) => (
+                  <PickerRow
+                    key={`${p.ownerType}:${p.owner}:${p.number}`}
+                    title={p.title}
+                    subtitle={p.owner}
+                    onClick={() =>
+                      handleChooseProject({
+                        owner: p.owner,
+                        ownerType: p.ownerType,
+                        number: p.number,
+                        title: p.title
+                      })
+                    }
+                  />
+                ))}
+              </Section>
+            </div>
+            <div className="border-t border-border/50 p-2">
+              <div className="flex gap-2">
+                <Input
+                  value={pasteInput}
+                  onChange={(e) => {
+                    setPasteInput(e.target.value)
+                    setPasteError(null)
+                  }}
+                  onKeyDown={(e) => {
+                    if (e.key === 'Enter') {
+                      void handlePaste()
+                    }
+                  }}
+                  placeholder="Add by URL or owner/number"
+                  className="h-8 text-xs"
+                />
+                <Button
+                  size="sm"
+                  onClick={() => void handlePaste()}
+                  disabled={pasteBusy || !pasteInput.trim()}
+                  className="h-8"
+                >
+                  Add
+                </Button>
+              </div>
+              {pasteError ? (
+                <div className="mt-1 text-[11px] text-destructive">{pasteError}</div>
+              ) : null}
+            </div>
+          </div>
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function Section({
+  label,
+  children
+}: {
+  label: string
+  children: React.ReactNode
+}): React.JSX.Element {
+  return (
+    <div className="py-1">
+      <div className="px-2 pb-0.5 text-[10px] uppercase tracking-wide text-muted-foreground">
+        {label}
+      </div>
+      {children}
+    </div>
+  )
+}
+
+function PickerRow({
+  title,
+  subtitle,
+  onClick,
+  zombie,
+  canPin,
+  onPin,
+  onRemovePin
+}: {
+  title: string
+  subtitle: string
+  onClick: () => void
+  zombie?: boolean
+  canPin?: boolean
+  onPin?: () => void
+  onRemovePin?: () => void
+}): React.JSX.Element {
+  return (
+    <div className="group flex items-center gap-2 rounded px-2 py-1 hover:bg-muted/50">
+      <button type="button" onClick={onClick} className="flex flex-1 min-w-0 flex-col text-left">
+        <span className="truncate text-sm">{title}</span>
+        <span className="truncate text-[10px] text-muted-foreground">{subtitle}</span>
+      </button>
+      {zombie ? (
+        <div className="flex items-center gap-1">
+          <AlertTriangle className="size-3.5 text-amber-500" />
+          <button
+            type="button"
+            className="text-[10px] text-muted-foreground hover:text-foreground"
+            onClick={onRemovePin}
+          >
+            Remove pin
+          </button>
+        </div>
+      ) : null}
+      {canPin ? (
+        <button
+          type="button"
+          title="Pin"
+          className="opacity-0 group-hover:opacity-100"
+          onClick={onPin}
+        >
+          <Pin className="size-3.5" />
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+function ViewPickStep({
+  loading,
+  views,
+  onPick,
+  onBack
+}: {
+  loading: boolean
+  views: GitHubProjectViewSummary[]
+  onPick: (view: GitHubProjectViewSummary) => void | Promise<void>
+  onBack: () => void
+}): React.JSX.Element {
+  return (
+    <div className="flex flex-col">
+      <div className="flex items-center justify-between border-b border-border/50 p-2">
+        <button
+          type="button"
+          onClick={onBack}
+          className="text-xs text-muted-foreground hover:text-foreground"
+        >
+          ← Back
+        </button>
+        <span className="text-xs font-medium">Choose a view</span>
+        <span />
+      </div>
+      <div className="max-h-[340px] overflow-y-auto p-1">
+        {loading ? (
+          <div className="flex items-center gap-2 px-2 py-2 text-xs text-muted-foreground">
+            <Loader className="size-3 animate-spin" /> Loading views…
+          </div>
+        ) : views.length === 0 ? (
+          <div className="px-2 py-2 text-xs text-muted-foreground">No views found.</div>
+        ) : (
+          views.map((v) => {
+            const supported = v.layout === 'TABLE_LAYOUT'
+            return (
+              <button
+                key={v.id}
+                type="button"
+                disabled={!supported}
+                onClick={() => void onPick(v)}
+                className={cn(
+                  'flex w-full flex-col items-start rounded px-2 py-1 text-left',
+                  supported ? 'hover:bg-muted/50' : 'cursor-not-allowed opacity-50'
+                )}
+              >
+                <span className="text-sm">{v.name}</span>
+                <span className="text-[10px] text-muted-foreground">
+                  {v.layout === 'TABLE_LAYOUT'
+                    ? 'Table'
+                    : v.layout === 'BOARD_LAYOUT'
+                      ? 'Board (unsupported)'
+                      : 'Roadmap (unsupported)'}
+                </span>
+              </button>
+            )
+          })
+        )}
+      </div>
+    </div>
+  )
+}
+
+function PartialFailuresBanner({
+  failures
+}: {
+  failures: { owner: string; message: string }[]
+}): React.JSX.Element {
+  // Why: a single generic sentence is preferable to enumerating every failed
+  // owner inline — the list is unbounded and the user only needs to know
+  // (1) their list is incomplete and (2) paste-to-add is the escape hatch.
+  // Hover exposes the underlying error messages for debugging.
+  const summary =
+    failures.length === 1 && failures[0].owner !== '*'
+      ? `Couldn't load projects from ${failures[0].owner}.`
+      : `Some organizations didn't load (${failures.length}).`
+  const detail = failures
+    .map((f) => `${f.owner === '*' ? 'orgs' : f.owner}: ${f.message}`)
+    .join('\n')
+  return (
+    <div
+      className="border-b border-amber-500/30 bg-amber-500/10 px-3 py-2 text-xs text-amber-800 dark:text-amber-200"
+      title={detail}
+    >
+      <div className="flex items-start gap-1.5">
+        <AlertTriangle className="mt-0.5 size-3 shrink-0" />
+        <div>
+          <div>{summary}</div>
+          <div className="mt-0.5 text-[11px] opacity-80">
+            Paste a project URL below to reach missing ones.
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function AuthErrorBanner({ error }: { error: GitHubProjectViewError }): React.JSX.Element {
+  if (error.type === 'auth_required' || error.type === 'scope_missing') {
+    return (
+      <GhAuthErrorHelp
+        error={error as GitHubProjectViewError & { type: 'auth_required' | 'scope_missing' }}
+        variant="banner"
+      />
+    )
+  }
+  // Non-auth errors keep the legacy single-line banner.
+  return (
+    <div className="border-b border-amber-500/30 bg-amber-500/10 px-3 py-2 text-xs text-amber-800 dark:text-amber-200">
+      <div>{error.message}</div>
+    </div>
+  )
+}
+
+function parseProjectInput(
+  input: string
+): { owner: string; number: number; viewNumber?: number } | null {
+  if (!input) {
+    return null
+  }
+  // owner/number
+  const short = /^([A-Za-z0-9][A-Za-z0-9-]*)\/(\d+)$/.exec(input)
+  if (short) {
+    return { owner: short[1], number: Number(short[2]) }
+  }
+  try {
+    const url = new URL(input)
+    if (url.hostname !== 'github.com') {
+      return null
+    }
+    const parts = url.pathname.split('/').filter(Boolean)
+    // /orgs/{owner}/projects/{n} or /users/{owner}/projects/{n}[/views/{viewNumber}]
+    if ((parts[0] === 'orgs' || parts[0] === 'users') && parts[2] === 'projects' && parts[3]) {
+      const owner = parts[1]
+      const number = Number(parts[3])
+      if (Number.isNaN(number)) {
+        return null
+      }
+      let viewNumber: number | undefined
+      if (parts[4] === 'views' && parts[5]) {
+        const v = Number(parts[5])
+        if (!Number.isNaN(v)) {
+          viewNumber = v
+        }
+      }
+      return { owner, number, viewNumber }
+    }
+  } catch {
+    return null
+  }
+  return null
+}
diff --git a/src/renderer/src/components/github-project/ProjectRow.tsx b/src/renderer/src/components/github-project/ProjectRow.tsx
new file mode 100644
index 00000000000..072d8f0b345
--- /dev/null
+++ b/src/renderer/src/components/github-project/ProjectRow.tsx
@@ -0,0 +1,128 @@
+import React from 'react'
+import { ExternalLink, Play } from 'lucide-react'
+import { HoverCard, HoverCardContent, HoverCardTrigger } from '@/components/ui/hover-card'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { cn } from '@/lib/utils'
+import ProjectCell from './ProjectCell'
+import type {
+  GitHubIssueType,
+  GitHubProjectField,
+  GitHubProjectFieldMutationValue,
+  GitHubProjectRow as GitHubProjectRowType
+} from '../../../../shared/github-project-types'
+
+type Props = {
+  row: GitHubProjectRowType
+  fields: GitHubProjectField[]
+  editable: boolean
+  onOpenDialog?: () => void
+  onEditField?: (fieldId: string, value: GitHubProjectFieldMutationValue | null) => void
+  onEditAssignees?: (add: string[], remove: string[]) => void
+  onEditLabels?: (add: string[], remove: string[]) => void
+  onEditIssueType?: (issueType: GitHubIssueType | null) => void
+  onStartWork?: () => void
+  onOpenInBrowser?: () => void
+}
+
+export default function ProjectRow({
+  row,
+  fields,
+  editable,
+  onOpenDialog,
+  onEditField,
+  onEditAssignees,
+  onEditLabels,
+  onEditIssueType,
+  onStartWork,
+  onOpenInBrowser
+}: Props): React.JSX.Element {
+  const disabled = row.itemType === 'REDACTED'
+  // Why: design doc §Row actions — draft-issue rows have no URL or number, so
+  // the title is non-interactive. Surface the draft body in a hover card so
+  // the user can still read context without round-tripping to GitHub.
+  const draftBody =
+    row.itemType === 'DRAFT_ISSUE' && row.content.body && row.content.body.trim().length > 0
+      ? row.content.body
+      : null
+  const rowInner = (
+    <div
+      className={cn(
+        'group grid items-center gap-3 border-b border-border/30 px-3 py-2 hover:bg-muted/30',
+        disabled && 'opacity-60'
+      )}
+      style={{ gridTemplateColumns: buildGridTemplate(fields) }}
+    >
+      {fields.map((f) => (
+        <ProjectCell
+          key={f.id}
+          row={row}
+          field={f}
+          editable={editable}
+          onEditField={onEditField}
+          onEditAssignees={onEditAssignees}
+          onEditLabels={onEditLabels}
+          onEditIssueType={onEditIssueType}
+          onOpenDialog={f.dataType === 'TITLE' ? onOpenDialog : undefined}
+        />
+      ))}
+      <div className="flex items-center justify-end gap-1 opacity-0 transition group-hover:opacity-100">
+        {row.content.url ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                onClick={onOpenInBrowser}
+                aria-label="Open in GitHub"
+                className="rounded p-1 hover:bg-muted"
+              >
+                <ExternalLink className="size-3.5" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>Open in GitHub</TooltipContent>
+          </Tooltip>
+        ) : null}
+        {!disabled && row.itemType !== 'DRAFT_ISSUE' && row.content.number != null ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                onClick={onStartWork}
+                aria-label="Start work"
+                className="rounded p-1 hover:bg-muted"
+              >
+                <Play className="size-3.5" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>Start work</TooltipContent>
+          </Tooltip>
+        ) : null}
+      </div>
+    </div>
+  )
+
+  if (draftBody) {
+    return (
+      <HoverCard openDelay={150}>
+        <HoverCardTrigger asChild>{rowInner}</HoverCardTrigger>
+        <HoverCardContent
+          align="start"
+          sideOffset={4}
+          className="max-h-80 w-96 overflow-y-auto whitespace-pre-wrap text-xs"
+        >
+          {draftBody}
+        </HoverCardContent>
+      </HoverCard>
+    )
+  }
+  return rowInner
+}
+
+export function buildGridTemplate(fields: GitHubProjectField[]): string {
+  // Why: TITLE gets the most space; other columns share equally. The extra
+  // trailing column is for row-hover action icons.
+  const cols: string[] = fields.map((f) =>
+    f.dataType === 'TITLE' ? 'minmax(0,3fr)' : 'minmax(80px,1fr)'
+  )
+  cols.push('80px')
+  return cols.join(' ')
+}
diff --git a/src/renderer/src/components/github-project/ProjectViewList.tsx b/src/renderer/src/components/github-project/ProjectViewList.tsx
new file mode 100644
index 00000000000..8f8392a9f0e
--- /dev/null
+++ b/src/renderer/src/components/github-project/ProjectViewList.tsx
@@ -0,0 +1,284 @@
+import React, { useEffect, useMemo, useState } from 'react'
+import { ArrowDown, ArrowUp, ArrowUpDown, Columns3 } from 'lucide-react'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { cn } from '@/lib/utils'
+import ProjectGroupHeader from './ProjectGroupHeader'
+import ProjectRow, { buildGridTemplate } from './ProjectRow'
+import { groupRows, sortRows } from './group-sort'
+import { getAvailableColumns, loadHiddenColumns, saveHiddenColumns } from './columns'
+import type {
+  GitHubIssueType,
+  GitHubProjectField,
+  GitHubProjectFieldMutationValue,
+  GitHubProjectRow,
+  GitHubProjectSortDirection,
+  GitHubProjectTable
+} from '../../../../shared/github-project-types'
+
+type SortOverride = { fieldId: string; direction: GitHubProjectSortDirection }
+
+type Props = {
+  table: GitHubProjectTable
+  onOpenDialog?: (row: GitHubProjectRow) => void
+  onEditField?: (
+    row: GitHubProjectRow,
+    fieldId: string,
+    value: GitHubProjectFieldMutationValue | null
+  ) => void
+  onEditAssignees?: (row: GitHubProjectRow, add: string[], remove: string[]) => void
+  onEditLabels?: (row: GitHubProjectRow, add: string[], remove: string[]) => void
+  onEditIssueType?: (row: GitHubProjectRow, issueType: GitHubIssueType | null) => void
+  onStartWork?: (row: GitHubProjectRow) => void
+  onOpenInBrowser?: (row: GitHubProjectRow) => void
+}
+
+export default function ProjectViewList({
+  table,
+  onOpenDialog,
+  onEditField,
+  onEditAssignees,
+  onEditLabels,
+  onEditIssueType,
+  onStartWork,
+  onOpenInBrowser
+}: Props): React.JSX.Element {
+  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set())
+  // Why: column-header clicks override the view's saved sortByFields locally
+  // without persisting to GitHub — matches GitHub Projects' transient
+  // header-sort behavior. `null` means "use the view's sort as authored".
+  const [sortOverride, setSortOverride] = useState<SortOverride | null>(null)
+
+  // Why: include project id so the same view id colliding across projects
+  // doesn't cross-pollute hidden-column preferences.
+  const scopeKey = `${table.project.id}:${table.selectedView.id}`
+  const availableFields = useMemo(
+    () => getAvailableColumns(table.selectedView),
+    [table.selectedView]
+  )
+  const [hidden, setHidden] = useState<ReadonlySet<string>>(() => loadHiddenColumns(scopeKey))
+  useEffect(() => {
+    setHidden(loadHiddenColumns(scopeKey))
+  }, [scopeKey])
+  const fields = useMemo(
+    () => availableFields.filter((f) => !hidden.has(f.id)),
+    [availableFields, hidden]
+  )
+
+  const toggleColumn = (fieldId: string): void => {
+    setHidden((prev) => {
+      const next = new Set(prev)
+      if (next.has(fieldId)) {
+        next.delete(fieldId)
+      } else {
+        next.add(fieldId)
+      }
+      saveHiddenColumns(scopeKey, next)
+      return next
+    })
+  }
+
+  const effectiveTable = useMemo<GitHubProjectTable>(() => {
+    if (!sortOverride) {
+      return table
+    }
+    const field = fields.find((f) => f.id === sortOverride.fieldId)
+    if (!field) {
+      return table
+    }
+    return {
+      ...table,
+      selectedView: {
+        ...table.selectedView,
+        sortByFields: [{ field, direction: sortOverride.direction }]
+      }
+    }
+  }, [table, fields, sortOverride])
+
+  const groups = useMemo(() => {
+    // Why: sort first, then group. Sorting the flat stream ensures rows within
+    // each group honor the view's sortByFields too — groupRows preserves input
+    // order within each bucket.
+    const sorted = sortRows(effectiveTable, effectiveTable.rows)
+    return groupRows(effectiveTable, sorted)
+  }, [effectiveTable])
+
+  const handleSortClick = (fieldId: string): void => {
+    setSortOverride((prev) => {
+      if (!prev || prev.fieldId !== fieldId) {
+        return { fieldId, direction: 'ASC' }
+      }
+      if (prev.direction === 'ASC') {
+        return { fieldId, direction: 'DESC' }
+      }
+      return null
+    })
+  }
+
+  if (table.rows.length === 0) {
+    return (
+      <div className="flex min-h-[120px] items-center justify-center p-6 text-sm text-muted-foreground">
+        No items match this view&apos;s filter.
+      </div>
+    )
+  }
+
+  // Why: the visible sort indicator reflects either the local override or the
+  // first persisted sort from the view, so users see what's actually driving
+  // row order.
+  const activeSort: SortOverride | null = sortOverride
+    ? sortOverride
+    : effectiveTable.selectedView.sortByFields[0]
+      ? {
+          fieldId: effectiveTable.selectedView.sortByFields[0].field.id,
+          direction: effectiveTable.selectedView.sortByFields[0].direction
+        }
+      : null
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col overflow-y-auto">
+      <ProjectHeaderRow
+        fields={fields}
+        availableFields={availableFields}
+        hidden={hidden}
+        onToggleColumn={toggleColumn}
+        activeSort={activeSort}
+        onSortClick={handleSortClick}
+      />
+      {groups.map((g) => {
+        const expanded = !collapsed.has(g.key)
+        return (
+          <div key={g.key}>
+            {table.selectedView.groupByFields[0] ? (
+              <ProjectGroupHeader
+                group={g}
+                expanded={expanded}
+                onToggle={() => {
+                  setCollapsed((prev) => {
+                    const next = new Set(prev)
+                    if (next.has(g.key)) {
+                      next.delete(g.key)
+                    } else {
+                      next.add(g.key)
+                    }
+                    return next
+                  })
+                }}
+              />
+            ) : null}
+            {expanded
+              ? g.rows.map((row) => (
+                  <ProjectRow
+                    key={row.id}
+                    row={row}
+                    fields={fields}
+                    editable
+                    onOpenDialog={() => onOpenDialog?.(row)}
+                    onEditField={(fieldId, value) => onEditField?.(row, fieldId, value)}
+                    onEditAssignees={(add, remove) => onEditAssignees?.(row, add, remove)}
+                    onEditLabels={(add, remove) => onEditLabels?.(row, add, remove)}
+                    onEditIssueType={(issueType) => onEditIssueType?.(row, issueType)}
+                    onStartWork={() => onStartWork?.(row)}
+                    onOpenInBrowser={() => onOpenInBrowser?.(row)}
+                  />
+                ))
+              : null}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+function ProjectHeaderRow({
+  fields,
+  availableFields,
+  hidden,
+  onToggleColumn,
+  activeSort,
+  onSortClick
+}: {
+  fields: GitHubProjectField[]
+  availableFields: GitHubProjectField[]
+  hidden: ReadonlySet<string>
+  onToggleColumn: (fieldId: string) => void
+  activeSort: SortOverride | null
+  onSortClick: (fieldId: string) => void
+}): React.JSX.Element {
+  // Why: matches GitHub Projects' fixed column header — sticky so it stays
+  // pinned while scrolling the rows beneath it. The trailing slot mirrors the
+  // hover-action column in ProjectRow so columns line up exactly.
+  return (
+    <div
+      className="sticky top-0 z-10 grid items-center gap-3 border-b border-border/60 bg-background/95 px-3 py-2 text-[11px] font-medium uppercase tracking-wide text-muted-foreground backdrop-blur"
+      style={{ gridTemplateColumns: buildGridTemplate(fields) }}
+    >
+      {fields.map((f) => {
+        const isActive = activeSort?.fieldId === f.id
+        const Icon = isActive ? (activeSort.direction === 'ASC' ? ArrowUp : ArrowDown) : ArrowUpDown
+        return (
+          <button
+            key={f.id}
+            type="button"
+            onClick={() => onSortClick(f.id)}
+            className={cn(
+              'group flex min-w-0 items-center gap-1 truncate text-left uppercase tracking-wide hover:text-foreground',
+              isActive && 'text-foreground'
+            )}
+            aria-label={`Sort by ${f.name}`}
+          >
+            <span className="truncate">{f.name}</span>
+            <Icon
+              className={cn(
+                'size-3 shrink-0 transition-opacity',
+                isActive ? 'opacity-100' : 'opacity-0 group-hover:opacity-60'
+              )}
+            />
+          </button>
+        )
+      })}
+      <div className="flex items-center justify-end">
+        <Popover>
+          <PopoverTrigger asChild>
+            <button
+              type="button"
+              aria-label="Configure columns"
+              className="rounded p-1 text-muted-foreground hover:bg-muted hover:text-foreground"
+            >
+              <Columns3 className="size-3.5" />
+            </button>
+          </PopoverTrigger>
+          <PopoverContent align="end" className="w-56 p-1">
+            <div className="px-2 py-1 text-[10px] uppercase tracking-wide text-muted-foreground">
+              Columns
+            </div>
+            {availableFields.map((f) => {
+              // Why: TITLE is the only column that anchors the row's identity
+              // and click target — disallow hiding it so users can't end up
+              // with a row of metadata they can't open.
+              const locked = f.dataType === 'TITLE'
+              const visible = !hidden.has(f.id)
+              return (
+                <label
+                  key={f.id}
+                  className={cn(
+                    'flex w-full cursor-pointer items-center gap-2 rounded px-2 py-1 text-xs hover:bg-muted/50',
+                    locked && 'cursor-not-allowed opacity-60'
+                  )}
+                >
+                  <input
+                    type="checkbox"
+                    checked={visible}
+                    disabled={locked}
+                    onChange={() => onToggleColumn(f.id)}
+                    className="size-3.5"
+                  />
+                  <span className="truncate">{f.name}</span>
+                </label>
+              )
+            })}
+          </PopoverContent>
+        </Popover>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/github-project/ProjectViewWrapper.tsx b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
new file mode 100644
index 00000000000..41e82db3af3
--- /dev/null
+++ b/src/renderer/src/components/github-project/ProjectViewWrapper.tsx
@@ -0,0 +1,938 @@
+/* eslint-disable max-lines -- Why: top-level Project-mode container coordinates picker, view selection, query overrides, fetch lifecycle, and toolbar interactions; splitting these would fragment shared state. */
+// 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 {
+  ExternalLink,
+  Loader,
+  RefreshCw,
+  KanbanSquare,
+  Map as MapIcon,
+  Search,
+  Table as TableIcon,
+  X
+} from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '@/components/ui/dialog'
+import GitHubItemDialog, { type GitHubItemDialogProjectOrigin } from '@/components/GitHubItemDialog'
+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 { useAppStore } from '@/store'
+import { projectViewCacheKey } from '@/store/slices/github'
+import type {
+  GetProjectViewTableResult,
+  GitHubIssueType,
+  GitHubProjectFieldMutationValue,
+  GitHubProjectRow,
+  GitHubProjectTable,
+  GitHubProjectViewError,
+  GitHubProjectViewSummary
+} from '../../../../shared/github-project-types'
+import type { GitHubWorkItem } from '../../../../shared/types'
+import ProjectPicker, { type ResolvedProjectSelection } from './ProjectPicker'
+import ProjectViewList from './ProjectViewList'
+import ProjectItemSlugDialog from './ProjectItemSlugDialog'
+
+type Props = Record<string, never>
+
+export default function ProjectViewWrapper(_props: Props = {} as Props): React.JSX.Element {
+  const settings = useAppStore((s) => s.settings)
+  const projectViewCache = useAppStore((s) => s.projectViewCache)
+  const fetchProjectViewTable = useAppStore((s) => s.fetchProjectViewTable)
+  const updateProjectFieldValue = useAppStore((s) => s.updateProjectFieldValue)
+  const clearProjectFieldValue = useAppStore((s) => s.clearProjectFieldValue)
+  const patchProjectIssueOrPr = useAppStore((s) => s.patchProjectIssueOrPr)
+  const patchProjectRowIssueType = useAppStore((s) => s.patchProjectRowIssueType)
+  const addRepoFromStore = useAppStore((s) => s.addRepo)
+  const lookupSlug = useRepoSlugIndex()
+
+  const activeProject = settings?.githubProjects?.activeProject ?? null
+  const lastViewByProject = settings?.githubProjects?.lastViewByProject ?? {}
+
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<{
+    error: GitHubProjectViewError
+    totalCount?: number
+  } | null>(null)
+  const [parentDroppedToasted, setParentDroppedToasted] = useState<ReadonlySet<string>>(
+    () => new Set()
+  )
+  // Why: cache the project's view list per active project so the tab strip
+  // renders without flicker on re-renders and survives view switches without
+  // refetching. Keyed by `ownerType:owner:number`.
+  const [viewListByProject, setViewListByProject] = useState<
+    Record<string, GitHubProjectViewSummary[]>
+  >({})
+
+  // Why: ephemeral search override, scoped to (project, view). Mirrors GitHub
+  // Projects' search box — pre-populated from `selectedView.filter`, applied
+  // on Enter/blur, cleared with the X button. The override is NEVER persisted
+  // to settings or to GitHub (per design doc §"Out of scope" line 36); a tab
+  // switch or refresh resets to the view's stored filter. Keyed by
+  // `ownerType:owner:number:viewId`. `undefined` (entry missing) means
+  // "use the view's filter as-is" so the cache key collapses to the
+  // unfiltered cache entry. The transient input string lives inside
+  // `ProjectSearchInput` so typing does not re-render the table.
+  const [appliedQueryByView, setAppliedQueryByView] = useState<Record<string, string>>({})
+
+  const doFetch = useCallback(
+    async (selection: ResolvedProjectSelection, force = false, queryOverride?: string) => {
+      setLoading(true)
+      setError(null)
+      try {
+        const res: GetProjectViewTableResult = await fetchProjectViewTable(
+          {
+            owner: selection.owner,
+            ownerType: selection.ownerType,
+            projectNumber: selection.projectNumber,
+            ...(selection.viewId ? { viewId: selection.viewId } : {}),
+            ...(queryOverride !== undefined ? { queryOverride } : {})
+          },
+          { force }
+        )
+        if (!res.ok) {
+          setError({ error: res.error, totalCount: res.totalCount })
+        }
+      } finally {
+        setLoading(false)
+      }
+    },
+    [fetchProjectViewTable]
+  )
+
+  const handleSelect = useCallback(
+    async (selection: ResolvedProjectSelection) => {
+      await doFetch(selection, true)
+    },
+    [doFetch]
+  )
+
+  // Auto-fetch when activeProject exists and we don't have cached data.
+  useEffect(() => {
+    if (!activeProject) {
+      return
+    }
+    const key = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+    const viewId = lastViewByProject[key]?.viewId
+    if (!viewId) {
+      return
+    }
+    const projectViewKey = `${key}:${viewId}`
+    const queryOverride = appliedQueryByView[projectViewKey]
+    const cacheKey = projectViewCacheKey(
+      activeProject.ownerType,
+      activeProject.owner,
+      activeProject.number,
+      viewId,
+      queryOverride
+    )
+    if (projectViewCache[cacheKey]?.data) {
+      return
+    }
+    void doFetch(
+      {
+        owner: activeProject.owner,
+        ownerType: activeProject.ownerType,
+        projectNumber: activeProject.number,
+        viewId
+      },
+      false,
+      queryOverride
+    )
+  }, [activeProject, lastViewByProject, projectViewCache, doFetch, appliedQueryByView])
+
+  // Load the project's view list whenever the active project changes so the
+  // tab strip can render. The list is small and rarely changes — fetched once
+  // per project per session is fine.
+  useEffect(() => {
+    if (!activeProject) {
+      return
+    }
+    const projectKey = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+    if (viewListByProject[projectKey]) {
+      return
+    }
+    let cancelled = false
+    void window.api.gh
+      .listProjectViews({
+        owner: activeProject.owner,
+        ownerType: activeProject.ownerType,
+        projectNumber: activeProject.number
+      })
+      .then((res) => {
+        if (cancelled) {
+          return
+        }
+        if (res.ok) {
+          setViewListByProject((prev) => ({ ...prev, [projectKey]: res.views }))
+        } else {
+          console.warn('[project-view] listProjectViews failed:', res.error.message)
+        }
+      })
+      .catch((err) => {
+        if (cancelled) {
+          return
+        }
+        // Why: an IPC rejection here would surface as an unhandled rejection
+        // and dev-tools red — log and fall back to the empty-tabs UI.
+        console.warn('[project-view] listProjectViews threw:', err)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [activeProject, viewListByProject])
+
+  const handleSwitchView = useCallback(
+    async (viewId: string) => {
+      if (!activeProject) {
+        return
+      }
+      const projectKey = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+      const current = lastViewByProject[projectKey]?.viewId
+      if (current === viewId) {
+        return
+      }
+      // Persist the new view selection so reloads & the picker stay in sync.
+      // Why: read the freshest settings via getState() rather than the closure-
+      // captured `settings` — between callback creation and invocation another
+      // mutation (pin/recent update from elsewhere) may have landed, and the
+      // closure value would clobber it on write.
+      const freshSettings = useAppStore.getState().settings
+      const prevSettings = freshSettings?.githubProjects ?? {
+        pinned: [],
+        recent: [],
+        lastViewByProject: {},
+        activeProject: null
+      }
+      await useAppStore.getState().updateSettings({
+        githubProjects: {
+          ...prevSettings,
+          lastViewByProject: {
+            ...prevSettings.lastViewByProject,
+            [projectKey]: { viewId }
+          }
+        }
+      })
+      await doFetch({
+        owner: activeProject.owner,
+        ownerType: activeProject.ownerType,
+        projectNumber: activeProject.number,
+        viewId
+      })
+    },
+    [activeProject, doFetch, lastViewByProject, settings]
+  )
+
+  const currentProjectViewKey = useMemo(() => {
+    if (!activeProject) {
+      return null
+    }
+    const key = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+    const viewId = lastViewByProject[key]?.viewId
+    if (!viewId) {
+      return null
+    }
+    return `${key}:${viewId}`
+  }, [activeProject, lastViewByProject])
+
+  const currentAppliedOverride = currentProjectViewKey
+    ? appliedQueryByView[currentProjectViewKey]
+    : undefined
+
+  const currentCacheKey = useMemo(() => {
+    if (!activeProject) {
+      return null
+    }
+    const key = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+    const viewId = lastViewByProject[key]?.viewId
+    if (!viewId) {
+      return null
+    }
+    return projectViewCacheKey(
+      activeProject.ownerType,
+      activeProject.owner,
+      activeProject.number,
+      viewId,
+      currentAppliedOverride
+    )
+  }, [activeProject, lastViewByProject, currentAppliedOverride])
+
+  const table: GitHubProjectTable | null = currentCacheKey
+    ? (projectViewCache[currentCacheKey]?.data ?? null)
+    : null
+
+  // Parent-dropped toast, once per table.
+  useEffect(() => {
+    if (!table || !currentCacheKey || !table.parentFieldDropped) {
+      return
+    }
+    if (parentDroppedToasted.has(currentCacheKey)) {
+      return
+    }
+    toast.message('Sub-issue data is unavailable for your token.')
+    setParentDroppedToasted((prev) => {
+      const next = new Set(prev)
+      next.add(currentCacheKey)
+      return next
+    })
+  }, [table, currentCacheKey, parentDroppedToasted])
+
+  const selectedViewUrl = table
+    ? `${table.project.url}/views/${table.selectedView.number ?? ''}`
+    : null
+
+  // ── Row action state ────────────────────────────────────────────────
+  // Why: when a row matches a registered repo, we open the full
+  // `GitHubItemDialog` in repo-backed mode; when it doesn't, we open the
+  // simplified slug-mode dialog. `repoNotInOrca` drives the fallback modal
+  // from the design doc's `repo-not-in-orca` interaction state.
+  const [dialogRepoItem, setDialogRepoItem] = useState<{
+    workItem: GitHubWorkItem
+    repoPath: string
+    origin: GitHubItemDialogProjectOrigin
+  } | null>(null)
+  // Why: the slug dialog is only opened for rows whose repo isn't registered
+  // in Orca (matched repos go through the full GitHubItemDialog above), so
+  // there's no `matchedRepo` to track here. The repo-not-in-orca modal —
+  // owned by this parent, not the slug dialog — handles "Start work".
+  const [slugDialog, setSlugDialog] = useState<{
+    origin: GitHubItemDialogProjectOrigin
+  } | null>(null)
+  const [repoNotInOrca, setRepoNotInOrca] = useState<{
+    owner: string
+    repo: string
+    url: string | null
+  } | null>(null)
+
+  const buildWorkItem = useCallback(
+    (row: GitHubProjectRow, repoId: string): GitHubWorkItem | null => {
+      if (row.itemType !== 'ISSUE' && row.itemType !== 'PULL_REQUEST') {
+        return null
+      }
+      if (row.content.number == null || !row.content.url) {
+        return null
+      }
+      return {
+        id: `${row.itemType === 'PULL_REQUEST' ? 'pr' : 'issue'}:${row.content.number}`,
+        type: row.itemType === 'PULL_REQUEST' ? 'pr' : 'issue',
+        number: row.content.number,
+        title: row.content.title,
+        state:
+          row.content.state === 'MERGED'
+            ? 'merged'
+            : row.content.state === 'CLOSED'
+              ? 'closed'
+              : row.content.isDraft
+                ? 'draft'
+                : 'open',
+        url: row.content.url,
+        labels: row.content.labels.map((l) => l.name),
+        updatedAt: row.updatedAt,
+        author: null,
+        repoId
+      }
+    },
+    []
+  )
+
+  const buildOrigin = useCallback(
+    (
+      row: GitHubProjectRow,
+      cacheKey: string,
+      table: GitHubProjectTable
+    ): GitHubItemDialogProjectOrigin | null => {
+      if (row.itemType !== 'ISSUE' && row.itemType !== 'PULL_REQUEST') {
+        return null
+      }
+      if (row.content.number == null || !row.content.repository) {
+        return null
+      }
+      const [owner, repo] = row.content.repository.split('/')
+      if (!owner || !repo) {
+        return null
+      }
+      return {
+        owner,
+        repo,
+        number: row.content.number,
+        type: row.itemType === 'PULL_REQUEST' ? 'pr' : 'issue',
+        projectId: table.project.id,
+        projectItemId: row.id,
+        cacheKey
+      }
+    },
+    []
+  )
+
+  const handleOpenDialog = useCallback(
+    (row: GitHubProjectRow) => {
+      if (!currentCacheKey || !table) {
+        return
+      }
+      const origin = buildOrigin(row, currentCacheKey, table)
+      if (!origin) {
+        // Redacted / draft / missing slug — fall back to opening GitHub.
+        if (row.content.url) {
+          void window.api.shell.openUrl(row.content.url)
+        }
+        return
+      }
+      const matched = lookupSlug(`${origin.owner}/${origin.repo}`)
+      if (matched) {
+        const workItem = buildWorkItem(row, matched.id)
+        if (workItem) {
+          setDialogRepoItem({ workItem, repoPath: matched.path, origin })
+          return
+        }
+      }
+      // Unknown repo — use the simplified slug-mode dialog.
+      setSlugDialog({ origin })
+    },
+    [currentCacheKey, table, buildOrigin, lookupSlug, buildWorkItem]
+  )
+
+  const handleStartWork = useCallback(
+    (row: GitHubProjectRow) => {
+      if (!currentCacheKey || !table) {
+        return
+      }
+      const origin = buildOrigin(row, currentCacheKey, table)
+      if (!origin) {
+        return
+      }
+      const matched = lookupSlug(`${origin.owner}/${origin.repo}`)
+      if (!matched) {
+        setRepoNotInOrca({
+          owner: origin.owner,
+          repo: origin.repo,
+          url: row.content.url ?? null
+        })
+        return
+      }
+      const workItem = buildWorkItem(row, matched.id)
+      if (!workItem) {
+        return
+      }
+      void launchWorkItemDirect({
+        item: workItem,
+        repoId: matched.id,
+        launchSource: 'task_page',
+        telemetrySource: 'sidebar',
+        openModalFallback: () => {
+          // Why: Project mode does not own the new-workspace composer modal.
+          // When `launchWorkItemDirect` wants user input (setupRunPolicy:'ask'
+          // or agent detection fails), fall back to opening the URL so the
+          // user keeps a path forward rather than a silent no-op.
+          if (row.content.url) {
+            void window.api.shell.openUrl(row.content.url)
+          }
+        }
+      })
+    },
+    [currentCacheKey, table, buildOrigin, lookupSlug, buildWorkItem]
+  )
+
+  const handleEditAssignees = useCallback(
+    async (row: GitHubProjectRow, add: string[], remove: string[]) => {
+      if (!currentCacheKey) {
+        return
+      }
+      const res = await patchProjectIssueOrPr(currentCacheKey, row.id, {
+        ...(add.length ? { addAssignees: add } : {}),
+        ...(remove.length ? { removeAssignees: remove } : {})
+      })
+      if (!res.ok) {
+        toast.error(res.error.message)
+      }
+    },
+    [currentCacheKey, patchProjectIssueOrPr]
+  )
+
+  const handleEditLabels = useCallback(
+    async (row: GitHubProjectRow, add: string[], remove: string[]) => {
+      if (!currentCacheKey) {
+        return
+      }
+      const res = await patchProjectIssueOrPr(currentCacheKey, row.id, {
+        ...(add.length ? { addLabels: add } : {}),
+        ...(remove.length ? { removeLabels: remove } : {})
+      })
+      if (!res.ok) {
+        toast.error(res.error.message)
+      }
+    },
+    [currentCacheKey, patchProjectIssueOrPr]
+  )
+
+  const handleEditIssueType = useCallback(
+    async (row: GitHubProjectRow, issueType: GitHubIssueType | null) => {
+      if (!currentCacheKey) {
+        return
+      }
+      const res = await patchProjectRowIssueType(currentCacheKey, row.id, issueType)
+      if (!res.ok) {
+        toast.error(res.error.message)
+      }
+    },
+    [currentCacheKey, patchProjectRowIssueType]
+  )
+
+  const handleEditField = useCallback(
+    async (
+      row: GitHubProjectRow,
+      fieldId: string,
+      value: GitHubProjectFieldMutationValue | null
+    ) => {
+      if (!currentCacheKey) {
+        return
+      }
+      const result =
+        value === null
+          ? await clearProjectFieldValue(currentCacheKey, row.id, fieldId)
+          : await updateProjectFieldValue(currentCacheKey, row.id, fieldId, value)
+      if (!result.ok) {
+        toast.error(result.error.message)
+      }
+    },
+    [clearProjectFieldValue, currentCacheKey, updateProjectFieldValue]
+  )
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div className="flex flex-none items-center gap-2 border-b border-border/50 bg-muted/30 px-3 py-2">
+        <ProjectPicker
+          activeProject={
+            activeProject && table
+              ? {
+                  owner: activeProject.owner,
+                  ownerType: activeProject.ownerType,
+                  number: activeProject.number,
+                  title: table.project.title
+                }
+              : activeProject
+                ? {
+                    owner: activeProject.owner,
+                    ownerType: activeProject.ownerType,
+                    number: activeProject.number
+                  }
+                : null
+          }
+          onSelect={handleSelect}
+        />
+        {currentProjectViewKey ? (
+          // Why: render the search input whenever a view is selected — even
+          // while a refetch is in flight and `table` has briefly cleared for
+          // the new cache key. Hiding the search box mid-search would make
+          // it look like the search vanished. `key` keeps the local input
+          // state stable across (project, view) changes only.
+          <ProjectSearchInput
+            key={currentProjectViewKey}
+            viewFilter={table?.selectedView.filter ?? ''}
+            appliedOverride={appliedQueryByView[currentProjectViewKey]}
+            onApply={(nextOverride) => {
+              if (!activeProject) {
+                return
+              }
+              const key = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+              const viewId = lastViewByProject[key]?.viewId
+              if (!viewId) {
+                return
+              }
+              setAppliedQueryByView((prev) => {
+                const next = { ...prev }
+                if (nextOverride === undefined) {
+                  delete next[currentProjectViewKey]
+                } else {
+                  next[currentProjectViewKey] = nextOverride
+                }
+                return next
+              })
+              // Why: force-fetch on user-initiated apply so the same
+              // query re-typed (or cache-stale entries within TTL) does
+              // not silently no-op.
+              void doFetch(
+                {
+                  owner: activeProject.owner,
+                  ownerType: activeProject.ownerType,
+                  projectNumber: activeProject.number,
+                  viewId
+                },
+                true,
+                nextOverride
+              )
+            }}
+          />
+        ) : null}
+        {table ? (
+          <>
+            <span className="ml-auto rounded-full border border-border/50 bg-background px-2 py-0.5 text-[11px]">
+              {table.totalCount}
+            </span>
+            {selectedViewUrl ? (
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-7 w-7"
+                onClick={() => void window.api.shell.openUrl(selectedViewUrl)}
+                aria-label="Open view in GitHub"
+              >
+                <ExternalLink className="size-3.5" />
+              </Button>
+            ) : null}
+            <Button
+              variant="outline"
+              size="icon"
+              className="h-7 w-7"
+              onClick={() => {
+                if (!activeProject || !currentCacheKey) {
+                  return
+                }
+                const key = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+                const viewId = lastViewByProject[key]?.viewId
+                if (!viewId) {
+                  return
+                }
+                void doFetch(
+                  {
+                    owner: activeProject.owner,
+                    ownerType: activeProject.ownerType,
+                    projectNumber: activeProject.number,
+                    viewId
+                  },
+                  true,
+                  currentAppliedOverride
+                )
+              }}
+              aria-label="Refresh"
+            >
+              <RefreshCw className={cn('size-3.5', loading && 'animate-spin')} />
+            </Button>
+          </>
+        ) : null}
+      </div>
+
+      {activeProject
+        ? (() => {
+            const projectKey = `${activeProject.ownerType}:${activeProject.owner}:${activeProject.number}`
+            const views = viewListByProject[projectKey] ?? []
+            if (views.length === 0) {
+              return null
+            }
+            const activeViewId = lastViewByProject[projectKey]?.viewId ?? null
+            return (
+              <ViewTabStrip
+                views={views}
+                activeViewId={activeViewId}
+                onPick={(viewId) => void handleSwitchView(viewId)}
+              />
+            )
+          })()
+        : null}
+
+      {!activeProject ? (
+        <div className="flex flex-1 items-center justify-center p-8 text-sm text-muted-foreground">
+          Choose a project to get started.
+        </div>
+      ) : loading && !table ? (
+        <div className="flex flex-1 items-center justify-center p-8 text-sm text-muted-foreground">
+          <Loader className="mr-2 size-4 animate-spin" />
+          Loading project view…
+        </div>
+      ) : error ? (
+        <ErrorState
+          error={error.error}
+          totalCount={error.totalCount}
+          onOpenInGitHub={() => {
+            if (selectedViewUrl) {
+              void window.api.shell.openUrl(selectedViewUrl)
+            }
+          }}
+        />
+      ) : table ? (
+        <ProjectViewList
+          table={table}
+          onOpenDialog={handleOpenDialog}
+          onEditField={handleEditField}
+          onEditAssignees={(row, add, remove) => void handleEditAssignees(row, add, remove)}
+          onEditLabels={(row, add, remove) => void handleEditLabels(row, add, remove)}
+          onEditIssueType={(row, issueType) => void handleEditIssueType(row, issueType)}
+          onOpenInBrowser={(row) => {
+            if (row.content.url) {
+              void window.api.shell.openUrl(row.content.url)
+            }
+          }}
+          onStartWork={handleStartWork}
+        />
+      ) : null}
+
+      {/* Full repo-backed dialog — writes still go through slug-addressed
+          mutation helpers (see design §Dialog editing from Project rows, line
+          707) so a row from another repo cannot accidentally edit the active
+          workspace. */}
+      <GitHubItemDialog
+        workItem={dialogRepoItem?.workItem ?? null}
+        repoPath={dialogRepoItem?.repoPath ?? null}
+        projectOrigin={dialogRepoItem?.origin}
+        onUse={(item) => {
+          const current = dialogRepoItem
+          setDialogRepoItem(null)
+          if (!current) {
+            return
+          }
+          void launchWorkItemDirect({
+            item,
+            repoId: current.workItem.repoId,
+            launchSource: 'task_page',
+            telemetrySource: 'sidebar',
+            openModalFallback: () => {
+              if (item.url) {
+                void window.api.shell.openUrl(item.url)
+              }
+            }
+          })
+        }}
+        onClose={() => setDialogRepoItem(null)}
+      />
+
+      {/* Slug-only simplified dialog for rows whose repo isn't added to Orca.
+          Why: no Start-work affordance lives inside the slug dialog — the
+          parent's `handleStartWork`/`repoNotInOrca` modal owns that flow, so
+          having a duplicate (always-disabled or always-routing-to-fallback)
+          button here would only confuse the user. */}
+      <ProjectItemSlugDialog
+        projectOrigin={slugDialog?.origin ?? null}
+        onClose={() => setSlugDialog(null)}
+      />
+
+      {/* repo-not-in-orca prompt: see design doc Interaction States. */}
+      <Dialog
+        open={repoNotInOrca !== null}
+        onOpenChange={(open) => !open && setRepoNotInOrca(null)}
+      >
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Repository not in Orca</DialogTitle>
+            <DialogDescription>
+              {repoNotInOrca
+                ? `${repoNotInOrca.owner}/${repoNotInOrca.repo} isn't added to Orca. Add it to start work, or open in GitHub.`
+                : null}
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter className="gap-2 sm:justify-end">
+            <Button variant="ghost" onClick={() => setRepoNotInOrca(null)}>
+              Cancel
+            </Button>
+            {repoNotInOrca?.url ? (
+              <Button
+                variant="outline"
+                onClick={() => {
+                  if (repoNotInOrca.url) {
+                    void window.api.shell.openUrl(repoNotInOrca.url)
+                  }
+                  setRepoNotInOrca(null)
+                }}
+              >
+                Open in GitHub
+              </Button>
+            ) : null}
+            <Button
+              onClick={async () => {
+                // Why: `addRepo` opens the OS folder picker — it's the only
+                // non-destructive way to register a repo today. Auto-cloning
+                // from a row click is out of v1 scope (design doc §Row
+                // actions). Close the modal regardless so the user isn't
+                // trapped if they cancel the picker.
+                setRepoNotInOrca(null)
+                await addRepoFromStore()
+              }}
+            >
+              Add repo
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  )
+}
+
+// Why: owns the transient search input string locally so typing does not
+// re-render the parent (and therefore not the table). The parent only learns
+// the value when the user applies it (Enter/blur/clear), which is the only
+// moment that should trigger a refetch. Pre-populated from the view's stored
+// filter and remounted (via `key`) when the active project/view changes.
+function ProjectSearchInput({
+  viewFilter,
+  appliedOverride,
+  onApply
+}: {
+  viewFilter: string
+  appliedOverride: string | undefined
+  onApply: (nextOverride: string | undefined) => void
+}): React.JSX.Element {
+  const initial = appliedOverride !== undefined ? appliedOverride : viewFilter
+  const [value, setValue] = useState<string>(initial)
+  const applied = appliedOverride !== undefined ? appliedOverride : viewFilter
+  const dirty = value !== applied
+
+  const apply = (next: string): void => {
+    // Why: when the user reverts to the view's stored filter, drop the
+    // override so the cache key collapses back onto the unfiltered entry.
+    onApply(next === viewFilter ? undefined : next)
+  }
+
+  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
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') {
+            e.preventDefault()
+            apply(value)
+          } else if (e.key === 'Escape') {
+            setValue(applied)
+            ;(e.target as HTMLInputElement).blur()
+          }
+        }}
+        onBlur={() => {
+          if (dirty) {
+            apply(value)
+          }
+        }}
+        placeholder={viewFilter || 'GitHub search, e.g. assignee:@me is:open'}
+        title={viewFilter ? `View filter: ${viewFilter}` : undefined}
+        className={cn(
+          'h-7 rounded-md border-border/50 bg-background pl-8 pr-7 text-[11px]',
+          dirty && 'border-amber-500/50'
+        )}
+      />
+      {value && value !== viewFilter ? (
+        <button
+          type="button"
+          aria-label="Reset to view filter"
+          onClick={() => {
+            setValue(viewFilter)
+            apply(viewFilter)
+          }}
+          className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground transition hover:text-foreground"
+        >
+          <X className="size-3.5" />
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+function ViewTabStrip({
+  views,
+  activeViewId,
+  onPick
+}: {
+  views: GitHubProjectViewSummary[]
+  activeViewId: string | null
+  onPick: (viewId: string) => void
+}): React.JSX.Element {
+  // Why: emulate GitHub Projects' tab strip — pill-shaped active tab with
+  // layout icon, sitting on a muted base bar with a bottom border. Inactive
+  // tabs are flat text; active gets a card background + outline. Disabled
+  // (non-table) layouts stay visible at low opacity.
+  return (
+    <div className="flex flex-none items-end gap-1 overflow-x-auto border-b border-border/50 bg-muted/20 px-3 pt-3">
+      {views.map((v) => {
+        const supported = v.layout === 'TABLE_LAYOUT'
+        const active = v.id === activeViewId
+        const Icon =
+          v.layout === 'BOARD_LAYOUT'
+            ? KanbanSquare
+            : v.layout === 'ROADMAP_LAYOUT'
+              ? MapIcon
+              : TableIcon
+        return (
+          <button
+            key={v.id}
+            type="button"
+            disabled={!supported}
+            onClick={() => onPick(v.id)}
+            title={
+              supported
+                ? v.name
+                : `${v.name} — ${
+                    v.layout === 'BOARD_LAYOUT' ? 'Board' : 'Roadmap'
+                  } layouts aren't supported in Orca yet. Open this view on GitHub to see it, or switch to a Table view to work with it here.`
+            }
+            className={cn(
+              'inline-flex shrink-0 items-center gap-1.5 rounded-t-md border-x border-t px-3 py-1.5 text-xs',
+              active
+                ? '-mb-px border-border/60 bg-background text-foreground'
+                : 'border-transparent text-muted-foreground hover:bg-background/40 hover:text-foreground',
+              !supported &&
+                'cursor-not-allowed opacity-50 hover:bg-transparent hover:text-muted-foreground'
+            )}
+          >
+            <Icon className="size-3.5 shrink-0 text-muted-foreground" />
+            <span className={cn(active && 'font-medium')}>{v.name}</span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+function ErrorState({
+  error,
+  totalCount,
+  onOpenInGitHub
+}: {
+  error: GitHubProjectViewError
+  totalCount?: number
+  onOpenInGitHub: () => void
+}): React.JSX.Element {
+  // Auth/scope errors get a richer remediation UI driven by `gh auth
+  // status`. Bail early so the generic `command`/`copy` block below is
+  // only computed for non-auth error types.
+  if (error.type === 'auth_required' || error.type === 'scope_missing') {
+    return (
+      <div className="flex flex-1 flex-col items-start gap-3 p-6 text-sm">
+        <GhAuthErrorHelp
+          error={error as GitHubProjectViewError & { type: 'auth_required' | 'scope_missing' }}
+        />
+        <Button size="sm" variant="outline" onClick={onOpenInGitHub}>
+          <ExternalLink className="mr-1 size-3.5" /> Open in GitHub
+        </Button>
+      </div>
+    )
+  }
+  const copy =
+    error.type === 'too_large'
+      ? `This view has ${totalCount ?? 'many'} items — too large to render in Orca. Narrow the view's filter on GitHub.`
+      : error.type === 'unsupported_layout'
+        ? 'Orca only renders table views yet. This is a Board or Roadmap view.'
+        : error.type === 'not_found'
+          ? 'Could not find this project or view.'
+          : error.type === 'schema_drift'
+            ? 'Could not read this project view.'
+            : error.message
+  return (
+    <div className="flex flex-1 flex-col items-start gap-3 p-6 text-sm">
+      <div className="text-muted-foreground">{copy}</div>
+      <div className="flex gap-2">
+        <Button size="sm" variant="outline" onClick={onOpenInGitHub}>
+          <ExternalLink className="mr-1 size-3.5" /> Open in GitHub
+        </Button>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/github-project/columns.ts b/src/renderer/src/components/github-project/columns.ts
new file mode 100644
index 00000000000..9e3684b5bfe
--- /dev/null
+++ b/src/renderer/src/components/github-project/columns.ts
@@ -0,0 +1,68 @@
+// Why: column visibility is a renderer-only preference — GitHub's view
+// definition is the source of truth for which fields exist, and we layer a
+// local visibility filter on top. Persisted in localStorage (not settings)
+// because it's purely cosmetic per device and would otherwise bloat the
+// debounced settings write on every checkbox toggle.
+import type { GitHubProjectField, GitHubProjectView } from '../../../../shared/github-project-types'
+
+export const TYPE_FIELD_ID = '__type__'
+export const TYPE_FIELD_DATA_TYPE = '__TYPE__'
+
+// Why: synthetic "Type" column derives from row.itemType — there is no
+// matching ProjectV2 field, so we inject it client-side. Inserted right
+// after TITLE so users see issue/PR/draft glyphs adjacent to the title.
+export const TYPE_FIELD: GitHubProjectField = {
+  kind: 'field',
+  id: TYPE_FIELD_ID,
+  name: 'Type',
+  dataType: TYPE_FIELD_DATA_TYPE
+}
+
+export function getAvailableColumns(view: GitHubProjectView): GitHubProjectField[] {
+  const fields = view.fields
+  const titleIdx = fields.findIndex((f) => f.dataType === 'TITLE')
+  if (titleIdx === -1) {
+    return [TYPE_FIELD, ...fields]
+  }
+  return [...fields.slice(0, titleIdx + 1), TYPE_FIELD, ...fields.slice(titleIdx + 1)]
+}
+
+const STORAGE_KEY = 'orca.githubProject.hiddenColumns'
+
+type HiddenMap = Record<string, string[]>
+
+function readMap(): HiddenMap {
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY)
+    if (!raw) {
+      return {}
+    }
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? (parsed as HiddenMap) : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeMap(map: HiddenMap): void {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(map))
+  } catch {
+    // localStorage may be disabled — visibility just won't persist this session.
+  }
+}
+
+export function loadHiddenColumns(scopeKey: string): ReadonlySet<string> {
+  const map = readMap()
+  return new Set(map[scopeKey] ?? [])
+}
+
+export function saveHiddenColumns(scopeKey: string, hidden: ReadonlySet<string>): void {
+  const map = readMap()
+  if (hidden.size === 0) {
+    delete map[scopeKey]
+  } else {
+    map[scopeKey] = Array.from(hidden)
+  }
+  writeMap(map)
+}
diff --git a/src/renderer/src/components/github-project/group-sort.test.ts b/src/renderer/src/components/github-project/group-sort.test.ts
new file mode 100644
index 00000000000..ef1059bff64
--- /dev/null
+++ b/src/renderer/src/components/github-project/group-sort.test.ts
@@ -0,0 +1,231 @@
+// Why: cover the bug fixes from the recent review — particularly the NaN
+// sort produced when two rows reference unknown single-select option IDs or
+// unknown iteration IDs, and the empty-group ordering invariant.
+import { describe, expect, it } from 'vitest'
+import type {
+  GitHubProjectField,
+  GitHubProjectRow,
+  GitHubProjectSort,
+  GitHubProjectTable,
+  GitHubProjectView
+} from '../../../../shared/github-project-types'
+import { sortRows, groupRows } from './group-sort'
+
+const singleSelectField: GitHubProjectField = {
+  kind: 'single-select',
+  id: 'F_status',
+  name: 'Status',
+  dataType: 'SINGLE_SELECT',
+  options: [
+    { id: 'opt_a', name: 'Todo', color: 'GRAY' },
+    { id: 'opt_b', name: 'In Progress', color: 'YELLOW' }
+  ]
+}
+
+const iterationField: GitHubProjectField = {
+  kind: 'iteration',
+  id: 'F_iter',
+  name: 'Iteration',
+  dataType: 'ITERATION',
+  iterations: [
+    { id: 'iter_1', title: 'Sprint 1', startDate: '2026-01-01', duration: 14, completed: false },
+    { id: 'iter_2', title: 'Sprint 2', startDate: '2026-01-15', duration: 14, completed: false }
+  ]
+}
+
+function makeRow(
+  id: string,
+  position: number,
+  values: GitHubProjectRow['fieldValuesByFieldId']
+): GitHubProjectRow {
+  return {
+    id,
+    itemType: 'ISSUE',
+    content: {
+      number: 1,
+      title: id,
+      body: null,
+      url: null,
+      state: 'open',
+      stateReason: null,
+      isDraft: null,
+      repository: 'acme/repo',
+      assignees: [],
+      labels: [],
+      parentIssue: null,
+      issueType: null
+    },
+    fieldValuesByFieldId: values,
+    updatedAt: '2026-01-01T00:00:00Z',
+    position
+  }
+}
+
+function makeView(field: GitHubProjectField, sort?: GitHubProjectSort): GitHubProjectView {
+  return {
+    id: 'V_1',
+    number: 1,
+    name: 'Default',
+    layout: 'TABLE_LAYOUT',
+    filter: '',
+    fields: [field],
+    groupByFields: [],
+    sortByFields: sort ? [sort] : []
+  }
+}
+
+function makeTable(view: GitHubProjectView, rows: GitHubProjectRow[]): GitHubProjectTable {
+  return {
+    project: {
+      id: 'P',
+      owner: 'acme',
+      ownerType: 'organization',
+      number: 1,
+      title: 'P',
+      url: ''
+    },
+    selectedView: view,
+    rows,
+    totalCount: rows.length,
+    parentFieldDropped: false
+  }
+}
+
+describe('sortRows', () => {
+  it('orders rows by single-select option order', () => {
+    const view = makeView(singleSelectField, {
+      direction: 'ASC',
+      field: singleSelectField
+    })
+    const rows = [
+      makeRow('r2', 1, {
+        F_status: {
+          kind: 'single-select',
+          fieldId: 'F_status',
+          optionId: 'opt_b',
+          name: 'In Progress',
+          color: 'YELLOW'
+        }
+      }),
+      makeRow('r1', 0, {
+        F_status: {
+          kind: 'single-select',
+          fieldId: 'F_status',
+          optionId: 'opt_a',
+          name: 'Todo',
+          color: 'GRAY'
+        }
+      })
+    ]
+    const sorted = sortRows(makeTable(view, rows), rows)
+    expect(sorted.map((r) => r.id)).toEqual(['r1', 'r2'])
+  })
+
+  it('does not produce NaN when both rows reference unknown single-select options', () => {
+    // Why: this was the bug — `Infinity - Infinity = NaN` made sort()'s
+    // behavior implementation-defined and skipped the row.position
+    // tie-break. Two orphaned rows must still fall through to position.
+    const view = makeView(singleSelectField, {
+      direction: 'ASC',
+      field: singleSelectField
+    })
+    const rows = [
+      makeRow('rB', 5, {
+        F_status: {
+          kind: 'single-select',
+          fieldId: 'F_status',
+          optionId: 'orphan_2',
+          name: 'Gone',
+          color: 'GRAY'
+        }
+      }),
+      makeRow('rA', 1, {
+        F_status: {
+          kind: 'single-select',
+          fieldId: 'F_status',
+          optionId: 'orphan_1',
+          name: 'Gone',
+          color: 'GRAY'
+        }
+      })
+    ]
+    const sorted = sortRows(makeTable(view, rows), rows)
+    // After tie-break by position, rA (position=1) precedes rB (position=5).
+    expect(sorted.map((r) => r.id)).toEqual(['rA', 'rB'])
+  })
+
+  it('does not produce NaN when both rows reference unknown iteration ids', () => {
+    const view = makeView(iterationField, {
+      direction: 'ASC',
+      field: iterationField
+    })
+    const rows = [
+      makeRow('rB', 5, {
+        F_iter: {
+          kind: 'iteration',
+          fieldId: 'F_iter',
+          iterationId: 'gone_b',
+          title: 'Gone B',
+          startDate: '2025-01-01',
+          duration: 14
+        }
+      }),
+      makeRow('rA', 1, {
+        F_iter: {
+          kind: 'iteration',
+          fieldId: 'F_iter',
+          iterationId: 'gone_a',
+          title: 'Gone A',
+          startDate: '2025-01-01',
+          duration: 14
+        }
+      })
+    ]
+    const sorted = sortRows(makeTable(view, rows), rows)
+    expect(sorted.map((r) => r.id)).toEqual(['rA', 'rB'])
+  })
+
+  it('places rows missing the sort field after rows that have it', () => {
+    const view = makeView(singleSelectField, {
+      direction: 'ASC',
+      field: singleSelectField
+    })
+    const rows = [
+      makeRow('rEmpty', 0, {}),
+      makeRow('rHas', 1, {
+        F_status: {
+          kind: 'single-select',
+          fieldId: 'F_status',
+          optionId: 'opt_a',
+          name: 'Todo',
+          color: 'GRAY'
+        }
+      })
+    ]
+    const sorted = sortRows(makeTable(view, rows), rows)
+    expect(sorted.map((r) => r.id)).toEqual(['rHas', 'rEmpty'])
+  })
+})
+
+describe('groupRows', () => {
+  it('places the empty group last', () => {
+    const view = {
+      ...makeView(singleSelectField),
+      groupByFields: [singleSelectField]
+    }
+    const rows = [
+      makeRow('rNone', 0, {}),
+      makeRow('rA', 1, {
+        F_status: {
+          kind: 'single-select',
+          fieldId: 'F_status',
+          optionId: 'opt_a',
+          name: 'Todo',
+          color: 'GRAY'
+        }
+      })
+    ]
+    const groups = groupRows(makeTable(view, rows), rows)
+    expect(groups.map((g) => g.key)).toEqual(['opt_a', '__empty__'])
+  })
+})
diff --git a/src/renderer/src/components/github-project/group-sort.ts b/src/renderer/src/components/github-project/group-sort.ts
new file mode 100644
index 00000000000..0a3b5137a61
--- /dev/null
+++ b/src/renderer/src/components/github-project/group-sort.ts
@@ -0,0 +1,247 @@
+// Why: grouping and sorting of Project rows is deterministic shared logic
+// driven by `selectedView` — it must not depend on fetch ordering. Keeping it
+// in a pure module makes the comparator easily fixture-testable.
+import type {
+  GitHubProjectField,
+  GitHubProjectRow,
+  GitHubProjectSort,
+  GitHubProjectTable
+} from '../../../../shared/github-project-types'
+
+export type ProjectGroup = {
+  /** Stable key used for React reconciliation. */
+  key: string
+  /** Human-readable label used in the group header. */
+  label: string
+  /** Iteration metadata for headers that render a date range + Current pill. */
+  iteration: {
+    startDate: string
+    duration: number
+    completed: boolean
+  } | null
+  rows: GitHubProjectRow[]
+}
+
+const EMPTY_GROUP_KEY = '__empty__'
+
+// Why: use a finite sentinel instead of Infinity so subtractions in the sort
+// comparator stay finite. `Infinity - Infinity` is NaN, which makes
+// Array.sort's behavior implementation-defined and skips later tie-breaks.
+const UNKNOWN_INDEX_SENTINEL = Number.MAX_SAFE_INTEGER
+
+function getFieldValueForGrouping(
+  row: GitHubProjectRow,
+  field: GitHubProjectField
+): { key: string; label: string; orderHint: number; iteration: ProjectGroup['iteration'] } {
+  const value = row.fieldValuesByFieldId[field.id]
+  if (!value) {
+    return {
+      key: EMPTY_GROUP_KEY,
+      label: labelForEmpty(field),
+      orderHint: UNKNOWN_INDEX_SENTINEL,
+      iteration: null
+    }
+  }
+  if (field.kind === 'iteration' && value.kind === 'iteration') {
+    const idx = field.iterations.findIndex((it) => it.id === value.iterationId)
+    const meta = field.iterations.find((it) => it.id === value.iterationId)
+    return {
+      key: value.iterationId,
+      label: value.title || meta?.title || 'Iteration',
+      orderHint: idx === -1 ? UNKNOWN_INDEX_SENTINEL - 1 : idx,
+      iteration: meta
+        ? { startDate: meta.startDate, duration: meta.duration, completed: meta.completed }
+        : null
+    }
+  }
+  if (field.kind === 'single-select' && value.kind === 'single-select') {
+    const idx = field.options.findIndex((o) => o.id === value.optionId)
+    return {
+      key: value.optionId,
+      label: value.name,
+      orderHint: idx === -1 ? UNKNOWN_INDEX_SENTINEL - 1 : idx,
+      iteration: null
+    }
+  }
+  // Fallback: use stringified value as both key and label.
+  const label = deriveStringValue(value)
+  return { key: `raw:${label}`, label, orderHint: 0, iteration: null }
+}
+
+function labelForEmpty(field: GitHubProjectField): string {
+  return `No ${field.name}`
+}
+
+function deriveStringValue(value: GitHubProjectRow['fieldValuesByFieldId'][string]): string {
+  switch (value.kind) {
+    case 'text':
+      return value.text
+    case 'number':
+      return String(value.number)
+    case 'date':
+      return value.date
+    case 'single-select':
+      return value.name
+    case 'iteration':
+      return value.title
+    case 'labels':
+      return value.labels.map((l) => l.name).join(', ')
+    case 'users':
+      return value.users.map((u) => u.login).join(', ')
+    default:
+      return ''
+  }
+}
+
+export function groupRows(
+  table: GitHubProjectTable,
+  rowsInOrder: GitHubProjectRow[]
+): ProjectGroup[] {
+  const groupField = table.selectedView.groupByFields[0]
+  if (!groupField) {
+    return [{ key: 'all', label: '', iteration: null, rows: rowsInOrder }]
+  }
+  const buckets = new Map<
+    string,
+    {
+      label: string
+      orderHint: number
+      iteration: ProjectGroup['iteration']
+      rows: GitHubProjectRow[]
+    }
+  >()
+  for (const row of rowsInOrder) {
+    const { key, label, orderHint, iteration } = getFieldValueForGrouping(row, groupField)
+    let bucket = buckets.get(key)
+    if (!bucket) {
+      bucket = { label, orderHint, iteration, rows: [] }
+      buckets.set(key, bucket)
+    }
+    bucket.rows.push(row)
+  }
+  const entries = Array.from(buckets.entries())
+  // Ordering rules per design doc §Grouping.
+  entries.sort((a, b) => {
+    // Empty group always last.
+    if (a[0] === EMPTY_GROUP_KEY) {
+      return 1
+    }
+    if (b[0] === EMPTY_GROUP_KEY) {
+      return -1
+    }
+    if (groupField.kind === 'iteration' || groupField.kind === 'single-select') {
+      return a[1].orderHint - b[1].orderHint
+    }
+    return a[1].label.localeCompare(b[1].label)
+  })
+  return entries.map(([key, v]) => ({
+    key,
+    label: v.label,
+    iteration: v.iteration,
+    rows: v.rows
+  }))
+}
+
+function compareSort(a: GitHubProjectRow, b: GitHubProjectRow, sort: GitHubProjectSort): number {
+  const field = sort.field
+  const aValue = a.fieldValuesByFieldId[field.id]
+  const bValue = b.fieldValuesByFieldId[field.id]
+  // Missing values sort last (regardless of direction).
+  if (!aValue && !bValue) {
+    return 0
+  }
+  if (!aValue) {
+    return 1
+  }
+  if (!bValue) {
+    return -1
+  }
+
+  let cmp = 0
+  if (
+    field.kind === 'single-select' &&
+    aValue.kind === 'single-select' &&
+    bValue.kind === 'single-select'
+  ) {
+    const aIdx = field.options.findIndex((o) => o.id === aValue.optionId)
+    const bIdx = field.options.findIndex((o) => o.id === bValue.optionId)
+    cmp =
+      (aIdx === -1 ? UNKNOWN_INDEX_SENTINEL : aIdx) - (bIdx === -1 ? UNKNOWN_INDEX_SENTINEL : bIdx)
+  } else if (
+    field.kind === 'iteration' &&
+    aValue.kind === 'iteration' &&
+    bValue.kind === 'iteration'
+  ) {
+    const aIdx = field.iterations.findIndex((it) => it.id === aValue.iterationId)
+    const bIdx = field.iterations.findIndex((it) => it.id === bValue.iterationId)
+    cmp =
+      (aIdx === -1 ? UNKNOWN_INDEX_SENTINEL : aIdx) - (bIdx === -1 ? UNKNOWN_INDEX_SENTINEL : bIdx)
+  } else if (aValue.kind === 'number' && bValue.kind === 'number') {
+    cmp = aValue.number - bValue.number
+  } else if (aValue.kind === 'date' && bValue.kind === 'date') {
+    cmp = aValue.date.localeCompare(bValue.date)
+  } else if (aValue.kind === 'text' && bValue.kind === 'text') {
+    cmp = aValue.text.localeCompare(bValue.text)
+  } else if (aValue.kind === 'users' && bValue.kind === 'users') {
+    const aLogin = aValue.users[0]?.login ?? ''
+    const bLogin = bValue.users[0]?.login ?? ''
+    if (!aLogin && !bLogin) {
+      cmp = 0
+    } else if (!aLogin) {
+      cmp = 1
+    } else if (!bLogin) {
+      cmp = -1
+    } else {
+      cmp = aLogin.localeCompare(bLogin)
+    }
+  } else if (aValue.kind === 'labels' && bValue.kind === 'labels') {
+    const aName = aValue.labels[0]?.name ?? ''
+    const bName = bValue.labels[0]?.name ?? ''
+    if (!aName && !bName) {
+      cmp = 0
+    } else if (!aName) {
+      cmp = 1
+    } else if (!bName) {
+      cmp = -1
+    } else {
+      cmp = aName.localeCompare(bName)
+    }
+  } else {
+    // Why: unknown sort-field kind — ignore this sort field and fall through
+    // to tie-breaks (and eventually row.position). Dev-time warning gated so
+    // production builds don't spam the console.
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn('[projectView] unknown sort-field kind', field)
+    }
+    return 0
+  }
+  return sort.direction === 'DESC' ? -cmp : cmp
+}
+
+export function sortRows(table: GitHubProjectTable, rows: GitHubProjectRow[]): GitHubProjectRow[] {
+  const sorts = table.selectedView.sortByFields
+  const out = [...rows]
+  out.sort((a, b) => {
+    for (const sort of sorts) {
+      const cmp = compareSort(a, b, sort)
+      if (cmp !== 0) {
+        return cmp
+      }
+    }
+    // Final tie-break: row.position preserves GitHub rank order.
+    return a.position - b.position
+  })
+  return out
+}
+
+export function isIterationCurrent(iteration: { startDate: string; duration: number }): boolean {
+  // Parse as YYYY-MM-DD in UTC to avoid TZ-shift false negatives near midnight.
+  const start = new Date(`${iteration.startDate}T00:00:00Z`).getTime()
+  if (Number.isNaN(start)) {
+    return false
+  }
+  const end = start + iteration.duration * 86_400_000
+  const now = Date.now()
+  return now >= start && now < end
+}
diff --git a/src/renderer/src/components/github-project/slug-dialog/AssigneesEditor.tsx b/src/renderer/src/components/github-project/slug-dialog/AssigneesEditor.tsx
new file mode 100644
index 00000000000..6ccc3a2e05b
--- /dev/null
+++ b/src/renderer/src/components/github-project/slug-dialog/AssigneesEditor.tsx
@@ -0,0 +1,106 @@
+import React, { useEffect, useMemo, useState } from 'react'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { cn } from '@/lib/utils'
+import type { GitHubAssignableUser } from '../../../../../shared/types'
+
+export function AssigneesEditor({
+  owner,
+  repo,
+  selected,
+  disabled,
+  onChange
+}: {
+  owner: string
+  repo: string
+  selected: string[]
+  disabled?: boolean
+  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)
+  // 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])
+  return (
+    <Popover open={open} onOpenChange={(o) => !disabled && setOpen(o)}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          disabled={disabled}
+          className="rounded-md border border-border/50 bg-muted/30 px-2 py-0.5 text-[11px] hover:bg-muted disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-muted/30"
+        >
+          Assignees: {selected.length === 0 ? 'none' : selected.join(', ')}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-64 p-1">
+        {loading ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
+        ) : (
+          users.map((u) => {
+            const isOn = selected.includes(u.login)
+            return (
+              <button
+                key={u.login}
+                type="button"
+                className="flex w-full items-center gap-2 rounded px-2 py-1 text-xs hover:bg-muted/50"
+                onClick={() => {
+                  if (isOn) {
+                    void onChange([], [u.login])
+                  } else {
+                    void onChange([u.login], [])
+                  }
+                }}
+              >
+                <span
+                  className={cn(
+                    'inline-block size-2 rounded-full',
+                    isOn ? 'bg-primary' : 'bg-muted-foreground/40'
+                  )}
+                />
+                {u.avatarUrl ? (
+                  <img src={u.avatarUrl} alt="" className="size-4 rounded-full" />
+                ) : null}
+                {u.login}
+              </button>
+            )
+          })
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}
diff --git a/src/renderer/src/components/github-project/slug-dialog/Comments.tsx b/src/renderer/src/components/github-project/slug-dialog/Comments.tsx
new file mode 100644
index 00000000000..5f914224218
--- /dev/null
+++ b/src/renderer/src/components/github-project/slug-dialog/Comments.tsx
@@ -0,0 +1,174 @@
+import React, { useState } from 'react'
+import { Send } from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
+import type { PRComment } from '../../../../../shared/types'
+
+export function CommentsList({
+  owner,
+  repo,
+  comments,
+  onChange
+}: {
+  owner: string
+  repo: string
+  comments: PRComment[]
+  onChange: (next: PRComment[]) => void
+}): React.JSX.Element {
+  return (
+    <div className="flex flex-col gap-3">
+      {comments.length === 0 ? (
+        <div className="text-xs italic text-muted-foreground">No comments yet.</div>
+      ) : (
+        comments.map((c) => (
+          <CommentRow
+            key={c.id}
+            owner={owner}
+            repo={repo}
+            comment={c}
+            onDelete={async () => {
+              const res = await window.api.gh.deleteIssueCommentBySlug({
+                owner,
+                repo,
+                commentId: c.id
+              })
+              if (!res.ok) {
+                toast.error(res.error.message)
+                return
+              }
+              onChange(comments.filter((x) => x.id !== c.id))
+            }}
+            onEdit={async (next) => {
+              const res = await window.api.gh.updateIssueCommentBySlug({
+                owner,
+                repo,
+                commentId: c.id,
+                body: next
+              })
+              if (!res.ok) {
+                toast.error(res.error.message)
+                return
+              }
+              onChange(comments.map((x) => (x.id === c.id ? { ...x, body: next } : x)))
+            }}
+          />
+        ))
+      )}
+    </div>
+  )
+}
+
+function CommentRow({
+  comment,
+  onDelete,
+  onEdit
+}: {
+  owner: string
+  repo: string
+  comment: PRComment
+  onDelete: () => void | Promise<void>
+  onEdit: (next: string) => void | Promise<void>
+}): React.JSX.Element {
+  const [editing, setEditing] = useState(false)
+  const [draft, setDraft] = useState(comment.body)
+  return (
+    <div className="rounded border border-border/50 bg-muted/20 p-3">
+      <div className="mb-1 flex items-center justify-between text-[11px] text-muted-foreground">
+        <span>{comment.author}</span>
+        <div className="flex gap-2">
+          <button
+            type="button"
+            className="hover:underline"
+            onClick={() => {
+              setDraft(comment.body)
+              setEditing(true)
+            }}
+          >
+            Edit
+          </button>
+          <button type="button" className="hover:underline" onClick={() => void onDelete()}>
+            Delete
+          </button>
+        </div>
+      </div>
+      {editing ? (
+        <div className="flex flex-col gap-2">
+          <textarea
+            autoFocus
+            value={draft}
+            onChange={(e) => setDraft(e.target.value)}
+            className="min-h-[80px] w-full rounded border border-border/50 bg-background p-2 text-sm"
+          />
+          <div className="flex gap-2">
+            <Button
+              size="sm"
+              onClick={() => {
+                setEditing(false)
+                void onEdit(draft)
+              }}
+            >
+              Save
+            </Button>
+            <Button size="sm" variant="ghost" onClick={() => setEditing(false)}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      ) : (
+        <CommentMarkdown content={comment.body} />
+      )}
+    </div>
+  )
+}
+
+export function NewCommentForm({
+  owner,
+  repo,
+  number,
+  onAdded
+}: {
+  owner: string
+  repo: string
+  number: number
+  onAdded: (c: PRComment) => void
+}): React.JSX.Element {
+  const [draft, setDraft] = useState('')
+  const [submitting, setSubmitting] = useState(false)
+  return (
+    <div className="flex flex-col gap-2">
+      <textarea
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        placeholder="Write a comment…"
+        className="min-h-[80px] w-full rounded border border-border/50 bg-background p-2 text-sm"
+      />
+      <div className="flex justify-end">
+        <Button
+          size="sm"
+          disabled={!draft.trim() || submitting}
+          onClick={async () => {
+            const body = draft.trim()
+            if (!body) {
+              return
+            }
+            setSubmitting(true)
+            try {
+              const res = await window.api.gh.addIssueCommentBySlug({ owner, repo, number, body })
+              if (!res.ok) {
+                toast.error(res.error.message)
+                return
+              }
+              onAdded(res.comment)
+              setDraft('')
+            } finally {
+              setSubmitting(false)
+            }
+          }}
+        >
+          <Send className="mr-1 size-3.5" /> Comment
+        </Button>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/github-project/slug-dialog/LabelsEditor.tsx b/src/renderer/src/components/github-project/slug-dialog/LabelsEditor.tsx
new file mode 100644
index 00000000000..6ac9eaed9a6
--- /dev/null
+++ b/src/renderer/src/components/github-project/slug-dialog/LabelsEditor.tsx
@@ -0,0 +1,94 @@
+import React, { useEffect, useState } from 'react'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { cn } from '@/lib/utils'
+
+export function LabelsEditor({
+  owner,
+  repo,
+  selected,
+  disabled,
+  onChange
+}: {
+  owner: string
+  repo: string
+  selected: string[]
+  disabled?: boolean
+  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])
+  return (
+    <Popover open={open} onOpenChange={(o) => !disabled && setOpen(o)}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          disabled={disabled}
+          className="rounded-md border border-border/50 bg-muted/30 px-2 py-0.5 text-[11px] hover:bg-muted disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-muted/30"
+        >
+          Labels: {selected.length === 0 ? 'none' : selected.join(', ')}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-64 p-1">
+        {loading ? (
+          <div className="px-2 py-1 text-xs text-muted-foreground">Loading…</div>
+        ) : (
+          options.map((name) => {
+            const isOn = selected.includes(name)
+            return (
+              <button
+                key={name}
+                type="button"
+                className="flex w-full items-center gap-2 rounded px-2 py-1 text-xs hover:bg-muted/50"
+                onClick={() => {
+                  if (isOn) {
+                    void onChange([], [name])
+                  } else {
+                    void onChange([name], [])
+                  }
+                }}
+              >
+                <span
+                  className={cn(
+                    'inline-block size-2 rounded-full',
+                    isOn ? 'bg-primary' : 'bg-muted-foreground/40'
+                  )}
+                />
+                {name}
+              </button>
+            )
+          })
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}
diff --git a/src/renderer/src/components/github-project/slug-dialog/SlugDialogBody.tsx b/src/renderer/src/components/github-project/slug-dialog/SlugDialogBody.tsx
new file mode 100644
index 00000000000..5878ab970ef
--- /dev/null
+++ b/src/renderer/src/components/github-project/slug-dialog/SlugDialogBody.tsx
@@ -0,0 +1,310 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { CircleDot, ExternalLink, GitPullRequest, LoaderCircle, X } from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
+import { useAppStore } from '@/store'
+import type { GitHubWorkItemDetails } from '../../../../../shared/types'
+import type { GitHubItemDialogProjectOrigin } from '@/components/GitHubItemDialog'
+import { LabelsEditor } from './LabelsEditor'
+import { AssigneesEditor } from './AssigneesEditor'
+import { CommentsList, NewCommentForm } from './Comments'
+
+export function SlugDialogBody({
+  projectOrigin,
+  onClose
+}: {
+  projectOrigin: GitHubItemDialogProjectOrigin
+  onClose: () => void
+}): React.JSX.Element {
+  const { owner, repo, number, type, cacheKey } = projectOrigin
+  const patchProjectIssueOrPr = useAppStore((s) => s.patchProjectIssueOrPr)
+  const projectViewCache = useAppStore((s) => s.projectViewCache)
+
+  // Why: the Project row is the source of truth for the list-side columns;
+  // reading it reactively here keeps the dialog in sync with optimistic
+  // patches applied by the table (e.g. inline assignee edits).
+  const row = useMemo(() => {
+    const table = projectViewCache[cacheKey]?.data
+    if (!table) {
+      return null
+    }
+    return (
+      table.rows.find(
+        (r) =>
+          r.content.number === number &&
+          r.content.repository?.toLowerCase() === `${owner}/${repo}`.toLowerCase()
+      ) ?? null
+    )
+  }, [projectViewCache, cacheKey, owner, repo, number])
+
+  const [details, setDetails] = useState<GitHubWorkItemDetails | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const requestIdRef = useRef(0)
+
+  useEffect(() => {
+    requestIdRef.current += 1
+    const rid = requestIdRef.current
+    setLoading(true)
+    setError(null)
+    setDetails(null)
+    window.api.gh
+      .projectWorkItemDetailsBySlug({ owner, repo, number, type })
+      .then((res) => {
+        if (rid !== requestIdRef.current) {
+          return
+        }
+        if (res.ok) {
+          setDetails(res.details)
+        } else {
+          setError(res.error.message)
+        }
+      })
+      .catch((err) => {
+        if (rid !== requestIdRef.current) {
+          return
+        }
+        setError(err instanceof Error ? err.message : 'Failed to load details')
+      })
+      .finally(() => {
+        if (rid !== requestIdRef.current) {
+          return
+        }
+        setLoading(false)
+      })
+  }, [owner, repo, number, type])
+
+  const title = row?.content.title ?? details?.item.title ?? ''
+  const url = row?.content.url ?? details?.item.url ?? null
+  const Icon = type === 'pr' ? GitPullRequest : CircleDot
+
+  const [editingTitle, setEditingTitle] = useState(false)
+  const [titleDraft, setTitleDraft] = useState('')
+
+  const commitTitle = useCallback(async () => {
+    const next = titleDraft.trim()
+    setEditingTitle(false)
+    if (!next || next === title) {
+      return
+    }
+    // Why: without a row id we can't address the project item — the helper
+    // would just return "Row not found" and toast-spam the user. The title
+    // button is also disabled in this case (see render below).
+    if (!row) {
+      return
+    }
+    const res = await patchProjectIssueOrPr(cacheKey, row.id, { title: next })
+    if (!res.ok) {
+      toast.error(res.error.message)
+    }
+  }, [titleDraft, title, patchProjectIssueOrPr, cacheKey, row])
+
+  const [editingBody, setEditingBody] = useState(false)
+  const [bodyDraft, setBodyDraft] = useState('')
+  const body = details?.body ?? ''
+  const commitBody = useCallback(async () => {
+    setEditingBody(false)
+    if (bodyDraft === body) {
+      return
+    }
+    // Why: same reason as commitTitle — bail rather than ask the helper to
+    // patch a missing row. The body button is also disabled when row is null.
+    if (!row) {
+      return
+    }
+    const res = await patchProjectIssueOrPr(cacheKey, row.id, { body: bodyDraft })
+    if (!res.ok) {
+      toast.error(res.error.message)
+      return
+    }
+    setDetails((prev) => (prev ? { ...prev, body: bodyDraft } : prev))
+  }, [bodyDraft, body, patchProjectIssueOrPr, cacheKey, row])
+
+  const labels = row?.content.labels.map((l) => l.name) ?? []
+  const assignees = row?.content.assignees.map((u) => u.login) ?? []
+
+  return (
+    <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">
+          <Icon className="mt-1 size-4 shrink-0 text-muted-foreground" />
+          <div className="min-w-0 flex-1">
+            <div className="flex items-center gap-2 text-[11px] text-muted-foreground">
+              <span className="font-mono">
+                {owner}/{repo}#{number}
+              </span>
+            </div>
+            {editingTitle ? (
+              <Input
+                autoFocus
+                value={titleDraft}
+                onChange={(e) => setTitleDraft(e.target.value)}
+                onBlur={() => void commitTitle()}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') {
+                    e.preventDefault()
+                    void commitTitle()
+                  } else if (e.key === 'Escape') {
+                    e.preventDefault()
+                    setEditingTitle(false)
+                  }
+                }}
+                className="mt-1 h-8"
+              />
+            ) : (
+              <button
+                type="button"
+                disabled={!row}
+                className="mt-1 text-left text-[15px] font-semibold leading-tight hover:underline disabled:cursor-not-allowed disabled:no-underline disabled:opacity-80"
+                onClick={() => {
+                  setTitleDraft(title)
+                  setEditingTitle(true)
+                }}
+              >
+                {title || 'Untitled'}
+              </button>
+            )}
+          </div>
+          <div className="flex items-center gap-1">
+            {url ? (
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-7 w-7"
+                onClick={() => void window.api.shell.openUrl(url)}
+                aria-label="Open in GitHub"
+              >
+                <ExternalLink className="size-3.5" />
+              </Button>
+            ) : null}
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-7 w-7"
+              onClick={onClose}
+              aria-label="Close"
+            >
+              <X className="size-3.5" />
+            </Button>
+          </div>
+        </div>
+        <div className="mt-3 flex flex-wrap items-center gap-3 text-[11px]">
+          <LabelsEditor
+            owner={owner}
+            repo={repo}
+            selected={labels}
+            disabled={!row}
+            onChange={async (add, remove) => {
+              // Why: bail rather than call the helper with an empty id —
+              // see commitTitle above. Trigger is also disabled when !row.
+              if (!row) {
+                return
+              }
+              const res = await patchProjectIssueOrPr(cacheKey, row.id, {
+                ...(add.length ? { addLabels: add } : {}),
+                ...(remove.length ? { removeLabels: remove } : {})
+              })
+              if (!res.ok) {
+                toast.error(res.error.message)
+              }
+            }}
+          />
+          <AssigneesEditor
+            owner={owner}
+            repo={repo}
+            selected={assignees}
+            disabled={!row}
+            onChange={async (add, remove) => {
+              if (!row) {
+                return
+              }
+              const res = await patchProjectIssueOrPr(cacheKey, row.id, {
+                ...(add.length ? { addAssignees: add } : {}),
+                ...(remove.length ? { removeAssignees: remove } : {})
+              })
+              if (!res.ok) {
+                toast.error(res.error.message)
+              }
+            }}
+          />
+        </div>
+      </div>
+
+      <div className="flex-1 min-h-0 overflow-y-auto px-4 py-3">
+        {loading && !details ? (
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <LoaderCircle className="size-4 animate-spin" /> Loading…
+          </div>
+        ) : error ? (
+          <div className="text-sm text-destructive">{error}</div>
+        ) : details ? (
+          <div className="flex flex-col gap-4">
+            <section>
+              {editingBody ? (
+                <div className="flex flex-col gap-2">
+                  <textarea
+                    autoFocus
+                    value={bodyDraft}
+                    onChange={(e) => setBodyDraft(e.target.value)}
+                    className="min-h-[140px] w-full rounded border border-border/50 bg-background p-2 text-sm"
+                  />
+                  <div className="flex gap-2">
+                    <Button size="sm" onClick={() => void commitBody()}>
+                      Save
+                    </Button>
+                    <Button size="sm" variant="ghost" onClick={() => setEditingBody(false)}>
+                      Cancel
+                    </Button>
+                  </div>
+                </div>
+              ) : body ? (
+                <button
+                  type="button"
+                  disabled={!row}
+                  className="block w-full text-left disabled:cursor-not-allowed"
+                  onClick={() => {
+                    setBodyDraft(body)
+                    setEditingBody(true)
+                  }}
+                >
+                  <CommentMarkdown content={body} variant="document" />
+                </button>
+              ) : (
+                <button
+                  type="button"
+                  disabled={!row}
+                  className="text-xs italic text-muted-foreground hover:underline disabled:cursor-not-allowed disabled:no-underline"
+                  onClick={() => {
+                    setBodyDraft('')
+                    setEditingBody(true)
+                  }}
+                >
+                  Add a description…
+                </button>
+              )}
+            </section>
+            <section className="flex flex-col gap-3">
+              <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                Comments
+              </h3>
+              <CommentsList
+                owner={owner}
+                repo={repo}
+                comments={details.comments}
+                onChange={(next) => setDetails((d) => (d ? { ...d, comments: next } : d))}
+              />
+              <NewCommentForm
+                owner={owner}
+                repo={repo}
+                number={number}
+                onAdded={(c) => setDetails((d) => (d ? { ...d, comments: [...d.comments, c] } : d))}
+              />
+            </section>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/github/GitHubRateLimitPill.tsx b/src/renderer/src/components/github/GitHubRateLimitPill.tsx
new file mode 100644
index 00000000000..51a2e5293be
--- /dev/null
+++ b/src/renderer/src/components/github/GitHubRateLimitPill.tsx
@@ -0,0 +1,205 @@
+/**
+ * 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 runs in the background 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 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
+}
+
+export default function GitHubRateLimitPill(): React.JSX.Element | null {
+  const [snapshot, setSnapshot] = useState<GitHubRateLimitSnapshot | null>(null)
+  const [hasError, setHasError] = useState(false)
+  // 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 {
+        setHasError(true)
+      }
+    } catch {
+      if (token !== latestToken.current) {
+        return
+      }
+      setHasError(true)
+    }
+  }, [])
+
+  useEffect(() => {
+    void fetchSnapshot(false)
+    const handle = window.setInterval(() => {
+      void fetchSnapshot(false)
+    }, REFRESH_INTERVAL_MS)
+    return () => window.clearInterval(handle)
+  }, [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>
+  )
+}
diff --git a/src/renderer/src/components/new-workspace/CreateFromTab.tsx b/src/renderer/src/components/new-workspace/CreateFromTab.tsx
deleted file mode 100644
index a0f8d07fc61..00000000000
--- a/src/renderer/src/components/new-workspace/CreateFromTab.tsx
+++ /dev/null
@@ -1,1327 +0,0 @@
-/* eslint-disable max-lines -- Why: this tab co-locates GitHub PR/issue/branch
-and Linear sub-tabs + their fetch/resolve/launch plumbing so the "Create from…"
-entry point lives in one file. Splitting would scatter debounce/caching logic
-that only these sub-tabs use. */
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { useShallow } from 'zustand/react/shallow'
-import {
-  CircleDot,
-  CornerDownLeft,
-  GitBranch,
-  GitPullRequest,
-  LoaderCircle,
-  Search
-} from 'lucide-react'
-import { Command, CommandGroup, CommandItem, CommandList } from '@/components/ui/command'
-import { Input } from '@/components/ui/input'
-import { Popover, PopoverAnchor, PopoverContent } from '@/components/ui/popover'
-import RepoCombobox from '@/components/repo/RepoCombobox'
-import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
-import IssueSourceSelector from '@/components/github/IssueSourceSelector'
-import { sameGitHubOwnerRepo } from '@/components/github/IssueSourceIndicator'
-import { useAppStore } from '@/store'
-import { cn } from '@/lib/utils'
-import { normalizeGitHubLinkQuery } from '@/lib/github-links'
-import { launchWorkItemDirect, launchFromBranch } from '@/lib/launch-work-item-direct'
-import { isGitRepoKind } from '../../../../shared/repo-kind'
-import type { GitHubWorkItem, LinearIssue } from '../../../../shared/types'
-
-export type CreateFromSubTab = 'prs' | 'issues' | 'branches' | 'linear'
-
-type CreateFromTabProps = {
-  /** Invoked after a successful workspace launch so the parent can close the
-   *  dialog. */
-  onLaunched: () => void
-  /** Called when any code path needs to fall back to the Quick-tab composer
-   *  (setup policy = 'ask', or the launch failed mid-flight). The parent is
-   *  responsible for switching tabs and prefilling whatever context is
-   *  available (linked work item, base branch, etc.). */
-  onFallbackToQuick: (data: {
-    initialRepoId?: string
-    linkedWorkItem?: {
-      type: 'issue' | 'pr'
-      number: number
-      title: string
-      url: string
-    } | null
-    prefilledName?: string
-    initialBaseBranch?: string
-  }) => void
-  /** Whether this tab is currently visible. Used by effects that should only
-   *  run while the user can actually see the results (fetching, autoFocus). */
-  active?: boolean
-}
-
-const SUB_TABS: {
-  id: CreateFromSubTab
-  label: string
-  Icon: React.ComponentType<{ className?: string }>
-}[] = [
-  { id: 'prs', label: 'Pull requests', Icon: GitPullRequest },
-  { id: 'issues', label: 'Issues', Icon: CircleDot },
-  { id: 'branches', label: 'Branches', Icon: GitBranch },
-  {
-    id: 'linear',
-    label: 'Linear',
-    Icon: ({ className }: { className?: string }) => (
-      <svg viewBox="0 0 24 24" aria-hidden className={className} fill="currentColor">
-        <path d="M2.886 4.18A11.982 11.982 0 0 1 11.99 0C18.624 0 24 5.376 24 12.009c0 3.64-1.62 6.903-4.18 9.105L2.887 4.18ZM1.817 5.626l16.556 16.556c-.524.33-1.075.62-1.65.866L.951 7.277c.247-.575.537-1.126.866-1.65ZM.322 9.163l14.515 14.515c-.71.172-1.443.282-2.195.322L0 11.358a12 12 0 0 1 .322-2.195Zm-.17 4.862 9.823 9.824a12.02 12.02 0 0 1-9.824-9.824Z" />
-      </svg>
-    )
-  }
-]
-
-const PR_LIST_LIMIT = 36
-const ISSUE_LIST_LIMIT = 36
-const BRANCH_CACHE_TTL_MS = 60_000
-// Why: branches change rarely during a composer session. A module-scoped
-// cache keyed on repoId + query (60s TTL) means switching sub-tabs or
-// re-opening the modal returns the prior result instantly instead of
-// re-shelling out to `git for-each-ref` (which can be slow on large repos).
-const branchCache = new Map<string, { data: string[]; fetchedAt: number }>()
-// Why: the unqualified empty-query path returns PRs + issues merged and
-// sliced to `limit`. Use the sum so each tab can render up to its own cap
-// after filtering by type client-side — and because both effects pass the
-// same limit, they share one cached IPC call and one gh invocation.
-const COMBINED_WORK_ITEM_LIMIT = PR_LIST_LIMIT + ISSUE_LIST_LIMIT
-const LINEAR_LIST_LIMIT = 36
-const SEARCH_DEBOUNCE_MS = 200
-
-export default function CreateFromTab({
-  onLaunched,
-  onFallbackToQuick,
-  active = true
-}: CreateFromTabProps): React.JSX.Element {
-  const {
-    activeRepoId,
-    repos,
-    linearStatus,
-    listLinearIssues,
-    searchLinearIssues,
-    rememberedSubTab,
-    setRememberedSubTab,
-    fetchWorkItems,
-    getCachedWorkItems,
-    getWorkItemsSourcesAndError,
-    setIssueSourcePreference,
-    workItemsInvalidationNonce
-  } = useAppStore(
-    useShallow((s) => ({
-      activeRepoId: s.activeRepoId,
-      repos: s.repos,
-      linearStatus: s.linearStatus,
-      listLinearIssues: s.listLinearIssues,
-      searchLinearIssues: s.searchLinearIssues,
-      rememberedSubTab: s.createFromSubTab,
-      setRememberedSubTab: s.setCreateFromSubTab,
-      fetchWorkItems: s.fetchWorkItems,
-      getCachedWorkItems: s.getCachedWorkItems,
-      getWorkItemsSourcesAndError: s.getWorkItemsSourcesAndError,
-      setIssueSourcePreference: s.setIssueSourcePreference,
-      // Why: re-run the issues fetch effect after `setIssueSourcePreference`
-      // evicts this repo's cache entries — otherwise flipping the selector
-      // clears the cache but the effect's deps wouldn't force a refetch and
-      // the Issues sub-tab would briefly show stale (then empty-once-cached-
-      // expires) data until the user typed or switched tabs.
-      workItemsInvalidationNonce: s.workItemsInvalidationNonce
-    }))
-  )
-
-  const eligibleRepos = useMemo(() => repos.filter((r) => isGitRepoKind(r)), [repos])
-
-  // Why: seed from the remembered sub-tab so users returning to Create-from
-  // land on whichever source they worked from last (GitHub Issues, Linear,
-  // …). A writer-through setter keeps the store in sync whenever the user
-  // switches, which persists across composer closes within the same session.
-  const searchInputRef = useRef<HTMLInputElement | null>(null)
-  const subTabsListRef = useRef<HTMLDivElement | null>(null)
-  const [subTab, setSubTabLocal] = useState<CreateFromSubTab>(rememberedSubTab)
-  // Why: results live in a popover anchored to the search input so the
-  // dialog stays compact while the list sizes to content and can show
-  // async-loading skeletons without reserving a 320px block inside the
-  // modal. The popover opens as soon as the input is focused so users
-  // see their options immediately — opening only on keystroke felt
-  // unresponsive given this flow starts by clicking the field.
-  const [resultsOpen, setResultsOpen] = useState(false)
-  // Why: the results popover auto-opens on focus, but clicking a sub-tab
-  // pulls focus away from the search input and Radix closes the popover
-  // on the pointer-down. Re-open on sub-tab change so the new sub-tab's
-  // results appear immediately rather than forcing the user to click the
-  // input again; also refocus the input so typing continues the flow.
-  const setSubTab = useCallback(
-    (next: CreateFromSubTab) => {
-      setSubTabLocal(next)
-      setRememberedSubTab(next)
-      setResultsOpen(true)
-      // Why: preemptively flip the new sub-tab's loading flag so the single
-      // render between sub-tab change and the fetch effect doesn't flash
-      // "No open PRs / No issues / …" while stale state from the previous
-      // sub-tab still claims nothing is loading. The fetch effect sets the
-      // flag to true again on mount, then to false when data resolves — so
-      // this just patches the one-frame gap.
-      if (next === 'prs') {
-        setPrLoading(true)
-      } else if (next === 'issues') {
-        setIssueLoading(true)
-      } else if (next === 'branches') {
-        setBranchesLoading(true)
-      } else if (next === 'linear') {
-        setLinearLoading(true)
-      }
-      requestAnimationFrame(() => {
-        searchInputRef.current?.focus({ preventScroll: true })
-      })
-    },
-    [setRememberedSubTab]
-  )
-  const [query, setQuery] = useState('')
-  const [debouncedQuery, setDebouncedQuery] = useState('')
-  const [selectedRepoId, setSelectedRepoId] = useState<string>(() => {
-    if (activeRepoId && eligibleRepos.some((r) => r.id === activeRepoId)) {
-      return activeRepoId
-    }
-    return eligibleRepos[0]?.id ?? ''
-  })
-
-  useEffect(() => {
-    const timer = window.setTimeout(() => setDebouncedQuery(query), SEARCH_DEBOUNCE_MS)
-    return () => window.clearTimeout(timer)
-  }, [query])
-
-  // Why: auto-focus the search input when this tab becomes visible — but
-  // only when it's actually visible AND the parent tab-panel height
-  // transition has settled. Without the `active` guard, the
-  // AnimatedTabPanels wrapper (which keeps both panels mounted for
-  // state-preservation) would let the search field steal focus from the
-  // Quick tab's repo combobox on modal open. The transition-settle delay
-  // matters because focusing the input fires onFocus → setResultsOpen(true)
-  // → Popover positions against the anchor. If the anchor is still moving
-  // (AnimatedTabPanels animates the wrapper height over ~200ms), Radix
-  // anchors the popover mid-flight and it visibly drifts down as the
-  // layout settles. Waiting past the transition lets Radix place it
-  // against the final input position from the start.
-  useEffect(() => {
-    if (!active) {
-      return
-    }
-    const el = searchInputRef.current
-    if (!el) {
-      return
-    }
-    const timer = window.setTimeout(() => el.focus({ preventScroll: true }), 220)
-    return () => window.clearTimeout(timer)
-  }, [active])
-
-  // Why: the results popover is portaled outside this panel, so switching
-  // to the Quick tab (via click or the ⌘N hotkey) doesn't unmount or hide
-  // it — users would see the CreateFrom dropdown floating over the Quick
-  // tab. Force-close when this tab goes inactive.
-  useEffect(() => {
-    if (!active) {
-      setResultsOpen(false)
-    }
-  }, [active])
-
-  const selectedRepo = useMemo(
-    () => eligibleRepos.find((r) => r.id === selectedRepoId) ?? null,
-    [eligibleRepos, selectedRepoId]
-  )
-  const isRemoteRepo = Boolean(selectedRepo?.connectionId)
-
-  const normalizedGhQuery = useMemo(
-    () => normalizeGitHubLinkQuery(debouncedQuery),
-    [debouncedQuery]
-  )
-
-  // ---------------------------------------------------------------------
-  // GitHub PRs
-  // ---------------------------------------------------------------------
-  const [prItems, setPrItems] = useState<GitHubWorkItem[]>([])
-  const [prLoading, setPrLoading] = useState(false)
-  const [prError, setPrError] = useState<string | null>(null)
-  const [directPr, setDirectPr] = useState<GitHubWorkItem | null>(null)
-
-  useEffect(() => {
-    if (subTab !== 'prs' || !selectedRepo?.path || isRemoteRepo) {
-      return
-    }
-    if (normalizedGhQuery.directNumber !== null) {
-      return // handled by direct-lookup effect below
-    }
-    const trimmed = debouncedQuery.trim()
-    // Why: when the user hasn't typed anything, use the unqualified listing —
-    // the backend routes that to `listRecentWorkItems` which hits
-    // `gh api --cache 120s` (fast, cached). Adding `is:pr is:open` forces the
-    // slow `gh pr list --search` path every time and skips the 60s renderer
-    // cache in the store. Same shortcut is used for the issues effect below.
-    const q = trimmed ? `is:pr is:open ${normalizedGhQuery.query}` : ''
-    // Why: empty-query path returns PRs+issues merged, so use the combined
-    // cap so the PR and Issue effects collapse onto the same cache key and
-    // dedupe into a single gh invocation via the store's inflight tracker.
-    const effectiveLimit = trimmed ? PR_LIST_LIMIT : COMBINED_WORK_ITEM_LIMIT
-
-    // Why: route through the store so the 60s workItemsCache + inflight dedup
-    // kick in. Re-opening the modal or toggling PR↔Issue sub-tabs returns
-    // cached data instantly instead of re-running gh search.
-    const cached = getCachedWorkItems(selectedRepo.path, effectiveLimit, q)
-    if (cached) {
-      setPrItems(cached.filter((i) => i.type === 'pr').slice(0, PR_LIST_LIMIT))
-      setPrLoading(false)
-      setPrError(null)
-    }
-
-    let stale = false
-    if (!cached) {
-      setPrLoading(true)
-    }
-    setPrError(null)
-    void fetchWorkItems(selectedRepo.id, selectedRepo.path, effectiveLimit, q)
-      .then((items) => {
-        if (stale) {
-          return
-        }
-        setPrItems(items.filter((i) => i.type === 'pr').slice(0, PR_LIST_LIMIT))
-        setPrLoading(false)
-      })
-      .catch((err) => {
-        if (stale) {
-          return
-        }
-        setPrError(err instanceof Error ? err.message : 'Failed to load PRs.')
-        setPrLoading(false)
-      })
-    return () => {
-      stale = true
-    }
-  }, [
-    subTab,
-    selectedRepo?.id,
-    selectedRepo?.path,
-    isRemoteRepo,
-    debouncedQuery,
-    normalizedGhQuery.query,
-    normalizedGhQuery.directNumber,
-    fetchWorkItems,
-    getCachedWorkItems
-  ])
-
-  // ---------------------------------------------------------------------
-  // GitHub Issues
-  // ---------------------------------------------------------------------
-  const [issueItems, setIssueItems] = useState<GitHubWorkItem[]>([])
-  const [issueLoading, setIssueLoading] = useState(false)
-  const [issueError, setIssueError] = useState<string | null>(null)
-
-  useEffect(() => {
-    if (subTab !== 'issues' || !selectedRepo?.path || isRemoteRepo) {
-      return
-    }
-    if (normalizedGhQuery.directNumber !== null) {
-      return
-    }
-    const trimmed = debouncedQuery.trim()
-    // Why: empty query → backend's fast cached path (see PR effect above).
-    // When no query is typed this is the SAME IPC call as the PR effect, so
-    // the store's inflight dedup collapses them into a single gh invocation.
-    const q = trimmed ? `is:issue is:open ${normalizedGhQuery.query}` : ''
-    const effectiveLimit = trimmed ? ISSUE_LIST_LIMIT : COMBINED_WORK_ITEM_LIMIT
-
-    const cached = getCachedWorkItems(selectedRepo.path, effectiveLimit, q)
-    if (cached) {
-      setIssueItems(cached.filter((i) => i.type === 'issue').slice(0, ISSUE_LIST_LIMIT))
-      setIssueLoading(false)
-      setIssueError(null)
-    }
-
-    let stale = false
-    if (!cached) {
-      setIssueLoading(true)
-    }
-    setIssueError(null)
-    void fetchWorkItems(selectedRepo.id, selectedRepo.path, effectiveLimit, q)
-      .then((items) => {
-        if (stale) {
-          return
-        }
-        setIssueItems(items.filter((i) => i.type === 'issue').slice(0, ISSUE_LIST_LIMIT))
-        // Why: partial failures (e.g. a 403 on a private upstream's issues)
-        // must surface here, otherwise the subtab shows an empty list and
-        // re-creates the silent-wrongness the parent feature aims to eliminate.
-        // fetchWorkItems stores envelope-level errors on the cache entry; read
-        // them via the selector so the banner surfaces rather than the subtab
-        // silently showing no items. This branch is mutually exclusive with the
-        // .catch below: a cached error implies the IPC call resolved, so
-        // there's no double-surface risk between the two setIssueError paths.
-        const { error } = getWorkItemsSourcesAndError(selectedRepo.path, effectiveLimit, q)
-        if (error) {
-          setIssueError(error.message)
-        }
-        setIssueLoading(false)
-      })
-      .catch((err) => {
-        if (stale) {
-          return
-        }
-        setIssueError(err instanceof Error ? err.message : 'Failed to load issues.')
-        setIssueLoading(false)
-      })
-    return () => {
-      stale = true
-    }
-  }, [
-    subTab,
-    selectedRepo?.id,
-    selectedRepo?.path,
-    isRemoteRepo,
-    debouncedQuery,
-    normalizedGhQuery.query,
-    normalizedGhQuery.directNumber,
-    fetchWorkItems,
-    getCachedWorkItems,
-    getWorkItemsSourcesAndError,
-    // Why: flipping the issue-source selector evicts this repo's cache and
-    // bumps the nonce so this effect re-runs against the new preference.
-    // Matches the identical pattern in TaskPage's Tasks-list fetch effect.
-    workItemsInvalidationNonce
-  ])
-
-  // ---------------------------------------------------------------------
-  // Direct `#N` / URL lookup across PR + Issue tabs
-  // ---------------------------------------------------------------------
-  const [directLoading, setDirectLoading] = useState(false)
-  useEffect(() => {
-    if ((subTab !== 'prs' && subTab !== 'issues') || !selectedRepo?.path || isRemoteRepo) {
-      setDirectPr(null)
-      return
-    }
-    const directNumber = normalizedGhQuery.directNumber
-    if (directNumber === null) {
-      setDirectPr(null)
-      return
-    }
-    let stale = false
-    setDirectLoading(true)
-    void window.api.gh
-      .workItem({ repoPath: selectedRepo.path, number: directNumber })
-      .then((item) => {
-        if (stale) {
-          return
-        }
-        const gh = item as GitHubWorkItem | null
-        if (!gh) {
-          setDirectPr(null)
-        } else {
-          const wantedType = subTab === 'prs' ? 'pr' : 'issue'
-          setDirectPr(
-            gh.type === wantedType
-              ? ({ ...gh, repoId: selectedRepo.id } as unknown as GitHubWorkItem)
-              : null
-          )
-        }
-      })
-      .catch(() => {
-        if (!stale) {
-          setDirectPr(null)
-        }
-      })
-      .finally(() => {
-        if (!stale) {
-          setDirectLoading(false)
-        }
-      })
-    return () => {
-      stale = true
-    }
-  }, [subTab, selectedRepo?.id, selectedRepo?.path, isRemoteRepo, normalizedGhQuery.directNumber])
-
-  // ---------------------------------------------------------------------
-  // Branches
-  // ---------------------------------------------------------------------
-  const [branches, setBranches] = useState<string[]>([])
-  const [branchesLoading, setBranchesLoading] = useState(false)
-  useEffect(() => {
-    if (subTab !== 'branches' || !selectedRepo) {
-      return
-    }
-    const trimmed = debouncedQuery.trim()
-    const cacheKey = `${selectedRepo.id}::${trimmed}`
-    const cached = branchCache.get(cacheKey)
-    const fresh = cached && Date.now() - cached.fetchedAt < BRANCH_CACHE_TTL_MS
-    if (cached) {
-      // Why: show stale cache immediately (SWR-style); the fetch below keeps
-      // the list current. Only skip the loader flash if the entry is fresh.
-      setBranches(cached.data)
-      if (fresh) {
-        setBranchesLoading(false)
-        return
-      }
-    }
-    let stale = false
-    if (!cached) {
-      setBranchesLoading(true)
-    }
-    void window.api.repos
-      .searchBaseRefs({ repoId: selectedRepo.id, query: trimmed, limit: 30 })
-      .then((results) => {
-        branchCache.set(cacheKey, { data: results, fetchedAt: Date.now() })
-        if (!stale) {
-          setBranches(results)
-        }
-      })
-      .catch(() => {
-        if (!stale) {
-          setBranches([])
-        }
-      })
-      .finally(() => {
-        if (!stale) {
-          setBranchesLoading(false)
-        }
-      })
-    return () => {
-      stale = true
-    }
-  }, [subTab, selectedRepo, debouncedQuery])
-
-  // ---------------------------------------------------------------------
-  // Linear
-  // ---------------------------------------------------------------------
-  const [linearIssues, setLinearIssues] = useState<LinearIssue[]>([])
-  const [linearLoading, setLinearLoading] = useState(false)
-  const [linearError, setLinearError] = useState<string | null>(null)
-  useEffect(() => {
-    if (subTab !== 'linear' || !linearStatus.connected) {
-      return
-    }
-    let stale = false
-    setLinearLoading(true)
-    setLinearError(null)
-    const trimmed = debouncedQuery.trim()
-    const request = trimmed
-      ? searchLinearIssues(trimmed, LINEAR_LIST_LIMIT)
-      : listLinearIssues('assigned', LINEAR_LIST_LIMIT)
-    void request
-      .then((items) => {
-        if (!stale) {
-          setLinearIssues(items)
-          setLinearLoading(false)
-        }
-      })
-      .catch((err) => {
-        if (!stale) {
-          setLinearError(err instanceof Error ? err.message : 'Failed to load Linear issues.')
-          setLinearLoading(false)
-        }
-      })
-    return () => {
-      stale = true
-    }
-    // Why: list/search methods are stable store selectors; depending on them
-    // would re-run the effect on unrelated store updates.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [subTab, linearStatus.connected, debouncedQuery])
-
-  // ---------------------------------------------------------------------
-  // Selection handlers — each defers to launchWorkItemDirect / launchFromBranch
-  // and falls back to the Quick tab on policy=ask.
-  // ---------------------------------------------------------------------
-  // Why: a single in-flight token guards against double-clicks and tab
-  // switches racing with slow network calls (PR base-ref resolution can take
-  // multiple seconds on cold caches).
-  const inflightRef = useRef(0)
-  const [launching, setLaunching] = useState(false)
-  // Why: once the user selects a row the popover closes and the search input
-  // would otherwise fall back to the (often empty) query, making the field
-  // look blank while "Creating workspace…" shows below. Pin the selected
-  // row's label into the input for the duration of the launch so the user
-  // still sees what they picked.
-  const [selectedLabel, setSelectedLabel] = useState<string | null>(null)
-  const beginLaunch = useCallback((label: string) => {
-    setSelectedLabel(label)
-    setResultsOpen(false)
-  }, [])
-
-  const handlePrSelect = useCallback(
-    async (item: GitHubWorkItem) => {
-      if (!selectedRepo || item.type !== 'pr') {
-        return
-      }
-      const token = ++inflightRef.current
-      setLaunching(true)
-      beginLaunch(`#${item.number} ${item.title}`)
-      try {
-        const result = await window.api.worktrees.resolvePrBase({
-          repoId: selectedRepo.id,
-          prNumber: item.number,
-          ...(item.branchName ? { headRefName: item.branchName } : {}),
-          ...(item.isCrossRepository !== undefined
-            ? { isCrossRepository: item.isCrossRepository }
-            : {})
-        })
-        if (token !== inflightRef.current) {
-          return
-        }
-        if ('error' in result) {
-          // Why: failed head resolution still gives the user something to do —
-          // hand off to Quick with the linked PR so they can pick a different
-          // base branch manually instead of being stuck on this tab.
-          onFallbackToQuick({
-            initialRepoId: selectedRepo.id,
-            linkedWorkItem: {
-              type: 'pr',
-              number: item.number,
-              title: item.title,
-              url: item.url
-            },
-            prefilledName: item.title
-          })
-          return
-        }
-        await launchWorkItemDirect({
-          item: {
-            title: item.title,
-            url: item.url,
-            type: 'pr',
-            number: item.number
-          },
-          repoId: selectedRepo.id,
-          baseBranch: result.baseBranch,
-          openModalFallback: () =>
-            onFallbackToQuick({
-              initialRepoId: selectedRepo.id,
-              linkedWorkItem: {
-                type: 'pr',
-                number: item.number,
-                title: item.title,
-                url: item.url
-              },
-              prefilledName: item.title,
-              initialBaseBranch: result.baseBranch
-            })
-        })
-        if (token === inflightRef.current) {
-          onLaunched()
-        }
-      } finally {
-        if (token === inflightRef.current) {
-          setLaunching(false)
-          setSelectedLabel(null)
-        }
-      }
-    },
-    [beginLaunch, onFallbackToQuick, onLaunched, selectedRepo]
-  )
-
-  const handleIssueSelect = useCallback(
-    async (item: GitHubWorkItem) => {
-      if (!selectedRepo || item.type !== 'issue') {
-        return
-      }
-      const token = ++inflightRef.current
-      setLaunching(true)
-      beginLaunch(`#${item.number} ${item.title}`)
-      try {
-        await launchWorkItemDirect({
-          item: {
-            title: item.title,
-            url: item.url,
-            type: 'issue',
-            number: item.number
-          },
-          repoId: selectedRepo.id,
-          openModalFallback: () =>
-            onFallbackToQuick({
-              initialRepoId: selectedRepo.id,
-              linkedWorkItem: {
-                type: 'issue',
-                number: item.number,
-                title: item.title,
-                url: item.url
-              },
-              prefilledName: item.title
-            })
-        })
-        if (token === inflightRef.current) {
-          onLaunched()
-        }
-      } finally {
-        if (token === inflightRef.current) {
-          setLaunching(false)
-          setSelectedLabel(null)
-        }
-      }
-    },
-    [beginLaunch, onFallbackToQuick, onLaunched, selectedRepo]
-  )
-
-  const handleBranchSelect = useCallback(
-    async (refName: string) => {
-      if (!selectedRepo) {
-        return
-      }
-      const token = ++inflightRef.current
-      setLaunching(true)
-      beginLaunch(refName)
-      try {
-        await launchFromBranch({
-          repoId: selectedRepo.id,
-          baseBranch: refName,
-          openModalFallback: () => onFallbackToQuick({ initialRepoId: selectedRepo.id })
-        })
-        if (token === inflightRef.current) {
-          onLaunched()
-        }
-      } finally {
-        if (token === inflightRef.current) {
-          setLaunching(false)
-          setSelectedLabel(null)
-        }
-      }
-    },
-    [beginLaunch, onFallbackToQuick, onLaunched, selectedRepo]
-  )
-
-  const handleLinearSelect = useCallback(
-    async (issue: LinearIssue) => {
-      // Why: Linear issues aren't scoped to a git repo, so pick the active
-      // repo (or the first eligible) as a target for the worktree. Users can
-      // still override via the Quick tab fallback if setup policy is `ask`.
-      const repoForLaunch =
-        eligibleRepos.find((r) => r.id === selectedRepoId) ?? eligibleRepos[0] ?? null
-      if (!repoForLaunch) {
-        onFallbackToQuick({})
-        return
-      }
-      const token = ++inflightRef.current
-      setLaunching(true)
-      beginLaunch(`${issue.identifier} ${issue.title}`)
-      try {
-        const parts = [
-          `[${issue.identifier}] ${issue.title}`,
-          `Status: ${issue.state.name} · Team: ${issue.team.name}`,
-          issue.assignee ? `Assignee: ${issue.assignee.displayName}` : null,
-          issue.labels.length > 0 ? `Labels: ${issue.labels.join(', ')}` : null,
-          `URL: ${issue.url}`,
-          issue.description ? `\n${issue.description}` : null
-        ]
-        const pasteContent = parts.filter(Boolean).join('\n')
-        await launchWorkItemDirect({
-          item: {
-            title: issue.title,
-            url: issue.url,
-            type: 'issue',
-            number: null,
-            pasteContent,
-            linearIdentifier: issue.identifier
-          },
-          repoId: repoForLaunch.id,
-          openModalFallback: () =>
-            onFallbackToQuick({
-              initialRepoId: repoForLaunch.id,
-              linkedWorkItem: {
-                type: 'issue',
-                // Why: Linear identifiers are strings (e.g. "ENG-123") — use 0
-                // as a placeholder since the URL is what the agent acts on.
-                number: 0,
-                title: issue.title,
-                url: issue.url
-              },
-              prefilledName: issue.title
-            })
-        })
-        if (token === inflightRef.current) {
-          onLaunched()
-        }
-      } finally {
-        if (token === inflightRef.current) {
-          setLaunching(false)
-          setSelectedLabel(null)
-        }
-      }
-    },
-    [beginLaunch, eligibleRepos, onFallbackToQuick, onLaunched, selectedRepoId]
-  )
-
-  // ---------------------------------------------------------------------
-  // Render
-  // ---------------------------------------------------------------------
-  const visiblePrItems = useMemo(() => {
-    if (normalizedGhQuery.directNumber !== null) {
-      return directPr && directPr.type === 'pr' ? [directPr] : []
-    }
-    return prItems
-  }, [directPr, normalizedGhQuery.directNumber, prItems])
-  const visibleIssueItems = useMemo(() => {
-    if (normalizedGhQuery.directNumber !== null) {
-      return directPr && directPr.type === 'issue' ? [directPr] : []
-    }
-    return issueItems
-  }, [directPr, normalizedGhQuery.directNumber, issueItems])
-
-  const placeholderBySubTab: Record<CreateFromSubTab, string> = {
-    prs: 'Search PRs, paste #N or URL…',
-    issues: 'Search issues, paste #N or URL…',
-    branches: 'Search branches…',
-    linear: 'Search Linear issues…'
-  }
-
-  const showGhRepoPicker = subTab !== 'linear'
-
-  // Why: render the issue-source selector inline with the Issues sub-tab's
-  // search input so a user who lands on an upstream/origin mismatch can
-  // correct it in place instead of closing the modal, flipping from the
-  // Tasks page, and re-opening. Sources come from whatever `workItemsCache`
-  // entry exists for this repo (empty-query or a past search) — the per-repo
-  // `listWorkItems` envelope always stamps both `prs` and `upstreamCandidate`
-  // so we can re-use the same derived shape the Tasks header consumes.
-  // Subscribing through `getWorkItemsAnySourcesForRepo` (a selector that
-  // returns a stable reference for unchanged entries) keeps this cheap —
-  // unrelated cache writes don't re-render the tab.
-  const selectorSources = useAppStore((s) =>
-    selectedRepo?.path && !isRemoteRepo
-      ? s.getWorkItemsAnySourcesForRepo(selectedRepo.path, COMBINED_WORK_ITEM_LIMIT)
-      : null
-  )
-  const selectorOrigin = selectorSources?.prs ?? null
-  const selectorUpstream = selectorSources?.upstreamCandidate ?? null
-  const selectorRenderable =
-    subTab === 'issues' &&
-    !!selectorOrigin &&
-    !!selectorUpstream &&
-    !sameGitHubOwnerRepo(selectorOrigin, selectorUpstream)
-
-  // Why: each row gets a stable, unique `value` so cmdk's keyboard
-  // navigation can track selection across sub-tab changes. Values also
-  // feed the controlled `commandValue` state below.
-  type RowEntry =
-    | { kind: 'pr'; value: string; item: GitHubWorkItem }
-    | { kind: 'issue'; value: string; item: GitHubWorkItem }
-    | { kind: 'branch'; value: string; refName: string }
-    | { kind: 'linear'; value: string; issue: LinearIssue }
-
-  type ResultState =
-    | { kind: 'empty'; message: React.ReactNode }
-    | { kind: 'loading' }
-    | { kind: 'rows'; rows: RowEntry[] }
-
-  const resultState = useMemo<ResultState>(() => {
-    if (subTab === 'prs') {
-      if (isRemoteRepo) {
-        return { kind: 'empty', message: "PR start points aren't supported for remote repos yet." }
-      }
-      if (prError) {
-        return {
-          kind: 'empty',
-          message: prError.includes('gh') ? 'gh not available — Branches tab still works' : prError
-        }
-      }
-      if ((prLoading || directLoading) && visiblePrItems.length === 0) {
-        return { kind: 'loading' }
-      }
-      if (visiblePrItems.length === 0) {
-        return {
-          kind: 'empty',
-          message:
-            normalizedGhQuery.directNumber !== null
-              ? `No PR #${normalizedGhQuery.directNumber}`
-              : 'No open PRs'
-        }
-      }
-      return {
-        kind: 'rows',
-        rows: visiblePrItems.map((item) => ({
-          kind: 'pr' as const,
-          value: `pr-${item.number}`,
-          item
-        }))
-      }
-    }
-    if (subTab === 'issues') {
-      if (isRemoteRepo) {
-        return {
-          kind: 'empty',
-          message: "Issue start points aren't supported for remote repos yet."
-        }
-      }
-      if (issueError) {
-        return {
-          kind: 'empty',
-          message: issueError.includes('gh')
-            ? 'gh not available — Branches tab still works'
-            : issueError
-        }
-      }
-      if ((issueLoading || directLoading) && visibleIssueItems.length === 0) {
-        return { kind: 'loading' }
-      }
-      if (visibleIssueItems.length === 0) {
-        return {
-          kind: 'empty',
-          message:
-            normalizedGhQuery.directNumber !== null
-              ? `No issue #${normalizedGhQuery.directNumber}`
-              : 'No open issues'
-        }
-      }
-      return {
-        kind: 'rows',
-        rows: visibleIssueItems.map((item) => ({
-          kind: 'issue' as const,
-          value: `issue-${item.number}`,
-          item
-        }))
-      }
-    }
-    if (subTab === 'branches') {
-      if (branchesLoading && branches.length === 0) {
-        return { kind: 'loading' }
-      }
-      if (branches.length === 0) {
-        return {
-          kind: 'empty',
-          message: query.trim() ? 'No branches match' : 'No branches found'
-        }
-      }
-      return {
-        kind: 'rows',
-        rows: branches.map((refName) => ({
-          kind: 'branch' as const,
-          value: `branch-${refName}`,
-          refName
-        }))
-      }
-    }
-    // linear
-    if (!linearStatus.connected) {
-      return {
-        kind: 'empty',
-        message:
-          'Connect Linear from Settings → Integrations to create workspaces from Linear issues.'
-      }
-    }
-    if (linearError) {
-      return { kind: 'empty', message: linearError }
-    }
-    if (linearLoading && linearIssues.length === 0) {
-      return { kind: 'loading' }
-    }
-    if (linearIssues.length === 0) {
-      return {
-        kind: 'empty',
-        message: query.trim() ? 'No Linear issues match' : 'No Linear issues assigned to you'
-      }
-    }
-    return {
-      kind: 'rows',
-      rows: linearIssues.map((issue) => ({
-        kind: 'linear' as const,
-        value: `linear-${issue.id}`,
-        issue
-      }))
-    }
-  }, [
-    branches,
-    branchesLoading,
-    directLoading,
-    isRemoteRepo,
-    issueError,
-    issueLoading,
-    linearError,
-    linearIssues,
-    linearLoading,
-    linearStatus.connected,
-    normalizedGhQuery.directNumber,
-    prError,
-    prLoading,
-    query,
-    subTab,
-    visibleIssueItems,
-    visiblePrItems
-  ])
-
-  const handleRowSelect = useCallback(
-    (row: RowEntry) => {
-      if (row.kind === 'pr') {
-        void handlePrSelect(row.item)
-      } else if (row.kind === 'issue') {
-        void handleIssueSelect(row.item)
-      } else if (row.kind === 'branch') {
-        void handleBranchSelect(row.refName)
-      } else {
-        void handleLinearSelect(row.issue)
-      }
-    },
-    [handleBranchSelect, handleIssueSelect, handleLinearSelect, handlePrSelect]
-  )
-
-  // Why: cmdk tracks the highlighted row via a controlled `value`. We
-  // seed it to the first row on list change so Enter works immediately
-  // and the top row has the visible selected style — matching every
-  // shadcn combobox flow.
-  const [commandValue, setCommandValue] = useState<string>('')
-  useEffect(() => {
-    if (resultState.kind === 'rows' && resultState.rows.length > 0) {
-      setCommandValue((prev) =>
-        resultState.rows.some((r) => r.value === prev) ? prev : resultState.rows[0].value
-      )
-    }
-  }, [resultState])
-
-  return (
-    <div className="flex flex-col gap-3">
-      {/* Why: give the Repository selector a stable row above the tabs so
-          switching to Linear (which hides the picker) doesn't rearrange the
-          sub-tab row, and the sub-tabs get the full width for themselves.
-          Matches the field-label style used on the Quick tab so the two
-          surfaces feel like the same form dialect.
-
-          The grid-template-rows 0fr↔1fr trick animates the picker's
-          collapse/expand smoothly when the user moves between Linear (no
-          repo picker) and GH sub-tabs. We keep the DOM mounted across the
-          transition so focus/state inside the combobox survives, and clip
-          the overflow so the shrinking row never peeks past the borders. */}
-      <div
-        className={cn(
-          'grid transition-[grid-template-rows,opacity,margin] duration-200 ease-out',
-          showGhRepoPicker ? 'grid-rows-[1fr] opacity-100' : '-mt-3 grid-rows-[0fr] opacity-0'
-        )}
-        aria-hidden={!showGhRepoPicker}
-      >
-        <div className="min-h-0 overflow-hidden">
-          <div className="space-y-1">
-            <label className="text-xs font-medium text-muted-foreground">Repository</label>
-            <RepoCombobox
-              repos={eligibleRepos}
-              value={selectedRepoId}
-              onValueChange={setSelectedRepoId}
-              placeholder="Repository"
-              triggerClassName="h-8 w-full border-input text-xs"
-              showStandaloneAddButton={false}
-            />
-          </div>
-        </div>
-      </div>
-
-      <Tabs
-        value={subTab}
-        onValueChange={(v) => setSubTab(v as CreateFromSubTab)}
-        className="gap-0"
-      >
-        <TabsList
-          ref={subTabsListRef}
-          variant="line"
-          className="h-8 w-full justify-start gap-5 border-b border-border/40 px-0"
-        >
-          {SUB_TABS.map(({ id, label, Icon }) => (
-            <TabsTrigger key={id} value={id} className="flex-none gap-1.5 px-0 text-xs">
-              <Icon className="size-3.5" />
-              {label}
-            </TabsTrigger>
-          ))}
-        </TabsList>
-
-        <div className="pt-3">
-          <Popover open={resultsOpen} onOpenChange={setResultsOpen}>
-            <Command
-              value={commandValue}
-              onValueChange={setCommandValue}
-              shouldFilter={false}
-              // Why: cmdk listens on its root for keyboard nav. Leaving
-              // its wrapper as a flex column keeps the input + popover
-              // rendering in their natural positions while cmdk still
-              // sees the input + list as one logical tree, so arrow
-              // keys move the highlighted row and Enter selects it.
-              className="overflow-visible bg-transparent"
-            >
-              <PopoverAnchor asChild>
-                <div className="relative">
-                  {launching ? (
-                    <LoaderCircle className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 animate-spin text-muted-foreground" />
-                  ) : (
-                    <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
-                  )}
-                  <Input
-                    ref={searchInputRef}
-                    // Why: once a row is chosen we pin its label into the input
-                    // so the user still sees what they selected while the
-                    // launch runs. `readOnly` + aria-busy lets keystrokes still
-                    // blur/focus without the text being editable mid-launch.
-                    value={selectedLabel ?? query}
-                    readOnly={launching}
-                    aria-busy={launching}
-                    onChange={(e) => {
-                      if (launching) {
-                        return
-                      }
-                      setQuery(e.target.value)
-                      setResultsOpen(true)
-                    }}
-                    onFocus={() => {
-                      if (!launching) {
-                        setResultsOpen(true)
-                      }
-                    }}
-                    onKeyDown={(e) => {
-                      if (launching) {
-                        return
-                      }
-                      if (e.key === 'Escape' && resultsOpen) {
-                        // Why: first Escape dismisses the suggestions; only
-                        // if the popover is already closed should Escape
-                        // bubble up to close the dialog.
-                        e.stopPropagation()
-                        setResultsOpen(false)
-                        return
-                      }
-                      if (
-                        e.key === 'ArrowDown' ||
-                        e.key === 'ArrowUp' ||
-                        e.key === 'Home' ||
-                        e.key === 'End'
-                      ) {
-                        if (!resultsOpen) {
-                          setResultsOpen(true)
-                        }
-                        // Why: cmdk handles arrow/Home/End on its root via
-                        // its own listener. The event reaching here already
-                        // got processed; just make sure the popover is open
-                        // so the user sees the movement.
-                      }
-                      if (e.key === 'Enter' && resultsOpen && resultState.kind === 'rows') {
-                        const row = resultState.rows.find((r) => r.value === commandValue)
-                        if (row) {
-                          e.preventDefault()
-                          handleRowSelect(row)
-                        }
-                      }
-                    }}
-                    placeholder={placeholderBySubTab[subTab]}
-                    className={cn(
-                      'h-9 pl-8 text-sm',
-                      // Why: reserve trailing space for the absolute-positioned
-                      // IssueSourceSelector so typed text never slides under
-                      // the pills. Only widen the padding when the selector
-                      // is actually rendered.
-                      selectorRenderable && !launching ? 'pr-[140px]' : ''
-                    )}
-                  />
-                  {selectorRenderable && selectedRepo && !launching ? (
-                    // Why: right-aligned inside the input so the selector
-                    // stays visually attached to the surface whose contents
-                    // it controls. `pointer-events-auto` is needed because
-                    // the sibling Search/Loader icons set
-                    // `pointer-events-none` on the absolute-positioned layer
-                    // — we override that for the clickable pills.
-                    // `suppressTooltip`: the selector is only visible on the
-                    // Issues sub-tab, so "Showing issues from X" restates
-                    // what's already implied (same reasoning as the Create
-                    // Issue composer mirror in TaskPage).
-                    <div
-                      className="pointer-events-auto absolute right-2 top-1/2 -translate-y-[calc(50%+2px)]"
-                      onMouseDown={(e) => {
-                        // Why: clicking a pill would otherwise blur the input
-                        // and close the results popover before the click
-                        // lands on the button. Blocking the default focus
-                        // shift keeps the popover open across a flip so the
-                        // user sees the list repopulate against the new
-                        // source without re-clicking the input.
-                        e.preventDefault()
-                      }}
-                    >
-                      <IssueSourceSelector
-                        preference={selectedRepo.issueSourcePreference}
-                        origin={selectorOrigin}
-                        upstream={selectorUpstream}
-                        onChange={(next) => {
-                          void setIssueSourcePreference(selectedRepo.id, selectedRepo.path, next)
-                        }}
-                        suppressTooltip
-                      />
-                    </div>
-                  ) : null}
-                </div>
-              </PopoverAnchor>
-              <PopoverContent
-                align="start"
-                sideOffset={4}
-                // Why: match the anchor width so results feel "attached"
-                // to the input. `--radix-popover-content-available-height`
-                // is Radix's dynamic measurement of free space on the
-                // chosen side (capped by the viewport); clamping the
-                // popover max-height to it lets the list grow as tall as
-                // it can without spilling outside the viewport whether
-                // the popover opens downward or flips upward.
-                //
-                // `popover-scroll-content` pairs with the wheel-event
-                // handler on PopoverContent so wheel scroll works even
-                // though Radix Dialog applies react-remove-scroll to
-                // everything outside its own subtree. The CommandList
-                // child uses h-full + overflow-y-auto so it owns the
-                // scroll region — nesting it this way means the
-                // shadcn-style `scrollbar-sleek` track lives inside the
-                // popover's rounded border.
-                className="popover-scroll-content flex w-[var(--radix-popover-trigger-width)] flex-col p-0"
-                style={{
-                  maxHeight: 'min(var(--radix-popover-content-available-height,22rem),22rem)'
-                }}
-                onOpenAutoFocus={(event) => {
-                  // Why: the input keeps focus so typing continues to
-                  // filter results. Without preventDefault the popover
-                  // would pull focus to its first child on open.
-                  event.preventDefault()
-                }}
-                onPointerDownOutside={(event) => {
-                  // Why: the search input is the popover's anchor (not its
-                  // trigger), so Radix treats clicks on it as "outside" and
-                  // would close the popover. Sub-tab triggers are also
-                  // outside — clicking them should just switch source and
-                  // keep results visible rather than dismissing the list.
-                  const target = event.target as Node
-                  if (
-                    searchInputRef.current?.contains(target) ||
-                    subTabsListRef.current?.contains(target)
-                  ) {
-                    event.preventDefault()
-                  }
-                }}
-                onFocusOutside={(event) => {
-                  // Why: sub-tab clicks move focus to a tab trigger and we
-                  // refocus the search input on the next frame. Both of
-                  // those focus destinations are "outside" the popover
-                  // content — if we don't suppress them Radix dismisses the
-                  // list and the user has to click the input again to see
-                  // the new sub-tab's results.
-                  const target = event.target as Node
-                  if (
-                    searchInputRef.current?.contains(target) ||
-                    subTabsListRef.current?.contains(target)
-                  ) {
-                    event.preventDefault()
-                  }
-                }}
-              >
-                <CommandList className="!max-h-none min-h-0 flex-1 scrollbar-sleek">
-                  {resultState.kind === 'loading' ? (
-                    <LoadingRows />
-                  ) : resultState.kind === 'empty' ? (
-                    <EmptyMessage>{resultState.message}</EmptyMessage>
-                  ) : (
-                    <CommandGroup className="p-1">
-                      {resultState.rows.map((row) => (
-                        <CommandItem
-                          key={row.value}
-                          value={row.value}
-                          onSelect={() => handleRowSelect(row)}
-                          disabled={launching}
-                          className="group gap-2 px-2 py-1.5 text-xs data-[disabled=true]:opacity-60"
-                        >
-                          {row.kind === 'pr' ? (
-                            <PrItemContent item={row.item} />
-                          ) : row.kind === 'issue' ? (
-                            <IssueItemContent item={row.item} />
-                          ) : row.kind === 'branch' ? (
-                            <BranchItemContent refName={row.refName} />
-                          ) : (
-                            <LinearItemContent issue={row.issue} />
-                          )}
-                          <CornerDownLeft className="ml-auto size-3 shrink-0 text-muted-foreground opacity-0 group-data-[selected=true]:opacity-100" />
-                        </CommandItem>
-                      ))}
-                    </CommandGroup>
-                  )}
-                </CommandList>
-              </PopoverContent>
-            </Command>
-          </Popover>
-        </div>
-      </Tabs>
-
-      {launching ? (
-        <div className="flex items-center gap-2 px-1 pt-1 text-[11px] text-muted-foreground">
-          <LoaderCircle className="size-3 animate-spin" />
-          Creating workspace…
-        </div>
-      ) : null}
-    </div>
-  )
-}
-
-function LoadingRows(): React.JSX.Element {
-  return (
-    <div className="space-y-1 p-1">
-      {[0, 1, 2, 3].map((i) => (
-        <div key={i} className="h-8 animate-pulse rounded bg-muted/40" />
-      ))}
-    </div>
-  )
-}
-
-function EmptyMessage({ children }: { children: React.ReactNode }): React.JSX.Element {
-  return <div className="px-6 py-6 text-center text-xs text-muted-foreground">{children}</div>
-}
-
-function PrItemContent({ item }: { item: GitHubWorkItem }): React.JSX.Element {
-  const isFork = item.isCrossRepository === true
-  return (
-    <>
-      <GitPullRequest className="size-3.5 shrink-0 text-emerald-600 dark:text-emerald-400" />
-      <span className="min-w-0 flex-1">
-        <span className="flex items-center gap-1.5">
-          <span className="text-muted-foreground">#{item.number}</span>
-          <span className="truncate">{item.title}</span>
-        </span>
-        {item.branchName ? (
-          <span className="mt-0.5 block truncate font-mono text-[10px] text-muted-foreground">
-            {item.branchName}
-            {isFork ? ' · fork' : ''}
-          </span>
-        ) : null}
-      </span>
-    </>
-  )
-}
-
-function IssueItemContent({ item }: { item: GitHubWorkItem }): React.JSX.Element {
-  return (
-    <>
-      <CircleDot className="size-3.5 shrink-0 text-emerald-600 dark:text-emerald-400" />
-      <span className="min-w-0 flex-1">
-        <span className="flex items-center gap-1.5">
-          <span className="text-muted-foreground">#{item.number}</span>
-          <span className="truncate">{item.title}</span>
-        </span>
-        {item.author ? (
-          <span className="mt-0.5 block truncate text-[10px] text-muted-foreground">
-            {item.author}
-          </span>
-        ) : null}
-      </span>
-    </>
-  )
-}
-
-function BranchItemContent({ refName }: { refName: string }): React.JSX.Element {
-  return (
-    <>
-      <GitBranch className="size-3.5 shrink-0 text-muted-foreground" />
-      <span className="truncate font-mono">{refName}</span>
-    </>
-  )
-}
-
-function LinearItemContent({ issue }: { issue: LinearIssue }): React.JSX.Element {
-  return (
-    <>
-      <span className="shrink-0 font-mono text-[10px] text-muted-foreground">
-        {issue.identifier}
-      </span>
-      <span className="min-w-0 flex-1">
-        <span className="truncate">{issue.title}</span>
-        <span className="mt-0.5 block truncate text-[10px] text-muted-foreground">
-          {issue.state.name}
-          {issue.team.name ? ` · ${issue.team.name}` : ''}
-        </span>
-      </span>
-    </>
-  )
-}
diff --git a/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
new file mode 100644
index 00000000000..4d6087416a5
--- /dev/null
+++ b/src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
@@ -0,0 +1,995 @@
+/* eslint-disable max-lines -- Why: the smart name field owns source tabs,
+search orchestration, and result rendering so the unified create flow stays
+in one predictable form control instead of splitting state across fragments. */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  CaseSensitive,
+  CircleDot,
+  ExternalLink,
+  GitBranch,
+  GitBranchPlus,
+  GitPullRequest,
+  Github,
+  LoaderCircle,
+  Search,
+  Sparkles,
+  X
+} from 'lucide-react'
+import { useShallow } from 'zustand/react/shallow'
+import { Command, CommandGroup, CommandItem, CommandList } from '@/components/ui/command'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '@/components/ui/dialog'
+import { Input } from '@/components/ui/input'
+import { Popover, PopoverAnchor, PopoverContent } from '@/components/ui/popover'
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { useAppStore } from '@/store'
+import {
+  normalizeGitHubLinkQuery,
+  parseGitHubIssueOrPRLink,
+  type RepoSlug
+} from '@/lib/github-links'
+import { cn } from '@/lib/utils'
+import type { GitHubWorkItem, LinearIssue } from '../../../../shared/types'
+
+type SmartNameMode = 'smart' | 'github' | 'branches' | 'linear' | 'text'
+
+type RepoOption = ReturnType<typeof useAppStore.getState>['repos'][number]
+
+type SmartWorkspaceNameFieldProps = {
+  repos: RepoOption[]
+  repoId: string
+  onRepoChange: (repoId: string) => void
+  value: string
+  onValueChange: (value: string) => void
+  onGitHubItemSelect: (item: GitHubWorkItem) => void
+  onBranchSelect: (refName: string) => void
+  onLinearIssueSelect: (issue: LinearIssue) => void
+  selectedSource: SmartWorkspaceNameSelection | null
+  onClearSelectedSource: () => void
+  inputRef?: React.RefObject<HTMLInputElement | null>
+  onPlainEnter?: () => void
+}
+
+export type SmartWorkspaceNameSelection = {
+  kind: 'github-pr' | 'github-issue' | 'branch' | 'linear'
+  label: string
+  url?: string
+}
+
+const SEARCH_DEBOUNCE_MS = 200
+const RESULT_LIMIT = 12
+
+const MODES: {
+  id: SmartNameMode
+  label: string
+  Icon: React.ComponentType<{ className?: string }>
+}[] = [
+  { id: 'smart', label: 'Smart', Icon: Sparkles },
+  { id: 'github', label: 'GitHub', Icon: Github },
+  { id: 'branches', label: 'Branch', Icon: GitBranch },
+  {
+    id: 'linear',
+    label: 'Linear',
+    Icon: ({ className }: { className?: string }) => (
+      <svg viewBox="0 0 24 24" aria-hidden className={className} fill="currentColor">
+        <path d="M2.886 4.18A11.982 11.982 0 0 1 11.99 0C18.624 0 24 5.376 24 12.009c0 3.64-1.62 6.903-4.18 9.105L2.887 4.18ZM1.817 5.626l16.556 16.556c-.524.33-1.075.62-1.65.866L.951 7.277c.247-.575.537-1.126.866-1.65ZM.322 9.163l14.515 14.515c-.71.172-1.443.282-2.195.322L0 11.358a12 12 0 0 1 .322-2.195Zm-.17 4.862 9.823 9.824a12.02 12.02 0 0 1-9.824-9.824Z" />
+      </svg>
+    )
+  },
+  { id: 'text', label: 'Name', Icon: CaseSensitive }
+]
+
+const emptyHintByMode: Record<SmartNameMode, string> = {
+  smart: 'Start typing to create a name or find a source.',
+  github: 'Start typing to search GitHub PRs and issues.',
+  branches: 'Start typing to find a branch or create a new one.',
+  linear: 'Start typing to search Linear issues.',
+  text: ''
+}
+
+type RowEntry =
+  | { kind: 'use-name'; value: string; name: string }
+  | { kind: 'create-branch'; value: string; name: string }
+  | { kind: 'github'; value: string; item: GitHubWorkItem }
+  | { kind: 'branch'; value: string; refName: string }
+  | { kind: 'linear'; value: string; issue: LinearIssue }
+
+export default function SmartWorkspaceNameField({
+  repos,
+  repoId,
+  onRepoChange,
+  value,
+  onValueChange,
+  onGitHubItemSelect,
+  onBranchSelect,
+  onLinearIssueSelect,
+  selectedSource,
+  onClearSelectedSource,
+  inputRef,
+  onPlainEnter
+}: SmartWorkspaceNameFieldProps): React.JSX.Element {
+  const {
+    addRepo,
+    checkLinearConnection,
+    fetchWorkItems,
+    getCachedWorkItems,
+    linearStatus,
+    linearStatusChecked,
+    listLinearIssues,
+    searchLinearIssues
+  } = useAppStore(
+    useShallow((s) => ({
+      addRepo: s.addRepo,
+      checkLinearConnection: s.checkLinearConnection,
+      fetchWorkItems: s.fetchWorkItems,
+      getCachedWorkItems: s.getCachedWorkItems,
+      linearStatus: s.linearStatus,
+      linearStatusChecked: s.linearStatusChecked,
+      listLinearIssues: s.listLinearIssues,
+      searchLinearIssues: s.searchLinearIssues
+    }))
+  )
+
+  const selectedRepo = useMemo(
+    () => repos.find((repo) => repo.id === repoId) ?? null,
+    [repoId, repos]
+  )
+  const [mode, setMode] = useState<SmartNameMode>('smart')
+  const [open, setOpen] = useState(false)
+  const [debouncedQuery, setDebouncedQuery] = useState(value)
+  const [githubItems, setGithubItems] = useState<GitHubWorkItem[]>([])
+  const [branches, setBranches] = useState<string[]>([])
+  const [linearIssues, setLinearIssues] = useState<LinearIssue[]>([])
+  const [githubLoading, setGithubLoading] = useState(false)
+  const [branchesLoading, setBranchesLoading] = useState(false)
+  const [linearLoading, setLinearLoading] = useState(false)
+  const [commandValue, setCommandValue] = useState('')
+  const localInputRef = useRef<HTMLInputElement | null>(null)
+  const tabsListRef = useRef<HTMLDivElement | null>(null)
+  const repoSlugCacheRef = useRef<Map<string, RepoSlug | null>>(new Map())
+  const handledCrossRepoUrlRef = useRef<string | null>(null)
+  const [crossRepoPrompt, setCrossRepoPrompt] = useState<{
+    link: NonNullable<ReturnType<typeof parseGitHubIssueOrPRLink>>
+    matchingRepo: RepoOption | null
+  } | null>(null)
+
+  const setInputNode = useCallback(
+    (node: HTMLInputElement | null) => {
+      localInputRef.current = node
+      if (inputRef) {
+        inputRef.current = node
+      }
+    },
+    [inputRef]
+  )
+
+  useEffect(() => {
+    // Why: the composer can be opened before any other Linear-aware surface
+    // (TaskPage, IntegrationsPane) has had a chance to refresh status, leaving
+    // `linearStatus.connected=false` even when the user is actually connected.
+    // Trigger a check on mount if it hasn't run this session.
+    if (!linearStatusChecked) {
+      void checkLinearConnection()
+    }
+  }, [checkLinearConnection, linearStatusChecked])
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => setDebouncedQuery(value), SEARCH_DEBOUNCE_MS)
+    return () => window.clearTimeout(timer)
+  }, [value])
+
+  useEffect(() => {
+    if (selectedSource) {
+      setOpen(false)
+    }
+  }, [selectedSource])
+
+  const normalizedGhQuery = useMemo(
+    () => normalizeGitHubLinkQuery(debouncedQuery),
+    [debouncedQuery]
+  )
+  const parsedGhLink = useMemo(() => parseGitHubIssueOrPRLink(debouncedQuery), [debouncedQuery])
+  const shouldQueryGithub = mode === 'smart' || mode === 'github'
+  const shouldQueryBranches = mode === 'smart' || mode === 'branches'
+  const shouldQueryLinear = mode === 'smart' || mode === 'linear'
+
+  useEffect(() => {
+    if (!shouldQueryGithub || !selectedRepo?.path || selectedRepo.connectionId) {
+      setGithubItems([])
+      setGithubLoading(false)
+      return
+    }
+    let stale = false
+    const directNumber = normalizedGhQuery.directNumber
+    const directLink = parsedGhLink
+    if (directLink !== null && handledCrossRepoUrlRef.current !== debouncedQuery.trim()) {
+      setGithubLoading(true)
+      void getRepoSlugCached(selectedRepo, repoSlugCacheRef.current)
+        .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
+            })
+            if (!stale) {
+              setGithubItems(item ? [{ ...item, repoId: selectedRepo.id } as GitHubWorkItem] : [])
+            }
+            return
+          }
+          const matchingRepo = await findMatchingRepoForSlug(
+            repos,
+            directLink.slug,
+            repoSlugCacheRef.current
+          )
+          if (!stale) {
+            setGithubItems([])
+            setOpen(false)
+            setCrossRepoPrompt({ link: directLink, matchingRepo })
+          }
+        })
+        .finally(() => {
+          if (!stale) {
+            setGithubLoading(false)
+          }
+        })
+      return () => {
+        stale = true
+      }
+    }
+    if (directNumber !== null) {
+      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 })
+      void request
+        .then((item) => {
+          if (!stale) {
+            setGithubItems(item ? [{ ...item, repoId: selectedRepo.id } as GitHubWorkItem] : [])
+          }
+        })
+        .catch(() => {
+          if (!stale) {
+            setGithubItems([])
+          }
+        })
+        .finally(() => {
+          if (!stale) {
+            setGithubLoading(false)
+          }
+        })
+      return () => {
+        stale = true
+      }
+    }
+
+    const trimmed = normalizedGhQuery.query.trim()
+    const query = trimmed ? normalizedGhQuery.query : ''
+    const cached = getCachedWorkItems(selectedRepo.path, RESULT_LIMIT, query)
+    if (cached) {
+      setGithubItems(cached.slice(0, RESULT_LIMIT))
+      setGithubLoading(false)
+    } else {
+      setGithubLoading(true)
+    }
+    void fetchWorkItems(selectedRepo.id, selectedRepo.path, RESULT_LIMIT, query)
+      .then((items) => {
+        if (!stale) {
+          setGithubItems(items.slice(0, RESULT_LIMIT))
+        }
+      })
+      .catch(() => {
+        if (!stale) {
+          setGithubItems([])
+        }
+      })
+      .finally(() => {
+        if (!stale) {
+          setGithubLoading(false)
+        }
+      })
+    return () => {
+      stale = true
+    }
+  }, [
+    debouncedQuery,
+    fetchWorkItems,
+    getCachedWorkItems,
+    normalizedGhQuery,
+    parsedGhLink,
+    repos,
+    selectedRepo,
+    shouldQueryGithub
+  ])
+
+  useEffect(() => {
+    if (!shouldQueryBranches || !selectedRepo) {
+      setBranches([])
+      setBranchesLoading(false)
+      return
+    }
+    let stale = false
+    setBranchesLoading(true)
+    void window.api.repos
+      .searchBaseRefs({
+        repoId: selectedRepo.id,
+        query: debouncedQuery.trim(),
+        limit: RESULT_LIMIT
+      })
+      .then((results) => {
+        if (!stale) {
+          setBranches(results)
+        }
+      })
+      .catch(() => {
+        if (!stale) {
+          setBranches([])
+        }
+      })
+      .finally(() => {
+        if (!stale) {
+          setBranchesLoading(false)
+        }
+      })
+    return () => {
+      stale = true
+    }
+  }, [debouncedQuery, selectedRepo, shouldQueryBranches])
+
+  useEffect(() => {
+    if (!shouldQueryLinear || !linearStatus.connected) {
+      setLinearIssues([])
+      setLinearLoading(false)
+      return
+    }
+    let stale = false
+    setLinearLoading(true)
+    const trimmed = debouncedQuery.trim()
+    const request = trimmed
+      ? searchLinearIssues(trimmed, RESULT_LIMIT)
+      : listLinearIssues('assigned', RESULT_LIMIT)
+    void request
+      .then((issues) => {
+        if (!stale) {
+          setLinearIssues(issues)
+        }
+      })
+      .catch(() => {
+        if (!stale) {
+          setLinearIssues([])
+        }
+      })
+      .finally(() => {
+        if (!stale) {
+          setLinearLoading(false)
+        }
+      })
+    return () => {
+      stale = true
+    }
+    // Why: list/search actions are stable store methods; depending on them
+    // would refetch on unrelated store writes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [debouncedQuery, linearStatus.connected, shouldQueryLinear])
+
+  const rows = useMemo<RowEntry[]>(() => {
+    const trimmed = value.trim()
+    // Why: on the Branches tab the generic "Use … as workspace name" row
+    // reads as off-topic — the user is picking/creating a branch. Swap it
+    // for a branch-creation row that's pinned above existing-branch results
+    // (suppressed when an existing branch matches exactly so we don't offer
+    // to "create" something that already exists).
+    const branchExactMatch = mode === 'branches' && trimmed.length > 0 && branches.includes(trimmed)
+    // Why: the "Use … as workspace name" row only makes sense in Smart
+    // mode, where the user might be typing a free-form name. On dedicated
+    // source tabs (GitHub/Linear/Branches) it's off-topic — the user is
+    // there to pick (or, on Branches, create) a source.
+    const useNameRow: RowEntry | null =
+      trimmed && mode === 'smart'
+        ? { kind: 'use-name', value: `use-name-${trimmed}`, name: trimmed }
+        : null
+    const createBranchRow: RowEntry | null =
+      trimmed && mode === 'branches' && !branchExactMatch
+        ? { kind: 'create-branch', value: `create-branch-${trimmed}`, name: trimmed }
+        : null
+    const nextRows: RowEntry[] = []
+    if (useNameRow) {
+      nextRows.push(useNameRow)
+    }
+    if (mode === 'text') {
+      return nextRows
+    }
+    if (mode === 'smart' || mode === 'github') {
+      nextRows.push(
+        ...githubItems.map((item) => ({
+          kind: 'github' as const,
+          value: `github-${item.type}-${item.number}`,
+          item
+        }))
+      )
+    }
+    if (mode === 'smart' || mode === 'branches') {
+      if (createBranchRow) {
+        nextRows.push(createBranchRow)
+      }
+      nextRows.push(
+        ...branches.map((refName) => ({
+          kind: 'branch' as const,
+          value: `branch-${refName}`,
+          refName
+        }))
+      )
+    }
+    if (mode === 'smart' || mode === 'linear') {
+      nextRows.push(
+        ...linearIssues.map((issue) => ({
+          kind: 'linear' as const,
+          value: `linear-${issue.id}`,
+          issue
+        }))
+      )
+    }
+    return nextRows.slice(0, RESULT_LIMIT + 1)
+  }, [branches, githubItems, linearIssues, mode, value])
+
+  // Why: source rows (GitHub/branches/Linear) are driven by debouncedQuery,
+  // so they're stale until the user pauses typing for SEARCH_DEBOUNCE_MS.
+  // We don't want to filter them out (causes flicker as results appear and
+  // disappear with each keystroke), but we do need to prevent cmdk's Enter
+  // handler from auto-selecting a stale source row. Two cases:
+  //   - Smart/Branches: a typed-text row (use-name / create-branch) exists
+  //     and is pinned at the top — force the highlight onto it so Enter
+  //     commits the typed text instead of a stale issue/PR/branch.
+  //   - GitHub/Linear: no typed-text fallback row, so clear the highlight
+  //     entirely; the input's Enter handler falls through to onPlainEnter.
+  const isQueryStale = value.trim().length > 0 && debouncedQuery.trim() !== value.trim()
+
+  // Why: when the typed value is unambiguously a source reference — a
+  // GitHub issue/PR shorthand ("#1234"), a github.com issue/pull URL, or a
+  // Linear identifier ("STA-123") — the user is clearly looking up that
+  // specific source rather than naming a workspace. Once a matching row
+  // appears in the results, snap the highlight onto it so Enter picks it
+  // instead of the typed-text fallback.
+  const sourceIntent = useMemo<'github' | 'linear' | null>(() => {
+    const trimmed = value.trim()
+    if (!trimmed) {
+      return null
+    }
+    if (/^#\d+$/.test(trimmed) || parseGitHubIssueOrPRLink(trimmed) !== null) {
+      return 'github'
+    }
+    if (/^[A-Za-z][A-Za-z0-9_]*-\d+$/.test(trimmed)) {
+      return 'linear'
+    }
+    return null
+  }, [value])
+
+  useEffect(() => {
+    if (rows.length === 0) {
+      return
+    }
+    if (isQueryStale) {
+      const typedTextRow = rows.find(
+        (row) => row.kind === 'use-name' || row.kind === 'create-branch'
+      )
+      // No typed-text fallback in this mode (GitHub/Linear): clear the
+      // highlight so cmdk doesn't auto-select a stale source on Enter.
+      setCommandValue(typedTextRow ? typedTextRow.value : '')
+      return
+    }
+    if (sourceIntent === 'github') {
+      const githubRow = rows.find((row) => row.kind === 'github')
+      if (githubRow) {
+        setCommandValue(githubRow.value)
+        return
+      }
+    } else if (sourceIntent === 'linear') {
+      const linearRow = rows.find((row) => row.kind === 'linear')
+      if (linearRow) {
+        setCommandValue(linearRow.value)
+        return
+      }
+    }
+    setCommandValue((current) =>
+      rows.some((row) => row.value === current) ? current : rows[0].value
+    )
+  }, [isQueryStale, rows, sourceIntent])
+
+  const loading = githubLoading || branchesLoading || linearLoading
+  const ActiveInputIcon = mode === 'text' ? CaseSensitive : loading ? LoaderCircle : Search
+
+  const handleSelect = useCallback(
+    (row: RowEntry) => {
+      if (row.kind === 'use-name' || row.kind === 'create-branch') {
+        // Why: "create new branch" has no existing ref to base from, so
+        // it follows the same path as a typed name — the workspace's branch
+        // is derived from `name` and `baseBranch` stays unset (default base).
+        onValueChange(row.name)
+      } else if (row.kind === 'github') {
+        onGitHubItemSelect(row.item)
+      } else if (row.kind === 'branch') {
+        onBranchSelect(row.refName)
+      } else {
+        onLinearIssueSelect(row.issue)
+      }
+      setOpen(false)
+    },
+    [onBranchSelect, onGitHubItemSelect, onLinearIssueSelect, onValueChange]
+  )
+
+  const acceptGitHubLink = useCallback(
+    async (targetRepo: RepoOption): Promise<void> => {
+      if (!crossRepoPrompt) {
+        return
+      }
+      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
+        })
+        if (!item) {
+          return
+        }
+        onRepoChange(targetRepo.id)
+        onGitHubItemSelect({ ...item, repoId: targetRepo.id } as GitHubWorkItem)
+        setOpen(false)
+        setCrossRepoPrompt(null)
+      } finally {
+        setGithubLoading(false)
+      }
+    },
+    [crossRepoPrompt, debouncedQuery, onGitHubItemSelect, onRepoChange]
+  )
+
+  const handleUseCurrentRepo = useCallback(async (): Promise<void> => {
+    if (!selectedRepo) {
+      return
+    }
+    setCrossRepoPrompt(null)
+    await acceptGitHubLink(selectedRepo)
+  }, [acceptGitHubLink, selectedRepo])
+
+  const handleAddMatchingRepo = useCallback(async (): Promise<void> => {
+    if (!crossRepoPrompt) {
+      return
+    }
+    const added = await addRepo()
+    if (!added) {
+      return
+    }
+    repoSlugCacheRef.current.delete(added.id)
+    const slug = await getRepoSlugCached(added, repoSlugCacheRef.current)
+    if (slug && sameSlug(slug, crossRepoPrompt.link.slug)) {
+      await acceptGitHubLink(added)
+    }
+  }, [acceptGitHubLink, addRepo, crossRepoPrompt])
+
+  const dismissCrossRepoPrompt = useCallback((): void => {
+    handledCrossRepoUrlRef.current = debouncedQuery.trim()
+    setCrossRepoPrompt(null)
+  }, [debouncedQuery])
+
+  const placeholder =
+    mode === 'smart'
+      ? 'Type a name, #1234, branch, GitHub or Linear URL'
+      : mode === 'github'
+        ? 'Search GitHub PRs and issues'
+        : mode === 'branches'
+          ? 'Search branches'
+          : mode === 'linear'
+            ? 'Search Linear issues'
+            : 'Workspace name'
+
+  return (
+    <div className="min-w-0 space-y-1.5">
+      <Tabs
+        value={mode}
+        onValueChange={(next) => {
+          setMode(next as SmartNameMode)
+          setOpen(next !== 'text')
+          requestAnimationFrame(() => localInputRef.current?.focus({ preventScroll: true }))
+        }}
+        className="gap-0"
+      >
+        <TabsList
+          ref={tabsListRef}
+          variant="line"
+          className="h-7 w-full justify-start gap-4 border-b border-border/40 px-0"
+          onFocusCapture={(event) => {
+            // Why: Radix Tabs uses roving focus and re-applies tabindex=0 to
+            // the active trigger on every render, so we can't keep it out of
+            // the natural Tab order via props or a MutationObserver (race
+            // with React commits). Instead, intercept focus *on entry* into
+            // the tabs list:
+            //   - Forward Tab from outside (e.g., Repo combobox) → bounce to
+            //     the search input so the segmented control is skipped.
+            //   - Shift-Tab from the input → relatedTarget is the input, so
+            //     allow focus to land on the active trigger (segmented
+            //     control remains reachable in reverse).
+            //   - Intra-list focus moves (arrow keys) → relatedTarget is
+            //     inside the list; allow.
+            const previous = event.relatedTarget as HTMLElement | null
+            const list = tabsListRef.current
+            const input = localInputRef.current
+            if (!list || !input) {
+              return
+            }
+            if (!previous || previous === input || list.contains(previous)) {
+              return
+            }
+            event.stopPropagation()
+            input.focus({ preventScroll: true })
+          }}
+        >
+          {MODES.map(({ id, label, Icon }) => (
+            <TabsTrigger
+              key={id}
+              value={id}
+              tabIndex={-1}
+              data-smart-name-mode={id}
+              className="flex-none gap-1.5 px-0 text-xs"
+            >
+              <Icon className="size-3.5" />
+              <span>{label}</span>
+            </TabsTrigger>
+          ))}
+        </TabsList>
+      </Tabs>
+
+      <Popover open={open && mode !== 'text'} onOpenChange={setOpen}>
+        <Command
+          value={commandValue}
+          onValueChange={setCommandValue}
+          shouldFilter={false}
+          className="overflow-visible bg-transparent"
+        >
+          <PopoverAnchor asChild>
+            <div className="relative min-w-0">
+              {selectedSource ? (
+                // Why: min-w-0 + w-full lets the pill shrink to its flex
+                // parent; without them the inner truncate's intrinsic
+                // min-content (long PR title) propagates up and pushes the
+                // dialog wider than its max-w.
+                <div className="flex h-9 w-full min-w-0 items-center gap-2 rounded-md border border-input bg-transparent px-2.5 text-sm shadow-xs focus-within:border-ring focus-within:ring-[3px] focus-within:ring-ring/50">
+                  <SelectionIcon kind={selectedSource.kind} />
+                  <span className="min-w-0 flex-1 truncate font-medium leading-none text-foreground">
+                    {selectedSource.label}
+                  </span>
+                  {selectedSource.url ? (
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <Button
+                          type="button"
+                          variant="ghost"
+                          size="icon-xs"
+                          onClick={() => void window.api.shell.openUrl(selectedSource.url!)}
+                          className="size-6 shrink-0 rounded-sm text-muted-foreground hover:text-foreground"
+                          aria-label="Open link in browser"
+                        >
+                          <ExternalLink className="size-3.5" />
+                        </Button>
+                      </TooltipTrigger>
+                      <TooltipContent side="top" sideOffset={6}>
+                        Open in browser
+                      </TooltipContent>
+                    </Tooltip>
+                  ) : null}
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon-xs"
+                        onClick={onClearSelectedSource}
+                        className="size-6 shrink-0 rounded-sm text-muted-foreground hover:text-foreground"
+                        aria-label="Clear selected source"
+                      >
+                        <X className="size-3.5" />
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent side="top" sideOffset={6}>
+                      Clear
+                    </TooltipContent>
+                  </Tooltip>
+                </div>
+              ) : (
+                <>
+                  <ActiveInputIcon
+                    className={cn(
+                      'pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground',
+                      loading && mode !== 'text' && 'animate-spin'
+                    )}
+                  />
+                  <Input
+                    ref={setInputNode}
+                    value={value}
+                    onChange={(event) => {
+                      onValueChange(event.target.value)
+                      if (mode !== 'text') {
+                        setOpen(true)
+                      }
+                    }}
+                    onFocus={() => {
+                      if (mode !== 'text') {
+                        setOpen(true)
+                      }
+                    }}
+                    onKeyDown={(event) => {
+                      if (event.key === 'Tab' && event.shiftKey) {
+                        const activeTrigger = tabsListRef.current?.querySelector<HTMLElement>(
+                          `[data-smart-name-mode="${mode}"]`
+                        )
+                        if (activeTrigger) {
+                          event.preventDefault()
+                          activeTrigger.focus()
+                          return
+                        }
+                      }
+                      if (
+                        event.key === 'Enter' &&
+                        !event.metaKey &&
+                        !event.ctrlKey &&
+                        !event.shiftKey
+                      ) {
+                        if (open && rows.length > 0) {
+                          const row = rows.find((entry) => entry.value === commandValue)
+                          if (row) {
+                            event.preventDefault()
+                            handleSelect(row)
+                            return
+                          }
+                          // No highlighted row (e.g., stale results in
+                          // GitHub/Linear modes where the highlight was
+                          // cleared to avoid auto-selecting a stale source).
+                          // Fall through to onPlainEnter so the keypress
+                          // doesn't feel inert.
+                        }
+                        onPlainEnter?.()
+                      }
+                      if (event.key === 'Escape' && open) {
+                        event.stopPropagation()
+                        setOpen(false)
+                      }
+                    }}
+                    placeholder={placeholder}
+                    className="h-9 pl-8 text-sm"
+                  />
+                </>
+              )}
+            </div>
+          </PopoverAnchor>
+          <PopoverContent
+            align="start"
+            sideOffset={4}
+            className="popover-scroll-content flex w-[var(--radix-popover-trigger-width)] flex-col p-0"
+            style={{ maxHeight: 'min(var(--radix-popover-content-available-height,22rem),22rem)' }}
+            onOpenAutoFocus={(event) => event.preventDefault()}
+            onPointerDownOutside={(event) => {
+              // Why: the input is a PopoverAnchor, not a PopoverTrigger, so
+              // Radix treats clicks on it as outside the popover. Keep focus
+              // clicks and mode-tab clicks from immediately closing results.
+              const target = event.target as Node
+              if (
+                localInputRef.current?.contains(target) ||
+                tabsListRef.current?.contains(target)
+              ) {
+                event.preventDefault()
+              }
+            }}
+            onFocusOutside={(event) => {
+              const target = event.target as Node
+              if (
+                localInputRef.current?.contains(target) ||
+                tabsListRef.current?.contains(target)
+              ) {
+                event.preventDefault()
+              }
+            }}
+          >
+            <CommandList className="!max-h-none min-h-0 flex-1 scrollbar-sleek">
+              {loading && rows.length === 0 ? (
+                <div className="space-y-1 p-1">
+                  {[0, 1, 2].map((index) => (
+                    <div key={index} className="h-8 animate-pulse rounded bg-muted/40" />
+                  ))}
+                </div>
+              ) : rows.length === 0 ? (
+                <div className="px-3 py-6 text-center text-xs text-muted-foreground">
+                  {mode === 'linear' && linearStatusChecked && !linearStatus.connected
+                    ? 'Connect Linear in Settings to search issues.'
+                    : emptyHintByMode[mode]}
+                </div>
+              ) : (
+                <CommandGroup className="p-1">
+                  {rows.map((row) => (
+                    <CommandItem
+                      key={row.value}
+                      value={row.value}
+                      onSelect={() => handleSelect(row)}
+                      className="gap-2 px-2 py-1.5 text-xs"
+                    >
+                      <RowIcon row={row} />
+                      <RowLabel row={row} />
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+            </CommandList>
+          </PopoverContent>
+        </Command>
+      </Popover>
+      <Dialog
+        open={crossRepoPrompt !== null}
+        onOpenChange={(next) => !next && dismissCrossRepoPrompt()}
+      >
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Switch project?</DialogTitle>
+            <DialogDescription>
+              The GitHub URL points to {crossRepoPrompt?.link.slug.owner}/
+              {crossRepoPrompt?.link.slug.repo}, which is different from the selected project.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={dismissCrossRepoPrompt}>
+              Cancel
+            </Button>
+            <Button variant="outline" onClick={() => void handleUseCurrentRepo()}>
+              Keep {selectedRepo?.displayName ?? 'current project'}
+            </Button>
+            {crossRepoPrompt?.matchingRepo ? (
+              <Button onClick={() => void acceptGitHubLink(crossRepoPrompt.matchingRepo!)}>
+                Switch to {crossRepoPrompt.matchingRepo.displayName}
+              </Button>
+            ) : (
+              <Button onClick={() => void handleAddMatchingRepo()}>Add project...</Button>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  )
+}
+
+function RowIcon({ row }: { row: RowEntry }): React.JSX.Element {
+  if (row.kind === 'use-name') {
+    return <CaseSensitive className="size-3.5 shrink-0 text-muted-foreground" />
+  }
+  if (row.kind === 'create-branch') {
+    return <GitBranchPlus className="size-3.5 shrink-0 text-muted-foreground" />
+  }
+  if (row.kind === 'github') {
+    return row.item.type === 'pr' ? (
+      <GitPullRequest className="size-3.5 shrink-0 text-muted-foreground" />
+    ) : (
+      <CircleDot className="size-3.5 shrink-0 text-muted-foreground" />
+    )
+  }
+  if (row.kind === 'branch') {
+    return <GitBranch className="size-3.5 shrink-0 text-muted-foreground" />
+  }
+  return (
+    <span className="size-3.5 shrink-0 rounded-sm bg-muted text-[8px] font-semibold leading-3.5 text-muted-foreground">
+      L
+    </span>
+  )
+}
+
+function SelectionIcon({ kind }: { kind: SmartWorkspaceNameSelection['kind'] }): React.JSX.Element {
+  if (kind === 'github-pr') {
+    return <GitPullRequest className="size-3.5 shrink-0 text-muted-foreground" />
+  }
+  if (kind === 'github-issue') {
+    return <CircleDot className="size-3.5 shrink-0 text-muted-foreground" />
+  }
+  if (kind === 'branch') {
+    return <GitBranch className="size-3.5 shrink-0 text-muted-foreground" />
+  }
+  return (
+    <span className="size-3.5 shrink-0 rounded-sm bg-muted text-center text-[8px] font-semibold leading-3.5 text-muted-foreground">
+      L
+    </span>
+  )
+}
+
+function RowLabel({ row }: { row: RowEntry }): React.JSX.Element {
+  if (row.kind === 'use-name') {
+    return (
+      <span className="min-w-0 truncate">
+        Use <span className="font-medium text-foreground">&ldquo;{row.name}&rdquo;</span> as
+        workspace name
+      </span>
+    )
+  }
+  if (row.kind === 'create-branch') {
+    return (
+      <span className="min-w-0 truncate">
+        Create new branch{' '}
+        <span className="font-mono text-[11px] font-medium text-foreground">{row.name}</span>
+      </span>
+    )
+  }
+  if (row.kind === 'github') {
+    return (
+      <span className="min-w-0 truncate">
+        <span className="font-medium text-foreground">#{row.item.number}</span> {row.item.title}
+      </span>
+    )
+  }
+  if (row.kind === 'branch') {
+    return <span className="min-w-0 truncate font-mono text-[11px]">{row.refName}</span>
+  }
+  return (
+    <span className="min-w-0 truncate">
+      <span className="font-medium text-foreground">{row.issue.identifier}</span> {row.issue.title}
+    </span>
+  )
+}
+
+function sameSlug(left: RepoSlug, right: RepoSlug): boolean {
+  return (
+    left.owner.toLowerCase() === right.owner.toLowerCase() &&
+    left.repo.toLowerCase() === right.repo.toLowerCase()
+  )
+}
+
+async function getRepoSlugCached(
+  repo: RepoOption,
+  cache: Map<string, RepoSlug | null>
+): Promise<RepoSlug | null> {
+  if (cache.has(repo.id)) {
+    return cache.get(repo.id) ?? null
+  }
+  if (repo.connectionId) {
+    cache.set(repo.id, null)
+    return null
+  }
+  try {
+    const slug = await window.api.gh.repoSlug({ repoPath: repo.path })
+    cache.set(repo.id, slug)
+    return slug
+  } catch {
+    cache.set(repo.id, null)
+    return null
+  }
+}
+
+async function findMatchingRepoForSlug(
+  repos: RepoOption[],
+  slug: RepoSlug,
+  cache: Map<string, RepoSlug | null>
+): Promise<RepoOption | null> {
+  for (const repo of repos) {
+    const candidate = await getRepoSlugCached(repo, cache)
+    if (candidate && sameSlug(candidate, slug)) {
+      return repo
+    }
+  }
+  return null
+}
diff --git a/src/renderer/src/components/right-sidebar/ActionButton.test.tsx b/src/renderer/src/components/right-sidebar/ActionButton.test.tsx
new file mode 100644
index 00000000000..55353d29850
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/ActionButton.test.tsx
@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Plus } from 'lucide-react'
+import { ActionButton } from './SourceControl'
+import { Button } from '@/components/ui/button'
+
+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 findInnerButton(node: unknown): ReactElementLike {
+  let found: ReactElementLike | null = null
+  visit(node, (entry) => {
+    if (entry.type === Button) {
+      found = entry
+    }
+  })
+  if (!found) {
+    throw new Error('inner Button not found')
+  }
+  return found
+}
+
+function findTooltipContentText(node: unknown): string {
+  const texts: string[] = []
+  visit(node, (entry) => {
+    const typeName =
+      typeof entry.type === 'function' || typeof entry.type === 'object'
+        ? ((entry.type as { displayName?: string; name?: string }).displayName ??
+          (entry.type as { displayName?: string; name?: string }).name ??
+          '')
+        : ''
+    if (typeName === 'TooltipContent') {
+      const children = entry.props?.children
+      if (typeof children === 'string') {
+        texts.push(children)
+      }
+    }
+  })
+  return texts.join(' ')
+}
+
+// Why: ActionButton's onClick handler only touches these three fields, so a
+// narrow event type is both correct and avoids a forbidden `as unknown as X`
+// double-cast on the event value.
+type MinimalMouseEvent = Pick<
+  React.MouseEvent,
+  'preventDefault' | 'stopPropagation' | 'defaultPrevented'
+>
+
+function makeClickEvent(): {
+  event: MinimalMouseEvent
+  preventDefault: ReturnType<typeof vi.fn>
+} {
+  const preventDefault = vi.fn()
+  const event: MinimalMouseEvent = {
+    preventDefault,
+    stopPropagation: vi.fn(),
+    defaultPrevented: false
+  }
+  return { event, preventDefault }
+}
+
+const baseProps = {
+  icon: Plus,
+  title: 'Stage all',
+  onClick: vi.fn()
+}
+
+describe('ActionButton', () => {
+  it('forwards the title as aria-label on the inner button', () => {
+    const element = ActionButton({ ...baseProps, onClick: vi.fn() })
+    const button = findInnerButton(element)
+    expect(button.props['aria-label']).toBe('Stage all')
+  })
+
+  it('renders the title as tooltip content (non-native, Radix)', () => {
+    const element = ActionButton({ ...baseProps, onClick: vi.fn() })
+    // Why: the Radix TooltipContent is what renders the visual tooltip.
+    // Native `title` was removed because its styling diverges from the
+    // rest of the sidebar chrome.
+    expect(findTooltipContentText(element)).toContain('Stage all')
+  })
+
+  it('calls the onClick handler when enabled', () => {
+    const onClick = vi.fn()
+    const element = ActionButton({ ...baseProps, onClick })
+    const button = findInnerButton(element)
+    const { event } = makeClickEvent()
+    ;(button.props.onClick as (e: MinimalMouseEvent) => void)(event)
+    expect(onClick).toHaveBeenCalledWith(event)
+  })
+
+  it('does NOT render the native disabled prop on the inner button', () => {
+    // Why: Radix TooltipTrigger on a DOM-disabled <button> gets its pointer
+    // events blocked in Chromium, suppressing the tooltip entirely — a
+    // regression vs. the native `title` attribute it replaced. ActionButton
+    // uses aria-disabled + a click guard instead.
+    const element = ActionButton({ ...baseProps, onClick: vi.fn(), disabled: true })
+    const button = findInnerButton(element)
+    expect(button.props.disabled).toBeUndefined()
+  })
+
+  it('marks the inner button aria-disabled when the disabled prop is true', () => {
+    const element = ActionButton({ ...baseProps, onClick: vi.fn(), disabled: true })
+    const button = findInnerButton(element)
+    expect(button.props['aria-disabled']).toBe(true)
+  })
+
+  it('applies the visual-disabled class when disabled', () => {
+    const element = ActionButton({ ...baseProps, onClick: vi.fn(), disabled: true })
+    const button = findInnerButton(element)
+    expect(button.props.className).toContain('opacity-50')
+    expect(button.props.className).toContain('cursor-not-allowed')
+  })
+
+  it('omits the visual-disabled class when enabled', () => {
+    const element = ActionButton({ ...baseProps, onClick: vi.fn(), disabled: false })
+    const button = findInnerButton(element)
+    expect(button.props.className).not.toContain('opacity-50')
+  })
+
+  it('swallows clicks and calls preventDefault when disabled', () => {
+    const onClick = vi.fn()
+    const element = ActionButton({ ...baseProps, onClick, disabled: true })
+    const button = findInnerButton(element)
+    const { event, preventDefault } = makeClickEvent()
+    ;(button.props.onClick as (e: MinimalMouseEvent) => void)(event)
+    // Why: keyboard Enter/Space also fires onClick on a non-DOM-disabled
+    // button. The guard must block both pointer and keyboard activation
+    // while `disabled` is true, even though the inner handler is trusted
+    // to early-return on `isExecutingBulk`.
+    expect(onClick).not.toHaveBeenCalled()
+    expect(preventDefault).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
index 1850727140c..47a86066972 100644
--- a/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/ChecksPanel.tsx
@@ -79,12 +79,15 @@ export default function ChecksPanel(): React.JSX.Element {
     ? (gitConflictOperationByWorktree[activeWorktreeId] ?? 'unknown')
     : 'unknown'
 
-  // Fetch PR data when the active worktree/branch changes
+  // Fetch PR data when the active worktree/branch changes.
+  // Why: pass linkedPR so worktrees created from a PR (whose new local branch
+  // differs from the PR's head ref) resolve via the number-based fallback.
+  const linkedPR = activeWorktree?.linkedPR ?? null
   useEffect(() => {
     if (repo && !isFolder && branch) {
-      void fetchPRForBranch(repo.path, branch)
+      void fetchPRForBranch(repo.path, branch, { linkedPRNumber: linkedPR })
     }
-  }, [repo, isFolder, branch, fetchPRForBranch])
+  }, [repo, isFolder, branch, linkedPR, fetchPRForBranch])
 
   useEffect(() => {
     if (!repo || isFolder || !branch || !pr || pr.mergeable !== 'CONFLICTING') {
@@ -102,8 +105,8 @@ 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 })
-  }, [repo, isFolder, branch, pr, fetchPRForBranch])
+    void fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR })
+  }, [repo, isFolder, branch, pr, linkedPR, fetchPRForBranch])
 
   // Fetch checks via cached store method
   const fetchChecks = useCallback(
@@ -232,7 +235,10 @@ export default function ChecksPanel(): React.JSX.Element {
     }
     setIsRefreshing(true)
     try {
-      const refreshedPR = await fetchPRForBranch(repo.path, branch, { force: true })
+      const refreshedPR = await fetchPRForBranch(repo.path, branch, {
+        force: true,
+        linkedPRNumber: linkedPR
+      })
       if (refreshedPR) {
         await Promise.all([
           fetchChecks({ force: true, prNumberOverride: refreshedPR.number }),
@@ -245,7 +251,7 @@ export default function ChecksPanel(): React.JSX.Element {
     } finally {
       setIsRefreshing(false)
     }
-  }, [repo, branch, fetchPRForBranch, fetchChecks, fetchComments])
+  }, [repo, branch, linkedPR, fetchPRForBranch, fetchChecks, fetchComments])
 
   const handleStartEdit = useCallback(() => {
     if (!pr) {
@@ -275,13 +281,13 @@ export default function ChecksPanel(): React.JSX.Element {
       })
       if (ok) {
         // Re-fetch PR to get updated title
-        await fetchPRForBranch(repo.path, branch, { force: true })
+        await fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR })
       }
     } finally {
       setTitleSaving(false)
       setEditingTitle(false)
     }
-  }, [repo, pr, titleDraft, branch, fetchPRForBranch])
+  }, [repo, pr, titleDraft, branch, linkedPR, fetchPRForBranch])
 
   const handleTitleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -315,9 +321,9 @@ 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 })
+      await fetchPRForBranch(repo.path, branch, { force: true, linkedPRNumber: linkedPR })
     }
-  }, [repo, branch, fetchPRForBranch])
+  }, [repo, branch, linkedPR, fetchPRForBranch])
 
   // Open PR in browser
   const handleOpenPR = useCallback(() => {
diff --git a/src/renderer/src/components/right-sidebar/SourceControl.tsx b/src/renderer/src/components/right-sidebar/SourceControl.tsx
index 414901f51a5..a3ffba6143f 100644
--- a/src/renderer/src/components/right-sidebar/SourceControl.tsx
+++ b/src/renderer/src/components/right-sidebar/SourceControl.tsx
@@ -34,6 +34,14 @@ import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@/comp
 import { Button } from '@/components/ui/button'
 import { BulkActionBar } from './BulkActionBar'
 import { useSourceControlSelection, type FlatEntry } from './useSourceControlSelection'
+import {
+  getDiscardAllPaths,
+  getStageAllPaths,
+  getUnstageAllPaths,
+  runDiscardAllForArea,
+  type DiscardAllArea
+} from './discard-all-sequence'
+import { toast } from 'sonner'
 import {
   ContextMenu,
   ContextMenuContent,
@@ -289,6 +297,7 @@ function SourceControlInner(): React.JSX.Element {
   const prCacheKey = activeRepo && branchName ? `${activeRepo.path}::${branchName}` : null
   const prInfo: PRInfo | null = prCacheKey ? (prCache[prCacheKey]?.data ?? null) : null
 
+  const linkedPR = activeWorktree?.linkedPR ?? null
   useEffect(() => {
     if (!isBranchVisible || !activeRepo || isFolder || !branchName || branchName === 'HEAD') {
       return
@@ -297,9 +306,10 @@ function SourceControlInner(): React.JSX.Element {
     // Why: the Source Control panel renders the branch's PR badge directly.
     // When a terminal checkout moves this worktree onto a new branch, we need
     // to fetch that branch's PR immediately instead of waiting for the user to
-    // reselect the worktree or open the separate Checks panel.
-    void fetchPRForBranch(activeRepo.path, branchName)
-  }, [activeRepo, branchName, fetchPRForBranch, isBranchVisible, isFolder])
+    // reselect the worktree or open the separate Checks panel. Pass linkedPR
+    // so create-from-PR worktrees resolve via the number-based fallback.
+    void fetchPRForBranch(activeRepo.path, branchName, { linkedPRNumber: linkedPR })
+  }, [activeRepo, branchName, fetchPRForBranch, isBranchVisible, isFolder, linkedPR])
 
   const grouped = useMemo(() => {
     const groups = {
@@ -617,6 +627,49 @@ function SourceControlInner(): React.JSX.Element {
     }
   }, [worktreePath, bulkUnstagePaths, clearSelection, activeWorktreeId])
 
+  // Why: "Stage all" on the Changes section intentionally skips unresolved
+  // conflict rows. `git add` on a conflicted file silently clears the `u`
+  // record — the only live signal we have — before the user has reviewed it,
+  // which mirrors the per-row Stage suppression above.
+  const handleStageAllInArea = useCallback(
+    async (area: 'unstaged' | 'untracked') => {
+      if (!worktreePath || isExecutingBulk) {
+        return
+      }
+      const paths = getStageAllPaths(grouped[area], area)
+      if (paths.length === 0) {
+        return
+      }
+      setIsExecutingBulk(true)
+      try {
+        const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
+        await window.api.git.bulkStage({ worktreePath, filePaths: paths, connectionId })
+        clearSelection()
+      } finally {
+        setIsExecutingBulk(false)
+      }
+    },
+    [worktreePath, grouped, activeWorktreeId, isExecutingBulk, clearSelection]
+  )
+
+  const handleUnstageAll = useCallback(async () => {
+    if (!worktreePath || isExecutingBulk) {
+      return
+    }
+    const paths = getUnstageAllPaths(grouped.staged)
+    if (paths.length === 0) {
+      return
+    }
+    setIsExecutingBulk(true)
+    try {
+      const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
+      await window.api.git.bulkUnstage({ worktreePath, filePaths: paths, connectionId })
+      clearSelection()
+    } finally {
+      setIsExecutingBulk(false)
+    }
+  }, [worktreePath, grouped.staged, activeWorktreeId, isExecutingBulk, clearSelection])
+
   const refreshBranchCompare = useCallback(async () => {
     if (!activeWorktreeId || !worktreePath || !effectiveBaseRef || isFolder) {
       return
@@ -758,34 +811,109 @@ function SourceControlInner(): React.JSX.Element {
     [worktreePath, activeWorktreeId]
   )
 
-  const handleDiscard = useCallback(
+  // Why: split into two variants — `discardSingle` throws so bulk callers can
+  // aggregate failures into a single toast via `runDiscardAllForArea`'s
+  // onError, while `handleDiscard` swallows for the per-row fire-and-forget UI
+  // contract (no individual failure toast).
+  const discardSingle = useCallback(
     async (filePath: string) => {
       if (!worktreePath || !activeWorktreeId) {
         return
       }
-      try {
-        // Why: git discard replaces the working tree version of this file. Any
-        // pending editor autosave must be quiesced first so it cannot recreate
-        // the discarded edits after git restores the file.
-        await requestEditorSaveQuiesce({
-          worktreeId: activeWorktreeId,
-          worktreePath,
-          relativePath: filePath
-        })
-        const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
-        await window.api.git.discard({ worktreePath, filePath, connectionId })
-        notifyEditorExternalFileChange({
-          worktreeId: activeWorktreeId,
-          worktreePath,
-          relativePath: filePath
-        })
-      } catch {
-        // git operation failed silently
-      }
+      // Why: git discard replaces the working tree version of this file. Any
+      // pending editor autosave must be quiesced first so it cannot recreate
+      // the discarded edits after git restores the file.
+      await requestEditorSaveQuiesce({
+        worktreeId: activeWorktreeId,
+        worktreePath,
+        relativePath: filePath
+      })
+      const connectionId = getConnectionId(activeWorktreeId ?? null) ?? undefined
+      await window.api.git.discard({ worktreePath, filePath, connectionId })
+      notifyEditorExternalFileChange({
+        worktreeId: activeWorktreeId,
+        worktreePath,
+        relativePath: filePath
+      })
     },
     [activeWorktreeId, worktreePath]
   )
 
+  const handleDiscard = useCallback(
+    async (filePath: string) => {
+      try {
+        await discardSingle(filePath)
+      } catch {
+        // Why: per-row discard is fire-and-forget for the UI; failures are not
+        // surfaced individually. Bulk callers use `discardSingle` directly so
+        // they can aggregate failures into a single toast.
+      }
+    },
+    [discardSingle]
+  )
+
+  // Why: "Discard all" mirrors the per-row discard rules — it skips unresolved
+  // and resolved_locally rows because discarding those can silently re-create
+  // the conflict or lose the resolution (no v1 UX to explain this clearly).
+  // There is no bulk discard IPC, so we serialize per-file discard calls that
+  // run the same editor-quiesce + external-change notification as the row action.
+  // The sequencing + filter rules live in discard-all-sequence.ts so they can
+  // be unit-tested independently of the full component (staged area needs a
+  // bulk-unstage first, and a failed unstage must skip the discard loop).
+  const handleRevertAllInArea = useCallback(
+    async (area: DiscardAllArea) => {
+      if (!worktreePath || !activeWorktreeId || isExecutingBulk) {
+        return
+      }
+      const paths = getDiscardAllPaths(grouped[area], area)
+      if (paths.length === 0) {
+        return
+      }
+      setIsExecutingBulk(true)
+      try {
+        const connectionId = getConnectionId(activeWorktreeId) ?? undefined
+        // Why: `onError` fires once per failure — both for the bulk-unstage
+        // pre-step and for each per-file discard failure. Aggregate into one
+        // toast after the sequence completes so a partial failure across N
+        // files doesn't spam N error toasts.
+        const errors: unknown[] = []
+        const result = await runDiscardAllForArea(area, paths, {
+          bulkUnstage: (filePaths) =>
+            window.api.git.bulkUnstage({ worktreePath, filePaths, connectionId }),
+          discardOne: discardSingle,
+          onError: (error) => {
+            errors.push(error)
+            console.error('[SourceControl] discard-all failure', error)
+          }
+        })
+        if (result.aborted) {
+          toast.error('Discard all failed — unable to unstage files before discard', {
+            description: errors[0] instanceof Error ? errors[0].message : undefined
+          })
+        } else if (result.failed.length > 0) {
+          // Why: only include the first error message to avoid a huge toast
+          // body on bulk failures; a short sample of failed paths gives users
+          // enough context to retry or investigate.
+          const firstMsg = errors[0] instanceof Error ? errors[0].message : undefined
+          const sample = result.failed.slice(0, 3).join(', ')
+          const more = result.failed.length > 3 ? `, +${result.failed.length - 3} more` : ''
+          toast.error(
+            `Failed to discard ${result.failed.length} file${result.failed.length === 1 ? '' : 's'}`,
+            {
+              description: firstMsg ? `${firstMsg} (e.g. ${sample}${more})` : `${sample}${more}`
+            }
+          )
+        }
+        if (!result.aborted) {
+          clearSelection()
+        }
+      } finally {
+        setIsExecutingBulk(false)
+      }
+    },
+    [worktreePath, activeWorktreeId, grouped, isExecutingBulk, clearSelection, discardSingle]
+  )
+
   if (!activeWorktree || !activeRepo || !worktreePath) {
     return (
       <div className="flex items-center justify-center h-full text-xs text-muted-foreground px-4 text-center">
@@ -1009,7 +1137,7 @@ function SourceControlInner(): React.JSX.Element {
               />
             )}
 
-          {(scope === 'all' || scope === 'uncommitted') && (
+          {(scope === 'all' || scope === 'uncommitted') && hasUncommittedEntries && (
             <CommitArea
               stagedCount={grouped.staged.length}
               hasUnresolvedConflicts={unresolvedConflicts.length > 0}
@@ -1038,6 +1166,26 @@ function SourceControlInner(): React.JSX.Element {
                   return null
                 }
                 const isCollapsed = collapsedSections.has(area)
+                // Why: "Stage all"/"Unstage all" operate on the *unfiltered*
+                // group for the area — acting on just the filter-visible subset
+                // would surprise users who don't realize a filter is active.
+                // The +/- is hidden when the filter is active to avoid that
+                // mismatch between what's shown and what would be staged.
+                // Why: visibility and execution both resolve paths through the
+                // same helpers (`getStageAllPaths`/`getUnstageAllPaths`/
+                // `getDiscardAllPaths`) so the button can never show for a set
+                // the handler would then filter to empty.
+                const stageAllPaths =
+                  area === 'unstaged' || area === 'untracked'
+                    ? getStageAllPaths(grouped[area], area)
+                    : []
+                const canStageAll = !normalizedFilter && stageAllPaths.length > 0
+                const canUnstageAll =
+                  !normalizedFilter &&
+                  area === 'staged' &&
+                  getUnstageAllPaths(grouped.staged).length > 0
+                const canRevertAll =
+                  !normalizedFilter && getDiscardAllPaths(grouped[area], area).length > 0
                 return (
                   <div key={area}>
                     <SectionHeader
@@ -1049,37 +1197,92 @@ function SourceControlInner(): React.JSX.Element {
                       isCollapsed={isCollapsed}
                       onToggle={() => toggleSection(area)}
                       actions={
-                        items.some((entry) => entry.conflictStatus === 'unresolved') ? (
-                          <Button
-                            type="button"
-                            variant="ghost"
-                            size="sm"
-                            className="h-6 px-1.5 text-[10px] text-muted-foreground hover:text-foreground"
-                            onClick={(e) => {
-                              e.stopPropagation()
-                              if (activeWorktreeId && worktreePath) {
-                                openAllDiffs(activeWorktreeId, worktreePath, undefined, area)
-                              }
-                            }}
-                          >
-                            View all
-                          </Button>
-                        ) : (
-                          <Button
-                            type="button"
-                            variant="ghost"
-                            size="sm"
-                            className="h-auto px-1.5 py-0.5 text-xs text-muted-foreground hover:text-foreground"
-                            onClick={(e) => {
-                              e.stopPropagation()
-                              if (activeWorktreeId && worktreePath) {
-                                openAllDiffs(activeWorktreeId, worktreePath, undefined, area)
-                              }
-                            }}
-                          >
-                            View all
-                          </Button>
-                        )
+                        <>
+                          {/* Why: bulk action buttons are hover-only on
+                              pointer devices to avoid cluttering the section
+                              header with persistent icons. On no-hover
+                              pointers (touch, and SSH sessions where hover
+                              state is unreliable — see AGENTS.md "SSH Use
+                              Case"), force them visible so they're reachable
+                              without tabbing. One outer wrapper so that
+                              focusing any action reveals all three siblings —
+                              otherwise keyboard users tab into an invisible
+                              next stop. */}
+                          <div className="flex items-center opacity-0 transition-opacity group-hover/section:opacity-100 focus-within:opacity-100 [@media(hover:none)]:opacity-100">
+                            {canRevertAll && (
+                              <ActionButton
+                                icon={Undo2}
+                                // Why: for untracked files, discard deletes the file
+                                // outright (rm -rf via git.discard's untracked branch).
+                                // A generic "Discard all" label hides that severity —
+                                // label explicitly for the destructive variant.
+                                title={
+                                  area === 'untracked' ? 'Delete all untracked' : 'Discard all'
+                                }
+                                onClick={(event) => {
+                                  event.stopPropagation()
+                                  void handleRevertAllInArea(area)
+                                }}
+                                disabled={isExecutingBulk}
+                              />
+                            )}
+                            {canStageAll && (
+                              <ActionButton
+                                icon={Plus}
+                                title="Stage all"
+                                onClick={(event) => {
+                                  event.stopPropagation()
+                                  if (area === 'unstaged' || area === 'untracked') {
+                                    void handleStageAllInArea(area)
+                                  }
+                                }}
+                                disabled={isExecutingBulk}
+                              />
+                            )}
+                            {canUnstageAll && (
+                              <ActionButton
+                                icon={Minus}
+                                title="Unstage all"
+                                onClick={(event) => {
+                                  event.stopPropagation()
+                                  void handleUnstageAll()
+                                }}
+                                disabled={isExecutingBulk}
+                              />
+                            )}
+                          </div>
+                          {items.some((entry) => entry.conflictStatus === 'unresolved') ? (
+                            <Button
+                              type="button"
+                              variant="ghost"
+                              size="sm"
+                              className="h-6 px-1.5 text-[10px] text-muted-foreground hover:text-foreground"
+                              onClick={(e) => {
+                                e.stopPropagation()
+                                if (activeWorktreeId && worktreePath) {
+                                  openAllDiffs(activeWorktreeId, worktreePath, undefined, area)
+                                }
+                              }}
+                            >
+                              View all
+                            </Button>
+                          ) : (
+                            <Button
+                              type="button"
+                              variant="ghost"
+                              size="sm"
+                              className="h-auto px-1.5 py-0.5 text-xs text-muted-foreground hover:text-foreground"
+                              onClick={(e) => {
+                                e.stopPropagation()
+                                if (activeWorktreeId && worktreePath) {
+                                  openAllDiffs(activeWorktreeId, worktreePath, undefined, area)
+                                }
+                              }}
+                            >
+                              View all
+                            </Button>
+                          )}
+                        </>
                       }
                     />
                     {!isCollapsed &&
@@ -1420,25 +1623,31 @@ function SectionHeader({
   onToggle: () => void
   actions?: React.ReactNode
 }): React.JSX.Element {
+  // Why: wrap the toggle button and actions in a shared rounded container
+  // so the hover background spans the entire row instead of clipping around
+  // the label. The outer div keeps the vertical spacing that separates
+  // sections; the inner wrapper owns the hover rectangle.
   return (
-    <div className="group/section flex items-center pl-1 pr-3 pt-3 pb-1">
-      <button
-        type="button"
-        className="flex flex-1 items-center gap-1 rounded-md px-0.5 py-0.5 text-left text-xs font-semibold uppercase tracking-wider text-foreground/70 hover:bg-accent hover:text-accent-foreground"
-        onClick={onToggle}
-      >
-        <ChevronDown
-          className={cn('size-3.5 shrink-0 transition-transform', isCollapsed && '-rotate-90')}
-        />
-        <span>{label}</span>
-        <span className="text-[11px] font-medium tabular-nums">{count}</span>
-        {conflictCount > 0 && (
-          <span className="text-[11px] font-medium text-destructive/80">
-            · {conflictCount} conflict{conflictCount === 1 ? '' : 's'}
-          </span>
-        )}
-      </button>
-      <div className="shrink-0 flex items-center">{actions}</div>
+    <div className="pl-1 pr-3 pt-3 pb-1">
+      <div className="group/section flex items-center rounded-md pr-1 hover:bg-accent hover:text-accent-foreground">
+        <button
+          type="button"
+          className="flex flex-1 items-center gap-1 px-0.5 py-0.5 text-left text-xs font-semibold uppercase tracking-wider text-foreground/70 group-hover/section:text-accent-foreground"
+          onClick={onToggle}
+        >
+          <ChevronDown
+            className={cn('size-3.5 shrink-0 transition-transform', isCollapsed && '-rotate-90')}
+          />
+          <span>{label}</span>
+          <span className="text-[11px] font-medium tabular-nums">{count}</span>
+          {conflictCount > 0 && (
+            <span className="text-[11px] font-medium text-destructive/80">
+              · {conflictCount} conflict{conflictCount === 1 ? '' : 's'}
+            </span>
+          )}
+        </button>
+        <div className="shrink-0 flex items-center">{actions}</div>
+      </div>
     </div>
   )
 }
@@ -1928,26 +2137,61 @@ function EmptyState({
   )
 }
 
-function ActionButton({
+export function ActionButton({
   icon: Icon,
   title,
-  onClick
+  onClick,
+  disabled
 }: {
   icon: React.ComponentType<{ className?: string }>
   title: string
   onClick: (event: React.MouseEvent) => void
+  disabled?: boolean
 }): React.JSX.Element {
+  // Why: use the Radix Tooltip instead of the native `title` attribute so the
+  // label matches the rest of the sidebar chrome (consistent styling, no OS
+  // delay quirks, dismissible on pointer leave).
+  //
+  // Why (no local TooltipProvider): the app root mounts a single
+  // TooltipProvider (see App.tsx); nesting another one here gives this subtree
+  // its own delay-timing state and breaks Radix's "skip the open delay when
+  // moving between adjacent tooltip triggers" handoff between sibling action
+  // buttons in the section header.
+  //
+  // Why (disabled handling): Radix's TooltipTrigger asChild on a disabled
+  // <button> gets pointer-events blocked in Chromium, which suppresses the
+  // tooltip entirely — a regression vs. the native `title` attribute it
+  // replaced. We keep the button interactive and rely on the caller's
+  // `isExecutingBulk` early-return to no-op the click during bulk ops;
+  // `aria-disabled` + visual dimming preserves the disabled affordance.
   return (
-    <Button
-      type="button"
-      variant="ghost"
-      size="icon-xs"
-      className="h-auto w-auto p-0.5 text-muted-foreground hover:text-foreground"
-      title={title}
-      onClick={onClick}
-    >
-      <Icon className="size-3.5" />
-    </Button>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-xs"
+          className={cn(
+            'h-auto w-auto p-0.5 text-muted-foreground hover:text-foreground',
+            disabled && 'opacity-50 cursor-not-allowed'
+          )}
+          aria-label={title}
+          aria-disabled={disabled}
+          onClick={(event) => {
+            if (disabled) {
+              event.preventDefault()
+              return
+            }
+            onClick(event)
+          }}
+        >
+          <Icon className="size-3.5" />
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom" sideOffset={6}>
+        {title}
+      </TooltipContent>
+    </Tooltip>
   )
 }
 
diff --git a/src/renderer/src/components/right-sidebar/discard-all-sequence.test.ts b/src/renderer/src/components/right-sidebar/discard-all-sequence.test.ts
new file mode 100644
index 00000000000..f7a2dcb5f7c
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/discard-all-sequence.test.ts
@@ -0,0 +1,284 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  getDiscardAllPaths,
+  getStageAllPaths,
+  getUnstageAllPaths,
+  runDiscardAllForArea,
+  type DiscardAllArea
+} from './discard-all-sequence'
+import type { GitStatusEntry } from '../../../../shared/types'
+
+function entry(partial: Partial<GitStatusEntry> & { path: string }): GitStatusEntry {
+  return {
+    status: 'modified',
+    area: 'unstaged',
+    ...partial
+  }
+}
+
+describe('getDiscardAllPaths', () => {
+  it('returns only paths in the requested area', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'a.ts', area: 'staged' }),
+      entry({ path: 'b.ts', area: 'unstaged' }),
+      entry({ path: 'c.ts', area: 'untracked', status: 'untracked' })
+    ]
+    expect(getDiscardAllPaths(entries, 'staged')).toEqual(['a.ts'])
+    expect(getDiscardAllPaths(entries, 'unstaged')).toEqual(['b.ts'])
+    expect(getDiscardAllPaths(entries, 'untracked')).toEqual(['c.ts'])
+  })
+
+  it('skips entries with an unresolved conflict', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'clean.ts', area: 'unstaged' }),
+      entry({
+        path: 'conflict.ts',
+        area: 'unstaged',
+        conflictKind: 'both_modified',
+        conflictStatus: 'unresolved'
+      })
+    ]
+    // Why: `git restore --worktree --source=HEAD` on an unresolved conflict
+    // clears the `u` record silently before the user has reviewed it, which
+    // is why the per-row Stage/Discard buttons also suppress this case.
+    expect(getDiscardAllPaths(entries, 'unstaged')).toEqual(['clean.ts'])
+  })
+
+  it('skips entries resolved locally but not yet re-staged', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'clean.ts', area: 'unstaged' }),
+      entry({
+        path: 'resolved.ts',
+        area: 'unstaged',
+        conflictKind: 'both_modified',
+        conflictStatus: 'resolved_locally'
+      })
+    ]
+    // Why: discarding a locally-resolved file loses the resolution. The user
+    // would have to re-resolve from scratch — treat it as too dangerous to
+    // include in a bulk action.
+    expect(getDiscardAllPaths(entries, 'unstaged')).toEqual(['clean.ts'])
+  })
+
+  it('returns an empty array when nothing matches', () => {
+    expect(getDiscardAllPaths([], 'staged')).toEqual([])
+    expect(getDiscardAllPaths([entry({ path: 'a.ts', area: 'staged' })], 'unstaged')).toEqual([])
+  })
+})
+
+describe('getStageAllPaths', () => {
+  it('returns only paths in the requested area', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'a.ts', area: 'staged' }),
+      entry({ path: 'b.ts', area: 'unstaged' }),
+      entry({ path: 'c.ts', area: 'untracked', status: 'untracked' })
+    ]
+    expect(getStageAllPaths(entries, 'unstaged')).toEqual(['b.ts'])
+    expect(getStageAllPaths(entries, 'untracked')).toEqual(['c.ts'])
+  })
+
+  it('skips entries with an unresolved conflict', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'clean.ts', area: 'unstaged' }),
+      entry({
+        path: 'conflict.ts',
+        area: 'unstaged',
+        conflictKind: 'both_modified',
+        conflictStatus: 'unresolved'
+      })
+    ]
+    // Why: `git add` on an unresolved conflict silently clears the `u`
+    // record before the user has reviewed it — same hazard the per-row
+    // Stage button guards against.
+    expect(getStageAllPaths(entries, 'unstaged')).toEqual(['clean.ts'])
+  })
+
+  it('includes entries that are resolved locally', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'clean.ts', area: 'unstaged' }),
+      entry({
+        path: 'resolved.ts',
+        area: 'unstaged',
+        conflictKind: 'both_modified',
+        conflictStatus: 'resolved_locally'
+      })
+    ]
+    // Why: staging a locally-resolved file is the normal resolution
+    // workflow — it marks the conflict as finished. Unlike discard, this
+    // must NOT be filtered out.
+    expect(getStageAllPaths(entries, 'unstaged')).toEqual(['clean.ts', 'resolved.ts'])
+  })
+
+  it('returns an empty array when nothing matches', () => {
+    expect(getStageAllPaths([], 'unstaged')).toEqual([])
+    expect(getStageAllPaths([entry({ path: 'a.ts', area: 'staged' })], 'unstaged')).toEqual([])
+  })
+})
+
+describe('getUnstageAllPaths', () => {
+  it('returns only staged-area paths', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'a.ts', area: 'staged' }),
+      entry({ path: 'b.ts', area: 'unstaged' }),
+      entry({ path: 'c.ts', area: 'untracked', status: 'untracked' })
+    ]
+    expect(getUnstageAllPaths(entries)).toEqual(['a.ts'])
+  })
+
+  it('includes staged conflict rows', () => {
+    const entries: GitStatusEntry[] = [
+      entry({ path: 'clean.ts', area: 'staged' }),
+      entry({
+        path: 'conflict.ts',
+        area: 'staged',
+        conflictKind: 'both_modified',
+        conflictStatus: 'unresolved'
+      }),
+      entry({
+        path: 'resolved.ts',
+        area: 'staged',
+        conflictKind: 'both_modified',
+        conflictStatus: 'resolved_locally'
+      })
+    ]
+    // Why: `git reset HEAD` on a staged conflict row is safe and mirrors
+    // the per-row Unstage action — no conflict filter here.
+    expect(getUnstageAllPaths(entries)).toEqual(['clean.ts', 'conflict.ts', 'resolved.ts'])
+  })
+
+  it('returns an empty array when nothing is staged', () => {
+    expect(getUnstageAllPaths([])).toEqual([])
+    expect(getUnstageAllPaths([entry({ path: 'a.ts', area: 'unstaged' })])).toEqual([])
+  })
+})
+
+describe('runDiscardAllForArea', () => {
+  function makeDeps(
+    overrides: {
+      bulkUnstageError?: unknown
+      discardOneError?: (path: string) => unknown
+    } = {}
+  ) {
+    const bulkUnstageCalls: string[][] = []
+    const discardOneCalls: string[] = []
+    const errors: unknown[] = []
+
+    const bulkUnstage = vi.fn(async (paths: string[]) => {
+      bulkUnstageCalls.push([...paths])
+      if (overrides.bulkUnstageError !== undefined) {
+        throw overrides.bulkUnstageError
+      }
+    })
+    const discardOne = vi.fn(async (path: string) => {
+      discardOneCalls.push(path)
+      if (overrides.discardOneError) {
+        const err = overrides.discardOneError(path)
+        if (err !== undefined) {
+          throw err
+        }
+      }
+    })
+    const onError = vi.fn((error: unknown) => {
+      errors.push(error)
+    })
+
+    return {
+      deps: { bulkUnstage, discardOne, onError },
+      bulkUnstageCalls,
+      discardOneCalls,
+      errors,
+      bulkUnstage,
+      discardOne,
+      onError
+    }
+  }
+
+  it('no-ops when the path list is empty', async () => {
+    const ctx = makeDeps()
+    const result = await runDiscardAllForArea('staged', [], ctx.deps)
+    expect(result).toEqual({ discarded: [], failed: [], aborted: false })
+    expect(ctx.bulkUnstage).not.toHaveBeenCalled()
+    expect(ctx.discardOne).not.toHaveBeenCalled()
+  })
+
+  it('discards unstaged paths one-by-one without bulk-unstaging', async () => {
+    const ctx = makeDeps()
+    const result = await runDiscardAllForArea('unstaged', ['a.ts', 'b.ts'], ctx.deps)
+    expect(result).toEqual({ discarded: ['a.ts', 'b.ts'], failed: [], aborted: false })
+    expect(ctx.bulkUnstage).not.toHaveBeenCalled()
+    expect(ctx.discardOneCalls).toEqual(['a.ts', 'b.ts'])
+  })
+
+  it('discards untracked paths one-by-one without bulk-unstaging', async () => {
+    const ctx = makeDeps()
+    const result = await runDiscardAllForArea('untracked', ['new.ts'], ctx.deps)
+    expect(result).toEqual({ discarded: ['new.ts'], failed: [], aborted: false })
+    expect(ctx.bulkUnstage).not.toHaveBeenCalled()
+    expect(ctx.discardOneCalls).toEqual(['new.ts'])
+  })
+
+  it('bulk-unstages staged paths before the per-file discard loop', async () => {
+    const ctx = makeDeps()
+    const result = await runDiscardAllForArea('staged', ['a.ts', 'b.ts'], ctx.deps)
+    expect(result).toEqual({ discarded: ['a.ts', 'b.ts'], failed: [], aborted: false })
+    expect(ctx.bulkUnstageCalls).toEqual([['a.ts', 'b.ts']])
+    expect(ctx.discardOneCalls).toEqual(['a.ts', 'b.ts'])
+    // Why: bulk unstage MUST happen strictly before any discard, otherwise
+    // the index would still hold the staged delta when the worktree was
+    // reset and the files would reappear as inverse changes.
+    expect(ctx.bulkUnstage.mock.invocationCallOrder[0]).toBeLessThan(
+      ctx.discardOne.mock.invocationCallOrder[0]
+    )
+  })
+
+  it('aborts and skips the discard loop if bulk-unstage rejects', async () => {
+    const error = new Error('index locked')
+    const ctx = makeDeps({ bulkUnstageError: error })
+    const result = await runDiscardAllForArea('staged', ['a.ts', 'b.ts'], ctx.deps)
+    expect(result).toEqual({ discarded: [], failed: [], aborted: true })
+    // Why: a failed unstage + successful discard would leave the index with
+    // the staged delta and the worktree at HEAD — a worse state than we
+    // started in. The discard loop must not run.
+    expect(ctx.discardOne).not.toHaveBeenCalled()
+    expect(ctx.errors).toEqual([error])
+  })
+
+  it('continues past a per-file discard failure and records it in `failed`', async () => {
+    const error = new Error('EPERM')
+    const ctx = makeDeps({
+      discardOneError: (path) => (path === 'b.ts' ? error : undefined)
+    })
+    const result = await runDiscardAllForArea('unstaged', ['a.ts', 'b.ts', 'c.ts'], ctx.deps)
+    // Why: best-effort continuation — one stuck file shouldn't block the
+    // rest of a bulk action the user explicitly triggered.
+    expect(result).toEqual({
+      discarded: ['a.ts', 'c.ts'],
+      failed: ['b.ts'],
+      aborted: false
+    })
+    expect(ctx.discardOneCalls).toEqual(['a.ts', 'b.ts', 'c.ts'])
+    // Why: `aborted` is reserved for the pre-step (bulk unstage) failing —
+    // per-file failures don't trip it, otherwise callers couldn't
+    // distinguish "nothing ran" from "some ran, some didn't".
+    expect(ctx.errors).toEqual([error])
+  })
+
+  it('does not invoke the error callback on a happy-path staged run', async () => {
+    const ctx = makeDeps()
+    await runDiscardAllForArea('staged', ['a.ts'], ctx.deps)
+    expect(ctx.onError).not.toHaveBeenCalled()
+  })
+
+  it('does not bulk-unstage for non-staged areas even if the dep is provided', async () => {
+    const ctx = makeDeps()
+    const areas: DiscardAllArea[] = ['unstaged', 'untracked']
+    for (const area of areas) {
+      await runDiscardAllForArea(area, ['x.ts'], ctx.deps)
+    }
+    // Why: the unstage step is specific to the staged area's two-step
+    // reset. Accidentally invoking it for unstaged/untracked would be a
+    // no-op for unstaged entries but could mask a regression where staged
+    // entries leak into those paths.
+    expect(ctx.bulkUnstage).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/discard-all-sequence.ts b/src/renderer/src/components/right-sidebar/discard-all-sequence.ts
new file mode 100644
index 00000000000..9425344bca2
--- /dev/null
+++ b/src/renderer/src/components/right-sidebar/discard-all-sequence.ts
@@ -0,0 +1,122 @@
+import type { GitStatusEntry } from '../../../../shared/types'
+
+export type DiscardAllArea = 'staged' | 'unstaged' | 'untracked'
+
+/**
+ * Collect the paths a "Discard all" bulk action should operate on for a given
+ * area. Unresolved and locally-resolved conflicts are excluded — discarding
+ * those can silently re-create the conflict or lose the resolution.
+ */
+export function getDiscardAllPaths(
+  entries: readonly GitStatusEntry[],
+  area: DiscardAllArea
+): string[] {
+  return entries
+    .filter(
+      (entry) =>
+        entry.area === area &&
+        entry.conflictStatus !== 'unresolved' &&
+        entry.conflictStatus !== 'resolved_locally'
+    )
+    .map((entry) => entry.path)
+}
+
+export type StageAllArea = 'unstaged' | 'untracked'
+
+/**
+ * Collect the paths a "Stage all" action should operate on.
+ * Unresolved conflict rows are excluded — `git add` on a conflicted file
+ * silently clears the `u` record before the user has reviewed it.
+ * `resolved_locally` rows are intentionally INCLUDED: staging them is how the
+ * user finalises the resolution and mirrors the per-row Stage button.
+ */
+export function getStageAllPaths(entries: readonly GitStatusEntry[], area: StageAllArea): string[] {
+  return entries
+    .filter((entry) => entry.area === area && entry.conflictStatus !== 'unresolved')
+    .map((entry) => entry.path)
+}
+
+/**
+ * Collect the paths an "Unstage all" action should operate on.
+ * Every staged row is eligible — `git reset HEAD` on a staged conflict
+ * row is safe and mirrors the per-row Unstage action.
+ */
+export function getUnstageAllPaths(entries: readonly GitStatusEntry[]): string[] {
+  return entries.filter((entry) => entry.area === 'staged').map((entry) => entry.path)
+}
+
+export type DiscardAllDeps = {
+  /** Unstage the given paths in one IPC round-trip. Only called for 'staged'. */
+  bulkUnstage: (paths: string[]) => Promise<void>
+  /** Discard a single path (restore working-tree to HEAD, or rm if untracked). */
+  discardOne: (path: string) => Promise<void>
+  /**
+   * Called when either the pre-step (bulkUnstage) rejects OR an individual
+   * `discardOne` rejects. Invoked once per failure so callers can surface
+   * each error (e.g. a toast per stuck file) rather than swallowing them.
+   */
+  onError?: (error: unknown) => void
+}
+
+export type DiscardAllResult = {
+  /** Paths whose `discardOne` call resolved successfully. */
+  discarded: string[]
+  /** Paths whose `discardOne` call rejected. Best-effort: the loop continues past these. */
+  failed: string[]
+  /**
+   * True only when the pre-step (bulk unstage for the 'staged' area) failed
+   * and we never entered the per-file discard loop. Per-file failures do
+   * NOT set this flag — they are reported via `failed`.
+   */
+  aborted: boolean
+}
+
+/**
+ * Run the "Discard all" sequence for a given area.
+ *
+ * For 'staged', this first bulk-unstages the paths — without that step,
+ * `discardOne` (which maps to `git restore --worktree --source=HEAD`) would
+ * reset the working tree to HEAD but leave the index carrying the staged
+ * delta, producing phantom inverse "Changes" rows the user thought they just
+ * discarded. If the unstage fails we MUST skip the discard loop entirely for
+ * the same reason: a stale index with a clean worktree is a worse state than
+ * the one the user started in.
+ *
+ * Per-file `discardOne` failures are best-effort: we continue past a failed
+ * file so a single stuck path does not block the rest of the bulk action.
+ * Failed paths are reported via `failed`, `onError` is invoked once per
+ * failure, and `aborted` remains `false` because the loop ran end-to-end.
+ */
+export async function runDiscardAllForArea(
+  area: DiscardAllArea,
+  paths: readonly string[],
+  deps: DiscardAllDeps
+): Promise<DiscardAllResult> {
+  if (paths.length === 0) {
+    return { discarded: [], failed: [], aborted: false }
+  }
+
+  if (area === 'staged') {
+    try {
+      await deps.bulkUnstage([...paths])
+    } catch (error) {
+      deps.onError?.(error)
+      return { discarded: [], failed: [], aborted: true }
+    }
+  }
+
+  const discarded: string[] = []
+  const failed: string[] = []
+  for (const path of paths) {
+    try {
+      await deps.discardOne(path)
+      discarded.push(path)
+    } catch (error) {
+      // Best-effort: record and continue so one stuck file doesn't block the
+      // rest of the bulk action.
+      failed.push(path)
+      deps.onError?.(error)
+    }
+  }
+  return { discarded, failed, aborted: false }
+}
diff --git a/src/renderer/src/components/settings/AccountsPane.tsx b/src/renderer/src/components/settings/AccountsPane.tsx
index 8a99966cebe..b503998e3b3 100644
--- a/src/renderer/src/components/settings/AccountsPane.tsx
+++ b/src/renderer/src/components/settings/AccountsPane.tsx
@@ -428,7 +428,16 @@ export function AccountsPane({ settings, updateSettings }: AccountsPaneProps): R
         <SearchableSetting
           title="Codex Accounts"
           description="Manage which Codex account Orca uses for live rate limit fetching."
-          keywords={['codex', 'account', 'rate limit', 'status bar', 'quota']}
+          // Why: this single SearchableSetting backs the whole Codex section,
+          // including the "Active Codex Account" sub-control (account picker
+          // below). Roll every Codex search entry's title/description/keywords
+          // into one haystack so a search for "Active Codex Account" doesn't
+          // render the section header with no body underneath it.
+          keywords={ACCOUNTS_CODEX_SEARCH_ENTRIES.flatMap((entry) => [
+            entry.title,
+            entry.description ?? '',
+            ...(entry.keywords ?? [])
+          ])}
           className="space-y-3 px-1 py-2"
         >
           {/* Why: Settings deep-links can target this subsection directly from
diff --git a/src/renderer/src/components/settings/AppearancePane.tsx b/src/renderer/src/components/settings/AppearancePane.tsx
index 4642d550877..295daf5ef97 100644
--- a/src/renderer/src/components/settings/AppearancePane.tsx
+++ b/src/renderer/src/components/settings/AppearancePane.tsx
@@ -5,11 +5,14 @@ import { UIZoomControl } from './UIZoomControl'
 import { SearchableSetting } from './SearchableSetting'
 import { matchesSettingsSearch, type SettingsSearchEntry } from './settings-search'
 import { useAppStore } from '../../store'
+import { FontAutocomplete } from './SettingsFormControls'
+import { DEFAULT_APP_FONT_FAMILY } from '../../../../shared/constants'
 
 type AppearancePaneProps = {
   settings: GlobalSettings
   updateSettings: (updates: Partial<GlobalSettings>) => void
   applyTheme: (theme: 'system' | 'dark' | 'light') => void
+  fontSuggestions: string[]
 }
 
 const STATUS_BAR_TOGGLES: readonly {
@@ -56,18 +59,24 @@ const STATUS_BAR_TOGGLES: readonly {
       'Show the active SSH connection. Only visible once an SSH target is configured.'
   },
   {
-    id: 'sessions',
-    title: 'Terminal Sessions',
-    description: 'Show the terminal session count in the status bar.',
-    keywords: ['status bar', 'terminal', 'sessions', 'count', 'pty'],
-    toggleDescription: 'Show the number of active terminal sessions across all workspaces.'
-  },
-  {
-    id: 'memory',
-    title: 'Memory Monitoring',
-    description: 'Show memory and CPU usage in the status bar.',
-    keywords: ['status bar', 'memory', 'ram', 'cpu', 'monitoring', 'usage', 'performance'],
-    toggleDescription: 'Show total memory and CPU usage. Click it to see a per-workspace breakdown.'
+    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'
+    ],
+    toggleDescription:
+      'Show CPU, memory, and terminal session counts. Click it for a per-workspace breakdown and daemon controls.'
   }
 ]
 
@@ -87,6 +96,14 @@ const ZOOM_ENTRIES: SettingsSearchEntry[] = [
   }
 ]
 
+const TYPOGRAPHY_ENTRIES: SettingsSearchEntry[] = [
+  {
+    title: 'IDE Font',
+    description: 'Choose the font used by the Orca interface.',
+    keywords: ['font', 'typeface', 'typography', 'ide', 'orca', 'interface', 'app', 'ui']
+  }
+]
+
 const LAYOUT_ENTRIES: SettingsSearchEntry[] = [
   {
     title: 'Open Right Sidebar by Default',
@@ -117,6 +134,7 @@ const SIDEBAR_ENTRIES: SettingsSearchEntry[] = [
 
 export const APPEARANCE_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
   ...THEME_ENTRIES,
+  ...TYPOGRAPHY_ENTRIES,
   ...ZOOM_ENTRIES,
   ...LAYOUT_ENTRIES,
   ...TITLEBAR_ENTRIES,
@@ -127,7 +145,8 @@ export const APPEARANCE_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
 export function AppearancePane({
   settings,
   updateSettings,
-  applyTheme
+  applyTheme,
+  fontSuggestions
 }: AppearancePaneProps): React.JSX.Element {
   const searchQuery = useAppStore((state) => state.settingsSearchQuery)
   const isMac = navigator.userAgent.includes('Mac')
@@ -191,6 +210,33 @@ export function AppearancePane({
         </SearchableSetting>
       </section>
     ) : null,
+    matchesSettingsSearch(searchQuery, TYPOGRAPHY_ENTRIES) ? (
+      <section key="typography" className="space-y-4">
+        <div className="space-y-1">
+          <h3 className="text-sm font-semibold">Typography</h3>
+          <p className="text-xs text-muted-foreground">
+            Choose the font used by the Orca interface.
+          </p>
+        </div>
+
+        <SearchableSetting
+          title="IDE Font"
+          description="Choose the font used by the Orca interface."
+          keywords={['font', 'typeface', 'typography', 'ide', 'orca', 'interface', 'app', 'ui']}
+          className="space-y-2"
+        >
+          <Label>IDE Font</Label>
+          <FontAutocomplete
+            value={settings.appFontFamily}
+            suggestions={fontSuggestions}
+            placeholder={DEFAULT_APP_FONT_FAMILY}
+            onChange={(value) =>
+              updateSettings({ appFontFamily: value.trim() || DEFAULT_APP_FONT_FAMILY })
+            }
+          />
+        </SearchableSetting>
+      </section>
+    ) : null,
     matchesSettingsSearch(searchQuery, LAYOUT_ENTRIES) ? (
       <section key="layout" className="space-y-4">
         <div className="space-y-1">
diff --git a/src/renderer/src/components/settings/ExperimentalPane.tsx b/src/renderer/src/components/settings/ExperimentalPane.tsx
index 8046ab172db..900607f016d 100644
--- a/src/renderer/src/components/settings/ExperimentalPane.tsx
+++ b/src/renderer/src/components/settings/ExperimentalPane.tsx
@@ -73,6 +73,9 @@ export function ExperimentalPane({
   const showOrchestration = matchesSettingsSearch(searchQuery, [
     EXPERIMENTAL_PANE_SEARCH_ENTRIES[3]
   ])
+  const showWorktreeSymlinks = matchesSettingsSearch(searchQuery, [
+    EXPERIMENTAL_PANE_SEARCH_ENTRIES[4]
+  ])
 
   const [orchestrationEnabled, setOrchestrationEnabled] = useState<boolean>(() => {
     return localStorage.getItem('orca.orchestration.enabled') === '1'
@@ -228,7 +231,7 @@ export function ExperimentalPane({
                   // when cutting a new mobile-v* tag.
                   onClick={() =>
                     void window.api.shell.openUrl(
-                      'https://github.com/stablyai/orca/releases/tag/mobile-v0.0.1'
+                      'https://github.com/stablyai/orca/releases/tag/mobile-v0.0.2'
                     )
                   }
                   className="cursor-pointer underline underline-offset-2 hover:text-foreground"
@@ -387,6 +390,44 @@ export function ExperimentalPane({
         </SearchableSetting>
       ) : null}
 
+      {showWorktreeSymlinks ? (
+        <SearchableSetting
+          title="Symlinks on worktrees"
+          description="Automatically symlink configured files or folders into newly created worktrees."
+          keywords={EXPERIMENTAL_PANE_SEARCH_ENTRIES[4].keywords}
+          className="space-y-3 px-1 py-2"
+        >
+          <div className="flex items-start justify-between gap-4">
+            <div className="min-w-0 shrink space-y-0.5">
+              <Label>Symlinks on worktrees</Label>
+              <p className="text-xs text-muted-foreground">
+                Allows for automatic symlinks of certain folders or files that must be connected to
+                created worktrees.
+              </p>
+            </div>
+            <button
+              type="button"
+              role="switch"
+              aria-checked={settings.experimentalWorktreeSymlinks}
+              onClick={() =>
+                updateSettings({
+                  experimentalWorktreeSymlinks: !settings.experimentalWorktreeSymlinks
+                })
+              }
+              className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-colors ${
+                settings.experimentalWorktreeSymlinks ? 'bg-foreground' : 'bg-muted-foreground/30'
+              }`}
+            >
+              <span
+                className={`inline-block h-3.5 w-3.5 transform rounded-full bg-background shadow-sm transition-transform ${
+                  settings.experimentalWorktreeSymlinks ? 'translate-x-4' : 'translate-x-0.5'
+                }`}
+              />
+            </button>
+          </div>
+        </SearchableSetting>
+      ) : null}
+
       {hiddenExperimentalUnlocked ? <HiddenExperimentalGroup /> : null}
     </div>
   )
diff --git a/src/renderer/src/components/settings/GeneralPane.tsx b/src/renderer/src/components/settings/GeneralPane.tsx
index 2622fa97316..5eaf6e1a287 100644
--- a/src/renderer/src/components/settings/GeneralPane.tsx
+++ b/src/renderer/src/components/settings/GeneralPane.tsx
@@ -422,7 +422,15 @@ export function GeneralPane({ settings, updateSettings }: GeneralPaneProps): Rea
         <SearchableSetting
           title="Cache Timer"
           description="Show a countdown after a Claude agent becomes idle."
-          keywords={['cache', 'timer', 'prompt', 'ttl', 'claude']}
+          // Why: this is the primary control for the section gated by
+          // GENERAL_CACHE_TIMER_SEARCH_ENTRIES (title "Prompt Cache Timer").
+          // Mirroring those keywords keeps a search for "Prompt Cache Timer"
+          // from rendering the section header with no body underneath.
+          keywords={GENERAL_CACHE_TIMER_SEARCH_ENTRIES.flatMap((entry) => [
+            entry.title,
+            entry.description ?? '',
+            ...(entry.keywords ?? [])
+          ])}
           className="flex items-center justify-between gap-4 px-1 py-2"
         >
           <div className="space-y-0.5">
diff --git a/src/renderer/src/components/settings/ManageSessionsSection.tsx b/src/renderer/src/components/settings/ManageSessionsSection.tsx
index ffdc4f879a5..79e8de123d8 100644
--- a/src/renderer/src/components/settings/ManageSessionsSection.tsx
+++ b/src/renderer/src/components/settings/ManageSessionsSection.tsx
@@ -17,16 +17,15 @@ import {
 } from '../ui/dialog'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
 import { SearchableSetting } from './SearchableSetting'
+import { MANAGE_SESSIONS_SEARCH_ENTRIES } from './terminal-search'
 import { useAppStore } from '../../store'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import { activateTabAndFocusPane } from '@/lib/activate-tab-and-focus-pane'
+import { useDaemonActions, DaemonActionDialog } from '../shared/useDaemonActions'
 
-type ConfirmKind = 'killAll' | 'restart' | 'killOne'
+type ConfirmKind = 'killOne'
 
-type PendingConfirm =
-  | { kind: 'killAll' }
-  | { kind: 'restart' }
-  | { kind: 'killOne'; session: PtyManagementSession }
-  | null
+type PendingConfirm = { kind: 'killOne'; session: PtyManagementSession } | null
 
 // Why: mirror the status-bar SessionsStatusSegment label style — last two
 // path segments joined by the platform separator, no ellipsis prefix. This
@@ -83,46 +82,16 @@ function getConfirmCopy(confirm: PendingConfirm): {
   if (!confirm) {
     return null
   }
-  switch (confirm.kind) {
-    case 'killAll':
-      return {
-        title: 'Kill all terminal sessions?',
-        description: (
-          <>
-            This force-quits every running terminal pane across all workspaces. Any unsaved work in
-            those sessions is lost. The daemon itself keeps running, and new terminals can be opened
-            immediately. This can&apos;t be undone.
-          </>
-        ),
-        confirmLabel: 'Kill all sessions',
-        busyLabel: 'Killing…'
-      }
-    case 'restart':
-      return {
-        title: 'Restart the terminal daemon?',
-        description: (
-          <>
-            Kills every running terminal pane and restarts the daemon process. Panes show
-            &ldquo;Process exited&rdquo; and can be reopened immediately. Legacy-protocol sessions
-            from a previous app version are preserved. This can&apos;t be undone.
-          </>
-        ),
-        confirmLabel: 'Restart daemon',
-        busyLabel: 'Restarting…'
-      }
-    case 'killOne':
-      return {
-        title: 'Kill this session?',
-        description: (
-          <>
-            Force-quits{' '}
-            <span className="font-medium text-foreground">{confirm.session.sessionId}</span>. Any
-            unsaved work in that pane is lost. This can&apos;t be undone.
-          </>
-        ),
-        confirmLabel: 'Kill session',
-        busyLabel: 'Killing…'
-      }
+  return {
+    title: 'Kill this session?',
+    description: (
+      <>
+        Force-quits <span className="font-medium text-foreground">{confirm.session.sessionId}</span>
+        . Any unsaved work in that pane is lost. This can&apos;t be undone.
+      </>
+    ),
+    confirmLabel: 'Kill session',
+    busyLabel: 'Killing…'
   }
 }
 
@@ -154,7 +123,6 @@ export function ManageSessionsSection(): React.JSX.Element {
   // entry points can't drift on what "go to this session" means.
   const tabsByWorktree = useAppStore((s) => s.tabsByWorktree)
   const ptyIdsByTabId = useAppStore((s) => s.ptyIdsByTabId)
-  const setActiveTab = useAppStore((s) => s.setActiveTab)
   const setActiveView = useAppStore((s) => s.setActiveView)
   const closeSettingsPage = useAppStore((s) => s.closeSettingsPage)
 
@@ -184,17 +152,20 @@ export function ManageSessionsSection(): React.JSX.Element {
       if (worktreeId) {
         // Why: match SessionsStatusSegment — route through the shared
         // activation path before switching tab so the worktree container
-        // is mounted by the time setActiveTab runs.
+        // is mounted by the time activateTabAndFocusPane runs.
         activateAndRevealWorktree(worktreeId)
       }
       setActiveView('terminal')
-      setActiveTab(tabId)
+      // Why: rows here only carry ptyId, and there's no selector that maps
+      // ptyId → numeric paneId for an unmounted tab. Pass null so the helper
+      // degrades to tab-only activation (no worse than prior behavior).
+      activateTabAndFocusPane(tabId, null)
       // Why: the status-bar version doesn't need this because it's already
       // rendered over the terminal surface; from the Settings pane the user
       // would otherwise land on their pane with the modal still covering it.
       closeSettingsPage()
     },
-    [tabIdToWorktreeId, setActiveView, setActiveTab, closeSettingsPage]
+    [tabIdToWorktreeId, setActiveView, closeSettingsPage]
   )
 
   useEffect(() => {
@@ -235,48 +206,30 @@ export function ManageSessionsSection(): React.JSX.Element {
 
   const sessionCount = sessions.length
 
-  const handleKillAll = useCallback(async () => {
-    setBusyKind('killAll')
-    mutationInFlight.current = true
-    optimisticRollback.current = sessions
-    setSessions([])
-    try {
-      const { killedCount, remainingCount } = await window.api.pty.management.killAll()
-      if (remainingCount > 0 && killedCount > 0) {
-        toast.warning(
-          `Killed ${killedCount} of ${killedCount + remainingCount} sessions. ${remainingCount} refused to exit.`
-        )
-      } else if (killedCount > 0) {
-        toast.success(`Killed ${killedCount} session${killedCount === 1 ? '' : 's'}.`)
-      } else if (remainingCount === 0) {
-        toast.info('No sessions running.')
-      } else {
-        toast.error(`${remainingCount} session${remainingCount === 1 ? '' : 's'} refused to exit.`)
-      }
-      mutationInFlight.current = false
-      await refresh()
-    } catch (err) {
-      // Why: the IPC rejected before the daemon could act — restore the list
-      // so the user isn't left staring at a blank table that doesn't reflect
-      // reality.
+  // Why: shared hook owns the daemon-wide restart + kill-all flows so the
+  // status-bar segment and this settings pane can't drift on copy, IPC calls,
+  // or the anti-dismiss guard. We pass lifecycle callbacks to keep the pane's
+  // optimistic setSessions([]) + rollback pattern local to the component.
+  const daemonActions = useDaemonActions({
+    onKillAllStart: () => {
+      mutationInFlight.current = true
+      optimisticRollback.current = sessions
+      setSessions([])
+    },
+    onKillAllError: () => {
       if (isMounted.current && optimisticRollback.current) {
         setSessions(optimisticRollback.current)
       }
-      toast.error('Couldn’t kill sessions.', {
-        description: err instanceof Error ? err.message : undefined
-      })
-    } finally {
+    },
+    onKillAllSettled: () => {
       optimisticRollback.current = null
       mutationInFlight.current = false
-      if (isMounted.current) {
-        setBusyKind(null)
-        // Why: the dialog stays open during the mutation so the user sees the
-        // spinner + busyLabel and can't dismiss mid-flight (see Dialog guard
-        // below). Close it here when the op actually finishes.
-        setConfirm(null)
-      }
+      void refresh()
+    },
+    onRestartSettled: () => {
+      void refresh()
     }
-  }, [refresh, sessions])
+  })
 
   const handleKillOne = useCallback(
     async (session: PtyManagementSession) => {
@@ -308,54 +261,19 @@ export function ManageSessionsSection(): React.JSX.Element {
     [refresh]
   )
 
-  const handleRestart = useCallback(async () => {
-    setBusyKind('restart')
-    mutationInFlight.current = true
-    try {
-      const { success } = await window.api.pty.management.restart()
-      if (success) {
-        toast.success('Daemon restarted.')
-      } else {
-        toast.error('Restart failed — check logs.')
-      }
-      mutationInFlight.current = false
-      await refresh()
-    } catch (err) {
-      toast.error('Restart failed.', {
-        description: err instanceof Error ? err.message : undefined
-      })
-    } finally {
-      mutationInFlight.current = false
-      if (isMounted.current) {
-        setBusyKind(null)
-        setConfirm(null)
-      }
-    }
-  }, [refresh])
-
   // Why: do NOT clear `confirm` here — the dialog must stay open for the
   // duration of the mutation so the spinner + busyLabel render and the
-  // anti-dismiss guard can actually hold. Each handler's `finally` clears
+  // anti-dismiss guard can actually hold. handleKillOne's `finally` clears
   // `confirm` when the op resolves.
   const runConfirmed = useCallback(() => {
     if (!confirm) {
       return
     }
-    const pending = confirm
-    switch (pending.kind) {
-      case 'killAll':
-        void handleKillAll()
-        return
-      case 'restart':
-        void handleRestart()
-        return
-      case 'killOne':
-        void handleKillOne(pending.session)
-    }
-  }, [confirm, handleKillAll, handleKillOne, handleRestart])
+    void handleKillOne(confirm.session)
+  }, [confirm, handleKillOne])
 
   const copy = useMemo(() => getConfirmCopy(confirm), [confirm])
-  const isBusy = busyKind !== null
+  const isBusy = busyKind !== null || daemonActions.isBusy
 
   return (
     <section className="space-y-4">
@@ -368,9 +286,9 @@ export function ManageSessionsSection(): React.JSX.Element {
       </div>
 
       <SearchableSetting
-        title="Daemon sessions running"
-        description="Count of live PTY sessions across all workspaces."
-        keywords={['daemon', 'pty', 'sessions', 'manage', 'kill', 'restart', 'terminal']}
+        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"
       >
         {/* Why: full-width sessions card. The table *is* the primary
@@ -410,11 +328,11 @@ export function ManageSessionsSection(): React.JSX.Element {
                     variant="ghost"
                     size="icon-xs"
                     disabled={isBusy || sessionCount === 0}
-                    onClick={() => setConfirm({ kind: 'killAll' })}
+                    onClick={() => daemonActions.setPending('killAll')}
                     aria-label="Kill all sessions"
                     className="text-muted-foreground hover:text-destructive"
                   >
-                    {busyKind === 'killAll' ? (
+                    {daemonActions.busyKind === 'killAll' ? (
                       <LoaderCircle className="animate-spin" />
                     ) : (
                       <Trash2 />
@@ -431,11 +349,11 @@ export function ManageSessionsSection(): React.JSX.Element {
                     variant="ghost"
                     size="icon-xs"
                     disabled={isBusy}
-                    onClick={() => setConfirm({ kind: 'restart' })}
+                    onClick={() => daemonActions.setPending('restart')}
                     aria-label="Restart daemon"
                     className="text-muted-foreground"
                   >
-                    {busyKind === 'restart' ? (
+                    {daemonActions.busyKind === 'restart' ? (
                       <LoaderCircle className="animate-spin" />
                     ) : (
                       <RotateCw />
@@ -581,6 +499,7 @@ export function ManageSessionsSection(): React.JSX.Element {
           ) : null}
         </DialogContent>
       </Dialog>
+      <DaemonActionDialog api={daemonActions} />
     </section>
   )
 }
diff --git a/src/renderer/src/components/settings/MobilePane.tsx b/src/renderer/src/components/settings/MobilePane.tsx
index 2dcc31ee03e..8bbe42ba76f 100644
--- a/src/renderer/src/components/settings/MobilePane.tsx
+++ b/src/renderer/src/components/settings/MobilePane.tsx
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState } from 'react'
 import { toast } from 'sonner'
-import { Maximize2, RefreshCw, Trash2, Wifi } from 'lucide-react'
+import { Check, Copy, Maximize2, RefreshCw, Trash2, Wifi } from 'lucide-react'
 import { Button } from '../ui/button'
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '../ui/dialog'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
@@ -38,12 +38,14 @@ type NetworkInterface = {
 
 export function MobilePane(): React.JSX.Element {
   const [qrDataUrl, setQrDataUrl] = useState<string | null>(null)
+  const [pairingUrl, setPairingUrl] = useState<string | null>(null)
   const [endpoint, setEndpoint] = useState<string | null>(null)
   const [loading, setLoading] = useState(false)
   const [devices, setDevices] = useState<PairedDevice[]>([])
   const [qrEnlarged, setQrEnlarged] = useState(false)
   const [networkInterfaces, setNetworkInterfaces] = useState<NetworkInterface[]>([])
   const [selectedAddress, setSelectedAddress] = useState<string | undefined>(undefined)
+  const [codeCopied, setCodeCopied] = useState(false)
 
   const loadDevices = useCallback(async () => {
     try {
@@ -74,7 +76,9 @@ export function MobilePane(): React.JSX.Element {
       )
       if (result.available) {
         setQrDataUrl(result.qrDataUrl)
+        setPairingUrl(result.pairingUrl)
         setEndpoint(result.endpoint)
+        setCodeCopied(false)
         void loadDevices()
       } else {
         toast.error('WebSocket transport is not running')
@@ -110,6 +114,22 @@ export function MobilePane(): React.JSX.Element {
     return () => clearInterval(interval)
   }, [deviceCountAtQr, devices.length, loadDevices])
 
+  async function copyPairingCode() {
+    if (!pairingUrl) {
+      return
+    }
+    try {
+      // Why: Electron renderer's navigator.clipboard fails in some contexts
+      // (no transient activation, non-secure context). Use the main-process
+      // IPC clipboard which the rest of the app uses everywhere.
+      await window.api.ui.writeClipboardText(pairingUrl)
+      setCodeCopied(true)
+      setTimeout(() => setCodeCopied(false), 2000)
+    } catch {
+      toast.error('Failed to copy pairing code')
+    }
+  }
+
   async function revokeDevice(deviceId: string) {
     try {
       await window.api.mobile.revokeDevice({ deviceId })
@@ -177,6 +197,26 @@ export function MobilePane(): React.JSX.Element {
           <p className="text-muted-foreground max-w-xs text-center text-xs">
             Scan this code with the Orca mobile app. Each code creates a unique device token.
           </p>
+          {pairingUrl && (
+            <div className="flex w-full max-w-lg flex-col gap-1.5 px-4">
+              <div className="text-muted-foreground text-center text-xs">
+                Or paste this code in the mobile app:
+              </div>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => void copyPairingCode()}
+                className="font-mono text-[11px] leading-tight whitespace-normal break-all h-auto py-2 px-3"
+              >
+                <span className="flex-1 text-left">{pairingUrl}</span>
+                {codeCopied ? (
+                  <Check className="ml-2 size-3.5 shrink-0 text-emerald-500" />
+                ) : (
+                  <Copy className="ml-2 size-3.5 shrink-0" />
+                )}
+              </Button>
+            </div>
+          )}
         </div>
       )}
 
diff --git a/src/renderer/src/components/settings/NotificationsPane.tsx b/src/renderer/src/components/settings/NotificationsPane.tsx
index ea6809a0bd5..9d292123628 100644
--- a/src/renderer/src/components/settings/NotificationsPane.tsx
+++ b/src/renderer/src/components/settings/NotificationsPane.tsx
@@ -1,11 +1,12 @@
-import { type ReactNode } from 'react'
+import { type ReactNode, useState } from 'react'
 import { toast } from 'sonner'
 import type { GlobalSettings } from '../../../../shared/types'
 import { Button } from '../ui/button'
 import { Label } from '../ui/label'
 import { Separator } from '../ui/separator'
-import { BellRing, Bot, Siren } from 'lucide-react'
+import { BellRing, Bot, FileAudio, Siren, X } from 'lucide-react'
 import type { SettingsSearchEntry } from './settings-search'
+import { basename } from '@/lib/path'
 
 export const NOTIFICATIONS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
   {
@@ -28,6 +29,11 @@ export const NOTIFICATIONS_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
     description: 'Avoid notifying when Orca is focused on the active worktree.',
     keywords: ['notifications', 'focused', 'suppress', 'filtering']
   },
+  {
+    title: 'Custom Sound',
+    description: 'Choose one local audio file for all delivered desktop notifications.',
+    keywords: ['notifications', 'sound', 'audio', 'ogg', 'mp3', 'wav']
+  },
   {
     title: 'Send Test Notification',
     description: 'Trigger a sample desktop notification using the native delivery path.',
@@ -45,6 +51,7 @@ export function NotificationsPane({
   updateSettings
 }: NotificationsPaneProps): React.JSX.Element {
   const notificationSettings = settings.notifications
+  const [isPickingSound, setIsPickingSound] = useState(false)
 
   const updateNotificationSettings = (updates: Partial<GlobalSettings['notifications']>): void => {
     updateSettings({
@@ -58,10 +65,34 @@ export function NotificationsPane({
   const handleSendTestNotification = async (): Promise<void> => {
     const result = await window.api.notifications.dispatch({ source: 'test' })
     if (result.delivered) {
+      // Why: the Test button must always play through, even if the user clicks
+      // it twice in quick succession — the in-flight dedupe is for incidental
+      // bursts of real notifications, not for an explicit user action.
+      const soundResult = notificationSettings.customSoundPath
+        ? await window.api.notifications.playSound({ force: true })
+        : null
+      if (notificationSettings.customSoundPath && soundResult && !soundResult.played) {
+        toast.error('Custom notification sound could not be played')
+        return
+      }
       toast.success('Test notification sent')
     }
   }
 
+  const handleChooseSound = async (): Promise<void> => {
+    setIsPickingSound(true)
+    try {
+      const soundPath = await window.api.shell.pickAudio()
+      if (soundPath) {
+        updateNotificationSettings({ customSoundPath: soundPath })
+      }
+    } finally {
+      setIsPickingSound(false)
+    }
+  }
+
+  const selectedSoundPath = notificationSettings.customSoundPath
+
   return (
     <div className="space-y-1">
       <SettingToggle
@@ -101,6 +132,61 @@ export function NotificationsPane({
 
       <Separator />
 
+      <div className="space-y-2 px-1 py-2">
+        <div className="space-y-0.5">
+          <div className="flex items-center gap-2">
+            <FileAudio className="size-4" />
+            <Label>Custom Sound</Label>
+          </div>
+          <p className="text-xs text-muted-foreground">
+            One local audio file for all delivered desktop notifications.
+          </p>
+        </div>
+        <div className="flex min-w-0 flex-wrap items-center gap-2">
+          <div
+            className="min-h-8 min-w-0 flex-1 rounded-md border border-border/50 bg-muted/35 px-2.5 py-1.5"
+            title={selectedSoundPath ?? undefined}
+          >
+            {selectedSoundPath ? (
+              <div className="min-w-0">
+                <div className="truncate text-xs font-medium">{basename(selectedSoundPath)}</div>
+                <div className="truncate font-mono text-[11px] text-muted-foreground">
+                  {selectedSoundPath}
+                </div>
+              </div>
+            ) : (
+              <div className="text-xs text-muted-foreground">System notification sound</div>
+            )}
+          </div>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            disabled={!notificationSettings.enabled || isPickingSound}
+            onClick={() => void handleChooseSound()}
+            className="gap-2"
+          >
+            <FileAudio className="size-3.5" />
+            {selectedSoundPath ? 'Change' : 'Choose'}
+          </Button>
+          {selectedSoundPath ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              disabled={!notificationSettings.enabled}
+              onClick={() => updateNotificationSettings({ customSoundPath: null })}
+              className="gap-2"
+            >
+              <X className="size-3.5" />
+              Clear
+            </Button>
+          ) : null}
+        </div>
+      </div>
+
+      <Separator />
+
       <SettingToggle
         label="Suppress While Focused"
         description="Skip notifications when the triggering worktree is already visible."
diff --git a/src/renderer/src/components/settings/PrivacyPane.test.ts b/src/renderer/src/components/settings/PrivacyPane.test.ts
new file mode 100644
index 00000000000..7d1cb214298
--- /dev/null
+++ b/src/renderer/src/components/settings/PrivacyPane.test.ts
@@ -0,0 +1,223 @@
+// PrivacyPane tests. The contract pinned here:
+//
+//   1. Toggle wiring — the rendered toggle reflects `settings.telemetry.optedIn`.
+//   2. Blocked-state predicates:
+//      - `isEnvBlocked` — the env-only detector, used by `computeBlockedReason`.
+//      - `computeBlockedReason` — the full gate, including first-launch-
+//        pending reasons. Env-var wins over first-launch so the user sees
+//        the hard constraint named first.
+//   3. Env-var naming — `envVarNameForReason` names the specific variable.
+//
+// Keeping these as pure helpers lets tests cover them without a DOM
+// harness (this repo's vitest runs in node-env, so `useEffect` does not
+// fire under `renderToStaticMarkup`).
+
+import React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { GlobalSettings } from '../../../../shared/types'
+import type { TelemetryConsentState } from '../../../../shared/telemetry-consent-types'
+
+const { getConsentStateMock, setOptInMock } = vi.hoisted(() => ({
+  getConsentStateMock: vi.fn<() => Promise<TelemetryConsentState>>(),
+  setOptInMock: vi.fn<(optedIn: boolean) => Promise<void>>()
+}))
+vi.mock('../../lib/telemetry', () => ({
+  getConsentState: getConsentStateMock,
+  setOptIn: setOptInMock
+}))
+
+import { PrivacyPane, computeBlockedReason, envVarNameForReason, isEnvBlocked } from './PrivacyPane'
+
+function buildSettings(
+  telemetry: Partial<NonNullable<GlobalSettings['telemetry']>> = {}
+): GlobalSettings {
+  return {
+    telemetry: {
+      installId: 'test-install-id',
+      existedBeforeTelemetryRelease: false,
+      optedIn: true,
+      ...telemetry
+    }
+  } as unknown as GlobalSettings
+}
+
+describe('PrivacyPane — toggle markup reflects stored preference', () => {
+  beforeEach(() => {
+    getConsentStateMock.mockReset()
+    getConsentStateMock.mockResolvedValue({ effective: 'enabled' })
+  })
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('renders the toggle in its checked state when optedIn is true', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(PrivacyPane, {
+        settings: buildSettings({ optedIn: true })
+      })
+    )
+    expect(markup).toContain('aria-checked="true"')
+  })
+
+  it('renders the toggle unchecked when optedIn is false', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(PrivacyPane, {
+        settings: buildSettings({ optedIn: false })
+      })
+    )
+    expect(markup).toContain('aria-checked="false"')
+  })
+
+  it('renders the toggle unchecked when optedIn is null (existing user pre-banner)', () => {
+    // `optedIn === null` is the existing-user cohort awaiting the banner.
+    // No events transmit in that state; the Settings toggle should visibly
+    // read "off" so flipping it on routes through the 'settings' `via`
+    // path (not 'first_launch_banner', which is reserved for the banner).
+    const markup = renderToStaticMarkup(
+      React.createElement(PrivacyPane, {
+        settings: buildSettings({
+          existedBeforeTelemetryRelease: true,
+          optedIn: null
+        })
+      })
+    )
+    expect(markup).toContain('aria-checked="false"')
+  })
+})
+
+describe('PrivacyPane — isEnvBlocked', () => {
+  it('returns true for DO_NOT_TRACK', () => {
+    expect(isEnvBlocked({ effective: 'disabled', reason: 'do_not_track' })).toBe(true)
+  })
+
+  it('returns true for ORCA_TELEMETRY_DISABLED', () => {
+    expect(isEnvBlocked({ effective: 'disabled', reason: 'orca_disabled' })).toBe(true)
+  })
+
+  it('returns true for CI', () => {
+    expect(isEnvBlocked({ effective: 'disabled', reason: 'ci' })).toBe(true)
+  })
+
+  it('returns false for user_opt_out (not env-blocked — the toggle remains actionable)', () => {
+    // `user_opt_out` is a stored-preference state, not an env override.
+    // The toggle MUST stay enabled so the user can flip back on; getting
+    // this wrong would trap a user who opted out once inside an inert UI.
+    expect(isEnvBlocked({ effective: 'disabled', reason: 'user_opt_out' })).toBe(false)
+  })
+
+  it('returns false for pending_banner', () => {
+    expect(isEnvBlocked({ effective: 'pending_banner' })).toBe(false)
+  })
+
+  it('returns false for enabled', () => {
+    expect(isEnvBlocked({ effective: 'enabled' })).toBe(false)
+  })
+
+  it('returns false for null (consent not yet fetched)', () => {
+    expect(isEnvBlocked(null)).toBe(false)
+  })
+})
+
+describe('PrivacyPane — envVarNameForReason', () => {
+  it('maps do_not_track to DO_NOT_TRACK', () => {
+    expect(envVarNameForReason('do_not_track')).toBe('DO_NOT_TRACK')
+  })
+
+  it('maps orca_disabled to ORCA_TELEMETRY_DISABLED', () => {
+    expect(envVarNameForReason('orca_disabled')).toBe('ORCA_TELEMETRY_DISABLED')
+  })
+
+  it('maps ci to CI', () => {
+    expect(envVarNameForReason('ci')).toBe('CI')
+  })
+})
+
+describe('PrivacyPane — computeBlockedReason', () => {
+  it('returns null when consent is enabled', () => {
+    expect(computeBlockedReason({ effective: 'enabled' })).toBeNull()
+  })
+
+  it('returns null for a user_opt_out state (the toggle must remain actionable)', () => {
+    // A user who opted out must be able to flip back on from Settings.
+    expect(computeBlockedReason({ effective: 'disabled', reason: 'user_opt_out' })).toBeNull()
+  })
+
+  it('returns null for pending_banner (banner-pending does NOT gate the toggle)', () => {
+    // Flipping the Settings toggle is a valid way to resolve the notice:
+    // it moves `optedIn` off `null`, which un-mounts the banner on its own.
+    expect(computeBlockedReason({ effective: 'pending_banner' })).toBeNull()
+  })
+
+  it('names DO_NOT_TRACK as the env reason when set', () => {
+    const result = computeBlockedReason({ effective: 'disabled', reason: 'do_not_track' })
+    expect(result).toEqual({ kind: 'env', reason: 'do_not_track' })
+  })
+
+  it('names ORCA_TELEMETRY_DISABLED as the env reason when set', () => {
+    const result = computeBlockedReason({ effective: 'disabled', reason: 'orca_disabled' })
+    expect(result).toEqual({ kind: 'env', reason: 'orca_disabled' })
+  })
+
+  it('names CI as the env reason when set', () => {
+    const result = computeBlockedReason({ effective: 'disabled', reason: 'ci' })
+    expect(result).toEqual({ kind: 'env', reason: 'ci' })
+  })
+})
+
+describe('PrivacyPane — markup respects blocked state', () => {
+  // The useEffect that fetches consent does not run in renderToStaticMarkup
+  // (no DOM, no state flushes), so the rendered toggle always reads the
+  // `consent === null` branch of the effect. Env-var blocked-state markup
+  // is covered by the computeBlockedReason unit tests above; here we just
+  // confirm the toggle is live for the cohorts that should be able to flip
+  // it.
+  beforeEach(() => {
+    getConsentStateMock.mockReset()
+    getConsentStateMock.mockResolvedValue({ effective: 'enabled' })
+  })
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('leaves the toggle enabled for a new user', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(PrivacyPane, {
+        settings: buildSettings({
+          existedBeforeTelemetryRelease: false,
+          optedIn: true
+        })
+      })
+    )
+    // Negative assertion: the disabled attribute should not appear on the
+    // switch. renderToStaticMarkup elides `disabled={false}` entirely.
+    expect(markup).not.toMatch(/role="switch"[^>]*disabled/)
+  })
+
+  it('leaves the toggle enabled for an existing user awaiting the banner (flip dismisses the banner)', () => {
+    // Flipping the toggle moves `optedIn` off `null`, which un-mounts the
+    // notice via TelemetryFirstLaunchSurface's cohort check. The Settings
+    // toggle is one of the valid ways to resolve the notice.
+    const markup = renderToStaticMarkup(
+      React.createElement(PrivacyPane, {
+        settings: buildSettings({
+          existedBeforeTelemetryRelease: true,
+          optedIn: null
+        })
+      })
+    )
+    expect(markup).not.toMatch(/role="switch"[^>]*disabled/)
+  })
+
+  it('leaves the toggle enabled once the existing-user banner is resolved', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(PrivacyPane, {
+        settings: buildSettings({
+          existedBeforeTelemetryRelease: true,
+          optedIn: true
+        })
+      })
+    )
+    expect(markup).not.toMatch(/role="switch"[^>]*disabled/)
+  })
+})
diff --git a/src/renderer/src/components/settings/PrivacyPane.tsx b/src/renderer/src/components/settings/PrivacyPane.tsx
new file mode 100644
index 00000000000..56a126349ce
--- /dev/null
+++ b/src/renderer/src/components/settings/PrivacyPane.tsx
@@ -0,0 +1,247 @@
+// Privacy pane — the permanent surface for the telemetry opt-in toggle.
+// Two responsibilities:
+//   1. Flip `optedIn` when the user toggles the switch. All renderer-
+//      initiated opt-in flips route through `window.api.telemetrySetOptIn`;
+//      main derives the `via` tag and fires `telemetry_opted_in` /
+//      `telemetry_opted_out`.
+//   2. Render the correct "blocked by X" helper text when an environment
+//      variable (DO_NOT_TRACK, ORCA_TELEMETRY_DISABLED) or CI presence
+//      disables transmission at runtime. Env vars are main-side process
+//      state, so the pane reads effective consent via
+//      `telemetry:getConsentState`.
+//
+// The toggle is NOT gated while the existing-user notice is pending — the
+// whole point of the pane is to let the user flip consent, and disabling
+// it would create a chicken-and-egg where the notice pushes the user at
+// Settings and the pane points back at the notice. Flipping the toggle
+// moves `optedIn` off `null`, which un-mounts `TelemetryFirstLaunchSurface`
+// on its own — so "toggle in Settings" IS a way to dismiss the notice.
+//
+// Structural note: the pane mimics NotificationsPane / DeveloperPermissionsPane
+// — a small toggle-heavy surface with inline helper text. A single-row
+// "toggle + subtext" layout keeps this file UI-only; `captureException` /
+// `$identify` patterns were considered and rejected in the telemetry
+// Decision Record and are intentionally not used here.
+
+import { useEffect, useState } from 'react'
+import { ShieldCheck } from 'lucide-react'
+import type { GlobalSettings } from '../../../../shared/types'
+import type { TelemetryConsentState } from '../../../../shared/telemetry-consent-types'
+import { Label } from '../ui/label'
+import { PRIVACY_URL, getConsentState, setOptIn as telemetrySetOptIn } from '../../lib/telemetry'
+import { useAppStore } from '../../store'
+
+// Pure helpers, exported for direct test coverage. The component's
+// useEffect cannot be exercised in the node-env vitest harness (no DOM,
+// no act()), so we keep the blocked-state decision and the env-var name
+// mapping as plain functions that tests can call without rendering.
+export type EnvBlockedReason = 'do_not_track' | 'orca_disabled' | 'ci'
+
+// Reasons the toggle is read-only. Only env/CI overrides block the toggle:
+// they persist until the operator unsets the variable and relaunches, so
+// the user's flip cannot take effect until then. The existing-user notice
+// is NOT a blocked reason — flipping the toggle is one of the valid ways
+// to resolve it.
+export type BlockedReason = { kind: 'env'; reason: EnvBlockedReason }
+
+export function isEnvBlocked(consent: TelemetryConsentState | null): consent is {
+  effective: 'disabled'
+  reason: EnvBlockedReason
+} {
+  return (
+    consent?.effective === 'disabled' &&
+    (consent.reason === 'do_not_track' ||
+      consent.reason === 'orca_disabled' ||
+      consent.reason === 'ci')
+  )
+}
+
+export function envVarNameForReason(reason: EnvBlockedReason): string {
+  if (reason === 'do_not_track') {
+    return 'DO_NOT_TRACK'
+  }
+  if (reason === 'orca_disabled') {
+    return 'ORCA_TELEMETRY_DISABLED'
+  }
+  return 'CI'
+}
+
+// Compute the reason the toggle should be inert, if any. Only env-var /
+// CI overrides block the toggle — they persist until the operator unsets
+// the variable and relaunches. The existing-user notice does not gate the
+// toggle; flipping it is a valid way to resolve the notice.
+//
+// Exported for test coverage. The component renders helper text by
+// pattern-matching the returned shape.
+export function computeBlockedReason(consent: TelemetryConsentState | null): BlockedReason | null {
+  if (isEnvBlocked(consent)) {
+    return { kind: 'env', reason: consent.reason }
+  }
+  return null
+}
+
+// Stable id wired from the switch's `aria-describedby` to the blocked-state
+// helper text below it. Without this, screen-reader users hear "switch,
+// disabled" with no explanation of why the toggle is inert.
+const PRIVACY_PANE_BLOCKED_HELPER_ID = 'privacy-pane-blocked-helper'
+
+type PrivacyPaneProps = {
+  settings: GlobalSettings
+}
+
+export function PrivacyPane({ settings }: PrivacyPaneProps): React.JSX.Element {
+  const [consent, setConsent] = useState<TelemetryConsentState | null>(null)
+  // Double-click guard. Main's `setOptIn` has no idempotence check; without
+  // this guard a fast double-click would fire two
+  // `telemetry_opted_{in,out}` events for one user intent. The handler
+  // derives `nextOptedIn` from `toggleChecked`, which is computed from
+  // `settings.telemetry?.optedIn`. Main's `telemetry:setOptIn` handler
+  // intentionally does NOT broadcast `settings:changed` on telemetry writes
+  // (telemetry writes stay silent at the settings-event layer so unrelated
+  // subscribers never re-render on a telemetry flip), so after
+  // `telemetrySetOptIn` resolves we explicitly call
+  // `fetchSettings()` to sync the renderer store. This ensures the next
+  // click sees the updated `toggleChecked` and does not re-fire the same
+  // opt-{in,out} intent against the user's already-persisted choice; the
+  // `inFlight` flag guards only the window between the click and that
+  // refetch completing.
+  const [inFlight, setInFlight] = useState(false)
+  const fetchSettings = useAppStore((s) => s.fetchSettings)
+
+  // Pull the effective consent state on mount and again when the user
+  // interacts with the toggle — env-var status does not change within a
+  // session, but a toggle flip changes the `user_opt_out` branch so the
+  // helper text needs to refresh. Polling is not needed; the pane is
+  // self-contained and the env-var branch is stable for the session.
+  useEffect(() => {
+    let stale = false
+    void getConsentState().then((state) => {
+      if (!stale) {
+        setConsent(state)
+      }
+    })
+    return () => {
+      stale = true
+    }
+  }, [settings.telemetry?.optedIn])
+
+  const blocked = computeBlockedReason(consent)
+
+  // Display the user's stored preference, not the effective state. An env
+  // var blocks transmission without overwriting the persisted preference
+  // (consent.ts:6-8 is explicit about this), so the toggle should still
+  // reflect "what the user chose" and the helper text explains why it's
+  // inactive. `optedIn === null` (existing user pre-banner) reads as off
+  // because no events are transmitting.
+  const toggleChecked = settings.telemetry?.optedIn === true
+
+  const handleToggle = async (): Promise<void> => {
+    if (blocked || inFlight) {
+      // Belt-and-suspenders: the button is disabled when env/CI overrides
+      // block transmission, but the click handler is the single source of
+      // truth for "did the user actually flip consent?" If a CSS or a11y
+      // bug ever makes the disabled button clickable, we must not route a
+      // flip through `telemetrySetOptIn` against an env-blocked state. The
+      // `inFlight` arm additionally suppresses duplicate sends while a
+      // previous flip is still round-tripping through IPC.
+      return
+    }
+    setInFlight(true)
+    const nextOptedIn = !toggleChecked
+    // Route through `telemetrySetOptIn` (NOT `settings:set` alone).
+    // `settings:set` persists the flip but skips `telemetry_opted_in/out`
+    // emission and the PostHog SDK's in-memory optIn / optOut flip. Main's
+    // `setOptIn` writes the preference, emits the event with
+    // `via='settings'`, and flips the SDK flag — all in the right order
+    // (opt-out event BEFORE posthog.optOut).
+    try {
+      await telemetrySetOptIn(nextOptedIn)
+      // Why: main's telemetry:setOptIn handler intentionally does NOT
+      // broadcast `settings:changed` — the invariant is that telemetry
+      // writes stay silent at the settings-event layer. But the Privacy
+      // pane derives `toggleChecked` from `settings.telemetry?.optedIn`,
+      // so without an explicit refresh the toggle would stay stuck on its
+      // pre-flip value. Refetch here so the next click sees the updated
+      // state and does not re-fire the same opt-{in,out} event against
+      // the user's already-persisted choice.
+      await fetchSettings()
+    } finally {
+      setInFlight(false)
+    }
+  }
+
+  return (
+    <div className="space-y-1">
+      <div className="flex items-center justify-between gap-4 px-1 py-2">
+        <div className="space-y-0.5">
+          <div className="flex items-center gap-2">
+            <ShieldCheck className="size-4" />
+            <Label>Share anonymous usage data</Label>
+          </div>
+          <p className="text-xs text-muted-foreground">
+            Help us figure out what to build next. Orca sends anonymous counts of which features you
+            use and where things break — no file contents, prompts, terminal output, branch names,
+            or anything that identifies you.{' '}
+            <button
+              type="button"
+              className="underline underline-offset-2 hover:text-foreground"
+              onClick={() => void window.api.shell.openUrl(PRIVACY_URL)}
+            >
+              Privacy policy
+            </button>
+            .
+          </p>
+        </div>
+        <button
+          role="switch"
+          aria-checked={toggleChecked}
+          aria-label="Share anonymous usage data"
+          aria-describedby={blocked ? PRIVACY_PANE_BLOCKED_HELPER_ID : undefined}
+          disabled={blocked !== null || inFlight}
+          onClick={handleToggle}
+          className={`relative inline-flex h-5 w-9 shrink-0 items-center rounded-full border border-transparent transition-colors ${
+            toggleChecked ? 'bg-foreground' : 'bg-muted-foreground/30'
+          } ${blocked !== null || inFlight ? 'cursor-not-allowed opacity-50' : 'cursor-pointer'}`}
+        >
+          <span
+            className={`pointer-events-none block size-3.5 rounded-full bg-background shadow-sm transition-transform ${
+              toggleChecked ? 'translate-x-4' : 'translate-x-0.5'
+            }`}
+          />
+        </button>
+      </div>
+
+      {blocked ? <BlockedHelper blocked={blocked} id={PRIVACY_PANE_BLOCKED_HELPER_ID} /> : null}
+    </div>
+  )
+}
+
+// Per-reason copy for the env/CI blocked states. The pane is accessible
+// only once the app boots past CI detection, so `ci` is rare on a
+// desktop install — but it's included for symmetry with the resolver.
+function BlockedHelper({ blocked, id }: { blocked: BlockedReason; id: string }): React.JSX.Element {
+  return (
+    <div id={id} className="px-1 pb-2 text-xs text-muted-foreground">
+      <EnvHelperBody reason={blocked.reason} />
+    </div>
+  )
+}
+
+function EnvHelperBody({ reason }: { reason: EnvBlockedReason }): React.JSX.Element {
+  if (reason === 'ci') {
+    return (
+      <p>
+        Telemetry is disabled because a CI environment variable is set. Unset it and restart to
+        re-enable.
+      </p>
+    )
+  }
+  const varName = envVarNameForReason(reason)
+  return (
+    <p>
+      Telemetry is disabled by the{' '}
+      <code className="rounded bg-muted px-1 py-0.5 font-mono text-[11px]">{varName}</code>{' '}
+      environment variable. Unset it and restart to re-enable.
+    </p>
+  )
+}
diff --git a/src/renderer/src/components/settings/RepositoryPane.tsx b/src/renderer/src/components/settings/RepositoryPane.tsx
index 8d266a9fef2..8f335364bb0 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 { WorktreeSymlinksSection } from './WorktreeSymlinksSection'
 import { SparsePresetSettingsSection } from './SparsePresetSettingsSection'
 import { SearchableSetting } from './SearchableSetting'
 import { matchesSettingsSearch, type SettingsSearchEntry } from './settings-search'
@@ -68,6 +69,20 @@ export function getRepositoryPaneSearchEntries(repo: Repo): SettingsSearchEntry[
     ...(isFolder
       ? []
       : [
+          {
+            title: 'Worktree Symlinks',
+            description: 'Paths to symlink from the primary checkout into newly created worktrees.',
+            keywords: [
+              repo.displayName,
+              'symlink',
+              'symlinks',
+              'worktree',
+              'link',
+              'shared',
+              'env',
+              'node_modules'
+            ]
+          },
           {
             title: 'orca.yaml hooks',
             description: 'Shared setup and archive hook commands for this repository.',
@@ -117,6 +132,7 @@ export function RepositoryPane({
 }: RepositoryPaneProps): React.JSX.Element {
   const isFolder = isFolderRepo(repo)
   const searchQuery = useAppStore((state) => state.settingsSearchQuery)
+  const symlinksEnabled = useAppStore((state) => state.settings?.experimentalWorktreeSymlinks)
   const [confirmingRemove, setConfirmingRemove] = useState<string | null>(null)
   const [copiedTemplate, setCopiedTemplate] = useState(false)
 
@@ -190,6 +206,7 @@ export function RepositoryPane({
       'Custom GitHub Issue Command'
     ].includes(entry.title)
   )
+  const symlinkEntries = allEntries.filter((entry) => entry.title === 'Worktree Symlinks')
 
   const visibleSections = [
     matchesSettingsSearch(searchQuery, identityEntries) ? (
@@ -287,6 +304,12 @@ export function RepositoryPane({
         ) : null}
       </section>
     ) : null,
+    !isFolder &&
+    !repo.connectionId &&
+    symlinksEnabled &&
+    matchesSettingsSearch(searchQuery, symlinkEntries) ? (
+      <WorktreeSymlinksSection key="symlinks" repo={repo} updateRepo={updateRepo} />
+    ) : null,
     !isFolder && matchesSettingsSearch(searchQuery, sparsePresetEntries) ? (
       <SparsePresetSettingsSection key="sparse-presets" repoId={repo.id} />
     ) : null,
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 9e1ad0209e0..089ef8e400d 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -8,6 +8,7 @@ import {
   GitBranch,
   Globe,
   Keyboard,
+  Lock,
   ShieldCheck,
   Palette,
   Server,
@@ -21,7 +22,9 @@ import { getRepoKindLabel, isFolderRepo } from '../../../../shared/repo-kind'
 import { useAppStore } from '../../store'
 import { useSystemPrefersDark } from '@/components/terminal-pane/use-system-prefers-dark'
 import { isMacUserAgent, isWindowsUserAgent } from '@/components/terminal-pane/pane-helpers'
+import { applyDocumentTheme } from '@/lib/document-theme'
 import { SCROLLBACK_PRESETS_MB, getFallbackTerminalFonts } from './SettingsConstants'
+import { DEFAULT_APP_FONT_FAMILY } from '../../../../shared/constants'
 import { GeneralPane, GENERAL_PANE_SEARCH_ENTRIES } from './GeneralPane'
 import { BrowserPane, BROWSER_PANE_SEARCH_ENTRIES } from './BrowserPane'
 import { AppearancePane, APPEARANCE_PANE_SEARCH_ENTRIES } from './AppearancePane'
@@ -44,6 +47,8 @@ import {
   DeveloperPermissionsPane,
   DEVELOPER_PERMISSIONS_PANE_SEARCH_ENTRIES
 } from './DeveloperPermissionsPane'
+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'
@@ -58,6 +63,7 @@ type SettingsNavTarget =
   | 'terminal'
   | 'notifications'
   | 'developer-permissions'
+  | 'privacy'
   | 'shortcuts'
   | 'stats'
   | 'ssh'
@@ -176,8 +182,8 @@ function Settings(): React.JSX.Element {
     void window.api.wsl.isAvailable().then(setWslAvailable)
     void window.api.pwsh.isAvailable().then(setPwshAvailable)
   }, [isWindows])
-  const [terminalFontSuggestions, setTerminalFontSuggestions] = useState<string[]>(
-    getFallbackTerminalFonts()
+  const [fontSuggestions, setFontSuggestions] = useState<string[]>(
+    Array.from(new Set([DEFAULT_APP_FONT_FAMILY, ...getFallbackTerminalFonts()]))
   )
   const [activeSectionId, setActiveSectionId] = useState('general')
   // Why: the hidden-experimental group is an unlock — Shift-clicking the
@@ -186,6 +192,7 @@ function Settings(): React.JSX.Element {
   // leak through into a normal reopen of Settings.
   const [hiddenExperimentalUnlocked, setHiddenExperimentalUnlocked] = useState(false)
   const contentScrollRef = useRef<HTMLDivElement | null>(null)
+  const searchInputRef = useRef<HTMLInputElement | null>(null)
   const terminalFontsLoadedRef = useRef(false)
   const pendingNavSectionRef = useRef<string | null>(null)
   const pendingScrollTargetRef = useRef<string | null>(null)
@@ -214,6 +221,30 @@ function Settings(): React.JSX.Element {
     return () => document.removeEventListener('keydown', handleKeyDown)
   }, [closeSettingsPage])
 
+  useEffect(() => {
+    const handleFindShortcut = (event: KeyboardEvent): void => {
+      if (event.defaultPrevented || event.altKey || event.shiftKey) {
+        return
+      }
+      // Why: Cmd on Mac, Ctrl elsewhere — matches the rest of the app's
+      // mod-key convention (see App.tsx) and aligns with platform Find norms.
+      const mod = isMac ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey
+      if (!mod || event.key.toLowerCase() !== 'f') {
+        return
+      }
+      const input = searchInputRef.current
+      if (!input) {
+        return
+      }
+      event.preventDefault()
+      input.focus()
+      input.select()
+    }
+
+    document.addEventListener('keydown', handleFindShortcut)
+    return () => document.removeEventListener('keydown', handleFindShortcut)
+  }, [isMac])
+
   useEffect(
     () => () => {
       // Why: the settings search is a transient in-page filter. Leaving it behind makes the next
@@ -251,7 +282,9 @@ function Settings(): React.JSX.Element {
           return
         }
         terminalFontsLoadedRef.current = true
-        setTerminalFontSuggestions((prev) => Array.from(new Set([...fonts, ...prev])).slice(0, 320))
+        setFontSuggestions((prev) =>
+          Array.from(new Set([DEFAULT_APP_FONT_FAMILY, ...fonts, ...prev])).slice(0, 320)
+        )
       } catch {
         // Fall back to curated cross-platform suggestions.
       }
@@ -318,19 +351,7 @@ function Settings(): React.JSX.Element {
   }, [repos])
 
   const applyTheme = useCallback((theme: 'system' | 'dark' | 'light') => {
-    const root = document.documentElement
-    if (theme === 'dark') {
-      root.classList.add('dark')
-    } else if (theme === 'light') {
-      root.classList.remove('dark')
-    } else {
-      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
-      if (prefersDark) {
-        root.classList.add('dark')
-      } else {
-        root.classList.remove('dark')
-      }
-    }
+    applyDocumentTheme(theme)
   }, [])
 
   const displayedGitUsername = repos[0]?.gitUsername ?? ''
@@ -404,6 +425,13 @@ function Settings(): React.JSX.Element {
             }
           ]
         : []),
+      {
+        id: 'privacy',
+        title: 'Privacy & Telemetry',
+        description: 'Anonymous usage data and telemetry controls.',
+        icon: Lock,
+        searchEntries: PRIVACY_PANE_SEARCH_ENTRIES
+      },
       {
         id: 'shortcuts',
         title: 'Shortcuts',
@@ -600,6 +628,7 @@ function Settings(): React.JSX.Element {
         repoSections={repoNavSections}
         hasRepos={repos.length > 0}
         searchQuery={settingsSearchQuery}
+        searchInputRef={searchInputRef}
         onBack={closeSettingsPage}
         onSearchChange={setSettingsSearchQuery}
         onSelectSection={scrollToSection}
@@ -673,6 +702,7 @@ function Settings(): React.JSX.Element {
                     settings={settings}
                     updateSettings={updateSettings}
                     applyTheme={applyTheme}
+                    fontSuggestions={fontSuggestions}
                   />
                 </SettingsSection>
 
@@ -697,7 +727,7 @@ function Settings(): React.JSX.Element {
                     settings={settings}
                     updateSettings={updateSettings}
                     systemPrefersDark={systemPrefersDark}
-                    terminalFontSuggestions={terminalFontSuggestions}
+                    terminalFontSuggestions={fontSuggestions}
                     scrollbackMode={scrollbackMode}
                     setScrollbackMode={setScrollbackMode}
                     ghostty={ghostty}
@@ -735,6 +765,15 @@ function Settings(): React.JSX.Element {
                   </SettingsSection>
                 ) : null}
 
+                <SettingsSection
+                  id="privacy"
+                  title="Privacy & Telemetry"
+                  description="Anonymous usage data and telemetry controls."
+                  searchEntries={PRIVACY_PANE_SEARCH_ENTRIES}
+                >
+                  <PrivacyPane settings={settings} />
+                </SettingsSection>
+
                 <SettingsSection
                   id="shortcuts"
                   title="Shortcuts"
diff --git a/src/renderer/src/components/settings/SettingsFormControls.tsx b/src/renderer/src/components/settings/SettingsFormControls.tsx
index b1ad300f1b6..737b5cb4eec 100644
--- a/src/renderer/src/components/settings/SettingsFormControls.tsx
+++ b/src/renderer/src/components/settings/SettingsFormControls.tsx
@@ -42,6 +42,7 @@ type FontAutocompleteProps = {
   value: string
   suggestions: string[]
   onChange: (value: string) => void
+  placeholder?: string
 }
 
 export function ThemePicker({
@@ -214,7 +215,8 @@ export function NumberField({
 export function FontAutocomplete({
   value,
   suggestions,
-  onChange
+  onChange,
+  placeholder = 'SF Mono'
 }: FontAutocompleteProps): React.JSX.Element {
   const [query, setQuery] = useState(value)
   const [prevValue, setPrevValue] = useState(value)
@@ -353,7 +355,7 @@ export function FontAutocomplete({
               }
             }
           }}
-          placeholder="SF Mono"
+          placeholder={placeholder}
           className="pr-18"
           role="combobox"
           aria-autocomplete="list"
diff --git a/src/renderer/src/components/settings/SettingsSidebar.tsx b/src/renderer/src/components/settings/SettingsSidebar.tsx
index b23d2c6553c..ba10f88c50b 100644
--- a/src/renderer/src/components/settings/SettingsSidebar.tsx
+++ b/src/renderer/src/components/settings/SettingsSidebar.tsx
@@ -1,7 +1,11 @@
+import type { RefObject } from 'react'
 import { ArrowLeft, Search, Server, type LucideIcon, type LucideProps } from 'lucide-react'
+import { isMacUserAgent } from '@/components/terminal-pane/pane-helpers'
 import { Button } from '../ui/button'
 import { Input } from '../ui/input'
 
+const SEARCH_SHORTCUT_HINT = isMacUserAgent() ? '⌘F' : 'Ctrl+F'
+
 type NavSection = {
   id: string
   title: string
@@ -20,6 +24,7 @@ type SettingsSidebarProps = {
   repoSections: RepoNavSection[]
   hasRepos: boolean
   searchQuery: string
+  searchInputRef?: RefObject<HTMLInputElement | null>
   onBack: () => void
   onSearchChange: (query: string) => void
   onSelectSection: (
@@ -34,6 +39,7 @@ export function SettingsSidebar({
   repoSections,
   hasRepos,
   searchQuery,
+  searchInputRef,
   onBack,
   onSearchChange,
   onSelectSection
@@ -56,11 +62,17 @@ export function SettingsSidebar({
         <div className="relative">
           <Search className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
           <Input
+            ref={searchInputRef}
             value={searchQuery}
             onChange={(event) => onSearchChange(event.target.value)}
             placeholder="Search settings"
-            className="pl-9"
+            className="pl-9 pr-14"
           />
+          {searchQuery === '' ? (
+            <kbd className="pointer-events-none absolute right-2 top-1/2 inline-flex -translate-y-1/2 items-center rounded border border-border/60 bg-background/40 px-1.5 py-px font-mono text-[10px] font-medium text-muted-foreground">
+              {SEARCH_SHORTCUT_HINT}
+            </kbd>
+          ) : null}
         </div>
       </div>
 
diff --git a/src/renderer/src/components/settings/WorktreeSymlinksSection.tsx b/src/renderer/src/components/settings/WorktreeSymlinksSection.tsx
new file mode 100644
index 00000000000..59a7fcc620e
--- /dev/null
+++ b/src/renderer/src/components/settings/WorktreeSymlinksSection.tsx
@@ -0,0 +1,201 @@
+import { useEffect, useMemo, useState } from 'react'
+import { File, Folder, Link2, Plus, X } from 'lucide-react'
+import type { Repo } from '../../../../shared/types'
+import { Button } from '../ui/button'
+import { Command, CommandEmpty, CommandInput, CommandItem, CommandList } from '../ui/command'
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
+import { cn } from '@/lib/utils'
+import { SearchableSetting } from './SearchableSetting'
+
+type WorktreeSymlinksSectionProps = {
+  repo: Repo
+  updateRepo: (repoId: string, updates: Partial<Repo>) => void
+}
+
+type DirEntry = { name: string; isDirectory: boolean }
+
+const MAX_SUGGESTIONS = 50
+
+export function WorktreeSymlinksSection({
+  repo,
+  updateRepo
+}: WorktreeSymlinksSectionProps): React.JSX.Element {
+  const [open, setOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const [entries, setEntries] = useState<DirEntry[]>([])
+
+  const paths = repo.symlinkPaths ?? []
+  const queryTrimmed = query.trim().replace(/^\/+/, '')
+
+  useEffect(() => {
+    let cancelled = false
+    void window.api.fs
+      .readDir({ dirPath: repo.path, connectionId: repo.connectionId ?? undefined })
+      .then((list) => {
+        if (cancelled) {
+          return
+        }
+        setEntries(list.map((entry) => ({ name: entry.name, isDirectory: entry.isDirectory })))
+      })
+      .catch(() => {
+        // Non-fatal: without entries the combobox still works as a free-text
+        // input — the user can type any path and commit it.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [repo.path, repo.connectionId])
+
+  const filtered = useMemo(() => {
+    const q = queryTrimmed.toLowerCase()
+    const base = q ? entries.filter((e) => e.name.toLowerCase().includes(q)) : entries
+    return base.slice(0, MAX_SUGGESTIONS)
+  }, [queryTrimmed, entries])
+
+  const hasExactMatch = filtered.some((e) => e.name === queryTrimmed)
+  const showLiteralItem = queryTrimmed.length > 0 && !hasExactMatch && !paths.includes(queryTrimmed)
+
+  const commit = (rawName: string): void => {
+    const trimmed = rawName.trim().replace(/^\/+/, '')
+    if (!trimmed || paths.includes(trimmed)) {
+      setQuery('')
+      return
+    }
+    updateRepo(repo.id, { symlinkPaths: [...paths, trimmed] })
+    setQuery('')
+    setOpen(false)
+  }
+
+  const handleRemove = (path: string): void => {
+    updateRepo(repo.id, { symlinkPaths: paths.filter((p) => p !== path) })
+  }
+
+  return (
+    <SearchableSetting
+      title="Worktree Symlinks"
+      description="Paths to symlink from the primary checkout into newly created worktrees."
+      keywords={[
+        repo.displayName,
+        'symlink',
+        'symlinks',
+        'worktree',
+        'link',
+        'shared',
+        'env',
+        'node_modules'
+      ]}
+      className="space-y-4"
+    >
+      <div className="flex items-start justify-between gap-4">
+        <div className="space-y-1">
+          <h3 className="text-sm font-semibold">Worktree Symlinks</h3>
+          <p className="text-xs text-muted-foreground">
+            When a new worktree is created, each path listed here will be symlinked from the primary
+            checkout.
+          </p>
+        </div>
+        <Popover open={open} onOpenChange={setOpen}>
+          <PopoverTrigger asChild>
+            <Button type="button" variant="outline" size="sm">
+              <Plus className="size-3.5" />
+              Add Path
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent align="end" className="w-72 p-0">
+            <Command shouldFilter={false}>
+              <CommandInput
+                placeholder="Type a path (e.g. .env or node_modules)…"
+                value={query}
+                onValueChange={setQuery}
+              />
+              <CommandList>
+                <CommandEmpty>No matches. Keep typing to add a custom path.</CommandEmpty>
+                {showLiteralItem ? (
+                  <CommandItem
+                    value={`__literal__:${queryTrimmed}`}
+                    onSelect={() => commit(queryTrimmed)}
+                    className="items-center gap-2 px-3 py-2"
+                  >
+                    <Plus className="size-3.5 text-muted-foreground" />
+                    <span className="text-xs">
+                      Add{' '}
+                      <code className="rounded bg-muted px-1 py-0.5 text-[11px]">
+                        {queryTrimmed}
+                      </code>
+                    </span>
+                  </CommandItem>
+                ) : null}
+                {filtered.map((entry) => {
+                  const alreadyAdded = paths.includes(entry.name)
+                  return (
+                    <CommandItem
+                      key={entry.name}
+                      value={entry.name}
+                      disabled={alreadyAdded}
+                      onSelect={() => commit(entry.name)}
+                      className={cn('items-center gap-2 px-3 py-2', alreadyAdded && 'opacity-50')}
+                    >
+                      {entry.isDirectory ? (
+                        <Folder className="size-3.5 text-muted-foreground" />
+                      ) : (
+                        <File className="size-3.5 text-muted-foreground" />
+                      )}
+                      <span className="truncate text-xs">{entry.name}</span>
+                      {alreadyAdded ? (
+                        <span className="ml-auto text-[10px] uppercase tracking-wide text-muted-foreground">
+                          added
+                        </span>
+                      ) : null}
+                    </CommandItem>
+                  )
+                })}
+              </CommandList>
+            </Command>
+          </PopoverContent>
+        </Popover>
+      </div>
+
+      {paths.length === 0 ? (
+        <div className="rounded-xl border border-dashed border-border/60 bg-background/60 px-4 py-6 text-sm text-muted-foreground">
+          No symlink paths configured for this repository.
+        </div>
+      ) : (
+        <div className="rounded-xl border border-border/50 bg-background/70 px-4 py-3 shadow-sm">
+          <div className="flex items-start gap-3">
+            <div className="mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-lg border border-border/50 bg-muted/30">
+              <Link2 className="size-4 text-muted-foreground" />
+            </div>
+            <div className="min-w-0 flex-1 space-y-2">
+              <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+                <h4 className="text-sm font-medium">Linked paths</h4>
+                <span className="text-[11px] text-muted-foreground">
+                  {paths.length === 1 ? '1 path' : `${paths.length} paths`}
+                </span>
+              </div>
+              <div className="flex flex-wrap gap-1.5">
+                {paths.map((path) => (
+                  <span
+                    key={path}
+                    title={path}
+                    className="inline-flex min-w-0 max-w-full items-center gap-1 truncate rounded-md border border-border/50 bg-muted/35 py-1 pl-2 pr-1 font-mono text-[11px] text-foreground/80"
+                  >
+                    <span className="truncate">{path}</span>
+                    <Button
+                      size="icon-xs"
+                      variant="ghost"
+                      onClick={() => handleRemove(path)}
+                      aria-label={`Remove ${path}`}
+                      className="size-4 shrink-0 rounded-sm"
+                    >
+                      <X className="size-3" />
+                    </Button>
+                  </span>
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+    </SearchableSetting>
+  )
+}
diff --git a/src/renderer/src/components/settings/experimental-search.ts b/src/renderer/src/components/settings/experimental-search.ts
index 9066f38794d..70382a48a7e 100644
--- a/src/renderer/src/components/settings/experimental-search.ts
+++ b/src/renderer/src/components/settings/experimental-search.ts
@@ -69,5 +69,22 @@ export const EXPERIMENTAL_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
       'worker',
       'coordinator'
     ]
+  },
+  {
+    title: 'Symlinks on worktrees',
+    description:
+      'Automatically symlink configured files or folders into newly created worktrees so shared state (envs, caches, installs) stays connected.',
+    keywords: [
+      'experimental',
+      'worktree',
+      'worktrees',
+      'symlink',
+      'symlinks',
+      'link',
+      'links',
+      'shared',
+      'env',
+      'node_modules'
+    ]
   }
 ]
diff --git a/src/renderer/src/components/settings/privacy-search.ts b/src/renderer/src/components/settings/privacy-search.ts
new file mode 100644
index 00000000000..fa8eb244db9
--- /dev/null
+++ b/src/renderer/src/components/settings/privacy-search.ts
@@ -0,0 +1,42 @@
+// Settings-search entries for the Privacy pane. Kept in its own file to
+// mirror the other per-pane search modules (notifications-search.ts,
+// terminal-search.ts, etc.) and keep Settings.tsx imports uniform.
+
+import type { SettingsSearchEntry } from './settings-search'
+
+export const PRIVACY_PANE_SEARCH_ENTRIES: SettingsSearchEntry[] = [
+  {
+    title: 'Privacy & Telemetry',
+    description: 'Anonymous product usage data and telemetry controls.',
+    keywords: [
+      'privacy',
+      'telemetry',
+      'analytics',
+      'usage',
+      'anonymous',
+      'data',
+      'posthog',
+      'opt out',
+      'opt in'
+    ]
+  },
+  {
+    title: 'Share Anonymous Usage Data',
+    description: 'Help improve Orca by sending anonymous feature-usage events.',
+    keywords: ['telemetry', 'usage', 'anonymous', 'opt in', 'opt out', 'share']
+  },
+  {
+    title: 'Telemetry environment variables',
+    description: 'Environment variables that disable telemetry transmission.',
+    keywords: [
+      'do not track',
+      'do_not_track',
+      'orca_telemetry_disabled',
+      'ci',
+      'continuous integration',
+      'env',
+      'environment variable',
+      'disable'
+    ]
+  }
+]
diff --git a/src/renderer/src/components/shared/useDaemonActions.tsx b/src/renderer/src/components/shared/useDaemonActions.tsx
new file mode 100644
index 00000000000..b8dd7c91483
--- /dev/null
+++ b/src/renderer/src/components/shared/useDaemonActions.tsx
@@ -0,0 +1,207 @@
+import React, { useCallback, useState } from 'react'
+import { LoaderCircle } from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '../ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '../ui/dialog'
+
+export type DaemonActionKind = 'restart' | 'killAll'
+
+export type DaemonActionCallbacks = {
+  // Why: ManageSessionsSection owns an optimistic setSessions([]) + rollback
+  // pattern. Exposing lifecycle hooks lets each caller keep the state that
+  // belongs to it (the settings pane's list; the status bar's badge) instead
+  // of pulling unrelated concerns into this module.
+  onKillAllStart?: () => void
+  onKillAllError?: () => void
+  onKillAllSettled?: () => void
+  onRestartSettled?: () => void
+}
+
+type PendingConfirm = DaemonActionKind | null
+
+export type DaemonActionsApi = {
+  pending: PendingConfirm
+  setPending: (kind: PendingConfirm) => void
+  busyKind: DaemonActionKind | null
+  isBusy: boolean
+  runRestart: () => Promise<void>
+  runKillAll: () => Promise<void>
+  runConfirmed: () => void
+}
+
+export function useDaemonActions(callbacks?: DaemonActionCallbacks): DaemonActionsApi {
+  const [pending, setPending] = useState<PendingConfirm>(null)
+  const [busyKind, setBusyKind] = useState<DaemonActionKind | null>(null)
+
+  const runRestart = useCallback(async () => {
+    setBusyKind('restart')
+    try {
+      const { success } = await window.api.pty.management.restart()
+      if (success) {
+        toast.success('Daemon restarted.')
+      } else {
+        toast.error('Restart failed — check logs.')
+      }
+    } catch (err) {
+      toast.error('Restart failed.', {
+        description: err instanceof Error ? err.message : undefined
+      })
+    } finally {
+      setBusyKind(null)
+      setPending(null)
+      callbacks?.onRestartSettled?.()
+    }
+  }, [callbacks])
+
+  const runKillAll = useCallback(async () => {
+    setBusyKind('killAll')
+    callbacks?.onKillAllStart?.()
+    try {
+      const { killedCount, remainingCount } = await window.api.pty.management.killAll()
+      if (remainingCount > 0 && killedCount > 0) {
+        toast.warning(
+          `Killed ${killedCount} of ${killedCount + remainingCount} sessions. ${remainingCount} refused to exit.`
+        )
+      } else if (killedCount > 0) {
+        toast.success(`Killed ${killedCount} session${killedCount === 1 ? '' : 's'}.`)
+      } else if (remainingCount === 0) {
+        toast.info('No sessions running.')
+      } else {
+        toast.error(`${remainingCount} session${remainingCount === 1 ? '' : 's'} refused to exit.`)
+      }
+    } catch (err) {
+      callbacks?.onKillAllError?.()
+      toast.error('Couldn’t kill sessions.', {
+        description: err instanceof Error ? err.message : undefined
+      })
+    } finally {
+      setBusyKind(null)
+      setPending(null)
+      callbacks?.onKillAllSettled?.()
+    }
+  }, [callbacks])
+
+  const runConfirmed = useCallback(() => {
+    if (pending === 'restart') {
+      void runRestart()
+    } else if (pending === 'killAll') {
+      void runKillAll()
+    }
+  }, [pending, runRestart, runKillAll])
+
+  return {
+    pending,
+    setPending,
+    busyKind,
+    isBusy: busyKind !== null,
+    runRestart,
+    runKillAll,
+    runConfirmed
+  }
+}
+
+type CopyShape = {
+  title: string
+  description: React.ReactNode
+  confirmLabel: string
+  busyLabel: string
+}
+
+function getCopy(kind: DaemonActionKind): CopyShape {
+  if (kind === 'restart') {
+    return {
+      title: 'Restart the terminal daemon?',
+      description: (
+        <>
+          Kills every running terminal pane and restarts the daemon process. Panes show
+          &ldquo;Process exited&rdquo; and can be reopened immediately. Legacy-protocol sessions
+          from a previous app version are preserved. This can&apos;t be undone.
+        </>
+      ),
+      confirmLabel: 'Restart daemon',
+      busyLabel: 'Restarting…'
+    }
+  }
+  return {
+    title: 'Kill all terminal sessions?',
+    description: (
+      <>
+        This force-quits every running terminal pane across all workspaces. Any unsaved work in
+        those sessions is lost. The daemon itself keeps running, and new terminals can be opened
+        immediately. This can&apos;t be undone.
+      </>
+    ),
+    confirmLabel: 'Kill all sessions',
+    busyLabel: 'Killing…'
+  }
+}
+
+export function DaemonActionDialog({
+  api,
+  // Why: when mounted under a Popover, we need the confirm to stay open while
+  // the mutation runs. The caller wires `onOpenChange` here to gate dismissal.
+  extraDescription
+}: {
+  api: DaemonActionsApi
+  extraDescription?: React.ReactNode
+}): React.JSX.Element {
+  const { pending, setPending, busyKind, isBusy, runConfirmed } = api
+  const copy = pending ? getCopy(pending) : null
+  return (
+    <Dialog
+      open={pending !== null}
+      onOpenChange={(open) => {
+        if (open) {
+          return
+        }
+        if (isBusy) {
+          return
+        }
+        setPending(null)
+      }}
+    >
+      <DialogContent
+        className="max-w-md"
+        showCloseButton={!isBusy}
+        onPointerDownOutside={(e) => {
+          if (isBusy) {
+            e.preventDefault()
+          }
+        }}
+        onEscapeKeyDown={(e) => {
+          if (isBusy) {
+            e.preventDefault()
+          }
+        }}
+      >
+        {copy ? (
+          <>
+            <DialogHeader>
+              <DialogTitle className="text-sm">{copy.title}</DialogTitle>
+              <DialogDescription className="text-xs">
+                {copy.description}
+                {extraDescription ? <div className="mt-2">{extraDescription}</div> : null}
+              </DialogDescription>
+            </DialogHeader>
+            <DialogFooter>
+              <Button variant="outline" onClick={() => setPending(null)} disabled={isBusy}>
+                Cancel
+              </Button>
+              <Button variant="destructive" onClick={runConfirmed} disabled={isBusy}>
+                {isBusy ? <LoaderCircle className="size-4 animate-spin" /> : null}
+                {isBusy && busyKind === pending ? copy.busyLabel : copy.confirmLabel}
+              </Button>
+            </DialogFooter>
+          </>
+        ) : null}
+      </DialogContent>
+    </Dialog>
+  )
+}
diff --git a/src/renderer/src/components/sidebar/AddRepoDialog.tsx b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
index 3f5d5a9beba..b7ff3fbe95e 100644
--- a/src/renderer/src/components/sidebar/AddRepoDialog.tsx
+++ b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
@@ -205,7 +205,7 @@ const AddRepoDialog = React.memo(function AddRepoDialog() {
     // the first focus frame from the composer's prompt textarea.
     closeModal()
     setTimeout(() => {
-      openModal('new-workspace-composer', { initialRepoId: repoId })
+      openModal('new-workspace-composer', { initialRepoId: repoId, telemetrySource: 'sidebar' })
     }, 150)
   }, [closeModal, openModal, repoId])
 
diff --git a/src/renderer/src/components/sidebar/SidebarHeader.tsx b/src/renderer/src/components/sidebar/SidebarHeader.tsx
index a943e8cd9cd..1458aaf3654 100644
--- a/src/renderer/src/components/sidebar/SidebarHeader.tsx
+++ b/src/renderer/src/components/sidebar/SidebarHeader.tsx
@@ -162,7 +162,7 @@ const SidebarHeader = React.memo(function SidebarHeader() {
                 if (!canCreateWorktree) {
                   return
                 }
-                openModal('new-workspace-composer')
+                openModal('new-workspace-composer', { telemetrySource: 'sidebar' })
               }}
               aria-label="New workspace"
               disabled={!canCreateWorktree}
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.tsx b/src/renderer/src/components/sidebar/WorktreeCard.tsx
index 8a3ae5a9e0c..1bd9f786efb 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.tsx
@@ -255,9 +255,22 @@ const WorktreeCard = React.memo(function WorktreeCard({
   // spend rate limit budget on data the user cannot see.
   useEffect(() => {
     if (repo && !isFolder && !worktree.isBare && prCacheKey && (showPR || showCI)) {
-      fetchPRForBranch(repo.path, branch)
+      // Why: pass linkedPR so worktrees created from a PR (whose new local
+      // branch differs from the PR's head ref) still resolve their PR via
+      // a number-based fallback in the main process.
+      fetchPRForBranch(repo.path, branch, { linkedPRNumber: worktree.linkedPR ?? null })
     }
-  }, [repo, isFolder, worktree.isBare, fetchPRForBranch, branch, prCacheKey, showPR, showCI])
+  }, [
+    repo,
+    isFolder,
+    worktree.isBare,
+    worktree.linkedPR,
+    fetchPRForBranch,
+    branch,
+    prCacheKey,
+    showPR,
+    showCI
+  ])
 
   // Same rationale for issues: once that section is hidden, polling only burns
   // GitHub calls and keeps stale-but-invisible data warm for no user benefit.
diff --git a/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx b/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
index c1dbfb69166..094e568aaa7 100644
--- a/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCardAgents.tsx
@@ -1,6 +1,8 @@
 import React, { useCallback, useMemo } from 'react'
 import { ChevronDown } from 'lucide-react'
 import { useAppStore } from '@/store'
+import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import { activateTabAndFocusPane } from '@/lib/activate-tab-and-focus-pane'
 import DashboardAgentRow from '@/components/dashboard/DashboardAgentRow'
 import { useNow } from '@/components/dashboard/useNow'
 import { useWorktreeAgentRows } from './useWorktreeAgentRows'
@@ -50,11 +52,7 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
 }: BodyProps) {
   const dropAgentStatus = useAppStore((s) => s.dropAgentStatus)
   const dismissRetainedAgent = useAppStore((s) => s.dismissRetainedAgent)
-  const setActiveWorktree = useAppStore((s) => s.setActiveWorktree)
-  const setActiveTab = useAppStore((s) => s.setActiveTab)
-  const setActiveView = useAppStore((s) => s.setActiveView)
   const acknowledgeAgents = useAppStore((s) => s.acknowledgeAgents)
-  const markWorktreeVisited = useAppStore((s) => s.markWorktreeVisited)
 
   // Why: per-worktree collapse is session-only UI state. Single-primitive
   // subscription so the card only re-renders when THIS worktree's collapsed
@@ -89,24 +87,32 @@ const WorktreeCardAgentsBody = React.memo(function WorktreeCardAgentsBody({
   const handleActivateAgentTab = useCallback(
     (tabId: string, paneKey: string) => {
       acknowledgeAgents([paneKey])
-      setActiveWorktree(worktreeId)
-      // Why: sidebar agent-tab click is a user-initiated switch; stamp focus
-      // recency for Cmd+J. See docs/cmd-j-empty-query-ordering.md.
-      markWorktreeVisited(worktreeId)
-      setActiveView('terminal')
+      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.
+        console.warn('[WorktreeCardAgents] malformed paneKey, skipping pane focus', paneKey)
+      }
+      // Why: route through activateAndRevealWorktree so cross-repo clicks also
+      // set activeRepoId, record a nav-history entry, clear sidebar filters,
+      // reveal the card, and stamp focus recency — per the design doc rule
+      // "Every user-initiated worktree switch must route through
+      // activateAndRevealWorktree". Bypassing it (direct setActiveWorktree +
+      // markWorktreeVisited) silently skipped cross-repo activation and
+      // back/forward history for clicks from inline agent rows.
+      activateAndRevealWorktree(worktreeId)
       const tabs = useAppStore.getState().tabsByWorktree[worktreeId] ?? []
       if (tabs.some((t) => t.id === tabId)) {
-        setActiveTab(tabId)
+        activateTabAndFocusPane(tabId, paneId)
       }
     },
-    [
-      worktreeId,
-      setActiveWorktree,
-      setActiveTab,
-      setActiveView,
-      acknowledgeAgents,
-      markWorktreeVisited
-    ]
+    [worktreeId, acknowledgeAgents]
   )
 
   const handleToggleCollapsed = useCallback(
diff --git a/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx b/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx
index 2bbe8e7ddab..d2f8e4c7128 100644
--- a/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCardMeta.tsx
@@ -73,13 +73,16 @@ type PrSectionProps = {
   onClick: (e: React.MouseEvent) => void
 }
 
-export function PrSection({ pr, onClick }: PrSectionProps): React.JSX.Element {
+export function PrSection({ pr, onClick: _onClick }: PrSectionProps): React.JSX.Element {
   return (
     <HoverCard openDelay={300}>
       <HoverCardTrigger asChild>
-        <div
+        <a
+          href={pr.url}
+          target="_blank"
+          rel="noreferrer"
           className="flex items-center gap-1.5 min-w-0 cursor-pointer group/meta -mx-1.5 px-1.5 py-0.5 rounded transition-colors hover:bg-background/40"
-          onClick={onClick}
+          onClick={(e) => e.stopPropagation()}
         >
           <PullRequestIcon
             className={cn(
@@ -93,20 +96,14 @@ export function PrSection({ pr, onClick }: PrSectionProps): React.JSX.Element {
             )}
           />
           <div className="flex-1 min-w-0 flex items-center gap-1.5 text-[11.5px] leading-none">
-            <a
-              href={pr.url}
-              target="_blank"
-              rel="noreferrer"
-              className="text-foreground opacity-80 shrink-0 hover:text-foreground hover:underline"
-              onClick={(e) => e.stopPropagation()}
-            >
+            <span className="text-foreground opacity-80 shrink-0 group-hover/meta:underline">
               PR #{pr.number}
-            </a>
+            </span>
             <span className="text-muted-foreground truncate group-hover/meta:text-foreground transition-colors">
               {pr.title}
             </span>
           </div>
-        </div>
+        </a>
       </HoverCardTrigger>
       <HoverCardContent side="right" align="start" className="w-72 p-3 text-xs space-y-1.5">
         <div className="font-semibold text-[13px]">
diff --git a/src/renderer/src/components/sidebar/WorktreeList.tsx b/src/renderer/src/components/sidebar/WorktreeList.tsx
index 4d90a4ac37f..0264ec4585e 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.tsx
@@ -417,7 +417,7 @@ const VirtualizedWorktreeViewport = React.memo(function VirtualizedWorktreeViewp
 
                   <div className="min-w-0 flex-1">
                     <div className="flex items-center gap-1.5">
-                      <div className="truncate text-[13px] font-semibold leading-none capitalize">
+                      <div className="truncate text-[13px] font-semibold leading-none">
                         {row.label}
                       </div>
                       <div className="rounded-full bg-black/12 px-1.5 py-0.5 text-[9px] font-medium leading-none text-muted-foreground/90">
@@ -790,7 +790,7 @@ const WorktreeList = React.memo(function WorktreeList() {
 
   const handleCreateForRepo = useCallback(
     (repoId: string) => {
-      openModal('new-workspace-composer', { initialRepoId: repoId })
+      openModal('new-workspace-composer', { initialRepoId: repoId, telemetrySource: 'sidebar' })
     },
     [openModal]
   )
diff --git a/src/renderer/src/components/sidebar/sleep-worktree-flow.test.ts b/src/renderer/src/components/sidebar/sleep-worktree-flow.test.ts
index 38266e97d2d..84c1a2ef54f 100644
--- a/src/renderer/src/components/sidebar/sleep-worktree-flow.test.ts
+++ b/src/renderer/src/components/sidebar/sleep-worktree-flow.test.ts
@@ -40,7 +40,9 @@ describe('runSleepWorktree', () => {
     // are still populated. If terminals ran first and kept its old
     // browserTabsByWorktree delete, browsers would no-op and leak webviews.
     expect(mocks.state.shutdownWorktreeBrowsers).toHaveBeenCalledWith('wt-1')
-    expect(mocks.state.shutdownWorktreeTerminals).toHaveBeenCalledWith('wt-1')
+    expect(mocks.state.shutdownWorktreeTerminals).toHaveBeenCalledWith('wt-1', {
+      keepIdentifiers: true
+    })
     const browsersCallOrder = mocks.state.shutdownWorktreeBrowsers.mock.invocationCallOrder[0]
     const terminalsCallOrder = mocks.state.shutdownWorktreeTerminals.mock.invocationCallOrder[0]
     expect(browsersCallOrder).toBeLessThan(terminalsCallOrder)
diff --git a/src/renderer/src/components/sidebar/sleep-worktree-flow.ts b/src/renderer/src/components/sidebar/sleep-worktree-flow.ts
index af643976628..7ade76cb61c 100644
--- a/src/renderer/src/components/sidebar/sleep-worktree-flow.ts
+++ b/src/renderer/src/components/sidebar/sleep-worktree-flow.ts
@@ -31,7 +31,14 @@ export async function runSleepWorktree(worktreeId: string): Promise<void> {
     // ordering on both paths. Without the browser thunk here, sleep leaks
     // browserPagesByWorkspace entries and live webviews for the slept worktree.
     await shutdownWorktreeBrowsers(worktreeId)
-    await shutdownWorktreeTerminals(worktreeId)
+    // Why: sleep is reversible — the tab record stays in tabsByWorktree, the
+    // layout stays in terminalLayoutsByTabId, only the live PTY processes are
+    // released. keepIdentifiers preserves tab.ptyId / ptyIdsByLeafId /
+    // lastKnownRelayPtyIdByTabId so wake re-spawns against the same on-disk
+    // history dir (local) or relay session id (SSH); it also captures
+    // serializer buffers into buffersByLeafId for SSH wake to reseed
+    // scrollback. See DESIGN_DOC_TERMINAL_HISTORY_FIX_V2.md §3.3.c.
+    await shutdownWorktreeTerminals(worktreeId, { keepIdentifiers: true })
   } catch (err) {
     // Why: callers are fire-and-forget; surface the failure as a toast and
     // otherwise continue — the active-worktree reset already happened so we
diff --git a/src/renderer/src/components/sidebar/smart-sort.test.ts b/src/renderer/src/components/sidebar/smart-sort.test.ts
index dc470ce89eb..b56f9c2c0db 100644
--- a/src/renderer/src/components/sidebar/smart-sort.test.ts
+++ b/src/renderer/src/components/sidebar/smart-sort.test.ts
@@ -1,7 +1,13 @@
 /* eslint-disable max-lines */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { Repo, TerminalTab, Worktree } from '../../../../shared/types'
-import { buildWorktreeComparator, computeSmartScore, type SmartSortOverride } from './smart-sort'
+import {
+  buildWorktreeComparator,
+  computeSmartScore,
+  CREATE_GRACE_MS,
+  effectiveRecentActivity,
+  type SmartSortOverride
+} from './smart-sort'
 import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
 
 const NOW = new Date('2026-03-27T12:00:00.000Z').getTime()
@@ -37,7 +43,8 @@ function makeWorktree(overrides: Partial<Worktree> = {}): Worktree {
     isPinned: overrides.isPinned ?? false,
     displayName: overrides.displayName ?? overrides.id ?? 'wt-1',
     sortOrder: overrides.sortOrder ?? 0,
-    lastActivityAt: overrides.lastActivityAt ?? 0
+    lastActivityAt: overrides.lastActivityAt ?? 0,
+    ...(overrides.createdAt !== undefined ? { createdAt: overrides.createdAt } : {})
   }
 }
 
@@ -511,3 +518,100 @@ describe('buildWorktreeComparator — recent (lastActivityAt)', () => {
     expect(worktrees.map((w) => w.id)).toEqual(['fresh-active', 'stale-high-order'])
   })
 })
+
+describe('effectiveRecentActivity — create-grace floor', () => {
+  it('returns lastActivityAt when createdAt is absent', () => {
+    const wt = makeWorktree({ id: 'old', lastActivityAt: 12345 })
+    expect(effectiveRecentActivity(wt, NOW)).toBe(12345)
+  })
+
+  it('returns createdAt + CREATE_GRACE_MS when grace window exceeds lastActivityAt', () => {
+    const wt = makeWorktree({ id: 'fresh', lastActivityAt: NOW, createdAt: NOW })
+    expect(effectiveRecentActivity(wt, NOW)).toBe(NOW + CREATE_GRACE_MS)
+  })
+
+  it('returns lastActivityAt when grace window has elapsed', () => {
+    const wt = makeWorktree({
+      id: 'post-grace',
+      createdAt: NOW - CREATE_GRACE_MS - 60_000,
+      lastActivityAt: NOW - 1000
+    })
+    expect(effectiveRecentActivity(wt, NOW)).toBe(NOW - 1000)
+  })
+
+  it('returns lastActivityAt when real activity has surpassed the grace floor', () => {
+    // A user who interacted 3 minutes after create has lastActivityAt > createdAt + 3min,
+    // but createdAt + 5min still wins for the next 2 minutes.
+    const createdAt = NOW - 3 * 60 * 1000
+    const wt = makeWorktree({ id: 'used', createdAt, lastActivityAt: NOW - 60_000 })
+    // createdAt + GRACE_MS = NOW + 2min, which exceeds lastActivityAt (NOW - 1min).
+    expect(effectiveRecentActivity(wt, NOW)).toBe(createdAt + CREATE_GRACE_MS)
+  })
+
+  it('returns lastActivityAt once the grace window has elapsed even when no other activity has occurred', () => {
+    // Bug-fix case: a worktree created days ago that was never touched after
+    // creation. Without the time-bound check, the floor would still apply and
+    // the worktree would rank as `createdAt + 5min` forever, masking truly
+    // fresher worktrees.
+    const createdAt = NOW - CREATE_GRACE_MS - 1
+    const wt = makeWorktree({ id: 'untouched', createdAt, lastActivityAt: createdAt })
+    expect(effectiveRecentActivity(wt, NOW)).toBe(createdAt)
+  })
+})
+
+describe('buildWorktreeComparator — recent with createdAt grace window', () => {
+  it('keeps a newly-created worktree on top even when another worktree bumps lastActivityAt', () => {
+    // Simulates the bug: user creates a worktree at t=0, then an ambient PTY
+    // bump on a different worktree lands at t=+100ms. Without the grace
+    // window, the bumped worktree would outrank the new one by 100ms.
+    const newWorktree = makeWorktree({
+      id: 'new',
+      displayName: 'New',
+      createdAt: NOW,
+      lastActivityAt: NOW
+    })
+    const bumpedByAmbient = makeWorktree({
+      id: 'bumped',
+      displayName: 'Bumped',
+      lastActivityAt: NOW + 100
+    })
+    const worktrees = [bumpedByAmbient, newWorktree]
+
+    worktrees.sort(buildWorktreeComparator('recent', null, repoMap, null, NOW))
+
+    expect(worktrees.map((w) => w.id)).toEqual(['new', 'bumped'])
+  })
+
+  it('falls through to normal recency once the grace window has elapsed', () => {
+    const oldCreated = makeWorktree({
+      id: 'old-created',
+      displayName: 'Old created',
+      // Created longer ago than GRACE_MS so the floor has expired.
+      createdAt: NOW - CREATE_GRACE_MS - 10_000,
+      lastActivityAt: NOW - 30_000
+    })
+    const freshActivity = makeWorktree({
+      id: 'fresh-activity',
+      displayName: 'Fresh activity',
+      // No createdAt (discovered on disk), but has recent real activity.
+      lastActivityAt: NOW - 1000
+    })
+    const worktrees = [oldCreated, freshActivity]
+
+    worktrees.sort(buildWorktreeComparator('recent', null, repoMap, null, NOW))
+
+    expect(worktrees.map((w) => w.id)).toEqual(['fresh-activity', 'old-created'])
+  })
+
+  it('does not disturb ranking for worktrees without createdAt', () => {
+    // All existing worktrees (persisted before createdAt field existed) stay
+    // sorted by lastActivityAt alone.
+    const alpha = makeWorktree({ id: 'alpha', displayName: 'Alpha', lastActivityAt: 5000 })
+    const bravo = makeWorktree({ id: 'bravo', displayName: 'Bravo', lastActivityAt: 10_000 })
+    const worktrees = [alpha, bravo]
+
+    worktrees.sort(buildWorktreeComparator('recent', null, repoMap, null, NOW))
+
+    expect(worktrees.map((w) => w.id)).toEqual(['bravo', 'alpha'])
+  })
+})
diff --git a/src/renderer/src/components/sidebar/smart-sort.ts b/src/renderer/src/components/sidebar/smart-sort.ts
index 8200cb357ff..54867cef86c 100644
--- a/src/renderer/src/components/sidebar/smart-sort.ts
+++ b/src/renderer/src/components/sidebar/smart-sort.ts
@@ -8,6 +8,38 @@ import {
 
 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
+// after the user clicked Create). During and after that window, ambient PTY
+// bumps on OTHER worktrees (data flush, exit, reconnect) can push the new
+// worktree below them in Recent sort. This grace period gives the new
+// worktree a floor of `createdAt + CREATE_GRACE_MS` in the Recent comparator
+// so it stays on top until the user has had a chance to notice it. 5 min is
+// long enough for the user to interact, short enough that steady-state
+// ordering resumes quickly.
+export const CREATE_GRACE_MS = 5 * 60 * 1000
+
+/**
+ * Rank a worktree in Recent sort using `lastActivityAt`, but with a floor of
+ * `createdAt + CREATE_GRACE_MS` *only during* the grace window (i.e. while
+ * `now < createdAt + CREATE_GRACE_MS`). Once the window has elapsed, returns
+ * `lastActivityAt` unchanged. Returns `lastActivityAt` unchanged for worktrees
+ * without `createdAt` (discovered on disk, or persisted before this field
+ * existed).
+ */
+export function effectiveRecentActivity(worktree: Worktree, now: number): number {
+  const { lastActivityAt, createdAt } = worktree
+  // Why bound by now: a worktree with createdAt set but no subsequent activity
+  // should not retain artificially-high recency forever; the floor exists to
+  // absorb the noisy creation window only. Without this bound, a worktree
+  // created days ago and never touched would keep ranking as if its activity
+  // were `createdAt + 5min`, masking truly fresher worktrees indefinitely.
+  if (createdAt === undefined || now >= createdAt + CREATE_GRACE_MS) {
+    return lastActivityAt
+  }
+  return Math.max(lastActivityAt, createdAt + CREATE_GRACE_MS)
+}
+
 type PRCacheEntry = { data: object | null; fetchedAt: number }
 export type SmartSortOverride = {
   worktree: Worktree
@@ -276,18 +308,27 @@ export function buildWorktreeComparator(
               )
         return (
           scoreB - scoreA ||
-          smartB.worktree.lastActivityAt - smartA.worktree.lastActivityAt ||
+          effectiveRecentActivity(smartB.worktree, now) -
+            effectiveRecentActivity(smartA.worktree, now) ||
           a.displayName.localeCompare(b.displayName)
         )
       }
       case 'recent':
-        // Why lastActivityAt (not sortOrder): sortOrder is a snapshot of the
-        // smart-sort ranking that only gets repersisted while the user is in
-        // "Smart" mode, so it's frozen in Recent mode and ignores new terminal
-        // events, meta edits, etc. lastActivityAt is the real "recency" signal
-        // — it's bumped by bumpWorktreeActivity (PTY spawn, background events)
-        // and by meaningful meta edits (comment, isUnread).
-        return b.lastActivityAt - a.lastActivityAt || a.displayName.localeCompare(b.displayName)
+        // Why effectiveRecentActivity (not raw lastActivityAt): newly-created
+        // worktrees get a CREATE_GRACE_MS floor on top of lastActivityAt so
+        // ambient PTY bumps in other worktrees don't immediately push them
+        // down. See CREATE_GRACE_MS above.
+        //
+        // Why not sortOrder: sortOrder is a snapshot of the smart-sort
+        // ranking that only gets repersisted while the user is in "Smart"
+        // mode, so it's frozen in Recent mode and ignores new terminal
+        // events, meta edits, etc. lastActivityAt is the real "recency"
+        // signal — bumped by bumpWorktreeActivity (PTY spawn, background
+        // events) and by meaningful meta edits (comment, isUnread).
+        return (
+          effectiveRecentActivity(b, now) - effectiveRecentActivity(a, now) ||
+          a.displayName.localeCompare(b.displayName)
+        )
       case 'repo': {
         const ra = repoMap.get(a.repoId)?.displayName ?? ''
         const rb = repoMap.get(b.repoId)?.displayName ?? ''
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 129be5f9205..9500cec1af6 100644
--- a/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
+++ b/src/renderer/src/components/sidebar/worktree-list-groups.test.ts
@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { buildRows, getPRGroupKey } from './worktree-list-groups'
 import type { Repo, Worktree } from '../../../../shared/types'
@@ -91,4 +93,22 @@ describe('buildRows with pinned worktrees', () => {
     const rows = buildRows('none', [pinned, allPinned], repoMap, null, new Set())
     expect(rows.some((r) => r.type === 'header' && r.key === 'all')).toBe(false)
   })
+
+  it('preserves repo display casing in group labels', () => {
+    const lowercaseRepo = { ...repo, displayName: 'c15t' }
+    const rows = buildRows('repo', [worktree], new Map([[repo.id, lowercaseRepo]]), null, new Set())
+
+    expect(rows[0]).toMatchObject({ type: 'header', label: 'c15t' })
+  })
+})
+
+describe('WorktreeList header styles', () => {
+  it('does not title-case workspace group labels', () => {
+    const source = readFileSync(
+      fileURLToPath(new URL('./WorktreeList.tsx', import.meta.url)),
+      'utf8'
+    )
+
+    expect(source).not.toContain('leading-none capitalize')
+  })
 })
diff --git a/src/renderer/src/components/sidekick/SidekickOverlay.tsx b/src/renderer/src/components/sidekick/SidekickOverlay.tsx
index 22c2f74ad1a..7baf8b870b8 100644
--- a/src/renderer/src/components/sidekick/SidekickOverlay.tsx
+++ b/src/renderer/src/components/sidekick/SidekickOverlay.tsx
@@ -1,5 +1,143 @@
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useId, useRef, useState } from 'react'
 import { useSidekickUrl } from './useSidekickUrl'
+import type { DetectedSpriteCacheEntry } from './sidekick-blob-cache'
+import type { CustomSidekick } from '../../../../shared/types'
+import { useAppStore } from '../../store'
+
+type Sprite = NonNullable<CustomSidekick['sprite']>
+
+// Why: pet bundles ship a sprite sheet — animate by stepping a CSS background
+// across the cells of one row. We pick which row + how many frames from the
+// manifest's defaultAnimation, falling back to the first row if the manifest
+// only declared frame size. imageRendering: 'pixelated' keeps edges crisp even
+// when scale is fractional (needed when frames exceed maxSize).
+function SpriteFrame({
+  url,
+  sprite,
+  animate,
+  maxSize
+}: {
+  url: string
+  sprite: Sprite
+  animate: boolean
+  maxSize: number
+}): React.JSX.Element {
+  const animKeyframesId = useId().replace(/[^a-zA-Z0-9_-]/g, '')
+  const anim =
+    (sprite.defaultAnimation && sprite.animations?.[sprite.defaultAnimation]) ||
+    (sprite.animations ? Object.values(sprite.animations)[0] : undefined)
+  const row = anim?.row ?? 0
+  // Why: clamp to >=1 so an empty/invalid manifest can't produce steps(0),
+  // which is rejected as invalid CSS and freezes the animation.
+  const frames = Math.max(1, anim?.frames ?? sprite.columns ?? 1)
+  // Why: allow fractional downscaling so frames larger than maxSize shrink to
+  // fit instead of overflowing the overlay; mirrors DetectedSpriteFrame's math.
+  const scale = Math.min(maxSize / sprite.frameWidth, maxSize / sprite.frameHeight)
+  const renderedW = sprite.frameWidth * scale
+  const renderedH = sprite.frameHeight * scale
+  const bgW = sprite.sheetWidth * scale
+  const bgH = sprite.sheetHeight * scale
+  const startX = 0
+  const startY = -(row * sprite.frameHeight * scale)
+  const endX = -(frames * sprite.frameWidth * scale)
+  const duration = Math.max(0.1, frames / Math.max(0.1, sprite.fps))
+  return (
+    <>
+      <style>{`@keyframes pet-${animKeyframesId} { from { background-position: ${startX}px ${startY}px; } to { background-position: ${endX}px ${startY}px; } }`}</style>
+      <div
+        style={{
+          width: renderedW,
+          height: renderedH,
+          backgroundImage: `url(${url})`,
+          backgroundRepeat: 'no-repeat',
+          backgroundSize: `${bgW}px ${bgH}px`,
+          backgroundPosition: `${startX}px ${startY}px`,
+          imageRendering: 'pixelated',
+          animation: `pet-${animKeyframesId} ${duration}s steps(${frames}) infinite`,
+          animationPlayState: animate ? 'running' : 'paused'
+        }}
+      />
+    </>
+  )
+}
+
+// Why: when the manifest doesn't declare frame size, we auto-detect frames
+// from the keyed sheet. Render via canvas because the frames may be different
+// sizes; we scale each one to fit the overlay box and step through them at a
+// fixed fps. requestAnimationFrame is paused when `animate` is false so the
+// overlay respects reduced motion / hidden window.
+function DetectedSpriteFrame({
+  detected,
+  animate,
+  maxSize
+}: {
+  detected: DetectedSpriteCacheEntry
+  animate: boolean
+  maxSize: number
+}): React.JSX.Element {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null)
+  const frameIndexRef = useRef(0)
+  const lastTimeRef = useRef(0)
+  // Why: honor manifest fps captured at import time so bundles play at their
+  // intended speed; default to 8 only when the manifest didn't declare one.
+  const fps = detected.fps > 0 ? detected.fps : 8
+
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) {
+      return
+    }
+    const ctx = canvas.getContext('2d')
+    if (!ctx) {
+      return
+    }
+    canvas.width = maxSize
+    canvas.height = maxSize
+    // Why: reset playback when the underlying sprite changes so the new
+    // animation starts from frame 0 rather than wherever the prior one stopped.
+    frameIndexRef.current = 0
+    lastTimeRef.current = 0
+    let raf = 0
+    const draw = (): void => {
+      const f = detected.frames[frameIndexRef.current % detected.frames.length]
+      const bmp = detected.bitmaps[frameIndexRef.current % detected.bitmaps.length]
+      ctx.imageSmoothingEnabled = false
+      ctx.clearRect(0, 0, canvas.width, canvas.height)
+      const scale = Math.min(maxSize / f.w, maxSize / f.h)
+      const w = f.w * scale
+      const h = f.h * scale
+      ctx.drawImage(bmp, (maxSize - w) / 2, (maxSize - h) / 2, w, h)
+    }
+    const tick = (now: number): void => {
+      const dt = now - lastTimeRef.current
+      if (dt >= 1000 / fps) {
+        lastTimeRef.current = now
+        frameIndexRef.current = (frameIndexRef.current + 1) % detected.frames.length
+        draw()
+      }
+      if (animate) {
+        raf = requestAnimationFrame(tick)
+      }
+    }
+    draw()
+    if (animate) {
+      lastTimeRef.current = performance.now()
+      raf = requestAnimationFrame(tick)
+    }
+    return () => {
+      if (raf) {
+        cancelAnimationFrame(raf)
+      }
+    }
+  }, [detected, animate, maxSize])
+
+  return (
+    <canvas
+      ref={canvasRef}
+      style={{ width: maxSize, height: maxSize, imageRendering: 'pixelated' }}
+    />
+  )
+}
 
 function useDocumentVisible(): boolean {
   const [visible, setVisible] = useState(() =>
@@ -34,24 +172,26 @@ function usePrefersReducedMotion(): boolean {
   return reduced
 }
 
+// Why: keep a default for the cached helpers below; the live size now comes
+// from the store so the user can resize from the status-bar menu.
 const SIZE = 180
 const POSITION_STORAGE_KEY = 'sidekick-overlay-position'
 
 type Position = { x: number; y: number }
 
-function clampToViewport(pos: Position): Position {
+function clampToViewport(pos: Position, size: number = SIZE): Position {
   if (typeof window === 'undefined') {
     return pos
   }
-  const maxX = Math.max(0, window.innerWidth - SIZE)
-  const maxY = Math.max(0, window.innerHeight - SIZE)
+  const maxX = Math.max(0, window.innerWidth - size)
+  const maxY = Math.max(0, window.innerHeight - size)
   return {
     x: Math.min(Math.max(0, pos.x), maxX),
     y: Math.min(Math.max(0, pos.y), maxY)
   }
 }
 
-function loadStoredPosition(): Position | null {
+function loadStoredPosition(size: number = SIZE): Position | null {
   if (typeof window === 'undefined') {
     return null
   }
@@ -64,39 +204,56 @@ function loadStoredPosition(): Position | null {
     if (typeof parsed.x !== 'number' || typeof parsed.y !== 'number') {
       return null
     }
-    return clampToViewport({ x: parsed.x, y: parsed.y })
+    // Why: clamp using the live overlay size so a persisted position from a
+    // larger overlay doesn't slip off the bottom/right edge after a shrink.
+    return clampToViewport({ x: parsed.x, y: parsed.y }, size)
   } catch {
     return null
   }
 }
 
-function defaultPosition(): Position {
+function defaultPosition(size: number = SIZE): Position {
   if (typeof window === 'undefined') {
     return { x: 0, y: 0 }
   }
   // Matches previous bottom-4 right-16 (right: 4rem, bottom: 1rem).
-  return clampToViewport({
-    x: window.innerWidth - SIZE - 64,
-    y: window.innerHeight - SIZE - 16
-  })
+  return clampToViewport(
+    {
+      x: window.innerWidth - size - 64,
+      y: window.innerHeight - size - 16
+    },
+    size
+  )
 }
 
 export function SidekickOverlay(): React.JSX.Element {
   const documentVisible = useDocumentVisible()
   const reducedMotion = usePrefersReducedMotion()
-  const { url } = useSidekickUrl()
+  const { url, sprite, detected } = useSidekickUrl()
+  const size = useAppStore((s) => s.sidekickSize)
 
-  const [position, setPosition] = useState<Position>(
-    () => loadStoredPosition() ?? defaultPosition()
-  )
+  const [position, setPosition] = useState<Position>(() => {
+    // Why: read the persisted size eagerly via getState so the initial clamp
+    // uses the user's last sidekick size — useState's lazy initializer runs
+    // before the `size` prop binding settles, and `loadStoredPosition` would
+    // otherwise default to SIZE and clip a previously-saved position.
+    const currentSize = useAppStore.getState().sidekickSize ?? SIZE
+    return loadStoredPosition(currentSize) ?? defaultPosition(currentSize)
+  })
   const [dragging, setDragging] = useState(false)
   const dragOffsetRef = useRef<Position>({ x: 0, y: 0 })
 
   useEffect(() => {
-    const onResize = (): void => setPosition((prev) => clampToViewport(prev))
+    const onResize = (): void => setPosition((prev) => clampToViewport(prev, size))
     window.addEventListener('resize', onResize)
     return () => window.removeEventListener('resize', onResize)
-  }, [])
+  }, [size])
+
+  // Why: when the user shrinks/grows the overlay, re-clamp so the box never
+  // overflows the viewport edges (which would otherwise leave it un-draggable).
+  useEffect(() => {
+    setPosition((prev) => clampToViewport(prev, size))
+  }, [size])
 
   useEffect(() => {
     if (dragging) {
@@ -132,10 +289,13 @@ export function SidekickOverlay(): React.JSX.Element {
       return
     }
     setPosition(
-      clampToViewport({
-        x: event.clientX - dragOffsetRef.current.x,
-        y: event.clientY - dragOffsetRef.current.y
-      })
+      clampToViewport(
+        {
+          x: event.clientX - dragOffsetRef.current.x,
+          y: event.clientY - dragOffsetRef.current.y
+        },
+        size
+      )
     )
   }
 
@@ -156,8 +316,8 @@ export function SidekickOverlay(): React.JSX.Element {
       style={{
         left: position.x,
         top: position.y,
-        width: SIZE,
-        height: SIZE
+        width: size,
+        height: size
       }}
     >
       <div
@@ -178,7 +338,18 @@ export function SidekickOverlay(): React.JSX.Element {
             '@keyframes sidekick-bob { 0%,100% { transform: translateY(0); } 50% { transform: translateY(-4px); } }'
           }
         </style>
-        <img src={url} alt="" className="max-h-full max-w-full object-contain" draggable={false} />
+        {sprite ? (
+          <SpriteFrame url={url} sprite={sprite} animate={animate} maxSize={size} />
+        ) : detected ? (
+          <DetectedSpriteFrame detected={detected} animate={animate} maxSize={size} />
+        ) : (
+          <img
+            src={url}
+            alt=""
+            className="max-h-full max-w-full object-contain"
+            draggable={false}
+          />
+        )}
       </div>
     </div>
   )
diff --git a/src/renderer/src/components/sidekick/sidekick-blob-cache.ts b/src/renderer/src/components/sidekick/sidekick-blob-cache.ts
index 3482aa07d8d..f78cf92a33d 100644
--- a/src/renderer/src/components/sidekick/sidekick-blob-cache.ts
+++ b/src/renderer/src/components/sidekick/sidekick-blob-cache.ts
@@ -2,6 +2,8 @@
 // without importing useSidekickUrl (which itself imports the store). Keeps
 // the dependency graph acyclic.
 
+import { detectFramesFromImageData, type DetectedFrame } from './sprite-frame-detection'
+
 // Why: sandbox=true + webSecurity=true block the renderer from reading user
 // files directly. For custom sidekick images we fetch the bytes over IPC and
 // turn them into a `blob:` URL that an <img> tag can load. A small in-memory
@@ -9,16 +11,33 @@
 // doesn't re-fetch from main.
 export const blobUrlCache = new Map<string, string>()
 
+export type DetectedSpriteCacheEntry = {
+  frames: DetectedFrame[]
+  /** Per-frame image bitmaps drawn from the keyed canvas. The overlay paints
+   *  these onto its own canvas one at a time, so we can crop irregular sheets
+   *  without forcing the manifest to declare a uniform grid. */
+  bitmaps: ImageBitmap[]
+  /** Manifest-declared playback speed; the overlay falls back to 8 fps when
+   *  the bundle didn't declare one. */
+  fps: number
+}
+export const detectedSpriteCache = new Map<string, DetectedSpriteCacheEntry>()
+
 export async function loadCustomBlobUrl(
   id: string,
   fileName: string,
-  mimeType: string
+  mimeType: string,
+  kind?: 'image' | 'bundle',
+  spriteFps?: number
 ): Promise<string | null> {
   const cached = blobUrlCache.get(id)
   if (cached) {
     return cached
   }
-  const buffer = await window.api.sidekick.read(id, fileName)
+  // Why: defensively clear any stale entry so we don't leak a prior blob URL
+  // or ImageBitmap[] when re-populating after a cache miss.
+  revokeCustomSidekickBlobUrl(id)
+  const buffer = await window.api.sidekick.read(id, fileName, kind)
   if (!buffer) {
     return null
   }
@@ -26,11 +45,122 @@ export async function loadCustomBlobUrl(
   // SVG, which browsers refuse to render from a blob URL with the wrong
   // Content-Type.
   const blob = new Blob([buffer], { type: mimeType })
-  const url = URL.createObjectURL(blob)
+  let url = URL.createObjectURL(blob)
+  // Why: pet bundles often ship spritesheets with a magenta chroma-key as
+  // the background instead of true alpha (common in pixel-art tooling).
+  // Strip it once at load and replace the cached URL with a transparent PNG
+  // so the overlay just sees a normal blob URL.
+  if (kind === 'bundle' && mimeType !== 'image/svg+xml') {
+    const processed = await processBundleSheet(url, spriteFps)
+    if (processed) {
+      URL.revokeObjectURL(url)
+      url = processed.url
+      if (processed.detected) {
+        detectedSpriteCache.set(id, processed.detected)
+      }
+    }
+  }
   blobUrlCache.set(id, url)
   return url
 }
 
+async function processBundleSheet(
+  srcUrl: string,
+  spriteFps?: number
+): Promise<{ url: string; detected: DetectedSpriteCacheEntry | null } | null> {
+  try {
+    const img = await loadImage(srcUrl)
+    const canvas = document.createElement('canvas')
+    canvas.width = img.naturalWidth
+    canvas.height = img.naturalHeight
+    const ctx = canvas.getContext('2d')
+    if (!ctx) {
+      return null
+    }
+    ctx.drawImage(img, 0, 0)
+    const data = ctx.getImageData(0, 0, canvas.width, canvas.height)
+    keyMagenta(data.data)
+    ctx.putImageData(data, 0, 0)
+    // Why: detect frames *after* keying so transparent gutters between
+    // sprites are visible to the band/column scanner. Without this the whole
+    // sheet collapses into one giant frame.
+    let detected: DetectedSpriteCacheEntry | null = null
+    const sprite = detectFramesFromImageData(data)
+    if (sprite && sprite.frames.length >= 1) {
+      // Why: allSettled so a single failed crop doesn't leak the bitmaps that
+      // did succeed — close fulfilled ones before bailing out.
+      const results = await Promise.allSettled(
+        sprite.frames.map((f) => createImageBitmap(canvas, f.x, f.y, f.w, f.h))
+      )
+      const rejected = results.some((r) => r.status === 'rejected')
+      if (rejected) {
+        for (const r of results) {
+          if (r.status === 'fulfilled') {
+            r.value.close()
+          }
+        }
+        return null
+      }
+      const bitmaps = results.map((r) => (r as PromiseFulfilledResult<ImageBitmap>).value)
+      detected = { frames: sprite.frames, bitmaps, fps: spriteFps ?? 8 }
+    }
+    const out = await new Promise<Blob | null>((res) => canvas.toBlob(res, 'image/png'))
+    if (!out) {
+      return null
+    }
+    return { url: URL.createObjectURL(out), detected }
+  } catch {
+    return null
+  }
+}
+
+// Why: WebP/JPEG-compressed magenta keys leave wide gradient halos around
+// each sprite, so a tight RGB-distance check leaves ugly fringing. We use a
+// hue-style test instead: the magenta family has R and B much greater than
+// G. Anything matching gets fully cleared; anything close gets proportional
+// alpha so antialiased edges fade smoothly.
+function magentaScore(r: number, g: number, b: number): number {
+  // 0 = not magenta, 1 = pure magenta key. Requires both red and blue to
+  // dominate green (the signature of any magenta shade), and rejects greys
+  // / dark pixels which can otherwise have low-but-equal channels.
+  if (r < 100 || b < 100) {
+    return 0
+  }
+  const minRB = Math.min(r, b)
+  if (g >= minRB) {
+    return 0
+  }
+  const dom = (minRB - g) / 255 // how much R and B dominate green
+  return Math.max(0, Math.min(1, dom * 1.4))
+}
+
+function keyMagenta(px: Uint8ClampedArray): void {
+  for (let i = 0; i < px.length; i += 4) {
+    const score = magentaScore(px[i], px[i + 1], px[i + 2])
+    if (score <= 0) {
+      continue
+    }
+    if (score >= 0.5) {
+      px[i + 3] = 0
+      px[i] = 0
+      px[i + 1] = 0
+      px[i + 2] = 0
+    } else {
+      const keep = 1 - score * 2
+      px[i + 3] = Math.round(px[i + 3] * Math.max(0, keep))
+    }
+  }
+}
+
+function loadImage(url: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image()
+    img.onload = () => resolve(img)
+    img.onerror = () => reject(new Error('image load failed'))
+    img.src = url
+  })
+}
+
 // Why: the store invokes this on removeCustomSidekick so the underlying Blob
 // is released; otherwise the blob: URL keeps it alive for the rest of the
 // session, wasting memory per imported image.
@@ -40,4 +170,11 @@ export function revokeCustomSidekickBlobUrl(id: string): void {
     URL.revokeObjectURL(url)
     blobUrlCache.delete(id)
   }
+  const detected = detectedSpriteCache.get(id)
+  if (detected) {
+    for (const bmp of detected.bitmaps) {
+      bmp.close()
+    }
+    detectedSpriteCache.delete(id)
+  }
 }
diff --git a/src/renderer/src/components/sidekick/sprite-frame-detection.ts b/src/renderer/src/components/sidekick/sprite-frame-detection.ts
new file mode 100644
index 00000000000..45a73fa041d
--- /dev/null
+++ b/src/renderer/src/components/sidekick/sprite-frame-detection.ts
@@ -0,0 +1,104 @@
+// Why: pet bundles often ship a sprite sheet without manifest frame data, so
+// we can't grid-step it. The sheets we see in the wild leave magenta (chroma
+// keyed in sidekick-blob-cache) or transparent gutters between sprites.
+// After keying, find connected non-empty rows → bands; within the best band,
+// split on empty columns to get one frame per sprite. The result drives the
+// canvas-based animation in the overlay.
+
+export type DetectedFrame = { x: number; y: number; w: number; h: number }
+export type DetectedSprite = { frames: DetectedFrame[] }
+
+const ALPHA_EMPTY = 16
+const MIN_DIM = 8
+
+function isPixelEmpty(data: Uint8ClampedArray, idx: number): boolean {
+  return data[idx + 3] < ALPHA_EMPTY
+}
+
+function computeRowEmpty(data: Uint8ClampedArray, width: number, height: number): Uint8Array {
+  const rowEmpty = new Uint8Array(height)
+  for (let y = 0; y < height; y++) {
+    let empty = 1
+    const rowStart = y * width * 4
+    for (let x = 0; x < width; x++) {
+      if (!isPixelEmpty(data, rowStart + x * 4)) {
+        empty = 0
+        break
+      }
+    }
+    rowEmpty[y] = empty
+  }
+  return rowEmpty
+}
+
+function findBands(rowEmpty: Uint8Array): { y0: number; y1: number }[] {
+  const bands: { y0: number; y1: number }[] = []
+  let start = -1
+  for (let y = 0; y < rowEmpty.length; y++) {
+    if (!rowEmpty[y] && start < 0) {
+      start = y
+    } else if (rowEmpty[y] && start >= 0) {
+      bands.push({ y0: start, y1: y - 1 })
+      start = -1
+    }
+  }
+  if (start >= 0) {
+    bands.push({ y0: start, y1: rowEmpty.length - 1 })
+  }
+  return bands
+}
+
+function framesInBand(
+  data: Uint8ClampedArray,
+  width: number,
+  band: { y0: number; y1: number }
+): DetectedFrame[] {
+  const colEmpty = new Uint8Array(width)
+  for (let x = 0; x < width; x++) {
+    let empty = 1
+    for (let y = band.y0; y <= band.y1; y++) {
+      if (!isPixelEmpty(data, (y * width + x) * 4)) {
+        empty = 0
+        break
+      }
+    }
+    colEmpty[x] = empty
+  }
+  const frames: DetectedFrame[] = []
+  let start = -1
+  for (let x = 0; x < width; x++) {
+    if (!colEmpty[x] && start < 0) {
+      start = x
+    } else if (colEmpty[x] && start >= 0) {
+      frames.push({ x: start, y: band.y0, w: x - start, h: band.y1 - band.y0 + 1 })
+      start = -1
+    }
+  }
+  if (start >= 0) {
+    frames.push({ x: start, y: band.y0, w: width - start, h: band.y1 - band.y0 + 1 })
+  }
+  return frames.filter((f) => f.w >= MIN_DIM && f.h >= MIN_DIM)
+}
+
+export function detectFramesFromImageData(image: ImageData): DetectedSprite | null {
+  const { data, width, height } = image
+  const rowEmpty = computeRowEmpty(data, width, height)
+  const bands = findBands(rowEmpty)
+  if (bands.length === 0) {
+    return null
+  }
+  // Why: sheets are usually grids with the largest animation as the most-
+  // populated band. Pick the band yielding the most frames so the overlay
+  // shows a real walk/idle cycle rather than a single pose.
+  let best: DetectedFrame[] = []
+  for (const band of bands) {
+    const candidate = framesInBand(data, width, band)
+    if (candidate.length > best.length) {
+      best = candidate
+    }
+  }
+  if (best.length === 0) {
+    return null
+  }
+  return { frames: best }
+}
diff --git a/src/renderer/src/components/sidekick/useSidekickUrl.ts b/src/renderer/src/components/sidekick/useSidekickUrl.ts
index b2439a93fb8..dbe01513ab6 100644
--- a/src/renderer/src/components/sidekick/useSidekickUrl.ts
+++ b/src/renderer/src/components/sidekick/useSidekickUrl.ts
@@ -1,19 +1,35 @@
 import { useEffect, useRef, useState } from 'react'
+import type { CustomSidekick } from '../../../../shared/types'
 import { useAppStore } from '../../store'
 import { BUNDLED_SIDEKICK, findBundledSidekick, isBundledSidekickId } from './sidekick-models'
-import { blobUrlCache, loadCustomBlobUrl } from './sidekick-blob-cache'
+import {
+  blobUrlCache,
+  detectedSpriteCache,
+  loadCustomBlobUrl,
+  type DetectedSpriteCacheEntry
+} from './sidekick-blob-cache'
 
 // Re-export so existing callers (the store slice) that point at this module
 // keep working without knowing about the cache module split.
 export { revokeCustomSidekickBlobUrl } from './sidekick-blob-cache'
 
+export type ResolvedSidekick =
+  | { url: string; ready: boolean; sprite: null; detected: null }
+  | {
+      url: string
+      ready: boolean
+      sprite: NonNullable<CustomSidekick['sprite']>
+      detected: null
+    }
+  | { url: string; ready: boolean; sprite: null; detected: DetectedSpriteCacheEntry }
+
 /** Resolve the active sidekick to a URL the overlay can render.
  *
  *  For bundled sidekicks this is synchronous. For custom ones we issue an
  *  IPC read and build a blob: URL with the correct MIME; until that resolves,
  *  we fall back to the bundled default so the overlay is never empty.
  */
-export function useSidekickUrl(): { url: string; ready: boolean } {
+export function useSidekickUrl(): ResolvedSidekick {
   const sidekickId = useAppStore((s) => s.sidekickId)
   const customSidekicks = useAppStore((s) => s.customSidekicks)
   const bundled = isBundledSidekickId(sidekickId)
@@ -30,6 +46,10 @@ export function useSidekickUrl(): { url: string; ready: boolean } {
   const customId = customMeta?.id ?? null
   const customFileName = customMeta?.fileName ?? null
   const customMime = customMeta?.mimeType ?? 'image/png'
+  const customKind = customMeta?.kind ?? 'image'
+  // Why: prefer manifest fps captured at import time; sprite-with-frame entries
+  // store fps on `sprite`, frame-less bundles carry it on `spriteFps`.
+  const customSpriteFps = customMeta?.sprite?.fps ?? customMeta?.spriteFps
   useEffect(() => {
     if (!customId || !customFileName) {
       setCustomUrl(null)
@@ -45,26 +65,39 @@ export function useSidekickUrl(): { url: string; ready: boolean } {
     setCustomUrl(null)
     pendingRef.current = customId
     let cancelled = false
-    void loadCustomBlobUrl(customId, customFileName, customMime).then((url) => {
-      if (cancelled || pendingRef.current !== customId) {
-        return
+    void loadCustomBlobUrl(customId, customFileName, customMime, customKind, customSpriteFps).then(
+      (url) => {
+        if (cancelled || pendingRef.current !== customId) {
+          return
+        }
+        setCustomUrl(url)
       }
-      setCustomUrl(url)
-    })
+    )
     return () => {
       cancelled = true
     }
-  }, [customId, customFileName, customMime])
+  }, [customId, customFileName, customMime, customKind, customSpriteFps])
 
   if (bundled) {
     const sidekick = findBundledSidekick(sidekickId) ?? BUNDLED_SIDEKICK
-    return { url: sidekick.url, ready: true }
+    return { url: sidekick.url, ready: true, sprite: null, detected: null }
   }
   if (customMeta && customUrl) {
-    return { url: customUrl, ready: true }
+    // Why: guard against manifest entries with zero/negative dims or fps —
+    // those would break the overlay's frame math, so fall through to detection.
+    if (
+      customMeta.sprite &&
+      customMeta.sprite.frameWidth > 0 &&
+      customMeta.sprite.frameHeight > 0 &&
+      customMeta.sprite.fps > 0
+    ) {
+      return { url: customUrl, ready: true, sprite: customMeta.sprite, detected: null }
+    }
+    const detected = detectedSpriteCache.get(customMeta.id)
+    if (detected) {
+      return { url: customUrl, ready: true, sprite: null, detected }
+    }
+    return { url: customUrl, ready: true, sprite: null, detected: null }
   }
-  // Fallback: while a custom blob URL is loading (or if the custom sidekick is
-  // missing entirely), render the bundled default so the overlay doesn't
-  // flash empty.
-  return { url: BUNDLED_SIDEKICK.url, ready: false }
+  return { url: BUNDLED_SIDEKICK.url, ready: false, sprite: null, detected: null }
 }
diff --git a/src/renderer/src/components/status-bar/MemoryStatusSegment.tsx b/src/renderer/src/components/status-bar/MemoryStatusSegment.tsx
deleted file mode 100644
index 4e314a52fbd..00000000000
--- a/src/renderer/src/components/status-bar/MemoryStatusSegment.tsx
+++ /dev/null
@@ -1,911 +0,0 @@
-/* eslint-disable max-lines -- Why: the popover, its sub-sections, the
-   sparkline, and the formatters are all small pieces that only exist to
-   serve this one status-bar segment. Keeping them co-located follows the
-   same convention as the other *StatusSegment.tsx files (see StatusBar.tsx). */
-import React, { memo, useCallback, useEffect, useMemo, useState } from 'react'
-import { ChevronDown, ChevronRight, MemoryStick, Moon, Trash2 } from 'lucide-react'
-import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
-import { cn } from '@/lib/utils'
-import { activateAndRevealWorktree } from '@/lib/worktree-activation'
-import { useAppStore } from '../../store'
-import { useWorktreeMap } from '../../store/selectors'
-import { runWorktreeDelete } from '../sidebar/delete-worktree-flow'
-import { runSleepWorktree } from '../sidebar/sleep-worktree-flow'
-import type {
-  AppMemory,
-  SessionMemory,
-  TerminalTab,
-  UsageValues,
-  Worktree,
-  WorktreeMemory
-} from '../../../../shared/types'
-import { ORPHAN_WORKTREE_ID } from '../../../../shared/constants'
-
-// ─── Constants ──────────────────────────────────────────────────────
-
-const POLL_MS = 2_000
-
-type SortOption = 'memory' | 'cpu' | 'name'
-
-const METRIC_COLUMNS_CLS = 'flex items-center shrink-0 tabular-nums'
-const CPU_COLUMN_CLS = 'w-12 text-right'
-const MEM_COLUMN_CLS = 'w-16 text-right'
-
-// ─── Formatters ─────────────────────────────────────────────────────
-
-function formatMemory(bytes: number): string {
-  if (bytes < 1024 * 1024) {
-    return `${Math.round(bytes / 1024)} KB`
-  }
-  if (bytes < 1024 * 1024 * 1024) {
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
-  }
-  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`
-}
-
-function formatCpu(percent: number): string {
-  return `${percent.toFixed(1)}%`
-}
-
-function formatPercent(value: number): string {
-  return `${value.toFixed(0)}%`
-}
-
-// ─── Session label resolution ───────────────────────────────────────
-
-function parsePaneKey(paneKey: string | null): { tabId: string; paneRuntimeId: number } | 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 }
-}
-
-function sessionRowLabel(
-  session: SessionMemory,
-  worktreeId: string,
-  tabsByWorktree: Record<string, TerminalTab[]>,
-  runtimePaneTitlesByTabId: Record<string, Record<number, string>>
-): string {
-  const parsed = parsePaneKey(session.paneKey)
-  if (parsed) {
-    const tabs = tabsByWorktree[worktreeId] ?? []
-    const tabIndex = tabs.findIndex((t) => t.id === parsed.tabId)
-    const tab = tabIndex >= 0 ? tabs[tabIndex] : undefined
-    if (tab) {
-      // Why: mirror the tab bar's label precedence (SortableTab: customTitle
-      // wins over the live OSC-updated title). Fall through to the runtime
-      // pane title so split panes stay identifiable, then the saved tab
-      // title, and finally a stable index-based label.
-      const custom = tab.customTitle?.trim()
-      if (custom) {
-        return custom
-      }
-      const runtime = runtimePaneTitlesByTabId[parsed.tabId]?.[parsed.paneRuntimeId]?.trim()
-      if (runtime) {
-        return runtime
-      }
-      return tab.defaultTitle?.trim() || tab.title?.trim() || `Terminal ${tabIndex + 1}`
-    }
-  }
-  if (session.pid > 0) {
-    return `pid ${session.pid}`
-  }
-  const fallback = session.sessionId?.slice(0, 8)
-  return fallback ? `session ${fallback}` : '(unknown session)'
-}
-
-// ─── Grouping helpers ───────────────────────────────────────────────
-
-type RepoGroup = {
-  repoId: string
-  repoName: string
-  cpu: number
-  memory: number
-  worktrees: WorktreeMemory[]
-}
-
-function bucketByRepo(worktrees: WorktreeMemory[]): RepoGroup[] {
-  const map = new Map<string, RepoGroup>()
-  for (const wt of worktrees) {
-    const key = wt.repoId || 'unknown'
-    let group = map.get(key)
-    if (!group) {
-      group = {
-        repoId: key,
-        repoName: wt.repoName || 'Unknown Repo',
-        cpu: 0,
-        memory: 0,
-        worktrees: []
-      }
-      map.set(key, group)
-    }
-    group.cpu += wt.cpu
-    group.memory += wt.memory
-    group.worktrees.push(wt)
-  }
-  return [...map.values()]
-}
-
-function sortWorktreesBy(
-  list: WorktreeMemory[],
-  sort: SortOption,
-  labelFor: (wt: WorktreeMemory) => string
-): WorktreeMemory[] {
-  const copy = [...list]
-  if (sort === 'memory') {
-    copy.sort((a, b) => b.memory - a.memory)
-  } else if (sort === 'cpu') {
-    copy.sort((a, b) => b.cpu - a.cpu)
-  } else {
-    // Why labelFor instead of worktreeName: the row label prefers the
-    // user-editable displayName over the dirname, so alphabetical order
-    // needs to match what the user actually sees in the list.
-    copy.sort((a, b) => labelFor(a).localeCompare(labelFor(b)))
-  }
-  return copy
-}
-
-function sortRepoGroupsBy(groups: RepoGroup[], sort: SortOption): RepoGroup[] {
-  const copy = [...groups]
-  if (sort === 'memory') {
-    copy.sort((a, b) => b.memory - a.memory)
-  } else if (sort === 'cpu') {
-    copy.sort((a, b) => b.cpu - a.cpu)
-  } else {
-    copy.sort((a, b) => a.repoName.localeCompare(b.repoName))
-  }
-  return copy
-}
-
-// ─── Sparkline ──────────────────────────────────────────────────────
-
-type SparklineProps = {
-  samples: number[]
-  width?: number
-  height?: number
-}
-
-function SparklineImpl({ samples, width = 48, height = 14 }: SparklineProps): React.JSX.Element {
-  const points = useMemo(() => {
-    // Why: defensive against IPC payload drift during hot-reload — a missing
-    // or non-array history should render as a flat line, not throw.
-    const safe = Array.isArray(samples) ? samples : []
-    if (safe.length < 2) {
-      const midY = (height / 2).toFixed(1)
-      return `0,${midY} ${width},${midY}`
-    }
-
-    let min = safe[0]
-    let max = safe[0]
-    for (const v of safe) {
-      if (v < min) {
-        min = v
-      }
-      if (v > max) {
-        max = v
-      }
-    }
-    const range = max - min || 1
-    const stepX = width / (safe.length - 1)
-
-    const out: string[] = []
-    for (let i = 0; i < safe.length; i++) {
-      const x = (i * stepX).toFixed(1)
-      // SVG y grows downward, so invert: larger values render higher.
-      const y = (height - ((safe[i] - min) / range) * height).toFixed(1)
-      out.push(`${x},${y}`)
-    }
-    return out.join(' ')
-  }, [samples, width, height])
-
-  return (
-    <svg
-      width={width}
-      height={height}
-      viewBox={`0 0 ${width} ${height}`}
-      aria-hidden
-      preserveAspectRatio="none"
-    >
-      <polyline
-        points={points}
-        fill="none"
-        strokeWidth={1}
-        strokeLinecap="round"
-        strokeLinejoin="round"
-        className="stroke-muted-foreground/70"
-      />
-    </svg>
-  )
-}
-
-/** Why memo: popover polls every 2s and shallow-equal samples shouldn't
- *  trigger a full re-scan of the min/max/polyline points for every row. */
-const Sparkline = memo(SparklineImpl, (a, b) => {
-  if (a.width !== b.width || a.height !== b.height) {
-    return false
-  }
-  const sa = Array.isArray(a.samples) ? a.samples : []
-  const sb = Array.isArray(b.samples) ? b.samples : []
-  if (sa === sb) {
-    return true
-  }
-  if (sa.length !== sb.length) {
-    return false
-  }
-  for (let i = 0; i < sa.length; i++) {
-    if (sa[i] !== sb[i]) {
-      return false
-    }
-  }
-  return true
-})
-
-// ─── Leaf UI: metric row ────────────────────────────────────────────
-
-function MetricPair({
-  cpu,
-  memory,
-  size = 'base'
-}: {
-  cpu: number
-  memory: number
-  size?: 'base' | 'small'
-}): React.JSX.Element {
-  const textCls = size === 'small' ? 'text-[11px]' : 'text-xs'
-  return (
-    <div className={cn(METRIC_COLUMNS_CLS, textCls, 'text-muted-foreground')}>
-      <span className={CPU_COLUMN_CLS}>{formatCpu(cpu)}</span>
-      <span className={MEM_COLUMN_CLS}>{formatMemory(memory)}</span>
-    </div>
-  )
-}
-
-// ─── Section: app (main / renderer / other) ─────────────────────────
-
-function AppSection({
-  app,
-  isCollapsed,
-  onToggle
-}: {
-  app: AppMemory
-  isCollapsed: boolean
-  onToggle: () => void
-}): React.JSX.Element {
-  return (
-    <div className="border-t border-border/50">
-      <div className="flex items-center">
-        <button
-          type="button"
-          onClick={onToggle}
-          className="pl-2 py-2 pr-0.5 transition-colors hover:bg-muted/50"
-          aria-label={isCollapsed ? 'Expand Orca' : 'Collapse Orca'}
-          aria-expanded={!isCollapsed}
-        >
-          {isCollapsed ? (
-            <ChevronRight className="h-3 w-3 text-muted-foreground" />
-          ) : (
-            <ChevronDown className="h-3 w-3 text-muted-foreground" />
-          )}
-        </button>
-        <div className="flex-1 min-w-0 py-2 pr-3 flex items-center justify-between">
-          <span className="text-[11px] font-semibold uppercase tracking-wide truncate text-muted-foreground">
-            Orca
-          </span>
-          <div className="flex items-center gap-2 shrink-0">
-            <Sparkline samples={app.history} />
-            <MetricPair cpu={app.cpu} memory={app.memory} />
-          </div>
-        </div>
-      </div>
-      {!isCollapsed && (
-        <div className="border-t border-border/30">
-          <AppSubRow label="Main" values={app.main} />
-          <AppSubRow label="Renderer" values={app.renderer} />
-          {(app.other.cpu > 0 || app.other.memory > 0) && (
-            <AppSubRow label="Other" values={app.other} />
-          )}
-        </div>
-      )}
-    </div>
-  )
-}
-
-function AppSubRow({ label, values }: { label: string; values: UsageValues }): React.JSX.Element {
-  return (
-    <div className="px-3 py-1.5 pl-6 flex items-center justify-between">
-      <span className="text-[11px] text-muted-foreground truncate">{label}</span>
-      <MetricPair cpu={values.cpu} memory={values.memory} size="small" />
-    </div>
-  )
-}
-
-// ─── Section: worktree tree ─────────────────────────────────────────
-
-function WorktreeSection({
-  worktrees,
-  sortOption,
-  collapsedRepos,
-  toggleRepo,
-  collapsedWorktrees,
-  toggleWorktree,
-  navigateToWorktree,
-  onSleep,
-  onDelete
-}: {
-  worktrees: WorktreeMemory[]
-  sortOption: SortOption
-  collapsedRepos: Set<string>
-  toggleRepo: (repoId: string) => void
-  collapsedWorktrees: Set<string>
-  toggleWorktree: (worktreeId: string) => void
-  navigateToWorktree: (worktreeId: string) => void
-  onSleep: (worktreeId: string) => void
-  onDelete: (worktreeId: string) => void
-}): React.JSX.Element {
-  // Why: these slices mutate frequently (runtimePaneTitlesByTabId updates on
-  // every terminal OSC escape). Subscribing inside WorktreeSection — which
-  // only mounts when the popover is open — prevents those updates from
-  // re-rendering the always-mounted status-bar segment.
-  const tabsByWorktree = useAppStore((s) => s.tabsByWorktree)
-  const runtimePaneTitlesByTabId = useAppStore((s) => s.runtimePaneTitlesByTabId)
-
-  // Why: WorktreeMemory is a lightweight snapshot; we look the real Worktree
-  // record up from the store so rows can (a) disable Delete for the main
-  // worktree, and (b) render the user-editable displayName instead of the
-  // dirname. Use the shared cached selector so we don't duplicate the
-  // WeakMap-cached Map the rest of the app already shares.
-  const worktreeById = useWorktreeMap()
-
-  // Shared label resolver: prefer displayName, fall back to the dirname
-  // carried on the memory snapshot. Used for both rendering and alpha-sort.
-  const labelFor = useCallback(
-    (wt: WorktreeMemory): string =>
-      worktreeById.get(wt.worktreeId)?.displayName?.trim() || wt.worktreeName,
-    [worktreeById]
-  )
-
-  // Memoize grouping: popover polls every 2s, so without this we'd rebuild
-  // the Map + arrays on every render even when nothing changed.
-  const repoGroups = useMemo(
-    () =>
-      sortRepoGroupsBy(bucketByRepo(worktrees), sortOption).map((group) => ({
-        ...group,
-        worktrees: sortWorktreesBy(group.worktrees, sortOption, labelFor)
-      })),
-    [worktrees, sortOption, labelFor]
-  )
-
-  // Why: when only one repo is active, the repo header row adds a useless
-  // level of nesting — the worktrees are the interesting thing. Flatten
-  // straight to worktree rows in that case.
-  const singleRepo = repoGroups.length === 1
-
-  const renderWorktree = (wt: WorktreeMemory): React.JSX.Element => {
-    const storeRecord = worktreeById.get(wt.worktreeId) ?? null
-    return (
-      <WorktreeRow
-        key={wt.worktreeId}
-        worktree={wt}
-        storeRecord={storeRecord}
-        isCollapsed={collapsedWorktrees.has(wt.worktreeId)}
-        onToggle={() => toggleWorktree(wt.worktreeId)}
-        onNavigate={() => navigateToWorktree(wt.worktreeId)}
-        onSleep={() => onSleep(wt.worktreeId)}
-        onDelete={() => onDelete(wt.worktreeId)}
-        tabsByWorktree={tabsByWorktree}
-        runtimePaneTitlesByTabId={runtimePaneTitlesByTabId}
-      />
-    )
-  }
-
-  if (singleRepo) {
-    return <>{repoGroups[0].worktrees.map(renderWorktree)}</>
-  }
-
-  return (
-    <>
-      {repoGroups.map((group) => {
-        const repoCollapsed = collapsedRepos.has(group.repoId)
-        return (
-          <div key={group.repoId} className="border-b border-border/50 last:border-b-0">
-            <div className="flex items-center">
-              <button
-                type="button"
-                onClick={() => toggleRepo(group.repoId)}
-                className="pl-2 py-2 pr-0.5 transition-colors hover:bg-muted/50"
-                aria-label={repoCollapsed ? 'Expand repo' : 'Collapse repo'}
-              >
-                {repoCollapsed ? (
-                  <ChevronRight className="h-3 w-3 text-muted-foreground" />
-                ) : (
-                  <ChevronDown className="h-3 w-3 text-muted-foreground" />
-                )}
-              </button>
-              <div className="flex-1 min-w-0 py-2 pr-3 flex items-center justify-between">
-                <span className="text-[11px] font-semibold uppercase tracking-wide truncate text-muted-foreground">
-                  {group.repoName}
-                </span>
-                <MetricPair cpu={group.cpu} memory={group.memory} />
-              </div>
-            </div>
-
-            {!repoCollapsed && (
-              <div className="border-t border-border/30">{group.worktrees.map(renderWorktree)}</div>
-            )}
-          </div>
-        )
-      })}
-    </>
-  )
-}
-
-function WorktreeRow({
-  worktree,
-  storeRecord,
-  isCollapsed,
-  onToggle,
-  onNavigate,
-  onSleep,
-  onDelete,
-  tabsByWorktree,
-  runtimePaneTitlesByTabId
-}: {
-  worktree: WorktreeMemory
-  storeRecord: Worktree | null
-  isCollapsed: boolean
-  onToggle: () => void
-  onNavigate: () => void
-  onSleep: () => void
-  onDelete: () => void
-  tabsByWorktree: Record<string, TerminalTab[]>
-  runtimePaneTitlesByTabId: Record<string, Record<number, string>>
-}): React.JSX.Element {
-  const hasSessions = worktree.sessions.length > 0
-  // Why: actions are only meaningful for real worktrees — orphan/unknown
-  // rows are synthetic buckets with no row to act on.
-  const showActions = worktree.worktreeId !== ORPHAN_WORKTREE_ID && storeRecord !== null
-  const isMainWorktree = storeRecord?.isMainWorktree ?? false
-  // Why: Worktree.displayName is the user-editable workspace name (set via
-  // Rename). Fall back to the dirname-shaped worktreeName from the memory
-  // snapshot for orphan/unresolved rows that have no store record.
-  const rowLabel = storeRecord?.displayName?.trim() || worktree.worktreeName
-
-  return (
-    <div className="border-b border-border/20 last:border-b-0">
-      <div className="group/wtrow flex items-center ml-2 transition-colors hover:bg-muted/60">
-        {hasSessions ? (
-          <button
-            type="button"
-            onClick={onToggle}
-            className="pl-2 py-2 pr-0.5 shrink-0"
-            aria-label={isCollapsed ? 'Expand workspace' : 'Collapse workspace'}
-          >
-            {isCollapsed ? (
-              <ChevronRight className="h-3 w-3 text-muted-foreground" />
-            ) : (
-              <ChevronDown className="h-3 w-3 text-muted-foreground" />
-            )}
-          </button>
-        ) : (
-          // Why this width: matches the chevron button's pl-2 + w-3 + pr-0.5
-          // footprint so rows without sessions don't shift horizontally
-          // relative to rows with sessions.
-          <span
-            className="pl-2 py-2 pr-0.5 shrink-0 w-[calc(0.5rem+0.75rem+0.125rem)]"
-            aria-hidden
-          />
-        )}
-        <button
-          type="button"
-          onClick={onNavigate}
-          aria-label={`Open workspace ${rowLabel}`}
-          className="flex-1 min-w-0 py-2 pr-2 pl-1 text-left"
-        >
-          <span className="text-xs font-medium truncate block">{rowLabel}</span>
-        </button>
-        <div className="flex items-center gap-2 shrink-0 pr-3">
-          {/* Why the relative wrapper + absolute actions: the sparkline
-              reserves the space so the row width never changes on hover.
-              The actions fade in on top of the sparkline (which fades out
-              in the same transition), preventing the layout "jump" that
-              happened when the sparkline was toggled via display:none. */}
-          <div className="relative">
-            <span
-              className={cn(
-                'block transition-opacity',
-                showActions &&
-                  'group-hover/wtrow:opacity-0 group-hover/wtrow:pointer-events-none group-focus-within/wtrow:opacity-0 group-focus-within/wtrow:pointer-events-none'
-              )}
-              aria-hidden={showActions ? undefined : true}
-            >
-              <Sparkline samples={worktree.history} />
-            </span>
-            {showActions && (
-              // Why pointer-events pairing: opacity alone leaves the buttons
-              // clickable when invisible (touch devices have no hover state),
-              // so the Delete button can fire on an accidental tap.
-              <div className="absolute inset-0 flex items-center justify-end gap-0.5 opacity-0 pointer-events-none transition-opacity group-hover/wtrow:opacity-100 group-hover/wtrow:pointer-events-auto group-focus-within/wtrow:opacity-100 group-focus-within/wtrow:pointer-events-auto">
-                <Tooltip delayDuration={300}>
-                  <TooltipTrigger asChild>
-                    <button
-                      type="button"
-                      onClick={onSleep}
-                      aria-label={`Sleep workspace ${rowLabel}`}
-                      className="p-0.5 rounded text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
-                    >
-                      <Moon className="size-3" />
-                    </button>
-                  </TooltipTrigger>
-                  <TooltipContent
-                    side="top"
-                    sideOffset={4}
-                    className="z-[70] max-w-[200px] text-pretty"
-                  >
-                    Sleep — close all panels in this workspace to free memory.
-                  </TooltipContent>
-                </Tooltip>
-                <Tooltip delayDuration={300}>
-                  <TooltipTrigger asChild>
-                    <button
-                      type="button"
-                      onClick={onDelete}
-                      disabled={isMainWorktree}
-                      aria-label={`Delete workspace ${rowLabel}`}
-                      className={cn(
-                        'p-0.5 rounded text-muted-foreground transition-colors',
-                        isMainWorktree
-                          ? 'opacity-40 cursor-not-allowed'
-                          : 'hover:bg-destructive/10 hover:text-destructive'
-                      )}
-                    >
-                      <Trash2 className="size-3" />
-                    </button>
-                  </TooltipTrigger>
-                  <TooltipContent
-                    side="top"
-                    sideOffset={4}
-                    className="z-[70] max-w-[200px] text-pretty"
-                  >
-                    {isMainWorktree ? 'The main workspace cannot be deleted.' : 'Delete workspace.'}
-                  </TooltipContent>
-                </Tooltip>
-              </div>
-            )}
-          </div>
-          <MetricPair cpu={worktree.cpu} memory={worktree.memory} />
-        </div>
-      </div>
-
-      {!isCollapsed &&
-        worktree.sessions.map((session) => (
-          // Why: sessionId can be null/fall back to ptyId; combine with pid
-          // so two sessions from the same process family don't collide in
-          // React reconciliation.
-          <div
-            key={`${session.sessionId}:${session.pid}`}
-            className="px-3 py-1.5 pl-10 flex items-center justify-between"
-          >
-            <span className="text-[11px] text-muted-foreground truncate min-w-0 mr-2">
-              {sessionRowLabel(
-                session,
-                worktree.worktreeId,
-                tabsByWorktree,
-                runtimePaneTitlesByTabId
-              )}
-            </span>
-            <MetricPair cpu={session.cpu} memory={session.memory} size="small" />
-          </div>
-        ))}
-    </div>
-  )
-
-  // Why: wrap real rows in the shared context menu so right-click exposes
-}
-
-// ─── Segment (top-level) ────────────────────────────────────────────
-
-export function MemoryStatusSegment({
-  iconOnly
-}: {
-  // Why: `compact` is accepted for uniformity with the other *StatusSegment
-  // components but is not used — the icon/badge layout already fits inside
-  // a compact status bar.
-  compact?: boolean
-  iconOnly: boolean
-}): React.JSX.Element {
-  const snapshot = useAppStore((s) => s.memorySnapshot)
-  const fetchSnapshot = useAppStore((s) => s.fetchMemorySnapshot)
-  // Why: worktree metadata (map, skipDeleteWorktreeConfirm,
-  // clearWorktreeDeleteState, openModal) is only needed at click time inside
-  // `deleteWorktree`. This segment is always mounted in the status bar, so
-  // subscribing to those slices at the top level would cause it (and every
-  // descendant) to re-render on unrelated worktree metadata churn
-  // (pin/rename/unread/session). The shared `runWorktreeDelete` helper pulls
-  // them imperatively via `useAppStore.getState()` instead.
-
-  const [open, setOpen] = useState(false)
-  const [sortOption, setSortOption] = useState<SortOption>('memory')
-  const [collapsedRepos, setCollapsedRepos] = useState<Set<string>>(new Set())
-  const [collapsedWorktrees, setCollapsedWorktrees] = useState<Set<string>>(new Set())
-  // Why: the Orca app breakdown (Main/Renderer/Other) is a diagnostic detail
-  // most users don't need to see every time — collapse it by default and
-  // surface the per-worktree usage, which is what people usually open this
-  // popover to investigate.
-  const [appCollapsed, setAppCollapsed] = useState(true)
-
-  // Why: only poll while the popover is open. When closed, the badge shows
-  // whatever value was last fetched — good enough for a passive indicator
-  // and keeps us from waking the main process every few seconds.
-  useEffect(() => {
-    if (!open) {
-      return
-    }
-    void fetchSnapshot()
-    const timer = window.setInterval(() => {
-      void fetchSnapshot()
-    }, POLL_MS)
-    return () => window.clearInterval(timer)
-  }, [open, fetchSnapshot])
-
-  // Derived values are grouped into one memo so open/sort/collapse state
-  // changes don't recompute them.
-  const { totalMemory, totalCpu, hostShare, badgeLabel } = useMemo(() => {
-    const memory = snapshot?.totalMemory ?? 0
-    const cpu = snapshot?.totalCpu ?? 0
-    const hostTotal = snapshot?.host.totalMemory ?? 0
-    return {
-      totalMemory: memory,
-      totalCpu: cpu,
-      hostShare: hostTotal > 0 ? (memory / hostTotal) * 100 : 0,
-      badgeLabel: snapshot ? formatMemory(memory) : '—'
-    }
-  }, [snapshot])
-
-  // Why empty deps: these callbacks only call the state setter returned by
-  // useState, which React guarantees is stable across renders — so we don't
-  // need to list it. Wrapping in useCallback keeps the reference stable across
-  // the 2s polling re-renders so descendants can be memoized downstream.
-  const toggleRepo = useCallback((repoId: string): void => {
-    setCollapsedRepos((prev) => {
-      const next = new Set(prev)
-      if (next.has(repoId)) {
-        next.delete(repoId)
-      } else {
-        next.add(repoId)
-      }
-      return next
-    })
-  }, [])
-
-  const toggleWorktree = useCallback((worktreeId: string): void => {
-    setCollapsedWorktrees((prev) => {
-      const next = new Set(prev)
-      if (next.has(worktreeId)) {
-        next.delete(worktreeId)
-      } else {
-        next.add(worktreeId)
-      }
-      return next
-    })
-  }, [])
-
-  // Deps intentionally empty: only uses the stable setOpen setter and
-  // module-level imports (ORPHAN_WORKTREE_ID, activateAndRevealWorktree).
-  const navigateToWorktree = useCallback((worktreeId: string): void => {
-    // Orphan bucket has a synthetic id with no real worktree to reveal.
-    if (worktreeId === ORPHAN_WORKTREE_ID) {
-      setOpen(false)
-      return
-    }
-    // Why: returns false when the worktree has been deleted between
-    // snapshot capture and this click. Leave the popover open in that
-    // case so a silent no-op doesn't look like a broken button.
-    const result = activateAndRevealWorktree(worktreeId)
-    if (result === false) {
-      return
-    }
-    setOpen(false)
-  }, [])
-
-  // Why this thin wrapper: the popover needs to close before the modal/toast
-  // appears (Radix's outside-pointerdown would otherwise dismiss the dialog).
-  // The actual decision tree lives in `runWorktreeDelete` so both the popover
-  // and the sidebar context menu stay in sync.
-  const deleteWorktree = useCallback((worktreeId: string): void => {
-    setOpen(false)
-    runWorktreeDelete(worktreeId)
-  }, [])
-
-  // Stable callback so onSleep prop identity doesn't churn across polls.
-  const handleSleep = useCallback((id: string): void => {
-    void runSleepWorktree(id)
-  }, [])
-
-  return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <Tooltip delayDuration={150}>
-        <TooltipTrigger asChild>
-          <PopoverTrigger asChild>
-            <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="Memory usage"
-            >
-              <MemoryStick className="size-3 text-muted-foreground" />
-              {!iconOnly && (
-                <span className="text-[11px] font-medium tabular-nums text-muted-foreground">
-                  {badgeLabel}
-                </span>
-              )}
-            </button>
-          </PopoverTrigger>
-        </TooltipTrigger>
-        <TooltipContent side="top" sideOffset={6}>
-          Memory — {badgeLabel}
-        </TooltipContent>
-      </Tooltip>
-
-      <PopoverContent
-        side="top"
-        align="end"
-        sideOffset={8}
-        className="w-[26rem] p-0"
-        // Why: the first focusable element inside is the CPU/memory/% span
-        // (tabIndex=0 so the tooltip is keyboard-reachable). Without this,
-        // Radix auto-focuses that span on open, which triggers its tooltip
-        // and leaves it stuck until the user mouses over something else.
-        onOpenAutoFocus={(event) => event.preventDefault()}
-      >
-        {/* Why: the popover trigger already announces "Memory & CPU", so a
-            heading row is redundant. We lead with the totals — which is what
-            most people open this for — on a single compact line. */}
-        {snapshot && (
-          <div className="px-3 py-2 border-b border-border flex items-baseline gap-3 text-xs tabular-nums">
-            <Tooltip delayDuration={200}>
-              <TooltipTrigger asChild>
-                {/* Why tabIndex on span triggers: Radix Tooltip needs a
-                    focusable child for keyboard reveal; plain <span> isn't
-                    focusable by default. */}
-                <span
-                  tabIndex={0}
-                  className="font-medium text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:rounded"
-                >
-                  {formatCpu(totalCpu)}
-                </span>
-              </TooltipTrigger>
-              <TooltipContent side="top" sideOffset={6} className="z-[70] max-w-xs">
-                Combined CPU load. Values above 100% mean more than one core is working at once.
-              </TooltipContent>
-            </Tooltip>
-            <span className="text-muted-foreground/50">·</span>
-            <Tooltip delayDuration={200}>
-              <TooltipTrigger asChild>
-                <span
-                  tabIndex={0}
-                  className="font-medium text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:rounded"
-                >
-                  {formatMemory(totalMemory)}
-                </span>
-              </TooltipTrigger>
-              <TooltipContent side="top" sideOffset={6} className="z-[70] max-w-xs">
-                Resident memory held by Orca plus the processes under each worktree&apos;s
-                terminals.
-              </TooltipContent>
-            </Tooltip>
-            <span className="text-muted-foreground/50">·</span>
-            <Tooltip delayDuration={200}>
-              <TooltipTrigger asChild>
-                <span
-                  tabIndex={0}
-                  className="text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:rounded"
-                >
-                  {formatPercent(hostShare)} of system RAM
-                </span>
-              </TooltipTrigger>
-              <TooltipContent side="top" sideOffset={6} className="z-[70] max-w-xs">
-                How much of this machine&apos;s physical RAM the Orca-tracked processes are sitting
-                on.
-              </TooltipContent>
-            </Tooltip>
-          </div>
-        )}
-
-        {/* Why click-to-sort on the column headers: the headers already
-            label the columns, so doubling them up with a separate sort
-            control was pure redundancy. The active column is bolded so
-            users can see at a glance which one drives the order. */}
-        {snapshot && (
-          <div className="flex items-center justify-between px-3 py-1 bg-muted/30 border-b border-border/50 text-[10px] uppercase tracking-wide">
-            <button
-              type="button"
-              onClick={() => setSortOption('name')}
-              className={cn(
-                'hover:text-foreground transition-colors',
-                sortOption === 'name' ? 'font-semibold text-foreground' : 'text-muted-foreground/80'
-              )}
-              aria-pressed={sortOption === 'name'}
-            >
-              Name
-            </button>
-            <div className={cn(METRIC_COLUMNS_CLS, 'text-[10px]')}>
-              <button
-                type="button"
-                onClick={() => setSortOption('cpu')}
-                className={cn(
-                  CPU_COLUMN_CLS,
-                  'hover:text-foreground transition-colors',
-                  sortOption === 'cpu'
-                    ? 'font-semibold text-foreground'
-                    : 'text-muted-foreground/80'
-                )}
-                aria-pressed={sortOption === 'cpu'}
-              >
-                CPU
-              </button>
-              <button
-                type="button"
-                onClick={() => setSortOption('memory')}
-                className={cn(
-                  MEM_COLUMN_CLS,
-                  'hover:text-foreground transition-colors',
-                  sortOption === 'memory'
-                    ? 'font-semibold text-foreground'
-                    : 'text-muted-foreground/80'
-                )}
-                aria-pressed={sortOption === 'memory'}
-              >
-                Memory
-              </button>
-            </div>
-          </div>
-        )}
-
-        <div className="max-h-[50vh] overflow-y-auto scrollbar-sleek">
-          {snapshot && snapshot.worktrees.length > 0 && (
-            <WorktreeSection
-              worktrees={snapshot.worktrees}
-              sortOption={sortOption}
-              collapsedRepos={collapsedRepos}
-              toggleRepo={toggleRepo}
-              collapsedWorktrees={collapsedWorktrees}
-              toggleWorktree={toggleWorktree}
-              navigateToWorktree={navigateToWorktree}
-              onSleep={handleSleep}
-              onDelete={deleteWorktree}
-            />
-          )}
-
-          {snapshot && snapshot.worktrees.length === 0 && (
-            <div className="px-3 py-4 text-center text-xs text-muted-foreground">
-              Nothing running right now
-            </div>
-          )}
-
-          {/* Why Orca App at the bottom: it's a constant baseline everyone has,
-              so it's less informative than the per-worktree breakdown. Keep
-              it available but out of the way. */}
-          {snapshot && (
-            <AppSection
-              app={snapshot.app}
-              isCollapsed={appCollapsed}
-              onToggle={() => setAppCollapsed((v) => !v)}
-            />
-          )}
-
-          {!snapshot && (
-            <div className="px-3 py-4 text-center text-xs text-muted-foreground">Loading…</div>
-          )}
-        </div>
-      </PopoverContent>
-    </Popover>
-  )
-}
diff --git a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
new file mode 100644
index 00000000000..c7191f05b05
--- /dev/null
+++ b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
@@ -0,0 +1,1297 @@
+/* eslint-disable max-lines -- Why: consolidating memory + sessions into one
+   surface deliberately co-locates the sparkline, worktree tree, session list,
+   daemon actions, and kill-confirm dialog so the popover body and badge stay
+   consistent. Splitting across files would scatter render-state that only
+   exists to serve this one status-bar segment. See
+   docs/resource-usage-merge-spec.md for the full design. */
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  AlertTriangle,
+  ChevronDown,
+  ChevronRight,
+  LoaderCircle,
+  MemoryStick,
+  Moon,
+  RotateCw,
+  Terminal,
+  Trash2,
+  X
+} from 'lucide-react'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from '@/components/ui/dialog'
+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 { 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 {
+  mergeSnapshotAndSessions,
+  UNATTRIBUTED_REPO_ID,
+  type DaemonSession,
+  type Metric,
+  type UnifiedRepoGroup,
+  type UnifiedSessionRow,
+  type UnifiedWorktreeRow
+} from './mergeSnapshotAndSessions'
+
+const POLL_MS = 2_000
+const SESSIONS_POLL_MS = 10_000
+
+type SortOption = 'memory' | 'cpu' | 'name'
+
+const METRIC_COLUMNS_CLS = 'flex items-center shrink-0 tabular-nums'
+const CPU_COLUMN_CLS = 'w-12 text-right'
+const MEM_COLUMN_CLS = 'w-16 text-right'
+// Why: every row (session, worktree, repo, app) AND the column header
+// reserve this same trailing gutter so the CPU/Memory columns line up
+// regardless of whether a row carries a kill-X. The X button sits inside
+// this gutter for session rows; other rows leave it blank.
+const ROW_TRAILING_GUTTER_CLS = 'w-5 shrink-0 flex items-center justify-end'
+
+// ─── Formatters ─────────────────────────────────────────────────────
+
+function formatMemory(bytes: number): string {
+  if (bytes < 1024 * 1024) {
+    return `${Math.round(bytes / 1024)} KB`
+  }
+  if (bytes < 1024 * 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+  }
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`
+}
+
+function formatCpu(percent: number): string {
+  return `${percent.toFixed(1)}%`
+}
+
+function formatPercent(value: number): string {
+  return `${value.toFixed(0)}%`
+}
+
+function formatMetricCpu(value: Metric): string {
+  return value === null ? '—' : formatCpu(value)
+}
+
+function formatMetricMemory(value: Metric): string {
+  return value === null ? '—' : formatMemory(value)
+}
+
+// ─── Sparkline ──────────────────────────────────────────────────────
+
+type SparklineProps = {
+  samples: number[]
+  width?: number
+  height?: number
+}
+
+function SparklineImpl({ samples, width = 48, height = 14 }: SparklineProps): React.JSX.Element {
+  const points = useMemo(() => {
+    const safe = Array.isArray(samples) ? samples : []
+    if (safe.length < 2) {
+      const midY = (height / 2).toFixed(1)
+      return `0,${midY} ${width},${midY}`
+    }
+
+    let min = safe[0]
+    let max = safe[0]
+    for (const v of safe) {
+      if (v < min) {
+        min = v
+      }
+      if (v > max) {
+        max = v
+      }
+    }
+    const range = max - min || 1
+    const stepX = width / (safe.length - 1)
+
+    const out: string[] = []
+    for (let i = 0; i < safe.length; i++) {
+      const x = (i * stepX).toFixed(1)
+      const y = (height - ((safe[i] - min) / range) * height).toFixed(1)
+      out.push(`${x},${y}`)
+    }
+    return out.join(' ')
+  }, [samples, width, height])
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      aria-hidden
+      preserveAspectRatio="none"
+    >
+      <polyline
+        points={points}
+        fill="none"
+        strokeWidth={1}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        className="stroke-muted-foreground/70"
+      />
+    </svg>
+  )
+}
+
+const Sparkline = memo(SparklineImpl, (a, b) => {
+  if (a.width !== b.width || a.height !== b.height) {
+    return false
+  }
+  const sa = Array.isArray(a.samples) ? a.samples : []
+  const sb = Array.isArray(b.samples) ? b.samples : []
+  if (sa === sb) {
+    return true
+  }
+  if (sa.length !== sb.length) {
+    return false
+  }
+  for (let i = 0; i < sa.length; i++) {
+    if (sa[i] !== sb[i]) {
+      return false
+    }
+  }
+  return true
+})
+
+// ─── Leaf UI: metric row ────────────────────────────────────────────
+
+function MetricPair({
+  cpu,
+  memory,
+  size = 'base'
+}: {
+  cpu: Metric
+  memory: Metric
+  size?: 'base' | 'small'
+}): React.JSX.Element {
+  const textCls = size === 'small' ? 'text-[11px]' : 'text-xs'
+  const muted = cpu === null && memory === null
+  return (
+    <div
+      className={cn(
+        METRIC_COLUMNS_CLS,
+        textCls,
+        muted ? 'text-muted-foreground/50' : 'text-muted-foreground'
+      )}
+    >
+      <span className={CPU_COLUMN_CLS}>{formatMetricCpu(cpu)}</span>
+      <span className={MEM_COLUMN_CLS}>{formatMetricMemory(memory)}</span>
+    </div>
+  )
+}
+
+function AppSubRow({ label, values }: { label: string; values: UsageValues }): React.JSX.Element {
+  return (
+    <div className="px-3 py-1.5 pl-6 flex items-center justify-between gap-2">
+      <span className="text-[11px] text-muted-foreground truncate">{label}</span>
+      <div className="flex items-center gap-2 shrink-0">
+        <MetricPair cpu={values.cpu} memory={values.memory} size="small" />
+        <span className={ROW_TRAILING_GUTTER_CLS} aria-hidden />
+      </div>
+    </div>
+  )
+}
+
+function AppSection({
+  app,
+  isCollapsed,
+  onToggle
+}: {
+  app: AppMemory
+  isCollapsed: boolean
+  onToggle: () => void
+}): React.JSX.Element {
+  return (
+    <div className="border-t border-border/50">
+      <div className="flex items-center">
+        <button
+          type="button"
+          onClick={onToggle}
+          className="pl-2 py-2 pr-0.5 transition-colors hover:bg-muted/50"
+          aria-label={isCollapsed ? 'Expand Orca' : 'Collapse Orca'}
+          aria-expanded={!isCollapsed}
+        >
+          {isCollapsed ? (
+            <ChevronRight className="h-3 w-3 text-muted-foreground" />
+          ) : (
+            <ChevronDown className="h-3 w-3 text-muted-foreground" />
+          )}
+        </button>
+        <div className="flex-1 min-w-0 py-2 pr-3 flex items-center justify-between">
+          <span className="text-[11px] font-semibold uppercase tracking-wide truncate text-muted-foreground">
+            Orca
+          </span>
+          <div className="flex items-center gap-2 shrink-0">
+            <Sparkline samples={app.history} />
+            <MetricPair cpu={app.cpu} memory={app.memory} />
+            <span className={ROW_TRAILING_GUTTER_CLS} aria-hidden />
+          </div>
+        </div>
+      </div>
+      {!isCollapsed && (
+        <div className="border-t border-border/30">
+          <AppSubRow label="Main" values={app.main} />
+          <AppSubRow label="Renderer" values={app.renderer} />
+          {(app.other.cpu > 0 || app.other.memory > 0) && (
+            <AppSubRow label="Other" values={app.other} />
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ─── Sorting ────────────────────────────────────────────────────────
+
+function compareMetricDesc(a: Metric, b: Metric): number {
+  // Why: null metrics (remote rows) sort last regardless of direction so
+  // they don't pollute the "biggest CPU/memory consumers" view.
+  if (a === null && b === null) {
+    return 0
+  }
+  if (a === null) {
+    return 1
+  }
+  if (b === null) {
+    return -1
+  }
+  return b - a
+}
+
+function sortWorktrees(list: UnifiedWorktreeRow[], sort: SortOption): UnifiedWorktreeRow[] {
+  const copy = [...list]
+  if (sort === 'memory') {
+    copy.sort((a, b) => compareMetricDesc(a.memory, b.memory))
+  } else if (sort === 'cpu') {
+    copy.sort((a, b) => compareMetricDesc(a.cpu, b.cpu))
+  } else {
+    copy.sort((a, b) => a.worktreeName.localeCompare(b.worktreeName))
+  }
+  return copy
+}
+
+function sortRepoGroups(groups: UnifiedRepoGroup[], sort: SortOption): UnifiedRepoGroup[] {
+  const copy = [...groups]
+  if (sort === 'memory') {
+    copy.sort((a, b) => compareMetricDesc(a.memory, b.memory))
+  } else if (sort === 'cpu') {
+    copy.sort((a, b) => compareMetricDesc(a.cpu, b.cpu))
+  } else {
+    copy.sort((a, b) => a.repoName.localeCompare(b.repoName))
+  }
+  return copy
+}
+
+// ─── Session row ────────────────────────────────────────────────────
+
+function SessionRow({
+  session,
+  worktreeId,
+  onNavigate,
+  onKill
+}: {
+  session: UnifiedSessionRow
+  worktreeId: string
+  onNavigate: (tabId: string, paneKey: string | null) => void
+  onKill: (session: UnifiedSessionRow) => void
+}): React.JSX.Element {
+  const clickable = session.tabId !== null && session.bound
+  const handleClick = (): void => {
+    if (clickable && session.tabId) {
+      onNavigate(session.tabId, session.paneKey)
+    }
+  }
+
+  return (
+    <div
+      className={cn(
+        'group/sessrow flex items-center gap-2 pl-10 pr-3 py-1.5',
+        clickable && 'cursor-pointer hover:bg-accent/40'
+      )}
+      onClick={clickable ? handleClick : undefined}
+      role={clickable ? 'button' : undefined}
+      tabIndex={clickable ? 0 : -1}
+      onKeyDown={
+        clickable
+          ? (e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                handleClick()
+              }
+            }
+          : undefined
+      }
+      data-worktree-id={worktreeId}
+    >
+      <span
+        className={cn(
+          'size-1.5 shrink-0 rounded-full',
+          session.bound ? 'bg-emerald-500' : 'bg-muted-foreground/40'
+        )}
+      />
+      <span className="text-[11px] text-muted-foreground truncate min-w-0 flex-1">
+        {session.label}
+      </span>
+      <MetricPair cpu={session.cpu} memory={session.memory} size="small" />
+      {/* Why: kill X lives inside the shared trailing gutter so CPU/Memory
+          columns stay aligned with the column header (whose gutter is empty).
+          Bound sessions hide the X until the row is hovered/focused (calm
+          list); orphan sessions show it always so the "this is reclaimable"
+          affordance survives. Mirrors Settings > Manage Sessions. */}
+      <span className={ROW_TRAILING_GUTTER_CLS}>
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation()
+            onKill(session)
+          }}
+          className={cn(
+            'rounded p-0.5 text-muted-foreground transition-opacity hover:bg-destructive/10 hover:text-destructive',
+            session.bound &&
+              'opacity-0 group-hover/sessrow:opacity-100 group-focus-within/sessrow:opacity-100 focus-visible:opacity-100'
+          )}
+          aria-label={`Kill session ${session.sessionId}`}
+        >
+          <X className="size-3" />
+        </button>
+      </span>
+    </div>
+  )
+}
+
+// ─── Worktree row ───────────────────────────────────────────────────
+
+function WorktreeRow({
+  worktree,
+  storeRecord,
+  isCollapsed,
+  onToggle,
+  onNavigate,
+  onSleep,
+  onDelete,
+  onKillSession,
+  navigateToTab
+}: {
+  worktree: UnifiedWorktreeRow
+  storeRecord: Worktree | null
+  isCollapsed: boolean
+  onToggle: () => void
+  onNavigate: () => void
+  onSleep: () => void
+  onDelete: () => void
+  onKillSession: (session: UnifiedSessionRow) => void
+  navigateToTab: (tabId: string, paneKey: string | null) => void
+}): React.JSX.Element {
+  const hasSessions = worktree.sessions.length > 0
+  // Why: synthetic buckets (orphan/unattributed) have no sidebar target to
+  // reveal. Real and SSH-resolved worktrees both qualify for navigation —
+  // navigateToWorktree handles the no-store-record case internally by
+  // bailing out of activateAndRevealWorktree if the worktree isn't known.
+  const isSynthetic =
+    worktree.worktreeId === ORPHAN_WORKTREE_ID || worktree.repoId === UNATTRIBUTED_REPO_ID
+  const isNavigable = !isSynthetic
+  // Why: Sleep / Delete affordances act on a sidebar worktree record; without
+  // one (synthesized SSH rows whose worktreeId isn't in worktreeById, or
+  // synthetic buckets) we hide them but keep the row clickable for navigation.
+  const showWorktreeActions = !isSynthetic && storeRecord !== null
+  const isMainWorktree = storeRecord?.isMainWorktree ?? false
+  const rowLabel = storeRecord?.displayName?.trim() || worktree.worktreeName
+
+  return (
+    <div className="border-b border-border/20 last:border-b-0">
+      <div className="group/wtrow flex items-center ml-2 transition-colors hover:bg-muted/60">
+        {hasSessions ? (
+          <button
+            type="button"
+            onClick={onToggle}
+            className="pl-2 py-2 pr-0.5 shrink-0"
+            aria-label={isCollapsed ? 'Expand workspace' : 'Collapse workspace'}
+          >
+            {isCollapsed ? (
+              <ChevronRight className="h-3 w-3 text-muted-foreground" />
+            ) : (
+              <ChevronDown className="h-3 w-3 text-muted-foreground" />
+            )}
+          </button>
+        ) : (
+          <span
+            className="pl-2 py-2 pr-0.5 shrink-0 w-[calc(0.5rem+0.75rem+0.125rem)]"
+            aria-hidden
+          />
+        )}
+        <button
+          type="button"
+          onClick={onNavigate}
+          aria-label={`Open workspace ${rowLabel}`}
+          className="flex-1 min-w-0 py-2 pr-2 pl-1 text-left flex items-center gap-1.5"
+          disabled={!isNavigable}
+        >
+          <span className="text-xs font-medium truncate">{rowLabel}</span>
+          {!worktree.hasLocalSamples && (
+            <span className="shrink-0 text-[9px] uppercase tracking-wide text-muted-foreground/70">
+              · remote
+            </span>
+          )}
+        </button>
+        <div className="flex items-center gap-2 shrink-0 pr-3">
+          <div className="relative">
+            <span
+              className={cn(
+                'block transition-opacity',
+                showWorktreeActions &&
+                  'group-hover/wtrow:opacity-0 group-hover/wtrow:pointer-events-none group-focus-within/wtrow:opacity-0 group-focus-within/wtrow:pointer-events-none'
+              )}
+              aria-hidden={showWorktreeActions ? undefined : true}
+            >
+              <Sparkline samples={worktree.history} />
+            </span>
+            {showWorktreeActions && (
+              <div className="absolute inset-0 flex items-center justify-end gap-0.5 opacity-0 pointer-events-none transition-opacity group-hover/wtrow:opacity-100 group-hover/wtrow:pointer-events-auto group-focus-within/wtrow:opacity-100 group-focus-within/wtrow:pointer-events-auto">
+                <Tooltip delayDuration={300}>
+                  <TooltipTrigger asChild>
+                    <button
+                      type="button"
+                      onClick={onSleep}
+                      aria-label={`Sleep workspace ${rowLabel}`}
+                      className="p-0.5 rounded text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+                    >
+                      <Moon className="size-3" />
+                    </button>
+                  </TooltipTrigger>
+                  <TooltipContent
+                    side="top"
+                    sideOffset={4}
+                    className="z-[70] max-w-[200px] text-pretty"
+                  >
+                    Sleep — close all panels in this workspace to free memory.
+                  </TooltipContent>
+                </Tooltip>
+                <Tooltip delayDuration={300}>
+                  <TooltipTrigger asChild>
+                    <button
+                      type="button"
+                      onClick={onDelete}
+                      disabled={isMainWorktree}
+                      aria-label={`Delete workspace ${rowLabel}`}
+                      className={cn(
+                        'p-0.5 rounded text-muted-foreground transition-colors',
+                        isMainWorktree
+                          ? 'opacity-40 cursor-not-allowed'
+                          : 'hover:bg-destructive/10 hover:text-destructive'
+                      )}
+                    >
+                      <Trash2 className="size-3" />
+                    </button>
+                  </TooltipTrigger>
+                  <TooltipContent
+                    side="top"
+                    sideOffset={4}
+                    className="z-[70] max-w-[200px] text-pretty"
+                  >
+                    {isMainWorktree ? 'The main workspace cannot be deleted.' : 'Delete workspace.'}
+                  </TooltipContent>
+                </Tooltip>
+              </div>
+            )}
+          </div>
+          <MetricPair cpu={worktree.cpu} memory={worktree.memory} />
+          <span className={ROW_TRAILING_GUTTER_CLS} aria-hidden />
+        </div>
+      </div>
+
+      {!isCollapsed &&
+        worktree.sessions.map((session) => (
+          <SessionRow
+            key={session.sessionId}
+            session={session}
+            worktreeId={worktree.worktreeId}
+            onNavigate={navigateToTab}
+            onKill={onKillSession}
+          />
+        ))}
+    </div>
+  )
+}
+
+// ─── Repo + worktree tree ───────────────────────────────────────────
+
+function ResourceTree({
+  repos,
+  sortOption,
+  collapsedRepos,
+  toggleRepo,
+  collapsedWorktrees,
+  toggleWorktree,
+  navigateToWorktree,
+  navigateToTab,
+  onSleep,
+  onDelete,
+  onKillSession
+}: {
+  repos: UnifiedRepoGroup[]
+  sortOption: SortOption
+  collapsedRepos: Set<string>
+  toggleRepo: (repoId: string) => void
+  collapsedWorktrees: Set<string>
+  toggleWorktree: (worktreeId: string) => void
+  navigateToWorktree: (worktreeId: string) => void
+  navigateToTab: (tabId: string, paneKey: string | null) => void
+  onSleep: (worktreeId: string) => void
+  onDelete: (worktreeId: string) => void
+  onKillSession: (session: UnifiedSessionRow) => void
+}): React.JSX.Element {
+  const worktreeById = useWorktreeMap()
+
+  const sortedRepos = useMemo(() => {
+    const grouped = sortRepoGroups(repos, sortOption)
+    return grouped.map((repo) => ({
+      ...repo,
+      worktrees: sortWorktrees(repo.worktrees, sortOption)
+    }))
+  }, [repos, sortOption])
+
+  const renderWorktree = (wt: UnifiedWorktreeRow): React.JSX.Element => {
+    const storeRecord = worktreeById.get(wt.worktreeId) ?? null
+    return (
+      <WorktreeRow
+        key={wt.worktreeId}
+        worktree={wt}
+        storeRecord={storeRecord}
+        isCollapsed={collapsedWorktrees.has(wt.worktreeId)}
+        onToggle={() => toggleWorktree(wt.worktreeId)}
+        onNavigate={() => navigateToWorktree(wt.worktreeId)}
+        onSleep={() => onSleep(wt.worktreeId)}
+        onDelete={() => onDelete(wt.worktreeId)}
+        onKillSession={onKillSession}
+        navigateToTab={navigateToTab}
+      />
+    )
+  }
+
+  if (sortedRepos.length === 1) {
+    return <>{sortedRepos[0].worktrees.map(renderWorktree)}</>
+  }
+
+  return (
+    <>
+      {sortedRepos.map((group) => {
+        const repoCollapsed = collapsedRepos.has(group.repoId)
+        return (
+          <div key={group.repoId} className="border-b border-border/50 last:border-b-0">
+            <div className="flex items-center">
+              <button
+                type="button"
+                onClick={() => toggleRepo(group.repoId)}
+                className="pl-2 py-2 pr-0.5 transition-colors hover:bg-muted/50"
+                aria-label={repoCollapsed ? 'Expand repo' : 'Collapse repo'}
+              >
+                {repoCollapsed ? (
+                  <ChevronRight className="h-3 w-3 text-muted-foreground" />
+                ) : (
+                  <ChevronDown className="h-3 w-3 text-muted-foreground" />
+                )}
+              </button>
+              <div className="flex-1 min-w-0 py-2 pr-3 flex items-center justify-between gap-2">
+                <span className="flex items-center gap-1.5 min-w-0">
+                  <span className="text-[11px] font-semibold uppercase tracking-wide truncate text-muted-foreground">
+                    {group.repoName}
+                  </span>
+                  {group.hasRemoteChildren && (
+                    <span className="shrink-0 text-[9px] uppercase tracking-wide text-muted-foreground/70">
+                      · remote
+                    </span>
+                  )}
+                </span>
+                <div className="flex items-center gap-2 shrink-0">
+                  <MetricPair cpu={group.cpu} memory={group.memory} />
+                  <span className={ROW_TRAILING_GUTTER_CLS} aria-hidden />
+                </div>
+              </div>
+            </div>
+
+            {!repoCollapsed && (
+              <div className="border-t border-border/30">{group.worktrees.map(renderWorktree)}</div>
+            )}
+          </div>
+        )
+      })}
+    </>
+  )
+}
+
+// ─── Top-level segment ──────────────────────────────────────────────
+
+export function ResourceUsageStatusSegment({
+  iconOnly
+}: {
+  compact?: boolean
+  iconOnly: boolean
+}): React.JSX.Element {
+  const snapshot = useAppStore((s) => s.memorySnapshot)
+  const memorySnapshotError = useAppStore((s) => s.memorySnapshotError)
+  const fetchSnapshot = useAppStore((s) => s.fetchMemorySnapshot)
+  const workspaceSessionReady = useAppStore((s) => s.workspaceSessionReady)
+  const ptyIdsByTabId = useAppStore((s) => s.ptyIdsByTabId)
+  const tabsByWorktree = useAppStore((s) => s.tabsByWorktree)
+  const runtimePaneTitlesByTabId = useAppStore((s) => s.runtimePaneTitlesByTabId)
+  const setActiveView = useAppStore((s) => s.setActiveView)
+  const repos = useAppStore((s) => s.repos)
+
+  const [open, setOpen] = useState(false)
+  const [sortOption, setSortOption] = useState<SortOption>('memory')
+  const [collapsedRepos, setCollapsedRepos] = useState<Set<string>>(new Set())
+  const [collapsedWorktrees, setCollapsedWorktrees] = useState<Set<string>>(new Set())
+  const [appCollapsed, setAppCollapsed] = useState(true)
+  const [sessions, setSessions] = useState<DaemonSession[]>([])
+  const [sessionsError, setSessionsError] = useState(false)
+  const [killConfirm, setKillConfirm] = useState<UnifiedSessionRow | null>(null)
+  const [killing, setKilling] = useState(false)
+
+  // 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
+  // somewhere stable for keyboard users.
+  const popoverBodyRef = useRef<HTMLDivElement | null>(null)
+
+  const refreshSessions = useCallback(async () => {
+    try {
+      const result = await window.api.pty.listSessions()
+      setSessions(result)
+      setSessionsError(false)
+    } catch {
+      setSessionsError(true)
+    }
+  }, [])
+
+  const daemonActions = useDaemonActions({
+    onRestartSettled: () => {
+      setSessionsError(false)
+      void fetchSnapshot()
+      void refreshSessions()
+    },
+    onKillAllSettled: () => {
+      void refreshSessions()
+    }
+  })
+
+  // Poll memory + sessions when popover is open. Sessions also poll in the
+  // background at a slower rate so the badge count stays reasonably fresh
+  // without keeping the Memory IPC hot.
+  useEffect(() => {
+    if (!open) {
+      return
+    }
+    void fetchSnapshot()
+    void refreshSessions()
+    const memTimer = window.setInterval(() => {
+      void fetchSnapshot()
+    }, POLL_MS)
+    const sessTimer = window.setInterval(() => {
+      void refreshSessions()
+    }, SESSIONS_POLL_MS)
+    return () => {
+      window.clearInterval(memTimer)
+      window.clearInterval(sessTimer)
+    }
+  }, [open, fetchSnapshot, refreshSessions])
+
+  useEffect(() => {
+    const interval = setInterval(() => void refreshSessions(), SESSIONS_POLL_MS)
+    void refreshSessions()
+    return () => clearInterval(interval)
+  }, [refreshSessions])
+
+  const repoDisplayNameById = useMemo(() => {
+    const map = new Map<string, string>()
+    for (const repo of repos) {
+      const display = repo.displayName?.trim()
+      if (display) {
+        map.set(repo.id, display)
+      }
+    }
+    return map
+  }, [repos])
+
+  // 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
+  // every keystroke in any open terminal pane) was making the whole app
+  // feel laggy because the segment is always mounted in the status bar.
+  const unifiedRepos = useMemo(
+    () =>
+      open
+        ? mergeSnapshotAndSessions(snapshot, sessions, {
+            tabsByWorktree,
+            ptyIdsByTabId,
+            runtimePaneTitlesByTabId,
+            workspaceSessionReady,
+            repoDisplayNameById
+          })
+        : [],
+    [
+      open,
+      snapshot,
+      sessions,
+      tabsByWorktree,
+      ptyIdsByTabId,
+      runtimePaneTitlesByTabId,
+      workspaceSessionReady,
+      repoDisplayNameById
+    ]
+  )
+
+  // Why: orphanCount drives the trigger badge (always visible in the status
+  // bar, popover open or not) so it must compute outside the open-gate.
+  // 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) {
+      return 0
+    }
+    const bound = new Set<string>()
+    for (const ids of Object.values(ptyIdsByTabId)) {
+      for (const id of ids) {
+        if (id) {
+          bound.add(id)
+        }
+      }
+    }
+    let n = 0
+    for (const s of sessions) {
+      if (!bound.has(s.id)) {
+        n++
+      }
+    }
+    return n
+  }, [sessions, ptyIdsByTabId, workspaceSessionReady])
+
+  const { totalMemory, totalCpu, hostShare, memBadgeLabel } = useMemo(() => {
+    const memory = snapshot?.totalMemory ?? 0
+    const cpu = snapshot?.totalCpu ?? 0
+    const hostTotal = snapshot?.host.totalMemory ?? 0
+    return {
+      totalMemory: memory,
+      totalCpu: cpu,
+      hostShare: hostTotal > 0 ? (memory / hostTotal) * 100 : 0,
+      memBadgeLabel: snapshot ? formatMemory(memory) : '—'
+    }
+  }, [snapshot])
+
+  const daemonUnreachable = sessionsError && memorySnapshotError !== 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 toggleRepo = useCallback((repoId: string): void => {
+    setCollapsedRepos((prev) => {
+      const next = new Set(prev)
+      if (next.has(repoId)) {
+        next.delete(repoId)
+      } else {
+        next.add(repoId)
+      }
+      return next
+    })
+  }, [])
+
+  const toggleWorktree = useCallback((worktreeId: string): void => {
+    setCollapsedWorktrees((prev) => {
+      const next = new Set(prev)
+      if (next.has(worktreeId)) {
+        next.delete(worktreeId)
+      } else {
+        next.add(worktreeId)
+      }
+      return next
+    })
+  }, [])
+
+  // Why: navigation handlers leave the popover open so users can chain
+  // multiple jumps (e.g. browse worktrees, hop between terminals) without
+  // having to re-open the popover each time. The popover still closes via
+  // its own outside-click / Escape handlers.
+  const navigateToWorktree = useCallback((worktreeId: string): void => {
+    if (worktreeId === ORPHAN_WORKTREE_ID || worktreeId.startsWith(`${UNATTRIBUTED_REPO_ID}::`)) {
+      return
+    }
+    activateAndRevealWorktree(worktreeId)
+  }, [])
+
+  const navigateToTab = useCallback(
+    (tabId: string, paneKey: string | null) => {
+      // Resolve the tab → worktree from the store so we can also reveal the
+      // worktree in the sidebar before flipping the active tab.
+      for (const [worktreeId, tabs] of Object.entries(tabsByWorktree)) {
+        if (tabs.some((t) => t.id === tabId)) {
+          activateAndRevealWorktree(worktreeId)
+          break
+        }
+      }
+      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)
+    },
+    [tabsByWorktree, setActiveView]
+  )
+
+  const deleteWorktree = useCallback((worktreeId: string): void => {
+    setOpen(false)
+    runWorktreeDelete(worktreeId)
+  }, [])
+
+  const handleSleep = useCallback((id: string): void => {
+    void runSleepWorktree(id)
+  }, [])
+
+  const handleKillSession = useCallback(
+    (session: UnifiedSessionRow): void => {
+      // Why: orphan sessions have no tab in this Orca instance, so there's
+      // no "unsaved work in that pane" the user could lose by killing them.
+      // Skip the confirm dialog for orphans and fire the kill straight away
+      // (with optimistic removal) — same UX as a one-off kill from the
+      // bulk "Kill orphan terminals" button. Bound sessions still confirm.
+      if (!session.bound) {
+        setSessions((prev) => prev.filter((s) => s.id !== session.sessionId))
+        void window.api.pty.kill(session.sessionId).catch(() => {
+          /* already dead */
+        })
+        void refreshSessions()
+        return
+      }
+      setKillConfirm(session)
+    },
+    [refreshSessions]
+  )
+
+  const handleKillOrphans = useCallback(async () => {
+    if (!workspaceSessionReady) {
+      return
+    }
+    const bound = new Set<string>()
+    for (const ids of Object.values(ptyIdsByTabId)) {
+      for (const id of ids) {
+        if (id) {
+          bound.add(id)
+        }
+      }
+    }
+    const orphans = sessions.filter((s) => !bound.has(s.id))
+    if (orphans.length === 0) {
+      return
+    }
+    // Why: optimistic removal so the rows disappear immediately rather than
+    // lingering up to SESSIONS_POLL_MS while the daemon-side list reconciles.
+    const orphanIds = new Set(orphans.map((s) => s.id))
+    setSessions((prev) => prev.filter((s) => !orphanIds.has(s.id)))
+    await Promise.allSettled(orphans.map((s) => window.api.pty.kill(s.id)))
+    void refreshSessions()
+  }, [sessions, ptyIdsByTabId, workspaceSessionReady, refreshSessions])
+
+  const runKillConfirmed = useCallback(async () => {
+    if (!killConfirm) {
+      return
+    }
+    const target = killConfirm
+    setKilling(true)
+    // Why: optimistic removal — the kill X was on the row that's about to be
+    // unmounted, so updating local state immediately avoids a flash where the
+    // dialog closes but the killed row stays for up to 10s.
+    setSessions((prev) => prev.filter((s) => s.id !== target.sessionId))
+    try {
+      await window.api.pty.kill(target.sessionId)
+    } catch {
+      /* already dead — fall through */
+    } finally {
+      setKilling(false)
+      setKillConfirm(null)
+      // Why: after the killed row unmounts, focus would otherwise drop to
+      // <body>. Park focus on the popover body so keyboard users land back
+      // in the list rather than outside the popover.
+      requestAnimationFrame(() => {
+        popoverBodyRef.current?.focus()
+      })
+      void refreshSessions()
+    }
+  }, [killConfirm, refreshSessions])
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <Tooltip delayDuration={150}>
+        <TooltipTrigger asChild>
+          <PopoverTrigger asChild>
+            <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"
+            >
+              <MemoryStick className="size-3 text-muted-foreground" />
+              {!iconOnly && (
+                <>
+                  <span className="text-[11px] font-medium tabular-nums text-muted-foreground">
+                    {memBadgeLabel}
+                  </span>
+                  <span className="text-muted-foreground/50">·</span>
+                  <Terminal className="size-3 text-muted-foreground" />
+                  <span className="text-[11px] tabular-nums text-muted-foreground">
+                    {sessions.length}
+                    {orphanCount > 0 && (
+                      <span className="text-yellow-500 ml-0.5">({orphanCount})</span>
+                    )}
+                  </span>
+                </>
+              )}
+              {iconOnly && sessions.length > 0 && (
+                <span className="text-[11px] tabular-nums text-muted-foreground">
+                  {sessions.length}
+                </span>
+              )}
+              {daemonUnreachable && (
+                <AlertTriangle className="size-3 text-yellow-500" aria-label="Daemon unreachable" />
+              )}
+            </button>
+          </PopoverTrigger>
+        </TooltipTrigger>
+        <TooltipContent side="top" sideOffset={6}>
+          Resource usage — {memBadgeLabel} · {sessions.length} session
+          {sessions.length === 1 ? '' : 's'}
+        </TooltipContent>
+      </Tooltip>
+
+      <PopoverContent
+        side="top"
+        align="end"
+        sideOffset={8}
+        className="w-[26rem] 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
+        // interpret that as a focus-outside event and close the popover.
+        // Suppress focus-driven closes; the popover still closes on
+        // 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>
+
+          <div className="flex items-center gap-0.5">
+            <Tooltip delayDuration={200}>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={() => daemonActions.setPending('restart')}
+                  disabled={daemonActions.isBusy}
+                  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"
+                >
+                  <RotateCw className="size-3" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={6}>
+                Restart daemon
+              </TooltipContent>
+            </Tooltip>
+            <Tooltip delayDuration={200}>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={() => daemonActions.setPending('killAll')}
+                  disabled={daemonActions.isBusy}
+                  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"
+                >
+                  <Trash2 className="size-3" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={6}>
+                Kill all sessions
+              </TooltipContent>
+            </Tooltip>
+          </div>
+        </div>
+
+        {daemonUnreachable && (
+          <div className="flex items-start gap-2 border-b border-border bg-yellow-500/10 px-3 py-2 text-[11px] text-foreground">
+            <AlertTriangle className="mt-0.5 size-3 shrink-0 text-yellow-500" />
+            <div className="flex-1">
+              <div className="font-medium">Daemon is not responding</div>
+              <div className="text-muted-foreground">
+                Resource snapshots and terminal sessions are unavailable.
+              </div>
+            </div>
+            <Button
+              variant="outline"
+              size="sm"
+              className="shrink-0"
+              onClick={() => daemonActions.setPending('restart')}
+              disabled={daemonActions.isBusy}
+            >
+              <RotateCw className="mr-1 size-3" />
+              Restart
+            </Button>
+          </div>
+        )}
+
+        {!daemonUnreachable && sessionsOnlyError && (
+          <div
+            className="flex items-center gap-2 border-b border-border bg-muted/40 px-3 py-1.5 text-[11px] text-muted-foreground"
+            role="status"
+          >
+            <AlertTriangle className="size-3 shrink-0 text-yellow-500" />
+            <span>Terminal sessions unavailable. The list may be stale.</span>
+          </div>
+        )}
+
+        {snapshot && (
+          <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}>
+                <TooltipTrigger asChild>
+                  <span
+                    tabIndex={0}
+                    className="font-medium text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:rounded"
+                  >
+                    {formatCpu(totalCpu)}
+                  </span>
+                </TooltipTrigger>
+                <TooltipContent side="top" sideOffset={6} className="z-[70] max-w-xs">
+                  Combined CPU load. Values above 100% mean more than one core is working at once.
+                </TooltipContent>
+              </Tooltip>
+              <span className="text-muted-foreground/50">·</span>
+              <Tooltip delayDuration={200}>
+                <TooltipTrigger asChild>
+                  <span
+                    tabIndex={0}
+                    className="font-medium text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:rounded"
+                  >
+                    {formatMemory(totalMemory)}
+                  </span>
+                </TooltipTrigger>
+                <TooltipContent side="top" sideOffset={6} className="z-[70] max-w-xs">
+                  Resident memory held by Orca plus the processes under each worktree&apos;s
+                  terminals.
+                </TooltipContent>
+              </Tooltip>
+              <span className="text-muted-foreground/50">·</span>
+              <Tooltip delayDuration={200}>
+                <TooltipTrigger asChild>
+                  <span
+                    tabIndex={0}
+                    className="text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:rounded"
+                  >
+                    {formatPercent(hostShare)} of system RAM
+                  </span>
+                </TooltipTrigger>
+                <TooltipContent side="top" sideOffset={6} className="z-[70] max-w-xs">
+                  How much of this machine&apos;s physical RAM the Orca-tracked processes are
+                  sitting on.
+                </TooltipContent>
+              </Tooltip>
+            </div>
+            {orphanCount > 0 && (
+              <span className="shrink-0 text-yellow-500" aria-live="polite">
+                {orphanCount} orphan{orphanCount === 1 ? '' : 's'}
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Why: pin body to a constant 420px so the popover surface doesn't
+            jump as worktrees expand/collapse or as sessions come and go. The
+            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) && (
+            <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"
+                onClick={() => setSortOption('name')}
+                className={cn(
+                  'hover:text-foreground transition-colors',
+                  sortOption === 'name'
+                    ? 'font-semibold text-foreground'
+                    : 'text-muted-foreground/80'
+                )}
+                aria-pressed={sortOption === 'name'}
+              >
+                Name
+              </button>
+              <div className="flex items-center gap-2 shrink-0">
+                <div className={cn(METRIC_COLUMNS_CLS, 'text-[10px]')}>
+                  <button
+                    type="button"
+                    onClick={() => setSortOption('cpu')}
+                    className={cn(
+                      CPU_COLUMN_CLS,
+                      'hover:text-foreground transition-colors',
+                      sortOption === 'cpu'
+                        ? 'font-semibold text-foreground'
+                        : 'text-muted-foreground/80'
+                    )}
+                    aria-pressed={sortOption === 'cpu'}
+                  >
+                    CPU
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => setSortOption('memory')}
+                    className={cn(
+                      MEM_COLUMN_CLS,
+                      'hover:text-foreground transition-colors',
+                      sortOption === 'memory'
+                        ? 'font-semibold text-foreground'
+                        : 'text-muted-foreground/80'
+                    )}
+                    aria-pressed={sortOption === 'memory'}
+                  >
+                    Memory
+                  </button>
+                </div>
+                {/* Why: empty trailing gutter so the CPU/Memory header
+                    cells line up with the row cells; rows reserve the same
+                    width for the kill-X button. */}
+                <span className={ROW_TRAILING_GUTTER_CLS} aria-hidden />
+              </div>
+            </div>
+          )}
+
+          <div className="flex-1 overflow-y-auto scrollbar-sleek">
+            {unifiedRepos.length > 0 && (
+              <ResourceTree
+                repos={unifiedRepos}
+                sortOption={sortOption}
+                collapsedRepos={collapsedRepos}
+                toggleRepo={toggleRepo}
+                collapsedWorktrees={collapsedWorktrees}
+                toggleWorktree={toggleWorktree}
+                navigateToWorktree={navigateToWorktree}
+                navigateToTab={navigateToTab}
+                onSleep={handleSleep}
+                onDelete={deleteWorktree}
+                onKillSession={handleKillSession}
+              />
+            )}
+
+            {unifiedRepos.length === 0 && snapshot && (
+              <div className="px-3 py-4 text-center text-xs text-muted-foreground">
+                Nothing running right now
+              </div>
+            )}
+
+            {snapshot && (
+              <AppSection
+                app={snapshot.app}
+                isCollapsed={appCollapsed}
+                onToggle={() => setAppCollapsed((v) => !v)}
+              />
+            )}
+
+            {!snapshot && !daemonUnreachable && (
+              <div className="px-3 py-4 text-center text-xs text-muted-foreground">Loading…</div>
+            )}
+          </div>
+        </div>
+
+        {orphanCount > 0 && (
+          <div className="border-t border-border/50 px-3 py-2 shrink-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"
+            >
+              Kill {orphanCount} orphan terminal{orphanCount === 1 ? '' : 's'}
+            </button>
+          </div>
+        )}
+
+        <Dialog
+          open={killConfirm !== null}
+          onOpenChange={(next) => {
+            if (next) {
+              return
+            }
+            if (killing) {
+              return
+            }
+            setKillConfirm(null)
+          }}
+        >
+          <DialogContent
+            className="max-w-md"
+            showCloseButton={!killing}
+            onPointerDownOutside={(e) => {
+              if (killing) {
+                e.preventDefault()
+              }
+            }}
+            onEscapeKeyDown={(e) => {
+              if (killing) {
+                e.preventDefault()
+              }
+            }}
+          >
+            <DialogHeader>
+              <DialogTitle className="text-sm">
+                Kill{' '}
+                <span className="font-medium text-foreground">
+                  {killConfirm?.label ?? 'this session'}
+                </span>
+                ?
+              </DialogTitle>
+              <DialogDescription className="text-xs">
+                Force-quits this terminal. Any unsaved work in the pane is lost. This can&apos;t be
+                undone.
+              </DialogDescription>
+            </DialogHeader>
+            <DialogFooter>
+              <Button variant="outline" onClick={() => setKillConfirm(null)} disabled={killing}>
+                Cancel
+              </Button>
+              <Button
+                variant="destructive"
+                onClick={() => void runKillConfirmed()}
+                disabled={killing}
+              >
+                {killing ? <LoaderCircle className="size-4 animate-spin" /> : null}
+                {killing ? 'Killing…' : 'Kill session'}
+              </Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </PopoverContent>
+      <DaemonActionDialog api={daemonActions} />
+    </Popover>
+  )
+}
diff --git a/src/renderer/src/components/status-bar/SessionsStatusSegment.tsx b/src/renderer/src/components/status-bar/SessionsStatusSegment.tsx
deleted file mode 100644
index 72739372326..00000000000
--- a/src/renderer/src/components/status-bar/SessionsStatusSegment.tsx
+++ /dev/null
@@ -1,310 +0,0 @@
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
-import { Terminal, Trash2 } from 'lucide-react'
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger
-} from '@/components/ui/dropdown-menu'
-import { useAppStore } from '../../store'
-import { activateAndRevealWorktree } from '@/lib/worktree-activation'
-
-type DaemonSession = { id: string; cwd: string; title: string }
-
-function shortCwd(cwd: string): string {
-  if (!cwd) {
-    return 'unknown'
-  }
-  const separator = cwd.includes('\\') ? '\\' : '/'
-  const parts = cwd.split(/[\\/]+/).filter(Boolean)
-  return parts.length > 2 ? parts.slice(-2).join(separator) : cwd
-}
-
-function sessionLabel(session: DaemonSession, tabTitle?: string): string {
-  if (session.cwd) {
-    return shortCwd(session.cwd)
-  }
-  // Why: daemon session IDs use the format `${worktreeId}@@${shortUuid}`.
-  // When the shell hasn't emitted OSC 7 cwd updates (e.g. Claude Code agents),
-  // fall back to showing the worktreeId portion so the user can identify which
-  // worktree the session belongs to.
-  const sep = session.id.lastIndexOf('@@')
-  if (sep !== -1) {
-    const worktreeId = session.id.slice(0, sep)
-    return shortCwd(worktreeId)
-  }
-  // Why: for sessions with legacy numeric IDs (e.g. from LocalPtyProvider) or
-  // sessions whose shells haven't emitted OSC 7, use the tab title from the
-  // renderer store — it carries the live terminal title shown in the tab bar.
-  // Fall back to the daemon-reported title (typically "shell") so orphan
-  // sessions without a bound tab still display something meaningful.
-  if (tabTitle) {
-    return tabTitle
-  }
-  if (session.title) {
-    return session.title
-  }
-  return 'unknown'
-}
-
-function SessionRow({
-  session,
-  isBound,
-  tabId,
-  tabTitle,
-  onKill,
-  onNavigate
-}: {
-  session: DaemonSession
-  isBound: boolean
-  tabId: string | null
-  tabTitle: string | undefined
-  onKill: (id: string) => void
-  onNavigate: (tabId: string) => void
-}): React.JSX.Element {
-  return (
-    <div
-      className={`flex items-center gap-2 px-2 py-1.5 rounded ${
-        tabId ? 'cursor-pointer hover:bg-accent/60' : ''
-      }`}
-      onClick={tabId ? () => onNavigate(tabId) : undefined}
-    >
-      <span
-        className={`size-1.5 shrink-0 rounded-full ${isBound ? 'bg-emerald-500' : 'bg-muted-foreground/40'}`}
-      />
-      <div className="min-w-0 flex-1">
-        <div className="truncate text-[12px] font-medium font-mono">
-          {sessionLabel(session, tabTitle)}
-        </div>
-      </div>
-      {!isBound && (
-        <button
-          type="button"
-          onClick={(e) => {
-            e.stopPropagation()
-            onKill(session.id)
-          }}
-          className="shrink-0 rounded p-0.5 text-muted-foreground hover:bg-destructive/10 hover:text-destructive"
-          aria-label={`Kill session ${session.id}`}
-        >
-          <Trash2 className="size-3" />
-        </button>
-      )}
-    </div>
-  )
-}
-
-export function SessionsStatusSegment({
-  compact: _compact,
-  iconOnly
-}: {
-  compact: boolean
-  iconOnly: boolean
-}): React.JSX.Element {
-  const [sessions, setSessions] = useState<DaemonSession[]>([])
-  const [open, setOpen] = useState(false)
-  const tabsByWorktree = useAppStore((s) => s.tabsByWorktree)
-  const ptyIdsByTabId = useAppStore((s) => s.ptyIdsByTabId)
-  const runtimePaneTitlesByTabId = useAppStore((s) => s.runtimePaneTitlesByTabId)
-  const workspaceSessionReady = useAppStore((s) => s.workspaceSessionReady)
-  const setActiveTab = useAppStore((s) => s.setActiveTab)
-  const setActiveView = useAppStore((s) => s.setActiveView)
-
-  const boundPtyIds = useMemo(
-    () => new Set(Object.values(ptyIdsByTabId).flat().filter(Boolean)),
-    [ptyIdsByTabId]
-  )
-
-  // Why: ptyIdsByTabId tracks all ptyIds a tab has ever been associated with
-  // (including split panes). Build a reverse map so we can navigate from a
-  // daemon session ID back to the tab that owns it.
-  const ptyIdToTabId = useMemo(() => {
-    const map = new Map<string, string>()
-    for (const [tabId, ptyIds] of Object.entries(ptyIdsByTabId)) {
-      for (const ptyId of ptyIds) {
-        map.set(ptyId, tabId)
-      }
-    }
-    return map
-  }, [ptyIdsByTabId])
-
-  const tabIdToWorktreeId = useMemo(() => {
-    const map = new Map<string, string>()
-    for (const [worktreeId, tabs] of Object.entries(tabsByWorktree)) {
-      for (const tab of tabs) {
-        map.set(tab.id, worktreeId)
-      }
-    }
-    return map
-  }, [tabsByWorktree])
-
-  // Why: the daemon IPC response has sparse metadata (cwd may be null, title is
-  // hardcoded to "shell"), but the renderer store already knows each tab's live
-  // title. Build a ptyId→title map so the popover can show the same name as the
-  // tab bar for bound sessions.
-  const ptyIdToTabTitle = useMemo(() => {
-    // Why: build a tabId→tab lookup once up-front instead of doing
-    // O(totalTabs) .flat().find() per ptyIdsByTabId entry.
-    const tabById = new Map<string, (typeof tabsByWorktree)[string][number]>()
-    for (const tabs of Object.values(tabsByWorktree)) {
-      for (const tab of tabs) {
-        tabById.set(tab.id, tab)
-      }
-    }
-    const map = new Map<string, string>()
-    for (const [tabId, ptyIds] of Object.entries(ptyIdsByTabId)) {
-      const tab = tabById.get(tabId)
-      if (!tab) {
-        continue
-      }
-      // Why: runtimePaneTitlesByTabId holds the most current OSC-reported title
-      // for each mounted pane — it updates on every title change regardless of
-      // which split pane is focused. Prefer the first non-empty runtime pane
-      // title, then the persisted tab.title (which only updates for the focused
-      // pane), then the stable defaultTitle.
-      const runtimeTitles = runtimePaneTitlesByTabId[tabId]
-      const liveTitle = runtimeTitles
-        ? Object.values(runtimeTitles).find((t) => t?.trim())
-        : undefined
-      const title =
-        tab.customTitle?.trim() || liveTitle?.trim() || tab.title || tab.defaultTitle?.trim()
-      if (title) {
-        for (const ptyId of ptyIds) {
-          map.set(ptyId, title)
-        }
-      }
-    }
-    return map
-  }, [ptyIdsByTabId, tabsByWorktree, runtimePaneTitlesByTabId])
-
-  const refresh = useCallback(async () => {
-    try {
-      const result = await window.api.pty.listSessions()
-      setSessions(result)
-    } catch {
-      setSessions([])
-    }
-  }, [])
-
-  useEffect(() => {
-    if (open) {
-      void refresh()
-    }
-  }, [open, refresh])
-
-  useEffect(() => {
-    const interval = setInterval(() => void refresh(), 10_000)
-    void refresh()
-    return () => clearInterval(interval)
-  }, [refresh])
-
-  const orphanCount = workspaceSessionReady
-    ? sessions.filter((s) => !boundPtyIds.has(s.id)).length
-    : 0
-
-  const handleKill = useCallback(
-    async (id: string) => {
-      try {
-        await window.api.pty.kill(id)
-      } catch {
-        /* already dead */
-      }
-      await refresh()
-    },
-    [refresh]
-  )
-
-  const handleKillOrphans = useCallback(async () => {
-    if (!workspaceSessionReady) {
-      return
-    }
-    const orphans = sessions.filter((s) => !boundPtyIds.has(s.id))
-    await Promise.allSettled(orphans.map((s) => window.api.pty.kill(s.id)))
-    await refresh()
-  }, [sessions, boundPtyIds, refresh, workspaceSessionReady])
-
-  const handleNavigate = useCallback(
-    (tabId: string) => {
-      const worktreeId = tabIdToWorktreeId.get(tabId)
-      if (worktreeId) {
-        // Why: opening a session from the status bar is another worktree jump,
-        // so route it through the shared activation path before restoring the
-        // specific tab inside that worktree.
-        activateAndRevealWorktree(worktreeId)
-      }
-      setActiveView('terminal')
-      setActiveTab(tabId)
-    },
-    [tabIdToWorktreeId, setActiveView, setActiveTab]
-  )
-
-  return (
-    <DropdownMenu open={open} onOpenChange={setOpen}>
-      <DropdownMenuTrigger asChild>
-        <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="Terminal sessions"
-        >
-          <Terminal className="size-3 text-muted-foreground" />
-          {!iconOnly && (
-            <span className="text-[11px] tabular-nums">
-              {sessions.length}
-              {orphanCount > 0 && <span className="text-yellow-500 ml-0.5">({orphanCount})</span>}
-            </span>
-          )}
-          {iconOnly && sessions.length > 0 && (
-            <span className="text-[11px] tabular-nums">{sessions.length}</span>
-          )}
-        </button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent side="top" align="end" sideOffset={8} className="w-[260px]">
-        <div className="px-2 pt-1.5 pb-1 text-[10px] font-medium uppercase tracking-[0.08em] text-muted-foreground">
-          Terminal Sessions ({sessions.length})
-        </div>
-        {sessions.length === 0 ? (
-          <div className="px-2 py-3 text-center text-[11px] text-muted-foreground">
-            No active sessions
-          </div>
-        ) : (
-          <div className="max-h-[240px] overflow-y-auto scrollbar-sleek">
-            {[...sessions]
-              .sort((a, b) => {
-                const aBound = workspaceSessionReady && boundPtyIds.has(a.id) ? 0 : 1
-                const bBound = workspaceSessionReady && boundPtyIds.has(b.id) ? 0 : 1
-                return aBound - bBound
-              })
-              .map((s) => {
-                const tabId = ptyIdToTabId.get(s.id) ?? null
-                return (
-                  <SessionRow
-                    key={s.id}
-                    session={s}
-                    isBound={workspaceSessionReady && boundPtyIds.has(s.id)}
-                    tabId={tabId}
-                    tabTitle={ptyIdToTabTitle.get(s.id)}
-                    onKill={handleKill}
-                    onNavigate={handleNavigate}
-                  />
-                )
-              })}
-          </div>
-        )}
-        {orphanCount > 0 && (
-          <>
-            <DropdownMenuSeparator />
-            <div className="px-2 py-2">
-              <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"
-              >
-                Kill {orphanCount} Orphan{orphanCount > 1 ? 's' : ''}
-              </button>
-            </div>
-          </>
-        )}
-      </DropdownMenuContent>
-    </DropdownMenu>
-  )
-}
diff --git a/src/renderer/src/components/status-bar/SidekickStatusSegment.tsx b/src/renderer/src/components/status-bar/SidekickStatusSegment.tsx
index ac66fea4fd4..692533ce486 100644
--- a/src/renderer/src/components/status-bar/SidekickStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/SidekickStatusSegment.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import { Check, Trash2, Upload } from 'lucide-react'
+import { Check, PackageOpen, Trash2, Upload } from 'lucide-react'
 import { toast } from 'sonner'
 import {
   DropdownMenu,
@@ -20,6 +20,7 @@ import {
   findBundledSidekick,
   isBundledSidekickId
 } from '../sidekick/sidekick-models'
+import { SIDEKICK_SIZE_MAX, SIDEKICK_SIZE_MIN } from '../../../../shared/types'
 
 // Why: cluster sidekick-related controls (show/hide, character picker, custom
 // upload + removal, jump-to-settings) behind a single status-bar segment. Only
@@ -34,6 +35,8 @@ function SidekickStatusSegmentInner(): React.JSX.Element {
   const customSidekicks = useAppStore((s) => s.customSidekicks)
   const addCustomSidekick = useAppStore((s) => s.addCustomSidekick)
   const removeCustomSidekick = useAppStore((s) => s.removeCustomSidekick)
+  const sidekickSize = useAppStore((s) => s.sidekickSize)
+  const setSidekickSize = useAppStore((s) => s.setSidekickSize)
   const openSettingsPage = useAppStore((s) => s.openSettingsPage)
   const openSettingsTarget = useAppStore((s) => s.openSettingsTarget)
 
@@ -67,6 +70,27 @@ function SidekickStatusSegmentInner(): React.JSX.Element {
     }
   }
 
+  const handleImportPetBundle = async (): Promise<void> => {
+    if (!window.api?.sidekick?.importPetBundle) {
+      toast.error('Pet bundle import needs a full app restart (not just reload).')
+      return
+    }
+    try {
+      const model = await window.api.sidekick.importPetBundle()
+      if (!model) {
+        return
+      }
+      addCustomSidekick(model)
+      if (!sidekickVisible) {
+        setSidekickVisible(true)
+      }
+      setSidekickId(model.id)
+    } catch (error) {
+      console.error('[sidekick-overlay] pet bundle: error', error)
+      toast.error(error instanceof Error ? error.message : 'Failed to import pet bundle')
+    }
+  }
+
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
@@ -92,6 +116,31 @@ function SidekickStatusSegmentInner(): React.JSX.Element {
         >
           {sidekickVisible ? 'Hide sidekick' : 'Show sidekick'}
         </DropdownMenuItem>
+        {/* Why: in-menu range so users can resize the overlay without leaving
+            the dropdown — pet sprites can import larger than the default 180px
+            box and visually overwhelm the viewport. preventDefault on pointer
+            events stops Radix from closing the menu while the user drags. */}
+        <div
+          className="px-2 py-1.5"
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={(e) => e.stopPropagation()}
+          onKeyDown={(e) => e.stopPropagation()}
+        >
+          <div className="mb-1 flex items-center justify-between text-[11px] text-muted-foreground">
+            <span>Size</span>
+            <span className="tabular-nums">{sidekickSize}px</span>
+          </div>
+          <input
+            type="range"
+            min={SIDEKICK_SIZE_MIN}
+            max={SIDEKICK_SIZE_MAX}
+            step={10}
+            value={sidekickSize}
+            onChange={(e) => setSidekickSize(Number(e.target.value))}
+            className="w-full"
+            aria-label="Sidekick size"
+          />
+        </div>
         <DropdownMenuSub>
           <DropdownMenuSubTrigger>Choose sidekick</DropdownMenuSubTrigger>
           {/* Why: portal so the submenu escapes the parent Content's overflow
@@ -165,6 +214,14 @@ function SidekickStatusSegmentInner(): React.JSX.Element {
                 <Upload className="size-3.5" aria-hidden />
                 Upload your own…
               </DropdownMenuItem>
+              <DropdownMenuItem
+                onSelect={() => {
+                  void handleImportPetBundle()
+                }}
+              >
+                <PackageOpen className="size-3.5" aria-hidden />
+                Import .codex-pet bundle…
+              </DropdownMenuItem>
             </DropdownMenuSubContent>
           </DropdownMenuPortal>
         </DropdownMenuSub>
diff --git a/src/renderer/src/components/status-bar/StatusBar.tsx b/src/renderer/src/components/status-bar/StatusBar.tsx
index 55d8c8d56c3..609473a86e8 100644
--- a/src/renderer/src/components/status-bar/StatusBar.tsx
+++ b/src/renderer/src/components/status-bar/StatusBar.tsx
@@ -1,15 +1,7 @@
 /* eslint-disable max-lines -- Why: the status bar keeps provider rendering,
 interaction menus, and compact-layout behavior together so the hover/click
 states stay consistent across Claude and Codex. */
-import {
-  AlertTriangle,
-  ChevronDown,
-  ChevronRight,
-  MemoryStick as MemoryStickIcon,
-  RefreshCw,
-  Server,
-  Terminal
-} from 'lucide-react'
+import { AlertTriangle, Activity, ChevronDown, ChevronRight, RefreshCw, Server } from 'lucide-react'
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import {
@@ -32,9 +24,8 @@ import { ClaudeIcon, GeminiIcon, OpenAIIcon, OpenCodeGoIcon } from './icons'
 import { formatWindowLabel } from '@/lib/window-label-formatter'
 import { markLiveCodexSessionsForRestart } from '@/lib/codex-session-restart'
 import { SshStatusSegment } from './SshStatusSegment'
-import { SessionsStatusSegment } from './SessionsStatusSegment'
 import { UpdateStatusSegment } from './UpdateStatusSegment'
-import { MemoryStatusSegment } from './MemoryStatusSegment'
+import { ResourceUsageStatusSegment } from './ResourceUsageStatusSegment'
 import { SidekickStatusSegment } from './SidekickStatusSegment'
 
 function getCodexAccountLabel(
@@ -774,9 +765,8 @@ function StatusBarInner(): React.JSX.Element | null {
   const showGemini = gemini !== null && statusBarItems.includes('gemini')
   const showOpencodeGo = opencodeGo !== null && statusBarItems.includes('opencode-go')
   const showSsh = statusBarItems.includes('ssh')
-  const showSessions = statusBarItems.includes('sessions')
-  const showMemory = statusBarItems.includes('memory')
-  const anyVisible = showClaude || showCodex || showGemini || showOpencodeGo || showMemory
+  const showResourceUsage = statusBarItems.includes('resource-usage')
+  const anyVisible = showClaude || showCodex || showGemini || showOpencodeGo || showResourceUsage
   const anyFetching =
     claude?.status === 'fetching' ||
     codex?.status === 'fetching' ||
@@ -850,8 +840,7 @@ function StatusBarInner(): React.JSX.Element | null {
       <div className="flex items-center gap-3">
         <UpdateStatusSegment compact={compact} iconOnly={iconOnly} />
         {sidekickEnabled && <SidekickStatusSegment />}
-        {showMemory && <MemoryStatusSegment compact={compact} iconOnly={iconOnly} />}
-        {showSessions && <SessionsStatusSegment compact={compact} iconOnly={iconOnly} />}
+        {showResourceUsage && <ResourceUsageStatusSegment compact={compact} iconOnly={iconOnly} />}
         {showSsh && <SshStatusSegment compact={compact} iconOnly={iconOnly} />}
       </div>
 
@@ -901,18 +890,11 @@ function StatusBarInner(): React.JSX.Element | null {
             SSH Status
           </DropdownMenuCheckboxItem>
           <DropdownMenuCheckboxItem
-            checked={statusBarItems.includes('sessions')}
-            onCheckedChange={() => toggleStatusBarItem('sessions')}
+            checked={statusBarItems.includes('resource-usage')}
+            onCheckedChange={() => toggleStatusBarItem('resource-usage')}
           >
-            <Terminal className="size-3.5" />
-            Terminal Sessions
-          </DropdownMenuCheckboxItem>
-          <DropdownMenuCheckboxItem
-            checked={statusBarItems.includes('memory')}
-            onCheckedChange={() => toggleStatusBarItem('memory')}
-          >
-            <MemoryStickIcon className="size-3.5" />
-            Memory
+            <Activity className="size-3.5" />
+            Resource Usage
           </DropdownMenuCheckboxItem>
         </DropdownMenuContent>
       </DropdownMenu>
diff --git a/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.test.ts b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.test.ts
new file mode 100644
index 00000000000..92641313b54
--- /dev/null
+++ b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.test.ts
@@ -0,0 +1,286 @@
+import { describe, expect, it } from 'vitest'
+import type { MemorySnapshot, TerminalTab, WorktreeMemory } from '../../../../shared/types'
+import {
+  mergeSnapshotAndSessions,
+  UNATTRIBUTED_REPO_ID,
+  type DaemonSession,
+  type MergeContext
+} from './mergeSnapshotAndSessions'
+
+function emptyAppMemory() {
+  return {
+    cpu: 0,
+    memory: 0,
+    main: { cpu: 0, memory: 0 },
+    renderer: { cpu: 0, memory: 0 },
+    other: { cpu: 0, memory: 0 },
+    history: []
+  }
+}
+
+function makeSnapshot(worktrees: WorktreeMemory[]): MemorySnapshot {
+  return {
+    app: emptyAppMemory(),
+    worktrees,
+    host: {
+      totalMemory: 16e9,
+      freeMemory: 8e9,
+      usedMemory: 8e9,
+      memoryUsagePercent: 50,
+      cpuCoreCount: 8,
+      loadAverage1m: 0
+    },
+    totalCpu: worktrees.reduce((s, w) => s + w.cpu, 0),
+    totalMemory: worktrees.reduce((s, w) => s + w.memory, 0),
+    collectedAt: 0
+  }
+}
+
+function makeTab(id: string, defaultTitle = 'Terminal'): TerminalTab {
+  return {
+    id,
+    title: defaultTitle,
+    defaultTitle,
+    customTitle: null,
+    type: 'terminal',
+    paneCount: 1
+  } as unknown as TerminalTab
+}
+
+const baseCtx = (overrides: Partial<MergeContext> = {}): MergeContext => ({
+  tabsByWorktree: {},
+  ptyIdsByTabId: {},
+  runtimePaneTitlesByTabId: {},
+  workspaceSessionReady: true,
+  repoDisplayNameById: new Map(),
+  ...overrides
+})
+
+describe('mergeSnapshotAndSessions', () => {
+  it('returns empty list when both inputs are empty', () => {
+    expect(mergeSnapshotAndSessions(null, [], baseCtx())).toEqual([])
+  })
+
+  it('passes through snapshot worktrees with numeric metrics and hasLocalSamples', () => {
+    const wt: WorktreeMemory = {
+      worktreeId: 'orca::/Users/me/Triton',
+      worktreeName: 'Triton',
+      repoId: 'orca',
+      repoName: 'ORCA',
+      cpu: 1.5,
+      memory: 100_000_000,
+      history: [1, 2, 3],
+      sessions: [{ sessionId: 'pty-1', paneKey: null, pid: 1234, cpu: 1.5, memory: 100_000_000 }]
+    }
+    const out = mergeSnapshotAndSessions(makeSnapshot([wt]), [], baseCtx())
+    expect(out).toHaveLength(1)
+    expect(out[0]).toMatchObject({
+      repoId: 'orca',
+      repoName: 'ORCA',
+      cpu: 1.5,
+      memory: 100_000_000,
+      hasRemoteChildren: false
+    })
+    expect(out[0].worktrees[0]).toMatchObject({
+      worktreeName: 'Triton',
+      cpu: 1.5,
+      memory: 100_000_000,
+      hasLocalSamples: true
+    })
+    expect(out[0].worktrees[0].sessions[0]).toMatchObject({
+      sessionId: 'pty-1',
+      cpu: 1.5,
+      memory: 100_000_000,
+      hasLocalSamples: true
+    })
+  })
+
+  it('dedups: a session present in both snapshot and daemon list renders once with numeric metrics', () => {
+    const wt: WorktreeMemory = {
+      worktreeId: 'orca::/Users/me/Triton',
+      worktreeName: 'Triton',
+      repoId: 'orca',
+      repoName: 'ORCA',
+      cpu: 0.1,
+      memory: 50_000_000,
+      history: [],
+      sessions: [{ sessionId: 'pty-1', paneKey: null, pid: 999, cpu: 0.1, memory: 50_000_000 }]
+    }
+    const ds: DaemonSession[] = [{ id: 'pty-1', cwd: '/Users/me/Triton', title: 'shell' }]
+    const out = mergeSnapshotAndSessions(makeSnapshot([wt]), ds, baseCtx())
+    expect(out[0].worktrees[0].sessions).toHaveLength(1)
+    expect(out[0].worktrees[0].sessions[0]).toMatchObject({
+      sessionId: 'pty-1',
+      hasLocalSamples: true,
+      cpu: 0.1,
+      memory: 50_000_000
+    })
+  })
+
+  it('@@ parse: an SSH-style session id resolves to its worktree group', () => {
+    const ds: DaemonSession[] = [
+      { id: 'orca::/remote/Stingray@@abcd1234', cwd: '', title: 'orca/Stingray' }
+    ]
+    const out = mergeSnapshotAndSessions(null, ds, baseCtx())
+    expect(out).toHaveLength(1)
+    expect(out[0]).toMatchObject({
+      repoId: 'orca',
+      hasRemoteChildren: true,
+      cpu: null,
+      memory: null
+    })
+    expect(out[0].worktrees[0]).toMatchObject({
+      worktreeId: 'orca::/remote/Stingray',
+      worktreeName: 'Stingray',
+      hasLocalSamples: false,
+      cpu: null,
+      memory: null
+    })
+    expect(out[0].worktrees[0].sessions[0]).toMatchObject({
+      sessionId: 'orca::/remote/Stingray@@abcd1234',
+      hasLocalSamples: false,
+      cpu: null,
+      memory: null,
+      bound: false
+    })
+  })
+
+  it('tab walk wins over @@ parse when they disagree', () => {
+    const tabId = 'tab-xyz'
+    const ds: DaemonSession[] = [{ id: 'orca::/wrong/path@@feedface', cwd: '', title: 'orca' }]
+    const ctx = baseCtx({
+      tabsByWorktree: {
+        'orca::/correct/path': [makeTab(tabId, 'My Tab')]
+      },
+      ptyIdsByTabId: { [tabId]: ['orca::/wrong/path@@feedface'] }
+    })
+    const out = mergeSnapshotAndSessions(null, ds, ctx)
+    expect(out[0].worktrees[0].worktreeId).toBe('orca::/correct/path')
+    expect(out[0].worktrees[0].sessions[0].tabId).toBe(tabId)
+    expect(out[0].worktrees[0].sessions[0].bound).toBe(true)
+  })
+
+  it('repo aggregate excludes remote children but flags hasRemoteChildren', () => {
+    const localWt: WorktreeMemory = {
+      worktreeId: 'orca::/local/Triton',
+      worktreeName: 'Triton',
+      repoId: 'orca',
+      repoName: 'ORCA',
+      cpu: 0.5,
+      memory: 125_000_000,
+      history: [],
+      sessions: []
+    }
+    const ds: DaemonSession[] = [
+      { id: 'orca::/remote/Stingray@@1234', cwd: '', title: 'orca/Stingray' }
+    ]
+    const out = mergeSnapshotAndSessions(makeSnapshot([localWt]), ds, baseCtx())
+    expect(out).toHaveLength(1)
+    expect(out[0]).toMatchObject({
+      repoId: 'orca',
+      cpu: 0.5,
+      memory: 125_000_000,
+      hasRemoteChildren: true
+    })
+    expect(out[0].worktrees).toHaveLength(2)
+    const local = out[0].worktrees.find((w) => w.hasLocalSamples)!
+    const remote = out[0].worktrees.find((w) => !w.hasLocalSamples)!
+    expect(local.cpu).toBe(0.5)
+    expect(remote.cpu).toBeNull()
+  })
+
+  it('unresolvable session falls into unattributed bucket', () => {
+    const ds: DaemonSession[] = [{ id: 'opaque-id-without-prefix', cwd: '', title: 'shell' }]
+    const out = mergeSnapshotAndSessions(null, ds, baseCtx())
+    expect(out).toHaveLength(1)
+    expect(out[0].repoId).toBe(UNATTRIBUTED_REPO_ID)
+    expect(out[0].hasRemoteChildren).toBe(true)
+    expect(out[0].worktrees[0].sessions[0].sessionId).toBe('opaque-id-without-prefix')
+  })
+
+  it('local-bound interaction state: numeric metrics + bound=true + tabId set', () => {
+    const tabId = 'tab-1'
+    const wt: WorktreeMemory = {
+      worktreeId: 'orca::/Users/me/Triton',
+      worktreeName: 'Triton',
+      repoId: 'orca',
+      repoName: 'ORCA',
+      cpu: 0.1,
+      memory: 1_000,
+      history: [],
+      sessions: [{ sessionId: 'pty-bound', paneKey: null, pid: 1, cpu: 0.1, memory: 1_000 }]
+    }
+    const ctx = baseCtx({
+      tabsByWorktree: { 'orca::/Users/me/Triton': [makeTab(tabId)] },
+      ptyIdsByTabId: { [tabId]: ['pty-bound'] }
+    })
+    const out = mergeSnapshotAndSessions(makeSnapshot([wt]), [], ctx)
+    const session = out[0].worktrees[0].sessions[0]
+    expect(session).toMatchObject({
+      hasLocalSamples: true,
+      bound: true,
+      tabId
+    })
+  })
+
+  it('local-orphan interaction state: numeric metrics + bound=false + tabId null', () => {
+    const wt: WorktreeMemory = {
+      worktreeId: 'orca::/Users/me/Triton',
+      worktreeName: 'Triton',
+      repoId: 'orca',
+      repoName: 'ORCA',
+      cpu: 0,
+      memory: 0,
+      history: [],
+      sessions: [{ sessionId: 'pty-orph', paneKey: null, pid: 0, cpu: 0, memory: 0 }]
+    }
+    const out = mergeSnapshotAndSessions(makeSnapshot([wt]), [], baseCtx())
+    const session = out[0].worktrees[0].sessions[0]
+    expect(session.bound).toBe(false)
+    expect(session.tabId).toBeNull()
+    expect(session.hasLocalSamples).toBe(true)
+  })
+
+  it('remote-orphan interaction state: null metrics + bound=false', () => {
+    const ds: DaemonSession[] = [{ id: 'orca::/remote/Wt@@deadbeef', cwd: '', title: 'orca/Wt' }]
+    const out = mergeSnapshotAndSessions(null, ds, baseCtx())
+    const session = out[0].worktrees[0].sessions[0]
+    expect(session).toMatchObject({
+      hasLocalSamples: false,
+      cpu: null,
+      memory: null,
+      bound: false,
+      tabId: null
+    })
+  })
+
+  it('uses repoDisplayNameById to humanize new repo groups when available', () => {
+    const ds: DaemonSession[] = [{ id: 'stably-ai/orca::/remote/Wt@@1', cwd: '', title: '' }]
+    const ctx = baseCtx({
+      repoDisplayNameById: new Map([['stably-ai/orca', 'ORCA']])
+    })
+    const out = mergeSnapshotAndSessions(null, ds, ctx)
+    expect(out[0].repoName).toBe('ORCA')
+  })
+
+  it('workspaceSessionReady=false suppresses bound flags so nothing looks bound prematurely', () => {
+    const tabId = 'tab-1'
+    const wt: WorktreeMemory = {
+      worktreeId: 'orca::/Users/me/Triton',
+      worktreeName: 'Triton',
+      repoId: 'orca',
+      repoName: 'ORCA',
+      cpu: 0,
+      memory: 0,
+      history: [],
+      sessions: [{ sessionId: 'pty-1', paneKey: null, pid: 1, cpu: 0, memory: 0 }]
+    }
+    const ctx = baseCtx({
+      workspaceSessionReady: false,
+      tabsByWorktree: { 'orca::/Users/me/Triton': [makeTab(tabId)] },
+      ptyIdsByTabId: { [tabId]: ['pty-1'] }
+    })
+    const out = mergeSnapshotAndSessions(makeSnapshot([wt]), [], ctx)
+    expect(out[0].worktrees[0].sessions[0].bound).toBe(false)
+  })
+})
diff --git a/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
new file mode 100644
index 00000000000..27644c48444
--- /dev/null
+++ b/src/renderer/src/components/status-bar/mergeSnapshotAndSessions.ts
@@ -0,0 +1,417 @@
+/* eslint-disable max-lines -- Why: this module deliberately co-locates the
+   renderer-local view-model types, the merge function, and its supporting
+   string-manipulation helpers because they exist solely to feed the popover
+   in ResourceUsageStatusSegment.tsx. Splitting would scatter logic that has
+   exactly one consumer. See docs/resource-usage-merge-spec.md. */
+/**
+ * Resource Usage popover merge helper.
+ *
+ * Produces a single grouped list (repo → worktree → session) by unifying:
+ *
+ *   - `MemorySnapshot.worktrees` — local PTYs only, with numeric CPU/Mem
+ *     per worktree and per session (the local memory collector doesn't see
+ *     SSH process trees, by design — see src/main/memory/collector.ts and
+ *     the registerPty branch at src/main/ipc/pty.ts:832).
+ *   - `pty.listSessions()` — every PTY the daemon tracks, local or SSH.
+ *
+ * The merge is renderer-only and pure. It does NOT widen the shared
+ * `WorktreeMemory` shape; instead it emits a renderer-local view-model
+ * with `Metric = number | null`, where `null` means "no local sample"
+ * (e.g. an SSH session). The popover renders `null` cells as `—`.
+ *
+ * See docs/resource-usage-merge-spec.md for the full design.
+ */
+
+import type {
+  MemorySnapshot,
+  SessionMemory,
+  TerminalTab,
+  WorktreeMemory
+} from '../../../../shared/types'
+
+// ─── View-model types (renderer-local) ──────────────────────────────
+
+/** `null` === "no local sample" (e.g. SSH PTY); UI renders as em-dash. */
+export type Metric = number | null
+
+export type DaemonSession = {
+  id: string
+  cwd: string
+  title: string
+}
+
+export type UnifiedSessionRow = {
+  sessionId: string
+  paneKey: string | null
+  pid: number
+  label: string
+  bound: boolean
+  tabId: string | null
+  cpu: Metric
+  memory: Metric
+  hasLocalSamples: boolean
+}
+
+export type UnifiedWorktreeRow = {
+  worktreeId: string
+  worktreeName: string
+  repoId: string
+  repoName: string
+  cpu: Metric
+  memory: Metric
+  history: number[]
+  hasLocalSamples: boolean
+  sessions: UnifiedSessionRow[]
+}
+
+export type UnifiedRepoGroup = {
+  repoId: string
+  repoName: string
+  cpu: Metric
+  memory: Metric
+  hasRemoteChildren: boolean
+  worktrees: UnifiedWorktreeRow[]
+}
+
+// ─── Inputs that the renderer already has on hand ───────────────────
+
+export type MergeContext = {
+  /** From useAppStore: maps tabId → worktreeId for tab-walk resolution. */
+  tabsByWorktree: Record<string, TerminalTab[]>
+  /** From useAppStore: maps tabId → ptyIds[] for the bound check. */
+  ptyIdsByTabId: Record<string, string[]>
+  /** From useAppStore: per-tab live pane titles (for label resolution). */
+  runtimePaneTitlesByTabId: Record<string, Record<number, string>>
+  /** From useAppStore: false until the renderer has booted enough state to
+   *  trust the bound/orphan distinction. Mirrors the existing gate. */
+  workspaceSessionReady: boolean
+  /** Repo display names by repo id. Used for new groups synthesized from
+   *  daemon sessions whose repo isn't in the snapshot (typical SSH case). */
+  repoDisplayNameById: Map<string, string>
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+const ORCA_WORKTREE_ID_SEPARATOR = '::'
+
+/** Why: minted PTY session ids look like `${worktreeId}@@${shortUuid}`
+ *  (see src/main/daemon/pty-session-id.ts). The renderer-side parser
+ *  only needs the prefix; `lastIndexOf` is robust to worktreeIds that
+ *  may themselves contain `@`. */
+function parseWorktreeIdFromSessionId(sessionId: string): string | null {
+  const idx = sessionId.lastIndexOf('@@')
+  if (idx <= 0) {
+    return null
+  }
+  const candidate = sessionId.slice(0, idx)
+  if (!candidate.includes(ORCA_WORKTREE_ID_SEPARATOR)) {
+    return null
+  }
+  return candidate
+}
+
+function deriveRepoIdFromWorktreeId(worktreeId: string): string {
+  const sep = worktreeId.indexOf(ORCA_WORKTREE_ID_SEPARATOR)
+  return sep > 0 ? worktreeId.slice(0, sep) : worktreeId
+}
+
+function deriveWorktreeNameFromWorktreeId(worktreeId: string): string {
+  const sep = worktreeId.indexOf(ORCA_WORKTREE_ID_SEPARATOR)
+  if (sep <= 0) {
+    return worktreeId
+  }
+  const path = worktreeId.slice(sep + 2)
+  if (!path) {
+    return worktreeId
+  }
+  const parts = path.split(/[\\/]+/).filter(Boolean)
+  return parts.at(-1) ?? worktreeId
+}
+
+function shortCwd(cwd: string): string {
+  if (!cwd) {
+    return ''
+  }
+  const sep = cwd.includes('\\') ? '\\' : '/'
+  const parts = cwd.split(/[\\/]+/).filter(Boolean)
+  return parts.length > 2 ? parts.slice(-2).join(sep) : cwd
+}
+
+function parsePaneKey(paneKey: string | null): { tabId: string; paneRuntimeId: number } | 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 }
+}
+
+function resolveSnapshotSessionLabel(
+  session: SessionMemory,
+  worktreeId: string,
+  ctx: MergeContext
+): string {
+  const parsed = parsePaneKey(session.paneKey)
+  if (parsed) {
+    const tabs = ctx.tabsByWorktree[worktreeId] ?? []
+    const tabIndex = tabs.findIndex((t) => t.id === parsed.tabId)
+    const tab = tabIndex >= 0 ? tabs[tabIndex] : undefined
+    if (tab) {
+      const custom = tab.customTitle?.trim()
+      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}`
+    }
+  }
+  if (session.pid > 0) {
+    return `pid ${session.pid}`
+  }
+  const fallback = session.sessionId?.slice(0, 8)
+  return fallback ? `session ${fallback}` : '(unknown session)'
+}
+
+function resolveDaemonSessionLabel(
+  session: DaemonSession,
+  resolvedWorktreeId: string | null,
+  tabId: string | null,
+  ctx: MergeContext
+): string {
+  if (tabId && resolvedWorktreeId) {
+    const tabs = ctx.tabsByWorktree[resolvedWorktreeId] ?? []
+    const tabIndex = tabs.findIndex((t) => t.id === tabId)
+    const tab = tabIndex >= 0 ? tabs[tabIndex] : undefined
+    if (tab) {
+      const custom = tab.customTitle?.trim()
+      if (custom) {
+        return custom
+      }
+      const runtimeMap = ctx.runtimePaneTitlesByTabId[tabId]
+      if (runtimeMap) {
+        const live = Object.values(runtimeMap).find((t) => t?.trim())
+        if (live) {
+          return live
+        }
+      }
+      const fallback = tab.defaultTitle?.trim() || tab.title?.trim()
+      if (fallback) {
+        return fallback
+      }
+    }
+  }
+  if (session.cwd) {
+    return shortCwd(session.cwd)
+  }
+  if (resolvedWorktreeId) {
+    return shortCwd(resolvedWorktreeId)
+  }
+  if (session.title) {
+    return session.title
+  }
+  return 'unknown'
+}
+
+// Why: the previous implementation did O(N) linear scans over
+// ptyIdsByTabId / tabsByWorktree for *every* session it processed. With a
+// large workspace that's S * (T + W) work per merge — and the merge runs on
+// every snapshot poll plus every store mutation. Pre-build O(1) lookup
+// indices once per merge instead.
+type MergeIndex = {
+  ptyIdToTabId: Map<string, string>
+  tabIdToWorktreeId: Map<string, string>
+}
+
+function buildMergeIndex(ctx: MergeContext): MergeIndex {
+  const ptyIdToTabId = new Map<string, string>()
+  for (const [tabId, ptyIds] of Object.entries(ctx.ptyIdsByTabId)) {
+    for (const ptyId of ptyIds) {
+      if (ptyId) {
+        ptyIdToTabId.set(ptyId, tabId)
+      }
+    }
+  }
+  const tabIdToWorktreeId = new Map<string, string>()
+  for (const [worktreeId, tabs] of Object.entries(ctx.tabsByWorktree)) {
+    for (const tab of tabs) {
+      tabIdToWorktreeId.set(tab.id, worktreeId)
+    }
+  }
+  return { ptyIdToTabId, tabIdToWorktreeId }
+}
+
+// ─── Public merge function ─────────────────────────────────────────
+
+export const UNATTRIBUTED_REPO_ID = '__unattributed__'
+export const UNATTRIBUTED_REPO_NAME = 'Unattributed'
+
+export function mergeSnapshotAndSessions(
+  snapshot: MemorySnapshot | null,
+  daemonSessions: readonly DaemonSession[],
+  ctx: MergeContext
+): UnifiedRepoGroup[] {
+  const repos = new Map<string, UnifiedRepoGroup>()
+  const seenSessionIds = new Set<string>()
+  const index = buildMergeIndex(ctx)
+  // Why: bound = the daemon session id appears as a pty id under some tab.
+  // ptyIdToTabId already encodes that membership in O(1), so the bound set
+  // is just its keys.
+  const boundPtyIds = ctx.workspaceSessionReady
+    ? new Set(index.ptyIdToTabId.keys())
+    : new Set<string>()
+
+  function ensureRepo(
+    repoId: string,
+    repoName: string,
+    initiallyHasRemoteChildren = false
+  ): UnifiedRepoGroup {
+    const existing = repos.get(repoId)
+    if (existing) {
+      return existing
+    }
+    const next: UnifiedRepoGroup = {
+      repoId,
+      repoName,
+      cpu: null,
+      memory: null,
+      hasRemoteChildren: initiallyHasRemoteChildren,
+      worktrees: []
+    }
+    repos.set(repoId, next)
+    return next
+  }
+
+  function findWorktreeRow(
+    repo: UnifiedRepoGroup,
+    worktreeId: string
+  ): UnifiedWorktreeRow | undefined {
+    return repo.worktrees.find((w) => w.worktreeId === worktreeId)
+  }
+
+  // ── Step 1: ingest snapshot worktrees as the local-truth foundation.
+  if (snapshot) {
+    for (const wt of snapshot.worktrees as readonly WorktreeMemory[]) {
+      const repo = ensureRepo(wt.repoId, wt.repoName)
+      const sessions: UnifiedSessionRow[] = wt.sessions.map((s) => {
+        seenSessionIds.add(s.sessionId)
+        const tabId = index.ptyIdToTabId.get(s.sessionId) ?? null
+        return {
+          sessionId: s.sessionId,
+          paneKey: s.paneKey,
+          pid: s.pid,
+          label: resolveSnapshotSessionLabel(s, wt.worktreeId, ctx),
+          bound: ctx.workspaceSessionReady && boundPtyIds.has(s.sessionId),
+          tabId,
+          cpu: s.cpu,
+          memory: s.memory,
+          hasLocalSamples: true
+        }
+      })
+      repo.worktrees.push({
+        worktreeId: wt.worktreeId,
+        worktreeName: wt.worktreeName,
+        repoId: wt.repoId,
+        repoName: wt.repoName,
+        cpu: wt.cpu,
+        memory: wt.memory,
+        history: wt.history,
+        hasLocalSamples: true,
+        sessions
+      })
+    }
+  }
+
+  // ── Step 2: union daemon sessions that the snapshot didn't cover.
+  for (const session of daemonSessions) {
+    if (seenSessionIds.has(session.id)) {
+      continue
+    }
+    seenSessionIds.add(session.id)
+
+    // 2a: tab-store walk — does this session belong to a tab in this renderer?
+    const tabId = index.ptyIdToTabId.get(session.id) ?? null
+    let worktreeId = tabId ? (index.tabIdToWorktreeId.get(tabId) ?? null) : null
+
+    // 2b: @@-parse — recover worktreeId from the minted session id format.
+    if (!worktreeId) {
+      worktreeId = parseWorktreeIdFromSessionId(session.id)
+    }
+
+    // 2c: unattributed bucket.
+    const isUnattributed = !worktreeId
+    const finalWorktreeId = worktreeId ?? `${UNATTRIBUTED_REPO_ID}::${session.id}`
+    const finalRepoId = isUnattributed
+      ? UNATTRIBUTED_REPO_ID
+      : deriveRepoIdFromWorktreeId(finalWorktreeId)
+    const finalRepoName = isUnattributed
+      ? UNATTRIBUTED_REPO_NAME
+      : ctx.repoDisplayNameById.get(finalRepoId) || finalRepoId
+    const finalWorktreeName = isUnattributed
+      ? session.title || session.id.slice(0, 12)
+      : deriveWorktreeNameFromWorktreeId(finalWorktreeId)
+
+    const repo = ensureRepo(finalRepoId, finalRepoName, true)
+    repo.hasRemoteChildren = true
+
+    let row = findWorktreeRow(repo, finalWorktreeId)
+    if (!row) {
+      row = {
+        worktreeId: finalWorktreeId,
+        worktreeName: finalWorktreeName,
+        repoId: finalRepoId,
+        repoName: finalRepoName,
+        cpu: null,
+        memory: null,
+        history: [],
+        hasLocalSamples: false,
+        sessions: []
+      }
+      repo.worktrees.push(row)
+    }
+
+    row.sessions.push({
+      sessionId: session.id,
+      paneKey: null,
+      pid: 0,
+      label: resolveDaemonSessionLabel(session, worktreeId, tabId, ctx),
+      bound: ctx.workspaceSessionReady && boundPtyIds.has(session.id),
+      tabId,
+      cpu: null,
+      memory: null,
+      hasLocalSamples: false
+    })
+  }
+
+  // ── Step 3: per-repo aggregates exclude remote children.
+  for (const repo of repos.values()) {
+    let cpuSum = 0
+    let memSum = 0
+    let anyLocal = false
+    let anyRemote = false
+    for (const wt of repo.worktrees) {
+      if (wt.hasLocalSamples && wt.cpu !== null && wt.memory !== null) {
+        cpuSum += wt.cpu
+        memSum += wt.memory
+        anyLocal = true
+      } else {
+        anyRemote = true
+      }
+    }
+    repo.cpu = anyLocal ? cpuSum : null
+    repo.memory = anyLocal ? memSum : null
+    if (anyRemote) {
+      repo.hasRemoteChildren = true
+    }
+  }
+
+  return [...repos.values()]
+}
diff --git a/src/renderer/src/components/terminal-pane/TerminalPane.tsx b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
index 06e852651b7..6437d3cd4ca 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPane.tsx
@@ -29,17 +29,15 @@ import { useTerminalPaneLifecycle } from './use-terminal-pane-lifecycle'
 import { useTerminalPaneContextMenu } from './use-terminal-pane-context-menu'
 import { useNotificationDispatch } from './use-notification-dispatch'
 import { connectPanePty } from './pty-connection'
-import {
-  getFitOverrideForPty,
-  getPaneIdsForPty,
-  onOverrideChange
-} from '@/lib/pane-manager/mobile-fit-overrides'
+import { getPaneIdsForPty, 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'
 
-/** Global set of buffer-capture callbacks, one per mounted TerminalPane.
- *  The beforeunload handler in App.tsx invokes every callback to populate
- *  Zustand with serialized buffers before flushing the session to disk. */
-export const shutdownBufferCaptures = new Set<() => void>()
+// Why: registry lives in a leaf module so the store slice can import it
+// without re-entering the `slice → TerminalPane → store → slice` cycle
+// that otherwise leaves createTerminalSlice undefined at store-init time.
+import { shutdownBufferCaptures } from './shutdown-buffer-captures'
+import { mergeCapturedLeafState } from './merge-captured-leaf-state'
 
 const MAX_BUFFER_BYTES = 512 * 1024
 
@@ -140,10 +138,17 @@ export default function TerminalPane({
           }
           requestAnimationFrame(fitAffectedPanes)
           // Why: belt-and-suspenders — if safeFit's fitAddon.fit() threw or
-          // was a no-op due to stale dimensions, this fallback uses the
-          // restored cols/rows from the runtime to force the resize. If
-          // safeFit already succeeded, the terminal is already at the right
-          // dims and this is a harmless no-op.
+          // was a no-op due to stale dimensions, fall back to a direct
+          // resize. ONLY fire if xterm is still parked at the prior
+          // mobile-fit dims, meaning safeFit failed to move it. Previously
+          // we also fired when xterm had moved to *any* size other than
+          // the captured baseline, which clobbered safeFit's correct
+          // DOM-measured fit when the desktop pane geometry had changed
+          // since mobile-fit started (e.g. user closed a split or resized
+          // the window while the phone was active). In that scenario the
+          // event.cols/rows is the stale baseline from the moment
+          // 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)
@@ -151,13 +156,12 @@ export default function TerminalPane({
                 continue
               }
               safeFit(pane)
-              // Fallback: if terminal is still at mobile dims, force resize
-              // using the restored dimensions from the runtime notification.
-              if (
-                event.cols > 0 &&
-                event.rows > 0 &&
-                (pane.terminal.cols !== event.cols || pane.terminal.rows !== event.rows)
-              ) {
+              const stuckAtMobile =
+                event.priorCols != null &&
+                event.priorRows != null &&
+                pane.terminal.cols === event.priorCols &&
+                pane.terminal.rows === event.priorRows
+              if (stuckAtMobile && event.cols > 0 && event.rows > 0) {
                 pane.terminal.resize(event.cols, event.rows)
               }
             }
@@ -167,6 +171,18 @@ export default function TerminalPane({
     []
   )
 
+  // Why: presence-lock banner re-render. Driver state lives in a plain Map
+  // for perf; this counter forces a re-render when the driver flips so the
+  // lock banner appears/disappears. See docs/mobile-presence-lock.md.
+  const [, setDriverTick] = useState(0)
+  useEffect(
+    () =>
+      onDriverChange(() => {
+        setDriverTick((n) => n + 1)
+      }),
+    []
+  )
+
   // Pane title state — keyed by ephemeral paneId, persisted via titlesByLeafId
   // in the layout snapshot. Ref keeps persistLayoutSnapshot closures fresh.
   const [paneTitles, setPaneTitles] = useState<Record<number, string>>({})
@@ -269,39 +285,42 @@ export default function TerminalPane({
     }
     const activePaneId = manager.getActivePane()?.id ?? manager.getPanes()[0]?.id ?? null
     const layout = serializeTerminalLayout(container, activePaneId, expandedPaneIdRef.current)
-    // Preserve existing buffersByLeafId so layout-only persists (resize, split,
-    // reorder) don't clobber previously captured scrollback.
     const existing = useAppStore.getState().terminalLayoutsByTabId[tabId]
-    if (existing?.buffersByLeafId) {
-      const currentLeafIds = new Set(manager.getPanes().map((p) => paneLeafId(p.id)))
-      layout.buffersByLeafId = Object.fromEntries(
-        Object.entries(existing.buffersByLeafId).filter(([id]) => currentLeafIds.has(id))
-      )
+    const currentPanes = manager.getPanes()
+    const currentLeafIds = new Set(currentPanes.map((p) => paneLeafId(p.id)))
+    // Preserve existing buffersByLeafId so layout-only persists (resize, split,
+    // reorder) don't clobber previously captured scrollback. Drop entries for
+    // leaves that no longer exist.
+    const mergedBuffers = mergeCapturedLeafState({
+      prior: existing?.buffersByLeafId,
+      fresh: {},
+      currentLeafIds
+    })
+    if (Object.keys(mergedBuffers).length > 0) {
+      layout.buffersByLeafId = mergedBuffers
     }
     // Why: between pane creation and the deferred rAF where PTYs actually
-    // attach, all transports have getPtyId() === null. If persistLayoutSnapshot
-    // fires during that window the live-transport block below finds no entries,
-    // so this block preserves the *prior* snapshot's leaf→PTY mappings. Without
-    // it, a rapid successive remount (tab moved again before the first rAF)
-    // would lose the mappings and force fresh PTY spawns.
-    if (existing?.ptyIdsByLeafId) {
-      const currentLeafIds = new Set(manager.getPanes().map((p) => paneLeafId(p.id)))
-      layout.ptyIdsByLeafId = Object.fromEntries(
-        Object.entries(existing.ptyIdsByLeafId).filter(([id]) => currentLeafIds.has(id))
-      )
-    }
-    // Preserve pane titles — uses the live React state (via ref) rather than
-    // the stale Zustand value because React state reflects in-flight title
-    // edits that haven't been persisted yet.
-    const currentPanes = manager.getPanes()
-    const ptyEntries = currentPanes
+    // attach, all transports have getPtyId() === null. The merge below
+    // preserves the *prior* snapshot's leaf→PTY mappings while still letting
+    // any live transports overwrite them. Without preservation, a rapid
+    // 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
       )
       .filter((entry): entry is readonly [string, string] => entry[1] !== null)
-    if (ptyEntries.length > 0) {
-      layout.ptyIdsByLeafId = Object.fromEntries(ptyEntries)
+    const mergedPtyIds = mergeCapturedLeafState({
+      prior: existing?.ptyIdsByLeafId,
+      fresh: Object.fromEntries(livePtyEntries),
+      currentLeafIds
+    })
+    if (Object.keys(mergedPtyIds).length > 0) {
+      layout.ptyIdsByLeafId = mergedPtyIds
     }
+    // Preserve pane titles — uses the live React state (via ref) rather than
+    // the stale Zustand value because React state reflects in-flight title
+    // edits that haven't been persisted yet.
     const titles = paneTitlesRef.current
     const titleEntries = currentPanes
       .filter((p) => titles[p.id])
@@ -845,9 +864,14 @@ export default function TerminalPane({
       }
       const activePaneId = manager.getActivePane()?.id ?? panes[0]?.id ?? null
       const layout = serializeTerminalLayout(container, activePaneId, expandedPaneIdRef.current)
-      if (Object.keys(buffers).length > 0) {
-        layout.buffersByLeafId = buffers
-      }
+      // Why: setTabLayout REPLACES — it doesn't merge. captureBuffers can
+      // run during a transient window (post-remount, just-attached,
+      // mid-replay) where xterm hasn't rendered yet so serialize returns 0
+      // bytes. Without preservation, that empty pass would wipe a known-good
+      // buffer. Merge prior state in for leaves whose live capture came back
+      // empty. Same shape as persistLayoutSnapshot.
+      const existing = useAppStore.getState().terminalLayoutsByTabId[tabId]
+      const currentLeafIds = new Set(panes.map((p) => paneLeafId(p.id)))
       const ptyEntries = panes
         .map(
           (pane) =>
@@ -857,8 +881,21 @@ export default function TerminalPane({
             ] as const
         )
         .filter((entry): entry is readonly [string, string] => entry[1] !== null)
-      if (ptyEntries.length > 0) {
-        layout.ptyIdsByLeafId = Object.fromEntries(ptyEntries)
+      const mergedBuffers = mergeCapturedLeafState({
+        prior: existing?.buffersByLeafId,
+        fresh: buffers,
+        currentLeafIds
+      })
+      const mergedPtyIds = mergeCapturedLeafState({
+        prior: existing?.ptyIdsByLeafId,
+        fresh: Object.fromEntries(ptyEntries),
+        currentLeafIds
+      })
+      if (Object.keys(mergedBuffers).length > 0) {
+        layout.buffersByLeafId = mergedBuffers
+      }
+      if (Object.keys(mergedPtyIds).length > 0) {
+        layout.ptyIdsByLeafId = mergedPtyIds
       }
       // Merge pane titles so the shutdown snapshot doesn't silently drop them.
       // Why: the old early-return on empty buffers skipped this entirely, which
@@ -872,9 +909,13 @@ export default function TerminalPane({
       }
       setTabLayout(tabId, layout)
     }
-    shutdownBufferCaptures.add(captureBuffers)
+    shutdownBufferCaptures.set(tabId, captureBuffers)
     return () => {
-      shutdownBufferCaptures.delete(captureBuffers)
+      // Why: only remove if the entry still points at this closure. A
+      // remount could have replaced it before the prior cleanup ran.
+      if (shutdownBufferCaptures.get(tabId) === captureBuffers) {
+        shutdownBufferCaptures.delete(tabId)
+      }
     }
   }, [tabId, setTabLayout])
 
@@ -1123,14 +1164,23 @@ export default function TerminalPane({
         // pane 1). Using the transport's actual ptyId avoids showing banners
         // on the wrong pane when IDs overlap.
         const ptyId = paneTransportsRef.current.get(pane.id)?.getPtyId()
-        const override = ptyId ? getFitOverrideForPty(ptyId) : null
-        if (!override) {
+        if (!ptyId) {
+          return null
+        }
+        // Why: presence-lock — banner is gated on driver state, not on
+        // fit-override. The banner now communicates "input is paused"
+        // (the load-bearing fact) instead of dimensional state. The
+        // dimensional override may still be active and is reflected in
+        // the PTY but not in the banner copy. See
+        // docs/mobile-presence-lock.md.
+        const driver = getDriverForPty(ptyId)
+        if (driver.kind !== 'mobile') {
           return null
         }
         return createPortal(
           <div
-            key={`mobile-fit-${pane.id}`}
-            className="mobile-fit-banner"
+            key={`mobile-driver-${pane.id}`}
+            className="mobile-driver-banner"
             style={{
               position: 'absolute',
               top: 0,
@@ -1147,7 +1197,7 @@ export default function TerminalPane({
             }}
           >
             <span>
-              Terminal resized for phone ({override.cols}×{override.rows})
+              Mobile is driving this terminal — your input is paused. Click Take back to resume.
             </span>
             <button
               style={{
@@ -1162,15 +1212,19 @@ export default function TerminalPane({
               onClick={() => {
                 const ptyId = paneTransportsRef.current.get(pane.id)?.getPtyId()
                 if (ptyId) {
+                  // Why: same IPC route — handler now also reclaims the
+                  // input floor for the desktop via the driver state
+                  // machine, so the banner unmounts and input is unblocked
+                  // until the next mobile interaction.
                   void window.api.runtime.restoreTerminalFit(ptyId)
                 }
               }}
             >
-              Restore
+              Take back
             </button>
           </div>,
           pane.container,
-          `mobile-fit-banner-${pane.id}`
+          `mobile-driver-banner-${pane.id}`
         )
       })}
       <CloseTerminalDialog
diff --git a/src/renderer/src/components/terminal-pane/merge-captured-leaf-state.test.ts b/src/renderer/src/components/terminal-pane/merge-captured-leaf-state.test.ts
new file mode 100644
index 00000000000..3e0e941cc82
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/merge-captured-leaf-state.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { mergeCapturedLeafState } from './merge-captured-leaf-state'
+
+describe('mergeCapturedLeafState', () => {
+  it('returns prior entries unchanged when fresh is empty (the wipe-protection case)', () => {
+    const result = mergeCapturedLeafState({
+      prior: { 'pane:1': 'old-buf-1', 'pane:2': 'old-buf-2' },
+      fresh: {},
+      currentLeafIds: new Set(['pane:1', 'pane:2'])
+    })
+    expect(result).toEqual({ 'pane:1': 'old-buf-1', 'pane:2': 'old-buf-2' })
+  })
+
+  it('overlays fresh entries on top of prior entries', () => {
+    const result = mergeCapturedLeafState({
+      prior: { 'pane:1': 'old-buf-1', 'pane:2': 'old-buf-2' },
+      fresh: { 'pane:1': 'new-buf-1' },
+      currentLeafIds: new Set(['pane:1', 'pane:2'])
+    })
+    expect(result).toEqual({ 'pane:1': 'new-buf-1', 'pane:2': 'old-buf-2' })
+  })
+
+  it('drops prior entries for leaves no longer present', () => {
+    const result = mergeCapturedLeafState({
+      prior: { 'pane:1': 'old-buf-1', 'pane:removed': 'gone' },
+      fresh: { 'pane:1': 'new-buf-1' },
+      currentLeafIds: new Set(['pane:1'])
+    })
+    expect(result).toEqual({ 'pane:1': 'new-buf-1' })
+    expect(result).not.toHaveProperty('pane:removed')
+  })
+
+  it('returns empty when prior is undefined and fresh is empty', () => {
+    const result = mergeCapturedLeafState({
+      prior: undefined,
+      fresh: {},
+      currentLeafIds: new Set(['pane:1'])
+    })
+    expect(result).toEqual({})
+  })
+
+  it('returns fresh entries when prior is undefined', () => {
+    const result = mergeCapturedLeafState({
+      prior: undefined,
+      fresh: { 'pane:1': 'fresh' },
+      currentLeafIds: new Set(['pane:1'])
+    })
+    expect(result).toEqual({ 'pane:1': 'fresh' })
+  })
+
+  it('drops fresh entries for leaves outside currentLeafIds (defense in depth)', () => {
+    const result = mergeCapturedLeafState({
+      prior: {},
+      fresh: { 'pane:1': 'fresh', 'pane:rogue': 'should-be-dropped' },
+      currentLeafIds: new Set(['pane:1'])
+    })
+    expect(result).toEqual({ 'pane:1': 'fresh' })
+    expect(result).not.toHaveProperty('pane:rogue')
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/merge-captured-leaf-state.ts b/src/renderer/src/components/terminal-pane/merge-captured-leaf-state.ts
new file mode 100644
index 00000000000..f504a40ae6a
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/merge-captured-leaf-state.ts
@@ -0,0 +1,30 @@
+// Why: setTabLayout REPLACES the stored layout — it doesn't merge. captureBuffers
+// can run during a transient window (post-remount, just-attached, mid-replay)
+// where xterm hasn't rendered yet so serialize returns 0 bytes for every pane.
+// Without preserving prior entries, that empty pass wipes a known-good buffer
+// from the persisted state and the user loses their scrollback on next launch.
+// This helper merges prior state with this pass's fresh state so a no-op
+// capture never erases a known-good buffer.
+
+export type LeafStringMap = Record<string, string>
+
+export function mergeCapturedLeafState(opts: {
+  prior: LeafStringMap | undefined
+  fresh: LeafStringMap
+  currentLeafIds: ReadonlySet<string>
+}): LeafStringMap {
+  const merged: LeafStringMap = {}
+  if (opts.prior) {
+    for (const [leafId, value] of Object.entries(opts.prior)) {
+      if (opts.currentLeafIds.has(leafId)) {
+        merged[leafId] = value
+      }
+    }
+  }
+  for (const [leafId, value] of Object.entries(opts.fresh)) {
+    if (opts.currentLeafIds.has(leafId)) {
+      merged[leafId] = value
+    }
+  }
+  return merged
+}
diff --git a/src/renderer/src/components/terminal-pane/pty-buffer-serializer.ts b/src/renderer/src/components/terminal-pane/pty-buffer-serializer.ts
index b5106e7349a..6c4cbb60c6c 100644
--- a/src/renderer/src/components/terminal-pane/pty-buffer-serializer.ts
+++ b/src/renderer/src/components/terminal-pane/pty-buffer-serializer.ts
@@ -3,20 +3,106 @@
 // serialize functions keyed by ptyId, and handles IPC requests from the
 // main process to serialize a specific terminal's buffer.
 
-type SerializedBuffer = { data: string; cols: number; rows: number }
-type SerializeFn = () => SerializedBuffer | null | Promise<SerializedBuffer | null>
+import type { IDisposable } from '@xterm/xterm'
 
-const serializersByPtyId = new Map<string, SerializeFn>()
+export type SerializeOpts = {
+  scrollbackRows?: number
+  altScreenForcesZeroRows?: boolean
+}
+
+export type SerializedBuffer = {
+  data: string
+  cols: number
+  rows: number
+  lastTitle?: string
+}
+
+export type SerializeFn = (
+  opts?: SerializeOpts
+) => SerializedBuffer | null | Promise<SerializedBuffer | null>
+
+// Why: ownership tokens prevent a disposed StrictMode first-mount from clobbering
+// the live registration of a remounted pane. Each registration mints a fresh
+// owner symbol; the unregister closure only deletes when the entry's owner
+// matches its captured token.
+type SerializerEntry = {
+  fn: SerializeFn
+  owner: symbol
+}
+
+type TitleEntry = {
+  title: string
+  owner: symbol
+  disposable: IDisposable
+}
+
+const serializersByPtyId = new Map<string, SerializerEntry>()
+const lastTitleByPtyId = new Map<string, TitleEntry>()
 let listenerAttached = false
 
 export function registerPtySerializer(ptyId: string, serialize: SerializeFn): () => void {
-  serializersByPtyId.set(ptyId, serialize)
+  const owner = Symbol(ptyId)
+  serializersByPtyId.set(ptyId, { fn: serialize, owner })
   ensureSerializerListener()
   return () => {
-    serializersByPtyId.delete(ptyId)
+    const current = serializersByPtyId.get(ptyId)
+    if (current?.owner === owner) {
+      serializersByPtyId.delete(ptyId)
+    }
+    const titleEntry = lastTitleByPtyId.get(ptyId)
+    if (titleEntry?.owner === owner) {
+      // Why: dispose the xterm onTitleChange IDisposable alongside the map
+      // cleanup. Without this, the listener stays attached to xterm's emitter
+      // for the lifetime of the xterm instance, firing against a torn-down
+      // pane (or worse, leaking during HMR).
+      titleEntry.disposable.dispose()
+      lastTitleByPtyId.delete(ptyId)
+    }
   }
 }
 
+// Why: the renderer pane installs an onTitleChange wrapper at the same time
+// it registers the serializer. The wrapper updates lastTitleByPtyId so the
+// IPC response payload can carry the latest observed title without needing
+// the renderer to round-trip xterm state on every serializeBuffer request.
+// xterm's SerializeAddon does NOT round-trip OSC 0/1/2 title sequences, so
+// this is the only channel that gets the title back to the main process.
+export function registerPtyTitleSource(
+  ptyId: string,
+  attach: (handler: (title: string) => void) => IDisposable
+): () => void {
+  const serializerOwner = serializersByPtyId.get(ptyId)?.owner
+  if (!serializerOwner) {
+    // Why: the title source must be registered AFTER the serializer so the
+    // owner token is available. Calling out of order is a programming bug.
+    throw new Error(`registerPtyTitleSource called before serializer for ptyId ${ptyId}`)
+  }
+  const disposable = attach((title) => {
+    const current = lastTitleByPtyId.get(ptyId)
+    if (current && current.owner !== serializerOwner) {
+      return
+    }
+    lastTitleByPtyId.set(ptyId, { title, owner: serializerOwner, disposable })
+  })
+  // Seed an entry with an empty title so the disposable is tracked even
+  // before the first onTitleChange fires. Subsequent updates overwrite it.
+  const existing = lastTitleByPtyId.get(ptyId)
+  if (!existing) {
+    lastTitleByPtyId.set(ptyId, { title: '', owner: serializerOwner, disposable })
+  }
+  return () => {
+    const entry = lastTitleByPtyId.get(ptyId)
+    if (entry?.owner === serializerOwner) {
+      entry.disposable.dispose()
+      lastTitleByPtyId.delete(ptyId)
+    }
+  }
+}
+
+export function hasPtySerializer(ptyId: string): boolean {
+  return serializersByPtyId.has(ptyId)
+}
+
 function ensureSerializerListener(): void {
   if (listenerAttached) {
     return
@@ -24,10 +110,26 @@ function ensureSerializerListener(): void {
   listenerAttached = true
 
   window.api.pty.onSerializeBufferRequest((request) => {
-    const serializer = serializersByPtyId.get(request.ptyId)
-    void Promise.resolve(serializer?.() ?? null)
+    const entry = serializersByPtyId.get(request.ptyId)
+    void Promise.resolve(entry?.fn(request.opts) ?? null)
       .then((result) => {
-        window.api.pty.sendSerializedBuffer(request.requestId, result ?? null)
+        if (!result) {
+          window.api.pty.sendSerializedBuffer(request.requestId, null)
+          return
+        }
+        const titleEntry = lastTitleByPtyId.get(request.ptyId)
+        const lastTitle = titleEntry && titleEntry.title.length > 0 ? titleEntry.title : undefined
+        const payload: SerializedBuffer = {
+          data: result.data,
+          cols: result.cols,
+          rows: result.rows
+        }
+        if (lastTitle !== undefined) {
+          payload.lastTitle = lastTitle
+        } else if (result.lastTitle !== undefined) {
+          payload.lastTitle = result.lastTitle
+        }
+        window.api.pty.sendSerializedBuffer(request.requestId, payload)
       })
       .catch(() => {
         window.api.pty.sendSerializedBuffer(request.requestId, null)
diff --git a/src/renderer/src/components/terminal-pane/pty-connection-types.ts b/src/renderer/src/components/terminal-pane/pty-connection-types.ts
index 2994f43b976..bb41e96990c 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection-types.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection-types.ts
@@ -1,11 +1,18 @@
 import type { PtyTransport } from './pty-transport'
 import type { ReplayingPanesRef } from './replay-guard'
+import type { EventProps } from '../../../../shared/telemetry-events'
 
 export type PtyConnectionDeps = {
   tabId: string
   worktreeId: string
   cwd?: string
-  startup?: { command: string; env?: Record<string, string> } | null
+  startup?: {
+    command: string
+    env?: Record<string, string>
+    /** Telemetry payload for `agent_started`. Forwarded to `pty:spawn`
+     *  so main fires the event only after the spawn succeeds. */
+    telemetry?: EventProps<'agent_started'>
+  } | null
   restoredLeafId?: string | null
   restoredPtyIdByLeafId?: Record<string, string>
   paneTransportsRef: React.RefObject<Map<number, PtyTransport>>
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 c51539cd048..c6e561bd31f 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.test.ts
@@ -4,6 +4,16 @@ 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'
 
+// Why: the fresh-spawn and reattach paths now chain pre-signal → spawn →
+// register/settle through multiple microtasks. Tests that previously flushed
+// once with `await Promise.resolve()` must drain a few extra ticks before
+// asserting against IPC mocks. See docs/mobile-prefer-renderer-scrollback.md.
+async function flushAsyncTicks(count = 6): Promise<void> {
+  for (let i = 0; i < count; i++) {
+    await Promise.resolve()
+  }
+}
+
 const toastInfo = vi.fn()
 
 type StoreState = {
@@ -139,7 +149,8 @@ function createPane(paneId: number) {
       rows: 40,
       write: vi.fn(),
       onData: vi.fn(() => ({ dispose: vi.fn() })),
-      onResize: vi.fn(() => ({ dispose: vi.fn() }))
+      onResize: vi.fn(() => ({ dispose: vi.fn() })),
+      onTitleChange: vi.fn(() => ({ dispose: vi.fn() }))
     },
     container: { dataset: {} },
     fitAddon: {
@@ -238,10 +249,14 @@ describe('connectPanePty', () => {
         pty: {
           signal: vi.fn(),
           ackColdRestore: vi.fn(),
-          onSerializeBufferRequest: vi.fn(() => vi.fn())
+          onSerializeBufferRequest: vi.fn(() => vi.fn()),
+          declarePendingPaneSerializer: vi.fn().mockResolvedValue(1),
+          settlePaneSerializer: vi.fn().mockResolvedValue(undefined),
+          clearPendingPaneSerializer: vi.fn().mockResolvedValue(undefined)
         },
         notifications: {
-          dispatch: vi.fn()
+          dispatch: vi.fn().mockResolvedValue({ delivered: true }),
+          playSound: vi.fn().mockResolvedValue({ played: true })
         }
       }
     }
@@ -627,7 +642,7 @@ describe('connectPanePty', () => {
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
-    await Promise.resolve()
+    await flushAsyncTicks(20)
 
     expect(pane.terminal.write).toHaveBeenCalledWith('\x1b[2J\x1b[3J\x1b[H', expect.any(Function))
     expect(pane.terminal.write).toHaveBeenCalledWith(
@@ -669,7 +684,7 @@ describe('connectPanePty', () => {
       expect.objectContaining({ sessionId: 'pty-local-detached' })
     )
     expect(transport.attach).not.toHaveBeenCalled()
-    await Promise.resolve()
+    await flushAsyncTicks()
     expect(deps.syncPanePtyLayoutBinding).toHaveBeenCalledWith(2, 'pty-local-detached')
   })
 
@@ -693,7 +708,7 @@ describe('connectPanePty', () => {
     })
 
     connectPanePty(restartPane as never, restartManager as never, restartDeps as never)
-    await Promise.resolve()
+    await flushAsyncTicks()
 
     expect(spawnedPtyId).toBe('pty-restarted')
     expect(restartDeps.syncPanePtyLayoutBinding).toHaveBeenCalledWith(1, 'pty-restarted')
@@ -888,9 +903,7 @@ describe('connectPanePty', () => {
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
-    for (let i = 0; i < 5; i++) {
-      await Promise.resolve()
-    }
+    await flushAsyncTicks(20)
 
     const api = (
       globalThis as unknown as {
@@ -945,9 +958,7 @@ describe('connectPanePty', () => {
     })
 
     connectPanePty(pane as never, manager as never, deps as never)
-    for (let i = 0; i < 5; i++) {
-      await Promise.resolve()
-    }
+    await flushAsyncTicks(20)
 
     expect(deps.onPtyErrorRef.current).not.toHaveBeenCalledWith(
       expect.any(Number),
diff --git a/src/renderer/src/components/terminal-pane/pty-connection.ts b/src/renderer/src/components/terminal-pane/pty-connection.ts
index ce27e9a7b00..523c3fa6d2e 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection.ts
@@ -11,6 +11,7 @@ import { shouldSeedCacheTimerOnInitialTitle } from './cache-timer-seeding'
 import type { PtyConnectionDeps } from './pty-connection-types'
 import { safeFit } from '@/lib/pane-manager/pane-tree-ops'
 import { getFitOverrideForPty, bindPanePtyId } from '@/lib/pane-manager/mobile-fit-overrides'
+import { isPtyLocked } from '@/lib/pane-manager/mobile-driver-state'
 import { isPaneReplaying, replayIntoTerminal, replayIntoTerminalAsync } from './replay-guard'
 import {
   paneLeafId,
@@ -19,7 +20,7 @@ import {
 } from './layout-serialization'
 import { warnTerminalLifecycleAnomaly } from './terminal-lifecycle-diagnostics'
 import { detectDeveloperPermissionHint } from './developer-permission-hints'
-import { registerPtySerializer } from './pty-buffer-serializer'
+import { registerPtySerializer, registerPtyTitleSource } from './pty-buffer-serializer'
 
 const pendingSpawnByPaneKey = new Map<string, Promise<string | null>>()
 const developerPermissionHintKeys = new Set<string>()
@@ -332,7 +333,14 @@ export function connectPanePty(
     command: paneStartup?.command,
     connectionId,
     worktreeId: deps.worktreeId,
+    // Why: closes the SIGKILL race documented in INVESTIGATION.md by letting
+    // main sync-flush the (worktreeId, tabId, leafId → ptyId) binding before
+    // 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),
     ...(shellOverride ? { shellOverride } : {}),
+    ...(paneStartup?.telemetry ? { telemetry: paneStartup.telemetry } : {}),
     onPtyExit: onExit,
     onTitleChange,
     onPtySpawn,
@@ -384,6 +392,16 @@ export function connectPanePty(
     if (isCodexPaneStale({ tabId: deps.tabId, panePtyId: currentPtyId })) {
       return
     }
+    // Why: presence-lock input drop. While mobile is the driver for this
+    // PTY, desktop keystrokes must not reach the shell — any input would
+    // race the mobile session and is also dimensionally wrong (PTY is at
+    // phone fit). Renderer-side guard belongs here so we don't even mark
+    // the pane as "interacted" (no unread clear, no take-floor cascade).
+    // The pty:write IPC has a defense-in-depth twin. See
+    // docs/mobile-presence-lock.md.
+    if (currentPtyId && isPtyLocked(currentPtyId)) {
+      return
+    }
     // Why: a real keystroke into the terminal is the unambiguous "user is
     // here" signal that dismisses the bell (ghostty "show until interact").
     // Guarded by the replay and codex-stale checks above so synthetic xterm
@@ -394,12 +412,17 @@ export function connectPanePty(
   })
 
   const onResizeDisposable = pane.terminal.onResize(({ cols, rows }) => {
-    // Why: when a mobile-fit override is active, the PTY is already at the
-    // correct phone dimensions. Suppress resize forwarding to avoid spurious
-    // SIGWINCH signals that could cause TUI flicker. Uses the transport's
-    // ptyId directly to avoid pane ID collisions across tabs.
+    // Why: when a mobile-fit override is active OR mobile is currently the
+    // driver of this PTY, the PTY is already at phone dims and any desktop
+    // resize is wrong. Suppress resize forwarding to avoid spurious SIGWINCH
+    // signals (TUI flicker / wrap corruption). Both checks are needed:
+    // - getFitOverrideForPty covers the "phone-fit dims" state.
+    // - isPtyLocked covers the broader "mobile driving" state, including
+    //   transitions where override may not be set (e.g. legacy code paths).
+    // The pty:resize IPC has a defense-in-depth twin. See
+    // docs/mobile-presence-lock.md.
     const currentPtyId = transport.getPtyId()
-    if (currentPtyId && getFitOverrideForPty(currentPtyId)) {
+    if (currentPtyId && (getFitOverrideForPty(currentPtyId) || isPtyLocked(currentPtyId))) {
       return
     }
     transport.resize(cols, rows)
@@ -438,6 +461,60 @@ export function connectPanePty(
     // constant used for serialized scrollback capture.
     const MAX_PENDING_BYTES = 512 * 1024
 
+    // Why: shared registration so both fresh-spawn and reattach paths install
+    // the same SerializeAddon-backed serializer plus the onTitleChange wrapper
+    // that drives lastTitle parity for mobile subscribers. Wires the resulting
+    // unregister into onDataDisposable.dispose so disposal stays a single
+    // teardown point. See docs/mobile-prefer-renderer-scrollback.md.
+    const registerPaneSerializerFor = (ptyId: string): void => {
+      // Why: StrictMode mounts panes twice; the first mount is disposed
+      // before the second runs, but its pty:spawn IPC may have resolved by
+      // the time `disposed` flips. Without this guard, the disposed first
+      // mount would register against a torn-down xterm and replace the live
+      // second-mount registration via owner-token shadowing.
+      if (disposed) {
+        return
+      }
+      const unregisterSerializer = registerPtySerializer(ptyId, async (opts) => {
+        try {
+          const pending = deps.pendingWritesRef.current.get(pane.id)
+          if (pending) {
+            deps.pendingWritesRef.current.set(pane.id, '')
+            // Why: hidden/background panes buffer PTY output instead of writing
+            // to xterm. Mobile snapshots must include that pending output, and
+            // replay guard prevents xterm query auto-replies from hitting stdin.
+            await replayIntoTerminalAsync(pane, deps.replayingPanesRef, pending)
+          }
+          // Why: alt-screen TUIs (vim, claude-code) hold transient state in
+          // the alternate screen. The hydration path requests
+          // altScreenForcesZeroRows so normal-buffer scrollback isn't bled
+          // into the seed when the user is mid-TUI; the read-fallback path
+          // omits it because it wants the user's currently-visible content.
+          const alt = pane.terminal.buffer.active.type === 'alternate'
+          const data =
+            opts?.altScreenForcesZeroRows && alt
+              ? pane.serializeAddon.serialize({ scrollback: 0 })
+              : pane.serializeAddon.serialize({ scrollback: opts?.scrollbackRows })
+          return {
+            data,
+            cols: pane.terminal.cols,
+            rows: pane.terminal.rows
+          }
+        } catch {
+          return null
+        }
+      })
+      const unregisterTitleSource = registerPtyTitleSource(ptyId, (handler) =>
+        pane.terminal.onTitleChange(handler)
+      )
+      const origOnDataDisposableDispose = onDataDisposable.dispose.bind(onDataDisposable)
+      onDataDisposable.dispose = () => {
+        unregisterTitleSource()
+        unregisterSerializer()
+        origOnDataDisposableDispose()
+      }
+    }
+
     // Why: for local connections (connectionId === null) the local PTY provider
     // already writes the startup command via writeStartupCommandWhenShellReady,
     // which is shell-ready-aware and reliable. Re-sending it here would cause
@@ -446,30 +523,56 @@ export function connectPanePty(
     let pendingStartupCommand = connectionId ? (paneStartup?.command ?? null) : null
 
     const startFreshSpawn = (): void => {
-      const spawnPromise = Promise.resolve(
-        transport.connect({
-          url: '',
-          cols,
-          rows,
-          callbacks: {
-            onData: dataCallback,
-            onReplayData: replayDataCallback,
-            onError: reportError
-          }
-        })
-      )
-        .then((spawnedPtyId) =>
-          typeof spawnedPtyId === 'string' ? spawnedPtyId : transport.getPtyId()
-        )
+      // Why: pre-signal the main process so its cooperation gate suppresses
+      // the daemon-snapshot seed for this paneKey. We issue declare and the
+      // spawn back-to-back without awaiting, because Electron's
+      // ipcRenderer→ipcMain channel preserves order across consecutive invoke
+      // 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 spawnedRaw = transport.connect({
+        url: '',
+        cols,
+        rows,
+        callbacks: {
+          onData: dataCallback,
+          onReplayData: replayDataCallback,
+          onError: reportError
+        }
+      })
+
+      const trackedPromise: Promise<string | null> = Promise.resolve(spawnedRaw)
+        .then(async (spawnedPtyId) => {
+          const resolvedPtyId =
+            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(() => {})
+          } else if (typeof gen === 'number') {
+            void window.api.pty.clearPendingPaneSerializer(cacheKey, gen).catch(() => {})
+          }
+          return resolvedPtyId
+        })
+        .catch(async () => {
+          const gen = await preSignalPromise
+          if (typeof gen === 'number') {
+            void window.api.pty.clearPendingPaneSerializer(cacheKey, gen).catch(() => {})
+          }
+          return null
+        })
         .finally(() => {
-          if (pendingSpawnByPaneKey.get(pendingSpawnKey) === spawnPromise) {
+          if (pendingSpawnByPaneKey.get(pendingSpawnKey) === trackedPromise) {
             pendingSpawnByPaneKey.delete(pendingSpawnKey)
           }
         })
       // Why: split panes in the same tab can spawn concurrently. Key by pane
       // as well as tab so a remount cannot attach to a sibling setup pane's PTY.
-      pendingSpawnByPaneKey.set(pendingSpawnKey, spawnPromise)
+      pendingSpawnByPaneKey.set(pendingSpawnKey, trackedPromise)
     }
 
     // Why: replay bytes (eager-buffer flush, attach-time screen clear) must
@@ -566,32 +669,10 @@ export function connectPanePty(
       deps.updateTabPtyId(deps.tabId, ptyId)
 
       // Why: mobile terminal streaming needs the exact screen state from
-      // xterm.js. Register a serializer for this ptyId so the main process
-      // can request a buffer snapshot when a mobile client subscribes.
-      const unregisterSerializer = registerPtySerializer(ptyId, async () => {
-        try {
-          const pending = deps.pendingWritesRef.current.get(pane.id)
-          if (pending) {
-            deps.pendingWritesRef.current.set(pane.id, '')
-            // Why: hidden/background panes buffer PTY output instead of writing
-            // to xterm. Mobile snapshots must include that pending output, and
-            // replay guard prevents xterm query auto-replies from hitting stdin.
-            await replayIntoTerminalAsync(pane, deps.replayingPanesRef, pending)
-          }
-          return {
-            data: pane.serializeAddon.serialize(),
-            cols: pane.terminal.cols,
-            rows: pane.terminal.rows
-          }
-        } catch {
-          return null
-        }
-      })
-      const origOnDataDisposableDispose = onDataDisposable.dispose.bind(onDataDisposable)
-      onDataDisposable.dispose = () => {
-        unregisterSerializer()
-        origOnDataDisposableDispose()
-      }
+      // xterm.js. The shared helper installs both the SerializeAddon-backed
+      // serializer and the onTitleChange-driven lastTitle source so the
+      // main-process hydration path has full status parity.
+      registerPaneSerializerFor(ptyId)
 
       if (connectResult?.coldRestore) {
         // Why: restoreScrollbackBuffers() already wrote the saved xterm
@@ -683,6 +764,74 @@ export function connectPanePty(
       )
       if (pendingSessionId || isDeferredTarget) {
         void (async () => {
+          // Why: if the target requires a passphrase/password and no credential
+          // is cached yet, auto-firing ssh.connect would surprise the user —
+          // a prompt pops unprompted just because they focused a tab / jumped
+          // via Cmd+J. Wait for the user to initiate the connect (via
+          // SshDisconnectedDialog → passphrase dialog) before proceeding with
+          // the PTY reattach. No-passphrase targets (ssh-agent, unencrypted
+          // key, cached creds) return false here and continue auto-connecting
+          // as before.
+          let needsPrompt = false
+          try {
+            needsPrompt = await window.api.ssh.needsPassphrasePrompt({
+              targetId: connectionId
+            })
+          } catch (err) {
+            console.warn('[pty-connection] needsPassphrasePrompt probe failed:', err)
+            // Why: if the probe fails, fall through to the existing auto-connect
+            // behavior rather than stranding the tab — a stuck tab is worse
+            // than a surprising prompt.
+          }
+          if (disposed) {
+            return
+          }
+          if (needsPrompt) {
+            const alreadyConnected =
+              useAppStore.getState().sshConnectionStates.get(connectionId)?.status === 'connected'
+            if (!alreadyConnected) {
+              // Wait for the user-driven connect (SshDisconnectedDialog →
+              // passphrase dialog → ssh.connect) to complete, then continue.
+              // Why: resolve on terminal-failure statuses too ('auth-failed',
+              // 'error', 'reconnection-failed') so this promise can't hang
+              // forever if the user cancels or the connect fails —
+              // waitForSshConnection below has its own error path that will
+              // surface the failure via reportError.
+              await new Promise<void>((resolve) => {
+                const isTerminalStatus = (status: string | undefined): boolean =>
+                  status === 'connected' ||
+                  status === 'auth-failed' ||
+                  status === 'error' ||
+                  status === 'reconnection-failed'
+                const unsub = useAppStore.subscribe((state) => {
+                  if (disposed) {
+                    unsub()
+                    resolve()
+                    return
+                  }
+                  if (isTerminalStatus(state.sshConnectionStates.get(connectionId)?.status)) {
+                    unsub()
+                    resolve()
+                  }
+                })
+                // Why: re-read state immediately after subscribing to close the
+                // race where status transitioned between the alreadyConnected
+                // check above and the subscribe registration — otherwise we'd
+                // wait forever for a state change that already happened.
+                const currentStatus = useAppStore
+                  .getState()
+                  .sshConnectionStates.get(connectionId)?.status
+                if (isTerminalStatus(currentStatus)) {
+                  unsub()
+                  resolve()
+                }
+              })
+              if (disposed) {
+                return
+              }
+            }
+          }
+
           // Why: ensure the SSH connection is established before attempting
           // PTY reattach. Multiple panes/tabs may need the same connection,
           // so we wait for it rather than returning early when in-flight.
@@ -706,6 +855,13 @@ export function connectPanePty(
             // Clear it before attach/fallback so remounts don't keep retrying
             // an expired session after a fresh shell has been created.
             useAppStore.getState().removeDeferredSshSessionId(deps.tabId)
+            // Why: pre-signal also for SSH-deferred reattach so the
+            // 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 reattachPromise = transport.connect({
               url: '',
               cols,
@@ -718,7 +874,7 @@ export function connectPanePty(
               }
             })
             void Promise.resolve(reattachPromise)
-              .then((result) => {
+              .then(async (result) => {
                 console.warn(
                   `[pty-connection] Reattach result for tab=${deps.tabId}:`,
                   result
@@ -729,8 +885,16 @@ export function connectPanePty(
                     : 'undefined'
                 )
                 handleReattachResult(result, pendingSessionId)
+                const gen = await preSignalPromise
+                if (typeof gen === 'number') {
+                  void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+                }
               })
-              .catch((err) => {
+              .catch(async (err) => {
+                const gen = await preSignalPromise
+                if (typeof gen === 'number') {
+                  void window.api.pty.clearPendingPaneSerializer(cacheKey, gen).catch(() => {})
+                }
                 console.warn(`[pty-connection] Reattach FAILED for tab=${deps.tabId}:`, err)
                 if (disposed) {
                   return
@@ -792,6 +956,18 @@ export function connectPanePty(
         `pane=${pane.id} → REATTACH`
       )
 
+      // Why: reattach also pre-signals so the cooperation gate suppresses
+      // the daemon seed for this paneKey. Reattach paths register their
+      // serializer in handleReattachResult (via registerPaneSerializerFor),
+      // mirroring the fresh-spawn path. We issue declare and the reattach
+      // connect back-to-back without awaiting; Electron's ipcRenderer→ipcMain
+      // 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 reattachPromise = transport.connect({
         url: '',
         cols,
@@ -805,10 +981,18 @@ export function connectPanePty(
       })
 
       void Promise.resolve(reattachPromise)
-        .then((result) => {
+        .then(async (result) => {
           handleReattachResult(result, deferredReattachSessionId)
+          const gen = await preSignalPromise
+          if (typeof gen === 'number') {
+            void window.api.pty.settlePaneSerializer(cacheKey, gen).catch(() => {})
+          }
         })
-        .catch((err) => {
+        .catch(async (err) => {
+          const gen = await preSignalPromise
+          if (typeof gen === 'number') {
+            void window.api.pty.clearPendingPaneSerializer(cacheKey, gen).catch(() => {})
+          }
           const message = err instanceof Error ? err.message : String(err)
           warnTerminalLifecycleAnomaly('restored PTY reattach threw', {
             tabId: deps.tabId,
diff --git a/src/renderer/src/components/terminal-pane/pty-dispatcher.ts b/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
index ba2aaa0eff3..d118fee70ce 100644
--- a/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
+++ b/src/renderer/src/components/terminal-pane/pty-dispatcher.ts
@@ -6,6 +6,7 @@
  * and the eager-buffer reconnection logic share.
  */
 import type { ParsedAgentStatusPayload } from '../../../../shared/agent-status-types'
+import type { EventProps } from '../../../../shared/telemetry-events'
 
 // ── Singleton PTY event dispatcher ───────────────────────────────────
 // One global IPC listener per channel, routes events to transports by
@@ -13,6 +14,36 @@ import type { ParsedAgentStatusPayload } from '../../../../shared/agent-status-t
 // MaxListenersExceededWarning with many panes/tabs.
 
 export const ptyDataHandlers = new Map<string, (data: string) => void>()
+/** Sidecar subscriptions that observe PTY data without owning the primary
+ *  handler. Used by features that need to react to the live byte stream
+ *  (e.g. agent-paste-draft watching for DECSET 2004 / bracketed-paste-
+ *  enable). Sidecars are invoked AFTER the primary handler so xterm rendering
+ *  is never delayed by a side-effect-only watcher. Each Set entry is one
+ *  active subscription; removal is by Set.delete inside the unsubscribe fn. */
+export const ptyDataSidecars = new Map<string, Set<(data: string) => void>>()
+
+/** Register a side-channel data watcher for a PTY without taking ownership
+ *  of the primary handler. Returns an unsubscribe fn. ensurePtyDispatcher()
+ *  is called automatically so the underlying IPC stream is wired up. */
+export function subscribeToPtyData(ptyId: string, watcher: (data: string) => void): () => void {
+  ensurePtyDispatcher()
+  let set = ptyDataSidecars.get(ptyId)
+  if (!set) {
+    set = new Set()
+    ptyDataSidecars.set(ptyId, set)
+  }
+  set.add(watcher)
+  return () => {
+    const current = ptyDataSidecars.get(ptyId)
+    if (!current) {
+      return
+    }
+    current.delete(watcher)
+    if (current.size === 0) {
+      ptyDataSidecars.delete(ptyId)
+    }
+  }
+}
 /** Per-PTY replay handlers for relay pty.attach replay data. Routed through
  *  a dedicated pty:replay IPC channel so the renderer can engage the replay
  *  guard and suppress xterm auto-replies during replay. */
@@ -50,6 +81,20 @@ export function ensurePtyDispatcher(): void {
   ptyDispatcherAttached = true
   window.api.pty.onData((payload) => {
     ptyDataHandlers.get(payload.id)?.(payload.data)
+    const sidecars = ptyDataSidecars.get(payload.id)
+    if (sidecars && sidecars.size > 0) {
+      // Why: snapshot the Set before iterating because watchers commonly
+      // unsubscribe themselves on the very chunk that satisfies them
+      // (e.g. agent-paste-draft resolves on DECSET 2004 and immediately
+      // tears down). Iterating the live Set in that case can skip a
+      // watcher or — if a watcher synchronously subscribes a sibling —
+      // double-fire. The Set is never large (one watcher per active
+      // ready-wait), so the array allocation is cheap.
+      const snapshot = Array.from(sidecars)
+      for (const watcher of snapshot) {
+        watcher(payload.data)
+      }
+    }
   })
   window.api.pty.onReplay((payload) => {
     ptyReplayHandlers.get(payload.id)?.(payload.data)
@@ -211,8 +256,19 @@ export type IpcPtyTransportOptions = {
   connectionId?: string | null
   /** Orca worktree identity for scoped shell history. */
   worktreeId?: string
+  /** Why: closes the SIGKILL race documented in INVESTIGATION.md by letting
+   *  main patch + sync-flush the (worktreeId, tabId, leafId → ptyId) binding
+   *  before pty:spawn returns. Only the renderer's daemon-host path threads
+   *  these from the calling pane's (tabId, leafId). */
+  tabId?: string
+  leafId?: string
   /** Why: mirrors PtySpawnOptions.shellOverride — see types.ts for rationale. */
   shellOverride?: string
+  /** Telemetry metadata for the `agent_started` event. Forwarded verbatim
+   *  to `pty:spawn` so main can fire the event after confirmed launch. The
+   *  IPC handler re-validates the schema; this type is the renderer-side
+   *  contract. */
+  telemetry?: EventProps<'agent_started'>
   onPtyExit?: (ptyId: string) => void
   onTitleChange?: (title: string, rawTitle: string) => void
   onPtySpawn?: (ptyId: string) => void
diff --git a/src/renderer/src/components/terminal-pane/pty-transport.ts b/src/renderer/src/components/terminal-pane/pty-transport.ts
index f8cb7f7f233..4ad85c0d9fd 100644
--- a/src/renderer/src/components/terminal-pane/pty-transport.ts
+++ b/src/renderer/src/components/terminal-pane/pty-transport.ts
@@ -149,7 +149,10 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
     command,
     connectionId,
     worktreeId,
+    tabId,
+    leafId,
     shellOverride,
+    telemetry,
     onPtyExit,
     onTitleChange,
     onPtySpawn,
@@ -353,7 +356,10 @@ export function createIpcPtyTransport(opts: IpcPtyTransportOptions = {}): PtyTra
           ...(connectionId ? { connectionId } : {}),
           ...(options.sessionId ? { sessionId: options.sessionId } : {}),
           worktreeId,
-          ...(shellOverride ? { shellOverride } : {})
+          ...(tabId ? { tabId } : {}),
+          ...(leafId ? { leafId } : {}),
+          ...(shellOverride ? { shellOverride } : {}),
+          ...(telemetry ? { telemetry } : {})
         })
         const spawnResult = result as PtyConnectResult & { isReattach?: boolean }
 
diff --git a/src/renderer/src/components/terminal-pane/shutdown-buffer-captures.ts b/src/renderer/src/components/terminal-pane/shutdown-buffer-captures.ts
new file mode 100644
index 00000000000..67c54e937b4
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/shutdown-buffer-captures.ts
@@ -0,0 +1,15 @@
+/** Map of tabId → buffer-capture callback, one per mounted TerminalPane.
+ *  The beforeunload handler in App.tsx invokes every callback to populate
+ *  Zustand with serialized buffers before flushing the session to disk.
+ *  Sleep (shutdownWorktreeTerminals with keepIdentifiers: true) iterates
+ *  only the entries whose tabId belongs to the worktree being slept, so
+ *  SSH worktrees can capture scrollback before the relay SIGKILLs the
+ *  remote PTY — see DESIGN_DOC_TERMINAL_HISTORY_FIX_V2.md §3.3.c.
+ *
+ *  Why this lives in its own module: the registry is shared between
+ *  TerminalPane.tsx (registration site) and the terminals store slice
+ *  (sleep-time iteration). Importing it directly from TerminalPane would
+ *  create a cycle (slice → TerminalPane → store → slice) that breaks the
+ *  Zustand store at module-init time. A leaf module with zero imports
+ *  has no cycle. */
+export const shutdownBufferCaptures = new Map<string, () => void>()
diff --git a/src/renderer/src/components/terminal-pane/use-notification-dispatch.ts b/src/renderer/src/components/terminal-pane/use-notification-dispatch.ts
index c04539e5386..54fd5556c8b 100644
--- a/src/renderer/src/components/terminal-pane/use-notification-dispatch.ts
+++ b/src/renderer/src/components/terminal-pane/use-notification-dispatch.ts
@@ -1,6 +1,7 @@
 import { useCallback } from 'react'
 import { useAppStore } from '@/store'
 import { getRepoMapFromState, getWorktreeMapFromState } from '@/store/selectors'
+import { playDesktopNotificationSound } from '@/lib/desktop-notification-sound'
 
 /**
  * Returns a stable dispatch function for terminal notifications.
@@ -36,15 +37,25 @@ export function useNotificationDispatch(
       // itself is the source of truth for its owning repo.
       const worktree = getWorktreeMapFromState(state).get(worktreeId)
       const repo = worktree ? getRepoMapFromState(state).get(worktree.repoId) : null
+      const customSoundPath = state.settings?.notifications?.customSoundPath ?? null
 
-      void window.api.notifications.dispatch({
-        source: event.source,
-        worktreeId,
-        repoLabel: repo?.displayName,
-        worktreeLabel: worktree?.displayName || worktree?.branch || worktreeId,
-        terminalTitle: event.terminalTitle,
-        isActiveWorktree: state.activeWorktreeId === worktreeId
-      })
+      void window.api.notifications
+        .dispatch({
+          source: event.source,
+          worktreeId,
+          repoLabel: repo?.displayName,
+          worktreeLabel: worktree?.displayName || worktree?.branch || worktreeId,
+          terminalTitle: event.terminalTitle,
+          isActiveWorktree: state.activeWorktreeId === worktreeId
+        })
+        .then((result) => {
+          if (result.delivered) {
+            void playDesktopNotificationSound(customSoundPath)
+          }
+        })
+        .catch((err) => {
+          console.warn('Failed to dispatch notification:', err)
+        })
     },
     [worktreeId]
   )
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 f045bc12643..c60facc8012 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
@@ -15,6 +15,7 @@ import type {
   SetupSplitDirection,
   TerminalLayoutSnapshot
 } from '../../../../shared/types'
+import type { EventProps } from '../../../../shared/telemetry-events'
 import { resolveTerminalFontWeights } from '../../../../shared/terminal-fonts'
 import {
   buildFontFamily,
@@ -52,7 +53,13 @@ type UseTerminalPaneLifecycleDeps = {
   tabId: string
   worktreeId: string
   cwd?: string
-  startup?: { command: string; env?: Record<string, string> } | null
+  startup?: {
+    command: string
+    env?: Record<string, string>
+    /** Telemetry payload for `agent_started`. Forwarded to `pty:spawn`
+     *  so main fires the event only after the spawn succeeds. */
+    telemetry?: EventProps<'agent_started'>
+  } | null
   /** When present, the initial pane boots clean and a split pane is created
    *  (vertical or horizontal per the user setting) to run the setup command —
    *  keeping the main terminal interactive. */
diff --git a/src/renderer/src/hooks/useAutoAckViewedAgent.test.ts b/src/renderer/src/hooks/useAutoAckViewedAgent.test.ts
new file mode 100644
index 00000000000..ee92d729a0f
--- /dev/null
+++ b/src/renderer/src/hooks/useAutoAckViewedAgent.test.ts
@@ -0,0 +1,175 @@
+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'
+
+// Why: regression coverage for the codex inline-agent row that stayed bold
+// after returning from another workspace (docs/codex-agent-row-bold-stuck.md).
+// The race: codex emits `Stop` (state=done), then its TUI title reverts to a
+// shell label; pty-connection.ts:onAgentExited fires removeAgentStatus before
+// the live `done` row could be auto-acked. The retention sync snapshots the
+// `done` row into retainedAgentsByPaneKey carrying a fresh stateStartedAt.
+// Pre-fix: useAutoAckViewedAgent only walked the live map, so the retained
+// row's stateStartedAt > ackAt forever. Fix: walk both maps.
+//
+// We test the pure helper (computeAutoAckTargets) rather than the hook so the
+// vitest 'node' environment doesn't need to mock document.visibilityState,
+// document.hasFocus, or the focus/visibilitychange event surface. The hook's
+// gate logic is unchanged by this fix — only the scan body was extended.
+
+describe('computeAutoAckTargets — codex retain race regression', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('acks a paneKey whose live row was retained mid-frame', () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-05-05T12:00:00.000Z'))
+    const store = createTestStore()
+    const paneKey = 'tab-codex:2'
+    const activeTabId = 'tab-codex'
+
+    // 1. Codex starts working, user acks it (e.g. by clicking the row).
+    store.getState().setAgentStatus(paneKey, {
+      state: 'working',
+      prompt: 'sleep 10 then say hi',
+      agentType: 'codex'
+    })
+    store.getState().acknowledgeAgents([paneKey])
+    const workingAck = store.getState().acknowledgedAgentsByPaneKey[paneKey]
+    expect(workingAck).toBeGreaterThan(0)
+
+    // 2. Time advances; codex Stop fires → state=done with a fresh
+    //    stateStartedAt (carry-forward only applies within the same state).
+    vi.setSystemTime(new Date('2026-05-05T12:00:10.000Z'))
+    store.getState().setAgentStatus(paneKey, {
+      state: 'done',
+      prompt: 'sleep 10 then say hi',
+      agentType: 'codex'
+    })
+    const liveDone = store.getState().agentStatusByPaneKey[paneKey]
+    expect(liveDone.stateStartedAt).toBeGreaterThan(workingAck)
+
+    // 3. The codex TUI title reverts to a plain shell label, so
+    //    onAgentExited → removeAgentStatus tears down the live entry AND
+    //    wipes the prior ack (per agent-status.ts cleanup contract).
+    const retentionSnapshot: RetainedAgentEntry = {
+      entry: liveDone,
+      worktreeId: 'wt-1',
+      tab: makeTab({ id: activeTabId, worktreeId: 'wt-1' }),
+      agentType: 'codex',
+      startedAt: liveDone.stateStartedAt
+    }
+    store.getState().removeAgentStatus(paneKey)
+    expect(store.getState().agentStatusByPaneKey[paneKey]).toBeUndefined()
+    expect(store.getState().acknowledgedAgentsByPaneKey[paneKey]).toBeUndefined()
+
+    // 4. The retention sync picks up the live→gone transition and stashes a
+    //    snapshot with the post-Stop stateStartedAt — same as
+    //    collectRetainedAgentsOnDisappear in useRetainedAgents.ts.
+    store.getState().retainAgents([retentionSnapshot])
+    expect(store.getState().retainedAgentsByPaneKey[paneKey]).toBeDefined()
+
+    // 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)
+    expect(targets).toEqual([paneKey])
+  })
+
+  it('returns no targets once the retained row has been acked', () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-05-05T12:00:00.000Z'))
+    const store = createTestStore()
+    const paneKey = 'tab-codex:2'
+    const activeTabId = 'tab-codex'
+
+    store.getState().setAgentStatus(paneKey, {
+      state: 'done',
+      prompt: 'p',
+      agentType: 'codex'
+    })
+    const doneEntry = store.getState().agentStatusByPaneKey[paneKey]
+    store.getState().retainAgents([
+      {
+        entry: doneEntry,
+        worktreeId: 'wt-1',
+        tab: makeTab({ id: activeTabId, worktreeId: 'wt-1' }),
+        agentType: 'codex',
+        startedAt: doneEntry.stateStartedAt
+      }
+    ])
+    store.getState().removeAgentStatus(paneKey)
+
+    // First scan: the retained row is unvisited.
+    expect(computeAutoAckTargets(store.getState(), activeTabId)).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([])
+  })
+
+  it('skips retained rows whose paneKey is on a different tab', () => {
+    const store = createTestStore()
+    const paneKey = 'tab-other:0'
+    store.getState().setAgentStatus(paneKey, {
+      state: 'done',
+      prompt: 'p',
+      agentType: 'codex'
+    })
+    const entry = store.getState().agentStatusByPaneKey[paneKey]
+    store.getState().retainAgents([
+      {
+        entry,
+        worktreeId: 'wt-1',
+        tab: makeTab({ id: 'tab-other', worktreeId: 'wt-1' }),
+        agentType: 'codex',
+        startedAt: entry.stateStartedAt
+      }
+    ])
+    store.getState().removeAgentStatus(paneKey)
+
+    // 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([])
+  })
+
+  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'
+
+    // Construct a (rare) state where retainedAgentsByPaneKey and
+    // agentStatusByPaneKey both contain the same paneKey — e.g. the
+    // retention sync hadn't observed the new live entry yet. The merged
+    // scan should report the paneKey at most twice (acknowledgeAgents
+    // collapses duplicates), never throw.
+    store.getState().setAgentStatus(paneKey, {
+      state: 'done',
+      prompt: 'p1',
+      agentType: 'codex'
+    })
+    const liveDone = store.getState().agentStatusByPaneKey[paneKey]
+    store.getState().retainAgents([
+      {
+        entry: liveDone,
+        worktreeId: 'wt-1',
+        tab: makeTab({ id: activeTabId, worktreeId: 'wt-1' }),
+        agentType: 'codex',
+        startedAt: liveDone.stateStartedAt
+      }
+    ])
+
+    const targets = computeAutoAckTargets(store.getState(), activeTabId)
+    // Two pushes, same paneKey — duplicates are intentional and harmless;
+    // acknowledgeAgents short-circuits per key.
+    expect(targets.length).toBeLessThanOrEqual(2)
+    expect(targets.every((k) => k === paneKey)).toBe(true)
+    expect(targets.includes(paneKey)).toBe(true)
+  })
+})
diff --git a/src/renderer/src/hooks/useAutoAckViewedAgent.ts b/src/renderer/src/hooks/useAutoAckViewedAgent.ts
index 3fe4d68edcf..a1d5062f4a6 100644
--- a/src/renderer/src/hooks/useAutoAckViewedAgent.ts
+++ b/src/renderer/src/hooks/useAutoAckViewedAgent.ts
@@ -1,5 +1,52 @@
 import { useEffect } from 'react'
 import { useAppStore } from '@/store'
+import type { AgentStatusEntry } from '../../../shared/agent-status-types'
+import type { RetainedAgentEntry } from '@/store/slices/agent-status'
+
+/**
+ * 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.
+ */
+export function computeAutoAckTargets(
+  state: {
+    agentStatusByPaneKey: Record<string, AgentStatusEntry>
+    retainedAgentsByPaneKey: Record<string, RetainedAgentEntry>
+    acknowledgedAgentsByPaneKey: Record<string, number>
+  },
+  activeTabId: string
+): string[] {
+  const prefix = `${activeTabId}:`
+  const targets: string[] = []
+  for (const [paneKey, entry] of Object.entries(state.agentStatusByPaneKey)) {
+    if (!paneKey.startsWith(prefix)) {
+      continue
+    }
+    const ackAt = state.acknowledgedAgentsByPaneKey[paneKey] ?? 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)
+    }
+  }
+  for (const [paneKey, retained] of Object.entries(state.retainedAgentsByPaneKey)) {
+    if (!paneKey.startsWith(prefix)) {
+      continue
+    }
+    const ackAt = state.acknowledgedAgentsByPaneKey[paneKey] ?? 0
+    if (ackAt < retained.entry.stateStartedAt) {
+      targets.push(paneKey)
+    }
+  }
+  return targets
+}
 
 // Why: an agent row counts as "already seen" when the user is actually looking
 // at the tab it lives on. Without this effect, ack only fires via an explicit
@@ -10,16 +57,26 @@ import { useAppStore } from '@/store'
 // The effect subscribes directly to the store (not via React selectors) so it
 // sees every state change with no re-render amplification up the component
 // tree. A reference-equality guard inside the callback bails out immediately
-// when none of the five slices we care about (activeView, activeTabId,
-// agentStatusByPaneKey, acknowledgedAgentsByPaneKey, settings) have changed —
-// so the Object.entries walk only runs for updates that could legitimately
-// affect the ack decision.
+// when none of the six slices we care about (activeView, activeTabId,
+// agentStatusByPaneKey, retainedAgentsByPaneKey, acknowledgedAgentsByPaneKey,
+// settings) have changed — so the Object.entries walk only runs for updates
+// that could legitimately affect the ack decision.
 //
 // It acks whenever:
 //   - activeView is 'terminal' (the user isn't on Settings/Tasks), AND
 //   - activeTabId identifies a live tab, AND
-//   - at least one agentStatusByPaneKey entry has paneKey prefixed by
-//     `${activeTabId}:` AND its ackAt < stateStartedAt.
+//   - at least one agentStatusByPaneKey entry OR retainedAgentsByPaneKey
+//     entry has paneKey prefixed by `${activeTabId}:` AND its
+//     ackAt < stateStartedAt.
+//
+// Why both maps: the inline-agents list renders the union of live + retained
+// rows (see useWorktreeAgentRows), so the ack scan must too. Without the
+// retained walk, a `done` row whose live entry was torn down by the
+// title-revert path (see pty-connection.ts:onAgentExited) migrates to the
+// retained map carrying a fresh `done.stateStartedAt` and never gets
+// auto-acked — leaving the inline row bold forever even while the user
+// stares at the terminal. Codex hits this race reliably because its TUI
+// reverts to a shell title within milliseconds of `Stop`.
 //
 // The ack ALSO requires the OS window to be visible and focused
 // (document.visibilityState === 'visible' && document.hasFocus()) —
@@ -43,6 +100,7 @@ export function useAutoAckViewedAgent(): void {
     let lastActiveView: unknown = undefined
     let lastActiveTabId: unknown = undefined
     let lastAgentStatus: unknown = undefined
+    let lastRetained: unknown = undefined
     let lastAcknowledged: unknown = undefined
     // Why: settings is tracked so flipping `experimentalAgentDashboard`
     // alone re-evaluates the feature gate below — without this, a pure
@@ -59,6 +117,7 @@ export function useAutoAckViewedAgent(): void {
         s.activeView === lastActiveView &&
         s.activeTabId === lastActiveTabId &&
         s.agentStatusByPaneKey === lastAgentStatus &&
+        s.retainedAgentsByPaneKey === lastRetained &&
         s.acknowledgedAgentsByPaneKey === lastAcknowledged &&
         s.settings === lastSettings
       ) {
@@ -107,26 +166,10 @@ export function useAutoAckViewedAgent(): void {
       lastActiveView = s.activeView
       lastActiveTabId = s.activeTabId
       lastAgentStatus = s.agentStatusByPaneKey
+      lastRetained = s.retainedAgentsByPaneKey
       lastAcknowledged = s.acknowledgedAgentsByPaneKey
       lastSettings = s.settings
-      const prefix = `${activeTabId}:`
-      const toAck: string[] = []
-      for (const [paneKey, entry] of Object.entries(s.agentStatusByPaneKey)) {
-        if (!paneKey.startsWith(prefix)) {
-          continue
-        }
-        const ackAt = s.acknowledgedAgentsByPaneKey[paneKey] ?? 0
-        // Why: use stateStartedAt (not updatedAt) so tool/prompt pings
-        // within the same state don't re-trigger ack work on every event —
-        // acknowledgeAgents short-circuits anyway when the value is
-        // unchanged, but keeping the comparison in sync with the
-        // "is-unvisited" rule in WorktreeCardAgents avoids a stutter
-        // where we ack on an updatedAt-bump that didn't cross a state
-        // transition.
-        if (ackAt < entry.stateStartedAt) {
-          toAck.push(paneKey)
-        }
-      }
+      const toAck = computeAutoAckTargets(s, activeTabId)
       if (toAck.length > 0) {
         s.acknowledgeAgents(toAck)
       }
@@ -137,7 +180,7 @@ export function useAutoAckViewedAgent(): void {
     // Why: store.subscribe fires on every state change. The reference-
     // equality guard above bails out immediately for the common case
     // (terminal output, timers, etc.) so the Object.entries walk only runs
-    // when one of the five slices we read has actually changed.
+    // when one of the six slices we read has actually changed.
     const unsubscribe = useAppStore.subscribe(maybeAck)
     // Why: focus/visibility don't flow through the zustand store, so a
     // late-arriving transition that failed the gate above never re-evaluates
diff --git a/src/renderer/src/hooks/useComposerState.ts b/src/renderer/src/hooks/useComposerState.ts
index 3f38a873122..d571a72dd4d 100644
--- a/src/renderer/src/hooks/useComposerState.ts
+++ b/src/renderer/src/hooks/useComposerState.ts
@@ -7,17 +7,25 @@ import { toast } from 'sonner'
 import { useShallow } from 'zustand/react/shallow'
 import { useAppStore } from '@/store'
 import { AGENT_CATALOG } from '@/lib/agent-catalog'
-import { parseGitHubIssueOrPRNumber, normalizeGitHubLinkQuery } from '@/lib/github-links'
-import { activateAndRevealWorktree } from '@/lib/worktree-activation'
-import { buildAgentStartupPlan } from '@/lib/tui-agent-startup'
+import {
+  parseGitHubIssueOrPRNumber,
+  parseGitHubIssueOrPRLink,
+  normalizeGitHubLinkQuery
+} from '@/lib/github-links'
+import { activateAndRevealWorktree, type AgentStartedTelemetry } from '@/lib/worktree-activation'
+import { buildAgentDraftLaunchPlan, buildAgentStartupPlan } from '@/lib/tui-agent-startup'
+import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
+import { tuiAgentToAgentKind } from '@/lib/telemetry'
 import { isGitRepoKind } from '../../../shared/repo-kind'
 import type {
   GitHubWorkItem,
+  LinearIssue,
   OrcaHooks,
   SetupDecision,
   SetupRunPolicy,
   SparsePreset,
-  TuiAgent
+  TuiAgent,
+  WorkspaceCreateTelemetrySource
 } from '../../../shared/types'
 import {
   ADD_ATTACHMENT_SHORTCUT,
@@ -35,6 +43,7 @@ import {
   type LinkedWorkItemSummary
 } from '@/lib/new-workspace'
 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'
 
@@ -58,6 +67,12 @@ export type UseComposerStateOptions = {
    *  which drives repo selection from the page header, not the card. */
   repoIdOverride?: string
   onRepoIdOverrideChange?: (value: string) => void
+  /** Telemetry surface that opened this composer. Threaded into
+   *  `createWorktree` so `workspace_created.source` reflects the actual
+   *  entry point (Cmd+J palette → `command_palette`, sidebar buttons →
+   *  `sidebar`, keyboard shortcut → `shortcut`). Omitted callers default
+   *  to `unknown` at the IPC boundary. */
+  telemetrySource?: WorkspaceCreateTelemetrySource
 }
 
 export type ComposerCardProps = {
@@ -65,7 +80,12 @@ export type ComposerCardProps = {
   repoId: string
   onRepoChange: (value: string) => void
   name: string
-  onNameChange: (event: React.ChangeEvent<HTMLInputElement>) => void
+  onNameValueChange: (value: string) => void
+  onSmartGitHubItemSelect: (item: GitHubWorkItem) => void
+  onSmartBranchSelect: (refName: string) => void
+  onSmartLinearIssueSelect: (issue: LinearIssue) => void
+  smartNameSelection: SmartWorkspaceNameSelection | null
+  onClearSmartNameSelection: () => void
   agentPrompt: string
   onAgentPromptChange: (value: string) => void
   onPromptKeyDown: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void
@@ -163,7 +183,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     persistDraft,
     onCreated,
     repoIdOverride,
-    onRepoIdOverrideChange
+    onRepoIdOverrideChange,
+    telemetrySource
   } = options
 
   // Why: each `useAppStore(s => s.someAction)` registers its own equality
@@ -346,6 +367,43 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
   agentPromptRef.current = agentPrompt
 
   const selectedRepo = eligibleRepos.find((repo) => repo.id === repoId)
+
+  // Why: resolves the selected repo's owner/repo slug so a PR URL pasted
+  // into the workspace name field can be matched against the current repo.
+  // Pasting a PR URL from a different repo would otherwise recover only the
+  // PR number, mislinking the worktree to an unrelated PR with the same
+  // number in the selected repo.
+  const [selectedRepoSlug, setSelectedRepoSlug] = useState<{ owner: string; repo: string } | null>(
+    null
+  )
+  const selectedRepoPath = selectedRepo?.path
+  useEffect(() => {
+    if (!selectedRepoPath) {
+      setSelectedRepoSlug(null)
+      return
+    }
+    let cancelled = false
+    void (
+      window.api.gh.repoSlug({ repoPath: selectedRepoPath }) as Promise<{
+        owner: string
+        repo: string
+      } | null>
+    )
+      .then((result) => {
+        if (cancelled) {
+          return
+        }
+        setSelectedRepoSlug(result)
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setSelectedRepoSlug(null)
+        }
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [selectedRepoPath])
   const sparsePresetsForRepo = sparsePresetsByRepo[repoId]
   const sparsePresets = sparsePresetsForRepo ?? EMPTY_SPARSE_PRESETS
   const normalizedSparseDirectories = useMemo(
@@ -390,6 +448,31 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     () => (linkedIssue.trim() ? parseGitHubIssueOrPRNumber(linkedIssue) : null),
     [linkedIssue]
   )
+  // Why: when the user pastes a PR URL straight into the workspace name field
+  // (without picking from the source picker), `linkedPR` stays null and the
+  // worktree card has no PR strip. Recover the PR number from the name on
+  // submit so create-from-PR worktrees always link back to their PR.
+  const effectiveLinkedPR = useMemo<number | null>(() => {
+    if (linkedPR !== null) {
+      return linkedPR
+    }
+    const fromName = parseGitHubIssueOrPRLink(name)
+    if (fromName && fromName.type === 'pr') {
+      // Why: only adopt a number when the URL's owner/repo matches the
+      // selected repo. Pasting `github.com/other/repo/pull/1234` must not
+      // mislink the worktree to an unrelated PR #1234 in the current repo.
+      // If the slug hasn't resolved yet, suppress recovery rather than
+      // risking a cross-repo mislink.
+      if (
+        selectedRepoSlug &&
+        fromName.slug.owner.toLowerCase() === selectedRepoSlug.owner.toLowerCase() &&
+        fromName.slug.repo.toLowerCase() === selectedRepoSlug.repo.toLowerCase()
+      ) {
+        return fromName.number
+      }
+    }
+    return null
+  }, [linkedPR, name, selectedRepoSlug])
   const setupConfig = useMemo(
     () => getSetupConfig(selectedRepo, yamlHooks),
     [selectedRepo, yamlHooks]
@@ -675,8 +758,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
           // discriminant, so the union-preserving shape must be asserted.
           // Why: the link popover intentionally does NOT surface
           // `envelope.errors?.issues`. Per-surface error copy lives in the
-          // Tasks view (TaskPage) and the new-workspace Create tab
-          // (CreateFromTab) — a partial-failure banner inside the small
+          // Tasks view (TaskPage) and the smart workspace-name field — a
+          // partial-failure banner inside the small
           // @-mention popover would crowd the input and the user would
           // already see the same error on the originating Tasks page. If a
           // future UX decision flips this, add an error row to the popover's
@@ -807,9 +890,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     }
   }, [name])
 
-  const handleNameChange = useCallback(
-    (event: React.ChangeEvent<HTMLInputElement>): void => {
-      const nextName = event.target.value
+  const handleNameValueChange = useCallback(
+    (nextName: string): void => {
       // Why: linked GitHub items should keep refreshing the suggested workspace
       // name only while the current value is still auto-managed. As soon as the
       // user edits the field by hand, later issue/PR selections must stop
@@ -824,7 +906,6 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     },
     [name]
   )
-
   const handleAddAttachment = useCallback(async (): Promise<void> => {
     try {
       const selectedPath = await window.api.shell.pickAttachment()
@@ -1042,6 +1123,119 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     [applyLinkedWorkItem]
   )
 
+  const handleSmartGitHubItemSelect = useCallback(
+    (item: GitHubWorkItem): void => {
+      applyLinkedWorkItem(item)
+      setStartFromResetHint(null)
+      const repoForItem = eligibleRepos.find((repo) => repo.id === item.repoId) ?? selectedRepo
+      if (item.type !== 'pr' || !repoForItem) {
+        return
+      }
+      void window.api.worktrees
+        .resolvePrBase({
+          repoId: repoForItem.id,
+          prNumber: item.number,
+          ...(item.branchName ? { headRefName: item.branchName } : {}),
+          ...(item.isCrossRepository !== undefined
+            ? { isCrossRepository: item.isCrossRepository }
+            : {})
+        })
+        .then((result) => {
+          if ('error' in result) {
+            return
+          }
+          handleBaseBranchPrSelect(result.baseBranch, item)
+        })
+    },
+    [applyLinkedWorkItem, eligibleRepos, handleBaseBranchPrSelect, selectedRepo]
+  )
+
+  const handleSmartBranchSelect = useCallback(
+    (refName: string): void => {
+      setBaseBranch(refName)
+      setStartFromResetHint(null)
+      if (!name.trim() || name === lastAutoNameRef.current) {
+        setName(refName)
+        lastAutoNameRef.current = refName
+      }
+    },
+    [name]
+  )
+
+  const handleSmartLinearIssueSelect = useCallback(
+    (issue: LinearIssue): void => {
+      setLinkedIssue('')
+      setLinkedPR(null)
+      setLinkedWorkItem({
+        type: 'issue',
+        // Why: Linear identifiers are strings (e.g. ENG-123); keep GitHub
+        // numeric metadata empty and carry the real source through the URL.
+        number: 0,
+        title: issue.title,
+        url: issue.url
+      })
+      const suggestedName = issue.title
+      if (!name.trim() || name === lastAutoNameRef.current) {
+        setName(suggestedName)
+        lastAutoNameRef.current = suggestedName
+      }
+      const details = [
+        `[${issue.identifier}] ${issue.title}`,
+        `Status: ${issue.state.name} · Team: ${issue.team.name}`,
+        issue.assignee ? `Assignee: ${issue.assignee.displayName}` : null,
+        issue.labels.length > 0 ? `Labels: ${issue.labels.join(', ')}` : null,
+        `URL: ${issue.url}`,
+        issue.description ? `\n${issue.description}` : null
+      ]
+        .filter(Boolean)
+        .join('\n')
+      if (!noteRef.current.trim() || noteRef.current === lastAutoNoteRef.current) {
+        setNote(details)
+        lastAutoNoteRef.current = details
+      }
+    },
+    [name]
+  )
+
+  const handleClearSmartNameSelection = useCallback((): void => {
+    setLinkedIssue('')
+    setLinkedPR(null)
+    setLinkedWorkItem(null)
+    setBaseBranch(undefined)
+    setStartFromResetHint(null)
+    if (name === lastAutoNameRef.current) {
+      setName('')
+      lastAutoNameRef.current = ''
+    }
+    if (noteRef.current === lastAutoNoteRef.current) {
+      setNote('')
+      lastAutoNoteRef.current = ''
+    }
+  }, [name])
+
+  const smartNameSelection = useMemo<SmartWorkspaceNameSelection | null>(() => {
+    if (linkedWorkItem) {
+      const isLinear = linkedWorkItem.number === 0 && !linkedWorkItem.url.includes('github.com')
+      const kind: SmartWorkspaceNameSelection['kind'] = isLinear
+        ? 'linear'
+        : linkedWorkItem.type === 'pr'
+          ? 'github-pr'
+          : 'github-issue'
+      return {
+        kind,
+        label:
+          isLinear || linkedWorkItem.number === 0
+            ? linkedWorkItem.title
+            : `#${linkedWorkItem.number} ${linkedWorkItem.title}`,
+        url: linkedWorkItem.url
+      }
+    }
+    if (baseBranch) {
+      return { kind: 'branch', label: baseBranch }
+    }
+    return null
+  }, [baseBranch, linkedWorkItem])
+
   const handleOpenAgentSettings = useCallback((): void => {
     openSettingsTarget({ pane: 'agents', repoId: null })
     openSettingsPage()
@@ -1110,13 +1304,14 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
               directories: normalizedSparseDirectories,
               ...(effectivePresetId ? { presetId: effectivePresetId } : {})
             }
-          : undefined
+          : undefined,
+        telemetrySource
       )
       const worktree = result.worktree
 
       await applyWorktreeMeta(worktree.id, {
         ...(parsedLinkedIssueNumber !== null ? { linkedIssue: parsedLinkedIssueNumber } : {}),
-        ...(linkedPR !== null ? { linkedPR } : {}),
+        ...(effectiveLinkedPR !== null ? { linkedPR: effectiveLinkedPR } : {}),
         ...(note.trim() ? { comment: note.trim() } : {})
       })
 
@@ -1136,10 +1331,27 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
         platform: CLIENT_PLATFORM
       })
 
+      // Why: thread agent_started telemetry through the queued startup so
+      // main fires the event after the spawn succeeds. The composer
+      // "create" path is the new-workspace surface; request_kind is
+      // `'new'` because this is always a fresh session (issue/PR-driven
+      // follow-ups go through launch-work-item-direct.ts).
+      const composerTelemetry: AgentStartedTelemetry = {
+        agent_kind: tuiAgentToAgentKind(tuiAgent),
+        launch_source: 'new_workspace_composer',
+        request_kind: 'new'
+      }
       activateAndRevealWorktree(worktree.id, {
         setup: result.setup,
         issueCommand,
-        ...(startupPlan ? { startup: { command: startupPlan.launchCommand } } : {})
+        ...(startupPlan
+          ? {
+              startup: {
+                command: startupPlan.launchCommand,
+                telemetry: composerTelemetry
+              }
+            }
+          : {})
       })
       if (startupPlan) {
         void ensureAgentStartupInTerminal({
@@ -1169,7 +1381,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     createWorktree,
     applyWorktreeMeta,
     issueCommandTemplate,
-    linkedPR,
+    effectiveLinkedPR,
     linkedWorkItem?.url,
     normalizedSparseDirectories,
     note,
@@ -1189,6 +1401,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     sparseEnabled,
     sparseError,
     effectivePresetId,
+    telemetrySource,
     tuiAgent,
     shouldRunIssueAutomation,
     shouldWaitForIssueAutomationCheck,
@@ -1202,8 +1415,8 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       const workspaceName = getWorkspaceSeedName({
         explicitName: name,
         prompt: '',
-        linkedIssueNumber: null,
-        linkedPR: null,
+        linkedIssueNumber: parsedLinkedIssueNumber,
+        linkedPR,
         fallbackName: fallbackCreatureName
       })
       if (
@@ -1236,27 +1449,107 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
                 directories: normalizedSparseDirectories,
                 ...(effectivePresetId ? { presetId: effectivePresetId } : {})
               }
-            : undefined
+            : undefined,
+          telemetrySource
         )
         const worktree = result.worktree
 
         const trimmedNote = note.trim()
-        await applyWorktreeMeta(worktree.id, trimmedNote ? { comment: trimmedNote } : {})
+        await applyWorktreeMeta(worktree.id, {
+          ...(parsedLinkedIssueNumber !== null ? { linkedIssue: parsedLinkedIssueNumber } : {}),
+          ...(effectiveLinkedPR !== null ? { linkedPR: effectiveLinkedPR } : {}),
+          ...(trimmedNote ? { comment: trimmedNote } : {})
+        })
 
-        const startupPlan =
-          agent === null
+        // Why: when a linked work item is selected in the quick flow, launch
+        // the agent with a blank prompt and type the URL into its input as a
+        // draft (no trailing Enter). This lets the user review/edit before
+        // sending instead of auto-executing a "Complete <url>" template.
+        // Falls back to the trimmed note when the linked item carries no
+        // number/URL (Linear typed-only entries).
+        const isLinearTypedOnly = linkedWorkItem?.number === 0 && Boolean(trimmedNote)
+        const quickPrompt = isLinearTypedOnly && trimmedNote ? trimmedNote : ''
+        const quickDraftPrompt = linkedWorkItem && !isLinearTypedOnly ? linkedWorkItem.url : null
+
+        // Why: agents that gate first-launch behind a "Do you trust this
+        // folder?" menu (cursor-agent, copilot) consume the bracketed paste
+        // as menu input. Pre-write the trust artifact so the menu is
+        // skipped — best-effort, errors swallowed by main. Guard the IPC
+        // presence so a stale preload bundle doesn't crash the launch with
+        // "Cannot read properties of undefined".
+        if (agent && worktree.path && window.api.agentTrust?.markTrusted) {
+          const preflight = TUI_AGENT_CONFIG[agent].preflightTrust
+          if (preflight) {
+            try {
+              await window.api.agentTrust.markTrusted({
+                preset: preflight,
+                workspacePath: worktree.path
+              })
+            } catch {
+              // Best-effort: continue with launch.
+            }
+          }
+        }
+
+        // Why: prefer the agent's native prefill flag (currently Claude's
+        // `--prefill`) when it has one — sidesteps the readiness/paste race
+        // entirely. Falls through to the type-after-ready path for every
+        // other agent.
+        const draftLaunchPlan =
+          agent === null || !quickDraftPrompt
             ? null
-            : buildAgentStartupPlan({
+            : buildAgentDraftLaunchPlan({
                 agent,
-                prompt: '',
+                draft: quickDraftPrompt,
                 cmdOverrides: settings?.agentCmdOverrides ?? {},
-                platform: CLIENT_PLATFORM,
-                allowEmptyPromptLaunch: true
+                platform: CLIENT_PLATFORM
               })
 
+        let startupPlan: ReturnType<typeof buildAgentStartupPlan> = null
+        if (draftLaunchPlan) {
+          startupPlan = {
+            agent: draftLaunchPlan.agent,
+            launchCommand: draftLaunchPlan.launchCommand,
+            expectedProcess: draftLaunchPlan.expectedProcess,
+            followupPrompt: null,
+            ...(draftLaunchPlan.env ? { env: draftLaunchPlan.env } : {})
+          }
+        } else if (agent !== null) {
+          startupPlan = buildAgentStartupPlan({
+            agent,
+            prompt: quickPrompt,
+            cmdOverrides: settings?.agentCmdOverrides ?? {},
+            platform: CLIENT_PLATFORM,
+            allowEmptyPromptLaunch: true
+          })
+          if (startupPlan && quickDraftPrompt) {
+            startupPlan.draftPrompt = quickDraftPrompt
+          }
+        }
+
+        // Why: only attach telemetry when an agent was selected — the
+        // quick path also handles "blank shell" (agent === null) where no
+        // agent_started event should fire. When telemetry is present main
+        // emits the event after pty:spawn succeeds.
+        const quickTelemetry: AgentStartedTelemetry | null =
+          agent === null
+            ? null
+            : {
+                agent_kind: tuiAgentToAgentKind(agent),
+                launch_source: 'new_workspace_composer',
+                request_kind: 'new'
+              }
         activateAndRevealWorktree(worktree.id, {
           setup: result.setup,
-          ...(startupPlan ? { startup: { command: startupPlan.launchCommand } } : {})
+          ...(startupPlan
+            ? {
+                startup: {
+                  command: startupPlan.launchCommand,
+                  ...(startupPlan.env ? { env: startupPlan.env } : {}),
+                  ...(quickTelemetry ? { telemetry: quickTelemetry } : {})
+                }
+              }
+            : {})
         })
         if (startupPlan) {
           void ensureAgentStartupInTerminal({
@@ -1287,10 +1580,14 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       clearNewWorkspaceDraft,
       createWorktree,
       fallbackCreatureName,
+      effectiveLinkedPR,
+      linkedPR,
+      linkedWorkItem,
       name,
       normalizedSparseDirectories,
       note,
       onCreated,
+      parsedLinkedIssueNumber,
       persistDraft,
       repoId,
       requiresExplicitSetupChoice,
@@ -1305,6 +1602,7 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
       sparseEnabled,
       sparseError,
       effectivePresetId,
+      telemetrySource,
       shouldWaitForSetupCheck
     ]
   )
@@ -1323,7 +1621,12 @@ export function useComposerState(options: UseComposerStateOptions): UseComposerS
     repoId,
     onRepoChange: handleRepoChange,
     name,
-    onNameChange: handleNameChange,
+    onNameValueChange: handleNameValueChange,
+    onSmartGitHubItemSelect: handleSmartGitHubItemSelect,
+    onSmartBranchSelect: handleSmartBranchSelect,
+    onSmartLinearIssueSelect: handleSmartLinearIssueSelect,
+    smartNameSelection,
+    onClearSmartNameSelection: handleClearSmartNameSelection,
     agentPrompt,
     onAgentPromptChange: setAgentPrompt,
     onPromptKeyDown: handlePromptKeyDown,
diff --git a/src/renderer/src/hooks/useGitHubSlugMetadata.ts b/src/renderer/src/hooks/useGitHubSlugMetadata.ts
new file mode 100644
index 00000000000..b7cd35283dd
--- /dev/null
+++ b/src/renderer/src/hooks/useGitHubSlugMetadata.ts
@@ -0,0 +1,171 @@
+// Why: when the dialog opens for a Project row whose repo differs from the
+// active workspace, label/assignee lookups must target the row's repo via
+// slug-addressed IPCs (`listLabelsBySlug` / `listAssignableUsersBySlug`),
+// not via the workspace path. These hooks live in their own module so the
+// 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'
+
+type MetadataState<T> = {
+  data: T
+  loading: boolean
+  error: string | null
+}
+
+const METADATA_TTL = 300_000 // 5 min
+
+type CachedMetadata<T> = { data: T; fetchedAt: number }
+
+const slugLabelCache = new Map<string, CachedMetadata<string[]>>()
+const slugAssigneeCache = new Map<string, CachedMetadata<GitHubAssignableUser[]>>()
+
+function isCacheFresh<T>(cache: Map<string, CachedMetadata<T>>, key: string): boolean {
+  const entry = cache.get(key)
+  return !!entry && Date.now() - entry.fetchedAt < METADATA_TTL
+}
+
+export function clearGitHubSlugMetadataCache(): void {
+  slugLabelCache.clear()
+  slugAssigneeCache.clear()
+}
+
+export function useRepoLabelsBySlug(
+  owner: string | null,
+  repo: string | null
+): MetadataState<string[]> {
+  const [state, setState] = useState<MetadataState<string[]>>({
+    data: [],
+    loading: false,
+    error: null
+  })
+  const activeKeyRef = useRef<string | null>(null)
+
+  useEffect(() => {
+    if (!owner || !repo) {
+      return
+    }
+    const key = `${owner}/${repo}`
+
+    const cached = slugLabelCache.get(key)
+    if (cached && isCacheFresh(slugLabelCache, key)) {
+      // Why: always seed state from cache. A remount with the same key
+      // resets local state to defaults but `activeKeyRef.current` from the
+      // new ref instance is null on first run — the previous gate that
+      // skipped setState when keys matched dropped cached data on remount.
+      setState({ data: cached.data, loading: false, error: null })
+      activeKeyRef.current = key
+      return
+    }
+
+    activeKeyRef.current = key
+    const requestKey = key
+    setState((s) => ({
+      ...s,
+      data: s.data.length ? ([] as typeof s.data) : s.data,
+      loading: true,
+      error: null
+    }))
+    window.api.gh
+      .listLabelsBySlug({ owner, repo })
+      .then((res) => {
+        if (activeKeyRef.current !== requestKey) {
+          return
+        }
+        if (!res.ok) {
+          setState((s) => ({ ...s, loading: false, error: res.error.message }))
+          return
+        }
+        const data = res.labels
+        slugLabelCache.set(key, { data, fetchedAt: Date.now() })
+        setState({ data, loading: false, error: null })
+      })
+      .catch((err) => {
+        if (activeKeyRef.current !== requestKey) {
+          return
+        }
+        activeKeyRef.current = null
+        setState((s) => ({
+          ...s,
+          loading: false,
+          error: err instanceof Error ? err.message : 'Failed to load labels'
+        }))
+      })
+  }, [owner, repo])
+
+  return state
+}
+
+export function useRepoAssigneesBySlug(
+  owner: string | null,
+  repo: string | null,
+  seedLogins?: string[]
+): MetadataState<GitHubAssignableUser[]> {
+  const [state, setState] = useState<MetadataState<GitHubAssignableUser[]>>({
+    data: [],
+    loading: false,
+    error: null
+  })
+  const activeKeyRef = useRef<string | null>(null)
+  // Why: seedLogins is a new array reference each parent render. Stabilize on
+  // the joined-string identity so the effect doesn't re-fire on every render
+  // — this is the assignee popover refetch-storm fix.
+  const seedKey = (seedLogins ?? []).slice().sort().join(',')
+
+  useEffect(() => {
+    if (!owner || !repo) {
+      return
+    }
+    const key = `${owner}/${repo}#${seedKey}`
+
+    const cached = slugAssigneeCache.get(key)
+    if (cached && isCacheFresh(slugAssigneeCache, key)) {
+      // Why: see useRepoLabelsBySlug — always seed state from cache so a
+      // remount with the same key picks up cached data instead of staying
+      // at the empty default.
+      setState({ data: cached.data, loading: false, error: null })
+      activeKeyRef.current = key
+      return
+    }
+
+    activeKeyRef.current = key
+    const requestKey = key
+    setState((s) => ({
+      ...s,
+      data: s.data.length ? ([] as typeof s.data) : s.data,
+      loading: true,
+      error: null
+    }))
+    window.api.gh
+      .listAssignableUsersBySlug({
+        owner,
+        repo,
+        ...(seedKey ? { seedLogins: seedKey.split(',') } : {})
+      })
+      .then((res) => {
+        if (activeKeyRef.current !== requestKey) {
+          return
+        }
+        if (!res.ok) {
+          setState((s) => ({ ...s, loading: false, error: res.error.message }))
+          return
+        }
+        const data = res.users
+        slugAssigneeCache.set(key, { data, fetchedAt: Date.now() })
+        setState({ data, loading: false, error: null })
+      })
+      .catch((err) => {
+        if (activeKeyRef.current !== requestKey) {
+          return
+        }
+        activeKeyRef.current = null
+        setState((s) => ({
+          ...s,
+          loading: false,
+          error: err instanceof Error ? err.message : 'Failed to load assignees'
+        }))
+      })
+  }, [owner, repo, seedKey])
+
+  return state
+}
diff --git a/src/renderer/src/hooks/useIpcEvents.test.ts b/src/renderer/src/hooks/useIpcEvents.test.ts
index 83a6c5d8752..4e15cede4c0 100644
--- a/src/renderer/src/hooks/useIpcEvents.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents.test.ts
@@ -169,6 +169,8 @@ describe('useIpcEvents updater integration', () => {
           replyTabCreate: () => {},
           onRequestTabClose: () => () => {},
           replyTabClose: () => {},
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -204,7 +206,8 @@ describe('useIpcEvents updater integration', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         ssh: {
           listTargets: () => Promise.resolve([]),
@@ -366,6 +369,8 @@ describe('useIpcEvents updater integration', () => {
           replyTabCreate: () => {},
           onRequestTabClose: () => () => {},
           replyTabClose: () => {},
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -398,7 +403,8 @@ describe('useIpcEvents updater integration', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         ssh: {
           listTargets: () => Promise.resolve([]),
@@ -562,6 +568,8 @@ describe('useIpcEvents updater integration', () => {
           replyTabCreate: () => {},
           onRequestTabClose: () => () => {},
           replyTabClose: vi.fn(),
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -594,7 +602,8 @@ describe('useIpcEvents updater integration', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         ssh: {
           listTargets: () => Promise.resolve([]),
@@ -769,6 +778,8 @@ describe('useIpcEvents browser tab close routing', () => {
             return () => {}
           },
           replyTabClose,
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -812,7 +823,8 @@ describe('useIpcEvents browser tab close routing', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         agentStatus: { onSet: () => () => {} }
       }
@@ -961,6 +973,8 @@ describe('useIpcEvents browser tab close routing', () => {
             return () => {}
           },
           replyTabClose,
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -1004,7 +1018,8 @@ describe('useIpcEvents browser tab close routing', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         agentStatus: { onSet: () => () => {} }
       }
@@ -1148,6 +1163,8 @@ describe('useIpcEvents browser tab close routing', () => {
             return () => {}
           },
           replyTabClose,
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -1191,7 +1208,8 @@ describe('useIpcEvents browser tab close routing', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         agentStatus: { onSet: () => () => {} }
       }
@@ -1354,6 +1372,8 @@ describe('useIpcEvents shortcut hint clearing', () => {
           replyTabCreate: () => {},
           onRequestTabClose: () => () => {},
           replyTabClose: () => {},
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -1392,7 +1412,8 @@ describe('useIpcEvents shortcut hint clearing', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         ssh: {
           listTargets: () => Promise.resolve([]),
@@ -1583,6 +1604,8 @@ describe('useIpcEvents CLI-created worktree activation', () => {
           replyTabCreate: () => {},
           onRequestTabClose: () => () => {},
           replyTabClose: () => {},
+          onRequestTabSetProfile: () => () => {},
+          replyTabSetProfile: () => {},
           onNewTerminalTab: () => () => {},
           onCloseActiveTab: () => () => {},
           onSwitchTab: () => () => {},
@@ -1626,7 +1649,8 @@ describe('useIpcEvents CLI-created worktree activation', () => {
         },
         runtime: {
           getTerminalFitOverrides: () => Promise.resolve([]),
-          onTerminalFitOverrideChanged: () => () => {}
+          onTerminalFitOverrideChanged: () => () => {},
+          onTerminalDriverChanged: () => () => {}
         },
         agentStatus: { onSet: () => () => {} }
       }
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index 47264b83167..0bd9f9039c4 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -24,6 +24,8 @@ import { normalizeAgentStatusPayload } from '../../../shared/agent-status-types'
 import { isGitRepoKind } from '../../../shared/repo-kind'
 import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
 import { setFitOverride, hydrateOverrides } from '@/lib/pane-manager/mobile-fit-overrides'
+import { setDriverForPty } from '@/lib/pane-manager/mobile-driver-state'
+import { destroyPersistentWebview } from '@/components/browser-pane/webview-registry'
 
 export { resolveZoomTarget } from './resolve-zoom-target'
 
@@ -144,7 +146,7 @@ export function useIpcEvents(): void {
     )
 
     unsubs.push(
-      window.api.ui.onOpenNewWorkspace((tab) => {
+      window.api.ui.onOpenNewWorkspace(() => {
         // Why: mirror the renderer's App.tsx Cmd+N guard — only open the
         // composer when there is at least one real git repo configured, so
         // users on a fresh install don't get a modal with nothing to target.
@@ -152,15 +154,10 @@ export function useIpcEvents(): void {
         if (!store.repos.some((repo) => isGitRepoKind(repo))) {
           return
         }
-        // Why: if the composer is already open, switch tabs in place so
-        // repeated Cmd+N / Cmd+Shift+N presses toggle between Quick and
-        // Create-from without remounting and losing in-flight composer state
-        // (repo pick, note drafts). Opening when closed seeds the initial tab.
         if (store.activeModal === 'new-workspace-composer') {
-          store.setNewWorkspaceComposerTab(tab)
           return
         }
-        store.openModal('new-workspace-composer', { initialTab: tab })
+        store.openModal('new-workspace-composer', { telemetrySource: 'shortcut' })
       })
     )
 
@@ -447,7 +444,8 @@ export function useIpcEvents(): void {
 
           const workspace = store.createBrowserTab(worktreeId, data.url, {
             title: data.url,
-            targetGroupId: activeBrowserUnifiedTab?.groupId
+            targetGroupId: activeBrowserUnifiedTab?.groupId,
+            sessionProfileId: data.sessionProfileId
           })
           // Why: registerGuest fires with the page ID (not workspace ID) as
           // browserPageId. Return the page ID so waitForTabRegistration can
@@ -464,6 +462,38 @@ export function useIpcEvents(): void {
       })
     )
 
+    unsubs.push(
+      window.api.ui.onRequestTabSetProfile((data) => {
+        try {
+          const store = useAppStore.getState()
+          const owningWorkspace = Object.values(store.browserTabsByWorktree)
+            .flat()
+            .find((workspace) => {
+              if (workspace.id === data.browserPageId) {
+                return true
+              }
+              const pages = store.browserPagesByWorkspace[workspace.id] ?? []
+              return pages.some((page) => page.id === data.browserPageId)
+            })
+          if (!owningWorkspace) {
+            window.api.ui.replyTabSetProfile({
+              requestId: data.requestId,
+              error: `Browser tab ${data.browserPageId} not found`
+            })
+            return
+          }
+          destroyPersistentWebview(data.browserPageId)
+          store.switchBrowserTabProfile(owningWorkspace.id, data.profileId)
+          window.api.ui.replyTabSetProfile({ requestId: data.requestId })
+        } catch (err) {
+          window.api.ui.replyTabSetProfile({
+            requestId: data.requestId,
+            error: err instanceof Error ? err.message : 'Tab profile update failed'
+          })
+        }
+      })
+    )
+
     unsubs.push(
       window.api.ui.onRequestTabClose((data) => {
         try {
@@ -838,6 +868,16 @@ export function useIpcEvents(): void {
       })
     )
 
+    unsubs.push(
+      // Why: presence-lock driver state mirror. Updates the renderer's
+      // mobile-driver-state map so TerminalPane / pty-connection guards
+      // know which PTYs are currently driven by mobile. See
+      // docs/mobile-presence-lock.md.
+      window.api.runtime.onTerminalDriverChanged((event) => {
+        setDriverForPty(event.ptyId, event.driver)
+      })
+    )
+
     return () => unsubs.forEach((fn) => fn())
   }, [])
 }
diff --git a/src/renderer/src/lib/activate-tab-and-focus-pane.ts b/src/renderer/src/lib/activate-tab-and-focus-pane.ts
new file mode 100644
index 00000000000..864b62928a0
--- /dev/null
+++ b/src/renderer/src/lib/activate-tab-and-focus-pane.ts
@@ -0,0 +1,18 @@
+import { useAppStore } from '@/store'
+import { FOCUS_TERMINAL_PANE_EVENT, type FocusTerminalPaneDetail } from '@/constants/terminal'
+
+export function activateTabAndFocusPane(tabId: string, paneId: number | null): void {
+  useAppStore.getState().setActiveTab(tabId)
+  if (paneId === null) {
+    return
+  }
+  // Why: defer one frame so the new TerminalPane has mounted its
+  // FOCUS_TERMINAL_PANE_EVENT listener before we dispatch.
+  requestAnimationFrame(() => {
+    window.dispatchEvent(
+      new CustomEvent<FocusTerminalPaneDetail>(FOCUS_TERMINAL_PANE_EVENT, {
+        detail: { tabId, paneId }
+      })
+    )
+  })
+}
diff --git a/src/renderer/src/lib/agent-catalog.tsx b/src/renderer/src/lib/agent-catalog.tsx
index 37696800350..37a8713d9f1 100644
--- a/src/renderer/src/lib/agent-catalog.tsx
+++ b/src/renderer/src/lib/agent-catalog.tsx
@@ -106,6 +106,13 @@ export const AGENT_CATALOG: AgentCatalogEntry[] = [
     faviconDomain: 'augmentcode.com',
     homepageUrl: 'https://docs.augmentcode.com/cli/overview'
   },
+  {
+    id: 'autohand',
+    label: 'Autohand Code',
+    cmd: 'autohand',
+    faviconDomain: 'autohand.ai',
+    homepageUrl: 'https://github.com/autohandai/code-cli'
+  },
   {
     id: 'cline',
     label: 'Cline',
diff --git a/src/renderer/src/lib/agent-paste-draft.ts b/src/renderer/src/lib/agent-paste-draft.ts
new file mode 100644
index 00000000000..7054bed4419
--- /dev/null
+++ b/src/renderer/src/lib/agent-paste-draft.ts
@@ -0,0 +1,172 @@
+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'
+
+// Why: bracketed paste markers let modern TUIs (Claude Code / Codex / Pi /
+// OpenCode / Gemini / cursor-agent / copilot) treat the inserted text as a
+// single atomic paste — the payload lands in the input buffer as a draft
+// instead of echoing character-by-character or triggering line-edit
+// shortcuts. Intentionally omit a trailing '\r' so the draft never auto-
+// submits; the user reviews and sends the prompt themselves.
+const BRACKETED_PASTE_BEGIN = '\x1b[200~'
+const BRACKETED_PASTE_END = '\x1b[201~'
+
+// Why: every prefill-capable TUI we ship support for (claude / codex / pi /
+// opencode / gemini / cursor-agent / copilot) emits `CSI ? 2004 h` (DECSET
+// 2004 — bracketed-paste-enable) on its output stream when its input layer
+// is wired up. That sequence is the protocol-level "I accept bracketed
+// paste" handshake — but on its own it doesn't mean "the input box is
+// rendered and visible". OpenCode in particular emits DECSET 2004 during
+// its alt-screen setup at ~500ms, then runs a 1.3s splash render with NO
+// data on the PTY, then paints the actual input box at ~1.85s. Pasting
+// during the silent gap drops the bytes.
+//
+// Strategy: take DECSET 2004 as the necessary precondition, then wait for
+// the TUI's render burst to finish — defined as `BRACKETED_PASTE_QUIET_MS`
+// of stream silence after the most recent post-`?2004h` byte. This
+// captures both the fast TUIs (claude/pi/codex emit their setup escapes
+// in one burst, then go quiet) and the slow ones (opencode emits, sleeps,
+// emits again, then goes quiet). Verified against opencode/claude/pi in
+// a node-pty rig: paste lands on the first try with a 1500ms quiet window.
+const DECSET_BRACKETED_PASTE = '\x1b[?2004h'
+const BRACKETED_PASTE_QUIET_MS = 1500
+
+// Why: deterministic signal can fail in two ways: (1) the agent never
+// emits DECSET 2004 (no shipped agent does this — guarded as a fallback),
+// or (2) the launch fails outright. The hard timeout caps the wait so a
+// stuck launch doesn't pin a Promise forever.
+const READINESS_TIMEOUT_MS = 8000
+
+/**
+ * Wait until the agent on `tabId` has rendered its input-accepting TUI,
+ * then bracketed-paste `content` into its input buffer. Never appends
+ * `\r`, so the draft stays editable for the user to review / append
+ * before sending.
+ *
+ * Returns true when the paste was issued, false on timeout or missing
+ * PTY. `onTimeout` lets the caller surface a UI hint (e.g. toast) when
+ * the agent doesn't reach a ready state inside `timeoutMs`.
+ *
+ * Readiness combines two stream signals:
+ *   1. `\x1b[?2004h` (DECSET 2004 — bracketed-paste-enable) on the PTY
+ *      output. This is the protocol-level "I accept bracketed paste"
+ *      handshake.
+ *   2. ≥`BRACKETED_PASTE_QUIET_MS` of silence after the last byte of the
+ *      post-handshake render burst. Captures TUIs (OpenCode) that emit
+ *      DECSET 2004 early and then run a multi-second splash before
+ *      drawing the actual input box.
+ */
+export async function pasteDraftWhenAgentReady(args: {
+  tabId: string
+  content: string
+  agent?: TuiAgent
+  timeoutMs?: number
+  onTimeout?: () => void
+}): Promise<boolean> {
+  const { tabId, content, agent, timeoutMs, onTimeout } = args
+
+  // Why: agents with a documented prefill flag (currently Claude — see
+  // TUI_AGENT_CONFIG.claude.draftPromptFlag) launch with the URL already
+  // in their input box. Pasting again would duplicate it. Callers should
+  // not invoke this helper for those agents; the early return guards
+  // against accidental double-injection if a stale call slips through.
+  if (agent && TUI_AGENT_CONFIG[agent].draftPromptFlag) {
+    return false
+  }
+
+  const budget = timeoutMs ?? READINESS_TIMEOUT_MS
+  const ptyId = await waitForPtyId(tabId, budget)
+  if (!ptyId) {
+    onTimeout?.()
+    return false
+  }
+
+  const ready = await waitForInputBoxReady(ptyId, budget)
+  if (!ready) {
+    onTimeout?.()
+    return false
+  }
+
+  window.api.pty.write(ptyId, `${BRACKETED_PASTE_BEGIN}${content}${BRACKETED_PASTE_END}`)
+  return true
+}
+
+/**
+ * Tap the PTY data stream as a side-channel observer (does NOT take over
+ * the primary handler that feeds xterm) and resolve `true` once we see
+ * DECSET 2004 *and* the post-handshake render burst settles for
+ * `BRACKETED_PASTE_QUIET_MS`. Resolves `false` on hard timeout.
+ *
+ * Why a sidecar subscription:
+ *   - the main pane may attach mid-flight; we must not race against its
+ *     handler registration on the dispatcher's primary slot.
+ *   - DECSET 2004 may straddle two data chunks at ANSI parser boundaries,
+ *     so we keep a small ring of recent bytes and search the union.
+ */
+function waitForInputBoxReady(ptyId: string, timeoutMs: number): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    let settled = false
+    let recent = ''
+    let saw2004 = false
+    let quietTimer: number | null = null
+    let unsubscribe: (() => void) | null = null
+
+    const finish = (value: boolean): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      window.clearTimeout(hardTimer)
+      if (quietTimer !== null) {
+        window.clearTimeout(quietTimer)
+      }
+      unsubscribe?.()
+      resolve(value)
+    }
+
+    const armQuietTimer = (): void => {
+      if (quietTimer !== null) {
+        window.clearTimeout(quietTimer)
+      }
+      quietTimer = window.setTimeout(() => finish(true), BRACKETED_PASTE_QUIET_MS)
+    }
+
+    unsubscribe = subscribeToPtyData(ptyId, (data) => {
+      // 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.
+      recent = (recent + data).slice(-64)
+      if (!saw2004 && recent.includes(DECSET_BRACKETED_PASTE)) {
+        saw2004 = true
+      }
+      if (saw2004) {
+        // Reset the quiet window on every byte we see post-handshake.
+        // The TUI's render is "done" when the stream goes quiet for
+        // BRACKETED_PASTE_QUIET_MS — at that point the input box is
+        // mounted and bracketed paste lands in the input buffer.
+        armQuietTimer()
+      }
+    })
+
+    const hardTimer = window.setTimeout(() => finish(false), timeoutMs)
+  })
+}
+
+/**
+ * Why: activation creates the tab synchronously but the PTY spawn is
+ * async. Poll the store until the primary PTY id appears or the budget
+ * expires. Tight interval because the wait is normally <200ms — only the
+ * first launch on a cold app reaches the tail of this.
+ */
+async function waitForPtyId(tabId: string, timeoutMs: number): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const ptyId = useAppStore.getState().ptyIdsByTabId[tabId]?.[0]
+    if (ptyId) {
+      return ptyId
+    }
+    await new Promise<void>((resolve) => window.setTimeout(resolve, 50))
+  }
+  return null
+}
diff --git a/src/renderer/src/lib/agent-status.ts b/src/renderer/src/lib/agent-status.ts
index 10594708a2c..ab93962b3d0 100644
--- a/src/renderer/src/lib/agent-status.ts
+++ b/src/renderer/src/lib/agent-status.ts
@@ -125,6 +125,7 @@ export function formatAgentTypeLabel(agentType: AgentType | null | undefined): s
 const ICONABLE_AGENT_TYPES: Record<TuiAgent, true> = {
   claude: true,
   codex: true,
+  autohand: true,
   opencode: true,
   pi: true,
   gemini: true,
diff --git a/src/renderer/src/lib/app-font-family.test.ts b/src/renderer/src/lib/app-font-family.test.ts
new file mode 100644
index 00000000000..3a23f8992a2
--- /dev/null
+++ b/src/renderer/src/lib/app-font-family.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { buildAppFontFamily } from './app-font-family'
+
+describe('buildAppFontFamily', () => {
+  it('defaults to the bundled app font', () => {
+    expect(buildAppFontFamily('')).toBe(
+      '"Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
+    )
+  })
+
+  it('places a custom UI font before the fallback chain', () => {
+    expect(buildAppFontFamily('Inter')).toBe(
+      '"Inter", "Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
+    )
+  })
+
+  it('does not duplicate the bundled font when selected explicitly', () => {
+    expect(buildAppFontFamily('Geist')).toBe(
+      '"Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
+    )
+  })
+})
diff --git a/src/renderer/src/lib/app-font-family.ts b/src/renderer/src/lib/app-font-family.ts
new file mode 100644
index 00000000000..956f478e0c6
--- /dev/null
+++ b/src/renderer/src/lib/app-font-family.ts
@@ -0,0 +1,36 @@
+import { DEFAULT_APP_FONT_FAMILY } from '../../../shared/constants'
+
+const APP_FONT_FALLBACKS = [
+  DEFAULT_APP_FONT_FAMILY,
+  '-apple-system',
+  'BlinkMacSystemFont',
+  'Segoe UI',
+  'sans-serif'
+] as const
+
+const CSS_FONT_KEYWORDS = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'blinkmacsystemfont'
+])
+
+function quoteFontFamily(fontFamily: string): string {
+  if (fontFamily.startsWith('-') || CSS_FONT_KEYWORDS.has(fontFamily.toLowerCase())) {
+    return fontFamily
+  }
+  return JSON.stringify(fontFamily)
+}
+
+export function buildAppFontFamily(fontFamily: string | null | undefined): string {
+  const trimmed = fontFamily?.trim() || DEFAULT_APP_FONT_FAMILY
+  const lowerTrimmed = trimmed.toLowerCase()
+  const parts = [
+    trimmed,
+    ...APP_FONT_FALLBACKS.filter((fallback) => fallback.toLowerCase() !== lowerTrimmed)
+  ]
+  return parts.map(quoteFontFamily).join(', ')
+}
diff --git a/src/renderer/src/lib/desktop-notification-sound.ts b/src/renderer/src/lib/desktop-notification-sound.ts
new file mode 100644
index 00000000000..2df1eafa5bc
--- /dev/null
+++ b/src/renderer/src/lib/desktop-notification-sound.ts
@@ -0,0 +1,19 @@
+export async function playDesktopNotificationSound(
+  customSoundPath: string | null | undefined
+): Promise<boolean> {
+  if (!customSoundPath) {
+    return false
+  }
+
+  try {
+    const result = await window.api.notifications.playSound()
+    // Why: 'deduped' is expected when bursts of notifications coalesce — not a failure.
+    if (!result.played && result.reason !== 'deduped') {
+      console.warn('Failed to play custom notification sound:', result.reason)
+    }
+    return result.played
+  } catch (err) {
+    console.warn('Failed to play custom notification sound:', err)
+    return false
+  }
+}
diff --git a/src/renderer/src/lib/document-theme.test.ts b/src/renderer/src/lib/document-theme.test.ts
new file mode 100644
index 00000000000..6c94a9a1354
--- /dev/null
+++ b/src/renderer/src/lib/document-theme.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest'
+import {
+  applyDocumentTheme,
+  resolveDocumentTheme,
+  THEME_TRANSITION_DISABLED_CLASS
+} from './document-theme'
+
+class FakeClassList {
+  private readonly tokens = new Set<string>()
+
+  add(...tokens: string[]): void {
+    for (const token of tokens) {
+      this.tokens.add(token)
+    }
+  }
+
+  remove(...tokens: string[]): void {
+    for (const token of tokens) {
+      this.tokens.delete(token)
+    }
+  }
+
+  toggle(token: string, force?: boolean): boolean {
+    if (force === true) {
+      this.tokens.add(token)
+      return true
+    }
+    if (force === false) {
+      this.tokens.delete(token)
+      return false
+    }
+    if (this.tokens.has(token)) {
+      this.tokens.delete(token)
+      return false
+    }
+    this.tokens.add(token)
+    return true
+  }
+
+  contains(token: string): boolean {
+    return this.tokens.has(token)
+  }
+}
+
+function createThemeRoot(): { classList: FakeClassList } {
+  return { classList: new FakeClassList() }
+}
+
+function createFrameQueue(): {
+  requestAnimationFrame: (callback: FrameRequestCallback) => number
+  flushNextFrame: () => void
+} {
+  const callbacks: FrameRequestCallback[] = []
+  return {
+    requestAnimationFrame: (callback) => {
+      callbacks.push(callback)
+      return callbacks.length
+    },
+    flushNextFrame: () => {
+      callbacks.shift()?.(0)
+    }
+  }
+}
+
+describe('document theme', () => {
+  it('resolves explicit theme preferences', () => {
+    expect(resolveDocumentTheme('dark')).toBe(true)
+    expect(resolveDocumentTheme('light')).toBe(false)
+  })
+
+  it('resolves system from matchMedia', () => {
+    expect(resolveDocumentTheme('system', () => ({ matches: true }))).toBe(true)
+    expect(resolveDocumentTheme('system', () => ({ matches: false }))).toBe(false)
+  })
+
+  it('applies dark and light root classes', () => {
+    const root = createThemeRoot()
+
+    applyDocumentTheme('dark', { root, disableTransitions: false })
+    expect(root.classList.contains('dark')).toBe(true)
+
+    applyDocumentTheme('light', { root, disableTransitions: false })
+    expect(root.classList.contains('dark')).toBe(false)
+  })
+
+  it('applies system root class from matchMedia', () => {
+    const root = createThemeRoot()
+
+    applyDocumentTheme('system', {
+      root,
+      matchMedia: () => ({ matches: true }),
+      disableTransitions: false
+    })
+    expect(root.classList.contains('dark')).toBe(true)
+  })
+
+  it('removes the transition suppression class after two animation frames', () => {
+    const root = createThemeRoot()
+    const frames = createFrameQueue()
+
+    applyDocumentTheme('dark', {
+      root,
+      requestAnimationFrame: frames.requestAnimationFrame
+    })
+
+    expect(root.classList.contains(THEME_TRANSITION_DISABLED_CLASS)).toBe(true)
+
+    frames.flushNextFrame()
+    expect(root.classList.contains(THEME_TRANSITION_DISABLED_CLASS)).toBe(true)
+
+    frames.flushNextFrame()
+    expect(root.classList.contains(THEME_TRANSITION_DISABLED_CLASS)).toBe(false)
+  })
+})
diff --git a/src/renderer/src/lib/document-theme.ts b/src/renderer/src/lib/document-theme.ts
new file mode 100644
index 00000000000..5651dba213c
--- /dev/null
+++ b/src/renderer/src/lib/document-theme.ts
@@ -0,0 +1,75 @@
+import type { GlobalSettings } from '../../../shared/types'
+
+export type DocumentThemePreference = GlobalSettings['theme']
+
+export const THEME_TRANSITION_DISABLED_CLASS = 'theme-transition-disabled'
+
+const DARK_MODE_QUERY = '(prefers-color-scheme: dark)'
+
+type ThemeClassList = {
+  add: (...tokens: string[]) => void
+  remove: (...tokens: string[]) => void
+  toggle: (token: string, force?: boolean) => boolean
+}
+
+type ThemeRoot = {
+  classList: ThemeClassList
+}
+
+type ThemeMediaMatcher = (query: string) => Pick<MediaQueryList, 'matches'>
+type ThemeAnimationFrame = (callback: FrameRequestCallback) => number
+
+type ApplyDocumentThemeOptions = {
+  root?: ThemeRoot
+  matchMedia?: ThemeMediaMatcher
+  requestAnimationFrame?: ThemeAnimationFrame
+  disableTransitions?: boolean
+}
+
+function systemPrefersDark(
+  matchMedia: ThemeMediaMatcher = window.matchMedia.bind(window)
+): boolean {
+  return matchMedia(DARK_MODE_QUERY).matches
+}
+
+export function resolveDocumentTheme(
+  theme: DocumentThemePreference,
+  matchMedia?: ThemeMediaMatcher
+): boolean {
+  if (theme === 'dark') {
+    return true
+  }
+  if (theme === 'light') {
+    return false
+  }
+  return systemPrefersDark(matchMedia)
+}
+
+export function applyDocumentTheme(
+  theme: DocumentThemePreference,
+  options: ApplyDocumentThemeOptions = {}
+): void {
+  const root = options.root ?? document.documentElement
+  const disableTransitions = options.disableTransitions ?? true
+  const shouldUseDarkTheme = resolveDocumentTheme(theme, options.matchMedia)
+
+  if (disableTransitions) {
+    root.classList.add(THEME_TRANSITION_DISABLED_CLASS)
+  }
+
+  root.classList.toggle('dark', shouldUseDarkTheme)
+
+  if (!disableTransitions) {
+    return
+  }
+
+  const requestFrame = options.requestAnimationFrame ?? window.requestAnimationFrame.bind(window)
+
+  // Why: two frames lets the root theme class recalculate before restoring
+  // normal hover/collapse transitions, preventing staggered color fades.
+  requestFrame(() => {
+    requestFrame(() => {
+      root.classList.remove(THEME_TRANSITION_DISABLED_CLASS)
+    })
+  })
+}
diff --git a/src/renderer/src/lib/ensure-hooks-confirmed.test.ts b/src/renderer/src/lib/ensure-hooks-confirmed.test.ts
index af7dbea851d..eff7523b571 100644
--- a/src/renderer/src/lib/ensure-hooks-confirmed.test.ts
+++ b/src/renderer/src/lib/ensure-hooks-confirmed.test.ts
@@ -7,13 +7,15 @@ import { hashOrcaHookScript } from './orca-hook-trust'
 const hooksCheckMock = vi.fn()
 const readIssueCommandMock = vi.fn()
 
-;(globalThis as { window: unknown }).window = {
-  api: {
-    hooks: {
-      check: hooksCheckMock,
-      readIssueCommand: readIssueCommandMock
+function installHooksApiMock(): void {
+  vi.stubGlobal('window', {
+    api: {
+      hooks: {
+        check: hooksCheckMock,
+        readIssueCommand: readIssueCommandMock
+      }
     }
-  }
+  })
 }
 
 type PendingPrompt = {
@@ -48,6 +50,7 @@ describe('ensureHooksConfirmed', () => {
   beforeEach(() => {
     hooksCheckMock.mockReset()
     readIssueCommandMock.mockReset()
+    installHooksApiMock()
     __resetTrustPromptChainForTests()
   })
 
@@ -171,17 +174,13 @@ describe('ensureHooksConfirmed', () => {
     const first = ensureHooksConfirmed(state, 'repo-1', 'setup')
     const second = ensureHooksConfirmed(state, 'repo-1', 'archive')
 
-    await flush()
-
-    expect(pending).toHaveLength(1)
+    await vi.waitFor(() => expect(pending).toHaveLength(1))
     expect(pending[0].data.scriptKind).toBe('setup')
 
     pending[0].resolve('skip')
     await expect(first).resolves.toBe('skip')
 
-    await flush()
-
-    expect(pending).toHaveLength(2)
+    await vi.waitFor(() => expect(pending).toHaveLength(2))
     expect(pending[1].data.scriptKind).toBe('archive')
 
     pending[1].resolve('run')
diff --git a/src/renderer/src/lib/github-links.ts b/src/renderer/src/lib/github-links.ts
index e6db2b488f8..d8701171827 100644
--- a/src/renderer/src/lib/github-links.ts
+++ b/src/renderer/src/lib/github-links.ts
@@ -52,6 +52,7 @@ export function parseGitHubIssueOrPRNumber(input: string): number | null {
 export function parseGitHubIssueOrPRLink(input: string): {
   slug: RepoSlug
   number: number
+  type: 'issue' | 'pr'
 } | null {
   const trimmed = input.trim()
   if (!trimmed) {
@@ -76,6 +77,7 @@ export function parseGitHubIssueOrPRLink(input: string): {
 
   return {
     slug: { owner: match[1], repo: match[2] },
+    type: url.pathname.toLowerCase().includes('/pull/') ? 'pr' : 'issue',
     number: Number.parseInt(match[3], 10)
   }
 }
diff --git a/src/renderer/src/lib/launch-agent-in-new-tab.ts b/src/renderer/src/lib/launch-agent-in-new-tab.ts
index dd49861c803..6e959f9c895 100644
--- a/src/renderer/src/lib/launch-agent-in-new-tab.ts
+++ b/src/renderer/src/lib/launch-agent-in-new-tab.ts
@@ -2,6 +2,7 @@ import { useAppStore } from '@/store'
 import { buildAgentStartupPlan, type AgentStartupPlan } from '@/lib/tui-agent-startup'
 import { CLIENT_PLATFORM } from '@/lib/new-workspace'
 import { reconcileTabOrder } from '@/components/tab-bar/reconcile-order'
+import { tuiAgentToAgentKind } from '@/lib/telemetry'
 import type { TuiAgent } from '../../../shared/types'
 
 export type LaunchAgentInNewTabArgs = {
@@ -55,8 +56,20 @@ export function launchAgentInNewTab(args: LaunchAgentInNewTabArgs): LaunchAgentI
   // lands after mount the agent binary never starts; the user sees a bare shell.
   // Since both calls happen synchronously in the same React batch, the queue
   // is in place by the time the pane commits.
+  //
+  // The telemetry payload is threaded through the queue → pty-connection →
+  // pty-transport → pty:spawn IPC → main, where main fires `agent_started`
+  // only after the spawn succeeds. `request_kind: 'new'` because
+  // quick-launch always opens a fresh empty-prompt session.
   const tab = store.createTab(worktreeId, groupId)
-  store.queueTabStartupCommand(tab.id, { command: startupPlan.launchCommand })
+  store.queueTabStartupCommand(tab.id, {
+    command: startupPlan.launchCommand,
+    telemetry: {
+      agent_kind: tuiAgentToAgentKind(agent),
+      launch_source: 'tab_bar_quick_launch',
+      request_kind: 'new'
+    }
+  })
 
   // Why: match the `+` button's `createNewTerminalTab` sequence — without
   // `setActiveTabType('terminal')`, a worktree currently showing an editor
diff --git a/src/renderer/src/lib/launch-work-item-direct.ts b/src/renderer/src/lib/launch-work-item-direct.ts
index decb9219d13..dac68d1186c 100644
--- a/src/renderer/src/lib/launch-work-item-direct.ts
+++ b/src/renderer/src/lib/launch-work-item-direct.ts
@@ -1,18 +1,26 @@
 import { toast } from 'sonner'
 import { useAppStore } from '@/store'
 import { AGENT_CATALOG } from '@/lib/agent-catalog'
-import { waitForAgentReady } from '@/lib/agent-ready-wait'
-import { buildAgentStartupPlan } from '@/lib/tui-agent-startup'
-import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import { pasteDraftWhenAgentReady } from '@/lib/agent-paste-draft'
+import { buildAgentDraftLaunchPlan, buildAgentStartupPlan } from '@/lib/tui-agent-startup'
+import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
+import { activateAndRevealWorktree, type AgentStartedTelemetry } from '@/lib/worktree-activation'
 import {
   CLIENT_PLATFORM,
   getLinkedWorkItemSuggestedName,
   getSetupConfig,
   getWorkspaceSeedName
 } from '@/lib/new-workspace'
-import { getSuggestedCreatureName } from '@/components/sidebar/worktree-name-suggestions'
 import { ensureHooksConfirmed } from '@/lib/ensure-hooks-confirmed'
-import type { OrcaHooks, RepoHookSettings, SetupDecision, TuiAgent } from '../../../shared/types'
+import { track, tuiAgentToAgentKind } from '@/lib/telemetry'
+import type {
+  OrcaHooks,
+  RepoHookSettings,
+  SetupDecision,
+  TuiAgent,
+  WorkspaceCreateTelemetrySource
+} from '../../../shared/types'
+import type { LaunchSource } from '../../../shared/telemetry-events'
 
 export type LaunchableWorkItem = {
   title: string
@@ -30,13 +38,9 @@ export type LaunchableWorkItem = {
   linearIdentifier?: string
 }
 
-// Why: bracketed paste markers let modern TUIs treat the inserted text as a
-// single atomic paste — Claude Code / Codex / Gemini put it in their input
-// buffer as a draft instead of echoing character-by-character. Intentionally
-// omit a trailing '\r' so the draft never auto-submits; the user gets to
-// review and send the prompt themselves.
-const BRACKETED_PASTE_BEGIN = '\x1b[200~'
-const BRACKETED_PASTE_END = '\x1b[201~'
+// Why: bracketed paste markers and ready-wait grace timing live in
+// agent-paste-draft.ts so the new-workspace and "Use" flows share one
+// definition of "type into the agent's input as a non-submitted draft".
 
 export type LaunchWorkItemDirectArgs = {
   item: LaunchableWorkItem
@@ -47,9 +51,18 @@ export type LaunchWorkItemDirectArgs = {
   openModalFallback: () => void
   /** Optional base branch to start the worktree from. When omitted the
    *  worktree inherits the repo's effective base ref. Used by the
-   *  "Create from…" PR row to branch from the PR's head so the first
+   *  smart workspace-name PR selection to branch from the PR's head so the first
    *  commit lands on the correct base without the user touching the UI. */
   baseBranch?: string
+  /** Telemetry surface that initiated this agent launch. Threaded into
+   *  the queued startup payload so `agent_started.launch_source` reflects
+   *  the actual entry point. */
+  launchSource: LaunchSource
+  /** Telemetry surface that initiated this launch. Threaded into
+   *  `createWorktree` so `workspace_created.source` reflects the actual
+   *  entry point (Tasks page row → `sidebar`, Create-from modal →
+   *  `command_palette`). Omitted callers default to `unknown`. */
+  telemetrySource?: WorkspaceCreateTelemetrySource
 }
 
 function pickAgent(
@@ -99,37 +112,55 @@ async function resolveSetupDecision(
   }
 }
 
+// Why: telemetry rides the queued startup so main fires `agent_started`
+// only after pty:spawn confirms the launch. No agent / no plan → no event.
+function buildStartupOpts(
+  agent: TuiAgent | null,
+  plan: ReturnType<typeof buildAgentStartupPlan>,
+  launchSource: LaunchSource
+): {
+  startup?: { command: string; env?: Record<string, string>; telemetry?: AgentStartedTelemetry }
+} {
+  if (!plan) {
+    return {}
+  }
+  const telemetry: AgentStartedTelemetry | null =
+    agent === null
+      ? null
+      : { agent_kind: tuiAgentToAgentKind(agent), launch_source: launchSource, request_kind: 'new' }
+  return {
+    startup: {
+      command: plan.launchCommand,
+      ...(plan.env ? { env: plan.env } : {}),
+      ...(telemetry ? { telemetry } : {})
+    }
+  }
+}
+
 async function pasteWorkItemDraftWhenAgentReady(args: {
   primaryTabId: string
   startupPlan: NonNullable<ReturnType<typeof buildAgentStartupPlan>>
   content: string
+  /** Telemetry-only: which agent the renderer thinks it launched, so an
+   *  `agent_error` on timeout can carry the right `agent_kind`. */
+  agentKind?: ReturnType<typeof tuiAgentToAgentKind>
 }): Promise<void> {
-  const { primaryTabId, startupPlan, content } = args
-  const readyResult = await waitForAgentReady(primaryTabId, startupPlan.expectedProcess, {
-    timeoutMs: 5000
+  const { primaryTabId, startupPlan, content, agentKind } = args
+  await pasteDraftWhenAgentReady({
+    tabId: primaryTabId,
+    content,
+    agent: startupPlan.agent,
+    onTimeout: () => {
+      toast.message(
+        'Agent took too long to start. The workspace is ready — paste the issue URL when the agent is idle.'
+      )
+      // Why: process-startup timeout has no v1 enum slot; the `unknown` slice
+      // on the dashboard is the trigger to add one.
+      if (agentKind) {
+        track('agent_error', { error_class: 'unknown', agent_kind: agentKind })
+      }
+    }
   })
-  if (!readyResult.ready) {
-    toast.message(
-      'Agent took too long to start. The workspace is ready — paste the issue URL when the agent is idle.'
-    )
-    return
-  }
-
-  const finalState = useAppStore.getState()
-  const ptyId = finalState.ptyIdsByTabId[primaryTabId]?.[0]
-  if (!ptyId) {
-    return
-  }
-
-  // Why: TUIs must enable bracketed paste mode (\x1b[?2004h) before they can
-  // interpret our paste markers. `title-idle` means the TUI has fully rendered
-  // its input box and enabled paste mode; weaker signals (`foreground-match`,
-  // `child-process`) only confirm the binary is running — the TUI's input
-  // setup may still be in-flight, especially on slow shell environments.
-  const graceMs = readyResult.reason === 'title-idle' ? 150 : 600
-  await new Promise((resolve) => window.setTimeout(resolve, graceMs))
-
-  window.api.pty.write(ptyId, `${BRACKETED_PASTE_BEGIN}${content}${BRACKETED_PASTE_END}`)
 }
 
 /**
@@ -146,7 +177,7 @@ async function pasteWorkItemDraftWhenAgentReady(args: {
  * has a usable workspace and can paste the URL themselves.
  */
 export async function launchWorkItemDirect(args: LaunchWorkItemDirectArgs): Promise<void> {
-  const { item, repoId, openModalFallback, baseBranch } = args
+  const { item, repoId, openModalFallback, baseBranch, telemetrySource, launchSource } = args
   const store = useAppStore.getState()
   const repo = store.repos.find((r) => r.id === repoId)
   if (!repo) {
@@ -179,29 +210,83 @@ export async function launchWorkItemDirect(args: LaunchWorkItemDirectArgs): Prom
   let worktreeId: string
   let primaryTabId: string | null
   let startupPlan: ReturnType<typeof buildAgentStartupPlan> = null
+  let effectiveAgent: TuiAgent | null = null
+  let draftLaunchedNatively = false
   try {
-    const result = await store.createWorktree(repoId, workspaceName, baseBranch, finalSetupDecision)
+    const result = await store.createWorktree(
+      repoId,
+      workspaceName,
+      baseBranch,
+      finalSetupDecision,
+      undefined,
+      telemetrySource
+    )
     worktreeId = result.worktree.id
+    const worktreePath = result.worktree.path
 
     const detectedIds = new Set(await detectedAgentsPromise)
-    const effectiveAgent = pickAgent(settings?.defaultTuiAgent, detectedIds)
-    // Why: launch the agent with no prompt so the first frame it draws is the
-    // empty input box. The URL paste below populates that input buffer, which
-    // gives the user a reviewable draft instead of a submitted request.
-    startupPlan =
+    effectiveAgent = pickAgent(settings?.defaultTuiAgent, detectedIds)
+    const draftContent = item.pasteContent ?? item.url
+
+    // Why: agents that gate first-launch behind a "Do you trust this folder?"
+    // menu (cursor-agent, copilot) consume the bracketed paste as menu input.
+    // Pre-write the same trust artifact those CLIs write after the user
+    // accepts so the menu never fires. Best-effort — main swallows errors,
+    // and we guard the IPC presence so a stale preload bundle (which can
+    // ship a renderer that's ahead of the loaded preload) doesn't crash the
+    // launch with "Cannot read properties of undefined".
+    if (effectiveAgent && worktreePath && window.api.agentTrust?.markTrusted) {
+      const preflight = TUI_AGENT_CONFIG[effectiveAgent].preflightTrust
+      if (preflight) {
+        try {
+          await window.api.agentTrust.markTrusted({
+            preset: preflight,
+            workspacePath: worktreePath
+          })
+        } catch {
+          // Best-effort: continue with launch even if the trust write
+          // throws. The user can dismiss the trust menu manually.
+        }
+      }
+    }
+
+    // Why: prefer a native prefill flag (e.g. `claude --prefill <url>`) when
+    // the agent's CLI exposes one — the TUI mounts with the URL already in
+    // its input box, which sidesteps the readiness/paste race entirely. Fall
+    // back to launching with no prompt + bracketed-paste-after-ready for
+    // every other agent so the URL still lands as a draft (not auto-
+    // submitted as the first turn).
+    const draftLaunchPlan =
       effectiveAgent === null
         ? null
-        : buildAgentStartupPlan({
+        : buildAgentDraftLaunchPlan({
             agent: effectiveAgent,
-            prompt: '',
+            draft: draftContent,
             cmdOverrides: settings?.agentCmdOverrides ?? {},
-            platform: CLIENT_PLATFORM,
-            allowEmptyPromptLaunch: true
+            platform: CLIENT_PLATFORM
           })
+    if (draftLaunchPlan) {
+      startupPlan = {
+        agent: draftLaunchPlan.agent,
+        launchCommand: draftLaunchPlan.launchCommand,
+        expectedProcess: draftLaunchPlan.expectedProcess,
+        followupPrompt: null,
+        ...(draftLaunchPlan.env ? { env: draftLaunchPlan.env } : {})
+      }
+      draftLaunchedNatively = true
+    } else if (effectiveAgent !== null) {
+      startupPlan = buildAgentStartupPlan({
+        agent: effectiveAgent,
+        prompt: '',
+        cmdOverrides: settings?.agentCmdOverrides ?? {},
+        platform: CLIENT_PLATFORM,
+        allowEmptyPromptLaunch: true
+      })
+    }
 
     const activation = activateAndRevealWorktree(worktreeId, {
       setup: result.setup,
-      ...(startupPlan ? { startup: { command: startupPlan.launchCommand } } : {})
+      ...buildStartupOpts(effectiveAgent, startupPlan, launchSource)
     })
     if (!activation) {
       // Worktree vanished between create and activate — extremely unlikely but
@@ -241,105 +326,24 @@ export async function launchWorkItemDirect(args: LaunchWorkItemDirectArgs): Prom
     store.setRightSidebarOpen(true)
   }
 
-  // Why: at this point the workspace is live and the agent (if any) has been
-  // queued on `primaryTabId`. The paste step below is the only remaining
-  // draft-specific work; bail out cleanly when either prerequisite is missing.
-  if (!primaryTabId || !startupPlan) {
+  // Why: at this point the workspace is live and the agent (if any) has
+  // been queued on `primaryTabId`. The post-launch paste step below only
+  // applies to agents that lacked a native prefill flag; for agents that
+  // were launched with the URL already on argv (Claude --prefill today),
+  // the URL is in the input box already — pasting again would duplicate it.
+  if (!primaryTabId || !startupPlan || draftLaunchedNatively) {
     return
   }
 
   const content = item.pasteContent ?? item.url
-  // Why: the workspace is already created and visible; waiting up to 5s for
-  // agent readiness here kept the Create-from modal in "Creating workspace…".
-  // Continue the draft paste in the background so selection latency ends when
-  // the worktree is ready, not when the TUI input buffer is ready.
-  void pasteWorkItemDraftWhenAgentReady({ primaryTabId, startupPlan, content })
-}
-
-export type LaunchFromBranchArgs = {
-  repoId: string
-  baseBranch: string
-  /** Called when the flow cannot proceed without user input (setup policy is
-   *  `ask`, or the selected repo cannot resolve). */
-  openModalFallback: () => void
-}
-
-/**
- * Create a workspace from a specific branch with no linked work item. Skips
- * the bracketed-paste draft step — there's no URL to hand the agent, so we
- * just land the user in a fresh workspace rooted at the requested branch.
- */
-export async function launchFromBranch(args: LaunchFromBranchArgs): Promise<void> {
-  const { repoId, baseBranch, openModalFallback } = args
-  const store = useAppStore.getState()
-  const repo = store.repos.find((r) => r.id === repoId)
-  if (!repo) {
-    openModalFallback()
-    return
-  }
-
-  const settings = store.settings
-  // Why: keep agent detection off the critical path while we resolve setup
-  // policy. Worktree creation only needs the startup command at activation.
-  const detectedAgentsPromise = store.ensureDetectedAgents()
-
-  const setupResolution = await resolveSetupDecision(repoId, repo)
-  if (setupResolution.kind === 'needs-modal') {
-    openModalFallback()
-    return
-  }
-
-  const trustDecision = await ensureHooksConfirmed(useAppStore.getState(), repoId, 'setup')
-  const finalSetupDecision: SetupDecision =
-    trustDecision === 'skip' ? 'skip' : setupResolution.decision
-
-  // Why: branch-based launches don't carry a title hint, so fall back to the
-  // repo's creature-name generator — same distinct, readable default the
-  // quick-composer uses when the name field is blank.
-  const fallbackName = getSuggestedCreatureName(
-    repoId,
-    store.worktreesByRepo,
-    settings?.nestWorkspaces ?? true
-  )
-  const workspaceName = getWorkspaceSeedName({
-    explicitName: '',
-    prompt: '',
-    linkedIssueNumber: null,
-    linkedPR: null,
-    fallbackName
+  // Why: the workspace is already created and visible; do not block selection
+  // latency on agent readiness. Run the paste in the background so the
+  // "Use" CTA's spinner ends when the worktree is ready, not when the TUI
+  // input buffer is ready.
+  void pasteWorkItemDraftWhenAgentReady({
+    primaryTabId,
+    startupPlan,
+    content,
+    ...(effectiveAgent ? { agentKind: tuiAgentToAgentKind(effectiveAgent) } : {})
   })
-
-  try {
-    const result = await store.createWorktree(repoId, workspaceName, baseBranch, finalSetupDecision)
-    const detectedIds = new Set(await detectedAgentsPromise)
-    const effectiveAgent = pickAgent(settings?.defaultTuiAgent, detectedIds)
-    const startupPlan =
-      effectiveAgent === null
-        ? null
-        : buildAgentStartupPlan({
-            agent: effectiveAgent,
-            prompt: '',
-            cmdOverrides: settings?.agentCmdOverrides ?? {},
-            platform: CLIENT_PLATFORM,
-            allowEmptyPromptLaunch: true
-          })
-    const activation = activateAndRevealWorktree(result.worktree.id, {
-      setup: result.setup,
-      ...(startupPlan ? { startup: { command: startupPlan.launchCommand } } : {})
-    })
-    if (!activation) {
-      toast.error('Workspace created but could not be activated.')
-      return
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : 'Failed to create workspace.'
-    toast.error(message)
-    return
-  }
-
-  store.setSidebarOpen(true)
-  if (settings?.rightSidebarOpenByDefault) {
-    store.setRightSidebarTab('explorer')
-    store.setRightSidebarOpen(true)
-  }
 }
diff --git a/src/renderer/src/lib/new-workspace.ts b/src/renderer/src/lib/new-workspace.ts
index 619c30e03d3..0e9dfd32d92 100644
--- a/src/renderer/src/lib/new-workspace.ts
+++ b/src/renderer/src/lib/new-workspace.ts
@@ -1,4 +1,5 @@
 import { useAppStore } from '@/store'
+import { pasteDraftWhenAgentReady } from '@/lib/agent-paste-draft'
 import type { AgentStartupPlan } from '@/lib/tui-agent-startup'
 import { isShellProcess } from '@/lib/tui-agent-startup'
 import type { OrcaHooks, TaskViewPresetId } from '../../../shared/types'
@@ -195,65 +196,87 @@ export function getWorkspaceSeedName(args: {
   return 'workspace'
 }
 
+// Why: bracketed paste markers and ready-wait grace timing live in
+// agent-paste-draft.ts so the new-workspace and "Use" flows share one
+// definition of "type into the agent's input as a non-submitted draft".
+
 export async function ensureAgentStartupInTerminal(args: {
   worktreeId: string
   startup: AgentStartupPlan
 }): Promise<void> {
   const { worktreeId, startup } = args
-  if (startup.followupPrompt === null) {
+  const draftPrompt = startup.draftPrompt ?? null
+  if (startup.followupPrompt === null && draftPrompt === null) {
     return
   }
 
-  let promptInjected = false
-
+  // Why: poll until a terminal tab + PTY exists for the worktree before we
+  // can interact with it. Activation creates the tab synchronously but the
+  // PTY spawn is async, so a brief wait is normal.
+  let tabId: string | null = null
+  let ptyId: string | null = null
   for (let attempt = 0; attempt < 30; attempt += 1) {
     if (attempt > 0) {
       await new Promise((resolve) => window.setTimeout(resolve, 150))
     }
-
     const state = useAppStore.getState()
-    const tabId =
+    tabId =
       state.activeTabIdByWorktree[worktreeId] ?? state.tabsByWorktree[worktreeId]?.[0]?.id ?? null
     if (!tabId) {
       continue
     }
-
-    const ptyId = state.ptyIdsByTabId[tabId]?.[0]
-    if (!ptyId) {
-      continue
+    ptyId = state.ptyIdsByTabId[tabId]?.[0] ?? null
+    if (ptyId) {
+      break
     }
+  }
+  if (!tabId || !ptyId) {
+    return
+  }
 
+  // Why: followupPrompt is the legacy path for stdin-after-start agents
+  // (aider, goose, etc.) that need their initial prompt typed into the live
+  // 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`)
+  }
+
+  // Why: draftPrompt uses bracketed-paste so the URL lands atomically in the
+  // agent's input buffer (no per-char echo, no auto-submit). Shared with the
+  // launch-work-item-direct flow so both behave identically.
+  if (draftPrompt) {
+    await pasteDraftWhenAgentReady({
+      tabId,
+      content: draftPrompt,
+      agent: startup.agent
+    })
+  }
+}
+
+// Why: legacy followupPrompt path used `agentOwnsForeground` exclusively (with
+// a hasChildProcesses fallback after several polls). Preserve that behavior so
+// stdin-after-start agents still receive their prompt under the same
+// conditions. Returns when the agent appears ready or the budget expires.
+async function waitForAgentForeground(ptyId: string, expectedProcess: string): Promise<void> {
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    if (attempt > 0) {
+      await new Promise((resolve) => window.setTimeout(resolve, 150))
+    }
     try {
       const foreground = (await window.api.pty.getForegroundProcess(ptyId))?.toLowerCase() ?? ''
-      const agentOwnsForeground =
-        foreground === startup.expectedProcess ||
-        foreground.startsWith(`${startup.expectedProcess}.`)
-
-      if (agentOwnsForeground && !promptInjected && startup.followupPrompt) {
-        window.api.pty.write(ptyId, `${startup.followupPrompt}\r`)
-        promptInjected = true
+      const owns =
+        foreground === expectedProcess ||
+        foreground.startsWith(`${expectedProcess}.`) ||
+        foreground.endsWith(`/${expectedProcess}`)
+      if (owns) {
         return
       }
-
-      if (agentOwnsForeground && promptInjected) {
-        return
-      }
-
-      const hasChildProcesses = await window.api.pty.hasChildProcesses(ptyId)
-      if (
-        !promptInjected &&
-        startup.followupPrompt &&
-        hasChildProcesses &&
-        !isShellProcess(foreground) &&
-        attempt >= 4
-      ) {
-        // Why: the initial agent launch is already queued on the first terminal
-        // tab. Only agents without a verified startup-prompt flag need extra
-        // help here: once the TUI owns the PTY, type the draft prompt into the
-        // live session instead of launching the binary a second time.
-        window.api.pty.write(ptyId, `${startup.followupPrompt}\r`)
-        promptInjected = true
-        return
+      if (attempt >= 4 && !isShellProcess(foreground)) {
+        const hasChildProcesses = await window.api.pty.hasChildProcesses(ptyId)
+        if (hasChildProcesses) {
+          return
+        }
       }
     } catch {
       // Ignore transient PTY inspection failures and keep polling.
diff --git a/src/renderer/src/lib/pane-manager/mobile-driver-state.ts b/src/renderer/src/lib/pane-manager/mobile-driver-state.ts
new file mode 100644
index 00000000000..f6e066dd040
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/mobile-driver-state.ts
@@ -0,0 +1,52 @@
+// Why: presence-based driver state for the mobile-presence lock. Mirrors
+// the runtime's `currentDriver` map. Keyed by ptyId. Updated by an IPC
+// listener (onTerminalDriverChanged) wired from main.
+//
+// While `getDriverForPty(ptyId).kind === 'mobile'` the renderer:
+//   - drops xterm.onData (input lock)
+//   - drops xterm.onResize (resize lock)
+//   - mounts the lock banner with the "Take back" affordance
+//
+// See docs/mobile-presence-lock.md.
+
+export type DriverState =
+  | { kind: 'idle' }
+  | { kind: 'desktop' }
+  | { kind: 'mobile'; clientId: string }
+
+const driverByPtyId = new Map<string, DriverState>()
+
+type DriverChangeEvent = {
+  ptyId: string
+  driver: DriverState
+}
+type DriverChangeListener = (event: DriverChangeEvent) => void
+const changeListeners = new Set<DriverChangeListener>()
+
+export function onDriverChange(listener: DriverChangeListener): () => void {
+  changeListeners.add(listener)
+  return () => changeListeners.delete(listener)
+}
+
+function notifyChange(event: DriverChangeEvent): void {
+  for (const listener of changeListeners) {
+    listener(event)
+  }
+}
+
+export function setDriverForPty(ptyId: string, driver: DriverState): void {
+  if (driver.kind === 'idle') {
+    driverByPtyId.delete(ptyId)
+  } else {
+    driverByPtyId.set(ptyId, driver)
+  }
+  notifyChange({ ptyId, driver })
+}
+
+export function getDriverForPty(ptyId: string): DriverState {
+  return driverByPtyId.get(ptyId) ?? { kind: 'idle' }
+}
+
+export function isPtyLocked(ptyId: string): boolean {
+  return driverByPtyId.get(ptyId)?.kind === 'mobile'
+}
diff --git a/src/renderer/src/lib/pane-manager/mobile-fit-overrides.test.ts b/src/renderer/src/lib/pane-manager/mobile-fit-overrides.test.ts
index 66a4cf4cf28..69dee772077 100644
--- a/src/renderer/src/lib/pane-manager/mobile-fit-overrides.test.ts
+++ b/src/renderer/src/lib/pane-manager/mobile-fit-overrides.test.ts
@@ -202,7 +202,9 @@ describe('onOverrideChange', () => {
       ptyId: 'pty-1',
       mode: 'mobile-fit',
       cols: 49,
-      rows: 20
+      rows: 20,
+      priorCols: null,
+      priorRows: null
     })
 
     unsub()
@@ -218,7 +220,28 @@ describe('onOverrideChange', () => {
       ptyId: 'pty-1',
       mode: 'desktop-fit',
       cols: 120,
-      rows: 40
+      rows: 40,
+      priorCols: null,
+      priorRows: null
+    })
+
+    unsub()
+  })
+
+  it('passes prior mobile-fit dims to desktop-fit listeners', () => {
+    setFitOverride('pty-1', 'mobile-fit', 49, 20)
+    const listener = vi.fn()
+    const unsub = onOverrideChange(listener)
+
+    setFitOverride('pty-1', 'desktop-fit', 120, 40)
+
+    expect(listener).toHaveBeenCalledWith({
+      ptyId: 'pty-1',
+      mode: 'desktop-fit',
+      cols: 120,
+      rows: 40,
+      priorCols: 49,
+      priorRows: 20
     })
 
     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 7e5a781a081..e489069624c 100644
--- a/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
+++ b/src/renderer/src/lib/pane-manager/mobile-fit-overrides.ts
@@ -23,6 +23,13 @@ type OverrideChangeEvent = {
   mode: 'mobile-fit' | 'desktop-fit'
   cols: number
   rows: number
+  // Why: the dimensions the PTY was at *before* this event fired. For a
+  // desktop-fit transition this is the prior mobile-fit cols/rows so
+  // listeners can check whether xterm is still stuck at phone dims and
+  // needs the safety-net resize, vs. already moved on (e.g. user resized
+  // the desktop pane while mobile was active).
+  priorCols: number | null
+  priorRows: number | null
 }
 type OverrideChangeListener = (event: OverrideChangeEvent) => void
 const changeListeners = new Set<OverrideChangeListener>()
@@ -44,12 +51,20 @@ export function setFitOverride(
   cols: number,
   rows: number
 ): void {
+  const prior = overridesByPtyId.get(ptyId) ?? null
   if (mode === 'mobile-fit') {
     overridesByPtyId.set(ptyId, { mode, cols, rows })
   } else {
     overridesByPtyId.delete(ptyId)
   }
-  notifyChange({ ptyId, mode, cols, rows })
+  notifyChange({
+    ptyId,
+    mode,
+    cols,
+    rows,
+    priorCols: prior?.cols ?? null,
+    priorRows: prior?.rows ?? null
+  })
 }
 
 export function getPaneIdsForPty(ptyId: string): number[] {
diff --git a/src/renderer/src/lib/repo-slug-index.ts b/src/renderer/src/lib/repo-slug-index.ts
new file mode 100644
index 00000000000..6c14526b093
--- /dev/null
+++ b/src/renderer/src/lib/repo-slug-index.ts
@@ -0,0 +1,118 @@
+// 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.
+//
+// The index is built lazily from `window.api.gh.repoSlug({ repoPath })` —
+// the main-process resolver that reads `git remote` and classifies the
+// remote into `owner/repo`. Repos whose slug cannot be resolved (no GitHub
+// remote, SSH lookup failure) are excluded; the design doc (§Row actions)
+// says to keep the unknown-repo fallback in that case.
+//
+// The index rebuilds only when `state.repos` changes — adding or removing
+// a repo is rare enough that a full re-resolution is simpler than per-id
+// invalidation, and the underlying IPC result is itself cached by the main
+// process (`repoSlug` reads `.git/config`).
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { useAppStore } from '@/store'
+import type { Repo } from '../../../shared/types'
+
+/** 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>
+
+/** Module-scope cache keyed by 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>()
+
+/** 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)
+}
+
+/** Clear the entire slug cache. Useful for tests or full repo-list resets. */
+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
+  }
+  try {
+    const result = await window.api.gh.repoSlug({ repoPath: repo.path })
+    if (!result) {
+      slugByRepoId.set(repo.id, null)
+      return null
+    }
+    const slug = `${result.owner}/${result.repo}`.toLowerCase()
+    slugByRepoId.set(repo.id, 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)
+    return null
+  }
+}
+
+async function buildIndex(repos: Repo[]): 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 next: SlugIndex = new Map()
+  const results = await Promise.all(
+    repos.map(async (r) => ({ repo: r, slug: await resolveRepoSlug(r) }))
+  )
+  for (const { repo, slug } of results) {
+    if (slug) {
+      next.set(slug, repo)
+    }
+  }
+  return next
+}
+
+/** Returns a lookup function `(slug) => Repo | null`. 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 {
+  const repos = useAppStore((s) => s.repos)
+  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.
+  const generationRef = useRef(0)
+
+  useEffect(() => {
+    const gen = ++generationRef.current
+    void buildIndex(repos).then((next) => {
+      if (gen !== generationRef.current) {
+        return
+      }
+      setIndex(next)
+    })
+  }, [repos])
+
+  return useMemo(
+    () =>
+      (slug: string | null | undefined): Repo | null => {
+        if (!slug) {
+          return null
+        }
+        return index.get(slug.toLowerCase()) ?? null
+      },
+    [index]
+  )
+}
diff --git a/src/renderer/src/lib/telemetry.ts b/src/renderer/src/lib/telemetry.ts
index 1228bc4c88a..2bf00b879d7 100644
--- a/src/renderer/src/lib/telemetry.ts
+++ b/src/renderer/src/lib/telemetry.ts
@@ -13,23 +13,111 @@
 // invariant is what keeps the vendor out of the renderer's attack surface.
 
 import type { EventName, EventProps } from '../../../shared/telemetry-events'
+import type { TelemetryConsentState } from '../../../shared/telemetry-consent-types'
+
+// Re-exported so renderer call sites can import the mapper from this lib
+// alongside `track`. The implementation lives in `src/shared/agent-kind.ts`
+// because main-process telemetry emission needs the same mapping when it
+// receives a `TuiAgent`-derived agent kind through the spawn IPC.
+export { tuiAgentToAgentKind } from '../../../shared/agent-kind'
+
+// Why: single source-of-truth for the privacy doc URL linked from the two
+// telemetry surfaces (FirstLaunchBanner, PrivacyPane). Keeping it here — in
+// the shared telemetry lib — prevents the surfaces from drifting if the doc
+// ever moves.
+export const PRIVACY_URL = 'https://www.onorca.dev/docs/telemetry'
+
+// Why: the IPC boundary is untyped at runtime, so a malformed payload from
+// main would otherwise let the Privacy pane render on garbage. Validate the
+// `effective` discriminant (and `reason` when disabled) before trusting it;
+// fall through to `pending_banner` otherwise, matching the bridge-missing
+// fail-closed behavior below.
+function isTelemetryConsentState(x: unknown): x is TelemetryConsentState {
+  if (!x || typeof x !== 'object') {
+    return false
+  }
+  const e = (x as { effective?: unknown }).effective
+  if (e === 'enabled' || e === 'pending_banner') {
+    return true
+  }
+  if (e === 'disabled') {
+    const r = (x as { reason?: unknown }).reason
+    return r === 'do_not_track' || r === 'orca_disabled' || r === 'ci' || r === 'user_opt_out'
+  }
+  return false
+}
 
 export function track<N extends EventName>(name: N, props: EventProps<N>): void {
   // Why: telemetry must never throw into the renderer. A missing bridge
   // (tests, early init, sandboxed iframe) would turn `window.api.telemetryTrack`
   // into a synchronous TypeError that defeats the documented fire-and-forget
-  // contract. Swallow both the sync throw and any promise rejection.
+  // contract. Log (do not rethrow) on both the sync throw and any promise
+  // rejection so IPC failures leave a diagnostic breadcrumb while preserving
+  // the fire-and-forget contract — silent swallowing would let disk state
+  // drift out of sync with UI state with zero signal to anyone debugging.
   try {
-    void window.api?.telemetryTrack?.(name, props as Record<string, unknown>)?.catch(() => {})
-  } catch {
-    // Swallow — telemetry must never break the renderer.
+    void window.api?.telemetryTrack?.(name, props as Record<string, unknown>)?.catch((err) => {
+      console.warn('[telemetry] IPC track failed', err)
+    })
+  } catch (err) {
+    console.warn('[telemetry] IPC track threw synchronously', err)
   }
 }
 
-export function setOptIn(optedIn: boolean): void {
+// Returns a Promise so callers that need to order a subsequent settings
+// write after the opt-in event can `await` it. Most call sites ignore the
+// return value; the fire-and-forget contract is preserved by resolving
+// (not rejecting) on any bridge error.
+export function setOptIn(optedIn: boolean): Promise<void> {
   try {
-    void window.api?.telemetrySetOptIn?.(optedIn)?.catch(() => {})
-  } catch {
-    // Swallow — telemetry must never break the renderer.
+    return (
+      window.api?.telemetrySetOptIn?.(optedIn)?.catch((err) => {
+        console.warn('[telemetry] IPC setOptIn failed', err)
+      }) ?? Promise.resolve()
+    )
+  } catch (err) {
+    console.warn('[telemetry] IPC setOptIn threw synchronously', err)
+    return Promise.resolve()
+  }
+}
+
+// Read the effective consent state for Privacy-pane rendering. Fails
+// closed to `pending_banner` if the bridge is missing (tests, sandbox),
+// which the UI treats like a non-actionable/disabled toggle — safer than
+// pretending the toggle is live when we cannot confirm consent.
+export async function getConsentState(): Promise<TelemetryConsentState> {
+  try {
+    const result = await window.api?.telemetryGetConsentState?.()
+    return isTelemetryConsentState(result) ? result : { effective: 'pending_banner' }
+  } catch (err) {
+    console.warn('[telemetry] IPC getConsentState failed', err)
+    return { effective: 'pending_banner' }
+  }
+}
+
+// Banner ✕ — silent persisted opt-IN (acknowledge without eventing).
+// Separate channel from `setOptIn(true)` because the event contract for
+// the ✕ path is "persist optedIn=true, fire nothing." Routing this through
+// `setOptIn(true)` would derive `via='first_launch_banner'` and emit
+// `telemetry_opted_in`, which the ✕-as-silent-acknowledge semantics
+// forbid — the user did not explicitly opt in, they declined to intervene.
+// The only renderer surface that calls this bridge is the FirstLaunchBanner
+// ✕ button; the banner's "Turn off" and every other opt-{in,out} path
+// uses `setOptIn(…)` so the corresponding event still fires.
+//
+// Returns a Promise so callers that need to order a subsequent settings
+// fetch after main has persisted the acknowledge can `await` it. Most
+// call sites ignore the return value; the fire-and-forget contract is
+// preserved by resolving (not rejecting) on any bridge error.
+export function acknowledgeBanner(): Promise<void> {
+  try {
+    return (
+      window.api?.telemetryAcknowledgeBanner?.()?.catch((err) => {
+        console.warn('[telemetry] IPC acknowledgeBanner failed', err)
+      }) ?? Promise.resolve()
+    )
+  } catch (err) {
+    console.warn('[telemetry] IPC acknowledgeBanner threw synchronously', err)
+    return Promise.resolve()
   }
 }
diff --git a/src/renderer/src/lib/tui-agent-startup.test.ts b/src/renderer/src/lib/tui-agent-startup.test.ts
index b9fe47e439f..a3e41193546 100644
--- a/src/renderer/src/lib/tui-agent-startup.test.ts
+++ b/src/renderer/src/lib/tui-agent-startup.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { buildAgentStartupPlan, isShellProcess } from './tui-agent-startup'
+import {
+  buildAgentDraftLaunchPlan,
+  buildAgentStartupPlan,
+  isShellProcess
+} from './tui-agent-startup'
 
 describe('buildAgentStartupPlan', () => {
   it('passes Claude prompts as a positional interactive argument', () => {
@@ -11,6 +15,7 @@ describe('buildAgentStartupPlan', () => {
         platform: 'darwin'
       })
     ).toEqual({
+      agent: 'claude',
       launchCommand: "claude 'Fix the bug'",
       expectedProcess: 'claude',
       followupPrompt: null
@@ -26,6 +31,7 @@ describe('buildAgentStartupPlan', () => {
         platform: 'linux'
       })
     ).toEqual({
+      agent: 'gemini',
       launchCommand: "gemini --prompt-interactive 'Investigate this regression'",
       expectedProcess: 'gemini',
       followupPrompt: null
@@ -41,12 +47,29 @@ describe('buildAgentStartupPlan', () => {
         platform: 'linux'
       })
     ).toEqual({
+      agent: 'aider',
       launchCommand: 'aider',
       expectedProcess: 'aider',
       followupPrompt: 'Refactor the parser'
     })
   })
 
+  it('launches Autohand Code first and injects the draft prompt after startup', () => {
+    expect(
+      buildAgentStartupPlan({
+        agent: 'autohand',
+        prompt: 'Add tests for the parser',
+        cmdOverrides: {},
+        platform: 'linux'
+      })
+    ).toEqual({
+      agent: 'autohand',
+      launchCommand: 'autohand',
+      expectedProcess: 'autohand',
+      followupPrompt: 'Add tests for the parser'
+    })
+  })
+
   it('uses cursor-agent as the actual launch binary', () => {
     expect(
       buildAgentStartupPlan({
@@ -56,6 +79,7 @@ describe('buildAgentStartupPlan', () => {
         platform: 'darwin'
       })
     ).toEqual({
+      agent: 'cursor',
       launchCommand: "cursor-agent 'Review this file'",
       expectedProcess: 'cursor-agent',
       followupPrompt: null
@@ -71,6 +95,7 @@ describe('buildAgentStartupPlan', () => {
         platform: 'linux'
       })
     ).toEqual({
+      agent: 'droid',
       launchCommand: "/opt/factory/bin/droid 'Ship the fix'",
       expectedProcess: 'droid',
       followupPrompt: null
@@ -86,6 +111,7 @@ describe('buildAgentStartupPlan', () => {
         platform: 'darwin'
       })
     ).toEqual({
+      agent: 'copilot',
       launchCommand: "copilot -i 'Fix the bug'",
       expectedProcess: 'copilot',
       followupPrompt: null
@@ -112,6 +138,7 @@ describe('buildAgentStartupPlan', () => {
         platform: 'darwin'
       })
     ).toEqual({
+      agent: 'copilot',
       launchCommand: "copilot -i 'Fix the bug'",
       expectedProcess: 'copilot',
       followupPrompt: null
@@ -119,6 +146,81 @@ describe('buildAgentStartupPlan', () => {
   })
 })
 
+describe('buildAgentDraftLaunchPlan', () => {
+  it('uses Claude --prefill to seed the input box without submitting', () => {
+    expect(
+      buildAgentDraftLaunchPlan({
+        agent: 'claude',
+        draft: 'https://github.com/acme/repo/issues/42',
+        cmdOverrides: {},
+        platform: 'darwin'
+      })
+    ).toEqual({
+      agent: 'claude',
+      launchCommand: "claude --prefill 'https://github.com/acme/repo/issues/42'",
+      expectedProcess: 'claude'
+    })
+  })
+
+  it('returns null for agents without a documented prefill flag', () => {
+    expect(
+      buildAgentDraftLaunchPlan({
+        agent: 'codex',
+        draft: 'https://github.com/acme/repo/issues/42',
+        cmdOverrides: {},
+        platform: 'darwin'
+      })
+    ).toBeNull()
+  })
+
+  it('uses ORCA_PI_PREFILL env var for pi (no CLI flag exists)', () => {
+    // Why: pi has no `--prefill` flag, and bracketed-paste-after-ready races
+    // against pi's lengthy startup output. The Orca overlay installs an
+    // `orca-prefill` extension that reads ORCA_PI_PREFILL on session_start
+    // and seeds the editor. Plan plumbs the env var without polluting the
+    // shell command (no `FOO='...' pi` prefix typed into the terminal).
+    expect(
+      buildAgentDraftLaunchPlan({
+        agent: 'pi',
+        draft: 'https://github.com/acme/repo/issues/42',
+        cmdOverrides: {},
+        platform: 'darwin'
+      })
+    ).toEqual({
+      agent: 'pi',
+      launchCommand: 'pi',
+      expectedProcess: 'pi',
+      env: { ORCA_PI_PREFILL: 'https://github.com/acme/repo/issues/42' }
+    })
+  })
+
+  it('returns null for an empty draft so callers fall back cleanly', () => {
+    expect(
+      buildAgentDraftLaunchPlan({
+        agent: 'claude',
+        draft: '   ',
+        cmdOverrides: {},
+        platform: 'darwin'
+      })
+    ).toBeNull()
+  })
+
+  it('honors cmdOverrides so custom Claude install paths still prefill', () => {
+    expect(
+      buildAgentDraftLaunchPlan({
+        agent: 'claude',
+        draft: 'review this',
+        cmdOverrides: { claude: '/opt/anthropic/bin/claude' },
+        platform: 'linux'
+      })
+    ).toEqual({
+      agent: 'claude',
+      launchCommand: "/opt/anthropic/bin/claude --prefill 'review this'",
+      expectedProcess: 'claude'
+    })
+  })
+})
+
 describe('isShellProcess', () => {
   it('treats common shells as non-agent foreground processes', () => {
     expect(isShellProcess('bash')).toBe(true)
diff --git a/src/renderer/src/lib/tui-agent-startup.ts b/src/renderer/src/lib/tui-agent-startup.ts
index 59c64c0f04d..12226de4904 100644
--- a/src/renderer/src/lib/tui-agent-startup.ts
+++ b/src/renderer/src/lib/tui-agent-startup.ts
@@ -2,9 +2,25 @@ import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
 import type { TuiAgent } from '../../../shared/types'
 
 export type AgentStartupPlan = {
+  /** Why: surfaces the agent id so downstream paste-draft logic can resolve
+   * the per-agent draft injection strategy without re-deriving from the
+   * launch command string. */
+  agent: TuiAgent
   launchCommand: string
   expectedProcess: string
   followupPrompt: string | null
+  /** Why: text to type into the live agent input WITHOUT submitting it (no
+   * trailing \r). Used by the quick-create flow to pre-fill a linked work
+   * item URL so the user can edit/add to it before sending. Independent from
+   * `followupPrompt` so the call site can choose: type-and-submit (followup)
+   * or type-and-leave-pending (draft). */
+  draftPrompt?: string | null
+  /** Why: env vars to apply at PTY spawn time. Currently used to deliver
+   * pi's `ORCA_PI_PREFILL` so the overlay's `orca-prefill` extension
+   * picks it up on session_start. Plumbed into `startup.env` by the
+   * activation site, NOT into the shell command, so the value isn't
+   * visibly prefixed onto the terminal. */
+  env?: Record<string, string>
 }
 
 function quoteStartupArg(value: string, platform: NodeJS.Platform): string {
@@ -32,6 +48,7 @@ export function buildAgentStartupPlan(args: {
       return null
     }
     return {
+      agent,
       launchCommand: baseCommand,
       expectedProcess: config.expectedProcess,
       followupPrompt: null
@@ -42,6 +59,7 @@ export function buildAgentStartupPlan(args: {
 
   if (config.promptInjectionMode === 'argv') {
     return {
+      agent,
       launchCommand: `${baseCommand} ${quotedPrompt}`,
       expectedProcess: config.expectedProcess,
       followupPrompt: null
@@ -50,6 +68,7 @@ export function buildAgentStartupPlan(args: {
 
   if (config.promptInjectionMode === 'flag-prompt') {
     return {
+      agent,
       launchCommand: `${baseCommand} --prompt ${quotedPrompt}`,
       expectedProcess: config.expectedProcess,
       followupPrompt: null
@@ -58,6 +77,7 @@ export function buildAgentStartupPlan(args: {
 
   if (config.promptInjectionMode === 'flag-prompt-interactive') {
     return {
+      agent,
       launchCommand: `${baseCommand} --prompt-interactive ${quotedPrompt}`,
       expectedProcess: config.expectedProcess,
       followupPrompt: null
@@ -66,6 +86,7 @@ export function buildAgentStartupPlan(args: {
 
   if (config.promptInjectionMode === 'flag-interactive') {
     return {
+      agent,
       launchCommand: `${baseCommand} -i ${quotedPrompt}`,
       expectedProcess: config.expectedProcess,
       followupPrompt: null
@@ -73,6 +94,7 @@ export function buildAgentStartupPlan(args: {
   }
 
   return {
+    agent,
     launchCommand: baseCommand,
     expectedProcess: config.expectedProcess,
     // Why: several agent TUIs either lack a documented "start interactive
@@ -83,4 +105,62 @@ export function buildAgentStartupPlan(args: {
   }
 }
 
+export type AgentDraftLaunchPlan = {
+  agent: TuiAgent
+  launchCommand: string
+  expectedProcess: string
+  /** Why: env-var-based prefill (currently pi via the overlay-installed
+   * `orca-prefill` extension) ships the draft text in the PTY-spawn
+   * environment instead of via a CLI flag. Callers MUST plumb this into
+   * the queued `startup.env` so it reaches the shell that launches the
+   * agent. Empty/undefined when the agent uses a CLI flag (Claude). */
+  env?: Record<string, string>
+}
+
+/**
+ * Why: when the agent's CLI exposes a documented "prefill but don't submit"
+ * flag (currently only `claude --prefill <text>`), launch with that flag so
+ * the TUI mounts with the draft already in its input box. This is strictly
+ * better than the post-launch bracketed-paste fallback in agent-paste-draft.ts
+ * because it eliminates the empirical readiness wait entirely — the agent
+ * controls when its input is rendered.
+ *
+ * Returns `null` when the agent has no native prefill flag; callers fall
+ * back to the paste-after-ready path.
+ */
+export function buildAgentDraftLaunchPlan(args: {
+  agent: TuiAgent
+  draft: string
+  cmdOverrides: Partial<Record<TuiAgent, string>>
+  platform: NodeJS.Platform
+}): AgentDraftLaunchPlan | null {
+  const { agent, draft, cmdOverrides, platform } = args
+  const config = TUI_AGENT_CONFIG[agent]
+  const trimmed = draft.trim()
+  if (!trimmed) {
+    return null
+  }
+  const baseCommand = cmdOverrides[agent] ?? config.launchCmd
+  if (config.draftPromptFlag) {
+    const quoted = quoteStartupArg(trimmed, platform)
+    return {
+      agent,
+      launchCommand: `${baseCommand} ${config.draftPromptFlag} ${quoted}`,
+      expectedProcess: config.expectedProcess
+    }
+  }
+  if (config.draftPromptEnvVar) {
+    // Why: the env var is set on the PTY-spawn env (not embedded in the
+    // shell command) so the value never has to be shell-escaped and the
+    // user doesn't see a `FOO='...'` prefix typed into their terminal.
+    return {
+      agent,
+      launchCommand: baseCommand,
+      expectedProcess: config.expectedProcess,
+      env: { [config.draftPromptEnvVar]: trimmed }
+    }
+  }
+  return null
+}
+
 export { isShellProcess } from '../../../shared/agent-detection'
diff --git a/src/renderer/src/lib/worktree-activation.test.ts b/src/renderer/src/lib/worktree-activation.test.ts
index ecb917a500a..26199221f59 100644
--- a/src/renderer/src/lib/worktree-activation.test.ts
+++ b/src/renderer/src/lib/worktree-activation.test.ts
@@ -111,6 +111,34 @@ describe('ensureWorktreeHasInitialTerminal', () => {
     expect(store.queueTabIssueCommandSplit).not.toHaveBeenCalled()
   })
 
+  it('forwards telemetry on the queued startup so main can fire agent_started', () => {
+    const store = createMockStore()
+
+    ensureWorktreeHasInitialTerminal(
+      store,
+      'wt-1',
+      {
+        command: 'claude',
+        telemetry: {
+          agent_kind: 'claude-code',
+          launch_source: 'new_workspace_composer',
+          request_kind: 'new'
+        }
+      },
+      undefined,
+      undefined
+    )
+
+    expect(store.queueTabStartupCommand).toHaveBeenCalledWith('tab-1', {
+      command: 'claude',
+      telemetry: {
+        agent_kind: 'claude-code',
+        launch_source: 'new_workspace_composer',
+        request_kind: 'new'
+      }
+    })
+  })
+
   it('does not create a terminal just because the legacy terminal slice is empty', () => {
     const store = createMockStore({
       tabsByWorktree: { 'wt-1': [] },
diff --git a/src/renderer/src/lib/worktree-activation.ts b/src/renderer/src/lib/worktree-activation.ts
index b9228bc68c0..f78de0d2aa2 100644
--- a/src/renderer/src/lib/worktree-activation.ts
+++ b/src/renderer/src/lib/worktree-activation.ts
@@ -1,4 +1,5 @@
 import type { SetupSplitDirection, WorktreeSetupLaunch } from '../../../shared/types'
+import type { EventProps } from '../../../shared/telemetry-events'
 import { shouldAutoCreateInitialTerminal } from '@/components/terminal/initial-terminal'
 import { buildSetupRunnerCommand } from './setup-runner'
 import { useAppStore } from '@/store'
@@ -8,6 +9,11 @@ import {
   setWorktreeNavViewActivator
 } from '@/store/slices/worktree-nav-history'
 
+/** Telemetry payload threaded from the launch site to `pty:spawn`. Main
+ *  fires `agent_started` only after the spawn succeeds — see
+ *  telemetry-plan.md§Agent launch semantics. */
+export type AgentStartedTelemetry = EventProps<'agent_started'>
+
 // Why: issue commands can originate from two sources with different shapes —
 // (1) a repo-level runner script generated by main (WorktreeSetupLaunch), or
 // (2) a user-typed command template substituted in the TaskPage flow.
@@ -30,7 +36,11 @@ type WorktreeActivationStore = {
   reconcileWorktreeTabModel: (worktreeId: string) => { renderableTabCount: number }
   queueTabStartupCommand: (
     tabId: string,
-    startup: { command: string; env?: Record<string, string> }
+    startup: {
+      command: string
+      env?: Record<string, string>
+      telemetry?: AgentStartedTelemetry
+    }
   ) => void
   queueTabSetupSplit: (
     tabId: string,
@@ -65,7 +75,11 @@ export type ActivateAndRevealResult = {
 export function activateAndRevealWorktree(
   worktreeId: string,
   opts?: {
-    startup?: { command: string; env?: Record<string, string> }
+    startup?: {
+      command: string
+      env?: Record<string, string>
+      telemetry?: AgentStartedTelemetry
+    }
     setup?: WorktreeSetupLaunch
     issueCommand?: IssueCommandLaunch
   }
@@ -133,7 +147,7 @@ export function activateAndRevealWorktree(
 export function ensureWorktreeHasInitialTerminal(
   store: WorktreeActivationStore,
   worktreeId: string,
-  startup?: { command: string; env?: Record<string, string> },
+  startup?: { command: string; env?: Record<string, string>; telemetry?: AgentStartedTelemetry },
   setup?: WorktreeSetupLaunch,
   issueCommand?: IssueCommandLaunch
 ): string | null {
diff --git a/src/renderer/src/main.tsx b/src/renderer/src/main.tsx
index 49cd7d81b4c..52f96613e4b 100644
--- a/src/renderer/src/main.tsx
+++ b/src/renderer/src/main.tsx
@@ -3,20 +3,14 @@ import './assets/main.css'
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import App from './App'
+import { applyDocumentTheme } from './lib/document-theme'
 
 if (import.meta.env.DEV) {
   import('react-grab').then(({ init }) => init())
   import('react-grab/styles.css')
 }
 
-// Respect system dark mode preference
-function applySystemTheme(): void {
-  const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches
-  document.documentElement.classList.toggle('dark', isDark)
-}
-
-applySystemTheme()
-window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', applySystemTheme)
+applyDocumentTheme('system', { disableTransitions: false })
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
diff --git a/src/renderer/src/store/slices/github.ts b/src/renderer/src/store/slices/github.ts
index 227e4071e21..e77901aba9f 100644
--- a/src/renderer/src/store/slices/github.ts
+++ b/src/renderer/src/store/slices/github.ts
@@ -14,9 +14,233 @@ import type {
   Worktree,
   GitHubWorkItem
 } from '../../../../shared/types'
+import type {
+  GetProjectViewTableArgs,
+  GetProjectViewTableResult,
+  GitHubProjectFieldMutationValue,
+  GitHubProjectMutationResult,
+  GitHubProjectRow,
+  GitHubProjectTable,
+  GitHubProjectViewError
+} from '../../../../shared/github-project-types'
 import { sortWorkItemsByUpdatedAt, PER_REPO_FETCH_LIMIT } from '../../../../shared/work-items'
 import { syncPRChecksStatus } from './github-checks'
 
+// ─── ProjectV2 cache types ────────────────────────────────────────────
+// Why: declared separately from CacheEntry<T> (not a generified E parameter)
+// because project-view has a single GraphQL source — no issue/PR-source
+// fallback — and the error union is distinct. Shared structural shape only.
+export type ProjectViewCacheEntry<T> = {
+  data: T | null
+  fetchedAt: number
+  error?: GitHubProjectViewError
+}
+
+export type ProjectRowContentUpdate = {
+  title?: string
+  body?: string
+  addLabels?: string[]
+  removeLabels?: string[]
+  addAssignees?: string[]
+  removeAssignees?: string[]
+}
+
+/** Optimistic, IPC-free patch shape for `projectViewCache` rows.
+ *  Why: the dialog already issues mutations via slug-addressed IPCs and only
+ *  needs to keep the Project table view in sync optimistically. Replacing
+ *  `addLabels`/`removeLabels` deltas with full `labels`/`assignees` arrays
+ *  matches what the dialog's local state already tracks (`localLabels`,
+ *  `localAssignees`) and avoids redundant set-merge logic at the call site. */
+export type ProjectRowContentPatch = {
+  title?: string
+  body?: string
+  /** Why: accept the renderer's lowercase work-item state vocabulary
+   *  ('open' | 'closed' | 'merged' | 'draft') and translate to GitHub's
+   *  UPPERCASE row.content.state when applying. The reducer only writes
+   *  what callers send; merged/draft are passed through for completeness
+   *  even though the dialog edits only flip open↔closed today. */
+  state?: 'open' | 'closed' | 'merged' | 'draft'
+  labels?: string[]
+  assignees?: string[]
+}
+
+// Why: queryOverride participates in the cache key so an overridden search
+// does not clobber the default-view cache entry, and vice versa. `undefined`
+// means "use the view's stored filter" — the unfiltered cache entry. An
+// empty string is a *distinct* override meaning "no filter", which produces
+// different rows when the view's stored filter is non-empty, so it gets its
+// own cache key.
+function queryOverrideKeyPart(queryOverride: string | undefined): string {
+  if (queryOverride === undefined) {
+    return ''
+  }
+  return `:q=${queryOverride}`
+}
+
+export function projectViewCacheKey(
+  ownerType: GetProjectViewTableArgs['ownerType'],
+  owner: string,
+  projectNumber: number,
+  resolvedViewId: string,
+  queryOverride?: string
+): string {
+  return `github-project:${ownerType}:${owner}:${projectNumber}:${resolvedViewId}${queryOverrideKeyPart(queryOverride)}`
+}
+
+function projectViewRequestKey(args: GetProjectViewTableArgs): string {
+  // Why: callers without `viewId` can't compute the resolved cache key up
+  // front. Use the input-arg signature for inflight dedup; the resolved
+  // cache key is only known after the main-process IPC returns.
+  const selector = args.viewId
+    ? `id:${args.viewId}`
+    : args.viewNumber !== undefined
+      ? `num:${args.viewNumber}`
+      : args.viewName
+        ? `name:${args.viewName}`
+        : 'default'
+  return `${args.ownerType}:${args.owner}:${args.projectNumber}:${selector}${queryOverrideKeyPart(args.queryOverride)}`
+}
+
+// Why: module-scope inflight map — must mirror `inflightWorkItemsRequests`
+// (dedup + force-refresh semantics). Reuses the work-item concurrency gate:
+// the gate exists to bound `gh` subprocess pressure at the renderer boundary,
+// and project-view fetches pressure the same subprocess budget. Two separate
+// gates would let concurrent Project + work-item fetches blow past the cap.
+const inflightProjectViewRequests = new Map<
+  string,
+  { promise: Promise<GetProjectViewTableResult>; force: boolean }
+>()
+
+// Why: derive an optimistic GitHubProjectFieldValue from a mutation value so
+// the patched row re-renders immediately. Single-select and iteration lookups
+// consult the field config on the cached table; the result is best-effort and
+// is overwritten by the authoritative payload on next refresh.
+function optimisticFieldValueFromMutation(
+  table: GitHubProjectTable,
+  fieldId: string,
+  value: GitHubProjectFieldMutationValue
+): GitHubProjectTable['rows'][number]['fieldValuesByFieldId'][string] | null {
+  const field = table.selectedView.fields.find((f) => f.id === fieldId)
+  switch (value.kind) {
+    case 'single-select': {
+      if (field?.kind === 'single-select') {
+        const option = field.options.find((o) => o.id === value.optionId)
+        if (option) {
+          return {
+            kind: 'single-select',
+            fieldId,
+            optionId: option.id,
+            name: option.name,
+            color: option.color
+          }
+        }
+      }
+      return {
+        kind: 'single-select',
+        fieldId,
+        optionId: value.optionId,
+        name: '',
+        color: ''
+      }
+    }
+    case 'iteration': {
+      if (field?.kind === 'iteration') {
+        const iteration = field.iterations.find((i) => i.id === value.iterationId)
+        if (iteration) {
+          return {
+            kind: 'iteration',
+            fieldId,
+            iterationId: iteration.id,
+            title: iteration.title,
+            startDate: iteration.startDate,
+            duration: iteration.duration
+          }
+        }
+      }
+      return {
+        kind: 'iteration',
+        fieldId,
+        iterationId: value.iterationId,
+        title: '',
+        startDate: '',
+        duration: 0
+      }
+    }
+    case 'text':
+      return { kind: 'text', fieldId, text: value.text }
+    case 'number':
+      return { kind: 'number', fieldId, number: value.number }
+    case 'date':
+      return { kind: 'date', fieldId, date: value.date }
+    default:
+      return null
+  }
+}
+
+function applyRowPatch(
+  set: (fn: (s: AppState) => Partial<AppState>) => void,
+  cacheKey: string,
+  rowId: string,
+  nextRow: GitHubProjectRow
+): void {
+  set((s) => {
+    const entry = s.projectViewCache[cacheKey]
+    if (!entry?.data) {
+      return {}
+    }
+    const rowIndex = entry.data.rows.findIndex((r) => r.id === rowId)
+    if (rowIndex === -1) {
+      return {}
+    }
+    const rows = [...entry.data.rows]
+    rows[rowIndex] = nextRow
+    return {
+      projectViewCache: {
+        ...s.projectViewCache,
+        [cacheKey]: {
+          ...entry,
+          data: { ...entry.data, rows }
+        }
+      }
+    }
+  })
+}
+
+function rollbackRowIfPresent(
+  set: (fn: (s: AppState) => Partial<AppState>) => void,
+  get: () => AppState,
+  cacheKey: string,
+  rowId: string,
+  previousRow: GitHubProjectRow
+): void {
+  // Why: the cache entry may have moved (rapid project switch) or the row may
+  // no longer exist by the time the mutation response returns. Skip rollback
+  // in that case — resurrecting stale data into a newly selected project would
+  // show the wrong row.
+  const entry = get().projectViewCache[cacheKey]
+  if (!entry?.data) {
+    return
+  }
+  const stillPresent = entry.data.rows.some((r) => r.id === rowId)
+  if (!stillPresent) {
+    return
+  }
+  applyRowPatch(set, cacheKey, rowId, previousRow)
+}
+
+function parseSlugAndNumber(
+  row: GitHubProjectRow
+): { owner: string; repo: string; number: number } | null {
+  if (!row.content.repository || row.content.number == null) {
+    return null
+  }
+  const parts = row.content.repository.split('/')
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    return null
+  }
+  return { owner: parts[0], repo: parts[1], number: row.content.number }
+}
+
 export type WorkItemsCacheSources = {
   issues: GitHubOwnerRepo | null
   prs: GitHubOwnerRepo | null
@@ -183,7 +407,7 @@ export type GitHubSlice = {
   fetchPRForBranch: (
     repoPath: string,
     branch: string,
-    options?: FetchOptions
+    options?: FetchOptions & { linkedPRNumber?: number | null }
   ) => Promise<PRInfo | null>
   fetchIssue: (repoPath: string, number: number) => Promise<IssueInfo | null>
   fetchPRChecks: (
@@ -311,6 +535,40 @@ export type GitHubSlice = {
     repoPath: string,
     preference: IssueSourcePreference
   ) => Promise<void>
+  // ── ProjectV2 view cache ─────────────────────────────────────────────
+  projectViewCache: Record<string, ProjectViewCacheEntry<GitHubProjectTable>>
+  fetchProjectViewTable: (
+    args: GetProjectViewTableArgs,
+    options?: FetchOptions
+  ) => Promise<GetProjectViewTableResult>
+  updateProjectFieldValue: (
+    cacheKey: string,
+    rowId: string,
+    fieldId: string,
+    value: GitHubProjectFieldMutationValue
+  ) => Promise<GitHubProjectMutationResult>
+  clearProjectFieldValue: (
+    cacheKey: string,
+    rowId: string,
+    fieldId: string
+  ) => Promise<GitHubProjectMutationResult>
+  patchProjectIssueOrPr: (
+    cacheKey: string,
+    rowId: string,
+    updates: ProjectRowContentUpdate
+  ) => Promise<GitHubProjectMutationResult>
+  patchProjectRowIssueType: (
+    cacheKey: string,
+    rowId: string,
+    issueType: { id: string; name: string; color: string | null; description: string | null } | null
+  ) => Promise<GitHubProjectMutationResult>
+  /** Optimistic, IPC-free patcher for a single `projectViewCache` row's
+   *  `content`. Used by GitHubItemDialog when `projectOrigin` is set so the
+   *  Project table re-renders immediately after dialog edits — `patchWorkItem`
+   *  alone only walks `workItemsCache` and would leave the Project view stale
+   *  until the next refresh. The actual write is dispatched separately via
+   *  the slug-addressed update IPCs. */
+  patchProjectRowContent: (cacheKey: string, rowId: string, patch: ProjectRowContentPatch) => void
 }
 
 export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (set, get) => ({
@@ -320,6 +578,380 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   commentsCache: {},
   workItemsCache: {},
   workItemsInvalidationNonce: 0,
+  projectViewCache: {},
+
+  fetchProjectViewTable: async (args, options) => {
+    const requestKey = projectViewRequestKey(args)
+
+    // Fast path: when the caller supplies `viewId`, we already know the
+    // resolved cache key and can serve a fresh entry directly.
+    const maybeKnownKey = args.viewId
+      ? projectViewCacheKey(
+          args.ownerType,
+          args.owner,
+          args.projectNumber,
+          args.viewId,
+          args.queryOverride
+        )
+      : null
+    if (!options?.force && maybeKnownKey) {
+      const cached = get().projectViewCache[maybeKnownKey]
+      if (cached?.data && Date.now() - cached.fetchedAt < WORK_ITEMS_CACHE_TTL) {
+        return { ok: true, data: cached.data }
+      }
+    }
+
+    const existing = inflightProjectViewRequests.get(requestKey)
+    if (existing) {
+      // Why: mirror fetchWorkItems force-refresh semantics — a forcing caller
+      // must not silently dedupe to a non-forcing in-flight request; wait for
+      // that to settle (result discarded) and then issue a fresh forced call.
+      if (options?.force && !existing.force) {
+        await existing.promise.catch(() => {})
+      } else {
+        return existing.promise
+      }
+    }
+
+    const request = (async (): Promise<GetProjectViewTableResult> => {
+      await acquireWorkItemSlot()
+      try {
+        const envelope = await window.api.gh.getProjectViewTable(args)
+        if (envelope.ok) {
+          const table = envelope.data
+          const key = projectViewCacheKey(
+            table.project.ownerType,
+            table.project.owner,
+            table.project.number,
+            table.selectedView.id,
+            args.queryOverride
+          )
+          set((s) => ({
+            projectViewCache: {
+              ...s.projectViewCache,
+              [key]: { data: table, fetchedAt: Date.now() }
+            }
+          }))
+        } else if (maybeKnownKey) {
+          // Only stamp the error onto the cache when we have a resolved key
+          // (i.e. caller supplied viewId). Otherwise we have nowhere to write
+          // it — the renderer classifies the error directly from the envelope.
+          set((s) => ({
+            projectViewCache: {
+              ...s.projectViewCache,
+              [maybeKnownKey]: {
+                data: s.projectViewCache[maybeKnownKey]?.data ?? null,
+                fetchedAt: Date.now(),
+                error: envelope.error
+              }
+            }
+          }))
+        }
+        return envelope
+      } catch (err) {
+        // Why: IPC boundary must not throw across the promise — wrap any
+        // unexpected error in the classified envelope so the renderer has
+        // a single shape to render.
+        console.error('Failed to fetch GitHub project view:', err)
+        return {
+          ok: false,
+          error: {
+            type: 'unknown',
+            message: err instanceof Error ? err.message : 'Failed to fetch project view'
+          }
+        }
+      } finally {
+        releaseWorkItemSlot()
+        inflightProjectViewRequests.delete(requestKey)
+      }
+    })()
+
+    inflightProjectViewRequests.set(requestKey, {
+      promise: request,
+      force: Boolean(options?.force)
+    })
+    return request
+  },
+
+  updateProjectFieldValue: async (cacheKey, rowId, fieldId, value) => {
+    const state = get()
+    const entry = state.projectViewCache[cacheKey]
+    const table = entry?.data
+    if (!table) {
+      return {
+        ok: false,
+        error: { type: 'unknown', message: 'Project view not loaded' }
+      }
+    }
+    const rowIndex = table.rows.findIndex((r) => r.id === rowId)
+    if (rowIndex === -1) {
+      return {
+        ok: false,
+        error: { type: 'unknown', message: 'Row not found' }
+      }
+    }
+    const previousRow = table.rows[rowIndex]
+    // Optimistic patch: build a field value matching the mutation shape.
+    const nextField = optimisticFieldValueFromMutation(table, fieldId, value)
+    const optimisticFieldValues = { ...previousRow.fieldValuesByFieldId }
+    if (nextField) {
+      optimisticFieldValues[fieldId] = nextField
+    }
+    const optimisticRow: GitHubProjectRow = {
+      ...previousRow,
+      fieldValuesByFieldId: optimisticFieldValues
+    }
+    applyRowPatch(set, cacheKey, rowId, optimisticRow)
+
+    const result = await window.api.gh.updateProjectItemField({
+      projectId: table.project.id,
+      itemId: rowId,
+      fieldId,
+      value
+    })
+    if (!result.ok) {
+      rollbackRowIfPresent(set, get, cacheKey, rowId, previousRow)
+    }
+    return result
+  },
+
+  clearProjectFieldValue: async (cacheKey, rowId, fieldId) => {
+    const state = get()
+    const entry = state.projectViewCache[cacheKey]
+    const table = entry?.data
+    if (!table) {
+      return {
+        ok: false,
+        error: { type: 'unknown', message: 'Project view not loaded' }
+      }
+    }
+    const rowIndex = table.rows.findIndex((r) => r.id === rowId)
+    if (rowIndex === -1) {
+      return {
+        ok: false,
+        error: { type: 'unknown', message: 'Row not found' }
+      }
+    }
+    const previousRow = table.rows[rowIndex]
+    const optimisticFieldValues = { ...previousRow.fieldValuesByFieldId }
+    delete optimisticFieldValues[fieldId]
+    const optimisticRow: GitHubProjectRow = {
+      ...previousRow,
+      fieldValuesByFieldId: optimisticFieldValues
+    }
+    applyRowPatch(set, cacheKey, rowId, optimisticRow)
+
+    const result = await window.api.gh.clearProjectItemField({
+      projectId: table.project.id,
+      itemId: rowId,
+      fieldId
+    })
+    if (!result.ok) {
+      rollbackRowIfPresent(set, get, cacheKey, rowId, previousRow)
+    }
+    return result
+  },
+
+  patchProjectIssueOrPr: async (cacheKey, rowId, updates) => {
+    const state = get()
+    const entry = state.projectViewCache[cacheKey]
+    const table = entry?.data
+    if (!table) {
+      return {
+        ok: false,
+        error: { type: 'unknown', message: 'Project view not loaded' }
+      }
+    }
+    const rowIndex = table.rows.findIndex((r) => r.id === rowId)
+    if (rowIndex === -1) {
+      return {
+        ok: false,
+        error: { type: 'unknown', message: 'Row not found' }
+      }
+    }
+    const previousRow = table.rows[rowIndex]
+    const { owner, repo, number } = parseSlugAndNumber(previousRow) ?? {}
+    if (!owner || !repo || !number) {
+      return {
+        ok: false,
+        error: {
+          type: 'validation_error',
+          message: 'Row has no owner/repo/number — cannot patch underlying item'
+        }
+      }
+    }
+    // Optimistic content patch.
+    const nextContent = { ...previousRow.content }
+    if (updates.title !== undefined) {
+      nextContent.title = updates.title
+    }
+    if (updates.body !== undefined) {
+      nextContent.body = updates.body
+    }
+    if (updates.addLabels || updates.removeLabels) {
+      const next = new Map(nextContent.labels.map((l) => [l.name, l]))
+      for (const name of updates.addLabels ?? []) {
+        if (!next.has(name)) {
+          next.set(name, { name, color: '808080' })
+        }
+      }
+      for (const name of updates.removeLabels ?? []) {
+        next.delete(name)
+      }
+      nextContent.labels = Array.from(next.values())
+    }
+    if (updates.addAssignees || updates.removeAssignees) {
+      const next = new Map(nextContent.assignees.map((u) => [u.login, u]))
+      for (const login of updates.addAssignees ?? []) {
+        if (!next.has(login)) {
+          next.set(login, { login, name: null, avatarUrl: null })
+        }
+      }
+      for (const login of updates.removeAssignees ?? []) {
+        next.delete(login)
+      }
+      nextContent.assignees = Array.from(next.values())
+    }
+    const optimisticRow: GitHubProjectRow = { ...previousRow, content: nextContent }
+    applyRowPatch(set, cacheKey, rowId, optimisticRow)
+
+    // Why: PRs and issues both accept label/assignee edits through the issue
+    // endpoint — GitHub PRs are issues for labels/assignees. Title/body for
+    // PRs goes through updatePullRequestBySlug; for issues through
+    // updateIssueBySlug. We dispatch both as needed.
+    let envelope: GitHubProjectMutationResult = { ok: true }
+    if (
+      previousRow.itemType === 'PULL_REQUEST' &&
+      (updates.title !== undefined || updates.body !== undefined)
+    ) {
+      const prRes = await window.api.gh.updatePullRequestBySlug({
+        owner,
+        repo,
+        number,
+        updates: {
+          ...(updates.title !== undefined ? { title: updates.title } : {}),
+          ...(updates.body !== undefined ? { body: updates.body } : {})
+        }
+      })
+      if (!prRes.ok) {
+        envelope = prRes
+      }
+    }
+    if (
+      envelope.ok &&
+      (updates.addLabels?.length ||
+        updates.removeLabels?.length ||
+        updates.addAssignees?.length ||
+        updates.removeAssignees?.length ||
+        (previousRow.itemType === 'ISSUE' &&
+          (updates.title !== undefined || updates.body !== undefined)))
+    ) {
+      const issueRes = await window.api.gh.updateIssueBySlug({
+        owner,
+        repo,
+        number,
+        updates: {
+          ...(updates.title !== undefined ? { title: updates.title } : {}),
+          ...(updates.body !== undefined ? { body: updates.body } : {}),
+          ...(updates.addLabels ? { addLabels: updates.addLabels } : {}),
+          ...(updates.removeLabels ? { removeLabels: updates.removeLabels } : {}),
+          ...(updates.addAssignees ? { addAssignees: updates.addAssignees } : {}),
+          ...(updates.removeAssignees ? { removeAssignees: updates.removeAssignees } : {})
+        }
+      })
+      if (!issueRes.ok) {
+        envelope = issueRes
+      }
+    }
+    if (!envelope.ok) {
+      rollbackRowIfPresent(set, get, cacheKey, rowId, previousRow)
+    }
+    return envelope
+  },
+
+  patchProjectRowIssueType: async (cacheKey, rowId, issueType) => {
+    const state = get()
+    const entry = state.projectViewCache[cacheKey]
+    const table = entry?.data
+    if (!table) {
+      return { ok: false, error: { type: 'unknown', message: 'Project view not loaded' } }
+    }
+    const row = table.rows.find((r) => r.id === rowId)
+    if (!row) {
+      return { ok: false, error: { type: 'unknown', message: 'Row not found' } }
+    }
+    if (row.itemType !== 'ISSUE') {
+      return {
+        ok: false,
+        error: { type: 'validation_error', message: 'Issue Type can only be set on Issues.' }
+      }
+    }
+    const { owner, repo, number } = parseSlugAndNumber(row) ?? {}
+    if (!owner || !repo || !number) {
+      return {
+        ok: false,
+        error: { type: 'validation_error', message: 'Row has no owner/repo/number.' }
+      }
+    }
+    const previousRow = row
+    const optimistic: GitHubProjectRow = {
+      ...previousRow,
+      content: { ...previousRow.content, issueType }
+    }
+    applyRowPatch(set, cacheKey, rowId, optimistic)
+    const res = await window.api.gh.updateIssueTypeBySlug({
+      owner,
+      repo,
+      number,
+      issueTypeId: issueType?.id ?? null
+    })
+    if (!res.ok) {
+      rollbackRowIfPresent(set, get, cacheKey, rowId, previousRow)
+    }
+    return res
+  },
+
+  patchProjectRowContent: (cacheKey, rowId, patch) => {
+    const state = get()
+    const entry = state.projectViewCache[cacheKey]
+    const table = entry?.data
+    if (!table) {
+      return
+    }
+    const previousRow = table.rows.find((r) => r.id === rowId)
+    if (!previousRow) {
+      return
+    }
+    const nextContent = { ...previousRow.content }
+    if (patch.title !== undefined) {
+      nextContent.title = patch.title
+    }
+    if (patch.body !== undefined) {
+      nextContent.body = patch.body
+    }
+    if (patch.state !== undefined) {
+      // Why: ProjectV2 row.state mirrors GitHub's UPPERCASE state enum
+      // ('OPEN' | 'CLOSED' | 'MERGED'). The dialog tracks lowercase
+      // ('open' | 'closed') matching `GitHubWorkItem['state']`. Translate
+      // here so the optimistic patch matches the canonical row shape and
+      // the next authoritative fetch overwrites cleanly.
+      nextContent.state = patch.state.toUpperCase()
+    }
+    if (patch.labels !== undefined) {
+      const existingByName = new Map(previousRow.content.labels.map((l) => [l.name, l]))
+      nextContent.labels = patch.labels.map(
+        (name) => existingByName.get(name) ?? { name, color: '808080' }
+      )
+    }
+    if (patch.assignees !== undefined) {
+      const existingByLogin = new Map(previousRow.content.assignees.map((u) => [u.login, u]))
+      nextContent.assignees = patch.assignees.map(
+        (login) => existingByLogin.get(login) ?? { login, name: null, avatarUrl: null }
+      )
+    }
+    const nextRow: GitHubProjectRow = { ...previousRow, content: nextContent }
+    applyRowPatch(set, cacheKey, rowId, nextRow)
+  },
 
   getCachedWorkItems: (repoPath, limit, query) => {
     const key = workItemsCacheKey(repoPath, limit, query)
@@ -549,21 +1181,27 @@ export const createGitHubSlice: StateCreator<AppState, [], [], GitHubSlice> = (s
   fetchPRForBranch: async (repoPath, branch, options): Promise<PRInfo | null> => {
     const cacheKey = `${repoPath}::${branch}`
     const cached = get().prCache[cacheKey]
-    if (!options?.force && isFresh(cached)) {
+    // 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
+    // return null forever. Refetch when the cached miss could now resolve via
+    // the linkedPR path.
+    const linkedRefetch = cached?.data === null && (options?.linkedPRNumber ?? null) !== null
+    if (!options?.force && !linkedRefetch && isFresh(cached)) {
       return cached.data
     }
 
     const inflightRequest = inflightPRRequests.get(cacheKey)
-    if (inflightRequest && (!options?.force || inflightRequest.force)) {
+    if (inflightRequest && (!options?.force || inflightRequest.force) && !linkedRefetch) {
       return inflightRequest.promise
     }
 
     const generation = (prRequestGenerations.get(cacheKey) ?? 0) + 1
     prRequestGenerations.set(cacheKey, generation)
 
+    const linkedPRNumber = options?.linkedPRNumber ?? null
     const request = (async () => {
       try {
-        const pr = await window.api.gh.prForBranch({ repoPath, branch })
+        const pr = await window.api.gh.prForBranch({ repoPath, branch, linkedPRNumber })
         if (prRequestGenerations.get(cacheKey) === generation) {
           set((s) => ({
             prCache: { ...s.prCache, [cacheKey]: { data: pr, fetchedAt: Date.now() } }
diff --git a/src/renderer/src/store/slices/memory.ts b/src/renderer/src/store/slices/memory.ts
index 2349fecdc0a..b24de6d0c89 100644
--- a/src/renderer/src/store/slices/memory.ts
+++ b/src/renderer/src/store/slices/memory.ts
@@ -4,18 +4,26 @@ import type { MemorySnapshot } from '../../../../shared/types'
 
 export type MemorySlice = {
   memorySnapshot: MemorySnapshot | null
+  memorySnapshotError: string | null
   fetchMemorySnapshot: () => Promise<void>
 }
 
 export const createMemorySlice: StateCreator<AppState, [], [], MemorySlice> = (set) => ({
   memorySnapshot: null,
+  memorySnapshotError: null,
 
   fetchMemorySnapshot: async () => {
     try {
       const snapshot = await window.api.memory.getSnapshot()
-      set({ memorySnapshot: snapshot })
+      set({ memorySnapshot: snapshot, memorySnapshotError: null })
     } catch (err) {
+      // Why: the always-on Resource Usage 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)
+      set({
+        memorySnapshotError: err instanceof Error ? err.message : String(err)
+      })
     }
   }
 })
diff --git a/src/renderer/src/store/slices/repos.ts b/src/renderer/src/store/slices/repos.ts
index f203a36b6c4..dceeb8c43c9 100644
--- a/src/renderer/src/store/slices/repos.ts
+++ b/src/renderer/src/store/slices/repos.ts
@@ -23,6 +23,7 @@ export type RepoSlice = {
         | 'hookSettings'
         | 'worktreeBaseRef'
         | 'kind'
+        | 'symlinkPaths'
         | 'issueSourcePreference'
       >
     >
diff --git a/src/renderer/src/store/slices/settings.ts b/src/renderer/src/store/slices/settings.ts
index 37a88db8a0e..b6aa9216d6b 100644
--- a/src/renderer/src/store/slices/settings.ts
+++ b/src/renderer/src/store/slices/settings.ts
@@ -27,18 +27,34 @@ export const createSettingsSlice: StateCreator<AppState, [], [], SettingsSlice>
   updateSettings: async (updates) => {
     try {
       await window.api.settings.set(updates)
-      set((s) => ({
-        settings: s.settings
-          ? {
-              ...s.settings,
-              ...updates,
-              notifications: {
-                ...s.settings.notifications,
-                ...updates.notifications
-              }
-            }
-          : null
-      }))
+      set((s) => {
+        if (!s.settings) {
+          return { settings: null }
+        }
+        // Deep-merge telemetry so partial writes do not clobber sibling
+        // fields like `installId`, `existedBeforeTelemetryRelease`, or
+        // `optedIn` in local renderer state until the next fetchSettings.
+        // Mirrors the main-side merge in src/main/persistence.ts:551-573.
+        // `telemetry` is optional on GlobalSettings, so guard against the case
+        // where both current and incoming telemetry are undefined — otherwise
+        // the spread would produce an empty object and we'd materialize a
+        // telemetry key that shouldn't exist.
+        const mergedTelemetry =
+          updates.telemetry !== undefined
+            ? { ...s.settings.telemetry, ...updates.telemetry }
+            : s.settings.telemetry
+        return {
+          settings: {
+            ...s.settings,
+            ...updates,
+            notifications: {
+              ...s.settings.notifications,
+              ...updates.notifications
+            },
+            ...(mergedTelemetry !== undefined ? { telemetry: mergedTelemetry } : {})
+          }
+        }
+      })
     } catch (err) {
       console.error('Failed to update settings:', err)
     }
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index e3b068fecf8..3555aec408e 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -8,6 +8,7 @@ import type {
   Worktree,
   WorkspaceSessionState
 } from '../../../../shared/types'
+import type { AgentStartedTelemetry } from '../../lib/worktree-activation'
 import { scheduleRuntimeGraphSync } from '@/runtime/sync-runtime-graph'
 import { clearTransientTerminalState, emptyLayoutSnapshot } from './terminal-helpers'
 import { isClaudeAgent, detectAgentStatusFromTitle } from '@/lib/agent-status'
@@ -24,6 +25,7 @@ import {
   ensurePtyDispatcher,
   unregisterPtyDataHandlers
 } from '@/components/terminal-pane/pty-transport'
+import { shutdownBufferCaptures } from '@/components/terminal-pane/shutdown-buffer-captures'
 
 function getNextTerminalOrdinal(tabs: TerminalTab[]): number {
   const usedOrdinals = new Set<number>()
@@ -80,7 +82,17 @@ export type TerminalSlice = {
   expandedPaneByTabId: Record<string, boolean>
   canExpandPaneByTabId: Record<string, boolean>
   terminalLayoutsByTabId: Record<string, TerminalLayoutSnapshot>
-  pendingStartupByTabId: Record<string, { command: string; env?: Record<string, string> }>
+  pendingStartupByTabId: Record<
+    string,
+    {
+      command: string
+      env?: Record<string, string>
+      /** Telemetry metadata for the `agent_started` event. Threaded all the
+       *  way to the `pty:spawn` IPC handler in main so the event fires only
+       *  after spawn confirms — never on click-intent. */
+      telemetry?: AgentStartedTelemetry
+    }
+  >
   /** Queued setup-split requests — when present, TerminalPane creates the
    *  initial pane clean, then splits (vertical or horizontal per user setting)
    *  and runs the command in the new pane so the main terminal stays
@@ -149,7 +161,10 @@ export type TerminalSlice = {
   setTabColor: (tabId: string, color: string | null) => void
   updateTabPtyId: (tabId: string, ptyId: string) => void
   clearTabPtyId: (tabId: string, ptyId?: string) => void
-  shutdownWorktreeTerminals: (worktreeId: string) => Promise<void>
+  shutdownWorktreeTerminals: (
+    worktreeId: string,
+    opts?: { keepIdentifiers?: boolean }
+  ) => Promise<void>
   suppressPtyExit: (ptyId: string) => void
   consumeSuppressedPtyExit: (ptyId: string) => boolean
   queueCodexPaneRestarts: (ptyIds: string[]) => void
@@ -163,11 +178,15 @@ export type TerminalSlice = {
   setTabLayout: (tabId: string, layout: TerminalLayoutSnapshot | null) => void
   queueTabStartupCommand: (
     tabId: string,
-    startup: { command: string; env?: Record<string, string> }
+    startup: {
+      command: string
+      env?: Record<string, string>
+      telemetry?: AgentStartedTelemetry
+    }
   ) => void
   consumeTabStartupCommand: (
     tabId: string
-  ) => { command: string; env?: Record<string, string> } | null
+  ) => { command: string; env?: Record<string, string>; telemetry?: AgentStartedTelemetry } | null
   queueTabSetupSplit: (
     tabId: string,
     startup: { command: string; env?: Record<string, string>; direction: SetupSplitDirection }
@@ -951,7 +970,8 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
     }
   },
 
-  shutdownWorktreeTerminals: async (worktreeId) => {
+  shutdownWorktreeTerminals: async (worktreeId, opts) => {
+    const keepIdentifiers = opts?.keepIdentifiers ?? false
     const tabs = get().tabsByWorktree[worktreeId] ?? []
     const ptyIds = tabs.flatMap((tab) => get().ptyIdsByTabId[tab.id] ?? [])
 
@@ -964,52 +984,94 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
     // Removing the data handlers first ensures the final flush is a no-op.
     unregisterPtyDataHandlers(ptyIds)
 
-    set((s) => {
-      const nextTabsByWorktree = {
-        ...s.tabsByWorktree,
-        [worktreeId]: (s.tabsByWorktree[worktreeId] ?? []).map((tab, index) =>
-          clearTransientTerminalState(tab, index)
-        )
+    // Why (ordering invariant — DESIGN_DOC §3.3.c): on sleep, capture every
+    // pane's serializer buffer into terminalLayoutsByTabId[tab].buffersByLeafId
+    // BEFORE issuing pty.kill (panes unmount on PTY exit and their
+    // serializeAddons go with them) AND BEFORE the set() block below (the
+    // capture writes through to the store via its own setTabLayout call; any
+    // subsequent set must use a functional updater spreading
+    // s.terminalLayoutsByTabId, not a captured snapshot). For SSH this is
+    // load-bearing — the relay drops the remote PTY on kill so there's no
+    // on-disk history dir to cold-restore from. For local daemon it's
+    // defense-in-depth alongside the on-disk history dir preserved by
+    // keepHistory below.
+    if (keepIdentifiers) {
+      for (const tab of tabs) {
+        const capture = shutdownBufferCaptures.get(tab.id)
+        if (capture) {
+          try {
+            capture()
+          } catch {
+            // Don't let one tab's capture failure block the rest.
+          }
+        }
       }
+    }
+
+    set((s) => {
+      const nextTabsByWorktree = keepIdentifiers
+        ? s.tabsByWorktree
+        : {
+            ...s.tabsByWorktree,
+            [worktreeId]: (s.tabsByWorktree[worktreeId] ?? []).map((tab, index) =>
+              clearTransientTerminalState(tab, index)
+            )
+          }
       const nextPtyIdsByTabId = {
         ...s.ptyIdsByTabId,
         ...Object.fromEntries(tabs.map((tab) => [tab.id, [] as string[]] as const))
       }
-      const nextRuntimePaneTitlesByTabId = { ...s.runtimePaneTitlesByTabId }
+      const nextRuntimePaneTitlesByTabId = keepIdentifiers
+        ? s.runtimePaneTitlesByTabId
+        : { ...s.runtimePaneTitlesByTabId }
       const nextSuppressedPtyExitIds = {
         ...s.suppressedPtyExitIds,
         ...Object.fromEntries(ptyIds.map((ptyId) => [ptyId, true] as const))
       }
-      const nextPendingCodexPaneRestartIds = { ...s.pendingCodexPaneRestartIds }
+      // Why: pendingCodexPaneRestartIds is keyed by ptyId — under sleep we
+      // preserve it so a mid-restart marker survives wake against the same
+      // identifier. codexRestartNoticeByPtyId is also keyed by the now-stale
+      // ptyId; on wake the post-spawn ptyId may differ, so the notice can't
+      // be carried forward and is cleared in both cases.
+      const nextPendingCodexPaneRestartIds = keepIdentifiers
+        ? s.pendingCodexPaneRestartIds
+        : { ...s.pendingCodexPaneRestartIds }
       const nextCodexRestartNoticeByPtyId = { ...s.codexRestartNoticeByPtyId }
       for (const ptyId of ptyIds) {
-        delete nextPendingCodexPaneRestartIds[ptyId]
+        if (!keepIdentifiers) {
+          delete nextPendingCodexPaneRestartIds[ptyId]
+        }
         delete nextCodexRestartNoticeByPtyId[ptyId]
       }
-      // Why: clear any queued setup and issue-command splits for the affected
-      // tabs so stale commands do not fire unintended splits when the worktree
-      // is later remounted.
+      // Why: setup-split and issue-command-split are transient one-shots that
+      // drive new-tab UX. They are not sleep-recovery state; clear in both
+      // cases.
       const nextPendingSetupSplitByTabId = { ...s.pendingSetupSplitByTabId }
       const nextPendingIssueCommandSplitByTabId = { ...s.pendingIssueCommandSplitByTabId }
-      // Why: layout snapshots carry `ptyIdsByLeafId` so in-session remounts
-      // (e.g. tab-group moves) can reattach to live PTYs. After shutdown these
-      // bindings point at killed PTY IDs; if we leave them, the next remount
-      // takes the reattach branch in connectPanePty and produces a visible
-      // but non-interactive "zombie" pane. Clearing the per-leaf binding
-      // forces a fresh spawn when the user returns to the worktree.
+      // Why: under remove-worktree (default), layout snapshots carry
+      // `ptyIdsByLeafId` referencing now-dead PTY IDs; if we leave them, the
+      // next remount takes the reattach branch in connectPanePty and produces
+      // a visible but non-interactive "zombie" pane. Under sleep
+      // (keepIdentifiers), we preserve `ptyIdsByLeafId` precisely so wake can
+      // pass them as args.sessionId to pty.spawn and reattach to the daemon
+      // history dir (or, on SSH, restore scrollback from buffersByLeafId
+      // captured above).
       const nextTerminalLayoutsByTabId = { ...s.terminalLayoutsByTabId }
-      // Why: unread dots survive across worktree switches by design, but a full
-      // shutdown tears down the PTYs behind them — the dot would point at a
-      // tab that is no longer running and cannot be cleared by focus because
-      // focus events for a killed pane never arrive. Drop them here so a later
-      // remount starts clean.
-      // Why: preserve the unreadTerminalTabs reference when none of the shutting-
-      // down tabs had an unread flag — avoids a no-op top-level state allocation
-      // that would force re-evaluation of full-state selectors on unrelated
-      // shutdown calls. Mirrors the sibling pattern in tabs.ts.
+      // Why: unread dots survive across worktree switches by design, but a
+      // full shutdown tears down the PTYs behind them. Even under sleep, the
+      // PTYs are killed, so unread state pointing at dead ptyIds is stale —
+      // clear in both cases. (Carrying the dot across sleep would also be
+      // surprising and inconsistent with how it behaves on tab close.)
+      // Why: preserve the unreadTerminalTabs reference when none of the
+      // shutting-down tabs had an unread flag — avoids a no-op top-level
+      // state allocation that would force re-evaluation of full-state
+      // selectors on unrelated shutdown calls. Mirrors the sibling pattern
+      // in tabs.ts.
       let nextUnreadTerminalTabs = s.unreadTerminalTabs
       for (const tab of tabs) {
-        delete nextRuntimePaneTitlesByTabId[tab.id]
+        if (!keepIdentifiers) {
+          delete nextRuntimePaneTitlesByTabId[tab.id]
+        }
         delete nextPendingSetupSplitByTabId[tab.id]
         delete nextPendingIssueCommandSplitByTabId[tab.id]
         if (nextUnreadTerminalTabs[tab.id]) {
@@ -1018,22 +1080,29 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
           }
           delete nextUnreadTerminalTabs[tab.id]
         }
-        const existingLayout = nextTerminalLayoutsByTabId[tab.id]
-        if (existingLayout?.ptyIdsByLeafId) {
-          nextTerminalLayoutsByTabId[tab.id] = {
-            ...existingLayout,
-            ptyIdsByLeafId: {}
+        if (!keepIdentifiers) {
+          const existingLayout = nextTerminalLayoutsByTabId[tab.id]
+          if (existingLayout?.ptyIdsByLeafId) {
+            nextTerminalLayoutsByTabId[tab.id] = {
+              ...existingLayout,
+              ptyIdsByLeafId: {}
+            }
           }
         }
       }
 
-      // Why: intentional shutdown kills the relay PTY. Remove the tab's
-      // lastKnown entry so session-save does not persist a dead session ID
-      // into remoteSessionIdsByTabId, which would cause the next restart
-      // to attempt reattaching to a PTY that no longer exists.
-      const nextLastKnownRelay = { ...s.lastKnownRelayPtyIdByTabId }
-      for (const tab of tabs) {
-        delete nextLastKnownRelay[tab.id]
+      // Why: under remove-worktree, intentional shutdown kills the relay PTY
+      // and persisting a dead session ID would cause next-restart reattach to
+      // fail. Under sleep, wake re-spawns over the relay against this exact
+      // session ID — preserving it is what lets the wake-side wiring stay
+      // consistent.
+      const nextLastKnownRelay = keepIdentifiers
+        ? s.lastKnownRelayPtyIdByTabId
+        : { ...s.lastKnownRelayPtyIdByTabId }
+      if (!keepIdentifiers) {
+        for (const tab of tabs) {
+          delete nextLastKnownRelay[tab.id]
+        }
       }
 
       return {
@@ -1056,20 +1125,25 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
       }
     })
 
-    // Why: sleep keeps the tab records (so wake restores them) but kills the
-    // PTYs, and there is no implicit "PTY death drops agent-status rows" path
-    // — closeTab and pane-close drop their own rows explicitly. Without the
-    // same explicit sweep here, a worktree slept in the 'done' state leaves
-    // live/retained entries behind and WorktreeCard's dot stays blue.
-    for (const tab of tabs) {
-      get().dropAgentStatusByTabPrefix(tab.id)
+    // Why: under remove-worktree, sweep agent-status rows so a tab killed in
+    // the 'done' state doesn't leave the WorktreeCard dot blue. Under sleep,
+    // the agent-status describes the live agent process which the user
+    // expects to survive sleep — skip the drop so wake renders the prior
+    // status until the next event arrives. (Mirror of the pattern in
+    // closeTab / pane-close, which drop their own rows explicitly.)
+    if (!keepIdentifiers) {
+      for (const tab of tabs) {
+        get().dropAgentStatusByTabPrefix(tab.id)
+      }
     }
 
     if (ptyIds.length === 0) {
       return
     }
 
-    await Promise.allSettled(ptyIds.map((ptyId) => window.api.pty.kill(ptyId)))
+    await Promise.allSettled(
+      ptyIds.map((ptyId) => window.api.pty.kill(ptyId, { keepHistory: keepIdentifiers }))
+    )
   },
 
   consumeSuppressedPtyExit: (ptyId) => {
diff --git a/src/renderer/src/store/slices/ui.test.ts b/src/renderer/src/store/slices/ui.test.ts
index 017497cc476..cdb9f0168ec 100644
--- a/src/renderer/src/store/slices/ui.test.ts
+++ b/src/renderer/src/store/slices/ui.test.ts
@@ -1,11 +1,16 @@
 import { createStore, type StoreApi } from 'zustand/vanilla'
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { getDefaultUIState } from '../../../../shared/constants'
 import type { PersistedUIState } from '../../../../shared/types'
 import { createUISlice } from './ui'
 import { createWorktreeNavHistorySlice } from './worktree-nav-history'
 import type { AppState } from '../types'
 
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
 function createUIStore(): StoreApi<AppState> {
   // Only the UI slice, repo ids, and right sidebar width fallback are needed
   // for persisted UI hydration tests. The worktree-nav-history slice is also
@@ -109,6 +114,41 @@ describe('createUISlice hydratePersistedUI', () => {
 
     expect(store.getState().hideDefaultBranchWorkspace).toBe(true)
   })
+
+  it('sanitizes task resume state field-by-field during hydration', () => {
+    const store = createUIStore()
+
+    store.getState().hydratePersistedUI(
+      makePersistedUI({
+        taskResumeState: {
+          githubMode: 'project',
+          githubItemsPreset: 'invalid',
+          githubItemsQuery: 42,
+          linearPreset: 'completed',
+          linearQuery: 'label:bug'
+        } as unknown as PersistedUIState['taskResumeState']
+      })
+    )
+
+    expect(store.getState().taskResumeState).toEqual({
+      githubMode: 'project',
+      linearPreset: 'completed',
+      linearQuery: 'label:bug'
+    })
+  })
+
+  it('merges and persists partial task resume updates', () => {
+    const setUI = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('window', { api: { ui: { set: setUI } } })
+    const store = createUIStore()
+
+    store.setState({ taskResumeState: { githubMode: 'project', linearPreset: 'all' } })
+    store.getState().setTaskResumeState({ githubItemsPreset: 'my-prs' })
+
+    const expected = { githubMode: 'project', linearPreset: 'all', githubItemsPreset: 'my-prs' }
+    expect(store.getState().taskResumeState).toEqual(expected)
+    expect(setUI).toHaveBeenCalledWith({ taskResumeState: expected })
+  })
 })
 
 describe('createUISlice settings navigation', () => {
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index 37728199c18..df60ce89b8c 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -8,12 +8,33 @@ import type {
   PersistedTrustedOrcaHooks,
   PersistedUIState,
   StatusBarItem,
+  TaskResumeState,
   TaskViewPresetId,
   TuiAgent,
   UpdateStatus,
   WorktreeCardProperty
 } from '../../../../shared/types'
+import {
+  SIDEKICK_SIZE_DEFAULT,
+  SIDEKICK_SIZE_MAX,
+  SIDEKICK_SIZE_MIN
+} from '../../../../shared/types'
 import { PER_REPO_FETCH_LIMIT } from '../../../../shared/work-items'
+import {
+  DEFAULT_STATUS_BAR_ITEMS,
+  DEFAULT_WORKTREE_CARD_PROPERTIES
+} from '../../../../shared/constants'
+import type { OrcaHookScriptKind } from '../../lib/orca-hook-trust'
+import { DEFAULT_SIDEKICK_ID, isBundledSidekickId } from '../../components/sidekick/sidekick-models'
+import { revokeCustomSidekickBlobUrl } from '../../components/sidekick/sidekick-blob-cache'
+import { isGitRepoKind } from '../../../../shared/repo-kind'
+
+function clampSidekickSize(size: number): number {
+  if (!Number.isFinite(size)) {
+    return SIDEKICK_SIZE_DEFAULT
+  }
+  return Math.max(SIDEKICK_SIZE_MIN, Math.min(SIDEKICK_SIZE_MAX, Math.round(size)))
+}
 
 // Why: mirrors the preset→query mapping used by TaskPage's preset buttons.
 // Keeping a local copy here avoids a store ↔ lib circular import while letting
@@ -34,13 +55,21 @@ function presetToQuery(presetId: TaskViewPresetId | null): string {
       return 'is:open'
   }
 }
-import {
-  DEFAULT_STATUS_BAR_ITEMS,
-  DEFAULT_WORKTREE_CARD_PROPERTIES
-} from '../../../../shared/constants'
-import type { OrcaHookScriptKind } from '../../lib/orca-hook-trust'
-import { DEFAULT_SIDEKICK_ID, isBundledSidekickId } from '../../components/sidekick/sidekick-models'
-import { revokeCustomSidekickBlobUrl } from '../../components/sidekick/sidekick-blob-cache'
+// Why: persisted UI state pre-dated the consolidation of `memory` + `sessions`
+// into a single `resource-usage` entry. Rewrite legacy ids in place and
+// de-duplicate. We leave unknown ids alone so a downgrade→upgrade cycle
+// doesn't strip a newer build's ids out of the user's settings.
+function migrateStatusBarItems(items: readonly string[] | undefined): StatusBarItem[] {
+  const source = items ?? DEFAULT_STATUS_BAR_ITEMS
+  const out: string[] = []
+  for (const id of source) {
+    const mapped = id === 'memory' || id === 'sessions' ? 'resource-usage' : id
+    if (!out.includes(mapped)) {
+      out.push(mapped)
+    }
+  }
+  return out as StatusBarItem[]
+}
 
 const MIN_SIDEBAR_WIDTH = 220
 const MAX_LEFT_SIDEBAR_WIDTH = 500
@@ -49,6 +78,20 @@ const MAX_LEFT_SIDEBAR_WIDTH = 500
 // cap on wide displays. Use a large hard ceiling purely as a safety net for
 // corrupted/manually-edited values rather than as a product limit.
 const MAX_RIGHT_SIDEBAR_WIDTH = 4000
+const VALID_TASK_PRESETS = new Set<TaskViewPresetId>([
+  'all',
+  'issues',
+  'review',
+  'my-issues',
+  'my-prs',
+  'prs'
+])
+const VALID_LINEAR_PRESETS = new Set<NonNullable<TaskResumeState['linearPreset']>>([
+  'assigned',
+  'created',
+  'all',
+  'completed'
+])
 
 function filterTrustedOrcaHooksToValidRepos(
   trust: PersistedTrustedOrcaHooks,
@@ -70,6 +113,39 @@ function sanitizePersistedSidebarWidth(width: unknown, fallback: number, maxWidt
   return Math.min(maxWidth, Math.max(MIN_SIDEBAR_WIDTH, width))
 }
 
+function sanitizeTaskResumeState(value: unknown): TaskResumeState | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined
+  }
+  const input = value as Record<string, unknown>
+  const next: TaskResumeState = {}
+
+  if (input.githubMode === 'items' || input.githubMode === 'project') {
+    next.githubMode = input.githubMode
+  }
+  if (input.githubItemsPreset === null) {
+    next.githubItemsPreset = null
+  } else if (typeof input.githubItemsPreset === 'string') {
+    if (VALID_TASK_PRESETS.has(input.githubItemsPreset as TaskViewPresetId)) {
+      next.githubItemsPreset = input.githubItemsPreset as TaskViewPresetId
+    }
+  }
+  if (typeof input.githubItemsQuery === 'string') {
+    next.githubItemsQuery = input.githubItemsQuery
+  }
+  if (
+    typeof input.linearPreset === 'string' &&
+    VALID_LINEAR_PRESETS.has(input.linearPreset as NonNullable<TaskResumeState['linearPreset']>)
+  ) {
+    next.linearPreset = input.linearPreset as NonNullable<TaskResumeState['linearPreset']>
+  }
+  if (typeof input.linearQuery === 'string') {
+    next.linearQuery = input.linearQuery
+  }
+
+  return Object.keys(next).length > 0 ? next : undefined
+}
+
 export type UISlice = {
   sidebarOpen: boolean
   sidebarWidth: number
@@ -100,6 +176,8 @@ export type UISlice = {
     prefilledName?: string
     taskSource?: 'github' | 'linear'
   }
+  taskResumeState: TaskResumeState | undefined
+  setTaskResumeState: (updates: Partial<TaskResumeState>) => void
   newWorkspaceDraft: {
     repoId: string | null
     name: string
@@ -158,17 +236,6 @@ export type UISlice = {
   modalData: Record<string, unknown>
   openModal: (modal: UISlice['activeModal'], data?: Record<string, unknown>) => void
   closeModal: () => void
-  /** Active tab inside the new-workspace composer modal. Mutable while the
-   *  modal is open so Cmd+N / Cmd+Shift+N can toggle tabs without tearing
-   *  down the composer state. */
-  newWorkspaceComposerTab: 'quick' | 'create-from'
-  setNewWorkspaceComposerTab: (tab: 'quick' | 'create-from') => void
-  /** Remembered sub-tab inside the Create-from tab (PRs / Issues / Branches /
-   *  Linear). Persists across composer opens within a session so users who
-   *  always start from Linear (for example) don't have to click back to that
-   *  tab every time. */
-  createFromSubTab: 'prs' | 'issues' | 'branches' | 'linear'
-  setCreateFromSubTab: (tab: 'prs' | 'issues' | 'branches' | 'linear') => void
   trustedOrcaHooks: PersistedTrustedOrcaHooks
   markOrcaHookScriptConfirmed: (
     repoId: string,
@@ -209,6 +276,11 @@ export type UISlice = {
   customSidekicks: CustomSidekick[]
   addCustomSidekick: (model: CustomSidekick) => void
   removeCustomSidekick: (id: string) => void
+  /** Sidekick overlay size in CSS pixels (square). User-adjustable from the
+   *  status-bar menu so a too-big imported sprite isn't a stuck-on-screen
+   *  problem. */
+  sidekickSize: number
+  setSidekickSize: (size: number) => void
   pendingRevealWorktreeId: string | null
   revealWorktreeInSidebar: (worktreeId: string) => void
   clearPendingRevealWorktreeId: () => void
@@ -293,6 +365,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
   previousViewBeforeSettings: 'terminal',
   setActiveView: (view) => set({ activeView: view }),
   taskPageData: {},
+  taskResumeState: undefined,
   newWorkspaceDraft: null,
   openTaskPage: (data = {}) => {
     // Why: record a Tasks visit in the shared back/forward history so the
@@ -314,14 +387,48 @@ 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 targetRepoId =
-      data.preselectedRepoId ?? state.activeRepoId ?? state.repos.find((r) => r.path)?.id ?? null
-    const repo = targetRepoId ? state.repos.find((r) => r.id === targetRepoId) : null
-    if (repo?.path) {
-      const preset = state.settings?.defaultTaskViewPreset ?? 'all'
-      state.prefetchWorkItems(repo.id, repo.path, PER_REPO_FETCH_LIMIT, presetToQuery(preset))
+    const resolvedSource = data.taskSource ?? state.settings?.defaultTaskSource ?? 'github'
+    const resolvedMode = state.taskResumeState?.githubMode ?? 'items'
+    if (resolvedSource === 'github' && resolvedMode === 'items') {
+      const eligibleRepos = state.repos.filter((repo) => isGitRepoKind(repo) && repo.path)
+      const selectedRepos = (() => {
+        const preferred = data.preselectedRepoId
+        if (preferred) {
+          const repo = eligibleRepos.find((r) => r.id === preferred)
+          return repo ? [repo] : []
+        }
+        const persisted = state.settings?.defaultRepoSelection
+        if (Array.isArray(persisted)) {
+          const selected = eligibleRepos.filter((repo) => persisted.includes(repo.id))
+          if (selected.length > 0) {
+            return selected
+          }
+        }
+        return eligibleRepos
+      })()
+
+      const resume = state.taskResumeState
+      const defaultPreset = state.settings?.defaultTaskViewPreset ?? 'all'
+      // Why: must match the exact query TaskPage's resume effect mounts with,
+      // otherwise the warm cache key (e.g. 'is:open') misses the page's actual
+      // fetch key (e.g. '') and the prefetch is wasted. When the user has an
+      // explicit cleared custom search (preset === null), preserve the empty
+      // query so both sides agree.
+      const query =
+        resume?.githubItemsPreset === null
+          ? (resume.githubItemsQuery ?? '').trim()
+          : presetToQuery(resume?.githubItemsPreset ?? defaultPreset)
+      for (const repo of selectedRepos) {
+        state.prefetchWorkItems(repo.id, repo.path, PER_REPO_FETCH_LIMIT, query)
+      }
     }
   },
+  setTaskResumeState: (updates) =>
+    set((s) => {
+      const next = { ...s.taskResumeState, ...updates }
+      window.api.ui.set({ taskResumeState: next }).catch(console.error)
+      return { taskResumeState: next }
+    }),
   closeTaskPage: () =>
     set((state) => {
       // Why: Esc-close from Tasks must rewind the history index if we're
@@ -369,27 +476,8 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
 
   activeModal: 'none',
   modalData: {},
-  openModal: (modal, data = {}) => {
-    // Why: when the new-workspace composer opens, seed its active tab from
-    // modalData.initialTab so Cmd+Shift+N lands directly on the "Create from…"
-    // tab without the Quick tab flashing first. Default to 'quick' when no
-    // explicit target is provided so existing callers keep their behavior.
-    if (modal === 'new-workspace-composer') {
-      const requestedTab = (data as { initialTab?: 'quick' | 'create-from' }).initialTab
-      set({
-        activeModal: modal,
-        modalData: data,
-        newWorkspaceComposerTab: requestedTab ?? 'quick'
-      })
-      return
-    }
-    set({ activeModal: modal, modalData: data })
-  },
+  openModal: (modal, data = {}) => set({ activeModal: modal, modalData: data }),
   closeModal: () => set({ activeModal: 'none', modalData: {} }),
-  newWorkspaceComposerTab: 'quick',
-  setNewWorkspaceComposerTab: (tab) => set({ newWorkspaceComposerTab: tab }),
-  createFromSubTab: 'prs',
-  setCreateFromSubTab: (tab) => set({ createFromSubTab: tab }),
 
   trustedOrcaHooks: {},
   markOrcaHookScriptConfirmed: (repoId, kind, contentHash) =>
@@ -511,6 +599,13 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
     set({ sidekickId: id })
   },
 
+  sidekickSize: SIDEKICK_SIZE_DEFAULT,
+  setSidekickSize: (size) => {
+    const clamped = clampSidekickSize(size)
+    window.api.ui.set({ sidekickSize: clamped }).catch(console.error)
+    set({ sidekickSize: clamped })
+  },
+
   customSidekicks: [],
   addCustomSidekick: (model) =>
     set((s) => {
@@ -525,13 +620,18 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         return s
       }
       const next = s.customSidekicks.filter((m) => m.id !== id)
-      window.api.ui.set({ customSidekicks: next }).catch(console.error)
       // Why: if the user removes the currently-active custom sidekick, fall
       // back to the bundled default so the overlay doesn't render nothing.
       const fallback = s.sidekickId === id ? DEFAULT_SIDEKICK_ID : s.sidekickId
-      if (fallback !== s.sidekickId) {
-        window.api.ui.set({ sidekickId: fallback }).catch(console.error)
+      // Why: send a single combined IPC update so customSidekicks and
+      // sidekickId persist atomically when both change.
+      const ipcPayload: { customSidekicks: CustomSidekick[]; sidekickId?: string } = {
+        customSidekicks: next
       }
+      if (fallback !== s.sidekickId) {
+        ipcPayload.sidekickId = fallback
+      }
+      window.api.ui.set(ipcPayload).catch(console.error)
       // Why: revoke the cached blob: URL so the underlying Blob is released;
       // otherwise it stays in memory for the rest of the session.
       revokeCustomSidekickBlobUrl(id)
@@ -539,8 +639,12 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
       // fails, the orphaned image stays in userData; each import uses a fresh
       // UUID so the file won't be hit again, and the renderer's metadata
       // index no longer references it.
-      window.api.sidekick.delete(id, target.fileName).catch(console.error)
-      return { customSidekicks: next, sidekickId: fallback }
+      window.api.sidekick.delete(id, target.fileName, target.kind).catch(console.error)
+      const partial: Partial<UISlice> = { customSidekicks: next }
+      if (fallback !== s.sidekickId) {
+        partial.sidekickId = fallback
+      }
+      return partial
     }),
 
   pendingRevealWorktreeId: null,
@@ -592,12 +696,13 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         uiZoomLevel: ui.uiZoomLevel ?? 0,
         editorFontZoomLevel: ui.editorFontZoomLevel ?? 0,
         worktreeCardProperties: ui.worktreeCardProperties ?? [...DEFAULT_WORKTREE_CARD_PROPERTIES],
-        statusBarItems: ui.statusBarItems ?? [...DEFAULT_STATUS_BAR_ITEMS],
+        statusBarItems: migrateStatusBarItems(ui.statusBarItems),
         statusBarVisible: ui.statusBarVisible ?? true,
         // Why: absent → true so existing users see the sidekick the first time
         // they enable the experimental flag. Only an explicit Hide sidekick
         // dismissal persists a `false` value.
         sidekickVisible: ui.sidekickVisible ?? true,
+        sidekickSize: clampSidekickSize(ui.sidekickSize ?? SIDEKICK_SIZE_DEFAULT),
         customSidekicks: Array.isArray(ui.customSidekicks) ? ui.customSidekicks : [],
         // Why: accept the persisted id if it matches a bundled sidekick or a
         // known custom one; otherwise fall back so the overlay never renders
@@ -620,6 +725,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         updateReassuranceSeen: ui.updateReassuranceSeen ?? false,
         browserDefaultUrl: ui.browserDefaultUrl ?? null,
         browserDefaultSearchEngine: ui.browserDefaultSearchEngine ?? null,
+        taskResumeState: sanitizeTaskResumeState(ui.taskResumeState),
         trustedOrcaHooks: filterTrustedOrcaHooksToValidRepos(
           ui.trustedOrcaHooks ?? {},
           validRepoIds
diff --git a/src/renderer/src/store/slices/worktree-helpers.ts b/src/renderer/src/store/slices/worktree-helpers.ts
index adf6a35c39c..1f4d4502675 100644
--- a/src/renderer/src/store/slices/worktree-helpers.ts
+++ b/src/renderer/src/store/slices/worktree-helpers.ts
@@ -2,6 +2,7 @@ import type {
   CreateWorktreeResult,
   CreateSparseCheckoutRequest,
   SetupDecision,
+  WorkspaceCreateTelemetrySource,
   Worktree,
   WorktreeMeta
 } from '../../../../shared/types'
@@ -59,7 +60,11 @@ export type WorktreeSlice = {
     name: string,
     baseBranch?: string,
     setupDecision?: SetupDecision,
-    sparseCheckout?: CreateSparseCheckoutRequest
+    sparseCheckout?: CreateSparseCheckoutRequest,
+    /** Telemetry-only: which renderer surface initiated this create. Optional
+     *  so existing callers default to `unknown`; specify when the surface
+     *  matters for the activation funnel. */
+    telemetrySource?: WorkspaceCreateTelemetrySource
   ) => 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 4e8a4ccf3b6..57b10152722 100644
--- a/src/renderer/src/store/slices/worktrees.test.ts
+++ b/src/renderer/src/store/slices/worktrees.test.ts
@@ -779,14 +779,28 @@ describe('markWorktreeVisited', () => {
     expect(store.getState().lastVisitedAtByWorktreeId['wt-1']).toBe(existing)
   })
 
-  it('pruneLastVisitedTimestamps drops entries for unknown worktree IDs', () => {
+  it('pruneLastVisitedTimestamps drops entries for unknown worktree IDs within hydrated repos', () => {
     const store = createTestStore()
     const wt = makeWorktree({ id: 'repo1::/a', repoId: 'repo1', path: '/a' })
     store.setState({
       worktreesByRepo: { repo1: [wt] },
-      lastVisitedAtByWorktreeId: { 'repo1::/a': 100, 'stale-id': 200 }
+      lastVisitedAtByWorktreeId: { 'repo1::/a': 100, 'repo1::/gone': 200 }
     } as Partial<AppState>)
     store.getState().pruneLastVisitedTimestamps()
     expect(store.getState().lastVisitedAtByWorktreeId).toEqual({ 'repo1::/a': 100 })
   })
+
+  it('pruneLastVisitedTimestamps preserves entries for not-yet-hydrated repos (e.g. SSH pre-connect)', () => {
+    const store = createTestStore()
+    const wt = makeWorktree({ id: 'repo1::/a', repoId: 'repo1', path: '/a' })
+    store.setState({
+      worktreesByRepo: { repo1: [wt] },
+      lastVisitedAtByWorktreeId: { 'repo1::/a': 100, 'ssh-repo::/b': 200 }
+    } as Partial<AppState>)
+    store.getState().pruneLastVisitedTimestamps()
+    expect(store.getState().lastVisitedAtByWorktreeId).toEqual({
+      'repo1::/a': 100,
+      'ssh-repo::/b': 200
+    })
+  })
 })
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index 037f801cd98..1e8dc80920b 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -162,7 +162,14 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     set({ hasHydratedWorktreePurge: true })
   },
 
-  createWorktree: async (repoId, name, baseBranch, setupDecision = 'inherit', sparseCheckout) => {
+  createWorktree: async (
+    repoId,
+    name,
+    baseBranch,
+    setupDecision = 'inherit',
+    sparseCheckout,
+    telemetrySource
+  ) => {
     const retryableConflictPatterns = [
       /already exists locally/i,
       /already exists on a remote/i,
@@ -180,7 +187,8 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             name: candidateName,
             baseBranch,
             setupDecision,
-            sparseCheckout
+            sparseCheckout,
+            ...(telemetrySource ? { telemetrySource } : {})
           })
           // Why: a file watcher (worktrees.onChanged) can fire between the
           // backend creating the worktree and this callback running, causing
@@ -584,16 +592,36 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
 
   pruneLastVisitedTimestamps: () => {
     set((s) => {
-      const validIds = new Set<string>()
-      for (const list of Object.values(s.worktreesByRepo)) {
+      // Why: scope pruning per-repo. SSH-backed repos cannot enumerate
+      // worktrees until their connection is established, so at hydration
+      // time worktreesByRepo[sshRepoId] is empty/undefined. If we pruned
+      // globally based on the union of all repos' worktrees, we would wipe
+      // every persisted focus-recency entry for SSH worktrees — precisely
+      // the set this feature exists to preserve. Instead, only drop entries
+      // whose repo has a populated worktree list: a missing repoId means
+      // "not yet hydrated" (defer), a repoId with an empty list after a
+      // successful listing means the worktree really is gone (drop).
+      // The ssh:state-changed 'connected' handler re-fetches worktrees and
+      // a follow-up prune runs from the same site if needed.
+      const validIdsByRepo = new Map<string, Set<string>>()
+      for (const [repoId, list] of Object.entries(s.worktreesByRepo)) {
+        const ids = new Set<string>()
         for (const w of list) {
-          validIds.add(w.id)
+          ids.add(w.id)
         }
+        validIdsByRepo.set(repoId, ids)
       }
       let changed = false
       const next: Record<string, number> = {}
       for (const [id, ts] of Object.entries(s.lastVisitedAtByWorktreeId)) {
-        if (validIds.has(id)) {
+        const repoId = getRepoIdFromWorktreeId(id)
+        const repoIds = validIdsByRepo.get(repoId)
+        if (!repoIds) {
+          // Repo not yet hydrated (e.g. SSH not connected). Keep the entry.
+          next[id] = ts
+          continue
+        }
+        if (repoIds.has(id)) {
           next[id] = ts
         } else {
           changed = true
diff --git a/src/shared/agent-kind.test.ts b/src/shared/agent-kind.test.ts
new file mode 100644
index 00000000000..98c56da9c1d
--- /dev/null
+++ b/src/shared/agent-kind.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+
+import { tuiAgentToAgentKind } from './agent-kind'
+import { AGENT_KIND_VALUES, agentKindSchema } from './telemetry-events'
+import { TUI_AGENT_CONFIG } from './tui-agent-config'
+import type { TuiAgent } from './types'
+
+describe('tuiAgentToAgentKind', () => {
+  it('maps every shipped TuiAgent to a concrete telemetry kind', () => {
+    const agents = Object.keys(TUI_AGENT_CONFIG) as TuiAgent[]
+
+    for (const agent of agents) {
+      const kind = tuiAgentToAgentKind(agent)
+
+      expect(kind).not.toBe('other')
+      expect(agentKindSchema.safeParse(kind).success).toBe(true)
+    }
+  })
+
+  it('keeps concrete telemetry kinds in exact sync with shipped TuiAgents', () => {
+    const agents = Object.keys(TUI_AGENT_CONFIG) as TuiAgent[]
+    const mappedKinds = agents.map((agent) => tuiAgentToAgentKind(agent)).sort()
+    const concreteSchemaKinds = AGENT_KIND_VALUES.filter((kind) => kind !== 'other').sort()
+
+    expect(mappedKinds).toEqual(concreteSchemaKinds)
+  })
+
+  it('uses the product id for Claude and the TuiAgent id for Pi', () => {
+    expect(tuiAgentToAgentKind('claude')).toBe('claude-code')
+    expect(tuiAgentToAgentKind('pi')).toBe('pi')
+  })
+})
diff --git a/src/shared/agent-kind.ts b/src/shared/agent-kind.ts
new file mode 100644
index 00000000000..efd1da48318
--- /dev/null
+++ b/src/shared/agent-kind.ts
@@ -0,0 +1,49 @@
+// Mapping from the renderer's `TuiAgent` union (every agent Orca knows how
+// to launch) to the closed `agentKindSchema` enum on telemetry events. Every
+// shipped agent maps to a concrete telemetry value so dashboards can
+// distinguish launch interest instead of collapsing the long tail to `other`.
+//
+// Lives in `src/shared/` (not the renderer) because main-side telemetry
+// emission (`agent_started` from the `pty:spawn` IPC handler) needs the
+// same mapping. Centralizing here means a new TuiAgent member is one edit,
+// not a sweep across renderer + main.
+
+import type { AgentKind } from './telemetry-events'
+import type { TuiAgent } from './types'
+
+type ConcreteAgentKind = Exclude<AgentKind, 'other'>
+
+const TUI_AGENT_KIND_BY_AGENT = {
+  claude: 'claude-code',
+  codex: 'codex',
+  autohand: 'autohand',
+  opencode: 'opencode',
+  pi: 'pi',
+  gemini: 'gemini',
+  aider: 'aider',
+  goose: 'goose',
+  amp: 'amp',
+  kilo: 'kilo',
+  kiro: 'kiro',
+  crush: 'crush',
+  aug: 'aug',
+  cline: 'cline',
+  codebuff: 'codebuff',
+  continue: 'continue',
+  cursor: 'cursor',
+  droid: 'droid',
+  kimi: 'kimi',
+  'mistral-vibe': 'mistral-vibe',
+  'qwen-code': 'qwen-code',
+  rovo: 'rovo',
+  hermes: 'hermes',
+  copilot: 'copilot'
+} satisfies Record<TuiAgent, ConcreteAgentKind>
+
+// Why: `satisfies Record<TuiAgent, …>` makes the lookup exhaustive at compile
+// time, but stale persisted settings or unsafe IPC casts can carry a string
+// outside the union at runtime — fall back to `'other'` so the event still
+// emits instead of failing validation and dropping silently.
+export function tuiAgentToAgentKind(agent: TuiAgent): AgentKind {
+  return TUI_AGENT_KIND_BY_AGENT[agent] ?? 'other'
+}
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 81b2b4d473f..0f9a3e96326 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -11,6 +11,7 @@ import type {
 import { DEFAULT_TERMINAL_FONT_WEIGHT } from './terminal-fonts'
 
 export const SCHEMA_VERSION = 1
+export const DEFAULT_APP_FONT_FAMILY = 'Geist'
 
 export const ORCA_BROWSER_PARTITION = 'persist:orca-browser'
 // Why: blank browser tabs must start from an inert guest URL that does not
@@ -81,8 +82,7 @@ export const DEFAULT_STATUS_BAR_ITEMS: StatusBarItem[] = [
   'gemini',
   'opencode-go',
   'ssh',
-  'sessions',
-  'memory'
+  'resource-usage'
 ]
 
 /** Synthetic worktree id used by the memory collector to bucket PTYs that
@@ -106,7 +106,8 @@ export function getDefaultNotificationSettings(): NotificationSettings {
     enabled: true,
     agentTaskComplete: true,
     terminalBell: false,
-    suppressWhenFocused: true
+    suppressWhenFocused: true,
+    customSoundPath: null
   }
 }
 
@@ -119,6 +120,7 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     branchPrefixCustom: '',
     enableGitHubAttribution: false,
     theme: 'system',
+    appFontFamily: DEFAULT_APP_FONT_FAMILY,
     editorAutoSave: false,
     editorAutoSaveDelayMs: DEFAULT_EDITOR_AUTO_SAVE_DELAY_MS,
     editorMinimapEnabled: false,
@@ -202,7 +204,18 @@ export function getDefaultSettings(homedir: string): GlobalSettings {
     experimentalMobile: false,
     // Why: off by default — opt-in cosmetic joke feature. Leaving the default
     // false keeps the overlay unmounted for users who never enable it.
-    experimentalSidekick: false
+    experimentalSidekick: false,
+    experimentalWorktreeSymlinks: false,
+    // 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
+    // `{ ...defaults, ...parsed }` merge in persistence.ts.
+    githubProjects: {
+      pinned: [],
+      recent: [],
+      lastViewByProject: {},
+      activeProject: null
+    }
   }
 }
 
diff --git a/src/shared/github-auth-types.ts b/src/shared/github-auth-types.ts
new file mode 100644
index 00000000000..9c39879db60
--- /dev/null
+++ b/src/shared/github-auth-types.ts
@@ -0,0 +1,39 @@
+/**
+ * Shared types for `gh auth status` diagnostics surfaced to the renderer.
+ */
+
+export type GhAuthAccount = {
+  host: string
+  user: string
+  /** True when this is the account gh would use for the next call. */
+  active: boolean
+  /**
+   * If gh reports the credential came from an environment variable, the
+   * variable's name. Null when the credential came from the keyring/file
+   * config. Env-token accounts can't be refreshed by `gh auth refresh`.
+   */
+  envToken: 'GITHUB_TOKEN' | 'GH_TOKEN' | null
+  source: 'env' | 'keyring'
+  scopes: string[]
+}
+
+export type GhAuthDiagnostic = {
+  /** False when gh CLI is not installed / not on PATH. */
+  ghAvailable: boolean
+  activeAccount: GhAuthAccount | null
+  accounts: GhAuthAccount[]
+  /**
+   * Whether the Electron main process itself sees GITHUB_TOKEN/GH_TOKEN in
+   * its environment. Distinct from `activeAccount.envToken` because gh may
+   * report an env source even when the variable was set in a parent shell
+   * that didn't propagate to Electron, and vice versa.
+   */
+  envTokenInProcess: 'GITHUB_TOKEN' | 'GH_TOKEN' | null
+  missingScopes: string[]
+  requiredScopes: string[]
+  /**
+   * True when there's a non-env keyring account on the same/another host
+   * that the user could fall back to by unsetting the env var.
+   */
+  hasKeyringFallback: boolean
+}
diff --git a/src/shared/github-project-types.ts b/src/shared/github-project-types.ts
new file mode 100644
index 00000000000..90ea46f9e37
--- /dev/null
+++ b/src/shared/github-project-types.ts
@@ -0,0 +1,431 @@
+/* eslint-disable max-lines -- Why: this module is the single source of truth for ProjectV2 shapes (settings, IPC payloads, view/field/value types) shared across main, preload, and renderer; splitting risks circular type imports. */
+// Why: ProjectV2 shapes are distinct enough from the issue/PR work-item types
+// that we keep them in a dedicated module. Preload and main-process callers
+// import from here directly — do not re-export through `./types.ts` just to
+// match the existing import block; routing through the issue types module
+// would obscure ownership of the Project surface.
+import type {
+  GitHubAssignableUser,
+  GitHubIssueUpdate,
+  GitHubWorkItemDetails,
+  PRComment
+} from './types'
+
+export type GitHubProjectViewLayout = 'TABLE_LAYOUT' | 'BOARD_LAYOUT' | 'ROADMAP_LAYOUT'
+export type GitHubProjectOwnerType = 'organization' | 'user'
+
+// Why: anything outside this union must render as an empty cell — the
+// normalizer must never throw on an unknown dataType. The `(string & {})`
+// branch preserves unknown values verbatim for debuggability while still
+// satisfying the distinct field-kind discriminants below.
+export type GitHubProjectFieldDataType =
+  | 'TITLE'
+  | 'ASSIGNEES'
+  | 'LABELS'
+  | 'LINKED_PULL_REQUESTS'
+  | 'REVIEWERS'
+  | 'REPOSITORY'
+  | 'MILESTONE'
+  | 'PARENT_ISSUE'
+  | 'SUB_ISSUES_PROGRESS'
+  | 'TRACKS'
+  | 'TRACKED_BY'
+  | 'ISSUE_TYPE'
+  | 'TEXT'
+  | 'NUMBER'
+  | 'DATE'
+  | 'SINGLE_SELECT'
+  | 'ITERATION'
+
+export type GitHubProjectSingleSelectOption = {
+  id: string
+  name: string
+  color: string
+}
+
+export type GitHubProjectIteration = {
+  id: string
+  title: string
+  /** YYYY-MM-DD — GitHub returns a calendar date, not an ISO timestamp. */
+  startDate: string
+  /** Length in days. */
+  duration: number
+  /** True when GitHub returned this iteration under `completedIterations`. */
+  completed: boolean
+}
+
+export type GitHubProjectField =
+  | {
+      kind: 'field'
+      id: string
+      name: string
+      dataType: Exclude<GitHubProjectFieldDataType, 'SINGLE_SELECT' | 'ITERATION'> | (string & {})
+    }
+  | {
+      kind: 'single-select'
+      id: string
+      name: string
+      dataType: 'SINGLE_SELECT'
+      options: GitHubProjectSingleSelectOption[]
+    }
+  | {
+      kind: 'iteration'
+      id: string
+      name: string
+      dataType: 'ITERATION'
+      iterations: GitHubProjectIteration[]
+    }
+
+export type GitHubProjectSortDirection = 'ASC' | 'DESC'
+
+export type GitHubProjectSort = {
+  direction: GitHubProjectSortDirection
+  field: GitHubProjectField
+}
+
+export type GitHubProjectView = {
+  id: string
+  number: number
+  name: string
+  layout: GitHubProjectViewLayout
+  /** Normalized to '' when GitHub returns null. Why: passing null through as
+   *  `$q` in the items query would change the query shape between filtered
+   *  and unfiltered views; the empty string keeps the GraphQL shape stable. */
+  filter: string
+  fields: GitHubProjectField[]
+  groupByFields: GitHubProjectField[]
+  sortByFields: GitHubProjectSort[]
+}
+
+export type GitHubProjectUser = {
+  login: string
+  name: string | null
+  avatarUrl: string | null
+}
+
+export type GitHubProjectLabel = {
+  name: string
+  color: string
+}
+
+export type GitHubProjectParentIssue = {
+  number: number
+  title: string
+  url: string
+}
+
+// Why: GitHub Issue Types are a repo-level taxonomy (Bug/Feature/Task/etc).
+// Only repos opted into typed-issues expose a non-empty list. We carry both
+// id and human-readable name so the picker can reflect updates without a
+// re-fetch and the cell can render the chosen name with its color.
+export type GitHubIssueType = {
+  id: string
+  name: string
+  color: string | null
+  description: string | null
+}
+
+export type GitHubProjectFieldValue =
+  | {
+      kind: 'single-select'
+      fieldId: string
+      optionId: string
+      name: string
+      color: string
+    }
+  | {
+      kind: 'iteration'
+      fieldId: string
+      iterationId: string
+      title: string
+      startDate: string
+      duration: number
+    }
+  | { kind: 'text'; fieldId: string; text: string }
+  | { kind: 'number'; fieldId: string; number: number }
+  | { kind: 'date'; fieldId: string; date: string }
+  | { kind: 'labels'; fieldId: string; labels: GitHubProjectLabel[] }
+  | { kind: 'users'; fieldId: string; users: GitHubProjectUser[] }
+
+export type GitHubProjectRowItemType = 'ISSUE' | 'PULL_REQUEST' | 'DRAFT_ISSUE' | 'REDACTED'
+
+export type GitHubProjectRow = {
+  id: string
+  itemType: GitHubProjectRowItemType
+  content: {
+    number: number | null
+    title: string
+    /** DraftIssue body and optional detail-cache patch target; list rows do
+     *  not render issue/PR body. */
+    body: string | null
+    url: string | null
+    state: string | null
+    /** Issue stateReason; null for PR/draft. Why: closed-as-not-planned needs
+     *  a different glyph than a regular closed issue. */
+    stateReason: string | null
+    /** PullRequest.isDraft; null otherwise. */
+    isDraft: boolean | null
+    /** nameWithOwner, e.g. 'stablyai/orca'. */
+    repository: string | null
+    assignees: GitHubProjectUser[]
+    labels: GitHubProjectLabel[]
+    parentIssue: GitHubProjectParentIssue | null
+    /** Issue.issueType when set; null on PRs/drafts/redacted or when unset. */
+    issueType: GitHubIssueType | null
+  }
+  fieldValuesByFieldId: Record<string, GitHubProjectFieldValue>
+  updatedAt: string
+  /** Original fetched order (zero-based index in the fully paginated
+   *  POSITION ASC stream). Used as the final tie-break so equal sort values
+   *  keep GitHub rank order. */
+  position: number
+}
+
+export type GitHubProjectTable = {
+  project: {
+    id: string
+    owner: string
+    ownerType: GitHubProjectOwnerType
+    number: number
+    title: string
+    url: string
+  }
+  selectedView: GitHubProjectView
+  rows: GitHubProjectRow[]
+  /** Echoes ProjectV2.items.totalCount for the view filter. */
+  totalCount: number
+  /** True when the `parent` retry fallback fired. The UI can hint
+   *  "sub-issues unavailable" without claiming a hard error. */
+  parentFieldDropped: boolean
+}
+
+export type GitHubProjectSummary = {
+  id: string
+  owner: string
+  ownerType: GitHubProjectOwnerType
+  number: number
+  title: string
+  url: string
+  source: 'viewer' | `org:${string}`
+}
+
+export type GitHubProjectViewSummary = {
+  id: string
+  number: number
+  name: string
+  layout: GitHubProjectViewLayout
+}
+
+export type GitHubProjectSettings = {
+  pinned: { owner: string; ownerType: GitHubProjectOwnerType; number: number }[]
+  recent: {
+    owner: string
+    ownerType: GitHubProjectOwnerType
+    number: number
+    lastOpenedAt: string
+  }[]
+  lastViewByProject: Record<string, { viewId: string }>
+  activeProject: { owner: string; ownerType: GitHubProjectOwnerType; number: number } | null
+}
+
+// ─── Classified errors ─────────────────────────────────────────────────
+
+export type GitHubProjectViewErrorType =
+  | 'auth_required'
+  | 'scope_missing'
+  | 'not_found'
+  | 'unsupported_layout'
+  | 'too_large'
+  | 'schema_drift'
+  | 'validation_error'
+  | 'network_error'
+  | 'rate_limited'
+  | 'unknown'
+
+export type GitHubProjectViewError = {
+  type: GitHubProjectViewErrorType
+  message: string
+  /** Populated when the error is classifiable from a GraphQL response. Never
+   *  includes tokens or full command stdout. */
+  details?: { path?: (string | number)[]; code?: string }
+}
+
+export type GetProjectViewTableResult =
+  | { ok: true; data: GitHubProjectTable }
+  | {
+      ok: false
+      error: GitHubProjectViewError
+      /** Populated for the `too_large` case and best-effort for
+       *  `unsupported_layout` when a cheap count-only query succeeds. */
+      totalCount?: number
+    }
+
+export type ListAccessibleProjectsResult =
+  | {
+      ok: true
+      projects: GitHubProjectSummary[]
+      /** Why: per-org discovery can partially fail (a single org 504s while
+       *  the rest succeed). The picker renders a banner listing the affected
+       *  org logins so the user knows their list is incomplete and can paste
+       *  a URL to reach missing projects. Empty when discovery was clean. */
+      partialFailures?: { owner: string; message: string }[]
+    }
+  | { ok: false; error: GitHubProjectViewError }
+
+export type ResolveProjectRefResult =
+  | {
+      ok: true
+      owner: string
+      ownerType: GitHubProjectOwnerType
+      number: number
+      title: string
+      // Why: when the input is a /views/{n} URL, surface the parsed view
+      // number so the picker can skip the view-pick step and commit the
+      // selection directly. Absent for owner/number shorthand and project
+      // URLs without a /views/ segment.
+      viewNumber?: number
+    }
+  | { ok: false; error: GitHubProjectViewError }
+
+export type ListProjectViewsResult =
+  | { ok: true; views: GitHubProjectViewSummary[] }
+  | { ok: false; error: GitHubProjectViewError }
+
+export type ProjectWorkItemDetailsBySlugResult =
+  | { ok: true; details: GitHubWorkItemDetails }
+  | { ok: false; error: GitHubProjectViewError }
+
+// ─── Mutations ─────────────────────────────────────────────────────────
+
+export type GitHubProjectMutationResult =
+  | { ok: true }
+  | { ok: false; error: GitHubProjectViewError }
+
+export type GitHubProjectCommentMutationResult =
+  | { ok: true; comment: PRComment }
+  | { ok: false; error: GitHubProjectViewError }
+
+export type GitHubProjectFieldMutationValue =
+  | { kind: 'single-select'; optionId: string }
+  | { kind: 'iteration'; iterationId: string }
+  | { kind: 'text'; text: string }
+  | { kind: 'number'; number: number }
+  /** YYYY-MM-DD. */
+  | { kind: 'date'; date: string }
+
+export type ListLabelsBySlugResult =
+  | { ok: true; labels: string[] }
+  | { ok: false; error: GitHubProjectViewError }
+
+export type ListAssignableUsersBySlugResult =
+  | { ok: true; users: GitHubAssignableUser[] }
+  | { ok: false; error: GitHubProjectViewError }
+
+export type ListIssueTypesBySlugResult =
+  | { ok: true; types: GitHubIssueType[] }
+  | { ok: false; error: GitHubProjectViewError }
+
+// ─── IPC arg shapes (shared between main, preload, renderer) ──────────
+
+export type GetProjectViewTableArgs = {
+  owner: string
+  ownerType: GitHubProjectOwnerType
+  projectNumber: number
+  /** View selection precedence: viewId > viewNumber > viewName > first
+   *  TABLE_LAYOUT view. */
+  viewId?: string
+  viewNumber?: number
+  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". */
+  queryOverride?: string
+}
+
+export type ProjectWorkItemDetailsBySlugArgs = {
+  owner: string
+  repo: string
+  number: number
+  type: 'issue' | 'pr'
+}
+
+export type UpdateProjectItemFieldArgs = {
+  projectId: string
+  itemId: string
+  fieldId: string
+  value: GitHubProjectFieldMutationValue
+}
+
+export type ClearProjectItemFieldArgs = {
+  projectId: string
+  itemId: string
+  fieldId: string
+}
+
+export type UpdateIssueBySlugArgs = {
+  owner: string
+  repo: string
+  number: number
+  updates: GitHubIssueUpdate & { body?: string }
+}
+
+export type UpdatePullRequestBySlugArgs = {
+  owner: string
+  repo: string
+  number: number
+  updates: { title?: string; body?: string }
+}
+
+export type AddIssueCommentBySlugArgs = {
+  owner: string
+  repo: string
+  number: number
+  body: string
+}
+
+export type UpdateIssueCommentBySlugArgs = {
+  owner: string
+  repo: string
+  commentId: number
+  body: string
+}
+
+export type DeleteIssueCommentBySlugArgs = {
+  owner: string
+  repo: string
+  commentId: number
+}
+
+export type ListLabelsBySlugArgs = {
+  owner: string
+  repo: string
+}
+
+export type ListAssignableUsersBySlugArgs = {
+  owner: string
+  repo: string
+  seedLogins?: string[]
+}
+
+export type ListIssueTypesBySlugArgs = {
+  owner: string
+  repo: string
+}
+
+export type UpdateIssueTypeBySlugArgs = {
+  owner: string
+  repo: string
+  number: number
+  /** null clears the issue type. */
+  issueTypeId: string | null
+}
+
+export type ResolveProjectRefArgs = {
+  input: string
+}
+
+export type ListProjectViewsArgs = {
+  owner: string
+  ownerType: GitHubProjectOwnerType
+  projectNumber: number
+}
diff --git a/src/shared/pairing.test.ts b/src/shared/pairing.test.ts
index de0738b5907..cf469f6ed4b 100644
--- a/src/shared/pairing.test.ts
+++ b/src/shared/pairing.test.ts
@@ -1,5 +1,10 @@
 import { describe, expect, it } from 'vitest'
-import { encodePairingOffer, decodePairingOffer, type PairingOffer } from './pairing'
+import {
+  encodePairingOffer,
+  decodePairingOffer,
+  parsePairingCode,
+  type PairingOffer
+} from './pairing'
 
 describe('pairing offer', () => {
   const offer: PairingOffer = {
@@ -49,3 +54,43 @@ describe('pairing offer', () => {
     expect(() => decodePairingOffer(`orca://pair#${base64}`)).toThrow()
   })
 })
+
+describe('parsePairingCode', () => {
+  const offer: PairingOffer = {
+    v: 2,
+    endpoint: 'ws://192.168.1.10:6768',
+    deviceToken: 'token-abc',
+    publicKeyB64: 'pubkey-xyz'
+  }
+
+  it('parses a full orca://pair# URL', () => {
+    const url = encodePairingOffer(offer)
+    expect(parsePairingCode(url)).toEqual(offer)
+  })
+
+  it('parses a bare base64url payload (without scheme prefix)', () => {
+    const url = encodePairingOffer(offer)
+    const base64url = url.split('#')[1]!
+    expect(parsePairingCode(base64url)).toEqual(offer)
+  })
+
+  it('tolerates surrounding whitespace from clipboard', () => {
+    const url = encodePairingOffer(offer)
+    expect(parsePairingCode(`  ${url}\n`)).toEqual(offer)
+  })
+
+  it('returns null for empty input', () => {
+    expect(parsePairingCode('')).toBeNull()
+    expect(parsePairingCode('   ')).toBeNull()
+  })
+
+  it('returns null for garbage input', () => {
+    expect(parsePairingCode('not a pairing code')).toBeNull()
+    expect(parsePairingCode('https://example.com')).toBeNull()
+  })
+
+  it('returns null for valid base64 of unrelated JSON', () => {
+    const bogus = Buffer.from(JSON.stringify({ hello: 'world' })).toString('base64')
+    expect(parsePairingCode(bogus)).toBeNull()
+  })
+})
diff --git a/src/shared/pairing.ts b/src/shared/pairing.ts
index 5f8d4afc3b4..4e9b5beba80 100644
--- a/src/shared/pairing.ts
+++ b/src/shared/pairing.ts
@@ -28,7 +28,28 @@ export function decodePairingOffer(url: string): PairingOffer {
   if (!url.startsWith('orca://pair') || hashIndex === -1) {
     throw new Error('Invalid pairing URL: must start with orca://pair#')
   }
-  const base64url = url.slice(hashIndex + 1)
+  return decodePairingBase64(url.slice(hashIndex + 1))
+}
+
+// Why: accept either an `orca://pair#<base64>` URL or the bare base64
+// string so the mobile paste-pair flow can take whichever the user
+// actually copied from desktop.
+export function parsePairingCode(input: string): PairingOffer | null {
+  const trimmed = input.trim()
+  if (!trimmed) {
+    return null
+  }
+  try {
+    if (trimmed.startsWith('orca://pair')) {
+      return decodePairingOffer(trimmed)
+    }
+    return decodePairingBase64(trimmed)
+  } catch {
+    return null
+  }
+}
+
+function decodePairingBase64(base64url: string): PairingOffer {
   const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/')
   const json = Buffer.from(base64, 'base64').toString('utf-8')
   return PairingOfferSchema.parse(JSON.parse(json))
diff --git a/src/shared/protocol-compat.test.ts b/src/shared/protocol-compat.test.ts
new file mode 100644
index 00000000000..1798e97fc87
--- /dev/null
+++ b/src/shared/protocol-compat.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import { evaluateCompat } from './protocol-compat'
+
+const MOBILE_V = 1
+
+describe('evaluateCompat', () => {
+  it('returns ok when both desktop fields are undefined and constants are wide-open', () => {
+    const verdict = evaluateCompat({
+      mobileProtocolVersion: MOBILE_V,
+      minCompatibleDesktopVersion: 0,
+      desktopProtocolVersion: undefined,
+      desktopMinCompatibleMobileVersion: undefined
+    })
+    expect(verdict).toEqual({ kind: 'ok' })
+  })
+
+  it('returns ok when desktop reports version equal to mobile', () => {
+    const verdict = evaluateCompat({
+      mobileProtocolVersion: MOBILE_V,
+      minCompatibleDesktopVersion: 0,
+      desktopProtocolVersion: MOBILE_V,
+      desktopMinCompatibleMobileVersion: 0
+    })
+    expect(verdict).toEqual({ kind: 'ok' })
+  })
+
+  it('returns ok when desktop reports a newer version (additive changes assumed safe)', () => {
+    const verdict = evaluateCompat({
+      mobileProtocolVersion: MOBILE_V,
+      minCompatibleDesktopVersion: 0,
+      desktopProtocolVersion: MOBILE_V + 5,
+      desktopMinCompatibleMobileVersion: 0
+    })
+    expect(verdict).toEqual({ kind: 'ok' })
+  })
+
+  it('blocks with mobile-too-old when desktop requires a newer mobile', () => {
+    const verdict = evaluateCompat({
+      mobileProtocolVersion: MOBILE_V,
+      minCompatibleDesktopVersion: 0,
+      desktopProtocolVersion: 5,
+      desktopMinCompatibleMobileVersion: MOBILE_V + 1
+    })
+    expect(verdict).toEqual({
+      kind: 'blocked',
+      reason: 'mobile-too-old',
+      desktopVersion: 5,
+      requiredMobileVersion: MOBILE_V + 1
+    })
+  })
+
+  it('coerces undefined desktopVersion to 0 in the verdict payload', () => {
+    const verdict = evaluateCompat({
+      mobileProtocolVersion: MOBILE_V,
+      minCompatibleDesktopVersion: 0,
+      desktopProtocolVersion: undefined,
+      desktopMinCompatibleMobileVersion: MOBILE_V + 1
+    })
+    expect(verdict).toMatchObject({
+      kind: 'blocked',
+      reason: 'mobile-too-old',
+      desktopVersion: 0
+    })
+  })
+
+  it('blocks with desktop-too-old when desktop reports below the local minimum', () => {
+    const verdict = evaluateCompat({
+      mobileProtocolVersion: MOBILE_V,
+      minCompatibleDesktopVersion: 5,
+      desktopProtocolVersion: 3,
+      desktopMinCompatibleMobileVersion: 0
+    })
+    expect(verdict).toEqual({
+      kind: 'blocked',
+      reason: 'desktop-too-old',
+      desktopVersion: 3,
+      requiredDesktopVersion: 5
+    })
+  })
+
+  it('mobile-too-old wins precedence when both constraints would fire', () => {
+    // Why: documents the intended kill-switch precedence — desktop's
+    // refusal of a too-old mobile takes priority over mobile's local
+    // refusal of a too-old desktop.
+    const verdict = evaluateCompat({
+      mobileProtocolVersion: MOBILE_V,
+      minCompatibleDesktopVersion: 99,
+      desktopProtocolVersion: -1,
+      desktopMinCompatibleMobileVersion: MOBILE_V + 1
+    })
+    expect(verdict.kind).toBe('blocked')
+    expect((verdict as { reason: string }).reason).toBe('mobile-too-old')
+  })
+
+  it('with minCompatibleDesktopVersion = 0 every reported desktop passes', () => {
+    for (const v of [0, 1, 2, 99]) {
+      expect(
+        evaluateCompat({
+          mobileProtocolVersion: MOBILE_V,
+          minCompatibleDesktopVersion: 0,
+          desktopProtocolVersion: v,
+          desktopMinCompatibleMobileVersion: 0
+        })
+      ).toEqual({ kind: 'ok' })
+    }
+  })
+})
diff --git a/src/shared/protocol-compat.ts b/src/shared/protocol-compat.ts
new file mode 100644
index 00000000000..72477cfb482
--- /dev/null
+++ b/src/shared/protocol-compat.ts
@@ -0,0 +1,50 @@
+// 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.
+
+export type CompatVerdict =
+  | { kind: 'ok' }
+  | {
+      kind: 'blocked'
+      reason: 'mobile-too-old' | 'desktop-too-old'
+      desktopVersion: number
+      requiredMobileVersion?: number
+      requiredDesktopVersion?: number
+    }
+
+export function evaluateCompat(input: {
+  mobileProtocolVersion: number
+  minCompatibleDesktopVersion: number
+  desktopProtocolVersion: number | undefined
+  desktopMinCompatibleMobileVersion: number | undefined
+}): CompatVerdict {
+  // Why: absent fields → 0 lets mobile keep talking to pre-PR desktops.
+  // Bumping minCompatibleDesktopVersion above 0 will fence those older
+  // desktops alongside any explicitly-version-0 desktop, which is the
+  // intended kill-switch behavior.
+  const desktopVersion = input.desktopProtocolVersion ?? 0
+  const requiredMobile = input.desktopMinCompatibleMobileVersion ?? 0
+
+  // Why: mobile-too-old precedence — if desktop says "I refuse this
+  // mobile build" (kill switch), that wins over any local mobile
+  // judgment about desktop's age.
+  if (input.mobileProtocolVersion < requiredMobile) {
+    return {
+      kind: 'blocked',
+      reason: 'mobile-too-old',
+      desktopVersion,
+      requiredMobileVersion: requiredMobile
+    }
+  }
+  if (desktopVersion < input.minCompatibleDesktopVersion) {
+    return {
+      kind: 'blocked',
+      reason: 'desktop-too-old',
+      desktopVersion,
+      requiredDesktopVersion: input.minCompatibleDesktopVersion
+    }
+  }
+  return { kind: 'ok' }
+}
diff --git a/src/shared/protocol-version.ts b/src/shared/protocol-version.ts
new file mode 100644
index 00000000000..e8232991356
--- /dev/null
+++ b/src/shared/protocol-version.ts
@@ -0,0 +1,23 @@
+// 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.
+//
+// Bump DESKTOP_PROTOCOL_VERSION when:
+//   - You remove an RPC method or required parameter that mobile uses.
+//   - You change the meaning (units, nullability) of an existing field
+//     mobile reads.
+//   - You change encryption, framing, or the auth handshake.
+// Do NOT bump for:
+//   - Adding new RPC methods.
+//   - Adding new optional fields on existing methods.
+//   - Adding new event types in `terminal.subscribe`.
+//
+// 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.
+
+export const DESKTOP_PROTOCOL_VERSION = 1
+export const MIN_COMPATIBLE_MOBILE_VERSION = 0
diff --git a/src/shared/runtime-types.ts b/src/shared/runtime-types.ts
index 95c6cf54f03..5b3a6fed205 100644
--- a/src/shared/runtime-types.ts
+++ b/src/shared/runtime-types.ts
@@ -1,6 +1,6 @@
 /* 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 { GitWorktreeInfo, Repo } from './types'
+import type { BrowserSessionProfile, GitWorktreeInfo, Repo } from './types'
 
 export type RuntimeGraphStatus = 'ready' | 'reloading' | 'unavailable'
 
@@ -11,6 +11,11 @@ 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.
+  protocolVersion?: number
+  minCompatibleMobileVersion?: number
 }
 
 export type CliRuntimeState =
@@ -259,6 +264,9 @@ export type BrowserTabInfo = {
   url: string
   title: string
   active: boolean
+  worktreeId?: string | null
+  profileId?: string | null
+  profileLabel?: string | null
 }
 
 export type BrowserTabListResult = {
@@ -270,6 +278,47 @@ export type BrowserTabSwitchResult = {
   browserPageId: string
 }
 
+export type BrowserTabSetProfileResult = {
+  browserPageId: string
+  profileId: string | null
+  profileLabel: string | null
+}
+
+export type BrowserTabShowResult = {
+  tab: BrowserTabInfo
+}
+
+export type BrowserTabCurrentResult = {
+  tab: BrowserTabInfo
+}
+
+export type BrowserTabProfileShowResult = {
+  browserPageId: string
+  worktreeId: string | null
+  profileId: string | null
+  profileLabel: string | null
+}
+
+export type BrowserTabProfileCloneResult = {
+  browserPageId: string
+  sourceBrowserPageId: string
+  profileId: string | null
+  profileLabel: string | null
+}
+
+export type BrowserProfileListResult = {
+  profiles: BrowserSessionProfile[]
+}
+
+export type BrowserProfileCreateResult = {
+  profile: BrowserSessionProfile | null
+}
+
+export type BrowserProfileDeleteResult = {
+  deleted: boolean
+  profileId: string
+}
+
 export type BrowserHoverResult = {
   hovered: string
 }
diff --git a/src/shared/telemetry-consent-types.ts b/src/shared/telemetry-consent-types.ts
new file mode 100644
index 00000000000..0cc5c7f2e62
--- /dev/null
+++ b/src/shared/telemetry-consent-types.ts
@@ -0,0 +1,17 @@
+// Shared consent-state shape, serializable across the main/renderer IPC
+// boundary. Lives in `shared/` rather than main so the Privacy pane
+// (renderer-side) can import the type without pulling in main-only code.
+//
+// The same discriminated union is what `src/main/telemetry/consent.ts`
+// produces from `resolveConsent(settings)`. Keeping it here as the source
+// of truth means the IPC getter in `src/main/ipc/telemetry.ts` returns
+// this exact shape and the Privacy pane renders helper text by pattern-
+// matching the `reason` without re-deriving the rules.
+
+export type TelemetryConsentState =
+  | { effective: 'enabled' }
+  | {
+      effective: 'disabled'
+      reason: 'do_not_track' | 'orca_disabled' | 'ci' | 'user_opt_out'
+    }
+  | { effective: 'pending_banner' }
diff --git a/src/shared/telemetry-events.test.ts b/src/shared/telemetry-events.test.ts
index ff684957832..1a6f76a864a 100644
--- a/src/shared/telemetry-events.test.ts
+++ b/src/shared/telemetry-events.test.ts
@@ -1,12 +1,11 @@
 // Schema round-trip coverage for the event map. Fail-closed invariants that
 // must hold: agent_error is enum-only (error_message / error_stack rejected
-// by `.strict()`), error_name is whitelisted, unknown enum values fail, and
-// any well-formed payload round-trips without coercion.
+// by `.strict()`), unknown enum values fail, and any well-formed payload
+// round-trips without coercion.
 
 import { describe, expect, it } from 'vitest'
 import {
-  AGENT_ERROR_NAME_WHITELIST,
-  agentErrorNameSchema,
+  AGENT_KIND_VALUES,
   agentKindSchema,
   commonPropsSchema,
   errorClassSchema,
@@ -18,38 +17,18 @@ import {
 describe('agent_error schema', () => {
   it('round-trips a minimal {error_class, agent_kind} payload', () => {
     const parsed = eventSchemas.agent_error.safeParse({
-      error_class: 'auth_expired',
+      error_class: 'unknown',
       agent_kind: 'claude-code'
     })
     expect(parsed.success).toBe(true)
   })
 
-  it('round-trips every whitelisted error_name value', () => {
-    for (const name of AGENT_ERROR_NAME_WHITELIST) {
-      const parsed = eventSchemas.agent_error.safeParse({
-        error_class: 'auth_expired',
-        agent_kind: 'claude-code',
-        error_name: name
-      })
-      expect(parsed.success).toBe(true)
-    }
-  })
-
-  it('rejects error_name values outside the whitelist', () => {
-    const parsed = eventSchemas.agent_error.safeParse({
-      error_class: 'auth_expired',
-      agent_kind: 'claude-code',
-      error_name: 'SomeNonWhitelistedName'
-    })
-    expect(parsed.success).toBe(false)
-  })
-
   // Core invariant: `.strict()` rejects raw error strings. If this test ever
   // flips, the analytics lane is leaking UGC — revert the offending schema
   // change.
   it('rejects error_message via .strict()', () => {
     const parsed = eventSchemas.agent_error.safeParse({
-      error_class: 'auth_expired',
+      error_class: 'unknown',
       agent_kind: 'claude-code',
       error_message: 'boom at /Users/alice/secret/path'
     })
@@ -58,13 +37,25 @@ describe('agent_error schema', () => {
 
   it('rejects error_stack via .strict()', () => {
     const parsed = eventSchemas.agent_error.safeParse({
-      error_class: 'auth_expired',
+      error_class: 'unknown',
       agent_kind: 'claude-code',
       error_stack: 'Error: boom\n    at /Users/alice/...'
     })
     expect(parsed.success).toBe(false)
   })
 
+  it('rejects error_name (deferred — schema is enum-only)', () => {
+    // `error_name` was part of an earlier draft. The trimmed schema is
+    // enum-only; if a future PR re-introduces it as additive-optional,
+    // this test should be replaced rather than relaxed silently.
+    const parsed = eventSchemas.agent_error.safeParse({
+      error_class: 'unknown',
+      agent_kind: 'claude-code',
+      error_name: 'BinaryNotFound'
+    })
+    expect(parsed.success).toBe(false)
+  })
+
   it('rejects unknown error_class enum values', () => {
     const parsed = eventSchemas.agent_error.safeParse({
       error_class: 'made_up_class',
@@ -75,7 +66,7 @@ describe('agent_error schema', () => {
 
   it('rejects unknown agent_kind enum values', () => {
     const parsed = eventSchemas.agent_error.safeParse({
-      error_class: 'auth_expired',
+      error_class: 'unknown',
       agent_kind: 'made_up_agent'
     })
     expect(parsed.success).toBe(false)
@@ -199,9 +190,9 @@ describe('commonPropsSchema', () => {
 
 describe('exported enum schemas', () => {
   it('agentKindSchema accepts the known product IDs', () => {
-    expect(agentKindSchema.safeParse('claude-code').success).toBe(true)
-    expect(agentKindSchema.safeParse('codex').success).toBe(true)
-    expect(agentKindSchema.safeParse('other').success).toBe(true)
+    for (const kind of AGENT_KIND_VALUES) {
+      expect(agentKindSchema.safeParse(kind).success).toBe(true)
+    }
   })
 
   it('errorClassSchema rejects novel classes', () => {
@@ -213,10 +204,4 @@ describe('exported enum schemas', () => {
       expect(settingsChangedKeySchema.safeParse(key).success).toBe(true)
     }
   })
-
-  it('agentErrorNameSchema membership matches AGENT_ERROR_NAME_WHITELIST', () => {
-    for (const name of AGENT_ERROR_NAME_WHITELIST) {
-      expect(agentErrorNameSchema.safeParse(name).success).toBe(true)
-    }
-  })
 })
diff --git a/src/shared/telemetry-events.ts b/src/shared/telemetry-events.ts
index 8840027b8ff..a12d8ec0f74 100644
--- a/src/shared/telemetry-events.ts
+++ b/src/shared/telemetry-events.ts
@@ -14,64 +14,62 @@
 
 import { z } from 'zod'
 
+import type { GlobalSettings } from './types'
+
 // ── Shared property enums ───────────────────────────────────────────────
 
-// Mirrors the detectable agents in `src/shared/agent-detection.ts`
-// (`AGENT_NAMES`), with one deliberate shift: `claude` in AGENT_NAMES ↔
-// `claude-code` here (product, not CLI string) so dashboards read cleanly.
+// Mirrors the shipped `TuiAgent` launch surface, with one deliberate shift:
+// `claude` in settings/launch state ↔ `claude-code` here (product, not CLI
+// string) so dashboards read cleanly.
 //
-// Enum values are limited to agents that have a real emit path today. Adding
-// a new agent is additive-safe — extend this enum when the call site that
-// would emit it lands, not in anticipation.
-export const agentKindSchema = z.enum([
+// `other` remains as a telemetry escape hatch, but project-owned TuiAgents
+// should map to concrete values; see `tuiAgentToAgentKind`.
+export const AGENT_KIND_VALUES = [
   'claude-code',
   'codex',
-  'gemini',
-  'copilot',
-  'cursor',
+  'autohand',
   'opencode',
+  'pi',
+  'gemini',
   'aider',
+  'goose',
+  'amp',
+  'kilo',
+  'kiro',
+  'crush',
+  'aug',
+  'cline',
+  'codebuff',
+  'continue',
+  'cursor',
+  'droid',
+  'kimi',
+  'mistral-vibe',
+  'qwen-code',
+  'rovo',
+  'hermes',
+  'copilot',
   'other'
-])
+] as const
+export const agentKindSchema = z.enum(AGENT_KIND_VALUES)
 export type AgentKind = z.infer<typeof agentKindSchema>
 
-export const errorClassSchema = z.enum([
-  'network_timeout',
-  'auth_expired',
-  'rate_limited',
-  'provider_unavailable',
-  'provider_error_generic',
-  'binary_not_found',
-  'binary_version_mismatch',
-  'workspace_gone',
-  'user_cancelled',
-  'unknown'
-])
+// Trimmed to the two values Orca's PTY-typed-command launch architecture can
+// actually emit:
+//   - `binary_not_found` — `provider.spawn` ENOENT (the *shell* binary is
+//     missing). The agent CLI being missing is invisible: Orca spawns a
+//     healthy shell and types the command, and bash/zsh's "command not found"
+//     surfaces only as terminal output.
+//   - `unknown` — every other thrown error (paste-readiness timeout, env-build
+//     failures, unclassifiable shell-spawn errors).
+// Provider-side errors (`auth_expired`, `rate_limited`, `network_timeout`,
+// `provider_*`) happen inside the agent CLI subprocess and are not observable
+// to Orca — see telemetry-plan.md §Decision: Defer per-incident error fields.
+// Adding a new value is additive-safe; do it when the call site lands, not in
+// anticipation.
+export const errorClassSchema = z.enum(['binary_not_found', 'unknown'])
 export type ErrorClass = z.infer<typeof errorClassSchema>
 
-// Closed whitelist of error `name` strings allowed on `agent_error`. This is
-// the one free-ish string that can leave the machine on an agent_error event
-// — the validator drops anything not in this set.
-//
-// A regex-shape check (e.g. `/^[A-Z][A-Za-z]{0,32}$/`) would permit
-// identifier-shaped leaks like `PaymentFailedForUserAlice` or
-// `TimeoutInRepoMyCompanyInternalMonorepo` — context-concatenation bugs
-// under deadline pressure. A closed whitelist forces each new error name
-// through review. Same pattern as `SETTINGS_CHANGED_WHITELIST`.
-export const AGENT_ERROR_NAME_WHITELIST = [
-  'NetworkTimeout',
-  'AuthExpired',
-  'RateLimited',
-  'ProviderUnavailable',
-  'ProviderErrorGeneric',
-  'BinaryNotFound',
-  'BinaryVersionMismatch',
-  'WorkspaceGone',
-  'UserCancelled'
-] as const
-export const agentErrorNameSchema = z.enum(AGENT_ERROR_NAME_WHITELIST)
-export type AgentErrorName = z.infer<typeof agentErrorNameSchema>
-
 export const repoMethodSchema = z.enum(['folder_picker', 'clone_url', 'drag_drop'])
 export type RepoMethod = z.infer<typeof repoMethodSchema>
 
@@ -104,7 +102,12 @@ export type RequestKind = z.infer<typeof requestKindSchema>
 // never fire a `telemetry_opted_in/out` event. If a future path explicitly
 // persists an env-var-driven opt-out, add `env_var` back here together with
 // the call site.
-export const optInViaSchema = z.enum(['first_launch_banner', 'first_launch_notice', 'settings'])
+//
+// `first_launch_notice` (new-user disclosure toast) is deliberately absent —
+// the new-user cohort has no first-launch surface (see telemetry-plan.md
+// §First-launch experience). Opt-outs from new users come through
+// `via: 'settings'`.
+export const optInViaSchema = z.enum(['first_launch_banner', 'settings'])
 export type OptInVia = z.infer<typeof optInViaSchema>
 
 // Whitelist of settings whose `setting_key` may be emitted on
@@ -121,12 +124,18 @@ export type OptInVia = z.infer<typeof optInViaSchema>
 //
 // Kept as an `as const` tuple so the Zod enum below and any call-site usage
 // share one array — typo-drift is impossible.
+type BooleanGlobalSettingsKey = {
+  [Key in keyof GlobalSettings]-?: GlobalSettings[Key] extends boolean ? Key : never
+}[keyof GlobalSettings]
 export const SETTINGS_CHANGED_WHITELIST = [
   'editorAutoSave',
   'openLinksInApp',
-  'experimentalTerminalDaemon',
-  'experimentalAgentDashboard'
-] as const
+  'experimentalAgentDashboard',
+  'experimentalMobile',
+  'experimentalSidekick',
+  'experimentalWorktreeSymlinks',
+  'geminiCliOAuthEnabled'
+] as const satisfies readonly BooleanGlobalSettingsKey[]
 export const settingsChangedKeySchema = z.enum(SETTINGS_CHANGED_WHITELIST)
 export type SettingsChangedKey = z.infer<typeof settingsChangedKeySchema>
 
@@ -156,22 +165,15 @@ const agentStartedSchema = z
   })
   .strict()
 
-// Enum-only by design for `error_class` + `agent_kind`. `error_name` is the
-// one free-ish string that can leave the machine on this event, and it is
-// drawn from the closed `AGENT_ERROR_NAME_WHITELIST` — adding a new value
-// requires a PR to the whitelist, giving review a chance to catch
-// context-concatenation patterns.
-//
-// `error_message` and `error_stack` are deliberately absent from this schema.
-// `.strict()` rejects either key if a call site ever tries to attach one,
-// which fails the validator and drops the event. Raw error strings carry
-// arbitrary user/workspace/path content; keeping them off the wire is the
-// only way to guarantee we never transmit them by accident.
+// Enum-only by design for both fields. `error_message` and `error_stack` are
+// deliberately absent — `.strict()` rejects either key if a call site ever
+// tries to attach one, which fails the validator and drops the event. Raw
+// error strings carry arbitrary user/workspace/path content; keeping them off
+// the wire is the only way to guarantee we never transmit them by accident.
 const agentErrorSchema = z
   .object({
     error_class: errorClassSchema,
-    agent_kind: agentKindSchema,
-    error_name: agentErrorNameSchema.optional()
+    agent_kind: agentKindSchema
   })
   .strict()
 
diff --git a/src/shared/tui-agent-config.ts b/src/shared/tui-agent-config.ts
index a5ed20950a2..174fe71500e 100644
--- a/src/shared/tui-agent-config.ts
+++ b/src/shared/tui-agent-config.ts
@@ -12,6 +12,32 @@ export type TuiAgentConfig = {
   launchCmd: string
   expectedProcess: string
   promptInjectionMode: AgentPromptInjectionMode
+  /** Why: flag that launches the TUI with the given text already in the
+   * input box but NOT submitted, so the user still gets a reviewable draft.
+   * Only set when the CLI documents native support — e.g. Claude's
+   * `--prefill <text>`. The draft-launch flow prefers this over the
+   * post-launch bracketed-paste path because it eliminates the empirical
+   * agent-readiness wait entirely: the TUI mounts with the input pre-filled.
+   * Agents without native support fall through to the paste-after-ready
+   * code path in agent-paste-draft.ts. */
+  draftPromptFlag?: string
+  /** Why: agents that don't expose a `--prefill <text>`-style CLI flag but
+   * CAN read an env var on startup to seed their input box without
+   * submitting. Today only pi uses this (via Orca's overlay-installed
+   * `orca-prefill` extension reading `ORCA_PI_PREFILL`). Equivalent in
+   * effect to `draftPromptFlag`: avoids the bracketed-paste-after-ready
+   * race when the agent's startup output is long (pi prints banner,
+   * skills, and extensions for several seconds, which keeps the
+   * readiness quiet-timer resetting). When set, the draft-launch plan
+   * passes the text via this env var instead of pasting after ready. */
+  draftPromptEnvVar?: string
+  /** Why: agents that gate first-launch behind a "Do you trust this
+   * folder?" menu (Cursor-Agent, GitHub Copilot CLI) consume the bracketed
+   * paste as menu input. Pre-write the same trust artifact the agent writes
+   * after the user accepts so the menu never fires. The actual file/path
+   * written lives in src/main/agent-trust-presets.ts; this flag just routes
+   * the workspace path through the matching preset before the agent spawns. */
+  preflightTrust?: 'cursor' | 'copilot'
 }
 
 // Why: the new-workspace handoff depends on three pieces of per-agent
@@ -25,7 +51,12 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     detectCmd: 'claude',
     launchCmd: 'claude',
     expectedProcess: 'claude',
-    promptInjectionMode: 'argv'
+    promptInjectionMode: 'argv',
+    // Why: `claude --prefill <text>` lands the TUI with `<text>` in the
+    // input box, nothing submitted. Strictly better than the paste-after-
+    // ready fallback because it eliminates the readiness race entirely.
+    // See PR https://github.com/stablyai/orca/pull/926 for context.
+    draftPromptFlag: '--prefill'
   },
   codex: {
     detectCmd: 'codex',
@@ -33,6 +64,12 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     expectedProcess: 'codex',
     promptInjectionMode: 'argv'
   },
+  autohand: {
+    detectCmd: 'autohand',
+    launchCmd: 'autohand',
+    expectedProcess: 'autohand',
+    promptInjectionMode: 'stdin-after-start'
+  },
   opencode: {
     detectCmd: 'opencode',
     launchCmd: 'opencode',
@@ -43,7 +80,15 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     detectCmd: 'pi',
     launchCmd: 'pi',
     expectedProcess: 'pi',
-    promptInjectionMode: 'argv'
+    promptInjectionMode: 'argv',
+    // Why: pi has no `--prefill` flag, and bracketed-paste-after-ready
+    // races against its multi-second startup output (banner + skills +
+    // extensions list) so the paste frequently never lands. Orca's
+    // overlay installs an `orca-prefill` pi extension (see
+    // src/main/pi/titlebar-extension-service.ts) that reads this env var
+    // on session_start and calls `pi.ui.setEditorText(text)`. Same
+    // user-visible behavior as `claude --prefill <text>`.
+    draftPromptEnvVar: 'ORCA_PI_PREFILL'
   },
   gemini: {
     detectCmd: 'gemini',
@@ -122,7 +167,13 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     detectCmd: 'cursor-agent',
     launchCmd: 'cursor-agent',
     expectedProcess: 'cursor-agent',
-    promptInjectionMode: 'argv'
+    promptInjectionMode: 'argv',
+    // Why: cursor-agent's first-launch trust menu ([a]/[w]/[q]) used to
+    // swallow our bracketed paste. Pre-writing the same `.workspace-trusted`
+    // marker the CLI itself writes after the user accepts (see
+    // agent-trust-presets.ts) makes the menu skip entirely, so the draft
+    // URL paste lands in the input as intended.
+    preflightTrust: 'cursor'
   },
   droid: {
     detectCmd: 'droid',
@@ -168,6 +219,12 @@ export const TUI_AGENT_CONFIG: Record<TuiAgent, TuiAgentConfig> = {
     // completion, which would kill the TUI session Orca is hosting.
     // `-i/--interactive <prompt>` starts an interactive session with the
     // initial prompt pre-executed — the behavior Orca needs.
-    promptInjectionMode: 'flag-interactive'
+    promptInjectionMode: 'flag-interactive',
+    // Why: Copilot's first-launch trust menu used to swallow our bracketed
+    // paste. Pre-appending the workspace path to `trustedFolders` in
+    // ~/.copilot/config.json (the same array Copilot's own
+    // `addTrustedFolder` writes after the user accepts) makes the menu skip
+    // entirely. See agent-trust-presets.ts for the file layout.
+    preflightTrust: 'copilot'
   }
 }
diff --git a/src/shared/types.ts b/src/shared/types.ts
index a10f9a333d6..f83802006d8 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1,5 +1,11 @@
 /* eslint-disable max-lines */
 import type { SshTarget } from './ssh-types'
+import type { WorkspaceSource } from './telemetry-events'
+import type { GitHubProjectSettings } from './github-project-types'
+
+// Re-exported for backward compat with renderer call sites that import
+// `WorkspaceCreateTelemetrySource` from '../../../shared/types'.
+export type { WorkspaceSource as WorkspaceCreateTelemetrySource } from './telemetry-events'
 
 // ─── Repo ────────────────────────────────────────────────────────────
 export type RepoKind = 'git' | 'folder'
@@ -37,6 +43,12 @@ export type Repo = {
    *  identically to `'auto'`; writers leave it undefined on creation so
    *  existing persisted records stay forward-compatible. */
   issueSourcePreference?: IssueSourcePreference
+  /** Paths (relative to the primary checkout) that should be symlinked into
+   *  newly created worktrees of this repo. Consumed only when the global
+   *  `experimentalWorktreeSymlinks` flag is on — the per-repo list is the
+   *  "what to link", the global flag is the "whether to link at all" switch.
+   *  Undefined/empty means no symlinks are created for this repo. */
+  symlinkPaths?: string[]
 }
 
 export type SetupRunPolicy = 'ask' | 'run-by-default' | 'skip-by-default'
@@ -89,6 +101,11 @@ export type Worktree = {
   isPinned: boolean
   sortOrder: number
   lastActivityAt: number
+  /** Set once when Orca creates the worktree. Absent for worktrees discovered
+   *  on disk or persisted before this field existed. Used by the sidebar to
+   *  grant newly-created worktrees a short grace window at the top of Recent,
+   *  immune to ambient PTY-bump reordering in other worktrees. */
+  createdAt?: number
   sparseDirectories?: string[]
   sparseBaseRef?: string
   /** ID of the saved preset this worktree was created from, if any. Cleared
@@ -109,6 +126,8 @@ export type WorktreeMeta = {
   isPinned: boolean
   sortOrder: number
   lastActivityAt: number
+  /** See {@link Worktree.createdAt}. Persisted to orca-data.json. */
+  createdAt?: number
   sparseDirectories?: string[]
   sparseBaseRef?: string
   sparsePresetId?: string
@@ -639,6 +658,11 @@ export type LinearComment = {
 export type GitHubIssueUpdate = {
   state?: 'open' | 'closed'
   title?: string
+  // Why: body writes are driven by the Project-mode slug-addressed path
+  // (`updateIssueBySlug`) because `gh issue edit` does not consistently
+  // cover every body-edit case the dialog needs; the repoPath-based
+  // `updateIssue` flow keeps ignoring `body` for backward compatibility.
+  body?: string
   addLabels?: string[]
   removeLabels?: string[]
   addAssignees?: string[]
@@ -671,6 +695,33 @@ export type ClassifiedError = {
 // can continue using the short local name.
 export type GitHubOwnerRepo = { owner: string; repo: string }
 
+/**
+ * GitHub API rate-limit buckets surfaced in the TaskPage header so users can
+ * see remaining budget before they hit the wall. `core` = REST (5000/hr),
+ * `search` = Search API (30/min — hit by countWorkItems), `graphql` =
+ * GraphQL (5000 points/hr — hit by project-view + discovery). All three are
+ * the buckets this app actually stresses; other buckets (e.g. code_search)
+ * are not surfaced because we don't touch them.
+ */
+export type GitHubRateLimitBucket = {
+  remaining: number
+  limit: number
+  /** Unix epoch seconds when the window resets. */
+  resetAt: number
+}
+
+export type GitHubRateLimitSnapshot = {
+  core: GitHubRateLimitBucket
+  search: GitHubRateLimitBucket
+  graphql: GitHubRateLimitBucket
+  /** Unix epoch ms the snapshot was produced (for "fetched Xs ago" copy). */
+  fetchedAt: number
+}
+
+export type GetRateLimitResult =
+  | { ok: true; snapshot: GitHubRateLimitSnapshot }
+  | { ok: false; error: string }
+
 /**
  * Envelope for `gh:listWorkItems`. Carries resolved issue/PR sources so the
  * renderer can render the "Issues from owner/repo" indicator without an
@@ -793,6 +844,15 @@ export type CreateWorktreeArgs = {
   baseBranch?: string
   setupDecision?: SetupDecision
   sparseCheckout?: CreateSparseCheckoutRequest
+  /** Telemetry-only: which UI surface initiated this create. Threaded from
+   *  the renderer entry point so main can emit `workspace_created` with the
+   *  correct `source`. `unknown` is a valid wire value — an unrecognized
+   *  surface emits `source: 'unknown'` rather than dropping the event, so
+   *  dashboards surface enum-coverage gaps as a slice rather than as
+   *  missing data. Optional on the type so older renderer code paths that
+   *  pre-date this prop default to `unknown` at the IPC boundary instead
+   *  of failing typecheck. */
+  telemetrySource?: WorkspaceSource
 }
 
 export type CreateWorktreeResult = {
@@ -847,6 +907,7 @@ export type NotificationSettings = {
   agentTaskComplete: boolean
   terminalBell: boolean
   suppressWhenFocused: boolean
+  customSoundPath: string | null
 }
 
 export type CodexManagedAccount = {
@@ -910,6 +971,7 @@ export type ClaudeRateLimitAccountsState = {
 export type TuiAgent =
   | 'claude' // Claude Code
   | 'codex' // OpenAI Codex
+  | 'autohand' // Autohand Code CLI
   | 'opencode' // OpenCode
   | 'pi' // Pi (pi.dev)
   | 'gemini' // Gemini CLI
@@ -980,6 +1042,7 @@ export type GlobalSettings = {
   branchPrefixCustom: string
   enableGitHubAttribution: boolean
   theme: 'system' | 'dark' | 'light'
+  appFontFamily: string
   editorAutoSave: boolean
   editorAutoSaveDelayMs: number
   editorMinimapEnabled: boolean
@@ -1158,6 +1221,17 @@ export type GlobalSettings = {
    *  off never mount the overlay. Toggling takes effect immediately in the
    *  current session (no relaunch) because it is purely renderer-side. */
   experimentalSidekick: boolean
+  /** Experimental: when creating a worktree, automatically symlink a
+   *  user-configured set of files/folders from the primary checkout (e.g.
+   *  `.env`, `node_modules`) into the new worktree. Opt-in while the
+   *  configuration surface and edge cases (conflicts with existing paths,
+   *  cleanup on worktree delete) are still being worked out. */
+  experimentalWorktreeSymlinks: boolean
+  /** 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
+   *  default via the persistence merge. */
+  githubProjects?: GitHubProjectSettings
   /** Anonymous product-telemetry state. Optional because the one-shot
    *  migration in `Store.load()` is what populates it on first boot of the
    *  telemetry release; before migration runs, the field is absent. After
@@ -1177,14 +1251,12 @@ export type GlobalSettings = {
     /** New users: initialized to `true` at install.
      *  Existing users: `null` until they resolve the first-launch banner. */
     optedIn: boolean | null
-    /** Anonymous UUID v4. Generated on first run. Regenerable from Privacy pane. */
+    /** Anonymous UUID v4. Generated on first run. Stable across launches; not surfaced in the UI. */
     installId: string
-    /** Cohort marker set once during migration. Drives toast-vs-banner. */
+    /** Cohort marker set once during migration. True for users with a
+     *  pre-existing profile (gates the existing-user opt-in banner);
+     *  false for fresh installs (no first-launch surface). */
     existedBeforeTelemetryRelease: boolean
-    /** New-user toast: true only after active dismissal ("Got it" or "Turn off").
-     *  Re-shows on next launch if false/undefined so the consent disclosure
-     *  is never silently skipped by quitting mid-session. */
-    firstRunNoticeShown?: boolean
   }
 }
 
@@ -1213,6 +1285,34 @@ export type NotificationDispatchResult = {
   reason?: 'disabled' | 'source-disabled' | 'suppressed-focus' | 'cooldown' | 'not-supported'
 }
 
+export type NotificationSoundResult = {
+  played: boolean
+  reason?:
+    | 'missing-path'
+    | 'invalid-path'
+    | 'unsupported-type'
+    | 'too-large'
+    | 'read-failed'
+    | 'playback-failed'
+    | 'deduped'
+}
+
+export type NotificationSoundDataResult =
+  | {
+      ok: true
+      data: Uint8Array
+      mimeType: string
+      path: string
+    }
+  | {
+      ok: false
+      reason: Exclude<NotificationSoundResult['reason'], 'playback-failed'>
+    }
+
+export type NotificationSoundPathResult =
+  | { ok: true; path: string }
+  | { ok: false; reason: 'missing-path' | 'invalid-path' | 'unsupported-type' }
+
 export type WorktreeCardProperty =
   | 'status'
   | 'unread'
@@ -1228,14 +1328,16 @@ export type WorktreeCardProperty =
   // view options.
   | 'inline-agents'
 
-export type StatusBarItem =
-  | 'claude'
-  | 'codex'
-  | 'gemini'
-  | 'opencode-go'
-  | 'ssh'
-  | 'sessions'
-  | 'memory'
+export type StatusBarItem = 'claude' | 'codex' | 'gemini' | 'opencode-go' | 'ssh' | 'resource-usage'
+
+export type TaskResumeState = {
+  githubMode?: 'items' | 'project'
+  githubItemsPreset?: TaskViewPresetId | null
+  githubItemsQuery?: string
+  linearPreset?: 'assigned' | 'created' | 'all' | 'completed'
+  linearQuery?: string
+}
+
 export type PersistedUIState = {
   lastActiveRepoId: string | null
   lastActiveWorktreeId: string | null
@@ -1324,8 +1426,19 @@ export type PersistedUIState = {
    *  this field is the metadata index so custom sidekicks ride the existing
    *  PersistedUIState save pipeline. */
   customSidekicks?: CustomSidekick[]
+  /** On-screen size of the sidekick overlay in CSS pixels (square box).
+   *  Clamped to [SIDEKICK_SIZE_MIN, SIDEKICK_SIZE_MAX] when read. */
+  sidekickSize?: number
+  /** Page-position state for Tasks. Source/repo/team/project selections keep
+   *  using their existing settings paths; this only restores transient tabs
+   *  and applied searches. */
+  taskResumeState?: TaskResumeState
 }
 
+export const SIDEKICK_SIZE_MIN = 60
+export const SIDEKICK_SIZE_MAX = 360
+export const SIDEKICK_SIZE_DEFAULT = 180
+
 /** Metadata for a user-uploaded sidekick image. `id` is the stable identifier;
  *  the on-disk filename (preserving the original extension) lives in `fileName`.
  *  The renderer never learns the absolute path — it asks main for the bytes
@@ -1338,6 +1451,36 @@ export type CustomSidekick = {
    *  Content-Type — especially image/svg+xml, which browsers won't render
    *  from a misdeclared blob URL. */
   mimeType: string
+  /** Storage layout. `image` = legacy flat file at `custom/<id>.<ext>`.
+   *  `bundle` = `.codex-pet` import expanded into `custom/<id>/`. Absent =
+   *  legacy `image` for backwards compatibility with persisted state. */
+  kind?: 'image' | 'bundle'
+  /** Sprite-sheet metadata captured at import time. Present iff this entry
+   *  came from a `.codex-pet` bundle and the manifest declared frame layout.
+   *  `columns`/`rows`/`sheetWidth`/`sheetHeight` are derived in main from
+   *  the decoded sheet so the renderer doesn't need to probe the image. */
+  sprite?: {
+    frameWidth: number
+    frameHeight: number
+    columns: number
+    rows: number
+    sheetWidth: number
+    sheetHeight: number
+    fps: number
+    defaultAnimation?: string
+    animations?: Record<string, SpriteAnimation>
+  }
+  /** Manifest-declared fps captured even when the manifest omits `frame` and
+   *  the renderer falls back to auto-detected frames. Lets DetectedSpriteFrame
+   *  honor the bundle's intended playback speed instead of a hardcoded 8 fps. */
+  spriteFps?: number
+}
+
+/** One animation strip within a sprite sheet: `row` is the y-index (0-based)
+ *  and `frames` is the number of consecutive cells played left-to-right. */
+export type SpriteAnimation = {
+  row: number
+  frames: number
 }
 
 export type PersistedTrustedOrcaHookEntry = {
diff --git a/src/shared/window-shortcut-policy.test.ts b/src/shared/window-shortcut-policy.test.ts
index 4d30d73c0a0..06cae2cc09f 100644
--- a/src/shared/window-shortcut-policy.test.ts
+++ b/src/shared/window-shortcut-policy.test.ts
@@ -270,23 +270,22 @@ describe('resolveWindowShortcutAction', () => {
     ).toBeNull()
   })
 
-  it('routes Cmd/Ctrl+Shift+N to the Create-from tab of the new-workspace composer', () => {
-    // Why: the shift variant of the new-workspace shortcut jumps straight to
-    // the "Create from…" tab so users can start from an existing GH/Linear
-    // item without a detour through the quick-create form.
+  it('routes Cmd/Ctrl+Shift+N to the unified new-workspace composer', () => {
+    // Why: keep the former Create-from shortcut accepted so muscle memory
+    // still opens the composer; source switching now lives in the smart name field.
     expect(
       resolveWindowShortcutAction(
         { code: 'KeyN', key: 'n', meta: true, control: false, alt: false, shift: true },
         'darwin'
       )
-    ).toEqual({ type: 'openNewWorkspace', tab: 'create-from' })
+    ).toEqual({ type: 'openNewWorkspace' })
 
     expect(
       resolveWindowShortcutAction(
         { code: 'KeyN', key: 'n', meta: false, control: true, alt: false, shift: true },
         'linux'
       )
-    ).toEqual({ type: 'openNewWorkspace', tab: 'create-from' })
+    ).toEqual({ type: 'openNewWorkspace' })
 
     // Alt must still be rejected — the allowlist is alt-free for Cmd/Ctrl+N
     // so future chords like Cmd+Alt+Shift+N remain available.
@@ -320,7 +319,7 @@ describe('resolveWindowShortcutAction', () => {
       [{ code: 'KeyR', key: 'p', meta: true, alt: false, shift: false }, { type: 'openQuickOpen' }],
       [
         { code: 'KeyL', key: 'n', meta: true, alt: false, shift: false },
-        { type: 'openNewWorkspace', tab: 'quick' }
+        { type: 'openNewWorkspace' }
       ],
       [
         { code: 'KeyC', key: 'j', meta: true, alt: false, shift: false },
@@ -350,7 +349,7 @@ describe('resolveWindowShortcutAction', () => {
       ],
       [
         { code: 'KeyN', key: 'Dead', meta: true, alt: false, shift: false },
-        { type: 'openNewWorkspace', tab: 'quick' }
+        { type: 'openNewWorkspace' }
       ],
       [{ code: 'KeyP', meta: true, alt: false, shift: false }, { type: 'openQuickOpen' }]
     ]
diff --git a/src/shared/window-shortcut-policy.ts b/src/shared/window-shortcut-policy.ts
index 4b742caaa06..2d2c751e16d 100644
--- a/src/shared/window-shortcut-policy.ts
+++ b/src/shared/window-shortcut-policy.ts
@@ -13,7 +13,7 @@ export type WindowShortcutAction =
   | { type: 'toggleLeftSidebar' }
   | { type: 'toggleRightSidebar' }
   | { type: 'openQuickOpen' }
-  | { type: 'openNewWorkspace'; tab: 'quick' | 'create-from' }
+  | { type: 'openNewWorkspace' }
   | { type: 'jumpToWorktreeIndex'; index: number }
   | { type: 'worktreeHistoryNavigate'; direction: 'back' | 'forward' }
 
@@ -167,12 +167,11 @@ export function resolveWindowShortcutAction(
   // main process so it reaches the renderer even when focus lives inside
   // a contentEditable surface (markdown rich editor) or a browser guest
   // webContents, both of which bypass the renderer's window-level keydown.
-  // Cmd/Ctrl+Shift+N opens the composer on the "Create from…" tab so users
-  // can start a workspace directly from an existing PR, issue, branch, or
-  // Linear ticket without going through the quick-create flow first.
+  // Shift is accepted for compatibility with the former Create-from shortcut;
+  // the unified composer now exposes source switching inside the name field.
   if (matchesLetterShortcut(input, 'n', 'KeyN')) {
     if (!input.alt) {
-      return { type: 'openNewWorkspace', tab: input.shift ? 'create-from' : 'quick' }
+      return { type: 'openNewWorkspace' }
     }
   }
 
diff --git a/src/shared/workspace-session-schema.test.ts b/src/shared/workspace-session-schema.test.ts
index 0b24fe5eb17..4a25933f4aa 100644
--- a/src/shared/workspace-session-schema.test.ts
+++ b/src/shared/workspace-session-schema.test.ts
@@ -95,4 +95,25 @@ describe('parseWorkspaceSession', () => {
     expect(parseWorkspaceSession('garbage').ok).toBe(false)
     expect(parseWorkspaceSession(42).ok).toBe(false)
   })
+
+  it('drops bad lastVisitedAtByWorktreeId entries rather than failing the session', () => {
+    const result = parseWorkspaceSession({
+      activeRepoId: null,
+      activeWorktreeId: null,
+      activeTabId: null,
+      tabsByWorktree: {},
+      terminalLayoutsByTabId: {},
+      lastVisitedAtByWorktreeId: {
+        good: 1_700_000_000_000,
+        nan: Number.NaN,
+        infinite: Number.POSITIVE_INFINITY,
+        negative: -5,
+        string: 'nope'
+      }
+    })
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.value.lastVisitedAtByWorktreeId).toEqual({ good: 1_700_000_000_000 })
+    }
+  })
 })
diff --git a/src/shared/workspace-session-schema.ts b/src/shared/workspace-session-schema.ts
index 30ebae27044..66b1f3b3c39 100644
--- a/src/shared/workspace-session-schema.ts
+++ b/src/shared/workspace-session-schema.ts
@@ -207,9 +207,29 @@ export const workspaceSessionStateSchema: z.ZodType<WorkspaceSessionState> = z.o
   remoteSessionIdsByTabId: z.record(z.string(), 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. Constrain to finite non-negative numbers so a bad on-disk
-  // value is rejected at parse time rather than silently breaking Cmd+J.
-  lastVisitedAtByWorktreeId: z.record(z.string(), z.number().finite().nonnegative()).optional()
+  // Infinity here. Parse leniently: drop individual bad entries rather than
+  // failing the entire session. A strict record() rejection here would cause
+  // parseWorkspaceSession to fall back to defaults for the ENTIRE session
+  // (terminals, editors, browsers, layouts) on a single corrupted timestamp
+  // — a blast radius far larger than "Cmd+J falls back to activity recency",
+  // which is all this field gates.
+  lastVisitedAtByWorktreeId: z
+    .preprocess(
+      (raw) => {
+        if (raw == null || typeof raw !== 'object') {
+          return raw
+        }
+        const cleaned: Record<string, number> = {}
+        for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+          if (typeof v === 'number' && Number.isFinite(v) && v >= 0) {
+            cleaned[k] = v
+          }
+        }
+        return cleaned
+      },
+      z.record(z.string(), z.number().finite().nonnegative())
+    )
+    .optional()
 })
 
 export type ParsedWorkspaceSession =
diff --git a/tests/e2e/worktree-recent-sort.spec.ts b/tests/e2e/worktree-recent-sort.spec.ts
new file mode 100644
index 00000000000..82e24ca6e7b
--- /dev/null
+++ b/tests/e2e/worktree-recent-sort.spec.ts
@@ -0,0 +1,119 @@
+/**
+ * E2E test for newly-added worktrees sorting correctly in "Recent" mode.
+ *
+ * Why this exists:
+ *   Before the fix in `src/main/ipc/worktrees.ts`, a worktree that existed
+ *   on disk but had no persisted WorktreeMeta (the case for folder-mode
+ *   repos and pre-existing worktrees discovered when adding a new git repo)
+ *   fell back to `lastActivityAt: 0`. "Recent" sort orders by
+ *   `lastActivityAt` descending, so those worktrees landed dead last —
+ *   even though the user had just added them.
+ *
+ *   The `worktrees:list` / `worktrees:listAll` handlers now stamp
+ *   `lastActivityAt = Date.now()` on first discovery. This test locks that
+ *   behavior in end-to-end.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'fs'
+import os from 'os'
+import path from 'path'
+import type { Page } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import { waitForSessionReady, waitForActiveWorktree } from './helpers/store'
+
+async function addFolderRepo(page: Page, folderPath: string): Promise<string> {
+  return page.evaluate(async (p) => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('window.__store is unavailable')
+    }
+    // Why: go through the public addNonGitFolder path (not window.api.repos.add
+    // directly) so the test exercises the same flow the "Add Folder" dialog
+    // uses. That path fetches worktrees internally, which is what triggers the
+    // discovery stamp we're asserting about.
+    const repo = await store.getState().addNonGitFolder(p)
+    if (!repo) {
+      throw new Error('addNonGitFolder returned null')
+    }
+    return repo.id
+  }, folderPath)
+}
+
+async function readFolderWorktreeLastActivity(page: Page, repoId: string): Promise<number> {
+  return page.evaluate((id) => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('window.__store is unavailable')
+    }
+    const worktree = store.getState().worktreesByRepo[id]?.[0]
+    if (!worktree) {
+      throw new Error(`No worktree found for repo ${id}`)
+    }
+    return worktree.lastActivityAt
+  }, repoId)
+}
+
+test.describe('Worktree Recent Sort', () => {
+  // Why: keep fixture tracking scoped to this describe block. Module-level
+  // shared arrays race if the file ever flips to parallel mode or another
+  // describe is added.
+  const createdFolderFixtures: string[] = []
+
+  function createFolderFixture(): string {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'orca-e2e-folder-'))
+    createdFolderFixtures.push(dir)
+    mkdirSync(path.join(dir, 'src'), { recursive: true })
+    writeFileSync(path.join(dir, 'README.md'), '# folder fixture\n')
+    return dir
+  }
+
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+    await waitForActiveWorktree(orcaPage)
+  })
+
+  test.afterEach(() => {
+    // Why: mkdtempSync fixtures leak unless we clean them up explicitly —
+    // matches the mkdtempSync/rmSync pairing used in helpers/orca-app.ts
+    // and helpers/orca-restart.ts.
+    while (createdFolderFixtures.length) {
+      const dir = createdFolderFixtures.pop()
+      if (dir) {
+        rmSync(dir, { recursive: true, force: true })
+      }
+    }
+  })
+
+  test('stamps lastActivityAt on a newly-added folder repo so it sorts to the top of Recent', async ({
+    orcaPage
+  }) => {
+    const folderPath = createFolderFixture()
+
+    const repoId = await addFolderRepo(orcaPage, folderPath)
+    const lastActivityAt = await readFolderWorktreeLastActivity(orcaPage, repoId)
+
+    // Why: the exact failure mode before the fix was `lastActivityAt === 0`
+    // (the fallback in mergeWorktree when meta is undefined). Asserting
+    // `> 0` captures that regression precisely without coupling to the
+    // wall-clock of the main process, which would introduce cross-process
+    // clock-skew flakiness in CI.
+    expect(lastActivityAt).toBeGreaterThan(0)
+  })
+
+  test('leaves lastActivityAt stable across repeated list refreshes', async ({ orcaPage }) => {
+    // Why: the stamp fires only on *first* discovery. Re-fetching must not
+    // overwrite it, or every sidebar refresh would reshuffle Recent order.
+    const folderPath = createFolderFixture()
+    const repoId = await addFolderRepo(orcaPage, folderPath)
+
+    const first = await readFolderWorktreeLastActivity(orcaPage, repoId)
+
+    await orcaPage.evaluate(async (id) => {
+      await window.__store?.getState().fetchWorktrees(id)
+      await window.__store?.getState().fetchWorktrees(id)
+    }, repoId)
+
+    const second = await readFolderWorktreeLastActivity(orcaPage, repoId)
+    expect(second).toBe(first)
+  })
+})
diff --git a/tests/e2e/worktree.spec.ts b/tests/e2e/worktree.spec.ts
index 0bda64b3667..38eb07dd2e9 100644
--- a/tests/e2e/worktree.spec.ts
+++ b/tests/e2e/worktree.spec.ts
@@ -87,9 +87,12 @@ test.describe('Create Workspace', () => {
       })
       await orcaPage.waitForTimeout(100)
 
-      // 3. Type the workspace name into the Name input. This is what lets
-      // the composer pass its `workspaceName` guard inside submitQuick.
-      const nameInput = dialog.getByPlaceholder(/Workspace name/i)
+      // 3. Type the workspace name into the unified smart-name input.
+      // The composer's default mode is 'smart'; its placeholder advertises
+      // multiple input shapes ("Type a name, #1234, branch, GitHub or
+      // Linear URL"). Plain free-form text is treated as a workspace name
+      // by submitQuick, which is what we want here.
+      const nameInput = dialog.getByPlaceholder(/Type a name/i)
       await expect(nameInput).toBeVisible()
       await nameInput.fill(workspaceName)