@vzn/vx 0.0.641 → 0.0.643

package/src/cache/scoped-cache.ts

@@ -1,20 +1,12 @@
-// The run's `cache.scope` over every layer at once (owner, 2026-10-14): a
-// scoped run reads the default key, then the scope's, and writes only the
-// scope's, in the local store and every remote alike. Below this wrapper no
-// layer knows a scope exists: the scope's key is a key like any other.
+// 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.
 
 import { xxh3hex } from '../util/index.js'
-import type {
-  CacheEntry,
-  CacheGetContext,
-  CacheLayer,
-  DeclaredOutputs,
-  IngestMeta,
-  InvocationRecord,
-  OutputDirRow,
-  RunRecord,
-  SaveArgs,
-} from './layer.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 {
@@ -22,229 +14,74 @@ export function scopedKey(scope: string, hash: string): string {
 }
 
 /**
- * A layer as a scoped run sees it. Callers speak task keys; each answer is
- * remembered under the key that served it (the default key on a default hit,
- * the scope's on a scope hit or a save), so the restore, the output index and
- * the run's history all reach the entry that answered. An artifact records
- * the key it was packed under and ingest refuses another, so a derived-key
- * collision degrades to a miss. A default artifact a remote ingest refuses is
- * a miss there, and the scope's key is asked next (Security F6).
+ * 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 ScopedCache implements CacheLayer {
-  readonly local?: CacheLayer['local']
-  readonly hasRemote?: boolean
-  readonly drainUploads?: () => Promise<void>
-  readonly stopUploads?: () => void
-  readonly remoteHasMany?: (hashes: readonly string[]) => Promise<Set<string> | null>
-  /** A scoped run saves under the scope's key, so that is the key asked. */
-  readonly probeBeforeUpload?: (hashes: Promise<readonly string[]>) => void
-  readonly getMany?: (
-    hashes: readonly string[],
-    ctx?: (hash: string) => CacheGetContext,
-  ) => Promise<Map<string, CacheEntry>>
-  /** Task key → the key that answers for it this run. */
-  private readonly served = new Map<string, string>()
-
-  constructor(
-    private readonly inner: CacheLayer,
-    private readonly scope: string,
-  ) {
-    if (inner.local !== undefined) this.local = inner.local
-    if (inner.hasRemote !== undefined) this.hasRemote = inner.hasRemote
-    if (inner.drainUploads !== undefined) this.drainUploads = () => inner.drainUploads!()
-    if (inner.stopUploads !== undefined) this.stopUploads = () => inner.stopUploads!()
-    if (inner.remoteHasMany !== undefined) this.remoteHasMany = (h) => this.scopedHasMany(h)
-    if (inner.probeBeforeUpload !== undefined)
-      this.probeBeforeUpload = (h) =>
-        inner.probeBeforeUpload!(h.then((keys) => keys.map((k) => this.own(k))))
-    if (inner.getMany !== undefined) this.getMany = (h, ctx) => this.scopedGetMany(h, ctx)
-  }
-
-  private own(hash: string): string {
-    return scopedKey(this.scope, hash)
-  }
-
-  private keyOf(hash: string): string {
-    return this.served.get(hash) ?? hash
-  }
-
-  /** A batch keyed by served keys, keyed back by task key. */
-  private batch<T>(
-    hashes: readonly string[],
-    read: (keys: string[]) => Map<string, T>,
-  ): Map<string, T> {
-    const keys = hashes.map((h) => this.keyOf(h))
-    const found = read(keys)
-    const out = new Map<string, T>()
-    for (let i = 0; i < hashes.length; i++) {
-      const v = found.get(keys[i]!)
-      if (v !== undefined) out.set(hashes[i]!, v)
+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 }),
     }
