@vzn/vx-migrate 0.0.640 → 0.0.642

package/README.md

@@ -62,7 +62,7 @@ Rules:
 - A transit node (Turbo's documented pattern, its with-vitest example: `transit: { dependsOn: ["^transit"] }` with no script anywhere, and `test: { dependsOn: ["transit"] }`) is a key-only task in each package that defines it: a keyed group (no command, nothing spawns) keyed on its inputs, with its `^transit` edge, so a dependant's `test` re-keys on its dependencies' sources as Turbo re-hashes it. A `^` task that some package has a script for, or that nothing depends on, is no transit node. A package without the script of a `^` task others run gets the same key-only task, as Turbo hashes a no-op node there: an edit to it re-keys its dependants. A `build` whose only edge is `^build` is not written: core gives every project with no `build` that node (solid's three script-less packages each got a `build` of their own). A dependency without the script whose own edges lack `^x` gets it too, so a `^x` stops there as Turbo's does (opencode's `build: { dependsOn: [] }`: core walked past to the builds below, which Turbo's `^build` never reaches).
 - `with` (tasks Turbo runs alongside, `web#dev` with `api#dev`): an edge to each sidecar that is persistent, so vx starts the task once the sidecar has spawned and runs the sidecar only when the task runs; a sidecar that ends would be waited for, so it is a todo instead, and a pair that names each other keeps one edge (two would be a cycle). A task with no script whose `with` names persistent sidecars (Turbo's with-tailwind example: `ui` has no `dev` script, its `dev` starts `dev:styles` and `dev:components`) is a group task that depends on them.
 - `inputs`: a structured entry (Turbo 2.11) is its `globs`, plus `**/*` with `withDefaults`, for `startup` and `jit` alike; `dependencyOutputs` adds none where the producer is cached (vx folds each dependency's key); from a `cache: false` producer (vercel/vercel's `//#generate:cache-keys`, which records the host) the named files, or its outputs, are a `inputs.workspaceRuntime` probe, and `inputs.tasks` leaves the producer out, so core answers the probe after it ran. Then: absent or `[]` → `**/*` (Turbo's default); `$TURBO_DEFAULT$` → `**/*`; exclusions alone narrow `**/*`; `$TURBO_ROOT$/<path>` → `inputs.workspaceFiles` (negation kept); any other `$TURBO_ROOT$` use is a todo. `globalDependencies` and Turbo 1's `globalDotEnv` land in `workspaceFiles` too, and a task's Turbo 1 `dotEnv` in its `files`. Turbo 1's `$NAME` entries, in `globalDependencies` or a task's `dependsOn`, are env vars: they join `inputs.env` and `exec.env.passThrough`. A package nested in the task's package (cal.com's apps inside `@calcom/app-store`) is hashed by Turbo with its parent, and core's globs stop at a project: each glob that reaches one is also listed in `inputs.workspaceFiles`. Turbo's glob grammar is translated as Nx's is (`*.[jt]s` is `*.{[jt],j,t}s`); an input with no safe form widens to `**/*` with a todo. A wildcard `X/**` input, `!` or not, also lists `X`, as outputs do: Turbo's `**` matches zero segments, so `*/**` keys on the package-root files too. A `.env`-shaped input (`.env*`, `.env.local`, a task's Turbo 1 `dotEnv`, create-turbo's `globalDependencies: ["**/.env.*local"]`) is gitignored as a rule, so it is keyed by a probe that hashes the `.env` files it can name (`inputs.runtime`) or, for a root entry, the files its root-relative globs name, hidden ones too, as Turbo's `*` matches them (`workspaceRuntime`; `**/<name>` is a `find -name` that skips `node_modules`, and another `**` walks the workspace), rather than as a file glob git never reports. A package whose `.env` globs all sit at its root gets a one-shell probe of that directory; one below the root walks the package.
-- `outputs`: `$TURBO_ROOT$/<path>` → `cache.outputs.workspaceFiles`; a negated output rides beside its positives and takes its paths back from the clean, the save and the restore (Next's `.next/**` minus `!.next/cache/**` keeps the cache), and one with no positive beside it takes back nothing and is dropped. Past its first segment an output takes Turbo's grammar (`dist/**/*.[cm]js`); the first stays a literal (a route directory). A wildcard `X/**` also lists `X`: Turbo's `**` matches zero segments, so medusa's `*/**` caches the package-root `tsconfig.tsbuildinfo` too (its `package.json` is taken back, below); a literal `dist/**` needs no `dist`. An output whose first segment is a wildcard (`**/*.d.ts`, medusa's `*/**`) stays cached, as in `nx()` (`turbo()` 2026-10-14): Turbo never cleans an output, vx cleans it before every run and every restore, and such a glob can reach the sources; core never cleans a committed file, and every untracked file it reaches is deleted, which `vx lock`'s warnings name (`output "*/**": … every untracked file this glob reaches is deleted`). Negations beside it (`!src/**`) keep what they name. Without git the files cannot be told apart, and the task runs uncached with a todo. A glob that reaches no tracked kind gets no warning: one segment with a literal extension the package tracks no file of (`*.xml`), `**/<dir>/**` when the package tracks nothing under a directory of that name (vercel/ai's `**/dist/**`), and a first segment no tracked top-level entry matches (tldraw's `dist-*/**`). An output that covers the package's own `package.json` (trpc's client build lists it: the build rewrites `exports`) takes the manifest back with `!package.json` and keeps the cache, in `turbo()` as in `nx()` (owner, 2026-10-03): vx would otherwise delete it before every run. The build rewrites a file it may list as an input (`@vzn/vx-lockfile` lists `package.json`), so the Turbo mapping also sets `inputStability: { strategy: 'mutable' }` and an identical rewrite counts as unchanged. So does one that covers the package's vx.config; `turbo()` and `nx()` check the config the package has, and `vx-migrate` the one it writes, so sanity's `*.js` shims stay cached beside none. `nx()` keeps a wildcard-first output cached the same way (owner, 2026-10-03). A committed file under an output (typescript-eslint's `data/sponsors.json` in a cached `data`) needs nothing: core never cleans a file git tracks, so it survives and the task keeps its cache.
+- `outputs`: `$TURBO_ROOT$/<path>` → `cache.outputs.workspaceFiles`; a negated output rides beside its positives and takes its paths back from the clean, the save and the restore (Next's `.next/**` minus `!.next/cache/**` keeps the cache), and one with no positive beside it takes back nothing and is dropped. Past its first segment an output takes Turbo's grammar (`dist/**/*.[cm]js`); the first stays a literal (a route directory). A wildcard `X/**` also lists `X`: Turbo's `**` matches zero segments, so medusa's `*/**` caches the package-root `tsconfig.tsbuildinfo` too (its `package.json` is taken back, below); a literal `dist/**` needs no `dist`. An output whose first segment is a wildcard (`**/*.d.ts`, medusa's `*/**`) stays cached, as in `nx()` (`turbo()` 2026-10-14): Turbo never cleans an output, vx cleans it before every run and every restore, and such a glob can reach the sources; core never cleans a committed file, and every untracked file it reaches is deleted, which `vx lock`'s warnings name (`output "*/**": … every untracked file this glob reaches is deleted`). Negations beside it (`!src/**`) keep what they name. Without git the files cannot be told apart, and the task runs uncached with a todo. A glob that reaches no tracked kind gets no warning: one segment with a literal extension the package tracks no file of (`*.xml`), `**/<dir>/**` when the package tracks nothing under a directory of that name (vercel/ai's `**/dist/**`), and a first segment no tracked top-level entry matches (tldraw's `dist-*/**`). An output that covers the package's own `package.json` (trpc's client build lists it: the build rewrites `exports`) takes the manifest back with `!package.json` and keeps the cache, in `turbo()` as in `nx()` (owner, 2026-10-03): vx would otherwise delete it before every run. The build rewrites a file it may list as an input (`@vzn/vx-lockfile` lists `package.json`), so the Turbo mapping also sets `inputStability: { strategy: 'mutable' }` and an identical rewrite counts as unchanged. So does one that covers the package's vx.config; `turbo()` and `nx()` check the config the package has, and `vx-migrate` the one it writes, so sanity's `*.js` shims stay cached beside none. `nx()` keeps a wildcard-first output cached the same way (owner, 2026-10-03). A committed file under an output (typescript-eslint's `data/sponsors.json` in a cached `data`) needs nothing: core never cleans a file git tracks, so it survives and the task keeps its cache. A task whose command runs `tsc` that writes a `.tsbuildinfo` (`-b`, `composite` or `incremental`, read through the tsconfig's `extends` and, for `-b`, its `references`) outside its outputs also outputs that file: tsc re-emits only what its buildinfo calls changed, so with `rootDir: "src"` and `outDir: "dist"` its `tsconfig.tsbuildinfo` beside the tsconfig survived the clean before a miss and the miss cached a `dist/` holding only the edited file. Nx infers the file as an output; Turbo never cleans `dist/`.
 - `env` / `passThroughEnv`: explicit names go to `inputs.env` (env only) and `exec.env.passThrough` (both, plus both globals); a wildcard expands over the run's environment under `turbo()`, which maps where the tasks run (a new variable name such a wildcard matches maps afresh); the CLI, which writes for another environment, lists the names the task's package and its workspace dependencies spell (a root task: the whole repo; clerk's `E2E_*`), noted once per entry, and one nothing spells is a todo; `*` is the only wildcard, as in Turbo, so `\*`, a leading `\!`, `?` and `[` are literal: unkey's `NEXT_PUBLIC_\*` names one variable, which vx cannot key, so it is dropped and reported once for the workspace with the count of tasks naming it (openstatus's root `build` env `\*` had written one todo into each of 45 configs; `turbo()`: only when the run's environment sets it, as Turbo hashes nothing otherwise); and a `!` entry (openstatus' `!NEXT_PUBLIC_VERCEL_URL`) removes the names it matches from its list, with no todo, since vx matches no name it is not given. A name both a global list and the task's own list carry is listed once. A name that is no shell variable name (`p-q`) is keyed but left out of `exec.env.passThrough`, as `sh` drops it before the task runs.
 - Framework inference (Turbo hashes and passes Next's `NEXT_PUBLIC_*`, Vite's `VITE_*`, … for a package that depends on the framework): `turbo()` expands the prefix over the run's environment; the CLI writes the names the tracked source and `.env.example` of the package and its workspace dependencies spell (the bare prefix, as a `startsWith` test spells it, is none) (Next bundles theirs: cal.com's web, 23 alone, 58 with them), and a note asks for any only an installed dependency reads.
 
@@ -231,7 +231,7 @@ It is the one command a repo needs (`pnpx @vzn/vx-migrate` in a pnpm repo works
 - In a Turbo or Nx repo, in a terminal, it asks which adoption you want: **native** (the default, a `vx.config.ts` per package) or **keep** (a workspace file declaring `turbo()` or `nx()`). `--native` / `--keep` answer it; with no terminal (CI, a pipe) it is native. Elsewhere both are refused. A repo already set up (a workspace file declaring neither, and project configs) is said to be, exit 0, unless `--force`.
 - Native or keep, a remote cache the repo shows is declared: `turboCache()` for turbo.json's enabled `remoteCache`, a `turbo link`ed `.turbo/config.json` or a CI file (`.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/config.yml`) setting `TURBO_TOKEN`; `nxCache()` for one setting `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. The report names the file that showed it. Nx Cloud (`nxCloudId`, `nxCloudAccessToken`, the `nx-cloud` runner) is named instead: vx does not speak its wire.
 - With no `.vx/workspace.*` yet, it writes one declaring the plugins the repo calls for (`src/workspace-plugins.ts`): the remote cache above, the `@vzn/vx-lockfile` factory for the lockfile (`pnpm()`, `bun()`, `npm()`, `yarn()`), `scheduleHistoryPlugin()`, and `github()` when `.github/workflows` exists, from `@vzn/vx-ci`, each installed beside `@vzn/vx` at vx-migrate's own version. Keep adds them to the file it writes, or to one already in that shape; any other workspace file is the user's and left alone. Native over a file vx wrote (a keep adoption's) rewrites it: `turbo()` and `nx()` go, since the configs written replace them, and the other plugins stay.
-- It installs what the written files import with the repo's own manager (`packageManager`, else the lockfile): `@vzn/vx`, the declared plugins' packages, and `@vzn/vx-migrate` for keep or when a written task runs its `nx-exec` or `nx-env` bin (`pnpm add -D -w`, `yarn add -D -W` on Yarn 1 and without `-W` on Yarn 2+, `bun add -d`, `npm install -D`). A package the root both lists and has installed at vx-migrate's own version is left alone; any other is installed at that version, and so is every other `@vzn/vx-*` plugin the root lists from the registry (one install moves them together, as `vx upgrade` does). Native removes a listed `@vzn/vx-migrate` when nothing written needs it (no `nx-exec` / `nx-env` task, no `turboCache()` or `nxCache()` left in the workspace file): `pnpm remove -w`, `yarn remove` (`-W` on Yarn 1), `bun remove`, `npm uninstall`. `--no-install` skips both. vx-migrate runs only with the `@vzn/vx` of its own release, which it installs: one of another release (a `bun x` install directory keeps the one it had) is refused, naming where it was loaded.
+- It installs what the written files import with the repo's own manager (`packageManager`, else the lockfile): `@vzn/vx`, every `@vzn/vx-*` package the workspace file imports (one an earlier init wrote included), and `@vzn/vx-migrate` for keep or when a written task runs its `nx-exec` or `nx-env` bin (`pnpm add -D -w`, `yarn add -D -W` on Yarn 1 and without `-W` on Yarn 2+, `bun add -d`, `npm install -D`). A package the root both lists and has installed at vx-migrate's own version is left alone; any other is installed at that version, and so is every other `@vzn/vx-*` plugin the root lists from the registry (one install moves them together, as `vx upgrade` does). Native removes a listed `@vzn/vx-migrate` when nothing written needs it (no `nx-exec` / `nx-env` task, no `turboCache()` or `nxCache()` left in the workspace file): `pnpm remove -w`, `yarn remove` (`-W` on Yarn 1), `bun remove`, `npm uninstall`. `--no-install` skips both. vx-migrate runs only with the `@vzn/vx` of its own release, which it installs: one of another release (a `bun x` install directory keeps the one it had) is refused, naming where it was loaded.
 - Native, once the files are written, it ends with `vx lock`: `.vx/projects.lock.json` is written and the graph rules are checked, its line the report's `lock` row. A refusal prints above the report and the configs stay written (exit 0). `--no-install` skips it, since the plugins the workspace file declares are not installed yet, and `next` then starts with `vx lock`.
 
 A Lerna repo is an Nx one: Lerna 6+ runs `lerna run` on Nx's task runner over the graph `nx graph` exports, nx.json or not, so a `lerna.json` with no nx.json and no turbo.json is mapped from that graph, and keep writes the workspace file declaring `nx()`. Lerna is the installed one, else the root manifest's range; with neither, the lerna.json is another tool's (lerna-lite reads it too, and runs no Nx). A root whose scripts never `lerna run` runs its tasks another way and publishes with Lerna (webdriverio: `run-s`, `pnpm -r`), so its scripts stay the source. Not where Lerna runs its own runner: `useNx: false`, or Lerna 5 without `useNx: true`; those map their scripts. Beside turbo.json, Turbo runs the tasks and Lerna only publishes: turbo.json is the source.
@@ -550,18 +550,19 @@ export default defineWorkspace({
 
 Off CI a run reads the remote and does not write it unless its policy names the remote. Give the write token only to the default branch's CI and a read-only one to laptops and pull request jobs: the server's token is the boundary (`docs/security.md` § Cache poisoning). The same holds for `nxCache()`.
 
-Every option falls back to the tool's own environment variable, so a self-hosted setup carries over unchanged. A token with no `apiUrl` means Vercel's hosted Remote Cache (`https://vercel.com/api`), exactly as it does for `turbo` — so `npx turbo login && npx turbo link`, then `turboCache()` with `TURBO_TOKEN` / `TURBO_TEAM` set, is the whole hosted setup. Below the environment, in Turbo's order: a Vercel build's `VERCEL_ARTIFACTS_TOKEN` and `VERCEL_ARTIFACTS_OWNER` (the team id, where `TURBO_TOKEN` with a team is not set), then the repo's `.turbo/config.json` (what `turbo link` writes: `apiUrl`, `teamId`, `teamSlug`, `token`), then the root `turbo.json`'s `remoteCache` (`apiUrl`, `teamId`, `teamSlug`), whose `enabled: false` declines unless the options name a cache. With no token the plugin **declines** and the run stays local.
+Every option falls back to the tool's own environment variable, so a self-hosted setup carries over unchanged. A token with no `apiUrl` means Vercel's hosted Remote Cache (`https://vercel.com/api`), exactly as it does for `turbo` — so `npx turbo login && npx turbo link`, then `turboCache()` with `TURBO_TOKEN` / `TURBO_TEAM` set, is the whole hosted setup. Below the environment, in Turbo's order: a Vercel build's `VERCEL_ARTIFACTS_TOKEN` and `VERCEL_ARTIFACTS_OWNER` (the team id, where `TURBO_TOKEN` with a team is not set), then the repo's `.turbo/config.json` (what `turbo link` writes: `apiUrl`, `teamId`, `teamSlug`, `token`), then the root `turbo.json`'s `remoteCache` (`apiUrl`, `teamId`, `teamSlug`), whose `enabled: false` declines unless the options name a cache. A team with no `apiUrl` also means Vercel's. With a URL or a team but no token, the token comes from the OS keychain ([Tokens](#tokens-and-the-os-keychain)); with none of the three the plugin **declines** and the run stays local.
 
 | Option            | Environment variable                                                                                                                     | Meaning                                                                                                                                                                                                                                                                       |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `apiUrl`          | `TURBO_API`                                                                                                                              | base URL of the cache server; default with a token: `https://vercel.com/api`; a `user:pass@` in it is refused                                                                                                                                                                 |
-| `token`           | `TURBO_TOKEN`                                                                                                                            | Bearer token on every request                                                                                                                                                                                                                                                 |
+| `token`           | `TURBO_TOKEN`                                                                                                                            | Bearer token on every request; then OIDC, `.turbo/config.json`, the OS keychain                                                                                                                                                                                               |
+| `oidc`            | `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` (GitHub sets them)                                                      | `true` or `{ tokenUrl, revokeUrl, audience, params }` (`TurboOidcOptions`): exchange the GitHub Actions job's OIDC token for a short-lived one ([OIDC](#oidc-on-github-actions))                                                                                              |
 | `teamId`          | `TURBO_TEAMID`                                                                                                                           | `teamId` query parameter; required with `signatureKey`                                                                                                                                                                                                                        |
 | `teamSlug`        | `TURBO_TEAM`                                                                                                                             | `slug` query parameter                                                                                                                                                                                                                                                        |
 | `signatureKey`    | `TURBO_REMOTE_CACHE_SIGNATURE_KEY`, read only under turbo.json's `remoteCache.signature: true` (or `TURBO_SIGNATURE`), as Turbo reads it | HMAC-SHA256 key (≥ 32 bytes, used raw); a download whose tag does not verify is a miss                                                                                                                                                                                        |
 | `timeoutMs`       | `TURBO_REMOTE_CACHE_TIMEOUT`, then `remoteCache.timeout` (seconds)                                                                       | HEAD/GET/POST deadline (default 30 s; 0 none)                                                                                                                                                                                                                                 |
 | `uploadTimeoutMs` | `TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT`, then `remoteCache.uploadTimeout` (seconds)                                                          | PUT deadline (default 60 s; 0 none)                                                                                                                                                                                                                                           |
-| `retries`         | —                                                                                                                                        | resends of a request answered 429 / 5xx (not 501) or never connected (default 1, Turbo's); 0 turns them off                                                                                                                                                                   |
+| `retries`         | —                                                                                                                                        | resends of a request answered 5xx (not 501) or never connected (default 1, Turbo's); a 429 waits out the limit; 0 turns both off                                                                                                                                              |
 | `preflight`       | `TURBO_PREFLIGHT` (1 or 0), then `remoteCache.preflight`                                                                                 | send Turbo's `OPTIONS` preflight before each artifact request and go where its `Location` points (relative to `apiUrl`); the token goes along only when the API's `Access-Control-Allow-Headers` admits `Authorization`; a redirected preflight is not followed (default off) |
 
 The signature is Turbo's current scheme (`artifact-signature:v2`: prefix, hash, team id and body, each length-prefixed, under HMAC-SHA256, base64 in `x-artifact-tag`). A signed body is written to a temp file before its tag can be checked, so one past core's artifact ceiling (2 GiB, at zstd's bound) is refused as it passes it, and is a miss.
@@ -581,26 +582,51 @@ export default defineWorkspace({
 })
 ```
 
-Every option falls back to the tool's own environment variable; with nothing configured the plugin **declines** and the run stays local.
+Every option falls back to the tool's own environment variable, and a missing token to the OS keychain ([Tokens](#tokens-and-the-os-keychain)); with no server the plugin **declines** and the run stays local.
 
-| Option        | Environment variable                       | Meaning                                                       |
-| ------------- | ------------------------------------------ | ------------------------------------------------------------- |
-| `server`      | `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`       | base URL of the cache server; a `user:pass@` in it is refused |
-| `accessToken` | `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN` | Bearer token; omit for a server that runs open                |
-| `timeoutMs`   | —                                          | per-request deadline (default 30 s; a positive number of ms)  |
-| `retries`     | —                                          | resends, as `turboCache()`'s (default 1)                      |
+| Option        | Environment variable                       | Meaning                                                                       |
+| ------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| `server`      | `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`       | base URL of the cache server; a `user:pass@` in it is refused                 |
+| `accessToken` | `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN` | Bearer token, else the OS keychain; `''` (option or variable): an open server |
+| `timeoutMs`   | —                                          | per-request deadline (default 30 s; a positive number of ms)                  |
+| `retries`     | —                                          | resends, as `turboCache()`'s (default 1)                                      |
 
 The Nx spec has no existence probe, so `has` (the `--dry` prediction; the prefetch pass calls `get`) is a `GET` whose body is cancelled before it answers. The wire carries no producing-task duration, so a remote hit reports none.
 
+## OIDC on GitHub Actions
+
+`turboCache({ oidc: true })` needs no `TURBO_TOKEN` secret on GitHub Actions: before the first task, when the run's policy uses the remote, it asks GitHub for the job's OIDC token (`ACTIONS_ID_TOKEN_REQUEST_URL`, with `audience` when given), exchanges it at the token endpoint (RFC 8693) for a short-lived cache token, and revokes that (RFC 7009) when the run ends. With Vercel's hosted cache the endpoints, Vercel's OAuth client id and `team_id_or_slug` (the team id, else slug; one is required) are the defaults, as Vercel's own action sends them; `params` adds fields such as `policy_id`. Any other server names its `tokenUrl` (and `revokeUrl`, or none); `params` carries its extras. `revokeUrl: false` skips the revoke.
+
+```yaml
+permissions:
+  id-token: write
+```
+
+- Order: the `token` option, `TURBO_TOKEN`, then OIDC, then `.turbo/config.json`, then the OS keychain.
+- A request is tried three times on a `429`, a `5xx` or no answer, 30 s each. A failed exchange is one warning and a local-only run; a failed revoke is a warning (the token expires on its own). No message quotes a token.
+- A job without `id-token: write` gets no OIDC variables: one warning, and the sources below OIDC answer. A pull request from a fork, and a Dependabot one, never gets an OIDC token.
+- `nxCache()` has no OIDC: Nx's cache spec names no exchange.
+
+## Tokens and the OS keychain
+
+With no token from an option, a variable or a config file, both plugins read the OS keychain through core's `ctx.secret` (`Bun.secrets`: macOS Keychain, libsecret, Windows Credential Manager), service `@vzn/vx-migrate`, entry named by the endpoint and team: `https://remote.cachely.dev/v8/artifacts#cachely` (`turboCache()`, team id else slug; no `#…` without a team) or `https://cache.example.com/v1/cache` (`nxCache()`). So separate caches never share a token.
+
+- Read once per run, only by a run that uses the remote: before its first task, when its policy reads or writes the remote. `--no-cache`, `--cache-policy=remote:`, `--dry`, `vx show` and `vx info` never touch the keychain. Off CI, remote writes are already off by default ([`cli.md` § Cache control](../vx/docs/cli.md#cache-control---cache-policy---no-cache---force)).
+- Missing, on a terminal (stdin and stderr TTYs, `CI` unset): asked once, input hidden — `Token for remote.cachely.dev (cachely), saved to the OS keychain: ` — and saved. Later runs read it without asking.
+- Missing anywhere else (CI, piped), or an empty answer (Ctrl-C stops the run): one warning naming the remote and the fixes (set `TURBO_TOKEN` / `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN`, run in a terminal, or `--cache-policy=remote:` to skip the remote), and the run goes on with the local cache.
+- A keychain token the server refuses (`401` / `403`) is deleted, with the warning, so the next run asks again. A token from an option or a variable is never deleted.
+- No keychain (headless Linux without libsecret) reads as empty; it never breaks a run.
+- The token never reaches a task: the task environment does not pass `TURBO_TOKEN`, `VERCEL_ARTIFACTS_TOKEN` or Nx's variable.
+
 ## Remote-cache behaviour (both)
 
 - A remote error degrades to a **miss** and a warning that names the request, the artifact and the server — `[vx] plugin '@vzn/vx-migrate': upload 32248a2a7c89e241 to https://cache.example.com/v8/artifacts failed: no answer within 60000 ms` — never the token. The run never fails because of the cache.
 - The same failure is said once per run: an unreachable server fails the probe, the download and the upload alike, and the run prints the first and, at its end, `[vx] plugin '@vzn/vx-migrate': 2 more requests failed the same way: Unable to connect. Is the computer able to access the url?` (core does the counting, for every cache plugin).
-- A request answered `429` or `5xx` (not `501`), or one that never connected (a refused port, an unresolved host), is sent again after 2 s — a `429` after its `Retry-After`, capped at 10 s — as Turbo's client does. A spent deadline is not: it has already cost its wait.
+- A request answered `5xx` (not `501`), or one that never connected (a refused port, an unresolved host), is sent again after 2 s, `retries` times. A `429` pauses every request to that remote for its `Retry-After` (capped at 10 s a wait, 2 s without one), and the request is sent again when the pause ends, for up to 20 s from its first `429`, as Turbo's client does. A spent deadline is not resent: it has already cost its wait.
 - Three outages in a row (no connection, no answer within the deadline, or a `5xx` once the resends are spent) open Turbo's outage breaker: no request is sent for 30 s, each lookup is a miss at once, then one request probes and its answer closes or reopens it. A hit is judged when its body ends, so a server that sends headers and then stalls the body counts the same way. A hung server costs three deadlines, not one per task.
 - A refused token (`401`/`403`) warns **once** and turns the layer off for the rest of the process (a `403` on an upload is a read-only token — Nx's spec, or turborepo-remote-cache's `READ_ONLY` and write-less JWTs: it turns off uploads alone, and reads go on) — including the requests already in flight when the refusal lands, which degrade in silence rather than repeating it (a six-project run printed five identical lines before 2026-09-20).
 - Policy (`--cache-policy=remote:r`, `VX_CACHE_POLICY`, `cache.policy`) is enforced by core, which layers each plugin's remote over the local cache — a read-only token pairs naturally with `remote:r`.
-- Each tool's own switches narrow that policy, never widen it, as they do for the tool: `TURBO_CACHE` (`--cache-policy`'s syntax, an omitted source off) and `TURBO_REMOTE_CACHE_READ_ONLY` for `turboCache()`, `NX_SKIP_REMOTE_CACHE` / `NX_DISABLE_REMOTE_CACHE` (`true`) for `nxCache()`. A CI that keeps untrusted pull requests off the shared cache that way keeps vx off it too.
+- Core's policy alone decides reads and writes: the plugins read none of Turbo's or Nx's own switches (`TURBO_CACHE`, `TURBO_REMOTE_CACHE_READ_ONLY`, `NX_SKIP_REMOTE_CACHE`, `NX_DISABLE_REMOTE_CACHE`). A CI that keeps untrusted pull requests off the shared cache sets `cache.policy` or `--cache-policy=local:rw,remote:r` for them.
 
 ## Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.640",
+  "version": "0.0.642",
   "license": "MIT",
   "description": "Adopt @vzn/vx from Turborepo, Nx or package.json scripts: run the repo unchanged, migrate it to vx.config.ts, and keep your Turbo or Nx remote cache",
   "keywords": [
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.640"
+    "@vzn/vx": "^0.0.642"
   },
   "repository": {
     "type": "git",

package/src/adopt.ts

@@ -175,6 +175,21 @@ export function listedPlugins(root: string): string[] {
   return [...plugins].sort()
 }
 
+/**
+ * The `@vzn/vx*` packages a workspace file imports, parsed, not matched (a
+ * formatter's quotes hid a match). Each is installed with core: a file an
+ * earlier init wrote imports @vzn/vx-lockfile that package.json need not
+ * list, and the lock could not find it (M, 2026-10-16).
+ */
+export function importedPackages(text: string): string[] {
+  const out = new Set<string>()
+  for (const i of new Bun.Transpiler({ loader: 'ts' }).scanImports(text)) {
+    const m = /^(@vzn\/vx(?:-[^/]+)?)(?:\/|$)/.exec(i.path)
+    if (m !== null) out.add(m[1]!)
+  }
+  return [...out].sort()
+}
+
 /** Install `packages` (at `version`, given one) with the repo's manager; its output only on failure. */
 export function install(
   root: string,

package/src/migrate-turbo.ts

@@ -24,6 +24,7 @@ import { DOTENV_GLOBS_HEAD, DOTENV_PROBE, DOTENV_PROBE_TOP } from './dotenv-prob
 import { adoptedToolNotes } from './workspace-notes.js'
 import { spelledNames } from './spelled-env.js'
 import { sealsConfig } from './sealed-tsconfig.js'
+import { onceReader, tscBuildInfo } from './tsc-buildinfo.js'
 
 /** What a task's `npm_package_*` read: the manifest, so a bump reaches them. */
 const MANIFEST_IMPORT = "import pkg from './package.json' with { type: 'json' }"
@@ -46,6 +47,7 @@ export async function migrateTurbo(
   format: MigrationFormat = 'ts',
 ): Promise<MigrationPlan> {
   const tracked = await trackedFiles(root)
+  const tsc = onceReader()
   const mapping = await mapTurboWorkspace(root, await withRootProject(root, metas), {
     splice: (kind) => [{ raw: `...${PRESET_NAMES[kind]}` }],
     persistentTodo: PERSISTENT_TODO,
@@ -55,6 +57,7 @@ export async function migrateTurbo(
     ownConfig: () => `vx.config.${format}`,
     sourceNames: (dirs) => spelledNames(root, dirs, tracked),
     ignored: (rels) => gitIgnored(root, rels),
+    buildInfo: (rel, command) => tscBuildInfo(tsc.read, path.join(root, rel), command),
   })
   // A reader whose `!` hides a committed file under another task's output
   // runs uncached, as under turbo().

package/src/migrate.ts

@@ -45,6 +45,7 @@ import { exportGraph, nxBin } from './nx/export-graph.js'
 import { readNxJson } from './nx/nx-map.js'
 import {
   type AdoptionMode,
+  importedPackages,
   install,
   installArgv,
   listedPackages,
@@ -358,11 +359,8 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
   const finalWorkspace = workspaceText ?? readFileSync(path.join(root, existingWorkspace!), 'utf8')
   // Imports parsed, not matched: a formatter's double quotes hid it, and
   // the file still imported the package removed (owner, 2026-10-16).
-  const needsSelf =
-    runsBins ||
-    new Bun.Transpiler({ loader: 'ts' })
-      .scanImports(finalWorkspace)
-      .some((i) => i.path === '@vzn/vx-migrate')
+  const imported = importedPackages(finalWorkspace)
+  const needsSelf = runsBins || imported.includes('@vzn/vx-migrate')
   const cacheNote =
     runner === 'vite-task'
       ? undefined
@@ -381,6 +379,7 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
                 '@vzn/vx',
                 ...(needsSelf ? ['@vzn/vx-migrate'] : []),
                 ...plugins.map((p) => p.pkg),
+                ...imported,
               ]),
             ],
             parsed,
@@ -544,7 +543,14 @@ async function keep(
   const declares = before === undefined || extended !== null
   const steps = await prepareRepo(
     root,
-    [...new Set(['@vzn/vx', '@vzn/vx-migrate', ...(declares ? all.map((p) => p.pkg) : [])])],
+    [
+      ...new Set([
+        '@vzn/vx',
+        '@vzn/vx-migrate',
+        ...(declares ? all.map((p) => p.pkg) : []),
+        ...importedPackages(text),
+      ]),
+    ],
     args,
   )
   if (args.json)
@@ -633,8 +639,8 @@ function lockRow(lock: { code: number; said: string }): ui.FieldRow {
   ]
 }
 
-/** `.vx/.gitignore`'s text, as core writes it: the machine-local cache stays out of git. */
-const DOT_VX_GITIGNORE = '/cache\n'
+/** `.vx/.gitignore`'s text, as core writes it: the machine-local cache and restore staging stay out of git. */
+const DOT_VX_GITIGNORE = '/cache\n/tmp\n'
 
 // npx and bunx name the package: their bare `vx` is a stranger's npm package.
 const EXEC: Record<PackageManager, string> = {
@@ -668,18 +674,23 @@ export function adoptionNext(
   return `${installArgv(root, pm, pinned).join(' ')} && ${vx} lock && ${run}`
 }
 
-/** `build` when the runner's config names it, else the first task it names. */
+/**
+ * `build` when the runner's config names it, else the first task name it
+ * names. A key with `:` is an Nx executor (`@angular/build:application`)
+ * and one with `#` a Turbo package task: neither is a task to run `--all`.
+ */
 function firstTask(file: string, runner: 'turbo' | 'nx'): string {
-  let text: string
+  let json: Record<string, unknown> | null
   try {
-    text = readFileSync(file, 'utf8')
+    json = Bun.JSONC.parse(readFileSync(file, 'utf8')) as Record<string, unknown> | null
   } catch {
     return 'build'
   }
-  if (/"build"\s*:/.test(text)) return 'build'
-  const field = runner === 'turbo' ? '(?:tasks|pipeline)' : 'targetDefaults'
-  const first = new RegExp(`"${field}"\\s*:\\s*\\{\\s*"([^"]+)"`).exec(text)?.[1]
-  return first ?? 'build'
+  const field =
+    runner === 'turbo' ? (json?.['tasks'] ?? json?.['pipeline']) : json?.['targetDefaults']
+  const names = Object.keys(typeof field === 'object' && field !== null ? field : {})
+  if (names.includes('build')) return 'build'
+  return names.find((n) => !n.includes(':') && !n.includes('#')) ?? 'build'
 }
 
 /**

package/src/nx/nx-map.ts

@@ -563,6 +563,11 @@ export async function mapNxWorkspace(
         followNxGraph(t.task, nodeName, meta.name, nxEdges, metaByNode, emittedIds, reached)
       }
       dropUnheldDeps(t, emitted, emittedIds)
+      const reader = dependentReaders.get(t)
+      if (reader !== undefined && !reachesProducer(t, meta.name, emittedIds, reached)) {
+        delete t.task!['cache']
+        t.todos.push(orphanReaderTodo(reader.globs, reader.dependsOn))
+      }
     }
     const tags = nxTags(nodeName === undefined ? undefined : nodeMap[nodeName])
     projects.push({
@@ -895,9 +900,7 @@ function buildTask(
   const orphanReader =
     inputs.dependentOutputs.length > 0 && !deps.some((d) => !d.includes('#nx-input:'))
   if (orphanReader && cacheWanted && !persistent) {
-    todos.push(
-      `reads ${inputs.dependentOutputs.map((g) => `\`${g}\``).join(', ')} from the outputs of the tasks it depends on, and no task it depends on is migrated (dependsOn ${JSON.stringify(target.dependsOn ?? [])}) — uncached here, so it never replays output generated from an older input; migrate the producer and depend on it to cache this task`,
-    )
+    todos.push(orphanReaderTodo(inputs.dependentOutputs, target.dependsOn))
   }
   const cacheEnabled = !persistent && cacheWanted && wild === undefined && !orphanReader
   if (persistent && cacheWanted) {
@@ -1007,7 +1010,41 @@ function buildTask(
     task.cache = { outputs }
   }
 
-  return { name: variant.name, todos, task }
+  const generated: GeneratedTask = { name: variant.name, todos, task }
+  if (cacheEnabled && inputs.dependentOutputs.length > 0)
+    dependentReaders.set(generated, { globs: inputs.dependentOutputs, dependsOn: target.dependsOn })
+  return generated
+}
+
+/**
+ * The cached readers of `dependentTasksOutputFiles`, judged again once the
+ * graph has its final edges: a `^build` kept because another project builds
+ * reached no producer of this one (nx-examples' codegen, its .NET
+ * ProductsApi no node once @nx/dotnet failed to load), and the key saw
+ * nothing the task reads (Growth, nx-codegen-dropped-producer.sh).
+ */
+const dependentReaders = new WeakMap<GeneratedTask, { globs: string[]; dependsOn: unknown }>()
+
+function orphanReaderTodo(globs: readonly string[], dependsOn: unknown): string {
+  return `reads ${globs.map((g) => `\`${g}\``).join(', ')} from the outputs of the tasks it depends on, and no task it depends on is migrated (dependsOn ${JSON.stringify(dependsOn ?? [])}) — uncached here, so it never replays output generated from an older input; migrate the producer and depend on it to cache this task`
+}
+
+/** Whether one of `t`'s final edges reaches a task vx runs. */
+function reachesProducer(
+  t: GeneratedTask,
+  project: string,
+  emittedIds: ReadonlySet<string>,
+  reached: (name: string) => ReadonlySet<string>,
+): boolean {
+  const deps = t.task?.['dependsOn']
+  if (!Array.isArray(deps)) return false
+  return deps.some((d) => {
+    if (typeof d !== 'string' || d.includes('*')) return true
+    if (d.includes('#nx-input:')) return false
+    if (d.startsWith('^'))
+      return [...reached(project)].some((p) => emittedIds.has(`${p}#${d.slice(1)}`))
+    return d.includes('#') || emittedIds.has(`${project}#${d}`)
+  })
 }
 
 /**

package/src/nx-cache/index.ts

@@ -14,19 +14,29 @@
 import {
   definePlugin,
   type RemoteCacheLayer,
+  type RemoteOpenContext,
   type VxPlugin,
   refuseUnknownOptions,
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadline } from '../remote-deadline.js'
 import { OutageBreaker } from '../remote-breaker.js'
-import { withRetry } from '../remote-retry.js'
-import { headerValueFault } from '../remote-token.js'
+import { Cooldown, withRetry } from '../remote-retry.js'
+import {
+  headerValueFault,
+  type KeychainRemote,
+  keychainToken,
+  remoteLabel,
+} from '../remote-token.js'
 
 export interface NxCacheOptions {
   /** Base URL of the cache server, or `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. */
   server?: string
-  /** Bearer token, or `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN`. Optional: a server may run open. */
+  /**
+   * Bearer token, or `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN`, then the OS
+   * keychain. `''` (option or variable) is a server that runs open: no
+   * token, nothing asked.
+   */
   accessToken?: string
   /** Per-request deadline (default 30 s). */
   timeoutMs?: number
@@ -36,6 +46,7 @@ export interface NxCacheOptions {
 
 export interface NxCacheConfig {
   server: string
+  /** Undefined: the layer's `open` asks the OS keychain; `''`: an open server. */
   accessToken?: string
   timeoutMs: number
   retries: number
@@ -46,10 +57,6 @@ export function resolveNxCacheConfig(
   options: NxCacheOptions,
   env: Record<string, string | undefined> = Bun.env,
 ): NxCacheConfig | undefined {
-  // Nx's own off switches (`skipRemoteCache`): a CI that sets one for an
-  // untrusted pull request kept Nx off the shared cache and not vx.
-  if (env['NX_SKIP_REMOTE_CACHE'] === 'true' || env['NX_DISABLE_REMOTE_CACHE'] === 'true')
-    return undefined
   const server = (options.server ?? env['NX_SELF_HOSTED_REMOTE_CACHE_SERVER'])?.replace(/\/+$/, '')
   if (!server) return undefined
   // The URL is printed in every refusal line, so a `user:pass@` in it would
@@ -62,7 +69,7 @@ export function resolveNxCacheConfig(
       )
   }
   const accessToken = options.accessToken ?? env['NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN']
-  const fault = accessToken ? headerValueFault(accessToken) : null
+  const fault = accessToken === undefined ? null : headerValueFault(accessToken)
   if (fault !== null)
     throw new Error(
       `vx/nx-cache: the access token holds ${fault}, which no HTTP header can carry — check the secret (it is not printed)`,
@@ -79,7 +86,7 @@ export function resolveNxCacheConfig(
     )
   return {
     server,
-    ...(accessToken ? { accessToken } : {}),
+    ...(accessToken !== undefined ? { accessToken } : {}),
     timeoutMs: options.timeoutMs ?? 30_000,
     retries,
   }
@@ -110,12 +117,31 @@ export class NxRemoteCache implements RemoteCacheLayer {
    */
   private writesRefused = false
   readonly endpoint: string
+  /** The remote's rate limit, which every request of this client waits out. */
+  private readonly cooldown = new Cooldown()
+  /** Undefined until `open` reads the keychain; a layer never opened (a plan) asks the server nothing. */
+  private token: string | undefined
+  /** Set by `open` when the token came from the keychain: a refusal deletes it. */
+  private forget: (() => Promise<void>) | undefined
+  private readonly keychainRemote: KeychainRemote
   constructor(
     private readonly config: NxCacheConfig,
     private readonly fetchImpl: typeof fetch = fetch,
     private readonly wait: (ms: number) => Promise<void> = Bun.sleep,
   ) {
     this.endpoint = `${config.server}/v1/cache`
+    this.token = config.accessToken
+    this.keychainRemote = {
+      key: this.endpoint,
+      label: remoteLabel(config.server, undefined),
+      env: 'NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN',
+    }
+  }
+
+  async open(ctx: RemoteOpenContext): Promise<void> {
+    if (this.token !== undefined) return
+    this.token = await keychainToken(ctx, this.keychainRemote)
+    this.forget = () => ctx.forgetSecret({ key: this.keychainRemote.key })
   }
 
   /**
@@ -129,8 +155,9 @@ export class NxRemoteCache implements RemoteCacheLayer {
     hash: string,
     body?: Blob,
   ): Promise<Response | undefined> {
+    if (this.token === undefined) return undefined
     const headers: Record<string, string> = {}
-    if (this.config.accessToken) headers['Authorization'] = `Bearer ${this.config.accessToken}`
+    if (this.token !== '') headers['Authorization'] = `Bearer ${this.token}`
     if (body !== undefined) {
       headers['Content-Type'] = 'application/octet-stream'
       headers['Content-Length'] = String(body.size)
@@ -152,6 +179,7 @@ export class NxRemoteCache implements RemoteCacheLayer {
             }),
           this.config.retries,
           this.wait,
+          this.cooldown,
         ),
       method === 'GET',
     )
@@ -167,8 +195,15 @@ export class NxRemoteCache implements RemoteCacheLayer {
       const first = !this.disabled
       this.disabled = true
       if (!first) return undefined
+      const why =
+        res.status === 401
+          ? 'missing or invalid token'
+          : 'access forbidden (the token may not read)'
+      if (this.forget === undefined)
+        throw new Error(`HTTP ${res.status}: ${why}; remote cache off for this run`)
+      await this.forget()
       throw new Error(
-        `HTTP ${res.status}: ${res.status === 401 ? 'missing or invalid token' : 'access forbidden (the token may not read)'}; remote cache off for this run`,
+        `HTTP ${res.status}: ${why}; removed it from the OS keychain, so the next run asks again; remote cache off for this run`,
       )
     }
     return res

package/src/remote-cache.ts

@@ -109,7 +109,7 @@ export function remoteCacheNote(
   const cache = REMOTE_CACHE[runner]
   if (signal !== undefined) {
     return declared
-      ? `${cache}(): ${signal}, so vx shares that remote cache (inert where the variable is unset).`
+      ? `${cache}(): ${signal}, so vx shares that remote cache (token: the variable, else the OS keychain).`
       : `${signal}: add ${cache}() from @vzn/vx-migrate to its plugins and vx shares that remote cache.`
   }
   return runner === 'nx' && usesNxCloud(root)

package/src/remote-retry.ts

@@ -1,40 +1,80 @@
+/**
+ * When a remote's rate limit ends, shared by every request to that remote:
+ * Turbo's `RateLimit` (`turborepo-api-client/src/retry.rs`; tests
+ * `waits_for_known_cooldown_before_initial_send`,
+ * `scopes_artifact_cooldowns_to_client_team_and_token`). A request that
+ * starts inside it waits it out before its first send instead of spending
+ * a try on a 429. One per wire instance: a client, its server and token.
+ */
+export class Cooldown {
+  until = 0
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /** Ms left of the limit, 0 when there is none. */
+  left(): number {
+    return Math.max(0, this.until - this.now())
+  }
+
+  extend(ms: number): void {
+    this.until = Math.max(this.until, this.now() + ms)
+  }
+}
+
 /**
  * One request with Turbo's retry rule (`turborepo-api-client/src/retry.rs`):
- * a 429 or a 5xx other than 501, or a request that never connected, is
- * sent again after a backoff — 2 s, or a 429's `Retry-After` capped at
- * 10 s. Without it one 503 from a gateway read as a miss and the task ran
- * again. A spent deadline is not retried, unlike Turbo's reads: it has
- * already cost its wait, and a hung server would cost it twice. Every
- * request both wires make is idempotent (content-addressed, and Nx's
- * second write is a 409 the caller takes as done), so a resend applies
- * nothing twice. Shared by `turboCache()` and `nxCache()`.
+ * a 5xx other than 501, or a request that never connected, is sent again
+ * after 2 s, `retries` times. A 429 opens the remote's `cooldown` for its
+ * `Retry-After` (capped at 10 s a wait, 2 s without one), and the request
+ * is resent once it ends, as often as fits in 20 s from its first 429: a
+ * limit longer than one capped wait lost every hit before (Growth's
+ * parity run, 2026-10-16). A spent deadline is not retried, unlike
+ * Turbo's reads: it has already cost its wait, and a hung server would
+ * cost it twice. Every request both wires make is idempotent
+ * (content-addressed, and Nx's second write is a 409 the caller takes as
+ * done), so a resend applies nothing twice. Shared by `turboCache()` and
+ * `nxCache()`.
  */
 export async function withRetry(
   send: () => Promise<Response>,
   retries: number,
   wait: (ms: number) => Promise<void> = Bun.sleep,
+  cooldown: Cooldown = new Cooldown(),
+  now: () => number = Date.now,
 ): Promise<Response> {
-  for (let attempt = 0; ; attempt++) {
+  let firstLimit: number | undefined
+  for (let attempt = 0; ;) {
+    const held = cooldown.left()
+    if (held > 0) await wait(held)
     let res: Response
     try {
       res = await send()
     } catch (err) {
       if (attempt >= retries || !neverConnected(err)) throw err
+      attempt++
       await wait(BACKOFF_MS)
       continue
     }
+    if (res.status === 429) {
+      firstLimit ??= now()
+      const delay = retryAfterMs(res) ?? BACKOFF_MS
+      if (retries === 0 || now() + delay - firstLimit > RATE_LIMIT_BUDGET_MS) return res
+      cooldown.extend(delay)
+      await res.body?.cancel()
+      continue
+    }
     if (attempt >= retries || !retryable(res.status)) return res
-    const delay = res.status === 429 ? (retryAfterMs(res) ?? BACKOFF_MS) : BACKOFF_MS
+    attempt++
     await res.body?.cancel()
-    await wait(delay)
+    await wait(BACKOFF_MS)
   }
 }
 
 const BACKOFF_MS = 2_000
 const MAX_RETRY_AFTER_MS = 10_000
+const RATE_LIMIT_BUDGET_MS = 20_000
 
 function retryable(status: number): boolean {
-  return status === 429 || (status >= 500 && status !== 501)
+  return status >= 500 && status !== 501
 }
 
 /** A refused port or an unresolved host, as Bun's `fetch` codes them (measured on 1.4.2). */