@vzn/vx 0.0.21 → 0.0.22

package/src/orchestrator/execute-task.ts

@@ -1,11 +1,15 @@
 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,
 } from '../cache/index.js'
@@ -20,16 +24,31 @@ import {
   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 } from '../graph/index.js'
-import { span } from '../util/index.js'
-import { sandboxRequestFor } from './sandbox-request.js'
-import { saveMiss, type OutputDirSnapshot } from './miss-save.js'
+import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { relPosix, span } from '../util/index.js'
+import {
+  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'
@@ -39,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
@@ -81,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
@@ -129,6 +157,12 @@ export interface ExecuteArgs {
    * 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:
@@ -154,6 +188,18 @@ export interface ExecuteArgs {
    * 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
 }
 
 /**
@@ -231,16 +277,34 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // (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?.()
-    const sb = await sandboxRequestFor(node, step.sandbox, args.workspaceRoot)
+    // 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,
-      ...sb,
+      env,
+      ...sb.sandbox,
+      server: true,
     })
     command = wrapped.wrapped
     bridgeTag = wrapped.tag
+    signalChannel = wrapped.forwardsSignals
   }
   const persistentOpts: Parameters<typeof runPersistent>[0] = {
     command,
@@ -249,6 +313,7 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
     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
@@ -263,12 +328,28 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const spawn = runPersistent(persistentOpts)
   // The host side of a port bridge lives exactly as long as the server:
   // released on the child's exit, whether the run tore it down or it died.
-  if (bridgeTag !== undefined) {
+  // 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
-    void spawn.child?.exited?.then(
-      () => releaseBridges(tag),
-      () => releaseBridges(tag),
-    )
+    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
@@ -278,17 +359,28 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // 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',
@@ -412,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
@@ -421,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
       }
     }
   }
@@ -482,6 +602,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // 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
@@ -506,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
@@ -536,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"
@@ -572,6 +727,20 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       // 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 }
   }
 
@@ -599,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',
@@ -626,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`,
     )
   }
 
@@ -655,7 +838,16 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     }
     if (!userSandbox) return base
     await args.armSandbox?.()
-    return { ...base, sandbox: await sandboxRequestFor(node, step.sandbox!, args.workspaceRoot) }
+    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
@@ -681,8 +873,13 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         },
       })
     }
-  } else if (effectiveExitCode === 0 && willSave) {
+  } 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,
       cache,
@@ -702,6 +899,76 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       deferSave: args.deferSave,
     })
     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,
+      })
+    }
+  }
+
+  /**
+   * 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
+  }
+
+  /**
+   * 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)
+  }
+
+  /**
+   * 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
   }
 
   const finalViolations = violations
@@ -713,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 } : {}),
@@ -730,6 +998,36 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 }
 
+/**
+ * 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).
+ */
+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)
+}
+
+/** 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
+}
+
 /**
  * Build the child-process env for one task. Same arguments at every call site
  * (persistent + cached). Two `node_modules/.bin` directories are prepended to
@@ -747,11 +1045,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
  * 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)
+  const bins = taskBinDirs(node, workspaceRoot)
   const env = buildIsolatedEnv({
     passThrough: step.env?.passThrough ?? [],
     define: step.env?.define ?? {},