@vzn/vx 0.0.652 → 0.0.653

package/src/workspace/config-schema.ts

@@ -23,6 +23,7 @@ import {
   UserError,
   BUN_GLOB_WILDCARDS,
   EXTGLOB,
+  braceAlternatives,
   braceRange,
   BRACE_RANGE_LIMIT,
   anyTaskGlob,
@@ -179,15 +180,17 @@ function validateSettingsAt(value: unknown, at: string, configPath: string): voi
     }
     return
   }
-  if (at === 'run.rules.dependencies') validateDependencyRules(value, where)
+  if (at === 'run.rules.dependencies') validateDependencyRules(value, where, configPath)
   else validateSettingValue(value, at, where)
 }
 
 const RULE_FIELDS = new Set(['from', 'allow', 'deny'])
 
-function validateDependencyRules(value: unknown, where: string): void {
+function validateDependencyRules(value: unknown, where: string, configPath: string): void {
   const shape = `an array of { from, allow?, deny? }, each a selector like 'tag:app' or '@acme/*'`
   if (!Array.isArray(value)) throw new UserError(`${where} must be ${shape}`)
+  // The whole path inside one code span, as the frame reads a setting.
+  const at = (i: number, rest = '') => `${configPath}: \`run.rules.dependencies[${i}]${rest}\``
   const selector = (v: unknown) => typeof v === 'string' && v.trim() !== '' && v !== 'tag:'
   const matchable = (v: string, field: string) => {
     const why = ruleSelectorProblem(v)
@@ -198,24 +201,24 @@ function validateDependencyRules(value: unknown, where: string): void {
       )
   }
   for (const [i, rule] of (value as unknown[]).entries()) {
-    const at = `${where}[${i}]`
     if (typeof rule !== 'object' || rule === null || Array.isArray(rule))
-      throw new UserError(`${at} must be { from, allow?, deny? }`)
-    assertKnownFields(rule, RULE_FIELDS, at)
+      throw new UserError(`${at(i)} must be { from, allow?, deny? }`)
+    assertKnownFields(rule, RULE_FIELDS, at(i))
     const { from, allow, deny } = rule as Record<string, unknown>
-    if (!selector(from)) throw new UserError(`${at}.from must be a selector like 'tag:app'`)
-    matchable(from as string, `${at}.from`)
+    if (!selector(from)) throw new UserError(`${at(i, '.from')} must be a selector like 'tag:app'`)
+    matchable(from as string, at(i, '.from'))
     for (const [k, list] of [
       ['allow', allow],
       ['deny', deny],
     ] as const) {
+      const field = at(i, `.${k}`)
       if (list !== undefined && (!Array.isArray(list) || !list.every(selector)))
-        throw new UserError(`${at}.${k} must be an array of selectors like 'tag:lib'`)
-      for (const [j, v] of ((list ?? []) as string[]).entries()) matchable(v, `${at}.${k}[${j}]`)
+        throw new UserError(`${field} must be an array of selectors like 'tag:lib'`)
+      for (const [j, v] of ((list ?? []) as string[]).entries()) matchable(v, at(i, `.${k}[${j}]`))
     }
     // A rule that says nothing reads as a constraint and checks nothing.
     if (allow === undefined && deny === undefined)
-      throw new UserError(`${at} names neither \`allow\` nor \`deny\``)
+      throw new UserError(`${at(i)} names neither \`allow\` nor \`deny\``)
   }
 }
 
@@ -514,12 +517,14 @@ export function validateProjectConfig(
   config: ProjectConfig,
   configPath: string,
   ownConfig: string | null = configPath,
+  /** The caller refused non-JSON values already and passes a JSON copy (project-loader.ts). */
+  jsonCopy = false,
 ): void {
   // Before the schema, on the object as it stands: the key folds its JSON,
   // so a value JSON cannot carry is refused here and in the config worker
   // alike (json-data.ts). A plugin's `project` edit and a lock entry cross
   // this line too.
-  const [nonJson] = nonJsonPaths(config)
+  const [nonJson] = jsonCopy ? [] : nonJsonPaths(config)
   if (nonJson !== undefined) throw new UserError(nonJsonMessage(configPath, nonJson))
   // The top level too: `task:` (singular) loaded as a project with no
   // tasks and every request against it said "no projects declare".
@@ -597,7 +602,13 @@ export function validateProjectConfig(
     }
     if (exec !== undefined) {
       if (typeof exec !== 'object' || exec === null) {
-        throw new UserError(`${where}.exec must be an object with a \`command\` string`)
+        // A command written as the exec itself, as the task-as-a-string
+        // refusal above spells its fix.
+        throw new UserError(
+          typeof exec === 'string'
+            ? `${where}.exec must be an object — a command is { exec: { command: ${JSON.stringify(exec)} } }`
+            : `${where}.exec must be an object with a \`command\` string`,
+        )
       }
       assertKnownFields(exec, EXEC_FIELDS, `${where}.exec`)
       const sandbox = (exec as { sandbox?: unknown }).sandbox
@@ -648,11 +659,33 @@ export function validateProjectConfig(
           )
         }
       }
+      const worker = (exec as { worker?: unknown }).worker
+      if (worker !== undefined && (typeof worker !== 'string' || worker.trim().length === 0)) {
+        throw new UserError(`${where}.exec.worker must be a worker type's name (or omitted)`)
+      }
       const env = (exec as { env?: unknown }).env
       if (env !== undefined) {
         if (typeof env !== 'object' || env === null) {
           throw new UserError(`${where}.exec.env must be an object (or omitted)`)
         }
+        // `env: { NODE_ENV: 'production' }` (Turbo's and Nx's shape): name
+        // the level the variable belongs at, not only the allowed fields.
+        const plain = Array.isArray(env)
+          ? undefined
+          : Object.entries(env).find(
+              ([k, v]) =>
+                !ENV_FIELDS.has(k) &&
+                // `passthrough` is a typo of a field, not a variable.
+                nearest(k, ENV_FIELDS) === undefined &&
+                ['string', 'number', 'boolean'].includes(typeof v),
+            )
+        if (plain !== undefined) {
+          throw new UserError(
+            `${where}.exec.env has unknown field "${plain[0]}" ` +
+              `(allowed: ${[...ENV_FIELDS].sort().join(', ')}) — vx spells it ` +
+              `exec.env.define: { ${plain[0]}: ${JSON.stringify(String(plain[1]))} }`,
+          )
+        }
         // `env: { set: {...} }` loaded and defined nothing — the one level
         // without this check until 2026-09-10 (tests/schema-unknown-keys).
         assertKnownFields(env, ENV_FIELDS, `${where}.exec.env`)
@@ -806,9 +839,12 @@ export function validateProjectConfig(
     }
     if (dependsOn !== undefined) {
       if (!Array.isArray(dependsOn) || dependsOn.some((s) => typeof s !== 'string')) {
+        // One name, not in a list: the fix is that list.
         throw new UserError(
-          `${where}.dependsOn must be an array of strings ` +
-            `(Turbo/Nx micro-syntax: 'name', '^name', 'pkg#name')`,
+          typeof dependsOn === 'string'
+            ? `${where}.dependsOn must be an array — write dependsOn: [${JSON.stringify(dependsOn)}]`
+            : `${where}.dependsOn must be an array of strings ` +
+                `(Turbo/Nx micro-syntax: 'name', '^name', 'pkg#name')`,
         )
       }
     }
@@ -924,6 +960,10 @@ export function validateProjectConfig(
             throw err
           }
         }
+        // The selection starts empty and a `!` entry only subtracts, so a
+        // list of negations folded no dependency and the key stopped moving
+        // with every upstream, as a negation-only inputs.files does.
+        assertTaskFiltersNotNegationOnly(taskFilters, `${where}.inputs.tasks`)
         assertFilterNamesDeclaredDeps(taskFilters, task.dependsOn, where)
       }
       for (const field of ['runtime', 'workspaceRuntime'] as const) {
@@ -1078,6 +1118,7 @@ const EXEC_FIELDS = new Set([
   'remote',
   'sandbox',
   'platforms',
+  'worker',
 ])
 const PERSISTENT_FIELDS = new Set(['readyWhen'])
 const ENV_FIELDS = new Set(['passThrough', 'define', 'secret'])
@@ -1274,7 +1315,11 @@ function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: s
     if (!allowed.has(key)) {
       // The nearest accepted spelling first: the list says what the level
       // takes, the hint says which one was meant.
-      const foreign = FOREIGN_FIELDS.get(allowed)?.[key] ?? nestedHome(allowed, key)
+      // Own keys only: `constructor` read Object's and printed its source.
+      const spellings = FOREIGN_FIELDS.get(allowed)
+      const foreign =
+        (spellings !== undefined && Object.hasOwn(spellings, key) ? spellings[key] : undefined) ??
+        nestedHome(allowed, key)
       const near =
         nearest(key, allowed) ?? (allowed === WORKSPACE_FIELDS ? nearestSetting(key) : undefined)
       throw new UserError(
@@ -1384,14 +1429,25 @@ function assertNoForeignToken(glob: string, where: string): void {
  * and names both.
  */
 function assertNoGluedGlobstar(glob: string, where: string): void {
+  if (gluesGlobstar(glob)) throw gluedGlobstar(glob, `"${glob}"`, where)
+  // Split on `{` `}` `,` alone, `src/{a,**}.ts` passed and expanded to
+  // `src/**.ts`, one level.
+  const alt = braceAlternatives(glob).find(gluesGlobstar)
+  if (alt !== undefined) throw gluedGlobstar(alt, `"${glob}" expands to "${alt}": that`, where)
+}
+
+function gluesGlobstar(glob: string): boolean {
   const body = glob.startsWith('!') ? glob.slice(1) : glob
-  if (!body.split(/[/{},]/).some((seg) => seg.includes('**') && /[^*]/.test(seg))) return
+  return body.split(/[/{},]/).some((seg) => seg.includes('**') && /[^*]/.test(seg))
+}
+
+function gluedGlobstar(glob: string, subject: string, where: string): UserError {
   const deep = glob.replace(/\*\*([^*/{},]+)/g, '**/*$1').replace(/([^*/{},]+)\*\*/g, '$1*/**')
   const one = glob.replace(/\*{2,}/g, (run, at: number) =>
     /[^*/{},]/.test(glob[at - 1] ?? '') || /[^*/{},]/.test(glob[at + run.length] ?? '') ? '*' : run,
   )
-  throw new UserError(
-    `${where}: "${glob}" glues ** to other text in one path segment, which vx's glob engine ` +
+  return new UserError(
+    `${where}: ${subject} glues ** to other text in one path segment, which vx's glob engine ` +
       `reads as one *, a single directory level. Write "${deep}" for every depth, or "${one}" ` +
       `for one level.`,
   )
@@ -1663,8 +1719,8 @@ function isEnvName(name: unknown): name is string {
  * A task name `dependsOn`, `inputs.tasks` and the CLI can name. Each
  * refused shape loaded and could not be referenced: `x#y` read as project
  * `x`, `^gen` as every dependency's `gen`, a `*` as a pattern, `''` ran
- * under `--all` as `a#` and `vx run a#` refused it, and a padded name was
- * trimmed away by the reader (item 1000).
+ * under `--all` as `a#` and `vx run a#` refused it, `-x` as a flag, and a
+ * padded name was trimmed away by the reader (item 1000).
  */
 function assertTaskName(name: string, configPath: string): void {
   const why = taskNameProblem(name)
@@ -1687,9 +1743,11 @@ export function taskNameProblem(name: string): string | null {
           ? "holds '*', which makes it a pattern"
           : name.startsWith('^') || name.startsWith('!')
             ? `starts with '${name[0]}', which names dependencies' tasks or negates`
-            : hasControl(name)
-              ? 'holds a control character'
-              : null
+            : name.startsWith('-')
+              ? "starts with '-', which the CLI reads as a flag"
+              : hasControl(name)
+                ? 'holds a control character'
+                : null
 }
 
 /**
@@ -1741,6 +1799,18 @@ function assertNotNegationOnly(globs: readonly string[], where: string): void {
   )
 }
 
+function assertTaskFiltersNotNegationOnly(filters: readonly string[], where: string): void {
+  if (filters.length === 0) return
+  if (filters.some((f) => !f.startsWith('!'))) return
+  throw new UserError(
+    `${where}: every entry is a negation, which selects NOTHING (got ${JSON.stringify(filters)}) — ` +
+      `negations only subtract from the dependencies a positive entry already selected, so this ` +
+      `task would fold no upstream hash and its cache key would stop tracking its dependencies. ` +
+      `Add the positive entry you meant, e.g. ['*', '^*', ${JSON.stringify(filters[0])}], ` +
+      `or use [] to decouple on purpose.`,
+  )
+}
+
 /**
  * A `!` entry subtracts wherever it sits in the list, so a file named
  * outright after it (`['src/**', '!src/gen/**', 'src/gen/keep.ts']`) never
@@ -1860,6 +1930,19 @@ function assertStringArray(v: unknown, where: string): void {
   }
 }
 
+/**
+ * Only `~` and `~/…` mean the home: `~root/x/` was read as `$HOME/root/x`,
+ * and vx created that directory on the host.
+ */
+function assertOwnHome(v: readonly string[], where: string): void {
+  const other = v.find((p) => p.startsWith('~') && p !== '~' && !p.startsWith('~/'))
+  if (other === undefined) return
+  throw new UserError(
+    `${where}: ${JSON.stringify(other)} names a user's home, which vx does not expand — ` +
+      `write '~/…' for your own home, or an absolute path`,
+  )
+}
+
 /**
  * Validate a `sandbox: {...}` block — one capability shape, whatever the
  * platform ends up doing with it. Unknown keys are refused rather than
@@ -1892,7 +1975,22 @@ function validateSandbox(sandbox: unknown, where: string): void {
     for (const f of GRANT_PATH_FIELDS) {
       // Patterns are allowed here: macOS matches them natively, Linux
       // expands them against the filesystem at resolve time.
-      if (g[f] !== undefined) assertStringArray(g[f], `${where}.sandbox.allow.${f}`)
+      if (g[f] === undefined) continue
+      assertStringArray(g[f], `${where}.sandbox.allow.${f}`)
+      assertOwnHome(g[f] as string[], `${where}.sandbox.allow.${f}`)
+    }
+    // SRT's Linux observer reports a write's path with each control
+    // character turned into a space, so a write a grant holding one covers
+    // read as a violation of the path spelled with a space, and a real
+    // write there reads the same: no match passes one and not the other.
+    // Reads are traced by strace, which escapes them.
+    const ctl = ((g['write'] as string[] | undefined) ?? []).find(hasControl)
+    if (ctl !== undefined) {
+      throw new UserError(
+        `${where}.sandbox.allow.write: ${JSON.stringify(ctl)} holds a control character, ` +
+          `which the Linux sandbox's report of a write does not keep (it spells a tab as a ` +
+          `space), so a write under it cannot be told from a refused one — rename it`,
+      )
     }
     for (const f of GRANT_NAME_FIELDS) {
       if (g[f] !== undefined) assertStringArray(g[f], `${where}.sandbox.allow.${f}`)
@@ -1949,7 +2047,10 @@ function validateSandbox(sandbox: unknown, where: string): void {
     // Patterns, not prefixes — `ignore` is vx's own filter over lines it
     // already holds, so a glob costs nothing and works on every platform.
     for (const f of IGNORE_FIELDS) {
-      if (g[f] !== undefined) assertStringArray(g[f], `${where}.sandbox.ignore.${f}`)
+      if (g[f] === undefined) continue
+      assertStringArray(g[f], `${where}.sandbox.ignore.${f}`)
+      if (f === 'read' || f === 'write')
+        assertOwnHome(g[f] as string[], `${where}.sandbox.ignore.${f}`)
     }
   }
 }

package/src/workspace/dependencies-lock.ts

@@ -11,8 +11,8 @@
 // changed lockfile's base digests are there, so the base side is never
 // parsed. `vx lock --check` holds it to a fresh derivation.
 
-import { rename, rm } from 'node:fs/promises'
 import path from 'node:path'
+import type { PendingWrite } from '../util/index.js'
 import type { ProjectMeta } from './workspace.js'
 import { lockKey } from './lockfile.js'
 import { type LoadReads, readOnce } from './load-reads.js'
@@ -90,19 +90,12 @@ function dependenciesLockText(lock: DependenciesLock): string {
   return `${JSON.stringify(lock)}\n`
 }
 
-/** Written beside its name and renamed over it, as `writeLockfile`: a reader never sees half a file. */
-export async function writeDependenciesLock(root: string, lock: DependenciesLock): Promise<void> {
-  const file = path.join(root, DEPENDENCIES_LOCK_NAME)
-  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`
-  try {
-    await Bun.write(tmp, dependenciesLockText(lock))
-    await rename(tmp, file)
-  } catch (err) {
-    await rm(tmp, { force: true }).catch(() => {})
-    const e = err as NodeJS.ErrnoException
-    if (typeof e.message === 'string') e.message = e.message.split(tmp).join(file)
-    if (e.path === tmp) e.path = file
-    throw err
+/** The dependency lock's file and bytes, for `writeAllOrNone`. */
+export function dependenciesLockWrite(root: string, lock: DependenciesLock): PendingWrite {
+  return {
+    file: path.join(root, DEPENDENCIES_LOCK_NAME),
+    text: dependenciesLockText(lock),
+    shown: DEPENDENCIES_LOCK_NAME,
   }
 }
 

package/src/workspace/filter.ts

@@ -131,9 +131,18 @@ export function parseFilter(
   if (scoped !== null && !scoped[1]!.startsWith('./') && scoped[1] !== '.') {
     s = scoped[1]!
     gitSince = scoped[2]!
+    // Neither Turbo nor pnpm reads it (both keep `^...` in the name):
+    // `{dir}^...[ref]` dropped the `^...` and selected the inverse, and
+    // the name spellings matched nothing.
+    if (s.endsWith('^...'))
+      throw new UserError(
+        `filter "${raw}" puts ^... before a git ref, which no form reads: ` +
+          `<sel>...[<ref>] is <sel> where it or a dependency changed, ` +
+          `<sel>[<ref>]^... the dependencies of the changed ones`,
+      )
     // The name glob kept the `...` and matched nothing (create-t3-turbo,
     // `@acme/*...[HEAD]`).
-    if (s.endsWith('...') && !s.endsWith('^...')) {
+    if (s.endsWith('...')) {
       s = s.slice(0, -3)
       sinceViaDeps = true
     }

package/src/workspace/index.ts

@@ -28,6 +28,7 @@ export {
   lockKey,
   NO_LOCK,
   readLockfile,
+  lockfileWrite,
   writeLockfile,
   type Lockfile,
   type LockedProject,
@@ -38,7 +39,7 @@ export {
   parseDependenciesLock,
   readDependenciesLock,
   recordedDigests,
-  writeDependenciesLock,
+  dependenciesLockWrite,
   type DependenciesLock,
 } from './dependencies-lock.js'
 export {
@@ -60,6 +61,7 @@ export {
   validateWorkspace,
 } from './config-schema.js'
 export { configImports } from './config-imports.js'
+export { repoIdsOf } from './repo-id.js'
 export {
   checkProjectNames,
   findWorkspaceRoot,

package/src/workspace/json-data.ts

@@ -8,10 +8,14 @@
 // worker's, which never saw it — or, where the validator does not type
 // the value, it was silently outside the key on both. So every path
 // refuses it, before schema validation, by this one rule: the first load
-// on the live object (`validateProjectConfig`), the worker before its
+// on the live object before its JSON copy (project-loader.ts), the worker before its
 // `JSON.stringify` (config-eval.ts). The worker embeds `nonJsonPaths` by its source text, so
 // the function must stay self-contained: no import, no module-scope name.
 //
+// JSON writes only own enumerable string keys: a symbol key or a
+// non-enumerable property vanished from the key and the lock
+// (`"config":{}`), so it is refused too.
+//
 // An `undefined` PROPERTY is allowed: JSON drops it, the validator reads
 // it as absent, and configs write it with conditional spreads. Inside an
 // array it is refused, because JSON writes it as `null`.
@@ -29,13 +33,20 @@ export function nonJsonPaths(value: unknown): NonJsonValue[] {
   // The key or index at each level, rendered only for a finding: the walk
   // runs on every first load, and a path string built per node cost three
   // times the schema check itself.
-  const keys: Array<string | number> = []
+  const keys: Array<string | number | symbol> = []
   // The objects on the path to the one being walked: a cycle throws in
   // `JSON.stringify` and would recurse here forever. A DAG is data.
   const ancestors: object[] = []
+  const MAX_DEPTH = 256
   const found = (is: string): void => {
     let path = ''
-    for (const k of keys) path += typeof k === 'number' ? `[${k}]` : path === '' ? k : `.${k}`
+    for (const k of keys)
+      path +=
+        typeof k === 'number' || typeof k === 'symbol'
+          ? `[${String(k)}]`
+          : path === ''
+            ? k
+            : `.${k}`
     out.push({ path: path === '' ? 'the default export' : path, is })
   }
   const walk = (v: unknown, inArray: boolean): void => {
@@ -45,6 +56,12 @@ export function nonJsonPaths(value: unknown): NonJsonValue[] {
     else if (typeof v === 'number' && !Number.isFinite(v)) found(String(v))
     else if (v === undefined && inArray) found('undefined in an array, which JSON writes as null')
     else if (typeof v === 'object' && v !== null) {
+      // Deeper, the walk and `JSON.stringify` overflowed the stack: a
+      // config 100,000 levels deep was vx's own RangeError (VX_E_INTERNAL).
+      if (ancestors.length >= MAX_DEPTH) {
+        found(`nested deeper than ${MAX_DEPTH} levels`)
+        return
+      }
       if (ancestors.includes(v)) {
         found('a cyclic reference')
         return
@@ -57,6 +74,13 @@ export function nonJsonPaths(value: unknown): NonJsonValue[] {
           walk(v[i], true)
           keys.pop()
         }
+        // Symbols only: listing an array's own names allocates every index
+        // string, +1-4% on a 20k-task lock, for a named property no config writes.
+        for (const key of Object.getOwnPropertySymbols(v)) {
+          keys.push(key)
+          found('a symbol key, which JSON drops')
+          keys.pop()
+        }
         ancestors.pop()
         return
       }
@@ -71,16 +95,18 @@ export function nonJsonPaths(value: unknown): NonJsonValue[] {
         return
       }
       ancestors.push(v)
-      for (const key of Object.keys(v)) {
+      for (const key of Reflect.ownKeys(v)) {
         keys.push(key)
         // Read by descriptor: a getter is code, and each read may answer
         // differently. `vx show` read one three times, so the key, the
         // check and the command could each see another value, and a
         // throwing one surfaced as vx's own stack (D-67). Never called here.
-        const d = Object.getOwnPropertyDescriptor(v, key)
-        if (d !== undefined && d.get !== undefined) found('a getter')
-        else if (d !== undefined && d.set !== undefined) found('a setter')
-        else walk(d?.value, false)
+        const d = Object.getOwnPropertyDescriptor(v, key) as PropertyDescriptor
+        if (typeof key === 'symbol') found('a symbol key, which JSON drops')
+        else if (d.enumerable !== true) found('a non-enumerable property, which JSON drops')
+        else if (d.get !== undefined) found('a getter')
+        else if (d.set !== undefined) found('a setter')
+        else walk(d.value, false)
         keys.pop()
       }
       ancestors.pop()

package/src/workspace/lockfile.ts

@@ -11,11 +11,18 @@
 //     eval-free.
 //   - `vx lock --check` AUDITS it: full re-evaluation + deep equality.
 
-import { readFileSync } from 'node:fs'
-import { rename, rm } from 'node:fs/promises'
+import { readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
 import type { ProjectConfig } from '../config.js'
-import { keysSorted, relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
+import {
+  keysSorted,
+  type PendingWrite,
+  relPosix,
+  UserError,
+  writeAllOrNone,
+  xxh3,
+  xxh3hex,
+} from '../util/index.js'
 import { VERSION } from '../version.js'
 import { validateProjectConfig } from './config-schema.js'
 import { PROJECT_CONFIG_FILENAMES } from './workspace.js'
@@ -38,6 +45,12 @@ export interface Lockfile {
    * by directory, so a name a plugin gives never invalidates the lock.
    */
   projects: Record<string, LockedProject>
+  /**
+   * Root-relative POSIX directories holding their own `.vx/workspace.*`,
+   * where every outer project's outputs stop. Absent when there is none, so a
+   * workspace without one locks the bytes it always did.
+   */
+  nestedWorkspaces?: string[]
   /** Written by `writeLockfile` from the bytes; never read off the object. */
   validated?: string
 }
@@ -101,7 +114,16 @@ export function lockDigest(lock: Lockfile): string | undefined {
  */
 export async function readLockfile(root: string): Promise<Lockfile | null> {
   const file = Bun.file(lockfilePath(root))
-  if (!(await file.exists())) return null
+  if (!(await file.exists())) {
+    // A directory reads as no file: `--check` said "run `vx lock`", which cannot write over it.
+    if (statSync(lockfilePath(root), { throwIfNoEntry: false })?.isDirectory()) {
+      throw new UserError(
+        `${LOCKFILE_NAME} is a directory — remove it and run \`vx lock\``,
+        'VX_E_LOCK',
+      )
+    }
+    return null
+  }
   let parsed: unknown
   let text: string
   try {
@@ -123,7 +145,7 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     throw new UserError(`${LOCKFILE_NAME} must be a JSON object — re-run \`vx lock\``, 'VX_E_LOCK')
   }
-  const lock = parsed as { version?: unknown; projects?: unknown }
+  const lock = parsed as { version?: unknown; projects?: unknown; nestedWorkspaces?: unknown }
   if (lock.version !== LOCKFILE_VERSION) {
     throw new UserError(
       `${LOCKFILE_NAME} has unsupported version ${String(lock.version)} ` +
@@ -153,21 +175,47 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
       Array.isArray(entry) ||
       typeof file !== 'string' ||
       !PROJECT_CONFIG_FILENAMES.includes(file) ||
-      typeof config !== 'object' ||
-      config === null ||
-      Array.isArray(config)
+      !isObj(config) ||
+      // A run trusts these shapes: a string `name`, a `tags` list, a `tasks` object.
+      (config['name'] !== undefined && typeof config['name'] !== 'string') ||
+      (config['tags'] !== undefined && !Array.isArray(config['tags'])) ||
+      (config['tasks'] !== undefined && !isObj(config['tasks']))
     ) {
-      throw new UserError(
-        `${LOCKFILE_NAME}: entry for "${dir}" is malformed — re-run \`vx lock\``,
-        'VX_E_LOCK',
-      )
+      throw malformed(dir)
     }
   }
+  const nested = lock.nestedWorkspaces
+  if (
+    nested !== undefined &&
+    (!Array.isArray(nested) ||
+      nested.some((d) => typeof d !== 'string' || d === '.' || !isLockKey(d)))
+  ) {
+    throw new UserError(
+      `${LOCKFILE_NAME}: \`nestedWorkspaces\` must list directories under the workspace root — re-run \`vx lock\``,
+      'VX_E_LOCK',
+    )
+  }
   pooledIn(parsed as Pooled)
+  // After the pool is put back, as a task may be an index into it. A
+  // string `dependsOn` was walked per character: "dependsOn b#a".
+  for (const [dir, entry] of Object.entries(lock.projects as Record<string, LockedProject>)) {
+    const tasks = entry.config.tasks as Obj | undefined
+    for (const name in tasks) {
+      const t = tasks[name]
+      if (!isObj(t) || (t['dependsOn'] !== undefined && !Array.isArray(t['dependsOn'])))
+        throw malformed(dir)
+    }
+  }
   digests.set(parsed as Lockfile, xxh3hex(text))
   return parsed as Lockfile
 }
 
+const malformed = (dir: string): UserError =>
+  new UserError(
+    `${LOCKFILE_NAME}: entry for "${dir}" is malformed — re-run \`vx lock\``,
+    'VX_E_LOCK',
+  )
+
 /**
  * The project entries of a lock's bytes with its pool put back, or null
  * for bytes that do not parse as a lock: an entry compares across two
@@ -335,31 +383,32 @@ function taskKeysSorted(key: string, value: unknown): unknown {
   return Object.fromEntries(Object.entries(value).map(([name, task]) => [name, keysSorted(task)]))
 }
 
-export async function writeLockfile(root: string, lock: Lockfile): Promise<void> {
-  // Written beside its name and renamed over it: `Bun.write` truncates in
-  // place, so a run, or `vx watch` woken by the write
-  // itself (item 971), could read an empty or half-written lock and fail
-  // on "not valid JSON" (item 972).
-  const file = lockfilePath(root)
-  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`
-  try {
-    // Minified: the file only vx reads, and it loads faster than pretty
-    // JSON (measured, 10k projects: 15.6 ms against 22.5 ms). `vx.lock.json`
-    // beside each config is the copy for people.
-    const sorted = JSON.parse(JSON.stringify(lock.projects, taskKeysSorted)) as Lockfile['projects']
-    const body = JSON.stringify({ version: lock.version, ...pooledOut(sorted) })
-    await Bun.write(tmp, `${body.slice(0, -1)},"validated":"${validatedDigest(body)}"}\n`)
-    await rename(tmp, file)
-  } catch (err) {
-    // Best effort: where the write was refused the temp cannot be named
-    // either (ENOTDIR), and that must not replace the refusal itself.
-    await rm(tmp, { force: true }).catch(() => {})
-    // The refusal names the file the user knows: a read-only checkout read
-    // `open '…/.vx/projects.lock.json.tmp-…'` where it had read the lock's own name.
-    const e = err as NodeJS.ErrnoException
-    if (typeof e.message === 'string') e.message = e.message.split(tmp).join(file)
-    if (e.path === tmp) e.path = file
-    throw err
+/**
+ * Written beside its name and renamed over it: `Bun.write` truncates in
+ * place, so a run, or `vx watch` woken by the write itself (item 971),
+ * could read an empty or half-written lock and fail on "not valid JSON"
+ * (item 972).
+ */
+export function writeLockfile(root: string, lock: Lockfile): Promise<void> {
+  return writeAllOrNone([lockfileWrite(root, lock)], root)
+}
+
+/** The lock's file and bytes, for `writeAllOrNone`. */
+export function lockfileWrite(root: string, lock: Lockfile): PendingWrite {
+  // Minified: the file only vx reads, and it loads faster than pretty
+  // JSON (measured, 10k projects: 15.6 ms against 22.5 ms). `vx.lock.json`
+  // beside each config is the copy for people.
+  const sorted = JSON.parse(JSON.stringify(lock.projects, taskKeysSorted)) as Lockfile['projects']
+  const nested = lock.nestedWorkspaces ?? []
+  const body = JSON.stringify({
+    version: lock.version,
+    ...(nested.length > 0 ? { nestedWorkspaces: nested } : {}),
+    ...pooledOut(sorted),
+  })
+  return {
+    file: lockfilePath(root),
+    text: `${body.slice(0, -1)},"validated":"${validatedDigest(body)}"}\n`,
+    shown: LOCKFILE_NAME,
   }
 }