-    return out
-  }
-
-  /** A task key the store holds under the default key or the scope's. */
-  async localHasMany(hashes: readonly string[]): Promise<Set<string>> {
-    const held = await this.inner.localHasMany?.([...hashes, ...hashes.map((h) => this.own(h))])
-    if (held === undefined) return new Set()
-    return new Set(hashes.filter((h) => held.has(h) || held.has(this.own(h))))
-  }
-
-  private async scopedHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
-    const scoped = hashes.map((h) => this.own(h))
-    const [plain, own] = await Promise.all([
-      this.inner.remoteHasMany!(hashes),
-      this.inner.remoteHasMany!(scoped),
-    ])
-    if (plain == null || own == null) return null
-    const found = new Set(plain)
-    const scopeOnly: string[] = []
-    for (let i = 0; i < hashes.length; i++) {
-      if (plain.has(hashes[i]!) || !own.has(scoped[i]!)) continue
-      found.add(hashes[i]!)
-      scopeOnly.push(hashes[i]!)
-    }
-    // Their default key is known absent: its GET is skipped.
-    this.inner.markRemoteAbsent?.(scopeOnly)
-    return found
-  }
-
-  markRemoteAbsent(hashes: Iterable<string>): void {
-    const all: string[] = []
-    for (const h of hashes) all.push(h, this.own(h))
-    this.inner.markRemoteAbsent?.(all)
-  }
-
-  key(input: Parameters<CacheLayer['key']>[0]): Promise<string> {
-    return this.inner.key(input)
-  }
-
-  async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
-    // The scope's key first when only it is local: the default key's
-    // remote GET would cost a round-trip for the same inputs.
-    const own = this.own(hash)
-    const keys = (await this.inner.localHasMany?.([hash, own]))?.has(own)
-      ? [own, hash]
-      : [hash, own]
-    for (const key of keys) {
-      const entry = await this.inner.get(key, ctx)
-      if (entry === null) continue
-      this.served.set(hash, key)
-      return key === hash ? entry : { ...entry, hash }
-    }
-    return null
-  }
-
-  private async scopedGetMany(
-    hashes: readonly string[],
-    ctx?: (hash: string) => CacheGetContext,
-  ): Promise<Map<string, CacheEntry>> {
-    const out = await this.inner.getMany!(hashes, ctx)
-    for (const h of out.keys()) this.served.set(h, h)
-    const rest = hashes.filter((h) => !out.has(h))
-    if (rest.length === 0) return out
-    const byOwn = new Map(rest.map((h) => [this.own(h), h]))
-    const scoped = await this.inner.getMany!(
-      [...byOwn.keys()],
-      ctx === undefined ? undefined : (key) => ctx(byOwn.get(key)!),
-    )
-    for (const [key, entry] of scoped) {
-      const hash = byOwn.get(key)!
-      this.served.set(hash, key)
-      out.set(hash, { ...entry, hash })
-    }
-    return out
-  }
-
-  async has(hash: string): Promise<'local' | 'remote' | null> {
-    return (await this.inner.has(hash)) ?? (await this.inner.has(this.own(hash)))
-  }
-
-  async prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean> {
-    return (await this.inner.prefetch(hash, ctx)) || this.inner.prefetch(this.own(hash), ctx)
-  }
-
-  loadOutputFilesBatch(hashes: readonly string[]): ReturnType<CacheLayer['loadOutputFilesBatch']> {
-    return this.batch(hashes, (keys) => this.inner.loadOutputFilesBatch(keys))
-  }
-
-  isOutputsCurrent(
-    ...args: Parameters<CacheLayer['isOutputsCurrent']>
-  ): ReturnType<CacheLayer['isOutputsCurrent']> {
-    return this.inner.isOutputsCurrent(...args)
-  }
-
-  async recordOutputDirs(
-    hash: string,
-    projectDir: string,
-    prefixes: readonly string[],
-    holds?: (files: readonly string[]) => boolean,
-  ): Promise<void> {
-    await this.inner.recordOutputDirs?.(this.keyOf(hash), projectDir, prefixes, holds)
-  }
-
-  recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
-    this.inner.recordOutputStamps?.(this.keyOf(hash), projectDir, workspaceRoot)
-  }
-
-  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
-    return this.batch(hashes, (keys) => this.inner.loadOutputDirsBatch?.(keys) ?? new Map())
-  }
-
-  async outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
-    return (await this.inner.outputDirsCurrent?.(projectDir, rows)) ?? false
-  }
-
-  restoreOutputs(
-    hash: string,
-    projectDir: string,
-    workspaceRoot?: string,
-    outputs?: DeclaredOutputs,
-  ): Promise<void> {
-    return this.inner.restoreOutputs(this.keyOf(hash), projectDir, workspaceRoot, outputs)
-  }
-
-  save(args: SaveArgs): Promise<void> {
-    const key = this.own(args.hash)
-    this.served.set(args.hash, key)
-    return this.inner.save({ ...args, hash: key })
-  }
-
-  ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void> {
-    const key = this.own(hash)
-    this.served.set(hash, key)
-    return this.inner.ingest(key, body, meta)
-  }
-
-  /** History names the key that answered, so `vx why` reads that entry's components. */
-  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
-    this.inner.recordRunBundle({
-      ...bundle,
-      runs: bundle.runs.map((r) => (r.hash === undefined ? r : { ...r, hash: this.keyOf(r.hash) })),
-    })
-  }
-
-  stats(...args: Parameters<CacheLayer['stats']>): ReturnType<CacheLayer['stats']> {
-    return this.inner.stats(...args)
-  }
-
-  hashFile(filePath: string): Promise<string> {
-    return this.inner.hashFile(filePath)
-  }
-
-  outputsPath(hash: string): string {
-    return this.inner.outputsPath(this.keyOf(hash))
-  }
-
-  artifactSize(hash: string): number | undefined {
-    return this.inner.artifactSize?.(this.keyOf(hash))
-  }
-
-  prune(...args: Parameters<CacheLayer['prune']>): ReturnType<CacheLayer['prune']> {
-    return this.inner.prune(...args)
-  }
-
-  close(): void {
-    this.inner.close()
   }
 }

