@vzn/vx-migrate 0.0.641 → 0.0.643

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.
 
@@ -76,7 +76,7 @@ Rules:
 - A task's `tags` (Turbo main, after 2.11.5) map to nothing: Turbo keeps them out of the hash and the run.
 - `envMode: "loose"` (top-level or in `global`, or `TURBO_ENV_MODE=loose`, which wins) is a note: Turbo hands every task the whole environment, vx only the declared names.
 - The workspace keys vx has a home for, top level or in `global`, fill what `.vx/workspace.ts` leaves unset: `run.concurrency` (`"10"`, `"50%"` of the cores) → `run.concurrency`; `cacheMaxSize` / `cacheMaxAge` (`"0"` is off; weeks become days, a bare number days; a size in Turbo's grammar, `7.5GB` or bare bytes, restated whole: `7680MB`) → `cache.retention.maxSize` / `.olderThan`. `TURBO_CONCURRENCY`, `TURBO_CACHE_MAX_SIZE` and `TURBO_CACHE_MAX_AGE` win over turbo.json, as under Turbo; a set one decides, its `0` included.
-- `TURBO_SCM_BASE`, the base `turbo run --affected` compares with, is `run.affectedBase` when `.vx/workspace.ts` sets none: a bare `vx run build --affected` compares with the same ref. With it unset on GitHub Actions (`GITHUB_ACTIONS`), Turbo's own base applies: a pull request's `GITHUB_BASE_REF`, else the push event's `before` from `GITHUB_EVENT_PATH`.
+- `TURBO_SCM_BASE`, the base `turbo run --affected` compares with, is the run's base commit (`setBranch({ base })`): a bare `vx run build --affected` compares with the same ref. With it unset on GitHub Actions (`GITHUB_ACTIONS`), Turbo's own base applies: a pull request's `GITHUB_BASE_REF`, else the push event's `before` from `GITHUB_EVENT_PATH`.
 - Turbo hashes each package's `microfrontends.json` (or `.jsonc`) into every task, or the one file `VC_MICROFRONTENDS_CONFIG_FILE_NAME` names; so does `turbo()`.
 - Turbo 2.11's `global` block (`futureFlags.globalConfiguration`) is read as the `globalDependencies`, `globalEnv` and `globalPassThroughEnv` it replaces.
 - An unknown Turbo key is a todo naming it; `extends` is accepted and ignored (the overlay order above is what it means).
@@ -169,7 +169,7 @@ Two cached tasks on one workspace path cannot both keep their cache, and the fir
 
 ### nx.json `defaultBase`
 
-`NX_BASE`, else `defaultBase` (Nx 19's `affected.defaultBase` before it), is `run.affectedBase` when `.vx/workspace.ts` sets none: a bare `vx run test --affected` compares with the ref `nx affected` does.
+`NX_BASE` is the run's base commit (`setBranch({ base })`), and `defaultBase` (Nx 19's `affected.defaultBase` before it, an `origin/` prefix dropped) is `baseBranch` when `.vx/workspace.ts` sets none: a bare `vx run test --affected` compares with the ref `nx affected` does.
 
 ### nx.json `maxCacheSize`
 
@@ -259,7 +259,7 @@ Reads the root pipeline (`tasks` in Turbo 2, `pipeline` in Turbo 1), per-package
 
 ### Nx
 
-Reads the **resolved** project graph only (`.nx/workspace-data/project-graph.json` when exported, else the one the workspace's own `nx graph` exports into a temp file, as `nx()` does; with no `node_modules/.bin/nx`, as in a fresh clone, it stops and names the repo manager's install), through the same mapper `nx()` runs live, executors aside (below). Targets Nx plugins infer at runtime are frozen as the snapshot saw them. `nx:run-commands` is the one shell line `nx()` runs (see [`nx:run-commands`](#nxrun-commands) above: where, parallel or in order, forwarded arguments, `env`, `readyWhen`) — storybook's `compile` is `cd ../../.. && node ./scripts/build/build-package.ts --cwd code/lib/cli`; a plain `command` is that shorthand; `nx:run-script` is the package's script body with its `pre<name>` / `post<name>` hooks folded in (or `yarn run <name>` when the body calls yarn's `run` builtin; an empty script is the placeholder with a todo), `nx:noop` is a group task; Nx 15–16's `@nrwl/workspace:run-commands` and `run-script` (and their `@nx/workspace:` names) are the `nx:` executors they re-exported; **an executor target is its `nx-exec` line**, as `nx()` runs it: the migrator translates no executor, so Nx and `@vzn/vx-migrate` stay installed until each such line is rewritten as the command it runs (a server executor Nx knows, `@nx/js:node` or a dev server, is still a persistent task). The report also says what `.vx/workspace.ts` still holds, as the Turbo migration does: the `nx()` a keep adoption declared, which keeps reading nx.json, and a lockfile with no `@vzn/vx-lockfile` plugin, where Nx keyed each project on the npm packages it depends on. A written command that still runs Nx itself (a run-commands `nx run b:build`, `npx nx test b`, a script's `nx exec -- tsc`) carries a TODO: it works only while Nx is installed. An Nx project no workspace glob lists (an integrated repo's `project.json` library) gets a `package.json` (`name`, `private`) where it has none, and a note names the directories to add to `workspaces` (or `pnpm-workspace.yaml`), so the package manager installs it and a lockfile plugin names it; the migrator never edits the root manifest. A repo with no `package.json` at all (Nx's `nx init` outside JS: Nx pinned in `.nx/installation`, projects as `project.json`) is migrated too, natively only: the root is the directory holding `nx.json`, the graph is exported by `.nx/installation`'s `nx`, each config writes the project's Nx `name`, every edge is the explicit `project#target` Nx's graph draws (a `^` edge needs a lockfile plugin, which has no lockfile to read), and `.vx/workspace.ts` declares no plugin, so nothing is installed and core runs the configs alone; `--keep` refuses, as `nx()` would have no `package.json` to install into, and an executor target's `nx-exec` line is a note to rewrite as a command. A target with `configurations` writes one task per configuration (`build`, `build:ci`). A project's Nx `tags` are written as its `tags`. Named inputs expand from `nx.json` when readable. An output path is kept as written, a `!` one too (`{projectRoot}/dist` → `dist`, `{projectRoot}/bin/tool` → `bin/tool`; one naming an unset `{options.x}` is dropped, as Nx drops it; a dotted `{options.outputPath.base}` walks the options, as Nx does; an extglob is put in vx's grammar: Next's inferred `.next/!(cache)/**/*` is `.next/*/**/*` with `!.next/cache/**/*`, `@(js|map)` is `{js,map}`, and a form with no vx spelling is dropped with a TODO): vx reads a bare path as the file or the whole tree under it, so a directory and an extensionless binary both save and restore. nx.json's `parallel`, `defaultBase` and `maxCacheSize`, which `nx()` applies live, are each a field of the `.vx/workspace.ts` it writes (`run.concurrency`, `run.affectedBase`, `cache.retention.maxSize`), read from nx.json alone, never the environment; beside a workspace file already there, or for a size vx cannot read (`1.5 GB`), each is a note naming the field to add. vx derives package edges from `package.json`; an Nx graph edge with no manifest path (`implicitDependencies`, a tsconfig path) becomes, for each `^target` of the dependant, an explicit `pkg#target` edge to what Nx's own walk reaches — each dependency that has the target, and through one that lacks it, its dependencies — so the order and the key are Nx's. The reverse too: where a project's manifest names a workspace package its Nx graph does not reach (an `implicitDependencies: ["!a"]` that breaks a manifest cycle), its `^target` becomes the explicit edges Nx draws, since vx's `^` would follow the manifest and bring the cycle back.
+Reads the **resolved** project graph only (`.nx/workspace-data/project-graph.json` when exported, else the one the workspace's own `nx graph` exports into a temp file, as `nx()` does; with no `node_modules/.bin/nx`, as in a fresh clone, it stops and names the repo manager's install), through the same mapper `nx()` runs live, executors aside (below). Targets Nx plugins infer at runtime are frozen as the snapshot saw them. `nx:run-commands` is the one shell line `nx()` runs (see [`nx:run-commands`](#nxrun-commands) above: where, parallel or in order, forwarded arguments, `env`, `readyWhen`) — storybook's `compile` is `cd ../../.. && node ./scripts/build/build-package.ts --cwd code/lib/cli`; a plain `command` is that shorthand; `nx:run-script` is the package's script body with its `pre<name>` / `post<name>` hooks folded in (or `yarn run <name>` when the body calls yarn's `run` builtin; an empty script is the placeholder with a todo), `nx:noop` is a group task; Nx 15–16's `@nrwl/workspace:run-commands` and `run-script` (and their `@nx/workspace:` names) are the `nx:` executors they re-exported; **an executor target is its `nx-exec` line**, as `nx()` runs it: the migrator translates no executor, so Nx and `@vzn/vx-migrate` stay installed until each such line is rewritten as the command it runs (a server executor Nx knows, `@nx/js:node` or a dev server, is still a persistent task). The report also says what `.vx/workspace.ts` still holds, as the Turbo migration does: the `nx()` a keep adoption declared, which keeps reading nx.json, and a lockfile with no `@vzn/vx-lockfile` plugin, where Nx keyed each project on the npm packages it depends on. A written command that still runs Nx itself (a run-commands `nx run b:build`, `npx nx test b`, a script's `nx exec -- tsc`) carries a TODO: it works only while Nx is installed. An Nx project no workspace glob lists (an integrated repo's `project.json` library) gets a `package.json` (`name`, `private`) where it has none, and a note names the directories to add to `workspaces` (or `pnpm-workspace.yaml`), so the package manager installs it and a lockfile plugin names it; the migrator never edits the root manifest. A repo with no `package.json` at all (Nx's `nx init` outside JS: Nx pinned in `.nx/installation`, projects as `project.json`) is migrated too, natively only: the root is the directory holding `nx.json`, the graph is exported by `.nx/installation`'s `nx`, each config writes the project's Nx `name`, every edge is the explicit `project#target` Nx's graph draws (a `^` edge needs a lockfile plugin, which has no lockfile to read), and `.vx/workspace.ts` declares no plugin, so nothing is installed and core runs the configs alone; `--keep` refuses, as `nx()` would have no `package.json` to install into, and an executor target's `nx-exec` line is a note to rewrite as a command. A target with `configurations` writes one task per configuration (`build`, `build:ci`). A project's Nx `tags` are written as its `tags`. Named inputs expand from `nx.json` when readable. An output path is kept as written, a `!` one too (`{projectRoot}/dist` → `dist`, `{projectRoot}/bin/tool` → `bin/tool`; one naming an unset `{options.x}` is dropped, as Nx drops it; a dotted `{options.outputPath.base}` walks the options, as Nx does; an extglob is put in vx's grammar: Next's inferred `.next/!(cache)/**/*` is `.next/*/**/*` with `!.next/cache/**/*`, `@(js|map)` is `{js,map}`, and a form with no vx spelling is dropped with a TODO): vx reads a bare path as the file or the whole tree under it, so a directory and an extensionless binary both save and restore. nx.json's `parallel`, `defaultBase` and `maxCacheSize`, which `nx()` applies live, are each a field of the `.vx/workspace.ts` it writes (`run.concurrency`, `baseBranch`, `cache.retention.maxSize`), read from nx.json alone, never the environment; beside a workspace file already there, or for a size vx cannot read (`1.5 GB`), each is a note naming the field to add. vx derives package edges from `package.json`; an Nx graph edge with no manifest path (`implicitDependencies`, a tsconfig path) becomes, for each `^target` of the dependant, an explicit `pkg#target` edge to what Nx's own walk reaches — each dependency that has the target, and through one that lacks it, its dependencies — so the order and the key are Nx's. The reverse too: where a project's manifest names a workspace package its Nx graph does not reach (an `implicitDependencies: ["!a"]` that breaks a manifest cycle), its `^target` becomes the explicit edges Nx draws, since vx's `^` would follow the manifest and bring the cycle back.
 
 ### Vite Task
 
@@ -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,22 +582,47 @@ 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.641",
+  "version": "0.0.643",
   "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.641"
+    "@vzn/vx": "^0.0.643"
   },
   "repository": {
     "type": "git",

package/src/migrate-nx.ts

@@ -164,8 +164,8 @@ async function unlistedProjects(
 
 /** A `.vx/workspace.ts` field nx.json's run settings call for. */
 export interface NxWorkspaceField {
-  /** The setting's path: its group, then its field. */
-  readonly field: 'run.concurrency' | 'run.affectedBase' | 'cache.retention'
+  /** The setting's path: its group, then its field, or a top-level key. */
+  readonly field: 'run.concurrency' | 'baseBranch' | 'cache.retention'
   /** The value as TypeScript source; undefined when vx cannot read it. */
   readonly source: string | undefined
   /** What to tell a user whose workspace file this run does not write. */
@@ -199,12 +199,14 @@ export function nxWorkspaceFields(json: Record<string, unknown> | undefined): Nx
       note: `nx.json \`parallel: ${parallel}\`: add \`run: { concurrency: ${parallel} }\` to .vx/workspace.ts`,
     })
   const base = nx?.defaultBase ?? nx?.affected?.defaultBase
-  if (typeof base === 'string' && base.trim() !== '')
+  if (typeof base === 'string' && base.trim() !== '') {
+    const branch = base.trim().replace(/^origin\//, '')
     out.push({
-      field: 'run.affectedBase',
-      source: quoted(base.trim()),
-      note: `nx.json \`defaultBase\` ${JSON.stringify(base.trim())}: add \`run: { affectedBase: ${JSON.stringify(base.trim())} }\` to .vx/workspace.ts`,
+      field: 'baseBranch',
+      source: quoted(branch),
+      note: `nx.json \`defaultBase\` ${JSON.stringify(base.trim())}: add \`baseBranch: ${JSON.stringify(branch)}\` to .vx/workspace.ts`,
     })
+  }
   const size = nxSizeText(nx?.maxCacheSize)
   if (size !== undefined)
     out.push({

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

@@ -674,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/index.ts

@@ -148,9 +148,11 @@ export function nx(options: NxPluginOptions = {}): VxPlugin {
     {
       async config(workspace, ctx) {
         const root = options.root ?? ctx.workspaceRoot
-        if (workspace.run?.affectedBase === undefined) {
-          const base = await nxBase(root)
-          if (base !== undefined) workspace.run = { ...workspace.run, affectedBase: base }
+        const nxBaseCommit = Bun.env['NX_BASE']?.trim()
+        if (nxBaseCommit) ctx.setBranch({ base: nxBaseCommit })
+        if (workspace.baseBranch === undefined) {
+          const branch = await nxDefaultBase(root)
+          if (branch !== undefined) workspace.baseBranch = branch
         }
         if (workspace.run?.concurrency === undefined) {
           const parallel = await nxParallel(root)
@@ -278,19 +280,18 @@ async function nxParallel(root: string): Promise<number | undefined> {
 }
 
 /**
- * What `nx affected` compares with when no `--base` is given: `NX_BASE`,
- * then nx.json's `defaultBase` (Nx 19's `affected.defaultBase` before it).
- * Read by nothing, a git-flow repo's `develop` was lost and a bare
- * `vx run … --affected` diffed against origin/HEAD.
+ * nx.json's `defaultBase` (Nx 19's `affected.defaultBase` before it), the
+ * branch `nx affected` compares with. Read by nothing, a git-flow repo's
+ * `develop` was lost and a bare `vx run … --affected` diffed against
+ * origin/HEAD.
  */
-async function nxBase(root: string): Promise<string | undefined> {
-  const env = Bun.env['NX_BASE']?.trim()
-  if (env) return env
+async function nxDefaultBase(root: string): Promise<string | undefined> {
   const json = (await readNxJson(root).catch(() => null))?.json as
     | { defaultBase?: unknown; affected?: { defaultBase?: unknown } }
     | undefined
   const b = json?.defaultBase ?? json?.affected?.defaultBase
-  return typeof b === 'string' && b.trim() !== '' ? b.trim() : undefined
+  // `baseBranch` is the branch; vx compares with it on `origin`.
+  return typeof b === 'string' && b.trim() !== '' ? b.trim().replace(/^origin\//, '') : undefined
 }
 
 /**

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
@@ -58,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)`,
@@ -75,7 +86,7 @@ export function resolveNxCacheConfig(
     )
   return {
     server,
-    ...(accessToken ? { accessToken } : {}),
+    ...(accessToken !== undefined ? { accessToken } : {}),
     timeoutMs: options.timeoutMs ?? 30_000,
     retries,
   }
@@ -106,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 })
   }
 
   /**
@@ -125,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)
@@ -148,6 +179,7 @@ export class NxRemoteCache implements RemoteCacheLayer {
             }),
           this.config.retries,
           this.wait,
+          this.cooldown,
         ),
       method === 'GET',
     )
@@ -163,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). */