@vzn/vx 0.0.642 → 0.0.644

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'
@@ -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/cli/workspace-config.ts

@@ -15,7 +15,7 @@ import {
   lockOfDiscovery,
   lockReader,
 } from '../orchestrator/index.js'
-import type { VxPlugin } from '../orchestrator/index.js'
+import type { BranchFacts, VxPlugin } from '../orchestrator/index.js'
 import {
   buildPackageGraph,
   type ProjectEntry,
@@ -27,6 +27,8 @@ import {
 interface CliWorkspace {
   workspaceConfig: WorkspaceConfig | null
   plugins: readonly VxPlugin[]
+  /** What a plugin's `config` stage said of the branch: its cache scope and base commit. */
+  branch: BranchFacts
   cacheDir: string
   /** The shared store a run opens `cacheDir` with (`resolveStoreRoot`), asked on load. */
   storeRoot: Promise<string | null>
@@ -37,10 +39,14 @@ export const warnToStderr = (message: string): void => {
 }
 
 export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorkspace> {
-  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warnToStderr)
+  const { workspaceConfig, plugins, branch } = await loadWorkspacePlugins(
+    workspaceRoot,
+    warnToStderr,
+  )
   return {
     workspaceConfig,
     plugins,
+    branch,
     cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig),
     storeRoot: resolveStoreRoot(workspaceRoot, workspaceConfig),
   }

package/src/config.ts

@@ -14,6 +14,13 @@ export type Duration = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`
  * Nothing here is folded into a cache key.
  */
 export interface WorkspaceConfig {
+  /**
+   * The repository's default branch (`'develop'`). A run on it has no
+   * cache scope and a bare `--affected` has no default; elsewhere both
+   * compare with the merge base of `origin/<baseBranch>` and HEAD.
+   * Omitted → `origin/HEAD`'s branch, then `main`, then `master`.
+   */
+  baseBranch?: string
   run?: RunSettings
   cache?: CacheSettings
   lock?: LockSettings
@@ -42,13 +49,6 @@ export interface RunSettings {
    * `schedule` plugin's weights still come first; this breaks their ties.
    */
   schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
-  /**
-   * The git ref a bare `--affected` compares with (`origin/develop`).
-   * `--affected=<base>` overrides it. Omitted → `origin/HEAD`, then the
-   * first of `origin/main`, `origin/master`, `main`, `master` that is not
-   * HEAD, else `HEAD~1`.
-   */
-  affectedBase?: string
   /**
    * A task's time limit, for tasks without their own `exec.timeout` (which
    * beats every run-level source). A runaway-process guard: a timed-out
@@ -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.
@@ -95,15 +86,6 @@ export interface CacheSettings {
    * first, then each remote in declared order.
    */
   policy?: string
-  /**
-   * Where this run's cache writes land. Omitted, a run reads and writes the
-   * default keys. A name (`'pr-123'`) reads the default key first, then the
-   * scope's, and writes only the scope's, so a PR never writes what the
-   * default branch reads. Whether a run writes at all is `policy`'s call.
-   * A client-side convention, not a security boundary: the boundary is a
-   * cache token the server limits.
-   */
-  scope?: string
   /** Which remote hits land on disk: `all` (the default), only the requested tasks' (`toplevel`), or `none`. */
   download?: 'all' | 'toplevel' | 'none'
   /** The `cache.inputStability` of every task that does not set its own. */
@@ -116,6 +98,21 @@ 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`. `verify` (default `'stat'`): what a hit on plain files
+   * checks first, each file's size and mtime, every byte (`'hash'`), or
+   * nothing (`'none'`).
+   */
+  store?: { embeddings?: false | string; decompress?: boolean; verify?: 'stat' | 'hash' | 'none' }
+  /**
+   * 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`. */
@@ -795,7 +792,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'
 
@@ -46,6 +46,7 @@ export type {
 } from './config.js'
 export { defineProject, defineWorkspace } from './config.js'
 export { definePlugin, refuseUnknownOptions } from './orchestrator/index.js'
+export { branchCacheScope } from './workspace/index.js'
 
 // Programmatic engine API: run / plan / prepare (docs/cli.md § Programmatic
 // API). The graph primitives, the cache-key hashing seam and the git / host
@@ -83,6 +84,7 @@ export type {
   CacheLayer,
   PluginCache,
   RemoteCacheLayer,
+  RemoteKey,
   RemoteOpenContext,
   RunRecord,
   InvocationRecord,
@@ -171,6 +173,8 @@ export type {
   ScheduleHookContext,
   AdmitContext,
   WorkspaceHookContext,
+  ConfigContext,
+  BranchFacts,
   DiscoverContext,
   DiscoveredProject,
   PluginSetupContext,

package/src/orchestrator/affected-tasks.ts

@@ -41,6 +41,7 @@ const KEYED_BY_EVERY_TASK: ReadonlySet<string> = new Set(PROJECT_CONFIG_FILENAME
 function wholeProjects(
   changes: AffectedChanges,
   projects: ReadonlyMap<string, ProjectEntry>,
+  byKeys: boolean,
 ): Map<string, string | undefined> {
   // Each whole project, with the path no task claims when one did it.
   const whole = new Map<string, string | undefined>([...changes.whole].map((n) => [n, undefined]))
@@ -50,7 +51,7 @@ function wholeProjects(
       (t) => t.exec !== undefined && t.inputs !== undefined,
     )
     const unclaimed = (rel: string): boolean =>
-      KEYED_BY_EVERY_TASK.has(rel) || !keyed.some((t) => declaresInput(t, rel, null))
+      KEYED_BY_EVERY_TASK.has(rel) || (!byKeys && !keyed.some((t) => declaresInput(t, rel, null)))
     const rel = rels.find(unclaimed)
     if (rel !== undefined) whole.set(name, rel)
   }
@@ -99,8 +100,10 @@ export function affectedRoots(
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
   explain?: AffectedExplain,
+  /** Only what moves a key: a changed path no task declares reaches no task. */
+  byKeys = false,
 ): string[] {
-  const whole = wholeProjects(changes, projects)
+  const whole = wholeProjects(changes, projects, byKeys)
   const seeds = explain === undefined ? null : new Map<string, AffectedReason>()
   const through = explain === undefined ? null : new Map<string, string>()
   const inProject = (name: string, rel: string | undefined): AffectedReason => {
@@ -226,6 +229,24 @@ 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

@@ -50,6 +50,8 @@ export {
   type ScheduleHookContext,
   type AdmitContext,
   type WorkspaceHookContext,
+  type ConfigContext,
+  type BranchFacts,
   type DiscoverContext,
   type DiscoveredProject,
   type InstallPluginsArgs,
@@ -117,6 +119,8 @@ export {
   captureWorkspaceIdentity,
   currentBranch,
   detectCi,
+  localBranchScope,
+  resolveCacheScope,
 } from './run-context.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './run-context.js'
 export {

package/src/orchestrator/options.ts

@@ -90,8 +90,16 @@ export interface RunOptions {
    * saying it is not.
    */
   remoteRequested?: boolean
-  /** This run's `cache.scope` (the CLI's `--cache-scope`), above `VX_CACHE_SCOPE` and `.vx/workspace`. */
+  /** 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
@@ -122,6 +130,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/plugin-host.ts

@@ -9,6 +9,7 @@
 
 import path from 'node:path'
 import {
+  type BranchScope,
   type Cache,
   type CacheLayer,
   type CachePolicy,
@@ -34,7 +35,7 @@ import type {
   RunReport,
   ScheduleHookContext,
   VxPlugin,
-  WorkspaceHookContext,
+  ConfigContext,
 } from './plugin.js'
 import type { ProjectMeta } from '../workspace/index.js'
 
@@ -137,7 +138,7 @@ function assertEditedInPlace(
 export async function applyConfigHooks(
   plugins: readonly VxPlugin[],
   workspace: WorkspaceConfig,
-  ctx: WorkspaceHookContext,
+  ctx: ConfigContext,
   /** Runs after EACH plugin's edit, so a refusal can name the plugin that made it. */
   afterEach?: (plugin: VxPlugin) => void,
 ): Promise<void> {
@@ -555,6 +556,10 @@ 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
 }
 
 /**
@@ -569,7 +574,7 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, ...ctx } = host
+  const { localCache, policy, remotes, branch, uploadConcurrency, ...ctx } = host
   const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
@@ -586,7 +591,9 @@ export async function resolveCache(
     resolved.push(entry)
     remotes?.push(entry)
   }
-  return resolved.length === 0 ? localCache : new LayeredCache(localCache, resolved)
+  return resolved.length === 0
+    ? localCache
+    : new LayeredCache(localCache, resolved, branch, uploadConcurrency)
 }
 
 /** The plugin each resolved executor came from, so a hook of it that throws is named. */

package/src/orchestrator/plugin.ts

@@ -61,8 +61,10 @@ export interface VxPlugin {
    * The workspace config, before anything is derived from it (concurrency,
    * cacheDir, timeout, …). `plugins` is already fixed by the time this runs.
    * Core re-validates after each plugin, as it does a user's file.
+   * `ctx.setBranch` names what the CI knows of the branch: its cache scope
+   * and the commit it is compared with.
    */
-  config?(workspace: WorkspaceConfig, ctx: WorkspaceHookContext): void | Promise<void>
+  config?(workspace: WorkspaceConfig, ctx: ConfigContext): void | Promise<void>
 
   /**
    * Projects beyond the directories holding a vx.config, their names, and
@@ -340,6 +342,25 @@ export interface WorkspaceHookContext {
   warn(message: string): void
 }
 
+/**
+ * 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. `trusted`: the run has no scope, whatever git
+ * names, and reads and writes only the default keys (a merge queue's run,
+ * owner 2026-10-18). A later plugin's field wins.
+ */
+export interface BranchFacts {
+  scope?: string
+  base?: string
+  trusted?: boolean
+}
+
+export interface ConfigContext extends WorkspaceHookContext {
+  setBranch(facts: BranchFacts): void
+}
+
 export interface DiscoverContext extends WorkspaceHookContext {
   /** Where vx's cache lives: a plugin may keep what it read to answer here. */
   readonly cacheDir: string
@@ -485,7 +506,7 @@ 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` (`'pr-123'`), `undefined` when none. Core already keys a scoped run's
+   * 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.
    */