package/src/cache/umask.ts

@@ -0,0 +1,29 @@
+// The process umask, read when a restore starts: Bun reads it by setting 0
+// and putting it back in one synchronous call (project-loader.ts
+// `currentUmask`), so no spawn on this thread sees the 0, and a run
+// evaluates no config in a worker. Through globalThis: the playground's
+// shim has no umask.
+const proc = globalThis.process as { umask?: () => number } | undefined
+let umask = 0
+
+/** Read the umask again: a restore's modes follow the process's as it is now. */
+export function readUmask(): void {
+  if (typeof proc?.umask === 'function') umask = proc.umask()
+}
+readUmask()
+
+/**
+ * The permission bits a restore gives a stored `mode`: minus the umask, as
+ * tar gives a non-root user and Turbo does. A hit under `umask 077` gave
+ * back 0644 / 0755 where the build left 0600 / 0700, readable by every
+ * user on the machine (Growth's parity run, 2026-10-16).
+ */
+export function restoredMode(mode: number): number {
+  return mode & 0o777 & ~umask
+}
+
+/** A file on disk holds the stored `mode`: as saved, or as a restore here leaves it. */
+export function modeMatches(disk: number, stored: number): boolean {
+  const d = disk & 0o777
+  return d === (stored & 0o777) || d === restoredMode(stored)
+}

package/src/cli/docs.ts

@@ -1,12 +1,16 @@
 // `vx docs <query> [--limit N] [--format pretty|json]` — search vx's
-// reference offline, for an agent that cannot reach the site: each page is
+// reference as this version wrote it: packages/vx/docs at its git tag on
+// GitHub, read online (M, 2026-10-17: nothing is embedded). Each page is
 // cut at its headings, and the sections holding every query word print
 // whole, best first.
 
+import { VERSION } from '../version.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 
 const SITE = 'https://vznjs.github.io/vx/'
 const DEFAULT_LIMIT = 3
