@vzn/vx 0.0.508 → 0.0.510

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.508",
+  "version": "0.0.510",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.508",
-    "@vzn/vx-linux-arm64": "0.0.508",
-    "@vzn/vx-darwin-x64": "0.0.508",
-    "@vzn/vx-darwin-arm64": "0.0.508"
+    "@vzn/vx-linux-x64": "0.0.510",
+    "@vzn/vx-linux-arm64": "0.0.510",
+    "@vzn/vx-darwin-x64": "0.0.510",
+    "@vzn/vx-darwin-arm64": "0.0.510"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/index.ts

@@ -33,6 +33,7 @@ export { ABSENT_INPUT, absentOr, CACHE_VERSION } from './key-fold.js'
 export {
   cleanOutputs,
   cleanWorkspaceOutputs,
+  declaresInput,
   resolveInputs,
   resolveOutputs,
   resolveWorkspaceOutputs,

package/src/cache/inputs.ts

@@ -19,7 +19,7 @@
 import path from 'node:path'
 import { lstatSync, readdirSync, realpathSync, rmdirSync, rmSync } from 'node:fs'
 import { rm, rmdir } from 'node:fs/promises'
-import type { CacheInputs } from '../config.js'
+import type { CacheConfig, CacheInputs } from '../config.js'
 import {
   asTrees,
   isExecutableMissing,
@@ -1124,6 +1124,61 @@ function filesPlan(
   return plan
 }
 
+/**
+ * Whether a changed path is one of a cached task's declared file inputs:
+ * `projectRel` (the path relative to the project that owns it) against
+ * `files`, `workspaceRel` (relative to the workspace root) against
+ * `workspaceFiles`; null skips that half, by the globs, `!` exclusions and own-output takebacks
+ * the key resolves. `--affected` seeds a task with it (owner, 2026-10-04).
+ */
+export function declaresInput(
+  cache: CacheConfig,
+  projectRel: string | null,
+  workspaceRel: string | null,
+): boolean {
+  if (projectRel !== null) {
+    const plan = filesPlan(cache.inputs.files, cache.outputs.files)
+    if (plan !== null && inPlan(plan, projectRel)) return true
+  }
+  const ws = cache.inputs.workspaceFiles
+  if (workspaceRel === null || ws === undefined || ws.length === 0) return false
+  const matcher = workspaceMatcher(ws, cache.outputs.workspaceFiles ?? [])
+  return matcher(workspaceRel)
+}
+
+function inPlan(plan: FilesPlan, rel: string): boolean {
+  let input = plan.verdicts.get(rel)
+  if (input === undefined) {
+    input =
+      plan.positiveGlobs.some((g) => g.match(rel)) &&
+      !plan.excludeGlobs.some((g) => g.match(rel)) &&
+      !plan.ownOutput(rel)
+    plan.verdicts.set(rel, input)
+  }
+  return input
+}
+
+const workspaceMatchers = new Map<string, (rel: string) => boolean>()
+
+function workspaceMatcher(
+  decl: readonly string[],
+  ownOutputs: readonly string[],
+): (rel: string) => boolean {
+  const key = JSON.stringify([decl, ownOutputs])
+  let m = workspaceMatchers.get(key)
+  if (m !== undefined) return m
+  const { positive, negative } = splitNegations(decl)
+  const positiveGlobs = asTrees(positive).map(globFor)
+  const excludeGlobs = [...ALWAYS_IGNORE, ...asTrees(negative)].map(globFor)
+  const ownOutput = outputMatcher(ownOutputs, globFor)
+  m = (rel) =>
+    positiveGlobs.some((g) => g.match(rel)) &&
+    !excludeGlobs.some((g) => g.match(rel)) &&
+    !ownOutput(rel)
+  workspaceMatchers.set(key, m)
+  return m
+}
+
 async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   const plan = filesPlan(args.files, args.ownOutputs)
   if (plan === null) return []

package/src/cli/run.ts

@@ -470,6 +470,7 @@ export async function resolveRunOptions(
   // drops app from either side (item 955 had put it first for that). First
   // it stays, so a message naming the filters names it first.
   const filterStrings = [...parsed.filters]
+  let affectedFilter: string | undefined
   if (parsed.affected !== undefined) {
     const root = await findWorkspaceRoot(cwd)
     let base = parsed.affected
@@ -484,7 +485,8 @@ export async function resolveRunOptions(
         return { error: err.message }
       }
     }
-    filterStrings.unshift(`...[${base}]`)
+    affectedFilter = `...[${base}]`
+    filterStrings.unshift(affectedFilter)
   }
 
   // Project scope applies to bare task names only. Anchored entries
@@ -495,13 +497,19 @@ export async function resolveRunOptions(
   let staged: RunOptions['staged']
   let discovered: RunOptions['discovered']
   let selectedByDiff = false
+  let affected: RunOptions['affected']
   if (bareTasks.length === 0) {
     projects = undefined
   } else if (filterStrings.length > 0) {
-    const resolved = await resolveFilters(cwd, filterStrings, {
-      ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
-      ...(parsed.frozen ? { frozen: true } : {}),
-    })
+    const resolved = await resolveFilters(
+      cwd,
+      filterStrings,
+      {
+        ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+        ...(parsed.frozen ? { frozen: true } : {}),
+      },
+      affectedFilter,
+    )
     if ('error' in resolved) return { error: resolved.error }
     if ('empty' in resolved) {
       // "Nothing changed" is a clean exit for the BARE tasks the filter
@@ -519,6 +527,7 @@ export async function resolveRunOptions(
       // instead of evaluating and staging them a second time.
       staged = resolved.staged
       discovered = resolved.discovered
+      affected = resolved.affected
     }
   } else if (parsed.all) {
     projects = undefined
@@ -563,6 +572,7 @@ export async function resolveRunOptions(
   }
   if (projects !== undefined) opts.projects = projects
   if (selectedByDiff) opts.selectedByDiff = true
+  if (affected !== undefined) opts.affected = affected
   if (staged !== undefined) opts.staged = staged
   if (discovered !== undefined) opts.discovered = discovered
   if (parsed.retries !== undefined) opts.retries = parsed.retries

package/src/cli/select.ts

@@ -6,6 +6,8 @@
 import path from 'node:path'
 import fs from 'node:fs'
 import {
+  affectedChanges,
+  type AffectedChanges,
   affectedProjects,
   refIsHead,
   applyFilters,
@@ -29,6 +31,7 @@ import {
   claimedAffected,
   fingerprintClaims,
   gitOfDiscovery,
+  isDefaultBuild,
   keepDiscoveryGraph,
 } from '../orchestrator/index.js'
 import {
@@ -177,6 +180,8 @@ export type FilterResolution =
       staged?: ReadonlyMap<string, ProjectEntry>
       /** The discovery this pass made, for the run to reuse (`RunOptions.discovered`). */
       discovered: { root: string; projects: ProjectMeta[] }
+      /** The `affected` filter's diff, for the run to seed its tasks from (`RunOptions.affected`). */
+      affected?: AffectedChanges
     }
   | { error: string }
   | { empty: string }
@@ -224,6 +229,8 @@ export async function resolveFilters(
   cwd: string,
   raw: string[],
   load: CliLoadOptions = {},
+  /** The raw filter `--affected` became: its diff is kept per path for the run. */
+  affected?: string,
 ): Promise<FilterResolution> {
   const root = await findWorkspaceRoot(cwd)
   const projects = await loadWorkspaceProjects(cwd)
@@ -273,19 +280,27 @@ export async function resolveFilters(
   // applyFilters pass runs. One spawn per distinct ref — usually
   // there's only one anyway.
   const affectedByFilter = new Map<(typeof parsed)[number], Set<string>>()
+  let changes: AffectedChanges | undefined
   for (const f of parsed) {
     if (f.gitSince === undefined) continue
     try {
-      const names = await affectedProjects({
+      const args = {
         workspaceRoot: root,
         since: f.gitSince,
         projects,
-        workspaceGlobOwners: (changed) =>
+        workspaceGlobOwners: (changed: readonly string[]) =>
           workspaceGlobOwners(root, projects, changed, load, stagedOnce),
         fingerprintClaims: () => workspaceFingerprintClaims(root, projects, load),
         taskEdges: async () => edges ?? taskEdgesFrom(await stagedOnce()),
         ...(git !== undefined ? { untracked: async () => (await git.start()).untracked } : {}),
-      })
+      }
+      let names: Set<string>
+      if (f.raw === affected) {
+        changes = await affectedChanges(args)
+        names = changes.projects
+      } else {
+        names = await affectedProjects(args)
+      }
       affectedByFilter.set(f, names)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
@@ -366,6 +381,7 @@ export async function resolveFilters(
     byDiff: parsed.some((f) => !f.negate && f.gitSince !== undefined),
     ...(staged !== undefined ? { staged } : {}),
     discovered: { root, projects },
+    ...(changes !== undefined ? { affected: changes } : {}),
   }
 }
 
@@ -392,7 +408,9 @@ export async function pickTask(
   for (const meta of projects) {
     const config = staged.get(meta.name)?.config
     if (config === undefined) continue
-    const taskNames = Object.keys(config.tasks ?? {}).sort()
+    const taskNames = Object.keys(config.tasks ?? {})
+      .filter((t) => !isDefaultBuild(config.tasks?.[t]))
+      .sort()
     for (const t of taskNames) {
       const desc = config.tasks?.[t]?.description
       entries.push({ project: meta.name, task: t, ...(desc ? { description: desc } : {}) })

package/src/cli/task-verb.ts

@@ -4,7 +4,7 @@
 // does it. It stays a refusal: a verb that runs whatever task shares its
 // name would change meaning the day a plugin declares that verb.
 
-import { nxProjectTarget, projectNamed } from '../orchestrator/index.js'
+import { isDefaultBuild, nxProjectTarget, projectNamed } from '../orchestrator/index.js'
 import { findWorkspaceRoot, loadWorkspace } from '../workspace/index.js'
 import { nearest } from '../util/index.js'
 import { findCwdProject } from './select.js'
@@ -66,7 +66,8 @@ export async function taskNamesHere(cwd: string): Promise<string[] | null> {
   const names = new Set<string>()
   for (const p of projects.values())
     if (own === null || p.name === own)
-      for (const t of Object.keys(p.config.tasks ?? {})) names.add(t)
+      for (const [t, task] of Object.entries(p.config.tasks ?? {}))
+        if (!isDefaultBuild(task)) names.add(t)
   return [...names].sort()
 }
 

package/src/index.ts

@@ -65,6 +65,8 @@ export { run, planRun, prepareRun } from './orchestrator/index.js'
 export { LocalHistoryProvider } from './orchestrator/index.js'
 export type { HistoryProvider, HistoryTable, TaskHistory } from './orchestrator/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
+// `RunOptions.affected`: what `--affected`'s diff changed, per project.
+export type { AffectedChanges } from './workspace/index.js'
 // `planRun` returns these, and an embedder that cannot NAME a return type
 // cannot hold it: `run` and `prepareRun` both had theirs here from the
 // start, so the omission read as "planRun is not really public" while

package/src/orchestrator/affected-tasks.ts

@@ -0,0 +1,113 @@
+// `--affected` per task (owner, 2026-10-04). The diff seeds the tasks it
+// reaches; a requested task runs when its `dependsOn` closure holds one.
+// So a change reaches another project only along a task edge: `web#test`
+// behind `^build` runs when `ui#build` (or what it depends on) is reached,
+// and a spec edit `ui#build`'s inputs leave out stops at `ui`'s own tasks.
+
+import { declaresInput } from '../cache/index.js'
+import {
+  compileTaskPattern,
+  isGroupTask,
+  isTaskPattern,
+  parseDependencySpec,
+  type TaskNode,
+} from '../graph/index.js'
+import {
+  type AffectedChanges,
+  type PackageGraph,
+  PROJECT_CONFIG_FILENAMES,
+  type ProjectEntry,
+} from '../workspace/index.js'
+
+/** Every file in this set re-keys each of its project's tasks, whatever their inputs. */
+const KEYED_BY_EVERY_TASK = new Set(['package.json', ...PROJECT_CONFIG_FILENAMES])
+
+/**
+ * The projects every task of which the change reaches: the whole ones the
+ * diff named, and those holding a changed path no cached task of theirs
+ * declares as an input. vx cannot prove such a path re-keys nothing (a
+ * `project` plugin may read it), so it reaches the whole project, as it did
+ * before selection was per task.
+ */
+function wholeProjects(
+  changes: AffectedChanges,
+  projects: ReadonlyMap<string, ProjectEntry>,
+): Set<string> {
+  const whole = new Set(changes.whole)
+  for (const [name, rels] of changes.paths) {
+    if (whole.has(name)) continue
+    const caches = Object.values(projects.get(name)?.config.tasks ?? {}).flatMap((t) =>
+      t.exec !== undefined && t.cache !== undefined ? [t.cache] : [],
+    )
+    const unclaimed = (rel: string): boolean =>
+      KEYED_BY_EVERY_TASK.has(rel) || !caches.some((c) => declaresInput(c, rel, null))
+    if (rels.some(unclaimed)) whole.add(name)
+  }
+  return whole
+}
+
+/**
+ * The task ids of `ids` whose closure the change reaches, in their order.
+ * A group seeds nothing (it runs nothing) unless it is keyed, as the default
+ * `build` is; an uncached task seeds whenever its project changed; a cached
+ * one when a changed path is one of its declared inputs. A `^name` edge the
+ * graph passes through a package it loaded no config for reaches it as the
+ * default `build` would: any change there reaches the task.
+ */
+export function affectedRoots(
+  nodes: ReadonlyMap<string, TaskNode>,
+  ids: readonly string[],
+  changes: AffectedChanges,
+  projects: ReadonlyMap<string, ProjectEntry>,
+  packageGraph: PackageGraph,
+): string[] {
+  const whole = wholeProjects(changes, projects)
+  // The builder's `^name` walk (task-graph.ts), keeping only the packages
+  // it passes through: a holder's own node is already in `deps`.
+  const passesChanged = (n: TaskNode): boolean => {
+    for (const raw of n.config.dependsOn ?? []) {
+      const spec = parseDependencySpec(raw)
+      if (spec.kind !== 'deps' || spec.negated) continue
+      const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
+      const holds = (name: string): boolean => {
+        const tasks = Object.keys(projects.get(name)?.config.tasks ?? {})
+        return re === null ? tasks.includes(spec.task) : tasks.some((t) => re.test(t))
+      }
+      const visited = new Set([n.projectName])
+      const frontier = [...packageGraph.directDeps(n.projectName)]
+      while (frontier.length > 0) {
+        const target = frontier.pop()!
+        if (visited.has(target)) continue
+        visited.add(target)
+        if (holds(target)) continue
+        if (changes.projects.has(target)) return true
+        frontier.push(...packageGraph.directDeps(target))
+      }
+    }
+    return false
+  }
+  const seeded = (n: TaskNode): boolean => {
+    if (!changes.projects.has(n.projectName)) return false
+    const cache = n.config.cache
+    // A group runs nothing; only the default `build` (projects.ts) is keyed.
+    if (cache === undefined) return !isGroupTask(n)
+    if (whole.has(n.projectName)) return true
+    if ((changes.paths.get(n.projectName) ?? []).some((rel) => declaresInput(cache, rel, null))) {
+      return true
+    }
+    return changes.changed.some((rel) => declaresInput(cache, null, rel))
+  }
+  const reached = new Map<string, boolean>()
+  const reaches = (id: string): boolean => {
+    const known = reached.get(id)
+    if (known !== undefined) return known
+    // The graph is acyclic (the builder refuses a cycle); the mark only
+    // stops a diamond being walked twice.
+    reached.set(id, false)
+    const n = nodes.get(id)
+    const hit = n !== undefined && (seeded(n) || passesChanged(n) || n.deps.some(reaches))
+    reached.set(id, hit)
+    return hit
+  }
+  return ids.filter(reaches)
+}

package/src/orchestrator/excluded-keys.ts

@@ -15,7 +15,7 @@
 
 import type { CacheLayer, GitFilesCache } from '../cache/index.js'
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
-import { computeGroupHash, computeTaskHash, type HashCache } from './task-hash.js'
+import { computeGroupKey, computeTaskHash, type HashCache } from './task-hash.js'
 import { filterUpstreamHashes, keyedDeps } from './upstream.js'
 
 export interface KeyExcludedArgs {
@@ -53,8 +53,7 @@ export async function keyExcludedDependencies(args: KeyExcludedArgs): Promise<vo
     Promise.all(ids.map(async (id) => synthetic(nodeOf(id), await keys.get(id)!)))
   const derive = async (node: TaskNode): Promise<string | undefined> => {
     const upstream = await outcomes(fullDeps(node))
-    if (isGroupTask(node)) return computeGroupHash(upstream)
-    return computeTaskHash({
+    return (isGroupTask(node) ? computeGroupKey : computeTaskHash)({
       node,
       upstream,
       workspaceRoot: args.workspaceRoot,

package/src/orchestrator/execute-task.ts

@@ -72,7 +72,7 @@ export { restoreHit, type RestoreHitArgs } from './hit-restore.js'
 import type { DeferredOutputs } from './deferred-outputs.js'
 import type { Logger } from './logger.js'
 import {
-  computeGroupHash,
+  computeGroupKey,
   computeTaskHash,
   describeTaskInputs,
   type HashCache,
@@ -249,14 +249,25 @@ export async function executeTask(args: ExecuteArgs): Promise<TaskOutcome> {
  * from upstream outcomes so downstream cache keys still cascade
  * through us.
  */
-function executeGroupTask(args: ExecuteArgs): TaskOutcome {
+async function executeGroupTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const wallclockNs = process.hrtime.bigint() - args.runStartHrTimeNs
+  const hash = await computeGroupKey({
+    node: args.node,
+    upstream: args.upstream,
+    workspaceRoot: args.workspaceRoot,
+    workspaceFingerprint: args.workspaceFingerprint,
+    cache: args.cache,
+    forwardArgs: args.forwardArgs,
+    nestedProjectDirs: args.nestedProjectDirs,
+    ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+    ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
+  })
   return {
     node: args.node,
     status: 'success',
     exitCode: 0,
     durationMs: 0,
-    hash: computeGroupHash(args.upstream),
+    hash,
     // What this group stands for. A dependent expands it to describe the
     // real tasks in its input closure — see `TaskOutcome.groupUpstream`.
     groupUpstream: args.upstream,

package/src/orchestrator/index.ts

@@ -6,6 +6,7 @@ export { prepareRun, type PreparedRun } from './prepare.js'
 export {
   discoverProjects,
   gitOfDiscovery,
+  isDefaultBuild,
   keepDiscoveryGraph,
   loadProjects,
   loadResolvedProjects,

package/src/orchestrator/keyed-projects.ts

@@ -16,8 +16,9 @@ import { keyedDeps, selectFoldedDeps, type FoldCandidate } from './upstream.js'
  * The fold relation is the hash path's, computed on the graph:
  *   - an exec task folds its dependencies as its own `cache.inputs.tasks`
  *     selects them (absent, or no `cache` at all, means all);
- *   - a group folds every dependency (`computeGroupHash`) and folds no
- *     files of its own;
+ *   - a group folds every dependency (`computeGroupKey`) and folds no
+ *     files of its own, but for the default `build`, which folds every
+ *     file of its project as a task does;
  *   - a persistent task is keyed as a task with no `cache` (A-17).
  *
  * Every exec task reached contributes its project, cached or not: a key
@@ -56,7 +57,7 @@ export function keyedProjects(
       stack.pop()
       const out = new Set<string>()
       for (const { node: dep } of deps) {
-        if (!isGroupTask(dep)) out.add(dep.projectDir)
+        if (!isGroupTask(dep) || dep.config.cache !== undefined) out.add(dep.projectDir)
         for (const dir of below.get(dep.id)!) out.add(dir)
       }
       below.set(node.id, out)
@@ -83,7 +84,7 @@ function folded(node: TaskNode, nodeOf: (id: string) => TaskNode): FoldCandidate
   for (const { node: dep } of node.excludedUpstream ?? []) {
     candidates.push({ node: dep, unit: foldUnit(dep) })
   }
-  if (isGroupTask(node)) return candidates
+  if (isGroupTask(node) && node.config.cache === undefined) return candidates
   return selectFoldedDeps(candidates, node.config.cache?.inputs?.tasks, node.projectName, node.id)
 }
 
@@ -94,5 +95,7 @@ function folded(node: TaskNode, nodeOf: (id: string) => TaskNode): FoldCandidate
  * with no id of its own, so two groups over the same members hash alike.
  */
 function foldUnit(node: TaskNode): string {
-  return isGroupTask(node) ? `group|${[...node.deps].sort().join('|')}` : `task|${node.id}`
+  return isGroupTask(node) && node.config.cache === undefined
+    ? `group|${[...node.deps].sort().join('|')}`
+    : `task|${node.id}`
 }

package/src/orchestrator/options.ts

@@ -8,7 +8,7 @@ import type { TaskOutcome } from '../graph/index.js'
 import type { EventBus } from './events.js'
 import type { TelemetrySink } from './telemetry.js'
 import type { Logger } from './logger.js'
-import type { ProjectEntry, ProjectMeta } from '../workspace/index.js'
+import type { AffectedChanges, ProjectEntry, ProjectMeta } from '../workspace/index.js'
 
 export interface RunOptions {
   cwd: string
@@ -29,6 +29,12 @@ export interface RunOptions {
    * `vx run test --affected` red (item 1024).
    */
   selectedByDiff?: boolean
+  /**
+   * `--affected`'s diff: a bare requested task runs only when the change
+   * reaches its `dependsOn` closure (`affected-tasks.ts`; owner,
+   * 2026-10-04). `projects` is the candidate set it narrows.
+   */
+  affected?: AffectedChanges
   /**
    * Configs a selection pass in this same process already loaded and
    * staged with the same `cacheDir` and `frozen` (the CLI walks every

package/src/orchestrator/plan.ts

@@ -15,7 +15,7 @@ import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
 import { FULL_CACHE_POLICY } from '../cache/index.js'
 import { isGroupTask, runGraph, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import type { HistoryProvider } from './history.js'
-import { computeGroupHash, computeTaskHash } from './task-hash.js'
+import { computeGroupKey, computeTaskHash } from './task-hash.js'
 import { keyUpstream } from './upstream.js'
 
 export type CacheStatus =
@@ -130,12 +130,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     concurrency: 1,
     execute: async (node, live) => {
       const upstream = keyUpstream(node, live)
-      if (isGroupTask(node)) {
-        cacheStatusById.set(node.id, 'group')
-        return planOutcome(node, computeGroupHash(upstream))
-      }
-
-      const hash = await computeTaskHash({
+      const hashArgs = {
         node,
         upstream,
         workspaceRoot: args.workspaceRoot,
@@ -145,7 +140,13 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
         nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],
         ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
         ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
-      })
+      }
+      if (isGroupTask(node)) {
+        cacheStatusById.set(node.id, 'group')
+        return planOutcome(node, await computeGroupKey(hashArgs))
+      }
+
+      const hash = await computeTaskHash(hashArgs)
 
       // Prediction keys off READS: a no-read policy re-executes every task,
       // so nothing is probed. Whether that run is a miss or no cache at all

package/src/orchestrator/prepare.ts

@@ -65,6 +65,7 @@ import {
   loadWorkspacePlugins,
   type LoadedProjects,
 } from './projects.js'
+import { affectedRoots } from './affected-tasks.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
@@ -159,7 +160,9 @@ export interface PreparedRun {
    *     returns NOT-ok.
    *   - `'none-affected'`     — as `'no-tasks-declared'`, but the scope
    *     came from a diff and every name is declared somewhere else in the
-   *     workspace: nothing changed that runs them, a clean outcome.
+   *     workspace: nothing changed that runs them, a clean outcome. Also
+   *     when `--affected`'s diff reaches no requested task's `dependsOn`
+   *     closure (`affected-tasks.ts`).
    *   - `'empty-graph'`       — `requested` was non-empty but the
    *     graph builder still produced no nodes. Defensive; unreachable
    *     under current `buildTaskGraph` semantics.
@@ -458,36 +461,36 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
 
     // Empty-cases bookkeeping. We still construct the cache + fingerprint
     // so the caller's try/finally pattern can close it uniformly.
-    if (requested.length === 0) {
-      return {
-        workspaceRoot,
-        workspaceConfig,
-        plugins,
-        cacheDir,
-        cache,
-        localCache,
-        hasRemoteLayer,
-        cachePolicy: policy,
-        priorities: new Map(),
-        nodes: new Map(),
-        keyOnly: new Map(),
-        unresolvedTasks,
-        declaredElsewhere,
-        projects,
-        hintProjects,
-        anyProjectConfig: projectsWithConfigs.length > 0,
-        workspaceFingerprint,
-        fingerprintWatch,
-        nestedDirsByProject,
-        gitFilesCache: new GitFilesCache(),
-        hashCache,
-        workspaceProjectCount: projectMetas.length,
-        empty:
-          options.selectedByDiff === true && unresolvedTasks.length === 0
-            ? 'none-affected'
-            : 'no-tasks-declared',
-      }
-    }
+    const emptyRun = (reason?: 'none-affected'): PreparedRun => ({
+      workspaceRoot,
+      workspaceConfig,
+      plugins,
+      cacheDir,
+      cache,
+      localCache,
+      hasRemoteLayer,
+      cachePolicy: policy,
+      priorities: new Map(),
+      nodes: new Map(),
+      keyOnly: new Map(),
+      unresolvedTasks,
+      declaredElsewhere,
+      projects,
+      hintProjects,
+      anyProjectConfig: projectsWithConfigs.length > 0,
+      workspaceFingerprint,
+      fingerprintWatch,
+      nestedDirsByProject,
+      gitFilesCache: new GitFilesCache(),
+      hashCache,
+      workspaceProjectCount: projectMetas.length,
+      empty:
+        reason ??
+        (options.selectedByDiff === true && unresolvedTasks.length === 0
+          ? 'none-affected'
+          : 'no-tasks-declared'),
+    })
+    if (requested.length === 0) return emptyRun()
 
     // The whole graph, whatever `--exclude-dependencies` says: the stages
     // below shape and key the tasks it drops as a full run would, because
@@ -496,15 +499,30 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     // by a config the scope left out, so the builder hands it back instead of
     // refusing it, and the rest decide.
     const unproven: Array<[taskId: string, name: string]> = []
-    const nodes = buildTaskGraph({
-      projects,
-      packageGraph,
-      requested,
-      workspaceRoot,
-      ...(projects.size < projectsWithConfigs.length
-        ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
-        : {}),
-    })
+    const graphOf = (req: typeof requested) =>
+      buildTaskGraph({
+        projects,
+        packageGraph,
+        requested: req,
+        workspaceRoot,
+        ...(projects.size < projectsWithConfigs.length
+          ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
+          : {}),
+      })
+    let nodes = graphOf(requested)
+    // `--affected` keeps a bare request only when the diff reaches its
+    // closure; a `pkg#task` the user named runs as it always does.
+    if (options.affected !== undefined) {
+      const named = new Set(tasks.filter((t) => t.includes('#')))
+      const ids = requested.map((r) => `${r.project}#${r.task}`)
+      const reached = new Set(affectedRoots(nodes, ids, options.affected, projects, packageGraph))
+      const kept = requested.filter((_r, i) => named.has(ids[i]!) || reached.has(ids[i]!))
+      if (kept.length === 0) return emptyRun('none-affected')
+      if (kept.length < requested.length) {
+        unproven.length = 0
+        nodes = graphOf(kept)
+      }
+    }
     if (unproven.length > 0) {
       await refuseUndeclaredDeps(unproven, () =>
         loadProjects({ ...loadArgs, seeds: 'all', closure: false, staged: projects }),

package/src/orchestrator/projects.ts

@@ -5,7 +5,7 @@
 // wrote a `vx.config.ts`.
 
 import path from 'node:path'
-import type { ProjectConfig } from '../config.js'
+import type { ProjectConfig, TaskConfig } from '../config.js'
 import {
   frozenProjectConfigs,
   loadProjectConfigs,
@@ -283,7 +283,8 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
           (plugin) => validateProjectConfig(config, `${where} (after plugin '${plugin.name}')`),
         )
       }
-      const named = rootName === undefined ? config : rootSpelled(config, rootName)
+      const built = withDefaultBuild(config)
+      const named = rootName === undefined ? built : rootSpelled(built, rootName)
       projects.set(meta.name, { name: meta.name, dir: meta.dir, config: named })
       for (const name of crossDepProjects(named)) {
         if (graph !== null) considerWithDeps(graph, name)
@@ -294,6 +295,32 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
   return { projects, configured }
 }
 
+/**
+ * The `build` a project gets when neither its config nor a plugin declared
+ * one (owner, 2026-10-04): a group behind `^build`, keyed on every file of
+ * the project. A package consumed as source then carries its files to every
+ * dependent behind `^build`, in the key and in `--affected`, and the chain
+ * through it to deeper builds holds. The one keyed group: a config cannot
+ * declare `cache` on a group (config-schema.ts), so nothing else is.
+ */
+const DEFAULT_BUILD: TaskConfig = Object.freeze({
+  dependsOn: Object.freeze(['^build']),
+  cache: Object.freeze({
+    inputs: Object.freeze({ files: Object.freeze(['**']) }),
+    outputs: Object.freeze({ files: Object.freeze([]) }),
+  }),
+}) as unknown as TaskConfig
+
+/** The default `build`, which a menu of the tasks a user declared leaves out. */
+export function isDefaultBuild(task: TaskConfig | undefined): boolean {
+  return task === DEFAULT_BUILD
+}
+
+function withDefaultBuild(config: ProjectConfig): ProjectConfig {
+  if (config.tasks?.['build'] !== undefined) return config
+  return { ...config, tasks: { ...config.tasks, build: DEFAULT_BUILD } }
+}
+
 /**
  * `config` with Turbo's `//#task` (in `dependsOn` and `cache.inputs.tasks`)
  * spelled `<root>#task`; the same object when it holds none. A copy, not

package/src/orchestrator/run.ts

@@ -385,7 +385,19 @@ async function runOnBus(
     return { ok: false, outcomes: [], refused }
   }
   if (prepared.empty === 'none-affected') {
-    log.status(`No affected project declares task(s): ${options.tasks.join(', ')}.`)
+    // A changed project declares the task, so `--affected`'s task walk is
+    // what left nothing (affected-tasks.ts), not the scope.
+    const inScope = new Set(options.projects ?? [])
+    const reachedNone =
+      options.affected !== undefined &&
+      [...prepared.projects.values()].some(
+        (p) => inScope.has(p.name) && options.tasks.some((t) => p.config.tasks?.[t] !== undefined),
+      )
+    log.status(
+      reachedNone
+        ? `Nothing affected: the change reaches no ${options.tasks.join(', ')} task.`
+        : `No affected project declares task(s): ${options.tasks.join(', ')}.`,
+    )
     await teardown()
     prepared.cache.close()
     return { ok: true, outcomes: [] }

package/src/orchestrator/stable-keys.ts

@@ -15,7 +15,7 @@ import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import type { CacheLayer, GitFilesCache } from '../cache/index.js'
 import { isLiteralPattern, normalizeGlob, relPosix } from '../util/index.js'
 import { commandWriteReach, mayWriteFingerprint, undeclaredWriteReach } from './sandbox-request.js'
-import { computeGroupHash, computeTaskHash, type HashCache } from './task-hash.js'
+import { computeGroupKey, computeTaskHash, type HashCache } from './task-hash.js'
 import { filterUpstreamHashes, keyUpstream } from './upstream.js'
 
 export interface DeriveStableKeysArgs {
@@ -208,7 +208,20 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       // dependents that filter inputs.tasks through the group still
       // cascade (and forward their producers, above). They inherit
       // instability from any unstable member.
-      keyById.set(id, computeGroupHash(upstream))
+      keyById.set(
+        id,
+        await computeGroupKey({
+          node,
+          upstream,
+          workspaceRoot: args.workspaceRoot,
+          workspaceFingerprint: args.workspaceFingerprint,
+          cache: args.cache,
+          forwardArgs: args.forwardArgs,
+          nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],
+          gitFilesCache: args.gitFilesCache,
+          hashCache: args.hashCache,
+        }),
+      )
       if (node.deps.some((d) => unstableById.has(d))) unstableById.add(id)
       continue
     }

package/src/orchestrator/task-hash.ts

@@ -100,7 +100,7 @@ export interface ComputeHashArgs {
  * Caller is responsible for handling the group-task case before
  * calling this — groups have no `exec` and no `cache.inputs`, so the
  * key-derivation steps below would all fall back to defaults.
- * `computeGroupHash` is exported for that purpose.
+ * `computeGroupKey` is exported for that purpose.
  */
 export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   const end = span('task hash')
@@ -380,7 +380,8 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
  * in place. Its one behavioural case is a config with NO `exec`, where
  * the spread would add `exec: {}` — and nothing reaches here that way,
  * proven by throwing on a no-exec config and running the whole suite:
- * a group takes `computeGroupHash` instead. `timeout`/`retries` stay folded — their keys are
+ * a group takes `computeGroupKey`, and the one keyed group (the default
+ * `build`) declares no `remote`. `timeout`/`retries` stay folded — their keys are
  * distinct by design (see the decision log); stripping them retroactively
  * would bump CACHE_VERSION.
  */
@@ -390,6 +391,16 @@ function hashableConfig(cfg: TaskConfig): unknown {
   return { ...cfg, exec: execRest }
 }
 
+/**
+ * A group's key: its upstream, and for a keyed group — the default
+ * `build` (projects.ts), the one group with `cache` — its own inputs too,
+ * the way a task's key folds them.
+ */
+export async function computeGroupKey(args: ComputeHashArgs): Promise<string> {
+  if (args.node.config.cache === undefined) return computeGroupHash(args.upstream)
+  return computeTaskHash(args)
+}
+
 /**
  * Derive a stable hash for a group task (no `exec`) from its upstream
  * outcomes. Lets downstream tasks that filter `inputs.tasks` to

package/src/workspace/affected.ts

@@ -15,6 +15,7 @@ import {
   UserError,
   gitSpawnRefusal,
   isExecutableMissing,
+  relPosix,
   taskGlob,
 } from '../util/index.js'
 import { LOCKFILE_NAME } from './lockfile.js'
@@ -123,6 +124,30 @@ export interface FingerprintClaims {
  * or `<since>` doesn't resolve to a commit.
  */
 export async function affectedProjects(args: AffectedArgs): Promise<Set<string>> {
+  return (await affectedChanges(args, false)).projects
+}
+
+/**
+ * What `--affected` seeds its tasks from (owner, 2026-10-04): the changed
+ * projects, each one's changed paths relative to it, and the projects a
+ * change reaches as a whole — every task in one is affected whatever its
+ * inputs say, because the reason was no path of its own (a lockfile claim,
+ * a manifest edge at the base, a config import, a nested repository, a
+ * workspace-wide file).
+ */
+export interface AffectedChanges {
+  projects: Set<string>
+  /** Workspace-relative changed paths. */
+  changed: readonly string[]
+  /** Project → its changed paths, relative to the project's directory. */
+  paths: ReadonlyMap<string, readonly string[]>
+  whole: ReadonlySet<string>
+}
+
+export async function affectedChanges(
+  args: AffectedArgs,
+  perTask = true,
+): Promise<AffectedChanges> {
   // Turbo's CI spelling, `[origin/main...HEAD]`, is the base alone here:
   // vx already diffs from the merge base (three dots' meaning), and the
   // working tree it diffs to holds HEAD (D-117). Its two-dot `[A..HEAD]`
@@ -226,9 +251,11 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
   // says per project, so selection asks the plugin the same question, with
   // the bytes at the base ref and in the working tree. Its answer is
   // unioned with the path-owned projects below; only "cannot tell" widens.
-  if (await workspaceConfigChanged(args.workspaceRoot, changed)) {
-    return new Set(args.projects.map((p) => p.name))
+  const everything = (): AffectedChanges => {
+    const all = new Set(args.projects.map((p) => p.name))
+    return { projects: all, changed, paths: new Map(), whole: all }
   }
+  if (await workspaceConfigChanged(args.workspaceRoot, changed)) return everything()
   const fingerprintChanged = changed.filter((p) => FINGERPRINT_SET.has(p))
   // A patch bun.lock names folds into every key, core's fingerprint and
   // `bun()`'s claim alike, so its edit widens as a lockfile edit does. A
@@ -237,7 +264,7 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
     const lock = await bytesOrNull(path.join(args.workspaceRoot, 'bun.lock'))
     if (lock !== null) {
       const patches = new Set(bunPatchFiles(lock))
-      if (changed.some((p) => patches.has(p))) return new Set(args.projects.map((p) => p.name))
+      if (changed.some((p) => patches.has(p))) return everything()
     }
   }
   const claimedOwned = new Set<string>()
@@ -256,15 +283,13 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
   }
   if (fingerprintChanged.length > 0) {
     for (const file of fingerprintChanged) {
-      if (claims === undefined || !claims.files.has(file)) {
-        return new Set(args.projects.map((p) => p.name))
-      }
+      if (claims === undefined || !claims.files.has(file)) return everything()
       const answer = await claims.affected({
         file,
         before: await gitBytesAt(args.workspaceRoot, base, file),
         after: await bytesOrNull(path.join(args.workspaceRoot, file)),
       })
-      if (answer === undefined) return new Set(args.projects.map((p) => p.name))
+      if (answer === undefined) return everything()
       for (const name of answer) claimedOwned.add(name)
     }
   }
@@ -274,7 +299,24 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
       args.projects.map(async (p) => [p.dir, await realpath(p.dir).catch(() => p.dir)] as const),
     ),
   )
-  const owned = projectsContaining(args.workspaceRoot, changed, args.projects, realDirs)
+  const paths = new Map<string, string[]>()
+  const whole = new Set<string>(claimedOwned)
+  const owned = projectsContaining(
+    args.workspaceRoot,
+    changed,
+    args.projects,
+    realDirs,
+    perTask
+      ? {
+          path: (name, rel) => {
+            const list = paths.get(name)
+            if (list) list.push(rel)
+            else paths.set(name, [rel])
+          },
+          repo: (name) => whole.add(name),
+        }
+      : undefined,
+  )
   for (const name of claimedOwned) owned.add(name)
 
   // A manifest edit can drop an edge today's graph no longer shows: a
@@ -293,10 +335,14 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
       args.projects,
       args.taskEdges,
     )
-    if (dependents === undefined) return new Set(args.projects.map((p) => p.name))
-    for (const name of dependents) owned.add(name)
+    if (dependents === undefined) return everything()
+    for (const name of dependents) {
+      owned.add(name)
+      whole.add(name)
+    }
     for (const name of parentsOfNewNested(args.workspaceRoot, atBase, args.projects)) {
       owned.add(name)
+      whole.add(name)
     }
   }
 
@@ -306,19 +352,23 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
   // runs on the FULL changed set, not just the paths no project owns: the
   // common shape is a config reaching into ANOTHER project
   // (`../../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: owned,
+    skip: perTask ? new Set() : owned,
     realDirs,
   })) {
     owned.add(name)
+    whole.add(name)
   }
 
-  if (changed.length === 0 || args.workspaceGlobOwners === undefined) return owned
+  const done = (): AffectedChanges => ({ projects: owned, changed, paths, whole })
+  if (changed.length === 0 || args.workspaceGlobOwners === undefined) return done()
   for (const name of await args.workspaceGlobOwners(changed)) owned.add(name)
-  return owned
+  return done()
 }
 
 /**
@@ -767,6 +817,8 @@ function projectsContaining(
   changedRelPaths: readonly string[],
   projects: readonly ProjectMeta[],
   realDirs: ReadonlyMap<string, string>,
+  /** Told each owned path relative to its project, and each nested repository's projects. */
+  on?: { path(name: string, rel: string): void; repo(name: string): void },
 ): Set<string> {
   // Index projects by their (canonical) dir, then for each changed path walk
   // its ancestor dirs bottom-up until one is a project dir. The FIRST hit is
@@ -798,6 +850,7 @@ function projectsContaining(
       const name = dirToName.get(dir)
       if (name !== undefined) {
         owned.add(name)
+        on?.path(name, relPosix(dir, path.resolve(workspaceRoot, rel)))
         hit = true
         break
       }
@@ -817,7 +870,11 @@ function projectsContaining(
     const abs = path.resolve(workspaceRoot, rel)
     if (isDirectory(abs)) {
       const prefix = abs + path.sep
-      for (const [dir, name] of dirToName) if (dir.startsWith(prefix)) owned.add(name)
+      for (const [dir, name] of dirToName) {
+        if (!dir.startsWith(prefix)) continue
+        owned.add(name)
+        on?.repo(name)
+      }
     }
   }
   return owned

package/src/workspace/index.ts

@@ -2,6 +2,8 @@
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
 export {
+  affectedChanges,
+  type AffectedChanges,
   affectedProjects,
   defaultAffectedBase,
   type FingerprintClaims,

package/src/workspace/migration.ts

@@ -597,7 +597,7 @@ function renderConfigFile(
   // runs the vx binary without the package installed. `mjs` is the same
   // object with nothing to erase.
   const lines: string[] = [
-    `// Generated by \`${verb}\` from ${source}. Review the TODO(vx-migrate) comments.`,
+    `// Generated by \`${verb}\` from ${source}.${p.tasks.some((t) => t.todos.length > 0) ? ' Review the TODO(vx-migrate) comments.' : ''}`,
   ]
   if (format === 'ts') lines.push("import type { ProjectConfig } from '@vzn/vx/config'")
   if (p.importLines.length > 0) lines.push(...p.importLines)