@vzn/vx-migrate 0.0.641 → 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.
 
@@ -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.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.641"
+    "@vzn/vx": "^0.0.642"
   },
   "repository": {
     "type": "git",

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/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). */

package/src/remote-token.ts

@@ -1,3 +1,5 @@
+import { isSecretUnavailable, type RemoteOpenContext } from '@vzn/vx'
+
 /**
  * Why a string cannot be an HTTP header value, or null when it can. Bun's
  * `fetch` refuses a value holding a line break or NUL, or a character past
@@ -16,3 +18,49 @@ export function headerValueFault(value: string): string | null {
   }
   return past ? 'a character past Latin-1' : null
 }
+
+/** One remote's keychain entry: `key` names it, `label` and `env` are what a person reads. */
+export interface KeychainRemote {
+  readonly key: string
+  readonly label: string
+  /** The variable that sets the token instead, named in the warning. */
+  readonly env: string
+}
+
+/**
+ * The token from the plugin's OS keychain, asked for on a terminal when
+ * missing (core's `ctx.secret`): the last source, after the option, the
+ * variable and the config files. A throw is the one warning that leaves the
+ * run on the local cache.
+ */
+export async function keychainToken(
+  ctx: RemoteOpenContext,
+  remote: KeychainRemote,
+): Promise<string> {
+  let token: string
+  try {
+    token = await ctx.secret({
+      key: remote.key,
+      prompt: `Token for ${remote.label}, saved to the OS keychain: `,
+    })
+  } catch (err) {
+    if (!isSecretUnavailable(err)) throw err
+    throw new Error(
+      `no token for ${remote.label}: set ${remote.env}, run vx in a terminal to be asked for one (kept in the OS keychain), or pass --cache-policy=remote: to skip the remote; local cache only this run`,
+    )
+  }
+  const fault = headerValueFault(token)
+  if (fault !== null) {
+    await ctx.forgetSecret({ key: remote.key })
+    throw new Error(
+      `the OS keychain's token for ${remote.label} holds ${fault}, which no HTTP header can carry (it is not printed); removed it, so the next run asks again`,
+    )
+  }
+  return token.trim()
+}
+
+/** How a remote reads in a prompt or a warning: its host, then its team. */
+export function remoteLabel(url: string, team: string | undefined): string {
+  const host = URL.canParse(url) ? new URL(url).host : url
+  return team === undefined ? host : `${host} (${team})`
+}

package/src/tsc-buildinfo.ts

