@vzn/vx-migrate 0.0.643 → 0.0.645

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

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

package/package.json

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

package/src/adoption-plugin.ts

@@ -60,7 +60,7 @@ export function adoptionPlugin(
   mapRun: (ctx: ProjectHookContext) => Promise<AdoptionRun>,
   reads: readonly string[] = [],
   // `config`: a workspace-wide key of the adopted tool's (nx.json `parallel`,
-  // Turbo's `cacheMaxSize`) that the workspace itself leaves unset.
+  // Turbo's `concurrency`) that the workspace itself leaves unset.
   // `discover`: a project the tool has that no member glob lists.
   stages: Pick<VxPlugin, 'config' | 'discover'> = {},
 ): VxPlugin {

package/src/glob-grammar.ts

@@ -1,28 +1,22 @@
-// The glob grammar Nx and Turbo share and vx's own differ in brackets and
-// extglobs; both adapters translate through here (items 914, 1031).
+// The glob grammar Nx and Turbo share and vx's own differ in extglobs;
+// both adapters translate through here (items 914, 1031).
 
 const EXTGLOB = /([?@+*!])\(([^()]*)\)/g
 
 /**
  * A minimatch-family glob (Nx's minimatch, Turbo's wax) in vx's grammar,
- * or null when it has no safe form. vx has no character classes (a bracket is a literal, for route
- * dirs, item 667) and no extglobs, so `src/**\/*.[jt]s` matched nothing
- * and Nx's own default `production` negation,
- * `?(*.)+(spec|test).[jt]s?(x)`, excluded nothing (item 914):
- * - `[jt]` is the brace set `{j,t}`, plus the literal `[jt]` itself in a
- *   positive glob (a superset of inputs is safe; the route dir may be
- *   meant); a range within digits or one case of letters (`[a-c]`,
- *   `[0-9]`) is its members;
- * - a negated class (`[!a]`) is `?` in a positive glob, a superset;
+ * or null when it has no safe form. Character classes pass through (vx
+ * reads them the same way); vx has no extglobs, so Nx's own default
+ * `production` negation, `?(*.)+(spec|test).[jt]s?(x)`, excluded nothing
+ * (item 914):
  * - `?(a|b)` is `{a,b,}` and `@(a|b)` is `{a,b}`;
  * - `+(a|b)` and `*(a|b)` narrow to one repetition, which only a
  *   NEGATION may do — it then excludes fewer files, never more;
- * - any other range, a negated class in a negation, `!(…)`, or nesting is
- *   null.
+ * - `!(…)` or nesting is null.
  */
 export function minimatchToVx(glob: string, negated: boolean): string | null {
-  if (!/[[(]/.test(glob)) return glob
-  let out = glob.replace(EXTGLOB, (whole, kind: string, body: string) => {
+  if (!glob.includes('(')) return glob
+  const out = glob.replace(EXTGLOB, (_whole, kind: string, body: string) => {
     const alts = body.split('|')
     if (alts.some((a) => /[{},]/.test(a))) return '\0'
     if (kind === '?') return `{${alts.join(',')},}`
@@ -30,36 +24,7 @@ export function minimatchToVx(glob: string, negated: boolean): string | null {
     if (!negated || kind === '!') return '\0'
     return kind === '+' ? `{${alts.join(',')}}` : `{${alts.join(',')},}`
   })
-  if (out.includes('\0') || /[?@+*!]\(/.test(out)) return null
-  out = out.replace(/\[([^\]]*)\]/g, (whole, body: string) => {
-    if (body === '' || /[{},/]/.test(body)) return '\0'
-    if (/^[!^]/.test(body)) return negated || body.length === 1 ? '\0' : '?'
-    const chars = classMembers(body)
-    if (chars === null) return '\0'
-    return negated ? `{${chars.join(',')}}` : `{${whole},${chars.join(',')}}`
-  })
-  return out.includes('\0') ? null : out
-}
-
-const RANGES = ['0123456789', 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ']
-
-/** A class body's characters, ranges spelled out; null for a range across kinds or backwards. */
-function classMembers(body: string): string[] | null {
-  const out = new Set<string>()
-  for (let i = 0; i < body.length; i++) {
-    const c = body[i]!
-    // A `-` first or last is itself, as in minimatch.
-    if (body[i + 1] === '-' && i + 2 < body.length) {
-      const end = body[i + 2]!
-      const kind = RANGES.find((r) => r.includes(c))
-      const from = kind?.indexOf(c) ?? -1
-      const to = kind?.indexOf(end) ?? -1
-      if (kind === undefined || to < from) return null
-      for (const m of kind.slice(from, to + 1)) out.add(m)
-      i += 2
-    } else out.add(c)
-  }
-  return [...out]
+  return out.includes('\0') || /[?@+*!]\(/.test(out) ? null : out
 }
 
 /**
@@ -73,7 +38,7 @@ function classMembers(body: string): string[] | null {
  */
 export function withoutTakenBack<T>(entries: readonly T[]): T[] {
   const list = [...new Set(entries)]
-  const wild = /[*?{}]/
+  const wild = /[*?{}[\]\\]/
   const negative = list.flatMap((e) =>
     typeof e === 'string' && e.startsWith('!') ? [e.slice(1)] : [],
   )
@@ -90,10 +55,10 @@ export function withoutTakenBack<T>(entries: readonly T[]): T[] {
 
 /**
  * A path from the file system as a task glob that names only itself: a dir
- * named `my{app}` read as a brace matched `myapp` instead. `[` `]` are
- * literal in a task glob already; `*` and `?` stay, since the schema reads
- * `\*` as a Windows separator, and they match the name too (a superset).
+ * named `my{app}` read as a brace matched `myapp` instead, and `app/[id]` a
+ * class. `*` and `?` stay, since the schema reads `\*` as a Windows
+ * separator, and they match the name too (a superset).
  */
 export function literalGlob(p: string): string {
-  return p.replace(/^!|[{}]/g, '\\$&')
+  return p.replace(/^!|[{}[\]]/g, '\\$&')
 }

package/src/migrate-nx.ts

@@ -5,7 +5,7 @@ import { stat } from 'node:fs/promises'
 import path from 'node:path'
 import { type GeneratedProject, type MigrationFormat, type MigrationPlan } from '@vzn/vx'
 import type { PackageMeta } from './packages.js'
-import { mapNxWorkspace, nxSizeText, parseNxGraph, readNxJson } from './nx/nx-map.js'
+import { mapNxWorkspace, parseNxGraph, readNxJson } from './nx/nx-map.js'
 import { spareTrackedOutputs, trackedFiles, trackedKinds } from './tracked-outputs.js'
 import { adoptedToolNotes } from './workspace-notes.js'
 import { relPosix } from './paths.js'
@@ -165,7 +165,7 @@ async function unlistedProjects(
 /** A `.vx/workspace.ts` field nx.json's run settings call for. */
 export interface NxWorkspaceField {
   /** The setting's path: its group, then its field, or a top-level key. */
-  readonly field: 'run.concurrency' | 'baseBranch' | 'cache.retention'
+  readonly field: 'run.concurrency' | 'baseBranch'
   /** The value as TypeScript source; undefined when vx cannot read it. */
   readonly source: string | undefined
   /** What to tell a user whose workspace file this run does not write. */
@@ -187,7 +187,6 @@ export function nxWorkspaceFields(json: Record<string, unknown> | undefined): Nx
         tasksRunnerOptions?: { default?: { options?: { parallel?: unknown } } }
         defaultBase?: unknown
         affected?: { defaultBase?: unknown }
-        maxCacheSize?: unknown
       }
     | undefined
   const out: NxWorkspaceField[] = []
@@ -207,12 +206,5 @@ export function nxWorkspaceFields(json: Record<string, unknown> | undefined): Nx
       note: `nx.json \`defaultBase\` ${JSON.stringify(base.trim())}: add \`baseBranch: ${JSON.stringify(branch)}\` to .vx/workspace.ts`,
     })
   }
-  const size = nxSizeText(nx?.maxCacheSize)
-  if (size !== undefined)
-    out.push({
-      field: 'cache.retention',
-      source: /^\d+[KMG]?B$/.test(size) ? `{ maxSize: ${quoted(size)} }` : undefined,
-      note: `nx.json \`maxCacheSize\`: add \`cache: { retention: { maxSize: ${JSON.stringify(size)} } }\` to .vx/workspace.ts`,
-    })
   return out
 }

package/src/nx/index.ts

@@ -39,7 +39,6 @@ import {
   mapNxWorkspace,
   type NxExecutors,
   type NxGraph,
-  nxSizeText,
   parseNxGraph,
   readNxJson,
 } from './nx-map.js'
@@ -166,11 +165,6 @@ export function nx(options: NxPluginOptions = {}): VxPlugin {
               rules: { ...workspace.run?.rules, dependencies },
             }
         }
-        if (workspace.cache?.retention === undefined) {
-          const maxSize = await nxMaxCacheSize(root)
-          if (maxSize !== undefined)
-            workspace.cache = { ...workspace.cache, retention: { maxSize } }
-        }
       },
       // The package manager's members are projects, each with no vx.config
       // written. An integrated Nx repo keeps projects out of that list
@@ -294,24 +288,6 @@ async function nxDefaultBase(root: string): Promise<string | undefined> {
   return typeof b === 'string' && b.trim() !== '' ? b.trim().replace(/^origin\//, '') : undefined
 }
 
-/**
- * nx.json's `maxCacheSize`, or `NX_MAX_CACHE_SIZE` above it, as core's
- * size: Nx caps its local cache there (`resolveMaxCacheSize`), and read by
- * nothing a capped cache grew without bound under vx, as turbo.json's
- * `cacheMaxSize` once did (G-49). 1024-based, a fraction truncated to
- * bytes; `0` is no cap. A value Nx would refuse is left to core's
- * refusal, which names the field.
- */
-async function nxMaxCacheSize(root: string): Promise<string | undefined> {
-  const env = process.env['NX_MAX_CACHE_SIZE']
-  const raw =
-    env !== undefined
-      ? env
-      : ((await readNxJson(root).catch(() => null))?.json as { maxCacheSize?: unknown } | undefined)
-          ?.maxCacheSize
-  return nxSizeText(raw)
-}
-
 interface LoadedGraph {
   readonly text: string
   readonly graph: NxGraph

package/src/nx/nx-map.ts

@@ -1522,20 +1522,3 @@ function followNxGraph(
     }
   }
 }
-
-/** Nx's cache-size grammar (`10GB`, `1.5 GB`, bare bytes) as core's size; `0` is no cap. */
-export function nxSizeText(raw: unknown): string | undefined {
-  if (typeof raw !== 'string' && typeof raw !== 'number') return undefined
-  const text = String(raw).trim()
-  const m = /^(\d+\.?\d*|\.\d+)\s?([KMG]?B)?$/.exec(text)
-  if (m === null) return text
-  const units = ['B', 'KB', 'MB', 'GB']
-  let n = Math.floor(Number(m[1]) * 1024 ** units.indexOf(m[2] ?? 'B'))
-  if (n === 0) return undefined
-  let u = 0
-  while (u < units.length - 1 && n % 1024 === 0) {
-    n /= 1024
-    u++
-  }
-  return `${n}${units[u]}`
-}

package/src/nx-cache/index.ts

@@ -227,15 +227,16 @@ export class NxRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  async has(hash: string): Promise<boolean> {
+  async has(hash: string): Promise<{ size?: number } | null> {
     const res = await this.fetch(hash)
-    if (res === null) return false
+    if (res === null) return null
     await res.body?.cancel()
-    return true
+    const size = Number(res.headers.get('content-length') ?? NaN)
+    return Number.isFinite(size) ? { size } : {}
   }
 
-  // Nx's record carries no duration; the seam's `meta` is accepted and unused.
-  async put(hash: string, body: Blob, _meta: { durationMs: number }): Promise<void> {
+  // Nx's record carries no duration.
+  async put(hash: string, body: Blob): Promise<void> {
     if (this.disabled || this.writesRefused) return
     const res = await this.request('PUT', hash, body)
     if (res === undefined) return

package/src/turbo/index.ts

@@ -11,7 +11,7 @@
 import { readFileSync } from 'node:fs'
 import { availableParallelism } from 'node:os'
 import path from 'node:path'
-import type { ProjectMeta, VxPlugin, WorkspaceConfig } from '@vzn/vx'
+import type { ProjectMeta, VxPlugin } from '@vzn/vx'
 import type { PackageMeta } from '../packages.js'
 import { memberProjects, withManifests } from '../manifests.js'
 import { refuseUnknownOptions, type PluginOptionKinds } from '@vzn/vx'
@@ -65,14 +65,6 @@ export function turbo(options: TurboPluginOptions = {}): VxPlugin {
         const keys = await workspaceKeys(options.root ?? ctx.workspaceRoot)
         if (workspace.run?.concurrency === undefined && keys.concurrency !== undefined)
           workspace.run = { ...workspace.run, concurrency: keys.concurrency }
-        if (workspace.cache?.retention === undefined && keys.cacheRetention !== undefined)
-          workspace.cache = {
-            ...workspace.cache,
-            // `olderThan` is built with its unit below.
-            retention: keys.cacheRetention as NonNullable<
-              NonNullable<WorkspaceConfig['cache']>['retention']
-            >,
-          }
         // `turbo run --affected` compares with TURBO_SCM_BASE when set, and
         // on GitHub Actions with what the event names.
         const base =
@@ -99,36 +91,6 @@ export function turbo(options: TurboPluginOptions = {}): VxPlugin {
   )
 }
 
-/**
- * turbo.json's workspace keys vx has a home for, top level or under
- * `global`: `concurrency` (`"10"`, `"50%"` of the cores) and the local
- * cache's `cacheMaxSize` / `cacheMaxAge` (`"0"` is off; weeks become days).
- * Read by nothing, a repo that capped its cache at 10GB (formbricks) grew
- * it without bound under vx. A value core cannot parse is left to core's
- * refusal, which names the field.
- */
-const SIZE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB']
-
-/**
- * Turbo's size (turborepo-cache `parse_human_size`): 1024-based, a bare
- * number is bytes, a fraction is truncated to bytes. Core takes a whole
- * number with a unit, so `7.5GB` (langfuse) is restated as `7680MB` and
- * `1000000` as `1000000B`; core refused both. Undefined when Turbo reads
- * it as off (under one byte).
- */
-function turboSize(v: string): string | undefined {
-  const m = /^(\d+\.?\d*|\.\d+)([KMGT]?B)?$/i.exec(v)
-  if (!m) return v
-  let n = Math.floor(Number(m[1]) * 1024 ** SIZE_UNITS.indexOf((m[2] ?? 'B').toUpperCase()))
-  if (n === 0) return undefined
-  let u = 0
-  while (u < SIZE_UNITS.length - 1 && n % 1024 === 0) {
-    n /= 1024
-    u++
-  }
-  return `${n}${SIZE_UNITS[u]}`
-}
-
 const UNKNOWN_SHA = '0'.repeat(40)
 
 /**
@@ -173,9 +135,12 @@ function githubActionsBase(root: string, remoteFallback: boolean): string | unde
   return before === '' ? undefined : before
 }
 
+/**
+ * turbo.json's workspace keys vx has a home for, top level or under
+ * `global`: `concurrency` (`"10"`, `"50%"` of the cores).
+ */
 async function workspaceKeys(root: string): Promise<{
   concurrency?: number
-  cacheRetention?: { maxSize?: string; olderThan?: string }
   remoteBaseFallback?: boolean
 }> {
   const file = await turboConfigFile(root)
@@ -199,7 +164,6 @@ async function workspaceKeys(root: string): Promise<{
   }
   const out: {
     concurrency?: number
-    cacheRetention?: { maxSize?: string; olderThan?: string }
     remoteBaseFallback?: boolean
   } = {}
   const flags = raw['futureFlags'] as { githubActionsRemoteBaseRefFallback?: unknown } | undefined
@@ -212,19 +176,6 @@ async function workspaceKeys(root: string): Promise<{
       : Number(c)
     if (Number.isInteger(n) && n > 0) out.concurrency = n
   }
-  const size = read('cacheMaxSize', 'TURBO_CACHE_MAX_SIZE')
-  const maxSize = size === undefined ? undefined : turboSize(size)
-  const age = read('cacheMaxAge', 'TURBO_CACHE_MAX_AGE')
-  // Turbo reads a bare number as days (`parse_human_duration`).
-  const olderThan = age
-    ?.replace(/^(\d+)w$/i, (_, w: string) => `${Number(w) * 7}d`)
-    .replace(/^\d+$/, (d) => `${d}d`)
-  if (maxSize !== undefined || olderThan !== undefined) {
-    out.cacheRetention = {
-      ...(maxSize !== undefined ? { maxSize } : {}),
-      ...(olderThan !== undefined ? { olderThan } : {}),
-    }
-  }
   return out
 }
 

package/src/turbo/turbo-map.ts

@@ -2023,9 +2023,9 @@ function buildTask(
         continue
       }
       const neg = i.startsWith('!')
-      // Turbo's globs have character classes and extglobs; a vx bracket is
-      // a literal, so `src/**/*.[jt]s` keyed on nothing and an edit
-      // replayed the old build (item 1031). A positive glob with no safe
+      // Turbo's globs have extglobs and vx's do not, so
+      // `src/**/*.@(js|ts)` keyed on nothing and an edit replayed the old
+      // build (item 1031). A positive glob with no safe
       // form widens to every package file; a negation with none is dropped
       // (it would exclude fewer files, never more).
       const wax = minimatchToVx(neg ? i.slice(1) : i, neg)
@@ -2103,19 +2103,16 @@ function buildTask(
   const zeroed = new Set<string>()
   const wsOutFiles: string[] = []
   for (const raw of def.outputs ?? []) {
-    // The first segment stays a literal (a route directory, item 667);
-    // the rest is Turbo's grammar: `dist/**/*.[cm]js` matched nothing, so
-    // a hit restored nothing (item 1031).
-    const cut = raw.indexOf('/')
-    const rest = cut < 0 ? null : minimatchToVx(raw.slice(cut + 1), raw.startsWith('!'))
-    if (cut >= 0 && rest === null) {
+    // Turbo's grammar: an extglob in `dist/**/*.@(js|mjs)` matched
+    // nothing, so a hit restored nothing (item 1031).
+    const mapped = minimatchToVx(raw, raw.startsWith('!'))
+    if (mapped === null) {
       todos.push(
         `output ${JSON.stringify(raw)}: glob syntax vx cannot take — task runs uncached; ` +
           'declare the exact outputs in a vx.config to cache it',
       )
       return { name, todos, task, uses }
     }
-    const mapped = cut < 0 ? raw : `${raw.slice(0, cut + 1)}${rest}`
     // A `!` output takes a path back, as Turbo's does (A-44): Next's
     // `.next/**` minus `!.next/cache/**` saved the cache and cleaned it
     // before every run while vx outputs could not exclude.

package/src/turbo-cache/index.ts

@@ -16,6 +16,7 @@ import { unlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import {
+  type ArtifactInfo,
   definePlugin,
   type RemoteCacheLayer,
   type RemoteOpenContext,
@@ -24,6 +25,7 @@ import {
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadline } from '../remote-deadline.js'
+import { keyedByRef, readScopes, remoteScope, type RemoteScope } from './scope.js'
 import { OutageBreaker } from '../remote-breaker.js'
 import { Cooldown, withRetry } from '../remote-retry.js'
 import {
@@ -80,6 +82,14 @@ export interface TurboCacheOptions {
    * `remoteCache.preflight`; default off.
    */
   preflight?: boolean
+  /**
+   * How branches stay apart (default `'header'`): every read names the run's
+   * refs in `x-artifact-read-scopes`, for a server that files writes by the
+   * CI token. `'key'` also folds the run's ref into each key and reads each
+   * ref's key in order, for a server that ignores the header. The server's
+   * OIDC policy alone decides where a write lands.
+   */
+  scope?: RemoteScope
 }
 
 /** turbo.json's `remoteCache` block: the source below Turbo's environment, as in Turbo. */
@@ -126,6 +136,17 @@ export const MIN_SIGNATURE_KEY_LENGTH = 32
 // Bun's own hasher and the global `crypto`, not `node:crypto`: importing that
 // module cost every `@vzn/vx-migrate` user 6.6 ms at startup, remote cache
 // or not (G-121).
+/** A size and a duration as the wire spells them (a header string, a JSON number), kept when they are counts. */
+function infoOf(size: unknown, durationMs: unknown): ArtifactInfo {
+  const count = (v: unknown): number | undefined => {
+    const n = typeof v === 'string' && v !== '' ? Number(v) : v
+    return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : undefined
+  }
+  const s = count(size)
+  const d = count(durationMs)
+  return { ...(s === undefined ? {} : { size: s }), ...(d === undefined ? {} : { durationMs: d }) }
+}
+
 function updateLength(mac: Bun.CryptoHasher, byteLength: number): void {
   const len = Buffer.alloc(8)
   len.writeBigUInt64LE(BigInt(byteLength))
@@ -448,6 +469,8 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   private readonly keychainRemote: KeychainRemote
   /** The remote's rate limit, which every request of this client waits out. */
   private readonly cooldown = new Cooldown()
+  /** Headers every read carries: the refs it may be answered from (`readScopes`). */
+  reads: Record<string, string> = {}
   constructor(
     private readonly config: TurboCacheConfig,
     private readonly fetchImpl: typeof fetch = fetch,
@@ -614,25 +637,26 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     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}`)
-    if (res === undefined) return false
-    if (res.status === 200) return true
+  async has(hash: string): Promise<ArtifactInfo | null> {
+    if (this.disabled) return null
+    const res = await this.request('HEAD', `/${hash}`, { headers: this.reads })
+    if (res === undefined) return null
+    if (res.status === 200)
+      return infoOf(res.headers.get('content-length'), res.headers.get('x-artifact-duration'))
     if (res.status === 404) {
       this.absent.add(hash)
-      return false
+      return null
     }
     throw new Error(`HTTP ${res.status}`)
   }
 
-  async hasMany(hashes: readonly string[]): Promise<Set<string> | null> {
-    if (this.disabled || hashes.length === 0) return this.disabled ? new Set() : null
+  async hasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
+    if (this.disabled || hashes.length === 0) return this.disabled ? new Map() : null
     const res = await this.request('POST', '', {
       body: JSON.stringify({ hashes }),
-      headers: { 'Content-Type': 'application/json' },
+      headers: { 'Content-Type': 'application/json', ...this.reads },
     })
-    if (res === undefined) return new Set()
+    if (res === undefined) return new Map()
     if (res.status !== 200) return null
     // 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).
@@ -643,13 +667,15 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     // 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 Set(
-      hashes.filter((h) => {
-        const v = info[h]
-        return typeof v === 'object' && v !== null && !('error' in v)
-      }),
-    )
-    for (const h of hashes) if (!held.has(h)) this.absent.add(h)
+    const held = new Map<string, ArtifactInfo>()
+    for (const h of hashes) {
+      const v = info[h]
+      if (typeof v !== 'object' || v === null || 'error' in v) this.absent.add(h)
+      else {
+        const { size, taskDurationMs } = v as { size?: unknown; taskDurationMs?: unknown }
+        held.set(h, infoOf(size, taskDurationMs))
+      }
+    }
     return held
   }
 
@@ -658,7 +684,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     // A gateway that keys binary media on Accept base64-encodes a `*/*`
     // response, and every hit read as a corrupt artifact (nx#33092's class).
     const res = await this.request('GET', `/${hash}`, {
-      headers: { Accept: 'application/octet-stream' },
+      headers: { Accept: 'application/octet-stream', ...this.reads },
     })
     if (res === undefined) return null
     if (res.status !== 200) {
@@ -723,6 +749,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
       // uploads: a lost store costs more. A server the HEAD cannot reach
       // fails the put, as the PUT would.
       const head = await this.request('HEAD', `/${hash}`, {
+        headers: this.reads,
         timeoutMs: this.config.uploadTimeoutMs,
       })
       if (head === undefined || head.status === 200) return
@@ -801,6 +828,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
   retries: 'number',
   preflight: 'boolean',
   oidc: 'any',
+  scope: 'string',
 }
 
 /**
@@ -814,6 +842,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
  */
 export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
   refuseUnknownOptions('turboCache()', options, TURBO_CACHE_KEYS)
+  const scope = remoteScope('turbo-cache', 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, {
@@ -829,8 +858,9 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
       // cache directory, which the sandbox walls, not the shared temp dir a
       // sandboxed task may read (L-45).
       const layer = new TurboRemoteCache(config, fetch, ctx.cacheDir)
+      layer.reads = readScopes(ctx.refs)
       if (config.oidc !== undefined) opened = { layer, warn: ctx.warn }
-      return layer
+      return scope === 'key' ? keyedByRef(layer, ctx.refs) : layer
     },
     async teardown() {
       const run = opened

package/src/turbo-cache/scope.ts

@@ -0,0 +1,89 @@
+import type { ArtifactInfo, RemoteCacheLayer } from '@vzn/vx'
+
+/**
+ * How a remote keeps branches apart (2026-10-20). `'header'`: plain keys,
+ * and every read names the refs it may be answered from, in order, in
+ * `x-artifact-read-scopes`; a server that files writes by the caller's CI
+ * token reads them, any other ignores it. `'key'`: each entry's key also
+ * folds a ref, for a server that keeps one bucket; a read asks each ref's
+ * key and the first hit wins.
+ */
+export type RemoteScope = 'header' | 'key'
+
+export function remoteScope(name: string, scope: unknown): RemoteScope {
+  if (scope === undefined || scope === 'header' || scope === 'key') return scope ?? 'header'
+  throw new Error(`vx/${name}: scope must be 'header' or 'key', got ${JSON.stringify(scope)}`)
+}
+
+/** A server caps the read header at this many refs (the server rules), so vx never sends more. */
+const MAX_READ_SCOPES = 8
+
+/** The read header: the refs in order. Writes carry none: the server files them by the token. */
+export function readScopes(refs: readonly string[]): Record<string, string> {
+  return refs.length === 0
+    ? {}
+    : { 'x-artifact-read-scopes': refs.slice(0, MAX_READ_SCOPES).join(', ') }
+}
+
+/** The key `ref` stores `hash` under: 16 hex, task-key shaped, so every wire takes it. */
+export function refKey(ref: string, hash: string): string {
+  return Bun.hash.xxHash3(`vx-cache-ref\0${ref}\0${hash}`).toString(16).padStart(16, '0')
+}
+
+const QUEUE = /^refs\/heads\/gh-readonly-queue\//
+
+/**
+ * `inner` keyed by ref: a write lands under the run's own ref's key (a
+ * merge queue's, its base branch's, which its results become), a read asks
+ * each ref's key in order. A merge queue's own ref holds nothing, so it is
+ * never asked.
+ */
+export function keyedByRef(inner: RemoteCacheLayer, allRefs: readonly string[]): RemoteCacheLayer {
+  const refs = QUEUE.test(allRefs[0] ?? '') ? allRefs.slice(1) : allRefs
+  const write = refs[0]
+  if (write === undefined) return inner
+  /** Task key → the stored key a batch probe found it under. */
+  const found = new Map<string, string>()
+  const hasMany = inner.hasMany
+  const firstHeld = async (hash: string): Promise<ArtifactInfo | null> => {
+    const known = found.get(hash)
+    if (known !== undefined) return inner.has(known)
+    for (const ref of refs) {
+      const info = await inner.has(refKey(ref, hash))
+      if (info !== null) return info
+    }
+    return null
+  }
+  return {
+    ...(inner.endpoint !== undefined ? { endpoint: inner.endpoint } : {}),
+    ...(inner.open !== undefined ? { open: (ctx) => inner.open!(ctx) } : {}),
+    has: firstHeld,
+    ...(hasMany !== undefined
+      ? {
+          hasMany: async (hashes) => {
+            const keys = hashes.map((h) => refs.map((r) => refKey(r, h)))
+            const held = await hasMany.call(inner, keys.flat())
+            if (held === null) return null
+            const out = new Map<string, ArtifactInfo>()
+            hashes.forEach((h, i) => {
+              const key = keys[i]!.find((k) => held.has(k))
+              if (key === undefined) return
+              found.set(h, key)
+              out.set(h, held.get(key)!)
+            })
+            return out
+          },
+        }
+      : {}),
+    get: async (hash) => {
+      const known = found.get(hash)
+      if (known !== undefined) return inner.get(known)
+      for (const ref of refs) {
+        const hit = await inner.get(refKey(ref, hash))
+        if (hit !== null) return hit
+      }
+      return null
+    },
+    put: (hash, body, meta) => inner.put(refKey(write, hash), body, meta),
+  }
+}