lidge-jun · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -77,7 +77,7 @@ on:
   # Nightly safety net. The Windows shards run on a pull request only when the
   # changes job judges it Windows-sensitive, so anything that slips past that
   # filter must still be caught within a day: a scheduled run requests the full
-  # lane=all matrix (nine Windows shards and the macOS control included).
+  # lane=all matrix (eleven Windows shards and the macOS control included).
   #
   # GitHub runs schedules from the DEFAULT branch, which is main, so this
   # trigger activates only once this file reaches main by promotion, and the
@@ -235,7 +235,7 @@ jobs:
       # Push, dispatch and schedule run both regardless; see the docker/keyring filters.
       docker: ${{ steps.narrow.outputs.docker }}
       keyring: ${{ steps.narrow.outputs.keyring }}
-      # Whether this pull request needs the nine Windows shards: the windows path
+      # Whether this pull request needs the Windows shards: the windows path
       # filter below OR an added src/tests line naming a Windows marker. Computed
       # by scripts/ci/windows-sensitive-diff.sh, which validates its input and
       # treats the diff as data.
@@ -428,7 +428,7 @@ jobs:
               - 'package.json'
               - 'bun.lock'
               - '.github/workflows/ci.yml'
-            # Paths whose change selects the nine Windows suite shards on a pull
+            # Paths whose change selects the Windows suite shards on a pull
             # request. These carry the Windows service, update, shim, intercept,
             # ACL and process code, and the harness every Windows shard runs.
             # scripts/ci/windows-sensitive-diff.sh adds the content markers.
@@ -696,10 +696,7 @@ jobs:
       # gui/package.json. Without this the affected shards die on
       # `Cannot find module 'react/jsx-dev-runtime'` while the other shards pass.
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd gui
-          bun install --frozen-lockfile
+        run: bash scripts/ci/bun-install-frozen.sh . gui
 
       # Nor is the build. Tests that fetch the served dashboard read the session
       # bootstrap meta tags out of `gui/dist/index.html`, so without a build the
@@ -734,7 +731,7 @@ jobs:
         with:
           role: test-runner # See the Bun roles contract above test.
       - name: Install dependencies and build the GUI the tests serve
-        run: bun install --frozen-lockfile && cd gui && bun install --frozen-lockfile && bun run build
+        run: bash scripts/ci/bun-install-frozen.sh . gui && cd gui && bun run build
       - name: Test the files this pull request reaches
         run: bash scripts/ci/run-changed-tests.sh
 
@@ -760,10 +757,7 @@ jobs:
           role: test-runner # See the Bun roles contract above test.
 
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd gui
-          bun install --frozen-lockfile
+        run: bash scripts/ci/bun-install-frozen.sh . gui
 
       - name: Build GUI
         run: |
@@ -802,10 +796,7 @@ jobs:
           role: test-runner # See the Bun roles contract above test.
 
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd gui
-          bun install --frozen-lockfile
+        run: bash scripts/ci/bun-install-frozen.sh . gui
 
       - name: Build GUI
         run: |
@@ -840,10 +831,7 @@ jobs:
           role: test-runner # See the Bun roles contract above test.
 
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd gui
-          bun install --frozen-lockfile
+        run: bash scripts/ci/bun-install-frozen.sh . gui
 
       - name: GUI lint
         if: needs.changes.outputs.gui == 'true'
@@ -897,29 +885,29 @@ jobs:
         run: bun run src/cli/index.ts help
 
   platform-macos:
-    name: macos ${{ matrix.shard }}/3
+    name: macos ${{ matrix.shard }}/4
     needs: changes
     # 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
-    # 260905_test_modularization_and_windows/003), so it was split in two. The
-    # suite then outgrew two halves: across seventeen dev dispatches from
-    # 2026-10-04 to 10-12 the slower half's test step went from 867s to 1155s,
-    # and run 38214884055 cancelled macos 2/2 at this cap with 68 files left
-    # while every test it had run was passing (#6978). Replaying the duration
-    # assignment against those runs' measured per-file times puts the slowest of
-    # three shards at 635-796s of tests, about 14 minutes with setup. The cap
-    # stays 20: the suite needs another shard, not a longer wait, and a wedged
-    # shard (#4956) is still cut off as early as before. The full-membership
-    # control runs the same bounded batches without sharding on explicit dispatch.
+    # Four shards. Three replaced two after run 38214884055 hit this cap with
+    # 68 files left and no failing tests (#6978). The suite outgrew three too:
+    # run 40727740334 took 13.1-16.4m, 40743681086 12.7-13.7m, and
+    # 40756291846 15.0-17.1m. In dev lane=all run 40766068492 (b16bc0978b),
+    # macos 1/3 (123090588998) reached batch 73/88 and macos 2/3
+    # (123090589363) batch 93/93 before this cap cancelled them, with no failing
+    # tests. The cap stays 20: the suite needs another shard, not a longer wait,
+    # and a wedged shard (#4956) is still cut off as early as before. Four suite
+    # shards + control + widget/bundle request six macOS jobs for five runner
+    # slots: one queues, and each run pays one extra shard's setup overhead.
+    # The full-membership control runs the same bounded batches without sharding
+    # on explicit dispatch.
     timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2, 3]
