@vzn/vx 0.0.643 → 0.0.645

package/src/cache/remote-lane.ts

@@ -4,8 +4,9 @@
 // class with the endpoint named. The order across remotes, the local store
 // and provenance are `LayeredCache`'s; nothing here knows another remote.
 
+import { machineParallelism } from '../util/index.js'
 import type { RemoteKeyTraffic, RemoteTraffic } from './cache.js'
-import type { RemoteCacheLayer } from './layered-cache.js'
+import type { ArtifactInfo, RemoteCacheLayer } from './layered-cache.js'
 
 /** One remote, resolved: its wire and what the run's policy and its `access` let it do. */
 export interface ResolvedRemote {
@@ -20,11 +21,13 @@ export interface ResolvedRemote {
 }
 
 /**
- * Cap on concurrent background PUTs per remote. Keeps a burst of cache
- * misses from opening one socket per task; excess uploads queue and drain
- * FIFO.
+ * Requests at once to a remote, by default: pnpm's network concurrency
+ * (Bun's is a fixed 64). A request waits on the network, not a core, so
+ * the cap follows cores only past 21 of them.
  */
-const UPLOAD_CONCURRENCY = 4
+export function networkConcurrency(): number {
+  return Math.min(96, Math.max(machineParallelism() * 3, 64))
+}
 
 /** The seam call a failure happened in, as the warning names it. */
 export type RemoteOp = 'probe' | 'download' | 'upload'
@@ -45,6 +48,14 @@ function invalidRemoteResult(what: string): Error {
   )
 }
 
+/** A plugin's `ArtifactInfo`, keeping only the fields that are finite, non-negative numbers; null when it is no object. */
+function artifactInfo(value: unknown): ArtifactInfo | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+  const { size, durationMs } = value as Record<string, unknown>
+  const ok = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0
+  return { ...(ok(size) ? { size } : {}), ...(ok(durationMs) ? { durationMs } : {}) }
+}
+
 function isBody(value: unknown): value is Blob | Response {
   return value instanceof Blob || value instanceof Response
 }
