@vzn/vx 0.0.636 → 0.0.638

package/src/exec/env.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+import { ESSENTIAL_ENV } from '../util/index.js'
 
 // Build the environment exposed to a task.
 //
@@ -9,37 +10,6 @@ import path from 'node:path'
 //   3. define: explicit name=value pairs from the task config.
 //   4. binPaths prepended to PATH (after all the above resolve PATH).
 
-/**
- * Exported so the schema doc's enumeration of it can be PINNED against the
- * real list: a hand-copied allowlist is how the two drift, and a reader
- * asking "what does my build script actually see?" is asking a
- * security-shaped question that a stale list answers wrongly.
- */
-export const ESSENTIAL_ENV: readonly string[] = [
-  'PATH',
-  'HOME',
-  'SHELL',
-  'USER',
-  'LOGNAME',
-  'TMPDIR',
-  'TEMP',
-  'TMP',
-  'LANG',
-  'LC_ALL',
-  'LC_CTYPE',
-  'TERM',
-  'COLORTERM',
-  'FORCE_COLOR',
-  'NO_COLOR',
-  'CI',
-  'NODE_OPTIONS',
-  // Where corepack and pnpm keep their own binaries, as HOME is: a machine
-  // path, never task output. Without them a corepack shim re-downloads its
-  // manager (offline or sandboxed: fails) and pnpm loses its global dir.
-  'COREPACK_HOME',
-  'PNPM_HOME',
-]
-
 /**
  * The two variables vx sets on every task it spawns, over the layers
  * above: the workspace root the run is in and the `project#task` running.

package/src/exec/executor.ts

@@ -73,12 +73,8 @@ export interface TaskInputs {
     readonly hash: string
     readonly outputs: readonly string[]
   }>
-  /** Digest of the project's own `package.json` (folded even when no glob lists it). */
-  readonly packageJsonDigest: string
   /** Digest of the resolved task config. */
   readonly configDigest: string