+        shard: [1, 2, 3, 4]
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
@@ -965,7 +953,7 @@ jobs:
 
       - name: Test in fresh-process batches
         env:
-          TEST_SHARD: ${{ matrix.shard }}/3
+          TEST_SHARD: ${{ matrix.shard }}/4
           BUN_TEST_FILE_SCOPE: all
           BUN_TEST_BATCH_SIZE: '12'
           BUN_TEST_PARALLEL: '1'
@@ -1077,7 +1065,7 @@ jobs:
   # each landed with green pull-request CI while breaking Windows, which is why
   # that dispatch is part of merging a Windows-sensitive pull request.
   platform-windows:
-    name: windows ${{ matrix.shard }}/9
+    name: windows ${{ matrix.shard }}/11
     needs: [changes, select-windows-runner]
     if: >-
       github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' && (github.event.inputs.lane == '' || github.event.inputs.lane == 'all')
@@ -1108,21 +1096,18 @@ jobs:
     # test deadline and all six shards, but left the whole batch and cleanup a
     # 30-minute bound.
     #
-    # Six shards then grew into the 30-minute ceiling too. Across seven lane=all
-    # dispatches the six shard totals were 114.3-133.2 minutes. The worst observed
-    # shard imbalance was 1.43x its dispatch's per-shard average. Eight shards leave
-    # no margin: 133.2 / 8 * 1.43 * 1.25 = 29.8 minutes after the already-observed
-    # 25% run-to-run slowdown. Nine gives 133.2 / 9 * 1.43 * 1.25 = 26.5 minutes.
-    # Keep the 30-minute bound and pay for three more concurrent runners plus their
-    # repeated checkout/install/build setup so test work, rather than the ceiling,
-    # shrinks. The per-batch timeout below is independent: it aborts a stuck Bun
-    # process but adds no delay to a healthy one, so calibrating it does not change
-    # this total-work projection.
+    # Nine shards also reached the ceiling: run 40756291846 cancelled 7/9 at batch
+    # 49/60; run 40743681086's successful shards took 22.1-29.5 minutes. Refreshing
+    # Windows weights from completed primary batches in both runs puts test work
+    # at 24.36/21.92/19.93 minutes with 9/10/11 shards. With the observed 2.4-minute
+    # maximum setup, eleven projects ~22.4 minutes; 25% test variance makes ~27.3.
+    # Pay for two extra setups (~3.3 runner-minutes at the older run's mean), keep
+    # the 30-minute job bound and all tests, and leave batch deadlines independent.
     timeout-minutes: 30
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9]
+        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
     steps:
       - name: Show selected runner
         shell: bash
@@ -1202,7 +1187,7 @@ jobs:
         # and service-manager guard before the lock boundary.
         shell: bash
         env:
-          TEST_SHARD: ${{ matrix.shard }}/9
+          TEST_SHARD: ${{ matrix.shard }}/11
           BUN_TEST_FILE_SCOPE: all
           BUN_TEST_BATCH_SIZE: "6"
           BUN_TEST_BATCH_TIMEOUT_SECONDS: "480"
@@ -1341,7 +1326,7 @@ jobs:
   # aggregate reported success while nothing had read the change (#5001).
   #
   # Running the gate directly here, rather than adding `structure/**` to `ci`,
-  # keeps a prose edit from starting nine Windows shards and two macOS shards for
+  # keeps a prose edit from starting the Windows shards and macOS shards for
   # a check that takes seconds. It runs whenever `structure/` changes, including
   # alongside a `src/` change where the suite covers it too; a duplicate of a
   # seconds-long check is not worth a condition that could be wrong.