@@ -103,14 +114,16 @@ export class RemoteLane {
    */
   private readonly absent = new Set<string>()
   /** What a `hasMany` said this remote holds, as `absent` records the rest. */
-  private readonly held = new Set<string>()
+  private readonly held = new Map<string, ArtifactInfo>()
 
   /**
    * A remote the run writes but does not read (`--force`): which of the
    * run's up-front keys it already holds, from one `hasMany`. `found` is
    * null when the probe failed.
    */
-  private presence: Promise<{ asked: Set<string>; found: Set<string> | null } | null> | undefined
+  private presence:
+    | Promise<{ asked: Set<string>; found: Map<string, ArtifactInfo> | null } | null>
+    | undefined
 
   private readonly uploadQueue: Array<() => Promise<void>> = []
   private activeUploads = 0
@@ -133,11 +146,11 @@ export class RemoteLane {
   constructor(
     resolved: ResolvedRemote,
     private readonly traffic: RemoteTraffic,
-    /** The wire as this run asks it: a branch scope's view of `resolved.remote`. */
-    remote: RemoteCacheLayer = resolved.remote,
+    /** Background PUTs at once; excess uploads queue and drain FIFO. */
+    private readonly uploadConcurrency: number = networkConcurrency(),
   ) {
     this.resolved = resolved
-    this.remote = remote
+    this.remote = resolved.remote
     this.onError = resolved.onError
     this.endpoint = printableEndpoint(resolved.remote.endpoint)
   }
@@ -154,15 +167,28 @@ export class RemoteLane {
    * Existence probe; a failure is a miss. A key a `hasMany` this run
    * answered for is not asked again: `--dry` batches its keys first.
    */
-  async has(hash: string): Promise<boolean> {
-    if (this.held.has(hash)) return true
-    if (this.absent.has(hash)) return false
+  async has(hash: string): Promise<ArtifactInfo | null> {
+    const held = this.held.get(hash)
+    if (held !== undefined) return held
+    if (this.absent.has(hash)) return null
+    let found: unknown
     try {
-      return Boolean(await this.remote.has(hash))
+      found = await this.remote.has(hash)
     } catch (err) {
       this.report('probe', hash, err)
-      return false
+      return null
     }
+    if (found === null || found === undefined) return null
+    const info = artifactInfo(found)
+    if (info === null)
+      this.report(
+        'probe',
+        hash,
+        invalidRemoteResult(
+          `has() resolved ${describeValue(found)} (expected { size, durationMs } or null)`,
+        ),
+      )
+    return info
   }
 
   /**
@@ -170,7 +196,7 @@ export class RemoteLane {
    * rest as absent; `null` when this remote cannot batch or the probe
    * failed, which the caller reads as "no batch info".
    */
-  async hasMany(hashes: readonly string[]): Promise<Set<string> | null> {
+  async hasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
     if (this.remote.hasMany === undefined) return null
     let found: unknown
     try {
@@ -180,19 +206,26 @@ export class RemoteLane {
       return null
     }
     if (found === null || found === undefined) return null
-    if (!(found instanceof Set)) {
+    if (!(found instanceof Map)) {
       this.report(
         'probe',
         batchOf(hashes),
         invalidRemoteResult(
-          `hasMany() resolved ${describeValue(found)} (expected a Set of the hashes present, or null)`,
+          `hasMany() resolved ${describeValue(found)} (expected a Map of the hashes present, or null)`,
         ),
       )
       return null
     }
-    const set = found as Set<string>
-    for (const h of hashes) (set.has(h) ? this.held : this.absent).add(h)
-    return set
+    const out = new Map<string, ArtifactInfo>()
+    for (const h of hashes) {
+      const info = found.has(h) ? (artifactInfo(found.get(h)) ?? {}) : undefined
+      if (info === undefined) this.absent.add(h)
+      else {
+        this.held.set(h, info)
+        out.set(h, info)
+      }
+    }
+    return out
   }
 
   /** The artifact's body, or null on a miss, a known absence, a failure or a malformed answer. */
@@ -248,14 +281,14 @@ export class RemoteLane {
     const probed = await this.presence
     if (probed !== undefined && probed !== null && probed.found !== null && probed.asked.has(hash))
       return probed.found.has(hash)
-    return this.has(hash)
+    return (await this.has(hash)) !== null
   }
 
   /** Queue a PUT in this remote's bounded pool; `body` is asked for when the job starts. */
   upload(
     hash: string,
     durationMs: number,
-    body: () => { body: Blob; release?: () => Promise<void> },
+    body: () => Promise<{ body: Blob; release?: () => Promise<void> }>,
     tally: { count: number; bytes: number; ms: number; failed: number },
   ): void {
     const key = this.trafficOf(hash)
@@ -265,10 +298,11 @@ export class RemoteLane {
       let release: (() => Promise<void>) | undefined
       try {
         if (this.stopped) return
+        if (this.held.has(hash)) return
         if (!this.read && (await this.holds(hash))) return
         if (this.stopped) return
         const start = performance.now()
-        const got = body()
+        const got = await body()
         release = got.release
         await this.remote.put(hash, got.body, { durationMs })
         tally.count++
@@ -369,7 +403,7 @@ export class RemoteLane {
   }
 
   private pump(): void {
-    while (this.activeUploads < UPLOAD_CONCURRENCY && this.uploadQueue.length > 0) {
+    while (this.activeUploads < this.uploadConcurrency && this.uploadQueue.length > 0) {
       const job = this.uploadQueue.shift()!
       this.activeUploads++
       // Jobs never reject (each wraps its PUT in the never-fail guard).

package/src/cache/scoped-cache.ts

@@ -1,87 +1,10 @@
-// A branch's cache scope (owner, 2026-10-17): the local store never knows
-// one, so every branch shares one local pool under the task keys. Scopes
-// decide only which remote entry a task asks for: a task the branch changed
-// reads the scope's key, every other task the default key, and a scoped run
-// writes every remote under the scope's key. An artifact is packed under its
-// task key wherever it is stored, so a remote entry ingests under that key.
+// A scope keys only what plugins store themselves (ctx.cache, run records):
+// task keys reach every remote plain, and a remote decides which branch a
+// read may see (VZN, 2026-10-20).
 
 import { xxh3hex } from '../util/index.js'
-import type { RemoteCacheLayer, RemoteKey } from './layered-cache.js'
 
 /** The key a scope stores `hash` under: task-key shaped, 16 hex, so every wire stores it unchanged. */
 export function scopedKey(scope: string, hash: string): string {
   return xxh3hex(`vx-cache-scope\0${scope}\0${hash}`)
 }
-
-/**
- * Which remote key each task asks for, in a run with a scope. The routes
- * come from the branch's diff, which only a remote call awaits: a run the
- * local cache answers never waits on git.
- */
-export class BranchScope {
-  /** Finds the tasks that read the scope, at the first remote call; null: every task does. */
-  private route: (() => Promise<ReadonlySet<string>>) | null = null
-  private routes: Promise<ReadonlySet<string>> | null = null
-  /** Task key → its task. */
-  private readonly taskOf = new Map<string, string>()
-
-  constructor(readonly scope: string) {}
-
-  /** Only the tasks `ids` finds read the scope; set before any remote call. */
-  routeTasks(ids: () => Promise<ReadonlySet<string>>): void {
-    this.route = ids
-  }
-
-  noteKey(taskId: string, hash: string): void {
-    this.taskOf.set(hash, taskId)
-  }
-
-  /** The remote key `hash` is read under, and the scope it is read in (none: the default key). */
-  private async readKey(hash: string): Promise<{ key: string; at: RemoteKey }> {
-    const id = this.taskOf.get(hash)
-    if (this.route !== null) this.routes ??= this.route()
-    const tasks = this.routes === null ? null : await this.routes
-    return tasks !== null && id !== undefined && !tasks.has(id)
-      ? { key: hash, at: {} }
-      : { key: scopedKey(this.scope, hash), at: { scope: this.scope } }
-  }
-
-  /**
-   * `inner` as this run asks it: each task key under its route's key; every
-   * write under the scope's. Each call also names its scope, for a backend
-   * that keeps one store per scope; no wire vx ships sends it.
-   */
-  remote(inner: RemoteCacheLayer): RemoteCacheLayer {
-    const read = (h: string) => this.readKey(h)
-    const at: RemoteKey = { scope: this.scope }
-    const hasMany = inner.hasMany
-    return {
-      ...(inner.endpoint !== undefined ? { endpoint: inner.endpoint } : {}),
-      ...(inner.open !== undefined ? { open: (ctx) => inner.open!(ctx) } : {}),
-      has: async (h) => {
-        const r = await read(h)
-        return inner.has(r.key, r.at)
-      },
-      ...(hasMany !== undefined
-        ? {
-            hasMany: async (hashes) => {
-              const reads = await Promise.all(hashes.map(read))
-              const keys = reads.map((r) => r.key)
-              const found = await hasMany.call(
-                inner,
-                keys,
-                reads.map((r) => r.at),
-              )
-              if (!(found instanceof Set)) return found
-              return new Set(hashes.filter((_, i) => found.has(keys[i]!)))
-            },
-          }
-        : {}),
-      get: async (h) => {
-        const r = await read(h)
-        return inner.get(r.key, r.at)
-      },
-      put: (h, body, meta) => inner.put(scopedKey(this.scope, h), body, { ...meta, ...at }),
-    }
-  }
-}

package/src/cache/tar-stream.ts

@@ -122,14 +122,19 @@ class Source {
   constructor(private readonly reader: AsyncIterator<Uint8Array>) {}
 
   private async fill(): Promise<boolean> {
-    if (this.done) return false
-    const { done, value } = await this.reader.next()
-    if (done === true || value === undefined) {
-      this.done = true
-      return false
+    // An empty chunk is skipped, never reported as data: the callers read
+    // `chunks[0]` after a true (the tar a tree packs back yields them).
+    for (;;) {
+      if (this.done) return false
+      const { done, value } = await this.reader.next()
+      if (done === true || value === undefined) {
+        this.done = true
+        return false
+      }
+      if (value.byteLength === 0) continue
+      this.chunks.push(value)
+      return true
     }
-    if (value.byteLength > 0) this.chunks.push(value)
-    return true
   }
 
   /** Exactly `n` bytes, or null at a clean end (nothing buffered), or a TarFormatError mid-entry. */

package/src/cli/format.ts

@@ -1,4 +1,3 @@
-// `formatBytes` moved to util/size.ts beside the parsers (item 658): a run
-// names what the workspace's `cacheRetention` evicted, and the orchestrator
+// `formatBytes` lives in util/size.ts beside the parsers: the orchestrator
 // may not import the CLI.
 export { formatBytes } from '../util/index.js'

package/src/cli/help.ts

@@ -163,6 +163,12 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  .vx/cache, entries in ~/.vx/<id>/cache.',
     '      --cache-download <mode>     all (default) | toplevel | none:',
     '                                  where remote outputs land.',
+    '      --cache-concurrency-download <n>',
+    '                                  Remote downloads at once.',
+    '      --cache-concurrency-upload <n>',
+    '                                  Uploads at once, per remote.',
+    '      --cache-concurrency-restore <n>',
+    '                                  Local hits restoring at once.',
     '      --retries <n>               Up to <n> more runs of a failed task, for',
     '                                  tasks without their own exec.retries. Not',
     '                                  folded into cache keys.',
@@ -258,10 +264,10 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --cache-dir <path>  Read the cache a run with the same flag uses.',
     '',
     'Migration:',
-    '  vx init              With no package.json: write .vx/workspace.ts and an empty',
-    '                       root vx.config.ts. With one: runs @vzn/vx-migrate, which maps',
-    '                       turbo.json, an Nx graph or package.json scripts to one',
-    '                       vx.config.ts per package (asking native or keep in Turbo/Nx).',
+    '  vx init              Install vx globally and as the root devDependency, then',
+    '                       write .vx/workspace.ts and an empty root vx.config.ts. In a',
+    '                       Turbo or Nx repo: runs @vzn/vx-migrate, which maps turbo.json',
+    '                       or the Nx graph to vx (asking native or keep).',
     '      --dry            Print the generated files instead of writing them.',
     '      --format json    With --dry: the plan as one JSON document (schemas/init.json).',
     '      --force          Overwrite existing vx.config.* files.',

package/src/cli/info.ts

@@ -100,9 +100,6 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
     ...(Object.values(f.settings).some((s) => s.source !== 'default')
       ? ([['settings', describeSettings(f.settings)]] as [string, string][])
       : []),
-    ...(f.cacheRetention !== null
-      ? ([['cache retention', describeRetention(f.cacheRetention)]] as [string, string][])
-      : []),
     // Only when there is something to say.
     ...(f.orphans.artifacts > 0
       ? ([
@@ -128,14 +125,9 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
   return ui.report('vx info', rows).lines(colors).join('\n')
 }
 
-/** `812 (1.2 GB)`, or against `cacheRetention.maxSize`: `812 (1.2 GB of 10 GB, 12%)`. */
+/** `812 (1.2 GB)`. */
 function describeEntries(f: InfoFacts): string {
-  const max = f.cacheRetention?.maxBytes
-  const size =
-    max === undefined
-      ? formatBytes(f.cacheBytes)
-      : `${formatBytes(f.cacheBytes)} of ${formatBytes(max)}, ${Math.round((f.cacheBytes / max) * 100)}%`
-  return `${f.cacheEntries} (${size})`
+  return `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`
 }
 
 /**
@@ -152,15 +144,6 @@ function describeSettings(settings: InfoFacts['settings']): string {
     .join(', ')
 }
 
-/** What a run's end evicts: `entries unused for 30d, and the oldest entries past 10G`. */
-function describeRetention(r: NonNullable<InfoFacts['cacheRetention']>): string {
-  const parts = [
-    ...(r.olderThan !== undefined ? [`entries unused for ${r.olderThan}`] : []),
-    ...(r.maxSize !== undefined ? [`the oldest entries past ${r.maxSize}`] : []),
-  ]
-  return `each run evicts ${parts.join(', and ')}`
-}
-
 /** A path under the home directory as `~/…`: shorter, and no user name in a pasted report. */
 function tildePath(p: string): string {
   const home = os.homedir()

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,13 +138,11 @@ 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.scope,
+    ws.branch.trusted === true ? null : ws.branch.scope,
     ws.plugins.some((p) => p.cache !== undefined),
     configuredBaseBranch(ws.workspaceConfig),
   )
@@ -162,6 +160,7 @@ async function verbCache(
     cacheDir: ws.cacheDir,
     warn,
     scope,
+    refs: cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
     localCache,
     policy: VERB_POLICY,
     remotes,