@vzn/vx 0.0.16 → 0.0.18

package/src/orchestrator/execute-task.ts

@@ -16,11 +16,16 @@ import {
 } from '../cache/index.js'
 import {
   buildIsolatedEnv,
-  runCommand,
   runPersistent,
-  runSandboxed,
   resolveSandboxConfig,
+  shellQuote,
+  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 {
@@ -31,10 +36,13 @@ import {
   outputRefs,
   undeclaredInputPaths,
 } from './verify.js'
+import { span, staticPrefix, wholeSubtreePrefixes } from '../util/index.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 +57,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
@@ -141,6 +175,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 +192,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,7 +204,7 @@ 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
@@ -176,7 +216,7 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
       step.persistent.readyWhen !== undefined
         ? step.command
         : effectiveForwardArgs.length > 0
-          ? step.command + ' ' + effectiveForwardArgs.map((s) => JSON.stringify(s)).join(' ')
+          ? step.command + ' ' + effectiveForwardArgs.map(shellQuote).join(' ')
           : step.command,
     cwd: node.projectDir,
     env,
@@ -241,8 +281,25 @@ 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)
+
+  // 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: willWrite, stderr: false }
 
   const outputs = cacheCfg?.outputs.files ?? []
   const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
@@ -295,6 +352,30 @@ 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) {
+    // 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,
+    }
+  }
+
   const cleanArgs = {
     projectDir: node.projectDir,
     outputs,
@@ -316,16 +397,41 @@ 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
 
+  // 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
+
   // 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`
@@ -344,7 +450,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
@@ -355,23 +461,56 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // streamed notice). Shared by the retry loop AND the `--verify` re-run so
   // the two 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`
@@ -383,10 +522,42 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // 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 (matches the
+      // `--verify && !result.timedOut` guard); 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,20 +589,30 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     )
   }
 
-  async function runUnsandboxedTask(): ReturnType<typeof runCommand> {
-    return runCommand({
+  async function buildRequest(): Promise<ExecuteRequest> {
+    const base: ExecuteRequest = {
+      taskId: node.id,
+      workspaceRoot: args.workspaceRoot,
       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 } : {}),
-    })
-  }
-
-  async function runSandboxedTask(): ReturnType<typeof runCommand> {
+      ...(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 (!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
@@ -468,26 +649,17 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     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,
-      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 } : {}),
-      baseAllowRead: [...resolved.files, ...baseAllowWrite],
-      baseAllowWrite,
-      baseDenyRead: [args.workspaceRoot],
-      config: resolveSandboxConfig(cfg.sandbox ?? {}, node.projectDir),
-    })
-    violations = sandboxResult.violations
-    const { violations: _v, ...runResult } = sandboxResult
-    return runResult
+    // 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,
+      },
+    }
   }
 
   const wallclockEndNs = process.hrtime.bigint() - args.runStartHrTimeNs
@@ -496,7 +668,27 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // captured inside the save block while the tree is attempt-1's.
   let verifyFp1: Map<string, string> | undefined
 
-  if (effectiveExitCode === 0 && willWrite) {
+  if (effectiveExitCode === 0 && willWrite && 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,
+        },
+      })
+    }
+  } else if (effectiveExitCode === 0 && willWrite) {
+    const endResolve = span('miss: resolve outputs')
     const outputFiles = await resolveOutputs({
       projectDir: node.projectDir,
       outputs,
@@ -506,26 +698,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       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({
-      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 } : {}),
-    })
+    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({
       hash,
       projectDir: node.projectDir,
@@ -534,14 +711,23 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         ? { 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,
-        exitCode: effectiveExitCode,
         durationMs: result.durationMs,
         stdout: result.stdout,
       },
     })
+    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
@@ -718,6 +904,10 @@ 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 } : {}),
@@ -758,6 +948,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   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,
@@ -781,7 +972,9 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   // tar (decompress + parse) at the same point.
   let skipRestore = false
   if (anyOutputs) {
-    const expected = args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
+    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.
@@ -789,15 +982,39 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
       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,
-      })
+      // 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 }>,
@@ -812,9 +1029,17 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         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)
+        }
       }
     }
   }
@@ -824,6 +1049,9 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     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
@@ -861,7 +1089,10 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     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
@@ -911,29 +1142,32 @@ async function prepareOutputsForBind(
  * 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).
+ * 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.
+ *
+ * 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 {
+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({
     passThrough: step.env?.passThrough ?? [],
     define: step.env?.define ?? {},
     source: process.env,
-    binPaths: [path.join(node.projectDir, 'node_modules', '.bin')],
+    binPaths: bins,
   })
 }