@vzn/vx 0.0.84 → 0.0.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.84",
+  "version": "0.0.85",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.84",
-    "@vzn/vx-linux-arm64": "0.0.84",
-    "@vzn/vx-darwin-x64": "0.0.84",
-    "@vzn/vx-darwin-arm64": "0.0.84"
+    "@vzn/vx-linux-x64": "0.0.85",
+    "@vzn/vx-linux-arm64": "0.0.85",
+    "@vzn/vx-darwin-x64": "0.0.85",
+    "@vzn/vx-darwin-arm64": "0.0.85"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/tar-stream.ts

@@ -30,6 +30,14 @@ export class TarFormatError extends Error {
 }
 
 const BLOCK = 512
+/**
+ * An extended header's body is read whole, so its size is a claim on
+ * memory the stream has not paid for: a 1 GiB pax header zstd-compresses
+ * to ~32 KB and cost 2 GiB of RSS where a regular entry of that size
+ * streams in 32 MiB (L-1). A real one holds a path (≤ PATH_MAX) and a few
+ * numbers; a MiB is far past any writer's.
+ */
+const MAX_EXTENDED_HEADER = 1024 * 1024
 const decoder = new TextDecoder()
 
 function field(h: Uint8Array, off: number, len: number): string {
@@ -173,6 +181,11 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
     pendingPath = undefined
     pendingSize = undefined
 
+    if ((type === 'x' || type === 'L' || type === 'g') && size > MAX_EXTENDED_HEADER) {
+      throw new TarFormatError(
+        `extended header of ${size} bytes, past ${MAX_EXTENDED_HEADER} (a hostile archive?)`,
+      )
+    }
     if (type === 'x' || type === 'L') {
       // Extended header: applies to the NEXT entry only.
       const body = await src.exact(padded, 'an extended header')
@@ -182,7 +195,14 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
         const p = pax.get('path')
         if (p !== undefined) pendingPath = p
         const s = pax.get('size')
-        if (s !== undefined) pendingSize = Number(s)
+        if (s !== undefined) {
+          // Digits only: `Number` reads `0.5` and `-1`, and a fractional
+          // size moved the reader to a fractional offset.
+          if (!/^[0-9]+$/.test(s) || !Number.isSafeInteger(Number(s))) {
+            throw new TarFormatError(`bad pax size: ${JSON.stringify(s)}`)
+          }
+          pendingSize = Number(s)
+        }
       } else {
         pendingPath = field(body, 0, size)
       }

package/src/cli/why.ts

@@ -27,6 +27,26 @@ interface WhyArgs {
   error?: string
 }
 
+/**
+ * What to do about a changed key component, by the kind `cache/key-fold.ts`
+ * captures. Held to that file's kinds in both directions by
+ * `tests/why.test.ts`.
+ */
+export const WHAT_TO_DO: Readonly<Record<string, string>> = {
+  file: 'an edit re-runs by design; a file the task does not read belongs out of cache.inputs.files',
+  env: "the variable's value moved; one the task does not read belongs out of cache.inputs.env",
+  runtime: 'the command printed something else; drop timestamps and paths from its output',
+  'ws-runtime':
+    'the workspace command printed something else; drop timestamps and paths from its output',
+  forward: 'the arguments after -- differ; the same arguments share one entry',
+  package: "the project's package.json changed (a dependency, version or script)",
+  workspace:
+    'a lockfile or root manifest changed, which re-keys every task; a lockfile plugin keys each project on its own dependencies',
+  config: "the task's evaluated config changed (its vx.config or a file that imports)",
+  upstream: "a dependency's key moved; `vx why <that task>` says why",
+  plugin: "a key plugin's material changed; that plugin decides what it folds",
+}
+
 export function parseWhyArgs(args: readonly string[]): WhyArgs {
   const out: WhyArgs = { format: 'pretty' }
   for (let i = 0; i < args.length; i++) {
@@ -204,6 +224,11 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
               : `${e.before} → ${e.after}`
         lines.push(`    ${e.change.padEnd(7)} ${e.kind.padEnd(kindW)}  ${e.name}  ${beforeAfter}`)
       }
+      const kinds = [...new Set(diff.entries.map((e) => e.kind))].filter((k) => k in WHAT_TO_DO)
+      if (kinds.length > 0) {
+        lines.push('', '  what to do:')
+        for (const k of kinds) lines.push(`    ${k.padEnd(kindW)}  ${WHAT_TO_DO[k]}`)
+      }
     } else if (why.hashChanged === true) {
       lines.push(`  detail     ${diff.note}`)
     }

package/src/exec/executor.ts

@@ -140,10 +140,11 @@ export interface ExecuteRequest {
   readonly onStdout: (chunk: string) => void
   readonly onStderr: (chunk: string) => void
   /**
-   * Aborted when the run stops: Ctrl-C, SIGTERM, SIGHUP or an embedder's
-   * `RunOptions.signal`. An executor ends its work and returns; core waits
-   * for `execute` before its teardown, and a child an executor spawned is
-   * not one core can reach (item H-10).
+   * Aborted when the run stops (Ctrl-C, SIGTERM, SIGHUP or an embedder's
+   * `RunOptions.signal`) or when `timeoutMs` elapses. An executor ends its
+   * work and returns; core waits for `execute`, and a child an executor
+   * spawned is not one core can reach (H-10, H-12). A non-zero exit after
+   * the timeout's abort is recorded `timedOut`.
    */
   readonly signal?: AbortSignal
   /** See `RunOptions.liveChildren`: the run's SIGINT/SIGTERM registry. */

package/src/orchestrator/execute-task.ts

@@ -472,6 +472,27 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // (`--timeout`/`RunOptions.timeout` → `VX_TASK_TIMEOUT` → workspace
   // `timeout`, already collapsed into `args.timeout` by run.ts).
   const effectiveTimeout = step.timeout ?? args.timeout
+  // `signal` stops a plugin executor on the run's stop AND on
+  // `exec.timeout`: core cannot kill a process an executor spawned, so a
+  // declared timeout meant nothing on one that kept its own clock (H-12).
+  // The local executor keeps its own timer (it signals the process group).
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined
+  let timeoutFired = false
+  function requestSignal(): AbortSignal {
+    const stop = new AbortController()
+    const abort = (): void => stop.abort(args.stopSignal?.reason)
+    if (args.stopSignal?.aborted === true) abort()
+    else args.stopSignal?.addEventListener('abort', abort, { once: true })
+    if (effectiveTimeout !== undefined) {
+      clearTimeout(timeoutTimer)
+      timeoutFired = false
+      timeoutTimer = setTimeout(() => {
+        timeoutFired = true
+        stop.abort(new Error(`timed out after ${effectiveTimeout}ms`))
+      }, effectiveTimeout)
+    }
+    return stop.signal
+  }
 
   // When the task started, as a ns offset from run start — captured for
   // EVERY outcome (hits included) so the run-detail timeline reflects when
@@ -701,7 +722,7 @@ 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
+    let res = await args.executor
       .execute(req)
       .then((r: unknown) => {
         assertExecuteResult(args.executor.name, node.id, r)
@@ -713,7 +734,13 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         await sweepPlaceholders(placeholders)
         throw err
       })
+      .finally(() => clearTimeout(timeoutTimer))
     endExec()
+    // An executor that stopped on the timeout's abort exits non-zero; say
+    // why, so the frame, the retry line and `timedOut` read as a timeout.
+    if (timeoutFired && res.exitCode !== 0 && res.timedOut !== true) {
+      res = { ...res, timedOut: true }
+    }
     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
@@ -875,7 +902,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       onStdout: (chunk) => log.taskStdout(node, chunk),
       onStderr: (chunk) => log.taskStderr(node, chunk),
       ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
-      ...(args.stopSignal !== undefined ? { signal: args.stopSignal } : {}),
+      signal: requestSignal(),
       ...(effectiveTimeout !== undefined ? { timeoutMs: effectiveTimeout } : {}),
       ...(inputs !== undefined ? { inputs } : {}),
       ...(cfgCacheable ? { cacheKey: hash } : {}),

package/src/orchestrator/stable-keys.ts

@@ -81,8 +81,23 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   //     preliminary. A dependency this key folds needs no pass-through here:
   //     a keyed task with such a rewriter unfolded is unstable itself, and
   //     instability is inherited below.
+  //   - wideById: the subset of outputProjects whose writes are undeclared
+  //     (`undeclaredWriteReach`), so they may land anywhere in the project.
+  //     A declared-output producer reaches a same-project reader only where
+  //     its output globs can meet the reader's inputs (`outputsOf`, A-20).
   const projects = new ProjectIndex(args.nodes)
   const outputProjectsById = new Map<string, ProjectSet>()
+  const wideById = new Map<string, ProjectSet>()
+  // Every project's declared `outputs.files`, over all its tasks: a superset
+  // 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 ?? []
+    if (files.length === 0) continue
+    const list = outputsOf.get(n.projectName)
+    if (list === undefined) outputsOf.set(n.projectName, [...files])
+    else list.push(...files)
+  }
   const rewritersById = new Map<string, ProjectSet>()
   const unfoldedById = new Map<string, ProjectSet>()
   const wsRewriters = new Set<string>()
@@ -115,6 +130,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
     // Fold every dep's accumulated producers + the dep's own declared
     // outputs into this node's transitive-upstream producer sets.
     const outputProjects = projects.empty()
+    let wide: ProjectSet | undefined
     let rewriters: ProjectSet | undefined
     let unfolded: ProjectSet | undefined
     let folds: ((dep: string) => boolean) | undefined
@@ -126,6 +142,8 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       if (!depNode) continue
       const upstreamOfDep = outputProjectsById.get(dep)
       if (upstreamOfDep !== undefined) outputProjects.addAll(upstreamOfDep)
+      const wideOfDep = wideById.get(dep)
+      if (wideOfDep !== undefined) (wide ??= projects.empty()).addAll(wideOfDep)
       if (wsOutputUpstreamById.get(dep) === true) wsOutputUpstream = true
       const depOut = depNode.config.cache?.outputs
       if ((depOut?.files?.length ?? 0) > 0) outputProjects.add(depNode.projectName)
@@ -135,8 +153,10 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       // 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).
       const reach = undeclaredWriteReach(depNode, args.workspaceRoot)
-      if (reach === 'project') outputProjects.add(depNode.projectName)
-      else if (reach === 'workspace') wsOutputUpstream = true
+      if (reach === 'project') {
+        outputProjects.add(depNode.projectName)
+        ;(wide ??= projects.empty()).add(depNode.projectName)
+      } else if (reach === 'workspace') wsOutputUpstream = true
       const cached = depNode.config.cache !== undefined
       if (!cached && mayWriteFingerprint(depNode, args.workspaceRoot)) wsOutputUpstream = true
       if (!anyUnfolded) continue
@@ -172,6 +192,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       if (wsRewriterOfDep || rewritesWs) wsUnfoldedHere = true
     }
     outputProjectsById.set(id, outputProjects)
