Sync upstream main (316b1887fd, 551 commits)

.claude/settings.json

@@ -0,0 +1,11 @@
+{
+  "extraKnownMarketplaces": {
+    "orca-agent-plugins": {
+      "source": { "source": "directory", "path": "./config/agent-plugins" }
+    }
+  },
+  "enabledPlugins": {
+    "orca-typescript@orca-agent-plugins": true,
+    "typescript-lsp@claude-plugins-official": false
+  }
+}

.gitattributes

@@ -1,6 +1,4 @@
-# A shebang plus CRLF makes vite's SSR transform emit a literal `#!` mid-module,
-# so any suite importing the script dies at load with a SyntaxError. Pin the whole
-# directory rather than the scripts that happen to have a test today.
+# CRLF shebangs break Vite's SSR transform.
 /config/scripts/**/*.mjs text eol=lf
 /skill-guides/*.md text eol=lf
 /skill-stubs/*.md text eol=lf
@@ -15,55 +13,33 @@
 *.html text eol=lf
 # Bundled plugin trees are byte-hashed; CRLF checkout would break the pinned hash.
 /resources/plugins/** text eol=lf
-# Relay assets are copied verbatim into the bundle and hashed byte-for-byte into
-# .version, which names the immutable remote install dir. A CRLF checkout makes a
-# Windows-built client disagree with a mac/Linux-built one on the same release,
-# so one host ends up with two relay trees (#17886 review).
-# Pin the bytes so a patch reads and diffs identically on every host. It is NOT
-# what makes the hash right: pnpm hashes a patch LF-normalized, so a CRLF checkout
-# cannot change it. Believing otherwise put a hand-computed raw digest in the
-# lockfile twice and broke every install (#17886).
-# These files are stored LF, which is not always the encoding they were written
-# against -- @vscode/windows-process-tree ships CRLF sources -- so any code that
-# runs `git apply` on one must force `-c core.autocrlf=input` rather than trust
-# the host's setting. See config/scripts/windows-process-tree-gyp-rebuild.mjs.
+# Keep patch diffs stable; pnpm hashes them with LF normalization.
+# CRLF upstream sources still need git -c core.autocrlf=input apply (windows-process-tree-gyp-rebuild.mjs).
 /config/patches/*.patch -text
-# Same reason, and pnpm parses these too: a CRLF checkout makes the mobile
-# patches unparseable, so Windows packaging dies on ERR_PNPM_INVALID_PATCH.
+# CRLF patches fail pnpm parsing on Windows.
 /mobile/patches/*.patch -text
-# The xterm bundle hunks also make a diff nobody can read; review the hand-written
-# source patch under xterm-src/ instead. The sibling patches stay diffable.
+# Review xterm-src/ instead of generated bundle hunks.
 /config/patches/@xterm__xterm@*.patch -diff
 /config/patches/xterm-src/*.patch text eol=lf
 # pnpm parses these unified diffs during Windows installs; keep checkout bytes stable.
 /mobile/patches/*.patch -text
-# Generated wrapper fixtures: collapse them in the PR diff so they stop drowning
-# the reviewable change, and pin LF because they are compared byte-for-byte.
-# Not -diff: the shell diff is the review surface when a wrapper does change.
+# Collapse generated wrappers but keep diffs available; tests compare LF bytes.
 /src/main/__fixtures__/shell-wrapper-snapshots/*.txt linguist-generated=true text eol=lf
-# Captured agent PTY transcripts. -text, not `text eol=lf` like the wrapper snapshots above:
-# these carry real CR and CRLF bytes as the terminal emitted them, and line-ending
-# normalisation on a Windows checkout would rewrite the evidence the fixture exists to be.
+# PTY transcripts must retain captured CR and CRLF bytes.
 /src/main/runtime/__fixtures__/*.txt -text
 /src/main/daemon/__fixtures__/pty-transcripts/*.txt -text
 /src/renderer/src/components/terminal-pane/terminal-link-transcripts/*.txt -text whitespace=cr-at-eol
-# Generated runtime English subset: compared byte-for-byte by
-# verify:localization-runtime-catalog, so a CRLF checkout would fail the gate.
+# verify:localization-runtime-catalog compares LF bytes.
 /src/renderer/src/i18n/en-runtime-required.json linguist-generated=true text eol=lf
-# Generated method->params catalog: compared byte-for-byte by
-# verify:rpc-params-catalog, so a CRLF checkout would fail the gate.
+# verify:rpc-params-catalog compares LF bytes.
 /src/shared/rpc-contract/rpc-params-catalog.generated.ts linguist-generated=true text eol=lf
-# Mobile RPC recording goldens: replay requires the file text to equal what rpc:record writes
-# (LF), so a CRLF checkout would fail every golden.
+# RPC recording goldens must match rpc:record's LF output.
 /mobile/rpc-foundation/goldens/*.json text eol=lf
-# Mobile web page source. Every text byte here is hashed into an asset digest and from
-# there into buildId, so a CRLF Windows checkout would ship a different bundle id for
-# identical source (91af2897 vs 9d78435e, measured on the bundle this replaced).
+# Mobile build IDs hash source bytes; checkout line endings must match across hosts.
 /mobile/src/** text eol=lf
 /mobile/app/** text eol=lf
 /mobile/web-entry/** text eol=lf
-# The blanket pin above would mark a future binary as text; exempt the asset types an
-# RN page actually carries.
+# Preserve binary assets under the text-pinned mobile directories.
 /mobile/src/**/*.png -text
 /mobile/src/**/*.jpg -text
 /mobile/src/**/*.jpeg -text

