@vzn/vx 0.0.644 → 0.0.645

package/src/cli/init.ts

@@ -1,8 +1,8 @@
 // `vx init [--dry [--format json]] [--force] [--mjs] [--native|--keep]` — a workspace from nowhere.
-// Core reads no package.json (M, 2026-10-14): a repo with one (package.json
-// scripts, Turbo, Nx) is `@vzn/vx-migrate`'s, which maps it and installs
-// what it writes (`migrate`); without one, the workspace file and an empty
-// root project are written here, then the lock (`starter`).
+// It installs vx globally and, where a package.json is, as its devDependency
+// (M, 2026-10-20). A Turbo or Nx repo is `@vzn/vx-migrate`'s, which maps it
+// and installs what it writes (`migrate`); any other gets the workspace file
+// and an empty root project, then the lock (`starter`).
 // `vx init --plugin <seam>` writes a runnable plugin for one seam and its
 // test instead (plugin-templates.ts, the examples the gate runs).
 
@@ -13,7 +13,14 @@ import { gitTop, workspaceFileWritten } from '../handoff.js'
 import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import { lockAfterMigration } from './lock.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
-import { isCompiledBinary, targetVersion } from './upgrade.js'
+import {
+  isCompiledBinary,
+  projectManager,
+  startedVersion,
+  targetVersion,
+  upgradeArgv,
+  type ManagedInstall,
+} from './upgrade.js'
 import { VERSION } from '../version.js'
 import { DOT_VX_GITATTRIBUTES, DOT_VX_GITIGNORE, ui, UserError, sayNotice } from '../util/index.js'
 import {
@@ -107,13 +114,96 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     dirs.push(d)
     if (d === top || path.dirname(d) === d) break
   }
-  const manifest = dirs.some((d) => MANIFESTS.some((f) => existsSync(path.join(d, f))))
-  if (manifest) return migrate(dirs, parsed)
-  return starter(marked ?? cwd, top === null, parsed)
+  if (dirs.some((d) => TOOL_CONFIGS.some((f) => existsSync(path.join(d, f))))) {
+    return migrate(dirs, parsed)
+  }
+  // The topmost package.json: a monorepo's root, wherever below it init ran.
+  const pkgRoot = dirs.findLast((d) => existsSync(path.join(d, 'package.json'))) ?? null
+  return starter(marked ?? pkgRoot ?? cwd, pkgRoot, top === null, parsed)
+}
+
+/** What makes a repo vx-migrate's to map: a Turbo or Nx config. */
+const TOOL_CONFIGS = ['turbo.json', 'turbo.jsonc', 'nx.json']
+
+/**
+ * The installs `vx init` runs (M, 2026-10-20): vx at `version` globally,
+ * with the manager that started init, so a bare `vx` is on PATH, unless
+ * the global vx already answers `version`; and, where `pkgRoot` has a
+ * package.json, as its devDependency with the repo's own manager.
+ */
+export function initInstalls(
+  version: string,
+  userAgent: string | undefined,
+  pkgRoot: string | null,
+  globalAt: string | undefined,
+  execPath = process.execPath,
+): { argv: string[]; cwd: string | null }[] {
+  const out: { argv: string[]; cwd: string | null }[] = []
+  if (globalAt !== version) {
+    const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1] ?? 'npm'
+    const manager = runner as ManagedInstall['manager']
+    out.push({ argv: upgradeArgv({ manager, scope: 'global', cwd: '' }, version), cwd: null })
+  }
+  if (pkgRoot !== null) {
+    const install: ManagedInstall = {
+      manager: projectManager(pkgRoot, execPath),
+      scope: 'project',
+      cwd: pkgRoot,
+      field: 'devDependencies',
+    }
+    out.push({ argv: upgradeArgv(install, version), cwd: pkgRoot })
+  }
+  return out
+}
+
+/** The version the global `vx` on PATH answers: not a runner's cache, not a project's bin. */
+function globalVersion(): string | undefined {
+  for (const dir of (process.env['PATH'] ?? '').split(path.delimiter)) {
+    const p = dir.split(path.sep).join('/')
+    if (p.includes('/_npx/') || /\/(bunx|dlx)-/.test(p) || p.includes('/node_modules/.bin'))
+      continue
+    const bin = path.join(dir, 'vx')
+    if (existsSync(bin)) return startedVersion(bin)?.split(' ')[1]
+  }
+  return undefined
 }
 
