@vzn/vx 0.0.634 → 0.0.635

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.634",
-  "description": "The fastest task runner and build cache for JavaScript monorepos.",
+  "version": "0.0.635",
+  "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
     ".": {
@@ -15,16 +15,16 @@
   },
   "types": "./src/index.ts",
   "bin": {
-    "vx": "./launcher.cjs"
+    "vx": "./launcher.sh"
   },
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.634",
-    "@vzn/vx-linux-arm64": "0.0.634",
-    "@vzn/vx-darwin-x64": "0.0.634",
-    "@vzn/vx-darwin-arm64": "0.0.634"
+    "@vzn/vx-linux-x64": "0.0.635",
+    "@vzn/vx-linux-arm64": "0.0.635",
+    "@vzn/vx-darwin-x64": "0.0.635",
+    "@vzn/vx-darwin-arm64": "0.0.635"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"
@@ -42,6 +42,7 @@
     "docs/patterns.md",
     "docs/security.md",
     "docs/features.md",
+    "launcher.sh",
     "launcher.cjs",
     "README.md",
     "LICENSE"
@@ -64,6 +65,14 @@
     "nx",
     "bun",
     "workspaces",
-    "ci"
+    "ci",
+    "task-orchestration",
+    "turborepo-alternative",
+    "nx-alternative",
+    "remote-cache",
+    "sandbox",
+    "incremental-build",
+    "mcp",
+    "pnpm"
   ]
 }

package/schemas/last.json

@@ -170,7 +170,7 @@
         },
         "locations": {
           "type": "array",
-          "description": "on a failed row: the existing files its output names, in order of first appearance",
+          "description": "on a failed row: the existing files its output names, in order of first appearance; a file it also names with a line drops its bare mention",
           "items": {
             "type": "object",
             "additionalProperties": false,
@@ -181,6 +181,10 @@
               "col": { "type": "integer" }
             }
           }
+        },
+        "fixedIn": {
+          "type": "string",
+          "description": "on a failed row: the first later run where this task passed (ran or hit); absent while it has not"
         }
       }
     }

package/schemas/show.json

@@ -115,7 +115,8 @@
                 "files": { "$ref": "#/$defs/stringList" },
                 "workspaceFiles": { "$ref": "#/$defs/stringList" }
               }
-            }
+            },
+            "rewrittenInputs": { "enum": ["withhold", "compare"] }
           }
         }
       }

package/schemas/why.json

@@ -77,7 +77,10 @@
               "type": ["boolean", "null"],
               "description": "on a hit: true when outputs were restored, false when up-to-date"
             },
-            "cached": { "type": ["boolean", "null"] },
+            "cached": {
+              "type": ["boolean", "null"],
+              "description": "whether the task declares a cache; not whether this run hit it"
+            },
             "startedAt": { "type": "integer", "description": "epoch ms" }
           }
         },

package/src/cache/layered-cache.ts