.github/CODEOWNERS

@@ -1,10 +1,8 @@
-# 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
 /config/i18next.config.ts @brennanb2025
 
-# The relay's deploy and operate surface: workspace, workflows, and the rollout lease action.
 /cloud/ @Jinwoo-H
 /.github/workflows/cloud-*.yml @Jinwoo-H
 /.github/actions/cloud-sql-rollout-lease/ @Jinwoo-H

.github/CONTRIBUTING.md

@@ -26,6 +26,87 @@ pnpm install
 pnpm dev
 ```
 
+### Dev Profiles and Parallel Instances
+
+`pnpm dev` in a linked Git worktree uses its own userData profile, renderer port, and remote
+debugging (CDP) port, so dev instances in different worktrees run side by side. The main checkout
+keeps the shared `orca-dev` profile. Ports are derived from the worktree path and move to the next
+free port when taken: renderer ports start at 15200 and CDP ports at 9333.
+
+On startup the runner prints one stdout line and writes the same JSON to `out/dev-instance.json`:
+
+```text
+ORCA_DEV_INSTANCE {"userData":".../orca-dev-wt/1d3830d4d3","profile":"worktree","rendererPort":15339,"rendererUrl":"http://localhost:15339","cdpPort":9513,"cdpUrl":"http://127.0.0.1:9513","repoRoot":"...","runnerPid":4242}
+```
+
+| Option                                                                  | Effect                                                     |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `pnpm dev --shared-profile` or `ORCA_DEV_PROFILE=shared`                | Use the shared `orca-dev` profile                          |
+| `pnpm dev --worktree-profile` or `ORCA_DEV_PROFILE=worktree`            | Use a per-worktree profile, including in the main checkout |
+| `ORCA_DEV_USER_DATA_PATH=<dir>`                                         | Use an explicit profile directory                          |
+| `REMOTE_DEBUGGING_PORT=<port>`, `ORCA_DEV_RENDERER_PORT=<port>`         | Pin a port                                                 |
+| `pnpm dev --seed-profile[=<dir>]` or `ORCA_DEV_SEED_PROFILE=<dir or 1>` | Seed an empty profile on first launch                      |
+
+Per-worktree profiles live in `orca-dev-wt/<hash>` next to `orca-dev` (`~/Library/Application
+Support` on macOS, `%APPDATA%` on Windows, `$XDG_CONFIG_HOME` or `~/.config` on Linux). The
+automatic storage cleanup removes them once their worktree is gone and nothing still runs from
+them. `config/scripts/orca-dev.mjs` and the `orca-dev` terminal wrapper target the profile this
+checkout's `pnpm dev` used.
+
+Seeding copies a slim set of state from another profile: projects, workspaces, settings, SSH
+targets, and the Orca account session. Terminal sessions, PTY leases, automations, caches, logs,
+and lock files are not copied, and the source profile is only read. The default source is
+`orca-dev`, or the installed app's profile when `orca-dev` is empty. Seed from `orca-dev` when you
+need the signed-in account session: dev builds cannot decrypt secrets the installed app encrypted.
+
+```bash
+pnpm dev:seed-profile [--from=<profile dir>] [--to=<profile dir>] [--reset]
+pnpm dev:fresh [--keep] [--seed-from[=<profile dir>]]   # temporary profile, removed on exit
+```
+
+### Targeting Local Tests
+
+Use a test file or directory when you know the relevant suites. For dependency-based
+feedback, Vitest can select tests affected by your edits:
+
+```bash
+pnpm test:changed src/main/runtime --maxWorkers=2
+pnpm test --changed=origin/main --maxWorkers=2
+pnpm test src/shared/app-version.test.ts --maxWorkers=2
+```
+
+`test:changed` considers staged, unstaged, and untracked files. `--changed=origin/main`
+also includes committed changes since the branch's merge base. Update that ref when
+you need a newer baseline. Both accept the same path filters and options as `pnpm test`.
+When Git reports no changed files at all, the launcher exits before starting Vitest.
+
+Local runs enable Vitest's [dependency recording](https://vitest.dev/config/experimental#experimental-recorddependencies).
+Ordinary test runs populate the cache; later changed-file runs read it instead of
+transforming every test's import graph. Records are separate for the Bun and Node
+projects and live in each checkout's `node_modules/.vite`. A test without a record
+runs when at most 100 such tests are in scope, which records them. Beyond that, as in
+a new worktree, unrecorded tests are selected with Vitest's static import graph
+instead of running all of them. Keep Vite's local test cache between runs. Use
+`--experimental.recordDependencies=false` to use the static import graph for every test.
+
+This is local feedback, not a complete regression check. Vitest records loaded
+imports, including executed dynamic imports, but cannot infer arbitrary filesystem
+reads, subprocess inputs, or externalized module dependencies. Explicitly run tests
+for changed fixtures, generated files, CLI entry points, and other indirect inputs.
+After changing imports, run the affected suites before committing those changes so
+later edits use current records. Configuration, lockfile, patch, and workspace-package
+changes rerun every test within the requested scope. CI does not enable recording;
+the existing CI selection policy is unchanged. The static graph has the same blind spots
+and also misses dynamic imports with computed specifiers, so the first changed-file run
+in a new worktree is a little less complete than later ones.
+
+`pnpm build:packages` (which `pnpm test` runs first) skips compiling workspace packages
+when their sources, build script, and compiler are unchanged and `dist` is intact.
+
+Vitest also supports [`related --run <source-files>`](https://vitest.dev/guide/cli#vitest-related)
+and dependency-aware watch mode. `pnpm test --changed` uses Git to provide the source
+inputs automatically and exits after one run.
+
 To reduce main-process rebuild CPU and memory when you do not need its source maps,
 set `ORCA_DEV_MAIN_SOURCEMAPS=0` before `pnpm dev`. In Bash/zsh:
 
@@ -37,6 +118,11 @@ In PowerShell, use `$env:ORCA_DEV_MAIN_SOURCEMAPS='0'` before `pnpm dev`.
 Remove the variable when debugging the main process with source maps. Renderer and
 preload settings are unaffected; production builds always keep their hidden main maps.
 
+`pnpm dev` serves the renderer with Vite's bundled dev mode: a few bundled chunks instead of
+thousands of module requests, so the first render and full reloads are faster. While a rebuild is
+pending, a newly opened pop-out, space, or web window may briefly get placeholder HTML. If the
+renderer misbehaves, set `ORCA_DEV_BUNDLED=0` (PowerShell: `$env:ORCA_DEV_BUNDLED='0'`) and report it.
+
 Local installs use pnpm's global virtual store: each package version is one slot
 under `~/pnpm/store` that every worktree links to, instead of a full `node_modules` per worktree.
 An existing worktree converts on its next `pnpm install`, and an older branch without the setting

.github/actions/cloud-sql-rollout-lease/gcloud-access-token.mjs

@@ -1,17 +1,6 @@
 import { execFileSync } from 'node:child_process'
 
-// DESIGN CHOICE: shell out to `gcloud auth print-access-token` instead of exchanging the
-// external_account credentials file that google-github-actions/auth writes.
-//
-// Every workflow on the Cloud SQL rollout lease already runs google-github-actions/setup-gcloud
-// right after auth (verified across all 11 mutating members), so gcloud is on PATH and already
-// bound to the federated identity. Doing the exchange ourselves would mean reimplementing the STS
-// token swap plus the service-account impersonation leg, in an action that must stay
-// zero-dependency and is duplicated by hand into a second repo. gcloud already handles every ADC
-// flavour and refreshes on its own. The metadata server is not an option: it does not exist on
-// GitHub or Blacksmith runners.
-//
-// Consequence, documented in the README: the lease step MUST come after setup-gcloud.
+// Use gcloud after setup-gcloud: it handles federated STS/impersonation and ADC refresh without dependencies or repo-local code in this duplicated action. Actions/Blacksmith runners have no metadata server.
 
 const TOKEN_REUSE_MS = 40 * 60 * 1_000 // GCP access tokens live ~60 min; re-mint well before that.
 

.github/actions/cloud-sql-rollout-lease/holder-identity.mjs

@@ -1,5 +1,4 @@
-// Who we claim to be on the lease object. Shared by main and the detached renewer so both agree
-// on the holder key without re-deriving it from a different set of environment variables.
+// Main and detached renewer must derive the same holder key from one environment contract.
 
 export function holderIdentity(explicitHolderKey) {
   const repository = process.env.GITHUB_REPOSITORY ?? 'unknown'

.github/actions/cloud-sql-rollout-lease/renew.mjs

@@ -3,8 +3,7 @@ import { createAccessTokenSource } from './gcloud-access-token.mjs'
 import { renewerLogPath } from './runner-state.mjs'
 import { CloudSqlRolloutLease, RENEW_INTERVAL_MS } from './storage-lease.mjs'
 
-// Detached renewer. `main` spawns it, `post` kills it. It rewrites expires_at on the same
-// generation-matched path as acquisition, and stops the moment the object stops being ours.
+// Detached renewer shares acquisition’s generation-matched writes; stop when ownership changes. Main starts it and post kills it.
 
 const MAX_LIFETIME_MS = 6 * 60 * 60 * 1_000 // Backstop if post never runs (runner killed).
 

.github/actions/cloud-sql-rollout-lease/runner-state.mjs

@@ -1,7 +1,6 @@
 import { appendFileSync } from 'node:fs'
 
-// Action-state and output plumbing via the runner's file protocol, so the action needs no
-// @actions/core dependency. Values are single-line by construction; anything else is rejected.
+// Use runner files without @actions/core; reject multiline values rather than corrupting their protocol.
 
 /** The detached renewer's stdio is ignored, so it appends here instead and `post` echoes it. */
 export function renewerLogPath() {

.github/actions/cloud-sql-rollout-lease/storage-lease.mjs

@@ -1,10 +1,4 @@
-// Compare-and-swap lease over a single Cloud Storage object.
-//
-// Ported from apps/relay-fence-broker/src/mutation-lease.ts rather than imported: this action is
-// duplicated verbatim into stablyai/orca, so it must carry no repo-local imports. Only the
-// algorithm is shared (read metadata -> write with ifGenerationMatch -> 412 is a conflict ->
-// generation-matched delete -> an expired record is free). The broker's token path is NOT shared;
-// it reads the GCE metadata server, which does not exist on Actions runners.
+// Ported CAS algorithm from relay-fence-broker/mutation-lease.ts: keep repo-local imports out of this duplicated action. Broker metadata-server tokens cannot work on Actions runners; use generation-matched writes/deletes, 412 conflicts and expiry.
 
 export const LEASE_TTL_MS = 35 * 60 * 1_000
 export const RENEW_INTERVAL_MS = 5 * 60 * 1_000

.github/actions/cloud-sql-rollout-lease/storage-lease.test.mjs

@@ -12,10 +12,7 @@ const BUCKET = 'onorca-cloud-terraform-state'
 const OBJECT = 'terraform/state/cloud-sql-rollout/production.lock'
 const NOW = 1_756_000_000_000
 
-/**
- * Enough of the Cloud Storage JSON API to exercise real compare-and-swap semantics: generations
- * increment, ifGenerationMatch is enforced, and a mismatch is a 412. `faults` injects failures.
- */
+/** Model real GCS generation increments, ifGenerationMatch and 412 conflicts; faults inject failures. */
 function fakeStorage({ object = null, faults = [] } = {}) {
   const state = { object, requests: [] }
   const fetcher = async (rawUrl, init = {}) => {

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

@@ -4,12 +4,7 @@ description: Frozen pnpm install for the mobile/ project, whose node_modules the
 runs:
   using: composite
   steps:
-    # Why a separate install: mobile is its own pnpm project, so the root install leaves
-    # mobile/node_modules empty and every mobile import resolves to nothing.
-    # Why no --ignore-scripts, unlike the root install: mobile's postinstall generates the
-    # gitignored terminal/mermaid webview engine modules that tracked source imports.
-    # The drift guard mirrors the root install so a stale mobile lockfile fails by name --
-    # mobile's lockfile carries patchedDependencies that a silent rewrite would drop.
+    # Install the separate mobile project: root install leaves its imports unresolved. Keep lifecycle scripts for generated terminal/mermaid engines; reject lockfile drift that could drop patchedDependencies.
     - name: Install mobile dependencies
       shell: bash
       working-directory: mobile

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

@@ -222,10 +222,7 @@ runs:
           rm -rf node_modules
         fi
 
-    # Why --frozen-lockfile: re-resolving pulls ~62 MB of registry packuments per job
-    # (measured) to recompute what the lockfile already pins, and the `git diff` guard
-    # below fails the run whenever that recomputation would have changed anything. The
-    # guard stays so a stale lockfile still fails by name rather than by resolver error.
+    # Frozen install avoids ~62MB/job of redundant resolution; retain diff guard to name stale lockfiles explicitly.
     - name: Install dependencies
       shell: bash
       run: |