@vzn/vx 0.0.634 → 0.0.635

package/src/orchestrator/history.ts

@@ -21,7 +21,8 @@ const DEFAULT_RECENT = 50
 
 // A hit is recorded as `cache-hit` / `cache-hit-remote` and replays a
 // success; the list is derived so a new status cannot miss it.
-const PASS_STATUSES = `(${TASK_STATUSES.filter(isPassStatus)
+/** The pass set as SQL, `(…)`: one definition, `isPassStatus`. */
+export const PASS_STATUSES = `(${TASK_STATUSES.filter(isPassStatus)
   .map((s) => `'${s}'`)
   .join(', ')})`
 
@@ -58,6 +59,12 @@ export interface TaskHistory {
 /** Map keyed by `project#task`. */
 export type HistoryTable = ReadonlyMap<string, TaskHistory>
 
+/** What a scheduler learns from a task's history: its p50 and its resource maxima. */
+export type TaskResources = Pick<
+  TaskHistory,
+  'p50DurationMs' | 'maxPeakRssBytes' | 'maxCpuParallelism'
+>
+
 export interface HistoryProvider {
   loadFor(taskIds: readonly string[]): Promise<HistoryTable>
   /**
@@ -213,6 +220,73 @@ export class LocalHistoryProvider implements HistoryProvider {
     return out
   }
 
+  /**
+   * `loadFor`'s p50 and resource maxima over the same window, without its
+   * rates. The rates group every row of the window and join each hit to
+   * its entry: 407 ms at 168,000 rows (8,002 tasks, 21 runs), most of a
+   * nothing-changed run's schedule stage. Here the executed successes are
+   * grouped alone, and the hits only as distinct keys, each joined to its
+   * entry once: 148 ms on the same table, the same numbers.
+   */
+  async resourcesFor(taskIds: readonly string[]): Promise<ReadonlyMap<string, TaskResources>> {
+    const out = new Map<string, TaskResources>()
+    if (taskIds.length === 0) return out
+    const floor = this.floor()
+    const wanted = new Set(taskIds)
+    type Executed = {
+      project: string
+      task: string
+      ds: string
+      rss: number | null
+      cpu: number | null
+    }
+    const executed = this.db
+      .query(
+        `SELECT project, task, GROUP_CONCAT(duration_ms) AS ds, MAX(peak_rss_bytes) AS rss,
+           MAX(CASE WHEN cpu_ms IS NOT NULL AND duration_ms > 0
+                    THEN cpu_ms * 1.0 / duration_ms END) AS cpu
+         FROM runs
+         WHERE id >= ? AND status = 'success' AND (cache_hit IS NULL OR cache_hit = 0)
+         GROUP BY project, task`,
+      )
+      .all(floor) as Executed[]
+    for (const row of executed) {
+      const key = `${row.project}#${row.task}`
+      if (!wanted.has(key)) continue
+      const durations = row.ds.split(',').map(Number)
+      durations.sort((a, b) => a - b)
+      out.set(key, {
+        p50DurationMs: pickPercentile(durations, 0.5),
+        ...(row.rss !== null ? { maxPeakRssBytes: row.rss } : {}),
+        ...(row.cpu !== null ? { maxCpuParallelism: row.cpu } : {}),
+      })
+    }
+    type Hit = { project: string; task: string; rss: number | null; cpu: number | null }
+    const hits = this.db
+      .query(
+        `SELECT h.project, h.task, MAX(e.peak_rss_bytes) AS rss,
+           MAX(CASE WHEN e.cpu_ms IS NOT NULL AND e.duration_ms > 0
+                    THEN e.cpu_ms * 1.0 / e.duration_ms END) AS cpu
+         FROM (SELECT DISTINCT project, task, hash FROM runs WHERE id >= ? AND cache_hit = 1) h
+         JOIN entries e ON e.hash = h.hash
+         GROUP BY h.project, h.task`,
+      )
+      .all(floor) as Hit[]
+    for (const row of hits) {
+      const key = `${row.project}#${row.task}`
+      if (!wanted.has(key) || (row.rss === null && row.cpu === null)) continue
+      const had = out.get(key)
+      const rss = Math.max(had?.maxPeakRssBytes ?? -Infinity, row.rss ?? -Infinity)
+      const cpu = Math.max(had?.maxCpuParallelism ?? -Infinity, row.cpu ?? -Infinity)
+      out.set(key, {
+        p50DurationMs: had?.p50DurationMs,
+        ...(rss !== -Infinity ? { maxPeakRssBytes: rss } : {}),
+        ...(cpu !== -Infinity ? { maxCpuParallelism: cpu } : {}),
+      })
+    }
+    return out
+  }
+
   /** The first `runs` id of the newest `recent` invocations (see `loadFor`). */
   private floor(): number {
     const row = this.db

package/src/orchestrator/index.ts

@@ -56,6 +56,7 @@ export {
   type HistoryTable,
   LocalHistoryProvider,
   type TaskHistory,
+  type TaskResources,
 } from './history.js'
 export {
   detectFlaky,

package/src/orchestrator/path-links.ts

@@ -35,7 +35,9 @@ export function linkPaths(text: string, dir: string, isFile: (abs: string) => bo
 
 /**
  * The files `text` names that exist (resolved against `dir`), each with the
- * line and column it gave, unique, in order of first appearance.
+ * line and column it gave, unique, in order of first appearance. A file also
+ * named with a line drops its bare mention: bun test heads a failure with
+ * `app.test.js:` and gives the line only in the stack below it.
  */
 export function fileLocations(
   text: string,
@@ -56,9 +58,9 @@ export function fileLocations(
       ...(line !== undefined ? { line: Number(line) } : {}),
       ...(col !== undefined ? { col: Number(col) } : {}),
     })
-    if (out.length === LOCATIONS_CAP) break
   }
-  return out
+  const lined = new Set(out.filter((l) => l.line !== undefined).map((l) => l.file))
+  return out.filter((l) => l.line !== undefined || !lined.has(l.file)).slice(0, LOCATIONS_CAP)
 }
 
 /** A file test that asks the file system once per path. */

package/src/orchestrator/plugin.ts

@@ -127,7 +127,9 @@ export interface VxPlugin {
   /**
    * Scheduling priorities: task id → weight, higher runs first among READY
    * tasks (merged over the structural baseline, which stays the tie-break).
-   * Runs once, after the graph is final. A later plugin's weight for a task
+   * Runs once, after the graph is final and the local hits are known, and
+   * only when a task will start: a run of confirmed local hits restores
+   * in no order a weight changes. A later plugin's weight for a task
    * overrides an earlier one's. Return undefined to leave the baseline.
    */
   schedule?(

package/src/orchestrator/prepare.ts

@@ -102,9 +102,11 @@ export interface PreparedRun {
   /**
    * Scheduling priorities from plugins' `schedule` stage (task id → weight,
    * merged over the structural baseline by the scheduler). Empty when no
-   * plugin declares the stage.
+   * plugin declares the stage. Asked only by a run with a task to start:
+   * the stage reads history (148 ms at 8,002 tasks) to order work a
+   * nothing-changed run never dispatches. Runs the stage once.
    */
-  priorities: ReadonlyMap<string, number>
+  priorities: () => Promise<ReadonlyMap<string, number>>
   nodes: Map<string, TaskNode>
   /**
    * The tasks `--exclude-dependencies` took out of the schedule: keyed as a
@@ -491,7 +493,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
-      priorities: new Map(),
+      priorities: () => Promise.resolve(new Map()),
       nodes: new Map(),
       keyOnly: new Map(),
       unresolvedTasks,
@@ -687,15 +689,16 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         })
       }
     }
-    let priorities: ReadonlyMap<string, number> = new Map()
-    if (hasHook(plugins, 'schedule')) {
-      priorities = await applyScheduleHooks(plugins, nodes, {
-        workspaceRoot,
-        cacheDir,
-        warn: (m) => log.status(m),
-        localCache,
-      })
-    }
+    let scheduled: Promise<ReadonlyMap<string, number>> | undefined
+    const priorities = (): Promise<ReadonlyMap<string, number>> =>
+      (scheduled ??= hasHook(plugins, 'schedule')
+        ? applyScheduleHooks(plugins, nodes, {
+            workspaceRoot,
+            cacheDir,
+            warn: (m) => log.status(m),
+            localCache,
+          })
+        : Promise.resolve(new Map()))
 
     return {
       workspaceRoot,

package/src/orchestrator/run-failures.ts

@@ -9,6 +9,7 @@ import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import path from 'node:path'
 import { isGroupTask, type TaskOutcome } from '../graph/index.js'
 import { decodeOutputLog } from './output-log.js'
+import { PASS_STATUSES } from './history.js'
 import { splitTaskId } from '../util/index.js'
 import { fileLocations, fileMemo, type OutputLocation } from './path-links.js'
 
@@ -23,6 +24,10 @@ export interface TaskFailure {
   /** Plain text, bounded, secrets masked; '' when the run kept none. */
   output: string
   locations: OutputLocation[]
+  /** The `exec.sandbox.allow` entries that would have granted its denials. */
+  sandboxFix?: NonNullable<TaskOutcome['sandboxFix']>
+  /** The first later run where this task passed (ran or hit): the failure is history. */
+  fixedIn?: string
 }
 
 export interface RunFailures {
@@ -56,6 +61,7 @@ function failuresOf(outcomes: readonly TaskOutcome[]): StoredFailure[] {
       ...(o.timedOut === true ? { timedOut: true as const } : {}),
       output,
       locations: fileLocations(output, o.node.projectDir, isFile),
+      ...(o.sandboxFix !== undefined ? { sandboxFix: o.sandboxFix } : {}),
     })
   }
   return out
@@ -110,10 +116,19 @@ export function runFailures(cacheDir: string, db: Database, runId?: string): Run
   }
   const rows = db
     .query(
-      `SELECT project, task, exit_code AS exitCode, timed_out AS timedOut FROM runs
-       WHERE run_id = ? AND status = 'failed' ORDER BY id`,
+      `SELECT r.project, r.task, r.exit_code AS exitCode, r.timed_out AS timedOut,
+         (SELECT s.run_id FROM runs s WHERE s.project = r.project AND s.task = r.task
+            AND s.id > r.id AND s.status IN ${PASS_STATUSES}
+          ORDER BY s.id LIMIT 1) AS fixedIn
+       FROM runs r WHERE r.run_id = ? AND r.status = 'failed' ORDER BY r.id`,
     )
-    .all(id) as { project: string; task: string; exitCode: number; timedOut: number | null }[]
+    .all(id) as {
+    project: string
+    task: string
+    exitCode: number
+    timedOut: number | null
+    fixedIn: string | null
+  }[]
   return {
     runId: id,
     tasks: rows.map((r) => {
@@ -125,6 +140,8 @@ export function runFailures(cacheDir: string, db: Database, runId?: string): Run
         ...(r.timedOut === 1 ? { timedOut: true as const } : {}),
         output: k?.output ?? '',
         locations: k?.locations ?? [],
+        ...(k?.sandboxFix !== undefined ? { sandboxFix: k.sandboxFix } : {}),
+        ...(r.fixedIn !== null ? { fixedIn: r.fixedIn } : {}),
       }
     }),
   }

package/src/orchestrator/run.ts

@@ -1089,6 +1089,14 @@ async function runOnBus(
     })
 
     mark('classify + probe')