@@ -0,0 +1,168 @@
+// Where `tsc` keeps its incremental state. tsc reads its `.tsbuildinfo`
+// and re-emits only the files it calls changed. vx empties a task's
+// outputs before a miss, so a `tsc -b` whose buildinfo sits outside them
+// (rootDir `src`, outDir `dist`: `tsconfig.tsbuildinfo` beside the
+// tsconfig) re-emitted the edited file into an empty `dist/`, and vx cached
+// that partial `dist/`. Turbo never cleans, so its `dist/` stayed whole; Nx
+// infers the buildinfo as an output. A mapped task declares it too.
+
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+/** A file's text, or null when it cannot be read. */
+export type ReadText = (file: string) => string | null
+
+interface Options {
+  composite?: unknown
+  incremental?: unknown
+  tsBuildInfoFile?: unknown
+  outDir?: unknown
+  rootDir?: unknown
+  outFile?: unknown
+}
+
+interface TsConfig {
+  extends?: unknown
+  references?: unknown
+  compilerOptions?: Options
+}
+
+function parse(read: ReadText, file: string): TsConfig | null {
+  const text = read(file)
+  if (text === null) return null
+  try {
+    const v = Bun.JSONC.parse(text)
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as TsConfig) : null
+  } catch {
+    return null
+  }
+}
+
+/** The file an `extends` entry names, as tsc resolves it (a package through `node_modules`). */
+function extended(read: ReadText, from: string, ext: string): string | null {
+  const withJson = (p: string) => (p.endsWith('.json') ? p : `${p}.json`)
+  if (ext.startsWith('.') || path.isAbsolute(ext)) return withJson(path.resolve(from, ext))
+  for (let dir = from; ; dir = path.dirname(dir)) {
+    const base = path.join(dir, 'node_modules', ext)
+    for (const f of [withJson(base), path.join(base, 'tsconfig.json')])
+      if (read(f) !== null) return f
+    if (path.dirname(dir) === dir) return null
+  }
+}
+
+/** The buildinfo path tsc writes for the project `file` (tsc's `getTsBuildInfoEmitOutputFilePath`). */
+function buildInfoOf(read: ReadText, file: string, build: boolean): string | null {
+  const configDir = path.dirname(file)
+  const opts: { [K in keyof Options]?: string | boolean } = {}
+  const seen = new Set<string>()
+  // The nearest file that states a field decides it; a path is relative to that file.
+  const visit = (at: string, depth: number): void => {
+    if (depth > 16 || seen.has(at)) return
+    seen.add(at)
+    const cfg = parse(read, at)
+    if (cfg === null) return
+    const o = cfg.compilerOptions ?? {}
+    for (const k of ['composite', 'incremental'] as const)
+      if (opts[k] === undefined && typeof o[k] === 'boolean') opts[k] = o[k]
+    for (const k of ['tsBuildInfoFile', 'outDir', 'rootDir', 'outFile'] as const) {
+      const v = o[k]
+      if (opts[k] !== undefined || typeof v !== 'string') continue
+      opts[k] = v.startsWith('${configDir}')
+        ? path.join(configDir, v.slice('${configDir}'.length))
+        : path.resolve(path.dirname(at), v)
+    }
+    // A later entry of an `extends` array wins over an earlier one.
+    const exts = typeof cfg.extends === 'string' ? [cfg.extends] : cfg.extends
+    if (!Array.isArray(exts)) return
+    for (const e of [...exts].reverse()) {
+      const next = typeof e === 'string' ? extended(read, path.dirname(at), e) : null
+      if (next !== null) visit(next, depth + 1)
+    }
+  }
+  visit(file, 0)
+  // No project there: tsc fails, and writes nothing.
+  if (parse(read, file) === null) return null
+  // tsc 5.6+ writes a buildinfo for every project `-b` builds.
+  if (!build && opts.incremental !== true && opts.composite !== true) return null
+  if (typeof opts.tsBuildInfoFile === 'string') return opts.tsBuildInfoFile
+  const bare = (p: string) => p.slice(0, p.length - path.extname(p).length)
+  if (typeof opts.outFile === 'string') return `${bare(opts.outFile)}.tsbuildinfo`
+  const config = bare(file)
+  const outDir = opts.outDir as string | undefined
+  const rootDir = opts.rootDir as string | undefined
+  const at =
+    outDir === undefined
+      ? config
+      : rootDir === undefined
+        ? path.join(outDir, path.basename(config))
+        : path.resolve(outDir, path.relative(rootDir, config))
+  return `${at}.tsbuildinfo`
+}
+
+/** A project argument's tsconfig: a directory names its `tsconfig.json`. */
+const projectFile = (dir: string, arg: string): string =>
+  arg.endsWith('.json') ? path.resolve(dir, arg) : path.resolve(dir, arg, 'tsconfig.json')
+
+/** Words that may run `tsc` before it: a runner, or an env assignment. */
+const RUNNER = /^(?:npx|bunx|pnpx|pnpm|yarn|npm|bun|exec|run|-y|--yes|--|[A-Za-z_][\w]*=\S*)$/
+
+/**
+ * The buildinfo files `command`'s `tsc` runs write, relative to the
+ * package `dir` (POSIX); one outside `dir` is another package's.
+ */
+export function tscBuildInfo(read: ReadText, dir: string, command: string): string[] {
+  const out = new Set<string>()
+  for (const segment of command.split(/&&|\|\||[;|&()\n]/)) {
+    const words = segment.trim().split(/\s+/)
+    const at = words.indexOf('tsc')
+    if (at < 0 || !words.slice(0, at).every((w) => RUNNER.test(w))) continue
+    const args = words.slice(at + 1)
+    if (args.some((a) => /^(?:-w|--watch|--clean)$/.test(a))) continue
+    const build = args[0] === '-b' || args[0] === '--build'
+    const files: string[] = []
+    if (build) {
+      const named = args.slice(1).filter((a) => !a.startsWith('-'))
+      files.push(...(named.length > 0 ? named : ['.']).map((a) => projectFile(dir, a)))
+    } else {
+      const p = args.findIndex((a) => a === '-p' || a === '--project')
+      files.push(projectFile(dir, p >= 0 && args[p + 1] !== undefined ? args[p + 1]! : '.'))
+    }
+    // `-b` builds each referenced project first, each with its own buildinfo.
+    const queue = [...files]
+    const visited = new Set<string>()
+    while (queue.length > 0) {
+      const file = queue.shift()!
+      if (visited.has(file)) continue
+      visited.add(file)
+      const info = buildInfoOf(read, file, build)
+      if (info !== null) {
+        const rel = path.relative(dir, info).split(path.sep).join('/')
+        if (!rel.startsWith('../') && !path.isAbsolute(rel)) out.add(rel)
+      }
+      if (!build) continue
+      const refs = parse(read, file)?.references
+      if (!Array.isArray(refs)) continue
+      for (const r of refs) {
+        const p = (r as { path?: unknown } | null)?.path
+        if (typeof p === 'string') queue.push(projectFile(path.dirname(file), p))
+      }
+    }
+  }
+  return [...out]
+}
+
+/** A reader that reads each file once, and the texts it read (a mapping's cache key). */
+export function onceReader(): { read: ReadText; texts: Map<string, string | null> } {
+  const texts = new Map<string, string | null>()
+  const read: ReadText = (file) => {
+    if (!texts.has(file)) {
+      let text: string | null = null
+      try {
+        text = readFileSync(file, 'utf8')
+      } catch {}
+      texts.set(file, text)
+    }
+    return texts.get(file)!
+  }
+  return { read, texts }
+}

