@vzn/vx 0.0.18 → 0.0.22

package/src/orchestrator/execute-task.ts

@@ -1,42 +1,56 @@
-import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import type { ExecConfig, TaskConfig, CacheConfig } from '../config.js'
 import {
+  ArtifactVanishedError,
   type CacheEntry,
   type CacheLayer,
   type CachePolicy,
   cleanOutputs,
   cleanWorkspaceOutputs,
+  type OutputStamp,
+  ownOutputsSince,
+  stampOutputs,
   FULL_CACHE_POLICY,
   type GitFilesCache,
-  resolveInputs,
-  resolveOutputs,
-  resolveWorkspaceOutputs,
-  WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import {
   buildIsolatedEnv,
+  VX_RUN_TASK_ENV,
+  VX_RUN_WORKSPACE_ENV,
   runPersistent,
-  resolveSandboxConfig,
   shellQuote,
+  releaseBridges,
+  wrapSandboxedCommand,
   signalExitCode,
   type CaptureConfig,
   type ExecuteRequest,
+  assertExecuteResult,
   type ExecuteResult,
   type SandboxViolation,
   type TaskExecutor,
   type TaskInputs,
+  PersistentReadyError,
 } from '../exec/index.js'
-import { isGroupTask, type TaskNode, type TaskOutcome, type VerifyVerdict } from '../graph/index.js'
+import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { relPosix, span } from '../util/index.js'
 import {
-  classifyDeterminism,
-  diffOutputTrees,
-  foldFingerprint,
-  hashOutputTree,
-  outputRefs,
-  undeclaredInputPaths,
-} from './verify.js'
-import { span, staticPrefix, wholeSubtreePrefixes } from '../util/index.js'
+  mayWriteFingerprint,
+  type Placeholder,
+  placeholderSweeper,
+  reachedWithheld,
+  sandboxRequestFor,
+  sweepPlaceholders,
+  undeclaredWriteReach,
+  untouchedPlaceholderLine,
+  type WithheldLink,
+  withheldLinkLine,
+} from './sandbox-request.js'
+import { markUnsaved, saveMiss, type OutputDirSnapshot } from './miss-save.js'
+import type { FingerprintWatch } from './fingerprint-watch.js'
+import { restoreHit } from './hit-restore.js'
+import { shellVerdict } from './shell-verdict.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 {
@@ -44,8 +58,10 @@ import {
   computeTaskHash,
   describeTaskInputs,
   type HashCache,
+  movedInput,
   type TaskInputComponent,
 } from './task-hash.js'
