@vzn/vx 0.0.642 → 0.0.643

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:',

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
 }

package/src/cli/select.ts

@@ -12,6 +12,7 @@ import {
   refIsHead,
   applyFilters,
   buildPackageGraph,
+  configuredBaseBranch,
   defaultAffectedBase,
   findWorkspaceRoot,
   type FingerprintClaims,
@@ -49,7 +50,6 @@ import {
   loadCliProjects,
   loadCliWorkspace,
 } from './workspace-config.js'
-import { resolveSetting } from '../settings.js'
 
 /**
  * The projects whose tasks declare an `inputs.workspaceFiles` glob
@@ -244,20 +244,18 @@ function refusalOf(err: unknown): Refusal {
 
 /**
  * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
- * projects and their dependents. An empty base is `run.affectedBase`
- * (its variable, then the workspace's, which a plugin's `config` stage may set from nx.json's
- * `defaultBase` or `TURBO_SCM_BASE`), then the guess.
+ * projects and their dependents. An empty base is a plugin's (`setBranch`:
+ * a pull request's base commit), else the merge base with `baseBranch`.
  */
 export async function affectedFilterFor(cwd: string, affected: string): Promise<string | Refusal> {
   const root = await findWorkspaceRoot(cwd)
   let base = affected
   if (base === '') {
-    const ws = (await loadCliWorkspace(root)).workspaceConfig
-    base = (resolveSetting('run.affectedBase', ws).value as string | undefined) ?? ''
-  }
-  if (base === '') {
+    const ws = await loadCliWorkspace(root)
     try {
-      base = await defaultAffectedBase(root)
+      base =
+        ws.branch.base ??
+        (await defaultAffectedBase(root, configuredBaseBranch(ws.workspaceConfig)))
     } catch (err) {
       if (!isUserError(err)) throw err
       return refusalOf(err)

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
@@ -95,15 +95,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. */

package/src/index.ts

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

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,8 @@ export interface CacheHost extends CacheContext {
   readonly policy: CachePolicy
   /** Filled with each remote and what its policy lets it do, for the plugins' `ctx.cache`. */
   readonly remotes?: ResolvedRemote[]
+  /** The run's branch scope, which picks each remote key. */
+  readonly branch?: BranchScope
 }
 
 /**
@@ -569,7 +572,7 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, ...ctx } = host
+  const { localCache, policy, remotes, branch, ...ctx } = host
   const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
@@ -586,7 +589,7 @@ 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)
 }
 
 /** 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,22 @@ 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. A later plugin's field wins.
+ */
+export interface BranchFacts {
+  scope?: string
+  base?: string
+}
+
+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 +503,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.
    */

package/src/orchestrator/prepare.ts

@@ -26,7 +26,7 @@ import {
   writesRunStore,
   type PluginCache,
   type ResolvedRemote,
-  ScopedCache,
+  BranchScope,
   applyGitEnumeration,
   gitPathspecs,
   MAX_SCOPED_PATHSPECS,
@@ -38,8 +38,9 @@ import {
   buildPackageGraph,
   computeNestedProjectDirs,
   findWorkspaceRoot,
-  cacheScopeEnvError,
-  isCacheScope,
+  type AffectedChanges,
+  branchChanges,
+  configuredBaseBranch,
   type LoadReads,
   PROJECT_CONFIG_FILENAMES,
   readClaimedFiles,
@@ -78,13 +79,13 @@ import {
   lockReader,
   type LoadedProjects,
 } from './projects.js'
-import { keptByAffected } from './affected-tasks.js'
+import { keptByAffected, keyedByChange } 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 } from './run-context.js'
+import { 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'
@@ -113,6 +114,8 @@ export interface PreparedRun {
   hasRemoteLayer: boolean
   /** `--cache-policy` with the workspace's `cacheScope` applied: what the layers were built under. */
   cachePolicy: CachePolicy
+  /** The scope this run's cache reads and writes, when one is set; named on the summary's `info` row. */
+  cacheScope: string | undefined
   /** The run's remotes in declared order, as the policy gates each; `openRemotes` turns one off. */
   remotes: ResolvedRemote[]
   /**
@@ -249,8 +252,21 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     (reused !== undefined ? gitOfDiscovery(reused.projects) : undefined) ??
     lazyGitEnumeration(workspaceRoot)
   if (wholeTree) void git.start()
-  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warnOf(log))
+  const {
+    workspaceConfig,
+    plugins,
+    branch: branchFacts,
+  } = await loadWorkspacePlugins(workspaceRoot, warnOf(log))
   mark('workspace config')
+  const baseBranch = configuredBaseBranch(workspaceConfig)
+  const cacheScope =
+    options.cacheScope ??
+    resolveCacheScope(
+      workspaceRoot,
+      branchFacts.scope,
+      plugins.some((p) => p.cache !== undefined),
+      baseBranch,
+    )
   let learnedBranch: string | null | undefined
   const branch = (): string | null =>
     learnedBranch === undefined
@@ -269,10 +285,38 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // Asked now, read when the cache opens: a repository with no remote is
   // named by its root commit, a git spawn the discovery below overlaps.
   const storeRoot = options.cacheDir ? null : resolveStoreRoot(workspaceRoot, workspaceConfig)
-  const projectMetas =
+  const discovering =
     reused !== undefined
-      ? reused.projects
-      : await discoverProjects(workspaceRoot, readLock, plugins, cacheDir, warnOf(log), git)
+      ? 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')
 
   // SCOPED config loading: configs are programs, and evaluating 1090
@@ -314,12 +358,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // so a reader profiling that stage was sent to the wrong code.
   mark('package graph')
 
-  // `--cache-scope`, then `VX_CACHE_SCOPE`, win over the workspace (and `github()`'s guess):
-  // a CI job that knows its trust level says so without editing config.
-  const envScope = process.env['VX_CACHE_SCOPE'] || undefined
-  if (envScope !== undefined && !isCacheScope(envScope)) throw cacheScopeEnvError()
   const workspacePolicy = workspaceCachePolicy(workspaceConfig)
-  const cacheScope = options.cacheScope ?? envScope ?? workspaceConfig?.cache?.scope
   const asked =
     options.cache ?? applyCacheFlags(workspacePolicy ?? FULL_CACHE_POLICY, options.cacheFlags)
   // A laptop reads the shared cache and does not write it unless a policy
@@ -470,6 +509,9 @@ 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,
@@ -480,7 +522,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   }
   try {
     cache = options.remoteCache
-      ? new LayeredCache(localCache, remotes)
+      ? new LayeredCache(localCache, remotes, branchScope)
       : await resolveCache(plugins, {
           workspaceRoot,
           cacheDir,
@@ -489,6 +531,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
           localCache,
           policy,
           remotes,
+          ...(branchScope !== undefined ? { branch: branchScope } : {}),
         })
   } catch (err) {
     // A cache plugin that throws or returns something off-contract is
@@ -499,8 +542,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     localCache.close()
     throw err
   }
-  // One scoping rule above every layer, local and remote alike.
-  if (cacheScope !== undefined) cache = new ScopedCache(cache, cacheScope)
   // Ask the LAYER, don't infer. Identity against `localCache` answers a
   // DIFFERENT question — "did the plugin hand back something other than the
   // handle I passed in?" — which an ordinary pass-through decorator (a
@@ -534,6 +575,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
+      cacheScope,
       remotes,
       keepRunEntry: undefined,
       priorities: () => Promise.resolve(new Map()),
@@ -721,6 +763,13 @@ 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()
@@ -783,6 +832,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
+      cacheScope,
       remotes,
       priorities,
       branch,