@vzn/vx 0.0.643 → 0.0.645

package/src/cli/plugin-templates.ts

@@ -10,7 +10,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   cache: {
     plugin:
-      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// core puts it behind the local cache, so a remote error is a miss and a\n// warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache() {\n      return new DirRemote(dir)\n    },\n  })\n}\n",
+      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// core puts it behind the local cache, so a remote error is a miss and a\n// warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type ArtifactInfo, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<ArtifactInfo | null> {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { size: file.size } : null\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache() {\n      return new DirRemote(dir)\n    },\n  })\n}\n",
     test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      inputs: { files: ['package.json'] }, cache: { outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx', 'cache'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
   },
   commands: {

package/src/cli/run.ts

@@ -109,6 +109,9 @@ const SETTING_OPTIONS = [
   ['run.retries', 'retries'],
   ['run.outputLogs', 'outputLogs'],
   ['cache.download', 'download'],
+  ['cache.concurrency.download', 'downloadConcurrency'],
+  ['cache.concurrency.upload', 'uploadConcurrency'],
+  ['cache.concurrency.restore', 'restoreConcurrency'],
 ] as const satisfies readonly (readonly [string, keyof RunOptions])[]
 
 /** `verb` is the one being parsed for: `vx watch` reads `vx run`'s flags, and
@@ -515,7 +518,6 @@ export async function resolveRunOptions(
   }
   if (parsed.profile !== undefined) opts.profile = parsed.profile
   // `--affected`'s base is the branch's for the cache scope too.
-  if (affectedFilter !== undefined) opts.scopeBase = affectedFilter.slice(4, -1)
 
   return opts
 }

package/src/cli/upgrade.ts

@@ -21,6 +21,7 @@ import { access, chmod, chown, link, mkdtemp, rename, rm, stat } from 'node:fs/p
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { UserError, sayNotice, ui } from '../util/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
 import { VERSION } from '../version.js'
 
 const REGISTRY = 'https://registry.npmjs.org'
@@ -474,7 +475,7 @@ function installedVersion(dir: string, pkg: string): string | undefined {
 }
 
 /** The project's package manager: its lockfile, then `packageManager`, then the tree's shape. */
-function projectManager(dir: string, execPath: string): ManagedInstall['manager'] {
+export function projectManager(dir: string, execPath: string): ManagedInstall['manager'] {
   for (let d = dir; ; d = path.dirname(d)) {
     if (existsSync(path.join(d, 'pnpm-lock.yaml'))) return 'pnpm'
     if (existsSync(path.join(d, 'bun.lock')) || existsSync(path.join(d, 'bun.lockb'))) return 'bun'
@@ -596,11 +597,11 @@ export async function upgradeManaged(
   version: string,
   current = VERSION,
   step = '',
-): Promise<void> {
+): Promise<boolean> {
   const plugins = install.plugins ?? []
   if (version === current && plugins.every((p) => installedVersion(install.cwd, p) === version)) {
     ui.print('out', ui.status('info', 'vx upgrade', `${step}already at ${current}`))
-    return
+    return false
   }
   const argv = upgradeArgv(install, version)
   // PATH as it is now: `Bun.which` alone reads the one the process started with.
@@ -636,6 +637,7 @@ export async function upgradeManaged(
       }`,
     )
   }
+  return true
 }
 
 /**
@@ -648,7 +650,7 @@ async function upgradeBinary(
   current = VERSION,
   step = '',
   key: SigningKey = NPM_SIGNING_KEY,
-): Promise<void> {
+): Promise<boolean> {
   const pkg = platformPackage()
   let installed: string | undefined
   const replaced = await replaceBinary(
@@ -679,6 +681,7 @@ async function upgradeBinary(
       ? ui.status('ok', 'vx upgrade', `${step}installed ${installed}`)
       : ui.status('info', 'vx upgrade', `${step}already at ${current}`),
   )
+  return replaced
 }
 
 /** The version `bin --version` answers, without the hand-off note a handed-off run adds. */
@@ -738,9 +741,9 @@ export async function upgradeOnlyGlobal(
 }
 
 /** `run`, its refusal naming `what` after the verb: a run that moves two installs says which failed. */
-async function named(what: string, run: () => Promise<void>): Promise<void> {
+async function named<T>(what: string, run: () => Promise<T>): Promise<T> {
   try {
-    await run()
+    return await run()
   } catch (err) {
     if (!(err instanceof UserError)) throw err
     throw new UserError(err.message.replace(/^vx upgrade: /, `vx upgrade: ${what}: `), err.code)
@@ -787,19 +790,46 @@ export async function upgradeCmd(argv: readonly string[]): Promise<number> {
   const from = handedOffFrom
   if (from !== undefined) {
     const version = await targetVersion(tag)
-    await named('project vx', () =>
+    const moved = await named('project vx', () =>
       install === null
         ? upgradeBinary(dest, version, VERSION, 'project ')
         : upgradeManaged(install, version, VERSION, 'project '),
     )
     await upgradeGlobal(from, version)
+    if (moved) await relock(newVx(install, dest))
     return 0
   }
-  if (install !== null) await upgradeManaged(install, await targetVersion(tag))
-  else await upgradeBinary(dest, versionSpec(tag))
+  const moved =
+    install !== null
+      ? await upgradeManaged(install, await targetVersion(tag))
+      : await upgradeBinary(dest, versionSpec(tag))
+  if (moved) await relock(newVx(install, dest))
   return 0
 }
 
+/**
+ * The vx an upgrade just installed: the replaced binary, or the project's
+ * `node_modules/.bin/vx` (a manager's store path names the old version).
+ */
+const newVx = (install: ManagedInstall | null, dest: string): string =>
+  install === null ? dest : path.join(install.cwd, 'node_modules', '.bin', 'vx')
+
+/**
+ * Lock the workspace with the vx just installed at `bin` (M, 2026-10-18):
+ * a release may record the lock differently. `-g` never re-locks. A lock
+ * that fails leaves the upgrade done and says what to run.
+ */
+export async function relock(bin: string, cwd = process.cwd()): Promise<void> {
+  const root = await findWorkspaceRoot(cwd).catch(() => null)
+  if (root === null) return
+  const proc = Bun.spawnSync({
+    cmd: [bin, 'lock'],
+    cwd: root,
+    stdio: ['inherit', 'inherit', 'inherit'],
+  })
+  if (proc.exitCode !== 0) sayNotice('warn', 'vx upgrade', 'vx lock failed: run vx lock')
+}
+
 /**
  * `bin --version` when it answers as vx within `timeoutMs`, else null. The
  * answer decides whether a replaced binary is rolled back, so it is

package/src/config.ts

@@ -79,15 +79,6 @@ export interface CacheSettings {
    * `.vx/cache` and its entries in the user's shared store.
    */
   dir?: string
-  /**
-   * Evict from the local cache at the end of every run, whatever its
-   * policy (a remote hit is ingested under any), by the same policy
-   * `vx cache clean` takes as flags: entries not used for `olderThan`
-   * (`'30d'`, `'12h'`), then least-recently-used entries until the cache
-   * is under `maxSize` (`'10GB'`, `'500MB'`). Either or both. Omitted →
-   * nothing is evicted unless you run `vx cache clean`.
-   */
-  retention?: { olderThan?: Duration; maxSize?: string }
   /**
    * Which layers a run reads and writes (`'local:rw,remote:r'`; a layer it
    * leaves out stays on); `--no-cache` and `--force` still apply on top.
@@ -107,6 +98,19 @@ export interface CacheSettings {
    * both (`'always'`). Only a run whose policy writes a remote keeps any.
    */
   upload?: { failures?: 'ci' | 'local' | 'always' }
+  /**
+   * How the local cache keeps an entry. `embeddings` (default `'32KiB'`):
+   * an entry up to this size inside the index; `false`, none. `decompress` (default true): a larger one as its
+   * plain files, which a hit copies or clones out with no decode; off, as
+   * one `.tar.zst`.
+   */
+  store?: { embeddings?: false | string; decompress?: boolean }
+  /**
+   * Cache transfers at once. `download` and `upload` (per remote) default
+   * to min(96, max(cores × 3, 64)); `restore`, local hits writing their
+   * outputs, to twice `run.concurrency`.
+   */
+  concurrency?: { download?: number; upload?: number; restore?: number }
 }
 
 /** `WorkspaceConfig.lock`. */
@@ -786,7 +790,6 @@ export function defineWorkspace<T extends WorkspaceConfig>(
         rules?: Known<At<At<T, 'run'>, 'rules'>, WorkspaceRules>
       }
       cache?: Known<At<T, 'cache'>, CacheSettings> & {
-        retention?: Known<At<At<T, 'cache'>, 'retention'>, NonNullable<CacheSettings['retention']>>
         inputStability?: Known<At<At<T, 'cache'>, 'inputStability'>, InputStability>
       }
       lock?: Known<At<T, 'lock'>, LockSettings>

package/src/exec/sandbox-paths.ts

@@ -16,8 +16,8 @@ import path from 'node:path'
  * move that spelling into the scan, which finds nothing before the task has
  * written, and turn a working grant into `Read-only file system`. The two
  * predicates answer different questions: whether a declaration must be
- * MATCHED against other declarations (495; `GLOB_WILDCARDS`, where a bracket
- * is literal since item 667), and whether a grant can be mounted (here).
+ * MATCHED against other declarations (495; `GLOB_WILDCARDS`), and whether a
+ * grant can be mounted (here).
  * Item 577 gave each question one spelling.
  */
 export const MOUNT_WILDCARDS = /[*?[\]]/

package/src/graph/scheduler.ts

@@ -239,6 +239,8 @@ export type ContinueMode = 'never' | 'deps-ok' | 'always'
 export interface ScheduleOptions {
   nodes: Map<string, TaskNode>
   concurrency: number
+  /** Restore-tier tasks at once; twice `concurrency` unset. */
+  restoreConcurrency?: number
   /**
    * An aborted run dispatches nothing further: every task not yet
    * started completes `aborted` (the ones in flight are being killed by
@@ -604,7 +606,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
   // the two lanes share its one slot, where a lane each let an 80 MB
   // restore run inside another task's execution (item 1103).
   let activeRestore = 0
-  const restoreConcurrency = 2 * concurrency
+  const restoreConcurrency = options.restoreConcurrency ?? 2 * concurrency
   const serial = concurrency === 1
   const execRoom = (): boolean => (serial ? active + activeRestore < 1 : active < concurrency)
   const restoreRoom = (): boolean =>

package/src/graph/task-graph.ts

@@ -4,6 +4,7 @@ import {
   checkIgnoreSync,
   ignoreProbes,
   isLiteralPattern,
+  literalPath,
   listedSync,
   normalizeGlob,
   relPosix,
@@ -915,15 +916,17 @@ export function outputsOverlap(rawA: string, rawB: string): boolean {
   // A built path proves overlap only between globs as written: a literal's
   // `/**` twin reads it as a directory, and `dist/types.d.ts` met
   // `dist/**/*.js` at `dist/types.d.ts/x.js`, a file no one can write.
-  const bothGlobs = !isLiteralPattern(rawA) && !isLiteralPattern(rawB)
+  const bothGlobs = literalPath(rawA) === null && literalPath(rawB) === null
   for (const a of asTrees([rawA])) {
     for (const b of asTrees([rawB])) {
-      if (isLiteralPattern(a) && isLiteralPattern(b)) {
-        if (a === b) return true
-      } else if (isLiteralPattern(a)) {
-        if (taskGlob(b).match(a)) return true
-      } else if (isLiteralPattern(b)) {
-        if (taskGlob(a).match(b)) return true
+      const la = literalPath(a)
+      const lb = literalPath(b)
+      if (la !== null && lb !== null) {
+        if (la === lb) return true
+      } else if (la !== null) {
+        if (taskGlob(b).match(la)) return true
+      } else if (lb !== null) {
+        if (taskGlob(a).match(lb)) return true
       } else if (a === b || covers(a, b) || covers(b, a) || (bothGlobs && witnessed(a, b)))
         return true
     }
@@ -1202,13 +1205,13 @@ function collideAcross(
  * found no match outside the head this cuts, and thousands once `\` and
  * `!` were left out (item 746).
  */
-const GLOB_HEAD_END = /[*?{}\\!]/
+const GLOB_HEAD_END = /[*?{}[\]\\!]/
 
 /** `firstSegment`'s answer for a glob that can start anywhere. */
 const ANYWHERE = ''
 
 /** Where a glob's first segment ends: a separator, or anything `GLOB_HEAD_END` stops at. */
-const FIRST_SEGMENT_END = /[*?{}\\!/]/
+const FIRST_SEGMENT_END = /[*?{}[\]\\!/]/
 
 const firstSegments = new Map<string, string>()
 
@@ -1315,8 +1318,9 @@ function overlapCandidates<T>(
     const s = sideOf?.(tasks[i]!) === true ? 1 : 0
     side.push(s)
     for (const tree of asTrees(globsOf(tasks[i]!) ?? [])) {
-      if (isLiteralPattern(tree)) {
-        literals.push([i, tree])
+      const lit = literalPath(tree)
+      if (lit !== null) {
+        literals.push([i, lit])
         continue
       }
       file(globs[s]!, tree, i)

package/src/index.ts

@@ -20,7 +20,7 @@ export { PLUGIN_HOOKS, type PluginHook } from './config.js'
 // the second, so the cgroup walk has one implementation.
 export { machineMemoryBytes, machineParallelism } from './util/index.js'
 // How core reads a task glob — its spelling, and which characters are
-// wildcards (`[` `]` are not; item 667) — for a plugin that turns declared
+// wildcards (`[` `]` and an escape are) — for a plugin that turns declared
 // outputs into something else (`@vzn/vx-reapi`'s literal `output_paths`).
 export { isLiteralPattern, normalizeGlob, restorableOutput } from './util/index.js'
 
@@ -83,8 +83,8 @@ export { Cache } from './cache/index.js'
 export type {
   CacheLayer,
   PluginCache,
+  ArtifactInfo,
   RemoteCacheLayer,
-  RemoteKey,
   RemoteOpenContext,
   RunRecord,
   InvocationRecord,

package/src/orchestrator/affected-tasks.ts

@@ -229,24 +229,6 @@ export function affectedRoots(
   return kept
 }
 
-/**
- * The tasks of `nodes` whose key the change can move (a branch's cache
- * scope, owner 2026-10-17): a changed path one of its inputs declares, a
- * whole project, or a task its closure holds. Unlike `--affected`, a path
- * no task declares (a README) reaches none: its key is the default
- * branch's, so it reads the default key.
- */
-export function keyedByChange(
-  nodes: ReadonlyMap<string, TaskNode>,
-  changes: AffectedChanges,
-  projects: ReadonlyMap<string, ProjectEntry>,
-  packageGraph: PackageGraph,
-): Set<string> {
-  return new Set(
-    affectedRoots(nodes, [...nodes.keys()], changes, projects, packageGraph, undefined, true),
-  )
-}
-
 /**
  * The requested tasks `--affected` keeps, in their order: one the user
  * named (`pkg#task`), one in a project another include selected outright

package/src/orchestrator/doctor.ts

@@ -18,7 +18,6 @@ import {
   isUserError,
   machineMemoryBytes,
   machineParallelism,
-  parseSize,
   treeBytes,
 } from '../util/index.js'
 import { vxPath } from '../handoff.js'
@@ -99,8 +98,6 @@ export interface InfoFacts {
     string,
     { value: string | number | boolean | null; source: 'env' | 'workspace' | 'default' }
   >
-  /** `cache.retention`, with `maxSize` in bytes; null when none is set. */
-  cacheRetention: { olderThan?: string; maxSize?: string; maxBytes?: number } | null
   orphans: { artifacts: number; bytes: number }
   runs24h: number
   hits24h: number
@@ -261,7 +258,6 @@ async function collectWorkspaceInfo(
     cacheEntries: stats.entryCount,
     cacheBytes: stats.totalBytes,
     settings: settingsFact(workspaceConfig),
-    cacheRetention: retentionFact(workspaceConfig),
     // A row-less artifact is indexed again only when its task asks for its
     // key; the rest only `vx cache clean` reclaims (after an upgrade's
     // schema reset, most often).
@@ -395,16 +391,3 @@ function settingsFact(config: WorkspaceConfig | null): InfoFacts['settings'] {
   }
   return out
 }
-
-function retentionFact(config: WorkspaceConfig | null): InfoFacts['cacheRetention'] {
-  const raw = (path: string): string | undefined =>
-    process.env[envName(path)] || (atPath(config, path) as string | undefined)
-  const olderThan = raw('cache.retention.olderThan')
-  const maxSize = raw('cache.retention.maxSize')
-  if (olderThan === undefined && maxSize === undefined) return null
-  return {
-    ...(olderThan !== undefined ? { olderThan } : {}),
-    // Validated before the run (env) or at load (workspace), so it parses.
-    ...(maxSize !== undefined ? { maxSize, maxBytes: parseSize(maxSize)! } : {}),
-  }
-}

package/src/orchestrator/execute-task.ts

@@ -335,7 +335,7 @@ async function restoreProbed(
 
 /**
  * A hit restored, or null when its artifact was removed after the probe (a
- * prune, another workspace's retention on a shared cache directory): a
+ * `vx cache clean`, here or for a workspace sharing the cache directory): a
  * miss. The restore has wiped the declared outputs by then; the run path
  * cleans them again and the task writes them.
  */

package/src/orchestrator/index.ts

@@ -120,6 +120,7 @@ export {
   currentBranch,
   detectCi,
   localBranchScope,
+  cacheRefs,
   resolveCacheScope,
 } from './run-context.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './run-context.js'

package/src/orchestrator/options.ts

@@ -92,14 +92,6 @@ export interface RunOptions {
   remoteRequested?: boolean
   /** This run's cache scope, above `VX_CACHE_SCOPE`, a plugin's and the branch's (an embedder's). */
   cacheScope?: string
-  /**
-   * What the branch changed, for a scoped run: the tasks whose key it can
-   * move read the scope's key, every other task the default key (one
-   * lookup each). Absent, the run diffs the branch from `scopeBase`.
-   */
-  scopeChanges?: AffectedChanges
-  /** The commit a scoped run diffs the branch from (`--affected`'s base); absent, a plugin's, else the merge base with the default branch. */
-  scopeBase?: string
   /**
    * The default policy's remote write is off (`remote:r`): the CLI passes it
    * off CI (`CI` unset, `0` or `false`) unless `--cache-policy` or
@@ -130,6 +122,12 @@ export interface RunOptions {
    * Locally-placed tasks always write in place and ignore this.
    */
   download?: 'all' | 'toplevel' | 'none'
+  /** Remote downloads at once (`cache.concurrency.download`). */
+  downloadConcurrency?: number
+  /** Uploads at once, per remote (`cache.concurrency.upload`). */
+  uploadConcurrency?: number
+  /** Local hits restoring at once (`cache.concurrency.restore`); twice `concurrency` unset. */
+  restoreConcurrency?: number
   /**
    * Run intent, derived by the CLI from selection flags: 'broad' iff
    * `--all` / `--filter` / `--affected` was passed, else 'focused'.

package/src/orchestrator/plan.ts

@@ -54,6 +54,8 @@ export interface PlannedTask {
    * eager task is the default and saying so on every line says nothing.
    */
   download?: 'deferred'
+  /** A remote hit's stored size, when the remote said it: what restoring it downloads. */
+  remoteBytes?: number
   /** Why `--affected` kept this requested task; absent without `--affected` and on a dependency it pulled in. */
   affected?: AffectedReason
 }
@@ -139,6 +141,7 @@ export interface PlanArgs {
  */
 export async function plan(args: PlanArgs): Promise<RunPlan> {
   const cacheStatusById = new Map<string, CacheStatus>()
+  const remoteBytesById = new Map<string, number>()
   // Keyed first, probed after: a remote that can batch (`hasMany`) is
   // asked once for every key, one that cannot is asked per key.
   const probed = new Map<string, string>()
@@ -191,13 +194,15 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     },
   })
   if (probed.size > 0) {
-    await args.cache.remoteHasMany?.([...new Set(probed.values())])
+    const infos = await args.cache.remoteHasMany?.([...new Set(probed.values())])
     for (const [id, hash] of probed) {
       const where = await args.cache.has(hash)
       cacheStatusById.set(
         id,
         where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local',
       )
+      const size = where === 'remote' ? infos?.get(hash)?.size : undefined
+      if (size !== undefined) remoteBytesById.set(id, size)
     }
   }
 
@@ -225,6 +230,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       deps: node.deps,
       ...(executor !== undefined ? { executor } : {}),
       ...(args.downloadOf?.(id) === 'deferred' ? { download: 'deferred' as const } : {}),
+      ...(remoteBytesById.has(id) ? { remoteBytes: remoteBytesById.get(id)! } : {}),
     })
   }
 

package/src/orchestrator/plugin-host.ts

@@ -9,7 +9,6 @@
 
 import path from 'node:path'
 import {
-  type BranchScope,
   type Cache,
   type CacheLayer,
   type CachePolicy,
@@ -556,8 +555,8 @@ export interface CacheHost extends CacheContext {
   readonly policy: CachePolicy
   /** Filled with each remote and what its policy lets it do, for the plugins' `ctx.cache`. */
   readonly remotes?: ResolvedRemote[]
-  /** The run's branch scope, which picks each remote key. */
-  readonly branch?: BranchScope
+  /** Uploads at once, per remote (`cache.concurrency.upload`). */
+  readonly uploadConcurrency?: number
 }
 
 /**
@@ -572,7 +571,7 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, branch, ...ctx } = host
+  const { localCache, policy, remotes, uploadConcurrency, ...ctx } = host
   const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
@@ -589,7 +588,9 @@ export async function resolveCache(
     resolved.push(entry)
     remotes?.push(entry)
   }
-  return resolved.length === 0 ? localCache : new LayeredCache(localCache, resolved, branch)
+  return resolved.length === 0
+    ? localCache
+    : new LayeredCache(localCache, resolved, uploadConcurrency)
 }
 
 /** The plugin each resolved executor came from, so a hook of it that throws is named. */

package/src/orchestrator/plugin.ts

@@ -346,12 +346,14 @@ export interface WorkspaceHookContext {
  * What a CI knows of the run's branch (owner, 2026-10-17): `scope`, the
  * cache scope (`'vznjs/vx:feat-x'`; `VX_CACHE_SCOPE` beats it, and it
  * beats the one git names), and `base`, the commit the branch is compared
- * with (a pull request's base), for a bare `--affected` and for which
- * tasks read the scope. A later plugin's field wins.
+ * with (a pull request's base), for a bare `--affected`. `trusted`: the
+ * run has no scope, whatever git names (a merge queue's run, owner
+ * 2026-10-18). The scope keys plugin entries only. A later plugin's field wins.
  */
 export interface BranchFacts {
   scope?: string
   base?: string
+  trusted?: boolean
 }
 
 export interface ConfigContext extends WorkspaceHookContext {
@@ -503,11 +505,16 @@ export interface ScheduleHookContext extends BaseContext {
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
 export interface CacheContext extends BaseContext {
   /**
-   * The run's cache scope (`'vznjs/vx:feat-x'`), `undefined` when none. Core already keys a scoped run's
-   * writes apart; a remote reads it to pick a credential or check a token's
-   * claims (an OIDC branch) for every call it makes.
+   * The run's cache scope (`'vznjs/vx:feat-x'`), `undefined` when none: what
+   * plugins' `ctx.cache` entries and stored runs are keyed apart by.
    */
   readonly scope: string | undefined
+  /**
+   * The refs the run reads, in order (`['refs/heads/feat-x', 'refs/heads/main']`):
+   * its own branch, the branch it merges into, the default branch. A remote
+   * keys or scopes its entries by them; core keys task entries by none.
+   */
+  readonly refs: readonly string[]
 }
 
 export interface OutputContext extends BaseContext {