@@ -1893,7 +1878,7 @@ jobs:
             if [ -z "$LANE" ] || [ "$LANE" = "all" ] || [ "$LANE" = "macos-control" ]; then
               dispatch=requested
             fi
-            # Only the default/all lane requests the nine Windows suite shards.
+            # Only the default/all lane requests the Windows suite shards.
             if [ -z "$LANE" ] || [ "$LANE" = "all" ]; then
               windows=requested
             fi
@@ -1965,10 +1950,10 @@ jobs:
           # started: five successes and one skipped leg roll up to `success`. No matrix here
           # carries a per-leg `if:`, so a leg can only be skipped when its whole job is, which
           # the expectation table above already catches. What that table cannot catch is a
-          # matrix that produced FEWER legs than the nine a dispatch is run to read, so count
-          # them by name. The nine Windows legs are the entire output of that dispatch.
+          # matrix that produced FEWER legs than the eleven a dispatch is run to read, so count
+          # them by name. The eleven Windows legs are the entire output of that dispatch.
           if [ "$windows" = requested ]; then
-            shards=9
+            shards=11
             # `filter=latest` (the default) is the latest execution of each job in the run,
             # which is what a human reading the run sees. Asking for one ATTEMPT instead would
             # fail every partial re-run: "Re-run failed jobs" puts only the repaired shard in

diff --git a/.github/workflows/cleanup-orphaned-workflows.yml b/.github/workflows/cleanup-orphaned-workflows.yml
@@ -35,9 +35,9 @@ jobs:
           persist-credentials: false
 
       - name: Setup Bun
-        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
-        with:
-          bun-version: 1.4.2
+        # The repository composite reads package.json dependencies.bun from the
+        # checkout above, so this job cannot drift from the runtime pin.
+        uses: ./.github/actions/setup-project-bun
 
       - name: Remove stale workflow histories
         env:

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -29,7 +29,8 @@ jobs:
         with:
           path: ./docs-site
           node-version: 22
-          package-manager: bun@latest
+          # Must equal package.json dependencies.bun (asserted in ci-workflows.test.ts).
+          package-manager: bun@1.4.4
 
   deploy:
     needs: build

