@vzn/vx 0.0.18 → 0.0.22

package/src/workspace/project-loader.ts

@@ -1,10 +1,18 @@
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { MAX_TIMEOUT_MS, UserError, xxh3hex } from '../util/index.js'
-import { evaluateConfigFresh } from './config-eval.js'
+import { UserError, xxh3hex } from '../util/index.js'
+import { validateProjectConfig, validateWorkspace } from './config-schema.js'
+import { beginEvalRound, evaluateConfigFresh } from './config-eval.js'
+import { hasEsmExport, unprovidedBareImports } from './config-imports.js'
 import { configEvalKey, configEvalKeyFromClosure, type ConfigEvalStore } from './config-cache.js'
+import { readOnce } from './load-reads.js'
 
-const WORKSPACE_CONFIG_FILENAMES = [
+// The validator lives in config-schema.ts; re-exported so a reader that
+// reaches the loader for it (the tests do) keeps working.
+export { validateProjectConfig }
+
+/** The workspace config's filenames at the root, in lookup order. `vx watch` re-runs on an edit to whichever exists. */
+export const WORKSPACE_CONFIG_FILENAMES = [
   'vx.workspace.ts',
   'vx.workspace.mts',
   'vx.workspace.js',
@@ -20,6 +28,80 @@ function assertDefaultObject(mod: unknown, kind: string, configPath: string): vo
   }
 }
 