-/** What makes a repo vx-migrate's to map: a package manager's root, a Turbo or Nx config. */
-const MANIFESTS = ['package.json', 'pnpm-workspace.yaml', 'turbo.json', 'turbo.jsonc', 'nx.json']
+/**
+ * Run `initInstalls`, in order. A source checkout (0.0.0, which npm never
+ * had) installs nothing: the release would replace the code under test.
+ */
+async function install(pkgRoot: string | null, dry: boolean): Promise<string[]> {
+  if (VERSION === '0.0.0') return []
+  const version = await targetVersion(undefined, 'vx init')
+  const steps = initInstalls(
+    version,
+    process.env['npm_config_user_agent'],
+    pkgRoot,
+    globalVersion(),
+  )
+  if (dry) return steps.map((s) => s.argv.join(' '))
+  for (const s of steps) {
+    const bin = Bun.which(s.argv[0]!, { PATH: process.env['PATH'] ?? '' })
+    if (bin === null) {
+      throw new UserError(
+        `vx init: ${s.argv[0]} is not on PATH; run it yourself: ${s.argv.join(' ')}`,
+      )
+    }
+    ui.print(
+      'out',
+      ui.text([ui.cmd(s.argv.join(' ')), ui.dim(s.cwd === null ? '' : ` in ${s.cwd}`)]),
+    )
+    const proc = Bun.spawnSync({
+      cmd: [bin, ...s.argv.slice(1)],
+      cwd: s.cwd ?? process.cwd(),
+      stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    if (proc.exitCode !== 0) {
+      throw new UserError(`vx init: ${s.argv.join(' ')} failed (exit ${proc.exitCode})`)
+    }
+  }
+  return steps.map((s) => s.argv.join(' '))
+}
 
 /** Write `plugins/<seam>.ts` and its test under `root`: the workspace root, else the cwd. */
 async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promise<number> {
@@ -151,17 +241,23 @@ const PROJECT =
   "import { defineProject } from '@vzn/vx'\n\nexport default defineProject({ tasks: {} })\n"
 
 /**
- * No package.json: `.vx/workspace.ts` declaring no plugin and a root
- * `vx.config.ts` with no task, then the lock. `@vzn/vx` resolves to the
- * running vx (core-alias.ts), so the two load with nothing installed.
- * A file already here is kept; `--force` replaces it.
+ * No Turbo or Nx config: the installs, then `.vx/workspace.ts` declaring
+ * no plugin and a root `vx.config.ts` with no task, then the lock.
+ * `@vzn/vx` resolves to the running vx (core-alias.ts), so the two load
+ * whatever got installed. A file already here is kept; `--force` replaces it.
  */
-async function starter(root: string, noGit: boolean, args: InitArgs): Promise<number> {
+async function starter(
+  root: string,
+  pkgRoot: string | null,
+  noGit: boolean,
+  args: InitArgs,
+): Promise<number> {
   if (args.mode !== undefined) {
     throw new UserError(
-      `vx init: --${args.mode} answers a Turbo or Nx repo's question, and there is no package.json here`,
+      `vx init: --${args.mode} answers a Turbo or Nx repo's question, and there is no turbo.json or nx.json here`,
     )
   }
+  const installs = args.json === true || args.dry ? await install(pkgRoot, true) : []
   const ext = args.mjs ? 'mjs' : 'ts'
   const config = `vx.config.${ext}`
   const files: { path: string; contents: string }[] = []
@@ -185,16 +281,17 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
   ] as const) {
     if (!existsSync(path.join(root, name))) files.push({ path: name, contents })
   }
-  const vx = vxInvocation(process.env['npm_config_user_agent'], false)
+  const vx = VERSION === '0.0.0' ? vxInvocation(process.env['npm_config_user_agent'], false) : 'vx'
   const next = `${noGit ? 'git init, ' : ''}declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then ${vx} lock && ${vx} run <task>`
   if (args.json === true) {
     process.stdout.write(
-      `${JSON.stringify({ dry: true, source: 'no package.json', files, kept, replaced, todos: [], notes: [], next })}\n`,
+      `${JSON.stringify({ dry: true, source: 'no turbo.json or nx.json', files, kept, replaced, todos: [], notes: [], next, installs })}\n`,
     )
     return 0
   }
-  const rows: ui.FieldRow[] = [['from', 'no package.json: one project, the root']]
+  const rows: ui.FieldRow[] = [['from', 'no turbo.json or nx.json: one project, the root']]
   if (args.dry) rows.push(['dry run', 'nothing written'])
+  if (installs.length > 0) rows.push(['install', ...installs])
   if (files.length > 0) rows.push(['files', ...files.map((f) => f.path)])
   if (kept.length > 0) rows.push(['kept', ...kept])
   if (replaced.length > 0) rows.push(['replaced', ...replaced])
@@ -203,6 +300,8 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
     ui.print('out', ui.report(`vx init ${VERSION}`, [...rows, null, ['next', next]]))
     return 0
   }
+  const ran = await install(pkgRoot, false)
+  if (ran.length > 0) rows.push(['installed', ...ran])
   for (const f of files) await Bun.write(path.join(root, f.path), f.contents)
   for (const f of replaced) await unlink(path.join(root, f))
   // The lock that follows loads the workspace file just written.
@@ -217,7 +316,7 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
 }
 
 /**
- * A repo with a package.json is `@vzn/vx-migrate`'s, at the latest
+ * A Turbo or Nx repo is `@vzn/vx-migrate`'s, after the global install, at the latest
  * release: it installs @vzn/vx and every @vzn/vx-* plugin the root lists
  * at its own version, so init always lands on latest with all of them
  * together, as `vx upgrade` moves them (M, 2026-10-16: an installed 0.0.637
@@ -232,6 +331,8 @@ async function migrate(dirs: readonly string[], args: InitArgs): Promise<number>
     args.mode !== undefined && `--${args.mode}`,
     args.json === true && '--format=json',
   ].filter((f): f is string => typeof f === 'string')
+  // vx-migrate installs the project's own vx.
+  if (!args.dry) await install(null, false)
   // An exact version: `bun x` may answer `@latest` from its cache.
   const latest = VERSION === '0.0.0' ? 'latest' : await targetVersion(undefined, 'vx init')
   return Bun.spawn(migrateCommand(dirs, flags, latest), {

package/src/cli/plan-format.ts

@@ -1,7 +1,7 @@
 // Formatters for `--dry` (human / JSON).
 
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
-import { formatElapsed, maskedCommand } from '../util/index.js'
+import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
 
 /**
  * Human-readable preview. One line per real task (groups hidden, same
@@ -65,7 +65,11 @@ export function formatPlanText(plan: RunPlan): string {
 
   const hitParts: string[] = []
   if (local > 0) hitParts.push(`${local} local`)
-  if (remote > 0) hitParts.push(`${remote} remote`)
+  if (remote > 0) {
+    // The remote's sizes, summed: what restoring the hits would download.
+    const bytes = real.reduce((sum, t) => sum + (t.remoteBytes ?? 0), 0)
+    hitParts.push(bytes > 0 ? `${remote} remote, ${formatBytes(bytes)}` : `${remote} remote`)
+  }
   const hits = local + remote
   const summary: string[] = [`${real.length} task(s) planned`]
   if (hits > 0) summary.push(`${hits} cache hit${hits === 1 ? '' : 's'} (${hitParts.join(', ')})`)

package/src/cli/plugin-commands.ts

@@ -138,10 +138,8 @@ async function verbCache(
   ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
   plugin: string,
 ): Promise<PluginCache> {
-  const [{ Cache, pluginCache }, { resolveCache, resolveCacheScope }] = await Promise.all([
-    import('../cache/index.js'),
-    import('../orchestrator/index.js'),
-  ])
+  const [{ Cache, pluginCache }, { cacheRefs, resolveCache, resolveCacheScope }] =
+    await Promise.all([import('../cache/index.js'), import('../orchestrator/index.js')])
   const scope = resolveCacheScope(
     ws.workspaceRoot,
     ws.branch.trusted === true ? null : ws.branch.scope,
@@ -162,6 +160,7 @@ async function verbCache(
     cacheDir: ws.cacheDir,
     warn,
     scope,
+    refs: cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
     localCache,
     policy: VERB_POLICY,
     remotes,

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

@@ -518,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

@@ -475,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'

package/src/config.ts

@@ -102,11 +102,9 @@ export interface CacheSettings {
    * 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'`).
+   * one `.tar.zst`.
    */
-  store?: { embeddings?: false | string; decompress?: boolean; verify?: 'stat' | 'hash' | 'none' }
+  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

package/src/index.ts

@@ -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/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

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,6 @@ 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
 }
