Sync upstream/main to v1.4.241's cut point

.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,29 @@ 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
+converts back the same way. CI always uses the normal layout. On Windows, pnpm links with
+junctions when you lack the symlink privilege, so no administrator rights or Developer Mode are
+needed. Things to know:
+
+- Keep `~/node_modules` (and any other `node_modules` above the store) out of your home
+  directory. Node resolves upward from the store slot, so a stray one there supplies
+  dependencies the package never declared and hides missing-dependency bugs; `pnpm install` warns
+  when it finds one.
+- Native addons are never rebuilt in place in a shared slot: each CPU gets its own build
+  beside it (see [`native-build-entry.cjs`](../config/scripts/native-build-entry.cjs)), so
+  cross-arch packaging is safe for other worktrees.
+- `ORCA_PNPM_GLOBAL_VIRTUAL_STORE=0` opts out. Keep it set
+  in your shell: `pnpm run` re-checks the install and relinks a worktree whose layout no longer
+  matches.
+
 Ordinary installs include native optional dependencies for the current OS and CPU only.
 Before a cross-architecture build (including `pnpm build:mac`, which produces both x64 and
 arm64 artifacts by default), run `pnpm install:release` to add the other CPU's variants.
@@ -72,8 +176,14 @@ pnpm build
 ```
 
 For repeated local typechecks, use `pnpm tc` (or `pnpm tc:node`, `pnpm tc:web`,
-and `pnpm tc:cli`). These keep TypeScript's incremental cache. CI uses
-`pnpm typecheck:ci` with Bun for full checks. Shared tests are checked by the
+and `pnpm tc:cli`). On Apple Silicon macOS and x64/arm64 Linux, these use the pinned
+`tsrs` compiler with incremental caches. Keep `.cache/typecheck/` between checks;
+delete it to force a fresh check. Caches are separate for each project, compiler
+version, and worktree. At most two projects run together, subject to the memory budget.
+Windows, Intel macOS, and other unsupported platforms use pinned Bun automatically.
+Pass `--compiler=bun` to explicitly use Bun, or `--compiler=native` to use TypeScript.
+CI uses `pnpm typecheck:ci`, which explicitly selects Bun and its CI concurrency.
+Shared tests are checked by the
 Node project; shared production code is checked in all three environments.
 Run `pnpm tc:node` after editing shared tests, or `pnpm tc` to check everything.
 

.github/actions/cloud-sql-rollout-lease/README.md

@@ -137,7 +137,7 @@ runners; only the compare-and-swap algorithm is shared with the fence broker.
 ## Duplication
 
 This directory is copied verbatim into `stablyai/orca`. It has no `package.json`, no
-`node_modules`, and imports nothing outside itself — `action-contract.test.mjs` enforces all three.
+`node_modules`, and imports nothing outside itself. Keep it self-contained when updating the action.
 Cross-repo consumption via `uses: stablyai/orca/.github/actions/...@<sha>` was rejected: it would
 put public-repo code inside private app deploys that hold a production credential, and neither
 repository protects `main` today.

.github/actions/cloud-sql-rollout-lease/action-contract.test.mjs

@@ -1,11 +1,9 @@
 import assert from 'node:assert/strict'
-import { readFileSync, readdirSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { test } from 'node:test'
 
 const here = new URL('./', import.meta.url)
 const action = readFileSync(new URL('action.yml', here), 'utf8')
-const modules = readdirSync(here).filter((name) => name.endsWith('.mjs'))
-const shipped = modules.filter((name) => !name.endsWith('.test.mjs'))
 
 test('is a node24 JavaScript action with an always-run post step', () => {
   // A composite action has no `post:`, so the lease could never be released on cancel or failure.
@@ -23,30 +21,3 @@ test('declares the inputs the wave-chain callers depend on', () => {
   assert.match(action, /default: \$\{\{ github\.repository \}\}\/\$\{\{ github\.run_id \}\}/)
   assert.match(action, /default: 'true'/)
 })
-
-test('stays self-contained so it can be duplicated into the public repo', () => {
-  assert.deepEqual(
-    readdirSync(here).filter((name) => name === 'package.json' || name === 'node_modules'),
-    [],
-    'the action must run with zero installed dependencies'
-  )
-  for (const name of modules) {
-    const source = readFileSync(new URL(name, here), 'utf8')
-    for (const match of source.matchAll(/^import\b[\s\S]*?from '([^']+)'/gm)) {
-      const specifier = match[1]
-      const local = specifier.startsWith('.')
-      assert.ok(
-        specifier.startsWith('node:') || (local && !specifier.includes('..')),
-        `${name} imports ${specifier}; only node: builtins and same-directory modules are allowed`
-      )
-    }
-  }
-})
-
-test('never reaches for the GCE metadata server', () => {
-  // Runners have no metadata.google.internal; the fence broker's token path must not be copied.
-  for (const name of shipped) {
-    const source = readFileSync(new URL(name, here), 'utf8')
-    assert.doesNotMatch(source, /metadata\.google\.internal/, name)
-  }
-})

.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() {