+    if (wide !== undefined) wideById.set(id, wide)
     wsOutputUpstreamById.set(id, wsOutputUpstream)
     if (rewriters !== undefined) rewritersById.set(id, rewriters)
     if (unfolded !== undefined) unfoldedById.set(id, unfolded)
@@ -207,6 +228,10 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
         unfolded === undefined ? outputProjects : unfolded.or(outputProjects),
         wsOutputUpstream || wsUnfoldedHere,
         dirByProject,
+        {
+          wide: unfolded === undefined ? wide : wide === undefined ? unfolded : wide.or(unfolded),
+          outputsOf,
+        },
       )
     if (unstable) unstableById.add(id)
 
@@ -292,12 +317,30 @@ export function dependsOnSiblingOutputs(
   upstreamOutputProjects: ProjectNames,
   hasWsOutputUpstream: boolean,
   dirByProject?: ReadonlyMap<string, string>,
+  sameProject?: {
+    /** The producers whose writes may land anywhere in their project. */
+    wide: ProjectNames | undefined
+    /** Each project's declared `outputs.files`, over all its tasks. */
+    outputsOf: ReadonlyMap<string, readonly string[]>
+  },
 ): boolean {
   const cache = node.config.cache
   // A cache-disabled task has no key to prefetch anyway; treat as
   // unstable-irrelevant (caller filters on cacheEnabled).
   if (cache === undefined) return false
-  if (upstreamOutputProjects.has(node.projectName)) return true
+  if (upstreamOutputProjects.has(node.projectName)) {
+    // A same-project producer whose writes are all declared reaches this
+    // task's inputs only where the globs can meet: a `test` reading `src/**`
+    // after a `build` writing `dist/**` keys the same before and after it,
+    // and classing it unstable hashed every such key twice more at 5,000
+    // projects (A-20). Undeclared writes, and a rewriter this key does not
+    // fold, may land anywhere: those stay project-wide.
+    if (sameProject === undefined || sameProject.wide?.has(node.projectName) === true) return true
+    const inputs = cache.inputs?.files
+    const outputs = sameProject.outputsOf.get(node.projectName) ?? []
+    if (inputs === undefined || outputs.length === 0) return true
+    if (workspaceInputsReach(inputs, outputs.map(literalPrefix))) return true
+  }
   // A root-anchored output is boundary-IGNORING by design, so it can land
   // inside THIS task's own project dir — where an ordinary project-relative
   // input reads it. Neither other clause sees that: `upstreamOutputProjects`
@@ -341,15 +384,8 @@ export function workspaceInputsReach(
 ): boolean {
   for (const raw of workspaceFiles) {
     if (raw.startsWith('!')) continue
-    const entry = normalizeGlob(raw)
-    const segments = entry.split('/')
-    const literal: string[] = []
-    for (const seg of segments) {
-      if (!isLiteralPattern(seg)) break
-      literal.push(seg)
-    }
-    if (literal.length === 0) return true
-    const prefix = literal.join('/')
+    const prefix = literalPrefix(raw)
+    if (prefix === '') return true
     for (const dir of dirs) {
       if (dir === '' || dir === '.') return true
       if (prefix === dir || prefix.startsWith(`${dir}/`) || dir.startsWith(`${prefix}/`))
@@ -359,6 +395,16 @@ export function workspaceInputsReach(
   return false
 }
 
+/** A glob's leading literal segments, `''` when its first holds a wildcard. */
+function literalPrefix(glob: string): string {
+  const literal: string[] = []
+  for (const seg of normalizeGlob(glob).split('/')) {
+    if (!isLiteralPattern(seg)) break
+    literal.push(seg)
+  }
+  return literal.join('/')
+}
+
 /** What the stability gate reads of a set of project names. */
 interface ProjectNames extends Iterable<string> {
   has(name: string): boolean