+/**
+ * The source a load already holds, by the specifier it imports it under.
+ * Bun's loader would open and read a project config a second time; the
+ * `vx-config-bytes` plugin hands it this instead, so the evaluation runs
+ * exactly the bytes the eval-cache key and the import gate saw. It is also
+ * the cheaper load: 1,000 configs imported this way took 80–100 ms against
+ * 180 ms read by Bun (measured 2026-09-24).
+ *
+ * Handed over as a string: `onLoad` reads a byte array as Latin-1, and a
+ * `ü` in a description came back as `ü`. So only UTF-8 is served, and
+ * only ESM (`hasEsmExport`): source handed to `onLoad` is always evaluated
+ * as a module, and a CommonJS config's `module.exports` would vanish. Any
+ * other config takes Bun's own path, which reads the file and decides its
+ * format as it always did. The two paths carry different queries because
+ * `onLoad` cannot decline a path it matched.
+ *
+ * The workspace config is never served. Proving it ESM is the parser's
+ * first use in a warm run, ~0.27 ms, and serving the one file saves less
+ * than that: `loadWorkspaceConfig` measured 0.3 ms slower served (40
+ * interleaved runs, 2026-09-24). Bun reads it a second time instead.
+ */
+//
+// Held by the bytes' hash, not the specifier: Bun hands `onLoad` the path
+// it RESOLVED, which is the real path, so a config reached through a
+// symlinked directory (macOS's `/var` → `/private/var`, every temp root
+// there) came back under a key nobody set, and every such load failed.
+// Equal hashes are equal sources, so two loads of the same bytes share an
+// entry; `uses` keeps it until the last of them has imported.
+const heldSources = new Map<string, { source: string; uses: number }>()
+let serving = false
+
+const HELD_QUERY = /\?vx-held=([0-9a-f]+)$/
+
+function serveHeldSources(): void {
+  if (serving) return
+  serving = true
+  Bun.plugin({
+    name: 'vx-config-bytes',
+    setup(build) {
+      build.onLoad({ filter: HELD_QUERY }, (args) => ({
+        contents: heldSources.get(HELD_QUERY.exec(args.path)![1]!)!.source,
+        loader: /\.[cm]?ts\?/.test(args.path) ? 'ts' : 'js',
+      }))
+    },
+  })
+}
+
+function holdSource(hash: string, source: string): void {
+  const held = heldSources.get(hash)
+  if (held === undefined) heldSources.set(hash, { source, uses: 1 })
+  else held.uses++
+}
+
+function releaseSource(hash: string): void {
+  const held = heldSources.get(hash)!
+  if (--held.uses === 0) heldSources.delete(hash)
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true })
+
+/** `bytes` as the source `onLoad` may stand in for Bun's read with, or null (see `heldSources`). */
+function servableSource(bytes: Uint8Array, loader: 'ts' | 'js'): string | null {
+  let source: string
+  try {
+    source = utf8.decode(bytes)
+  } catch {
+    return null
+  }
+  return hasEsmExport(source, loader) ? source : null
+}
+
+/** vx's module-cache query, which no user wrote: stripped from anything shown to them. */
+const BUST_QUERY = /\?vx-(?:bust|held)=[^'"\s]*/g
+
 // Bun has native TS / ESM execution — no transpiler dep needed. We fold
 // a short content hash into the import URL as a cache-bust key so that:
 //   same content   → same URL → Bun's module cache hits (fast)
@@ -31,20 +113,33 @@ function assertDefaultObject(mod: unknown, kind: string, configPath: string): vo
 async function loadDefaultExport(
   configPath: string,
   kind: string,
-  fresh = false,
-  bytes?: Uint8Array,
+  bytes: Uint8Array,
 ): Promise<unknown> {
-  bytes ??= await Bun.file(configPath).bytes()
-  // `fresh` opts out of module-cache reuse entirely: `vx lock` and
-  // `vx lock --check` must observe the CURRENT environment, and the
-  // content-hash bust would replay an evaluation made under earlier
-  // env values when the file bytes are unchanged in this process.
-  const bust = fresh ? `${xxh3hex(bytes)}-${Bun.randomUUIDv7()}` : xxh3hex(bytes)
+  refuseUnprovidedImports(bytes, configPath, kind)
+  // No random bust for `vx lock`: a project config reaches this import
+  // only on its FIRST load in the process, so nothing is cached under the
+  // URL yet, and a repeat load (the one that could replay an evaluation
+  // made under earlier env values) re-evaluates in a worker instead
+  // (`loadedConfigs`, item 678).
+  const source =
+    kind === 'Project' ? servableSource(bytes, /\.[cm]?ts$/.test(configPath) ? 'ts' : 'js') : null
+  const hash = xxh3hex(bytes)
+  const specifier = `${configPath}?vx-${source !== null ? 'held' : 'bust'}=${hash}`
+  if (source !== null) {
+    serveHeldSources()
+    holdSource(hash, source)
+  }
   let ns: { default?: unknown }
   try {
-    ns = (await import(`${configPath}?vx-bust=${bust}`)) as { default?: unknown }
+    ns = (await import(specifier)) as { default?: unknown }
   } catch (err) {
-    throw unresolvedImportError(err, configPath, kind) ?? err
+    // A served module's frames name its specifier; the user wrote the path.
+    if (err instanceof Error && err.stack !== undefined) {
+      err.stack = err.stack.replaceAll(specifier, configPath).replace(BUST_QUERY, '')
+    }
+    throw configLoadError(err, configPath, kind) ?? err
+  } finally {
+    if (source !== null) releaseSource(hash)
   }
   const mod = ns?.default
   assertDefaultObject(mod, kind, configPath)
@@ -52,28 +147,87 @@ async function loadDefaultExport(
 }
 
 /**
- * A config whose import cannot be resolved is the user's to fix, and the
- * usual cause has one answer: the workspace runs the vx binary and never
- * installed `@vzn/vx`, which its own `vx.workspace.ts` imports. Bun's
- * resolver error also carries the module-cache bust query; the user
- * gets the file they wrote.
+ * A bare import nothing above the config provides is refused BEFORE the
+ * evaluation: left to Bun, a workspace with no `node_modules` would have
+ * the package auto-installed from the registry first (config-imports.ts),
+ * and a config must never download. The message keeps the shape Bun's own
+ * refusal has, with the remedy.
  */
-export function unresolvedImportError(
-  err: unknown,
-  configPath: string,
-  kind: string,
-): UserError | null {
-  if (!(err instanceof Error) || err.name !== 'ResolveMessage') return null
-  const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(err.message)?.[1]
-  const what =
-    spec === undefined ? err.message.replace(/\?vx-bust=\S+/g, '') : `cannot find '${spec}'`
-  const hint =
-    spec?.startsWith('@vzn/vx') === true ? `; install it in the workspace: bun add -d @vzn/vx` : ''
-  return new UserError(`${kind} config ${configPath}: ${what}${hint}`)
+function refuseUnprovidedImports(bytes: Uint8Array, configPath: string, kind: string): void {
+  const loader = /\.[cm]?ts$/.test(configPath) ? 'ts' : 'js'
+  const missing = unprovidedBareImports(
+    new TextDecoder().decode(bytes),
+    path.dirname(configPath),
+    loader,
+  )
+  if (missing.length === 0) return
+  throw new UserError(
+    `${kind} config ${configPath}: cannot find '${missing[0]}' — no node_modules above the config provides it; install the workspace's dependencies first`,
+  )
+}
+
+/**
+ * Where a transpile error was found. Bun's `BuildMessage` carries it as
+ * `position`; the config worker forwards the same three fields (see
+ * config-eval.ts) so the repeat path names the line too.
+ */
+interface BuildPosition {
+  file?: string
+  line?: number
+  column?: number
+}
+
+/**
+ * Turn the two errors Bun's own loader throws into user errors naming the
+ * file the user wrote; every other throw is the config's own and already
+ * carries its location in its stack, so it passes through unchanged.
+ *
+ * `ResolveMessage` — an import that cannot be resolved. The usual cause has
+ * one answer: the workspace runs the vx binary and never installed `@vzn/vx`,
+ * which its own `vx.workspace.ts` imports. Bun's message also carries the
+ * module-cache bust query; the user gets the file they wrote.
+ *
+ * `BuildMessage` — a syntax or transpile error. Its message alone (`Expected
+ * "}" but found end of file`) names no file at all, and the file is not
+ * always the config: a preset the config imports fails the same way, so the
+ * location is taken from the error's position, with the config as the
+ * fallback.
+ */
+export function configLoadError(err: unknown, configPath: string, kind: string): UserError | null {
+  // Matched on SHAPE, not `instanceof Error`. Bun's `BuildMessage` is not an
+  // Error subclass on every build — on 1.3.11 its prototype chain is
+  // `BuildMessage → Object` — and an `instanceof` guard there hands the user
+  // a raw transpile object for a missing brace in their own config, which is
+  // the defect `isFsRefusal` exists to prevent one layer down. The two names
+  // below are Bun's own and nothing else answers to them, so this is
+  // narrower than it looks: every other throw still passes through (2026-09-20).
+  if (err === null || typeof err !== 'object') return null
+  const { name, message } = err as { name?: unknown; message?: unknown }
+  if (typeof message !== 'string') return null
+  if (name === 'ResolveMessage') {
+    const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(message)?.[1]
+    const what = spec === undefined ? message.replace(BUST_QUERY, '') : `cannot find '${spec}'`
+    const hint =
+      spec?.startsWith('@vzn/vx') === true
+        ? `; install it in the workspace: bun add -d @vzn/vx`
+        : ''
+    return new UserError(`${kind} config ${configPath}: ${what}${hint}`)
+  }
+  if (name === 'BuildMessage') {
+    const pos = (err as { position?: BuildPosition | null }).position ?? {}
+    const file = typeof pos.file === 'string' && pos.file.length > 0 ? pos.file : configPath
+    const at =
+      typeof pos.line === 'number'
+        ? `:${pos.line}${typeof pos.column === 'number' ? `:${pos.column}` : ''}`
+        : ''
+    const where = file === configPath ? `${configPath}${at}` : `${configPath} (in ${file}${at})`
+    return new UserError(`${kind} config ${where}: ${message}`)
+  }
+  return null
 }
 
 export interface LoadProjectConfigOptions {
-  /** Observe the CURRENT environment: no module-cache reuse, no eval cache. */
+  /** Observe the CURRENT environment: no eval cache, even when `evalCache` is passed. */
   fresh?: boolean
   /**
    * Serve a provably-pure config from its cached evaluation (see
@@ -95,6 +249,11 @@ export async function loadProjectConfigs(
   const evalCache = opts?.fresh === true ? undefined : opts?.evalCache
   const store = evalCache?.store
   const hashFile = store?.hashFile?.bind(store)
+  const hashBytes = store?.hashBytes?.bind(store)
+  // The slow path keys from the bytes it already holds; `hashFile` there
+  // memoised every closure file one autocommit upsert at a time (item 615).
+  const slowKeyHash =
+    hashBytes !== undefined ? { hashBytes } : hashFile !== undefined ? { hashFile } : {}
   // The warm fast path: a config whose ordered closure the store remembers
   // is keyed from per-file identities (a stat each, no read, no scan); the
   // slow path below reads, gates and scans, and indexes the closure for
@@ -103,13 +262,29 @@ export async function loadProjectConfigs(
     hashFile !== undefined && store?.getConfigClosures !== undefined
       ? store.getConfigClosures(configPaths)
       : new Map<string, string[]>()
+  // Every indexed closure's files identified in ONE batch, then keyed from
+  // the map; a file the batch could not stat has no identity, which makes
+  // that config's fast key miss and sends it down the slow path exactly as
+  // a throwing per-file `hashFile` did.
+  let fastHashFile = hashFile
+  if (closures.size > 0 && store?.hashFiles !== undefined) {
+    const files = new Set<string>()
+    for (const closure of closures.values()) for (const f of closure) files.add(f)
+    const identities = await store.hashFiles([...files])
+    fastHashFile = (file: string): Promise<string> => {
+      const id = identities.get(file)
+      return id === undefined
+        ? Promise.reject(new Error(`no identity for ${file}`))
+        : Promise.resolve(id)
+    }
+  }
   const prepared = await Promise.all(
     configPaths.map(async (configPath) => {
       const closure = closures.get(configPath)
-      if (closure !== undefined && evalCache !== undefined && hashFile !== undefined) {
+      if (closure !== undefined && evalCache !== undefined && fastHashFile !== undefined) {
         const fastKey = await configEvalKeyFromClosure({
           closure,
-          hashFile,
+          hashFile: fastHashFile,
           workspaceFingerprint: evalCache.workspaceFingerprint,
         })
         if (fastKey !== null) return { configPath, bytes: null, cacheKey: fastKey, indexed: true }
@@ -122,7 +297,7 @@ export async function loadProjectConfigs(
               configPath,
               bytes,
               workspaceFingerprint: evalCache.workspaceFingerprint,
-              ...(hashFile !== undefined ? { hashFile } : {}),
+              ...slowKeyHash,
             })
       return {
         configPath,
@@ -148,58 +323,89 @@ export async function loadProjectConfigs(
     }
   }
   const out: ProjectConfig[] = []
-  for (const entry of prepared) {
-    const { configPath, cacheKey } = entry
-    const hit = cacheKey === null ? undefined : hits.get(cacheKey)
-    // Stored AFTER validation, so a hit needs none; the key covers every
-    // byte the evaluation could have read.
-    if (hit !== undefined) {
-      out.push(JSON.parse(hit) as ProjectConfig)
-      continue
-    }
-    // A fast key that missed: the closure is stale or the file changed.
-    // Take the slow path for this one config, which re-indexes it.
-    let bytes = entry.bytes
-    let closure = entry.closure
-    let key = cacheKey
-    if (entry.indexed) {
-      bytes = await Bun.file(configPath).bytes()
-      const keyed = await configEvalKey({
-        configPath,
-        bytes,
-        workspaceFingerprint: evalCache!.workspaceFingerprint,
-        ...(hashFile !== undefined ? { hashFile } : {}),
-      })
-      key = keyed?.key ?? null
-      closure = keyed !== null && keyed.indexable ? keyed.closure : undefined
-      const slowHit = key === null ? null : (store!.getConfigEval(key) ?? null)
-      if (slowHit !== null) {
-        out.push(JSON.parse(slowHit) as ProjectConfig)
-        if (closure !== undefined) store!.putConfigClosure?.(configPath, closure)
+  // What the round learned, written ONCE at the end: one transaction per
+  // table where each evaluation was its own (1,000 configs cold: 100 ms of
+  // autocommit inserts against 5, item 615). Written in `finally`, so a
+  // config that fails validation costs the next attempt only its own
+  // evaluation.
+  const evals: Array<readonly [string, string]> = []
+  const learnedClosures: Array<readonly [string, readonly string[]]> = []
+  // One worker for every repeat load in this round, however many there are.
+  const endRound = beginEvalRound()
+  try {
+    for (const entry of prepared) {
+      const { configPath, cacheKey } = entry
+      const hit = cacheKey === null ? undefined : hits.get(cacheKey)
+      // Stored AFTER validation, so a hit needs none; the key covers every
+      // byte the evaluation could have read.
+      if (hit !== undefined) {
+        out.push(JSON.parse(hit) as ProjectConfig)
         continue
       }
-    }
-    // A REPEAT load in this process re-evaluates in a worker, because the
-    // bust above cannot reach the config's import closure — see
-    // config-eval.ts. A FIRST load keeps the in-process import, so the
-    // single `vx run` hot path never pays for a worker.
-    const repeat = loadedConfigs.has(configPath)
-    loadedConfigs.add(configPath)
-    const mod = repeat
-      ? await evaluateConfigFresh(configPath).catch((err: unknown) => {
-          throw unresolvedImportError(err, configPath, 'Project') ?? err
+      // A fast key that missed: the closure is stale or the file changed.
+      // Take the slow path for this one config, which re-indexes it.
+      let bytes = entry.bytes
+      let closure = entry.closure
+      let key = cacheKey
+      if (entry.indexed) {
+        bytes = await Bun.file(configPath).bytes()
+        const keyed = await configEvalKey({
+          configPath,
+          bytes,
+          workspaceFingerprint: evalCache!.workspaceFingerprint,
+          ...slowKeyHash,
         })
-      : await loadDefaultExport(configPath, 'Project', opts?.fresh === true, bytes!)
-    assertDefaultObject(mod, 'Project', configPath)
-    // Validation runs HERE, on whichever object we ended up with, so a
-    // malformed config reports the identical UserError whether it was
-    // evaluated in-process or in a worker.
-    validateProjectConfig(mod as ProjectConfig, configPath)
-    if (key !== null) {
-      evalCache!.store.putConfigEval(key, JSON.stringify(mod))
-      if (closure !== undefined) evalCache!.store.putConfigClosure?.(configPath, closure)
+        key = keyed?.key ?? null
+        closure = keyed !== null && keyed.indexable ? keyed.closure : undefined
+        const slowHit = key === null ? null : (store!.getConfigEval(key) ?? null)
+        if (slowHit !== null) {
+          out.push(JSON.parse(slowHit) as ProjectConfig)
+          if (closure !== undefined) learnedClosures.push([configPath, closure])
+          continue
+        }
+      }
+      // A REPEAT load in this process re-evaluates in a worker, because the
+      // bust above cannot reach the config's import closure — see
+      // config-eval.ts. A FIRST load keeps the in-process import, so the
+      // single `vx run` hot path never pays for a worker.
+      const repeat = loadedConfigs.has(configPath)
+      loadedConfigs.add(configPath)
+      if (repeat) refuseUnprovidedImports(bytes!, configPath, 'Project')
+      const mod = repeat
+        ? await evaluateConfigFresh(configPath).catch((err: unknown) => {
+            throw configLoadError(err, configPath, 'Project') ?? err
+          })
+        : await loadDefaultExport(configPath, 'Project', bytes!)
+      assertDefaultObject(mod, 'Project', configPath)
+      // Validation runs HERE, on whichever object we ended up with, so a
+      // malformed config reports the identical UserError whether it was
+      // evaluated in-process or in a worker.
+      validateProjectConfig(mod as ProjectConfig, configPath)
+      const json = JSON.stringify(mod)
+      if (key !== null) {
+        evals.push([key, json])
+        if (closure !== undefined) learnedClosures.push([configPath, closure])
+      }
+      // A tree of its own, as a hit and the lock hand out. The module object
+      // shares what the config shares: one preset's task in two configs, one
+      // `exec` in two tasks. A `project` hook that edits in place then edited
+      // them all, so a cold run ran `echo P +plug +plug` where the warm run
+      // and `--frozen` ran `echo P +plug`, under another key (item 967). A
+      // config is JSON data (config-schema.ts), so the copy loses nothing.
+      out.push(JSON.parse(json) as ProjectConfig)
+    }
+  } finally {
+    endRound()
+    if (store !== undefined) {
+      if (evals.length > 0) {
+        if (store.putConfigEvals !== undefined) store.putConfigEvals(evals)
+        else for (const [k, json] of evals) store.putConfigEval(k, json)
+      }
+      if (learnedClosures.length > 0 && store.putConfigClosure !== undefined) {
+        if (store.putConfigClosures !== undefined) store.putConfigClosures(learnedClosures)
+        else for (const [p, files] of learnedClosures) store.putConfigClosure(p, files)
+      }
     }
-    out.push(mod as ProjectConfig)
   }
   return out
 }
@@ -219,738 +425,12 @@ export async function loadProjectConfig(
  * a `UserError` on malformed input.
  */
 export async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig | null> {
-  let configPath: string | null = null
-  for (const candidate of WORKSPACE_CONFIG_FILENAMES.map((f) => path.join(root, f))) {
-    if (await Bun.file(candidate).exists()) {
-      configPath = candidate
-      break
-    }
-  }
-  if (!configPath) return null
-  const mod = (await loadDefaultExport(configPath, 'Workspace')) as WorkspaceConfig
-  validateWorkspace(mod, configPath)
-  return mod
-}
-
-function validateWorkspace(config: WorkspaceConfig, configPath: string): void {
-  if (config.concurrency !== undefined) {
-    if (
-      typeof config.concurrency !== 'number' ||
-      !Number.isFinite(config.concurrency) ||
-      config.concurrency < 1 ||
-      !Number.isInteger(config.concurrency)
-    ) {
-      throw new UserError(`${configPath}: \`concurrency\` must be a positive integer`)
-    }
-  }
-  if (config.cacheDir !== undefined && typeof config.cacheDir !== 'string') {
-    throw new UserError(`${configPath}: \`cacheDir\` must be a string`)
-  }
-  if (config.timeout !== undefined) {
-    if (
-      typeof config.timeout !== 'number' ||
-      !Number.isInteger(config.timeout) ||
-      config.timeout <= 0
-    ) {
-      throw new UserError(`${configPath}: \`timeout\` must be a positive integer (milliseconds)`)
-    }
-    assertTimeoutInRange(config.timeout, `${configPath}: \`timeout\``)
-  }
-  if (config.plugins !== undefined) {
-    if (!Array.isArray(config.plugins)) {
-      throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
-    }
-    for (const [i, p] of config.plugins.entries()) {
-      if (p === null || typeof p !== 'object') {
-        throw new UserError(`${configPath}: \`plugins[${i}]\` must be an object`)
-      }
-      const plug = p as {
-        name?: unknown
-        setup?: unknown
-        backend?: unknown
-        cache?: unknown
-        executor?: unknown
-        telemetry?: unknown
-        config?: unknown
-        project?: unknown
-        graph?: unknown
-        key?: unknown
-        schedule?: unknown
-        commands?: unknown
-        teardown?: unknown
-      }
-      if (typeof plug.name !== 'string' || plug.name.length === 0) {
-        throw new UserError(`${configPath}: \`plugins[${i}].name\` must be a non-empty string`)
-      }
-      // The whole-run `backend` seam was REMOVED on 2026-08-23 with vx
-      // cloud: a run always executes in the `vx run` process. Nothing
-      // consults `.backend` any more, so leaving it in `caps` below meant a
-      // plugin declaring ONLY `backend` — a third-party one written against
-      // the old API, say — validated as "contributes a capability" and was
-      // then silently ignored. Refuse it by name and point at the seam that
-      // replaced it; a silent no-op is the failure this validation exists
-      // to prevent.
-      if (plug.backend !== undefined) {
-        throw new UserError(
-          `${configPath}: \`plugins[${i}].backend\` is no longer a capability — the whole-run ` +
-            `backend seam was removed in 2026-08. Use \`executor\` to change where a single ` +
-            `task's command runs (see docs/architecture.md § plugin capabilities).`,
-        )
-      }
-      const caps = [
-        'config',
-        'project',
-        'graph',
-        'key',
-        'schedule',
-        'setup',
-        'cache',
-        'executor',
-        'telemetry',
-        'teardown',
-      ] as const
-      for (const cap of caps) {
-        if (plug[cap] !== undefined && typeof plug[cap] !== 'function') {
-          throw new UserError(`${configPath}: \`plugins[${i}].${cap}\` must be a function`)
-        }
-      }
-      if (plug.commands !== undefined) {
-        if (plug.commands === null || typeof plug.commands !== 'object') {
-          throw new UserError(`${configPath}: \`plugins[${i}].commands\` must be an object`)
-        }
-        for (const [verb, cmd] of Object.entries(plug.commands as Record<string, unknown>)) {
-          const c = cmd as { description?: unknown; run?: unknown } | null
-          if (
-            c === null ||
-            typeof c !== 'object' ||
-            typeof c.run !== 'function' ||
-            typeof c.description !== 'string'
-          ) {
-            throw new UserError(
-              `${configPath}: \`plugins[${i}].commands.${verb}\` must be { description: string, run: function }`,
-            )
-          }
-        }
-      }
-      // A plugin must contribute at least one capability or lifecycle hook
-      // — an empty `{ name }` object is a no-op authoring mistake.
-      if (caps.every((cap) => plug[cap] === undefined) && plug.commands === undefined) {
-        throw new UserError(
-          `${configPath}: \`plugins[${i}]\` must contribute at least one of ${[...caps, 'commands'].join('/')}`,
-        )
-      }
-    }
-  }
-}
-
-/**
- * Runtime validation for the user-authored config. TypeScript checks
- * shape at edit-time, but `vx run` may load configs that were never
- * typechecked (plain .js, or TS with errors ignored). Catch the worst
- * shape problems early with a clear message rather than letting them
- * crash deeper in the orchestrator. Also applied to configs loaded
- * back from `vx-lock.json` (a hand-editable file — same boundary).
- */
-export function validateProjectConfig(config: ProjectConfig, configPath: string): void {
-  const tasks = config.tasks
-  if (tasks === undefined) return
-  if (typeof tasks !== 'object' || tasks === null || Array.isArray(tasks)) {
-    // An ARRAY of task objects reads as valid to `typeof`, and
-    // `Object.entries` then yields a task literally named "0" — a config
-    // that loads, runs nothing the author asked for, and never says why.
-    throw new UserError(`${configPath}: \`tasks\` must be an object keyed by task name`)
-  }
-  for (const [name, task] of Object.entries(tasks)) {
-    const where = `${configPath}: tasks.${name}`
-    if (!task || typeof task !== 'object') {
-      throw new UserError(`${where} must be an object`)
-    }
-    assertKnownFields(task, TASK_FIELDS, where)
-    const exec = (task as { exec?: unknown }).exec
-    const dependsOn = (task as { dependsOn?: unknown }).dependsOn
-    const cache = (task as { cache?: unknown }).cache
-    if (exec !== undefined) {
-      if (typeof exec !== 'object' || exec === null) {
-        throw new UserError(`${where}.exec must be an object with a \`command\` string`)
-      }
-      assertKnownFields(exec, EXEC_FIELDS, `${where}.exec`)
-      const command = (exec as { command?: unknown }).command
-      if (typeof command !== 'string' || command.length === 0) {
-        throw new UserError(`${where}.exec.command must be a non-empty string`)
-      }
-      const timeout = (exec as { timeout?: unknown }).timeout
-      if (timeout !== undefined) {
-        if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout <= 0) {
-          throw new UserError(`${where}.exec.timeout must be a positive integer (milliseconds)`)
-        }
-        assertTimeoutInRange(timeout, `${where}.exec.timeout`)
-      }
-      const retries = (exec as { retries?: unknown }).retries
-      if (retries !== undefined) {
-        if (typeof retries !== 'number' || !Number.isInteger(retries) || retries < 0) {
-          throw new UserError(`${where}.exec.retries must be a non-negative integer`)
-        }
-      }
-      const remote = (exec as { remote?: unknown }).remote
-      if (remote !== undefined && typeof remote !== 'boolean' && remote !== 'only') {
-        throw new UserError(`${where}.exec.remote must be a boolean or 'only' (or omitted)`)
-      }
-      const resources = (exec as { resources?: unknown }).resources
-      if (resources !== undefined) {
-        validateResources(resources, `${where}.exec.resources`)
-      }
-      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)`)
-        }
-        const passThrough = (env as { passThrough?: unknown }).passThrough
-        if (passThrough !== undefined) {
-          // A non-array here reaches `buildIsolatedEnv`'s `for (const name of
-          // passThrough)` — a number throws "not iterable" mid-run, a string
-          // silently char-iterates. Fail loud at load with a config pointer.
-          if (
-            !Array.isArray(passThrough) ||
-            passThrough.some((n) => typeof n !== 'string' || n.length === 0)
-          ) {
-            throw new UserError(
-              `${where}.exec.env.passThrough must be an array of non-empty env var names`,
-            )
-          }
-        }
-        const define = (env as { define?: unknown }).define
-        if (define !== undefined) {
-          if (typeof define !== 'object' || define === null || Array.isArray(define)) {
-            throw new UserError(
-              `${where}.exec.env.define must be an object of name:value string pairs`,
-            )
-          }
-          for (const [k, val] of Object.entries(define as Record<string, unknown>)) {
-            if (typeof val !== 'string') {
-              throw new UserError(`${where}.exec.env.define.${k} must be a string`)
-            }
-          }
-        }
-      }
-      const persistent = (exec as { persistent?: unknown }).persistent
-      if (persistent !== undefined) {
-        if (typeof persistent !== 'object' || persistent === null) {
-          throw new UserError(`${where}.exec.persistent must be an object (or omitted)`)
-        }
-        // The one nested object that had no unknown-key check while every
-        // sibling did — and the failure it let through is the quiet kind:
-        // `readWhen` (typo) leaves `readyWhen` undefined, so the task is
-        // ready the moment it spawns instead of when its server actually
-        // listens, and the dependents that start too early fail in a way
-        // that points at the user's code rather than at their config.
-
-        assertKnownFields(persistent, PERSISTENT_FIELDS, `${where}.exec.persistent`)
-        const readyWhen = (persistent as { readyWhen?: unknown }).readyWhen
-        if (readyWhen !== undefined && typeof readyWhen !== 'string') {
-          throw new UserError(`${where}.exec.persistent.readyWhen must be a string regex`)
-        }
-        if (cache !== undefined) {
-          throw new UserError(
-            `${where}: \`cache\` is not allowed on a persistent task — persistent tasks ` +
-              `don't terminate, so there's no exit to cache`,
-          )
-        }
-        if (retries !== undefined) {
-          throw new UserError(
-            `${where}: \`retries\` is not allowed on a persistent task — persistent tasks ` +
-              `don't terminate, so there's no failed exit to retry`,
-          )
-        }
-      }
-    } else {
-      // Group task: no exec, just dependencies. Must declare something to
-      // depend on, otherwise the task is a literal no-op with nothing to
-      // chain (almost certainly a config mistake).
-      if (dependsOn === undefined) {
-        throw new UserError(
-          `${where}: a task with no \`exec\` must declare \`dependsOn\` ` +
-            `(group tasks exist to chain dependencies)`,
-        )
-      }
-      if (cache !== undefined) {
-        throw new UserError(
-          `${where}: \`cache\` requires \`exec\` — a group task has nothing to cache`,
-        )
-      }
-    }
-    const description = (task as { description?: unknown }).description
-    if (description !== undefined && typeof description !== 'string') {
-      throw new UserError(`${where}.description must be a string`)
-    }
-    if (dependsOn !== undefined) {
-      if (!Array.isArray(dependsOn) || dependsOn.some((s) => typeof s !== 'string')) {
-        throw new UserError(
-          `${where}.dependsOn must be an array of strings ` +
-            `(Turbo/Nx micro-syntax: 'name', '^name', 'pkg#name')`,
-        )
-      }
-    }
-    if (cache !== undefined) {
-      if (typeof cache !== 'object' || cache === null) {
-        throw new UserError(`${where}.cache must be an object when present`)
-      }
-      assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
-      const inputs = (cache as { inputs?: unknown }).inputs
-      const outputs = (cache as { outputs?: unknown }).outputs
-      if (!inputs || typeof inputs !== 'object') {
-        throw new UserError(`${where}.cache.inputs is required when \`cache\` is set`)
-      }
-      assertKnownFields(inputs, CACHE_INPUT_FIELDS, `${where}.cache.inputs`)
-      if (!Array.isArray((inputs as { files?: unknown }).files)) {
-        throw new UserError(`${where}.cache.inputs.files must be an array of glob strings`)
-      }
-      const envList = (inputs as { env?: unknown }).env
-      if (envList !== undefined) {
-        if (
-          !Array.isArray(envList) ||
-          envList.some((s) => typeof s !== 'string' || s.length === 0)
-        ) {
-          throw new UserError(
-            `${where}.cache.inputs.env must be an array of non-empty env var names`,
-          )
-        }
-        for (const name of envList as string[]) {
-          // Reject wildcards explicitly so users don't silently miss
-          // env vars they thought they were tracking. Turbo supports
-          // `VERCEL_*` expansion; vx requires the literal names. If
-          // we add expansion later it'll be additive — until then,
-          // surface the footgun instead of returning '' for the
-          // literal env name `'VERCEL_*'`.
-          if (/[*?[\]]/.test(name)) {
-            throw new UserError(
-              `${where}.cache.inputs.env: wildcards in env names are not supported ` +
-                `(got "${name}") — list explicit env var names instead`,
-            )
-          }
-        }
-      }
-      if (!outputs || typeof outputs !== 'object') {
-        throw new UserError(`${where}.cache.outputs is required when \`cache\` is set`)
-      }
-      assertKnownFields(outputs, CACHE_OUTPUT_FIELDS, `${where}.cache.outputs`)
-      const outFiles = (outputs as { files?: unknown }).files
-      if (!Array.isArray(outFiles)) {
-        throw new UserError(`${where}.cache.outputs.files must be an array of glob strings`)
-      }
-      // Reject zero-length strings and absolute paths up front.
-      // Both reach `resolveOutputs` as undefined behavior; the error
-      // surfaces deep inside the glob resolver with no line pointing
-      // at the user's config. Fail loud at load time.
-      for (const g of outFiles as unknown[]) {
-        if (typeof g !== 'string' || g.length === 0) {
-          throw new UserError(`${where}.cache.outputs.files must be an array of non-empty strings`)
-        }
-        if (g.startsWith('/')) {
-          throw new UserError(
-            `${where}.cache.outputs.files: absolute paths are not allowed (got "${g}") — ` +
-              `outputs must be project-relative globs`,
-          )
-        }
-        if (hasParentSegment(g)) {
-          throw new UserError(
-            `${where}.cache.outputs.files: '..' path segments are not allowed (got "${g}") — ` +
-              `outputs must stay within the project (a glob that escapes the project dir would ` +
-              `let cleanOutputs delete files outside it)`,
-          )
-        }
-        if (g.startsWith('!')) {
-          throw new UserError(
-            `${where}.cache.outputs.files: negation is not supported (got "${g}") — ` +
-              `unlike inputs, output globs are never split on '!', so this is read as a literal ` +
-              `path beginning with '!' and matches nothing. List the outputs you DO produce.`,
-          )
-        }
-      }
-      // Same for inputs.files.
-      for (const g of (inputs as { files: unknown[] }).files) {
-        if (typeof g !== 'string' || g.length === 0) {
-          throw new UserError(`${where}.cache.inputs.files must be an array of non-empty strings`)
-        }
-        if (g.startsWith('/')) {
-          throw new UserError(
-            `${where}.cache.inputs.files: absolute paths are not allowed (got "${g}") — ` +
-              `inputs must be project-relative globs`,
-          )
-        }
-        if (hasParentSegment(g)) {
-          throw new UserError(
-            `${where}.cache.inputs.files: '..' path segments are not allowed (got "${g}") — ` +
-              `inputs must be project-relative (a '..' glob silently matches nothing; ` +
-              `use cache.inputs.workspaceFiles for workspace-root-relative inputs)`,
-          )
-        }
-        assertNotDoubleNegated(g, `${where}.cache.inputs.files`)
-      }
-      // A list of ONLY negations selects nothing at all. `resolveFiles`
-      // builds the file set from the POSITIVE globs and uses the `!` entries
-      // purely to subtract, so with no positive pattern it returns `[]` — the
-      // task folds ZERO file inputs and its key stops moving with its source,
-      // which is a stale hit waiting to happen.
-      //
-      // Every gitignore-trained reader parses `['!**/*.spec.ts']` as
-      // "everything except specs", and Turbo makes exactly this a hard config
-      // error for the same reason. Refusing costs nothing: such a config was
-      // already silently broken, so no working key changes.
-      assertNotNegationOnly((inputs as { files: string[] }).files, `${where}.cache.inputs.files`)
-      // The only CacheInputs field that reached the run unvalidated: a
-      // non-string entry crashes deep in `filterUpstreamHashes` /
-      // `parseDependencySpec` with a raw TypeError naming neither the task
-      // nor the config. Entry SYNTAX is already checked downstream (a
-      // `DependencySpecError` becomes a UserError naming the task) — this
-      // only pins the shape.
-      const taskFilters = (inputs as { tasks?: unknown }).tasks
-      if (taskFilters !== undefined) {
-        if (
-          !Array.isArray(taskFilters) ||
-          taskFilters.some((s) => typeof s !== 'string' || s.length === 0)
-        ) {
-          throw new UserError(
-            `${where}.cache.inputs.tasks must be an array of non-empty strings ` +
-              `(Turbo/Nx micro-syntax: 'name', '^name', 'pkg#name', '*', '^*', '!name')`,
-          )
-        }
-      }
-      for (const field of ['runtime', 'workspaceRuntime'] as const) {
-        const list = (inputs as Record<string, unknown>)[field]
-        if (list !== undefined) {
-          if (!Array.isArray(list) || list.some((s) => typeof s !== 'string' || s.length === 0)) {
-            throw new UserError(
-              `${where}.cache.inputs.${field} must be an array of non-empty shell command strings`,
-            )
-          }
-        }
-      }
-      // workspaceFiles mirror the files validation: non-empty strings,
-      // never absolute (they're workspace-root-relative by definition).
-      const wsInputs = (inputs as { workspaceFiles?: unknown }).workspaceFiles
-      if (wsInputs !== undefined) {
-        validateWorkspaceGlobs(wsInputs, `${where}.cache.inputs.workspaceFiles`, true)
-      }
-      const wsOutputs = (outputs as { workspaceFiles?: unknown }).workspaceFiles
-      if (wsOutputs !== undefined) {
-        validateWorkspaceGlobs(wsOutputs, `${where}.cache.outputs.workspaceFiles`, false)
-      }
-    }
-    const sandbox = (task as { sandbox?: unknown }).sandbox
-    if (sandbox !== undefined) validateSandbox(sandbox, where, exec !== undefined)
-  }
-}
-
-// Known fields per config level, mirroring the interfaces in src/config.ts.
-// Unknown keys are REJECTED rather than silently dropped: a typo in a
-// cache-key field (`workspaceFile`, `task`, `timeoutMs`) is otherwise
-// discarded, so the task hashes as if the field were never written and vx
-// serves a stale artifact — the same reasoning `exec.resources` and
-// `sandbox` already encode. A new field must be added here deliberately.
-const TASK_FIELDS = new Set(['description', 'exec', 'dependsOn', 'cache', 'sandbox'])
-const EXEC_FIELDS = new Set([
-  'command',
-  'env',
-  'timeout',
-  'retries',
-  'resources',
-  'persistent',
-  'remote',
-])
-const PERSISTENT_FIELDS = new Set(['readyWhen'])
-const CACHE_FIELDS = new Set(['inputs', 'outputs'])
-const CACHE_INPUT_FIELDS = new Set([
-  'files',
-  'workspaceFiles',
-  'env',
-  'tasks',
-  'runtime',
-  'workspaceRuntime',
-])
-const CACHE_OUTPUT_FIELDS = new Set(['files', 'workspaceFiles'])
-
-function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: string): void {
-  for (const key of Object.keys(value)) {
-    if (!allowed.has(key)) {
-      throw new UserError(
-        `${where} has unknown field "${key}". Allowed: ${[...allowed].sort().join(', ')}`,
-      )
-    }
-  }
-}
-
-/**
- * True when a glob contains a `..` PATH SEGMENT (`../x`, `a/../b`, `x/..`), which
- * escapes its base dir — `foo..bar` / `a..b` inside a filename are fine. A
- * leading negation marker is stripped first so `!../x` is caught too. Used to
- * keep output globs inside the project and workspace globs inside the workspace
- * root: `cleanOutputs` rm()s resolved output paths before every run, and
- * `Bun.Glob.scan` follows `..` out of its cwd, so a `..` glob is a data-loss
- * vector (delete files outside the project / above the repo root).
- */
-/**
- * A millisecond delay past `MAX_TIMEOUT_MS` does not mean "effectively never" —
- * `setTimeout` silently reduces it to 1 ms, so the task is killed the instant it
- * spawns and reported `failed`. That is the exact inverse of the declaration,
- * and the only clue is a `TimeoutOverflowWarning` on stderr.
- *
- * Refused rather than clamped, because this is a value the user WROTE and reads
- * back: silently substituting ~24.8 days for the 317 years they asked for would
- * trade one surprise for a quieter one. Costs nothing — such a config never
- * worked, it killed the task in milliseconds, so refusing reports a state that
- * already existed.
- */
-function assertTimeoutInRange(ms: number, where: string): void {
-  if (ms <= MAX_TIMEOUT_MS) return
-  throw new UserError(
-    `${where}: ${ms} ms exceeds the maximum timer delay (${MAX_TIMEOUT_MS} ms, ~24.8 days). ` +
-      `Timers larger than this do NOT mean "no limit" — the platform reduces them to 1 ms, so ` +
-      `the task would be killed the moment it starts. Omit \`timeout\` for no limit.`,
-  )
-}
-
-function hasParentSegment(glob: string): boolean {
-  const g = glob.startsWith('!') ? glob.slice(1) : glob
-  return g.split('/').some((seg) => seg === '..')
-}
-
-/**
- * Refuse a non-empty glob list made up ENTIRELY of negations.
- *
- * The resolvers build their file set from the POSITIVE globs and use `!`
- * entries only to subtract, so with no positive pattern they return `[]` —
- * the task folds zero file inputs and its cache key stops moving with its
- * source. That is a stale hit, and it is silent.
- *
- * Refusing is free: such a config was ALREADY selecting nothing, so no
- * working task's key changes and no CACHE_VERSION bump is owed.
- */
-/**
- * `!!x` INVERTS the input set instead of double-negating it.
- *
- * The resolver strips ONE `!` and hands the remainder to `new Bun.Glob()` —
- * which applies its OWN leading-`!` negation. So `!!vendor/**` becomes the
- * exclude glob `Glob('!vendor/**')`, and that matches every path EXCEPT
- * vendor's. Everything else is therefore excluded and the task folds ONLY
- * `vendor/**`: its own source drops out of the cache key entirely, which is a
- * permanent stale hit.
- *
- * Neither neighbouring guard catches it — `assertNotNegationOnly` sees the
- * positive glob and is satisfied, and `hasParentSegment` strips one `!` before
- * splitting so `!!../x` shows no `..` segment.
- *
- * Refused rather than reinterpreted: `!!` has no coherent meaning here.
- * Negation in vx is subtraction from what a positive glob matched, not
- * gitignore's ordered re-inclusion, so there is nothing for a second `!` to
- * undo. Costs nothing to refuse — such a config already folds the wrong set,
- * so no working cache key changes.
- */
-function assertNotDoubleNegated(glob: string, where: string): void {
-  if (!glob.startsWith('!!')) return
-  const inner = glob.slice(2)
-  throw new UserError(
-    `${where}: '!!' is not a double negation (got "${glob}") — it INVERTS the set. ` +
-      `One '!' is stripped and the remainder is compiled as a glob, which applies its own ` +
-      `leading-'!' negation, so this excludes everything EXCEPT ${JSON.stringify(inner)} and ` +
-      `the task folds only that. Use ${JSON.stringify(`!${inner}`)} to subtract it, or ` +
-      `${JSON.stringify(inner)} to include it.`,
-  )
-}
-
-function assertNotNegationOnly(globs: readonly string[], where: string): void {
-  if (globs.length === 0) return
-  if (globs.some((g) => !g.startsWith('!'))) return
-  throw new UserError(
-    `${where}: every entry is a negation, which selects NOTHING (got ${JSON.stringify(globs)}) — ` +
-      `negations only subtract from the files a positive glob already matched, so this task ` +
-      `would fold zero file inputs and its cache key would stop tracking its source. ` +
-      `Add the positive glob you meant, e.g. ['**/*', ${JSON.stringify(globs[0])}].`,
-  )
-}
-
-/**
- * `negation: false` for OUTPUT globs — `resolveOutputs` /
- * `resolveWorkspaceOutputs` never split on `!`, so such an entry is read as a
- * literal path starting with `!` and matches nothing.
- */
-function validateWorkspaceGlobs(v: unknown, where: string, negation: boolean): void {
-  if (!Array.isArray(v)) {
-    throw new UserError(`${where} must be an array of glob strings`)
-  }
-  for (const g of v as unknown[]) {
-    if (typeof g !== 'string' || g.length === 0) {
-      throw new UserError(`${where} must be an array of non-empty strings`)
-    }
-    if (g.startsWith('/') || g.startsWith('!/')) {
-      throw new UserError(
-        `${where}: absolute paths are not allowed (got "${g}") — ` +
-          `entries are workspace-root-relative globs`,
-      )
-    }
-    if (hasParentSegment(g)) {
-      throw new UserError(
-        `${where}: '..' path segments are not allowed (got "${g}") — ` +
-          `entries are workspace-root-relative and must stay within the workspace root`,
-      )
-    }
-    if (!negation && g.startsWith('!')) {
-      throw new UserError(
-        `${where}: negation is not supported (got "${g}") — ` +
-          `unlike inputs, output globs are never split on '!', so this is read as a literal ` +
-          `path beginning with '!' and matches nothing. List the outputs you DO produce.`,
-      )
-    }
-    if (negation) assertNotDoubleNegated(g, where)
-  }
-  if (negation) assertNotNegationOnly(v as string[], where)
-}
-
-const SANDBOX_PATH_FIELDS = ['allowRead', 'allowWrite'] as const
-const SANDBOX_BOOL_FIELDS = [
-  'allowGitConfig',
-  'allowPty',
-  'enableWeakerNestedSandbox',
-  'enableWeakerNetworkIsolation',
-] as const
-const SANDBOX_NETWORK_PATH_FIELDS = [
-  'allowedDomains',
-  'deniedDomains',
-  'allowUnixSockets',
-  'allowMachLookup',
-] as const
-const SANDBOX_NETWORK_BOOL_FIELDS = ['allowAllUnixSockets', 'allowLocalBinding'] as const
-const SANDBOX_FIELDS = new Set<string>([
-  ...SANDBOX_PATH_FIELDS,
-  ...SANDBOX_BOOL_FIELDS,
-  'network',
-  'ignoreViolations',
-])
-const SANDBOX_NETWORK_FIELDS = new Set<string>([
-  ...SANDBOX_NETWORK_PATH_FIELDS,
-  ...SANDBOX_NETWORK_BOOL_FIELDS,
-])
-
-/**
- * Validate a `sandbox: {...}` block. The field set mirrors the user-
- * facing surface of SandboxConfig in src/config.ts; this is the only
- * place we enforce shape at runtime (TS users get compile-time checks
- * already).
- */
-function validateSandbox(sandbox: unknown, where: string, hasExec: boolean): void {
-  if (typeof sandbox !== 'object' || sandbox === null || Array.isArray(sandbox)) {
-    throw new UserError(
-      `${where}.sandbox must be an object (e.g. \`{}\` for the baseline, or ` +
-        `\`{ allowRead: [...], network: true }\`)`,
-    )
-  }
-  if (!hasExec) {
-    throw new UserError(`${where}.sandbox requires \`exec\` — a group task has nothing to wrap`)
-  }
-  for (const key of Object.keys(sandbox as object)) {
-    if (!SANDBOX_FIELDS.has(key)) {
-      throw new UserError(
-        `${where}.sandbox.${key} is not a known field. Allowed: ` +
-          `${[...SANDBOX_FIELDS].sort().join(', ')}`,
-      )
-    }
-  }
-  const obj = sandbox as Record<string, unknown>
-  for (const field of SANDBOX_PATH_FIELDS) {
-    if (obj[field] === undefined) continue
-    assertPathArray(obj[field], `${where}.sandbox.${field}`)
-  }
-  for (const field of SANDBOX_BOOL_FIELDS) {
-    if (obj[field] !== undefined && typeof obj[field] !== 'boolean') {
-      throw new UserError(`${where}.sandbox.${field} must be a boolean`)
-    }
-  }
-  const network = obj.network
-  if (network !== undefined && typeof network !== 'boolean') {
-    if (typeof network !== 'object' || network === null || Array.isArray(network)) {
-      throw new UserError(
-        `${where}.sandbox.network must be a boolean or an object (allowedDomains, ` +
-          `deniedDomains, allowUnixSockets, allowAllUnixSockets, allowLocalBinding, allowMachLookup)`,
-      )
-    }
-    for (const key of Object.keys(network)) {
-      if (!SANDBOX_NETWORK_FIELDS.has(key)) {
-        throw new UserError(
-          `${where}.sandbox.network.${key} is not a known field. Allowed: ` +
-            `${[...SANDBOX_NETWORK_FIELDS].sort().join(', ')}`,
-        )
-      }
-    }
-    const netObj = network as Record<string, unknown>
-    for (const field of SANDBOX_NETWORK_PATH_FIELDS) {
-      if (netObj[field] === undefined) continue
-      assertStringArray(netObj[field], `${where}.sandbox.network.${field}`)
-    }
-    for (const field of SANDBOX_NETWORK_BOOL_FIELDS) {
-      if (netObj[field] !== undefined && typeof netObj[field] !== 'boolean') {
-        throw new UserError(`${where}.sandbox.network.${field} must be a boolean`)
-      }
-    }
-  }
-  const ignoreViolations = obj.ignoreViolations
-  if (ignoreViolations !== undefined) {
-    if (
-      typeof ignoreViolations !== 'object' ||
-      ignoreViolations === null ||
-      Array.isArray(ignoreViolations)
-    ) {
-      throw new UserError(
-        `${where}.sandbox.ignoreViolations must be a record mapping command patterns to arrays of paths`,
-      )
-    }
-    for (const [k, v] of Object.entries(ignoreViolations)) {
-      assertStringArray(v, `${where}.sandbox.ignoreViolations[${JSON.stringify(k)}]`)
-    }
-  }
-}
-
-const RESOURCES_FIELDS = new Set(['cpus', 'memory', 'image'])
-
-function validateResources(resources: unknown, where: string): void {
-  if (typeof resources !== 'object' || resources === null || Array.isArray(resources)) {
-    throw new UserError(`${where} must be an object (e.g. \`{ cpus: 2, memory: 2048 }\`)`)
-  }
-  for (const key of Object.keys(resources as object)) {
-    if (!RESOURCES_FIELDS.has(key)) {
-      throw new UserError(
-        `${where} has unknown field "${key}". Allowed: ${[...RESOURCES_FIELDS].sort().join(', ')}`,
-      )
-    }
-  }
-  const { cpus, memory, image } = resources as {
-    cpus?: unknown
-    memory?: unknown
-    image?: unknown
-  }
-  if (cpus !== undefined && (typeof cpus !== 'number' || !Number.isFinite(cpus) || cpus < 0)) {
-    throw new UserError(`${where}.cpus must be a non-negative number of CPU cores`)
-  }
-  if (
-    memory !== undefined &&
-    (typeof memory !== 'number' || !Number.isInteger(memory) || memory < 0)
-  ) {
-    throw new UserError(`${where}.memory must be a non-negative integer number of megabytes`)
-  }
-  if (image !== undefined && (typeof image !== 'string' || image === '')) {
-    throw new UserError(`${where}.image must be a non-empty string (or omitted)`)
-  }
-}
-
-function assertStringArray(v: unknown, where: string): void {
-  if (!Array.isArray(v) || v.some((s) => typeof s !== 'string' || s.length === 0)) {
-    throw new UserError(`${where} must be an array of non-empty strings`)
-  }
-}
-
-function assertPathArray(v: unknown, where: string): void {
-  assertStringArray(v, where)
-  if ((v as string[]).some((s) => /[*?[\]]/.test(s))) {
-    throw new UserError(
-      `${where} entries must be path prefixes (no globs — bwrap on Linux can't enforce them)`,
-    )
+  for (const configPath of WORKSPACE_CONFIG_FILENAMES.map((f) => path.join(root, f))) {
+    const bytes = await readOnce(undefined, configPath)
+    if (bytes === null) continue
+    const mod = (await loadDefaultExport(configPath, 'Workspace', bytes)) as WorkspaceConfig
+    validateWorkspace(mod, configPath)
+    return mod
   }
+  return null
 }