@vzn/vx 0.0.369 → 0.0.371

package/package.json

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

package/src/cache/cache.ts

@@ -223,7 +223,16 @@ export function noteSchemaReset(cache: Cache, warn: (message: string) => void):
 //        the last entry's bytes on disk under a green run (item 886). A row
 //        is current only with the inode and ctime recorded after the save
 //        or restore that wrote it. The cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v28'
+//   v29: entries.stdout moved to entry_stdout. SQLite rewrites a whole
+//        record on UPDATE, so the run-end `accessed_at` bump rewrote each
+//        hit's stored stdout (up to 16 MB) with its overflow pages: 200
+//        hits of 1 MB cost the close 125-150 ms. The cache KEY is
+//        unchanged.
+export const SCHEMA_VERSION = 'v29'
+
+/** An entry row with its stdout, which lives apart (v29); none stored reads as ''. */
+const SELECT_ENTRY =
+  "SELECT e.*, COALESCE(s.stdout, '') AS stdout FROM entries e LEFT JOIN entry_stdout s ON s.hash = e.hash"
 
 /** A schema version's number (`v28` → 28); one that is not `v<n>` is older than any. */
 function schemaOrdinal(version: string): number {
@@ -439,6 +448,8 @@ export class Cache implements CacheLayer {
   private readonly insertEntry: ReturnType<Database['prepare']>
   private readonly deleteEntryRow: ReturnType<Database['prepare']>
   private readonly selectEntry: ReturnType<Database['prepare']>
+  private readonly upsertStdout: ReturnType<Database['prepare']>
+  private readonly deleteStdout: ReturnType<Database['prepare']>
   private readonly entryExists: ReturnType<Database['prepare']>
   private readonly bumpAccessed: ReturnType<Database['prepare']>
   private readonly touched = new Set<string>()
@@ -675,7 +686,7 @@ export class Cache implements CacheLayer {
             }
             if (found === SCHEMA_VERSION) return null
             this.db.exec(
-              'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS blob_sizes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals; DROP TABLE IF EXISTS config_closures; DROP TABLE IF EXISTS output_dirs;',
+              'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS blob_sizes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals; DROP TABLE IF EXISTS config_closures; DROP TABLE IF EXISTS output_dirs; DROP TABLE IF EXISTS entry_stdout;',
             )
             this.db
               .prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'")
@@ -697,10 +708,9 @@ export class Cache implements CacheLayer {
 
     this.deleteEntryRow = this.db.prepare('DELETE FROM entries WHERE hash = ?')
     this.insertEntry = this.db.prepare(`
-      INSERT INTO entries(hash, project, task, command, exit_code, duration_ms, size_bytes, stdout, created_at, accessed_at, cpu_ms, peak_rss_bytes)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO entries(hash, project, task, command, exit_code, duration_ms, size_bytes, created_at, accessed_at, cpu_ms, peak_rss_bytes)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(hash) DO UPDATE SET
-        stdout         = excluded.stdout,
         project        = excluded.project,
         task           = excluded.task,
         command        = excluded.command,
@@ -711,12 +721,15 @@ export class Cache implements CacheLayer {
         cpu_ms         = excluded.cpu_ms,
         peak_rss_bytes = excluded.peak_rss_bytes
     `)
-    this.selectEntry = this.db.prepare('SELECT * FROM entries WHERE hash = ?')
-    // `has` asks only whether the row is there: the whole row, stdout
-    // included, was built and dropped once per task of a `--dry` plan. A
+    this.upsertStdout = this.db.prepare(
+      'INSERT INTO entry_stdout(hash, stdout) VALUES (?, ?) ON CONFLICT(hash) DO UPDATE SET stdout = excluded.stdout',
+    )
+    this.deleteStdout = this.db.prepare('DELETE FROM entry_stdout WHERE hash = ?')
+    this.selectEntry = this.db.prepare(`${SELECT_ENTRY} WHERE e.hash = ?`)
+    // `has` asks only whether the row is there, with no stdout joined. A
     // column off the index, so the table row is still read and a corrupt
     // table refuses here as it does on `get` (`SELECT 1` answers from the
-    // index alone); stdout's overflow pages are not.
+    // index alone).
     this.entryExists = this.db.prepare('SELECT exit_code FROM entries WHERE hash = ?')
     this.bumpAccessed = this.db.prepare('UPDATE entries SET accessed_at = ? WHERE hash = ?')
     // INSERT OR IGNORE: re-saving the same hash (idempotent ingest /
@@ -961,7 +974,7 @@ export class Cache implements CacheLayer {
       const placeholders = chunk.map(() => '?').join(',')
       rows.push(
         ...(this.db
-          .query(`SELECT * FROM entries WHERE hash IN (${placeholders})`)
+          .query(`${SELECT_ENTRY} WHERE e.hash IN (${placeholders})`)
           .all(...(chunk as readonly SQLQueryBindings[])) as EntryRow[]),
       )
     }
@@ -1580,6 +1593,8 @@ export class Cache implements CacheLayer {
     // (not the per-run path) so a warm all-cache-hit run — which never
     // saves — writes none of them.
     const insertEntry = this.insertEntry
+    const upsertStdout = this.upsertStdout
+    const deleteStdout = this.deleteStdout
     const outputs = this.outputs
     const insertEntryInput = this.insertEntryInput
     const inputComponents = meta.inputComponents
@@ -1629,7 +1644,6 @@ export class Cache implements CacheLayer {
         0,
         meta.durationMs,
         totalBytes,
-        stdoutText,
         now,
         now,
         // From the artifact, on both paths: a save indexes what it just
@@ -1637,6 +1651,8 @@ export class Cache implements CacheLayer {
         scanned.exec?.cpuMs ?? null,
         scanned.exec?.peakRssBytes ?? null,
       )
+      if (stdoutText === '') deleteStdout.run(hash)
+      else upsertStdout.run(hash, stdoutText)
       outputs.replaceFileRows(hash, outputFileRows)
       // INSERT OR IGNORE: identical inputs derive this same hash, so a
       // re-save's rows are identical — keep the first set, skip the rest.

package/src/cache/schema.ts

@@ -18,10 +18,8 @@ export function createTables(db: Database): void {
   `)
 
   db.exec(`
-    -- The queryable index: command, exit_code, duration, size,
-    -- timestamps, and stdout, which the <hash>.tar.zst artifact also
-    -- carries so it survives a remote round trip; a local hit
-    -- replays it from here.
+    -- The queryable index: command, exit_code, duration, size and
+    -- timestamps; stdout in entry_stdout below.
     CREATE TABLE IF NOT EXISTS entries (
       hash         TEXT PRIMARY KEY,
       project      TEXT NOT NULL,
@@ -30,13 +28,21 @@ export function createTables(db: Database): void {
       exit_code    INTEGER NOT NULL,
       duration_ms  INTEGER NOT NULL,
       size_bytes   INTEGER NOT NULL,
-      stdout       TEXT NOT NULL DEFAULT '',
       created_at   INTEGER NOT NULL,
       accessed_at  INTEGER NOT NULL,
       -- v26: the producing execution's usage, from the artifact's sidecar.
       cpu_ms         INTEGER,
       peak_rss_bytes INTEGER
     );
+    -- v29: an entry's stdout, which the <hash>.tar.zst artifact also
+    -- carries so it survives a remote round trip; a local hit replays it
+    -- from here. Its own table: an UPDATE rewrites a whole record, and the
+    -- accessed_at bump rewrote up to 16 MB a hit. No row: empty stdout.
+    CREATE TABLE IF NOT EXISTS entry_stdout (
+      hash   TEXT PRIMARY KEY,
+      stdout TEXT NOT NULL,
+      FOREIGN KEY (hash) REFERENCES entries(hash) ON DELETE CASCADE
+    );
     CREATE TABLE IF NOT EXISTS runs (
       id                  INTEGER PRIMARY KEY AUTOINCREMENT,
       -- '' when the outcome derived no cache key (skipped / persistent).

package/src/cli/select.ts

@@ -26,7 +26,12 @@ import type { ProjectConfig } from '../config.js'
 import type { ProjectEntry } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
 import { maskedLine, nearest, UserError } from '../util/index.js'
-import { claimedAffected, fingerprintClaims, gitOfDiscovery } from '../orchestrator/index.js'
+import {
+  claimedAffected,
+  fingerprintClaims,
+  gitOfDiscovery,
+  keepDiscoveryGraph,
+} from '../orchestrator/index.js'
 import {
   type CliLoadOptions,
   discoverCliProjects,
@@ -251,6 +256,9 @@ export async function resolveFilters(
     }
   }
   const graph = buildPackageGraph(projects, edges)
+  // The graph a run reusing this discovery builds is this one when no task
+  // edge went into it.
+  if (edges === undefined) keepDiscoveryGraph(projects, graph)
 
   // Resolve every `[<since>]` filter against git before the pure
   // applyFilters pass runs. One spawn per distinct ref — usually

package/src/exec/sandbox-runtime.ts

@@ -88,6 +88,7 @@ import {
   srtDefaultWritePaths,
 } from './sandbox-deny-scan.js'
 import {
+  hiddenReadsOutside,
   parseStraceViolations,
   refusedConnections,
   refusedWrites,
@@ -1820,6 +1821,16 @@ async function runSandboxedOnce(
     })
   }
 
+  if (exitCode !== 0) {
+    const hidden = hiddenReadsOutside(recorded, {
+      within: args.reportWithin,
+      linked: args.reportLinked,
+      config: args.config,
+      skip: [taskTmpRoot()],
+    })
+    if (hidden.length > 0) violations.push(hiddenReadsHint(hidden, args.reportWithin))
+  }
+
   try {
     SandboxManager.cleanupAfterCommand()
   } catch {
@@ -1867,6 +1878,19 @@ function outsideWritesHint(paths: readonly string[]): SandboxViolation {
   }
 }
 
+function hiddenReadsHint(paths: readonly string[], within: string): SandboxViolation {
+  const shown = paths.slice(0, 5).join(', ')
+  const more = paths.length > 5 ? ` and ${paths.length - 5} more` : ''
+  return {
+    timestamp: new Date(),
+    hint: true,
+    line:
+      `vx: the sandbox hid paths outside the project that exist on this machine, which are ` +
+      `not reported as violations: ${shown}${more}. If the task reads one, grant it, e.g. ` +
+      `\`allow: { read: ['${path.relative(toRealPath(within), paths[0]!)}'] }\`.`,
+  }
+}
+
 /**
  * Is `dir` inside a path the sandbox granted for reading? bwrap binds and
  * seatbelt rules are both prefix-based, so a grant covers the subtree.

package/src/exec/sandbox-violations.ts

@@ -4,6 +4,7 @@
 // task's owner can act on — inside the project, minus the loopback denial
 // no grant can avoid, minus what the task chose to ignore.
 
+import { statSync } from 'node:fs'
 import path from 'node:path'
 import { absolutize, atOrUnder, isUnderAny, localBindingOn, toRealPath } from './sandbox-paths.js'
 import { bindableReads } from './sandbox-binds.js'
@@ -500,6 +501,44 @@ export function refusedWritesOutside(
   return [...paths]
 }
 
+/**
+ * The paths outside the project a read was denied that exist on this
+ * machine, files first: the reads `reportableViolations` drops at the
+ * wall. A task that failed on one said only what its tool says for a
+ * missing file — `tsc` extending a root `tsconfig.base.json` read "File
+ * not found" — and nothing named the sandbox (2026-10-02). Never a
+ * violation — a failed task's hint (`runSandboxed`). What a process walks
+ * through to reach its cwd (the project's ancestors) and what `skip` names
+ * are left out, as is a path that does not exist on the host: that miss
+ * is the tool's own.
+ */
+export function hiddenReadsOutside(
+  violations: readonly SandboxViolation[],
+  opts: {
+    within: string
+    linked?: readonly string[]
+    config: ResolvedSandboxConfig
+    skip: readonly string[]
+  },
+): string[] {
+  const reported = reportedWithin(opts.within, opts.linked ?? [])
+  const home = toRealPath(opts.within)
+  const skip = opts.skip.map(toRealPath)
+  const found = new Map<string, boolean>()
+  for (const v of filterIgnored(describe(violations), opts.config.ignore)) {
+    const p = v.path
+    if (p === undefined || v.hint === true || !v.ignorable?.includes('read') || reported(v))
+      continue
+    if (found.has(p) || atOrUnder(home, p) || skip.some((s) => atOrUnder(p, s))) continue
+    try {
+      found.set(p, statSync(p).isDirectory())
+    } catch {
+      // Not on the host either: the tool's own miss.
+    }
+  }
+  return [...found].sort((a, b) => Number(a[1]) - Number(b[1])).map(([p]) => p)
+}
+
 /** Every record described: a seatbelt one parsed, a Linux one as produced. */
 function describe(violations: readonly SandboxViolation[]): SandboxViolation[] {
   return violations.map((v) =>

package/src/orchestrator/index.ts

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

package/src/orchestrator/prepare.ts

@@ -57,6 +57,7 @@ import {
 import {
   discoverProjects,
   gitOfDiscovery,
+  graphOfDiscovery,
   loadProjects,
   loadWorkspacePlugins,
   type LoadedProjects,
@@ -223,7 +224,9 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // those configs are evaluated. Side effect, deliberate and
   // Turbo-like: a broken config in an unrelated package no longer
   // fails a scoped run — it surfaces when that package enters scope.
-  const packageGraph = buildPackageGraph(projectMetas)
+  const packageGraph =
+    (reused !== undefined ? graphOfDiscovery(reused.projects) : undefined) ??
+    buildPackageGraph(projectMetas)
   // Seeds: explicit scope, plus anchored pkg#task targets (which bypass
   // scope by design). With no explicit scope, bare task names fan out
   // across the whole workspace — but when EVERY spec is anchored, the

package/src/orchestrator/projects.ts

@@ -67,6 +67,21 @@ export function gitOfDiscovery(projects: readonly ProjectMeta[]): LazyGitEnumera
   return discoveredGit.get(projects)
 }
 
+/**
+ * The package graph a selection pass built over a discovery, by that
+ * discovery's array, when it folded no task edge in: the graph a run that
+ * reuses the discovery (`RunOptions.discovered`) would build again.
+ */
+const discoveredGraph = new WeakMap<readonly ProjectMeta[], PackageGraph>()
+
+export function graphOfDiscovery(projects: readonly ProjectMeta[]): PackageGraph | undefined {
+  return discoveredGraph.get(projects)
+}
+
+export function keepDiscoveryGraph(projects: readonly ProjectMeta[], graph: PackageGraph): void {
+  discoveredGraph.set(projects, graph)
+}
+
 /**
  * The workspace's projects: core's discovery, then the plugin `discover`
  * stage. With no plugin declaring it, `listProjects` alone.

package/src/orchestrator/run.ts

@@ -544,7 +544,21 @@ async function runOnBus(
   // (`signals.ts`); the handlers are removed in the finally below so
   // repeated run() calls (test suites) never stack listeners.
   const liveChildren = new Set<ReturnType<typeof Bun.spawn>>()
-  const persistentRegistry = new Map<string, ReturnType<typeof Bun.spawn>>()
+  // A server that ends on its own while the graph still runs is said at
+  // once: its dependants were failing against it, and the end of the run
+  // was the first word of it (C-69). Not once the graph is done (the end
+  // of the run and the keep-alive wait say it) nor under a stop.
+  let graphDone = false
+  const persistentRegistry = new (class extends Map<string, ReturnType<typeof Bun.spawn>> {
+    override set(id: string, child: ReturnType<typeof Bun.spawn>): this {
+      super.set(id, child)
+      void child.exited.then((code) => {
+        if (code !== 0 && !graphDone && !stopRun.signal.aborted)
+          log.status(`vx: ${id} exited with code ${code} while the run went on`)
+      })
+      return this
+    }
+  })()
   // One stop for the run: an embedder's `RunOptions.signal` and a process
   // signal both abort it. The scheduler stops dispatching (it reads the
   // signal), the children are torn down, and run() returns through its own
@@ -951,6 +965,7 @@ async function runOnBus(
       // Empty when the short-circuit didn't fire → byte-identical.
       restoreTier: shortCircuit.restoreTier,
     })
+    graphDone = true
 
     // Which persistent children outlive the graph, and the bounded SIGTERM
     // of the rest, before the summary prints. Scoped to the real CLI

package/src/workspace/affected.ts

@@ -125,8 +125,11 @@ export interface FingerprintClaims {
 export async function affectedProjects(args: AffectedArgs): Promise<Set<string>> {
   // Turbo's CI spelling, `[origin/main...HEAD]`, is the base alone here:
   // vx already diffs from the merge base (three dots' meaning), and the
-  // working tree it diffs to holds HEAD (D-117). Any other range is refused.
-  const since = /^(.+)\.\.\.HEAD$/.exec(args.since)?.[1] ?? args.since
+  // working tree it diffs to holds HEAD (D-117). Its two-dot `[A..HEAD]`
+  // diffs from A itself (G-145). Any other range is refused.
+  const headRange = /^(.+?)(\.{2,3})HEAD$/s.exec(args.since)
+  const since = headRange?.[1] ?? args.since
+  const fromMergeBase = headRange?.[2] !== '..'
   // The base reaches git as an argument, never through a shell, so `$(…)`
   // is opaque — but an option-like value is not: `--output=<path>` is a
   // real `git diff` option and an arbitrary file write. This is a security
@@ -155,8 +158,9 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
   // CI `--affected`), and hides your own edit when the base later landed
   // byte-identical content. Turbo and Nx both diff from the merge base;
   // when there is none (unrelated histories, a detached probe) the ref
-  // itself is the base, as before.
-  const base = await mergeBase(args.workspaceRoot, since)
+  // itself is the base, as before. Turbo's two-dot range `A..HEAD` is the
+  // one form that diffs from A itself.
+  const base = fromMergeBase ? await mergeBase(args.workspaceRoot, since) : since
 
   const [diffed, untracked] = await Promise.all([
     // `--no-renames` is crucial for project-affected detection: with

package/src/workspace/config-eval.ts

@@ -109,6 +109,7 @@ self.onmessage = async (e) => {
   const own = (o) => new Map(Reflect.ownKeys(o).map((k) => [k, Object.getOwnPropertyDescriptor(o, k)]))
   const before = watched?.map(([, o]) => own(o))
   const envBefore = watched ? { ...live } : null
+  const cwdBefore = watched ? globalThis.process.cwd() : null
   const same = (a, b) =>
     a !== undefined && b !== undefined && a.value === b.value && a.get === b.get && a.set === b.set &&
     a.writable === b.writable && a.enumerable === b.enumerable && a.configurable === b.configurable
@@ -122,6 +123,7 @@ self.onmessage = async (e) => {
     })
     for (const k of new Set([...Object.keys(envBefore), ...Object.keys(live)]))
       if (envBefore[k] !== live[k]) out.push('process.env.' + k)
+    if (globalThis.process.cwd() !== cwdBefore) out.push('process.cwd (a chdir)')
     return out
   }
   try {
@@ -137,6 +139,7 @@ self.onmessage = async (e) => {
       ok: true,
       nonJson,
       json: isObject && nonJson.length === 0 ? JSON.stringify(mod) : null,
+      fn: typeof mod === 'function',
       changed: changed(),
     })
   } catch (err) {
@@ -156,12 +159,16 @@ self.onmessage = async (e) => {
 }
 `
 
+const FUNCTION_EXPORT = (): void => {}
+
 const WORKER_URL = `data:text/javascript,${encodeURIComponent(WORKER_SRC)}`
 
 interface WorkerReply {
   id: number
   ok: boolean
   json: string | null
+  /** The default export is a function, which JSON cannot carry back. */
+  fn?: boolean
   nonJson: NonJsonValue[]
   name: string
   message: string
@@ -325,7 +332,10 @@ export async function evaluateConfigFresh(configPath: string): Promise<unknown>
     })
     const [nonJson] = reply.nonJson
     if (nonJson !== undefined) throw new UserError(nonJsonMessage(configPath, nonJson))
-    return reply.json === null ? null : (JSON.parse(reply.json) as unknown)
+    // A function stands in for the one the config exported, so the caller's
+    // refusal names it as the in-process load's does.
+    if (reply.json === null) return reply.fn === true ? FUNCTION_EXPORT : null
+    return JSON.parse(reply.json) as unknown
   } finally {
     // In the `finally`, not after the await: a REJECTED evaluation — a config
     // with a typo, the common case while editing — would otherwise skip the

package/src/workspace/migrate-scripts.ts

@@ -738,6 +738,24 @@ export function migrateScripts(
       return !LIFECYCLE.test(n) && (base === undefined || !(base in scripts))
     })
   }
+  // Why a root mapped nothing: `eslint .` beside a member's `lint` runs
+  // nothing of the workspace, and the note said it did.
+  const rootLeftOut = (): string => {
+    if (rootMeta === undefined) return 'run the workspace'
+    const scripts = scriptsOf(rootMeta)
+    const named = Object.keys(scripts).filter(
+      (n) => typeof scripts[n] === 'string' && scripts[n] !== '' && !LIFECYCLE.test(n),
+    )
+    const runs = runningMembers(
+      scripts,
+      rootMeta.dir,
+      metas.filter((m) => m !== root).map((m) => m.dir),
+    )
+    const shared = named.filter((n) => memberTasks.has(n) && !runs.has(n))
+    if (shared.length === 0) return 'run the workspace'
+    const list = `${shared.slice(0, 8).join(', ')}${shared.length > 8 ? ', …' : ''}`
+    return `${shared.length < named.length ? 'run the workspace or ' : ''}share a member's task name (${list})`
+  }
   const rootName =
     root?.name ??
     (outsideRuns
@@ -768,7 +786,7 @@ export function migrateScripts(
     // A nameless root's vx.config is skipped (vx names projects by their
     // manifest's name), so the hand-written one needs a name first (vuejs/core).
     notes.push(
-      `${rootName} (the workspace root) not mapped: its scripts run the workspace; declare its own tasks in its vx.config by hand` +
+      `${rootName} (the workspace root) not mapped: its scripts ${rootLeftOut()}; declare its own tasks in its vx.config by hand` +
         (rootName === 'package.json' ? ', after giving its package.json a "name"' : ''),
     )
   }

package/src/workspace/project-loader.ts

@@ -37,12 +37,21 @@ export const WORKSPACE_CONFIG_FILENAMES = [
   'vx.workspace.cjs',
 ]
 
+/** What a function default export is told; the playground says the same. */
+const EXPORTED_A_FUNCTION =
+  'it exports a function, and vx reads the object itself — export what the function returns'
+
 /** Project configs already loaded in this process, by absolute path. */
 const loadedConfigs = new Set<string>()
 
 function assertDefaultObject(mod: unknown, kind: string, configPath: string): void {
   if (!mod || typeof mod !== 'object') {
-    throw new UserError(`${kind} config at ${configPath} did not export a default object`)
+    // Vite's `defineConfig(() => ({ … }))` shape: vx reads the object, and
+    // the bare refusal did not say what was there instead (D-110).
+    throw new UserError(
+      `${kind} config at ${configPath} did not export a default object` +
+        (typeof mod === 'function' ? `: ${EXPORTED_A_FUNCTION}` : ''),
+    )
   }
 }
 
@@ -441,6 +450,7 @@ export async function loadProjectConfigs(
   // `node:stream`), ~7 ms of a two-config warm run where every load hit.
   let builtins: BuiltinSnapshot = []
   let env: Readonly<Record<string, string | undefined>> = {}
+  let cwd = ''
   // More than one evaluation in flight: a change seen after one load may
   // be another's.
   let overlapping = false
@@ -484,7 +494,9 @@ export async function loadProjectConfigs(
       : await loadDefaultExport(configPath, 'Project', bytes!)
     // Before anything reads through them: a replaced `Array.prototype.includes`
     // turned the JSON-data walk's own check into "a cyclic reference".
-    const changed = repeat ? [] : [...restoreBuiltins(builtins), ...restoreEnv(env)]
+    const changed = repeat
+      ? []
+      : [...restoreBuiltins(builtins), ...restoreEnv(env), ...restoreCwd(cwd)]
     // Loads overlap, so another config's change can surface after this
     // one: named here, the refusal blamed the wrong file (D-119). The round
     // finds the one that made it.
@@ -536,6 +548,7 @@ export async function loadProjectConfigs(
     if (misses.length > 0) {
       builtins = builtinSnapshot()
       env = { ...process.env }
+      cwd = process.cwd()
     }
     overlapping = misses.length > 1
     let next = 0
@@ -554,7 +567,10 @@ export async function loadProjectConfigs(
         if (r.closure !== undefined) learnedClosures.push(r.closure)
       }
     }
-    const changed = misses.length > 0 ? [...restoreBuiltins(builtins), ...restoreEnv(env)] : []
+    const changed =
+      misses.length > 0
+        ? [...restoreBuiltins(builtins), ...restoreEnv(env), ...restoreCwd(cwd)]
+        : []
     if (first?.failed instanceof ChangedInRound) {
       for (const i of misses) {
         const configPath = prepared[i]!.configPath
@@ -644,9 +660,13 @@ class ChangedInRound {
 /** Without `configPath`, no config alone was found to make the change. */
 function builtinsChanged(changed: readonly string[], configPath?: string): UserError {
   const who = configPath === undefined ? 'a project config' : configPath
-  const env = changed.some((c) => c.startsWith('process.env.'))
-    ? '; a task gets an env var through `exec.env.define` or `passThrough`'
-    : ''
+  const env =
+    (changed.some((c) => c.startsWith('process.env.'))
+      ? '; a task gets an env var through `exec.env.define` or `passThrough`'
+      : '') +
+    (changed.some((c) => c.startsWith('process.cwd'))
+      ? '; a task runs in its project directory, and `cd <dir> && …` in `exec.command` moves it'
+      : '')
   return new UserError(
     `${who} changed ${changed.join(', ')} while it was evaluated — a config must not change the built-ins vx runs on: other configs are read through them and cache keys are made with them${env}`,
   )
@@ -702,6 +722,20 @@ function restoreEnv(before: Readonly<Record<string, string | undefined>>): strin
   return changed
 }
 
+/**
+ * A config's `process.chdir()` moved the whole process: every relative path
+ * vx resolves after it, its own and a plugin's, read from the config's
+ * choice (D-120). Put back, and named as the change.
+ */
+function restoreCwd(before: string): string[] {
+  // Through globalThis: the playground bundles this module, and its
+  // browser shim carries no free process global.
+  const proc = globalThis.process
+  if (before === '' || proc.cwd() === before) return []
+  proc.chdir(before)
+  return ['process.cwd (a chdir)']
+}
+
 function sameDescriptor(a: PropertyDescriptor, b: PropertyDescriptor): boolean {
   return (
     a.value === b.value &&