+const REPO = 'vznjs/vx'
+const DIR = 'packages/vx/docs'
 
 interface DocsArgs {
   terms: string[]
@@ -59,9 +63,55 @@ function anchor(heading: string): string {
     .replace(/ /g, '-')
 }
 
-/** A page's URL on the site; `features.md` is served as `all-features/`. */
+/** A page's URL on the site, as packages/vx-docs/scripts/import-docs.ts serves it. */
 function pageUrl(page: string): string {
-  return `${SITE}${page === 'features' ? 'all-features' : page}/`
+  const served: Record<string, string> = {
+    README: 'overview',
+    features: 'all-features',
+    'turbo-nx-support': 'compare/turbo-nx-support',
+  }
+  return `${SITE}${served[page] ?? page.toLowerCase()}/`
+}
+
+/** The git ref this vx's docs are at: its release tag; a source checkout (0.0.0) reads main. */
+export function docsRef(version: string = VERSION): string {
+  return version === '0.0.0' ? 'main' : `v${version}`
+}
+
+/**
+ * Every page of packages/vx/docs at `ref` (its own `.md` files, the
+ * maintainers' STATUS.md aside), page name → markdown. One listing, then
+ * the pages at once. Throws with what failed; a token in GITHUB_TOKEN or
+ * GH_TOKEN lifts GitHub's anonymous listing limit.
+ */
+export async function loadPages(
+  ref: string,
+  get: (url: string, init?: RequestInit) => Promise<Response> = fetch,
+  env: Record<string, string | undefined> = process.env,
+): Promise<Record<string, string>> {
+  const token = env['GITHUB_TOKEN'] ?? env['GH_TOKEN']
+  const listing = await get(
+    `https://api.github.com/repos/${REPO}/contents/${DIR}?ref=${encodeURIComponent(ref)}`,
+    {
+      headers: {
+        accept: 'application/vnd.github+json',
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+    },
+  )
+  if (!listing.ok) throw new Error(`GitHub answered ${listing.status} listing ${DIR} at ${ref}`)
+  const names = ((await listing.json()) as Array<{ name: string; type: string }>)
+    .filter((e) => e.type === 'file' && e.name.endsWith('.md') && e.name !== 'STATUS.md')
+    .map((e) => e.name)
+  const texts = await Promise.all(
+    names.map(async (name) => {
+      const url = `https://raw.githubusercontent.com/${REPO}/${ref}/${DIR}/${name}`
+      const r = await get(url)
+      if (!r.ok) throw new Error(`GitHub answered ${r.status} for ${url}`)
+      return r.text()
+    }),
+  )
+  return Object.fromEntries(names.map((n, i) => [n.slice(0, -3), texts[i]!]))
 }
 
 interface Section {
@@ -137,7 +187,10 @@ export function searchDocs(
   }))
 }
 