-  /** The workspace fingerprint (root manifests + lockfile). */
-  readonly workspaceFingerprint: string
 }
 
 export interface ExecuteRequest {
@@ -146,7 +142,7 @@ export interface ExecuteRequest {
    * work and returns: a child an executor spawned is not one core can
    * reach (H-10, H-12). One already aborted is work not to start (B-55).
    * Any exit after the timeout's abort, a 0 included, is a timeout. Core
-   * waits the kill grace (`VX_KILL_GRACE_MS`, 2 s) after the abort, then
+   * waits the kill grace (`VX_RUN_KILL_GRACE`, 2 s) after the abort, then
    * settles the attempt without `execute` and abandons it (H-14).
    */
   readonly signal?: AbortSignal

package/src/exec/kill-tree.ts

@@ -11,7 +11,7 @@
 // takes even that.
 
 import { closeSync, readdirSync, readFileSync, writeSync } from 'node:fs'
-import { procfsIsOwn, taskShell } from '../util/index.js'
+import { helperEnv, procfsIsOwn, taskShell } from '../util/index.js'
 
 export type Child = ReturnType<typeof Bun.spawn>
 
@@ -104,6 +104,7 @@ function startGuard(): void {
   try {
     const guard = Bun.spawn([taskShell(), '-c', GUARD_SCRIPT], {
       argv0: 'vx-group-guard',
+      env: helperEnv(),
       stdio: ['ignore', 'ignore', 'ignore', 'pipe'],
       // Out of vx's group, so a Ctrl-C at the terminal leaves it to the
       // pipe; vx's own teardown owns that path.

package/src/exec/sandbox-runtime.ts

@@ -62,6 +62,7 @@ import {
 import {
   BUN_GLOB_WILDCARDS,
   executablePath,
+  helperEnv,
   taskShell,
   grantPrefix,
   isTmpdirRefusal,
@@ -1806,10 +1807,11 @@ function spawnHostBridges(ports: readonly number[], tag: string): void {
             ? Bun.spawn(argv, {
                 stdio: ['ignore', 'ignore', 'ignore'],
                 detached: true,
+                env: helperEnv(),
               })
             : Bun.spawn(
                 [taskShell(), '-c', `${guardLine(3)}exec ${argv.map(shellQuote).join(' ')}`],
-                { stdio: ['ignore', 'ignore', 'ignore', guard], detached: true },
+                { stdio: ['ignore', 'ignore', 'ignore', guard], detached: true, env: helperEnv() },
               ),
         ),
       )
@@ -2691,6 +2693,15 @@ function expandGrants(
       // names a wall literally never reaches this loop and stays, and one
       // spelled with escaped brackets names it as surely.
       if (namedPath(p) === undefined && walls.some((w) => atOrUnder(real, w))) continue
+      // A write hit that HOLDS a wall would bind it writable: `.*` in a root
+      // project matched `.vx`, which holds the cache. A read hit is punched
+      // around it instead (`punchWalls`).
+      if (
+        unmatched !== undefined &&
+        namedPath(p) === undefined &&
+        walls.some((w) => atOrUnder(w, real))
+      )
+        continue
       out.push(abs)
       hits++
     }

package/src/exec/sandbox-violations.ts

@@ -744,6 +744,9 @@ export function refusedConnections(records: readonly string[]): SandboxViolation
   }))
 }
 
+/** Write syscalls that act on a path's last component, not what a link there names. */
+const NAME_SYSCALL = /^(?:symlink|unlink|rename|rmdir|mknod|link)/
+
 /**
  * The writes SRT's Linux observer saw that this task's binds do not cover.
  * The observer reports every write-intent syscall as `deny <syscall>
@@ -774,7 +777,12 @@ export function refusedWrites(
     // `5>out.log` in the project reported a write to `out.log` and failed
     // a clean task (2026-10-02).
     if (/^\/(?:dev|proc)\//.test(raw)) continue
-    const abs = toRealPath(raw)
+    // These act on the name itself, never through it: resolving the link
+    // `ln -s ../src/a.ts dist/a` just made judged the write by `src/a.ts`,
+    // and a clean task failed with a fix that granted `write: ['src/']`.
+    const abs = NAME_SYSCALL.test(syscall)
+      ? path.join(toRealPath(path.dirname(raw)), path.basename(raw))
+      : toRealPath(raw)
     if (isUnderAny(abs, binds) || underGlob(abs, globs)) continue
     // A directory a write bind lies in exists, since bwrap made it to mount
     // the bind: `mkdir -p node_modules/.cache/tool` under a grant of

package/src/graph/dependency-spec.ts

@@ -11,7 +11,7 @@ export type DependencySpec =
 
 export class DependencySpecError extends Error {
   constructor(raw: string, message: string) {
-    super(`Invalid dependency spec "${raw}": ${message}`)
+    super(`invalid dependsOn "${raw}": ${message}`)
   }
 }
 

package/src/graph/index.ts

@@ -24,6 +24,7 @@ export {
   declaredTask,
   excludeDependencies,
   expandRequested,
+  type GraphRules,
   isGroupTask,
   markSurfacedDeps,
   outputsOverlap,

package/src/graph/priorities.ts

@@ -161,7 +161,7 @@ export function computeReverseDepCount(nodes: Map<string, TaskNode>): Map<string
 
 /**
  * The ready-queue baseline a workspace may pick in place of the default
- * (`schedule` in vx.workspace.ts). Each ranks with no timings; a `schedule`
+ * (`schedule` in .vx/workspace.ts). Each ranks with no timings; a `schedule`
  * plugin's weights still sort above it, and it breaks their ties.
  *   - `most-work`: transitive dependents (`computeReverseDepCount`), the default.
  *   - `critical-path`: steps on the longest chain of dependents below a task.

package/src/graph/scheduler.ts

@@ -121,14 +121,14 @@ export interface TaskOutcome {
   groupUpstream?: readonly TaskOutcome[]
   /**
    * This task RAN over inputs its key no longer describes: one moved while
-   * it ran, the workspace fingerprint moved, or an upstream carried this
+   * it ran, a claimed root file moved, or an upstream carried this
    * mark. Its save was withheld, and its outputs are not what `hash` names,
    * so a dependant that folds `hash` saves nothing either (A-12).
    */
   unkeyed?: true
   /**
    * The run's cache policy read and wrote nothing (`--no-cache`,
-   * `--cache=local:`): no cache answered for this task, so a run of it is
+   * `--cache-policy=local:`): no cache answered for this task, so a run of it is
    * `no-cache`, not a miss. Set by `run()`; `ranNoCache` reads it.
    */
   cacheOff?: true
@@ -152,19 +152,33 @@ export interface TaskOutcome {
    * bounded to its first 8 KiB and last 56 KiB. The run's history keeps it.
    */
   failedOutput?: string
+  /**
+   * When the run keeps its bytes in a remote, a task that ran and saved no
+   * entry (failed, or uncached): its whole output as `encodeOutputLog`
+   * stores it, secrets masked, at the entry's bounds.
+   */
+  runLog?: string
   /**
    * On a failed persistent task: why it never became ready — the readiness
    * deadline fired, the child exited first (`exitCode` is then its own), or
    * the spawn itself failed. Every label reads this instead of the exit.
    */
   notReady?: 'timeout' | 'exited' | 'spawn'
+  /**
+   * The input that changed while the command ran, failing the task under
+   * `inputStability.severity: 'error'` (workspace-relative; '' when vx
+   * could not name it). The exit is vx's 1; the label reads this instead.
+   */
+  inputMoved?: string
   /** Executor-reported placement label (`ExecuteResult.where`) — set only
    *  when the task ran somewhere other than this host. Telemetry-only. */
   where?: string
   /** `'deferred'` when the task's outputs were left in the remote store
-   *  (`--download=none`) instead of landing on this machine. Absent for
+   *  (`--cache-download=none`) instead of landing on this machine. Absent for
    *  every ordinary outcome. Telemetry-only. */
   outputs?: 'deferred'
+  /** The task ran here and its result went to the cache. The footer's `↑`. */
+  saved?: true
   /**
    * v11 analytics: hrtime span relative to the parent run's t=0.
    * Lets downstream analytics reconstruct the actual parallel timeline
@@ -183,7 +197,7 @@ export interface TaskOutcome {
   restored?: boolean
   /**
    * How many times the task executed this run, when `exec.retries` /
-   * `--retry` re-ran failed attempts. Set only when > 1 — a plain
+   * `--retries` re-ran failed attempts. Set only when > 1 — a plain
    * single-attempt run carries nothing. Not persisted; telemetry-side
    * flaky detection reads it off the outcome stream.
    */
@@ -216,6 +230,12 @@ export interface TaskOutcome {
     systemInfo?: string[]
     /** Credential paths denied and left out of the grants: an agent applies the fix as given. */
     withheld?: string[]
+    /**
+     * Reads of the project the task's `cache.inputs.files` does not match:
+     * add them there too when the output depends on them, or a hit replays
+     * output built from an older copy. Cached tasks only.
+     */
+    inputs?: string[]
   }
 }
 
@@ -267,7 +287,7 @@ export interface ScheduleOptions {
    * outcome lands. Absent = stderr. The run gives it the task's own
    * stderr, so its frame carries the reason.
    */
-  onError?: (node: TaskNode, line: string) => void
+  onError?: (node: TaskNode, line: string, err: unknown) => void
   /**
    * What an outcome still owes before its dependents may start — a cache
    * save that runs off the execution slot (the orchestrator's save lane):
@@ -294,7 +314,7 @@ export interface ScheduleOptions {
    */
   priorities?: ReadonlyMap<string, number>
   /**
-   * The baseline ranking under `priorities` (`schedule` in vx.workspace.ts).
+   * The baseline ranking under `priorities` (`schedule` in .vx/workspace.ts).
    * Undefined or `most-work` is the reverse-deps count above.
    */
   strategy?: ScheduleStrategy
@@ -1027,7 +1047,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
             }
             try {
               if (options.onError === undefined) process.stderr.write(line)
-              else options.onError(node, line)
+              else options.onError(node, line, err)
             } catch {
               process.stderr.write(line)
             }

package/src/graph/task-graph.ts

@@ -7,6 +7,7 @@ import {
   splitNegations,
   staticPrefix,
   taskGlob,
+  refusal,
   UserError,
   wholeSubtreePrefixes,
 } from '../util/index.js'
@@ -288,10 +289,16 @@ export interface BuildGraphOptions {
    * with other root-anchored ones.
    */
   workspaceRoot?: string
-  /** The workspace's `rules`; each is on unless set to `false`. */
-  rules?: WorkspaceRules | undefined
+  /** The workspace's `run.rules`; each is on unless set to `false`. */
+  rules?: GraphRules | undefined
 }
 
+/**
+ * `run.rules` as the graph applies them. `locked`: a run, which never
+ * checks them; `vx lock` and `vx lock --check` do (owner, 2026-10-14).
+ */
+export type GraphRules = WorkspaceRules & { readonly locked?: boolean }
+
 /**
  * The refusal of a literal `^name` that no project in the workspace
  * declares: it has no holder anywhere, so it can only be a typo (nx#32779
@@ -301,7 +308,7 @@ export interface BuildGraphOptions {
  */
 export function undeclaredDepsError(taskId: string, name: string): UserError {
   return new UserError(
-    `Task ${taskId} depends on ^${name} but no project in the workspace declares ${name}`,
+    `${taskId}: dependsOn ^${name} but no project in the workspace declares ${name}`,
     'VX_E_DEPENDS_ON',
   )
 }
@@ -493,7 +500,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       spec = parseDependencySpec(raw)
     } catch (err) {
       if (err instanceof DependencySpecError) {
-        throw new UserError(`Task ${id}: ${err.message}`, 'VX_E_DEPENDS_ON')
+        throw new UserError(`${id}: ${err.message}`, 'VX_E_DEPENDS_ON')
       }
       throw err
     }
@@ -505,19 +512,19 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     // they name a namespace of tasks to add (Nx 19.5 parity).
     if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') {
       throw new UserError(
-        `Task ${id}: dependsOn does not accept bare wildcards (got "${raw}")`,
+        `${id}: dependsOn does not accept bare wildcards (got "${raw}")`,
         'VX_E_DEPENDS_ON',
       )
     }
     if (spec.negated) {
       throw new UserError(
-        `Task ${id}: dependsOn does not accept negation (got "${raw}")`,
+        `${id}: dependsOn does not accept negation (got "${raw}")`,
         'VX_E_DEPENDS_ON',
       )
     }
     if (spec.kind === 'cross' && (isTaskPattern(spec.task) || isTaskPattern(spec.project))) {
       throw new UserError(
-        `Task ${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
+        `${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
         'VX_E_DEPENDS_ON',
       )
     }
@@ -537,7 +544,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         // doesn't resolve in this project.
         if (!visit(frame, projectName, spec.task, false)) {
           throw new UserError(
-            `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
+            `${id}: dependsOn ${taskId(projectName, spec.task)} but no such task is declared`,
             'VX_E_DEPENDS_ON',
           )
         }
@@ -570,6 +577,17 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       // last (`resolveDeferred`), and a walk that meets it on a cycle takes
       // the edge and goes on past it, so the builds it could not depend on
       // still come first.
+      //
+      // With no edge source every `^` resolves to nothing and its upstream
+      // folds into no key: a stale hit, green. With one, a project with no
+      // deps is a leaf. The default `build`'s `^build` is no exception: a
+      // task behind it would fold no upstream either.
+      if (!packageGraph.edgeSource) {
+        throw new UserError(
+          `${id}: ^${spec.task} needs project edges; add pnpm()/bun()/npm()/yarn() or a plugin that returns \`deps\``,
+          'VX_E_DEPENDS_ON',
+        )
+      }
       const visited = new Set<string>([projectName])
       if (!isTaskPattern(spec.task)) {
         const held = walkHolders(frame, spec.task, visited, projectName)
@@ -602,11 +620,11 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         // The loader spells `//` as the root project's name when there is one.
         if (spec.project === '//')
           throw new UserError(
-            `Task ${id} depends on //#${spec.task}, Turbo's root package, but the workspace root is no project here: give it a package.json name and a vx.config with that task`,
+            `${id}: dependsOn //#${spec.task}, the workspace root's task, but the root declares no such task: add a vx.config at the root declaring it and run \`vx lock\``,
             'VX_E_DEPENDS_ON',
           )
         throw new UserError(
-          `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+          `${id}: dependsOn ${taskId(spec.project, spec.task)} but no such project or task is declared`,
           'VX_E_DEPENDS_ON',
         )
       }
@@ -746,7 +764,7 @@ function reachingTo(nodes: Map<string, TaskNode>, target: string): Set<string> {
 export function checkGraph(
   nodes: Map<string, TaskNode>,
   workspaceRoot?: string,
-  rules?: WorkspaceRules,
+  rules?: GraphRules,
 ): void {
   for (const [key, node] of nodes) {
     if (node.id !== key) {
@@ -762,8 +780,12 @@ export function checkGraph(
   }
   for (const node of nodes.values()) refuseSelfClean(node)
   detectCycle(nodes)
-  detectOutputCollisions(nodes, workspaceRoot, rules?.exclusiveOutputs !== false)
-  if (rules?.upfrontKeys !== false) detectInputOverlaps(nodes, workspaceRoot)
+  const exclusive = rules?.exclusiveOutputs !== false
+  const locked = rules?.locked === true
+  // Under a lock an exclusive graph has no overlap to mark; a non-exclusive
+  // one still needs the addition marks the walk derives.
+  if (!locked || !exclusive) detectOutputCollisions(nodes, workspaceRoot, exclusive)
+  if (rules?.upfrontKeys !== false && !locked) detectInputOverlaps(nodes, workspaceRoot)
 }
 
 /**
@@ -948,6 +970,19 @@ function witnessed(a: string, b: string): boolean {
       if (ga.match(candidate) && gb.match(candidate)) return true
     }
   }
+  // Each glob filled in whole, every wildcard a name and `**` one level or
+  // none: `**/dist/**` beside `**/*` meets at `x/dist/x`, a path neither
+  // last segment builds (solid, M 2026-10-15).
+  for (const glob of [a, b]) {
+    const segs = glob.split('/')
+    if (segs.some((s) => /[[\]{}()!+@]/.test(s))) continue
+    for (const drop of [false, true]) {
+      const candidate = segs
+        .flatMap((s) => (s === '**' ? (drop ? [] : ['x']) : [s.replace(/\*+|\?/g, 'x')]))
+        .join('/')
+      if (candidate !== '' && ga.match(candidate) && gb.match(candidate)) return true
+    }
+  }
   return false
 }
 
@@ -1352,13 +1387,13 @@ function neverWritesLocally(n: TaskNode): boolean {
 }
 
 /**
- * The way out of an edge-ordered overlap under `rules.exclusiveOutputs`: an
+ * The way out of an edge-ordered overlap under `run.rules.exclusiveOutputs`: an
  * ordered pair is correct (the addition shape, item 588), only slower to
  * clean and restore, so the rule may be turned off.
  */
 const EXCLUSIVE_OUTPUTS_FIX =
-  'Give each task its own output path, or set rules: { exclusiveOutputs: false } in ' +
-  "vx.workspace.ts to let a dependant add to its upstream's outputs."
+  'Give each task its own output path, or set run.rules.exclusiveOutputs: false in ' +
+  ".vx/workspace.ts to let a dependant add to its upstream's outputs."
 
 function collide(
   a: TaskNode,
@@ -1383,11 +1418,22 @@ function collide(
       // dependant runs after its upstream and adds to that tree, so the
       // order is fixed and the dependant's own set can be told apart from
       // what it found. Marked on both, and the pair is allowed when
-      // `rules.exclusiveOutputs` is off (X-53). Without an edge the two run
+      // `run.rules.exclusiveOutputs` is off (X-53). Without an edge the two run
       // in either order, and the refusal below stands.
       const [up, down] = reaches(b.id, a.id) ? [a, b] : reaches(a.id, b.id) ? [b, a] : []
+      const parts = {
+        headline: `${a.id} and ${b.id} both write ${ga === gb ? ga : `${ga} / ${gb}`}`,
+        ...(field === 'files' ? {} : { what: ['in cache.outputs.workspaceFiles'] }),
+        why: "vx clears a task's outputs before it runs, so one deletes the other's",
+      }
       if (up !== undefined && exclusive)
-        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`, 'VX_E_OUTPUT_OVERLAP')
+        throw refusal(
+          {
+            ...parts,
+            fix: 'give each task its own output path, or set run.rules.exclusiveOutputs: false in .vx/workspace.ts',
+          },
+          { code: 'VX_E_OUTPUT_OVERLAP', message: `${head}. ${EXCLUSIVE_OUTPUTS_FIX}` },
+        )
       if (up !== undefined && down !== undefined) {
         const downGlobs = splitNegations(
           (field === 'files'
@@ -1398,9 +1444,12 @@ function collide(
         ;(up.outputsAddedToBy ??= []).push(...(downGlobs ?? []))
         return
       }
-      throw new UserError(
-        `${head} and the run still reports success. Give each task its own output path.`,
-        'VX_E_OUTPUT_OVERLAP',
+      throw refusal(
+        { ...parts, fix: 'give each task its own output path' },
+        {
+          code: 'VX_E_OUTPUT_OVERLAP',
+          message: `${head} and the run still reports success. Give each task its own output path.`,
+        },
       )
     }
   }
@@ -1504,7 +1553,7 @@ interface Side {
 }
 
 /**
- * `rules.upfrontKeys` (X-54): refuse a task whose input globs can match
+ * `run.rules.upfrontKeys` (X-54): refuse a task whose input globs can match
  * another task's declared outputs. Such a key reads bytes a producer writes
  * this run, so it is not known until the producer ran (`stable-keys.ts`
  * keeps it waiting); refused, every key reads only what no task writes and
@@ -1677,7 +1726,7 @@ function readsOutputs(
           `${writer.node.id}'s output ${JSON.stringify(shown)} — a task's key must not read ` +
           `another task's outputs (the dependency's key already cascades through dependsOn). ` +
           `Exclude it: add ${JSON.stringify(`!${out}`)} to ${reader.node.id}'s ` +
-          `cache.inputs.${field}, or set rules: { upfrontKeys: false } in vx.workspace.ts to ` +
+          `cache.inputs.${field}, or set run.rules.upfrontKeys: false in .vx/workspace.ts to ` +
           `let it wait for its producer.`,
         'VX_E_INPUT_IS_OUTPUT',
       )
@@ -1725,7 +1774,10 @@ function detectCycle(nodes: Map<string, TaskNode>): void {
           for (let i = 0; i < stack.length; i += 2) path.push(idsArr[stack[i]!]!)
           const startInPath = path.indexOf(idsArr[depIdx]!)
           const cycle = [...path.slice(startInPath), idsArr[depIdx]!].join(' -> ')
-          throw new UserError(`Cycle detected in task graph: ${cycle}`, 'VX_E_CYCLE')
+          throw new UserError(
+            `dependsOn cycle: ${cycle} — remove one edge of the loop`,
+            'VX_E_CYCLE',
+          )
         }
         color[depIdx] = GRAY
         stack.push(depIdx, 0)