@vzn/vx-migrate 0.0.645 → 0.0.648

package/src/turbo-cache/index.ts

@@ -18,13 +18,17 @@ import path from 'node:path'
 import {
   type ArtifactInfo,
   definePlugin,
+  type LentAccess,
   type RemoteCacheLayer,
   type RemoteOpenContext,
   type VxPlugin,
   refuseUnknownOptions,
+  UserError,
   type PluginOptionKinds,
 } from '@vzn/vx'
-import { deadline } from '../remote-deadline.js'
+import { deadline, MAX_TIMER_MS } from '../remote-deadline.js'
+import { checkRemoteUrl } from '../remote-url.js'
+import { refusal } from '../remote-refusal.js'
 import { keyedByRef, readScopes, remoteScope, type RemoteScope } from './scope.js'
 import { OutageBreaker } from '../remote-breaker.js'
 import { Cooldown, withRetry } from '../remote-retry.js'
@@ -44,7 +48,7 @@ import {
 
 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
+  url?: string
   /** Bearer token every request carries, or `TURBO_TOKEN`, OIDC, `.turbo/config.json`, then the OS keychain. */
   token?: string
   /**
@@ -54,7 +58,7 @@ export interface TurboCacheOptions {
    * its `tokenUrl`. The job needs `permissions: id-token: write`.
    */
   oidc?: true | TurboOidcOptions
-  /** `teamId` query parameter, or `TURBO_TEAMID`. Required with `signatureKey`. */
+  /** `teamId` query parameter, or `TURBO_TEAMID`; the signature folds it, `''` when unset, as Turbo's does. */
   teamId?: string
   /** `slug` query parameter (a team slug), or `TURBO_TEAM`. */
   teamSlug?: string
@@ -62,8 +66,10 @@ export interface TurboCacheOptions {
    * Sign uploads and verify downloads with Turbo's artifact signature
    * (HMAC-SHA256, `x-artifact-tag`), or `TURBO_REMOTE_CACHE_SIGNATURE_KEY`
    * where turbo.json sets `remoteCache.signature: true`, as Turbo reads it.
-   * At least 32 bytes, used raw. A download whose tag does not verify is a
-   * miss, never a restore.
+   * The option needs at least 32 bytes; the env key warns below that,
+   * refused only under turbo.json's `futureFlags.longerSignatureKey`, as
+   * in Turbo. Used raw. A download whose tag does not verify is a miss,
+   * never a restore.
    */
   signatureKey?: string
   /**
@@ -102,6 +108,8 @@ export interface TurboJsonRemoteCache {
   timeout?: unknown
   uploadTimeout?: unknown
   preflight?: unknown
+  /** turbo.json's `futureFlags.longerSignatureKey`, which `remoteCacheOf` hoists here. */
+  longerSignatureKey?: unknown
 }
 
 /** `.turbo/config.json`'s fields, under any of the spellings Turbo accepts. */
@@ -113,7 +121,7 @@ export interface TurboLocalConfig {
 }
 
 export interface TurboCacheConfig {
-  apiUrl: string
+  url: 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. */
@@ -195,6 +203,7 @@ function trackTemp(file: string): void {
     for (const f of liveTemps) {
       try {
         unlinkSync(f)
+        // quiet: a temp file already gone at exit
       } catch {
         // never written, or gone
       }
@@ -205,6 +214,7 @@ function trackTemp(file: string): void {
 async function removeTemp(file: string): Promise<void> {
   // Listed until the unlink lands: an exit in between would otherwise find
   // nothing to remove and leave the temp (item 868).
+  // quiet: a temp file already gone
   await unlink(file).catch(() => undefined)
   liveTemps.delete(file)
 }
@@ -245,7 +255,7 @@ function tagsEqual(expected: string, actual: string): boolean {
   return diff === 0
 }
 
-/** Where `turbo` itself sends a token with no `apiUrl`: Vercel's hosted Remote Cache. */
+/** Where `turbo` itself sends a token with no `url`: Vercel's hosted Remote Cache. */
 export const VERCEL_API = 'https://vercel.com/api'
 
 /** Resolve options over Turbo's environment; `undefined` = not configured. */
@@ -255,25 +265,28 @@ export function resolveTurboCacheConfig(
   file: TurboJsonRemoteCache = {},
   /** The repo's `.turbo/config.json` (`turbo link` writes it): below the environment, above turbo.json. */
   local: TurboLocalConfig = {},
+  warn: (message: string) => void = (m) => console.error(`[vx] plugin '@vzn/vx-migrate': ${m}`),
 ): TurboCacheConfig | undefined {
   // `enabled: false` turns Turbo's remote cache off whatever the env says;
   // options name a cache for vx alone, and win.
-  if (file.enabled === false && options.apiUrl === undefined && options.token === undefined)
+  if (file.enabled === false && options.url === undefined && options.token === undefined)
     return undefined
   const fromFile = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined)
+  // Empty is unset, as Turbo reads it: a fork's pull request gets `''` for a
+  // secret, and `${{ vars.TURBO_API }}` is `''` for an unset variable.
+  const set = (name: string): string | undefined => env[name] || undefined
   // A Vercel build hands Turbo its cache as VERCEL_ARTIFACTS_TOKEN and
   // _OWNER (the team id), taken where TURBO_TOKEN with a team is not set
   // (Turbo's `override_env.rs`); unread, turboCache() declined on Vercel.
-  const turboPair = env['TURBO_TOKEN'] && (env['TURBO_TEAMID'] || env['TURBO_TEAM'])
+  const turboPair = set('TURBO_TOKEN') && (set('TURBO_TEAMID') || set('TURBO_TEAM'))
   const vercel =
-    !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'] }
-  // 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
+    !turboPair && set('VERCEL_ARTIFACTS_TOKEN') && set('VERCEL_ARTIFACTS_OWNER')
+      ? { token: set('VERCEL_ARTIFACTS_TOKEN'), teamId: set('VERCEL_ARTIFACTS_OWNER') }
+      : { token: undefined, teamId: turboPair ? undefined : set('VERCEL_ARTIFACTS_OWNER') }
+  const given = (options.token ?? set('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 idTokenUrl = set('ACTIONS_ID_TOKEN_REQUEST_URL')
+  const idTokenBearer = set('ACTIONS_ID_TOKEN_REQUEST_TOKEN')
   const exchanges =
     options.oidc !== undefined &&
     given === undefined &&
@@ -282,41 +295,39 @@ export function resolveTurboCacheConfig(
   const token = given ?? (exchanges ? undefined : fromFile(local.token) || undefined)
   const teamId =
     options.teamId ??
-    env['TURBO_TEAMID'] ??
+    set('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:
+    options.teamSlug ?? set('TURBO_TEAM') ?? fromFile(local.teamSlug) ?? fromFile(file.teamSlug)
+  // Turbo's own default when a token or a team is set and no URL 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 || teamId || teamSlug ? VERCEL_API : undefined)
-  )?.replace(/\/+$/, '')
-  if (!apiUrl) return undefined
+  // Each source with its name: TURBO_API was refused as a `url`
+  // option the workspace never set.
+  const [rawUrl, urlFrom] =
+    options.url !== undefined
+      ? [options.url, 'turboCache() option "url"']
+      : set('TURBO_API') !== undefined
+        ? [set('TURBO_API'), 'TURBO_API']
+        : fromFile(local.apiUrl) !== undefined
+          ? [fromFile(local.apiUrl), '.turbo/config.json apiUrl']
+          : fromFile(file.apiUrl) !== undefined
+            ? [fromFile(file.apiUrl), 'turbo.json remoteCache.apiUrl']
+            : [token || teamId || teamSlug ? VERCEL_API : undefined, 'url']
+  const url = rawUrl?.replace(/\/+$/, '')
+  if (!url) return undefined
+  checkRemoteUrl(url, urlFrom)
   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)) {
-    const u = new URL(apiUrl)
-    if (u.username !== '' || u.password !== '')
-      throw new Error(
-        'vx/turbo-cache: apiUrl carries credentials (user:pass@); pass them as the token instead',
-      )
-  }
+      : oidcSettings(options.oidc, url === VERCEL_API, teamId ?? teamSlug)
   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)`,
+      `turboCache(): the token holds ${fault}, which no HTTP header can carry — check the secret (it is not printed)`,
     )
   const preflight =
     options.preflight ??
@@ -324,34 +335,34 @@ export function resolveTurboCacheConfig(
     file.preflight === true
   // Turbo signs only under `remoteCache.signature: true`; the env key alone
   // signs nothing there, and a short one here refused the whole cache.
-  // `TURBO_SIGNATURE` (1/true, 0/false) sits above turbo.json, as in Turbo.
-  const signing = truthy(env['TURBO_SIGNATURE'], 'TURBO_SIGNATURE') ?? file.signature === true
-  const signatureKey =
-    options.signatureKey ?? (signing ? env['TURBO_REMOTE_CACHE_SIGNATURE_KEY'] : undefined)
+  const signing = file.signature === true
+  const envKey = signing ? env['TURBO_REMOTE_CACHE_SIGNATURE_KEY'] || undefined : undefined
+  const signatureKey = options.signatureKey ?? envKey
+  // Turbo signs with no key as it fails every request: no usable remote. Read
+  // unsigned here, the bytes a signing repo refuses were restored.
+  if (signing && signatureKey === undefined) {
+    warn(
+      'turbo.json sets remoteCache.signature but TURBO_REMOTE_CACHE_SIGNATURE_KEY is unset: remote cache off for this run, as for turbo',
+    )
+    return undefined
+  }
   if (signatureKey !== undefined) {
-    if (Buffer.byteLength(signatureKey) < MIN_SIGNATURE_KEY_LENGTH) {
-      throw new Error(
-        `vx/turbo-cache: signatureKey must be at least ${MIN_SIGNATURE_KEY_LENGTH} bytes (Turbo's minimum)`,
+    const bytes = Buffer.byteLength(signatureKey)
+    // Turbo only warns about a short key unless `futureFlags.longerSignatureKey`
+    // is set; refusing it here failed a run Turbo runs.
+    if (bytes < MIN_SIGNATURE_KEY_LENGTH) {
+      if (options.signatureKey !== undefined || file.longerSignatureKey === true)
+        throw new Error(
+          `turboCache(): signatureKey must be at least ${MIN_SIGNATURE_KEY_LENGTH} bytes`,
+        )
+      warn(
+        `TURBO_REMOTE_CACHE_SIGNATURE_KEY is ${bytes} bytes; ${MIN_SIGNATURE_KEY_LENGTH} or more is safe (Turbo enforces it under futureFlags.longerSignatureKey)`,
       )
     }
-    if (!teamId)
-      throw new Error(
-        'vx/turbo-cache: signatureKey needs teamId — the team id is part of the signed message',
-      )
   }
   const retries = options.retries ?? 1
-  // A NaN never reaches the bound, and the request would be resent forever.
-  if (!Number.isInteger(retries) || retries < 0)
-    throw new Error(`vx/turbo-cache: retries must be a whole number ≥ 0, got ${retries}`)
-  // 0 is no deadline, as Turbo reads it; a negative or non-number one made
-  // AbortSignal.timeout throw on every request.
-  for (const name of ['timeoutMs', 'uploadTimeoutMs'] as const) {
-    const ms = options[name]
-    if (ms !== undefined && !(typeof ms === 'number' && Number.isFinite(ms) && ms >= 0))
-      throw new Error(`vx/turbo-cache: ${name} must be ms ≥ 0 (0: none), got ${JSON.stringify(ms)}`)
-  }
   return {
-    apiUrl,
+    url,
     ...(token !== undefined ? { token } : {}),
     ...(oidc !== undefined && exchanges
       ? { oidc: { ...oidc, idTokenUrl: idTokenUrl!, idTokenBearer: idTokenBearer! } }
@@ -381,7 +392,7 @@ export function resolveTurboCacheConfig(
 function truthy(v: string | undefined, name: string): boolean | undefined {
   if (v === undefined || v === '') return undefined
   if (!/^(1|0|true|false)$/.test(v))
-    throw new Error(`vx/turbo-cache: ${name} should be 1 or 0, got ${JSON.stringify(v)}`)
+    throw new Error(`turboCache(): ${name} should be 1 or 0, got ${JSON.stringify(v)}`)
   return v === '1' || v === 'true'
 }
 
@@ -393,7 +404,7 @@ function seconds(v: unknown, name: string): number | undefined {
   if (v === undefined || v === null || v === '') return undefined
   const n = typeof v === 'string' ? Number(v) : v
   if (typeof n !== 'number' || !Number.isInteger(n) || n < 0)
-    throw new Error(`vx/turbo-cache: ${name} must be whole seconds ≥ 0, got ${JSON.stringify(v)}`)
+    throw new Error(`turboCache(): ${name} must be whole seconds ≥ 0, got ${JSON.stringify(v)}`)
   return n * 1000
 }
 
@@ -428,6 +439,19 @@ async function boundedText(res: Response, max: number): Promise<string | null> {
  */
 const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
 
+/** A lent token ending sooner than this is exchanged again first, so an agent's request never carries a spent one. */
+const LEND_MARGIN_MS = 5 * 60_000
+
+/** Statuses of a server that has no batch query. */
+const NO_BATCH = new Set([404, 405, 501])
+
+/**
+ * The most hashes one batch query may carry: Vercel answers more with 400
+ * "Too many hashes. Limit is 100." (main f71b377 asked 107 at once, and
+ * the run planned as if none were held).
+ */
+const BATCH_MAX = 100
+
 /**
  * The seam implementation: `has` is HEAD, `hasMany` is the batch query,
  * `get`/`put` carry `x-artifact-duration` (and the tag when signing). An
@@ -458,14 +482,27 @@ export class TurboRemoteCache implements RemoteCacheLayer {
    * entry is immutable, so any other key is asked first.
    */
   private readonly absent = new Set<string>()
+  /**
+   * Keys whose GET this process answered 200. Core saves a key after its
+   * hit only when that hit did not restore (bad bytes, a tag that does not
+   * verify), so `put` sends it over the stored one: its HEAD saw 200 and
+   * kept the bad entry for every later run.
+   */
+  private readonly served = 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
+  /** The tokens OIDC exchanges gave, the last one current, each revoked when the run ends. */
+  private exchanged: string[] = []
+  /** When the current exchanged token ends (epoch ms), when the server said. */
+  private expiresAt: number | undefined
+  /** Set by `open` when this machine has a lent token and no token of its own: read per request. */
+  private borrowed: (() => string | undefined) | undefined
+  /** The token a run running its tasks here lent (`CacheContext.lent`). */
+  lent: (() => string | undefined) | undefined
   private readonly keychainRemote: KeychainRemote
   /** The remote's rate limit, which every request of this client waits out. */
   private readonly cooldown = new Cooldown()
@@ -480,39 +517,72 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     private readonly maxSignedBody: number = MAX_SIGNED_BODY,
   ) {
     this.key = config.signatureKey === undefined ? undefined : Buffer.from(config.signatureKey)
-    this.endpoint = `${config.apiUrl}/v8/artifacts`
+    this.endpoint = `${config.url}/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),
+      label: remoteLabel(config.url, team),
       env: 'TURBO_TOKEN',
     }
   }
 
   async open(ctx: RemoteOpenContext): Promise<void> {
-    if (this.config.oidcMissing)
+    const lent = this.lent?.() === undefined ? undefined : this.lent
+    if (this.config.oidcMissing && lent === undefined)
       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
+    // A lent token beats this machine's own OIDC: the server files a write
+    // by the token, so an agent's own (another workflow, another ref)
+    // filed the task where its run could not read it.
+    if (lent !== undefined) {
+      this.borrowed = lent
+      return
+    }
     if (this.config.oidc !== undefined) {
       try {
-        this.token = await exchangeOidc(this.config.oidc, this.fetchImpl, this.wait)
+        await this.exchange()
       } 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 async exchange(): Promise<void> {
+    const got = await exchangeOidc(this.config.oidc!, this.fetchImpl, this.wait)
+    this.token = got.token
+    this.expiresAt = got.expiresAt
+    this.exchanged.push(got.token)
+  }
+
+  /**
+   * The token an OIDC exchange gave this run, for a machine that runs its
+   * tasks (`RemoteCacheLayer.lend`); exchanged again when it ends within
+   * five minutes. A token of any other kind is never lent.
+   */
+  async lend(): Promise<LentAccess | undefined> {
+    if (this.exchanged.length === 0) return undefined
+    if (this.expiresAt !== undefined && this.expiresAt - Date.now() < LEND_MARGIN_MS)
+      await this.exchange()
+    return {
+      token: this.token!,
+      ...(this.expiresAt === undefined ? {} : { expiresAt: this.expiresAt }),
+    }
+  }
+
+  private bearer(): string | undefined {
+    return this.borrowed?.() ?? this.token
+  }
+
   private url(pathname: string): string {
-    const u = new URL(`${this.config.apiUrl}/v8/artifacts${pathname}`)
+    const u = new URL(`${this.config.url}/v8/artifacts${pathname}`)
     // Turbo sends a team id only in Vercel's `team_` form (its API client's
     // `add_team_params`); a personal account's owner id is not one, and the
     // signature, which folds the id as given, is unaffected.
@@ -523,7 +593,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
 
   private headers(extra: Record<string, string> = {}, auth = true): Record<string, string> {
     return {
-      ...(auth ? { Authorization: `Bearer ${this.token}` } : {}),
+      ...(auth ? { Authorization: `Bearer ${this.bearer()}` } : {}),
       'x-artifact-client-interactive': process.stdout.isTTY ? '1' : '0',
       ...extra,
     }
@@ -531,7 +601,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
 
   /**
    * Turbo's preflight: an `OPTIONS` to the request's URL names the method
-   * and headers to come; the answer's `Location` (relative to `apiUrl`) is
+   * and headers to come; the answer's `Location` (relative to `url`) is
    * where the request goes, as given — a signed storage URL signs its own
    * query, so nothing is appended — and the token goes along only when
    * `Access-Control-Allow-Headers` admits `Authorization` (or `*`), so it
@@ -550,7 +620,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     const res = await this.fetchImpl(url, {
       method: 'OPTIONS',
       headers: {
-        Authorization: `Bearer ${this.token}`,
+        Authorization: `Bearer ${this.bearer()}`,
         'Access-Control-Request-Method': method === 'HEAD' ? 'GET' : method,
         'Access-Control-Request-Headers': ['Authorization', ...Object.keys(headers)].join(', '),
       },
@@ -561,7 +631,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     const location = res.headers.get('location')
     const allowed = res.headers.get('access-control-allow-headers') ?? ''
     return {
-      url: location === null ? url : new URL(location, this.config.apiUrl).toString(),
+      url: location === null ? url : new URL(location, this.config.url).toString(),
       auth:
         allowed.trim() === '*' ||
         allowed.split(',').some((h) => h.trim().toLowerCase() === 'authorization'),
@@ -579,7 +649,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
+    if (this.bearer() === undefined) return undefined
     const timeoutMs = init.timeoutMs ?? this.config.timeoutMs
     // 0 is Turbo's "no deadline".
     const signal = () => (timeoutMs === 0 ? undefined : deadline(timeoutMs))
@@ -611,30 +681,32 @@ export class TurboRemoteCache implements RemoteCacheLayer {
       const first = !this.writesRefused
       this.writesRefused = true
       if (!first) return undefined
+      // The status and the server's own words (`refusal`): a scope it
+      // refuses and a token it no longer takes read alike.
       throw new Error(
-        'HTTP 403: the upload was refused (a read-only token or server); uploads off for this run, reads go on',
+        `${(await refusal(res)).message}: the upload was refused (a read-only token or server); uploads off for this run, reads go on`,
       )
     }
     if (res.status === 401 || res.status === 403) {
       const first = !this.disabled
       this.disabled = true
       if (!first) return undefined
+      const said = (await refusal(res)).message
       if (this.forget === undefined)
-        throw new Error(`HTTP ${res.status}: the token was refused; remote cache off for this run`)
+        throw new Error(`${said}: 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`,
+        `${said}: 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. */
+  /** Revoke each token this run 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)
+    const tokens = this.exchanged.splice(0)
+    for (const token of tokens)
+      await revokeOidc(this.config.oidc!, token, this.fetchImpl, this.wait)
   }
 
   async has(hash: string): Promise<ArtifactInfo | null> {
@@ -650,26 +722,66 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     throw new Error(`HTTP ${res.status}`)
   }
 
+  /**
+   * Null when the layer is off: no answer, which core keeps apart from
+   * "none held" (an empty map rewrote every key it asked as a miss in
+   * `remote_hits`, and the next run fetched none of them).
+   */
   async hasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
-    if (this.disabled || hashes.length === 0) return this.disabled ? new Map() : null
+    if (this.disabled || hashes.length === 0) return null
+    if (hashes.length <= BATCH_MAX) return this.batch(hashes)
+    const parts = await Promise.all(
+      Array.from({ length: Math.ceil(hashes.length / BATCH_MAX) }, (_, i) =>
+        this.batch(hashes.slice(i * BATCH_MAX, (i + 1) * BATCH_MAX)),
+      ),
+    )
+    if (parts.some((p) => p === null)) return null
+    return new Map(parts.flatMap((p) => [...p!]))
+  }
+
+  private async batch(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
     const res = await this.request('POST', '', {
       body: JSON.stringify({ hashes }),
       headers: { 'Content-Type': 'application/json', ...this.reads },
     })
-    if (res === undefined) return new Map()
-    if (res.status !== 200) return null
+    if (res === undefined) return null
+    if (res.status !== 200) {
+      // A server with no batch query (404, 405, 501) is asked per hash. Any
+      // other refusal was silent: main f71b377's probe gave no answer and no
+      // one could say why, and DTE sized the run as if every task ran.
+      if (NO_BATCH.has(res.status)) {
+        await res.body?.cancel()
+        return null
+      }
+      throw await refusal(res, 'batch query answered ')
+    }
     // An answer per hash is a few hundred bytes of ArtifactInfo; a reply
     // past this bound is no answer, read no further than the bound (L-9).
     const bound = hashes.length * 4096 + 64 * 1024
     const text = await boundedText(res, bound)
-    if (text === null) return null
-    const info = JSON.parse(text) as Record<string, unknown>
+    if (text === null) throw new Error(`batch query answered past ${bound} bytes; read no further`)
+    // A 200 that is no JSON object (a proxy's page, `null`, `[]`) threw a
+    // parser's line that named no query, or read as every hash absent:
+    // DTE sized the run as if every task ran.
+    let info: unknown
+    try {
+      info = JSON.parse(text)
+    } catch {
+      // quiet: refused below, with what came
+      info = undefined
+    }
+    if (typeof info !== 'object' || info === null || Array.isArray(info)) {
+      const said = text.replace(/\s+/g, ' ').trim().slice(0, 200)
+      throw new Error(
+        `batch query answered HTTP 200 with no JSON object${said === '' ? '' : `: ${said}`}`,
+      )
+    }
     // Each hash answers ArtifactInfo, null, or `{ error: { message } }`; an
     // error entry is not a stored artifact, and it was counted as one (a GET
     // spent on a 404, item 929).
     const held = new Map<string, ArtifactInfo>()
     for (const h of hashes) {
-      const v = info[h]
+      const v = (info as Record<string, unknown>)[h]
       if (typeof v !== 'object' || v === null || 'error' in v) this.absent.add(h)
       else {
         const { size, taskDurationMs } = v as { size?: unknown; taskDurationMs?: unknown }
@@ -688,13 +800,14 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     })
     if (res === undefined) return null
     if (res.status !== 200) {
-      await res.body?.cancel()
       if (res.status === 404) {
+        await res.body?.cancel()
         this.absent.add(hash)
         return null
       }
-      throw new Error(`HTTP ${res.status}`)
+      throw await refusal(res)
     }
+    this.served.add(hash)
     const duration = Number(res.headers.get('x-artifact-duration'))
     const durationMs = Number.isFinite(duration) && duration > 0 ? duration : undefined
     if (this.key === undefined) return { body: res, durationMs }
@@ -742,9 +855,14 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     return new Response(unlinkingStream(temp))
   }
 
-  async put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void> {
-    if (this.disabled || this.writesRefused) return
-    if (!this.absent.has(hash)) {
+  missing(hash: string): void {
+    this.absent.add(hash)
+  }
+
+  async put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void | false> {
+    // Nothing sent, so no upload is counted.
+    if (this.disabled || this.writesRefused) return false
+    if (!this.absent.has(hash) && !this.served.has(hash)) {
       // Part of the upload, so under its deadline. Any answer but 200 or 404
       // uploads: a lost store costs more. A server the HEAD cannot reach
       // fails the put, as the PUT would.
@@ -752,7 +870,8 @@ export class TurboRemoteCache implements RemoteCacheLayer {
         headers: this.reads,
         timeoutMs: this.config.uploadTimeoutMs,
       })
-      if (head === undefined || head.status === 200) return
+      if (head === undefined) return false
+      if (head.status === 200) return
       if (head.status === 404) this.absent.add(hash)
     }
     const headers: Record<string, string> = {
@@ -768,11 +887,12 @@ export class TurboRemoteCache implements RemoteCacheLayer {
       headers,
       timeoutMs: this.config.uploadTimeoutMs,
     })
-    if (res === undefined) return
+    if (res === undefined) return false
     // Turbo's client takes any 2xx (`error_for_status`); a server's 201 or
     // 204 stored the artifact and was counted a failed upload.
-    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    if (!res.ok) throw await refusal(res)
     this.absent.delete(hash)
+    this.served.delete(hash)
   }
 }
 
@@ -784,6 +904,7 @@ function localConfigOf(root: string): TurboLocalConfig {
   let raw: unknown
   try {
     raw = JSON.parse(readFileSync(path.join(root, '.turbo', 'config.json'), 'utf8'))
+    // quiet: a local config file: none read is none linked
   } catch {
     return {}
   }
@@ -803,12 +924,22 @@ function remoteCacheOf(root: string): TurboJsonRemoteCache {
     let text: string
     try {
       text = readFileSync(path.join(root, name), 'utf8')
+      // quiet: a local config file: none read is none declared
     } catch {
       continue
     }
     try {
-      const rc = (Bun.JSONC.parse(text) as { remoteCache?: unknown } | null)?.remoteCache
-      return typeof rc === 'object' && rc !== null ? (rc as TurboJsonRemoteCache) : {}
+      const json = Bun.JSONC.parse(text) as {
+        remoteCache?: unknown
+        futureFlags?: { longerSignatureKey?: unknown }
+      } | null
+      const rc = json?.remoteCache
+      const longerSignatureKey = json?.futureFlags?.longerSignatureKey
+      return {
+        ...(typeof rc === 'object' && rc !== null ? (rc as TurboJsonRemoteCache) : {}),
+        ...(longerSignatureKey === undefined ? {} : { longerSignatureKey }),
+      }
+      // quiet: a local config file: none read is none declared
     } catch {
       return {}
     }
@@ -818,7 +949,7 @@ function remoteCacheOf(root: string): TurboJsonRemoteCache {
 
 /** Each option `TurboCacheOptions` names, with its kind: derived from the type, so the two cannot drift. */
 const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
-  apiUrl: 'string',
+  url: 'string',
   token: 'string',
   teamId: 'string',
   teamSlug: 'string',
@@ -831,18 +962,44 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
   scope: 'string',
 }
 
+/**
+ * The number options, refused at the call: in the `cache` hook a laptop
+ * with no remote named passed what failed the first CI run.
+ */
+function refuseBadNumbers(options: TurboCacheOptions): void {
+  // A NaN never reaches the bound, and the request would be resent forever.
+  const { retries } = options
+  if (retries !== undefined && !(Number.isInteger(retries) && retries >= 0))
+    throw new UserError(`turboCache() option "retries" must be a whole number ≥ 0, got ${retries}`)
+  // 0 is no deadline, as Turbo reads it; a negative or non-number one made
+  // AbortSignal.timeout throw on every request, and one past the longest
+  // timer aborted each as it started (Turbo's own env values are held).
+  for (const name of ['timeoutMs', 'uploadTimeoutMs'] as const) {
+    const ms = options[name]
+    if (ms !== undefined && !(ms >= 0 && ms <= MAX_TIMER_MS))
+      throw new UserError(
+        `turboCache() option "${name}" must be ms ≥ 0 (0: none) up to ${MAX_TIMER_MS}, got ${ms}`,
+      )
+  }
+}
+
 /**
  * Declare in `.vx/workspace.ts`; the local store stays the floor beneath it:
  *
  * ```ts
- * plugins: [turboCache({ apiUrl: 'https://cache.example.com', token: process.env.CACHE_TOKEN })]
+ * plugins: [turboCache({ url: 'https://cache.example.com', token: process.env.CACHE_TOKEN })]
  * ```
  *
  * 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)
-  const scope = remoteScope('turbo-cache', options.scope)
+  refuseBadNumbers(options)
+  // At the call too, as vxCache() checks its url: in the hook alone, a verb
+  // that opens no cache (`vx show`) took a url every run then failed on.
+  const url = options.url?.replace(/\/+$/, '')
+  if (url) checkRemoteUrl(url, 'turboCache() option "url"')
+  const scope = remoteScope('turboCache', options.scope)
   // 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, {
@@ -852,6 +1009,7 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
         Bun.env,
         remoteCacheOf(ctx.workspaceRoot),
         localConfigOf(ctx.workspaceRoot),
+        (m) => ctx.warn(`[vx] plugin '@vzn/vx-migrate': ${m}`),
       )
       if (config === undefined) return undefined
       // A signed download waits in a temp until its tag checks: in vx's
@@ -859,6 +1017,7 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
       // sandboxed task may read (L-45).
       const layer = new TurboRemoteCache(config, fetch, ctx.cacheDir)
       layer.reads = readScopes(ctx.refs)
+      layer.lent = ctx.lent
       if (config.oidc !== undefined) opened = { layer, warn: ctx.warn }
       return scope === 'key' ? keyedByRef(layer, ctx.refs) : layer
     },