+import { getContext } from './remote-prefetch.js'
 
 export interface ExecuteArgs {
   node: TaskNode
@@ -86,6 +102,13 @@ export interface ExecuteArgs {
   nestedProjectDirs: string[]
   /** Anchor for hrtime spans across all tasks in this run. */
   runStartHrTimeNs: bigint
+  /**
+   * The run's stop (a process signal or the embedder's abort). An attempt
+   * that ends while it is aborted is `aborted`, whatever its exit: a task
+   * that traps the forwarded SIGINT and exits 0 did not finish on its own
+   * terms (item 962).
+   */
+  stopSignal?: AbortSignal
   /**
    * Registry the orchestrator owns. For each persistent task we
    * spawn, we stash the subprocess handle here so the orchestrator
@@ -112,25 +135,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). */
@@ -147,6 +151,55 @@ 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>
+  /**
+   * The run's keyed-set lookup (keyed-projects.ts): the project directories
+   * a task's key answers for. A sandboxed task that declares `cache` is
+   * granted a linked workspace package only when it is in this set.
+   */
+  keyedProjects: (node: TaskNode) => ReadonlySet<string>
+  /**
+   * 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
+  /**
+   * Whether a task has rewritten a file the workspace fingerprint folded
+   * since the run read it (fingerprint-watch.ts): past that, no key taken
+   * on the old digest is probed or saved.
+   */
+  fingerprintWatch?: FingerprintWatch
+  /**
+   * No task in the run depends on this one, so none is ordered after it to
+   * read what it wrote: a miss that saves nothing marks nothing (the output
+   * walk cost 1,000 read-only misses 1.62 → 1.78 s, item 750).
+   */
+  noDependants?: true
 }
 
 /**
@@ -211,18 +264,56 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // 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
+  let signalChannel = false
+  // The empty files the request pre-created for a literal write grant; a
+  // server that never writes one gets it taken back when it exits, and a
+  // server that dies before readiness is told the directory spelling — the
+  // same trap and the same answer as a one-shot task's (sandbox-request.ts).
+  let placeholders: Placeholder[] = []
+  if (step.sandbox !== undefined) {
+    await args.armSandbox?.()
+    // A persistent task never declares `cache` (the loader refuses it), so
+    // it keeps the whole linked grant: no key of its can be stale.
+    const sb = await sandboxRequestFor(
+      node,
+      step.sandbox,
+      args.workspaceRoot,
+      undefined,
+      args.nestedProjectDirs,
+    )
+    placeholders = sb.placeholders
+    const wrapped = await wrapSandboxedCommand({
+      command: plainCommand,
+      cwd: node.projectDir,
+      env,
+      ...sb.sandbox,
+      server: true,
+    })
+    command = wrapped.wrapped
+    bridgeTag = wrapped.tag
+    signalChannel = wrapped.forwardsSignals
+  }
   const persistentOpts: Parameters<typeof runPersistent>[0] = {
-    command:
-      step.persistent.readyWhen !== undefined
-        ? step.command
-        : effectiveForwardArgs.length > 0
-          ? step.command + ' ' + effectiveForwardArgs.map(shellQuote).join(' ')
-          : step.command,
+    command,
     cwd: node.projectDir,
     env,
     onStdout: (chunk) => log.taskStdout(node, chunk),
     onStderr: (chunk) => log.taskStderr(node, chunk),
     ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
+    ...(signalChannel ? { signalChannel } : {}),
   }
   if (step.persistent.readyWhen !== undefined) {
     persistentOpts.readyWhen = step.persistent.readyWhen
@@ -235,25 +326,61 @@ 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.
+  // A placeholder the server never wrote goes back the same way.
+  // ONE sweep, shared by the exit handler and the readiness failure below
+  // — whichever asks second must get the SAME list. A second sweep cannot
+  // produce it: the first one's `rm` already happened, so the file is gone
+  // and `sweepPlaceholders` skips it. Collecting both lists and unioning
+  // them does not close that, because the union only covers an exit
+  // handler that FINISHED; one still between its `rm` and its return has
+  // published nothing yet, and the readiness path then reports no
+  // placeholder at all. The failure then says only "File exists", which is
+  // the message the hint exists to explain (seen under the gate's parallel
+  // load, and reproduced deterministically by delaying each side, item 450).
+  const sweptUntouched = placeholderSweeper(placeholders)
+  if (bridgeTag !== undefined || placeholders.length > 0) {
+    const tag = bridgeTag
+    const onExit = async (): Promise<void> => {
+      if (tag !== undefined) releaseBridges(tag)
+      await sweptUntouched()
+    }
+    // A spawn that failed has no child to wait on: release now, or the
+    // tag would hold the sandbox's reset for the rest of the process.
+    if (spawn.child === undefined) void onExit()
+    else void spawn.child.exited.then(onExit, onExit)
+  }
   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`)
+    // The server is dead or being torn down, so the sweep on its exit may
+    // already be running: ask the shared one rather than starting a second.
+    for (const p of await sweptUntouched()) {
+      log.taskStderr(node, `${untouchedPlaceholderLine(node.projectDir, p)}\n`)
+    }
+    // The reason rides the outcome (every label reads it), and a child that
+    // exited before ready keeps its own exit code rather than a made-up 1.
+    const ready = err instanceof PersistentReadyError ? err : undefined
     return {
       node,
       status: 'failed',
-      exitCode: 1,
+      exitCode: ready?.exitCode ?? 1,
       durationMs: spawn.readyMs(),
+      ...(ready !== undefined ? { notReady: ready.reason } : {}),
       wallclockStartNs,
       wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
     }
   }
 
   args.persistentRegistry?.set(node.id, spawn.child)
+  forgetUndeclaredWrites(args, undeclaredWriteReach(node, args.workspaceRoot))
+  if (mayWriteFingerprint(node, args.workspaceRoot)) args.fingerprintWatch?.wrote()
   return {
     node,
     status: 'success',
@@ -288,6 +415,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   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;
@@ -299,7 +429,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // 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: willWrite, stderr: false }
+  const capture: CaptureConfig = { stdout: willSave, stderr: false }
 
   const outputs = cacheCfg?.outputs.files ?? []
   const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
@@ -357,20 +487,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // 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) {
-    // Under a `--verify` proof the noop must be REPORTED, not silent: there
-    // is no execution to sandbox or re-run, so the proof cannot cover this
-    // task (the eleventh-wave residual — a silently unverified task reads
-    // as a green proof over ground the proof never touched).
-    const wantsProof =
-      args.verify !== undefined &&
-      (args.verify.inputs || args.verify.determinism || args.verify.fingerprint)
     return {
       node,
       status: 'success',
       exitCode: 0,
       durationMs: 0,
       hash,
-      ...(wantsProof ? { verify: { kind: 'unverifiable-remote-only' as const } } : {}),
       wallclockStartNs: taskStartNs,
       wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
     }
@@ -382,6 +504,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     nestedProjectDirs: args.nestedProjectDirs,
   }
   const wsCleanArgs = { workspaceRoot: args.workspaceRoot, outputs: wsOutputs }
+  // An ADDITIVE task (its outputs overlap an upstream's, with the edge that
+  // orders them; item 588) does not clean by glob — the glob selects the
+  // upstream's files it adds beside. Its outputs are stamped once before
+  // the first attempt, and after a 0 exit its own set is what the run
+  // added or changed against that stamp. Stale files of its own from an
+  // earlier run are its command's to clean, as they are under Turbo.
+  const additive = (node.addsToOutputsOf?.length ?? 0) > 0
+  let stampedBefore: ReadonlyMap<string, OutputStamp> | undefined
 
   // Cache lookup. On hit, time the user-perceived restore op
   // (clean+restore+log-replay) — that's what the framed-block footer
@@ -391,17 +521,37 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // to the run path as a known stable miss. No second cache.get.
   if (willRead) {
     const cacheOpStart = performance.now()
+    // A hit whose artifact was removed after the probe (a prune, another
+    // workspace's retention on a shared cache directory) is a miss. The
+    // restore has wiped the declared outputs by then; the run path cleans
+    // them again and the task writes them.
+    const restoreOrMiss = async (hit: CacheEntry): Promise<TaskOutcome | null> => {
+      try {
+        return await restoreHit({ args, hash, hit, cacheOpStart, taskStartNs })
+      } catch (err) {
+        if (!(err instanceof ArtifactVanishedError)) throw err
+        log.status(`[vx] ${node.id}: ${err.message} — running it`)
+        return null
+      }
+    }
     if (preProbed !== undefined) {
       if (preProbed.hit !== null) {
-        return restoreHit({ args, hash, hit: preProbed.hit, cacheOpStart, taskStartNs })
+        const restored = await restoreOrMiss(preProbed.hit)
+        if (restored !== null) return restored
+        // The up-front probe's hit may be restoring AHEAD of this task's
+        // deps, and a command run now would build from outputs they have
+        // not written yet and save that under the good key. The scheduler
+        // runs it again once they are done (admission drops the probe).
+        throw new RestoreDemoted(node.id)
       }
       // Confirmed stable miss — skip the probe, fall through to run.
-    } else {
+    } else if (!fingerprintMoved()) {
       const endProbe = span('cache.get')
-      const hit = await cache.get(hash, { taskId: node.id, command: step.command })
+      const hit = await cache.get(hash, getContext(node, step.command))
       endProbe()
       if (hit) {
-        return restoreHit({ args, hash, hit, cacheOpStart, taskStartNs })
+        const restored = await restoreOrMiss(hit)
+        if (restored !== null) return restored
       }
     }
   }
@@ -431,19 +581,33 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       })
     : 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 `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
+  // 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[] = []
+  // The empty files the sandbox request created for a literal write grant;
+  // swept after the attempt (`sweepPlaceholders`).
+  let placeholders: Placeholder[] = []
+  // The linked workspace packages the request withheld: the key does not
+  // answer for them.
+  let withheld: WithheldLink[] = []
 
   // Cache miss path (or caching disabled), up to `1 + retries` attempts.
   // Explicit config wins over the run-level `--retry` default, including
@@ -458,8 +622,8 @@ 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: ExecuteResult
     exitCode: number
@@ -468,7 +632,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // 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) {
+    if (additive && willWrite && !deferralRequested && outputs.length > 0) {
+      const endStamp = span('miss: stamp outputs')
+      stampedBefore ??= await stampOutputs(cleanArgs)
+      endStamp()
+    } else 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
@@ -498,13 +666,38 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // 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
-    })
+    const res = await args.executor
+      .execute(req)
+      .then((r: unknown) => {
+        assertExecuteResult(args.executor.name, node.id, r)
+        return r
+      })
+      .catch(async (err: unknown) => {
+        const message = err instanceof Error ? err.message : String(err)
+        log.taskStderr(node, `${message}\n`)
+        await sweepPlaceholders(placeholders)
+        throw err
+      })
     endExec()
     violations = [...res.violations]
+    // A denial under a dependency the key does not answer for says only
+    // ENOENT; the line beside it names the package and how to key it. Only
+    // with a denial there, so it never reddens a pass.
+    for (const w of reachedWithheld(withheld, violations)) {
+      violations.push({ timestamp: new Date(), line: withheldLinkLine(node.id, w) })
+    }
+    // A placeholder the task never wrote is not its output: take it back
+    // before the outputs are collected. On a failure it is also the one
+    // clue to a grant that meant a directory — say so beside the failure.
+    const untouched = await sweepPlaceholders(placeholders)
+    if (res.exitCode !== 0 && violations.length === 0) {
+      for (const p of untouched) {
+        violations.push({
+          timestamp: new Date(),
+          line: untouchedPlaceholderLine(node.projectDir, p),
+        })
+      }
+    }
     // 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"
@@ -512,12 +705,16 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // 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) {
@@ -526,11 +723,24 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       // 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 (matches the
-      // `--verify && !result.timedOut` guard); a genuinely-killed child already
-      // reports 143, so this only rewrites the trap-exit-0 case.
+      // 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')
     }
+    // The shell's 127 and 126 name the word and nothing about why — the
+    // PATH vx built, or a `#!` line the file itself carries (items 257,
+    // 258) — and an exit above 128 is a signal's number and nothing
+    // about what sent it (259). One frame line names the rule.
+    if (!res.timedOut) {
+      const verdict = shellVerdict({
+        code,
+        command: step.command,
+        cwd: node.projectDir,
+        bins: taskBinDirs(node, args.workspaceRoot),
+        signal: res.signal,
+      })
+      if (verdict !== undefined) log.taskStderr(node, `\n${verdict}\n`)
+    }
     return { result: res, exitCode: code }
   }
 
@@ -558,19 +768,33 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     }
   }
 
+  // Pass or fail, the command may have written where its project's
+  // run-start facts describe; a remote executor wrote on its own disk.
+  const writeReach =
+    args.executor.remote === true ? 'none' : undeclaredWriteReach(node, args.workspaceRoot)
+  const writesFingerprint =
+    args.executor.remote !== true && mayWriteFingerprint(node, args.workspaceRoot)
   for (;;) {
     attempt++
     const a = await runAttempt()
+    forgetUndeclaredWrites(args, writeReach)
+    if (writesFingerprint) args.fingerprintWatch?.wrote()
     result = a.result
     effectiveExitCode = a.exitCode
 
-    // A child killed by a shutdown signal (Ctrl-C / SIGTERM teardown)
-    // never finished on its own terms — revert it to aborted so it's
-    // neither cached, counted, shown, nor RETRIED (the run is tearing
-    // down). SIGKILL (OOM, forced) stays a real failure. A timeout also
-    // SIGTERMs, but `timedOut` marks it as our own deadline, not a
-    // shutdown — so it stays a real (retryable) failure.
-    if ((result.signal === 'SIGINT' || result.signal === 'SIGTERM') && !result.timedOut) {
+    // An attempt that ended in a shutdown never finished on its own terms —
+    // it is aborted, so it is neither cached, counted, shown, nor RETRIED.
+    // Two ways to know: the child died of SIGINT / SIGTERM (Ctrl-C, or a
+    // `kill` vx never saw; a timeout also SIGTERMs, but `timedOut` marks it
+    // as our own deadline, a real and retryable failure), or the RUN is
+    // stopping. The child alone was not enough: one that traps the
+    // forwarded SIGINT and exits 0 was cached as a success with its partial
+    // outputs, one that exits 1 was retried after Ctrl-C, and one SIGKILLed
+    // at the end of the grace read as an OOM failure (item 962).
+    const shutdown =
+      args.stopSignal?.aborted === true ||
+      ((result.signal === 'SIGINT' || result.signal === 'SIGTERM') && !result.timedOut)
+    if (shutdown) {
       return {
         node,
         status: 'aborted',
@@ -585,7 +809,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     if (effectiveExitCode === 0 || attempt >= maxAttempts) break
     log.taskStderr(
       node,
-      `vx: retrying ${node.id} (attempt ${attempt + 1}/${maxAttempts}) after exit ${effectiveExitCode}\n`,
+      `vx: retrying ${node.id} (attempt ${attempt + 1}/${maxAttempts}) after ${result.timedOut === true ? 'a timeout' : `exit ${effectiveExitCode}`}\n`,
     )
   }
 
@@ -612,63 +836,23 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       ...(cfgCacheable && !(policy.localRead || policy.remoteRead) ? { refresh: true } : {}),
       outputs: { files: outputs, workspaceFiles: wsOutputs },
     }
-    if (!useSandbox) return base
-    // 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,
-      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).
-    return {
-      ...base,
-      sandbox: {
-        baseAllowRead: [...resolved.files, ...baseAllowWrite],
-        baseAllowWrite,
-        baseDenyRead: [args.workspaceRoot],
-        config: resolveSandboxConfig(cfg.sandbox ?? {}, node.projectDir),
-        settleOnCleanExit: verifyInputs,
-      },
-    }
+    if (!userSandbox) return base
+    await args.armSandbox?.()
+    const sb = await sandboxRequestFor(
+      node,
+      step.sandbox!,
+      args.workspaceRoot,
+      cfgCacheable ? args.keyedProjects(node) : undefined,
+      args.nestedProjectDirs,
+    )
+    placeholders = sb.placeholders
+    withheld = sb.withheld
+    return { ...base, sandbox: sb.sandbox }
   }
 
   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 && deferralRequested) {
+  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.
@@ -684,216 +868,110 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           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 && willWrite) {
-    const endResolve = span('miss: resolve outputs')
-    const outputFiles = await resolveOutputs({
-      projectDir: node.projectDir,
-      outputs,
-      nestedProjectDirs: args.nestedProjectDirs,
-    })
-    const wsOutputFiles = await resolveWorkspaceOutputs({
-      workspaceRoot: args.workspaceRoot,
-      outputs: wsOutputs,
-    })
-    endResolve()
-    const endSave = span('miss: save')
-    // Tier-3 input fingerprint: the digest rows captured by the pre-exec
-    // describe above, persisted with the entry inside `cache.save`'s
-    // transaction. Miss path only — the warm/hit path never reaches here.
-    await cache.save({
+  } else if (effectiveExitCode === 0 && willSave && (await keyStillTrue())) {
+    const ownOutputFiles =
+      additive && stampedBefore !== undefined
+        ? await ownOutputsSince(cleanArgs, stampedBefore)
+        : undefined
+    const { landed } = await saveMiss({
+      ...(ownOutputFiles !== undefined ? { ownOutputFiles } : {}),
+      node,
       hash,
-      projectDir: node.projectDir,
-      outputFiles,
-      ...(wsOutputFiles.length > 0
-        ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: args.workspaceRoot }
-        : {}),
-      inputComponents: captured.map((c) => ({ entryHash: hash, ...c })),
-      // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
-      // the contract no longer accepts one — so the invariant is enforced by
-      // the type rather than by every call site remembering the gate.
-      entry: {
-        taskId: node.id,
-        command: step.command,
-        durationMs: result.durationMs,
-        stdout: result.stdout,
-      },
+      cache,
+      log,
+      workspaceRoot: args.workspaceRoot,
+      nestedProjectDirs: args.nestedProjectDirs,
+      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,
     })
-    endSave()
-    {
-      const savedDirPrefixes = wholeSubtreePrefixes(outputs)
-      if (savedDirPrefixes !== null) {
-        await cache.recordOutputDirs?.(hash, node.projectDir, savedDirPrefixes)
-      }
-    }
-    // --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)
+  } else if (cfgCacheable && !remoteOnly && !deferralRequested && args.noDependants !== true) {
+    // Ran here and saves nothing — failed, a read-only policy, a tainted
+    // upstream, a key that no longer held — yet it wrote what a save would
+    // have marked, and may have rewritten an input the re-check before a
+    // save catches. A same-run reader keyed from the snapshot's OIDs for
+    // either replayed the bytes from before the command (item 750). A
+    // withheld save already dropped the project; this finds the same move
+    // again and drops it again.
+    const endCheck = span('miss: recheck inputs')
+    const moved = await movedSinceKey()
+    endCheck()
+    if (moved !== undefined) {
+      forgetUndeclaredWrites(args, wsOutputs.length > 0 ? 'workspace' : 'project')
+    } else {
+      await markUnsaved({
+        node,
+        workspaceRoot: args.workspaceRoot,
+        nestedProjectDirs: args.nestedProjectDirs,
+        gitFilesCache: args.gitFilesCache,
+        outputs,
+        wsOutputs,
+      })
     }
   }
 
-  // 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
+  /**
+   * The workspace fingerprint every key here folded has moved (a task
+   * rewrote the lockfile), said once per run.
+   */
+  function fingerprintMoved(): boolean {
+    if (args.fingerprintWatch?.moved() === undefined) return false
+    args.fingerprintWatch.say(log)
+    return true
+  }
 
-  // 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' }
-    }
+  /**
+   * The input that no longer holds what the key folded: `null` when the
+   * key re-derived just before the command already differed (the file
+   * unnamed), undefined when none moved.
+   */
+  async function movedSinceKey(): Promise<string | null | undefined> {
+    return described!.hash !== hash
+      ? null
+      : await movedInput(described!.facts, cache, described!.describedAt)
   }
 
