@vzn/vx 0.0.645 → 0.0.648

package/src/orchestrator/prepare.ts

@@ -7,10 +7,18 @@
 // closes at the bottom of execution, `planRun()` does so via
 // try/finally around its plan() call.
 
-import { existsSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
-import { beginRun, mark, nearest, relPosix, type SecretBroker, UserError } from '../util/index.js'
+import {
+  beginRun,
+  mark,
+  nearest,
+  relPosix,
+  type SecretBroker,
+  thrownMessage,
+  UserError,
+} from '../util/index.js'
 import {
   Cache,
   type CacheLayer,
@@ -40,6 +48,7 @@ import {
   findWorkspaceRoot,
   configuredBaseBranch,
   type LoadReads,
+  lockDigest,
   PROJECT_CONFIG_FILENAMES,
   readClaimedFiles,
   resolveCacheDir,
@@ -47,10 +56,10 @@ import {
   type ProjectEntry,
 } from '../workspace/index.js'
 import {
-  buildTaskGraph,
   excludeDependencies,
   expandRequested,
   type GraphRules,
+  isDefaultBuild,
   isGroupTask,
   refuseFiltersThroughGroups,
   type TaskNode,
@@ -70,7 +79,6 @@ import {
   discoverProjects,
   gitOfDiscovery,
   graphOfDiscovery,
-  isDefaultBuild,
   loadProjects,
   loadWorkspacePlugins,
   lockOfDiscovery,
@@ -82,6 +90,7 @@ 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 { memoGraph, type GraphMemo } from './graph-memo.js'
 import { askIgnoredOutputs, gatedOutputs } from './stable-keys.js'
 import { cacheRefs, currentBranch, resolveCacheScope } from './run-context.js'
 import { createHashCache, type HashCache } from './task-hash.js'
@@ -116,6 +125,8 @@ export interface PreparedRun {
   cacheScope: string | undefined
   /** The run's remotes in declared order, as the policy gates each; `openRemotes` turns one off. */
   remotes: ResolvedRemote[]
+  /** The refs the run reads, in order (`CacheContext.refs`). */
+  cacheRefs: readonly string[]
   /**
    * Scheduling priorities from plugins' `schedule` stage (task id → weight,
    * merged over the structural baseline by the scheduler). Empty when no
@@ -166,6 +177,14 @@ export interface PreparedRun {
    * mistaken for a workspace vx was never set up in.
    */
   anyProjectConfig: boolean
+  /** A workspace project that declares no task: no config, and nothing configured reaches it. */
+  taskless: (name: string) => boolean
+  /**
+   * With no config in the lock, one a directory holds anyway (root-relative):
+   * written after `vx lock`, so the fix is `vx lock`, not `vx init`. Asked
+   * only by a refusal, so a run that goes on pays no stat.
+   */
+  unlockedConfig: () => string | undefined
   /** The claimed root files, and whether a task has since rewritten one (fingerprint-watch.ts). */
   fingerprintWatch: FingerprintWatch
   nestedDirsByProject: Map<string, string[]>
@@ -333,7 +352,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   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
-  // names the remote (owner, 2026-10-03; Security F1, 2026-10-14): a key
+  // names the remote (2026-10-03; Security F1, 2026-10-14): a key
   // holds only declared inputs, so a laptop's write could be replayed on CI.
   // A workspace policy naming the remote asks to write it, as `--cache-policy` does.
   const readOnly =
@@ -366,7 +385,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
 
   // Configs load FROM .vx/projects.lock.json with no evaluation and no check of
   // the configs (`vx lock --check` re-evaluates them; a run does not):
-  // only `vx lock` evaluates (owner, 2026-10-14).
+  // only `vx lock` evaluates (2026-10-14).
   // See docs/design/config-lock-2026-06.md.
   // Read once, and only when a config is to be read from it: the CLI's
   // selection pass may have staged every config (`options.staged`), and
@@ -410,6 +429,12 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // name, never by count: a config-less project counts as loaded, so a
   // scope holding one hid an unloaded declarer (X-129, X-182).
   const partialLoad = projectsWithConfigs.some((m) => !projects.has(m.name))
+  // Asked on a refusal only: a scope never loads a config-less project
+  // nothing configured reaches.
+  const taskless = (name: string): boolean =>
+    !projects.has(name) &&
+    projectMetas.some((m) => m.name === name) &&
+    !projectsWithConfigs.some((m) => m.name === name)
 
   // Boundary geometry considers every workspace project, loaded or not,
   // config or not: `--affected` gives a changed path to the deepest project
@@ -427,7 +452,20 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // A dependant's `^build` still reaches it, and `lib#build` names it.
   const requested = expandRequested(tasks, candidateProjects, projects, isDefaultBuild)
   let unresolvedTasks = unresolvedRequests(tasks, candidateProjects, projects, isDefaultBuild)
+  // A diff that changed only config-less projects loads none of them: no
+  // candidate to ask, so every bare name is still to judge, or a typo ran
+  // nothing, exit 0.
+  if (options.selectedByDiff === true && candidateProjects.length === 0)
+    unresolvedTasks = [...new Set([...tasks.filter((t) => !t.includes('#')), ...unresolvedTasks])]
   refuseUnlockedConfig(tasks, projects, projectMetas, workspaceRoot)
+  // A scope that loaded no candidate judged no bare name: each is unresolved.
+  if (options.projects !== undefined && options.selectedByDiff !== true)
+    refuseUnlockedScope(
+      candidateProjects.length === 0 ? tasks : unresolvedTasks,
+      options.projects,
+      projectMetas,
+      workspaceRoot,
+    )
   if (options.selectedByDiff === true && unresolvedTasks.some((t) => !t.includes('#'))) {
     // A name a loaded project declares is no typo, whether or not the load
     // was whole: an unaffected dependency loaded for the closure declared
@@ -494,6 +532,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       onError: (err) => warnOf(log)(`[vx] remote cache: ${err.message}`),
     })
   }
+  // An injected remote is no plugin's: nothing reads refs for it.
+  const refs = options.remoteCache ? [] : cacheRefs(workspaceRoot, baseBranch, branchFacts.refs)
   try {
     cache = options.remoteCache
       ? new LayeredCache(localCache, remotes, options.uploadConcurrency)
@@ -502,7 +542,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
           cacheDir,
           warn: warnOf(log),
           scope: cacheScope,
-          refs: cacheRefs(workspaceRoot, baseBranch),
+          refs,
           localCache,
           policy,
           remotes,
@@ -554,6 +594,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       cachePolicy: policy,
       cacheScope,
       remotes,
+      cacheRefs: refs,
       keepRunEntry: undefined,
       priorities: () => Promise.resolve(new Map()),
       branch,
@@ -565,6 +606,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       projects,
       hintProjects,
       anyProjectConfig: projectsWithConfigs.length > 0,
+      taskless,
+      unlockedConfig: () => unlockedConfigOf(projectsWithConfigs, projectMetas, workspaceRoot),
       fingerprintWatch,
       nestedDirsByProject,
       gitFilesCache: new GitFilesCache(),
@@ -585,21 +628,38 @@ 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.
     // A run never checks the graph rules: `vx lock` and `vx lock --check`
-    // do (owner, 2026-10-14). `exclusiveOutputs: false` still asks the walk
+    // do (2026-10-14). `exclusiveOutputs: false` still asks the walk
     // for its addition marks.
     const graphRules: GraphRules = { ...runRules(workspaceConfig), locked: true }
     const unproven: Array<[taskId: string, name: string]> = []
-    const graphOf = (req: typeof requested) =>
-      buildTaskGraph({
-        projects,
-        packageGraph,
-        requested: req,
-        workspaceRoot,
-        rules: graphRules,
-        ...(partialLoad
-          ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
-          : {}),
-      })
+    // Every config is the lock's only when it was read and no `project`
+    // plugin edited one (graph-memo.ts).
+    const lock =
+      hashCache.folds !== undefined &&
+      options.staged === undefined &&
+      !allStaged &&
+      !hasHook(plugins, 'project')
+        ? lockDigest(await readLock())
+        : undefined
+    const graphMemo: GraphMemo | undefined =
+      lock === undefined ? undefined : { folds: hashCache.folds!, lock, metas: projectMetas }
+    const graphOf = (req: typeof requested) => {
+      const built = memoGraph(
+        {
+          projects,
+          packageGraph,
+          requested: req,
+          workspaceRoot,
+          rules: graphRules,
+          ...(partialLoad
+            ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
+            : {}),
+        },
+        graphMemo,
+      )
+      hashCache.graph = built.token
+      return built.nodes
+    }
     let nodes = graphOf(requested)
     const hasGraphHook = hasHook(plugins, 'graph')
     const graphStage = (): Promise<void> =>
@@ -686,6 +746,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     // `prepare (graph)` row until 2026-09-10.
     mark('build graph')
     const gitFilesCache = new GitFilesCache()
+    gitFilesCache.vxDirs = withinRoot(workspaceRoot, cacheDir)
     // Bulk-populate via a single `git ls-files` at the workspace root —
     // partitions the output by project. Avoids one fork+exec per project
     // (~5-10ms each on Linux; the dominant cold-start cost on big
@@ -742,6 +803,13 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     }
     refuseFiltersThroughGroups(nodes)
     const exclude = options.excludeDependencies
+    // The nodes are what the graph token names only while nothing edited them.
+    if (
+      hasGraphHook ||
+      hasHook(plugins, 'key') ||
+      (exclude !== undefined && (exclude === 'all' || exclude.length > 0))
+    )
+      hashCache.graph = undefined
     let keyOnly: ReadonlyMap<string, TaskNode> = new Map()
     if (exclude !== undefined && (exclude === 'all' || exclude.length > 0)) {
       const split = excludeDependencies(nodes, exclude)
@@ -787,6 +855,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
               warn: warnOf(log),
               localCache,
               branch: branch(),
+              refs,
             },
             cacheFor,
             run,
@@ -804,6 +873,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       cachePolicy: policy,
       cacheScope,
       remotes,
+      cacheRefs: refs,
       priorities,
       branch,
       cacheFor,
@@ -817,6 +887,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       projects,
       hintProjects,
       anyProjectConfig: projectsWithConfigs.length > 0,
+      taskless,
+      unlockedConfig: () => unlockedConfigOf(projectsWithConfigs, projectMetas, workspaceRoot),
       fingerprintWatch,
       nestedDirsByProject,
       gitFilesCache,
@@ -891,7 +963,7 @@ async function refuseUndeclaredDeps(
     for (const t of Object.keys(p.config.tasks ?? {})) declared.add(t)
   }
   for (const [id, name] of unproven) {
-    if (!declared.has(name)) throw undeclaredDepsError(id, name)
+    if (!declared.has(name)) throw undeclaredDepsError(id, name, declared)
   }
 }
 
@@ -905,9 +977,11 @@ function pruneToClosure(nodes: Map<string, TaskNode>, roots: ReadonlySet<string>
   const stack = [...roots]
   while (stack.length > 0) {
     const id = stack.pop()!
-    if (keep.has(id)) continue
+    // A `pkg#task` the user named is kept, though a hook may have dropped it.
+    const node = nodes.get(id)
+    if (node === undefined || keep.has(id)) continue
     keep.add(id)
-    stack.push(...nodes.get(id)!.deps)
+    stack.push(...node.deps)
   }
   for (const [id, n] of nodes) {
     if (!keep.has(id)) nodes.delete(id)
@@ -915,7 +989,7 @@ function pruneToClosure(nodes: Map<string, TaskNode>, roots: ReadonlySet<string>
   }
 }
 
-const namesRemote = (spec: string | undefined): boolean =>
+export const namesRemote = (spec: string | undefined): boolean =>
   spec !== undefined && /remote:[rw]/.test(spec)
 
 /**
@@ -923,7 +997,9 @@ const namesRemote = (spec: string | undefined): boolean =>
  * since the grammar lives in the cache module the workspace module may not
  * import. Undefined when it names none.
  */
-function workspaceCachePolicy(config: WorkspaceConfig | null | undefined): CachePolicy | undefined {
+export function workspaceCachePolicy(
+  config: WorkspaceConfig | null | undefined,
+): CachePolicy | undefined {
   const spec = config?.cache?.policy
   if (spec === undefined) return undefined
   try {
@@ -936,16 +1012,30 @@ function workspaceCachePolicy(config: WorkspaceConfig | null | undefined): Cache
   }
 }
 
+/** A config no locked project has, looked for only when the lock holds none. */
+function unlockedConfigOf(
+  configured: readonly unknown[],
+  metas: ReadonlyArray<{ dir: string }>,
+  workspaceRoot: string,
+): string | undefined {
+  if (configured.length > 0) return undefined
+  for (const m of metas) {
+    const config = PROJECT_CONFIG_FILENAMES.find((n) => existsSync(path.join(m.dir, n)))
+    if (config !== undefined) return relPosix(workspaceRoot, path.join(m.dir, config))
+  }
+  return undefined
+}
+
 /**
  * A `project#build` naming the default `build` of a project the lock holds
- * no config for, while its directory holds one, asks for that config's task, not
+ * no config for (or no project at all), while its directory holds one, asks for that config's task, not
  * one that runs nothing: ran, `c#build` was 0 tasks, exit 0, where a
  * renamed task gets "run `vx lock`" (Growth, lock drift).
  */
 function refuseUnlockedConfig(
   tasks: readonly string[],
   projects: ReadonlyMap<string, ProjectEntry>,
-  metas: ReadonlyArray<{ name: string; configPath?: string | null }>,
+  metas: ReadonlyArray<{ name: string; dir: string; configPath?: string | null }>,
   workspaceRoot: string,
 ): void {
   for (const spec of tasks) {
@@ -953,17 +1043,55 @@ function refuseUnlockedConfig(
     if (at < 0) continue
     const name = spec.slice(0, at)
     const entry = projects.get(name)
-    if (entry === undefined || !isDefaultBuild(entry.config.tasks?.[spec.slice(at + 1)])) continue
-    const locked = metas.find((m) => m.name === name)?.configPath
-    if (typeof locked === 'string' && locked !== '') continue
-    const config = PROJECT_CONFIG_FILENAMES.find((n) => existsSync(path.join(entry.dir, n)))
+    // No entry: a package the lock holds no project for, whose config came after it.
+    if (entry !== undefined && !isDefaultBuild(entry.config.tasks?.[spec.slice(at + 1)])) continue
+    const config = unlockedConfig(name, metas)
+    if (config === undefined) continue
+    throw new UserError(
+      `${spec}: ${relPosix(workspaceRoot, config)} is not in the lock yet — run \`vx lock\``,
+      'VX_E_LOCK',
+    )
+  }
+}
+
+/**
+ * The same for a bare name the selection (the cwd's project, `--filter`)
+ * left unresolved: run from a member whose config came after the lock, it
+ * said only projects outside the selection declare the task — pass
+ * `--all`, which skips that member too.
+ */
+function refuseUnlockedScope(
+  unresolved: readonly string[],
+  selected: readonly string[],
+  metas: ReadonlyArray<{ name: string; dir: string; configPath?: string | null }>,
+  workspaceRoot: string,
+): void {
+  const spec = unresolved.find((t) => !t.includes('#'))
+  if (spec === undefined) return
+  // The selection, not the loaded projects: a scope loads no config-less
+  // member nothing configured reaches, and that is the one to ask about.
+  for (const name of selected) {
+    const config = unlockedConfig(name, metas)
     if (config === undefined) continue
     throw new UserError(
-      `${spec}: ${relPosix(workspaceRoot, path.join(entry.dir, config))} is not in the lock yet — run \`vx lock\``,
+      `${spec}: ${relPosix(workspaceRoot, config)} is not in the lock yet — run \`vx lock\``,
+      'VX_E_LOCK',
     )
   }
 }
 
+/** The config file in a project's directory the lock holds none for. */
+function unlockedConfig(
+  name: string,
+  metas: ReadonlyArray<{ name: string; dir: string; configPath?: string | null }>,
+): string | undefined {
+  const meta = metas.find((m) => m.name === name)
+  if (meta === undefined) return undefined
+  if (typeof meta.configPath === 'string' && meta.configPath !== '') return undefined
+  const config = PROJECT_CONFIG_FILENAMES.find((n) => existsSync(path.join(meta.dir, n)))
+  return config === undefined ? undefined : path.join(meta.dir, config)
+}
+
 /**
  * Each remote's `open`, in declared order, for the ones the policy lets read
  * or write. One at a time: two that ask on the terminal must not interleave.
@@ -988,10 +1116,28 @@ export async function openRemotes(
     } catch (err) {
       entry.read = false
       entry.write = false
-      const e = err instanceof Error ? err : new Error(String(err))
+      const e = err instanceof Error ? err : new Error(thrownMessage(err))
       entry.onError?.(e)
       closed = true
     }
   }
   return closed && !remotes.some((r) => r.read || r.write)
 }
+
+/**
+ * `dir` spelled under `root` as the run spells the root, when it lies
+ * there; compared through links, so a root reached by a symlink (macOS's
+ * `/var/folders`) still finds a cache directory written canonical.
+ */
+function withinRoot(root: string, dir: string): string[] {
+  const real = (p: string): string => {
+    try {
+      return realpathSync(p)
+    } catch {
+      return path.resolve(p)
+    }
+  }
+  const rel = path.relative(real(root), real(dir))
+  const outside = rel === '' || rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)
+  return outside ? [] : [path.join(root, rel)]
+}

package/src/orchestrator/projects.ts

@@ -6,7 +6,7 @@
 
 import { stat } from 'node:fs/promises'
 import path from 'node:path'
-import type { ProjectConfig, TaskConfig } from '../config.js'
+import type { ProjectConfig } from '../config.js'
 import {
   checkProjectNames,
   frozenProjectConfigs,
@@ -33,7 +33,7 @@ import {
   resolveCacheDir,
   validateWorkspace,
 } from '../workspace/index.js'
-import { parseDependencySpec } from '../graph/index.js'
+import { DEFAULT_BUILD, parseDependencySpec } from '../graph/index.js'
 import { applyConfigHooks, applyDiscoverHooks, applyProjectHooks, hasHook } from './plugin-host.js'
 import type { BranchFacts, VxPlugin } from './plugin.js'
 
@@ -79,14 +79,35 @@ export async function loadWorkspacePlugins(
       branch.scope = facts.scope
       delete branch.trusted
     }
-    if (facts.base !== undefined) branch.base = facts.base
+    if (facts.base !== undefined) {
+      // Read into `--affected`'s `...[<base>]` filter.
+      if (typeof facts.base !== 'string' || !/^[^\s\0[\]-][^\s\0[\]]*$/.test(facts.base))
+        throw new UserError('setBranch: base must be a commit or a ref')
+      branch.base = facts.base
+    }
+    if (facts.refs !== undefined) {
+      if (!Array.isArray(facts.refs) || facts.refs.some((r) => !isRef(r)))
+        throw new UserError('setBranch: refs must be a list of refs, each starting "refs/"')
+      branch.refs = [...new Set(facts.refs)]
+    }
   }
-  await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn, setBranch }, (plugin) =>
-    validateWorkspace(workspaceConfig, `.vx/workspace (after plugin '${plugin.name}')`),
-  )
+  await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn, setBranch }, (plugin) => {
+    const at = `.vx/workspace (after plugin '${plugin.name}')`
+    validateWorkspace(workspaceConfig, at)
+    // The run takes `plugins` from the file: an edited list validated and was dropped.
+    const now = workspaceConfig.plugins
+    if (now?.length !== list?.length || now?.some((p, i) => p !== list![i])) {
+      throw new UserError(
+        `${at}: \`plugins\` is fixed before the config stage, so an edit to it would change nothing — declare plugins in .vx/workspace`,
+      )
+    }
+  })
   return { workspaceConfig, plugins, branch }
 }
 
