@vzn/vx-migrate 0.0.641 → 0.0.643

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,
@@ -77,8 +78,7 @@ export function turbo(options: TurboPluginOptions = {}): VxPlugin {
         const base =
           Bun.env['TURBO_SCM_BASE']?.trim() ||
           githubActionsBase(options.root ?? ctx.workspaceRoot, keys.remoteBaseFallback === true)
-        if (workspace.run?.affectedBase === undefined && base)
-          workspace.run = { ...workspace.run, affectedBase: base }
+        if (base) ctx.setBranch({ base })
       },
       // Turbo's packages are the package manager's members, each a project
       // with no vx.config written. `//#task` keys run on the root, as Turbo
@@ -247,6 +247,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 +268,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 +285,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 +303,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`,
+          ),
+        )
     },
   })
 }