@@ -76,7 +76,9 @@ export interface RemoteCacheLayer {
    * straight into the local cache — an HTTP wire returns its `fetch`
    * `Response`, a chunked wire `new Response(stream)`, bytes in hand
    * `new Blob([bytes])`. `durationMs` is the producing task's duration
-   * when the wire carries it.
+   * when the wire carries it. A body that errors before its end stores
+   * nothing and the read is a miss, so a layer can check bytes as they pass
+   * (a digest, a signature) and refuse at the end.
    */
   get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
   /**

package/src/cli/last.ts

@@ -384,7 +384,15 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
       )
       const tasks = (detail?.tasks ?? []).map((t) => {
         const f = failures.get(`${t.project}#${t.task}`)
-        return f === undefined ? t : { ...t, output: f.output, locations: f.locations }
+        return f === undefined
+          ? t
+          : {
+              ...t,
+              output: f.output,
+              locations: f.locations,
+              ...(f.sandboxFix !== undefined ? { sandboxFix: f.sandboxFix } : {}),
+              ...(f.fixedIn !== undefined ? { fixedIn: f.fixedIn } : {}),
+            }
       })
       process.stdout.write(`${JSON.stringify({ invocation: inv, tasks })}\n`)
       return 0

package/src/cli/plugin-templates.ts

@@ -10,7 +10,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   cache: {
     plugin:
-      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// `LayeredCache` puts it behind the local cache, so a remote error is a\n// miss and a warning, never a failed run.\nimport { mkdir, rename } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, LayeredCache, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then renamed: a reader never sees half an artifact.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    await rename(tmp, path.join(this.endpoint, hash))\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache(ctx) {\n      return new LayeredCache(ctx.localCache, new DirRemote(dir), {\n        policy: ctx.policy,\n        onRemoteError: (err) => ctx.warn(`dir-cache: ${err.message}`),\n      })\n    },\n  })\n}\n",
+      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// `LayeredCache` puts it behind the local cache, so a remote error is a\n// miss and a warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, LayeredCache, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache(ctx) {\n      return new LayeredCache(ctx.localCache, new DirRemote(dir), {\n        policy: ctx.policy,\n        onRemoteError: (err) => ctx.warn(`dir-cache: ${err.message}`),\n      })\n    },\n  })\n}\n",
     test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
   },
   commands: {

package/src/cli/run.ts

@@ -479,7 +479,9 @@ function onCI(v: string | undefined): boolean {
 async function scopeFilters(
   parsed: RunArgs,
   cwd: string,
-): Promise<{ filterStrings: string[]; affectedFilter?: string } | { error: string }> {
+): Promise<
+  { filterStrings: string[]; affectedFilter?: string } | { error: string; code?: string }
+> {
   // `--affected[=<base>]` is sugar for `--filter '...[<base>]'`: the
   // changed projects AND their dependents — what a CI gate must run, what
   // the flag's name says, what the guides promised while the sugar was the
@@ -523,7 +525,7 @@ export async function resolveRunOptions(
   verb: 'run' | 'watch' = 'run',
   /** Given, it learns the ref `--affected` diffed from (`--dry=json` states it). */
   scopeOut?: { affectedBase?: string },
-): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
+): Promise<RunOptions | { error: string; code?: string } | { nothingSelected: string }> {
   for (const t of tasks) {
     const idx = t.indexOf('#')
     if (idx >= 0) {
@@ -566,7 +568,7 @@ export async function resolveRunOptions(
           affectedFilter,
         )
       : undefined
-  if (resolved !== undefined && 'error' in resolved) return { error: resolved.error }
+  if (resolved !== undefined && 'error' in resolved) return resolved
   if (bareTasks.length === 0) {
     projects = undefined
   } else if (resolved !== undefined) {
@@ -696,11 +698,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     // `--filter` / `--affected` scope the menu, as they scope a bare task:
     // the menu listed every project and the anchored pick ran outside it.
     const scope = await scopeFilters(parsed, cwd)
-    if ('error' in scope) return refuse('run', args, scope.error, 'VX_E_USAGE')
+    if ('error' in scope) return refuse('run', args, scope.error, scope.code ?? 'VX_E_USAGE')
     let only: ReadonlySet<string> | undefined
     if (scope.filterStrings.length > 0) {
       const selected = await resolveFilters(cwd, scope.filterStrings, load, scope.affectedFilter)
-      if ('error' in selected) return refuse('run', args, selected.error, 'VX_E_USAGE')
+      if ('error' in selected)
+        return refuse('run', args, selected.error, selected.code ?? 'VX_E_USAGE')
       if ('empty' in selected) {
         process.stderr.write(`vx run: ${selected.empty}\n`)
         return 0
@@ -716,7 +719,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
 
   const scopeOut: { affectedBase?: string } = {}
   const resolved = await resolveRunOptions(parsed, cwd, tasks, 'run', scopeOut)
-  if ('error' in resolved) return refuse('run', args, resolved.error, 'VX_E_USAGE')
+  if ('error' in resolved) return refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
   if ('nothingSelected' in resolved) {
     process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
     return 0

package/src/cli/select.ts

@@ -197,7 +197,7 @@ export type FilterResolution =
       /** What the other includes selected (`RunOptions.selectedOutright`). */
       outright?: string[]
     }
-  | { error: string }
+  | Refusal
   | { empty: string }
 
 /**
@@ -239,16 +239,23 @@ export function taskEdgesFrom(staged: ReadonlyMap<string, ProjectEntry>): Map<st
   return out
 }
 
+/** A refusal a resolver returns; `code` is the thrown one's own, when it has one. */
+type Refusal = { error: string; code?: string }
+
+function refusalOf(err: unknown): Refusal {
+  if (!(err instanceof Error)) return { error: String(err) }
+  return isUserError(err) && err.code !== 'VX_E_REFUSED'
+    ? { error: err.message, code: err.code }
+    : { error: err.message }
+}
+
 /**
  * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
  * projects and their dependents. An empty base is the workspace's
  * `affectedBase` (or a plugin's `config` stage, from nx.json's
  * `defaultBase` or `TURBO_SCM_BASE`), then the guess.
  */
-export async function affectedFilterFor(
-  cwd: string,
-  affected: string,
-): Promise<string | { error: string }> {
+export async function affectedFilterFor(cwd: string, affected: string): Promise<string | Refusal> {
   const root = await findWorkspaceRoot(cwd)
   let base = affected
   if (base === '') base = (await loadCliWorkspace(root)).workspaceConfig?.affectedBase ?? ''
@@ -257,7 +264,7 @@ export async function affectedFilterFor(
       base = await defaultAffectedBase(root)
     } catch (err) {
       if (!isUserError(err)) throw err
-      return { error: err.message }
+      return refusalOf(err)
     }
   }
   return `...[${base}]`
@@ -276,7 +283,7 @@ export async function resolveFilters(
   try {
     parsed = raw.map((r) => parseFilter(r, root))
   } catch (err) {
-    return { error: err instanceof Error ? err.message : String(err) }
+    return refusalOf(err)
   }
   // `sinceViaDeps` (`e2e...[main]`) walks the changed projects' dependents.
   const walksGraph = parsed.some(
@@ -299,7 +306,7 @@ export async function resolveFilters(
     try {
       edges = taskEdgesFrom(await stagedOnce())
     } catch (err) {
-      return { error: err instanceof Error ? err.message : String(err) }
+      return refusalOf(err)
     }
   }
   // A tag lives in the config, so a `tag:` selector needs the staged load
@@ -309,7 +316,7 @@ export async function resolveFilters(
     try {
       tags = new Map([...(await stagedOnce()).values()].map((p) => [p.name, p.config.tags ?? []]))
     } catch (err) {
-      return { error: err instanceof Error ? err.message : String(err) }
+      return refusalOf(err)
     }
   }
   const graph = buildPackageGraph(projects, edges)
@@ -353,8 +360,7 @@ export async function resolveFilters(
       }
       affectedByFilter.set(f, names)
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      return { error: msg }
+      return refusalOf(err)
     }
   }
 

package/src/cli/show.ts

@@ -145,12 +145,12 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     let affected: string | undefined
     if (parsed.affected !== undefined) {
       const f = await affectedFilterFor(process.cwd(), parsed.affected)
-      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`, 'VX_E_USAGE')
+      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`, f.code ?? 'VX_E_USAGE')
       affected = f
       raw.unshift(f)
     }
     const r = await resolveFilters(process.cwd(), raw, { noCreate: true }, affected)
-    if ('error' in r) throw new UserError(`vx show: ${r.error}`, 'VX_E_USAGE')
+    if ('error' in r) throw new UserError(`vx show: ${r.error}`, r.code ?? 'VX_E_USAGE')
     if ('empty' in r) process.stderr.write(`vx show: ${r.empty}\n`)
     selected = new Set('empty' in r ? [] : r.names)
     if ('names' in r && r.affected !== undefined)

package/src/config.ts

@@ -65,9 +65,11 @@ export interface WorkspaceConfig {
    * Plugins registered for this workspace, consulted in this order once
    * per `vx run`: each fills any of the pipeline stages and capabilities
    * below, and core's own executor and cache store sit at the tail of
-   * every list. See `docs/design/pipeline-2026-09.md`.
+   * every list. See `docs/design/pipeline-2026-09.md`. An `undefined`,
+   * `null` or `false` entry is skipped, so a factory that declines
+   * (`github()` off Actions) or `cond && plugin()` needs no filter.
    */
-  plugins?: readonly Plugin[]
+  plugins?: readonly (Plugin | undefined | null | false)[]
 }
 
 /** `WorkspaceConfig.rules`. */
@@ -488,6 +490,16 @@ export interface CacheConfig {
   inputs: CacheInputs
   /** What this task produces. Captured for restore on a cache hit. */
   outputs: CacheOutputs
+  /**
+   * What a write to an input while the command runs means. `'withhold'`
+   * (the default): the entry is not saved, whatever the file holds after,
+   * since an edit undone mid-run cannot be told from no edit. `'compare'`:
+   * a file rewritten to the bytes the key folded counts as unchanged, for
+   * a task that rewrites its own input identically (tsdown's
+   * `package.json`). `VX_REWRITTEN_INPUTS=compare` sets the default for
+   * every task that does not say.
+   */
+  rewrittenInputs?: 'withhold' | 'compare'
 }
 
 export interface CacheOutputs {

package/src/graph/scheduler.ts

@@ -208,6 +208,15 @@ export interface TaskOutcome {
    * inline in the task's block instead of as loose status output.
    */
   sandboxViolationLines?: string[]
+  /** The `exec.sandbox.allow` entries that would have granted the denials. */
+  sandboxFix?: {
+    read?: string[]
+    write?: string[]
+    network?: string[]
+    systemInfo?: string[]
+    /** Credential paths denied and left out of the grants: an agent applies the fix as given. */
+    withheld?: string[]
+  }
 }
 
 export type ContinueMode = 'never' | 'deps-ok' | 'always'
@@ -804,14 +813,16 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       // tasks are never asked, so they never park.
       const takeFitting = (): string | undefined => {
         if (holding) return undefined
-        // No pools, no policy and a full exec lane: nothing on the
-        // exec queue can be admitted, so it is not scanned — scanning it
+        // No pools and a full exec lane: nothing on the exec queue can be
+        // admitted, so it is not scanned — an admit policy only narrows
+        // the count gate, never widens it (scanning under one cost the
+        // history plugin's cold bench run 10 s, 2026-10-09) — scanning it
         // would pop and re-park every ready exec task on every tick, and
         // with a wide frontier that is O(R) per tick, O(R²) per run (the
         // 6,000-task scale pin went 0.5 s → 28 s when the restore lane's
         // first cut let the scan run past a full exec lane, 2026-09-10).
         // This is the legacy O(1) gate, kept per lane.
-        const execAdmissible = poolOf !== undefined || admitActive || execRoom()
+        const execAdmissible = poolOf !== undefined || execRoom()
         if (execAdmissible) {
           while (execReady.size > 0) {
             const seq = execReady.peekSeq()

package/src/graph/task-graph.ts

@@ -302,6 +302,7 @@ export interface BuildGraphOptions {
 export function undeclaredDepsError(taskId: string, name: string): UserError {
   return new UserError(
     `Task ${taskId} depends on ^${name} but no project in the workspace declares ${name}`,
+    'VX_E_DEPENDS_ON',
   )
 }
 
@@ -492,7 +493,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       spec = parseDependencySpec(raw)
     } catch (err) {
       if (err instanceof DependencySpecError) {
-        throw new UserError(`Task ${id}: ${err.message}`)
+        throw new UserError(`Task ${id}: ${err.message}`, 'VX_E_DEPENDS_ON')
       }
       throw err
     }
@@ -503,14 +504,21 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     // operations. PARTIAL patterns (`build.*`, `^build.*`) are legal:
     // they name a namespace of tasks to add (Nx 19.5 parity).
     if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') {
-      throw new UserError(`Task ${id}: dependsOn does not accept bare wildcards (got "${raw}")`)
+      throw new UserError(
+        `Task ${id}: dependsOn does not accept bare wildcards (got "${raw}")`,
+        'VX_E_DEPENDS_ON',
+      )
     }
     if (spec.negated) {
-      throw new UserError(`Task ${id}: dependsOn does not accept negation (got "${raw}")`)
+      throw new UserError(
+        `Task ${id}: dependsOn does not accept negation (got "${raw}")`,
+        'VX_E_DEPENDS_ON',
+      )
     }
     if (spec.kind === 'cross' && (isTaskPattern(spec.task) || isTaskPattern(spec.project))) {
       throw new UserError(
         `Task ${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
+        'VX_E_DEPENDS_ON',
       )
     }
     if (spec.kind === 'self') {
@@ -530,6 +538,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         if (!visit(frame, projectName, spec.task, false)) {
           throw new UserError(
             `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
+            'VX_E_DEPENDS_ON',
           )
         }
         goPast(frame, projectName, spec.task, new Set([projectName]))
@@ -594,9 +603,11 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         if (spec.project === '//')
           throw new UserError(
             `Task ${id} depends on //#${spec.task}, Turbo's root package, but the workspace root is no project here: give it a package.json name and a vx.config with that task`,
+            'VX_E_DEPENDS_ON',
           )
         throw new UserError(
           `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+          'VX_E_DEPENDS_ON',
         )
       }
       goPast(frame, spec.project, spec.task, new Set([projectName, spec.project]))
@@ -1109,7 +1120,7 @@ function collideAcross(
         `cache.outputs.files — vx cleans a task's declared outputs before it runs and before a ` +
         `cache-hit restore, so whichever of these runs second DELETES the other's output`
       if (exclusive && (reaches(files.id, ws.id) || reaches(ws.id, files.id))) {
-        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`)
+        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`, 'VX_E_OUTPUT_OVERLAP')
       }
       if (reaches(files.id, ws.id)) {
         ;(files.addsToOutputsOf ??= []).push(ws.id)
@@ -1132,11 +1143,13 @@ function collideAcross(
           `${head}. ${ws.id} depends on ${files.id}, but adding to its output needs every ` +
             `cache.outputs.workspaceFiles entry inside ${rel === '' ? 'the workspace root' : rel}, ` +
             `and ${JSON.stringify(outside)} is not. Give each task its own output path.`,
+          'VX_E_OUTPUT_OVERLAP',
         )
       }
       throw new UserError(
         `${head} and the run still reports success. Give each task its own output path` +
           (exclusive ? '.' : ', or make one depend on the other.'),
+        'VX_E_OUTPUT_OVERLAP',
       )
     }
   }
@@ -1373,7 +1386,8 @@ function collide(
       // `rules.exclusiveOutputs` is off (X-53). Without an edge the two run
       // in either order, and the refusal below stands.
       const [up, down] = reaches(b.id, a.id) ? [a, b] : reaches(a.id, b.id) ? [b, a] : []
-      if (up !== undefined && exclusive) throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`)
+      if (up !== undefined && exclusive)
+        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`, 'VX_E_OUTPUT_OVERLAP')
       if (up !== undefined && down !== undefined) {
         const downGlobs = splitNegations(
           (field === 'files'
@@ -1386,6 +1400,7 @@ function collide(
       }
       throw new UserError(
         `${head} and the run still reports success. Give each task its own output path.`,
+        'VX_E_OUTPUT_OVERLAP',
       )
     }
   }
@@ -1440,6 +1455,7 @@ function refuseSelfClean(node: TaskNode): void {
           `its own output — vx removes a task's outputs before it runs, so the task would ` +
           `delete its own sources. A task that rewrites files in place (a formatter) declares ` +
           `no outputs.`,
+        'VX_E_INPUT_IS_OUTPUT',
       )
     }
   }
@@ -1663,6 +1679,7 @@ function readsOutputs(
           `Exclude it: add ${JSON.stringify(`!${out}`)} to ${reader.node.id}'s ` +
           `cache.inputs.${field}, or set rules: { upfrontKeys: false } in vx.workspace.ts to ` +
           `let it wait for its producer.`,
+        'VX_E_INPUT_IS_OUTPUT',
       )
     }
   }

package/src/index.ts

@@ -65,7 +65,12 @@ export { run, planRun, prepareRun } from './orchestrator/index.js'
 // (`@vzn/vx-schedule-history` does; a plugin package reaches core only
 // through this façade, which is what put these here).
 export { LocalHistoryProvider } from './orchestrator/index.js'
-export type { HistoryProvider, HistoryTable, TaskHistory } from './orchestrator/index.js'
+export type {
+  HistoryProvider,
+  HistoryTable,
+  TaskHistory,
+  TaskResources,
+} from './orchestrator/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
 // `RunOptions.affected`: what `--affected`'s diff changed, per project.
 export type { AffectedChanges } from './workspace/index.js'

package/src/orchestrator/execute-task.ts

@@ -78,6 +78,7 @@ import type { FingerprintWatch } from './fingerprint-watch.js'
 import { restoreHit } from './hit-restore.js'
 import type { MissExplainer } from './miss-reason.js'
 import { shellVerdict } from './shell-verdict.js'
+import { sandboxFix } from './sandbox-fix.js'
 // The hit path's entry stays importable from here (tests).
 export { restoreHit, type RestoreHitArgs } from './hit-restore.js'
 import type { DeferredOutputs } from './deferred-outputs.js'
@@ -336,6 +337,18 @@ async function restoreOrMiss(
   }
 }
 
+/**
+ * Does a write to an input during the command count as unchanged when it
+ * left the bytes the key folded (`movedInput`'s `writesByBytes`)? Only when
+ * the task says `compare`, or says nothing and `VX_REWRITTEN_INPUTS` is
+ * `compare`: by default any such write withholds the save, on CI too,
+ * since a concurrent task can change an input and put it back (owner,
+ * 2026-10-12).
+ */
+function rewritesByBytes(cache: CacheConfig | undefined): boolean {
+  return (cache?.rewrittenInputs ?? process.env['VX_REWRITTEN_INPUTS']) === 'compare'
+}
+
 /**
  * The workspace fingerprint every key here folded has moved (a task
  * rewrote the lockfile), said once per run.
@@ -1558,7 +1571,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
    */
   async function movedSinceKey(): Promise<string | null | undefined> {
     if (described!.hash !== hash) return null
-    return (await movedInput(described!.facts, cache, described!.describedAt)) ?? described!.added()
+    return (
+      (await movedInput(
+        described!.facts,
+        cache,
+        described!.describedAt,
+        rewritesByBytes(args.node.config.cache),
+      )) ?? described!.added()
+    )
   }
 
   /**
@@ -1608,6 +1628,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 
   const finalViolations = violations
+  const fixOf = (fix: TaskOutcome['sandboxFix']) => (fix === undefined ? {} : { sandboxFix: fix })
 
   return {
     node,
@@ -1640,6 +1661,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           sandboxViolations: finalViolations.filter((v) => v.hint !== true).length,
           // A denied path is the task's own spelling, a secret in it too.
           sandboxViolationLines: finalViolations.map((v) => secrets?.mask(v.line) ?? v.line),
+          ...fixOf(
+            sandboxFix(
+              finalViolations,
+              node.projectDir,
+              (t) => secrets?.mask(t) ?? t,
+              cacheCfg?.inputs.files,
+            ),
+          ),
         }
       : {}),
   }

package/src/orchestrator/framed-output.ts

@@ -32,6 +32,7 @@ import { paint, type ColorSupport } from './colors.js'
 import { neverStarted } from './summary.js'
 import { outcomeLabel, ranNoCache, skippedReason } from './events.js'
 import { fileMemo, linkPaths } from './path-links.js'
+import { sandboxFixLine } from './sandbox-fix.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }
 
@@ -529,7 +530,32 @@ function violationSection(outcome: TaskOutcome, colors: ColorSupport): string[]
   // every record for telemetry.
   const body = [...new Set(vlines)]
   // Red, not amber: a violation fails the task, so it reads as a failure.
-  return [sectionLine(`SANDBOX VIOLATIONS (${body.length})`, ERROR, colors), '', ...body, '']
+  // vx's note, after the evidence: the grants that would have allowed it.
+  // A read the output depends on is a key input too; the sandbox never
+  // adds one (owner, 2026-10-09).
+  const fix = outcome.sandboxFix
+  const line = fix === undefined ? undefined : sandboxFixLine(fix)
+  const dim = (text: string): string => paint('', text, colors, { dim: true })
+  const note =
+    fix === undefined
+      ? []
+      : [
+          ...(line !== undefined ? [dim(`fix: ${line}`)] : []),
+          ...(fix.read !== undefined
+            ? [dim('a read the output depends on belongs in cache.inputs.files too')]
+            : []),
+          ...(fix.withheld !== undefined
+            ? [dim(`credential path, grant it only on purpose: ${fix.withheld.join(', ')}`)]
+            : []),
+          '',
+        ]
+  return [
+    sectionLine(`SANDBOX VIOLATIONS (${body.length})`, ERROR, colors),
+    '',
+    ...body,
+    '',
+    ...note,
+  ]
 }
 
 export function formatFrameClose(