Sync upstream 1.4.214

.gitattributes

@@ -97,3 +97,7 @@
 
 # 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,7 +16,7 @@ Thanks for contributing to Orca.
 
 ## Local Setup
 
-Install Node 24, pnpm, and the Bun version in [`config/bun-version`](../config/bun-version).
+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.
@@ -29,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
 

.github/pull_request_template.md

@@ -11,6 +11,7 @@
 <!-- What problem does this solve, and why is this approach better than the alternatives you considered? -->
 
 ## Linked Issue
+
 _If you do not have one and are an outside contributors, your PR **wiil** be ignored. Refs is not sufficient. Link an actual issue_
 <!-- Link the issue this PR addresses, there should ALWAYS be one (for outside contributors) -->
 <!-- SPECIAL CASE: If you are a maintainer (member of stablyai org) AVOID opening needless issues. Only attach pre-existing ones -->
@@ -39,7 +40,7 @@ Fixes #
 
 ## Agent skill upstream boundary
 
-- [ ] Not applicable, or this change follows `docs/reference/agent-skill-sharing-upstream-boundary.md` and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.
+- [ ] Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.
 
 ## Notes
 

.github/workflows/adhoc-mac-build.yml

@@ -6,7 +6,9 @@ name: Adhoc macOS + Windows Dev Build
 #
 # Deliberately narrow scope:
 #   - macOS and Windows desktop installers. Linux keeps using RC/stable.
-#   - No tests, no lint, no e2e. PR CI and release-cut remain the gates.
+#   - No tests, no lint, no e2e. PR CI and release-cut remain the gates. The one
+#     exception is the orcad template: like release-cut, it is merged from the
+#     node-server lanes that build and qualify each SSH target's slot.
 #   - macOS is signed and notarized so TCC grants survive updates.
 #   - Windows is unsigned; the published release notes explain the one-time
 #     SmartScreen/manual-install requirement.
@@ -81,21 +83,116 @@ env:
   ADHOC_RETAIN_DAYS: 30
 
 jobs:
