@vzn/vx 0.0.636 → 0.0.638

package/src/workspace/workspace.ts

@@ -1,59 +1,38 @@
-import { constants, existsSync, type Dirent } from 'node:fs'
-import { access, readdir, realpath, stat } from 'node:fs/promises'
+// What a project is (owner, 2026-10-14): a directory holding a
+// `vx.config.*`. `vx lock` finds them (`findProjectConfigs`) and records
+// each by directory; a run takes them from the lock (`lockedProjects`) and
+// never walks. A project is named by `name` in its config, else by a
+// `discover` plugin, else by its root-relative path, `//` for the root.
+// Design: docs/design/language-agnostic-core-2026-10.md.
+import type { Dirent } from 'node:fs'
+import { lstat, readdir, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
 import {
-  BUN_GLOB_WILDCARDS,
-  EXTGLOB,
+  executablePath,
+  gitEnv,
+  gitSpawnRefusal,
+  isExecutableMissing,
   isOutOfFds,
-  isPermissionError,
+  refusal,
   relPosix,
-  slashBraceExpansions,
   UserError,
-  normalizeBunGlob,
-  realpathOf,
 } from '../util/index.js'
-import { type LoadReads, readOnce, unreadable } from './load-reads.js'
+import { gitTop, workspaceFile, workspaceRootOf } from '../handoff.js'
 import { repoIdOf } from './repo-id.js'
 
-export interface PackageJson {
-  name: string
-  version?: string
-  dependencies?: Record<string, string>
-  devDependencies?: Record<string, string>
-  peerDependencies?: Record<string, string>
-  optionalDependencies?: Record<string, string>
-  /** npm / yarn / bun workspaces. May be a glob array or { packages: [...] }. */
-  workspaces?: string[] | { packages?: string[] }
-}
-
-export interface Workspace {
-  root: string
-  /** Glob patterns relative to root that match project directories. */
-  packageGlobs: string[]
-  /** The package manager's catalogs, when the root declares any. */
-  catalogs?: Catalogs
-}
-
-/**
- * Catalog name → dependency → the spec a `catalog:<name>` entry stands
- * for; `catalog:` alone is `default`. pnpm's from `pnpm-workspace.yaml`
- * (`catalog`, `catalogs`), bun's from the root `package.json` (the same
- * keys, top level or under `workspaces`).
- */
-export type Catalogs = ReadonlyMap<string, Readonly<Record<string, unknown>>>
-
 export interface ProjectMeta {
-  /** Canonical name from package.json. */
+  /** `name` in its config, else a `discover` plugin's, else its root-relative path (`//` for the root). */
   name: string
   /** Absolute path to the project directory. */
   dir: string
-  packageJson: PackageJson
-  /** Absolute path to vx.config.{ts,mts,js,mjs,cts,cjs} or null. */
+  /** Absolute path to vx.config.{ts,mts,js,mjs,cts,cjs}; null for a project a plugin added. */
   configPath: string | null
-  /** The workspace's catalogs, which the package graph resolves `catalog:` specs through. */
-  catalogs?: Catalogs
+  /** Projects a `discover` plugin says this one builds after (order and reach). */
+  deps?: readonly string[]
+  /** Projects a `discover` plugin says a change reaches this one through, with no order. */
+  reach?: readonly string[]
 }
 
 /** A discovered project joined with its loaded vx config. */
@@ -74,399 +53,73 @@ export const PROJECT_CONFIG_FILENAMES = [
   'vx.config.cjs',
 ]
 
-const decoder = new TextDecoder()
-
 /**
- * Walk up from `start` to find the workspace root. A directory is a root
- * CANDIDATE when it contains `pnpm-workspace.yaml` or a `package.json`.
+ * The workspace root for `start`: the directory holding the first
+ * `.vx/workspace.*` from `start` up to the git top-level, or up to `/`
+ * outside git ({@link workspaceFile}, shared with the hand-off). Nothing
+ * else decides it (owner, 2026-10-13: "Workspace file is the ultimate"):
+ * not a `package.json`, not `pnpm-workspace.yaml`, not a lockfile. Throws
+ * `VX_E_NO_WORKSPACE` when there is none.
  *
- * The nearest candidate that CLAIMS `start` wins — one of the directories
- * between it and `start` matches one of its package globs. Every workspace
- * member has its own `package.json`, so stopping at the first candidate would
- * make a run from inside a package treat that package as the whole workspace:
- * `^task` edges vanish, upstream hashes drop out of the cache key (stale
- * hits), and a second cache dir appears under the member. Claiming is decided
- * with the same globs `loadWorkspace` applies, so "the root that claims me"
- * and "the root that lists me as a project" cannot diverge. An outer root
- * that lists both the claimer and the claimed member outranks the claimer:
- * from the claimer's own directory the walk reaches the outer root too.
- *
- * When no candidate claims `start` — a standalone package, or a subdirectory
- * of a single-project repo — the nearest candidate wins (the root itself IS
- * the project). Throws a `UserError` when there is no candidate before `/`.
- * A load that goes on to `loadWorkspace` passes its `reads`, so the
- * root's manifest is read once for both.
+ * Outside git, a file another user owns is refused (root aside): a
+ * `.vx/workspace.ts` planted in a shared directory above you (`/tmp`) is
+ * code that would run as you. The owner is the file's own, a link's
+ * included, and its `.vx` directory's. Inside git the walk never leaves your
+ * checkout. The directory you run in is yours to judge, and costs no
+ * stat. Run as root, vx trusts every owner, as a container over a mounted
+ * checkout needs. `uid` is for tests.
  */
 export async function findWorkspaceRoot(
   start: string,
-  reads: LoadReads = new Map(),
+  uid: number = process.getuid?.() ?? 0,
 ): Promise<string> {
-  let dir = path.resolve(start)
-  const below: string[] = []
-  let nearest: string | null = null
-  // The nearest manifest with workspace globs of its own, once passed: an
-  // outer root claims the tree only by listing this directory itself.
-  let inner: string | null = null
-  // The root that claims `start`, and the members it claimed it through.
-  let claimed: string | null = null
-  let members: string[] = []
-  while (true) {
-    let globs: string[] | null
-    try {
-      globs = await readPackageGlobs(dir, reads)
-    } catch (err) {
-      if (isOutOfFds(err)) throw err
-      // An unparseable manifest is still a root SIGNAL (the pre-existing
-      // behaviour probed only for existence); it just can't claim members.
-      // `loadWorkspace` surfaces the parse error if this dir is chosen.
-      globs = []
-    }
-    if (globs !== null) {
-      nearest ??= dir
-      if (claimed !== null) {
-        // An outer root that lists both the claimer and the member owns
-        // them: `packages/**` holding `packages/inner` (with `workspaces:
-        // ['sub']`) and `packages/inner/sub` resolved `sub` to `inner` and
-        // `inner` to the outer root, two roots and two keys for one tree.
-        if (
-          (await claimsMember(dir, [claimed], globs)) &&
-          (await claimsMember(dir, members, globs))
-        )
-          claimed = dir
-      } else if (await claimsMember(dir, inner === null ? below : [inner], globs)) {
-        claimed = dir
-        members = inner === null ? [...below] : [inner]
-      }
-      // pnpm takes the nearest `pnpm-workspace.yaml` as the root, listed or
-      // not. Walking past it, `apps/inner` resolved to the outer workspace
-      // while `apps/inner/pkgs/x` resolved to the inner one: two roots and
-      // two caches for one tree (item 990). Already read: `reads` holds it.
-      if ((await readOnce(reads, path.join(dir, 'pnpm-workspace.yaml'))) !== null) {
-        return claimed ?? dir
-      }
-    }
-    const parent = path.dirname(dir)
-    if (parent === dir) break
-    // Only a directory holding a manifest can be a member: a glob that
-    // matched `packages/tools`, which has none, claimed the standalone
-    // package below it, and `packages/tools/standalone` ran as a stranger
-    // in a workspace that does not list it (item 989).
-    if (globs !== null) below.push(dir)
-    // `apps/tool/workspace` with its own `workspaces`, under a root listing
-    // `apps/*`, resolved to the outer root through `apps/tool`, and its
-    // members ran in a workspace that does not list them (D-137). npm makes
-    // an outer root own a nested one only when it lists that directory.
-    if (inner === null && globs !== null && globs.length > 0) inner = dir
-    dir = parent
-  }
-  if (claimed !== null) return claimed
-  if (nearest !== null) return nearest
-  throw new UserError(
-    `Could not find a workspace root in any parent of ${start} ` +
-      `(looked for pnpm-workspace.yaml or package.json): run vx inside a project, ` +
-      `or create a package.json (\`bun init\` or \`npm init -y\`) and run \`vx init\``,
-    'VX_E_NO_WORKSPACE',
-  )
-}
-
-/** True when one of `below` (dirs under `root`, toward `start`) is a member. */
-async function claimsMember(
-  root: string,
-  below: readonly string[],
-  globs: readonly string[],
-): Promise<boolean> {
-  if (below.length === 0 || globs.length === 0) return false
-  const { positive, negative } = splitPackageGlobs(globs)
-  const rels = below.map((d) => relPosix(root, d)).filter((rel) => !excludedBy(rel, negative))
-  for (const pattern of positive) {
-    const normalized = pattern.replace(/\/+$/, '')
-    // `.` means the root itself is the project — never a directory below it.
-    if (normalized === '' || normalized === '.') continue
-    // Matched as discovery scans, on the manifest: `packages/**` lists
-    // `packages/package.json`, while against the directory `**` needs a
-    // segment below `packages`, and a run from there was its own root.
-    const glob = new Bun.Glob(`${normalized}/package.json`)
-    for (const rel of rels) {
-      if (!glob.match(`${rel}/package.json`)) continue
-      // `match` has no `dot: false`: `packages/*` matched `packages/.tpl`,
-      // which discovery skips, and a run from inside it found a workspace
-      // that does not list it. Such a path asks discovery's own walk.
-      if (!SKIPPED_SEGMENT.test(rel)) return true
-      const dirs = await memberDirs(root, pattern)
-      if (dirs.includes(path.join(root, rel))) return true
-    }
-  }
-  return false
-}
-
-const SKIPPED_SEGMENT = /(^|\/)(\.|node_modules(\/|$))/
-
-/**
- * pnpm, npm, yarn and Bun all take `!packages/fixtures` in the package
- * list. Handed to `Bun.Glob` raw, a leading `!` negates the WHOLE pattern,
- * so `!packages/fixtures/package.json` matched every manifest in the tree
- * and every directory holding one became a project — the excluded package
- * ran under `--all`, and a fixture repeating a name killed the run with
- * "Duplicate package name". Negations subtract from what the positive
- * globs found; a literal one excludes its tree.
- */
-function splitPackageGlobs(globs: readonly string[]): { positive: string[]; negative: string[] } {
-  const positive: string[] = []
-  const negative: string[] = []
-  // `!./packages/legacy` and `!packages//legacy` excluded nothing, silently
-  // (2026-09-10): the same spellings the input globs normalize.
-  for (const raw of globs) {
-    // A member glob names directories, so a trailing slash says nothing:
-    // npm and pnpm read `packages/*/` as `packages/*`. `normalizeBunGlob`
-    // gives it a task glob's meaning, `/**`, and `packages/*/` found every
-    // example and fixture package at any depth below the members (item 985).
-    const g = normalizeBunGlob(raw.replace(/(.)\/+$/, '$1'))
-    if (g.startsWith('!')) negative.push(g.slice(1).replace(/\/+$/, ''))
-    else positive.push(g)
-  }
-  return { positive, negative }
-}
-
-function excludedBy(rel: string, negative: readonly string[]): boolean {
-  for (const neg of negative) {
-    if (neg.length === 0) continue
-    if (rel === neg || rel.startsWith(`${neg}/`)) return true
-    if (!BUN_GLOB_WILDCARDS.test(neg)) continue
-    if (new Bun.Glob(neg).match(rel)) return true
-    // pnpm matches the MANIFEST (`<pattern>/package.json`), so its documented
-    // `!**/test/**` excludes `packages/test` itself; matched against the
-    // directory, `**/test/**` needs something below `test` and the package
-    // stayed a member (item 986).
-    if (new Bun.Glob(`${neg}/package.json`).match(`${rel}/package.json`)) return true
-  }
-  return false
-}
-
-/**
- * Package globs declared by `dir`, or `null` when `dir` is not a root
- * candidate. A bare `package.json` (no `workspaces`) is single-project mode:
- * the root itself is the only project, hence `['.']`.
- */
-async function readPackageGlobs(dir: string, reads?: LoadReads): Promise<string[] | null> {
-  return (await readRootManifests(dir, reads)).globs
-}
-
-/** `readPackageGlobs`, and the catalogs the same manifests declare. */
-async function readRootManifests(
-  dir: string,
-  reads?: LoadReads,
-): Promise<{ globs: string[] | null; catalogs: Catalogs | undefined }> {
-  const yamlPath = path.join(dir, 'pnpm-workspace.yaml')
-  const yaml = await readOnce(reads, yamlPath)
-  let yamlWithoutPackages = false
-  // pnpm reads its catalogs from this file alone, bun from package.json.
-  let catalogs: Catalogs | undefined
-  if (yaml !== null) {
-    const parsed = parseManifest(decoder.decode(yaml), yamlPath, Bun.YAML.parse)
-    if (parsed !== null && parsed !== undefined) {
-      if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new UserError(`${yamlPath}: must be a mapping (\`packages:\` and pnpm's settings)`)
-      }
-      catalogs = catalogsOf([parsed])
-      const packages = (parsed as { packages?: unknown }).packages
-      // A list commented out leaves `packages:` null, which pnpm reads as
-      // absent; vx refused it as "must be an array" (D-149).
-      if (packages !== undefined && packages !== null) {
-        return { globs: assertGlobList(packages, yamlPath, 'packages'), catalogs }
-      }
-    }
-    // No `packages:` (or an empty one): pnpm 10 keeps its settings and catalogs in this file
-    // for a single-package repo too. The root's package.json decides, as it
-    // would without the file; read as an empty list, the root found zero
-    // projects and every verb ran nothing and exited 0 (item 984).
-    yamlWithoutPackages = true
-  }
-  const pkgPath = path.join(dir, 'package.json')
-  const pkgBytes = await readOnce(reads, pkgPath)
-  if (pkgBytes === null) return { globs: yamlWithoutPackages ? [] : null, catalogs }
-  const pkg = parsePackageJson(decoder.decode(pkgBytes), pkgPath)
-  const ws = pkg.workspaces as unknown
-  if (yaml === null) {
-    catalogs = catalogsOf(
-      ws !== null && typeof ws === 'object' && !Array.isArray(ws) ? [pkg, ws] : [pkg],
+  start = path.resolve(start)
+  const file = await workspaceFile(start)
+  if (file === null) {
+    const headline = `no .vx/workspace.ts in ${start} or a parent${(await gitTop(start)) === null ? '' : ' up to the git root'}`
+    throw refusal(
+      { headline, fix: 'vx init' },
+      { code: 'VX_E_NO_WORKSPACE', message: `${headline} — run \`vx init\` to create one` },
     )
   }
-  if (ws === undefined || ws === null) return { globs: ['.'], catalogs }
-  // bun's `{ catalog }` and yarn's `{ nohoist }` name no members, and both
-  // managers run the root alone; vx refused them as no array (D-151).
-  if (typeof ws === 'object' && !Array.isArray(ws) && !('packages' in ws)) {
-    return { globs: ['.'], catalogs }
-  }
-  if (ws && typeof ws === 'object' && !Array.isArray(ws) && 'packages' in ws) {
-    const packages = (ws as { packages?: unknown }).packages
-    // Yarn 1 and 4 run the root alone under `packages: null`; read as an
-    // empty list, the root was no project and every verb ran nothing (D-150).
-    if (packages === null) return { globs: ['.'], catalogs }
-    return { globs: assertGlobList(packages, pkgPath, 'workspaces.packages'), catalogs }
-  }
-  return { globs: assertGlobList(ws, pkgPath, 'workspaces'), catalogs }
-}
-
-/**
- * The `catalog` and `catalogs` keys of the manifests (bun reads them at
- * the top level and under `workspaces`), or undefined when none declares
- * one. An entry that is not a mapping is no catalog: a `catalog:` spec
- * through it keeps its edge, as one through an unknown catalog does.
- */
-function catalogsOf(manifests: readonly object[]): Catalogs | undefined {
-  const isMap = (v: unknown): v is Record<string, unknown> =>
-    typeof v === 'object' && v !== null && !Array.isArray(v)
-  let out: Map<string, Readonly<Record<string, unknown>>> | undefined
-  for (const m of manifests) {
-    const { catalog, catalogs } = m as { catalog?: unknown; catalogs?: unknown }
-    if (isMap(catalogs)) {
-      for (const [name, c] of Object.entries(catalogs))
-        if (isMap(c)) (out ??= new Map()).set(name, c)
-    }
-    // `catalog` is the default catalog to pnpm and bun.
-    if (isMap(catalog)) (out ??= new Map()).set('default', catalog)
-  }
-  return out
-}
-
-/**
- * Package manifests the globs never reach, in single-project mode only: a
- * root `package.json` with no `workspaces` field makes the root the one
- * project, and a `packages/app/package.json` full of scripts beside it is
- * then invisible — `vx init` said "no package.json scripts" and `vx run`
- * said "run vx init" (2026-09-16). One shallow scan, two levels, on the
- * failure path only; `node_modules` and dot directories are skipped.
- */
-export async function unreachedPackages(workspace: Workspace): Promise<string[]> {
-  if (workspace.packageGlobs.length !== 1 || workspace.packageGlobs[0] !== '.') return []
-  const found: string[] = []
-  // Two scans: Bun.Glob does not expand a brace whose alternatives hold a
-  // slash (`{*,*/*}/package.json` matched nothing, measured 2026-09-16).
-  for (const pattern of ['*/package.json', '*/*/package.json']) {
-    for await (const rel of new Bun.Glob(pattern).scan({
-      cwd: workspace.root,
-      onlyFiles: true,
-      dot: false,
-    })) {
-      const posix = rel.split(path.sep).join('/')
-      if (posix.startsWith('node_modules/') || posix.includes('/node_modules/')) continue
-      found.push(posix.slice(0, -'/package.json'.length))
-    }
-  }
-  return found.sort()
-}
-
-/**
- * The line for `unreachedPackages`' finding: the cause, the packages, the
- * glob to add, and where. A `pnpm-workspace.yaml` with no `packages:` (pnpm
- * keeps its settings there) is where pnpm reads the globs: the hint said
- * there was no such file and named package.json, beside ngrx's (2026-10-07).
- */
-export function unreachedHint(unreached: readonly string[], root: string): string {
-  const n = unreached.length
-  const shown = unreached.slice(0, 3).join(', ') + (n > 3 ? ` and ${n - 3} more` : '')
-  const globs = [
-    ...new Set(unreached.map((d) => (d.includes('/') ? `${path.posix.dirname(d)}/*` : d))),
-  ]
-    .map((g) => `"${g}"`)
-    .join(', ')
-  const rest = `so the root is the only project and ${n} package.json below it ${n === 1 ? 'is' : 'are'} not: ${shown}.`
-  return existsSync(path.join(root, 'pnpm-workspace.yaml'))
-    ? `pnpm-workspace.yaml lists no \`packages\`, ${rest} Add \`packages: [${globs}]\` to pnpm-workspace.yaml and re-run.`
-    : `package.json declares no \`workspaces\` (and there is no pnpm-workspace.yaml), ${rest} ` +
-        `Add \`"workspaces": [${globs}]\` to package.json and re-run.`
-}
-
-/**
- * Parse a workspace manifest, naming the FILE on failure. The raw parser
- * errors (`Failed to parse JSON`) carry no path, so in a 1000-package
- * monorepo they say nothing about which manifest is broken.
- */
-function parseManifest(text: string, file: string, parse: (t: string) => unknown): unknown {
-  try {
-    return parse(text)
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err)
-    throw new UserError(`failed to parse ${file}: ${msg}`)
-  }
-}
-
-/**
- * A `package.json` as discovery reads it: a JSON object whose `name`, when
- * present, is a string with no surrounding whitespace (npm refuses one).
- * Parsed and cast unchecked, `null` crashed with a TypeError and a stack,
- * `{"name":123}` planned `123#build`, and `" a"` beside `"a"` made two
- * projects (item 988).
- */
-function parsePackageJson(text: string, file: string): PackageJson {
-  const pkg = parseManifest(text, file, JSON.parse)
-  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
-    throw new UserError(`${file}: must be a JSON object`)
-  }
-  const name = (pkg as { name?: unknown }).name
-  if (name !== undefined && (typeof name !== 'string' || name.trim() !== name)) {
-    throw new UserError(`${file}: "name" must be a string with no surrounding whitespace`)
-  }
-  // A task is `<project>#<task>` split at the first `#`: `"a#b"` planned
-  // under `--all` but no run spec or dependsOn could reach it (D-130).
-  if (typeof name === 'string' && name.includes('#')) {
-    throw new UserError(`${file}: "name" cannot hold "#" — vx addresses a task as <name>#<task>`)
-  }
-  return pkg as PackageJson
-}
-
-/**
- * A glob list is user input from a manifest: `packages: "packages/*"`
- * (a bare string instead of a list) is an easy YAML slip, and without
- * this it surfaces as `workspace.packageGlobs.map is not a function`.
- */
-function assertGlobList(value: unknown, file: string, field: string): string[] {
-  if (!Array.isArray(value) || value.some((p) => typeof p !== 'string')) {
-    throw new UserError(`${file}: \`${field}\` must be an array of glob strings`)
-  }
-  for (const pattern of value as string[]) {
-    if (EXTGLOB.test(pattern)) throw extglobRefusal(pattern, file, field)
-  }
-  return value as string[]
-}
-
-function extglobRefusal(pattern: string, file: string, field: string): UserError {
-  const head = `${file}: \`${field}\` entry "${pattern}" is an extglob, which vx's glob engine does not read`
-  // The common shape, a whole segment excluding plain names, has an exact
-  // rewrite in the `!` entries every package manager takes.
-  const segments = pattern.split('/')
-  const at = segments.findIndex((s) => /^!\([^()]*\)$/.test(s))
-  const names = at === -1 ? [] : segments[at]!.slice(2, -1).split('|')
-  const plain = names.every((n) => n !== '' && !BUN_GLOB_WILDCARDS.test(n) && !/[()!@+]/.test(n))
-  const rest = segments.filter((_s, i) => i !== at).join('/')
-  if (at === -1 || !plain || EXTGLOB.test(rest)) {
-    return new UserError(
-      `${head}. List the members with \`*\`, braces or \`!\` exclusions instead.`,
+  const root = workspaceRootOf(file)
+  if (uid !== 0 && root !== start && (await gitTop(start)) === null) {
+    // The link itself and the `.vx` holding it, not what a link names: a
+    // link another user planted to a root-owned file passed as root's, and
+    // its owner could point it at their own code once it had.
+    const owners = await Promise.all(
+      [lstat(file), stat(path.dirname(file))].map((p) =>
+        p.then(
+          (st) => st.uid,
+          () => uid,
+        ),
+      ),
     )
+    if (owners.some((owner) => owner !== uid && owner !== 0)) {
+      throw new UserError(
+        `${file} belongs to another user, so vx does not take its directory as your workspace: ` +
+          'its config would run as you. Run vx in a checkout you own, or run `vx init` in yours',
+        'VX_E_NO_WORKSPACE',
+      )
+    }
   }
-  const before = segments.slice(0, at)
-  const rewrite = [
-    [...before, '*', ...segments.slice(at + 1)].join('/'),
-    ...names.map((n) => `!${[...before, n].join('/')}`),
-  ]
-  return new UserError(
-    `${head} (npm and yarn read \`!(…)\` as an exclusion). List the exclusion as its own entry: [${rewrite.map((r) => JSON.stringify(r)).join(', ')}].`,
-  )
+  return root
 }
 
 /**
- * The workspace's own cache directory (index, history, memos): the
- * workspace's `cacheDir`, else `VX_CACHE_DIR`, else `.vx/cache`, relative
- * to the workspace root.
+ * The workspace's own cache directory (index, history, memos):
+ * `VX_CACHE_DIR`, else the workspace's `cache.dir`, else `.vx/cache`,
+ * relative to the workspace root (`--cache-dir` is the caller's, above both).
  */
 export function resolveCacheDir(root: string, config: WorkspaceConfig | null): string {
   const env = process.env['VX_CACHE_DIR']
-  // `cacheDir: '   '` is refused at load (X-22); the variable made the same
+  // `cache.dir: '   '` is refused at load (X-22); the variable made the same
   // directory named in spaces at the root (D-160).
-  if (config?.cacheDir === undefined && env !== undefined && env !== '' && env.trim() === '') {
+  if (env !== undefined && env !== '' && env.trim() === '') {
     throw new UserError('VX_CACHE_DIR is only whitespace — name a directory, or unset it')
   }
-  const rel = config?.cacheDir ?? (env || path.join('.vx', 'cache'))
+  const fromEnv = env !== undefined && env !== ''
+  const rel = (fromEnv ? env : config?.cache?.dir) ?? path.join('.vx', 'cache')
   const home = process.env['HOME'] || homedir()
   // No shell expands `~` in a config string or a quoted variable, and
   // `'~/.cache/vx'` made a directory named `~` in the workspace.
@@ -475,7 +128,7 @@ export function resolveCacheDir(root: string, config: WorkspaceConfig | null): s
   // The cache writes a `*` .gitignore beside its index: a bare `~` made a
   // directory named `~`, and expanded it would land in home itself (D-153).
   if (path.resolve(dir) === path.resolve(home)) {
-    const source = config?.cacheDir !== undefined ? 'cacheDir' : 'VX_CACHE_DIR'
+    const source = fromEnv ? 'VX_CACHE_DIR' : 'cache.dir'
     throw new UserError(
       `${source} ${JSON.stringify(rel)} is the home directory itself, where the cache's \`*\` .gitignore and index would land — name a directory under it, like '~/.cache/vx'`,
     )
@@ -487,7 +140,7 @@ export function resolveCacheDir(root: string, config: WorkspaceConfig | null): s
  * Where this repository's shared store lives: `~/.vx/<repo id>/cache`, as
  * Nx 23 keeps `~/.nx/<id>/cache` (owner, 2026-10-06), so every checkout of
  * the repository hits what another saved and no other repository shares
- * it (`repoIdOf`). Null when the workspace names its cache (`cacheDir`,
+ * it (`repoIdOf`). Null when the workspace names its cache (`cache.dir`,
  * `VX_CACHE_DIR`): that directory then holds everything, as one
  * workspace's alone. Null with no repository identity or no home.
  */
@@ -495,7 +148,7 @@ export async function resolveStoreRoot(
   root: string,
   config: WorkspaceConfig | null,
 ): Promise<string | null> {
-  if (config?.cacheDir !== undefined || process.env['VX_CACHE_DIR']) return null
+  if (config?.cache?.dir !== undefined || process.env['VX_CACHE_DIR']) return null
   // HOME first: Bun's homedir() keeps the HOME the process started with (1.4.2).
   const home = process.env['HOME'] || homedir()
   if (!path.isAbsolute(home)) return null
@@ -508,483 +161,362 @@ export async function resolveStoreRoot(
 const repoIds = new Map<string, Promise<string | null>>()
 
 /**
- * Read the workspace's package-glob list, supporting all common
- * package managers:
- *   - `pnpm-workspace.yaml` (pnpm)
- *   - `package.json` `workspaces` array (npm / yarn / bun)
- *   - `package.json` `workspaces.packages` array (yarn legacy)
- *
- * If a `package.json` exists with no `workspaces` field, the root
- * itself is treated as a single-project workspace.
+ * Sets each project's `deps` / `reach` from the `discover` entries' edge
+ * directories, resolved against every project the stage left. A target
+ * outside the root or that is no project is refused naming the plugin.
  */
-export async function loadWorkspace(root: string, reads?: LoadReads): Promise<Workspace> {
-  const { globs: packageGlobs, catalogs } = await readRootManifests(root, reads)
-  if (packageGlobs === null) {
-    // The CLI never lands here (findWorkspaceRoot returns only a dir that
-    // passes one of the two checks); a direct call of this public function
-    // on a bare dir does (D-58).
-    throw new UserError(`workspace root ${root} has neither pnpm-workspace.yaml nor package.json`)
+export function linkDiscoveredEdges(
+  root: string,
+  projects: readonly ProjectMeta[],
+  edges: ReadonlyArray<{
+    readonly by: string
+    readonly meta: ProjectMeta
+    readonly deps: readonly string[] | undefined
+    readonly reach: readonly string[]
+  }>,
+): void {
+  if (edges.length === 0) return
+  const byDir = new Map(projects.map((p) => [p.dir, p.name]))
+  const deps = new Map<ProjectMeta, Set<string>>()
+  const reach = new Map<ProjectMeta, Set<string>>()
+  for (const edge of edges) {
+    // An entry carrying `deps`, even none, makes its project a leaf of an
+    // edge source rather than a project no plugin spoke for.
+    if (edge.deps !== undefined && !deps.has(edge.meta)) deps.set(edge.meta, new Set())
+    for (const [kind, into] of [
+      [edge.deps ?? [], deps],
+      [edge.reach, reach],
+    ] as const) {
+      for (const target of kind) {
+        const dir = path.resolve(root, target)
+        const rel = relPosix(root, dir)
+        const where = `plugin '${edge.by}' gave project "${edge.meta.name}" an edge to ${target}`
+        if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
+          throw new UserError(`${where}: outside the workspace root`)
+        }
+        const name = byDir.get(dir)
+        if (name === undefined) throw new UserError(`${where}: not a project`)
+        let set = into.get(edge.meta)
+        if (set === undefined) into.set(edge.meta, (set = new Set()))
+        set.add(name)
+      }
+    }
   }
-  return catalogs === undefined ? { root, packageGlobs } : { root, packageGlobs, catalogs }
+  for (const [meta, names] of deps) meta.deps = [...names].sort()
+  for (const [meta, names] of reach) meta.reach = [...names].sort()
 }
 
-// `<dir>/*` — the shape of nearly every workspace glob. Anything with another
-// glob character (`**`, `{a,b}`, `?`, `[`) or a negation takes the general
-// path.
-const SIMPLE_STAR_RE = /^[^*?{}[\]!]+\/\*$/
+/** The root project's name when nothing names it: Turbo's spelling, and the root alias in filters and `dependsOn`. */
+export const ROOT_NAME = '//'
 
-/**
- * The directory each `<dir>/*` package glob names — where a member comes
- * and goes as one directory entry, so `vx watch` can hear a package added
- * or removed without walking anything. A glob of another shape (`apps/**`)
- * has no such directory and contributes none.
- */
-export function memberBaseDirs(workspace: Workspace): string[] {
-  const bases = new Set<string>()
-  for (const pattern of splitPackageGlobs(workspace.packageGlobs).positive) {
-    const normalized = pattern === '.' ? '' : pattern.replace(/\/$/, '')
-    if (SIMPLE_STAR_RE.test(normalized)) {
-      bases.add(path.resolve(workspace.root, normalized.slice(0, -2)))
-    }
-  }
-  return [...bases]
+/** A project's name when nothing names it: its root-relative POSIX path, `//` for the root. */
+export function pathName(root: string, dir: string): string {
+  return relPosix(root, dir) || ROOT_NAME
 }
 
-/**
- * True when a member glob reaches a `package.json` other than the root's,
- * addressable or not: a nameless manifest, or two sharing a name, is
- * matched and left out, not unmatched (M-46).
- */
-export async function reachesManifest(workspace: Workspace): Promise<boolean> {
-  const { positive, negative } = splitPackageGlobs(workspace.packageGlobs)
-  const root = path.resolve(workspace.root)
-  for (const pattern of positive) {
-    for (const dir of await memberDirs(workspace.root, pattern)) {
-      if (path.resolve(dir) === root) continue
-      if (negative.length > 0 && excludedBy(relPosix(workspace.root, dir), negative)) continue
-      try {
-        if ((await stat(path.join(dir, 'package.json'))).isFile()) return true
-      } catch (err) {
-        absent(err, undefined)
-      }
-    }
-  }
-  return false
-}
+const CONFIG_RANK = new Map(PROJECT_CONFIG_FILENAMES.map((n, i) => [n, i]))
 
-/**
- * The directories a workspace glob names. For the `<dir>/*` shape this is
- * one readdir of `<dir>` — the same answer `Bun.Glob` gives, at a third of
- * the cost (measured 2026-09-02: 25 ms → ~2 ms for 1000 members). A
- * symlinked member is followed when it points at a directory, and so is
- * it by the scan any other shape takes, unless the glob holds `**` (item
- * 987). Dot-directories are skipped (`dot: false`), so are `node_modules`.
- */
-async function memberDirs(root: string, pattern: string): Promise<string[]> {
-  // Normalize: `"."` -> the root itself; `"foo/"` -> `"foo"`.
-  const normalized = pattern === '.' ? '' : pattern.replace(/\/$/, '')
-  if (SIMPLE_STAR_RE.test(normalized)) {
-    const base = path.resolve(root, normalized.slice(0, -2))
-    let entries: import('node:fs').Dirent[]
-    try {
-      entries = await readdir(base, { withFileTypes: true })
-    } catch (err) {
-      return absent(err, [])
-    }
-    const dirs: string[] = []
-    for (const e of entries) {
-      if (e.name.startsWith('.') || e.name === 'node_modules') continue
-      if (e.isDirectory()) dirs.push(path.join(base, e.name))
-      else if (e.isSymbolicLink()) {
-        try {
-          if ((await stat(path.join(base, e.name))).isDirectory())
-            dirs.push(path.join(base, e.name))
-        } catch (err) {
-          absent(err, undefined) // dangling link: not a member
-        }
-      }
-    }
-    return dirs
-  }
-  const dirs: string[] = []
-  // `Bun.Glob`'s scan finds nothing for a brace whose alternatives hold a
-  // slash, though its `match` reads one: `packages/{a,nested/b}` listed
-  // neither package, and both ran under no verb while the root still
-  // claimed them (D-2). Such a pattern is scanned as its expansions.
-  for (const expanded of slashBraceExpansions(normalized)) {
-    const globPattern = expanded === '' ? 'package.json' : `${expanded}/package.json`
-    const glob = new Bun.Glob(globPattern)
-    // A linked member is a member, as the readdir path above has it:
-    // `packages/*` found `packages/b -> ../ext/b` while `packages/{a,b}` and
-    // `pack*/*` did not (item 987). Followed only where the depth is bounded:
-    // under `**` the scan would walk every pnpm `node_modules` link.
-    const followSymlinks = !expanded.includes('**')
-    try {
-      for await (const rel of glob.scan({
-        cwd: root,
-        onlyFiles: true,
-        dot: false,
-        followSymlinks,
-      })) {
-        // Skip nested node_modules — workspace package globs shouldn't
-        // ever reach into them, but a pathological pattern like `**`
-        // would. Avoid splitting the path on the hot loop.
-        if (rel.includes(`${path.sep}node_modules${path.sep}`)) continue
-        if (rel.startsWith(`node_modules${path.sep}`)) continue
-        dirs.push(path.dirname(path.resolve(root, rel)))
-      }
-    } catch (err) {
-      // The scan stops at a directory it may not open and cannot skip it,
-      // so the readdir path's skip is not on offer here (D-132).
-      if (!isPermissionError(err)) throw err
-      const where = relPosix(root, path.resolve(root, err.path ?? ''))
-      throw new UserError(
-        `${where}: not readable by this user (${err.code}), and the workspace glob "${pattern}" walks into it`,
-      )
-    }
-  }
-  return dirs
+/** A directory holding a vx config, and the config file precedence picked there. */
+export interface ConfigDir {
+  /** Absolute. */
+  readonly dir: string
+  readonly configPath: string
 }
 
 /**
- * The project's config file, by `PROJECT_CONFIG_FILENAMES` precedence, or null.
- *
- * Two shapes, one per platform, each the measured winner there across
- * 1,000 projects with the manifest read in flight alongside:
- *   - macOS stats the candidates in order: a readdir each cost 9.6 ms
- *     against 6.3 ms of stats even with the config at the LAST name
- *     (2026-09-03), and a `.ts` config — the first name — pays one stat.
- *   - Linux lists the directory once: a readdir each is 12 ms against
- *     43 ms of stats at the last name and ties the one-stat case
- *     (2026-09-09, a `vx.config.mjs` workspace; stats there cost a
- *     thread-pool round trip apiece).
- * Both answer identically: a directory or dangling link under a config
- * name is skipped for the next name, a symlink to a file counts.
+ * Every project directory under `root`, for `vx lock` (a run reads the
+ * lock and never walks). In git: `git ls-files` over the config names,
+ * tracked and untracked, git's ignore rules applied, and each nested
+ * repository's own listing. Outside git: a walk
+ * that skips dot-directories and `node_modules`. A config at or under a
+ * nested `.vx/workspace.*` belongs to that workspace and is left out.
+ * Where a directory holds several, `PROJECT_CONFIG_FILENAMES` order picks
+ * the first that is a file.
  */
-async function findConfigFile(dir: string): Promise<string | null> {
-  if (process.platform === 'linux') {
-    let entries: Dirent[]
-    try {
-      entries = await readdir(dir, { withFileTypes: true })
-    } catch (err) {
-      return absent(err, null)
-    }
-    // By precedence slot, not a Map per directory, and no `path.join`: at
-    // 5,000 projects that cut `listProjects` from 53.5 to 47.7 ms (min of
-    // 15, six interleaved rounds, A/A 54.7).
-    const found: Dirent[] = []
-    for (const e of entries) {
-      const rank = CONFIG_RANK.get(e.name)
-      if (rank !== undefined) found[rank] = e
-    }
-    for (const entry of found) {
-      if (entry === undefined) continue
-      const candidate = dir + path.sep + entry.name
-      if (entry.isFile()) return candidate
-      if (entry.isSymbolicLink() && (await isFile(candidate))) return candidate
-    }
-    return null
-  }
-  for (const name of PROJECT_CONFIG_FILENAMES) {
-    const candidate = path.join(dir, name)
-    if (await isFile(candidate)) return candidate
-  }
-  return null
+export async function findProjectConfigs(root: string): Promise<ConfigDir[]> {
+  const rels = (await gitTop(root)) === null ? await scanConfigs(root) : await gitConfigs(root)
+  const nested: string[] = []
+  for (const rel of rels) {
+    const at = rel.lastIndexOf('.vx/workspace.')
+    if (at > 0 && rel[at - 1] === '/' && rel.lastIndexOf('/') === at + 3)
+      nested.push(rel.slice(0, at - 1))
+  }
+  const byDir = new Map<string, string[]>()
+  for (const rel of rels) {
+    const slash = rel.lastIndexOf('/')
+    const base = rel.slice(slash + 1)
+    if (!CONFIG_RANK.has(base)) continue
+    const dir = slash === -1 ? '' : rel.slice(0, slash)
+    if (nested.some((n) => dir === n || dir.startsWith(`${n}/`))) continue
+    const names = byDir.get(dir)
+    if (names === undefined) byDir.set(dir, [base])
+    else names.push(base)
+  }
+  const found = await Promise.all(
+    [...byDir].map(async ([rel, names]) => {
+      const dir = rel === '' ? root : path.join(root, rel)
+      names.sort((a, b) => CONFIG_RANK.get(a)! - CONFIG_RANK.get(b)!)
+      // A file each: git lists a tracked config deleted from the worktree,
+      // and a directory may carry a config's name.
+      for (const name of names) {
+        const configPath = path.join(dir, name)
+        if (await isFile(configPath)) return { dir, configPath }
+      }
+      return null
+    }),
+  )
+  return found
+    .filter((f): f is ConfigDir => f !== null)
+    .sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0))
 }
 
-const CONFIG_RANK = new Map(PROJECT_CONFIG_FILENAMES.map((n, i) => [n, i]))
-
 async function isFile(p: string): Promise<boolean> {
   try {
     return (await stat(p)).isFile()
   } catch (err) {
-    return absent(err, false)
+    if (isOutOfFds(err)) throw err
+    return false
   }
 }
 
 /**
- * A read that found nothing is absent; one the process could not make is
- * not. Out of descriptors (`EMFILE`), every member read failed, and the
- * catches here read the workspace as empty: "No package matched the
- * workspace's package globs" (D-60).
+ * The config and workspace-file paths git lists under `root`, root-relative.
+ * A nested repository is one entry to the outer git, a gitlink (a
+ * submodule) or an untracked `dir/` (an embedded repository), and none of
+ * its files: its own git lists them, or a walk when it has no `.git`, as
+ * the input enumeration expands one.
  */
-function absent<T>(err: unknown, value: T): T {
-  if (isOutOfFds(err)) throw err
-  return value
-}
-
-/**
- * A member's manifest text, or null when there is none. A manifest this
- * user may not read is refused, not skipped: its project dropped out of
- * `--all` and the run went green without it (D-132). A directory it may
- * not search hides whether a manifest is there at all, so that one is
- * named and skipped (a service's data directory under `packages/*`).
- */
-async function readManifest(root: string, dir: string, file: string): Promise<string | null> {
-  try {
-    return await Bun.file(file).text()
-  } catch (err) {
-    if (!isPermissionError(err)) return absent(err, null)
-    const searchable = await access(dir, constants.X_OK).then(
+async function gitConfigs(root: string): Promise<string[]> {
+  const [configs, index, untracked] = await Promise.all([
+    gitZ(root, [
+      'ls-files',
+      '-z',
+      '--cached',
+      '--others',
+      '--exclude-standard',
+      '--',
+      ':(glob)**/vx.config.*',
+      ':(glob)**/.vx/workspace.*',
+    ]),
+    gitZ(root, ['ls-files', '-z', '--stage']),
+    // An embedded repository is the one untracked entry git lists as `dir/`.
+    gitZ(root, ['ls-files', '-z', '--others', '--exclude-standard']),
+  ])
+  // A submodule's `.git` is a file, an embedded repository's a directory.
+  const isRepo = (rel: string): Promise<boolean> =>
+    stat(path.join(root, rel, '.git')).then(
       () => true,
       () => false,
     )
-    if (searchable) unreadable(err, file)
-    process.stderr.write(
-      `vx: ${shownDir(root, dir)} is not readable by this user — skipped, with any project in it\n`,
-    )
-    return null
-  }
-}
-
-/** `dir` as a discovery line names it: the root's own path is '' (D-127, D-154). */
-function shownDir(root: string, dir: string): string {
-  return relPosix(root, dir) || 'the workspace root'
-}
-
-export async function listProjects(workspace: Workspace): Promise<ProjectMeta[]> {
-  return discoverProjects(workspace)
-}
-
-/**
- * `listProjects`, and `nameless` collects each member directory whose
- * manifest has no `name`: `vx init` names them, since their scripts map to
- * nothing.
- */
-export async function discoverProjects(
-  workspace: Workspace,
-  nameless?: string[],
-): Promise<ProjectMeta[]> {
-  // Run all package globs concurrently. Disk-bound walks parallelize
-  // well; serializing them just stretches the discovery phase by N×.
-  const { positive, negative } = splitPackageGlobs(workspace.packageGlobs)
-  // A root the globs do not list is a project when it holds a vx config
-  // (D-39): the package manager's member list stays the manager's, and
-  // the root's globs stop at every member as any parent project's do.
-  const [perPattern, rootConfig] = await Promise.all([
-    Promise.all(positive.map((pattern) => memberDirs(workspace.root, pattern))),
-    findConfigFile(workspace.root),
+  const gitlinks = index
+    .filter((e) => e.startsWith('160000 '))
+    .map((e) => e.slice(e.indexOf('\t') + 1))
+  const embedded = untracked.filter((e) => e.endsWith('/')).map((e) => e.slice(0, -1))
+  const inner = await Promise.all([
+    ...gitlinks.map(async (rel) =>
+      // A submodule never initialised, or vendored with its `.git` removed, is walked.
+      (await isRepo(rel)) ? gitConfigs(path.join(root, rel)) : scanConfigs(path.join(root, rel)),
+    ),
+    ...embedded.map((rel) => gitConfigs(path.join(root, rel))),
   ])
-  const matches = new Set<string>()
-  for (const arr of perPattern) {
-    for (const m of arr) {
-      if (negative.length > 0 && excludedBy(relPosix(workspace.root, m), negative)) continue
-      matches.add(m)
-    }
-  }
-  if (rootConfig !== null) matches.add(workspace.root)
-
-  // Per-project discovery: the manifest read answers "is there a
-  // package.json" (an ENOENT is the "not a member" answer, at the cost of
-  // one failed open) and `findConfigFile` answers "which config file", both
-  // in flight together. All async and all in flight at once — the thread
-  // pool runs them in parallel, and a sync read here measured 2× slower on
-  // a 1000-member workspace.
-  const loaded = await Promise.all(
-    [...matches].map(async (dir) => {
-      const pkgJsonPath = dir + path.sep + 'package.json'
-      const [configPath, text] = await Promise.all([
-        findConfigFile(dir),
-        readManifest(workspace.root, dir, pkgJsonPath),
-      ])
-      if (text === null) {
-        // A member dir with a vx config and no manifest was skipped without
-        // a word: `--all` said no package matched, and a run from inside
-        // it "not inside a project" (D-128). The config was found in the
-        // same flight as the failed read, so naming it costs nothing.
-        if (configPath !== null) {
-          process.stderr.write(
-            `vx: ${shownDir(workspace.root, dir)} has a vx config but no package.json — skipped: vx names a project by its package.json "name"\n`,
-          )
-        }
-        return null
-      }
-      const pkg = parsePackageJson(text, pkgJsonPath)
-      return { dir, pkg, configPath }
-    }),
-  )
+  const nested = [...gitlinks, ...embedded]
+  const prefixed = inner.flatMap((files, i) => files.map((f) => `${nested[i]}/${f}`))
+  return [...configs, ...prefixed]
+}
 
-  const byName = new Map<string, NonNullable<(typeof loaded)[number]>[]>()
-  for (const entry of loaded) {
-    if (entry === null) continue
-    const { dir, pkg, configPath } = entry
-    // npm and pnpm take `../ext/*`, but `--affected` asks git from the root
-    // and sees nothing outside it: an edit there moved the task's key and
-    // selected nothing, green.
-    const rel = relPosix(workspace.root, dir)
-    if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
-      throw new UserError(
-        `workspace member ${rel} (${dir}) is outside the workspace root ${workspace.root}: ` +
-          'vx keeps every project under the root. Move the workspace root up to a directory that holds every member.',
-      )
-    }
-    if (!pkg.name) {
-      nameless?.push(dir)
-      // A nameless manifest can't be addressed, filtered, or made affected —
-      // and vx identifies projects by name, so it simply vanishes. Silent is
-      // fine for a dir that declares no tasks; a dir with a vx config was
-      // meant to run.
-      if (configPath !== null) {
-        process.stderr.write(
-          `vx: ${shownDir(workspace.root, dir)} has a vx config but its package.json has no "name" — skipped\n`,
-        )
-      }
-      continue
-    }
-    const group = byName.get(pkg.name)
-    if (group === undefined) byName.set(pkg.name, [entry])
-    else group.push(entry)
+/** `git <args>`'s NUL-separated output at `cwd`. */
+async function gitZ(cwd: string, args: string[]): Promise<string[]> {
+  let proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'>
+  try {
+    proc = Bun.spawn({
+      cmd: [executablePath('git'), ...args],
+      cwd,
+      env: gitEnv(),
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+  } catch (err) {
+    if (isExecutableMissing(err)) throw gitSpawnRefusal(cwd)
+    throw err
   }
-  const projects: ProjectMeta[] = []
-  const shared: string[] = []
-  let rootReal: string | undefined
-  for (const [name, found] of byName) {
-    // One package reached by two paths (a member and a link to it) is one
-    // project, not a name two packages share: `apps/docs -> ../packages/docs`
-    // was refused as a duplicate and told to rename one (D-135). Resolved
-    // only here, so a workspace without a shared name pays nothing.
-    let group = found
-    if (group.length > 1) {
-      rootReal ??= await realpath(workspace.root)
-      group = await oneEntryPerPackage(group, workspace.root, rootReal)
-    }
-    if (group.length === 1) {
-      const { dir, pkg, configPath } = group[0]!
-      projects.push(withCatalogs({ name, dir, packageJson: pkg, configPath }, workspace))
-      continue
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).bytes(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  if (code !== 0)
+    throw new UserError(`git ls-files failed (exit ${code}): ${err.trim()}`, 'VX_E_GIT')
+  return new TextDecoder('utf-8', { ignoreBOM: true })
+    .decode(out)
+    .split('\0')
+    .filter((p) => p !== '')
+}
+
+/** The config paths under `root` outside git, root-relative: no dot-directory, no `node_modules`. */
+async function scanConfigs(root: string): Promise<string[]> {
+  const out: string[] = []
+  const walk = async (rel: string): Promise<void> => {
+    let entries: Dirent[]
+    try {
+      entries = await readdir(rel === '' ? root : path.join(root, rel), { withFileTypes: true })
+    } catch (err) {
+      if (isOutOfFds(err)) throw err
+      return
     }
-    // The root's own manifest is '' relative to itself, and the refusal read
-    // "in workspace:  and packages/a" (D-127).
-    const dirs = group
-      .map((e) => relPosix(workspace.root, e.dir))
-      .sort()
-      .map((d) => (d === '' ? 'the workspace root' : d))
-    // pnpm accepts two manifests of one name (vite's playground, sveltejs/kit's
-    // test apps); vx cannot, since a project is addressed by it. Like a
-    // nameless one, a pair that declares no vx tasks is left out, so the
-    // rest of the workspace runs (vite was refused whole, 2026-10-01); one
-    // with a vx config was meant to run, and is refused with the way on.
-    if (group.some((e) => e.configPath !== null)) {
-      throw new UserError(
-        `Duplicate package name "${name}" in workspace: ${dirs.join(' and ')}; ` +
-          'vx names a project by its package name — rename one, or leave one out with a `!` pattern in the workspace globs',
-      )
+    // A nested workspace's projects are its own.
+    if (rel !== '' && entries.some((e) => e.name === '.vx') && (await workspaceFileIn(root, rel)))
+      return
+    const below: string[] = []
+    for (const e of entries) {
+      const child = rel === '' ? e.name : `${rel}/${e.name}`
+      if (CONFIG_RANK.has(e.name)) out.push(child)
+      else if (e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+        below.push(child)
     }
-    shared.push(`${name} (${dirs.join(', ')})`)
-  }
-  if (shared.length > 0) {
-    shared.sort()
-    const shown =
-      shared.slice(0, 2).join('; ') + (shared.length > 2 ? `; and ${shared.length - 2} more` : '')
-    process.stderr.write(
-      `vx: left out, as no project can be addressed by a name several manifests share (none has a vx config): ${shown}\n`,
-    )
+    await Promise.all(below.map(walk))
   }
+  await walk('')
+  return out
+}
 
-  // Code-unit order, not `localeCompare`: ICU collation cost 28 ms of a
-  // 300 ms warm run at 1000 projects, and a stable deterministic order is
-  // all any consumer needs.
-  return projects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+async function workspaceFileIn(root: string, rel: string): Promise<boolean> {
+  const names = await readdir(path.join(root, rel, '.vx')).catch(() => [] as string[])
+  return names.some((n) => n.startsWith('workspace.'))
 }
 
+/** How each project got its name, when not by its path: `config`, or the plugin's name. */
+const namedBy = new WeakMap<ProjectMeta, string>()
+
 /**
- * The entries of a name group, one per real directory. Of several paths to
- * one package, the one that reaches it through no link inside the
- * workspace is kept, else the first in path order.
+ * The projects a lock records, by directory: what a run starts from. Named
+ * by the locked config's `name`, else by path; a `discover` plugin may name
+ * a path-named one after this.
  */
-async function oneEntryPerPackage<T extends { dir: string }>(
-  group: T[],
+export function lockedProjects(
   root: string,
-  rootReal: string,
-): Promise<T[]> {
-  const byReal = new Map<string, T[]>()
-  for (const entry of group) {
-    const real = realpathOf(entry.dir)
-    const same = byReal.get(real)
-    if (same === undefined) byReal.set(real, [entry])
-    else same.push(entry)
-  }
-  if (byReal.size === group.length) return group
-  const kept: T[] = []
-  for (const [real, paths] of byReal) {
-    const direct = paths.find((e) => relPosix(root, e.dir) === relPosix(rootReal, real))
-    kept.push(direct ?? paths.sort((a, b) => (a.dir < b.dir ? -1 : 1))[0]!)
+  locked: Readonly<Record<string, { readonly file: string; readonly config: ProjectConfig }>>,
+): ProjectMeta[] {
+  const metas: ProjectMeta[] = []
+  for (const rel of Object.keys(locked)) {
+    const entry = locked[rel]!
+    const dir = rel === '.' ? root : path.join(root, rel)
+    const name = entry.config.name
+    const meta: ProjectMeta = {
+      name: name ?? pathName(root, dir),
+      dir,
+      configPath: path.join(dir, entry.file),
+    }
+    if (name !== undefined) namedBy.set(meta, 'config')
+    metas.push(meta)
   }
-  return kept
+  return metas
 }
 
 /**
- * A directory a plugin's `discover` hook names, as a project meta; null
- * when `known` already holds it under that name. `by` names the plugin in
- * a refusal. A directory without a `package.json` is a project by the
- * plugin's name alone.
+ * The project a plugin's `discover` entry names: a new meta (`added`) for a
+ * directory that is not a project yet, else the project already there,
+ * renamed when its name was its path's. A config's `name` wins over the
+ * plugin's; a name another plugin gave is not changed. `by` names the
+ * plugin in a refusal.
  */
-export async function namedProject(
-  workspace: Workspace,
+export async function discoveredProject(
+  root: string,
   known: readonly ProjectMeta[],
-  named: { readonly dir: string; readonly name: string },
+  entry: {
+    readonly dir: string
+    readonly name?: string
+    readonly deps?: readonly string[]
+    readonly reach?: readonly string[]
+  },
   by: string,
-): Promise<ProjectMeta | null> {
+): Promise<{ meta: ProjectMeta; added: boolean }> {
   const where = `plugin '${by}' named project`
-  if (typeof named?.name !== 'string' || named.name === '' || typeof named.dir !== 'string') {
-    throw new UserError(`${where} ${JSON.stringify(named)}: expected { dir: string, name: string }`)
-  }
-  // The rules `parsePackageJson` holds a manifest's name to: a plugin's name
-  // for a directory with no `name` of its own skipped them, and `a#b` planned
-  // under `--all` while no run spec or dependsOn could reach it.
-  if (named.name.trim() !== named.name) {
+  const dirList = (v: unknown): boolean =>
+    v === undefined || (Array.isArray(v) && v.every((d) => typeof d === 'string'))
+  if (
+    typeof entry?.dir !== 'string' ||
+    (entry.name !== undefined && (typeof entry.name !== 'string' || entry.name === '')) ||
+    !dirList(entry.deps) ||
+    !dirList(entry.reach)
+  ) {
     throw new UserError(
-      `${where} ${JSON.stringify(named.name)}: the name has surrounding whitespace`,
+      `${where} ${JSON.stringify(entry)}: expected { dir: string, name?: string, deps?: string[], reach?: string[] }`,
     )
   }
-  if (named.name.includes('#')) {
-    throw new UserError(
-      `${where} "${named.name}": the name holds "#" — vx addresses a task as <name>#<task>`,
-    )
+  const name = entry.name
+  if (name !== undefined) {
+    const bad = nameFault(name)
+    if (bad !== null) throw new UserError(`${where} ${JSON.stringify(name)}: ${bad}`)
   }
-  const dir = path.resolve(workspace.root, named.dir)
-  const rel = relPosix(workspace.root, dir)
+  const dir = path.resolve(root, entry.dir)
+  const rel = relPosix(root, dir)
+  const named = name === undefined ? '' : ` "${name}"`
   if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
-    throw new UserError(`${where} "${named.name}" at ${dir}: outside the workspace root`)
+    throw new UserError(`${where}${named} at ${dir}: outside the workspace root`)
   }
   const shown = rel === '' ? '.' : rel
-  for (const p of known) {
-    if (p.dir === dir && p.name === named.name) return null
-    if (p.dir === dir) {
-      throw new UserError(`${where} "${named.name}" at ${shown}: already the project "${p.name}"`)
-    }
-    if (p.name === named.name) {
+  const meta = known.find((p) => p.dir === dir)
+  if (meta !== undefined) {
+    const from = namedBy.get(meta)
+    if (name === undefined || name === meta.name || from === 'config') return { meta, added: false }
+    if (from !== undefined) {
       throw new UserError(
-        `${where} "${named.name}" at ${shown}: the name is taken by ${relPosix(workspace.root, p.dir) || '.'}`,
+        `${where} "${name}" at ${shown}: plugin '${from}' already named it "${meta.name}"`,
       )
     }
+    meta.name = name
+    namedBy.set(meta, by)
+    return { meta, added: false }
   }
-  const pkgJsonPath = dir + path.sep + 'package.json'
-  const [configPath, text] = await Promise.all([
-    findConfigFile(dir),
-    readManifest(workspace.root, dir, pkgJsonPath),
-  ])
   if (
-    text === null &&
     !(await stat(dir).then(
       (st) => st.isDirectory(),
       () => false,
     ))
   ) {
-    throw new UserError(`${where} "${named.name}" at ${shown}: no such directory`)
-  }
-  const parsed: Partial<PackageJson> = text === null ? {} : parsePackageJson(text, pkgJsonPath)
-  // A nameless manifest names nothing to disagree with (Nx's own projects).
-  const pkg: PackageJson = { ...parsed, name: parsed.name ?? named.name }
-  if (pkg.name !== named.name) {
-    throw new UserError(
-      `${where} "${named.name}" at ${shown}: its package.json names it "${pkg.name ?? ''}"`,
-    )
+    throw new UserError(`${where}${named} at ${shown}: no such directory`)
   }
-  return withCatalogs({ name: named.name, dir, packageJson: pkg, configPath }, workspace)
+  const added: ProjectMeta = { name: name ?? pathName(root, dir), dir, configPath: null }
+  if (name !== undefined) namedBy.set(added, by)
+  return { meta: added, added: true }
 }
 
-function withCatalogs(meta: ProjectMeta, workspace: Workspace): ProjectMeta {
-  if (workspace.catalogs !== undefined) meta.catalogs = workspace.catalogs
-  return meta
+/** Why `name` cannot name a project, or null. */
+function nameFault(name: string): string | null {
+  if (name.trim() !== name) return 'the name has surrounding whitespace'
+  // A task is `<project>#<task>` split at the first `#`.
+  if (name.includes('#')) return 'the name holds "#" — vx addresses a task as <name>#<task>'
+  return null
+}
+
+/**
+ * Refuses two projects of one name, naming both directories, and a name
+ * no task spec can address: a path name holding `#` or surrounding
+ * whitespace (set `name`), or `//` on a directory other than the root.
+ * Returns `metas` sorted by name.
+ */
+export function checkProjectNames(root: string, metas: ProjectMeta[]): ProjectMeta[] {
+  metas.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  for (let i = 0; i < metas.length; i++) {
+    const meta = metas[i]!
+    const rel = relPosix(root, meta.dir) || '.'
+    if (meta.name === ROOT_NAME && rel !== '.') {
+      throw new UserError(`${rel}: "//" names the workspace root — set another \`name\``)
+    }
+    const fault = namedBy.has(meta) ? null : nameFault(meta.name)
+    if (fault !== null) {
+      throw new UserError(
+        `${rel}: a project is named by its path unless named, and ${fault.replace('the name', 'this one')} — set \`name\` in its vx.config`,
+      )
+    }
+    const next = metas[i + 1]
+    if (next !== undefined && next.name === meta.name) {
+      const dirs = [meta, next].map((m) => relPosix(root, m.dir) || '.').sort()
+      throw new UserError(
+        `two projects are named "${meta.name}": ${dirs[0]} and ${dirs[1]} — give one another \`name\` in its vx.config`,
+      )
+    }
+  }
+  return metas
 }