lidge-jun · Oct 14, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
@@ -2,7 +2,7 @@ name: Catalog async contracts
 
 on:
   push:
-    branches: [dev, main, preview]
+    branches: [main, preview]
     paths:
       - src/**
       - scripts/diagnostics/windows-version-control/**
@@ -35,7 +35,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        # Pull requests run the ubuntu leg only; macos and windows run on push
+        # to main/preview and on manual dispatch.
+        os: ${{ fromJSON(github.event_name == 'pull_request' && '["ubuntu-latest"]' || '["ubuntu-latest","macos-latest","windows-latest"]') }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:

@@ -1,3 +1,11 @@
+# ============================================================================
+# CI POLICY (maintainer decision — do not change in a contributor PR)
+#  * Pull requests run ONLY the fast Ubuntu subset.
+#  * Full cross-platform (macOS/Windows) CI runs ONLY via manual
+#    workflow_dispatch and on push to main/preview (release lines).
+#  * NEVER add a dev push trigger or pull_request runs for macOS/Windows jobs.
+#  PRs that change this policy will be closed. See AGENTS.md "CI policy".
+# ============================================================================
 name: Cross-platform CI
 
 on:
@@ -21,14 +29,19 @@ on:
     # because this workflow is `pull_request` (not `pull_request_target`),
     # declares `contents: read`, and reads no secrets.
     #
-    # `push:` stays pinned to the release lines: it gates publication, and
-    # review is covered by the pull_request trigger above. dev is dropped:
-    # its integration evidence comes from the pull_request run into dev, and
-    # workflow_dispatch covers anything a maintainer wants proven by hand.
-    # main and preview MUST stay: release.yml requires a successful
-    # push-event Cross-platform CI run for the exact release SHA and states
-    # that a pull-request run does not qualify, so removing either branch
-    # breaks publication.
+    #
+    # Pull requests run only the fast Ubuntu subset. Every macOS and Windows
+    # job (and the macOS/Windows legs of the keyring, npm-global, setup-action
+    # and remote-helper matrices) is skipped on `pull_request` and runs after
+    # merge instead, via workflow_dispatch, the main/preview `push:` below and
+    # the nightly schedule.
+    #
+    # `push:` is pinned to the release lines. dev is deliberately absent:
+    # cross-platform evidence for dev is run by hand via workflow_dispatch.
+    # main and preview MUST stay: release.yml requires a successful push-event
+    # Cross-platform CI run for the exact release SHA and states that a
+    # pull-request run does not qualify, so removing either branch breaks
+    # publication.
   push:
     branches: [main, preview]
     paths:
@@ -454,6 +467,7 @@ jobs:
         shell: bash
         env:
           NATIVE_SELECTED: ${{ github.event_name == 'schedule' && 'true' || steps.filter.outputs.native }}
+          EVENT_NAME: ${{ github.event_name }}
         run: |
           set -euo pipefail
           case "$NATIVE_SELECTED" in
@@ -466,33 +480,48 @@ jobs:
               ;;
           esac
 
-          # Two unconditional legs plus the macos leg that rides the native
-          # selection. These strings are what the keyring-smoke and
-          # npm-global-smoke matrices consume through fromJSON.
-          if [ "$NATIVE_SELECTED" = "true" ]; then
+          # These strings are what the keyring-smoke and npm-global-smoke
+          # matrices consume through fromJSON. A pull request runs only the
+          # ubuntu leg; the windows and macos legs run after merge on push
+          # (and on dispatch and the schedule). Outside pull requests, ubuntu
+          # and windows always run and macos rides the native selection.
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            keyring_matrix='[{"name":"ubuntu","runner":"ubuntu-latest"}]'
+            npm_global_matrix='[{"os":"ubuntu-latest"}]'
+            min_legs_filter='length >= 1'
+          elif [ "$NATIVE_SELECTED" = "true" ]; then
             keyring_matrix='[{"name":"ubuntu","runner":"ubuntu-latest"},{"name":"windows","runner":"windows-latest"},{"name":"macos","runner":"macos-latest"}]'
             npm_global_matrix='[{"os":"ubuntu-latest"},{"os":"windows-latest"},{"os":"macos-latest"}]'
+            min_legs_filter='length >= 2'
           else
             keyring_matrix='[{"name":"ubuntu","runner":"ubuntu-latest"},{"name":"windows","runner":"windows-latest"}]'
             npm_global_matrix='[{"os":"ubuntu-latest"},{"os":"windows-latest"}]'
+            min_legs_filter='length >= 2'
           fi
 
           # GitHub turns an empty matrix include list into a job with no legs
           # that still reports success, so the emitted value itself is
-          # validated: it must parse as a JSON array carrying at least the two
-          # unconditional legs. A malformed or empty matrix fails this job
-          # instead of passing over nothing.
+          # validated: it must parse as a JSON array carrying the ubuntu leg,
+          # and outside pull requests the windows leg too. A malformed or
+          # empty matrix fails this job instead of passing over nothing.
           assert_matrix() {
             local label="$1" json="$2" jq_filter="$3"
             if ! printf '%s' "$json" | jq -e "$jq_filter" >/dev/null; then
               printf '::error::%s matrix output was %q\n' "$label" "$json"
               exit 1
             fi
           }
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            keyring_windows='true'
+            npm_global_windows='true'
+          else
+            keyring_windows='any(.[]; .name == "windows")'
+            npm_global_windows='any(.[]; .os == "windows-latest")'
+          fi
           assert_matrix keyring "$keyring_matrix" \
-            'type == "array" and length >= 2 and any(.[]; .name == "ubuntu") and any(.[]; .name == "windows")'
+            "type == \"array\" and $min_legs_filter and any(.[]; .name == \"ubuntu\") and $keyring_windows"
           assert_matrix npm-global "$npm_global_matrix" \
-            'type == "array" and length >= 2 and any(.[]; .os == "ubuntu-latest") and any(.[]; .os == "windows-latest")'
+            "type == \"array\" and $min_legs_filter and any(.[]; .os == \"ubuntu-latest\") and $npm_global_windows"
 
           printf 'keyring_matrix=%s\n' "$keyring_matrix" >> "$GITHUB_OUTPUT"
           printf 'npm_global_matrix=%s\n' "$npm_global_matrix" >> "$GITHUB_OUTPUT"
@@ -800,10 +829,9 @@ jobs:
   platform-macos:
     name: macos ${{ matrix.shard }}/3
     needs: changes
-    # Native-gated: these legs only run when the changes job's `native` filter
-    # says the macOS suite's inputs could have changed, so an ordinary source
-    # pull request stops paying for three macOS runners.
-    if: github.event_name != 'pull_request' || (needs.changes.outputs.ci == 'true' && needs.changes.outputs.native == 'true')
+    # Never on pull requests: macOS legs run after merge, on push to
+    # main/preview, and on dispatch and the schedule.
+    if: github.event_name != 'pull_request'
     runs-on: macos-latest
     # Three shards. Unsharded, this job was the critical path on every green dev
     # push (mean 14.9 min against a 4.7 min Linux maximum; devlog
@@ -979,7 +1007,7 @@ jobs:
     name: windows ${{ matrix.shard }}/9
     needs: [changes, select-windows-runner]
     if: >-
-      github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' && (github.event.inputs.lane == '' || github.event.inputs.lane == 'all') || github.event_name == 'pull_request' && needs.changes.outputs.windows == 'true'
+      github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' && (github.event.inputs.lane == '' || github.event.inputs.lane == 'all')
     runs-on: ${{ fromJSON(needs.select-windows-runner.outputs.runner) }}
     # Sharded like the Linux legs. The single-leg run reached 30 minutes on a
     # green suite and was killed in cleanup; four shards put each leg inside the
@@ -1278,7 +1306,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        # Pull requests run the ubuntu leg only; windows and macos run after merge.
+        os: ${{ fromJSON(github.event_name == 'pull_request' && '["ubuntu-latest"]' || '["ubuntu-latest","windows-latest","macos-latest"]') }}
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
@@ -1336,7 +1365,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        # Pull requests run the ubuntu leg only; macos and windows run after merge.
+        os: ${{ fromJSON(github.event_name == 'pull_request' && '["ubuntu-latest"]' || '["ubuntu-latest","macos-latest","windows-latest"]') }}
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
@@ -1467,9 +1497,9 @@ jobs:
   widget:
     name: macos widget + bundle
     needs: [changes, gates]
-    # Native-gated like platform-macos: the widget extension and app bundle
-    # are rebuilt only when native-capable paths changed.
-    if: github.event_name != 'pull_request' || (needs.changes.outputs.ci == 'true' && needs.changes.outputs.native == 'true')
+    # Never on pull requests, like platform-macos: the widget extension and
+    # app bundle are rebuilt after merge, on push, dispatch and the schedule.
+    if: github.event_name != 'pull_request'
     runs-on: macos-latest
     timeout-minutes: 30
     steps:
@@ -1719,13 +1749,13 @@ jobs:
           if [ "$EVENT_NAME" = "pull_request" ] && [ "$CHANGES_CI" != "true" ]; then
             scoped=not-requested
           fi
-          # platform-macos and widget carry the ordinary scope gate AND the native path filter.
-          # desktop-shell accepts that native set plus the package-E2E set.
-          # This mirrors that expression exactly; where it disagrees with the
-          # jobs' own `if:`, the gate fails by name instead of demanding
+          # platform-macos and widget never run on a pull request (macOS runs after merge).
+          # desktop-shell (ubuntu) carries the ordinary scope gate AND the native or
+          # package-E2E path filters. This mirrors those expressions exactly; where it
+          # disagrees with the jobs' own `if:`, the gate fails by name instead of demanding
           # success from a job that was deliberately left unselected.
           native=not-requested
-          if [ "$EVENT_NAME" != "pull_request" ] || { [ "$CHANGES_CI" = "true" ] && [ "$CHANGES_NATIVE" = "true" ]; }; then
+          if [ "$EVENT_NAME" != "pull_request" ]; then
             native=requested
           fi
           desktop_shell=not-requested
@@ -1775,11 +1805,6 @@ jobs:
             if [ -z "$LANE" ] || [ "$LANE" = "all" ]; then
               windows=requested
             fi
-          elif [ "$EVENT_NAME" = "pull_request" ] && [ "${CHANGES_WINDOWS:-}" = "true" ]; then
-            # A Windows-sensitive pull request (path filter or added-line marker) runs the
-            # nine shards and requires them, exactly as dispatch and the schedule do. A
-            # shard that only fails on a pull request is a regression in that pull request.
-            windows=requested
           fi
 
           # One line per job, mirroring that job's own `if:`. Adding a job to this workflow

@@ -8,13 +8,15 @@ on:
       - 'docs-site/src/content/docs/guides/composer-usage-gate-fallback.md'
       - '.github/workflows/codex-queue-helpers.yml'
   push:
-    branches: [dev, main, preview]
+    branches: [main, preview]
     paths:
       - 'scripts/codex-queue.*'
       - 'docs-site/astro.config.mjs'
       - 'docs-site/src/content/docs/guides/composer-usage-gate-fallback.md'
       - '.github/workflows/codex-queue-helpers.yml'
 
+  workflow_dispatch:
+
 permissions:
   contents: read
 

@@ -24,11 +24,11 @@ on:
       # produced no run and the gate dead-ended until a manual dispatch.
       - ".github/workflows/release.yml"
   push:
-    # Release lines only. release.yml needs a successful push run for the exact
-    # release SHA, and scripts/release.ts only releases from main or preview.
-    # Without a branch filter every feature-branch push whose range carried a
-    # dev merge touching these paths re-ran the macOS and Windows legs that the
-    # pull_request trigger above already runs for the same change.
+    # Release lines only (no dev: cross-platform legs run on dev by manual
+    # workflow_dispatch). Pull requests run only the Linux leg. main and preview
+    # must stay: release.yml needs a successful push run for the exact release
+    # SHA, and scripts/release.ts only releases from main or preview. Without a
+    # branch filter every feature-branch push would re-run all three legs.
     branches: [main, preview]
     paths:
       - "src/service.ts"
@@ -177,6 +177,8 @@ jobs:
           fi
 
   macos-launchd:
+    # Pull requests run the Linux leg only; macOS runs on manual dispatch and main/preview push.
+    if: github.event_name != 'pull_request'
     runs-on: macos-latest
     timeout-minutes: 10
     steps:
@@ -255,6 +257,8 @@ jobs:
           fi
 
   windows-schtasks:
+    # Pull requests run the Linux leg only; Windows runs on manual dispatch and main/preview push.
+    if: github.event_name != 'pull_request'
     runs-on: windows-latest
     timeout-minutes: 10
     steps:

@@ -15,15 +15,15 @@ Bun-native TypeScript with no separate server compile step.
 - `tests/` — Bun tests in domain directories that mirror `src/`
   (`tests/<domain>/*.test.ts`; `providers/` and `adapters/` have one more
   level for the larger vendors). The explicit map is
-  `scripts/test-layout/layout.json`, with regex seeds and migration state in
+  `scripts/test-layout/layout.json` plus its `explicitShards` sibling maps, with regex seeds and migration state in
   `scripts/test-layout/seeds.json`; `tests/test-layout.test.ts` enforces that every file resolves to a
   domain and sits in it, and only the two layout guards live at the root.
   Shared helpers in `tests/helpers/`, fixtures in `tests/fixtures/`, broader
   scenarios in `tests/e2e-style/`. Source-oracle tests resolve the repository
   through `tests/helpers/repo-root.ts` (`repoRoot()`, `repoPath()`,
   `helperPath()`, `fixturePath()`), never `import.meta.dir + "/.."`. A new
   test file lands in its domain directory and needs an entry in both
-  `layout.json` `explicit` and `tests/fixtures/test-layout-expected.json`
+  `layout.json` `explicit` (or its domain shard) and a `tests/fixtures/test-layout-expected*.json` shard
   (`tests/test-layout-tooling.test.ts` names the missing one); the regex
   seeds in `seeds.json` place a conventionally named file until then.
   History: `devlog/_fin/260905_test_modularization_and_windows/`.
@@ -268,7 +268,7 @@ fails `file-size ratchet: repository` for your branch and for every branch cut f
 Two branches can each stay under a cap alone and sum over it together; that is what
 happened in #4908, #5011 and #5018. The remedy is always a move, never a number: put the
 new case in a sibling file, byte for byte, and register it in **both**
-`scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`.
+`scripts/test-layout/layout.json` (or its domain shard) and a `tests/fixtures/test-layout-expected*.json` shard.
 `d3ca5522db` is the original precedent.
 
 A moved test is not automatically the same test. One case moved out of
@@ -365,6 +365,14 @@ than nudged.
   recorded in [`CREDITS.md`](./CREDITS.md); `missing_coauthor_credit` in
   `.github/scripts/pr-carry-attribution.cjs` is why the list should not grow.
 
+## CI policy (maintainer decision — do not change)
+
+- Pull requests run **only the fast Ubuntu subset**.
+- Full cross-platform (macOS/Windows) CI runs **only** via manual
+  `workflow_dispatch` and on push to `main`/`preview` (release lines).
+- **Never** add a `dev` push trigger, or `pull_request` runs for macOS/Windows
+  jobs, to any workflow. PRs that change this policy will be closed.
+
 ## Branch policy
 
 - `dev` — the single integration branch and the target for every pull request.

@@ -36,6 +36,14 @@ Source development requires the `bun` CLI on your `PATH`. The published npm pack
 Bun runtime for end users. Package scripts such as `bun run test` and `bun run prepush` may resolve
 Bun through that bundled dependency.
 
+## CI policy (maintainer decision — do not change)
+
+- Pull requests run **only the fast Ubuntu subset**.
+- Full cross-platform (macOS/Windows) CI runs **only** via manual
+  `workflow_dispatch` and on push to `main`/`preview` (release lines).
+- **Never** add a `dev` push trigger, or `pull_request` runs for macOS/Windows
+  jobs, to any workflow. PRs that change this policy will be closed.
+
 ## Pull request contract
 
 A ready-for-review PR is the author's claim that the change is complete, understood, tested, and suitable for merging. Opening a PR does not transfer responsibility for the branch to maintainers.

@@ -154,10 +154,6 @@ See [SPONSORS.md](./SPONSORS.md).
 <td>Thanks to <a href="https://www.orcarouter.ai/?utm_source=opencodex&utm_medium=readme">OrcaRouter</a> for sponsoring this project! OrcaRouter is one OpenAI-compatible AI gateway for production AI: adaptive routing that grades every prompt and sends it to the model that clears your bar, automatic failover, routing rules as code, zero-markup provider pricing with prompt caching, and guardrails, an agent firewall, and request logs on every call across 200+ models. Pick <code>OrcaRouter</code> in the Add provider picker or run <code>ocx provider add orcarouter</code>; <code>orcarouter/auto</code> is the adaptive router.</td>
 </tr>
 <tr>
-<td width="180"><a href="https://www.packyapi.com/register?aff=k5KT"><img src="assets/sponsors/packycode.png" alt="PackyCode" width="150"></a></td>
-<td>Thanks to <a href="https://www.packyapi.com/register?aff=k5KT">PackyCode</a> for sponsoring this project! PackyCode is a stable, high-performance API relay provider, offering relay services for Claude Code, Codex, Gemini, and more. With automatic failover, smart routing, and unlimited concurrency, it turns AI into a real productivity tool. <a href="https://www.packyapi.com/register?aff=k5KT">Register via this link</a> and get started! Pick <code>PackyCode</code> in the Add provider picker or run <code>ocx provider add packycode</code>.<br><sub>PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。具备自动故障转移、智能路由和无限并发等多种功能，让 AI 编程成为真正的生产力工具。<a href="https://www.packyapi.com/register?aff=k5KT">点此链接注册</a>，立即开始使用！</sub></td>
-</tr>
-<tr>
 <td width="180"><a href="https://tokenlab.sh/r/OPENCODEX"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/tokenlab-dark.png"><img src="assets/sponsors/tokenlab-light.png" alt="TokenLab" width="150"></picture></a></td>
 <td>Thanks to <a href="https://tokenlab.sh/r/OPENCODEX">TokenLab</a> for sponsoring this project! TokenLab gives coding agents one API key for leading models, supporting OpenAI Responses and Chat Completions, Anthropic Messages, and Gemini's native API formats, with streaming and tool calling. It also provides an MCP server and agent Skills for easy integration. Choose your delivery mode and pay as you go. Pick <code>TokenLab</code> in the Add provider picker or run <code>ocx provider add tokenlab</code>.<br><sub>TokenLab 为编程智能体提供统一的多模型 API，一枚 API Key 即可接入主流模型，支持 OpenAI Responses、Chat Completions、Anthropic Messages 和 Gemini 原生 API 格式，以及流式输出和工具调用。同时提供 MCP 服务器和 Agent Skills，方便接入现有工作流；交付模式可选，按量付费。</sub></td>
 </tr>