@vzn/vx 0.0.16 → 0.0.21

package/src/orchestrator/execute-task.ts

@@ -1,4 +1,3 @@
-import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import type { ExecConfig, TaskConfig, CacheConfig } from '../config.js'
 import {
@@ -9,32 +8,36 @@ import {
   cleanWorkspaceOutputs,
   FULL_CACHE_POLICY,
   type GitFilesCache,
-  resolveInputs,
-  resolveOutputs,
-  resolveWorkspaceOutputs,
-  WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import {
   buildIsolatedEnv,
-  runCommand,
+  VX_RUN_TASK_ENV,
+  VX_RUN_WORKSPACE_ENV,
   runPersistent,
-  runSandboxed,
-  resolveSandboxConfig,
+  shellQuote,
+  releaseBridges,
+  wrapSandboxedCommand,
+  signalExitCode,
+  type CaptureConfig,
+  type ExecuteRequest,
+  type ExecuteResult,
   type SandboxViolation,
+  type TaskExecutor,
+  type TaskInputs,
 } from '../exec/index.js'
-import { isGroupTask, type TaskNode, type TaskOutcome, type VerifyVerdict } from '../graph/index.js'
-import {
-  classifyDeterminism,
-  diffOutputTrees,
-  foldFingerprint,
-  hashOutputTree,
-  outputRefs,
-  undeclaredInputPaths,
-} from './verify.js'
+import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { span } from '../util/index.js'
+import { sandboxRequestFor } from './sandbox-request.js'
+import { saveMiss, type OutputDirSnapshot } from './miss-save.js'
+import { restoreHit } from './hit-restore.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'
 import type { Logger } from './logger.js'
 import {
   computeGroupHash,
   computeTaskHash,
+  describeTaskInputs,
   type HashCache,
   type TaskInputComponent,
 } from './task-hash.js'
@@ -49,6 +52,32 @@ export interface ExecuteArgs {
   cachePolicy?: CachePolicy
   forwardArgs?: readonly string[] | undefined
   log: Logger
+  /** The executor this task was PLACED on (run.ts, before scheduling). */
+  executor: TaskExecutor
+  /**
+   * `exec.remote: 'only'` with no remote executor to take it: succeed
+   * WITHOUT executing, cleaning, restoring or saving anything on this
+   * machine. The hash is still computed — dependents fold it.
+   */
+  remoteOnlyNoop?: boolean
+  /**
+   * `exec.remote: 'only'` placed on a remote executor: execute remotely,
+   * but this machine's disk is untouched — no output clean, no vx cache
+   * probe/restore/save. The task's outputs live in the REMOTE store and
+   * reach dependents' input trees by reference (the executor's job).
+   */
+  remoteOnly?: boolean
+  /**
+   * Plan-time `--download` decision for THIS task (run.ts). `'deferred'`
+   * means: do not clean, do not save — the executor is expected to leave
+   * the outputs in the remote store and hand back a closure. An executor
+   * that ignores it and materialises anyway simply gets no local entry;
+   * the outputs are on disk but unindexed, which is its contract to keep.
+   */
+  download?: 'eager' | 'deferred'
+  /** Run-scoped deferral registry — where deferred closures land, and
+   *  where a locally-placed consumer fetches its producers from. */
+  deferred?: DeferredOutputs
   nestedProjectDirs: string[]
   /** Anchor for hrtime spans across all tasks in this run. */
   runStartHrTimeNs: bigint
@@ -78,25 +107,6 @@ export interface ExecuteArgs {
    * `exec.timeout` wins. Threaded as an option only — never hashed.
    */
   timeout?: number
-  /**
-   * Cache-correctness verification (`vx run --verify`). When
-   * `determinism` is set, an executed + cacheable task is re-run after its
-   * save and its outputs are content-compared; a divergence flags the task
-   * non-hermetic. When `inputs` is set, an executed + cacheable task is
-   * forced through the declared-input baseline sandbox and any read outside
-   * those inputs flags the declared `cache.inputs` as incomplete. When
-   * `fingerprint` is set, the executed task's output tree is fingerprinted
-   * and attached to the outcome (no re-run — the cross-machine diff feed).
-   * `allow` exempts known-nondeterministic task ids from failing the run.
-   * Pure side-channel — the re-run never saves, nothing is hashed.
-   * Undefined = off.
-   */
-  verify?: {
-    determinism: boolean
-    inputs: boolean
-    fingerprint: boolean
-    allow: ReadonlySet<string>
-  }
   /** Per-run memo for `git ls-files` (one entry per project dir). */
   gitFilesCache?: GitFilesCache
   /** Per-run memo for derived hashes (package.json bytes + task config). */
@@ -113,6 +123,37 @@ export interface ExecuteArgs {
    * Absent → probe lazily, exactly as today (unstable / unclassified).
    */
   preProbed?: { hash: string; hit: CacheEntry | null }
+  /**
+   * Start the sandbox runtime, on the first task that executes inside one
+   * (run.ts, `prepareSandbox`). Absent when no task in the run declares a
+   * sandbox. A cache hit never calls it: a hit needs no sandbox.
+   */
+  armSandbox?: () => Promise<void>
+  /**
+   * Run-scoped list the miss path appends its output-directory snapshot
+   * request to, taken at run end (run.ts) instead of right after the save:
+   * a directory written milliseconds ago is inside the snapshot's racy
+   * window and would be refused, and the next hit would walk the tree.
+   */
+  outputDirSnapshots?: OutputDirSnapshot[]
+  /** The run's save lane: a miss's cache save runs off the execution slot (save-lane.ts). */
+  deferSave?: (save: () => Promise<void>) => Promise<void>
+  /**
+   * Where a deferred save's `landed` promise is parked by task id, for the
+   * in-flight join (admission.ts): a duplicate of this task in another run
+   * must not probe the cache before the entry is there.
+   */
+  deferredSaves?: Map<string, Promise<void>>
+  /**
+   * `continueMode: 'always'` let this task run although an upstream —
+   * directly or through a chain of successes — failed or aborted. It still
+   * cleans its outputs and runs, and a cache HIT still restores (a hit is a
+   * healthy run's bytes), but its own result is never saved: the key it
+   * derives is the one a healthy run derives (pure-input hashing), while
+   * the bytes were built on a partial tree, so a save here is the next
+   * clean run's stale hit.
+   */
+  taintedUpstream?: boolean
 }
 
 /**
@@ -141,6 +182,9 @@ function executeGroupTask(args: ExecuteArgs): TaskOutcome {
     exitCode: 0,
     durationMs: 0,
     hash: computeGroupHash(args.upstream),
+    // What this group stands for. A dependent expands it to describe the
+    // real tasks in its input closure — see `TaskOutcome.groupUpstream`.
+    groupUpstream: args.upstream,
     wallclockStartNs: wallclockNs,
     wallclockEndNs: wallclockNs,
   }
@@ -155,6 +199,9 @@ function executeGroupTask(args: ExecuteArgs): TaskOutcome {
  * Never reads or writes the cache — the project loader rejects
  * `cache + persistent` at config-load time, so by the time we get
  * here, `cache` is guaranteed undefined.
+ *
+ * Never routed through an executor: a persistent task is local by
+ * construction (its port lives on this machine).
  */
 async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const { node, log } = args
@@ -164,20 +211,39 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
     persistent: NonNullable<ExecConfig['persistent']>
   }
   const effectiveForwardArgs = node.requested ? (args.forwardArgs ?? []) : []
-  const env = taskEnv(node, step)
+  const env = taskEnv(node, step, args.workspaceRoot)
   const wallclockStartNs = process.hrtime.bigint() - args.runStartHrTimeNs
 
   // When readyWhen is set we leave the command untouched so the
   // regex matcher sees the unmodified output. When it's absent the
   // task is "ready on spawn" — we can safely append forwardArgs in
   // the same way runCommand does.
+  const plainCommand =
+    step.persistent.readyWhen !== undefined
+      ? step.command
+      : effectiveForwardArgs.length > 0
+        ? step.command + ' ' + effectiveForwardArgs.map(shellQuote).join(' ')
+        : step.command
+  // A persistent task declaring `exec.sandbox` runs inside it like any
+  // other: the same grants, the same walls. What it cannot have is the
+  // violation REPORT — that reads the trace after the child exits, and a
+  // server exits when the run tears it down. Enforced, not reported.
+  // (Until 2026-09-09 the block was accepted and silently ignored.)
+  let command = plainCommand
+  let bridgeTag: string | undefined
+  if (step.sandbox !== undefined) {
+    await args.armSandbox?.()
+    const sb = await sandboxRequestFor(node, step.sandbox, args.workspaceRoot)
+    const wrapped = await wrapSandboxedCommand({
+      command: plainCommand,
+      cwd: node.projectDir,
+      ...sb,
+    })
+    command = wrapped.wrapped
+    bridgeTag = wrapped.tag
+  }
   const persistentOpts: Parameters<typeof runPersistent>[0] = {
-    command:
-      step.persistent.readyWhen !== undefined
-        ? step.command
-        : effectiveForwardArgs.length > 0
-          ? step.command + ' ' + effectiveForwardArgs.map((s) => JSON.stringify(s)).join(' ')
-          : step.command,
+    command,
     cwd: node.projectDir,
     env,
     onStdout: (chunk) => log.taskStdout(node, chunk),
@@ -195,14 +261,23 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 
   const spawn = runPersistent(persistentOpts)
+  // The host side of a port bridge lives exactly as long as the server:
+  // released on the child's exit, whether the run tore it down or it died.
+  if (bridgeTag !== undefined) {
+    const tag = bridgeTag
+    void spawn.child?.exited?.then(
+      () => releaseBridges(tag),
+      () => releaseBridges(tag),
+    )
+  }
   try {
     await spawn.ready
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
-    // Surface readiness failure on stderr so the user sees what went
-    // wrong; the buffered stdout/stderr already streamed live via the
-    // logger callbacks during spawn.ready.
-    process.stderr.write(`\n[vx] ${node.id}: persistent task failed to become ready: ${message}\n`)
+    // The task's OWN stream, not the process's: the frame is where a
+    // reader looks for why a task failed, and a run with a custom logger
+    // (an embedder, the MCP server) never saw a bare stderr write at all.
+    log.taskStderr(node, `\n[vx] ${node.id}: persistent task failed to become ready: ${message}\n`)
     return {
       node,
       status: 'failed',
@@ -241,8 +316,28 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // on. Output management (clean before exec) keys off writes — so
   // `--no-cache` (all off) leaves the user's tree alone, while `--force`
   // (reads off, writes on) still wipes + repopulates a clean snapshot.
-  const willRead = cfgCacheable && (policy.localRead || policy.remoteRead)
-  const willWrite = cfgCacheable && (policy.localWrite || policy.remoteWrite)
+  // A remote-only task never touches this machine's disk: no probe/restore
+  // (restoring node_modules onto a dev machine is exactly what the field
+  // exists to prevent), no output clean, no local artifact save. Its result
+  // lives in the remote executor's own store.
+  const remoteOnly = args.remoteOnly === true
+  const willRead = !remoteOnly && cfgCacheable && (policy.localRead || policy.remoteRead)
+  const willWrite = !remoteOnly && cfgCacheable && (policy.localWrite || policy.remoteWrite)
+  // `willWrite` governs output hygiene (clean before exec); the save itself
+  // is also withheld from a task downstream of a failure (see `taintedUpstream`).
+  const willSave = willWrite && args.taintedUpstream !== true
+
+  // Retain only what is read back. `cache.save` below is the single consumer
+  // of `result.stdout`, and it runs only when this task will WRITE an entry;
+  // `result.stderr` has no consumer at all (a failing task's stderr reaches
+  // the user through the live `onStderr` callback, and the cache has never
+  // stored stderr — see the v17 artifact format). Both streams are still
+  // drained and still stream chunk-by-chunk to the logger; only the retained
+  // copy is dropped, which for a chatty task is its full byte size in heap.
+  // Deferral is decided at plan time and only ever set for a remote-placed,
+  // eligibility-cleared task; it suppresses this machine's clean AND save.
+  const deferralRequested = args.download === 'deferred'
+  const capture: CaptureConfig = { stdout: willSave, stderr: false }
 
   const outputs = cacheCfg?.outputs.files ?? []
   const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
@@ -295,6 +390,22 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
         })
 
+  // The local no-op half of `exec.remote: 'only'`: no remote executor took
+  // the task, so it succeeds without running. The hash was still computed —
+  // dependents fold it — and the machine's ambient state (node_modules as
+  // installed by the dev) serves dependents exactly as before the field.
+  if (args.remoteOnlyNoop === true) {
+    return {
+      node,
+      status: 'success',
+      exitCode: 0,
+      durationMs: 0,
+      hash,
+      wallclockStartNs: taskStartNs,
+      wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+    }
+  }
+
   const cleanArgs = {
     projectDir: node.projectDir,
     outputs,
@@ -316,27 +427,60 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       }
       // Confirmed stable miss — skip the probe, fall through to run.
     } else {
+      const endProbe = span('cache.get')
       const hit = await cache.get(hash, { taskId: node.id, command: step.command })
+      endProbe()
       if (hit) {
         return restoreHit({ args, hash, hit, cacheOpStart, taskStartNs })
       }
     }
   }
 
-  const env = taskEnv(node, step)
+  const env = taskEnv(node, step, args.workspaceRoot)
   const wallclockStartNs = process.hrtime.bigint() - args.runStartHrTimeNs
 
-  // Sandbox is opt-in per task via `sandbox: {}` (or `sandbox: {...}`)
-  // in the task config. No CLI flag, no workspace inheritance — the
-  // task config is the single source of truth. EXCEPTION: `--verify=inputs`
-  // forces the declared-input baseline sandbox onto every executed, cacheable
-  // task to prove input-completeness (a read outside the declared inputs is a
-  // proof failure, not a task failure — so it flags the RUN via the verdict,
-  // it does not flip the task's own exit code the way a user-declared sandbox
-  // violation does).
-  const userSandbox = cfg.sandbox !== undefined
-  const verifyInputs = args.verify?.inputs === true && willWrite
-  const useSandbox = userSandbox || verifyInputs
+  // Miss path: describe the input set ONCE — the executor gets the values
+  // (what a remote worker must reproduce) and the save below reuses the
+  // captured digest rows for the Tier-3 `entry_inputs` fingerprint, so the
+  // fold runs once here instead of once after the subprocess. The HashCache
+  // memos + gitFilesCache OID map make this a fold + array pushes, no I/O.
+  // A non-cacheable task folds nothing and ships no inputs.
+  const captured: TaskInputComponent[] = []
+  const described = cfgCacheable
+    ? await describeTaskInputs({
+        node,
+        upstream,
+        workspaceRoot: args.workspaceRoot,
+        workspaceFingerprint: args.workspaceFingerprint,
+        cache,
+        forwardArgs: args.forwardArgs,
+        nestedProjectDirs: args.nestedProjectDirs,
+        captureInto: captured,
+        ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+        ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
+      })
+    : undefined
+  const inputs: TaskInputs | undefined = described?.inputs
+  // A declared input set that resolves to NOTHING is the quiet stale hit:
+  // the key stops moving with this project's source and every later run
+  // is a hit. Almost always a glob written against the wrong directory
+  // (`lib/**` in a package that builds `src/`). Said once per miss, on the
+  // run's status line — the task itself succeeds.
+  const declaredInputs = [
+    ...(cacheCfg?.inputs.files ?? []),
+    ...(cacheCfg?.inputs.workspaceFiles ?? []),
+  ]
+  if (inputs !== undefined && declaredInputs.length > 0 && inputs.files.length === 0) {
+    log.status(
+      `[vx] ${node.id}: cache.inputs matched no files (${declaredInputs.join(', ')}) — ` +
+        `the key will not change when this project's source does`,
+    )
+  }
+
+  // Sandbox is opt-in per task via `exec.sandbox: {}` (or `{...}`) in the
+  // task config. No CLI flag, no workspace inheritance — the task config is
+  // the single source of truth, and a violation fails the task (below).
+  const userSandbox = cfg.exec?.sandbox !== undefined
   let violations: SandboxViolation[] = []
 
   // Cache miss path (or caching disabled), up to `1 + retries` attempts.
@@ -344,7 +488,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // an explicit `retries: 0`.
   const maxAttempts = 1 + (step.retries ?? args.retries ?? 0)
   let attempt = 0
-  let result: Awaited<ReturnType<typeof runCommand>>
+  let result: ExecuteResult
   let effectiveExitCode: number
 
   // One task attempt: clean the declared outputs (before EVERY attempt — so a
@@ -352,41 +496,109 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // attempt's partial outputs can't leak into the next; gated on WRITES so a
   // `--no-cache` run leaves the user's tree alone), spawn, and classify the
   // exit (a sandbox violation on a 0 exit → fail; a timeout SIGTERM → the
-  // streamed notice). Shared by the retry loop AND the `--verify` re-run so
-  // the two can never drift on the spawn/clean/classify path.
+  // streamed notice). Shared by every attempt of the retry loop, so they
+  // can never drift on the spawn/clean/classify path.
   async function runAttempt(): Promise<{
-    result: Awaited<ReturnType<typeof runCommand>>
+    result: ExecuteResult
     exitCode: number
   }> {
-    if (willWrite && outputs.length > 0) await cleanOutputs(cleanArgs)
-    if (willWrite && wsOutputs.length > 0) {
+    // A deferred task's outputs are deliberately NOT coming, so wiping the
+    // tree would replace a stale build with nothing at all. The eligibility
+    // gate guarantees no key in this run can see what stays behind, and the
+    // summary names every deferred task so `dist/` is not silently stale.
+    if (willWrite && !deferralRequested && outputs.length > 0) {
+      // Mark the wiped paths, exactly as the workspace twin below does. The
+      // git snapshot still lists them with their committed index OIDs, and
+      // resolveFiles SKIPS its existence probe for any path carrying a
+      // trusted OID — so a declared output the producer deletes and does not
+      // re-create would stay in a same-project consumer's input set, keeping
+      // that consumer's key unchanged while the file is gone from disk.
+      const endClean = span('miss: clean outputs')
+      const cleanedRels = await cleanOutputs(cleanArgs)
+      endClean()
+      args.gitFilesCache?.markOutputsChanged(node.projectDir, cleanedRels)
+    }
+    if (willWrite && !deferralRequested && wsOutputs.length > 0) {
       // Root-anchored deletions can land in other projects' dirs; mark
       // them so stale per-project git snapshots can't survive the wipe.
       const cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
       args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, cleanedWsRels)
     }
     violations = []
-    const res = useSandbox ? await runSandboxedTask() : await runUnsandboxedTask()
-    // Fail-on-violation. macOS's structured violation store lets us turn a
-    // passing exit code into a failure when the task tripped the boundary;
-    // Linux relies on the child failing naturally on ENOENT (violations is
-    // always 0 there, but the task is already exit != 0 if it needed the
-    // missing file). Violations surface via `TaskOutcome.sandboxViolationLines`.
+    const endReq = span('miss: build request')
+    const req = await buildRequest()
+    endReq()
+    // An executor that THROWS produces no captured output, so the task's
+    // frame would print the command and nothing else while the reason went
+    // straight to stderr and scrolled away in a broad run. Put it in the
+    // task's own stream first: the frame is where a reader looks for why a
+    // task failed, and a remote executor's failures are exactly the ones with
+    // no other trace. Rethrown unchanged — the scheduler still classifies it,
+    // and still prints it plainly for a UserError.
+    const endExec = span('miss: execute')
+    const res = await args.executor.execute(req).catch((err: unknown) => {
+      const message = err instanceof Error ? err.message : String(err)
+      log.taskStderr(node, `${message}\n`)
+      throw err
+    })
+    endExec()
+    violations = [...res.violations]
+    // Fail-on-violation, on BOTH platforms: macOS reads SRT's structured
+    // violation store, Linux parses the strace log the sandboxed spawn
+    // writes. (This comment used to claim Linux violations are "always 0"
+    // and that enforcement there rests on the child failing naturally — true
+    // before the strace pass shipped, false since, and the branch below is
+    // live on Linux.) Violations surface via `TaskOutcome.sandboxViolationLines`.
     let code = res.exitCode
-    // A USER-declared sandbox fails the task on any violation (that's its
-    // fail-on-violation contract). A sandbox forced on ONLY by `--verify=inputs`
-    // does NOT — the task ran fine; the incompleteness is surfaced as the
-    // `undeclared-inputs` verdict (which reds the run) so the retry loop
-    // doesn't pointlessly re-run and the task isn't mislabeled failed.
+    // ANY violation fails the task (owner, 2026-09-05). A sandboxed task
+    // declares what it touches; a denial means it touched something else,
+    // and an artifact built while reading — or failing to read — something
+    // the cache key never folded is not a safe thing to replay. A task that
+    // survives the denial is the dangerous case, not the harmless one:
+    // that is precisely the run that succeeds and caches a wrong result.
     if (userSandbox && violations.length > 0 && code === 0) code = 1
+    // A declared sandbox fails the task on any violation — that is its
+    // whole contract. `userSandbox` is the only way a task is sandboxed,
+    // so this reads as "sandboxed and it tripped".
     // A child we SIGTERMed for exceeding the timeout is a genuine failure —
     // stream a clear line so the 143 exit reads as a timeout.
     if (res.timedOut) {
       log.taskStderr(node, `\n[vx] timed out after ${effectiveTimeout}ms — killed (SIGTERM)\n`)
+      // Force a non-zero classification even if the child TRAPPED SIGTERM and
+      // still exited 0 (`trap 'exit 0' TERM`, a common graceful-shutdown
+      // pattern). Without this a timed-out task is classified `success` and its
+      // PARTIAL outputs are cached + replayed forever — the run even reports
+      // green. The timeout is a real, retryable failure; a genuinely-killed
+      // child already reports 143, so this only rewrites the trap-exit-0 case.
+      if (code === 0) code = signalExitCode('SIGTERM')
     }
     return { result: res, exitCode: code }
   }
 
+  // This task is about to run a command HERE, and it missed the cache, so
+  // whatever its dependency closure produced has to actually be on disk.
+  // Producers left deferred are fetched now — once per run, concurrently,
+  // on this task's own worker slot, because they are its real critical
+  // path. A remote-placed task needs nothing: its worker grafts the
+  // upstream bytes by reference. A cache HIT reads no inputs at all.
+  if (args.executor.remote !== true && args.deferred !== undefined) {
+    try {
+      await args.deferred.materializeFor(node)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      log.taskStderr(node, `\n[vx] ${msg}\n`)
+      return {
+        node,
+        status: 'failed',
+        exitCode: 1,
+        durationMs: 0,
+        hash,
+        wallclockStartNs: taskStartNs,
+        wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+      }
+    }
+  }
+
   for (;;) {
     attempt++
     const a = await runAttempt()
@@ -418,297 +630,82 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     )
   }
 
-  async function runUnsandboxedTask(): ReturnType<typeof runCommand> {
-    return runCommand({
-      command: step.command,
-      cwd: node.projectDir,
-      env,
-      forwardArgs: effectiveForwardArgs,
-      onStdout: (chunk) => log.taskStdout(node, chunk),
-      onStderr: (chunk) => log.taskStderr(node, chunk),
-      ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
-      ...(effectiveTimeout !== undefined ? { timeoutMs: effectiveTimeout } : {}),
-    })
-  }
-
-  async function runSandboxedTask(): ReturnType<typeof runCommand> {
-    // Baseline allowRead = resolved cache.inputs.files (absolute paths)
-    // Baseline allowWrite = static prefix of every cache.outputs.files glob
-    // Baseline denyRead = the workspace root, so any read outside the
-    //   project's declared inputs trips the deny boundary.
-    // The user's sandbox block extends each list with explicit additions.
-    const resolved = await resolveInputs({
-      projectDir: node.projectDir,
+  async function buildRequest(): Promise<ExecuteRequest> {
+    const base: ExecuteRequest = {
+      taskId: node.id,
       workspaceRoot: args.workspaceRoot,
-      envSource: process.env,
-      inputs: cacheCfg?.inputs,
-      ownOutputs: outputs,
-      ownWorkspaceOutputs: wsOutputs,
-      nestedProjectDirs: args.nestedProjectDirs,
-      ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
-      ...(args.hashCache !== undefined
-        ? {
-            runtimeCache: args.hashCache.runtime,
-            workspaceRuntimeCache: args.hashCache.workspaceRuntime,
-          }
-        : {}),
-    })
-    const baseAllowWrite = [
-      ...outputs.map((g) => path.join(node.projectDir, staticPrefix(g))),
-      // Workspace outputs anchor their write prefixes at the root.
-      ...wsOutputs.map((g) => path.join(args.workspaceRoot, staticPrefix(g))),
-    ]
-    // bwrap can't --bind a non-existent host path; the bind silently
-    // becomes a no-op (or a tmpfs that evaporates on exit), and writes
-    // to the path appear to succeed inside the sandbox but never land
-    // on the host. Pre-create every output path so the binds resolve
-    // to real fs entries: globbed outputs (`dist/**`) become empty
-    // dirs; literal outputs (`out.txt`) become empty files.
-    await prepareOutputsForBind(node.projectDir, outputs)
-    await prepareOutputsForBind(args.workspaceRoot, wsOutputs)
-    // Output paths are read+write — a task that declares `dist/**` as
-    // output expects to read what it just wrote (e.g. `touch dist/x`
-    // stats the file; `tsc --incremental` re-reads .tsbuildinfo). This
-    // isn't magic — the user already declared these paths; we're just
-    // honoring the natural read-write symmetry of an output directory.
-    const sandboxResult = await runSandboxed({
       command: step.command,
+      forwardArgs: effectiveForwardArgs,
       cwd: node.projectDir,
       env,
-      forwardArgs: effectiveForwardArgs,
+      envDefine: step.env?.define ?? {},
+      capture,
       onStdout: (chunk) => log.taskStdout(node, chunk),
       onStderr: (chunk) => log.taskStderr(node, chunk),
       ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
       ...(effectiveTimeout !== undefined ? { timeoutMs: effectiveTimeout } : {}),
-      baseAllowRead: [...resolved.files, ...baseAllowWrite],
-      baseAllowWrite,
-      baseDenyRead: [args.workspaceRoot],
-      config: resolveSandboxConfig(cfg.sandbox ?? {}, node.projectDir),
-    })
-    violations = sandboxResult.violations
-    const { violations: _v, ...runResult } = sandboxResult
-    return runResult
+      ...(inputs !== undefined ? { inputs } : {}),
+      ...(cfgCacheable ? { cacheKey: hash } : {}),
+      ...(remoteOnly ? { remoteOnly: true } : {}),
+      ...(deferralRequested ? { download: 'deferred' as const } : {}),
+      // `--force`/`--no-cache` reach a remote executor's private record
+      // through this flag — the policy gates above only cover vx's OWN cache.
+      ...(cfgCacheable && !(policy.localRead || policy.remoteRead) ? { refresh: true } : {}),
+      outputs: { files: outputs, workspaceFiles: wsOutputs },
+    }
+    if (!userSandbox) return base
+    await args.armSandbox?.()
+    return { ...base, sandbox: await sandboxRequestFor(node, step.sandbox!, args.workspaceRoot) }
   }
 
   const wallclockEndNs = process.hrtime.bigint() - args.runStartHrTimeNs
 
-  // Attempt-1 output fingerprint for `--verify` (content OIDs by output key),
-  // captured inside the save block while the tree is attempt-1's.
-  let verifyFp1: Map<string, string> | undefined
-
-  if (effectiveExitCode === 0 && willWrite) {
-    const outputFiles = await resolveOutputs({
-      projectDir: node.projectDir,
-      outputs,
-      nestedProjectDirs: args.nestedProjectDirs,
-    })
-    const wsOutputFiles = await resolveWorkspaceOutputs({
-      workspaceRoot: args.workspaceRoot,
-      outputs: wsOutputs,
-    })
-    // Tier-3 input fingerprint: capture the cache-key components for
-    // THIS entry, persisted with the entry inside `cache.save`'s
-    // transaction. Miss path only — the warm/hit path never reaches
-    // here, so it allocates no array and pushes nothing. The HashCache
-    // memos + gitFilesCache OID map make this second `computeTaskHash`
-    // a fold + array pushes (no re-stat / re-hash I/O), negligible next
-    // to the subprocess this task just ran.
-    const captured: TaskInputComponent[] = []
-    await computeTaskHash({
+  if (effectiveExitCode === 0 && willSave && deferralRequested) {
+    // The outputs never landed here: no artifact, no rows. A partial local
+    // record (a row with no artifact) is exactly the corrupt-entry shape
+    // `restoreOutputs` refuses, so writing none is the only clean answer.
+    // The closure is what a later local consumer — or a later eager run —
+    // pulls the bytes with.
+    const materialize = result.outputs?.kind === 'deferred' ? result.outputs.materialize : undefined
+    if (materialize !== undefined) {
+      args.deferred?.register(node.id, {
+        materialize,
+        hash,
+        entry: {
+          taskId: node.id,
+          command: step.command,
+          durationMs: result.durationMs,
+          stdout: result.stdout,
+          ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
+          ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
+        },
+      })
+    }
+  } else if (effectiveExitCode === 0 && willSave) {
+    const { landed } = await saveMiss({
       node,
-      upstream,
-      workspaceRoot: args.workspaceRoot,
-      workspaceFingerprint: args.workspaceFingerprint,
+      hash,
       cache,
-      forwardArgs: args.forwardArgs,
+      log,
+      workspaceRoot: args.workspaceRoot,
       nestedProjectDirs: args.nestedProjectDirs,
-      captureInto: captured,
-      ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
-      ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
-    })
-    await cache.save({
-      hash,
-      projectDir: node.projectDir,
-      outputFiles,
-      ...(wsOutputFiles.length > 0
-        ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: args.workspaceRoot }
-        : {}),
-      inputComponents: captured.map((c) => ({ entryHash: hash, ...c })),
-      entry: {
-        taskId: node.id,
-        command: step.command,
-        exitCode: effectiveExitCode,
-        durationMs: result.durationMs,
-        stdout: result.stdout,
-      },
+      gitFilesCache: args.gitFilesCache,
+      outputs,
+      wsOutputs,
+      captured,
+      command: step.command,
+      durationMs: result.durationMs,
+      stdout: result.stdout,
+      ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
+      ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
+      outputDirSnapshots: args.outputDirSnapshots,
+      deferSave: args.deferSave,
     })
-    // --verify: fingerprint attempt 1's outputs by CONTENT (raw bytes, never
-    // the mtime+size memo). The determinism re-run below compares against it,
-    // and the fingerprinting modes (`--verify`/`=all`/`=fingerprint`) fold it
-    // into the shipped `outputFp` — the cross-machine diff feed.
-    //
-    // Gate on DECLARED outputs (`outputs`/`wsOutputs` globs), not the
-    // RESOLVED file count: a task that declares `dist/**` but produces zero
-    // files this run must still ship the EMPTY tree, or the cross-machine
-    // diff can't pair it against a platform where the same glob DID match —
-    // a platform-conditional glob producing nothing on one OS is exactly
-    // the divergence Phase 4 exists to catch. The empty fold is well-defined
-    // (a fixed sentinel tree), so two both-empty platforms stay silent.
-    if (
-      (args.verify?.fingerprint || args.verify?.determinism) &&
-      outputs.length + wsOutputs.length > 0
-    ) {
-      verifyFp1 = await hashOutputTree(
-        outputRefs(node.projectDir, outputFiles, args.workspaceRoot, wsOutputFiles),
-      )
-    }
-    // This task just wrote outputs to the project's tree. Record the
-    // exact declared-output paths as changed (same as the cache-hit
-    // restore path) instead of dropping the whole snapshot: a downstream
-    // same-project task then re-spawns git ONLY when its input globs can
-    // actually see one of these paths. On a 1000-package cold run this
-    // removes ~one synchronous `git ls-files` spawn per project (the
-    // single largest cold-run cost — 22% of CPU in profiling). Contract:
-    // outputs must be declared — an executed task that writes files
-    // outside `cache.outputs.files` which a same-project downstream task
-    // reads is undeclared behavior (the restore path already assumes it).
-    if (outputFiles.length > 0) {
-      args.gitFilesCache?.markOutputsChanged(
-        node.projectDir,
-        outputFiles.map((p) => path.relative(node.projectDir, p).split(path.sep).join('/')),
-      )
-    }
-    // Declared workspace outputs may have landed inside OTHER
-    // projects' dirs (no-boundary escape hatch) — mark the exact
-    // paths against every partition that can see them.
-    if (wsOutputFiles.length > 0) {
-      args.gitFilesCache?.markWorkspaceOutputsChanged(
-        args.workspaceRoot,
-        wsOutputFiles.map((f) => path.relative(args.workspaceRoot, f).split(path.sep).join('/')),
-      )
-    }
-    // The workspace-wide partition (when one exists) spans this
-    // project's subtree, so it inherits the same "undeclared writes
-    // are only visible to git" rule as the project drop above.
-    if (outputFiles.length + wsOutputFiles.length > 0) {
-      args.gitFilesCache?.invalidateWorkspacePartition()
-    }
+    args.deferredSaves?.set(node.id, landed)
   }
 
-  // Snapshot the WINNING attempt's sandbox violations before the verify re-run
-  // (which reuses `runAttempt` and would clobber `violations`); the outcome
-  // must report attempt 1's, not the re-run's.
   const finalViolations = violations
 
-  let verify: VerifyVerdict | undefined
-
-  // Input-completeness verification (`vx run --verify=inputs` / `=all`, Phase 2).
-  // The task ran under the forced declared-input baseline sandbox. A read of a
-  // workspace path outside the declared inputs proves `cache.inputs` is
-  // incomplete — a future hit could serve stale bytes when that undeclared file
-  // changes. This reds the run via the verdict (see run.ts `ok`), not the task's
-  // own exit code. Checked FIRST: if the inputs are wrong, there's no point
-  // re-running for determinism — fix the inputs (which changes the key) first.
-  if (verifyInputs) {
-    if (finalViolations.length > 0) {
-      verify = {
-        kind: 'undeclared-inputs',
-        paths: undeclaredInputPaths(finalViolations, args.workspaceRoot),
-      }
-    } else if (effectiveExitCode === 0 && !args.verify?.determinism) {
-      // Inputs-only run, inputs complete. (`=all` falls through to the stronger
-      // determinism verdict below.)
-      verify = { kind: 'proven-complete' }
-    }
-  }
-
-  // Determinism verification (`vx run --verify` / `=all`). The task executed and
-  // saved; re-run it fresh and content-compare its outputs against attempt 1. A
-  // divergence proves the task is non-hermetic — its cache entry would replay
-  // arbitrary past bytes. The re-run NEVER saves; the canonical (attempt-1)
-  // bytes are restored afterward so disk == the cache regardless of verdict.
-  if (
-    verify === undefined &&
-    args.verify?.determinism &&
-    effectiveExitCode === 0 &&
-    willWrite &&
-    !result.timedOut
-  ) {
-    // Determinism verdict is keyed on RESOLVED outputs (unchanged): a task
-    // that declares outputs but produced none this run has nothing to
-    // content-compare, so it stays `no-outputs` with no re-run — even though
-    // `verifyFp1` is now the (empty) declared-outputs fingerprint that
-    // `--verify=fingerprint` ships for the cross-machine diff. `verifyFp1`
-    // is keyed by resolved output file, so an empty map means "declared but
-    // produced nothing" — the in-scope stand-in for the resolved-zero count.
-    if (verifyFp1 === undefined || verifyFp1.size === 0) {
-      verify = { kind: 'no-outputs' } // cacheable but nothing to replay (e.g. lint)
-    } else {
-      const rerun = await runAttempt()
-      if (rerun.exitCode !== 0 || rerun.result.timedOut) {
-        verify = { kind: 'rerun-failed', exitCode: rerun.exitCode }
-      } else {
-        const fp2 = await hashOutputTree(
-          outputRefs(
-            node.projectDir,
-            await resolveOutputs({
-              projectDir: node.projectDir,
-              outputs,
-              nestedProjectDirs: args.nestedProjectDirs,
-            }),
-            args.workspaceRoot,
-            await resolveWorkspaceOutputs({
-              workspaceRoot: args.workspaceRoot,
-              outputs: wsOutputs,
-            }),
-          ),
-        )
-        verify = classifyDeterminism(
-          diffOutputTrees(verifyFp1, fp2),
-          args.verify.allow.has(node.id),
-        )
-      }
-      // Put attempt 1's saved bytes back so disk == the cached artifact
-      // REGARDLESS of the verdict. Mirror the restoreHit sequence exactly:
-      // clean the declared globs FIRST (a nondeterministic re-run may have
-      // written a stray filename the restore would never overwrite), then
-      // restore, then record the exact changed paths so a downstream
-      // same-project task's git snapshot can't go stale. fp1's keys ARE
-      // attempt 1's saved rels (bare project rels + workspace-outputs/-
-      // prefixed ws rels — the artifact namespace).
-      let cleanedRels: string[] = []
-      let cleanedWsRels: string[] = []
-      if (outputs.length > 0) cleanedRels = await cleanOutputs(cleanArgs)
-      if (wsOutputs.length > 0) cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
-      await cache.restoreOutputs(
-        hash,
-        node.projectDir,
-        wsOutputs.length > 0 ? args.workspaceRoot : undefined,
-      )
-      const savedKeys = [...verifyFp1.keys()]
-      if (outputs.length > 0) {
-        args.gitFilesCache?.markOutputsChanged(node.projectDir, [
-          ...cleanedRels,
-          ...savedKeys.filter((k) => !k.startsWith(WORKSPACE_OUTPUT_PREFIX)),
-        ])
-      }
-      if (wsOutputs.length > 0) {
-        args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, [
-          ...cleanedWsRels,
-          ...savedKeys
-            .filter((k) => k.startsWith(WORKSPACE_OUTPUT_PREFIX))
-            .map((k) => k.slice(WORKSPACE_OUTPUT_PREFIX.length)),
-        ])
-      }
-    }
-  }
-
-  // Cross-machine diff feed: ship attempt 1's fingerprint (the SAVED bytes —
-  // the determinism re-run above never clobbers verifyFp1) so a connected
-  // serve can pair it with other platforms' reports for the same cache key.
-  const outputFp =
-    args.verify?.fingerprint && verifyFp1 !== undefined ? foldFingerprint(verifyFp1) : undefined
-
   return {
     node,
     status: effectiveExitCode === 0 ? 'success' : 'failed',
@@ -718,10 +715,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     ...(attempt > 1 ? { attempts: attempt } : {}),
     ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
     ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
+    ...(result.where !== undefined ? { where: result.where } : {}),
+    ...(deferralRequested && result.outputs?.kind === 'deferred'
+      ? { outputs: 'deferred' as const }
+      : {}),
     wallclockStartNs,
     wallclockEndNs,
-    ...(verify !== undefined ? { verify } : {}),
-    ...(outputFp !== undefined ? { outputFp } : {}),
     ...(finalViolations.length > 0
       ? {
           sandboxViolations: finalViolations.length,
@@ -731,209 +730,35 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 }
 
-export interface RestoreHitArgs {
-  args: ExecuteArgs
-  hash: string
-  hit: CacheEntry
-  /** `performance.now()` when the cache op (probe) started — the
-   *  user-perceived restore duration is measured from here. */
-  cacheOpStart: number
-  /** ns offset from run start for the outcome's wallclock window. */
-  taskStartNs: bigint
-}
-
 /**
- * Materialize a confirmed cache hit: decide skip-restore, clean +
- * restore declared outputs, mark the exact changed paths so downstream
- * same-project tasks needn't re-spawn git, replay stored stdout, and
- * build the cache-hit `TaskOutcome`. Extracted from `executeCachedTask`
- * so the local short-circuit can restore a stable-key hit ahead of the
- * schedule using the IDENTICAL logic — there is one restore path, not
- * two that could drift.
- */
-export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome> {
-  const { args, hash, hit, cacheOpStart, taskStartNs } = restore
-  const { node, log } = args
-  const cacheCfg: CacheConfig | undefined = node.config.cache
-  const outputs = cacheCfg?.outputs.files ?? []
-  const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
-  const anyOutputs = outputs.length > 0 || wsOutputs.length > 0
-  const cleanArgs = {
-    projectDir: node.projectDir,
-    outputs,
-    nestedProjectDirs: args.nestedProjectDirs,
-  }
-  const wsCleanArgs = { workspaceRoot: args.workspaceRoot, outputs: wsOutputs }
-
-  // "Tree is already current" short-circuit — skip cleanOutputs
-  // + restoreOutputs when the on-disk state matches what this
-  // entry recorded at save time. Integrity-preserving: we
-  // require BOTH that the output-glob walk yields exactly the
-  // expected paths (no strays, no missing) AND that every file's
-  // (size, mode, mtime) matches the stored fingerprint. Any
-  // divergence falls through to a real clean + restore.
-  //
-  // The output-file fingerprints can't be batch-loaded at
-  // prepareRun time — non-leaf task hashes depend on upstream
-  // outputs that haven't been written yet, so hashes are
-  // necessarily computed mid-run. We do one extra SELECT per
-  // cache hit here. Still beats reading the manifest from the
-  // tar (decompress + parse) at the same point.
-  let skipRestore = false
-  if (anyOutputs) {
-    const expected = args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
-    if (expected.length > 0) {
-      // Two namespaces in the rows: bare rels are project outputs,
-      // `workspace-outputs/<rel>` rows anchor at the workspace root.
-      const projExpected = expected.filter((e) => !e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
-      const wsExpected = expected
-        .filter((e) => e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
-        .map((e) => ({ ...e, path: e.path.slice(WORKSPACE_OUTPUT_PREFIX.length) }))
-      const actualAbs = await resolveOutputs({
-        projectDir: node.projectDir,
-        outputs,
-        nestedProjectDirs: args.nestedProjectDirs,
-      })
-      const actualWsAbs = await resolveWorkspaceOutputs({
-        workspaceRoot: args.workspaceRoot,
-        outputs: wsOutputs,
-      })
-      const setsMatch = (
-        actual: readonly string[],
-        exp: ReadonlyArray<{ path: string }>,
-      ): boolean => {
-        const expSet = new Set(exp.map((e) => e.path))
-        return actual.length === expSet.size && actual.every((r) => expSet.has(r))
-      }
-      const actualRels = actualAbs.map((p) =>
-        path.relative(node.projectDir, p).split(path.sep).join('/'),
-      )
-      const actualWsRels = actualWsAbs.map((p) =>
-        path.relative(args.workspaceRoot, p).split(path.sep).join('/'),
-      )
-      if (setsMatch(actualRels, projExpected) && setsMatch(actualWsRels, wsExpected)) {
-        skipRestore =
-          (await args.cache.isOutputsCurrent(node.projectDir, projExpected)) &&
-          (await args.cache.isOutputsCurrent(args.workspaceRoot, wsExpected))
-      }
-    }
-  }
-  if (!skipRestore) {
-    let cleanedRels: string[] = []
-    let cleanedWsRels: string[] = []
-    if (outputs.length > 0) cleanedRels = await cleanOutputs(cleanArgs)
-    if (wsOutputs.length > 0) cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
-    await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot)
-    // Restored outputs changed the project's tree — but on this
-    // path we know the EXACT changed paths (wiped declared
-    // outputs + the artifact's files). Record them instead of
-    // dropping the snapshot; downstream same-project tasks only
-    // re-spawn git when their input globs can actually see one of
-    // these paths. The cache-miss save path keeps the
-    // unconditional drop (an executed task may write undeclared
-    // files only git can see).
-    if (outputs.length > 0) {
-      args.gitFilesCache?.markOutputsChanged(node.projectDir, [
-        ...cleanedRels,
-        ...hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX)),
-      ])
-    }
-    if (wsOutputs.length > 0) {
-      args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, [
-        ...cleanedWsRels,
-        ...hit.outputFiles
-          .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
-          .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length)),
-      ])
-    }
-  }
-  if (hit.stdout) log.taskStdout(node, hit.stdout)
-  const status =
-    hit.exitCode !== 0 ? 'failed' : hit.source === 'remote' ? 'cache-hit-remote' : 'cache-hit'
-  // `restored` distinguishes "we just wrote files to disk" from
-  // "disk already matched the cached snapshot". Drives the
-  // "up-to-date" vs "local-cache" / "remote-cache" label in the
-  // framed block. Only meaningful when at least one output was
-  // declared — no-outputs tasks never materialize anything, so
-  // they're vacuously up-to-date.
-  const restored = !skipRestore && anyOutputs
-  return {
-    node,
-    status,
-    exitCode: hit.exitCode,
-    durationMs: Math.round(performance.now() - cacheOpStart),
-    hash,
-    restored,
-    // Under `--verify`, a cache hit didn't execute this run — so it wasn't
-    // proven. Flag it `not-verified` (use `--force` to re-execute + verify).
-    ...(args.verify?.determinism || args.verify?.inputs
-      ? { verify: { kind: 'not-verified' as const } }
-      : {}),
-    wallclockStartNs: taskStartNs,
-    wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
-  }
-}
-
-/**
- * Ensure each declared output path exists on the host as either an
- * empty file (for literal output specs) or a directory (for globbed
- * specs) so bwrap's --bind can find a real fs entry to mount. Without
- * this, writes inside the sandbox to a non-existent allowWrite path
- * silently disappear (bwrap creates a tmpfs that evaporates on exit).
+ * Build the child-process env for one task. Same arguments at every call site
+ * (persistent + cached). Two `node_modules/.bin` directories are prepended to
+ * PATH: the project's own, then the WORKSPACE ROOT's. Never a sibling
+ * project's, and never an arbitrary ancestor — that is the project-isolation
+ * rule, and the root is not a sibling.
  *
- * `cleanOutputs` ran just before this in the cache-enabled path, so
- * we know any stale content was wiped; what's left is to materialize
- * the empty skeleton.
- */
-async function prepareOutputsForBind(
-  projectDir: string,
-  outputs: readonly string[],
-): Promise<void> {
-  for (const g of outputs) {
-    const hasWildcard = /[*?[\]]/.test(g)
-    if (hasWildcard) {
-      const abs = path.join(projectDir, staticPrefix(g))
-      await mkdir(abs, { recursive: true })
-    } else {
-      const abs = path.join(projectDir, g)
-      await mkdir(path.dirname(abs), { recursive: true })
-      const f = Bun.file(abs)
-      if (!(await f.exists())) await Bun.write(abs, '')
-    }
-  }
-}
-
-/**
- * Return the longest prefix of a glob that contains no wildcards. Used
- * to derive an allowWrite path from each `cache.outputs.files` entry:
- * `dist/**` → `dist`, `build/output.js` → `build/output.js`, `**` →
- * `.` (the project dir itself). bwrap binds at the directory level so
- * a file path covers writes to that file; a dir path covers writes
- * anywhere underneath.
- */
-function staticPrefix(glob: string): string {
-  const wildcardIdx = glob.search(/[*?[\]]/)
-  if (wildcardIdx === -1) return glob
-  // Trim back to the last separator before the wildcard so we keep
-  // only complete path components (e.g. `dist/sub-**` → `dist`, not
-  // `dist/sub-`).
-  const head = glob.slice(0, wildcardIdx)
-  const lastSep = head.lastIndexOf('/')
-  if (lastSep === -1) return '.'
-  return head.slice(0, lastSep) || '/'
-}
-
-/**
- * Build the child-process env for one task. Same arguments at every
- * call site (persistent + cached); the project's own
- * `node_modules/.bin` is prepended to PATH — never the workspace
- * root's, never sibling projects' (per the project-isolation rule).
+ * The root entry is where a monorepo's shared tooling actually lives: declare
+ * `oxlint` once as a root devDependency and every member's `.bin` is empty of
+ * it. Without the root on PATH such a task exits 127, which is what this
+ * repo's own gate did the moment core stopped BEING the root and the two
+ * paths stopped coinciding. It also removes a divergence that mattered more:
+ * the REAPI executor already rebuilds both entries in the action's command,
+ * so a task that resolved on a worker failed on the machine that submitted
+ * it. npm/pnpm/yarn all put the ancestor chain on PATH for the same reason.
  */
-function taskEnv(node: TaskNode, step: ExecConfig): NodeJS.ProcessEnv {
-  return buildIsolatedEnv({
+function taskEnv(node: TaskNode, step: ExecConfig, workspaceRoot: string): NodeJS.ProcessEnv {
+  const bins = [path.join(node.projectDir, 'node_modules', '.bin')]
+  const rootBin = path.join(workspaceRoot, 'node_modules', '.bin')
+  // Identical when the root is itself a project — dedupe rather than list it
+  // twice, so PATH reads the same either way.
+  if (rootBin !== bins[0]) bins.push(rootBin)
+  const env = buildIsolatedEnv({
     passThrough: step.env?.passThrough ?? [],
     define: step.env?.define ?? {},
     source: process.env,
-    binPaths: [path.join(node.projectDir, 'node_modules', '.bin')],
+    binPaths: bins,
   })
+  env[VX_RUN_WORKSPACE_ENV] = workspaceRoot
+  env[VX_RUN_TASK_ENV] = node.id
+  return env
 }