@vzn/vx 0.0.651 → 0.0.653

package/src/orchestrator/save-lane.ts

@@ -6,8 +6,8 @@
 // A bounded number run at once (memory: each pack holds an artifact's
 // bytes); the scheduler finishes a task only once its save has settled
 // (`settledOf`), so a run ends with every save in the cache; and a save
-// that fails degrades to a miss next time, said once — the task's work
-// ran.
+// that fails degrades to a miss next time, reported with its task — the
+// task's work ran.
 
 export interface SaveLane {
   /**
@@ -17,34 +17,45 @@ export interface SaveLane {
    * task's outcome, and a duplicate of the same task in another run
    * (admission's in-flight join).
    */
-  defer(save: () => Promise<void>): Promise<boolean>
+  defer(save: () => Promise<void>, taskId: string): Promise<boolean>
 }
 
-export function createSaveLane(cap: number, onError: (err: unknown) => void): SaveLane {
-  const queue: Array<{ save: () => Promise<void>; settle: (stored: boolean) => void }> = []
+interface Queued {
+  save: () => Promise<void>
+  taskId: string
+  settle: (stored: boolean) => void
+}
+
+export function createSaveLane(
+  cap: number,
+  onError: (err: unknown, taskId: string) => void,
+): SaveLane {
+  const queue: Queued[] = []
   let running = 0
-  const start = (save: () => Promise<void>, settle: (stored: boolean) => void): void => {
-    void save()
+  const start = (q: Queued): void => {
+    void q
+      .save()
       .then(
         () => true,
         (err: unknown) => {
-          onError(err)
+          onError(err, q.taskId)
           return false
         },
       )
       .then((stored) => {
         running--
-        settle(stored)
+        q.settle(stored)
         const next = queue.shift()
-        if (next !== undefined) start(next.save, next.settle)
+        if (next !== undefined) start(next)
       })
     running++
   }
   return {
-    defer(save) {
+    defer(save, taskId) {
       return new Promise<boolean>((settle) => {
-        if (running < cap) start(save, settle)
-        else queue.push({ save, settle })
+        const q = { save, taskId, settle }
+        if (running < cap) start(q)
+        else queue.push(q)
       })
     },
   }

package/src/orchestrator/shell-verdict.ts

@@ -25,9 +25,11 @@ export function shellVerdict(args: {
   signal?: string | number | undefined
   /** A sandboxed task's view: whether a file is hidden from it (no grant reads it). */
   hidden?: ((file: string) => boolean) | undefined
+  /** What the step wrote to stderr: the shell's own "not found" line names the word a compound command missed. */
+  stderr?: string | undefined
 }): string | undefined {
   if (args.code !== 127 && args.code !== 126) return signalVerdict(args.code, args.signal)
-  const word = execWord(args.command)
+  const word = execWord(args.command) ?? (args.code === 127 ? notFoundWord(args.stderr) : undefined)
   const what = word ?? 'a command in this task'
   if (word !== undefined && word.includes('/')) {
     const file = path.resolve(args.cwd, word)
@@ -43,6 +45,15 @@ export function shellVerdict(args: {
   if (args.code === 126) {
     return `[vx] exit 126 is the shell's "found but cannot execute": ${what} is not executable or is a directory — chmod +x it`
   }
+  // A program the host's PATH has may be one the sandbox hides (a
+  // hermetic task sees no /usr/bin): the reason is a grant, not an install.
+  const found =
+    word === undefined || args.hidden === undefined
+      ? null
+      : Bun.which(word, { PATH: [...args.bins, process.env['PATH'] ?? ''].join(path.delimiter) })
+  if (found !== null && args.hidden!(found)) {
+    return `[vx] exit 127 is the shell's "command not found": ${word} is ${found} on the host, but no sandbox grant reads it, so inside the sandbox it is not there — add it (or its directory) to exec.sandbox.allow.read`
+  }
   const unnamed = args.bins.find((dir) => dir.includes(path.delimiter))
   if (unnamed !== undefined) {
     return `[vx] exit 127 is the shell's "command not found": ${what} is not on this task's PATH — ${unnamed} holds "${path.delimiter}", which PATH reads as a separator, so vx cannot put it there; move the workspace to a path without "${path.delimiter}"`
@@ -50,6 +61,23 @@ export function shellVerdict(args: {
   return `[vx] exit 127 is the shell's "command not found": ${what} is not on this task's PATH — vx puts ${args.bins.join(' and ')} first and never a sibling project's bin; install it in this package or at the workspace root`
 }
 
+/**
+ * The word the shell's last "not found" line names: dash's `sh: 1: cat:
+ * not found`, bash's `bash: line 1: cat: command not found`. A command with
+ * a redirect or a `&&` has no one word to read from the command itself, and
+ * a hermetic task's hidden `cat` was told to be installed (almost every
+ * real command has one).
+ */
+function notFoundWord(stderr: string | undefined): string | undefined {
+  if (stderr === undefined) return undefined
+  const lines = stderr.trimEnd().split('\n')
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = /: ([^:]+): (?:command )?not found$/.exec(lines[i]!.trimEnd())
+    if (m !== null) return m[1]
+  }
+  return undefined
+}
+
 /** Why the shell could not run a file, read from the file. */
 function fileVerdict(file: string): string {
   if (!existsSync(file)) {

package/src/orchestrator/signals.ts

@@ -99,6 +99,103 @@ export async function terminateChildren(
   }
 }
 
+/**
+ * The signals a run hears from the moment it goes for its run lock until
+ * `forwardSignals` takes over. A plugin's setup runs in between, so a
+ * slow one held that window open for seconds, and a Ctrl-C in it killed
+ * vx by the default action: no plugin's teardown, no sink's flush, the
+ * lock's entry left in the temp dir. The first signal is noted and aborts
+ * `signal` (the lock's wait reads it); `forwardSignals` replays it once
+ * installed, or `run()` exits of it on a way out before that. A second
+ * exits at once, as a second does later.
+ */
+export interface HeldSignals {
+  readonly signal: AbortSignal
+  /** Removes the listeners, once; the signal heard so far, if any. */
+  takeOver(): StopSignal | undefined
+  /**
+   * From here a stop is held for the run's own end (plugin setup has
+   * begun, so teardown is owed); before it, a stop leaves at once, its
+   * exit hooks releasing the run lock: nothing earlier (a git listing, a
+   * remote's open) waits on the stop, so holding it held the run.
+   */
+  arm(): void
+}
+
+export function holdSignals(): HeldSignals {
+  const controller = new AbortController()
+  let heard: StopSignal | undefined
+  let armed = false
+  const onSignal = (signal: StopSignal): void => {
+    if (heard !== undefined) exitOf(heard, false)
+    if (!armed) {
+      claimExitForSignal()
+      exitOf(signal, false)
+    }
+    heard = signal
+    claimExitForSignal()
+    controller.abort(signal)
+  }
+  const onSigint = (): void => onSignal('SIGINT')
+  const onSigterm = (): void => onSignal('SIGTERM')
+  const onSighup = (): void => onSignal('SIGHUP')
+  process.on('SIGINT', onSigint)
+  process.on('SIGTERM', onSigterm)
+  if (!hangupIgnored()) process.on('SIGHUP', onSighup)
+  let taken = false
+  return {
+    signal: controller.signal,
+    arm: () => {
+      armed = true
+    },
+    takeOver: () => {
+      if (taken) return undefined
+      taken = true
+      process.off('SIGINT', onSigint)
+      process.off('SIGTERM', onSigterm)
+      process.off('SIGHUP', onSighup)
+      return heard
+    },
+  }
+}
+
+/**
+ * `work`, or a rejection once `signal` aborts. A plugin's setup or
+ * executor factory that never settles held a held signal with it: the
+ * first was noted and waited, and only a second, which tears nothing
+ * down, ended vx.
+ */
+export function unlessStopped<T>(work: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return work
+  if (signal.aborted) return Promise.reject(new Error(`stopped by ${String(signal.reason)}`))
+  const { promise, resolve, reject } = Promise.withResolvers<T>()
+  const onAbort = (): void => reject(new Error(`stopped by ${String(signal.reason)}`))
+  signal.addEventListener('abort', onAbort, { once: true })
+  work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort))
+  return promise
+}
+
+/**
+ * A held signal no `forwardSignals` took over (the run returned or threw
+ * before its tasks) leaves here, once the run's own end is done: stdout
+ * drained, bounded, then `exitOf`.
+ */
+export async function exitOfSignal(signal: StopSignal): Promise<never> {
+  await settleWithin(new Promise<void>((r) => process.stdout.end(() => r())), 2_000)
+  return exitOf(signal, false)
+}
+
+/**
+ * Die of the signal once the exit hooks have run: a shell running vx in
+ * a script stops it on Ctrl-C only when its child died of SIGINT, and a
+ * 130 exit ran the script's next line. The code stays the fallback
+ * should the signal not land.
+ */
+function exitOf(signal: StopSignal, handsTerminal: boolean): never {
+  if (!handsTerminal) process.once('exit', () => dieOf(signal))
+  process.exit(signalExitCode(signal))
+}
+
 export interface SignalForwarding {
   /** Detach the handlers — in `run()`'s finally, so repeated runs never stack listeners. */
   remove(): void
@@ -130,6 +227,8 @@ export function forwardSignals(args: {
    * the signal's code rather than dying of the signal.
    */
   handsTerminal?: boolean
+  /** The run's held signals: taken over here, and one already heard replayed. */
+  held?: HeldSignals | undefined
   /** In-flight children; the runner adds and removes each around its spawn. */
   liveChildren: ReadonlySet<Child>
   /** Ready persistent tasks the orchestrator owns until the graph finishes. */
@@ -155,14 +254,7 @@ export function forwardSignals(args: {
     } catch {
       // double-close race with the normal path; we're exiting anyway
     }
-    // Die of the signal once the exit hooks have run: a shell running vx
-    // in a script stops it on Ctrl-C only when its child died of SIGINT,
-    // and a 130 exit ran the script's next line. The code stays the
-    // fallback should the signal not land.
-    if (args.handsTerminal !== true) {
-      process.once('exit', () => dieOf(signal))
-    }
-    process.exit(signalExitCode(signal))
+    return exitOf(signal, args.handsTerminal === true)
   }
   let stopping: StopSignal | undefined
   const onSignal = (signal: StopSignal): void => {
@@ -209,6 +301,9 @@ export function forwardSignals(args: {
     process.on('SIGTSTP', onSigtstp)
     process.on('SIGCONT', onSigcont)
   }
+  // After this module's own listeners are on, so no signal finds none.
+  const heard = args.held?.takeOver()
+  if (heard !== undefined) onSignal(heard)
   return {
     remove: () => {
       process.off('SIGINT', onSigint)

package/src/orchestrator/stable-keys.ts

@@ -15,6 +15,7 @@ import {
   foldedDeps,
   isGroupTask,
   outputTakenBack,
+  standInsOf,
   type TaskNode,
   type TaskOutcome,
 } from '../graph/index.js'
@@ -89,14 +90,14 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   // reached through a no-output intermediate still poisons the key, so each
   // dep's accumulated producers fold forward.
   //   - outputProjects: the project names of every upstream task declaring
-  //     cache.outputs.files (project-relative outputs land in the producer's
-  //     own dir), and of every upstream with no cache block that may write
+  //     outputs.files (project-relative outputs land in the producer's
+  //     own dir), and of every upstream with no `cache: true` that may write
   //     in its own project (`undeclaredWriteReach`, item 743). A bitset over
   //     project indexes: a union per dep was a string Set copied tasks ×
   //     deps × projects times, 101 ms of a 513 ms warm run at 476 packages
   //     (item 744).
-  //   - wsOutputUpstream: any upstream declares cache.outputs.workspaceFiles
-  //     (root-anchored, boundary-ignoring outputs), or has no cache block
+  //   - wsOutputUpstream: any upstream declares outputs.workspaceFiles
+  //     (root-anchored, boundary-ignoring outputs), or has no `cache: true`
   //     and a sandbox write grant elsewhere in the workspace, or may rewrite
   //     a root file a plugin claims (a root `pnpm install`): every key folds
   //     what the claimant took from it, once per run.
@@ -125,7 +126,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   // of what any one reader's upstream producers declare.
   const outputsOf = new Map<string, string[]>()
   for (const n of args.nodes.values()) {
-    const files = n.config.cache?.outputs.files ?? []
+    const files = n.config.outputs?.files ?? []
     if (files.length === 0) continue
     const list = outputsOf.get(n.projectName)
     if (list === undefined) outputsOf.set(n.projectName, [...files])
@@ -185,10 +186,10 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
         const wideOfDep = wideById.get(dep)
         if (wideOfDep !== undefined) wideUnion.addAll(wideOfDep)
         if (wsOutputUpstreamById.get(dep) === true) wsOutputUpstream = true
-        const depOut = depNode.config.cache?.outputs
+        const depOut = depNode.config.outputs
         if ((depOut?.files?.length ?? 0) > 0) outputs.add(depNode.projectName)
         if ((depOut?.workspaceFiles?.length ?? 0) > 0) wsOutputUpstream = true
-        // An uncached producer declares no outputs, yet a same-project reader
+        // An uncached producer is held to no outputs, yet a same-project reader
         // after it (`tasks: []` decouples the key, not the order) read the
         // bytes it wrote: its key taken up front was the pre-producer one, and
         // the fourth run of seeds A,B,B,A replayed B over A (turborepo#13788).
@@ -198,7 +199,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
           wideUnion.add(depNode.projectName)
         } else if (reach === 'workspace') wsOutputUpstream = true
         if (
-          depNode.config.cache === undefined &&
+          depNode.config.cache !== true &&
           mayWriteFingerprint(depNode, args.workspaceRoot, args.claimedFiles)
         )
           wsOutputUpstream = true
@@ -219,7 +220,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
     for (const dep of anyUnfolded ? node.deps : []) {
       const depNode = args.nodes.get(dep)
       if (!depNode) continue
-      const cached = depNode.config.cache !== undefined
+      const cached = depNode.config.cache === true
       // The cached twin: a formatter rewriting its own input ahead of a
       // reader that folds no key of it replayed seed B's build under seed A
       // on the fourth run, the same way (item 750).
@@ -323,7 +324,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       )
     if (unstable) unstableById.add(id)
 
-    const cacheEnabled = node.config.cache !== undefined
+    const cacheEnabled = node.config.cache === true
     if (cacheEnabled && !unstable) stableKeys.push({ hash, node })
     // An uncached key stays preliminary behind any upstream that may write
     // into this project, or anywhere: none of its writes is declared.
@@ -438,7 +439,7 @@ export function gatedOutputs(
   // 1,000 projects' tasks spent 5-8 ms here re-splitting the same globs.
   const outputsOf = new Map<string, ProjectOutputs>()
   for (const n of nodes.values()) {
-    const files = n.config.cache?.outputs.files
+    const files = n.config.outputs?.files
     if (files === undefined || files.length === 0) continue
     let po = outputsOf.get(n.projectName)
     if (po === undefined) outputsOf.set(n.projectName, (po = new ProjectOutputs()))
@@ -518,13 +519,13 @@ const probesAfterWritesOf = new WeakMap<ReadonlyMap<string, TaskNode>, ReadonlyS
  * its upstream ran (`ComputeHashArgs.probesAfterWrites`).
  *
  * A writer is any upstream whose command may write (`commandWriteReach`)
- * or that declares outputs. A key that folds the writer's covers what it
- * writes, as for a rewriter in `deriveStableKeys`: an early answer then
+ * or that declares outputs. A key that folds a cached writer's covers what
+ * it writes, as for a rewriter in `deriveStableKeys`: an early answer then
  * costs a spurious miss on the run after the bytes change, never a stale
  * hit, and such a probe keeps the run's shared answer — one spawn per run,
  * not per task. So only a writer the key does not fold, transitively
- * (`tasks: []`, a filter that leaves it out, an order-only edge), makes
- * the probe wait.
+ * (`tasks: []`, a filter that leaves it out, an order-only edge), or an
+ * uncached one, makes the probe wait.
  *
  * Once per graph: run, admission and both up-front passes ask the same map.
  */
@@ -554,8 +555,8 @@ export function probesAfterWrites(
   for (const n of nodes.values()) {
     if (
       commandWriteReach(n, workspaceRoot) !== 'none' ||
-      (n.config.cache?.outputs.files.length ?? 0) > 0 ||
-      (n.config.cache?.outputs.workspaceFiles?.length ?? 0) > 0
+      (n.config.outputs?.files.length ?? 0) > 0 ||
+      (n.config.outputs?.workspaceFiles?.length ?? 0) > 0
     )
       writers.add(n.id)
   }
@@ -577,19 +578,24 @@ export function probesAfterWrites(
       if (unfolded || !depWrites) continue
       const folded =
         foldsAll || (folds ??= new Set(foldedDeps(node, nodeOf).map((c) => c.node.id))).has(dep)
-      unfolded = folded ? unfoldedBelow.has(dep) : true
+      // An uncached writer's writes are not a function of its key.
+      const covers = folded && (!writers.has(dep) || nodeOf(dep).config.cache === true)
+      unfolded = covers ? unfoldedBelow.has(dep) : true
     }
     if (writer) writerBelow.add(id)
     if (unfolded) unfoldedBelow.add(id)
-    if (unfolded && node.config.cache !== undefined && probes(node)) late.add(id)
+    if (unfolded && node.config.cache === true && probes(node)) late.add(id)
   }
   return late
 }
 
 /**
  * Does this task's key fold the dependency's? What `computeTaskHash` folds
- * (`filterUpstreamHashes` over the same synthetic outcomes); a group folds
- * every keyed member.
+ * (`filterUpstreamHashes` over the same synthetic outcomes); an unkeyed
+ * group, which has no filter, folds every keyed member. A keyed group is
+ * keyed by `computeTaskHash`, filter and all: read as folding everything, its
+ * `tasks: []` hid a cached rewriter below it, and its reader was restored
+ * under the key taken before the rewrite.
  */
 function foldedBy(
   node: TaskNode,
@@ -597,9 +603,11 @@ function foldedBy(
   keyById: Map<string, string>,
 ): (dep: string) => boolean {
   const filter = node.config.inputs?.tasks
-  if (isGroupTask(node) || filter === undefined) return (dep) => keyById.has(dep)
+  if (filter === undefined) return (dep) => keyById.has(dep)
   const hashes = new Set(
-    filterUpstreamHashes(upstream, filter, node.projectName, node.id).map(([, h]) => h),
+    filterUpstreamHashes(upstream, filter, node.projectName, node.id, standInsOf(node)).map(
+      ([, h]) => h,
+    ),
   )
   return (dep) => {
     const h = keyById.get(dep)
@@ -628,8 +636,8 @@ function synthUpstream(
  * Conservative stability check: does any TRANSITIVE-upstream task whose
  * outputs could land where this task reads its inputs make this task's
  * key preliminary? The producers are pre-folded by `deriveStableKeys`
- * (`upstreamOutputProjects` = projects declaring `cache.outputs.files`
- * upstream; `hasWsOutputUpstream` = any `cache.outputs.workspaceFiles`
+ * (`upstreamOutputProjects` = projects declaring `outputs.files`
+ * upstream; `hasWsOutputUpstream` = any `outputs.workspaceFiles`
  * upstream), so a producer reached through a no-output intermediate is
  * caught too.
  *
@@ -663,7 +671,6 @@ export function dependsOnSiblingOutputs(
     readableOf?: ReadonlyMap<string, readonly string[]>
   },
 ): boolean {
-  const cache = node.config.cache
   const declared = node.config.inputs
   // A task with no inputs has no key to take up front.
   if (declared === undefined) return false
@@ -697,7 +704,7 @@ export function dependsOnSiblingOutputs(
     // that producer, its restore raced the producer's clean and extract
     // (M-5; invariant 2 of docs/design/overlapping-outputs-2026-09.md).
     // `outputsOf` holds this task's own globs too; set them aside once.
-    const own = cache?.outputs.files ?? []
+    const own = node.config.outputs?.files ?? []
     if (own.length > 0) {
       const others = [...outputs]
       for (const g of own) {

package/src/orchestrator/task-artifacts.ts

@@ -22,7 +22,7 @@ export interface ArtifactTask {
   /** Absolute. */
   readonly projectDir: string
   readonly command: string
-  /** Its `cache.outputs`: project-relative `files`, root-relative `workspaceFiles`. */
+  /** Its `outputs`: project-relative `files`, root-relative `workspaceFiles`. */
   readonly outputs: {
     readonly files: readonly string[]
     readonly workspaceFiles: readonly string[]
@@ -69,7 +69,10 @@ export interface TaskArtifacts {
   restore(key: string, task: ArtifactTask): Promise<CapturedChunk[] | null>
   /**
    * Entry `key`'s output alone, laying no file; null when no cache holds
-   * it. An `exec.remote: 'only'` task's files stay off this disk.
+   * it. An `exec.remote: 'only'` task's files stay off this disk. An entry
+   * read off a remote is kept in the local store, so a later `restore`
+   * downloads nothing; naming no task, its row reads `<key>#unknown` with
+   * no command, and its file names are not checked against any outputs.
    */
   output(key: string): Promise<CapturedChunk[] | null>
   /**
@@ -129,7 +132,17 @@ export function taskArtifacts(cache: CacheLayer, workspaceRoot: string): TaskArt
     },
 
     async restore(key, task) {
-      const entry = await (cache.getSaved ? cache.getSaved(key) : cache.get(key))
+      // The task names the row a remote read writes, and the files its
+      // artifact may carry (`CacheGetContext.outputs`). Its command is
+      // masked as a save's is, read only by that write.
+      const ctx = {
+        taskId: task.id,
+        get command() {
+          return secretMask([process.env])?.mask(task.command) ?? task.command
+        },
+        outputs: task.outputs,
+      }
+      const entry = await (cache.getSaved ? cache.getSaved(key, ctx) : cache.get(key, ctx))
       if (entry === null) return null
       await cache.restoreOutputs(key, task.projectDir, workspaceRoot, task.outputs)
       return decodeOutputLog(entry.stdout)