+  # Why: every job below checks out its own copy, and a branch name read per job builds whatever
+  # the branch points at when that job starts. A push mid-run then mixes commits, e.g. slot lanes
+  # from one commit merged by a template step from the next. Resolving once pins the whole run.
+  # The mac job still vets this commit's reachability before anything is signed.
+  resolve-ref:
+    if: github.repository == 'stablyai/orca'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      sha: ${{ steps.resolve.outputs.sha }}
+    steps:
+      - name: Resolve the requested ref to one commit
+        id: resolve
+        shell: bash
+        env:
+          REQUESTED_REF: ${{ inputs.ref || github.ref_name }}
+          REPO_URL: https://github.com/${{ github.repository }}
+        run: |
+          set -euo pipefail
+          case "$REQUESTED_REF" in
+            refs/pull/*|pull/*)
+              echo "::error::Refusing to build PR ref '$REQUESTED_REF'; push the code to a branch of stablyai/orca instead."
+              exit 1
+              ;;
+          esac
+          if [[ "$REQUESTED_REF" =~ ^[0-9a-f]{40}$ ]]; then
+            sha="$REQUESTED_REF"
+          else
+            # Branch first, as the mac job's vet does; a peeled annotated tag names its commit.
+            refs="$(git ls-remote "$REPO_URL" "refs/heads/$REQUESTED_REF" "refs/tags/$REQUESTED_REF" "refs/tags/$REQUESTED_REF^{}")"
+            sha=""
+            for name in "refs/heads/$REQUESTED_REF" "refs/tags/$REQUESTED_REF^{}" "refs/tags/$REQUESTED_REF"; do
+              sha="$(awk -v ref="$name" '$2 == ref { print $1; exit }' <<<"$refs")"
+              [[ -n "$sha" ]] && break
+            done
+          fi
+          if [[ -z "$sha" ]]; then
+            echo "::error::'$REQUESTED_REF' is not a branch, tag, or full commit SHA of stablyai/orca."
+            exit 1
+          fi
+          echo "Resolved $REQUESTED_REF -> $sha"
+          echo "sha=$sha" >>"$GITHUB_OUTPUT"
+
   # Why its own job: this package ships relays for Windows SSH hosts, and only a
   # Windows runner compiles the addon that launches one outside sshd's job.
   # Why the unvetted ref is safe here: this job holds no secrets, and the mac job
   # vets the same ref before it downloads anything, so fork code never gets signed.
   relay-windows-process-tree:
-    if: github.repository == 'stablyai/orca'
+    needs: resolve-ref
     permissions:
       contents: read
     uses: ./.github/workflows/relay-windows-process-tree.yml
     with:
-      ref: ${{ inputs.ref || github.ref_name }}
+      ref: ${{ needs.resolve-ref.outputs.sha }}
+
+  # Why: a branch cut before the orcad template landed has none to build or ship.
+  orcad-template-support:
+    needs: resolve-ref
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      ships: ${{ steps.detect.outputs.ships }}
+    steps:
+      - name: Checkout the template packager only
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.resolve-ref.outputs.sha }}
+          sparse-checkout: |
+            /config/scripts/packaged-orcad-template.cjs
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+      - name: Detect whether the ref ships the orcad template
+        id: detect
+        shell: bash
+        run: |
+          if [[ -f config/scripts/packaged-orcad-template.cjs ]]; then
+            echo "ships=true" >>"$GITHUB_OUTPUT"
+          else
+            echo "ships=false" >>"$GITHUB_OUTPUT"
+            echo "::notice::This ref predates the orcad template; the build ships without it."
+          fi
+
+  # Design D2, as release-cut does: every desktop build ships the orcad template (server JS plus
+  # every target's addons), merged from the node-server lanes that qualify each slot at this ref.
+  # Without it an adhoc build cannot deploy managed orcad to an SSH host. No secrets, like the
+  # relay job, and the mac job vets the ref before anything is signed.
+  orcad-template:
+    needs: [resolve-ref, orcad-template-support]
+    if: needs.orcad-template-support.outputs.ships == 'true'
+    permissions:
+      contents: read
+    uses: ./.github/workflows/node-server-tests.yml
+    with:
+      ref: ${{ needs.resolve-ref.outputs.sha }}
+      build_template: true
 
   build-adhoc-mac:
-    needs: relay-windows-process-tree
-    if: github.repository == 'stablyai/orca'
+    needs: [resolve-ref, relay-windows-process-tree, orcad-template-support, orcad-template]
+    # Why not the implicit success(): a ref without the orcad template skips that job on purpose.
+    if: >-
+      !cancelled() && github.repository == 'stablyai/orca' &&
+      needs.relay-windows-process-tree.result == 'success' &&
+      needs.orcad-template-support.result == 'success' &&
+      (needs.orcad-template.result == 'success' ||
+        (needs.orcad-template.result == 'skipped' &&
+          needs.orcad-template-support.outputs.ships == 'false'))
     # Why an environment: it gives the signing/notary/App secrets somewhere to
     # live that a stale copy of this workflow on an old branch cannot reach.
     # Referencing it is a no-op until repo settings give it teeth; the intended
@@ -109,6 +206,7 @@ jobs:
       version: ${{ steps.adhoc.outputs.version }}
       head_sha: ${{ steps.adhoc.outputs.head_sha }}
       published: ${{ steps.publish_live.outcome == 'success' && 'true' || 'false' }}
+      ships_orcad_template: ${{ needs.orcad-template-support.outputs.ships }}
     runs-on: blacksmith-6vcpu-macos-15
     # Why 150: it must exceed the worst case the retry budgets below can produce
     # (install 3x10 + publish 2x45 = 120, plus ~25 for checkout/build/verify), or
@@ -128,7 +226,8 @@ jobs:
         id: vetted
         shell: bash
         env:
-          REQUESTED_REF: ${{ inputs.ref || github.ref_name }}
+          # The commit resolve-ref pinned for every job; vetting it keeps the reachability test.
+          REQUESTED_REF: ${{ needs.resolve-ref.outputs.sha }}
           REPO_URL: https://github.com/${{ github.repository }}
         run: |
           set -euo pipefail
@@ -292,6 +391,14 @@ jobs:
           # sshd's job for a standard user on a Windows SSH host.
           ORCA_REQUIRE_RELAY_NATIVE_ADDONS: x64,arm64
 
+      # After the app build so nothing that cleans out/ can drop it; electron-builder ships it.
+      - name: Download the orcad deployment template
+        if: needs.orcad-template-support.outputs.ships == 'true'
+        uses: actions/download-artifact@v8
+        with:
+          name: orcad-template
+          path: out/orcad-template
+
       # Why the token is minted here and not at the top: installation tokens live
       # one hour, everything before this point writes nothing, and the notary round
       # trip inside the publish step can be tens of minutes. Minting after the build
@@ -366,6 +473,8 @@ jobs:
           GH_TOKEN: ${{ steps.app_token.outputs.token }}
           ORCA_ADHOC_BUILD_VERSION: ${{ steps.adhoc.outputs.version }}
           ORCA_BUILD_COMMIT: ${{ steps.adhoc.outputs.commit }}
+          # beforePack and afterPack fail the package when the template is absent.
+          ORCA_REQUIRE_ORCAD_TEMPLATE: ${{ needs.orcad-template-support.outputs.ships == 'true' && '1' || '' }}
           CSC_LINK: ${{ secrets.MAC_CERTS }}
           CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTS_PASSWORD }}
           # Why all three: electron-builder's notarize step authenticates to the
@@ -514,3 +623,4 @@ jobs:
       tag: ${{ needs.build-adhoc-mac.outputs.tag }}
       ref: ${{ needs.build-adhoc-mac.outputs.head_sha }}
       version: ${{ needs.build-adhoc-mac.outputs.version }}
+      orcad_template: ${{ needs.build-adhoc-mac.outputs.ships_orcad_template == 'true' }}

.github/workflows/ci-cache-warmup.yml

@@ -14,7 +14,7 @@ on:
       - '.github/actions/prepare-native-runtime/**'
       - '.github/actions/prepare-git-compatibility/**'
       - '.github/actions/prepare-headless-compiler/**'
-      - 'config/scripts/headless-detector-compiler-cache*'
+      - 'config/scripts/headless-detector-compiler-cache.mjs'
       - '.github/actions/prepare-linux-package-fixture/**'
       - 'config/docker/headless-serve-shutdown/**'
       - 'config/docker/cli-launch-contract/**'
@@ -44,12 +44,11 @@ on:
       - '.github/workflows/ci-cache-warmup.yml'
       - '.github/actions/prepare-git-compatibility/**'
       - '.github/actions/prepare-headless-compiler/**'
-      - 'config/scripts/headless-detector-compiler-cache*'
+      - 'config/scripts/headless-detector-compiler-cache.mjs'
       - '.github/actions/prepare-linux-package-fixture/**'
       - 'config/docker/headless-serve-shutdown/**'
       - 'config/docker/cli-launch-contract/**'
       - 'config/docker/daemon-shutdown-descendants/**'
-      - 'config/scripts/ci-cache-warmup-workflow.test.mjs'
 
 permissions:
   contents: read

.github/workflows/cloud-deploy-relay-production-same-cap-job.yml

@@ -30,7 +30,8 @@ jobs:
     if: ${{ github.ref == 'refs/heads/main' }}
     runs-on: blacksmith-2vcpu-ubuntu-2204
     # The pre-drain sample adds 3-8 min (20 at most); a timeout cancels the job and skips the failsafe.
-    timeout-minutes: 90
+    # A 1200000 drain step alone may take 50 min.
+    timeout-minutes: 120
     environment: production
     env:
       GCP_PROJECT_ID: onorca-cloud
@@ -53,8 +54,9 @@ jobs:
       # /v1/assign at hosts / window and is re-placed through the director's drain-return
       # lane. The wave validator admits only its closed set, and anything below the 300000
       # default only on US general cells: Asia drains are bound by their targets' accept
-      # rate. The transition wait below is the 15-min migration lease plus this window. A
-      # cell on an older image drains at once.
+      # rate. The transition wait below is the 15-min migration lease plus this window, plus
+      # its excess over 300000, since restart-safe waits a window of quiet after the drain. A
+      # cell on an older image drains at once, or refuses a window above 300000.
       DRAIN_PACE_WINDOW_MS: ${{ inputs.drain-pace-window-ms }}
     steps:
       - name: Require exact reusable-workflow configuration
@@ -499,8 +501,8 @@ jobs:
         if: ${{ inputs.mode == 'verify' }}
         run: echo 'Exact same-cap rollback point verified.'
 
-      # The sample can age the first one-hour token by up to 20 min; the drain's 20-min
-      # restart-safe wait gets a fresh one.
+      # The sample can age the first one-hour token by up to 20 min; the drain's restart-safe
+      # wait (20 min at the default pace, 50 at the slowest) gets a fresh one.
       - id: drain-auth
         if: ${{ inputs.mode != 'verify' && env.ROLLBACK_RESUME != 'true' }}
         uses: google-github-actions/auth@v2
@@ -517,6 +519,11 @@ jobs:
         env:
           ORCA_RELAY_ADMIN_ID_TOKEN: ${{ steps.drain-auth.outputs.id_token }}
         run: |
+          # Before any mutation: a cell whose image caps the pace below this one stops untouched.
+          node dev/scripts/prepare-relay-production-capacity-canary.mjs \
+            --director-origin "${DIRECTOR_ORIGIN}" --cell-origin "${CELL_ORIGIN}" \
+            --cell-id "${TARGET_CELL_ID}" --approved-cells same-cap --mode pace-check \
+            --pace-window-ms "${DRAIN_PACE_WINDOW_MS}"
           # Opens the window the report-only shadow health gate below judges this cell over.
           echo "drain-started-at=$(date -u +%FT%TZ)" >> "${GITHUB_OUTPUT}"
           echo "MUTATION_STARTED=true" >> "${GITHUB_ENV}"
@@ -555,7 +562,7 @@ jobs:
             --heartbeat either --admission migration-only --draining required \
             --activity restart-safe --expected-image-digests "${PREDECESSOR_IMAGE_DIGEST}" \
             --pace-window-ms "${DRAIN_PACE_WINDOW_MS}" \
-            --timeout-ms "$((900000 + DRAIN_PACE_WINDOW_MS))"
+            --timeout-ms "$((900000 + DRAIN_PACE_WINDOW_MS + (DRAIN_PACE_WINDOW_MS > 300000 ? DRAIN_PACE_WINDOW_MS - 300000 : 0)))"
           echo "drain-settled-at=$(date -u +%FT%TZ)" >> "${GITHUB_OUTPUT}"
 
       - id: capacity-auth
@@ -709,19 +716,31 @@ jobs:
         env:
           ORCA_RELAY_ADMIN_ID_TOKEN: ${{ steps.post-auth.outputs.id_token }}
         run: |
-          # A single transient 5xx (LB warm-up behind a fresh instance) must not
-          # fail a canary; 4xx (auth, generation mismatch) still fails fast.
+          # Rides out one DB stall: 5-7 s, then readiness grace and two 10 s LB
+          # health checks (c18, 10-07 18:49Z: 503 "no healthy upstream", healthy
+          # 16 s later). A cell still down after 60 s fails; other 4xx fail fast.
+          # Retried in this loop: the runner's 7.81 client (Ubuntu 22.04) never
+          # retries under --fail-with-body, so its --retry flags were inert.
           admin_post() {
-            local out="${RUNNER_TEMP}/$1.json"
-            if ! curl --fail-with-body --max-time 30 \
-              --retry 3 --retry-delay 2 --retry-connrefused --output "${out}" \
-              --request POST "$2" \
-              --header "Authorization: Bearer ${ORCA_RELAY_ADMIN_ID_TOKEN}" \
-              --header 'Content-Type: application/json' --data "$3"; then
-              cat "${out}" >&2
-              return 1
-            fi
-            cat "${out}"
+            local out="${RUNNER_TEMP}/$1.json" window=60 delay=5 status
+            local deadline=$((SECONDS + window))
+            while true; do
+              # A refused or timed-out attempt writes no body; never report the last one's.
+              rm -f "${out}"
+              status="$(curl --silent --show-error --max-time 30 --output "${out}" \
+                --write-out '%{http_code}' --request POST "$2" \
+                --header "Authorization: Bearer ${ORCA_RELAY_ADMIN_ID_TOKEN}" \
+                --header 'Content-Type: application/json' --data "$3")" || status=000
+              case "${status}" in
+                2??) cat "${out}"; return 0 ;;
+                000|408|429|5??) ((SECONDS + delay < deadline)) || break ;;
+                *) break ;;
+              esac
+              sleep "${delay}"
+            done
+            echo "admin_post $1: HTTP ${status}" >&2
+            cat "${out}" >&2 2>/dev/null || true
+            return 1
           }
           node dev/scripts/verify-relay-capacity-transition.mjs \
             --director-origin "${DIRECTOR_ORIGIN}" --cell-origin "${CELL_ORIGIN}" \
@@ -824,8 +843,8 @@ jobs:
         # read cost its full retry budget and can push the job past timeout-minutes, and a
         # cancelled job takes the whole wave with it. A healthy gate is already minutes of
         # serial reads, so both bounds sit above that: the script settles at seven minutes and
-        # reaching this eight is the pathological case. Eight on top of a ~14-minute cell still
-        # leaves the job's 90 minutes intact.
+        # reaching this eight is the pathological case. Eight on top of a cell of ~14 minutes
+        # (~45 at the slowest pace) still leaves the job's 120 minutes intact.
         timeout-minutes: 8
         env:
           DRAIN_STARTED_AT: ${{ steps.drain.outputs.drain-started-at }}

.github/workflows/cloud-deploy-relay-production-same-cap.yml

@@ -54,11 +54,11 @@ on:
         required: true
         type: string
       drain-pace-window-ms:
-        description: Window the cell spreads its drain over; below 300000 only for US general cells, named in the confirmation
+        description: Window the cell spreads its drain over; below 300000 only for US general cells; any other value named in the confirmation
         required: true
         default: '300000'
         type: choice
-        options: ['300000', '60000', '30000']
+        options: ['300000', '60000', '30000', '900000', '1200000']
       canary-run-id:
         description: Successful same-code canary in this rehome control generation; reusable across batches
         required: false