package/src/turbo/index.ts

@@ -19,7 +19,8 @@ import { type AdoptionRun, adoptionPlugin } from '../adoption-plugin.js'
 import type { AdoptionMapping } from '../mapping-cache.js'
 import { collectGaps } from '../plugin-gaps.js'
 import { gitIgnored, trackedKinds } from '../tracked-outputs.js'
-import { relPosix } from '../paths.js'
+import { packageScripts, relPosix } from '../paths.js'
+import { onceReader, type ReadText, tscBuildInfo } from '../tsc-buildinfo.js'
 import {
   envNamesThatMap,
   mapTurboWorkspace,
@@ -247,6 +248,11 @@ async function run(root: string, projects: readonly ProjectMeta[]): Promise<Adop
     dirs.flatMap((d) => ['turbo.json', 'turbo.jsonc'].map((f) => textOf(path.join(d, f)))),
   )
   const envNames = envNamesThatMap(configs, envNamesNow())
+  // The tsconfigs a `tsc` script reads are the mapping's inputs too.
+  const tsc = onceReader()
+  for (const m of metas)
+    for (const s of Object.values(packageScripts(m)))
+      if (typeof s === 'string' && /\btsc\b/.test(s)) tscBuildInfo(tsc.read, m.dir, s)
   return {
     name: 'turbo',
     spareTracked: true,
@@ -263,8 +269,9 @@ async function run(root: string, projects: readonly ProjectMeta[]): Promise<Adop
       JSON.stringify(microfrontendsConfigs(root, dirs)),
       // A config file added beside mapped tasks changes what an output may cover.
       JSON.stringify(metas.map((m) => [m.name, m.dir, m.packageJson, m.configPath])),
+      JSON.stringify([...tsc.texts]),
     ],
-    map: (tracked) => mapAll(root, metas, envNames, tracked),
+    map: (tracked) => mapAll(root, metas, envNames, tracked, tsc.read),
   }
 }
 