+    // A run whose every task is a confirmed local hit dispatches only
+    // restores, which no weight orders: the `schedule` stage is not asked.
+    const priorities = [...nodes.values()].every(
+      (n) => n.config.exec?.command === undefined || shortCircuit.restoreTier.has(n.id),
+    )
+      ? new Map<string, number>()
+      : await prepared.priorities()
+    mark('schedule')
     // Judged as each task finishes, against the history BEFORE this run's
     // rows land, so the row that prints next carries the verdict: nothing
     // prints below the footer. A hit or a skip asks nothing; a green miss
@@ -1172,7 +1180,7 @@ async function runOnBus(
         : {}),
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
-      ...(prepared.priorities.size > 0 ? { priorities: prepared.priorities } : {}),
+      ...(priorities.size > 0 ? { priorities } : {}),
       // The baseline under them; `most-work` when the workspace names none.
       ...(prepared.workspaceConfig?.schedule !== undefined
         ? { strategy: prepared.workspaceConfig.schedule }
@@ -1718,6 +1726,8 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
     if (prepared.empty === 'none-affected')
       return { tasks: [], noneAffected: noneAffected(prepared, options) }
     if (prepared.empty !== null) return { tasks: [] }
+    // The plan orders nothing, but it refuses what the run would refuse.
+    await prepared.priorities()
     // Its own mark: a dry run's plan (every task's hash, the cache lookups,
     // the history p50s) was booked under `close`, the next mark, and read
     // as 105 ms of closing a cache at 1,000 projects (item 601).

package/src/orchestrator/sandbox-fix.ts

@@ -0,0 +1,123 @@
+// The `exec.sandbox.allow` entries that would have granted what a failed
+// task was denied, so the report names the line to add (CLI, JSON, MCP)
+// rather than leaving the user to turn absolute paths into grants. Built on
+// the failure path only: a passing run never calls it.
+
+import { lstatSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import type { SandboxViolation } from '../exec/index.js'
+import type { TaskOutcome } from '../graph/index.js'
+import { isLiteralPattern } from '../util/index.js'
+
+/** Grants to add under `exec.sandbox.allow`, each list sorted and unique. */
+type SandboxFix = NonNullable<TaskOutcome['sandboxFix']>
+type Kind = Exclude<keyof SandboxFix, 'withheld'>
+
+// Where credentials live. A denial here is never turned into a grant: an
+// agent applies `sandboxFix` as given, so a dependency probing ~/.ssh would
+// get its grant suggested and applied (Security, 2026-10-12).
+const CREDENTIAL_DIRS = ['.ssh', '.aws', '.gnupg', '.kube', '.config/gh', '.config/gcloud']
+const CREDENTIAL_FILES = ['.netrc', '.npmrc', '.docker/config.json', '.git-credentials', '.pypirc']
+
+function isCredential(abs: string): boolean {
+  const base = path.basename(abs)
+  if (base === '.env' || base.startsWith('.env.')) return true
+  const rel = path.relative(os.homedir(), abs)
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return false
+  return (
+    CREDENTIAL_FILES.includes(rel) ||
+    CREDENTIAL_DIRS.some((d) => rel === d || rel.startsWith(d + path.sep))
+  )
+}
+
+/**
+ * A path as a grant spells it: project-relative inside the project, `~/…`
+ * under home, else absolute.
+ */
+function grantPath(abs: string, projectDir: string): string {
+  const rel = path.relative(projectDir, abs)
+  if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel
+  const home = os.homedir()
+  return abs.startsWith(home + path.sep) ? `~/${abs.slice(home.length + 1)}` : abs
+}
+
+/**
+ * A write grant covers the top directory the write landed in: granting
+ * `dist/a.js` alone fails the run again on `dist/b.js`. Not when the task
+ * reads that directory as an input: the grant would let it write its own
+ * inputs, so it names the path alone.
+ */
+function writeGrant(grant: string, isDir: boolean, inputs: readonly string[]): string {
+  const slash = grant.indexOf('/')
+  const exact = isDir ? `${grant}/` : grant
+  if (grant.startsWith('~/') || path.isAbsolute(grant) || slash === -1) return exact
+  const top = grant.slice(0, slash)
+  return inputs.some((g) => readsDir(g, top)) ? exact : `${top}/`
+}
+
+/** Whether input glob `g` can match under top directory `top`. */
+function readsDir(g: string, top: string): boolean {
+  if (g.startsWith('!')) return false
+  const first = g.replace(/^\.\//, '').split('/')[0] ?? ''
+  return first === top || !isLiteralPattern(first)
+}
+
+function kindOf(v: SandboxViolation): Kind | undefined {
+  const can = v.ignorable ?? []
+  if (can.length === 1) return can[0]
+  // Linux reports a refused `openat` as either: the flags the parse drops
+  // decide. A file the host has was hidden from a read; one it lacks was
+  // being created.
+  if (can.includes('read') && can.includes('write') && v.path !== undefined)
+    return lstatSync(v.path, { throwIfNoEntry: false }) !== undefined ? 'read' : 'write'
+  return undefined
+}
+
+export function sandboxFix(
+  violations: readonly SandboxViolation[],
+  projectDir: string,
+  mask: (text: string) => string = (t) => t,
+  /** The task's `cache.inputs.files`: a write under one is granted exactly. */
+  inputs: readonly string[] = [],
+): SandboxFix | undefined {
+  const fix: Record<Kind | 'withheld', Set<string>> = {
+    read: new Set(),
+    write: new Set(),
+    network: new Set(),
+    systemInfo: new Set(),
+    withheld: new Set(),
+  }
+  for (const v of violations) {
+    if (v.hint === true || v.target === undefined) continue
+    const kind = kindOf(v)
+    if (kind === undefined) continue
+    if (kind === 'network') fix.network.add(v.target.replace(/:\d+$/, ''))
+    else if (kind === 'systemInfo') fix.systemInfo.add(v.target)
+    else if (v.path === undefined) continue
+    else if (isCredential(v.path)) fix.withheld.add(grantPath(v.path, projectDir))
+    else if (kind === 'read') fix.read.add(grantPath(v.path, projectDir))
+    else {
+      const isDir =
+        v.line.startsWith('mkdir') ||
+        lstatSync(v.path, { throwIfNoEntry: false })?.isDirectory() === true
+      fix.write.add(writeGrant(grantPath(v.path, projectDir), isDir, inputs))
+    }
+  }
+  const out: SandboxFix = {}
+  for (const k of ['read', 'write', 'network', 'systemInfo', 'withheld'] as const)
+    if (fix[k].size > 0) out[k] = [...new Set([...fix[k]].map(mask))].sort()
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/**
+ * The fix as the config line it is: `exec.sandbox.allow: { read: ['a'] }`,
+ * or undefined when every denial was a withheld credential path.
+ */
+export function sandboxFixLine({ withheld: _, ...fix }: SandboxFix): string | undefined {
+  if (Object.keys(fix).length === 0) return undefined
+  const parts = Object.entries(fix).map(
+    ([k, list]: [string, string[]]) => `${k}: [${list.map((p) => `'${p}'`).join(', ')}]`,
+  )
+  return `exec.sandbox.allow: { ${parts.join(', ')} }`
+}

package/src/orchestrator/task-hash.ts

@@ -238,11 +238,15 @@ export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
  * input changed and changed BACK while the command ran matched its digest
  * again, and the entry saved the other content's output under the key (item
  * 1015). A write before it — an upstream's — is judged by content, as before.
+ * `writesByBytes` (`cache.rewrittenInputs: 'compare'`) judges a write
+ * during the command by content too: the task says the same bytes are its
+ * own identical rewrite (tsdown's package.json), not an edit undone.
  */
 export async function movedInput(
   facts: readonly InputFact[],
   cache: CacheLayer,
   commandFrom?: number,
+  writesByBytes = false,
 ): Promise<string | undefined> {
   const suspects: InputFact[] = []
   for (const f of facts) {
@@ -260,7 +264,9 @@ export async function movedInput(
     // an even one, FAT's tick), one during the command included
     // (`racyWindowMs`).
     if (commandFrom !== undefined && ctimeMs >= commandFrom - racyWindowMs(ctimeMs, 0)) {
-      return f.path
+      if (!writesByBytes) return f.path
+      suspects.push(f)
+      continue
     }
     if (ctimeMs >= f.since - racyWindowMs(ctimeMs, FILE_HASH_RACY_MS)) suspects.push(f)
   }

package/src/workspace/affected.ts

@@ -173,6 +173,7 @@ export async function affectedChanges(
   if (since.length === 0 || since.startsWith('-')) {
     throw new UserError(
       `git ref "${since}" is not a ref: a base cannot be empty or start with "-".`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   // `A..B` / `A...B` reached `rev-parse --verify`, which refuses a range, and
@@ -183,6 +184,7 @@ export async function affectedChanges(
     throw new UserError(
       `git ref "${since}" is a range: ranges are not supported — pass the base alone ` +
         `("${since.slice(0, range) || 'HEAD'}"); vx diffs it against the working tree.`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   // `^main` is rev-list's exclusion, not a ref: merge-base refused it, it
@@ -191,6 +193,7 @@ export async function affectedChanges(
   if (since.startsWith('^')) {
     throw new UserError(
       `git ref "${since}" is an exclusion, not a ref: pass the base alone ("${since.replace(/^\^+/, '') || 'HEAD'}").`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   // Diff from the MERGE BASE of `since` and HEAD, not from `since` itself:
@@ -556,12 +559,13 @@ async function gitBlobsAt(
     proc.exited,
   ])
   if (exit !== 0) {
-    throw new UserError(`git cat-file --batch failed (exit ${exit}): ${stderr.trim()}`)
+    throw new UserError(`git cat-file --batch failed (exit ${exit}): ${stderr.trim()}`, 'VX_E_GIT')
   }
   let at = 0
   for (const file of batched) {
     const eol = out.indexOf(0x0a, at)
-    if (eol === -1) throw new UserError(`git cat-file --batch ended before ${ref}:./${file}`)
+    if (eol === -1)
+      throw new UserError(`git cat-file --batch ended before ${ref}:./${file}`, 'VX_E_GIT')
     const header = new TextDecoder().decode(out.subarray(at, eol))
     at = eol + 1
     // `<oid> <type> <size>`, or `<spec> missing` / `<spec> ambiguous`.
@@ -636,7 +640,10 @@ async function gitBytesAt(
   // "exists on disk but not in <ref>" and "path does not exist in <ref>"
   // are the file being absent at the ref; anything else is git failing.
   if (/does not exist in|exists on disk, but not in/.test(stderr)) return null
-  throw new UserError(`git show ${ref}:./${file} failed (exit ${exit}): ${stderr.trim()}`)
+  throw new UserError(
+    `git show ${ref}:./${file} failed (exit ${exit}): ${stderr.trim()}`,
+    'VX_E_GIT',
+  )
 }
 
 async function bytesOrNull(file: string): Promise<Uint8Array | null> {
@@ -654,7 +661,7 @@ async function gitPaths(workspaceRoot: string, cmd: string[]): Promise<string[]>
   const stderr = await new Response(proc.stderr).text()
   const exit = await proc.exited
   if (exit !== 0) {
-    throw new UserError(`git ${cmd[0]} failed (exit ${exit}): ${stderr.trim()}`)
+    throw new UserError(`git ${cmd[0]} failed (exit ${exit}): ${stderr.trim()}`, 'VX_E_GIT')
   }
   return stdout.split('\0').filter((s) => s.length > 0)
 }
@@ -724,6 +731,7 @@ export async function defaultAffectedBase(workspaceRoot: string): Promise<string
       '--affected has no base here: origin/HEAD is not set (or names a branch that is gone) and HEAD has no parent to compare ' +
         'with — a shallow clone? Fetch history (actions/checkout: fetch-depth: 0) or name the ' +
         'base: --affected=origin/main',
+      'VX_E_AFFECTED_BASE',
     )
   }
   return 'HEAD~1'
@@ -742,6 +750,7 @@ function noHistoryRefusal(workspaceRoot: string): UserError | undefined {
   if (revParse(workspaceRoot, 'HEAD') === undefined) {
     return new UserError(
       '--affected has no base here: this repository has no commit yet. Commit first, or run without --affected.',
+      'VX_E_AFFECTED_BASE',
     )
   }
   return undefined
@@ -832,6 +841,7 @@ async function mergeBase(workspaceRoot: string, ref: string): Promise<string> {
     throw new UserError(
       `git ref "${ref}" names what is at ${sub[2]}, not a commit: vx diffs the whole ` +
         `workspace, so pass the commit alone ("${sub[1] || 'HEAD'}").`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   return ref
@@ -857,6 +867,7 @@ async function verifyRef(workspaceRoot: string, ref: string): Promise<void> {
     throw new UserError(
       `git rev-parse failed (exit ${proc.exitCode}) in ${workspaceRoot}` +
         (stderr.length > 0 ? `: ${stderr}` : ''),
+      'VX_E_GIT',
     )
   }
   // A shallow clone (CI's checkout fetches one commit by default) has no
@@ -868,6 +879,7 @@ async function verifyRef(workspaceRoot: string, ref: string): Promise<void> {
       (isShallow
         ? ' This clone is shallow: fetch the history the base needs (`git fetch --unshallow`, or `fetch-depth: 0` on actions/checkout).'
         : ''),
+    'VX_E_AFFECTED_BASE',
   )
 }
 

package/src/workspace/config-schema.ts

@@ -136,6 +136,11 @@ function validateRetention(retention: unknown, configPath: string): void {
   }
 }
 
+/** A `plugins` entry that stands for no plugin: `undefined`, `null` or `false`. */
+export function isSkippedPlugin(p: unknown): p is undefined | null | false {
+  return p === undefined || p === null || p === false
+}
+
 export function validateWorkspace(config: WorkspaceConfig, configPath: string): void {
   // No JSON-data rule here, unlike `validateProjectConfig`: `plugins` holds
   // objects of functions by design, the file is evaluated in-process on
@@ -206,7 +211,10 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     }
     const verbOwners = new Map<string, string>()
     const fileClaimants = new Map<string, { name: string; at: number }>()
-    for (const [i, p] of config.plugins.entries()) {
+    for (const [i, p] of (config.plugins as readonly unknown[]).entries()) {
+      // A factory that declines returns nothing, and `cond && plugin()` is
+      // false: both are skipped, as Vite skips them.
+      if (isSkippedPlugin(p)) continue
       if (p === null || typeof p !== 'object') {
         // Nx's nx.json lists plugins by module name (`'@nx/vite/plugin'`);
         // a vx plugin is the value its package's function returns.
@@ -660,6 +668,10 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         )
       }
       assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
+      const rewritten = (cache as { rewrittenInputs?: unknown }).rewrittenInputs
+      if (rewritten !== undefined && rewritten !== 'withhold' && rewritten !== 'compare') {
+        throw new UserError(`${where}.cache.rewrittenInputs must be 'withhold' or 'compare'`)
+      }
       const inputs = (cache as { inputs?: unknown }).inputs
       const outputs = (cache as { outputs?: unknown }).outputs
       // A present field of the wrong shape (`outputs: 'dist'`) was told it
@@ -896,7 +908,7 @@ const EXEC_FIELDS = new Set([
 ])
 const PERSISTENT_FIELDS = new Set(['readyWhen'])
 const ENV_FIELDS = new Set(['passThrough', 'define', 'secret'])
-const CACHE_FIELDS = new Set(['inputs', 'outputs'])
+const CACHE_FIELDS = new Set(['inputs', 'outputs', 'rewrittenInputs'])
 const CACHE_INPUT_FIELDS = new Set([
   'files',
   'workspaceFiles',