diff --git a/AGENTS.md b/AGENTS.md
@@ -195,7 +195,7 @@ it binds you regardless of which mechanism is within reach.
 
 ```bash
 bun install
-bun run typecheck      # bun x tsc --noEmit (strict)
+bun run typecheck      # bun check --no-script --noEmit (strict)
 bun run test:changed   # import-graph tests against the resolved `dev` merge base
 bun run test           # full tests/ suite (default before review)
 bun run lint:gui       # GUI eslint
@@ -375,6 +375,20 @@ than nudged.
   add `ci:full` for changes it cannot see (subprocesses, files read as data, generated output).
 - Full cross-platform (macOS/Windows) CI runs **only** via manual
   `workflow_dispatch` and on push to `main`/`preview` (release lines).
+- A manual `lane=all` dispatch is a **batch check on `dev`**, never a per-PR gate.
+  One run is about 32 jobs (11 Windows, at least 6 macOS, 15 Linux) and six runner-hours, and the
+  account has only five macOS slots (a macOS job can queue), so per-PR dispatches starve
+  every other check. On 2026-10-27, parallel agent lanes dispatched 48 of them in twelve hours (about 13,000
+  runner-minutes). The queue passed 200 runs, and ordinary PR checks waited hours to start.
+  - Merge a pull request, including a Windows- or macOS-sensitive one, on its green PR
+    CI. After a batch of merges, run one `gh workflow run ci.yml --ref dev` as described
+    under "Batched merges". If it is red, stop merging and fix `dev` from that batch.
+  - Do not dispatch `lane=all` for a PR branch unless a maintainer explicitly asks for it
+    on that PR. Even then, run it once, on the exact head about to merge. Never re-dispatch
+    because the head moved (an `origin/dev` merge or a review fix), and never rerun to
+    green. Cancel your own superseded dispatches with `gh run cancel`.
+  - Every description edit or label change starts three event-gate workflows. Batch those
+    edits, and keep the number of agents working pull requests in parallel small.
 - **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.
 

diff --git a/README.md b/README.md
@@ -1,10 +1,11 @@
 <p align="center">
-  <img src="assets/banner.png" alt="opencodex — universal provider proxy for Codex, Claude Code, Claude Desktop and Grok Build" width="100%">
+  <img src="assets/banner.png" alt="opencodex — one local gateway for Codex, Claude Code, Claude Desktop, Grok Build and more" width="100%">
 </p>
 
-<h3 align="center">make codex open!</h3>
-<p align="center"><b>Universal provider proxy for OpenAI Codex, Claude Code, Claude Desktop &amp; Grok Build</b><br>
-Two commands, and every one of them runs any LLM you point it at.</p>
+<h3 align="center">One local gateway for your AI coding tools and models.</h3>
+<p align="center"><b>Use the models you choose with Codex, Claude Code, Claude Desktop and Grok Build,<br>
+and connect OpenCode, Pi, Qoder, WorkBuddy, Kilo, Cline, T3 Code and more through managed configs.</b><br>
+<a href="https://opencodex.me/reference/client-support/">See every supported tool →</a></p>
 
 <p align="center">
   <a href="https://x.com/claudeebum"><img src="https://img.shields.io/badge/%40claudeebum-000000?logo=x&logoColor=white" alt="Follow @claudeebum on X"></a>
@@ -80,10 +81,12 @@ Sol drives the session and calls a Kimi K3 subagent.
   <a href="README.md">English</a> · <a href="readme/README.fr.md">Français</a> · <a href="readme/README.ko.md">한국어</a> · <a href="readme/README.zh-CN.md">简体中文</a> · <a href="readme/README.zh-TW.md">繁體中文</a> · <a href="readme/README.ru.md">Русский</a> · <a href="readme/README.ja.md">日本語</a> · <a href="readme/README.tr.md">Türkçe</a> · 📖 <a href="https://opencodex.me/"><b>Full documentation →</b></a>
 </p>
 
-opencodex is a lightweight local proxy that translates Codex's Responses API into whatever your
-provider speaks — streaming, tool calls, reasoning tokens, images, in both directions. Use Claude,
-Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama, or any other LLM with Codex, Claude Code, Claude
-Desktop, and Grok Build. It can also manage a **ChatGPT account pool** for Codex auth: add accounts,
+opencodex is a lightweight local gateway between your coding tools and your model providers. It
+accepts the Responses, Chat Completions and Anthropic Messages APIs and translates each request into
+whatever your provider speaks, carrying streaming, tool calls, reasoning and images where the client,
+model and provider support them. Use Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama and other
+providers with Codex, Claude Code, Claude Desktop, Grok Build and the tools listed on the
+[client support page](https://opencodex.me/reference/client-support/). It can also manage a **ChatGPT account pool** for Codex auth: add accounts,
 refresh their quotas in the dashboard, and let new sessions auto-route to the lowest-usage healthy
 account while existing threads stay pinned to the account that started them.
 
@@ -102,6 +105,22 @@ Open **http://localhost:10100** and configure everything in the web dashboard
 (40+ built-ins, or any OpenAI-compatible endpoint), pick models, manage accounts. `ocx gui`
 re-opens the dashboard at any time.
 
+### Connect your tool
+
+Connect the tool you already use:
+
+| Tool | How to connect |
+|---|---|
+| Codex | Turn on the Codex switch on the dashboard's **Connect** page, then run `codex` as usual. On a local listener this points Codex's built-in provider at the proxy. From the terminal, run `ocx init` before adding providers in the dashboard and accept its Codex prompt. |
+| Claude Code | With the `claude` CLI installed, run `ocx claude`. It starts the proxy if needed and launches Claude Code through it. |
+| Claude Desktop | Run `ocx claude desktop`. On a new install it sets up the gateway profile for the whole app; an existing first-party setup is kept, and `ocx claude desktop apply --gateway` switches explicitly. See the [Claude Code guide](https://opencodex.me/guides/claude-code/). Fully quit and reopen Claude Desktop after a switch. |
+| Grok Build | On a local listener with Grok integration enabled, `ocx start` registers the models when `~/.grok` exists; pick an `ocx-*` model in Grok Build. Remote setups: see the [Grok Build guide](https://opencodex.me/guides/grok-build/). After adding providers, restart the proxy (or run `ocx ensure` when Codex autostart is enabled) to refresh the list. |
+| Tools with a managed integration | Use the dashboard **Connect** page, or `ocx integration client enable --client <id>`. |
+| Any other tool | Set a custom OpenAI-compatible base URL of `http://localhost:10100/v1`, or an Anthropic base URL of `http://localhost:10100`. |
+
+The [client support page](https://opencodex.me/reference/client-support/) lists which path each tool has
+and which protocol it speaks.
+
 <details>
 <summary><b>Desktop app (beta)</b></summary>