-  // 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)),
-        ])
-      }
-    }
+  /**
+   * Does the key still describe the inputs the command ran over? It was
+   * taken before the command — up front, or before `describeTaskInputs` —
+   * and a save files the outputs under it. A user's edit mid-run, or a
+   * task rewriting its own input (a formatter), saved bytes built from one
+   * state under the key of another: restore the old state and the next run
+   * replayed them as up-to-date (turborepo#10111, #1146, item 743). The
+   * result stands; only the entry is withheld, and the facts about the
+   * project go, since something wrote there. A lockfile a task rewrote
+   * withholds it too: the key folded the old one.
+   */
+  async function keyStillTrue(): Promise<boolean> {
+    if (fingerprintMoved()) return false
+    const endCheck = span('miss: recheck inputs')
+    const moved = await movedSinceKey()
+    endCheck()
+    if (moved === undefined) return true
+    const what = moved === null ? 'its inputs' : `\`${relPosix(args.workspaceRoot, moved)}\``
+    log.status(
+      `[vx] ${node.id}: ${what} changed after its key was taken — the result stands, ` +
+        `but is not saved under a key that no longer describes it`,
+    )
+    forgetUndeclaredWrites(args, wsOutputs.length > 0 ? 'workspace' : 'project')
+    return false
   }
 