+const isRef = (r: unknown): boolean =>
+  typeof r === 'string' && r.startsWith('refs/') && !/[\s\0]/.test(r)
+
 /**
  * The enumeration a discovery's `discover` hooks shared, by the array it
  * returned: a run handed that array (`RunOptions.discovered`, the CLI's
@@ -176,7 +197,8 @@ interface LoadProjectsBase {
   projectMetas: readonly ProjectMeta[]
   /**
    * Projects whose configs must load — `'all'`, or names (unknown and
-   * config-less ones are ignored). With `closure`, each seed's transitive
+   * config-less ones are ignored, unless a configured project's closure
+   * reaches them, as in the `'all'` load). With `closure`, each seed's transitive
    * package dependencies load too, which bounds `^task` frontier
    * expansion; a `pkg#task` dependsOn entry pulls its project in either
    * way, since the package graph cannot see the cross form.
@@ -268,7 +290,17 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
     for (const dep of packageGraph.transitiveDeps(name)) consider(dep)
   }
   const seedAll = (): Iterable<string> => configured.map((m) => m.name)
-  const seeds = args.seeds === 'all' ? seedAll() : [...args.seeds]
+  // A named config-less seed loads only where the `'all'` load would load
+  // it: a configured project's closure reaches it. Seeded as itself, it got
+  // a default build `vx show` listed nowhere and no run of the workspace had
+  // (`vx run lone#build` ran a group no dependant reaches).
+  const configuredNames = new Set(configured.map((m) => m.name))
+  const seedable = (name: string): boolean =>
+    configuredNames.has(name) ||
+    (graph !== null &&
+      metaByName.has(name) &&
+      graph.transitiveDependents(name).some((d) => configuredNames.has(d)))
+  const seeds = args.seeds === 'all' ? seedAll() : [...args.seeds].filter(seedable)
   for (const seed of seeds) consider(seed)
   if (graph !== null && pending.length < metaByName.size) {
     for (const seed of args.seeds === 'all' ? seedAll() : seeds) {
@@ -304,7 +336,8 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
     const present = await Promise.all(withFile.map((m) => Bun.file(m.configPath).exists()))
     const gone = withFile.find((_, i) => !present[i])
     if (gone !== undefined) {
-      const rel = relPosix(workspaceRoot, gone.dir) || '.'
+      // `.` read as a sentence's end: the notice cut the line there.
+      const rel = relPosix(workspaceRoot, gone.dir) || 'the workspace root project'
       const named = gone.name === pathName(workspaceRoot, gone.dir) ? '' : ` ("${gone.name}")`
       const file = relPosix(gone.dir, gone.configPath)
       // exists() says false for a file behind a directory this user may not
@@ -314,11 +347,15 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
         (err: NodeJS.ErrnoException) =>
           err.code === 'EACCES' || err.code === 'EPERM' ? err.code : null,
       )
-      throw new UserError(
-        denied !== null
-          ? `${LOCKFILE_NAME} locks ${rel}${named}, but its ${file} is not readable by this user (${denied})`
-          : `${LOCKFILE_NAME} locks ${rel}${named}, but its ${file} is gone — run \`vx lock\``,
-      )
+      throw denied !== null
+        ? new UserError(
+            `${LOCKFILE_NAME} locks ${rel}${named}, but its ${file} is not readable by this user (${denied})`,
+            'VX_E_FS',
+          )
+        : new UserError(
+            `${LOCKFILE_NAME} locks ${rel}${named}, but its ${file} is gone — run \`vx lock\``,
+            'VX_E_LOCK',
+          )
     }
     const loaded =
       withFile.length === 0 ? [] : frozenProjectConfigs(await lock(), withFile, workspaceRoot)
@@ -341,6 +378,7 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
         // the loader accepts from a user, and the refusal names both the
         // config file and the plugin whose edit broke it.
         const where = meta.configPath ?? `${meta.name} (no config file)`
+        const name = config.name
         await applyProjectHooks(
           plugins,
           config,
@@ -353,12 +391,17 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
             projects: args.projectMetas,
             lock: args.lock === true,
           },
-          (plugin) =>
-            validateProjectConfig(
-              config,
-              `${where} (after plugin '${plugin.name}')`,
-              meta.configPath,
-            ),
+          (plugin) => {
+            const at = `${where} (after plugin '${plugin.name}')`
+            validateProjectConfig(config, at, meta.configPath)
+            // Projects are named and edged before any config loads: a new
+            // `name` here validated, and the project kept its old one.
+            if (config.name !== name) {
+              throw new UserError(
+                `${at}: project "${meta.name}" is named before the project stage, so \`name: ${JSON.stringify(config.name)}\` cannot rename it — a plugin names a project in its \`discover\` hook`,
+              )
+            }
+          },
         )
       }
       const built = withDefaultBuild(config)
@@ -373,24 +416,6 @@ 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. A keyed group, as a config may
- * declare one (config-schema.ts).
- */
-const DEFAULT_BUILD: TaskConfig = Object.freeze({
-  dependsOn: Object.freeze(['^build']),
-  inputs: Object.freeze({ files: Object.freeze(['**']) }),
-})
-
-/** 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 } }
@@ -432,7 +457,7 @@ function crossDepProjects(config: ProjectConfig): string[] {
       // the offending task. Here it just contributes no project.
       if (!raw.includes('#')) continue
       try {
-        const spec = parseDependencySpec(raw)
+        const spec = parseDependencySpec(raw, 'dependsOn')
         if (spec.kind === 'cross') out.push(spec.project)
       } catch {
         continue
@@ -475,7 +500,7 @@ export function lockReader(workspaceRoot: string): () => Promise<Lockfile> {
   let read: Promise<Lockfile> | undefined
   return () =>
     (read ??= readLockfile(workspaceRoot).then((lock) => {
-      if (lock === null) throw new UserError(NO_LOCK)
+      if (lock === null) throw new UserError(NO_LOCK, 'VX_E_LOCK')
       return lock
     }))
 }