@vzn/vx 0.0.642 → 0.0.643

package/src/orchestrator/projects.ts

@@ -25,6 +25,8 @@ import type { WorkspaceConfig } from '../config.js'
 import { lazyGitEnumeration, type LazyGitEnumeration } from '../cache/index.js'
 import { relPosix, UserError } from '../util/index.js'
 import {
+  cacheScopeError,
+  isCacheScope,
   loadWorkspaceConfig,
   discoveredProject,
   linkDiscoveredEdges,
@@ -33,7 +35,7 @@ import {
 } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
 import { applyConfigHooks, applyDiscoverHooks, applyProjectHooks, hasHook } from './plugin-host.js'
-import type { VxPlugin } from './plugin.js'
+import type { BranchFacts, VxPlugin } from './plugin.js'
 
 /**
  * The workspace config with the plugin `config` stage applied — the first
@@ -43,10 +45,16 @@ import type { VxPlugin } from './plugin.js'
 export async function loadWorkspacePlugins(
   workspaceRoot: string,
   warn: (message: string) => void,
-): Promise<{ workspaceConfig: WorkspaceConfig | null; plugins: readonly VxPlugin[] }> {
+): Promise<{
+  workspaceConfig: WorkspaceConfig | null
+  plugins: readonly VxPlugin[]
+  branch: BranchFacts
+}> {
   const loaded = await loadWorkspaceConfig(workspaceRoot)
   const plugins = (loaded?.plugins ?? []) as readonly VxPlugin[]
-  if (loaded === null || !hasHook(plugins, 'config')) return { workspaceConfig: loaded, plugins }
+  const branch: BranchFacts = {}
+  if (loaded === null || !hasHook(plugins, 'config'))
+    return { workspaceConfig: loaded, plugins, branch }
   // Bun keeps one module per specifier, so the file's export is one object
   // per process: the CLI's selection pass, the run and each `vx watch`
   // cycle handed the hooks what the last load's hooks had edited
@@ -60,10 +68,16 @@ export async function loadWorkspacePlugins(
   // Re-validated after each plugin, as the `project` stage is: an edit
   // the loader would refuse from a user (`concurrency: -3`) hung the run,
   // and `cacheDir: 42` reached `path.resolve` as a TypeError.
-  await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn }, (plugin) =>
+  const setBranch = (facts: BranchFacts): void => {
+    if (facts.scope !== undefined && !isCacheScope(facts.scope))
+      throw new UserError(`setBranch: ${cacheScopeError('scope')}`)
+    if (facts.scope !== undefined) branch.scope = facts.scope
+    if (facts.base !== undefined) branch.base = facts.base
+  }
+  await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn, setBranch }, (plugin) =>
     validateWorkspace(workspaceConfig, `.vx/workspace (after plugin '${plugin.name}')`),
   )
-  return { workspaceConfig, plugins }
+  return { workspaceConfig, plugins, branch }
 }
 
 /**

package/src/orchestrator/run-context.ts

@@ -15,6 +15,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { executablePath, gitEnv, relPosix, ulid, xxh3hex } from '../util/index.js'
 import { resolveSetting } from '../settings.js'
+import { branchCacheScope, cacheScopeEnvError, isCacheScope } from '../workspace/index.js'
 import { VERSION } from '../version.js'
 import type { RunContextRecord } from './telemetry.js'
 
@@ -525,6 +526,85 @@ export function currentBranch(
   return set ?? captureGitContext(workspaceRoot, null, env).branch
 }
 
+/**
+ * The cache scope a checkout on a branch reads, from the `.git` files
+ * alone (owner, 2026-10-17): `<owner>/<repo>:<branch>`, the branch it
+ * tracks (`branch.<name>.merge` on `branch.<name>.remote`), else its own
+ * name on `origin`, the repository named by that remote's URL. None on
+ * the default branch, on a detached HEAD, or with no remote URL. CI writes
+ * that scope for the same branch (`github()`), so a laptop reads what its
+ * branch's CI saved.
+ */
+export function localBranchScope(
+  workspaceRoot: string,
+  baseBranch: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const head = readHeadDirect(workspaceRoot)
+  if (head === null || head.branch === null) return undefined
+  const config = gitConfigSections(workspaceRoot)
+  const own = config.get(`branch "${head.branch}"`)
+  const name = own?.get('merge')?.replace(/^refs\/heads\//, '') ?? head.branch
+  const url = config.get(`remote "${own?.get('remote') ?? 'origin'}"`)?.get('url')
+  const repo = url === undefined ? undefined : repoOfUrl(url)
+  if (repo === undefined) return undefined
+  const trunk = baseBranch ?? captureDefaultBranch(env, workspaceRoot)
+  if (trunk === null ? name === 'main' || name === 'master' : name === trunk) return undefined
+  return branchCacheScope(repo, name)
+}
+
+/** `owner/repo` from a remote URL (its last two path segments); undefined for a local path. */
+function repoOfUrl(url: string): string | undefined {
+  const parts = normalizeRemoteUrl(url).split('/')
+  return parts.length < 3 ? undefined : parts.slice(-2).join('/')
+}
+
+/** `.git/config`'s sections, each a key → value map (last wins); empty when it cannot be read. */
+function gitConfigSections(workspaceRoot: string): Map<string, Map<string, string>> {
+  const sections = new Map<string, Map<string, string>>()
+  try {
+    const dirs = refDirsOf(workspaceRoot)
+    if (dirs === null) return sections
+    let at: Map<string, string> | undefined
+    for (const raw of fs.readFileSync(path.join(dirs.commonDir, 'config'), 'utf8').split('\n')) {
+      const line = raw.trim()
+      const section = /^\[\s*(\w+)(?:\s+"(.*)")?\s*\]$/.exec(line)
+      if (section !== null) {
+        const key = section[2] === undefined ? section[1]! : `${section[1]} "${section[2]}"`
+        at = sections.get(key) ?? new Map()
+        sections.set(key, at)
+        continue
+      }
+      const kv = /^(\w+)\s*=\s*(.*)$/.exec(line)
+      if (kv !== null) at?.set(kv[1]!.toLowerCase(), kv[2]!.trim())
+    }
+  } catch {
+    // no config to read: no remote, so no scope.
+  }
+  return sections
+}
+
+/**
+ * The run's cache scope (owner, 2026-10-17): `VX_CACHE_SCOPE` (empty: none),
+ * else a plugin's (`setBranch`, `github()` on Actions), else, with a cache
+ * plugin to share it, the branch's from git. Undefined: the default keys.
+ */
+export function resolveCacheScope(
+  workspaceRoot: string,
+  pluginScope: string | undefined,
+  hasRemote: boolean,
+  baseBranch: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const named = env['VX_CACHE_SCOPE']
+  if (named !== undefined) {
+    if (named === '') return undefined
+    if (!isCacheScope(named)) throw cacheScopeEnvError()
+    return named
+  }
+  return pluginScope ?? (hasRemote ? localBranchScope(workspaceRoot, baseBranch, env) : undefined)
+}
+
 export interface TelemetryRunContextArgs {
   runId: string
   /** The invocation, already masked. */

package/src/orchestrator/run.ts

@@ -799,6 +799,7 @@ async function runOnBus(
       version: VERSION,
       packageCount: packagesInScope.size,
       remoteCacheEnabled,
+      cacheScope: prepared.cacheScope,
       cache: {
         local: policy.localRead || policy.localWrite,
         localWrite: policy.localWrite,

package/src/orchestrator/task-hash.ts

@@ -97,6 +97,12 @@ export interface ComputeHashArgs {
  */
 export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   if (isKeyless(args.node.config)) return keylessHash(args.node.id)
+  const key = await taskHash(args)
+  args.cache.noteKey?.(args.node.id, key)
+  return key
+}
+
+async function taskHash(args: ComputeHashArgs): Promise<string> {
   const end = span('task hash')
   try {
     const folds = args.captureInto === undefined ? args.hashCache?.folds : undefined

package/src/report/summary.ts

@@ -188,6 +188,8 @@ export interface RunContext {
   /** Worker-pool size for this run; shown on the `info` row. */
   concurrency?: number
   remoteCacheEnabled: boolean
+  /** The run's cache scope, named after the cache mode: `scope vznjs/vx:feat-x`. */
+  cacheScope?: string | undefined
   /**
    * The cache layers the run used, so the legend reads `local 1= 2↓ 4↑ ·
    * remote 3↓ 4↑`. Absent: the plain `N miss` legend.
@@ -407,6 +409,7 @@ export function formatSummarySection(
     if (context.concurrency !== undefined)
       info.push(`${context.concurrency} worker${context.concurrency === 1 ? '' : 's'}`)
     info.push(context.remoteCacheEnabled ? 'local + remote cache' : 'local cache')
+    if (context.cacheScope !== undefined) info.push(`scope ${context.cacheScope}`)
     // The plugin's hand on the run: a task a policy held with a worker
     // free would otherwise have started; without the line nothing says
     // the policy acted. The duration is the waits summed, task-seconds

package/src/settings.ts

@@ -43,6 +43,12 @@ export interface Setting {
 const SCHEDULES = ['most-work', 'critical-path', 'direct-dependents', 'ready-order'] as const
 
 export const SETTINGS: readonly Setting[] = [
+  {
+    path: 'baseBranch',
+    kind: { type: 'string' },
+    default: "origin/HEAD's branch, then main, then master",
+    doc: 'The default branch: a run on it has no cache scope and a bare `--affected` no base; elsewhere both use the merge base with `origin/<baseBranch>`.',
+  },
   {
     path: 'run.concurrency',
     kind: { type: 'concurrency' },
@@ -57,12 +63,6 @@ export const SETTINGS: readonly Setting[] = [
     doc: 'Which ready task starts first when there are more than workers.',
     flag: { verb: 'run', name: '--schedule' },
   },
-  {
-    path: 'run.affectedBase',
-    kind: { type: 'string' },
-    default: 'origin/HEAD, then the trunk, else HEAD~1',
-    doc: 'The git ref a bare `--affected` compares with.',
-  },
   {
     path: 'run.branch',
     kind: { type: 'string' },
@@ -137,9 +137,9 @@ export const SETTINGS: readonly Setting[] = [
   {
     path: 'cache.scope',
     kind: { type: 'string' },
-    default: 'none (the default keys)',
-    doc: "Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.",
-    flag: { verb: 'run', name: '--cache-scope' },
+    default: "the branch's, `<owner>/<repo>:<branch>`, with a remote cache off `baseBranch`",
+    doc: "A branch's remote entries (`'vznjs/vx:feat-x'`): tasks the branch changed read the scope's key, the rest the default key; the local cache never uses it. Empty: no scope.",
+    config: false,
   },
   {
     path: 'cache.download',
@@ -220,7 +220,7 @@ export const SETTINGS: readonly Setting[] = [
   },
 ]
 
-/** The `.vx/workspace` groups that hold settings; `plugins` is the other key. */
+/** The `.vx/workspace` groups that hold settings; `baseBranch` and `plugins` are the other keys. */
 export const SETTING_GROUPS = ['run', 'cache', 'lock', 'watch'] as const
 
 const BY_PATH = new Map(SETTINGS.map((s) => [s.path, s]))
@@ -229,7 +229,7 @@ export function setting(path: string): Setting {
   return BY_PATH.get(path)!
 }
 
-/** `run.affectedBase` → `VX_RUN_AFFECTED_BASE`. */
+/** `run.branch` → `VX_RUN_BRANCH`. */
 export function envName(path: string): string {
   return `VX_${path
     .replace(/([a-z0-9])([A-Z])/g, '$1_$2')

package/src/workspace/affected.ts

@@ -14,6 +14,7 @@ import {
   gitSpawnRefusal,
   isExecutableMissing,
   isInstalledPath,
+  isUserError,
   notAWorkTree,
   relPosix,
   UserError,
@@ -73,7 +74,14 @@ export interface AffectedArgs {
   workspaceRoot: string
   /** Git ref / commit / branch to compare against. Required. */
   since: string
-  projects: readonly ProjectMeta[]
+  /** A promise when the caller is still discovering them: the git calls start first. */
+  projects: readonly ProjectMeta[] | Promise<readonly ProjectMeta[]>
+  /**
+   * False skips the scan of what each `vx.config` imports (every config
+   * read): the cache scope's split, where a wrong answer costs a miss,
+   * never a stale hit, and the scan was most of a 1,000-project diff.
+   */
+  configImports?: false
   /**
    * Which projects declare a `inputs.workspaceFiles` glob matching one of
    * these workspace-relative paths.
@@ -255,6 +263,8 @@ export async function affectedChanges(
       gitPaths(args.workspaceRoot, ['ls-files', '--others', '--exclude-standard', '-z']))(),
   ])
 
+  const projects = await args.projects
+
   // .vx/projects.lock.json (workspace-root metadata) is excluded like a gitignored
   // file: re-running `vx lock` must not mark every project affected.
   // An untracked file under `node_modules` is an install, which the input
@@ -291,7 +301,7 @@ export async function affectedChanges(
   //
   // Selection is not hashed, so widening it here changes no cache key.
   const everything = (file: string): AffectedChanges => {
-    const all = new Set(args.projects.map((p) => p.name))
+    const all = new Set(projects.map((p) => p.name))
     const wholeBy = new Map([...all].map((n) => [n, file]))
     return { projects: all, changed, paths: new Map(), whole: all, wholeBy }
   }
@@ -320,7 +330,7 @@ export async function affectedChanges(
   const rootDir = path.resolve(args.workspaceRoot)
   const loose = changed.filter((rel) => {
     const abs = path.join(rootDir, rel)
-    return !args.projects.some((p) => p.dir !== rootDir && abs.startsWith(p.dir + path.sep))
+    return !projects.some((p) => p.dir !== rootDir && abs.startsWith(p.dir + path.sep))
   })
   const extraClaims = loose.length > 0 ? await loadClaims() : undefined
   for (const file of extraClaims?.files ?? []) {
@@ -383,7 +393,7 @@ export async function affectedChanges(
 
   const realDirs = new Map(
     await Promise.all(
-      args.projects.map(async (p) => [p.dir, await realpath(p.dir).catch(() => p.dir)] as const),
+      projects.map(async (p) => [p.dir, await realpath(p.dir).catch(() => p.dir)] as const),
     ),
   )
   const paths = new Map<string, string[]>()
@@ -392,7 +402,7 @@ export async function affectedChanges(
     args.workspaceRoot,
     changed,
     nested,
-    args.projects,
+    projects,
     realDirs,
     perTask
       ? {
@@ -412,7 +422,7 @@ export async function affectedChanges(
   const configs = changed.filter((rel) => CONFIG_NAMES.has(path.posix.basename(rel)))
   if (configs.length > 0) {
     const atBase = await gitBlobsAt(args.workspaceRoot, base, configs)
-    for (const name of parentsOfNewNested(args.workspaceRoot, atBase, args.projects)) {
+    for (const name of parentsOfNewNested(args.workspaceRoot, atBase, projects)) {
       owned.add(name)
       whole.add(name)
     }
@@ -426,12 +436,14 @@ export async function affectedChanges(
   // (`../../src/index.ts`), whose target is owned.
   // Per task, a project that owns the changed file still needs to know its
   // config imported it: that re-keys every task, whatever their inputs.
-  for (const name of await configImportOwners({
-    workspaceRoot: args.workspaceRoot,
-    projects: args.projects,
-    changed,
-    skip: perTask ? new Set() : owned,
-  })) {
+  for (const name of args.configImports === false
+    ? []
+    : await configImportOwners({
+        workspaceRoot: args.workspaceRoot,
+        projects: projects,
+        changed,
+        skip: perTask ? new Set() : owned,
+      })) {
     owned.add(name)
     whole.add(name)
   }
@@ -679,43 +691,35 @@ async function gitDiffPaths(
 }
 
 /**
- * Resolve the default base for `--affected` with no explicit value.
- * Tries the remote's HEAD branch first (`origin/main`, `origin/master`,
- * etc.), then `origin/main`, `origin/master`, `main`, `master`, then
- * falls back to `HEAD~1`. A clone with no `origin/HEAD` and
- * no parent commit — a CI checkout at `fetch-depth: 1` — has no base at
- * all, and says so here rather than failing on a ref nobody typed.
+ * The base a bare `--affected` compares with: the merge base of HEAD and
+ * the base branch (`origin/<baseBranch>`, or the local branch in a clone
+ * with no remote; its tip when they share no history). On the base branch
+ * itself there is none (owner, 2026-10-17): what a push to main changed
+ * is the last good commit's to say (`--affected=<sha>`), and `HEAD~1`
+ * guessed it wrong after any multi-commit push.
  */
-export async function defaultAffectedBase(workspaceRoot: string): Promise<string> {
-  const probe = spawnGitSync(
-    ['symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD'],
-    workspaceRoot,
-    'ignore',
-  )
-  const out = new TextDecoder().decode(probe.stdout).trim()
-  // An origin/HEAD naming a branch the remote deleted (a pruned fetch keeps
-  // the symref) is no base either: it failed as `git ref "origin/master" did
-  // not resolve`, a ref nobody typed, where an unset one falls back.
-  if (probe.exitCode === 0 && out.length > 0 && revParse(workspaceRoot, out) !== undefined) {
-    return out
-  }
-  // No origin/HEAD: `git remote add` + fetch, as actions/checkout does, sets
-  // none, and `HEAD~1` saw only a feature branch's last commit where Turbo
-  // and Nx compare with `main` (D-93). The usual trunk names, remote first;
-  // one that IS HEAD (a push to main) falls through to `HEAD~1` as before.
-  const trunk = trunkBase(workspaceRoot)
-  if (trunk !== undefined) return trunk
-  if (revParse(workspaceRoot, 'HEAD~1') === undefined) {
+export async function defaultAffectedBase(
+  workspaceRoot: string,
+  baseBranch: string | undefined,
+): Promise<string> {
+  const found = await baseBranchRef(workspaceRoot, baseBranch)
+  if (found === undefined) {
     const noHistory = noHistoryRefusal(workspaceRoot)
     if (noHistory !== undefined) throw noHistory
     throw new UserError(
-      '--affected has no base here: origin/HEAD is not set (or names a branch that is gone) and HEAD has no parent to compare ' +
-        'with — a shallow clone? Fetch history (actions/checkout: fetch-depth: 0) or name the ' +
-        'base: --affected=origin/main',
+      `--affected has no base here: ${baseBranch === undefined ? 'no origin/HEAD, main or master' : `no ${baseBranch} or origin/${baseBranch}`} ` +
+        'to compare with — a shallow clone? Fetch history (actions/checkout: fetch-depth: 0), ' +
+        'set `baseBranch`, or name the base: --affected=origin/main',
+      'VX_E_AFFECTED_BASE',
+    )
+  }
+  if (found.onIt) {
+    throw new UserError(
+      `--affected has no default on the base branch (${found.branch}): name the last good commit, --affected=<sha>`,
       'VX_E_AFFECTED_BASE',
     )
   }
-  return 'HEAD~1'
+  return found.ref
 }
 
 /**
@@ -737,30 +741,83 @@ function noHistoryRefusal(workspaceRoot: string): UserError | undefined {
   return undefined
 }
 
-const TRUNKS = ['origin/main', 'origin/master', 'main', 'master']
+/**
+ * What a branch changed, for which of its tasks read its cache scope
+ * (owner, 2026-10-17): from `base` (a plugin's: a pull request's base
+ * commit), else from the merge base with the base branch. No base, or
+ * one git cannot resolve (a CI checkout at `fetch-depth: 1`), is no
+ * change: every task reads the default key, which costs hits, never
+ * correctness, since a key must still match.
+ */
+export async function branchChanges(
+  workspaceRoot: string,
+  base: string | undefined,
+  baseBranch: string | undefined,
+  projects: Promise<readonly ProjectMeta[]>,
+  /** The run's own enumeration, so the diff walks nothing a second time. */
+  walked: Pick<AffectedArgs, 'untracked' | 'links'> = {},
+): Promise<AffectedChanges> {
+  const none: AffectedChanges = {
+    projects: new Set(),
+    changed: [],
+    paths: new Map(),
+    whole: new Set(),
+  }
+  const since = base ?? (await baseBranchRef(workspaceRoot, baseBranch))?.ref
+  if (since === undefined) return none
+  try {
+    return await affectedChanges({
+      workspaceRoot,
+      since,
+      projects,
+      configImports: false,
+      ...walked,
+    })
+  } catch (err) {
+    if (!isUserError(err)) throw err
+    return none
+  }
+}
 
-/** The first of `TRUNKS` that exists and is not HEAD's commit, in one spawn. */
-function trunkBase(workspaceRoot: string): string | undefined {
-  const proc = spawnGitSync(
-    [
+/**
+ * The base branch as a ref: `origin/<name>`, else the local branch (a
+ * clone with no remote), and whether HEAD is on it. The name is the
+ * configured one, else `origin/HEAD`'s, else `main`, else `master`. Its
+ * spawns run at once, off the event loop.
+ */
+async function baseBranchRef(
+  workspaceRoot: string,
+  configured: string | undefined,
+): Promise<{ ref: string; branch: string; onIt: boolean } | undefined> {
+  const text = async (args: string[]): Promise<string> => {
+    const proc = spawnGit(args, workspaceRoot)
+    const [out, exit] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+    return exit === 0 ? out.trim() : ''
+  }
+  const names = configured === undefined ? ['main', 'master'] : [configured]
+  const [remoteHead, refs, head] = await Promise.all([
+    configured === undefined
+      ? text(['symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD'])
+      : Promise.resolve(''),
+    text([
       'for-each-ref',
-      '--format=%(refname:short) %(objectname)',
+      '--format=%(refname:short)',
       '--end-of-options',
-      ...TRUNKS.map((t) => (t.startsWith('origin/') ? `refs/remotes/${t}` : `refs/heads/${t}`)),
-    ],
-    workspaceRoot,
-    'ignore',
-  )
-  if (proc.exitCode !== 0) return undefined
-  const at = new Map(
-    new TextDecoder()
-      .decode(proc.stdout)
-      .split('\n')
-      .filter((l) => l !== '')
-      .map((l) => l.split(' ') as [string, string]),
-  )
-  const head = revParse(workspaceRoot, 'HEAD')
-  return TRUNKS.find((t) => at.has(t) && at.get(t) !== head)
+      ...(configured === undefined
+        ? ['refs/remotes/origin']
+        : [`refs/remotes/origin/${configured}`]),
+      ...names.map((n) => `refs/heads/${n}`),
+    ]),
+    text(['symbolic-ref', '--short', '-q', 'HEAD']),
+  ])
+  const have = new Set(refs.split('\n'))
+  const at = (branch: string, ref: string) => ({ ref, branch, onIt: head === branch })
+  if (remoteHead.startsWith('origin/') && have.has(remoteHead)) {
+    return at(remoteHead.slice('origin/'.length), remoteHead)
+  }
+  for (const n of names) if (have.has(`origin/${n}`)) return at(n, `origin/${n}`)
+  for (const n of names) if (have.has(n)) return at(n, n)
+  return undefined
 }
 
 /**

package/src/workspace/config-schema.ts

@@ -44,14 +44,39 @@ import { nonJsonMessage, nonJsonPaths } from './json-data.js'
 // declared no plugins and ran the workspace bare, `cacheDirectory` left the
 // cache where it was — a config that loads and quietly does nothing it says.
 const CACHE_SCOPE_RULE =
-  "must be a scope name of letters, digits and . _ - / @ (at most 128), like 'pr-123'"
+  "must be a scope name of letters, digits and . _ - / @ : (at most 128), like 'vznjs/vx:feat-x'"
 
-/** `cache.scope`'s rule, shared with `VX_CACHE_SCOPE`. */
+/** A cache scope's rule, for `VX_CACHE_SCOPE` and a plugin's `setBranch`. */
 export function isCacheScope(v: unknown): v is string {
-  return typeof v === 'string' && /^[\w.@/-]{1,128}$/.test(v)
+  return typeof v === 'string' && /^[\w.@/:-]{1,128}$/.test(v)
 }
 
-/** Why a `VX_CACHE_SCOPE` or `--cache-scope` value is refused, in `cache.scope`'s words. */
+/**
+ * A branch's cache scope, `<owner>/<repo>:<branch>`: what CI writes for a
+ * branch and a laptop on it reads (owner, 2026-10-17). The repository's
+ * identity, not a remote's local name, so a clone whose `origin` is a fork
+ * names the fork. A name may hold characters a scope may not; each
+ * becomes `_`.
+ */
+const BASE_BRANCH_RULE = "must be a branch name like 'main'"
+
+/**
+ * A branch name git takes after `origin/`: a leading '-' would reach git
+ * as an option, and whitespace, `..`, `~^:?*[\\` are no ref's.
+ */
+function isBaseBranch(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    /^[^-\s\0~^:?*[\\][^\s\0~^:?*[\\]*$/.test(value) &&
+    !value.includes('..')
+  )
+}
+
+export function branchCacheScope(repo: string, branch: string): string {
+  return `${repo.toLowerCase()}:${branch}`.replace(/[^\w.@/:-]/g, '_').slice(0, 128)
+}
+
+/** Why a `VX_CACHE_SCOPE` value is refused. */
 export function cacheScopeError(source = 'VX_CACHE_SCOPE'): string {
   return `${source} ${CACHE_SCOPE_RULE}`
 }
@@ -61,6 +86,15 @@ export function cacheScopeEnvError(): UserError {
   return new UserError(cacheScopeError())
 }
 
+/** `baseBranch`: `VX_BASE_BRANCH`, else the workspace's; undefined lets git name it. */
+export function configuredBaseBranch(workspace: WorkspaceConfig | null): string | undefined {
+  const env = settingEnv('baseBranch')
+  if (env !== undefined && !isBaseBranch(env)) {
+    throw new UserError(`VX_BASE_BRANCH ${BASE_BRANCH_RULE}`, 'VX_E_USAGE')
+  }
+  return (env as string | undefined) ?? workspace?.baseBranch
+}
+
 const STRATEGIES = ['immutable', 'mutable', 'unchecked'] as const
 const SEVERITIES = ['warn', 'error'] as const
 const INPUT_STABILITY_FIELDS = new Set(['strategy', 'severity'])
@@ -98,7 +132,7 @@ export function inputStabilityEnv(): InputStability {
   }
 }
 
-const WORKSPACE_FIELDS = new Set<string>([...SETTING_GROUPS, 'plugins'])
+const WORKSPACE_FIELDS = new Set<string>([...SETTING_GROUPS, 'baseBranch', 'plugins'])
 
 /**
  * `.vx/workspace`'s settings, as `src/settings.ts` lists them: each group's
@@ -126,7 +160,7 @@ function validateSettingsAt(value: unknown, at: string, configPath: string): voi
       if (at === 'cache')
         // Turbo's and Nx's workspace `cache: true` is a task's own `cache` in vx (D-98).
         throw new UserError(
-          `${where} must be an object like { dir, policy, scope }; a task caches through its own \`cache\` in its project's vx.config`,
+          `${where} must be an object like { dir, policy }; a task caches through its own \`cache\` in its project's vx.config`,
         )
       throw new UserError(`${where} must be an object (fields: ${[...fields].join(', ')})`)
     }
@@ -197,18 +231,12 @@ function validateSettingsExtra(config: WorkspaceConfig, configPath: string): voi
     // unwritable workspace.
     throw new UserError(`${configPath}: \`cache.dir\` holds a NUL, which no path can carry`)
   }
-  const base = config.run?.affectedBase
-  // A leading '-' would reach git as an option, not a ref; a NUL fails the
-  // spawn with an argument error naming nothing in this file.
-  if (base !== undefined && !/^[^-\s\0][^\s\0]*$/.test(base)) {
-    throw new UserError(`${configPath}: \`run.affectedBase\` must be a git ref like 'origin/main'`)
+  const base = config.baseBranch
+  if (base !== undefined && !isBaseBranch(base)) {
+    throw new UserError(`${configPath}: \`baseBranch\` ${BASE_BRANCH_RULE}`)
   }
   // `policy`'s grammar is the cache module's (`parseCachePolicy`), which
   // this module may not import: the run parses it before any task (prepare.ts).
-  const scope = config.cache?.scope
-  if (scope !== undefined && !isCacheScope(scope)) {
-    throw new UserError(`${configPath}: \`cache.scope\` ${CACHE_SCOPE_RULE}`)
-  }
   if (config.cache?.retention !== undefined) validateRetention(config.cache.retention, configPath)
 }
 
@@ -1103,7 +1131,7 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
         'a cache plugin in `plugins` (`turboCache()` or `nxCache()` from `@vzn/vx-migrate`)',
       parallel: '`run.concurrency`',
       cacheDirectory: '`cache.dir`',
-      defaultBase: '`run.affectedBase`',
+      defaultBase: '`baseBranch`',
       tasksRunnerOptions: 'a cache plugin in `plugins` (`nxCache()` from `@vzn/vx-migrate`)',
       globalPassThroughEnv: '`exec.env.passThrough` on the tasks it passes to',
       // pnpm-workspace.yaml's, Lerna's and the package.json's own keys

package/src/workspace/index.ts

@@ -6,6 +6,7 @@ export {
   type AffectedChanges,
   affectedProjects,
   defaultAffectedBase,
+  branchChanges,
   type FingerprintClaims,
   refIsHead,
 } from './affected.js'
@@ -35,8 +36,10 @@ export {
   WORKSPACE_CONFIG_FILENAMES,
 } from './project-loader.js'
 export {
+  branchCacheScope,
   cacheScopeEnvError,
   cacheScopeError,
+  configuredBaseBranch,
   inputStabilityEnv,
   isCacheScope,
   taskNameProblem,