sync: absorb upstream v1.4.224

.gitattributes

@@ -7,6 +7,12 @@
 /skill-stubs/_shared/*.md text eol=lf
 /skills/*/SKILL.md text eol=lf
 /src/cli/bundled-skill-guides.ts text eol=lf
+# SVG bytes feed embedded data URLs and asset hashes on every build host.
+*.svg text eol=lf
+# Compiler input line breaks must not depend on the checkout OS.
+*.ts text eol=lf
+*.tsx text eol=lf
+*.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
@@ -47,6 +53,9 @@
 # Generated method->params catalog: compared byte-for-byte by
 # verify:rpc-params-catalog, so a CRLF checkout would fail the gate.
 /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.
+/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).
@@ -85,3 +94,10 @@
 /mobile/web-entry/**/*.otf -text
 /mobile/web-entry/**/*.woff -text
 /mobile/web-entry/**/*.woff2 -text
+
+# Generated ACP schemas are checked byte-for-byte against formatted output.
+/src/main/acp/generated/*.generated.ts linguist-generated=true text eol=lf
+# Generated skill bundle artifacts are verified byte-for-byte against fresh output.
+/resources/skills/*.json linguist-generated=true text eol=lf
+# Vitest writes snapshots with LF, so checkout bytes must match on every host.
+**/__snapshots__/*.snap text eol=lf

.github/CONTRIBUTING.md

@@ -16,6 +16,11 @@ Thanks for contributing to Orca.
 
 ## Local Setup
 
+Install Node 24, pnpm, and the Bun version in [`config/.bun-version`](../config/.bun-version).
+`pnpm test` runs Vitest on Bun, with Node workers for runtime contracts such as SQLite,
+native PTYs, socket liveness, and V8 memory behavior. `pnpm test:node` runs the same suites
+entirely on Node. Builds and dependency installation still use Node and pnpm.
+
 ```bash
 pnpm install
 pnpm dev
@@ -24,7 +29,6 @@ pnpm dev
 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.
-See [the install policy](../docs/reference/pnpm-install-policy.md).
 
 ## Branch Naming
 
@@ -63,9 +67,10 @@ CI enforces this for `src/preload/` and `src/shared/`.
 
 Each pull request should follow [`.github/pull_request_template.md`](./pull_request_template.md). In particular:
 
+- if you are an outside contributor, link the issue your PR addresses
 - open with an ELI5 of the change (plain language paragraph; the PR title is the one-liner)
 - explain what changed and why, and stay focused on a single topic when possible
-- for any UI or interaction change, attach **before and after** screenshots (or short videos); if there is no visual change, say `No visual change` and why
+- for any UI or interaction change, attach **before and after** screenshots (or short videos); if there is no visual or interaction change, write `N/A` and briefly explain why
 - include high-quality tests when behavior changes or bug fixes warrant them
 - include a brief code review summary from your AI coding agent that explicitly checks cross-platform compatibility, SSH/remote/local compatibility, supported agent and integration compatibility, performance risk, UI quality when applicable, and basic security risk
 - mention any platform-specific, remote/SSH-specific, agent-specific, integration-specific, or git-provider-specific behavior and testing notes

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

@@ -2,8 +2,16 @@ name: Install Node dependencies
 description: Installs the Node toolchain and repository dependencies for CI jobs, with optional Electron archive caching.
 
 inputs:
+  cache-pnpm-store:
+    description: Restore or save the pnpm download store; verification and native caches are independent.
+    required: false
+    default: 'true'
+  cache-pnpm-store-lookup-only:
+    description: Auto uses measured hosted Node 24 root installs; true forces lookup, false retains archive restoration.
+    required: false
+    default: auto
   cache-pnpm-verification:
-    description: Restore pnpm's policy-checked lockfile verification record on Linux.
+    description: Restore pnpm's policy-checked lockfile verification record.
     required: false
     default: 'true'
   native-runtime:
@@ -28,9 +36,12 @@ inputs:
     default: 'false'
 
 outputs:
+  pnpm-store-cache-hit:
+    description: Whether the requested download store matched an existing cache.
+    value: ${{ steps.pnpm-store-lookup.outputs.cache-hit || steps.pnpm-store-restore.outputs.cache-hit || steps.requested-node.outputs.cache-hit || steps.default-node.outputs.cache-hit }}
   verification-cache-hit:
     description: Whether pnpm's verification record was restored.
-    value: ${{ steps.verification-cache-restore.outputs.cache-hit }}
+    value: ${{ steps.verification-cache.outputs.cache-hit }}
   verification-cache-path:
     description: The small pnpm-owned verification record, without registry metadata.
     value: ${{ steps.verification-cache.outputs.path }}
@@ -42,14 +53,44 @@ outputs:
     value: ${{ steps.requested-node.outputs.node-version || steps.default-node.outputs.node-version }}
   native-cache-scope:
     description: Operating-system image scope used by the native module cache.
-    value: ${{ steps.native-cache-scope.outputs.scope }}
+    value: ${{ steps.native-runtime.outputs.cache-scope }}
+  native-cache-key:
+    description: Exact native cache key requested after installation.
+    value: ${{ steps.native-runtime.outputs.cache-key }}
+  native-cache-path:
+    description: Native build directories covered by the requested cache.
+    value: ${{ steps.native-runtime.outputs.cache-path }}
   native-cache-hit:
     description: Whether the compiled native module cache was restored.
-    value: ${{ steps.native-cache-restore.outputs.cache-hit || steps.native-cache-restore-only.outputs.cache-hit }}
+    value: ${{ steps.native-runtime.outputs.cache-hit }}
 
 runs:
   using: composite
   steps:
+    - name: Resolve pnpm store mode
+      id: pnpm-store-mode
+      if: >-
+        github.event_name != 'pull_request' && inputs.cache-pnpm-store != 'false' &&
+        (inputs.cache-pnpm-store-lookup-only == 'true' ||
+        (inputs.cache-pnpm-store-lookup-only == 'auto' &&
+        inputs.cache-dependency-path == 'pnpm-lock.yaml' &&
+        runner.environment == 'github-hosted' && job.container.id == '' &&
+        (runner.os == 'Linux' || runner.os == 'macOS' || runner.os == 'Windows') &&
+        (runner.arch == 'X64' || runner.arch == 'ARM64') &&
+        (inputs.node-version == '' || inputs.node-version == '24')))
+      shell: bash
+      env:
+        LOOKUP_REQUEST: ${{ inputs.cache-pnpm-store-lookup-only }}
+      run: |
+        lookup_only=true
+        case "$LOOKUP_REQUEST" in
+          [aA][uU][tT][oO])
+            # Hosted runners have Node for this manifest-only check before toolchain setup.
+            lookup_only="$(node -p 'const p = require("./package.json"); p.engines?.node === "24" && typeof p.packageManager === "string" && p.packageManager.split("+")[0] === "pnpm@12.8.1"')"
+            ;;
+        esac
+        printf 'lookup-only=%s\n' "$lookup_only" >> "$GITHUB_OUTPUT"
+
     # setup-node needs pnpm on PATH to locate and restore its store.
     - name: Setup pnpm
       uses: pnpm/setup@v2
@@ -63,7 +104,7 @@ runs:
       uses: actions/setup-node@v6
       with:
         node-version-file: package.json
-        cache: ${{ github.event_name != 'pull_request' && 'pnpm' || '' }}
+        cache: ${{ github.event_name != 'pull_request' && inputs.cache-pnpm-store != 'false' && steps.pnpm-store-mode.outputs.lookup-only != 'true' && 'pnpm' || '' }}
         cache-dependency-path: ${{ inputs.cache-dependency-path }}
         package-manager-cache: false
 
@@ -73,50 +114,66 @@ runs:
       uses: actions/setup-node@v6
       with:
         node-version: ${{ inputs.node-version }}
-        cache: ${{ github.event_name != 'pull_request' && 'pnpm' || '' }}
+        cache: ${{ github.event_name != 'pull_request' && inputs.cache-pnpm-store != 'false' && steps.pnpm-store-mode.outputs.lookup-only != 'true' && 'pnpm' || '' }}
         cache-dependency-path: ${{ inputs.cache-dependency-path }}
         package-manager-cache: false
 
     # PR-local stores compete with reusable build caches for the repository quota.
     - name: Resolve pnpm download store
       id: pnpm-store
-      if: github.event_name == 'pull_request'
+      if: >-
+        github.event_name == 'pull_request' && inputs.cache-pnpm-store != 'false' &&
+        !((runner.os == 'Linux' || runner.os == 'macOS') && (runner.arch == 'X64' || runner.arch == 'ARM64') && inputs.cache-dependency-path == 'pnpm-lock.yaml') &&
+        (runner.os != 'Windows' ||
+        !(runner.arch == 'X64' && contains(inputs.cache-dependency-path, 'mobile/pnpm-lock.yaml')) &&
+        !((runner.arch == 'X64' || runner.arch == 'ARM64') && inputs.cache-dependency-path == 'pnpm-lock.yaml')) ||
+        (github.event_name != 'pull_request' && inputs.cache-pnpm-store != 'false' &&
+        steps.pnpm-store-mode.outputs.lookup-only == 'true')
       shell: bash
       env:
         LOCKFILE_HASH: ${{ hashFiles(inputs.cache-dependency-path) }}
+        STORE_LOOKUP_ONLY: ${{ steps.pnpm-store-mode.outputs.lookup-only == 'true' }}
       run: |
         test -n "$LOCKFILE_HASH"
         cache_path="$(pnpm store path --silent)"
         test -n "$cache_path"
         printf 'path=%s\n' "$cache_path" >> "$GITHUB_OUTPUT"
         printf 'arch=%s\n' "$(node -p 'require("node:os").arch()')" >> "$GITHUB_OUTPUT"
+        if [ "$STORE_LOOKUP_ONLY" = 'true' ]; then
+          printf 'ORCA_PNPM_STORE_CACHE_PATH=%s\n' "$cache_path" >> "$GITHUB_ENV"
+        fi
 
     # Match setup-node's key and path so existing default-branch stores remain reusable.
+    # Direct downloads beat store restoration for the measured Linux, macOS and Windows installs.
     - name: Restore pnpm download store without saving
-      if: github.event_name == 'pull_request'
+      id: pnpm-store-restore
+      if: >-
+        github.event_name == 'pull_request' && inputs.cache-pnpm-store != 'false' &&
+        !((runner.os == 'Linux' || runner.os == 'macOS') && (runner.arch == 'X64' || runner.arch == 'ARM64') && inputs.cache-dependency-path == 'pnpm-lock.yaml') &&
+        (runner.os != 'Windows' ||
+        !(runner.arch == 'X64' && contains(inputs.cache-dependency-path, 'mobile/pnpm-lock.yaml')) &&
+        !((runner.arch == 'X64' || runner.arch == 'ARM64') && inputs.cache-dependency-path == 'pnpm-lock.yaml'))
       uses: actions/cache/restore@v5
       with:
         path: ${{ steps.pnpm-store.outputs.path }}
         key: node-cache-${{ runner.os }}-${{ steps.pnpm-store.outputs.arch }}-pnpm-${{ hashFiles(inputs.cache-dependency-path) }}
 
-    - name: Resolve pnpm verification cache
-      id: verification-cache
-      if: runner.os == 'Linux' && inputs.cache-pnpm-verification == 'true'
-      shell: bash
-      env:
-        POLICY_HASH: ${{ hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', '.npmrc') }}
-      run: |
-        printf 'path=%s/lockfile-verified.jsonl\n' "$(pnpm cache path)" >> "$GITHUB_OUTPUT"
-        printf 'key=pnpm-verification-v1-%s-%s-%s-%s\n' "$RUNNER_OS" "$RUNNER_ARCH" "$(pnpm --version)" "$POLICY_HASH" >> "$GITHUB_OUTPUT"
+    # Producers can refresh access and publish misses without downloading existing archives.
+    - name: Keep pnpm download store without restoring
+      id: pnpm-store-lookup
+      if: steps.pnpm-store-mode.outputs.lookup-only == 'true'
+      uses: actions/cache@v5
+      with:
+        # Twice-nested composite cleanup loses internal step outputs.
+        path: ${{ env.ORCA_PNPM_STORE_CACHE_PATH }}
+        key: node-cache-${{ runner.os }}-${{ steps.pnpm-store.outputs.arch }}-pnpm-${{ hashFiles(inputs.cache-dependency-path) }}
+        lookup-only: true
 
     - name: Restore pnpm verification record
-      id: verification-cache-restore
-      if: steps.verification-cache.outputs.key != ''
-      continue-on-error: true
-      uses: actions/cache/restore@v5
+      id: verification-cache
+      uses: ./.github/actions/restore-pnpm-verification
       with:
-        path: ${{ steps.verification-cache.outputs.path }}
-        key: ${{ steps.verification-cache.outputs.key }}
+        enabled: ${{ inputs.cache-pnpm-verification }}
 
     - name: Validate native runtime
       shell: bash
@@ -152,9 +209,14 @@ runs:
           git -C "$GITHUB_WORKSPACE" diff --exit-code -- package.json pnpm-lock.yaml pnpm-workspace.yaml
         fi
 
+    # Why --if-present: release cuts run main's workflows against older release tags that predate this script.
+    - name: Build internal packages
+      shell: bash
+      run: pnpm run --if-present build:packages
+
     # pnpm checks the cached record's policy and validity; never bypass verification.
     - name: Save pnpm verification record on main
-      if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && steps.verification-cache.outputs.key != '' && steps.verification-cache-restore.outputs.cache-hit != 'true'
+      if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && steps.verification-cache.outputs.key != '' && steps.verification-cache.outputs.cache-hit != 'true'
       continue-on-error: true
       uses: actions/cache/save@v5
       with:
@@ -194,68 +256,11 @@ runs:
         path: ${{ steps.electron-package-cache.outputs.cache-root }}
         key: electron-package-${{ runner.os }}-${{ runner.arch }}-${{ steps.electron-package-cache.outputs.version }}
 
-    # Why cached: `--ignore-scripts` leaves node-pty without build/Release, so
-    # ensure-native-runtime node-gyp-compiles it in every job that asks for a runtime.
-    # The artifacts are ABI-bound, so the key carries the target runtime, the resolved
-    # Node version, and the patch whose contents the build has to match.
-    # Windows extra globs are empty on Linux. No restore-keys: a partial-match key is
-    # an ABI-mismatched build, and ensure-native-runtime would recompile it anyway.
-    # Native addons built on a newer Linux image can require glibc symbols
-    # missing from an older runner/container. ImageOS distinguishes hosted
-    # Windows/macOS images; /etc/os-release also distinguishes Linux containers.
-    - name: Resolve native cache scope
-      id: native-cache-scope
-      if: inputs.native-runtime != 'none'
-      shell: bash
-      run: |
-        scope="${ImageOS:-$RUNNER_OS}"
-        if [ -r /etc/os-release ]; then
-          . /etc/os-release
-          scope="${ID:-linux}-${VERSION_ID:-unknown}"
-        fi
-        echo "scope=$scope" >> "$GITHUB_OUTPUT"
-
-    - name: Restore compiled native modules
-      id: native-cache-restore
-      if: inputs.native-runtime != 'none' && inputs.persist-native-cache != 'false'
-      uses: actions/cache@v5
-      with:
-        path: |
-          node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
-          native/windows-registry/build
-          node_modules/.pnpm/@vscode+windows-process-tre*/node_modules/@vscode/windows-process-tree/build
-        key: native-modules-${{ runner.os }}-${{ steps.native-cache-scope.outputs.scope }}-${{ runner.arch }}-${{ inputs.native-runtime }}-node${{ steps.requested-node.outputs.node-version || steps.default-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml', '.github/actions/install-node-dependencies/action.yml', 'config/scripts/ensure-native-runtime.mjs', 'config/scripts/rebuild-native-deps.mjs', 'config/patches/node-pty@1.1.0.patch', 'config/patches/@vscode__windows-process-tree@0.8.0.patch', 'native/windows-registry/src/addon.cc', 'native/windows-registry/binding.gyp', 'native/windows-registry/package.json') }}
-
-    - name: Restore compiled native modules without saving
-      id: native-cache-restore-only
-      if: inputs.native-runtime != 'none' && inputs.persist-native-cache == 'false'
-      uses: actions/cache/restore@v5
-      with:
-        path: |
-          node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
-          native/windows-registry/build
-          node_modules/.pnpm/@vscode+windows-process-tre*/node_modules/@vscode/windows-process-tree/build
-        key: native-modules-${{ runner.os }}-${{ steps.native-cache-scope.outputs.scope }}-${{ runner.arch }}-${{ inputs.native-runtime }}-node${{ steps.requested-node.outputs.node-version || steps.default-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml', '.github/actions/install-node-dependencies/action.yml', 'config/scripts/ensure-native-runtime.mjs', 'config/scripts/rebuild-native-deps.mjs', 'config/patches/node-pty@1.1.0.patch', 'config/patches/@vscode__windows-process-tree@0.8.0.patch', 'native/windows-registry/src/addon.cc', 'native/windows-registry/binding.gyp', 'native/windows-registry/package.json') }}
-
-    # pnpm's bundled gyp_main.py is not executable on fresh Linux runners.
-    - name: Use external node-gyp
-      if: runner.os == 'Linux' && inputs.native-runtime != 'none'
-      shell: bash
-      env:
-        NATIVE_RUNTIME: ${{ inputs.native-runtime }}
-        NATIVE_CACHE_HIT: ${{ steps.native-cache-restore.outputs.cache-hit || steps.native-cache-restore-only.outputs.cache-hit }}
-      run: |
-        # A cache hit can contain unusable addons; probe before skipping the rebuild toolchain.
-        if [ "$NATIVE_RUNTIME" = node ] && [ "$NATIVE_CACHE_HIT" = true ] &&
-          node config/scripts/ensure-native-runtime.mjs --check-only; then
-          exit 0
-        fi
-        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: Prepare native runtime
+      id: native-runtime
       if: inputs.native-runtime != 'none'
-      shell: bash
-      env:
-        NATIVE_RUNTIME: ${{ inputs.native-runtime }}
-      run: node config/scripts/ensure-native-runtime.mjs --runtime="$NATIVE_RUNTIME"
+      uses: ./.github/actions/prepare-native-runtime
+      with:
+        native-runtime: ${{ inputs.native-runtime }}
+        node-version: ${{ steps.requested-node.outputs.node-version || steps.default-node.outputs.node-version }}
+        persist-native-cache: ${{ inputs.persist-native-cache }}

.github/actions/prepare-git-compatibility/action.yml

@@ -10,15 +10,17 @@ runs:
       uses: actions/cache@v5
       with:
         path: ~/.cache/orca-git-compat/git-2.25.5
-        key: git-compat-baseline-${{ runner.os }}-${{ runner.arch }}-2.25.5
+        key: git-compat-baseline-${{ runner.os }}-${{ runner.arch }}-2.25.5-submodule
 
     # Finish the CPU-heavy build before any timed compatibility lanes start.
     - name: Build the baseline Git binary
       shell: bash
       run: |
         archive="$RUNNER_TEMP/git-2.25.5.tar.gz"
         source="$HOME/.cache/orca-git-compat/git-2.25.5"
-        if [ -x "$source/git" ]; then
+        if [ -x "$source/git" ] && [ -x "$source/git-submodule" ] \
+          && [ -f "$source/git-sh-setup" ] && [ -f "$source/git-sh-i18n" ] \
+          && [ -f "$source/git-parse-remote" ] && [ -x "$source/git-sh-i18n--envsubst" ]; then
           exit 0
         fi
         curl -fsSL https://www.kernel.org/pub/software/scm/git/git-2.25.5.tar.gz -o "$archive"
@@ -27,6 +29,7 @@ runs:
         mkdir -p "$source"
         tar -xzf "$archive" -C "$source" --strip-components=1
         make -C "$source" -j"$(nproc)" \
-          NO_GETTEXT=YesPlease NO_TCLTK=YesPlease NO_PYTHON=YesPlease git
+          NO_GETTEXT=YesPlease NO_TCLTK=YesPlease NO_PYTHON=YesPlease \
+          git git-submodule git-sh-setup git-sh-i18n git-parse-remote git-sh-i18n--envsubst
         # Object files are no longer needed after linking the cached binary.
         find "$source" -name '*.o' -delete