-export async function docsCmd(args: readonly string[]): Promise<number> {
+export async function docsCmd(
+  args: readonly string[],
+  load: (ref: string) => Promise<Record<string, string>> = loadPages,
+): Promise<number> {
   const parsed = parseDocsArgs(args)
   if (parsed.error) return refuse('docs', args, parsed.error, 'VX_E_USAGE')
   if (parsed.terms.length === 0) {
@@ -148,8 +201,19 @@ export async function docsCmd(args: readonly string[]): Promise<number> {
       'VX_E_USAGE',
     )
   }
-  const { PAGES } = await import('./docs-corpus.js')
-  const hits = searchDocs(PAGES, parsed.terms, parsed.limit)
+  const ref = docsRef()
+  let pages: Record<string, string>
+  try {
+    pages = await load(ref)
+  } catch (err) {
+    return refuse(
+      'docs',
+      args,
+      `cannot read the docs at ${ref} from GitHub (${err instanceof Error ? err.message : String(err)}); they are on the site, ${SITE}`,
+      'VX_E_NETWORK',
+    )
+  }
+  const hits = searchDocs(pages, parsed.terms, parsed.limit)
   const query = parsed.terms.join(' ')
   if (parsed.json) {
     process.stdout.write(`${JSON.stringify({ query, hits })}\n`)
@@ -157,7 +221,7 @@ export async function docsCmd(args: readonly string[]): Promise<number> {
   }
   if (hits.length === 0) {
     process.stdout.write(
-      `vx docs: no section of ${Object.keys(PAGES).join(', ')} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
+      `vx docs: no section of the docs at ${ref} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
     )
     return 0
   }

package/src/cli/help.ts

@@ -134,8 +134,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
     '                             foo^..., !foo, [<since>]',
     '      --affected[=<base>]  Projects changed since <base>, and dependents',
-    '                             (--filter "...[<base>]"); default run.affectedBase,',
-    '                             else origin/HEAD, main, master, HEAD~1.',
+    '                             (--filter "...[<base>]"); default the merge base',
+    '                             with origin/<baseBranch>; none on that branch.',
     "  pkg#task                 Run a specific project's task directly.",
     '',
     'Execution (for run):',
@@ -159,8 +159,6 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  flags; unnamed layers keep theirs. Examples:',
     '                                  local:rw,remote:r (remote read-only), remote:',
     '                                  (remote off), local:r (local read-only).',
-    "      --cache-scope <name>        This run's cache.scope (pr-123): write there,",
-    '                                  read the default keys first.',
     '      --cache-dir <path>          Cache directory (cwd-relative); default',
     '                                  .vx/cache, entries in ~/.vx/<id>/cache.',
     '      --cache-download <mode>     all (default) | toplevel | none:',
@@ -287,10 +285,10 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                           or write it where the shell loads completions from.',
     '',
     'Docs:',
-    '  vx docs <query>      Search the reference offline (cli, schema, caching, execution,',
-    '                       patterns, security, features): the sections holding every',
-    '                       word of the query print whole, best first, with their URL;',
-    '                       an error code (vx docs VX_E_CYCLE) prints its fix alone.',
+    "  vx docs <query>      Search the reference at this version's tag on GitHub (online):",
+    '                       the sections holding every word of the query print whole,',
+    '                       best first, with their URL; an error code',
+    '                       (vx docs VX_E_CYCLE) prints its fix alone.',
     '      --limit N        How many sections (default 3).',
     '      --format json    {query, hits: [{page, heading, url, text}]}.',
     '',

package/src/cli/plan-format.ts

@@ -148,7 +148,10 @@ export interface PlanTaskJson {
 }
 
 /** `affectedBase`: the ref a bare `--affected` guessed (or was given), so a reader knows what the diff was against. */
-export function formatPlanJson(plan: RunPlan, affectedBase?: string): string {
+export function formatPlanJson(
+  plan: Pick<RunPlan, 'tasks' | 'predicted' | 'downloadDowngrades'>,
+  affectedBase?: string,
+): string {
   return (
     JSON.stringify(
       {

package/src/cli/plugin-commands.ts

@@ -9,8 +9,8 @@
 
 import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
 import type { WorkspaceConfig } from '../config.js'
-import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
-import { cacheScopeEnvError, findWorkspaceRoot, isCacheScope } from '../workspace/index.js'
+import type { BranchFacts, VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
+import { configuredBaseBranch, findWorkspaceRoot } from '../workspace/index.js'
 import { machineParallelism, maskedLine } from '../util/index.js'
 import { resolveSetting } from '../settings.js'
 
@@ -49,6 +49,7 @@ async function workspacePlugins(cwd: string): Promise<
       workspaceConfig: WorkspaceConfig | null
       concurrency: number
       plugins: readonly VxPlugin[]
+      branch: BranchFacts
     }
   | UnresolvedPluginCommand
   | null
@@ -76,6 +77,7 @@ async function workspacePlugins(cwd: string): Promise<
       (resolveSetting('run.concurrency', ws.workspaceConfig).value as number | undefined) ??
       machineParallelism(),
     plugins: ws.plugins,
+    branch: ws.branch,
   }
 }
 
@@ -136,13 +138,16 @@ async function verbCache(
   ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
   plugin: string,
 ): Promise<PluginCache> {
-  const [{ Cache, pluginCache }, { resolveCache }] = await Promise.all([
+  const [{ Cache, pluginCache }, { resolveCache, resolveCacheScope }] = await Promise.all([
     import('../cache/index.js'),
     import('../orchestrator/index.js'),
   ])
-  const envScope = process.env['VX_CACHE_SCOPE'] || undefined
-  if (envScope !== undefined && !isCacheScope(envScope)) throw cacheScopeEnvError()
-  const scope = envScope ?? ws.workspaceConfig?.cache?.scope
+  const scope = resolveCacheScope(
+    ws.workspaceRoot,
+    ws.branch.scope,
+    ws.plugins.some((p) => p.cache !== undefined),
+    configuredBaseBranch(ws.workspaceConfig),
+  )
   const localCache = new Cache(
     ws.cacheDir,
     { read: true, write: false },

package/src/cli/run.ts

@@ -1,5 +1,5 @@
 import { isatty } from 'node:tty'
-import { cacheScopeError, findWorkspaceRoot, isCacheScope } from '../workspace/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
 import { translateForeign } from './foreign-flags.js'
 import { flagHint, refuse, seeHelp } from './help.js'
 import {
@@ -60,8 +60,6 @@ export interface RunArgs {
   remoteRequested?: boolean
   /** `--cache-dir <path>`: override the cache directory (cwd-relative). */
   cacheDir: string | undefined
-  /** `--cache-scope <name>`: this run's `cache.scope`, above `VX_CACHE_SCOPE` and the workspace's. */
-  cacheScope?: string
   /** `vx watch --poll` (`watch.poll`). */
   poll?: true
   forwardArgs: string[]
@@ -90,9 +88,7 @@ function flagOf(a: string | undefined, name: string): string | undefined {
 // The settings parsed by their kind alone; the cache flags, `--continue`
 // and `--cache-dir` keep their own branches above.
 const GENERIC_FLAGS = SETTINGS.filter(
-  (s) =>
-    s.flag?.verb === 'run' &&
-    !['run.continue', 'cache.dir', 'cache.policy', 'cache.scope'].includes(s.path),
+  (s) => s.flag?.verb === 'run' && !['run.continue', 'cache.dir', 'cache.policy'].includes(s.path),
 )
 
 /** The setting a flag names. */
@@ -204,11 +200,6 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
         }
       }
       out.cacheDir = v
-    } else if (a === '--cache-scope' || a?.startsWith('--cache-scope=')) {
-      const v = a === '--cache-scope' ? before[++i] : a.slice('--cache-scope='.length)
-      if (v === undefined || !isCacheScope(v))
-        return { ...out, error: cacheScopeError('--cache-scope') }
-      out.cacheScope = v
     } else if (flagOf(a, '--cache-policy')) {
       cacheFlag = true
       const name = flagOf(a, '--cache-policy')!
@@ -494,7 +485,6 @@ export async function resolveRunOptions(
       ? { cacheFlags: parsed.cacheFlags }
       : { cache: parsed.cache }),
     ...(parsed.remoteRequested ? { remoteRequested: true } : {}),
-    ...(parsed.cacheScope !== undefined ? { cacheScope: parsed.cacheScope } : {}),
     // A laptop reads the shared cache and never writes it (owner,
     // 2026-10-03); naming the remote in `--cache-policy` is asking to.
     ...(!parsed.remoteRequested && !onCI(process.env['CI'])
@@ -524,6 +514,8 @@ export async function resolveRunOptions(
     if (parsed.settings[path] !== undefined) Object.assign(opts, { [field]: parsed.settings[path] })
   }
   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
 }
@@ -595,9 +587,16 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   const scopeOut: { affectedBase?: string } = {}
   const resolved = await resolveRunOptions(parsed, cwd, tasks, 'run', scopeOut)
   if ('error' in resolved) return refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
+  // `--dry=json` prints a plan even when there is nothing to run: a script
+  // reading stdout broke exactly then (Growth, 2026-10-16).
+  const nothingToRun = (): 0 => {
+    if (parsed.dry === 'json')
+      process.stdout.write(formatPlanJson({ tasks: [] }, scopeOut.affectedBase))
+    return 0
+  }
   if ('nothingSelected' in resolved) {
     sayNotice('info', 'vx run', resolved.nothingSelected)
-    return 0
+    return nothingToRun()
   }
   const opts = resolved
   // The raw invocation, recorded on the `invocations` row so dashboards
@@ -628,11 +627,11 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       // said no affected project declared a task one did (X-141).
       if (plan.noneAffected !== undefined) {
         sayLine('info', plan.noneAffected, 'vx run')
-        return 0
+        return nothingToRun()
       }
       if (opts.selectedByDiff === true) {
         sayNotice('info', 'vx run', `no affected project declares task(s): ${tasks.join(', ')}`)
-        return 0
+        return nothingToRun()
       }
       return refuse(
         'run',