-  // 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
+  const finalViolations = violations
 
   return {
     node,
@@ -902,6 +980,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     durationMs: result.durationMs,
     hash,
     ...(attempt > 1 ? { attempts: attempt } : {}),
+    ...(result.timedOut === true && effectiveExitCode !== 0 ? { timedOut: true as const } : {}),
     ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
     ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
     ...(result.where !== undefined ? { where: result.where } : {}),
@@ -910,8 +989,6 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       : {}),
     wallclockStartNs,
     wallclockEndNs,
-    ...(verify !== undefined ? { verify } : {}),
-    ...(outputFp !== undefined ? { outputFp } : {}),
     ...(finalViolations.length > 0
       ? {
           sandboxViolations: finalViolations.length,
@@ -921,227 +998,36 @@ 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.
+ * Drop the run's facts about files a task may have written without
+ * declaring them (`undeclaredWriteReach`): the project's git snapshot and
+ * its index OIDs, and its `package.json` digest. The next reader
+ * re-enumerates the project (one `git ls-files`) and hashes its files by
+ * content; the per-declaration file-list memos are keyed on the snapshot
+ * array, so they miss with it (item 743).
  */
-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 dirPrefixes = wholeSubtreePrefixes(outputs)
-  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 endRows = span('output rows')
-    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
-    endRows()
-    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) }))
-      // The directory short-circuit: for whole-subtree globs, unchanged
-      // mtimes on every directory recorded at the last save/restore prove
-      // the output SET is unchanged (a file added or removed anywhere the
-      // glob could see bumps a recorded directory), so the walk that cost
-      // 0.36 ms per warm hit is replaced by a few stats. The per-file
-      // fingerprint check below still runs; only the enumeration is skipped.
-      let setKnown = false
-      if (dirPrefixes !== null && wsOutputs.length === 0 && args.cache.outputDirsCurrent) {
-        const endDirs = span('output dirs')
-        // Loaded with the entry (batched by getMany, or with the lazy get).
-        const dirRows = hit.outputDirRows ?? []
-        const covers = dirPrefixes.every((pre) => dirRows.some((r) => r.path === pre))
-        setKnown = covers && (await args.cache.outputDirsCurrent!(node.projectDir, dirRows))
-        endDirs()
-      }
-      let actualAbs: string[]
-      let actualWsAbs: string[]
-      if (setKnown) {
-        actualAbs = projExpected.map((e) => path.join(node.projectDir, e.path))
-        actualWsAbs = []
-      } else {
-        const endGlob = span('output glob')
-        actualAbs = await resolveOutputs({
-          projectDir: node.projectDir,
-          outputs,
-          nestedProjectDirs: args.nestedProjectDirs,
-        })
-        actualWsAbs = await resolveWorkspaceOutputs({
-          workspaceRoot: args.workspaceRoot,
-          outputs: wsOutputs,
-        })
-        endGlob()
-      }
-      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)) {
-        const endStat = span('output stat')
-        skipRestore =
-          (await args.cache.isOutputsCurrent(node.projectDir, projExpected)) &&
-          (await args.cache.isOutputsCurrent(args.workspaceRoot, wsExpected))
-        endStat()
-        // The walk ran and proved the tree current (rows absent, or a
-        // directory had moved — a benign touch): snapshot the directories
-        // so the next hit skips the walk.
-        if (skipRestore && !setKnown && dirPrefixes !== null) {
-          await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
-        }
-      }
-    }
-  }
-  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)
-    if (dirPrefixes !== null) {
-      await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
-    }
-    // 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,
-    // What THIS run spent: probe + restore. NOT the stored exec time — see
-    // `storedDurationMs`, which is what the hit skipped.
-    durationMs: Math.round(performance.now() - cacheOpStart),
-    storedDurationMs: hit.durationMs,
-    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,
+function forgetUndeclaredWrites(args: ExecuteArgs, reach: 'none' | 'project' | 'workspace'): void {
+  if (reach === 'none') return
+  if (reach === 'workspace') {
+    args.gitFilesCache?.clear()
+    args.hashCache?.packageJson.clear()
+    return
   }
+  args.gitFilesCache?.delete(args.node.projectDir)
+  args.gitFilesCache?.invalidateWorkspacePartition()
+  args.hashCache?.packageJson.delete(args.node.projectDir)
 }
 
-/**
- * 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).
- *
- * `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, '')
-    }
-  }
+/** The two bin directories a task's PATH starts with: its own, then the root's (once when they coincide). */
+function taskBinDirs(node: TaskNode, workspaceRoot: string): string[] {
+  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)
+  return bins
 }
 
-/**
- * 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.
- */
 /**
  * Build the child-process env for one task. Same arguments at every call site
  * (persistent + cached). Two `node_modules/.bin` directories are prepended to
@@ -1159,15 +1045,14 @@ async function prepareOutputsForBind(
  * it. npm/pnpm/yarn all put the ancestor chain on PATH for the same reason.
  */
 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)
-  return buildIsolatedEnv({
+  const bins = taskBinDirs(node, workspaceRoot)
+  const env = buildIsolatedEnv({
     passThrough: step.env?.passThrough ?? [],
     define: step.env?.define ?? {},
     source: process.env,
     binPaths: bins,
   })
+  env[VX_RUN_WORKSPACE_ENV] = workspaceRoot
+  env[VX_RUN_TASK_ENV] = node.id
+  return env
 }