@vzn/vx-migrate 0.0.594 → 0.0.596

package/src/nx/nx-upstream.ts

@@ -20,6 +20,7 @@ import type { GeneratedTask, ProjectMeta } from '@vzn/vx'
 import { emptyNxInputs, expandNxInputs, type NxInputs } from './nx-inputs.js'
 import { nxProjectOutputs } from './nx-outputs.js'
 import { matchNxProjects } from './nx-deps.js'
+import { literalGlob } from '../glob-grammar.js'
 
 interface GraphNode {
   name?: string
@@ -192,7 +193,9 @@ export function planNxUpstream(
     const inputs = emptyNxInputs()
     for (const g of own.files) {
       const neg = g.startsWith('!') ? '!' : ''
-      inputs.wsFiles.push(rel === '' ? g : `${neg}${rel}/${neg === '' ? g : g.slice(1)}`)
+      inputs.wsFiles.push(
+        rel === '' ? g : `${neg}${literalGlob(rel)}/${neg === '' ? g : g.slice(1)}`,
+      )
     }
     inputs.wsFiles.push(...own.wsFiles)
     inputs.envNames.push(...own.envNames)

package/src/nx-cache/index.ts

@@ -21,6 +21,7 @@ import {
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadlineNamed } from '../remote-deadline.js'
+import { OutageBreaker } from '../remote-breaker.js'
 import { withRetry } from '../remote-retry.js'
 import { headerValueFault } from '../remote-token.js'
 
@@ -102,6 +103,7 @@ export function resolveNxCacheConfig(
  */
 export class NxRemoteCache implements RemoteCacheLayer {
   private disabled = false
+  private readonly breaker = new OutageBreaker()
   /**
    * A `403` on a write is the spec's read-only token (a CI's pull-request
    * token): uploads stop, reads go on. Read as a refused token, it turned
@@ -140,19 +142,23 @@ export class NxRemoteCache implements RemoteCacheLayer {
       // every hit read as a corrupt artifact (nx#33092).
       headers['Accept'] = 'application/octet-stream'
     }
-    const res = await withRetry(
-      () =>
-        this.fetchImpl(`${this.config.server}/v1/cache/${hash}`, {
-          method,
-          headers,
-          ...(body === undefined ? {} : { body }),
-          signal: AbortSignal.timeout(this.config.timeoutMs),
-        }),
-      this.config.retries,
-      this.wait,
-    ).catch((err: unknown) => {
-      throw deadlineNamed(err, this.config.timeoutMs)
-    })
+    const res = await this.breaker
+      .send(() =>
+        withRetry(
+          () =>
+            this.fetchImpl(`${this.config.server}/v1/cache/${hash}`, {
+              method,
+              headers,
+              ...(body === undefined ? {} : { body }),
+              signal: AbortSignal.timeout(this.config.timeoutMs),
+            }),
+          this.config.retries,
+          this.wait,
+        ),
+      )
+      .catch((err: unknown) => {
+        throw deadlineNamed(err, this.config.timeoutMs)
+      })
     if (method === 'PUT' && res.status === 403) {
       const first = !this.writesRefused
       this.writesRefused = true
@@ -166,7 +172,7 @@ export class NxRemoteCache implements RemoteCacheLayer {
       this.disabled = true
       if (!first) return undefined
       throw new Error(
-        `HTTP ${res.status}: ${res.status === 401 ? 'missing or invalid token' : 'access forbidden (a read-only token cannot write)'}; remote cache off for this run`,
+        `HTTP ${res.status}: ${res.status === 401 ? 'missing or invalid token' : 'access forbidden (the token may not read)'}; remote cache off for this run`,
       )
     }
     return res

package/src/nx-env.cjs

@@ -25,7 +25,10 @@
 const { spawn, spawnSync } = require('node:child_process')
 const { createRequire } = require('node:module')
 const path = require('node:path')
-const { loadTaskEnv } = require('./nx-dotenv.cjs')
+const { realpathSync } = require('node:fs')
+// Through npm's `.bin` symlink under `--preserve-symlinks-main`, Node keeps
+// the link as the main module, so a relative require would look in `.bin`.
+const { loadTaskEnv } = require(path.join(path.dirname(realpathSync(__filename)), 'nx-dotenv.cjs'))
 
 // `--envFile`, Nx's own option name, and not `--env-file`: Node 22 takes
 // `--env-file` from anywhere on its command line, the script's arguments

package/src/nx-exec.cjs

@@ -21,7 +21,10 @@
 
 const { createRequire, enableCompileCache } = require('node:module')
 const path = require('node:path')
-const { loadTaskEnv } = require('./nx-dotenv.cjs')
+const { realpathSync } = require('node:fs')
+// Through npm's `.bin` symlink under `--preserve-symlinks-main`, Node keeps
+// the link as the main module, so a relative require would look in `.bin`.
+const { loadTaskEnv } = require(path.join(path.dirname(realpathSync(__filename)), 'nx-dotenv.cjs'))
 
 // Nx's module graph is ~150 ms of every executed task; Node's on-disk
 // compile cache (22.1+, a no-op below) takes ~30 of them back on the

package/src/remote-breaker.ts

@@ -0,0 +1,60 @@
+/**
+ * Turbo's outage breaker (`turborepo-cache/src/outage_breaker.rs`): three
+ * outages in a row — no connection, no answer in time, or a 5xx once the
+ * retries are spent — open it for 30 s, and while open no request is sent.
+ * After the cooldown one request probes; its success closes the breaker,
+ * its outage opens it again. Without it a server that hung cost every
+ * task its full deadline. A result that lands after the breaker moved on
+ * (a request already in flight when it opened) changes nothing. Shared by
+ * `turboCache()` and `nxCache()`.
+ */
+export class OutageBreaker {
+  private failures = 0
+  private openUntil: number | undefined
+  private probing = false
+  private generation = 0
+  constructor(private readonly now: () => number = Date.now) {}
+
+  async send(request: () => Promise<Response>): Promise<Response> {
+    let probe = false
+    if (this.openUntil !== undefined) {
+      if (this.now() < this.openUntil || this.probing)
+        throw new Error(
+          `unavailable after ${FAILURE_THRESHOLD} failures in a row; not asked again for ${COOLDOWN_MS / 1000} s`,
+        )
+      this.probing = probe = true
+    }
+    const generation = this.generation
+    let res: Response
+    try {
+      res = await request()
+    } catch (err) {
+      this.finish(generation, probe, true)
+      throw err
+    }
+    this.finish(generation, probe, res.status >= 500)
+    return res
+  }
+
+  private finish(generation: number, probe: boolean, outage: boolean): void {
+    if (generation !== this.generation) return
+    if (outage) {
+      this.failures++
+      if (probe || this.failures >= FAILURE_THRESHOLD) {
+        this.openUntil = this.now() + COOLDOWN_MS
+        this.probing = false
+        this.generation++
+      }
+      return
+    }
+    this.failures = 0
+    if (probe) {
+      this.openUntil = undefined
+      this.probing = false
+      this.generation++
+    }
+  }
+}
+
+const FAILURE_THRESHOLD = 3
+const COOLDOWN_MS = 30_000

package/src/shared-outputs.ts

@@ -413,6 +413,8 @@ export function excludeWorkspaceOutputs(
     readonly dir: string
     readonly tasks: GeneratedTask[]
   }[],
+  /** The globs an opaque entry stands for (`vx-migrate`'s `...globalInputs` spread). */
+  expand: (entry: unknown) => readonly string[] = () => [],
 ): void {
   const positive = (v: unknown): string[] =>
     Array.isArray(v)
@@ -444,7 +446,7 @@ export function excludeWorkspaceOutputs(
         ?.inputs
       if (inputs === undefined || !Array.isArray(inputs.workspaceFiles)) continue
       const files = inputs.workspaceFiles as string[]
-      const reads = positive(files)
+      const reads = positive(files.flatMap((f) => (typeof f === 'string' ? [f] : expand(f))))
       if (reads.length === 0) continue
       for (const i of candidates(reads)) {
         const w = writers[i]!

package/src/spelled-env.ts

@@ -0,0 +1,36 @@
+// The env names a package's tracked source spells: what stands in, in a
+// written config, for a `*` env entry Turbo or Vite Task matched against
+// the environment a run sees.
+
+import path from 'node:path'
+import { relPosix } from './paths.js'
+
+/** Source and env-example files a framework build reads its variables from. */
+const SPELLS_ENV =
+  /\.(c|m)?(j|t)sx?$|\.(vue|svelte|astro|html)$|(^|\/)\.env\.(example|sample|template)$/
+
+/**
+ * The upper-case names the tracked source under `dirs` spells (`NEXT_PUBLIC_API`
+ * in `process.env.NEXT_PUBLIC_API` or an `.env.example`), sorted. Without
+ * git, none: the note still names the framework's prefix.
+ */
+export async function spelledNames(
+  root: string,
+  dirs: readonly string[],
+  tracked: readonly string[] | null,
+): Promise<string[]> {
+  if (tracked === null) return []
+  const prefixes = dirs.map((dir) => {
+    const rel = relPosix(root, dir)
+    return rel === '' || rel === '.' ? '' : `${rel}/`
+  })
+  const names = new Set<string>()
+  for (const f of tracked) {
+    if (!SPELLS_ENV.test(f) || !prefixes.some((p) => f.startsWith(p))) continue
+    const text = await Bun.file(path.join(root, f))
+      .text()
+      .catch(() => '')
+    for (const m of text.matchAll(/\b[A-Z][A-Z0-9_]*_[A-Z0-9_]+\b/g)) names.add(m[0])
+  }
+  return [...names].sort()
+}

package/src/tracked-outputs.ts

@@ -9,7 +9,7 @@
 
 import { lstat, readFile } from 'node:fs/promises'
 import path from 'node:path'
-import { outputsOverlap } from '@vzn/vx'
+import { isLiteralPattern, outputsOverlap } from '@vzn/vx'
 
 /** The files git tracks under `root`, root-relative; null outside a repo or without git. */
 export async function trackedFiles(root: string): Promise<string[] | null> {
@@ -216,6 +216,27 @@ export function spareTrackedOutputs(
   tracked: readonly string[],
 ): [string, string][] {
   const todos: [string, string][] = []
+  const trackedSet = new Set(tracked)
+  /** Drop the `!` entries readers carry for a committed file no output names any more. */
+  const unhide = (owner: (typeof projects)[number] | null, rooted: string) => {
+    for (const q of projects) {
+      const qrel = path.relative(root, q.dir).split(path.sep).join('/')
+      for (const r of q.tasks) {
+        const inputs = (r.task?.['cache'] as { inputs?: Outputs } | undefined)?.inputs
+        if (inputs === undefined) continue
+        const own =
+          q === owner &&
+          Array.isArray(inputs.files) &&
+          (qrel === '' || rooted.startsWith(`${qrel}/`))
+            ? rooted.slice(qrel === '' ? 0 : qrel.length + 1)
+            : undefined
+        if (own !== undefined)
+          inputs.files = (inputs.files as unknown[]).filter((g) => g !== `!${own}`)
+        if (Array.isArray(inputs.workspaceFiles))
+          inputs.workspaceFiles = inputs.workspaceFiles.filter((g) => g !== `!${rooted}`)
+      }
+    }
+  }
   for (const p of projects) {
     const rel = path.relative(root, p.dir).split(path.sep).join('/')
     const own = rel === '' ? tracked : filesUnder(tracked, rel).map((f) => f.slice(rel.length + 1))
@@ -229,7 +250,20 @@ export function spareTrackedOutputs(
       ] as const) {
         const globs = outputs[key]
         if (!Array.isArray(globs) || globs.length === 0) continue
-        const strings = globs.filter((g): g is string => typeof g === 'string')
+        let strings = globs.filter((g): g is string => typeof g === 'string')
+        // An output naming one committed file (eslint's
+        // `eslint-suppressions.json`) is a source: its `!` would take the
+        // whole entry back, so the entry goes, and so does the `!` a
+        // reader's inputs got for it, or every reader ran uncached (hono).
+        const rootedOf = (g: string) => (key === 'files' && rel !== '' ? `${rel}/${g}` : g)
+        const sources = new Set(
+          strings.filter((g) => isLiteralPattern(g) && trackedSet.has(rootedOf(g))),
+        )
+        if (sources.size > 0) {
+          strings = strings.filter((g) => !sources.has(g.startsWith('!') ? g.slice(1) : g))
+          outputs[key] = strings
+          for (const g of sources) unhide(key === 'files' ? p : null, rootedOf(g))
+        }
         const hit = coveredTracked(strings, base)
         if (hit.length > 0) hits.push([key, strings, hit])
       }

package/src/turbo/turbo-map.ts

@@ -13,7 +13,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { pruneOrphanPersistentNotes, type ProjectMeta, UserError } from '@vzn/vx'
-import { minimatchToVx, withoutTakenBack } from '../glob-grammar.js'
+import { literalGlob, minimatchToVx, withoutTakenBack } from '../glob-grammar.js'
 import { shellQuote } from '../nx-command.js'
 import { scriptCommand, yarnPnp } from '../script-command.js'
 import {
@@ -65,6 +65,8 @@ interface TurboJson {
   envMode?: unknown
 }
 
+const SHELL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
 /** A name core takes in `cache.inputs.env` and `exec.env.passThrough`. */
 const keyable = (name: string): boolean =>
   name.length > 0 && !name.startsWith('!') && !/[*?[\]{}=\0]/.test(name)
@@ -842,7 +844,7 @@ function rootDependencyGlobs(
   const out: string[] = []
   for (const name of seen) {
     const rel = relPosix(root, byName.get(name)!.dir)
-    if (rel !== '' && rel !== '.') out.push(`${rel}/**`)
+    if (rel !== '' && rel !== '.') out.push(`${literalGlob(rel)}/**`)
   }
   return out.sort()
 }
@@ -1110,22 +1112,15 @@ export async function mapTurboWorkspace(
       // A name no package has a script for is an entry point of its own:
       // `turbo run ci` over `ci: { dependsOn: ["lint", "build"] }`, or
       // cal.com's `deploy` → `@calcom/web#build`, runs its edges, and vx
-      // said no project declares it. Its `pkg#task` edges stay in that
-      // package alone: core's `--filter`/`--affected` reach follows a task
-      // edge across packages, and cal.com's `deploy` in all 116 would have
-      // made every package a dependent of web.
+      // said no project declares it. With no edge left (documenso's `lint`,
+      // shadcn-ui's `check`) Turbo still runs a no-op node per package and
+      // exits 0, so a CI step `vx run lint` must too. Its `pkg#task` edges
+      // stay in that package alone: core's `--filter`/`--affected` reach
+      // follows a task edge across packages, and cal.com's `deploy` in all
+      // 116 would have made every package a dependent of web.
       else if (!scripted.has(name)) {
-        const kept = entryEdges(def?.dependsOn ?? [], meta.name, rootMeta?.name)
-        const keeps = kept.some((d) => {
-          if (envDependency(d) !== null || d.includes('$TURBO_ROOT$')) return false
-          if (d.startsWith('^'))
-            return d !== `^${name}` && [...runnable.values()].some((r) => r.has(d.slice(1)))
-          return d !== name && (own.has(d) || defined.has(d))
-        })
-        if (keeps) {
-          emitted.get(meta.name)!.add(name)
-          entry.add(`${meta.name}#${name}`)
-        }
+        emitted.get(meta.name)!.add(name)
+        entry.add(`${meta.name}#${name}`)
       }
     }
   }
@@ -1495,7 +1490,14 @@ export async function mapTurboWorkspace(
     )
   literalEnvGapsOnce(projects, notes)
   resolveSharedWorkspaceOutputs(root, projects)
-  excludeWorkspaceOutputs(root, projects)
+  // A written config spreads the preset (`...globalInputs`), which the
+  // take-back pass must read as its globs: unread, opencode's configs
+  // read `packages/plugin/**` with no `!packages/plugin/dist/**` and
+  // core refused to load them.
+  const opaque = new Map<string, readonly string[]>()
+  for (const e of opts.splice('inputs', globals.inputs))
+    if (typeof e !== 'string') opaque.set(JSON.stringify(e), globals.inputs)
+  excludeWorkspaceOutputs(root, projects, (e) => opaque.get(JSON.stringify(e)) ?? [])
   pruneUnreachedPersistentNotes(projects, metas, opts.persistentTodo)
   pruneOrphanPersistentNotes(projects, opts.persistentTodo)
   return { projects, notes, globals }
@@ -1730,7 +1732,7 @@ function buildTask(
   const climbed = (glob: string): string | null => {
     const body = glob.startsWith('!') ? glob.slice(1) : glob
     if (!body.startsWith('../')) return null
-    const anchored = path.posix.normalize(path.posix.join(pkgDir, body))
+    const anchored = path.posix.normalize(path.posix.join(literalGlob(pkgDir), body))
     if (anchored.startsWith('../')) return null
     return (glob.startsWith('!') ? '!' : '') + anchored
   }
@@ -1889,10 +1891,12 @@ function buildTask(
     spelled,
   )
 
+  // A name that is no shell identifier never reached a task (`sh` drops it)
+  // and core refuses it in passThrough.
   const passThrough = uniq(
     [...global('env'), ...global('pass'), ...envNames, ...passNames],
     hidden('env', 'pass'),
-  )
+  ).filter((n) => typeof n !== 'string' || SHELL_NAME.test(n))
 
   const exec: Record<string, unknown> = { command }
   if (passThrough.length > 0) exec.env = { passThrough }

package/src/turbo-cache/index.ts

@@ -25,6 +25,7 @@ import {
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadlineNamed } from '../remote-deadline.js'
+import { OutageBreaker } from '../remote-breaker.js'
 import { withRetry } from '../remote-retry.js'
 import { headerValueFault } from '../remote-token.js'
 
@@ -55,6 +56,12 @@ export interface TurboCacheOptions {
   uploadTimeoutMs?: number
   /** Resends of a request answered 429 / 5xx or never connected (default 1, Turbo's); 0 turns them off. */
   retries?: number
+  /**
+   * Send Turbo's preflight (`OPTIONS`) before each artifact request and
+   * follow its `Location`, or `TURBO_PREFLIGHT` / turbo.json's
+   * `remoteCache.preflight`; default off.
+   */
+  preflight?: boolean
 }
 
 /** turbo.json's `remoteCache` block: the source below Turbo's environment, as in Turbo. */
@@ -66,6 +73,7 @@ export interface TurboJsonRemoteCache {
   enabled?: unknown
   timeout?: unknown
   uploadTimeout?: unknown
+  preflight?: unknown
 }
 
 /** `.turbo/config.json`'s fields, under any of the spellings Turbo accepts. */
@@ -85,6 +93,7 @@ export interface TurboCacheConfig {
   timeoutMs: number
   uploadTimeoutMs: number
   retries: number
+  preflight: boolean
 }
 
 /** Turbo's signature message prefix (`crates/turborepo-cache/src/signature_authentication.rs`). */
@@ -250,18 +259,14 @@ export function resolveTurboCacheConfig(
     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') ??
+    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 signEnv = env['TURBO_SIGNATURE']
-  let signing = file.signature === true
-  if (signEnv !== undefined && signEnv !== '') {
-    if (!/^(1|0|true|false)$/.test(signEnv))
-      throw new Error(
-        `vx/turbo-cache: TURBO_SIGNATURE should be 1 or 0, got ${JSON.stringify(signEnv)}`,
-      )
-    signing = signEnv === '1' || signEnv === 'true'
-  }
+  const signing = truthy(env['TURBO_SIGNATURE'], 'TURBO_SIGNATURE') ?? file.signature === true
   const signatureKey =
     options.signatureKey ?? (signing ? env['TURBO_REMOTE_CACHE_SIGNATURE_KEY'] : undefined)
   if (signatureKey !== undefined) {
@@ -303,9 +308,18 @@ export function resolveTurboCacheConfig(
       seconds(file.uploadTimeout, 'remoteCache.uploadTimeout') ??
       60_000,
     retries,
+    preflight,
   }
 }
 
+/** Turbo's `truth_env_var`: 1/true, 0/false; unset or empty is `undefined`. */
+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)}`)
+  return v === '1' || v === 'true'
+}
+
 /**
  * Turbo's timeout, whole seconds, as ms; `undefined` when unset. A value
  * Turbo would refuse is refused here rather than read as some other wait.
@@ -353,7 +367,8 @@ const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
  * The seam implementation: `has` is HEAD, `hasMany` is the batch query,
  * `get`/`put` carry `x-artifact-duration` (and the tag when signing). An
  * auth failure (401/403) throws ONCE — LayeredCache reports it — and then
- * turns the layer off for the rest of the process, so a bad token costs one
+ * turns the layer off for the rest of the process (an upload's 403 turns off
+ * uploads alone: the read-only token), so a bad token costs one
  * line, not one per task — the requests already in flight when it lands
  * degrade in silence rather than repeating it.
  *
@@ -364,6 +379,14 @@ const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
  */
 export class TurboRemoteCache implements RemoteCacheLayer {
   private disabled = false
+  private readonly breaker = new OutageBreaker()
+  /**
+   * A `403` on an upload is a read-only token or server
+   * (turborepo-remote-cache's `READ_ONLY` and its JWTs without the write
+   * scope): uploads stop, reads go on. Read as a refused token, it turned
+   * the reads off too, and every task after the first upload missed.
+   */
+  private writesRefused = false
   private readonly key: Uint8Array | undefined
   readonly endpoint: string
   constructor(
@@ -388,14 +411,50 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     return u.toString()
   }
 
-  private headers(extra: Record<string, string> = {}): Record<string, string> {
+  private headers(extra: Record<string, string> = {}, auth = true): Record<string, string> {
     return {
-      Authorization: `Bearer ${this.config.token}`,
+      ...(auth ? { Authorization: `Bearer ${this.config.token}` } : {}),
       'x-artifact-client-interactive': process.stdout.isTTY ? '1' : '0',
       ...extra,
     }
   }
 
+  /**
+   * 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
+   * 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
+   * never reaches a third-party store. The answer's status is not read, as
+   * in Turbo.
+   */
+  private async preflight(
+    url: string,
+    method: string,
+    headers: Record<string, string>,
+    signal: () => AbortSignal | undefined,
+  ): Promise<{ url: string; auth: boolean }> {
+    const s = signal()
+    const res = await this.fetchImpl(url, {
+      method: 'OPTIONS',
+      headers: {
+        Authorization: `Bearer ${this.config.token}`,
+        'Access-Control-Request-Method': method === 'HEAD' ? 'GET' : method,
+        'Access-Control-Request-Headers': ['Authorization', ...Object.keys(headers)].join(', '),
+      },
+      ...(s === undefined ? {} : { signal: s }),
+    })
+    await res.body?.cancel()
+    const location = res.headers.get('location')
+    const allowed = res.headers.get('access-control-allow-headers') ?? ''
+    return {
+      url: location === null ? res.url || url : new URL(location, this.config.apiUrl).toString(),
+      auth:
+        allowed.trim() === '*' ||
+        allowed.split(',').some((h) => h.trim().toLowerCase() === 'authorization'),
+    }
+  }
+
   /**
    * `undefined` = the token was refused and the refusal is ALREADY
    * reported, so the caller degrades to its miss value in silence. Only the
@@ -408,20 +467,41 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     init: { body?: Blob | string; headers?: Record<string, string>; timeoutMs?: number } = {},
   ): Promise<Response | undefined> {
     const timeoutMs = init.timeoutMs ?? this.config.timeoutMs
-    const res = await withRetry(
-      () =>
-        this.fetchImpl(this.url(pathname), {
-          method,
-          headers: this.headers(init.headers),
-          ...(init.body === undefined ? {} : { body: init.body }),
-          // 0 is Turbo's "no deadline".
-          ...(timeoutMs === 0 ? {} : { signal: AbortSignal.timeout(timeoutMs) }),
-        }),
-      this.config.retries,
-      this.wait,
-    ).catch((err: unknown) => {
-      throw deadlineNamed(err, timeoutMs)
-    })
+    // 0 is Turbo's "no deadline".
+    const signal = () => (timeoutMs === 0 ? undefined : AbortSignal.timeout(timeoutMs))
+    // The batch query is never preflighted, as in Turbo.
+    const preflight = this.config.preflight && method !== 'POST'
+    const res = await this.breaker
+      .send(() =>
+        withRetry(
+          async () => {
+            const extra = init.headers ?? {}
+            const to = preflight
+              ? await this.preflight(this.url(pathname), method, extra, signal)
+              : { url: this.url(pathname), auth: true }
+            const s = signal()
+            return this.fetchImpl(to.url, {
+              method,
+              headers: this.headers(extra, to.auth),
+              ...(init.body === undefined ? {} : { body: init.body }),
+              ...(s === undefined ? {} : { signal: s }),
+            })
+          },
+          this.config.retries,
+          this.wait,
+        ),
+      )
+      .catch((err: unknown) => {
+        throw deadlineNamed(err, timeoutMs)
+      })
+    if (method === 'PUT' && res.status === 403) {
+      const first = !this.writesRefused
+      this.writesRefused = true
+      if (!first) return undefined
+      throw new Error(
+        'HTTP 403: 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
@@ -520,7 +600,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   }
 
   async put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void> {
-    if (this.disabled) return
+    if (this.disabled || this.writesRefused) return
     const headers: Record<string, string> = {
       'Content-Type': 'application/octet-stream',
       'Content-Length': String(body.size),
@@ -535,7 +615,9 @@ export class TurboRemoteCache implements RemoteCacheLayer {
       timeoutMs: this.config.uploadTimeoutMs,
     })
     if (res === undefined) return
-    if (res.status !== 200 && res.status !== 202) throw new Error(`HTTP ${res.status}`)
+    // 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}`)
   }
 }
 
@@ -620,6 +702,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
   timeoutMs: 'number',
   uploadTimeoutMs: 'number',
   retries: 'number',
+  preflight: 'boolean',
 }
 
 /**