@@ -574,7 +571,7 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, branch, uploadConcurrency, ...ctx } = host
+  const { localCache, policy, remotes, uploadConcurrency, ...ctx } = host
   const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
@@ -593,7 +590,7 @@ export async function resolveCache(
   }
   return resolved.length === 0
     ? localCache
-    : new LayeredCache(localCache, resolved, branch, uploadConcurrency)
+    : 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,10 +346,9 @@ 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. `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.
+ * 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
@@ -506,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 {

package/src/orchestrator/prepare.ts

@@ -26,7 +26,6 @@ import {
   writesRunStore,
   type PluginCache,
   type ResolvedRemote,
-  BranchScope,
   applyGitEnumeration,
   gitPathspecs,
   MAX_SCOPED_PATHSPECS,
@@ -34,14 +33,11 @@ import {
   lazyGitEnumeration,
   measureFsClockLag,
   DEFAULT_STORE,
-  type StoreOptions,
 } from '../cache/index.js'
 import {
   buildPackageGraph,
   computeNestedProjectDirs,
   findWorkspaceRoot,
-  type AffectedChanges,
-  branchChanges,
   configuredBaseBranch,
   type LoadReads,
   PROJECT_CONFIG_FILENAMES,
@@ -81,13 +77,13 @@ import {
   lockReader,
   type LoadedProjects,
 } from './projects.js'
-import { keptByAffected, keyedByChange } from './affected-tasks.js'
+import { keptByAffected } from './affected-tasks.js'
 import { applyGraphStage } from './graph-stage.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
 import { askIgnoredOutputs, gatedOutputs } from './stable-keys.js'
-import { currentBranch, resolveCacheScope } from './run-context.js'
+import { cacheRefs, currentBranch, resolveCacheScope } from './run-context.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import { type Logger, warnOf } from '../report/index.js'
 import type { RunOptions } from './options.js'
@@ -291,33 +287,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     reused !== undefined
       ? Promise.resolve(reused.projects)
       : discoverProjects(workspaceRoot, readLock, plugins, cacheDir, warnOf(log), git)
-  // What the branch changed decides which tasks read the scope (owner,
-  // 2026-10-17). Only a scoped run's first remote call asks git: a run the
-  // local cache answers makes no remote call, and diffing beside discovery
-  // cost it 20-60 ms at 1k-5k projects.
-  const scopeChanges: (() => Promise<AffectedChanges>) | undefined =
-    cacheScope === undefined
-      ? undefined
-      : options.scopeChanges !== undefined
-        ? async () => options.scopeChanges!
-        : () =>
-            branchChanges(
-              workspaceRoot,
-              options.scopeBase ?? branchFacts.base,
-              baseBranch,
-              discovering,
-              {
-                untracked: async () => (await git.start()).untracked,
-                // A scoped enumeration lists only its projects: null asks git.
-                links: async () => {
-                  const g = await git.start()
-                  if (!g.scopes.includes('.')) return null
-                  const out: string[] = []
-                  for (const [rel, oid] of g.trusted) if (oid.startsWith('120000:')) out.push(rel)
-                  return out
-                },
-              },
-            )
   const projectMetas = await discovering
   mark('discover projects')
 
@@ -383,8 +352,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         DEFAULT_STORE.embeddings) as number,
       decompress: (resolveSetting('cache.store.decompress', workspaceConfig).value ??
         DEFAULT_STORE.decompress) as boolean,
-      verify: (resolveSetting('cache.store.verify', workspaceConfig).value ??
-        DEFAULT_STORE.verify) as StoreOptions['verify'],
     },
   )
   const unwritable = localCache.readOnlyNotice()
@@ -519,9 +486,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // cache plugin.
   let cache: CacheLayer
   const remotes: ResolvedRemote[] = []
-  // A scope only picks remote keys (owner, 2026-10-17): the local store
-  // keeps every branch's entries under the task keys.
-  const branchScope = cacheScope === undefined ? undefined : new BranchScope(cacheScope)
   if (options.remoteCache) {
     remotes.push({
       remote: options.remoteCache,
@@ -532,16 +496,16 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   }
   try {
     cache = options.remoteCache
-      ? new LayeredCache(localCache, remotes, branchScope, options.uploadConcurrency)
+      ? new LayeredCache(localCache, remotes, options.uploadConcurrency)
       : await resolveCache(plugins, {
           workspaceRoot,
           cacheDir,
           warn: warnOf(log),
           scope: cacheScope,
+          refs: cacheRefs(workspaceRoot, baseBranch),
           localCache,
           policy,
           remotes,
-          ...(branchScope !== undefined ? { branch: branchScope } : {}),
           ...(options.uploadConcurrency !== undefined
             ? { uploadConcurrency: options.uploadConcurrency }
             : {}),
@@ -776,13 +740,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     if (hasHook(plugins, 'key')) {
       await applyKeyHooks(plugins, nodes, { workspaceRoot, cacheDir, warn: warnOf(log) })
     }
-    // The final inputs decide which tasks the branch changed: they read
-    // the scope, every other task the default key.
-    if (branchScope !== undefined && scopeChanges !== undefined) {
-      branchScope.routeTasks(async () =>
-        keyedByChange(nodes, await scopeChanges(), projects, packageGraph),
-      )
-    }
     refuseFiltersThroughGroups(nodes)
     const exclude = options.excludeDependencies
     let keyOnly: ReadonlyMap<string, TaskNode> = new Map()