@@ -279,6 +286,7 @@ async function mapAll(
   metas: readonly PackageMeta[],
   envNames: readonly string[],
   trackedFiles: () => Promise<readonly string[] | null>,
+  read: ReadText,
 ): Promise<AdoptionMapping> {
   const tracked = await trackedFiles()
   const configs = new Map(
@@ -296,6 +304,7 @@ async function mapAll(
     ...(tracked === null ? {} : { tracked: trackedKinds(tracked) }),
     ownConfig: (rel) => configs.get(rel === '.' ? '' : rel) ?? null,
     ignored: (rels) => gitIgnored(root, rels),
+    buildInfo: (rel, command) => tscBuildInfo(read, path.join(root, rel), command),
   })
   const byName = new Map<string, TurboMappedProject>()
   for (const project of mapped.projects) byName.set(project.name, project)

package/src/turbo/turbo-map.ts

@@ -349,6 +349,11 @@ export interface MapTurboOptions {
    * path among them is keyed by a probe. Absent, none is.
    */
   ignored?: (rels: readonly string[]) => Promise<ReadonlySet<string>>
+  /**
+   * The `.tsbuildinfo` files a root-relative package's command writes,
+   * relative to the package (`tscBuildInfo`). Absent, none.
+   */
+  buildInfo?: (rel: string, command: string) => readonly string[]
 }
 
 /**
@@ -384,6 +389,15 @@ function withZeroSegments(glob: string): string[] {
   return head === null ? [glob] : [glob, neg + head]
 }
 
+/** Does a positive glob of `globs` take `rel`, and no `!` give it back? */
+function covers(globs: readonly string[], rel: string): boolean {
+  const hit = (g: string) => new Bun.Glob(g).match(rel)
+  return (
+    globs.some((g) => !g.startsWith('!') && hit(g)) &&
+    !globs.some((g) => g.startsWith('!') && hit(g.slice(1)))
+  )
+}
+
 /** No glob syntax: one path, which git may ignore. */
 const isLiteral = (glob: string): boolean => !/[*?[\]{}()!]/.test(glob)
 
@@ -2141,6 +2155,12 @@ function buildTask(
     return { name, todos, task, uses }
   }
   if (wild !== undefined) todos.push(wildcardCleanTodo(wild))
+  // tsc re-emits only what its buildinfo calls changed: outside the
+  // outputs it survives the clean before a miss, and the miss caches a
+  // partial `dist/` (`tsc-buildinfo.ts`).
+  if (outFiles.some((g) => !g.startsWith('!')))
+    for (const rel of opts.buildInfo?.(pkgDir, command) ?? [])
+      if (!covers(outFiles, rel)) outFiles.push(literalGlob(rel))
   // An output over the project's own package.json (trpc's builds list
   // it: tsdown rewrites `exports`) is taken back and keeps the cache, as
   // nx() does (owner, 2026-10-03). The build rewrites an input the key

package/src/turbo-cache/index.ts

@@ -7,8 +7,8 @@
 // Nothing is on by default: declare `turboCache()` in `.vx/workspace.ts`
 // (the local store is the floor beneath it) and give it a URL and a token (options, or
 // Turbo's own environment variables and turbo.json's `remoteCache` so a
-// self-hosted setup carries over).
-// With neither the plugin DECLINES and the run stays local.
+// self-hosted setup carries over; the OS keychain last). With no URL, team
+// or token the plugin DECLINES and the run stays local.
 //
 // Imports core only through the public `@vzn/vx` specifier.
 import { readFileSync, unlinkSync } from 'node:fs'
@@ -18,20 +18,40 @@ import path from 'node:path'
 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'
+import {
+  exchangeOidc,
+  type OidcConfig,
+  oidcSettings,
+  revokeOidc,
+  type TurboOidcOptions,
+} from './oidc.js'
 
 export interface TurboCacheOptions {
   /** Base URL of the cache server (`https://cache.example.com`), or `TURBO_API`; with a token and neither, Vercel's hosted cache, as for `turbo`. */
   apiUrl?: string
-  /** Bearer token every request carries, or `TURBO_TOKEN`. */
+  /** Bearer token every request carries, or `TURBO_TOKEN`, OIDC, `.turbo/config.json`, then the OS keychain. */
   token?: string
+  /**
+   * On GitHub Actions with no token or `TURBO_TOKEN`, exchange the job's
+   * OIDC token for a short-lived one, revoked when the run ends. `true`:
+   * Vercel's hosted cache with Vercel's endpoints; any other server names
+   * its `tokenUrl`. The job needs `permissions: id-token: write`.
+   */
+  oidc?: true | TurboOidcOptions
   /** `teamId` query parameter, or `TURBO_TEAMID`. Required with `signatureKey`. */
   teamId?: string
   /** `slug` query parameter (a team slug), or `TURBO_TEAM`. */
@@ -84,7 +104,12 @@ export interface TurboLocalConfig {
 
 export interface TurboCacheConfig {
   apiUrl: string
-  token: string
+  /** Undefined: the layer's `open` exchanges OIDC or asks the OS keychain. */
+  token?: string
+  /** The job's OIDC exchange, when `oidc` is set and GitHub hands the job a token. */
+  oidc?: OidcConfig
+  /** `oidc` is set on GitHub Actions, but the job has no ID-token permission. */
+  oidcMissing?: true
   teamId?: string
   teamSlug?: string
   signatureKey?: string
@@ -223,18 +248,41 @@ export function resolveTurboCacheConfig(
     !turboPair && env['VERCEL_ARTIFACTS_TOKEN'] && env['VERCEL_ARTIFACTS_OWNER']
       ? { token: env['VERCEL_ARTIFACTS_TOKEN'], teamId: env['VERCEL_ARTIFACTS_OWNER'] }
       : { token: undefined, teamId: turboPair ? undefined : env['VERCEL_ARTIFACTS_OWNER'] }
-  const token = options.token ?? env['TURBO_TOKEN'] ?? vercel.token ?? fromFile(local.token)
-  // Turbo's own default when a token is set and no `apiUrl` is: Vercel's
-  // hosted Remote Cache. A token alone is a configured cache, as it is for
-  // `turbo`; no token at all is the declined, local run.
+  // Empty is unset, as Turbo reads it: a fork's pull request gets `''` for a secret.
+  const given = (options.token ?? env['TURBO_TOKEN'] ?? vercel.token) || undefined
+  // OIDC sits under the variables and over the config files.
+  const idTokenUrl = env['ACTIONS_ID_TOKEN_REQUEST_URL'] || undefined
+  const idTokenBearer = env['ACTIONS_ID_TOKEN_REQUEST_TOKEN'] || undefined
+  const exchanges =
+    options.oidc !== undefined &&
+    given === undefined &&
+    idTokenUrl !== undefined &&
+    idTokenBearer !== undefined
+  const token = given ?? (exchanges ? undefined : fromFile(local.token) || undefined)
+  const teamId =
+    options.teamId ??
+    env['TURBO_TEAMID'] ??
+    vercel.teamId ??
+    fromFile(local.teamId) ??
+    fromFile(file.teamId)
+  const teamSlug =
+    options.teamSlug ?? env['TURBO_TEAM'] ?? fromFile(local.teamSlug) ?? fromFile(file.teamSlug)
+  // Turbo's own default when a token or a team is set and no `apiUrl` is:
+  // Vercel's hosted Remote Cache. A token alone is a configured cache, as it
+  // is for `turbo`; a URL or a team without one asks the OS keychain at
+  // `open`; none of them is the declined, local run.
   const apiUrl = (
     options.apiUrl ??
     env['TURBO_API'] ??
     fromFile(local.apiUrl) ??
     fromFile(file.apiUrl) ??
-    (token ? VERCEL_API : undefined)
+    (token || teamId || teamSlug ? VERCEL_API : undefined)
   )?.replace(/\/+$/, '')
-  if (!apiUrl || !token) return undefined
+  if (!apiUrl) return undefined
+  const oidc =
+    options.oidc === undefined
+      ? undefined
+      : oidcSettings(options.oidc, apiUrl === VERCEL_API, teamId ?? teamSlug)
   // The URL is printed in every refusal line, so a `user:pass@` in it would
   // leak to the log. Credentials go in the token.
   if (URL.canParse(apiUrl)) {
@@ -244,19 +292,11 @@ export function resolveTurboCacheConfig(
         'vx/turbo-cache: apiUrl carries credentials (user:pass@); pass them as the token instead',
       )
   }
-  const fault = headerValueFault(token)
+  const fault = token === undefined ? null : headerValueFault(token)
   if (fault !== null)
     throw new Error(
       `vx/turbo-cache: the token holds ${fault}, which no HTTP header can carry — check the secret (it is not printed)`,
     )
-  const teamId =
-    options.teamId ??
-    env['TURBO_TEAMID'] ??
-    vercel.teamId ??
-    fromFile(local.teamId) ??
-    fromFile(file.teamId)
-  const teamSlug =
-    options.teamSlug ?? env['TURBO_TEAM'] ?? fromFile(local.teamSlug) ?? fromFile(file.teamSlug)
   const preflight =
     options.preflight ??
     truthy(env['TURBO_PREFLIGHT'], 'TURBO_PREFLIGHT') ??
@@ -291,7 +331,13 @@ export function resolveTurboCacheConfig(
   }
   return {
     apiUrl,
-    token,
+    ...(token !== undefined ? { token } : {}),
+    ...(oidc !== undefined && exchanges
+      ? { oidc: { ...oidc, idTokenUrl: idTokenUrl!, idTokenBearer: idTokenBearer! } }
+      : {}),
+    ...(oidc !== undefined && !exchanges && given === undefined && env['GITHUB_ACTIONS'] === 'true'
+      ? { oidcMissing: true as const }
+      : {}),
     ...(teamId ? { teamId } : {}),
     ...(teamSlug ? { teamSlug } : {}),
     ...(signatureKey !== undefined ? { signatureKey } : {}),
@@ -393,6 +439,15 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   private readonly absent = new Set<string>()
   private readonly key: Uint8Array | undefined
   readonly endpoint: string
+  /** 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
+  /** The token an OIDC exchange gave, revoked when the run ends. */
+  private exchanged: string | undefined
+  private readonly keychainRemote: KeychainRemote
+  /** The remote's rate limit, which every request of this client waits out. */
+  private readonly cooldown = new Cooldown()
   constructor(
     private readonly config: TurboCacheConfig,
     private readonly fetchImpl: typeof fetch = fetch,
@@ -403,6 +458,34 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   ) {
     this.key = config.signatureKey === undefined ? undefined : Buffer.from(config.signatureKey)
     this.endpoint = `${config.apiUrl}/v8/artifacts`
+    this.token = config.token
+    const team = config.teamId ?? config.teamSlug
+    this.keychainRemote = {
+      key: team === undefined ? this.endpoint : `${this.endpoint}#${team}`,
+      label: remoteLabel(config.apiUrl, team),
+      env: 'TURBO_TOKEN',
+    }
+  }
+
+  async open(ctx: RemoteOpenContext): Promise<void> {
+    if (this.config.oidcMissing)
+      ctx.warn(
+        'oidc: GitHub gave this job no OIDC token: it needs `permissions: id-token: write` (a fork or Dependabot pull request never gets one)',
+      )
+    if (this.token !== undefined) return
+    if (this.config.oidc !== undefined) {
+      try {
+        this.token = await exchangeOidc(this.config.oidc, this.fetchImpl, this.wait)
+      } catch (err) {
+        throw new Error(
+          `oidc: ${err instanceof Error ? err.message : String(err)}; local cache only this run`,
+        )
+      }
+      this.exchanged = this.token
+      return
+    }
+    this.token = await keychainToken(ctx, this.keychainRemote)
+    this.forget = () => ctx.forgetSecret({ key: this.keychainRemote.key })
   }
 
   private url(pathname: string): string {
@@ -417,7 +500,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
 
   private headers(extra: Record<string, string> = {}, auth = true): Record<string, string> {
     return {
-      ...(auth ? { Authorization: `Bearer ${this.config.token}` } : {}),
+      ...(auth ? { Authorization: `Bearer ${this.token}` } : {}),
       'x-artifact-client-interactive': process.stdout.isTTY ? '1' : '0',
       ...extra,
     }
@@ -444,7 +527,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     const res = await this.fetchImpl(url, {
       method: 'OPTIONS',
       headers: {
-        Authorization: `Bearer ${this.config.token}`,
+        Authorization: `Bearer ${this.token}`,
         'Access-Control-Request-Method': method === 'HEAD' ? 'GET' : method,
         'Access-Control-Request-Headers': ['Authorization', ...Object.keys(headers)].join(', '),
       },
@@ -473,6 +556,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     pathname: string,
     init: { body?: Blob | string; headers?: Record<string, string>; timeoutMs?: number } = {},
   ): Promise<Response | undefined> {
+    if (this.token === undefined) return undefined
     const timeoutMs = init.timeoutMs ?? this.config.timeoutMs
     // 0 is Turbo's "no deadline".
     const signal = () => (timeoutMs === 0 ? undefined : deadline(timeoutMs))
@@ -496,6 +580,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
           },
           this.config.retries,
           this.wait,
+          this.cooldown,
         ),
       method === 'GET',
     )
@@ -511,11 +596,24 @@ export class TurboRemoteCache implements RemoteCacheLayer {
       const first = !this.disabled
       this.disabled = true
       if (!first) return undefined
-      throw new Error(`HTTP ${res.status}: the token was refused; remote cache off for this run`)
+      if (this.forget === undefined)
+        throw new Error(`HTTP ${res.status}: the token was refused; remote cache off for this run`)
+      await this.forget()
+      throw new Error(
+        `HTTP ${res.status}: the token was refused; removed it from the OS keychain, so the next run asks again; remote cache off for this run`,
+      )
     }
     return res
   }
 
+  /** Revoke the token `open` exchanged, once; a throw is the caller's warning. */
+  async revoke(): Promise<void> {
+    const token = this.exchanged
+    if (token === undefined) return
+    this.exchanged = undefined
+    await revokeOidc(this.config.oidc!, token, this.fetchImpl, this.wait)
+  }
+
   async has(hash: string): Promise<boolean> {
     if (this.disabled) return false
     const res = await this.request('HEAD', `/${hash}`)
@@ -702,6 +800,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
   uploadTimeoutMs: 'number',
   retries: 'number',
   preflight: 'boolean',
+  oidc: 'any',
 }
 
 /**
@@ -711,10 +810,12 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
  * plugins: [turboCache({ apiUrl: 'https://cache.example.com', token: process.env.CACHE_TOKEN })]
  * ```
  *
- * Declines without a URL and a token, so it is safe to leave declared.
+ * Declines with no URL, team or token, so it is safe to leave declared.
  */
 export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
   refuseUnknownOptions('turboCache()', options, TURBO_CACHE_KEYS)
+  // The run's layer and warn, for `teardown` to revoke an exchanged token.
+  let opened: { layer: TurboRemoteCache; warn: (m: string) => void } | undefined
   return definePlugin(import.meta, {
     cache(ctx): RemoteCacheLayer | undefined {
       const config = resolveTurboCacheConfig(
@@ -727,7 +828,20 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
       // A signed download waits in a temp until its tag checks: in vx's
       // cache directory, which the sandbox walls, not the shared temp dir a
       // sandboxed task may read (L-45).
-      return new TurboRemoteCache(config, fetch, ctx.cacheDir)
+      const layer = new TurboRemoteCache(config, fetch, ctx.cacheDir)
+      if (config.oidc !== undefined) opened = { layer, warn: ctx.warn }
+      return layer
+    },
+    async teardown() {
+      const run = opened
+      opened = undefined
+      await run?.layer
+        .revoke()
+        .catch((err: unknown) =>
+          run.warn(
+            `[vx] plugin '@vzn/vx-migrate': oidc: ${err instanceof Error ? err.message : String(err)}; the token expires on its own`,
+          ),
+        )
     },
   })
 }

package/src/turbo-cache/oidc.ts

@@ -0,0 +1,171 @@
+// A GitHub Actions job's OIDC token, exchanged for a short-lived remote
+// cache token (RFC 8693), and revoked when the run ends (RFC 7009): no
+// long-lived TURBO_TOKEN secret in the repo. Vercel's flow as its own
+// action runs it (vercel/setup-turborepo-remote-cache-action, read
+// 2026-10-17); any other server names its token URL.
+
+import { deadline } from '../remote-deadline.js'
+
+/** `turboCache({ oidc })`: `true` is Vercel's hosted cache with its defaults. */
+export interface TurboOidcOptions {
+  /** The RFC 8693 token endpoint; Vercel's by default with Vercel's cache, required otherwise. */
+  tokenUrl?: string
+  /** The RFC 7009 revocation endpoint, asked when the run ends; `false`: none. Vercel's by default. */
+  revokeUrl?: string | false
+  /** The `audience` GitHub mints the OIDC token for. */
+  audience?: string
+  /** Fields the exchange also sends (Vercel's `policy_id`); over the defaults. */
+  params?: Record<string, string>
+}
+
+export interface OidcConfig {
+  /** GitHub's ID-token endpoint and its bearer: the job's `ACTIONS_ID_TOKEN_REQUEST_*`. */
+  idTokenUrl: string
+  idTokenBearer: string
+  tokenUrl: string
+  revokeUrl?: string
+  audience?: string
+  params: Record<string, string>
+}
+
+const VERCEL_TOKEN_URL = 'https://api.vercel.com/login/oauth/token'
+const VERCEL_REVOKE_URL = 'https://api.vercel.com/login/oauth/token/revoke'
+/** Vercel's public OAuth client for the Remote Cache exchange, as its action sends it. */
+const VERCEL_CLIENT_ID = 'cl_kyUx2zVvA4MGptBohkmtYHJly2XltXzD'
+
+const ATTEMPTS = 3
+const TIMEOUT_MS = 30_000
+
+/**
+ * The exchange `oidc` asks for, or undefined when the option is off. A
+ * misconfigured one (a server that is not Vercel's with no `tokenUrl`, a
+ * Vercel exchange with no team) is refused at config load.
+ */
+export function oidcSettings(
+  oidc: true | TurboOidcOptions,
+  vercel: boolean,
+  team: string | undefined,
+): Omit<OidcConfig, 'idTokenUrl' | 'idTokenBearer'> {
+  const o = oidc === true ? {} : oidc
+  if (typeof o !== 'object' || o === null)
+    throw new Error(
+      'vx/turbo-cache: oidc must be true or { tokenUrl, revokeUrl, audience, params }',
+    )
+  if (!vercel && o.tokenUrl === undefined)
+    throw new Error("vx/turbo-cache: oidc needs tokenUrl for a cache that is not Vercel's")
+  if (vercel && team === undefined)
+    throw new Error('vx/turbo-cache: oidc on Vercel needs teamId or teamSlug (TURBO_TEAM)')
+  const revokeUrl = o.revokeUrl ?? (vercel ? VERCEL_REVOKE_URL : undefined)
+  return {
+    tokenUrl: o.tokenUrl ?? VERCEL_TOKEN_URL,
+    ...(revokeUrl === false || revokeUrl === undefined ? {} : { revokeUrl }),
+    ...(o.audience !== undefined ? { audience: o.audience } : {}),
+    params: {
+      ...(vercel ? { client_id: VERCEL_CLIENT_ID, team_id_or_slug: team! } : {}),
+      ...o.params,
+    },
+  }
+}
+
+/** A request, sent again on a 429, a 5xx or no answer: up to three tries, 30 s each. */
+async function send(
+  fetchImpl: typeof fetch,
+  url: string,
+  init: RequestInit,
+  wait: (ms: number) => Promise<void>,
+): Promise<Response> {
+  for (let attempt = 1; ; attempt++) {
+    let res: Response | undefined
+    let failure: unknown
+    try {
+      res = await fetchImpl(url, { ...init, signal: deadline(TIMEOUT_MS) })
+    } catch (err) {
+      failure = err
+    }
+    const again = res === undefined || res.status === 429 || res.status >= 500
+    if (!again || attempt === ATTEMPTS) {
+      if (res === undefined) throw failure
+      return res
+    }
+    await res?.body?.cancel()
+    await wait(1000 * attempt)
+  }
+}
+
+const form = (fields: Record<string, string>) => ({
+  method: 'POST',
+  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  body: new URLSearchParams(fields).toString(),
+})
+
+/** Where a URL points, never its query: GitHub's carries a runtime id. */
+const where = (url: string) => (URL.canParse(url) ? new URL(url).host : 'the endpoint')
+
+async function field(res: Response, name: string, what: string): Promise<string> {
+  if (!res.ok) {
+    await res.body?.cancel()
+    throw new Error(`${what} answered HTTP ${res.status}`)
+  }
+  const value = ((await res.json().catch(() => null)) as Record<string, unknown> | null)?.[name]
+  if (typeof value !== 'string' || value === '') throw new Error(`${what} sent no ${name}`)
+  return value
+}
+
+/** The job's OIDC token, exchanged for the cache's access token. Errors never quote a token. */
+export async function exchangeOidc(
+  cfg: OidcConfig,
+  fetchImpl: typeof fetch = fetch,
+  wait: (ms: number) => Promise<void> = Bun.sleep,
+): Promise<string> {
+  const idUrl = new URL(cfg.idTokenUrl)
+  if (cfg.audience !== undefined) idUrl.searchParams.set('audience', cfg.audience)
+  const idToken = await field(
+    await send(
+      fetchImpl,
+      idUrl.toString(),
+      { headers: { Authorization: `bearer ${cfg.idTokenBearer}` } },
+      wait,
+    ),
+    'value',
+    `GitHub's OIDC endpoint (${where(cfg.idTokenUrl)})`,
+  )
+  return field(
+    await send(
+      fetchImpl,
+      cfg.tokenUrl,
+      form({
+        grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+        subject_token: idToken,
+        subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+        requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
+        ...cfg.params,
+      }),
+      wait,
+    ),
+    'access_token',
+    `the token exchange (${where(cfg.tokenUrl)})`,
+  )
+}
+
+/** Revoke the exchanged token; a throw is the caller's warning. */
+export async function revokeOidc(
+  cfg: OidcConfig,
+  token: string,
+  fetchImpl: typeof fetch = fetch,
+  wait: (ms: number) => Promise<void> = Bun.sleep,
+): Promise<void> {
+  if (cfg.revokeUrl === undefined) return
+  const clientId = cfg.params['client_id']
+  const res = await send(
+    fetchImpl,
+    cfg.revokeUrl,
+    form({
+      ...(clientId !== undefined ? { client_id: clientId } : {}),
+      token,
+      token_type_hint: 'access_token',
+    }),
+    wait,
+  )
+  await res.body?.cancel()
+  if (!res.ok) throw new Error(`revoking at ${where(cfg.revokeUrl)} answered HTTP ${res.status}`)
+}