Merge origin/main into brennanb2025/native-chat-multiline-send

.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Product source remains owned by its normal reviewers; localization inputs need focused review.
+/src/renderer/src/i18n/locales/ @brennanb2025
+/config/scripts/*localization*.mjs @brennanb2025
+/config/scripts/*locale*.mjs @brennanb2025
+/i18next.config.ts @brennanb2025

.github/actions/install-node-dependencies/action.yml

@@ -6,6 +6,10 @@ inputs:
     description: Native runtime to prepare after the script-free install (none, node, or electron).
     required: false
     default: none
+  node-version:
+    description: Node.js version override; defaults to the version declared in package.json.
+    required: false
+    default: ''
 
 runs:
   using: composite
@@ -17,11 +21,19 @@ runs:
         run_install: false
 
     - name: Setup Node.js
+      if: inputs.node-version == ''
       uses: actions/setup-node@v6
       with:
         node-version-file: package.json
         cache: pnpm
 
+    - name: Setup requested Node.js
+      if: inputs.node-version != ''
+      uses: actions/setup-node@v6
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: pnpm
+
     - name: Validate native runtime
       shell: bash
       env:

.github/workflows/computer-e2e.yml

@@ -9,6 +9,7 @@ on:
       - 'config/scripts/build-windows-cli-launcher.mjs'
       - 'config/scripts/build-windows-cli-launcher.test.mjs'
       - 'config/scripts/computer-e2e-workflow.test.mjs'
+      - 'config/scripts/computer-use-modifier-safety.test.mjs'
       - 'config/scripts/computer-use-skill-guidance.test.mjs'
       - 'config/scripts/computer-use-smoke.mjs'
       - 'config/scripts/computer-use-smoke.test.mjs'
@@ -84,6 +85,7 @@ jobs:
           config/scripts/build-windows-cli-launcher.test.mjs
           src/main/ssh/ssh-remote-cli-launcher.test.ts
           config/scripts/computer-e2e-workflow.test.mjs
+          config/scripts/computer-use-modifier-safety.test.mjs
           config/scripts/computer-use-skill-guidance.test.mjs
           config/scripts/computer-use-smoke.test.mjs
           src/main/computer/computer-provider-lifecycle.test.ts

.github/workflows/e2e.yml

@@ -184,7 +184,9 @@ jobs:
     name: ssh docker watcher isolation
     needs: build
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    # Why 35: the terminal parking + retention specs below add two more
+    # docker-rig tests capped at 240s each on top of the watcher isolation pair.
+    timeout-minutes: 35
 
     steps:
       - name: Checkout
@@ -227,6 +229,13 @@ jobs:
       - name: Run Docker SSH watcher isolation E2E
         run: xvfb-run --auto-servernum env SKIP_BUILD=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm run test:e2e:ssh-docker-watcher-isolation
 
+      # Why always(): these specs gate the C1 terminal parking/retention budget
+      # over a real SSH host and run in no other lane, so a watcher-isolation
+      # failure above must not silently skip them.
+      - name: Run Docker SSH terminal parking + retention E2E
+        if: always()
+        run: xvfb-run --auto-servernum env SKIP_BUILD=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm run test:e2e:ssh-docker-terminal-parking
+
       - name: Upload watcher isolation traces
         if: failure()
         uses: actions/upload-artifact@v7

.github/workflows/pr.yml

@@ -62,6 +62,11 @@ jobs:
       - name: Verify localization catalog
         run: pnpm run verify:localization-catalog
 
+      # Why: extraction writes sorted evidence to an isolated temporary path,
+      # so feature PRs need one normalized AST pass rather than a three-OS matrix.
+      - name: Verify localization extraction
+        run: pnpm run verify:localization-extraction
+
       - name: Verify localization coverage
         run: pnpm run verify:localization-coverage
 
@@ -179,12 +184,14 @@ jobs:
             src/shared/posix-command-path-lookup.test.ts
 
   test:
-    name: tests ${{ matrix.shard }}/${{ strategy.job-total }}
+    name: tests node ${{ matrix.node }} ${{ matrix.shard }}/${{ matrix.shard_total }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
+        node: ['24', '26']
         shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
+        shard_total: [16]
 
     steps:
       - name: Checkout
@@ -195,6 +202,7 @@ jobs:
       - uses: ./.github/actions/install-node-dependencies
         with:
           native-runtime: node
+          node-version: ${{ matrix.node }}
 
       - name: Install Electron package binary for tests
         run: node config/scripts/install-electron-package-binary.mjs
@@ -208,7 +216,7 @@ jobs:
             --exclude=src/main/providers/__tests__/shell-ready-framework-example.test.ts \
             --exclude=src/main/pty/omp-shell-wrapper.node-pty.test.ts \
             --exclude=src/shared/posix-command-path-lookup.test.ts \
-            --shard=${{ matrix.shard }}/${{ strategy.job-total }}
+            --shard=${{ matrix.shard }}/${{ matrix.shard_total }}
 
   package:
     name: package

.github/workflows/terminal-ime-e2e.yml

@@ -0,0 +1,99 @@
+name: Terminal IME E2E
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/terminal-ime-e2e.yml'
+      - 'config/patches/@xterm__xterm@6.1.0-beta.287.patch'
+      - 'config/scripts/run-terminal-ibus-hangul-e2e.mjs'
+      - 'config/scripts/terminal-ime-e2e-workflow.test.mjs'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'src/renderer/src/components/terminal-pane/keyboard-handlers.ts'
+      - 'src/renderer/src/components/terminal-pane/keyboard-handlers-ime.test.tsx'
+      - 'src/renderer/src/components/terminal-pane/pty-connection.ts'
+      - 'src/renderer/src/components/terminal-pane/pty-connection.test.ts'
+      - 'src/renderer/src/components/terminal-pane/terminal-ime-*'
+      - 'src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts'
+      - 'src/renderer/src/components/terminal-pane/xterm-bypass-policy.ts'
+      - 'src/renderer/src/components/terminal-pane/xterm-bypass-policy.test.ts'
+      - 'tests/e2e/chinese-ime-chat-input-repro.spec.ts'
+      - 'tests/e2e/korean-ime-terminal-shift-enter-commit.spec.ts'
+      - 'tests/e2e/terminal-ibus-hangul-native.spec.ts'
+      - 'tests/e2e/terminal-ime-*.ts'
+  workflow_dispatch:
+  schedule:
+    - cron: '30 9 * * *'
+
+permissions:
+  contents: read
+
+jobs:
+  linux-x11:
+    name: Linux X11 terminal IME
+    runs-on: ubuntu-22.04
+    timeout-minutes: 25
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Install native build and IME tools
+        run: >-
+          sudo apt-get update &&
+          sudo apt-get install -y
+          build-essential
+          dbus-x11
+          dconf-gsettings-backend
+          ibus
+          ibus-hangul
+          libglib2.0-bin
+          python3
+          xdotool
+          xfwm4
+          xvfb
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          run_install: false
+
+      - name: Use external node-gyp to avoid pnpm bundled copy
+        run: |
+          npm install -g node-gyp@11.5.0
+          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build Electron app for E2E
+        run: pnpm exec electron-vite build --mode e2e
+
+      - name: Run deterministic terminal IME boundary tests
+        run: >-
+          xvfb-run --auto-servernum
+          env SKIP_BUILD=1 ORCA_E2E_FORWARD_APP_LOGS=1
+          pnpm run test:e2e --
+          tests/e2e/terminal-ime-exact-byte.spec.ts
+          --workers=1
+
+      - name: Run native IBus Hangul exact-byte tests
+        env:
+          SKIP_BUILD: '1'
+        run: pnpm run test:e2e:terminal-ime-native
+
+      - name: Upload terminal IME evidence
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: terminal-ime-evidence
+          path: test-results/
+          retention-days: 7
+          if-no-files-found: ignore

README.md

@@ -36,7 +36,7 @@
 
 Monitor and steer your agents from your phone — get notified when an agent finishes and send follow-ups from anywhere.
 
-[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [Android APK 0.0.32](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.32/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
+[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [Android APK 0.0.36](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.36/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -230,7 +230,7 @@ yay -S stably-orca-bin
 Pair with your desktop app to monitor and steer your agents from your phone.
 
 - **iOS:** [Download on the App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) or [join TestFlight](https://testflight.apple.com/join/YjeGMQBA)
-- **Android:** [Download APK 0.0.32](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.32/app-release.apk)
+- **Android:** [Download APK 0.0.36](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.36/app-release.apk)
 
 ---
 

config/electron-builder.config.cjs

@@ -83,12 +83,17 @@ module.exports = {
     '!skill-guides{,/**/*}',
     '!skill-stubs{,/**/*}',
     '!tests{,/**/*}',
+    // Why: examples/ is plugin authoring documentation with no runtime consumer —
+    // bundled plugins ship via extraResources from resources/plugins/launch/. It also
+    // carries hostile-panel, the adversarial fixture the containment tests point at,
+    // which must never reach a user's install.
+    '!examples{,/**/*}',
     // Why: pr-evidence/ is a local e2e screenshot output (ORCA_CAPTURE_EVIDENCE);
     // it is gitignored, but exclude it defensively so a stray local capture at
     // package time never bloats app.asar.
     '!pr-evidence{,/**/*}',
     '!Casks{,/**/*}',
-    '!{AGENTS.md,CLAUDE.md,DEVELOPING.md,bundle-size-progress.md}',
+    '!{AGENTS.md,CLAUDE.md,DEVELOPING.md,bundle-size-progress.md,ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md,ORCHESTRATION_STRUCTURED_OUTPUT_DESIGN.md}',
     '!out/**/*.test.js',
     // Why: Vite's manifest is only used to project the paired web client.
     '!out/renderer/.vite{,/**/*}',

config/localization-audit.md

@@ -52,11 +52,27 @@ Sync catalog keys after adding or removing `translate(...)` calls:
 pnpm run sync:localization-catalog
 ```
 
-The sync command adds missing `en.json` entries from each call's string fallback,
-copies untranslated English placeholders into other locale catalogs to keep
-parity, removes locale entries whose English key was deleted, and repairs
-placeholder mismatches. Run the machine-translation bootstrap commands only when
-refreshing real translations, not for ordinary UI copy changes.
+The sync command adds missing `en.json` entries from each call's string fallback.
+It never edits target catalogs: missing values remain absent and use the existing
+runtime English fallback. Existing placeholder mismatches fail validation until
+a localization PR fixes or retires the target entry.
+
+Run maintained source extraction without committing a second English catalog:
+
+```sh
+pnpm run verify:localization-extraction
+```
+
+Extraction fails when a statically extracted key is absent from `en.json` or an
+inline default has incompatible placeholders. Existing unreferenced English keys
+and wording-only fallback drift are reported as migration debt; the permanent
+bilingual translation source will reconcile them without a large disposition
+database. Reviewed and stale translation state is likewise deferred to that
+source rather than inferred permanently from Git history.
+
+The legacy free-endpoint bootstrap and whole-catalog repair scripts intentionally
+have no package-script entry points. Ordinary product and localization work must
+not invoke tools that can overwrite an entire target catalog.
 
 The coverage gate compares current candidates against
 `config/localization-coverage-allowlist.json`. The committed allowlist is empty:
@@ -97,8 +113,8 @@ Recommended migration order:
 The final gate should combine three checks:
 
 1. Scanner coverage: no unclassified localizable candidates remain.
-2. Catalog coverage: every supported locale has the same keys as English, with
-   matching interpolation variables.
+2. Catalog correctness: existing translations have matching interpolation
+   variables; missing target entries are reported rather than rejected.
 3. Runtime coverage: pseudo-localization and real locale smoke tests show no
    obvious English leftovers or layout clipping in core screens.
 

config/scripts/computer-e2e-workflow.test.mjs

@@ -47,6 +47,7 @@ describe('computer-use e2e workflow', () => {
     expect(triggerPaths).toEqual(
       expect.arrayContaining([
         'config/scripts/computer-e2e-workflow.test.mjs',
+        'config/scripts/computer-use-modifier-safety.test.mjs',
         'config/scripts/computer-use-skill-guidance.test.mjs',
         'config/scripts/computer-use-smoke.mjs',
         'config/scripts/computer-use-smoke.test.mjs',
@@ -72,6 +73,7 @@ describe('computer-use e2e workflow', () => {
     const regressionRun = nativeSmokeRuns.find((run) => run.includes('pnpm vitest run'))
     const expectedRegressionFiles = [
       'config/scripts/computer-e2e-workflow.test.mjs',
+      'config/scripts/computer-use-modifier-safety.test.mjs',
       'config/scripts/computer-use-skill-guidance.test.mjs',
       'config/scripts/computer-use-smoke.test.mjs',
       'src/main/computer/computer-provider-lifecycle.test.ts',

config/scripts/computer-use-modifier-safety.test.mjs

@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const projectDir = resolve(import.meta.dirname, '../..')
+
+function source(path) {
+  return readFileSync(join(projectDir, path), 'utf8')
+}
+
+function sourceBetween(contents, startMarker, endMarker) {
+  const start = contents.indexOf(startMarker)
+  const end = contents.indexOf(endMarker, start + startMarker.length)
+  if (start < 0 || end < 0) {
+    throw new Error(`Missing source boundary: ${startMarker} → ${endMarker}`)
+  }
+  return contents.slice(start, end)
+}
+
+describe('computer-use modifier safety', () => {
+  it('uses mouse-event flags instead of held modifier keys on macOS', () => {
+    const macOS = source('native/computer-use-macos/Sources/OrcaComputerUseMacOS/main.swift')
+    const clickInput = sourceBetween(macOS, 'static func click(', 'static func scroll(')
+    const mouseInput = sourceBetween(
+      macOS,
+      'private static func mouse(',
+      'private static func keyEvent('
+    )
+
+    expect(mouseInput).toContain('event.flags = flags')
+    expect(clickInput.match(/flags: flags/gu)).toHaveLength(3)
+    expect(clickInput).not.toContain('down: true')
+  })
+
+  it('submits each modified Windows click in a closed, timed SendInput batch', () => {
+    const windows = source('native/computer-use-windows/runtime.ps1')
+    const modifiedClick = sourceBetween(
+      windows,
+      'public static void SendModifiedClick',
+      'private static INPUT KeyboardInput'
+    )
+    const mouseClick = sourceBetween(
+      windows,
+      'function Send-OrcaMouseClick',
+      'function Send-OrcaDrag'
+    )
+
+    expect(modifiedClick).toContain('SendInput((uint)values.Length, values')
+    expect(modifiedClick).toContain('SendInput((uint)releaseValues.Length, releaseValues')
+    expect(modifiedClick).toContain('if (sent != (uint)values.Length)')
+    expect(modifiedClick).toContain('releases.Add(MouseInput(mouseInput, mouseUp))')
+    expect(modifiedClick).not.toContain('int count')
+    expect(mouseClick).toMatch(
+      /for \(\$i = 0; \$i -lt \$clickCount; \$i\+\+\) \{\s+\[OrcaDesktopWin32\]::SendModifiedClick\(/
+    )
+    expect(mouseClick).toContain('if ($i + 1 -lt $clickCount) { Start-Sleep -Milliseconds 35 }')
+    expect(windows).not.toContain('keybd_event')
+  })
+
+  it('keeps Linux modifier release in the xdotool sequence and a fallback', () => {
+    const linux = source('native/computer-use-linux/runtime.py')
+    const modifiedClick = sourceBetween(linux, 'def modified_click_at(', 'def scroll_at(')
+
+    expect(modifiedClick).toContain('command.extend(["keyup", modifier])')
+    expect(modifiedClick).toContain('is_wayland')
+    expect(modifiedClick).toContain('modified clicks require xdotool on an X11 session')
+    expect(modifiedClick).toContain('finally:')
+    expect(modifiedClick).toContain('check=False')
+    expect(modifiedClick).toContain('timeout=5')
+    expect(modifiedClick).toContain('timeout=2')
+  })
+})

config/scripts/computer-use-skill-guidance.test.mjs

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
+import { BUNDLED_SKILL_GUIDES } from '../../src/cli/bundled-skill-guides'
 
 const projectDir = resolve(import.meta.dirname, '../..')
 // Why: computer-use now ships a hybrid discovery stub, so its version-sensitive command
@@ -8,6 +9,7 @@ const projectDir = resolve(import.meta.dirname, '../..')
 // installable stub projection is checked separately below.
 const guidePath = join(projectDir, 'skill-guides', 'computer-use.md')
 const stubPath = join(projectDir, 'skills', 'computer-use', 'SKILL.md')
+const bundledGuide = BUNDLED_SKILL_GUIDES.find((guide) => guide.name === 'computer-use')?.markdown
 
 describe('computer-use skill guidance', () => {
   it('keeps web-app targeting on the computer-use surface', () => {
@@ -44,6 +46,15 @@ describe('computer-use skill guidance', () => {
     expect(skill).toContain('`result.snapshot.treeText`')
     expect(skill).not.toContain('`result.elements`')
   })
+
+  it('requires atomic modifier-click actions in the source and bundled guide', () => {
+    expect(bundledGuide).toBeDefined()
+
+    for (const skill of [readFileSync(guidePath, 'utf8'), bundledGuide]) {
+      expect(skill).toContain('click --modifiers <chord>')
+      expect(skill).toContain('Never synthesize separate modifier-down and modifier-up commands')
+    }
+  })
 })
 
 describe('computer-use install stub', () => {

config/scripts/electron-builder-config.test.mjs

@@ -6,6 +6,7 @@ import { describe, expect, it } from 'vitest'
 
 const require = createRequire(import.meta.url)
 const electronBuilderConfig = require('../electron-builder.config.cjs')
+const { FileMatcher } = require('app-builder-lib/out/fileMatcher')
 const electronBuilderNativeRebuild = require('./electron-builder-native-rebuild.cjs')
 const {
   createPackagedRuntimeNodeModuleResources,
@@ -38,15 +39,39 @@ describe('electron-builder config', () => {
         '!skill-stubs{,/**/*}',
         '!resources/skills/**',
         '!tests{,/**/*}',
+        '!examples{,/**/*}',
         '!pr-evidence{,/**/*}',
         '!Casks{,/**/*}',
-        '!{AGENTS.md,CLAUDE.md,DEVELOPING.md,bundle-size-progress.md}',
+        '!{AGENTS.md,CLAUDE.md,DEVELOPING.md,bundle-size-progress.md,ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md,ORCHESTRATION_STRUCTURED_OUTPUT_DESIGN.md}',
         '!out/**/*.test.js',
         '!resources/plugins/launch/**'
       ])
     )
   })
 
+  // Why: `files` is an all-negation list, so electron-builder's default `**/*` packs
+  // anything without an explicit `!` entry — examples/ landed without one and shipped
+  // hostile-panel, the adversarial containment fixture, into 1.4.160-rc.3's app.asar.
+  // Drive the real matcher: pinning the pattern string cannot prove it excludes the tree.
+  it('keeps plugin authoring examples out of app.asar', () => {
+    const matcher = new FileMatcher('/app', '/dest', (value) => value, electronBuilderConfig.files)
+    // copyFiles() prepends this itself once the pattern list is all-negation.
+    matcher.prependPattern('**/*')
+    const isPacked = matcher.createFilter()
+    const packs = (repoPath) => isPacked(join('/app', repoPath), { isDirectory: () => false })
+
+    for (const authoringOnly of [
+      'examples/plugins/hostile-panel/panel.html',
+      'examples/plugins/hostile-panel/orca-plugin.json',
+      'examples/plugins/hello-orca/main.mjs',
+      'examples/plugins/hello-orca/orca-plugin.json'
+    ]) {
+      expect(packs(authoringOnly)).toBe(false)
+    }
+    // The negation stays anchored at the app root, so nested `examples` segments still ship.
+    expect(packs('out/main/examples/index.js')).toBe(true)
+  })
+
   it('keeps runtime resources available through extraResources', () => {
     const bundledPluginResources = expect.objectContaining({
       from: 'resources/plugins/launch',
@@ -141,6 +166,12 @@ describe('electron-builder config', () => {
     )
   })
 
+  it('keeps the worker-thread hang watchdog inside app.asar', () => {
+    expect(electronBuilderConfig.asarUnpack).not.toContain(
+      'out/main/main-thread-hang-watchdog-entry.js'
+    )
+  })
+
   it('uses the multi-size icon source for Linux packages', () => {
     expect(electronBuilderConfig.linux.icon).toBe('resources/build/icon.icns')
   })

config/scripts/electron-vite-output-contract.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest'
 import { electronViteConfig } from '../../electron.vite.config'
 
 const targetConfig = readFileSync('config/electron-vite-target.config.ts', 'utf8')
+const devRunner = readFileSync('config/scripts/run-electron-vite-dev.mjs', 'utf8')
 
 describe('Electron Vite output contract', () => {
   it('keeps main-process and plain-Node entries at stable CommonJS paths', () => {
@@ -39,4 +40,12 @@ describe('Electron Vite output contract', () => {
   it('rejects prototype properties as build targets', () => {
     expect(targetConfig).toContain('Object.prototype.hasOwnProperty.call(configByTarget, target)')
   })
+
+  it('gives the dev terminal daemon helper the TCC identity watched by Orca', () => {
+    expect(devRunner).toContain('const helperBundleId = `${bundleId}.helper`')
+    expect(devRunner).toContain("'Electron Helper.app',")
+    expect(devRunner).toContain(
+      "setPlistValue(helperPlistPath, 'CFBundleIdentifier', helperBundleId)"
+    )
+  })
 })

config/scripts/locale-key-override-merge.mjs

@@ -1,5 +1,6 @@
 import { CROSS_LOCALE_KEY_OVERRIDES } from './locale-cross-locale-key-overrides.mjs'
 import { KO_KEY_OVERRIDES } from './locale-ko-key-overrides.mjs'
+import { MACOS_TCC_KEY_OVERRIDES } from './locale-macos-tcc-key-overrides.mjs'
 
 export function mergeLocaleKeyOverrides(base) {
   const merged = { ...base }
@@ -10,5 +11,8 @@ export function mergeLocaleKeyOverrides(base) {
     // KO split overrides can share keys with zh/ja repairs; merge per locale.
     merged[key] = { ...merged[key], ...overrides }
   }
+  for (const [key, overrides] of Object.entries(MACOS_TCC_KEY_OVERRIDES)) {
+    merged[key] = { ...merged[key], ...overrides }
+  }
   return merged
 }

config/scripts/locale-ko-key-overrides.json

@@ -2231,9 +2231,6 @@
   "auto.components.settings.DeveloperPermissionsPane.16381e040a": {
     "ko": "마이크"
   },
-  "auto.components.settings.DeveloperPermissionsPane.7ca17b62c8": {
-    "ko": "프로젝트, 워크트리 또는 심볼릭 링크된 파일이 macOS 보호 폴더에 닿을 때 권장됩니다."
-  },
   "auto.components.settings.DeveloperPermissionsPane.e119f0d66b": {
     "ko": "자동화"
   },

config/scripts/locale-macos-tcc-key-overrides.mjs

@@ -0,0 +1,18 @@
+export const MACOS_TCC_KEY_OVERRIDES = {
+  'auto.hooks.useMacosTccPromptNotice.description': {
+    es: 'macOS atribuye a Orca el acceso a archivos realizado por tus agentes y herramientas de terminal. Conceder acceso total al disco reduce estos avisos.',
+    ja: 'エージェントやターミナルツールがファイルにアクセスすると、macOS はそのアクセス元を Orca として扱います。フルディスクアクセスを許可すると、これらの確認を減らせます。',
+    ko: '에이전트와 터미널 도구의 파일 접근은 macOS에서 Orca의 접근으로 표시됩니다. 전체 디스크 접근 권한을 허용하면 이러한 요청을 줄일 수 있습니다.',
+    zh: 'macOS 会将代理和终端工具的文件访问归因于 Orca。授予“完全磁盘访问权限”可减少此类提示。'
+  },
+  'auto.components.settings.DeveloperPermissionsPane.7ca17b62c8': {
+    es: 'Cuando los agentes que ejecuta Orca leen datos de otras apps, macOS muestra el nombre de Orca porque es el proceso responsable de los comandos de terminal. Concede este permiso a Orca y Orca Helper para reducir esos avisos. Después, cierra Orca, finaliza cualquier proceso de Orca Helper que siga en ejecución y vuelve a abrir Orca.',
+    ja: 'Orca が実行するエージェントがほかのアプリのデータを読み取ると、ターミナルコマンドの実行元プロセスである Orca の名前が macOS に表示されます。これらの確認を減らすには、Orca と Orca Helper にこの権限を許可してください。その後、Orca を終了し、残っている Orca Helper プロセスもすべて終了してから、Orca を再度開いてください。',
+    ko: 'Orca가 실행하는 에이전트가 다른 앱의 데이터를 읽으면, macOS는 터미널 명령을 실행하는 프로세스인 Orca를 표시합니다. 이러한 요청을 줄이려면 Orca와 Orca Helper에 이 권한을 허용하세요. 그런 다음 Orca를 종료하고, 남아 있는 Orca Helper 프로세스도 모두 종료한 후 Orca를 다시 여세요.',
+    zh: '当 Orca 运行的代理读取其他应用的数据时，macOS 会显示 Orca，因为 Orca 是执行终端命令的进程。请为 Orca 和 Orca Helper 授予此权限，以减少此类提示。然后退出 Orca，结束所有仍在运行的 Orca Helper 进程，再重新打开 Orca。'
+  },
+  'auto.components.settings.DeveloperPermissionsPane.c566bca278': {
+    ko: '전체 디스크 접근 권한',
+    zh: '完全磁盘访问权限'
+  }
+}

config/scripts/locale-prose-term-exemptions.mjs

@@ -0,0 +1,19 @@
+const LOCALIZED_PROSE_TERM_KEYS = new Set([
+  'auto.hooks.useMacosTccPromptNotice.description',
+  'auto.components.settings.DeveloperPermissionsPane.7ca17b62c8'
+])
+
+const LOCALIZABLE_PROSE_TERMS = new Set([
+  'Agent',
+  'Agents',
+  'agent',
+  'agents',
+  'Terminal',
+  'Terminals',
+  'terminal',
+  'terminals'
+])
+
+export function isLocalizedProseTermContext(term, key) {
+  return LOCALIZED_PROSE_TERM_KEYS.has(key) && LOCALIZABLE_PROSE_TERMS.has(term)
+}

config/scripts/locale-translation-policy.mjs

@@ -1,4 +1,5 @@
 import { CJK_LATIN_SPACED_TERMS } from './locale-cjk-latin-spaced-terms.mjs'
+import { isLocalizedProseTermContext } from './locale-prose-term-exemptions.mjs'
 import { isScreenCursorContext } from './locale-screen-cursor-exemptions.mjs'
 import { LOCALE_KEY_OVERRIDES } from './locale-key-overrides.mjs'
 import { LOCALE_PHRASE_FIXES } from './locale-phrase-fixes.mjs'
@@ -382,6 +383,9 @@ function applyBrandMistranslationFixes(enValue, localeValue, locale, key = '') {
     if (isScreenCursorContext(brand, enValue, key)) {
       continue
     }
+    if (isLocalizedProseTermContext(brand, key)) {
+      continue
+    }
     if (includesPreservedLatinTerm(result, brand)) {
       continue
     }

config/scripts/localization-package-contract.test.mjs

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+
+import { describe, expect, it } from 'vitest'
+
+describe('localization package scripts', () => {
+  const scripts = JSON.parse(readFileSync('package.json', 'utf8')).scripts
+
+  it('keeps safe catalog and extraction verification available', () => {
+    expect(scripts['verify:localization-catalog']).toBeDefined()
+    expect(scripts['sync:localization-catalog']).toBeDefined()
+    expect(scripts['verify:localization-extraction']).toBeDefined()
+  })
+
+  it('does not expose whole-catalog translation and repair commands', () => {
+    expect(scripts['bootstrap:locale-catalog']).toBeUndefined()
+    expect(scripts['bootstrap:zh-catalog']).toBeUndefined()
+    expect(scripts['bootstrap:ko-catalog']).toBeUndefined()
+    expect(scripts['bootstrap:ja-catalog']).toBeUndefined()
+    expect(scripts['bootstrap:es-catalog']).toBeUndefined()
+    expect(scripts['repair:locale-catalog']).toBeUndefined()
+  })
+})

config/scripts/macos-tcc-prompt-localization.test.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs'
+
+import { describe, expect, it } from 'vitest'
+import { repairTranslatedValue } from './locale-translation-policy.mjs'
+
+const LOCALES = ['es', 'ja', 'ko', 'zh']
+const KEYS = [
+  'auto.hooks.useMacosTccPromptNotice.title',
+  'auto.hooks.useMacosTccPromptNotice.description',
+  'auto.hooks.useMacosTccPromptNotice.openSettings',
+  'auto.hooks.useMacosTccPromptNotice.dismiss',
+  'auto.components.settings.DeveloperPermissionsPane.7ca17b62c8',
+  'auto.components.settings.DeveloperPermissionsPane.c566bca278'
+]
+
+function readCatalog(locale) {
+  return JSON.parse(
+    fs.readFileSync(
+      new URL(`../../src/renderer/src/i18n/locales/${locale}.json`, import.meta.url),
+      'utf8'
+    )
+  )
+}
+
+function getValue(catalog, key) {
+  return key.split('.').reduce((value, part) => value[part], catalog)
+}
+
+describe('macOS TCC prompt localization', () => {
+  it('survives the canonical catalog repair policy', () => {
+    const english = readCatalog('en')
+    for (const locale of LOCALES) {
+      const catalog = readCatalog(locale)
+      for (const key of KEYS) {
+        const enValue = getValue(english, key)
+        const localeValue = getValue(catalog, key)
+        expect(repairTranslatedValue({ key, enValue, localeValue, locale })).toBe(localeValue)
+      }
+    }
+  })
+
+  it('uses the macOS Full Disk Access labels in Korean and Chinese', () => {
+    expect(
+      getValue(readCatalog('ko'), 'auto.components.settings.DeveloperPermissionsPane.c566bca278')
+    ).toBe('전체 디스크 접근 권한')
+    expect(
+      getValue(readCatalog('zh'), 'auto.components.settings.DeveloperPermissionsPane.c566bca278')
+    ).toBe('完全磁盘访问权限')
+  })
+})

config/scripts/orchestration-skill-guidance.test.mjs

@@ -51,30 +51,39 @@ describe('orchestration skill guidance', () => {
     )
   })
 
-  it('teaches the hard cutover without reviving a legacy executor', () => {
+  it('teaches attested adoption without reviving the retired scheduler', () => {
     const skill = readSkill()
     const migration = getSection(skill, 'Contract Migration')
 
-    expect(migration).toContain('hard cutover')
-    expect(migration).toContain('effectsApplied')
-    expect(migration).toContain('skills get orchestration --full')
-    expect(migration).toContain('Do not retry the rejected command unchanged')
-    expect(migration).toContain('no longer supervised')
-    expect(migration).toContain('task-list --run run_legacy_local')
-    expect(migration).toContain('Read-only inspection never consumes legacy mail')
-    expect(migration).toContain('does not run a legacy scheduler, translate old writes, or drain')
-    expect(migration).toContain('does not cancel the prior assignment')
-    expect(migration).toContain('invalidate its worktree')
-    expect(migration).toContain('discard filesystem changes')
-    expect(migration).toContain('leave it as the only editor in that worktree')
-    expect(migration).toContain('observe it manually, read-only')
-    expect(migration).toContain('until it reaches a stable handoff point')
-    expect(migration).toContain('visible activity is a reason to keep observing')
     expect(migration).toContain(
-      'Never launch a replacement editor in the same worktree while the legacy worker may still write there.'
+      'adopts a live pre-update orchestration assignment into an ordinary Run'
     )
-    expect(migration).toContain('if remaining work needs new lifecycle supervision')
-    expect(migration).not.toContain('restart the work using Run -> Task -> `worker-start`')
+    expect(migration).toContain(
+      'preserves the existing agent process, PTY/session, terminal handle, tab/leaf/pane, worktree or folder workspace, Task, and Dispatch'
+    )
+    expect(migration).toContain('never restarts or replaces the worker')
+    expect(migration).toContain('The retired scheduler is not revived')
+    expect(migration).toContain('[LEGACY COMPATIBILITY]')
+    expect(migration).toContain('[LEGACY READ-ONLY]')
+    expect(migration).toContain(
+      'Loss of lifecycle authority does not invalidate the existing assignment, process, or filesystem work.'
+    )
+    expect(migration).toContain(
+      'It must not spawn, write, signal, stop, switch, focus, split, or inject a terminal.'
+    )
+    expect(migration).not.toContain('task-list --run run_legacy_local')
+    expect(migration).toContain('run_legacy_local is an empty audit tombstone')
+    expect(migration).toContain('Recovered orchestration work from a contract update')
+    expect(migration).toContain('run-show --id <adopted_run_id>')
+    expect(migration).toContain('task-list --run <adopted_run_id>')
+    expect(migration).toContain('Legacy inspection remains available without consuming mail')
+    expect(migration).toContain('run-use --id <adopted_run_id> --takeover-legacy')
+    expect(migration).toContain('Takeover fences only the old coordinator')
+    expect(migration).toContain('Live legacy workers keep their original Tasks, Dispatches')
+    expect(migration).toContain(
+      'keep the original worker as the only editor until it reaches a stable handoff point'
+    )
+    expect(migration).toContain('a conflict-free placement for any remaining work')
   })
 
   it('treats long-running worker waits as liveness checkpoints, not failures', () => {

config/scripts/pr-workflow-parallelism.test.mjs

@@ -37,13 +37,19 @@ describe('PR workflow parallelism', () => {
     expect(workflow.permissions).toEqual({ contents: 'read' })
   })
 
-  it('shards the general test suite across sixteen runners', () => {
+  it('shards the general test suite across Node 24 and Node 26', () => {
+    expect(workflow.jobs.test.strategy.matrix.node).toEqual(['24', '26'])
     expect(workflow.jobs.test.strategy.matrix.shard).toEqual(
       Array.from({ length: 16 }, (_, index) => index + 1)
     )
+    expect(workflow.jobs.test.strategy.matrix.shard_total).toEqual([16])
     const testStep = workflow.jobs.test.steps.find((step) => step.name === 'Test shard')
+    const installStep = workflow.jobs.test.steps.find(
+      (step) => step.uses === './.github/actions/install-node-dependencies'
+    )
 
-    expect(testStep.run).toContain('--shard=${{ matrix.shard }}/${{ strategy.job-total }}')
+    expect(installStep.with['node-version']).toBe('${{ matrix.node }}')
+    expect(testStep.run).toContain('--shard=${{ matrix.shard }}/${{ matrix.shard_total }}')
     for (const testFile of nativeShellContractFiles) {
       expect(testStep.run).toContain(`--exclude=${testFile}`)
     }
@@ -95,9 +101,15 @@ describe('PR workflow parallelism', () => {
     const steps = dependencyAction.runs.steps
     const pnpmIndex = steps.findIndex((step) => step.name === 'Setup pnpm')
     const nodeIndex = steps.findIndex((step) => step.name === 'Setup Node.js')
+    const requestedNodeIndex = steps.findIndex((step) => step.name === 'Setup requested Node.js')
 
     expect(pnpmIndex).toBeLessThan(nodeIndex)
+    expect(pnpmIndex).toBeLessThan(requestedNodeIndex)
     expect(steps[nodeIndex].with.cache).toBe('pnpm')
+    expect(steps[nodeIndex].if).toBe("inputs.node-version == ''")
+    expect(steps[requestedNodeIndex].if).toBe("inputs.node-version != ''")
+    expect(steps[requestedNodeIndex].with['node-version']).toBe('${{ inputs.node-version }}')
+    expect(steps[requestedNodeIndex].with.cache).toBe('pnpm')
   })
 
   it('restores Electron downloads before preparing the package runtime', () => {

config/scripts/run-electron-vite-dev.mjs

@@ -128,10 +128,8 @@ function prepareMacDevElectronApp() {
 
   const title = process.env.ORCA_DEV_DOCK_TITLE || 'Orca: dev'
   const identityKey = process.env.ORCA_DEV_INSTANCE_KEY || repoRoot
-  // v6: bundle the notification-status helper (real permission readout) and
-  // ad-hoc re-sign after plist edits so Notification Center accepts the
-  // bundle; bumping forces stale cached copies to be recreated.
-  const bundleLayoutVersion = 'dock-title-app-preserve-framework-symlinks-v6'
+  // v7: give the terminal daemon helper an Orca-specific TCC identity.
+  const bundleLayoutVersion = 'dock-title-app-preserve-framework-symlinks-v7'
   const hash = createHash('sha1')
     .update(
       `${sourceAppPath}\0${electronVersion ?? ''}\0${title}\0${identityKey}\0${bundleLayoutVersion}`
@@ -155,6 +153,7 @@ function prepareMacDevElectronApp() {
   // Electron drops clicks for notification ids it didn't create, so the
   // click is lost, not misdirected.
   const bundleId = 'com.stablyai.orca.dev'
+  const helperBundleId = `${bundleId}.helper`
   process.env.ORCA_DEV_MACOS_BUNDLE_ID = bundleId
   const expectedMarker = JSON.stringify(
     { title, appBundleName, bundleId, sourceAppPath, electronVersion, bundleLayoutVersion },
@@ -205,9 +204,18 @@ function prepareMacDevElectronApp() {
   restoreElectronFrameworkSymlinks(appPath)
 
   const plistPath = path.join(appPath, 'Contents', 'Info.plist')
+  const helperPlistPath = path.join(
+    appPath,
+    'Contents',
+    'Frameworks',
+    'Electron Helper.app',
+    'Contents',
+    'Info.plist'
+  )
   setPlistValue(plistPath, 'CFBundleName', title)
   setPlistValue(plistPath, 'CFBundleDisplayName', title)
   setPlistValue(plistPath, 'CFBundleIdentifier', bundleId)
+  setPlistValue(helperPlistPath, 'CFBundleIdentifier', helperBundleId)
 
   // Why: the notification-status helper reads the app's real macOS
   // notification authorization (UNUserNotificationCenter has no Electron

config/scripts/run-ssh-docker-terminal-parking-e2e.mjs

@@ -0,0 +1,45 @@
+import { spawnSync } from 'node:child_process'
+
+const rawExtraArgs = process.argv.slice(2)
+const extraArgs = rawExtraArgs[0] === '--' ? rawExtraArgs.slice(1) : rawExtraArgs
+const pnpm = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
+const env = {
+  ...process.env,
+  ORCA_E2E_SSH_DOCKER: '1'
+}
+
+// Why: Node's CVE-2024-27980 hardening rejects .cmd spawns without shell on Windows.
+const spawnOptions = {
+  stdio: 'inherit',
+  env,
+  shell: process.platform === 'win32'
+}
+
+const runtime = spawnSync(pnpm, ['run', 'ensure:electron-runtime'], spawnOptions)
+
+if (runtime.status !== 0) {
+  process.exit(runtime.status ?? 1)
+}
+
+// Why both specs in one runner: they share the docker SSH rig and the same
+// ORCA_E2E_SSH_DOCKER gate — the SSH parking spec proves SSH panes park and
+// restore, the retention spec proves the C1 budget bounds what they retain.
+const result = spawnSync(
+  pnpm,
+  [
+    'exec',
+    'playwright',
+    'test',
+    'tests/e2e/ssh-terminal-parking.spec.ts',
+    'tests/e2e/terminal-retention-budget.spec.ts',
+    '--config',
+    'tests/playwright.config.ts',
+    '--project',
+    'electron-headless',
+    '--workers=1',
+    ...extraArgs
+  ],
+  spawnOptions
+)
+
+process.exit(result.status ?? 1)

config/scripts/run-terminal-ibus-hangul-e2e.mjs

@@ -0,0 +1,306 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { closeSync, copyFileSync, mkdirSync, mkdtempSync, openSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const projectDir = path.resolve(import.meta.dirname, '../..')
+const scriptPath = import.meta.filename
+const insideSessionFlag = '--inside-session'
+const processStopTimeoutMs = 5_000
+const processKillTimeoutMs = 1_000
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+function waitForExit(child) {
+  return new Promise((resolve, reject) => {
+    child.once('error', reject)
+    child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)))
+  })
+}
+
+function processGroupMembers(processGroupId) {
+  const result = spawnSync('ps', ['-o', 'pid=,ppid=,pgid=,comm=', '-g', String(processGroupId)], {
+    encoding: 'utf8'
+  })
+  if (result.status !== 0) {
+    return []
+  }
+  return result.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+}
+
+async function stopOwnedProcessGroup(processGroupId) {
+  let members = processGroupMembers(processGroupId)
+  if (members.length === 0) {
+    return []
+  }
+  console.error(
+    `[terminal-ime] stopping owned process group ${processGroupId}: ${members.join('; ')}`
+  )
+  try {
+    process.kill(-processGroupId, 'SIGTERM')
+  } catch (error) {
+    if (error?.code !== 'ESRCH') {
+      throw error
+    }
+  }
+
+  const deadline = Date.now() + processStopTimeoutMs
+  while (Date.now() < deadline) {
+    members = processGroupMembers(processGroupId)
+    if (members.length === 0) {
+      return []
+    }
+    await delay(100)
+  }
+
+  try {
+    process.kill(-processGroupId, 'SIGKILL')
+  } catch (error) {
+    if (error?.code !== 'ESRCH') {
+      throw error
+    }
+  }
+  const killDeadline = Date.now() + processKillTimeoutMs
+  do {
+    members = processGroupMembers(processGroupId)
+    if (members.length === 0) {
+      return []
+    }
+    await delay(100)
+  } while (Date.now() < killDeadline)
+  return members
+}
+
+function commandOutput(command, args) {
+  const result = spawnSync(command, args, { encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : result.stderr.trim()
+}
+
+function configureHangulEngine() {
+  for (const [key, value] of [
+    ['initial-input-mode', 'hangul'],
+    ['hangul-keyboard', '2']
+  ]) {
+    const result = spawnSync(
+      'gsettings',
+      ['set', 'org.freedesktop.ibus.engine.hangul', key, value],
+      { encoding: 'utf8' }
+    )
+    if (result.status !== 0) {
+      throw new Error(`Failed to configure IBus Hangul ${key}: ${result.stderr.trim()}`)
+    }
+  }
+}
+
+async function waitForHangulEngine(ibusProcess) {
+  const deadline = Date.now() + 15_000
+  while (Date.now() < deadline) {
+    if (ibusProcess.exitCode !== null) {
+      throw new Error(`ibus-daemon exited early with code ${ibusProcess.exitCode}`)
+    }
+    const result = spawnSync('ibus', ['engine', 'hangul'], { stdio: 'pipe' })
+    if (result.status === 0) {
+      return
+    }
+    await delay(100)
+  }
+  throw new Error('Timed out while selecting the IBus Hangul engine')
+}
+
+async function runInsideSession(evidenceDir) {
+  const ibusLogPath = path.join(evidenceDir, 'ibus-daemon.log')
+  const ibusLogFd = openSync(ibusLogPath, 'w')
+  const windowManagerLogPath = path.join(evidenceDir, 'xfwm4.log')
+  const windowManagerLogFd = openSync(windowManagerLogPath, 'w')
+  const evidence = {
+    display: process.env.DISPLAY ?? null,
+    ibusDaemonPid: null,
+    ibusGroupBeforeCleanup: [],
+    ibusGroupAfterCleanup: [],
+    playwrightPid: null,
+    windowManagerPid: null,
+    windowManagerGroupAfterCleanup: []
+  }
+  let ibusProcess
+  let windowManagerProcess
+  let testExitCode = 1
+
+  try {
+    configureHangulEngine()
+    windowManagerProcess = spawn('xfwm4', ['--compositor=off'], {
+      detached: true,
+      env: process.env,
+      stdio: ['ignore', windowManagerLogFd, windowManagerLogFd]
+    })
+    if (!windowManagerProcess.pid) {
+      throw new Error('xfwm4 did not return a PID')
+    }
+    evidence.windowManagerPid = windowManagerProcess.pid
+    console.error(`[terminal-ime] started xfwm4 PID ${windowManagerProcess.pid}`)
+
+    ibusProcess = spawn(
+      'ibus-daemon',
+      ['--xim', '--verbose', '--panel=disable', '--emoji-extension=disable'],
+      {
+        detached: true,
+        env: process.env,
+        stdio: ['ignore', ibusLogFd, ibusLogFd]
+      }
+    )
+    if (!ibusProcess.pid) {
+      throw new Error('ibus-daemon did not return a PID')
+    }
+    evidence.ibusDaemonPid = ibusProcess.pid
+    console.error(`[terminal-ime] started ibus-daemon PID ${ibusProcess.pid}`)
+    await waitForHangulEngine(ibusProcess)
+    console.error(`[terminal-ime] IBus version: ${commandOutput('ibus', ['version'])}`)
+    console.error(`[terminal-ime] IBus engine: ${commandOutput('ibus', ['engine'])}`)
+    console.error(
+      `[terminal-ime] Hangul initial mode: ${commandOutput('gsettings', [
+        'get',
+        'org.freedesktop.ibus.engine.hangul',
+        'initial-input-mode'
+      ])}`
+    )
+    console.error(
+      `[terminal-ime] Hangul keyboard: ${commandOutput('gsettings', [
+        'get',
+        'org.freedesktop.ibus.engine.hangul',
+        'hangul-keyboard'
+      ])}`
+    )
+    evidence.ibusGroupBeforeCleanup = processGroupMembers(ibusProcess.pid)
+    console.error(`[terminal-ime] owned IBus group: ${evidence.ibusGroupBeforeCleanup.join('; ')}`)
+
+    const testProcess = spawn(
+      process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm',
+      [
+        'run',
+        'test:e2e:headful',
+        '--workers=1',
+        '--',
+        'tests/e2e/terminal-ibus-hangul-native.spec.ts'
+      ],
+      {
+        cwd: projectDir,
+        env: {
+          ...process.env,
+          ORCA_E2E_FORWARD_APP_LOGS: '1',
+          ORCA_E2E_NATIVE_IBUS_HANGUL: '1'
+        },
+        stdio: 'inherit'
+      }
+    )
+    if (!testProcess.pid) {
+      throw new Error('Playwright did not return a PID')
+    }
+    evidence.playwrightPid = testProcess.pid
+    console.error(`[terminal-ime] started Playwright PID ${testProcess.pid}`)
+    testExitCode = await waitForExit(testProcess)
+  } finally {
+    if (ibusProcess?.pid) {
+      evidence.ibusGroupBeforeCleanup = processGroupMembers(ibusProcess.pid)
+      evidence.ibusGroupAfterCleanup = await stopOwnedProcessGroup(ibusProcess.pid)
+    }
+    if (windowManagerProcess?.pid) {
+      evidence.windowManagerGroupAfterCleanup = await stopOwnedProcessGroup(
+        windowManagerProcess.pid
+      )
+    }
+    closeSync(ibusLogFd)
+    closeSync(windowManagerLogFd)
+    mkdirSync(path.join(projectDir, 'test-results'), { recursive: true })
+    copyFileSync(
+      ibusLogPath,
+      path.join(projectDir, 'test-results', 'terminal-ibus-hangul-native-ibus.log')
+    )
+    copyFileSync(
+      windowManagerLogPath,
+      path.join(projectDir, 'test-results', 'terminal-ibus-hangul-native-xfwm4.log')
+    )
+    writeFileSync(
+      path.join(projectDir, 'test-results', 'terminal-ibus-hangul-native-processes.json'),
+      `${JSON.stringify(evidence, null, 2)}\n`
+    )
+  }
+
+  if (evidence.ibusGroupAfterCleanup.length > 0) {
+    throw new Error(
+      `Owned IBus processes survived cleanup: ${evidence.ibusGroupAfterCleanup.join('; ')}`
+    )
+  }
+  if (evidence.windowManagerGroupAfterCleanup.length > 0) {
+    throw new Error(
+      `Owned window-manager processes survived cleanup: ${evidence.windowManagerGroupAfterCleanup.join('; ')}`
+    )
+  }
+  return testExitCode
+}
+
+async function runOuter() {
+  if (process.platform !== 'linux') {
+    throw new Error('The native IBus Hangul E2E runner requires Linux/X11')
+  }
+
+  const evidenceDir = mkdtempSync(path.join(os.tmpdir(), 'orca-terminal-ime-e2e-'))
+  const runtimeDir = path.join(evidenceDir, 'runtime')
+  mkdirSync(runtimeDir, { mode: 0o700 })
+  mkdirSync(path.join(evidenceDir, 'config'))
+  mkdirSync(path.join(evidenceDir, 'cache'))
+  console.error(`[terminal-ime] evidence directory: ${evidenceDir}`)
+
+  const sessionProcess = spawn(
+    'xvfb-run',
+    [
+      '--auto-servernum',
+      'dbus-run-session',
+      '--',
+      process.execPath,
+      scriptPath,
+      insideSessionFlag,
+      evidenceDir
+    ],
+    {
+      cwd: projectDir,
+      detached: true,
+      env: {
+        ...process.env,
+        GTK_IM_MODULE: 'ibus',
+        IBUS_ENABLE_SYNC_MODE: '1',
+        LANG: process.env.LANG || 'C.UTF-8',
+        QT_IM_MODULE: 'ibus',
+        XDG_CACHE_HOME: path.join(evidenceDir, 'cache'),
+        XDG_CONFIG_HOME: path.join(evidenceDir, 'config'),
+        XDG_RUNTIME_DIR: runtimeDir,
+        XMODIFIERS: '@im=ibus'
+      },
+      stdio: 'inherit'
+    }
+  )
+  if (!sessionProcess.pid) {
+    throw new Error('xvfb-run did not return a PID')
+  }
+  console.error(`[terminal-ime] started isolated X11 session PID ${sessionProcess.pid}`)
+  const exitCode = await waitForExit(sessionProcess)
+  const remaining = await stopOwnedProcessGroup(sessionProcess.pid)
+  if (remaining.length > 0) {
+    throw new Error(`Owned X11 session processes survived cleanup: ${remaining.join('; ')}`)
+  }
+  return exitCode
+}
+
+const insideSession = process.argv[2] === insideSessionFlag
+try {
+  if (insideSession && !process.argv[3]) {
+    throw new Error(`${insideSessionFlag} requires an evidence directory argument`)
+  }
+  process.exitCode = insideSession ? await runInsideSession(process.argv[3]) : await runOuter()
+} catch (error) {
+  console.error(`[terminal-ime] ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}

config/scripts/terminal-ime-e2e-workflow.test.mjs

@@ -0,0 +1,93 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { parse } from 'yaml'
+
+const projectDir = resolve(import.meta.dirname, '../..')
+
+describe('terminal IME e2e workflow', () => {
+  const workflow = parse(
+    readFileSync(join(projectDir, '.github/workflows/terminal-ime-e2e.yml'), 'utf8')
+  )
+
+  it('runs for xterm patch and terminal IME regression changes', () => {
+    expect(workflow.on.pull_request.paths).toEqual(
+      expect.arrayContaining([
+        'config/patches/@xterm__xterm@6.1.0-beta.287.patch',
+        'config/scripts/run-terminal-ibus-hangul-e2e.mjs',
+        'src/renderer/src/components/terminal-pane/keyboard-handlers.ts',
+        'src/renderer/src/components/terminal-pane/keyboard-handlers-ime.test.tsx',
+        'src/renderer/src/components/terminal-pane/pty-connection.ts',
+        'src/renderer/src/components/terminal-pane/pty-connection.test.ts',
+        'src/renderer/src/components/terminal-pane/terminal-ime-*',
+        'src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts',
+        'src/renderer/src/components/terminal-pane/xterm-bypass-policy.ts',
+        'src/renderer/src/components/terminal-pane/xterm-bypass-policy.test.ts',
+        'tests/e2e/korean-ime-terminal-shift-enter-commit.spec.ts',
+        'tests/e2e/terminal-ibus-hangul-native.spec.ts',
+        'tests/e2e/terminal-ime-*.ts'
+      ])
+    )
+  })
+
+  it('installs native IBus Hangul and X11 input tools', () => {
+    const runs = workflow.jobs['linux-x11'].steps
+      .map((step) => step.run)
+      .filter((run) => typeof run === 'string')
+    const installRun = runs.find((run) => run.includes('apt-get install'))
+
+    expect(installRun).toBeDefined()
+    expect(installRun).toContain('ibus-hangul')
+    expect(installRun).toContain('xdotool')
+    expect(installRun).toContain('xfwm4')
+    expect(installRun).toContain('xvfb')
+    expect(installRun).toContain('dbus-x11')
+    expect(installRun).toContain('dconf-gsettings-backend')
+    expect(installRun).toContain('libglib2.0-bin')
+  })
+
+  it('runs deterministic boundaries before the real IBus suite', () => {
+    const runs = workflow.jobs['linux-x11'].steps
+      .map((step) => step.run)
+      .filter((run) => typeof run === 'string')
+    const deterministicIndex = runs.findIndex((run) =>
+      run.includes('terminal-ime-exact-byte.spec.ts')
+    )
+    const nativeIndex = runs.findIndex((run) => run.includes('test:e2e:terminal-ime-native'))
+
+    expect(deterministicIndex).toBeGreaterThanOrEqual(0)
+    expect(nativeIndex).toBeGreaterThan(deterministicIndex)
+  })
+
+  it('keeps IBus lifecycle scoped to owned processes', () => {
+    const runner = readFileSync(
+      join(projectDir, 'config/scripts/run-terminal-ibus-hangul-e2e.mjs'),
+      'utf8'
+    )
+
+    expect(runner).toContain(
+      "['--xim', '--verbose', '--panel=disable', '--emoji-extension=disable']"
+    )
+    expect(runner).toContain("spawn('xfwm4', ['--compositor=off']")
+    expect(runner).toContain("['initial-input-mode', 'hangul']")
+    expect(runner).toContain("['hangul-keyboard', '2']")
+    expect(runner).toContain("process.kill(-processGroupId, 'SIGTERM')")
+    expect(runner).toContain("process.kill(-processGroupId, 'SIGKILL')")
+    expect(runner).toContain('const killDeadline = Date.now() + processKillTimeoutMs')
+    expect(runner).toMatch(
+      /'test:e2e:headful',\s*'--workers=1',\s*'--',\s*'tests\/e2e\/terminal-ibus-hangul-native\.spec\.ts'/
+    )
+    expect(runner).not.toContain("'--replace'")
+    expect(runner).not.toContain('killall')
+    expect(runner).not.toContain('pkill')
+  })
+
+  it('bounds blocking native input commands', () => {
+    const nativeSpec = readFileSync(
+      join(projectDir, 'tests/e2e/terminal-ibus-hangul-native.spec.ts'),
+      'utf8'
+    )
+
+    expect(nativeSpec.match(/timeout: NATIVE_COMMAND_TIMEOUT_MS/g)).toHaveLength(3)
+  })
+})

config/scripts/verify-localization-catalog.mjs

@@ -227,44 +227,6 @@ function setCatalogEntry(catalog, key, value) {
   cursor[parts.at(-1)] = value
 }
 
-function deleteCatalogEntry(catalog, key) {
-  const parts = key.split('.')
-  const stack = []
-  let cursor = catalog
-
-  for (const part of parts.slice(0, -1)) {
-    if (
-      typeof cursor?.[part] !== 'object' ||
-      cursor[part] === null ||
-      Array.isArray(cursor[part])
-    ) {
-      return false
-    }
-    stack.push([cursor, part])
-    cursor = cursor[part]
-  }
-
-  const leafKey = parts.at(-1)
-  if (!Object.hasOwn(cursor, leafKey)) {
-    return false
-  }
-
-  delete cursor[leafKey]
-  for (let index = stack.length - 1; index >= 0; index -= 1) {
-    const [parent, part] = stack[index]
-    const child = parent[part]
-    if (
-      typeof child === 'object' &&
-      child !== null &&
-      !Array.isArray(child) &&
-      Object.keys(child).length === 0
-    ) {
-      delete parent[part]
-    }
-  }
-  return true
-}
-
 function collectLocaleParityIssues(enCatalog, localeCatalog) {
   const enEntries = flattenCatalogEntries(enCatalog)
   const localeEntries = flattenCatalogEntries(localeCatalog)
@@ -286,30 +248,6 @@ function collectLocaleParityIssues(enCatalog, localeCatalog) {
   return { enEntries, localeEntries, missingInLocale, extraInLocale, interpolationMismatches }
 }
 
-function repairLocaleParity(enCatalog, localeCatalog) {
-  const { enEntries, missingInLocale, extraInLocale, interpolationMismatches } =
-    collectLocaleParityIssues(enCatalog, localeCatalog)
-  let changed = 0
-
-  for (const key of missingInLocale) {
-    setCatalogEntry(localeCatalog, key, enEntries.get(key))
-    changed += 1
-  }
-
-  for (const key of extraInLocale) {
-    if (deleteCatalogEntry(localeCatalog, key)) {
-      changed += 1
-    }
-  }
-
-  for (const key of interpolationMismatches) {
-    setCatalogEntry(localeCatalog, key, enEntries.get(key))
-    changed += 1
-  }
-
-  return changed
-}
-
 function referencesMissingFallbacks(missing) {
   return missing.filter((reference) => typeof reference.fallback !== 'string')
 }
@@ -344,23 +282,18 @@ function applyMissingEnglishEntries(catalog, missing) {
   return changed
 }
 
-function verifyLocaleParity(enCatalog, localeName, localeCatalog) {
-  const { localeEntries, missingInLocale, extraInLocale, interpolationMismatches } =
+function verifyLocaleCatalog(enCatalog, localeName, localeCatalog) {
+  const { enEntries, localeEntries, missingInLocale, extraInLocale, interpolationMismatches } =
     collectLocaleParityIssues(enCatalog, localeCatalog)
 
-  if (
-    missingInLocale.length > 0 ||
-    extraInLocale.length > 0 ||
-    interpolationMismatches.length > 0
-  ) {
-    console.error(`Locale catalog parity failed for ${localeName}.json.`)
-    if (missingInLocale.length > 0) {
-      console.error('')
-      console.error(formatMissingKeys('missing', missingInLocale.slice(0, 20)))
-      if (missingInLocale.length > 20) {
-        console.error(`...and ${missingInLocale.length - 20} more missing keys`)
-      }
-    }
+  // Why: feature PRs own English declarations; absent target leaves deliberately
+  // use i18next's existing English fallback until a localization PR supplies them.
+  console.log(
+    `${localeName}.json coverage: ${enEntries.size - missingInLocale.length}/${enEntries.size} translated, ${missingInLocale.length} missing.`
+  )
+
+  if (extraInLocale.length > 0 || interpolationMismatches.length > 0) {
+    console.error(`Locale catalog validation failed for ${localeName}.json.`)
     if (extraInLocale.length > 0) {
       console.error('')
       console.error(formatMissingKeys('extra', extraInLocale.slice(0, 20)))
@@ -380,7 +313,7 @@ function verifyLocaleParity(enCatalog, localeName, localeCatalog) {
     return 1
   }
 
-  console.log(`Verified locale parity for ${localeName}.json (${localeEntries.size} keys).`)
+  console.log(`Verified ${localeEntries.size} existing ${localeName}.json entries.`)
   return 0
 }
 
@@ -527,19 +460,10 @@ export async function main(root = process.cwd(), options = parseArgs(process.arg
     const localeName = fileName.replace(/\.json$/, '')
     const localeCatalogPath = path.join(localesDir, fileName)
     const localeCatalog = JSON.parse(await fs.readFile(localeCatalogPath, 'utf8'))
-    if (options.fix) {
-      const repaired = repairLocaleParity(catalog, localeCatalog)
-      if (repaired > 0) {
-        await fs.writeFile(localeCatalogPath, `${JSON.stringify(localeCatalog, null, 2)}\n`, 'utf8')
-        console.log(`Repaired ${fileName} parity (${repaired} key update(s)).`)
-      }
-    }
-    const exitCode = verifyLocaleParity(catalog, localeName, localeCatalog)
+    const exitCode = verifyLocaleCatalog(catalog, localeName, localeCatalog)
     if (exitCode !== 0) {
-      if (!options.fix) {
-        console.error('')
-        console.error('Run `pnpm run sync:localization-catalog` to repair locale parity.')
-      }
+      console.error('')
+      console.error('Fix or retire the existing target entry in a localization PR.')
       return exitCode
     }
   }

config/scripts/verify-localization-catalog.test.mjs

@@ -33,7 +33,7 @@ function makeProject({ sourceText, enCatalog = {}, esCatalog = {} }) {
 }
 
 describe('verify-localization-catalog', () => {
-  it('bootstraps missing catalog entries from string fallbacks', async () => {
+  it('bootstraps English entries without fabricating target translations', async () => {
     const { root, localesDir } = makeProject({
       sourceText:
         "import { translate } from '@/i18n/i18n'\nexport const label = translate('auto.example.greeting', 'Hello {{name}}', { name: 'Orca' })\n"
@@ -45,12 +45,10 @@ describe('verify-localization-catalog', () => {
     expect(readJson(path.join(localesDir, 'en.json'))).toEqual({
       auto: { example: { greeting: 'Hello {{name}}' } }
     })
-    expect(readJson(path.join(localesDir, 'es.json'))).toEqual({
-      auto: { example: { greeting: 'Hello {{name}}' } }
-    })
+    expect(readJson(path.join(localesDir, 'es.json'))).toEqual({})
   })
 
-  it('repairs stale locale keys and interpolation mismatches', async () => {
+  it('never overwrites mismatched translations or removes target-only entries', async () => {
     const { root, localesDir } = makeProject({
       sourceText:
         "import { translate } from '@/i18n/i18n'\nexport const label = translate('auto.example.greeting', 'Hello {{name}}', { name: 'Orca' })\n",
@@ -63,13 +61,29 @@ describe('verify-localization-catalog', () => {
       }
     })
 
-    await expect(verifyLocalizationCatalog(root, { fix: true })).resolves.toBe(0)
+    await expect(verifyLocalizationCatalog(root, { fix: true })).resolves.toBe(1)
 
     expect(readJson(path.join(localesDir, 'es.json'))).toEqual({
-      auto: { example: { greeting: 'Hello {{name}}' } }
+      auto: {
+        example: { greeting: 'Hola' },
+        stale: { removed: 'Viejo' }
+      }
     })
   })
 
+  it('accepts sparse target catalogs when existing placeholders match', async () => {
+    const { root } = makeProject({
+      sourceText:
+        "import { translate } from '@/i18n/i18n'\nexport const label = translate('auto.example.greeting', 'Hello {{name}}', { name: 'Orca' })\n",
+      enCatalog: {
+        auto: { example: { greeting: 'Hello {{name}}', untranslated: 'English only' } }
+      },
+      esCatalog: { auto: { example: { greeting: 'Hola {{name}}' } } }
+    })
+
+    await expect(verifyLocalizationCatalog(root, { fix: false })).resolves.toBe(0)
+  })
+
   it('does not invent values for keys without string fallbacks', async () => {
     const { root, localesDir } = makeProject({
       sourceText:

config/scripts/verify-localization-extraction.mjs

@@ -0,0 +1,123 @@
+import { execFile } from 'node:child_process'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+import { promisify } from 'node:util'
+import { pathToFileURL } from 'node:url'
+
+const execFileAsync = promisify(execFile)
+const EN_CATALOG_PATH = path.join('src', 'renderer', 'src', 'i18n', 'locales', 'en.json')
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/g
+
+function flattenCatalog(value, prefix = '', entries = new Map()) {
+  if (typeof value === 'string') {
+    entries.set(prefix, value)
+    return entries
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return entries
+  }
+  for (const [key, child] of Object.entries(value)) {
+    flattenCatalog(child, prefix ? `${prefix}.${key}` : key, entries)
+  }
+  return entries
+}
+
+function placeholders(value) {
+  return [...(value.match(PLACEHOLDER_RE) ?? [])].sort().join('|')
+}
+
+export function compareExtraction(extractedCatalog, englishCatalog) {
+  const extracted = flattenCatalog(extractedCatalog)
+  const english = flattenCatalog(englishCatalog)
+  const dynamicDefaults = [...extracted.entries()]
+    .filter(([, value]) => value.length === 0)
+    .map(([key]) => key)
+  const missingFromEnglish = [...extracted.keys()].filter((key) => !english.has(key))
+  const orphans = [...english.keys()].filter((key) => !extracted.has(key))
+  const fallbackDrift = []
+  const placeholderMismatches = []
+
+  for (const [key, extractedValue] of extracted) {
+    const englishValue = english.get(key)
+    if (
+      extractedValue.length === 0 ||
+      englishValue === undefined ||
+      englishValue === extractedValue
+    ) {
+      continue
+    }
+    fallbackDrift.push(key)
+    if (placeholders(extractedValue) !== placeholders(englishValue)) {
+      placeholderMismatches.push(key)
+    }
+  }
+
+  return {
+    extracted,
+    dynamicDefaults,
+    missingFromEnglish,
+    orphans,
+    fallbackDrift,
+    placeholderMismatches
+  }
+}
+
+function printKeys(label, keys) {
+  if (keys.length === 0) {
+    return
+  }
+  console.error(`${label}:`)
+  for (const key of keys.slice(0, 20)) {
+    console.error(`  ${key}`)
+  }
+  if (keys.length > 20) {
+    console.error(`  ...and ${keys.length - 20} more`)
+  }
+}
+
+async function extractToTemporaryCatalog(root, tempDir) {
+  const cliPath = path.join(root, 'node_modules', 'i18next-cli', 'dist', 'esm', 'cli.js')
+  const outputPattern = path.join(tempDir, '{{language}}.json')
+  // Why: extraction output is evidence for this check, not another committed
+  // catalog that feature authors must keep synchronized.
+  await execFileAsync(process.execPath, [cliPath, 'extract', '--sync-primary', '--quiet'], {
+    cwd: root,
+    env: {
+      ...process.env,
+      ORCA_I18N_EXTRACTION_OUTPUT: outputPattern.split(path.sep).join('/')
+    }
+  })
+  return JSON.parse(await fs.readFile(path.join(tempDir, 'en.json'), 'utf8'))
+}
+
+export async function main(root = process.cwd()) {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'orca-i18next-extraction-'))
+
+  try {
+    const [extractedCatalog, englishCatalog] = await Promise.all([
+      extractToTemporaryCatalog(root, tempDir),
+      fs.readFile(path.join(root, EN_CATALOG_PATH), 'utf8').then(JSON.parse)
+    ])
+    const result = compareExtraction(extractedCatalog, englishCatalog)
+
+    console.log(
+      `Extracted ${result.extracted.size} keys; ${result.dynamicDefaults.length} dynamic defaults are report-only, ${result.orphans.length} existing English entries are not statically referenced, and ${result.fallbackDrift.length} inline defaults differ.`
+    )
+
+    if (result.missingFromEnglish.length > 0 || result.placeholderMismatches.length > 0) {
+      printKeys('Extracted keys missing from en.json', result.missingFromEnglish)
+      printKeys('Extracted defaults with incompatible placeholders', result.placeholderMismatches)
+      return 1
+    }
+
+    return 0
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true })
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(await main())
+}

config/scripts/verify-localization-extraction.test.mjs

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+
+import { compareExtraction } from './verify-localization-extraction.mjs'
+
+describe('verify-localization-extraction', () => {
+  it('reports legacy drift without requiring a committed disposition database', () => {
+    const result = compareExtraction(
+      { menu: { open: 'Open now {{name}}' } },
+      { menu: { open: 'Open {{name}}', legacy: 'Legacy copy' } }
+    )
+
+    expect(result.orphans).toEqual(['menu.legacy'])
+    expect(result.fallbackDrift).toEqual(['menu.open'])
+    expect(result.placeholderMismatches).toEqual([])
+  })
+
+  it('reports dynamic defaults without treating empty extractor values as catalog copy', () => {
+    const result = compareExtraction(
+      { menu: { dynamic: '' } },
+      { menu: { dynamic: '{{count}} items' } }
+    )
+
+    expect(result.dynamicDefaults).toEqual(['menu.dynamic'])
+    expect(result.fallbackDrift).toEqual([])
+    expect(result.placeholderMismatches).toEqual([])
+  })
+
+  it('rejects undeclared keys even when their defaults are dynamic', () => {
+    const result = compareExtraction({ menu: { dynamic: '' } }, {})
+
+    expect(result.missingFromEnglish).toEqual(['menu.dynamic'])
+  })
+
+  it('rejects missing English declarations and incompatible placeholders', () => {
+    const result = compareExtraction(
+      {
+        menu: {
+          missing: 'Missing',
+          open: 'Open {{name}}'
+        }
+      },
+      { menu: { open: 'Open {{path}}' } }
+    )
+
+    expect(result.missingFromEnglish).toEqual(['menu.missing'])
+    expect(result.placeholderMismatches).toEqual(['menu.open'])
+  })
+})

config/tsconfig.node.json

@@ -4,6 +4,7 @@
     "../electron.vite.config.*",
     "../build-plugins/**/*",
     "../src/main/**/*",
+    "../src/renderer/src/lib/skill-freshness-display-status.ts",
     "../src/preload/**/*",
     "../src/shared/**/*",
     "../src/relay/**/*",

config/vitest.config.ts

@@ -15,6 +15,8 @@ export default defineConfig({
   },
   test: {
     environment: 'node',
+    // Why: Node 26's undefined Web Storage globals prevent Vitest from installing happy-dom's.
+    execArgv: ['--no-experimental-webstorage'],
     include: [
       'src/**/*.test.ts',
       'src/**/*.test.tsx',

docs/reference/plans/2026-07-27-sta-2694-alt-screen-reveal-artifacts-handoff.md

@@ -1,213 +0,0 @@
-# STA-2694 — garbled terminal after switching away from an AI workspace
-
-Handoff snapshot: 2026-07-27, branch
-`neil/sta-2694-fix-ui-rendering-artifacts-when-switching-away-from-ai`.
-
-## The report
-
-> When I use an AI tool—such as OpenCode—and switch away to the desktop or
-> another task, the page appears garbled or distorted upon returning; I have to
-> resize the window to restore the display.
-
-Reporter hints: related to terminal parking / workspace switching; also happens
-with Claude Code and probably grok.
-
-## Status
-
-**One defect, root-caused and fixed, with a mechanism-level test that fails
-without the fix.** The garble window is *unbounded*, not the ~1s I originally
-claimed — see [the correction](#correction-the-window-is-unbounded).
-
-A second hypothesis was implemented, then **refuted by measurement and
-reverted**. That refutation is the other half of the value here: it rules out a
-whole class of "just force a fuller repaint" fixes, and it is pinned by a test so
-it cannot be reintroduced.
-
-| | |
-|---|---|
-| Fix | `ed1eaf55f1` — release an abandoned synchronized-output frame on reveal |
-| Refuted + reverted | `0f7ec4458d`, reverted in `8d5eacecb4` |
-| Oracle + scope correction | `3ccffc17ec` |
-| Unit tests | 8 passing across 2 files |
-| e2e | 5 draw-command oracle + 10 headless convergence + 1 headful |
-| Teeth-verified | Yes — removing the fix fails the stranded-latch test |
-
-## The defect
-
-Alt-screen agent TUIs (OpenCode/OpenTUI, Codex, grok) bracket every repaint in
-DEC 2026 synchronized output — `\x1b[?2026h … \x1b[?2026l` — many times a second.
-Hide a pane mid-bracket (a worktree switch, a cold park, or an OS-level occlusion
-lands there routinely) and xterm keeps
-`decPrivateModes.synchronizedOutput` latched `true`.
-
-`RenderService.refreshRows` checks that latch **before** rendering
-(`RenderService.ts:162`), so while it holds, every repaint Orca owns is a no-op:
-the forced render-pause repaint, the plain `refresh()` fallback, and the shared
-glyph-atlas rebuild all render zero rows against a perfectly correct buffer.
-
-The fix (`terminal-synchronized-output-release.ts`) clears the latch and flushes
-the handler's buffered row range at both reveal repaint entry points, before the
-repaint. Both reveal paths reach it:
-
-- `schedulePaneRevealPresent` (plain refocus / desktop return)
-- `resetWebglTextureAtlas` (worktree switch, cold park, tab reveal — also reached
-  from `resetAndRefreshAllTerminalWebglAtlases` via the light tab-resume path)
-
-### Correction: the window is unbounded
-
-`ed1eaf55f1`'s commit message says this "closes a bounded window rather than the
-whole STA-2694 report", because xterm arms a 1s watchdog that clears the latch.
-**That was wrong.** The watchdog is armed only inside
-`SynchronizedOutputHandler.bufferRows`, and `refreshRows` returns at its
-`_isPaused` check *first*:
-
-```ts
-public refreshRows(start, end, sync = false, isRedrawOnly = false): void {
-  if (this._isPaused) { this._needsFullRefresh = true; return }   // ← occluded pane stops here
-  if (this._coreService.decPrivateModes.synchronizedOutput) {
-    this._syncOutputHandler.bufferRows(start, end)               // ← only place the watchdog arms
-    return
-  }
-  ...
-```
-
-While a pane is occluded its `IntersectionObserver` sets `_isPaused`, so nothing
-ever reaches `bufferRows` and **no timer is ever pending**. A pane hidden
-mid-frame holds the latch with no watchdog behind it, indefinitely — which is the
-indefinite garble the report describes. `terminal-reveal-draw-command-probe.spec.ts`
-asserts exactly this: latch set, `_timeout === undefined`, and a repaint drawing
-0 instances.
-
-This also explains the specific workaround: resizing the window makes the TUI
-repaint via SIGWINCH, and that repaint's closing `?2026l` clears the latch.
-
-## The refuted hypothesis (do not reimplement)
-
-The idea: xterm's renderers are diff-based, so a reveal `refresh()` skips cells
-whose model entry still matches the buffer, leaving an occluded canvas showing
-pre-hide pixels until a resize rebuilds the model. It is a *plausible* reading —
-`WebglRenderer._updateModel` really does early-continue per unchanged cell.
-
-It is wrong, measured on a live pane:
-
-| Refresh | `updateCell` calls | instances drawn |
-|---|---|---|
-| diff-skipped (model matches buffer) | 0 | 562 |
-| model cleared first | 561 | 562 |
-
-`GlyphRenderer.render` copies vertices for **every** row up to `lineLengths[y]`
-into the active buffer and issues **one** full-viewport `drawElementsInstanced`.
-The diff only decides how much *vertex data* is rewritten, never how much is
-*drawn*. The DOM renderer likewise `replaceChildren()`s every row
-unconditionally. So clearing the model cannot change what reaches the screen.
-
-Worse, it has a cost: `_clearModel(true)` zeroes every glyph vertex, and
-`RenderService.clear()` fires no repaint of its own — so any paint landing between
-the clear and the repopulating refresh draws an **empty** viewport (0 instances,
-also asserted in the spec). On a reveal that refresh is debounced through a RAF
-and can itself be swallowed, which would turn a merely-stale pane into a blank
-one. Reverted in `8d5eacecb4`.
-
-The first test in the oracle spec pins the refutation so this cannot come back as
-a "fix".
-
-## Why pixel oracles failed, and what replaced them
-
-The field defect is "the buffer is correct but the compositor shows pre-hide
-pixels". Two pixel oracles were built and **both were proven blind** by injecting
-that exact defect (freeze `RenderService.refreshRows`, then write new content):
-
-1. **Canvas-vs-buffer ink sampling.** `drawImage` on a
-   non-`preserveDrawingBuffer` WebGL canvas hands back a *re-rendered* copy — it
-   reported 0 missing cells against 5263 cells of text the canvas had never
-   drawn.
-2. **Screenshot vs. a forced repaint.** Playwright's screenshot drives a fresh
-   compositor frame, which *heals* the stale paint before capture; and the
-   "repair" ran the same code the reveal already ran, so a shared defect cancels
-   out.
-
-An earlier resize-referenced oracle was also unsound: resizing shifts alt-screen
-rows, so its 4.4% pixel diff measured legitimate reflow.
-
-**Pixels are the wrong layer** — anything that reads them can trigger the repaint
-that hides the bug. `tests/e2e/terminal-reveal-draw-command-probe.spec.ts`
-instead wraps `GlyphRenderer.updateCell` and `gl.drawElementsInstanced` on the
-live pane and counts draw commands. A draw command cannot be healed after the
-fact, so "did the reveal repaint?" is directly observable — and falsifiable,
-which is how the second hypothesis got refuted.
-
-Use that spec for **paint** questions;
-`terminal-opencode-altscreen-reveal-artifacts.spec.ts` for **buffer, geometry and
-PTY-size convergence** (worktree switch, cold park, idle agent, headful desktop
-hide). The idle-agent case matters: every earlier test kept the TUI streaming
-across the reveal, so live frames repainted whatever the reveal got wrong and the
-defect healed itself before any assertion ran.
-
-## Leads closed by measurement
-
-Both were live suspects in the previous handoff; both are now ruled out.
-
-- **Dimension staleness.** Every dimension-rebuilding path in `WebglRenderer` is
-  behind an unchanged/zero-sized early exit that a hidden pane trips, and
-  `performSafeFit` early-returns at unchanged geometry — so nothing on the reveal
-  path re-runs `handleResize()`. Measured across a real `window.hide()` /
-  `show()`: canvas backing store `1272×1104` matched the renderer's computed
-  dimensions exactly, char metrics stayed `8.65×16`, `_isAttached` stayed true,
-  the screen element stayed connected. No staleness.
-- **Lagging atlas page bindings.** Right after a reveal the bound texture version
-  *does* lag the atlas page (e.g. 1297 vs 1366) — but bindings are lazy and
-  `GlyphRenderer.render` rebinds any page whose version moved, so one repaint
-  brings them level (1366/1366). Normal, not a defect. Judge bindings only
-  *after* a draw.
-
-## Residual risk
-
-The oracle proves the repaint is *issued*; it does not photograph the user's
-screen. If a report survives this fix, the remaining suspects are below the draw
-call — GPU-process/compositor-level content loss — where the in-app sentinel on
-real hardware is the tool:
-
-```js
-localStorage.setItem('orca:render-desync-sentinel', '1')   // then reload
-```
-
-Reproduce, then **⌘-click** (Ctrl-click off Mac) in the garbled pane. That starts
-a 10s burst at 250ms intervals; a trip needs the same cells missing across 2
-consecutive samples, ≥200 text cells, ≥8% missing. It writes `corrupt.png` +
-`corrupt.json` to `<userData>/terminal-render-desync-evidence/<captureId>/`, then
-runs atlas recovery and captures the healed frame. Armed at import when the flag
-is set (`terminal-freeze-breadcrumbs.ts:45`).
-
-## Verification commands
-
-```bash
-npx vitest run --config config/vitest.config.ts src/renderer/src/lib/pane-manager/
-npx tsc --noEmit -p config/tsconfig.tc.web.json
-npx playwright test tests/e2e/terminal-reveal-draw-command-probe.spec.ts \
-  tests/e2e/terminal-opencode-altscreen-reveal-artifacts.spec.ts \
-  tests/e2e/terminal-inline-tui-reveal-convergence.spec.ts \
-  --config tests/playwright.config.ts --project=electron-headless --workers=1
-SKIP_BUILD=1 npx playwright test tests/e2e/terminal-opencode-altscreen-reveal-artifacts.spec.ts \
-  --config tests/playwright.config.ts --project=electron-headful --workers=1
-```
-
-To confirm the fix still has teeth, delete the
-`releaseAbandonedSynchronizedOutput(pane.terminal)` line from
-`schedulePaneRevealPresent` and re-run the oracle: the stranded-latch test fails
-with "the reveal repaint did not release the stranded latch, so the pane stays
-frozen".
-
-## Files
-
-Production:
-
-- `src/renderer/src/lib/pane-manager/terminal-synchronized-output-release.ts` (the fix)
-- `src/renderer/src/lib/pane-manager/pane-reveal-repaint.ts` (`schedulePaneRevealPresent`)
-- `src/renderer/src/lib/pane-manager/pane-webgl-renderer.ts` (`resetWebglTextureAtlas`)
-
-Tests:
-
-- `terminal-synchronized-output-release.test.ts`, `reveal-repaint-synchronized-output.test.ts`
-- `tests/e2e/terminal-reveal-draw-command-probe.spec.ts` (the oracle)
-- `tests/e2e/terminal-opencode-altscreen-reveal-artifacts.spec.ts`,
-  `tests/e2e/fixtures/opencode-altscreen-live-fixture.cjs`

docs/reference/plans/2026-07-28-orchestration-seamless-update-migration.md

@@ -0,0 +1,576 @@
+# Preserve active orchestration work across contract updates
+
+Status: implementation validation
+
+Date: 2026-07-28
+
+## Decision
+
+Do not block updates, restart active workers, or revive the retired scheduler.
+
+On first launch after the contract update, atomically adopt the durable
+pre-Run graph into one ordinary lightweight Run. Preserve every Task,
+Dispatch, message, gate, terminal, PTY, process, worktree, and prompt
+identifier. Mark only the pre-update Dispatch attempts as legacy-contract
+attempts and accept the exact command shapes already pasted into those
+workers through a narrow adapter.
+
+This is state migration plus a per-Dispatch protocol adapter. It is not a
+second scheduler:
+
+- the migrated Run owns the preserved graph and coordinator inbox;
+- legacy attempts keep their original protocol until they settle;
+- every new attempt uses the current protocol, even on a preserved Task; and
+- no placement, polling, concurrency, or deadline loop is resurrected.
+
+## User-visible outcome
+
+- The update installs immediately.
+- Existing coordinator and worker terminals keep the same process, PTY,
+  worktree, prompt, Task ID, Dispatch ID, and history.
+- Orca does not inject text, focus a tab, or start a replacement editor.
+- The legacy graph appears in an automatically adopted, normal Run instead of
+  being stranded in `run_legacy_local`.
+- An original live worker with retained launch proof can keep using the
+  `heartbeat`, `worker_done`, `escalation`, `ask`, and `check` commands in its
+  existing prompt.
+- An original live coordinator can keep listing and settling preserved Tasks,
+  dispatch remaining work with current commands, check direct legacy mail, and
+  use the pre-cutover `reply` CLI guidance.
+- Unprovable, stale, ambiguous, or already-settled rows remain inspectable and
+  unmistakably read-only. They never advertise Reply or Ack actions.
+- A pre-update WSL process whose older launcher did not propagate the hidden
+  token remains lifecycle read-only. Its assignment, process, terminal, and
+  filesystem work remain valid and inspectable.
+
+The retired `orchestration run`, `coordinator-start`, and `coordinator-stop`
+scheduler commands remain retired. Their in-memory loop cannot be reconstructed
+truthfully. The coordinator agent and all durable work remain accessible; it
+explicitly dispatches any ready work that was never assigned before the update.
+
+## Evidence and constraints
+
+- Schema v7 preserved old `messages`, `tasks`, `dispatch_contexts`, and
+  `decision_gates` by assigning them to `run_legacy_local`.
+- The exact prompt at `8b154d686` used old `send`, `ask`, and consuming
+  `check` shapes. It omitted `worker_done --outcome`; a subject equal to
+  `Failed` or beginning `Failed:` represented failure. Its escalation carried
+  `taskId` but no `dispatchId`.
+- `reply` existed in the old CLI and message formatter guidance, not in that
+  pinned worker prompt.
+- Restored `OrcaRuntime` PTY records currently set `launchToken: null`, and
+  provider `listProcesses()` does not expose the launch token. Handles and
+  pane IDs alone therefore cannot authorize compatibility.
+- Managed hooks source the owner-only endpoint file on every invocation, so an
+  old process reaches the new hook server after restart. The hook cache retains
+  the prior authenticated pane/launch-token association and distinguishes
+  hydrated rows from events observed by the current runtime.
+- Older builds did not propagate `ORCA_AGENT_LAUNCH_TOKEN` through `WSLENV`, and
+  a running process cannot acquire it retroactively.
+- The CLI transport mutation receipt is keyed by rotating runtime
+  authentication. It cannot deduplicate a legacy mutation across restart.
+- Current invalid-capability lifecycle sends deliberately remain as auditable
+  rejected messages. Compatibility must not silently change that behavior.
+- PR #11142 fixes background-tab materialization for newly dispatched workers.
+  It does not recover a pre-fix worker whose PTY survived an update after its
+  renderer tab binding was lost; workspace activation can otherwise mistake
+  that worker for a sleeping provider session and launch `codex resume`.
+- The packaged Windows launcher keeps its Electron-as-Node child alive for the
+  lifetime of a blocking CLI command. A seamless design cannot assume that a
+  bounded RPC wait releases the installed executable.
+
+## Non-negotiable invariants
+
+1. Adoption never spawns, writes, signals, stops, focuses, or injects a
+   terminal and never mutates the assigned filesystem. It may restore one
+   persisted background tab/leaf binding for the exact already-live PTY.
+2. Every durable row and identifier survives adoption; only its owning Run and
+   explicit protocol metadata change.
+3. Compatibility is write-once per Dispatch. Migration never classifies a
+   current retry as legacy.
+4. A legacy mutation requires one uniquely resolved legacy attempt or
+   coordinator principal plus current live proof of its original process tree.
+5. Caller-supplied handles, pane keys, Task IDs, Dispatch IDs, or remote
+   attachments never create authority.
+6. Current Dispatch behavior remains unchanged, including auditable rejected
+   lifecycle messages, capabilities, process incarnation, Run Delivery, and
+   question semantics.
+7. Legacy direct mail and current Run Delivery are disjoint, even when their
+   Dispatches share one migrated Task and Run.
+8. A B-era disconnect may replay accepted work; it may not lose mail or create
+   a second question, reply, completion, or settlement. A cut after an A-era
+   ask was already answered is explicitly ambiguous because A persisted no
+   invocation identity; recovery replays its answer through legacy check before
+   a same-text question is asked again.
+9. Different reply bodies for the same source and principal conflict instead
+   of creating multiple replies.
+10. Folder workspaces, SSH, WSL, remote runtimes, macOS, Linux, and Windows
+    follow the same proof rules. Missing proof degrades to inspection without
+    invalidating the retained assignment or filesystem work.
+
+## Storage and atomic adoption
+
+Raise the schema version and add:
+
+```text
+dispatch_contexts.contract_version INTEGER NOT NULL
+dispatch_contexts.launch_token_hash TEXT
+messages.delivery_contract TEXT NOT NULL
+  CHECK(delivery_contract IN ('legacy_direct', 'current_delivery', 'audit_only'))
+legacy_adoptions(
+  source_run_id PRIMARY KEY,
+  adopted_run_id UNIQUE NOT NULL,
+  scheduler_state_lost INTEGER NOT NULL,
+  adopted_at
+)
+legacy_compatibility_principals(
+  id PRIMARY KEY,
+  run_id NOT NULL,
+  dispatch_id,
+  role CHECK(role IN ('worker', 'coordinator')),
+  host_scope NOT NULL,
+  terminal_handle NOT NULL,
+  pane_key NOT NULL,
+  launch_token_hash NOT NULL,
+  process_incarnation,
+  status CHECK(status IN ('committed', 'settled', 'revoked')),
+  UNIQUE(role, run_id, dispatch_id)
+)
+legacy_operation_receipts(
+  principal_id,
+  operation_key,
+  method,
+  payload_hash,
+  effect_id,
+  response_json,
+  completed_at,
+  PRIMARY KEY(principal_id, operation_key)
+)
+legacy_mail_receipts(
+  principal_id,
+  message_id,
+  acknowledged_at,
+  PRIMARY KEY(principal_id, message_id)
+)
+```
+
+The schema migration runs in one `BEGIN IMMEDIATE` transaction:
+
+1. create a persisted random Run ID and `legacy_adoptions` marker if one does
+   not already exist;
+2. create an ordinary `legacy = 0` Run with a recovery objective;
+3. move all `run_legacy_local` Tasks, Dispatches, decision gates, messages,
+   and question threads to it without changing their IDs, sequence, status, or
+   content;
+4. mark pre-existing direct mail `legacy_direct` and hard-cutover rejection
+   rows `audit_only`;
+5. mark a Dispatch legacy only when it predates the contract column and lacks
+   a current dispatch capability; and
+6. fence any impossible outstanding legacy Delivery, move retained Delivery
+   history to the adopted Run, assert every Task/Dispatch/gate/message/question/
+   Delivery Run ID agrees, and leave `run_legacy_local` as an empty read-only
+   audit tombstone.
+
+Every new Dispatch and message writes the current contract explicitly.
+Repeated startup, a partially initialized fixture, and WAL recovery reuse the
+persisted adoption marker. Reset and fresh-database paths cannot synthesize
+legacy authority.
+
+## Durable principals and live authority
+
+After the hook server and PTY inventory are ready, a one-shot adoption service
+may commit compatibility principals. It does not mutate terminal processes or
+input.
+
+Before renderer hydration, legacy Dispatch evidence also fences automatic
+provider resume for the exact sleeping pane. Once the relevant local daemon or
+SSH relay has authoritative inventory, Orca intersects the durable handle,
+pane, PTY ID, PTY incarnation, workspace, and host owner. A unique live match
+is adopted into its original tab/leaf as inactive background state while the
+coordinator tab remains active. Missing, stale, reused, cross-host, or
+ambiguous evidence stays fenced and inspectable. Ordinary provider resume is
+unblocked only when authoritative inventory proves that exact PTY exited.
+
+At hook-server startup, copy the validated hydrated status rows into an
+immutable main-process-only startup snapshot before the server listens or
+binds the new listener. Later live events update a separate current-runtime
+observation map and cannot overwrite the pre-update commitment source. A
+current event is preferred but is not required before the worker's first
+post-restart lifecycle command when controller inventory proves the exact
+original PTY and process incarnation are live.
+
+For each candidate it resolves the union of:
+
+- durable Dispatch assignee and pane;
+- equivalent-pane aliases;
+- remote attachment and host ownership;
+- coordinator candidates from active legacy coordinator rows, Task creator
+  handles, Dispatch coordinator/parent provenance, and direct-message
+  sender/recipient history;
+- the restored terminal inventory and process incarnation; and
+- the hydrated, previously authenticated hook pane/launch-token association.
+
+The candidate commits only when that union identifies exactly one role and
+row. The orchestration database stores a SHA-256 token commitment, never the
+raw token. The existing owner-only hook status cache is an input to the
+one-time commitment, but a hydrated status is not enough to mutate.
+
+Every compatibility call then requires:
+
+- a hidden launch token and pane inherited by the calling process;
+- the immutable pre-update hook commitment, plus either a matching
+  current-runtime hook event or exact current controller proof of the original
+  PTY and process incarnation;
+- a live PTY with the committed handle, host scope, and process incarnation;
+- the committed principal and exact active legacy Dispatch or adopted Run; and
+- an operation-specific unique match.
+
+The current hook event or exact controller inventory proves that the process
+survived the restart; equality with the pre-update commitment proves it is the
+same launch. If the hook cache was absent, the provider cannot report the
+proof, the token changed, or any candidate is ambiguous, the row remains
+read-only.
+
+For new Dispatches, persist the launch-token hash at dispatch time so later
+contract updates do not depend on hook-cache recovery. Never return or log raw
+tokens. Add explicit RPC-envelope, structured-log, error, and CLI JSON
+redaction tests.
+
+Host scope is runtime-owned:
+
+- local: stable local execution-host identity;
+- WSL: stable native execution-host identity plus distro;
+- SSH: saved-host authority plus remote pane/process identity; and
+- federated runtime: authenticated peer fingerprint plus remote attachment.
+
+`pickRemoteCliEnv`, SSH relay forwarding, WSLENV, and the legacy in-process SSH
+fallback must carry the hidden evidence without exposing it in command text or
+logs. A local runtime never accepts a raw remote token as local authority.
+Pre-update WSL processes without the token cannot use the lifecycle adapter.
+
+For SSH, the host passthrough and in-process fallback stamp the saved target,
+`SshRelaySession` connection incarnation, and attachment provenance from the
+authenticated runtime channel; caller environment cannot choose them. WSL
+stamps the runtime-owned native host and distro in both the full bridge and
+fallback bridge. The verifier intersects those stamps with the committed host
+scope before considering token or pane evidence.
+
+## Mixed-contract Run and mail routing
+
+The adopted Run is a normal current Run. Tasks belong to it, so a current retry
+of a preserved Task naturally routes to the same Run without a cross-Run Task
+reference.
+
+Message delivery is selected by `messages.delivery_contract`, not by Run ID:
+
+- old and adapter-created direct messages are `legacy_direct`;
+- current sends are `current_delivery`; and
+- migration rejections and non-actionable history are `audit_only`.
+
+Current Run Delivery creation, filtering, waiting, and acknowledgment select
+only `current_delivery`. Legacy `check` selects only the exact principal's
+`legacy_direct` address. History and inbox may show all three with explicit
+labels but never attach actions to `audit_only`. Mixed legacy/current attempts
+under one Task are covered across send, ask, check, reply, and settlement.
+
+The original coordinator is automatically associated with the adopted Run
+after its principal proves live. `run-use` may bind that same principal without
+converting legacy Dispatches. A different coordinator cannot silently take
+over while a legacy attempt is active; an explicit recovery takeover is a
+separate current-contract action and revokes legacy coordinator mutation
+authority before rebinding.
+
+When that coordinator uses old direct `check`, the adapter also performs a
+non-consuming existence check for `current_delivery` mail. It never mixes the
+messages into legacy output; it prints the exact current Run check command and,
+after that command creates a Delivery, the exact acknowledgment form. This
+keeps an unchanged coordinator informed about current retries without
+weakening current Delivery semantics.
+
+## Exact legacy adapter
+
+The CLI keeps accepting the old flags. It sends a hidden compatibility
+envelope; the runtime, not the CLI, decides whether legacy behavior applies.
+
+Version B generates a random hidden `compatibilityInvocationId` once per CLI
+process and reuses it for every transport reconnect by that invocation.
+`legacy_operation_receipts.operation_key` is this invocation ID for B calls.
+The method and canonical payload hash must also match.
+
+Attested compatibility calls bypass the rotating-auth generic mutation ledger
+after the contract fence routes them to the adapter. Their only dedupe boundary
+is the compatibility-principal receipt transaction described here; current
+calls continue through the existing generic ledger unchanged.
+
+Version A had no invocation ID. Cross-cutover reconstruction is therefore
+limited to effects with a durable semantic identity: final settlement per
+Dispatch, still-pending ask per normalized question/options/recipient, reply
+per source/principal/body, and read recovery per message. Heartbeat and
+escalation remain at-least-once across an A-to-B manual retry because
+collapsing identical commands could suppress a legitimate later event. Tests
+and guidance do not promise cross-cutover exactly-once behavior for those
+repeatable signals.
+
+An A-era ask that was already answered before its output was lost is also
+ambiguous. B does not guess whether the same text means retry or a new
+question. Its answer is in the durable recovery cohort and the error tells the
+agent to run the exact legacy check command first. After that answer is printed
+and acknowledged, a new B invocation with identical text creates a new
+question. If multiple identical A threads exist, ask fails ambiguous and
+recovery check drains them by message sequence; no arbitrary thread is chosen.
+
+### Lifecycle `send`
+
+- `heartbeat` and `worker_done`: resolve Task + Dispatch from the payload, then
+  intersect them with the verified worker principal.
+- `escalation`: resolve Task + verified worker principal to exactly one active
+  legacy Dispatch because the old prompt supplied no Dispatch ID.
+- Preserve the old direct coordinator recipient after verifying it belongs to
+  the adopted Run principal.
+- Infer missing `worker_done` outcome as `failed` only when the trimmed subject
+  is `Failed` or begins `Failed:`; otherwise infer `succeeded`.
+- Normalize to the current internal settlement model.
+
+Compatibility validation happens before message insertion. Current lifecycle
+handling is not refactored through this prevalidation: its existing
+invalid-capability audit message behavior remains locked by regression tests.
+
+The DB commits the direct message, lifecycle effect, and compatibility receipt
+in one transaction. If a pre-update `worker_done` already settled the Dispatch,
+the adapter reconstructs the matching semantic receipt from the existing
+message and settlement. The persisted A settlement is authoritative: the
+pinned A reconciler recorded even a `Failed:` subject as completed, so B
+returns that original completed result rather than retroactively changing Task
+or dependency state. Only a not-yet-accepted B call applies the corrected
+failure inference. A conflicting retry fails.
+
+### `check`
+
+Legacy check is at-least-once:
+
+1. a read RPC returns the exact unacknowledged `legacy_direct` message IDs
+   without changing them;
+2. the CLI prints the complete response; and
+3. a hidden ack atomically records receipts and marks those exact rows read.
+
+A cut after read and before ack replays the same IDs. `--peek` and `--all`
+remain read-only.
+
+Version A could mark a message read before losing its response. On adoption,
+every eligible read direct message connected to a still-active legacy attempt
+and lacking a post-adoption receipt is inserted into a durable recovery cohort
+using `legacy_mail_receipts` with `acknowledged_at = NULL`. Legacy check drains
+that stable cohort in bounded sequence-ordered pages before ordinary unread
+mail. Each page is labeled
+`[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]`, replays until its post-print
+ack, and then advances. The cohort never grows after adoption, so every
+eligible row is covered without an unbounded response. Settled-at-cutover and
+unrelated historical mail do not enter it.
+
+### `ask`
+
+Legacy ask is an idempotent mutation followed by a resumable read:
+
+1. create or find the direct legacy gate/question by verified Dispatch,
+   normalized question, options, and recipient;
+2. atomically commit its message/thread plus operation receipt and return the
+   stable question ID;
+3. wait in bounded read-only slices using that ID; and
+4. after printing the answer, hidden-ack that exact answer.
+
+On first adoption, existing pending decision-gate threads are indexed into the
+same semantic identity. A retry resumes them instead of creating another gate.
+
+### `reply`
+
+Legacy reply requires the source thread, the verified coordinator principal,
+and a unique question owned by the adopted Run. One transaction inserts the
+reply, resolves the exact gate, marks the exact source, and completes the
+receipt.
+
+An existing pre-update reply with the same source, principal, and body is
+reconstructed as success. A second body for the same source/principal is a
+conflict, not another reply.
+
+### Coordinator and Task commands
+
+After automatic binding, unchanged Task listing, Task settlement, dispatch,
+and gate inspection use the adopted Run. A new attempt receives a current
+preamble, capability, launch-token commitment, and current message contract.
+No unrelated Task can be created until the migrated coordinator binding is
+proven or explicitly taken over.
+
+## Windows update behavior
+
+No compatibility mutation holds a DB transaction while waiting. Windows
+legacy `ask` commits the question, prints its stable ID and exact resume
+command, then exits before a long wait whenever the installed launcher cannot
+prove that the executable is replaceable.
+
+The native packaged launcher sets an internal
+`ORCA_WINDOWS_PACKAGED_CLI_LAUNCHER=1` marker for its Electron-as-Node child.
+After the DB commit, legacy `ask` writes and flushes the stable question ID and
+the exact resume command, then exits with a documented `75` resume-required
+status. The command name comes only from the validated inherited
+`ORCA_CLI_COMMAND` packaged enum: `orca` for native packaged terminals or
+`orca-ide` for packaged WSL. Arbitrary environment text is rejected rather
+than rendered. The launcher propagates status 75. No long wait starts on this
+path.
+
+This compatibility path makes the accepted question recoverable without
+claiming Windows updater or uninstaller process ownership. Generic executable
+drain, replacement, and uninstall behavior remains separate updater
+reliability work and requires its own Windows artifact proof.
+
+## Rendering and authoritative guidance
+
+Formatting is authority-aware:
+
+- `[LEGACY COMPATIBILITY]`: live and attested; show only supported commands;
+- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]`: one bounded cutover replay;
+- `[LEGACY READ-ONLY]`: retained but unactionable; no Reply or Ack hint; and
+- current messages: unchanged.
+
+Update `skill-guides/orchestration.md` and regenerate its bundled source. The
+guide explains automatic adoption, exact continuity, the retired scheduler
+boundary, proof failures, current retries, and the Windows ask resume fallback.
+It must not tell agents to restart a worker whose Dispatch was adopted.
+
+Formatting cannot use database provenance alone; current liveness and
+attestation are runtime facts. Recovery may reveal the exact already-live PTY
+once as an inactive background tab. It never creates a PTY or process, writes
+input, switches workspaces, focuses, splits, or injects a terminal.
+
+## Deterministic verification
+
+### Schema and authority
+
+- Migrate exact pre-v7, hard-cutover, current, partial, WAL, reset, and fresh
+  fixtures; preserve IDs and row counts and reuse one adopted Run.
+- Assert Task, Dispatch, decision-gate, message, question-thread, and retained
+  Delivery Run ownership agrees; outstanding legacy Deliveries are fenced.
+- Prove current retries in the adopted Run remain current across repeated
+  migrations.
+- Test unique worker/coordinator import from prior hook commitment plus current
+  live hook, and every forged, stale, wrong-host, wrong-pane, wrong-process,
+  duplicate-token, duplicate-role, equivalent-pane, and remote-attachment
+  ambiguity.
+- Race a current-runtime hook before adoption and prove the immutable startup
+  commitment is neither overwritten nor confused with live proof.
+- Cover manual coordinators with no `coordinator_runs` row and reject
+  conflicting candidates from Task, Dispatch, and message provenance.
+- Assert all legacy authority failures occur before message/receipt/gate/state
+  effects while current invalid-capability rejection remains unchanged.
+- Assert tokens are absent from RPC logs, errors, CLI output, and orchestration
+  storage.
+
+### Exact old behavior and replay
+
+- Replay the pinned prompt's heartbeat, successful and `Failed:`
+  `worker_done`, task-only escalation, ask, and consuming check.
+- Replay the old formatter's reply command separately.
+- Cover every operation once after B and once accepted by A immediately before
+  the cutover where a durable semantic identity exists, including the bounded
+  recovery replay for an A check and preservation of A's persisted settlement.
+- Prove one B invocation reuses its invocation ID across reconnect, while
+  separate identical heartbeat/escalation invocations remain distinct.
+- Inject real transport cuts after check read, ask commit, reply commit, and
+  completion commit; prove stable IDs and one receipt/effect.
+- Page a recovery cohort larger than one response limit across repeated
+  disconnects and prove every eligible row appears until ack, then never again.
+- Test mixed legacy/current attempts for every send/check/ask/reply route and
+  prove current Delivery cannot consume legacy direct mail and old coordinator
+  check only advertises the exact non-consuming current Delivery command.
+
+### Live two-launch E2E
+
+The focused renderer/daemon restart regression reconstructs the rc.3-era
+orphan artifact in a shared candidate profile: a durable legacy Dispatch,
+sleeping provider record, and live daemon PTY with its visual binding removed.
+It proves startup restores the exact PID, PTY/incarnation, handle, tab/leaf,
+Task, and Dispatch; emits no provider-resume spawn or interruption; preserves
+coordinator focus; and remains inert after switching away and back. This
+candidate/candidate fixture covers the renderer regression deterministically
+but does not replace the distinct installed-A/candidate-B packaged cutover
+journey below. It does not claim packaged Windows updater behavior.
+
+Use distinct installed A and B artifacts plus an external append-only fake
+agent spawn ledger:
+
+1. launch A with coordinator and worker terminals and record the replaceable A
+   desktop/main PID, runtime ID, version, and artifact hash separately from the
+   durable daemon, coordinator, and worker identities;
+2. accept one command with durable semantic identity on A—pending ask, reply,
+   completion, or check—cut its response, close A without stopping the daemon
+   or fake agent, install B, and prove B owns the relaunched runtime;
+3. assert A's desktop/main process and runtime are gone, B has a different
+   desktop/main PID, runtime ID, version, and artifact hash, while the daemon
+   plus coordinator/worker PID and start time, PTY/session, terminal handle,
+   tab/leaf/pane, worktree, Task, and Dispatch remain byte-identical;
+4. prove that exact pending ask, reply, completion, or check resumes or
+   deduplicates on B; do not use heartbeat, escalation, or an already-answered
+   A ask as an exactly-once oracle;
+5. run the remaining exact old lifecycle commands and settle the same
+   Dispatch;
+6. switch away and back and assert no second spawn/tab and no
+   `Conversation interrupted`; and
+7. create a current attempt on preserved state and prove current grammar.
+
+The append-only spawn ledger and an append-only interruption ledger, daemon
+inventory, runtime terminal inventory, and every viewer DOM independently
+prove one launch, process, handle, tab, and no `Conversation interrupted`.
+Transport fault injection cuts the real CLI connection after check output but
+before ack, and after ask, reply, and completion commit. Re-run the byte-exact A
+argv under B and assert stable IDs plus exactly one message, gate, reply,
+settlement, and receipt.
+
+Retain #11142's local visible-inactive test and extend its oracle beyond DOM
+counting with the ledgers and host inventory.
+
+Run separate remote journeys:
+
+- headed paired server A-to-B with a surviving external client;
+- headless `orca serve` A-to-B with the same surviving-client oracle;
+- both prove the remote PID/PTy continuity, both viewer states, zero
+  client-local handles/tabs, and wrong-host evidence with zero effects;
+- Docker SSH restart/reconnect with a remote proof file binding the process,
+  pane, and token commitment;
+- physical Windows WSL coverage proving the correct distro and rejecting a
+  wrong-distro token; and
+- a git-independent folder workspace parameter through the same adoption
+  journey.
+
+Packaged Windows updater continuity is outside this migration gate. A separate
+updater change must prove candidate-built A/B install, executable release,
+resume, and normal uninstall behavior on Windows before making that guarantee.
+
+## Implementation slices
+
+1. Schema, atomic Run adoption, per-row contract provenance, and mixed mailbox.
+2. Hook-commitment import, live principal verifier, host scopes, and redaction.
+3. Atomic compatibility receipts plus lifecycle send/escalation.
+4. Check read/ack and cutover recovery replay.
+5. Ask create/resume, reply conflict semantics, and coordinator binding.
+6. CLI hidden envelope, SSH/WSL forwarding, Windows resume fallback.
+7. Authority-aware formatting and the version-matched orchestration guide.
+8. Two-launch, remote, platform, and #11142 regression coverage.
+9. Focused unit/type/lint/E2E checks and final adversarial review.
+
+## Definition of done
+
+- Updates are never blocked.
+- Every durable legacy Task is owned by an ordinary visible Run.
+- Every provably original live legacy Dispatch can finish through its existing
+  prompt without changing process or worktree.
+- New attempts use the current contract and mailbox in that same Run.
+- No authority comes from IDs or handles alone.
+- No adoption step starts, stops, writes, signals, focuses, splits, or injects
+  a terminal. Exact live-PTY recovery may restore one inactive background
+  renderer tab/leaf binding.
+- B-era disconnects replay or deduplicate instead of losing or duplicating
+  work; A-era repeatable signals and already-answered asks follow the explicit
+  ambiguity recovery rules.
+- Lost scheduler memory is reported precisely without stranding durable state.
+- Local/background, remote, SSH, WSL, folder, and Windows guarantees have
+  deterministic proof.
+- The PR contains this plan, focused implementation, and no unrelated changes.

docs/workspace-space-scan-resource-bounds.md

@@ -87,11 +87,21 @@ allocate one live operation per entry.
 
 Every portable entry is admitted through `WorkspaceSpaceScanBudget` before retention:
 
-- maximum entries held at once per worktree traversal: 100,000;
+- maximum entries in any one directory listing: 100,000;
 - maximum estimated live scan state per worktree traversal: 64 MiB.
 
-The retained-byte estimate includes parent path and entry name UTF-16 storage plus conservative
-per-entry object overhead. These are admission limits, not post-allocation observations.
+The entry cap is per listing rather than per traversal because only a single directory's width is
+fixed by directory shape. A traversal-wide entry counter is charged by every worker holding a
+listing at once, so its verdict scales with the configured concurrency: at 48 workers, 48 × 2,100
+files (100,848 entries) was rejected while 100 × 1,500 (150,100 entries, 50% more) was admitted.
+Aggregate live retention stays bounded by the 64 MiB byte cap, which all concurrent listings share.
+
+The retained-byte estimate includes entry name UTF-16 storage plus conservative per-entry object
+overhead, and each listing's parent path once. The parent path is charged per listing rather than
+per entry because a listing's entries all share a single parent-path string; charging it per entry
+multiplied it by the directory's width, so the 64 MiB cap tracked checkout depth instead of live
+heap and rejected the layouts above once the worktree path passed ~58 characters. These are
+admission limits, not post-allocation observations.
 
 The budget measures what the traversal is holding **right now**, not what it has ever seen. A
 directory listing is charged when admitted and released once every one of its entries has been
@@ -100,9 +110,10 @@ distinction decides real workspaces: a cumulative counter charged an ordinary 76
 worktree 61.2 MiB of its 64 MiB cap — 4% headroom, and tipping over purely because a longer branch
 name lengthens every absolute path. The same worktree peaks between 4 MiB and 8 MiB of live state.
 
-Because the estimate scales with absolute path length, a cumulative cap would make success depend on
-where a user checks out their worktrees. A live cap depends only on directory shape, so it rejects
-genuinely pathological layouts (one directory holding six figures of entries) and nothing else.
+Neither cap may depend on where a user checks out their worktrees, so the estimate charges each
+absolute path once per listing rather than once per entry. A live cap depends only on directory
+shape, so it rejects genuinely pathological layouts (one directory holding six figures of entries)
+and nothing else.
 
 Top-level directory enumeration for the `du` path uses the same budget. A capacity error must not
 fall through into the portable walker, because that would repeat an already rejected traversal.
@@ -169,7 +180,7 @@ The deterministic regression measurements are:
 - peak simultaneous local `du` calls across repositories: exactly one;
 - peak simultaneous desktop-side SSH fallback traversals across repositories: at most two;
 - portable traversal live entry jobs: no more than its configured worker count;
-- portable entries held at once: at most 100,000 per worktree;
+- portable entries in any one directory listing: at most 100,000;
 - estimated live portable state: at most 64 MiB per worktree; an ordinary 76,788-entry worktree
   peaks between 4 MiB and 8 MiB;
 - progress and final row counts remain unchanged for scans below the limits.

electron.vite.config.ts

@@ -208,6 +208,11 @@ export const electronViteConfig: UserConfig = {
           // Why: forked with ELECTRON_RUN_AS_NODE so @parcel/watcher faults
           // can't take down the main process (issue #7547).
           'parcel-watcher-process-entry': resolve('src/main/ipc/parcel-watcher-process-entry.ts'),
+          // Why: a worker thread survives the macOS 26 AppKit main-thread deadlock
+          // without paying for another Electron process.
+          'main-thread-hang-watchdog-entry': resolve(
+            'src/main/hang-watchdog/main-thread-hang-watchdog-entry.ts'
+          ),
           // Why: run under ELECTRON_RUN_AS_NODE while the caller blocks on
           // spawnSync — codex app-server trust grants need a live event loop
           // but must finish before a Codex pane launch proceeds.

i18next.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'i18next-cli'
+
+const output =
+  process.env.ORCA_I18N_EXTRACTION_OUTPUT ?? 'tmp/localization-extraction/{{language}}.json'
+
+export default defineConfig({
+  locales: ['en'],
+  extract: {
+    input: ['src/**/*.{js,jsx,ts,tsx,mts,cts}'],
+    ignore: [
+      '**/*.test.*',
+      '**/*.spec.*',
+      '**/__tests__/**',
+      '**/__snapshots__/**',
+      '**/assets/**'
+    ],
+    output,
+    defaultNS: false,
+    functions: ['t', '*.t', 'translate', 'translateMain'],
+    useTranslationNames: ['useTranslation'],
+    sort: true,
+    disablePlurals: true,
+    removeUnusedKeys: true
+  }
+})

mobile/package.json

@@ -72,6 +72,7 @@
     "acorn": "8.15.0",
     "esbuild": "0.25.4",
     "expo-module-scripts": "^55.0.2",
+    "happy-dom": "^20.9.0",
     "oxfmt": "^0.52.0",
     "oxlint": "^1.71.0",
     "react-test-renderer": "19.2.6",

mobile/pnpm-lock.yaml

@@ -168,6 +168,9 @@ importers:
       expo-module-scripts:
         specifier: ^55.0.2
         version: 55.0.2(@babel/core@7.29.7)(@babel/runtime@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(eslint@9.39.4)(expo@55.0.27)(jest@29.7.0(@types/node@26.1.1))(prettier@2.8.8)(react-native@0.83.9(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.6))(react-refresh@0.14.2)(react-test-renderer@19.2.6(react@19.2.6))(react@19.2.6)
+      happy-dom:
+        specifier: ^20.9.0
+        version: 20.11.1
       oxfmt:
         specifier: ^0.52.0
         version: 0.52.0
@@ -188,7 +191,7 @@ importers:
         version: 8.1.0(@types/node@26.1.1)(esbuild@0.25.4)(terser@5.49.0)(tsx@4.22.4)(yaml@2.9.0)
       vitest:
         specifier: ^4.1.9
-        version: 4.1.9(@types/node@26.1.1)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.1.1)(esbuild@0.25.4)(terser@5.49.0)(tsx@4.22.4)(yaml@2.9.0))
+        version: 4.1.9(@types/node@26.1.1)(happy-dom@20.11.1)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.1.1)(esbuild@0.25.4)(terser@5.49.0)(tsx@4.22.4)(yaml@2.9.0))
 
 packages:
 
@@ -2741,6 +2744,9 @@ packages:
   '@types/unist@3.0.3':
     resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
 
+  '@types/whatwg-mimetype@3.0.2':
+    resolution: {integrity: sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA==}
+
   '@types/ws@8.18.1':
     resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
 
@@ -3177,6 +3183,10 @@ packages:
   buffer-from@1.1.2:
     resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
 
+  buffer-image-size@0.6.4:
+    resolution: {integrity: sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ==}
+    engines: {node: '>=4.0'}
+
   buffer@6.0.3:
     resolution: {integrity: sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==}
 
@@ -3556,6 +3566,10 @@ packages:
     resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
     engines: {node: '>=0.12'}
 
+  entities@7.0.1:
+    resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
+    engines: {node: '>=0.12'}
+
   error-ex@1.3.4:
     resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==}
 
@@ -4286,6 +4300,10 @@ packages:
   graceful-fs@4.2.11:
     resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
 
+  happy-dom@20.11.1:
+    resolution: {integrity: sha512-XSt8tMzbW9ymE7687xztkO1ckR7qJNQ3LywY9vlYGhGi3zXrGBHuUo2Cl1ztZaICW+1eAGdkLbj6iwVqDT33kg==}
+    engines: {node: '>=20.0.0'}
+
   has-bigints@1.1.0:
     resolution: {integrity: sha512-R3pbpkcIqv2Pm3dUwgjclDRVmWpTJW2DcMzcIhEXEx1oh/CEMObMm3KLmRJOdvhM7o4uQBnwr8pzRK2sJWIqfg==}
     engines: {node: '>= 0.4'}
@@ -9661,6 +9679,8 @@ snapshots:
 
   '@types/unist@3.0.3': {}
 
+  '@types/whatwg-mimetype@3.0.2': {}
+
   '@types/ws@8.18.1':
     dependencies:
       '@types/node': 25.6.0
@@ -10236,6 +10256,10 @@ snapshots:
 
   buffer-from@1.1.2: {}
 
+  buffer-image-size@0.6.4:
+    dependencies:
+      '@types/node': 26.1.1
+
   buffer@6.0.3:
     dependencies:
       base64-js: 1.5.1
@@ -10611,6 +10635,8 @@ snapshots:
 
   entities@6.0.1: {}
 
+  entities@7.0.1: {}
+
   error-ex@1.3.4:
     dependencies:
       is-arrayish: 0.2.1
@@ -11614,6 +11640,19 @@ snapshots:
 
   graceful-fs@4.2.11: {}
 
+  happy-dom@20.11.1:
+    dependencies:
+      '@types/node': 26.1.1
+      '@types/whatwg-mimetype': 3.0.2
+      '@types/ws': 8.18.1
+      buffer-image-size: 0.6.4
+      entities: 7.0.1
+      whatwg-mimetype: 3.0.0
+      ws: 8.21.0
+    transitivePeerDependencies:
+      - bufferutil
+      - utf-8-validate
+
   has-bigints@1.1.0: {}
 
   has-flag@3.0.0: {}
@@ -14235,7 +14274,7 @@ snapshots:
       tsx: 4.22.4
       yaml: 2.9.0
 
-  vitest@4.1.9(@types/node@26.1.1)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.1.1)(esbuild@0.25.4)(terser@5.49.0)(tsx@4.22.4)(yaml@2.9.0)):
+  vitest@4.1.9(@types/node@26.1.1)(happy-dom@20.11.1)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.1.1)(esbuild@0.25.4)(terser@5.49.0)(tsx@4.22.4)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.9
       '@vitest/mocker': 4.1.9(vite@8.1.0(@types/node@26.1.1)(esbuild@0.25.4)(terser@5.49.0)(tsx@4.22.4)(yaml@2.9.0))
@@ -14259,6 +14298,7 @@ snapshots:
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 26.1.1
+      happy-dom: 20.11.1
       jsdom: 20.0.3
     transitivePeerDependencies:
       - msw

mobile/scripts/mock-server-rpc-handlers.ts

@@ -12,6 +12,7 @@ import { handleMockFilePreviewRequest } from './mock-server-file-preview-data'
 import { handleMockGitRequest } from './mock-server-git-state'
 import { handleMockAccountRequest } from './mock-server-account-rpc'
 import { handleMockNativeChatRequest } from './mock-server-native-chat-scenario'
+import { handleMockSessionTabsRequest } from './mock-server-session-tabs-fixture'
 import {
   createMockTerminals,
   FAKE_SCROLLBACK,
@@ -124,7 +125,8 @@ export function handleRequest(
     handleMockGitRequest(request, respond, success) ||
     handleMockFilePreviewRequest(request, respond, success, error) ||
     handleMockAccountRequest(request, respond, success, error) ||
-    handleMockNativeChatRequest(request, respond, success, error, ws)
+    handleMockNativeChatRequest(request, respond, success, error, ws) ||
+    handleMockSessionTabsRequest(request, respond, success, terminalListWorktreeId)
   ) {
     return
   }

mobile/scripts/mock-server-session-tabs-fixture.ts

@@ -0,0 +1,69 @@
+import { randomUUID } from 'node:crypto'
+import type { RuntimeMobileSessionTabsResult } from '../../src/shared/runtime-types'
+import type { RpcRequest, RpcResponse } from './mock-server-rpc-handlers'
+
+// Why: the client's snapshot-acceptance gate keys on the publisher epoch, so it
+// must stay stable for the process and change on restart like a real publisher —
+// hence a uuid, not a clock read two restarts could land on.
+// The `mobile-local:` prefix is reserved for phone-local writes — never use it.
+const PUBLICATION_EPOCH = `mock-server:${randomUUID()}`
+const GROUP_ID = 'group-1'
+const PARENT_TAB_ID = 'tab-1'
+// The host only ever publishes terminal-layout UUIDs here; pane-key parsing
+// rejects any other shape, so a placeholder would mask pane-attribution bugs.
+const LEAF_ID = 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+// The host publishes terminal surfaces as `${parentTabId}::${leafId}`.
+const SURFACE_TAB_ID = `${PARENT_TAB_ID}::${LEAF_ID}`
+
+/** One ready terminal tab bound to the `term-1` fixture. Mirrors the full
+ *  `session.tabs.list` contract so mock-server repros of tab, split-pane, and
+ *  pane-attribution bugs aren't shape-incomplete. */
+function createMockSessionTabs(worktreeId: string): RuntimeMobileSessionTabsResult {
+  return {
+    worktree: worktreeId,
+    publicationEpoch: PUBLICATION_EPOCH,
+    snapshotVersion: 1,
+    activeGroupId: GROUP_ID,
+    activeTabId: SURFACE_TAB_ID,
+    activeTabType: 'terminal',
+    // Groups track top-level tabs, so they carry parentTabId, not surface ids.
+    tabGroups: [
+      {
+        id: GROUP_ID,
+        activeTabId: PARENT_TAB_ID,
+        tabOrder: [PARENT_TAB_ID],
+        recentTabIds: [PARENT_TAB_ID]
+      }
+    ],
+    tabs: [
+      {
+        type: 'terminal',
+        id: SURFACE_TAB_ID,
+        title: 'zsh',
+        parentTabId: PARENT_TAB_ID,
+        leafId: LEAF_ID,
+        status: 'ready',
+        terminal: 'term-1',
+        isActive: true
+      }
+    ]
+  }
+}
+
+/** Default session-tabs backend: without it the session screen hangs on
+ *  'Loading tabs'. Returns false for methods it does not own. */
+export function handleMockSessionTabsRequest(
+  request: RpcRequest,
+  respond: (response: RpcResponse) => void,
+  success: (id: string, result: unknown, streaming?: boolean) => RpcResponse,
+  // Shared with `terminal.list` so both surfaces agree on which worktree an
+  // absent or `id:`-prefixed selector means.
+  resolveWorktreeId: (selector: unknown) => string | undefined
+): boolean {
+  if (request.method !== 'session.tabs.list') {
+    return false
+  }
+  const worktreeId = resolveWorktreeId(request.params?.worktree) ?? 'mock'
+  respond(success(request.id, createMockSessionTabs(worktreeId)))
+  return true
+}

mobile/src/agent-history/MobileAgentSessionHistoryPanel.tsx

@@ -10,15 +10,17 @@ import type { RpcClient } from '../transport/rpc-client'
 import { getWorktreeLabel } from '../session/worktree-label'
 import {
   buildMobileAiVaultResumeLaunch,
-  prepareMobileAiVaultSessionResume,
   createMobileAiVaultResumeMutationRegistry,
   readMobileRuntimeHostPlatform,
   readMobileRuntimeTerminalWindowsShell,
   resolveMobileAiVaultResumePlatform,
   resumeAiVaultSessionInTerminal,
-  RESUME_RPC_TIMEOUT_MS,
   type MobileAiVaultResumeSettings
 } from '../session/ai-vault-resume-launch'
+import {
+  prepareMobileAiVaultSessionResume,
+  RESUME_RPC_TIMEOUT_MS
+} from '../session/ai-vault-resume-preparation'
 import { triggerError, triggerSuccess } from '../platform/haptics'
 import type { AiVaultScope, AiVaultSession } from '../../../src/shared/ai-vault-types'
 import type { Worktree } from '../worktree/workspace-list-types'

mobile/src/components/BottomDrawer.tsx

@@ -1,4 +1,4 @@
-import { type ReactNode, useState } from 'react'
+import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react'
 import { resolveBottomDrawerMounted } from './bottom-drawer-mount-state'
 import { MountedBottomDrawer } from './mounted-bottom-drawer'
 
@@ -31,6 +31,37 @@ export function BottomDrawer({
   zIndex
 }: Props) {
   const [mounted, setMounted] = useState(visible)
+  const onAfterCloseRef = useRef(onAfterClose)
+  const hiddenHandledRef = useRef(false)
+  const afterClosePendingRef = useRef(false)
+
+  useEffect(() => {
+    onAfterCloseRef.current = onAfterClose
+  }, [onAfterClose])
+
+  useEffect(() => {
+    if (visible) {
+      hiddenHandledRef.current = false
+      afterClosePendingRef.current = false
+    }
+  }, [visible])
+
+  useEffect(() => {
+    if (mounted || !afterClosePendingRef.current) {
+      return
+    }
+    afterClosePendingRef.current = false
+    onAfterCloseRef.current?.()
+  }, [mounted])
+
+  const handleHidden = useCallback(() => {
+    if (hiddenHandledRef.current) {
+      return
+    }
+    hiddenHandledRef.current = true
+    afterClosePendingRef.current = true
+    setMounted(false)
+  }, [])
   const resolvedMounted = resolveBottomDrawerMounted(visible, mounted)
 
   // Why: opening drawers should mount before commit; waiting for a passive
@@ -49,10 +80,7 @@ export function BottomDrawer({
     <MountedBottomDrawer
       visible={visible}
       onClose={onClose}
-      onHidden={() => {
-        setMounted(false)
-        onAfterClose?.()
-      }}
+      onHidden={handleHidden}
       dragContentToDismiss={dragContentToDismiss}
       contentScrollable={contentScrollable}
       fillAvailable={fillAvailable}

mobile/src/components/MobileMarkdown.test.ts

@@ -70,9 +70,64 @@ describe('parseMobileMarkdown', () => {
     expect(normalizeMobileMarkdownPreviewHtml('Array<string> in prose')).toBe(
       'Array<string> in prose'
     )
+    expect(normalizeMobileMarkdownPreviewHtml('Promise<Result> in prose')).toBe(
+      'Promise<Result> in prose'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('Promise<Array<string>> in prose')).toBe(
+      'Promise<Array<string>> in prose'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('Map<string, Array<number>> in prose')).toBe(
+      'Map<string, Array<number>> in prose'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('type Box<T = string> = { value: T }')).toBe(
+      'type Box<T = string> = { value: T }'
+    )
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        'type Box<T extends object, Value = string> = { value: Value }'
+      )
+    ).toBe('type Box<T extends object, Value = string> = { value: Value }')
+    expect(normalizeMobileMarkdownPreviewHtml('a<b=c>')).toBe('a<b=c>')
+    expect(normalizeMobileMarkdownPreviewHtml('<T> is a type parameter')).toBe(
+      '<T> is a type parameter'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<mailto:orca@example.com>')).toBe(
+      '<mailto:orca@example.com>'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<ftp://example.com/file>')).toBe(
+      '<ftp://example.com/file>'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<tel:+15551234567>')).toBe('<tel:+15551234567>')
     expect(normalizeMobileMarkdownPreviewHtml('<https://example.com>')).toBe(
       '<https://example.com>'
     )
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        "<https://en.wikipedia.org/wiki/O'Brien> <svg>hidden</svg>"
+      )
+    ).toBe("<https://en.wikipedia.org/wiki/O'Brien> hidden")
+    expect(normalizeMobileMarkdownPreviewHtml('Replace <your-api-key> now')).toBe(
+      'Replace <your-api-key> now'
+    )
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<span title="</your-api-key>"></span> Replace <your-api-key> now'
+      )
+    ).toBe('Replace <your-api-key> now')
+    expect(
+      normalizeMobileMarkdownPreviewHtml('<span title="</string>"></span> Array<string> now')
+    ).toBe('Array<string> now')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<span title=</your-api-key>></span> Replace <your-api-key> now'
+      )
+    ).toBe('Replace <your-api-key> now')
+    expect(
+      normalizeMobileMarkdownPreviewHtml('<span title=</string>></span> Array<string> now')
+    ).toBe('Array<string> now')
+    expect(normalizeMobileMarkdownPreviewHtml('Use <insert name here> next')).toBe(
+      'Use <insert name here> next'
+    )
     expect(normalizeMobileMarkdownPreviewHtml('<div>Readable text</div>')).toBe('Readable text')
   })
 
@@ -91,4 +146,131 @@ describe('parseMobileMarkdown', () => {
       `${literalPlaceholder} and \`Array<string>\``
     )
   })
+
+  it('strips nested HTML and SVG markup without leaking tag variants', () => {
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<p>Logo<svg viewBox="0 0 1 1"><g><path d="M0 > 0"/></g></svg> done</p>'
+      )
+    ).toBe('Logo done')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<svg/onload=alert(1)><path/></svg> done')).toBe(
+      'Logo done'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<svg=invalid><path/></svg> done')).toBe(
+      'Logo done'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<svg=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<SVG=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<path=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<p=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<strong=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<math=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<foo=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<my-widget=invalid>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<my-widget disabled>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('<svg=invalid><path/>')).toBe('')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<my-widget=invalid>Hi</my-widget> done')).toBe(
+      'LogoHi done'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<SVG><PATH/></SVG>')).toBe('')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<svg>Hi<path>there')).toBe('LogoHithere')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<p>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<B>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<strong>Hi')).toBe('LogoHi')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<center>Hi <font>there <marquee>now')).toBe(
+      'LogoHi there now'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<center>Title</center>')).toBe('Title')
+    expect(normalizeMobileMarkdownPreviewHtml('<my-widget>Hi</my-widget>')).toBe('Hi')
+    expect(normalizeMobileMarkdownPreviewHtml('<my:widget>')).toBe('')
+    expect(normalizeMobileMarkdownPreviewHtml('<svg:path>')).toBe('')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<foo>Hi</foo> done')).toBe('LogoHi done')
+    expect(normalizeMobileMarkdownPreviewHtml('</1>Logo<svg>Hi</svg> done')).toBe('</1>LogoHi done')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<svg>Hi</svg   > done')).toBe('LogoHi done')
+    expect(normalizeMobileMarkdownPreviewHtml('&lt;svg&gt;&lt;path/&gt;&lt;/svg&gt;')).toBe(
+      '<svg><path/></svg>'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<p>Use &lt;svg&gt; icons</p>')).toBe(
+      'Use <svg> icons'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<p title="a > b">x</p>')).toBe('x')
+    expect(normalizeMobileMarkdownPreviewHtml("<p title='a > b'>x</p>")).toBe('x')
+    expect(normalizeMobileMarkdownPreviewHtml('<img alt="a > b">')).toBe('a > b')
+    expect(
+      normalizeMobileMarkdownPreviewHtml('<a title="a > b" href="https://example.com">link</a>')
+    ).toBe('[link](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a href="https://example.com">first <a href="https://example.com">second'
+      )
+    ).toBe('first second')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a-widget href="https://wrong.example">custom</a-widget> <a href="https://example.com">real</a>'
+      )
+    ).toBe('custom [real](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a data-href="https://wrong.example" href="https://example.com">real</a>'
+      )
+    ).toBe('[real](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a title="see href=https://wrong.example" href="https://example.com">real</a>'
+      )
+    ).toBe('[real](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml('<a data-href="https://wrong.example">plain</a>')
+    ).toBe('plain')
+    expect(normalizeMobileMarkdownPreviewHtml('<img data-alt="wrong" alt="right">')).toBe('right')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a:widget href="https://wrong.example">custom</a:widget> <a href="https://example.com">real</a>'
+      )
+    ).toBe('custom [real](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a=invalid href="https://wrong.example">bad <a href="https://example.com">real</a>'
+      )
+    ).toBe('bad [real](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a href="https://wrong.example"/>bad <a href="https://example.com">real</a>'
+      )
+    ).toBe('bad [real](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<a href="https://wrong.example">bad <a href="https://example.com">real</a>'
+      )
+    ).toBe('bad [real](https://example.com)')
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        'before<p title="unterminated>middle<svg><path/></svg>after'
+      )
+    ).toBe('beforemiddleafter')
+    expect(normalizeMobileMarkdownPreviewHtml('before<p title=x<svg><path/></svg>after')).toBe(
+      'beforeafter'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<p>first</p><p>second')).toBe('first\nsecond')
+    expect(normalizeMobileMarkdownPreviewHtml('<strong>first</strong><strong>second')).toBe(
+      '**first**second'
+    )
+    expect(
+      normalizeMobileMarkdownPreviewHtml(
+        '<strong-widget>custom</strong-widget> <strong>real</strong>'
+      )
+    ).toBe('custom **real**')
+    expect(
+      normalizeMobileMarkdownPreviewHtml('Logo<strong=invalid>Hi <strong>real</strong> done')
+    ).toBe('LogoHi **real** done')
+    expect(normalizeMobileMarkdownPreviewHtml('Logo<strong />Hi <strong>real</strong> done')).toBe(
+      'LogoHi **real** done'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml('<strong>bad <strong>real</strong> done')).toBe(
+      'bad **real** done'
+    )
+    expect(normalizeMobileMarkdownPreviewHtml(`${'<p>x'.repeat(4096)}</p>`)).toBe(
+      `${'x'.repeat(4095)}\nx`
+    )
+  })
 })

mobile/src/components/bottom-drawer-close-lifecycle.test.ts

@@ -0,0 +1,103 @@
+import { createElement } from 'react'
+import { act, create, type ReactTestRenderer } from 'react-test-renderer'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { BottomDrawer } from './BottomDrawer'
+
+vi.mock('./mounted-bottom-drawer', () => ({
+  MountedBottomDrawer: 'MountedBottomDrawer'
+}))
+
+function renderDrawer(
+  visible: boolean,
+  onClose: () => void,
+  onAfterClose: () => void
+): ReactTestRenderer {
+  let renderer: ReactTestRenderer | null = null
+  act(() => {
+    renderer = create(
+      createElement(
+        BottomDrawer,
+        { visible, onClose, onAfterClose },
+        createElement('DrawerContent')
+      )
+    )
+  })
+  if (!renderer) {
+    throw new Error('Bottom drawer did not render')
+  }
+  return renderer
+}
+
+function updateDrawer(
+  renderer: ReactTestRenderer,
+  visible: boolean,
+  onClose: () => void,
+  onAfterClose: () => void
+): void {
+  act(() => {
+    renderer.update(
+      createElement(
+        BottomDrawer,
+        { visible, onClose, onAfterClose },
+        createElement('DrawerContent')
+      )
+    )
+  })
+}
+
+function mountedDrawer(renderer: ReactTestRenderer) {
+  return renderer.root.findByType('MountedBottomDrawer')
+}
+
+describe('BottomDrawer close lifecycle', () => {
+  beforeEach(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true
+    const originalConsoleError = console.error
+    vi.spyOn(console, 'error').mockImplementation((...args) => {
+      const message = args[0]
+      if (
+        typeof message === 'string' &&
+        (message.includes('react-test-renderer is deprecated') ||
+          message.includes('The current testing environment is not configured to support act'))
+      ) {
+        return
+      }
+      originalConsoleError(...args)
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('keeps close stable and delivers the latest action once after unmount', () => {
+    const firstAfterClose = vi.fn()
+    const rendered: { current?: ReactTestRenderer } = {}
+    const latestAfterClose = vi.fn(() => {
+      expect(rendered.current?.toJSON()).toBeNull()
+    })
+    const renderer = renderDrawer(true, vi.fn(), firstAfterClose)
+    rendered.current = renderer
+    const initialOnHidden = mountedDrawer(renderer).props.onHidden
+
+    updateDrawer(renderer, false, vi.fn(), firstAfterClose)
+    const closingOnHidden = mountedDrawer(renderer).props.onHidden
+    updateDrawer(renderer, false, vi.fn(), latestAfterClose)
+    const rerenderedOnHidden = mountedDrawer(renderer).props.onHidden
+
+    expect(closingOnHidden).toBe(initialOnHidden)
+    expect(rerenderedOnHidden).toBe(initialOnHidden)
+
+    act(() => {
+      rerenderedOnHidden()
+      rerenderedOnHidden()
+    })
+    act(() => {
+      rerenderedOnHidden()
+    })
+
+    expect(firstAfterClose).not.toHaveBeenCalled()
+    expect(latestAfterClose).toHaveBeenCalledTimes(1)
+    expect(renderer.toJSON()).toBeNull()
+  })
+})

mobile/src/components/mobile-markdown-preview-html.ts

@@ -1,3 +1,11 @@
+import {
+  findMobileMarkdownMarkupTagEnd,
+  findNextPairedMarkupOpener,
+  isPairedMarkupOpener,
+  replaceMobileMarkdownPairedMarkupTags,
+  stripMobileMarkdownMarkupTags
+} from './mobile-markdown-preview-tag-stripper'
+
 // Why: README HTML snippets can document escaped entities; repeated cleanup
 // passes must not turn `<` into a real tag and strip it.
 const escapedHtmlEntityTokens = [
@@ -5,24 +13,11 @@ const escapedHtmlEntityTokens = [
   { pattern: /</gi, token: '\uE000ORCA_MD_ENTITY_LT\uE000', value: '<' },
   { pattern: />/gi, token: '\uE000ORCA_MD_ENTITY_GT\uE000', value: '>' },
   { pattern: /"/gi, token: '\uE000ORCA_MD_ENTITY_QUOT\uE000', value: '"' },
-  { pattern: /'/gi, token: '\uE000ORCA_MD_ENTITY_APOS\uE000', value: ''' }
+  { pattern: /'/gi, token: '\uE000ORCA_MD_ENTITY_APOS\uE000', value: ''' },
+  { pattern: /&lt;/gi, token: '\uE000ORCA_MD_ENTITY_RAW_LT\uE000', value: '<' },
+  { pattern: /&gt;/gi, token: '\uE000ORCA_MD_ENTITY_RAW_GT\uE000', value: '>' }
 ] as const
 
-const strippableHtmlTagNames = new Set(
-  [
-    'a abbr address area article aside audio b base bdi bdo blockquote body br button',
-    'canvas caption cite code col colgroup data datalist dd del details dfn dialog div',
-    'dl dt em embed fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head',
-    'header hgroup hr html i iframe img input ins kbd label legend li link main map',
-    'mark menu meta meter nav noscript object ol optgroup option output p picture pre',
-    'progress q rp rt ruby s samp script search section select slot small source span',
-    'strong style sub summary sup table tbody td template textarea tfoot th thead time',
-    'title tr track u ul var video wbr'
-  ]
-    .join(' ')
-    .split(' ')
-)
-
 function protectEscapedHtmlEntities(value: string): string {
   return escapedHtmlEntityTokens.reduce(
     (next, entity) => next.replace(entity.pattern, entity.token),
@@ -52,11 +47,7 @@ function decodeHtmlEntities(value: string, preserveEscapedEntities = false): str
 function stripTags(value: string): string {
   const { protectedText, codeSpans, placeholderPrefix } = protectMarkdownCode(value)
   const stripped = decodeHtmlEntities(
-    protectedText
-      .replace(/<!--[\s\S]*?-->/g, '')
-      .replace(/<\/?([A-Za-z][A-Za-z0-9:-]*)(?:\s[^<>]*)?\/?>/g, (tag, name: string) =>
-        strippableHtmlTagNames.has(name.toLowerCase()) ? '' : tag
-      ),
+    stripMobileMarkdownMarkupTags(protectedText.replace(/<!--[\s\S]*?-->/g, '')),
     true
   )
     .replace(/[ \t]+\n/g, '\n')
@@ -67,36 +58,141 @@ function stripTags(value: string): string {
 }
 
 function attrValue(tag: string, name: string): string {
-  const pattern = new RegExp(`${name}\\s*=\\s*("[^"]*"|'[^']*'|[^\\s>]+)`, 'i')
-  const match = tag.match(pattern)
-  const raw = match?.[1] ?? ''
-  return decodeHtmlEntities(raw.replace(/^["']|["']$/g, ''))
+  let cursor = 1
+  while (cursor < tag.length && !/[\s/>]/.test(tag[cursor] ?? '')) {
+    cursor += 1
+  }
+  while (cursor < tag.length) {
+    while (/\s/.test(tag[cursor] ?? '')) {
+      cursor += 1
+    }
+    if (tag[cursor] === '>' || (tag[cursor] === '/' && tag[cursor + 1] === '>')) {
+      return ''
+    }
+
+    const attributeStart = cursor
+    while (!/[\s=/>]/.test(tag[cursor] ?? '>')) {
+      cursor += 1
+    }
+    if (attributeStart === cursor) {
+      cursor += 1
+      continue
+    }
+    const attributeName = tag.slice(attributeStart, cursor)
+    while (/\s/.test(tag[cursor] ?? '')) {
+      cursor += 1
+    }
+    if (tag[cursor] !== '=') {
+      continue
+    }
+
+    cursor += 1
+    while (/\s/.test(tag[cursor] ?? '')) {
+      cursor += 1
+    }
+    const quote = tag[cursor] === '"' || tag[cursor] === "'" ? tag[cursor] : ''
+    if (quote) {
+      cursor += 1
+    }
+    const valueStart = cursor
+    if (quote) {
+      const valueEnd = tag.indexOf(quote, cursor)
+      if (valueEnd < 0) {
+        return ''
+      }
+      cursor = valueEnd + 1
+      if (attributeName.toLowerCase() === name) {
+        return decodeHtmlEntities(tag.slice(valueStart, valueEnd))
+      }
+      continue
+    }
+
+    while (!/[\s>]/.test(tag[cursor] ?? '>')) {
+      cursor += 1
+    }
+    if (attributeName.toLowerCase() === name) {
+      return decodeHtmlEntities(tag.slice(valueStart, cursor))
+    }
+  }
+  return ''
+}
+
+const tagAttributesSource = `(?:[^<>"']|"[^"]*"|'[^']*')*`
+const imageTagPattern = new RegExp(`<img\\b${tagAttributesSource}>`, 'gi')
+
+function normalizeAnchorTags(value: string): string {
+  const lowerValue = value.toLowerCase()
+  let output = ''
+  let copyCursor = 0
+  let searchCursor = 0
+  let closingStart = -1
+
+  while (searchCursor < value.length) {
+    const start = findNextPairedMarkupOpener(value, lowerValue, 'a', searchCursor)
+    if (start < 0) {
+      break
+    }
+    const end = findMobileMarkdownMarkupTagEnd(value, start + 2)
+    if (end < 0) {
+      if (end === -2) {
+        break
+      }
+      searchCursor = start + 2
+      continue
+    }
+    if (!isPairedMarkupOpener(value, start + 2, end)) {
+      searchCursor = end + 1
+      continue
+    }
+
+    const tag = value.slice(start, end + 1)
+    const href = attrValue(tag, 'href')
+    if (!href) {
+      searchCursor = end + 1
+      continue
+    }
+
+    if (closingStart < end + 1) {
+      closingStart = lowerValue.indexOf('</a>', end + 1)
+    }
+    if (closingStart < 0) {
+      break
+    }
+    const nestedStart = findNextPairedMarkupOpener(value, lowerValue, 'a', end + 1)
+    if (nestedStart >= 0 && nestedStart < closingStart) {
+      searchCursor = nestedStart
+      continue
+    }
+
+    const text = stripTags(value.slice(end + 1, closingStart))
+    output += value.slice(copyCursor, start)
+    output += href && text ? `[${text}](${href})` : text
+    copyCursor = closingStart + 4
+    searchCursor = copyCursor
+  }
+
+  return output + value.slice(copyCursor)
 }
 
 function normalizeInlineHtml(value: string): string {
-  return value
+  const imagesNormalized = value
     .replace(/<br\s*\/?>/gi, '\n')
-    .replace(/<img\b[^>]*>/gi, (tag) => attrValue(tag, 'alt') || 'image')
-    .replace(
-      /<a\b[^>]*href\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)[^>]*>([\s\S]*?)<\/a>/gi,
-      (tag, _href, label) => {
-        const href = attrValue(tag, 'href')
-        const text = stripTags(label)
-        return href && text ? `[${text}](${href})` : text
-      }
-    )
-    .replace(/<(strong|b)\b[^>]*>([\s\S]*?)<\/\1>/gi, (_tag, _name, inner) => {
-      const text = stripTags(inner)
-      return text ? `**${text}**` : ''
-    })
-    .replace(/<(em|i)\b[^>]*>([\s\S]*?)<\/\1>/gi, (_tag, _name, inner) => {
-      const text = stripTags(inner)
-      return text ? `*${text}*` : ''
-    })
-    .replace(/<(code|kbd)\b[^>]*>([\s\S]*?)<\/\1>/gi, (_tag, _name, inner) => {
-      const text = stripTags(inner)
-      return text ? `\`${text}\`` : ''
-    })
+    .replace(imageTagPattern, (tag) => attrValue(tag, 'alt') || 'image')
+
+  let next = normalizeAnchorTags(imagesNormalized)
+  next = replaceMobileMarkdownPairedMarkupTags(next, ['strong', 'b'], (_name, inner) => {
+    const text = stripTags(inner)
+    return text ? `**${text}**` : ''
+  })
+  next = replaceMobileMarkdownPairedMarkupTags(next, ['em', 'i'], (_name, inner) => {
+    const text = stripTags(inner)
+    return text ? `*${text}*` : ''
+  })
+  next = replaceMobileMarkdownPairedMarkupTags(next, ['code', 'kbd'], (_name, inner) => {
+    const text = stripTags(inner)
+    return text ? `\`${text}\`` : ''
+  })
+  return next
 }
 
 // Why: Markdown code is literal source, so it must bypass the HTML strip pass.
@@ -174,15 +270,19 @@ export function normalizeMobileMarkdownPreviewHtml(content: string): string {
   // Why: repository Markdown often uses small HTML islands for centered README
   // headers and badges. Preview mode should read like Markdown, while Source
   // mode remains the exact file bytes.
-  next = next.replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (_tag, level, inner) => {
-    const text = stripTags(normalizeInlineHtml(inner))
-    return text ? `\n${'#'.repeat(Number(level))} ${text}\n` : '\n'
-  })
-  next = next.replace(/<p\b[^>]*>([\s\S]*?)<\/p>/gi, (_tag, inner) => {
+  next = replaceMobileMarkdownPairedMarkupTags(
+    next,
+    ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+    (name, inner) => {
+      const text = stripTags(normalizeInlineHtml(inner))
+      return text ? `\n${'#'.repeat(Number(name.slice(1)))} ${text}\n` : '\n'
+    }
+  )
+  next = replaceMobileMarkdownPairedMarkupTags(next, ['p'], (_name, inner) => {
     const text = stripTags(normalizeInlineHtml(inner))
     return text ? `\n${text}\n` : '\n'
   })
-  next = next.replace(/<sub\b[^>]*>([\s\S]*?)<\/sub>/gi, (_tag, inner) =>
+  next = replaceMobileMarkdownPairedMarkupTags(next, ['sub'], (_name, inner) =>
     stripTags(normalizeInlineHtml(inner))
   )
   next = normalizeInlineHtml(next)

mobile/src/components/mobile-markdown-preview-tag-stripper.ts

@@ -0,0 +1,324 @@
+const knownMarkupTagNames = new Set(
+  `a abbr address area article aside audio b base bdi bdo blockquote body br button canvas caption cite code col colgroup data datalist dd del details dfn dialog div dl dt em embed fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head header hgroup hr html i iframe img input ins kbd label legend li link main map mark menu meta meter nav noscript object ol optgroup option output p picture pre progress q rp rt ruby s samp script search section select slot small source span strong style sub summary sup table tbody td template textarea tfoot th thead time title tr track u ul var video wbr fencedframe portal selectedcontent
+acronym applet basefont bgsound big blink center command content dir element font frame frameset isindex keygen listing marquee menuitem multicol nextid nobr noembed noframes noindex param plaintext rb rtc shadow spacer strike tt xmp
+animate animatemotion animatetransform circle clippath defs desc ellipse feblend fecolormatrix fecomponenttransfer fecomposite feconvolvematrix fediffuselighting fedisplacementmap fedistantlight fedropshadow feflood fefunca fefuncb fefuncg fefuncr fegaussianblur feimage femerge femergenode femorphology feoffset fepointlight fespecularlighting fespotlight fetile feturbulence filter foreignobject g hatch hatchpath image line lineargradient marker mask metadata mpath path pattern polygon polyline radialgradient rect discard set stop svg switch symbol text textpath tspan use view
+altglyph altglyphdef altglyphitem animatecolor cursor font-face font-face-format font-face-name font-face-src font-face-uri glyph glyphref hkern missing-glyph solidcolor vkern
+annotation annotation-xml maction math menclose merror mfenced mfrac mi mmultiscripts mn mo mover mpadded mphantom mprescripts mroot mrow ms mspace msqrt mstyle msub msubsup msup mtable mtd mtext mtr munder munderover semantics`.split(
+    /\s+/
+  )
+)
+
+function followsAttributeEquals(value: string, index: number): boolean {
+  let previous = index - 1
+  while (previous >= 0 && /\s/.test(value[previous] ?? '')) {
+    previous -= 1
+  }
+  return value[previous] === '='
+}
+
+export function findMobileMarkdownMarkupTagEnd(value: string, start: number): number {
+  let quote = ''
+  for (let index = start; index < value.length; index += 1) {
+    const char = value[index] ?? ''
+    if (quote) {
+      if (char === quote) {
+        quote = ''
+      }
+      continue
+    }
+    if ((char === '"' || char === "'") && followsAttributeEquals(value, index)) {
+      quote = char
+    } else if (char === '<') {
+      return -1
+    } else if (char === '>') {
+      return index
+    }
+  }
+  if (quote) {
+    for (let index = start; index < value.length; index += 1) {
+      const char = value[index] ?? ''
+      if (char === '<') {
+        return -1
+      }
+      if (char === '>') {
+        return index
+      }
+    }
+  }
+  return -2
+}
+
+function nextNestedMarkupCursor(value: string, start: number): number {
+  const nestedStart = value.indexOf('<', start + 1)
+  if (!followsAttributeEquals(value, nestedStart)) {
+    return nestedStart
+  }
+  const nestedEnd = findMobileMarkdownMarkupTagEnd(value, nestedStart + 1)
+  if (nestedEnd < 0) {
+    return nestedStart
+  }
+  return nestedEnd + 1 + Number(value[nestedEnd + 1] === '>')
+}
+
+function isMarkupNameStart(char: string): boolean {
+  const code = char.charCodeAt(0)
+  return (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+}
+
+const markupNameCharPattern = /^[A-Za-z0-9:-]$/
+
+function isMarkupNameChar(char: string): boolean {
+  return markupNameCharPattern.test(char)
+}
+
+function isPairedMarkupOpenerBoundary(char: string): boolean {
+  return char === '>' || /\s/.test(char)
+}
+
+export function isPairedMarkupOpener(value: string, nameEnd: number, end: number): boolean {
+  if (!isPairedMarkupOpenerBoundary(value[nameEnd] ?? '')) {
+    return false
+  }
+  let lastContent = end - 1
+  while (lastContent >= nameEnd && /\s/.test(value[lastContent] ?? '')) {
+    lastContent -= 1
+  }
+  return value[lastContent] !== '/'
+}
+
+export function findNextPairedMarkupOpener(
+  value: string,
+  lowerValue: string,
+  name: string,
+  cursor: number
+): number {
+  let start = lowerValue.indexOf(`<${name}`, cursor)
+  while (start >= 0) {
+    const nameEnd = start + name.length + 1
+    const end = findMobileMarkdownMarkupTagEnd(value, nameEnd)
+    if (end >= 0 && isPairedMarkupOpener(value, nameEnd, end)) {
+      return start
+    }
+    start = lowerValue.indexOf(`<${name}`, start + name.length + 1)
+  }
+  return -1
+}
+
+export function replaceMobileMarkdownPairedMarkupTags(
+  value: string,
+  tagNames: readonly string[],
+  replacement: (name: string, inner: string) => string
+): string {
+  const lowerValue = value.toLowerCase()
+  const activeNames = new Set(tagNames)
+  const nextStarts = new Map<string, number>()
+  const nextClosingStarts = new Map<string, number>()
+  let output = ''
+  let copyCursor = 0
+  let searchCursor = 0
+
+  while (activeNames.size > 0 && searchCursor < value.length) {
+    let name = ''
+    let start = -1
+    for (const candidate of activeNames) {
+      let candidateStart = nextStarts.get(candidate) ?? -1
+      if (candidateStart < searchCursor) {
+        candidateStart = findNextPairedMarkupOpener(value, lowerValue, candidate, searchCursor)
+        if (candidateStart < 0) {
+          activeNames.delete(candidate)
+          nextStarts.delete(candidate)
+          continue
+        }
+        nextStarts.set(candidate, candidateStart)
+      }
+      if (start < 0 || candidateStart < start) {
+        name = candidate
+        start = candidateStart
+      }
+    }
+    if (start < 0) {
+      break
+    }
+
+    const nameEnd = start + name.length + 1
+    nextStarts.delete(name)
+    const end = findMobileMarkdownMarkupTagEnd(value, nameEnd)
+
+    const closingTag = `</${name}>`
+    let closingStart = nextClosingStarts.get(name) ?? -1
+    if (closingStart < end + 1) {
+      closingStart = lowerValue.indexOf(closingTag, end + 1)
+      nextClosingStarts.set(name, closingStart)
+    }
+    if (closingStart < 0) {
+      // No later opener of this name can match once its final closer is behind us.
+      activeNames.delete(name)
+      searchCursor = start + 1
+      continue
+    }
+    const nestedStart = findNextPairedMarkupOpener(value, lowerValue, name, end + 1)
+    if (nestedStart >= 0 && nestedStart < closingStart) {
+      nextStarts.set(name, nestedStart)
+      searchCursor = nestedStart
+      continue
+    }
+
+    output += value.slice(copyCursor, start)
+    output += replacement(name, value.slice(end + 1, closingStart))
+    copyCursor = closingStart + closingTag.length
+    searchCursor = copyCursor
+  }
+
+  return output + value.slice(copyCursor)
+}
+
+function isPlaceholderSuffix(value: string, start: number, end: number): boolean {
+  let lastNonSpace = ''
+  for (let index = start; index < end; index += 1) {
+    const char = value[index] ?? ''
+    if (char === '=') {
+      return false
+    }
+    if (!/\s/.test(char)) {
+      lastNonSpace = char
+    }
+  }
+  return lastNonSpace !== '/'
+}
+
+function closingMarkupTagNames(value: string): Set<string> {
+  const names = new Set<string>()
+  let cursor = 0
+  while (cursor < value.length) {
+    const start = value.indexOf('<', cursor)
+    if (start < 0) {
+      return names
+    }
+    const end = findMobileMarkdownMarkupTagEnd(value, start + 1)
+    if (end < 0) {
+      if (end === -2) {
+        return names
+      }
+      cursor = nextNestedMarkupCursor(value, start)
+      continue
+    }
+    if (value[start + 1] !== '/' || !isMarkupNameStart(value[start + 2] ?? '')) {
+      cursor = end + 1
+      continue
+    }
+    let nameEnd = start + 3
+    while (isMarkupNameChar(value[nameEnd] ?? '')) {
+      nameEnd += 1
+    }
+    let boundary = nameEnd
+    while (/\s/.test(value[boundary] ?? '')) {
+      boundary += 1
+    }
+    if (boundary === end) {
+      names.add(value.slice(start + 2, nameEnd).toLowerCase())
+    }
+    cursor = end + 1
+  }
+  return names
+}
+
+export function stripMobileMarkdownMarkupTags(value: string): string {
+  let output = ''
+  let cursor = 0
+  const closingTagNames = closingMarkupTagNames(value)
+  while (cursor < value.length) {
+    const start = value.indexOf('<', cursor)
+    if (start < 0) {
+      return output + value.slice(cursor)
+    }
+    output += value.slice(cursor, start)
+
+    const isClosing = value[start + 1] === '/'
+    const nameStart = start + (isClosing ? 2 : 1)
+    if (!isMarkupNameStart(value[nameStart] ?? '')) {
+      output += '<'
+      cursor = start + 1
+      continue
+    }
+
+    let nameEnd = nameStart + 1
+    while (isMarkupNameChar(value[nameEnd] ?? '')) {
+      nameEnd += 1
+    }
+
+    const previousChar = value[start - 1]
+    const name = value.slice(nameStart, nameEnd)
+    const lowerName = name.toLowerCase()
+    const end = findMobileMarkdownMarkupTagEnd(value, nameEnd)
+    if (end < 0) {
+      if (end === -2) {
+        return output + value.slice(start)
+      }
+      const nestedStart = value.indexOf('<', nameEnd)
+      const isNestedGeneric =
+        Boolean(previousChar && /\w/.test(previousChar)) &&
+        !isClosing &&
+        !/[-:]/.test(name) &&
+        !knownMarkupTagNames.has(lowerName) &&
+        !closingTagNames.has(lowerName)
+      if (isNestedGeneric && nestedStart >= 0) {
+        output += value.slice(start, nestedStart)
+        cursor = nestedStart
+        continue
+      }
+      cursor = nextNestedMarkupCursor(value, start)
+      continue
+    }
+
+    const suffixStart = value[nameEnd] ?? ''
+    const isKnownMarkup = knownMarkupTagNames.has(lowerName)
+    const canPreserveOpening = !isClosing && !closingTagNames.has(lowerName)
+    const isAutolink =
+      /^<[A-Za-z][A-Za-z0-9+.-]+:[^\s<>]*>$/.test(value.slice(start, end + 1)) &&
+      nameEnd < end &&
+      canPreserveOpening
+    const isComparisonAngleText =
+      name.length === 1 &&
+      suffixStart === '=' &&
+      Boolean(previousChar && /\w/.test(previousChar)) &&
+      !/\w/.test(value[start - 2] ?? '') &&
+      canPreserveOpening
+    const isGeneric =
+      Boolean(previousChar && /\w/.test(previousChar)) &&
+      canPreserveOpening &&
+      nameEnd === end &&
+      !/[-:]/.test(name) &&
+      !isKnownMarkup
+    const isTypeParameter =
+      canPreserveOpening && nameEnd === end && /^[A-Z]$/.test(name) && !isKnownMarkup
+    const tagSuffix = value.slice(nameEnd, end)
+    const hasGenericDefault =
+      /^\s*=/.test(tagSuffix) || /^\s*(?:extends\b|,)[\s\S]*=/.test(tagSuffix)
+    const isGenericDefault =
+      Boolean(previousChar && /\w/.test(previousChar)) &&
+      canPreserveOpening &&
+      /^[A-Z][A-Za-z0-9]*$/.test(name) &&
+      !isKnownMarkup &&
+      hasGenericDefault &&
+      !/\/\s*$/.test(tagSuffix)
+    const isUnpairedPlaceholder =
+      canPreserveOpening &&
+      !isKnownMarkup &&
+      isPlaceholderSuffix(value, nameEnd, end) &&
+      (!name.includes('-') || tagSuffix.trim().length === 0) &&
+      !name.includes(':')
+
+    if (
+      isAutolink ||
+      isComparisonAngleText ||
+      isGeneric ||
+      isTypeParameter ||
+      isGenericDefault ||
+      isUnpairedPlaceholder
+    ) {
+      output += value.slice(start, end + 1)
+    }
+    cursor = end + 1
+  }
+  return output
+}

mobile/src/mock-server-session-tabs-fixture.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import type { WebSocket } from 'ws'
+import {
+  handleRequest,
+  type RpcRequest,
+  type RpcResponse
+} from '../scripts/mock-server-rpc-handlers'
+
+function callRpc(method: string, params?: Record<string, unknown>): RpcResponse {
+  let response: RpcResponse | undefined
+  const request: RpcRequest = { id: 'request-1', method, ...(params ? { params } : {}) }
+  handleRequest(
+    request,
+    (nextResponse) => {
+      response = nextResponse
+    },
+    {} as WebSocket
+  )
+  expect(response).toBeDefined()
+  return response!
+}
+
+function listSessionTabs(worktree: string): RpcResponse {
+  return callRpc('session.tabs.list', { worktree })
+}
+
+describe('mock server session tabs fixture', () => {
+  it('returns a contract-complete terminal surface for the requested worktree', () => {
+    const response = listSessionTabs('id:repo-1::worktree-1')
+
+    expect(response.result).toEqual({
+      worktree: 'repo-1::worktree-1',
+      publicationEpoch: expect.stringMatching(/^mock-server:/),
+      snapshotVersion: 1,
+      activeGroupId: 'group-1',
+      activeTabId: 'tab-1::f47ac10b-58cc-4372-a567-0e02b2c3d479',
+      activeTabType: 'terminal',
+      tabGroups: [
+        {
+          id: 'group-1',
+          activeTabId: 'tab-1',
+          tabOrder: ['tab-1'],
+          recentTabIds: ['tab-1']
+        }
+      ],
+      tabs: [
+        {
+          type: 'terminal',
+          id: 'tab-1::f47ac10b-58cc-4372-a567-0e02b2c3d479',
+          title: 'zsh',
+          parentTabId: 'tab-1',
+          leafId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+          status: 'ready',
+          terminal: 'term-1',
+          isActive: true
+        }
+      ]
+    })
+  })
+
+  it('passes a bare worktree selector through unprefixed', () => {
+    const response = listSessionTabs('repo-1::worktree-1')
+
+    expect((response.result as { worktree: string }).worktree).toBe('repo-1::worktree-1')
+  })
+
+  it('falls back to the same worktree terminal.list uses when no selector is sent', () => {
+    const terminals = callRpc('terminal.list').result as {
+      terminals: { worktreeId: string }[]
+    }
+    const expected = terminals.terminals[0]?.worktreeId
+    expect(expected).toBeTruthy()
+
+    const tabs = callRpc('session.tabs.list').result as { worktree: string }
+    expect(tabs.worktree).toBe(expected)
+  })
+})

mobile/src/notifications/mobile-notifications.ts

@@ -15,9 +15,12 @@ import {
 } from './local-notification-scheduling'
 import {
   adoptNotificationEpoch,
+  catchUpWatermarkSeq,
   enqueueHostDelivery,
   getHostNotificationSession,
+  quarantineCatchUpWatermark,
   releaseQueuedShowNotificationId,
+  resolveCatchUpQuarantine,
   saveWatermark,
   seedWatermarkFromStorage,
   seenKeyForEvent,
@@ -68,7 +71,10 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin
           releaseQueuedShowNotificationId(session, event.notificationId)
         }
       }
-    })
+      // Why swallowed: the caller is an un-awaited handler, so a rejected show would
+      // surface as an unhandled rejection (a RN redbox) instead of being retried by
+      // the next catch-up — which is now possible, since `seen` is marked after the show.
+    }).catch(() => {})
   }
 
   async function deliverLive(
@@ -76,87 +82,127 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin
     event: NotificationEvent | DismissNotificationEvent
   ): Promise<void> {
     adoptNotificationEpoch(session, hostId, event.notificationEpoch)
-    // Why (#8129): mark seen on the live path too, so a later replay of an already-pushed id dedups instead of double-pushing.
-    const key = seenKeyForEvent(event)
-    if (key) {
-      session.seen.add(key)
-    }
+    const epochAtDelivery = session.lastDeliveredEpoch
     if (type === 'notification') {
       await showLocalNotification(event as NotificationEvent, hostId)
     } else {
       await dismissLocalNotification(event as DismissNotificationEvent, hostId)
     }
+    // Why after the await, exactly like the watermark below: `seen` asserts this event
+    // reached the user (#8129). Marked before, a rejected show leaves the key behind and
+    // every later replay is dropped as a duplicate — loss the quarantine cannot recover,
+    // since the first event to drain a batch lifts it past the one never shown.
+    const key = seenKeyForEvent(event)
+    // A mid-flight epoch adoption already cleared the counter lifetime this key indexes.
+    if (key && session.lastDeliveredEpoch === epochAtDelivery) {
+      session.seen.add(key)
+    }
     // Why after the await (#8591): the watermark is a promise that everything up
     // to this seq has been shown. Advancing it before the local notification lands
     // means a process death in between silently drops it — the next launch asks the
     // desktop for seq greater than one the user never saw.
     if (event.notificationSeq != null && event.notificationSeq > session.lastDeliveredSeq) {
       session.lastDeliveredSeq = event.notificationSeq
-      // Persisted as a pair: a seq is only trustworthy alongside the epoch it indexes.
+      // Why clamped: while a failed catch-up's range is still unrecovered, persisting
+      // the live seq would let the next catch-up ask from above the gap and the desktop
+      // would cut it. resolveCatchUpQuarantine writes the held-back value on success.
       void saveWatermark(hostId, {
-        seq: session.lastDeliveredSeq,
+        seq: catchUpWatermarkSeq(session),
         epoch: session.lastDeliveredEpoch
       })
     }
   }
 
+  // Claimed inline rather than via queueDelivery: the batch is already one queue
+  // entry, and re-enqueueing per item is what let a live event cut in.
+  async function deliverMissedEvent(
+    event: NotificationEvent | DismissNotificationEvent
+  ): Promise<void> {
+    // No pre-marking here either: deliverLive marks the key once the show lands.
+    const key = seenKeyForEvent(event)
+    if (key && session.seen.has(key)) {
+      return
+    }
+    if (event.type === 'notification') {
+      if (!shouldQueueShowForNotificationId(session, event.notificationId)) {
+        return
+      }
+      try {
+        await deliverLive('notification', event)
+      } finally {
+        releaseQueuedShowNotificationId(session, event.notificationId)
+      }
+      return
+    }
+    if (event.type === 'dismiss') {
+      await deliverLive('dismiss', event)
+    }
+  }
+
   // Why: desktop cuts by seq > lastSeenSeq, so re-fetching from the watermark is idempotent (session.seen guards residual overlap).
   async function fetchMissed(): Promise<void> {
     if (disposed) {
       return
     }
+    // Captured before the request: everything at or below it is known delivered, so
+    // it is the floor the watermark falls back to if this catch-up never completes.
+    const askFrom = catchUpWatermarkSeq(session)
     const missed = await client
       .sendRequest('notifications.getMissedSince', {
-        lastSeenSeq: session.lastDeliveredSeq,
+        lastSeenSeq: askFrom,
         // Why: sending the epoch lets the desktop reject a watermark from a counter
         // it no longer has and return the whole retained buffer instead of nothing.
         ...(session.lastDeliveredEpoch != null ? { epoch: session.lastDeliveredEpoch } : {})
       })
       .then((response) => {
         if (!response.ok) {
-          return []
+          return null
         }
         const result = response.result as { notifications?: unknown[]; epoch?: string } | undefined
         adoptNotificationEpoch(session, hostId, result?.epoch)
         return Array.isArray(result?.notifications) ? result.notifications : []
       })
-      .catch(() => [])
+      .catch(() => null)
+    if (missed == null) {
+      // Why quarantine rather than retry: the range this catch-up abandoned stays
+      // unrecovered until SOME later one succeeds, and a live seq persisting past it
+      // meanwhile would make the desktop cut it forever.
+      quarantineCatchUpWatermark(session, hostId, askFrom)
+      return
+    }
     // Why the whole batch is ONE queue entry (#8591): awaiting per event returns to
     // the event loop between replays, so a live seq 11 slots into the chain between
     // seq 6 and 7 and persists a watermark past a notification still unshown. Why the
     // request stays OUTSIDE the queue: sendRequest waits up to 30s, and holding the
     // chain for that would stall live delivery on a slow link.
     await enqueueHostDelivery(session, async () => {
-      for (const raw of missed) {
-        // Re-checked per event: the batch can start before a teardown and still be
-        // draining after it, and a torn-down host must stop pushing.
-        if (disposed) {
-          return
-        }
-        const event = raw as NotificationEvent | DismissNotificationEvent
-        const key = seenKeyForEvent(event)
-        if (key && session.seen.has(key)) {
-          continue
-        }
-        if (key) {
-          session.seen.add(key)
-        }
-        // Claimed inline rather than via queueDelivery: the batch is already one
-        // queue entry, and re-enqueueing per item is what let a live event cut in.
-        if (event.type === 'notification') {
-          if (!shouldQueueShowForNotificationId(session, event.notificationId)) {
-            continue
+      // Advances only past events this batch settled, so a teardown or a failing show
+      // quarantines the true contiguous point instead of the range it never reached.
+      let contiguousSeq = askFrom
+      let drained = false
+      try {
+        for (const raw of missed) {
+          // Re-checked per event: the batch can start before a teardown and still be
+          // draining after it, and a torn-down host must stop pushing.
+          if (disposed) {
+            return
           }
-          try {
-            await deliverLive('notification', event)
-          } finally {
-            releaseQueuedShowNotificationId(session, event.notificationId)
-          }
-        } else if (event.type === 'dismiss') {
-          await deliverLive('dismiss', event)
+          const event = raw as NotificationEvent | DismissNotificationEvent
+          await deliverMissedEvent(event)
+          contiguousSeq = event.notificationSeq ?? contiguousSeq
+        }
+        drained = true
+      } finally {
+        if (drained) {
+          resolveCatchUpQuarantine(session, hostId)
+        } else {
+          quarantineCatchUpWatermark(session, hostId, contiguousSeq)
         }
       }
-    })
+      // Why swallowed here: the `finally` above already recorded the contiguous point,
+      // and the only caller is an un-awaited 'ready' continuation — letting a failed
+      // show escape turns every one into an unhandled rejection (a RN redbox).
+    }).catch(() => {})
   }
 
   seedWatermarkFromStorage(session, hostId)

mobile/src/notifications/notification-catchup-failure-quarantine.test.ts

@@ -0,0 +1,316 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Notifications from 'expo-notifications'
+import { subscribeToDesktopNotifications } from './mobile-notifications'
+import { resetHostNotificationSessionsForTests } from './notification-reconnect-catchup'
+import type { RpcClient } from '../transport/rpc-client'
+import { loadPushNotificationsEnabled } from '../storage/preferences'
+
+vi.mock('expo-notifications', () => ({
+  AndroidImportance: { HIGH: 'high' },
+  setNotificationChannelAsync: vi.fn(),
+  getPermissionsAsync: vi.fn(),
+  requestPermissionsAsync: vi.fn(),
+  scheduleNotificationAsync: vi.fn(),
+  dismissNotificationAsync: vi.fn()
+}))
+
+vi.mock('react-native', () => ({
+  Platform: { OS: 'ios', Version: 18 }
+}))
+
+const WATERMARK_KEY = 'orca:mobileNotificationsWatermark:host-1'
+const storage = new Map<string, string>()
+
+vi.mock('@react-native-async-storage/async-storage', () => ({
+  default: {
+    getItem: vi.fn(async (key: string) => storage.get(key) ?? null),
+    setItem: vi.fn(async (key: string, value: string) => {
+      storage.set(key, value)
+    })
+  }
+}))
+
+vi.mock('../storage/preferences', () => ({
+  loadPushNotificationsEnabled: vi.fn()
+}))
+
+function flushAsync(): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, 10)
+  })
+}
+
+function persistedSeq(): number {
+  return (JSON.parse(storage.get(WATERMARK_KEY) ?? '{}') as { seq?: number }).seq ?? 0
+}
+
+type MissedOutcome =
+  | { kind: 'reject' }
+  | { kind: 'notOk' }
+  | { kind: 'ok'; notifications: unknown[] }
+  // Rejects only once `settle()` is called, so a live event can land mid-request.
+  | { kind: 'heldReject' }
+
+function makeHostClient() {
+  let onData: ((data: unknown) => void) | null = null
+  const askedFrom: number[] = []
+  let outcome: MissedOutcome = { kind: 'ok', notifications: [] }
+  let releaseHeld: (() => void) | null = null
+  const client = {
+    subscribe: vi.fn((_m: string, _p: unknown, cb: (data: unknown) => void) => {
+      onData = cb
+      return vi.fn(() => {
+        onData = null
+      })
+    }),
+    getState: vi.fn(() => 'connected'),
+    sendRequest: vi.fn(async (method: string, params: unknown = {}) => {
+      if (method !== 'notifications.getMissedSince') {
+        return { ok: true, result: undefined } as never
+      }
+      askedFrom.push((params as { lastSeenSeq: number }).lastSeenSeq)
+      if (outcome.kind === 'heldReject') {
+        await new Promise<void>((resolve) => {
+          releaseHeld = resolve
+        })
+        throw new Error('socket closed')
+      }
+      if (outcome.kind === 'reject') {
+        throw new Error('socket closed')
+      }
+      if (outcome.kind === 'notOk') {
+        return { ok: false, error: { message: 'timeout' } } as never
+      }
+      return { ok: true, result: { notifications: outcome.notifications } } as never
+    })
+  }
+  return {
+    client: client as unknown as RpcClient,
+    get onData() {
+      return onData
+    },
+    askedFrom,
+    setOutcome(next: MissedOutcome) {
+      outcome = next
+    },
+    settleHeld() {
+      releaseHeld?.()
+    }
+  }
+}
+
+function notification(seq: number) {
+  return {
+    type: 'notification',
+    title: `m${seq}`,
+    body: 'b',
+    notificationId: `agent:${seq}`,
+    notificationSeq: seq
+  }
+}
+
+describe('#8591 catch-up failure quarantines the watermark', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    storage.clear()
+    resetHostNotificationSessionsForTests()
+    vi.mocked(loadPushNotificationsEnabled).mockResolvedValue(true)
+    vi.mocked(Notifications.getPermissionsAsync).mockResolvedValue({
+      status: 'granted',
+      canAskAgain: true
+    } as never)
+    vi.mocked(Notifications.scheduleNotificationAsync).mockResolvedValue('sched-1')
+    vi.mocked(Notifications.dismissNotificationAsync).mockResolvedValue(undefined)
+  })
+
+  it('keeps asking from the abandoned range until a catch-up actually succeeds', async () => {
+    // The phone was offline while seqs 6-7 dispatched. The catch-up that would have
+    // replayed them dies (socket close / timeout / ok:false), and live traffic keeps
+    // flowing. If a live seq is allowed to persist past 6-7, the desktop cuts by
+    // `seq > lastSeenSeq` on the next catch-up and they are gone for good — and the
+    // window stays open until some catch-up succeeds, not for one round trip.
+    storage.set(WATERMARK_KEY, JSON.stringify({ seq: 5, epoch: 'epoch-1' }))
+    const host = makeHostClient()
+    host.setOutcome({ kind: 'reject' })
+
+    subscribeToDesktopNotifications(host.client, 'host-1')
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+    expect(host.askedFrom).toEqual([5])
+
+    host.onData?.({ ...notification(11), notificationEpoch: 'epoch-1' })
+    await flushAsync()
+    expect(persistedSeq()).toBe(5)
+
+    // Second catch-up also fails; the gap is still open.
+    host.setOutcome({ kind: 'notOk' })
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+    host.onData?.({ ...notification(12), notificationEpoch: 'epoch-1' })
+    await flushAsync()
+    expect(host.askedFrom).toEqual([5, 5])
+    expect(persistedSeq()).toBe(5)
+
+    // Third succeeds and replays the abandoned range.
+    host.setOutcome({ kind: 'ok', notifications: [notification(6), notification(7)] })
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+
+    expect(host.askedFrom).toEqual([5, 5, 5])
+    const titles = vi
+      .mocked(Notifications.scheduleNotificationAsync)
+      .mock.calls.map((call) => (call[0] as { content: { title: string } }).content.title)
+    // Exact, not arrayContaining: a duplicate here is the double-push `seen` prevents.
+    // m11/m12 are the live events that kept flowing while the gap stayed open.
+    expect(titles).toEqual(['m11', 'm12', 'm6', 'm7'])
+
+    // Only now may the watermark move past the recovered range.
+    expect(persistedSeq()).toBe(12)
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+    expect(host.askedFrom).toEqual([5, 5, 5, 12])
+  })
+
+  it('rolls back a watermark a live event stored while the catch-up was in flight', async () => {
+    // getMissedSince waits up to 30s, so live traffic routinely persists during it.
+    // Clamping only writes made AFTER the failure leaves that higher seq on disk, and
+    // the next launch reads it back and resumes past the range this catch-up abandoned.
+    storage.set(WATERMARK_KEY, JSON.stringify({ seq: 5, epoch: 'epoch-1' }))
+    const host = makeHostClient()
+    host.setOutcome({ kind: 'heldReject' })
+
+    subscribeToDesktopNotifications(host.client, 'host-1')
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+    expect(host.askedFrom).toEqual([5])
+
+    host.onData?.({ ...notification(11), notificationEpoch: 'epoch-1' })
+    await flushAsync()
+    expect(persistedSeq()).toBe(11)
+
+    host.settleHeld()
+    await flushAsync()
+    expect(persistedSeq()).toBe(5)
+  })
+
+  it('quarantines at the last replayed seq when a teardown cuts the batch short', async () => {
+    // The batch can start before a teardown and still be draining after it, so the
+    // events past the interruption were never shown. A live seq arriving on the next
+    // connection must not persist over them.
+    storage.set(WATERMARK_KEY, JSON.stringify({ seq: 5, epoch: 'epoch-1' }))
+    const host = makeHostClient()
+    host.setOutcome({
+      kind: 'ok',
+      notifications: [notification(6), notification(7), notification(8)]
+    })
+
+    let unsubscribe: (() => void) | null = null
+    vi.mocked(Notifications.scheduleNotificationAsync).mockImplementation(async (request) => {
+      if ((request as { content: { title: string } }).content.title === 'm6') {
+        unsubscribe?.()
+      }
+      return 'sched-1'
+    })
+
+    unsubscribe = subscribeToDesktopNotifications(host.client, 'host-1')
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+
+    const titles = vi
+      .mocked(Notifications.scheduleNotificationAsync)
+      .mock.calls.map((call) => (call[0] as { content: { title: string } }).content.title)
+    expect(titles).toEqual(['m6'])
+
+    // A fresh subscription on the same module-scope session takes a live seq 20 before
+    // its own catch-up, then resumes from 6 rather than from 20.
+    vi.mocked(Notifications.scheduleNotificationAsync).mockResolvedValue('sched-1')
+    const host2 = makeHostClient()
+    host2.setOutcome({ kind: 'ok', notifications: [notification(7), notification(8)] })
+    subscribeToDesktopNotifications(host2.client, 'host-1')
+    host2.onData?.({ ...notification(20), notificationEpoch: 'epoch-1' })
+    await flushAsync()
+    expect(persistedSeq()).toBe(6)
+
+    host2.onData?.({ type: 'ready', subscriptionId: 'sub-2', epoch: 'epoch-1' })
+    await flushAsync()
+
+    expect(host2.askedFrom).toEqual([6])
+    expect(
+      vi
+        .mocked(Notifications.scheduleNotificationAsync)
+        .mock.calls.map((call) => (call[0] as { content: { title: string } }).content.title)
+    ).toEqual(['m6', 'm20', 'm7', 'm8'])
+    expect(persistedSeq()).toBe(20)
+  })
+
+  it('re-shows a replay whose show threw, instead of dropping it as already seen', async () => {
+    // The quarantine only holds the RANGE. If the failing event is also marked seen,
+    // the next catch-up re-fetches it and the dedup guard drops it — the banner is
+    // never shown, and the first later event to drain the batch lifts the quarantine
+    // past it. Silent loss with the watermark looking healthy.
+    storage.set(WATERMARK_KEY, JSON.stringify({ seq: 5, epoch: 'epoch-1' }))
+    const host = makeHostClient()
+    host.setOutcome({ kind: 'ok', notifications: [notification(6), notification(7)] })
+
+    let failNext = true
+    vi.mocked(Notifications.scheduleNotificationAsync).mockImplementation(async (request) => {
+      const title = (request as { content: { title: string } }).content.title
+      if (title === 'm6' && failNext) {
+        failNext = false
+        throw new Error('scheduling rejected')
+      }
+      return 'sched-1'
+    })
+
+    subscribeToDesktopNotifications(host.client, 'host-1')
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+    expect(persistedSeq()).toBe(5)
+
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+
+    const titles = vi
+      .mocked(Notifications.scheduleNotificationAsync)
+      .mock.calls.map((call) => (call[0] as { content: { title: string } }).content.title)
+    expect(titles).toEqual(['m6', 'm6', 'm7'])
+    expect(host.askedFrom).toEqual([5, 5])
+    expect(persistedSeq()).toBe(7)
+  })
+
+  it('re-shows a live event whose show threw, instead of dropping it as already seen', async () => {
+    // The same hole without any catch-up failing: the live path marks seen before the
+    // show, so a rejected show leaves the key behind while the watermark stays put.
+    // The next catch-up dutifully re-fetches the seq and the guard eats it.
+    storage.set(WATERMARK_KEY, JSON.stringify({ seq: 5, epoch: 'epoch-1' }))
+    const host = makeHostClient()
+    host.setOutcome({ kind: 'ok', notifications: [] })
+
+    let failNext = true
+    vi.mocked(Notifications.scheduleNotificationAsync).mockImplementation(async () => {
+      if (failNext) {
+        failNext = false
+        throw new Error('scheduling rejected')
+      }
+      return 'sched-1'
+    })
+
+    subscribeToDesktopNotifications(host.client, 'host-1')
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+
+    host.onData?.({ ...notification(6), notificationEpoch: 'epoch-1' })
+    await flushAsync()
+    expect(persistedSeq()).toBe(5)
+
+    host.setOutcome({ kind: 'ok', notifications: [notification(6)] })
+    host.onData?.({ type: 'ready', subscriptionId: 'sub-1', epoch: 'epoch-1' })
+    await flushAsync()
+
+    const titles = vi
+      .mocked(Notifications.scheduleNotificationAsync)
+      .mock.calls.map((call) => (call[0] as { content: { title: string } }).content.title)
+    expect(titles).toEqual(['m6', 'm6'])
+    expect(persistedSeq()).toBe(6)
+  })
+})

mobile/src/notifications/notification-reconnect-catchup.ts

@@ -135,6 +135,9 @@ export type HostNotificationSession = {
   // Counter lifetime lastDeliveredSeq belongs to; null until one is known. A
   // mismatch on reconnect means the desktop restarted and the watermark is void.
   lastDeliveredEpoch: string | null
+  // Highest seq known delivered CONTIGUOUSLY, frozen here while a catch-up is
+  // outstanding; null when none has failed. See quarantineCatchUpWatermark.
+  catchUpQuarantineSeq: number | null
   seen: ReturnType<typeof createSeenNotificationGuard>
   // False only until the host's first subscription reaches 'ready' — a true cold open.
   connectedBefore: boolean
@@ -161,6 +164,7 @@ export function getHostNotificationSession(hostId: string): HostNotificationSess
     session = {
       lastDeliveredSeq: 0,
       lastDeliveredEpoch: null,
+      catchUpQuarantineSeq: null,
       seen: createSeenNotificationGuard(),
       connectedBefore: false,
       hadStoredWatermark: false,
@@ -239,6 +243,55 @@ export function resetHostNotificationSessionsForTests(): void {
   sessionsByHost.clear()
 }
 
+/**
+ * Freeze the catch-up watermark at the last seq known delivered contiguously,
+ * after a catch-up that did not complete.
+ *
+ * Why: live delivery advances lastDeliveredSeq unconditionally, so an abandoned
+ * catch-up otherwise lets the NEXT one ask from above the range it gave up on —
+ * the desktop cuts by seq, so those notifications are never replayed and are
+ * gone. Lowest wins: an earlier failure's gap is still open.
+ */
+export function quarantineCatchUpWatermark(
+  session: HostNotificationSession,
+  hostId: string,
+  contiguousSeq: number
+): void {
+  session.catchUpQuarantineSeq =
+    session.catchUpQuarantineSeq == null
+      ? contiguousSeq
+      : Math.min(session.catchUpQuarantineSeq, contiguousSeq)
+  // Why re-persist: a live event delivered while the catch-up was still in flight
+  // already stored a seq above the gap. Clamping only later writes would leave that
+  // value on disk, so a restart still resumes past the abandoned range.
+  void saveWatermark(hostId, {
+    seq: catchUpWatermarkSeq(session),
+    epoch: session.lastDeliveredEpoch
+  })
+}
+
+/** Lift the quarantine once a catch-up completes, persisting what it held back. */
+export function resolveCatchUpQuarantine(session: HostNotificationSession, hostId: string): void {
+  if (session.catchUpQuarantineSeq == null) {
+    return
+  }
+  session.catchUpQuarantineSeq = null
+  void saveWatermark(hostId, {
+    seq: session.lastDeliveredSeq,
+    epoch: session.lastDeliveredEpoch
+  })
+}
+
+/**
+ * The seq a catch-up may ask from and the highest seq safe to persist — the live
+ * watermark, clamped to any open gap.
+ */
+export function catchUpWatermarkSeq(session: HostNotificationSession): number {
+  return session.catchUpQuarantineSeq == null
+    ? session.lastDeliveredSeq
+    : Math.min(session.catchUpQuarantineSeq, session.lastDeliveredSeq)
+}
+
 // Why (#8591): the desktop's seq counter restarts at 0 every launch, so a watermark
 // from a previous lifetime indexes a counter that no longer exists. Comparing it
 // against the fresh counter makes `lastSeenSeq >= seq` true for everything and
@@ -262,6 +315,8 @@ export function adoptNotificationEpoch(
   // counter re-issues those same low seqs, so a stale `seq:1` would silently drop
   // the new counter's first bell. The dedup window belongs to one counter lifetime.
   session.seen.clear()
+  // The quarantined gap indexed the dead counter; the watermark it guarded is gone too.
+  session.catchUpQuarantineSeq = null
   session.lastDeliveredEpoch = epoch
   void saveWatermark(hostId, { seq: 0, epoch })
 }

mobile/src/session/ai-vault-resume-launch.test.ts

@@ -8,9 +8,9 @@ import {
   readMobileRuntimeHostPlatform,
   readMobileRuntimeTerminalWindowsShell,
   resolveMobileAiVaultResumePlatform,
-  resumeAiVaultSessionInTerminal,
-  RESUME_RPC_TIMEOUT_MS
+  resumeAiVaultSessionInTerminal
 } from './ai-vault-resume-launch'
+import { RESUME_RPC_TIMEOUT_MS } from './ai-vault-resume-preparation'
 
 function session(overrides: Partial<AiVaultSession> = {}): AiVaultSession {
   return {

mobile/src/session/ai-vault-resume-launch.ts

@@ -4,10 +4,7 @@ import {
   buildAiVaultResumeShellCommand,
   realHomeCodexResumeEnvDeletion
 } from '../../../src/shared/ai-vault-types'
-import {
-  isAiVaultPrepareSessionResumeUnavailableError,
-  isLegacySharedCodexHome
-} from '../../../src/shared/ai-vault-resume-preparation'
+import { RESUME_RPC_TIMEOUT_MS } from './ai-vault-resume-preparation'
 import { isResumableTuiAgent } from '../../../src/shared/agent-session-resume'
 import type { SleepingAgentLaunchConfig } from '../../../src/shared/agent-session-resume'
 import { buildAgentResumeStartupPlan } from '../../../src/shared/tui-agent-startup'
@@ -167,43 +164,6 @@ function normalizeMobileAiVaultResumeCommandOverrides(
   return normalized
 }
 
-// Why: without an explicit timeout, a socket drop mid-resume parks the request
-// on the reconnect waiter for the full reconnect budget, pinning the spinner.
-export const RESUME_RPC_TIMEOUT_MS = 30_000
-
-export async function prepareMobileAiVaultSessionResume(
-  client: Pick<RpcClient, 'sendRequest'>,
-  session: AiVaultSession
-): Promise<AiVaultSession> {
-  if (session.agent !== 'codex' || !isLegacySharedCodexHome(session.codexHome)) {
-    return session
-  }
-  const response = await client.sendRequest(
-    'aiVault.prepareSessionResume',
-    {
-      agent: session.agent,
-      filePath: session.filePath,
-      codexHome: session.codexHome,
-      executionHostId: session.executionHostId
-    },
-    { timeoutMs: RESUME_RPC_TIMEOUT_MS }
-  )
-  if (!response.ok) {
-    if (isAiVaultPrepareSessionResumeUnavailableError(response.error)) {
-      // Why: older hosts cannot prepare, but their shared home still supports the legacy resume path.
-      return session
-    }
-    throw new Error(
-      response.error?.message || 'Could not prepare this legacy Codex session. Retry resume.'
-    )
-  }
-  const result = response.result as { useRealCodexHome?: unknown } | null
-  if (result?.useRealCodexHome !== true) {
-    return session
-  }
-  return { ...session, codexHome: null }
-}
-
 export async function resumeAiVaultSessionInTerminal(
   client: Pick<RpcClient, 'sendRequest'>,
   worktreeId: string,

mobile/src/session/ai-vault-resume-preparation.test.ts

@@ -2,12 +2,15 @@ import { describe, expect, it, vi } from 'vitest'
 import type { AiVaultSession } from '../../../src/shared/ai-vault-types'
 import {
   buildMobileAiVaultResumeLaunch,
-  prepareMobileAiVaultSessionResume,
-  resumeAiVaultSessionInTerminal,
-  RESUME_RPC_TIMEOUT_MS
+  resumeAiVaultSessionInTerminal
 } from './ai-vault-resume-launch'
+import {
+  prepareMobileAiVaultSessionResume,
+  RESUME_RPC_TIMEOUT_MS
+} from './ai-vault-resume-preparation'
 
 const LEGACY_CODEX_HOME = '/Users/ada/Library/Application Support/orca/codex-runtime-home/home'
+const PER_ACCOUNT_HOME = '/Users/ada/Library/Application Support/orca/codex-accounts/a/home'
 
 function legacySession(overrides: Partial<AiVaultSession> = {}): AiVaultSession {
   return {
@@ -121,10 +124,11 @@ describe('prepareMobileAiVaultSessionResume', () => {
     { agent: 'codex' as const, codexHome: '/Users/ada/.config/codex' },
     {
       agent: 'codex' as const,
-      codexHome: '/Users/ada/Library/Application Support/orca/codex-accounts/a/home'
+      codexHome: PER_ACCOUNT_HOME,
+      executionHostId: 'ssh:server-1' as AiVaultSession['executionHostId']
     },
     { agent: 'codex' as const, codexHome: '\\\\wsl.localhost\\Ubuntu\\home\\ada\\.codex' }
-  ])('does not prepare non-legacy session $agent at $codexHome', async (overrides) => {
+  ])('does not prepare unrepinnable session $agent at $codexHome', async (overrides) => {
     const current = legacySession(overrides)
     const sendRequest = vi.fn()
 
@@ -132,6 +136,51 @@ describe('prepareMobileAiVaultSessionResume', () => {
     expect(sendRequest).not.toHaveBeenCalled()
   })
 
+  it('repins a per-account session to the home the host substitutes', async () => {
+    const substituteHome = '/Users/ada/Library/Application Support/orca/codex-accounts/b/home'
+    const current = legacySession({ codexHome: PER_ACCOUNT_HOME })
+    const sendRequest = vi.fn().mockResolvedValue({
+      ok: true,
+      result: { useRealCodexHome: false, substituteCodexHome: substituteHome }
+    })
+
+    const prepared = await prepareMobileAiVaultSessionResume({ sendRequest }, current)
+    const launch = buildMobileAiVaultResumeLaunch({ session: prepared, hostPlatform: 'darwin' })
+
+    expect(sendRequest).toHaveBeenCalledWith(
+      'aiVault.prepareSessionResume',
+      {
+        agent: 'codex',
+        filePath: current.filePath,
+        codexHome: PER_ACCOUNT_HOME,
+        executionHostId: 'local'
+      },
+      { timeoutMs: RESUME_RPC_TIMEOUT_MS }
+    )
+    expect(prepared.codexHome).toBe(substituteHome)
+    expect(launch.command).toContain(`CODEX_HOME='${substituteHome}'`)
+  })
+
+  it('keeps a per-account session home when an older host sends no repin', async () => {
+    const current = legacySession({ codexHome: PER_ACCOUNT_HOME })
+    const sendRequest = vi.fn().mockResolvedValue({
+      ok: true,
+      result: { useRealCodexHome: false }
+    })
+
+    await expect(prepareMobileAiVaultSessionResume({ sendRequest }, current)).resolves.toBe(current)
+  })
+
+  it('keeps a per-account session usable when the host cannot prepare at all', async () => {
+    const current = legacySession({ codexHome: PER_ACCOUNT_HOME })
+    const sendRequest = vi.fn().mockResolvedValue({
+      ok: false,
+      error: { code: 'method_not_found', message: 'Unknown method' }
+    })
+
+    await expect(prepareMobileAiVaultSessionResume({ sendRequest }, current)).resolves.toBe(current)
+  })
+
   it.each([
     {
       code: 'internal_error',

mobile/src/session/ai-vault-resume-preparation.ts

@@ -0,0 +1,60 @@
+import type { AiVaultSession } from '../../../src/shared/ai-vault-types'
+import {
+  isAiVaultPrepareSessionResumeUnavailableError,
+  isLegacySharedCodexHome,
+  isPerAccountManagedCodexHome
+} from '../../../src/shared/ai-vault-resume-preparation'
+import { LOCAL_EXECUTION_HOST_ID } from '../../../src/shared/execution-host'
+import type { RpcClient } from '../transport/rpc-client'
+
+// Why: without an explicit timeout, a socket drop mid-resume parks the request
+// on the reconnect waiter for the full reconnect budget, pinning the spinner.
+export const RESUME_RPC_TIMEOUT_MS = 30_000
+
+export async function prepareMobileAiVaultSessionResume(
+  client: Pick<RpcClient, 'sendRequest'>,
+  session: AiVaultSession
+): Promise<AiVaultSession> {
+  // Why: per-account repinning runs on the serving host, whose account
+  // selection only applies to that host's own ("local") sessions.
+  const needsAccountRepin =
+    isPerAccountManagedCodexHome(session.codexHome) &&
+    (!session.executionHostId || session.executionHostId === LOCAL_EXECUTION_HOST_ID)
+  if (
+    session.agent !== 'codex' ||
+    (!isLegacySharedCodexHome(session.codexHome) && !needsAccountRepin)
+  ) {
+    return session
+  }
+  const response = await client.sendRequest(
+    'aiVault.prepareSessionResume',
+    {
+      agent: session.agent,
+      filePath: session.filePath,
+      codexHome: session.codexHome,
+      executionHostId: session.executionHostId
+    },
+    { timeoutMs: RESUME_RPC_TIMEOUT_MS }
+  )
+  if (!response.ok) {
+    if (isAiVaultPrepareSessionResumeUnavailableError(response.error)) {
+      // Why: older hosts cannot prepare, but their shared home still supports the legacy resume path.
+      return session
+    }
+    throw new Error(
+      response.error?.message || 'Could not prepare this legacy Codex session. Retry resume.'
+    )
+  }
+  const result = response.result as {
+    useRealCodexHome?: unknown
+    substituteCodexHome?: unknown
+  } | null
+  if (result?.useRealCodexHome === true) {
+    return { ...session, codexHome: null }
+  }
+  // Why: older hosts never send a repin home, so absence keeps the session's own home.
+  if (typeof result?.substituteCodexHome === 'string' && result.substituteCodexHome) {
+    return { ...session, codexHome: result.substituteCodexHome }
+  }
+  return session
+}

mobile/src/terminal/terminal-webview-html.ts

@@ -11,6 +11,7 @@ import { TERMINAL_WEBVIEW_THEME_JS } from './terminal-webview-theme-injected'
 import { TERMINAL_QUERY_REPLY_JS } from './terminal-webview-query-reply-injected'
 import { URL_TAP_WEBVIEW_JS } from './terminal-webview-url-tap'
 import { TERMINAL_WEBGL_RECOVERY_JS } from './terminal-webview-webgl-recovery-injected'
+import { TERMINAL_WHEEL_SCROLL_JS } from './terminal-webview-wheel-scroll-injected'
 
 const DEFAULT_TERMINAL_THEME: RuntimeMobileTerminalTheme['theme'] = {
   background: colors.terminalBg,
@@ -688,6 +689,7 @@ ${TERMINAL_WEBGL_RECOVERY_JS}
     initRows = rows || 24;
     firstDataPending = true;
     smoothScrollOffsetY = 0;
+    wheelAccumDeltaY = 0;
     mouseModeScanTail = '';
     trackedMouseTrackingMode = 'none';
     sgrMouseMode = false;
@@ -1634,6 +1636,10 @@ ${TERMINAL_WEBGL_RECOVERY_JS}
   // terminal-webview-tap-dispatch-injected.ts (extracted for max-lines).
   ${TERMINAL_TAP_DISPATCH_JS}
 
+  // External mouse / trackpad scroll: see
+  // terminal-webview-wheel-scroll-injected.ts (extracted for max-lines).
+  ${TERMINAL_WHEEL_SCROLL_JS}
+
   btnCopy.addEventListener('click', function(e) {
     e.preventDefault();
     e.stopPropagation();
@@ -1690,6 +1696,8 @@ ${TERMINAL_WEBGL_RECOVERY_JS}
     targetSurface.addEventListener('mousedown', function(e) { e.preventDefault(); e.stopPropagation(); }, true);
     targetSurface.addEventListener('click', function(e) { e.preventDefault(); e.stopPropagation(); }, true);
 
+    attachSurfaceWheelHandler(targetSurface);
+
     targetSurface.addEventListener('touchstart', function(e) {
       if (dispatcherShouldBlockSurface()) return;
       if (ts.momentumId) {

mobile/src/terminal/terminal-webview-wheel-scroll-injected.ts

@@ -0,0 +1,53 @@
+// Indirect-pointer (external mouse / trackpad) scroll for the terminal surface,
+// injected into XTERM_HTML. Extracted from terminal-webview-html.ts to keep that
+// file within its max-lines budget. Closes over host-IIFE state/functions:
+// term, getCellHeight, getTotalScale, shouldRouteScrollToTerminalInput,
+// routeScrollLines, enqueueNormalBufferScrollDelta, resetSmoothScrollOffset,
+// and dispatcherShouldBlockSurface.
+export const TERMINAL_WHEEL_SCROLL_JS = `
+  var wheelAccumDeltaY = 0;
+
+  function wheelEventPixelDeltaY(e) {
+    var delta = e.deltaY;
+    if (typeof delta !== 'number' || !isFinite(delta) || delta === 0) return 0;
+    // DOM_DELTA_LINE / DOM_DELTA_PAGE: Android WebView reports line-mode deltas
+    // for external mouse wheels, iOS trackpads report pixels.
+    if (e.deltaMode === 1) return delta * getCellHeight() * getTotalScale();
+    if (e.deltaMode === 2) return delta * window.innerHeight;
+    return delta;
+  }
+
+  function attachSurfaceWheelHandler(targetSurface) {
+    targetSurface.addEventListener('wheel', function(e) {
+      if (dispatcherShouldBlockSurface()) return;
+      if (!term) return;
+      // Why: xterm's own wheel handler scrolls its hidden viewport or emits
+      // cursor keys through onData, which the mobile query-reply gate drops.
+      // Claim the event so indirect pointers share the touch scroll router.
+      e.preventDefault();
+      e.stopPropagation();
+
+      // Why: a trackpad pinch arrives as ctrl+wheel. Swallow it rather than
+      // firing cursor keys at the TUI; two-finger pinch still drives text size.
+      if (e.ctrlKey) return;
+
+      var deltaY = wheelEventPixelDeltaY(e);
+      if (deltaY === 0) return;
+
+      if (shouldRouteScrollToTerminalInput()) {
+        resetSmoothScrollOffset();
+        var effectiveCellH = getCellHeight() * getTotalScale();
+        if (!(effectiveCellH > 0)) return;
+        wheelAccumDeltaY += deltaY;
+        var lines = Math.trunc(wheelAccumDeltaY / effectiveCellH);
+        if (lines !== 0) {
+          wheelAccumDeltaY -= lines * effectiveCellH;
+          routeScrollLines(lines, e.clientX, e.clientY);
+        }
+        return;
+      }
+      wheelAccumDeltaY = 0;
+      enqueueNormalBufferScrollDelta(deltaY);
+    }, { capture: true, passive: false });
+  }
+`

mobile/src/terminal/terminal-webview-wheel-scroll.test.ts

@@ -0,0 +1,292 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { XTERM_HTML } from './terminal-webview-html'
+
+function iifeSource(): string {
+  const start = XTERM_HTML.indexOf('(function() {')
+  const end = XTERM_HTML.lastIndexOf('})();')
+  return XTERM_HTML.slice(start, end + '})();'.length)
+}
+
+function bodyMarkup(): string {
+  const start = XTERM_HTML.indexOf('<body>') + '<body>'.length
+  const end = XTERM_HTML.indexOf('<script>', start)
+  return XTERM_HTML.slice(start, end)
+}
+
+type BufferState = {
+  baseY: number
+  type: 'alternate' | 'normal'
+  viewportY: number
+}
+
+type TerminalStub = ReturnType<typeof makeTerminal>
+type RegisteredWindowListener = {
+  listener: EventListenerOrEventListenerObject
+  options?: boolean | AddEventListenerOptions
+  type: string
+}
+
+const CELL_HEIGHT = 15
+const ESC = '\u001b'
+const ESC_ARROW_DOWN = `${ESC}[B`
+const ESC_APP_ARROW_UP = `${ESC}OA`
+
+function makeTerminal(buffer: BufferState, scrollLines: (lines: number) => void) {
+  const terminal = {
+    cols: 40,
+    rows: 24,
+    options: { fontSize: 13 },
+    modes: { mouseTrackingMode: 'none' as string },
+    element: null as HTMLElement | null,
+    _core: {
+      _renderService: { dimensions: { css: { cell: { width: 8, height: CELL_HEIGHT } } } }
+    },
+    buffer: {
+      active: {
+        get baseY() {
+          return buffer.baseY
+        },
+        get type() {
+          return buffer.type
+        },
+        get viewportY() {
+          return buffer.viewportY
+        },
+        cursorY: 0,
+        length: 1,
+        getLine: () => null
+      }
+    },
+    write(_data: string, callback?: () => void) {
+      callback?.()
+    },
+    open(surface: HTMLElement) {
+      terminal.element = surface
+    },
+    loadAddon() {},
+    resize(cols: number, rows: number) {
+      terminal.cols = cols
+      terminal.rows = rows
+    },
+    clear() {},
+    reset() {},
+    refresh() {},
+    selectAll() {},
+    clearSelection() {},
+    select() {},
+    scrollLines,
+    scrollToBottom() {},
+    scrollToLine() {},
+    attachCustomKeyEventHandler() {},
+    getSelection: () => '',
+    onData: () => ({ dispose() {} }),
+    onLineFeed: () => ({ dispose() {} }),
+    onScroll: () => ({ dispose() {} }),
+    onWriteParsed: () => ({ dispose() {} }),
+    dispose() {}
+  }
+  return terminal
+}
+
+function dispatchWheel(deltaY: number, init: WheelEventInit = {}): WheelEvent {
+  const surface = document.getElementById('terminal-surface')
+  if (!surface) {
+    throw new Error('terminal surface missing')
+  }
+  const event = new WheelEvent('wheel', {
+    bubbles: true,
+    cancelable: true,
+    clientX: 40,
+    clientY: 60,
+    deltaMode: 0,
+    deltaY,
+    ...init
+  })
+  if (init.ctrlKey) {
+    // Why: happy-dom drops modifier flags from the WheelEvent init dict.
+    Object.defineProperty(event, 'ctrlKey', { value: true })
+  }
+  surface.dispatchEvent(event)
+  return event
+}
+
+function terminalInputBytes(postMessage: ReturnType<typeof vi.fn>): string {
+  return postMessage.mock.calls
+    .map(([raw]) => JSON.parse(String(raw)) as { bytes?: string; type: string })
+    .filter((msg) => msg.type === 'terminal-input')
+    .map((msg) => msg.bytes ?? '')
+    .join('')
+}
+
+describe('terminal WebView external pointer wheel scrolling', () => {
+  let animationFrames: Array<() => void>
+  let buffer: BufferState
+  let postMessage: ReturnType<typeof vi.fn>
+  let registeredWindowListeners: RegisteredWindowListener[]
+  let scrollLines: ReturnType<typeof vi.fn>
+  let terminals: TerminalStub[]
+
+  function boot(): void {
+    document.body.innerHTML = bodyMarkup()
+    new Function(iifeSource())()
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: JSON.stringify({ type: 'init', cols: 40, rows: 24, initialData: '' })
+      })
+    )
+    // Why: init commits the replacement surface on the next animation frame.
+    while (animationFrames.length > 0) {
+      animationFrames.shift()?.()
+    }
+  }
+
+  function flushFrames(): void {
+    for (let i = 0; i < 4 && animationFrames.length > 0; i++) {
+      animationFrames.shift()?.()
+    }
+  }
+
+  beforeEach(() => {
+    animationFrames = []
+    buffer = { baseY: 0, type: 'normal', viewportY: 0 }
+    registeredWindowListeners = []
+    scrollLines = vi.fn()
+    terminals = []
+    const addWindowEventListener = window.addEventListener.bind(window)
+    vi.spyOn(window, 'addEventListener').mockImplementation(((
+      type: string,
+      listener: EventListenerOrEventListenerObject,
+      options?: boolean | AddEventListenerOptions
+    ) => {
+      registeredWindowListeners.push({ type, listener, options })
+      addWindowEventListener(type, listener, options)
+    }) as typeof window.addEventListener)
+    vi.stubGlobal('requestAnimationFrame', (callback: () => void) => {
+      animationFrames.push(callback)
+      return animationFrames.length
+    })
+    vi.stubGlobal('cancelAnimationFrame', () => {})
+    Object.defineProperty(window, 'innerWidth', { value: 381, configurable: true })
+    Object.defineProperty(window, 'innerHeight', { value: 612, configurable: true })
+    postMessage = vi.fn()
+    const webWindow = window as unknown as {
+      Terminal: new () => TerminalStub
+      ReactNativeWebView: { postMessage: (data: string) => void }
+    }
+    webWindow.Terminal = function () {
+      const terminal = makeTerminal(buffer, scrollLines)
+      terminals.push(terminal)
+      return terminal
+    } as unknown as new () => TerminalStub
+    webWindow.ReactNativeWebView = { postMessage }
+  })
+
+  afterEach(() => {
+    for (const { type, listener, options } of registeredWindowListeners) {
+      window.removeEventListener(type, listener as EventListener, options)
+    }
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  it('turns an alternate-screen wheel scroll into cursor keys (#6863, #8818)', () => {
+    buffer = { baseY: 0, type: 'alternate', viewportY: 0 }
+    boot()
+    expect(terminals).toHaveLength(1)
+
+    dispatchWheel(3 * CELL_HEIGHT)
+
+    // Why: alt-screen TUIs (Claude Code, vim) have no scrollback, so an external
+    // mouse/trackpad wheel must reach the PTY as cursor keys the way touch does.
+    expect(terminalInputBytes(postMessage)).toBe(ESC_ARROW_DOWN.repeat(3))
+  })
+
+  it('sends application cursor keys when the TUI enabled DECCKM', () => {
+    buffer = { baseY: 0, type: 'alternate', viewportY: 0 }
+    boot()
+    const terminal = terminals[0]
+    if (!terminal) {
+      throw new Error('terminal missing')
+    }
+    ;(terminal.modes as Record<string, unknown>).applicationCursorKeysMode = true
+
+    dispatchWheel(-2 * CELL_HEIGHT)
+
+    expect(terminalInputBytes(postMessage)).toBe(ESC_APP_ARROW_UP.repeat(2))
+  })
+
+  it('reports the wheel as mouse tracking bytes when the TUI asked for them', () => {
+    buffer = { baseY: 0, type: 'alternate', viewportY: 0 }
+    boot()
+    const terminal = terminals[0]
+    if (!terminal) {
+      throw new Error('terminal missing')
+    }
+    terminal.modes.mouseTrackingMode = 'any'
+
+    dispatchWheel(CELL_HEIGHT)
+
+    // Default (non-SGR) encoding: wheel-down button 65 + 32 = 97 ('a'), then two
+    // printable cell bytes (their value depends on the fit scale, not on routing).
+    const bytes = terminalInputBytes(postMessage)
+    expect(bytes.slice(0, 4)).toBe(`${ESC}[Ma`)
+    expect(bytes).toHaveLength(6)
+    expect(bytes.charCodeAt(4)).toBeGreaterThanOrEqual(33)
+    expect(bytes.charCodeAt(5)).toBeGreaterThanOrEqual(33)
+  })
+
+  it('scrolls normal-buffer scrollback from a wheel instead of leaving it frozen', () => {
+    buffer = { baseY: 20, type: 'normal', viewportY: 20 }
+    boot()
+
+    dispatchWheel(-3 * CELL_HEIGHT)
+    flushFrames()
+
+    expect(scrollLines).toHaveBeenCalledWith(-3)
+  })
+
+  it('converts line-mode deltas that Android reports for external mouse wheels', () => {
+    buffer = { baseY: 0, type: 'alternate', viewportY: 0 }
+    boot()
+
+    dispatchWheel(2, { deltaMode: 1 })
+
+    expect(terminalInputBytes(postMessage)).toBe(ESC_ARROW_DOWN.repeat(2))
+  })
+
+  it('swallows a trackpad pinch instead of firing cursor keys at the TUI', () => {
+    buffer = { baseY: 0, type: 'alternate', viewportY: 0 }
+    boot()
+
+    const event = dispatchWheel(3 * CELL_HEIGHT, { ctrlKey: true })
+
+    expect(terminalInputBytes(postMessage)).toBe('')
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('claims the wheel so xterm does not double-apply it', () => {
+    buffer = { baseY: 20, type: 'normal', viewportY: 20 }
+    boot()
+
+    const event = dispatchWheel(-CELL_HEIGHT)
+
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('clears fractional wheel state when the terminal is recreated', () => {
+    buffer = { baseY: 0, type: 'alternate', viewportY: 0 }
+    boot()
+    dispatchWheel(CELL_HEIGHT - 1)
+
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: JSON.stringify({ type: 'init', cols: 40, rows: 24, initialData: '' })
+      })
+    )
+    flushFrames()
+    dispatchWheel(1)
+
+    expect(terminalInputBytes(postMessage)).toBe('')
+  })
+})

mobile/src/transport/rpc-client-log-redaction.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { connect } from './rpc-client'
+import type { ConnectionLogEntry } from './types'
+
+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) => plaintext,
+  decrypt: (raw: string) => raw,
+  decryptBytes: (bytes: Uint8Array) => bytes
+}))
+
+class NeverOpeningWebSocket {
+  static CONNECTING = 0
+  static OPEN = 1
+  static CLOSING = 2
+  static CLOSED = 3
+  readonly CONNECTING = 0
+  readonly OPEN = 1
+  readonly CLOSING = 2
+  readonly CLOSED = 3
+  readyState = 0
+  onopen: (() => void) | null = null
+  onclose: (() => void) | null = null
+  onmessage: ((event: { data: unknown }) => void) | null = null
+  onerror: (() => void) | null = null
+  send(): void {}
+  close(): void {
+    this.readyState = 3
+  }
+}
+
+const originalWebSocket = globalThis.WebSocket
+
+afterEach(() => {
+  globalThis.WebSocket = originalWebSocket
+})
+
+describe('mobile rpc-client connection logs', () => {
+  it('never exposes endpoint query credentials', () => {
+    globalThis.WebSocket = NeverOpeningWebSocket as unknown as typeof WebSocket
+    const logs: ConnectionLogEntry[] = []
+    const endpoint = 'wss://desktop.example:7443/runtime?token=super-secret&route=private'
+
+    const client = connect(endpoint, 'device-token', 'server-key', {
+      onLog: (entry) => logs.push(entry)
+    })
+
+    expect(logs).toContainEqual(
+      expect.objectContaining({ message: 'Opening WebSocket', detail: 'desktop.example:7443' })
+    )
+    expect(JSON.stringify(logs)).not.toContain('super-secret')
+    expect(JSON.stringify(logs)).not.toContain('route=private')
+    client.close()
+  })
+
+  it('does not expose URL credentials in malformed legacy endpoints', () => {
+    globalThis.WebSocket = NeverOpeningWebSocket as unknown as typeof WebSocket
+    const logs: ConnectionLogEntry[] = []
+
+    const client = connect('wss://user:password@desktop.example:7443/runtime', 'token', 'key', {
+      onLog: (entry) => logs.push(entry)
+    })
+
+    expect(logs[0]?.detail).toBe('desktop.example:7443')
+    expect(JSON.stringify(logs)).not.toContain('password')
+    client.close()
+  })
+})

mobile/src/transport/rpc-client.ts

@@ -241,8 +241,7 @@ export function connect(
   // Why: keep device tokens / full URLs out of log scrolls — truncate to host:port.
   function redactedEndpoint(ep: string): string {
     try {
-      const m = ep.match(/^wss?:\/\/([^/]+)/i)
-      return m ? m[1] : 'unknown'
+      return new URL(ep).host || 'unknown'
     } catch {
       return 'unknown'
     }
@@ -305,7 +304,7 @@ export function connect(
     emitLog(
       'info',
       reconnectAttempt > 0 ? `Reconnecting (attempt ${reconnectAttempt + 1})` : 'Opening WebSocket',
-      endpoint
+      redactedEndpoint(endpoint)
     )
 
     ws = new WebSocket(endpoint)

native/computer-use-linux/runtime.py

@@ -822,19 +822,60 @@ def require_non_empty_string(value, name):
     return str(value)
 
 
-def click_at(x, y, button, count):
+def click_at(x, y, button, count, modifiers=None):
     button = (button or "left").lower()
     buttons = {"left": ("b1p", "b1r"), "right": ("b3p", "b3r"), "middle": ("b2p", "b2r")}
     if button not in buttons:
         raise RuntimeError(f"unsupported mouse button: {button}")
+    parsed_count = require_positive_integer(1 if count is None else count, "click_count")
+    modifier_keys = click_modifier_keys(modifiers)
+    if modifier_keys:
+        modified_click_at(x, y, button, parsed_count, modifier_keys)
+        return
     down, up = buttons[button]
-    for _ in range(require_positive_integer(1 if count is None else count, "click_count")):
+    for _ in range(parsed_count):
         Atspi.generate_mouse_event(round(x), round(y), "abs")
         Atspi.generate_mouse_event(round(x), round(y), down)
         time.sleep(0.03)
         Atspi.generate_mouse_event(round(x), round(y), up)
 
 
+def click_modifier_keys(raw):
+    if raw is None:
+        return []
+    aliases = {
+        "ctrl": "ctrl", "control": "ctrl", "cmdorctrl": "ctrl", "commandorcontrol": "ctrl",
+        "shift": "shift", "alt": "alt", "option": "alt",
+        "meta": "super", "super": "super", "win": "super", "cmd": "super", "command": "super",
+    }
+    parts = [part.strip().lower() for part in str(raw).split("+")]
+    if not parts or any(not part or part not in aliases for part in parts):
+        raise RuntimeError("click modifiers require modifier keys only")
+    return list(dict.fromkeys(aliases[part] for part in parts))
+
+
+def modified_click_at(x, y, button, count, modifier_keys):
+    xdotool = shutil.which("xdotool")
+    is_wayland = os.environ.get("XDG_SESSION_TYPE", "").lower() == "wayland"
+    if not xdotool or is_wayland:
+        raise RuntimeError("modified clicks require xdotool on an X11 session")
+    button_number = {"left": "1", "middle": "2", "right": "3"}[button]
+    command = [xdotool, "mousemove", "--sync", str(round(x)), str(round(y))]
+    for modifier in modifier_keys:
+        command.extend(["keydown", modifier])
+    command.extend(["click", "--repeat", str(count), "--delay", "35", button_number])
+    for modifier in reversed(modifier_keys):
+        command.extend(["keyup", modifier])
+    try:
+        subprocess.run(command, check=True, timeout=5)
+    finally:
+        subprocess.run(
+            [xdotool, *[item for modifier in reversed(modifier_keys) for item in ("keyup", modifier)]],
+            check=False,
+            timeout=2,
+        )
+
+
 def scroll_at(x, y, direction, pages):
     if direction is None or str(direction).strip() == "":
         raise RuntimeError("direction is required")
@@ -1024,12 +1065,14 @@ def run_operation(operation):
             if operation.get("click_count") is not None
             else 1
         )
-        handled = operation.get("mouse_button", "left") == "left" and click_count <= 1 and perform_action(node, preferred)
+        has_modifiers = bool(str(operation.get("modifiers") or "").strip())
+        handled = not has_modifiers and operation.get("mouse_button", "left") == "left" and click_count <= 1 and perform_action(node, preferred)
         if not handled:
             click_at(
                 *screen_point(bounds, saved, operation.get("x"), operation.get("y"), node),
                 operation.get("mouse_button", "left"),
                 click_count,
+                operation.get("modifiers"),
             )
             action = {"path": "synthetic", "actionName": None, "fallbackReason": "actionUnsupported"}
         else:

native/computer-use-macos/Sources/OrcaComputerUseMacOS/main.swift

@@ -729,12 +729,13 @@ final class Provider {
         let snapshot = try currentSnapshot(params: params)
         let button = params["mouseButton"]?.string ?? "left"
         let count = try positiveInteger(params["clickCount"]?.number, defaultValue: 1, name: "clickCount")
+        let modifiers = try KeyMap.parseModifiers(params["modifiers"]?.string)
         // Why: agents expect a click into a target app to make the next
         // keyboard action safe, even when the click uses an AX action path.
         recoverWindow(snapshot.app)
         if let elementIndex = try optionalInteger(params, "elementIndex") {
             let record = try element(snapshot, elementIndex)
-            if count <= 1, let actionName = try performClickAction(record: record, mouseButton: button) {
+            if modifiers.isEmpty, count <= 1, let actionName = try performClickAction(record: record, mouseButton: button) {
                 return actionMetadata(path: "accessibility", actionName: actionName)
             }
             if let point = center(record.localFrame, in: snapshot.windowBounds) {
@@ -742,7 +743,8 @@ final class Provider {
                     pid: snapshot.app.pid,
                     at: point,
                     button: mouseButton(button),
-                    count: count
+                    count: count,
+                    modifiers: modifiers
                 )
                 return actionMetadata(path: "synthetic", fallbackReason: "actionUnsupported")
             }
@@ -753,7 +755,8 @@ final class Provider {
             pid: snapshot.app.pid,
             at: point,
             button: mouseButton(button),
-            count: count
+            count: count,
+            modifiers: modifiers
         )
         return actionMetadata(path: "synthetic")
     }
@@ -2282,14 +2285,23 @@ private func resizePng(_ image: CGImage, scale: CGFloat) -> BoundedPNG? {
 }
 
 private enum Input {
-    static func click(pid: pid_t, at point: CGPoint, button: MouseButton, count: Int) throws {
+    static func click(
+        pid: pid_t,
+        at point: CGPoint,
+        button: MouseButton,
+        count: Int,
+        modifiers: [KeyModifier]
+    ) throws {
         guard let source = CGEventSource(stateID: .combinedSessionState) else {
             throw ProviderError.coded("accessibility_error", "failed to create event source")
         }
+        let flags = modifiers.reduce(into: CGEventFlags()) { result, modifier in
+            result.insert(modifier.flag)
+        }
         for _ in 0..<max(count, 1) {
-            try mouse(.mouseMoved, source: source, point: point, button: button.cgButton, pid: pid)
-            try mouse(button.downEvent, source: source, point: point, button: button.cgButton, pid: pid)
-            try mouse(button.upEvent, source: source, point: point, button: button.cgButton, pid: pid)
+            try mouse(.mouseMoved, source: source, point: point, button: button.cgButton, flags: flags, pid: pid)
+            try mouse(button.downEvent, source: source, point: point, button: button.cgButton, flags: flags, pid: pid)
+            try mouse(button.upEvent, source: source, point: point, button: button.cgButton, flags: flags, pid: pid)
         }
     }
 
@@ -2343,16 +2355,20 @@ private enum Input {
     static func pressKey(_ key: String, pid: pid_t) throws {
         let parsed = try KeyMap.parse(key)
         var flags = CGEventFlags()
+        var pressedModifiers: [KeyModifier] = []
+        defer {
+            for modifier in pressedModifiers.reversed() {
+                flags.remove(modifier.flag)
+                try? keyEvent(modifier.keyCode, down: false, flags: flags, pid: pid)
+            }
+        }
         for modifier in parsed.modifiers {
             flags.insert(modifier.flag)
             try keyEvent(modifier.keyCode, down: true, flags: flags, pid: pid)
+            pressedModifiers.append(modifier)
         }
         try keyEvent(parsed.keyCode, down: true, flags: flags, pid: pid)
         try keyEvent(parsed.keyCode, down: false, flags: flags, pid: pid)
-        for modifier in parsed.modifiers.reversed() {
-            try keyEvent(modifier.keyCode, down: false, flags: flags, pid: pid)
-            flags.remove(modifier.flag)
-        }
     }
 
     static func pasteText(_ text: String, pid: pid_t) throws {
@@ -2377,10 +2393,18 @@ private enum Input {
         try pressKey("cmd+v", pid: pid)
     }
 
-    private static func mouse(_ type: CGEventType, source: CGEventSource, point: CGPoint, button: CGMouseButton, pid: pid_t) throws {
+    private static func mouse(
+        _ type: CGEventType,
+        source: CGEventSource,
+        point: CGPoint,
+        button: CGMouseButton,
+        flags: CGEventFlags = [],
+        pid: pid_t
+    ) throws {
         guard let event = CGEvent(mouseEventSource: source, mouseType: type, mouseCursorPosition: point, mouseButton: button) else {
             throw ProviderError.coded("accessibility_error", "failed to create mouse event")
         }
+        event.flags = flags
         event.postToPid(pid)
     }
 
@@ -2497,16 +2521,9 @@ private enum KeyMap {
         var modifiers: [KeyModifier] = []
         var keyName: String?
         for part in parts {
-            switch part {
-            case "cmd", "command", "meta", "super", "cmdorctrl", "commandorcontrol":
-                modifiers.append(KeyModifier(keyCode: 55, flag: .maskCommand))
-            case "ctrl", "control":
-                modifiers.append(KeyModifier(keyCode: 59, flag: .maskControl))
-            case "alt", "option":
-                modifiers.append(KeyModifier(keyCode: 58, flag: .maskAlternate))
-            case "shift":
-                modifiers.append(KeyModifier(keyCode: 56, flag: .maskShift))
-            default:
+            if let modifier = modifier(part) {
+                modifiers.append(modifier)
+            } else {
                 keyName = part
             }
         }
@@ -2516,6 +2533,38 @@ private enum KeyMap {
         return ParsedKey(keyCode: keyCode, modifiers: modifiers)
     }
 
+    static func parseModifiers(_ spec: String?) throws -> [KeyModifier] {
+        guard let spec else {
+            return []
+        }
+        let parts = spec.split(separator: "+", omittingEmptySubsequences: false)
+            .map { String($0).trimmingCharacters(in: .whitespacesAndNewlines).lowercased() }
+        guard !parts.isEmpty, !parts.contains(where: \.isEmpty) else {
+            throw ProviderError.coded("invalid_argument", "click modifiers require modifier keys only")
+        }
+        return try parts.map { part in
+            guard let modifier = modifier(part) else {
+                throw ProviderError.coded("invalid_argument", "unsupported click modifier '\(part)'")
+            }
+            return modifier
+        }
+    }
+
+    private static func modifier(_ part: String) -> KeyModifier? {
+        switch part {
+        case "cmd", "command", "meta", "super", "win", "cmdorctrl", "commandorcontrol":
+            return KeyModifier(keyCode: 55, flag: .maskCommand)
+        case "ctrl", "control":
+            return KeyModifier(keyCode: 59, flag: .maskControl)
+        case "alt", "option":
+            return KeyModifier(keyCode: 58, flag: .maskAlternate)
+        case "shift":
+            return KeyModifier(keyCode: 56, flag: .maskShift)
+        default:
+            return nil
+        }
+    }
+
     private static let codes: [String: CGKeyCode] = [
         "a": 0, "s": 1, "d": 2, "f": 3, "h": 4, "g": 5, "z": 6, "x": 7, "c": 8, "v": 9,
         "b": 11, "q": 12, "w": 13, "e": 14, "r": 15, "y": 16, "t": 17, "1": 18, "2": 19,
@@ -2530,9 +2579,12 @@ private enum KeyMap {
 }
 
 private final class AgentRuntime: NSObject, NSApplicationDelegate {
+    private static let unclaimedSessionDeadline: TimeInterval = 30
+
     private let socketPath: String
     private let token: String?
     private var listener: SocketListener?
+    private var unclaimedSessionTimeout: DispatchWorkItem?
 
     init(socketPath: String, token: String?) {
         self.socketPath = socketPath
@@ -2541,9 +2593,31 @@ private final class AgentRuntime: NSObject, NSApplicationDelegate {
 
     func applicationDidFinishLaunching(_ notification: Notification) {
         do {
-            let listener = try SocketListener(socketPath: socketPath, token: token)
+            let timeout = DispatchWorkItem {
+                fputs("computer-use agent received no authenticated session before its deadline\n", stderr)
+                NSApp.terminate(nil)
+            }
+            unclaimedSessionTimeout = timeout
+            let listener = try SocketListener(
+                socketPath: socketPath,
+                token: token,
+                onSessionClaimed: {
+                    DispatchQueue.main.async {
+                        timeout.cancel()
+                    }
+                },
+                onSessionClosed: {
+                    DispatchQueue.main.async {
+                        NSApp.terminate(nil)
+                    }
+                }
+            )
             self.listener = listener
             listener.start()
+            DispatchQueue.main.asyncAfter(
+                deadline: .now() + Self.unclaimedSessionDeadline,
+                execute: timeout
+            )
         } catch {
             fputs("failed to start computer-use socket: \(error)\n", stderr)
             NSApp.terminate(nil)
@@ -2551,6 +2625,8 @@ private final class AgentRuntime: NSObject, NSApplicationDelegate {
     }
 
     func applicationWillTerminate(_ notification: Notification) {
+        unclaimedSessionTimeout?.cancel()
+        unclaimedSessionTimeout = nil
         listener?.stop()
     }
 }
@@ -3456,14 +3532,25 @@ private final class ButtonTarget: NSObject {
 private final class SocketListener: @unchecked Sendable {
     private let socketPath: String
     private let token: String?
+    private let onSessionClaimed: () -> Void
+    private let onSessionClosed: () -> Void
     private let provider = Provider()
     private let providerLock = NSLock()
+    private let sessionLock = NSLock()
+    private var sessionOwnership = AgentSessionOwnership()
     private var socketFd: Int32 = -1
     private var isStopped = false
 
-    init(socketPath: String, token: String?) throws {
+    init(
+        socketPath: String,
+        token: String?,
+        onSessionClaimed: @escaping () -> Void,
+        onSessionClosed: @escaping () -> Void
+    ) throws {
         self.socketPath = socketPath
         self.token = token
+        self.onSessionClaimed = onSessionClaimed
+        self.onSessionClosed = onSessionClosed
         try bindSocket()
     }
 
@@ -3545,15 +3632,39 @@ private final class SocketListener: @unchecked Sendable {
     }
 
     private func handleConnection(_ fd: Int32) {
-        defer { close(fd) }
+        defer {
+            sessionLock.lock()
+            let shouldTerminate = sessionOwnership.disconnect(fd)
+            sessionLock.unlock()
+            close(fd)
+            if shouldTerminate {
+                onSessionClosed()
+            }
+        }
         let authorizedPeer = peerProcessId(fd).map(isAuthorizedAgentPeer) == true
         let decoder = JSONDecoder()
+        var registrationComplete = false
         while let line = readLine(from: fd) {
             guard let data = line.data(using: .utf8),
                   let request = try? decoder.decode(Request.self, from: data)
             else {
                 continue
             }
+            if !registrationComplete {
+                sessionLock.lock()
+                let registration = sessionOwnership.registerConnection(
+                    fd,
+                    authenticated: isAuthenticated(
+                        request: request,
+                        authorizedPeer: authorizedPeer
+                    )
+                )
+                sessionLock.unlock()
+                registrationComplete = registration != .rejected
+                if registration == .claimed {
+                    onSessionClaimed()
+                }
+            }
             let response = handleRequest(
                 provider: provider,
                 lock: providerLock,
@@ -3564,6 +3675,12 @@ private final class SocketListener: @unchecked Sendable {
             writeJSON(response, to: fd)
         }
     }
+
+    private func isAuthenticated(request: Request, authorizedPeer: Bool) -> Bool {
+        guard authorizedPeer else { return false }
+        guard let token else { return true }
+        return request.token == token
+    }
 }
 
 private func existingPathMode(_ path: String) -> mode_t? {
@@ -3696,7 +3813,7 @@ private func handleRequest(
     if let expectedToken, request.token != expectedToken {
         return ["id": request.id, "ok": false, "error": ["code": "permission_denied", "message": "invalid computer-use agent token"]]
     }
-    if expectedToken != nil && !authorizedPeer {
+    if !authorizedPeer {
         return ["id": request.id, "ok": false, "error": ["code": "permission_denied", "message": "computer-use agent peer is not authorized"]]
     }
     if request.method == "terminate" {

native/computer-use-macos/Sources/OrcaComputerUseMacOSCore/AgentSessionOwnership.swift

@@ -0,0 +1,35 @@
+public enum AgentSessionRegistration: Sendable, Equatable {
+    case rejected
+    case sessionReleased
+    case joined
+    case claimed
+}
+
+public struct AgentSessionOwnership: Sendable {
+    private var authenticatedConnections: Set<Int32> = []
+    private var wasClaimed = false
+    private var wasReleased = false
+
+    public init() {}
+
+    public mutating func registerConnection(
+        _ connection: Int32,
+        authenticated: Bool
+    ) -> AgentSessionRegistration {
+        guard authenticated else { return .rejected }
+        guard !wasReleased else { return .sessionReleased }
+        let inserted = authenticatedConnections.insert(connection).inserted
+        guard inserted, !wasClaimed else { return .joined }
+        wasClaimed = true
+        return .claimed
+    }
+
+    public mutating func disconnect(_ connection: Int32) -> Bool {
+        guard authenticatedConnections.remove(connection) != nil else { return false }
+        let released = wasClaimed && authenticatedConnections.isEmpty
+        if released {
+            wasReleased = true
+        }
+        return released
+    }
+}

native/computer-use-macos/Tests/OrcaComputerUseMacOSTests/AgentEntrypointSourceSafetyTests.swift

@@ -18,4 +18,32 @@ final class AgentEntrypointSourceSafetyTests: XCTestCase {
         XCTAssertFalse(source.contains("unlink(tokenPath)"))
         XCTAssertFalse(source.contains("unlink(socketPath)"))
     }
+
+    func testSyntheticModifiersHaveGuaranteedReleaseAndModifiedClicksUseFlags() throws {
+        let source = try agentEntrypointSource()
+
+        XCTAssertTrue(source.contains("var pressedModifiers: [KeyModifier] = []"))
+        XCTAssertTrue(source.contains(
+            """
+            defer {
+                        for modifier in pressedModifiers.reversed() {
+                            flags.remove(modifier.flag)
+                            try? keyEvent(modifier.keyCode, down: false, flags: flags, pid: pid)
+            """
+        ))
+        XCTAssertTrue(source.contains("event.flags = flags\n        event.postToPid(pid)"))
+    }
+
+    private func agentEntrypointSource() throws -> String {
+        let testFile = URL(fileURLWithPath: #filePath)
+        let packageRoot = testFile
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+        let mainPath = packageRoot
+            .appendingPathComponent("Sources")
+            .appendingPathComponent("OrcaComputerUseMacOS")
+            .appendingPathComponent("main.swift")
+        return try String(contentsOf: mainPath, encoding: .utf8)
+    }
 }

native/computer-use-macos/Tests/OrcaComputerUseMacOSTests/AgentSessionOwnershipTests.swift

@@ -0,0 +1,50 @@
+import OrcaComputerUseMacOSCore
+import XCTest
+
+final class AgentSessionOwnershipTests: XCTestCase {
+    func testUnclaimedDisconnectDoesNotTerminateAgent() {
+        var ownership = AgentSessionOwnership()
+
+        XCTAssertFalse(ownership.disconnect(12))
+    }
+
+    func testUnauthenticatedConnectionCannotClaimOrRetainAgent() {
+        var ownership = AgentSessionOwnership()
+
+        XCTAssertEqual(ownership.registerConnection(12, authenticated: false), .rejected)
+        XCTAssertFalse(ownership.disconnect(12))
+    }
+
+    func testLastAuthenticatedDisconnectTerminatesAgent() {
+        var ownership = AgentSessionOwnership()
+
+        XCTAssertEqual(ownership.registerConnection(12, authenticated: true), .claimed)
+        XCTAssertTrue(ownership.disconnect(12))
+    }
+
+    func testAgentWaitsForEveryAuthenticatedConnectionToClose() {
+        var ownership = AgentSessionOwnership()
+
+        XCTAssertEqual(ownership.registerConnection(12, authenticated: true), .claimed)
+        XCTAssertEqual(ownership.registerConnection(13, authenticated: true), .joined)
+        XCTAssertFalse(ownership.disconnect(12))
+        XCTAssertTrue(ownership.disconnect(13))
+    }
+
+    func testDuplicateRegistrationDoesNotRetainAgent() {
+        var ownership = AgentSessionOwnership()
+
+        XCTAssertEqual(ownership.registerConnection(12, authenticated: true), .claimed)
+        XCTAssertEqual(ownership.registerConnection(12, authenticated: true), .joined)
+        XCTAssertTrue(ownership.disconnect(12))
+    }
+
+    func testReleasedSessionCannotBeReclaimed() {
+        var ownership = AgentSessionOwnership()
+
+        XCTAssertEqual(ownership.registerConnection(12, authenticated: true), .claimed)
+        XCTAssertTrue(ownership.disconnect(12))
+        XCTAssertEqual(ownership.registerConnection(13, authenticated: true), .sessionReleased)
+        XCTAssertFalse(ownership.disconnect(13))
+    }
+}

native/computer-use-windows/runtime.ps1

@@ -16,6 +16,7 @@ Add-Type -AssemblyName System.Windows.Forms
 
 Add-Type -TypeDefinition @"
 using System;
+using System.Collections.Generic;
 using System.Runtime.InteropServices;
 
 public static class OrcaDesktopWin32 {
@@ -33,6 +34,39 @@ public static class OrcaDesktopWin32 {
         public int Y;
     }
 
+    [StructLayout(LayoutKind.Sequential)]
+    public struct INPUT {
+        public uint type;
+        public INPUTUNION data;
+    }
+
+    [StructLayout(LayoutKind.Explicit)]
+    public struct INPUTUNION {
+        [FieldOffset(0)]
+        public MOUSEINPUT mouse;
+        [FieldOffset(0)]
+        public KEYBDINPUT keyboard;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct MOUSEINPUT {
+        public int dx;
+        public int dy;
+        public uint mouseData;
+        public uint flags;
+        public uint time;
+        public UIntPtr extraInfo;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct KEYBDINPUT {
+        public ushort virtualKey;
+        public ushort scanCode;
+        public uint flags;
+        public uint time;
+        public UIntPtr extraInfo;
+    }
+
     [DllImport("user32.dll")]
     public static extern bool GetWindowRect(IntPtr hwnd, out RECT rect);
 
@@ -56,6 +90,54 @@ public static class OrcaDesktopWin32 {
 
     [DllImport("user32.dll")]
     public static extern void mouse_event(uint dwFlags, uint dx, uint dy, int dwData, UIntPtr dwExtraInfo);
+
+    [DllImport("user32.dll")]
+    public static extern uint SendInput(uint count, INPUT[] inputs, int size);
+
+    public static void SendModifiedClick(byte[] modifiers, uint mouseDown, uint mouseUp) {
+        const uint keyboardInput = 1;
+        const uint mouseInput = 0;
+        const uint keyUp = 0x0002;
+        var inputs = new List<INPUT>();
+        foreach (var modifier in modifiers) {
+            inputs.Add(KeyboardInput(keyboardInput, modifier, 0));
+        }
+        inputs.Add(MouseInput(mouseInput, mouseDown));
+        inputs.Add(MouseInput(mouseInput, mouseUp));
+        for (var index = modifiers.Length - 1; index >= 0; index--) {
+            inputs.Add(KeyboardInput(keyboardInput, modifiers[index], keyUp));
+        }
+        var values = inputs.ToArray();
+        var sent = SendInput((uint)values.Length, values, Marshal.SizeOf(typeof(INPUT)));
+        if (sent != (uint)values.Length) {
+            var releases = new List<INPUT>();
+            releases.Add(MouseInput(mouseInput, mouseUp));
+            for (var index = modifiers.Length - 1; index >= 0; index--) {
+                releases.Add(KeyboardInput(keyboardInput, modifiers[index], keyUp));
+            }
+            var releaseValues = releases.ToArray();
+            SendInput((uint)releaseValues.Length, releaseValues, Marshal.SizeOf(typeof(INPUT)));
+            throw new InvalidOperationException("SendInput did not complete the modified click");
+        }
+    }
+
+    private static INPUT KeyboardInput(uint type, byte virtualKey, uint flags) {
+        return new INPUT {
+            type = type,
+            data = new INPUTUNION {
+                keyboard = new KEYBDINPUT { virtualKey = virtualKey, flags = flags }
+            }
+        };
+    }
+
+    private static INPUT MouseInput(uint type, uint flags) {
+        return new INPUT {
+            type = type,
+            data = new INPUTUNION {
+                mouse = new MOUSEINPUT { flags = flags }
+            }
+        };
+    }
 }
 "@
 
@@ -912,7 +994,7 @@ function Get-OrcaElementScreenPoint($Element) {
     $null
 }
 
-function Send-OrcaMouseClick([IntPtr]$WindowHandle, [int]$ScreenX, [int]$ScreenY, [string]$Button, [int]$Count) {
+function Send-OrcaMouseClick([IntPtr]$WindowHandle, [int]$ScreenX, [int]$ScreenY, [string]$Button, [int]$Count, [string]$Modifiers) {
     [void][OrcaDesktopWin32]::SetForegroundWindow($WindowHandle)
     [void][OrcaDesktopWin32]::SetCursorPos($ScreenX, $ScreenY)
     $buttonName = if ([string]::IsNullOrWhiteSpace($Button)) { "left" } else { $Button.ToLowerInvariant() }
@@ -923,10 +1005,23 @@ function Send-OrcaMouseClick([IntPtr]$WindowHandle, [int]$ScreenX, [int]$ScreenY
         default { throw "unsupported mouse button: $Button" }
     }
 
-    for ($i = 0; $i -lt (Get-OrcaPositiveInteger $Count "click_count"); $i++) {
-        [OrcaDesktopWin32]::mouse_event($down, 0, 0, 0, [UIntPtr]::Zero)
-        Start-Sleep -Milliseconds 35
-        [OrcaDesktopWin32]::mouse_event($up, 0, 0, 0, [UIntPtr]::Zero)
+    $modifierKeys = @(Get-OrcaClickModifierVirtualKeys $Modifiers)
+    $clickCount = Get-OrcaPositiveInteger $Count "click_count"
+    if ($modifierKeys.Count -eq 0) {
+        for ($i = 0; $i -lt $clickCount; $i++) {
+            [OrcaDesktopWin32]::mouse_event($down, 0, 0, 0, [UIntPtr]::Zero)
+            Start-Sleep -Milliseconds 35
+            [OrcaDesktopWin32]::mouse_event($up, 0, 0, 0, [UIntPtr]::Zero)
+        }
+        return
+    }
+    for ($i = 0; $i -lt $clickCount; $i++) {
+        [OrcaDesktopWin32]::SendModifiedClick(
+            [byte[]]$modifierKeys,
+            [uint32]$down,
+            [uint32]$up
+        )
+        if ($i + 1 -lt $clickCount) { Start-Sleep -Milliseconds 35 }
     }
 }
 
@@ -990,6 +1085,16 @@ function Get-OrcaModifierVirtualKey([string]$Modifier) {
     }
 }
 
+function Get-OrcaClickModifierVirtualKeys([string]$Modifiers) {
+    if ([string]::IsNullOrWhiteSpace($Modifiers)) { return @() }
+    $parts = @($Modifiers.Split("+") | ForEach-Object { $_.Trim() })
+    $emptyParts = @($parts | Where-Object { [string]::IsNullOrWhiteSpace($_) })
+    if ($parts.Count -eq 0 -or $emptyParts.Count -gt 0) {
+        throw "Click modifiers require modifier keys only"
+    }
+    @($parts | ForEach-Object { Get-OrcaModifierVirtualKey $_ })
+}
+
 function Send-OrcaHotkey([IntPtr]$WindowHandle, [string]$KeySpec) {
     $parts = @($KeySpec.Split("+") | ForEach-Object { $_.Trim() } | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
     if ($parts.Count -eq 0) { throw "Unsupported key: $KeySpec" }
@@ -1106,13 +1211,14 @@ function Invoke-OrcaOperation($Operation) {
             Restore-OrcaWindow $process
             $handledByPattern = $false
             $clickCount = Get-OrcaPositiveInteger $Operation.click_count "click_count"
-            if ($null -ne $element -and $Operation.mouse_button -ne "right" -and $Operation.mouse_button -ne "middle" -and $clickCount -le 1) {
+            $hasModifiers = -not [string]::IsNullOrWhiteSpace([string]$Operation.modifiers)
+            if (-not $hasModifiers -and $null -ne $element -and $Operation.mouse_button -ne "right" -and $Operation.mouse_button -ne "middle" -and $clickCount -le 1) {
                 $handledByPattern = Invoke-OrcaPrimaryAction $element
             }
             if (-not $handledByPattern) {
                 $point = Get-OrcaElementScreenPoint $element
                 if ($null -eq $point) { $point = Get-OrcaScreenPoint $Operation $windowFrame }
-                Send-OrcaMouseClick $handle $point.x $point.y $Operation.mouse_button $clickCount
+                Send-OrcaMouseClick $handle $point.x $point.y $Operation.mouse_button $clickCount $Operation.modifiers
                 $action = [pscustomobject]@{ path = "synthetic"; actionName = $null; fallbackReason = "actionUnsupported" }
             } else {
                 $action = [pscustomobject]@{ path = "accessibility"; actionName = "primaryAction"; fallbackReason = $null }

native/windows-cli-launcher/OrcaCliLauncher.cs

@@ -50,6 +50,11 @@ internal static class OrcaCliLauncher
                 "ORCA_NODE_REPL_EXTERNAL_MODULE"
             );
             startInfo.EnvironmentVariables["ELECTRON_RUN_AS_NODE"] = "1";
+            startInfo.EnvironmentVariables["ORCA_WINDOWS_PACKAGED_CLI_LAUNCHER"] = "1";
+            startInfo.EnvironmentVariables["ORCA_CLI_COMMAND"] =
+                Environment.GetEnvironmentVariable("ORCA_CLI_COMMAND") == "orca-ide"
+                    ? "orca-ide"
+                    : "orca";
 
             using (Process child = Process.Start(startInfo))
             {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.160-rc.3",
+  "version": "1.4.162-rc.0",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",
@@ -11,7 +11,7 @@
   "main": "./out/main/index.js",
   "scripts": {
     "format": "oxfmt --write .",
-    "lint": "oxlint && pnpm run audit:code-quality:native && pnpm run audit:code-quality:type-aware && pnpm run check:reliability-gates && pnpm run check:max-lines-ratchet && pnpm run verify:bundled-skill-guides && pnpm run verify:skill-bundle-manifest && pnpm run verify:localization-catalog && pnpm run verify:localization-coverage",
+    "lint": "oxlint && pnpm run audit:code-quality:native && pnpm run audit:code-quality:type-aware && pnpm run check:reliability-gates && pnpm run check:max-lines-ratchet && pnpm run verify:bundled-skill-guides && pnpm run verify:skill-bundle-manifest && pnpm run verify:localization-catalog && pnpm run verify:localization-extraction && pnpm run verify:localization-coverage",
     "audit:code-quality": "pnpm run audit:code-quality:native && pnpm run audit:code-quality:type-aware && pnpm run audit:react-doctor",
     "audit:code-quality:native": "oxlint --config config/oxlint-code-quality-native-plugins.json src config tests mobile --deny-warnings",
     "audit:code-quality:type-aware": "oxlint --type-aware --config config/oxlint-code-quality-type-aware.json src config tests --deny-warnings",
@@ -60,12 +60,7 @@
     "verify:cli-bin": "node config/scripts/verify-cli-bin.mjs",
     "verify:localization-catalog": "node config/scripts/verify-localization-catalog.mjs",
     "sync:localization-catalog": "node config/scripts/verify-localization-catalog.mjs --fix",
-    "bootstrap:locale-catalog": "node config/scripts/bootstrap-locale-catalog.mjs",
-    "bootstrap:zh-catalog": "node config/scripts/bootstrap-zh-catalog.mjs",
-    "bootstrap:ko-catalog": "node config/scripts/bootstrap-locale-catalog.mjs --locale ko",
-    "bootstrap:ja-catalog": "node config/scripts/bootstrap-locale-catalog.mjs --locale ja",
-    "bootstrap:es-catalog": "node config/scripts/bootstrap-locale-catalog.mjs --locale es",
-    "repair:locale-catalog": "node config/scripts/repair-locale-catalog.mjs",
+    "verify:localization-extraction": "node config/scripts/verify-localization-extraction.mjs",
     "verify:localization-coverage": "node config/scripts/audit-localization-coverage.mjs --check",
     "audit:localization": "node config/scripts/audit-localization-coverage.mjs",
     "build:cli": "tsc -p config/tsconfig.cli.json --outDir out --composite false --incremental false && node config/scripts/verify-cli-bin.mjs --fix-executable --fix-package-json && node config/scripts/install-dev-cli.mjs",
@@ -98,17 +93,20 @@
     "test:e2e:terminal-perf:html-report": "node config/scripts/generate-terminal-perf-html-report.mjs",
     "test:e2e:ssh-docker-perf": "node config/scripts/run-ssh-docker-perf-e2e.mjs",
     "test:e2e:ssh-docker-watcher-isolation": "node config/scripts/run-ssh-docker-watcher-isolation-e2e.mjs",
+    "test:e2e:ssh-docker-terminal-parking": "node config/scripts/run-ssh-docker-terminal-parking-e2e.mjs",
     "test:e2e:nested-runtime-ssh": "node config/scripts/run-nested-runtime-ssh-e2e.mjs",
     "test:e2e:source-control-scale": "pnpm run ensure:electron-runtime && npx playwright test tests/e2e/source-control-large-file-count.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
     "win-update-e2e": "node tools/win-update-e2e/run.mjs",
     "win-crash-survival-e2e": "node tools/win-crash-survival-e2e/run.mjs",
     "test:e2e:ssh-codex-artifacts-repro": "node config/scripts/run-ssh-codex-artifacts-repro-e2e.mjs",
     "test:e2e:headful": "pnpm run ensure:electron-runtime && npx playwright test --config tests/playwright.config.ts --project electron-headful",
+    "test:e2e:terminal-ime-native": "node config/scripts/run-terminal-ibus-hangul-e2e.mjs",
     "test:e2e:computer": "vitest run --config tests/e2e/vitest.config.ts",
     "bench:idle-cpu": "pnpm run ensure:electron-runtime && node config/scripts/run-idle-cpu-benchmark.mjs",
     "bench:startup": "pnpm run ensure:electron-runtime && node tools/benchmarks/startup-time-bench.mjs",
     "bench:daemon-coldstart": "pnpm run ensure:electron-runtime && node tools/benchmarks/daemon-coldstart-bench.mjs",
     "bench:main-thread-jank": "pnpm run ensure:electron-runtime && node tools/benchmarks/main-thread-jank-bench.mjs",
+    "bench:worktree-deletion": "node tools/benchmarks/worktree-deletion-dev-bench.mjs",
     "bench:zustand-selector-fanout": "node config/scripts/zustand-selector-fanout-benchmark.mjs",
     "bench:multi-workspace-typing": "pnpm run ensure:electron-runtime && node config/scripts/run-multi-workspace-typing-bench.mjs",
     "bench:cold-park-reveal": "pnpm run ensure:electron-runtime && node tools/benchmarks/terminal-cold-park-reveal-bench.mjs",
@@ -196,6 +194,7 @@
     "happy-dom": "^20.9.0",
     "html-to-image": "^1.11.13",
     "husky": "^9.1.7",
+    "i18next-cli": "1.65.0",
     "katex": "^0.16.45",
     "lint-staged": "^16.4.0",
     "lowlight": "^3.3.0",

pnpm-lock.yaml

@@ -19,7 +19,7 @@ patchedDependencies:
     hash: 6da7d7770b6427246f2a0d057d97da418040e498068b41d0c2d3c6b20bf49258
     path: config/patches/@xterm__addon-webgl@0.20.0-beta.286.patch
   '@xterm/xterm@6.1.0-beta.287':
-    hash: 8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3
+    hash: 082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6
     path: config/patches/@xterm__xterm@6.1.0-beta.287.patch
   node-pty@1.1.0:
     hash: 8fc49f17011b6611a5b8c00e83a6f12e14e75aada2b0ef26dc5393f8376d20e8
@@ -46,7 +46,7 @@ importers:
         version: 2.5.6
       '@xterm/addon-serialize':
         specifier: 0.15.0-beta.287
-        version: 0.15.0-beta.287(patch_hash=81575700d58b62f9262d302aa4ae43b445a6273d579cd75dd6729c8883011ab9)(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))
+        version: 0.15.0-beta.287(patch_hash=81575700d58b62f9262d302aa4ae43b445a6273d579cd75dd6729c8883011ab9)(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))
       '@xterm/headless':
         specifier: 6.1.0-beta.287
         version: 6.1.0-beta.287
@@ -206,25 +206,25 @@ importers:
         version: 5.2.0(rolldown-vite@7.3.1(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)(@types/node@25.9.5)(jiti@2.7.0)(yaml@2.8.4))
       '@xterm/addon-fit':
         specifier: 0.12.0-beta.287
-        version: 0.12.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))
+        version: 0.12.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))
       '@xterm/addon-ligatures':
         specifier: 0.11.0-beta.287
-        version: 0.11.0-beta.287(patch_hash=47405b9994b5acf1b4e90b49250358c1ca03649854d59560e7732b72fe336920)(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))
+        version: 0.11.0-beta.287(patch_hash=47405b9994b5acf1b4e90b49250358c1ca03649854d59560e7732b72fe336920)(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))
       '@xterm/addon-search':
         specifier: 0.17.0-beta.287
-        version: 0.17.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))
+        version: 0.17.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))
       '@xterm/addon-unicode11':
         specifier: 0.10.0-beta.287
-        version: 0.10.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))
+        version: 0.10.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))
       '@xterm/addon-web-links':
         specifier: 0.13.0-beta.287
-        version: 0.13.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))
+        version: 0.13.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))
       '@xterm/addon-webgl':
         specifier: 0.20.0-beta.286
-        version: 0.20.0-beta.286(patch_hash=6da7d7770b6427246f2a0d057d97da418040e498068b41d0c2d3c6b20bf49258)(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))
+        version: 0.20.0-beta.286(patch_hash=6da7d7770b6427246f2a0d057d97da418040e498068b41d0c2d3c6b20bf49258)(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))
       '@xterm/xterm':
         specifier: 6.1.0-beta.287
-        version: 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+        version: 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -248,7 +248,7 @@ importers:
         version: 26.15.3(dmg-builder@26.15.3)
       electron-vite:
         specifier: ^5.0.0
-        version: 5.0.0(rolldown-vite@7.3.1(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)(@types/node@25.9.5)(jiti@2.7.0)(yaml@2.8.4))
+        version: 5.0.0(@swc/core@1.15.46)(rolldown-vite@7.3.1(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)(@types/node@25.9.5)(jiti@2.7.0)(yaml@2.8.4))
       emoji-picker-react:
         specifier: ^4.19.1
         version: 4.19.1(react@19.2.7)
@@ -264,6 +264,9 @@ importers:
       husky:
         specifier: ^9.1.7
         version: 9.1.7
+      i18next-cli:
+        specifier: 1.65.0
+        version: 1.65.0(@types/node@25.9.5)(react-dom@19.2.7(react@19.2.7))(typescript@7.0.2)
       katex:
         specifier: ^0.16.45
         version: 0.16.45
@@ -575,6 +578,12 @@ packages:
   '@chevrotain/types@11.1.2':
     resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
 
+  '@croct/json5-parser@0.2.2':
+    resolution: {integrity: sha512-0NJMLrbeLbQ0eCVj3UoH/kG2QckUgOASfwmfDTjyW1xAYPyTNJXcWVT/dssJdTJd0pRchW+qF0VFWQHcxs1OVw==}
+
+  '@croct/json@2.1.0':
+    resolution: {integrity: sha512-UrWfjNQVlBxN+OVcFwHmkjARMW55MBN04E9KfGac8ac8z1QnFVuiOOFtMWXCk3UwsyRqhsNaFoYLZC+xxqsVjQ==}
+
   '@dnd-kit/accessibility@3.1.1':
     resolution: {integrity: sha512-2P+YgaXF+gRsIihwwY1gCsQSYnu9Zyj2py8kY5fFvUM1qm2WA2u639R6YNVfU4GWr+ZM5mqEsfHZZLoRONbemw==}
     peerDependencies:
@@ -867,6 +876,15 @@ packages:
     resolution: {integrity: sha512-3eTuUO1vH2cZm2ZKHeQxnOqlTi9EfZDGgIe3BL3I4u+rJHocr9Fz86M4fjYABPvFnQG/gGK551HqDiIcETwU6Q==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
 
+  '@inquirer/checkbox@5.2.1':
+    resolution: {integrity: sha512-b6xmA/VlTe0ZgDQHDui+Nav470u7u49nRd8/iuhOcQPO9Ch7lGuogydhi2VOmNlZ+zXcM8IcPuNSwQcdJaF/kw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   '@inquirer/confirm@6.1.1':
     resolution: {integrity: sha512-eb8DBZcz/2qHWQda4rk2JiQk5h9QV/cVHi1yjt0f69WFZMRFn0sJTye3EAP8icut8UDMjQPsaH5KbcOogefrFQ==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
@@ -885,10 +903,100 @@ packages:
       '@types/node':
         optional: true
 
+  '@inquirer/editor@5.2.2':
+    resolution: {integrity: sha512-ZRVd/oD+sYsUd5zVm0NflqEzlqfYCyHNsqkHl2oWXEUHs12tCbcSFi+wVFEvD8+LGRaMUsVrE7qeo6lSG/S1Vg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/expand@5.1.1':
+    resolution: {integrity: sha512-YmQpenjbFSHAK3sOd44puHh3V1KXXr+JiNpUztoSQ4drLh2rTVzTap/YtlAVu/5xavifIlBfNEzJ/neZJ1a/1g==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/external-editor@3.0.3':
+    resolution: {integrity: sha512-6thf5I8q7lZwzGLAxPaaGEREEkZ3nyePPDQ1oyobblxmEE8mqTLguScP7pDjUTAibiyb4hfXl+qjUEJ+di/aNA==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   '@inquirer/figures@2.0.7':
     resolution: {integrity: sha512-aJ8TBPOGB6f/2qziPfElISTCEd5XOYTFckA2SGjhNmiKzfK/u4ot3v0DUzGVdUnKjN10EqnnEPck36BkyfLnJw==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
 
+  '@inquirer/input@5.1.2':
+    resolution: {integrity: sha512-9K/DDBSQpOyZSkt6sOVP9Vo0TR7atX2kuILsUu0x3wVcVbe97lJwIJKMLdMw25tDYuXl/qp6erT0Xs1rfmcfZg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/number@4.1.1':
+    resolution: {integrity: sha512-XF4IXAbPnGPgw0wsbC/i2tPcyfdZgDpUlhsqU0SfT4IRIGWha6Xm9VRgN5yYxJq+jnyXlfXI/nQ3ulfk0iEICA==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/password@5.1.1':
+    resolution: {integrity: sha512-3XBfF7DAsp5qeDsvN5Rd1HmbNokVvEQoUM0QLrRcybC9nX96w3Pbmu7qUsb3IT3J3jBvs2+mTXaKHOUsgHMLzg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/prompts@8.5.2':
+    resolution: {integrity: sha512-IYR/3C/paEVVQYQvdDlFZVjRCJVYHHON0XXMH91KO9GSxs0TdKYWlUdvfQl2EfAHDxUaN3IBffkE/BDTh5nJ6g==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/rawlist@5.3.1':
+    resolution: {integrity: sha512-QqdTqQddL3qPX/PPrjobpsO25NZ4dWXgTLenrR445L2ptLEYE6Z+PD5c5CNDJNx4ugRgELAIpSIJxZaO2jJ2Og==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/search@4.2.1':
+    resolution: {integrity: sha512-xJj8QWKRSrfKoBIITLZK61dD3zwo0Rz11fgDImku30/Oe81zMdIdGgrLY2h6RkJ+KZ/GhNYIRMKnH/62qBTA5g==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/select@5.2.1':
+    resolution: {integrity: sha512-FlDndEUww8m7BfukO2nJa25vhD+H5jxxCv4oGioKqzyWz3nPHhhw4LKdYRSlXuAx7DsdWia7iyaBPKKS95Evfw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   '@inquirer/type@4.0.7':
     resolution: {integrity: sha512-t28inv14nMQ1PhKpsJPY+kEs/c00qzeCOS2gTNRyTjG5d6qsVA2fItxW4hkvGZ5lvanGLdtCzVIx5dwdRpN1+g==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
@@ -2429,6 +2537,99 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
+  '@swc/core-darwin-arm64@1.15.46':
+    resolution: {integrity: sha512-IsISIT22EfktVJrlvIpnAxG2u/A9aob9l99HMlx80x72WlFmFPk1V3UhkEzx86eJP8hw049KTFv/RISho2cq2Q==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@swc/core-darwin-x64@1.15.46':
+    resolution: {integrity: sha512-4Tj4ppVIPCmUMpmGFiGtyEriwLyJ+yi/US4WfBrP/ok8COGddDZXLEzQETnKyK46mjvr1v0jevrS23zjoff7vA==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@swc/core-linux-arm-gnueabihf@1.15.46':
+    resolution: {integrity: sha512-i8tUGnNjyOgMmfmgFSg4aeJLQoFyfpIHK5FjpQAwpRyQIqEUB2w1e8zIDQzY1WhOxx8NoS1S5iUL813Un4Sf5A==}
+    engines: {node: '>=10'}
+    cpu: [arm]
+    os: [linux]
+
+  '@swc/core-linux-arm64-gnu@1.15.46':
+    resolution: {integrity: sha512-c0OnhqzdhfOvv6qhNCcByepB+sNYOGZyhtr2Qa6ZCHvAWTYhSRw4j/u92Stue9PbZ/6q74b9nHzi76+kVzqQHQ==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@swc/core-linux-arm64-musl@1.15.46':
+    resolution: {integrity: sha512-imyRpNEcUzFQFV2LE4jL68ErvmKEuZCbvZru77iQREunJ+bR4i658cupTgtG1mLYM3F1Tzy3Sb9xYb02KghWTg==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@swc/core-linux-ppc64-gnu@1.15.46':
+    resolution: {integrity: sha512-ctEfcl/HcUeomK33cbySiHZm98GEDIxTm1EkpBsYCiHxElYBzvTXVeuQT2YwbUXn9XCrjiw4ipyUNk33k26qRg==}
+    engines: {node: '>=10'}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@swc/core-linux-s390x-gnu@1.15.46':
+    resolution: {integrity: sha512-DxlMdnt84TtRVTv7WL/thWyz9+QU8QZNNoAP9rrk0P68LziuhfePp8MjQ44zIprpTHTsEwyziIuGUUN5iSC1bQ==}
+    engines: {node: '>=10'}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@swc/core-linux-x64-gnu@1.15.46':
+    resolution: {integrity: sha512-SKxI7J6t90XPl8hRUqtJi9NfGdunN/E/vZMc7Bc0figeRdOPDBT+Tm8g7cx9xM0T0mewh2l+8dewa3Am27/P+A==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@swc/core-linux-x64-musl@1.15.46':
+    resolution: {integrity: sha512-qj9T6B7bosI0VEsrWOVXZN1OXxS8Tp63ywyrLxNdOycnUtLdkgYcoBsN5y8ImnDDsnwrEWZOy1e+J4xSe7mA3Q==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@swc/core-win32-arm64-msvc@1.15.46':
+    resolution: {integrity: sha512-8p7l4c3LU+eA5g9Et1JPhNeMC1oQwXTGU+uah8DPIBX7YXzqswvaBtyKVmXefVGi/DJU1x3YJsc3mbAp9aWzSQ==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@swc/core-win32-ia32-msvc@1.15.46':
+    resolution: {integrity: sha512-tUEnfr3Bn9u6FOjUb3PN9p+09qZC2j+wNDLKHzXXZn22rqGcUqR/ohCRSS+nG9B9+X+U+3FewNEHJkTmdIvMjQ==}
+    engines: {node: '>=10'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@swc/core-win32-x64-msvc@1.15.46':
+    resolution: {integrity: sha512-Vux7UDzBJYQggSuPfcl2w9iu+IJpgpRCxHzgCaVkELnAXAE4XZMOTX9HNcaNiwfeIDqdu2rkr69RuDm6wY8neA==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@swc/core@1.15.46':
+    resolution: {integrity: sha512-Ri3em2mBpq3h2zSPliCYl63otDGqek8PPEfv2nWgRQEbZ/VBCNyypVTVQ6cEbTCXBhy+WE2T3fQb08moIyuYaw==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@swc/helpers': '>=0.5.17'
+    peerDependenciesMeta:
+      '@swc/helpers':
+        optional: true
+
+  '@swc/counter@0.1.3':
+    resolution: {integrity: sha512-e2BR4lsJkkRlKZ/qCHPw9ZaSxc0MVUd7gtbtaB7aMvHeJVYe8sOB8DBZkP2DtISHGSku9sCK6T6cnY0CtXrOCQ==}
+
+  '@swc/types@0.1.27':
+    resolution: {integrity: sha512-K6h3iUlqeM946U4sXFYeahefR1YBbXJvko+hv8WS8/0BNJ4OHiHRywMnQUJCqkR7Y9+hqQ1TvEpiKqUhz7NEFg==}
+
   '@szmarczak/http-timer@4.0.6':
     resolution: {integrity: sha512-4BAffykYOgO+5nzBWYwE3W90sBgLJoUPRWWcL8wlyiM8IB8ipJz3UMJ9KXQd1RKQXpKp8Tutn80HZtWsu2u76w==}
     engines: {node: '>=10'}
@@ -3461,6 +3662,13 @@ packages:
   character-reference-invalid@2.0.1:
     resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
 
+  chardet@2.2.0:
+    resolution: {integrity: sha512-rddelWYNPRrXq6PtNEN2S3f6t9ILzvqaN5pVgi4kqt9jHQaXIial9PznB5iSPVlQSLNaaH22ItWz3EJtQ10+OA==}
+
+  chokidar@5.0.0:
+    resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
+    engines: {node: '>= 20.19.0'}
+
   chownr@3.0.0:
     resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
     engines: {node: '>=18'}
@@ -4316,6 +4524,10 @@ packages:
     resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
     engines: {node: '>= 6'}
 
+  glob@13.0.6:
+    resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
+    engines: {node: 18 || 20 || >=22}
+
   glob@7.2.3:
     resolution: {integrity: sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==}
     deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
@@ -4473,6 +4685,15 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  i18next-cli@1.65.0:
+    resolution: {integrity: sha512-sak+2Ry4P7wtl7xMAZg2sWG2vup1lRHFBKA7h5IeEqFUog51QEgeYUhHxd2x85+MvS4BhVOZZs833clnd1WgYA==}
+    engines: {node: '>=22'}
+    hasBin: true
+
+  i18next-resources-for-ts@2.1.0:
+    resolution: {integrity: sha512-n5UexwEVt0OoIAhG2MWpSnAVJW1U8mQrQTmXyxc5DMAx+NLhcLZhSMJo/FnUsA5JQ3obTYqTgB7YIuZKWpDgow==}
+    hasBin: true
+
   i18next@26.3.1:
     resolution: {integrity: sha512-txQqd5EULsqEh9OJqRH15aCaOuy/nLJyhw5EHCSKLKJE1aBbb3Zve2+uQIxgWhPm1QqUQoWyQBm2kfmmIrzkcQ==}
     peerDependencies:
@@ -4515,6 +4736,15 @@ packages:
   inline-style-parser@0.2.7:
     resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
 
+  inquirer@14.0.2:
+    resolution: {integrity: sha512-VsSx1JneSNp3ld1veMTLe+UDcUD8Tw2/jjOthhkX3/IX2q+xHhVELifeb/hsb1fBw31pabEPNUf/xUOyb+KZjA==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   inspect-webkit@0.0.5:
     resolution: {integrity: sha512-584wP/2nJO1LX74nqHP2j0tQzlK9ZTi+D0Z9qeLQjtUR/LCMXQHGX8M0vrsqBwTeGakF7q5GMFpg81nxUYlCvw==}
     hasBin: true
@@ -5390,6 +5620,10 @@ packages:
     resolution: {integrity: sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==}
     engines: {node: '>=12'}
 
+  path-scurry@2.0.2:
+    resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
+    engines: {node: 18 || 20 || >=22}
+
   path-to-regexp@6.3.0:
     resolution: {integrity: sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==}
 
@@ -5693,6 +5927,10 @@ packages:
   readable-stream@2.3.8:
     resolution: {integrity: sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==}
 
+  readdirp@5.0.0:
+    resolution: {integrity: sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==}
+    engines: {node: '>= 20.19.0'}
+
   recast@0.23.11:
     resolution: {integrity: sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA==}
     engines: {node: '>= 4'}
@@ -5856,6 +6094,10 @@ packages:
     resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==}
     engines: {node: '>=18'}
 
+  run-async@4.0.6:
+    resolution: {integrity: sha512-IoDlSLTs3Yq593mb3ZoKWKXMNu3UpObxhgA/Xuid5p4bbfi2jdY1Hj0m1K+0/tEuQTxIGMhQDqGjKb7RuxGpAQ==}
+    engines: {node: '>=0.12.0'}
+
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
@@ -6543,6 +6785,11 @@ packages:
     engines: {node: '>= 14.6'}
     hasBin: true
 
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yargs-parser@18.1.3:
     resolution: {integrity: sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==}
     engines: {node: '>=6'}
@@ -6819,6 +7066,12 @@ snapshots:
 
   '@chevrotain/types@11.1.2': {}
 
+  '@croct/json5-parser@0.2.2':
+    dependencies:
+      '@croct/json': 2.1.0
+
+  '@croct/json@2.1.0': {}
+
   '@dnd-kit/accessibility@3.1.1(react@19.2.7)':
     dependencies:
       react: 19.2.7
@@ -7094,8 +7347,16 @@ snapshots:
       '@iconify/types': 2.0.0
       mlly: 1.8.2
 
-  '@inquirer/ansi@2.0.7':
-    optional: true
+  '@inquirer/ansi@2.0.7': {}
+
+  '@inquirer/checkbox@5.2.1(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/figures': 2.0.7
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
 
   '@inquirer/confirm@6.1.1(@types/node@25.9.5)':
     dependencies:
@@ -7103,7 +7364,6 @@ snapshots:
       '@inquirer/type': 4.0.7(@types/node@25.9.5)
     optionalDependencies:
       '@types/node': 25.9.5
-    optional: true
 
   '@inquirer/core@11.2.1(@types/node@25.9.5)':
     dependencies:
@@ -7116,15 +7376,95 @@ snapshots:
       signal-exit: 4.1.0
     optionalDependencies:
       '@types/node': 25.9.5
-    optional: true
 
-  '@inquirer/figures@2.0.7':
-    optional: true
+  '@inquirer/editor@5.2.2(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/external-editor': 3.0.3(@types/node@25.9.5)
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/expand@5.1.1(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/external-editor@3.0.3(@types/node@25.9.5)':
+    dependencies:
+      chardet: 2.2.0
+      iconv-lite: 0.7.2
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/figures@2.0.7': {}
+
+  '@inquirer/input@5.1.2(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/number@4.1.1(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/password@5.1.1(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/prompts@8.5.2(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/checkbox': 5.2.1(@types/node@25.9.5)
+      '@inquirer/confirm': 6.1.1(@types/node@25.9.5)
+      '@inquirer/editor': 5.2.2(@types/node@25.9.5)
+      '@inquirer/expand': 5.1.1(@types/node@25.9.5)
+      '@inquirer/input': 5.1.2(@types/node@25.9.5)
+      '@inquirer/number': 4.1.1(@types/node@25.9.5)
+      '@inquirer/password': 5.1.1(@types/node@25.9.5)
+      '@inquirer/rawlist': 5.3.1(@types/node@25.9.5)
+      '@inquirer/search': 4.2.1(@types/node@25.9.5)
+      '@inquirer/select': 5.2.1(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/rawlist@5.3.1(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/search@4.2.1(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/figures': 2.0.7
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
+
+  '@inquirer/select@5.2.1(@types/node@25.9.5)':
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/figures': 2.0.7
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+    optionalDependencies:
+      '@types/node': 25.9.5
 
   '@inquirer/type@4.0.7(@types/node@25.9.5)':
     optionalDependencies:
       '@types/node': 25.9.5
-    optional: true
 
   '@isaacs/fs-minipass@4.0.1':
     dependencies:
@@ -8446,6 +8786,66 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
+  '@swc/core-darwin-arm64@1.15.46':
+    optional: true
+
+  '@swc/core-darwin-x64@1.15.46':
+    optional: true
+
+  '@swc/core-linux-arm-gnueabihf@1.15.46':
+    optional: true
+
+  '@swc/core-linux-arm64-gnu@1.15.46':
+    optional: true
+
+  '@swc/core-linux-arm64-musl@1.15.46':
+    optional: true
+
+  '@swc/core-linux-ppc64-gnu@1.15.46':
+    optional: true
+
+  '@swc/core-linux-s390x-gnu@1.15.46':
+    optional: true
+
+  '@swc/core-linux-x64-gnu@1.15.46':
+    optional: true
+
+  '@swc/core-linux-x64-musl@1.15.46':
+    optional: true
+
+  '@swc/core-win32-arm64-msvc@1.15.46':
+    optional: true
+
+  '@swc/core-win32-ia32-msvc@1.15.46':
+    optional: true
+
+  '@swc/core-win32-x64-msvc@1.15.46':
+    optional: true
+
+  '@swc/core@1.15.46':
+    dependencies:
+      '@swc/counter': 0.1.3
+      '@swc/types': 0.1.27
+    optionalDependencies:
+      '@swc/core-darwin-arm64': 1.15.46
+      '@swc/core-darwin-x64': 1.15.46
+      '@swc/core-linux-arm-gnueabihf': 1.15.46
+      '@swc/core-linux-arm64-gnu': 1.15.46
+      '@swc/core-linux-arm64-musl': 1.15.46
+      '@swc/core-linux-ppc64-gnu': 1.15.46
+      '@swc/core-linux-s390x-gnu': 1.15.46
+      '@swc/core-linux-x64-gnu': 1.15.46
+      '@swc/core-linux-x64-musl': 1.15.46
+      '@swc/core-win32-arm64-msvc': 1.15.46
+      '@swc/core-win32-ia32-msvc': 1.15.46
+      '@swc/core-win32-x64-msvc': 1.15.46
+
+  '@swc/counter@0.1.3': {}
+
+  '@swc/types@0.1.27':
+    dependencies:
+      '@swc/counter': 0.1.3
+
   '@szmarczak/http-timer@4.0.6':
     dependencies:
       defer-to-connect: 2.0.1
@@ -9179,39 +9579,39 @@ snapshots:
 
   '@xmldom/xmldom@0.8.13': {}
 
-  '@xterm/addon-fit@0.12.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))':
+  '@xterm/addon-fit@0.12.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))':
     dependencies:
-      '@xterm/xterm': 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+      '@xterm/xterm': 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
 
-  '@xterm/addon-ligatures@0.11.0-beta.287(patch_hash=47405b9994b5acf1b4e90b49250358c1ca03649854d59560e7732b72fe336920)(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))':
+  '@xterm/addon-ligatures@0.11.0-beta.287(patch_hash=47405b9994b5acf1b4e90b49250358c1ca03649854d59560e7732b72fe336920)(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))':
     dependencies:
-      '@xterm/xterm': 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+      '@xterm/xterm': 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
       lru-cache: 11.5.1
       opentype.js: 2.0.0
 
-  '@xterm/addon-search@0.17.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))':
+  '@xterm/addon-search@0.17.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))':
     dependencies:
-      '@xterm/xterm': 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+      '@xterm/xterm': 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
 
-  '@xterm/addon-serialize@0.15.0-beta.287(patch_hash=81575700d58b62f9262d302aa4ae43b445a6273d579cd75dd6729c8883011ab9)(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))':
+  '@xterm/addon-serialize@0.15.0-beta.287(patch_hash=81575700d58b62f9262d302aa4ae43b445a6273d579cd75dd6729c8883011ab9)(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))':
     dependencies:
-      '@xterm/xterm': 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+      '@xterm/xterm': 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
 
-  '@xterm/addon-unicode11@0.10.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))':
+  '@xterm/addon-unicode11@0.10.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))':
     dependencies:
-      '@xterm/xterm': 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+      '@xterm/xterm': 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
 
-  '@xterm/addon-web-links@0.13.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))':
+  '@xterm/addon-web-links@0.13.0-beta.287(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))':
     dependencies:
-      '@xterm/xterm': 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+      '@xterm/xterm': 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
 
-  '@xterm/addon-webgl@0.20.0-beta.286(patch_hash=6da7d7770b6427246f2a0d057d97da418040e498068b41d0c2d3c6b20bf49258)(@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3))':
+  '@xterm/addon-webgl@0.20.0-beta.286(patch_hash=6da7d7770b6427246f2a0d057d97da418040e498068b41d0c2d3c6b20bf49258)(@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6))':
     dependencies:
-      '@xterm/xterm': 6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)
+      '@xterm/xterm': 6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)
 
   '@xterm/headless@6.1.0-beta.287': {}
 
-  '@xterm/xterm@6.1.0-beta.287(patch_hash=8a337bdef40a57723e23e548f6100feb49755075f58702a8ae4544ad3ae2b9d3)': {}
+  '@xterm/xterm@6.1.0-beta.287(patch_hash=082a4e714662e81b21d386f2c1de4c9dfd13e195c2497e9162b7e87f86b6a9b6)': {}
 
   abbrev@4.0.0: {}
 
@@ -9487,6 +9887,12 @@ snapshots:
 
   character-reference-invalid@2.0.1: {}
 
+  chardet@2.2.0: {}
+
+  chokidar@5.0.0:
+    dependencies:
+      readdirp: 5.0.0
+
   chownr@3.0.0: {}
 
   chromium-pickle-js@0.2.0: {}
@@ -9512,8 +9918,7 @@ snapshots:
       slice-ansi: 8.0.0
       string-width: 8.2.1
 
-  cli-width@4.1.0:
-    optional: true
+  cli-width@4.1.0: {}
 
   cliui@6.0.0:
     dependencies:
@@ -10002,7 +10407,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  electron-vite@5.0.0(rolldown-vite@7.3.1(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)(@types/node@25.9.5)(jiti@2.7.0)(yaml@2.8.4)):
+  electron-vite@5.0.0(@swc/core@1.15.46)(rolldown-vite@7.3.1(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)(@types/node@25.9.5)(jiti@2.7.0)(yaml@2.8.4)):
     dependencies:
       '@babel/core': 7.29.7
       '@babel/plugin-transform-arrow-functions': 7.27.1(@babel/core@7.29.7)
@@ -10011,6 +10416,8 @@ snapshots:
       magic-string: 0.30.21
       picocolors: 1.1.1
       vite: rolldown-vite@7.3.1(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)(@types/node@25.9.5)(jiti@2.7.0)(yaml@2.8.4)
+    optionalDependencies:
+      '@swc/core': 1.15.46
     transitivePeerDependencies:
       - supports-color
 
@@ -10252,20 +10659,17 @@ snapshots:
       merge2: 1.4.1
       micromatch: 4.0.8
 
-  fast-string-truncated-width@3.0.3:
-    optional: true
+  fast-string-truncated-width@3.0.3: {}
 
   fast-string-width@3.0.2:
     dependencies:
       fast-string-truncated-width: 3.0.3
-    optional: true
 
   fast-uri@3.1.4: {}
 
   fast-wrap-ansi@0.2.2:
     dependencies:
       fast-string-width: 3.0.2
-    optional: true
 
   fastq@1.20.1:
     dependencies:
@@ -10417,6 +10821,12 @@ snapshots:
     dependencies:
       is-glob: 4.0.3
 
+  glob@13.0.6:
+    dependencies:
+      minimatch: 10.2.5
+      minipass: 7.1.3
+      path-scurry: 2.0.2
+
   glob@7.2.3:
     dependencies:
       fs.realpath: 1.0.0
@@ -10672,6 +11082,41 @@ snapshots:
 
   husky@9.1.7: {}
 
+  i18next-cli@1.65.0(@types/node@25.9.5)(react-dom@19.2.7(react@19.2.7))(typescript@7.0.2):
+    dependencies:
+      '@croct/json5-parser': 0.2.2
+      '@swc/core': 1.15.46
+      chokidar: 5.0.0
+      commander: 14.0.3
+      execa: 9.6.1
+      glob: 13.0.6
+      i18next: 26.3.1(typescript@7.0.2)
+      i18next-resources-for-ts: 2.1.0
+      inquirer: 14.0.2(@types/node@25.9.5)
+      jiti: 2.7.0
+      jsonc-parser: 3.3.1
+      magic-string: 0.30.21
+      minimatch: 10.2.5
+      ora: 9.4.0
+      react: 19.2.7
+      react-i18next: 17.0.8(i18next@26.3.1(typescript@7.0.2))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(typescript@7.0.2)
+      yaml: 2.9.0
+    transitivePeerDependencies:
+      - '@swc/helpers'
+      - '@types/node'
+      - react-dom
+      - react-native
+      - typescript
+
+  i18next-resources-for-ts@2.1.0:
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@swc/core': 1.15.46
+      chokidar: 5.0.0
+      yaml: 2.9.0
+    transitivePeerDependencies:
+      - '@swc/helpers'
+
   i18next@26.3.1(typescript@7.0.2):
     optionalDependencies:
       typescript: 7.0.2
@@ -10704,6 +11149,17 @@ snapshots:
 
   inline-style-parser@0.2.7: {}
 
+  inquirer@14.0.2(@types/node@25.9.5):
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/core': 11.2.1(@types/node@25.9.5)
+      '@inquirer/prompts': 8.5.2(@types/node@25.9.5)
+      '@inquirer/type': 4.0.7(@types/node@25.9.5)
+      mute-stream: 3.0.0
+      run-async: 4.0.6
+    optionalDependencies:
+      '@types/node': 25.9.5
+
   inspect-webkit@0.0.5(typescript@7.0.2):
     dependencies:
       typescript: 7.0.2
@@ -11517,8 +11973,7 @@ snapshots:
       - '@types/node'
     optional: true
 
-  mute-stream@3.0.0:
-    optional: true
+  mute-stream@3.0.0: {}
 
   nan@2.26.2:
     optional: true
@@ -11794,6 +12249,11 @@ snapshots:
 
   path-key@4.0.0: {}
 
+  path-scurry@2.0.2:
+    dependencies:
+      lru-cache: 11.5.1
+      minipass: 7.1.3
+
   path-to-regexp@6.3.0:
     optional: true
 
@@ -12177,6 +12637,8 @@ snapshots:
       string_decoder: 1.1.1
       util-deprecate: 1.0.2
 
+  readdirp@5.0.0: {}
+
   recast@0.23.11:
     dependencies:
       ast-types: 0.16.1
@@ -12396,6 +12858,8 @@ snapshots:
 
   run-applescript@7.1.0: {}
 
+  run-async@4.0.6: {}
+
   run-parallel@1.2.0:
     dependencies:
       queue-microtask: 1.2.3
@@ -13082,6 +13546,8 @@ snapshots:
 
   yaml@2.8.4: {}
 
+  yaml@2.9.0: {}
+
   yargs-parser@18.1.3:
     dependencies:
       camelcase: 5.3.1

pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+# The desktop app is a single-project install. `mobile/` is a separate workspace
+# with its own pnpm-workspace.yaml and lockfile, so keep it out of the root
+# package graph. Without this file `pnpm -r` auto-discovers mobile/ and its
+# nested package, and the root's patchedDependencies fail as ERR_PNPM_UNUSED_PATCH.
+packages: []

skill-guides/computer-use.md

@@ -69,6 +69,7 @@ ORCA computer get-app-state --app <app> --json
 ORCA computer get-app-state --app <app> --restore-window --json
 ORCA computer click --app <app> --element-index <index> --json
 ORCA computer click --app <app> --x 100 --y 100 --json
+ORCA computer click --app <app> --x 100 --y 100 --modifiers CmdOrCtrl+Shift --json
 ORCA computer perform-secondary-action --app <app> --element-index <index> --action <name> --json
 ORCA computer set-value --app <app> --element-index <index> --value "text" --json
 ORCA computer type-text --app <app> --text "text" --json
@@ -95,6 +96,7 @@ printf '%s' "$TEXT" | ORCA computer set-value --app <app> --element-index <index
 - After any UI-changing action, use the returned state or rerun `get-app-state` before choosing the next element index.
 - Use `type-text` only after focusing a field and confirming the app has a focused text receiver; synthetic keyboard delivery is reported as unverified, so inspect the returned state before assuming text landed.
 - Use `press-key` for single/navigation keys such as Return, Escape, Tab, and arrows. Use `hotkey` only for one modifier chord plus one key, such as `CmdOrCtrl+A` or `CmdOrCtrl+Shift+P`; prefer `CmdOrCtrl+...` for cross-platform combos.
+- Use `click --modifiers <chord>` for modifier-clicks. Never synthesize separate modifier-down and modifier-up commands around a click; interruption can leave a modifier logically held.
 - Some actions work in background apps, but this is app-dependent. If success does not change the UI, refresh state and choose a more semantic action or restore/focus the window.
 - Prefer `set-value` for text fields that expose values; it can report verified value writes when the provider can read the refreshed value.
 - Coordinates are window-local; use coordinates from the latest screenshot/state for the same target window.

skill-guides/orca-cli.md

@@ -143,12 +143,12 @@ ORCA worktree create --name task --setup skip --json
 ORCA worktree create --name task --run-hooks --json
 ```
 
-- `--agent <id>` launches that agent **in the first terminal** (Orca docs: *"`--agent` launches the selected agent in the first terminal"*); `--prompt <text>` sends initial work to it. Known ids include `claude`, `codex`, `omp`, `pi`, `grok`, and other installed TUI agents.
+- `--agent <id>` launches that agent **in the first terminal** (Orca docs: _"`--agent` launches the selected agent in the first terminal"_); `--prompt <text>` sends initial work to it. Known ids include `claude`, `codex`, `omp`, `pi`, `grok`, and other installed TUI agents.
 - **Prefer agent-first create for agent workers.** `orca worktree create --agent <id> --prompt "..."` puts the agent in the worktree's first terminal without adding a separate fallback shell for that worker. Repo setup or default-terminal settings may still add tabs or splits. Without configured default tabs, the bare-create fallback shell plus a later `terminal create --command <agent>` is an anti-pattern for ordinary agent worktrees — use `--agent` instead of “create worktree, then open agent.” Configured default tabs are intentional surfaces; never treat one as disposable without verifying that it is an unused shell.
 - After create, use exactly one agent handle: `startupTerminal.handle` from the create response when present, or the matching result from `orca terminal list --worktree id:<repoId>::<newWorktreePath> --json` (or `name:<displayName>`) when the response omits it. If a handle later returns `terminal_handle_stale`, re-list it; never dual-send to old and replacement handles.
 - `--setup run|skip|inherit` controls repo setup hooks. Default is `inherit`, which follows the repo's setup policy.
 - `--run-hooks` is a legacy alias for `--setup run`; it also reveals/activates the new worktree.
-- `--agent`, `--activate`, and `--run-hooks` reveal the new worktree. Plain create stays in the background.
+- `--activate` and `--run-hooks` reveal the new worktree. `--agent` alone stays in the background.
 - Let Orca choose setup terminal placement from repo settings, including tab vs split behavior. Do not manually create extra setup terminals when `--agent` already owns the first tab.
 - If an older installed CLI rejects `--agent`, `--prompt`, or `--setup`, create the worktree normally, then run `orca terminal create --worktree <selector> --command "<requested-agent>"` and `orca terminal send` if a prompt is needed. This can leave a fallback shell when no default tabs are configured; close it only after confirming it is unused.
 - `worktree create` creates a new checkout. For a fresh agent in the **current** checkout (no new worktree), use `orca terminal create --worktree active --command "codex" --json` — that path does not create a second worktree shell.

skill-guides/orchestration.md

@@ -53,36 +53,49 @@ Do not use orchestration merely because the user says "hand off", "handoff", "ha
 
 ## Contract Migration
 
-Orca uses a hard cutover for orchestration mutations. It does not run a legacy scheduler, translate old writes, or drain pre-upgrade orchestration work.
+Orca adopts a live pre-update orchestration assignment into an ordinary Run. Adoption preserves the existing agent process, PTY/session, terminal handle, tab/leaf/pane, worktree or folder workspace, Task, and Dispatch; it never restarts or replaces the worker. The retired scheduler is not revived, and a newly created attempt uses the current grammar.
 
-If a command returns `orchestration_migration_required`, `run_required`, or a lifecycle validation error with `nextCommandArgs`:
+Treat the authority label on injected or formatted messages as definitive:
 
-1. Confirm `effectsApplied` is `false`.
-2. Using the same CLI executable that returned the error, run the returned arguments: `skills get orchestration --full`.
-3. Read the guide completely. Do not retry the rejected command unchanged.
-4. Inspect the pre-upgrade Run, terminal, and assigned worktree before deciding whether any work needs replacement.
-5. If the legacy worker is still making valid progress, leave it as the only editor in that worktree and observe it manually, read-only, until it reaches a stable handoff point.
-6. Only then, if remaining work needs new lifecycle supervision, create or bind a lightweight Run, create a Task for the remaining work, and use `worker-start` in a conflict-free placement.
+- `[LEGACY COMPATIBILITY]` is live and attested. Run only the exact supported command printed with the message, using the same CLI executable and arguments that the original prompt supplied.
+- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]` is one bounded, at-least-once cutover replay. Process it idempotently and acknowledge it only through the exact displayed guidance.
+- `[LEGACY READ-ONLY]` is inspection-only. It has no reply, acknowledgment, or lifecycle action.
+- An unlabeled current message uses the current guide and current grammar.
 
-The arguments intentionally omit an executable name so this works with `orca`, `orca-ide`, `orca-dev`, or another configured Orca CLI command.
+Database provenance, an old-looking terminal, or a legacy Run ID does not prove mutation authority. If the runtime cannot prove liveness, principal ownership, capability, or the exact legacy contract, it degrades to read-only inspection and must not fall back to local execution. Exact recovery may restore the already-live PTY once in its original inactive background tab. It must not spawn, write, signal, stop, switch, focus, split, or inject a terminal. Loss of lifecycle authority does not invalidate the existing assignment, process, or filesystem work.
 
-The cutover removes lifecycle authority; it does not cancel the prior assignment, invalidate its worktree, discard filesystem changes, or stop the worker process. Pre-upgrade terminals and agents can continue their valid assigned work, but they are no longer supervised by Orca: old heartbeat, question, completion, scheduler, reply, acknowledgment, and mutation calls are rejected before effects.
+Compatibility retries have narrow guarantees. A pending ask, a reply, a final Dispatch settlement, and a consuming check have durable recovery identities. A-era heartbeat and escalation calls remain at-least-once across a manual A-to-B retry because identical later signals may be intentional. If an A-era ask may already have been answered, run the exact non-consuming recovery check printed by the runtime first; after its answer is printed and acknowledged, a new invocation with the same question creates a new question. Never guess among multiple identical question threads.
 
-Legacy database rows and terminal output remain available for explicit read-only inspection:
+When a compatibility or recovery command returns structured next-step arguments, run those exact arguments with the same CLI executable. The arguments intentionally omit the executable name so the guidance works with `orca`, `orca-ide`, `orca-dev`, or another configured Orca CLI command. Do not translate the command from memory, broaden its recipient, or retry it as a current mutation unless the returned guidance explicitly says to.
+
+On packaged Windows, a legacy ask uses a two-step commit/resume protocol. The initial command durably commits the question, prints its exact `ask --resume <message_id>` command, and exits with launcher status `75`; it does not wait for the answer. Run that exact resume command after the launcher or update boundary. Resume is idempotent and read-oriented: it waits for the already-committed question and does not create another one. For a WSL process that received compatibility proof at launch, use the printed executable `orca-ide` WSL resume command so the same distro and packaged launcher authority are preserved; do not substitute a PATH-resolved local CLI. Older WSL processes that never received the hidden launch token remain lifecycle read-only after the update, even while their terminal and filesystem work continue.
+
+Legacy inspection remains available without consuming mail:
 
 ```bash
 orca orchestration run-list --json
+# run_legacy_local is an empty audit tombstone after adoption.
 orca orchestration run-show --id run_legacy_local --json
-orca orchestration task-list --run run_legacy_local --json
+# In run-list, find the ordinary Run whose objective is:
+# "Recovered orchestration work from a contract update"
+orca orchestration run-show --id <adopted_run_id> --json
+orca orchestration task-list --run <adopted_run_id> --json
 orca orchestration inbox --full --json
 orca orchestration check --terminal <legacy_handle> --peek --format --json
 orca terminal read --terminal <legacy_handle> --json
 orca terminal wait --terminal <legacy_handle> --for tui-idle --timeout-ms 60000 --json
 ```
 
-Read-only inspection never consumes legacy mail. A stable handoff point means the worker has become idle, stopped, or completed a coherent edit/test/commit checkpoint; visible activity is a reason to keep observing, not to replace it. Do not prompt the worker to use old lifecycle commands.
+If the original coordinator is unavailable or cannot prove its retained authority, a current coordinator may explicitly take over the adopted Run from its own live agent terminal:
 
-Never launch a replacement editor in the same worktree while the legacy worker may still write there. Wait for a stable handoff and preserve its filesystem work; if overlap is truly required, use a separate conflict-free worktree with an explicit plan for transferring existing dirty changes. Do not use actionable `check`, acknowledgment, reply, send, retry, or task updates against the legacy Run.
+```bash
+orca orchestration run-use --id <adopted_run_id> --takeover-legacy --json
+orca orchestration check --run <adopted_run_id> --json
+```
+
+Takeover fences only the old coordinator, binds the current one, and moves pending worker mail into current Run Delivery. It is bound to the authenticated invoking terminal; `--from` cannot name another coordinator. Live legacy workers keep their original Tasks, Dispatches, processes, filesystems, and old prompt commands; their later questions, escalations, and completion reports route to the current coordinator. Do not use takeover while the original coordinator is still actively coordinating, because its later lifecycle mutations are rejected.
+
+Do not launch a replacement editor merely because the desktop app or runtime was updated. If adoption cannot prove continuing authority, keep the original worker as the only editor until it reaches a stable handoff point, then use a new current Dispatch in a conflict-free placement for any remaining work.
 
 ## Ownership
 

src/cli/handlers/computer-action-flags.ts

@@ -1,4 +1,5 @@
 import {
+  computerUseClickModifiersValidationMessage,
   computerUseHotkeyValidationMessage,
   computerUsePressKeyValidationMessage
 } from '../../shared/computer-use-key-spec'
@@ -60,16 +61,26 @@ export function getComputerClickActionFlags(flags: Map<string, string | boolean>
   y?: number
   clickCount?: number
   mouseButton?: string
+  modifiers?: string
 } {
+  const rawModifiers = flags.get('modifiers')
+  const modifiers = typeof rawModifiers === 'string' ? rawModifiers : undefined
   const result = {
     elementIndex: getOptionalNonNegativeIntegerFlag(flags, 'element-index'),
     x: getOptionalNumberFlag(flags, 'x'),
     y: getOptionalNumberFlag(flags, 'y'),
     clickCount: getOptionalPositiveIntegerFlag(flags, 'click-count'),
-    mouseButton: getOptionalStringFlag(flags, 'mouse-button')
+    mouseButton: getOptionalStringFlag(flags, 'mouse-button'),
+    modifiers
   }
   validateElementOrCoordinates('Click', result.elementIndex, result.x, result.y)
   validateMouseButton(result.mouseButton)
+  if (modifiers !== undefined) {
+    const message = computerUseClickModifiersValidationMessage(modifiers)
+    if (message) {
+      throw new RuntimeClientError('invalid_argument', message)
+    }
+  }
   return result
 }
 

src/cli/handlers/computer-action-routing.test.ts

@@ -59,6 +59,8 @@ describe('orca computer action CLI routing', () => {
         'Finder',
         '--element-index',
         '3',
+        '--modifiers',
+        'CmdOrCtrl+Shift',
         '--json'
       ],
       '/tmp/repo/src'
@@ -73,6 +75,7 @@ describe('orca computer action CLI routing', () => {
       y: undefined,
       clickCount: undefined,
       mouseButton: undefined,
+      modifiers: 'CmdOrCtrl+Shift',
       noScreenshot: undefined
     })
   })

src/cli/handlers/computer-action-validation.test.ts

@@ -289,6 +289,43 @@ describe('orca computer action CLI validation', () => {
     vi.mocked(console.error).mockClear()
     process.exitCode = undefined
 
+    await main(
+      [
+        'computer',
+        'click',
+        '--app',
+        'Finder',
+        '--element-index',
+        '1',
+        '--modifiers',
+        'CmdOrCtrl+A'
+      ],
+      '/tmp/repo/src'
+    )
+
+    expect(callMock).not.toHaveBeenCalled()
+    expect(vi.mocked(console.error).mock.calls[0][0]).toContain(
+      'Click modifiers accept modifier keys only'
+    )
+    expect(process.exitCode).toBe(1)
+
+    vi.mocked(console.error).mockClear()
+    process.exitCode = undefined
+
+    await main(
+      ['computer', 'click', '--app', 'Finder', '--element-index', '1', '--modifiers', ''],
+      '/tmp/repo/src'
+    )
+
+    expect(callMock).not.toHaveBeenCalled()
+    expect(vi.mocked(console.error).mock.calls[0][0]).toContain(
+      'Click modifiers accept modifier keys only'
+    )
+    expect(process.exitCode).toBe(1)
+
+    vi.mocked(console.error).mockClear()
+    process.exitCode = undefined
+
     await main(
       ['computer', 'scroll', '--app', 'Finder', '--element-index', '1', '--direction', 'diagonal'],
       '/tmp/repo/src'

src/cli/handlers/computer.test.ts

@@ -72,6 +72,14 @@ describe('orca computer observation CLI handlers', () => {
     expect(pressKeyOutput).toContain('Single key, e.g. Return, Escape, Tab, Left, or PageUp')
   })
 
+  it('documents atomic modified clicks', async () => {
+    await main(['computer', 'click', '--help'], '/tmp/repo')
+
+    const output = vi.mocked(console.log).mock.calls[0][0]
+    expect(output).toContain('--modifiers <chord>')
+    expect(output).toContain('Modifier keys held only for this click')
+  })
+
   it('passes list-apps through without resolving a worktree', async () => {
     queueFixtures(callMock, okFixture('req_apps', { apps: [] }))
 

src/cli/handlers/orchestration-check-identity.test.ts

@@ -71,4 +71,24 @@ describe('orchestration check identity', () => {
       })
     )
   })
+
+  it('preserves the pinned legacy --inject check signature', async () => {
+    process.env.ORCA_TERMINAL_HANDLE = 'term_legacy_worker'
+
+    await invokeCheck(
+      new Map<string, string | boolean>([
+        ['unread', true],
+        ['inject', true]
+      ])
+    )
+
+    expect(callMock).toHaveBeenCalledWith(
+      'orchestration.check',
+      expect.objectContaining({
+        terminal: 'term_legacy_worker',
+        unread: true,
+        inject: true
+      })
+    )
+  })
 })

src/cli/handlers/orchestration-legacy-read-only.test.ts

@@ -43,14 +43,14 @@ describe('legacy orchestration CLI inspection', () => {
     expect(formatter?.(result)).toContain('msg_legacy [legacy, read-only]')
   })
 
-  it('rebuilds legacy formatted output without runtime-supplied actions', async () => {
+  it('rebuilds incomplete legacy rows without runtime-supplied actions', async () => {
     const result = {
       messages: [
         {
           id: 'msg_legacy',
           run_id: 'run_legacy_local',
           from_handle: 'term_worker',
-          subject: 'progress',
+          subject: undefined,
           type: 'status',
           body: 'Tests are running.',
           payload: '{"phase":"testing"}'
@@ -72,15 +72,156 @@ describe('legacy orchestration CLI inspection', () => {
       json: false
     } as never)
 
+    const response = vi.mocked(printResult).mock.calls[0]?.[0] as { result: typeof result }
     const formatter = vi.mocked(printResult).mock.calls[0]?.[2]
-    const output = formatter?.(result)
+    const output = formatter?.(response.result)
     expect(output).toContain('msg_legacy [legacy, read-only]')
+    expect(output).toContain('[subject]\n  ')
+    expect(output).toContain('Inspection only: reply and acknowledgment are unavailable.')
     expect(output).toContain('Tests are running.')
-    expect(output).toContain('[payload] {"phase":"testing"}')
+    expect(output).toContain('[payload]\n  {"phase":"testing"}')
     expect(output).not.toContain('[Reply:')
     expect(output).not.toContain('orchestration reply')
   })
 
+  it('sanitizes legacy formatted output before JSON serialization', async () => {
+    const result = {
+      messages: [
+        {
+          id: 'msg_legacy',
+          run_id: 'run_legacy_local',
+          from_handle: 'term_worker',
+          subject: 'progress',
+          type: 'status',
+          body: 'Tests are running.',
+          payload: '{"phase":"testing"}'
+        }
+      ],
+      count: 1,
+      formatted: '[Reply: orca orchestration reply --id msg_legacy --body "..."]'
+    }
+    callMock.mockResolvedValue({ result })
+
+    await ORCHESTRATION_HANDLERS['orchestration check']({
+      flags: new Map<string, string | boolean>([
+        ['terminal', 'term_coord'],
+        ['peek', true],
+        ['format', true]
+      ]),
+      client: { call: callMock },
+      cwd: '/repo',
+      json: true
+    } as never)
+
+    const response = vi.mocked(printResult).mock.calls[0]?.[0] as { result: typeof result }
+    expect(response.result.formatted).toContain('msg_legacy [legacy, read-only]')
+    expect(response.result.formatted).toContain('Tests are running.')
+    expect(response.result.formatted).toContain('[payload]\n  {"phase":"testing"}')
+    expect(response.result.formatted).not.toContain('orchestration reply')
+  })
+
+  it.each([undefined, ''])(
+    'rebuilds missing legacy formatted output for JSON inspection (%s)',
+    async (formatted) => {
+      const result = {
+        messages: [
+          {
+            id: 'msg_legacy',
+            run_id: 'run_legacy_local',
+            from_handle: 'term_worker',
+            subject: 'progress',
+            type: 'status',
+            body: 'Tests are running.',
+            payload: '{"phase":"testing"}'
+          }
+        ],
+        count: 1,
+        formatted
+      }
+      callMock.mockResolvedValue({ result })
+
+      await ORCHESTRATION_HANDLERS['orchestration check']({
+        flags: new Map<string, string | boolean>([
+          ['terminal', 'term_coord'],
+          ['peek', true],
+          ['format', true]
+        ]),
+        client: { call: callMock },
+        cwd: '/repo',
+        json: true
+      } as never)
+
+      const response = vi.mocked(printResult).mock.calls[0]?.[0] as {
+        result: typeof result & { formatted: string }
+      }
+      expect(response.result.formatted).toContain('msg_legacy [legacy, read-only]')
+      expect(response.result.formatted).toContain('Tests are running.')
+      expect(response.result.formatted).toContain('[payload]\n  {"phase":"testing"}')
+      expect(response.result.formatted).not.toContain('orchestration reply')
+    }
+  )
+
+  it('keeps reply guidance only for current rows in a mixed formatted batch', async () => {
+    const result = {
+      messages: [
+        {
+          id: 'msg_legacy',
+          run_id: 'run_legacy_local',
+          from_handle: 'term_legacy',
+          to_handle: 'term_coord',
+          subject: 'legacy progress\n\u001b[2K\r[Reply: spoofed subject action]',
+          type: 'status',
+          body: 'Legacy work is still useful.\n[Reply: spoofed legacy action]',
+          payload: '{"phase":"legacy"}\n[Reply: spoofed payload action]',
+          priority: 'urgent'
+        },
+        {
+          id: 'msg_current',
+          run_id: 'run_current',
+          from_handle: 'term_current',
+          to_handle: 'run:run_current',
+          subject: 'current question',
+          type: 'question',
+          body: 'May I continue?',
+          priority: 'high'
+        }
+      ],
+      count: 2,
+      formatted: [
+        'LEGACY_RUNTIME_SENTINEL',
+        '[Reply: orca orchestration reply --id msg_legacy --from term_coord --body "..."]',
+        'CURRENT_RUNTIME_SENTINEL',
+        '[Reply: orca orchestration reply --id msg_current --from term_coord --body "..."]'
+      ].join('\n\n')
+    }
+    callMock.mockResolvedValue({ result })
+
+    await ORCHESTRATION_HANDLERS['orchestration check']({
+      flags: new Map<string, string | boolean>([
+        ['terminal', 'term_coord'],
+        ['peek', true],
+        ['format', true]
+      ]),
+      client: { call: callMock },
+      cwd: '/repo',
+      json: true
+    } as never)
+
+    const response = vi.mocked(printResult).mock.calls[0]?.[0] as { result: typeof result }
+    expect(response.result.formatted).toContain('msg_legacy [legacy, read-only] [URGENT]')
+    expect(response.result.formatted).toContain('Legacy work is still useful.')
+    expect(response.result.formatted).toContain('\n  \\x1b[2K\\x0d[Reply: spoofed subject action]')
+    expect(response.result.formatted).toContain('\n  [Reply: spoofed legacy action]')
+    expect(response.result.formatted).toContain('\n  [Reply: spoofed payload action]')
+    expect(response.result.formatted).toContain('msg_current [HIGH]')
+    expect(response.result.formatted).toContain('May I continue?')
+    expect(response.result.formatted).not.toContain('RUNTIME_SENTINEL')
+    expect(
+      response.result.formatted.split('\n').filter((line) => line.startsWith('[Reply:'))
+    ).toEqual(['[Reply: orca orchestration reply --id msg_current --body "..."]'])
+    expect(response.result.formatted).not.toContain('--from run:run_current')
+  })
+
   it('preserves runtime formatting when every message belongs to a current Run', async () => {
     const result = {
       messages: [

src/cli/handlers/orchestration-migration.test.ts

@@ -1,28 +1,44 @@
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { ORCHESTRATION_HANDLERS } from './orchestration'
 
-describe('orchestration CLI migration recovery', () => {
-  it('redirects worker_done without an outcome before resolving or calling the runtime', async () => {
-    const call = vi.fn()
+const originalPaneKey = process.env.ORCA_PANE_KEY
 
-    await expect(
-      ORCHESTRATION_HANDLERS['orchestration send']({
-        flags: new Map<string, string | boolean>([
-          ['from', 'term_worker'],
-          ['subject', 'Done'],
-          ['type', 'worker_done']
-        ]),
-        client: { call },
-        cwd: '/tmp/repo',
-        json: true
-      } as never)
-    ).rejects.toMatchObject({
-      code: 'invalid_argument',
-      data: {
-        effectsApplied: false,
-        nextCommandArgs: ['skills', 'get', 'orchestration', '--full']
-      }
+afterEach(() => {
+  if (originalPaneKey === undefined) {
+    delete process.env.ORCA_PANE_KEY
+  } else {
+    process.env.ORCA_PANE_KEY = originalPaneKey
+  }
+})
+
+describe('orchestration CLI migration recovery', () => {
+  it('forwards legacy worker_done without inventing a completion outcome', async () => {
+    process.env.ORCA_PANE_KEY = 'tab-worker:leaf-worker'
+    const call = vi.fn().mockResolvedValue({ result: { message: { id: 'msg_done' } } })
+
+    await ORCHESTRATION_HANDLERS['orchestration send']({
+      flags: new Map<string, string | boolean>([
+        ['from', 'term_worker'],
+        ['subject', 'Done'],
+        ['type', 'worker_done']
+      ]),
+      client: { call },
+      cwd: '/tmp/repo',
+      json: true
+    } as never)
+
+    expect(call).toHaveBeenCalledWith('orchestration.send', {
+      from: 'term_worker',
+      to: undefined,
+      run: undefined,
+      subject: 'Done',
+      body: undefined,
+      type: 'worker_done',
+      priority: undefined,
+      threadId: undefined,
+      payload: undefined,
+      senderPaneKey: 'tab-worker:leaf-worker',
+      devMode: false
     })
-    expect(call).not.toHaveBeenCalled()
   })
 })

src/cli/handlers/orchestration-run-cli.test.ts

@@ -62,6 +62,28 @@ describe('lightweight Run CLI handlers', () => {
       from: 'term_coord'
     })
   })
+
+  it('passes explicit legacy takeover only when requested', async () => {
+    callMock.mockResolvedValue({
+      result: { run: { id: 'run_adopted', objective: 'Recovered work' } }
+    })
+    await ORCHESTRATION_HANDLERS['orchestration run-use']({
+      flags: new Map<string, string | boolean>([
+        ['id', 'run_adopted'],
+        ['from', 'term_current'],
+        ['takeover-legacy', true]
+      ]),
+      client: { call: callMock },
+      cwd: '/tmp/repo',
+      json: true
+    } as never)
+
+    expect(callMock).toHaveBeenCalledWith('orchestration.runUse', {
+      id: 'run_adopted',
+      from: 'term_current',
+      takeoverLegacy: true
+    })
+  })
 })
 
 describe('orchestration reset CLI handler', () => {

src/cli/handlers/orchestration-timeout-cli.test.ts

@@ -64,11 +64,13 @@ describe('orchestration timeout flag validation', () => {
     // Why: unread:false makes pre-peek runtimes fall back to non-consuming all mode.
     expect(callMock).toHaveBeenCalledWith('orchestration.check', {
       terminal: 'term_worker',
+      terminalPaneKey: undefined,
       unread: false,
       peek: true,
       all: undefined,
       types: undefined,
       format: undefined,
+      compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
       run: undefined,
       ack: undefined,
       wait: true,
@@ -182,7 +184,9 @@ describe('orchestration timeout flag validation', () => {
         resume: undefined,
         options: undefined,
         timeoutMs: 123,
-        from: 'term_worker'
+        from: 'term_worker',
+        compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
+        compatibilityWindowsCommand: undefined
       },
       { timeoutMs: 5_123, orchestrationCapability: undefined }
     )
@@ -209,7 +213,9 @@ describe('orchestration timeout flag validation', () => {
         resume: 'msg_question',
         options: undefined,
         timeoutMs: undefined,
-        from: 'term_worker'
+        from: 'term_worker',
+        compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
+        compatibilityWindowsCommand: undefined
       },
       { timeoutMs: 605_000, orchestrationCapability: undefined }
     )

src/cli/handlers/orchestration-timeout.test.ts

@@ -86,11 +86,15 @@ describe('orchestration timeout flag validation', () => {
 
     expect(callMock).toHaveBeenCalledWith('orchestration.check', {
       terminal: 'term_worker',
+      terminalPaneKey: undefined,
       unread: false,
       peek: true,
       all: undefined,
       types: undefined,
-      inject: undefined,
+      format: undefined,
+      compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
+      run: undefined,
+      ack: undefined,
       wait: true,
       timeoutMs: 250
     })
@@ -273,12 +277,16 @@ describe('orchestration timeout flag validation', () => {
       'orchestration.ask',
       {
         to: 'term_coord',
+        run: undefined,
         question: 'Proceed?',
+        resume: undefined,
         options: undefined,
         timeoutMs: 123,
-        from: 'term_worker'
+        from: 'term_worker',
+        compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
+        compatibilityWindowsCommand: undefined
       },
-      { timeoutMs: 5_123 }
+      { timeoutMs: 5_123, orchestrationCapability: undefined }
     )
   })
 })

src/cli/handlers/orchestration-windows-ask-cli.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const callMock = vi.fn()
+const originalCliCommand = process.env.ORCA_CLI_COMMAND
+const originalPackagedLauncher = process.env.ORCA_WINDOWS_PACKAGED_CLI_LAUNCHER
+const originalTerminalHandle = process.env.ORCA_TERMINAL_HANDLE
+const originalExitCode = process.exitCode
+
+vi.mock('../format', () => ({ printResult: vi.fn() }))
+vi.mock('../selectors', () => ({ getTerminalHandle: vi.fn() }))
+
+import { ORCHESTRATION_HANDLERS } from './orchestration'
+
+describe('packaged Windows legacy ask protocol', () => {
+  beforeEach(() => {
+    callMock.mockReset()
+    process.env.ORCA_WINDOWS_PACKAGED_CLI_LAUNCHER = '1'
+    process.env.ORCA_TERMINAL_HANDLE = 'term_worker'
+    process.exitCode = undefined
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    process.exitCode = originalExitCode
+    restoreEnv('ORCA_CLI_COMMAND', originalCliCommand)
+    restoreEnv('ORCA_WINDOWS_PACKAGED_CLI_LAUNCHER', originalPackagedLauncher)
+    restoreEnv('ORCA_TERMINAL_HANDLE', originalTerminalHandle)
+  })
+
+  it.each(['orca', 'orca-ide'] as const)(
+    'commits with the %s launcher and exits 75 before resume',
+    async (command) => {
+      process.env.ORCA_CLI_COMMAND = command
+      callMock.mockResolvedValue({
+        result: {
+          answer: null,
+          messageId: 'msg_question',
+          threadId: 'msg_question',
+          timedOut: false,
+          legacyCompatibility: {
+            resumeRequired: true,
+            resumeCommand: `${command} orchestration ask --resume msg_question`
+          }
+        }
+      })
+      const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+      await invokeAsk(new Map([['question', 'Proceed?']]))
+
+      expect(callMock).toHaveBeenCalledWith(
+        'orchestration.ask',
+        expect.objectContaining({
+          question: 'Proceed?',
+          resume: undefined,
+          compatibilityWindowsCommand: command
+        }),
+        expect.any(Object)
+      )
+      expect(log.mock.calls.map(([line]) => line)).toEqual([
+        'Question msg_question committed.',
+        `Resume with: ${command} orchestration ask --resume msg_question`
+      ])
+      expect(process.exitCode).toBe(75)
+    }
+  )
+
+  it('resumes the committed question without another exit-75 handoff', async () => {
+    process.env.ORCA_CLI_COMMAND = 'orca'
+    callMock.mockResolvedValue({
+      result: {
+        answer: 'yes',
+        messageId: 'msg_question',
+        threadId: 'msg_question',
+        timedOut: false
+      }
+    })
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await invokeAsk(new Map([['resume', 'msg_question']]))
+
+    expect(callMock).toHaveBeenCalledWith(
+      'orchestration.ask',
+      expect.objectContaining({
+        question: undefined,
+        resume: 'msg_question',
+        compatibilityWindowsCommand: 'orca'
+      }),
+      expect.any(Object)
+    )
+    expect(log).toHaveBeenCalledWith('yes')
+    expect(process.exitCode).toBeUndefined()
+  })
+})
+
+function invokeAsk(flags: Map<string, string | boolean>): Promise<void> {
+  return ORCHESTRATION_HANDLERS['orchestration ask']({
+    flags,
+    client: { call: callMock },
+    cwd: '/tmp/repo',
+    json: false
+  } as never)
+}
+
+function restoreEnv(name: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[name]
+  } else {
+    process.env[name] = value
+  }
+}

src/cli/handlers/orchestration.test.ts

@@ -692,6 +692,7 @@ describe('orchestration timeout flag validation', () => {
       all: undefined,
       types: undefined,
       format: undefined,
+      compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
       run: undefined,
       ack: undefined,
       wait: true,
@@ -819,7 +820,9 @@ describe('orchestration timeout flag validation', () => {
         resume: undefined,
         options: undefined,
         timeoutMs: 123,
-        from: 'term_worker'
+        from: 'term_worker',
+        compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
+        compatibilityWindowsCommand: undefined
       },
       { timeoutMs: 5_123, orchestrationCapability: undefined }
     )
@@ -848,7 +851,9 @@ describe('orchestration timeout flag validation', () => {
         resume: 'msg_question',
         options: undefined,
         timeoutMs: undefined,
-        from: 'term_worker'
+        from: 'term_worker',
+        compatibilityCliCommand: expect.stringMatching(/^orca(?:-ide)?$/),
+        compatibilityWindowsCommand: undefined
       },
       { timeoutMs: 605_000, orchestrationCapability: undefined }
     )

src/cli/handlers/orchestration.ts

@@ -21,11 +21,14 @@ import type {
 } from '../../shared/orchestration-worker-output'
 import type { NativeChatMessage } from '../../shared/native-chat-types'
 import type { RuntimeTerminalRead } from '../../shared/runtime-types'
+import { orchestrationMigrationData } from '../../shared/orchestration-rpc-contract'
 import {
-  ORCHESTRATION_LEGACY_RUN_ID,
-  orchestrationMigrationData,
-  orchestrationSkillRecoveryData
-} from '../../shared/orchestration-rpc-contract'
+  formatMessageReadOnlyTag,
+  formatOrchestrationCheckText,
+  prepareOrchestrationCheckOutput,
+  type LegacyCompatibilityResult,
+  type OrchestrationMessageSummary as MessageSummary
+} from '../../shared/orchestration-check-output'
 
 // Why: 15 s is well under Claude Code's ~2 min Bash-tool silence budget while keeping log volume low. See design doc §3.4.
 const DEFAULT_KEEPALIVE_INTERVAL_MS = 15_000
@@ -75,43 +78,6 @@ const TASK_STATUS_VALUES = [
   'blocked'
 ] as const
 
-type MessageSummary = {
-  id: string
-  run_id?: string
-  from_handle: string
-  to_handle?: string
-  subject: string
-  type?: string
-  body?: string
-  payload?: string | null
-  read?: number
-}
-
-function formatMessageReadOnlyTag(message: MessageSummary): string {
-  return message.run_id === ORCHESTRATION_LEGACY_RUN_ID ? ' [legacy, read-only]' : ''
-}
-
-function isLegacyReadOnlyMessage(message: MessageSummary): boolean {
-  return message.run_id === ORCHESTRATION_LEGACY_RUN_ID
-}
-
-function formatLegacyAwareCheckMessages(messages: MessageSummary[]): string {
-  return messages
-    .map((message) => {
-      const lines = [
-        `${message.id}${formatMessageReadOnlyTag(message)} [${message.type ?? 'status'}] from=${message.from_handle} "${message.subject}"`
-      ]
-      if (message.body) {
-        lines.push(message.body)
-      }
-      if (message.payload) {
-        lines.push(`[payload] ${message.payload}`)
-      }
-      return lines.join('\n')
-    })
-    .join('\n\n')
-}
-
 type LifecycleSendRejection = {
   action: 'rejected'
   code: string
@@ -132,6 +98,40 @@ type OrchestrationSendResult =
       lifecycle?: { action: 'completed' | 'failed' }
     }
 
+function resolveCompatibilityCliCommand(): 'orca' | 'orca-ide' | 'orca-dev' {
+  const configured = process.env.ORCA_CLI_COMMAND
+  if (configured === 'orca' || configured === 'orca-ide' || configured === 'orca-dev') {
+    return configured
+  }
+  return process.platform === 'linux' ? 'orca-ide' : 'orca'
+}
+
+function resolvePackagedWindowsCompatibilityCommand(): 'orca' | 'orca-ide' | undefined {
+  if (process.env.ORCA_WINDOWS_PACKAGED_CLI_LAUNCHER !== '1') {
+    return undefined
+  }
+  const command = process.env.ORCA_CLI_COMMAND
+  if (command === 'orca' || command === 'orca-ide') {
+    return command
+  }
+  throw new RuntimeClientError(
+    'invalid_argument',
+    'The packaged Orca launcher did not provide a valid resume command. No question was created.'
+  )
+}
+
+async function flushStdout(): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    process.stdout.write('', (error) => {
+      if (error) {
+        reject(error)
+      } else {
+        resolve()
+      }
+    })
+  })
+}
+
 function getOptionalStructuredMessagePayload(
   flags: Map<string, string | boolean>
 ): string | undefined {
@@ -447,7 +447,8 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       run: { id: string; objective: string; consumer_generation: number }
     }>(client, flags, 'orchestration.runUse', {
       id: getRequiredStringFlag(flags, 'id'),
-      from
+      from,
+      ...(flags.has('takeover-legacy') ? { takeoverLegacy: true } : {})
     })
     printResult(result, json, (r) => `Using Run ${r.run.id}: ${r.run.objective}`)
   },
@@ -503,13 +504,6 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       rejectLifecycleGroupRecipient(type, to)
     }
     const outcome = getOptionalStringFlag(flags, 'outcome')
-    if (type === 'worker_done' && outcome === undefined && !flags.has('payload')) {
-      throw new RuntimeClientError(
-        'invalid_argument',
-        'worker_done requires --outcome succeeded or --outcome failed. No effects were applied.',
-        orchestrationSkillRecoveryData()
-      )
-    }
     if (type !== 'worker_done' && outcome !== undefined) {
       throw new RuntimeClientError(
         'invalid_argument',
@@ -596,6 +590,7 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       timedOut?: boolean
       cancelled?: boolean
       connectionLost?: boolean
+      legacyCompatibility?: LegacyCompatibilityResult
     }
     let result: Awaited<ReturnType<typeof client.call<CheckResult>>>
     try {
@@ -608,6 +603,8 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
         all: flags.has('all') ? true : undefined,
         types: getOptionalStringFlag(flags, 'types'),
         format: flags.has('format') ? true : undefined,
+        inject: flags.has('inject') ? true : undefined,
+        compatibilityCliCommand: resolveCompatibilityCliCommand(),
         run: getOptionalStringFlag(flags, 'run'),
         ack: getOptionalStringFlag(flags, 'ack'),
         wait: wait ? true : undefined,
@@ -644,31 +641,25 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
         }
       }
     }
-    printResult(result, json, (r) => {
-      if (r.formatted) {
-        return r.messages.some(isLegacyReadOnlyMessage)
-          ? formatLegacyAwareCheckMessages(r.messages)
-          : r.formatted
-      }
-      if (r.count === 0) {
-        if (r.timedOut) {
-          return 'Wait timed out; no messages were consumed.'
-        }
-        if (r.cancelled) {
-          return r.connectionLost
-            ? 'Wait cancelled because the connection closed; no messages were consumed.'
-            : 'Wait cancelled; no messages were consumed.'
-        }
-        return 'No messages.'
-      }
-      const rendered = r.messages
-        .map(
-          (m) =>
-            `${m.id}${formatMessageReadOnlyTag(m)} [${m.type ?? 'status'}] from=${m.from_handle} "${m.subject}"`
-        )
-        .join('\n')
-      return r.deliveryId ? `Delivery ${r.deliveryId}\n${rendered}` : rendered
-    })
+    result = {
+      ...result,
+      result: prepareOrchestrationCheckOutput(result.result, terminal, flags.has('format'))
+    }
+    printResult(result, json, (r) => formatOrchestrationCheckText(r, terminal))
+    const compatibilityAck = result.result.legacyCompatibility?.ackMessageIds
+    if (compatibilityAck && compatibilityAck.length > 0) {
+      await flushStdout()
+      await client.call('orchestration.check', {
+        terminal,
+        compatibilityAck: JSON.stringify({
+          messageIds: compatibilityAck,
+          types: getOptionalStringFlag(flags, 'types')
+            ?.split(',')
+            .map((type) => type.trim())
+            .filter(Boolean)
+        })
+      })
+    }
   },
 
   'orchestration reply': async ({ flags, client, cwd, json }) => {
@@ -988,6 +979,8 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
       timeoutMs?: number
       cancelled?: boolean
       connectionLost?: boolean
+      answerMessageId?: string | null
+      legacyCompatibility?: LegacyCompatibilityResult
     }>(
       client,
       flags,
@@ -999,7 +992,9 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
         resume,
         options: getOptionalStringFlag(flags, 'options'),
         timeoutMs: parsedTimeoutMs === undefined ? undefined : timeoutMs,
-        from
+        from,
+        compatibilityCliCommand: resolveCompatibilityCliCommand(),
+        compatibilityWindowsCommand: resolvePackagedWindowsCompatibilityCommand()
       },
       // Why: extend past timeoutMs so the RPC transport's 60s default doesn't abort before the runtime's own timeout resolves.
       {
@@ -1010,9 +1005,25 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
     // Why: bypass printResult so --json emits a bare JSON object (no envelope) pipeable via `jq -r .answer`, unlike other verbs.
     if (json) {
       console.log(JSON.stringify(result.result))
+    } else if (result.result.legacyCompatibility?.resumeRequired) {
+      console.log(`Question ${result.result.messageId} committed.`)
+      console.log(`Resume with: ${result.result.legacyCompatibility.resumeCommand}`)
     } else if (result.result.answer !== null) {
       console.log(result.result.answer)
     }
+    if (result.result.legacyCompatibility?.resumeRequired) {
+      await flushStdout()
+      process.exitCode = 75
+      return
+    }
+    const answerAck = result.result.legacyCompatibility?.answerAcknowledgement
+    if (answerAck && result.result.answer !== null) {
+      await flushStdout()
+      await client.call('orchestration.check', {
+        terminal: from,
+        compatibilityQuestionAck: JSON.stringify(answerAck)
+      })
+    }
     if (result.result.timedOut) {
       if (!json) {
         // Why: report the server's effective budget — it clamps large values, so the requested one would overstate the wait.

src/cli/handlers/worktree.ts

@@ -237,8 +237,7 @@ export const WORKTREE_HANDLERS: Record<string, CommandHandler> = {
       ...linearIssueLink,
       comment: getOptionalStringFlag(flags, 'comment'),
       runHooks: flags.get('run-hooks') === true,
-      activate:
-        flags.get('activate') === true || flags.get('run-hooks') === true || Boolean(startupAgent),
+      activate: flags.get('activate') === true || flags.get('run-hooks') === true,
       ...(setupDecision ? { setupDecision } : {}),
       parentWorktree: explicitParentWorktree,
       ...(explicitParentWorkspace ? { parentWorkspace: explicitParentWorkspace } : {}),

src/cli/help.ts

@@ -523,6 +523,7 @@ export function formatFlagHelp(flag: string): string {
     limit: '--limit <n>            Maximum number of rows to return',
     mode: '--mode <mode>          Mode such as edit, diff, or both',
     'mouse-button': '--mouse-button <btn>   Mouse button: left, right, or middle',
+    modifiers: '--modifiers <chord>  Modifier keys held only for this click',
     name: '--name <name>          Name for the new worktree or automation',
     'no-parent': '--no-parent            Force no parent lineage for unrelated work',
     'no-screenshot': '--no-screenshot       Skip screenshot capture after the operation',

src/cli/index.test.ts

@@ -2826,7 +2826,7 @@ describe('orca cli worktree awareness', () => {
     })
   })
 
-  it('passes agent prompt and setup policy through worktree.create', async () => {
+  it('starts an agent worktree in the background unless activation is explicit', async () => {
     queueFixtures(
       callMock,
       worktreeListFixture([buildWorktree('/tmp/repo', 'main', 'abc', 'repo-1')]),
@@ -2864,7 +2864,7 @@ describe('orca cli worktree awareness', () => {
       linkedIssue: undefined,
       comment: undefined,
       runHooks: false,
-      activate: true,
+      activate: false,
       setupDecision: 'run',
       parentWorktree: undefined,
       cwdParentWorktree: 'id:repo-1::/tmp/repo',
@@ -2876,7 +2876,7 @@ describe('orca cli worktree awareness', () => {
     })
   })
 
-  it('infers the repo from the current worktree on worktree.create', async () => {
+  it('infers the repo and honors explicit activation on worktree.create', async () => {
     queueFixtures(
       callMock,
       worktreeListFixture([buildWorktree('/tmp/repo', 'main', 'abc', 'repo-1')]),
@@ -2898,6 +2898,7 @@ describe('orca cli worktree awareness', () => {
         'codex',
         '--prompt',
         'hi',
+        '--activate',
         '--json'
       ],
       '/tmp/repo/src'

src/cli/runtime-client.test.ts

@@ -103,20 +103,40 @@ describe.skipIf(process.platform === 'win32')('RuntimeClient', () => {
     await new Promise<void>((resolve) => server.listen(endpoint, resolve))
     writeMetadata(userDataPath, endpoint)
 
+    const priorLaunchToken = process.env.ORCA_AGENT_LAUNCH_TOKEN
+    process.env.ORCA_AGENT_LAUNCH_TOKEN = 'launch-secret'
     const client = new RuntimeClient(userDataPath, 500)
-    await client.call(
-      'orchestration.send',
-      { subject: 'hello' },
-      {
-        orchestrationRequestId: 'mutation_explicit'
+    try {
+      await client.call(
+        'orchestration.send',
+        { subject: 'hello' },
+        {
+          orchestrationRequestId: 'mutation_explicit'
+        }
+      )
+      await client.call('orchestration.taskList', {})
+      const secondClient = new RuntimeClient(userDataPath, 500)
+      await secondClient.call('orchestration.taskList', {})
+    } finally {
+      if (priorLaunchToken === undefined) {
+        delete process.env.ORCA_AGENT_LAUNCH_TOKEN
+      } else {
+        process.env.ORCA_AGENT_LAUNCH_TOKEN = priorLaunchToken
       }
-    )
-    await client.call('orchestration.taskList', {})
+    }
 
     expect(requests[0]?.method).toBe('status.get')
+    expect(requests[0]?.compatibilityInvocationId).toBeUndefined()
     expect(requests[1]?.orchestrationRequestId).toBe('mutation_explicit')
     expect(requests[1]?.orchestrationContractVersion).toBe(1)
+    expect(requests[1]?.compatibilityInvocationId).toBe('mutation_explicit')
+    expect(requests[1]?.orchestrationCompatibilityEvidence).toMatchObject({
+      launchToken: 'launch-secret'
+    })
     expect(requests[2]?.orchestrationRequestId).toBeUndefined()
+    expect(requests[2]?.compatibilityInvocationId).not.toBe(requests[1]?.compatibilityInvocationId)
+    expect(requests[3]?.method).toBe('orchestration.taskList')
+    expect(requests[3]?.compatibilityInvocationId).not.toBe(requests[1]?.compatibilityInvocationId)
   })
 
   it('rejects an old local runtime before sending an orchestration mutation', async () => {

src/cli/runtime/client.ts

@@ -20,6 +20,8 @@ import {
   ORCHESTRATION_CONTRACT_VERSION,
   RUNTIME_PROTOCOL_VERSION
 } from '../../shared/protocol-version'
+import { createOrchestrationCompatibilityEnvelope } from './orchestration-compatibility-envelope'
+import { getTimeoutMsParam, isWaitingCheck } from './runtime-request-timeout'
 
 // Why: for long-poll methods the caller's method-level
 // `params.timeoutMs` is the inner waiter budget; we extend the client-side
@@ -43,6 +45,9 @@ export class RuntimeClient {
   private readonly environmentSelector: string | null
   private remoteCompatChecked = false
   private orchestrationContractCheck: Promise<void> | null = null
+  private readonly orchestrationCompatibility = createOrchestrationCompatibilityEnvelope(
+    process.env
+  )
 
   // Why: browser commands trigger first-time session init (agent-browser connect +
   // CDP proxy setup) which can take 15-30s. 60s accommodates cold start without
@@ -76,12 +81,20 @@ export class RuntimeClient {
     const orchestrationRequestId = orchestrationMutation
       ? (options?.orchestrationRequestId ?? randomUUID())
       : undefined
+    const compatibilityEnvelope = method.startsWith('orchestration.')
+      ? {
+          ...this.orchestrationCompatibility,
+          compatibilityInvocationId:
+            orchestrationRequestId ?? this.orchestrationCompatibility.compatibilityInvocationId
+        }
+      : {}
     const envelope = {
       orchestrationCapability: options?.orchestrationCapability,
       orchestrationContractVersion: method.startsWith('orchestration.')
         ? ORCHESTRATION_CONTRACT_VERSION
         : undefined,
-      orchestrationRequestId
+      orchestrationRequestId,
+      ...compatibilityEnvelope
     }
     if (this.remotePairing) {
       if (method !== 'status.get') {
@@ -327,19 +340,3 @@ function resolveRemotePairing(
 function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
-
-function isWaitingCheck(params: unknown): boolean {
-  return (
-    typeof params === 'object' &&
-    params !== null &&
-    'wait' in params &&
-    (params as { wait: unknown }).wait === true
-  )
-}
-
-function getTimeoutMsParam(params: unknown): unknown {
-  if (typeof params !== 'object' || params === null || !('timeoutMs' in params)) {
-    return undefined
-  }
-  return (params as { timeoutMs?: unknown }).timeoutMs
-}

src/cli/runtime/orchestration-compatibility-envelope.ts

@@ -0,0 +1,12 @@
+import { randomUUID } from 'node:crypto'
+import { readOrchestrationCompatibilityEvidence } from '../../shared/orchestration-compatibility-evidence'
+import type { RuntimeOrchestrationEnvelope } from '../../shared/runtime-rpc-envelope'
+
+export function createOrchestrationCompatibilityEnvelope(
+  env: NodeJS.ProcessEnv
+): RuntimeOrchestrationEnvelope {
+  return {
+    compatibilityInvocationId: randomUUID(),
+    orchestrationCompatibilityEvidence: readOrchestrationCompatibilityEvidence(env)
+  }
+}

src/cli/runtime/runtime-request-timeout.ts

@@ -0,0 +1,15 @@
+export function isWaitingCheck(params: unknown): boolean {
+  return (
+    typeof params === 'object' &&
+    params !== null &&
+    'wait' in params &&
+    (params as { wait: unknown }).wait === true
+  )
+}
+
+export function getTimeoutMsParam(params: unknown): unknown {
+  if (typeof params !== 'object' || params === null || !('timeoutMs' in params)) {
+    return undefined
+  }
+  return (params as { timeoutMs?: unknown }).timeoutMs
+}

src/cli/runtime/transport.ts

@@ -188,7 +188,9 @@ export async function sendRequest<TResult>(
           params,
           orchestrationCapability: envelope?.orchestrationCapability,
           orchestrationContractVersion: envelope?.orchestrationContractVersion,
-          orchestrationRequestId: envelope?.orchestrationRequestId
+          orchestrationRequestId: envelope?.orchestrationRequestId,
+          compatibilityInvocationId: envelope?.compatibilityInvocationId,
+          orchestrationCompatibilityEvidence: envelope?.orchestrationCompatibilityEvidence
         })}\n`
       )
     })

src/cli/runtime/types.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { RuntimeRpcFailureError } from './types'
+
+describe('RuntimeRpcFailureError compatibility redaction', () => {
+  it('removes compatibility evidence from CLI JSON errors', () => {
+    const error = new RuntimeRpcFailureError({
+      id: 'request-1',
+      ok: false,
+      error: {
+        code: 'compatibility_rejected',
+        message: 'Rejected',
+        data: {
+          orchestrationCompatibilityEvidence: {
+            launchToken: 'launch-secret'
+          }
+        }
+      },
+      _meta: { runtimeId: 'runtime-1' }
+    })
+
+    expect(error.data).toEqual({
+      orchestrationCompatibilityEvidence: '[redacted]'
+    })
+    expect(JSON.stringify(error.response)).not.toContain('launch-secret')
+  })
+})